prime-ui-kit 0.14.0 → 0.16.0

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

@@ -29,7 +29,7 @@ import { PageContent } from "prime-ui-kit";
 
 ## Anatomy
 ```
-PageContent.Root | PageContent.Page        column; Root adds maxWidth and fill, Page renders <section>
+PageContent.Root                           column (<div>, or <section> with as="section"); maxWidth, fill
 ├─ PageContent.Header                      heading column + actions in one wrapping row
 │  ├─ PageContent.Title                    <h1>, heading-m
 │  ├─ PageContent.Description              <p>, secondary body-m
@@ -40,8 +40,8 @@ PageContent.Root | PageContent.Page        column; Root adds maxWidth and fill,
    ├─ PageContent.Section                  <section> + <h2> label, 40 from its neighbours
    │  └─ PageContent.Actions               a link or button at the end of the section heading
    └─ 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.Panel kind="list"     list pane: 16–20rem column, or the whole split while closed
+      └─ PageContent.Panel kind="detail"   detail pane: the rest, or the whole split while open
          └─ PageContent.BackButton         back to the list, only while one pane shows
 ```
 
@@ -50,20 +50,14 @@ PageContent.Root | PageContent.Page        column; Root adds maxWidth and fill,
 <!-- 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 24 apart, centred under its cap.
+`ref` → `HTMLElement` (`<div>` or `<section>`). The page column inside `main`: header → body 24 apart, centred under its cap.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
+| `as` | `"div" \| "section"` | `"div"` | `section` — the whole app page as a region; name it with `aria-labelledby` → the Title `id`. |
 | `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.Page
-`ref` → `HTMLElement`. The whole app page as a `<section>` (the same column, the full panel width); name it with `aria-labelledby` → the Title `id`.
-
-| Prop | Type | Default | Description |
-|---|---|---|---|
-| `…rest` | `HTMLAttributes<HTMLElement>` | — | `children`, `aria-labelledby`, `className` and the other section attributes. |
+| `…rest` | `HTMLAttributes<HTMLElement>` | — | `children` (Header, Body), `className` and the other attributes. |
 
 ### PageContent.Header
 `ref` → `HTMLDivElement`. Heading column and page actions in one wrapping row; `PageContent.Actions` children move to the end.
@@ -136,20 +130,14 @@ PageContent.Root | PageContent.Page        column; Root adds maxWidth and fill,
 | `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. |
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children` (two `PageContent.Panel`s: `list`, then `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.
+### PageContent.Panel
+`ref` → `HTMLDivElement`. A pane of the split: a column whose last child takes the free height (a Card with its own ScrollContainer). Focusable from code (`tabindex=-1`, no ring).
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
+| `kind` | `"list" \| "detail"` | — (required) | `list` — the 16–20rem column, or the whole split while closed; going back refocuses its last control. `detail` — the rest, or the whole split while open; focus lands here when it opens. |
 | `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children`, `aria-label`, `className` and the other div attributes. |
 
 ### PageContent.BackButton
@@ -222,20 +210,24 @@ One `PageContent.Title` (`<h1>`) per page; a topic inside Body is a `PageContent
 - Grid lays itself out from its own width (container `prime-grid`), never from the window, so a board beside an open Sidebar folds on its own. A Cell stretches its child: the tiles of a row share one height; a chart in a `rows={2}` cell fills it with `ChartFrame.Plot height="fill"`. `dense` flow lets a small tile fill a hole left by a wide one.
 - `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 records of the list pane are a [List](../list/COMPONENT.md).
-- 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.
+- 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. A newly chosen record cross-fades in (`Crossfade` keyed by its id).
 
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 | 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.Page` an `aria-labelledby` that points at the Title `id` to name the region.
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+- `PageContent.Title` is an `<h1>`; use one per page.
+- Give `PageContent.Root as="section"` an `aria-labelledby` that points at the Title `id` to name the region.
 - `PageContent.Section` is a `<section>` named by its own `<h2>` (`label`) through `aria-labelledby`, so it is a region landmark with the heading's name; the heading levels go h1 (page) → h2 (section) → h3 (a card title inside it).
-- 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).
+- Name both `PageContent.Panel`s with `aria-label`: a named pane is `role="region"`, a landmark. 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
@@ -252,15 +244,16 @@ One `PageContent.Title` (`<h1>`) per page; a topic inside Body is a `PageContent
 | [variants.tsx](examples/variants.tsx) | The same page column at three caps: the whole main, a wide dashboard column, a reading column — `maxWidth`. |
 | [grid.tsx](examples/grid.tsx) | A dashboard board: four KPI tiles, a chart two rows high beside two panels, one gap on both axes — `PageContent.Grid`, `PageContent.Cell`, `span`, `rows`. |
 | [sections.tsx](examples/sections.tsx) | A page with titled sections: tiles of one screen close together, a new topic set off by air, a link at the end of the heading, a heading column beside a panel — `PageContent.Section`, `label`, `description`, `PageContent.Actions`, `layout`. |
