@mantis-core/ui 0.4.0 → 0.6.0

package/docs/components/filter-pannel.md

@@ -1,23 +1,48 @@
-# FilterPannel
-
-- Export: `FilterPannel`
-- Import: `import { FilterPannel } from "@mantis-core/ui";`
-- Base library: `primereact/sidebar` + `react-hook-form`
-- Base typing: `PropsWithChildren<{ onApplyFilter: (data: T) => Promise<void> }>`
-- Required styles: none
+---
+name: FilterPannel
+category: tables
+import: '@mantis-core/ui/components/Tables/FilterPannel'
+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, description: 'Called with the cleaned form data on submit (Aplicar), or `{}` on reset (Restaurar).' }
+---
 
 ## Example
 
 ```tsx
-<FilterPannel<{ status: string | null; city: string | null }>
-  onApplyFilter={async (filters) => setFilters(filters)}
->
-  <DropDown controller={{ name: "status" }} options={statusOptions} />
-  <DropDown controller={{ name: "city" }} options={cityOptions} />
-</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 `{}`.

package/docs/components/forgot-password-form.md

@@ -0,0 +1,36 @@
+---
+name: ForgotPasswordForm
+category: auth
+import: '@mantis-core/ui/components/auth/ForgotPasswordForm'
+whenToUse: Email-only form to trigger a password-reset email; caller owns the actual reset request.
+baseLibrary: custom
+requiredStyles: []
+relatedComponents: [LoginForm, ResetPasswordForm]
+relatedNextCore: []
+props:
+  - { name: onSubmit, type: '(values: ForgotPasswordFormValues) => void | Promise<void>', required: true, description: 'Receives { email }; form manages isSubmitting via RHF.' }
+  - { name: title, type: string, required: false, default: '"Recuperar contraseña"' }
+  - { name: subtitle, type: string, required: false }
+  - { name: submitLabel, type: string, required: false, default: '"Enviar enlace"' }
+  - { name: backSlot, type: ReactNode, required: false, description: 'Rendered below the submit button (e.g. a "back to login" link).' }
+  - { name: className, type: string, required: false }
+---
+
+## Example
+
+```tsx
+import ForgotPasswordForm from '@mantis-core/ui/components/auth/ForgotPasswordForm';
+import type { ForgotPasswordFormValues } from '@mantis-core/ui/components/auth/ForgotPasswordForm';
+
+function Example() {
+  const handleSubmit = async ({ email }: ForgotPasswordFormValues) => {
+    await fetch('/api/auth/forgot-password', { method: 'POST', body: JSON.stringify({ email }) });
+  };
+
+  return <ForgotPasswordForm onSubmit={handleSubmit} />;
+}
+```
+
+## Notes
+
+- Single `TextField` (email, `emailRule()`), own `useForm<ForgotPasswordFormValues>({ mode: 'onChange' })`.

package/docs/components/form-actions-bar.md

@@ -1,22 +1,52 @@
-# FormActionsBar
-
-- Export: `FormActionsBar`
-- Import: `import { FormActionsBar } from "@mantis-core/ui";`
-- Base library: custom layout + `Button`
-- Base typing: explicit `FormActionsBarProps`
-- Required styles: `@mantis-core/styles/scss/form-actions.scss`
+---
+name: FormActionsBar
+category: forms
+import: '@mantis-core/ui/components/Forms/FormActionsBar'
+whenToUse: Sticky-capable action bar with primary/secondary buttons and optional left/right slots for form pages.
+baseLibrary: custom
+requiredStyles: [scss/form-actions.scss]
+relatedComponents: [FormWizard, DirtyFormGuard]
+relatedNextCore: []
+props:
+  - { name: className, type: string, required: false, description: 'Additional CSS class on the root element' }
+  - { name: align, type: '''start'' | ''end'' | ''between''', required: false, default: '''between''', description: 'Horizontal alignment of action groups' }
+  - { name: sticky, type: boolean, required: false, default: 'false', description: 'Fix bar to bottom of viewport' }
+  - { name: leftSlot, type: ReactNode, required: false, description: 'Content rendered on the left side' }
+  - { name: rightSlot, type: ReactNode, required: false, description: 'Content rendered before the action buttons on the right' }
+  - { name: primaryLabel, type: string, required: false, default: '''Guardar''', description: 'Label for the primary button' }
+  - { name: primaryVariant, type: ButtonVariant, required: false, default: '''primary''', description: 'Design-system variant for primary button' }
+  - { name: primaryType, type: '''button'' | ''submit'' | ''reset''', required: false, default: '''submit''', description: 'HTML type for primary button' }
+  - { name: primaryLoading, type: boolean, required: false, default: 'false', description: 'Show loading spinner on primary button' }
+  - { name: primaryDisabled, type: boolean, required: false, default: 'false', description: 'Disable primary button' }
+  - { name: onPrimaryClick, type: '() => void', required: false, description: 'Click handler for primary button' }
+  - { name: secondaryLabel, type: string, required: false, description: 'Label for the secondary button; omit to hide it' }
+  - { name: secondaryVariant, type: ButtonVariant, required: false, default: '''secondary''', description: 'Design-system variant for secondary button' }
+  - { name: secondaryType, type: '''button'' | ''submit'' | ''reset''', required: false, default: '''button''', description: 'HTML type for secondary button' }
+  - { name: secondaryOutlined, type: boolean, required: false, default: 'true', description: 'Render secondary button as outlined' }
+  - { name: secondaryDisabled, type: boolean, required: false, default: 'false', description: 'Disable secondary button' }
+  - { name: onSecondaryClick, type: '() => void', required: false, description: 'Click handler for secondary button' }
+---
 
 ## Example
 
 ```tsx
