prime-ui-kit 0.9.0 → 0.9.2

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

@@ -1,19 +1,20 @@
 # FileUpload
 
 **Category:** inputs
+**Kind:** field
 
-> File picker zone with drag and drop, plus presentational parts for the list of selected files.
+> A file drop zone with the field label, hint and error, plus file rows for the selected files.
 
 ## 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.
+- 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).
 
 ## 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).
+- A «nothing uploaded yet» page state with a call to action → use [EmptyPage](../empty-page/COMPONENT.md).
 
 ## Import
 ```tsx
@@ -22,252 +23,193 @@ import { FileUpload } from "prime-ui-kit";
 
 ## Anatomy
 ```
-FileUpload.Root                     <label> with a visually hidden <input type="file">; drop target
-└─ (built-in body from `labels`) or a custom body:
-   FileUpload.DropBody              centered column, pointer-events: none
-   ├─ FileUpload.Icon               icon circle (aria-hidden)
-   ├─ FileUpload.Title              title line (tone default | muted)
-   │  └─ FileUpload.BrowseLink      inline link-button inside a title
-   ├─ FileUpload.Hint               formats / size limit (Hint of the zone tier)
-   ├─ FileUpload.BrowseLabel        decorative "browse" button (the whole zone is the target)
-   └─ FileUpload.ActionsRow         row of source chips
-      └─ FileUpload.Chip            source button
-         └─ FileUpload.ChipLabel    chip text
-
-FileUpload.Item                     one file row (outside Root)
-├─ FileUpload.ItemRow               horizontal row
-│  ├─ FileUpload.FormatBadge        extension badge
-│  ├─ FileUpload.ItemMain           text column
-│  │  ├─ FileUpload.ItemName        file name (single line, ellipsis)
-│  │  ├─ FileUpload.ItemMeta        size / status line
-│  │  │  └─ FileUpload.ItemMetaSep  "∙" separator
-│  │  └─ FileUpload.ItemStack       error column instead of name+meta
-│  │     ├─ FileUpload.ItemTextGroup  name + meta without gap
-│  │     └─ FileUpload.ItemTryAgain   retry link-button
-│  └─ FileUpload.ItemActions        trailing buttons (remove…)
-├─ FileUpload.ItemProgress          progress under the row (ProgressBar by default)
-└─ FileUpload.ItemFooter            extra full-width area under the row
+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 component does not keep a file list or upload anything: it reports picked/dropped files through `onFilesChange`, the app renders `FileUpload.Item` rows from its own state.
+The built-in body (icon, `labels.title`, `labels.description` and a decorative soft Button) renders when there are no children.
 
 ## API
 
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 ### FileUpload.Root
-`forwardRef` to `HTMLLabelElement`. + native `<label>` props except `children` (`onDragOver`, `onDragLeave`, `onDrop` are taken by the zone).
+`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 |
 |---|---|---|---|
-| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Zone padding and radius, icon circle and browse button height, title and hint size. Provided to the body via the control-size context. |
-| `variant` | `"dashed" \| "solid"` | `"dashed"` | Zone treatment, see Variants. |
-| `inputRef` | `Ref<HTMLInputElement>` | — | Ref to the hidden input, e.g. `inputRef.current?.click()` from a separate button. |
-| `accept` | `string` | — | Native `accept` of the input. Not enforced on drop — validate dropped files yourself. |
-| `multiple` | `boolean` | — | Allow several files. |
-| `disabled` | `boolean` | `false` | Disables the input and ignores drops. |
-| `invalid` | `boolean` | `false` | Danger line (or ring for `solid`), danger icon, `aria-invalid` on the input. |
-| `name` | `string` | — | Name of the hidden input inside a form. |
-| `onFilesChange` | `(files: File[]) => void` | — | Called after picking or dropping. The input value is reset afterwards, so the same file can be picked again. |
-| `labels` | `Partial<FileUploadLabels>` | see Accessibility | Texts of the built-in body (used only without `children`). |
-| `children` | `ReactNode` | — | Custom body; replaces the built-in icon, title, hint and browse button. |
-| `className` | `string` | — | Class on the `<label>`. |
+| `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
-+ native `<span>` props. Renders `aria-hidden`. Children: usually an `Icon`.
+`ref` → `HTMLSpanElement`. A round tinted icon slot (`aria-hidden`) that turns accent on drag-over and danger when invalid. Native `<span>` props.
 
 ### FileUpload.Title
