prime-ui-kit 0.7.13 → 0.9.1

package/src/components/pagination/COMPONENT.md

@@ -1,123 +1,132 @@
 # Pagination
 
-**Default `size`:** use **`m`** for the size axis unless the toolbar or table footer explicitly needs another tier.
+**Category:** navigation
+**Kind:** navigation
 
-## Canonical
+> Page-by-page navigation: arrows, page numbers with ellipsis and a compact «3 / 12» view.
 
-- **`Pagination`** is a single compound export: **`Pagination.Root`** only (`Pagination = { Root }`).
-- **Controlled API:** **`page`**, **`totalPages`**, and **`onPageChange`** are all required; there is no uncontrolled mode.
-- **Semantics:** root is a **`nav`** with **`aria-label="Pagination"`**, **`data-size`**, previous/next **ghost** **`Button.Root`** cells with **`Button.Icon`**, numeric page **`Button.Root`** cells (current page **`primary`** **`filled`**), and ellipsis **`span`**s (**`aria-hidden`**).
-- **Range logic:** if **`totalPages ≤ 7`**, every page index is shown; otherwise the row is shortened with **`siblingCount`** (default **`1`**) and **`…`** segments while keeping first and last pages visible.
-- **Edge cases:** **`totalPages < 1`** renders **`null`**; **`page`** is clamped to **`1 … totalPages`** for display and clicks; previous/next are **`disabled`** on the first/last page.
-- **Copy:** arrow and **“Page N”** strings are fixed in the implementation (English); there are no i18n props on **`Pagination`**.
+## When to use
+- Lists and tables split into pages, usually in their footer.
+- Narrow places (cards, mobile footers) — `compact` or `compact="auto"`.
 
-## Extended
-
-### About
-
-Chunked navigation for lists and tables: chevron previous/next, numbered pages, and ellipses for long ranges.
-
-- **Use** when the dataset is split into discrete pages and **`totalPages`** is known (server-driven or client-side paging).
-- **Use** in table footers, list toolbars, or search result bars alongside a short range summary.
-- **Do not use** as the only paging affordance when the product is infinite-scroll-only with no page index.
-- **Do not use** when **`totalPages < 1`** and you still need chrome—**`Pagination.Root`** returns nothing; show an empty state or omit the bar in the parent.
-- **Do not use** when you must replace inner markup or strings; structure and **Button** wiring are fixed—fork or wrap at app level if you need deep customization.
-
-### Composition
-
-- **`Pagination.Root`** — the only public part. Renders the **`nav`** row; **`className`** merges onto that **`nav`** only.
-- Full-width or “meta left / pager right” layouts are parent responsibility (flex or grid around **`Pagination.Root`**)—there is no **`fullWidth`** prop on **`Pagination`**.
-
-### Playground snippets
-
-Demos match **`playground/sections/PaginationSection.tsx`** (order and intent). Sources use **`@/`** under **`playground/snippets/pagination/`**; section descriptions and some labels are Russian in the playground UI.
-
-| Playground block | Snippet | Intent |
-|------------------|---------|--------|
-| Размеры | [`sizes.tsx`](../../../playground/snippets/pagination/sizes.tsx) (+ [`sizes.module.css`](../../../playground/snippets/pagination/sizes.module.css)) | **`size`** **`s`–`xl`**, long range (**`totalPages={20}`**), local state per row |
-| Диапазон номеров | [`range-modes.tsx`](../../../playground/snippets/pagination/range-modes.tsx) (+ [`rows.module.css`](../../../playground/snippets/pagination/rows.module.css)) | All indices when **`totalPages ≤ 7`** vs ellipsis row when larger |
-| Состояния | [`states.tsx`](../../../playground/snippets/pagination/states.tsx) | First / last / single-page arrow **`disabled`** semantics |
-| Контролируемый режим | [`controlled.tsx`](../../../playground/snippets/pagination/controlled.tsx) (+ [`controlled.module.css`](../../../playground/snippets/pagination/controlled.module.css)) | Shared **`page`** with external jump buttons |
-| Full width | [`full-width.tsx`](../../../playground/snippets/pagination/full-width.tsx) (+ [`full-width.module.css`](../../../playground/snippets/pagination/full-width.module.css)) | Flex toolbar: meta left, pager right (no **`fullWidth`** prop) |
-| Специфичные фичи | [`features.tsx`](../../../playground/snippets/pagination/features.tsx) | **`siblingCount`** **`0`** / **`2`**; **`totalPages=0`** → **`null`** |
-
-### Scenarios (see `examples/`)
-
-| Scenario | Approach |
-|----------|----------|
-| Size ladder | Same as playground **Размеры**; package copy in English. → [`examples/sizes.tsx`](examples/sizes.tsx) |
-| Range modes | Same as playground **Диапазон номеров**. → [`examples/range-modes.tsx`](examples/range-modes.tsx) |
-| Disabled arrows / single page | Same as playground **Состояния**. → [`examples/states.tsx`](examples/states.tsx) |
-| Sibling window + empty data | Same as playground **Специфичные фичи** (`siblingCount`, `totalPages=0`). → [`examples/features.tsx`](examples/features.tsx) |
-| Table footer | Pair a range summary with **`Pagination.Root`** in a footer row; keep **`page`** in sync with fetched rows. → [`examples/table-footer.tsx`](examples/table-footer.tsx) |
-| Compact toolbar | Set **`size="s"`** for denser toolbars or mobile-adjacent rows. → [`examples/compact.tsx`](examples/compact.tsx) |
-| Full-width list bar | **`display: flex`**, **`justify-content: space-between`**, **`flex-wrap`**: meta text + pager. → [`examples/full-width-list.tsx`](examples/full-width-list.tsx) |
-| Controlled page index | Store **`page`** in React state (or router); update from **`onPageChange`** and any other controls (e.g. jump to first/last). → [`examples/controlled-page.tsx`](examples/controlled-page.tsx) |
-| Canonical wiring | Minimal **`Pagination.Root`** with required props; short row + long row with **`siblingCount`**. → [`examples/canonical-composition.tsx`](examples/canonical-composition.tsx) |
-
-### Minimal example
+## 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 → [DataTable](../data-table/COMPONENT.md) already renders Pagination in its footer.
 
