@mantis-core/ui 0.4.0 → 0.6.0

package/docs/components/confirm-dialog.md

@@ -1,21 +1,50 @@
-# ConfirmDialog
-
-- Export: `ConfirmDialog`
-- Extra exports: `ConfirmDialogProps`, `ConfirmDialogSeverity`
-- Import: `import { ConfirmDialog } from "@mantis-core/ui";`
-- Base library: `primereact/dialog`
-- Base typing: explicit `ConfirmDialogProps`
-- Required styles: `@mantis-core/styles/scss/confirm-dialog.scss`
+---
+name: ConfirmDialog
+category: feedback
+import: '@mantis-core/ui/components/ui/ConfirmDialog'
+whenToUse: Confirm/cancel dialog for destructive or non-trivial actions; composed from the migrated Modal + Button.
+baseLibrary: custom
+requiredStyles: [scss/confirm-dialog.scss]
+relatedComponents: ['Modal', 'Button']
+relatedNextCore: []
+props:
+  - { name: visible, type: boolean, required: true }
+  - { name: onConfirm, type: '() => void | Promise<void>', required: true }
+  - { name: onCancel, type: '() => void', required: true }
+  - { name: title, type: ReactNode, required: false, default: "'Confirmar accion'" }
+  - { name: message, type: ReactNode, required: false, default: "'Esta accion no se puede deshacer.'" }
+  - { name: icon, type: ReactNode, required: false }
+  - { name: confirmLabel, type: string, required: false, default: "'Confirmar'" }
+  - { name: cancelLabel, type: string, required: false, default: "'Cancelar'" }
+  - { name: confirmSeverity, type: "'primary' | 'info' | 'success' | 'warning' | 'danger'", required: false, default: "'danger'" }
+  - { name: loading, type: boolean, required: false, default: 'false' }
+  - { name: disabled, type: boolean, required: false, default: 'false' }
+  - { name: className, type: string, required: false }
+---
 
 ## Example
 
 ```tsx
-<ConfirmDialog
-  visible={open}
-  title="Delete listing"
-  message="This action cannot be undone."
-  confirmSeverity="danger"
-  onConfirm={handleDelete}
-  onCancel={() => setOpen(false)}
-/>
+import ConfirmDialog from '@mantis-core/ui/components/ui/ConfirmDialog';
+import { useState } from 'react';
+
+function Example() {
+  const [visible, setVisible] = useState(false);
+  return (
+    <ConfirmDialog
+      visible={visible}
+      title='Delete property?'
+      message='This cannot be undone.'
+      confirmSeverity='danger'
+      onConfirm={() => setVisible(false)}
+      onCancel={() => setVisible(false)}
+    />
+  );
+}
 ```
+
+## Notes
+
+- Renders headerless inside a `size="sm"` Modal — title/message live in the body, actions in the footer.
+- Backdrop/close dismissal is treated as cancel, unless `loading` is `true` — dismissal is blocked while an action is in flight.
+- Default copy is Spanish; override `title`/`message`/`confirmLabel`/`cancelLabel` for other locales.

package/docs/components/data-state.md