-+ native `<p>` props.
+`ref` → `HTMLParagraphElement`. The zone title `<p>`. Native `<p>` props.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `tone` | `"default" \| "muted"` | `"default"` | `default`: primary text, medium weight. `muted`: secondary text, regular weight (instruction line with a `BrowseLink`). |
-
-### FileUpload.Hint
-+ native `<p>` props; renders [Hint](../hint/COMPONENT.md) `Hint.Root` with the size of the enclosing zone (`m` outside a zone).
-
-### FileUpload.BrowseLabel
-+ native `<span>` props. A neutral filled "button" of the zone tier; decorative (`pointer-events: none`), the whole zone opens the picker.
-
-### FileUpload.BrowseLink
-`forwardRef` to `HTMLButtonElement`. + native `<button>` props; `type` defaults to `"button"`. Prevents the default and stops propagation, so it does not trigger the label: open the picker in `onClick` (`inputRef.current?.click()`).
+| `tone` | `"default" \| "muted"` | `"default"` | `muted` — secondary color, regular weight (an instruction line in custom bodies). |
 
-### FileUpload.DropBody
-+ native `<div>` props. Centered column with the zone stack spacing (xs 8 · s 12 · m 16 · l 20 · xl 24); `pointer-events: none` so the label receives clicks; links, chips and action rows inside opt back in.
+### FileUpload.Description
+`ref` → `HTMLParagraphElement`. The secondary zone line (formats, size limit), the kit Hint of the zone tier. Native `<p>` props.
 
-### FileUpload.ActionsRow
-+ native `<div>` props. Wrapping, centered row of chips (`pointer-events: auto`).
-
-### FileUpload.Chip
-`forwardRef` to `HTMLButtonElement`. + native `<button>` props; `type` defaults to `"button"`. Prevents the default and stops propagation — does not open the picker by itself; handle the source in `onClick`.
-
-### FileUpload.ChipLabel
-+ native `<span>` props. Chip text in secondary color.
+### 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.
 
-### FileUpload.FormatBadge
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `format` | `string` | — (required) | Extension text; trimmed, cut to 8 characters, uppercased. |
-| `color` | `"gray" \| "blue" \| "green" \| "orange" \| "red" \| "yellow" \| "purple" \| "sky" \| "pink" \| "teal"` | `"gray"` | Palette hue. |
-| `className` | `string` | — | Class on the `<span>` (`aria-hidden`). |
+| `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. |
 
-### FileUpload.Item
-+ native `<div>` props.
+### FileUpload.FormatBadge
+`ref` → `HTMLSpanElement`. The file format as a square kit Badge of the row tier (`aria-hidden`: the name carries the extension).
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Padding, gap, name/meta typography, badge size. Not inherited from a Root — set it explicitly. |
-| `invalid` | `boolean` | `false` | Failed upload: danger soft fill, danger inset ring, danger meta text. |
-
-### FileUpload.ItemRow / ItemMain / ItemStack / ItemTextGroup / ItemName / ItemMeta / ItemActions / ItemFooter
-Each takes + native `<div>` props (`className`, `children`, …) and only adds layout and typography:
-- `ItemRow` — centered row with the item gap.
-- `ItemMain` — flexible text column, gap `--prime-space-1`.
-- `ItemStack` — flexible column, start-aligned, gap `--prime-space-2` (error text + retry).
-- `ItemTextGroup` — name + meta without gap.
-- `ItemName` — medium primary text, one line with ellipsis.
-- `ItemMeta` — muted hint-size line, tabular numbers; `<strong>` inside is medium primary; danger in an invalid item.
-- `ItemActions` — non-shrinking trailing row, gap `--prime-space-1`.
-- `ItemFooter` — full-width area.
-
-### FileUpload.ItemMetaSep
-+ native `<span>` props. Always renders `∙`, `aria-hidden` by default.
-
-### FileUpload.ItemTryAgain
-`forwardRef` to `HTMLButtonElement`. + native `<button>` props; `type` defaults to `"button"`. Underlined danger link-button in meta size.
+| `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. |
+
+### 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
+`ref` → `HTMLDivElement` (the wrapper). Upload progress across the row: the kit ProgressBar.
+
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `value` | `number` | — | Renders `ProgressBar.Root` with this value when there are no `children`. |
-| `max` | `number` | — | `max` of that ProgressBar. |
-| `children` | `ReactNode` | — | Custom indicator instead of the ProgressBar. |
-| `className` | `string` | — | Class on the wrapper. |
+| `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 `border-default` line, radius 12 (m); hover darkens fill and line | Standalone drop zone on a page or canvas — the dashed line is the "drop here" affordance | yes |
-| `solid` | Field fill only, transparent line; danger/accent line appears only for invalid / drag-over | Inside cards, modals and drawers where a dashed line is too loud; custom zones (avatar) | |
+| `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 (FileUpload.Root)
+### size
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| `xs` | Padding 16, radius 8, icon circle 28, browse 28, title 12/16 | Compact attachment field in dense forms | |
-| `s` | Padding 20, radius 8, icon circle 32, browse 32, title 13/20 | Side panels, small dialogs | |
-| `m` | Padding 24, radius 12, icon circle 36, browse 36, title 14/20 | Regular forms | yes |
-| `l` | Padding 32, radius 12, icon circle 40, browse 40, title 16/24 | Main upload area of a page | |
-| `xl` | Padding 40, radius 16, icon circle 48, browse 48, title 16/24 | Full-page or onboarding upload | |
+| `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 | |
 
-### size (FileUpload.Item)
-| Value | Looks like | Use when | Default |
-|---|---|---|---|
-| `xs` | Padding 8, radius 8, badge 28, name 12/16 | Dense lists | |
-| `s` | Padding 8, radius 8, badge 32, name 13/20 | Compact lists | |
-| `m` | Padding 12, radius 12, badge 36, name 14/20 | Regular lists | yes |
-| `l` | Padding 16, radius 12, badge 40, name 16/24 | Spacious lists | |
-| `xl` | Padding 16, gap 16, radius 16, badge 48, name 16/24 | Large upload pages | |
+**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 `BrowseLink` | |
+| `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 | |
 
