prime-ui-kit 0.9.0 → 0.9.1

package/src/components/pagination/COMPONENT.md

@@ -1,6 +1,7 @@
 # Pagination
 
 **Category:** navigation
+**Kind:** navigation
 
 > Page-by-page navigation: arrows, page numbers with ellipsis and a compact «3 / 12» view.
 
@@ -11,113 +12,121 @@
 ## When not to use
 - Steps of a process with names and statuses → use [Stepper](../stepper/COMPONENT.md).
 - Switching sections of one screen → use [Tabs](../tabs/COMPONENT.md).
-- A table with its own footer → [DataTable](../data-table/COMPONENT.md) already includes pagination.
+- A table → [DataTable](../data-table/COMPONENT.md) already renders Pagination in its footer.
 
 ## Import
 ```tsx
 import { Pagination } from "prime-ui-kit";
 ```
 
+## Anatomy
+```
+Pagination              <nav aria-label={labels.nav}>; size and compact mode
+├─ previous             ghost icon-only Button (nav.chevronLeft)
+├─ pages                ghost Buttons with numbers; «…» for skipped ranges (aria-hidden)
+├─ summary              «3 / 12» in the compact view
+└─ next                 ghost icon-only Button (nav.chevronRight)
+```
+
 ## API
 
-### Pagination.Root
-Renders `<nav>`; does not forward a ref. + native `<nav>` props (`HTMLAttributes<HTMLElement>` except `defaultValue`, `onChange`); `aria-label` always comes from `labels.nav`.
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+### Pagination
+`ref` → `HTMLElement`. A `<nav>` named by `labels.nav` with ghost `Button`s: previous, page numbers with ellipses, next.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `totalPages` | `number` | — (required) | Number of pages. Below `1` nothing is rendered. |
-| `value` | `number` | — | Current page (1-based), controlled. Clamped to `1…totalPages`. |
+| `value` | `number` | — | Current page (1-based), controlled; clamped to `1…totalPages`. |
 | `defaultValue` | `number` | `1` | Initial page, uncontrolled. |
-| `onValueChange` | `(page: number) => void` | — | Called on a page button or arrow click (not when the page does not change). |
-| `siblingCount` | `number` | `1` | Pages on each side of the current one before an ellipsis (only when `totalPages > 7`). |
-| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Control tier: button height, radius, text, icon. |
-| `compact` | `boolean \| "auto"` | `false` | `true` — arrows + «current / total» instead of numbers; `"auto"` — fills the parent and switches to compact when the container is narrower than 22rem. |
-| `labels` | `Partial<PaginationLabels>` | see Accessibility | Screen-reader strings. |
-| `className` | `string` | — | Extra class on the `nav`. |
+| `onValueChange` | `(page: number) => void` | — | Called when a page button or an arrow picks another page. |
+| `siblingCount` | `number` | `1` | Pages on each side of the current one before an ellipsis (when `totalPages > 7`). |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Control tier of the buttons: height 28 · 32 · 36 · 40 · 48. |
+| `compact` | `boolean \| "auto"` | `false` | `true` — arrows + «current / total» instead of numbers; `"auto"` — fills the parent and turns compact below 22rem of its width. |
+| `labels` | `Partial<PaginationLabels>` | — | Built-in strings, see Labels. |
+| `…rest` | `Omit<HTMLAttributes<HTMLElement>, "defaultValue" \| "onChange">` | — | `className`, `data-*` and the other `<nav>` attributes; `aria-label` comes from `labels.nav`. |
 
 ## Variants
 
 ### compact
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| `false` | ghost arrow buttons around page numbers; ellipsis «…» for skipped ranges | desktop list and table footers | yes |
-| `true` | arrows around «3 / 12» (current in primary medium, total muted, tabular numbers) | cards, mobile footers, tight toolbars | |
-| `"auto"` | `display: block; width: 100%`; full view right-aligned, below 22rem container width the compact view with arrows at the edges | responsive footers (DataTable uses this) | |
+| `false` | arrows around page numbers; «…» for skipped ranges | desktop list and table footers | yes |
+| `true` | arrows around «3 / 12» (current in primary medium, total muted, tabular figures) | cards, mobile footers, tight toolbars | |
+| `"auto"` | fills the parent; the full row right-aligned, below 22rem of container width the compact view with arrows at the edges | responsive footers (DataTable uses it) | |
 
 ### size
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| `xs` | 28px square buttons, 12/16 text, icon 14, no gap | dense tables | |
-| `s` | 32px, 13/20, icon 16, gap 4 | list and table footers next to an `s` Select | |
-| `m` | 36px, 14/20, icon 16, gap 4 | default | yes |
-| `l` | 40px, 16/24, icon 20, gap 4 | large layouts | |
-| `xl` | 48px, 16/24, icon 20, gap 8 | touch-first screens | |
+| `xs` | 28 px buttons, 12/16 text, no gap | dense tables | |
+| `s` | 32 px, 13/20, gap 4 | list footers next to an `s` Select | |
+| `m` | 36 px, 14/20, gap 4 | most places | yes |
+| `l` | 40 px, 16/24, gap 4 | large layouts | |
+| `xl` | 48 px, 16/24, gap 8 | touch-first screens | |
 
