@hortonstudio/main 1.9.11 → 1.9.20

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

@@ -0,0 +1,451 @@
+# **Accordion Accessibility**
+
+## **Overview**
+
+Universal accordion system for FAQ, summary/read-more, and general toggle components. Automatically manages ARIA attributes, visual state, and optional text swapping.
+
+**This function handles all accordion/toggle patterns with a single unified system.**
+
+---
+
+## **Required Elements**
+
+**Accordion Wrapper** _(container and state manager)_
+
+- `data-hs-accordion="wrapper"`
+- Gets `is-active` class when open
+- Optional: `data-hs-accordion-default="open"` - Start in open state
+- Optional: `data-hs-accordion-open="Close"` - Text for open state
+- Optional: `data-hs-accordion-closed="Open"` - Text for closed state
+
+**Accordion Toggle Button** _(clickable trigger)_
+
+- `data-hs-accordion="toggle"`
+- Must be a `<button>` element
+- Receives click handler and ARIA attributes
+
+**Accordion Content** _(expandable area)_
+
+- `data-hs-accordion="content"`
+- Contains the content that expands/collapses
+
+**State Text Elements** _(optional - for text swapping)_
+
+- `data-hs-accordion-text="state"`
+- Text content swaps between open/closed values
+- Requires open/closed attributes on wrapper
+
+---
+
+## **How It Works**
+
+### **State Management:**
+
+1. Button click toggles `is-active` class on wrapper
+2. MutationObserver watches wrapper for class changes
+3. When `is-active` changes, ARIA attributes update
+4. Text elements with `[data-hs-accordion-text="state"]` update if configured
+5. Content height animates to auto (open) or 0 (closed) via GSAP
+
+### **ARIA Updates:**
+
+- `aria-expanded` on button (true/false)
+- `aria-hidden` on content (true/false)
+- `aria-controls` links button to content
+- `role="region"` on content
+- No `aria-label` - button text is used directly
+
+### **Animation:**
+
+- Uses GSAP (loaded globally via Webflow)
+- Animates content `height` from 0 to auto (0.3s, power2.inOut)
+- Initial state set without animation
+- All animations killed on destroy (SPA safe)
+- Gracefully degrades if GSAP not available
+
+### **Focus Management:**
+
+- When closing, if focus is inside content, focus returns to button first
+- Then ARIA updates apply
+- Prevents keyboard users from losing focus
+
+---
+
+## **Usage Examples**
+
+### **Standard FAQ (No Text Swap)**
+
+```html
+<div data-hs-accordion="wrapper">
+  <h3>
+    <button data-hs-accordion="toggle">
+      What is this product?
+      <span aria-hidden="true">▼</span>
+    </button>
+  </h3>
+  <div data-hs-accordion="content">
+    <p>This is a detailed answer about the product...</p>
+  </div>
+</div>
+```
+
+**Result:**
+
+- Only `aria-expanded` changes on button ✅
+- Button text stays static ✅
+- Arrow provides visual indicator ✅
+- Screen reader: "What is this product?, button, collapsed/expanded"
+
+---
+
+### **FAQ with Default Open**
+
+```html
+<div data-hs-accordion="wrapper" data-hs-accordion-default="open">
+  <h3>
+    <button data-hs-accordion="toggle">What is this product?</button>
+  </h3>
+  <div data-hs-accordion="content">
+    <p>This is a detailed answer...</p>
+  </div>
+</div>
+```
+
+**Result:**
+
+- Accordion starts in open state ✅
+- `is-active` class applied on page load ✅
+
+---
+
+### **Show/Hide Toggle (With Text Swap)**
+
+```html
+<div
+  data-hs-accordion="wrapper"
+  data-hs-accordion-open="Hide Details"
+  data-hs-accordion-closed="Show Details"
+>
+  <div>
+    <button data-hs-accordion="toggle">
+      <span data-hs-accordion-text="state">Show Details</span>
+      <span aria-hidden="true">▼</span>
+    </button>
+  </div>
+  <div data-hs-accordion="content">
+    <p>Product specifications and details...</p>
+  </div>
+</div>
+```
+
+**Result:**
+
+- Span text swaps: "Show Details" ↔ "Hide Details" ✅
+- `aria-expanded` still provides semantic state ✅
+- Visual text matches current action ✅
+
+---
+
+### **Complex Accordion with State Indicator**
+
+```html
+<div data-hs-accordion="wrapper" data-hs-accordion-open="Close" data-hs-accordion-closed="Open">
+  <h3>
+    <button data-hs-accordion="toggle">
+      <span>Frequently Asked Question</span>
+      <span aria-hidden="true">
+        <span data-hs-accordion-text="state">Open</span>
+        <span class="arrow">→</span>
+      </span>
+    </button>
+  </h3>
+  <div data-hs-accordion="content">
+    <p>Answer content here...</p>
+  </div>
+</div>
+```
+
+**Result:**
+
+- Question text stays visible ✅
+- State indicator swaps: "Open" ↔ "Close" ✅
+- State container has `aria-hidden="true"` to prevent duplication ✅
+- Screen reader only announces question + expanded state ✅
+
+---
+
+### **Nested Accordions**
+
+```html
+<div data-hs-accordion="wrapper">
+  <h2>
+    <button data-hs-accordion="toggle">Product Details</button>
+  </h2>
+  <div data-hs-accordion="content">
+    <p>Product information...</p>
+
+    <!-- Nested accordion -->
+    <div data-hs-accordion="wrapper">
+      <h3>
+        <button data-hs-accordion="toggle">Shipping Questions</button>
+      </h3>
+      <div data-hs-accordion="content">
+        <p>Shipping details...</p>
+      </div>
+    </div>
+  </div>
+</div>
+```
+
+**Result:**
+
+- Each accordion manages its own state independently ✅
+- Focus returns to parent when parent closes ✅
+- Full keyboard navigation support ✅
+
+---
+
+## **Key Attributes**
+
+| Attribute                          | Element     | Purpose                         | Required |
+| ---------------------------------- | ----------- | ------------------------------- | -------- |
+| `data-hs-accordion="wrapper"`      | Container   | Holds state (`is-active` class) | Yes      |
+| `data-hs-accordion="toggle"`       | `<button>`  | Clickable trigger               | Yes      |
+| `data-hs-accordion="content"`      | Container   | Expandable content area         | Yes      |
+| `data-hs-accordion-default="open"` | Wrapper     | Start in open state             | No       |
+| `data-hs-accordion-open`           | Wrapper     | Text for open state             | No\*     |
+| `data-hs-accordion-closed`         | Wrapper     | Text for closed state           | No\*     |
+| `data-hs-accordion-text="state"`   | Any element | Text content will swap          | No\*     |
+
+**Note:** `open`, `closed`, and `state` attributes work together - all three required for text swapping.
+
+---
+
+## **Text Swapping System**
+
+### **When to Use:**
+
+- Show/Hide toggles
+- Read More/Read Less buttons
+- Any toggle where button text should change
+
+### **When NOT to Use:**
+
+- FAQ items (question should stay visible)
+- Accordions with static headings
+- When arrow/icon is sufficient visual indicator
+
+### **Requirements:**
+
+1. `data-hs-accordion-open` on wrapper (text for open state)
+2. `data-hs-accordion-closed` on wrapper (text for closed state)
+3. `data-hs-accordion-text="state"` on elements that should swap
+
+### **How It Works:**
+
+- Finds all `[data-hs-accordion-text="state"]` inside button
+- Updates `textContent` of those elements based on state
+- Multiple elements can have `state` attribute
+- Text swaps instantly when state changes
+
+---
+
+## **Accessibility Features**
+
+### **ARIA Attributes:**
+
+- ✅ `aria-expanded` on button (announces open/closed state)
+- ✅ `aria-controls` links button to content
+- ✅ `aria-hidden` on content (hides from screen readers when closed)
+- ✅ `role="region"` on content (landmark for navigation)
+- ✅ `aria-labelledby` on content (associates with button)
+- ✅ Unique IDs generated automatically
+
+### **Keyboard Support:**
+
+- ✅ Button is natively focusable
+- ✅ Enter/Space toggles accordion
+- ✅ Focus returns to button when closing if focus was inside content
+- ✅ Tab navigation works correctly
+
+### **Screen Reader Announcements:**
+
+- Closed: "Question text, button, collapsed"
+- Open: "Question text, button, expanded"
+- No redundant announcements from visual state indicators
+
+---
+
+## **Best Practices**
+
+### **Semantic HTML:**
+
+```html
+<!-- Good: Heading wraps button -->
+<h3>
+  <button data-hs-accordion="toggle">Question</button>
+</h3>
+
+<!-- Bad: Button inside div -->
+<div>
+  <button data-hs-accordion="toggle">Question</button>
+</div>
+```
+
+### **Visual State Indicators:**
+
+```html
+<!-- Good: Hidden from screen readers -->
+<button data-hs-accordion="toggle">
+  <span>Question</span>
+  <span aria-hidden="true">▼</span>
+</button>
+
+<!-- Bad: Not hidden -->
+<button data-hs-accordion="toggle">
+  <span>Question</span>
+  <span>▼</span>
+</button>
+```
+
+### **State Text:**
+
+```html
+<!-- Good: State container hidden -->
+<button data-hs-accordion="toggle">
+  <span>Question</span>
+  <span aria-hidden="true">
+    <span data-hs-accordion-text="state">Open</span>
+  </span>
+</button>
+
+<!-- Bad: State text not hidden, causes redundancy -->
+<button data-hs-accordion="toggle">
+  <span>Question</span>
+  <span data-hs-accordion-text="state">Open</span>
+</button>
+```
+
+---
+
+## **Barba.js / SPA Compatibility**
+
+The accordion system is fully compatible with Barba.js and other SPA frameworks:
+
+**On Initialize:**
+
+- Adds click handlers to all buttons
+- Sets up MutationObservers on all wrappers
+- Applies default states
+- Syncs initial ARIA
+
+**On Destroy:**
+
+- Removes all click event listeners
+- Disconnects all MutationObservers
+- Cleans up tracking arrays
+- Safe for page transitions
+
+**No memory leaks or orphaned listeners!** ✅
+
+---
+
+## **Common Patterns**
+
+### **FAQ List:**
+
+```html
+<!-- No text swap, just arrow indicators -->
+<div data-hs-accordion="wrapper">
+  <h3>
+    <button data-hs-accordion="toggle">
+      Question text?
+      <span aria-hidden="true">▼</span>
+    </button>
+  </h3>
+  <div data-hs-accordion="content">
+    <p>Answer text...</p>
+  </div>
+</div>
+```
+
+### **Read More Toggle:**
+
+```html
+<!-- Text swaps for "Read More" / "Read Less" -->
+<div
+  data-hs-accordion="wrapper"
+  data-hs-accordion-open="Read Less"
+  data-hs-accordion-closed="Read More"
+>
+  <button data-hs-accordion="toggle">
+    <span data-hs-accordion-text="state">Read More</span>
+  </button>
+  <div data-hs-accordion="content">
+    <p>Full content here...</p>
+  </div>
+</div>
+```
+
+### **Show/Hide Details:**
+
+```html
+<!-- Text and visual indicator both swap -->
+<div
+  data-hs-accordion="wrapper"
+  data-hs-accordion-open="Hide Details"
+  data-hs-accordion-closed="Show Details"
+>
+  <button data-hs-accordion="toggle">
+    <span data-hs-accordion-text="state">Show Details</span>
+    <span aria-hidden="true"> <span data-hs-accordion-text="state">Show</span> → </span>
+  </button>
+  <div data-hs-accordion="content">
+    <p>Details content...</p>
+  </div>
+</div>
+```
+
+---
+
+## **Troubleshooting**
+
+**Accordion not opening:**
+
+- Ensure `is-active` class is defined in CSS
+- Check that wrapper has `data-hs-accordion="wrapper"`
+- Verify button has `data-hs-accordion="toggle"`
+
+**Text not swapping:**
+
+- Ensure both `data-hs-accordion-open` and `data-hs-accordion-closed` are present
+- Verify elements have `data-hs-accordion-text="state"`
+- Check that state elements are inside the button
+
+**Focus issues:**
+
+- Focus return only works when closing
+- Only triggers if focus is inside content area
+- Button must be focusable (not disabled)
+
+**ARIA not updating:**
+
+- Check browser console for warnings
+- Ensure toggle is a `<button>` element
+- Verify content element exists
+
+---
+
+## **Version**
+
+**Current version:** 2.0.0
+
+**Breaking changes from v1.x:**
+
+- Removed `data-site-clickable` wrapper pattern
+- Removed `data-hs-accordion-text-swap` attribute
+- Added `data-hs-accordion-open` and `data-hs-accordion-closed`
+- Added `data-hs-accordion-text="state"` for selective text swapping
+- `is-active` now on wrapper instead of toggle
+- Toggle must be `<button>` element directly
+- No longer updates `aria-label` (uses button text directly)

