prime-ui-kit 0.10.0 → 0.11.1

package/src/components/thumbnail/examples/pressable.tsx

@@ -0,0 +1,56 @@
+/** 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`. */
+import { Icon, MediaViewer, type MediaViewerItem, Thumbnail } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const photoUrl = (id: string, width: number) =>
+  `https://picsum.photos/seed/delivery-${id}/${width}/${Math.round((width * 3) / 4)}`;
+
+const PHOTOS: MediaViewerItem[] = [
+  { id: "dock", title: "Разгрузка у ворот 3" },
+  { id: "pallets", title: "Паллеты после приёмки" },
+  { id: "label", title: "Маркировка коробки" },
+].map(({ id, title }) => ({
+  src: photoUrl(id, 1600),
+  thumbnail: photoUrl(id, 160),
+  width: 1600,
+  height: 1200,
+  alt: title,
+}));
+
+export default function ThumbnailPressableExample() {
+  const [open, setOpen] = React.useState(false);
+  const [index, setIndex] = React.useState(0);
+
+  return (
+    <>
+      <div className={styles.row}>
+        {PHOTOS.map((photo, at) => (
+          <Thumbnail.Root key={photo.src} asChild size="xl" ratio="4:3">
+            <button
+              type="button"
+              aria-label={`Открыть фото: ${photo.alt}`}
+              onClick={() => {
+                setIndex(at);
+                setOpen(true);
+              }}
+            >
+              <Thumbnail.Image src={photo.thumbnail ?? photo.src} />
+              <Thumbnail.Fallback>
+                <Icon name="object.image" />
+              </Thumbnail.Fallback>
+            </button>
+          </Thumbnail.Root>
+        ))}
+      </div>
+      <MediaViewer
+        items={PHOTOS}
+        open={open}
+        onOpenChange={setOpen}
+        index={index}
+        onIndexChange={setIndex}
+      />
+    </>
+  );
+}

package/src/components/thumbnail/examples/video.tsx

@@ -0,0 +1,46 @@
+/** 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`. */
+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";
+
+export default function ThumbnailVideoExample() {
+  return (
+    <div className={styles.media}>
+      <div className={styles.cardContent}>
+        <Thumbnail.Root fullWidth ratio="16:9">
+          <Thumbnail.Video src={CLIP} 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="Как собрать заказ, ролик" />
+          <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} controls aria-label="Видеосообщение от клиента" />
+          <Thumbnail.Fallback>
+            <Icon name="action.play" />
+          </Thumbnail.Fallback>
+        </Thumbnail.Root>
+        <Typography variant="caption" tone="muted">
+          Сообщение клиента · с контролами
+        </Typography>
+      </div>
+    </div>
+  );
+}

package/src/components/timeline/COMPONENT.md

@@ -14,6 +14,7 @@
 - Steps of a process the user goes through → use [Stepper](../stepper/COMPONENT.md).
 - Records with many attributes to compare or sort → use [DataTable](../data-table/COMPONENT.md).
 - Transient system messages → use [Notification](../notification/COMPONENT.md).
+- Work with a start and an end laid out on a calendar (tasks, bookings, occupancy) → use [Gantt](../gantt/COMPONENT.md).
 
 ## Import
 ```tsx
@@ -177,4 +178,4 @@ No `labels`.
 
 ## Related
 - **Built from:** —
-- **See also:** [Stepper](../stepper/COMPONENT.md), [DataTable](../data-table/COMPONENT.md), [Card](../card/COMPONENT.md)
+- **See also:** [Stepper](../stepper/COMPONENT.md), [DataTable](../data-table/COMPONENT.md), [Gantt](../gantt/COMPONENT.md), [Card](../card/COMPONENT.md)

package/src/components/tooltip/COMPONENT.md

@@ -7,7 +7,8 @@
 
 ## When to use
 - Name and shortcut of an icon-only button.
-- Why a control is disabled (wrap the disabled control in a focusable element).
+- Why a control is disabled: put the disabled control straight into `Tooltip.Trigger`.
+- What a status badge, an avatar or an information icon means.
 - A one-line definition of a term or abbreviation.
 
 ## When not to use
@@ -27,6 +28,7 @@ import { Tooltip } from "prime-ui-kit";
 Tooltip.Provider        optional; delay and skip-delay group for a subtree
 └── Tooltip.Root        state of one tooltip (no DOM)
     ├── Tooltip.Trigger clones its single child element and adds handlers
+    │                   (a focusable <span> around a disabled control)
     └── Tooltip.Content portaled role="tooltip" chip
         └── arrow       decorative svg pointing at the trigger's centre
 ```
