@hortonstudio/main 1.9.9 → 1.9.11

package/autoInit/accessibility/README.md

@@ -2,7 +2,7 @@
 
 ## **Overview**
 
-The accessibility system provides 7 modular functions to enhance website accessibility and functionality. Each function operates independently and can be customized through data attributes.
+The accessibility system provides 8 modular functions to enhance website accessibility and functionality. Each function operates independently and can be customized through data attributes.
 
 **Note:** This module auto-initializes and loads all functions on page load.
 
@@ -61,6 +61,13 @@ Universal dropdown system for FAQ, summary/read-more, and general toggle compone
 
 ---
 
+### **8. Pagination**
+Complete pagination system for paginated lists with controls, counters, dot navigation, and infinite looping. Supports responsive layouts and accessibility features.
+
+**Use case:** Multi-item paginated lists (product grids, blog lists, search results) and carousels (with `show-1` config).
+
+---
+
 ## **Documentation**
 
 Each function has detailed documentation in its respective folder:
@@ -72,6 +79,7 @@ Each function has detailed documentation in its respective folder:
 - `functions/text-synchronization/README.md`
 - `functions/toc/README.md`
 - `functions/dropdown/README.md`
+- `functions/pagination/README.md`
 
 ---
 

package/autoInit/accessibility/accessibility.js

