prime-ui-kit 0.16.0 → 0.18.0

package/dist/skill/reference/{components/page-toolbar/examples/narrow.tsx → layout/page/examples/tools.tsx}

@@ -1,8 +1,8 @@
-/** 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`. */
+/** The orders page's tools in its top bar: sections with counts, search and filter, the period, in the order written; the active filters on a line under everything — `Page.Tools`, `Page.Chips`. */
 import {
   Button,
   Icon,
-  PageToolbar,
+  Page,
   SegmentedControl,
   Select,
   SmartFilter,
@@ -11,17 +11,17 @@ import {
 } 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 },
+  { value: "cancelled", label: "Отменены", count: 20 },
 ];
 
 const PERIODS = [
   { value: "7d", label: "7 дней" },
   { value: "30d", label: "30 дней" },
+  { value: "quarter", label: "Квартал" },
 ];
 
 const FIELDS: SmartFilterField[] = [
@@ -31,38 +31,42 @@ const FIELDS: SmartFilterField[] = [
     options: [
       { value: "msk", label: "Москва" },
       { value: "spb", label: "Санкт-Петербург" },
+      { value: "kzn", label: "Казань" },
+    ],
+  },
+  {
+    key: "payment",
+    label: "Оплата",
+    options: [
+      { value: "card", label: "Картой" },
+      { value: "invoice", label: "По счёту" },
     ],
   },
 ];
 
-export default function PageToolbarNarrowExample() {
+export default function PageToolsExample() {
   const [section, setSection] = React.useState("all");
-  const [period, setPeriod] = React.useState("7d");
+  const [period, setPeriod] = React.useState("30d");
   const [filter, setFilter] = React.useState<SmartFilterValue>({
     city: { include: ["msk"], exclude: [] },
   });
   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.Tools>
-            <SmartFilter.Toolbar />
-          </PageToolbar.Tools>
-          <PageToolbar.Sections>
-            <SegmentedControl.Root
-              fullWidth
-              value={section}
-              onValueChange={setSection}
-              aria-label="Раздел"
-            >
+    <SmartFilter.Root
+      fields={FIELDS}
+      value={filter}
+      onValueChange={setFilter}
+      search={search}
+      onSearchChange={setSearch}
+    >
+      <Page.Root>
+        <Page.TopBar sticky={false}>
+          <Page.Heading>
+            <Page.Title>Заказы</Page.Title>
+          </Page.Heading>
+          <Page.Tools aria-label="Заказы">
+            <SegmentedControl.Root value={section} onValueChange={setSection} aria-label="Раздел">
               {SECTIONS.map((item) => (
                 <SegmentedControl.Item key={item.value} value={item.value}>
                   {item.label}
@@ -70,8 +74,7 @@ export default function PageToolbarNarrowExample() {
                 </SegmentedControl.Item>
               ))}
             </SegmentedControl.Root>
-          </PageToolbar.Sections>
-          <PageToolbar.View>
+            <SmartFilter.Toolbar />
             <Select.Root value={period} onValueChange={setPeriod}>
               <Select.Trigger aria-label="Период">
                 <Select.TriggerIcon>
@@ -87,20 +90,20 @@ export default function PageToolbarNarrowExample() {
                 ))}
               </Select.Content>
             </Select.Root>
-          </PageToolbar.View>
-          <PageToolbar.Actions>
+          </Page.Tools>
+          <Page.Actions>
             <Button.Root>
               <Button.Icon>
                 <Icon name="action.add" />
               </Button.Icon>
               Новый заказ
             </Button.Root>
-          </PageToolbar.Actions>
-          <PageToolbar.Chips>
+          </Page.Actions>
+          <Page.Chips>
             <SmartFilter.Chips />
-          </PageToolbar.Chips>
-        </PageToolbar.Root>
-      </SmartFilter.Root>
-    </div>
+          </Page.Chips>
+        </Page.TopBar>
+      </Page.Root>
+    </SmartFilter.Root>
   );
 }

package/dist/skill/reference/layout/page/examples/top-bar.tsx

