prime-ui-kit 0.10.0 → 0.11.0

package/src/components/file-upload/examples/overview.tsx

@@ -1,52 +1,49 @@
-/** Attachments of a request: a labelled drop zone and the chosen files as rows with a remove button — `label`, `hint`, `multiple`, `onFilesChange`, `FileUpload.Item`. */
-import { Button, FileUpload, Icon } from "prime-ui-kit";
-import * as React from "react";
+/** Documents of a deal: a drop zone, the files already attached as rows, and new files uploading through a queue with progress, a reason and a retry — `label`, `hint`, `multiple`, `defaultValue`, `queue`. */
+import { FileUpload, type FileUploadFile, type UploadContext, useUploadQueue } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
 
-const formatSize = (bytes: number) =>
-  bytes < 1024 * 1024
-    ? `${Math.max(1, Math.round(bytes / 1024))} КБ`
-    : `${(bytes / 1024 / 1024).toFixed(1)} МБ`;
+const MAX_SIZE = 10 * 1024 * 1024;
 
-const fileKey = (file: File) => `${file.name}-${file.size}-${file.lastModified}`;
+const ATTACHED: readonly FileUploadFile[] = [
+  { id: "deal-contract", name: "Договор № 48-П.pdf", size: 1_840_000, type: "application/pdf" },
+  { id: "deal-estimate", name: "Смета.xlsx", size: 240_000 },
+];
+
+/** A stand-in for the server: sends a file in a few steps and answers with its address. */
+function sendFile(file: File, { signal, onProgress }: UploadContext): Promise<string> {
+  return new Promise((resolve, reject) => {
+    if (file.size > MAX_SIZE) {
+      reject(new Error("Файл больше 10 МБ"));
+      return;
+    }
+    let sent = 0;
+    const timer = window.setInterval(() => {
+      sent = Math.min(1, sent + 0.12 + Math.random() * 0.12);
+      onProgress(sent);
+      if (sent < 1) return;
+      window.clearInterval(timer);
+      resolve(`https://files.example.com/deals/${encodeURIComponent(file.name)}`);
+    }, 300);
+    signal.addEventListener("abort", () => {
+      window.clearInterval(timer);
+      reject(signal.reason);
+    });
+  });
+}
 
 export default function FileUploadOverviewExample() {
-  const [files, setFiles] = React.useState<File[]>([]);
+  const queue = useUploadQueue({ upload: sendFile, concurrency: 2 });
 
   return (
     <div className={styles.column}>
       <FileUpload.Root
-        label="Документы к заявке"
-        hint="PDF, PNG или JPG, можно несколько"
+        label="Документы сделки"
+        hint="Любые файлы до 10 МБ, можно несколько"
         multiple
-        accept=".pdf,.png,.jpg,.jpeg"
-        onFilesChange={(next) =>
-          setFiles((current) => {
-            const known = new Set(current.map(fileKey));
-            return [...current, ...next.filter((file) => !known.has(fileKey(file)))];
-          })
-        }
+        defaultValue={ATTACHED}
+        queue={queue}
       />
-      {files.map((file) => (
-        <FileUpload.Item key={fileKey(file)}>
-          <FileUpload.FormatBadge format={file.name.split(".").pop() ?? "file"} />
-          <FileUpload.ItemName>{file.name}</FileUpload.ItemName>
-          <FileUpload.ItemDescription>{formatSize(file.size)}</FileUpload.ItemDescription>
-          <FileUpload.ItemActions>
-            <Button.Root
-              variant="ghost"
-              tone="neutral"
-              aria-label={`Удалить ${file.name}`}
-              onClick={() => setFiles((current) => current.filter((item) => item !== file))}
-            >
-              <Button.Icon>
-                <Icon name="action.close" />
-              </Button.Icon>
-            </Button.Root>
-          </FileUpload.ItemActions>
-        </FileUpload.Item>
-      ))}
     </div>
   );
 }

package/src/components/file-upload/examples/row-parts.tsx

