prime-ui-kit 0.9.3 → 0.11.0

package/dist/skill/reference/components/page-content/COMPONENT.md

@@ -0,0 +1,215 @@
+# PageContent
+
+**Category:** page
+**Kind:** layout
+
+> Page structure inside the main column: title, description, page actions and content sections; a page as high as the panel and the list + detail layout.
+
+## 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"`).
+- A page whose body takes the rest of the panel's height — a log table, a board, a chat (`fill`).
+- Mail, a messenger, a ticket queue: a list and the chosen record side by side, one at a time on a narrow panel (`PageContent.Split`).
+
+## 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).
+- Details that open over the list and close again (a record from a table) → use [Drawer](../drawer/COMPONENT.md); `Split` is for a list people work through record by record.
+
+## Import
+```tsx
+import { PageContent } from "prime-ui-kit";
+```
+
+## Anatomy
+```
+PageContent.Root | PageContent.Section     column; Root adds maxWidth and fill, 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
+   └─ PageContent.Split                    list + detail; a container (prime-split)
+      ├─ PageContent.List                  list pane: 16–20rem column, or the whole split while closed
+      └─ PageContent.Detail                detail pane: the rest, or the whole split while open
+         └─ PageContent.BackButton         back to the list, only while one pane shows
+```
+
+## API
+
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+### PageContent.Root
+`ref` → `HTMLDivElement`. The page column inside `main`: header → body 32 apart, centred under its cap.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `maxWidth` | `"full" \| "readable" \| "wide"` | `"full"` | Cap of the column, centred: `full` — the whole main; `readable` — the reading measure `--prime-layout-reading-max-width` (42rem); `wide` — the content width `--prime-layout-content-max-width` (75rem). |
+| `fill` | `boolean` | `false` | The page takes the height of main (`AppShell.Root fillViewport`) and the body takes what the header leaves: for a full-height table, board, chat or `PageContent.Split`. |
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children` (Header, Body), `className` and the other div attributes. |
+
+### PageContent.Section
+`ref` → `HTMLElement`. The same column as a `<section>`, without a cap; name it with `aria-labelledby` → the Title `id`.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLElement>` | — | `children`, `aria-labelledby`, `className` and the other section attributes. |
+
+### PageContent.Header
+`ref` → `HTMLDivElement`. Heading column and page actions in one wrapping row; `PageContent.Actions` children move to the end.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children` (Title, Description, Actions), `className` and the other div attributes. |
+
+### PageContent.Title
+`ref` → `HTMLHeadingElement`. The page `<h1>` in heading-m.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLHeadingElement>` | — | `children`, `id`, `className` and the other heading attributes. |
+
+### PageContent.Description
+`ref` → `HTMLParagraphElement`. Intro `<p>` in secondary body-m.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `measure` | `"readable" \| "full"` | `"readable"` | `readable` — no wider than the reading measure `--prime-layout-reading-max-width` (42rem); `full` — the full width of the parent. |
+| `…rest` | `HTMLAttributes<HTMLParagraphElement>` | — | `children`, `className` and the other paragraph attributes. |
+
+### PageContent.Actions
+`ref` → `HTMLDivElement`. Page-level buttons next to the title; they wrap under the heading on narrow columns.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children` (Buttons), `className` and the other div attributes. |
+
+### PageContent.Body
+`ref` → `HTMLDivElement`. The page content; blocks 40 apart.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children`, `className` and the other div attributes. |
+
+### PageContent.Split
+`ref` → `HTMLDivElement`. List + detail (mail, a messenger, a ticket queue): side by side from 48rem of its own width, one pane at a time below it, focus following the pane that comes into view.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `open` | `boolean` | — | The detail is open (a record is chosen), controlled. On a narrow split it takes the place of the list; on a wide one both panes stay. |
+| `defaultOpen` | `boolean` | `false` | Initial open state, uncontrolled. |
+| `onOpenChange` | `(open: boolean) => void` | — | `PageContent.BackButton` closes the detail (`false`); clear the chosen record there. |
+| `labels` | `Partial<PageContentLabels>` | — | Built-in strings, see Labels. |
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children` (`PageContent.List`, `PageContent.Detail`), `className` and the other div attributes. |
+
+### PageContent.List
+`ref` → `HTMLDivElement`. The list pane: a column whose last child takes the free height (a Card with its own ScrollContainer). Focusable from code (`tabindex=-1`, no ring): going back lands on the control that had focus, else here.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children`, `aria-label`, `className` and the other div attributes. |
+
+### PageContent.Detail
+`ref` → `HTMLDivElement`. The detail pane, built like the list pane; focus lands here when it opens on a narrow split. Show a hint («Выберите диалог») while nothing is chosen: a wide split always shows this pane.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children`, `aria-label`, `className` and the other div attributes. |
+
+### PageContent.BackButton
+`ref` → `HTMLButtonElement`. Back from the detail to the list: a soft neutral icon Button (`nav.chevronLeft`) named by `labels.back`, shown only while the split shows one pane. Put it first in the detail's header; `event.preventDefault()` in `onClick` keeps the detail open.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `Omit<ButtonHTMLAttributes<HTMLButtonElement>, "type" \| "children">` | — | `onClick`, `aria-label` (replaces `labels.back`), `className` and the other button attributes. |
+
+## 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` (42rem), centred | Terms, articles, help pages | |
+| `wide` | Column capped at `--prime-layout-content-max-width` (75rem), 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 | |
+
+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.
+
+### Flags
+| Flag | Looks like when on | Use when | Default |
+|---|---|---|---|
+| `fill` (Root) | the page is as high as main; the body takes what the header leaves; main keeps gutter-high air under it | a full-height table, board, chat or `PageContent.Split` in an `AppShell.Root fillViewport` | `false` |
+
+### Split layout
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| wide (from 48rem of the split's width) | list in a 16–20rem column, detail beside it, 24 apart; no back button | desktops, tablets in landscape | — |
+| narrow (below 48rem) | one pane: the list, or the open detail with `PageContent.BackButton` | phones, a narrow panel next to an open Sidebar | — |
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| capped column | `maxWidth` | `data-max-width="readable" \| "wide"` on Root (absent for `full`) |
+| filling | `fill` | `data-fill="true"` on Root; `AppShell.Main` drops its long bottom air for it |
+| full-width intro | `measure="full"` | `data-measure="full"` on Description |
+| with actions | `PageContent.Actions` child | `data-has-actions="true"` on Header |
+| detail open | `open` / `defaultOpen` on Split | `data-open="true"` on Split; narrow: the list is `display: none`, else the detail is |
+| pane swap | `open` changes on a narrow split | the pane that comes into view enters once (`enterMotion.enterBase`: base, opacity + a 4 px rise); focus moves into the detail, or back to the list control; a wide split moves nothing |
+
+## 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`; heading → Actions `--prime-space-6` (24) side by side, `--prime-space-4` (16) once they wrap below.
+- Header is a wrapping row: actions stay to the right of the title while the heading keeps half a reading measure, otherwise they wrap below it — no breakpoint needed, works from 320px.
+- Title and Description wrap long words (`overflow-wrap: anywhere`).
+- `fill` needs a main with a height: `AppShell.Root fillViewport` (main scrolls inside the panel). The body passes its free height on to a filling child — DataTable `scrollHeight="fill"`, Crossfade `fill`, `PageContent.Split`.
+- Split takes the free height of a filling page and lays itself out from its own width (container `prime-split`), never from the window: a split beside an open Sidebar may be narrow on a wide screen. Each pane is a column whose last child takes the free height — put a Card with its own `ScrollContainer` there, so the list and the thread scroll separately.
+- The detail pane is on screen all the time on a wide split: while nothing is chosen it shows a short hint («Выберите диалог»), never an empty card.
+
+## Accessibility
+
+### Keyboard
+| Key | Action |
+|---|---|
+| `Enter` · `Space` | On `PageContent.BackButton`: back from the detail to the list; focus returns to the list control that opened it. |
+
+### ARIA
+- Title is an `<h1>`; use one per page.
+- Give `PageContent.Section` an `aria-labelledby` that points at the Title `id` to name the region.
+- Name `PageContent.List` and `PageContent.Detail` with `aria-label`. On a narrow split opening the detail moves focus into it and going back returns focus to the list control; the hidden pane is `display: none`, out of Tab and the accessibility tree. The panes take focus from code only (`tabindex="-1"`, no ring).
+- `PageContent.BackButton` is named by `labels.back` and is shown only while the split shows one pane.
+
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+| Key | Default | Used for |
+|---|---|---|
+| `back` | `"Назад к списку"` | Name of `PageContent.BackButton` (on `PageContent.Split`). |
+
+## Examples
+| Example | Shows |
+|---|---|
+| [overview.tsx](examples/overview.tsx) | A page in the main column: title, description and page actions, then the body blocks — `PageContent.Actions`. |
+| [variants.tsx](examples/variants.tsx) | The same page column at three caps: the whole main, a wide dashboard column, a reading column — `maxWidth`. |
+| [list-detail.tsx](examples/list-detail.tsx) | A support inbox as list + detail on a full-height page: side by side on a wide panel, one pane at a time with a back button on a narrow one — `PageContent.Split`, `PageContent.BackButton`, `fill`. |
+| [narrow.tsx](examples/narrow.tsx) | In a phone-width column the page actions wrap under the heading instead of squeezing it. |
+
+## 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.
+- Computing a height from `100vh` minus the header for a full-height table or chat → `PageContent.Root fill` and a filling child.
+- A list + detail built with window media queries → `PageContent.Split` follows its own width.
+- Unmounting the detail content the moment the narrow split goes back → keep the last record until another is chosen (the pane leaves with it on screen).
+
+## Related
+- **Built from:** [Button](../button/COMPONENT.md) (`PageContent.BackButton`), Icon (`nav.chevronLeft`)
+- **See also:** [AppShell](../../layout/app-shell/COMPONENT.md), [Sidebar](../../layout/sidebar/COMPONENT.md), [Card](../card/COMPONENT.md), [EmptyPage](../empty-page/COMPONENT.md), [ScrollContainer](../scroll-container/COMPONENT.md), [Drawer](../drawer/COMPONENT.md)

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

@@ -0,0 +1,76 @@
+/* Layout of the PageContent scenarios: 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-layer-current);
+  container-type: inline-size;
+}
+
+/* Several page columns stacked with the section rhythm. */
+.stack {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-space-10);
+}
+
+/* list-detail: main of a viewport-high shell — a column of a fixed height the page fills. */
+.fillMain {
+  box-sizing: border-box;
+  display: flex;
+  flex-direction: column;
+  width: 100%;
+  height: calc(var(--prime-space-24) * 5);
+  padding: var(--prime-layout-gutter-m);
+  border-radius: var(--prime-card-radius);
+  background: var(--prime-color-layer-current);
+}
+
+/* A pane's card: an optional header row, then the scrolling region takes the rest. */
+.paneCard {
+  display: flex;
+  flex-direction: column;
+}
+
+.threadHeader {
+  display: flex;
+  align-items: center;
+  gap: var(--prime-space-2);
+  padding: var(--prime-space-3) var(--prime-space-4);
+}
+
+.pane {
+  flex: 1 1 auto;
+  min-height: 0;
+}
+
+.dialogs,
+.messages {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-space-1);
+  margin: 0;
+  padding: var(--prime-space-2);
+  list-style: none;
+}
+
+.messages {
+  gap: var(--prime-space-3);
+  padding: var(--prime-space-2) var(--prime-space-4) var(--prime-space-4);
+}
+
+/* A dialog row: the name at the start, the unread count at the end. */
+.dialog {
+  justify-content: space-between;
+}
+
+.hint {
+  padding: var(--prime-space-2) var(--prime-space-4);
+}
+
+/* A phone-width main column (360px). */
+.narrow {
+  width: min(100%, calc(var(--prime-space-24) * 3.75));
+}

