prime-ui-kit 0.7.13 → 0.9.1

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

@@ -1,250 +1,215 @@
 # FileUpload
 
-**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+**Category:** inputs
+**Kind:** field
 
-## Canonical
+> A file drop zone with the field label, hint and error, plus file rows for the selected files.
 
-- **Назначение:** зона выбора файла — внешний **`label`**, скрытый **`input type="file"`**, клик по зоне открывает системный диалог; поддерживаются **drag-and-drop** и **`data-dragover`** на корне.
-- **Импорт:** `import { FileUpload } from "prime-ui-kit"`.
-- **Минимальный сценарий:** `<FileUpload.Root />` — встроенные `Icon`, `Title`, `Hint`, `BrowseLabel`.
-- **Ключевые пропы корня:** `accept`, `multiple`, `disabled`, `onFilesChange(files: File[])`, `appearance` (`"dashed"` \| `"solid"`), `size` (`"s"` \| `"m"` \| `"l"` \| `"xl"`), `inputRef` для программного `click()`.
-- **Контракт:** после каждого выбора или drop значение input **сбрасывается**, чтобы повторный выбор того же файла снова вызвал `onFilesChange`. Список файлов и загрузка на сервер — **на стороне приложения**.
+## When to use
+- Attaching documents, images or media to a form or a request.
+- A drop target that also opens the system file dialog on click or Enter / Space.
+- Showing selected files with size, upload progress, a remove action or a retry after an error.
+- A custom drop target around another element (e.g. a round zone around an Avatar).
 
