prime-ui-kit 0.9.1 → 0.9.2

package/src/components/kanban/examples/overview.tsx

@@ -0,0 +1,130 @@
+/** A release board: cards move within and between columns by drag, a touch hold or Alt + arrows; a card shows its meta line, labels, comments and assignee — `Kanban.Root`, `Kanban.Item`, `renderItem`, `renderColumnActions`. */
+import { Avatar, Badge, Button, Icon, Kanban, type PaletteColor } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+type Task = {
+  id: string;
+  title: string;
+  due: string;
+  labels: { text: string; color: PaletteColor }[];
+  comments: number;
+  assignee: { initials: string; name: string; color: PaletteColor };
+};
+
+const COLUMNS = [
+  { id: "backlog", title: "Бэклог" },
+  { id: "progress", title: "В работе" },
+  { id: "review", title: "На проверке" },
+  { id: "done", title: "Готово" },
+];
+
+const ANNA = { initials: "АК", name: "Анна Котова", color: "purple" } as const;
+const ILYA = { initials: "ИС", name: "Илья Смирнов", color: "teal" } as const;
+const MARIA = { initials: "МВ", name: "Мария Волкова", color: "orange" } as const;
+
+const TASKS: Task[] = [
+  {
+    id: "PRJ-214",
+    title: "Экспорт счетов в CSV для бухгалтерии",
+    due: "14 окт",
+    labels: [{ text: "Биллинг", color: "blue" }],
+    comments: 3,
+    assignee: ANNA,
+  },
+  {
+    id: "PRJ-221",
+    title: "Фильтр заказов по складу",
+    due: "17 окт",
+    labels: [{ text: "Заказы", color: "green" }],
+    comments: 0,
+    assignee: ILYA,
+  },
+  {
+    id: "PRJ-198",
+    title: "Повторная отправка приглашений в команду",
+    due: "10 окт",
+    labels: [
+      { text: "Команда", color: "purple" },
+      { text: "Срочно", color: "red" },
+    ],
+    comments: 5,
+    assignee: MARIA,
+  },
+  {
+    id: "PRJ-205",
+    title: "Тёмная тема для отчётов",
+    due: "12 окт",
+    labels: [{ text: "Дизайн", color: "pink" }],
+    comments: 2,
+    assignee: ANNA,
+  },
+  {
+    id: "PRJ-187",
+    title: "Лимиты API для партнёров",
+    due: "9 окт",
+    labels: [{ text: "API", color: "sky" }],
+    comments: 8,
+    assignee: ILYA,
+  },
+  {
+    id: "PRJ-176",
+    title: "Онбординг нового проекта",
+    due: "3 окт",
+    labels: [{ text: "Проекты", color: "yellow" }],
+    comments: 1,
+    assignee: MARIA,
+  },
+];
+
+const PLACEMENT = {
+  backlog: ["PRJ-214", "PRJ-221"],
+  progress: ["PRJ-198", "PRJ-205"],
+  review: ["PRJ-187"],
+  done: ["PRJ-176"],
+};
+
+export default function KanbanOverviewExample() {
+  return (
+    <Kanban.Root
+      aria-label="Задачи релиза 2.4"
+      className={styles.board}
+      columns={COLUMNS}
+      items={TASKS}
+      getId={(task) => task.id}
+      getLabel={(task) => task.title}
+      defaultValue={PLACEMENT}
+      renderColumnActions={(column) => (
+        <Button.Root variant="ghost" tone="neutral" aria-label={`Добавить в «${column.title}»`}>
+          <Button.Icon>
+            <Icon name="action.add" />
+          </Button.Icon>
+        </Button.Root>
+      )}
+      renderItem={(task) => (
+        <Kanban.Item>
+          <Kanban.ItemTitle>{task.title}</Kanban.ItemTitle>
+          <Kanban.ItemDescription>
+            {task.id} · до {task.due}
+          </Kanban.ItemDescription>
+          <Kanban.ItemBadges>
+            {task.labels.map((label) => (
+              <Badge.Root key={label.text} color={label.color}>
+                {label.text}
+              </Badge.Root>
+            ))}
+          </Kanban.ItemBadges>
+          <Kanban.ItemFooter>
+            <Kanban.ItemCount>
+              <Icon name="object.message" />
+              {task.comments}
+            </Kanban.ItemCount>
+            <Avatar.Root size="s" color={task.assignee.color} aria-label={task.assignee.name}>
+              <Avatar.Fallback>{task.assignee.initials}</Avatar.Fallback>
+            </Avatar.Root>
+          </Kanban.ItemFooter>
+        </Kanban.Item>
+      )}
+    />
+  );
+}

package/src/components/kanban/examples/states.tsx

