prime-ui-kit 0.14.0 → 0.16.0

package/src/components/field-list/examples/sizes.tsx

@@ -1,5 +1,5 @@
 /** Every tier: the headings, the fields, the handle and the buttons follow the list's size — `size`. */
-import { FieldList, type FieldListColumn, Input } from "prime-ui-kit";
+import { FieldList, type FieldListColumn, Input, Typography } from "prime-ui-kit";
 
 type Contact = { id: string; name: string; phone: string };
 
@@ -11,32 +11,38 @@ const CONTACTS: Contact[] = [{ id: "buyer", name: "Анна Лебедева", p
 
 export default function FieldListSizesExample() {
   return (
-    <>
+    <div>
       {SIZES.map((size) => (
-        <FieldList
-          key={size}
-          size={size}
-          label={size}
-          columns={COLUMNS}
-          defaultValue={CONTACTS}
-          getId={(contact) => contact.id}
-          getLabel={(contact) => contact.name}
-          renderItem={(contact) => (
-            <>
-              <Input.Root>
-                <Input.Wrapper>
-                  <Input.Field defaultValue={contact.name} />
-                </Input.Wrapper>
-              </Input.Root>
-              <Input.Root>
-                <Input.Wrapper>
-                  <Input.Field type="tel" defaultValue={contact.phone} />
-                </Input.Wrapper>
-              </Input.Root>
-            </>
-          )}
-        />
+        <div key={size}>
+          <div>
+            <FieldList
+              size={size}
+              label="Контакты покупателя"
+              columns={COLUMNS}
+              defaultValue={CONTACTS}
+              getId={(contact) => contact.id}
+              getLabel={(contact) => contact.name}
+              renderItem={(contact) => (
+                <>
+                  <Input.Root>
+                    <Input.Wrapper>
+                      <Input.Field defaultValue={contact.name} />
+                    </Input.Wrapper>
+                  </Input.Root>
+                  <Input.Root>
+                    <Input.Wrapper>
+                      <Input.Field type="tel" defaultValue={contact.phone} />
+                    </Input.Wrapper>
+                  </Input.Root>
+                </>
+              )}
+            />
+            <Typography as="span" variant="caption" tone="muted">
+              {size}
+            </Typography>
+          </div>
+        </div>
       ))}
-    </>
+    </div>
   );
 }

package/src/components/field-list/examples/states.tsx

@@ -1,5 +1,5 @@
 /** The same list editable and disabled while the request saves it: fields, handles and buttons turn off together — `disabled`. */
-import { FieldList, type FieldListColumn, Input } from "prime-ui-kit";
+import { FieldList, type FieldListColumn, Input, Typography } from "prime-ui-kit";
 
 type Stage = { id: string; name: string; days: string };
 
@@ -11,41 +11,47 @@ const STAGES: Stage[] = [
 ];
 
 const STATES = [
-  { label: "Этапы проекта", disabled: false },
-  { label: "disabled", disabled: true },
+  { caption: "default", disabled: false },
+  { caption: "disabled", disabled: true },
 ];
 
 export default function FieldListStatesExample() {
   return (
-    <>
+    <div>
       {STATES.map((state) => (
-        <FieldList
-          key={state.label}
-          label={state.label}
-          disabled={state.disabled}
-          reorderable
-          columns={COLUMNS}
-          defaultValue={STAGES}
-          getId={(stage) => stage.id}
-          getLabel={(stage) => stage.name}
-          createItem={() => ({ id: crypto.randomUUID(), name: "", days: "" })}
-          addLabel="Добавить этап"
-          renderItem={(stage) => (
-            <>
-              <Input.Root>
-                <Input.Wrapper>
-                  <Input.Field defaultValue={stage.name} />
-                </Input.Wrapper>
-              </Input.Root>
-              <Input.Root>
-                <Input.Wrapper>
-                  <Input.Field defaultValue={stage.days} inputMode="numeric" />
-                </Input.Wrapper>
-              </Input.Root>
-            </>
-          )}
-        />
+        <div key={state.caption}>
+          <div>
+            <FieldList
+              label="Этапы проекта"
+              disabled={state.disabled}
+              reorderable
+              columns={COLUMNS}
+              defaultValue={STAGES}
+              getId={(stage) => stage.id}
+              getLabel={(stage) => stage.name}
+              createItem={() => ({ id: crypto.randomUUID(), name: "", days: "" })}
+              addLabel="Добавить этап"
+              renderItem={(stage) => (
+                <>
+                  <Input.Root>
+                    <Input.Wrapper>
+                      <Input.Field defaultValue={stage.name} />
+                    </Input.Wrapper>
+                  </Input.Root>
+                  <Input.Root>
+                    <Input.Wrapper>
+                      <Input.Field defaultValue={stage.days} inputMode="numeric" />
+                    </Input.Wrapper>
+                  </Input.Root>
+                </>
+              )}
+            />
+            <Typography as="span" variant="caption" tone="muted">
+              {state.caption}
+            </Typography>
+          </div>
+        </div>
       ))}
-    </>
+    </div>
   );
 }

package/src/components/fieldset/COMPONENT.md

@@ -9,12 +9,13 @@
 - A long form split into groups («Реквизиты», «Контакты», «Уведомления»), each with a heading 16 above its fields.
 - Disabling every field of a form while its request runs: `disabled` on the group instead of `disabled` on each field.
 - A group that needs a native name for assistive tech (`<legend>`), e.g. a set of switches under one heading.
+- Without `label`: the plain field column of a form — the fields 20 apart and one `disabled` for all of them, instead of a hand-made stack.
 
 ## When not to use
 - One choice among options with a heading → [Radio](../radio/COMPONENT.md) `Radio.Group label`, a [SegmentedControl](../segmented-control/COMPONENT.md) or [ButtonGroup](../button-group/COMPONENT.md) `label`.
 - A bounded block with a surface (a settings panel) → [Card](../card/COMPONENT.md) `Card.Root`; a Fieldset inside it groups the fields.
 - A page section with a title and actions → [PageContent](../page-content/COMPONENT.md) sections.
-- A group of settings with a title and a trailing control (a «Сбросить» button, a master switch) → `Card.Root variant="panel"` with `Card.Header` (`Card.Title` + the control) and the Fieldset in `Card.Body`, named by the title (`aria-labelledby`), as the settings page pattern names its Fieldset by the section heading.
+- A group of settings with a title and a trailing control (a «Сбросить» button, a master switch) → `Card.Root variant="panel"` with `Card.Header` (`Card.Title` + the control) and the Fieldset in `Card.Body`, named by the title (`aria-labelledby`).
 - A single field's label → the field's own `label`.
 
 ## Import
@@ -40,7 +41,7 @@ A leaf: everything is a prop or a child. A row of two fields inside is the consu
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `label` | `ReactNode` | — | Group heading in the native `<legend>` (`title-s`); it names the group for assistive tech. Without it give the fieldset an `aria-label` when the group needs a name. |
+| `label` | `ReactNode` | — | Group heading in the native `<legend>` (`title-s`), the group name. Without it the fieldset is the plain field column of a form; give it an `aria-label` when the group needs a name. |
 | `description` | `ReactNode` | — | Secondary text under the heading (`body-s`, secondary), linked through `aria-describedby`. |
 | `disabled` | `boolean` | `false` | Disables every control inside, native and kit (they take their own disabled look, ARIA and keyboard); nested groups inherit it. Use it while the form's request runs. |
 | `children` | `ReactNode` | — (required) | The fields, stacked 20 apart; a row of two fields is the consumer's grid. |
@@ -56,7 +57,7 @@ Fieldset has no `variant`, `tone` or `size`: fields keep their own tier (or the
 
 **Combinations**
 - Recommended: groups 32 apart in the form, a `label` on each; `disabled={saving}` on every group and `loading` on the submit button outside them.
-- Allowed but rare: no `label` — a group only for `disabled`; give it an `aria-label` when the group itself needs a name.
+- Allowed: no `label` — the plain field column of a form (the rhythm and `disabled` without a heading); give it an `aria-label` when the group itself needs a name.
 - Pointless: a description without a heading.
 - Forbidden: a border, padding or fill added to the group — the group is made by proximity; use a Card when it needs a surface.
 
@@ -69,17 +70,21 @@ A Button inside a disabled group is disabled too (it reads the same context), so
 
 ## Layout & spacing
 - Heading → fields `--prime-space-4` (16); heading → description `--prime-space-1` (4); description → fields `--prime-space-4`; field → field `--prime-space-5` (20).
-- Group → group `--prime-space-8` (32) — set by the form around the groups.
+- Group → group 32 — set by the form around the groups.
 - `width: 100%`, `min-width: 0` (the native fieldset's `min-content` minimum is reset), so long values never widen the form.
 
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 | Key | Action |
 |---|---|
 | `Tab` | Moves through the group's fields; the fields of a disabled group are skipped. |
 
 ### ARIA
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 - The native `<fieldset>` is a group (`role="group"`) named by the `<legend>` text from `label`; without a heading give it `aria-label`.
 - `description` is linked to the group through `aria-describedby`.
 - `disabled` disables the native controls inside and passes a context to kit controls: they set their own `disabled` / `aria-disabled` and drop out of the Tab order.
@@ -105,4 +110,4 @@ No `labels`.
 
 ## Related
 - **Built from:** —
-- **See also:** [Card](../card/COMPONENT.md) (a surface around the groups), [Input](../input/COMPONENT.md) (takes its disabled look from the group), [Button](../button/COMPONENT.md) (the submit with `loading`, outside the group), [LoginForm](../login-form/COMPONENT.md) (its fields wrapped in `Fieldset disabled` while signing in), [Radio](../radio/COMPONENT.md)
+- **See also:** [Card](../card/COMPONENT.md) (a surface around the groups), [Input](../input/COMPONENT.md) (takes its disabled look from the group), [Button](../button/COMPONENT.md) (the submit with `loading`, outside the group), [Radio](../radio/COMPONENT.md)

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

@@ -5,7 +5,7 @@
   display: flex;
   flex-direction: column;
   gap: var(--prime-space-8);
-  width: min(100%, var(--prime-modal-width-s));
+  width: min(100%, var(--prime-layout-form-width-s));
 }
 
 .actions {

package/src/components/file-upload/COMPONENT.md

@@ -47,6 +47,7 @@ FileUpload.Root                 field frame: label → trigger → files → hin
 │     ├─ FileUpload.Title       zone title (`<LinkButton asChild><button>` inside for an inline link)
 │     └─ FileUpload.Description secondary line (the kit Hint)
 ├─ Button                       trigger="button": kit Button that opens the picker; children are its content
+├─ (nothing)                    trigger="none": only the hidden <input type="file"> that picker.open clicks
 └─ files                        `value` then the uploads of `queue` (nothing while empty, unless an add tile)
    ├─ layout="list"             <ul> of rows drawn from the FileUpload.Item parts; the add tile as the last row
    └─ layout="grid" | "strip"   Dnd.Sortable <ul> of square tiles, the same slots on every kind:
@@ -59,9 +60,9 @@ FileUpload.Root                 field frame: label → trigger → files → hin
 FileUpload.Queue                the same files with no trigger of their own (a tray whose paperclip lives elsewhere)
 
 FileUpload.Item                 a file row the set does not draw (own actions, a server-side job)
-├─ FileUpload.FormatBadge       square kit Badge with the extension
+├─ FileUpload.FormatBadge       square kit Thumbnail labelled with the extension
 │  or FileUpload.ItemPreview    square kit Thumbnail of an image file
-├─ FileUpload.ItemName          one line, truncated (the set passes the name without its extension when a format badge shows it)
+├─ FileUpload.ItemText          one line, truncated (the set passes the name without its extension when a format badge shows it)
 ├─ FileUpload.ItemDescription   size, progress or error
 ├─ FileUpload.ItemActions       buttons at the end of the row (kit Button)
 └─ FileUpload.ItemProgress      the kit ProgressBar across the row
@@ -105,29 +106,30 @@ A rejection of `upload` fails the file with its message as the reason; retry que
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `trigger` | `"dropzone" \| "button" \| "tile"` | `"dropzone"` | `dropzone`: the drop area. `button`: a compact picker button, no zone and no drop (a composer paperclip). `tile`: an add tile as the last cell of the files. |
+| `trigger` | `"dropzone" \| "button" \| "tile" \| "none"` | `"dropzone"` | `dropzone`: the drop area. `button`: a compact picker button, no drop. `tile`: an add tile after the files. `none`: no trigger, the picker opens from code (`picker`). |
 | `variant` | `"dashed" \| "solid"` | `"dashed"` | The look of the drop zone: `dashed` shows the drop line; `solid` keeps only the fill (cards, modals). |
-| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `host tier, else "m"` | Tier of the zone padding, icon, title, button, label, hint and the rows. Without it the tier of its host (a form, a panel), else `m`. Tiles keep their own size. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | host tier, else `"m"` | Tier of the zone padding, icon, title, button, label, hint and the rows. Without it the tier of its host (a form, a panel), else `m`. Tiles keep their own size. |
 | `value` | `readonly FileUploadFile[]` | — | Files in their order (controlled): `{ id, name, size?, type?, src?, alt?, href? }` — on the server or uploads of `queue` by id. `src`: picture or video; `alt` spoken for the name; `href` links name or tile to the file. |
 | `defaultValue` | `readonly FileUploadFile[]` | `[]` | Initial files (uncontrolled). |
 | `onValueChange` | `(value: readonly FileUploadFile[]) => void \| Promise<void>` | — | The set changed (a reorder, a removal, files added to `queue`), with the whole new list. Return the save's promise: the touched files wait busy, a rejection puts the set back and is announced. |
 | `queue` | `Pick<UploadQueue, "items" \| "retry" \| "remove"> & Partial<Pick<UploadQueue, "add" \| "move">>` | — | The uploads: `useUploadQueue(…)` or an object of that shape. Each file on its way shows its upload; removing a file aborts it. With `add`, picked and dropped files go into the queue. |
 | `layout` | `"list" \| "grid" \| "strip"` | `"list"` | `list`: a row per file. `grid`: square tiles that wrap to the set's width and reorder. `strip`: one sideways-scrolling row of tiles (an attachment tray). |
 | `cover` | `boolean` | `false` | Tiles only: the first file is the cover («Обложка», 2 × 2 in a `grid`). Reordering a file to the first place makes it the cover. |
-| `formatSize` | `(bytes: number) => string` | `Russian digits, Б · КБ · МБ · ГБ` | Display of a file size («820 КБ», «1,2 МБ»). |
+| `formatSize` | `(bytes: number) => string` | Russian digits, Б · КБ · МБ · ГБ | Display of a file size («820 КБ», «1,2 МБ»). |
 | `label` | `ReactNode` | — | Field label above the trigger; names the file input and the list of files. |
 | `required` | `boolean` | — | Red `*` after the label and native `required` on the input. |
 | `optional` | `boolean` | — | Muted marker right after the label text (`labels.optional`). |
 | `hint` | `ReactNode` | — | Help text under the field. Hidden while `error` is shown. |
 | `error` | `ReactNode` | — | Error message under the field (a rejected file, too few files); implies `invalid`. |
 | `invalid` | `boolean` | — | Danger line and icon of the zone, `aria-invalid` on the input. A non-empty `error` implies it. |
+| `focusRing` | `boolean` | `true` | `false` hides only the visual focus ring of the drop zone and the add tile (`data-focus-ring="false"`); focus, keyboard and ARIA stay. The picker Button keeps its ring. |
 | `disabled` | `boolean` | `false` | Blocks picking and drag-and-drop; the files are read-only: no add tile, no reorder, no remove. |
 | `accept` | `string` | — | Native `accept` of the file input; dropped files outside it are not taken (MIME type, `type/*` or `.ext`; a file with no MIME type by its extension). |
 | `multiple` | `boolean` | — | Allows several files at once in the picker. |
 | `max` | `number` | — | Most files in the set: picked and dropped files are cut to the room left; the add tile counts `count из max` (the digits roll) and at the limit says «Лимит файлов» and takes nothing. |
 | `name` | `string` | — | Name of the file input inside a form. |
 | `onFilesChange` | `(files: File[]) => void` | — | Called with the picked or dropped files (of `accept`, cut to `max`); the input is reset, so the same file can be picked again. Not called when `queue.add` takes them. |
-| `inputRef` | `Ref<HTMLInputElement>` | — | The hidden file input, e.g. to open the picker from a button. |
+| `picker` | `Ref<{ open: (options?: { accept?: string }) => void }>` | — | Opens the file picker from code (a custom body button, a menu item): `open()`, or `open({ accept })` for one pick of other types that also filter its files. A disabled or full field does not open. |
 | `id` | `string` | — | Id of the file input (generated when omitted); hint id is `<id>-hint`, error id is `<id>-error`. |
 | `labels` | `Partial<FileUploadLabels>` | — | Built-in strings, see Labels. |
 | `children` | `ReactNode` | — | A zone: a custom body (`FileUpload.Body`) instead of the built-in one. `trigger="button"`: the button's content, `Button.Icon` and text (default: the paperclip and `labels.browse`). |
@@ -135,20 +137,33 @@ A rejection of `upload` fails the file with its message as the reason; retry que
 | `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "id" \| "children" \| "defaultValue" \| "defaultChecked" \| "onChange">` | — | `className`, `data-*` and the other attributes of the field frame `<div>`. The zone reads `--file-upload-padding` and `--file-upload-radius` from that class (a round zone around an avatar). |
 
 ### FileUpload.Body
-`ref` → `HTMLDivElement`. A centered column for a custom zone body; nested buttons and links stay interactive (drag-over follows enter / leave depth, so crossing children never flickers it). Native `<div>` props.
+`ref` → `HTMLDivElement`. A centered column for a custom zone body; nested buttons and links stay interactive (drag-over follows enter / leave depth, so crossing children never flickers it).
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children`, `className` and the other div attributes. |
 
 ### FileUpload.Icon
-`ref` → `HTMLSpanElement`. A round tinted icon slot (`aria-hidden`) that turns accent on drag-over and danger when invalid. Native `<span>` props.
+`ref` → `HTMLSpanElement`. A round tinted icon slot (`aria-hidden`) that turns accent on drag-over and danger when invalid.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLSpanElement>` | — | `children` (the `Icon`), `className` and the other span attributes. |
 
 ### FileUpload.Title
-`ref` → `HTMLParagraphElement`. The zone title `<p>`. Native `<p>` props.
+`ref` → `HTMLParagraphElement`. The zone title `<p>`.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `tone` | `"default" \| "muted"` | `"default"` | `muted` — secondary color, regular weight (an instruction line in custom bodies). |
+| `tone` | `"default" \| "secondary"` | `"default"` | `secondary` — secondary color, regular weight (an instruction line in custom bodies). |
+| `…rest` | `HTMLAttributes<HTMLParagraphElement>` | — | `children`, `className` and the other paragraph attributes. |
 
 ### FileUpload.Description
-`ref` → `HTMLParagraphElement`. The secondary zone line (formats, size limit), the kit Hint of the zone tier. Native `<p>` props.
+`ref` → `HTMLParagraphElement`. The secondary zone line (formats, size limit), the kit Hint of the zone tier.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLParagraphElement>` | — | `children`, `className` and the other paragraph attributes. |
 
 ### FileUpload.Queue
 `ref` → `HTMLUListElement`. The files of a set with no picker of its own — a tray whose paperclip lives elsewhere: the same rows or tiles `FileUpload.Root` draws, in a `<ul>` (nothing while empty).
@@ -161,27 +176,28 @@ A rejection of `upload` fails the file with its message as the reason; retry que
 | `queue` | `Pick<UploadQueue, "items" \| "retry" \| "remove"> & Partial<Pick<UploadQueue, "add" \| "move">>` | — | The uploads: `useUploadQueue(…)` or an object of that shape. Each file on its way shows its upload; removing a file aborts it. With `add`, picked and dropped files go into the queue. |
 | `layout` | `"list" \| "grid" \| "strip"` | `"list"` | `list`: a row per file. `grid`: square tiles that wrap to the set's width and reorder. `strip`: one sideways-scrolling row of tiles (an attachment tray). |
 | `cover` | `boolean` | `false` | Tiles only: the first file is the cover («Обложка», 2 × 2 in a `grid`). Reordering a file to the first place makes it the cover. |
-| `formatSize` | `(bytes: number) => string` | `Russian digits, Б · КБ · МБ · ГБ` | Display of a file size («820 КБ», «1,2 МБ»). |
+| `formatSize` | `(bytes: number) => string` | Russian digits, Б · КБ · МБ · ГБ | Display of a file size («820 КБ», «1,2 МБ»). |
 | `disabled` | `boolean` | `false` | Read-only files: no reorder, no remove. |
 | `labels` | `Partial<FileUploadLabels>` | — | Row and tile strings, see Labels. |
 | `…rest` | `Omit<HTMLAttributes<HTMLUListElement>, "children" \| "defaultValue">` | — | `className`, `aria-label` (name the list) and the other attributes of the `<ul>`. |
 
 ### FileUpload.Item
-`ref` → `HTMLDivElement`. A file row: format badge · name over description · actions, then the progress bar; children are placed by their part. Native `<div>` props.
+`ref` → `HTMLDivElement`. A file row: format badge · name over description · actions, then the progress bar; children are placed by their part.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `host tier, else "m"` | Tier of the padding, text and the format badge. Without it the tier of its host, else `m`. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | host tier, else `"m"` | Tier of the padding, text and the format badge. Without it the tier of its host, else `m`. |
 | `invalid` | `boolean` | `false` | A failed upload: danger wash and ring, danger description. |
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children` (the item parts), `className` and the other div attributes. |
 
 ### FileUpload.FormatBadge
-`ref` → `HTMLSpanElement`. The file format as a square kit Badge of the row tier (`aria-hidden`: the row's name is trimmed of the extension and the accessible name carries it whole).
+`ref` → `HTMLDivElement`. The file format as the short label of a square kit Thumbnail of the row tier, where an image file shows its picture (`aria-hidden`: the accessible name carries the extension).
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `format` | `string` | — (required) | File extension; shown upper-case, cut to 8 characters. |
-| `color` | `"gray" \| "blue" \| "green" \| "orange" \| "red" \| "yellow" \| "purple" \| "sky" \| "pink" \| "teal"` | `"gray"` | Palette hue of the badge. |
-| `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children" \| "color">` | — | `className` and the other attributes of the badge. |
+| `color` | `"gray" \| "blue" \| "green" \| "orange" \| "red" \| "yellow" \| "purple" \| "sky" \| "pink" \| "teal"` | `"gray"` | Palette hue of the tile. |
+| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children" \| "color">` | — | `className` and the other attributes of the tile. |
 
 ### FileUpload.ItemPreview
 `ref` → `HTMLDivElement`. An image file's picture in place of the format badge: a square kit Thumbnail of the row tier (`aria-hidden`: the name names the file), the image icon while it loads or if it fails.
@@ -191,8 +207,12 @@ A rejection of `upload` fails the file with its message as the reason; retry que
 | `src` | `string` | — (required) | The picture: a URL, or the local `preview` of a queued file. |
 | `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children" \| "color">` | — | `className` and the other attributes of the thumbnail frame. |
 
-### FileUpload.ItemName · FileUpload.ItemDescription · FileUpload.ItemActions
-`ref` → `HTMLDivElement`. The file name (one line, truncated), its description (size, progress, error; danger in an invalid row) and the buttons at the end of the row. Native `<div>` props.
+### FileUpload.ItemText · FileUpload.ItemDescription · FileUpload.ItemActions
+`ref` → `HTMLDivElement`. The file name (one line, truncated), its description (size, progress, error; danger in an invalid row) and the buttons at the end of the row.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children`, `className` and the other div attributes. |
 
 ### FileUpload.ItemProgress
 `ref` → `HTMLDivElement` (the wrapper). Upload progress across the row: the kit ProgressBar.
@@ -202,17 +222,26 @@ A rejection of `upload` fails the file with its message as the reason; retry que
 | `value` | `number` | — (required) | Uploaded amount. |
 | `max` | `number` | — | Total amount (ProgressBar default). |
 | `tone` | `"accent" \| "neutral" \| "success" \| "warning" \| "danger" \| "info"` | `"accent"` | Fill color: `success` for a finished file, `danger` where a failed one stopped. |
-| `aria-label` | `string` | `«Загрузка файла»` | Accessible name of the bar (not the wrapper); name the file. |
+| `aria-label` | `string` | `labels.upload` | Accessible name of the bar (not the wrapper); name the file. |
 | `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children">` | — | `className` and the other attributes of the wrapper. |
 
-### useUploadQueue
-`useUploadQueue<TResult>({ upload, concurrency })` → `{ items, add, retry, remove, clear, move }`. The upload queue of FileUpload: `concurrency` files go at once through `upload`, the rest wait as `queued`; each has its progress, error and retry.
+### Types
 
-| Prop | Type | Default | Description |
+#### `UploadQueueOptions<TResult>`
+The argument of `useUploadQueue(options)`.
+
+| Field | Type | Default | Description |
 |---|---|---|---|
 | `upload` | `(file: File, context: { id: string; signal: AbortSignal; onProgress: (progress: number) => void }) => Promise<TResult>` | — (required) | Sends one file: progress through `onProgress` (0…1), stop on `signal`, resolve with the answer (`result`), reject to fail. `id` is the item: after-upload work runs here once the request resolves. |
 | `concurrency` | `number` | `3` | How many files upload at once; the rest wait as `queued`. |
 
+### Functions
+
+#### `useUploadQueue(options)`
+`<TResult>(options: UploadQueueOptions<TResult>) => UploadQueue<TResult>`
+
+The upload queue of FileUpload: `concurrency` files go at once through `upload`, the rest wait as `queued`; each has its progress, error and retry. Returns `{ items, add, retry, remove, clear, move }`.
+
 ## Variants
 
 ### trigger (FileUpload.Root)
@@ -221,6 +250,7 @@ A rejection of `upload` fails the file with its message as the reason; retry que
 | `dropzone` | the drop area with an icon, a title, a description and a decorative browse button, the files under it | a standalone upload field of a form; documents | yes |
 | `button` | a kit Button of the tier, no zone and no drop: soft with the paperclip and text, ghost when its content is a `Button.Icon` alone | a composer's paperclip, an «attach» action in a toolbar or a dense form; pair it with `FileUpload.Queue` when the files live elsewhere | |
 | `tile` | a dashed add tile — «+», «Добавить», `count из max` — as the last cell of the files; the whole row while empty; files drop anywhere on the set | file cards and the image gallery: files are added where they will lie | |
+| `none` | nothing of its own: a hidden file input that `picker.open({ accept })` clicks, no drop | a menu of attachment kinds whose items each open the picker with their own types (`Composer.Attach` with `Composer.Item`) | |
 
 ### variant (FileUpload.Root)
 | Value | Looks like | Use when | Default |
@@ -256,7 +286,7 @@ A rejection of `upload` fails the file with its message as the reason; retry que
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
 | `default` | primary text, medium weight | the main line of the zone | yes |
-| `muted` | secondary text, regular weight | an instruction sentence with an inline `LinkButton asChild` button | |
+| `secondary` | secondary text, regular weight | an instruction sentence with an inline `LinkButton asChild` button | |
 
 ### tone (FileUpload.ItemProgress)
 | Value | Looks like | Use when | Default |
@@ -272,6 +302,9 @@ A rejection of `upload` fails the file with its message as the reason; retry que
 | `invalid` (Root) | danger line and icon | a rejected file without a message; otherwise pass `error` | — |
 | `invalid` (Item) | danger soft fill, danger ring, danger description | an upload failed | `false` |
 | `disabled` | disabled fill and text, drops ignored; the files read-only | uploading is unavailable, a published set | `false` |
+| `focusRing` | `false`: the zone and the add tile draw no focus ring; focus, keys and ARIA stay | the zone sits in a host that marks focus itself | `true` |
+| `multiple` | the picker takes several files at once | a set of files rather than one | — |
+| `required` / `optional` | red `*` / muted «необязательно» after the label | Mark the minority of the form | — |
 
 **Combinations**
 - Recommended: `variant="solid"` inside Card / Modal; `error` on Root explaining the rule; `queue` on the root with `useUploadQueue`; `trigger="tile"` + `layout="grid"` + `cover` for an image gallery; `trigger="button"` + `FileUpload.Queue layout="strip"` for a tray.
@@ -288,7 +321,7 @@ A rejection of `upload` fails the file with its message as the reason; retry que
 | disabled | `disabled` | `data-disabled="true"`, disabled input, disabled fill and text, drops ignored; no add tile, actions or drag; a disabled button with `trigger="button"` |
 | empty | no files, `trigger="tile"` | the add tile spans the row with «Нажмите или перетащите файлы» |
 | cover | `cover`, the first tile | «Обложка» in place of the format pill, `data-cover` on the tiles wrapper (the first tile takes a 2 × 2 cell in a grid) |
-| full | the set reaches `max` | `data-full` on the add tile: «Лимит файлов», faded, the file input disabled |
+| full | the set reaches `max` | `data-full` on the add tile: «Лимит файлов», faded; the file input is `aria-disabled` and opens no picker, so the field label stays undimmed |
 | queued | queue item `status: "queued"` | a row reads «size · В очереди» over an empty bar; a tile (`data-upload="queued"`) dims under a 40px disk on the `media` shade (Button `shape="circle"` `variant="shade"`) whose ring turns at its least arc, described by «В очереди» |
 | loading | `status: "loading"` | a row reads «size · Загрузка 40%» and its bar fills (`accent`); a tile's white arc grows clockwise from 12 o'clock with the share sent (the `progress` ring of a shade circle Button, one variable `--ring-value`, gliding `base` while it turns); the disk is the remove («Отменить загрузку: name», described by the state), the corner × is not drawn; the tile still reorders, its carried copy keeps the disk |
 | done | `status: "done"` | a row reads «size» over a full `success` bar; a tile's ring fills, then its disk fades and shrinks to 0.9 (`fast`, `inert`), the picture returns to full or the sheet comes back |
@@ -316,6 +349,8 @@ Also `data-size`, `data-variant` on the zone, `data-size` on Item, `data-status`
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 | Key | Action |
 |---|---|
 | `Tab` | Focuses the hidden file input (the zone or the add tile shows the ring), then the files and their buttons. |
@@ -325,6 +360,8 @@ Also `data-size`, `data-variant` on the zone, `data-size` on Item, `data-status`
 | `Escape` | Cancels a tile drag in flight. |
 
 ### ARIA
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 - The zone is a `<label>` around a visually hidden but focusable `<input type="file">`. With `label` the input is named by it (`aria-labelledby`) and described by the hint or error; without it the zone text names the input — give a custom body without text an `aria-label` on Root.
 - `trigger="button"`: the kit Button takes the focus, named by the field label and its own text (or `aria-label`, required when it is an icon alone) and described by the hint or error; the input leaves the tab order.
 - `trigger="tile"`: the frame is a group named by the label; the add tile is the label of a hidden input («Добавить файлы») with the hint, the error and `aria-invalid` wired to it.
@@ -355,6 +392,7 @@ Also `data-size`, `data-variant` on the zone, `data-size` on Item, `data-status`
 | `uploading` | `"Загрузка {percent}%"` | A file in flight. |
 | `failed` | `"Не удалось загрузить"` | A failed file whose upload gave no reason. |
 | `progress` | `"Загрузка: {name}"` | Name of a row's progress bar. |
+| `upload` | `"Загрузка файла"` | Name of a `FileUpload.ItemProgress` without an `aria-label` of its own. |
 | `cancel` | `"Отменить загрузку: {name}"` | Name of the disk that cancels a tile's upload in flight. |
 | `retry` | `"Повторить загрузку: {name}"` | Name of the retry button of a failed row (the retry disk of a failed tile). |
 | `remove` | `"Убрать {name}"` | Name of the remove button of a file (it also stops an upload). |
@@ -372,25 +410,26 @@ Also `data-size`, `data-variant` on the zone, `data-size` on Item, `data-status`
 | Example | Shows |
 |---|---|
 | [overview.tsx](examples/overview.tsx) | Documents of a deal: a drop zone, the files already attached as rows whose names open them, and new files uploading through a queue with progress, a reason and a retry — `label`, `hint`, `multiple`, `defaultValue`, `href`, `queue`. |
-| [variants.tsx](examples/variants.tsx) | 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`. |
+| [variants.tsx](examples/variants.tsx) | 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`. |
 | [sizes.tsx](examples/sizes.tsx) | Every tier of the zone and of its file rows: padding, icon, button, text and the format badge follow it — `size`. |
 | [states.tsx](examples/states.tsx) | A default zone, a disabled one whose files are read-only and an invalid one without a message — `disabled`, `invalid`. |
 | [validation.tsx](examples/validation.tsx) | 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`. |
-| [gallery.tsx](examples/gallery.tsx) | An image gallery of an office listing: the first photo is the cover on two tiles and a photo dragged first takes its place, new photos upload in their tiles, and the add tile counts up to the limit — `trigger`, `layout`, `cover`, `max`, `value`, `queue`. |
-| [file-cards.tsx](examples/file-cards.tsx) | Materials of a warehouse inspection as cards: photos and documents in one grid, each with its picture or format and the name with the size; new files upload in their cards and the order is set by drag or Alt + arrows — `trigger`, `layout`, `defaultValue`, `queue`. |
+| [gallery.tsx](examples/gallery.tsx) | An image gallery of an office listing: the first photo is the cover on two tiles and a photo dragged first takes its place, new photos upload in their tiles, one fails and retries, and the add tile counts up to the limit and then says so — `trigger`, `layout`, `cover`, `max`, `value`, `queue`. |
+| [file-cards.tsx](examples/file-cards.tsx) | Materials of a warehouse inspection as cards: photos and documents in one grid, each with its picture or format and the name with the size in megabytes as the report gives it; new files upload in their cards and the order is set by drag or Alt + arrows — `trigger`, `layout`, `defaultValue`, `queue`, `formatSize`. |
 | [attachment-tray.tsx](examples/attachment-tray.tsx) | A reply to a client with a paperclip instead of a drop zone: the icon-only picker button, and the attachments as one scrolling row of tiles above the message — `trigger`, `aria-label`, `FileUpload.Queue`, `layout`. |
 | [saving.tsx](examples/saving.tsx) | 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`. |
-| [custom-body.tsx](examples/custom-body.tsx) | A custom body: a muted title with a browse link and source buttons instead of the built-in one — `FileUpload.Body`, `FileUpload.Title`. |
-| [avatar-upload.tsx](examples/avatar-upload.tsx) | A round zone around an Avatar that takes images and shows a preview; buttons open the same input — `inputRef`, `accept`, `className`. |
-| [row-parts.tsx](examples/row-parts.tsx) | 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`. |
+| [custom-body.tsx](examples/custom-body.tsx) | A custom body: a secondary title with a browse link and the formats line and source buttons instead of the built-in one; the gallery button picks only images — `FileUpload.Body`, `FileUpload.Title`, `FileUpload.Description`, `picker`. |
+| [avatar-upload.tsx](examples/avatar-upload.tsx) | A round zone around an Avatar that takes images and shows a preview; buttons open the same picker — `picker`, `accept`, `className`. |
+| [row-parts.tsx](examples/row-parts.tsx) | Rows the set does not draw, built from parts: order documents with a download button, a photo with its preview, a report still being prepared and one that failed with a retry — `FileUpload.Item`, `FileUpload.FormatBadge`, `FileUpload.ItemPreview`, `FileUpload.ItemActions`, `FileUpload.ItemProgress`, `invalid`, `tone`. |
 | [controlled.tsx](examples/controlled.tsx) | Documents of a deal in one list: the files already on the server and new uploads after them, saved on every change, and a button brings back the saved set — `value`, `onValueChange`, `queue`. |
 | [in-form.tsx](examples/in-form.tsx) | A contract upload form: submit checks the required scan, its error shakes in and leaves once a file is picked or removed — `required`, `error`, `name`, `value`. |
-| [narrow.tsx](examples/narrow.tsx) | In a phone-width column the zone text wraps, a long file name truncates, and a gallery goes three across and then two, the cover keeping two columns and the remove buttons shown without hover. |
+| [narrow.tsx](examples/narrow.tsx) | In a phone-width column the zone text wraps, a long file name truncates, and a gallery goes three across and then two, the cover keeping two columns and the remove buttons shown without hover — `layout`, `cover`. |
+| [screen.tsx](examples/screen.tsx) | 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`. |
 
 ## Mistakes
 - A `Label` and a `Hint` placed around the zone by hand → pass `label`, `hint`, `error`.
 - Nesting `FileUpload.Root` in another `<label>` → it already is one.
-- A plain `<button>` in a custom body expecting it to open the picker → call `inputRef.current?.click()` in its `onClick`; an inline «browse» link is `<LinkButton asChild><button type="button" onClick={…}>`.
+- A plain `<button>` in a custom body expecting it to open the picker → call `picker.current?.open()` in its `onClick` (`open({ accept })` for one pick of other types); an inline «browse» link is `<LinkButton asChild><button type="button" onClick={…}>`.
 - `labels.hint` → the built-in secondary line is `labels.description`; `hint` is the field hint under the zone.
 - A hand-written upload loop with its own progress, retry and abort per row → `useUploadQueue` + `queue`.
 - A zone recolored into a button for a paperclip → `trigger="button"`.
@@ -407,5 +446,5 @@ Also `data-size`, `data-variant` on the zone, `data-size` on Item, `data-status`
 - Styling a tile from an ancestor (`.gallery li`) → the carried clone is portalled to `<body>` and loses it.
 
 ## Related
-- **Built from:** [Label](../label/COMPONENT.md) (`label`), [Hint](../hint/COMPONENT.md) (`hint`, `error`, `Description`), [LinkButton](../link-button/COMPONENT.md) (a row's name with `href`), [Button](../button/COMPONENT.md) (browse button, `trigger="button"`, row and tile actions, the tile's upload disk `shape="circle"` `variant="shade"`), [Badge](../badge/COMPONENT.md) (`FormatBadge`), [Thumbnail](../thumbnail/COMPONENT.md) (`ItemPreview`, video tiles), [ProgressBar](../progress-bar/COMPONENT.md) (`ItemProgress`), [Dnd](../dnd/COMPONENT.md) and [ScrollContainer](../scroll-container/COMPONENT.md) (tiles), the shared attachment tile (`src/internal/attachmentTile`) and transfer disk (`src/internal/transferDisk`), `Icon`; the files of `queue` come from `useUploadQueue`
+- **Built from:** [Label](../label/COMPONENT.md) (`label`), [Hint](../hint/COMPONENT.md) (`hint`, `error`, `Description`), [LinkButton](../link-button/COMPONENT.md) (a row's name with `href`), [Button](../button/COMPONENT.md) (browse button, `trigger="button"`, row and tile actions, the tile's upload disk `shape="circle"` `variant="shade"`), [Badge](../badge/COMPONENT.md) (the cover pill), [Thumbnail](../thumbnail/COMPONENT.md) (`FormatBadge`, `ItemPreview`, video tiles), [ProgressBar](../progress-bar/COMPONENT.md) (`ItemProgress`), [Dnd](../dnd/COMPONENT.md) and [ScrollContainer](../scroll-container/COMPONENT.md) (tiles), the shared attachment tile (`src/internal/attachmentTile`) and transfer disk (`src/internal/transferDisk`, a [Spinner](../spinner/COMPONENT.md) while a transfer waits), `Icon`; the files of `queue` come from `useUploadQueue`, [VisuallyHidden](../visually-hidden/COMPONENT.md)
 - **See also:** [Composer](../composer/COMPONENT.md) (its attachment tray is `FileUpload.Queue layout="strip"`), [LinkButton](../link-button/COMPONENT.md) (an inline browse link in a custom body), [Avatar](../avatar/COMPONENT.md), [Thumbnail](../thumbnail/COMPONENT.md), [EmptyPage](../empty-page/COMPONENT.md)

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

@@ -1,11 +1,11 @@
-/** A round zone around an Avatar that takes images and shows a preview; buttons open the same input — `inputRef`, `accept`, `className`. */
-import { Avatar, Button, FileUpload, Typography } from "prime-ui-kit";
+/** A round zone around an Avatar that takes images and shows a preview; buttons open the same picker — `picker`, `accept`, `className`. */
+import { Avatar, Button, FileUpload, type FileUploadPicker, Typography } from "prime-ui-kit";
 import * as React from "react";
 
 import styles from "./examples.module.css";
 
 export default function FileUploadAvatarUploadExample() {
-  const inputRef = React.useRef<HTMLInputElement>(null);
+  const picker = React.useRef<FileUploadPicker>(null);
   const [preview, setPreview] = React.useState<string | null>(null);
 
   React.useEffect(() => {
@@ -17,7 +17,7 @@ export default function FileUploadAvatarUploadExample() {
   return (
     <div className={styles.avatarRow}>
       <FileUpload.Root
-        inputRef={inputRef}
+        picker={picker}
         accept="image/png,image/jpeg"
         variant="solid"
         className={styles.avatarZone}
@@ -41,7 +41,7 @@ export default function FileUploadAvatarUploadExample() {
           </Typography>
         </div>
         <div className={styles.avatarActions}>
-          <Button.Root variant="soft" tone="neutral" onClick={() => inputRef.current?.click()}>
+          <Button.Root variant="soft" tone="neutral" onClick={() => picker.current?.open()}>
             {preview ? "Заменить" : "Загрузить"}
           </Button.Root>
           {preview ? (

package/src/components/file-upload/examples/custom-body.tsx

@@ -1,21 +1,21 @@
-/** A custom body: a muted title with a browse link and source buttons instead of the built-in one — `FileUpload.Body`, `FileUpload.Title`. */
-import { Button, FileUpload, Icon, LinkButton } from "prime-ui-kit";
+/** A custom body: a secondary title with a browse link and the formats line and source buttons instead of the built-in one; the gallery button picks only images — `FileUpload.Body`, `FileUpload.Title`, `FileUpload.Description`, `picker`. */
+import { Button, FileUpload, type FileUploadPicker, Icon, LinkButton } from "prime-ui-kit";
 import * as React from "react";
 
 import styles from "./examples.module.css";
 
 export default function FileUploadCustomBodyExample() {
-  const inputRef = React.useRef<HTMLInputElement>(null);
-  const openPicker = () => inputRef.current?.click();
+  const picker = React.useRef<FileUploadPicker>(null);
+  const openPicker = () => picker.current?.open();
 
   return (
     <div className={styles.column}>
-      <FileUpload.Root label="Сканы документов" inputRef={inputRef} variant="solid" multiple>
+      <FileUpload.Root label="Сканы документов" picker={picker} variant="solid" multiple>
         <FileUpload.Body>
           <FileUpload.Icon>
             <Icon name="action.upload" tone="secondary" />
           </FileUpload.Icon>
-          <FileUpload.Title tone="muted">
+          <FileUpload.Title tone="secondary">
             Перетащите файлы сюда или{" "}
             <LinkButton asChild>
               <button type="button" onClick={openPicker}>
@@ -23,8 +23,14 @@ export default function FileUploadCustomBodyExample() {
               </button>
             </LinkButton>
           </FileUpload.Title>
+          <FileUpload.Description>PDF, JPG или PNG до 20 МБ</FileUpload.Description>
           <div className={styles.sources}>
-            <Button.Root variant="soft" tone="neutral" size="s" onClick={openPicker}>
+            <Button.Root
+              variant="soft"
+              tone="neutral"
+              size="s"
+              onClick={() => picker.current?.open({ accept: "image/*" })}
+            >
               <Button.Icon>
                 <Icon name="nav.layoutGrid" />
               </Button.Icon>