-## Extended
-
-### About
-
-Composable UI for choosing files: a `label` wrapping a hidden `input type="file"`, optional drag-and-drop styling, and building blocks for per-file rows (badge, name/meta, progress, actions).
-
-**When to use**
-
-- A visible drop zone plus native picker, with `accept`, `multiple`, and optional `disabled`.
-- Drag-and-drop and click on the same target, with `onFilesChange` to feed app or server logic.
-- Lists of uploads styled as cards with `FormatBadge`, typography slots, and optional `ItemProgress`.
-- Dense modal layouts using `DropBody`, `Title`, `BrowseLink`, `ActionsRow`, and `Chip`, often with `inputRef` to open the dialog from nested controls.
-
-**When not to use**
-
-- A headless file field with no shared drop-zone affordance (use a plain `input` or minimal markup).
-- Built-in upload, scanning, or storage integration (only UI and `File[]` callbacks).
-- Automatic list state or remove/retry semantics inside the kit (`Item` is presentational).
-- Scenarios where a non-`label` activation pattern is required without rethinking focus and hit targets.
-
-### Composition
-
-- **`FileUpload.Root`** — outer `label`, hidden file `input`, `ControlSizeProvider` for descendants. Omit `children` to get the default inner layout (`Icon`, `Title`, `Hint`, `BrowseLabel`). Replace `children` with `DropBody` / `Title` / `BrowseLink` / `ActionsRow` / `Chip` / `ChipLabel` for custom copy; use `inputRef` + `click()` from `BrowseLink` or `Chip` handlers because those elements stop propagation to the `label`.
-- **File row** — `FileUpload.Item` (optional `variant`, `size`) → `ItemRow` → `FormatBadge` and `ItemMain`. Inside `ItemMain`, use `ItemTextGroup` with `ItemName` / `ItemMeta` / `ItemMetaSep`, or `ItemStack` with `ItemTryAgain` for error layouts; optional `ItemActions`. Below the row, optional `ItemProgress` (bar when `value` is set and `children` omitted) or `ItemFooter`.
-
-### Playground snippets
-
-Демо совпадают по порядку и смыслу с **`playground/sections/FileUploadSection.tsx`**. Исходники с импортами **`@/`** лежат в **`playground/snippets/file-upload/`**:
-
-| Блок | Файл | Содержание |
-|------|------|------------|
-| **Размеры** | [`sizes.tsx`](../../../playground/snippets/file-upload/sizes.tsx) (+ [`sizes.module.css`](../../../playground/snippets/file-upload/sizes.module.css)) | Сетка **`FileUpload.Root`** с **`size`** `s`–`xl` и такие же **`FileUpload.Item`** с **`FormatBadge`**, индикатором в **`ItemName`**, **`ItemProgress`** с **`value`**. |
-| **Варианты** | [`variants.tsx`](../../../playground/snippets/file-upload/variants.tsx) (+ [`variants.module.css`](../../../playground/snippets/file-upload/variants.module.css)) | У корня **`appearance`** **`dashed`** / **`solid`**; у карточки **`variant`** **`default`** / **`error`**. |
-| **Состояния** | [`states.tsx`](../../../playground/snippets/file-upload/states.tsx) (+ [`states.module.css`](../../../playground/snippets/file-upload/states.module.css)) | Обычная и **`disabled`** зона; карточки с прогрессом, успехом и ошибкой (**`ItemStack`** + **`ItemTryAgain`**). Подсветка при перетаскивании — **`data-dragover`** на **`Root`**. |
-| **Контролируемый режим** | [`controlled.tsx`](../../../playground/snippets/file-upload/controlled.tsx) | **`onFilesChange`**, **`multiple`**, **`accept`**; список имён и сброс через [Button](../button/COMPONENT.md). |
-| **Композиция** | [`composition.tsx`](../../../playground/snippets/file-upload/composition.tsx) (+ [`composition.module.css`](../../../playground/snippets/file-upload/composition.module.css)) | **`DropBody`**, **`Title tone="muted"`**, **`BrowseLink`**, **`ActionsRow`** / **`Chip`** / **`ChipLabel`**, общий **`inputRef`** для программного **`click()`**. |
-| **Full width** | [`full-width.tsx`](../../../playground/snippets/file-upload/full-width.tsx) (+ [`full-width.module.css`](../../../playground/snippets/file-upload/full-width.module.css)) | **`Root`** на всю ширину родителя (колонка формы). |
-| **Свой контент и accept** | [`custom-children.tsx`](../../../playground/snippets/file-upload/custom-children.tsx) (+ [`custom-children.module.css`](../../../playground/snippets/file-upload/custom-children.module.css)) | Замена тела зоны через **`children`**, **`accept="image/*"`**. |
-| **Круглая зона** | [`circle-modal.tsx`](../../../playground/snippets/file-upload/circle-modal.tsx) (+ [`circle-modal.module.css`](../../../playground/snippets/file-upload/circle-modal.module.css)) | Круглый контейнер (CSS), **`DropBody`**, внешняя кнопка загрузки с тем же **`inputRef`**. |
-| **Список с аватаром** | [`avatar-rows.tsx`](../../../playground/snippets/file-upload/avatar-rows.tsx) | Макет строки профиля (**`Avatar`**, кнопки). **`FileUpload` в сниппете не рендерится** — в приложении при необходимости свяжите кнопки с общим **`inputRef`**. |
-
-### Scenarios (recipes)
-
-Готовые рецепты с импортом **`prime-ui-kit`** — **`examples/*.tsx`**. Лестницы размеров/состояний и разметка модалок — в **Playground snippets** выше.
-
-| Файл | Идея | Связь со сниппетами |
-|------|------|---------------------|
-| [`examples/controlled-list.tsx`](examples/controlled-list.tsx) | Контролируемый список с **`Item`**, удаление по строке, очистка всего. | Расширяет [`controlled.tsx`](../../../playground/snippets/file-upload/controlled.tsx) карточками и действиями. |
-| [`examples/drag-area.tsx`](examples/drag-area.tsx) | **`DropBody`**, **`BrowseLink`**, **`inputRef`**, счётчик последнего выбора. | Упрощённая композиция рядом с [`composition.tsx`](../../../playground/snippets/file-upload/composition.tsx) (без **`ActionsRow`** / **`Chip`**). |
-| [`examples/document-attach.tsx`](examples/document-attach.tsx) | Вложения: **`multiple`**, фильтр типов, список **`Item`**. | Тематически близко к композиции и контролируемому режиму; визуальные паттерны карточек см. **Размеры** / **Состояния** в плейграунде. |
-| [`examples/avatar-upload.tsx`](examples/avatar-upload.tsx) | Одно изображение, превью [Avatar](../avatar/COMPONENT.md), **`URL.createObjectURL`**. | См. [`circle-modal.tsx`](../../../playground/snippets/file-upload/circle-modal.tsx) для круглой зоны и внешней кнопки. |
-| [`examples/full-width.tsx`](examples/full-width.tsx) | Колонка формы: зона на всю ширину родителя. | Зеркало [`full-width.tsx`](../../../playground/snippets/file-upload/full-width.tsx) для потребителей пакета. |
-| [`examples/custom-children.tsx`](examples/custom-children.tsx) | **`children`** вместо дефолтного тела, **`accept`** для изображений. | Зеркало [`custom-children.tsx`](../../../playground/snippets/file-upload/custom-children.tsx) для потребителей пакета. |
-
-### Minimal example
+## When not to use
+- Uploading is a single secondary action in a toolbar → use a [Button](../button/COMPONENT.md) that calls `inputRef.current?.click()` on a hidden zone, or a native input.
+- Showing only progress without picking files → use [ProgressBar](../progress-bar/COMPONENT.md).
+- A «nothing uploaded yet» page state with a call to action → use [EmptyPage](../empty-page/COMPONENT.md).
 
