prime-ui-kit 0.10.0 → 0.11.1

package/dist/skill/reference/components/page-toolbar/examples/examples.module.css

@@ -0,0 +1,16 @@
+/* Layout of the PageToolbar scenarios: page columns of a capped width, so the toolbar shows its
+   two-row form. A cap (`max-width`), not a width: the column is as wide as the stage allows. */
+
+/* A phone-width page column (360px). */
+.phone {
+  width: 100%;
+  max-width: calc(var(--prime-space-24) * 3.75);
+  margin-inline: auto;
+}
+
+/* A tablet-width page column (600px). */
+.tablet {
+  width: 100%;
+  max-width: calc(var(--prime-space-24) * 6.25);
+  margin-inline: auto;
+}

package/dist/skill/reference/components/page-toolbar/examples/narrow.tsx

@@ -0,0 +1,103 @@
+/** A phone-width column: search, filter and the primary action on top, the active filters under them, then the sections and the period, every row 12 apart — `PageToolbar.Root`. */
+import {
+  Button,
+  Icon,
+  PageToolbar,
+  SegmentedControl,
+  Select,
+  SmartFilter,
+  type SmartFilterField,
+  type SmartFilterValue,
+} from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const SECTIONS = [
+  { value: "all", label: "Все", count: 128 },
+  { value: "active", label: "В работе", count: 12 },
+  { value: "done", label: "Доставлены", count: 96 },
+];
+
+const PERIODS = [
+  { value: "7d", label: "7 дней" },
+  { value: "30d", label: "30 дней" },
+];
+
+const FIELDS: SmartFilterField[] = [
+  {
+    key: "city",
+    label: "Город",
+    options: [
+      { value: "msk", label: "Москва" },
+      { value: "spb", label: "Санкт-Петербург" },
+    ],
+  },
+];
+
+export default function PageToolbarNarrowExample() {
+  const [section, setSection] = React.useState("all");
+  const [period, setPeriod] = React.useState("7d");
+  const [filter, setFilter] = React.useState<SmartFilterValue>({});
+  const [search, setSearch] = React.useState("");
+
+  return (
+    <div className={styles.phone}>
+      <SmartFilter.Root
+        fields={FIELDS}
+        value={filter}
+        onValueChange={setFilter}
+        search={search}
+        onSearchChange={setSearch}
+      >
+        <PageToolbar.Root aria-label="Заказы">
+          <PageToolbar.Tools>
+            <SmartFilter.Toolbar />
+          </PageToolbar.Tools>
+          <PageToolbar.Sections>
+            <SegmentedControl.Root
+              fullWidth
+              value={section}
+              onValueChange={setSection}
+              aria-label="Раздел"
+            >
+              {SECTIONS.map((item) => (
+                <SegmentedControl.Item key={item.value} value={item.value}>
+                  {item.label}
+                  <SegmentedControl.Count>{item.count}</SegmentedControl.Count>
+                </SegmentedControl.Item>
+              ))}
+            </SegmentedControl.Root>
+          </PageToolbar.Sections>
+          <PageToolbar.View>
+            <Select.Root value={period} onValueChange={setPeriod}>
+              <Select.Trigger aria-label="Период">
+                <Select.TriggerIcon>
+                  <Icon name="field.calendar" />
+                </Select.TriggerIcon>
+                <Select.Value />
+              </Select.Trigger>
+              <Select.Content>
+                {PERIODS.map((item) => (
+                  <Select.Item key={item.value} value={item.value}>
+                    {item.label}
+                  </Select.Item>
+                ))}
+              </Select.Content>
+            </Select.Root>
+          </PageToolbar.View>
+          <PageToolbar.Actions>
+            <Button.Root aria-label="Новый заказ">
+              <Button.Icon>
+                <Icon name="action.add" />
+              </Button.Icon>
+            </Button.Root>
+          </PageToolbar.Actions>
+          <PageToolbar.Chips>
+            <SmartFilter.Chips />
+          </PageToolbar.Chips>
+        </PageToolbar.Root>
+      </SmartFilter.Root>
+    </div>
+  );
+}

package/dist/skill/reference/components/page-toolbar/examples/overview.tsx

