@ulu/frontend-vue 0.5.15 → 0.6.0

package/lib/components/systems/scroll-anchors/useScrollAnchors.js

@@ -1,5 +1,6 @@
 import { onMounted, onUnmounted, nextTick, watch } from "vue";
 import { getScrollParent } from "@ulu/utils/browser/dom.js";
+import { debounce } from "@ulu/utils/performance.js";
 
 /**
  * The main composable that contains the core "engine" for the Scroll Anchors system.
@@ -10,96 +11,236 @@ import { getScrollParent } from "@ulu/utils/browser/dom.js";
  */
 export function useScrollAnchors({ sections, props, emit, componentElRef }) {
   let observer = null;
+  let lastScrollY = 0;
+  let lastScrollDirection = 'down';
+  let scrollRoot = null;
+  let isObserverRefresh = true;
 
+  /**
+   * Helper to quickly get the index of a section by its DOM element
+   */
   function getSectionIndex(el) {
     return sections.value.findIndex(({ element }) => el === element);
   }
 
+  /**
+   * Standardizes state assignments (active, forward/reverse animations) for a specific section
+   */
+  function setSectionState(section, isActive, scrollDirection = 'down') {
+    if (!section) return;
+    const direction = scrollDirection === 'down' ? 'forward' : 'reverse';
+    if (isActive) {
+      section.active = true;
+      section.inactiveFrom = null;
+      section.activeFrom = direction;
+    } else {
+      if (section.active) {
+        section.inactiveFrom = direction;
+        section.activeFrom = null;
+      }
+      section.active = false;
+    }
+  }
+
+  /**
+   * Loops through all sections and forces them to inactive, optionally skipping one target
+   */
   function removeActive(except = null, scrollDirection = 'down') {
     sections.value.forEach(s => {
       if (s !== except) {
-        if (s.active) {
-          s.inactiveFrom = scrollDirection === 'down' ? 'forward' : 'reverse';
-          s.activeFrom = null;
-        }
-        s.active = false;
+        setSectionState(s, false, scrollDirection);
       }
     });
   }
 
+  /**
+   * Safe wrapper to clear other sections, make a new target active, and emit the change event
+   */
+  function setSectionActive(section, scrollDirection) {
+    if (section && !section.active) {
+      if (props.debug) console.log("Activate:", section.title);
+      nextTick(() => {
+        removeActive(section, scrollDirection);
+        setSectionState(section, true, scrollDirection);
+        emit("section-change", { section, sections: sections.value, active: true });
+      });
+    }
+  }
+
+  /**
+   * Clears the currently active item and emits a deactivation event (used at top/bottom scroll edges)
+   */
+  function deactivateAll(scrollDirection, debugMsg) {
+    const activeSection = sections.value.find(s => s.active);
+    if (activeSection) {
+      if (props.debug && debugMsg) console.log(debugMsg, activeSection.title);
+      nextTick(() => {
+        removeActive(null, scrollDirection);
+        emit("section-change", { section: activeSection, sections: sections.value, active: false });
+      });
+    }
+  }
+
+  /**
+   * Resolves the scrolling container element based on options, DOM hierarchy, or defaults to window
+   */
+  function getScrollRoot() {
+    let root = null;
+    if (props.observerOptions && props.observerOptions.root !== undefined) {
+      root = props.observerOptions.root;
+    } else if (componentElRef.value) {
+      root = getScrollParent(componentElRef.value);
+      if (root === document.scrollingElement) {
+        root = null;
+      }
+    }
+    return root || window;
+  }
+
+  /**
+   * Debounced callback attached to the scroll listener.
+   * Rebuilding the observer ensures a fresh set of entries representing the true layout when scrolling stops.
+   */
+  const refreshObserver = debounce(() => {
+    if (props.debug) console.log("New Observer (debounced/check)");
+    if (observer) {
+      observer.disconnect();
+      observer = null;
+    }
+    createObserver();
+    observeItems();
+  }, 100);
+
+  function setupScrollListener() {
+    removeScrollListener();
+    scrollRoot = getScrollRoot();
+    if (scrollRoot) {
+      scrollRoot.addEventListener('scroll', refreshObserver, { passive: true });
+    }
+  }
+
+  function removeScrollListener() {
+    if (scrollRoot) {
+      scrollRoot.removeEventListener('scroll', refreshObserver);
+      scrollRoot = null;
+    }
+  }
+
+  /**
+   * Primary logic core. Creates the IntersectionObserver and handles state changes.
+   */
   function createObserver() {
-    let lastScrollY = 0;
-    let isInitialObservation = true;
+    isObserverRefresh = true;
 
     const onObserve = (entries) => {
       const { root } = observer;
       const currentScrollY = root ? root.scrollTop : document.documentElement.scrollTop || window.scrollY;
 
-      if (props.debug) {
-        console.group("useScrollAnchors: onObserve");
-        console.log("Observer:", observer);
-        console.log("Last/Current Y:", `${ lastScrollY }/${ currentScrollY }`);
-        console.log("Entries:", entries.map(e => ({ el: e.target, is: e.isIntersecting })));
+      // Determine the direction of the scroll
+      let scrollDirection = lastScrollDirection;
+      if (currentScrollY > lastScrollY) {
+        scrollDirection = 'down';
+      } else if (currentScrollY < lastScrollY) {
+        scrollDirection = 'up';
       }
       
-      if (isInitialObservation && props.firstItemActive) {
-        if (props.debug) console.log("Initial observation, respecting `firstItemActive`.");
-        isInitialObservation = false;
-        lastScrollY = currentScrollY;
-        if (props.debug) console.groupEnd();
-        return;
+      if (props.debug) {
+        console.groupCollapsed(`Scroll: ${lastScrollY} -> ${currentScrollY} (${scrollDirection})`);
+        console.table(entries.map(e => ({ 
+          el: e.target.id || e.target.tagName, 
+          int: e.isIntersecting,
+          ratio: e.intersectionRatio.toFixed(2)
+        })));
       }
-      isInitialObservation = false;
 
-      const scrollDirection = currentScrollY > lastScrollY ? 'down' : 'up';
       lastScrollY = currentScrollY;
-      if (props.debug) console.log(`Scroll direction: ${scrollDirection}`);
+      lastScrollDirection = scrollDirection;
 
       const intersectingEntries = entries.filter(entry => entry.isIntersecting);
-      if (props.debug) console.log("Intersecting entries:", intersectingEntries.map(e => e.target));
 
+      // Strategy 1: Standard intersection detection
       if (intersectingEntries.length > 0) {
         intersectingEntries.sort((a, b) => getSectionIndex(a.target) - getSectionIndex(b.target));
         
+        // Choose the most appropriate intersecting entry based on scroll direction
         const targetEntry = scrollDirection === 'down'
           ? intersectingEntries[intersectingEntries.length - 1]
           : intersectingEntries[0];
-        if (props.debug) console.log("Chosen target entry:", targetEntry.target);
+          
+        if (props.debug) console.log("Target:", targetEntry.target.id || targetEntry.target.tagName);
 
         const sectionToActivate = sections.value[getSectionIndex(targetEntry.target)];
-
-        if (sectionToActivate && !sectionToActivate.active) {
-          if (props.debug) console.log("Activating section:", sectionToActivate.title);
-          nextTick(() => {
-            removeActive(sectionToActivate, scrollDirection);
-            sectionToActivate.active = true;
-            sectionToActivate.inactiveFrom = null;
-            sectionToActivate.activeFrom = scrollDirection === 'down' ? 'forward' : 'reverse';
-            emit("section-change", { section: sectionToActivate, sections: sections.value, active: true });
-          });
-        }
+        setSectionActive(sectionToActivate, scrollDirection);
       } else {
-        if (props.debug) console.log("No intersecting entries. Checking edge cases.");
-        const activeSection = sections.value.find(s => s.active);
-        if (activeSection) {
-          const entryForActive = entries.find(e => e.target === activeSection.element);
-          if (entryForActive && !entryForActive.isIntersecting) {
-            const index = getSectionIndex(entryForActive.target);
-            const isFirst = index === 0;
-            const isLast = index === sections.value.length - 1;
-            if ((isFirst && scrollDirection === 'up' && !props.firstItemActive) || (isLast && scrollDirection === 'down')) {
-              if (props.debug) console.log("Deactivating section at edge:", activeSection.title);
-              nextTick(() => {
-                removeActive(null, scrollDirection);
-                emit("section-change", { section: activeSection, sections: sections.value, active: false });
-              });
+        // Strategy 2: Absolute positioning fallback (fired automatically on fresh observer load)
+        // Used to instantly catch sections we skipped entirely during warp-speed scrolling.
+        if (isObserverRefresh) {
+          if (props.debug) console.log("Fallback: bounds");
+          
+          let highestAboveIndex = -1;
+          entries.forEach(entry => {
+            const rootTop = entry.rootBounds ? entry.rootBounds.top : 0;
+            // +1 buffer for fractional pixels, check if element is above the reading zone
+            if (entry.boundingClientRect.top <= rootTop + 1) {
+              const idx = getSectionIndex(entry.target);
+              if (idx > highestAboveIndex) {
+                highestAboveIndex = idx;
+              }
+            }
+          });
+
+          // Activate the last section that is above the reading zone viewport
+          if (highestAboveIndex > -1) {
+            const isLast = highestAboveIndex === sections.value.length - 1;
+            const targetSection = sections.value[highestAboveIndex];
+
+            // Edge case: User scrolled past the bottom of the very last section into a footer
+            if (isLast && props.deactivateLastItem) {
+              const lastEntry = entries.find(e => e.target === targetSection.element);
+              const rootBottom = lastEntry.rootBounds ? lastEntry.rootBounds.bottom : window.innerHeight;
+              if (lastEntry && lastEntry.boundingClientRect.bottom < rootBottom) {
+                deactivateAll(scrollDirection, "Deactivate (last):");
+              } else {
+                setSectionActive(targetSection, scrollDirection);
+              }
+            } else {
+               setSectionActive(targetSection, scrollDirection);
+            }
+          } else {
+            // No elements are above the reading zone viewport, we are above the first item
+            if (props.debug) console.log("Fallback: top");
+            if (!props.firstItemActive) {
+              deactivateAll(scrollDirection, "Deactivate (top):");
+            } else {
+              const firstSection = sections.value[0];
+              setSectionActive(firstSection, scrollDirection);
+            }
+          }
+        } else {
+          // Strategy 3: Real-time edge deactivation
+          // Fires as user slowly scrolls out of the bounds of the first or last items
+          if (props.debug) console.log("Check edges");
+          const activeSection = sections.value.find(s => s.active);
+          if (activeSection) {
+            const entryForActive = entries.find(e => e.target === activeSection.element);
+            if (entryForActive && !entryForActive.isIntersecting) {
+              const index = getSectionIndex(entryForActive.target);
+              const isFirst = index === 0;
+              const isLast = index === sections.value.length - 1;
+              if ((isFirst && scrollDirection === 'up' && !props.firstItemActive) || (isLast && scrollDirection === 'down' && props.deactivateLastItem)) {
+                deactivateAll(scrollDirection, "Deactivate (edge):");
+              }
             }
           }
         }
       }
+      
+      // Observer refresh cycle completed
+      isObserverRefresh = false;
       if (props.debug) console.groupEnd();
     };
 
+    // Calculate options and margins for the reading zone
     let root = null;
     if (props.observerOptions && props.observerOptions.root !== undefined) {
       root = props.observerOptions.root;
@@ -147,32 +288,32 @@ export function useScrollAnchors({ sections, props, emit, componentElRef }) {
   }
 
   onMounted(() => {
-    if (props.firstItemActive && sections.value.length > 0) {
-      const first = sections.value[0];
-      if (first) {
-        first.active = true;
-      }
-    }
     createObserver();
     observeItems();
+    setupScrollListener();
   });
 
   onUnmounted(() => {
     destroyObserver();
+    removeScrollListener();
+    refreshObserver.cancel();
   });
 
+  // Re-observe items dynamically if the section list grows/shrinks
   watch(() => sections.value.length, () => {
     nextTick(() => {
       observeItems();
     });
   });
 
+  // Hot swap the observer if the developer changes options or snap settings
   watch(
     () => [props.snapOffset, props.observerOptions],
     () => {
       destroyObserver();
       createObserver();
       observeItems();
+      setupScrollListener();
     },
     { deep: true }
   );

package/lib/components/utils/UluAction.vue

@@ -48,7 +48,11 @@
      * Allows passing 'click' as a prop to signify this is an action (used in UluMenu data objects).
      * Note: The actual @click listener should be attached via fallthrough attrs, this is just for logic routing.
      */
-    click: Function
+    click: Function,
+    /**
+     * Button type (e.g. 'submit', 'reset', 'button'). Defaults to 'button' to prevent accidental form submissions.
+     */
+    type: String
   });
 
   const resolvedElement = computed(() => {
@@ -73,7 +77,7 @@
       }
     } else if (!props.element || props.element === "button") {
       // It's a button, ensure it doesn't accidentally submit forms unless requested
-      attrs.type = "button";
+      attrs.type = props.type || "button";
     }
     
     return attrs;

package/lib/plugins/core/index.js

@@ -27,7 +27,8 @@ const defaults = {
     file: "fas fa-file",
     previous: "fas fa-chevron-left",
     next: "fas fa-chevron-right",
-    dropdownExpand: "fas fa-caret-down"
+    dropdownExpand: "fas fa-caret-down",
+    search: "fas fa-search"
   }
 };
 

package/lib/utils/props.js

@@ -5,4 +5,18 @@
  */
 export function isArrayOfObjects(array) {
   return array.every(item => typeof item === "object");
+}
+
+/**
+ * Checks for deprecated props and calls a callback for each match
+ * @param {object} props - The current props object
+ * @param {string[]} deprecatedNames - Array of prop names to check
+ * @param {function} callback - Function called for each match, receiving the prop name
+ */
+export function checkDeprecatedProps(props, deprecatedNames, callback) {
+  deprecatedNames.forEach(name => {
+    if (props[name] !== undefined) {
+      callback(name);
+    }
+  });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ulu/frontend-vue",
-  "version": "0.5.15",
+  "version": "0.6.0",
   "description": "A modular, tree-shakeable Vue 3 component library for the Ulu Frontend theming system, plus general utilities for Vue development",
   "type": "module",
   "files": [
@@ -65,7 +65,7 @@
     "@fortawesome/vue-fontawesome": "^3.0.8",
     "@headlessui/vue": "^1.7.23",
     "@portabletext/vue": "^1.0.14",
-    "@ulu/frontend": "^0.5.0",
+    "@ulu/frontend": "^0.6.8",
     "@ulu/utils": "^0.0.34",
     "@unhead/vue": "^2.0.11",
     "fuse.js": "^6.6.2",
@@ -87,7 +87,7 @@
     "@storybook/addon-essentials": "^9.0.0-alpha.12",
     "@storybook/addon-links": "^9.1.1",
     "@storybook/vue3-vite": "^9.1.1",
-    "@ulu/frontend": "^0.4.11",
+    "@ulu/frontend": "^0.6.8",
     "@ulu/utils": "^0.0.34",
     "@unhead/vue": "^2.0.11",
     "@vitejs/plugin-vue": "^6.0.0",