+## Import
 ```tsx
 import { FileUpload } from "prime-ui-kit";
-
-export function Example() {
-  return <FileUpload.Root />;
-}
 ```
 
-### Rules
-
-- After each change or drop, `onFilesChange` receives a `File[]`; the input’s value is cleared so selecting the same file again still fires the callback.
-- When `disabled` is set, the input is disabled, drops are ignored, and `data-disabled` is set on the `label` (`aria-disabled` is mirrored on the input).
-- While a drag hovers the zone, the root `label` has `data-dragover` for styling.
-- `BrowseLink` and `Chip` call `preventDefault` and `stopPropagation` on click — they do not open the picker unless you call `inputRef.current?.click()`.
-- `FileUpload.Icon` and `FileUpload.FormatBadge` set `aria-hidden`; expose file meaning in visible text (e.g. `ItemName` / `ItemMeta`).
-- `ItemProgress` renders `ProgressBar.Root` when `value` is defined and `children` are omitted; with no `value` and no `children`, only the empty wrapper is present.
-- `DropBody` uses `pointer-events: none` on the wrapper so nested controls must remain interactive via nested `pointer-events` (as in the module styles).
+## Anatomy
+```
+FileUpload.Root                 field frame: label → drop zone → hint | error
+└─ <label> drop zone            visually hidden <input type="file">; built-in body or children
+   └─ FileUpload.Body           custom body column
+      ├─ FileUpload.Icon        round tinted icon slot
+      ├─ FileUpload.Title       zone title (`<LinkButton asChild><button>` inside for an inline link)
+      └─ FileUpload.Description secondary line (the kit Hint)
+
+FileUpload.Item                 file row
+├─ FileUpload.FormatBadge       square kit Badge with the extension
+├─ FileUpload.ItemName          one line, truncated
+├─ FileUpload.ItemDescription   size, progress or error
+├─ FileUpload.ItemActions       remove / retry buttons (kit Button)
+└─ FileUpload.ItemProgress      the kit ProgressBar across the row
+```
+The built-in body (icon, `labels.title`, `labels.description` and a decorative soft Button) renders when there are no children.
 
 ## API
 
