From ab92fe89429c5b9ce24e8d71f394550d7f8a8255 Mon Sep 17 00:00:00 2001
From: lskramarov <l.s.kramarov@gmail.com>
Date: Thu, 9 Jul 2026 21:39:55 +0300
Subject: [PATCH] feat: file upload by agent (first gen)

---
 .../src/components/FileUpload/FileUpload.mdx  | 284 +++++++
 .../FileUpload/FileUpload.module.css          | 116 +++
 .../FileUpload/FileUpload.stories.tsx         | 692 ++++++++++++++++++
 .../FileUpload/FileUploadContext.ts           |  25 +
 .../FileUpload/MultipleFileUpload.module.css  |  73 ++
 .../FileUpload/MultipleFileUpload.test.tsx    | 173 +++++
 .../FileUpload/MultipleFileUpload.tsx         | 277 +++++++
 .../FileUpload/SingleFileUpload.module.css    |   7 +
 .../FileUpload/SingleFileUpload.test.tsx      | 188 +++++
 .../FileUpload/SingleFileUpload.tsx           | 232 ++++++
 .../DropzoneContent.module.css                |   8 +
 .../DropzoneContent/DropzoneContent.tsx       |  73 ++
 .../components/DropzoneContent/index.ts       |   1 +
 .../components/FileInput/FileInput.tsx        |  83 +++
 .../FileUpload/components/FileInput/index.ts  |   1 +
 .../FileUploadCaption/FileUploadCaption.tsx   |  80 ++
 .../components/FileUploadCaption/index.ts     |   1 +
 .../FileUploadItem/FileUploadItem.module.css  |  58 ++
 .../FileUploadItem/FileUploadItem.tsx         | 141 ++++
 .../components/FileUploadItem/index.ts        |   1 +
 .../FileUploadProvider/FileUploadProvider.tsx |  33 +
 .../components/FileUploadProvider/index.ts    |   1 +
 .../FullScreenDropzone.module.css             |  13 +
 .../FullScreenDropzone/FullScreenDropzone.tsx |  53 ++
 .../components/FullScreenDropzone/index.ts    |   1 +
 .../LocalDropzone/LocalDropzone.module.css    |  15 +
 .../LocalDropzone/LocalDropzone.tsx           | 217 ++++++
 .../components/LocalDropzone/index.ts         |   1 +
 .../components/FileUpload/components/index.ts |   5 +
 .../src/components/FileUpload/constants.ts    |   8 +
 .../components/FileUpload/dropzones.test.tsx  | 158 ++++
 .../components/FileUpload/errorPredicates.ts  |  23 +
 .../src/components/FileUpload/hooks/index.ts  |   7 +
 .../FileUpload/hooks/useFileDrop/index.ts     |   1 +
 .../hooks/useFileDrop/useFileDrop.ts          | 129 ++++
 .../FileUpload/hooks/useFileInput/index.ts    |   1 +
 .../hooks/useFileInput/useFileInput.ts        |  80 ++
 .../FileUpload/hooks/useFileList/index.ts     |   1 +
 .../hooks/useFileList/useFileList.ts          | 121 +++
 .../hooks/useFileUploadItem/index.ts          |   1 +
 .../useFileUploadItem/useFileUploadItem.ts    |  21 +
 .../hooks/useFileUploadLocale/index.ts        |   1 +
 .../useFileUploadLocale.ts                    | 131 ++++
 .../hooks/useFileUploadState/index.ts         |   1 +
 .../useFileUploadState/useFileUploadState.ts  |  60 ++
 .../hooks/useFullScreenDropzone/index.ts      |   1 +
 .../useFullScreenDropzone.ts                  | 144 ++++
 .../src/components/FileUpload/index.ts        |  17 +
 .../src/components/FileUpload/intl.json       |  22 +
 .../components/FileUpload/locales.test.tsx    | 119 +++
 .../src/components/FileUpload/locales.ts      | 137 ++++
 .../components/FileUpload/primitives.test.tsx | 272 +++++++
 .../src/components/FileUpload/types.ts        | 254 +++++++
 .../src/components/FileUpload/utils.ts        | 182 +++++
 .../src/components/FileUpload/validators.ts   |  41 ++
 packages/components/src/components/index.ts   |   1 +
 tools/api-extractor/config.json               |   1 +
 .../components/FileUpload.api.md              | 538 ++++++++++++++
 58 files changed, 5326 insertions(+)
 create mode 100644 packages/components/src/components/FileUpload/FileUpload.mdx
 create mode 100644 packages/components/src/components/FileUpload/FileUpload.module.css
 create mode 100644 packages/components/src/components/FileUpload/FileUpload.stories.tsx
 create mode 100644 packages/components/src/components/FileUpload/FileUploadContext.ts
 create mode 100644 packages/components/src/components/FileUpload/MultipleFileUpload.module.css
 create mode 100644 packages/components/src/components/FileUpload/MultipleFileUpload.test.tsx
 create mode 100644 packages/components/src/components/FileUpload/MultipleFileUpload.tsx
 create mode 100644 packages/components/src/components/FileUpload/SingleFileUpload.module.css
 create mode 100644 packages/components/src/components/FileUpload/SingleFileUpload.test.tsx
 create mode 100644 packages/components/src/components/FileUpload/SingleFileUpload.tsx
 create mode 100644 packages/components/src/components/FileUpload/components/DropzoneContent/DropzoneContent.module.css
 create mode 100644 packages/components/src/components/FileUpload/components/DropzoneContent/DropzoneContent.tsx
 create mode 100644 packages/components/src/components/FileUpload/components/DropzoneContent/index.ts
 create mode 100644 packages/components/src/components/FileUpload/components/FileInput/FileInput.tsx
 create mode 100644 packages/components/src/components/FileUpload/components/FileInput/index.ts
 create mode 100644 packages/components/src/components/FileUpload/components/FileUploadCaption/FileUploadCaption.tsx
 create mode 100644 packages/components/src/components/FileUpload/components/FileUploadCaption/index.ts
 create mode 100644 packages/components/src/components/FileUpload/components/FileUploadItem/FileUploadItem.module.css
 create mode 100644 packages/components/src/components/FileUpload/components/FileUploadItem/FileUploadItem.tsx
 create mode 100644 packages/components/src/components/FileUpload/components/FileUploadItem/index.ts
 create mode 100644 packages/components/src/components/FileUpload/components/FileUploadProvider/FileUploadProvider.tsx
 create mode 100644 packages/components/src/components/FileUpload/components/FileUploadProvider/index.ts
 create mode 100644 packages/components/src/components/FileUpload/components/FullScreenDropzone/FullScreenDropzone.module.css
 create mode 100644 packages/components/src/components/FileUpload/components/FullScreenDropzone/FullScreenDropzone.tsx
 create mode 100644 packages/components/src/components/FileUpload/components/FullScreenDropzone/index.ts
 create mode 100644 packages/components/src/components/FileUpload/components/LocalDropzone/LocalDropzone.module.css
 create mode 100644 packages/components/src/components/FileUpload/components/LocalDropzone/LocalDropzone.tsx
 create mode 100644 packages/components/src/components/FileUpload/components/LocalDropzone/index.ts
 create mode 100644 packages/components/src/components/FileUpload/components/index.ts
 create mode 100644 packages/components/src/components/FileUpload/constants.ts
 create mode 100644 packages/components/src/components/FileUpload/dropzones.test.tsx
 create mode 100644 packages/components/src/components/FileUpload/errorPredicates.ts
 create mode 100644 packages/components/src/components/FileUpload/hooks/index.ts
 create mode 100644 packages/components/src/components/FileUpload/hooks/useFileDrop/index.ts
 create mode 100644 packages/components/src/components/FileUpload/hooks/useFileDrop/useFileDrop.ts
 create mode 100644 packages/components/src/components/FileUpload/hooks/useFileInput/index.ts
 create mode 100644 packages/components/src/components/FileUpload/hooks/useFileInput/useFileInput.ts
 create mode 100644 packages/components/src/components/FileUpload/hooks/useFileList/index.ts
 create mode 100644 packages/components/src/components/FileUpload/hooks/useFileList/useFileList.ts
 create mode 100644 packages/components/src/components/FileUpload/hooks/useFileUploadItem/index.ts
 create mode 100644 packages/components/src/components/FileUpload/hooks/useFileUploadItem/useFileUploadItem.ts
 create mode 100644 packages/components/src/components/FileUpload/hooks/useFileUploadLocale/index.ts
 create mode 100644 packages/components/src/components/FileUpload/hooks/useFileUploadLocale/useFileUploadLocale.ts
 create mode 100644 packages/components/src/components/FileUpload/hooks/useFileUploadState/index.ts
 create mode 100644 packages/components/src/components/FileUpload/hooks/useFileUploadState/useFileUploadState.ts
 create mode 100644 packages/components/src/components/FileUpload/hooks/useFullScreenDropzone/index.ts
 create mode 100644 packages/components/src/components/FileUpload/hooks/useFullScreenDropzone/useFullScreenDropzone.ts
 create mode 100644 packages/components/src/components/FileUpload/index.ts
 create mode 100644 packages/components/src/components/FileUpload/intl.json
 create mode 100644 packages/components/src/components/FileUpload/locales.test.tsx
 create mode 100644 packages/components/src/components/FileUpload/locales.ts
 create mode 100644 packages/components/src/components/FileUpload/primitives.test.tsx
 create mode 100644 packages/components/src/components/FileUpload/types.ts
 create mode 100644 packages/components/src/components/FileUpload/utils.ts
 create mode 100644 packages/components/src/components/FileUpload/validators.ts
 create mode 100644 tools/public_api_guard/components/FileUpload.api.md