-Button height equals the control height: Pagination lines up with Button, Input and Select of the same `size`.
-
-### Page range
+### siblingCount
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| `totalPages ≤ 7` | every page number, no ellipsis | short lists | |
-| `siblingCount={1}` | 1 … 19 20 21 … 40 | most lists | yes |
-| `siblingCount={2}` | 1 … 18 19 20 21 22 … 40 | wide footers, frequent jumps | |
-
-**Combinations**
-- Recommended: `size="s"` with a rows-per-page Select of the same size in a list footer; `compact="auto"` when the footer can get narrow.
-- Avoid: a large `siblingCount` together with `compact="auto"` in a narrow container — the full row overflows before it collapses.
+| any, `totalPages ≤ 2 × siblingCount + 5` (7 by default) | every page number, no ellipsis | short lists | |
+| `1` | 1 … 19 20 21 … 40 | most lists | yes |
+| `2` | 1 … 18 19 20 21 22 … 40 | wide footers, frequent jumps | |
 
 ## States
 | State | Driven by | DOM |
 |---|---|---|
-| current page | `value` / `defaultValue` | `aria-current="page"`, `data-current="true"`, `accent-soft` fill + accent text |
-| hover / active | pointer | `fill-subtle` / `fill-subtle-active`, primary text |
-| focus-visible | keyboard | outer focus ring |
+| current page | `value` / `defaultValue` | `aria-current="page"` on a soft accent Button: `accent-soft` fill, `accent-text` |
+| hover / active | pointer | `fill-subtle` / `fill-subtle-active`, primary text, press scale |
+| focus-visible | keyboard | outer focus ring of the Button |
 | disabled arrow | first / last page | native `disabled`, `text-disabled` |
-
-Root attributes: `data-size`, `data-compact` (`"true"` / `"false"` / `"auto"`). Controlled: `value` + `onValueChange`; uncontrolled: `defaultValue`.
+| size / compact | `size`, `compact` | `data-size`, `data-compact` (`"true"` · `"false"` · `"auto"`) |
 
 ## Layout & spacing
-- In a list footer: range text on the left, controls on the right (`justify-content: space-between`), `gap: var(--prime-space-6)` between the per-page Select and the pager; let the row wrap.
+- In a list footer: the range text on the left, rows-per-page Select and Pagination on the right (`justify-content: space-between`), the row wraps.
 - `compact="auto"` needs a parent with a width — it is a size container.
+- Page numbers keep a square footprint up to two digits; wider numbers grow the button.
 
 ## Accessibility
-- `nav` landmark with `aria-label`; page buttons have `aria-label` from `labels.page(n)` and the current one `aria-current="page"`; the ellipsis is `aria-hidden`.
-- Compact view reads «3 из 12» via the visually hidden `labels.of`.
-- Keyboard: Tab through buttons, Enter/Space activates.
 