-### FileUpload.Root
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| size | `FileUploadSize` (`"s" \| "m" \| "l" \| "xl"`) | `"m"` | No | Tokens for the zone, built-in icon, and hint context. |
-| appearance | `FileUploadAppearance` (`"dashed" \| "solid"`) | `"dashed"` | No | Dashed vs solid border and field-like background. |
-| inputRef | `React.Ref<HTMLInputElement>` | — | No | Ref to the hidden input (e.g. programmatic `click()`). |
-| accept | `string` | — | No | Native `accept`. |
-| multiple | `boolean` | — | No | Multi-select in the file dialog. |
-| disabled | `boolean` | — | No | Disables input and drops. |
-| onFilesChange | `(files: File[]) => void` | — | No | Called after picker change or drop. |
-| children | `React.ReactNode` | — | No | Replaces the default drop-zone body. |
-| className | `string` | — | No | Class on the `label`. |
-| …rest | `Omit<React.LabelHTMLAttributes<HTMLLabelElement>, "children">` | — | No | `id`, `htmlFor`, ARIA, and other label attributes. |
+### FileUpload.Root
+`ref` → `HTMLDivElement` (the field frame). The field frame (label → zone → hint | error) around a `<label>` drop zone with a visually hidden file input. Field-root rule: `className`, `ref` and the rest go to the frame; `id` and `aria-label` to the file input.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `variant` | `"dashed" \| "solid"` | `"dashed"` | `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 and hint. Without it the tier of its host (a form, a panel), else `m`. |
+| `label` | `ReactNode` | — | Field label above the zone; names the file input. |
+| `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 zone. Hidden while `error` is shown. |
+| `error` | `ReactNode` | — | Error message under the zone (a rejected file); implies `invalid`. |
+| `invalid` | `boolean` | — | Danger line and icon, `aria-invalid` on the input. A non-empty `error` implies it. |
+| `disabled` | `boolean` | `false` | Blocks picking and drag-and-drop. |
+| `accept` | `string` | — | Native `accept` of the file input. |
+| `multiple` | `boolean` | — | Allows several files at once. |
+| `name` | `string` | — | Name of the file input inside a form. |
+| `onFilesChange` | `(files: File[]) => void` | — | Called with the picked or dropped files; the input is reset, so the same file can be picked again. |
+| `inputRef` | `Ref<HTMLInputElement>` | — | The hidden file input, e.g. to open the picker from a button. |
+| `id` | `string` | — | Id of the file input; hint id is `<id>-hint`, error id is `<id>-error`. |
+| `labels` | `Partial<FileUploadLabels>` | — | Built-in strings, see Labels. |
+| `children` | `ReactNode` | — | Custom body (`FileUpload.Body`); replaces the built-in icon, title, description and button. |
+| `aria-label` | `string` | — | Name of the file input when there is no `label`. |
+| `…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.
 
 ### FileUpload.Icon
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| className | `string` | — | No | Wrapper class. |
-| children | `React.ReactNode` | — | No | Icon or other content. |
-| …rest | `React.HTMLAttributes<HTMLSpanElement>` | — | No | Passed to `span` (`aria-hidden` is set on the component). |
+`ref` → `HTMLSpanElement`. A round tinted icon slot (`aria-hidden`) that turns accent on drag-over and danger when invalid. Native `<span>` props.
 
 ### FileUpload.Title
+`ref` → `HTMLParagraphElement`. The zone title `<p>`. Native `<p>` props.
 
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| tone | `"default" \| "muted"` | `"default"` | No | Text emphasis. |
-| className | `string` | — | No | Class on the `p`. |
-| children | `React.ReactNode` | — | No | Title text. |
-| …rest | `React.HTMLAttributes<HTMLParagraphElement>` | — | No | Other paragraph attributes. |
-
-### FileUpload.Hint
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| className | `string` | — | No | Class passed to `Hint.Root`. |
-| children | `React.ReactNode` | — | No | Hint content. |
-| …rest | `React.HTMLAttributes<HTMLParagraphElement>` | — | No | Forwarded into `Hint.Root`; size follows `Root` context. |
-
-### FileUpload.BrowseLabel
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| className | `string` | — | No | `span` class. |
-| children | `React.ReactNode` | — | No | Browse chip label. |
-| …rest | `React.HTMLAttributes<HTMLSpanElement>` | — | No | Other `span` attributes. |
-
-### FileUpload.BrowseLink
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| type | `"button" \| "submit" \| "reset"` | `"button"` | No | Button `type`. |
-| className | `string` | — | No | Class on the `button`. |
-| onClick | `React.MouseEventHandler<HTMLButtonElement>` | — | No | Invoked after `preventDefault` / `stopPropagation`. |
-| children | `React.ReactNode` | — | No | Link text. |
-| …rest | `React.ButtonHTMLAttributes<HTMLButtonElement>` | — | No | Other button attributes. |
-
-### FileUpload.DropBody
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| className | `string` | — | No | Column wrapper class. |
-| children | `React.ReactNode` | — | No | Custom layout. |
-| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | `div` attributes. |
-
-### FileUpload.ActionsRow
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| className | `string` | — | No | Row class. |
-| children | `React.ReactNode` | — | No | Chips or other actions. |
-| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | `div` attributes. |
-
-### FileUpload.Chip
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| type | `"button" \| "submit" \| "reset"` | `"button"` | No | Button `type`. |
-| className | `string` | — | No | Class on the `button`. |
-| onClick | `React.MouseEventHandler<HTMLButtonElement>` | — | No | Invoked after `preventDefault` / `stopPropagation`. |
-| children | `React.ReactNode` | — | No | Chip contents (e.g. icon + `ChipLabel`). |
-| …rest | `React.ButtonHTMLAttributes<HTMLButtonElement>` | — | No | Other button attributes. |
-
-### FileUpload.ChipLabel
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| className | `string` | — | No | Class on the `span`. |
-| children | `React.ReactNode` | — | No | Chip text. |
-| …rest | `React.HTMLAttributes<HTMLSpanElement>` | — | No | `span` attributes. |
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `tone` | `"default" \| "muted"` | `"default"` | `muted` — secondary color, regular weight (an instruction line in custom bodies). |
 
-### FileUpload.FormatBadge
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| format | `string` | — | Yes | Source string; trimmed, truncated, and uppercased for display. |
-| color | `FileUploadFormatBadgeColor` | `"gray"` | No | Badge palette (`gray`, `red`, `blue`, `green`, `orange`, `purple`, `sky`, `yellow`). |
-| className | `string` | — | No | Extra class on the `span`. |
+### FileUpload.Description
+`ref` → `HTMLParagraphElement`. The secondary zone line (formats, size limit), the kit Hint of the zone tier. Native `<p>` props.
 
 ### 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.
 
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| variant | `FileUploadItemVariant` (`"default" \| "error"`) | `"default"` | No | Card emphasis. |
-| size | `FileUploadSize` | `"m"` | No | Card and inline scale. |
-| className | `string` | — | No | Container class. |
-| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | `div` attributes. |
-
-### FileUpload.ItemRow, ItemMain, ItemStack, ItemTextGroup, ItemName, ItemMeta, ItemActions, ItemFooter
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| className | `string` | — | No | Extra class. |
-| children | `React.ReactNode` | — | No | Nested markup. |
-| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | `div` attributes. |
-
-### FileUpload.ItemMetaSep
+| 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`. |
+| `invalid` | `boolean` | `false` | A failed upload: danger wash and ring, danger description. |
 
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| className | `string` | — | No | `span` class. |
-| children | `React.ReactNode` | — | No | Avoid relying on `children`; the glyph is fixed. |
-| …rest | `React.HTMLAttributes<HTMLSpanElement>` | — | No | Passed to `span` (`aria-hidden`). |
+### FileUpload.FormatBadge
+`ref` → `HTMLSpanElement`. The file format as a square kit Badge of the row tier (`aria-hidden`: the name carries the extension).
 