diff --git a/packages/components/src/components/FileUpload/FileUpload.mdx b/packages/components/src/components/FileUpload/FileUpload.mdx
new file mode 100644
index 00000000..44a45cbe
--- /dev/null
+++ b/packages/components/src/components/FileUpload/FileUpload.mdx
@@ -0,0 +1,284 @@
+import {
+  Meta,
+  Story,
+  Props,
+  Status,
+} from '../../../../../.storybook/components';
+
+import * as Stories from './FileUpload.stories';
+
+<Meta of={Stories} />
+
+# FileUpload
+
+<Status variant="experimental" />
+
+Allows the user to upload files to the product. It ships as two components:
+`SingleFileUpload` (holds at most one file) and `MultipleFileUpload` (an ordered
+list of files). Files can be dragged into the upload area or picked through the
+system dialog; dropped folders are expanded recursively and each file is stamped
+with its `fullPath`.
+
+Validation is **external**: the component never filters, dedupes, or limits
+files, and `accept` is only forwarded to the native input as a browse hint — it
+is _not_ enforced on drop. Use the shipped helpers (`maxFileSize`,
+`isCorrectExtension`) in your `onChange`.
+
+## Import
+
+```tsx
+import { SingleFileUpload, MultipleFileUpload } from '@koobiq/react-components';
+```
+
+## Usage
+
+Selecting or dropping a file replaces the current one; removing it clears the
+value. A custom `icon` can mark the selected file (for example, for images), and
+`showFileSize={false}` hides the size for the single uploader.
+
+<Story of={Stories.Overview} />
+
+## Props
+
+<Props of={Stories.Base} />
+
+## Multiple upload
+
+Multiple files can be dragged into the upload area or selected via the system
+dialog. Files are appended in selection order (duplicates allowed) and removed by
+index; the list exposes native `list` / `listitem` semantics.
+
+<Story of={Stories.Multiple} />
+<Story of={Stories.MultipleWithFiles} />
+
+### Compact variant
+
+For the multiple uploader, a compact view is available when it is empty.
+
+<Story of={Stories.MultipleCompact} />
+
+## File size
+
+When uploading multiple files, their size is always shown in the list. For the
+single uploader, displaying the file size is configured separately via
+`showFileSize` (on by default). Sizes are formatted with SI units, matching the
+Angular `KbqDataSizePipe`.
+
+<Story of={Stories.SingleWithSize} />
+
+## Icon for selected file
+
+Selected files can be given a custom icon — a static `icon` for the single
+uploader, or a per-row `renderFileIcon` for the multiple one.
+
+<Story of={Stories.MultipleCustomIcon} />
+
+## Selecting folders or files
+
+`allowed` selects the browse links and captions: `file` (default), `folder`
+(`webkitdirectory`), or `mixed` (both a file and a folder link).
+
+<Story of={Stories.AllowedTypes} />
+
+## Disabled state
+
+In the disabled state the component does not receive focus and drag-and-drop
+does not work.
+
+<Story of={Stories.MultipleDisabled} />
+
+## Error
+
+Ship `isInvalid` + `errorMessage`, and optionally a `shouldShowError` predicate
+(`showErrorOnTouched` (default), `showErrorOnSubmit`, `showErrorRequiredOnSubmit`,
+`showErrorOnDirty`). In the multiple uploader, mark the offending rows with the
+item `hasError` flag — the invalid items are highlighted and the error message is
+shown below the control.
+
+<Story of={Stories.MultipleError} />
+<Story of={Stories.MultipleErrorFilled} />
+
+## Height of the selected items list
+
+By default the list grows with the number of files. To cap it — after which the
+list scrolls — set the `--fileupload-list-max-block-size` custom property via
+`slotProps.dropArea`.
+
+<Story of={Stories.MultipleMaxHeight} />
+
+You can also give the uploader a fixed height via `slotProps.dropArea`.
+
+<Story of={Stories.MultipleFixedHeight} />
+
+## Full-screen file uploader
+
+Set `fullScreenDropzone` (a boolean, or a `DropzoneData` object to configure the
+title/caption/size). While active, the inline drop area is disabled and a
+full-viewport overlay opens whenever a file is dragged over the document;
+dropping adds the files and closes the overlay.
+
+<Story of={Stories.FullScreenDropzone} />
+
+## Upload area
+
+The drop area does not have to be the whole screen or the uploader itself — it
+can be a separate region of the page. Give the upload a `dropTargetRef` and
+connect a `LocalDropzone` to it; dragging over the host opens an overlay
+positioned over it and routes the drop into the connected component.
+
+```tsx
+const target = useRef<FileUploadDropTarget>(null);
+
+<MultipleFileUpload dropTargetRef={target} />
+<LocalDropzone connectedTo={target}>
+  <YourHostRegion />
+</LocalDropzone>;
+```
+
+<Story of={Stories.ConnectedLocalDropzone} />
+
+## Localization
+
+Captions ship for `en-US`, `ru-RU`, `pt-BR`, `es-LA` and `tk-TM`. Wrapping a
+subtree in an `I18nProvider` changes the language for every uploader inside it at
+once.
+
+<Story of={Stories.LocalizedProvider} />
+
+To override only specific labels for a single instance, pass `localeConfig`
+(highest precedence); the rest follow the active language.
+
+<Story of={Stories.LocalizedConfig} />
+
+## Progress
+
+While an item's `loading` flag is set, its icon is replaced by a progress
+indicator bound to `progress` (0–100). Drive progress by updating the value
+**immutably**.
+
+<Story of={Stories.Loading} />
+
+Use `progressMode="indeterminate"` when the progress is unknown.
+
+<Story of={Stories.IndeterminateLoading} />
+
+Because `loading` / `progress` / `hasError` are plain fields, you can model
+post-upload processing — for example, flag a file as errored once a background
+check completes.
+
+<Story of={Stories.Processing} />
+
+## Forms
+
+The controlled `value` / `onChange` / `onBlur` API plugs into any form library.
+Feed the field's validity into `isInvalid` / `errorMessage` and gate visibility
+with `shouldShowError`.
+
+### Native controlled form
+
+<Story of={Stories.NativeForm} />
+
+### React Hook Form
+
+```tsx
+import { Controller, useForm } from 'react-hook-form';
+import { SingleFileUpload, type FileItem } from '@koobiq/react-components';
+
+const { control } = useForm<{ file: FileItem | null }>();
+
+<Controller
+  name="file"
+  control={control}
+  rules={{ required: 'A file is required' }}
+  render={({ field, fieldState, formState }) => (
+    <SingleFileUpload
+      value={field.value ?? null}
+      onChange={field.onChange}
+      onBlur={field.onBlur}
+      isInvalid={fieldState.invalid}
+      errorMessage={fieldState.error?.message}
+      shouldShowError={() => fieldState.isTouched || formState.isSubmitted}
+    />
+  )}
+/>;
+```
+
+### Formik
+
+```tsx
+import { useField } from 'formik';
+import { MultipleFileUpload, type FileItem } from '@koobiq/react-components';
+
+const [field, meta, helpers] = useField<FileItem[]>('files');
+
+<MultipleFileUpload
+  value={field.value}
+  onChange={helpers.setValue}
+  onBlur={() => helpers.setTouched(true)}
+  isInvalid={Boolean(meta.error)}
+  errorMessage={meta.error}
+  shouldShowError={() => meta.touched}
+/>;
+```
+
+## Validation
+
+Validation is the app's responsibility. Run a validator in `onChange` and feed
+the result into `isInvalid` / `errorMessage`. The shipped helpers (`maxFileSize`,
+`isCorrectExtension`) mirror the Angular `FileValidators`.
+
+### Required
+
+<Story of={Stories.SingleRequired} />
+<Story of={Stories.MultipleRequired} />
+
+### File size
+
+<Story of={Stories.SingleSizeValidation} />
+<Story of={Stories.MultipleSizeValidation} />
+
+### File type or extension
+
+<Story of={Stories.SingleExtensionValidation} />
+<Story of={Stories.MultipleExtensionValidation} />
+
+### Mixed: required and extension
+
+<Story of={Stories.SingleMixedValidation} />
+<Story of={Stories.MultipleMixedValidation} />
+
+### Asynchronous
+
+Await a server-side check and set the error when it resolves; keep the item in
+its `loading` state while the check runs.
+
+<Story of={Stories.SingleAsyncValidation} />
+
+## Primitives
+
+Build a fully custom uploader from the exported primitives — `useFileList`
+(list state), `useFileDrop` (drag-and-drop), and `FileInput` (the browse link).
+
+<Story of={Stories.Primitives} />
+
+## Migrating from Angular `kbq-file-upload`
+
+- The deprecated `fileQueueChange` / `fileQueueChanged` events are **dropped** —
+  use `onChange` (plus `onFilesAdded` / `onFileRemoved`).
+- `accept` is **not** enforced on drop (it never was); validate in `onChange`.
+- `allowed` defaults to `'file'` (the Angular JSDoc said `mixed`, but the code
+  default was always `File`).
+- `KbqFileItem.loading` / `progress` were RxJS `BehaviorSubject`s; in React they
+  are plain `boolean` / `number` fields — update them immutably to re-render.
+
+## Accessibility
+
+- The hidden native file input is tab-reachable; browse links are `<label>`s
+  tied to it, so activating a link opens the dialog.
+- Remove a focused file with <kbd>Backspace</kbd> or <kbd>Delete</kbd>; after the
+  list empties, focus returns to the input.
+- The truncated file name exposes its full value in a tooltip and via
+  `aria-label`.
+- `MultipleFileUpload` rows use `list` / `listitem` roles.
+- When `isDisabled`, the control is not focusable and ignores keyboard and
+  drag-and-drop.
diff --git a/packages/components/src/components/FileUpload/FileUpload.module.css b/packages/components/src/components/FileUpload/FileUpload.module.css
new file mode 100644
index 00000000..08b6db25
--- /dev/null
+++ b/packages/components/src/components/FileUpload/FileUpload.module.css
@@ -0,0 +1,116 @@
+.root {
+  display: flex;
+  flex-direction: column;
+  gap: var(--kbq-size-xs);
+  inline-size: 100%;
+}
+
+.dropArea {
+  display: flex;
+  flex-direction: var(--fileupload-drop-direction, row);
+  align-items: var(--fileupload-drop-align, center);
+  justify-content: var(--fileupload-drop-justify, flex-start);
+  box-sizing: border-box;
+  inline-size: 100%;
+  min-block-size: var(--fileupload-drop-min-block-size, 44px);
+
+  /* Container padding subtracts the border width so the dashed border never
+     shifts the content (mirrors the Angular `calc(padding - border-width)`). */
+  padding-block: var(
+    --fileupload-drop-padding-block,
+    calc(var(--kbq-size-m) - 1px)
+  );
+  padding-inline: var(
+    --fileupload-drop-padding-inline,
+    calc(var(--kbq-size-l) - 1px)
+  );
+  border: 1px dashed var(--kbq-line-contrast-fade);
+  border-radius: var(--kbq-size-s);
+  background-color: var(--kbq-background-bg);
+  transition:
+    border-color 100ms ease-in-out,
+    background-color 100ms ease-in-out;
+}
+
+.dropArea[data-invalid] {
+  border-color: var(--kbq-line-error, var(--kbq-foreground-error));
+  background-color: var(--kbq-background-error-less);
+}
+
+.dropArea[data-dragover] {
+  border-color: var(--kbq-line-theme-fade);
+  background-color: var(--kbq-background-theme-fade);
+}
+
+.dropArea[data-disabled] {
+  cursor: not-allowed;
+  border-color: var(--kbq-states-line-disabled);
+  background-color: var(--kbq-states-background-disabled);
+}
+
+.dropArea[data-disabled] .dropzone,
+.dropArea[data-disabled] .caption,
+.dropArea[data-disabled] .captionText {
+  color: var(--kbq-states-foreground-disabled);
+}
+
+.dropArea[data-disabled] .dropzoneIcon {
+  color: var(--kbq-states-icon-disabled);
+}
+
+.dropzone {
+  display: flex;
+  align-items: baseline;
+  gap: var(--kbq-size-s);
+  color: var(--kbq-foreground-contrast);
+}
+
+.dropzoneIcon {
+  flex-shrink: 0;
+  color: var(
+    --kbq-icon-contrast-fade,
+    var(--kbq-foreground-contrast-secondary)
+  );
+}
+
+.caption {
+  color: var(--kbq-foreground-contrast);
+}
+
+.captionText {
+  color: var(--kbq-foreground-contrast);
+}
+
+.browseLink {
+  cursor: pointer;
+  color: var(--kbq-foreground-theme, var(--kbq-foreground-contrast));
+  text-decoration: none;
+}
+
+.browseLink:hover {
+  text-decoration: underline;
+}
+
+.browseLink:has(input:focus-visible) {
+  border-radius: var(--kbq-size-xxs);
+  outline: 2px solid var(--kbq-states-focus-color, currentColor);
+  outline-offset: 2px;
+  text-decoration: underline;
+}
+
+.browseLinkDisabled {
+  cursor: not-allowed;
+  color: var(--kbq-states-foreground-disabled);
+}
+
+.browseLinkDisabled:hover {
+  text-decoration: none;
+}
+
+.hint {
+  color: var(--kbq-foreground-contrast-secondary);
+}
+
+.error {
+  color: var(--kbq-foreground-error);
+}
diff --git a/packages/components/src/components/FileUpload/FileUpload.stories.tsx b/packages/components/src/components/FileUpload/FileUpload.stories.tsx
new file mode 100644
index 00000000..cae42a31
--- /dev/null
+++ b/packages/components/src/components/FileUpload/FileUpload.stories.tsx
@@ -0,0 +1,692 @@
+import { useRef, useState } from 'react';
+import type { CSSProperties } from 'react';
+
+import { I18nProvider } from '@koobiq/react-core';
+import { IconFileO16 } from '@koobiq/react-icons';
+import type { Meta, StoryObj } from '@storybook/react';
+
+import { Button } from '../Button';
+import { FlexBox } from '../FlexBox';
+
+import { FileInput } from './components/FileInput';
+import { LocalDropzone } from './components/LocalDropzone';
+import { useFileDrop } from './hooks/useFileDrop';
+import { useFileList } from './hooks/useFileList';
+import { ruRUFileUploadConfig } from './locales';
+import { MultipleFileUpload } from './MultipleFileUpload';
+import { SingleFileUpload } from './SingleFileUpload';
+import type { FileItem, FileUploadDropTarget } from './types';
+import { formatDataSize, mapToFileItem } from './utils';
+import { isCorrectExtension, maxFileSize } from './validators';
+
+const mockFile = (name: string, bytes = 24_576, type = ''): File =>
+  new File([new Uint8Array(bytes)], name, { type });
+
+const mockItem = (name: string, bytes?: number): FileItem => ({
+  file: mockFile(name, bytes),
+  loading: false,
+  progress: 0,
+});
+
+const meta = {
+  title: 'Components/FileUpload',
+  component: SingleFileUpload,
+  subcomponents: { MultipleFileUpload },
+  tags: ['status:new', 'date:2026-07-09'],
+  parameters: { layout: 'padded' },
+} satisfies Meta<typeof SingleFileUpload>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+// --- validation helpers -------------------------------------------------------
+// Validation is external: run a validator in `onChange` and feed the result into
+// `isInvalid` / `errorMessage`. These small components back the validation
+// stories below.
+
+/** Single upload that validates each picked file inline. */
+function SingleValidated({
+  isValid,
+  message,
+}: {
+  isValid: (file: File) => boolean;
+  message: string;
+}) {
+  const [error, setError] = useState<string>();
+
+  return (
+    <div style={{ inlineSize: 360 }}>
+      <SingleFileUpload
+        isInvalid={!!error}
+        errorMessage={error}
+        shouldShowError={() => !!error}
+        onChange={(item) =>
+          setError(item && !isValid(item.file) ? message : undefined)
+        }
+      />
+    </div>
+  );
+}
+
+/** Multiple upload that flags each invalid row and shows a control-level message. */
+function MultipleValidated({
+  isValid,
+  message,
+}: {
+  isValid: (file: File) => boolean;
+  message: string;
+}) {
+  const [items, setItems] = useState<FileItem[]>([]);
+  const [error, setError] = useState<string>();
+
+  const handleChange = (next: FileItem[]) => {
+    let hasInvalid = false;
+
+    const marked = next.map((item) => {
+      const invalid = !isValid(item.file);
+
+      if (invalid) {
+        hasInvalid = true;
+      }
+
+      return { ...item, hasError: invalid };
+    });
+
+    setItems(marked);
+    setError(hasInvalid ? message : undefined);
+  };
+
+  return (
+    <div style={{ inlineSize: 420 }}>
+      <MultipleFileUpload
+        value={items}
+        onChange={handleChange}
+        isInvalid={!!error}
+        errorMessage={error}
+        shouldShowError={() => !!error}
+      />
+    </div>
+  );
+}
+
+/** Single upload inside a form; the error is revealed on submit. */
+function SingleForm({
+  validate,
+}: {
+  validate: (file: File | null) => string | null;
+}) {
+  const [value, setValue] = useState<FileItem | null>(null);
+  const [submitted, setSubmitted] = useState(false);
+  const error = submitted ? validate(value?.file ?? null) : null;
+
+  return (
+    <form
+      style={{ inlineSize: 360, display: 'grid', gap: 'var(--kbq-size-l)' }}
+      onSubmit={(event) => {
+        event.preventDefault();
+        setSubmitted(true);
+      }}
+    >
+      <SingleFileUpload
+        value={value}
+        onChange={setValue}
+        isInvalid={!!error}
+        errorMessage={error ?? undefined}
+        shouldShowError={() => !!error}
+      />
+      <Button type="submit">Submit</Button>
+    </form>
+  );
+}
+
+/** Multiple upload inside a form; the error is revealed on submit. */
+function MultipleForm({
+  validate,
+}: {
+  validate: (files: File[]) => string | null;
+}) {
+  const [items, setItems] = useState<FileItem[]>([]);
+  const [submitted, setSubmitted] = useState(false);
+  const error = submitted ? validate(items.map((item) => item.file)) : null;
+
+  return (
+    <form
+      style={{ inlineSize: 420, display: 'grid', gap: 'var(--kbq-size-l)' }}
+      onSubmit={(event) => {
+        event.preventDefault();
+        setSubmitted(true);
+      }}
+    >
+      <MultipleFileUpload
+        value={items}
+        onChange={setItems}
+        isInvalid={!!error}
+        errorMessage={error ?? undefined}
+        shouldShowError={() => !!error}
+      />
+      <Button type="submit">Submit</Button>
+    </form>
+  );
+}
+
+// --- stories ------------------------------------------------------------------
+
+export const Base: Story = {
+  args: { allowed: 'file' },
+  render: (args) => (
+    <div style={{ inlineSize: 360 }}>
+      <SingleFileUpload {...args} />
+    </div>
+  ),
+};
+
+export const Overview: Story = {
+  render: () => (
+    <div style={{ inlineSize: 360 }}>
+      <SingleFileUpload
+        defaultValue={mockItem('annual-review.pdf')}
+        icon={<IconFileO16 />}
+        showFileSize={false}
+      />
+    </div>
+  ),
+};
+
+export const Multiple: Story = {
+  render: () => (
+    <div style={{ inlineSize: 420 }}>
+      <MultipleFileUpload />
+    </div>
+  ),
+};
+
+export const MultipleWithFiles: Story = {
+  render: () => (
+    <div style={{ inlineSize: 420 }}>
+      <MultipleFileUpload
+        defaultValue={[
+          mockItem('design-spec.fig', 262_144),
+          mockItem('handoff.pdf', 524_288),
+          mockItem('cover-image.png', 131_072),
+        ]}
+      />
+    </div>
+  ),
+};
+
+export const MultipleCompact: Story = {
+  render: () => (
+    <div style={{ inlineSize: 420 }}>
+      <MultipleFileUpload size="compact" />
+    </div>
+  ),
+};
+
+export const SingleWithSize: Story = {
+  render: () => (
+    <div style={{ inlineSize: 360 }}>
+      <SingleFileUpload defaultValue={mockItem('quarterly-report-final.pdf')} />
+    </div>
+  ),
+};
+
+export const MultipleCustomIcon: Story = {
+  render: () => (
+    <div style={{ inlineSize: 420 }}>
+      <MultipleFileUpload
+        defaultValue={[
+          mockItem('photo-1.png', 131_072),
+          mockItem('photo-2.jpg', 262_144),
+        ]}
+        renderFileIcon={() => <IconFileO16 />}
+      />
+    </div>
+  ),
+};
+
+export const AllowedTypes: Story = {
+  parameters: { layout: 'padded' },
+  render: () => (
+    <FlexBox gap="xl" wrap="wrap" alignItems="flex-start">
+      {(['file', 'folder', 'mixed'] as const).map((allowed) => (
+        <div key={allowed} style={{ inlineSize: 320 }}>
+          <SingleFileUpload
+            allowed={allowed}
+            caption={`allowed="${allowed}"`}
+          />
+        </div>
+      ))}
+    </FlexBox>
+  ),
+};
+
+export const MultipleDisabled: Story = {
+  render: () => (
+    <div style={{ inlineSize: 420 }}>
+      <MultipleFileUpload
+        isDisabled
+        defaultValue={[mockItem('locked-1.pdf'), mockItem('locked-2.pdf')]}
+      />
+    </div>
+  ),
+};
+
+export const MultipleError: Story = {
+  render: () => (
+    <div style={{ inlineSize: 420 }}>
+      <MultipleFileUpload
+        isInvalid
+        errorMessage="Something is wrong with your selection."
+        shouldShowError={() => true}
+      />
+    </div>
+  ),
+};
+
+export const MultipleErrorFilled: Story = {
+  render: () => (
+    <div style={{ inlineSize: 420 }}>
+      <MultipleFileUpload
+        defaultValue={[
+          mockItem('valid-file.pdf', 262_144),
+          { ...mockItem('too-large.zip', 4_194_304), hasError: true },
+          mockItem('cover.png', 131_072),
+        ]}
+        isInvalid
+        errorMessage="“too-large.zip” exceeds the size limit."
+        shouldShowError={() => true}
+      />
+    </div>
+  ),
+};
+
+export const MultipleMaxHeight: Story = {
+  render: () => (
+    <div style={{ inlineSize: 420 }}>
+      <MultipleFileUpload
+        defaultValue={Array.from({ length: 9 }, (_, index) =>
+          mockItem(`document-${index + 1}.pdf`, 131_072 * (index + 1))
+        )}
+        slotProps={{
+          dropArea: {
+            style: {
+              '--fileupload-list-max-block-size': '240px',
+            } as CSSProperties,
+          },
+        }}
+      />
+    </div>
+  ),
+};
+
+export const MultipleFixedHeight: Story = {
+  render: () => (
+    <div style={{ inlineSize: 420 }}>
+      <MultipleFileUpload
+        defaultValue={[
+          mockItem('spec.pdf', 262_144),
+          mockItem('draft.docx', 131_072),
+        ]}
+        slotProps={{ dropArea: { style: { blockSize: 320 } } }}
+      />
+    </div>
+  ),
+};
+
+export const FullScreenDropzone: Story = {
+  render: () => (
+    <div style={{ inlineSize: 420 }}>
+      <MultipleFileUpload
+        fullScreenDropzone={{
+          title: 'Drop files anywhere',
+          caption: 'Release to upload',
+        }}
+      />
+    </div>
+  ),
+};
+
+export const ConnectedLocalDropzone: Story = {
+  render: function Render() {
+    const target = useRef<FileUploadDropTarget>(null);
+
+    return (
+      <FlexBox gap="3xl" alignItems="flex-start">
+        <div style={{ inlineSize: 360 }}>
+          <MultipleFileUpload dropTargetRef={target} />
+        </div>
+        <LocalDropzone
+          connectedTo={target}
+          config={{ title: 'Drop onto the card' }}
+        >
+          <div
+            style={{
+              inlineSize: 240,
+              blockSize: 160,
+              display: 'grid',
+              placeItems: 'center',
+              borderRadius: 'var(--kbq-size-s)',
+              border: '1px dashed var(--kbq-line-contrast-less)',
+            }}
+          >
+            Drag files over this card
+          </div>
+        </LocalDropzone>
+      </FlexBox>
+    );
+  },
+};
+
+export const LocalizedProvider: Story = {
+  render: () => (
+    <I18nProvider locale="ru-RU">
+      <div style={{ inlineSize: 420 }}>
+        <MultipleFileUpload />
+      </div>
+    </I18nProvider>
+  ),
+};
+
+export const LocalizedConfig: Story = {
+  render: () => (
+    <div style={{ inlineSize: 420 }}>
+      <MultipleFileUpload localeConfig={ruRUFileUploadConfig.multiple} />
+    </div>
+  ),
+};
+
+export const Loading: Story = {
+  render: function Render() {
+    const [value, setValue] = useState<FileItem | null>({
+      file: mockFile('uploading.mov', 8_388_608),
+      loading: true,
+      progress: 62,
+    });
+
+    return (
+      <div style={{ inlineSize: 360 }}>
+        <SingleFileUpload value={value} onChange={setValue} />
+      </div>
+    );
+  },
+};
+
+export const IndeterminateLoading: Story = {
+  render: () => (
+    <div style={{ inlineSize: 360 }}>
+      <SingleFileUpload
+        progressMode="indeterminate"
+        defaultValue={{
+          file: mockFile('processing.zip', 4_194_304),
+          loading: true,
+          progress: 0,
+        }}
+      />
+    </div>
+  ),
+};
+
+export const Processing: Story = {
+  render: function Render() {
+    const [value, setValue] = useState<FileItem | null>(null);
+
+    const handleChange = (item: FileItem | null) => {
+      if (!item) {
+        setValue(null);
+
+        return;
+      }
+
+      // Simulate an upload that finishes, then flags a processing issue.
+      setValue({ ...item, loading: true, progress: 0 });
+
+      setTimeout(
+        () => setValue({ ...item, loading: false, hasError: true }),
+        1500
+      );
+    };
+
+    return (
+      <div style={{ inlineSize: 360 }}>
+        <SingleFileUpload
+          value={value}
+          onChange={handleChange}
+          isInvalid={!!value?.hasError}
+          errorMessage="Processing found an issue with this file."
+          shouldShowError={() => !!value?.hasError}
+        />
+      </div>
+    );
+  },
+};
+
+export const NativeForm: Story = {
+  render: function Render() {
+    const [value, setValue] = useState<FileItem | null>(null);
+    const [touched, setTouched] = useState(false);
+    const [submitted, setSubmitted] = useState<string | null>(null);
+    const required = touched && !value;
+
+    return (
+      <form
+        style={{ inlineSize: 360, display: 'grid', gap: 'var(--kbq-size-l)' }}
+        onSubmit={(event) => {
+          event.preventDefault();
+          setTouched(true);
+
+          if (value) {
+            setSubmitted(value.file.name);
+          }
+        }}
+      >
+        <SingleFileUpload
+          value={value}
+          onChange={setValue}
+          onBlur={() => setTouched(true)}
+          isInvalid={required}
+          errorMessage="A file is required."
+          shouldShowError={() => required}
+        />
+        <Button type="submit">Upload</Button>
+        {submitted ? <span>Submitted: {submitted}</span> : null}
+      </form>
+    );
+  },
+};
+
+export const SingleRequired: Story = {
+  render: () => (
+    <SingleForm validate={(file) => (file ? null : 'A file is required.')} />
+  ),
+};
+
+export const MultipleRequired: Story = {
+  render: () => (
+    <MultipleForm
+      validate={(files) => (files.length ? null : 'Add at least one file.')}
+    />
+  ),
+};
+
+export const SingleSizeValidation: Story = {
+  render: () => (
+    <SingleValidated
+      isValid={(file) => !maxFileSize(500_000)(file)}
+      message="The file must be 500 KB or smaller."
+    />
+  ),
+};
+
+export const MultipleSizeValidation: Story = {
+  render: () => (
+    <MultipleValidated
+      isValid={(file) => !maxFileSize(500_000)(file)}
+      message="Some files are larger than 500 KB."
+    />
+  ),
+};
+
+export const SingleExtensionValidation: Story = {
+  render: () => (
+    <SingleValidated
+      isValid={(file) => !isCorrectExtension(['.png', '.jpg'])(file)}
+      message="Only PNG or JPG files are allowed."
+    />
+  ),
+};
+
+export const MultipleExtensionValidation: Story = {
+  render: () => (
+    <MultipleValidated
+      isValid={(file) => !isCorrectExtension(['.png', '.jpg'])(file)}
+      message="Only PNG or JPG files are allowed."
+    />
+  ),
+};
+
+export const SingleMixedValidation: Story = {
+  render: () => (
+    <SingleForm
+      validate={(file) => {
+        if (!file) {
+          return 'A file is required.';
+        }
+
+        if (isCorrectExtension(['.pdf'])(file)) {
+          return 'Only PDF files are allowed.';
+        }
+
+        return null;
+      }}
+    />
+  ),
+};
+
+export const MultipleMixedValidation: Story = {
+  render: () => (
+    <MultipleForm
+      validate={(files) => {
+        if (!files.length) {
+          return 'Add at least one file.';
+        }
+
+        if (files.some((file) => isCorrectExtension(['.pdf'])(file))) {
+          return 'Only PDF files are allowed.';
+        }
+
+        return null;
+      }}
+    />
+  ),
+};
+
+export const SingleAsyncValidation: Story = {
+  render: function Render() {
+    const [value, setValue] = useState<FileItem | null>(null);
+    const [checking, setChecking] = useState(false);
+    const [error, setError] = useState<string>();
+
+    const handleChange = (item: FileItem | null) => {
+      setValue(item);
+      setError(undefined);
+
+      if (!item) {
+        return;
+      }
+
+      // Simulate an asynchronous server-side content check.
+      setChecking(true);
+
+      setTimeout(() => {
+        setChecking(false);
+
+        setError(
+          item.file.size > 300_000
+            ? 'The file did not pass the server check.'
+            : undefined
+        );
+      }, 1200);
+    };
+
+    return (
+      <div style={{ inlineSize: 360 }}>
+        <SingleFileUpload
+          value={value ? { ...value, loading: checking } : null}
+          onChange={handleChange}
+          isInvalid={!!error}
+          errorMessage={error}
+          shouldShowError={() => !!error}
+        />
+      </div>
+    );
+  },
+};
+
+export const Primitives: Story = {
+  render: function Render() {
+    const fileList = useFileList<FileItem>({ defaultList: [] });
+
+    const { dropRef } = useFileDrop<HTMLDivElement>({
+      onFilesDropped: (files) => fileList.addArray(files.map(mapToFileItem)),
+    });
+
+    return (
+      <div
+        ref={dropRef}
+        style={{
+          inlineSize: 420,
+          display: 'grid',
+          gap: 'var(--kbq-size-s)',
+          padding: 'var(--kbq-size-l)',
+          borderRadius: 'var(--kbq-size-s)',
+          border: '1px dashed var(--kbq-line-contrast-fade)',
+        }}
+      >
+        <FileInput
+          multiple
+          accept="image/*"
+          onChange={(event) =>
+            fileList.addArray(
+              Array.from(event.target.files ?? []).map(mapToFileItem)
+            )
+          }
+        >
+          Browse or drop images
+        </FileInput>
+        {fileList.list.length > 0 ? (
+          <ul
+            style={{
+              margin: 0,
+              padding: 0,
+              listStyle: 'none',
+              display: 'grid',
+              gap: 'var(--kbq-size-xxs)',
+            }}
+          >
+            {fileList.list.map((item, index) => (
+              <li
+                key={index}
+                style={{
+                  display: 'flex',
+                  gap: 'var(--kbq-size-s)',
+                  alignItems: 'center',
+                }}
+              >
+                <span style={{ flex: 1 }}>{item.file.name}</span>
+                <span>{formatDataSize(item.file.size)}</span>
+                <button
+                  type="button"
+                  aria-label={`Remove ${item.file.name}`}
+                  onClick={() => fileList.removeAt(index)}
+                >
+                  ×
+                </button>
+              </li>
+            ))}
+          </ul>
+        ) : null}
+      </div>
+    );
+  },
+};
diff --git a/packages/components/src/components/FileUpload/FileUploadContext.ts b/packages/components/src/components/FileUpload/FileUploadContext.ts
new file mode 100644
index 00000000..ed0c7e46
--- /dev/null
+++ b/packages/components/src/components/FileUpload/FileUploadContext.ts
@@ -0,0 +1,25 @@
+'use client';
+
+import { createContext, useContext } from 'react';
+
+/** Configuration published to descendant upload primitives. */
+export interface FileUploadContextValue {
+  /** Id applied to the underlying file input. */
+  id?: string | null;
+  /** Whether interaction is disabled. */
+  isDisabled?: boolean | null;
+  /** Whether multiple selection is allowed. */
+  multiple?: boolean | null;
+  /** Native-input `accept` specifiers (already joined). */
+  accept?: string | null;
+  /** Whether the input selects directories (`webkitdirectory`). */
+  directory?: boolean | null;
+}
+
+export const FileUploadContext = createContext<FileUploadContextValue | null>(
+  null
+);
+
+/** Reads the nearest {@link FileUploadContext}, if any. */
+export const useFileUploadContext = (): FileUploadContextValue | null =>
+  useContext(FileUploadContext);
diff --git a/packages/components/src/components/FileUpload/MultipleFileUpload.module.css b/packages/components/src/components/FileUpload/MultipleFileUpload.module.css
new file mode 100644
index 00000000..cd8f1847
--- /dev/null
+++ b/packages/components/src/components/FileUpload/MultipleFileUpload.module.css
@@ -0,0 +1,73 @@
+/* Multiple upload tunes the shared drop-area via custom properties (order-safe).
+   Spacing values mirror the Angular multiple container geometry. */
+.dropArea {
+  --fileupload-drop-direction: column;
+  --fileupload-drop-align: stretch;
+  --fileupload-drop-justify: flex-start;
+  --fileupload-drop-min-block-size: 120px;
+  --fileupload-drop-padding-block: 0;
+  --fileupload-drop-padding-inline: 0;
+}
+
+/* Default-size empty state: a centered 320×192 drop target, matching the
+   Angular "big" empty container. */
+.dropArea[data-size='default'][data-empty] {
+  --fileupload-drop-align: center;
+  --fileupload-drop-justify: center;
+  --fileupload-drop-min-block-size: 192px;
+
+  min-inline-size: 320px;
+}
+
+.compact {
+  --fileupload-drop-direction: row;
+  --fileupload-drop-align: center;
+  --fileupload-drop-justify: flex-start;
+  --fileupload-drop-min-block-size: auto;
+  --fileupload-drop-padding-block: 11px;
+  --fileupload-drop-padding-inline: 15px;
+}
+
+.emptyState {
+  inline-size: 100%;
+}
+
+.wrapper {
+  display: flex;
+  flex-direction: column;
+  inline-size: 100%;
+  block-size: 100%;
+}
+
+.list {
+  display: flex;
+  flex-direction: column;
+  gap: var(--kbq-size-xs);
+  min-block-size: 120px;
+
+  /* Uncapped by default (the list grows with its content, matching the Angular
+     `--kbq-file-upload-size-multiple-max-height: unset`). Set the custom property
+     to cap the height and enable scrolling. */
+  max-block-size: var(--fileupload-list-max-block-size, none);
+  margin: 0;
+  padding: 0;
+
+  /* Angular list padding-top: xxs minus the container border width. */
+  padding-block-start: calc(var(--kbq-size-xxs) - 1px);
+  overflow-y: auto;
+  list-style: none;
+}
+
+.listItem {
+  display: flex;
+  inline-size: 100%;
+  padding-inline: calc(var(--kbq-size-xxs) - 1px);
+}
+
+/* Footer dropzone below the list, separated by the dashed divider. */
+.footer {
+  justify-content: flex-start;
+  padding-block: var(--kbq-size-m);
+  padding-inline: var(--kbq-size-l);
+  border-block-start: 1px dashed var(--kbq-line-contrast-fade);
+}
diff --git a/packages/components/src/components/FileUpload/MultipleFileUpload.test.tsx b/packages/components/src/components/FileUpload/MultipleFileUpload.test.tsx
new file mode 100644
index 00000000..3c7dacdc
--- /dev/null
+++ b/packages/components/src/components/FileUpload/MultipleFileUpload.test.tsx
@@ -0,0 +1,173 @@
+import {
+  cleanup,
+  fireEvent,
+  render,
+  screen,
+  waitFor,
+  within,
+} from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { MultipleFileUpload } from './MultipleFileUpload';
+import type { FileItem } from './types';
+
+afterEach(cleanup);
+
+const makeItem = (name: string): FileItem => ({
+  file: new File(['content'], name, { type: 'text/plain' }),
+  loading: false,
+  progress: 0,
+});
+
+const getFileInput = (): HTMLInputElement =>
+  document.querySelector('input[type="file"]') as HTMLInputElement;
+
+const getDropArea = (container: HTMLElement): HTMLElement =>
+  container.querySelector('[class*="dropArea"]') as HTMLElement;
+
+const dataTransferWith = (files: File[]) =>
+  ({
+    items: files.map((file) => ({
+      kind: 'file',
+      webkitGetAsEntry: () => ({
+        isFile: true,
+        isDirectory: false,
+        fullPath: `/${file.name}`,
+        file: (cb: (f: File) => void) => cb(file),
+      }),
+    })),
+    files,
+  }) as unknown as DataTransfer;
+
+describe('MultipleFileUpload', () => {
+  it('appends selected files and emits change + added', async () => {
+    const onChange = vi.fn();
+    const onFilesAdded = vi.fn();
+
+    render(
+      <MultipleFileUpload onChange={onChange} onFilesAdded={onFilesAdded} />
+    );
+
+    const a = new File(['a'], 'a.txt');
+    const b = new File(['b'], 'b.txt');
+
+    await userEvent.upload(getFileInput(), [a, b]);
+
+    expect(onChange.mock.calls.at(-1)?.[0]).toHaveLength(2);
+    expect(onFilesAdded.mock.calls.at(-1)?.[0]).toHaveLength(2);
+    expect(screen.getByLabelText('a.txt')).toBeInTheDocument();
+    expect(screen.getByLabelText('b.txt')).toBeInTheDocument();
+  });
+
+  it('exposes list and listitem semantics', () => {
+    render(
+      <MultipleFileUpload
+        defaultValue={[makeItem('a.txt'), makeItem('b.txt')]}
+      />
+    );
+
+    const list = screen.getByRole('list');
+
+    expect(within(list).getAllByRole('listitem')).toHaveLength(2);
+  });
+
+  it('allows duplicates and re-selecting the same file', async () => {
+    const onChange = vi.fn();
+
+    render(<MultipleFileUpload onChange={onChange} />);
+
+    const file = new File(['a'], 'a.txt');
+
+    await userEvent.upload(getFileInput(), file);
+    // The footer browse input persists once files exist.
+    await userEvent.upload(getFileInput(), file);
+
+    expect(onChange.mock.calls.at(-1)?.[0]).toHaveLength(2);
+  });
+
+  it('removes by index and emits the removed item and index', async () => {
+    const onFileRemoved = vi.fn();
+    const first = makeItem('a.txt');
+    const second = makeItem('b.txt');
+
+    render(
+      <MultipleFileUpload
+        defaultValue={[first, second]}
+        onFileRemoved={onFileRemoved}
+      />
+    );
+
+    const removeButtons = screen.getAllByRole('button', { name: /remove/i });
+
+    await userEvent.click(removeButtons[0]!);
+
+    expect(onFileRemoved).toHaveBeenCalledWith(first, 0);
+    expect(screen.queryByLabelText('a.txt')).not.toBeInTheDocument();
+    expect(screen.getByLabelText('b.txt')).toBeInTheDocument();
+  });
+
+  it('removes the focused row with the Delete key', async () => {
+    const onFileRemoved = vi.fn();
+    const first = makeItem('a.txt');
+
+    render(
+      <MultipleFileUpload
+        defaultValue={[first, makeItem('b.txt')]}
+        onFileRemoved={onFileRemoved}
+      />
+    );
+
+    const removeButtons = screen.getAllByRole('button', { name: /remove/i });
+
+    removeButtons[0]!.focus();
+    await userEvent.keyboard('{Delete}');
+
+    expect(onFileRemoved).toHaveBeenCalledWith(first, 0);
+  });
+
+  it('appends all dropped files', async () => {
+    const onChange = vi.fn();
+    const { container } = render(<MultipleFileUpload onChange={onChange} />);
+
+    fireEvent.drop(getDropArea(container), {
+      dataTransfer: dataTransferWith([
+        new File(['a'], 'a.txt'),
+        new File(['b'], 'b.txt'),
+      ]),
+    });
+
+    await waitFor(() =>
+      expect(onChange.mock.calls.at(-1)?.[0]).toHaveLength(2)
+    );
+  });
+
+  it('renders a compact empty state', () => {
+    const { container } = render(<MultipleFileUpload size="compact" />);
+
+    expect(getDropArea(container)).toHaveAttribute('data-size', 'compact');
+    expect(screen.getByText('choose files')).toBeInTheDocument();
+  });
+
+  it('is disabled: input disabled and drops ignored', () => {
+    const onChange = vi.fn();
+
+    const { container } = render(
+      <MultipleFileUpload isDisabled onChange={onChange} />
+    );
+
+    expect(getFileInput()).toBeDisabled();
+
+    fireEvent.drop(getDropArea(container), {
+      dataTransfer: dataTransferWith([new File(['x'], 'x.txt')]),
+    });
+
+    expect(onChange).not.toHaveBeenCalled();
+  });
+
+  it('always shows the file size in rows', () => {
+    render(<MultipleFileUpload defaultValue={[makeItem('a.txt')]} />);
+
+    expect(screen.getByText(/\bB\b/)).toBeInTheDocument();
+  });
+});
diff --git a/packages/components/src/components/FileUpload/MultipleFileUpload.tsx b/packages/components/src/components/FileUpload/MultipleFileUpload.tsx
new file mode 100644
index 00000000..e201cd81
--- /dev/null
+++ b/packages/components/src/components/FileUpload/MultipleFileUpload.tsx
@@ -0,0 +1,277 @@
+'use client';
+
+import { forwardRef, useId, useImperativeHandle, useRef } from 'react';
+import type { ChangeEvent } from 'react';
+
+import { deprecate } from '@koobiq/logger';
+import {
+  clsx,
+  mergeProps,
+  useLocalizedStringFormatter,
+} from '@koobiq/react-core';
+import {
+  IconArrowUpFromBracket16,
+  IconCloudArrowUpO24,
+} from '@koobiq/react-icons';
+
+import { utilClasses } from '../../styles/utility';
+import { EmptyState } from '../EmptyState';
+
+import { FileUploadCaption } from './components/FileUploadCaption';
+import { FileUploadItem } from './components/FileUploadItem';
+import { FullScreenDropzone } from './components/FullScreenDropzone';
+import { FOCUS_RETURN_DELAY } from './constants';
+import s from './FileUpload.module.css';
+import { useFileUploadContext } from './FileUploadContext';
+import { useFileDrop } from './hooks/useFileDrop';
+import { useFileList } from './hooks/useFileList';
+import { useMultipleFileUploadLocale } from './hooks/useFileUploadLocale';
+import { useFileUploadState } from './hooks/useFileUploadState';
+import intlMessages from './intl.json';
+import sMultiple from './MultipleFileUpload.module.css';
+import type { FileItem, FileWithPath, MultipleFileUploadProps } from './types';
+import { formatDataSize, mapToFileItem } from './utils';
+
+/**
+ * MultipleFileUpload lets a user select or drop many files. Files are appended
+ * in selection order with no dedupe, limit, or validation; removal is by index.
+ * Validation is external — `accept` is a browse hint only and is not enforced on
+ * drop.
+ */
+export const MultipleFileUpload = forwardRef<
+  HTMLDivElement,
+  MultipleFileUploadProps
+>((props, ref) => {
+  const {
+    value: valueProp,
+    defaultValue,
+    onChange,
+    onFilesAdded,
+    onFileRemoved,
+    onBlur,
+    accept,
+    allowed = 'file',
+    isDisabled: isDisabledProp,
+    disabled,
+    isInvalid: isInvalidProp,
+    shouldShowError,
+    size = 'default',
+    progressMode = 'determinate',
+    inputId: inputIdProp,
+    localeConfig,
+    renderFileIcon,
+    errorMessage,
+    caption,
+    className,
+    slotProps,
+    fullScreenDropzone,
+    dropTargetRef,
+    ...other
+  } = props;
+
+  if (process.env.NODE_ENV !== 'production' && 'disabled' in props) {
+    deprecate(
+      'MultipleFileUpload: the "disabled" prop is deprecated. Use "isDisabled" prop to replace it.'
+    );
+  }
+
+  const context = useFileUploadContext();
+  const isDisabled = isDisabledProp ?? disabled ?? context?.isDisabled ?? false;
+  const isInvalid = isInvalidProp ?? false;
+  const generatedId = useId();
+  const inputId = inputIdProp ?? context?.id ?? generatedId;
+
+  const t = useLocalizedStringFormatter(intlMessages);
+
+  const fileList = useFileList<FileItem>({
+    list: valueProp,
+    defaultList: defaultValue ?? [],
+    onListChange: onChange,
+    onItemsAdded: onFilesAdded,
+    onItemRemoved: onFileRemoved,
+  });
+
+  const files = fileList.list;
+
+  const { errorState, markTouched, markDirty } = useFileUploadState({
+    isInvalid,
+    shouldShowError,
+  });
+
+  const invalid = errorState;
+
+  const { locale, config, captionContext, whenSelectedText } =
+    useMultipleFileUploadLocale({
+      allowed,
+      size,
+      hasFiles: files.length > 0,
+      localeConfig,
+    });
+
+  const browseInputRef = useRef<HTMLInputElement>(null);
+  const acceptAttr = accept?.length ? accept.join(',') : undefined;
+  const fullScreenActive = !!fullScreenDropzone;
+
+  const addFiles = (toAdd: File[]) => {
+    if (!toAdd.length) {
+      return;
+    }
+
+    fileList.addArray(toAdd.map(mapToFileItem));
+    markDirty();
+  };
+
+  const handleSelectViaClick = (event: ChangeEvent<HTMLInputElement>) => {
+    if (isDisabled) {
+      return;
+    }
+
+    addFiles(event.target.files ? Array.from(event.target.files) : []);
+    markTouched();
+  };
+
+  const handleDrop = (dropped: FileWithPath[]) => {
+    if (isDisabled) {
+      return;
+    }
+
+    addFiles(dropped);
+    markTouched();
+  };
+
+  const handleRemove = (index: number) => {
+    if (isDisabled) {
+      return;
+    }
+
+    const willBeEmpty = files.length <= 1;
+
+    fileList.removeAt(index);
+    markTouched();
+
+    if (willBeEmpty) {
+      setTimeout(() => browseInputRef.current?.focus(), FOCUS_RETURN_DELAY);
+    }
+  };
+
+  const { dropRef } = useFileDrop<HTMLDivElement>({
+    disabled: isDisabled || fullScreenActive,
+    onFilesDropped: handleDrop,
+  });
+
+  useImperativeHandle(dropTargetRef, () => ({ addFiles: handleDrop }), [
+    handleDrop,
+  ]);
+
+  const dropAreaProps = mergeProps(
+    {
+      className: clsx(
+        s.dropArea,
+        sMultiple.dropArea,
+        size === 'compact' && sMultiple.compact
+      ),
+      'data-disabled': isDisabled || undefined,
+      'data-invalid': invalid || undefined,
+      'data-size': size,
+      'data-empty': files.length === 0 || undefined,
+    },
+    slotProps?.dropArea
+  );
+
+  const captionElement = (
+    <FileUploadCaption
+      captionContext={captionContext}
+      leadingText={
+        files.length > 0 ? whenSelectedText : captionContext.captionText
+      }
+      inputId={inputId}
+      accept={acceptAttr}
+      isDisabled={isDisabled}
+      onFileSelected={handleSelectViaClick}
+      fileInputRef={browseInputRef}
+    />
+  );
+
+  const renderEmptyState = () => {
+    if (size === 'compact') {
+      return (
+        <div className={s.dropzone}>
+          <IconArrowUpFromBracket16 className={s.dropzoneIcon} />
+          {captionElement}
+        </div>
+      );
+    }
+
+    return (
+      <EmptyState
+        size="normal"
+        isInvalid={invalid}
+        className={sMultiple.emptyState}
+      >
+        <EmptyState.Media>
+          <IconCloudArrowUpO24 />
+        </EmptyState.Media>
+        <EmptyState.Title>{config.title}</EmptyState.Title>
+        <EmptyState.Content>{captionElement}</EmptyState.Content>
+      </EmptyState>
+    );
+  };
+
+  return (
+    <div
+      {...other}
+      ref={ref}
+      className={clsx(s.root, className)}
+      onBlur={(event) => {
+        markTouched();
+        onBlur?.(event);
+      }}
+    >
+      <div {...dropAreaProps} ref={dropRef}>
+        {files.length === 0 ? (
+          renderEmptyState()
+        ) : (
+          <div className={sMultiple.wrapper}>
+            <ul className={clsx(sMultiple.list, utilClasses.scrollable)}>
+              {files.map((file, index) => (
+                <li key={index} className={sMultiple.listItem}>
+                  <FileUploadItem
+                    item={file}
+                    isDisabled={isDisabled}
+                    hasError={file.hasError}
+                    size={formatDataSize(file.file.size, locale)}
+                    icon={renderFileIcon?.(file)}
+                    progressMode={progressMode}
+                    removeLabel={t.format('remove')}
+                    onRemove={() => handleRemove(index)}
+                  />
+                </li>
+              ))}
+            </ul>
+            <div className={clsx(s.dropzone, sMultiple.footer)}>
+              <IconArrowUpFromBracket16 className={s.dropzoneIcon} />
+              {captionElement}
+            </div>
+          </div>
+        )}
+      </div>
+      {fullScreenActive ? (
+        <FullScreenDropzone
+          config={
+            typeof fullScreenDropzone === 'object'
+              ? fullScreenDropzone
+              : undefined
+          }
+          disabled={isDisabled}
+          onFilesDropped={handleDrop}
+        />
+      ) : null}
+      {caption ? <div className={s.hint}>{caption}</div> : null}
+      {invalid && errorMessage ? (
+        <div className={s.error}>{errorMessage}</div>
+      ) : null}
+    </div>
+  );
+});
+
+MultipleFileUpload.displayName = 'MultipleFileUpload';
diff --git a/packages/components/src/components/FileUpload/SingleFileUpload.module.css b/packages/components/src/components/FileUpload/SingleFileUpload.module.css
new file mode 100644
index 00000000..9af4bf8f
--- /dev/null
+++ b/packages/components/src/components/FileUpload/SingleFileUpload.module.css
@@ -0,0 +1,7 @@
+/* Single upload only tunes the shared drop-area via custom properties. The
+   container padding matches the Angular single container (12px/16px minus the
+   1px dashed border → 11px/15px). */
+.dropArea {
+  --fileupload-drop-padding-block: calc(var(--kbq-size-m) - 1px);
+  --fileupload-drop-padding-inline: calc(var(--kbq-size-l) - 1px);
+}
diff --git a/packages/components/src/components/FileUpload/SingleFileUpload.test.tsx b/packages/components/src/components/FileUpload/SingleFileUpload.test.tsx
new file mode 100644
index 00000000..efd5607e
--- /dev/null
+++ b/packages/components/src/components/FileUpload/SingleFileUpload.test.tsx
@@ -0,0 +1,188 @@
+import {
+  cleanup,
+  fireEvent,
+  render,
+  screen,
+  waitFor,
+} from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { SingleFileUpload } from './SingleFileUpload';
+import type { FileItem } from './types';
+
+afterEach(cleanup);
+
+const makeItem = (name = 'document.txt'): FileItem => ({
+  file: new File(['hello world'], name, { type: 'text/plain' }),
+  loading: false,
+  progress: 0,
+});
+
+const getFileInput = (): HTMLInputElement =>
+  document.querySelector('input[type="file"]') as HTMLInputElement;
+
+const getDropArea = (container: HTMLElement): HTMLElement =>
+  container.querySelector('[class*="dropArea"]') as HTMLElement;
+
+const dataTransferWith = (files: File[]) =>
+  ({
+    items: files.map((file) => ({
+      kind: 'file',
+      webkitGetAsEntry: () => ({
+        isFile: true,
+        isDirectory: false,
+        fullPath: `/${file.name}`,
+        file: (cb: (f: File) => void) => cb(file),
+      }),
+    })),
+    files,
+  }) as unknown as DataTransfer;
+
+describe('SingleFileUpload', () => {
+  it('renders an empty state with a browse link', () => {
+    render(<SingleFileUpload />);
+
+    expect(screen.getByText('choose')).toBeInTheDocument();
+    expect(getFileInput()).toBeInTheDocument();
+  });
+
+  it('selects a file and emits change', async () => {
+    const onChange = vi.fn();
+
+    render(<SingleFileUpload onChange={onChange} />);
+
+    const file = new File(['hi'], 'hi.txt', { type: 'text/plain' });
+
+    await userEvent.upload(getFileInput(), file);
+
+    expect(onChange).toHaveBeenCalledTimes(1);
+    expect(onChange.mock.calls[0]?.[0]?.file).toBe(file);
+    expect(screen.getByLabelText('hi.txt')).toBeInTheDocument();
+  });
+
+  it('replaces the file when a new one is dropped', async () => {
+    const { container } = render(
+      <SingleFileUpload defaultValue={makeItem('first.txt')} />
+    );
+
+    expect(screen.getByLabelText('first.txt')).toBeInTheDocument();
+
+    fireEvent.drop(getDropArea(container), {
+      dataTransfer: dataTransferWith([new File(['x'], 'second.txt')]),
+    });
+
+    await waitFor(() =>
+      expect(screen.getByLabelText('second.txt')).toBeInTheDocument()
+    );
+
+    expect(screen.queryByLabelText('first.txt')).not.toBeInTheDocument();
+  });
+
+  it('clears the value on remove and returns focus to the input', async () => {
+    const onChange = vi.fn();
+    const onFileRemoved = vi.fn();
+
+    render(
+      <SingleFileUpload
+        defaultValue={makeItem()}
+        onChange={onChange}
+        onFileRemoved={onFileRemoved}
+      />
+    );
+
+    await userEvent.click(screen.getByRole('button', { name: /remove/i }));
+
+    expect(onChange).toHaveBeenLastCalledWith(null);
+    expect(onFileRemoved).toHaveBeenCalledTimes(1);
+    expect(screen.getByText('choose')).toBeInTheDocument();
+
+    await waitFor(() => expect(getFileInput()).toHaveFocus());
+  });
+
+  it('adds a dropped file (accept is not enforced on drop)', async () => {
+    const onChange = vi.fn();
+
+    const { container } = render(
+      <SingleFileUpload accept={['.png']} onChange={onChange} />
+    );
+
+    const disallowed = new File(['x'], 'notes.txt', { type: 'text/plain' });
+
+    fireEvent.drop(getDropArea(container), {
+      dataTransfer: dataTransferWith([disallowed]),
+    });
+
+    await waitFor(() => expect(onChange).toHaveBeenCalled());
+    expect(onChange.mock.calls[0]?.[0]?.file.name).toBe('notes.txt');
+  });
+
+  it('toggles the drag-over attribute without clearing on descendant leave', () => {
+    const { container } = render(<SingleFileUpload />);
+    const dropArea = getDropArea(container);
+
+    fireEvent.dragEnter(dropArea);
+    expect(dropArea).toHaveAttribute('data-dragover');
+
+    // jsdom drops `relatedTarget` on synthetic DragEvents, so dispatch a
+    // MouseEvent (which carries it) to exercise the descendant guard.
+    const dragLeave = (relatedTarget: Node | null) =>
+      dropArea.dispatchEvent(
+        new MouseEvent('dragleave', { bubbles: true, relatedTarget })
+      );
+
+    // Leaving onto a descendant keeps the highlight.
+    const descendant = dropArea.querySelector('span') ?? dropArea;
+
+    dragLeave(descendant);
+    expect(dropArea).toHaveAttribute('data-dragover');
+
+    // Leaving the target clears it.
+    dragLeave(document.body);
+    expect(dropArea).not.toHaveAttribute('data-dragover');
+  });
+
+  it('is disabled: input disabled and drops are ignored', () => {
+    const onChange = vi.fn();
+
+    const { container } = render(
+      <SingleFileUpload isDisabled onChange={onChange} />
+    );
+
+    expect(getFileInput()).toBeDisabled();
+
+    fireEvent.drop(getDropArea(container), {
+      dataTransfer: dataTransferWith([new File(['x'], 'x.txt')]),
+    });
+
+    expect(onChange).not.toHaveBeenCalled();
+  });
+
+  it('shows the error message and invalid styling when the predicate allows it', () => {
+    const { container } = render(
+      <SingleFileUpload
+        defaultValue={makeItem()}
+        isInvalid
+        errorMessage="Something is wrong"
+        shouldShowError={() => true}
+      />
+    );
+
+    expect(screen.getByText('Something is wrong')).toBeInTheDocument();
+    expect(getDropArea(container)).toHaveAttribute('data-invalid');
+  });
+
+  it('hides the file size when showFileSize is false', () => {
+    render(<SingleFileUpload defaultValue={makeItem()} showFileSize={false} />);
+
+    expect(screen.queryByText(/\bB\b/)).not.toBeInTheDocument();
+  });
+
+  it('renders a controlled value and does not throw during SSR', async () => {
+    const { renderToString } = await import('react-dom/server');
+
+    expect(() =>
+      renderToString(<SingleFileUpload value={makeItem()} onChange={vi.fn()} />)
+    ).not.toThrow();
+  });
+});
diff --git a/packages/components/src/components/FileUpload/SingleFileUpload.tsx b/packages/components/src/components/FileUpload/SingleFileUpload.tsx
new file mode 100644
index 00000000..886f7efa
--- /dev/null
+++ b/packages/components/src/components/FileUpload/SingleFileUpload.tsx
@@ -0,0 +1,232 @@
+'use client';
+
+import { forwardRef, useId, useImperativeHandle, useRef } from 'react';
+import type { ChangeEvent } from 'react';
+
+import { deprecate } from '@koobiq/logger';
+import {
+  clsx,
+  mergeProps,
+  useControlledState,
+  useLocalizedStringFormatter,
+} from '@koobiq/react-core';
+import { IconArrowUpFromBracket16 } from '@koobiq/react-icons';
+
+import { FileUploadCaption } from './components/FileUploadCaption';
+import { FileUploadItem } from './components/FileUploadItem';
+import { FullScreenDropzone } from './components/FullScreenDropzone';
+import { FOCUS_RETURN_DELAY } from './constants';
+import s from './FileUpload.module.css';
+import { useFileUploadContext } from './FileUploadContext';
+import { useFileDrop } from './hooks/useFileDrop';
+import { useSingleFileUploadLocale } from './hooks/useFileUploadLocale';
+import { useFileUploadState } from './hooks/useFileUploadState';
+import intlMessages from './intl.json';
+import sSingle from './SingleFileUpload.module.css';
+import type { FileItem, FileWithPath, SingleFileUploadProps } from './types';
+import { formatDataSize, mapToFileItem } from './utils';
+
+/**
+ * SingleFileUpload lets a user select or drop a single file. Selection replaces
+ * the previous file; removal clears the value. Validation is external — `accept`
+ * is a browse hint only and is not enforced on drop.
+ */
+export const SingleFileUpload = forwardRef<
+  HTMLDivElement,
+  SingleFileUploadProps
+>((props, ref) => {
+  const {
+    value: valueProp,
+    defaultValue = null,
+    onChange,
+    onFilesAdded,
+    onFileRemoved,
+    onBlur,
+    accept,
+    allowed = 'file',
+    isDisabled: isDisabledProp,
+    disabled,
+    isInvalid: isInvalidProp,
+    shouldShowError,
+    showFileSize = true,
+    progressMode = 'determinate',
+    inputId: inputIdProp,
+    localeConfig,
+    icon,
+    errorMessage,
+    caption,
+    className,
+    slotProps,
+    fullScreenDropzone,
+    dropTargetRef,
+    ...other
+  } = props;
+
+  if (process.env.NODE_ENV !== 'production' && 'disabled' in props) {
+    deprecate(
+      'SingleFileUpload: the "disabled" prop is deprecated. Use "isDisabled" prop to replace it.'
+    );
+  }
+
+  const context = useFileUploadContext();
+  const isDisabled = isDisabledProp ?? disabled ?? context?.isDisabled ?? false;
+  const isInvalid = isInvalidProp ?? false;
+  const generatedId = useId();
+  const inputId = inputIdProp ?? context?.id ?? generatedId;
+
+  const t = useLocalizedStringFormatter(intlMessages);
+
+  const [value, setValue] = useControlledState<FileItem | null>(
+    valueProp,
+    defaultValue,
+    onChange
+  );
+
+  const { errorState, markTouched, markDirty } = useFileUploadState({
+    isInvalid,
+    shouldShowError,
+  });
+
+  const invalid = !!value?.hasError || errorState;
+
+  const { locale, captionContext } = useSingleFileUploadLocale({
+    allowed,
+    localeConfig,
+  });
+
+  const browseInputRef = useRef<HTMLInputElement>(null);
+  const acceptAttr = accept?.length ? accept.join(',') : undefined;
+  const fullScreenActive = !!fullScreenDropzone;
+
+  const selectFile = (file: File) => {
+    const item = mapToFileItem(file);
+
+    setValue(item);
+    onFilesAdded?.(item);
+    markDirty();
+  };
+
+  const handleSelectViaClick = (event: ChangeEvent<HTMLInputElement>) => {
+    if (isDisabled) {
+      return;
+    }
+
+    const file = event.target.files?.[0];
+
+    if (file) {
+      selectFile(file);
+    }
+
+    markTouched();
+  };
+
+  const handleDrop = (files: FileWithPath[]) => {
+    if (isDisabled) {
+      return;
+    }
+
+    const [first] = files;
+
+    if (first) {
+      selectFile(first);
+    }
+
+    // Mark touched after a drop even when nothing was accepted.
+    markTouched();
+  };
+
+  const handleRemove = () => {
+    if (isDisabled) {
+      return;
+    }
+
+    const removed = value;
+
+    setValue(null);
+
+    if (removed) {
+      onFileRemoved?.(removed);
+    }
+
+    markTouched();
+
+    // Return focus to the input once the empty state (with its input) re-renders.
+    setTimeout(() => browseInputRef.current?.focus(), FOCUS_RETURN_DELAY);
+  };
+
+  const { dropRef } = useFileDrop<HTMLDivElement>({
+    disabled: isDisabled || fullScreenActive,
+    onFilesDropped: handleDrop,
+  });
+
+  useImperativeHandle(dropTargetRef, () => ({ addFiles: handleDrop }), [
+    handleDrop,
+  ]);
+
+  const dropAreaProps = mergeProps(
+    {
+      className: clsx(s.dropArea, sSingle.dropArea),
+      'data-disabled': isDisabled || undefined,
+      'data-invalid': invalid || undefined,
+    },
+    slotProps?.dropArea
+  );
+
+  return (
+    <div
+      {...other}
+      ref={ref}
+      className={clsx(s.root, className)}
+      onBlur={(event) => {
+        markTouched();
+        onBlur?.(event);
+      }}
+    >
+      <div {...dropAreaProps} ref={dropRef}>
+        {value ? (
+          <FileUploadItem
+            item={value}
+            isDisabled={isDisabled}
+            hasError={invalid}
+            size={
+              showFileSize ? formatDataSize(value.file.size, locale) : undefined
+            }
+            icon={icon}
+            progressMode={progressMode}
+            removeLabel={t.format('remove')}
+            onRemove={handleRemove}
+          />
+        ) : (
+          <div className={s.dropzone}>
+            <IconArrowUpFromBracket16 className={s.dropzoneIcon} />
+            <FileUploadCaption
+              captionContext={captionContext}
+              inputId={inputId}
+              accept={acceptAttr}
+              isDisabled={isDisabled}
+              onFileSelected={handleSelectViaClick}
+              fileInputRef={browseInputRef}
+            />
+          </div>
+        )}
+      </div>
+      {fullScreenActive ? (
+        <FullScreenDropzone
+          config={
+            typeof fullScreenDropzone === 'object'
+              ? fullScreenDropzone
+              : undefined
+          }
+          disabled={isDisabled}
+          onFilesDropped={handleDrop}
+        />
+      ) : null}
+      {caption ? <div className={s.hint}>{caption}</div> : null}
+      {invalid && errorMessage ? (
+        <div className={s.error}>{errorMessage}</div>
+      ) : null}
+    </div>
+  );
+});
+
+SingleFileUpload.displayName = 'SingleFileUpload';
diff --git a/packages/components/src/components/FileUpload/components/DropzoneContent/DropzoneContent.module.css b/packages/components/src/components/FileUpload/components/DropzoneContent/DropzoneContent.module.css
new file mode 100644
index 00000000..7b2f486a
--- /dev/null
+++ b/packages/components/src/components/FileUpload/components/DropzoneContent/DropzoneContent.module.css
@@ -0,0 +1,8 @@
+.content {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  inline-size: 100%;
+  block-size: 100%;
+  outline: none;
+}
diff --git a/packages/components/src/components/FileUpload/components/DropzoneContent/DropzoneContent.tsx b/packages/components/src/components/FileUpload/components/DropzoneContent/DropzoneContent.tsx
new file mode 100644
index 00000000..9e0ad9cf
--- /dev/null
+++ b/packages/components/src/components/FileUpload/components/DropzoneContent/DropzoneContent.tsx
@@ -0,0 +1,73 @@
+'use client';
+
+import type { ReactNode } from 'react';
+
+import {
+  clsx,
+  FocusScope,
+  useLocalizedStringFormatter,
+} from '@koobiq/react-core';
+import { IconCloudArrowUpO24 } from '@koobiq/react-icons';
+
+import { EmptyState } from '../../../EmptyState';
+import intlMessages from '../../intl.json';
+import type { DropzoneContentSize } from '../../types';
+
+import s from './DropzoneContent.module.css';
+
+export interface DropzoneContentProps {
+  /** Title text; falls back to the localized default. */
+  title?: string;
+  /** Caption text or node rendered below the title. */
+  caption?: ReactNode;
+  /**
+   * Visual size of the content.
+   * @default 'normal'
+   */
+  size?: DropzoneContentSize;
+  /**
+   * Whether focus is captured into the overlay when it opens.
+   * @default true
+   */
+  autoCapture?: boolean;
+  /** Additional CSS-classes. */
+  className?: string;
+}
+
+/**
+ * The content shown inside a dropzone overlay: a cloud icon, a title, and an
+ * optional caption. Traps focus while mounted (react-aria `FocusScope`).
+ */
+export const DropzoneContent = (props: DropzoneContentProps) => {
+  const {
+    title,
+    caption,
+    size = 'normal',
+    autoCapture = true,
+    className,
+  } = props;
+
+  const t = useLocalizedStringFormatter(intlMessages);
+  const hasCaption = caption != null && caption !== '';
+
+  return (
+    <FocusScope contain autoFocus={autoCapture} restoreFocus>
+      {/* eslint-disable-next-line jsx-a11y/no-noninteractive-tabindex -- focus-trap target for the dropzone overlay (mirrors CdkTrapFocus autoCapture) */}
+      <div tabIndex={0} className={clsx(s.content, className)}>
+        <EmptyState size={size}>
+          <EmptyState.Media>
+            <IconCloudArrowUpO24 />
+          </EmptyState.Media>
+          <EmptyState.Title>
+            {title ?? t.format('dropzoneTitle')}
+          </EmptyState.Title>
+          {hasCaption ? (
+            <EmptyState.Content>{caption}</EmptyState.Content>
+          ) : null}
+        </EmptyState>
+      </div>
+    </FocusScope>
+  );
+};
+
+DropzoneContent.displayName = 'DropzoneContent';
diff --git a/packages/components/src/components/FileUpload/components/DropzoneContent/index.ts b/packages/components/src/components/FileUpload/components/DropzoneContent/index.ts
new file mode 100644
index 00000000..89af98e4
--- /dev/null
+++ b/packages/components/src/components/FileUpload/components/DropzoneContent/index.ts
@@ -0,0 +1 @@
+export * from './DropzoneContent.js';
diff --git a/packages/components/src/components/FileUpload/components/FileInput/FileInput.tsx b/packages/components/src/components/FileUpload/components/FileInput/FileInput.tsx
new file mode 100644
index 00000000..2fcd5713
--- /dev/null
+++ b/packages/components/src/components/FileUpload/components/FileInput/FileInput.tsx
@@ -0,0 +1,83 @@
+'use client';
+
+import { forwardRef } from 'react';
+import type { ChangeEvent, ReactNode, Ref } from 'react';
+
+import { clsx, mergeRefs } from '@koobiq/react-core';
+
+import { utilClasses } from '../../../../styles/utility';
+import s from '../../FileUpload.module.css';
+import { useFileInput } from '../../hooks/useFileInput';
+
+export interface FileInputProps {
+  /** Id for the input (associates the browse label with it). */
+  id?: string;
+  /** Joined `accept` specifiers. */
+  accept?: string;
+  /** Whether multiple selection is allowed. */
+  multiple?: boolean;
+  /** Whether the input selects directories. */
+  directory?: boolean;
+  /** Whether the input is disabled. */
+  isDisabled?: boolean;
+  /** Change handler receiving the underlying DOM change event. */
+  onChange?: (event: ChangeEvent<HTMLInputElement>) => void;
+  /** Visible browse-link content. */
+  children?: ReactNode;
+  /** Additional CSS-classes for the label. */
+  className?: string;
+  /** External ref to the underlying input (e.g. for focus management). */
+  inputRef?: Ref<HTMLInputElement>;
+}
+
+/**
+ * A pseudo-link `<label>` wrapping a visually-hidden, tab-reachable native file
+ * input. Activating the label opens the file dialog; the input drives keyboard
+ * and assistive-technology interaction.
+ */
+export const FileInput = forwardRef<HTMLLabelElement, FileInputProps>(
+  (props, ref) => {
+    const {
+      id,
+      accept,
+      multiple,
+      directory,
+      isDisabled,
+      onChange,
+      children,
+      className,
+      inputRef: externalInputRef,
+    } = props;
+
+    const { inputProps, inputRef } = useFileInput({
+      id,
+      accept,
+      multiple,
+      directory,
+      isDisabled,
+      onChange,
+    });
+
+    return (
+      <label
+        ref={ref}
+        className={clsx(
+          s.browseLink,
+          isDisabled && s.browseLinkDisabled,
+          className
+        )}
+        data-disabled={isDisabled || undefined}
+      >
+        {children}
+        <input
+          {...inputProps}
+          ref={mergeRefs(inputRef, externalInputRef)}
+          tabIndex={0}
+          className={utilClasses.hideVisually}
+        />
+      </label>
+    );
+  }
+);
+
+FileInput.displayName = 'FileInput';
diff --git a/packages/components/src/components/FileUpload/components/FileInput/index.ts b/packages/components/src/components/FileUpload/components/FileInput/index.ts
new file mode 100644
index 00000000..047aa3e0
--- /dev/null
+++ b/packages/components/src/components/FileUpload/components/FileInput/index.ts
@@ -0,0 +1 @@
+export * from './FileInput.js';
diff --git a/packages/components/src/components/FileUpload/components/FileUploadCaption/FileUploadCaption.tsx b/packages/components/src/components/FileUpload/components/FileUploadCaption/FileUploadCaption.tsx
new file mode 100644
index 00000000..3f8f5b88
--- /dev/null
+++ b/packages/components/src/components/FileUpload/components/FileUploadCaption/FileUploadCaption.tsx
@@ -0,0 +1,80 @@
+'use client';
+
+import type { ChangeEvent, Ref } from 'react';
+
+import s from '../../FileUpload.module.css';
+import type { FileUploadCaptionContext } from '../../types';
+import { FileInput } from '../FileInput';
+
+export interface FileUploadCaptionProps {
+  /** Resolved caption pieces. */
+  captionContext: FileUploadCaptionContext;
+  /** Overrides the leading caption text (e.g. the "when selected" text). */
+  leadingText?: string;
+  /** Id shared with the primary browse input. */
+  inputId?: string;
+  /** Joined `accept` specifiers for the file browse link. */
+  accept?: string;
+  /** Whether the browse links are disabled. */
+  isDisabled?: boolean;
+  /** Change handler for both browse inputs. */
+  onFileSelected: (event: ChangeEvent<HTMLInputElement>) => void;
+  /** Ref to the primary browse input (focus-return target). */
+  fileInputRef?: Ref<HTMLInputElement>;
+}
+
+/**
+ * Renders an empty-state caption: leading text plus one or two clickable browse
+ * links (file and/or folder) that open the native file dialog.
+ */
+export const FileUploadCaption = (props: FileUploadCaptionProps) => {
+  const {
+    captionContext,
+    leadingText,
+    inputId,
+    accept,
+    isDisabled,
+    onFileSelected,
+    fileInputRef,
+  } = props;
+
+  const { captionText, browseLink, captionTextSeparator, browseLinkFolder } =
+    captionContext;
+
+  const text = leadingText ?? captionText;
+  const hasFileLink = !!browseLink;
+
+  return (
+    <span className={s.caption}>
+      {text ? <span className={s.captionText}>{text}</span> : null}
+      {browseLink ? (
+        <FileInput
+          id={inputId}
+          accept={accept}
+          multiple
+          isDisabled={isDisabled}
+          onChange={onFileSelected}
+          inputRef={fileInputRef}
+        >
+          {browseLink}
+        </FileInput>
+      ) : null}
+      {captionTextSeparator ? (
+        <span className={s.captionText}>{captionTextSeparator}</span>
+      ) : null}
+      {browseLinkFolder ? (
+        <FileInput
+          id={hasFileLink ? undefined : inputId}
+          directory
+          isDisabled={isDisabled}
+          onChange={onFileSelected}
+          inputRef={hasFileLink ? undefined : fileInputRef}
+        >
+          {browseLinkFolder}
+        </FileInput>
+      ) : null}
+    </span>
+  );
+};
+
+FileUploadCaption.displayName = 'FileUploadCaption';
diff --git a/packages/components/src/components/FileUpload/components/FileUploadCaption/index.ts b/packages/components/src/components/FileUpload/components/FileUploadCaption/index.ts
new file mode 100644
index 00000000..5cfb3c95
--- /dev/null
+++ b/packages/components/src/components/FileUpload/components/FileUploadCaption/index.ts
@@ -0,0 +1 @@
+export * from './FileUploadCaption.js';
diff --git a/packages/components/src/components/FileUpload/components/FileUploadItem/FileUploadItem.module.css b/packages/components/src/components/FileUpload/components/FileUploadItem/FileUploadItem.module.css
new file mode 100644
index 00000000..19c9eaea
--- /dev/null
+++ b/packages/components/src/components/FileUpload/components/FileUploadItem/FileUploadItem.module.css
@@ -0,0 +1,58 @@
+.item {
+  display: flex;
+  align-items: center;
+  gap: var(--kbq-size-s);
+  inline-size: 100%;
+  color: var(--kbq-foreground-contrast);
+}
+
+.leading {
+  display: flex;
+  flex-shrink: 0;
+  align-items: center;
+  color: var(--kbq-icon-contrast-fade);
+}
+
+.name {
+  display: flex;
+  flex: 1 1 auto;
+  min-inline-size: 0;
+}
+
+.nameHead {
+  overflow: hidden;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+}
+
+.nameTail {
+  flex-shrink: 0;
+  white-space: nowrap;
+}
+
+.size {
+  flex-shrink: 0;
+  color: var(--kbq-foreground-contrast-secondary);
+}
+
+.remove {
+  flex-shrink: 0;
+}
+
+.item[data-error] .name,
+.item[data-error] .size {
+  color: var(--kbq-foreground-error);
+}
+
+.item[data-error] .leading {
+  color: var(--kbq-icon-error);
+}
+
+.item[data-disabled] .name,
+.item[data-disabled] .size {
+  color: var(--kbq-states-foreground-disabled);
+}
+
+.item[data-disabled] .leading {
+  color: var(--kbq-states-icon-disabled);
+}
diff --git a/packages/components/src/components/FileUpload/components/FileUploadItem/FileUploadItem.tsx b/packages/components/src/components/FileUpload/components/FileUploadItem/FileUploadItem.tsx
new file mode 100644
index 00000000..510db569
--- /dev/null
+++ b/packages/components/src/components/FileUpload/components/FileUploadItem/FileUploadItem.tsx
@@ -0,0 +1,141 @@
+'use client';
+
+import { forwardRef, useRef, useState } from 'react';
+import type { ReactNode } from 'react';
+
+import {
+  clsx,
+  mergeRefs,
+  useIsomorphicEffect,
+  useResizeObserver,
+} from '@koobiq/react-core';
+import { IconCircleXmark16 } from '@koobiq/react-icons';
+
+import { utilClasses } from '../../../../styles/utility';
+import { IconButton } from '../../../IconButton';
+import { ProgressSpinner } from '../../../ProgressSpinner';
+import { Tooltip } from '../../../Tooltip';
+import { useFileUploadItem } from '../../hooks/useFileUploadItem';
+import type { FileItem, FileUploadProgressMode } from '../../types';
+import { centerEllipsisParts } from '../../utils';
+
+import s from './FileUploadItem.module.css';
+
+export interface FileUploadItemProps {
+  /** The file to render. */
+  item: FileItem;
+  /** Whether interaction is disabled. */
+  isDisabled?: boolean;
+  /** Row-level error state (drives error color on the name and remove button). */
+  hasError?: boolean;
+  /** Formatted size string; when omitted the size cell is hidden. */
+  size?: string;
+  /** Leading icon shown when not loading. */
+  icon?: ReactNode;
+  /** Progress indicator mode. @default 'determinate' */
+  progressMode?: FileUploadProgressMode;
+  /** Accessible label for the remove button. */
+  removeLabel: string;
+  /** Called to remove this item. */
+  onRemove: () => void;
+}
+
+/** Presentational row: leading icon/spinner, center-ellipsized name, optional size, remove button. */
+export const FileUploadItem = forwardRef<HTMLDivElement, FileUploadItemProps>(
+  (props, ref) => {
+    const {
+      item,
+      isDisabled,
+      hasError,
+      size,
+      icon,
+      progressMode = 'determinate',
+      removeLabel,
+      onRemove,
+    } = props;
+
+    const { isLoading, progress } = useFileUploadItem(item);
+    const name = item.file.name;
+    const { head, tail } = centerEllipsisParts(name);
+
+    // Center-ellipsis truncates the head span; mirror the Angular
+    // `KbqEllipsisCenterDirective`, which shows the full name in a tooltip only
+    // while the name actually overflows. Observe the name box and re-measure the
+    // head's overflow whenever its width changes.
+    const headRef = useRef<HTMLSpanElement>(null);
+    const [nameRef, nameRect] = useResizeObserver<HTMLSpanElement>();
+    const [isTruncated, setIsTruncated] = useState(false);
+
+    useIsomorphicEffect(() => {
+      const el = headRef.current;
+
+      setIsTruncated(!!el && el.scrollWidth > el.clientWidth);
+    }, [nameRect.width, name]);
+
+    const isTooltipDisabled = isDisabled || !isTruncated;
+
+    return (
+      <div
+        ref={ref}
+        className={clsx(s.item, utilClasses.typography['text-normal'])}
+        data-error={hasError || undefined}
+        data-disabled={isDisabled || undefined}
+      >
+        <span className={s.leading}>
+          {isLoading ? (
+            <ProgressSpinner
+              value={progress}
+              isIndeterminate={progressMode === 'indeterminate'}
+            />
+          ) : (
+            icon
+          )}
+        </span>
+        <Tooltip
+          isDisabled={isTooltipDisabled}
+          control={({ ref: controlRef, ...controlProps }) => (
+            <span
+              {...controlProps}
+              ref={mergeRefs<HTMLSpanElement>(nameRef, controlRef)}
+              className={s.name}
+              aria-label={name}
+            >
+              {head ? (
+                <span ref={headRef} className={s.nameHead}>
+                  {head}
+                </span>
+              ) : null}
+              <span className={s.nameTail}>{tail}</span>
+            </span>
+          )}
+        >
+          {name}
+        </Tooltip>
+        {size != null ? <span className={s.size}>{size}</span> : null}
+        <IconButton
+          className={s.remove}
+          isCompact
+          size="l"
+          variant={hasError ? 'error' : 'fade-contrast'}
+          isDisabled={isDisabled}
+          aria-label={removeLabel}
+          onPress={onRemove}
+          onKeyDown={(event) => {
+            if (isDisabled) {
+              return;
+            }
+
+            if (event.key === 'Backspace' || event.key === 'Delete') {
+              event.preventDefault();
+              onRemove();
+            }
+          }}
+        >
+          <IconCircleXmark16 />
+        </IconButton>
+      </div>
+    );
+  }
+);
+
+FileUploadItem.displayName = 'FileUploadItem';
diff --git a/packages/components/src/components/FileUpload/components/FileUploadItem/index.ts b/packages/components/src/components/FileUpload/components/FileUploadItem/index.ts
new file mode 100644
index 00000000..128d1641
--- /dev/null
+++ b/packages/components/src/components/FileUpload/components/FileUploadItem/index.ts
@@ -0,0 +1 @@
+export * from './FileUploadItem.js';
diff --git a/packages/components/src/components/FileUpload/components/FileUploadProvider/FileUploadProvider.tsx b/packages/components/src/components/FileUpload/components/FileUploadProvider/FileUploadProvider.tsx
new file mode 100644
index 00000000..6d05bdec
--- /dev/null
+++ b/packages/components/src/components/FileUpload/components/FileUploadProvider/FileUploadProvider.tsx
@@ -0,0 +1,33 @@
+'use client';
+
+import { useMemo } from 'react';
+import type { ReactNode } from 'react';
+
+import { FileUploadContext } from '../../FileUploadContext';
+import type { FileUploadContextValue } from '../../FileUploadContext';
+
+export interface FileUploadProviderProps extends FileUploadContextValue {
+  /** Descendants that consume the upload context. */
+  children: ReactNode;
+}
+
+/**
+ * Publishes upload configuration to descendant primitives. Non-nil values take
+ * precedence over a descendant's own local props.
+ */
+export const FileUploadProvider = (props: FileUploadProviderProps) => {
+  const { children, id, isDisabled, multiple, accept, directory } = props;
+
+  const value = useMemo<FileUploadContextValue>(
+    () => ({ id, isDisabled, multiple, accept, directory }),
+    [id, isDisabled, multiple, accept, directory]
+  );
+
+  return (
+    <FileUploadContext.Provider value={value}>
+      {children}
+    </FileUploadContext.Provider>
+  );
+};
+
+FileUploadProvider.displayName = 'FileUploadProvider';
diff --git a/packages/components/src/components/FileUpload/components/FileUploadProvider/index.ts b/packages/components/src/components/FileUpload/components/FileUploadProvider/index.ts
new file mode 100644
index 00000000..f51f8d62
--- /dev/null
+++ b/packages/components/src/components/FileUpload/components/FileUploadProvider/index.ts
@@ -0,0 +1 @@
+export * from './FileUploadProvider.js';
diff --git a/packages/components/src/components/FileUpload/components/FullScreenDropzone/FullScreenDropzone.module.css b/packages/components/src/components/FileUpload/components/FullScreenDropzone/FullScreenDropzone.module.css
new file mode 100644
index 00000000..b17f20fa
--- /dev/null
+++ b/packages/components/src/components/FileUpload/components/FullScreenDropzone/FullScreenDropzone.module.css
@@ -0,0 +1,13 @@
+.overlay {
+  position: fixed;
+  inset: 0;
+  z-index: var(--kbq-overlay-z-index, 1000);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  inline-size: 100vw;
+  block-size: 100vh;
+  padding: var(--kbq-size-xl);
+  border: 2px dashed var(--kbq-line-contrast, var(--kbq-line-contrast-fade));
+  background-color: var(--kbq-background-overlay, rgb(0 0 0 / 40%));
+}
diff --git a/packages/components/src/components/FileUpload/components/FullScreenDropzone/FullScreenDropzone.tsx b/packages/components/src/components/FileUpload/components/FullScreenDropzone/FullScreenDropzone.tsx
new file mode 100644
index 00000000..4262d50f
--- /dev/null
+++ b/packages/components/src/components/FileUpload/components/FullScreenDropzone/FullScreenDropzone.tsx
@@ -0,0 +1,53 @@
+'use client';
+
+import { clsx } from '@koobiq/react-core';
+import { createPortal } from 'react-dom';
+
+import { useFullScreenDropzone } from '../../hooks/useFullScreenDropzone';
+import type { DropzoneData, FileWithPath } from '../../types';
+import { DropzoneContent } from '../DropzoneContent';
+
+import s from './FullScreenDropzone.module.css';
+
+export interface FullScreenDropzoneProps {
+  /** Overlay content configuration. */
+  config?: DropzoneData;
+  /** When `true`, drag events are ignored. */
+  disabled?: boolean;
+  /** Fires with the (directory-expanded) dropped files. */
+  onFilesDropped: (files: FileWithPath[]) => void;
+  /** Additional CSS-classes for the overlay. */
+  className?: string;
+}
+
+/**
+ * A full-viewport overlay portalled to `document.body` that opens while a file
+ * is dragged over the document and routes the drop to `onFilesDropped`.
+ */
+export const FullScreenDropzone = (props: FullScreenDropzoneProps) => {
+  const { config, disabled, onFilesDropped, className } = props;
+
+  const { isOpen } = useFullScreenDropzone({
+    enabled: true,
+    disabled,
+    onFilesDropped,
+  });
+
+  if (!isOpen || typeof document === 'undefined') {
+    return null;
+  }
+
+  return createPortal(
+    <div className={clsx(s.overlay, className)} data-attached>
+      <DropzoneContent
+        title={config?.title}
+        caption={config?.caption}
+        size={config?.size ?? 'normal'}
+        autoCapture={config?.autoCapture}
+      />
+    </div>,
+    document.body
+  );
+};
+
+FullScreenDropzone.displayName = 'FullScreenDropzone';
diff --git a/packages/components/src/components/FileUpload/components/FullScreenDropzone/index.ts b/packages/components/src/components/FileUpload/components/FullScreenDropzone/index.ts
new file mode 100644
index 00000000..ba587e51
--- /dev/null
+++ b/packages/components/src/components/FileUpload/components/FullScreenDropzone/index.ts
@@ -0,0 +1 @@
+export * from './FullScreenDropzone.js';
diff --git a/packages/components/src/components/FileUpload/components/LocalDropzone/LocalDropzone.module.css b/packages/components/src/components/FileUpload/components/LocalDropzone/LocalDropzone.module.css
new file mode 100644
index 00000000..f355fd8a
--- /dev/null
+++ b/packages/components/src/components/FileUpload/components/LocalDropzone/LocalDropzone.module.css
@@ -0,0 +1,15 @@
+.host {
+  position: relative;
+}
+
+.overlay {
+  z-index: var(--kbq-overlay-z-index, 1000);
+  display: flex;
+  box-sizing: border-box;
+  align-items: center;
+  justify-content: center;
+  padding: var(--kbq-size-s);
+  border: 2px dashed var(--kbq-line-contrast, var(--kbq-line-contrast-fade));
+  border-radius: var(--kbq-size-s);
+  background-color: var(--kbq-background-overlay, rgb(0 0 0 / 40%));
+}
diff --git a/packages/components/src/components/FileUpload/components/LocalDropzone/LocalDropzone.tsx b/packages/components/src/components/FileUpload/components/LocalDropzone/LocalDropzone.tsx
new file mode 100644
index 00000000..a96801ce
--- /dev/null
+++ b/packages/components/src/components/FileUpload/components/LocalDropzone/LocalDropzone.tsx
@@ -0,0 +1,217 @@
+'use client';
+
+import { useEffect, useRef, useState } from 'react';
+import type { ReactNode, RefObject } from 'react';
+
+import { clsx } from '@koobiq/react-core';
+import { createPortal } from 'react-dom';
+
+import type { DropzoneData, FileUploadDropTarget } from '../../types';
+import {
+  extractDroppedFiles,
+  isFolderDragSupported,
+  isOutsideViewport,
+  isSafari,
+} from '../../utils';
+import { DropzoneContent } from '../DropzoneContent';
+
+import s from './LocalDropzone.module.css';
+
+interface HostRect {
+  top: number;
+  left: number;
+  width: number;
+  height: number;
+}
+
+export interface LocalDropzoneProps {
+  /** Ref to a connected component's imperative handle (its `dropTargetRef`). */
+  connectedTo: RefObject<FileUploadDropTarget | null>;
+  /** Overlay content configuration. */
+  config?: DropzoneData;
+  /** When `true`, drag events are ignored. */
+  disabled?: boolean;
+  /** The host region that becomes a dropzone. */
+  children: ReactNode;
+  /** Additional CSS-classes for the host wrapper. */
+  className?: string;
+}
+
+/**
+ * Turns its host region into a scoped dropzone: on drag-enter it opens an
+ * overlay positioned over the host and routes the drop to the connected upload
+ * component. Ported from the Angular `KbqLocalDropzone`. The portalled overlay
+ * uses native listeners (React synthetic events on portals are unreliable).
+ */
+export const LocalDropzone = (props: LocalDropzoneProps) => {
+  const { connectedTo, config, disabled, children, className } = props;
+  const hostRef = useRef<HTMLDivElement>(null);
+  const overlayRef = useRef<HTMLDivElement>(null);
+  const [rect, setRect] = useState<HostRect | null>(null);
+  const isOpen = rect !== null;
+
+  const disabledRef = useRef(disabled);
+
+  disabledRef.current = disabled;
+
+  const measure = (): HostRect | null => {
+    const el = hostRef.current;
+
+    if (!el) {
+      return null;
+    }
+
+    const r = el.getBoundingClientRect();
+
+    return { top: r.top, left: r.left, width: r.width, height: r.height };
+  };
+
+  // Keep the overlay aligned with the host while it is open.
+  useEffect(() => {
+    if (!isOpen || typeof window === 'undefined') {
+      return;
+    }
+
+    const update = () => {
+      const next = measure();
+
+      if (next) {
+        setRect(next);
+      }
+    };
+
+    window.addEventListener('scroll', update, true);
+    window.addEventListener('resize', update);
+
+    return () => {
+      window.removeEventListener('scroll', update, true);
+      window.removeEventListener('resize', update);
+    };
+  }, [isOpen]);
+
+  // Native drag listeners on the portalled overlay.
+  useEffect(() => {
+    const el = overlayRef.current;
+
+    if (!el) {
+      return;
+    }
+
+    const onDragOver = (event: DragEvent) => {
+      event.preventDefault();
+      event.stopPropagation();
+    };
+
+    const onDragLeave = (event: DragEvent) => {
+      const related = event.relatedTarget as Node | null;
+      const r = el.getBoundingClientRect();
+
+      const withinHost = isSafari()
+        ? !isOutsideViewport({
+            clientX: event.clientX,
+            clientY: event.clientY,
+            innerWidth: r.right,
+            innerHeight: r.bottom,
+            xAxisMinThreshold: r.left,
+            yAxisMinThreshold: r.top,
+          })
+        : !!(related && el.contains(related));
+
+      if (withinHost) {
+        return;
+      }
+
+      event.preventDefault();
+      event.stopPropagation();
+      setRect(null);
+    };
+
+    const onDrop = (event: DragEvent) => {
+      if (disabledRef.current) {
+        return;
+      }
+
+      if (!isFolderDragSupported()) {
+        console.warn(
+          'Drag-and-drop functionality for folders is not supported by this browser.'
+        );
+      }
+
+      event.preventDefault();
+      event.stopPropagation();
+
+      if (event.dataTransfer && event.dataTransfer.items.length > 0) {
+        void extractDroppedFiles(event.dataTransfer).then((files) =>
+          connectedTo.current?.addFiles(files)
+        );
+      }
+
+      setRect(null);
+    };
+
+    el.addEventListener('dragover', onDragOver);
+    el.addEventListener('dragleave', onDragLeave);
+    el.addEventListener('drop', onDrop);
+
+    return () => {
+      el.removeEventListener('dragover', onDragOver);
+      el.removeEventListener('dragleave', onDragLeave);
+      el.removeEventListener('drop', onDrop);
+    };
+  }, [isOpen, connectedTo]);
+
+  return (
+    <div
+      ref={hostRef}
+      className={clsx(s.host, className)}
+      onDragEnter={(event) => {
+        if (disabled) {
+          return;
+        }
+
+        event.preventDefault();
+        event.stopPropagation();
+
+        const next = measure();
+
+        if (next) {
+          setRect(next);
+        }
+      }}
+      onDragOver={(event) => {
+        if (disabled) {
+          return;
+        }
+
+        event.preventDefault();
+      }}
+    >
+      {children}
+      {isOpen && rect && typeof document !== 'undefined'
+        ? createPortal(
+            <div
+              ref={overlayRef}
+              className={s.overlay}
+              style={{
+                position: 'fixed',
+                top: rect.top,
+                left: rect.left,
+                width: rect.width,
+                height: rect.height,
+              }}
+            >
+              <DropzoneContent
+                title={config?.title}
+                caption={config?.caption}
+                size={config?.size ?? 'normal'}
+                autoCapture={config?.autoCapture}
+              />
+            </div>,
+            document.body
+          )
+        : null}
+    </div>
+  );
+};
+
+LocalDropzone.displayName = 'LocalDropzone';
diff --git a/packages/components/src/components/FileUpload/components/LocalDropzone/index.ts b/packages/components/src/components/FileUpload/components/LocalDropzone/index.ts
new file mode 100644
index 00000000..a64a4e72
--- /dev/null
+++ b/packages/components/src/components/FileUpload/components/LocalDropzone/index.ts
@@ -0,0 +1 @@
+export * from './LocalDropzone.js';
diff --git a/packages/components/src/components/FileUpload/components/index.ts b/packages/components/src/components/FileUpload/components/index.ts
new file mode 100644
index 00000000..aec3e1e5
--- /dev/null
+++ b/packages/components/src/components/FileUpload/components/index.ts
@@ -0,0 +1,5 @@
+export * from './FileUploadProvider';
+export * from './FileInput';
+export * from './DropzoneContent';
+export * from './FullScreenDropzone';
+export * from './LocalDropzone';
diff --git a/packages/components/src/components/FileUpload/constants.ts b/packages/components/src/components/FileUpload/constants.ts
new file mode 100644
index 00000000..bfc1d813
--- /dev/null
+++ b/packages/components/src/components/FileUpload/constants.ts
@@ -0,0 +1,8 @@
+/** Number of trailing characters kept intact when center-truncating a file name. */
+export const FILE_NAME_TAIL_LENGTH = 7;
+
+/**
+ * Delay (ms) before returning focus to the input after the list empties. A
+ * macrotask lets the empty-state (with its input) re-render first.
+ */
+export const FOCUS_RETURN_DELAY = 0;
diff --git a/packages/components/src/components/FileUpload/dropzones.test.tsx b/packages/components/src/components/FileUpload/dropzones.test.tsx
new file mode 100644
index 00000000..4e2692e7
--- /dev/null
+++ b/packages/components/src/components/FileUpload/dropzones.test.tsx
@@ -0,0 +1,158 @@
+import { useRef } from 'react';
+
+import {
+  cleanup,
+  fireEvent,
+  render,
+  screen,
+  waitFor,
+} from '@testing-library/react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { LocalDropzone } from './components/LocalDropzone';
+import { MultipleFileUpload } from './MultipleFileUpload';
+import { SingleFileUpload } from './SingleFileUpload';
+import type { FileUploadDropTarget } from './types';
+
+afterEach(cleanup);
+
+const dataTransferWith = (files: File[]) =>
+  ({
+    items: files.map((file) => ({
+      kind: 'file',
+      webkitGetAsEntry: () => ({
+        isFile: true,
+        isDirectory: false,
+        fullPath: `/${file.name}`,
+        file: (cb: (f: File) => void) => cb(file),
+      }),
+    })),
+    files,
+  }) as unknown as DataTransfer;
+
+describe('FullScreenDropzone (via fullScreenDropzone prop)', () => {
+  it('does not open when not enabled', () => {
+    render(<MultipleFileUpload />);
+
+    fireEvent.dragEnter(document.body);
+
+    expect(screen.queryByText('Drop anywhere')).not.toBeInTheDocument();
+  });
+
+  it('opens on document drag, adds on drop, then closes', async () => {
+    const onChange = vi.fn();
+
+    render(
+      <MultipleFileUpload
+        fullScreenDropzone={{ title: 'Drop anywhere' }}
+        onChange={onChange}
+      />
+    );
+
+    expect(screen.queryByText('Drop anywhere')).not.toBeInTheDocument();
+
+    fireEvent.dragEnter(document.body);
+    expect(screen.getByText('Drop anywhere')).toBeInTheDocument();
+
+    fireEvent.drop(document.body, {
+      dataTransfer: dataTransferWith([new File(['a'], 'a.txt')]),
+    });
+
+    await waitFor(() => expect(onChange).toHaveBeenCalled());
+    expect(onChange.mock.calls.at(-1)?.[0]).toHaveLength(1);
+
+    await waitFor(() =>
+      expect(screen.queryByText('Drop anywhere')).not.toBeInTheDocument()
+    );
+  });
+
+  it('uses the localized default title when no config title is given', () => {
+    render(<SingleFileUpload fullScreenDropzone />);
+
+    fireEvent.dragEnter(document.body);
+
+    // The single empty-state caption is "Drag here or …" (a different node);
+    // the overlay title is exactly "Drag here".
+    expect(screen.getByText('Drag here')).toBeInTheDocument();
+  });
+
+  it('does not open while disabled', () => {
+    render(
+      <MultipleFileUpload
+        isDisabled
+        fullScreenDropzone={{ title: 'Drop anywhere' }}
+      />
+    );
+
+    fireEvent.dragEnter(document.body);
+
+    expect(screen.queryByText('Drop anywhere')).not.toBeInTheDocument();
+  });
+});
+
+describe('LocalDropzone', () => {
+  const Harness = ({ onChange }: { onChange: (v: unknown) => void }) => {
+    const ref = useRef<FileUploadDropTarget>(null);
+
+    return (
+      <>
+        <MultipleFileUpload dropTargetRef={ref} onChange={onChange} />
+        <LocalDropzone
+          connectedTo={ref}
+          config={{ title: 'Drop here' }}
+          className="local-host"
+        >
+          <div>Host region</div>
+        </LocalDropzone>
+      </>
+    );
+  };
+
+  const getHost = (container: HTMLElement): HTMLElement =>
+    container.querySelector('.local-host') as HTMLElement;
+
+  const getOverlay = (): HTMLElement =>
+    document.querySelector('[class*="overlay"]') as HTMLElement;
+
+  it('opens an overlay over the host on drag enter', () => {
+    const { container } = render(<Harness onChange={vi.fn()} />);
+
+    expect(screen.queryByText('Drop here')).not.toBeInTheDocument();
+
+    fireEvent.dragEnter(getHost(container));
+
+    expect(screen.getByText('Drop here')).toBeInTheDocument();
+  });
+
+  it('routes a drop to the connected component', async () => {
+    const onChange = vi.fn();
+    const { container } = render(<Harness onChange={onChange} />);
+
+    fireEvent.dragEnter(getHost(container));
+
+    fireEvent.drop(getOverlay(), {
+      dataTransfer: dataTransferWith([new File(['a'], 'a.txt')]),
+    });
+
+    await waitFor(() => expect(onChange).toHaveBeenCalled());
+    expect(onChange.mock.calls.at(-1)?.[0]).toHaveLength(1);
+  });
+
+  it('closes when the drag leaves the host', async () => {
+    const { container } = render(<Harness onChange={vi.fn()} />);
+
+    fireEvent.dragEnter(getHost(container));
+    expect(screen.getByText('Drop here')).toBeInTheDocument();
+
+    getOverlay().dispatchEvent(
+      new MouseEvent('dragleave', {
+        bubbles: true,
+        relatedTarget: document.body,
+      })
+    );
+
+    await waitFor(() =>
+      expect(screen.queryByText('Drop here')).not.toBeInTheDocument()
+    );
+  });
+});
diff --git a/packages/components/src/components/FileUpload/errorPredicates.ts b/packages/components/src/components/FileUpload/errorPredicates.ts
new file mode 100644
index 00000000..82dcfa03
--- /dev/null
+++ b/packages/components/src/components/FileUpload/errorPredicates.ts
@@ -0,0 +1,23 @@
+import type { ShouldShowError } from './types';
+
+/**
+ * Default predicate: show the error when the control is invalid and has been
+ * touched or the form was submitted.
+ */
+export const showErrorOnTouched: ShouldShowError = (s) =>
+  s.isInvalid && (s.isTouched || s.isSubmitted);
+
+/** Show the error only after the surrounding form has been submitted. */
+export const showErrorOnSubmit: ShouldShowError = (s) =>
+  s.isInvalid && s.isSubmitted;
+
+/**
+ * Defer error display until form submission — intended for required-style
+ * errors that should not appear on touch alone.
+ */
+export const showErrorRequiredOnSubmit: ShouldShowError = (s) =>
+  s.isInvalid && s.isSubmitted;
+
+/** Show the error when the control is invalid and dirty (or the form was submitted). */
+export const showErrorOnDirty: ShouldShowError = (s) =>
+  s.isInvalid && (s.isDirty || s.isSubmitted);
diff --git a/packages/components/src/components/FileUpload/hooks/index.ts b/packages/components/src/components/FileUpload/hooks/index.ts
new file mode 100644
index 00000000..05d60971
--- /dev/null
+++ b/packages/components/src/components/FileUpload/hooks/index.ts
@@ -0,0 +1,7 @@
+export * from './useFileList';
+export * from './useFileInput';
+export * from './useFileDrop';
+export * from './useFileUploadState';
+export * from './useFileUploadItem';
+export * from './useFileUploadLocale';
+export * from './useFullScreenDropzone';
diff --git a/packages/components/src/components/FileUpload/hooks/useFileDrop/index.ts b/packages/components/src/components/FileUpload/hooks/useFileDrop/index.ts
new file mode 100644
index 00000000..2e57cef7
--- /dev/null
+++ b/packages/components/src/components/FileUpload/hooks/useFileDrop/index.ts
@@ -0,0 +1 @@
+export * from './useFileDrop.js';
diff --git a/packages/components/src/components/FileUpload/hooks/useFileDrop/useFileDrop.ts b/packages/components/src/components/FileUpload/hooks/useFileDrop/useFileDrop.ts
new file mode 100644
index 00000000..33220625
--- /dev/null
+++ b/packages/components/src/components/FileUpload/hooks/useFileDrop/useFileDrop.ts
@@ -0,0 +1,129 @@
+'use client';
+
+import { useEffect, useRef } from 'react';
+import type { RefObject } from 'react';
+
+import type { FileWithPath } from '../../types';
+import { extractDroppedFiles, isFolderDragSupported } from '../../utils';
+
+export interface UseFileDropParams {
+  /** When `true`, all drag events are ignored. */
+  disabled?: boolean;
+  /** Fires with the (directory-expanded) list of dropped files. */
+  onFilesDropped: (files: FileWithPath[]) => void;
+}
+
+export interface UseFileDropReturn<E extends HTMLElement> {
+  /** Ref to attach to the drop target. */
+  dropRef: RefObject<E | null>;
+}
+
+/**
+ * Attaches native drag-and-drop listeners to a ref. The drag-over highlight is
+ * driven by a `data-dragover` attribute written directly on the node (no React
+ * state), so high-frequency drag events never cause re-renders. Ported from the
+ * Angular `KbqFileDropDirective`.
+ */
+export function useFileDrop<E extends HTMLElement = HTMLElement>(
+  params: UseFileDropParams
+): UseFileDropReturn<E> {
+  const { disabled, onFilesDropped } = params;
+  const dropRef = useRef<E>(null);
+
+  const disabledRef = useRef(disabled);
+
+  disabledRef.current = disabled;
+
+  const onDropRef = useRef(onFilesDropped);
+
+  onDropRef.current = onFilesDropped;
+
+  useEffect(() => {
+    const el = dropRef.current;
+
+    if (!el) {
+      return;
+    }
+
+    const setDragover = (active: boolean) => {
+      if (active) {
+        el.setAttribute('data-dragover', 'true');
+      } else {
+        el.removeAttribute('data-dragover');
+      }
+    };
+
+    const onDragEnter = (event: DragEvent) => {
+      if (disabledRef.current) {
+        return;
+      }
+
+      event.preventDefault();
+      event.stopPropagation();
+      setDragover(true);
+    };
+
+    const onDragOver = (event: DragEvent) => {
+      if (disabledRef.current) {
+        return;
+      }
+
+      event.preventDefault();
+      event.stopPropagation();
+    };
+
+    const onDragLeave = (event: DragEvent) => {
+      if (disabledRef.current) {
+        return;
+      }
+
+      const current = event.currentTarget as HTMLElement | null;
+      const related = event.relatedTarget as Node | null;
+
+      // Moving onto a descendant must not clear the highlight.
+      if (current && related && current.contains(related)) {
+        return;
+      }
+
+      event.preventDefault();
+      event.stopPropagation();
+      setDragover(false);
+    };
+
+    const onDrop = (event: DragEvent) => {
+      if (disabledRef.current) {
+        return;
+      }
+
+      if (!isFolderDragSupported()) {
+        console.warn(
+          'Drag-and-drop functionality for folders is not supported by this browser.'
+        );
+      }
+
+      event.preventDefault();
+      event.stopPropagation();
+      setDragover(false);
+
+      if (event.dataTransfer && event.dataTransfer.items.length > 0) {
+        void extractDroppedFiles(event.dataTransfer).then((files) =>
+          onDropRef.current(files)
+        );
+      }
+    };
+
+    el.addEventListener('dragenter', onDragEnter);
+    el.addEventListener('dragover', onDragOver);
+    el.addEventListener('dragleave', onDragLeave);
+    el.addEventListener('drop', onDrop);
+
+    return () => {
+      el.removeEventListener('dragenter', onDragEnter);
+      el.removeEventListener('dragover', onDragOver);
+      el.removeEventListener('dragleave', onDragLeave);
+      el.removeEventListener('drop', onDrop);
+    };
+  }, []);
+
+  return { dropRef };
+}
diff --git a/packages/components/src/components/FileUpload/hooks/useFileInput/index.ts b/packages/components/src/components/FileUpload/hooks/useFileInput/index.ts
new file mode 100644
index 00000000..8341b034
--- /dev/null
+++ b/packages/components/src/components/FileUpload/hooks/useFileInput/index.ts
@@ -0,0 +1 @@
+export * from './useFileInput.js';
diff --git a/packages/components/src/components/FileUpload/hooks/useFileInput/useFileInput.ts b/packages/components/src/components/FileUpload/hooks/useFileInput/useFileInput.ts
new file mode 100644
index 00000000..9febe8a7
--- /dev/null
+++ b/packages/components/src/components/FileUpload/hooks/useFileInput/useFileInput.ts
@@ -0,0 +1,80 @@
+'use client';
+
+import { useCallback, useRef } from 'react';
+import type { ChangeEvent, InputHTMLAttributes, RefObject } from 'react';
+
+import { useFileUploadContext } from '../../FileUploadContext';
+
+export interface UseFileInputParams {
+  /** Id for the input. */
+  id?: string;
+  /** Joined `accept` specifiers. */
+  accept?: string;
+  /** Whether multiple selection is allowed. */
+  multiple?: boolean;
+  /** Whether the input selects directories. */
+  directory?: boolean;
+  /** Whether the input is disabled. */
+  isDisabled?: boolean;
+  /** Change handler receiving the underlying DOM change event. */
+  onChange?: (event: ChangeEvent<HTMLInputElement>) => void;
+}
+
+/** Props for the hidden native file input (includes the non-standard `webkitdirectory`). */
+export type FileInputElementProps = InputHTMLAttributes<HTMLInputElement> & {
+  webkitdirectory?: string;
+};
+
+export interface UseFileInputReturn {
+  /** Props to spread onto a visually-hidden `<input type="file">`. */
+  inputProps: FileInputElementProps;
+  /** Ref to the underlying input element. */
+  inputRef: RefObject<HTMLInputElement | null>;
+  /** Clears the input value (so the same file can be re-selected). */
+  reset: () => void;
+}
+
+/**
+ * Resolves upload configuration (local props overridden by a non-nil
+ * {@link FileUploadContext}) and returns props for a hidden file input. The
+ * input value is reset after each selection so re-picking the same file
+ * re-fires `change`.
+ */
+export function useFileInput(params: UseFileInputParams): UseFileInputReturn {
+  const context = useFileUploadContext();
+  const inputRef = useRef<HTMLInputElement>(null);
+  const { onChange } = params;
+
+  const resolvedId = context?.id ?? params.id;
+  const resolvedAccept = context?.accept ?? params.accept;
+  const resolvedMultiple = context?.multiple ?? params.multiple;
+  const resolvedDirectory = context?.directory ?? params.directory;
+  const resolvedDisabled = context?.isDisabled ?? params.isDisabled;
+
+  const handleChange = useCallback(
+    (event: ChangeEvent<HTMLInputElement>) => {
+      onChange?.(event);
+      // Reset so selecting the same file consecutively still fires `change`.
+      event.target.value = '';
+    },
+    [onChange]
+  );
+
+  const reset = useCallback(() => {
+    if (inputRef.current) {
+      inputRef.current.value = '';
+    }
+  }, []);
+
+  const inputProps: FileInputElementProps = {
+    type: 'file',
+    id: resolvedId ?? undefined,
+    accept: resolvedAccept ?? undefined,
+    multiple: resolvedMultiple ?? undefined,
+    disabled: resolvedDisabled ?? undefined,
+    onChange: handleChange,
+    ...(resolvedDirectory ? { webkitdirectory: '' } : {}),
+  };
+
+  return { inputProps, inputRef, reset };
+}
diff --git a/packages/components/src/components/FileUpload/hooks/useFileList/index.ts b/packages/components/src/components/FileUpload/hooks/useFileList/index.ts
new file mode 100644
index 00000000..dd96f4c0
--- /dev/null
+++ b/packages/components/src/components/FileUpload/hooks/useFileList/index.ts
@@ -0,0 +1 @@
+export * from './useFileList.js';
diff --git a/packages/components/src/components/FileUpload/hooks/useFileList/useFileList.ts b/packages/components/src/components/FileUpload/hooks/useFileList/useFileList.ts
new file mode 100644
index 00000000..2ecd5b58
--- /dev/null
+++ b/packages/components/src/components/FileUpload/hooks/useFileList/useFileList.ts
@@ -0,0 +1,121 @@
+'use client';
+
+import { useCallback } from 'react';
+
+import { useControlledState } from '@koobiq/react-core';
+
+export interface UseFileListParams<T> {
+  /** Controlled list value. */
+  list?: T[];
+  /** Uncontrolled initial list. */
+  defaultList?: T[];
+  /** Fires with the full list whenever it changes. */
+  onListChange?: (next: T[]) => void;
+  /** Fires with the chunk of items that were just added. */
+  onItemsAdded?: (items: T[]) => void;
+  /** Fires with a removed item and its index (only from `removeAt`). */
+  onItemRemoved?: (item: T, index: number) => void;
+}
+
+export interface UseFileListReturn<T> {
+  /** The current list. */
+  list: T[];
+  /** Appends a single item and emits the added event. */
+  add: (item: T) => void;
+  /** Appends multiple items and emits the added event. */
+  addArray: (items: T[]) => void;
+  /**
+   * Removes the first occurrence of `item`, returning the survivors. Emits no
+   * removal event (parity with the Angular `KbqFileList.remove`).
+   */
+  remove: (item: T) => T[];
+  /**
+   * Removes the item at `index`, returning it and emitting the removal event.
+   * Always produces a new array reference.
+   */
+  removeAt: (index: number) => T | undefined;
+  /** Immutably merges a patch into the item at `index`. */
+  updateAt: (index: number, patch: Partial<T>) => void;
+}
+
+/**
+ * Headless list-state container for upload items. Controlled or uncontrolled;
+ * mirrors the add/remove/removeAt semantics of the Angular `KbqFileList`.
+ */
+export function useFileList<T>(
+  params: UseFileListParams<T> = {}
+): UseFileListReturn<T> {
+  const {
+    list: listProp,
+    defaultList,
+    onListChange,
+    onItemsAdded,
+    onItemRemoved,
+  } = params;
+
+  const [list, setList] = useControlledState<T[]>(
+    listProp,
+    defaultList ?? [],
+    onListChange
+  );
+
+  const add = useCallback(
+    (item: T) => {
+      setList([...list, item]);
+      onItemsAdded?.([item]);
+    },
+    [list, setList, onItemsAdded]
+  );
+
+  const addArray = useCallback(
+    (items: T[]) => {
+      setList([...list, ...items]);
+      onItemsAdded?.(items);
+    },
+    [list, setList, onItemsAdded]
+  );
+
+  const remove = useCallback(
+    (item: T): T[] => {
+      const index = list.indexOf(item);
+
+      if (index === -1) {
+        return list;
+      }
+
+      const survivors = list.filter((_, i) => i !== index);
+
+      setList(survivors);
+
+      return survivors;
+    },
+    [list, setList]
+  );
+
+  const removeAt = useCallback(
+    (index: number): T | undefined => {
+      const copy = [...list];
+      const [removed] = copy.splice(index, 1);
+
+      setList(copy);
+
+      if (removed !== undefined) {
+        onItemRemoved?.(removed, index);
+      }
+
+      return removed;
+    },
+    [list, setList, onItemRemoved]
+  );
+
+  const updateAt = useCallback(
+    (index: number, patch: Partial<T>) => {
+      setList(
+        list.map((item, i) => (i === index ? { ...item, ...patch } : item))
+      );
+    },
+    [list, setList]
+  );
+
+  return { list, add, addArray, remove, removeAt, updateAt };
+}
diff --git a/packages/components/src/components/FileUpload/hooks/useFileUploadItem/index.ts b/packages/components/src/components/FileUpload/hooks/useFileUploadItem/index.ts
new file mode 100644
index 00000000..5272549e
--- /dev/null
+++ b/packages/components/src/components/FileUpload/hooks/useFileUploadItem/index.ts
@@ -0,0 +1 @@
+export * from './useFileUploadItem.js';
diff --git a/packages/components/src/components/FileUpload/hooks/useFileUploadItem/useFileUploadItem.ts b/packages/components/src/components/FileUpload/hooks/useFileUploadItem/useFileUploadItem.ts
new file mode 100644
index 00000000..26217b0d
--- /dev/null
+++ b/packages/components/src/components/FileUpload/hooks/useFileUploadItem/useFileUploadItem.ts
@@ -0,0 +1,21 @@
+'use client';
+
+import type { FileItem } from '../../types';
+
+export interface UseFileUploadItemReturn {
+  /** Whether to show the progress indicator in place of the icon. */
+  isLoading: boolean;
+  /** Progress value in the range 0–100. */
+  progress: number;
+}
+
+/**
+ * Presentational helper deriving the display state for a single file item
+ * (loading spinner vs. icon, and the progress value).
+ */
+export function useFileUploadItem(item: FileItem): UseFileUploadItemReturn {
+  return {
+    isLoading: !!item.loading,
+    progress: item.progress ?? 0,
+  };
+}
diff --git a/packages/components/src/components/FileUpload/hooks/useFileUploadLocale/index.ts b/packages/components/src/components/FileUpload/hooks/useFileUploadLocale/index.ts
new file mode 100644
index 00000000..e0a3aaf2
--- /dev/null
+++ b/packages/components/src/components/FileUpload/hooks/useFileUploadLocale/index.ts
@@ -0,0 +1 @@
+export * from './useFileUploadLocale.js';
diff --git a/packages/components/src/components/FileUpload/hooks/useFileUploadLocale/useFileUploadLocale.ts b/packages/components/src/components/FileUpload/hooks/useFileUploadLocale/useFileUploadLocale.ts
new file mode 100644
index 00000000..69e5cd06
--- /dev/null
+++ b/packages/components/src/components/FileUpload/hooks/useFileUploadLocale/useFileUploadLocale.ts
@@ -0,0 +1,131 @@
+'use client';
+
+import { useLocale } from '@koobiq/react-core';
+
+import { DEFAULT_FILE_UPLOAD_CONFIG, fileUploadIntl } from '../../locales';
+import type {
+  FileUploadAllowedType,
+  FileUploadCaptionContext,
+  MultipleFileUploadLocaleConfig,
+  MultipleFileUploadSize,
+  SingleFileUploadLocaleConfig,
+} from '../../types';
+
+const FILE_LINK_PLACEHOLDER = '{{ browseLink }}';
+const FOLDER_LINK_PLACEHOLDER = '{{ browseLinkFolder }}';
+const FOLDER_MIXED_PLACEHOLDER = '{{ browseLinkFolderMixed }}';
+
+const before = (template: string, placeholder: string): string =>
+  template.split(placeholder)[0] ?? '';
+
+const buildCaptionContext = (
+  allowed: FileUploadAllowedType,
+  config: SingleFileUploadLocaleConfig,
+  fileCaption: string
+): FileUploadCaptionContext => {
+  switch (allowed) {
+    case 'mixed': {
+      const [head = '', tail = ''] = config.captionTextWithFolder.split(
+        FILE_LINK_PLACEHOLDER
+      );
+
+      return {
+        captionText: head,
+        browseLink: config.browseLink,
+        captionTextSeparator: tail.split(FOLDER_MIXED_PLACEHOLDER)[0],
+        browseLinkFolder: config.browseLinkFolderMixed,
+      };
+    }
+
+    case 'folder':
+      return {
+        captionText: before(
+          config.captionTextOnlyFolder,
+          FOLDER_LINK_PLACEHOLDER
+        ),
+        browseLinkFolder: config.browseLinkFolder,
+      };
+    case 'file':
+    default:
+      return {
+        captionText: before(fileCaption, FILE_LINK_PLACEHOLDER),
+        browseLink: config.browseLink,
+      };
+  }
+};
+
+export interface UseSingleFileUploadLocaleParams {
+  allowed: FileUploadAllowedType;
+  localeConfig?: Partial<SingleFileUploadLocaleConfig>;
+}
+
+export interface UseSingleFileUploadLocaleReturn {
+  locale: string;
+  config: SingleFileUploadLocaleConfig;
+  captionContext: FileUploadCaptionContext;
+}
+
+/** Resolves single-file caption config (override > locale > fallback) + caption pieces. */
+export function useSingleFileUploadLocale(
+  params: UseSingleFileUploadLocaleParams
+): UseSingleFileUploadLocaleReturn {
+  const { allowed, localeConfig } = params;
+  const { locale } = useLocale();
+
+  const base = fileUploadIntl[locale] ?? DEFAULT_FILE_UPLOAD_CONFIG;
+
+  const config: SingleFileUploadLocaleConfig = {
+    ...base.single,
+    ...localeConfig,
+  };
+
+  const captionContext = buildCaptionContext(
+    allowed,
+    config,
+    config.captionTextWithFolder
+  );
+
+  return { locale, config, captionContext };
+}
+
+export interface UseMultipleFileUploadLocaleParams {
+  allowed: FileUploadAllowedType;
+  size: MultipleFileUploadSize;
+  hasFiles: boolean;
+  localeConfig?: Partial<MultipleFileUploadLocaleConfig>;
+}
+
+export interface UseMultipleFileUploadLocaleReturn {
+  locale: string;
+  config: MultipleFileUploadLocaleConfig;
+  captionContext: FileUploadCaptionContext;
+  /** Caption text shown when the list already contains files. */
+  whenSelectedText: string;
+}
+
+/** Resolves multiple-file caption config + caption pieces + the "when selected" text. */
+export function useMultipleFileUploadLocale(
+  params: UseMultipleFileUploadLocaleParams
+): UseMultipleFileUploadLocaleReturn {
+  const { allowed, size, localeConfig } = params;
+  const { locale } = useLocale();
+
+  const base = fileUploadIntl[locale] ?? DEFAULT_FILE_UPLOAD_CONFIG;
+
+  const config: MultipleFileUploadLocaleConfig = {
+    ...base.multiple,
+    ...localeConfig,
+  };
+
+  const fileCaption =
+    size === 'compact' ? config.captionTextForCompactSize : config.captionText;
+
+  const captionContext = buildCaptionContext(allowed, config, fileCaption);
+
+  const whenSelectedText = before(
+    config.captionTextWhenSelected,
+    FILE_LINK_PLACEHOLDER
+  );
+
+  return { locale, config, captionContext, whenSelectedText };
+}
diff --git a/packages/components/src/components/FileUpload/hooks/useFileUploadState/index.ts b/packages/components/src/components/FileUpload/hooks/useFileUploadState/index.ts
new file mode 100644
index 00000000..91fade82
--- /dev/null
+++ b/packages/components/src/components/FileUpload/hooks/useFileUploadState/index.ts
@@ -0,0 +1 @@
+export * from './useFileUploadState.js';
diff --git a/packages/components/src/components/FileUpload/hooks/useFileUploadState/useFileUploadState.ts b/packages/components/src/components/FileUpload/hooks/useFileUploadState/useFileUploadState.ts
new file mode 100644
index 00000000..b7395416
--- /dev/null
+++ b/packages/components/src/components/FileUpload/hooks/useFileUploadState/useFileUploadState.ts
@@ -0,0 +1,60 @@
+'use client';
+
+import { useCallback, useMemo, useState } from 'react';
+
+import { showErrorOnTouched } from '../../errorPredicates';
+import type { FileUploadState, ShouldShowError } from '../../types';
+
+export interface UseFileUploadStateParams {
+  /** Whether the control is invalid. */
+  isInvalid?: boolean;
+  /** Whether the surrounding form has been submitted (fed by a form adapter). */
+  isSubmitted?: boolean;
+  /** Predicate deciding error visibility. @default showErrorOnTouched */
+  shouldShowError?: ShouldShowError;
+}
+
+export interface UseFileUploadStateReturn {
+  /** The current interaction state. */
+  state: FileUploadState;
+  /** Whether the error styling should be shown. */
+  errorState: boolean;
+  /** Whether the control has been touched. */
+  isTouched: boolean;
+  /** Whether the value has changed since mount. */
+  isDirty: boolean;
+  /** Marks the control as touched. */
+  markTouched: () => void;
+  /** Marks the control as dirty. */
+  markDirty: () => void;
+}
+
+/**
+ * Tracks touched/dirty interaction state and computes the error state via a
+ * predicate. The React equivalent of the Angular `updateErrorState` machinery,
+ * but pull-based (recomputed each render) rather than a `Subject`.
+ */
+export function useFileUploadState(
+  params: UseFileUploadStateParams
+): UseFileUploadStateReturn {
+  const {
+    isInvalid = false,
+    isSubmitted = false,
+    shouldShowError = showErrorOnTouched,
+  } = params;
+
+  const [isTouched, setTouched] = useState(false);
+  const [isDirty, setDirty] = useState(false);
+
+  const markTouched = useCallback(() => setTouched(true), []);
+  const markDirty = useCallback(() => setDirty(true), []);
+
+  const state = useMemo<FileUploadState>(
+    () => ({ isInvalid, isTouched, isDirty, isSubmitted }),
+    [isInvalid, isTouched, isDirty, isSubmitted]
+  );
+
+  const errorState = shouldShowError(state);
+
+  return { state, errorState, isTouched, isDirty, markTouched, markDirty };
+}
diff --git a/packages/components/src/components/FileUpload/hooks/useFullScreenDropzone/index.ts b/packages/components/src/components/FileUpload/hooks/useFullScreenDropzone/index.ts
new file mode 100644
index 00000000..9c7817f6
--- /dev/null
+++ b/packages/components/src/components/FileUpload/hooks/useFullScreenDropzone/index.ts
@@ -0,0 +1 @@
+export * from './useFullScreenDropzone.js';
diff --git a/packages/components/src/components/FileUpload/hooks/useFullScreenDropzone/useFullScreenDropzone.ts b/packages/components/src/components/FileUpload/hooks/useFullScreenDropzone/useFullScreenDropzone.ts
new file mode 100644
index 00000000..cd244f47
--- /dev/null
+++ b/packages/components/src/components/FileUpload/hooks/useFullScreenDropzone/useFullScreenDropzone.ts
@@ -0,0 +1,144 @@
+'use client';
+
+import { useEffect, useRef, useState } from 'react';
+
+import type { FileWithPath } from '../../types';
+import {
+  extractDroppedFiles,
+  isFolderDragSupported,
+  isOutsideViewport,
+  isSafari,
+} from '../../utils';
+
+export interface UseFullScreenDropzoneParams {
+  /** Whether the full-screen dropzone is enabled. */
+  enabled: boolean;
+  /** When `true`, drag events are ignored. */
+  disabled?: boolean;
+  /** Fires with the (directory-expanded) dropped files. */
+  onFilesDropped: (files: FileWithPath[]) => void;
+}
+
+export interface UseFullScreenDropzoneReturn {
+  /** Whether the overlay is currently open. */
+  isOpen: boolean;
+}
+
+/**
+ * Opens a full-viewport overlay when a drag enters the document, and routes the
+ * drop to `onFilesDropped`. Listeners are attached to `document.body` and the
+ * overlay is expected to be a child of `body`, so drops bubble to these
+ * handlers. Ported from the Angular `KbqFullScreenDropzoneService`.
+ */
+export function useFullScreenDropzone(
+  params: UseFullScreenDropzoneParams
+): UseFullScreenDropzoneReturn {
+  const { enabled, disabled, onFilesDropped } = params;
+  const [isOpen, setOpen] = useState(false);
+
+  const disabledRef = useRef(disabled);
+
+  disabledRef.current = disabled;
+
+  const onDropRef = useRef(onFilesDropped);
+
+  onDropRef.current = onFilesDropped;
+
+  useEffect(() => {
+    if (!enabled || typeof document === 'undefined') {
+      return;
+    }
+
+    const body = document.body;
+
+    const onDragEnter = (event: DragEvent) => {
+      if (disabledRef.current) {
+        return;
+      }
+
+      event.preventDefault();
+      event.stopPropagation();
+      setOpen(true);
+    };
+
+    const onDragOver = (event: DragEvent) => {
+      if (disabledRef.current) {
+        return;
+      }
+
+      event.preventDefault();
+      event.stopPropagation();
+    };
+
+    const onDragLeave = (event: DragEvent) => {
+      if (disabledRef.current) {
+        return;
+      }
+
+      const current = event.currentTarget as HTMLElement | null;
+      const related = event.relatedTarget as Node | null;
+
+      const withinViewport = isSafari()
+        ? !isOutsideViewport({
+            clientX: event.clientX,
+            clientY: event.clientY,
+            innerWidth: window.innerWidth,
+            innerHeight: window.innerHeight,
+            xAxisMinThreshold: 0,
+            yAxisMinThreshold: 0,
+          })
+        : !!(current && related && current.contains(related));
+
+      if (withinViewport) {
+        return;
+      }
+
+      event.preventDefault();
+      event.stopPropagation();
+      setOpen(false);
+    };
+
+    const onDrop = (event: DragEvent) => {
+      if (disabledRef.current) {
+        return;
+      }
+
+      if (!isFolderDragSupported()) {
+        console.warn(
+          'Drag-and-drop functionality for folders is not supported by this browser.'
+        );
+      }
+
+      event.preventDefault();
+      event.stopPropagation();
+      setOpen(false);
+
+      if (event.dataTransfer && event.dataTransfer.items.length > 0) {
+        void extractDroppedFiles(event.dataTransfer).then((files) =>
+          onDropRef.current(files)
+        );
+      }
+    };
+
+    body.addEventListener('dragenter', onDragEnter);
+    body.addEventListener('dragover', onDragOver);
+    body.addEventListener('dragleave', onDragLeave);
+    body.addEventListener('drop', onDrop);
+
+    return () => {
+      body.removeEventListener('dragenter', onDragEnter);
+      body.removeEventListener('dragover', onDragOver);
+      body.removeEventListener('dragleave', onDragLeave);
+      body.removeEventListener('drop', onDrop);
+      setOpen(false);
+    };
+  }, [enabled]);
+
+  useEffect(() => {
+    if (disabled) {
+      setOpen(false);
+    }
+  }, [disabled]);
+
+  return { isOpen };
+}
diff --git a/packages/components/src/components/FileUpload/index.ts b/packages/components/src/components/FileUpload/index.ts
new file mode 100644
index 00000000..68cd1d4b
--- /dev/null
+++ b/packages/components/src/components/FileUpload/index.ts
@@ -0,0 +1,17 @@
+export * from './SingleFileUpload.js';
+export * from './MultipleFileUpload.js';
+export * from './types.js';
+export * from './validators.js';
+export * from './errorPredicates.js';
+export * from './FileUploadContext.js';
+export * from './hooks';
+export * from './components';
+export { formatDataSize, mapToFileItem } from './utils.js';
+export {
+  fileUploadIntl,
+  enUSFileUploadConfig,
+  ruRUFileUploadConfig,
+  ptBRFileUploadConfig,
+  esLAFileUploadConfig,
+  tkTMFileUploadConfig,
+} from './locales.js';
diff --git a/packages/components/src/components/FileUpload/intl.json b/packages/components/src/components/FileUpload/intl.json
new file mode 100644
index 00000000..a5906654
--- /dev/null
+++ b/packages/components/src/components/FileUpload/intl.json
@@ -0,0 +1,22 @@
+{
+  "en-US": {
+    "remove": "Remove",
+    "dropzoneTitle": "Drag here"
+  },
+  "ru-RU": {
+    "remove": "Удалить",
+    "dropzoneTitle": "Перетащите сюда"
+  },
+  "pt-BR": {
+    "remove": "Remover",
+    "dropzoneTitle": "Carregar arquivos"
+  },
+  "es-LA": {
+    "remove": "Eliminar",
+    "dropzoneTitle": "Cargue los archivos"
+  },
+  "tk-TM": {
+    "remove": "Aýyrmak",
+    "dropzoneTitle": "Faýl ýükläň"
+  }
+}
diff --git a/packages/components/src/components/FileUpload/locales.test.tsx b/packages/components/src/components/FileUpload/locales.test.tsx
new file mode 100644
index 00000000..6e7cf9e6
--- /dev/null
+++ b/packages/components/src/components/FileUpload/locales.test.tsx
@@ -0,0 +1,119 @@
+import type { ReactNode } from 'react';
+
+import { I18nProvider } from '@koobiq/react-core';
+import { renderHook } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+
+import {
+  useMultipleFileUploadLocale,
+  useSingleFileUploadLocale,
+} from './hooks/useFileUploadLocale';
+import { fileUploadIntl } from './locales';
+
+const LOCALES = ['en-US', 'ru-RU', 'pt-BR', 'es-LA', 'tk-TM'] as const;
+
+const withLocale = (locale: string) => {
+  const LocaleWrapper = ({ children }: { children: ReactNode }) => (
+    <I18nProvider locale={locale}>{children}</I18nProvider>
+  );
+
+  LocaleWrapper.displayName = 'LocaleWrapper';
+
+  return LocaleWrapper;
+};
+
+describe('FileUpload localization', () => {
+  it('bundles all five locales', () => {
+    expect(Object.keys(fileUploadIntl).sort()).toEqual([
+      'en-US',
+      'es-LA',
+      'pt-BR',
+      'ru-RU',
+      'tk-TM',
+    ]);
+  });
+
+  it.each(LOCALES)(
+    'resolves the single-file caption for %s',
+    (locale: (typeof LOCALES)[number]) => {
+      const config = fileUploadIntl[locale];
+
+      const { result } = renderHook(
+        () => useSingleFileUploadLocale({ allowed: 'file' }),
+        { wrapper: withLocale(locale) }
+      );
+
+      expect(result.current.locale).toBe(locale);
+
+      expect(result.current.captionContext.captionText.length).toBeGreaterThan(
+        0
+      );
+
+      expect(result.current.captionContext.browseLink).toBe(
+        config?.single.browseLink
+      );
+    }
+  );
+
+  it('lets localeConfig override the resolved locale', () => {
+    const { result } = renderHook(
+      () =>
+        useSingleFileUploadLocale({
+          allowed: 'file',
+          localeConfig: { browseLink: 'pick a file' },
+        }),
+      { wrapper: withLocale('en-US') }
+    );
+
+    expect(result.current.captionContext.browseLink).toBe('pick a file');
+  });
+
+  it('selects folder and mixed captions by allowed type', () => {
+    const folder = renderHook(
+      () => useSingleFileUploadLocale({ allowed: 'folder' }),
+      { wrapper: withLocale('en-US') }
+    );
+
+    expect(folder.result.current.captionContext.browseLinkFolder).toBe(
+      'choose folder'
+    );
+
+    expect(folder.result.current.captionContext.browseLink).toBeUndefined();
+
+    const mixed = renderHook(
+      () => useSingleFileUploadLocale({ allowed: 'mixed' }),
+      { wrapper: withLocale('en-US') }
+    );
+
+    expect(mixed.result.current.captionContext.browseLink).toBe('choose');
+    expect(mixed.result.current.captionContext.browseLinkFolder).toBe('folder');
+  });
+
+  it('multiple uses when-selected and compact captions', () => {
+    const selected = renderHook(
+      () =>
+        useMultipleFileUploadLocale({
+          allowed: 'file',
+          size: 'default',
+          hasFiles: true,
+        }),
+      { wrapper: withLocale('en-US') }
+    );
+
+    expect(selected.result.current.whenSelectedText).toContain('Drag more');
+
+    const compact = renderHook(
+      () =>
+        useMultipleFileUploadLocale({
+          allowed: 'file',
+          size: 'compact',
+          hasFiles: false,
+        }),
+      { wrapper: withLocale('en-US') }
+    );
+
+    expect(compact.result.current.captionContext.captionText).toContain(
+      'Drag files'
+    );
+  });
+});
diff --git a/packages/components/src/components/FileUpload/locales.ts b/packages/components/src/components/FileUpload/locales.ts
new file mode 100644
index 00000000..bc52accc
--- /dev/null
+++ b/packages/components/src/components/FileUpload/locales.ts
@@ -0,0 +1,137 @@
+import type { FileUploadLocaleConfig } from './types';
+
+/** Bundled `en-US` caption configuration. */
+export const enUSFileUploadConfig: FileUploadLocaleConfig = {
+  single: {
+    captionText: 'Drag file here or {{ browseLink }}',
+    captionTextOnlyFolder: 'Drag here or {{ browseLinkFolder }}',
+    captionTextWithFolder:
+      'Drag here or {{ browseLink }} or {{ browseLinkFolderMixed }}',
+    browseLink: 'choose',
+    browseLinkFolder: 'choose folder',
+    browseLinkFolderMixed: 'folder',
+  },
+  multiple: {
+    captionText: 'or {{ browseLink }}',
+    captionTextOnlyFolder: 'or {{ browseLinkFolder }}',
+    captionTextWithFolder: 'or {{ browseLink }} or {{ browseLinkFolderMixed }}',
+    captionTextWhenSelected: 'Drag more or {{ browseLink }}',
+    captionTextForCompactSize: 'Drag files or {{ browseLink }}',
+    browseLink: 'choose files',
+    browseLinkFolder: 'choose folder',
+    browseLinkFolderMixed: 'folder',
+    title: 'Drag here',
+  },
+};
+
+/** Bundled `ru-RU` caption configuration. */
+export const ruRUFileUploadConfig: FileUploadLocaleConfig = {
+  single: {
+    captionText: 'Перетащите сюда или {{ browseLink }}',
+    captionTextOnlyFolder: 'Перетащите сюда или {{ browseLinkFolder }}',
+    captionTextWithFolder:
+      'Перетащите сюда или {{ browseLink }} или {{ browseLinkFolderMixed }}',
+    browseLink: 'выберите файл',
+    browseLinkFolder: 'выберите папку',
+    browseLinkFolderMixed: 'папку',
+  },
+  multiple: {
+    captionText: 'или {{ browseLink }}',
+    captionTextOnlyFolder: 'или {{ browseLinkFolder }}',
+    captionTextWithFolder:
+      'или {{ browseLink }} или {{ browseLinkFolderMixed }}',
+    captionTextWhenSelected: 'Перетащите еще или {{ browseLink }}',
+    captionTextForCompactSize: 'Перетащите сюда или {{ browseLink }}',
+    browseLink: 'выберите файлы',
+    browseLinkFolder: 'выберите папку',
+    browseLinkFolderMixed: 'папку',
+    title: 'Перетащите сюда',
+  },
+};
+
+/** Bundled `pt-BR` caption configuration. */
+export const ptBRFileUploadConfig: FileUploadLocaleConfig = {
+  single: {
+    captionText: 'Arrastar o arquivo aqui ou {{ browseLink }}',
+    captionTextOnlyFolder: 'Arrastar o arquivo aqui ou {{ browseLinkFolder }}',
+    captionTextWithFolder:
+      'Arrastar o arquivo aqui ou {{ browseLink }} ou {{ browseLinkFolderMixed }}',
+    browseLink: 'escolher',
+    browseLinkFolder: 'pasta',
+    browseLinkFolderMixed: 'pasta',
+  },
+  multiple: {
+    captionText: 'Arrastar aqui ou {{ browseLink }}',
+    captionTextOnlyFolder: 'Arrastar aqui ou {{ browseLinkFolder }}',
+    captionTextWithFolder:
+      'Arrastar aqui ou {{ browseLink }} ou {{ browseLinkFolderMixed }}',
+    captionTextWhenSelected: 'Arrastar mais arquivos aqui ou {{ browseLink }}',
+    captionTextForCompactSize: 'Arrastar arquivos ou {{ browseLink }}',
+    browseLink: 'escolher',
+    browseLinkFolder: 'pasta',
+    browseLinkFolderMixed: 'pasta',
+    title: 'Carregar arquivos',
+  },
+};
+
+/** Bundled `es-LA` caption configuration. */
+export const esLAFileUploadConfig: FileUploadLocaleConfig = {
+  single: {
+    captionText: 'Arrastre el archivo aquí o {{ browseLink }}',
+    captionTextOnlyFolder: 'Arrastre el archivo aquí o {{ browseLinkFolder }}',
+    captionTextWithFolder:
+      'Arrastre el archivo aquí o {{ browseLink }} o {{ browseLinkFolderMixed }}',
+    browseLink: 'elija',
+    browseLinkFolder: 'carpeta',
+    browseLinkFolderMixed: 'carpeta',
+  },
+  multiple: {
+    captionText: 'Arrastre aquí o {{ browseLink }}',
+    captionTextOnlyFolder: 'Arrastre aquí o {{ browseLinkFolder }}',
+    captionTextWithFolder:
+      'Arrastre aquí o {{ browseLink }} o {{ browseLinkFolderMixed }}',
+    captionTextWhenSelected: 'Arrastre más archivos aquí o {{ browseLink }}',
+    captionTextForCompactSize: 'Arrastre archivos o {{ browseLink }}',
+    browseLink: 'elija',
+    browseLinkFolder: 'carpeta',
+    browseLinkFolderMixed: 'carpeta',
+    title: 'Cargue los archivos',
+  },
+};
+
+/** Bundled `tk-TM` caption configuration. */
+export const tkTMFileUploadConfig: FileUploadLocaleConfig = {
+  single: {
+    captionText: 'Faýly geçiriň ýa-da {{ browseLink }}',
+    captionTextOnlyFolder: 'Faýly geçiriň ýa-da {{ browseLinkFolder }}',
+    captionTextWithFolder:
+      'Faýly geçiriň ýa-da {{ browseLink }} ýa-da {{ browseLinkFolderMixed }}',
+    browseLink: 'saýlaň',
+    browseLinkFolder: 'bukja',
+    browseLinkFolderMixed: 'bukja',
+  },
+  multiple: {
+    captionText: 'Şu ýere geçiriň ýa-da {{ browseLink }}',
+    captionTextOnlyFolder: 'Şu ýere geçiriň ýa-da {{ browseLinkFolder }}',
+    captionTextWithFolder:
+      'Şu ýere geçiriň ýa-da {{ browseLink }} ýa-da {{ browseLinkFolderMixed }}',
+    captionTextWhenSelected: 'Ýene geçiriň ýa-da {{ browseLink }}',
+    captionTextForCompactSize: 'Faýllary geçiriň ýa-da {{ browseLink }}',
+    browseLink: 'saýlaň',
+    browseLinkFolder: 'bukja',
+    browseLinkFolderMixed: 'bukja',
+    title: 'Faýl ýükläň',
+  },
+};
+
+/** Default configuration used when no locale matches. */
+export const DEFAULT_FILE_UPLOAD_CONFIG = enUSFileUploadConfig;
+
+/** All bundled locale configurations, keyed by locale. */
+export const fileUploadIntl: Record<string, FileUploadLocaleConfig> = {
+  'en-US': enUSFileUploadConfig,
+  'ru-RU': ruRUFileUploadConfig,
+  'pt-BR': ptBRFileUploadConfig,
+  'es-LA': esLAFileUploadConfig,
+  'tk-TM': tkTMFileUploadConfig,
+};
diff --git a/packages/components/src/components/FileUpload/primitives.test.tsx b/packages/components/src/components/FileUpload/primitives.test.tsx
new file mode 100644
index 00000000..f87f8775
--- /dev/null
+++ b/packages/components/src/components/FileUpload/primitives.test.tsx
@@ -0,0 +1,272 @@
+import { act, cleanup, render, renderHook } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { FileInput, FileUploadProvider } from './components';
+import {
+  showErrorOnDirty,
+  showErrorOnSubmit,
+  showErrorOnTouched,
+} from './errorPredicates';
+import { useFileList } from './hooks/useFileList';
+import type { FileItem } from './types';
+import { extractDroppedFiles, formatDataSize } from './utils';
+import { isCorrectExtension, maxFileSize } from './validators';
+
+afterEach(cleanup);
+
+const getFileInput = (): HTMLInputElement =>
+  document.querySelector('input[type="file"]') as HTMLInputElement;
+
+// --- fake directory-entry helpers for drag-and-drop tests ---------------------
+
+const fileEntry = (file: File, fullPath: string) => ({
+  isFile: true,
+  isDirectory: false,
+  fullPath,
+  file: (cb: (f: File) => void) => cb(file),
+});
+
+const dirEntry = (fullPath: string, children: unknown[]) => {
+  let read = false;
+
+  return {
+    isFile: false,
+    isDirectory: true,
+    fullPath,
+    createReader: () => ({
+      readEntries: (resolve: (entries: unknown[]) => void) => {
+        resolve(read ? [] : children);
+        read = true;
+      },
+    }),
+  };
+};
+
+const makeDataTransfer = (entries: unknown[]) =>
+  ({
+    items: entries.map((entry) => ({
+      kind: 'file',
+      webkitGetAsEntry: () => entry,
+    })),
+    files: [],
+  }) as unknown as DataTransfer;
+
+describe('useFileList', () => {
+  it('add appends one item and emits added', () => {
+    const onItemsAdded = vi.fn();
+
+    const { result } = renderHook(() =>
+      useFileList<number>({ defaultList: [], onItemsAdded })
+    );
+
+    act(() => result.current.add(1));
+
+    expect(result.current.list).toEqual([1]);
+    expect(onItemsAdded).toHaveBeenCalledWith([1]);
+  });
+
+  it('addArray appends many items', () => {
+    const { result } = renderHook(() =>
+      useFileList<number>({ defaultList: [1] })
+    );
+
+    act(() => result.current.addArray([2, 3]));
+
+    expect(result.current.list).toEqual([1, 2, 3]);
+  });
+
+  it('remove drops the first match, returns survivors, emits no removal event', () => {
+    const onItemRemoved = vi.fn();
+
+    const { result } = renderHook(() =>
+      useFileList<string>({ defaultList: ['a', 'b', 'a'], onItemRemoved })
+    );
+
+    let survivors: string[] = [];
+
+    act(() => {
+      survivors = result.current.remove('a');
+    });
+
+    expect(survivors).toEqual(['b', 'a']);
+    expect(result.current.list).toEqual(['b', 'a']);
+    expect(onItemRemoved).not.toHaveBeenCalled();
+  });
+
+  it('removeAt splices by index, emits the removal event, returns the removed item', () => {
+    const onItemRemoved = vi.fn();
+
+    const { result } = renderHook(() =>
+      useFileList<string>({ defaultList: ['a', 'b', 'c'], onItemRemoved })
+    );
+
+    let removed: string | undefined;
+
+    act(() => {
+      removed = result.current.removeAt(1);
+    });
+
+    expect(removed).toBe('b');
+    expect(result.current.list).toEqual(['a', 'c']);
+    expect(onItemRemoved).toHaveBeenCalledWith('b', 1);
+  });
+
+  it('updateAt immutably patches the item at an index', () => {
+    const { result } = renderHook(() =>
+      useFileList<{ v: number }>({ defaultList: [{ v: 1 }, { v: 2 }] })
+    );
+
+    const before = result.current.list[0];
+
+    act(() => result.current.updateAt(0, { v: 9 }));
+
+    expect(result.current.list[0]).toEqual({ v: 9 });
+    expect(result.current.list[0]).not.toBe(before);
+  });
+});
+
+describe('validators', () => {
+  it('maxFileSize fails over the limit and passes under it', () => {
+    const file = new File(['x'.repeat(2000)], 'a.txt', { type: 'text/plain' });
+
+    expect(maxFileSize(1000)(file)).toEqual({
+      maxFileSize: { max: 1000, actual: 2000 },
+    });
+
+    expect(maxFileSize(5000)(file)).toBeNull();
+  });
+
+  it('isCorrectExtension matches extensions and MIME wildcards', () => {
+    const png = new File([''], 'photo.PNG', { type: 'image/png' });
+
+    expect(isCorrectExtension(['.png'])(png)).toBeNull();
+    expect(isCorrectExtension(['image/*'])(png)).toBeNull();
+
+    expect(isCorrectExtension(['.jpg'])(png)).toEqual({
+      fileExtensionMismatch: { expected: ['.jpg'], actual: 'photo.PNG' },
+    });
+  });
+});
+
+describe('error predicates', () => {
+  const base = {
+    isInvalid: true,
+    isTouched: false,
+    isDirty: false,
+    isSubmitted: false,
+  };
+
+  it('default shows on touched or submitted', () => {
+    expect(showErrorOnTouched({ ...base, isTouched: true })).toBe(true);
+    expect(showErrorOnTouched(base)).toBe(false);
+  });
+
+  it('on-submit shows only after submit', () => {
+    expect(showErrorOnSubmit({ ...base, isTouched: true })).toBe(false);
+    expect(showErrorOnSubmit({ ...base, isSubmitted: true })).toBe(true);
+  });
+
+  it('on-dirty shows when dirty', () => {
+    expect(showErrorOnDirty({ ...base, isDirty: true })).toBe(true);
+    expect(showErrorOnDirty(base)).toBe(false);
+  });
+});
+
+describe('formatDataSize', () => {
+  // The separator is a non-breaking space (U+00A0), matching KbqDataSizePipe.
+  const NBSP = '\u00A0';
+
+  it('formats bytes with the SI base (1000) and up to 2 fraction digits', () => {
+    expect(formatDataSize(0, 'en-US')).toBe(`0${NBSP}B`);
+    expect(formatDataSize(512, 'en-US')).toBe(`512${NBSP}B`);
+    // Steps up at 1000 (SI), not 1024, and drops trailing zeros.
+    expect(formatDataSize(1000, 'en-US')).toBe(`1${NBSP}KB`);
+    expect(formatDataSize(1024, 'en-US')).toBe(`1.02${NBSP}KB`);
+    expect(formatDataSize(1500, 'en-US')).toBe(`1.5${NBSP}KB`);
+    expect(formatDataSize(1_500_000, 'en-US')).toBe(`1.5${NBSP}MB`);
+  });
+
+  it('localizes the unit labels and decimal separator for ru', () => {
+    expect(formatDataSize(1024, 'ru-RU')).toBe(`1,02${NBSP}КБ`);
+    expect(formatDataSize(1_500_000, 'ru-RU')).toBe(`1,5${NBSP}МБ`);
+  });
+
+  it('returns an empty string for non-finite input', () => {
+    expect(formatDataSize(Number.NaN)).toBe('');
+    expect(formatDataSize(Number.POSITIVE_INFINITY)).toBe('');
+  });
+});
+
+describe('extractDroppedFiles', () => {
+  it('recursively expands directories and stamps fullPath', async () => {
+    const top = new File(['a'], 'a.txt');
+    const nested = new File(['b'], 'b.txt');
+
+    const files = await extractDroppedFiles(
+      makeDataTransfer([
+        fileEntry(top, '/a.txt'),
+        dirEntry('/dir', [fileEntry(nested, '/dir/b.txt')]),
+      ])
+    );
+
+    expect(files.map((f) => f.name).sort()).toEqual(['a.txt', 'b.txt']);
+    expect(files.find((f) => f.name === 'b.txt')?.fullPath).toBe('/dir/b.txt');
+  });
+});
+
+describe('useFileInput / FileInput', () => {
+  it('maps attributes onto the hidden input', () => {
+    render(
+      <FileInput accept="image/*" multiple onChange={vi.fn()}>
+        choose
+      </FileInput>
+    );
+
+    const input = getFileInput();
+
+    expect(input).toHaveAttribute('type', 'file');
+    expect(input).toHaveAttribute('accept', 'image/*');
+    expect(input).toHaveAttribute('multiple');
+  });
+
+  it('sets webkitdirectory when directory is requested', () => {
+    render(
+      <FileInput directory onChange={vi.fn()}>
+        choose folder
+      </FileInput>
+    );
+
+    expect(getFileInput()).toHaveAttribute('webkitdirectory');
+  });
+
+  it('gives context values precedence over local props', () => {
+    render(
+      <FileUploadProvider isDisabled>
+        <FileInput onChange={vi.fn()}>choose</FileInput>
+      </FileUploadProvider>
+    );
+
+    expect(getFileInput()).toBeDisabled();
+  });
+
+  it('resets the input value after each selection (same-file re-pick)', async () => {
+    const onChange = vi.fn();
+
+    render(<FileInput onChange={onChange}>choose</FileInput>);
+
+    const input = getFileInput();
+
+    await userEvent.upload(input, new File(['x'], 'x.txt'));
+
+    expect(onChange).toHaveBeenCalledTimes(1);
+    expect(input.value).toBe('');
+  });
+});
+
+// Guards the FileItem shape used across the suite.
+export const sampleItem = (name: string): FileItem => ({
+  file: new File(['x'], name),
+  loading: false,
+  progress: 0,
+});
diff --git a/packages/components/src/components/FileUpload/types.ts b/packages/components/src/components/FileUpload/types.ts
new file mode 100644
index 00000000..09f8047e
--- /dev/null
+++ b/packages/components/src/components/FileUpload/types.ts
@@ -0,0 +1,254 @@
+import type {
+  ComponentPropsWithoutRef,
+  CSSProperties,
+  FocusEventHandler,
+  ReactNode,
+  Ref,
+} from 'react';
+
+import type { ExtendableProps } from '@koobiq/react-core';
+
+/** A single file tracked by an upload component. */
+export interface FileItem {
+  /** The underlying native file. */
+  file: File;
+  /** Whether this file is in an error state (drives per-row error styling). */
+  hasError?: boolean;
+  /** Whether this file is currently loading; replaces its icon with a progress indicator. */
+  loading?: boolean;
+  /** Upload progress in the range 0–100 (used while `loading` is `true` in determinate mode). */
+  progress?: number;
+}
+
+/** A native file stamped with its full path within a dropped directory tree. */
+export type FileWithPath = File & { fullPath: string };
+
+/** The kinds of items an upload component accepts. */
+export const fileUploadAllowedType = ['file', 'folder', 'mixed'] as const;
+
+export type FileUploadAllowedType = (typeof fileUploadAllowedType)[number];
+
+/** Progress indicator mode. */
+export const fileUploadProgressMode = ['determinate', 'indeterminate'] as const;
+
+export type FileUploadProgressMode = (typeof fileUploadProgressMode)[number];
+
+/** Density of the multiple-file empty state. */
+export const multipleFileUploadSize = ['default', 'compact'] as const;
+
+export type MultipleFileUploadSize = (typeof multipleFileUploadSize)[number];
+
+/** Visual size of dropzone content. */
+export const dropzoneContentSize = ['compact', 'normal', 'big'] as const;
+
+export type DropzoneContentSize = (typeof dropzoneContentSize)[number];
+
+/** Configuration for a dropzone overlay (used by the Phase 2 dropzone components). */
+export interface DropzoneData {
+  /** Title text; falls back to a localized default. */
+  title?: string;
+  /** Caption text or node rendered below the title. */
+  caption?: ReactNode;
+  /** Visual size of the dropzone content. */
+  size?: DropzoneContentSize;
+  /** Whether focus is captured automatically when the overlay opens. @default true */
+  autoCapture?: boolean;
+}
+
+/** State passed to error-visibility predicates. */
+export interface FileUploadState {
+  /** Whether the control is invalid. */
+  isInvalid: boolean;
+  /** Whether the control has been blurred/interacted with. */
+  isTouched: boolean;
+  /** Whether the value has changed since mount. */
+  isDirty: boolean;
+  /** Whether the surrounding form has been submitted. */
+  isSubmitted: boolean;
+}
+
+/** Predicate deciding whether error styling should be shown. */
+export type ShouldShowError = (state: FileUploadState) => boolean;
+
+/** Locale strings for the single-file upload. */
+export interface SingleFileUploadLocaleConfig {
+  captionText: string;
+  captionTextOnlyFolder: string;
+  captionTextWithFolder: string;
+  browseLink: string;
+  browseLinkFolder: string;
+  browseLinkFolderMixed?: string;
+}
+
+/** Locale strings for the multiple-file upload. */
+export interface MultipleFileUploadLocaleConfig extends SingleFileUploadLocaleConfig {
+  captionTextWhenSelected: string;
+  captionTextForCompactSize: string;
+  title: string;
+}
+
+/** Combined single + multiple locale configuration. */
+export interface FileUploadLocaleConfig {
+  single: SingleFileUploadLocaleConfig;
+  multiple: MultipleFileUploadLocaleConfig;
+}
+
+/** Resolved caption pieces used to render an empty-state caption. */
+export interface FileUploadCaptionContext {
+  /** Leading caption text. */
+  captionText: string;
+  /** Label for the file browse link. */
+  browseLink?: string;
+  /** Text placed between the file and folder browse links. */
+  captionTextSeparator?: string;
+  /** Label for the folder browse link. */
+  browseLinkFolder?: string;
+}
+
+/** Error produced by the {@link maxFileSize} validator. */
+export interface MaxFileSizeError {
+  maxFileSize: { max: number; actual: number };
+}
+
+/** Error produced by the {@link isCorrectExtension} validator. */
+export interface FileExtensionMismatchError {
+  fileExtensionMismatch: { expected: string[]; actual: string };
+}
+
+/** Overrides for the composite parts of an upload component. */
+export interface FileUploadSlotProps {
+  /** Props for the bordered drop area. */
+  dropArea?: ComponentPropsWithoutRef<'div'>;
+}
+
+/**
+ * Imperative handle exposed by the upload components (via `dropTargetRef`) so a
+ * `LocalDropzone` can route dropped files into them.
+ */
+export interface FileUploadDropTarget {
+  /** Adds files to the connected component (single takes the first). */
+  addFiles: (files: FileWithPath[]) => void;
+}
+
+type FileUploadSharedProps = {
+  /** Additional CSS-classes. */
+  className?: string;
+  /** Inline styles. */
+  style?: CSSProperties;
+  /** Unique identifier for testing purposes. */
+  'data-testid'?: string | number;
+  /**
+   * Native-input `accept` specifiers. Forwarded to the file input as a browse
+   * hint only — it is NOT enforced on drop (validation is the app's job).
+   */
+  accept?: string[];
+  /**
+   * Which item kinds the component accepts.
+   * @default 'file'
+   */
+  allowed?: FileUploadAllowedType;
+  /**
+   * If `true`, the component is disabled.
+   */
+  isDisabled?: boolean;
+  /**
+   * If `true`, the component is in an invalid state.
+   */
+  isInvalid?: boolean;
+  /**
+   * Predicate controlling when the invalid styling is shown.
+   * @default showErrorOnTouched
+   */
+  shouldShowError?: ShouldShowError;
+  /**
+   * Progress indicator mode.
+   * @default 'determinate'
+   */
+  progressMode?: FileUploadProgressMode;
+  /** Id for the underlying file input; auto-generated when omitted. */
+  inputId?: string;
+  /** Blur handler; marks the control as touched. */
+  onBlur?: FocusEventHandler<HTMLDivElement>;
+  /** Error message rendered below the control when invalid. */
+  errorMessage?: ReactNode;
+  /** Helper text rendered below the control. */
+  caption?: ReactNode;
+  /** Overrides for composite parts. */
+  slotProps?: FileUploadSlotProps;
+  /**
+   * Opt-in full-screen dropzone. Pass `true` to enable with defaults, or a
+   * {@link DropzoneData} object to configure it. While active, the inline drop
+   * area is disabled and a full-viewport overlay opens on document drag.
+   */
+  fullScreenDropzone?: boolean | DropzoneData;
+  /**
+   * Imperative handle populated with an `addFiles` method, so a
+   * `LocalDropzone` can be connected to this component.
+   */
+  dropTargetRef?: Ref<FileUploadDropTarget>;
+  /**
+   * If `true`, the component is disabled.
+   * @deprecated The "disabled" prop is deprecated. Use "isDisabled" prop to replace it.
+   */
+  disabled?: boolean;
+};
+
+type SingleFileUploadOwnProps = FileUploadSharedProps & {
+  /** Controlled value (holds at most one file). */
+  value?: FileItem | null;
+  /**
+   * Uncontrolled initial value.
+   * @default null
+   */
+  defaultValue?: FileItem | null;
+  /** Fires when the value changes (pick, drop, remove, programmatic write). */
+  onChange?: (value: FileItem | null) => void;
+  /** Fires when a file is added. */
+  onFilesAdded?: (added: FileItem) => void;
+  /** Fires when the file is removed. */
+  onFileRemoved?: (removed: FileItem) => void;
+  /**
+   * Whether to display the file size.
+   * @default true
+   */
+  showFileSize?: boolean;
+  /** Locale overrides (highest precedence). */
+  localeConfig?: Partial<SingleFileUploadLocaleConfig>;
+  /** Custom leading icon for the selected-file row. */
+  icon?: ReactNode;
+};
+
+export type SingleFileUploadProps = ExtendableProps<
+  SingleFileUploadOwnProps,
+  Omit<ComponentPropsWithoutRef<'div'>, 'onChange' | 'defaultValue' | 'color'>
+>;
+
+type MultipleFileUploadOwnProps = FileUploadSharedProps & {
+  /** Controlled value (an ordered list of files). */
+  value?: FileItem[];
+  /**
+   * Uncontrolled initial value.
+   * @default []
+   */
+  defaultValue?: FileItem[];
+  /** Fires when the value changes (pick, drop, remove, programmatic write). */
+  onChange?: (value: FileItem[]) => void;
+  /** Fires with the chunk of files that were just added. */
+  onFilesAdded?: (added: FileItem[]) => void;
+  /** Fires with the removed file and its index. */
+  onFileRemoved?: (removed: FileItem, index: number) => void;
+  /**
+   * Empty-state density.
+   * @default 'default'
+   */
+  size?: MultipleFileUploadSize;
+  /** Renders a custom leading icon per row. */
+  renderFileIcon?: (item: FileItem) => ReactNode;
+  /** Locale overrides (highest precedence). */
+  localeConfig?: Partial<MultipleFileUploadLocaleConfig>;
+};
+
+export type MultipleFileUploadProps = ExtendableProps<
+  MultipleFileUploadOwnProps,
+  Omit<ComponentPropsWithoutRef<'div'>, 'onChange' | 'defaultValue' | 'color'>
+>;
diff --git a/packages/components/src/components/FileUpload/utils.ts b/packages/components/src/components/FileUpload/utils.ts
new file mode 100644
index 00000000..39a7a835
--- /dev/null
+++ b/packages/components/src/components/FileUpload/utils.ts
@@ -0,0 +1,182 @@
+import { FILE_NAME_TAIL_LENGTH } from './constants';
+import type { FileItem, FileWithPath } from './types';
+
+/** Wraps a native `File` into a `FileItem` (loading off, progress 0). */
+export const mapToFileItem = (file: File): FileItem => ({
+  file,
+  loading: false,
+  progress: 0,
+});
+
+// SI unit abbreviations (base 1000), matching the Angular `KbqDataSizePipe`
+// default unit system (`defaultUnitSystem: 'SI'`). Russian localizes the labels
+// to Cyrillic, mirroring the pipe's per-locale `sizeUnits` table; every other
+// bundled locale keeps the Latin labels.
+const DATA_SIZE_UNITS = ['B', 'KB', 'MB', 'GB', 'TB'] as const;
+const DATA_SIZE_UNITS_RU = ['Б', 'КБ', 'МБ', 'ГБ', 'ТБ'] as const;
+
+// SI base and default precision, matching `KbqDataSizePipe` (`base: 10, power: 3`
+// → 1000; `defaultPrecision: 2`). The pipe joins value and unit with a
+// non-breaking space, so we do the same.
+const DATA_SIZE_BASE = 1000;
+const DATA_SIZE_MAX_PRECISION = 2;
+const NON_BREAKING_SPACE = '\u00A0';
+
+/**
+ * Formats a byte count into a localized, human-readable size string, matching
+ * the Angular `KbqDataSizePipe` SI defaults: base 1000, up to 2 fraction digits
+ * (trailing zeros dropped), a non-breaking space separator, and Cyrillic unit
+ * labels under `ru`. Unlike the pipe (which throws on non-finite input), this
+ * returns an empty string so it stays render-safe.
+ */
+export const formatDataSize = (bytes: number, locale?: string): string => {
+  if (!Number.isFinite(bytes)) {
+    return '';
+  }
+
+  const units = locale?.toLowerCase().startsWith('ru')
+    ? DATA_SIZE_UNITS_RU
+    : DATA_SIZE_UNITS;
+
+  let value = bytes;
+  let unitIndex = 0;
+
+  while (value >= DATA_SIZE_BASE && unitIndex < units.length - 1) {
+    value /= DATA_SIZE_BASE;
+    unitIndex += 1;
+  }
+
+  const formatted = new Intl.NumberFormat(locale, {
+    minimumFractionDigits: 0,
+    maximumFractionDigits: DATA_SIZE_MAX_PRECISION,
+  }).format(value);
+
+  return `${formatted}${NON_BREAKING_SPACE}${units[unitIndex]}`;
+};
+
+/** Splits a file name into a head (truncatable) and a preserved tail. */
+export const centerEllipsisParts = (
+  name: string,
+  tailLength = FILE_NAME_TAIL_LENGTH
+): { head: string; tail: string } => {
+  if (name.length <= tailLength) {
+    return { head: '', tail: name };
+  }
+
+  return {
+    head: name.slice(0, name.length - tailLength),
+    tail: name.slice(name.length - tailLength),
+  };
+};
+
+/** Returns the leading part of a caption template, before the given placeholder. */
+export const splitBefore = (template: string, placeholder: string): string =>
+  template.split(placeholder)[0] ?? template;
+
+/** Determines whether a pointer position falls outside the given bounds. */
+export const isOutsideViewport = (params: {
+  clientX: number;
+  clientY: number;
+  innerWidth: number;
+  innerHeight: number;
+  xAxisMinThreshold: number;
+  yAxisMinThreshold: number;
+}): boolean => {
+  const {
+    clientX,
+    clientY,
+    innerWidth,
+    innerHeight,
+    xAxisMinThreshold,
+    yAxisMinThreshold,
+  } = params;
+
+  return (
+    clientX <= xAxisMinThreshold ||
+    clientY <= yAxisMinThreshold ||
+    clientX >= innerWidth ||
+    clientY >= innerHeight
+  );
+};
+
+/** Whether the current browser is Safari (drag `relatedTarget` is unreliable there). */
+export const isSafari = (): boolean => {
+  if (typeof navigator === 'undefined') {
+    return false;
+  }
+
+  return /^((?!chrome|android|crios|fxios).)*safari/i.test(navigator.userAgent);
+};
+
+/** Whether the browser supports reading dropped directory entries. */
+export const isFolderDragSupported = (): boolean =>
+  typeof DataTransferItem !== 'undefined' &&
+  'webkitGetAsEntry' in DataTransferItem.prototype;
+
+const entryIsDirectory = (
+  entry: FileSystemEntry | undefined
+): entry is FileSystemDirectoryEntry => !!entry && entry.isDirectory;
+
+const entryIsFile = (
+  entry: FileSystemEntry | undefined
+): entry is FileSystemFileEntry => !!entry && entry.isFile;
+
+/**
+ * Recursively expands a dropped entry into a flat list of files, stamping each
+ * with its full path within the dropped tree. Ported from the Angular
+ * `KbqDrop.unwrapDirectory` iterative BFS.
+ */
+export const unwrapDirectory = async (
+  item: FileSystemEntry
+): Promise<FileWithPath[]> => {
+  const queue: (FileSystemEntry | Promise<FileSystemEntry[]>)[] = [item];
+  const result: Promise<FileWithPath>[] = [];
+
+  while (queue.length > 0) {
+    const next = queue.pop();
+
+    if (next instanceof Promise) {
+      queue.push(...(await next));
+    } else if (entryIsDirectory(next)) {
+      const reader = next.createReader();
+
+      queue.push(
+        new Promise<FileSystemEntry[]>((resolve, reject) =>
+          reader.readEntries(resolve, reject)
+        )
+      );
+    } else if (entryIsFile(next)) {
+      const fileEntry = next;
+
+      result.push(
+        new Promise<FileWithPath>((resolve, reject) => {
+          fileEntry.file((file) => {
+            const withPath = file as FileWithPath;
+
+            withPath.fullPath = fileEntry.fullPath;
+            resolve(withPath);
+          }, reject);
+        })
+      );
+    }
+  }
+
+  return Promise.all(result);
+};
+
+/**
+ * Extracts dropped files from a `DataTransfer`, recursively expanding any
+ * directories. `accept` is intentionally not applied here.
+ */
+export const extractDroppedFiles = async (
+  dataTransfer: DataTransfer
+): Promise<FileWithPath[]> => {
+  const entries = Array.from(dataTransfer.items)
+    .filter((item) => item.kind === 'file')
+    .map((item) => item.webkitGetAsEntry())
+    .filter((entry): entry is FileSystemEntry => entry != null);
+
+  const groups = await Promise.all(entries.map(unwrapDirectory));
+
+  return groups.reduce<FileWithPath[]>((acc, group) => acc.concat(group), []);
+};
diff --git a/packages/components/src/components/FileUpload/validators.ts b/packages/components/src/components/FileUpload/validators.ts
new file mode 100644
index 00000000..a62476f8
--- /dev/null
+++ b/packages/components/src/components/FileUpload/validators.ts
@@ -0,0 +1,41 @@
+import type { FileExtensionMismatchError, MaxFileSizeError } from './types';
+
+/**
+ * Returns a validator that fails when a file exceeds `max` bytes.
+ * Error shape mirrors the Angular `FileValidators.maxFileSize`.
+ */
+export const maxFileSize =
+  (max: number) =>
+  (file: File): MaxFileSizeError | null =>
+    file.size > max ? { maxFileSize: { max, actual: file.size } } : null;
+
+/**
+ * Returns a validator that fails when a file matches none of the `expected`
+ * specifiers. Specifiers may be extensions (`.png`), MIME types (`image/png`),
+ * or MIME wildcards (`image/*`). Error shape mirrors the Angular
+ * `FileValidators.isCorrectExtension`.
+ */
+export const isCorrectExtension =
+  (expected: string[]) =>
+  (file: File): FileExtensionMismatchError | null => {
+    const name = file.name.toLowerCase();
+    const type = file.type.toLowerCase();
+
+    const matches = expected.some((raw) => {
+      const spec = raw.toLowerCase().trim();
+
+      if (spec.startsWith('.')) {
+        return name.endsWith(spec);
+      }
+
+      if (spec.endsWith('/*')) {
+        return type.startsWith(spec.slice(0, -1));
+      }
+
+      return type === spec;
+    });
+
+    return matches
+      ? null
+      : { fileExtensionMismatch: { expected, actual: file.name } };
+  };
diff --git a/packages/components/src/components/index.ts b/packages/components/src/components/index.ts
index 9cb9d87c..730c1909 100644
--- a/packages/components/src/components/index.ts
+++ b/packages/components/src/components/index.ts
@@ -54,6 +54,7 @@ export * from './ActionsPanel';
 export * from './Tree';
 export * from './TreeSelect';
 export * from './EmptyState';
