@hortonstudio/main 1.9.9 → 1.9.10

package/utils/before-after/README.md

@@ -1,8 +1,8 @@
-# **Before/After Image Comparison**
+# **Before/After Image Comparison Documentation**
 
 ## **Overview**
 
-Interactive before/after image comparison utility with multiple viewing modes, slider controls, and carousel functionality. Supports keyboard navigation, touch gestures, and accessibility features.
+Interactive before/after image comparison utility with multiple viewing modes, slider controls, and carousel functionality. Features full keyboard navigation, touch gestures, ARIA live announcements, and Barba.js compatibility.
 
 **Note:** This utility is loaded via `data-hs-util-ba` attribute on the script tag in index.js.
 
@@ -13,47 +13,129 @@ Interactive before/after image comparison utility with multiple viewing modes, s
 - **Three Viewing Modes**: Before, After, and Split (slider)
 - **Multiple Items**: Carousel navigation with arrows and pagination
 - **Slider Control**: Draggable slider with click-to-position
-- **Keyboard Support**: Arrow keys for navigation and slider control
-- **Touch Gestures**: Full mobile touch support
-- **Accessibility**: ARIA attributes and keyboard navigation
+- **Keyboard Support**: Full arrow key navigation and slider control
+- **Touch Gestures**: Complete mobile touch support
+- **Accessibility**: Live regions, proper ARIA attributes, semantic roles
+- **Memory Safe**: WeakMap-based references, proper cleanup for Barba.js
+- **Console Warnings**: Helpful warnings for missing required elements
 
 ---
 
-## **Required Elements**
+## **Required Structure**
 
-**Wrapper**
-* data-hs-ba="wrapper"
-* Container for entire before/after instance
+### **Wrapper** *(required)*
 
-**Image Wrapper**
-* data-hs-ba="image-wrapper"
-* Container for before/after images
-* Focusable for keyboard slider control
+**Attribute:** `data-hs-ba="wrapper"`
 
-**Before Image**
-* data-hs-ba="image-before"
-* Background/base image layer
+**What it does:** Main container for entire before/after instance. Automatically receives:
+- `role="region"`
+- `aria-roledescription="image comparison carousel"`
+- `aria-label` with keyboard instructions
+- Live region for announcing state changes
 
-**After Image**
-* data-hs-ba="image-after"
-* Foreground image with clip-path
+---
+
+### **Image Wrapper** *(required)*
 
-**Slider** *(optional)*
-* data-hs-ba="slider"
-* Draggable handle for split view
+**Attribute:** `data-hs-ba="image-wrapper"`
 
-**Mode Buttons** *(optional)*
-* data-hs-ba="mode-before"
-* data-hs-ba="mode-after"
-* data-hs-ba="mode-split"
+**What it does:** Container for before/after images. Made focusable for keyboard slider control.
+- `tabindex="0"` for keyboard focus
+- `role="img"` for semantics
+- Arrow keys adjust slider position when focused (in split mode)
+
+---
 
-**Navigation** *(optional, for multiple items)*
-* data-hs-ba="left" - Previous item
-* data-hs-ba="right" - Next item
+### **Before Image** *(required)*
 
