prime-ui-kit 0.14.0 → 0.16.0

package/dist/skill/reference/components/typography/examples/weights.tsx

@@ -17,6 +17,9 @@ export default function TypographyWeightsExample() {
       <Typography variant="body-m" weight="semibold">
         {LINE} · semibold
       </Typography>
+      <Typography variant="body-m" tracking="tight">
+        {LINE} · tracking tight
+      </Typography>
       <Typography variant="body-m" tracking="tighter">
         {LINE} · tracking tighter
       </Typography>

package/dist/skill/reference/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. |
@@ -155,10 +159,10 @@ One look. The circle is the video; the play disk and the pills stand on the medi
 |---|---|
 | [overview.tsx](examples/overview.tsx) | A foreman's round video report: its still first frame with the play disk and the duration, played with sound on a press — `src`, `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`. |
-| [in-message.tsx](examples/in-message.tsx) | Round video messages in a field crew chat: the circle is the message itself, the time stands on its pill and the reply follows as text — `Message.Root`, `time`, `status`. |
+| [in-message.tsx](examples/in-message.tsx) | Round video messages in a field crew chat: the circle is the message itself, the time stands on its pill, the reply follows as text and the answer circle shows the cover its server made — `Message.Root`, `time`, `status`, `poster`. |
 | [transcript.tsx](examples/transcript.tsx) | Round video messages with a transcript: the button stands at the circle's top end like a voice message's, one text is known and one is asked for on the first open — `transcript`, `onTranscribe`. |
 | [transfer.tsx](examples/transfer.tsx) | One look for a round video on its way in either direction: the foreman's report waits to be fetched and then arrives, the engineer's answer is being sent — the disk in the middle with the ring of the share, the cross cancels, a dropped connection offers a retry, the circle plays once it is through — `transfer`, `transferProgress`, `transferDirection`, `onCancel`, `onRetry`, `onDownload`. |
-| [controlled.tsx](examples/controlled.tsx) | The parent knows what plays and marks the report as watched on the first play — `playing`, `onPlayingChange`, `unplayed`. |
+| [controlled.tsx](examples/controlled.tsx) | The parent knows what plays, marks the report as watched on the first play and as seen to the end when it ends, and keeps the transcript open — `playing`, `onPlayingChange`, `unplayed`, `onEnded`, `transcriptExpanded`, `onTranscriptExpandedChange`. |
 
 ## Mistakes
 - A `<video>` cropped round by hand in a bubble → use `VideoNote`: it plays one sound at a time, draws the transfer on its disk and keeps the meta on its pill.
@@ -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/dist/skill/reference/components/video-note/examples/controlled.tsx

@@ -1,12 +1,25 @@
-/** The parent knows what plays and marks the report as watched on the first play — `playing`, `onPlayingChange`, `unplayed`. */
+/** The parent knows what plays, marks the report as watched on the first play and as seen to the end when it ends, and keeps the transcript open — `playing`, `onPlayingChange`, `unplayed`, `onEnded`, `transcriptExpanded`, `onTranscriptExpandedChange`. */
 import { Typography, VideoNote } from "prime-ui-kit";
 import * as React from "react";
 
 const VIDEO_URL = "https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4";
 
+const TRANSCRIPT =
+  "Стойка собрана, кабели промаркированы. Жду подтверждения, чтобы включить питание.";
+
 export default function VideoNoteControlledExample() {
   const [playing, setPlaying] = React.useState(false);
   const [unplayed, setUnplayed] = React.useState(true);
+  const [seen, setSeen] = React.useState(false);
+  const [transcriptOpen, setTranscriptOpen] = React.useState(true);
+
+  const state = playing
+    ? "Воспроизводится"
+    : seen
+      ? "Досмотрено до конца"
+      : unplayed
+        ? "Ещё не просмотрено"
+        : "Просмотрено";
 
   return (
     <>
@@ -19,9 +32,13 @@ export default function VideoNoteControlledExample() {
           setPlaying(next);
           if (next) setUnplayed(false);
         }}
+        onEnded={() => setSeen(true)}
+        transcript={TRANSCRIPT}
+        transcriptExpanded={transcriptOpen}
+        onTranscriptExpandedChange={setTranscriptOpen}
       />
       <Typography as="p" variant="body-s" tone="secondary">
-        {playing ? "Воспроизводится" : unplayed ? "Ещё не просмотрено" : "Просмотрено"}
+        {state} · расшифровка {transcriptOpen ? "открыта" : "свёрнута"}
       </Typography>
     </>
   );

package/dist/skill/reference/components/video-note/examples/in-message.tsx

@@ -1,10 +1,13 @@
-/** Round video messages in a field crew chat: the circle is the message itself, the time stands on its pill and the reply follows as text — `Message.Root`, `time`, `status`. */
+/** Round video messages in a field crew chat: the circle is the message itself, the time stands on its pill, the reply follows as text and the answer circle shows the cover its server made — `Message.Root`, `time`, `status`, `poster`. */
 import { Message, VideoNote } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
 
 const VIDEO_URL = "https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4";
 
+/** The cover the media server made for the reply: shown at once, before the first frame. */
+const POSTER_URL = "https://picsum.photos/seed/server-rack/480/480";
+
 export default function VideoNoteInMessageExample() {
   return (
     <div className={styles.thread}>
@@ -15,7 +18,7 @@ export default function VideoNoteInMessageExample() {
         <Message.Text>Вижу, стойка собрана. Подключайте питание.</Message.Text>
       </Message.Root>
       <Message.Root direction="outgoing" time="13:51" status="read">
-        <VideoNote src={VIDEO_URL} duration={6} />
+        <VideoNote src={VIDEO_URL} duration={6} poster={POSTER_URL} />
       </Message.Root>
     </div>
   );

package/dist/skill/reference/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.
 
@@ -69,12 +73,13 @@ No `labels`.
 ## Examples
 | Example | Shows |
 |---|---|
-| [overview.tsx](examples/overview.tsx) | A count that sighted users read from the layout, said in words to screen readers, and a polite announcement after an action — `VisuallyHidden`. |
+| [overview.tsx](examples/overview.tsx) | A count that sighted users read from the layout, said in words to screen readers, and a polite announcement after an action — `VisuallyHidden`, `live`. |
+| [assertive.tsx](examples/assertive.tsx) | A failed save shown by a badge on screen and announced at once, interrupting the screen reader — `live`. |
 
 ## 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/dist/skill/reference/components/visually-hidden/examples/assertive.tsx

@@ -0,0 +1,39 @@
+/** A failed save shown by a badge on screen and announced at once, interrupting the screen reader — `live`. */
+import { Badge, Button, VisuallyHidden } from "prime-ui-kit";
+import * as React from "react";
+
+/** The server refusing the save a beat later. */
+const saveInvoice = () =>
+  new Promise<void>((_, reject) => setTimeout(() => reject(new Error("offline")), 700));
+
+export default function VisuallyHiddenAssertiveExample() {
+  const [saving, setSaving] = React.useState(false);
+  const [failed, setFailed] = React.useState(false);
+
+  const save = async () => {
+    setSaving(true);
+    setFailed(false);
+    try {
+      await saveInvoice();
+    } catch {
+      setFailed(true);
+    }
+    setSaving(false);
+  };
+
+  return (
+    <>
+      <Button.Root loading={saving} onClick={save}>
+        Сохранить счёт
+      </Button.Root>
+      {failed ? (
+        <Badge.Root tone="danger" aria-hidden="true">
+          Не сохранено
+        </Badge.Root>
+      ) : null}
+      <VisuallyHidden live="assertive">
+        {failed ? "Счёт не сохранён: нет связи с сервером. Повторите попытку." : ""}
+      </VisuallyHidden>
+    </>
+  );
+}

package/dist/skill/reference/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/dist/skill/reference/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/dist/skill/reference/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/dist/skill/reference/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>
     </>
   );