prime-ui-kit 0.9.0 → 0.9.2

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

@@ -0,0 +1,45 @@
+/** Toasts of one position and tone stack; hover expands the stack and pauses the timers — `max`, `items`, `dismissAll`. */
+import { Button, NotificationProvider, Typography, useNotifications } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+function StackControls() {
+  const { notify, dismissAll, items } = useNotifications();
+  return (
+    <div className={styles.row}>
+      <Button.Root
+        variant="outline"
+        tone="neutral"
+        onClick={() =>
+          notify({
+            tone: "success",
+            title: "Заказ оформлен",
+            description: `№ ${48_213 + items.length}, доставка завтра.`,
+          })
+        }
+      >
+        Оформить заказ
+      </Button.Root>
+      <Button.Root
+        variant="ghost"
+        tone="neutral"
+        disabled={items.length === 0}
+        onClick={dismissAll}
+      >
+        Закрыть все
+      </Button.Root>
+      <Typography as="span" variant="body-s" tone="secondary">
+        Активных: {items.length}
+      </Typography>
+    </div>
+  );
+}
+
+export default function NotificationStackingExample() {
+  // In an app NotificationProvider wraps the root once; here it keeps the example self-contained.
+  return (
+    <NotificationProvider max={4}>
+      <StackControls />
+    </NotificationProvider>
+  );
+}

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

@@ -0,0 +1,20 @@
+/** Optional parts on static cards: a custom icon, a counter, an action and a close button, or a title alone — `icon`, `badge`, `action`, `onDismiss`. */
+import { Icon, NotificationCard } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function NotificationStructureExample() {
+  return (
+    <div className={styles.cards}>
+      <NotificationCard
+        title="Новые ответы в обсуждении"
+        description="Мария и ещё двое ответили на ваш комментарий."
+        icon={<Icon name="object.message" />}
+        badge={3}
+        action={{ label: "Открыть", onClick: () => undefined }}
+        onDismiss={() => undefined}
+      />
+      <NotificationCard tone="success" title="Ссылка скопирована" />
+    </div>
+  );
+}

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

@@ -1,36 +1,24 @@
-/** The four tones as static `NotificationCard`s: the tone icon carries the meaning, the card is a raised surface without a border. Use static cards for docs and mockups; in an app toasts come from `notify()`. */
-import { NotificationCard, type NotificationRecord } from "prime-ui-kit";
+/** The four tones: the icon carries the meaning; danger and warning are announced at once — `tone`. */
+import { NotificationCard } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
 