-<FormActionsBar
-  align="between"
-  sticky
-  leftSlot={<span>Unsaved changes</span>}
-  primaryLabel="Save"
-  primaryType="submit"
-  secondaryLabel="Cancel"
-  secondaryOutlined
-  onSecondaryClick={() => router.back()}
-/>
+import FormActionsBar from '@mantis-core/ui/components/Forms/FormActionsBar';
+
+function Example() {
+  return (
+    <FormActionsBar
+      primaryLabel='Save'
+      secondaryLabel='Cancel'
+      onPrimaryClick={() => {}}
+      onSecondaryClick={() => {}}
+    />
+  );
+}
 ```
+
+## Notes
+
+- `primaryType` defaults to `submit` — inside a `<form onSubmit={handleSubmit(onSubmit)}>` the
+  primary button submits without an explicit `onPrimaryClick`.
+- `secondaryDisabled` is OR-ed with `primaryLoading`, so the secondary action is blocked while the
+  primary one is in flight.

package/docs/components/form-field-render.md

@@ -1,20 +1,48 @@
-# FormFieldRender
-
-- Export: `FormFieldRender`
-- Extra exports: `FormFieldRenderProps`
-- Import: `import { FormFieldRender } from "@mantis-core/ui";`
-- Base library: custom label and error wrapper
-- Base typing: `{ name: string; label: string | ReactElement; labelProps?; containerClassName?; render: ({ name }) => ReactElement | ReactNode }`
-- Required styles: none
+---
+name: FormFieldRender
+category: forms
+import: '@mantis-core/ui/components/Forms/FormFieldRender'
+whenToUse: 'Composes a label, a render-prop input slot, and an inline ErrorMessage for one field; use to wrap a custom/non-Mantis input with the same label+error layout as the field wrappers.'
+baseLibrary: custom
+relatedComponents: ['ErrorMessage', 'RenderField']
+relatedNextCore: []
+props:
+  - { name: name, type: string, required: true, description: 'RHF field name; forwarded to `render` and to the inline ErrorMessage.' }
+  - { name: label, type: 'string | ReactElement', required: true }
+  - { name: labelProps, type: 'LabelHTMLAttributes<HTMLLabelElement>', required: false }
+  - { name: containerClassName, type: string, required: false }
+  - { name: render, type: '({ name }: { name: string }) => ReactElement | ReactNode', required: true, description: 'Renders the actual input; receives `name` to wire to your own Controller/register call.' }
+---
 
 ## Example
 
 ```tsx
