prime-ui-kit 0.14.0 → 0.16.0

package/dist/skill/reference/layout/app-header/COMPONENT.md

@@ -3,18 +3,18 @@
 **Category:** page
 **Kind:** layout
 
-> The bar at the top of the app's content panel: where you are, global search and a few actions.
+> The page's bar at the top of the app's content panel: the page title with a line of data, the page's tools and its own buttons — only what the current page needs.
 
 ## When to use
-- The top row of an app built on [AppShell](../app-shell/COMPONENT.md): the section title or the path, the ⌘K search entry, notifications, the account, one primary action.
-- The phone header: the menu button that opens the off-canvas Sidebar, the title, search as an icon.
-- A page without its own heading row in main (a board, a chat, a dense register): the header carries the page title (`AppHeader.Title as="h1"`) and the page tools (`AppHeader.Tools` with a PageToolbar).
+- Every page of an app built on [AppShell](../app-shell/COMPONENT.md): the page titles itself here — `AppHeader.Title` (the page's `<h1>`) with an `AppHeader.Description` that carries data, the path up (`Breadcrumb`) on a nested record.
+- The page's tools — its own search and filter, sections, the view, the primary action — as a [PageToolbar](../../components/page-toolbar/COMPONENT.md) in `AppHeader.Tools`.
+- The phone header: in an `AppShell` whose Sidebar is off-canvas the header leads with the menu button that opens it by itself; the title and the page's action as an icon follow.
+- A page that owns its header: render `AppHeader.Root` at the top of the page — inside the shell it renders in the shell's header row and replaces `AppShell.Template`'s `header` while the page is on screen.
 
 ## When not to use
-- A page that has its heading, description and page actions in main → use [PageContent](../../components/page-content/COMPONENT.md) (`PageContent.Title` is the `<h1>`); then the header title stays a plain name.
-- Tabs, filters and search for the data on the page while the page has its own heading in main → put the [PageToolbar](../../components/page-toolbar/COMPONENT.md) in main, not in `AppHeader.Tools`.
-- App navigation → use [Sidebar](../sidebar/COMPONENT.md) and, on a phone, [BottomNav](../bottom-nav/COMPONENT.md); the header holds at most the menu button.
-- The search dialog itself → use [CommandMenu](../../components/command-menu/COMPONENT.md); `AppHeader.Search` only opens it.
+- A document page (settings, a long form, an article) → its title is `PageContent.Header` in main ([PageContent](../../components/page-content/COMPONENT.md)); the header then has no title.
+- App navigation → [Sidebar](../sidebar/COMPONENT.md) and, on a phone, [BottomNav](../bottom-nav/COMPONENT.md); the header holds at most the menu button.
+- Anything that is not about the current page (a global search, app-wide buttons) → the header row is per page; the app's own places live in the Sidebar.
 
 ## Import
 ```tsx
@@ -23,44 +23,43 @@ import { AppHeader } from "prime-ui-kit";
 
 ## Anatomy
 ```
-AppHeader.Root               <header>, one sticky row as high as the Sidebar brand row
+AppHeader.Root               <header>, the page's sticky bar; in an AppShell it renders in the shell's header row
 ├─ AppHeader.Start           leading zone, takes the free width
-│  ├─ AppHeader.MenuButton   opens the off-canvas Sidebar (below 768px by default)
-│  ├─ AppHeader.Separator    short vertical line between groups (a back Button | a Breadcrumb)
-│  └─ AppHeader.Title        name, truncates (or a Breadcrumb instead)
+│  ├─ (menu button)          drawn while the shell's Sidebar is off-canvas; AppHeader.MenuButton places it elsewhere
+│  ├─ Breadcrumb             the path up, only on a nested record
+│  ├─ AppHeader.Separator    short vertical line between the path and the title
+│  └─ AppHeader.Title        the page title, truncates
 │     ├─ AppHeader.Icon      decorative glyph on a tile shaped like a soft button m
-│     └─ AppHeader.Description  muted caption under the name
-├─ AppHeader.Search          field-looking button that opens the CommandMenu
-├─ AppHeader.Actions         trailing buttons: notifications, account, primary action
-└─ AppHeader.Tools           second row, full width: the page tools (a PageToolbar.Root)
+│     └─ AppHeader.Description  a muted line of data under the name
+├─ AppHeader.Actions         the page's own buttons at the end of the title row
+└─ AppHeader.Tools           second row, full width: the page's tools (a PageToolbar.Root)
 ```
-`AppHeader.Title as="h1"` makes the name (not the description) the page heading.
+The name of `AppHeader.Title` (not the icon or the description) is the page's `<h1>`.
 
 ## API
 
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
 ### AppHeader.Root
-`ref` → `HTMLElement`. The sticky `<header>` bar at the top of the content panel, one row as high as the Sidebar brand row and lined up with the page. Icon buttons inside are `soft`, not `ghost`.
+`ref` → `HTMLElement`. The page's sticky `<header>`: its title, tools and own buttons. In an `AppShell` it renders in the shell's header row and, while the Sidebar is off-canvas, leads with the menu button. Icon buttons inside are `soft`.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `labels` | `Partial<AppHeaderLabels>` | — | Built-in strings, see Labels. |
-| `…rest` | `HTMLAttributes<HTMLElement>` | — | `children` (`AppHeader.Start`, `AppHeader.Search`, `AppHeader.Actions`, `AppHeader.Tools`), `className` and the other attributes. |
+| `…rest` | `HTMLAttributes<HTMLElement>` | — | `children` (`AppHeader.Start`, `AppHeader.Actions`, `AppHeader.Tools`), `className` and the other attributes. |
 
 ### AppHeader.Start
-`ref` → `HTMLDivElement`. The leading zone that takes the free width: the menu button, a back button, the title or a Breadcrumb.
+`ref` → `HTMLDivElement`. The leading zone that takes the free width: the menu button, the path up (a Breadcrumb) and the title.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children`, `className` and the other div attributes. |
 
 ### AppHeader.Title
-`ref` → `HTMLDivElement`. Where you are: an optional `AppHeader.Icon`, the name (title-s, truncates) and an optional `AppHeader.Description` under it. Not a heading unless `as="h1"`.
+`ref` → `HTMLDivElement`. The page title: an optional `AppHeader.Icon`, the name (title-s, truncates) and an optional `AppHeader.Description` under it. The name is the page heading `<h1>`; the description stays outside its accessible name.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `as` | `"span" \| "h1"` | `"span"` | Tag of the name. `h1`: the header carries the page title — only the name is the heading, the description stays outside its accessible name; the look does not change. |
 | `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children` (the name, `AppHeader.Icon`, `AppHeader.Description` in any order), `className` and the other div attributes. |
 
 ### AppHeader.Icon
@@ -71,105 +70,88 @@ AppHeader.Root               <header>, one sticky row as high as the Sidebar bra
 | `…rest` | `HTMLAttributes<HTMLSpanElement>` | — | `children` (an `Icon`), `className` and the other span attributes. |
 
 ### AppHeader.Description
-`ref` → `HTMLSpanElement`. Muted caption under the title (a workspace, a period); hidden on a narrow header.
+`ref` → `HTMLSpanElement`. Muted line under the title that carries data («128 в работе · 6 ждут оплаты», a status and a date); truncates on a narrow header, never hides.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `…rest` | `HTMLAttributes<HTMLSpanElement>` | — | `children`, `className` and the other span attributes. |
 
 ### AppHeader.Separator
-`ref` → `HTMLDivElement`. A short vertical `Divider` (20) between groups in a zone — a back button and the path — with 16 of air on each side.
+`ref` → `HTMLDivElement`. The `inset` vertical `Divider` between groups in a zone — the path and the title: one text line tall, the tier gap on each side.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `…rest` | `Omit<DividerProps, "orientation" \| "children">` | — | `className` and the other div attributes. |
-
-### AppHeader.Search
-`ref` → `HTMLButtonElement`. The global search entry: a `<button type="button">` drawn as a field (search icon, placeholder text, key hint) that opens your CommandMenu. Below 36rem of header width it folds into a square button named by its text.
-
-| Prop | Type | Default | Description |
-|---|---|---|---|
-| `children` | `ReactNode` | — (required) | The placeholder text; also the accessible name. |
-| `shortcut` | `ReactNode` | `"⌘K"` | The key hint at the end (a `Kbd`, hidden from assistive tech); `null` hides it. Bind the key yourself. |
-| `…rest` | `ButtonHTMLAttributes<HTMLButtonElement>` | — | `onClick`, `className` and the other button attributes. |
+| `…rest` | `Omit<DividerProps, "orientation" \| "children" \| "align" \| "size" \| "inset">` | — | `className` and the other div attributes. |
 
 ### AppHeader.Tools
-`ref` → `HTMLDivElement`. The page's tools in the header (a `PageToolbar.Root`): the header's second row, full width under the title row, wherever it is written.
+`ref` → `HTMLDivElement`. The page's tools in the header (a `PageToolbar.Root`): the header's second row, full width under the title row, wherever it is written in `AppHeader.Root` — directly, in a fragment or inside a component of the page.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children` (a `PageToolbar.Root`), `className` and the other div attributes. |
 
 ### AppHeader.Actions
-`ref` → `HTMLDivElement`. The trailing row of buttons: notifications, the account, one primary action. Never wraps.
+`ref` → `HTMLDivElement`. The trailing row of the page's own buttons in the title row (export, a more menu); the page's primary action goes into the PageToolbar in `AppHeader.Tools` when the page has tools. Never wraps.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children`, `className` and the other div attributes. |
 
 ### AppHeader.MenuButton
-`ref` → `HTMLButtonElement`. A soft neutral icon `Button` named by `labels.menu` that opens the off-canvas Sidebar; wire `onClick` and `aria-expanded`.
+`ref` → `HTMLButtonElement`. The menu button the header draws by itself, placed elsewhere: a soft icon `Button` named by `labels.menu` that opens the shell's off-canvas Sidebar. Nothing while the Sidebar is a rail, or outside a shell.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `show` | `"narrow" \| "always"` | `"narrow"` | `narrow` — only below 768px, where a Sidebar with `offCanvas="auto"` leaves the layout; `always` — on every width (`offCanvas="always"`). |
-| `…rest` | `ButtonHTMLAttributes<HTMLButtonElement>` | — | `onClick`, `aria-expanded`, `aria-label` (replaces `labels.menu`), `className` and the other button attributes. |
+| `…rest` | `Omit<ButtonHTMLAttributes<HTMLButtonElement>, "type" \| "children" \| "aria-expanded" \| "aria-controls">` | — | `onClick` (runs first; `preventDefault()` stops the toggle), `aria-label` (replaces `labels.menu`), `className` and the other button attributes. |
 
 ## Variants
 
-### show (MenuButton)
-| Value | Looks like | Use when | Default |
-|---|---|---|---|
-| `narrow` | The menu button shows only below 768px | Sidebar with `offCanvas="auto"` | yes |
-| `always` | The menu button on every width | Sidebar with `offCanvas="always"`, or you decide visibility yourself | |
-
 ### Structure
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| `AppHeader.Title` | Icon, name and a caption under it, like the Sidebar brand | A top-level section | |
-| Breadcrumb in Start | A soft back button, `AppHeader.Separator` and the path | A nested record page | |
-| with `AppHeader.Search` | A field-looking button with a key hint between Start and Actions | The app has a CommandMenu | |
-| with `AppHeader.Actions` | A row of buttons at the end | Notifications, account, one primary action | |
-| with `AppHeader.Tools` | A second row under the title row with the page's PageToolbar | The header carries the page: no heading row in main | |
-
-### as (Title)
-| Value | Looks like | Use when | Default |
-|---|---|---|---|
-| `span` | the name, no heading | the page has `PageContent.Header` in main | yes |
-| `h1` | the same look; the name is the page `<h1>`, the description stays outside its name | the header carries the page title | |
+| `AppHeader.Title` | Icon, name and a line of data under it, like the Sidebar brand | A top-level page | |
+| Breadcrumb in Start | The path, `AppHeader.Separator` and the record as the title | A nested record page | |
+| with `AppHeader.Actions` | A row of the page's buttons at the end of the title row | Export, a more menu of the page | |
+| with `AppHeader.Tools` | A second row under the title row with the page's PageToolbar | The page has search, filters, sections, a view or a primary action | |
+| no `AppHeader.Title` | Only the menu button and the page's buttons | A document page: its title is `PageContent.Header` in main | |
+| with `AppHeader.MenuButton` | The menu button at the place of the part instead of the start | The button belongs elsewhere in the bar (after a back button, in Actions) | |
 
 ## States
 | State | Driven by | DOM |
 |---|---|---|
-| with page tools | an `AppHeader.Tools` child | Root renders it after the title row (DOM and Tab order follow the rows), full width, `--prime-space-3` under it |
-| narrow header | header width below 36rem (container `prime-app-header`) | the icon tile and the description hide; the search folds into a square button, its text stays as the name |
-| menu button hidden | `show="narrow"` and viewport from 768px | `data-show="narrow"` on MenuButton |
+| in an app shell | `AppHeader.Root` anywhere inside `AppShell.Root` (a page's own one in main) | renders in the shell's header row at the top of the panel; the latest one on screen wins over `AppShell.Template`'s `header` |
+| with the menu button | the shell's Sidebar is off-canvas (`offCanvas="auto"` on a phone, `"always"`) | a soft icon Button leads `AppHeader.Start` (or the row) with `aria-expanded` and `aria-controls` from the shell; gone while the Sidebar is a rail on screen and outside a shell |
+| with page tools | an `AppHeader.Tools` anywhere in Root (directly, in a fragment, inside a component of the page) | rendered after the title row (DOM and Tab order follow the rows), full width, `--prime-space-3` under it |
+| narrow header | header width below 36rem (container `prime-app-header`) | the icon tile hides; the title and its line of data truncate |
 | short viewport | viewport below 480px high (a phone on its side) | Root stops sticking |
 
 ## Layout & spacing
 - Row min height = control m + `--prime-space-2` (44), padding-block `--prime-space-3` (the top grows to the safe-area inset): 68 in all, the height of the Sidebar header, so the brand and the title share one line.
-- Inline padding: the shell gutters (16 → 24 → 32, the same as `AppShell.Main`) in the shell's panel, so the header lines up with the page; `--prime-space-4` elsewhere.
-- Icon buttons are `soft` neutral (MenuButton is), never `ghost`: the search folds into a filled square too, so every button on the bar has a shape.
-- Gaps: `--prime-space-3` between zones, `--prime-space-2` inside Start and Actions; `AppHeader.Separator` adds `--prime-space-2` on each side (16 in all) and is 20 high.
+- Inline padding: the page gutter `--prime-layout-gutter` (16 → 24 → 32, the same as `AppShell.Main`), so in the shell's header row the header lines up with the page; in a frame inside the page (a preview) the small gutter. Main's top air ([AppShell](../app-shell/COMPONENT.md)) stands between the header and the page's first block.
+- Icon buttons are `soft` neutral (the menu button is), never `ghost`: every button on the bar has a shape.
+- Gaps: `--prime-space-3` between zones, `--prime-space-2` inside Start and Actions; `AppHeader.Separator` is the `inset` vertical Divider: the tier gap on each side (8 at `m`) and one text line tall (20 at `m`).
 - `AppHeader.Icon` is a 36 tile with the radius and fill of a soft neutral button m, so it lines up with the buttons on the bar.
 - On the panel surface with no divider or shadow (depth from fill); `z-index: --prime-z-sticky`.
 - Sticky at `top: 0` of its scroller (static on a viewport below 480px high). The shared sticky surface paints its fill one border width past the top edge, so no sub-pixel seam of the scrolling rows shows above it.
-- Search: up to 288 wide, shrinks first; field tier m and the fill of the panel layer it sits on. Controls inside are size `m`.
-- `AppHeader.Tools` is the header's second row: the full width under the title row, 12 apart, sticky with it. The PageToolbar inside lays itself out from that width — one row from 56rem, two below — so on a phone the page tools wrap under the title, never squeeze it. The page's primary action goes into `PageToolbar.Actions` there, and `AppHeader.Actions` keeps notifications and the account.
+- Controls inside are size `m`.
+- `AppHeader.Tools` is the header's second row: the full width under the title row, 12 apart, sticky with it. The PageToolbar inside lays itself out from that width — one row from 56rem, stacked rows below, the primary action on its own row when the search would get less than 18rem beside it — so on a phone the page tools wrap under the title, never squeeze it.
 
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 | Key | Action |
 |---|---|
-| `Tab` | Moves through the menu button, the path links, the search and the actions in reading order, then the page tools in the second row. |
-| `Enter` · `Space` | Presses the focused button: opens the menu, the search or runs the action. |
+| `Tab` | Moves through the menu button, the path links and the page's buttons in reading order, then the page tools in the second row. |
+| `Enter` · `Space` | Presses the focused button: opens the menu or runs the action. |
 
 ### ARIA
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 - Root is a `<header>`: the banner landmark when it sits at the top level of the page.
-- Search is a button named by its text; the key hint is `aria-hidden`, and the app binds the shortcut.
-- MenuButton is named by `labels.menu`; pass `aria-expanded` (whether the Sidebar is open).
-- Title is not a heading by default: the page `<h1>` stays with PageContent.Title. With `as="h1"` the name is the page heading; the description sits next to it, outside its accessible name. One `<h1>` per page either way.
+- The menu button is named by `labels.menu`; `aria-expanded` (whether the Sidebar panel is open) and `aria-controls` (its `<nav>`) come from the shell.
+- The name of `AppHeader.Title` is the page heading `<h1>`; the description sits next to it, outside its accessible name. One `<h1>` per page: in the header on app pages, `PageContent.Title` on a document page (whose header has no title).
 - `AppHeader.Tools` follows the title row in the DOM, so Tab and screen readers meet the page tools after the header's own buttons.
 
 ### Labels
@@ -177,27 +159,29 @@ AppHeader.Root               <header>, one sticky row as high as the Sidebar bra
 
 | Key | Default | Used for |
 |---|---|---|
-| `menu` | `"Открыть меню"` | Name of `AppHeader.MenuButton`. |
+| `menu` | `"Открыть меню"` | Name of the menu button (drawn by the header or `AppHeader.MenuButton`). |
 
 ## Examples
 | Example | Shows |
 |---|---|
-| [overview.tsx](examples/overview.tsx) | The top bar of a screen: where you are, global search, notifications and the primary action — `AppHeader.Title`, `AppHeader.Search`, `AppHeader.Actions`. |
-| [breadcrumbs.tsx](examples/breadcrumbs.tsx) | A nested page: a back button, a separator and the path instead of a title, actions on the record at the end — `AppHeader.Separator`, `AppHeader.Actions`. |
-| [page-title.tsx](examples/page-title.tsx) | The header carries the page: the title is the page heading, the page tools (sections, the period, the primary action) are its second row and lay themselves out from its width — `AppHeader.Title`, `as`, `AppHeader.Tools`. |
+| [overview.tsx](examples/overview.tsx) | The page's header: the page title with its icon and a line of data under it, the page's own buttons at the end — `AppHeader.Title`, `AppHeader.Description`, `AppHeader.Actions`. |
+| [breadcrumbs.tsx](examples/breadcrumbs.tsx) | A nested record: the path up, a separator and the record as the page title, the record's buttons at the end — `AppHeader.Separator`, `AppHeader.Actions`. |
+| [page-title.tsx](examples/page-title.tsx) | The header carries the page: the title is the page heading with a line of data, the page tools (sections, the period, the primary action) are its second row and lay themselves out from its width — `AppHeader.Title`, `AppHeader.Tools`. |
 | [in-app-shell.tsx](examples/in-app-shell.tsx) | The header in the app frame: one row with the Sidebar brand across the two planes, sticky over main — `AppShell`, `Sidebar.Brand`. |
-| [narrow.tsx](examples/narrow.tsx) | On a phone: the menu button opens the navigation, the description goes and the search folds into an icon — `AppHeader.MenuButton`, `show`. |
+| [narrow.tsx](examples/narrow.tsx) | On a phone the header leads with the menu button that opens the navigation by itself, the title and its line of data truncate and the page's action keeps its icon — `AppShell`, `offCanvas`. |
 
 ## Mistakes
 - A border or shadow under the header → it sits on the panel surface; the fill is the boundary.
-- `AppHeader.Title as="h1"` while main also has `PageContent.Title` → two `<h1>`; the header carries the title only when main has no heading row.
+- `AppHeader.Title` while main also has `PageContent.Title` → two titles; an app page titles itself in the header, only a document page keeps `PageContent.Header` (and then the header has no title).
+- No title at all on an app page → the page has no `<h1>`.
+- A description that describes the page («Все заказы магазина») → a line of data («128 в работе · 6 ждут оплаты») or nothing.
 - Page tools crammed into `AppHeader.Actions` → `AppHeader.Tools` with a PageToolbar: it wraps under the title instead of squeezing it.
-- A heading element of your own inside `AppHeader.Title` → `as="h1"`, so the description stays out of the heading.
-- A real text input for global search → `AppHeader.Search` opens the CommandMenu, where typing happens.
-- More than three actions → keep one primary action; the rest go into the page or a Dropdown.
-- A hand-made menu button with a media query → `AppHeader.MenuButton` follows the Sidebar breakpoint.
+- A global search, notifications or app-wide buttons in the header → the row is per page; the app's own places live in the Sidebar.
+- A heading element of your own inside `AppHeader.Title` → the title's name is already the `<h1>`; a second heading nests inside it.
+- A hand-made menu button with a media query or hand-wired `aria-expanded` → the header draws the menu button itself from the shell's Sidebar; `AppHeader.MenuButton` only moves it.
+- A page header that misses the phone menu → render the page's `AppHeader.Root` inside the `AppShell` (not in a frame of its own): it then joins the shell's header row and gets the menu button.
 - `ghost` icon buttons in the header → `variant="soft" tone="neutral"`: a light fill gives each button a shape on the bar.
 
 ## Related
-- **Built from:** [Button](../../components/button/COMPONENT.md), [Kbd](../../components/kbd/COMPONENT.md), [Divider](../../components/divider/COMPONENT.md), Icon (`action.search`, `nav.menu`)
-- **See also:** [AppShell](../app-shell/COMPONENT.md), [Sidebar](../sidebar/COMPONENT.md), [PageContent](../../components/page-content/COMPONENT.md), [PageToolbar](../../components/page-toolbar/COMPONENT.md) (inside `AppHeader.Tools`), [CommandMenu](../../components/command-menu/COMPONENT.md), [Breadcrumb](../../components/breadcrumb/COMPONENT.md)
+- **Built from:** [Button](../../components/button/COMPONENT.md), [Divider](../../components/divider/COMPONENT.md), Icon (`nav.menu`), [AppShell](../app-shell/COMPONENT.md) (its header row and navigation)
+- **See also:** [AppShell](../app-shell/COMPONENT.md), [Sidebar](../sidebar/COMPONENT.md), [PageContent](../../components/page-content/COMPONENT.md), [PageToolbar](../../components/page-toolbar/COMPONENT.md) (inside `AppHeader.Tools`), [Breadcrumb](../../components/breadcrumb/COMPONENT.md)

package/dist/skill/reference/layout/app-header/examples/breadcrumbs.tsx

@@ -1,4 +1,4 @@
-/** A nested page: a back button, a separator and the path instead of a title, actions on the record at the end — `AppHeader.Separator`, `AppHeader.Actions`. */
+/** A nested record: the path up, a separator and the record as the page title, the record's buttons at the end — `AppHeader.Separator`, `AppHeader.Actions`. */
 import { AppHeader, Breadcrumb, Button, Icon } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
@@ -8,21 +8,22 @@ export default function AppHeaderBreadcrumbsExample() {
     <div className={styles.window}>
       <AppHeader.Root>
         <AppHeader.Start>
-          <Button.Root variant="soft" tone="neutral" aria-label="Назад к клиентам">
-            <Button.Icon>
-              <Icon name="nav.chevronLeft" />
-            </Button.Icon>
-          </Button.Root>
-          <AppHeader.Separator />
           <Breadcrumb.Root>
             <Breadcrumb.Item href="#crm">CRM</Breadcrumb.Item>
             <Breadcrumb.Item href="#clients">Клиенты</Breadcrumb.Item>
-            <Breadcrumb.Item current>ООО «Север»</Breadcrumb.Item>
           </Breadcrumb.Root>
+          <AppHeader.Separator />
+          <AppHeader.Title>
+            ООО «Север»
+            <AppHeader.Description>Клиент с 2021 года · 4 сделки</AppHeader.Description>
+          </AppHeader.Title>
         </AppHeader.Start>
         <AppHeader.Actions>
           <Button.Root variant="soft" tone="neutral">
-            Экспорт
+            <Button.Icon>
+              <Icon name="action.send" />
+            </Button.Icon>
+            Написать
           </Button.Root>
           <Button.Root variant="soft" tone="neutral" aria-label="Ещё действия">
             <Button.Icon>

package/dist/skill/reference/layout/app-header/examples/examples.module.css

@@ -1,20 +1,15 @@
-/* Layout of the AppHeader scenarios: an app window and a phone-wide screen. Semantic tokens only. */
+/* Layout of the AppHeader scenarios: app windows and a phone-wide screen. The preview stage is the page; a window only sizes and clips. Semantic tokens only. */
 
-/* The top of an app window: the content panel (the page) with the header on it. */
+/* The top of an app window: the page with the header on it. */
 .window {
   box-sizing: border-box;
   width: 100%;
   overflow: hidden;
-  border-radius: var(--prime-card-radius);
-  background: var(--prime-color-layer-current);
-  box-shadow:
-    0 0 0 var(--prime-border-width) var(--prime-color-border-subtle),
-    var(--prime-shadow-raised);
 }
 
-/* narrow.tsx: the same window, phone-wide, so the header folds its search. */
+/* narrow.tsx: an app window, phone-wide, so the title and its line of data truncate. */
 .phone {
-  width: min(100%, var(--prime-drawer-width-s));
+  width: min(100%, var(--prime-layout-narrow-width));
   margin-inline: auto;
 }
 
@@ -25,23 +20,9 @@
   width: 100%;
   height: calc(var(--prime-space-24) * 4);
   overflow: hidden;
-  border-radius: var(--prime-card-radius);
-  background: var(--prime-color-layer-current);
-  box-shadow:
-    0 0 0 var(--prime-border-width) var(--prime-color-border-subtle),
-    var(--prime-shadow-raised);
 }
 
 /* The shell fills the window frame instead of the viewport. */
 .shell {
   height: 100%;
 }
-
-/* The product mark inside `Sidebar.BrandLogo`: an accent tile with a glyph. */
-.logo {
-  display: grid;
-  place-items: center;
-  border-radius: var(--prime-radius-m);
-  background: var(--prime-color-accent-default);
-  color: var(--prime-color-accent-fg);
-}

package/dist/skill/reference/layout/app-header/examples/in-app-shell.tsx

@@ -21,9 +21,7 @@ export default function AppHeaderInAppShellExample() {
             <Sidebar.Header>
               <Sidebar.Brand href="#home" description="Отдел продаж">
                 <Sidebar.BrandLogo>
-                  <span className={styles.logo}>
-                    <Icon name="nav.layoutGrid" />
-                  </span>
+                  <Icon name="nav.layoutGrid" />
                 </Sidebar.BrandLogo>
                 Acme CRM
               </Sidebar.Brand>
@@ -51,10 +49,9 @@ export default function AppHeaderInAppShellExample() {
               <AppHeader.Description>128 в работе</AppHeader.Description>
             </AppHeader.Title>
           </AppHeader.Start>
-          <AppHeader.Search>Поиск</AppHeader.Search>
         </AppHeader.Root>
         <AppShell.Main>
-          <PageContent.Page>
+          <PageContent.Root as="section">
             <PageContent.Body>
               {ORDERS.map((order) => (
                 <Typography key={order} variant="body-m">
@@ -62,7 +59,7 @@ export default function AppHeaderInAppShellExample() {
                 </Typography>
               ))}
             </PageContent.Body>
-          </PageContent.Page>
+          </PageContent.Root>
         </AppShell.Main>
       </AppShell.Root>
     </div>

package/dist/skill/reference/layout/app-header/examples/narrow.tsx

@@ -1,29 +1,66 @@
-/** On a phone: the menu button opens the navigation, the description goes and the search folds into an icon — `AppHeader.MenuButton`, `show`. */
-import { AppHeader, Button, Icon } from "prime-ui-kit";
+/** On a phone the header leads with the menu button that opens the navigation by itself, the title and its line of data truncate and the page's action keeps its icon — `AppShell`, `offCanvas`. */
+import { AppHeader, AppShell, Button, Icon, PageContent, Sidebar, Typography } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
 
+const ORDERS = [
+  "№ 4821 · ООО «Север» · 84 000 ₽",
+  "№ 4820 · ИП Котов · 12 500 ₽",
+  "№ 4819 · ООО «Вектор» · 230 000 ₽",
+];
+
 export default function AppHeaderNarrowExample() {
   return (
-    <div className={`${styles.window} ${styles.phone}`}>
-      <AppHeader.Root>
-        <AppHeader.Start>
-          {/* `always`: this frame is phone-wide on any screen; in an app keep the default `narrow`. */}
-          <AppHeader.MenuButton show="always" aria-expanded={false} />
-          <AppHeader.Title>
-            Заказы
-            <AppHeader.Description>128 в работе</AppHeader.Description>
-          </AppHeader.Title>
-        </AppHeader.Start>
-        <AppHeader.Search>Поиск заказов</AppHeader.Search>
-        <AppHeader.Actions>
-          <Button.Root variant="soft" tone="neutral" aria-label="Новый заказ">
-            <Button.Icon>
-              <Icon name="action.add" />
-            </Button.Icon>
-          </Button.Root>
-        </AppHeader.Actions>
-      </AppHeader.Root>
+    <div className={`${styles.stage} ${styles.phone}`}>
+      <AppShell.Root fillViewport className={styles.shell}>
+        <AppShell.Nav>
+          {/* `always`: this window is phone-wide on any screen; in an app keep the default `auto`. */}
+          <Sidebar.Root offCanvas="always">
+            <Sidebar.Content>
+              <Sidebar.Item href="#overview">
+                <Sidebar.ItemIcon>
+                  <Icon name="nav.home" />
+                </Sidebar.ItemIcon>
+                Обзор
+              </Sidebar.Item>
+              <Sidebar.Item href="#orders" current>
+                <Sidebar.ItemIcon>
+                  <Icon name="object.package" />
+                </Sidebar.ItemIcon>
+                Заказы
+              </Sidebar.Item>
+            </Sidebar.Content>
+          </Sidebar.Root>
+        </AppShell.Nav>
+        <AppHeader.Root>
+          <AppHeader.Start>
+            <AppHeader.Title>
+              Заказы покупателей
+              <AppHeader.Description>
+                128 в работе · 6 ждут оплаты · 2 возврата
+              </AppHeader.Description>
+            </AppHeader.Title>
+          </AppHeader.Start>
+          <AppHeader.Actions>
+            <Button.Root aria-label="Новый заказ">
+              <Button.Icon>
+                <Icon name="action.add" />
+              </Button.Icon>
+            </Button.Root>
+          </AppHeader.Actions>
+        </AppHeader.Root>
+        <AppShell.Main>
+          <PageContent.Root as="section">
+            <PageContent.Body>
+              {ORDERS.map((order) => (
+                <Typography key={order} variant="body-m">
+                  {order}
+                </Typography>
+              ))}
+            </PageContent.Body>
+          </PageContent.Root>
+        </AppShell.Main>
+      </AppShell.Root>
     </div>
   );
 }

package/dist/skill/reference/layout/app-header/examples/overview.tsx

@@ -1,4 +1,4 @@
-/** The top bar of a screen: where you are, global search, notifications and the primary action — `AppHeader.Title`, `AppHeader.Search`, `AppHeader.Actions`. */
+/** The page's header: the page title with its icon and a line of data under it, the page's own buttons at the end — `AppHeader.Title`, `AppHeader.Description`, `AppHeader.Actions`. */
 import { AppHeader, Button, Icon } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
@@ -10,24 +10,22 @@ export default function AppHeaderOverviewExample() {
         <AppHeader.Start>
           <AppHeader.Title>
             <AppHeader.Icon>
-              <Icon name="nav.dashboard" />
+              <Icon name="object.package" />
             </AppHeader.Icon>
-            Обзор
-            <AppHeader.Description>Отдел продаж · октябрь</AppHeader.Description>
+            Заказы
+            <AppHeader.Description>128 в работе · 6 ждут оплаты</AppHeader.Description>
           </AppHeader.Title>
         </AppHeader.Start>
-        <AppHeader.Search>Поиск заказов и клиентов</AppHeader.Search>
         <AppHeader.Actions>
-          <Button.Root variant="soft" tone="neutral" aria-label="Уведомления">
+          <Button.Root variant="soft" tone="neutral" aria-label="Экспорт в CSV">
             <Button.Icon>
-              <Icon name="object.bell" />
+              <Icon name="action.download" />
             </Button.Icon>
           </Button.Root>
-          <Button.Root>
+          <Button.Root variant="soft" tone="neutral" aria-label="Ещё действия">
             <Button.Icon>
-              <Icon name="action.add" />
+              <Icon name="action.more" />
             </Button.Icon>
-            Новый заказ
           </Button.Root>
         </AppHeader.Actions>
       </AppHeader.Root>

package/dist/skill/reference/layout/app-header/examples/page-title.tsx

@@ -1,4 +1,4 @@
-/** The header carries the page: the title is the page heading, the page tools (sections, the period, the primary action) are its second row and lay themselves out from its width — `AppHeader.Title`, `as`, `AppHeader.Tools`. */
+/** The header carries the page: the title is the page heading with a line of data, the page tools (sections, the period, the primary action) are its second row and lay themselves out from its width — `AppHeader.Title`, `AppHeader.Tools`. */
 import { AppHeader, Button, Icon, PageToolbar, SegmentedControl, Select } from "prime-ui-kit";
 import * as React from "react";
 
@@ -24,18 +24,11 @@ export default function AppHeaderPageTitleExample() {
     <div className={styles.window}>
       <AppHeader.Root>
         <AppHeader.Start>
-          <AppHeader.Title as="h1">
+          <AppHeader.Title>
             Сделки
-            <AppHeader.Description>Отдел продаж</AppHeader.Description>
+            <AppHeader.Description>24 сделки в работе · 8,2 млн ₽</AppHeader.Description>
           </AppHeader.Title>
         </AppHeader.Start>
-        <AppHeader.Actions>
-          <Button.Root variant="soft" tone="neutral" aria-label="Уведомления">
-            <Button.Icon>
-              <Icon name="object.bell" />
-            </Button.Icon>
-          </Button.Root>
-        </AppHeader.Actions>
         <AppHeader.Tools>
           <PageToolbar.Root aria-label="Сделки">
             <PageToolbar.Sections>