+## Import
 ```tsx
 import { Pagination } from "prime-ui-kit";
-
-export function Example() {
-  return (
-    <Pagination.Root page={1} totalPages={5} onPageChange={() => {}} />
-  );
-}
 ```
 
-### Canonical composition (reference)
-
-For **default wiring**, **long ranges**, and **`siblingCount`**, open **`examples/canonical-composition.tsx`** next to this file. Imports use **`"prime-ui-kit"`** so snippets work in an app after installing the package.
-
-### Example files in `examples/`
-
-| File | Scenario |
-|------|----------|
-| `sizes.tsx` | **`size`** ladder + long range (mirror [`sizes.tsx`](../../../playground/snippets/pagination/sizes.tsx)) |
-| `range-modes.tsx` | Short vs long `totalPages` (mirror [`range-modes.tsx`](../../../playground/snippets/pagination/range-modes.tsx)) |
-| `states.tsx` | First / last / single page (mirror [`states.tsx`](../../../playground/snippets/pagination/states.tsx)) |
-| `controlled-page.tsx` | Controlled `page` + jump buttons (mirror [`controlled.tsx`](../../../playground/snippets/pagination/controlled.tsx)) |
-| `full-width-list.tsx` | Full-width bar (mirror [`full-width.tsx`](../../../playground/snippets/pagination/full-width.tsx)) |
-| `features.tsx` | `siblingCount` and `totalPages=0` (mirror [`features.tsx`](../../../playground/snippets/pagination/features.tsx)) |
-| `canonical-composition.tsx` | Required props, default size, short row + long row with `siblingCount` |
-| `table-footer.tsx` | Table footer: row range + pager |
-| `compact.tsx` | Compact row: `size="s"` |
-
-### Rules
-
-- **Controlled only:** **`page`**, **`totalPages`**, and **`onPageChange`** are required.
-- **`page`** is clamped internally to **`1 … totalPages`** before rendering and when handling clicks.
-- If **`totalPages < 1`**, the component returns **`null`**.
-- The active page button sets **`aria-current="page"`**; other page buttons use **`aria-label`** of the form **`Page {n}`**; arrows use **“Previous page”** / **“Next page”**.
-- Syncing **`page`** to the URL, router, or query params is the parent’s responsibility.
+## 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
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| page | `number` | — | Yes | Current page; clamped to `1 … totalPages` for display and navigation |
-| totalPages | `number` | — | Yes | Page count; if `< 1`, renders nothing |
-| onPageChange | `(page: number) => void` | — | Yes | Called when the user selects a page or an arrow |
-| siblingCount | `number` | `1` | No | How many page indices to show on each side of the current page when `totalPages > 7` |
-| size | `"s" \| "m" \| "l" \| "xl"` | `"m"` | No | Control and ellipsis scale (`--prime-sys-size-control-*`) |
-| className | `string` | — | No | Extra class on the root `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`. |
+| `defaultValue` | `number` | `1` | Initial page, uncontrolled. |
+| `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` | 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` | 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 | |
+
+### siblingCount
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| 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"` 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` |
+| size / compact | `size`, `compact` | `data-size`, `data-compact` (`"true"` · `"false"` · `"auto"`) |
+
+## Layout & spacing
+- 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
+
+### Keyboard
+| Key | Action |
+|---|---|
+| `Tab` | Moves between the arrows and the page numbers. |
+| `Enter` · `Space` | Opens the focused page. |
+
+### 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`.
+
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+| 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`.
+- 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
-
-- [Button](../button/COMPONENT.md) — page and arrow cells are **`Button.Root`** + **`Button.Icon`**.
-- [DataTable](../data-table/COMPONENT.md) — typical host for a footer pager.
-
-## LLM note
-
-- **Playground:** demos and order — **`playground/sections/PaginationSection.tsx`** + **`playground/snippets/pagination/*.tsx`**; **`examples/`** files in the table above mirror those snippets with **`prime-ui-kit`** imports where noted.
-- **Imports:** **`import { Pagination } from "prime-ui-kit"`** — use **`Pagination.Root`** only; there is no flat **`Pagination`** element.
-- **Props:** **`page`**, **`totalPages`**, **`onPageChange`** required; optional **`siblingCount`**, **`size`**, **`className`**.
-- **`size`** literals: **`s`**, **`m`**, **`l`**, **`xl`** — default **`m`**; maps to **`data-size`** on the root **`nav`**.
-- **`totalPages < 1`:** render is **`null`** — parent must handle empty data or hide the footer.
-- **No uncontrolled mode** — always pass **`page`** and **`onPageChange`**; lift state to the parent or router.
-- **Layout:** no **`fullWidth`** on **`Pagination`**; wrap in flex/grid and align in the parent.
-- **Strings:** labels are English and built-in; do not assume i18n props exist on **`Pagination`**.
+- **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

@@ -0,0 +1,24 @@
+/* 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;
+  flex-wrap: wrap;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--prime-space-3);
+  padding: var(--prime-space-3) var(--prime-space-4);
+}
+
+.controls {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--prime-space-4);
+}
+
+/* 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,50 +1,19 @@
-import { Pagination, type PaginationSize } 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";
 
-function PaginationSizeRow({ size }: { size: PaginationSize }) {
-  const [page, setPage] = React.useState(8);
+const SIZES = ["xs", "s", "m", "l", "xl"] as const;
 
-  return (
-    <div
-      style={{
-        display: "flex",
-        flexDirection: "column",
-        gap: "var(--prime-sys-spacing-x2)",
-        alignItems: "flex-start",
-      }}
-    >
-      <p
-        style={{
-          margin: 0,
-          fontSize: "var(--prime-sys-size-control-s-supportText)",
-          color: "var(--prime-sys-color-content-secondary)",
-        }}
-      >
-        {size}
-      </p>
-      <Pagination.Root page={page} totalPages={20} onPageChange={setPage} size={size} />
-    </div>
-  );
-}
-
-/**
- * Four control tiers on a long page row (arrows, numbers, ellipsis share one scale per `size`).
- * Parity with `playground/snippets/pagination/sizes.tsx`.
- */
 export default function PaginationSizesExample() {
   return (
-    <div
-      style={{
-        display: "flex",
-        flexDirection: "column",
-        gap: "var(--prime-sys-spacing-x4)",
-        alignItems: "center",
-      }}
-    >
-      <PaginationSizeRow size="s" />
-      <PaginationSizeRow size="m" />
-      <PaginationSizeRow size="l" />
-      <PaginationSizeRow size="xl" />
+    <div>
+      {SIZES.map((size) => (
+        <div key={size}>
+          <Pagination size={size} totalPages={12} defaultValue={4} />
+          <Typography as="span" variant="caption" tone="muted">
+            {size}
+          </Typography>
+        </div>
+      ))}
     </div>
   );
 }