prime-ui-kit 0.14.0 → 0.16.0

package/src/components/visually-hidden/examples/overview.tsx

@@ -2,21 +2,31 @@
 import { Badge, Button, Typography, VisuallyHidden } from "prime-ui-kit";
 import * as React from "react";
 
+const UNPAID_INVOICES = 3;
+
 export default function VisuallyHiddenOverviewExample() {
-  const [archived, setArchived] = React.useState(0);
+  const [unpaid, setUnpaid] = React.useState(UNPAID_INVOICES);
+  const [announcement, setAnnouncement] = React.useState("");
+
+  const archive = () => {
+    const left = Math.max(0, unpaid - 1);
+    setUnpaid(left);
+    setAnnouncement(`Счёт перенесён в архив. Ждут оплаты: ${left}`);
+  };
 
   return (
     <>
       <Typography as="span" variant="body-m">
-        Счета к оплате <Badge.Root color="orange">3</Badge.Root>
-        <VisuallyHidden>: три счёта ждут оплаты</VisuallyHidden>
+        Счета к оплате{" "}
+        <Badge.Root tone="warning" aria-hidden="true">
+          {unpaid}
+        </Badge.Root>
+        <VisuallyHidden>, ждут оплаты: {unpaid}</VisuallyHidden>
       </Typography>
-      <Button.Root variant="soft" tone="neutral" onClick={() => setArchived((count) => count + 1)}>
+      <Button.Root variant="soft" tone="neutral" disabled={unpaid === 0} onClick={archive}>
         В архив
       </Button.Root>
-      <VisuallyHidden live="polite">
-        {archived > 0 ? `Счетов в архиве: ${archived}` : ""}
-      </VisuallyHidden>
+      <VisuallyHidden live="polite">{announcement}</VisuallyHidden>
     </>
   );
 }

package/src/components/voice-player/COMPONENT.md

@@ -51,7 +51,7 @@ VoicePlayer            <div role="group">; state in data-*
 |---|---|---|---|
 | `src` | `string` | — (required) | Audio URL, loaded with `preload="metadata"`: nothing plays before a press. |
 | `duration` | `number` | — | Length in seconds, shown until the media reports its own. |
-| `unplayed` | `boolean` | `false` | Nobody has played it yet: an accent dot after the time and `labels.unplayed` for screen readers. Clear it when `onPlayingChange(true)` comes; the dot leaves with a fade. |
+| `unplayed` | `boolean` | `false` | Nobody has played it yet: an accent dot after the time and `labels.unplayed` for screen readers. Clear it when `onPlayingChange(true)` comes; the dot fades out and the row closes up in place. |
 | `disabled` | `boolean` | `false` | Nothing can be played: the play disk, the waveform slider and the rate chip, the transcript button and the transfer actions are off (native `disabled`). A disabled `Fieldset` around it disables it too. |
 | `waveform` | `readonly number[]` | — | Levels 0…1 from data, resampled to the bars that fit the width. Without it: a calm flat row. Voice only: a circle shows a face, not levels. |
 | `rate` | `1 \| 1.5 \| 2` | — | Playback speed (controlled). Voice only: speech is listened to faster; a face is watched at its own pace. |
@@ -75,8 +75,12 @@ VoicePlayer            <div role="group">; state in data-*
 | `labels` | `Partial<VoicePlayerLabels>` | — | Built-in strings, see Labels. |
 | `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children" \| "onPlay" \| "onPause" \| "onEnded" \| "onRateChange">` | — | `className`, `aria-label` (replaces `labels.player`), `data-*` and the other div attributes. |
 
-### getWaveform
-`getWaveform(source, bars = 48)`: the 0…1 peaks of a `Blob` or URL with no stored levels, for `waveform`.
+### Functions
+
+#### `getWaveform(source, bars)`
+`(source: Blob \| string, bars?: number) => Promise<number[]>`
+
+The 0…1 peaks of a `Blob` or URL with no stored levels, for `waveform`; `bars` defaults to 48. Rejects when the audio cannot be fetched or decoded.
 
 ## Variants
 One look. Colors are semantic roles only (`accent-default`, `accent-fg`, `fill-strong`, `text-muted`), so an outgoing chat bubble restyles the player by overriding them for its subtree.
