prime-ui-kit 0.7.11 → 0.9.0

package/src/components/page-content/COMPONENT.md

@@ -1,128 +1,173 @@
 # PageContent
 
-## About
+**Category:** layout
 
-Семантические примитивы **контентной колонки**: **`PageContent.Section`** (регион страницы **`<section>`** без собственных внешних полей), **`PageContent.Root`** (обёртка страницы с опциональным **`maxWidth`**, **без** дублирующих полей к краю колонки), **`PageContent.Title`** → **`<h1>`**, **`PageContent.Description`** с **`measure`**, **`PageContent.Body`**. Типографика — токены кита.
+> Page structure inside the main column: title, description, page actions and content sections.
 
-- **С `AppShell.Template`** краевые поля колонки задаёт **`AppShell.Main`**. Для маршрута чаще берут **`PageContent.Section`** + **`Header`** / **`Body`**, либо **`PageContent.Root`** только ради **`maxWidth`**, без второго слоя полей.
-- **`PageContent.Root`** — когда нужен **`maxWidth`** (`full` | `readable` | `wide`; по умолчанию **`full`**) и структура шапки/тела; краевые поля **не** входят в корень — их даёт **`AppShell.Main`**.
-- **`Description`** с **`measure="full"`**, если ширину уже ограничивает родитель; по умолчанию **`measure="readable"`** — узкая мера лида ~65ch.
+## When to use
+- Every route rendered inside `AppShell.Main`: a page heading (`<h1>`), an intro line, page-level actions and the page body.
+- A text page held to a reading measure (`PageContent.Root maxWidth="readable"`).
+- A wide dashboard page capped at the content width (`maxWidth="wide"`).
 
-### Краевые поля колонки
-
-Они **не** задаются **`PageContent`**: их даёт **`AppShell.Main`**. Если контент «прилип» к краю экрана, проверьте шелл и стили — см. [AppShell](../../layout/app-shell/COMPONENT.md).
-
-## Composition
-
-- **`PageContent.Root`** — внешняя обёртка: **`maxWidth`** через `data-max-width` (кроме `full`), **padding по краям колонки — 0** (поля у **`AppShell.Main`**).
-- **`PageContent.Section`** — **`<section>`**; сочетайте с **`aria-labelledby`** на заголовок **`PageContent.Title`**.
-- **`PageContent.Header`** — заголовок + описание с отступами.
-- **`PageContent.Title`** — **`<h1>`** (один на вью).
-- **`PageContent.Description`** — лид **`<p>`**; **`measure`** — ширина текста.
-- **`PageContent.Body`** — блоки под шапкой.
-
-### Canonical example (маршрут внутри `AppShell.Template`)
+## When not to use
+- The app frame (navigation rail, header, scrolling main column) → use [AppShell](../../layout/app-shell/COMPONENT.md).
+- A bounded block inside the page → use [Card](../card/COMPONENT.md).
+- An empty / error / not-found page → use [EmptyPage](../empty-page/COMPONENT.md).
+- Arbitrary headings inside content → use [Typography](../typography/COMPONENT.md).
 
+## Import
 ```tsx
 import { PageContent } from "prime-ui-kit";
-
-export function SettingsPage() {
-  return (
-    <PageContent.Section aria-labelledby="page-heading">
-      <PageContent.Header>
-        <PageContent.Title id="page-heading">Settings</PageContent.Title>
-        <PageContent.Description measure="full">
-          Manage your workspace profile and notifications.
-        </PageContent.Description>
-      </PageContent.Header>
-      <PageContent.Body>{/* блоки страницы */}</PageContent.Body>
-    </PageContent.Section>
-  );
-}
 ```
 
