prime-ui-kit 0.15.0 → 0.17.0

package/src/components/file-upload/examples/screen.module.css

@@ -1,5 +1,5 @@
-/* Media library: a work screen — the app header carries the title and the tools; this module lays
-   out the library block only, the page rhythm comes from PageContent. */
+/* Media library: a work screen — the page top bar carries the title and the tools; this module lays
+   out the library block only, the page rhythm comes from Page. */
 
 .bar {
   display: flex;
@@ -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/src/components/file-upload/examples/screen.tsx

@@ -1,17 +1,17 @@
-/** A media library of a catalog object as a work screen: the title, the object and a PageToolbar with sections, search, order and upload in the app header; uploads in FileUpload tiles through a queue; a grid of Thumbnails that open MediaViewer out of the tile or are picked for bulk download and delete; a Skeleton first load and a filtered empty state in a Crossfade — `trigger`, `layout`. */
+/** A media library of a catalog object as a work screen: the title, the object and a toolbar with sections, search, order and upload in its top bar; uploads in FileUpload tiles through a queue; a grid of Thumbnails that open MediaViewer out of the tile or are picked for bulk download and delete; a Skeleton first load and a filtered empty state in a Crossfade — `trigger`, `layout`. */
 import {
-  AppHeader,
   Button,
   ConfirmDialog,
   Crossfade,
   EmptyPage,
   FileUpload,
+  type FileUploadPicker,
+  formatDateValue,
   formatFileSize,
   Icon,
   MediaViewer,
   type MediaViewerItem,
-  PageContent,
-  PageToolbar,
+  Page,
   SegmentedControl,
   Select,
   Skeleton,
@@ -201,7 +201,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 +267,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>());
 
@@ -363,76 +363,62 @@ export default function FileUploadScreenExample() {
   const totalSize = visible.reduce((sum, media) => sum + media.size, 0);
 
   return (
-    <>
-      {/* A work screen: in an app this header fills the shell's `header` slot and carries the page —
-          the only h1, the object it belongs to and the page's tools; main has no PageContent.Header. */}
-      <AppHeader.Root>
-        <AppHeader.Start>
-          <AppHeader.Title>
-            Медиатека
-            <AppHeader.Description>БЦ «Северная башня», Невский пр., 112</AppHeader.Description>
-          </AppHeader.Title>
-        </AppHeader.Start>
-        <AppHeader.Tools>
-          <SmartFilter.Root
-            fields={[]}
-            search={search}
-            onSearchChange={setSearch}
-            labels={{ searchPlaceholder: "Поиск по названию" }}
-          >
-            <PageToolbar.Root aria-label="Медиатека">
-              <PageToolbar.Tools>
-                <SmartFilter.Toolbar />
-              </PageToolbar.Tools>
-              <PageToolbar.Sections>
-                <SegmentedControl.Root
-                  fullWidth
-                  value={section}
-                  onValueChange={(value) => setSection(value as Section)}
-                  aria-label="Раздел"
-                >
-                  {SECTIONS.map((item) => (
-                    <SegmentedControl.Item key={item.value} value={item.value}>
-                      {item.label}
-                      {loading ? null : (
-                        <SegmentedControl.Count>{count(item.value)}</SegmentedControl.Count>
-                      )}
-                    </SegmentedControl.Item>
-                  ))}
-                </SegmentedControl.Root>
-              </PageToolbar.Sections>
-              <PageToolbar.View>
-                <Select.Root value={order} onValueChange={(value) => setOrder(value as Order)}>
-                  <Select.Trigger aria-label="Порядок">
-                    <Select.TriggerIcon>
-                      <Icon name="sort.descending" />
-                    </Select.TriggerIcon>
-                    <Select.Value />
-                  </Select.Trigger>
-                  <Select.Content>
-                    {ORDERS.map((item) => (
-                      <Select.Item key={item.value} value={item.value}>
-                        {item.label}
-                      </Select.Item>
-                    ))}
-                  </Select.Content>
-                </Select.Root>
-              </PageToolbar.View>
-              <PageToolbar.Actions>
-                <Button.Root onClick={() => inputRef.current?.click()}>
-                  <Button.Icon>
-                    <Icon name="action.upload" />
-                  </Button.Icon>
-                  Загрузить
-                </Button.Root>
-              </PageToolbar.Actions>
-            </PageToolbar.Root>
-          </SmartFilter.Root>
-        </AppHeader.Tools>
-      </AppHeader.Root>
-
-      <PageContent.Root>
-        <PageContent.Body>
+    <SmartFilter.Root
+      fields={[]}
+      search={search}
+      onSearchChange={setSearch}
+      labels={{ searchPlaceholder: "Поиск по названию" }}
+    >
+      <Page.Root>
+        {/* A work screen titles itself in its top bar: the only h1, the object it belongs to, the
+          page's tools — sections, search, order — and the upload. */}
+        <Page.TopBar>
+          <Page.Heading>
+            <Page.Title>Медиатека</Page.Title>
+            <Page.Description>БЦ «Северная башня», Невский пр., 112</Page.Description>
+          </Page.Heading>
+          <Page.Tools aria-label="Медиатека">
+            <SegmentedControl.Root
+              value={section}
+              onValueChange={(value) => setSection(value as Section)}
+              aria-label="Раздел"
+            >
+              {SECTIONS.map((item) => (
+                <SegmentedControl.Item key={item.value} value={item.value}>
+                  {item.label}
+                  {loading ? null : (
+                    <SegmentedControl.Count>{count(item.value)}</SegmentedControl.Count>
+                  )}
+                </SegmentedControl.Item>
+              ))}
+            </SegmentedControl.Root>
+            <SmartFilter.Toolbar />
+            <Select.Root value={order} onValueChange={(value) => setOrder(value as Order)}>
+              <Select.Trigger aria-label="Порядок">
+                <Select.TriggerIcon>
+                  <Icon name="sort.descending" />
+                </Select.TriggerIcon>
+                <Select.Value />
+              </Select.Trigger>
+              <Select.Content>
+                {ORDERS.map((item) => (
+                  <Select.Item key={item.value} value={item.value}>
+                    {item.label}
+                  </Select.Item>
+                ))}
+              </Select.Content>
+            </Select.Root>
+          </Page.Tools>
+          <Page.Actions>
+            <Button.Root onClick={() => picker.current?.open()}>
+              <Button.Icon>
+                <Icon name="action.upload" />
+              </Button.Icon>
+              Загрузить
+            </Button.Root>
+          </Page.Actions>
+        </Page.TopBar>
+        <Page.Body>
           {/* Uploads in flight: the add tile is also the drop zone; a done file moves into the grid. */}
           <FileUpload.Root
             label="Новые файлы"
@@ -442,10 +428,10 @@ export default function FileUploadScreenExample() {
             accept="image/*,video/*"
             multiple
             queue={queue}
-            inputRef={inputRef}
+            picker={picker}
           />
 
-          <PageContent.Section
+          <Page.Section
             label="Файлы"
             description={
               <span aria-live="polite">
@@ -457,7 +443,7 @@ export default function FileUploadScreenExample() {
               </span>
             }
           >
-            <PageContent.Actions>
+            <Page.Actions>
               <Crossfade state={selecting ? "select" : "browse"}>
                 {selecting ? (
                   <div className={styles.bar}>
@@ -507,7 +493,7 @@ export default function FileUploadScreenExample() {
                   </div>
                 )}
               </Crossfade>
-            </PageContent.Actions>
+            </Page.Actions>
 
             <Crossfade state={state} aria-busy={loading}>
               {loading ? (
@@ -619,7 +605,7 @@ export default function FileUploadScreenExample() {
                 </EmptyPage.Root>
               ) : null}
             </Crossfade>
-          </PageContent.Section>
+          </Page.Section>
 
           <MediaViewer
             items={viewerItems}
@@ -639,8 +625,8 @@ export default function FileUploadScreenExample() {
               </Button.Root>
             )}
           />
-        </PageContent.Body>
-      </PageContent.Root>
-    </>
+        </Page.Body>
+      </Page.Root>
+    </SmartFilter.Root>
   );
 }

package/src/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/src/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/src/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/src/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,23 @@ 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.
+- A video tile shorter than 6.5rem (a small tile of a phone album) has no room for the centred play mark under the length pill: it shows the length alone, so the two marks never collide.
 
 ## 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 +140,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 +157,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/src/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/src/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/src/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/src/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/src/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")}
     />
   );
 }