prime-ui-kit 0.14.0 → 0.16.0

package/src/components/tag-select/examples/creatable.tsx

@@ -1,4 +1,4 @@
-/** A typed text that is not in the list becomes a new tag from the Create row or Enter and is saved on the server: the chip waits busy, and a tag the server refuses leaves again — `creatable`, `onCreate`, `defaultColor`. */
+/** A typed text that is not in the list becomes a new tag from the Create row or Enter and is saved on the server: the chip waits busy, and a tag the server refuses leaves again — `creatable`, `onCreate`, `fallbackColor`. */
 import { TagSelect, type TagSelectOption, Typography } from "prime-ui-kit";
 import * as React from "react";
 
@@ -27,7 +27,7 @@ export default function TagSelectCreatableExample() {
         label="Метки"
         options={OPTIONS}
         creatable
-        defaultColor="purple"
+        fallbackColor="purple"
         error={failure}
         onCreate={async (value) => {
           setFailure(undefined);

package/src/components/tag-select/examples/dismiss.tsx

@@ -0,0 +1,23 @@
+/** A tag list that stays open while the person reads the task beside it: Escape or Tab close it — `closeOnOutsideClick`, `closeOnEscape`. */
+import { TagSelect, type TagSelectOption } from "prime-ui-kit";
+
+const OPTIONS: TagSelectOption[] = [
+  { value: "design", label: "Дизайн", color: "purple" },
+  { value: "backend", label: "Бэкенд", color: "blue" },
+  { value: "frontend", label: "Фронтенд", color: "sky" },
+  { value: "urgent", label: "Срочно", color: "red" },
+  { value: "blocked", label: "Заблокировано", color: "orange" },
+];
+
+export default function TagSelectDismissExample() {
+  return (
+    <TagSelect
+      label="Метки задачи"
+      options={OPTIONS}
+      defaultValue={["backend"]}
+      placeholder="Добавить метку"
+      closeOnOutsideClick={false}
+      closeOnEscape
+    />
+  );
+}

package/src/components/tag-select/examples/examples.module.css

@@ -1,11 +1,11 @@
 /* Layout of the TagSelect scenarios: semantic tokens only. */
 
-/* in-form.tsx: field → field 20, actions at the end. */
+/* in-form.tsx: the fields (a Fieldset) → actions 32 (foundation §1). */
 .form {
   display: flex;
   flex-direction: column;
-  gap: var(--prime-space-5);
-  width: min(100%, var(--prime-modal-width-m));
+  gap: var(--prime-space-8);
+  width: min(100%, var(--prime-layout-form-width-m));
 }
 
 .actions {

package/src/components/tag-select/examples/in-form.tsx

@@ -1,5 +1,5 @@
 /** A new task form: the required labels field is checked on submit, its error shakes the field and leaves once a label is added, a calm note confirms the task; the tags go with the form — `required`, `error`, `creatable`, `name`. */
-import { Button, Input, TagSelect, type TagSelectOption, Typography } from "prime-ui-kit";
+import { Button, Fieldset, Input, TagSelect, type TagSelectOption, Typography } from "prime-ui-kit";
 import * as React from "react";
 
 import styles from "./examples.module.css";
@@ -29,37 +29,36 @@ export default function TagSelectInFormExample() {
 
   return (
     <form className={styles.form} noValidate onSubmit={submit}>
-      <Typography as="h3" variant="title-m">
-        Новая задача
-      </Typography>
-      <Input.Root label="Название" required>
-        <Input.Wrapper>
-          <Input.Field name="title" placeholder="Коротко о задаче" />
-        </Input.Wrapper>
-      </Input.Root>
-      <TagSelect
-        label="Метки"
-        name="labels"
-        required
-        hint="Помогают фильтровать задачи"
-        error={error}
-        options={LABELS}
-        value={labels}
-        onValueChange={(next) => {
-          setLabels(next);
-          setError(undefined);
-          setSaved(false);
-        }}
-        creatable
-        placeholder="Добавить метку"
-      />
-      <TagSelect
-        label="Наблюдатели"
-        name="watchers"
-        optional
-        options={PEOPLE}
-        placeholder="Добавить человека"
-      />
+      <Fieldset label="Новая задача">
+        <Input.Root label="Название" required>
+          <Input.Wrapper>
+            <Input.Field name="title" placeholder="Коротко о задаче" />
+          </Input.Wrapper>
+        </Input.Root>
+        <TagSelect
+          label="Метки"
+          name="labels"
+          required
+          hint="Помогают фильтровать задачи"
+          error={error}
+          options={LABELS}
+          value={labels}
+          onValueChange={(next) => {
+            setLabels(next);
+            setError(undefined);
+            setSaved(false);
+          }}
+          creatable
+          placeholder="Добавить метку"
+        />
+        <TagSelect
+          label="Наблюдатели"
+          name="watchers"
+          optional
+          options={PEOPLE}
+          placeholder="Добавить человека"
+        />
+      </Fieldset>
       <div className={styles.actions}>
         {saved ? (
           <Typography as="p" variant="body-s" tone="secondary">

package/src/components/tag-select/examples/sizes.tsx

@@ -11,7 +11,7 @@ const OPTIONS: TagSelectOption[] = [
 
 export default function TagSelectSizesExample() {
   return (
-    <>
+    <div>
       {SIZES.map((size) => (
         <TagSelect
           key={size}
@@ -22,6 +22,6 @@ export default function TagSelectSizesExample() {
           labels={{ panelHint: "Выберите метку" }}
         />
       ))}
-    </>
+    </div>
   );
 }

package/src/components/tag-select/examples/states.tsx

@@ -1,4 +1,4 @@
-/** A default field next to a disabled and an invalid one, with a disabled option in the list — `disabled`, `invalid`. */
+/** A default field next to a disabled and an invalid one and one whose focus shows without the ring, with a disabled option in the list — `disabled`, `invalid`, `focusRing`. */
 import { TagSelect, type TagSelectOption } from "prime-ui-kit";
 
 const OPTIONS: TagSelectOption[] = [
@@ -10,7 +10,7 @@ const OPTIONS: TagSelectOption[] = [
 
 export default function TagSelectStatesExample() {
   return (
-    <>
+    <div>
       <TagSelect
         label="default"
         options={OPTIONS}
@@ -19,6 +19,13 @@ export default function TagSelectStatesExample() {
       />
       <TagSelect label="disabled" options={OPTIONS} defaultValue={["msk", "kzn"]} disabled />
       <TagSelect label="invalid" options={OPTIONS} invalid placeholder="Добавить город" />
-    </>
+      <TagSelect
+        label="focusRing={false}"
+        options={OPTIONS}
+        defaultValue={["spb"]}
+        focusRing={false}
+        placeholder="Добавить город"
+      />
+    </div>
   );
 }

package/src/components/textarea/COMPONENT.md

@@ -41,7 +41,7 @@ Unlike Input, Textarea has no Wrapper / Field parts: `Textarea.Root` renders the
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `host tier, else "m"` | Tier for text, padding, radius, label and hint. One line of text sits exactly like an Input of the same size. Without it the tier of its host (LoginForm, Popover, a panel with a size), else `m`. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | host tier, else `"m"` | Tier for text, padding, radius, label and hint. One line of text sits exactly like an Input of the same size. Without it the tier of its host (LoginForm, Popover, a panel with a size), else `m`. |
 | `label` | `ReactNode` | — | Label above the field (`<label htmlFor>`). Without it, set `aria-label`. |
 | `required` | `boolean` | — | Native `required` on the textarea and a red `*` after the label (`aria-hidden`). |
 | `optional` | `boolean` | `false` | Muted marker right after the label text (`labels.optional`). |
@@ -49,7 +49,7 @@ Unlike Input, Textarea has no Wrapper / Field parts: `Textarea.Root` renders the
 | `error` | `ReactNode` | — | Error message in the hint slot; implies `invalid`. |
 | `invalid` | `boolean` | `false` | Danger inset ring on the field box, `aria-invalid` on the textarea. A non-empty `error` implies it. |
 | `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 />`. |
+| `counter` | `ReactNode` | — | Right side of the support row, usually `<Textarea.Counter current max />`. |
 | `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 `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. |
@@ -78,7 +78,7 @@ Unlike Input, Textarea has no Wrapper / Field parts: `Textarea.Root` renders the
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `value` | `string` | `the field's value` | Text to copy instead of the field's current value. |
+| `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
@@ -114,7 +114,7 @@ Textarea has no `variant` or `tone`: one field treatment (fill, no visible borde
 ### Flags
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| `focusRing={false}` | No focus ring; focus fill and caret remain | A single composer field where focus is obvious | `true` |
+| `focusRing` | `false`: no focus ring; focus fill and caret remain | A single composer field where focus is obvious | `true` |
 | `formatting` | A floating toolbar over a selection (bold, italic, strikethrough, code, spoiler, link, quote) and the Mod-hotkeys; each writes Markdown around the selection | The text is shown later with its Markdown (Message renders the same subset) | `false` |
 | `reserveSupportRow` | Empty support row of hint height | Live validation, fields side by side | `false` |
 | `required` / `optional` | Red `*` / muted «необязательно» after the label | Mark the minority of the form | — / `false` |
@@ -148,7 +148,7 @@ Inline save (`onCommit`): the text at focus is the committed one; blur and Mod+E
 
 ## Layout & spacing
 - Label → field: tier `label-gap` (`--prime-space-1` on xs/s, `--prime-space-2` on m–xl); field → support row: tier `hint-gap`.
-- Field → field in a form: `--prime-space-5`; group → actions: `--prime-space-8`.
+- Fields of a form stack in a label-less [Fieldset](../fieldset/COMPONENT.md) (20 apart); the form around the groups spaces them from its actions (32).
 - Width is always `100%` of the parent; set the width with the layout column.
 - Long words wrap (`overflow-wrap: anywhere`), so the field never overflows horizontally.
 - With `formatting` the toolbar floats `--prime-space-2` above the field box's start edge on the floating layer, over whatever is above the field; it takes no room in the layout.
@@ -156,6 +156,8 @@ Inline save (`onCommit`): the text at focus is the committed one; blur and Mod+E
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 | Key | Action |
 |---|---|
 | `Tab` | Focuses the field, then the buttons in its corner; Enter inserts a line break instead of submitting the form. |
@@ -166,6 +168,8 @@ Inline save (`onCommit`): the text at focus is the committed one; blur and Mod+E
 | `Home` · `End` | Jump to the first / last formatting button. |
 
 ### ARIA
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 - `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.
@@ -200,7 +204,7 @@ Inline save (`onCommit`): the text at focus is the committed one; blur and Mod+E
 |---|---|
 | [overview.tsx](examples/overview.tsx) | A labelled multi-line field with a hint; the height follows the text — `label`, `hint`. |
 | [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`. |
+| [states.tsx](examples/states.tsx) | A default field next to a read-only, a disabled and an invalid one with no message — `readOnly`, `disabled`, `invalid`. |
 | [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, 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`. |
@@ -222,5 +226,5 @@ Inline save (`onCommit`): the text at focus is the committed one; blur and Mod+E
 - `formatting` on text that is shown as plain text → the reader sees `**` and `||`; turn it on only where the text is rendered with its Markdown.
 
 ## Related
-- **Built from:** [Label](../label/COMPONENT.md) (`label`), [Hint](../hint/COMPONENT.md) (`hint`, `error`), [Tooltip](../tooltip/COMPONENT.md) (corner actions, formatting tools), [Spinner](../spinner/COMPONENT.md) (`onCommit`), [Button](../button/COMPONENT.md) and [Kbd](../kbd/COMPONENT.md) (formatting tools), Icon (`format.*`); `internal/textFormatting` + `internal/textFormattingToolbar` (the formatting shared with Composer)
+- **Built from:** [Label](../label/COMPONENT.md) (`label`), [Hint](../hint/COMPONENT.md) (`hint`, `error`), [Tooltip](../tooltip/COMPONENT.md) (corner actions, formatting tools), [Spinner](../spinner/COMPONENT.md) (`onCommit`), [Button](../button/COMPONENT.md) and [Kbd](../kbd/COMPONENT.md) (formatting tools), Icon (`format.*`); `internal/textFormatting` + `internal/textFormattingToolbar` (the formatting shared with Composer), [VisuallyHidden](../visually-hidden/COMPONENT.md)
 - **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/examples.module.css

@@ -1,23 +1,10 @@
 /* Layout of the Textarea scenarios: semantic tokens only. */
 
-/* in-form.tsx: field → field 20, group → actions 32 (foundation §1). */
+/* in-form.tsx, validation.tsx: the fields (a Fieldset), then the actions — group → actions 32. */
 .form {
-  display: flex;
-  flex-direction: column;
+  display: grid;
   gap: var(--prime-space-8);
-  width: min(100%, var(--prime-modal-width-m));
-}
-
-.formHeader {
-  display: flex;
-  flex-direction: column;
-  gap: var(--prime-space-1);
-}
-
-.formFields {
-  display: flex;
-  flex-direction: column;
-  gap: var(--prime-space-5);
+  width: min(100%, var(--prime-layout-form-width-m));
 }
 
 .formActions {

package/src/components/textarea/examples/in-form.tsx

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

package/src/components/textarea/examples/sizes.tsx

@@ -7,13 +7,16 @@ export default function TextareaSizesExample() {
   return (
     <>
       {SIZES.map((size) => (
-        <Textarea.Root
-          key={size}
-          size={size}
-          label={size}
-          placeholder="Комментарий к заказу"
-          hint="Курьер увидит этот текст"
-        />
+        <div key={size}>
+          <div>
+            <Textarea.Root
+              size={size}
+              label={size}
+              placeholder="Комментарий к заказу"
+              hint="Курьер увидит этот текст"
+            />
+          </div>
+        </div>
       ))}
     </>
   );

package/src/components/textarea/examples/states.tsx

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

package/src/components/textarea/examples/validation.tsx

@@ -1,7 +1,9 @@
 /** 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`. */
-import { Button, Textarea } from "prime-ui-kit";
+import { Button, Fieldset, Textarea } from "prime-ui-kit";
 import * as React from "react";
 
+import styles from "./examples.module.css";
+
 const MIN_REASON = 20;
 
 export default function TextareaValidationExample() {
@@ -9,42 +11,49 @@ export default function TextareaValidationExample() {
   const [comment, setComment] = React.useState("Оплата частями");
   const [commentError, setCommentError] = React.useState<string>();
 
-  const send = () => setCommentError(/\d{3,}/.test(comment) ? undefined : "Укажите номер договора");
+  const send = (event: React.FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    setCommentError(/\d{3,}/.test(comment) ? undefined : "Укажите номер договора");
+  };
 
   return (
-    <>
-      <Textarea.Root
-        label="Описание задачи"
-        required
-        defaultValue="Подготовить акт сверки с поставщиком за третий квартал."
-        hint="Исполнитель увидит его в карточке задачи"
-      />
-      <Textarea.Root
-        label="Причина отказа"
-        required
-        value={reason}
-        onValueChange={setReason}
-        hint="Клиент получит её в письме"
-        error={
-          reason.trim().length < MIN_REASON
-            ? `Опишите причину хотя бы в ${MIN_REASON} символах`
-            : undefined
-        }
-      />
-      <Textarea.Root
-        label="Комментарий для бухгалтерии"
-        optional
-        reserveSupportRow
-        value={comment}
-        onValueChange={(value) => {
-          setComment(value);
-          setCommentError(undefined);
-        }}
-        error={commentError}
-      />
-      <Button.Root variant="soft" tone="neutral" onClick={send}>
-        Отправить в бухгалтерию
-      </Button.Root>
-    </>
+    <form className={styles.form} noValidate onSubmit={send}>
+      <Fieldset>
+        <Textarea.Root
+          label="Описание задачи"
+          required
+          defaultValue="Подготовить акт сверки с поставщиком за третий квартал."
+          hint="Исполнитель увидит его в карточке задачи"
+        />
+        <Textarea.Root
+          label="Причина отказа"
+          required
+          value={reason}
+          onValueChange={setReason}
+          hint="Клиент получит её в письме"
+          error={
+            reason.trim().length < MIN_REASON
+              ? `Опишите причину хотя бы в ${MIN_REASON} символах`
+              : undefined
+          }
+        />
+        <Textarea.Root
+          label="Комментарий для бухгалтерии"
+          optional
+          reserveSupportRow
+          value={comment}
+          onValueChange={(value) => {
+            setComment(value);
+            setCommentError(undefined);
+          }}
+          error={commentError}
+        />
+      </Fieldset>
+      <div className={styles.formActions}>
+        <Button.Root type="submit" variant="soft" tone="neutral">
+          Отправить в бухгалтерию
+        </Button.Root>
+      </div>
+    </form>
   );
 }

package/src/components/thumbnail/COMPONENT.md

@@ -41,7 +41,7 @@ Thumbnail.Root          frame (a <div>; the child with asChild; a <button role="
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Height 24 · 32 · 40 · 48 · 64 px, radius 4 · 6 · 8 · 8 · 12; width follows `ratio`. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | host tier, else `"m"` | Height 24 · 32 · 40 · 48 · 64 px, radius 4 · 6 · 8 · 8 · 12; width follows `ratio`. Without it the tile takes the tier of its host, else `m`. |
 | `ratio` | `"1:1" \| "4:3" \| "3:2" \| "16:9" \| "3:4"` | `"1:1"` | Aspect ratio, width ÷ height. |
 | `color` | `"gray" \| "blue" \| "green" \| "orange" \| "red" \| "yellow" \| "purple" \| "sky" \| "pink" \| "teal"` | `"gray"` | Fallback fill and icon hue; a color that means something (category, vehicle color). |
 | `variant` | `"soft" \| "solid"` | `"soft"` | Fallback fill: a soft tint with a hue icon, or a solid hue with a contrasting icon. |
@@ -54,7 +54,7 @@ Thumbnail.Root          frame (a <div>; the child with asChild; a <button role="
 | `…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. Loads lazily and decodes off the main thread (`loading="lazy"`, `decoding="async"`; pass either to override).
+`ref` → `HTMLImageElement`. The picture; hidden while it loads and after an error, so the Fallback shows through. A new `src` fades in over the last one. Loads lazily and decodes off the main thread (`loading="lazy"`, `decoding="async"`; pass either to override).
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -64,16 +64,16 @@ Thumbnail.Root          frame (a <div>; the child with asChild; a <button role="
 | `…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).
+`ref` → `HTMLVideoElement`. A video in the frame (`preload="metadata"`, `playsInline`); the Fallback shows until its first frame (with a `poster`, its metadata). Without `controls`: the duration pill and a play mark that fades while it plays.
 
 | 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. |
+| `poster` | `string` | — | A still shown before playing; with it the video counts as loaded once its metadata is in. |
 | `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. |
+| `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
@@ -132,26 +132,30 @@ Thumbnail.Root          frame (a <div>; the child with asChild; a <button role="
 | 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 |
+| video loading | `Thumbnail.Video` mounted | `data-status="loading"` until the first frame (`loadeddata`) — with a `poster`, until its metadata (`loadedmetadata`) — then `loaded`; `error` falls back like an image |
+| video still / playing | no `controls`, not looping | 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 (the control `l` height, a glyph of half of it, `--prime-color-media-disk` under `--prime-media-disk-blur`), at 60% of a lower frame's height; it fades and shrinks away while the video plays (`data-shown="false"`) and comes back on a pause. The duration at the end corner (from `l` and `fullWidth`) is the media pill (`internal/mediaPill`) |
+| hover / press / focus | `asChild` or selectable | `data-interactive`: lift on `--prime-shadow-overlay` (`@media (hover: hover)`), the kit's press (`--prime-motion-press-scale`, `fast`), focus ring |
+| selected | `checked` · `defaultChecked` | `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`.
+- Thumbnail + text in a row: flex, `align-items: center`, the row's gap; the text column `min-width: 0` with `truncate`.
 - In a table the row grows to the thumbnail; never shrink the thumbnail to the row.
-- Card covers: `fullWidth` inside the card body, gap `--prime-space-3` to the title.
+- Card covers: `fullWidth` inside the card body, the body's gap to the title.
 - No outline by default: the fill separates the preview.
 
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 | 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
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 - 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.
 - A preview that opens the object is `asChild` on a `<button>` or `<a>`; name it (`aria-label`) when the picture is all it shows.
@@ -169,11 +173,12 @@ No `labels`.
 | [overview.tsx](examples/overview.tsx) | A vehicle next to its name: the photo with an icon fallback underneath — `Thumbnail.Image`, `Thumbnail.Fallback`, `ratio`. |
 | [variants.tsx](examples/variants.tsx) | The fallback fill: a soft tint or a solid hue, in a color that means something — `variant`, `color`. |
 | [sizes.tsx](examples/sizes.tsx) | Every height tier, 24 to 64 px; `m` fits a two-line table cell — `size`. |
-| [states.tsx](examples/states.tsx) | No image (an icon or a short label on the fill) and an image that fails and falls back by itself. |
+| [states.tsx](examples/states.tsx) | No image (an icon or a short label on the fill) and an image that fails and falls back by itself — `Thumbnail.Fallback`, `Thumbnail.Image`. |
 | [ratios.tsx](examples/ratios.tsx) | Every aspect ratio at the same height; keep one ratio per list — `ratio`. |
+| [fit.tsx](examples/fit.tsx) | A supplier's wide banner in a square frame: cropped to fill or shown whole on the fill — `fit`. |
 | [ring.tsx](examples/ring.tsx) | A faint inner ring for a white-background photo on a light surface, where the edge would vanish — `ring`. |
 | [full-width.tsx](examples/full-width.tsx) | Covers in a card grid take the card width and keep 16:9, so every cover has one height — `fullWidth`. |
-| [video.tsx](examples/video.tsx) | Videos in the frame: a walkthrough without a poster shows its first frame, a play mark and the duration; a short clip loops muted like a GIF; a video message plays in place with its controls — `Thumbnail.Video`, `autoPlay`, `controls`. |
+| [video.tsx](examples/video.tsx) | Videos in the frame: a walkthrough without a poster shows its first frame, a play mark and the duration; a briefing shows its poster and its own duration format; a short clip loops muted like a GIF; a video message plays in place with its controls — `Thumbnail.Video`, `poster`, `formatDuration`, `autoPlay`, `controls`. |
 | [pressable.tsx](examples/pressable.tsx) | Photos of a delivery that open a viewer: the frame is put on a button, so it lifts on hover, presses and takes the focus ring — `asChild`. |
 | [controlled.tsx](examples/controlled.tsx) | A media library picks photos for a listing: each tile is a checkbox with its check in the corner, the selection lives in the parent and a button clears it — `checked`, `onCheckedChange`. |
 
@@ -187,5 +192,5 @@ No `labels`.
 - A bare `<video>` sized in CSS next to thumbnails → `Thumbnail.Video` in the same frame.
 
 ## Related
-- **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))
+- **Built from:** [Checkbox](../checkbox/COMPONENT.md) (`Checkbox.Indicator` of a selectable tile), `internal/mediaDisk` (the play mark, one look with the shade circle Button), `internal/mediaPill` (the duration), `internal/imageSlot` (the picture and its fallback; a new picture cross-fades over the last), `internal/press` (the press of a pressable tile)
 - **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/examples.module.css

@@ -1,6 +1,6 @@
 /* Layout of the Thumbnail scenarios: semantic tokens only. */
 
-/* ratios.tsx, ring.tsx: thumbnails with captions in one line. */
+/* ratios.tsx, fit.tsx, ring.tsx: thumbnails with captions in one line. */
 .row {
   display: flex;
   flex-wrap: wrap;
@@ -20,7 +20,7 @@
   display: flex;
   align-items: center;
   gap: var(--prime-space-3);
-  width: min(100%, var(--prime-modal-width-s));
+  width: min(100%, var(--prime-layout-form-width-s));
   min-width: 0;
 }