-| [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. |
+| [list-detail.tsx](examples/list-detail.tsx) | A ticket queue 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; the chosen ticket cross-fades in — `PageContent.Split`, `PageContent.Panel`, `PageContent.BackButton`, `fill`. |
+| [narrow.tsx](examples/narrow.tsx) | In a phone-width column the page actions wrap under the heading instead of squeezing it — `PageContent.Actions`. |
+| [screen.tsx](examples/screen.tsx) | A settings page: sections with a heading column and a panel, a form saved by its own button, switches that apply at once and a danger zone with a confirm — `layout`, `maxWidth`. |
 
 ## 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>`; a topic of the page is a `PageContent.Section` with its `<h2>`.
 - A hand-made `<section>` + `Typography as="h2"` + own gap CSS → `PageContent.Section label`.
-- Each row of cards in its own auto-fit grid → the rows stand 24 apart instead of 16; put every tile of the screen in one `PageContent.Grid`.
+- Each row of cards in its own grid → the rows stand 24 apart instead of 16; put every tile of the screen in one `PageContent.Grid`.
 - Margins between blocks in Body → Body already sets the 24 gap and the 40 around a Section.
 - 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.

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

@@ -1,21 +1,12 @@
-/* Layout of the PageContent scenarios: the frame imitates AppShell.Main (canvas + gutter). */
+/* Layout of the PageContent scenarios: the frame stands for AppShell.Main (its 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;
@@ -24,8 +15,6 @@
   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. */
@@ -46,17 +35,15 @@
   min-height: 0;
 }
 
