@hortonstudio/main 1.9.8 → 1.9.9

package/index.js

@@ -25,8 +25,8 @@ const initializeHsMain = async () => {
 
   const moduleMap = {
     transition: () => import("./autoInit/transition/transition.js"),
-    "data-hs-util-ba": () => import("./utils/before-after.js"),
-    "data-hs-util-slider": () => import("./utils/slider.js"),
+    "data-hs-util-ba": () => import("./utils/before-after/before-after.js"),
+    "data-hs-util-slider": () => import("./utils/slider/slider.js"),
     "smooth-scroll": () => import("./autoInit/smooth-scroll/smooth-scroll.js"),
     navbar: () => import("./autoInit/navbar/navbar.js"),
     accessibility: () => import("./autoInit/accessibility/accessibility.js"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hortonstudio/main",
-  "version": "1.9.8",
+  "version": "1.9.9",
   "description": "Animation and utility library for client websites",
   "main": "index.js",
   "type": "module",

package/utils/before-after/README.md

@@ -0,0 +1,243 @@
+# **Before/After Image Comparison**
+
+## **Overview**
+
+Interactive before/after image comparison utility with multiple viewing modes, slider controls, and carousel functionality. Supports keyboard navigation, touch gestures, and accessibility features.
+
+**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**: Arrow keys for navigation and slider control
+- **Touch Gestures**: Full mobile touch support
+- **Accessibility**: ARIA attributes and keyboard navigation
+
+---
+
+## **Required Elements**
+
+**Wrapper**
+* data-hs-ba="wrapper"
+* Container for entire before/after instance
+
+**Image Wrapper**
+* data-hs-ba="image-wrapper"
+* Container for before/after images
+* Focusable for keyboard slider control
+
+**Before Image**
+* data-hs-ba="image-before"
+* Background/base image layer
+
+**After Image**
+* data-hs-ba="image-after"
+* Foreground image with clip-path
+
+**Slider** *(optional)*
+* data-hs-ba="slider"
+* Draggable handle for split view
+
+**Mode Buttons** *(optional)*
+* data-hs-ba="mode-before"
+* data-hs-ba="mode-after"
+* data-hs-ba="mode-split"
+
+**Navigation** *(optional, for multiple items)*
+* data-hs-ba="left" - Previous item
+* data-hs-ba="right" - Next item
+
+**Pagination** *(optional)*
+* data-hs-ba="pagination"
+* Container with template dot (first child)
+
+---
+
+## **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 -->
+  <button data-hs-ba="mode-before">Before</button>
+  <button data-hs-ba="mode-split">Split</button>
+  <button data-hs-ba="mode-after">After</button>
+</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">
+      <img data-hs-ba="image-after" src="after-1.jpg">
+      <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>
+  </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">
+      <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>
+  </div>
+
+  <!-- Navigation -->
+  <button data-hs-ba="left">Previous</button>
+  <button data-hs-ba="right">Next</button>
+
+  <!-- Pagination -->
+  <div data-hs-ba="pagination">
+    <div class="dot"></div> <!-- Template -->
+  </div>
+</div>
+```
+
+---
+
+## **Viewing Modes**
+
+### **Before Mode**
+- Shows only the before image
+- Hides slider
+- Clips after image to 100% (invisible)
+
+### **After Mode**
+- Shows only the after image
+- Hides slider
+- Clips after image to 0% (fully visible)
+
+### **Split Mode** *(default)*
+- Shows both images side by side
+- Slider visible and draggable
+- Default split at 50%
+- Clicking split mode button resets to 50%
+
+---
+
+## **Keyboard Navigation**
+
+### **Main Wrapper Focus:**
+- `Arrow Left/Right/Up/Down`: Navigate between items
+
+### **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)
+
+---
+
+## **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
+});
+```
+
+---
+
+## **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
+
+---
+
+## **Touch Support**
+
+- Drag slider handle on touch devices
+- Click/tap image wrapper to position slider
+- Touch-friendly navigation buttons
+- Prevents default scroll during drag
+
+---
+
+## **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
+
+---
+
+## **Notes**
+
+- Each wrapper is an independent instance
+- Slider position persists when navigating items
+- Pagination automatically generated from items
+- First pagination dot used as template
+- Supports any number of items (1+)
+- Cleanup on destroy for Barba.js compatibility
+- Caches DOM queries for performance

package/utils/{before-after.js → before-after/before-after.js}

@@ -1,3 +1,58 @@
+// Module-level state (shared across all inits)
+let globalDragInstance = null;
+const elementRefs = new WeakMap();
+
+// Global event handlers for drag operations
+function handleGlobalMouseMove(e) {
+  if (globalDragInstance) {
+    const rect = globalDragInstance.imageWrap.getBoundingClientRect();
+    const x = e.clientX - rect.left;
+    const percentage = Math.max(0, Math.min(100, (x / rect.width) * 100));
+
+    globalDragInstance.slider.style.left = `${percentage}%`;
+    globalDragInstance.updateSliderPosition(
+      globalDragInstance.instance,
+      globalDragInstance.instance.currentIndex,
+      percentage,
+    );
+    globalDragInstance.instance.sliderPosition = percentage;
+  }
+}
+
+function handleGlobalTouchMove(e) {
+  if (globalDragInstance) {
+    e.preventDefault();
+    const rect = globalDragInstance.imageWrap.getBoundingClientRect();
+    const x = e.touches[0].clientX - rect.left;
+    const percentage = Math.max(0, Math.min(100, (x / rect.width) * 100));
+
+    globalDragInstance.slider.style.left = `${percentage}%`;
+    globalDragInstance.updateSliderPosition(
+      globalDragInstance.instance,
+      globalDragInstance.instance.currentIndex,
+      percentage,
+    );
+    globalDragInstance.instance.sliderPosition = percentage;
+  }
+}
+
+function handleGlobalDragEnd() {
+  if (globalDragInstance) {
+    globalDragInstance.slider.style.cursor = "grab";
+    globalDragInstance = null;
+    document.body.style.userSelect = "";
+    document.body.style.cursor = "";
+  }
+}
+
+// Set up global event handlers once (module-level)
+if (typeof document !== "undefined") {
+  document.addEventListener("mousemove", handleGlobalMouseMove);
+  document.addEventListener("touchmove", handleGlobalTouchMove, { passive: false });
+  document.addEventListener("mouseup", handleGlobalDragEnd);
+  document.addEventListener("touchend", handleGlobalDragEnd);
+}
+
 export function init() {
   const config = {
     defaultMode: "split",
@@ -15,11 +70,34 @@ export function init() {
     Object.assign(config, newConfig);
   }
 
+  // Live region for announcing state changes
+  function announceChange(instance, message) {
+    const liveRegion = elementRefs.get(instance.wrapper)?.liveRegion;
+    if (liveRegion) {
+      liveRegion.textContent = message;
+      // Clear after announcement to allow repeated announcements
+      setTimeout(() => {
+        liveRegion.textContent = '';
+      }, 1000);
+    }
+  }
+
   function initInstance(wrapper) {
     const instanceId = instances.length;
     const items = Array.from(wrapper.children);
 
-    if (items.length === 0) return;
+    if (items.length === 0) {
+      console.warn('[hs-before-after] Wrapper element has no child items');
+      return;
+    }
+
+    // Create and append live region for announcements
+    const liveRegion = document.createElement('div');
+    liveRegion.setAttribute('aria-live', 'polite');
+    liveRegion.setAttribute('aria-atomic', 'true');
+    liveRegion.className = 'sr-only';
+    liveRegion.style.cssText = 'position: absolute; width: 1px; height: 1px; padding: 0; margin: -1px; overflow: hidden; clip: rect(0,0,0,0); white-space: nowrap; border-width: 0;';
+    wrapper.appendChild(liveRegion);
 
     const instance = {
       id: instanceId,
@@ -35,6 +113,9 @@ export function init() {
       cachedElements: new Map(),
     };
 
+    // Store live region reference in WeakMap
+    elementRefs.set(wrapper, { liveRegion });
+
     instances.push(instance);
     currentSlideIndex[instanceId] = 0;
 
@@ -50,8 +131,22 @@ export function init() {
     items.forEach((item, index) => {
       item.style.display = index === 0 ? "block" : "none";
 
-      // Set default clip path for after image
+      // Check for required elements and warn if missing
+      const imageWrapper = item.querySelector('[data-hs-ba="image-wrapper"]');
+      const beforeImage = item.querySelector('[data-hs-ba="image-before"]');
       const afterImage = item.querySelector('[data-hs-ba="image-after"]');
+
+      if (!imageWrapper) {
+        console.warn(`[hs-before-after] Missing required element in item ${index + 1}: data-hs-ba="image-wrapper"`);
+      }
+      if (!beforeImage) {
+        console.warn(`[hs-before-after] Missing required element in item ${index + 1}: data-hs-ba="image-before"`);
+      }
+      if (!afterImage) {
+        console.warn(`[hs-before-after] Missing required element in item ${index + 1}: data-hs-ba="image-after"`);
+      }
+
+      // Set default clip path for after image
       if (afterImage) {
         afterImage.style.clipPath = `polygon(${config.sliderPosition}% 0%, 100% 0%, 100% 100%, ${config.sliderPosition}% 100%)`;
       }
@@ -64,13 +159,40 @@ export function init() {
 
   function setupItemInteractions(instance, item, itemIndex) {
     const modeButtons = item.querySelectorAll('[data-hs-ba^="mode-"]');
-    const leftArrow = item.querySelector('[data-hs-ba="left"]');
-    const rightArrow = item.querySelector('[data-hs-ba="right"]');
+    const leftArrowWrapper = item.querySelector('[data-hs-ba="left-arrow"]');
+    const rightArrowWrapper = item.querySelector('[data-hs-ba="right-arrow"]');
     const slider = item.querySelector('[data-hs-ba="slider"]');
     const paginationContainer = item.querySelector('[data-hs-ba="pagination"]');
 
-    modeButtons.forEach((button) => {
-      const mode = button.getAttribute("data-hs-ba").replace("mode-", "");
+    // Setup mode buttons
+    modeButtons.forEach((modeWrapper) => {
+      const mode = modeWrapper.getAttribute("data-hs-ba").replace("mode-", "");
+
+      // Find the element with data-button-style attribute
+      const styleElement = modeWrapper.querySelector('[data-button-style]');
+
+      // Find the actual button inside clickable
+      const clickableElement = modeWrapper.querySelector('[data-site-clickable="element"]');
+      const button = clickableElement ? clickableElement.children[0] : null;
+
+      if (!button) return;
+
+      // Store references in WeakMap for later use
+      if (!elementRefs.has(modeWrapper)) {
+        elementRefs.set(modeWrapper, {});
+      }
+      const refs = elementRefs.get(modeWrapper);
+      refs.button = button;
+      refs.styleElement = styleElement;
+
+      // Add descriptive aria-label based on mode
+      const ariaLabels = {
+        before: "Switch to before view",
+        after: "Switch to after view",
+        split: "Switch to split view"
+      };
+      button.setAttribute("aria-label", ariaLabels[mode] || `Switch to ${mode} view`);
+
       button.addEventListener("click", (e) => {
         e.preventDefault();
 
@@ -83,18 +205,31 @@ export function init() {
       });
     });
 
-    if (leftArrow) {
-      leftArrow.addEventListener("click", (e) => {
-        e.preventDefault();
-        navigateSlide(instance, -1);
-      });
+    // Setup arrow buttons
+    if (leftArrowWrapper) {
+      const clickableElement = leftArrowWrapper.querySelector('[data-site-clickable="element"]');
+      const leftButton = clickableElement ? clickableElement.children[0] : null;
+
+      if (leftButton) {
+        leftButton.setAttribute('aria-label', 'Previous image');
+        leftButton.addEventListener("click", (e) => {
+          e.preventDefault();
+          navigateSlide(instance, -1);
+        });
+      }
     }
 
-    if (rightArrow) {
-      rightArrow.addEventListener("click", (e) => {
-        e.preventDefault();
-        navigateSlide(instance, 1);
-      });
+    if (rightArrowWrapper) {
+      const clickableElement = rightArrowWrapper.querySelector('[data-site-clickable="element"]');
+      const rightButton = clickableElement ? clickableElement.children[0] : null;
+
+      if (rightButton) {
+        rightButton.setAttribute('aria-label', 'Next image');
+        rightButton.addEventListener("click", (e) => {
+          e.preventDefault();
+          navigateSlide(instance, 1);
+        });
+      }
     }
 
     if (slider) {
@@ -113,12 +248,21 @@ export function init() {
     const sliderHandle = item.querySelector('[data-hs-ba="slider"]');
     const modeButtons = item.querySelectorAll('[data-hs-ba^="mode-"]');
 
-    modeButtons.forEach((btn) => {
-      const btnMode = btn.getAttribute("data-hs-ba").replace("mode-", "");
-      if (btnMode === mode) {
-        btn.classList.add("is-active");
-      } else {
-        btn.classList.remove("is-active");
+    // Update mode button states
+    modeButtons.forEach((modeWrapper) => {
+      const btnMode = modeWrapper.getAttribute("data-hs-ba").replace("mode-", "");
+      const refs = elementRefs.get(modeWrapper);
+
+      if (refs && refs.button && refs.styleElement) {
+        if (btnMode === mode) {
+          // Active state
+          refs.styleElement.setAttribute('data-button-style', 'primary');
+          refs.button.setAttribute('aria-pressed', 'true');
+        } else {
+          // Inactive state
+          refs.styleElement.setAttribute('data-button-style', 'secondary');
+          refs.button.setAttribute('aria-pressed', 'false');
+        }
       }
     });
 
@@ -145,6 +289,14 @@ export function init() {
     }
 
     instance.mode = mode;
+
+    // Announce mode change
+    const modeLabels = {
+      before: "Before view",
+      after: "After view",
+      split: "Split view"
+    };
+    announceChange(instance, modeLabels[mode] || mode);
   }
 
   function setupSliderDragging(instance, slider, itemIndex) {
@@ -152,64 +304,22 @@ export function init() {
     // Find the image wrapper using the data attribute
     const imageWrap = item.querySelector('[data-hs-ba="image-wrapper"]');
 
-    if (!imageWrap) return;
+    if (!imageWrap) {
+      console.warn('[hs-before-after] Missing required element: data-hs-ba="image-wrapper"');
+      return;
+    }
 
     function startDrag(e) {
-      instance.isDragging = true;
-      instance.dragInstance = { instance, itemIndex, imageWrap, slider };
+      globalDragInstance = { instance, imageWrap, slider, updateSliderPosition };
       document.body.style.userSelect = "none";
       document.body.style.cursor = "grabbing";
       slider.style.cursor = "grabbing";
       e.preventDefault();
     }
 
-    function handleDrag(clientX) {
-      if (!instance.isDragging || !instance.dragInstance) return;
-
-      const rect = instance.dragInstance.imageWrap.getBoundingClientRect();
-      const x = clientX - rect.left;
-      const percentage = Math.max(0, Math.min(100, (x / rect.width) * 100));
-
-      // Move the slider element directly
-      instance.dragInstance.slider.style.left = `${percentage}%`;
-
-      // Update the clip path
-      updateSliderPosition(
-        instance.dragInstance.instance,
-        instance.dragInstance.itemIndex,
-        percentage,
-      );
-      instance.dragInstance.instance.sliderPosition = percentage;
-    }
-
-    function endDrag() {
-      instance.isDragging = false;
-      if (instance.dragInstance && instance.dragInstance.slider) {
-        instance.dragInstance.slider.style.cursor = "grab";
-      }
-      instance.dragInstance = null;
-      document.body.style.userSelect = "";
-      document.body.style.cursor = "";
-    }
-
     slider.addEventListener("mousedown", startDrag);
     slider.addEventListener("touchstart", startDrag, { passive: false });
 
-    document.addEventListener("mousemove", (e) => handleDrag(e.clientX));
-    document.addEventListener(
-      "touchmove",
-      (e) => {
-        if (instance.isDragging) {
-          e.preventDefault();
-          handleDrag(e.touches[0].clientX);
-        }
-      },
-      { passive: false },
-    );
-
-    document.addEventListener("mouseup", endDrag);
-    document.addEventListener("touchend", endDrag);
-
     imageWrap.addEventListener("click", (e) => {
       if (instance.mode !== "split") return;
 
@@ -218,7 +328,7 @@ export function init() {
       const percentage = (x / rect.width) * 100;
 
       slider.style.left = `${percentage}%`;
-      updateSliderPosition(instance, itemIndex, percentage);
+      updateSliderPosition(instance, instance.currentIndex, percentage);
       instance.sliderPosition = percentage;
     });
   }
@@ -300,6 +410,11 @@ export function init() {
 
     updatePagination(instance);
     setMode(instance, index, instance.mode);
+
+    // Announce slide change
+    if (instance.items.length > 1) {
+      announceChange(instance, `Image ${index + 1} of ${instance.items.length}`);
+    }
   }
 
   function setupPagination(instance, paginationContainer) {
@@ -309,6 +424,10 @@ export function init() {
 
     if (!templateDot) return; // No template found
 
+    // Add pagination accessibility attributes
+    paginationContainer.setAttribute("role", "group");
+    paginationContainer.setAttribute("aria-label", "Image pagination");
+
     // Clear existing dots
     paginationContainer.innerHTML = "";
 
@@ -444,7 +563,8 @@ export function init() {
 
     // Set up main wrapper accessibility
     instance.wrapper.setAttribute("tabindex", "0");
-    instance.wrapper.setAttribute("role", "application");
+    instance.wrapper.setAttribute("role", "region");
+    instance.wrapper.setAttribute("aria-roledescription", "image comparison carousel");
     instance.wrapper.setAttribute(
       "aria-label",
       "Before and after image comparison, use arrow keys to navigate items",
@@ -490,21 +610,34 @@ export function init() {
   return {
     result: "before-after initialized",
     destroy: () => {
+      // Reset global drag state
+      globalDragInstance = null;
+
       // Clean up all instances
       instances.forEach((instance) => {
-        // Remove event listeners from wrapper
-        const newWrapper = instance.wrapper.cloneNode(true);
-        instance.wrapper.parentNode.replaceChild(newWrapper, instance.wrapper);
+        // Remove live region element
+        const liveRegion = elementRefs.get(instance.wrapper)?.liveRegion;
+        if (liveRegion && liveRegion.parentNode) {
+          liveRegion.parentNode.removeChild(liveRegion);
+        }
 
         // Clear cached elements
         instance.cachedElements.clear();
+
+        // Remove event listeners by cloning and replacing wrapper
+        const newWrapper = instance.wrapper.cloneNode(true);
+        instance.wrapper.parentNode.replaceChild(newWrapper, instance.wrapper);
       });
 
-      // Remove initialized markers
+      // Remove initialized markers and accessibility attributes
       document
         .querySelectorAll('[data-hs-ba="wrapper"][data-initialized]')
         .forEach((wrapper) => {
           wrapper.removeAttribute("data-initialized");
+          wrapper.removeAttribute("tabindex");
+          wrapper.removeAttribute("role");
+          wrapper.removeAttribute("aria-roledescription");
+          wrapper.removeAttribute("aria-label");
         });
 
       // Reset module state

package/utils/slider/README.md

@@ -0,0 +1,299 @@
+# **Slider/Carousel Utility**
+
+## **Overview**
+
+Flexible slider/carousel system supporting infinite carousels and paginated lists with responsive layouts, keyboard navigation, and accessibility features.
+
+**Note:** This utility is loaded via `data-hs-util-slider` attribute on the script tag in index.js.
+
+---
+
+## **Features**
+
+- **Infinite Carousel**: Seamless looping with GSAP animations
+- **Pagination Slider**: Multi-item pages with infinite loop
+- **Responsive**: Desktop/mobile breakpoints with different item counts
+- **Keyboard Support**: Full keyboard navigation
+- **Accessibility**: ARIA attributes, live regions, focus management
+- **Dot Navigation**: Click dots to jump to any page
+
+---
+
+## **Slider Types**
+
+### **1. Infinite Carousel**
+
+Basic infinite loop slider with next/prev buttons.
+
+**Required Elements:**
+- `data-hs-slider="wrapper"` - Container for slides
+- `data-hs-slider="next"` - Next button
+- `data-hs-slider="previous"` - Previous button
+
+**Example:**
+```html
+<div data-hs-slider="wrapper">
+  <div>Slide 1</div>
+  <div>Slide 2</div>
+  <div>Slide 3</div>
+</div>
+
+<button data-hs-slider="previous">Prev</button>
+<button data-hs-slider="next">Next</button>
+```
+
+**How it works:**
+- Clones first and last slides for seamless loop
+- Uses GSAP for smooth animations
+- Instant reset at loop endpoints
+
+---
+
+### **2. Pagination Slider**
+
+Multi-item slider with page-based navigation.
+
+**Required Elements:**
+- `data-hs-slider="pagination"` - Main container
+- `data-hs-slider="pagination-list"` - List of items
+- `data-hs-slider="pagination-next"` - Next page button
+- `data-hs-slider="pagination-previous"` - Previous page button
+
+**Optional Elements:**
+- `data-hs-slider="pagination-counter"` - Page counter display
+- `data-hs-slider="pagination-controls"` - Controls container with config
+- `data-hs-slider="dots-wrap"` - Dot navigation container
+
+---
+
+## **Configuration**
+
+Add to `pagination-controls` element via `data-hs-config`:
+
+### **Syntax:**
+```
+data-hs-config="[option], [option], ..."
+```
+
+### **Options:**
+
+**Show Items (Desktop):**
+```html
+data-hs-config="show-6"
+```
+Shows 6 items per page on desktop (default: 6)
+
+**Show Items (Mobile):**
+```html
+data-hs-config="show-3-mobile"
+```
+Shows 3 items per page on mobile (default: desktop value)
+
+**Infinite Mode:**
+```html
+data-hs-config="infinite"
+```
+Disables pagination completely (hides controls and dots)
+
+**Combined Example:**
+```html
+<div data-hs-slider="pagination-controls" data-hs-config="show-6, show-3-mobile">
+  <!-- Controls -->
+</div>
+```
+
+---
+
+## **Pagination Example**
+
+```html
+<div data-hs-slider="pagination">
+  <!-- List wrapper (auto-managed) -->
+  <div>
+    <div data-hs-slider="pagination-list">
+      <div>Item 1</div>
+      <div>Item 2</div>
+      <div>Item 3</div>
+      <div>Item 4</div>
+      <div>Item 5</div>
+      <div>Item 6</div>
+      <div>Item 7</div>
+      <div>Item 8</div>
+    </div>
+  </div>
+
+  <!-- Controls -->
+  <div data-hs-slider="pagination-controls" data-hs-config="show-4, show-2-mobile">
+    <button data-hs-slider="pagination-previous">Previous</button>
+    <div data-hs-slider="pagination-counter">1 / 2</div>
+    <button data-hs-slider="pagination-next">Next</button>
+  </div>
+
+  <!-- Dot navigation -->
+  <div data-hs-slider="dots-wrap">
+    <div class="dot"></div> <!-- Template (active) -->
+    <div class="dot"></div> <!-- Template (inactive) -->
+  </div>
+</div>
+```
+
+---
+
+## **Dot Navigation**
+
+### **Setup:**
+1. Add `data-hs-slider="dots-wrap"` container
+2. Include template dots as children
+3. First dot with `is-active` class = active template
+4. Second dot without class = inactive template
+
+### **Behavior:**
+- Dots auto-generated for each page
+- Click or press Enter/Space to navigate
+- Active dot gets `is-active` class and `aria-current="page"`
+- Hidden when only 1 page or infinite mode
+
+### **Example:**
+```html
+<div data-hs-slider="dots-wrap">
+  <div class="dot is-active"></div>  <!-- Active template -->
+  <div class="dot"></div>             <!-- Inactive template -->
+</div>
+```
+
+---
+
+## **Responsive Breakpoints**
+
+Uses CSS custom property `--data-hs-break` to detect layout:
+
+```css
+.pagination-list {
+  --data-hs-break: "desktop";
+}
+
+@media (max-width: 768px) {
+  .pagination-list {
+    --data-hs-break: "mobile";
+  }
+}
+```
+
+When breakpoint changes:
+- Re-calculates items per page
+- Re-generates pagination
+- Maintains current position when possible
+
+---
+
+## **Keyboard Navigation**
+
+All controls support keyboard:
+- `Tab`: Navigate between controls
+- `Enter/Space`: Activate buttons and dots
+- Focus managed with `inert` attribute on inactive pages
+
+---
+
+## **Accessibility Features**
+
+### **ARIA Attributes:**
+- `aria-label` on all buttons
+- `aria-live="polite"` on counter
+- `aria-current="page"` on active dot
+- `aria-hidden` on hidden controls/dots
+
+### **Screen Reader Announcements:**
+- Page changes announced via live region
+- Format: "Page X of Y"
+- Temporary announcement (clears after 1s)
+
+### **Focus Management:**
+- Uses `inert` attribute on inactive pages
+- Prevents tab navigation to hidden content
+- Focus maintained on controls during navigation
+
+---
+
+## **Pagination Behavior**
+
+### **Single Page:**
+- Controls and dots hidden
+- All items visible
+- No interaction needed
+
+### **Multiple Pages:**
+- Infinite loop (last page → first page)
+- Clones pages at start/end for seamless loop
+- Instant position reset at boundaries
+- Smooth CSS transitions between pages
+
+### **Mobile Scroll:**
+On mobile, after page change:
+- Auto-scrolls to show controls
+- 5rem clearance from bottom
+- Smooth scroll behavior
+
+---
+
+## **How It Works**
+
+### **Infinite Carousel:**
+1. Clones first/last slides
+2. Positions wrapper at slide 1 (middle)
+3. On next/prev, animates to target
+4. On loop, instantly resets position
+5. Uses GSAP for smooth animations
+
+### **Pagination:**
+1. Calculates total pages based on config
+2. Splits items into page lists
+3. Clones pages for infinite loop
+4. Positions wrapper at page 1 (middle)
+5. On navigate, transitions to target page
+6. On loop, instantly resets to real page
+7. Manages height based on active page
+
+---
+
+## **Edge Cases**
+
+### **No Items:**
+- Early exit, no initialization
+
+### **Single Item (Pagination):**
+- No controls shown
+- Single item displayed
+- No pagination needed
+
+### **Infinite Mode:**
+- Controls completely hidden
+- Dots completely hidden
+- List displayed as-is
+- No pagination logic runs
+
+### **Layout Changes:**
+- ResizeObserver detects breakpoint changes
+- Re-initializes pagination with new item count
+- Tries to maintain current page position
+
+---
+
+## **Performance**
+
+- Uses CSS custom properties for breakpoint detection
+- ResizeObserver for efficient layout monitoring
+- Inert attribute prevents unnecessary focus handling
+- Cleanup on destroy for Barba.js compatibility
+- Efficient DOM cloning and manipulation
+
+---
+
+## **Notes**
+
+- Requires GSAP for infinite carousel animations
+- CSS transitions handle pagination animations
+- Each pagination container is independent
+- Dot templates must exist before initialization
+- Mobile breakpoint detected via CSS custom property
+- All event listeners cleaned up on destroy