prime-ui-kit 0.14.0 → 0.16.0

package/dist/components/switch/Switch.d.ts

@@ -1,34 +1,59 @@
 import type * as React from "react";
 import { type ChoiceLabelProps } from "../../internal/ChoiceField";
 import type { ControlSize } from "../../internal/states";
+export type SwitchLabels = {
+    /** Muted marker after the label text when `optional`. */
+    optional: string;
+};
+export declare const SWITCH_LABELS: SwitchLabels;
 export type SwitchRootProps = Omit<React.InputHTMLAttributes<HTMLInputElement>, "type" | "size" | "checked" | "defaultChecked" | "onChange"> & {
+    /**
+     * Controlled state.
+     */
     checked?: boolean;
+    /**
+     * Initial state when uncontrolled.
+     */
     defaultChecked?: boolean;
     /**
-     * The new state. Return the save's promise to apply it on a server: the thumb waits in the new
-     * position with a spinner (`aria-busy`) and presses do nothing; resolve keeps it, reject glides
-     * it back.
+     * Called with the new state on every toggle. Return the save's promise: the thumb waits with a spinner; a controlled owner sets `checked` before resolving; on reject the thumb goes back (say why with `error`).
      */
     onCheckedChange?: (checked: boolean) => void | Promise<void>;
     /**
-     * Saving: a spinner in the thumb, `aria-busy`, presses do nothing. For an owner that tracks the
-     * request itself; a promise from `onCheckedChange` does this on its own.
+     * Saving, for an owner that tracks the request itself: a spinner in the thumb, `aria-busy` on the input, presses do nothing. A promise from `onCheckedChange` does the same on its own.
      */
     loading?: boolean;
-    /** Invalid state; a non-empty `error` implies it. */
+    /**
+     * Danger ring on the off track and `aria-invalid`. A non-empty `error` implies it.
+     */
     invalid?: boolean;
-    /** Help text under the label text. Hidden while `error` is shown. */
+    /**
+     * Help text under the label text. Hidden while `error` is shown.
+     */
     hint?: React.ReactNode;
-    /** Error message in the hint slot; implies `invalid`. */
+    /**
+     * Error message in the hint slot; implies `invalid`.
+     */
     error?: React.ReactNode;
-    /** Tier. Default: the tier of the surrounding control (a form, a panel), else `m`. */
+    /**
+     * Tier of the track (24×16 … 44×24), the text and the gap. Without it the tier of its host (a form, a panel), else `m`.
+     */
     size?: ControlSize;
-    /** `Switch.Label`; without it only the track renders (give it an `aria-label`). */
+    /**
+     * Muted `labels.optional` after the label text; the field may stay off.
+     */
+    optional?: boolean;
+    /**
+     * Built-in strings, see Labels.
+     */
+    labels?: Partial<SwitchLabels>;
+    /**
+     * `Switch.Label`. Without it only the track renders — name it with `aria-label` or `aria-labelledby`.
+     */
     children?: React.ReactNode;
-    /** The native `role="switch"` input. */
     ref?: React.Ref<HTMLInputElement>;
 };
-declare function SwitchRoot({ id, checked: checkedProp, defaultChecked, onCheckedChange, loading, invalid, hint, error, size: sizeProp, disabled: disabledProp, readOnly, className, "aria-describedby": ariaDescribedBy, children, ref, ...inputRest }: SwitchRootProps): import("react/jsx-runtime").JSX.Element;
+declare function SwitchRoot({ id, checked: checkedProp, defaultChecked, onCheckedChange, loading, invalid, hint, error, size: sizeProp, optional, labels: labelsProp, disabled: disabledProp, readOnly, className, "aria-describedby": ariaDescribedBy, children, ref, ...inputRest }: SwitchRootProps): import("react/jsx-runtime").JSX.Element;
 declare namespace SwitchRoot {
     var displayName: string;
 }

package/dist/components/tabs/Tabs.d.ts

@@ -1,32 +1,56 @@
 import * as React from "react";
 import { type ControlSize, type PaletteColor } from "../../internal/states";
+import { type AsyncHandler } from "../../internal/usePendingChanges";
 export type TabsLabels = {
     /** Name of the close button of a removable tab; `{label}` is the tab's title. */
     remove: string;
 };