@@ -0,0 +1,85 @@
+/** A nested record in the top bar: the path ending in the title, a line of data, the page's tools and its buttons — `Page.TopBar`, `Page.Heading`, `Page.Tools`, `Page.Actions`. */
+import { Breadcrumb, Button, Icon, Input, Page, SegmentedControl } from "prime-ui-kit";
+import * as React from "react";
+
+const SECTIONS = [
+  { value: "all", label: "Все" },
+  { value: "mine", label: "Мои" },
+  { value: "overdue", label: "Просрочены" },
+];
+
+const VIEWS = [
+  { value: "board", label: "Доска" },
+  { value: "list", label: "Список" },
+];
+
+export default function PageTopBarExample() {
+  const [section, setSection] = React.useState("all");
+  const [view, setView] = React.useState("board");
+  const [query, setQuery] = React.useState("");
+
+  return (
+    <Page.Root>
+      <Page.TopBar sticky={false}>
+        <Page.Heading>
+          <Breadcrumb.Root>
+            <Breadcrumb.Item href="#clients">Клиенты</Breadcrumb.Item>
+            <Breadcrumb.Item href="#north">ООО «Север»</Breadcrumb.Item>
+          </Breadcrumb.Root>
+          <Page.Title>Сделка № 2026-418</Page.Title>
+          <Page.Description>7 в работе · 6,5 млн ₽ · обновлено 9:40</Page.Description>
+        </Page.Heading>
+        <Page.Tools aria-label="Сделка № 2026-418">
+          <SegmentedControl.Root value={section} onValueChange={setSection} aria-label="Раздел">
+            {SECTIONS.map((item) => (
+              <SegmentedControl.Item key={item.value} value={item.value}>
+                {item.label}
+              </SegmentedControl.Item>
+            ))}
+          </SegmentedControl.Root>
+          <Input.Root>
+            <Input.Wrapper>
+              <Input.Icon side="start">
+                <Icon name="action.search" tone="secondary" />
+              </Input.Icon>
+              <Input.Field
+                type="search"
+                aria-label="Поиск по задачам"
+                placeholder="Поиск"
+                value={query}
+                onValueChange={setQuery}
+              />
+            </Input.Wrapper>
+          </Input.Root>
+          <SegmentedControl.Root value={view} onValueChange={setView} aria-label="Вид">
+            {VIEWS.map((item) => (
+              <SegmentedControl.Item key={item.value} value={item.value}>
+                {item.label}
+              </SegmentedControl.Item>
+            ))}
+          </SegmentedControl.Root>
+        </Page.Tools>
+        <Page.Actions>
+          <Button.Root variant="soft" tone="neutral">
+            <Button.Icon>
+              <Icon name="action.forward" />
+            </Button.Icon>
+            Поделиться
+          </Button.Root>
+          <Button.Root variant="soft" tone="neutral">
+            <Button.Icon>
+              <Icon name="action.download" />
+            </Button.Icon>
+            Экспорт
+          </Button.Root>
+          <Button.Root>
+            <Button.Icon>
+              <Icon name="action.add" />
+            </Button.Icon>
+            Новая сделка
+          </Button.Root>
+        </Page.Actions>
+      </Page.TopBar>
+    </Page.Root>
+  );
+}

package/dist/skill/reference/{components/page-content → layout/page}/examples/variants.tsx

@@ -1,5 +1,5 @@
-/** The same page column at three caps: the whole main, a wide dashboard column, a reading column — `maxWidth`. */
-import { Card, PageContent, Typography } from "prime-ui-kit";
+/** The same page at three caps: the whole main, a wide dashboard column, a reading column — `maxWidth`. */
+import { Card, Page, Typography } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
 
@@ -9,13 +9,13 @@ const WIDTHS = [
   { value: "readable", text: "Условия использования: не шире колонки для чтения, по центру." },
 ] as const;
 