-**Pagination** *(optional)*
-* data-hs-ba="pagination"
-* Container with template dot (first child)
+**Attribute:** `data-hs-ba="image-before"`
+
+**What it does:** Background/base image layer. Always visible behind the after image.
+
+---
+
+### **After Image** *(required)*
+
+**Attribute:** `data-hs-ba="image-after"`
+
+**What it does:** Foreground image with clip-path animation. Reveals/hides based on mode and slider position.
+
+---
+
+### **Slider** *(optional)*
+
+**Attribute:** `data-hs-ba="slider"`
+
+**What it does:** Draggable handle for split view mode. Hidden in before/after modes.
+- Supports mouse and touch dragging
+- Click anywhere on image wrapper to reposition
+
+---
+
+### **Mode Buttons** *(optional)*
+
+**Attributes:**
+- `data-hs-ba="mode-before"`
+- `data-hs-ba="mode-split"`
+- `data-hs-ba="mode-after"`
+
+**What they do:** Switch between viewing modes. Must use Global/Button component pattern:
+
+**Typical element layout:**
+
+1. Mode Wrapper (data-hs-ba="mode-before/split/after")
+   1. Style Element (has data-button-style attribute as descendant)
+   2. Clickable Wrapper (data-site-clickable="element")
+      1. Actual Button Element (first child)
+
+**What JavaScript does:**
+- Finds `[data-site-clickable="element"]` and gets `.children[0]` for actual button
+- Adds descriptive `aria-label` ("Switch to before view", etc.)
+- Manages `aria-pressed` state (true/false)
+- Finds descendant with `data-button-style` and updates between "primary"/"secondary"
+- Announces mode changes via live region
+
+---
+
+### **Navigation Arrows** *(optional, for multiple items)*
+
+**Attributes:**
+- `data-hs-ba="left-arrow"` - Previous item
+- `data-hs-ba="right-arrow"` - Next item
+
+**What they do:** Navigate between carousel items. Must use Global/Clickable component pattern:
+
+**Typical element layout:**
+
+1. Arrow Wrapper (data-hs-ba="left-arrow" or "right-arrow")
+   1. Clickable Wrapper (data-site-clickable="element")
+      1. Link or Button Element (first child)
+
+**What JavaScript does:**
+- Finds `[data-site-clickable="element"]` and gets `.children[0]`
+- Adds `aria-label` ("Previous image" or "Next image")
+- Loops through items infinitely
+- Announces slide changes via live region
+
+---
+
+### **Pagination** *(optional)*
+
+**Attribute:** `data-hs-ba="pagination"`
+
+**What it does:** Displays dots for each item. Requires template dot as first child.
+
+**Typical element layout:**
+
+1. Pagination Container (data-hs-ba="pagination")
+   1. Template Dot (first child, will be cloned)
+
+**What JavaScript does:**
+- Clones first child for each item
+- Adds `role="group"` and `aria-label="Image pagination"` to container
+- Adds `role="button"`, `tabindex="0"`, `aria-label` to each dot
+- Manages `is-active` class and `aria-current="true"` state
+- Keyboard accessible (Enter/Space to activate)
 
 ---
 
@@ -71,10 +153,30 @@ Interactive before/after image comparison utility with multiple viewing modes, s
     </div>
   </div>
 
-  <!-- Mode buttons -->
-  <button data-hs-ba="mode-before">Before</button>
-  <button data-hs-ba="mode-split">Split</button>
-  <button data-hs-ba="mode-after">After</button>
+  <!-- Mode buttons (using Global/Button components) -->
+  <div data-hs-ba="mode-before" data-site-button="wrapper">
+    <div data-button-style="secondary">
+      <div data-site-clickable="element">
+        <button type="button">Before</button>
+      </div>
+    </div>
+  </div>
+
+  <div data-hs-ba="mode-split" data-site-button="wrapper">
+    <div data-button-style="primary">
+      <div data-site-clickable="element">
+        <button type="button">Split</button>
+      </div>
+    </div>
+  </div>
+
+  <div data-hs-ba="mode-after" data-site-button="wrapper">
+    <div data-button-style="secondary">
+      <div data-site-clickable="element">
+        <button type="button">After</button>
+      </div>
+    </div>
+  </div>
 </div>
 ```
 
@@ -87,34 +189,47 @@ Interactive before/after image comparison utility with multiple viewing modes, s
   <!-- Item 1 -->
   <div>
     <div data-hs-ba="image-wrapper">
-      <img data-hs-ba="image-before" src="before-1.jpg">
-      <img data-hs-ba="image-after" src="after-1.jpg">
+      <img data-hs-ba="image-before" src="before-1.jpg" alt="Before">
+      <img data-hs-ba="image-after" src="after-1.jpg" alt="After">
       <div data-hs-ba="slider"></div>
     </div>
-    <button data-hs-ba="mode-before">Before</button>
-    <button data-hs-ba="mode-split">Split</button>
-    <button data-hs-ba="mode-after">After</button>
+
+    <!-- Mode buttons for this item -->
+    <div data-hs-ba="mode-before" data-site-button="wrapper">...</div>
+    <div data-hs-ba="mode-split" data-site-button="wrapper">...</div>
+    <div data-hs-ba="mode-after" data-site-button="wrapper">...</div>
   </div>
 
   <!-- Item 2 -->
   <div>
     <div data-hs-ba="image-wrapper">
-      <img data-hs-ba="image-before" src="before-2.jpg">
-      <img data-hs-ba="image-after" src="after-2.jpg">
+      <img data-hs-ba="image-before" src="before-2.jpg" alt="Before">
+      <img data-hs-ba="image-after" src="after-2.jpg" alt="After">
       <div data-hs-ba="slider"></div>
     </div>
-    <button data-hs-ba="mode-before">Before</button>
-    <button data-hs-ba="mode-split">Split</button>
-    <button data-hs-ba="mode-after">After</button>
+
+    <!-- Mode buttons for this item -->
+    <div data-hs-ba="mode-before" data-site-button="wrapper">...</div>
+    <div data-hs-ba="mode-split" data-site-button="wrapper">...</div>
+    <div data-hs-ba="mode-after" data-site-button="wrapper">...</div>
   </div>
 
   <!-- Navigation -->
-  <button data-hs-ba="left">Previous</button>
-  <button data-hs-ba="right">Next</button>
+  <div data-hs-ba="left-arrow">
+    <div data-site-clickable="element">
+      <a href="#">Previous</a>
+    </div>
+  </div>
+
+  <div data-hs-ba="right-arrow">
+    <div data-site-clickable="element">
+      <a href="#">Next</a>
+    </div>
+  </div>
 
   <!-- Pagination -->
   <div data-hs-ba="pagination">
-    <div class="dot"></div> <!-- Template -->
+    <button class="dot"></button> <!-- Template -->
   </div>
 </div>
 ```
