prime-ui-kit 0.15.0 → 0.16.0

package/dist/skill/reference/components/file-upload/examples/row-parts.tsx

@@ -8,7 +8,7 @@ export default function FileUploadRowPartsExample() {
     <div className={styles.column}>
       <FileUpload.Item>
         <FileUpload.FormatBadge format="pdf" color="red" />
-        <FileUpload.ItemName>Счёт № 318.pdf</FileUpload.ItemName>
+        <FileUpload.ItemText>Счёт № 318.pdf</FileUpload.ItemText>
         <FileUpload.ItemDescription>1,2 МБ · выставлен 12 марта</FileUpload.ItemDescription>
         <FileUpload.ItemActions>
           <Button.Root variant="ghost" tone="neutral" aria-label="Скачать Счёт № 318.pdf">
@@ -20,7 +20,7 @@ export default function FileUploadRowPartsExample() {
       </FileUpload.Item>
       <FileUpload.Item>
         <FileUpload.ItemPreview src="https://picsum.photos/seed/warehouse-gate/160/160" />
-        <FileUpload.ItemName>Отгрузка, паллет 4.jpg</FileUpload.ItemName>
+        <FileUpload.ItemText>Отгрузка, паллет 4.jpg</FileUpload.ItemText>
         <FileUpload.ItemDescription>820 КБ · снято при отгрузке</FileUpload.ItemDescription>
         <FileUpload.ItemActions>
           <Button.Root variant="ghost" tone="neutral" aria-label="Скачать Отгрузка, паллет 4.jpg">
@@ -32,13 +32,13 @@ export default function FileUploadRowPartsExample() {
       </FileUpload.Item>
       <FileUpload.Item>
         <FileUpload.FormatBadge format="xlsx" color="green" />
-        <FileUpload.ItemName>Отчёт по заказу.xlsx</FileUpload.ItemName>
+        <FileUpload.ItemText>Отчёт по заказу.xlsx</FileUpload.ItemText>
         <FileUpload.ItemDescription>Формируется · 60%</FileUpload.ItemDescription>
         <FileUpload.ItemProgress value={60} aria-label="Формируется: Отчёт по заказу.xlsx" />
       </FileUpload.Item>
       <FileUpload.Item invalid>
         <FileUpload.FormatBadge format="pdf" color="red" />
-        <FileUpload.ItemName>Акт сверки за март.pdf</FileUpload.ItemName>
+        <FileUpload.ItemText>Акт сверки за март.pdf</FileUpload.ItemText>
         <FileUpload.ItemDescription>
           Не удалось сформировать: нет данных за 31 марта
         </FileUpload.ItemDescription>

package/dist/skill/reference/components/file-upload/examples/screen.module.css

@@ -7,14 +7,14 @@
   gap: var(--prime-space-2);
 }
 
-/* As many ~8rem tiles as fit: two across from 320px, more as the panel grows. */
+/* As many ~8rem tiles as fit: two across from 320px, more as the panel grows. A tile is a grid,
+   not a list item, so it draws no marker. */
 .grid {
   display: grid;
   grid-template-columns: repeat(auto-fill, minmax(min(100%, calc(var(--prime-space-16) * 2)), 1fr));
   gap: var(--prime-space-5) var(--prime-space-4);
   margin: 0;
   padding: 0;
-  list-style: none;
 }
 
 /* A tile: the picture, then the name over the size and date. */

package/dist/skill/reference/components/file-upload/examples/screen.tsx

@@ -6,6 +6,8 @@ import {
   Crossfade,
   EmptyPage,
   FileUpload,
+  type FileUploadPicker,
+  formatDateValue,
   formatFileSize,
   Icon,
   MediaViewer,
@@ -201,7 +203,7 @@ const filesWord = (count: number) => {
   return "файлов";
 };
 
-const today = () => new Date().toISOString().slice(0, 10);
+const today = () => formatDateValue(new Date());
 
 /** Upload attempts per file, and how many files have started: the stand-in drops every third one once. */
 const attempts = new WeakMap<File, number>();
@@ -267,7 +269,7 @@ export default function FileUploadScreenExample() {
   const [index, setIndex] = React.useState(0);
 
   const queue = useUploadQueue({ upload: sendFile, concurrency: 2 });
-  const inputRef = React.useRef<HTMLInputElement>(null);
+  const picker = React.useRef<FileUploadPicker>(null);
   const tiles = React.useRef(new Map<string, HTMLElement>());
   const moving = React.useRef(new Set<string>());
 
@@ -419,7 +421,7 @@ export default function FileUploadScreenExample() {
                 </Select.Root>
               </PageToolbar.View>
               <PageToolbar.Actions>
-                <Button.Root onClick={() => inputRef.current?.click()}>
+                <Button.Root onClick={() => picker.current?.open()}>
                   <Button.Icon>
                     <Icon name="action.upload" />
                   </Button.Icon>
@@ -442,7 +444,7 @@ export default function FileUploadScreenExample() {
             accept="image/*,video/*"
             multiple
             queue={queue}
-            inputRef={inputRef}
+            picker={picker}
           />
 
           <PageContent.Section

package/dist/skill/reference/components/file-upload/examples/sizes.tsx

@@ -1,8 +1,6 @@
 /** Every tier of the zone and of its file rows: padding, icon, button, text and the format badge follow it — `size`. */
 import { FileUpload, type FileUploadFile } from "prime-ui-kit";
 
-import styles from "./examples.module.css";
-
 const SIZES = ["xs", "s", "m", "l", "xl"] as const;
 
 const CONTRACT: readonly FileUploadFile[] = [
@@ -11,7 +9,7 @@ const CONTRACT: readonly FileUploadFile[] = [
 
 export default function FileUploadSizesExample() {
   return (
-    <div className={styles.column}>
+    <div>
       {SIZES.map((size) => (
         <FileUpload.Root
           key={size}

package/dist/skill/reference/components/file-upload/examples/states.tsx

@@ -1,8 +1,6 @@
 /** A default zone, a disabled one whose files are read-only and an invalid one without a message — `disabled`, `invalid`. */
 import { FileUpload, type FileUploadFile } from "prime-ui-kit";
 
-import styles from "./examples.module.css";
-
 /** The zone names the formats the order takes. */
 const ZONE_LABELS = { description: "PDF или PNG до 20 МБ" };
 
@@ -12,7 +10,7 @@ const ACT: readonly FileUploadFile[] = [
 
 export default function FileUploadStatesExample() {
   return (
-    <div className={styles.column}>
+    <div>
       <FileUpload.Root label="default" labels={ZONE_LABELS} />
       <FileUpload.Root
         label="disabled"

package/dist/skill/reference/components/file-upload/examples/variants.tsx

@@ -1,15 +1,21 @@
 /** How files are added: the dashed drop zone, the zone with only its fill for cards and modals, the compact picker button and the add tile that starts an empty set of tiles — `variant`, `trigger`. */
 import { FileUpload } from "prime-ui-kit";
 
-import styles from "./examples.module.css";
-
 export default function FileUploadVariantsExample() {
   return (
-    <div className={styles.column}>
-      <FileUpload.Root label="dashed" variant="dashed" />
-      <FileUpload.Root label="solid" variant="solid" />
-      <FileUpload.Root label="button" trigger="button" />
-      <FileUpload.Root label="tile" trigger="tile" layout="grid" multiple />
+    <div>
+      <div>
+        <FileUpload.Root label="dashed" variant="dashed" />
+      </div>
+      <div>
+        <FileUpload.Root label="solid" variant="solid" />
+      </div>
+      <div>
+        <FileUpload.Root label="button" trigger="button" />
+      </div>
+      <div>
+        <FileUpload.Root label="tile" trigger="tile" layout="grid" multiple />
+      </div>
     </div>
   );
 }

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

@@ -23,7 +23,7 @@ import { Gallery, type GalleryItem } from "prime-ui-kit";
 
 ## Anatomy
 ```
-Gallery                      <div>, aspect-ratio from the layout; data-count, data-pressed while a tile is pressed
+Gallery                      <div>, aspect-ratio from the layout; data-count, data-max-size with `maxSize`
 ├─ tile × 1–10               a box at fractions of the gallery, inset by half a gap at inner edges
 │  ├─ Thumbnail              the picture (lazy, async decode) or a video's first frame (near the view)
 │  ├─ play mark · length     the media disk and a pill over a video tile (aria-hidden)
@@ -46,6 +46,7 @@ An item (`GalleryItem`) is `type` (`"image"` by default, or `"video"`), `src`, a
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `items` | `GalleryItem[]` | — (required) | `{ type?, src, poster?, alt?, width?, height?, duration?, transfer?, transferProgress?, transferDirection? }`; `width` / `height` give the ratio (default 4 : 3). The first 10 are shown. |
+| `maxSize` | `string` | — | Caps the width at this CSS length instead of the host's width (`85cqi` of a chat row); the gallery then draws no radius — the host shapes and clips it. |
 | `viewer` | `boolean` | `true` | A tile (a press, Enter or Space) opens the album in the kit's `MediaViewer` at that item. `false` — no viewer of the kit: open your own from `onOpenChange` and `onIndexChange`. |
 | `open` | `boolean` | — | The viewer is open (controlled). |
 | `defaultOpen` | `boolean` | `false` | Initially open (uncontrolled). |
@@ -56,7 +57,7 @@ An item (`GalleryItem`) is `type` (`"image"` by default, or `"video"`), `src`, a
 | `onCancel` | `(index: number) => void \| Promise<void>` | — | Cancel the transfer in flight: the disk's cross. A returned promise keeps the disk pending (a spinner, `aria-busy`, no second press); a rejection leaves the transfer as it was and announces `cancelFailed`. |
 | `onRetry` | `(index: number) => void \| Promise<void>` | — | Transfer it again after a failure: the danger disk's retry; a promise works the same (`retryFailed` on a rejection). |
 | `onDownload` | `(index: number) => void \| Promise<void>` | — | Fetch a `remote` content: the download arrow; set `transfer` to `loading` with `transferDirection="download"` as it starts. A promise works the same (`downloadFailed` on a rejection). |
-| `labels` | `Partial<GalleryLabels>` | — | System strings, see Labels. |
+| `labels` | `Partial<GalleryLabels>` | — | Built-in strings, see Labels. |
 | `children` | `ReactNode` | — | Laid over the gallery, above every tile (a caption pill, a message's time). |
 | `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `className` and the other attributes. |
 
@@ -82,7 +83,9 @@ Decided by the items, not a prop: the number of items and their ratios.
 |---|---|---|
 | loading | an image that has not loaded | the Thumbnail's own placeholder in the tile's final box; nothing moves when it loads |
 | video near the view | a video tile entering the view | the `<video preload="metadata">` mounts and shows its first frame; the length comes from the item's `duration` first, then from the metadata |
-| pressed | a press on a tile (pointer, or Enter / Space held) | the whole album gives in a little (`data-pressed` on the root, `--prime-motion-press-scale`, `fast`); inside a message the bubble presses instead |
+| pressed | a press on a tile (pointer, or Enter / Space held) | the whole album gives in a little (`:active` on the root, `--prime-motion-press-scale`, `fast`); inside a message the bubble presses instead |
+| on its way | an item's `transfer` before `done` | the picture dims under the transfer disk; a video's play mark fades out of the middle and back once the transfer is done |
+| open | `open` · `defaultOpen` · a tile | `MediaViewer` shows the album at `index`, flying out of the tile and back into it on close |
 | transferring | `transfer` `queued` / `loading` on an item | the picture dims to 0.6 under the shared transfer disk with its progress ring (an indeterminate arc while `transferProgress` is left out; `transferDirection` changes only the words); pressing the disk cancels; the play mark gives way (`fast`) |
 | failed | `transfer="failed"` | the disk turns danger with a retry arrow, described by the reason |
 | remote | `transfer="remote"` | the download arrow on the disk; the picture dims under it |
@@ -92,18 +95,22 @@ Decided by the items, not a prop: the number of items and their ratios.
 ## Layout & spacing
 - The gallery is as wide as its host allows, up to `--prime-gallery-max-size` (22.5rem); a lone portrait is narrower, its height reaching the cap. Its height is its width over the layout's ratio.
 - Tiles are `--prime-gallery-gap` (2px) apart; the gaps are the gallery's own background, transparent by default (a host may paint it: a message paints the incoming surface).
-- The outer corners are rounded (`--prime-radius-l`); a host that clips it itself (a message) sets the radius to 0 through `className`.
-- From 320px up the album keeps its layout: tiles scale with the gallery, never rearrange.
+- The outer corners are rounded (`--prime-radius-l`). A host that shapes and clips it itself (a message) passes `maxSize`: the gallery takes that length as its cap instead of its host's width and draws no radius of its own.
+- At any width the album keeps its layout: tiles scale with the gallery, never rearrange.
 
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 | Key | Action |
 |---|---|
 | `Tab` | Moves through the tiles that open the viewer and the transfer disks |
 | `Enter` · `Space` | Opens the album in the viewer at this tile, or presses a transfer disk; in the viewer `←` `→` page and `Escape` closes, the focus returning to the tile |
 
 ### ARIA
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 - A tile is a button «Открыть: {alt}» (`labels.open`; without `alt` — «фото» or «видео») with `aria-haspopup="dialog"`; its picture is then decorative. The viewer is MediaViewer's dialog with its own names; on close the focus returns to the tile.
 - With `viewer={false}` and no open handlers a picture is an image with its own `alt`; the play mark and the length of a video are `aria-hidden`.
 - A transfer disk is the cancel, retry or download button; the share is its accessible description («Отправка 42%»), the reason of a failure the retry's description; a refused cancel, retry or download is announced politely.
@@ -132,8 +139,10 @@ Decided by the items, not a prop: the number of items and their ratios.
 ## Examples
 | Example | Shows |
 |---|---|
-| [overview.tsx](examples/overview.tsx) | One album of mixed photos and a video, re-laid out for every count from one to ten: the switcher picks how many items the gallery holds, the layout cross-fades into the next, and a tile opens the album in the viewer — `items`, `width`, `height`, `type`. |
+| [overview.tsx](examples/overview.tsx) | An album of photos of different shapes and a video, laid out by their ratios before anything loads; a tile opens the album in the viewer — `items`, `width`, `height`, `type`. |
+| [album-sizes.tsx](examples/album-sizes.tsx) | One album re-laid out for every count from one to ten: the switcher picks how many items the gallery holds and the layout cross-fades into the next — `items`. |
 | [transfer.tsx](examples/transfer.tsx) | Items on their way, one look both ways: an upload with its ring and cancel, a failed one with a retry, a received one waiting to be fetched — the picture dims under the disk until it is done — `transfer`, `transferProgress`, `transferDirection`, `onCancel`, `onRetry`, `onDownload`. |
+| [controlled.tsx](examples/controlled.tsx) | The album with a viewer of the screen's own: a tile reports its item, and the inspection card beside it shows which photo is open — `viewer`, `index`, `onIndexChange`. |
 | [controlled-open.tsx](examples/controlled-open.tsx) | The viewer owned by the screen: a button opens the album at its third item, the page the viewer shows is kept, and closing returns the focus to where it came from — `open`, `onOpenChange`, `index`, `onIndexChange`. |
 
 ## Mistakes
@@ -147,5 +156,5 @@ Decided by the items, not a prop: the number of items and their ratios.
 - More than ten items in one gallery → items after the tenth are not shown; split them into several albums of up to ten.
 
 ## Related
-- **Built from:** [Thumbnail](../thumbnail/COMPONENT.md) (`Thumbnail.Image`, `Thumbnail.Video`), [MediaViewer](../media-viewer/COMPONENT.md) (the album full-screen), [Button](../button/COMPONENT.md) (the transfer disk), Icon (`action.play`, `action.video`, `object.image`); `internal/transferDisk` (the transfer of a tile), `internal/mediaDisk` (the play mark), `internal/mediaPill` (the length), `internal/useNearView` (a video mounts near the view), `internal/formatClock`, `internal/messagePart` (the press goes to the message)
+- **Built from:** [Thumbnail](../thumbnail/COMPONENT.md) (`Thumbnail.Image`, `Thumbnail.Video`), [MediaViewer](../media-viewer/COMPONENT.md) (the album full-screen), [Button](../button/COMPONENT.md) (the transfer disk), [Spinner](../spinner/COMPONENT.md) (a pending transfer disk), Icon (`action.play`, `action.video`, `object.image`); `internal/transferDisk` (the transfer of a tile), `internal/mediaDisk` (the play mark), `internal/mediaPill` (the length), `internal/useNearView` (a video mounts near the view), `internal/press` (the album's press), `internal/formatClock`, `internal/messagePart` (the press goes to the message), [VisuallyHidden](../visually-hidden/COMPONENT.md)
 - **See also:** [Message](../message/COMPONENT.md) — `Message.Media` is a Gallery in a message; [MediaViewer](../media-viewer/COMPONENT.md) — the viewer on its own; [Thumbnail](../thumbnail/COMPONENT.md), [FileUpload](../file-upload/COMPONENT.md), [VideoNote](../video-note/COMPONENT.md)

package/dist/skill/reference/components/gallery/examples/album-sizes.tsx

@@ -0,0 +1,52 @@
+/** One album re-laid out for every count from one to ten: the switcher picks how many items the gallery holds and the layout cross-fades into the next — `items`. */
+import { Crossfade, Gallery, type GalleryItem, SegmentedControl } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const CLIP = "https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4";
+
+const photo = (seed: string, width: number, height: number, alt: string): GalleryItem => ({
+  src: `https://picsum.photos/seed/${seed}/${width}/${height}`,
+  width,
+  height,
+  alt,
+});
+
+const ITEMS: GalleryItem[] = [
+  photo("rack-a", 600, 800, "Стеллаж А"),
+  photo("dock", 1200, 800, "Рампа"),
+  { type: "video", src: CLIP, width: 1280, height: 720, duration: 6, alt: "Проезд к рампе" },
+  photo("pallet", 800, 800, "Паллета 1"),
+  photo("yard", 1600, 900, "Двор склада"),
+  photo("rack-b", 600, 900, "Стеллаж Б"),
+  photo("gate", 800, 600, "Ворота 2"),
+  photo("seal", 800, 800, "Пломба"),
+  photo("rack-c", 600, 800, "Стеллаж В"),
+  photo("bay", 1200, 800, "Зона погрузки"),
+];
+
+const COUNTS = ["1", "2", "3", "4", "5", "6", "7", "8", "9", "10"];
+
+export default function GalleryAlbumSizesExample() {
+  const [count, setCount] = React.useState("3");
+  return (
+    <div className={styles.stage}>
+      <SegmentedControl.Root
+        value={count}
+        onValueChange={setCount}
+        aria-label="Фото в альбоме"
+        className={styles.fit}
+      >
+        {COUNTS.map((value) => (
+          <SegmentedControl.Item key={value} value={value}>
+            {value}
+          </SegmentedControl.Item>
+        ))}
+      </SegmentedControl.Root>
+      <Crossfade state={count} className={styles.fit}>
+        <Gallery items={ITEMS.slice(0, Number(count))} />
+      </Crossfade>
+    </div>
+  );
+}

package/dist/skill/reference/components/gallery/examples/controlled.tsx

@@ -0,0 +1,40 @@
+/** The album with a viewer of the screen's own: a tile reports its item, and the inspection card beside it shows which photo is open — `viewer`, `index`, `onIndexChange`. */
+import { Card, Gallery, type GalleryItem, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+const INSPECTION: GalleryItem[] = [
+  {
+    src: "https://picsum.photos/seed/pallet-front/800/600",
+    width: 800,
+    height: 600,
+    alt: "Паллета, фронт",
+  },
+  {
+    src: "https://picsum.photos/seed/pallet-side/800/600",
+    width: 800,
+    height: 600,
+    alt: "Паллета, бок",
+  },
+  {
+    src: "https://picsum.photos/seed/pallet-label/600/800",
+    width: 600,
+    height: 800,
+    alt: "Этикетка",
+  },
+];
+
+export default function GalleryControlledExample() {
+  const [index, setIndex] = React.useState(0);
+  return (
+    <>
+      <Gallery items={INSPECTION} viewer={false} index={index} onIndexChange={setIndex} />
+      <Card.Root>
+        <Card.Body>
+          <Typography as="span" variant="body-s" aria-live="polite">
+            Открыто в карточке приёмки: {INSPECTION[index]?.alt}
+          </Typography>
+        </Card.Body>
+      </Card.Root>
+    </>
+  );
+}

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

@@ -1,4 +1,4 @@
-/* overview.tsx: the switcher above the gallery it re-lays out, one column. */
+/* album-sizes.tsx: the switcher above the gallery it re-lays out, one column. */
 .stage {
   display: flex;
   flex-direction: column;

package/dist/skill/reference/components/gallery/examples/overview.tsx

@@ -1,52 +1,24 @@
-/** One album of mixed photos and a video, re-laid out for every count from one to ten: the switcher picks how many items the gallery holds, the layout cross-fades into the next, and a tile opens the album in the viewer — `items`, `width`, `height`, `type`. */
-import { Crossfade, Gallery, type GalleryItem, SegmentedControl } from "prime-ui-kit";
-import * as React from "react";
-
-import styles from "./examples.module.css";
+/** An album of photos of different shapes and a video, laid out by their ratios before anything loads; a tile opens the album in the viewer — `items`, `width`, `height`, `type`. */
+import { Gallery, type GalleryItem } from "prime-ui-kit";
 
 const CLIP = "https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4";
 
-const photo = (seed: string, width: number, height: number, alt: string): GalleryItem => ({
-  src: `https://picsum.photos/seed/${seed}/${width}/${height}`,
-  width,
-  height,
-  alt,
-});
-
 const ITEMS: GalleryItem[] = [
-  photo("rack-a", 600, 800, "Стеллаж А"),
-  photo("dock", 1200, 800, "Рампа"),
+  {
+    src: "https://picsum.photos/seed/rack-a/600/800",
+    width: 600,
+    height: 800,
+    alt: "Стеллаж А",
+  },
+  {
+    src: "https://picsum.photos/seed/dock/1200/800",
+    width: 1200,
+    height: 800,
+    alt: "Рампа",
+  },
   { type: "video", src: CLIP, width: 1280, height: 720, duration: 6, alt: "Проезд к рампе" },
-  photo("pallet", 800, 800, "Паллета 1"),
-  photo("yard", 1600, 900, "Двор склада"),
-  photo("rack-b", 600, 900, "Стеллаж Б"),
-  photo("gate", 800, 600, "Ворота 2"),
-  photo("seal", 800, 800, "Пломба"),
-  photo("rack-c", 600, 800, "Стеллаж В"),
-  photo("bay", 1200, 800, "Зона погрузки"),
 ];
 
-const COUNTS = ["1", "2", "3", "4", "5", "6", "7", "8", "9", "10"];
-
 export default function GalleryOverviewExample() {
-  const [count, setCount] = React.useState("3");
-  return (
-    <div className={styles.stage}>
-      <SegmentedControl.Root
-        value={count}
-        onValueChange={setCount}
-        aria-label="Фото в альбоме"
-        className={styles.fit}
-      >
-        {COUNTS.map((value) => (
-          <SegmentedControl.Item key={value} value={value}>
-            {value}
-          </SegmentedControl.Item>
-        ))}
-      </SegmentedControl.Root>
-      <Crossfade state={count} className={styles.fit}>
-        <Gallery items={ITEMS.slice(0, Number(count))} />
-      </Crossfade>
-    </div>
-  );
+  return <Gallery items={ITEMS} />;
 }

package/dist/skill/reference/components/gallery/examples/transfer.tsx

@@ -10,36 +10,45 @@ const photo = (seed: string, alt: string): GalleryItem => ({
 });
 
 const START: GalleryItem[] = [
-  { ...photo("waybill", "Накладная"), transfer: "loading", transferProgress: 0.35 },
+  { ...photo("waybill", "Накладная"), transfer: "loading", transferProgress: 0.25 },
   { ...photo("damage", "Повреждённая коробка"), transfer: "failed" },
   { ...photo("seal", "Пломба"), transfer: "remote", transferDirection: "download" },
 ];
 
-const STEP_MS = 400;
+/** A stand-in transfer moves a quarter per step. */
+const STEP_MS = 800;
+const STEP = 0.25;
+
+/** One step of every item in flight; a full one is done. */
+const advance = (item: GalleryItem): GalleryItem => {
+  if (item.transfer !== "loading") return item;
+  const share = Math.min(1, (item.transferProgress ?? 0) + STEP);
+  return { ...item, transferProgress: share, transfer: share >= 1 ? "done" : "loading" };
+};
 
 export default function GalleryTransferExample() {
   const [items, setItems] = React.useState(START);
+  const inFlight = items.some((item) => item.transfer === "loading");
+
+  // One clock for every transfer: a cancel takes its item out of `loading`, and the step skips it.
+  React.useEffect(() => {
+    if (!inFlight) return;
+    const timer = window.setInterval(() => setItems((current) => current.map(advance)), STEP_MS);
+    return () => window.clearInterval(timer);
+  }, [inFlight]);
 
   const patch = (index: number, next: Partial<GalleryItem>) =>
     setItems((current) => current.map((item, i) => (i === index ? { ...item, ...next } : item)));
 
-  /** A stand-in transfer: four steps, then done. */
-  const run = (index: number, direction: "upload" | "download") => {
-    let share = 0;
+  const start = (index: number, direction: "upload" | "download") =>
     patch(index, { transfer: "loading", transferProgress: 0, transferDirection: direction });
-    const timer = window.setInterval(() => {
-      share = Math.min(1, share + 0.25);
-      patch(index, { transferProgress: share, ...(share >= 1 ? { transfer: "done" } : {}) });
-      if (share >= 1) window.clearInterval(timer);
-    }, STEP_MS);
-  };
 
   return (
     <Gallery
       items={items}
       onCancel={(index) => patch(index, { transfer: "failed" })}
-      onRetry={(index) => run(index, "upload")}
-      onDownload={(index) => run(index, "download")}
+      onRetry={(index) => start(index, "upload")}
+      onDownload={(index) => start(index, "download")}
     />
   );
 }

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

@@ -48,7 +48,7 @@ Gantt                          surface (layer of the ladder), size container
 | `getRowLabel` | `(row: Row) => string` | — (required) | Row name: the first column text by default and the row header for assistive tech. |
 | `getRowBars` | `(row: Row) => Bar[]` | — (required) | Bars of a row (`GanttBar`); bars that overlap in time stack into lanes and grow the row. |
 | `renderRow` | `(row: Row) => ReactNode` | — | First-column content instead of the label (a name with a role or a code). |
-| `renderRowAvatar` | `(row: Row) => ReactNode` | — | A picture before the row content (an `Avatar`). Below 36rem of chart width the column keeps only it; the name stays for assistive tech. |
+| `renderRowAvatar` | `(row: Row) => ReactNode` | — | A picture before the row content (an `Avatar`). Below 36rem of chart width the column keeps only it; the row header is then named by `getRowLabel` (`aria-label`). |
 | `getRowHref` | `(row: Row) => string` | — | The row header is a link: a real `<a>` fills the first column and is the row's stop in the grid, so a click, ⌘/Ctrl-click, a middle click and «open in new tab» work on it; Space follows it like Enter. |
 | `onRowClick` | `(row: Row, event: GanttRowClickEvent) => void` | — | Opens a row in place (a profile in a Drawer): a click on its header, Enter or Space; never from a control inside it. With `getRowHref` it gets plain clicks: `event.preventDefault()` routes in the app. |
 | `renderBarTooltip` | `(bar: Bar, row: Row) => ReactNode` | — | Extra lines of a bar's tooltip (a client, hours, an owner), under its title and the dates line — those always stay, the dates and the duration are what the bar means on the axis. |
@@ -56,24 +56,26 @@ Gantt                          surface (layer of the ladder), size container
 | `defaultScale` | `"day" \| "week" \| "month"` | `"week"` | Initial zoom, uncontrolled. |
 | `onScaleChange` | `(scale: GanttScale) => void` | — | The zoom switch changed. The day in the middle of the view stays in the middle. |
 | `range` | `{ start: Date; end: Date }` | — | The time axis, snapped to whole units. Default: every bar and today with room on both sides (a week of days, two weeks, a month), at least 35 days / 14 weeks / 12 months. |
-| `today` | `Date` | `new Date()` | The day of the today line; the chart opens with it a third into the view and «Сегодня» scrolls back to it. |
+| `today` | `Date` | today | The day of the today line; the chart opens with it a third into the view and «Сегодня» scrolls back to it. |
 | `locale` | `Locale` | `ru` | date-fns locale of the header, tooltips and spoken dates. |
-| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Tier of rows, bars, header and toolbar controls: one-lane rows 28 · 32 · 44 · 48 · 52 px; a day is 32 · 40 · 48 px wide at `day`. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | host tier, else `"m"` | Tier of rows, bars, header and toolbar controls: one-lane rows 28 · 32 · 44 · 48 · 52 px; a day is 32 · 40 · 48 px wide at `day`; bar text one tier down. Without it the tier of its host, else `m`. |
 | `readOnly` | `boolean` | `false` | No moving, resizing or creating; bars still select and show their dates. |
 | `loading` | `boolean` | `false` | Without rows — skeleton rows in the chart's geometry and a status for screen readers; with rows they stay and the grid is `aria-busy`. |
 | `empty` | `ReactNode` | — | Empty-state content when `rows` is empty; a string goes into a compact `EmptyPage`. Defaults to `labels.empty`. |
 | `toolbar` | `ReactNode` | — | Content at the start of the toolbar (title, filters, a primary action); the zoom and «Сегодня» sit at its end. |
 | `scrollHeight` | `number \| "fill"` | — | Max height of the viewport in px, so the header sticks while rows scroll; `"fill"` — the chart takes its flex / grid parent's height. |
-| `onSelect` | `(bar: Bar, row: Row) => void` | — | A bar was activated (click, Enter, Space): open its record. A drag never selects. |
+| `onItemOpen` | `(bar: Bar, row: Row) => void` | — | A bar was activated (click, Enter, Space): open its record. A drag never opens it. |
 | `onBarChange` | `(dates: GanttDates, bar: Bar, row: Row) => void \| Promise<void>` | — | New dates of a bar after a drag or an editing key — update your data. A returned Promise keeps the bar busy at the new dates; a rejection glides it back. Without it bars cannot be edited. |
 | `onBarCreate` | `(dates: GanttDates, row: Row) => void \| Promise<void>` | — | A new bar in a row: drawn across empty space, a double-click, a touch long-press or `N`. Add it to your data; a returned Promise keeps a busy ghost in place. Without it nothing can be created. |
 | `labels` | `Partial<GanttLabels>` | — | Built-in strings, see Labels. |
-| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children" \| "onSelect">` | — | `aria-label` (the grid's name), `className` and the other div attributes. |
+| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children">` | — | `aria-label` (the grid's name), `className` and the other div attributes. |
 
-### GanttBar
+### Types
+
+#### `GanttBar`
 One bar of `getRowBars`: data, not a part. Dates are calendar days with an exclusive `end`; `start` equal to `end` is a milestone. Extend the type with your own fields: callbacks get your object back.
 
-| Prop | Type | Default | Description |
+| Field | Type | Default | Description |
 |---|---|---|---|
 | `id` | `string` | — (required) | Unique across the chart. |
 | `start` | `Date` | — (required) | First day. |
@@ -126,7 +128,7 @@ A `tone` wins over `color`. Say the status in the label too, never only by color
 | State | Driven by | DOM |
 |---|---|---|
 | zoom | `scale` / `defaultScale` | `data-scale` on the root; the grid cross-fades into the new zoom, the day in the middle stays in the middle |
-| tier | `size` | `data-size` on the root |
+| tier | `size` (else the host tier) | `data-size` on the root; each row's track carries the tier one down (`data-size`), the size of the bar text |
 | bar color | `color` / `tone` | `data-color` (without a tone) or `data-tone` on the bar |
 | milestone | `start` equal to `end` | `data-milestone`: a diamond on its day, the label beside it |
 | label beside | the label does not fit the bar (measured) | `data-label="inside" \| "outside" \| "hidden"` (beside the bar when there is room, else hidden; the name and the tooltip keep it) |
@@ -137,7 +139,7 @@ A `tone` wins over `color`. Say the status in the label too, never only by color
 | pending | `onBarChange` returned a Promise | `data-pending`, `aria-busy`, a Spinner; reject → the bar glides back |
 | loading | `loading` without rows | Skeleton rows with one or two bars each in a real bar's height, radius and lane, under the column and today lines; `aria-busy`, status `labels.loading`; data cross-fades in |
 | empty | `rows` empty | a compact `EmptyPage` (`empty` or `labels.empty`), cross-faded in |
-| row opens | `onRowClick` / `getRowHref` | `data-clickable` on the row header: a pointer cursor and a hover wash under its content; with `getRowHref` the content is an `<a>` whose hit area fills the header |
+| row opens | `onRowClick` / `getRowHref` | `data-clickable` on the row header: a pointer cursor and a hover wash under its content (an inset shadow over the opaque header, faded both ways); with `getRowHref` the content is an `<a>` whose hit area fills the header |
 | scrolled | the axis hides content at an edge | `data-overflow-start` / `data-overflow-end`: an edge shadow from the pinned column / at the end |
 
 ## Layout & spacing
@@ -146,7 +148,7 @@ A `tone` wins over `color`. Say the status in the label too, never only by color
 - Header: two quiet mono tiers. The upper tier (months as `MM.yyyy` — «09.2026» — or years at `month`) is the faintest text on the chart and has no lines: a period is told by its label, which starts at the period's first column (at `week`, the first ISO week: the one whose Thursday is in the month) and rides the start of the visible axis while the period is on screen. The lower tier has faint hairlines; the column that opens a new period gets a slightly stronger line, down through the rows too. The today line and the «Сегодня» flag lie over the labels; today's cell is an accent chip with the kit's chip radius (a single digit is a small rectangle, never a circle).
 - The header (two tiers) and the first column stick inside the chart's own scroller; pass `scrollHeight` (or `"fill"` in a sized parent) so the header sticks while rows scroll. Below 480 px of screen height the header scrolls with the rows.
 - Virtualization: rows render only in view (plus an overscan) at offsets computed from their lanes and corrected by measuring, so the total height and the scrollbar stay exact; header cells, period lines and bars render only inside the visible time window plus a screen on each side; weekends and day / week column lines are CSS patterns, not elements. A focused, dragged, pending or new bar stays rendered wherever the chart scrolls.
-- Editing precision: a move, a resize and a drawing snap to whole days at every zoom (at the month zoom a day is 4 px, so the snap holds a day until the pointer clearly leaves it); hold Alt to snap to the zoom's week or month. A bar is at least one day long: a resize past the opposite edge stops there and never flips. On touch a long press picks a bar up, then it drags like a pointer.
+- Editing precision: a move, a resize and a drawing snap to whole days at every zoom (at the month zoom a day is 4 px, so the snap holds a day until the pointer clearly leaves it); hold Alt to snap to the zoom's week or month. A bar is at least one day long: a resize past the opposite edge stops there and never flips. On touch a finger held on a bar picks it up, then it drags like a pointer.
 - Creating: on empty space the cursor is a crosshair and, on pointer devices, the cell under it is washed with a «+». Drag across a row to draw a range in days, double-click (or long-press on touch) for one unit of the zoom; a drag after the long press draws days. While drawing, a ghost with a dates and duration tooltip follows the pointer. Without `onBarCreate` (or with `readOnly`) nothing can be created and empty space shows no create cursor. Near the edges of the axis a drag, a resize and a drawing scroll the chart.
 - Tooltip: the bar's title, then its dates · duration · progress; `renderBarTooltip` adds lines under them (a client, planned hours) and never replaces them — the dates are what the bar means on the axis, and the same tooltip shows the new dates while dragging.
 - A legend of bar colours goes in `toolbar`: a row of `Badge.Root color` + `Badge.Dot` with the category name, one per hue the bars use; the toolbar wraps it. Say the category in the bar label or the tooltip too, never only by colour.
@@ -158,13 +160,15 @@ A `tone` wins over `color`. Say the status in the label too, never only by color
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 | Key | Action |
 |---|---|
 | `Tab` | The chart is one tab stop: the last active cell (a bar or a row header). |
 | `←` · `→` | Along the row: its header, then its bars in time order. A row off screen is rendered and scrolled into view. |
 | `↑` · `↓` | From a bar, the bar nearest in time in the row above / below (rows without bars are skipped); from a row header, the next row's header, empty rows too. |
 | `Home` · `End` | First / last bar of the row; with Ctrl, of the chart. |
-| `Enter` · `Space` | On a bar: selects it (`onSelect`). On a row header: opens the row (`onRowClick`) or follows its link (`getRowHref`). |
+| `Enter` · `Space` | On a bar: opens its record (`onItemOpen`). On a row header: opens the row (`onRowClick`) or follows its link (`getRowHref`). |
 | `Shift + ←` · `Shift + →` | Moves the bar by one day, at every zoom. |
 | `Shift + Alt + ←` · `Shift + Alt + →` | Moves the bar by the zoom's unit (a week, a month). |
 | `Ctrl + Shift + ←` · `Ctrl + Shift + →` | Shortens / lengthens the bar by one day (⌘ on macOS); it stops at one day. |
@@ -173,6 +177,8 @@ A `tone` wins over `color`. Say the status in the label too, never only by color
 | `Escape` | Cancels a drag or the drawing of a new bar; closes the tooltip. |
 
 ### ARIA
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 - A `role="grid"` named by `aria-label`: a header row of `columnheader`s (the first column and the time axis named `labels.timeline`), then a row per record with a `rowheader` (the row name) and a `gridcell` holding its bars. A grid because the bars are navigated in two dimensions: moving between rows, a screen reader announces the row.
 - A bar is a `<button>` named «Задача: 6 июля 2026 — 10 июля 2026» (with «выполнено 50%» when it has progress); a milestone «Релиз: 20 июля 2026». The Tooltip with the dates opens on hover and on focus and closes as soon as the chart scrolls (scrollbar, wheel, touch); the next hover or focus opens it again. It points at the visible part of the bar and stays inside the timeline, never over the label column or the header; a bar with less than `--prime-space-6` in view shows none.
 - An editable bar has `aria-keyshortcuts` and is described by `labels.editHint`; the new dates after an editing key are announced in a polite status, a refused change with `labels.changeFailed`.
@@ -212,24 +218,24 @@ A `tone` wins over `color`. Say the status in the label too, never only by color
 | [overview.tsx](examples/overview.tsx) | A project plan: work streams with phases, progress and a launch milestone that move and stretch by pointer or keyboard — `getRowBars`, `onBarChange`. |
 | [variants.tsx](examples/variants.tsx) | Bars colored by category with palette hues, and by status with tones that win over the hue — `color`, `tone`. |
 | [sizes.tsx](examples/sizes.tsx) | Every tier: one-lane rows from 28 to 52 px, bars, header and toolbar controls of the tier — `size`. |
-| [occupancy.tsx](examples/occupancy.tsx) | Team occupancy by day: people with avatars, projects that overlap into lanes, locked vacations, a saved move held busy and a conflicting one gliding back, new work drawn on a free day — `renderRowAvatar`, `renderRow`, `onBarChange`, `onBarCreate`, `onSelect`, `readOnly`. |
+| [occupancy.tsx](examples/occupancy.tsx) | Team occupancy by day: people with avatars, projects that overlap into lanes, locked vacations, a saved move held busy and a conflicting one gliding back, new work drawn on a free day — `renderRowAvatar`, `renderRow`, `onBarChange`, `onBarCreate`, `onItemOpen`, `readOnly`. |
 | [large.tsx](examples/large.tsx) | Two thousand people over two years stay fast: only the rows and days in view are rendered, keyboard focus reaches any row, and new bars are drawn on empty space — `rows`, `range`, `scrollHeight`, `onBarCreate`. |
 | [row-link.tsx](examples/row-link.tsx) | A team by client: each row header is a link to the person's profile that a plain click opens in place, each tooltip adds the client and the planned hours under the dates, and a legend of client hues stands in the toolbar — `getRowHref`, `onRowClick`, `renderBarTooltip`. |
 | [states.tsx](examples/states.tsx) | Skeleton rows in the chart's geometry while it loads, an empty period and a report you may only look at, its today line on the report day — `loading`, `empty`, `readOnly`, `today`. |
 | [controlled.tsx](examples/controlled.tsx) | The zoom owned by the page: presets in the toolbar and the built-in switch change one state — `scale`, `onScaleChange`. |
 | [narrow.tsx](examples/narrow.tsx) | At 360 px the first column keeps only the avatars, the toolbar moves to its own row and the axis scrolls under the pinned column — `renderRowAvatar`. |
-| [screen.tsx](examples/screen.tsx) | A team schedule as a work screen: the title with the people shown and a PageToolbar with search, filters, team sections and the primary action in the app header over a full-height Gantt; moves saved or refused, new work drawn and named in a Modal, details in a Drawer — `scrollHeight`, `onBarChange`, `onBarCreate`, `onSelect`. |
+| [screen.tsx](examples/screen.tsx) | A team schedule as a work screen: the title with the people shown and a PageToolbar with search, filters, team sections and the primary action in the app header over a full-height Gantt; moves saved or refused, new work drawn and named in a Modal, details in a Drawer — `scrollHeight`, `onBarChange`, `onBarCreate`, `onItemOpen`. |
 
 ## Mistakes
 - Updating the rows before the request succeeds (optimistic) → the chart cannot glide back on reject; update them when `onBarChange` resolves, or before you resolve it.
 - An inclusive `end` (`{ start: 3 July, end: 3 July }` for a one-day task) → that is a milestone; `end` is the day after the last one.
 - Status only by bar color → put it into the label too («Отпуск», «Просрочено»).
 - Dates with times expecting hour precision → the chart works in calendar days.
-- A `<div onClick>` inside `renderRow` to open a bar's or a row's record → use `onSelect` for a bar and `onRowClick` / `getRowHref` for a row: they work from the keyboard too.
+- A `<div onClick>` inside `renderRow` to open a bar's or a row's record → use `onItemOpen` for a bar and `onRowClick` / `getRowHref` for a row: they work from the keyboard too.
 - Replacing the dates in the tooltip with your own text → `renderBarTooltip` adds lines under them; the dates stay.
 - Wrapping the chart in a Card → it is a surface itself; place it directly in the page or a Card body only as the card's one content.
 - Expecting the page to scroll to today → «Сегодня» scrolls only the chart.
 
 ## Related
-- **Built from:** [ScrollContainer](../scroll-container/COMPONENT.md), [Tooltip](../tooltip/COMPONENT.md), [SegmentedControl](../segmented-control/COMPONENT.md), [Button](../button/COMPONENT.md), [Skeleton](../skeleton/COMPONENT.md), [EmptyPage](../empty-page/COMPONENT.md), [Spinner](../spinner/COMPONENT.md), Icon (`action.add` in the create cue)
+- **Built from:** [ScrollContainer](../scroll-container/COMPONENT.md), [Tooltip](../tooltip/COMPONENT.md), [SegmentedControl](../segmented-control/COMPONENT.md), [Button](../button/COMPONENT.md), [Skeleton](../skeleton/COMPONENT.md), [EmptyPage](../empty-page/COMPONENT.md), [Spinner](../spinner/COMPONENT.md), Icon (`action.add` in the create cue), [VisuallyHidden](../visually-hidden/COMPONENT.md)
 - **See also:** [Timeline](../timeline/COMPONENT.md), [DataTable](../data-table/COMPONENT.md), [Kanban](../kanban/COMPONENT.md), [Datepicker](../datepicker/COMPONENT.md), [Avatar](../avatar/COMPONENT.md)