prime-ui-kit 0.3.1 → 0.4.0

package/src/components/dropdown/examples/placement-demo.tsx

@@ -0,0 +1,59 @@
+import { Button } from "@/components/button/Button";
+import { Dropdown } from "@/components/dropdown/Dropdown";
+
+const longLabel = "Экспорт в PDF и печатная версия";
+
+/** Предпочтения `align` и `side`; у края вьюпорта панель может переноситься. */
+export default function DropdownPlacementDemoExample() {
+  return (
+    <>
+      <Dropdown.Root>
+        <Dropdown.Trigger>
+          <Button.Root type="button" size="s" variant="neutral" mode="stroke">
+            align start
+          </Button.Root>
+        </Dropdown.Trigger>
+        <Dropdown.Content align="start">
+          <Dropdown.Item>{longLabel}</Dropdown.Item>
+          <Dropdown.Item>Дублировать в проект</Dropdown.Item>
+        </Dropdown.Content>
+      </Dropdown.Root>
+
+      <Dropdown.Root>
+        <Dropdown.Trigger>
+          <Button.Root type="button" size="s" variant="neutral" mode="stroke">
+            align center
+          </Button.Root>
+        </Dropdown.Trigger>
+        <Dropdown.Content align="center">
+          <Dropdown.Item>{longLabel}</Dropdown.Item>
+          <Dropdown.Item>Дублировать в проект</Dropdown.Item>
+        </Dropdown.Content>
+      </Dropdown.Root>
+
+      <Dropdown.Root>
+        <Dropdown.Trigger>
+          <Button.Root type="button" size="s" variant="neutral" mode="stroke">
+            align end
+          </Button.Root>
+        </Dropdown.Trigger>
+        <Dropdown.Content align="end">
+          <Dropdown.Item>{longLabel}</Dropdown.Item>
+          <Dropdown.Item>Дублировать в проект</Dropdown.Item>
+        </Dropdown.Content>
+      </Dropdown.Root>
+
+      <Dropdown.Root>
+        <Dropdown.Trigger>
+          <Button.Root type="button" size="s" variant="neutral" mode="stroke">
+            side top
+          </Button.Root>
+        </Dropdown.Trigger>
+        <Dropdown.Content side="top">
+          <Dropdown.Item>Пункт выше триггера</Dropdown.Item>
+          <Dropdown.Item>Второй пункт</Dropdown.Item>
+        </Dropdown.Content>
+      </Dropdown.Root>
+    </>
+  );
+}

package/src/components/dropdown/examples/select-like-list.tsx

@@ -0,0 +1,31 @@
+import { useState } from "react";
+import { Button } from "@/components/button/Button";
+import { Dropdown } from "@/components/dropdown/Dropdown";
+
+const WORKSPACES = ["Команда дизайна", "Продукт Альфа", "Внутренние"] as const;
+
+/**
+ * Быстрый переключатель контекста: триггер показывает текущий выбор.
+ * Семантика остаётся `role="menu"` / `menuitem`, не комбобокс — для поля формы с одним значением
+ * и связью label/value используйте Select.
+ */
+export default function DropdownSelectLikeListExample() {
+  const [workspace, setWorkspace] = useState<(typeof WORKSPACES)[number]>(WORKSPACES[0]);
+
+  return (
+    <Dropdown.Root>
+      <Dropdown.Trigger>
+        <Button.Root type="button" variant="neutral" mode="stroke" size="m">
+          Пространство: {workspace}
+        </Button.Root>
+      </Dropdown.Trigger>
+      <Dropdown.Content sameMinWidthAsTrigger>
+        {WORKSPACES.map((name) => (
+          <Dropdown.Item key={name} onSelect={() => setWorkspace(name)}>
+            {name}
+          </Dropdown.Item>
+        ))}
+      </Dropdown.Content>
+    </Dropdown.Root>
+  );
+}

package/src/components/dropdown/examples/sizes.tsx