-### Canonical example (узкая колонка + `maxWidth`)
-
-```tsx
-import { PageContent } from "prime-ui-kit";
-
-export function AccountPage() {
-  return (
-    <PageContent.Root maxWidth="readable">
-      <PageContent.Header>
-        <PageContent.Title>Account</PageContent.Title>
-        <PageContent.Description>Billing and security.</PageContent.Description>
-      </PageContent.Header>
-      <PageContent.Body>{/* … */}</PageContent.Body>
-    </PageContent.Root>
-  );
-}
+## Anatomy
+```
+PageContent.Root | PageContent.Section     column; Root adds maxWidth, Section renders <section>
+├── PageContent.Header                     heading column + actions in one wrapping row
+│   ├── PageContent.Title                  <h1>, heading-m
+│   ├── PageContent.Description            <p>, secondary body-m
+│   └── PageContent.Actions                page buttons (moved to the end of the header row)
+└── PageContent.Body                       page content, blocks 40 apart
 ```
-
-### Playground
-
-Живые примеры и таблицы API: **`playground/sections/PageContentSection.tsx`**.
-
-## Rules
-
-- На вью — **один** `h1` через **`PageContent.Title`**.
-- **Не** вкладывайте **`PageContent.Root`** так, чтобы дублировать краевые поля, которые уже даёт **`AppShell.Main`**.
-- **`Description`**: по умолчанию узкая мера; **`measure="full"`**, когда колонка уже ограничена снаружи.
 
 ## API
 
 ### PageContent.Root
+`forwardRef` to `<div>`.
 
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| maxWidth | `full` \| `readable` \| `wide` | `full` | No | Ограничение ширины контентной колонки; `data-max-width`, кроме `full`. |
-| className | `string` | — | No | Класс на корневой обёртке. |
-| children | `React.ReactNode` | — | No | Шапка, тело, секции. |
-| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | В т.ч. `ref` (`forwardRef`). |
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `maxWidth` | `"full" \| "readable" \| "wide"` | `"full"` | Max width of the column (centred with `margin-inline: auto`). |
+| `className` | `string` | — | Extra class. |
+| `children` | `ReactNode` | — | Header, Body. |
+
++ native `<div>` props.
 
 ### PageContent.Section
+`forwardRef` to `<section>`. Same column and rhythm as Root, without `maxWidth`.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `className` | `string` | — | Extra class. |
+| `children` | `ReactNode` | — | Header, Body. |
 
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| className | `string` | — | No | Класс на **`<section>`**. |
-| children | `React.ReactNode` | — | No | Обычно **`Header`** + **`Body`**. |
-| …rest | `React.HTMLAttributes<HTMLElement>` | — | No | В т.ч. `ref` (`forwardRef`). |
++ native `<section>` props (`HTMLAttributes<HTMLElement>`; use `aria-labelledby` pointing at the Title `id`).
 
 ### PageContent.Header
+Plain function component (no ref). Children of type `PageContent.Actions` are moved after the heading column; all other children go into the heading column.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `className` | `string` | — | Extra class. |
+| `children` | `ReactNode` | — | Title, Description, Actions. |
 
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| className | `string` | — | No | Класс на блоке шапки. |
-| children | `React.ReactNode` | — | No | **`Title`**, **`Description`**. |
-| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | Атрибуты `div`. |
++ native `<div>` props.
 
 ### PageContent.Title
+`forwardRef` to `<h1>`.
 
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| className | `string` | — | No | Класс на **`<h1>`**. |
-| children | `React.ReactNode` | — | No | Заголовок страницы. |
-| …rest | `React.HTMLAttributes<HTMLHeadingElement>` | — | No | В т.ч. `ref` (`forwardRef`). |
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `className` | `string` | — | Extra class. |
+| `children` | `ReactNode` | — | Page title. |
+
++ native `<h1>` props.
 
 ### PageContent.Description
+`forwardRef` to `<p>`.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `measure` | `"readable" \| "full"` | `"readable"` | `readable` caps the line at the reading width; `full` uses the full width of the parent. |
+| `className` | `string` | — | Extra class. |
+| `children` | `ReactNode` | — | Intro text. |
+
++ native `<p>` props.
+
+### PageContent.Actions
+Plain function component (no ref).
 
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| measure | `readable` \| `full` | `readable` | No | `readable` — ~65ch; `full` — ширина родителя. |
-| className | `string` | — | No | Класс на **`<p>`**. |
-| children | `React.ReactNode` | — | No | Вводный текст. |
-| …rest | `React.HTMLAttributes<HTMLParagraphElement>` | — | No | В т.ч. `ref` (`forwardRef`). |
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `className` | `string` | — | Extra class. |
+| `children` | `ReactNode` | — | Page buttons. |
+
++ native `<div>` props.
 
 ### PageContent.Body
+Plain function component (no ref).
 
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| className | `string` | — | No | Класс на обёртке контента под шапкой. |
-| children | `React.ReactNode` | — | No | Основное содержимое. |
-| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | Атрибуты `div`. |
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `className` | `string` | — | Extra class. |
+| `children` | `ReactNode` | — | Page content blocks. |
 
-## Related
++ native `<div>` props.
+
+## Variants
+
+### maxWidth (Root)
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `full` | Column fills the main area | App pages, tables, dashboards in a padded main | yes |
+| `readable` | Column capped at `--prime-layout-reading-max-width` (~65ch), centred | Terms, articles, help pages | |
+| `wide` | Column capped at `--prime-layout-content-max-width`, centred | Wide screens where content should not stretch edge to edge | |
+
+### measure (Description)
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `readable` | Intro line wraps at the reading width | Default, most pages | yes |
+| `full` | Intro uses the full header width | The column is already narrow, or the intro sits next to actions | |
+
+**Combinations** — `Root maxWidth="readable"` with the default Description measure for text pages; `Section` + `measure="full"` + `Actions` for app pages. `Description measure="full"` inside `Root maxWidth="readable"` changes nothing visible.
+
+**Hierarchy** — one `PageContent.Title` (`<h1>`) per page; sub-sections inside Body use `title-s` / `title-m` headings (`h2`). One primary button in Actions, the rest `soft`/`ghost` neutral.
+
+## States
+Static layout. DOM: `data-max-width="readable" | "wide"` on Root (absent for `full`), `data-measure="full"` on Description (absent for `readable`), `data-has-actions="true"` on Header when it contains Actions.
+
+## Layout & spacing
+- No outer padding: edge gutters come from `AppShell.Main`.
+- Header → Body `--prime-space-8` (32); blocks inside Body `--prime-space-10` (40); Title → Description `--prime-space-2` (8); buttons in Actions `--prime-space-2`.
+- Header is a wrapping row (`gap: --prime-space-4` / `--prime-space-6`): actions stay to the right of the title while the heading keeps half a reading measure, otherwise wrap below it — no breakpoint needed, works from 320px.
+- Title and Description wrap long words (`overflow-wrap: anywhere`).
+
+## Accessibility
+- Title is an `<h1>`; use one per page.
+- Give `PageContent.Section` an `aria-labelledby` that points at the Title `id` to name the region.
+- No keyboard behaviour, no `labels`.
 
-- [Typography](../typography/COMPONENT.md) — роли текста на странице.
-- [EmptyPage](../empty-page/COMPONENT.md) — пустое состояние списка или области данных (**`h2`**, не дублирует **`PageContent.Title`**).
-- [AppShell](../../layout/app-shell/COMPONENT.md) — сетка и **`Main`**.
+## Examples
+| File | Scenario | When to use this pattern |
+|---|---|---|
+| [settings-page.tsx](examples/settings-page.tsx) | Section with title, description, actions and panel cards in Body | App pages with page-level actions |
+| [readable.tsx](examples/readable.tsx) | `Root maxWidth="readable"` with reading text | Terms, articles, help pages |
+| [widths.tsx](examples/widths.tsx) | `Root maxWidth` full · wide · readable side by side | Choosing the column cap |
+
+```tsx
+import { Button, PageContent } from "prime-ui-kit";
+
+export function Example() {
+  return (
+    <PageContent.Section>
+      <PageContent.Header>
+        <PageContent.Title>Заказы</PageContent.Title>
+        <PageContent.Description>Все заказы за последний месяц.</PageContent.Description>
+        <PageContent.Actions>
+          <Button.Root>Создать заказ</Button.Root>
+        </PageContent.Actions>
+      </PageContent.Header>
+      <PageContent.Body>…</PageContent.Body>
+    </PageContent.Section>
+  );
+}
+```
+
+## Mistakes
+- Padding on `PageContent.Root` to imitate gutters → gutters come from `AppShell.Main`.
+- Actions placed outside Header → put `PageContent.Actions` inside `PageContent.Header` so it aligns with the title and wraps.
+- Several `PageContent.Title` on one page → one `<h1>`, sub-headings via Typography.
+- Margins between blocks in Body → Body already sets the 40 gap.
+
+## Related
+[AppShell](../../layout/app-shell/COMPONENT.md) · [Sidebar](../../layout/sidebar/COMPONENT.md) · [Card](../card/COMPONENT.md) · [EmptyPage](../empty-page/COMPONENT.md)

package/src/components/page-content/examples/examples.module.css

@@ -0,0 +1,26 @@
+/* Layout for the PageContent examples: the frame imitates AppShell.Main (canvas + gutter). */
+
+.main {
+  box-sizing: border-box;
+  width: 100%;
+  padding: var(--prime-layout-gutter-m);
+  border-radius: var(--prime-card-radius);
+  background: var(--prime-color-bg-canvas);
+  container-type: inline-size;
+}
+
+/* Several page columns stacked with the section rhythm. */
+.stack {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-space-10);
+}
+
+/* A visible block so the column width can be read at a glance. */
+.block {
+  box-sizing: border-box;
+  padding: var(--prime-space-4);
+  border-radius: var(--prime-card-radius);
+  background: var(--prime-color-card-bg);
+  box-shadow: var(--prime-card-shadow);
+}

package/src/components/page-content/examples/readable.tsx

@@ -0,0 +1,24 @@
+/** A text page in `PageContent.Root maxWidth="readable"`, held to ~65 characters per line. Use for terms, articles and help pages. */
+import { PageContent, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function PageContentReadableExample() {
+  return (
+    <div className={styles.main}>
+      <PageContent.Root maxWidth="readable">
+        <PageContent.Header>
+          <PageContent.Title>Условия использования</PageContent.Title>
+          <PageContent.Description>Обновлено 1 октября 2026 года.</PageContent.Description>
+        </PageContent.Header>
+        <PageContent.Body>
+          <Typography.Root as="p" variant="body-l">
+            Сервис помогает командам вести продажи и отчётность. Используя его, вы соглашаетесь
+            хранить доступы в тайне и не передавать их третьим лицам. Мы бережно обращаемся с
+            данными и удаляем их по первому запросу.
+          </Typography.Root>
+        </PageContent.Body>
+      </PageContent.Root>
+    </div>
+  );
+}

package/src/components/page-content/examples/settings-page.tsx

@@ -0,0 +1,49 @@
+/** A settings route inside AppShell.Main: header with title, description and actions, then panel cards in Body. Use for any app page with page-level actions. */
+import { Button, Card, Input, PageContent, Switch } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function PageContentSettingsPageExample() {
+  return (
+    <div className={styles.main}>
+      <PageContent.Section aria-labelledby="settings-heading">
+        <PageContent.Header>
+          <PageContent.Title id="settings-heading">Настройки</PageContent.Title>
+          <PageContent.Description measure="full">
+            Профиль рабочего пространства и уведомления.
+          </PageContent.Description>
+          <PageContent.Actions>
+            <Button.Root variant="soft" tone="neutral">
+              Экспорт
+            </Button.Root>
+            <Button.Root>Сохранить</Button.Root>
+          </PageContent.Actions>
+        </PageContent.Header>
+        <PageContent.Body>
+          <Card.Root variant="panel">
+            <Card.SectionHeader>
+              <Card.SectionTitle>Профиль</Card.SectionTitle>
+            </Card.SectionHeader>
+            <Card.Body>
+              <Input.Root label="Название компании">
+                <Input.Wrapper>
+                  <Input.Field defaultValue="Прайм Софт" />
+                </Input.Wrapper>
+              </Input.Root>
+            </Card.Body>
+          </Card.Root>
+          <Card.Root variant="panel">
+            <Card.SectionHeader>
+              <Card.SectionTitle>Уведомления</Card.SectionTitle>
+            </Card.SectionHeader>
+            <Card.Body>
+              <Switch.Root defaultChecked>
+                <Switch.Label>Письма о новых заказах</Switch.Label>
+              </Switch.Root>
+            </Card.Body>
+          </Card.Root>
+        </PageContent.Body>
+      </PageContent.Section>
+    </div>
+  );
+}

package/src/components/page-content/examples/widths.tsx

@@ -0,0 +1,39 @@
+/** `PageContent.Root maxWidth` full · wide · readable: the same page column at three caps. Use `wide` for dashboards on very wide screens, `readable` for text pages, `full` everywhere else. */
+import { PageContent, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const WIDTHS = [
+  { value: "full", title: "На всю ширину", text: "maxWidth: full — колонка занимает весь main." },
+  {
+    value: "wide",
+    title: "Широкая колонка",
+    text: "maxWidth: wide — не шире --prime-layout-content-max-width, по центру.",
+  },
+  {
+    value: "readable",
+    title: "Колонка для чтения",
+    text: "maxWidth: readable — около 65 знаков в строке, по центру.",
+  },
+] as const;
+
+export default function PageContentWidthsExample() {
+  return (
+    <div className={styles.main}>
+      <div className={styles.stack}>
+        {WIDTHS.map(({ value, title, text }) => (
+          <PageContent.Root key={value} maxWidth={value}>
+            <PageContent.Header>
+              <PageContent.Title>{title}</PageContent.Title>
+            </PageContent.Header>
+            <PageContent.Body>
+              <Typography.Root as="div" variant="body-s" tone="secondary" className={styles.block}>
+                {text}
+              </Typography.Root>
+            </PageContent.Body>
+          </PageContent.Root>
+        ))}
+      </div>
+    </div>
+  );
+}

package/src/components/pagination/COMPONENT.md

@@ -1,123 +1,123 @@
 # Pagination
 
-**Default `size`:** use **`m`** for the size axis unless the toolbar or table footer explicitly needs another tier.
+**Category:** 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 with its own footer → [DataTable](../data-table/COMPONENT.md) already includes pagination.
 
+## 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.
-
 ## 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`.