@@ -0,0 +1,113 @@
+/** The panel of an orders page: search and filter, sections with counts, the period and the primary action in one row; active filters right under the search — `PageToolbar.Tools`, `PageToolbar.Sections`, `PageToolbar.View`, `PageToolbar.Actions`, `PageToolbar.Chips`. */
+import {
+  Button,
+  Icon,
+  PageToolbar,
+  SegmentedControl,
+  Select,
+  SmartFilter,
+  type SmartFilterField,
+  type SmartFilterValue,
+} from "prime-ui-kit";
+import * as React from "react";
+
+const SECTIONS = [
+  { value: "all", label: "Все", count: 128 },
+  { value: "active", label: "В работе", count: 12 },
+  { value: "done", label: "Доставлены", count: 96 },
+  { value: "cancelled", label: "Отменены", count: 20 },
+];
+
+const PERIODS = [
+  { value: "7d", label: "7 дней" },
+  { value: "30d", label: "30 дней" },
+  { value: "quarter", label: "Квартал" },
+];
+
+const FIELDS: SmartFilterField[] = [
+  {
+    key: "city",
+    label: "Город",
+    options: [
+      { value: "msk", label: "Москва" },
+      { value: "spb", label: "Санкт-Петербург" },
+      { value: "kzn", label: "Казань" },
+    ],
+  },
+  {
+    key: "payment",
+    label: "Оплата",
+    options: [
+      { value: "card", label: "Картой" },
+      { value: "invoice", label: "По счёту" },
+    ],
+  },
+];
+
+export default function PageToolbarOverviewExample() {
+  const [section, setSection] = React.useState("all");
+  const [period, setPeriod] = React.useState("30d");
+  const [filter, setFilter] = React.useState<SmartFilterValue>({
+    city: { include: ["msk"], exclude: [] },
+  });
+  const [search, setSearch] = React.useState("");
+
+  return (
+    <SmartFilter.Root
+      fields={FIELDS}
+      value={filter}
+      onValueChange={setFilter}
+      search={search}
+      onSearchChange={setSearch}
+    >
+      <PageToolbar.Root aria-label="Заказы">
+        <PageToolbar.Tools>
+          <SmartFilter.Toolbar />
+        </PageToolbar.Tools>
+        <PageToolbar.Sections>
+          <SegmentedControl.Root
+            fullWidth
+            value={section}
+            onValueChange={setSection}
+            aria-label="Раздел"
+          >
+            {SECTIONS.map((item) => (
+              <SegmentedControl.Item key={item.value} value={item.value}>
+                {item.label}
+                <SegmentedControl.Count>{item.count}</SegmentedControl.Count>
+              </SegmentedControl.Item>
+            ))}
+          </SegmentedControl.Root>
+        </PageToolbar.Sections>
+        <PageToolbar.View>
+          <Select.Root value={period} onValueChange={setPeriod}>
+            <Select.Trigger aria-label="Период">
+              <Select.TriggerIcon>
+                <Icon name="field.calendar" />
+              </Select.TriggerIcon>
+              <Select.Value />
+            </Select.Trigger>
+            <Select.Content>
+              {PERIODS.map((item) => (
+                <Select.Item key={item.value} value={item.value}>
+                  {item.label}
+                </Select.Item>
+              ))}
+            </Select.Content>
+          </Select.Root>
+        </PageToolbar.View>
+        <PageToolbar.Actions>
+          <Button.Root>
+            <Button.Icon>
+              <Icon name="action.add" />
+            </Button.Icon>
+            Новый заказ
+          </Button.Root>
+        </PageToolbar.Actions>
+        <PageToolbar.Chips>
+          <SmartFilter.Chips />
+        </PageToolbar.Chips>
+      </PageToolbar.Root>
+    </SmartFilter.Root>
+  );
+}

package/dist/skill/reference/components/page-toolbar/examples/save-changes.tsx