-### color (FileUpload.FormatBadge)
-| Value | Looks like | Use when | Default |
-|---|---|---|---|
-| `gray` | Secondary text on a `fill-strong` wash | Unknown or generic formats | yes |
-| `red` | Red text on a translucent red wash | PDF | |
-| `blue` | Blue text on a translucent blue wash | PNG, DOC | |
-| `green` | Green text on a translucent green wash | JPG, XLS, CSV | |
-| `orange` | Orange text on a translucent orange wash | PPT, archives | |
-| `yellow` | Yellow text on a translucent yellow wash | Other format groups | |
-| `purple` | Purple text on a translucent purple wash | Video (MP4) | |
-| `sky` | Sky text on a translucent sky wash | Other format groups | |
-| `pink` | Pink text on a translucent pink wash | Other format groups | |
-| `teal` | Teal text on a translucent teal wash | Other format groups | |
-
-### invalid (Root / Item)
+### Flags
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| `false` | Normal | — | yes |
-| `true` | Root: danger line, danger icon. Item: danger soft fill, danger ring, danger meta | A file was rejected (type, size) / an upload failed | |
+| `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; `invalid` Root + custom `labels.title`/`labels.hint` explaining the rule; `invalid` Item + `ItemStack` + `ItemTryAgain`.
-- Allowed: the same `size` for the zone and the items below it.
-- Pointless: `labels` together with `children` (labels are ignored); `invalid` with `disabled`.
-- Forbidden: interactive elements in a custom body other than `BrowseLink`, `Chip`, buttons in `ActionsRow` — plain buttons inside the label would also open the picker.
-
-**Hierarchy:** one drop zone per form section; the submit action lives outside the zone (in Card actions or the form footer).
+- 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 darkens, dashed line darkens, browse button hover fill |
-| focus | keyboard focus on the hidden input | inset focus ring on the zone (danger color when invalid); Enter/Space opens the dialog |
-| drag-over | a file dragged over the zone | `data-state="active"` on Root: accent line, accent soft fill, accent icon |
-| invalid | `invalid` | `data-invalid="true"` on Root, `aria-invalid` on the input; `data-invalid="true"` on Item |
+| 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 Root, `data-size` on Item, `data-color` on FormatBadge. Files are always "uncontrolled" in the component: keep the list in your state and update it in `onFilesChange`.
+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
-- Root and Item are `width: 100%`; the parent sets the width.
-- Zone → first file row and row → row: `--prime-space-3`.
-- In a card put the zone and the list in `Card.Body`, actions in `Card.Actions`.
-- A custom zone can be shrunk around its content (avatar zone: `width: auto`).
-- Documented `className` exception: the round avatar zone ([avatar-upload.tsx](examples/avatar-upload.tsx)) is the one case where `className` on `FileUpload.Root` sets `padding: var(--prime-space-1)` and `border-radius: var(--prime-radius-full)` (plus `width: auto; flex-shrink: 0`). Everywhere else `className` is for placement only.
-- **Field frame.** FileUpload has no `label` / `hint` / `error` props, and `FileUpload.Root` is itself a `<label>` — do not nest it in another label. Put `Label.Root` as a sibling above the zone and `Hint.Root` below it (`invalid` for errors, together with `invalid` on the Root), in a grid with `gap: var(--prime-control-<size>-label-gap)` between label and zone and `var(--prime-control-<size>-hint-gap)` between zone and hint, using the zone's `size`.
+- 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
-- The zone is a `<label>` around a visually hidden but focusable `<input type="file">`: Tab focuses it, Enter/Space opens the dialog, the label text is its name. Give a custom body without text an `aria-label` on Root.
-- `FileUpload.Icon`, `FormatBadge`, `ItemMetaSep` are `aria-hidden`: the file name and meta carry the meaning.
+
+### 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` key | Default | Used for |
-|---|---|---|
-| `title` | `"Выберите файл или перетащите его сюда"` | Title of the built-in body |
-| `hint` | `"JPEG, PNG, PDF, MP4 до 50 МБ"` | Hint under the title; an empty string hides it |
-| `browse` | `"Выбрать файл"` | Text of the decorative browse button |
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
-## Examples
-| File | Scenario | When to use this pattern |
+| Key | Default | Used for |
 |---|---|---|