+export declare const TABS_LABELS: TabsLabels;
 type TabsOrientation = "horizontal" | "vertical";
 export type TabsRootProps = Omit<React.HTMLAttributes<HTMLDivElement>, "defaultValue"> & {
+    /**
+     * Active tab (controlled).
+     */
     value?: string;
+    /**
+     * Initial active tab (uncontrolled). With `""` no tab is selected.
+     */
     defaultValue?: string;
+    /**
+     * Called with the new active value.
+     */
     onValueChange?: (value: string) => void;
-    /** Default `horizontal`. A vertical list stacks above the panel in containers narrower than 600px. */
+    /**
+     * List direction and arrow keys. Vertical: a column of sections beside the panel, which becomes a horizontal strip in a container below 600px.
+     */
     orientation?: TabsOrientation;
+    /**
+     * Control tier: text, icon, spacing, folder radius and the gap between the strip and the panel; a tab is at least the control height. Without it the tier of the host.
+     */
     size?: ControlSize;
-    /** Text and icon colour of the active tab. Default `neutral`: primary text, accent icon. */
+    /**
+     * Colour of the active tab: `neutral` is primary text with an accent icon, `accent` puts text and icon in accent.
+     */
     tone?: "neutral" | "accent";
     /**
-     * Horizontal tabs fill the list and tend to equal widths, never narrower than their content.
-     * Default `true`; `false` sizes each tab to its content.
+     * Horizontal tabs fill the list and tend to equal widths within `minItemWidth` … `maxItemWidth`; `false` sizes each tab to its content within the same bounds.
      */
     fullWidth?: boolean;
-    /** Narrowest a horizontal tab with a label gets (px or a CSS length); never below its content. */
+    /**
+     * Narrowest a horizontal tab with a label gets, px or a CSS length; a tab is also never narrower than its content (up to `maxItemWidth`).
+     */
     minItemWidth?: number | string;
-    /** Widest a horizontal tab gets (px or a CSS length); a longer label ends with an ellipsis. */
+    /**
+     * Widest a horizontal tab gets, px or a CSS length (`"none"` lifts the cap); a longer label ends with an ellipsis.
+     */
     maxItemWidth?: number | string;
+    /**
+     * Built-in strings, see Labels.
+     */
     labels?: Partial<TabsLabels>;
     ref?: React.Ref<HTMLDivElement>;
 };
-declare function TabsRoot({ value, defaultValue, onValueChange, orientation, size, tone, fullWidth, minItemWidth, maxItemWidth, labels, children, className, style, ...rest }: TabsRootProps): import("react/jsx-runtime").JSX.Element;
+declare function TabsRoot({ value, defaultValue, onValueChange, orientation, size: sizeProp, tone, fullWidth, minItemWidth, maxItemWidth, labels, children, className, style, ...rest }: TabsRootProps): import("react/jsx-runtime").JSX.Element;
 declare namespace TabsRoot {
     var displayName: string;
 }
