feat(pat navigation): Add scroll-marker functionality.

The pattern now sets current and in-view classes on the navigation and
the content when scrolling to hash-link targets.

Author: thet

src/pat/navigation/documentation.md

@@ -5,12 +5,21 @@ Marks navigation paths with "in-path" and "current" classes.
 
 ## Documentation
 
-The "in-path" and "current" classes and the "item-wrapper" are configurable.
+When clicking on a navigation item this one will always get the `current-class`.
+When loading a page and the browser's url matches a navigation item's href value, this one will get the `current-class`.
+Any navigation items in it's path will get the `in-path-class`.
+
+### scroll-marker functionality
+
+When a content items with an id which matches a hash-url in the navigation are scrolled into view then the corresponding navigation items will get the `in-view-class`.
+One matching navigation item will get the `current-class` and the corresponding content item will get the `current-content-class`, depending on the algorithm in use as described in the [pat-scroll-marker documentation](../scroll-marker/documentation.md).
+The default is that the content item in view, which top position is neares to the middle of the scrolling container will be the current item.
+
+### Automatic loading of items
 
 You can automatically load the navigation item marked with the `current` class by adding the class `navigation-load-current` along with `pat-navigation` on the pattern element.
 This would invoke a `click` event on the current navigation item and that can be used to load content via `pat-inject`.
 
-For examples see index.html.
 
 ### Option reference
 
@@ -19,6 +28,12 @@ The available options are:
 
 | Field           | Default              | Options        | Description                                                                                                                                                            |
 | --------------- | -------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `item-wrapper`  | `li`                 | CSS selector   | The DOM element which wraps each menu item. This is used to set the "current" and "in-path" classes also on the wrapper element. If empty, no wrapper element is used. |
-| `in-path-class` | `navigation-in-path` | CSS class name | Class name, which is set on item-wrapper elements if nested menu items are within the current path.                                                                    |
-| `current-class` | `current`            | CSS class name | Class name, which is set on item-wrapper or items if they are the currently selected menu option.                                                                      |
+| item-wrapper    | li                 | CSS selector   | The DOM element which wraps each menu item. This is used to set the "current" and "in-path" classes also on the wrapper element. If empty, no wrapper element is used.   |
+| in-path-class   | navigation-in-path | CSS class name | Class name, which is set on item-wrapper elements if nested menu items are within the current path.                                                                      |
+| current-class   | current            | CSS class name | Class name, which is set on item-wrapper or items if they are the currently selected menu option or - for hash links - when it's corresponding content item is in view.  |
+| in-view-class   | in-view       |        | String            | CSS class for a navigation item when it's corresponding content item is in view. |
+| current-content-class | current |        | String            | CSS class for a content item when it is the current one. |
+| scroll-marker-side            | top           | top, bottom, middle, auto  | String | Side of element that scrolls. This is used to calculate the current item. The defined side of the element will be used to calculate the distance baseline. If this is set to "auto" then one of the "top" or "bottom" positions are used, depending on which one is nearer to the distance baseline. |
+| scroll-marker-distance        | 50%           |        | String            | Distance from side of scroll box. any amount in px or %. This is used to calculate the current item. The nearest element to the distance-baseline measured from the top of the container will get the current class. |
+| scroll-marker-visibility      |               | null, most-visible | String | Visibility of element in scroll box. This is used to calculate the current item. If "most-visible" is set, the element which is most visible in the scroll container gets the current class. If more elements have the same visibility ratio, the other conditions are used to calculate the current one. |
+

src/pat/navigation/navigation.js

@@ -1,16 +1,27 @@
 import $ from "jquery";
 import { BasePattern } from "../../core/basepattern";
 import Parser from "../../core/parser";
+import ScrollMarker from "../scroll-marker/scroll-marker";
 import logging from "../../core/logging";
 import events from "../../core/events";
 import registry from "../../core/registry";
+import utils from "../../core/utils";
 
 const log = logging.getLogger("navigation");
 
 export const parser = new Parser("navigation");
 parser.addArgument("item-wrapper", "li");
 parser.addArgument("in-path-class", "navigation-in-path");
+parser.addArgument("in-view-class", "in-view");
 parser.addArgument("current-class", "current");
+parser.addArgument("current-content-class", "navigation-current");
+
+// Side of element that scrolls. top/bottom/middle/auto (default 'top')
+parser.addArgument("scroll-marker-side", "top", ["top", "bottom", "middle", "auto"]);
+// Distance from side of scroll box. any amount in px or % (default '50%')
+parser.addArgument("scroll-marker-distance", "50%");
+// Visibility of element in scroll box. most-visible or null (default null)
+parser.addArgument("scroll-marker-visibility", null, [null, "most-visible"]);
 
 class Pattern extends BasePattern {
     static name = "navigation";
@@ -24,6 +35,26 @@ class Pattern extends BasePattern {
 
         this.init_listeners();
         this.init_markings();
+
+        this.scroll_marker = new ScrollMarker(this.el, {
+            "current-class": this.options["current-class"],
+            "current-content-class": this.options["current-content-class"],
+            "in-view-class": this.options["in-view-class"],
+            "side": this.options["scroll-marker-side"],
+            "distance": this.options["scroll-marker-distance"],
+            "visibility": this.options["scroll-marker-visibility"],
+        });
+
+        this.debounced_scroll_marker_enabler = utils.debounce(() => {
+            log.debug("Enable scroll-marker.");
+            this.scroll_marker.set_current_disabled = false;
+            events.remove_event_listener(
+                this.scroll_marker.scroll_container === window
+                    ? document
+                    : this.scroll_marker.scroll_container,
+                "pat-navigation__scroll_marker_enable"
+            );
+        }, 200);
     }
 
     /**
@@ -42,6 +73,20 @@ class Pattern extends BasePattern {
                     this.clear_items();
                     // Mark the current item
                     this.mark_current(ev.target);
+
+                    // Disable scroll marker to set the current class after
+                    // clicking in the menu and scrolling to the target.
+                    log.debug("Disable scroll-marker.");
+                    this.scroll_marker.set_current_disabled = true;
+                    this.debounced_scroll_marker_enabler();
+                    events.add_event_listener(
+                        this.scroll_marker.scroll_container === window
+                            ? document
+                            : this.scroll_marker.scroll_container,
+                        "scroll",
+                        "pat-navigation__scroll_marker_enable",
+                        this.debounced_scroll_marker_enabler
+                    );
                 }
             }
         );
@@ -124,6 +169,22 @@ class Pattern extends BasePattern {
             wrapper?.classList.add(this.options["current-class"]);
             this.mark_in_path(wrapper || item);
             log.debug("Statically set current item marked as current", item);
+
+            // Clear all previous current content items.
+            for (const it of [
+                ...document.querySelectorAll(
+                    `.${this.options["current-content-class"]}`
+                ),
+            ]) {
+                it.classList.remove(this.options["current-content-class"]);
+            }
+            // Mark the current content item, if it is a hash link.
+            if (item.matches("a[href^='#']")) {
+                const content_item = document.querySelector(item.getAttribute("href"));
+                if (content_item) {
+                    content_item.classList.add(this.options["current-content-class"]);
+                }
+            }
         }
     }