prime-ui-kit 0.10.0 → 0.11.0

package/src/components/tag-select/examples/manage-tags.tsx

@@ -1,14 +1,17 @@
-/** Users keep their own tag dictionary: the row «⋯» menu renames, recolors or deletes an option — `onOptionUpdate`, `onOptionDelete`. */
+/** Users keep their own tag dictionary on the server: the row «⋯» menu renames, recolors or deletes an option, and «⋯» spins while a change is saved — `onOptionUpdate`, `onOptionDelete`. */
 import { TagSelect, type TagSelectOption } from "prime-ui-kit";
 import * as React from "react";
 
 const INITIAL_OPTIONS: TagSelectOption[] = [
-  { value: "telegram", label: "Telegram", color: "blue" },
+  { value: "chat", label: "Чат на сайте", color: "blue" },
   { value: "whatsapp", label: "WhatsApp", color: "green" },
   { value: "email", label: "Почта", color: "purple" },
   { value: "phone", label: "Телефон", color: "orange" },
 ];
 
+/** The server saving a change of the dictionary, a beat later. */
+const saveDictionary = () => new Promise<void>((resolve) => setTimeout(resolve, 600));
+
 export default function TagSelectManageTagsExample() {
   const [options, setOptions] = React.useState(INITIAL_OPTIONS);
 
@@ -16,15 +19,16 @@ export default function TagSelectManageTagsExample() {
     <TagSelect
       label="Каналы связи"
       options={options}
-      defaultValue={["telegram", "email"]}
+      defaultValue={["chat", "email"]}
       creatable
-      onOptionUpdate={(value, updates) =>
+      onOptionUpdate={async (value, updates) => {
+        await saveDictionary();
         setOptions((prev) =>
           prev.some((option) => option.value === value)
             ? prev.map((option) => (option.value === value ? { ...option, ...updates } : option))
             : [...prev, { value, label: updates.label ?? value, color: updates.color }],
-        )
-      }
+        );
+      }}
       onOptionDelete={(value) =>
         setOptions((prev) => prev.filter((option) => option.value !== value))
       }

package/src/components/textarea/COMPONENT.md

@@ -7,12 +7,14 @@
 
 ## When to use
 - Free-form text longer than one line: comments, descriptions, reviews, support requests, notes.
+- A plain growing input (`rows={1} maxRows={8}`) when a full chat composer with attachments, reply and voice is not needed.
 - Text with a length limit shown to the user (`Textarea.Counter`).
 
 ## When not to use
 - A single-line value (name, e-mail, search) → use [Input](../input/COMPONENT.md).
 - A one-time code split into cells → use [DigitInput](../digit-input/COMPONENT.md).
 - Read-only code or logs → use [CodeBlock](../code-block/COMPONENT.md).
+- A chat message input with send, attachments, reply / edit and voice → use [Composer](../composer/COMPONENT.md).
 
 ## Import
 ```tsx
@@ -22,9 +24,11 @@ import { Textarea } from "prime-ui-kit";
 ## Anatomy
 ```
 Textarea.Root       label row → field box with the native <textarea> → support row (hint | error · counter)
+├─ Textarea.CopyButton   children: copies the text from the top end corner (kit-rendered)
+└─ Textarea.Action       children: the consumer's named icon action with a tooltip (button or asChild link)
 Textarea.Counter    goes into Textarea.Root `counter` (right side of the support row)
 ```
-Unlike Input, Textarea has no Wrapper / Field parts: `Textarea.Root` renders the whole field and takes native `<textarea>` props directly.
+Unlike Input, Textarea has no Wrapper / Field parts: `Textarea.Root` renders the whole field and takes native `<textarea>` props directly. Its children are only the corner actions: they sit in the top end corner as full-height segments flush with the box edges, in JSX order, after the commit status of `onCommit`.
 
 ## API
 
@@ -45,10 +49,14 @@ Unlike Input, Textarea has no Wrapper / Field parts: `Textarea.Root` renders the
 | `focusRing` | `boolean` | `true` | `false` hides only the visual focus ring on the field box (`data-focus-ring="false"`); focus, keyboard, ARIA and the invalid ring stay. |
 | `counter` | `ReactNode` | — | Right side of the support row, usually `<Textarea.Counter />`. |
 | `reserveSupportRow` | `boolean` | `false` | Always render the support row (min height = hint line height), so an appearing error does not shift the layout. |
-| `autoResize` | `boolean` | `true` | Height follows the content (minimum three lines, no scrollbar, no resize handle). `false` → fixed height (three lines or `rows`) with native vertical resize. |
+| `autoResize` | `boolean` | `true` | Height follows the content (minimum `rows` lines, no resize handle; up to `maxRows` lines when set, then it scrolls inside). `false` → fixed height of `rows` lines with native vertical resize. |
+| `rows` | `number` | `3` | Minimum height in lines; with `autoResize={false}` the fixed height. `rows={1}` makes a field that starts as one line, like an Input. |
+| `maxRows` | `number` | — | With `autoResize`: the field grows up to this many lines, then scrolls inside (a chat composer: `rows={1} maxRows={8}`). Without it the field grows without a limit. |
 | `onValueChange` | `(value: string) => void` | — | Called with the new string; native `onChange` still fires first. |
 | `id` | `string` | — | Id of the `<textarea>` (auto-generated when omitted); hint id is `<id>-hint`, error id is `<id>-error`. |
 | `aria-describedby` | `string` | — | Merged before the hint/error ids. |
+| `onCommit` | `(value: string) => void \| Promise<void>` | — | Inline save: fires with a changed value on blur and Mod+Enter; Escape reverts. Return a Promise: the field shows a spinner and stays editable; a rejection restores the value — show why through `error`. |
+| `children` | `ReactNode` | — | Actions in the field's top end corner: `Textarea.CopyButton`, `Textarea.Action`. |
 | `labels` | `Partial<TextareaLabels>` | — | Built-in strings, see Labels. |
 | `className` | `string` | — | Class on the field frame `<div>` (label, field box, support row), as on every field root. |
 | `…rest` | `Omit<TextareaHTMLAttributes<HTMLTextAreaElement>, "size" \| "children">` | — | `value`, `defaultValue`, `onChange`, `placeholder`, `rows`, `maxLength`, `name`, `disabled`, `readOnly`, `aria-label`… |
@@ -62,6 +70,24 @@ Unlike Input, Textarea has no Wrapper / Field parts: `Textarea.Root` renders the
 | `max` | `number` | — (required) | Limit; `current > max` turns the counter danger (`data-invalid="true"`). Add `maxLength` on the root for a hard limit. |
 | `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className` and the other attributes of the `<span>`. |
 
+### Textarea.CopyButton
+`ref` → `HTMLButtonElement`. Copies the field's value from the field's top end corner (a read-only result): the copy glyph morphs into a check, the name and tooltip switch to `labels.copied` (`labels.copyError` when the clipboard refuses), a polite live region repeats it.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `value` | `string` | `the field's value` | Text to copy instead of the field's current value. |
+| `…rest` | `Omit<ButtonHTMLAttributes<HTMLButtonElement>, "type" \| "children" \| "aria-label">` | — | `onClick`, `disabled` and the other button attributes. |
+
+### Textarea.Action
+`ref` → `HTMLButtonElement` (the child with `asChild`). The consumer's icon action in the field's top end corner: a full-height button segment named by `label`, with a tooltip and the touch hit area.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `label` | `string` | — (required) | Accessible name and tooltip («Позвонить», «Открыть профиль»). |
+| `asChild` | `boolean` | `false` | Renders the one child (an `<a href>`, a router link) with the segment's look; `disabled` becomes `aria-disabled`. |
+| `children` | `ReactNode` | — (required) | The glyph (`<Icon name>`), or with `asChild` the element that carries it. |
+| `…rest` | `Omit<ButtonHTMLAttributes<HTMLButtonElement>, "aria-label" \| "children">` | — | `onClick`, `disabled` and the other button attributes. |
+
 ## Variants
 Textarea has no `variant` or `tone`: one field treatment (fill, no visible border).
 
@@ -70,7 +96,7 @@ Textarea has no `variant` or `tone`: one field treatment (fill, no visible borde
 |---|---|---|---|
 | `xs` | Text 12/16, padX 8, radius 6, label 12/16, hint 12/16 | Dense panels next to `xs` controls | |
 | `s` | Text 13/20, padX 8, radius 8, label 12/16, hint 12/16 | Compact side panels, comments in lists | |
-| `m` | Text 14/20, padX 12, radius 8, label 13/20, hint 12/16 | Regular forms | yes |
+| `m` | Text 14/20, padX 12, radius 8, label 13/20, hint 12/16 | Regular forms | yes (without `size`: the host's tier, else `m`) |
 | `l` | Text 16/24, padX 12, radius 10, label 14/20, hint 13/20 | Spacious forms, long reading text | |
 | `xl` | Text 16/24, padX 16, radius 12, label 14/20, hint 13/20 | Hero forms next to `xl` inputs | |
 
@@ -79,8 +105,8 @@ Textarea has no `variant` or `tone`: one field treatment (fill, no visible borde
 ### autoResize
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| `true` | Box grows line by line with the text, minimum three lines, no resize handle | Comments, descriptions — most cases | yes |
-| `false` | Fixed height (`rows` or three lines), native vertical resize handle, scrolls inside | Very long text where the page must not grow, or a fixed layout | |
+| `true` | Box grows line by line with the text from `rows` lines (three by default), no resize handle; with `maxRows` it stops there and scrolls inside | Comments, descriptions — most cases; `rows={1} maxRows={8}` for a chat input | yes |
+| `false` | Fixed height of `rows` lines, native vertical resize handle, scrolls inside | Very long text where the page must not grow, or a fixed layout | |
 
 ### Flags
 | Value | Looks like | Use when | Default |
@@ -101,10 +127,17 @@ Textarea has no `variant` or `tone`: one field treatment (fill, no visible borde
 | focus | keyboard focus | focus fill and inset focus ring on the field box; clicking the box padding focuses the textarea |
 | no focus ring | `focusRing={false}` | `data-focus-ring="false"` on the field box |
 | invalid | `invalid` or non-empty `error` | `data-invalid="true"` on the outer wrapper and the field box, `aria-invalid="true"`, danger ring; the control shakes once when an error arrives (`data-shake` on the frame) |
-| disabled | `disabled` | `data-disabled="true"` on the field box, disabled fill and text; label and hint dimmed |
+| disabled | `disabled`, or a disabled `Fieldset` around it | `data-disabled="true"` on the field box, disabled fill and text; label and hint dimmed |
+| capped | `autoResize` with `maxRows` | `data-capped="true"` on the field box; the box grows line by line up to `maxRows` lines, then the textarea scrolls inside with the thin scrollbar |
 | read-only | `readOnly` | `data-readonly="true"` on the field box, no hover, default cursor |
 | reserved support row | `reserveSupportRow` | `data-reserve="true"` on the support row |
 | counter over limit | `current > max` | `data-invalid="true"` on `Textarea.Counter` |
+| saving | `onCommit` returned a pending Promise | `aria-busy="true"` on the textarea, a `Spinner` in the top end corner (`data-commit="pending"`); the field stays editable; a live region says `labels.saving` |
+| saved | the Promise resolved (or `onCommit` returned nothing) | the spinner cross-fades into a success check (`data-commit="saved"`) that fades out; the live region says `labels.saved` |
+| save refused | the Promise rejected | the committed text is put back (unless the person typed on); the owner shows why through `error` |
+| copied | `Textarea.CopyButton` pressed | the copy glyph cross-fades into a check, the name becomes `labels.copied` (or `labels.copyError`) |
+
+Inline save (`onCommit`): the text at focus is the committed one; blur and Mod+Enter (Ctrl or ⌘ with Enter — a plain Enter is a line break) commit a changed text, Escape puts the committed text back and is consumed. An unchanged text never fires. Return a Promise for a server save: pending shows a spinner while the field stays editable and Tab moves on, reject restores the text, resolve shows the check.
 
 `data-size` is set on the outer wrapper and the field box. Controlled: `value` + `onValueChange` (or `onChange`). Uncontrolled: `defaultValue`.
 
@@ -119,13 +152,17 @@ Textarea has no `variant` or `tone`: one field treatment (fill, no visible borde
 ### Keyboard
 | Key | Action |
 |---|---|
-| `Tab` | Focuses the field; Enter inserts a line break instead of submitting the form. |
+| `Tab` | Focuses the field, then the buttons in its corner; Enter inserts a line break instead of submitting the form. |
+| `Mod+Enter` | With `onCommit`: saves a changed text; focus stays in the field. |
+| `Escape` | With `onCommit`: puts the committed text back. |
 
 ### ARIA
 - `label` renders `<label htmlFor>` bound to the textarea; without it set `aria-label`. A placeholder never replaces the label.
 - Hint and error are linked via `aria-describedby`; the error replaces the hint and sets `aria-invalid="true"`.
 - The field box is a `<div>`, not a `<label>`, so counter and hint never leak into the accessible name; clicking its padding focuses the textarea.
 - `Textarea.Counter` shows `12/280` visually and announces `labels.counter` (`aria-live="polite"`).
+- `Textarea.Action` and `Textarea.CopyButton` are buttons (or a link with `asChild`) named by their label, with a tooltip; copying announces `labels.copied`. A press on them never moves focus into the textarea.
+- With `onCommit` the textarea carries `aria-busy="true"` while saving; a polite live region says `labels.saving`, then `labels.saved`.
 
 ### Labels
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
@@ -134,6 +171,11 @@ Textarea has no `variant` or `tone`: one field treatment (fill, no visible borde
 |---|---|---|
 | `optional` | `"необязательно"` | Marker after the label when `optional`. |
 | `counter` | `"{current} из {max} символов"` | Screen-reader text of `Textarea.Counter`; `{current}` and `{max}` are replaced. |
+| `copy` | `"Копировать"` | Name and tooltip of the copy button. |
+| `copied` | `"Скопировано"` | Name, tooltip and announcement once the value is copied. |
+| `copyError` | `"Не удалось скопировать"` | Name, tooltip and announcement when the clipboard refuses. |
+| `saving` | `"Сохранение"` | Announced while an `onCommit` save is pending. |
+| `saved` | `"Сохранено"` | Announced once an `onCommit` save succeeds. |
 
 ## Examples
 | Example | Shows |
@@ -142,8 +184,10 @@ Textarea has no `variant` or `tone`: one field treatment (fill, no visible borde
 | [sizes.tsx](examples/sizes.tsx) | Every size tier; text, padding, label and hint follow the tier — `size`. |
 | [states.tsx](examples/states.tsx) | A default field next to a read-only and a disabled one — `readOnly`, `disabled`. |
 | [validation.tsx](examples/validation.tsx) | Live validation: an error shakes the field as it arrives, drops in and leaves as soon as the text is fixed; required and optional markers, a hint and a support row that does not shift — `required`, `optional`, `hint`, `error`, `reserveSupportRow`. |
-| [auto-resize.tsx](examples/auto-resize.tsx) | A field that grows with its text next to a fixed one with a resize handle — `autoResize`, `rows`. |
+| [auto-resize.tsx](examples/auto-resize.tsx) | A field that grows with its text, one that starts as a line and stops growing at five, and a fixed one with a resize handle — `autoResize`, `rows`, `maxRows`. |
 | [without-focus-ring.tsx](examples/without-focus-ring.tsx) | A single reply composer where the caret and the lighter fill show focus — `focusRing`. |
+| [edge-actions.tsx](examples/edge-actions.tsx) | A read-only generated reply with copying and a link to the template in the field's corner — `Textarea.CopyButton`, `Textarea.Action`. |
+| [inline-edit.tsx](examples/inline-edit.tsx) | A record card note that saves on blur and Mod+Enter, reverts on Escape and shows the server's refusal — `onCommit`, `error`. |
 | [controlled.tsx](examples/controlled.tsx) | The parent owns the text; the counter follows it and `maxLength` stops extra input — `value`, `onValueChange`, `Textarea.Counter`, `maxLength`. |
 | [in-form.tsx](examples/in-form.tsx) | Support request form: the description is checked on submit, its error leaves as soon as the text is long enough and does not shift the form, a sent request turns the button green — `required`, `error`, `reserveSupportRow`. |
 
@@ -152,8 +196,11 @@ Textarea has no `variant` or `tone`: one field treatment (fill, no visible borde
 - Counter without `maxLength` when the limit is hard → add `maxLength` so extra input is blocked.
 - `className` expected on the field box → it lands on the field frame (label, box, support row), as on every field root; size the box through the frame's layout.
 - Expecting a fixed height with the default `autoResize` → set `autoResize={false}` (and `rows`) for a fixed box with a resize handle.
+- A field that pushes the page down without end (a chat input, a note in a narrow panel) → cap it with `maxRows`; past it the field scrolls inside.
 - Only a placeholder, no label → add `label` or `aria-label`.
+- A copy `Button` under a read-only result → `Textarea.CopyButton` as a child of the root.
+- Other children than `Textarea.CopyButton` / `Textarea.Action` → the root renders the textarea itself; children are only the corner actions.
 
 ## Related
-- **Built from:** [Label](../label/COMPONENT.md) (`label`), [Hint](../hint/COMPONENT.md) (`hint`, `error`)
-- **See also:** [Input](../input/COMPONENT.md) — the same field contract for one line; [CodeBlock](../code-block/COMPONENT.md)
+- **Built from:** [Label](../label/COMPONENT.md) (`label`), [Hint](../hint/COMPONENT.md) (`hint`, `error`), [Tooltip](../tooltip/COMPONENT.md) (corner actions), [Spinner](../spinner/COMPONENT.md) (`onCommit`)
+- **See also:** [Input](../input/COMPONENT.md) — the same field contract for one line; [Composer](../composer/COMPONENT.md) — a chat message input built on Textarea; [CodeBlock](../code-block/COMPONENT.md)

package/src/components/textarea/examples/auto-resize.tsx

@@ -1,4 +1,4 @@
-/** A field that grows with its text next to a fixed one with a resize handle — `autoResize`, `rows`. */
+/** A field that grows with its text, one that starts as a line and stops growing at five, and a fixed one with a resize handle — `autoResize`, `rows`, `maxRows`. */
 import { Textarea } from "prime-ui-kit";
 
 export default function TextareaAutoResizeExample() {
@@ -9,6 +9,13 @@ export default function TextareaAutoResizeExample() {
         placeholder="Состав, размеры, уход"
         hint="Высота растёт вместе с текстом, минимум три строки"
       />
+      <Textarea.Root
+        label="Комментарий к заказу"
+        rows={1}
+        maxRows={5}
+        placeholder="Например, позвонить за час"
+        hint="Начинается с одной строки, после пяти строк прокручивается"
+      />
       <Textarea.Root
         label="Условия договора"
         autoResize={false}

package/src/components/textarea/examples/edge-actions.tsx

@@ -0,0 +1,24 @@
+/** A read-only generated reply with copying and a link to the template in the field's corner — `Textarea.CopyButton`, `Textarea.Action`. */
+import { Icon, Textarea } from "prime-ui-kit";
+
+const REPLY = `Добрый день, Ирина!
+
+Счёт № 1042 на сумму 184 500 ₽ выставлен и отправлен на почту бухгалтерии. Оплатить его можно до 15 ноября.`;
+
+export default function TextareaEdgeActionsExample() {
+  return (
+    <Textarea.Root
+      label="Ответ клиенту"
+      hint="Собран из шаблона «Счёт выставлен»"
+      readOnly
+      value={REPLY}
+    >
+      <Textarea.Action label="Открыть шаблон" asChild>
+        <a href="#template-invoice-sent">
+          <Icon name="object.document" />
+        </a>
+      </Textarea.Action>
+      <Textarea.CopyButton />
+    </Textarea.Root>
+  );
+}

package/src/components/textarea/examples/inline-edit.tsx

@@ -0,0 +1,42 @@
+/** A record card note that saves on blur and Mod+Enter, reverts on Escape and shows the server's refusal — `onCommit`, `error`. */
+import { Textarea } from "prime-ui-kit";
+import * as React from "react";
+
+const SAVE_DELAY_MS = 900;
+const MAX_NOTE_LENGTH = 500;
+
+/** Stands in for the API call: a note over the limit is refused like a server validation error. */
+function saveNote(value: string) {
+  return new Promise<void>((resolve, reject) => {
+    window.setTimeout(() => {
+      if (value.length > MAX_NOTE_LENGTH) reject(new Error("Заметка длиннее 500 символов"));
+      else resolve();
+    }, SAVE_DELAY_MS);
+  });
+}
+
+export default function TextareaInlineEditExample() {
+  const [note, setNote] = React.useState(
+    "Перезвонить после согласования бюджета. Интересует годовой тариф на 40 мест.",
+  );
+  const [error, setError] = React.useState<string>();
+
+  return (
+    <Textarea.Root
+      label="Заметка по сделке"
+      hint="Сохраняется при выходе из поля и по Ctrl+Enter, Escape отменяет правку"
+      error={error}
+      value={note}
+      onValueChange={setNote}
+      onCommit={async (value) => {
+        setError(undefined);
+        try {
+          await saveNote(value);
+        } catch (reason) {
+          setError(reason instanceof Error ? reason.message : "Не удалось сохранить");
+          throw reason;
+        }
+      }}
+    />
+  );
+}

package/src/components/thumbnail/COMPONENT.md

@@ -3,12 +3,15 @@
 **Category:** data-display
 **Kind:** primitive
 
-> A preview of an object — product, vehicle, file, cover — at a fixed aspect ratio, with a colored icon fallback.
+> A preview of an object — product, vehicle, file, cover, video — at a fixed aspect ratio, with a colored icon fallback; it can open the object or be selected.
 
 ## When to use
 - An object next to its name in a table cell or list row (vehicle, product, document).
 - Covers in a card grid or gallery (`fullWidth`).
 - Any picture of a thing, with a fallback while it loads or when there is none.
+- A video, a GIF-like clip or a video message in the same frame (`Thumbnail.Video`).
+- A preview that opens a viewer or the object (`asChild` on a `<button>` / `<a>`).
+- A tile of a media library that is picked (`checked` / `onCheckedChange`).
 
 ## When not to use
 - A person or an organization's account → use [Avatar](../avatar/COMPONENT.md).
@@ -22,9 +25,11 @@ import { Thumbnail } from "prime-ui-kit";
 
 ## Anatomy
 ```
-Thumbnail.Root          frame: tier height, width from ratio, radius, palette fill; image load state
+Thumbnail.Root          frame (a <div>; the child with asChild; a <button role="checkbox"> when selectable)
 ├─ Thumbnail.Image      <img>, covers the frame; fades in when loaded, hidden on error
-└─ Thumbnail.Fallback   icon or short label on the fill, under the image
+│  or Thumbnail.Video   <video>, first frame or poster; play mark (the media disk) and duration (media shade)
+├─ Thumbnail.Fallback   icon or short label on the fill, under the image
+└─ check                Checkbox.Indicator in the start corner (selectable only)
 ```
 
 ## API
@@ -32,7 +37,7 @@ Thumbnail.Root          frame: tier height, width from ratio, radius, palette fi
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
 ### Thumbnail.Root
-`ref` → `HTMLDivElement`. The frame: height of the tier, width from `ratio`, radius, palette fill; tracks the image load for the Fallback.
+`ref` → `HTMLDivElement` (the `<button>` of a selectable tile, the child with `asChild`). The frame: height of the tier, width from `ratio`, radius, palette fill; tracks the image load for the Fallback.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -42,10 +47,14 @@ Thumbnail.Root          frame: tier height, width from ratio, radius, palette fi
 | `variant` | `"soft" \| "solid"` | `"soft"` | Fallback fill: a soft tint with a hue icon, or a solid hue with a contrasting icon. |
 | `fullWidth` | `boolean` | `false` | Fills the container width (cards, galleries); the height follows `ratio`. |
 | `ring` | `boolean` | `false` | A faint inner ring, for photos with a white background on a light surface. |
-| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `className`, `aria-label` + `role` for a fallback-only thumbnail, and the other div attributes. |
+| `asChild` | `boolean` | `false` | Puts the frame, with hover, press and focus ring, on its one child — a `<button>` that opens a viewer or an `<a>` to the object. Name the child (`aria-label`) when the picture is all it shows. |
+| `checked` | `boolean` | — | Selected (controlled). Any of the checked triad makes a selectable tile — a `<button role="checkbox">` with a check in the corner. Name it with `aria-label` or the image `alt`. |
+| `defaultChecked` | `boolean` | — | Initially selected (uncontrolled); makes the tile selectable. |
+| `onCheckedChange` | `(checked: boolean) => void` | — | Selection changed by click, Space or Enter; makes the tile selectable. |
+| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "color" \| "defaultChecked" \| "onChange">` | — | `className`, `aria-label` + `role` for a fallback-only thumbnail, and the other attributes of the frame. |
 
 ### Thumbnail.Image
-`ref` → `HTMLImageElement`. The picture; hidden while it loads and after an error, so the Fallback shows through. A new `src` starts again.
+`ref` → `HTMLImageElement`. The picture; hidden while it loads and after an error, so the Fallback shows through. A new `src` starts again. Loads lazily and decodes off the main thread (`loading="lazy"`, `decoding="async"`; pass either to override).
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -54,6 +63,19 @@ Thumbnail.Root          frame: tier height, width from ratio, radius, palette fi
 | `fit` | `"cover" \| "contain"` | `"cover"` | `cover` crops to fill; `contain` shows the whole image on the fallback fill (logos). |
 | `…rest` | `Omit<ImgHTMLAttributes<HTMLImageElement>, "src" \| "alt">` | — | `className`, `onLoad`, `onError` and the other img attributes. |
 
+### Thumbnail.Video
+`ref` → `HTMLVideoElement`. A video in the frame (`preload="metadata"`, `playsInline`); the Fallback shows until its first frame. Without `controls` it shows the duration, and a play mark while it is still (not looping, not playing).
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `src` | `string` | — (required) | Video URL. Without a `poster` the first frame is asked for (`#t=0.001` is added when the URL has no fragment). |
+| `poster` | `string` | — | A still shown before playing. |
+| `controls` | `boolean` | `false` | Native controls: a video message or a clip to watch in place; no play mark or duration of the kit. |
+| `autoPlay` | `boolean` | `false` | A GIF-like clip: plays muted, in a loop, inline. Off under `prefers-reduced-motion` (read once): the first frame stands still with the play mark. |
+| `fit` | `"cover" \| "contain"` | `"cover"` | `cover` crops to fill; `contain` letterboxes on the fallback fill. |
+| `formatDuration` | `(seconds: number) => string` | `m:ss (h:mm:ss from an hour)` | Display of the duration badge. |
+| `…rest` | `Omit<VideoHTMLAttributes<HTMLVideoElement>, "src" \| "poster" \| "controls" \| "autoPlay" \| "muted" \| "loop" \| "children">` | — | `className`, `aria-label`, `onLoadedData`, `onError` and the other video attributes. |
+
 ### Thumbnail.Fallback
 `ref` → `HTMLSpanElement`. A `<span>` with an icon (sized to the tier) or a short label on the fill; `aria-hidden` once the image has loaded.
 
@@ -97,6 +119,10 @@ Thumbnail.Root          frame: tier height, width from ratio, radius, palette fi
 |---|---|---|---|
 | `fullWidth` | takes the container width, height from `ratio` | card covers, galleries | `false` |
 | `ring` | faint inner ring | white-background photos on a light surface | `false` |
+| `asChild` | the frame on a button or link: hover lift, press, focus ring | the preview opens a viewer or the object | `false` |
+| `checked` triad | a checkbox tile: the check in the corner, an accent ring when selected | picking media in a library | — |
+| `controls` (Video) | native video controls, no kit marks | a video message, a clip to watch in place | `false` |
+| `autoPlay` (Video) | muted looping clip; still under reduced motion | GIF-like previews | `false` |
 
 ## States
 | State | Driven by | DOM |
@@ -106,6 +132,10 @@ Thumbnail.Root          frame: tier height, width from ratio, radius, palette fi
 | loaded | image `load` | `data-status="loaded"`, the image fades in; Fallback `aria-hidden` |
 | error | image `error` | `data-status="error"`, image hidden, Fallback visible |
 | frame | props | `data-size`, `data-ratio`, `data-color`, `data-variant`, `data-full-width`, `data-ring` |
+| video loading | `Thumbnail.Video` mounted | `data-status="loading"` until the first frame (`loadeddata`), then `loaded`; `error` falls back like an image |
+| video still | no `controls`, not playing | a play mark in the centre (from `m`): the still media disk (`internal/mediaDisk`) — the look and size of the shade circle Button over media (40, a 20 glyph, `--prime-color-media-disk` under `--prime-media-disk-blur`), at 60% of a lower frame's height; the duration at the end corner (from `l` and `fullWidth`) on `--prime-color-media-shade` |
+| hover / press / focus | `asChild` or selectable | `data-interactive`: lift on `--prime-shadow-overlay` (`@media (hover: hover)`), scale 0.98 while pressed (`fast`), focus ring |
+| selected | `checked` | `aria-checked="true"`, `data-checked="true"`: an accent ring over the picture and a checked indicator; the indicator is always shown, never hover-only |
 
 ## Layout & spacing
 - Thumbnail + text in a row: flex, `align-items: center`, gap `--prime-space-3`; the text column `min-width: 0` with `truncate`.
@@ -116,12 +146,17 @@ Thumbnail.Root          frame: tier height, width from ratio, radius, palette fi
 ## Accessibility
 
 ### Keyboard
-No keyboard interaction.
+| Key | Action |
+|---|---|
+| `Tab` | Focuses a pressable (`asChild`) or selectable tile; a plain thumbnail takes no focus. |
+| `Enter` · `Space` | Opens the object (`asChild`) or toggles a selectable tile. |
 
 ### ARIA
 - Next to a name the thumbnail is decorative: keep `alt=""` (default) and mark fallback icons `aria-hidden`.
 - Alone: give `Thumbnail.Image` a descriptive `alt`, or `role="img"` + `aria-label` on Root for a fallback-only thumbnail.
-- No behaviour of its own: wrap it in a link or button when it opens the object.
+- A preview that opens the object is `asChild` on a `<button>` or `<a>`; name it (`aria-label`) when the picture is all it shows.
+- A selectable tile is a `<button role="checkbox">` with `aria-checked`, named by `aria-label` or the image `alt`; its indicator is `aria-hidden`, and the state is not only color (the check).
+- Name a `Thumbnail.Video` with `aria-label`; the play mark is decorative, the duration is text. Under `prefers-reduced-motion` an `autoPlay` clip stands still.
 
 ### Labels
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
@@ -138,13 +173,19 @@ No `labels`.
 | [ratios.tsx](examples/ratios.tsx) | Every aspect ratio at the same height; keep one ratio per list — `ratio`. |
 | [ring.tsx](examples/ring.tsx) | A faint inner ring for a white-background photo on a light surface, where the edge would vanish — `ring`. |
 | [full-width.tsx](examples/full-width.tsx) | Covers in a card grid take the card width and keep 16:9, so every cover has one height — `fullWidth`. |
+| [video.tsx](examples/video.tsx) | Videos in the frame: a walkthrough without a poster shows its first frame, a play mark and the duration; a short clip loops muted like a GIF; a video message plays in place with its controls — `Thumbnail.Video`, `autoPlay`, `controls`. |
+| [pressable.tsx](examples/pressable.tsx) | Photos of a delivery that open a viewer: the frame is put on a button, so it lifts on hover, presses and takes the focus ring — `asChild`. |
+| [controlled.tsx](examples/controlled.tsx) | A media library picks photos for a listing: each tile is a checkbox with its check in the corner, the selection lives in the parent and a button clears it — `checked`, `onCheckedChange`. |
 
 ## Mistakes
 - `Avatar` for a product or vehicle → a circle crops the object; use `Thumbnail`.
 - A `div` with a background image and fixed sizes → use `Thumbnail.Root` with `ratio` and `size`.
 - Width or height in CSS → change `size`, `ratio` or `fullWidth`.
 - No `Thumbnail.Fallback` → a broken image leaves an empty box; always add an icon.
+- A `<button>` wrapped around a Thumbnail by hand → `asChild` on the root with the button as its child.
+- A `<label>` with a checkbox laid over a tile → the checked triad on the root.
+- A bare `<video>` sized in CSS next to thumbnails → `Thumbnail.Video` in the same frame.
 
 ## Related
-- **Built from:** —
-- **See also:** [Avatar](../avatar/COMPONENT.md), [Card](../card/COMPONENT.md), [DataTable](../data-table/COMPONENT.md), [Select](../select/COMPONENT.md)
+- **Built from:** [Checkbox](../checkbox/COMPONENT.md) (`Checkbox.Indicator` of a selectable tile), `internal/mediaDisk` (the play mark, one look with the shade circle [Button](../button/COMPONENT.md))
+- **See also:** [Avatar](../avatar/COMPONENT.md), [Card](../card/COMPONENT.md), [DataTable](../data-table/COMPONENT.md), [Select](../select/COMPONENT.md), [FileUpload](../file-upload/COMPONENT.md) (`FileUpload.ItemPreview` is a Thumbnail; its tiles draw videos with `Thumbnail.Video`)

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

@@ -0,0 +1,61 @@
+/** A media library picks photos for a listing: each tile is a checkbox with its check in the corner, the selection lives in the parent and a button clears it — `checked`, `onCheckedChange`. */
+import { Button, Icon, Thumbnail, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const LIBRARY = [
+  { id: "hall", title: "Холл" },
+  { id: "office", title: "Офис" },
+  { id: "kitchen", title: "Кухня" },
+  { id: "meeting", title: "Переговорная" },
+  { id: "terrace", title: "Терраса" },
+  { id: "parking", title: "Парковка" },
+];
+
+export default function ThumbnailControlledExample() {
+  const [selected, setSelected] = React.useState<ReadonlySet<string>>(new Set(["hall"]));
+
+  const toggle = (id: string, checked: boolean) =>
+    setSelected((current) => {
+      const next = new Set(current);
+      if (checked) next.add(id);
+      else next.delete(id);
+      return next;
+    });
+
+  return (
+    <div className={styles.library}>
+      <div className={styles.libraryBar}>
+        <Typography as="span" variant="body-s" tone="muted" aria-live="polite">
+          {selected.size === 0 ? "Ничего не выбрано" : `Выбрано: ${selected.size}`}
+        </Typography>
+        <Button.Root
+          variant="ghost"
+          tone="neutral"
+          disabled={selected.size === 0}
+          onClick={() => setSelected(new Set())}
+        >
+          Снять выбор
+        </Button.Root>
+      </div>
+      <div className={styles.libraryGrid}>
+        {LIBRARY.map((photo) => (
+          <Thumbnail.Root
+            key={photo.id}
+            fullWidth
+            ratio="4:3"
+            aria-label={photo.title}
+            checked={selected.has(photo.id)}
+            onCheckedChange={(checked) => toggle(photo.id, checked)}
+          >
+            <Thumbnail.Image src={`https://picsum.photos/seed/office-${photo.id}/240/180`} />
+            <Thumbnail.Fallback>
+              <Icon name="object.image" />
+            </Thumbnail.Fallback>
+          </Thumbnail.Root>
+        ))}
+      </div>
+    </div>
+  );
+}

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

@@ -38,6 +38,37 @@
   grid-template-columns: repeat(auto-fill, minmax(min(100%, calc(var(--prime-space-16) * 3)), 1fr));
 }
 
+/* video.tsx: three videos side by side, wrapping on a narrow page. */
+.media {
+  display: grid;
+  gap: var(--prime-space-4);
+  width: 100%;
+  grid-template-columns: repeat(auto-fill, minmax(min(100%, calc(var(--prime-space-16) * 3)), 1fr));
+}
+
+/* controlled.tsx: the selection bar over a grid of tiles. */
+.library {
+  display: grid;
+  gap: var(--prime-space-3);
+  width: min(100%, calc(var(--prime-space-24) * 5));
+}
+
+.libraryBar {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--prime-space-3);
+}
+
+.libraryGrid {
+  display: grid;
+  gap: var(--prime-space-3);
+  grid-template-columns: repeat(
+      auto-fill,
+      minmax(min(100%, calc(var(--prime-space-24) * 1.25)), 1fr)
+    );
+}
+
 .cardContent {
   display: grid;
   gap: var(--prime-space-3);

package/src/components/thumbnail/examples/full-width.tsx

@@ -1,11 +1,8 @@
 /** Covers in a card grid take the card width and keep 16:9, so every cover has one height — `fullWidth`. */
-import { Bike } from "lucide-react";
-import { Card, createIcon, type PaletteColor, Thumbnail, Typography } from "prime-ui-kit";
+import { Card, Icon, type PaletteColor, Thumbnail, Typography } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
 
-const IconBike = createIcon(Bike);
-
 const BIKES: { id: string; title: string; meta: string; color: PaletteColor; photo?: string }[] = [
   { id: "1", title: "Honda ADV 350", meta: "2026 · 5672", color: "red" },
   {
@@ -28,7 +25,7 @@ export default function ThumbnailFullWidthExample() {
               <Thumbnail.Root ratio="16:9" color={bike.color} fullWidth>
                 {bike.photo ? <Thumbnail.Image src={bike.photo} /> : null}
                 <Thumbnail.Fallback>
-                  <IconBike />
+                  <Icon name="object.bike" />
                 </Thumbnail.Fallback>
               </Thumbnail.Root>
               <div className={styles.entityText}>

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

@@ -1,12 +1,8 @@
 /** A vehicle next to its name: the photo with an icon fallback underneath — `Thumbnail.Image`, `Thumbnail.Fallback`, `ratio`. */
-import { Bike } from "lucide-react";
-import { createIcon, Thumbnail, Typography } from "prime-ui-kit";
+import { Icon, Thumbnail, Typography } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
 
-/** A domain glyph the kit lacks, turned into a kit icon once. */
-const IconBike = createIcon(Bike);
-
 const PHOTO = "https://picsum.photos/seed/nmax/320/180";
 
 export default function ThumbnailOverviewExample() {
@@ -15,7 +11,7 @@ export default function ThumbnailOverviewExample() {
       <Thumbnail.Root ratio="16:9" color="gray">
         <Thumbnail.Image src={PHOTO} />
         <Thumbnail.Fallback>
-          <IconBike />
+          <Icon name="object.bike" />
         </Thumbnail.Fallback>
       </Thumbnail.Root>
       <div className={styles.entityText}>