-export default function PageContentVariantsExample() {
+export default function PageVariantsExample() {
   return (
     <>
       {WIDTHS.map(({ value, text }) => (
         <div key={value} className={styles.main}>
-          <PageContent.Root maxWidth={value}>
-            <PageContent.Body>
+          <Page.Root maxWidth={value}>
+            <Page.Body>
               <Card.Root>
                 <Card.Body>
                   <Typography variant="body-s" tone="secondary">
@@ -23,8 +23,8 @@ export default function PageContentVariantsExample() {
                   </Typography>
                 </Card.Body>
               </Card.Root>
-            </PageContent.Body>
-          </PageContent.Root>
+            </Page.Body>
+          </Page.Root>
         </div>
       ))}
     </>

package/dist/skill/reference/layout/sidebar/COMPONENT.md

@@ -89,7 +89,7 @@ useSidebar()                       state hook for custom parts inside Root (useA
 | `onModeChange` | `(mode: SidebarMode) => void` | — | Called with the new mode (Toggle, `useSidebar().setMode`). |
 | `open` | `boolean` | — | Off-canvas panel on narrow viewports (controlled). |
 | `defaultOpen` | `boolean` | `false` | Initial off-canvas state (uncontrolled). |
-| `onOpenChange` | `(open: boolean) => void` | — | Off-canvas open / close: Toggle, the AppHeader menu button, scrim, Escape, an activated item, leaving the narrow viewport. |
+| `onOpenChange` | `(open: boolean) => void` | — | Off-canvas open / close: Toggle, the menu button of `Page.TopBar`, scrim, Escape, an activated item, leaving the narrow viewport. |
 | `offCanvas` | `"auto" \| "always" \| "never"` | `"auto"` | When the rail becomes an off-canvas panel opened by `open`: `auto` — below 768px (viewport); `always` — at any width; `never` — always a rail. |
 | `closeOnOutsideClick` | `boolean` | `true` | A press on the scrim (outside the off-canvas panel) closes the panel. |
 | `closeOnEscape` | `boolean` | `true` | Escape closes the off-canvas panel. |
@@ -294,13 +294,15 @@ The rail width does not depend on `size`.
 | `closeOnEscape` (Root) | Escape closes the off-canvas panel | default; turn off with `closeOnOutsideClick` for a panel only its toggle closes | on |
 | `asChild` (ItemAction) | the row action is the consumer's link with the button look | the action opens a page or `mailto:` | off |
 
-Put `<Sidebar.Toggle variant="header" />` next to `Sidebar.Brand` in the header, or `Sidebar.Toggle` in the footer for a rail without a brand. Inside an `AppShell` the Sidebar publishes its navigation to the shell: on phones (`offCanvas="auto"`) or always (`offCanvas="always"`) the `AppHeader` draws the menu button that opens the panel by itself, a `Sidebar.Toggle` outside the rail brings back a hidden one, and other triggers (a BottomNav «Ещё») read `useAppShellNav()`. One current item at a time; give every top-level item an icon when the rail can go compact (child items need none).
+Put `<Sidebar.Toggle variant="header" />` next to `Sidebar.Brand` in the header, or `Sidebar.Toggle` in the footer for a rail without a brand. Inside an `AppShell` the Sidebar publishes its navigation to the shell: on phones (`offCanvas="auto"`) or always (`offCanvas="always"`) the page's `Page.TopBar` draws the menu button that opens the panel by itself, a `Sidebar.Toggle` outside the rail brings back a hidden one, and other triggers (a BottomNav «Ещё») read `useAppShellNav()`. One current item at a time; give every top-level item an icon when the rail can go compact (child items need none).
 
 ## States
 | State | Driven by | DOM |
 |---|---|---|
+| held | a `Page.Guard` that is `busy` or `dirty` on the page | a press on `Sidebar.Item` or `Sidebar.Brand` stops before it navigates (a router link included) and the panel stays; `dirty` asks first, then repeats it |
 | mode | `mode` / `defaultMode` | Root `data-mode`, `data-panel-mode` (the last visible mode while hidden); `<nav inert>` while hidden |
 | off-canvas | `offCanvas="always"`, or `"auto"` + viewport < 768px | Root `data-off-canvas`, `data-state="open" \| "closed"`; `<nav inert>` while closed; the kit scrim (`role="presentation"`) while open; in an `AppShell` the shell Root `data-off-canvas` |
+| placing | the viewport crossed the off-canvas breakpoint (not a person's choice) | Root `data-placing` for one painted frame: the rail lands at its new width with no motion (no growing from 0, no folding rows, no sliding panel) |
 | dismiss | `closeOnOutsideClick`, `closeOnEscape` | a press on the scrim / Escape closes the open panel, or not |
 | current | `current` or a router's `aria-current` | Item `aria-current="page"`, `data-state="active"` |
 | active path | a child of a Sub (or an item of a Group) is current | SubTrigger (or the `…` row of a folded Group) `data-active-path`; a closed Sub opens, a closed Group opens off the compact rail |
@@ -364,7 +366,7 @@ Leaving the narrow viewport closes the off-canvas panel; activating an item (a l
 - A row action is its own button next to the item (never nested), named by `label` with a tooltip.
 - The account avatar is hidden from screen readers; the name and the muted line name the button.
 - Off-canvas: a decorative scrim (a press on it is a press outside, `closeOnOutsideClick`), focus trap and Escape (`closeOnEscape`); focus returns to the opener.
-- Toggle, the AppHeader menu button and `useAppShellNav` triggers: `aria-expanded`, `aria-controls` → the `<nav>`, label from `labels`.
+- Toggle, the menu button of `Page.TopBar` and `useAppShellNav` triggers: `aria-expanded`, `aria-controls` → the `<nav>`, label from `labels`.
 
 ### Labels
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
@@ -392,7 +394,7 @@ Leaving the narrow viewport closes the off-canvas panel; activating an item (a l
 | [dismiss.tsx](examples/dismiss.tsx) | An off-canvas panel only its own toggle closes: a press on the scrim and Escape leave it open, a picked item still closes it — `closeOnOutsideClick`, `closeOnEscape`. |
 | [controlled.tsx](examples/controlled.tsx) | The parent owns the rail mode: expanded, an icon rail with tooltips, or hidden; every switch is one synchronous movement — `mode`, `onModeChange`. |
 | [controlled-open.tsx](examples/controlled-open.tsx) | Navigation behind a menu button at any width: the parent opens the off-canvas panel, the scrim, Escape, the header toggle or a navigation closes it — `offCanvas`, `open`, `onOpenChange`. |
-| [narrow.tsx](examples/narrow.tsx) | Below 768px the rail leaves the layout and slides in over the page from the menu button the header draws by itself; from 768px it is the rail again, and the button leaves — `AppShell`, `labels`. |
+| [narrow.tsx](examples/narrow.tsx) | Below 768px the rail leaves the layout and slides in over the page from the menu button the page top bar draws by itself; from 768px it is the rail again, and the button leaves — `AppShell`, `labels`. |
 
 ## Mistakes
 - `icon={…}` / `badge={…}` props → use the `Sidebar.ItemIcon` and `Sidebar.ItemCount` parts.

package/dist/skill/reference/layout/sidebar/examples/dismiss.tsx

@@ -1,5 +1,5 @@
 /** An off-canvas panel only its own toggle closes: a press on the scrim and Escape leave it open, a picked item still closes it — `closeOnOutsideClick`, `closeOnEscape`. */
-import { AppHeader, AppShell, Icon, Sidebar } from "prime-ui-kit";
+import { AppShell, Icon, Page, Sidebar } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
 
@@ -35,12 +35,15 @@ export default function SidebarDismissExample() {
             </Sidebar.Content>
           </Sidebar.Root>
         </AppShell.Nav>
-        <AppHeader.Root>
-          <AppHeader.Start>
-            <AppHeader.Title>Сборка заказов</AppHeader.Title>
-          </AppHeader.Start>
-        </AppHeader.Root>
-        <AppShell.Main />
+        <AppShell.Main>
+          <Page.Root>
+            <Page.TopBar>
+              <Page.Heading>
+                <Page.Title>Сборка заказов</Page.Title>
+              </Page.Heading>
+            </Page.TopBar>
+          </Page.Root>
+        </AppShell.Main>
       </AppShell.Root>
     </div>
   );

package/dist/skill/reference/layout/sidebar/examples/narrow.tsx

@@ -1,5 +1,5 @@
-/** Below 768px the rail leaves the layout and slides in over the page from the menu button the header draws by itself; from 768px it is the rail again, and the button leaves — `AppShell`, `labels`. */
-import { AppHeader, AppShell, Icon, Sidebar } from "prime-ui-kit";
+/** Below 768px the rail leaves the layout and slides in over the page from the menu button the page top bar draws by itself; from 768px it is the rail again, and the button leaves — `AppShell`, `labels`. */
+import { AppShell, Icon, Page, Sidebar } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
 
@@ -43,12 +43,15 @@ export default function SidebarNarrowExample() {
             </Sidebar.Content>
           </Sidebar.Root>
         </AppShell.Nav>
-        <AppHeader.Root>
-          <AppHeader.Start>
-            <AppHeader.Title>Сделки</AppHeader.Title>
-          </AppHeader.Start>
-        </AppHeader.Root>
-        <AppShell.Main />
+        <AppShell.Main>
+          <Page.Root>
+            <Page.TopBar>
+              <Page.Heading>
+                <Page.Title>Сделки</Page.Title>
+              </Page.Heading>
+            </Page.TopBar>
+          </Page.Root>
+        </AppShell.Main>
       </AppShell.Root>
     </div>
   );

package/dist/skill/responsive.md

@@ -38,7 +38,7 @@ everything inside a page breaks by its container.
 - CSS custom properties cannot be used inside media / container conditions: write the number.
 - Inside your own blocks prefer container queries: `container-type: inline-size` on the block,
   `@container (min-width: 30rem)` inside it.
-- The app takes the full width; cap only text (`PageContent.Root maxWidth="readable"`).
+- The app takes the full width; cap only text (`Page.Root maxWidth="readable"`).
 - Required minimum: `<meta name="viewport" content="width=device-width, initial-scale=1">`, no
   `user-scalable=no`, no horizontal page scroll at 320px.
 
@@ -46,9 +46,10 @@ everything inside a page breaks by its container.
 
 A layout inside a page needs no breakpoint: it takes its columns from the room it has.
 
-- The tiles of a page (KPI cards, charts, panels) are one `PageContent.Grid` with a
-  `PageContent.Cell span` per tile: it folds by its own width (below 30rem every tile takes the row,
-  then small tiles pair up, from 64rem each its span).
+- The tiles of a page (KPI cards, charts, panels) are one `Page.Grid` with a
+  `Page.Cell span` per tile: it folds by its own width (below 30rem every tile takes the row,
+  then small tiles pair up, from 64rem each its span). Write a wide tile (`span` 7–11) next to a
+  narrow one (4–5): between 40 and 64rem the two pair up as 2/3 + 1/3, so an 8 + 4 row keeps no hole.
 - A grid inside one block (thumbnails, short fields of one record) is the block's own
   `grid-template-columns: repeat(auto-fill, minmax(min(100%, var(--prime-layout-tile-min-width)), 1fr))`
   — `auto-fill`, so a lone item keeps its column width instead of stretching across the row.
@@ -61,43 +62,49 @@ Use these as they are; never wrap them in your own breakpoints.
 
 | Need | Built in |
 |---|---|
-| app frame | AppShell gutters 16 → 24 → 32; `AppHeader` un-sticks on screens lower than 480px, respects safe areas and, below 36rem of its width, drops the title icon, the title and its line of data truncate |
-| app navigation | Sidebar: on-canvas from 768px, an off-canvas panel below (`offCanvas="auto"`) opened by the menu button the AppHeader draws by itself while the Sidebar is off-canvas; `BottomNav` in `AppShell.Footer` for 2–6 app sections on phones — flat or a floating glass capsule (`floating`) with an optional round `BottomNav.Action`, icons with or without labels (`iconOnly`); the shell hides it by itself while the Sidebar rail is on screen (from 768px with `offCanvas="auto"`) |
-| page panel | `PageToolbar` — search and filter first, one row when wide, stacked rows when narrow, the primary action on its own row when the search would get less than 18rem beside it ([below](#page-panel--pagetoolbar)) |
-| page header | `AppHeader`: the page's tools wrap under the title (`AppHeader.Tools`); a document page's `PageContent.Header`: actions wrap under the title |
+| app frame | `AppShell.Main` hands the page its gutters 16 → 24 → 32, top air 24 → 32 and bottom air 64 (the gutter under a `fill` page; above a floating BottomNav it keeps the capsule's room); `Page.TopBar` un-sticks on screens lower than 480px and respects the top safe area |
+| app navigation | Sidebar: on-canvas from 768px, an off-canvas panel below (`offCanvas="auto"`) opened by the menu button `Page.TopBar` draws by itself while the Sidebar is off-canvas; `BottomNav` in `AppShell.Footer` for 2–6 app sections on phones — flat or a floating glass capsule (`floating`) with an optional round `BottomNav.Action`, icons with or without labels (`iconOnly`); the shell hides it by itself while the Sidebar rail is on screen (from 768px with `offCanvas="auto"`) |
+| page top bar | `Page.TopBar` lays out its groups from their natural widths: one line while they fit, then the tools on a line of their own, then icon-only buttons, then «⋯», and the heading gives last ([below](#the-pages-top-bar--pagetopbar)). `Page.Header` in the flow: actions wrap under the title |
 | switchers | [Switchers](#switchers) never wrap or truncate: they scroll inside themselves |
 | tables | DataTable scrolls inside itself, edge shadows show hidden columns, `stickyFirstColumn`, `DataTable.ColumnsMenu` for a column chooser, the toolbar stacks below a 30rem table, sticky head off on short screens |
 | floating layers | Popover (opened from a Trigger), Dropdown, Select (and Datepicker, ColorPresets) never wider than the viewport − 16, 8 from the edges, flip when out of room; below 640 they open as a bottom sheet — scrim, grab handle, swipe down to close, page scroll locked; Tooltip and TagSelect stay anchored |
 | dialogs | Modal is a bottom sheet with a handle below 640 (swipe down closes it while `closeOnOutsideClick` allows); footer actions stack on phones and in a dialog narrower than 360px; `Sheet` is a bottom sheet for a short task at every width (centred at 560 on a tablet or desktop) and closes with a swipe down from its handle or header; a Drawer has no swipe — buttons, Escape and the scrim close it |
 | date picking | Datepicker shows two months and side presets only when they fit; otherwise one month and presets above |
 | system messages | Banner actions move under the text in a narrow container; Notification stays within the viewport with safe-area insets |
-| chat | `Message` bubbles fit their content in CSS and cap at 30rem and 85% of the chat column, file / contact / location cards at 16rem and 75%, a round video at its size token × 1.15 and the row width (the Composer's recording preview at 70%), so a chat works from 320px; the message menu is a bottom sheet below 640, the reaction bar opens on a long press; `Composer` takes its container's width, keeps 16px text and 44px hit areas on touch, and the recording bar covers the field without changing the row height; `VoicePlayer` shrinks its waveform to fit; `Chat` fills its pane, a chat beside its dialogs is `PageContent.Split` (one pane at a time when narrow); `Chat.Header` keeps the avatar, a title that truncates and icon-only actions, `Chat.Search` puts its counter and arrows after a shrinking field, `Chat.Pinned` truncates its line, the «к последним» button floats inside the thread at its bottom-end, and the Composer stays one row (paperclip · field · button) from 320px with its bars above it |
+| chat | `Message` bubbles fit their content in CSS and cap at 30rem and 85% of the chat column, file / contact / location cards at 16rem and 75%, a round video at its size token × 1.15 and the row width (the Composer's recording preview at 70%), so a chat works from 320px; the message menu is a bottom sheet below 640, the reaction bar opens on a long press; `Composer` takes its container's width, keeps 16px text and 44px hit areas on touch, and the recording bar covers the field without changing the row height; `VoicePlayer` shrinks its waveform to fit; `Chat` fills its pane, a chat beside its dialogs is `Page.Split` (one pane at a time when narrow); `Chat.Header` keeps the avatar, a title that truncates and icon-only actions, `Chat.Search` puts its counter and arrows after a shrinking field, `Chat.Pinned` truncates its line, the «к последним» button floats inside the thread at its bottom-end, and the Composer stays one row (paperclip · field · button) from 320px with its bars above it |
 | schedules and boards | `Gantt` scrolls inside itself with the header and the first column pinned; the first column narrows (12 → 10 → 6rem by the chart's width, or only the avatar); a long press on touch creates a one-unit bar; rows and days are virtualized. `Kanban` columns are 18rem from 40rem of board width, below that 85% of it with snapping so the next column peeks; the strip scrolls sideways inside the board |
 | cards and properties | Card templates stack and wrap in a narrow container; `DescriptionList` stacks label over value below 24rem of its width; FileUpload `layout="grid"` shows 5 · 4 · 3 · 2 tiles across by its own width |
 | fields | text ≥ 16px under a coarse pointer (no iOS zoom on focus); labels above fields; affixes in the field row |
 | codes | DigitInput cells 36–64px, `fullWidth` cells share a phone column |
 | touch | hover effects only under `(hover: hover)`; under `(pointer: coarse)` small controls get a 44px hit area; nothing is hover-only |
 
-## Page panel — `PageToolbar`
+## The page's top bar — `Page.TopBar`
 
-One strip at the top of the page — on an app page, the page's tools row in `AppHeader.Tools` — holds
-up to five slots. It renders them in one fixed order whatever the JSX order (that is also the Tab
-order) and lays them out from its own width; how each slot moves at every width is in
-[PageToolbar COMPONENT.md → Layout by width](reference/components/page-toolbar/COMPONENT.md#layout-by-width).
+The bar holds up to four groups ([what goes in each](composition.md#the-top-bar)) and lays them out
+by one plan chosen from their natural widths. As the width runs out it gives way in five steps, always
+in this order, and nothing ever overflows:
 
-| Slot | Holds |
-|---|---|
-| `PageToolbar.Tools` | search + filter button: `SmartFilter.Toolbar` |
-| `PageToolbar.Sections` | sections of the page: a `fullWidth` SegmentedControl with counts |
-| `PageToolbar.View` | period, table / cards, columns |
-| `PageToolbar.Actions` | the primary action («Создать», «Сохранить 3 изменения») |
-| `PageToolbar.Chips` | active filters: `SmartFilter.Chips` |
+1. **One line** — `Page.Heading`, `Page.Tools` and `Page.Actions` side by side while they fit.
+2. **Tools below** — the tools take a line of their own under the first one and fill its width: a
+   search (`SmartFilter.Toolbar`, `Input.Root`) grows first, the switchers and a period
+   (`Datepicker.Root`) share the rest and wrap when one line is not enough. Beside a search that
+   would get too little room the SmartFilter button shows only its icon and count, on the same row.
+   The actions stay on the first line beside the heading at every width.
+3. **Icons** — every Button with an icon shows only the icon, the secondary ones first, then the
+   primary; its label stays its accessible name and becomes its tooltip.
+4. **«⋯»** — the secondary Buttons fold into a menu (`labels.more`); the primary always stays.
+5. **The heading gives** — only after every button step: the middle levels of the path fold into
+   «…»; a heading with a path that still does not fit stacks (the path on its own line over the
+   title, the title and its description wrapping), so no level is cut to a fragment; a heading without a path truncates.
+
+`Page.Chips` is always a line of its own under everything, gone while no filter is set. The heading
+keeps its natural width: the bar sizes the title, so there is nothing to tune.
 
 ```tsx
 import {
   Button,
   Icon,
-  PageToolbar,
+  Page,
   SegmentedControl,
   Select,
   SmartFilter,
@@ -110,7 +117,7 @@ const FIELDS: SmartFilterField[] = [
   { key: "city", label: "Город", options: [{ value: "msk", label: "Москва" }] },
 ];
 
-export function OrdersPanel() {
+export function OrdersPage() {
   const [section, setSection] = useState("all");
   const [period, setPeriod] = useState("30d");
   const [filter, setFilter] = useState<SmartFilterValue>({});
@@ -124,63 +131,75 @@ export function OrdersPanel() {
       search={search}
       onSearchChange={setSearch}
     >
-      <PageToolbar.Root aria-label="Заказы">
-        <PageToolbar.Tools>
-          <SmartFilter.Toolbar />
-        </PageToolbar.Tools>
-        <PageToolbar.Sections>
-          <SegmentedControl.Root fullWidth value={section} onValueChange={setSection} aria-label="Раздел">
-            <SegmentedControl.Item value="all">
-              Все<SegmentedControl.Count>128</SegmentedControl.Count>
-            </SegmentedControl.Item>
-            <SegmentedControl.Item value="active">
-              В работе<SegmentedControl.Count>12</SegmentedControl.Count>
-            </SegmentedControl.Item>
-          </SegmentedControl.Root>
-        </PageToolbar.Sections>
-        <PageToolbar.View>
-          <Select.Root value={period} onValueChange={setPeriod}>
-            <Select.Trigger aria-label="Период">
-              <Select.Value />
-            </Select.Trigger>
-            <Select.Content>
-              <Select.Item value="7d">7 дней</Select.Item>
-              <Select.Item value="30d">30 дней</Select.Item>
-            </Select.Content>
-          </Select.Root>
-        </PageToolbar.View>
-        <PageToolbar.Actions>
-          <Button.Root>
-            <Button.Icon>
-              <Icon name="action.add" />
-            </Button.Icon>
-            Новый заказ
-          </Button.Root>
-        </PageToolbar.Actions>
-        <PageToolbar.Chips>
-          <SmartFilter.Chips />
-        </PageToolbar.Chips>
-      </PageToolbar.Root>
+      <Page.Root>
+        <Page.TopBar>
+          <Page.Heading>
+            <Page.Title>Заказы</Page.Title>
+            <Page.Description>128 в работе · 6 ждут оплаты</Page.Description>
+          </Page.Heading>
+          <Page.Tools aria-label="Заказы">
+            <SegmentedControl.Root value={section} onValueChange={setSection} aria-label="Раздел">
+              <SegmentedControl.Item value="all">
+                Все<SegmentedControl.Count>128</SegmentedControl.Count>
+              </SegmentedControl.Item>
+              <SegmentedControl.Item value="active">
+                В работе<SegmentedControl.Count>12</SegmentedControl.Count>
+              </SegmentedControl.Item>
+            </SegmentedControl.Root>
+            <SmartFilter.Toolbar />
+            <Select.Root value={period} onValueChange={setPeriod}>
+              <Select.Trigger aria-label="Период">
+                <Select.Value />
+              </Select.Trigger>
+              <Select.Content>
+                <Select.Item value="7d">7 дней</Select.Item>
+                <Select.Item value="30d">30 дней</Select.Item>
+              </Select.Content>
+            </Select.Root>
+          </Page.Tools>
+          <Page.Actions>
+            <Button.Root variant="soft" tone="neutral">
+              <Button.Icon>
+                <Icon name="action.download" />
+              </Button.Icon>
+              Экспорт
+            </Button.Root>
+            <Button.Root>
+              <Button.Icon>
+                <Icon name="action.add" />
+              </Button.Icon>
+              Новый заказ
+            </Button.Root>
+          </Page.Actions>
+          <Page.Chips>
+            <SmartFilter.Chips />
+          </Page.Chips>
+        </Page.TopBar>
+        <Page.Body>{/* the orders table */}</Page.Body>
+      </Page.Root>
     </SmartFilter.Root>
   );
 }
 ```
 
-- One tier for the whole panel (default `m`): never `size` on one control inside — wrapped rows must
-  stay level. A denser page wraps the toolbar in `<ControlSizeProvider value="s">`; every kit control
+- One tier for the whole bar (default `m`): never `size` on one control inside — wrapped lines must
+  stay level. A denser page wraps the bar in `<ControlSizeProvider value="s">`; every kit control
   inside takes that tier.
-- The primary action is always there: on a phone it may take its own row or become icon-only with
-  `aria-label`; it never disappears.
+- A Button without an icon keeps its label at every step and leaves the bar less room before it
+  folds: give each one a `Button.Icon`.
+- A SegmentedControl or a Datepicker in `Page.Tools` needs no `fullWidth`: the bar sets it.
+- The primary action is on screen at every width — as its icon at the narrowest; it never folds and
+  never disappears.
 - Section totals go into `SegmentedControl.Count`, not into stat cards above the table.
-- A long form saves through the panel's action with a count («Сохранить 3 изменения»), never a sticky
-  bar at the bottom of a phone screen.
-- Do not duplicate search: if the panel has one, the list below filters by it.
+- A long form saves through the bar's primary action with a count («Сохранить 3 изменения»), never a
+  sticky bar at the bottom of a phone screen.
+- Do not duplicate search: if the bar has one, the list below filters by it.
 
 ## Switchers
 
-- **Three width modes:** by content (`fullWidth` off), full width (`fullWidth`), full width only when
-  narrow (a `fullWidth` SegmentedControl inside `PageToolbar.Sections` — the toolbar decides).
-- Sections of a page → SegmentedControl in `PageToolbar.Sections`; panels inside a card or a section →
+- **Three width modes:** by content (`fullWidth` off), full width (`fullWidth`), full width only on
+  a line of its own (a SegmentedControl in `Page.Tools` — the bar decides).
+- Sections of a page → SegmentedControl in `Page.Tools`; panels inside a card or a section →
   Tabs (the folder look belongs to its panel).
 - Every switcher — Tabs, SegmentedControl, a horizontal ButtonGroup and BottomNav — scrolls inside
   itself when its items do not fit: never a second line, never a truncated item. Its hidden edges
@@ -195,9 +214,9 @@ export function OrdersPanel() {
 
 ## List + details, side panels
 
-- A list people work through record by record (mail, a messenger, tickets) is `PageContent.Split`:
-  the list in a 16–20rem column with the details beside it from 48rem of the split's own width, one
-  pane at a time with `PageContent.BackButton` below it. Details opened now and then from a table
+- A list people work through record by record (mail, a messenger, tickets) is `Page.Split`:
+  the list (`Page.List`) in a 16–20rem column with the details (`Page.Detail`) beside it from 48rem
+  of the split's own width, one pane at a time with `Page.BackButton` below it. Details opened now and then from a table
   open in a Drawer.
 - A side panel of details becomes full-screen on a phone (`Drawer.Content` is full width below 640).
 - Its period / view controls stay visible on every tab of the panel.
@@ -205,7 +224,7 @@ export function OrdersPanel() {
 ## Components on narrow widths — what you still decide
 
 **Tables.** Let DataTable scroll inside itself; offer a column chooser (`DataTable.ColumnsMenu` in
-`toolbar`; the key column `hideable: false`); `stickyFirstColumn` for the name. On phones a table / cards switch in `PageToolbar.View` is fine — silently dropping columns
+`toolbar`; the key column `hideable: false`); `stickyFirstColumn` for the name. On phones a table / cards switch in `Page.Tools` is fine — silently dropping columns
 by breakpoint is not. Never ask to rotate the phone.
 
 **Card grids.** [Intrinsic grids](#intrinsic-grids), never a breakpoint. Tiles of a row share one
@@ -257,7 +276,7 @@ Target CLS ≤ 0.1: nothing moves while loading or when a filter changes.
 Drag the window through 320, 390, 768, 1024, 1280 and 1920px — continuously, not only at these points.
 
 - [ ] No horizontal page scroll at any width (tables and switchers scroll inside themselves).
-- [ ] The primary action is on screen at every width — never hidden ([the page panel](#page-panel--pagetoolbar)).
+- [ ] The primary action is on screen at every width — never hidden ([the page's top bar](#the-pages-top-bar--pagetopbar)).
 - [ ] Every item alone in its row stretches; items of stretched switchers are equal.
 - [ ] All controls in a row share one height; no «staircase» after a wrap.
 - [ ] Text never overlaps and is cut only at its own block's edge; cut text has a tooltip or `title`.