@@ -1,19 +1,44 @@
-# DataState
-
-- Export: `DataState`
-- Extra exports: `DataStateProps`, `DataStateStatus`
-- Import: `import { DataState } from "@mantis-core/ui";`
-- Base library: custom state wrapper + `Button`
-- Base typing: explicit `DataStateProps`
-- Required styles: `@mantis-core/styles/scss/data-state.scss`
+---
+name: DataState
+category: feedback
+import: '@mantis-core/ui/components/ui/DataState'
+whenToUse: Loading/empty/error/ready placeholder for data-fetching views; renders `children` unchanged when `status="ready"`, otherwise a titled state panel.
+baseLibrary: custom
+requiredStyles: [scss/data-state.scss]
+relatedComponents: ['StatusBadge', 'Loading']
+relatedNextCore: []
+props:
+  - { name: status, type: "'ready' | 'loading' | 'empty' | 'error'", required: true }
+  - { name: className, type: string, required: false }
+  - { name: children, type: ReactNode, required: false, description: 'Rendered as-is only when `status` is `"ready"`.' }
+  - { name: icon, type: ReactNode, required: false, description: 'Overrides the default per-status icon (spinner/inbox/triangle).' }
+  - { name: loadingTitle, type: ReactNode, required: false, default: "'Cargando informacion'" }
+  - { name: loadingDescription, type: ReactNode, required: false, default: "'Espera un momento mientras consultamos los datos.'" }
+  - { name: emptyTitle, type: ReactNode, required: false, default: "'Sin resultados'" }
+  - { name: emptyDescription, type: ReactNode, required: false, default: "'No hay registros para mostrar con los filtros actuales.'" }
+  - { name: emptyAction, type: ReactNode, required: false }
+  - { name: errorTitle, type: ReactNode, required: false, default: "'No se pudo cargar la informacion'" }
+  - { name: errorDescription, type: ReactNode, required: false, default: "'Ocurrio un error al consultar los datos.'" }
+  - { name: errorAction, type: ReactNode, required: false, description: 'Overrides the default retry Button built from `onRetry`.' }
+  - { name: onRetry, type: '() => void', required: false, description: 'Renders a default retry Button on `error` when `errorAction` is not given.' }
+  - { name: retryLabel, type: string, required: false, default: "'Reintentar'" }
+---
 
 ## Example
 
 ```tsx
-<DataState
-  status={query.isError ? "error" : query.isLoading ? "loading" : rows.length === 0 ? "empty" : "ready"}
-  onRetry={() => query.refetch()}
->
-  <PaginatedTable value={rows}>{/* columns */}</PaginatedTable>
-</DataState>
+import DataState from '@mantis-core/ui/components/ui/DataState';
+
+function Example() {
+  return (
+    <DataState status='empty' emptyTitle='No properties found' emptyDescription='Try adjusting your filters.'>
+      <ul />
+    </DataState>
+  );
+}
 ```
+
+## Notes
+
+- `status="ready"` short-circuits to `<>{children}</>` — every other prop is ignored in that case.
+- Default copy is Spanish; override the `*Title`/`*Description` props for other locales.

package/docs/components/date-field.md

@@ -0,0 +1,39 @@
+---
+name: DateField
+category: forms
+import: '@mantis-core/ui/components/Forms/DateField'
+whenToUse: Single date, date-range, or time-only picker wired to react-hook-form; one wrapper covers all three via `selectionMode`/`timeOnly`/`showTime`.
+baseLibrary: '@primereact/ui/datepicker'
+formContract: FieldControllerProps
+relatedComponents: ['DatePresets', 'MaskField']
+relatedNextCore: []
+props:
+  - { name: selectionMode, type: "'single' | 'multiple' | 'range'", required: false, default: "'single'", description: 'Drives the value shape: Date for single, Date[] for multiple, (Date|null)[] for range.' }
+  - { name: showTime, type: boolean, required: false, default: 'false', description: 'Adds hour/minute pickers alongside the calendar.' }
+  - { name: timeOnly, type: boolean, required: false, default: 'false', description: 'Hides the calendar, showing only the time pickers.' }
+  - { name: hourFormat, type: "'12' | '24'", required: false, default: "'24'", description: 'Adds an AM/PM picker when set to 12.' }
+  - { name: showSeconds, type: boolean, required: false, default: 'false', description: 'Adds a seconds picker (with showTime/timeOnly).' }
+  - { name: minDate, type: Date, required: false }
+  - { name: maxDate, type: Date, required: false }
+  - { name: placeholder, type: string, required: false }
+  - { name: showButtonBar, type: boolean, required: false, default: 'false', description: 'Renders a Today + Clear footer inside the panel.' }
+---
+
+## Example
+
+```tsx
+import { DateField } from '@mantis-core/ui/components/Forms/DateField';
+import { useForm } from 'react-hook-form';
+
+function Example() {
+  const { control } = useForm({ defaultValues: { fecha: null as Date | null } });
+  return <DateField name='fecha' control={control} label='Fecha' />;
+}
+```
+
+## Notes
+
+- Folds the three former PR10 date components: single date (default), range (`selectionMode="range"`, value `[start, end]`), and time (`timeOnly`/`showTime`). `react-datepicker` is gone.
+- Value collapses every PR11 "empty" shape (`[]`, `[null, null]`) to a canonical `null` — a partial in-progress range (`[Date, null]`) passes through untouched.
+- Built-in clear affordance (✕ in the input) and, when `showButtonBar`, a Today/Clear footer — both route through the same empty-value normalization.
+- Pair with `DatePresets` for a quick-range button row above a `selectionMode="range"` field.

