@mantis-core/ui 0.5.0 → 0.7.0

package/docs/components/confirm-dialog.md

@@ -2,22 +2,49 @@
 name: ConfirmDialog
 category: feedback
 import: '@mantis-core/ui/components/ui/ConfirmDialog'
-whenToUse: Modal confirmation dialog with confirm/cancel buttons and severity-aware styling.
-baseLibrary: primereact/dialog
+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', required: true }
+  - { name: onConfirm, type: '() => void | Promise<void>', required: true }
   - { name: onCancel, type: '() => void', required: true }
-  - { name: title, type: ReactNode, required: false }
-  - { name: message, type: ReactNode, required: false }
-  - { name: confirmSeverity, type: '''primary'' | ''info'' | ''success'' | ''warning'' | ''danger''', required: false, default: '''danger''' }
-  - { name: loading, type: boolean, required: false }
-  - { name: width, type: string, required: false, default: '''30rem''' }
+  - { 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={showConfirm} title='Delete?' message='This cannot be undone.' confirmSeverity='danger' onConfirm={handleDelete} onCancel={() => setShowConfirm(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

@@ -2,18 +2,43 @@
 name: DataState
 category: feedback
 import: '@mantis-core/ui/components/ui/DataState'
-whenToUse: Full-area empty/error/loading state placeholder for data-fetching views.
+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]
+relatedComponents: ['StatusBadge', 'Loading']
 relatedNextCore: []
 props:
-  - { name: status, type: DataStateStatus, required: true }
-  - { name: message, type: string, required: false }
-  - { name: action, type: ReactNode, required: false }
+  - { 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='empty' message='No properties found' action={<Button label='Add first' onClick={onCreate} />} />
+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

@@ -2,17 +2,31 @@
 name: DatePresets
 category: forms
 import: '@mantis-core/ui/components/Forms/DatePresets'
-whenToUse: 'Row of preset buttons (Hoy, 7 días, 30 días, Este mes) that fire onChange with a [Date, Date] range; pair with DateRangeInput.'
-baseLibrary: custom
+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 }
-  - { name: disabled, type: boolean, required: false }
+  - { 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
-<DatePresets onChange={(range) => setValue('period', range)} />
+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

@@ -2,15 +2,33 @@
 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.'
+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
-<DescriptionList columns={2} items={[{ label: 'Nombre', value: lead.name }, { label: 'Email', value: lead.email }]} />
+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

@@ -2,7 +2,7 @@
 name: DirtyFormGuard
 category: forms
 import: '@mantis-core/ui/components/Forms/DirtyFormGuard'
-whenToUse: Blocks navigation when a react-hook-form has unsaved changes; also available as useDirtyFormGuard hook.
+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: []
@@ -11,13 +11,25 @@ props:
   - { 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
-{/* TODO: add example */}
+import DirtyFormGuard from '@mantis-core/ui/components/Forms/DirtyFormGuard';
+import { useForm } from 'react-hook-form';
+
+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

@@ -2,20 +2,37 @@
 name: DonutChart
 category: charts
 import: '@mantis-core/ui/components/charts/DonutChart'
-whenToUse: Part-to-whole breakdown rendered as a doughnut chart.
-baseLibrary: custom
+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 }
-  - { name: options, type: 'ChartOptions<''doughnut''>', required: false }
-  - { name: colors, type: 'string[]', required: false, default: DEFAULT_COLORS palette }
-  - { name: height, type: number, required: false, default: '300' }
+  - { 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
-<DonutChart labels={['Leads','Closed','Lost']} datasets={[{ data: [60,25,15] }]} />
+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

@@ -2,18 +2,37 @@
 name: Drawer
 category: overlays
 import: '@mantis-core/ui/components/overlays/Drawer'
-whenToUse: Slide-in side panel (PrimeReact Sidebar wrapper); defaults to right position.
-baseLibrary: custom
+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: visible, type: boolean, required: true }
-  - { name: onHide, type: '() => void', required: true }
-  - { name: position, type: '''left'' | ''right'' | ''top'' | ''bottom''', required: false, default: '''right''' }
-  - { name: header, type: ReactNode, required: false }
-  - { name: className, type: string, required: false }
+  - { 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
-<Drawer visible={open} onHide={() => setOpen(false)} header='Filtros'><FilterForm /></Drawer>
+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

@@ -2,8 +2,9 @@
 name: EmptyState
 category: feedback
 import: '@mantis-core/ui/components/feedback/EmptyState'
-whenToUse: 'Centered empty-state placeholder with icon, title, optional description, and action button.'
+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 }
@@ -11,8 +12,17 @@ props:
   - { name: description, type: ReactNode, required: false }
   - { name: action, type: ReactNode, required: false }
 ---
+
 ## Example
 
 ```tsx
-<EmptyState icon={<i className='pi pi-inbox' />} title='Sin propiedades' description='Crea tu primera propiedad.' action={<Button label='Nueva' onClick={onCreate} />} />
+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

@@ -2,7 +2,7 @@
 name: ErrorBoundary
 category: feedback
 import: '@mantis-core/ui/components/feedback/ErrorBoundary'
-whenToUse: React error boundary; renders fallback UI on uncaught errors; fallback can be a ReactNode or render function.
+whenToUse: React class error boundary; renders fallback UI on uncaught render errors in its children.
 baseLibrary: custom
 relatedNextCore: []
 props:
@@ -10,8 +10,22 @@ props:
   - { name: fallback, type: 'ReactNode | ((error: Error) => ReactNode)', required: false }
   - { name: onError, type: '(error: Error, info: ErrorInfo) => void', required: false }
 ---
+
 ## Example
 
 ```tsx
-<ErrorBoundary fallback={<p>Algo salió mal.</p>}><FeatureView /></ErrorBoundary>
+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

@@ -2,14 +2,33 @@
 name: ErrorMessage
 category: forms
 import: '@mantis-core/ui/components/Forms/ErrorMessage'
-whenToUse: Displays a validation error string; use standalone when not using FormFieldRender.
+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: message, type: string, required: false }
+  - { name: name, type: string, required: true, description: 'The RHF field name to read the error for.' }
 ---
+
 ## Example
 
 ```tsx
-<ErrorMessage message={errors.email?.message} />
+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

@@ -2,14 +2,14 @@
 name: FileDropzone
 category: forms
 import: '@mantis-core/ui/components/Forms/FileDropzone'
-whenToUse: Drag-and-drop file input with validation (type, size, count); supports react-hook-form mode and plain controlled mode.
+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: ControllerProps, required: false, description: 'When provided, wires to react-hook-form' }
-  - { name: value, type: 'File[]', required: false, description: 'Controlled file list (plain mode)' }
+  - { 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' }
@@ -25,13 +25,29 @@ props:
   - { 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
-{/* TODO: add example */}
+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`.

package/docs/components/filter-pannel.md

@@ -2,20 +2,47 @@
 name: FilterPannel
 category: tables
 import: '@mantis-core/ui/components/Tables/FilterPannel'
-whenToUse: Slide-in sidebar filter panel for tables; wraps children in FormProvider and calls onApplyFilter with cleaned form data.
-baseLibrary: primereact/sidebar
-relatedComponents: [PaginatedTable, MultiSelectFilter]
+whenToUse: 'Slide-in filter sidebar for tables; wraps RHF-bound filter fields in their own `FormProvider` and calls `onApplyFilter` with the cleaned form data.'
+baseLibrary: custom
+relatedComponents: [PaginatedTable, MultiSelectFilter, TableFilterField]
 relatedNextCore: []
 props:
-  - { name: onApplyFilter, type: '(data: T) => Promise<void>', required: true }
+  - { name: onApplyFilter, type: '(data: T) => Promise<void>', required: true, description: 'Called with the cleaned form data on submit (Aplicar), or `{}` on reset (Restaurar).' }
 ---
+
 ## Example
 
 ```tsx
-<FilterPannel onApplyFilter={pagination.applyFilters}><TableFilterField label='Search'><TextInput controller={{ name: 'search' }} /></TableFilterField></FilterPannel>
+import FilterPannel from '@mantis-core/ui/components/Tables/FilterPannel';
+import TableFilterField from '@mantis-core/ui/components/table-filter-field';
+import { useFormContext } from 'react-hook-form';
+
+interface Filters {
+  search: string;
+}
+
+function SearchField() {
+  const { register } = useFormContext<Filters>();
+  return (
+    <TableFilterField label='Search' htmlFor='search'>
+      <input id='search' {...register('search')} />
+    </TableFilterField>
+  );
+}
+
+function Example() {
+  const onApplyFilter = async (data: Filters) => console.log(data);
+  return (
+    <FilterPannel<Filters> onApplyFilter={onApplyFilter}>
+      <SearchField />
+    </FilterPannel>
+  );
+}
 ```
 
 ## Notes
 
-- The component creates its own `FormProvider`.
-- Empty values are normalized to `null` before `onApplyFilter`.
+- Not re-exported from the package root — import the deep path.
+- Migrated to the PR11 `Drawer` (was PR10 `primereact/sidebar`, hence `baseLibrary: custom` — the sidebar itself is a Mantis wrapper, not a direct PrimeReact base) and the migrated `Button`.
+- Children must read the panel's own `useForm` instance via `useFormContext` (a `FormProvider` is created internally) — do not pass an outer `control`.
+- Empty (`""`/`null`/`undefined`) values are normalized to `null` before `onApplyFilter`; reset applies `{}`.