prime-ui-kit 0.14.0 → 0.16.0

package/dist/components/empty-page/EmptyPage.d.ts

@@ -7,37 +7,39 @@ export type EmptyPageLabels = {
     /** Text of `EmptyPage.RetryButton`. */
     retry: string;
 };
+export declare const EMPTY_PAGE_LABELS: EmptyPageLabels;
 export type EmptyPageRootProps = React.HTMLAttributes<HTMLDivElement> & {
-    /** Control height, type and spacing tier. Default `m`. */
+    /**
+     * Icon tile, title type and padding; given to the controls inside. Without it the tier of its host, else `m`.
+     */
     size?: ControlSize;
     /**
-     * `default` — a block sized by its content.
-     * `fill` — stretches to the parent's height and centers the content (inside a table, a scroll area, a card).
-     * `compact` — a quiet state inside a menu, listbox or command list: panel padding, body-s title,
-     * caption description, a small icon and no entrance motion.
+     * `default` sizes by content; `fill` stretches to the parent's height and centers; `compact` — a quiet state inside a menu or list: smaller text and icon, no entrance motion.
      */
     layout?: EmptyPageLayout;
     /**
-     * `danger` — the region's load failed: the icon tile turns danger and the root announces itself
-     * (`role="alert"`, unless you pass a `role`). Default `neutral`.
+     * `neutral` — nothing here (yet); `danger` — the region failed to load: the icon tile turns danger and the root is `role="alert"` unless you pass a `role`.
      */
     tone?: EmptyPageTone;
+    /**
+     * Built-in strings, see Labels.
+     */
     labels?: Partial<EmptyPageLabels>;
     ref?: React.Ref<HTMLDivElement>;
 };
 /** Parts rise in on first render, except in `compact` (it appears on every keystroke). */