-<FormFieldRender
-  name="email"
-  label="Email"
-  render={({ name }) => (
-    <TextInput controller={{ name, control: form.control }} block />
-  )}
-/>
+import FormFieldRender from '@mantis-core/ui/components/Forms/FormFieldRender';
+import { Controller, FormProvider, useForm, type FieldValues } from 'react-hook-form';
+
+function Example() {
+  const methods = useForm<FieldValues>({ defaultValues: { email: '' } });
+  return (
+    <FormProvider {...methods}>
+      <FormFieldRender
+        name='email'
+        label='Email'
+        render={({ name }) => (
+          <Controller
+            name={name}
+            control={methods.control}
+            render={({ field }) => <input {...field} id={name} />}
+          />
+        )}
+      />
+    </FormProvider>
+  );
+}
 ```
+
+## Notes
+
+- Pre-`FieldControllerProps` composition primitive: `render` gets only `{ name }`, not `control` —
+  wire the actual RHF binding yourself (e.g. with `Controller`, or `RenderField`).
+- Renders an `ErrorMessage` internally, which reads react-hook-form via context — this component
+  must be used inside a `<FormProvider>`.

package/docs/components/form-section.md

@@ -1,15 +1,31 @@
-# FormSection
-
-- Export: `FormSection`
-- Import: `import { FormSection } from "@mantis-core/ui";`
-- Base library: custom card section
-- Base typing: `{ title: string; description?: string; icon?: ReactNode; children: ReactNode; className?: string }`
-- Required styles: none
+---
+name: FormSection
+category: pages
+import: '@mantis-core/ui/components/pages/FormSection'
+whenToUse: Bordered card section with a header (title + description + icon) and a padded body; groups related form fields.
+baseLibrary: custom
+relatedNextCore: []
+props:
+  - { name: title, type: string, required: true }
+  - { name: description, type: string, required: false }
+  - { name: icon, type: ReactNode, required: false }
+  - { name: children, type: ReactNode, required: true }
+  - { name: className, type: string, required: false }
+---
 
 ## Example
 
 ```tsx