package/docs/components/date-presets.md

@@ -0,0 +1,32 @@
+---
+name: DatePresets
+category: forms
+import: '@mantis-core/ui/components/Forms/DatePresets'
+whenToUse: Row of quick-range preset buttons (Today, 7 days, 30 days, This month) that fire onChange with a [Date, Date] tuple. Not RHF-bound — pair with a `DateField` in `selectionMode="range"`.
+baseLibrary: '@primereact/ui/button'
+relatedComponents: ['DateField']
+relatedNextCore: []
+props:
+  - { name: onChange, type: '(range: [Date, Date]) => void', required: true }
+  - { name: presets, type: '{ label: string; resolve: () => [Date, Date] }[]', required: false, description: 'Defaults to Today / 7 días / 30 días / Este mes.' }
+  - { name: className, type: string, required: false }
+  - { name: disabled, type: boolean, required: false }
+---
+
+## Example
+
+```tsx
+import DatePresets from '@mantis-core/ui/components/Forms/DatePresets';
+import { useState } from 'react';
+
+function Example() {
+  const [range, setRange] = useState<[Date, Date] | null>(null);
+  return <DatePresets onChange={setRange} />;
+}
+```
+
+## Notes
+
+- Default export, not a named export.
+- Purely presentational: each preset renders as a PR11 `Button` (`type="button"`, `variant="outlined"`, `size="small"`) and calls `onChange` with its `resolve()` result — it does not read or write any form state itself.
+- Default preset labels are hardcoded in Spanish ("Hoy", "7 días", "30 días", "Este mes") — pass your own `presets` for other locales.

package/docs/components/description-list.md

@@ -0,0 +1,34 @@
+---
+name: DescriptionList
+category: data
+import: '@mantis-core/ui/components/data/DescriptionList'
+whenToUse: Grid-based label/value list for detail views; supports 1, 2, or 3 columns.
+baseLibrary: custom
+relatedComponents: ['StatCard']
+relatedNextCore: []
+props:
+  - { name: items, type: '{ label: string; value: ReactNode }[]', required: true }
+  - { name: columns, type: '1 | 2 | 3', required: false, default: '1' }
+---
+
+## Example
+
+```tsx
+import DescriptionList from '@mantis-core/ui/components/data/DescriptionList';
+
+function Example() {
+  return (
+    <DescriptionList
+      columns={2}
+      items={[
+        { label: 'Name', value: 'Jane Doe' },
+        { label: 'Email', value: 'jane@example.com' },
+      ]}
+    />
+  );
+}
+```
+
+## Notes
+
+- Not re-exported from the package root — import the deep path shown above.

package/docs/components/dirty-form-guard.md