@@ -0,0 +1,99 @@
+import { Copy, Edit, Trash2 } from "lucide-react";
+import { Button } from "@/components/button/Button";
+import { Dropdown } from "@/components/dropdown/Dropdown";
+
+/** Ярус `size` на `Dropdown.Content`: s, m, l, xl — как в `playground/snippets/dropdown/sizes.tsx`. */
+export default function DropdownSizesExample() {
+  return (
+    <>
+      <Dropdown.Root>
+        <Dropdown.Trigger>
+          <Button.Root type="button" size="s" variant="neutral" mode="stroke">
+            size=&quot;s&quot;
+          </Button.Root>
+        </Dropdown.Trigger>
+        <Dropdown.Content size="s">
+          <Dropdown.Item>
+            <Dropdown.ItemIcon as={Edit} strokeWidth={2} />
+            Редактировать
+          </Dropdown.Item>
+          <Dropdown.Item>
+            <Dropdown.ItemIcon as={Copy} strokeWidth={2} />
+            Дублировать
+          </Dropdown.Item>
+          <Dropdown.Separator />
+          <Dropdown.Item destructive>
+            <Dropdown.ItemIcon as={Trash2} strokeWidth={2} />
+            Удалить
+          </Dropdown.Item>
+        </Dropdown.Content>
+      </Dropdown.Root>
+      <Dropdown.Root>
+        <Dropdown.Trigger>
+          <Button.Root type="button" size="m" variant="neutral" mode="stroke">
+            size=&quot;m&quot;
+          </Button.Root>
+        </Dropdown.Trigger>
+        <Dropdown.Content size="m">
+          <Dropdown.Item>
+            <Dropdown.ItemIcon as={Edit} strokeWidth={2} />
+            Редактировать
+          </Dropdown.Item>
+          <Dropdown.Item>
+            <Dropdown.ItemIcon as={Copy} strokeWidth={2} />
+            Дублировать
+          </Dropdown.Item>
+          <Dropdown.Separator />
+          <Dropdown.Item destructive>
+            <Dropdown.ItemIcon as={Trash2} strokeWidth={2} />
+            Удалить
+          </Dropdown.Item>
+        </Dropdown.Content>
+      </Dropdown.Root>
+      <Dropdown.Root>
+        <Dropdown.Trigger>
+          <Button.Root type="button" size="l" variant="neutral" mode="stroke">
+            size=&quot;l&quot;
+          </Button.Root>
+        </Dropdown.Trigger>
+        <Dropdown.Content size="l">
+          <Dropdown.Item>
+            <Dropdown.ItemIcon as={Edit} strokeWidth={2} />
+            Редактировать
+          </Dropdown.Item>
+          <Dropdown.Item>
+            <Dropdown.ItemIcon as={Copy} strokeWidth={2} />
+            Дублировать
+          </Dropdown.Item>
+          <Dropdown.Separator />
+          <Dropdown.Item destructive>
+            <Dropdown.ItemIcon as={Trash2} strokeWidth={2} />
+            Удалить
+          </Dropdown.Item>
+        </Dropdown.Content>
+      </Dropdown.Root>
+      <Dropdown.Root>
+        <Dropdown.Trigger>
+          <Button.Root type="button" size="xl" variant="neutral" mode="stroke">
+            size=&quot;xl&quot;
+          </Button.Root>
+        </Dropdown.Trigger>
+        <Dropdown.Content size="xl">
+          <Dropdown.Item>
+            <Dropdown.ItemIcon as={Edit} strokeWidth={2} />
+            Редактировать
+          </Dropdown.Item>
+          <Dropdown.Item>
+            <Dropdown.ItemIcon as={Copy} strokeWidth={2} />
+            Дублировать
+          </Dropdown.Item>
+          <Dropdown.Separator />
+          <Dropdown.Item destructive>
+            <Dropdown.ItemIcon as={Trash2} strokeWidth={2} />
+            Удалить
+          </Dropdown.Item>
+        </Dropdown.Content>
+      </Dropdown.Root>
+    </>
+  );
+}

package/src/components/dropdown/examples/states.tsx