-<FormSection title="Publishing" description="Visibility and timing controls">
-  <Switch name="published" control={form.control} />
-</FormSection>
+import FormSection from '@mantis-core/ui/components/pages/FormSection';
+import { TextField } from '@mantis-core/ui/components/Forms/TextField';
+import { useForm } from 'react-hook-form';
+
+function Example() {
+  const { control } = useForm({ defaultValues: { email: '' } });
+  return (
+    <FormSection title='Contact Info' description='Public contact details'>
+      <TextField name='email' control={control} label='Email' />
+    </FormSection>
+  );
+}
 ```

package/docs/components/form-wizard.md

@@ -0,0 +1,47 @@
+---
+name: FormWizard
+category: forms
+import: '@mantis-core/ui/components/Forms/FormWizard'
+whenToUse: 'Multi-step form navigator with a PR11 Stepper step indicator and per-step field validation; must render inside a FormProvider, parent owns the <form onSubmit>.'
+baseLibrary: '@primereact/ui/stepper'
+requiredStyles: []
+relatedComponents: [FormActionsBar, DirtyFormGuard]
+relatedNextCore: []
+props:
+  - { name: steps, type: 'FormWizardStep[]', required: true, description: 'Each step: `{ label, fields?: string[], content: ReactNode }`. `fields` are validated (via `trigger`) before advancing.' }
+  - { name: onComplete, type: '() => void | Promise<void>', required: false, description: 'Escape hatch for wizard usage outside a <form> element; when set, the final step''s button uses type="button" instead of "submit".' }
+  - { name: submitLabel, type: string, required: false, default: '''Finalizar''' }
+  - { name: className, type: string, required: false }
+---
+
+## Example
+
+```tsx
+import FormWizard from '@mantis-core/ui/components/Forms/FormWizard';
+import { FormProvider, useForm } from 'react-hook-form';
+
+function Example() {
+  const form = useForm({ defaultValues: { name: '', email: '' } });
+  return (
+    <FormProvider {...form}>
+      <form onSubmit={form.handleSubmit(() => {})}>
+        <FormWizard
+          steps={[
+            { label: 'Data', fields: ['name', 'email'], content: <div>Step 1</div> },
+            { label: 'Confirm', content: <div>Step 2</div> },
+          ]}
+          submitLabel='Save'
+        />
+      </form>
+    </FormProvider>
+  );
+}
+```
+
+## Notes
+
+- `Stepper.Root` (PR11) is uncontrolled — its `value` only sets the initial step, so the indicator
+  is remounted via `key={active}` + `defaultValue={active}` to track the wizard's own step state.
+- Without `onComplete`, the final step's button is `type="submit"` — the surrounding
+  `<form onSubmit={handleSubmit(onSubmit)}>` fires with no extra wiring.
+- Steps with no `fields` skip validation entirely on "Siguiente"/next.

package/docs/components/hidden-field.md

@@ -1,19 +1,32 @@
-# HiddenField
-
-- Export: `HiddenField`
-- Extra exports: `HiddenFieldProps`
-- Import: `import { HiddenField } from "@mantis-core/ui";`
-- Base library: `react-hook-form`
-- Base typing: `ControllerProps & { hidden?: boolean }`
-- Form contract: [`ControllerProps`](../contracts/controller-props.md)
-- Required styles: none
+---
+name: HiddenField
+category: forms
+import: '@mantis-core/ui/components/Forms/HiddenField'
+whenToUse: Registers a react-hook-form value with no visible UI.
+baseLibrary: custom
+formContract: FieldControllerProps
+relatedComponents: ['TextField']
+relatedNextCore: []
+props: []
+---
 
 ## Example
 
 ```tsx
-<HiddenField
-  name="tenantId"
-  control={form.control}
-  defaultValue={tenantId}
-/>
+import { HiddenField } from '@mantis-core/ui/components/Forms/HiddenField';
+import { useForm } from 'react-hook-form';
+
+function Example() {
+  const { control } = useForm({ defaultValues: { id: '' } });
+  return <HiddenField name='id' control={control} />;
+}
 ```
+
+## Notes
+
+- Not the full `FieldControllerProps`: only the RHF-binding subset —
+  `name | control | rules | defaultValue | shouldUnregister | id` — since there is no visible
+  control, so `label`/`labelMode`/`addonBefore`/`variant`/`size`/`fluid`/`required`/`helpText`
+  don't apply. Passing them fails to compile, not just render wrong.
+- Renders a real `<input type="hidden">` (mirrors `field.value`) so the value participates in
+  native form serialization.

package/docs/components/index-column.md

@@ -1,13 +1,36 @@
-# IndexColumn
-
-- Export: `IndexColumn`
-- Import: `import { IndexColumn } from "@mantis-core/ui";`
-- Base library: `primereact/column`
-- Base typing: `(props?: ColumnProps) => JSX.Element`
-- Required styles: none beyond table context
+---
+name: IndexColumn
+category: tables
+import: '@mantis-core/ui/components/Tables/IndexColumn'
+whenToUse: 'Factory that returns a 1-based row-number `ColumnDef` for MantisDataTable/PaginatedTable''s `columns` array.'
+baseLibrary: '@primereact/ui/datatable'
+relatedComponents: [MantisDataTable, PaginatedTable]
+relatedNextCore: []
+props:
+  - { name: overrides, type: 'Partial<ColumnDef<T>>', required: false, description: 'Overrides merged onto the default index ColumnDef (field/header/width/body).' }
+---
 
 ## Example
 
 ```tsx