-declare function EmptyPageRoot({ size, layout, tone, labels, className, children, ...rest }: EmptyPageRootProps): import("react/jsx-runtime").JSX.Element;
+declare function EmptyPageRoot({ size: sizeProp, layout, tone, labels, className, children, ...rest }: EmptyPageRootProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>;
 declare namespace EmptyPageRoot {
     var displayName: string;
 }
 export type EmptyPageIconProps = React.HTMLAttributes<HTMLDivElement> & {
     /**
-     * Tile fill: `neutral`, `accent` — an invitation to start, `danger` — a failure. Default: the
-     * root's `tone`.
+     * `neutral` — no data yet, `accent` — a first run and a call to start, `danger` — a failed load.
      */
     tone?: Extract<Tone, "neutral" | "accent" | "danger">;
     ref?: React.Ref<HTMLDivElement>;
 };
+/** The kit's icon tile on the tier scale (the `compact` state takes the smallest tile). */
 declare function EmptyPageIcon({ tone: toneProp, className, ...rest }: EmptyPageIconProps): import("react/jsx-runtime").JSX.Element;
 declare namespace EmptyPageIcon {
     var displayName: string;
@@ -45,8 +47,7 @@ declare namespace EmptyPageIcon {
 type EmptyPageTitleAs = "h2" | "h3" | "h4" | "p";
 export type EmptyPageTitleProps = React.HTMLAttributes<HTMLElement> & {
     /**
-     * Tag that fits the outline; the look does not change. `p` inside menus, lists and table cells,
-     * where a heading would break the page outline.
+     * Tag that fits the outline; the look does not change. `p` inside menus, lists and table cells.
      */
     as?: EmptyPageTitleAs;
     ref?: React.Ref<HTMLElement>;
@@ -71,9 +72,7 @@ declare namespace EmptyPageActions {
 }
 export type EmptyPageRetryButtonProps = Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "onClick" | "type"> & {
     /**
-     * Loads the region again. May return a Promise: while it is pending the button shows its loading
-     * state and cannot be pressed twice. Resolve — the owner swaps the region to its data; reject —
-     * the error state stays and the button is ready again.
+     * Loads the region again. A returned Promise keeps the button loading until it settles; on reject the error state stays and the button is ready again.
      */
     onRetry: () => void | Promise<void>;
     ref?: React.Ref<HTMLButtonElement>;

package/dist/components/example-frame/ExampleFrame.d.ts

@@ -5,9 +5,11 @@ type ColorScheme = "light" | "dark";
 /**
  * Layout of the preview children, so snippets need no wrapper divs for rows and stacks.
  * `matrix`: labelled specimens — every direct child is a row, its children are cells (a specimen
- * above its caption), and cells line up in columns across rows.
+ * above its caption), and cells line up in columns across rows. `matrix-wide`: the same rows and
+ * cells for specimens as wide as their container (tabs, a toolbar, a table), one cell under
+ * another at the stack measure.
  */
-export type ExampleFramePreviewLayout = "default" | "stack" | "stack-narrow" | "full" | "row" | "matrix";
+export type ExampleFramePreviewLayout = "default" | "stack" | "stack-narrow" | "full" | "row" | "matrix" | "matrix-wide";
 export type ExampleFrameLabels = {
     paneSwitch: string;
     preview: string;
@@ -23,25 +25,53 @@ export type ExampleFrameLabels = {
     themeLight: string;
     codeRegion: string;
 };
+export declare const EXAMPLE_FRAME_LABELS: ExampleFrameLabels;
 export type ExampleFrameProps = Omit<React.HTMLAttributes<HTMLDivElement>, "onCopy"> & {
-    /** Source shown on the code pane (TS/TSX highlighting) and copied by the copy button. */
+    /**
+     * Source shown on the code pane (TS / TSX highlighting via CodeBlock) and copied by the copy button.
+     */
     code: string;
     /** The outer `<div>`. */
     ref?: React.Ref<HTMLDivElement>;
-    /** Preview color scheme (controlled). */
+    /**
+     * Theme of the stage and code pane (controlled); the page theme is untouched.
+     */
     colorScheme?: ColorScheme;
+    /**
+     * Initial theme (uncontrolled).
+     */
     defaultColorScheme?: ColorScheme;
+    /**
+     * Called with the new theme from the theme toggle.
+     */
     onColorSchemeChange?: (scheme: ColorScheme) => void;
-    /** Preview width (desktop / tablet / mobile). Default `desktop`. */
+    /**
+     * Preview width (controlled).
+     */
     viewport?: ExampleFrameViewport;
+    /**
+     * Initial preview width (uncontrolled).
+     */
     defaultViewport?: ExampleFrameViewport;
+    /**
+     * Called with the new width from the device switch.
+     */
     onViewportChange?: (v: ExampleFrameViewport) => void;
-    /** Show the light / dark toggle in the toolbar. Default `true`. */
+    /**
+     * Show the light / dark toggle in the toolbar.
+     */
     showThemeToggle?: boolean;
-    /** Called after `code` was copied to the clipboard. */
+    /**
+     * Called after `code` was copied to the clipboard.
+     */
     onCopy?: () => void;
-    /** How the preview lays out its children. Default `default`: one centered block. */
+    /**
+     * How the preview lays out its children, so snippets need no wrapper divs (see Variants).
+     */
     previewLayout?: ExampleFramePreviewLayout;
+    /**
+     * Built-in strings, see Labels.
+     */
     labels?: Partial<ExampleFrameLabels>;
 };
 /** Documentation frame: a toolbar (pane, theme, copy, device width) above the preview or the code. */

package/dist/components/field-list/FieldList.d.ts

@@ -15,6 +15,7 @@ export type FieldListLabels = {
     /** Text beside the disabled add button once the list holds `max` rows; `{max}` is the limit. */
     maxReached: string;
 };
+export declare const FIELD_LIST_LABELS: FieldListLabels;
 /** Width of a column: the same track in the heading row and in every row. */
 export type FieldListColumnWidth = "fill" | "compact" | "s" | "m";
 export type FieldListColumn = {
@@ -38,44 +39,81 @@ export type FieldListRow<T> = {
     remove: () => void;
 };
 export type FieldListProps<T extends object> = Omit<FieldRootDomProps, "onChange"> & {
-    /** The rows (controlled). */
+    /**
+     * The rows (controlled).
+     */
     value?: readonly T[];
-    /** The first rows (uncontrolled). */
+    /**
+     * The first rows (uncontrolled).
+     */
     defaultValue?: readonly T[];
-    /** The new list after an edit, an added, removed or moved row. */
+    /**
+     * The new list after an edit (`row.update`), an added, removed or moved row.
+     */
     onValueChange?: (value: T[]) => void;
-    /** Stable unique id of an item: the row key, the drag id. */
+    /**
+     * Stable unique id of an item: the row key and the drag id.
+     */
     getId: (item: T) => string;
-    /** The columns, in the order of the cells `renderItem` returns. */
+    /**
+     * The columns in cell order: `label` (the heading; it names the field of the column in every row), `width` (`fill` | `compact` | `s` | `m`), `required` (a `*` after the heading).
+     */
     columns: readonly FieldListColumn[];
     /**
-     * The cells of a row: one element per column, in column order (a fragment of fields). A cell
-     * holds a kit field without a `label`: the column heading names it.
+     * The cells of a row, one element per column (a fragment): kit fields without `label`. `row` has `index`, `update(patch)` and `remove()`.
      */
     renderItem: (item: T, row: FieldListRow<T>) => React.ReactNode;
-    /** A new empty item; with it the list shows the add button under the rows. */
+    /**
+     * A new empty item; with it the add button shows under the rows and focus goes to the new row's first field.
+     */
     createItem?: () => T;
-    /** Text of the add button: what is added («Добавить позицию»). */
+    /**
+     * Text of the add button: what is added («Добавить позицию»).
+     */
     addLabel?: string;
-    /** The row's own text for its handle, remove button and drag announcements (its title field). */
+    /**
+     * The row's own text (its title field) for the remove button, the handle and drag announcements; else the row number.
+     */
     getLabel?: (item: T) => string;
-    /** Rows that hold their place and cannot be removed: a lock in the lead column. */
+    /**
+     * Pinned rows: a lock in the lead column, no remove button, they hold their place while others move.
+     */
     getLocked?: (item: T) => boolean;
-    /** Rows move by a leading handle (drag, a touch hold, Alt + ↑ / ↓). */
+    /**
+     * Rows move by a leading handle: drag, a touch hold, Alt + ↑ / ↓.
+     */
     reorderable?: boolean;
-    /** The fewest rows: remove buttons turn disabled at this count. Default 0. */
+    /**
+     * The fewest rows: at this count the remove buttons are disabled.
+     */
     min?: number;
-    /** The most rows: the add button turns disabled with `labels.maxReached` beside it. */
+    /**
+     * The most rows: at this count the add button is disabled with `labels.maxReached` beside it.
+     */
     max?: number;
-    /** Heading of the list (field label); omit it inside a `Fieldset` whose legend names the list. */
+    /**
+     * Heading of the list; names the `<ol>`. Omit it inside a `Fieldset` whose legend names the list.
+     */
     label?: React.ReactNode;
+    /**
+     * Help text under the list; hidden while `error` shows.
+     */
     hint?: React.ReactNode;
-    /** A problem of the list as a whole («Добавьте хотя бы одну позицию»); a field's own goes on it. */
+    /**
+     * A problem of the list as a whole («Добавьте хотя бы одну позицию»); a field's own error goes on that field.
+     */
     error?: React.ReactNode;
-    /** Every field, the handles and the buttons are disabled. */
+    /**
+     * Disables every field, handle and button; a disabled `Fieldset` around it sets it too.
+     */
     disabled?: boolean;
-    /** Tier of the rows, the headings and the kit fields that read the host tier. Default `m`. */
+    /**
+     * Tier of the headings, buttons and the kit fields that read the host tier. Without it the host tier, else `m`.
+     */
     size?: ControlSize;
+    /**
+     * Built-in strings, see Labels.
+     */
     labels?: Partial<FieldListLabels>;
 };
 /**
@@ -84,7 +122,7 @@ export type FieldListProps<T extends object> = Omit<FieldRootDomProps, "onChange
  * reorder and pinned rows. In a narrow container the rows stack into blocks and each field shows
  * its own label.
  */
-export declare function FieldList<T extends object>({ value: valueProp, defaultValue, onValueChange, getId, columns, renderItem, createItem, addLabel, getLabel, getLocked, reorderable, min, max, label, hint, error, disabled: disabledProp, size: sizeProp, labels: labelsProp, className, ref, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, ...rest }: FieldListProps<T>): import("react/jsx-runtime").JSX.Element;
+export declare function FieldList<T extends object>({ value: valueProp, defaultValue, onValueChange, getId, columns, renderItem, createItem, addLabel, getLabel, getLocked, reorderable, min, max, label, hint, error, disabled: disabledProp, size: sizeProp, labels: labelsProp, className, ref, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, ...rest }: FieldListProps<T>): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>;
 export declare namespace FieldList {
     var displayName: string;
 }

package/dist/components/fieldset/Fieldset.d.ts

@@ -1,22 +1,27 @@
 import * as React from "react";
 export type FieldsetProps = Omit<React.FieldsetHTMLAttributes<HTMLFieldSetElement>, "children" | "disabled"> & {
-    /** Group heading (`title-s`) in the native `<legend>`; it names the group. */
+    /**
+     * 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.
+     */
     label?: React.ReactNode;
-    /** Secondary text under the heading; linked to the group through `aria-describedby`. */
+    /**
+     * Secondary text under the heading (`body-s`, secondary), linked through `aria-describedby`.
+     */
     description?: React.ReactNode;
     /**
-     * Disables every control inside: native `disabled` on the `<fieldset>` (native controls) plus the
-     * kit's disabled context, so kit controls render, announce and behave disabled. Use it while the
-     * form's request runs.
+     * 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.
      */
     disabled?: boolean;
-    /** The fields; they stack at the form rhythm (field → field 20). */
+    /**
+     * The fields, stacked 20 apart; a row of two fields is the consumer's grid.
+     */
     children: React.ReactNode;
     ref?: React.Ref<HTMLFieldSetElement>;
 };
 /**
  * A frameless group of fields: native `<fieldset>` + `<legend>` heading, the kit's field rhythm
- * between the children, one `disabled` for all of them. No border, no padding, no fill.
+ * between the children, one `disabled` for all of them. No border, no padding, no fill. Without a
+ * `label` it is the plain field column of a form.
  */
 export declare function Fieldset({ label, description, disabled: disabledProp, className, children, "aria-describedby": ariaDescribedBy, ...rest }: FieldsetProps): import("react/jsx-runtime").JSX.Element;
 export declare namespace Fieldset {

package/dist/components/file-upload/FileUpload.d.ts

@@ -1,14 +1,16 @@
 import * as React from "react";
 import type { UploadQueue } from "../../hooks/useUploadQueue";
-import { type FieldFrameProps, type FieldRootDomProps } from "../../internal/FieldFrame";
+import { type FieldFocusRingProps, type FieldFrameProps, type FieldRootDomProps } from "../../internal/FieldFrame";
 import type { ControlSize, PaletteColor, TextTone, Tone } from "../../internal/states";
 /** The look of the drop zone: `dashed` — the drop affordance line; `solid` — its fill only. */
 export type FileUploadVariant = "dashed" | "solid";
 /**
  * How files are added: `dropzone` — the drop area; `button` — a compact picker button (a paperclip)
- * with no zone and no drop; `tile` — an add tile at the end of the files, the whole set a drop target.
+ * with no zone and no drop; `tile` — an add tile at the end of the files, the whole set a drop
+ * target; `none` — no trigger of its own: the picker opens from code (`picker.open`), from a menu
+ * of another component.
  */
-export type FileUploadTrigger = "dropzone" | "button" | "tile";
+export type FileUploadTrigger = "dropzone" | "button" | "tile" | "none";
 /**
  * `list` — rows: badge or preview, name, size and status, a progress bar across the row. `grid` —
  * square tiles that follow the set's width (5 · 4 · 3 · 2 across); `strip` — one row of tiles that
@@ -66,6 +68,8 @@ export type FileUploadLabels = {
     failed: string;
     /** Name of the progress bar of a row: `{name}`. */
     progress: string;
+    /** Name of a `FileUpload.ItemProgress` that has no `aria-label` of its own. */
+    upload: string;
     /** Name of the disk that cancels a tile's upload in flight: `{name}`. */
     cancel: string;
     /** Name of the retry button of a failed file: `{name}`. */
@@ -91,6 +95,7 @@ export type FileUploadLabels = {
     /** Name of any other file's tile: `{position}`, `{name}`, `{status}`. */
     tileFile: string;
 };
+export declare const FILE_UPLOAD_LABELS: FileUploadLabels;
 type DivProps = React.HTMLAttributes<HTMLDivElement> & {
     ref?: React.Ref<HTMLDivElement>;
 };
@@ -112,8 +117,10 @@ declare namespace FileUploadIcon {
     var displayName: string;
 }
 export type FileUploadTitleProps = ParagraphProps & {
-    /** `muted` — secondary color, regular weight (an instruction line in custom bodies). */
-    tone?: Extract<TextTone, "default" | "muted">;
+    /**
+     * `secondary` — secondary color, regular weight (an instruction line in custom bodies).
+     */
+    tone?: Extract<TextTone, "default" | "secondary">;
 };
 declare function FileUploadTitle({ className, tone, ...rest }: FileUploadTitleProps): import("react/jsx-runtime").JSX.Element;
 declare namespace FileUploadTitle {
@@ -126,29 +133,43 @@ declare namespace FileUploadDescription {
     var displayName: string;
 }
 export type FileUploadItemProps = DivProps & {
-    /** Failed upload: danger wash and ring, danger description. */
+    /**
+     * A failed upload: danger wash and ring, danger description.
+     */
     invalid?: boolean;
-    /** Typography, spacing and the format badge follow the control tier (default: the host tier, else `m`). */
+    /**
+     * Tier of the padding, text and the format badge. Without it the tier of its host, else `m`.
+     */
     size?: ControlSize;
 };
 /** A file row: format badge or preview · name over description · actions, then the progress bar. */
-declare function FileUploadItem({ className, invalid, size: sizeProp, ...rest }: FileUploadItemProps): import("react/jsx-runtime").JSX.Element;
+declare function FileUploadItem({ className, invalid, size: sizeProp, ...rest }: FileUploadItemProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>;
 declare namespace FileUploadItem {
     var displayName: string;
 }
-export type FileUploadFormatBadgeProps = Omit<React.HTMLAttributes<HTMLSpanElement>, "children" | "color"> & {
-    /** File extension; shown upper-case, cut to 8 characters. */
+export type FileUploadFormatBadgeProps = Omit<React.HTMLAttributes<HTMLDivElement>, "children" | "color"> & {
+    /**
+     * File extension; shown upper-case, cut to 8 characters.
+     */
     format: string;
+    /**
+     * Palette hue of the tile.
+     */
     color?: PaletteColor;
-    ref?: React.Ref<HTMLSpanElement>;
+    ref?: React.Ref<HTMLDivElement>;
 };
-/** The file format as a square kit Badge (decorative: the name already carries the extension). */
+/**
+ * The file format as the short label of a square kit Thumbnail of the row tier, the box an image
+ * file's picture takes (decorative: the name already carries the extension).
+ */
 declare function FileUploadFormatBadge({ format, color, className, ...rest }: FileUploadFormatBadgeProps): import("react/jsx-runtime").JSX.Element;
 declare namespace FileUploadFormatBadge {
     var displayName: string;
 }
 export type FileUploadItemPreviewProps = Omit<React.HTMLAttributes<HTMLDivElement>, "children" | "color"> & {
-    /** The picture: a URL, or the local preview of a file being uploaded. */
+    /**
+     * The picture: a URL, or the local `preview` of a queued file.
+     */
     src: string;
     ref?: React.Ref<HTMLDivElement>;
 };
@@ -160,9 +181,9 @@ declare function FileUploadItemPreview({ src, className, ...rest }: FileUploadIt
 declare namespace FileUploadItemPreview {
     var displayName: string;
 }
-export type FileUploadItemNameProps = DivProps;
-declare function FileUploadItemName({ className, ...rest }: FileUploadItemNameProps): import("react/jsx-runtime").JSX.Element;
-declare namespace FileUploadItemName {
+export type FileUploadItemTextProps = DivProps;
+declare function FileUploadItemText({ className, ...rest }: FileUploadItemTextProps): import("react/jsx-runtime").JSX.Element;
+declare namespace FileUploadItemText {
     var displayName: string;
 }
 export type FileUploadItemDescriptionProps = DivProps;
@@ -178,11 +199,21 @@ declare namespace FileUploadItemActions {
     var displayName: string;
 }
 export type FileUploadItemProgressProps = Omit<DivProps, "children"> & {
+    /**
+     * Uploaded amount.
+     */
     value: number;
+    /**
+     * Total amount (ProgressBar default).
+     */
     max?: number;
-    /** Fill color: `success` for a finished file, `danger` where a failed one stopped. Default `accent`. */
+    /**
+     * Fill color: `success` for a finished file, `danger` where a failed one stopped.
+     */
     tone?: Tone;
-    /** Accessible name of the bar; name the file. Default «Загрузка файла». */
+    /**
+     * Accessible name of the bar (not the wrapper); name the file.
+     */
     "aria-label"?: string;
 };
 /** Upload progress across the whole row: the kit ProgressBar. */
@@ -198,30 +229,41 @@ declare namespace FileUploadItemProgress {
 export type FileUploadQueueSource = Pick<UploadQueue, "items" | "retry" | "remove"> & Partial<Pick<UploadQueue, "add" | "move">>;
 /** The props of the set itself, shared by `FileUpload.Root` and `FileUpload.Queue`. */
 type FileSetProps = {
-    /** Files in their order (controlled): on the server, or uploads of `queue` by their ids. */
+    /**
+     * 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.
+     */
     value?: readonly FileUploadFile[];
-    /** Initial files (uncontrolled). */
+    /**
+     * Initial files (uncontrolled).
+     */
     defaultValue?: readonly FileUploadFile[];
     /**
-     * The set changed: reordered, a file removed, files added to `queue`. Return
-     * the save's promise: the files it touches wait busy; a move or new files stand in
-     * their new places meanwhile, a removed file stays until the answer. Resolve — the change stands
-     * (a controlled owner applies `value` before resolving); reject — the set goes back (new files
-     * leave the queue) and `labels.changeFailed` is announced.
+     * 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.
      */
     onValueChange?: (value: readonly FileUploadFile[]) => void | Promise<void>;
-    /** The uploads: `useUploadQueue(…)`. Its files that are not in `value` follow it in its order. */
+    /**
+     * 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.
+     */
     queue?: FileUploadQueueSource;
+    /**
+     * `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).
+     */
     layout?: FileUploadLayout;
     /**
-     * Tiles (`grid`, `strip`): the first file is the cover — «Обложка» in place of its format pill,
-     * two by two in a grid. A file reordered first becomes the cover, and that is announced.
+     * Tiles only: the first file is the cover («Обложка», 2 × 2 in a `grid`). Reordering a file to the first place makes it the cover.
      */
     cover?: boolean;
-    /** Display of a file size. Default: Russian digits with Б · КБ · МБ · ГБ. */
+    /**
+     * Display of a file size («820 КБ», «1,2 МБ»).
+     */
     formatSize?: (bytes: number) => string;
-    /** Read-only set: no add tile, no reorder, no remove. */
+    /**
+     * Read-only files: no reorder, no remove.
+     */
     disabled?: boolean;
+    /**
+     * Row and tile strings, see Labels.
+     */
     labels?: Partial<FileUploadLabels>;
 };
 export type FileUploadQueueProps = Omit<React.HTMLAttributes<HTMLUListElement>, "children" | "defaultValue"> & FileSetProps & {
@@ -235,28 +277,63 @@ declare function FileUploadQueue(props: FileUploadQueueProps): import("react/jsx
 declare namespace FileUploadQueue {
     var displayName: string;
 }
-export type FileUploadRootProps = FieldRootDomProps & Omit<FieldFrameProps, "focusRing"> & FileSetProps & {
-    /** Tier. Default: the tier of the surrounding control (a form, a panel), else `m`. */
+/** Opens the root's file picker from code (`FileUpload.Root` `picker`). */
+export type FileUploadPicker = {
+    /**
+     * Opens the picker; `accept` narrows this one pick (a «Фото» item of a menu) and the files it
+     * takes. Nothing happens while the field is disabled or its set is full.
+     */
+    open: (options?: {
+        accept?: string;
+    }) => void;
+};
+export type FileUploadRootProps = FieldRootDomProps & FieldFrameProps & FieldFocusRingProps & FileSetProps & {
+    /**
+     * 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?: ControlSize;
+    /**
+     * `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`).
+     */
     trigger?: FileUploadTrigger;
+    /**
+     * The look of the drop zone: `dashed` shows the drop line; `solid` keeps only the fill (cards, modals).
+     */
     variant?: FileUploadVariant;
-    /** Access to the hidden file input (open the picker programmatically). */
-    inputRef?: React.Ref<HTMLInputElement>;
+    /**
+     * 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.
+     */
+    picker?: React.Ref<FileUploadPicker>;
+    /**
+     * 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).
+     */
     accept?: string;
+    /**
+     * Allows several files at once in the picker.
+     */
     multiple?: boolean;
-    /** Most files in the set: the add tile counts them; files past it are not taken. */
+    /**
+     * 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.
+     */
     max?: number;
-    /** Invalid state: danger line and `aria-invalid`. A non-empty `error` implies it. */
+    /**
+     * Danger line and icon of the zone, `aria-invalid` on the input. A non-empty `error` implies it.
+     */
     invalid?: boolean;
-    /** Name of the file input inside a form. */
+    /**
+     * Name of the file input inside a form.
+     */
     name?: string;
-    /** Files picked or dropped (of `accept`, cut to `max`). Not called with `queue.add`: they go there. */
+    /**
+     * 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.
+     */
     onFilesChange?: (files: File[]) => void;
-    /** Id of the file input; generated when omitted. */
+    /**
+     * Id of the file input (generated when omitted); hint id is `<id>-hint`, error id is `<id>-error`.
+     */
     id?: string;
     /**
-     * A zone: a custom body (`FileUpload.Body`) instead of the built-in one. `trigger="button"`:
-     * the button's content (`Button.Icon` and text; an icon alone makes it icon-only).
+     * 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`).
      */
     children?: React.ReactNode;
 };
@@ -278,7 +355,7 @@ export declare const FileUpload: {
     Item: typeof FileUploadItem;
     FormatBadge: typeof FileUploadFormatBadge;
     ItemPreview: typeof FileUploadItemPreview;
-    ItemName: typeof FileUploadItemName;
+    ItemText: typeof FileUploadItemText;
     ItemDescription: typeof FileUploadItemDescription;
     ItemActions: typeof FileUploadItemActions;
     ItemProgress: typeof FileUploadItemProgress;