@@ -38,18 +62,20 @@ declare namespace TabsList {
     var displayName: string;
 }
 export type TabsItemProps = Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "value" | "type" | "role" | "onClick"> & {
+    /**
+     * Value that selects this tab and its panel.
+     */
     value: string;
+    /**
+     * Disables the tab; clicks and arrow keys skip it.
+     */
     disabled?: boolean;
     /**
-     * Makes the tab closable: a close button, `Delete` / `Backspace` on the focused tab and a middle
-     * click. Closing the active tab selects its neighbour; remove the item in this callback. Return a
-     * promise to confirm first (unsaved changes): while pending the close button shows loading and
-     * the tab stays selected; resolved — the neighbour takes over; rejected — nothing changes.
+     * Makes the tab closable (close button, `Delete` / `Backspace`, middle click); remove the item from your list here. Return a promise to confirm first: rejected, the tab stays.
      */
-    onRemove?: () => void | Promise<void>;
+    onRemove?: AsyncHandler;
     /**
-     * Plain text, or parts: `Tabs.Icon`, `Tabs.Label`, `Tabs.Count`, `Tabs.Description`.
-     * A `Tabs.Description` makes the item two-line and becomes its accessible description.
+     * Plain text, or `Tabs.Icon` / `Tabs.Label` / `Tabs.Count` / `Tabs.Description`. A description makes the tab two-line.
      */
     children: React.ReactNode;
     ref?: React.Ref<HTMLButtonElement>;
@@ -59,6 +85,9 @@ declare namespace TabsItem {
     var displayName: string;
 }
 export type TabsIconProps = Omit<React.HTMLAttributes<HTMLSpanElement>, "children"> & {
+    /**
+     * The icon, e.g. `<Icon name="field.calendar" />`.
+     */
     children: React.ReactNode;
     ref?: React.Ref<HTMLSpanElement>;
 };
@@ -67,20 +96,29 @@ declare namespace TabsIcon {
     var displayName: string;
 }
 export type TabsLabelProps = Omit<React.HTMLAttributes<HTMLSpanElement>, "children"> & {
+    /**
+     * Title text.
+     */
     children: React.ReactNode;
     ref?: React.Ref<HTMLSpanElement>;
 };
 /**
  * Tab title; truncates with an ellipsis in a narrow tab. Text labels reserve the width of the
- * medium weight, so the row does not shift when a tab becomes active.
+ * medium weight, so the row does not shift when a tab becomes active. In a list collapsed to
+ * icons the visible title leaves the row and a VisuallyHidden copy keeps naming the tab.
  */
 declare function TabsLabel({ children, className, ...rest }: TabsLabelProps): import("react/jsx-runtime").JSX.Element;
 declare namespace TabsLabel {
     var displayName: string;
 }
 export type TabsCountProps = Omit<React.HTMLAttributes<HTMLSpanElement>, "children" | "color"> & {
-    /** Badge hue. Default `gray`. */
+    /**
+     * Badge hue.
+     */
     color?: PaletteColor;
+    /**
+     * The number.
+     */
     children: React.ReactNode;
     ref?: React.Ref<HTMLSpanElement>;
 };
@@ -90,7 +128,9 @@ declare namespace TabsCount {
     var displayName: string;
 }
 export type TabsDescriptionProps = Omit<React.HTMLAttributes<HTMLSpanElement>, "children"> & {
-    /** Muted second line; wrap a key value in `<strong>` to emphasize it. */
+    /**
+     * Second-line text; wrap a key value in `<strong>`.
+     */
     children: React.ReactNode;
     ref?: React.Ref<HTMLSpanElement>;
 };
@@ -107,10 +147,13 @@ declare namespace TabsSeparator {
     var displayName: string;
 }
 export type TabsPanelProps = React.HTMLAttributes<HTMLDivElement> & {
+    /**
+     * Tab value this panel belongs to.
+     */
     value: string;
     ref?: React.Ref<HTMLDivElement>;
 };
-declare function TabsPanel({ value, children, className, ...rest }: TabsPanelProps): import("react/jsx-runtime").JSX.Element | null;
+declare function TabsPanel({ value, ...rest }: TabsPanelProps): import("react/jsx-runtime").JSX.Element | null;
 declare namespace TabsPanel {
     var displayName: string;
 }

package/dist/components/tag-select/TagSelect.d.ts

@@ -1,4 +1,5 @@
-import { type FieldFrameProps, type FieldRootDomProps } from "../../internal/FieldFrame";
+import * as React from "react";
+import { type FieldFocusRingProps, type FieldFrameProps, type FieldRootDomProps } from "../../internal/FieldFrame";
 import { type ControlSize, type PaletteColor } from "../../internal/states";
 export type TagSelectOption = {
     value: string;
@@ -38,57 +39,110 @@ export type TagSelectLabels = {
     /** Muted marker after the label when `optional`. */
     optional: string;
 };
-export type TagSelectProps = FieldRootDomProps & FieldFrameProps & {
-    /** Available tags: value, label and chip color. */
+export declare const TAG_SELECT_LABELS: TagSelectLabels;
+export type TagSelectProps = FieldRootDomProps & FieldFrameProps & FieldFocusRingProps & {
+    /**
+     * Available tags: `{ value, label, color?, disabled? }`.
+     */
     options: TagSelectOption[];
+    /**
+     * Controlled picked values.
+     */
     value?: string[];
+    /**
+     * Initial picked values, uncontrolled.
+     */
     defaultValue?: string[];
+    /**
+     * Called with the new list after a pick, a removal or a creation.
+     */
     onValueChange?: (value: string[]) => void;
+    /**
+     * Controlled open state of the list.
+     */
     open?: boolean;
+    /**
+     * Initial open state, uncontrolled.
+     */
     defaultOpen?: boolean;
+    /**
+     * Called on every open and close: focus, a field click, typing, arrows, Escape, an outside press; typing closes it when nothing matches.
+     */
     onOpenChange?: (open: boolean) => void;
-    /** Allow adding a value that is not in `options`. */
+    /**
+     * Escape closes the list; focus stays in the input.
+     */
+    closeOnEscape?: boolean;
+    /**
+     * A press outside the field and the list closes the list.
+     */
+    closeOnOutsideClick?: boolean;
+    /**
+     * A typed text that is not an option can be added (the Create row or Enter).
+     */
     creatable?: boolean;
     /**
-     * A new value was created (Create row or Enter), not picked from `options`. Return the save's
-     * promise: the new chip waits busy until it settles; reject — it leaves the selection and
-     * `labels.createFailed` is announced.
+     * A new value was created, not picked from `options`; it joins the selection at once. Return the save's promise: the chip waits busy; on reject it leaves again (say why with `error`).
      */
     onCreate?: (value: string) => void | Promise<void>;
-    /** Chip color of values without an option color, including created ones. */
-    defaultColor?: PaletteColor;
     /**
-     * Enables the «⋯» row menu: tag name and color. `value` never changes. Return the save's
-     * promise: the new name or color shows at once and «⋯» spins until it settles; reject — the
-     * option goes back and `labels.updateFailed` is announced.
+     * Chip color of values without an option color, created ones included.
+     */
+    fallbackColor?: PaletteColor;
+    /**
+     * Enables the row «⋯» menu to rename and recolor a tag; `value` never changes. Return the save's promise and apply the change to `options` before it resolves; on reject the option goes back.
      */
     onOptionUpdate?: (value: string, updates: TagSelectOptionUpdate) => void | Promise<void>;
     /**
-     * Enables «Удалить» in the row menu; the value is also removed from the selection. A returned
-     * Promise holds the row pending (spinner on «⋯») and changes nothing until it resolves; a
-     * rejection keeps the option and the selection (the owner shows why).
+     * Enables «Удалить» in the row menu; the value also leaves the selection. A returned Promise defers it: resolve deletes, reject keeps everything (e.g. after a confirmation).
      */
     onOptionDelete?: (value: string) => void | Promise<void>;
+    /**
+     * Disabled field and chips; the list never opens.
+     */
     disabled?: boolean;
-    /** Form field name: one hidden input per selected value. */
+    /**
+     * Form field name: one hidden input per selected value (read with `formData.getAll(name)`).
+     */
     name?: string;
+    /**
+     * Text in the input while no tag is picked.
+     */
     placeholder?: string;
-    /** Danger ring and `aria-invalid`; a non-empty `error` implies it. */
+    /**
+     * Danger inset ring and `aria-invalid`.
+     */
     invalid?: boolean;
-    /** Field tier; the list uses the same tier, chips one tier down. */
+    /**
+     * Field tier; the list uses the same tier, chips one tier down. Without it the tier of its host (a form, a panel with a size), else `m`.
+     */
     size?: ControlSize;
-    /** Id of the text input; generated when omitted. */
+    /**
+     * Id of the input; generated when omitted.
+     */
     id?: string;
+    /**
+     * Built-in strings, see Labels (`colorNames` merges by key).
+     */
     labels?: Partial<TagSelectLabels>;
+    /**
+     * Class on the field frame `<div>`.
+     */
     className?: string;
+    /**
+     * Name of the input and the list when there is no `label`.
+     */
     "aria-label"?: string;
+    /**
+     * Name of the input and the list when there is no `label`.
+     */
     "aria-labelledby"?: string;
 };
 /**
  * A multi-value field shown as tag chips: pick from a list, type to filter, create new values.
  * At rest one row (extra chips fold into «+N»); focused or open it shows every chip.
  */
-export declare function TagSelect({ options, value: valueProp, defaultValue, onValueChange, open: openProp, defaultOpen, onOpenChange, creatable, onCreate, defaultColor, onOptionUpdate, onOptionDelete, disabled: disabledProp, name, placeholder, invalid: invalidProp, focusRing, size, label, required, optional, hint, error, id: idProp, labels: labelsProp, className, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, ...rest }: TagSelectProps): import("react/jsx-runtime").JSX.Element;
+export declare function TagSelect({ options, value: valueProp, defaultValue, onValueChange, open: openProp, defaultOpen, onOpenChange, closeOnEscape, closeOnOutsideClick, creatable, onCreate, fallbackColor, onOptionUpdate, onOptionDelete, disabled: disabledProp, name, placeholder, invalid: invalidProp, focusRing, size: sizeProp, label, required, optional, hint, error, id: idProp, labels: labelsProp, className, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, ...rest }: TagSelectProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>;
 export declare namespace TagSelect {
     var displayName: string;
 }

package/dist/components/textarea/Textarea.d.ts

@@ -1,6 +1,7 @@
 import * as React from "react";
 import { type FieldActionButtonProps } from "../../internal/FieldAction";
 import { type FieldCommitHandler } from "../../internal/FieldCommit";
+import { type FieldFocusRingProps } from "../../internal/FieldFrame";
 import type { ControlSize } from "../../internal/states";
 import { type TextFormattingLabels } from "../../internal/textFormatting";
 export type { TextFormat } from "../../internal/textFormatting";
@@ -21,53 +22,71 @@ export type TextareaLabels = TextFormattingLabels & {
     /** Announced once an `onCommit` save succeeds. */
     saved: string;
 };
-export type TextareaRootProps = Omit<React.TextareaHTMLAttributes<HTMLTextAreaElement>, "size" | "children"> & {
+export declare const TEXTAREA_LABELS: TextareaLabels;
+export type TextareaRootProps = Omit<React.TextareaHTMLAttributes<HTMLTextAreaElement>, "size" | "children"> & FieldFocusRingProps & {
     /**
-     * Saves the field on its own (inline editing): fires with the value on blur and Mod+Enter when it
-     * differs from the last committed one; Escape reverts to it. Return a Promise to show a spinner
-     * in the field's corner while it runs (the field stays editable, Tab moves on); a rejection puts
-     * the committed value back — show why through `error`. Success shows a brief check.
+     * 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`.
      */
     onCommit?: FieldCommitHandler;
-    /** Actions in the field's top end corner: `Textarea.CopyButton`, `Textarea.Action`. */
+    /**
+     * Actions in the field's top end corner: `Textarea.CopyButton`, `Textarea.Action`.
+     */
     children?: React.ReactNode;
-    /** Tier. Default: the tier of the surrounding control (a form, a panel), 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?: ControlSize;
-    /** Invalid state: danger ring and `aria-invalid`. A non-empty `error` implies it. */
+    /**
+     * Danger inset ring on the field box, `aria-invalid` on the textarea. A non-empty `error` implies it.
+     */
     invalid?: boolean;
     /**
-     * Draws the focus ring on the field box (default). `false` hides only the visual ring — focus,
-     * keyboard and ARIA are unchanged, the error ring still shows. Turn it off only where focus is
-     * otherwise obvious (a single composer field with a caret); WCAG 2.4.7.
+     * Label above the field (`<label htmlFor>`). Without it, set `aria-label`.
      */
-    focusRing?: boolean;
     label?: React.ReactNode;
-    /** Shows the muted optional marker after the label text (`labels.optional`). */
+    /**
+     * Muted marker right after the label text (`labels.optional`).
+     */
     optional?: boolean;
+    /**
+     * Help text under the field. Hidden while `error` is shown.
+     */
     hint?: React.ReactNode;
-    /** Error message; replaces the hint in the same slot and implies `invalid`. */
+    /**
+     * Error message in the hint slot; implies `invalid`.
+     */
     error?: React.ReactNode;
-    /** Right-aligned slot of the support row, e.g. `<Textarea.Counter current={n} max={500} />`. */
+    /**
+     * Right side of the support row, usually `<Textarea.Counter current max />`.
+     */
     counter?: React.ReactNode;
-    /** Always render the support row so an appearing error does not shift the layout. */
+    /**
+     * Always render the support row (min height = hint line height), so an appearing error does not shift the layout.
+     */
     reserveSupportRow?: boolean;
-    /** Height follows the content. `false` → fixed height with native vertical resize. */
+    /**
+     * 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.
+     */
     autoResize?: boolean;
-    /** Minimum height in lines (default 3); with `autoResize={false}` the fixed height. */
+    /**
+     * Minimum height in lines; with `autoResize={false}` the fixed height. `rows={1}` makes a field that starts as one line, like an Input.
+     */
     rows?: 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.
+     * 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.
      */
     maxRows?: number;
-    /** Called with the new string value; native `onChange` still fires. */
+    /**
+     * Called with the new string; native `onChange` still fires first.
+     */
     onValueChange?: (value: string) => void;
     /**
-     * Markdown formatting, as in Composer: selecting text shows a floating toolbar (bold, italic,
-     * strikethrough, code, spoiler, link, quote) and enables the hotkeys; each writes Markdown around
-     * the selection.
+     * Selecting text shows a floating toolbar of seven Markdown tools and enables their hotkeys; a tool wraps the selection, a second press unwraps it. Off: plain text.
      */
     formatting?: boolean;
+    /**
+     * Built-in strings, see Labels.
+     */
     labels?: Partial<TextareaLabels>;
     /** The native `<textarea>`. */
     ref?: React.Ref<HTMLTextAreaElement>;
@@ -81,7 +100,13 @@ declare namespace TextareaRoot {
     var displayName: string;
 }
 export type TextareaCounterProps = Omit<React.HTMLAttributes<HTMLSpanElement>, "children"> & {
+    /**
+     * Current length.
+     */
     current: number;
+    /**
+     * Limit; `current > max` turns the counter danger (`data-invalid="true"`). Add `maxLength` on the root for a hard limit.
+     */
     max: number;
     ref?: React.Ref<HTMLSpanElement>;
 };
@@ -97,7 +122,9 @@ declare namespace TextareaAction {
     var displayName: string;
 }
 export type TextareaCopyButtonProps = Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "type" | "children" | "aria-label"> & {
-    /** Text to copy; the field's current value when omitted. */
+    /**
+     * Text to copy instead of the field's current value.
+     */
     value?: string;
     ref?: React.Ref<HTMLButtonElement>;
 };

package/dist/components/thumbnail/Thumbnail.d.ts

@@ -1,31 +1,49 @@
 import * as React from "react";
 import { type ImageSlotFallbackProps, type ImageSlotImageProps } from "../../internal/imageSlot";
-import type { ControlSize, PaletteColor } from "../../internal/states";
+import { type ControlSize, type PaletteColor } from "../../internal/states";
 /** Width ÷ height. `1:1` square · `4:3` / `3:2` photo · `16:9` wide cover · `3:4` portrait. */
 export type ThumbnailRatio = "1:1" | "4:3" | "3:2" | "16:9" | "3:4";
+/** The frame's props; each is described in `api.ts`. */
 export type ThumbnailRootProps = Omit<React.HTMLAttributes<HTMLDivElement>, "color" | "defaultChecked" | "onChange"> & {
-    /** Height tier: 24 · 32 · 40 · 48 · 64; width follows `ratio`. Default `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`.
+     */
     size?: ControlSize;
-    /** Aspect ratio, width ÷ height. Default `1:1`. */
+    /**
+     * Aspect ratio, width ÷ height.
+     */
     ratio?: ThumbnailRatio;
-    /** Fallback fill and icon color (`--prime-color-palette-<hue>-*`). Default `gray`. */
+    /**
+     * Fallback fill and icon hue; a color that means something (category, vehicle color).
+     */
     color?: PaletteColor;
-    /** Fallback fill: `soft` tint with a hue icon, or `solid` hue with a contrasting icon. */
+    /**
+     * Fallback fill: a soft tint with a hue icon, or a solid hue with a contrasting icon.
+     */
     variant?: "soft" | "solid";
-    /** Fills the container width (cards, galleries); the height follows `ratio`. */
+    /**
+     * Fills the container width (cards, galleries); the height follows `ratio`.
+     */
     fullWidth?: boolean;
-    /** A faint inner ring around the frame, for photos with a white background on a light surface. */
+    /**
+     * A faint inner ring, for photos with a white background on a light surface.
+     */
     ring?: boolean;
     /**
-     * Puts the frame on its one child — a `<button>` that opens a viewer, an `<a>` to the object —
-     * which takes the parts as its children: hover lift, press and focus ring come with it.
+     * 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.
      */
     asChild?: boolean;
-    /** Selected (controlled): the tile becomes a checkbox with a check in its corner. */
+    /**
+     * 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`.
+     */
     checked?: boolean;
-    /** Initially selected (uncontrolled); makes the tile selectable. */
+    /**
+     * Initially selected (uncontrolled); makes the tile selectable.
+     */
     defaultChecked?: boolean;
-    /** Selection changed; makes the tile selectable. */
+    /**
+     * Selection changed by click, Space or Enter; makes the tile selectable.
+     */
     onCheckedChange?: (checked: boolean) => void;
     ref?: React.Ref<HTMLDivElement>;
 };
@@ -34,12 +52,14 @@ export type ThumbnailRootProps = Omit<React.HTMLAttributes<HTMLDivElement>, "col
  * With `asChild` it is a link or a button that opens the object; with the checked triad a
  * selectable tile of a media library.
  */
-declare function ThumbnailRoot({ size, ratio, color, variant, fullWidth, ring, asChild, checked: checkedProp, defaultChecked, onCheckedChange, className, children, ref, ...rest }: ThumbnailRootProps): import("react/jsx-runtime").JSX.Element;
+declare function ThumbnailRoot({ size: sizeProp, ratio, color, variant, fullWidth, ring, asChild, checked: checkedProp, defaultChecked, onCheckedChange, className, children, ref, ...rest }: ThumbnailRootProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>;
 declare namespace ThumbnailRoot {
     var displayName: string;
 }
 export type ThumbnailImageProps = ImageSlotImageProps & {
-    /** `cover` (default) crops to fill; `contain` shows the whole image on the fallback fill. */
+    /**
+     * `cover` crops to fill; `contain` shows the whole image on the fallback fill (logos).
+     */
     fit?: "cover" | "contain";
 };
 /** The picture; while it loads or after an error the Fallback shows through. */
@@ -48,19 +68,29 @@ declare namespace ThumbnailImage {
     var displayName: string;
 }
 export type ThumbnailVideoProps = Omit<React.VideoHTMLAttributes<HTMLVideoElement>, "src" | "poster" | "controls" | "autoPlay" | "muted" | "loop" | "children"> & {
+    /**
+     * Video URL. Without a `poster` the first frame is asked for (`#t=0.001` is added when the URL has no fragment).
+     */
     src: string;
-    /** A still to show before playing; without it the first frame is drawn (`preload="metadata"`). */
+    /**
+     * A still shown before playing; with it the video counts as loaded once its metadata is in.
+     */
     poster?: string;
-    /** The native controls: a video message or a clip to watch in place. */
+    /**
+     * Native controls: a video message or a clip to watch in place; no play mark or duration of the kit.
+     */
     controls?: boolean;
     /**
-     * Plays muted, in a loop, inline, with no controls: a GIF-like clip. Off under reduced motion
-     * (the first frame stands still).
+     * 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.
      */
     autoPlay?: boolean;
-    /** `cover` (default) crops to fill; `contain` letterboxes on the fallback fill. */
+    /**
+     * `cover` crops to fill; `contain` letterboxes on the fallback fill.
+     */
     fit?: "cover" | "contain";
-    /** Display of the duration badge. Default `m:ss` (`h:mm:ss` from an hour). */
+    /**
+     * Display of the duration badge.
+     */
     formatDuration?: (seconds: number) => string;
     ref?: React.Ref<HTMLVideoElement>;
 };