@hortonstudio/main 1.9.6 → 1.9.8

package/autoInit/navbar/README.md

@@ -0,0 +1,366 @@
+# **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
+
+---
+
+## **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/autoInit/site-settings/README.md

@@ -0,0 +1,218 @@
+# **Site Settings System Documentation**
+
+## **Overview**
+
+The site settings system collects dynamic values from designated elements and replaces placeholder text (`{{name}}`) throughout the entire page. This allows for centralized content management where values can be defined once and used multiple times across text and links.
+
+---
+
+## **Site Settings**
+
+### **Required Elements**
+
+**Settings Wrapper** *(container for all settings lists)*
+
+* data-site-settings-element="wrapper"
+
+**Settings List** *(can have multiple lists inside wrapper)*
+
+* data-site-settings-element="list"
+
+**Setting Element** *(individual setting with a name and value)*
+
+* data-site-settings="name"
+  * The attribute value is the placeholder name (e.g., "company", "email", "phone")
+  * The element's text content is the value to replace
+
+**Typical element layout:**
+
+1. Settings Wrapper (data-site-settings-element="wrapper")
+   1. Settings List (data-site-settings-element="list")
+      1. Setting Element (data-site-settings="company")
+         1. Text: "Compass Facilities"
+      2. Setting Element (data-site-settings="email")
+         1. Text: "info@compass.com"
+      3. Setting Element (data-site-settings="phone")
+         1. Text: "555-1234"
+
+### **What It Does**
+
+1. **Collects settings** - Finds all elements with `[data-site-settings]` and stores their text values
+2. **Ignores empty elements** - Elements without text (like images) are skipped
+3. **Replaces text placeholders** - Finds all `{{name}}` in page text and replaces with values
+4. **Replaces link placeholders** - Finds all `{{name}}` in link hrefs and replaces with values
+
+### **When It Runs**
+
+* Runs once on page load
+* Runs again on Barba.js page transitions (via `reinitialize()`)
+* No ongoing monitoring or event listeners
+
+---
+
+## **Conditional Hide Feature**
+
+### **Optional Hide Attribute**
+
+**Hide Element** *(removes content conditionally before extracting text)*
+
+* data-site-settings-hide="class-name"
+  * Can specify multiple classes separated by spaces
+  * Element is removed if it has ANY of the specified classes
+
+### **Example Use Case**
+
+For dynamic content where certain parts should be hidden based on CMS conditions:
+
+```html
+<div data-site-settings="address">
+  <!-- Hidden by Webflow CMS condition -->
+  <span class="w-condition-invisible" data-site-settings-hide="w-condition-invisible">
+    <span>Suite 200</span>
+    <span>, </span>
+  </span>
+
+  <!-- Always visible -->
+  <span>Rockwall</span>
+  <span>, </span>
+  <span>Texas</span>
+  <span> 75087</span>
+</div>
+```
+
+**Result:** If the span has class `w-condition-invisible`, it's removed before extracting text. Final value: "Rockwall, Texas 75087"
+
+### **How It Works**
+
+1. Clones element to avoid modifying original DOM
+2. Finds all descendants with `[data-site-settings-hide]`
+3. Checks if element has any matching classes
+4. Removes matching elements from clone
+5. Extracts text from cleaned clone
+
+---
+
+## **Usage Examples**
+
+### **Define Settings**
+
+```html
+<div data-site-settings-element="wrapper" style="display: none;">
+  <div data-site-settings-element="list">
+    <div data-site-settings="company">Compass Facilities</div>
+    <div data-site-settings="email">info@compass.com</div>
+    <div data-site-settings="phone">555-1234</div>
+    <div data-site-settings="address">123 Main St, Dallas, TX 75001</div>
+  </div>
+</div>
+```
+
+**Note:** The wrapper is typically hidden with `display: none` since it's only for data storage.
+
+### **Use Settings in Text**
+
+```html
+<h1>Welcome to {{company}}</h1>
+<p>Contact us at {{email}} or call {{phone}}</p>
+<p>Visit us at {{address}}</p>
+```
+
+**Result:**
+```html
+<h1>Welcome to Compass Facilities</h1>
+<p>Contact us at info@compass.com or call 555-1234</p>
+<p>Visit us at 123 Main St, Dallas, TX 75001</p>
+```
+
+### **Use Settings in Links**
+
+```html
+<a href="mailto:{{email}}">Email Us</a>
+<a href="tel:{{phone}}">Call Us</a>
+<a href="https://maps.google.com/?q={{address}}">Get Directions</a>
+```
+
+**Result:**
+```html
+<a href="mailto:info@compass.com">Email Us</a>
+<a href="tel:555-1234">Call Us</a>
+<a href="https://maps.google.com/?q=123 Main St, Dallas, TX 75001">Get Directions</a>
+```
+
+---
+
+## **Multiple Lists**
+
+You can have multiple lists inside the wrapper for organization:
+
+```html
+<div data-site-settings-element="wrapper">
+  <!-- Contact info -->
+  <div data-site-settings-element="list">
+    <div data-site-settings="email">info@compass.com</div>
+    <div data-site-settings="phone">555-1234</div>
+  </div>
+
+  <!-- Company info -->
+  <div data-site-settings-element="list">
+    <div data-site-settings="company">Compass Facilities</div>
+    <div data-site-settings="established">2020</div>
+  </div>
+</div>
+```
+
+All settings are collected regardless of which list they're in.
+
+---
+
+## **Key Attributes Summary**
+
+| Attribute | Purpose | Required On |
+| ----- | ----- | ----- |
+| `data-site-settings-element="wrapper"` | Settings container | Wrapper div |
+| `data-site-settings-element="list"` | Settings list | List div (at least one) |
+| `data-site-settings="name"` | Setting with name | Individual setting elements |
+| `data-site-settings-hide="class"` | Conditional hide | Optional (inside setting elements) |
+
+---
+
+## **Placeholder Syntax**
+
+**Format:** `{{name}}`
+
+* Double curly braces
+* Name must match the `data-site-settings` attribute value exactly
+* Case-sensitive
+* Works in text content and link hrefs
+
+---
+
+## **Notes**
+
+1. **Empty elements ignored** - Elements without text (images, empty divs) are skipped
+2. **No visual component** - Settings wrapper should be hidden with CSS
+3. **Page-wide replacement** - Placeholders are replaced throughout entire page
+4. **Multiple replacements** - Same placeholder can be used unlimited times
+5. **Barba.js compatible** - Automatically reinitializes on page transitions
+
+---
+
+## **Common Issues**
+
+**Placeholder not replacing:**
+
+1. Verify `data-site-settings` attribute matches placeholder name exactly
+2. Check that setting element has text content
+3. Ensure double curly braces: `{{name}}` not `{name}` or `{{ name }}`
+
+**Wrong value appearing:**
+
+1. Check for duplicate setting names (last one wins)
+2. Verify conditional hide elements are working correctly
+3. Inspect the settings wrapper to confirm expected text
+
+**Links not working:**
+
+1. Ensure placeholder syntax is correct in href attribute
+2. Check that value is URL-safe (encode special characters if needed)
+3. For tel: links, ensure phone number has no spaces or dashes in setting value