-| [sizes.tsx](examples/sizes.tsx) | Zone and file row on `xs`…`xl` | Picking a size |
-| [variants.tsx](examples/variants.tsx) | `dashed` vs `solid` on different surfaces | Zone on a page vs inside a card |
-| [states.tsx](examples/states.tsx) | Default, disabled, invalid zone; uploading, uploaded and failed rows | Upload feedback |
-| [file-list.tsx](examples/file-list.tsx) | `multiple` + `accept`, appending files to state, removing rows | Keeping selected files before sending |
-| [in-card.tsx](examples/in-card.tsx) | `solid` zone in a card with `DropBody`, muted `Title`, `BrowseLink`, `Chip`s and file rows | Document attachments in a request form |
-| [avatar-upload.tsx](examples/avatar-upload.tsx) | Round zone around an Avatar with preview and `inputRef` buttons | Profile photo |
-
-```tsx
-import { FileUpload } from "prime-ui-kit";
+| `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`. |
 
-export function AttachDocuments() {
-  return (
-    <FileUpload.Root
-      multiple
-      accept=".pdf,.png,.jpg"
-      labels={{ hint: "PDF, PNG или JPG до 20 МБ" }}
-      onFilesChange={(files) => console.log(files)}
-    />
-  );
-}
-```
+## 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
-- `<FileUpload.Root label="Документы" error="…">` → there are no such props; render `Label.Root` above and `Hint.Root invalid` below as siblings (see Field frame).
-- Wrapping `FileUpload.Root` in `<label>` or `Label.Root` → it is already a `<label>`; keep the Label a sibling.
-- Restyling the zone through `className` (padding, radius, fill) → use `size` / `variant`; the round avatar zone is the only documented exception.
-- Expecting the component to keep or upload files → keep `File[]` in state from `onFilesChange` and render `FileUpload.Item` rows.
-- A plain `<button>` inside the zone → use `FileUpload.Chip` / `FileUpload.BrowseLink`, they stop the click from reaching the label.
-- `FileUpload.BrowseLink` without `onClick` → it does not open the picker by itself; call `inputRef.current?.click()`.
-- Relying on `accept` for dropped files → check the type/size of dropped files and set `invalid` when rejected.
-- `size` on Root expected to size the Items → pass `size` to each `FileUpload.Item`.
-- `dashed` zone inside a card → use `variant="solid"`.
+- 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
-- [ProgressBar](../progress-bar/COMPONENT.md) — rendered by `ItemProgress`.
-- [Hint](../hint/COMPONENT.md) — rendered by `FileUpload.Hint`.
-- [Avatar](../avatar/COMPONENT.md), [Button](../button/COMPONENT.md), [Card](../card/COMPONENT.md) — used in the examples.
+- **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,4 +1,4 @@
-/** A round drop zone around an Avatar that accepts images and shows a preview; buttons open the same input via `inputRef`. Use it for profile photos. */
+/** 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";
 
@@ -33,24 +33,19 @@ export default function FileUploadAvatarUploadExample() {
       </FileUpload.Root>
       <div className={styles.avatarText}>
         <div className={styles.avatarCopy}>
-          <Typography.Root as="p" variant="title-s">
+          <Typography as="p" variant="title-s">
             Фото профиля
-          </Typography.Root>
-          <Typography.Root as="p" variant="body-s" tone="secondary">
+          </Typography>
+          <Typography as="p" variant="body-s" tone="secondary">
             PNG или JPG, не меньше 400×400 px. Можно перетащить на аватар.
-          </Typography.Root>
+          </Typography>
         </div>
         <div className={styles.avatarActions}>
-          <Button.Root
-            variant="soft"
-            tone="neutral"
-            size="s"
-            onClick={() => inputRef.current?.click()}
-          >
+          <Button.Root variant="soft" tone="neutral" onClick={() => inputRef.current?.click()}>
             {preview ? "Заменить" : "Загрузить"}
           </Button.Root>
           {preview ? (
-            <Button.Root variant="ghost" tone="danger" size="s" onClick={() => setPreview(null)}>
+            <Button.Root variant="ghost" tone="danger" onClick={() => setPreview(null)}>
               Удалить
             </Button.Root>
           ) : null}

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>
+  );
+}