prime-ui-kit 0.15.0 → 0.16.0

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

@@ -25,7 +25,7 @@ import { Composer, type ComposerActivity, type ComposerMessage, useUploadQueue }
 ## Anatomy
 ```
 Composer.Root                  <form>: the column below, one tier for every part
-├─ (video preview)             round camera preview (VideoNote geometry, Skeleton until the camera answers, progress ring to 60 s)
+├─ (video preview)             round camera preview (VideoNote geometry, Skeleton until the camera answers, progress ring to 60 s, `weight="band"`)
 ├─ (tray)                      Crossfade of `queue`: opens and closes with a fade and a height glide
 │  ├─ (strip)                  FileUpload.Queue layout="strip": one row of tiles — photos, videos and
 │  │                           files in tray order; format pill, remove ×, name · size band, upload disk + ring, reorder
@@ -53,10 +53,10 @@ Sending is an async event (`SKILL/api-contract.md`, Events):
 const queue = useUploadQueue({ upload: sendFile });
 <Composer.Root
   queue={queue}
-  onSend={({ text, media, files }) =>
+  onSend={({ text, albums, files }) =>
     api.post(chatId, {
       text,
-      album: media.map((item) => ({ type: item.type, id: item.result })),
+      albums: albums.map((album) => album.map((item) => ({ type: item.type, id: item.result }))),
       files: files.map((item) => item.result),
     })
   }
@@ -68,9 +68,9 @@ const queue = useUploadQueue({ upload: sendFile });
 
 `text` arrives trimmed. While the Promise runs the button is busy and the field read-only; resolve clears the field and the queue and closes the reply / edit bar (its `onDismiss`), reject leaves the text for another try.
 
-Every attachment is a tile of one strip, in the order attached and then reordered by the person. Photos and videos arrive as `media` in that order — send them as one album (`Message.Media`, up to ten per album, the text as its caption) — and the other files as `files` in that order, a `Message.File` each. Clearing the queue revokes its previews, so a sent album shows from `result` (the server's URL) or from your own `URL.createObjectURL(item.file)` — revoke it when its message is deleted or the chat unmounts.
+Every attachment is a tile of one strip, in the order attached and then reordered by the person. Photos and videos arrive as `albums` in that order, a new album every ten (the most a `Gallery` lays out) — send each as one `Message.Media` message, the text as the caption of the first — and the other files as `files` in that order, a `Message.File` each. Clearing the queue revokes its previews, so a sent album shows from `result` (the server's URL) or from your own `URL.createObjectURL(item.file)` — revoke it when its message is deleted or the chat unmounts.
 
-In an optimistic chat the send returns at once: add the message to the list with `status="sending"` under a client id, then patch its status as the server answers — the row keeps its key, so it never enters twice. Give the reply / edit bar the message id (`Composer.Context value`) and the send says what it answers or edits:
+In an optimistic chat the send returns at once: add the message to the list with `status="sending"` under a client id, then patch its status as the server answers — the row keeps its key, so it never enters twice. Give the reply / edit bar the message id (`Composer.Context messageId`) and the send says what it answers or edits:
 
 ```tsx partial
 <Composer.Root