package/src/modules/default/functions/accordion/accordion.ts

@@ -0,0 +1,189 @@
+import {
+  querySelectorAll,
+  querySelector,
+  getSelector,
+  globalConfig,
+  animateHeight,
+  setHeight,
+} from '@utils';
+
+export function init(config) {
+  const cleanup = {
+    observers: [],
+    handlers: [],
+    liveRegions: [],
+  };
+
+  const addObserver = (observer) => cleanup.observers.push(observer);
+  const addHandler = (element, event, handler, options) => {
+    element.addEventListener(event, handler, options);
+    cleanup.handlers.push({ element, event, handler, options });
+  };
+
+  function setupAccordionAccessibility(addObserver, addHandler) {
+    const accordionWrappers = querySelectorAll(config, 'wrapper');
+
+    if (accordionWrappers.length === 0) {
+      return 0;
+    }
+
+    let initializedCount = 0;
+
+    accordionWrappers.forEach((wrapper, index) => {
+      const button = querySelector(config, 'toggle', wrapper);
+      const content = querySelector(config, 'content', wrapper);
+
+      if (!button || !content) {
+        return;
+      }
+
+      initializedCount++;
+
+      // Check for visual height wrapper (contains data-hs-height="element")
+      // If found, animate that instead of the content (content is for ARIA only)
+      const heightWrapper = wrapper.querySelector('[data-hs-height="element"]');
+      const animationTarget = heightWrapper ? heightWrapper.parentElement : content;
+
+      // Generate unique IDs
+      const buttonId = `hs-accordion-btn-${index}`;
+      const contentId = `hs-accordion-content-${index}`;
+
+      // Create live region for announcements
+      const liveRegion = document.createElement('div');
+      liveRegion.className = 'sr-only';
+      liveRegion.setAttribute('aria-live', 'polite');
+      liveRegion.setAttribute('aria-atomic', 'true');
+      liveRegion.style.cssText =
+        'position: absolute; left: -10000px; width: 1px; height: 1px; overflow: hidden;';
+      wrapper.appendChild(liveRegion);
+      cleanup.liveRegions.push(liveRegion);
+
+      // Get text state attributes (optional)
+      const openText = wrapper.getAttribute(config.attributes.properties.open);
+      const closedText = wrapper.getAttribute(config.attributes.properties.closed);
+      const hasTextSwap = openText && closedText;
+
+      // Find all state text elements (if text swap enabled)
+      let stateElements = [];
+      if (hasTextSwap) {
+        const stateSelector = getSelector(config, 'state');
+        stateElements = Array.from(button.querySelectorAll(stateSelector));
+      }
+
+      // Function to update state text elements
+      function updateStateText(text) {
+        if (!hasTextSwap) return;
+        stateElements.forEach((el) => {
+          el.textContent = text;
+        });
+      }
+
+      // Set initial IDs and ARIA attributes
+      button.setAttribute('id', buttonId);
+      content.setAttribute('id', contentId);
+      content.setAttribute('role', 'region');
+      content.setAttribute('aria-labelledby', buttonId);
+      button.setAttribute('aria-controls', contentId);
+
+      // Function to check if accordion is open
+      function isAccordionOpen() {
+        return wrapper.classList.contains(globalConfig.classes.active);
+      }
+
+      // Announce state change to screen readers
+      function announceStateChange(isOpen: boolean) {
+        const buttonText = button.textContent?.trim() || 'Section';
+        liveRegion.textContent = `${buttonText} ${isOpen ? 'expanded' : 'collapsed'}`;
+        setTimeout(() => (liveRegion.textContent = ''), 1000);
+      }
+
+      // Update ARIA states based on current visual state
+      function updateARIAStates() {
+        const isOpen = isAccordionOpen();
+        const wasOpen = button.getAttribute('aria-expanded') === 'true';
+
+        // If closing and focus is inside content, return focus first
+        if (wasOpen && !isOpen && content.contains(document.activeElement)) {
+          const buttonEl = button as HTMLElement;
+          buttonEl.focus();
+        }
+
+        // Update ARIA attributes
+        button.setAttribute('aria-expanded', isOpen ? 'true' : 'false');
+        const contentEl = content as HTMLElement;
+        contentEl.inert = !isOpen; // Use inert instead of aria-hidden
+
+        // Announce state change if it actually changed
+        if (isOpen !== wasOpen) {
+          announceStateChange(isOpen);
+        }
+
+        // Update state text if text swap enabled
+        if (hasTextSwap && stateElements.length > 0) {
+          updateStateText(isOpen ? openText : closedText);
+        }
+
+        // Animate height wrapper (visual container, not ARIA content)
+        animateHeight(animationTarget, isOpen, { duration: 300, ease: 'power2.inOut' });
+      }
+
+      // Handle default open state
+      const defaultState = wrapper.getAttribute(config.attributes.properties.default);
+      if (defaultState && defaultState.toLowerCase() === 'open') {
+        wrapper.classList.add(globalConfig.classes.active);
+      }
+
+      // Set initial height without animation
+      setHeight(animationTarget, isAccordionOpen());
+
+      // Set initial state based on existing is-active class
+      updateARIAStates();
+
+      // Add click handler to button
+      const clickHandler = (e: Event) => {
+        e.preventDefault();
+        wrapper.classList.toggle(globalConfig.classes.active);
+      };
+      addHandler(button, 'click', clickHandler);
+
+      // Monitor for class changes on wrapper
+      const observer = new MutationObserver(() => {
+        updateARIAStates();
+      });
+
+      observer.observe(wrapper, {
+        attributes: true,
+        attributeFilter: ['class'],
+      });
+
+      addObserver(observer);
+    });
+
+    return initializedCount;
+  }
+
+  setupAccordionAccessibility(addObserver, addHandler);
+
+  return {
+    result: 'accordion initialized',
+    destroy: () => {
+      // Remove all live regions
+      cleanup.liveRegions.forEach((liveRegion) => {
+        if (liveRegion.parentNode) {
+          liveRegion.parentNode.removeChild(liveRegion);
+        }
+      });
+      cleanup.liveRegions.length = 0;
+
+      // Disconnect all observers
+      cleanup.observers.forEach((obs) => obs.disconnect());
+      cleanup.observers.length = 0;
+
+      // Remove all event listeners
+      cleanup.handlers.forEach(({ element, event, handler, options }) => {
+        element.removeEventListener(event, handler, options);
+      });
+      cleanup.handlers.length = 0;
+    },
+  };
+}