@slotted/angular 0.0.0-stage → 0.1.0-beta.1

package/docs/pagination.md

@@ -0,0 +1,238 @@
+<!-- index: ./index.md -->
+# pagination
+
+`data-ui="pagination"` · Moves between pages of results.
+
+## Import
+
+```ts
+import {
+  SlPagination,
+  SlPaginationFirst,
+  SlPaginationItems,
+  SlPaginationLast,
+  SlPaginationNext,
+  SlPaginationPageSize,
+  SlPaginationPrevious,
+  SlPaginationStatus,
+  providePaginationDefaults,
+} from '@slotted/angular/pagination';
+```
+
+Selector: `nav[slPagination], [slPaginationFirst], [slPaginationPrevious], [slPaginationNext], [slPaginationLast], sl-pagination-items, p[slPaginationStatus], sl-pagination-page-size` · exportAs: `slPagination, slPaginationFirst, slPaginationPrevious, slPaginationNext, slPaginationLast, slPaginationItems, slPaginationStatus, slPaginationPageSize`
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```html
+<nav slPagination [count]="482" (pageChange)="load($event.value)">
+  <button slPaginationPrevious type="button"></button>
+  <sl-pagination-items />
+  <button slPaginationNext type="button"></button>
+</nav>
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | nav | yes |
+| `list` | ul | no |
+| `item` | li | no |
+| `page` | button, or a in link mode | no |
+| `ellipsis` | span | no |
+| `summary` | span | no |
+| `first` | button, or a in link mode | no |
+| `previous` | button, or a in link mode | no |
+| `next` | button, or a in link mode | no |
+| `last` | button, or a in link mode | no |
+| `status` | p | no |
+| `page-size` | select | no |
+| `page-size-label` | label | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `count` | `number` | — | slPagination | How many items the collection holds. It has no default on purpose: left out entirely, the total is unknown, no page numbers are drawn, and the family invents none |
+| `page` | `number` | — | slPagination | Present means controlled, for the life of the component |
+| `defaultPage` | `number` | 1 | slPagination | The page an uncontrolled paginator starts from, read once |
+| `pageSize` | `number` | — | slPagination | Present means controlled, for the life of the component |
+| `defaultPageSize` | `number` | 20 | slPagination | The page size it starts from, read once |
+| `siblingCount` | `number` | 1 | slPagination | Pages drawn either side of the current one |
+| `boundaryCount` | `number` | 1 | slPagination | Pages drawn at each end of the row |
+| `pageSizeOptions` | `readonly number[]` | [10, 20, 50, 100] | slPagination | What the page-size control offers |
+| `itemHref` | `(page: number) => string` | — | slPagination | Turns every page and every trigger into an anchor with a real destination |
+| `messages` | `Partial<PaginationMessages>` | — | slPagination | Words laid over the language in force, key by key: the landmark’s name (label), every control and both sentences |
+| `live` | `'polite' \| 'off'` | polite | slPagination | Whether the range announces a page change |
+| `disabled` | `boolean` | false | slPagination | Takes every control away without taking the row out of the page |
+| `loading` | `boolean` | false | slPagination | A page change in flight: the controls refuse, the row keeps its size, and the root says aria-busy |
+| `exportAs="slPagination"` | `template reference` | — | Template | Reaches the instance for goToPage, next, previous, reset and setPageSize, plus the arithmetic they were derived from |
+| `providePaginationDefaults` | `siblingCount \| boundaryCount \| defaultPageSize \| pageSizeOptions \| live` | — | Application | Sets those five once for the whole injector; an input on the paginator still wins |
+| `aria-label` | `attribute` | — | The nav | A static label written straight onto the element survives the host binding, so the consumer’s own name is never rewritten |
+| `ng-content` | `projection` | — | slPaginationStatus, sl-pagination-page-size | Replaces the range sentence and the page-size label with your own wording, without replacing the element or its live region |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `pageChange` | `ChangeRequest<number>` | Before the page moves. The request carries the page it replaces, the reason — pointer, keyboard or programmatic — and the originating event, and cancelling it commits nothing. programmatic is the family’s own move: the collection shrank under a reader who was past its new end, or the page size changed and the page followed the reader’s first item. |
+| `pageSizeChange` | `ChangeRequest<number>` | Before the page size moves, with the reason select. The page that follows arrives as a second pageChange carrying programmatic, because nobody asked for it directly and a consumer holding both values has to be told about both. |
+
+## Rules
+
+- The rendered root is the consumer’s own nav, named so a page carrying several landmarks can tell them apart. Nothing here is a widget: a row of controls inside a landmark is a row of tab stops, so the family binds no key of its own and Tab, Enter and Space are the platform’s.
+- The page being read carries aria-current="page" — the value the ARIA specification names for a link within a set of pagination links — and that attribute is also what paints its fill, so what a screen reader announces and what the eye sees are one fact rather than two.
+- The range is a polite live region, and it is the only one: a paginator that also announced its label would say the same thing twice. It reports the new range after the page settles, and live="off" silences it where an application announces the page itself.
+- A trigger at a bound stays in the page rather than disappearing, so the row does not reflow under the pointer. In button mode it takes the native disabled; in link mode it loses its href and says aria-disabled, because an anchor has no disabled attribute and one that kept its destination would still navigate on a middle click.
+- The page size is a native select wrapped by its own label, which gives the control its accessible name from the platform with no generated id, and its popup follows the colour scheme the theme already emits.
+- Below 22rem of the family’s own inline size the numbered row is replaced by "Page 3 of 24". Both are rendered and exactly one is displayed, so neither is announced twice — and where no summary exists to replace it, as in a cursor paginator, the range is kept instead.
+- A disabled or loading paginator mutes the current page’s chip into the disabled palette while keeping its shape: the reader still sees which page they are on, and nothing in a greyed row reads as the one thing still operable.
+
+## Tokens
+
+`--slotted-border-strong`, `--slotted-control-border-color`, `--slotted-control-border-width`, `--slotted-control-font-size-md`, `--slotted-control-height-md`, `--slotted-control-icon-size-md`, `--slotted-control-padding-inline-sm`, `--slotted-control-radius`, `--slotted-control-shadow`, `--slotted-control-surface`, `--slotted-control-transition-duration`, `--slotted-control-transition-easing`, `--slotted-disabled-background`, `--slotted-disabled-border`, `--slotted-disabled-foreground`, `--slotted-focus-ring-color`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`, `--slotted-font-family-sans`, `--slotted-font-weight-medium`, `--slotted-pagination-color`, `--slotted-pagination-color-disabled`, `--slotted-pagination-color-muted`, `--slotted-pagination-current-color`, `--slotted-pagination-current-surface`, `--slotted-pagination-ellipsis-lift`, `--slotted-pagination-ellipsis-tracking`, `--slotted-pagination-font-family`, `--slotted-pagination-font-size`, `--slotted-pagination-gap`, `--slotted-pagination-glyph-size`, `--slotted-pagination-item-gap`, `--slotted-pagination-item-padding`, `--slotted-pagination-item-weight`, `--slotted-pagination-page-size-gap`, `--slotted-pagination-page-size-inset`, `--slotted-pagination-page-size-surface`, `--slotted-pagination-radius`, `--slotted-pagination-row-gap`, `--slotted-pagination-surface-active`, `--slotted-pagination-surface-hover`, `--slotted-pagination-target`, `--slotted-pagination-text-gap`, `--slotted-space-1`, `--slotted-space-2`, `--slotted-space-3`, `--slotted-space-4`, `--slotted-space-6`, `--slotted-text`, `--slotted-text-muted`, `--slotted-tone-accent-on-solid`, `--slotted-tone-accent-solid`, `--slotted-tone-accent-subtle-active`, `--slotted-tone-accent-subtle-hover`
+
+## Examples
+
+### The row of pages
+
+Seven items at every page: a boundary, a gap, the current page and its siblings, a gap, a boundary. Walk through it and nothing moves except the numbers.
+
+Excerpt — not a complete module
+
+```html
+<nav slPagination [count]="482" [siblingCount]="2" [boundaryCount]="2">
+  <sl-pagination-items />
+</nav>
+```
+
+### A total the server does not know
+
+No count, so there are no page numbers to draw and the family invents none. Two triggers and a sentence are the whole paginator.
+
+Excerpt — not a complete module
+
+```html
+<nav slPagination (pageChange)="fetch($event.value)">
+  <button slPaginationPrevious type="button"></button>
+  <p slPaginationStatus>Showing the first 20 results</p>
+  <button slPaginationNext type="button"></button>
+</nav>
+```
+
+### Which items this page holds
+
+The sentence the numbers do not say, in a polite live region: a reader who cannot see the row hears the new range once, after the page settles.
+
+Excerpt — not a complete module
+
+```html
+<nav slPagination [count]="482">
+  <p slPaginationStatus></p>
+</nav>
+
+<nav slPagination [count]="482" live="off">
+  <p slPaginationStatus></p>
+</nav>
+```
+
+### How many rows a page holds
+
+Changing it keeps the reader’s first item visible rather than clamping them to the end or resetting them to page one, and the page that follows is reported as programmatic.
+
+Excerpt — not a complete module
+
+```html
+<nav slPagination [count]="482" [pageSizeOptions]="[25, 50, 100]">
+  <sl-pagination-page-size />
+  <p slPaginationStatus></p>
+</nav>
+```
+
+### Pages a crawler can follow
+
+One input turns every page and every trigger into an anchor with a real destination, so a middle click opens page four in a tab and a bookmark still works.
+
+Excerpt — not a complete module
+
+```html
+<nav slPagination [count]="482" [itemHref]="pageUrl">
+  <a slPaginationPrevious></a>
+  <sl-pagination-items />
+  <a slPaginationNext></a>
+</nav>
+```
+
+### Narrow enough to lose the row
+
+Below 22rem of its own inline size the numbered row gives way to "Page 3 of 24" and the triggers stay. Resize the column and watch the swap happen without the viewport changing.
+
+Excerpt — not a complete module
+
+```html
+<!-- The compaction is the family’s own container query.
+     A paginator in a split pane compacts; the same one on a full page does not. -->
+<nav slPagination [count]="482">
+  <sl-pagination-items />
+</nav>
+```
+
+### States
+
+A trigger at a bound is unavailable rather than absent, a page change in flight refuses every press, and a disabled paginator keeps its current chip in the disabled palette.
+
+Excerpt — not a complete module
+
+```html
+<nav slPagination [count]="482" [loading]="pending()">
+  <sl-pagination-items />
+</nav>
+
+<nav slPagination [count]="482" disabled>
+  <sl-pagination-items />
+</nav>
+```
+
+### Content the paginator did not choose
+
+Ten thousand pages. The figures are tabular and each box is at least as wide as it is tall, so page 9 and page 8 942 are the same target and the row does not move.
+
+Excerpt — not a complete module
+
+```html
+<nav slPagination [count]="200000" [pageSize]="20" [page]="8942">
+  <sl-pagination-items />
+</nav>
+```
+
+### Composition
+
+providePaginationDefaults decides the row width for a whole injector, provideSlotted the language, and exportAs reaches the instance for goToPage, next, previous and reset.
+
+Excerpt — not a complete module
+
+```html
+<nav slPagination #pager="slPagination" [count]="482">
+  <sl-pagination-items />
+</nav>
+<button type="button" (click)="pager.reset()">Back to the first page</button>
+```
+
+### Keyboard and announcement
+
+Tab reaches every control in reading order and Enter or Space activates it; the family binds no key of its own, because a list of controls inside a landmark is a list of tab stops.
+
+Excerpt — not a complete module
+
+```html
+<!-- The landmark is named, each trigger says which page it moves to,
+     and the range announces the new page once it settles. -->
+<nav slPagination aria-label="Invoices" [count]="482">
+  <button slPaginationPrevious type="button"></button>
+  <sl-pagination-items />
+  <button slPaginationNext type="button"></button>
+  <p slPaginationStatus></p>
+</nav>
+```