@hortonstudio/main 1.9.10 → 1.9.20

package/src/modules/default/functions/navbar/README.md

@@ -0,0 +1,393 @@
+# **Navbar System Documentation**
+
+## **Webflow IX3 Notes**
+
+When an element only has a click toggle/reverse trigger, it also works with enter/space. If it has click toggle/reverse AND hover triggers, it doesn't work with space but it does with enter.
+
+---
+
+# **Navbar Setup Guide**
+
+## **Overview**
+
+The navbar system uses Webflow IX3 interactions to manage visual states (`.is-active` class) while JavaScript automatically syncs ARIA attributes, keyboard navigation, and focus management.
+
+## **Required Structure**
+
+### **Navbar Setup**
+
+Add **data-hs-nav="wrapper"** to the main wrapper of the navbar, e.g. the `<nav>` element.
+
+**What it does:** Container for all navbar functionality. Used for arrow key navigation scope.
+
+---
+
+## **Navbar Dropdown List**
+
+### **Required Elements**
+
+**Button Wrapper** _(wraps the button and dropdown list)_
+
+- data-hs-nav="dropdown"
+
+**Toggle Button** _(the wrapper of the actual button/link that opens/closes the dropdown list)_
+
+- data-site-clickable="element"
+  - The Global / Clickable component already has this set
+
+**Dropdown List** _(main wrapper of the list)_
+
+- data-hs-nav="dropdown-list"
+
+**Dropdown List Items**
+
+- data-site-clickable="element"
+  - If using webflow framework, this is auto set with Global / Button and their respective Global / Clickable
+
+**Typical element layout:**
+
+1. Button Wrapper (data-hs-nav="dropdown")
+   1. Button Content
+      1. Clickable Component (data-site-clickable="element")
+         1. Toggle Button
+   2. Dropdown List Component Slot
+      1. Dropdown List
+         1. Dropdown list items
+
+### **Interaction Requirements (IX3)**
+
+**Triggers:**
+
+1. **Hover Trigger** on `[data-hs-nav="dropdown"]`
+   1. `Mouse Enter -> Each Mouse Enter: Play`
+2. **Hover Trigger** on `[data-hs-nav="dropdown"]`
+   1. `Mouse Leave -> Each Mouse Leave: Reverse`
+3. **Click Trigger** on `[data-hs-nav="dropdown"]`
+   1. `Each click: Toggle play/reverse`
+4. **Add class** `.is-active` to wrapper on hover in
+5. **Remove class** `.is-active` on hover out
+
+**Timeline requirements:**
+
+1. 0s: Toggle is-active class on the trigger element
+2. 0s: From: Display: none | To: Display: flex on the element you will be animating to open
+3. .06s: Rest of animation
+
+### **What It Does**
+
+1. **Keyboard navigation:** ArrowDown/ArrowUp/Space open dropdown, Escape closes
+2. **Focus management:** Auto-focuses first item on open, returns focus to toggle on close
+3. **ARIA sync:** Watches `.is-active` class, updates `aria-expanded` and `aria-hidden`
+4. **Arrow navigation:** Navigate items with ArrowDown/ArrowUp when open
+
+### **Notes**
+
+1. Using Global / Button is preferred for this system. For attribute adding, use this component props:
+   1. Attribute 1 Name: set to “data-hs-nav”
+   2. Attribute 1 Value: set to “dropdown”
+2. `[data-site-clickable="element"]` Is set up by default in the Global / Clickable component
+   1. Toggle is the **first child** of `[data-site-clickable="element"]`
+   2. Items must use same `[data-site-clickable="element"]` pattern
+3. Enter key navigates the toggle link (default behavior)
+
+---
+
+## **Mobile Menu**
+
+### **Required Elements**
+
+**Menu Button** _(the wrapper of the actual button)_
+
+- data-site-clickable="element"
+  - This one does not use the Global / Clickable component
+  - This is not required for the actual menu functionality, but for the arrow navigation throughout the Navbar
+
+**Menu Button Element** _(the actual button)_
+
+- data-hs-nav="menu-button"
+
+**Menu** _(main wrapper of the menu)_
+
+- data-hs-nav="menu"
+
+**Menu Items**
+
+- data-site-clickable="element"
+  - If using webflow framework, this is auto set with Global / Button and their respective Global / Clickable
+
+**Breakpoint Indicator**
+
+- This element wraps the Menu (main wrapper)
+  - Requires: data-hs-nav="menu-hide"
+
+**Typical element layout:**
+
+1. Navbar Component (data-hs-nav=”wrapper”)
+   1. Announce Bar
+      1. Buttons
+   2. Navbar Wrap
+      1. Navbar Container
+         1. Buttons
+         2. Menu Button Wrapper (data-site-clickable="element")
+            1. Menu Button (data-hs-nav="menu-button")
+      2. Menu Hide (data-hs-nav=”menu-hide”)
+         1. Menu (data-hs-nav="menu")
+            1. Menu Items (elements with data-site-clickable="element")
+               1. Typically Global / Button components, auto set attributes
+
+### **Interaction Requirements (IX3)**
+
+#### Triggers:
+
+1. **Click trigger** on `[data-hs-nav="menu-button"]`
+   1. `Toggle play/reverse`
+
+#### Timeline:
+
+1. 0s: Toggle is-active class on the trigger element
+2. 0s: From: Display: none | To: Display: flex on the element you will be animating to open
+3. .06s: Rest of animation
+
+### **What It Does**
+
+1. **ARIA sync:** Watches `.is-active` on button, updates `aria-expanded`
+2. **Body overflow:** Adds `u-overflow-hidden` class to body when open
+   1. If the site uses Lenis scrolling, this code triggers start and top so it works with lenis properly.
+3. **Focus trap:** Traps tab key within navbar when menu open
+4. **Auto-focus:** Focuses first menu item on open
+5. **Focus return:** Returns focus to button on close
+6. **Arrow navigation:** ArrowDown/ArrowUp navigate through all visible items
+
+### **Breakpoint Indicator (`menu-hide`)**
+
+**CSS pattern (typically add data-responsive=”desktop/mobile” to the menu-hide element):**
+
+/\* Mobile styles (default) \*/
+
+\[data-responsive="desktop"\] { display: none\!important; }
+
+\[data-responsive="mobile"\] { display: flex\!important; }
+
+/\* Desktop styles \*/
+
+@media (width \> 63em) {
+
+\[data-responsive="desktop"\] { display: flex\!important; }
+
+\[data-responsive="mobile"\] { display: none\!important; }
+
+}
+
+**What it does:** JavaScript checks if this element is visible to enable/disable menu button functionality at different breakpoints.
+
+---
+
+## **Mobile Menu Dropdown**
+
+### **Required Elements**
+
+**Dropdown Wrapper**
+
+- data-hs-nav="menu-dropdown"
+
+**Dropdown Toggle Button** _(the wrapper of the actual button)_
+
+- data-site-clickable="element"
+  - The Global / Clickable component already has this set
+
+**Dropdown List** _(main wrapper of the list)_
+
+- data-hs-nav="menu-dropdown-list"
+
+**Dropdown List Items**
+
+- data-site-clickable="element"
+  - If using webflow framework, this is auto set with Global / Button and their respective Global / Clickable
+
+**Typical element layout:**
+
+1. Dropdown Wrapper (data-hs-nav="menu-dropdown")
+   1. Button Wrapper (data-site-clickable="element")
+      1. Toggle Button
+   2. Dropdown List (data-hs-nav="menu-dropdown-list")
+      1. List Items (data-site-clickable="element")
+         1. Links or Buttons
+
+### **Interaction Requirements (IX3)**
+
+#### Triggers:
+
+1. **Click trigger** on Dropdown Wrapper `[data-hs-nav="menu-dropdown"]`
+   1. `Toggle play/reverse`
+
+#### Timeline:
+
+1. 0s: Toggle is-active class on the trigger element
+2. 0s: From: Display: none | To: Display: flex on the element you will be animating to open
+3. .06s: Rest of animation
+
+### **What It Does**
+
+1. **ARIA sync:** Watches `.is-active` on wrapper, updates `aria-expanded` and `aria-hidden`
+2. **Focus return:** Returns focus to button when closing (if focus was inside list)
+3. **Arrow integration:** Items automatically included in menu arrow navigation when open (filtered when closed via `aria-hidden`)
+
+### **Notes**
+
+1. Using Global / Button is preferred for this system. For attribute adding, use this component props:
+   1. Attribute 1 Name: set to “data-hs-nav”
+   2. Attribute 1 Value: set to “menu-dropdown”
+2. Items inside closed dropdown lists are filtered from arrow navigation
+3. Uses same `[data-site-clickable="element"]` pattern as desktop
+4. Button is **first child** of clickable wrapper
+
+---
+
+## **Skip Link (Optional)**
+
+**What it does:** When using a skip link, add these attributes so the system ignores it for arrow navigation.
+
+### **Required Elements**
+
+**Skip Link Wrapper**
+
+- data-hs-nav="skip-link"
+
+---
+
+## **Clickable Element Pattern**
+
+**All interactive elements** (buttons, links) must follow this pattern:
+
+**For Links:**
+
+1. Clickable Wrapper (data-site-clickable="element")
+   1. Link Element
+
+**For Buttons:**
+
+1. Clickable Wrapper (data-site-clickable="element")
+   1. Button Element
+
+**Why:** JavaScript queries `[data-site-clickable="element"]` then gets `.children[0]` to find the actual interactive element. This allows wrapping for styling while maintaining consistent selection.
+
+This is for arrow navigation and proper accessibility labelling
+
+---
+
+## **Key Attributes Summary**
+
+| Attribute                          | Purpose                     | Required On            |
+| ---------------------------------- | --------------------------- | ---------------------- |
+| `data-hs-nav="wrapper"`            | Navbar container            | `<nav>`                |
+| `data-hs-nav="dropdown"`           | Desktop dropdown wrapper    | Wrapper div            |
+| `data-hs-nav="dropdown-list"`      | Desktop dropdown content    | Content div            |
+| `data-hs-nav="menu-button"`        | Mobile menu toggle          | `<button>`             |
+| `data-hs-nav="menu"`               | Mobile menu container       | Menu div               |
+| `data-hs-nav="menu-hide"`          | Breakpoint indicator        | Any element            |
+| `data-hs-nav="menu-dropdown"`      | Mobile dropdown wrapper     | Wrapper div            |
+| `data-hs-nav="menu-dropdown-list"` | Mobile dropdown content     | Content div            |
+| `data-site-clickable="element"`    | Interactive element wrapper | Wrapper div            |
+| `data-hs-nav="skip-link"`          | Skip link container         | Wrapper div (optional) |
+
+---
+
+## **Webflow Class Requirements**
+
+### **`.is-active` class**
+
+Must be added/removed by Webflow interactions on:
+
+1. Desktop dropdown wrapper (`[data-hs-nav="dropdown"]`)
+2. Mobile menu button (`[data-hs-nav="menu-button"]`)
+3. Mobile menu dropdown wrapper (`[data-hs-nav="menu-dropdown"]`)
+
+JavaScript watches for this class and syncs ARIA/behavior accordingly.
+
+### **`.u-overflow-hidden` class**
+
+Applied to `<body>` by JavaScript when the menu is open. Style accordingly:
+
+.u-overflow-hidden { overflow: hidden; }
+
+---
+
+## **Keyboard Navigation**
+
+### **Desktop Dropdown (when focused on toggle)**
+
+1. **ArrowDown** → Open dropdown, focus first item
+2. **ArrowUp** → Open dropdown, focus last item
+3. **Space** → Open/close dropdown
+4. **Escape** → Close dropdown
+5. **Enter** → Navigate to toggle link href
+
+### **Desktop Dropdown (when inside)**
+
+1. **ArrowDown** → Next item
+2. **ArrowUp** → Previous item (or close if on first item)
+3. **Escape** → Close dropdown, return focus to toggle
+
+### **Desktop Navbar**
+
+1. **ArrowLeft/ArrowRight** → Navigate between navbar elements
+
+### **Mobile Menu**
+
+1. **ArrowDown/ArrowUp** → Navigate through all visible items
+2. **ArrowLeft** → Collapse dropdown (when on dropdown button)
+3. **ArrowRight** → Expand dropdown (when on dropdown button)
+4. **Home/End** → First/last item
+5. **Escape** → Close menu
+
+---
+
+## **Barba.js / SPA Compatibility**
+
+The navbar system is fully compatible with Barba.js and other SPA frameworks:
+
+### **v2.0.0 Improvements:**
+
+- **setTimeout tracking and cleanup** - Properly clears all focus management timeouts on destroy (fixes edge case focus issues)
+- **JSON config system** - Future-proof attribute management for easy rebranding
+- **Enhanced SPA compatibility** - Perfect cleanup for Barba.js and other SPA frameworks
+
+### **On Destroy:**
+
+1. **Clears all pending timeouts** (4 focus management timeouts)
+2. Disconnects all MutationObservers and ResizeObservers
+3. Removes all event listeners (element-specific and document-level)
+4. Removes focus trap handler
+5. Clears body overflow class if present
+6. Resets all module state
+
+### **On Reinitialize:**
+
+1. Finds fresh navbar elements on new page
+2. Creates new observers and event handlers
+3. Applies all ARIA attributes to new elements
+4. Works like fresh page load on new DOM
+
+---
+
+## **Common Issues**
+
+**Items not navigable with arrow keys:**
+
+1. Ensure items use `[data-site-clickable="element"]` wrapper
+2. Check that first child is the actual button/link
+
+**Dropdown not syncing ARIA:**
+
+1. Verify Webflow interaction adds/removes `.is-active` class
+2. Check class is on correct element (wrapper for dropdowns, button for menu)
+
+**Tab goes into hidden dropdowns:**
+
+1. Ensure Webflow interaction uses `display: none` or `visibility: hidden` when closed
+2. Or verify `.is-active` class is being removed properly
+
+**Menu button doesn't work at desktop:**
+
+1. Check `[data-hs-nav="menu-hide"]` has correct responsive CSS
+2. Element should be `display: none` at desktop breakpoint