@@ -0,0 +1,41 @@
+/** Rows the set does not draw, built from parts: order documents with a download button, a photo with its preview and a report still being prepared — `FileUpload.Item`, `FileUpload.FormatBadge`, `FileUpload.ItemPreview`, `FileUpload.ItemActions`, `FileUpload.ItemProgress`. */
+import { Button, FileUpload, Icon } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function FileUploadRowPartsExample() {
+  return (
+    <div className={styles.column}>
+      <FileUpload.Item>
+        <FileUpload.FormatBadge format="pdf" color="red" />
+        <FileUpload.ItemName>Счёт № 318.pdf</FileUpload.ItemName>
+        <FileUpload.ItemDescription>1,2 МБ · выставлен 12 марта</FileUpload.ItemDescription>
+        <FileUpload.ItemActions>
+          <Button.Root variant="ghost" tone="neutral" aria-label="Скачать Счёт № 318.pdf">
+            <Button.Icon>
+              <Icon name="action.download" />
+            </Button.Icon>
+          </Button.Root>
+        </FileUpload.ItemActions>
+      </FileUpload.Item>
+      <FileUpload.Item>
+        <FileUpload.ItemPreview src="https://picsum.photos/seed/warehouse-gate/160/160" />
+        <FileUpload.ItemName>Отгрузка, паллет 4.jpg</FileUpload.ItemName>
+        <FileUpload.ItemDescription>820 КБ · снято при отгрузке</FileUpload.ItemDescription>
+        <FileUpload.ItemActions>
+          <Button.Root variant="ghost" tone="neutral" aria-label="Скачать Отгрузка, паллет 4.jpg">
+            <Button.Icon>
+              <Icon name="action.download" />
+            </Button.Icon>
+          </Button.Root>
+        </FileUpload.ItemActions>
+      </FileUpload.Item>
+      <FileUpload.Item>
+        <FileUpload.FormatBadge format="xlsx" color="green" />
+        <FileUpload.ItemName>Отчёт по заказу.xlsx</FileUpload.ItemName>
+        <FileUpload.ItemDescription>Формируется · 60%</FileUpload.ItemDescription>
+        <FileUpload.ItemProgress value={60} aria-label="Формируется: Отчёт по заказу.xlsx" />
+      </FileUpload.Item>
+    </div>
+  );
+}

package/src/components/file-upload/examples/saving.tsx

