prime-ui-kit 0.14.0 → 0.16.0

package/dist/skill/reference/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/dist/skill/reference/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/dist/skill/reference/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/dist/skill/reference/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/dist/skill/reference/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/dist/skill/reference/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;
 }
 

package/dist/skill/reference/components/thumbnail/examples/fit.tsx

@@ -0,0 +1,24 @@
+/** A supplier's wide banner in a square frame: cropped to fill or shown whole on the fill — `fit`. */
+import { Thumbnail, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const BANNER = "https://picsum.photos/seed/supplier-banner/480/160";
+const FITS = ["cover", "contain"] as const;
+
+export default function ThumbnailFitExample() {
+  return (
+    <div className={styles.row}>
+      {FITS.map((fit) => (
+        <div key={fit} className={styles.cell}>
+          <Thumbnail.Root size="xl" color="gray">
+            <Thumbnail.Image src={BANNER} fit={fit} alt="Ферма поставщика «Северное хозяйство»" />
+          </Thumbnail.Root>
+          <Typography as="span" variant="caption" tone="muted">
+            {fit}
+          </Typography>
+        </div>
+      ))}
+    </div>
+  );
+}

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

@@ -1,4 +1,4 @@
-/** No image (an icon or a short label on the fill) and an image that fails and falls back by itself. */
+/** 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`. */
 import { Icon, Thumbnail, Typography } from "prime-ui-kit";
 
 export default function ThumbnailStatesExample() {

package/dist/skill/reference/components/thumbnail/examples/variants.tsx

@@ -1,7 +1,18 @@
 /** The fallback fill: a soft tint or a solid hue, in a color that means something — `variant`, `color`. */
 import { Icon, Thumbnail, Typography } from "prime-ui-kit";
 
-const COLORS = ["gray", "blue", "green", "orange", "red"] as const;
+const COLORS = [
+  "gray",
+  "blue",
+  "green",
+  "orange",
+  "red",
+  "yellow",
+  "purple",
+  "sky",
+  "pink",
+  "teal",
+] as const;
 const VARIANTS = ["soft", "solid"] as const;
 
 export default function ThumbnailVariantsExample() {

package/dist/skill/reference/components/thumbnail/examples/video.tsx

@@ -1,9 +1,12 @@
-/** 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`. */
+/** 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`. */
 import { Icon, Thumbnail, Typography } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
 
 const CLIP = "https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4";
+const POSTER = "https://picsum.photos/seed/safety-briefing/640/360";
+
+const formatSeconds = (seconds: number) => `${Math.round(seconds)} с`;
 
 export default function ThumbnailVideoExample() {
   return (
@@ -19,6 +22,22 @@ export default function ThumbnailVideoExample() {
           Обход склада · без обложки
         </Typography>
       </div>
+      <div className={styles.cardContent}>
+        <Thumbnail.Root fullWidth ratio="16:9">
+          <Thumbnail.Video
+            src={CLIP}
+            poster={POSTER}
+            formatDuration={formatSeconds}
+            aria-label="Инструктаж по технике безопасности"
+          />
+          <Thumbnail.Fallback>
+            <Icon name="action.play" />
+          </Thumbnail.Fallback>
+        </Thumbnail.Root>
+        <Typography variant="caption" tone="muted">
+          Инструктаж · обложка, длительность в секундах
+        </Typography>
+      </div>
       <div className={styles.cardContent}>
         <Thumbnail.Root fullWidth ratio="16:9">
           <Thumbnail.Video src={CLIP} autoPlay aria-label="Как собрать заказ, ролик" />

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

@@ -23,16 +23,15 @@ import { Timeline } from "prime-ui-kit";
 
 ## Anatomy
 ```
-Timeline.Root                    size container, sets the tier
-└─ Timeline.Group label          labelled <ol>; the line runs from its first dot to its last
+Timeline.Root                    size container, sets the tier (size, else the host tier)
+└─ Timeline.Group label          labelled <ol role="list">; the line runs from its first dot to its last
    ├─ Timeline.Item              <li> + row (div | button | a | asChild element) with the dot
-   │  ├─ Timeline.Title          first line
-   │  ├─ Timeline.Meta           second line (date)
-   │  │  └─ Timeline.MetaPrimary emphasized part
-   │  └─ Timeline.Value          trailing amount
-   │     └─ Timeline.ValueMeta   second line under the amount
+   │  ├─ Timeline.ItemTitle      first line
+   │  ├─ Timeline.ItemMeta       second line (date); <strong> emphasizes a part
+   │  └─ Timeline.ItemValue      trailing amount
+   │     └─ Timeline.ItemMeta    second line under the amount
    └─ Timeline.Gap               <li>: interval between events (dashed segment, hollow dot)
-      └─ Timeline.GapMeta        caption on the right («сейчас»)
+      └─ Timeline.Description    caption on the right («сейчас»)
 ```
 
 ## API
@@ -44,8 +43,10 @@ Timeline.Root                    size container, sets the tier
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Text, dot and row rhythm: rows 40 · 52 · 64 · 68 · 76 px. |
-| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children">` | — | `children` (`Timeline.Group`), `className` and the other div attributes. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | host tier, else `"m"` | Text, dot and row rhythm: rows 40 · 52 · 64 · 68 · 76 px, dot column → text 8 · 12 · 16 · 16 · 20 px. Without it the tier of its host, else `m`. |
+| `children` | `ReactNode` | — (required) | The `Timeline.Group`s. |
+| `className` | `string` | — | Class on the element. |
+| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children">` | — | The other div attributes. |
 
 ### Timeline.Group
 `ref` → `HTMLOListElement`. A labelled `<ol>` of events; the line runs from its first dot to its last.
@@ -53,10 +54,12 @@ Timeline.Root                    size container, sets the tier
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `label` | `ReactNode` | — | Group heading («Недавно»); names the list via `aria-labelledby`. |
-| `…rest` | `Omit<OlHTMLAttributes<HTMLOListElement>, "children">` | — | `children` (`Timeline.Item`, `Timeline.Gap`), `className` and the other ol attributes. |
+| `children` | `ReactNode` | — (required) | `Timeline.Item` and `Timeline.Gap` rows. |
+| `className` | `string` | — | Class on the element. |
+| `…rest` | `Omit<OlHTMLAttributes<HTMLOListElement>, "children">` | — | The other ol attributes. |
 
 ### Timeline.Item
-`ref` → the row element. An `<li>` with a row: `<div>`, `<button>` (`onClick`), `<a>` (`href`) or your element (`asChild`); the dot is prepended. The row under the pointer or keyboard focus is highlighted (pill, accent title and dot).
+`ref` → the row element. An `<li>` with a row: `<div>`, `<button>` (`onClick`), `<a>` (`href`) or your element (`asChild`); the dot is prepended. The row under the pointer or keyboard focus is highlighted (pill, accent title and dot); an interactive row gives under the press.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -65,22 +68,28 @@ Timeline.Root                    size container, sets the tier
 | `onClick` | `MouseEventHandler<HTMLElement>` | — | Renders the row as a `<button>`. |
 | `href` | `string` | — | Renders the row as a link (with `target`, `rel`, `download`). |
 | `asChild` | `boolean` | `false` | Renders the row as the single child element (a router link). |
-| `…rest` | `Omit<HTMLAttributes<HTMLElement>, "children" \| "color" \| "onClick">` | — | `children` (Title, Meta, Value), `className` and the other row attributes. |
+| `children` | `ReactNode` | — (required) | `Timeline.ItemTitle`, `Timeline.ItemMeta`, `Timeline.ItemValue`. |
+| `className` | `string` | — | Class on the element. |
+| `…rest` | `Omit<HTMLAttributes<HTMLElement>, "children" \| "color" \| "onClick">` | — | The other row attributes (`target`, `rel`, `download` with `href`). |
 
-### Timeline.Title · Timeline.Meta · Timeline.MetaPrimary
-`ref` → `HTMLSpanElement`. `<span>` lines: the event (medium, accent on the highlighted row, wraps), the muted date line with tabular numbers, and its emphasized part.
+### Timeline.ItemTitle · Timeline.ItemMeta
+`ref` → `HTMLSpanElement`. `<span>` lines: the event (medium, accent on the highlighted row, wraps) and the muted secondary line with tabular numbers — under the title the date (emphasize a part with `<strong>`), inside `Timeline.ItemValue` the value's second line.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `…rest` | `HTMLAttributes<HTMLSpanElement>` | — | `children`, `className` and the other span attributes. |
+| `children` | `ReactNode` | — (required) | The text of the line. |
+| `className` | `string` | — | Class on the element. |
+| `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | The other span attributes. |
 
-### Timeline.Value · Timeline.ValueMeta
-`ref` → `HTMLSpanElement`. `<span>`: the trailing amount (right-aligned, tabular) and a muted second line under it. Moves under the meta below 20rem.
+### Timeline.ItemValue
+`ref` → `HTMLSpanElement`. A `<span>` with the trailing amount (right-aligned, tabular), a `Timeline.ItemMeta` inside under it. Moves under the meta below 20rem.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `tone` | `"neutral" \| "accent" \| "success" \| "warning" \| "danger" \| "info"` | `"neutral"` | Value: text color (income `success`, refund `danger`). |
-| `…rest` | `HTMLAttributes<HTMLSpanElement>` | — | `children`, `className` and the other span attributes. |
+| `tone` | `"neutral" \| "accent" \| "success" \| "warning" \| "danger" \| "info"` | `"neutral"` | Text color (income `success`, refund `danger`). |
+| `children` | `ReactNode` | — (required) | The amount. |
+| `className` | `string` | — | Class on the element. |
+| `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | The other span attributes. |
 
 ### Timeline.Gap
 `ref` → `HTMLDivElement`. An `<li>` interval between events: a shorter row with a hollow dot on a dashed segment and a muted caption.
@@ -88,10 +97,12 @@ Timeline.Root                    size container, sets the tier
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `tone` | `"neutral" \| "accent" \| "success" \| "warning" \| "danger" \| "info"` | `"neutral"` | Caption and dot color; `warning` / `danger` flag a long interval. |
-| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children">` | — | `children` (the interval caption and an optional `Timeline.GapMeta`), `className` and the other div attributes. |
+| `children` | `ReactNode` | — (required) | The interval caption and an optional `Timeline.Description`. |
+| `className` | `string` | — | Class on the element. |
+| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children">` | — | The other div attributes. |
 
-### Timeline.GapMeta
-`ref` → `HTMLSpanElement`. A caption on the right of the gap («сейчас»), in the gap tone.
+### Timeline.Description
+`ref` → `HTMLSpanElement`. The secondary caption of a gap, at its end («сейчас»), in the gap tone.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -102,10 +113,10 @@ Timeline.Root                    size container, sets the tier
 ### size
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| `xs` | rows 40, title 12/16, dot 8 | very dense side panels | |
-| `s` | rows 52, title 13/20 | side panels, drawers | |
-| `m` | rows 64, title 14/20, dot 10 | page content and cards | yes |
-| `l` · `xl` | rows 68 / 76, title 16/24, dot 12 | spacious feeds, detail pages | |
+| `xs` | rows 40, title 12/16, dot 8, dot column → text 8 | very dense side panels | |
+| `s` | rows 52, title 13/20, dot column → text 12 | side panels, drawers | |
+| `m` | rows 64, title 14/20, dot 10, dot column → text 16 | page content and cards | yes |
+| `l` · `xl` | rows 68 / 76, title 16/24, dot 12, dot column → text 16 / 20 | spacious feeds, detail pages | |
 
 ### color (Item)
 | Value | Looks like | Use when | Default |
@@ -113,10 +124,10 @@ Timeline.Root                    size container, sets the tier
 | `blue` | blue dot at reduced emphasis | default category | yes |
 | `gray` · `green` · `orange` · `red` · `yellow` · `purple` · `sky` · `pink` · `teal` | dot in the hue | categories | |
 
-### tone (Item · Value · Gap)
+### tone (Item · ItemValue · Gap)
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| `neutral` | muted dot / primary value / muted gap caption | a status without meaning | Value, Gap |
+| `neutral` | muted dot / primary value / muted gap caption | a status without meaning | ItemValue, Gap |
 | `accent` | accent | a pending action | |
 | `success` | success | paid, income | |
 | `warning` | warning | overdue, a too-long interval | |
@@ -131,26 +142,31 @@ On an Item `tone` wins over `color` and shows at full emphasis.
 | tier | `size` | `data-size` on the root |
 | highlighted | pointer over the row, keyboard focus | `:hover`, `:focus-visible`: `fill-subtle-active` pill, accent title and dot (a `tone` keeps its dot) |
 | dot color | `color` / `tone` | `data-color` (without a tone) or `data-tone` |
-| interactive | `onClick`, `href`, `asChild` | `data-interactive`; pointer cursor, inset focus ring |
+| interactive | `onClick`, `href`, `asChild` | `data-interactive`; pointer cursor, inset focus ring, the touch row height (`touchTargetRowClass`) |
+| pressed | pointer or key down on an interactive row | the row gives (`press`: scale over `fast`), back on release |
 
 Timeline keeps no state and has no persistent selection: every row is highlighted only while it is under the pointer or focused.
 
 ## Layout & spacing
 - The root is a size container: give it a definite width (`width: min(100%, 30rem)`).
-- Row grid: dot column · text · value; below 20rem of root width the value moves under the meta line.
+- Row grid: dot column · text · value; the dot column and the text stand 8 · 12 · 16 · 16 · 20 apart by tier (`--tl-gap`); below 20rem of root width the value moves under the meta line.
 - Rows touch so the line is continuous; group → group `--prime-space-4`.
 - Inside a Card put it in `Card.Body`; the card owns the padding.
 
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 | Key | Action |
 |---|---|
 | `Tab` | Interactive rows are one Tab stop each; the focus ring is drawn inside the row. |
 | `Enter` · `Space` | Activates a button row; Enter opens a link row. |
 
 ### ARIA
-- Each group is an `<ol>` labelled by its heading (`aria-labelledby`); events are `<li>`.
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+- Each group is an `<ol role="list">` labelled by its heading (`aria-labelledby`); events are `<li>`. The role keeps the list semantics that WebKit drops under `list-style: none`.
 - The dot is `aria-hidden`: put the status into the title or meta, not only the dot color.
 
 ### Labels
@@ -161,12 +177,12 @@ No `labels`.
 ## Examples
 | Example | Shows |
 |---|---|
-| [overview.tsx](examples/overview.tsx) | An operations feed: one labelled group, a line through the dots, the row under the pointer highlighted — `Timeline.Group`, `Timeline.Value`. |
+| [overview.tsx](examples/overview.tsx) | An operations feed: one labelled group, a line through the dots, the row under the pointer highlighted — `Timeline.Group`, `Timeline.ItemValue`. |
 | [variants.tsx](examples/variants.tsx) | Dot hues for categories at reduced emphasis, and status tones on items, values and gaps at full emphasis — `color`, `tone`. |
 | [sizes.tsx](examples/sizes.tsx) | Every tier scales text, dot and row rhythm, rows 40 to 76 px — `size`. |
-| [structure.tsx](examples/structure.tsx) | A service history with intervals between events, a caption on the right of a gap and a second value line — `Timeline.Gap`, `Timeline.GapMeta`, `Timeline.ValueMeta`. |
-| [links.tsx](examples/links.tsx) | Rows that open an operation page become links, one Tab stop each with a focus ring — `href`. |
-| [narrow.tsx](examples/narrow.tsx) | At 375 px the title wraps and the amount stays right; below 20rem of its own width the amount moves under the meta line. |
+| [structure.tsx](examples/structure.tsx) | A service history with intervals between events, a caption on the right of a gap and a second value line — `Timeline.Gap`, `Timeline.Description`, `Timeline.ItemMeta`. |
+| [links.tsx](examples/links.tsx) | Rows that open something: an operation page by a link or by your router link through the slot, a receipt in place by a button; one Tab stop each with a focus ring — `href`, `asChild`, `onClick`. |
+| [narrow.tsx](examples/narrow.tsx) | At 375 px the title wraps and the amount stays right; below 20rem of its own width the amount moves under the meta line — `Timeline.ItemValue`. |
 
 ## Mistakes
 - `Timeline.Item` outside `Timeline.Group` → items are `<li>`; always wrap them in a group.