@@ -1,31 +1,35 @@
-# DirtyFormGuard and useDirtyFormGuard
-
-- Exports: `DirtyFormGuard`, `useDirtyFormGuard`
-- Extra exports: `DirtyFormGuardProps`, `UseDirtyFormGuardOptions`, `UseDirtyFormGuardResult`
-- Base library: browser `beforeunload` + `window.confirm`
-- Required styles: none
-
-## Component example
-
-```tsx
-<DirtyFormGuard
-  isDirty={form.formState.isDirty}
-  message="You have unsaved changes."
-/>
-```
-
-## Hook example
+---
+name: DirtyFormGuard
+category: forms
+import: '@mantis-core/ui/components/Forms/DirtyFormGuard'
+whenToUse: Blocks tab-close/reload when a react-hook-form has unsaved changes; render it declaratively, or use the underlying useDirtyFormGuard hook to also guard programmatic navigation.
+baseLibrary: custom
+relatedComponents: [FormActionsBar]
+relatedNextCore: []
+props:
+  - { name: isDirty, type: boolean, required: true, description: 'Pass formState.isDirty from react-hook-form' }
+  - { name: enabled, type: boolean, required: false, default: 'true', description: 'Set to false to temporarily disable the guard' }
+  - { name: message, type: string, required: false, description: 'Custom confirmation message shown to the user' }
+---
+
+## Example
 
 ```tsx
-const guard = useDirtyFormGuard({
-  isDirty: form.formState.isDirty,
-  message: "Leave without saving?",
-});
+import DirtyFormGuard from '@mantis-core/ui/components/Forms/DirtyFormGuard';
+import { useForm } from 'react-hook-form';
 
-void guard.confirmIfDirty(async () => router.push("/admin"));
+function Example() {
+  const { formState } = useForm({ defaultValues: { name: '' } });
+  return <DirtyFormGuard isDirty={formState.isDirty} />;
+}
 ```
 
 ## Notes
 