@@ -127,29 +242,41 @@ Interactive before/after image comparison utility with multiple viewing modes, s
 - Shows only the before image
 - Hides slider
 - Clips after image to 100% (invisible)
+- Announces "Before view" to screen readers
 
 ### **After Mode**
 - Shows only the after image
 - Hides slider
 - Clips after image to 0% (fully visible)
+- Announces "After view" to screen readers
 
 ### **Split Mode** *(default)*
 - Shows both images side by side
 - Slider visible and draggable
 - Default split at 50%
-- Clicking split mode button resets to 50%
+- Clicking split mode button when already in split mode resets to 50%
+- Announces "Split view" to screen readers
 
 ---
 
 ## **Keyboard Navigation**
 
 ### **Main Wrapper Focus:**
-- `Arrow Left/Right/Up/Down`: Navigate between items
+- `Arrow Left/Right/Up/Down`: Navigate between carousel items
+- Focus returns to wrapper after slide change
 
 ### **Image Wrapper Focus:**
-- `Arrow Left`: Move slider left (in split mode)
-- `Arrow Right`: Move slider right (in split mode)
-- Step size: 5% per press (configurable)
+- `Arrow Left`: Move slider left 5% (in split mode only)
+- `Arrow Right`: Move slider right 5% (in split mode only)
+- Step size configurable via `keyboardStep` config
+
+### **Mode Buttons:**
+- `Enter` or `Space`: Activate button
+- `aria-pressed` state reflects active mode
+
+### **Pagination Dots:**
+- `Tab`: Navigate between dots
+- `Enter` or `Space`: Jump to that slide
 
 ---
 