@@ -0,0 +1,75 @@
+/** Loading draws skeleton cards in the card geometry and cross-fades the cards in; an empty column keeps its drop area; a read-only board drags nothing — `loading`, `disabled`. */
+import { Button, Icon, Kanban, Switch } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+type Order = { id: string; title: string; total: string };
+
+const COLUMNS = [
+  { id: "new", title: "Новые" },
+  { id: "packing", title: "Сборка" },
+  { id: "shipped", title: "Отгружены" },
+];
+
+const ORDERS: Order[] = [
+  { id: "ORD-5531", title: "ООО «Север» · 12 позиций", total: "48 300 ₽" },
+  { id: "ORD-5529", title: "ИП Лебедев · 3 позиции", total: "7 950 ₽" },
+  { id: "ORD-5524", title: "АО «Гранит» · 40 позиций", total: "212 000 ₽" },
+];
+
+const PLACEMENT = { new: ["ORD-5531", "ORD-5529"], packing: [], shipped: ["ORD-5524"] };
+
+const LOAD_MS = 1200;
+
+export default function KanbanStatesExample() {
+  const [loading, setLoading] = React.useState(true);
+  const [readOnly, setReadOnly] = React.useState(false);
+
+  React.useEffect(() => {
+    if (!loading) return;
+    const timer = window.setTimeout(() => setLoading(false), LOAD_MS);
+    return () => window.clearTimeout(timer);
+  }, [loading]);
+
+  return (
+    <div className={styles.stage}>
+      <div className={styles.toolbar}>
+        <Switch.Root checked={readOnly} onCheckedChange={setReadOnly}>
+          <Switch.Label>Только просмотр</Switch.Label>
+        </Switch.Root>
+        <div className={styles.spacer} />
+        <Button.Root
+          variant="soft"
+          tone="neutral"
+          loading={loading}
+          onClick={() => setLoading(true)}
+        >
+          <Button.Icon>
+            <Icon name="action.refresh" />
+          </Button.Icon>
+          Обновить
+        </Button.Root>
+      </div>
+      <Kanban.Root
+        aria-label="Заказы склада"
+        className={styles.board}
+        columns={COLUMNS}
+        items={ORDERS}
+        getId={(order) => order.id}
+        getLabel={(order) => order.id}
+        defaultValue={PLACEMENT}
+        loading={loading}
+        disabled={readOnly}
+        renderItem={(order) => (
+          <Kanban.Item>
+            <Kanban.ItemTitle>{order.id}</Kanban.ItemTitle>
+            <Kanban.ItemDescription>
+              {order.title} · {order.total}
+            </Kanban.ItemDescription>
+          </Kanban.Item>
+        )}
+      />
+    </div>
+  );
+}

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

@@ -0,0 +1,76 @@
+/** Cards take only the parts they need: a title alone, a meta line, labels, a footer with counts and an assignee — `Kanban.ItemTitle`, `Kanban.ItemDescription`, `Kanban.ItemBadges`, `Kanban.ItemFooter`, `Kanban.ItemCount`. */
+import { Avatar, Badge, Icon, Kanban } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+type Card = {
+  id: string;
+  title: string;
+  meta?: string;
+  label?: string;
+  comments?: number;
+  attachments?: number;
+  assignee?: { initials: string; name: string };
+};
+
+const COLUMNS = [
+  { id: "inbox", title: "Входящие" },
+  { id: "planned", title: "Запланировано" },
+];
+
+const CARDS: Card[] = [
+  { id: "c1", title: "Уточнить реквизиты поставщика" },
+  { id: "c2", title: "Сверка остатков на складе", meta: "INV-3102 · до 15 окт" },
+  { id: "c3", title: "Новый тариф для партнёров", label: "Продажи" },
+  {
+    id: "c4",
+    title: "Акт сверки с ООО «Вектор»",
+    meta: "INV-3088 · до 11 окт",
+    label: "Финансы",
+    comments: 4,
+    attachments: 2,
+    assignee: { initials: "ОБ", name: "Ольга Белова" },
+  },
+];
+
+const PLACEMENT = { inbox: ["c1", "c2"], planned: ["c3", "c4"] };
+
+export default function KanbanStructureExample() {
+  return (
+    <Kanban.Root
+      aria-label="Задачи отдела закупок"
+      className={styles.board}
+      columns={COLUMNS}
+      items={CARDS}
+      getId={(card) => card.id}
+      getLabel={(card) => card.title}
+      defaultValue={PLACEMENT}
+      renderItem={(card) => (
+        <Kanban.Item>
+          <Kanban.ItemTitle>{card.title}</Kanban.ItemTitle>
+          {card.meta ? <Kanban.ItemDescription>{card.meta}</Kanban.ItemDescription> : null}
+          {card.label ? (
+            <Kanban.ItemBadges>
+              <Badge.Root color="blue">{card.label}</Badge.Root>
+            </Kanban.ItemBadges>
+          ) : null}
+          {card.assignee ? (
+            <Kanban.ItemFooter>
+              <Kanban.ItemCount>
+                <Icon name="object.message" />
+                {card.comments}
+              </Kanban.ItemCount>
+              <Kanban.ItemCount>
+                <Icon name="object.document" />
+                {card.attachments}
+              </Kanban.ItemCount>
+              <Avatar.Root size="s" color="green" aria-label={card.assignee.name}>
+                <Avatar.Fallback>{card.assignee.initials}</Avatar.Fallback>
+              </Avatar.Root>
+            </Kanban.ItemFooter>
+          ) : null}
+        </Kanban.Item>
+      )}
+    />
+  );
+}