@@ -0,0 +1,20 @@
+import { Button } from "@/components/button/Button";
+import { Dropdown } from "@/components/dropdown/Dropdown";
+
+/** Недоступный пункт через `disabled` — как в `playground/snippets/dropdown/states.tsx`. */
+export default function DropdownStatesExample() {
+  return (
+    <Dropdown.Root>
+      <Dropdown.Trigger>
+        <Button.Root type="button" size="m" variant="neutral" mode="stroke">
+          Доступ к отчёту
+        </Button.Root>
+      </Dropdown.Trigger>
+      <Dropdown.Content>
+        <Dropdown.Item>Скачать PDF</Dropdown.Item>
+        <Dropdown.Item disabled>Экспорт в Excel (нет прав)</Dropdown.Item>
+        <Dropdown.Item>Отправить на почту</Dropdown.Item>
+      </Dropdown.Content>
+    </Dropdown.Root>
+  );
+}

package/src/components/dropdown/examples/variants.tsx

@@ -0,0 +1,21 @@
+import { Button } from "@/components/button/Button";
+import { Dropdown } from "@/components/dropdown/Dropdown";
+
+/** Обычные пункты и `destructive` на `Dropdown.Item` — как в `playground/snippets/dropdown/variants.tsx`. */
+export default function DropdownVariantsExample() {
+  return (
+    <Dropdown.Root>
+      <Dropdown.Trigger>
+        <Button.Root type="button" size="m" variant="neutral" mode="lighter">
+          Документ
+        </Button.Root>
+      </Dropdown.Trigger>
+      <Dropdown.Content>
+        <Dropdown.Item>Переименовать</Dropdown.Item>
+        <Dropdown.Item>Переместить…</Dropdown.Item>
+        <Dropdown.Separator />
+        <Dropdown.Item destructive>Удалить безвозвратно</Dropdown.Item>
+      </Dropdown.Content>
+    </Dropdown.Root>
+  );
+}

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

@@ -2,7 +2,17 @@
 
 **Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
 
-## About
+## Canonical
+
+- **Назначение:** зона выбора файла — внешний **`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`. Список файлов и загрузка на сервер — **на стороне приложения**.
+
+## 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).
 
@@ -20,11 +30,40 @@ Composable UI for choosing files: a `label` wrapping a hidden `input type="file"
 - 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
+### 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
 
 ```tsx