-| `labels` key | Default | Used for |
-|---|---|---|
-| `nav` | `"Навигация по страницам"` | `aria-label` of the `nav` |
-| `previous` | `"Предыдущая страница"` | previous arrow |
-| `next` | `"Следующая страница"` | next arrow |
-| `page` | `(page) => \`Страница ${page}\`` | page button `aria-label` |
-| `of` | `"из"` | hidden word between current and total in the compact view |
+### Keyboard
+| Key | Action |
+|---|---|
+| `Tab` | Moves between the arrows and the page numbers. |
+| `Enter` · `Space` | Opens the focused page. |
 
-## Examples
-| File | Scenario | When to use this pattern |
-|---|---|---|
-| [list-footer.tsx](examples/list-footer.tsx) | Range + rows-per-page Select + `s` pagination | list and table footers |
-| [sizes.tsx](examples/sizes.tsx) | Every size next to a Button of the same size | aligning with controls |
-| [states.tsx](examples/states.tsx) | Disabled edge arrows, ≤ 7 pages, `siblingCount` 1 and 2 | choosing the range behaviour |
-| [compact.tsx](examples/compact.tsx) | `compact` and `compact="auto"` at 36rem and 20rem | narrow and responsive footers |
+### ARIA
+- A `<nav>` landmark named by `labels.nav`.
+- The current page has `aria-current="page"`; every page button is named by `labels.page` («Страница 3»).
+- The edge arrows are `disabled`; the ellipsis is `aria-hidden`.
+- The compact view reads «3 из 12» through the visually hidden `labels.of`.
 
-```tsx
-import { Pagination } from "prime-ui-kit";
-import * as React from "react";
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
-export function OrdersPager() {
-  const [page, setPage] = React.useState(1);
-  return <Pagination.Root value={page} totalPages={12} onValueChange={setPage} />;
-}
-```
+| Key | Default | Used for |
+|---|---|---|
+| `nav` | `"Навигация по страницам"` | `aria-label` of the `<nav>`. |
+| `previous` | `"Предыдущая страница"` | Name of the previous-page arrow. |
+| `next` | `"Следующая страница"` | Name of the next-page arrow. |
+| `page` | `"Страница {page}"` | Name of a page button; `{page}` is replaced. |
+| `of` | `"из"` | Hidden word between the current and the total page in the compact view. |
+
+## Examples
+| Example | Shows |
+|---|---|
+| [overview.tsx](examples/overview.tsx) | Pages of an order list: arrows, page numbers and the current page — `totalPages`, `defaultValue`. |
+| [sizes.tsx](examples/sizes.tsx) | Every size tier; buttons are as high as Button and Input of the same tier, 28 to 48 px — `size`. |
+| [overflow.tsx](examples/overflow.tsx) | Up to 7 pages without an ellipsis, then a window around the current page; a wider window — `siblingCount`. |
+| [controlled.tsx](examples/controlled.tsx) | A list footer owns the page: changing rows per page returns it to page 1 — `value`, `onValueChange`. |
+| [narrow.tsx](examples/narrow.tsx) | A 320 px card footer: `compact` always shows «current / total», `compact="auto"` switches by the container width — `compact`. |
 
 ## Mistakes
 - `page` / `onPageChange` → use `value` / `onValueChange`.
-- 0-based page index → pages start at `1`.
-- Passing `aria-label` to change the landmark name → use `labels={{ nav: "…" }}`.
+- A 0-based page index → pages start at `1`.
+- Passing `aria-label` to rename the landmark → use `labels={{ nav: "…" }}`.
 - `compact="auto"` inside a shrink-wrapped flex item → give the parent a width.
+- A pager under a DataTable → the table renders its own.
 
 ## Related