-<IndexColumn style={{ width: "4rem" }} />
+import { indexColumn } from '@mantis-core/ui/components/Tables/IndexColumn';
+import { MantisDataTable } from '@mantis-core/ui/components/Tables/MantisDataTable';
+import type { ColumnDef } from '@mantis-core/ui/components/Tables/columns';
+
+interface Property {
+  id: string;
+  name: string;
+}
+
+function Example() {
+  const rows: Property[] = [{ id: '1', name: 'Casa Ceibos' }];
+  const columns: ColumnDef<Property>[] = [indexColumn<Property>({ width: '3rem' }), { field: 'name', header: 'Name' }];
+  return <MantisDataTable rows={rows} columns={columns} />;
+}
 ```
+
+## Notes
+
+- Reshaped from the PR10 `<Column/>` JSX element to a `ColumnDef<T>` factory — the canonical table is descriptor-driven, not JSX-children-driven.
+- `field` on the returned descriptor is the non-data key `"__index__"` (required by `ColumnDef` but unused for the cell); the cell renders `index + 1` via the `body` render-prop.
+- `PaginatedTable`'s `showIndexColumn`/`indexColumnOptions` props call this factory for you — reach for those first before prepending `indexColumn` by hand.

package/docs/components/line-chart.md

@@ -0,0 +1,39 @@
+---
+name: LineChart
+category: charts
+import: '@mantis-core/ui/components/charts/LineChart'
+whenToUse: Time-series/trend data rendered as a line chart, zero-config over chart.js defaults.
+baseLibrary: chart.js
+requiredStyles: []
+relatedComponents: [BarChart, DonutChart]
+relatedNextCore: []
+props:
+  - { name: labels, type: 'string[]', required: true }
+  - { name: datasets, type: 'LineChartDataset[]', required: true, description: 'ChartDataset<''line''> minus ''data'', plus data: number[].' }
+  - { name: options, type: 'ChartOptions<''line''>', required: false, description: 'Deep-merged over defaultLineOptions (plugins/scales merge shallowly one level).' }
+  - { name: colors, type: 'string[]', required: false, default: 'DEFAULT_COLORS (8-color palette)', description: 'Applied per-dataset (cycled by index) to datasets that don''t specify their own borderColor/backgroundColor.' }
+  - { name: height, type: number, required: false, default: '300', description: 'Container height in px.' }
+  - { name: className, type: string, required: false }
+---
+
+## Example
+
+```tsx
+import LineChart from '@mantis-core/ui/components/charts/LineChart';
+
+function Example() {
+  return (
+    <LineChart
+      labels={['Jan', 'Feb', 'Mar']}
+      datasets={[{ label: 'Revenue', data: [100, 200, 150] }]}
+      height={250}
+    />
+  );
+}
+```
+
+## Notes
+
+- Not re-exported from the package root — import from the deep path above (`@mantis-core/ui/components/charts/LineChart`), not `@mantis-core/ui`.
+- Calls `registerCharts()` (module-level, from `./chart-setup`) on import — no separate chart.js registration needed.
+- Default `tension: 0.3` (curved line) and a 20%-opacity fill color per dataset unless overridden.

package/docs/components/loading.md

@@ -1,21 +1,32 @@
-# Loading
-
-- Export: `Loading`
-- Extra exports: `LoadingWrapperProps`
-- Import: `import { Loading } from "@mantis-core/ui";`
-- Base library: custom full-screen overlay
-- Base typing: `PropsWithChildren<{ loading?: boolean; texto?: string; className?: string }>`
-- Required styles: none
+---
+name: Loading
+category: feedback
+import: '@mantis-core/ui/components/Loaders/Loading'
+whenToUse: Full-screen loading overlay with a themed spinner; renders children unchanged when not loading.
+baseLibrary: '@primereact/ui/progressspinner'
+relatedNextCore: []
+props:
+  - { name: loading, type: boolean, required: false, default: 'false' }
+  - { name: texto, type: string, required: false, default: "'Cargando...'" }
+  - { name: className, type: string, required: false }
+  - { name: children, type: ReactNode, required: false }
+---
 
 ## Example
 
 ```tsx