@@ -0,0 +1,40 @@
+/** A settings page: sections of the form on the left, the save action with the number of changes at the end of the top row — never a sticky bar at the bottom of a phone screen — `PageToolbar.Actions`. */
+import { Button, PageToolbar, SegmentedControl } from "prime-ui-kit";
+import * as React from "react";
+
+const SECTIONS = [
+  { value: "profile", label: "Профиль" },
+  { value: "billing", label: "Оплата" },
+  { value: "team", label: "Команда" },
+];
+
+const CHANGES = 3;
+
+export default function PageToolbarSaveChangesExample() {
+  const [section, setSection] = React.useState("profile");
+
+  return (
+    <PageToolbar.Root aria-label="Настройки">
+      <PageToolbar.Sections>
+        <SegmentedControl.Root
+          fullWidth
+          value={section}
+          onValueChange={setSection}
+          aria-label="Раздел настроек"
+        >
+          {SECTIONS.map((item) => (
+            <SegmentedControl.Item key={item.value} value={item.value}>
+              {item.label}
+            </SegmentedControl.Item>
+          ))}
+        </SegmentedControl.Root>
+      </PageToolbar.Sections>
+      <PageToolbar.Actions>
+        <Button.Root variant="ghost" tone="neutral">
+          Отменить
+        </Button.Root>
+        <Button.Root>Сохранить {CHANGES} изменения</Button.Root>
+      </PageToolbar.Actions>
+    </PageToolbar.Root>
+  );
+}

package/dist/skill/reference/components/page-toolbar/examples/without-search.tsx

@@ -0,0 +1,60 @@
+/** A dashboard panel without search on a tablet-width column: the sections fill the top row, the period selector alone in the bottom row stretches to the full width — `PageToolbar.Sections`, `PageToolbar.View`. */
+import { Icon, PageToolbar, SegmentedControl, Select } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const SECTIONS = [
+  { value: "overview", label: "Обзор" },
+  { value: "activity", label: "Активность" },
+  { value: "resources", label: "Ресурсы" },
+];
+
+const PERIODS = [
+  { value: "1h", label: "1 час" },
+  { value: "24h", label: "24 часа" },
+  { value: "7d", label: "7 дней" },
+];
+
+export default function PageToolbarWithoutSearchExample() {
+  const [section, setSection] = React.useState("overview");
+  const [period, setPeriod] = React.useState("24h");
+
+  return (
+    <div className={styles.tablet}>
+      <PageToolbar.Root aria-label="Панель мониторинга">
+        <PageToolbar.Sections>
+          <SegmentedControl.Root
+            fullWidth
+            value={section}
+            onValueChange={setSection}
+            aria-label="Раздел"
+          >
+            {SECTIONS.map((item) => (
+              <SegmentedControl.Item key={item.value} value={item.value}>
+                {item.label}
+              </SegmentedControl.Item>
+            ))}
+          </SegmentedControl.Root>
+        </PageToolbar.Sections>
+        <PageToolbar.View>
+          <Select.Root value={period} onValueChange={setPeriod}>
+            <Select.Trigger aria-label="Период">
+              <Select.TriggerIcon>
+                <Icon name="field.calendar" />
+              </Select.TriggerIcon>
+              <Select.Value />
+            </Select.Trigger>
+            <Select.Content>
+              {PERIODS.map((item) => (
+                <Select.Item key={item.value} value={item.value}>
+                  {item.label}
+                </Select.Item>
+              ))}
+            </Select.Content>
+          </Select.Root>
+        </PageToolbar.View>
+      </PageToolbar.Root>
+    </div>
+  );
+}

package/dist/skill/reference/components/pagination/COMPONENT.md

@@ -0,0 +1,132 @@
+# Pagination
+
+**Category:** navigation
+**Kind:** navigation
+
+> Page-by-page navigation: arrows, page numbers with ellipsis and a compact «3 / 12» view.
+
+## When to use
+- Lists and tables split into pages, usually in their footer.
+- Narrow places (cards, mobile footers) — `compact` or `compact="auto"`.
+
+## 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";
+```
+
+## 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
+
+<!-- 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
+- **Built from:** [Button](../button/COMPONENT.md), Icon (`nav.chevronLeft`, `nav.chevronRight`)
+- **See also:** [DataTable](../data-table/COMPONENT.md), [Select](../select/COMPONENT.md), [Stepper](../stepper/COMPONENT.md)

package/dist/skill/reference/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/dist/skill/reference/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/dist/skill/reference/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/dist/skill/reference/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/dist/skill/reference/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/dist/skill/reference/components/pagination/examples/sizes.tsx

@@ -0,0 +1,19 @@
+/** 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";
+
+const SIZES = ["xs", "s", "m", "l", "xl"] as const;
+
+export default function PaginationSizesExample() {
+  return (
+    <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>
+  );
+}