@reliability-design/web 1.4.6 → 1.4.8

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

@@ -1,424 +1,100 @@
-# 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-bg-surface` - Button/link background
-- `--rel-text-label` - Text color and active page background
-- `--rel-border-default` - Border color
-- `--rel-text-default` - Hover border color
-- `--rel-bg-neutral-elevated-1` - Hover background
-- `--rel-text-placeholder` - Ellipsis color
-- `--rel-bg-info` - Focus outline
-
-### Typography
-- `--rel-fonts-font-family` - Font family (Poppins)
-- `--rel-fonts-weight-body-medium` - Default text weight
-- `--rel-fonts-weight-body-semibold` - Active page weight
-- `--rel-body-sm-regular-font-size` - Comfortable mode font size
-- `--rel-body-xs-regular-font-size` - Compact mode font size
-
-### Spacing
-- `--rel-spacing-3xs` (2px) - Compact gap
-- `--rel-spacing-2xs` (4px) - Comfortable gap
-- `--rel-spacing-xs` (8px) - Compact padding
-- `--rel-spacing-sm` (12px) - Comfortable padding
-
-### Borders
-- `--rel-stroke-sm` (1px) - Border width
-- `--rel-border-radius-sm` (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>
-```
-
-### Very Large Page Counts
-
-Page buttons auto-widen to fit their number (min-width 40px). Far first/last
-buttons with numbers ≥ 10,000 are abbreviated so the control stays compact:
-`10000` → `10k`, `368178` → `368k`, `1234567` → `1.2M`. The exact page number
-is preserved in the button's `aria-label` and `title` (hover tooltip). The
-current page and its immediate neighbors always render exact — abbreviating
-them would make adjacent pages indistinguishable.
-
-```html
-<rel-pagination totalPages="368178" page="7"></rel-pagination>
-<!-- [<] [1] ... [6] [7] [8] ... [368k] [>] -->
-```
-
-## 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
+# rel-pagination
+
+Page navigation implementing the Figma "Pagination" component in its three **Type** layouts: `extended` (prev/next ghost buttons around numbered page chips, with a windowed ellipsis for long ranges), `compact` (prev/next around a "Page X of Y" readout) and `count-text` (a "1–10 of 50" item range with the nav on the right). Use it under tables, lists and search results that load one page at a time. It never fetches data or reads the URL: listen for `rel-change` and load the requested page yourself.
+
+## Usage
+
+```html
+<!-- Extended (default): numbered pages, uncontrolled -->
+<rel-pagination totalPages="12" defaultPage="3"></rel-pagination>
+
+<!-- Extended with the "Viewing page X of Y" caption -->
+<rel-pagination totalPages="20" showLabel></rel-pagination>
+
+<!-- Compact: prev / "Page X of Y" / next -->
+<rel-pagination type="compact" totalPages="8"></rel-pagination>
+
+<!-- Count-text: item range computed from totalItems and perPage -->
+<rel-pagination type="count-text" totalItems="137" perPage="25"></rel-pagination>
+
+<!-- Controlled: the parent owns the page -->
+<rel-pagination id="results" page="1" totalPages="40" ariaLabel="Search results pagination"></rel-pagination>
+<script>
+  const pager = document.getElementById('results');
+  pager.addEventListener('rel-change', (e) => {
+    loadResults(e.detail.page).then(() => {
+      pager.page = e.detail.page; // commit once the data is in
+    });
+  });
+</script>
+
+<!-- Disabled while loading -->
+<rel-pagination totalPages="12" disabled></rel-pagination>
+```
+
+<!-- readme-gen:start -->
+
+<!-- Generated from rel-pagination.ts — do not edit; run readme-generate.mjs -->
+
+## API
+
+### Attributes / Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `type` | `type` | `"extended" \| "compact" \| "count-text"` | `"extended"` | Figma "Type": `extended` = prev/next + numbered page buttons (auto-collapses to compact under 480px container width), `compact` = prev/next + "Page X of Y", `count-text` = "start–end of total" item range + prev/next around the current page number. Reflected. |
+| `page` | `page` | `number` | `undefined` | Controlled current page (1-based). When set, the element only emits `rel-change` and waits for the parent to update `page`; leave unset for uncontrolled behaviour. |
+| `defaultPage` | `defaultpage` | `number` | `1` | Starting page for uncontrolled use (ignored when `page` is set). Attribute `defaultPage`, also read once as `default-page` on connect. |
+| `totalPages` | `totalpages` | `number` | `0` | Total number of pages. `0` (the default) lets `totalItems` / `perPage` compute the page count instead. Attribute `totalPages`, also read once as `total-pages` on connect. |
+| `totalItems` | `totalitems` | `number` | `0` | Total item count; with `perPage` it computes the page count when `totalPages` is `0` and is the "of N" figure in the count-text readout. Attribute `totalItems`, also read once as `total-items` on connect. |
+| `perPage` | `perpage` | `number` | `10` | Items per page, used to compute the page count from `totalItems` and the "start–end" range in the count-text readout. Attribute `perPage`, also read once as `per-page` on connect. |
+| `showLabel` | `showlabel` | `boolean` | `false` | DELIBERATE DIVERGENCE — do not flip this default to `true`. Figma's `Type=Extended` has no boolean for the caption: the "Viewing page 1 of 10" text is a fixed child of both Extended variants and is load-bearing for their 78px height (40 + spacing-md + 22). Here it stays opt-in. Ruled by the user: our behaviour stands and the DESIGN FILE follows our docs. Defaulting it on would silently add 38px to every existing extended pagination. |
+| `disabled` | `disabled` | `boolean` | `false` | Dims the whole control to 40% opacity, shows a `not-allowed` cursor and ignores every page change. Reflected. |
+| `hrefTemplate` | `hreftemplate` | `string` | `""` | Reserved for link-mode pagination. Currently accepted but not rendered: every page control is a `<button>`, so navigate in your `rel-change` handler instead. |
+| `ariaLabel` | `arialabel` | `string` | `"Pagination"` | Accessible name of the `role="navigation"` landmark (attribute `ariaLabel`). Set it when a page contains more than one pagination control. |
+
+## Events
+
+| Event | Detail | Bubbles / composed | Description |
+| --- | --- | --- | --- |
+| `rel-change` | `{ page: newPage }` | bubbles / composed | Fired when the user picks another page (prev/next or a page number). Detail: `{ page: number }` (1-based). In controlled mode the parent must then set `page`. |
+
+## Slots
+
+| Slot | Description |
+| --- | --- |
+| — | This element has no slots. |
+
+## CSS Parts
+
+| Part | Description |
+| --- | --- |
+| `base` | The `role="navigation"` root of the extended layout (page buttons plus the optional "Viewing page" label). |
+| `label` | The `role="navigation"` root row of the count-text layout (item-range text plus prev/next nav). |
+
+<!-- readme-gen:end -->
+
+## Accessibility
+
+- The control is a `role="navigation"` landmark named by `ariaLabel` (default "Pagination"); give each pager on a page a distinct name.
+- Prev/next are native buttons labelled "Previous page" / "Next page"; they are disabled (not hidden) on the first / last page.
+- Each page chip is a native button labelled "Page N" with `aria-current="page"` on the current one. Abbreviated first/last chips (e.g. "368k") keep the exact number in their `title`.
+- Every page change is announced to screen readers as "Page N of M" via the shared live region.
+- If a prev/next button becomes disabled while it has focus (you reached the first/last page), focus moves to the other nav button instead of being lost.
+
+| Key | Action |
+| --- | --- |
+| `Tab` / `Shift+Tab` | Move between the prev button, page chips and next button |
+| `Enter` / `Space` | Activate the focused button (native behaviour) |
+
+No arrow-key navigation is implemented; all controls are regular tab stops.
+
+## Notes / Edge Cases
+
+- **Attribute names.** The Lit attributes are the lowercase property names (`totalPages`, `defaultPage`, `totalItems`, `perPage`, `showLabel`, `hrefTemplate`, `ariaLabel` — HTML attributes are case-insensitive). The kebab-case forms `total-pages`, `default-page`, `total-items`, `per-page` and `page` are additionally read **once** when the element connects, so they work in static markup but not for later updates; set the property in code.
+- **Page count.** `totalPages` wins when greater than `0`; otherwise the count is `ceil(totalItems / perPage)`. With neither set the element renders no page chips and both nav buttons disabled.
+- **Controlled vs uncontrolled.** With `page` unset the element tracks the current page itself starting at `defaultPage`. Once `page` is set it stays on that page until the parent changes it — clicking only emits `rel-change`.
+- **Ellipsis window.** Up to 7 pages render in full. Beyond that: the first 5 + last near the start, first + last 5 near the end, otherwise first, current ±1 and last, with `…` between. Far first/last chips abbreviate large numbers (`10000` → `10k`, `2500000` → `2.5M`); chips inside the window are never abbreviated.
+- **Responsive.** `extended` uses a container query on the host: between 480px and 768px only first, last and current ±1 stay visible; under 480px the whole control swaps to the compact layout (media-query fallback for browsers without container queries). The `label` part belongs to the `count-text` layout, not to the "Viewing page" caption.
+- **`hrefTemplate`** is accepted but currently unused — chips are always buttons, not links. Perform navigation in the `rel-change` handler.
+- **`rel-change` is not fired** for the current page, out-of-range pages, or while `disabled`.