@@ -12,7 +12,8 @@ export async function init() {
     "click-forwarding": () => import("./functions/click-forwarding/click-forwarding.js"),
     "text-synchronization": () => import("./functions/text-synchronization/text-synchronization.js"),
     "toc": () => import("./functions/toc/toc.js"),
-    "dropdown": () => import("./functions/dropdown/dropdown.js")
+    "dropdown": () => import("./functions/dropdown/dropdown.js"),
+    "pagination": () => import("./functions/pagination/pagination.js")
   };
 
   const loadFunction = async (functionName) => {

package/autoInit/accessibility/functions/pagination/README.md

@@ -0,0 +1,452 @@
+# **Pagination System Documentation**
+
+## **Overview**
+
+Complete pagination system for paginated lists with controls, counters, dot navigation, and infinite looping. Features responsive layouts, ARIA live announcements, and full keyboard accessibility.
+
+**Note:** This function auto-initializes on page load as part of the accessibility system.
+
+---
+
+## **Features**
+
+- **Infinite Loop Pagination**: Seamless page transitions with cloned pages
+- **Responsive Layouts**: Different items per page for desktop/mobile
+- **Page Controls**: Next/Previous buttons with infinite looping
+- **Page Counter**: Live-updating "X / Y" page indicator
+- **Dot Navigation**: Visual page indicators with click/keyboard support (semantic buttons)
+- **Auto-height Management**: Smooth height transitions between pages
+- **Focus Management**: Uses `inert` attribute for inactive pages
+- **ARIA Live Announcements**: Screen reader announcements for page changes
+- **Mobile Auto-scroll**: Scrolls controls into view on mobile after navigation
+
+---
+
+## **Required Structure**
+
+### **Wrapper** *(required)*
+
+**Attribute:** `data-hs-pagination="wrapper"`
+
+**What it does:** Main container for entire pagination instance.
+
+---
+
+### **List** *(required)*
+
+**Attribute:** `data-hs-pagination="list"`
+
+**What it does:** Container for all items to be paginated. System will split these into pages.
+
+**Important:** Must be a direct child of a wrapper element (typically a div).
+
+---
+
+### **Next Button** *(required)*
+
+**Attribute:** `data-hs-pagination="next"` on wrapper element
+
+**What it does:** Navigate to next page. Loops to first page after last page.
+
+**Structure:** Uses `data-site-clickable="element"` pattern:
+```html
+<div data-hs-pagination="next" data-site-clickable="element">
+  <button type="button">Next</button>
+</div>
+```
+
+**Accessibility:** Automatically receives `aria-label="Go to next page"` on the button element
+
+---
+
+### **Previous Button** *(required)*
+
+**Attribute:** `data-hs-pagination="previous"` on wrapper element
+
+**What it does:** Navigate to previous page. Loops to last page from first page.
+
+**Structure:** Uses `data-site-clickable="element"` pattern:
+```html
+<div data-hs-pagination="previous" data-site-clickable="element">
+  <button type="button">Previous</button>
+</div>
+```
+
+**Accessibility:** Automatically receives `aria-label="Go to previous page"` on the button element
+
+---
+
+### **Controls Container** *(required for configuration)*
+
+**Attribute:** `data-hs-pagination="controls"`
+
+**What it does:** Container for pagination controls AND configuration.
+
+**Configuration Attributes:**
+
+**`data-hs-pagination-show`** - Desktop items per page (default: 6)
+```html
+data-hs-pagination-show="4"
+```
+
+**`data-hs-pagination-show-mobile`** - Mobile items per page (optional, defaults to desktop value)
+```html
+data-hs-pagination-show-mobile="2"
+```
+
+**Example:**
+```html
+<div data-hs-pagination="controls"
+     data-hs-pagination-show="4"
+     data-hs-pagination-show-mobile="2">
+  <!-- Buttons, counter, etc. -->
+</div>
+```
+
+**No Pagination (Infinite Mode):**
+
+To disable pagination and show all items, simply don't render the controls element at all. Without controls, the pagination system won't initialize and the list displays naturally.
+
+---
+
+### **Counter** *(optional)*
+
+**Attribute:** `data-hs-pagination="counter"`
+
+**What it does:** Displays current page and total pages (e.g., "2 / 5").
+
+**Accessibility:** Automatically receives:
+- `aria-live="polite"` - Announces changes
+- `aria-label="Current page"`
+
+---
+
+### **Dots Container** *(optional)*
+
+**Attribute:** `data-hs-pagination="dots"`
+
+**What it does:** Container for pagination dots. Requires template dot as first child.
+
+**Template Requirements:**
+- At least one child element (used as template)
+- Use `.is-active` class to designate active template
+- If only one template, same used for active/inactive states
+- **Dots are semantic `<button>` elements with `type="button"`**
+
+**Accessibility:** System automatically adds:
+- Individual dots via separate pagination dots system
+- `role="button"`, `tabindex="0"`, `aria-label` on each dot button
+- `aria-current="page"` on active dot
+
+---
+
+## **Usage Example**
+
+### **Basic Pagination**
+
+```html
+<div data-hs-pagination="wrapper">
+  <!-- Wrapper for list -->
+  <div>
+    <div data-hs-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-pagination="controls"
+       data-hs-pagination-show="4"
+       data-hs-pagination-show-mobile="2">
+
+    <div data-hs-pagination="previous" data-site-clickable="element">
+      <button type="button">Previous</button>
+    </div>
+
+    <div data-hs-pagination="counter">1 / 2</div>
+
+    <div data-hs-pagination="next" data-site-clickable="element">
+      <button type="button">Next</button>
+    </div>
+  </div>
+
+  <!-- Dots -->
+  <div data-hs-pagination="dots">
+    <button type="button" class="dot is-active"></button> <!-- Active template -->
+    <button type="button" class="dot"></button> <!-- Inactive template -->
+  </div>
+</div>
+```
+
+---
+
+### **No Pagination (Infinite Mode)**
+
+To disable pagination and show all items without pagination controls, simply don't render the controls element:
+
+```html
+<div data-hs-pagination="wrapper">
+  <div>
+    <div data-hs-pagination="list">
+      <!-- All items displayed, no pagination -->
+      <div>Item 1</div>
+      <div>Item 2</div>
+      <div>Item 3</div>
+      <div>Item 4</div>
+      <div>Item 5</div>
+    </div>
+  </div>
+
+  <!-- No controls = no pagination initialization -->
+</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 page when possible
+- Updates dots accordingly
+
+---
+
+## **Key Attributes Summary**
+
+| Attribute | Purpose | Required | Element Type |
+| ----- | ----- | ----- | ----- |
+| `data-hs-pagination="wrapper"` | Main container | **Required** | Wrapper div |
+| `data-hs-pagination="list"` | Items to paginate | **Required** | List container |
+| `data-hs-pagination="next"` | Next button wrapper | **Required** | Wrapper div with `data-site-clickable="element"` |
+| `data-hs-pagination="previous"` | Previous button wrapper | **Required** | Wrapper div with `data-site-clickable="element"` |
+| `data-hs-pagination="controls"` | Controls + config | Required for config | Wrapper div |
+| `data-hs-pagination-show` | Desktop items per page | Required on controls | Attribute (number) |
+| `data-hs-pagination-show-mobile` | Mobile items per page | Optional on controls | Attribute (number) |
+| `data-hs-pagination="counter"` | Page counter | Optional | Any element |
+| `data-hs-pagination="dots"` | Dots container | Optional | Wrapper div |
+
+---
+
+## **Accessibility Features**
+
+### **ARIA Live Regions**
+- Dynamically created live region for announcements
+- Announces page changes: "Page 2 of 5"
+- Uses `aria-live="assertive"` and `aria-atomic="true"`
+- Visually hidden with sr-only styling
+
+### **Button Accessibility**
+- Next/Previous buttons: `aria-label` with clear descriptions
+- Counter: `aria-live="polite"` for automatic announcements
+
+### **Focus Management**
+- Active page: No `inert` attribute (focusable)
+- Inactive pages: `inert` attribute prevents tab navigation
+- Focus stays on controls during navigation
+
+### **Dot Navigation**
+- Handled by separate pagination dots system
+- Full keyboard support (Enter/Space)
+- ARIA attributes for current page
+
+---
+
+## **How It Works**
+
+### **Initialization:**
+1. Finds all `[data-hs-pagination="wrapper"]` containers
+2. Reads configuration from `data-hs-pagination-show` attributes
+3. Calculates total pages based on items and config
+4. Splits items into page lists
+5. Clones pages for infinite loop (adds before/after)
+6. Positions wrapper at page 1 (middle clone)
+7. Initializes dots via pagination dots system
+
+### **Navigation:**
+1. User clicks next/previous or dot
+2. Updates current page index
+3. Animates wrapper with CSS transform
+4. On loop boundary, instantly resets to real page
+5. Updates counter, announces change, manages focus
+6. Auto-scrolls on mobile to keep controls visible
+
+### **Responsive:**
+1. ResizeObserver monitors wrapper size
+2. Detects breakpoint via CSS custom property
+3. Re-initializes pagination if breakpoint changes
+4. Maintains current page position when possible
+
+### **No Pagination (Infinite Mode):**
+1. Don't render controls element in HTML
+2. Pagination system won't initialize
+3. All items display naturally in list
+
+---
+
+## **Pagination Behavior**
+
+### **Single Page:**
+- Controls and dots hidden automatically
+- All items visible
+- No navigation needed
+
+### **Multiple Pages:**
+- Infinite loop (last → first, first → last)
+- Clones pages at boundaries for seamless transitions
+- Instant position reset after loop animation
+- Smooth CSS transitions between pages
+
+### **Mobile Scroll:**
+After page change on mobile:
+- Auto-scrolls to keep controls visible
+- 5rem clearance from bottom of viewport
+- Smooth scroll behavior
+
+---
+
+## **Dot Navigation Integration**
+
+The pagination system integrates with the separate pagination dots system:
+
+**How Integration Works:**
+1. Pagination sets attributes on dots container:
+   - `data-hs-pagination=""` (empty, triggers dots system)
+   - `data-hs-pagination-total` (total pages)
+   - `data-hs-pagination-current` (current page)
+2. Dots system handles rendering and click events
+3. Pagination listens for `hs-pagination-change` custom event
+4. Updates are bidirectional via `hsPaginationUpdate()` API
+
+**See:** `/autoInit/accessibility/functions/pagination/README.md` for full dots documentation
+
+---
+
+## **Configuration Examples**
+
+### **Desktop: 6 items, Mobile: 3 items**
+```html
+<div data-hs-pagination="controls"
+     data-hs-pagination-show="6"
+     data-hs-pagination-show-mobile="3">
+```
+
+### **Desktop: 4 items, Mobile: 2 items**
+```html
+<div data-hs-pagination="controls"
+     data-hs-pagination-show="4"
+     data-hs-pagination-show-mobile="2">
+```
+
+### **Same on all devices (8 items)**
+```html
+<div data-hs-pagination="controls"
+     data-hs-pagination-show="8">
+```
+
+### **No pagination (infinite mode)**
+```html
+<!-- Don't render controls element at all -->
+```
+
+---
+
+## **Edge Cases**
+
+### **No Items:**
+- Early exit, no initialization
+- Console warning displayed
+
+### **Single Page:**
+- Controls hidden with `display: none` and `aria-hidden="true"`
+- Dots hidden similarly
+- All items displayed on single page
+
+### **No Pagination (Infinite Mode):**
+- Don't render controls element
+- Pagination system won't initialize
+- List displays all items naturally
+- 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
+- CSS transitions (not JavaScript animations) for page changes
+
+---
+
+## **Common Issues**
+
+**Pagination not working:**
+1. Ensure wrapper, list, next, and previous elements exist
+2. Check `data-hs-pagination-show` attribute has valid number
+3. Verify list has children elements
+4. Ensure button structure uses `data-site-clickable="element"` pattern
+5. Check console for warnings
+
+**Items not splitting into pages:**
+1. Ensure `data-hs-pagination-show` specifies a number
+2. Check that total items > items per page
+3. Verify CSS custom property `--data-hs-break` is set
+
+**Dots not appearing:**
+1. Ensure dots container has template children
+2. Check that there are multiple pages (>1)
+3. Verify pagination accessibility system is loaded
+4. Check that `data-hs-pagination="dots"` attribute is correct
+
+**Layout not responsive:**
+1. Add `--data-hs-break` CSS custom property to list
+2. Ensure media query updates the property
+3. Check ResizeObserver is not being blocked
+
+**Controls always hidden:**
+1. Ensure total items > items per page
+2. Verify controls container exists in DOM
+3. Check that `data-hs-pagination-show` is set properly
+
+---
+
+## **Notes**
+
+- Each wrapper is an independent instance
+- Pages are cloned for infinite looping
+- Dots handled by separate pagination dots system
+- Works with any element type for items
+- Requires GSAP-less approach (uses CSS transitions)
+- Barba.js compatible with proper cleanup
+- Auto-initializes as part of accessibility system
+- Supports any number of items
+- Mobile-first responsive behavior