prime-ui-kit 0.15.0 → 0.16.0

package/src/components/tooltip/examples/sizes.tsx

@@ -1,21 +1,28 @@
 /** Every size tier next to buttons of the same tier; take the tier of the control it describes — `size`. */
-import { Button, Tooltip } from "prime-ui-kit";
+import { Button, Tooltip, Typography } from "prime-ui-kit";
 
 const SIZES = ["xs", "s", "m", "l", "xl"] as const;
 
 export default function TooltipSizesExample() {
   return (
     <Tooltip.Provider>
-      {SIZES.map((size) => (
-        <Tooltip.Root key={size}>
-          <Tooltip.Trigger>
-            <Button.Root variant="soft" tone="neutral" size={size}>
+      <div>
+        {SIZES.map((size) => (
+          <div key={size}>
+            <Tooltip.Root>
+              <Tooltip.Trigger>
+                <Button.Root variant="soft" tone="neutral" size={size}>
+                  Черновик
+                </Button.Root>
+              </Tooltip.Trigger>
+              <Tooltip.Content size={size}>Черновик сохранится на сервере</Tooltip.Content>
+            </Tooltip.Root>
+            <Typography as="span" variant="caption" tone="muted">
               {size}
-            </Button.Root>
-          </Tooltip.Trigger>
-          <Tooltip.Content size={size}>Черновик сохранится на сервере</Tooltip.Content>
-        </Tooltip.Root>
-      ))}
+            </Typography>
+          </div>
+        ))}
+      </div>
     </Tooltip.Provider>
   );
 }

package/src/components/typography/COMPONENT.md

@@ -42,9 +42,12 @@ Typography       the element from `as` (default <p>); variant, tone, weight, tra
 | `as` | `"p" \| "span" \| "div" \| "h1" \| "h2" \| "h3" \| "h4" \| "h5" \| "h6" \| "small" \| "blockquote" \| "article" \| "section" \| "header" \| "footer" \| "aside" \| "nav" \| "main"` | `"p"` | The element, by the page outline; the role keeps the look. |
 | `weight` | `"regular" \| "medium" \| "semibold"` | — | Overrides the role's weight. |
 | `tracking` | `"normal" \| "tight" \| "tighter" \| "wide"` | — | Overrides the role's tracking with a `--prime-font-tracking-*` step. |
+| `numeric` | `"proportional" \| "tabular"` | `"proportional"` | `tabular` — every digit as wide as the others: amounts, times and counts line up in a column and keep their width. |
 | `italic` | `boolean` | `false` | Italic, for quotes and titles of works. |
 | `truncate` | `boolean` | `false` | One line with an ellipsis; set `title` when the full text matters. |
-| `…rest` | `HTMLAttributes<HTMLElement>` | — | `children`, `className`, `id`, `title` and the other attributes of the element. |
+| `children` | `ReactNode` | — | The text. |
+| `className` | `string` | — | Class on the element. |
+| `…rest` | `HTMLAttributes<HTMLElement>` | — | `id`, `title` and the other attributes of the element. |
 
 ## Variants
 
@@ -71,6 +74,12 @@ Typography       the element from `as` (default <p>); variant, tone, weight, tra
 | `italic` | italic | quotes, titles of works | `false` |
 | `truncate` | one line with an ellipsis | names in fixed-width cells | `false` |
 
+### numeric
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `proportional` | the font's own figures | running text | yes |
+| `tabular` | every digit as wide as the others | amounts, times and counts in a column, a number that changes in place | |
+
 `weight` (`regular` · `medium` · `semibold`) and `tracking` (`normal` 0 · `tight` −0.01em · `tighter` −0.02em · `wide` +0.01em, from `--prime-font-tracking-*`) override the role.
 
 ## States
@@ -85,15 +94,19 @@ Text has no interactive states.
 - No outer margins: spacing comes from the parent's `gap`.
 - Title, heading and display roles balance their lines (`text-wrap-style: balance`); body and caption avoid a lone last word (`pretty`). Long words break (`overflow-wrap: break-word`).
 - `code` uses the mono family (JetBrains Mono); every other role the sans family (Golos Text).
-- Reading text: cap the column at `--prime-layout-reading-max-width` (60–75 characters).
+- Reading text: cap the column at the reading measure (PageContent `maxWidth="readable"`, 60–75 characters).
 - `truncate` needs a block element and a shrinking parent (`min-width: 0` in flex rows).
 
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 No keyboard interaction.
 
 ### ARIA
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 - The heading level comes from `as` by the page outline, the look from `variant`: never skip levels for size.
 - `tone` never carries meaning alone — name the status in words.
 - With `truncate` pass the full text in `title` when it matters.
