@hortonstudio/main 1.9.9 → 1.9.10

package/utils/slider/README.md

@@ -1,299 +0,0 @@
-# **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