@@ -0,0 +1,71 @@
+/** Published listing photos with no picker, every change saved on the server: a moved or removed photo waits busy, and a change the server refuses puts the set back — `FileUpload.Queue`, `onValueChange`, `value`, `cover`. */
+import { FileUpload, type FileUploadFile, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const PHOTOS: readonly FileUploadFile[] = [
+  {
+    id: "sedan-front",
+    name: "Спереди.jpg",
+    type: "image/jpeg",
+    src: "https://picsum.photos/seed/sedan-front/480/480",
+  },
+  {
+    id: "sedan-side",
+    name: "Сбоку.jpg",
+    type: "image/jpeg",
+    src: "https://picsum.photos/seed/sedan-side/480/480",
+  },
+  {
+    id: "sedan-back",
+    name: "Сзади.jpg",
+    type: "image/jpeg",
+    src: "https://picsum.photos/seed/sedan-back/480/480",
+  },
+  {
+    id: "sedan-salon",
+    name: "Салон.jpg",
+    type: "image/jpeg",
+    src: "https://picsum.photos/seed/sedan-salon/480/480",
+  },
+];
+
+/** The server saving the set a beat later: moderation needs the front photo in the listing. */
+function savePhotos(photos: readonly FileUploadFile[]) {
+  return new Promise<void>((resolve, reject) => {
+    setTimeout(() => {
+      if (photos.some((photo) => photo.id === "sedan-front")) resolve();
+      else reject(new Error("Фото «Спереди» нужно для модерации — его не удалить"));
+    }, 900);
+  });
+}
+
+export default function FileUploadSavingExample() {
+  const [photos, setPhotos] = React.useState(PHOTOS);
+  const [failure, setFailure] = React.useState<string | null>(null);
+
+  return (
+    <div className={styles.wide}>
+      <Typography as="p" variant="body-s" tone={failure ? "danger" : "muted"}>
+        {failure ?? "Порядок и удаление сохраняются на сервере сразу"}
+      </Typography>
+      <FileUpload.Queue
+        aria-label="Фотографии объявления"
+        layout="grid"
+        cover
+        value={photos}
+        onValueChange={async (next) => {
+          setFailure(null);
+          try {
+            await savePhotos(next);
+          } catch (error) {
+            setFailure(error instanceof Error ? error.message : String(error));
+            throw error;
+          }
+          setPhotos(next);
+        }}
+      />
+    </div>
+  );
+}

package/src/components/file-upload/examples/sizes.tsx

@@ -1,26 +1,25 @@
-/** Every size of the zone and of a file row: padding, icon, button and text follow the tier — `size`. */
-import { FileUpload } from "prime-ui-kit";
+/** 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[] = [
+  { id: "contract", name: "Договор поставки.pdf", size: 240_000, type: "application/pdf" },
+];
+
 export default function FileUploadSizesExample() {
   return (
     <div className={styles.column}>
       {SIZES.map((size) => (
-        <div key={size} className={styles.sizeRow}>
-          <FileUpload.Root
-            size={size}
-            label={size}
-            labels={{ title: "Перетащите файл", description: "" }}
-          />
-          <FileUpload.Item size={size}>
-            <FileUpload.FormatBadge format="pdf" color="red" />
-            <FileUpload.ItemName>Договор поставки.pdf</FileUpload.ItemName>
-            <FileUpload.ItemDescription>240 КБ</FileUpload.ItemDescription>
-          </FileUpload.Item>
-        </div>
+        <FileUpload.Root
+          key={size}
+          size={size}
+          label={size}
+          defaultValue={CONTRACT}
+          labels={{ title: "Перетащите файл", description: "" }}
+        />
       ))}
     </div>
   );

package/src/components/file-upload/examples/states.tsx

@@ -1,13 +1,22 @@
-/** A default zone, a disabled one and an invalid one without a message — `disabled`, `invalid`. */
-import { FileUpload } from "prime-ui-kit";
+/** 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";
 
+const ACT: readonly FileUploadFile[] = [
+  { id: "act", name: "Акт сверки.pdf", size: 310_000, type: "application/pdf" },
+];
+
 export default function FileUploadStatesExample() {
   return (
     <div className={styles.column}>
       <FileUpload.Root label="default" hint="PDF или PNG до 20 МБ" />
-      <FileUpload.Root label="disabled" disabled hint="Станет доступно после выбора заказа" />
+      <FileUpload.Root
+        label="disabled"
+        disabled
+        defaultValue={ACT}
+        hint="Заказ закрыт, документы только для просмотра"
+      />
       <FileUpload.Root label="invalid" invalid hint="PDF или PNG до 20 МБ" />
     </div>
   );

package/src/components/file-upload/examples/validation.tsx

@@ -1,21 +1,29 @@
 /** A required scan checked as soon as it is picked: a wrong type or a large file shakes in an error that leaves when the file is removed; a hint and an optional zone — `required`, `hint`, `error`, `optional`. */
-import { Button, FileUpload, Icon } from "prime-ui-kit";
+import { FileUpload, type FileUploadFile } from "prime-ui-kit";
 import * as React from "react";
 
 import styles from "./examples.module.css";
 
 const MAX_SIZE = 20 * 1024 * 1024;
 
-/** The scan error, or nothing when every picked file is a PDF within the limit. */
-function scanError(files: File[]) {
+/** A picked file as a file of the set. */
+const toFile = (file: File): FileUploadFile => ({
+  id: `${file.name}-${file.size}-${file.lastModified}`,
+  name: file.name,
+  size: file.size,
+  type: file.type,
+});
+
+/** The scan error, or nothing when every file is a PDF within the limit. */
+function scanError(files: readonly FileUploadFile[]) {
   if (files.some((file) => !file.name.toLowerCase().endsWith(".pdf")))
     return "Нужен файл в формате PDF";
-  if (files.some((file) => file.size > MAX_SIZE)) return "Файл больше 20 МБ";
+  if (files.some((file) => (file.size ?? 0) > MAX_SIZE)) return "Файл больше 20 МБ";
   return undefined;
 }
 
 export default function FileUploadValidationExample() {
-  const [files, setFiles] = React.useState<File[]>([]);
+  const [scan, setScan] = React.useState<readonly FileUploadFile[]>([]);
 
   return (
     <div className={styles.column}>
@@ -23,27 +31,11 @@ export default function FileUploadValidationExample() {
         label="Скан договора"
         required
         hint="PDF до 20 МБ, все страницы"
-        error={scanError(files)}
-        onFilesChange={setFiles}
+        error={scanError(scan)}
+        value={scan}
+        onValueChange={setScan}
+        onFilesChange={(files) => setScan(files.map(toFile))}
       />
-      {files.map((file) => (
-        <FileUpload.Item key={file.name}>
-          <FileUpload.FormatBadge format={file.name.split(".").pop() ?? ""} color="red" />
-          <FileUpload.ItemName>{file.name}</FileUpload.ItemName>
-          <FileUpload.ItemActions>
-            <Button.Root
-              variant="ghost"
-              tone="neutral"
-              aria-label={`Удалить ${file.name}`}
-              onClick={() => setFiles([])}
-            >
-              <Button.Icon>
-                <Icon name="action.close" />
-              </Button.Icon>
-            </Button.Root>
-          </FileUpload.ItemActions>
-        </FileUpload.Item>
-      ))}
       <FileUpload.Root label="Доверенность" optional hint="Если подписывает не директор" />
     </div>
   );

package/src/components/file-upload/examples/variants.tsx

@@ -1,13 +1,32 @@
-/** The dashed drop line next to a zone with only the fill, for cards and modals — `variant`. */
-import { FileUpload } from "prime-ui-kit";
+/** 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 after the files — `variant`, `trigger`. */
+import { FileUpload, type FileUploadFile } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
 
+const PHOTOS: readonly FileUploadFile[] = [
+  {
+    id: "dock",
+    name: "Рампа.jpg",
+    type: "image/jpeg",
+    size: 412_000,
+    src: "https://picsum.photos/seed/variants-dock/320/320",
+  },
+  {
+    id: "racks",
+    name: "Стеллажи.jpg",
+    type: "image/jpeg",
+    size: 388_000,
+    src: "https://picsum.photos/seed/variants-racks/320/320",
+  },
+];
+
 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" defaultValue={PHOTOS} />
     </div>
   );
 }

package/src/components/gallery/COMPONENT.md

@@ -0,0 +1,151 @@
+# Gallery
+
+**Category:** messages
+**Kind:** primitive
+
+> Photos and videos as a messenger album: one, or up to ten laid out from their aspect ratios alone, every box final before a byte loads; a tile opens the album in MediaViewer.
+
+## When to use
+- The media of a chat message — `Message.Media` is a Gallery its message shapes.
+- Photos and videos attached anywhere else: a post in a feed, a comment, a report on a task, the attachments of a ticket.
+- Media on its way, either way: an upload with its share and cancel, a failed one with a retry, a received one waiting to be fetched.
+
+## When not to use
+- One picture of an object in a list or a card (a product, a document) → [Thumbnail](../thumbnail/COMPONENT.md).
+- Picking and ordering files before they are sent → [FileUpload](../file-upload/COMPONENT.md) (its `grid` gallery) or the Composer's tray.
+- A full-screen viewer on its own (a product's photos from a button) → [MediaViewer](../media-viewer/COMPONENT.md); the gallery opens it for you.
+- A grid of many images to browse (a media library) → a CSS grid of `Thumbnail`s.
+
+## Import
+```tsx
+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
+├─ 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)
+│  ├─ open button            over the whole tile («Открыть: {alt}», aria-haspopup="dialog")
+│  └─ transfer disk          the shared disk in the middle while the tile is on its way (internal/transferDisk)
+├─ children                  laid over every tile (a message's meta pill)
+└─ MediaViewer               the album full-screen (`viewer`), opened by a tile, closing back into it
+```
+The layout is a pure function of the items' ratios (`layout.ts`, `layoutGallery`): each item's ratio is kept between a tall portrait and a wide panorama (0.5…2 in an album, 0.6…1.8 alone), its orientation is read (wide, narrow, about square), and the shape is picked as a messenger does — two wide ones of one shape stacked, two alike side by side, two different ones sharing one height by their ratios; three with a tall first one as that one beside a column of two, otherwise a wide one over two; four the same with three; five to ten in rows, the partition (up to four rows of up to four) that comes closest to a square, penalised for very short rows and for more items above fewer. Nothing is measured: the tiles stand absolutely at fractions of the gallery's box, which keeps its aspect ratio.
+
+An item (`GalleryItem`) is `type` (`"image"` by default, or `"video"`), `src`, an optional `poster` and `alt`, its natural `width` / `height` (the ratio that lays the album out and reserves every box before load), a video's `duration` before its metadata loads, and its transfer — `transfer`, `transferProgress`, `transferDirection`, the same shape as every transferring part.
+
+## API
+
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+### Gallery
+`ref` → `HTMLDivElement`. Photos and videos as a messenger album: one, or 2–10 laid out from their aspect ratios alone, every box final before anything loads. A tile opens the album in `MediaViewer`; a tile on its way shows the shared transfer disk.
+
+| 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. |
+| `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). |
+| `onOpenChange` | `(open: boolean) => void` | — | A tile opened the viewer (`true`), or the viewer closed (`false`). |
+| `index` | `number` | — | The item the viewer shows (controlled); a tile sets it to its own. |
+| `defaultIndex` | `number` | `0` | The item shown first (uncontrolled). |
+| `onIndexChange` | `(index: number) => void` | — | A tile was activated, or the viewer turned its page: the item now shown. |
+| `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. |
+| `children` | `ReactNode` | — | Laid over the gallery, above every tile (a caption pill, a message's time). |
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `className` and the other attributes. |
+
+## Variants
+
+### layout
+Decided by the items, not a prop: the number of items and their ratios.
+
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| one | the item at its own ratio; a portrait narrower than the cap, its height reaching it | a single photo or video | |
+| two | side by side at one height, or stacked when both are wide and alike | a pair | |
+| three · four | a tall first one beside a column, or a wide first one over a row | a small album | |
+| five–ten | rows, fewer items above more, close to a square | a large album | |
+
+### Flags
+| Prop | Effect |
+|---|---|
+| `viewer` | the album opens in `MediaViewer` (default) with the whole album as its set: arrows and swipes page, a video plays inside, pictures zoom, Escape closes; `false` — your own viewer from `onOpenChange` / `onIndexChange` |
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| 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 |
+| 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 |
+| done | `transfer="done"` | the disk fades and shrinks away (`fast`), the picture returns to full |
+| viewing | a tile pressed, Enter on it, or `open` | `MediaViewer` grows out of the tile at that item (`getOrigin`), the whole album its set; it closes back into the tile showing the item on screen, and the focus returns to the tile |
+
+## 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.
+
+## Accessibility
+
+### Keyboard
+| 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
+- 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.
+
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+| Key | Default | Used for |
+|---|---|---|
+| `open` | `"Открыть: {name}"` | Gallery: the name of a tile that opens the viewer; `{name}` is `alt`, else `photo` / `video`. |
+| `photo` | `"фото"` | Gallery: `{name}` of a photo without `alt`. |
+| `video` | `"видео"` | Gallery: `{name}` of a video without `alt`. |
+| `cancelUpload` | `"Отменить отправку"` | Gallery: the cross while sending. |
+| `cancelDownload` | `"Отменить загрузку"` | Gallery: the cross while receiving. |
+| `retryUpload` | `"Повторить отправку"` | Gallery: the retry after a failed send. |
+| `retryDownload` | `"Повторить загрузку"` | Gallery: the retry after a failed receive. |
+| `uploadProgress` | `"Отправка {percent}%"` | Gallery: the share while sending — the description of the cross. |
+| `downloadProgress` | `"Загрузка {percent}%"` | Gallery: the share while receiving — the description of the cross. |
+| `notSent` | `"Не отправилось"` | Gallery: why a send failed — the retry's description. |
+| `notReceived` | `"Не загрузилось"` | Gallery: why a receive failed — the retry's description. |
+| `download` | `"Скачать {name}"` | Gallery: the download arrow of a `remote` tile; `{name}` is its `alt` or `photo` / `video`. |
+| `cancelFailed` | `"Не удалось отменить"` | Gallery: announced when `onCancel` rejected. |
+| `retryFailed` | `"Не удалось повторить"` | Gallery: announced when `onRetry` rejected. |
+| `downloadFailed` | `"Не удалось скачать"` | Gallery: announced when `onDownload` rejected. |
+
+## 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`. |
+| [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-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
+- A CSS grid of your own for an album → `Gallery items`: the messenger layout from the ratios, every box final before load.
+- Items without `width` / `height` → each tile falls back to 4 : 3 and the layout guesses; pass the natural size so the album is laid out right and never shifts.
+- Measuring images to lay them out → nothing to measure: the layout is computed from the data.
+- A rounded wrapper with `overflow: hidden` around it → the gallery rounds its own corners.
+- A video that autoplays in a tile → the tile shows its first frame; it plays in the viewer.
+- A lightbox of your own around the gallery → the gallery opens `MediaViewer` itself; control it with `open` / `index`, or `viewer={false}` for a viewer of your own.
+- A progress bar or a spinner of your own over an uploading picture → `transfer` and `transferProgress` on the item (`transfer={item.status}`, `transferProgress={item.progress}` of a `useUploadQueue` item): the shared transfer disk.
+- 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)
+- **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/controlled-open.tsx

@@ -0,0 +1,39 @@
+/** 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`. */
+import { Button, Gallery, type GalleryItem, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+const REPORT: GalleryItem[] = [
+  { src: "https://picsum.photos/seed/act-1/800/600", width: 800, height: 600, alt: "Акт, стр. 1" },
+  { src: "https://picsum.photos/seed/act-2/600/800", width: 600, height: 800, alt: "Акт, стр. 2" },
+  { src: "https://picsum.photos/seed/act-3/800/600", width: 800, height: 600, alt: "Повреждение" },
+  { src: "https://picsum.photos/seed/act-4/800/800", width: 800, height: 800, alt: "Пломба" },
+];
+
+export default function GalleryControlledOpenExample() {
+  const [open, setOpen] = React.useState(false);
+  const [index, setIndex] = React.useState(0);
+  return (
+    <>
+      <Gallery
+        items={REPORT}
+        open={open}
+        onOpenChange={setOpen}
+        index={index}
+        onIndexChange={setIndex}
+      />
+      <Button.Root
+        variant="soft"
+        tone="neutral"
+        onClick={() => {
+          setIndex(2);
+          setOpen(true);
+        }}
+      >
+        Показать повреждение
+      </Button.Root>
+      <Typography as="span" variant="caption" tone="muted">
+        Последнее открытое: {REPORT[index]?.alt}
+      </Typography>
+    </>
+  );
+}

package/src/components/gallery/examples/examples.module.css

@@ -0,0 +1,14 @@
+/* overview.tsx: the switcher above the gallery it re-lays out, one column. */
+.stage {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: var(--prime-space-4);
+  inline-size: 100%;
+  min-inline-size: 0;
+}
+
+/* Both keep to the column: a wider switcher scrolls instead of wrapping, the gallery narrows. */
+.fit {
+  max-inline-size: 100%;
+}

package/src/components/gallery/examples/overview.tsx

@@ -0,0 +1,52 @@
+/** 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";
+
+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 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>
+  );
+}