@@ -112,10 +125,12 @@ No `labels`.
 | [inline-emphasis.tsx](examples/inline-emphasis.tsx) | Values emphasized inside running text by nested spans with another weight — `as`, `weight`. |
 | [semantic-tag.tsx](examples/semantic-tag.tsx) | The tag follows the page outline and the role sets the look, so a section title can be an `h2` at title size — `as`. |
 | [truncate.tsx](examples/truncate.tsx) | A long product name clamped to one line with an ellipsis; the full text stays in the tooltip — `truncate`, `title`. |
+| [numeric.tsx](examples/numeric.tsx) | Invoice amounts in a column line up digit under digit with tabular figures — `numeric`. |
 | [article.tsx](examples/article.tsx) | A help article from landmarks, headings and a quote at the reading width — `as`, `variant`. |
 
 ## Mistakes
 - `variant="h1"` → `variant="heading-m"` (or another role) plus `as="h1"`.
+- `font-variant-numeric: tabular-nums` in your own class around a number → `numeric="tabular"`.
 - Missing `variant` → it is required.
 - `tone="error"` → `tone="danger"`; `color="gray"` → `tone="muted"`.
 - `truncate` on an inline span in a flex row that does not shrink → use a block element and `min-width: 0`.

package/src/components/typography/examples/examples.module.css

@@ -4,9 +4,8 @@
 .block {
   display: grid;
   gap: var(--prime-space-2);
-  max-width: var(--prime-modal-width-s);
+  max-width: var(--prime-layout-form-width-s);
   margin: 0;
-  text-align: start;
 }
 
 /* inline-emphasis.tsx: a paragraph keeps inline flow, its spans must not become grid rows. */
