@reliability-design/web 1.4.8 → 1.4.10

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

@@ -1,100 +1,141 @@
-# 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`.
+# 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 total-pages="12" default-page="3"></rel-pagination>
+
+<!-- Extended with the "Viewing page X of Y" caption -->
+<rel-pagination total-pages="20" show-label></rel-pagination>
+
+<!-- Compact: prev / "Page X of Y" / next -->
+<rel-pagination type="compact" total-pages="8"></rel-pagination>
+
+<!-- Count-text: item range computed from total-items and per-page -->
+<rel-pagination type="count-text" total-items="137" per-page="25"></rel-pagination>
+
+<!-- Controlled: the parent owns the page -->
+<rel-pagination id="results" page="1" total-pages="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 total-pages="12" disabled></rel-pagination>
+
+<!-- New in 1.5.0. Page select: prev / "Page [dropdown] of Y" / next; the dropdown jumps to any page -->
+<rel-pagination type="page-select" total-pages="40"></rel-pagination>
+
+<!-- New in 1.5.0. A rows-per-page selector after the navigation (Figma "Extended with Rows").
+     Works with every type; choosing a value updates per-page and returns to page 1. -->
+<rel-pagination total-items="137" per-page="20" show-rows-per-page></rel-pagination>
+<rel-pagination type="count-text" total-items="137" per-page="25"
+  show-rows-per-page rows-per-page-options="[25, 50, 100]"></rel-pagination>
+<script>
+  document.querySelector('rel-pagination[show-rows-per-page]')
+    .addEventListener('rel-per-page-change', (e) => reload({ perPage: e.detail.perPage, page: 1 }));
+</script>
+```
+
+Without `show-rows-per-page` there is no rows-per-page selector, and every type except `page-select` has no jump-to-page control: those are the defaults, so existing markup renders exactly as before.
+
+### Deprecated aliases
+
+```html
+<!-- Lowercase-joined attribute spellings → kebab-case (since 1.5.0; still work, log a one-time
+     console notice, removed in 3.0). camelCase markup (totalPages="12") lands on these too. -->
+<rel-pagination totalpages="12" defaultpage="3" showlabel></rel-pagination>
+<rel-pagination type="count-text" totalitems="137" perpage="25" hreftemplate="?page={page}"></rel-pagination>
+<!-- canonical -->
+<rel-pagination total-pages="12" default-page="3" show-label></rel-pagination>
+<rel-pagination type="count-text" total-items="137" per-page="25" href-template="?page={page}"></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" \| "page-select"` | `"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, `page-select` = prev/next around "Page [select] of Y", a dropdown that jumps to any page (new in 1.5.0). Every type except `page-select` has no jump-to-page control. 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` | `default-page` | `number` | `1` | Starting page for uncontrolled use (ignored when `page` is set). The `defaultpage` attribute spelling is deprecated (still works; removal targeted for 3.0). |
+| `totalPages` | `total-pages` | `number` | `0` | Total number of pages. `0` (the default) lets `totalItems` / `perPage` compute the page count instead. The `totalpages` attribute spelling is deprecated (still works; removal targeted for 3.0). |
+| `totalItems` | `total-items` | `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. The `totalitems` attribute spelling is deprecated (still works; removal targeted for 3.0). |
+| `perPage` | `per-page` | `number` | `10` | Items per page, used to compute the page count from `totalItems` and the "start–end" range in the count-text readout. The `perpage` attribute spelling is deprecated (still works; removal targeted for 3.0). |
+| `showLabel` | `show-label` | `boolean` | `false` | Shows a "Viewing page X of Y" caption under the extended layout (ignored by the other types). Off by default. The `showlabel` attribute spelling is deprecated (still works; removal targeted for 3.0). |
+| `disabled` | `disabled` | `boolean` | `false` | Dims the whole control to 40% opacity, shows a `not-allowed` cursor and ignores every page change. Reflected. |
+| `hrefTemplate` | `href-template` | `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. The `hreftemplate` attribute spelling is deprecated (still works; removal targeted for 3.0). |
+| `ariaLabel` | `arialabel` | `string` | `"Pagination"` | Accessible name of the `role="navigation"` landmark (attribute `ariaLabel`). Set it when a page contains more than one pagination control. |
+| `showRowsPerPage` | `show-rows-per-page` | `boolean` | `false` | New in 1.5.0. Adds a rows-per-page selector after the navigation, with any `type` (Figma "Extended with Rows" is `type="extended"` with this set). Choosing a value sets `perPage`, fires `rel-per-page-change` and returns to page 1. Off by default: no rows-per-page selector. |
+| `rowsPerPageOptions` | `rows-per-page-options` | `number[]` | `[10, 20, 50, 100]` | New in 1.5.0. The values the rows-per-page selector offers (a number array, or a JSON array in the attribute). The current `perPage` is added to the list when it is not in it. |
+| `rowsPerPageLabel` | `rows-per-page-label` | `string` | `"Results per Page"` | New in 1.5.0. Text before the rows-per-page selector, also its accessible name. |
+
+## 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`. |
+| `rel-per-page-change` | `{ perPage }` | bubbles / composed | New in 1.5.0. Fired when the user picks a value in the rows-per-page selector (`show-rows-per-page`). Detail: `{ perPage: number }`. `perPage` is already updated; the element then returns to page 1 (in controlled mode it fires `rel-change` with `{ page: 1 }` for the parent to commit). |
+
+## 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). |
+| `page-select` | The `rel-select` of the `page-select` layout (the jump-to-page dropdown). New in 1.5.0. |
+| `rows-per-page` | The rows-per-page block (its text plus the `rel-select`), rendered with `show-rows-per-page`. New in 1.5.0. |
+
+<!-- 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.
+- `type="page-select"` (new in 1.5.0): the dropdown is a `rel-select` combobox named "Page (of N)", so it is read as, for example, "Page (of 40), 3". The visible "Page" and "of N" texts are hidden from assistive technology because the name already carries them. It sits inside the navigation landmark, and picking a page is announced like any other page change.
+- `show-rows-per-page` (new in 1.5.0): the rows-per-page dropdown is a `rel-select` combobox named by `rows-per-page-label` (default "Results per Page"), placed after the navigation landmark rather than inside it. Its visible text is hidden from assistive technology for the same reason.
+- `disabled` also disables both dropdowns.
+
+| Key | Action |
+| --- | --- |
+| `Tab` / `Shift+Tab` | Move between the prev button, page chips (or the page dropdown) and next button, then the rows-per-page dropdown |
+| `Enter` / `Space` | Activate the focused button (native behaviour); on a dropdown, open it |
+| `ArrowDown` / `ArrowUp`, `Enter`, `Escape` (dropdown open) | Move the highlight, pick the highlighted value, close without picking (rel-select's keyboard model) |
+| Typing (page dropdown open) | Filters the page list; the first match is highlighted |
+
+The page chips and nav buttons have no arrow-key navigation; they are regular tab stops.
+
+## Notes / Edge Cases
+
+- **Attribute names.** Multi-word attributes are kebab-case: `total-pages`, `default-page`, `total-items`, `per-page`, `show-label`, `href-template`. They are observed like any other attribute, so later changes apply. The older lowercase spellings (which camelCase markup also produces, since HTML attribute names are case-insensitive) still work since 1.5.0 but log a one-time console notice and are removed in 3.0; see Deprecated aliases. `ariaLabel` keeps its `arialabel` attribute.
+- **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`.
+- **Page select.** The dropdown lists every page. Above 1,000 pages it lists a window of 1,000 around the current page plus the first and last, so the list stays fast. In controlled mode the dropdown snaps back to `page` until the parent commits the new one.
+- **Rows per page.** `rows-per-page-options` defaults to `[10, 20, 50, 100]`; the current `per-page` is added when it is not in the list. A pick sets `perPage`, fires `rel-per-page-change` (`{ perPage }`), then returns to page 1: uncontrolled, the element moves and fires `rel-change` with `{ page: 1 }`; controlled, it only fires `rel-change` with `{ page: 1 }`. When it is already on page 1, no `rel-change` fires. The inner dropdowns' own `changed` / `rel-change` events stop at the dropdown, so a listener on the pagination only ever sees `{ page }`.
+- **Narrow containers.** With `show-rows-per-page` the navigation and the rows-per-page block share one row, 16px apart, and wrap onto two rows when they do not fit.