package/src/components/login-form/COMPONENT.md

@@ -1,6 +1,6 @@
 # LoginForm
 
-**Category:** inputs
+**Category:** composition
 **Kind:** composite
 
 > A sign-in card with a logo, title, provider buttons and a form; covers sign-in, sign-up, password reset and code confirmation.

package/src/components/modal/COMPONENT.md

@@ -26,6 +26,7 @@ import { Modal } from "prime-ui-kit";
 Modal.Root                    state and dismiss policy (no DOM)
 ├── Modal.Trigger             clones its child; opens on click
 └── Modal.Content             portal + scrim + role="dialog"
+    ├── (grab handle)         below 640px only: aria-hidden bar, a drag starts here
     ├── Modal.Header          grid: [Icon] [Title + Description] [close button]
     │   ├── Modal.Icon        40 tile with a tone fill
     │   ├── Modal.Title       <h2>, names the dialog
@@ -49,7 +50,7 @@ No DOM, no ref. State and dismiss policy.
 | `defaultOpen` | `boolean` | `false` | Initial visibility, uncontrolled. |
 | `onOpenChange` | `(open: boolean) => void` | — | Called on every open and close: trigger, close button, `Close`, Escape, scrim click, code. |
 | `closeOnEscape` | `boolean` | `true` | Escape closes the dialog. |
-| `closeOnOutsideClick` | `boolean` | `true` | A click on the scrim closes the dialog; turn off for destructive confirms. |
+| `closeOnOutsideClick` | `boolean` | `true` | A click on the scrim (and a swipe on a bottom sheet) closes the dialog; turn off for destructive confirms. |
 | `labels` | `Partial<ModalLabels>` | — | Built-in strings, see Labels. |
 | `children` | `ReactNode` | — | Trigger and Content. |
 | `confirmOnEnter` | `boolean` | `true` | Enter inside the dialog clicks the element wrapped in `Modal.Confirm`; Enter on a button or link activates that element instead. |
@@ -60,7 +61,7 @@ No DOM, no ref. State and dismiss policy.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `size` | `"s" \| "m" \| "l" \| "xl"` | `"m"` | Width: 440 · 560 · 720 · 960. Below 640 px of viewport — a full-width bottom sheet. |
+| `size` | `"s" \| "m" \| "l" \| "xl"` | `"m"` | Width: 440 · 560 · 720 · 960. Below 640 px of viewport — a full-width bottom sheet with a grab handle; a swipe down from the handle or the header closes it. |
 | `container` | `HTMLElement \| null` | `document.body` | Portal target. |
 | `aria-label` | `string` | — | Dialog name when there is no Title. |
 | `aria-labelledby` | `string` | — | Overrides the Title id. |
