prime-ui-kit 0.0.1

package/src/components/notification/examples/toast-queue.tsx

@@ -0,0 +1,5 @@
+import FeaturesExample from "./features";
+
+/** @deprecated Prefer [`features.tsx`](./features.tsx); kept for older doc links. */
+export default FeaturesExample;
+export { FeaturesExample as ToastQueueExample };

package/src/components/notification/examples/variants.tsx

@@ -0,0 +1,68 @@
+import {
+  NotificationCard,
+  NotificationProvider,
+  type NotificationRecord,
+  type NotificationType,
+} from "prime-ui-kit";
+
+const copy: Record<NotificationType, { title: string; description: string }> = {
+  success: { title: "Saved", description: "Changes were written to your profile." },
+  error: {
+    title: "Could not send",
+    description: "Check your connection and try again.",
+  },
+  warning: { title: "Subscription", description: "Your paid period ends in three days." },
+  info: {
+    title: "Night maintenance",
+    description: "The service will be down from 02:00 to 03:00.",
+  },
+};
+
+function VariantsDemo() {
+  const types = (["success", "error", "warning", "info"] as const).map((type) => {
+    const text = copy[type];
+    const item: NotificationRecord = {
+      id: `demo-variant-${type}`,
+      type,
+      title: text.title,
+      description: text.description,
+      position: "top-right",
+      size: "m",
+      duration: 60000,
+      persistent: true,
+      closable: false,
+      createdAt: Date.now(),
+    };
+    return item;
+  });
+
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: "var(--prime-sys-spacing-m)",
+        maxWidth: 440,
+      }}
+    >
+      {types.map((item) => (
+        <NotificationCard
+          key={item.id}
+          item={item}
+          paused={false}
+          onDismiss={() => {}}
+          stackDepth={0}
+          stackExpanded
+        />
+      ))}
+    </div>
+  );
+}
+
+export default function VariantsExample() {
+  return (
+    <NotificationProvider>
+      <VariantsDemo />
+    </NotificationProvider>
+  );
+}

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