-- [DataTable](../data-table/COMPONENT.md)
-- [Select](../select/COMPONENT.md)
-- [Stepper](../stepper/COMPONENT.md)
+- **Built from:** [Button](../button/COMPONENT.md)
+- **See also:** [DataTable](../data-table/COMPONENT.md), [Select](../select/COMPONENT.md), [Stepper](../stepper/COMPONENT.md)

package/src/components/pagination/examples/controlled.tsx

@@ -0,0 +1,51 @@
+/** A list footer owns the page: changing rows per page returns it to page 1 — `value`, `onValueChange`. */
+import { Card, Pagination, Select, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const TOTAL_INVOICES = 248;
+
+export default function PaginationControlledExample() {
+  const [perPage, setPerPage] = React.useState("25");
+  const [page, setPage] = React.useState(2);
+
+  const pageSize = Number(perPage);
+  const from = (page - 1) * pageSize + 1;
+  const to = Math.min(page * pageSize, TOTAL_INVOICES);
+
+  return (
+    <Card.Root>
+      <div className={styles.footer}>
+        <Typography as="span" variant="body-s" tone="secondary">
+          Счета {from}–{to} из {TOTAL_INVOICES}
+        </Typography>
+        <div className={styles.controls}>
+          <Select.Root
+            size="s"
+            value={perPage}
+            onValueChange={(next) => {
+              setPerPage(next);
+              setPage(1);
+            }}
+          >
+            <Select.Trigger aria-label="Строк на странице">
+              <Select.Value />
+            </Select.Trigger>
+            <Select.Content>
+              <Select.Item value="10">10 строк</Select.Item>
+              <Select.Item value="25">25 строк</Select.Item>
+              <Select.Item value="50">50 строк</Select.Item>
+            </Select.Content>
+          </Select.Root>
+          <Pagination
+            size="s"
+            value={page}
+            onValueChange={setPage}
+            totalPages={Math.ceil(TOTAL_INVOICES / pageSize)}
+          />
+        </div>
+      </div>
+    </Card.Root>
+  );
+}

package/src/components/pagination/examples/examples.module.css

@@ -1,44 +1,6 @@
-/* Layout for the Pagination examples: semantic tokens only. */
-
-.stack {
-  display: flex;
-  flex-direction: column;
-  align-items: center;
-  gap: var(--prime-space-5);
-  width: 100%;
-  min-width: 0;
-}
-
-/* caption · pagination · button of the same tier, columns aligned across rows */
-.sizeGrid {
-  display: grid;
-  grid-template-columns: auto auto auto;
-  align-items: center;
-  justify-items: start;
-  gap: var(--prime-space-4);
-  max-width: 100%;
-  overflow-x: auto;
-}
-
-.group {
-  display: flex;
-  flex-direction: column;
-  align-items: center;
-  gap: var(--prime-space-2);
-  width: 100%;
-  min-width: 0;
-}
-
-/* 320px. */
-.narrow {
-  width: min(100%, calc(var(--prime-drawer-width-s) - var(--prime-space-10)));
-}
-
-/* 576px. */
-.wide {
-  width: min(100%, calc(var(--prime-modal-width-m) + var(--prime-space-4)));
-}
+/* Layout of the Pagination scenarios: semantic tokens only. */
 
+/* A list footer in a Card: the range on the left, rows per page and pages on the right; wraps when narrow. */
 .footer {
   box-sizing: border-box;
   display: flex;
@@ -46,28 +8,17 @@
   align-items: center;
   justify-content: space-between;
   gap: var(--prime-space-3);
-  width: 100%;
   padding: var(--prime-space-3) var(--prime-space-4);
-  border-radius: var(--prime-card-radius);
-  background: var(--prime-color-card-bg);
-  box-shadow: var(--prime-card-shadow);
-  --prime-color-field-bg: var(--prime-color-field-bg-surface);
 }
 
-/* Right group: the per-page select sits next to the pager it controls. */
 .controls {
   display: flex;
   flex-wrap: wrap;
   align-items: center;
-  gap: var(--prime-space-6);
-}
-
-.summary {
-  font-variant-numeric: tabular-nums;
+  gap: var(--prime-space-4);
 }
 
-.perPage {
-  display: flex;
-  align-items: center;
-  gap: var(--prime-space-2);
+/* A 320 px card. */
+.narrow {
+  width: min(100%, calc(var(--prime-space-20) * 4));
 }

package/src/components/pagination/examples/narrow.tsx

@@ -0,0 +1,25 @@
+/** A 320 px card footer: `compact` always shows «current / total», `compact="auto"` switches by the container width — `compact`. */
+import { Card, Pagination, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function PaginationNarrowExample() {
+  return (
+    <Card.Root className={styles.narrow}>
+      <Card.Body>
+        <div>
+          <Pagination compact totalPages={12} defaultValue={3} />
+          <Typography as="span" variant="caption" tone="muted">
+            compact
+          </Typography>
+        </div>
+        <div>
+          <Pagination compact="auto" totalPages={12} defaultValue={3} />
+          <Typography as="span" variant="caption" tone="muted">
+            compact="auto"
+          </Typography>
+        </div>
+      </Card.Body>
+    </Card.Root>
+  );
+}

package/src/components/pagination/examples/overflow.tsx

@@ -0,0 +1,23 @@
+/** Up to 7 pages without an ellipsis, then a window around the current page; a wider window — `siblingCount`. */
+import { Pagination, Typography } from "prime-ui-kit";
+
+const CASES = [
+  { caption: "5 страниц", total: 5, page: 3, siblings: 1 },
+  { caption: "siblingCount 1", total: 40, page: 20, siblings: 1 },
+  { caption: "siblingCount 2", total: 40, page: 20, siblings: 2 },
+] as const;
+
+export default function PaginationOverflowExample() {
+  return (
+    <div>
+      {CASES.map(({ caption, total, page, siblings }) => (
+        <div key={caption}>
+          <Pagination totalPages={total} defaultValue={page} siblingCount={siblings} />
+          <Typography as="span" variant="caption" tone="muted">
+            {caption}
+          </Typography>
+        </div>
+      ))}
+    </div>
+  );
+}

package/src/components/pagination/examples/overview.tsx

@@ -0,0 +1,6 @@
+/** Pages of an order list: arrows, page numbers and the current page — `totalPages`, `defaultValue`. */
+import { Pagination } from "prime-ui-kit";
+
+export default function PaginationOverviewExample() {
+  return <Pagination totalPages={12} defaultValue={4} />;
+}

package/src/components/pagination/examples/sizes.tsx

@@ -1,26 +1,18 @@
-/** Pagination at every size tier next to a Button of the same size; heights match (28–48). Use to align the pager with neighbouring controls. */
-import { Button, type ControlSize, Pagination, Typography } from "prime-ui-kit";
-import * as React from "react";
+/** Every size tier; buttons are as high as Button and Input of the same tier, 28 to 48 px — `size`. */
+import { Pagination, Typography } from "prime-ui-kit";
 
-import styles from "./examples.module.css";
-
-const sizes: ControlSize[] = ["xs", "s", "m", "l", "xl"];
+const SIZES = ["xs", "s", "m", "l", "xl"] as const;
 
 export default function PaginationSizesExample() {
-  const [page, setPage] = React.useState(4);
-
   return (
-    <div className={styles.sizeGrid}>
-      {sizes.map((size) => (
-        <React.Fragment key={size}>
-          <Typography.Root as="span" variant="caption" tone="muted">
+    <div>
+      {SIZES.map((size) => (
+        <div key={size}>
+          <Pagination size={size} totalPages={12} defaultValue={4} />
+          <Typography as="span" variant="caption" tone="muted">
             {size}
-          </Typography.Root>
-          <Pagination.Root size={size} value={page} totalPages={12} onValueChange={setPage} />
-          <Button.Root variant="outline" tone="neutral" size={size}>
-            Кнопка {size}
-          </Button.Root>
-        </React.Fragment>
+          </Typography>
+        </div>
       ))}
     </div>
   );