@hortonstudio/main 1.9.10 → 1.9.20

package/src/modules/structure/functions/form/functions/select/README.md

@@ -0,0 +1,393 @@
+# **Custom Select Component**
+
+## **Overview**
+
+Fully accessible, styled select dropdowns that sync with native `<select>` elements for form submission. Features typeahead search, keyboard navigation, autofill support, and all modern accessibility requirements.
+
+---
+
+### **Required Elements**
+
+**Select Wrapper** _(main container)_
+
+- data-hs-form-select="wrapper"
+
+**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)_
+
+- data-hs-form-select="button"
+- Should contain a `<span>` element for displaying selected text
+- Webflow IX must add/remove `.is-active` class on this button for open/close animation
+- Script automatically adds/removes `.is-filled` class based on whether a value is selected
+
+**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="wrapper")
+   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 (data-hs-form-select="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, Home/End, Tab, Enter, Space, Escape support
+7. **Typeahead search** - Type to quickly navigate to options (native select behavior)
+8. **Focus management** - Handles focus return, tabbing out, and keyboard navigation
+9. **Value state tracking** - Adds/removes `.is-filled` class on button based on whether an actual value is selected
+10. **Disabled state sync** - Automatically disables button when native select is disabled
+11. **Form reset support** - Updates custom UI when form is reset via `<button type="reset">`
+12. **Autofill support** - Syncs with browser autofill and password managers
+
+### **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 (data-hs-form-select="button")
+   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.)
+
+**Class Behavior:**
+
+- `.is-active` - Controlled by Webflow IX for dropdown open/close animation state
+- `.is-filled` - Automatically controlled by script to indicate if a value is selected (use for placeholder-like styling)
+
+---
+
+## **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="wrapper">
+  <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 data-hs-form-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. **Home** � Open dropdown and focus first option
+5. **End** � Open dropdown and focus last option
+6. **Escape** � Close dropdown (if open)
+7. **Alphanumeric keys** � Typeahead search (see below)
+
+### **When Option is Focused**
+
+1. **ArrowDown** � Focus next option
+2. **ArrowUp** � Focus previous option (or close and focus button if on first option)
+3. **Home** � Jump to first option
+4. **End** � Jump to last option
+5. **Enter** or **Space** � Select option and close dropdown
+6. **Escape** � Close dropdown and return focus to button
+7. **Tab** � Navigate through options, tab out of last option closes dropdown
+8. **Alphanumeric keys** � Typeahead search (see below)
+
+### **Typeahead Search**
+
+The select supports native-like typeahead functionality:
+
+1. **Single character** � Jumps to first option starting with that letter
+2. **Repeated character** � Cycles through options starting with that letter
+   - Example: Press "B" → "Banana", press "B" again → "Blueberry", press "B" again → "Banana"
+3. **Multi-character** � Builds search string to find matches
+   - Example: Type "te" → "Texas", type "tenn" → "Tennessee"
+4. **Auto-reset** � Search string clears after 500ms of no typing
+5. **Works from button or list** � Typeahead works whether focused on button (opens dropdown) or within list
+6. **Auto-scroll** � Focused option automatically scrolls into view in scrollable lists
+7. **No backspace** � Matches native select behavior (wait for timeout to reset if you mistype)
+
+---
+
+## **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="wrapper"` | Select wrapper             | Wrapper div             |
+| `data-hs-form-select="button"`  | Toggle button for dropdown | Button element          |
+| `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. **Button attribute required** - Button must have `data-hs-form-select="button"` attribute
+4. **Template is removed** - First child of list is cloned then deleted
+5. **Webflow IX required** - Must toggle `.is-active` class on button for open/close animation
+6. **Auto class management** - Script automatically adds/removes `.is-filled` class based on value state
+7. **Barba.js compatible** - Automatically cleans up on destroy/reinitialize (including timeouts)
+8. **Silent failures** - Missing required elements cause function to return early (no errors)
+9. **Empty values supported** - Options with `value=""` work correctly (removes `.is-filled` class)
+10. **Special characters safe** - Handles quotes and special characters in option values
+11. **Typeahead search** - Matches native select behavior with 500ms timeout
+
+---
+
+## **v2.0.0 Improvements**
+
+### **JSON Config System**
+
+- Added config.js with all attribute definitions
+- Future-proof: Easy to add aliases or change attribute patterns
+- Self-documenting: All supported attributes in one place
+- Config-based selectors: `data-hs-form-select` attribute namespace
+
+### **Typeahead Search**
+
+- Native select-like typeahead functionality
+- Single letter cycling (press "B" repeatedly to cycle through "Banana", "Blueberry", etc.)
+- Multi-character search (type "tenn" to find "Tennessee")
+- 500ms auto-reset timeout
+- Works from both button and list focus states
+- Auto-scrolls focused option into view
+
+### **Value State Tracking**
+
+- Automatic `.is-filled` class management on button
+- Adds `.is-filled` when option with value is selected
+- Removes `.is-filled` when empty/default option selected
+- Enables placeholder-like CSS styling based on value state
+
+### **Enhanced Keyboard Navigation**
+
+- **Home/End keys** - Jump to first/last option (matches native select)
+- Works from both button and list focus states
+- Auto-opens dropdown if closed
+
+### **Disabled State Synchronization**
+
+- Automatically syncs button disabled state with native select
+- Observes `disabled` attribute changes on native select
+- Sets `aria-disabled` for accessibility
+- Prevents interaction when disabled
+
+### **Form Integration**
+
+- **Form reset support** - Listens for form `reset` event, syncs custom UI to default values
+- **Autofill support** - Listens for `input` events to catch browser autofill and password managers
+- **Autocomplete attribute** - Use standard `autocomplete` attribute on native select for proper autofill
+
+### **Barba.js / SPA Compatibility**
+
+The form system is fully compatible with Barba.js and other SPA frameworks:
+
+- Proper cleanup on destroy (removes all event listeners, observers, and timeouts)
+- Fresh initialization on reinitialize
+- Syncs custom select state with native select on new pages
+- Works like fresh page load on new DOM
+
+---
+
+## **Common Issues**
+
+**Dropdown not opening:**
+
+1. Verify Webflow IX adds `.is-active` class to button (not wrapper or list)
+2. Check that button has `data-hs-form-select="button"` attribute
+3. Ensure 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="wrapper"` 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