@hortonstudio/main 1.9.4 → 1.9.7

package/autoInit/form/README.md

@@ -0,0 +1,338 @@
+# **Form System Documentation**
+
+## **Overview**
+
+The form system provides two main features:
+1. **Honeypot spam prevention** - Blocks bot submissions using a hidden field
+2. **Custom select component** - Fully accessible, styled select dropdowns that sync with native `<select>` elements for form submission
+
+---
+
+## **Honeypot Spam Prevention**
+
+### **Required Element**
+
+**Honeypot Field** *(hidden field in your form)*
+
+* data-hs-form="form-handler"
+* Should be hidden with CSS (bots will auto-fill it, humans won't see it)
+
+### **What It Does**
+
+1. **Listens for form submissions** - Captures all form submit events
+2. **Checks honeypot field** - If the hidden field has a value, it's likely a bot
+3. **Blocks submission** - Prevents form from submitting if honeypot is filled
+
+### **Example**
+
+```html
+<form>
+  <input type="text" name="name" placeholder="Your Name">
+  <input type="email" name="email" placeholder="Your Email">
+
+  <!-- Honeypot field (hidden with CSS) -->
+  <input type="text" name="website" data-hs-form="form-handler" style="display: none;">
+
+  <button type="submit">Submit</button>
+</form>
+```
+
+**Result:** Legitimate users never see the honeypot field. Bots auto-fill all fields, triggering the spam prevention.
+
+---
+
+## **Custom Select Component**
+
+### **Required Elements**
+
+**Select Wrapper** *(main container)*
+
+* data-hs-form="select"
+
+**Native Select** *(hidden select element for form submission)*
+
+* Standard `<select>` element with `<option>` children
+* Should have `name` attribute for form submission
+* Will be hidden but remains functional
+
+**Toggle Button** *(visual button to open/close dropdown)*
+
+* `<button>` element or element with `role="button"`
+* Should contain a `<span>` element for displaying selected text
+* Webflow IX must add/remove `.is-active` class on this button
+
+**Custom List** *(dropdown container)*
+
+* data-hs-form="select-list"
+* First child is used as template for generating options
+* Webflow IX must show/hide this when button is clicked
+
+**Template Element** *(first child of select-list)*
+
+* Should contain a `<span>` element for option text
+* Will be cloned for each `<option>` in the native select
+* Original template is removed after cloning
+
+**Label** *(optional but recommended)*
+
+* Standard `<label>` element
+* Can be inside wrapper or reference select by `for` attribute
+
+**Typical element layout:**
+
+1. Select Wrapper (data-hs-form="select")
+   1. Label (optional)
+      1. Text: "Choose an option"
+   2. Native Select (`<select>`)
+      1. Option 1 (`<option value="value1">`)
+         1. Text: "Option 1"
+      2. Option 2 (`<option value="value2">`)
+         1. Text: "Option 2"
+   3. Toggle Button (`<button>`)
+      1. Button Text (`<span>`)
+         1. Text: "Choose an option"
+   4. Custom List (data-hs-form="select-list")
+      1. Template Element
+         1. Text Span (`<span>`)
+            1. Text: "Placeholder"
+
+### **What It Does**
+
+1. **Unwraps Webflow slots** - Removes any `<div>` wrappers inside `<select>` elements
+2. **Clones template** - Uses first child of select-list as template
+3. **Generates options** - Creates custom option elements from native `<option>` elements
+4. **Syncs state** - Keeps custom UI and native select in sync
+5. **ARIA management** - Automatically updates accessibility attributes
+6. **Keyboard navigation** - Full arrow key, Tab, Enter, Space, Escape support
+7. **Focus management** - Handles focus return, tabbing out, and keyboard navigation
+
+### **When It Runs**
+
+* Runs once on page load (or DOMContentLoaded)
+* Available for manual re-initialization via `window.initCustomSelects()`
+* Runs again on Barba.js page transitions (via `reinitialize()`)
+
+### **Interaction Requirements (IX3)**
+
+**CRITICAL:** Webflow interactions MUST add/remove `.is-active` class on the toggle button.
+
+**Triggers:**
+
+1. **Click trigger** on `<button>` element
+   1. `Each click: Toggle play/reverse`
+
+**Timeline:**
+
+1. 0s: Toggle `.is-active` class on the button element
+2. .06s: Rest of animation (fade in, slide, etc.)
+
+---
+
+## **Accessibility**
+
+### **Automatic ARIA Setup**
+
+For each select, the system automatically:
+
+1. **Button (combobox)**
+   - `role="combobox"`
+   - `aria-haspopup="listbox"`
+   - `aria-expanded="true|false"` (synced with `.is-active` class)
+   - `aria-controls="[listbox-id]"`
+   - `aria-labelledby="[label-id]"` (if label exists)
+   - `aria-activedescendant="[option-id]"` (when navigating with arrows)
+
+2. **Select List**
+   - `role="listbox"`
+   - `tabindex="-1"` (not directly tabbable)
+
+3. **Options**
+   - `role="option"`
+   - `aria-selected="true|false"`
+   - `tabindex="0"` when dropdown open, `tabindex="-1"` when closed
+   - Unique `id` for aria-activedescendant
+
+4. **Label**
+   - Connected to native select with `for` attribute
+   - Linked to button with `aria-labelledby`
+
+### **Focus Management**
+
+1. **Opening dropdown** - All options become tabbable
+2. **Closing dropdown** - Focus returns to button if inside list
+3. **Tabbing out** - Automatically closes dropdown
+4. **Arrow navigation** - Focuses options with visual `.focused` class
+
+---
+
+## **Usage Examples**
+
+### **Basic Select**
+
+```html
+<div data-hs-form="select">
+  <label for="fruit-select">Choose a fruit</label>
+
+  <select name="fruit" id="fruit-select">
+    <option value="">Choose an option</option>
+    <option value="apple">Apple</option>
+    <option value="banana">Banana</option>
+    <option value="orange">Orange</option>
+  </select>
+
+  <button>
+    <span>Choose an option</span>
+  </button>
+
+  <div data-hs-form="select-list">
+    <div>
+      <span>Template</span>
+    </div>
+  </div>
+</div>
+```
+
+**Result:** Creates 4 custom options (including empty "Choose an option"). Native select stays synced for form submission.
+
+### **Pre-selected Option**
+
+```html
+<select name="size">
+  <option value="small">Small</option>
+  <option value="medium" selected>Medium</option>
+  <option value="large">Large</option>
+</select>
+```
+
+**Result:** Button text automatically shows "Medium" on page load. Corresponding custom option has `aria-selected="true"`.
+
+### **Options with Special Characters**
+
+```html
+<option value='product"deluxe"'>Deluxe Edition</option>
+<option value="user's choice">Custom Option</option>
+```
+
+**Result:** Works correctly - uses safe value comparison instead of selector injection.
+
+---
+
+## **Keyboard Navigation**
+
+### **When Button is Focused**
+
+1. **Space** or **Enter** � Open/close dropdown
+2. **ArrowDown** � Open dropdown (or focus first option if already open)
+3. **ArrowUp** � Focus last option (if dropdown is open)
+4. **Escape** � Close dropdown (if open)
+
+### **When Option is Focused**
+
+1. **ArrowDown** � Focus next option
+2. **ArrowUp** � Focus previous option (or close and focus button if on first option)
+3. **Enter** or **Space** � Select option and close dropdown
+4. **Escape** � Close dropdown and return focus to button
+5. **Tab** � Navigate through options, tab out of last option closes dropdown
+
+---
+
+## **State Synchronization**
+
+### **Native Select � Custom UI**
+
+When native select value changes (programmatically or via Webflow):
+1. Finds matching custom option by value
+2. Updates button text
+3. Updates `aria-selected` on all options
+
+### **Custom UI � Native Select**
+
+When user selects custom option:
+1. Updates native select's `value`
+2. Dispatches `change` event on native select
+3. Updates button text
+4. Updates `aria-selected`
+5. Closes dropdown
+
+**Both stay in sync at all times.**
+
+---
+
+## **Key Attributes Summary**
+
+| Attribute | Purpose | Required On |
+| ----- | ----- | ----- |
+| `data-hs-form="select"` | Select wrapper | Wrapper div |
+| `data-hs-form="select-list"` | Custom options container | List div |
+| `data-hs-form="form-handler"` | Honeypot spam field | Hidden input (optional) |
+
+---
+
+## **API**
+
+### **Manual Re-initialization**
+
+```javascript
+window.initCustomSelects();
+```
+
+Re-scans page for new selects and initializes them. Useful for dynamically added content.
+
+---
+
+## **Notes**
+
+1. **Native select required** - Must have actual `<select>` element for form submission
+2. **Button must have span** - `<span>` child is required for text updates
+3. **Template is removed** - First child of select-list is cloned then deleted
+4. **Webflow IX required** - Must toggle `.is-active` class on button
+5. **Barba.js compatible** - Automatically cleans up on destroy/reinitialize
+6. **Silent failures** - Missing required elements cause function to return early (no errors)
+7. **Empty values supported** - Options with `value=""` work correctly
+8. **Special characters safe** - Handles quotes and special characters in option values
+
+---
+
+## **Common Issues**
+
+**Dropdown not opening:**
+
+1. Verify Webflow IX adds `.is-active` class to button (not wrapper or list)
+2. Check that button exists and is `<button>` or has `role="button"`
+3. Ensure select-list exists with `data-hs-form="select-list"`
+
+**Button text not updating:**
+
+1. Verify button has a `<span>` child element
+2. Check that template element has a `<span>` child
+3. Ensure option values match between native and custom
+
+**Options not clickable:**
+
+1. Check that template element exists as first child of select-list
+2. Verify template has `<span>` for text
+3. Ensure options are being generated (inspect DOM)
+
+**Can't tab to options:**
+
+1. Verify dropdown is open (`.is-active` class on button)
+2. Check Webflow IX animation shows the select-list
+3. Ensure `display: none` is removed when open
+
+**Form not submitting selected value:**
+
+1. Native `<select>` must have `name` attribute
+2. Check that native select's value is updating (inspect DOM or use console)
+3. Verify native select is inside `<form>` element
+
+**Dropdown doesn't close when tabbing out:**
+
+1. Ensure wrapper element properly contains button and list
+2. Check that `data-hs-form="select"` is on wrapper
+3. Verify Webflow IX removes `.is-active` when clicking button again
+
+**Spam prevention not working:**
+
+1. Verify honeypot field has `data-hs-form="form-handler"`
+2. Ensure field is hidden with CSS (not removed from DOM)
+3. Check that field is inside the `<form>` element

package/autoInit/{form.js → form/form.js}

@@ -105,6 +105,7 @@ export function init() {
       // Add ARIA attributes
       customList.setAttribute('role', 'listbox');
       customList.setAttribute('id', `${selectName}-listbox`);
+      customList.setAttribute('tabindex', '-1');
 
       button.setAttribute('role', 'combobox');
       button.setAttribute('aria-haspopup', 'listbox');
@@ -127,7 +128,6 @@ export function init() {
       }
 
       // Track state
-      let currentIndex = -1;
       let isOpen = false;
 
       // Update expanded state
@@ -148,7 +148,6 @@ export function init() {
         });
 
         // Add new focus
-        currentIndex = index;
         options[index].classList.add('focused');
         options[index].setAttribute('tabindex', '0');
         options[index].focus();
@@ -157,7 +156,7 @@ export function init() {
 
       // Select option
       function selectOption(optionElement) {
-        const value = optionElement.getAttribute('data-value');
+        const value = optionElement.getAttribute('data-value') || '';
         const text = optionElement.querySelector('span')?.textContent || optionElement.textContent;
 
         // Update real select
@@ -176,7 +175,7 @@ export function init() {
         });
         optionElement.setAttribute('aria-selected', 'true');
 
-        // Click the button to close
+        // Close dropdown by clicking button
         button.click();
       }
 
@@ -266,33 +265,46 @@ export function init() {
       };
       addHandler(customList, 'click', listClickHandler);
 
-      // Track open/close state
-      const observer = new MutationObserver((mutations) => {
-        mutations.forEach((mutation) => {
-          if (mutation.type === 'attributes') {
-            // Check if dropdown is visible
-            const isVisible = !customList.hidden &&
-                            customList.style.display !== 'none' &&
-                            !customList.classList.contains('hidden');
-
-            updateExpandedState(isVisible);
-
-            if (!isVisible) {
-              currentIndex = -1;
-              button.removeAttribute('aria-activedescendant');
-              // Return focus to button if it was in the list
-              if (document.activeElement?.closest('[data-hs-form="select-list"]') === customList) {
-                button.focus();
-              }
-            }
+      // Handle tabbing out of select list
+      const listFocusoutHandler = (e) => {
+        // Check if focus is moving outside the wrapper (or to browser chrome)
+        if ((!e.relatedTarget || !wrapper.contains(e.relatedTarget)) && button.classList.contains('is-active')) {
+          button.click(); // Close the dropdown
+        }
+      };
+      addHandler(customList, 'focusout', listFocusoutHandler);
+
+      // Track open/close state via .is-active class on button
+      const observer = new MutationObserver(() => {
+        const isActive = button.classList.contains('is-active');
+
+        updateExpandedState(isActive);
+
+        if (isActive) {
+          // Make all options tabbable when opened
+          const options = customList.querySelectorAll('[role="option"]');
+          options.forEach(opt => {
+            opt.setAttribute('tabindex', '0');
+          });
+        } else {
+          // Return focus to button BEFORE aria changes if it was in the list
+          if (document.activeElement?.closest('[data-hs-form="select-list"]') === customList) {
+            button.focus();
           }
-        });
+
+          // Reset on close
+          button.removeAttribute('aria-activedescendant');
+          const options = customList.querySelectorAll('[role="option"]');
+          options.forEach(opt => {
+            opt.setAttribute('tabindex', '-1');
+          });
+        }
       });
 
-      // Observe the custom list for visibility changes
-      observer.observe(customList, {
+      // Observe the button for .is-active class changes
+      observer.observe(button, {
         attributes: true,
-        attributeFilter: ['hidden', 'style', 'class']
+        attributeFilter: ['class']
       });
       addObserver(observer);
 
@@ -300,7 +312,10 @@ export function init() {
       const selectChangeHandler = () => {
         const selectedOption = realSelect.options[realSelect.selectedIndex];
         if (selectedOption) {
-          const customOption = customList.querySelector(`[data-value="${selectedOption.value}"]`);
+          const options = customList.querySelectorAll('[role="option"]');
+          const customOption = Array.from(options).find(opt =>
+            opt.getAttribute('data-value') === selectedOption.value
+          );
           if (customOption) {
             // Update button text
             const text = customOption.querySelector('span')?.textContent || customOption.textContent;
@@ -310,7 +325,7 @@ export function init() {
             }
 
             // Update aria-selected
-            customList.querySelectorAll('[role="option"]').forEach(opt => {
+            options.forEach(opt => {
               opt.setAttribute('aria-selected', 'false');
             });
             customOption.setAttribute('aria-selected', 'true');