+export * from './FileUpload';
 export * from './layout';
 export {
   useListData,
diff --git a/tools/api-extractor/config.json b/tools/api-extractor/config.json
index 202e10d5..6bc68bb9 100644
--- a/tools/api-extractor/config.json
+++ b/tools/api-extractor/config.json
@@ -18,6 +18,7 @@
     "DatePicker",
     "Divider",
     "EmptyState",
+    "FileUpload",
     "FlexBox",
     "Form",
     "FormField",
diff --git a/tools/public_api_guard/components/FileUpload.api.md b/tools/public_api_guard/components/FileUpload.api.md
new file mode 100644
index 00000000..b9a82856
--- /dev/null
+++ b/tools/public_api_guard/components/FileUpload.api.md
@@ -0,0 +1,538 @@
+## API Report File for "koobiq-react"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+
+import type { ChangeEvent } from 'react';
+import type { ComponentPropsWithoutRef } from 'react';
+import { Context } from 'react';
+import { CSSProperties } from 'react';
+import { DetailedHTMLProps } from 'react';
+import type { ExtendableProps } from '@koobiq/react-core';
+import { FocusEventHandler } from 'react';
+import { ForwardRefExoticComponent } from 'react';
+import { HTMLAttributes } from 'react';
+import type { InputHTMLAttributes } from 'react';
+import { JSX } from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import { ReactPortal } from 'react';
+import { Ref } from 'react';
+import { RefAttributes } from 'react';
+import type { RefObject } from 'react';
+
+// @public
+export const DropzoneContent: {
+    (props: DropzoneContentProps): JSX.Element;
+    displayName: string;
+};
+
+// @public (undocumented)
+export interface DropzoneContentProps {
+    autoCapture?: boolean;
+    caption?: ReactNode;
+    className?: string;
+    size?: DropzoneContentSize;
+    title?: string;
+}
+
+// @public (undocumented)
+export type DropzoneContentSize = (typeof dropzoneContentSize)[number];
+
+// @public
+export const dropzoneContentSize: readonly ["compact", "normal", "big"];
+
+// @public
+export interface DropzoneData {
+    autoCapture?: boolean;
+    caption?: ReactNode;
+    size?: DropzoneContentSize;
+    title?: string;
+}
+
+// @public
+export const enUSFileUploadConfig: FileUploadLocaleConfig;
+
+// @public
+export const esLAFileUploadConfig: FileUploadLocaleConfig;
+
+// @public
+export interface FileExtensionMismatchError {
+    // (undocumented)
+    fileExtensionMismatch: {
+        expected: string[];
+        actual: string;
+    };
+}
+
+// @public
+export const FileInput: ForwardRefExoticComponent<FileInputProps & RefAttributes<HTMLLabelElement>>;
+
+// @public
+export type FileInputElementProps = InputHTMLAttributes<HTMLInputElement> & {
+    webkitdirectory?: string;
+};
+
+// @public (undocumented)
+export interface FileInputProps {
+    accept?: string;
+    children?: ReactNode;
+    className?: string;
+    directory?: boolean;
+    id?: string;
+    inputRef?: Ref<HTMLInputElement>;
+    isDisabled?: boolean;
+    multiple?: boolean;
+    onChange?: (event: ChangeEvent<HTMLInputElement>) => void;
+}
+
+// @public
+export interface FileItem {
+    file: File;
+    hasError?: boolean;
+    loading?: boolean;
+    progress?: number;
+}
+
+// @public (undocumented)
+export type FileUploadAllowedType = (typeof fileUploadAllowedType)[number];
+
+// @public
+export const fileUploadAllowedType: readonly ["file", "folder", "mixed"];
+
+// @public
+export interface FileUploadCaptionContext {
+    browseLink?: string;
+    browseLinkFolder?: string;
+    captionText: string;
+    captionTextSeparator?: string;
+}
+
+// @public (undocumented)
+export const FileUploadContext: Context<FileUploadContextValue | null>;
+
+// @public
+export interface FileUploadContextValue {
+    accept?: string | null;
+    directory?: boolean | null;
+    id?: string | null;
+    isDisabled?: boolean | null;
+    multiple?: boolean | null;
+}
+
+// @public
+export interface FileUploadDropTarget {
+    addFiles: (files: FileWithPath[]) => void;
+}
+
+// @public
+export const fileUploadIntl: Record<string, FileUploadLocaleConfig>;
+
+// @public
+export interface FileUploadLocaleConfig {
+    // (undocumented)
+    multiple: MultipleFileUploadLocaleConfig;
+    // (undocumented)
+    single: SingleFileUploadLocaleConfig;
+}
+
+// @public (undocumented)
+export type FileUploadProgressMode = (typeof fileUploadProgressMode)[number];
+
+// @public
+export const fileUploadProgressMode: readonly ["determinate", "indeterminate"];
+
+// @public
+export const FileUploadProvider: {
+    (props: FileUploadProviderProps): JSX.Element;
+    displayName: string;
+};
+
+// @public (undocumented)
+export interface FileUploadProviderProps extends FileUploadContextValue {
+    children: ReactNode;
+}
+
+// @public
+export interface FileUploadSlotProps {
+    dropArea?: ComponentPropsWithoutRef<'div'>;
+}
+
+// @public
+export interface FileUploadState {
+    isDirty: boolean;
+    isInvalid: boolean;
+    isSubmitted: boolean;
+    isTouched: boolean;
+}
+
+// @public
+export type FileWithPath = File & {
+    fullPath: string;
+};
+
+// @public
+export const formatDataSize: (bytes: number, locale?: string) => string;
+
+// @public
+export const FullScreenDropzone: {
+    (props: FullScreenDropzoneProps): ReactPortal | null;
+    displayName: string;
+};
+
+// @public (undocumented)
+export interface FullScreenDropzoneProps {
+    className?: string;
+    config?: DropzoneData;
+    disabled?: boolean;
+    onFilesDropped: (files: FileWithPath[]) => void;
+}
+
+// @public
+export const isCorrectExtension: (expected: string[]) => (file: File) => FileExtensionMismatchError | null;
+
+// @public
+export const LocalDropzone: {
+    (props: LocalDropzoneProps): JSX.Element;
+    displayName: string;
+};
+
+// @public (undocumented)
+export interface LocalDropzoneProps {
+    children: ReactNode;
+    className?: string;
+    config?: DropzoneData;
+    connectedTo: RefObject<FileUploadDropTarget | null>;
+    disabled?: boolean;
+}
+
+// @public
+export const mapToFileItem: (file: File) => FileItem;
+
+// @public
+export const maxFileSize: (max: number) => (file: File) => MaxFileSizeError | null;
+
+// @public
+export interface MaxFileSizeError {
+    // (undocumented)
+    maxFileSize: {
+        max: number;
+        actual: number;
+    };
+}
+
+// @public
+export const MultipleFileUpload: ForwardRefExoticComponent<Omit<Omit<Omit<DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref">, "defaultValue" | "color" | "onChange">, "value" | "defaultValue" | "onChange" | "size" | keyof {
+className?: string;
+style?: CSSProperties;
+'data-testid'?: string | number;
+accept?: string[];
+allowed?: FileUploadAllowedType;
+isDisabled?: boolean;
+isInvalid?: boolean;
+shouldShowError?: ShouldShowError;
+progressMode?: FileUploadProgressMode;
+inputId?: string;
+onBlur?: FocusEventHandler<HTMLDivElement>;
+errorMessage?: ReactNode;
+caption?: ReactNode;
+slotProps?: FileUploadSlotProps;
+fullScreenDropzone?: boolean | DropzoneData;
+dropTargetRef?: Ref<FileUploadDropTarget>;
+disabled?: boolean;
+} | "onFilesAdded" | "onFileRemoved" | "localeConfig" | "renderFileIcon"> & {
+className?: string;
+style?: CSSProperties;
+'data-testid'?: string | number;
+accept?: string[];
+allowed?: FileUploadAllowedType;
+isDisabled?: boolean;
+isInvalid?: boolean;
+shouldShowError?: ShouldShowError;
+progressMode?: FileUploadProgressMode;
+inputId?: string;
+onBlur?: FocusEventHandler<HTMLDivElement>;
+errorMessage?: ReactNode;
+caption?: ReactNode;
+slotProps?: FileUploadSlotProps;
+fullScreenDropzone?: boolean | DropzoneData;
+dropTargetRef?: Ref<FileUploadDropTarget>;
+disabled?: boolean;
+} & {
+value?: FileItem[];
+defaultValue?: FileItem[];
+onChange?: (value: FileItem[]) => void;
+onFilesAdded?: (added: FileItem[]) => void;
+onFileRemoved?: (removed: FileItem, index: number) => void;
+size?: MultipleFileUploadSize;
+renderFileIcon?: (item: FileItem) => ReactNode;
+localeConfig?: Partial<MultipleFileUploadLocaleConfig>;
+} & RefAttributes<HTMLDivElement>>;
+
+// @public
+export interface MultipleFileUploadLocaleConfig extends SingleFileUploadLocaleConfig {
+    // (undocumented)
+    captionTextForCompactSize: string;
+    // (undocumented)
+    captionTextWhenSelected: string;
+    // (undocumented)
+    title: string;
+}
+
+// Warning: (ae-forgotten-export) The symbol "MultipleFileUploadOwnProps" needs to be exported by the entry point index.d.ts
+//
+// @public (undocumented)
+export type MultipleFileUploadProps = ExtendableProps<MultipleFileUploadOwnProps, Omit<ComponentPropsWithoutRef<'div'>, 'onChange' | 'defaultValue' | 'color'>>;
+
+// @public (undocumented)
+export type MultipleFileUploadSize = (typeof multipleFileUploadSize)[number];
+
+// @public
+export const multipleFileUploadSize: readonly ["default", "compact"];
+
+// @public
+export const ptBRFileUploadConfig: FileUploadLocaleConfig;
+
+// @public
+export const ruRUFileUploadConfig: FileUploadLocaleConfig;
+
+// @public
+export type ShouldShowError = (state: FileUploadState) => boolean;
+
+// @public
+export const showErrorOnDirty: ShouldShowError;
+
+// @public
+export const showErrorOnSubmit: ShouldShowError;
+
+// @public
+export const showErrorOnTouched: ShouldShowError;
+
+// @public
+export const showErrorRequiredOnSubmit: ShouldShowError;
+
+// @public
+export const SingleFileUpload: ForwardRefExoticComponent<Omit<Omit<Omit<DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref">, "defaultValue" | "color" | "onChange">, "value" | "defaultValue" | "onChange" | "icon" | keyof {
+className?: string;
+style?: CSSProperties;
+'data-testid'?: string | number;
+accept?: string[];
+allowed?: FileUploadAllowedType;
+isDisabled?: boolean;
+isInvalid?: boolean;
+shouldShowError?: ShouldShowError;
+progressMode?: FileUploadProgressMode;
+inputId?: string;
+onBlur?: FocusEventHandler<HTMLDivElement>;
+errorMessage?: ReactNode;
+caption?: ReactNode;
+slotProps?: FileUploadSlotProps;
+fullScreenDropzone?: boolean | DropzoneData;
+dropTargetRef?: Ref<FileUploadDropTarget>;
+disabled?: boolean;
+} | "onFilesAdded" | "onFileRemoved" | "showFileSize" | "localeConfig"> & {
+className?: string;
+style?: CSSProperties;
+'data-testid'?: string | number;
+accept?: string[];
+allowed?: FileUploadAllowedType;
+isDisabled?: boolean;
+isInvalid?: boolean;
+shouldShowError?: ShouldShowError;
+progressMode?: FileUploadProgressMode;
+inputId?: string;
+onBlur?: FocusEventHandler<HTMLDivElement>;
+errorMessage?: ReactNode;
+caption?: ReactNode;
+slotProps?: FileUploadSlotProps;
+fullScreenDropzone?: boolean | DropzoneData;
+dropTargetRef?: Ref<FileUploadDropTarget>;
+disabled?: boolean;
+} & {
+value?: FileItem | null;
+defaultValue?: FileItem | null;
+onChange?: (value: FileItem | null) => void;
+onFilesAdded?: (added: FileItem) => void;
+onFileRemoved?: (removed: FileItem) => void;
+showFileSize?: boolean;
+localeConfig?: Partial<SingleFileUploadLocaleConfig>;
+icon?: ReactNode;
+} & RefAttributes<HTMLDivElement>>;
+
+// @public
+export interface SingleFileUploadLocaleConfig {
+    // (undocumented)
+    browseLink: string;
+    // (undocumented)
+    browseLinkFolder: string;
+    // (undocumented)
+    browseLinkFolderMixed?: string;
+    // (undocumented)
+    captionText: string;
+    // (undocumented)
+    captionTextOnlyFolder: string;
+    // (undocumented)
+    captionTextWithFolder: string;
+}
+
+// Warning: (ae-forgotten-export) The symbol "SingleFileUploadOwnProps" needs to be exported by the entry point index.d.ts
+//
+// @public (undocumented)
+export type SingleFileUploadProps = ExtendableProps<SingleFileUploadOwnProps, Omit<ComponentPropsWithoutRef<'div'>, 'onChange' | 'defaultValue' | 'color'>>;
+
+// @public
+export const tkTMFileUploadConfig: FileUploadLocaleConfig;
+
+// @public
+export function useFileDrop<E extends HTMLElement = HTMLElement>(params: UseFileDropParams): UseFileDropReturn<E>;
+
+// @public (undocumented)
+export interface UseFileDropParams {
+    disabled?: boolean;
+    onFilesDropped: (files: FileWithPath[]) => void;
+}
+
+// @public (undocumented)
+export interface UseFileDropReturn<E extends HTMLElement> {
+    dropRef: RefObject<E | null>;
+}
+
+// @public
+export function useFileInput(params: UseFileInputParams): UseFileInputReturn;
+
+// @public (undocumented)
+export interface UseFileInputParams {
+    accept?: string;
+    directory?: boolean;
+    id?: string;
+    isDisabled?: boolean;
+    multiple?: boolean;
+    onChange?: (event: ChangeEvent<HTMLInputElement>) => void;
+}
+
+// @public (undocumented)
+export interface UseFileInputReturn {
+    inputProps: FileInputElementProps;
+    inputRef: RefObject<HTMLInputElement | null>;
+    reset: () => void;
+}
+
+// @public
+export function useFileList<T>(params?: UseFileListParams<T>): UseFileListReturn<T>;
+
+// @public (undocumented)
+export interface UseFileListParams<T> {
+    defaultList?: T[];
+    list?: T[];
+    onItemRemoved?: (item: T, index: number) => void;
+    onItemsAdded?: (items: T[]) => void;
+    onListChange?: (next: T[]) => void;
+}
+
+// @public (undocumented)
+export interface UseFileListReturn<T> {
+    add: (item: T) => void;
+    addArray: (items: T[]) => void;
+    list: T[];
+    remove: (item: T) => T[];
+    removeAt: (index: number) => T | undefined;
+    updateAt: (index: number, patch: Partial<T>) => void;
+}
+
+// @public
+export const useFileUploadContext: () => FileUploadContextValue | null;
+
+// @public
+export function useFileUploadItem(item: FileItem): UseFileUploadItemReturn;
+
+// @public (undocumented)
+export interface UseFileUploadItemReturn {
+    isLoading: boolean;
+    progress: number;
+}
+
+// @public
+export function useFileUploadState(params: UseFileUploadStateParams): UseFileUploadStateReturn;
+
+// @public (undocumented)
+export interface UseFileUploadStateParams {
+    isInvalid?: boolean;
+    isSubmitted?: boolean;
+    shouldShowError?: ShouldShowError;
+}
+
+// @public (undocumented)
+export interface UseFileUploadStateReturn {
+    errorState: boolean;
+    isDirty: boolean;
+    isTouched: boolean;
+    markDirty: () => void;
+    markTouched: () => void;
+    state: FileUploadState;
+}
+
+// @public
+export function useFullScreenDropzone(params: UseFullScreenDropzoneParams): UseFullScreenDropzoneReturn;
+
+// @public (undocumented)
+export interface UseFullScreenDropzoneParams {
+    disabled?: boolean;
+    enabled: boolean;
+    onFilesDropped: (files: FileWithPath[]) => void;
+}
+
+// @public (undocumented)
+export interface UseFullScreenDropzoneReturn {
+    isOpen: boolean;
+}
+
+// @public
+export function useMultipleFileUploadLocale(params: UseMultipleFileUploadLocaleParams): UseMultipleFileUploadLocaleReturn;
+
+// @public (undocumented)
+export interface UseMultipleFileUploadLocaleParams {
+    // (undocumented)
+    allowed: FileUploadAllowedType;
+    // (undocumented)
+    hasFiles: boolean;
+    // (undocumented)
+    localeConfig?: Partial<MultipleFileUploadLocaleConfig>;
+    // (undocumented)
+    size: MultipleFileUploadSize;
+}
+
+// @public (undocumented)
+export interface UseMultipleFileUploadLocaleReturn {
+    // (undocumented)
+    captionContext: FileUploadCaptionContext;
+    // (undocumented)
+    config: MultipleFileUploadLocaleConfig;
+    // (undocumented)
+    locale: string;
+    whenSelectedText: string;
+}
+
+// @public
+export function useSingleFileUploadLocale(params: UseSingleFileUploadLocaleParams): UseSingleFileUploadLocaleReturn;
+
+// @public (undocumented)
+export interface UseSingleFileUploadLocaleParams {
+    // (undocumented)
+    allowed: FileUploadAllowedType;
+    // (undocumented)
+    localeConfig?: Partial<SingleFileUploadLocaleConfig>;
+}
+
+// @public (undocumented)
+export interface UseSingleFileUploadLocaleReturn {
+    // (undocumented)
+    captionContext: FileUploadCaptionContext;
+    // (undocumented)
+    config: SingleFileUploadLocaleConfig;
+    // (undocumented)
+    locale: string;
+}
+
+// (No @packageDocumentation comment for this package)
+
+```