-<Loading loading={isSubmitting} texto="Saving changes...">
-  <FormScreen />
-</Loading>
+import Loading from '@mantis-core/ui/components/Loaders/Loading';
+
+function Example() {
+  return (
+    <Loading loading={true} texto='Loading...'>
+      <div>Page content</div>
+    </Loading>
+  );
+}
 ```
 
 ## Notes
 
 - When `loading` is `false`, it returns `children` unchanged.
-- This is a page overlay, not an inline spinner primitive.
+- This is a fixed, full-viewport overlay (indeterminate PR11 `ProgressSpinner`), not an inline spinner primitive.

package/docs/components/login-form.md

@@ -0,0 +1,47 @@
+---
+name: LoginForm
+category: auth
+import: '@mantis-core/ui/components/auth/LoginForm'
+whenToUse: Self-contained login form (identifier + password) built on migrated TextField/PasswordInput/Button; pass onSubmit to wire signIn/Supabase from the app layer.
+baseLibrary: custom
+requiredStyles: []
+relatedComponents: [ForgotPasswordForm, ResetPasswordForm, ChangePasswordForm, UserMenu]
+relatedNextCore: []
+props:
+  - { name: onSubmit, type: '(values: LoginFormValues) => void | Promise<void>', required: true, description: 'Receives { identifier, password }; form manages isSubmitting via RHF.' }
+  - { name: brand, type: ReactNode, required: false, description: 'Rendered above the title.' }
+  - { name: title, type: string, required: false, default: '"Iniciar sesión"' }
+  - { name: subtitle, type: string, required: false }
+  - { name: footer, type: ReactNode, required: false, description: 'Rendered below the submit button (e.g. forgot-password link).' }
+  - { name: identifierField, type: '''email'' | ''username''', required: false, default: '"email"', description: 'Switches the identifier field''s validation, type, and autoComplete between email and plain username.' }
+  - { name: identifierLabel, type: string, required: false, description: 'Overrides the default label ("Correo electrónico" / "Usuario") derived from identifierField.' }
+  - { name: identifierPlaceholder, type: string, required: false }
+  - { name: passwordLabel, type: string, required: false, default: '"Contraseña"' }
+  - { name: passwordPlaceholder, type: string, required: false }
+  - { name: submitLabel, type: string, required: false, default: '"Ingresar"' }
+  - { name: className, type: string, required: false }
+---
+
+## Example
+
+```tsx
+import LoginForm from '@mantis-core/ui/components/auth/LoginForm';
+import type { LoginFormValues } from '@mantis-core/ui/components/auth/LoginForm';
+
+function Example() {
+  const handleSubmit = async (values: LoginFormValues) => {
+    await fetch('/api/auth/login', { method: 'POST', body: JSON.stringify(values) });
+  };
+
+  return <LoginForm onSubmit={handleSubmit} identifierField='email' />;
+}
+```
+
+## Notes
+
+- Owns its own `useForm<LoginFormValues>({ mode: 'onChange' })` — it is not a field wrapper, so
+  there is no `control`/`FieldControllerProps` to pass in from outside.
+- `identifierField='email'` applies `emailRule()` + `notEmptyRule()`; `'username'` applies only
+  `notEmptyRule()`. Both cases still submit the value under the `identifier` key.
+- Submit `Button` shows `loading`/`disabled` from `form.formState.isSubmitting` — no extra wiring
+  needed for a pending state.

package/docs/components/mantis-data-table.md

@@ -0,0 +1,61 @@
+---
+name: MantisDataTable
+category: tables
+import: '@mantis-core/ui/components/Tables/MantisDataTable'
+whenToUse: 'The 90% shortcut over PR11''s compound DataTable — one flat `columns: ColumnDef[]` array renders the whole TableContainer→Table→THead→TBody→EmptyTBody tree with striped rows + gridlines. Default table for any grid; drop to `PaginatedTable` for pagination + index/action columns baked in.'
+baseLibrary: '@primereact/ui/datatable'
+requiredStyles: [scss/table.scss]
+relatedComponents: [PaginatedTable, ActionColumn, IndexColumn, MenuButton, FilterPannel, MultiSelectFilter]
+relatedNextCore: []
+props:
+  - { name: rows, type: 'T[]', required: true, description: 'Row data (PR11''s `data`, renamed since PR11 root''s own `rows` means page size).' }
+  - { name: columns, type: 'ColumnDef<T>[]', required: true, description: 'Flat column descriptor array — see ColumnDef shape below.' }
+  - { name: rowsPerPage, type: number, required: false, description: 'Forwarded to PR11 Root''s `rows` (page size). Only relevant with `paginator`.' }
+  - { name: selectable, type: boolean, required: false, default: 'false', description: 'Prepends a checkbox selection column. Requires `selectionMode` on the passthrough root props.' }
+  - { name: emptyMessage, type: ReactNode, required: false, default: "'No records'" }
+  - { name: filters, type: 'Record<string, string>', required: false, description: 'Current per-field filter values (page-owned state, not RHF).' }
+  - { name: onFilterChange, type: '(field: string, value: string) => void', required: false, description: 'Fires when a header filter control (text/dropdown preset or custom filterElement) changes.' }
+---
+
+## Example
+
+```tsx
+import { MantisDataTable } from '@mantis-core/ui/components/Tables/MantisDataTable';
+import { currencyCell, badgeCell } from '@mantis-core/ui/components/Tables/cell-presets';
+import type { ColumnDef } from '@mantis-core/ui/components/Tables/columns';
+
+interface Property {
+  id: string;
+  name: string;
+  price: number;
+  status: string;
+}
+
+const COLUMNS: ColumnDef<Property>[] = [
+  { field: 'name', header: 'Name', sortable: true, filter: 'text' },
+  { field: 'price', header: 'Price', cell: currencyCell({ currency: 'USD' }) },
+  {
+    field: 'status',
+    header: 'Status',
+    cell: badgeCell({ styles: { active: 'bg-green-100 text-green-700' } }),
+    filter: 'dropdown',
+    filterOptions: [
+      { label: 'Active', value: 'active' },
+      { label: 'Draft', value: 'draft' },
+    ],
+  },
+];
+
+function Example() {
+  const rows: Property[] = [{ id: '1', name: 'Casa Ceibos', price: 125000, status: 'active' }];
+  return <MantisDataTable rows={rows} columns={COLUMNS} emptyMessage='No properties yet' />;
+}
+```
+
+## Notes
+
+- `ColumnDef<T>` fields: `field` (`keyof T & string`, also the sort/filter key), `header`, `sortable?`, `width?`; cell rendering via preset `cell?: CellRenderer` or escape hatch `body?: (item: T, index: number) => ReactNode` (escape hatch always wins); filtering via preset `filter?: 'text' | 'dropdown'` (+ `filterOptions?` for dropdown) or escape hatch `filterElement?: (ctx: { value, onChange }) => ReactNode` (escape hatch always wins).
+- Cell presets from `./cell-presets`: `currencyCell({ currency?, locale? })` (defaults USD/en-US, no decimals), `dateCell({ locale?, options? })` (short localized date), `badgeCell({ styles?, className? })` (maps a cell value to Tailwind tone classes).
+- Column factories `indexColumn()` and `actionColumn()` live in `IndexColumn`/`ActionColumn` and return a `ColumnDef<T>` to prepend/append — see their own docs, or reach for `PaginatedTable`'s `showIndexColumn`/`showActionColumn` shortcuts instead of wiring them by hand.
+- Any `DataTableRootProps` not owned by this wrapper (e.g. `paginator`, `selectionMode`, `lazy`, `sortField`, `onLazyLoad`, `dataKey`) passes straight through to PR11's `DataTable.Root`.
+- The `dropdown` filter preset renders the themed PR11 `Select` (page-owned scalar value, not RHF); pagination UI only renders when `paginator` is passed through and true.