package/dist/skill/reference/components/page-content/examples/list-detail.tsx

@@ -0,0 +1,114 @@
+/** A support inbox as list + detail on a full-height page: side by side on a wide panel, one pane at a time with a back button on a narrow one — `PageContent.Split`, `PageContent.BackButton`, `fill`. */
+import { Badge, Button, Card, PageContent, ScrollContainer, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+type Dialog = { id: string; client: string; unread: number; messages: string[] };
+
+const DIALOGS: Dialog[] = [
+  {
+    id: "granit",
+    client: "ООО «Гранит»",
+    unread: 2,
+    messages: [
+      "Счёт № 4821 пришёл без НДС.",
+      "Проверю реквизиты и вернусь.",
+      "Нужно провести до пятницы.",
+      "Исправили ставку, новый счёт № 4830 на почте.",
+    ],
+  },
+  {
+    id: "leto",
+    client: "ООО «Лето»",
+    unread: 0,
+    messages: ["Можно перенести доставку на среду?", "Да, перенесли на 15 октября."],
+  },
+  {
+    id: "kozlov",
+    client: "ИП Козлов",
+    unread: 1,
+    messages: ["Подключите, пожалуйста, ЭДО.", "Пришлите идентификатор в Диадоке."],
+  },
+];
+
+export default function PageContentListDetailExample() {
+  const [dialogId, setDialogId] = React.useState<string | null>(null);
+  // The last opened dialog stays in the detail while the narrow split goes back to the list.
+  const [shown, setShown] = React.useState<Dialog | null>(null);
+
+  const open = (dialog: Dialog) => {
+    setDialogId(dialog.id);
+    setShown(dialog);
+  };
+
+  return (
+    <div className={styles.fillMain}>
+      <PageContent.Root fill>
+        <PageContent.Header>
+          <PageContent.Title>Обращения</PageContent.Title>
+        </PageContent.Header>
+        <PageContent.Body>
+          <PageContent.Split
+            open={dialogId !== null}
+            onOpenChange={(next) => {
+              if (!next) setDialogId(null);
+            }}
+          >
+            <PageContent.List aria-label="Диалоги">
+              <Card.Root className={styles.paneCard}>
+                <ScrollContainer className={styles.pane}>
+                  <ul className={styles.dialogs}>
+                    {DIALOGS.map((dialog) => (
+                      <li key={dialog.id}>
+                        <Button.Root
+                          variant={dialog.id === dialogId ? "soft" : "ghost"}
+                          tone="neutral"
+                          fullWidth
+                          aria-current={dialog.id === dialogId ? "true" : undefined}
+                          className={styles.dialog}
+                          onClick={() => open(dialog)}
+                        >
+                          {dialog.client}
+                          {dialog.unread > 0 ? (
+                            <Badge.Root color="blue">{dialog.unread}</Badge.Root>
+                          ) : null}
+                        </Button.Root>
+                      </li>
+                    ))}
+                  </ul>
+                </ScrollContainer>
+              </Card.Root>
+            </PageContent.List>
+
+            <PageContent.Detail aria-label="Переписка">
+              <Card.Root className={styles.paneCard}>
+                <div className={styles.threadHeader}>
+                  <PageContent.BackButton />
+                  <Typography as="h2" variant="title-s">
+                    {shown?.client ?? "Выберите диалог"}
+                  </Typography>
+                </div>
+                <ScrollContainer anchor="end" className={styles.pane}>
+                  {shown ? (
+                    <ul className={styles.messages}>
+                      {shown.messages.map((text) => (
+                        <li key={text}>
+                          <Typography variant="body-m">{text}</Typography>
+                        </li>
+                      ))}
+                    </ul>
+                  ) : (
+                    <Typography variant="body-m" tone="muted" className={styles.hint}>
+                      Переписка откроется здесь.
+                    </Typography>
+                  )}
+                </ScrollContainer>
+              </Card.Root>
+            </PageContent.Detail>
+          </PageContent.Split>
+        </PageContent.Body>
+      </PageContent.Root>
+    </div>
+  );
+}

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

@@ -0,0 +1,25 @@
+/** In a phone-width column the page actions wrap under the heading instead of squeezing it. */
+import { Button, PageContent } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function PageContentNarrowExample() {
+  return (
+    <div className={styles.narrow}>
+      <div className={styles.main}>
+        <PageContent.Root>
+          <PageContent.Header>
+            <PageContent.Title>Счета</PageContent.Title>
+            <PageContent.Description>Выставленные и оплаченные за квартал.</PageContent.Description>
+            <PageContent.Actions>
+              <Button.Root variant="soft" tone="neutral">
+                Экспорт
+              </Button.Root>
+              <Button.Root>Новый счёт</Button.Root>
+            </PageContent.Actions>
+          </PageContent.Header>
+        </PageContent.Root>
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,41 @@
+/** A page in the main column: title, description and page actions, then the body blocks — `PageContent.Actions`. */
+import { Button, Card, PageContent, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function PageContentOverviewExample() {
+  return (
+    <div className={styles.main}>
+      <PageContent.Section aria-labelledby="settings-heading">
+        <PageContent.Header>
+          <PageContent.Title id="settings-heading">Настройки</PageContent.Title>
+          <PageContent.Description>
+            Профиль рабочего пространства и уведомления.
+          </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.Body>
+              <Typography variant="body-m" tone="secondary">
+                Компания «Прайм Софт», часовой пояс Москва (UTC+3), валюта — рубль.
+              </Typography>
+            </Card.Body>
+          </Card.Root>
+          <Card.Root variant="panel">
+            <Card.Body>
+              <Typography variant="body-m" tone="secondary">
+                Письма о новых заказах и сводка по понедельникам включены.
+              </Typography>
+            </Card.Body>
+          </Card.Root>
+        </PageContent.Body>
+      </PageContent.Section>
+    </div>
+  );
+}

package/dist/skill/reference/components/page-content/examples/variants.tsx

@@ -0,0 +1,39 @@
+/** The same page column at three caps: the whole main, a wide dashboard column, a reading column — `maxWidth`. */
+import { Card, PageContent, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const WIDTHS = [
+  { value: "full", title: "Сделки", text: "Колонка занимает всю ширину main." },
+  { value: "wide", title: "Дашборд продаж", text: "Не шире ширины контента, по центру." },
+  {
+    value: "readable",
+    title: "Условия использования",
+    text: "Не шире колонки для чтения, по центру.",
+  },
+] as const;
+
+export default function PageContentVariantsExample() {
+  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>
+              <Card.Root>
+                <Card.Body>
+                  <Typography variant="body-s" tone="secondary">
+                    {value} — {text}
+                  </Typography>
+                </Card.Body>
+              </Card.Root>
+            </PageContent.Body>
+          </PageContent.Root>
+        ))}
+      </div>
+    </div>
+  );
+}

package/dist/skill/reference/components/page-toolbar/COMPONENT.md

@@ -0,0 +1,141 @@
+# PageToolbar
+
+**Category:** page
+**Kind:** layout
+
+> The panel at the top of a page — sections, filter and search, view options and the primary action — laid out from its own width: one row when wide, stacked rows when narrow, search and filter always first with the active filters under them.
+
+## When to use
+- A list, registry or dashboard page whose top holds several of: sections with counts, a filter and search, a period or view switch, the primary action.
+- A settings page with sections and a «Сохранить N изменений» action that must stay reachable on a phone.
+- Any page that has to work from 320px with the same controls as on desktop — nothing is hidden, the slots only move.
+
+## When not to use
+- A page with a title, a description and one or two buttons → [PageContent](../page-content/COMPONENT.md) `Header` with `Actions`.
+- Tools that belong to one table → the DataTable `toolbar` slot.
+- Switching panels inside a card or a section → [Tabs](../tabs/COMPONENT.md).
+- App-level navigation → [Sidebar](../../layout/sidebar/COMPONENT.md).
+
+## Import
+```tsx
+import { PageToolbar } from "prime-ui-kit";
+```
+
+## Anatomy
+```
+PageToolbar.Root                 container: its own width picks the layout
+├─ PageToolbar.Tools             search + filter button: SmartFilter.Toolbar — always first
+├─ PageToolbar.Sections          sections of the page: a fullWidth SegmentedControl with counts
+├─ PageToolbar.View              period, table / cards, columns
+├─ PageToolbar.Actions           the primary action (and its secondary twin, e.g. «Отменить»)
+└─ PageToolbar.Chips             active filters: SmartFilter.Chips, a row right under the search
+```
+
+## API
+
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+### PageToolbar.Root
+`ref` → `HTMLDivElement`. The page panel: one row from 56rem of its own width, stacked rows below. Any slot may be left out; JSX order is the Tab order — write Tools, Sections, View, Actions, Chips.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children`, `className` and the other div attributes. |
+
+### PageToolbar.Sections
+`ref` → `HTMLDivElement`. Sections of the page — a `fullWidth` SegmentedControl with counts; scrolls inside when it does not fit.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children`, `className` and the other div attributes. |
+
+### PageToolbar.Tools
+`ref` → `HTMLDivElement`. Search and filter button (`SmartFilter.Toolbar`): always the first slot and the stretchy one, the Chips right under it.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children`, `className` and the other div attributes. |
+
+### PageToolbar.View
+`ref` → `HTMLDivElement`. How the data is shown: period, table / cards, columns. Sized by content when wide; its own full row when narrow, its controls sharing it equally.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children`, `className` and the other div attributes. |
+
+### PageToolbar.Actions
+`ref` → `HTMLDivElement`. The primary action of the page: at the end of the top row at every width, never wraps down.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children`, `className` and the other div attributes. |
+
+### PageToolbar.Chips
+`ref` → `HTMLDivElement`. Active filters (`SmartFilter.Chips`) in their own row right under the search and filter; the row takes no space while it is empty.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children`, `className` and the other div attributes. |
+
+## Variants
+PageToolbar has no variants: the layout follows the toolbar's width.
+
+### Layout by width
+| Toolbar width | Looks like | Default |
+|---|---|---|
+| `≥ 56rem` | one row that never wraps: Tools (stretch, at least 18rem — a 9rem search and the filter button on one line) · Sections (content width) · View (content width) · Actions; Chips under it; short of room the Tools give way first, then the Sections shrink and scroll inside | |
+| `< 56rem` | rows: Tools (stretch) + Actions; Chips; Sections (full row); View (full row) | yes (mobile first) |
+| any | Chips right under the search and filter, only while there are chips | |
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| wide | container ≥ 56rem | one flex row, no wrapping; Chips rendered under the bar |
+| narrow | container < 56rem | a grid of real rows only (`order` + grid columns): a missing slot makes no row, every row is 12 from the next |
+| no Tools | Sections without Tools | the Sections take the Tools' place: first and stretchy, beside the action |
+| alone in a row | Tools or Sections without Actions; View when narrow | that slot stretches to the full row; the View's controls share it equally |
+| no chips | `PageToolbar.Chips` empty (`SmartFilter.Chips` renders nothing) | the chips row takes no space |
+
+## Layout & spacing
+- 8 inside a slot. No padding or fill of its own: it sits at the top of `PageContent.Body` (or replaces `PageContent.Header` on dense pages that keep their `h1` in the shell).
+- The order is fixed: search and filter first, then the sections, the view and the primary action; the active filters always sit right under the search and filter, never under the sections. The primary action is at the end of the top row at every width and never wraps down.
+- Every gap is one step: 12 between slots and between every pair of rows, at any width — no row is ever further from the next.
+- Sections take a `fullWidth` SegmentedControl: the toolbar decides when it stretches (content width when wide, the full row when narrow), its items tend to equal width and it scrolls inside itself when they do not fit.
+- All controls share one tier, so they share one height and wrapped rows stay level: leave `size` off the controls (default `m`); for a denser page wrap the toolbar in `<ControlSizeProvider value="s">`.
+- On a phone the primary action may drop its text and keep the icon with `aria-label`; never remove it.
+- The toolbar breaks by its own width, so it behaves the same with the sidebar open or closed.
+
+## Accessibility
+
+### Keyboard
+No keyboard interaction.
+
+### ARIA
+- A plain `<div>`: name it with `aria-label` when a page has more than one panel.
+- Slots move only visually (`order`); the Tab order is the JSX order. Write the slots in the reading order of the wide layout — Tools, Sections, View, Actions, Chips. In the narrow layout the action is shown beside the tools but reached after the view.
+- An icon-only primary action on a narrow page carries `aria-label`.
+
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+No `labels`.
+
+## Examples
+| Example | Shows |
+|---|---|
+| [overview.tsx](examples/overview.tsx) | 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`. |
+| [without-search.tsx](examples/without-search.tsx) | 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`. |
+| [save-changes.tsx](examples/save-changes.tsx) | 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`. |
+| [narrow.tsx](examples/narrow.tsx) | 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`. |
+
+## Mistakes
+- A hand-built flex row of tabs, search and buttons with `flex-wrap` → rows wrap «as they come», the action drifts down; use `PageToolbar`.
+- `size="s"` on one control inside → a step in the row; one tier for all, through `ControlSizeProvider` around the toolbar.
+- A SegmentedControl without `fullWidth` in Sections → it never stretches on narrow widths.
+- Stat cards above a table for the section totals → counts inside the sections (`SegmentedControl.Count`).
+- Hiding the search or the action on phones → they move, they never disappear.
+- A sticky «Сохранить» bar at the bottom of a phone → the save action with its count in `PageToolbar.Actions`.
+
+## Related
+- **Built from:** —
+- **See also:** [SegmentedControl](../segmented-control/COMPONENT.md), [SmartFilter](../smart-filter/COMPONENT.md), [PageContent](../page-content/COMPONENT.md), [DataTable](../data-table/COMPONENT.md), [Select](../select/COMPONENT.md)