-### FileUpload.ItemTryAgain
+| 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. |
 
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| type | `"button" \| "submit" \| "reset"` | `"button"` | No | Button `type`. |
-| className | `string` | — | No | Class on the `button`. |
-| children | `React.ReactNode` | — | No | Label. |
-| …rest | `React.ButtonHTMLAttributes<HTMLButtonElement>` | — | No | Other button attributes. |
+### 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.ItemProgress
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| value | `number` | — | No | When set and `children` omitted, renders `ProgressBar.Root`. |
-| max | `number` | — | No | Progress maximum (passed to `ProgressBar.Root`). |
-| className | `string` | — | No | Wrapper class. |
-| children | `React.ReactNode` | — | No | Custom indicator instead of the bar. |
+`ref` → `HTMLDivElement` (the wrapper). Upload progress across the row: the kit ProgressBar.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `value` | `number` | — (required) | Uploaded amount. |
+| `max` | `number` | — | Total amount (ProgressBar default). |
+| `aria-label` | `string` | `«Загрузка файла»` | Accessible name of the bar (not the wrapper); name the file. |
+| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children">` | — | `className` and the other attributes of the wrapper. |
+
+## Variants
+
+### variant (FileUpload.Root)
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `dashed` | field fill with a 1px dashed line; hover darkens fill and line | a standalone drop zone on a page — the dashed line is the «drop here» affordance | yes |
+| `solid` | field fill only; the danger / accent line appears only when invalid / on drag-over | inside cards, modals and drawers; custom zones (avatar) | |
+
+### size
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `xs` | zone padding 16, icon circle 28, browse 28, title 12/16; row badge 28 | compact attachment field in dense forms | |
+| `s` | padding 20, icon 32, browse 32, title 13/20; badge 32 | side panels, small dialogs | |
+| `m` | padding 24, icon 36, browse 36, title 14/20; badge 36 | regular forms | yes |
+| `l` | padding 32, icon 40, browse 40, title 16/24; badge 40 | the main upload area of a page | |
+| `xl` | padding 40, icon 48, browse 48, title 16/24; badge 48 | full-page or onboarding upload | |
+
+**Sizes:** `size` on Root and on Item are separate; use the same tier for a zone and its rows.
+
+### tone (FileUpload.Title)
+| 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 | |
+
+### Flags
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `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 | uploading is unavailable | `false` |
+
+**Combinations**
+- Recommended: `variant="solid"` inside Card / Modal; `error` on Root explaining the rule; an invalid Item with a retry Button in `ItemActions`.
+- Pointless: `labels` together with `children` (the built-in texts are ignored); `invalid` with `disabled`.
+- One drop zone per form section; the submit action lives outside the zone.
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| hover | — | zone fill and dashed line darken |
+| focus | keyboard focus on the hidden input | inset focus ring on the zone (danger when invalid); Enter / Space opens the dialog |
+| drag-over | a file dragged over the zone | `data-state="active"` on the zone: accent line, accent soft fill, accent icon |
+| invalid | `invalid` or a non-empty `error` | `data-invalid="true"` on the zone, `aria-invalid` on the input; `data-invalid="true"` on Item |
+| disabled | `disabled` | `data-disabled="true"`, disabled input, disabled fill and text, drops ignored |
+
+Also `data-size`, `data-variant` on the zone and `data-size` on Item. Files are not kept by the component: keep the list in your state and update it in `onFilesChange`.
+
+## Layout & spacing
+- The zone and Item are `width: 100%`; the parent sets the width. Label → zone and zone → hint use the tier `label-gap` / `hint-gap`.
+- Zone → first file row and row → row: `--prime-space-2`.
+- A custom zone can hug its content (avatar zone: a root `className` with `width: fit-content`, `--file-upload-radius: var(--prime-radius-full)` and a small `--file-upload-padding`).
+
+## Accessibility
+
+### Keyboard
+| Key | Action |
+|---|---|
+| `Tab` | Focuses the hidden file input (the zone shows the ring), then the buttons of the file rows. |
+| `Enter` · `Space` | Opens the system file dialog. |
+
+### ARIA
+- 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.
+- `FileUpload.Icon` and `FormatBadge` are `aria-hidden`: the file name and description carry the meaning.
+- Icon-only remove buttons in `ItemActions` need an `aria-label` with the file name.
+
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+| Key | Default | Used for |
+|---|---|---|
+| `title` | `"Выберите файл или перетащите его сюда"` | Title of the built-in zone body. |
+| `description` | `"JPEG, PNG, PDF, MP4 до 50 МБ"` | Description of the built-in body; an empty string hides it. |
+| `browse` | `"Выбрать файл"` | Text of the decorative browse button of the built-in body. |
+| `optional` | `"необязательно"` | Marker after the label when `optional`. |
+
+## Examples
+| Example | Shows |
+|---|---|
+| [overview.tsx](examples/overview.tsx) | Attachments of a request: a labelled drop zone and the chosen files as rows with a remove button — `label`, `hint`, `multiple`, `onFilesChange`, `FileUpload.Item`. |
+| [variants.tsx](examples/variants.tsx) | The dashed drop line next to a zone with only the fill, for cards and modals — `variant`. |
+| [sizes.tsx](examples/sizes.tsx) | Every size of the zone and of a file row: padding, icon, button and text follow the tier — `size`. |
+| [states.tsx](examples/states.tsx) | A default zone, a disabled one and an invalid one without a message — `disabled`, `invalid`. |
+| [validation.tsx](examples/validation.tsx) | A required zone with a hint, a rejected file whose error replaces the hint and an optional zone — `required`, `hint`, `error`, `optional`. |
+| [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`. |
+| [upload-progress.tsx](examples/upload-progress.tsx) | File rows while uploading, uploaded and failed with a retry — `FileUpload.ItemProgress`, `invalid`, `FileUpload.ItemActions`. |
+| [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`. |
+| [in-form.tsx](examples/in-form.tsx) | A contract upload form: the required scan is checked on submit and its error replaces the hint — `required`, `error`, `name`. |
+| [narrow.tsx](examples/narrow.tsx) | In a phone-width column the zone text wraps and a long file name truncates. |
+
+## 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={…}>`.
+- `labels.hint` → the built-in secondary line is `labels.description`; `hint` is the field hint under the zone.
 
 ## Related
-
-- [Button](../button/COMPONENT.md) — actions that call `inputRef.current?.click()`, clear lists, or sit in `ItemActions`.
-- [Hint](../hint/COMPONENT.md) — underlying primitive for `FileUpload.Hint`.
-- [ProgressBar](../progress-bar/COMPONENT.md) — used inside `ItemProgress` when `value` is provided without custom `children`.
-- [Label](../label/COMPONENT.md) — pairing copy with the zone in forms.
-- [Avatar](../avatar/COMPONENT.md) — image preview next to upload actions on profile-style screens.
-- [Divider](../divider/COMPONENT.md) — separating rows in attachment lists.
-
-## LLM note
-
-- **Namespace:** `FileUpload` object; entry point for picking files is **`FileUpload.Root`** (`<label>` + hidden `<input type="file">`).
-- **Callbacks:** `onFilesChange(File[])` after native change or drop; input value reset after each emit.
-- **Drag state:** `data-dragover` on root while over; `data-disabled` when `disabled`.
-- **Nested buttons:** `BrowseLink` / `Chip` do not bubble to label — use **`inputRef`** and `inputRef.current?.click()` to open the file dialog.
-- **Presentation rows:** `FileUpload.Item` subtree (`ItemRow`, `FormatBadge`, `ItemMain`, `ItemProgress`, …) does not manage data; bind to app state yourself.
-- **Appearances:** `appearance` on Root: `dashed` (default) vs `solid` (embedded / modal-style).
-- **A11y:** `FormatBadge` and default icon wrapper are `aria-hidden`; file identity belongs in `ItemName` / visible text.
-- **Playground vs recipes:** полная сетка демо и порядок блоков — **`playground/snippets/file-upload/*.tsx`** и **`FileUploadSection.tsx`**; копипаст под продукт — **`examples/*.tsx`** (см. таблицы **Playground snippets** и **Scenarios (recipes)**).
+- **Built from:** [Label](../label/COMPONENT.md) (`label`), [Hint](../hint/COMPONENT.md) (`hint`, `error`, `Description`), [Button](../button/COMPONENT.md) (built-in browse button), [LinkButton](../link-button/COMPONENT.md) (inline browse link in a custom body), [Badge](../badge/COMPONENT.md) (`FormatBadge`), [ProgressBar](../progress-bar/COMPONENT.md) (`ItemProgress`), `Icon`
+- **See also:** [Avatar](../avatar/COMPONENT.md), [EmptyPage](../empty-page/COMPONENT.md)

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

@@ -1,53 +1,55 @@
-import { Avatar, FileUpload } from "prime-ui-kit";
+/** 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";
 import * as React from "react";
 
-/**
- * Аватар: одно фото, превью через Avatar и object URL.
- * В проде не забывайте вызывать URL.revokeObjectURL при смене/сбросе файла.
- */
-export function FileUploadAvatarUploadExample() {
-  const [previewUrl, setPreviewUrl] = React.useState<string | null>(null);
+import styles from "./examples.module.css";
+
+export default function FileUploadAvatarUploadExample() {
+  const inputRef = React.useRef<HTMLInputElement>(null);
+  const [preview, setPreview] = React.useState<string | null>(null);
 
   React.useEffect(() => {
     return () => {
-      if (previewUrl) {
-        URL.revokeObjectURL(previewUrl);
-      }
+      if (preview) URL.revokeObjectURL(preview);
     };
-  }, [previewUrl]);
+  }, [preview]);
 
   return (
-    <div
-      style={{
-        display: "flex",
-        flexDirection: "column",
-        gap: "var(--prime-sys-spacing-l)",
-        maxWidth: 320,
-      }}
-    >
-      <div style={{ display: "flex", alignItems: "center", gap: "var(--prime-sys-spacing-m)" }}>
-        <Avatar.Root size="xl">
-          {previewUrl ? <Avatar.Image src={previewUrl} alt="Предпросмотр аватара" /> : null}
-          <Avatar.Fallback>U</Avatar.Fallback>
+    <div className={styles.avatarRow}>
+      <FileUpload.Root
+        inputRef={inputRef}
+        accept="image/png,image/jpeg"
+        variant="solid"
+        className={styles.avatarZone}
+        aria-label="Загрузить фото профиля"
+        onFilesChange={([file]) => {
+          if (file) setPreview(URL.createObjectURL(file));
+        }}
+      >
+        <Avatar.Root size="2xl">
+          {preview ? <Avatar.Image src={preview} alt="" /> : null}
+          <Avatar.Fallback>АК</Avatar.Fallback>
         </Avatar.Root>
-        <FileUpload.Root
-          accept="image/jpeg,image/png,image/webp"
-          onFilesChange={(files) => {
-            const file = files[0];
-            setPreviewUrl((prev) => {
-              if (prev) {
-                URL.revokeObjectURL(prev);
-              }
-              return file ? URL.createObjectURL(file) : null;
-            });
-          }}
-        >
-          <FileUpload.DropBody>
-            <FileUpload.Title>Загрузить фото</FileUpload.Title>
-            <FileUpload.Hint>PNG или JPEG, до 5 МБ</FileUpload.Hint>
-            <FileUpload.BrowseLabel>Нажмите или перетащите файл</FileUpload.BrowseLabel>
-          </FileUpload.DropBody>
-        </FileUpload.Root>
+      </FileUpload.Root>
+      <div className={styles.avatarText}>
+        <div className={styles.avatarCopy}>
+          <Typography as="p" variant="title-s">
+            Фото профиля
+          </Typography>
+          <Typography as="p" variant="body-s" tone="secondary">
+            PNG или JPG, не меньше 400×400 px. Можно перетащить на аватар.
+          </Typography>
+        </div>
+        <div className={styles.avatarActions}>
+          <Button.Root variant="soft" tone="neutral" onClick={() => inputRef.current?.click()}>
+            {preview ? "Заменить" : "Загрузить"}
+          </Button.Root>
+          {preview ? (
+            <Button.Root variant="ghost" tone="danger" onClick={() => setPreview(null)}>
+              Удалить
+            </Button.Root>
+          ) : null}
+        </div>
       </div>
     </div>
   );

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

@@ -0,0 +1,44 @@
+/** 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";
+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();
+
+  return (
+    <div className={styles.column}>
+      <FileUpload.Root label="Сканы документов" inputRef={inputRef} variant="solid" multiple>
+        <FileUpload.Body>
+          <FileUpload.Icon>
+            <Icon name="action.upload" tone="secondary" />
+          </FileUpload.Icon>
+          <FileUpload.Title tone="muted">
+            Перетащите файлы сюда или{" "}
+            <LinkButton asChild>
+              <button type="button" onClick={openPicker}>
+                выберите на компьютере
+              </button>
+            </LinkButton>
+          </FileUpload.Title>
+          <div className={styles.sources}>
+            <Button.Root variant="soft" tone="neutral" size="s" onClick={openPicker}>
+              <Button.Icon>
+                <Icon name="nav.layoutGrid" />
+              </Button.Icon>
+              Из галереи
+            </Button.Root>
+            <Button.Root variant="soft" tone="neutral" size="s" onClick={openPicker}>
+              <Button.Icon>
+                <Icon name="field.email" />
+              </Button.Icon>
+              Из почты
+            </Button.Root>
+          </div>
+        </FileUpload.Body>
+      </FileUpload.Root>
+    </div>
+  );
+}