@@ -200,44 +327,194 @@ window.hsmain.utilBeforeAfter.updateConfig({
 
 ---
 
+## **Key Attributes Summary**
+
+| Attribute | Purpose | Required | Element Type |
+| ----- | ----- | ----- | ----- |
+| `data-hs-ba="wrapper"` | Main container | **Required** | Wrapper div |
+| `data-hs-ba="image-wrapper"` | Images container | **Required** | Wrapper div |
+| `data-hs-ba="image-before"` | Before image | **Required** | `<img>` |
+| `data-hs-ba="image-after"` | After image | **Required** | `<img>` |
+| `data-hs-ba="slider"` | Slider handle | Optional | Wrapper div |
+| `data-hs-ba="mode-before"` | Before button wrapper | Optional | Wrapper div |
+| `data-hs-ba="mode-split"` | Split button wrapper | Optional | Wrapper div |
+| `data-hs-ba="mode-after"` | After button wrapper | Optional | Wrapper div |
+| `data-hs-ba="left-arrow"` | Previous button wrapper | Optional | Wrapper div |
+| `data-hs-ba="right-arrow"` | Next button wrapper | Optional | Wrapper div |
+| `data-hs-ba="pagination"` | Pagination container | Optional | Wrapper div |
+| `data-site-clickable="element"` | Interactive element wrapper | Required for buttons | Wrapper div |
+
+---
+
 ## **Accessibility Features**
 
-- Wrapper has `role="application"` with descriptive aria-label
-- Image wrapper has `role="img"` and keyboard instructions
-- Pagination dots have proper ARIA attributes
-- All interactive elements are keyboard accessible
-- Focus management between items
-- Slider position persists across item navigation
+### **ARIA Live Regions**
+- Dynamically created live region for announcements
+- Announces mode changes: "Before view", "After view", "Split view"
+- Announces slide changes: "Image 2 of 3"
+- Uses `aria-live="polite"` and `aria-atomic="true"`
+
+### **Semantic Roles**
+- Wrapper: `role="region"` with `aria-roledescription="image comparison carousel"`
+- Image wrapper: `role="img"` with descriptive `aria-label`
+- Pagination: `role="group"` with `aria-label="Image pagination"`
+- Dots: `role="button"` with `aria-current` state
+
+### **Button States**
+- Mode buttons: `aria-pressed="true"` for active, `"false"` for inactive
+- Mode buttons: Descriptive `aria-label` for each mode
+- Arrow buttons: `aria-label="Previous image"` / `"Next image"`
+- Pagination dots: `aria-current="true"` for active page
+
+### **Focus Management**
+- Wrapper and image wrapper are keyboard focusable
+- Tab key navigates through all interactive elements
+- Focus remains on controls during interaction
+
+### **Memory Safety**
+- Uses WeakMap for storing DOM references (prevents memory leaks)
+- Proper cleanup on destroy for Barba.js page transitions
+- Global event handlers set up once at module level
 
 ---
 
 ## **Touch Support**
 
-- Drag slider handle on touch devices
-- Click/tap image wrapper to position slider
-- Touch-friendly navigation buttons
-- Prevents default scroll during drag
+- **Drag slider handle**: Touch and drag to adjust position
+- **Click/tap to position**: Click/tap anywhere on image wrapper to move slider
+- **Touch-friendly controls**: All buttons and dots are touch accessible
+- **Prevents scroll**: Prevents default scroll behavior during drag
+
+---
+
+## **Console Warnings**
+
+The utility provides helpful warnings for missing required elements:
+
+- `[hs-before-after] Wrapper element has no child items`
+- `[hs-before-after] Missing required element in item X: data-hs-ba="image-wrapper"`
+- `[hs-before-after] Missing required element in item X: data-hs-ba="image-before"`
+- `[hs-before-after] Missing required element in item X: data-hs-ba="image-after"`
+
+Optional elements (slider, mode buttons, navigation, pagination) do not trigger warnings.
+
+---
+
+## **Barba.js Compatibility**
+
+The utility is fully compatible with Barba.js page transitions:
+
+### **On Destroy:**
+1. Resets global drag state
+2. Removes dynamically created live region elements
+3. Clears cached elements (WeakMap and Map)
+4. Removes all event listeners via clone-and-replace
+5. Strips accessibility attributes from wrappers
+6. Removes `data-initialized` markers
+7. Cleans up window API
+
+### **On Reinitialize:**
+1. Finds fresh wrappers on new page
+2. Creates new instances
+3. Reuses existing global event handlers (no duplicates)
+4. Applies all accessibility features to new elements
+
+### **Global Event Handlers:**
+- Mouse/touch drag handlers attached once at module level
+- Shared across all page transitions
+- Only execute when `globalDragInstance` exists
+- No memory leaks or duplicate listeners
 
 ---
 
 ## **How It Works**
 
-1. **Initialization**: Finds all `[data-hs-ba="wrapper"]` elements
-2. **Instance Creation**: Each wrapper becomes independent instance
-3. **Carousel Setup**: Multiple items get navigation and pagination
-4. **Mode Management**: Buttons control image visibility via clip-path
-5. **Slider Dragging**: Mouse/touch events update clip-path in real-time
-6. **Keyboard Control**: Arrow keys navigate items and adjust slider
-7. **State Persistence**: Slider position maintained across item changes
+1. **Module Load**: Global event handlers attach to document (once)
+2. **Initialization**: Finds all `[data-hs-ba="wrapper"]` elements not yet initialized
+3. **Instance Creation**: Each wrapper becomes independent instance
+4. **Live Region**: Creates hidden ARIA live region for announcements
+5. **Accessibility Setup**: Adds all ARIA attributes and semantic roles
+6. **Carousel Setup**: Multiple items get navigation and pagination
+7. **Mode Management**: Buttons control image visibility via clip-path
+8. **Slider Dragging**: Global handlers update clip-path via `globalDragInstance`
+9. **Keyboard Control**: Arrow keys navigate items and adjust slider
+10. **State Persistence**: Slider position maintained across item changes
+11. **Cleanup**: Destroy removes all traces for clean Barba.js transitions
+
+---
+
+## **Clickable Element Pattern**
+
+**All interactive elements** (mode buttons, arrows) must follow this pattern:
+
+**For Buttons:**
+```html
+<div data-hs-ba="mode-split">
+  <div data-button-style="primary"> <!-- Found via querySelector -->
+    <div data-site-clickable="element">
+      <button type="button">Split</button> <!-- .children[0] -->
+    </div>
+  </div>
+</div>
+```
+
+**For Links:**
+```html
+<div data-hs-ba="left-arrow">
+  <div data-site-clickable="element">
+    <a href="#">Previous</a> <!-- .children[0] -->
+  </div>
+</div>
+```
+
+**Why:** JavaScript queries `[data-site-clickable="element"]` then gets `.children[0]` to find the actual interactive element. For mode buttons, it separately finds descendants with `[data-button-style]` for style updates. This allows wrapping for styling while maintaining consistent selection.
+
+---
+
+## **Common Issues**
+
+**Mode buttons not switching styles:**
+1. Ensure `data-button-style` attribute exists on a descendant element
+2. Verify button is first child of `[data-site-clickable="element"]`
+3. Check console for warnings about missing elements
+
+**Arrow buttons not working:**
+1. Ensure using `data-hs-ba="left-arrow"` and `data-hs-ba="right-arrow"` (not "left"/"right")
+2. Verify `[data-site-clickable="element"]` wrapper exists
+3. Check that first child is the actual link/button element
+
+**Slider not draggable:**
+1. Verify `data-hs-ba="image-wrapper"` exists
+2. Check that slider has `data-hs-ba="slider"` attribute
+3. Ensure in split mode (slider hidden in before/after modes)
+
+**Pagination dots not generated:**
+1. Ensure at least one template child exists in pagination container
+2. Check that wrapper has multiple items (single item hides pagination)
+3. Verify `data-hs-ba="pagination"` is on correct element
+
+**Console warnings appearing:**
+1. Only required elements trigger warnings: wrapper, image-wrapper, image-before, image-after
+2. Optional elements (slider, buttons, navigation) never trigger warnings
+3. Fix missing elements or ignore if intentionally omitted
+
+**Barba.js transitions not working:**
+1. Ensure `data-initialized` attribute is being removed on destroy
+2. Check that destroy function is being called
+3. Verify global event handlers not causing issues (they're safe to persist)
 
 ---
 
 ## **Notes**
 
 - Each wrapper is an independent instance
-- Slider position persists when navigating items
+- Slider position persists when navigating items across the carousel
+- Mode state persists when navigating items
 - Pagination automatically generated from items
-- First pagination dot used as template
+- First pagination child used as template (cloned for each item)
 - Supports any number of items (1+)
-- Cleanup on destroy for Barba.js compatibility
-- Caches DOM queries for performance
+- Single item hides navigation and pagination automatically
+- Using Global/Button and Global/Clickable components is recommended
+- Complete cleanup on destroy for Barba.js compatibility
+- WeakMap caching prevents memory leaks
+- Global drag handlers shared efficiently across instances and page transitions