@hortonstudio/main 1.9.10 → 1.9.20

package/utils/before-after/README.md

@@ -1,520 +0,0 @@
-# **Before/After Image Comparison Documentation**
-
-## **Overview**
-
-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.
-
----
-
-## **Features**
-
-- **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**: 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 Structure**
-
-### **Wrapper** *(required)*
-
-**Attribute:** `data-hs-ba="wrapper"`
-
-**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
-
----
-
-### **Image Wrapper** *(required)*
-
-**Attribute:** `data-hs-ba="image-wrapper"`
-
-**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)
-
----
-
-### **Before Image** *(required)*
-
-**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)
-
----
-
-## **Usage Example**
-
-### **Single Comparison**
-
-```html
-<div data-hs-ba="wrapper">
-  <div data-hs-ba="image-wrapper">
-    <img data-hs-ba="image-before" src="before.jpg" alt="Before">
-    <img data-hs-ba="image-after" src="after.jpg" alt="After">
-    <div data-hs-ba="slider">
-      <!-- Slider handle content -->
-    </div>
-  </div>
-
-  <!-- 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>
-```
-
----
-
-### **Multiple Items with Carousel**
-
-```html
-<div data-hs-ba="wrapper">
-  <!-- Item 1 -->
-  <div>
-    <div data-hs-ba="image-wrapper">
-      <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>
-
-    <!-- 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" alt="Before">
-      <img data-hs-ba="image-after" src="after-2.jpg" alt="After">
-      <div data-hs-ba="slider"></div>
-    </div>
-
-    <!-- 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 -->
-  <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">
-    <button class="dot"></button> <!-- Template -->
-  </div>
-</div>
-```
-
----
-
-## **Viewing Modes**
-
-### **Before Mode**
-- 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 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 carousel items
-- Focus returns to wrapper after slide change
-
-### **Image Wrapper Focus:**
-- `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
-
----
-
-## **Configuration**
-
-Default configuration can be updated via `window.hsmain.utilBeforeAfter.updateConfig()`:
-
-```javascript
-{
-  defaultMode: "split",           // Initial viewing mode
-  sliderPosition: 50,             // Default slider position (%)
-  touchSensitivity: 1,            // Touch drag sensitivity
-  keyboardStep: 5,                // Keyboard arrow step (%)
-  autoPlay: false,                // Auto-advance items
-  autoPlayInterval: 5000          // Auto-play interval (ms)
-}
-```
-
----
-
-## **API Methods**
-
-Accessible via `window.hsmain.utilBeforeAfter`:
-
-### **showSlide(instanceId, index)**
-Navigate to specific item in carousel
-
-```javascript
-window.hsmain.utilBeforeAfter.showSlide(0, 2); // Go to third item
-```
-
-### **setMode(instanceId, mode)**
-Change viewing mode programmatically
-
-```javascript
-window.hsmain.utilBeforeAfter.setMode(0, 'before');
-```
-
-### **updateConfig(newConfig)**
-Update global configuration
-
-```javascript
-window.hsmain.utilBeforeAfter.updateConfig({
-  sliderPosition: 60,
-  keyboardStep: 10
-});
-```
-
----
-
-## **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**
-
-### **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**: 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. **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 across the carousel
-- Mode state persists when navigating items
-- Pagination automatically generated from items
-- First pagination child used as template (cloned for each item)
-- Supports any number of items (1+)
-- 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