prime-ui-kit 0.15.0 → 0.16.0

package/src/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,8 +244,8 @@ 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
@@ -261,7 +253,7 @@ One `PageContent.Title` (`<h1>`) per page; a topic inside Body is a `PageContent
 - 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/src/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/src/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/src/components/page-content/examples/list-detail.tsx

@@ -1,45 +1,48 @@
-/** 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 (
@@ -47,57 +50,60 @@ export default function PageContentListDetailExample() {
       <PageContent.Root fill>
         <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/src/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/src/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/src/components/page-content/examples/variants.tsx

@@ -11,10 +11,10 @@ const WIDTHS = [
 
 export default function PageContentVariantsExample() {
   return (
-    <div className={styles.main}>
-      <div className={styles.stack}>
-        {WIDTHS.map(({ value, text }) => (
-          <PageContent.Root key={value} maxWidth={value}>
+    <>
+      {WIDTHS.map(({ value, text }) => (
+        <div key={value} className={styles.main}>
+          <PageContent.Root maxWidth={value}>
             <PageContent.Body>
               <Card.Root>
                 <Card.Body>
@@ -25,8 +25,8 @@ export default function PageContentVariantsExample() {
               </Card.Root>
             </PageContent.Body>
           </PageContent.Root>
-        ))}
-      </div>
-    </div>
+        </div>
+      ))}
+    </>
   );
 }

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

@@ -8,7 +8,7 @@
 ## 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
 - One or two buttons of the page and nothing else → `AppHeader.Actions` in the [AppHeader](../../layout/app-header/COMPONENT.md) title row.
@@ -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 |
 |---|---|---|---|
@@ -95,7 +95,7 @@ PageToolbar has no variants: the layout follows the toolbar's width.
 | 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 |
+| 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
@@ -110,11 +110,15 @@ PageToolbar has no variants: the layout follows the toolbar's width.
 ## 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.
+<!-- 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
@@ -125,7 +129,7 @@ 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 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`. |

package/src/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,

package/src/components/page-toolbar/examples/save-changes.tsx

@@ -13,28 +13,31 @@ const CHANGES = 3;
 export default function PageToolbarSaveChangesExample() {
   const [section, setSection] = React.useState("profile");
 
+  // The toolbar heads the settings form: its save action submits the page's form.
   return (
-    <PageToolbar.Root aria-label="Настройки">
-      <PageToolbar.Sections>
-        <SegmentedControl.Root
-          fullWidth
-          value={section}
-          onValueChange={setSection}
-          aria-label="Раздел настроек"
-        >
-          {SECTIONS.map((item) => (
-            <SegmentedControl.Item key={item.value} value={item.value}>
-              {item.label}
-            </SegmentedControl.Item>
-          ))}
-        </SegmentedControl.Root>
-      </PageToolbar.Sections>
-      <PageToolbar.Actions>
-        <Button.Root variant="ghost" tone="neutral">
-          Отменить
-        </Button.Root>
-        <Button.Root>Сохранить {CHANGES} изменения</Button.Root>
-      </PageToolbar.Actions>
-    </PageToolbar.Root>
+    <form onSubmit={(event) => event.preventDefault()}>
+      <PageToolbar.Root aria-label="Настройки">
+        <PageToolbar.Sections>
+          <SegmentedControl.Root
+            fullWidth
+            value={section}
+            onValueChange={setSection}
+            aria-label="Раздел настроек"
+          >
+            {SECTIONS.map((item) => (
+              <SegmentedControl.Item key={item.value} value={item.value}>
+                {item.label}
+              </SegmentedControl.Item>
+            ))}
+          </SegmentedControl.Root>
+        </PageToolbar.Sections>
+        <PageToolbar.Actions>
+          <Button.Root variant="ghost" tone="neutral">
+            Отменить
+          </Button.Root>
+          <Button.Root type="submit">Сохранить {CHANGES} изменения</Button.Root>
+        </PageToolbar.Actions>
+      </PageToolbar.Root>
+    </form>
   );
 }