prime-ui-kit 0.13.1 → 0.15.0

package/dist/skill/reference/components/textarea/examples/in-form.tsx

@@ -1,5 +1,5 @@
 /** Support request form: the description is checked on submit, its error leaves as soon as the text is long enough and does not shift the form, a sent request turns the button green — `required`, `error`, `reserveSupportRow`. */
-import { Button, Input, Textarea, Typography } from "prime-ui-kit";
+import { Button, Input, Textarea } from "prime-ui-kit";
 import * as React from "react";
 
 import styles from "./examples.module.css";
@@ -23,14 +23,6 @@ export default function TextareaInFormExample() {
 
   return (
     <form className={styles.form} noValidate onSubmit={submit}>
-      <div className={styles.formHeader}>
-        <Typography as="h3" variant="title-m">
-          Обращение в поддержку
-        </Typography>
-        <Typography as="p" variant="body-s" tone="secondary">
-          Ответим в течение рабочего дня.
-        </Typography>
-      </div>
       <div className={styles.formFields}>
         <Input.Root label="Тема" required>
           <Input.Wrapper>

package/dist/skill/reference/components/textarea/examples/states.tsx

@@ -1,4 +1,4 @@
-/** A default field next to a read-only and a disabled one — `readOnly`, `disabled`. */
+/** A default field next to a read-only, a disabled and an invalid one with no message — `readOnly`, `disabled`, `invalid`. */
 import { Textarea } from "prime-ui-kit";
 
 export default function TextareaStatesExample() {
@@ -16,6 +16,7 @@ export default function TextareaStatesExample() {
         placeholder="Причина возврата"
         hint="Станет доступно после выбора заказа"
       />
+      <Textarea.Root label="invalid" invalid defaultValue="Не подошёл размер" />
     </>
   );
 }

package/dist/skill/reference/components/thumbnail/COMPONENT.md

@@ -171,9 +171,10 @@ No `labels`.
 | [sizes.tsx](examples/sizes.tsx) | Every height tier, 24 to 64 px; `m` fits a two-line table cell — `size`. |
 | [states.tsx](examples/states.tsx) | No image (an icon or a short label on the fill) and an image that fails and falls back by itself. |
 | [ratios.tsx](examples/ratios.tsx) | Every aspect ratio at the same height; keep one ratio per list — `ratio`. |
+| [fit.tsx](examples/fit.tsx) | A supplier's wide banner in a square frame: cropped to fill or shown whole on the fill — `fit`. |
 | [ring.tsx](examples/ring.tsx) | A faint inner ring for a white-background photo on a light surface, where the edge would vanish — `ring`. |
 | [full-width.tsx](examples/full-width.tsx) | Covers in a card grid take the card width and keep 16:9, so every cover has one height — `fullWidth`. |
-| [video.tsx](examples/video.tsx) | Videos in the frame: a walkthrough without a poster shows its first frame, a play mark and the duration; a short clip loops muted like a GIF; a video message plays in place with its controls — `Thumbnail.Video`, `autoPlay`, `controls`. |
+| [video.tsx](examples/video.tsx) | Videos in the frame: a walkthrough without a poster shows its first frame, a play mark and the duration; a briefing shows its poster and its own duration format; a short clip loops muted like a GIF; a video message plays in place with its controls — `Thumbnail.Video`, `poster`, `formatDuration`, `autoPlay`, `controls`. |
 | [pressable.tsx](examples/pressable.tsx) | Photos of a delivery that open a viewer: the frame is put on a button, so it lifts on hover, presses and takes the focus ring — `asChild`. |
 | [controlled.tsx](examples/controlled.tsx) | A media library picks photos for a listing: each tile is a checkbox with its check in the corner, the selection lives in the parent and a button clears it — `checked`, `onCheckedChange`. |
 

package/dist/skill/reference/components/thumbnail/examples/examples.module.css

@@ -1,6 +1,6 @@
 /* Layout of the Thumbnail scenarios: semantic tokens only. */
 
-/* ratios.tsx, ring.tsx: thumbnails with captions in one line. */
+/* ratios.tsx, fit.tsx, ring.tsx: thumbnails with captions in one line. */
 .row {
   display: flex;
   flex-wrap: wrap;

package/dist/skill/reference/components/thumbnail/examples/fit.tsx

@@ -0,0 +1,24 @@
+/** A supplier's wide banner in a square frame: cropped to fill or shown whole on the fill — `fit`. */
+import { Thumbnail, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const BANNER = "https://picsum.photos/seed/supplier-banner/480/160";
+const FITS = ["cover", "contain"] as const;
+
+export default function ThumbnailFitExample() {
+  return (
+    <div className={styles.row}>
+      {FITS.map((fit) => (
+        <div key={fit} className={styles.cell}>
+          <Thumbnail.Root size="xl" color="gray">
+            <Thumbnail.Image src={BANNER} fit={fit} alt="Ферма поставщика «Северное хозяйство»" />
+          </Thumbnail.Root>
+          <Typography as="span" variant="caption" tone="muted">
+            {fit}
+          </Typography>
+        </div>
+      ))}
+    </div>
+  );
+}

package/dist/skill/reference/components/thumbnail/examples/video.tsx

@@ -1,9 +1,12 @@
-/** Videos in the frame: a walkthrough without a poster shows its first frame, a play mark and the duration; a short clip loops muted like a GIF; a video message plays in place with its controls — `Thumbnail.Video`, `autoPlay`, `controls`. */
+/** Videos in the frame: a walkthrough without a poster shows its first frame, a play mark and the duration; a briefing shows its poster and its own duration format; a short clip loops muted like a GIF; a video message plays in place with its controls — `Thumbnail.Video`, `poster`, `formatDuration`, `autoPlay`, `controls`. */
 import { Icon, Thumbnail, Typography } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
 
 const CLIP = "https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4";
+const POSTER = "https://picsum.photos/seed/safety-briefing/640/360";
+
+const formatSeconds = (seconds: number) => `${Math.round(seconds)} с`;
 
 export default function ThumbnailVideoExample() {
   return (
@@ -19,6 +22,22 @@ export default function ThumbnailVideoExample() {
           Обход склада · без обложки
         </Typography>
       </div>
+      <div className={styles.cardContent}>
+        <Thumbnail.Root fullWidth ratio="16:9">
+          <Thumbnail.Video
+            src={CLIP}
+            poster={POSTER}
+            formatDuration={formatSeconds}
+            aria-label="Инструктаж по технике безопасности"
+          />
+          <Thumbnail.Fallback>
+            <Icon name="action.play" />
+          </Thumbnail.Fallback>
+        </Thumbnail.Root>
+        <Typography variant="caption" tone="muted">
+          Инструктаж · обложка, длительность в секундах
+        </Typography>
+      </div>
       <div className={styles.cardContent}>
         <Thumbnail.Root fullWidth ratio="16:9">
           <Thumbnail.Video src={CLIP} autoPlay aria-label="Как собрать заказ, ролик" />

package/dist/skill/reference/components/timeline/COMPONENT.md

@@ -165,7 +165,7 @@ No `labels`.
 | [variants.tsx](examples/variants.tsx) | Dot hues for categories at reduced emphasis, and status tones on items, values and gaps at full emphasis — `color`, `tone`. |
 | [sizes.tsx](examples/sizes.tsx) | Every tier scales text, dot and row rhythm, rows 40 to 76 px — `size`. |
 | [structure.tsx](examples/structure.tsx) | A service history with intervals between events, a caption on the right of a gap and a second value line — `Timeline.Gap`, `Timeline.GapMeta`, `Timeline.ValueMeta`. |
-| [links.tsx](examples/links.tsx) | Rows that open an operation page become links, one Tab stop each with a focus ring — `href`. |
+| [links.tsx](examples/links.tsx) | Rows that open something: an operation page by a link or by your router link through the slot, a receipt in place by a button; one Tab stop each with a focus ring — `href`, `asChild`, `onClick`. |
 | [narrow.tsx](examples/narrow.tsx) | At 375 px the title wraps and the amount stays right; below 20rem of its own width the amount moves under the meta line. |
 
 ## Mistakes

package/dist/skill/reference/components/timeline/examples/examples.module.css

@@ -6,14 +6,6 @@
   width: min(100%, calc(var(--prime-space-24) * 5));
 }
 
-.stack {
-  display: flex;
-  flex-direction: column;
-  gap: var(--prime-space-10);
-  width: min(100%, calc(var(--prime-space-24) * 5));
-  min-width: 0;
-}
-
 /* narrow.tsx: a 375px phone column. */
 .phone {
   width: min(100%, calc(var(--prime-space-1) * 93.75));

package/dist/skill/reference/components/timeline/examples/links.tsx

@@ -1,28 +1,69 @@
-/** Rows that open an operation page become links, one Tab stop each with a focus ring — `href`. */
-import { Timeline } from "prime-ui-kit";
+/** Rows that open something: an operation page by a link or by your router link through the slot, a receipt in place by a button; one Tab stop each with a focus ring — `href`, `asChild`, `onClick`. */
+import { Button, Drawer, Timeline } from "prime-ui-kit";
+import * as React from "react";
 
 import styles from "./examples.module.css";
 
-const EVENTS = [
+const OPERATIONS = [
   { id: "rent-ivan", title: "Аренда закончилась · Иван К.", date: "21.09.26", value: "+6 300 ₽" },
   { id: "oil", title: "ТО: замена масла", date: "10.09.26", value: "−689 ₽" },
-  { id: "wash", title: "Мойка и химчистка салона", date: "01.09.26", value: "−450 ₽" },
 ];
 
+const WASH = { title: "Мойка и химчистка салона", date: "01.09.26", value: "−450 ₽" };
+
 export default function TimelineLinksExample() {
+  const [receiptOpen, setReceiptOpen] = React.useState(false);
+
   return (
-    <Timeline.Root className={styles.feed}>
-      <Timeline.Group label="Операции">
-        {EVENTS.map((event) => (
-          <Timeline.Item key={event.id} href={`#${event.id}`}>
-            <Timeline.Title>{event.title}</Timeline.Title>
+    <>
+      <Timeline.Root className={styles.feed}>
+        <Timeline.Group label="Операции">
+          {OPERATIONS.map((operation) => (
+            <Timeline.Item key={operation.id} href={`#${operation.id}`}>
+              <Timeline.Title>{operation.title}</Timeline.Title>
+              <Timeline.Meta>
+                <Timeline.MetaPrimary>{operation.date}</Timeline.MetaPrimary>
+              </Timeline.Meta>
+              <Timeline.Value>{operation.value}</Timeline.Value>
+            </Timeline.Item>
+          ))}
+          {/* The receipt opens in place: the row is a button. */}
+          <Timeline.Item onClick={() => setReceiptOpen(true)}>
+            <Timeline.Title>{WASH.title}</Timeline.Title>
             <Timeline.Meta>
-              <Timeline.MetaPrimary>{event.date}</Timeline.MetaPrimary>
+              <Timeline.MetaPrimary>{WASH.date}</Timeline.MetaPrimary> · чек
             </Timeline.Meta>
-            <Timeline.Value>{event.value}</Timeline.Value>
+            <Timeline.Value>{WASH.value}</Timeline.Value>
           </Timeline.Item>
-        ))}
-      </Timeline.Group>
-    </Timeline.Root>
+          {/* A router link (`<Link to>`) goes in the same way. */}
+          <Timeline.Item asChild>
+            <a href="#operations-archive">
+              <Timeline.Title>Операции за август</Timeline.Title>
+              <Timeline.Meta>
+                <Timeline.MetaPrimary>14 операций</Timeline.MetaPrimary>
+              </Timeline.Meta>
+            </a>
+          </Timeline.Item>
+        </Timeline.Group>
+      </Timeline.Root>
+
+      <Drawer.Root open={receiptOpen} onOpenChange={setReceiptOpen}>
+        <Drawer.Content size="s">
+          <Drawer.Header>
+            <Drawer.Title>{WASH.title}</Drawer.Title>
+            <Drawer.Description>
+              Чек от {WASH.date} · {WASH.value}
+            </Drawer.Description>
+          </Drawer.Header>
+          <Drawer.Footer>
+            <Drawer.Close>
+              <Button.Root variant="outline" tone="neutral">
+                Закрыть
+              </Button.Root>
+            </Drawer.Close>
+          </Drawer.Footer>
+        </Drawer.Content>
+      </Drawer.Root>
+    </>
   );
 }

package/dist/skill/reference/components/timeline/examples/narrow.tsx

@@ -20,7 +20,7 @@ const EVENTS = [
 
 export default function TimelineNarrowExample() {
   return (
-    <div className={styles.stack}>
+    <>
       {WIDTHS.map((width) => (
         <Timeline.Root key={width.id} className={width.className}>
           <Timeline.Group label={width.label}>
@@ -36,6 +36,6 @@ export default function TimelineNarrowExample() {
           </Timeline.Group>
         </Timeline.Root>
       ))}
-    </div>
+    </>
   );
 }

package/dist/skill/reference/components/timeline/examples/sizes.tsx

@@ -7,9 +7,9 @@ const SIZES = ["xs", "s", "m", "l", "xl"] as const;
 
 export default function TimelineSizesExample() {
   return (
-    <div className={styles.stack}>
+    <>
       {SIZES.map((size) => (
-        <Timeline.Root key={size} size={size}>
+        <Timeline.Root key={size} size={size} className={styles.feed}>
           <Timeline.Group label={size}>
             <Timeline.Item>
               <Timeline.Title>Аренда закончилась · Иван К.</Timeline.Title>
@@ -28,6 +28,6 @@ export default function TimelineSizesExample() {
           </Timeline.Group>
         </Timeline.Root>
       ))}
-    </div>
+    </>
   );
 }

package/dist/skill/reference/components/timeline/examples/variants.tsx

@@ -27,8 +27,8 @@ const TONES: { tone: Tone; title: string; value: string }[] = [
 
 export default function TimelineVariantsExample() {
   return (
-    <div className={styles.stack}>
-      <Timeline.Root>
+    <>
+      <Timeline.Root className={styles.feed}>
         <Timeline.Group label="color">
           {COLORS.map((color) => (
             <Timeline.Item key={color} color={color}>
@@ -38,7 +38,7 @@ export default function TimelineVariantsExample() {
           ))}
         </Timeline.Group>
       </Timeline.Root>
-      <Timeline.Root>
+      <Timeline.Root className={styles.feed}>
         <Timeline.Group label="tone">
           {TONES.map(({ tone, title, value }) => (
             <Timeline.Item key={tone} tone={tone}>
@@ -51,6 +51,6 @@ export default function TimelineVariantsExample() {
           <Timeline.Gap tone="danger">Просрочка 30 дней</Timeline.Gap>
         </Timeline.Group>
       </Timeline.Root>
-    </div>
+    </>
   );
 }

package/dist/skill/reference/components/tooltip/COMPONENT.md

@@ -70,7 +70,7 @@ No DOM of its own: clones the single child and links it to the tooltip with `ari
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `side` | `"top" \| "bottom" \| "left" \| "right"` | `"top"` | Preferred side; flips to the opposite one when it does not fit, then shifts inside the viewport. |
-| `align` | `"start" \| "center" \| "end"` | `"center"` | Alignment along the trigger: its start edge, centre or end edge; the arrow keeps pointing at the trigger. |
+| `align` | `"auto" \| "start" \| "center" \| "end"` | `"center"` | Alignment along the trigger: centred by default; `auto` lines the chip up with the trigger edge that has more room beyond it; `start` or `end` fix the edge. The arrow keeps pointing at the trigger. |
 | `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Text and padding tier; also the size context of controls inside (a Kbd). |
 | `children` | `ReactNode` | — (required) | Hint text, optionally with a Kbd. |
 | `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "id" \| "role" \| "onPointerEnter" \| "onPointerLeave">` | — | `className`, `style` and the other attributes of the chip. |
@@ -100,9 +100,10 @@ A chip of tier T is as tall as a menu item of tier T; text, padding and radius s
 ### align (Content)
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| `start` | Chip starts at the trigger's start edge | Wide triggers, triggers at a container's start | |
 | `center` | Chip centred on the trigger | Most triggers | yes |
-| `end` | Chip ends at the trigger's end edge | Triggers at a container's end | |
+| `auto` | Lined up with the trigger edge that has more room: near the end of the screen the end edges meet and the chip grows toward the start, near the start the other way | A long chip on a wide trigger near a screen edge | |
+| `start` | Chip starts at the trigger's start edge | The chip must line up with the start of a block whatever room there is | |
+| `end` | Chip ends at the trigger's end edge | The chip must line up with the end of a block whatever room there is | |
 
 **Combinations** — size of the tooltip = size of the trigger control; a Kbd inside takes the tier one step down by itself.
 
@@ -133,6 +134,7 @@ A chip of tier T is as tall as a menu item of tier T; text, padding and radius s
 - `Tooltip.Trigger` composes the child's `ref`, sets `data-state` and chains the child's `onPointerEnter`, `onPointerLeave`, `onPointerDown`, `onFocus` and `onBlur`.
 - The tooltip is a description, not the name: an icon-only button needs its own `aria-label`.
 - The pointer may move onto the chip without closing it (WCAG 1.4.13); a touch does not open it, focus does.
+- Tooltip has no `closeOnEscape` / `closeOnOutsideClick` (foundation §8): it closes on pointer-leave, blur, a press on the trigger and Escape, and Escape cannot be turned off — WCAG 1.4.13 requires the chip to be dismissable without moving the pointer or focus.
 - A `disabled` control is wrapped by the kit in a focusable `<span>`: the host takes hover and Tab, the focus ring is drawn on the control.
 - A trigger that is no tab stop (Badge, Avatar, ProgressCircle, `Icon` with `label`) gets `tabIndex={0}` and the focus ring; its name comes from `aria-label` or the icon `label`.
 
@@ -146,8 +148,8 @@ No `labels`.
 |---|---|
 | [overview.tsx](examples/overview.tsx) | An icon-only button with a tooltip that repeats its name on hover and keyboard focus — `Tooltip.Trigger`, `Tooltip.Content`. |
 | [sizes.tsx](examples/sizes.tsx) | Every size tier next to buttons of the same tier; take the tier of the control it describes — `size`. |
-| [placement.tsx](examples/placement.tsx) | Every side, and start / end alignment along the trigger; without room the chip flips and shifts, the arrow keeps pointing at the trigger — `side`, `align`. |
-| [toolbar.tsx](examples/toolbar.tsx) | A formatting toolbar in one group: after the first tooltip the neighbours open at once, each with its name and shortcut — `Tooltip.Provider`. |
+| [placement.tsx](examples/placement.tsx) | Every side, and alignment by room, start and end along the trigger; without room the chip flips and shifts, the arrow keeps pointing at the trigger — `side`, `align`. |
+| [toolbar.tsx](examples/toolbar.tsx) | A formatting toolbar in one group: after the first tooltip the neighbours open at once for half a second, each with its name and shortcut — `Tooltip.Provider`, `skipDelayDuration`. |
 | [disabled-trigger.tsx](examples/disabled-trigger.tsx) | Why an action is unavailable: the disabled button still shows its tooltip on hover and Tab, no wrapper needed — `Tooltip.Trigger`. |
 | [non-interactive-trigger.tsx](examples/non-interactive-trigger.tsx) | A status badge, an avatar and an information icon explain themselves: the kit makes each a tab stop, so the tooltip opens from the keyboard too — `Tooltip.Trigger`. |
 | [delay.tsx](examples/delay.tsx) | The show delay of one tooltip: at once, the default 400 ms and one second — `delayDuration`. |

package/dist/skill/reference/components/tooltip/examples/placement.tsx

@@ -1,4 +1,4 @@
-/** Every side, and start / end alignment along the trigger; without room the chip flips and shifts, the arrow keeps pointing at the trigger — `side`, `align`. */
+/** Every side, and alignment by room, start and end along the trigger; without room the chip flips and shifts, the arrow keeps pointing at the trigger — `side`, `align`. */
 import { Button, Tooltip } from "prime-ui-kit";
 
 const PLACEMENTS = [
@@ -6,6 +6,7 @@ const PLACEMENTS = [
   { side: "bottom", align: "center" },
   { side: "left", align: "center" },
   { side: "right", align: "center" },
+  { side: "bottom", align: "auto" },
   { side: "bottom", align: "start" },
   { side: "bottom", align: "end" },
 ] as const;

package/dist/skill/reference/components/tooltip/examples/toolbar.tsx

@@ -1,4 +1,4 @@
-/** A formatting toolbar in one group: after the first tooltip the neighbours open at once, each with its name and shortcut — `Tooltip.Provider`. */
+/** A formatting toolbar in one group: after the first tooltip the neighbours open at once for half a second, each with its name and shortcut — `Tooltip.Provider`, `skipDelayDuration`. */
 import { Button, Icon, Kbd, Tooltip } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
@@ -13,7 +13,7 @@ const TOOLS = [
 
 export default function TooltipToolbarExample() {
   return (
-    <Tooltip.Provider>
+    <Tooltip.Provider skipDelayDuration={500}>
       <div className={styles.toolbar} role="toolbar" aria-label="Форматирование">
         {TOOLS.map(({ icon, label, keys }) => (
           <Tooltip.Root key={label}>

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

@@ -79,7 +79,7 @@ One look. The circle is the video; the play disk and the pills stand on the medi
 ## States
 | State | Driven by | DOM |
 |---|---|---|
-| loading | the first frame not drawn yet | `data-frame="loading"` on the circle: a Skeleton fills it, the video fades in (`base`) once loaded |
+| 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 |
 | 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)` |
@@ -155,10 +155,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.

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

@@ -69,7 +69,8 @@ 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.

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 color="red" aria-hidden="true">
+          Не сохранено
+        </Badge.Root>
+      ) : null}
+      <VisuallyHidden live="assertive">
+        {failed ? "Счёт не сохранён: нет связи с сервером. Повторите попытку." : ""}
+      </VisuallyHidden>
+    </>
+  );
+}

package/dist/skill/reference/components/voice-player/COMPONENT.md

@@ -84,7 +84,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 leaves with a fade and scale | the recipient has not listened yet | |
+| `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 | |
 | `disabled` | muted disk, no played bars, disabled time | the recording cannot be played (deleted, expired) | |
 
 ## States
@@ -172,11 +172,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.

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="Запись звонка"
         />