@@ -84,7 +88,7 @@ One look. Colors are semantic roles only (`accent-default`, `accent-fg`, `fill-s
 ### Flags
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| `unplayed` | an accent dot after the time; it rises in with a fade and sinks out the same way | the recipient has not listened yet | |
+| `unplayed` | an accent dot after the time; it rises in, and fades as the row closes up in place when it clears | the recipient has not listened yet | |
 | `disabled` | muted disk, no played bars, disabled time | the recording cannot be played (deleted, expired) | |
 
 ## States
@@ -122,6 +126,8 @@ One look. Colors are semantic roles only (`accent-default`, `accent-fg`, `fill-s
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 | Key | Action |
 |---|---|
 | `Tab` | Moves focus: the disk (or the transfer disk), the waveform slider, the rate chip, the transcript button. |
@@ -132,6 +138,8 @@ One look. Colors are semantic roles only (`accent-default`, `accent-fg`, `fill-s
 | `Home` · `End` | On the waveform: to the start or the end. |
 
 ### ARIA
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 - The root is `role="group"` named by `labels.player` (or your `aria-label`).
 - The disk is named `labels.play` while paused and `labels.pause` while playing. While the recording is sent, received or not fetched the same button is the transfer, named by the direction — `cancelUpload` / `cancelDownload` described by `uploadProgress` / `downloadProgress` (`aria-busy`), after a failure `retryUpload` / `retryDownload` described by `notSent` / `notReceived`, `download` for a remote one; its ring is `aria-hidden`; a refused cancel, retry or download is announced (`role="status"`).
 - The waveform is `role="slider"` with `aria-valuemin`, `aria-valuemax` (seconds), `aria-valuenow` and `aria-valuetext` from `labels.position`.
@@ -146,11 +154,11 @@ One look. Colors are semantic roles only (`accent-default`, `accent-fg`, `fill-s
 |---|---|---|
 | `player` | `"Голосовое сообщение"` | Name of the player group. |
 | `play` | `"Воспроизвести голосовое сообщение"` | Name of the play disk while it does not play. |
-| `pause` | `"Пауза"` | Name of the play disk while it plays. |
-| `position` | `"{current} из {duration}"` | The position: `{current}` and `{duration}` as m:ss. |
 | `unplayed` | `"Не прослушано"` | Visually hidden text read while `unplayed`. |
 | `seek` | `"Перемотка"` | Name of the waveform slider (its `aria-valuetext` is `position`). |
 | `rate` | `"Скорость воспроизведения: {rate}"` | Name of the rate chip; `{rate}` as shown on it. |
+| `pause` | `"Пауза"` | Name of the play disk while it plays. |
+| `position` | `"{current} из {duration}"` | The position: `{current}` and `{duration}` as m:ss. |
 | `transcribe` | `"Расшифровать"` | Name of the transcript button while the text is closed. |
 | `hideTranscript` | `"Скрыть расшифровку"` | Name of the transcript button while the text is open. |
 | `transcribeFailed` | `"Не удалось расшифровать сообщение"` | Announced when `onTranscribe` rejects. |
@@ -172,11 +180,11 @@ One look. Colors are semantic roles only (`accent-default`, `accent-fg`, `fill-s
 |---|---|
 | [overview.tsx](examples/overview.tsx) | A client's voice message to support, ready to play — `src`, `waveform`, `duration`. |
 | [states.tsx](examples/states.tsx) | Every state side by side, each labelled by its prop: the transfer is drawn on the play disk itself — in flight with the cross and the ring, failed with the retry, not fetched with the download arrow — `unplayed`, `transfer`, `transferProgress`, `disabled`. |
-| [call-recording.tsx](examples/call-recording.tsx) | A sales call recording on a deal card: the player takes the card's width — `className`. |
+| [call-recording.tsx](examples/call-recording.tsx) | A sales call recording on a deal card: the telephony stores no levels, so the waveform is read from the audio itself and the calm flat row fills in once it is ready; the player takes the card's width — `getWaveform`, `waveform`, `className`. |
 | [in-message.tsx](examples/in-message.tsx) | Voice messages in a support chat: the player sits on the bubble fill and the bubble's time stands in its corner — `Message.Root`, `time`, `status`. |
 | [transcript.tsx](examples/transcript.tsx) | Voice messages with a transcript: one known, one asked for on the first open — `transcript`, `onTranscribe`. |
 | [transfer.tsx](examples/transfer.tsx) | One look for a recording on its way in either direction: the client's voice message waits to be fetched and then arrives, the reply is being sent — the play disk itself carries the cross and the ring of the share, a dropped connection offers a retry, and the play glyph comes back once it is through — `transfer`, `transferProgress`, `transferDirection`, `onCancel`, `onRetry`, `onDownload`. |
-| [controlled.tsx](examples/controlled.tsx) | The parent knows what plays, marks the message as listened on the first play and keeps the speed — `playing`, `onPlayingChange`, `unplayed`, `rate`, `onRateChange`. |
+| [controlled.tsx](examples/controlled.tsx) | The parent knows what plays, marks the message as listened on the first play and as heard to the end when it ends, keeps the speed and keeps the transcript open — `playing`, `onPlayingChange`, `unplayed`, `onEnded`, `rate`, `onRateChange`, `transcriptExpanded`, `onTranscriptExpandedChange`. |
 
 ## Mistakes
 - A hand-made `<audio controls>` in a bubble → use `VoicePlayer`: it matches the bubble's colors and keeps room for the time.
@@ -188,5 +196,5 @@ One look. Colors are semantic roles only (`accent-default`, `accent-fg`, `fill-s
 - `onTranscribe` that resolves `undefined` or returns `true` → resolve the text itself, or return nothing and pass `transcript` when it comes.
 
 ## Related
-- **Built from:** [Button](../button/COMPONENT.md) (the play disk, `shape="circle"`; the transcript button), [Spinner](../spinner/COMPONENT.md), Icon (`action.play`, `action.pause`, `action.transcribe`, `nav.chevronUp`); `internal/disabledContext` (a disabled `Fieldset`), `internal/mediaPlayer` (the playing triad, the transcript button and the transfer shared with VideoNote), `internal/transferDisk` (the transfer's logic on the play disk: `useTransferDisk`), `internal/transcript` + `internal/Disclosure` (the transcript), `internal/mediaSession` (one sound at a time)
+- **Built from:** [Button](../button/COMPONENT.md) (the play disk, `shape="circle"`; the transcript button; the rate chip, soft neutral `density="inline"`), [Spinner](../spinner/COMPONENT.md), Icon (`action.play`, `action.pause`, `action.transcribe`, `nav.chevronUp`); `internal/disabledContext` (a disabled `Fieldset`), `internal/mediaPlayer` (the playing triad, the transcript button and the transfer shared with VideoNote), `internal/transferDisk` (the transfer's logic on the play disk: `useTransferDisk`), `internal/transcript` + `internal/Disclosure` (the transcript), `internal/mediaSession` (one sound at a time), `internal/audio` (`getWaveform`'s decoding and peaks, shared with the Composer's recorder), [VisuallyHidden](../visually-hidden/COMPONENT.md)
 - **See also:** [VideoNote](../video-note/COMPONENT.md) — the round video message, the same player contract; [Message](../message/COMPONENT.md) — the bubble a voice message sits in; [Composer](../composer/COMPONENT.md) — records the voice message; [Slider](../slider/COMPONENT.md), [ProgressBar](../progress-bar/COMPONENT.md)

package/src/components/voice-player/examples/call-recording.tsx

@@ -1,17 +1,27 @@
-/** A sales call recording on a deal card: the player takes the card's width — `className`. */
-import { Card, Typography, VoicePlayer } from "prime-ui-kit";
+/** A sales call recording on a deal card: the telephony stores no levels, so the waveform is read from the audio itself and the calm flat row fills in once it is ready; the player takes the card's width — `getWaveform`, `waveform`, `className`. */
+import { Card, getWaveform, Typography, VoicePlayer } from "prime-ui-kit";
+import * as React from "react";
 
 import styles from "./examples.module.css";
 
 const RECORDING_URL = "https://interactive-examples.mdn.mozilla.net/media/cc0-audio/t-rex-roar.mp3";
 
-const WAVEFORM = [
-  0.2, 0.34, 0.5, 0.42, 0.6, 0.78, 0.66, 0.4, 0.3, 0.52, 0.7, 0.86, 0.74, 0.48, 0.36, 0.58, 0.8,
-  0.62, 0.38, 0.26, 0.44, 0.68, 0.9, 0.72, 0.5, 0.32, 0.46, 0.64, 0.54, 0.3, 0.22, 0.4, 0.6, 0.76,
-  0.56, 0.34,
-];
-
 export default function VoicePlayerCallRecordingExample() {
+  const [waveform, setWaveform] = React.useState<number[]>();
+
+  React.useEffect(() => {
+    let current = true;
+    getWaveform(RECORDING_URL)
+      .then((levels) => {
+        if (current) setWaveform([...levels]);
+      })
+      // Without levels the player keeps its flat row: the recording still plays.
+      .catch(() => {});
+    return () => {
+      current = false;
+    };
+  }, []);
+
   return (
     <Card.Root className={styles.card}>
       <Card.Body className={styles.body}>
@@ -24,7 +34,7 @@ export default function VoicePlayerCallRecordingExample() {
         <VoicePlayer
           className={styles.player}
           src={RECORDING_URL}
-          waveform={WAVEFORM}
+          waveform={waveform}
           duration={754}
           aria-label="Запись звонка"
         />

package/src/components/voice-player/examples/controlled.tsx

@@ -1,4 +1,4 @@
-/** The parent knows what plays, marks the message as listened on the first play and keeps the speed — `playing`, `onPlayingChange`, `unplayed`, `rate`, `onRateChange`. */
+/** The parent knows what plays, marks the message as listened on the first play and as heard to the end when it ends, keeps the speed and keeps the transcript open — `playing`, `onPlayingChange`, `unplayed`, `onEnded`, `rate`, `onRateChange`, `transcriptExpanded`, `onTranscriptExpandedChange`. */
 import { Typography, VoicePlayer, type VoicePlayerRate } from "prime-ui-kit";
 import * as React from "react";
 
@@ -9,10 +9,23 @@ const WAVEFORM = [
   0.64, 0.86, 0.58, 0.32, 0.2,
 ];
 
+const TRANSCRIPT =
+  "Добрый день! Машина с заказом 4821 будет у склада в девять, водитель позвонит за полчаса.";
+
 export default function VoicePlayerControlledExample() {
   const [playing, setPlaying] = React.useState(false);
   const [unplayed, setUnplayed] = React.useState(true);
+  const [heard, setHeard] = React.useState(false);
   const [rate, setRate] = React.useState<VoicePlayerRate>(1.5);
+  const [transcriptOpen, setTranscriptOpen] = React.useState(false);
+
+  const state = playing
+    ? "Воспроизводится"
+    : heard
+      ? "Дослушано до конца"
+      : unplayed
+        ? "Ещё не прослушано"
+        : "Прослушано";
 
   return (
     <>
@@ -26,12 +39,16 @@ export default function VoicePlayerControlledExample() {
           setPlaying(next);
           if (next) setUnplayed(false);
         }}
+        onEnded={() => setHeard(true)}
         rate={rate}
         onRateChange={setRate}
+        transcript={TRANSCRIPT}
+        transcriptExpanded={transcriptOpen}
+        onTranscriptExpandedChange={setTranscriptOpen}
       />
       <Typography as="p" variant="body-s" tone="secondary">
-        {playing ? "Воспроизводится" : unplayed ? "Ещё не прослушано" : "Прослушано"} · скорость{" "}
-        {String(rate).replace(".", ",")}×
+        {state} · скорость {String(rate).replace(".", ",")}× · расшифровка{" "}
+        {transcriptOpen ? "открыта" : "свёрнута"}
       </Typography>
     </>
   );

package/src/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/src/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/src/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);
-}