-.dialogs {
+.tickets {
   padding: var(--prime-space-2);
 }
 
-.messages {
+.notes {
   display: flex;
   flex-direction: column;
   gap: var(--prime-space-3);
-  margin: 0;
   padding: var(--prime-space-2) var(--prime-space-4) var(--prime-space-4);
-  list-style: none;
 }
 
 .hint {

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

@@ -20,6 +20,8 @@ const WEEKS = [
   { week: "5 нед", orders: 352 },
 ];
 
+const ROWS = WEEKS.map(({ week, orders }) => ({ label: week, values: { orders } }));
+
 const MARGIN = { top: 8, right: 8, bottom: 24, left: 8 };
 
 const formatOrders = (value: number) => `${value.toLocaleString("ru-RU")} заказов`;
@@ -39,7 +41,7 @@ export default function PageContentGridExample() {
             </PageContent.Cell>
           ))}
           <PageContent.Cell span={8} rows={2}>
-            <ChartFrame.Root series={SERIES} formatValue={formatOrders}>
+            <ChartFrame.Root series={SERIES} rows={ROWS} formatValue={formatOrders}>
               <ChartFrame.Header>
                 <ChartFrame.Title>Заказы по неделям</ChartFrame.Title>
                 <ChartFrame.Description>Октябрь</ChartFrame.Description>

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

@@ -1,106 +1,109 @@
-/** 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 { Card, List, PageContent, ScrollContainer, Typography } from "prime-ui-kit";
+/** A ticket queue 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; the chosen ticket cross-fades in — `PageContent.Split`, `PageContent.Panel`, `PageContent.BackButton`, `fill`. */
+import { Card, Crossfade, List, 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[] };
+type Ticket = { id: string; subject: string; client: string; open: number; notes: string[] };
 
-const DIALOGS: Dialog[] = [
+const TICKETS: Ticket[] = [
   {
-    id: "granit",
+    id: "T-4821",
+    subject: "Счёт без НДС",
     client: "ООО «Гранит»",
-    unread: 2,
-    messages: [
+    open: 2,
+    notes: [
       "Счёт № 4821 пришёл без НДС.",
-      "Проверю реквизиты и вернусь.",
+      "Проверили реквизиты: ставка не подставилась из договора.",
       "Нужно провести до пятницы.",
-      "Исправили ставку, новый счёт № 4830 на почте.",
+      "Исправили ставку, новый счёт № 4830 отправлен на почту.",
     ],
   },
   {
-    id: "leto",
+    id: "T-4817",
+    subject: "Перенос доставки",
     client: "ООО «Лето»",
-    unread: 0,
-    messages: ["Можно перенести доставку на среду?", "Да, перенесли на 15 октября."],
+    open: 0,
+    notes: ["Просят перенести доставку на среду.", "Перенесли на 15 октября, склад предупреждён."],
   },
   {
-    id: "kozlov",
+    id: "T-4809",
+    subject: "Подключение ЭДО",
     client: "ИП Козлов",
-    unread: 1,
-    messages: ["Подключите, пожалуйста, ЭДО.", "Пришлите идентификатор в Диадоке."],
+    open: 1,
+    notes: ["Нужно подключить ЭДО.", "Запросили идентификатор в Диадоке."],
   },
 ];
 
 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 [ticketId, setTicketId] = React.useState<string | null>(null);
+  // The last opened ticket stays in the detail while the narrow split goes back to the list.
+  const [shown, setShown] = React.useState<Ticket | null>(null);
 
-  const open = (dialog: Dialog) => {
-    setDialogId(dialog.id);
-    setShown(dialog);
+  const open = (ticket: Ticket) => {
+    setTicketId(ticket.id);
+    setShown(ticket);
   };
 
   return (
     <div className={styles.fillMain}>
       <PageContent.Root fill>
-        <PageContent.Header>
-          <PageContent.Title>Обращения</PageContent.Title>
-        </PageContent.Header>
         <PageContent.Body>
           <PageContent.Split
-            open={dialogId !== null}
+            open={ticketId !== null}
             onOpenChange={(next) => {
-              if (!next) setDialogId(null);
+              if (!next) setTicketId(null);
             }}
           >
-            <PageContent.List aria-label="Диалоги">
+            <PageContent.Panel kind="list" aria-label="Обращения">
               <Card.Root className={styles.paneCard}>
                 <ScrollContainer className={styles.pane}>
-                  <List.Root className={styles.dialogs}>
-                    {DIALOGS.map((dialog) => (
+                  <List.Root className={styles.tickets}>
+                    {TICKETS.map((ticket) => (
                       <List.Item
-                        key={dialog.id}
-                        current={dialog.id === dialogId}
-                        onClick={() => open(dialog)}
+                        key={ticket.id}
+                        current={ticket.id === ticketId}
+                        onClick={() => open(ticket)}
                       >
-                        <List.ItemText>{dialog.client}</List.ItemText>
-                        {dialog.unread > 0 ? (
-                          <List.ItemCount color="blue">{dialog.unread}</List.ItemCount>
+                        <List.ItemText>{ticket.subject}</List.ItemText>
+                        <List.ItemDescription>{ticket.client}</List.ItemDescription>
+                        {ticket.open > 0 ? (
+                          <List.ItemCount color="blue">{ticket.open}</List.ItemCount>
                         ) : null}
                       </List.Item>
                     ))}
                   </List.Root>
                 </ScrollContainer>
               </Card.Root>
-            </PageContent.List>
+            </PageContent.Panel>
 
-            <PageContent.Detail aria-label="Переписка">
+            <PageContent.Panel kind="detail" aria-label="Обращение">
               <Card.Root className={styles.paneCard}>
                 <div className={styles.threadHeader}>
                   <PageContent.BackButton />
                   <Typography as="h2" variant="title-s">
-                    {shown?.client ?? "Выберите диалог"}
+                    {shown ? `${shown.id} · ${shown.subject}` : "Выберите обращение"}
                   </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>
-                  )}
+                  <Crossfade state={shown?.id ?? "none"}>
+                    {shown ? (
+                      <div className={styles.notes}>
+                        {shown.notes.map((text) => (
+                          <Typography key={text} variant="body-m">
+                            {text}
+                          </Typography>
+                        ))}
+                      </div>
+                    ) : (
+                      <Typography variant="body-m" tone="muted" className={styles.hint}>
+                        История обращения откроется здесь.
+                      </Typography>
+                    )}
+                  </Crossfade>
                 </ScrollContainer>
               </Card.Root>
-            </PageContent.Detail>
+            </PageContent.Panel>
           </PageContent.Split>
         </PageContent.Body>
       </PageContent.Root>

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

@@ -1,4 +1,4 @@
-/** In a phone-width column the page actions wrap under the heading instead of squeezing it. */
+/** In a phone-width column the page actions wrap under the heading instead of squeezing it — `PageContent.Actions`. */
 import { Button, PageContent } from "prime-ui-kit";
 
 import styles from "./examples.module.css";

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

@@ -6,7 +6,7 @@ import styles from "./examples.module.css";
 export default function PageContentOverviewExample() {
   return (
     <div className={styles.main}>
-      <PageContent.Page aria-labelledby="settings-heading">
+      <PageContent.Root as="section" aria-labelledby="settings-heading">
         <PageContent.Header>
           <PageContent.Title id="settings-heading">Настройки</PageContent.Title>
           <PageContent.Description>
@@ -35,7 +35,7 @@ export default function PageContentOverviewExample() {
             </Card.Body>
           </Card.Root>
         </PageContent.Body>
-      </PageContent.Page>
+      </PageContent.Root>
     </div>
   );
 }

package/dist/skill/{patterns/settings-page.tsx → reference/components/page-content/examples/screen.tsx}

@@ -1,4 +1,4 @@
-/** A settings page: sections with a heading column and a panel, a form saved by its own button, switches that apply at once and a danger zone with a confirm. */
+/** A settings page: sections with a heading column and a panel, a form saved by its own button, switches that apply at once and a danger zone with a confirm — `layout`, `maxWidth`. */
 import {
   Button,
   Card,
@@ -13,7 +13,7 @@ import {
 } from "prime-ui-kit";
 import * as React from "react";
 
-import styles from "./settings-page.module.css";
+import styles from "./screen.module.css";
 
 const TIMEZONES = [
   { value: "Europe/Kaliningrad", label: "Калининград (UTC+2)" },
@@ -45,7 +45,7 @@ const ALERTS = [
   },
 ];
 
-export default function SettingsPagePattern() {
+export default function PageContentScreenExample() {
   const [innError, setInnError] = React.useState<string>();
   const [saving, setSaving] = React.useState(false);
   const [saved, setSaved] = React.useState(false);

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

@@ -4,24 +4,17 @@ 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: "Не шире колонки для чтения, по центру.",
-  },
+  { value: "full", text: "Сделки: колонка занимает всю ширину main." },
+  { value: "wide", text: "Дашборд продаж: не шире ширины контента, по центру." },
+  { value: "readable", 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>
+    <>
+      {WIDTHS.map(({ value, text }) => (
+        <div key={value} className={styles.main}>
+          <PageContent.Root maxWidth={value}>
             <PageContent.Body>
               <Card.Root>
                 <Card.Body>
@@ -32,8 +25,8 @@ export default function PageContentVariantsExample() {
               </Card.Root>
             </PageContent.Body>
           </PageContent.Root>
-        ))}
-      </div>
-    </div>
+        </div>
+      ))}
+    </>
   );
 }

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

@@ -3,15 +3,15 @@
 **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.
+> 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 the top row.
 
 ## 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.
+- Any page that has to work on the narrowest supported screen (a 320 px phone) 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`.
+- One or two buttons of the page and nothing else → `AppHeader.Actions` in the [AppHeader](../../layout/app-header/COMPONENT.md) title row.
 - 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).
@@ -28,7 +28,7 @@ PageToolbar.Root                 container: its own width picks the layout
 ├─ 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
+└─ PageToolbar.Chips             active filters: SmartFilter.Chips, a row under the top row
 ```
 
 ## API
@@ -36,7 +36,7 @@ PageToolbar.Root                 container: its own width picks the layout
 <!-- 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.
+`ref` → `HTMLDivElement`. The page panel: one row from 56rem of its own width, stacked rows below. Any slot may be left out; whatever the JSX order, the DOM and Tab order is Tools, Sections, View, Actions, Chips. Named (`aria-label`), it is a `group`.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -50,7 +50,7 @@ PageToolbar.Root                 container: its own width picks the layout
 | `…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.
+`ref` → `HTMLDivElement`. Search and filter button (`SmartFilter.Toolbar`): always the first slot and the stretchy one; it gives way first when the row runs short.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -64,14 +64,14 @@ PageToolbar.Root                 container: its own width picks the layout
 | `…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.
+`ref` → `HTMLDivElement`. The primary action of the page: at the end of the top row; on a phone, when the search would get less than 18rem beside it, its own full row right under the search.
 
 | 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.
+`ref` → `HTMLDivElement`. Active filters (`SmartFilter.Chips`) in their own row under the top row; the row takes no space while it is empty.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -83,37 +83,43 @@ 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` | one row that never wraps: Tools (stretch) · Sections (content width) · View (content width) · Actions; Chips under it; short of room the Tools give way first, down to 12rem, so the Sections keep their items and counts whole; only 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 | |
+| phone (Tools would get < 18rem beside the Actions) | rows: Tools (full row); Actions (full row, its buttons share it); Chips; Sections; View — the search is never squeezed; an icon-only action still fits beside the Tools | |
+| any | Chips under the top row, 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 |
+| narrow | container < 56rem | one wrapping flex line of real rows only (`order` + full-row slots): a missing slot makes no row, every row is 12 from the next |
+| action on its own row | narrow, and the Tools (or the Sections in their place) would get less than 18rem beside the Actions | the Actions wrap under them and stretch across the row; an Actions slot alone in the toolbar keeps its buttons at the end |
+| no Tools | Sections without Tools; View without Tools and Sections | that slot takes the Tools' place: first and stretchy, beside the action, so the action stays at the top row's end |
+| 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 and may shrink below their content (`min-width: 0`), so the row fits a phone |
 | 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.
+- 8 inside a slot. No padding or fill of its own: on an app page it is the page's tools row in `AppHeader.Tools`, under the page title; tools of one table go into that table's `toolbar`.
+- The order is fixed: search and filter first, then the sections, the view and the primary action; the active filters sit under the top row, never under the sections. The primary action is at the end of the top row; on a phone, where the search would get less than 18rem beside it, it takes its own row right under the search — still above the sections and the view.
 - 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.
+- On a phone the primary action takes its own row by itself; an icon-only action with `aria-label` stays beside the search instead. Never remove it.
 - The toolbar breaks by its own width, so it behaves the same with the sidebar open or closed.
 
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 No keyboard interaction.
 
 ### ARIA
-- A plain `<div>`: when a page has more than one panel, give each `role="group"` and an `aria-label` (a name on a `<div>` without a role is ignored by assistive tech).
-- 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`.
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+- With an `aria-label` the root is `role="group"` named by it: when a page has more than one panel, name each.
+- The root renders the slots in the wide layout's reading order — Tools, Sections, View, Actions, Chips — whatever the JSX order; the narrow layout moves them only visually (`order`).
+- An icon-only primary action carries `aria-label`.
 
 ### Labels
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
@@ -123,10 +129,10 @@ 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`. |
+| [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 under the top row — `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`. |
+| [narrow.tsx](examples/narrow.tsx) | A phone-width column: search and filter on top, the primary action on its own row under them, then the active filters, 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`.

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

@@ -1,4 +1,4 @@
-/** 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`. */
+/** A phone-width column: search and filter on top, the primary action on its own row under them, then the active filters, the sections and the period, every row 12 apart — `PageToolbar.Root`. */
 import {
   Button,
   Icon,
@@ -38,7 +38,9 @@ const FIELDS: SmartFilterField[] = [
 export default function PageToolbarNarrowExample() {
   const [section, setSection] = React.useState("all");
   const [period, setPeriod] = React.useState("7d");
-  const [filter, setFilter] = React.useState<SmartFilterValue>({});
+  const [filter, setFilter] = React.useState<SmartFilterValue>({
+    city: { include: ["msk"], exclude: [] },
+  });
   const [search, setSearch] = React.useState("");
 
   return (
@@ -87,10 +89,11 @@ export default function PageToolbarNarrowExample() {
             </Select.Root>
           </PageToolbar.View>
           <PageToolbar.Actions>
-            <Button.Root aria-label="Новый заказ">
+            <Button.Root>
               <Button.Icon>
                 <Icon name="action.add" />
               </Button.Icon>
+              Новый заказ
             </Button.Root>
           </PageToolbar.Actions>
           <PageToolbar.Chips>

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

@@ -1,4 +1,4 @@
-/** 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`. */
+/** The panel of an orders page: search and filter, sections with counts, the period and the primary action in one row; active filters under the top row — `PageToolbar.Tools`, `PageToolbar.Sections`, `PageToolbar.View`, `PageToolbar.Actions`, `PageToolbar.Chips`. */
 import {
   Button,
   Icon,