@@ -96,7 +97,7 @@ No DOM, no ref. State and dismiss policy.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `layout` | `"fill" \| "end"` | `"fill" (s/m), "end" (l/xl)` | `fill`: equal-width buttons in one row; `end`: auto width, at the end. Narrower than 360 px — stacked. |
+| `layout` | `"fill" \| "end"` | `"fill" (s/m), "end" (l/xl)` | `fill`: equal-width buttons in one row; `end`: auto width, at the end. Stacked on phones (viewport below 640 px) and in a dialog narrower than 360 px. |
 
 ### Modal.Trigger · Modal.Close · Modal.Confirm
 No DOM: clone the single child and chain its `onClick` (unless the child's handler calls `preventDefault()`).
@@ -116,7 +117,7 @@ The dialog has one look: `bg-raised`, `--prime-modal-radius` (16), `shadow-modal
 | `l` | 720 wide, footer buttons right-aligned | Two-column forms | |
 | `xl` | 960 wide, footer buttons right-aligned | Tables, previews | |
 
-Below 640px of viewport every size becomes a full-width bottom sheet.
+Below 640px of viewport every size becomes a full-width bottom sheet with a grab handle.
 
 ### layout (Footer)
 | Value | Looks like | Use when | Default |
@@ -124,7 +125,7 @@ Below 640px of viewport every size becomes a full-width bottom sheet.
 | `fill` | Equal-width buttons in one row, gap 12 | Narrow dialogs with two actions | for `s`, `m` |
 | `end` | Auto-width buttons at the end, gap 8 | Wide dialogs | for `l`, `xl` |
 
-When the dialog itself is narrower than 360px, actions stack full width in DOM order (primary last).
+On phones (viewport below 640px, where the dialog is a bottom sheet) and in a dialog narrower than 360px, actions stack full width in DOM order (primary last).
 
 ### tone (Icon)
 | Value | Looks like | Use when | Default |
@@ -157,6 +158,7 @@ When the dialog itself is narrower than 360px, actions stack full width in DOM o
 | footer layout | `layout` or the size default | `data-layout` on the footer |
 | icon tone | `tone` on Icon | `data-tone` on the tile |
 | while open | — | focus trapped inside, page scroll locked, siblings of the portal `inert` (the toast region stays usable) |
+| swiping | below 640px, a drag down from the handle or the header (with `closeOnOutsideClick`) | `data-swiping` and `--swipe-offset` on the dialog while the pointer drags it; past 30% of its height or on a flick it closes, otherwise it glides back |
 
 Loading or disabled actions use the Button props (`loading`, `disabled`) inside the footer.
 
@@ -164,7 +166,7 @@ Loading or disabled actions use the Button props (`loading`, `disabled`) inside
 - Dialog padding `--prime-modal-padding` (24) on every zone; header 24 top / 20 bottom, body 20 with a 16 gap between blocks, footer 20 top / 24 bottom.
 - Max height = viewport minus `--prime-modal-viewport-padding` on both sides; only the body scrolls.
 - Fields inside get the surface field fill; cards inside become sunken tiles. Group fields with a 20 gap.
-- Narrow viewport (< 640px): bottom sheet, full width, top corners rounded.
+- Narrow viewport (< 640px): bottom sheet, full width, top corners `--prime-sheet-radius`, a grab handle strip on top, up to `100dvh − --prime-sheet-top-gap` high, the bottom safe-area inset below the content.
 
 ## Accessibility
 
@@ -180,6 +182,7 @@ Loading or disabled actions use the Button props (`loading`, `disabled`) inside
 - Focus moves into the dialog on open (an `autoFocus` field wins) and returns to the opener on close — also after a scrim click (foundation §8).
 - The page behind is `inert` and its scroll is locked.
 - Only the topmost layer reacts: a Select open inside the dialog closes first.
+- On a narrow viewport a swipe down is an extra way out; the close button and Escape stay. A destructive confirm (`closeOnOutsideClick={false}`) does not close by swipe. The grab handle is `aria-hidden`.
 
 ### Labels
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->

package/src/components/notification/COMPONENT.md

@@ -1,6 +1,6 @@
 # Notification
 
-**Category:** feedback
+**Category:** status
 **Kind:** overlay
 
 > Pop-up toast notifications: `NotificationProvider` at the app root and `notify()` from any screen.
@@ -136,7 +136,7 @@ The card is always a raised surface without a border; only the icon, the badge a
 Collapsed stacks show up to 3 cards peeking behind each other. Hover or keyboard focus expands the stack. Toasts enter from their edge and leave toward it, faster than they came; a swipe toward the edge dismisses (past `--prime-space-12` or a quick flick). Under `prefers-reduced-motion` toasts are removed without an exit animation.
 
 ## Layout & spacing
-- A fixed, portaled viewport; zones are `--prime-space-5` from the edge (`--prime-space-3` below 640px), at most 24rem wide.
+- A fixed, portaled viewport; zones are `--prime-space-5` from the edge (`--prime-space-3` below 640px) plus the safe-area insets (`env(safe-area-inset-*)`), at most 24rem wide.
 - Cards in an expanded stack are `--prime-space-2` apart.
 - The viewport takes pointer events only over the cards.
 

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

@@ -1,6 +1,6 @@
 # PageContent
 
-**Category:** layout
+**Category:** page
 **Kind:** layout
 
 > Page structure inside the main column: title, description, page actions and content sections.

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;
+}

package/src/components/page-toolbar/examples/narrow.tsx

@@ -0,0 +1,103 @@
+/** 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`. */
+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.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.Tools>
+            <SmartFilter.Toolbar />
+          </PageToolbar.Tools>
+          <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>
+  );
+}