@@ -78,7 +78,7 @@ In an optimistic chat the send returns at once: add the message to the list with
   onActivityChange={(activity) => chat.signal(activity)}
 >
   {replyTo ? (
-    <Composer.Context value={replyTo.id} onDismiss={() => setReplyTo(null)}>
+    <Composer.Context messageId={replyTo.id} onDismiss={() => setReplyTo(null)}>
       <Composer.Title>Ответ Анне</Composer.Title>
       <Composer.Description>{replyTo.text}</Composer.Description>
     </Composer.Context>
@@ -98,7 +98,7 @@ In an optimistic chat the send returns at once: add the message to the list with
 | `value` | `string` | — | The text of the message (controlled). |
 | `defaultValue` | `string` | `""` | Initial text, uncontrolled (a saved draft). |
 | `onValueChange` | `(value: string) => void` | — | Every change of the text: typing, formatting, the field cleared after a send. |
-| `onSend` | `(message: { text: string; media: readonly (UploadItem & { type: "image" \| "video" })[]; files: readonly UploadItem[]; replyTo?: string; editOf?: string }) => void \| Promise<unknown>` | — | Sends the message (Enter, Mod+Enter, the button): trimmed `text`, the uploaded `media` and `files` and `replyTo` / `editOf`. Return a Promise to keep the text until it resolves; reject leaves everything as it was. |
+| `onSend` | `(message: { text: string; albums: readonly (readonly (UploadItem & { type: "image" \| "video" })[])[]; files: readonly UploadItem[]; replyTo?: string; editOf?: string }) => void \| Promise<unknown>` | — | Sends the message (Enter, Mod+Enter, the button): trimmed `text`, photos and videos as `albums` of up to 10, `files`, `replyTo` / `editOf`. A Promise keeps the text until it resolves; reject changes nothing. |
 | `onActivityChange` | `(activity: "typing" \| "voice" \| "video" \| null) => void` | — | What the person is doing changed, for the other side's «печатает…»: `typing`, `voice` / `video` while recording, or `null`. Fires on a change only. |
 | `onSendVoice` | `(recording: { blob: Blob; durationMs: number; waveform: number[] }) => void \| Promise<unknown>` | — | A voice message was recorded: the `MediaRecorder` blob, its length and 48 loudness values 0…1 for its waveform. With it an empty field shows the record button (where the browser can record). |
 | `onSendVideoNote` | `(recording: { blob: Blob; durationMs: number; waveform: number[] }) => void \| Promise<unknown>` | — | A round video message was recorded (front camera and microphone), at most 60 s. With both record handlers a double click or tap on the record button (or ↑ / ↓ on it) switches voice and video. |
@@ -108,7 +108,7 @@ In an optimistic chat the send returns at once: add the message to the list with
 | `onRecordModeChange` | `(mode: "voice" \| "video") => void` | — | A double click / double tap on the record button (or ↑ / ↓ on it) switched voice and video. |
 | `queue` | `Pick<UploadQueue, "items" \| "add" \| "retry" \| "remove" \| "clear" \| "move">` | — | Attachments, usually `useUploadQueue(…)`: the paperclip, a paste and a drop add to it, and a tray above the row shows them as one reorderable strip of tiles. Without `queue` paste and drop of files do nothing. |
 | `formatting` | `boolean` | `true` | Selecting text shows a floating toolbar of seven Markdown tools and enables their hotkeys; a tool wraps the selection, a second press unwraps it. `false` turns both off. |
-| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `host tier, else "m"` | Tier of the field, the buttons and the bar text. Without it the tier of its host, else `m`. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | host tier, else `"m"` | Tier of the field, the buttons and the bar text. Without it the tier of its host, else `m`. |
 | `disabled` | `boolean` | `false` | A closed conversation: the field, the paperclip and the button are disabled; nothing is pasted or dropped. A disabled `Fieldset` around it sets it too (`data-disabled` included). |
 | `inputRef` | `Ref<HTMLTextAreaElement>` | — | The message `<textarea>`: focus it after «Ответить» in a message menu. |
 | `labels` | `Partial<ComposerLabels>` | — | Built-in strings, see Labels. |
@@ -116,26 +116,32 @@ In an optimistic chat the send returns at once: add the message to the list with
 | `…rest` | `Omit<FormHTMLAttributes<HTMLFormElement>, "children" \| "defaultValue" \| "onSubmit">` | — | `className`, `aria-*`, `onKeyDown` and the other attributes of the `<form>`. |
 
 ### Composer.Context
-`ref` → `HTMLDivElement`. The bar above the field: a reply or edit glyph, `Composer.Title` over `Composer.Description` behind an accent rule, and a close button; it describes the field; when it appears, the caret moves to the field. + native `<div>` props.
+`ref` → `HTMLDivElement`. The bar above the field: a reply or edit glyph, `Composer.Title` over `Composer.Description` behind an accent rule, and a close button; it describes the field; when it appears, the caret moves to the field.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `mode` | `"reply" \| "edit"` | `"reply"` | `reply` — a reply to a message; `edit` — your message is being edited: the send button turns into «Сохранить» and the record button is not offered. |
-| `value` | `string` | — | The id of the message answered or edited: `onSend` receives it as `replyTo` (`reply`) or `editOf` (`edit`). |
+| `messageId` | `string` | — | The id of the message answered or edited: `onSend` receives it as `replyTo` (`reply`) or `editOf` (`edit`). |
 | `onDismiss` | `() => void` | — | Stop replying or editing: the close button, Escape in the field, and a send that went through. Without it the bar has no close button. |
 | `children` | `ReactNode` | — | `Composer.Title` and `Composer.Description`. |
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `className` and the other div attributes. |
 
 ### Composer.Title · Composer.Description
-`ref` → `HTMLDivElement`. The first line of the bar in the accent text color, medium weight («Ответ Анне», «Редактирование») / the quoted message in the secondary color; both one line, cut with an ellipsis. + native `<div>` props.
+`ref` → `HTMLDivElement`. The first line of the bar in the accent text color, medium weight («Ответ Анне», «Редактирование») / the quoted message in the secondary color; both one line, cut with an ellipsis.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children`, `className` and the other div attributes. |
 
 ### Composer.Attach
-`ref` → `HTMLDivElement`. The paperclip at the start of the row. Alone it opens the file picker (FileUpload `trigger="button"`); with `Composer.Item` children it opens a menu where every item picks its own file types. Files go to the root's `queue`. + native `<div>` props.
+`ref` → `HTMLDivElement`. The paperclip at the start of the row. Alone it opens the file picker (FileUpload `trigger="button"`); with `Composer.Item` children it opens a menu where every item picks its own file types. Files go to the root's `queue`.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `accept` | `string` | — | File types of the picker without a menu. |
 | `aria-label` | `string` | — | Name of the button. Default `labels.attach`. |
 | `children` | `ReactNode` | — | `Composer.Item` kinds of attachment. |
+| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children">` | — | `className` and the other div attributes. |
 
 ### Composer.Item
 `ref` → `HTMLButtonElement`. A kind of attachment in the paperclip menu, a `Dropdown.Item` (`role="menuitem"`): `Composer.ItemIcon` and the label. + native button props.
@@ -145,9 +151,14 @@ In an optimistic chat the send returns at once: add the message to the list with
 | `accept` | `string` | — | File types this item picks (`"image/*,video/*"`; `""` for any file). Without it the item only runs `onSelect`. |
 | `onSelect` | `() => void` | — | The item's own action (a poll, a location); runs after the picker opens when `accept` is set. |
 | `disabled` | `boolean` | `false` | Muted and skipped by the arrow keys. |
+| `…rest` | `Omit<ButtonHTMLAttributes<HTMLButtonElement>, "onSelect" \| "type">` | — | `children`, `className` and the other button attributes. |
 
 ### Composer.ItemIcon
-`ref` → `HTMLSpanElement`. The leading glyph of a menu item (`Dropdown.ItemIcon`, `aria-hidden`). + native `<span>` props.
+`ref` → `HTMLSpanElement`. The leading glyph of a menu item (`Dropdown.ItemIcon`, `aria-hidden`).
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLSpanElement>` | — | `children` (the `Icon`), `className` and the other span attributes. |
 
 ## Variants
 Composer has no `variant`; what the row shows follows its state.
@@ -179,19 +190,19 @@ Composer has no `variant`; what the row shows follows its state.
 | State | Driven by | DOM |
 |---|---|---|
 | empty | no text, no attachments | with a record handler the button is the quiet ghost microphone (or camera), else a disabled send |
-| typing | text | the button turns into the accent send; the glyph turns and scales into the plane |
+| typing | text | the button turns into the accent send; the glyph cross-fades into the plane (`Button.Icon`) |
 | attachments | `queue.items` | the tray above the row: one strip of tiles in the order attached — photos and videos (MIME type, else the name's extension) as the local preview or first frame, other files as the sheet glyph, each with the format pill and a name · size (duration) band; while a file goes up a disk with the progress ring along its edge stands in the middle of a picture (dimmed under it) or in place of a file's sheet (name and size stay readable) (pressing it cancels, a failure turns it into a danger retry, done fades it away), remove ×, reorder by drag or `Alt + ←` / `→`; send is disabled while any is `queued` / `uploading` |
-| as files | the «Отправить как файлы, без сжатия» checkbox (shown with photos or videos) | the view stays the same (the strip); `onSend` gets every file in `files` and `media` empty; reset after a send |
+| as files | the «Отправить как файлы, без сжатия» checkbox (shown with photos or videos) | the view stays the same (the strip); `onSend` gets every file in `files` and `albums` empty; reset after a send |
 | sending | `onSend` returned a Promise | button `loading` (`aria-busy`), textarea `readonly`, text kept |
 | sent | the Promise resolved (or nothing returned) | field and queue cleared (the previews revoked, the tray fades and glides closed), the reply / edit bar's `onDismiss` called, focus stays in the field; `onActivityChange(null)` |
-| reply / edit | `Composer.Context` | bar above the field (enters with `enterMotion`); `mode="edit"` turns send into save; its `value` goes to `onSend` as `replyTo` / `editOf` |
+| reply / edit | `Composer.Context` | bar above the field (enters with `enterMotion`); `mode="edit"` turns send into save; its `messageId` goes to `onSend` as `replyTo` / `editOf` |
 | activity | typing, recording | `onActivityChange`: `typing` from the first keystroke until the text is sent, emptied or rests for 3 s; `voice` / `video` while the recording bar shows; `null` after, and on unmount while active. It fires on a change only: a server that expires the signal wants it repeated on your side while the value is not `null` |
 | selection | a non-empty selection while the field has focus | the floating toolbar fades in from below (`overlayMotion` floating, `data-side="top"`); a tool wraps the selection in its Markdown, a second press removes it |
 | files over | a file drag over the composer (with `queue`) | `data-dropping="true"`: an accent ring over the field; a drop adds the files to the queue. A pasted file with no type (a screenshot from some apps) takes its clipboard item's type. Without `queue` paste and drop of files do nothing |
-| recording, held | `data-recording="hold"` (a finger on the button; with voice and video both offered, from 200 ms of holding) | recording bar over the paperclip and the field with «Влево — отмена» sliding and fading with the finger — a slide of `--prime-space-24` throws the recording away; lock pill above the button, a lift of `--prime-space-12` locks; release sends |
+| recording, held | `data-recording="hold"` (a finger on the button; with voice and video both offered, from 200 ms of holding) | recording bar over the paperclip and the field with «Влево — отмена» sliding and fading with the finger — a slide of `--prime-space-24` throws the recording away; lock pill above the button (a floating surface, `data-depth="floating"`) rises in, a lift of `--prime-space-12` locks and it snaps away; release sends |
 | recording, locked | `data-recording="locked"` (a mouse click, Enter / Space, a tap shorter than 200 ms, or a slide up) | delete button · pause button · dot · timer · live waveform over the full free width; the button and Enter send; a video message sends itself at 60 s of recorded time |
-| recording, paused | Space or the pause button during a hands-free recording (`MediaRecorder.pause()`) | `data-paused` on the bar: the dot turns into a still pause glyph, the timer and the waveform stand, the video ring stops; Space or «Продолжить запись» resumes; a send hands over what was recorded, without the pause |
-| double-click window | with voice and video both offered, the 300 ms after a click or a tap | no `data-recording` yet: the button keeps its glyph and nothing is announced; with a granted microphone voice already records. A second press inside it discards that recording unseen and switches the mode (glyph swap, «Голосовое сообщение» / «Видеосообщение» announced); otherwise the bar cross-fades in with the timer counting from the first press |
+| recording, paused | Space or the pause button during a hands-free recording (`MediaRecorder.pause()`) | `data-paused` on the bar: the dot cross-fades into a still pause glyph (`GlyphSwap`), the timer and the waveform stand, the video ring stops; Space or «Продолжить запись» resumes; a send hands over what was recorded, without the pause |
+| double-click window | with voice and video both offered, the 300 ms after a click or a tap | no `data-recording` yet: the button keeps its glyph and nothing is announced; with a granted microphone voice already records. A second press inside it discards that recording unseen and switches the mode (glyph swap, «Голосовое сообщение» / «Видеосообщение» announced); otherwise the bar rises in over the field with the timer counting from the first press; when the recording ends it closes up in place |
 | starting | the press is answered, the device is not granted yet | already the recording bar with a running timer (it counts from the press) while the device is asked for in parallel; the waveform is a calm line of dots |
 | too short | a recording under 0.7 s | dropped: nothing is sent |
 | record error | the browser refused / found no device | the bar cross-fades back to the field; `Hint` with `role="alert"` above the row, cleared by typing or the next attempt |
@@ -203,7 +214,7 @@ Motion: the tray opens and closes as a Crossfade (fade and height glide, the row
 - The row stands on its bottom edge with `--prime-space-2` gaps: the paperclip and the button stay by the last line as the field grows. Field → bar / attachments above: `--prime-space-2`.
 - The tray is never in the row: the strip (`--prime-space-24` square tiles, one row scrolling sideways with faded edges, so its height is one tile at any count) and the «как файлы» checkbox stack with `--prime-space-2` gaps above it.
 - The field grows from one line to eight and then scrolls inside; its padding centres one line exactly like an Input of the tier.
-- The composer takes its container's width and works from 320 px; it is a size container, the round video preview is `--prime-message-video-note` wide, at most 70% of its width, and needs that room above the composer (a chat history gives it).
+- The composer takes its container's width and works on the narrowest phone (320 px); it is a size container, the round video preview is `--prime-message-video-note` wide, at most 70% of its width, and needs that room above the composer (a chat history gives it).
 - The recording bar covers the paperclip and the field, so entering and leaving a recording never changes the row height; its waveform takes all the width between the timer and the send button, as tall as the button minus `--prime-space-2`, in VoicePlayer's bar geometry.
 - On touch the editable text is at least 16 px (no iOS zoom) and every button has the 44 px hit area.
 - The formatting toolbar floats above the field's start edge on the floating layer, over whatever is above the composer.
@@ -211,6 +222,8 @@ Motion: the tray opens and closes as a Crossfade (fade and height glide, the row
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 | Key | Action |
 |---|---|
 | `Enter` | In the field sends the message; on a touch screen breaks the line. |
@@ -227,6 +240,8 @@ Motion: the tray opens and closes as a Crossfade (fade and height glide, the row
 | `Delete` · `Backspace` | On a tile of the tray: removes the attachment; focus moves to its neighbour. |
 
 ### ARIA
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 - The composer is a `<form>` named «Новое сообщение»; the field is a `<textarea>` named «Сообщение» with `enterkeyhint="send"` (`enter` on touch).
 - A reply / edit bar describes the field (`aria-describedby`); when it appears after the first render the caret moves to the field. Its close button is «Отменить ответ» / «Отменить редактирование». A send that went through closes it.
 - The formatting toolbar is `role="toolbar"` with one Tab stop and arrow keys; every button has `aria-keyshortcuts` and a tooltip with its keys (`⌘B` on Apple systems, `Ctrl+B` elsewhere).
@@ -234,6 +249,8 @@ Motion: the tray opens and closes as a Crossfade (fade and height glide, the row
 - A live region (`role="status"`) announces a recording started, locked, deleted and sent, and the record mode after a switch («Голосовое сообщение» / «Видеосообщение»); a refused microphone is a `role="alert"` message that also describes the field, never a thrown error.
 - While recording the paperclip and the field are `inert` under the bar; the bar's buttons are «Удалить запись» and «Приостановить запись» / «Продолжить запись» (`aria-keyshortcuts="Space"`), the action button «Отправить запись». Deleting brings the focus back to the action button. Pause and resume are announced. The timer and the waveform are decorative. While a finger holds a recording only `Escape` works (it throws the recording away); the delete and pause buttons keep their own Enter and Space.
 - The attachments are one `<ul>` named «Вложения» (FileUpload.Queue `layout="strip"`): every tile is «Фото N: name» / «Видео N: name» / «Файл N: name» with its upload state, `aria-keyshortcuts` for `Alt + ←` / `→` and `Delete`, a remove button «Убрать name»; the upload disk is a `progressbar` while the file goes up. Moves are announced by Dnd's live region, finished and failed files by the queue's. «Отправить как файлы, без сжатия» is a labelled Checkbox.
+- Touch: the buttons get a 44 px hit area; Enter breaks the line, the button sends.
+- Voice and video together: a single press records without holding, a double press (within 300 ms) switches the mode. The first press records silently until the window ends, so a double press shows no recording and sends nothing.
 
 ### Labels
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
@@ -285,19 +302,20 @@ Motion: the tray opens and closes as a Crossfade (fade and height glide, the row
 | [sizes.tsx](examples/sizes.tsx) | One composer in every tier: field, buttons and the paperclip follow it — `size`. |
 | [attachments.tsx](examples/attachments.tsx) | Warehouse photos and documents for a client go through an upload queue: the paperclip opens the file picker for photos, videos and office documents, a paste or a drop adds files too, every attachment is a tile of one strip that drags into its order, and send waits until the uploads finish — `queue`, `Composer.Attach`, `accept`, `useUploadQueue`. |
 | [attach-menu.tsx](examples/attach-menu.tsx) | The paperclip as a menu of attachment kinds: photos and videos, documents, any file, and an invoice from the system that puts its link into the message and returns the focus to the field — `Composer.Item`, `Composer.ItemIcon`, `accept`, `onSelect`, `inputRef`. |
-| [reply-edit.tsx](examples/reply-edit.tsx) | Answering a client's message and correcting your own: the bar above the field quotes the message, Escape or the cross cancels, ↑ in an empty field opens your last message, send becomes save and hands over the message id — `Composer.Context`, `mode`, `value`, `onDismiss`, `onEditLast`. |
+| [reply-edit.tsx](examples/reply-edit.tsx) | Answering a client's message and correcting your own: the bar above the field quotes the message, Escape or the cross cancels, ↑ in an empty field opens your last message, send becomes save and hands over the message id — `Composer.Context`, `mode`, `messageId`, `onDismiss`, `onEditLast`. |
 | [typing.tsx](examples/typing.tsx) | The other side's status line follows what you do: typing, recording a voice or a video message, then nothing — `onActivityChange`. |
 | [formatting.tsx](examples/formatting.tsx) | Selected text gets a toolbar of bold, italic, strikethrough, code, spoiler, link and quote, each with its shortcut, written as Markdown around the selection — `formatting`. |
 | [voice.tsx](examples/voice.tsx) | Voice and round video messages: hold the button to record and release to send, slide left to cancel, slide up or tap to record hands-free; a double tap or double click switches voice and video — `onSendVoice`, `onSendVideoNote`, `recordMode`. |
 | [states.tsx](examples/states.tsx) | A closed conversation is disabled, a slow send keeps the text with a busy button until the server answers — `disabled`, `onSend`. |
 | [controlled.tsx](examples/controlled.tsx) | Every conversation keeps its own draft: switching the chat swaps the text, a template button fills it from outside — `value`, `onValueChange`. |
-| [narrow.tsx](examples/narrow.tsx) | On a phone-width chat the row keeps the paperclip, the field and the button; Enter makes a new line on touch screens and the button sends. |
+| [narrow.tsx](examples/narrow.tsx) | On a phone-width chat the row keeps the paperclip, the field and the button; Enter makes a new line on touch screens and the button sends — `Composer.Attach`, `onSend`. |
 
 ## Mistakes
 - A `<Textarea>` with a hand-made send button and an Enter handler → `Composer.Root`: Enter / Shift+Enter / touch, the async send, the clearing and the focus are built in.
 - Clearing the field in `onSend` before the server answers → return the Promise; the composer clears on resolve and keeps the text on reject.
 - Rendering the attachment rows yourself → pass `queue`; the tray, paste and drop come with it.
-- Sending photos as file messages → send `media` as one `Message.Media` album (its order is the tray's), `files` as `Message.File`.
+- Sending photos as file messages → send each of `albums` as one `Message.Media` message (its order is the tray's), `files` as `Message.File`.
+- Cutting `media` into albums of ten by hand → `albums` comes split.
 - Showing a sent photo from `item.preview` → the queue revokes it after the send; use `result` or your own object URL of `item.file`, revoked with its message.
 - Expecting HTML from the formatting → the text is Markdown (`**…**`, `_…_`, `~~…~~`, `` `…` ``, `||…||`, Markdown links, `> `); render it with the message component, never as HTML.
 - Hiding the reply bar by CSS → unmount `Composer.Context` in `onDismiss`; Escape and a sent message call the same handler.
@@ -308,5 +326,5 @@ Motion: the tray opens and closes as a Crossfade (fade and height glide, the row
 - An `aria-label` on the root to rename the field → use `labels.placeholder` (the field) and `labels.region` (the form).
 
 ## Related
-- **Built from:** [Textarea](../textarea/COMPONENT.md), [Button](../button/COMPONENT.md), [FileUpload](../file-upload/COMPONENT.md) (the paperclip; `FileUpload.Queue layout="strip"`, the tray), [Crossfade](../crossfade/COMPONENT.md), [Checkbox](../checkbox/COMPONENT.md), [Dropdown](../dropdown/COMPONENT.md), [Tooltip](../tooltip/COMPONENT.md), [Kbd](../kbd/COMPONENT.md), [Hint](../hint/COMPONENT.md), [Skeleton](../skeleton/COMPONENT.md), Icon (`action.*`, `format.*`, `nav.chevronLeft`, `nav.chevronUp`, `status.locked`), `useUploadQueue` (the `queue`), `internal/ring` (the video preview's ring), `internal/textFormatting` + `internal/textFormattingToolbar` (the formatting shared with Textarea `formatting`)
+- **Built from:** [Textarea](../textarea/COMPONENT.md), [Button](../button/COMPONENT.md), [FileUpload](../file-upload/COMPONENT.md) (the paperclip and the picker of the menu; `FileUpload.Queue layout="strip"`, the tray), [Gallery](../gallery/COMPONENT.md) (`GALLERY_MAX`, the size of an album in `albums`), [Crossfade](../crossfade/COMPONENT.md), [Checkbox](../checkbox/COMPONENT.md), [Dropdown](../dropdown/COMPONENT.md), [Tooltip](../tooltip/COMPONENT.md), [Kbd](../kbd/COMPONENT.md), [Hint](../hint/COMPONENT.md), [Skeleton](../skeleton/COMPONENT.md), Icon (`action.*`, `format.*`, `nav.chevronLeft`, `nav.chevronUp`, `status.locked`), `useUploadQueue` (the `queue`), `internal/ring` (the video preview's ring), `internal/textFormatting` + `internal/textFormattingToolbar` (the formatting shared with Textarea `formatting`), [VisuallyHidden](../visually-hidden/COMPONENT.md)
 - **See also:** [Message](../message/COMPONENT.md) — the bubbles the composer writes into; [VoicePlayer](../voice-player/COMPONENT.md) — plays a sent voice message; [Textarea](../textarea/COMPONENT.md), [Input](../input/COMPONENT.md)

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

@@ -19,12 +19,3 @@
   width: min(100%, calc(var(--prime-space-20) * 4));
   margin-inline: auto;
 }
-
-/* sizes.tsx, states.tsx: one composer per row with its caption. */
-.cell {
-  display: flex;
-  flex-direction: column;
-  gap: var(--prime-space-1);
-  width: min(100%, calc(var(--prime-space-24) * 6));
-  margin-inline: auto;
-}

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

@@ -1,4 +1,4 @@
-/** On a phone-width chat the row keeps the paperclip, the field and the button; Enter makes a new line on touch screens and the button sends. */
+/** On a phone-width chat the row keeps the paperclip, the field and the button; Enter makes a new line on touch screens and the button sends — `Composer.Attach`, `onSend`. */
 import { Composer, useUploadQueue } from "prime-ui-kit";
 
 import styles from "./examples.module.css";

package/dist/skill/reference/components/composer/examples/reply-edit.tsx

@@ -1,4 +1,4 @@
-/** Answering a client's message and correcting your own: the bar above the field quotes the message, Escape or the cross cancels, ↑ in an empty field opens your last message, send becomes save and hands over the message id — `Composer.Context`, `mode`, `value`, `onDismiss`, `onEditLast`. */
+/** Answering a client's message and correcting your own: the bar above the field quotes the message, Escape or the cross cancels, ↑ in an empty field opens your last message, send becomes save and hands over the message id — `Composer.Context`, `mode`, `messageId`, `onDismiss`, `onEditLast`. */
 import { Button, Composer, type ComposerMessage, Typography } from "prime-ui-kit";
 import * as React from "react";
 
@@ -46,13 +46,13 @@ export default function ComposerReplyEditExample() {
         }}
       >
         {mode?.kind === "reply" ? (
-          <Composer.Context value={CLIENT_MESSAGE_ID} onDismiss={dismiss}>
+          <Composer.Context messageId={CLIENT_MESSAGE_ID} onDismiss={dismiss}>
             <Composer.Title>Ответ Анне Соколовой</Composer.Title>
             <Composer.Description>{CLIENT_MESSAGE}</Composer.Description>
           </Composer.Context>
         ) : null}
         {mode?.kind === "edit" ? (
-          <Composer.Context mode="edit" value={LAST_OWN_MESSAGE_ID} onDismiss={dismiss}>
+          <Composer.Context mode="edit" messageId={LAST_OWN_MESSAGE_ID} onDismiss={dismiss}>
             <Composer.Title>Редактирование</Composer.Title>
             <Composer.Description>{LAST_OWN_MESSAGE}</Composer.Description>
           </Composer.Context>

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

@@ -1,15 +1,13 @@
 /** One composer in every tier: field, buttons and the paperclip follow it — `size`. */
 import { Composer, Typography } from "prime-ui-kit";
 
-import styles from "./examples.module.css";
-
 const SIZES = ["xs", "s", "m", "l", "xl"] as const;
 
 export default function ComposerSizesExample() {
   return (
-    <>
+    <div>
       {SIZES.map((size) => (
-        <div key={size} className={styles.cell}>
+        <div key={size}>
           <Composer.Root size={size} defaultValue="Счёт № 2187 оплачен" onSend={() => {}}>
             <Composer.Attach />
           </Composer.Root>
@@ -18,6 +16,6 @@ export default function ComposerSizesExample() {
           </Typography>
         </div>
       ))}
-    </>
+    </div>
   );
 }

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

@@ -1,16 +1,14 @@
 /** A closed conversation is disabled, a slow send keeps the text with a busy button until the server answers — `disabled`, `onSend`. */
 import { Composer, Typography } from "prime-ui-kit";
 
-import styles from "./examples.module.css";
-
 const SLOW_SEND_MS = 2500;
 
 const slowSend = () => new Promise<void>((resolve) => window.setTimeout(resolve, SLOW_SEND_MS));
 
 export default function ComposerStatesExample() {
   return (
-    <>
-      <div className={styles.cell}>
+    <div>
+      <div>
         <Composer.Root disabled defaultValue="Обращение закрыто">
           <Composer.Attach />
         </Composer.Root>
@@ -18,7 +16,7 @@ export default function ComposerStatesExample() {
           disabled
         </Typography>
       </div>
-      <div className={styles.cell}>
+      <div>
         <Composer.Root defaultValue="Нажмите Enter — отправка займёт пару секунд" onSend={slowSend}>
           <Composer.Attach />
         </Composer.Root>
@@ -26,6 +24,6 @@ export default function ComposerStatesExample() {
           onSend → Promise
         </Typography>
       </div>
-    </>
+    </div>
   );
 }

package/dist/skill/reference/components/confirm-dialog/COMPONENT.md

@@ -14,7 +14,7 @@
 - A form, a choice or more than one sentence of content → use [Modal](../modal/COMPONENT.md).
 - An action that can be undone → do it at once and offer «Отменить» in a [Notification](../notification/COMPONENT.md).
 - A hold-to-confirm right on the button (no dialog) → `holdToConfirm` on [Button](../button/COMPONENT.md).
-- Unsaved changes in a Modal or Drawer form → `Modal.Guard` / `Drawer.Guard dirty` (it opens this dialog itself).
+- Unsaved changes in a Modal, Drawer or Sheet form → `Modal.Guard` / `Drawer.Guard` / `Sheet.Guard` with `dirty` (it opens this dialog itself).
 - A confirm that asks for input (a reason for a refusal, a comment) → [Modal](../modal/COMPONENT.md) `size="s"` with the field in `Modal.Body`, the action button in `Modal.Confirm`, and `Modal.Guard busy` while it is sent.
 
 ## Import
@@ -28,7 +28,7 @@ ConfirmDialog.Root            state; renders the trigger and the dialog
 ├── ConfirmDialog.Trigger     clones its child; opens on click
 └── (Modal s)                 portal + scrim + role="alertdialog"
     ├── header                title (names it) · description (describes it) · close button
-    ├── (message)             a danger Banner with role="alert" after a failure
+    ├── (reason)              a danger Banner with role="alert" after a failure: the rejection's message
     └── footer                Cancel (focused first) · the confirm (solid, loading while it runs)
 ```
 
@@ -37,19 +37,20 @@ ConfirmDialog.Root            state; renders the trigger and the dialog
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
 ### ConfirmDialog.Root
-No ref (state root). Renders its Trigger and a Modal `s` with `role="alertdialog"`: the title, the description, an inline danger message after a failure, Cancel (focused first) and the confirm. A press outside never closes it; while `onConfirm` runs nothing closes it.
+No ref (state root). Renders its Trigger and a Modal `s` with `role="alertdialog"`: the question, the consequence, the reason after a failure, Cancel (focused first) and the confirm. While `onConfirm` runs nothing closes it.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `open` | `boolean` | — | Controlled visibility; together with `onOpenChange`. |
 | `defaultOpen` | `boolean` | `false` | Initial visibility, uncontrolled. |
 | `onOpenChange` | `(open: boolean) => void` | — | Called on open and close: the Trigger, Cancel, the close button, Escape, a resolved `onConfirm`. |
+| `closeOnEscape` | `boolean` | `true` | Escape closes the dialog, like Cancel. |
+| `closeOnOutsideClick` | `boolean` | `false` | A click on the scrim (and on a phone a swipe down) closes the dialog. Off by default: a question about a weighty action is answered with a button, not by a stray click beside it. |
 | `title` | `ReactNode` | — (required) | The question as a heading («Удалить проект?»); names the dialog. |
 | `description` | `ReactNode` | — | What happens and what cannot be undone; describes the dialog. |
 | `confirmLabel` | `ReactNode` | — (required) | The confirm button: the action as a verb («Удалить»), never «Да» or «ОК». |
 | `tone` | `"danger" \| "accent"` | `"danger"` | `danger`: a destructive action, solid danger confirm. `accent`: a weighty but safe one (send, publish), solid accent confirm. |
-| `onConfirm` | `() => unknown` | — (required) | The action. A Promise keeps the dialog busy: the confirm shows `loading`, Cancel and the close button are disabled, Escape is ignored. Resolve closes the dialog; reject keeps it open with `error` (else `labels.error`). |
-| `error` | `ReactNode` | — | Why the action failed, from the owner; shown under the text while set. |
+| `onConfirm` | `() => unknown` | — (required) | The action. A pending Promise keeps the dialog busy (`loading`, nothing closes it). Resolve closes it; reject keeps it open with the reason: the `Error.message` or string, else `labels.error`. |
 | `labels` | `Partial<ConfirmDialogLabels>` | — | Built-in strings, see Labels. |
 | `children` | `ReactNode` | — | `ConfirmDialog.Trigger`; nothing when `open` comes from code. |
 
@@ -69,32 +70,42 @@ The dialog is a Modal `s` with the floating surface, a header and a footer; ther
 | `danger` | solid danger confirm | Delete, revoke, cancel for good | yes |
 | `accent` | solid accent confirm | Send, publish, charge — weighty but safe | |
 
+### Flags
+| Flag | Effect | Default |
+|---|---|---|
+| `closeOnEscape` | Escape closes the dialog like Cancel (never while the action runs) | `true` |
+| `closeOnOutsideClick` | a click on the scrim (on a phone also a swipe down) closes it; turn on only for a safe confirm | `false` |
+
 ## States
 | State | Driven by | DOM |
 |---|---|---|
 | open / closed | `open` / `defaultOpen` / `onOpenChange` | `data-state` on the scrim and the dialog (closed while the exit motion plays) |
 | running | `onConfirm` returned a pending Promise | the confirm `data-loading="true"` and `aria-busy="true"`; Cancel and the close button `disabled` in place; Escape ignored |
-| failed | `onConfirm` rejected, or `error` set | a danger Banner with `role="alert"` drops in under the header; the confirm is ready again |
+| failed | `onConfirm` rejected | a danger Banner with `role="alert"` drops in under the header with the rejection's `Error.message` (or string, else `labels.error`); the confirm is ready again; the next try or closing clears it, and the body closes up in place |
 
 ## Layout & spacing
-- Modal `s`: 440 wide, the footer fills with two equal buttons; a bottom sheet below 640px of viewport, buttons stacked full width.
+- Modal `s`: 440 wide, the footer fills with two equal buttons; a bottom sheet on a phone, buttons stacked full width.
 - The failure message is the dialog body (20 around it); without it the header meets the footer.
 - Write the title as a question with the object («Удалить тег «VIP»?»), the description as the consequence in one or two sentences, the confirm as the verb.
 
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 | Key | Action |
 |---|---|
 | `Tab` · `Shift+Tab` | Cycles focus inside the dialog; Cancel is focused first. |
 | `Enter` | On a button presses it; from the dialog itself presses the confirm. |
-| `Escape` | Closes the dialog unless the action runs; focus returns to the trigger. |
+| `Escape` | Closes the dialog (`closeOnEscape`) unless the action runs; focus returns to the trigger. |
 
 ### ARIA
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 - `role="alertdialog"`, `aria-modal="true"`, named by `title`, described by `description`.
 - Cancel takes focus first — the least destructive choice.
 - While the action runs the confirm has `aria-busy="true"`; Cancel and the close button are disabled.
-- The failure message is `role="alert"`, read at once.
+- The reason of a failure is `role="alert"`, read at once.
 
 ### Labels
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
@@ -103,23 +114,25 @@ The dialog is a Modal `s` with the floating surface, a header and a footer; ther
 |---|---|---|
 | `cancel` | `"Отмена"` | The cancel button. |
 | `close` | `"Закрыть"` | `aria-label` of the header close button. |
-| `error` | `"Не получилось. Попробуйте ещё раз."` | The message after a rejected `onConfirm` when there is no `error`. |
+| `error` | `"Не получилось. Попробуйте ещё раз."` | The message after a rejected `onConfirm` without a reason of its own. |
 
 ## Examples
 | Example | Shows |
 |---|---|
 | [overview.tsx](examples/overview.tsx) | Deleting a project: the danger confirm runs the request with a spinner and nothing closes the dialog until it ends — `ConfirmDialog.Trigger`, `onConfirm`. |
 | [variants.tsx](examples/variants.tsx) | A destructive action gets the danger confirm; a weighty but safe one, such as sending an invoice, the accent one — `tone`. |
-| [failure.tsx](examples/failure.tsx) | The server refuses: the dialog stays open with the owner's reason under the text and the confirm ready to try again — `error`, `onConfirm`. |
+| [failure.tsx](examples/failure.tsx) | The server refuses: the dialog stays open with the reason of the rejection under the text and the confirm ready to try again — `onConfirm`. |
+| [dismiss.tsx](examples/dismiss.tsx) | A reminder to the client is weighty but safe: a click beside the dialog closes it like Cancel, and Escape does too — `closeOnOutsideClick`, `closeOnEscape`. |
 | [controlled-open.tsx](examples/controlled-open.tsx) | A menu item opens the confirm from code: the dialog has no trigger of its own and the parent owns its state — `open`, `onOpenChange`. |
 
 ## Mistakes
 - A hand-built Modal with `closeOnOutsideClick={false}`, a loading flag and a disabled Cancel → ConfirmDialog does all of it.
-- `onConfirm` that catches its own error and resolves → the dialog closes as if it worked; rethrow (or reject) to keep it open.
+- `onConfirm` that catches its own error and resolves → the dialog closes as if it worked; rethrow (or reject) to keep it open. Reject with an `Error` whose message a person can read («Тег используется в 12 сделках») — it is the text under the question.
+- `closeOnOutsideClick` on a destructive confirm → a stray click beside it must not answer the question; keep it off for `danger`.
 - «Да» / «ОК» on the confirm → the verb of the action («Удалить», «Отправить»).
 - A success message inside the dialog → it closes on success; say «Удалено» with a Notification.
 - `tone="accent"` for a delete → destructive is always `danger`.
 
 ## Related
-- **Built from:** [Modal](../modal/COMPONENT.md) (`s`, the header and footer parts), [Button](../button/COMPONENT.md) (Cancel, the confirm with `loading`), [Banner](../banner/COMPONENT.md) (the failure message), `Icon` (`status.danger` in the Banner)
+- **Built from:** the dialog Modal stands on (`internal/overlay/ModalDialog` at `s`, the header, body and footer of `internal/overlay/DialogParts`), [ScrollContainer](../scroll-container/COMPONENT.md) (the body), [Avatar](../avatar/COMPONENT.md) and [Thumbnail](../thumbnail/COMPONENT.md) (pictures the shared icon slot recognises), [Button](../button/COMPONENT.md) (Cancel, the confirm with `loading`), [Banner](../banner/COMPONENT.md) (the failure message), `Icon` (`status.danger` in the Banner)
 - **See also:** [Modal](../modal/COMPONENT.md), [Drawer](../drawer/COMPONENT.md), [Notification](../notification/COMPONENT.md)

package/dist/skill/reference/components/confirm-dialog/examples/dismiss.tsx

@@ -0,0 +1,27 @@
+/** A reminder to the client is weighty but safe: a click beside the dialog closes it like Cancel, and Escape does too — `closeOnOutsideClick`, `closeOnEscape`. */
+import { Button, ConfirmDialog } from "prime-ui-kit";
+
+/** Pretends to send the reminder. */
+function sendReminder() {
+  return new Promise((resolve) => setTimeout(resolve, 900));
+}
+
+export default function ConfirmDialogDismissExample() {
+  return (
+    <ConfirmDialog.Root
+      tone="accent"
+      closeOnOutsideClick
+      closeOnEscape
+      title="Напомнить клиенту о счёте №318?"
+      description="ООО «Гранит» получит письмо со ссылкой на оплату."
+      confirmLabel="Напомнить"
+      onConfirm={sendReminder}
+    >
+      <ConfirmDialog.Trigger>
+        <Button.Root variant="soft" tone="neutral">
+          Напомнить об оплате
+        </Button.Root>
+      </ConfirmDialog.Trigger>
+    </ConfirmDialog.Root>
+  );
+}

package/dist/skill/reference/components/confirm-dialog/examples/failure.tsx

@@ -1,31 +1,24 @@
-/** The server refuses: the dialog stays open with the owner's reason under the text and the confirm ready to try again — `error`, `onConfirm`. */
+/** The server refuses: the dialog stays open with the reason of the rejection under the text and the confirm ready to try again — `onConfirm`. */
 import { Button, ConfirmDialog } from "prime-ui-kit";
-import * as React from "react";
 
 /** Pretends the server refuses: the tag is still in use. */
 function deleteTag() {
-  return new Promise((_, reject) => setTimeout(() => reject(new Error("in use")), 900));
+  return new Promise((_, reject) =>
+    setTimeout(
+      () =>
+        reject(new Error("Тег используется в 12 активных сделках — сначала снимите его с них.")),
+      900,
+    ),
+  );
 }
 
 export default function ConfirmDialogFailureExample() {
-  const [error, setError] = React.useState<string>();
-
   return (
     <ConfirmDialog.Root
       title="Удалить тег «VIP»?"
       description="Тег снимется со всех клиентов."
       confirmLabel="Удалить тег"
-      error={error}
-      onOpenChange={() => setError(undefined)}
-      onConfirm={async () => {
-        setError(undefined);
-        try {
-          await deleteTag();
-        } catch (reason) {
-          setError("Тег используется в 12 активных сделках — сначала снимите его с них.");
-          throw reason;
-        }
-      }}
+      onConfirm={deleteTag}
     >
       <ConfirmDialog.Trigger>
         <Button.Root variant="soft" tone="danger">

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

@@ -40,7 +40,7 @@ Crossfade          <div>; holds the region's height while it changes
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
 ### Crossfade
-`ref` → `HTMLDivElement`. A region that cross-fades its content when `state` changes and glides to the new height; still on the first render, instant under reduced motion.
+`ref` → `HTMLDivElement`. A region that cross-fades its content when `state` changes and glides to the new height; still on the first render. Under reduced motion the old content goes at once and the height jumps; the new content still fades in.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -69,12 +69,13 @@ Crossfade has no variants: one treatment, keyed by `state`.
 |---|---|---|
 | first render | mount | one layer, `data-state="open"`, no motion |
 | swapping | `state` changes | previous layer `data-state="closed"`, `aria-hidden`, `inert`, absolutely placed, fades out over `fast` with `exit` easing and unmounts on `animationend` (timeout fallback); the new layer fades in over `base` with `enter` easing |
-| resizing | the new state has another height | root `data-resizing="true"`: height glides from the old to the new value over `base` with `standard` easing, clipped with a `--prime-focus-space` margin, then returns to `auto` |
-| reduced motion | `prefers-reduced-motion: reduce` | instant swap: no leaving layer, no glide |
+| resizing | the new state has another height | root `data-resizing="true"`: height glides from the old to the new value over `base` with `standard` easing (a swap mid-glide starts from the height on screen), clipped with a `--prime-focus-space` margin, then returns to `auto` |
+| reduced motion | `prefers-reduced-motion: reduce` | the old layer goes before it is painted and the height does not glide; the new layer still fades in (the fade clock, foundation §7 rule 12) |
+| focus handoff | focus was in the old state when `state` changed | focus moves into the new layer: its first tab stop, else the layer itself (`tabindex="-1"`); focus elsewhere stays |
 | empty | the current state renders nothing (`null`, `false`, `""`) | no current layer; once nothing is leaving the root is `:empty` and `display: none` — no box and no gap in its grid or flex parent |
 | filling | `fill` | `data-fill="true"`; the root is a one-cell grid (`flex: 1`, `height: 100%`, `min-height: 0`), layers stretch to it |
 
-Motion is opacity only, so nothing shifts under the pointer; the leaving content keeps its instance (no remount, no repeated effects) until it is gone.
+Motion is opacity only, so nothing shifts under the pointer; the leaving content keeps its instance (no remount, no repeated effects) until it is gone. Each state is a block formatting context, so it measures the same in flow and laid over as it leaves.
 
 ## Layout & spacing
 - No padding, gap or fill of its own: it sits where the swapped content would sit (inside `Card.Body`, a page section, a panel).
@@ -85,12 +86,16 @@ Motion is opacity only, so nothing shifts under the pointer; the leaving content
 ## 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. -->
+
 - Renders a plain `<div>`; pass `aria-busy` while the region loads and `aria-live` or `role` when its changes must be announced.
 - The leaving layer is `aria-hidden` and `inert`: screen readers and Tab never reach content that is going away.
-- Move focus yourself when the focused control was in the old state (e.g. the retry button of an error).
+- Focus in the old state (the retry button of an error) moves into the new one: its first tab stop, or the new content itself; focus elsewhere on the page stays where it is.
 
 ### Labels
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
@@ -111,6 +116,7 @@ No `labels`.
 - A spinner block for content of known shape → a `Skeleton` of that shape; a spinner is for loading with no shape to hold (a button, a status line).
 - Wrapping a DataTable to animate its loading / empty / error → the table body already cross-fades; use its props.
 - Hand-written `opacity` transitions or `height` animations for a state swap → Crossfade owns both, with tokens and reduced motion.
+- An effect that moves focus out of a state that is going away (the retry button of an error) → Crossfade hands focus to the new state itself.
 - `height: 100%` on the content of a full-height region → `fill` on the Crossfade; its layers stretch.
 - Rendering an optional block conditionally outside Crossfade (`{notice && <Banner />}`) → it pops in and out; keep the Crossfade and pass `null` when there is nothing to show.