package/src/modules/default/functions/navbar/functions/arrow-navigation/arrow-navigation.ts

@@ -0,0 +1,183 @@
+import { getSelector, globalConfig } from '@utils';
+
+export function init(config) {
+  const cleanup = {
+    handlers: [],
+  };
+
+  const addHandler = (element, event, handler, options) => {
+    element.addEventListener(event, handler, options);
+    cleanup.handlers.push({ element, event, handler, options });
+  };
+
+  function setupDesktopArrowNavigation(addHandler) {
+    const keydownHandler = function (e) {
+      if (e.key !== 'ArrowLeft' && e.key !== 'ArrowRight') return;
+
+      const menu = document.querySelector('[data-hs-nav-menu="wrapper"]');
+      if (menu && menu.contains(document.activeElement)) return;
+
+      const navbar = document.querySelector('[data-hs-nav="wrapper"]');
+
+      if (!navbar || !navbar.contains(document.activeElement)) return;
+
+      // Check if focus is inside an open dropdown (using .is-active class)
+      const openDropdown = navbar.querySelector(
+        `.${globalConfig.classes.active}[data-hs-nav-dropdown]`
+      );
+      if (openDropdown && openDropdown.contains(document.activeElement)) return;
+
+      e.preventDefault();
+
+      const clickableSelector = getSelector(globalConfig.clickable, 'button');
+      const allNavbarElements = Array.from(navbar.querySelectorAll(clickableSelector));
+      const focusableElements = Array.from(allNavbarElements).filter((el) => {
+        if (el.getAttribute('tabindex') === '-1') return false;
+
+        const isInDropdownList = el.closest('[role="menu"]');
+        if (isInDropdownList) return false;
+
+        const isInMenu = el.closest('[data-hs-nav-menu="wrapper"]');
+        if (isInMenu) return false;
+
+        const isInSkipLink = el.closest('[data-hs-nav="skip-link"]');
+        if (isInSkipLink) return false;
+
+        const computedStyle = window.getComputedStyle(el);
+        const isHidden =
+          computedStyle.display === 'none' ||
+          computedStyle.visibility === 'hidden' ||
+          computedStyle.opacity === '0' ||
+          el.offsetWidth === 0 ||
+          el.offsetHeight === 0;
+        if (isHidden) return false;
+
+        let parent = el.parentElement;
+        while (parent && parent !== navbar) {
+          const parentStyle = window.getComputedStyle(parent);
+          const parentHidden =
+            parentStyle.display === 'none' ||
+            parentStyle.visibility === 'hidden' ||
+            parent.offsetWidth === 0 ||
+            parent.offsetHeight === 0;
+          if (parentHidden) return false;
+          parent = parent.parentElement;
+        }
+
+        return true;
+      });
+
+      const currentIndex = focusableElements.indexOf(document.activeElement);
+      if (currentIndex === -1) return;
+
+      if (e.key === 'ArrowRight') {
+        if (currentIndex < focusableElements.length - 1) {
+          const nextIndex = currentIndex + 1;
+          focusableElements[nextIndex].focus();
+        }
+      } else {
+        if (currentIndex > 0) {
+          const nextIndex = currentIndex - 1;
+          focusableElements[nextIndex].focus();
+        }
+      }
+    };
+
+    addHandler(document, 'keydown', keydownHandler);
+  }
+
+  function setupMenuArrowNavigation(addHandler) {
+    const menuContainer = document.querySelector('[data-hs-nav-menu="wrapper"]');
+    if (!menuContainer) return;
+
+    function getFocusableElements() {
+      const menuClickableSelector = getSelector(globalConfig.clickable, 'button');
+      const allElements = Array.from(menuContainer.querySelectorAll(menuClickableSelector));
+      return Array.from(allElements).filter((el) => {
+        // Check if element or any ancestor is inert (inactive dropdown)
+        let current = el;
+        while (current && current !== menuContainer) {
+          if (current.inert) {
+            return false;
+          }
+          current = current.parentElement;
+        }
+        return true;
+      });
+    }
+
+    let currentFocusIndex = -1;
+
+    const keydownHandler = function (e) {
+      const focusableElements = getFocusableElements();
+      if (focusableElements.length === 0) return;
+
+      const activeElement = document.activeElement;
+      currentFocusIndex = focusableElements.indexOf(activeElement);
+
+      if (e.key === 'ArrowDown') {
+        e.preventDefault();
+        if (currentFocusIndex < focusableElements.length - 1) {
+          currentFocusIndex = currentFocusIndex + 1;
+          focusableElements[currentFocusIndex].focus();
+        }
+      } else if (e.key === 'ArrowUp') {
+        e.preventDefault();
+        if (currentFocusIndex > 0) {
+          currentFocusIndex = currentFocusIndex - 1;
+          focusableElements[currentFocusIndex].focus();
+        }
+      } else if (e.key === 'ArrowRight') {
+        e.preventDefault();
+        if (activeElement.tagName === 'BUTTON' && activeElement.hasAttribute('aria-controls')) {
+          const isExpanded = activeElement.getAttribute('aria-expanded') === 'true';
+          if (!isExpanded) {
+            activeElement.click();
+          }
+          return;
+        }
+      } else if (e.key === 'ArrowLeft') {
+        e.preventDefault();
+        if (activeElement.tagName === 'BUTTON' && activeElement.hasAttribute('aria-controls')) {
+          const isExpanded = activeElement.getAttribute('aria-expanded') === 'true';
+          if (isExpanded) {
+            activeElement.click();
+          }
+          return;
+        }
+      } else if (e.key === 'Home') {
+        e.preventDefault();
+        currentFocusIndex = 0;
+        focusableElements[0].focus();
+      } else if (e.key === 'End') {
+        e.preventDefault();
+        currentFocusIndex = focusableElements.length - 1;
+        focusableElements[focusableElements.length - 1].focus();
+      } else if (e.key === ' ' && activeElement.tagName === 'A') {
+        e.preventDefault();
+      } else if (e.key === 'Escape') {
+        const menuButton = document.querySelector('[data-hs-nav-menu="button"]');
+        if (menuButton) {
+          menuButton.click();
+          menuButton.focus();
+        }
+      }
+    };
+
+    addHandler(menuContainer, 'keydown', keydownHandler);
+  }
+
+  setupDesktopArrowNavigation(addHandler);
+  setupMenuArrowNavigation(addHandler);
+
+  return {
+    result: 'arrow-navigation initialized',
+    destroy: () => {
+      // Remove all event listeners
+      cleanup.handlers.forEach(({ element, event, handler, options }) => {
+        element.removeEventListener(event, handler, options);
+      });
+      cleanup.handlers.length = 0;
+    },
+  };
+}