-const copy: Record<NotificationRecord["tone"], [string, string]> = {
-  success: ["Изменения сохранены", "Профиль компании обновлён."],
-  info: ["Обновление ночью", "Сервис будет недоступен с 02:00 до 03:00."],
-  warning: ["Заканчивается подписка", "Через 3 дня закончится оплаченный период."],
-  danger: ["Не удалось отправить", "Проверьте соединение и повторите попытку."],
-};
-
-function card(tone: NotificationRecord["tone"]): NotificationRecord {
-  const [title, description] = copy[tone];
-  return {
-    id: `tones-${tone}`,
-    tone,
-    title,
-    description,
-    position: "top-right",
-    size: "m",
-    duration: 0,
-    persistent: true,
-    closable: true,
-    createdAt: 0,
-  };
-}
+const TONES = [
+  { tone: "success", title: "Изменения сохранены", description: "Профиль компании обновлён." },
+  { tone: "info", title: "Обновление ночью", description: "Сервис недоступен с 02:00 до 03:00." },
+  {
+    tone: "warning",
+    title: "Заканчивается подписка",
+    description: "Оплата закончится через 3 дня.",
+  },
+  { tone: "danger", title: "Не удалось отправить", description: "Проверьте соединение." },
+] as const;
 
 export default function NotificationTonesExample() {
   return (
     <div className={styles.cards}>
-      {(["success", "info", "warning", "danger"] as const).map((tone) => (
-        <NotificationCard key={tone} item={card(tone)} paused onDismiss={() => {}} />
+      {TONES.map((item) => (
+        <NotificationCard key={item.tone} {...item} onDismiss={() => undefined} />
       ))}
     </div>
   );

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

@@ -1,6 +1,7 @@
 # PageContent
 
-**Category:** layout
+**Category:** page
+**Kind:** layout
 
 > Page structure inside the main column: title, description, page actions and content sections.
 
@@ -23,86 +24,67 @@ import { PageContent } from "prime-ui-kit";
 ## 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
+├─ 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
 ```
 
 ## API
 
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 ### PageContent.Root
-`forwardRef` to `<div>`.
+`ref` → `HTMLDivElement`. The page column inside `main`: header → body 32 apart, centred under its cap.
 
 | 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.
+| `maxWidth` | `"full" \| "readable" \| "wide"` | `"full"` | Cap of the column: the whole main, `--prime-layout-content-max-width`, or a ~65ch reading measure. |
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children` (Header, Body), `className` and the other div attributes. |
 
 ### PageContent.Section
-`forwardRef` to `<section>`. Same column and rhythm as Root, without `maxWidth`.
+`ref` → `HTMLElement`. The same column as a `<section>`, without a cap; name it with `aria-labelledby` → the Title `id`.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `className` | `string` | — | Extra class. |
-| `children` | `ReactNode` | — | Header, Body. |
-
-+ native `<section>` props (`HTMLAttributes<HTMLElement>`; use `aria-labelledby` pointing at the Title `id`).
+| `…rest` | `HTMLAttributes<HTMLElement>` | — | `children`, `aria-labelledby`, `className` and the other section attributes. |
 
 ### 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.
+`ref` → `HTMLDivElement`. Heading column and page actions in one wrapping row; `PageContent.Actions` children move to the end.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `className` | `string` | — | Extra class. |
-| `children` | `ReactNode` | — | Title, Description, Actions. |
-
-+ native `<div>` props.
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children` (Title, Description, Actions), `className` and the other div attributes. |
 
 ### PageContent.Title
-`forwardRef` to `<h1>`.
+`ref` → `HTMLHeadingElement`. The page `<h1>` in heading-m.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `className` | `string` | — | Extra class. |
-| `children` | `ReactNode` | — | Page title. |
-
-+ native `<h1>` props.
+| `…rest` | `HTMLAttributes<HTMLHeadingElement>` | — | `children`, `id`, `className` and the other heading attributes. |
 
 ### PageContent.Description
-`forwardRef` to `<p>`.
+`ref` → `HTMLParagraphElement`. Intro `<p>` in secondary body-m.
 
 | 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.
+| `measure` | `"readable" \| "full"` | `"readable"` | `readable` — max ~65ch; `full` — the full width of the parent. |
+| `…rest` | `HTMLAttributes<HTMLParagraphElement>` | — | `children`, `className` and the other paragraph attributes. |
 
 ### PageContent.Actions
-Plain function component (no ref).
+`ref` → `HTMLDivElement`. Page-level buttons next to the title; they wrap under the heading on narrow columns.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `className` | `string` | — | Extra class. |
-| `children` | `ReactNode` | — | Page buttons. |
-
-+ native `<div>` props.
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children` (Buttons), `className` and the other div attributes. |
 
 ### PageContent.Body
-Plain function component (no ref).
+`ref` → `HTMLDivElement`. The page content; blocks 40 apart.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `className` | `string` | — | Extra class. |
-| `children` | `ReactNode` | — | Page content blocks. |
-
-+ native `<div>` props.
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children`, `className` and the other div attributes. |
 
 ## Variants
 
@@ -117,51 +99,43 @@ Plain function component (no ref).
 | 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.
+| `full` | Intro uses the full header width | The column is already narrow | |
 
-**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.
+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.
+| State | Driven by | DOM |
+|---|---|---|
+| capped column | `maxWidth` | `data-max-width="readable" \| "wide"` on Root (absent for `full`) |
+| full-width intro | `measure="full"` | `data-measure="full"` on Description |
+| with actions | `PageContent.Actions` child | `data-has-actions="true"` on Header |
 
 ## 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.
+- 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`).
 
 ## Accessibility
+
+### Keyboard
+No keyboard interaction.
+
+### 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.
-- No keyboard behaviour, no `labels`.
 
-## 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 |
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
-```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>
-  );
-}
-```
+No `labels`.
+
+## 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`. |
+| [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`.
@@ -170,4 +144,5 @@ export function Example() {
 - 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)
+- **Built from:** —
+- **See also:** [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

@@ -1,4 +1,4 @@
-/* Layout for the PageContent examples: the frame imitates AppShell.Main (canvas + gutter). */
+/* Layout of the PageContent scenarios: the frame imitates AppShell.Main (canvas + gutter). */
 
 .main {
   box-sizing: border-box;
@@ -16,11 +16,7 @@
   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);
+/* A phone-width main column (360px). */
+.narrow {
+  width: min(100%, calc(var(--prime-space-24) * 3.75));
 }

package/src/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/src/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/src/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: "Около 65 знаков в строке, по центру.",
+  },
+] 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/src/components/page-toolbar/COMPONENT.md

@@ -0,0 +1,142 @@
+# 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, exactly two rows when narrow, every slot in a fixed place.
+
+## 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.Sections          sections of the page: a fullWidth SegmentedControl with counts
+├─ PageToolbar.Tools             filter button + search: SmartFilter.Toolbar
+├─ 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 under the panel
+└─ break                         hidden line break of the two-row layout (rendered by Root)
+```
+
+## API
+
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+### PageToolbar.Root
+`ref` → `HTMLDivElement`. The page panel: lays its slots out from its own width — one row from a 56rem container, exactly two rows below it. Parts may be left out; JSX order is the Tab order.
+
+| 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. Top row; sized by content when wide, stretches when narrow and 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`. Filter button and search (`SmartFilter.Toolbar`): the stretchy item of its row; gives way down to 18rem (the button and a 9rem search on one line), then the View wraps instead.
+
+| 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 next to the Tools; alone in its row it stretches and its controls share the row 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 under the panel; 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: Sections (content width) · Tools (stretch, at least 18rem) · View (content width) · Actions; short of room the Sections shrink and scroll inside | |
+| `< 56rem` | two rows: Sections (stretch) + Actions on top; Tools (stretch) + View below | yes (mobile first) |
+| any | Chips in their own row under the panel, only while there are chips | |
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| wide | container ≥ 56rem | one row, no wrapping, break hidden; Chips rendered under the bar |
+| narrow | container < 56rem | `order` moves Actions to the top row, the break forces the second row |
+| one row empty | a row has no slot | break hidden, no empty gap |
+| alone in a row | Sections without Actions, Tools without View, View without Tools | that slot stretches to the full row; the View's controls share it equally |
+| tight row | Tools would go under 18rem (the filter button and a 9rem search) | the View wraps whole onto its own row and stretches there; the tools stay one line |
+| no chips | `PageToolbar.Chips` empty (`SmartFilter.Chips` renders nothing) | the chips row takes no space |
+
+## Layout & spacing
+- 12 between slots and between rows, 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).
+- One stretchy item per row: Sections on top, Tools below. The primary action is at the end of the top row at every width and never wraps down; with no sections it is still pushed to the end.
+- 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 — Sections, Tools, View, Actions, Chips. In the narrow layout the action is shown before the tools but reached after them.
+- 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: sections with counts, filter and search, the period and the primary action in one row; active filters in a row under it — `PageToolbar.Sections`, `PageToolbar.Tools`, `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: exactly two rows — sections and the primary action on top, filter, search and the period below; each row has one stretchy item — `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)

package/src/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;
+}