@@ -18,7 +17,6 @@ p.block {
 .stack {
   display: grid;
   gap: var(--prime-space-3);
-  text-align: start;
 }
 
 /* article.tsx: long-form text at the reading width. */
@@ -26,13 +24,12 @@ p.block {
   display: grid;
   gap: var(--prime-space-4);
   max-width: var(--prime-layout-reading-max-width);
-  text-align: start;
 }
 
+/* The quote stands in from the text column. */
 .article blockquote {
   margin: 0;
-  padding-inline-start: var(--prime-space-3);
-  border-inline-start: var(--prime-space-1) solid var(--prime-color-fill-strong);
+  padding-inline-start: var(--prime-space-4);
 }
 
 /* truncate.tsx: 240px, narrow enough to show the ellipsis. */

package/src/components/typography/examples/numeric.tsx

@@ -0,0 +1,16 @@
+/** Invoice amounts in a column line up digit under digit with tabular figures — `numeric`. */
+import { Typography } from "prime-ui-kit";
+
+const AMOUNTS = ["1 118 400,00 ₽", "96 250,50 ₽", "7 111,11 ₽"];
+
+export default function TypographyNumericExample() {
+  return (
+    <>
+      {AMOUNTS.map((amount) => (
+        <Typography key={amount} variant="body-m" numeric="tabular">
+          {amount}
+        </Typography>
+      ))}
+    </>
+  );
+}

package/src/components/video-note/COMPONENT.md

@@ -46,7 +46,7 @@ VideoNote              <div role="group">; data-playing · data-disabled · data
 |---|---|---|---|
 | `src` | `string` | — (required) | Video 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 duration 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 duration 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 and the keyboard seek, the transcript button and the transfer actions are off (native `disabled`). A disabled `Fieldset` around it disables it too. |
 | `poster` | `string` | — | A still shown before the first frame; without it the first frame is drawn. Video only. |
 | `playing` | `boolean` | — | Playing with sound (controlled): `true` plays it (from the start or on from a pause), `false` pauses it. One sound plays on the page at a time. |
@@ -81,11 +81,11 @@ One look. The circle is the video; the play disk and the pills stand on the medi
 |---|---|---|
 | loading | the first frame not drawn yet | `data-frame="loading"` on the circle: a Skeleton fills it; once loaded the video fades in over it (`base`), then the Skeleton goes |
 | at rest | idle | `data-state="idle"` on the circle; the still first frame (or `poster`) with the play disk and the duration; nothing plays, loops or decodes past the metadata and the first frame — a long chat costs nothing until a press |
-| playing | the disk (or a press on the circle), `playing` / `defaultPlaying` | `data-playing="true"` on the root, `data-state="playing"`; sound from the start, the ring fills over the edge every frame (one CSS variable on the ring), the duration counts down, the disk's glyph turns to pause and the disk fades out (it stays while it has the keyboard focus); `onPlayingChange(true)`; any other sound pauses |
+| playing | the disk (or a press on the circle), `playing` / `defaultPlaying` | `data-playing="true"` on the root, `data-state="playing"`; sound from the start, the ring (the kit ring at its `band` weight, in the accent) fills over the edge every frame (one CSS variable on the ring), the duration counts down, the disk's glyph turns to pause and the disk fades out (it stays while it has the keyboard focus); `onPlayingChange(true)`; any other sound pauses |
 | paused | the disk or the circle again, another sound starting, `playing={false}` | `data-state="paused"`, the disk with the play glyph comes back, the ring stays; `onPlayingChange(false)` |
 | sought | an arrow, PageUp / PageDown, Home / End on the disk | the position moves (5 s, a tenth, the edges), the ring and the description follow; from rest it stops there, paused |
 | ended | the media ends | rewound, the ring empties, the still first frame and the play disk; `onPlayingChange(false)`, `onEnded` |
-| unplayed | `unplayed` | the accent dot and `labels.unplayed` in the description |
+| unplayed | `unplayed` | the accent dot in the duration pill (it rises in, and closes up in place when `unplayed` clears) and `labels.unplayed` in the description |
 | disabled | `disabled`, or a disabled `Fieldset` around it | `data-disabled="true"`; the circle and its duration dim to 0.6, the disk, the transcript button and the transfer disk are natively `disabled`; nothing plays by a press, a key or `playing` |
 | transferring | `transfer` `queued` / `loading`, `transferProgress` | `data-transfer="true"`; the circle dims to 0.6 and the play disk itself becomes the transfer in the same place and look (the play glyph cross-fades into a white ×; the share is the Button's `progress` ring along its inner edge — the kit ring at the line weight, a 32% track, gliding `base`, always turning; a quarter arc without a share); the button is `aria-busy`, described by `uploadProgress` / `downloadProgress`; nothing plays until it is done |
 | transfer failed | `transfer="failed"` | `data-transfer="true"`, the circle dims to 0.6; the disk turns danger with a retry arrow (`retryUpload` / `retryDownload`, described by `notSent` / `notReceived`); `onRetry` |
@@ -96,7 +96,7 @@ One look. The circle is the video; the play disk and the pills stand on the medi
 | transcript failed | `onTranscribe` rejects | the area closes, `onTranscriptExpandedChange(false)`, `labels.transcribeFailed` announced; the next open asks again |
 
 ## Layout & spacing
-- The circle is one square box: `min(--prime-message-video-note × 1.15, 100cqi)` wide with `aspect-ratio: 1`; everything in it fills it, so it stays a perfect circle at every width from 320px.
+- The circle is one square box: `min(--prime-message-video-note-box, 100cqi)` wide with `aspect-ratio: 1`; everything in it fills it, so it stays a perfect circle at every width.
 - The duration pill stands at the bottom-start corner, the message's meta pill at the bottom-end corner, the transcript button at the top-end corner of the square — where the circle leaves room — the place a voice message has it, at the end of its top row.
 - The duration and the meta read like a voice message's time row: the caption size and regular weight in the muted tone of the media pill (`--prime-color-media-pill-fg` on `--prime-color-media-pill`), AA over a white frame.
 - The transcript opens under the circle in a block of the message's fill (`--prime-message-padding-*`, `--prime-message-radius`). In a chat, opening and closing it is one motion of the message: the height and the width change together and the text fades in or out where it stands, the circle never moves. The text is selectable, and the chat search marks its matches in it.
@@ -107,6 +107,8 @@ One look. The circle is the video; the play disk and the pills stand on the medi
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 | Key | Action |
 |---|---|
 | `Tab` | Moves focus: the play disk (or the transfer disk), the transcript button. |
@@ -117,6 +119,8 @@ One look. The circle is the video; the play disk and the pills stand on the medi
 | `Home` · `End` | On the disk: 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 play disk is a button named `labels.play` / `labels.pause`, described by the duration (`labels.duration`) or the position (`labels.position`) and `labels.unplayed`; the pills are `aria-hidden`, and the press area over the whole circle is a pointer aid only (`aria-hidden`).
 - While the note is on its way, failed or not fetched, the play button itself is the transfer, named by the direction (`cancelUpload` / `cancelDownload` described by `uploadProgress` / `downloadProgress`, `retryUpload` / `retryDownload` described by `notSent` / `notReceived`, `download`); its ring is `aria-hidden`; a refused action is announced (`role="status"`).
@@ -130,10 +134,10 @@ One look. The circle is the video; the play disk and the pills stand on the medi
 |---|---|---|
 | `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`. |
 | `duration` | `"Длительность {duration}"` | The play disk's description before playback (during it, `position`). |
+| `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. |
@@ -169,5 +173,5 @@ One look. The circle is the video; the play disk and the pills stand on the medi
 - `transferDirection` used to restyle → it changes only the words; the look is one both ways.
 
 ## Related
-- **Built from:** [Button](../button/COMPONENT.md) (the play disk, `shape="circle"` `variant="shade"`; the transcript button), [Skeleton](../skeleton/COMPONENT.md), [Spinner](../spinner/COMPONENT.md), Icon (`action.play`, `action.pause`, `action.close`, `action.refresh`, `action.download`, `action.transcribe`, `nav.chevronUp`, `status.failed`); `internal/mediaPlayer` (the shared props, the play disk, the transcript button, the keyboard seek, the playing triad, the transfer — with VoicePlayer), `internal/disabledContext` (a disabled `Fieldset`), `internal/mediaSession` (one sound at a time), `internal/transferDisk` (the transfer's logic), `internal/ring` (the playback ring), `internal/mediaPill` (pills and marks), `internal/transcript` + `internal/Disclosure` (the transcript), `internal/messagePart` (the round part of a message)
+- **Built from:** [Button](../button/COMPONENT.md) (the play disk, `shape="circle"` `variant="shade"`; the transcript button), [Skeleton](../skeleton/COMPONENT.md), [Spinner](../spinner/COMPONENT.md), Icon (`action.play`, `action.pause`, `action.close`, `action.refresh`, `action.download`, `action.transcribe`, `nav.chevronUp`, `status.failed`); `internal/mediaPlayer` (the shared props, the play disk, the transcript button, the keyboard seek, the playing triad, the transfer — with VoicePlayer), `internal/disabledContext` (a disabled `Fieldset`), `internal/mediaSession` (one sound at a time), `internal/transferDisk` (the transfer's logic), `internal/ring` (the playback ring), `internal/mediaPill` (pills and marks), `internal/transcript` + `internal/Disclosure` (the transcript), `internal/messagePart` (the round part of a message), [VisuallyHidden](../visually-hidden/COMPONENT.md)
 - **See also:** [VoicePlayer](../voice-player/COMPONENT.md) — the voice message, the same player contract; [Message](../message/COMPONENT.md) — the chat it sits in; [Composer](../composer/COMPONENT.md) — records the video message

package/src/components/visually-hidden/COMPONENT.md

@@ -6,8 +6,8 @@
 > Text that screen readers read and nobody sees: the words behind an icon, a badge or a change on the screen.
 
 ## When to use
-- A count or a status the layout shows by position or colour, said in words («: три счёта ждут оплаты»).
-- An announcement after an action that changes no visible text: `role="status"` + `aria-live="polite"`, the message set after the action.
+- A count or a status the layout shows by position or colour, said in words («ждут оплаты: 3»).
+- An announcement after an action that changes no visible text: `live="polite"`, the message set after the action.
 - A description for `aria-describedby` that sighted users read elsewhere on the screen.
 
 ## When not to use
@@ -37,7 +37,7 @@ VisuallyHidden    <span>: out of sight (1px, clipped), pinned to its containing
 |---|---|---|---|
 | `children` | `ReactNode` | — | The text to read. |
 | `live` | `"polite" \| "assertive"` | — | An announcement region, read as a whole on every change: `polite` — `role="status"`, `assertive` — `role="alert"` (urgent only). |
-| `…rest` | `HTMLAttributes<HTMLSpanElement>` | — | `id` (to point `aria-describedby` at it), `className` and the other span attributes. |
+| `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "role" \| "aria-live" \| "aria-atomic" \| "aria-relevant">` | — | `id` (to point `aria-describedby` at it), `className` and the other span attributes; the region attributes come only from `live`. |
 
 ## Variants
 One look: none. It renders no pixels and takes no room.
@@ -55,9 +55,13 @@ One look: none. It renders no pixels and takes no room.
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 No keyboard interaction.
 
 ### ARIA
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 - The text stays in the accessibility tree: it joins the accessible name of the element around it.
 - With `live="polite"` it is a polite live region (`role="status"`), with `live="assertive"` an alert (`role="alert"`) for what cannot wait; keep it mounted and change its text — a region mounted together with its message is often not read.
 
@@ -75,7 +79,7 @@ No `labels`.
 ## Mistakes
 - `display: none` or `hidden` for screen-reader text → both remove it from the accessibility tree.
 - A live region mounted with its first message → mount it empty, then set the text.
-- `role="status"` and `aria-live` written by hand → `live="polite"` sets them together, atomic.
+- `role="status"` and `aria-live` written by hand → `live="polite"` sets them together, atomic; the props have no `role` / `aria-live`, and `live` wins over any passed through.
 - `live="assertive"` for a routine result («Сохранено») → it interrupts the reader; keep it for errors that block.
 - VisuallyHidden as the only name of a button that has `aria-label` → the `aria-label` wins; use one of them.
 - Hidden text that repeats the visible label → screen readers read it twice.

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

@@ -27,7 +27,7 @@ export default function VisuallyHiddenAssertiveExample() {
         Сохранить счёт
       </Button.Root>
       {failed ? (
-        <Badge.Root color="red" aria-hidden="true">
+        <Badge.Root tone="danger" aria-hidden="true">
           Не сохранено
         </Badge.Root>
       ) : null}

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. |
@@ -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/layout/app-header/COMPONENT.md

@@ -8,7 +8,8 @@
 ## When to use
 - 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: the menu button that opens the off-canvas Sidebar, the title, the page's action as an icon.
+- 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 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.
@@ -22,9 +23,9 @@ import { AppHeader } from "prime-ui-kit";
 
 ## Anatomy
 ```
-AppHeader.Root               <header>, the page's 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)
+│  ├─ (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
@@ -40,7 +41,7 @@ The name of `AppHeader.Title` (not the icon or the description) is the page's `<
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
 ### AppHeader.Root
-`ref` → `HTMLElement`. The page's sticky `<header>` bar at the top of the content panel: only what the current page needs — its title, tools and own buttons. As high as the Sidebar brand row, 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 |
 |---|---|---|---|
@@ -76,14 +77,14 @@ The name of `AppHeader.Title` (not the icon or the description) is the page's `<
 | `…rest` | `HTMLAttributes<HTMLSpanElement>` | — | `children`, `className` and the other span attributes. |
 
 ### AppHeader.Separator
-`ref` → `HTMLDivElement`. A short vertical `Divider` (20) between groups in a zone — the path and the title — 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. |
+| `…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 |
 |---|---|---|---|
@@ -97,21 +98,14 @@ The name of `AppHeader.Title` (not the icon or the description) is the page's `<
 | `…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 |
 |---|---|---|---|
@@ -120,20 +114,22 @@ The name of `AppHeader.Title` (not the icon or the description) is the page's `<
 | 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 |
+| 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 |
-| menu button hidden | `show="narrow"` and viewport from 768px | `data-show="narrow"` on MenuButton |
 | 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. Main's top air (24, 32 from 1024px) stands between the header and the page's first block.
-- Icon buttons are `soft` neutral (MenuButton 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` 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.
@@ -143,14 +139,18 @@ The name of `AppHeader.Title` (not the icon or the description) is the page's `<
 ## 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 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.
-- MenuButton is named by `labels.menu`; pass `aria-expanded` (whether the Sidebar is open).
+- 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.
 
@@ -159,7 +159,7 @@ The name of `AppHeader.Title` (not the icon or the description) is the page's `<
 
 | 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 |
@@ -168,7 +168,7 @@ The name of `AppHeader.Title` (not the icon or the description) is the page's `<
 | [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 title and its line of data truncate and the page's action keeps its 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.
@@ -178,9 +178,10 @@ The name of `AppHeader.Title` (not the icon or the description) is the page's `<
 - Page tools crammed into `AppHeader.Actions` → `AppHeader.Tools` with a PageToolbar: it wraps under the title instead of squeezing it.
 - 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 → `AppHeader.MenuButton` follows the Sidebar breakpoint.
+- 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), [Divider](../../components/divider/COMPONENT.md), Icon (`nav.menu`)
+- **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/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 title and its line of data truncate. */
+/* 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);
-}