@@ -56,11 +58,11 @@ No DOM, no ref. Its tooltips form a group: one is open at a time, and once one h
 | `children` | `ReactNode` | — (required) | Subtree. |
 
 ### Tooltip.Trigger
-No DOM: clones the single child, composes its `ref`, appends the tooltip id to its `aria-describedby` while open, sets `data-state` and chains `onPointerEnter`, `onPointerLeave`, `onPointerDown`, `onFocus`, `onBlur`.
+No DOM of its own: clones the single child and links it to the tooltip with `aria-describedby`. A `disabled` child is wrapped in a focusable `<span>`; a child that is no tab stop becomes one.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `children` | `ReactElement` | — (required) | One focusable element: a Button, or a `tabIndex={0}` wrapper around a disabled control. |
+| `children` | `ReactElement` | — (required) | One element: a control, a disabled control or a non-interactive element such as a Badge. |
 
 ### Tooltip.Content
 `ref` → `HTMLDivElement`. Portaled `role="tooltip"` chip with an arrow; renders while open and during its exit animation, placed before paint.
@@ -127,10 +129,12 @@ A chip of tier T is as tall as a menu item of tier T; text, padding and radius s
 | `Escape` | Hides the tooltip; focus stays on the trigger. |
 
 ### ARIA
-- The chip is `role="tooltip"`; while open the trigger points at it with `aria-describedby`.
+- The chip is `role="tooltip"`; while open the trigger points at it with `aria-describedby` (appended to the child's own).
+- `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.
-- A natively `disabled` button gets no events: wrap it in `<span tabIndex={0}>`.
+- 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`.
 
 ### Labels
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
@@ -144,13 +148,15 @@ No `labels`.
 | [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`. |
-| [disabled-trigger.tsx](examples/disabled-trigger.tsx) | Why an action is unavailable: a disabled button inside a focusable wrapper still shows its tooltip on hover and Tab — `Tooltip.Trigger`. |
+| [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`. |
 | [long-content.tsx](examples/long-content.tsx) | A sentence of explanation wraps at the tooltip max width; anything with actions belongs in a Popover — `Tooltip.Content`. |
 | [controlled-open.tsx](examples/controlled-open.tsx) | The parent owns the open state: a switch shows the tooltip from code, hover and focus still work — `open`, `onOpenChange`. |
 
 ## Mistakes
-- Tooltip on a `disabled` button directly → wrap the button in a focusable `span`.
+- Your own `<span tabIndex={0}>` around a disabled button → the trigger does it; a second wrapper adds a second tab stop.
+- An unnamed Badge or Icon as the trigger → give the icon `label` (or the element `aria-label`): the tooltip describes, it does not name.
 - Links or buttons inside Tooltip.Content → use Popover.
 - Several children inside Tooltip.Trigger → exactly one element.
 - Relying on the tooltip as the button's name → add `aria-label` to the button.

package/src/components/tooltip/examples/disabled-trigger.tsx

@@ -1,16 +1,11 @@
-/** Why an action is unavailable: a disabled button inside a focusable wrapper still shows its tooltip on hover and Tab — `Tooltip.Trigger`. */
+/** Why an action is unavailable: the disabled button still shows its tooltip on hover and Tab, no wrapper needed — `Tooltip.Trigger`. */
 import { Button, Tooltip } from "prime-ui-kit";
 
-import styles from "./examples.module.css";
-
 export default function TooltipDisabledTriggerExample() {
   return (
     <Tooltip.Root>
       <Tooltip.Trigger>
-        {/* biome-ignore lint/a11y/noNoninteractiveTabindex: the wrapper must be focusable to explain the disabled button */}
-        <span className={styles.disabledWrap} tabIndex={0}>
-          <Button.Root disabled>Опубликовать</Button.Root>
-        </span>
+        <Button.Root disabled>Опубликовать</Button.Root>
       </Tooltip.Trigger>
       <Tooltip.Content>Заполните обязательные поля, чтобы опубликовать</Tooltip.Content>
     </Tooltip.Root>

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

@@ -11,13 +11,10 @@
   box-shadow: var(--prime-shadow-raised);
 }
 
-/* disabled-trigger.tsx: a focusable wrapper around the disabled button, with the outer ring. */
-.disabledWrap {
-  display: inline-flex;
-  border-radius: var(--prime-control-m-radius);
-}
-
-.disabledWrap:focus-visible {
-  outline: var(--prime-focus-width) solid var(--prime-color-focus-ring);
-  outline-offset: var(--prime-focus-offset);
+/* non-interactive-trigger.tsx: the three triggers in one row. */
+.row {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--prime-space-4);
 }

package/src/components/tooltip/examples/non-interactive-trigger.tsx

@@ -0,0 +1,31 @@
+/** 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`. */
+import { Avatar, Badge, Icon, Tooltip } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function TooltipNonInteractiveTriggerExample() {
+  return (
+    <div className={styles.row}>
+      <Tooltip.Root>
+        <Tooltip.Trigger>
+          <Badge.Root color="orange">Просрочен</Badge.Root>
+        </Tooltip.Trigger>
+        <Tooltip.Content>Счёт не оплачен 12 дней, срок был 1 октября</Tooltip.Content>
+      </Tooltip.Root>
+      <Tooltip.Root>
+        <Tooltip.Trigger>
+          <Avatar.Root color="blue" aria-label="Анна Соколова">
+            <Avatar.Fallback>АС</Avatar.Fallback>
+          </Avatar.Root>
+        </Tooltip.Trigger>
+        <Tooltip.Content>Анна Соколова, ответственная по заказу</Tooltip.Content>
+      </Tooltip.Root>
+      <Tooltip.Root>
+        <Tooltip.Trigger>
+          <Icon name="status.locked" tone="muted" label="Системный статус" />
+        </Tooltip.Trigger>
+        <Tooltip.Content>Системный статус нельзя удалить или переименовать</Tooltip.Content>
+      </Tooltip.Root>
+    </div>
+  );
+}

package/src/components/typography/COMPONENT.md

@@ -83,6 +83,8 @@ Text has no interactive states.
 
 ## Layout & spacing
 - 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).
 - `truncate` needs a block element and a shrinking parent (`min-width: 0` in flex rows).
 

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

@@ -0,0 +1,173 @@
+# VideoNote
+
+**Category:** messages
+**Kind:** control
+
+> A round video message: a still first frame with the play disk that plays with sound on a press — the same player API as VoicePlayer.
+
+## When to use
+- A round video message in a chat — place it as the content of `Message.Root`: the circle is the message itself (no bubble), the time and status stand on a pill at its bottom-end corner, reactions under it.
+- A short face-to-camera report outside a chat: a site visit on a task, a reply on a ticket.
+
+## When not to use
+- A video with controls, chapters or a full-screen view → `Thumbnail.Video` or a video in `Message.Media`.
+- Audio only → [VoicePlayer](../voice-player/COMPONENT.md).
+- Recording a video message → [Composer](../composer/COMPONENT.md) `onSendVideoNote`.
+
+## Import
+```tsx
+import { VideoNote } from "prime-ui-kit";
+```
+
+## Anatomy
+```
+VideoNote              <div role="group">; data-playing · data-disabled · data-transfer
+├─ circle              the square box, a perfect circle at every width (data-state, data-frame)
+│  ├─ media            the round clip: Skeleton until the first frame, the <video preload="metadata">
+│  ├─ ring             playback ring over the edge (internal/ring, `live`: --ring-value written per frame)
+│  ├─ hit              the whole circle takes a press (a pointer aid, aria-hidden)
+│  ├─ play disk        the shared play disk, centred (internal/mediaPlayer PlayDisk): Button shape="circle"
+│  │                   variant="shade", play ⇄ pause, keyboard seek; fades while playing; with `transfer` the same
+│  │                   button carries ×, retry or download and the share as its `progress` ring (internal/transferDisk)
+│  ├─ duration         pill at the bottom-start corner, muted caption (internal/mediaPill)
+│  ├─ transcript       Button soft xs at the top-end corner, outside the circle's edge (internal/mediaPlayer TranscriptButton)
+│  └─ meta             in a message: its time and status on a pill at the bottom-end corner
+└─ transcript text     <div data-transcript> (internal/Disclosure) under the circle, in the message's fill
+```
+
+## API
+
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+### VideoNote
+`ref` → `HTMLDivElement` (the `role="group"` root). A round video message: a still first frame that plays with sound on a press. Inside `Message.Root` it is the message itself, without a bubble. Its props are VoicePlayer's (`MediaPlayerProps`) plus `poster`.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `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. |
+| `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. |
+| `defaultPlaying` | `boolean` | `false` | Initial playing state (uncontrolled). |
+| `onPlayingChange` | `(playing: boolean) => void` | — | Playback with sound started or stopped: the play disk, Enter / Space, another sound taking over, the end (then `onEnded` too); a seek from the keyboard does not count. |
+| `onEnded` | `() => void` | — | Playback reached the end; the note is back at its still first frame. |
+| `transcript` | `string` | — | The text of the recording, when it is known. With it or `onTranscribe` a «→A» button opens and closes the text: the button stands at the circle's top-end corner, the text opens under the circle. |
+| `onTranscribe` | `() => Promise<string> \| void` | — | Asks for the text on the first open while `transcript` is not known; return a Promise of the text. The button spins, then the text opens; a rejection announces `labels.transcribeFailed`. |
+| `transcriptExpanded` | `boolean` | — | The transcript is open (controlled). Opening it without a text calls `onTranscribe`. |
+| `defaultTranscriptExpanded` | `boolean` | `false` | Initially open (uncontrolled). In `Chat.Messages` the open state and a resolved text survive a row scrolled away and back. |
+| `onTranscriptExpandedChange` | `(expanded: boolean) => void` | — | The transcript button was pressed, or a rejected `onTranscribe` closed the transcript. |
+| `transfer` | `"remote" \| "queued" \| "loading" \| "failed" \| "done"` | — | The transfer of the note, drawn on the play disk itself, either way (`TransferState`): `queued` / `loading` — the cancel cross and the share ring; `failed` — retry; `remote` — download; `done` — the disk fades out. |
+| `transferProgress` | `number` | — | Share transferred, 0…1 (`UploadItem.progress`): the ring along the disk's inner edge, gliding (`base`) while it turns. Without it a transfer in flight turns a quarter arc. |
+| `transferDirection` | `"upload" \| "download"` | `"upload"` | Which way it goes: sending (`upload`) or receiving (`download`). Changes only the words — the names of the cross and the retry, the share and the failure — never the look. |
+| `onCancel` | `() => void \| Promise<void>` | — | Cancel the transfer in flight: the disk's cross. A returned promise keeps the disk pending (a spinner, `aria-busy`, no second press); a rejection leaves the transfer as it was and announces `cancelFailed`. |
+| `onRetry` | `() => void \| Promise<void>` | — | Transfer it again after a failure: the danger disk's retry; a promise works the same (`retryFailed` on a rejection). |
+| `onDownload` | `() => void \| Promise<void>` | — | Fetch a `remote` content: the download arrow; set `transfer` to `loading` with `transferDirection="download"` as it starts. A promise works the same (`downloadFailed` on a rejection). |
+| `labels` | `Partial<VideoNoteLabels>` | — | 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. |
+
+## Variants
+One look. The circle is the video; the play disk and the pills stand on the media shade, the same in both themes; the transcript block under it takes the message's fill (standalone, the next surface). The play disk is VoicePlayer's in its `shade` look.
+
+### Flags
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `unplayed` | an accent dot after the duration | nobody has watched it yet | |
+| `disabled` | the circle and its duration dim, the disk in the Button's disabled look | it cannot be played (deleted, expired) | |
+
+## 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 |
+| 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)` |
+| 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 |
+| 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` |
+| remote | `transfer="remote"` | `data-transfer="true"`, the circle dims to 0.6; not fetched yet: the disk with the download arrow (`labels.download`), no ring, the video is not preloaded; `onDownload` |
+| transferred | `transfer="done"` | the ring fades where it is (`fast`), the × cross-fades back into play and the circle returns to full |
+| transcript open | the transcript button, `transcriptExpanded` / `defaultTranscriptExpanded` | the button's glyph cross-fades into a chevron up, `aria-expanded="true"`; the text opens under the circle at once; in a chat the view is held still and the message grows downward |
+| transcript pending | an open with no text while `onTranscribe`'s Promise is in flight | only the button spins (`loading`, `aria-busy`); the area stays closed and opens with the text; when `onTranscribe` returns nothing, the button spins until `transcript` comes |
+| 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 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.
+- The play disk is the control `l` disk centred on the circle — the same element, size, glyphs and motion as VoicePlayer's, on the media shade with a blur.
+- One sound at a time on the page: starting it pauses whatever else plays with sound — a voice message, another circle, a video in `Message.Media`.
+- Symmetric with VoicePlayer: the same shared props (`MediaPlayerProps`), labels keys, `data-*` and keys. Its own prop is `poster`; it has no `waveform` (a face, not levels) and no rate (a face is watched at its own pace), and it seeks from its disk, having no slider.
+
+## Accessibility
+
+### Keyboard
+| Key | Action |
+|---|---|
+| `Tab` | Moves focus: the play disk (or the transfer disk), the transcript button. |
+| `Enter` · `Space` | On the disk: play with sound or pause; on the transcript button: open or close the text; on the transfer disk: cancel, retry or download. |
+| `ArrowRight` · `ArrowUp` | On the disk: 5 seconds forward (`ArrowRight` mirrored in RTL). |
+| `ArrowLeft` · `ArrowDown` | On the disk: 5 seconds back (`ArrowLeft` mirrored in RTL). |
+| `PageUp` · `PageDown` | On the disk: 10 % of the note forward or back. |
+| `Home` · `End` | On the disk: to the start or the end. |
+
+### ARIA
+- 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"`).
+- The transcript button is named `labels.transcribe` / `labels.hideTranscript`, with `aria-expanded` and `aria-controls`; a failed request is announced with `labels.transcribeFailed`.
+- `disabled` (own or a `Fieldset`'s) disables the disk, the transcript button and the transfer actions natively.
+
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+| Key | Default | Used for |
+|---|---|---|
+| `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`). |
+| `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. |
+| `cancelUpload` | `"Отменить отправку"` | The transfer of the note: the cross while sending. |
+| `cancelDownload` | `"Отменить загрузку"` | The transfer of the note: the cross while receiving. |
+| `retryUpload` | `"Повторить отправку"` | The transfer of the note: the retry after a failed send. |
+| `retryDownload` | `"Повторить загрузку"` | The transfer of the note: the retry after a failed receive. |
+| `uploadProgress` | `"Отправка {percent}%"` | The transfer of the note: the share while sending — the description of the cross. |
+| `downloadProgress` | `"Загрузка {percent}%"` | The transfer of the note: the share while receiving — the description of the cross. |
+| `notSent` | `"Не отправилось"` | The transfer of the note: why a send failed — the retry's description. |
+| `notReceived` | `"Не загрузилось"` | The transfer of the note: why a receive failed — the retry's description. |
+| `download` | `"Скачать"` | The transfer of the note: the download arrow of a `remote` content. |
+| `cancelFailed` | `"Не удалось отменить"` | The transfer of the note: announced when `onCancel` rejected. |
+| `retryFailed` | `"Не удалось повторить"` | The transfer of the note: announced when `onRetry` rejected. |
+| `downloadFailed` | `"Не удалось скачать"` | The transfer of the note: announced when `onDownload` rejected. |
+
+## Examples
+| Example | Shows |
+|---|---|
+| [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`. |
+| [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`. |
+
+## 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.
+- An autoplaying muted loop of your own around it → the circle stays still until a press; a long chat must not decode video on its own.
+- A `VideoNote` inside a `Card` or a bubble of text → put it alone in `Message.Root`: the round shell is the message.
+- `unplayed` never cleared → clear it when `onPlayingChange(true)` comes.
+- A transfer drawn with your own spinner or ProgressCircle over the circle → pass `transfer`, `transferProgress` and the handlers.
+- `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)
+- **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/video-note/examples/controlled.tsx

@@ -0,0 +1,28 @@
+/** The parent knows what plays and marks the report as watched on the first play — `playing`, `onPlayingChange`, `unplayed`. */
+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";
+
+export default function VideoNoteControlledExample() {
+  const [playing, setPlaying] = React.useState(false);
+  const [unplayed, setUnplayed] = React.useState(true);
+
+  return (
+    <>
+      <VideoNote
+        src={VIDEO_URL}
+        duration={6}
+        unplayed={unplayed}
+        playing={playing}
+        onPlayingChange={(next) => {
+          setPlaying(next);
+          if (next) setUnplayed(false);
+        }}
+      />
+      <Typography as="p" variant="body-s" tone="secondary">
+        {playing ? "Воспроизводится" : unplayed ? "Ещё не просмотрено" : "Просмотрено"}
+      </Typography>
+    </>
+  );
+}

package/src/components/video-note/examples/examples.module.css

@@ -0,0 +1,4 @@
+/* A conversation column: messages are rows as wide as the column. */
+.thread {
+  inline-size: 100%;
+}

package/src/components/video-note/examples/in-message.tsx

@@ -0,0 +1,22 @@
+/** 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`. */
+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";
+
+export default function VideoNoteInMessageExample() {
+  return (
+    <div className={styles.thread}>
+      <Message.Root direction="incoming" time="13:48">
+        <VideoNote src={VIDEO_URL} duration={6} unplayed />
+      </Message.Root>
+      <Message.Root direction="outgoing" time="13:50" status="read">
+        <Message.Text>Вижу, стойка собрана. Подключайте питание.</Message.Text>
+      </Message.Root>
+      <Message.Root direction="outgoing" time="13:51" status="read">
+        <VideoNote src={VIDEO_URL} duration={6} />
+      </Message.Root>
+    </div>
+  );
+}

package/src/components/video-note/examples/overview.tsx

@@ -0,0 +1,8 @@
+/** 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`. */
+import { VideoNote } from "prime-ui-kit";
+
+const VIDEO_URL = "https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4";
+
+export default function VideoNoteOverviewExample() {
+  return <VideoNote src={VIDEO_URL} duration={6} />;
+}

package/src/components/video-note/examples/states.tsx

@@ -0,0 +1,74 @@
+/** 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`. */
+import { Typography, VideoNote } from "prime-ui-kit";
+
+const VIDEO_URL = "https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4";
+
+/** Stand-ins for the chat's transfer service: the disks show their actions. */
+const cancelTransfer = () => {};
+const retryTransfer = () => {};
+const fetchNote = () => {};
+
+export default function VideoNoteStatesExample() {
+  return (
+    <>
+      <div>
+        <div>
+          <VideoNote src={VIDEO_URL} duration={6} />
+          <Typography as="span" variant="caption" tone="muted">
+            default
+          </Typography>
+        </div>
+        <div>
+          <VideoNote src={VIDEO_URL} duration={6} unplayed />
+          <Typography as="span" variant="caption" tone="muted">
+            unplayed
+          </Typography>
+        </div>
+        <div>
+          <VideoNote src={VIDEO_URL} duration={6} disabled />
+          <Typography as="span" variant="caption" tone="muted">
+            disabled
+          </Typography>
+        </div>
+      </div>
+      <div>
+        <div>
+          <VideoNote
+            src={VIDEO_URL}
+            duration={6}
+            transfer="loading"
+            transferProgress={0.45}
+            onCancel={cancelTransfer}
+          />
+          <Typography as="span" variant="caption" tone="muted">
+            transfer · loading
+          </Typography>
+        </div>
+        <div>
+          <VideoNote
+            src={VIDEO_URL}
+            duration={6}
+            transfer="failed"
+            transferProgress={0.6}
+            onRetry={retryTransfer}
+          />
+          <Typography as="span" variant="caption" tone="muted">
+            transfer · failed
+          </Typography>
+        </div>
+        <div>
+          <VideoNote
+            src={VIDEO_URL}
+            duration={6}
+            transfer="remote"
+            transferDirection="download"
+            onDownload={fetchNote}
+          />
+          <Typography as="span" variant="caption" tone="muted">
+            transfer · remote
+          </Typography>
+        </div>
+      </div>
+    </>
+  );
+}

package/src/components/video-note/examples/transcript.tsx

@@ -0,0 +1,29 @@
+/** 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`. */
+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";
+
+const FOREMAN_TRANSCRIPT = "Стойка собрана, кабели уложены. Жду команду на подключение питания.";
+
+const ENGINEER_TRANSCRIPT =
+  "Питание подключайте после проверки заземления, протокол пришлю в этот чат.";
+
+/** The speech service answers in a moment. */
+function transcribeEngineerNote(): Promise<string> {
+  return new Promise((resolve) => setTimeout(() => resolve(ENGINEER_TRANSCRIPT), 1200));
+}
+
+export default function VideoNoteTranscriptExample() {
+  return (
+    <div className={styles.thread}>
+      <Message.Root direction="incoming" time="13:48">
+        <VideoNote src={VIDEO_URL} duration={6} transcript={FOREMAN_TRANSCRIPT} />
+      </Message.Root>
+      <Message.Root direction="outgoing" time="13:52" status="read">
+        <VideoNote src={VIDEO_URL} duration={6} onTranscribe={transcribeEngineerNote} />
+      </Message.Root>
+    </div>
+  );
+}