+
+| 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 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`. |
+
+## 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) | |
+
+### 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 | |
+
+Button height equals the control height: Pagination lines up with Button, Input and Select of the same `size`.
+
+### Page range
+| 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.
+
+## 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 |
+| disabled arrow | first / last page | native `disabled`, `text-disabled` |
+
+Root attributes: `data-size`, `data-compact` (`"true"` / `"false"` / `"auto"`). Controlled: `value` + `onValueChange`; uncontrolled: `defaultValue`.
+
+## 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.
+- `compact="auto"` needs a parent with a width — it is a size container.
+
+## 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 |
+
+## 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 |
 
-| 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` |
-
-## Related
+```tsx
+import { Pagination } from "prime-ui-kit";
+import * as React from "react";
 
-- [Button](../button/COMPONENT.md) — page and arrow cells are **`Button.Root`** + **`Button.Icon`**.
-- [DataTable](../data-table/COMPONENT.md) — typical host for a footer pager.
+export function OrdersPager() {
+  const [page, setPage] = React.useState(1);
+  return <Pagination.Root value={page} totalPages={12} onValueChange={setPage} />;
+}
+```
 
-## LLM note
+## 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: "…" }}`.
+- `compact="auto"` inside a shrink-wrapped flex item → give the parent a width.
 
-- **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`**.
+## Related
+- [DataTable](../data-table/COMPONENT.md)
+- [Select](../select/COMPONENT.md)
+- [Stepper](../stepper/COMPONENT.md)