-- Use the component for declarative page guards.
-- Use the hook when you need to wrap specific navigation or destructive actions.
+- Renders nothing (`return null`) — it only attaches a `beforeunload` listener while
+  `enabled && isDirty`.
+- Also exported as the `useDirtyFormGuard(options)` hook, returning `{ shouldProceed,
+  confirmIfDirty }`: `shouldProceed()` runs `window.confirm(message)` and `confirmIfDirty(action)`
+  runs `action()` only if the user confirms (or the form isn't dirty). Use the hook to guard
+  programmatic navigation (router pushes, tab switches, discard buttons) that `beforeunload` can't
+  catch; use the component for the tab-close/reload case.

package/docs/components/donut-chart.md

@@ -0,0 +1,38 @@
+---
+name: DonutChart
+category: charts
+import: '@mantis-core/ui/components/charts/DonutChart'
+whenToUse: Part-to-whole breakdown rendered as a doughnut chart, zero-config over chart.js defaults.
+baseLibrary: chart.js
+requiredStyles: []
+relatedComponents: [LineChart, BarChart]
+relatedNextCore: []
+props:
+  - { name: labels, type: 'string[]', required: true }
+  - { name: datasets, type: '{ data: number[]; label?: string }[]', required: true, description: 'Typically a single-entry array — one value per label/slice.' }
+  - { name: options, type: 'ChartOptions<''doughnut''>', required: false, description: 'Deep-merged over defaultDonutOptions (plugins merge shallowly one level).' }
+  - { name: colors, type: 'string[]', required: false, default: 'DEFAULT_COLORS (8-color palette)', description: 'Applied per-slice (cycled by label index) unless the dataset supplies its own backgroundColor/borderColor.' }
+  - { name: height, type: number, required: false, default: '300', description: 'Container height in px.' }
+  - { name: className, type: string, required: false }
+---
+
+## Example
+
+```tsx
+import DonutChart from '@mantis-core/ui/components/charts/DonutChart';
+
+function Example() {
+  return (
+    <DonutChart
+      labels={['Leads', 'Closed', 'Lost']}
+      datasets={[{ data: [60, 25, 15] }]}
+    />
+  );
+}
+```
+
+## Notes
+
+- Not re-exported from the package root — import from the deep path above (`@mantis-core/ui/components/charts/DonutChart`), not `@mantis-core/ui`.
+- Calls `registerCharts()` (module-level, from `./chart-setup`) on import — no separate chart.js registration needed.
+- Legend defaults to `position: 'right'` (vs. `'top'` for Bar/Line).

package/docs/components/drawer.md

@@ -0,0 +1,38 @@
+---
+name: Drawer
+category: overlays
+import: '@mantis-core/ui/components/overlays/Drawer'
+whenToUse: Controlled slide-in side panel; composes PR11's headless Drawer compound (Root/Portal/Backdrop/Popup/Header/Content/Footer — no Positioner, unlike Dialog) behind a simple `open`/`side`/`title`/`footer` API.
+baseLibrary: '@primereact/ui/drawer'
+relatedComponents: ['Modal', 'FilterPannel']
+relatedNextCore: []
+props:
+  - { name: open, type: boolean, required: true, description: 'Controlled visibility.' }
+  - { name: onOpenChange, type: '(open: boolean) => void', required: true, description: 'Fires with the next open value when the backdrop/close toggles it.' }
+  - { name: side, type: "'left' | 'right' | 'top' | 'bottom'", required: false, default: "'right'", description: 'Edge the panel slides in from — maps to PR11 `position`.' }
+  - { name: title, type: ReactNode, required: false, description: 'Header title. Omit to render no header.' }
+  - { name: footer, type: ReactNode, required: false, description: 'Footer content. Omit to render no footer.' }
+  - { name: className, type: string, required: false, description: 'Extra class on the Popup element.' }
+  - { name: children, type: ReactNode, required: false }
+---
+
+## Example
+
+```tsx
+import Drawer from '@mantis-core/ui/components/overlays/Drawer';
+import { useState } from 'react';
+
+function Example() {
+  const [open, setOpen] = useState(false);
+  return (
+    <Drawer open={open} onOpenChange={setOpen} side='right' title='Filters'>
+      <p>Filter form</p>
+    </Drawer>
+  );
+}
+```
+
+## Notes
+
+- Without a `title`, still renders a dismissable close (X) button (used e.g. by AppShell's mobile nav) — the panel is never un-dismissable.
+- No `requiredStyles` — preset-themed.

package/docs/components/empty-state.md

@@ -0,0 +1,28 @@
+---
+name: EmptyState
+category: feedback
+import: '@mantis-core/ui/components/feedback/EmptyState'
+whenToUse: Centered empty-state placeholder with icon, title, optional description, and action button.
+baseLibrary: custom
+relatedComponents: ['DataState']
+relatedNextCore: []
+props:
+  - { name: title, type: ReactNode, required: true }
+  - { name: icon, type: ReactNode, required: false }
+  - { name: description, type: ReactNode, required: false }
+  - { name: action, type: ReactNode, required: false }
+---
+
+## Example
+
+```tsx
+import EmptyState from '@mantis-core/ui/components/feedback/EmptyState';
+
+function Example() {
+  return <EmptyState title='No properties yet' description='Create your first property to get started.' />;
+}
+```
+
+## Notes
+
+- Not re-exported from the package root — import the deep path shown above.

package/docs/components/error-boundary.md

@@ -0,0 +1,31 @@
+---
+name: ErrorBoundary
+category: feedback
+import: '@mantis-core/ui/components/feedback/ErrorBoundary'
+whenToUse: React class error boundary; renders fallback UI on uncaught render errors in its children.
+baseLibrary: custom
+relatedNextCore: []
+props:
+  - { name: children, type: ReactNode, required: true }
+  - { name: fallback, type: 'ReactNode | ((error: Error) => ReactNode)', required: false }
+  - { name: onError, type: '(error: Error, info: ErrorInfo) => void', required: false }
+---
+
+## Example
+
+```tsx
+import ErrorBoundary from '@mantis-core/ui/components/feedback/ErrorBoundary';
+
+function Example() {
+  return (
+    <ErrorBoundary fallback={<p>Something went wrong.</p>}>
+      <div>Feature content</div>
+    </ErrorBoundary>
+  );
+}
+```
+
+## Notes
+
+- Not re-exported from the package root — import the deep path shown above.
+- `fallback` as a function receives the caught `Error`; as a plain node it renders as-is. Omitted entirely, it falls back to a minimal built-in message.

package/docs/components/error-message.md

@@ -1,13 +1,34 @@
-# ErrorMessage
-
-- Export: `ErrorMessage`
-- Import: `import { ErrorMessage } from "@mantis-core/ui";`
-- Base library: `@hookform/error-message`
-- Base typing: wrapper export around hook-form error rendering
-- Required styles: none
+---
+name: ErrorMessage
+category: forms
+import: '@mantis-core/ui/components/Forms/ErrorMessage'
+whenToUse: 'Standalone validation-error text for one named react-hook-form field, read from form context; use when composing a custom layout instead of FormFieldRender.'
+baseLibrary: '@hookform/error-message'
+relatedComponents: ['FormFieldRender']
+relatedNextCore: []
+props:
+  - { name: name, type: string, required: true, description: 'The RHF field name to read the error for.' }
+---
 
 ## Example
 
 ```tsx
-<ErrorMessage errors={form.formState.errors} name="title" />
+import ErrorMessage from '@mantis-core/ui/components/Forms/ErrorMessage';
+import { FormProvider, useForm } from 'react-hook-form';
+
+function Example() {
+  const methods = useForm({ defaultValues: { email: '' } });
+  return (
+    <FormProvider {...methods}>
+      <ErrorMessage name='email' />
+    </FormProvider>
+  );
+}
 ```
+
+## Notes
+
+- Reads `useFormState({ name })` with no explicit `control` — it resolves the form from React
+  context, so it must render inside a `<FormProvider>`.
+- Pre-`FieldControllerProps` component: it only displays a message string, it does not wrap an
+  input or manage aria wiring itself (compare `FieldShell`, which owns aria via `useFieldController`).

package/docs/components/field-shell.md

@@ -0,0 +1,47 @@
+---
+name: FieldShell
+category: forms
+import: '@mantis-core/ui/components/Forms/FieldShell'
+whenToUse: 'Presentation primitive for label + addon + help/error composition around one input; every FieldControllerProps-based field wrapper renders it internally — reach for it directly only when hand-building a new wrapper (see field-controller.md).'
+baseLibrary: custom
+formContract: FieldControllerProps
+relatedComponents: ['TextField', 'useFieldController']
+relatedNextCore: []
+props:
+  - { name: id, type: string, required: true, description: 'Input id; also roots the generated help/error ids (`${id}-help` / `${id}-error`).' }
+  - { name: label, type: string, required: false }
+  - { name: required, type: boolean, required: false, description: 'Presentational ` *` marker on the label; validation is still driven by rules.' }
+  - { name: helpText, type: string, required: false }
+  - { name: errorMessage, type: string, required: false, description: 'Typically `useFieldController(...).errorMessage`.' }
+  - { name: labelMode, type: LabelMode, required: false, description: '''ifta'' | ''float'' | ''beside'' | ''top'' | ''none'' — defaults to MantisThemeProvider.' }
+  - { name: floatVariant, type: FloatVariant, required: false, description: '''over'' | ''in'' | ''on'' — only used when labelMode=''float''.' }
+  - { name: addonBefore, type: ReactNode, required: false }
+  - { name: addonAfter, type: ReactNode, required: false }
+  - { name: children, type: ReactNode, required: true, description: 'The input/trigger element.' }
+---
+
+## Example
+
+```tsx
+import { FieldShell } from '@mantis-core/ui/components/Forms/FieldShell';
+
+function Example() {
+  return (
+    <FieldShell id='email' label='Email' helpText='We will never share it.'>
+      <input id='email' type='email' />
+    </FieldShell>
+  );
+}
+```
+
+## Notes
+
+- Not itself a `FieldControllerProps` field — it takes `id`/`errorMessage`/`labelMode` etc. directly;
+  pair it with `useFieldController` to build a new RHF-bound wrapper (see
+  [`field-controller.md`](../contracts/field-controller.md)).
+- `fluid` is read from `useFieldConfig()` context, not a shell prop — there is no per-shell fluid override.
+- Renders inside PR11's `IftaLabel`/`FloatLabel` (label modes) and `InputGroup.Root` (addons); falls
+  back to `DEFAULT_FIELD_CONFIG` when no `MantisThemeProvider` is mounted, so it renders sanely
+  without a provider (e.g. isolated tests).
+- Help and error `<small>` elements both render when both are truthy — there is no suppression; only
+  `aria-describedby` (computed by `useFieldController`, not by this component) prefers the error.

package/docs/components/file-dropzone.md

@@ -1,25 +1,53 @@
-# FileDropzone
-
-- Export: `FileDropzone`
-- Extra exports: `FileDropzoneProps`, `FileDropzoneRejectedFile`, `FileDropzoneRejectCode`
-- Import: `import { FileDropzone } from "@mantis-core/ui";`
-- Base library: custom drag-and-drop file input
-- Base typing: explicit `FileDropzoneProps`
-- Required styles: `@mantis-core/styles/scss/file-dropzone.scss`
+---
+name: FileDropzone
+category: forms
+import: '@mantis-core/ui/components/Forms/FileDropzone'
+whenToUse: Drag-and-drop file input with validation (type, size, count); supports a react-hook-form binding or plain controlled value/onChange.
+baseLibrary: custom
+requiredStyles: [scss/file-dropzone.scss]
+relatedComponents: [UploadFilesPreview]
+relatedNextCore: []
+props:
+  - { name: controller, type: 'Pick<FieldControllerProps, "name" | "control" | "rules" | "defaultValue" | "shouldUnregister">', required: false, description: 'When provided, wires the dropzone to react-hook-form via this nested object.' }
+  - { name: value, type: 'File[]', required: false, description: 'Controlled file list (plain mode, when `controller` is omitted)' }
+  - { name: onChange, type: '(files: File[]) => void', required: false, description: 'Change handler (plain mode)' }
+  - { name: onFilesAccepted, type: '(files: File[]) => void', required: false, description: 'Called with accepted files after drop' }
+  - { name: onFilesRejected, type: '(rejections: FileDropzoneRejectedFile[]) => void', required: false, description: 'Called with rejected files after drop' }
+  - { name: multiple, type: boolean, required: false, default: 'true', description: 'Allow multiple files' }
+  - { name: maxFiles, type: number, required: false, default: '10', description: 'Maximum number of files' }
+  - { name: maxSizeBytes, type: number, required: false, default: '10485760', description: 'Max file size in bytes (default 10 MB)' }
+  - { name: accept, type: 'string | string[]', required: false, description: 'Accepted MIME types or extensions' }
+  - { name: disabled, type: boolean, required: false, default: 'false', description: 'Disable the dropzone' }
+  - { name: block, type: boolean, required: false, default: 'true', description: 'Full-width layout' }
+  - { name: label, type: string, required: false, description: 'Optional label above the zone' }
+  - { name: hint, type: string, required: false, description: 'Hint text inside the zone' }
+  - { name: dropTitle, type: string, required: false, description: 'Title text when idle' }
+  - { name: dragOverTitle, type: string, required: false, description: 'Title text while dragging over' }
+  - { name: className, type: string, required: false, description: 'Additional CSS class on the root element' }
+---
 
 ## Example
 
 ```tsx
-<FileDropzone
-  controller={{ name: "attachments", control: form.control, defaultValue: [] }}
-  accept={["image/*", ".pdf"]}
-  maxFiles={5}
-  maxSizeBytes={5 * 1024 * 1024}
-  label="Attachments"
-/>
+import FileDropzone from '@mantis-core/ui/components/Forms/FileDropzone';
+import { useForm, type FieldValues } from 'react-hook-form';
+
+function Example() {
+  const { control } = useForm<FieldValues>({ defaultValues: { documents: [] as File[] } });
+  return (
+    <FileDropzone
+      controller={{ name: 'documents', control }}
+      accept={['.pdf', '.jpg']}
+      maxFiles={5}
+    />
+  );
+}
 ```
 
 ## Notes
 
-- Supports both `react-hook-form` mode and plain controlled mode with `value` and `onChange`.
-- Rejections are normalized into `FileDropzoneRejectedFile`.
+- `controller` is a nested object (legacy pattern: `{ name, control, rules }`), not the flattened
+  `FieldControllerProps` other PR11 field wrappers accept as top-level props.
+- Rejections are normalized into `FileDropzoneRejectedFile` (`{ file, code, message }`); the RHF
+  binding disables the dropzone during `formState.isSubmitting` in addition to the `disabled` prop.
+- Omit `controller` to use it as a plain controlled input with `value`/`onChange`.