@reliability-design/web 1.0.3 → 1.0.6

package/dist/components/rel-pagination/README.md

@@ -0,0 +1,410 @@
+# rel-pagination
+
+A flexible pagination component with smart ellipsis rendering, keyboard navigation, and support for both controlled and uncontrolled modes.
+
+## What It Is
+
+The pagination component provides navigation through multiple pages of content. It intelligently renders page numbers with ellipsis to handle large page counts, supports Previous/Next controls, and can render either as buttons or links.
+
+## Basic Usage
+
+```html
+<!-- Uncontrolled mode (manages its own state) -->
+<rel-pagination totalPages="10" defaultPage="1"></rel-pagination>
+
+<!-- Controlled mode (external state management) -->
+<rel-pagination totalPages="10" page="5"></rel-pagination>
+```
+
+## API Reference
+
+### Attributes / Properties
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `page` | number | undefined | Current page (1-based). When set, enables controlled mode |
+| `defaultPage` | number | 1 | Initial page for uncontrolled mode |
+| `totalPages` | number | required | Total number of pages |
+| `siblingCount` | number | 1 | Number of pages to show around current page |
+| `boundaryCount` | number | 1 | Number of pages to show at start/end |
+| `disabled` | boolean | false | Disables all interactions |
+| `density` | "comfortable" \| "compact" | "comfortable" | Spacing density |
+| `variant` | "default" \| "icons" | "default" | Controls visual style |
+| `hrefTemplate` | string | "" | Template for href links (e.g., "/page/{page}") |
+| `ariaLabel` | string | "Pagination" | ARIA label for the nav element |
+
+### Events
+
+**rel-change**
+
+Emitted when user selects a new page.
+
+```typescript
+detail: { page: number }
+```
+
+**Example:**
+```javascript
+const pagination = document.querySelector('rel-pagination');
+pagination.addEventListener('rel-change', (e) => {
+  console.log('New page:', e.detail.page);
+});
+```
+
+## Controlled vs Uncontrolled
+
+### Uncontrolled Mode
+
+Component manages its own internal state. Use `defaultPage` to set initial page.
+
+```html
+<rel-pagination totalPages="10" defaultPage="2"></rel-pagination>
+```
+
+```javascript
+pagination.addEventListener('rel-change', (e) => {
+  // Component has already updated its internal page
+  console.log('Changed to page:', e.detail.page);
+});
+```
+
+### Controlled Mode
+
+External code manages the page state. Set the `page` attribute.
+
+```html
+<rel-pagination id="controlled-pagination" totalPages="10" page="5"></rel-pagination>
+```
+
+```javascript
+let currentPage = 5;
+const pagination = document.getElementById('controlled-pagination');
+
+pagination.addEventListener('rel-change', (e) => {
+  // Update your external state
+  currentPage = e.detail.page;
+  // Update the component
+  pagination.page = currentPage;
+
+  // Fetch new data, etc.
+  fetchData(currentPage);
+});
+```
+
+## Ellipsis Logic
+
+The component intelligently renders page numbers with ellipsis based on `siblingCount` and `boundaryCount`:
+
+### Examples
+
+**totalPages=10, page=5, siblingCount=1, boundaryCount=1:**
+```
+1 … 4 5 6 … 10
+```
+
+**totalPages=10, page=2, siblingCount=1, boundaryCount=1:**
+```
+1 2 3 … 10
+```
+
+**totalPages=10, page=9, siblingCount=1, boundaryCount=1:**
+```
+1 … 8 9 10
+```
+
+**totalPages=5, page=3 (no ellipsis needed):**
+```
+1 2 3 4 5
+```
+
+### How It Works
+
+1. **Boundary Pages**: Always shows `boundaryCount` pages at start and end
+2. **Sibling Pages**: Shows `siblingCount` pages on each side of current page
+3. **Ellipsis**: Inserted when there's a gap between visible page ranges
+
+## Variants
+
+### Default Variant
+
+Shows text labels for Previous/Next buttons.
+
+```html
+<rel-pagination totalPages="10" variant="default"></rel-pagination>
+<!-- Renders: [Previous] [1] [2] ... [10] [Next] -->
+```
+
+### Icons Variant
+
+Shows chevron icons instead of text labels.
+
+```html
+<rel-pagination totalPages="10" variant="icons"></rel-pagination>
+<!-- Renders: [<] [1] [2] ... [10] [>] -->
+```
+
+## Density
+
+### Comfortable (Default)
+
+Standard spacing with larger touch targets.
+
+```html
+<rel-pagination totalPages="10" density="comfortable"></rel-pagination>
+```
+
+- Height: 40px
+- Font size: sm
+- Padding: sm
+
+### Compact
+
+Tighter spacing for dense layouts.
+
+```html
+<rel-pagination totalPages="10" density="compact"></rel-pagination>
+```
+
+- Height: 32px
+- Font size: xs
+- Padding: xs
+
+## Link Mode
+
+Instead of buttons, render page items as links by providing an `hrefTemplate`.
+
+```html
+<rel-pagination
+  totalPages="10"
+  page="3"
+  hrefTemplate="/docs?page={page}">
+</rel-pagination>
+```
+
+The `{page}` placeholder is replaced with the page number:
+- Page 1 → `/docs?page=1`
+- Page 5 → `/docs?page=5`
+
+**Note**: Click events still emit `rel-change` events and prevent default navigation, allowing you to handle routing in JavaScript.
+
+## Keyboard Navigation
+
+Full keyboard accessibility:
+
+| Key | Action |
+|-----|--------|
+| `Tab` / `Shift+Tab` | Navigate through page buttons and controls |
+| `Enter` | Activate focused button/link |
+| `Space` | Activate focused button/link |
+
+## Accessibility
+
+The component follows ARIA best practices:
+
+### Semantic HTML
+- Wrapped in `<nav>` with `role="navigation"`
+- Configurable `aria-label` (default: "Pagination")
+
+### Page Buttons
+- Current page has `aria-current="page"`
+- Each button has descriptive `aria-label`:
+  - "Go to page 1"
+  - "Go to page 2"
+  - etc.
+
+### Controls
+- Previous button: `aria-label="Go to previous page"`
+- Next button: `aria-label="Go to next page"`
+- Disabled state reflected with `disabled` attribute or `aria-disabled`
+
+### Focus Management
+- Visible focus indicators using focus-visible
+- Proper tab order through page numbers
+
+## Styling Tokens
+
+The component uses design tokens from the Reliability Design System:
+
+### Colors
+- `--rel-colors-white` - Button/link background
+- `--rel-colors-gray-heading` - Text color and active page background
+- `--rel-colors-gray-border` - Border color
+- `--rel-colors-gray-primary` - Hover border color
+- `--rel-colors-gray-background` - Hover background
+- `--rel-colors-gray-placeholder` - Ellipsis color
+- `--rel-colors-blue-primary` - Focus outline
+
+### Typography
+- `--rel-fontFamilies-primary` - Font family (Poppins)
+- `--rel-fontWeights-medium` - Default text weight
+- `--rel-fontWeights-semibold` - Active page weight
+- `--rel-fontSizes-sm` - Comfortable mode font size
+- `--rel-fontSizes-xs` - Compact mode font size
+
+### Spacing
+- `--rel-spacing-space-3xs` (2px) - Compact gap
+- `--rel-spacing-space-2xs` (4px) - Comfortable gap
+- `--rel-spacing-space-xs` (8px) - Compact padding
+- `--rel-spacing-space-sm` (12px) - Comfortable padding
+
+### Borders
+- `--rel-borders-width-stroke-100` (1px) - Border width
+- `--rel-borders-radius-border-radius-200` (8px) - Border radius
+
+## Complete Examples
+
+### Simple Pagination
+
+```html
+<rel-pagination totalPages="10" defaultPage="1"></rel-pagination>
+```
+
+### With Event Handling
+
+```html
+<rel-pagination id="my-pagination" totalPages="50" defaultPage="1"></rel-pagination>
+
+<script>
+  const pagination = document.getElementById('my-pagination');
+
+  pagination.addEventListener('rel-change', (e) => {
+    console.log('Loading page:', e.detail.page);
+    fetchPageData(e.detail.page);
+  });
+
+  function fetchPageData(page) {
+    // Your data fetching logic
+  }
+</script>
+```
+
+### Controlled with More Siblings
+
+```html
+<rel-pagination
+  id="controlled"
+  totalPages="100"
+  page="50"
+  siblingCount="2"
+  boundaryCount="2">
+</rel-pagination>
+
+<script>
+  let currentPage = 50;
+  const pagination = document.getElementById('controlled');
+
+  pagination.addEventListener('rel-change', (e) => {
+    currentPage = e.detail.page;
+    pagination.page = currentPage;
+    updateContent(currentPage);
+  });
+</script>
+```
+
+### Compact with Icons
+
+```html
+<rel-pagination
+  totalPages="25"
+  defaultPage="1"
+  density="compact"
+  variant="icons"
+  siblingCount="1"
+  boundaryCount="1">
+</rel-pagination>
+```
+
+### Link Mode for SEO
+
+```html
+<rel-pagination
+  totalPages="20"
+  page="5"
+  hrefTemplate="/products?page={page}"
+  siblingCount="1">
+</rel-pagination>
+
+<script>
+  const pagination = document.querySelector('rel-pagination');
+
+  pagination.addEventListener('rel-change', (e) => {
+    // Handle client-side navigation
+    navigateToPage(e.detail.page);
+  });
+
+  function navigateToPage(page) {
+    // Your routing logic (e.g., History API)
+    history.pushState({}, '', `/products?page=${page}`);
+    loadPageData(page);
+  }
+</script>
+```
+
+## Edge Cases
+
+### Few Pages (No Ellipsis)
+
+When total pages is small, all pages are shown:
+
+```html
+<rel-pagination totalPages="5" page="3"></rel-pagination>
+<!-- Renders: [Previous] [1] [2] [3] [4] [5] [Next] -->
+```
+
+### First Page
+
+Previous button is disabled:
+
+```html
+<rel-pagination totalPages="10" page="1"></rel-pagination>
+<!-- [Previous - disabled] [1] [2] [3] ... [10] [Next] -->
+```
+
+### Last Page
+
+Next button is disabled:
+
+```html
+<rel-pagination totalPages="10" page="10"></rel-pagination>
+<!-- [Previous] [1] ... [8] [9] [10] [Next - disabled] -->
+```
+
+### Disabled State
+
+All interactions disabled:
+
+```html
+<rel-pagination totalPages="10" page="5" disabled></rel-pagination>
+```
+
+## Browser Support
+
+Compatible with all modern browsers supporting:
+- Web Components (Custom Elements v1)
+- Shadow DOM
+- ES2020+ features
+
+## Framework Integration
+
+Works seamlessly with:
+- Vanilla JavaScript
+- Angular
+- React (via wrapper)
+- Vue
+- Any framework supporting Web Components
+
+## Best Practices
+
+1. **Use controlled mode** for complex state management (Redux, Vuex, etc.)
+2. **Use uncontrolled mode** for simple cases where component can manage its own state
+3. **Adjust siblingCount** based on available space (mobile: 0-1, desktop: 1-2)
+4. **Use compact density** on mobile or in sidebars
+5. **Use link mode** when SEO matters (server-rendered pagination)
+6. **Always handle rel-change events** to update your data/UI
+
+## Performance Notes
+
+- Ellipsis calculation is optimized and runs only when page/total changes
+- No unnecessary re-renders in controlled mode
+- Minimal DOM elements (only visible pages + controls)
+- Efficient event handling with no memory leaks

package/dist/components/rel-pagination/index.ts

@@ -0,0 +1 @@
+export * from "./rel-pagination";