@@ -35,7 +74,7 @@ export function Example() {
 }
 ```
 
-## Rules
+### 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).
@@ -198,3 +237,14 @@ export function Example() {
 - [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)**).

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

@@ -0,0 +1,54 @@
+import { Avatar, FileUpload } 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);
+
+  React.useEffect(() => {
+    return () => {
+      if (previewUrl) {
+        URL.revokeObjectURL(previewUrl);
+      }
+    };
+  }, [previewUrl]);
+
+  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>
+        </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>
+      </div>
+    </div>
+  );
+}

package/src/components/file-upload/examples/controlled-list.tsx

@@ -0,0 +1,103 @@
+import { Button, FileUpload } from "prime-ui-kit";
+import * as React from "react";
+
+function formatBytes(bytes: number): string {
+  if (bytes < 1024) {
+    return `${bytes} B`;
+  }
+  if (bytes < 1024 * 1024) {
+    return `${(bytes / 1024).toFixed(1)} KB`;
+  }
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+function extensionOf(name: string): string {
+  const dot = name.lastIndexOf(".");
+  return dot >= 0 ? name.slice(dot + 1) : "file";
+}
+
+type FileEntry = { id: string; file: File };
+
+/**
+ * Контролируемый список: добавление через зону, удаление по строке и очистка всего списка.
+ */
+export function FileUploadControlledListExample() {
+  const [entries, setEntries] = React.useState<FileEntry[]>([]);
+
+  const removeById = (id: string) => {
+    setEntries((prev) => prev.filter((e) => e.id !== id));
+  };
+
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: "var(--prime-sys-spacing-m)",
+        maxWidth: 520,
+      }}
+    >
+      <FileUpload.Root
+        multiple
+        accept="image/png,image/jpeg,.pdf,application/pdf"
+        onFilesChange={(next) => {
+          setEntries((prev) => [
+            ...prev,
+            ...next.map((file) => ({ id: crypto.randomUUID(), file })),
+          ]);
+        }}
+      />
+
+      {entries.length > 0 ? (
+        <>
+          <div
+            style={{ display: "flex", flexDirection: "column", gap: "var(--prime-sys-spacing-s)" }}
+          >
+            {entries.map(({ id, file }) => (
+              <FileUpload.Item key={id}>
+                <FileUpload.ItemRow>
+                  <FileUpload.FormatBadge
+                    format={extensionOf(file.name)}
+                    color={file.type.startsWith("image/") ? "blue" : "gray"}
+                  />
+                  <FileUpload.ItemMain>
+                    <FileUpload.ItemTextGroup>
+                      <FileUpload.ItemName>{file.name}</FileUpload.ItemName>
+                      <FileUpload.ItemMeta>
+                        <span>{formatBytes(file.size)}</span>
+                      </FileUpload.ItemMeta>
+                    </FileUpload.ItemTextGroup>
+                  </FileUpload.ItemMain>
+                  <FileUpload.ItemActions>
+                    <Button.Root
+                      type="button"
+                      size="s"
+                      variant="neutral"
+                      mode="stroke"
+                      onClick={() => {
+                        removeById(id);
+                      }}
+                    >
+                      Удалить
+                    </Button.Root>
+                  </FileUpload.ItemActions>
+                </FileUpload.ItemRow>
+              </FileUpload.Item>
+            ))}
+          </div>
+          <Button.Root
+            type="button"
+            size="s"
+            variant="neutral"
+            mode="stroke"
+            onClick={() => {
+              setEntries([]);
+            }}
+          >
+            Очистить всё
+          </Button.Root>
+        </>
+      ) : null}
+    </div>
+  );
+}

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

@@ -0,0 +1,21 @@
+import { FileUpload } from "prime-ui-kit";
+
+/**
+ * Свой контент зоны и accept для изображений.
+ * См. playground/snippets/file-upload/custom-children.tsx.
+ */
+export function FileUploadCustomChildrenExample() {
+  return (
+    <FileUpload.Root accept="image/*">
+      <div
+        style={{
+          padding: "var(--prime-sys-spacing-x4)",
+          fontSize: "var(--prime-sys-size-control-l-text)",
+          color: "var(--prime-sys-color-content-secondary)",
+        }}
+      >
+        Custom drop area — images only
+      </div>
+    </FileUpload.Root>
+  );
+}

package/src/components/file-upload/examples/document-attach.tsx

@@ -0,0 +1,70 @@
+import { FileUpload } from "prime-ui-kit";
+import * as React from "react";
+
+function formatBytes(bytes: number): string {
+  if (bytes < 1024) {
+    return `${bytes} B`;
+  }
+  if (bytes < 1024 * 1024) {
+    return `${(bytes / 1024).toFixed(1)} KB`;
+  }
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+function extensionOf(name: string): string {
+  const dot = name.lastIndexOf(".");
+  return dot >= 0 ? name.slice(dot + 1) : "file";
+}
+
+/**
+ * Вложения к сообщению: несколько файлов, список в виде Item.
+ */
+export function FileUploadDocumentAttachExample() {
+  const [files, setFiles] = React.useState<File[]>([]);
+
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: "var(--prime-sys-spacing-m)",
+        maxWidth: 480,
+      }}
+    >
+      <FileUpload.Root
+        multiple
+        accept=".pdf,.doc,.docx,application/pdf"
+        onFilesChange={(next) => {
+          setFiles((prev) => [...prev, ...next]);
+        }}
+      >
+        <FileUpload.DropBody>
+          <FileUpload.Title>Прикрепить документы</FileUpload.Title>
+          <FileUpload.Hint>PDF, DOC или DOCX</FileUpload.Hint>
+        </FileUpload.DropBody>
+      </FileUpload.Root>
+
+      {files.length > 0 ? (
+        <div
+          style={{ display: "flex", flexDirection: "column", gap: "var(--prime-sys-spacing-s)" }}
+        >
+          {files.map((file) => (
+            <FileUpload.Item key={`${file.name}-${file.size}-${file.lastModified}`}>
+              <FileUpload.ItemRow>
+                <FileUpload.FormatBadge format={extensionOf(file.name)} color="red" />
+                <FileUpload.ItemMain>
+                  <FileUpload.ItemTextGroup>
+                    <FileUpload.ItemName>{file.name}</FileUpload.ItemName>
+                    <FileUpload.ItemMeta>
+                      <span>{formatBytes(file.size)}</span>
+                    </FileUpload.ItemMeta>
+                  </FileUpload.ItemTextGroup>
+                </FileUpload.ItemMain>
+              </FileUpload.ItemRow>
+            </FileUpload.Item>
+          ))}
+        </div>
+      ) : null}
+    </div>
+  );
+}

package/src/components/file-upload/examples/drag-area.tsx

@@ -0,0 +1,49 @@
+import { FileUpload, Icon } from "prime-ui-kit";
+import * as React from "react";
+
+/**
+ * Кастомная зона: solid, текст с встроенной ссылкой «обзор» и программный open через inputRef.
+ */
+export function FileUploadDragAreaExample() {
+  const inputRef = React.useRef<HTMLInputElement>(null);
+  const [lastCount, setLastCount] = React.useState(0);
+
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: "var(--prime-sys-spacing-s)",
+        maxWidth: 520,
+      }}
+    >
+      <FileUpload.Root
+        inputRef={inputRef}
+        appearance="solid"
+        size="l"
+        multiple
+        onFilesChange={(files) => {
+          setLastCount(files.length);
+        }}
+      >
+        <FileUpload.DropBody>
+          <FileUpload.Icon>
+            <Icon name="action.upload" size="l" tone="subtle" />
+          </FileUpload.Icon>
+          <FileUpload.Title tone="muted">
+            Перетащите файлы сюда или{" "}
+            <FileUpload.BrowseLink type="button" onClick={() => inputRef.current?.click()}>
+              выберите на диске
+            </FileUpload.BrowseLink>
+          </FileUpload.Title>
+          <FileUpload.Hint>Любые типы, несколько файлов за раз</FileUpload.Hint>
+        </FileUpload.DropBody>
+      </FileUpload.Root>
+      {lastCount > 0 ? (
+        <p style={{ fontSize: "var(--prime-sys-typography-support-2xs)", margin: 0 }}>
+          Последний выбор: {lastCount} файл(ов)
+        </p>
+      ) : null}
+    </div>
+  );
+}

package/src/components/file-upload/examples/full-width.tsx

@@ -0,0 +1,32 @@
+import { FileUpload } from "prime-ui-kit";
+
+/**
+ * Зона на всю ширину колонки: у Root уже width 100%.
+ * См. playground/snippets/file-upload/full-width.tsx.
+ */
+export function FileUploadFullWidthExample() {
+  return (
+    <div
+      style={{
+        boxSizing: "border-box",
+        width: "100%",
+        maxWidth: "40rem",
+        padding: "var(--prime-sys-spacing-x4)",
+        borderRadius: "var(--prime-sys-shape-radius-l)",
+        border: "1px dashed var(--prime-sys-color-border-subtle)",
+        background: "var(--prime-sys-color-surface-default)",
+      }}
+    >
+      <p
+        style={{
+          margin: "0 0 var(--prime-sys-spacing-x3)",
+          fontSize: "var(--prime-sys-size-control-s-supportText)",
+          color: "var(--prime-sys-color-content-secondary)",
+        }}
+      >
+        Родитель на всю колонку: зона тянется вместе с формой или панелью.
+      </p>
+      <FileUpload.Root size="m" appearance="solid" />
+    </div>
+  );
+}