@@ -0,0 +1,128 @@
+# PageContent
+
+## About
+
+Семантические примитивы **контентной колонки**: **`PageContent.Section`** (регион страницы **`<section>`** без собственных внешних полей), **`PageContent.Root`** (обёртка страницы с опциональным **`maxWidth`**, **без** дублирующих полей к краю колонки), **`PageContent.Title`** → **`<h1>`**, **`PageContent.Description`** с **`measure`**, **`PageContent.Body`**. Типографика — токены кита.
+
+- **С `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.
+
+### Краевые поля колонки
+
+Они **не** задаются **`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`)
+
+```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>
+  );
+}
+```
+
+### Playground
+
+Живые примеры и таблицы API: **`playground/sections/PageContentSection.tsx`**.
+
+## Rules
+
+- На вью — **один** `h1` через **`PageContent.Title`**.
+- **Не** вкладывайте **`PageContent.Root`** так, чтобы дублировать краевые поля, которые уже даёт **`AppShell.Main`**.
+- **`Description`**: по умолчанию узкая мера; **`measure="full"`**, когда колонка уже ограничена снаружи.
+
+## API
+
+### PageContent.Root
+
+| 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`). |
+
+### PageContent.Section
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| className | `string` | — | No | Класс на **`<section>`**. |
+| children | `React.ReactNode` | — | No | Обычно **`Header`** + **`Body`**. |
+| …rest | `React.HTMLAttributes<HTMLElement>` | — | No | В т.ч. `ref` (`forwardRef`). |
+
+### PageContent.Header
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| className | `string` | — | No | Класс на блоке шапки. |
+| children | `React.ReactNode` | — | No | **`Title`**, **`Description`**. |
+| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | Атрибуты `div`. |
+
+### PageContent.Title
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| className | `string` | — | No | Класс на **`<h1>`**. |
+| children | `React.ReactNode` | — | No | Заголовок страницы. |
+| …rest | `React.HTMLAttributes<HTMLHeadingElement>` | — | No | В т.ч. `ref` (`forwardRef`). |
+
+### PageContent.Description
+
+| 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`). |
+
+### PageContent.Body
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| className | `string` | — | No | Класс на обёртке контента под шапкой. |
+| children | `React.ReactNode` | — | No | Основное содержимое. |
+| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | Атрибуты `div`. |
+
+## Related
+
+- [Typography](../typography/COMPONENT.md) — роли текста на странице.
+- [EmptyPage](../empty-page/COMPONENT.md) — пустое состояние списка или области данных (**`h2`**, не дублирует **`PageContent.Title`**).
+- [AppShell](../../layout/app-shell/COMPONENT.md) — сетка и **`Main`**.

package/src/components/pagination/COMPONENT.md

@@ -0,0 +1,123 @@
+# Pagination
+
+**Default `size`:** use **`m`** for the size axis unless the toolbar or table footer explicitly needs another tier.
+
+## Canonical
+
+- **`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`**.
+
+## 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
+
+```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
+
+| 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
+
+- [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`**.

package/src/components/pagination/examples/canonical-composition.tsx

@@ -0,0 +1,20 @@
+import { Pagination } from "prime-ui-kit";
+
+/**
+ * Canonical wiring: required props on Pagination.Root only. Long ranges use siblingCount to widen the numeric window.
+ */
+export default function CanonicalCompositionExample() {
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: "var(--prime-sys-spacing-m)",
+        alignItems: "flex-start",
+      }}
+    >
+      <Pagination.Root page={2} totalPages={5} onPageChange={() => {}} />
+      <Pagination.Root page={10} totalPages={40} onPageChange={() => {}} siblingCount={2} />
+    </div>
+  );
+}

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

@@ -0,0 +1,32 @@
+import { Pagination } from "prime-ui-kit";
+import * as React from "react";
+
+/** Dense toolbar row: Pagination.Root with size="s". */
+export default function CompactExample() {
+  const [page, setPage] = React.useState(3);
+
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexWrap: "wrap",
+        alignItems: "center",
+        gap: "var(--prime-sys-spacing-x2)",
+        padding: "var(--prime-sys-spacing-x2) var(--prime-sys-spacing-x3)",
+        borderRadius: "var(--prime-sys-radius-m)",
+        background: "var(--prime-sys-color-surface-default)",
+        border: "1px solid var(--prime-sys-color-border-subtle)",
+      }}
+    >
+      <span
+        style={{
+          fontSize: "var(--prime-sys-size-control-s-supportText)",
+          color: "var(--prime-sys-color-content-secondary)",
+        }}
+      >
+        Compact
+      </span>
+      <Pagination.Root page={page} totalPages={12} onPageChange={setPage} size="s" />
+    </div>
+  );
+}

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

@@ -0,0 +1,57 @@
+import { Button, Pagination } from "prime-ui-kit";
+import * as React from "react";
+
+const TOTAL = 12;
+
+/** Page index lives in parent state; Pagination.Root and buttons share the same setter. Parity with `playground/snippets/pagination/controlled.tsx` (English copy). */
+export default function ControlledPageExample() {
+  const [page, setPage] = React.useState(4);
+
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: "var(--prime-sys-spacing-x3)",
+        alignItems: "flex-start",
+      }}
+    >
+      <p
+        style={{
+          margin: 0,
+          fontSize: "var(--prime-sys-size-control-s-supportText)",
+          color: "var(--prime-sys-color-content-secondary)",
+        }}
+      >
+        Open page {page} of {TOTAL} — updates via <code>page</code> and <code>onPageChange</code>.
+      </p>
+      <Pagination.Root page={page} totalPages={TOTAL} onPageChange={setPage} />
+      <div
+        style={{
+          display: "flex",
+          flexWrap: "wrap",
+          gap: "var(--prime-sys-spacing-x2)",
+        }}
+      >
+        <Button.Root
+          size="s"
+          variant="neutral"
+          mode="stroke"
+          onClick={() => setPage(1)}
+          disabled={page <= 1}
+        >
+          First
+        </Button.Root>
+        <Button.Root
+          size="s"
+          variant="neutral"
+          mode="stroke"
+          onClick={() => setPage(TOTAL)}
+          disabled={page >= TOTAL}
+        >
+          Last
+        </Button.Root>
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,107 @@
+import { Pagination } from "prime-ui-kit";
+import * as React from "react";
+
+/**
+ * `siblingCount` widens or narrows the numeric window; `totalPages < 1` renders nothing.
+ * Parity with `playground/snippets/pagination/features.tsx`.
+ */
+export default function PaginationFeaturesExample() {
+  const [pageNarrow, setPageNarrow] = React.useState(8);
+  const [pageWide, setPageWide] = React.useState(8);
+
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: "var(--prime-sys-spacing-x4)",
+      }}
+    >
+      <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)",
+          }}
+        >
+          <code>siblingCount=0</code>
+        </p>
+        <Pagination.Root
+          page={pageNarrow}
+          totalPages={20}
+          onPageChange={setPageNarrow}
+          siblingCount={0}
+        />
+      </div>
+      <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)",
+          }}
+        >
+          <code>siblingCount=2</code>
+        </p>
+        <Pagination.Root
+          page={pageWide}
+          totalPages={20}
+          onPageChange={setPageWide}
+          siblingCount={2}
+        />
+      </div>
+      <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)",
+          }}
+        >
+          <code>totalPages=0</code>
+        </p>
+        <div
+          style={{
+            display: "flex",
+            flexWrap: "wrap",
+            alignItems: "center",
+            gap: "var(--prime-sys-spacing-x2)",
+            minHeight: "var(--prime-sys-size-control-m-height)",
+          }}
+        >
+          <Pagination.Root page={1} totalPages={0} onPageChange={() => {}} />
+          <span
+            style={{
+              fontSize: "var(--prime-sys-size-control-s-supportText)",
+              color: "var(--prime-sys-color-content-muted)",
+            }}
+          >
+            empty output
+          </span>
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/components/pagination/examples/full-width-list.tsx

@@ -0,0 +1,37 @@
+import { Pagination } from "prime-ui-kit";
+import * as React from "react";
+
+/** Full-width bar: meta on the left, Pagination.Root on the right (parent layout). Parity with `playground/snippets/pagination/full-width.tsx` (English copy). */
+export default function FullWidthListExample() {
+  const [page, setPage] = React.useState(2);
+  const totalPages = 21;
+
+  return (
+    <div
+      style={{
+        display: "flex",
+        width: "100%",
+        maxWidth: "36rem",
+        alignItems: "center",
+        justifyContent: "space-between",
+        gap: "var(--prime-sys-spacing-x3)",
+        flexWrap: "wrap",
+        padding: "var(--prime-sys-spacing-x3) var(--prime-sys-spacing-x4)",
+        borderRadius: "var(--prime-sys-radius-m)",
+        background: "var(--prime-sys-color-surface-raised)",
+        border: "1px solid var(--prime-sys-color-border-subtle)",
+      }}
+    >
+      <span
+        style={{
+          fontSize: "var(--prime-sys-size-control-s-supportText)",
+          color: "var(--prime-sys-color-content-secondary)",
+          lineHeight: "var(--prime-sys-typography-body-lineHeight)",
+        }}
+      >
+        Showing 21–40 of 412
+      </span>
+      <Pagination.Root page={page} totalPages={totalPages} onPageChange={setPage} />
+    </div>
+  );
+}

package/src/components/pagination/examples/range-modes.tsx

@@ -0,0 +1,60 @@
+import { Pagination } from "prime-ui-kit";
+import * as React from "react";
+
+/**
+ * Up to seven pages: all indices shown; more pages: shortened row with ellipses (`totalPages` drives logic).
+ * Parity with `playground/snippets/pagination/range-modes.tsx`.
+ */
+export default function PaginationRangeModesExample() {
+  const [shortPage, setShortPage] = React.useState(3);
+  const [longPage, setLongPage] = React.useState(8);
+
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: "var(--prime-sys-spacing-x4)",
+      }}
+    >
+      <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)",
+          }}
+        >
+          Five pages — all numbers
+        </p>
+        <Pagination.Root page={shortPage} totalPages={5} onPageChange={setShortPage} />
+      </div>
+      <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)",
+          }}
+        >
+          Twenty pages — ellipsis
+        </p>
+        <Pagination.Root page={longPage} totalPages={20} onPageChange={setLongPage} />
+      </div>
+    </div>
+  );
+}