@mantis-core/ui 0.5.0 → 0.6.0

package/docs/contracts/dependency-map.md

@@ -6,34 +6,56 @@ Which base library each component wraps.
 
 ## PrimeReact wrappers
 
-- `ActionColumn`: `primereact/column`
-- `Button`: `primereact/button`
-- `ConfirmDialog`: `primereact/dialog`
-- `DateInput`: `primereact/calendar`
-- `DropDown`: `primereact/dropdown`
-- `FilterPannel`: `primereact/sidebar`
-- `IndexColumn`: `primereact/column`
-- `MenuButton`: `primereact/tieredmenu`
-- `MultiSelect`: `primereact/multiselect`
-- `MultiSelectFilter`: `primereact/multiselect`
-- `NumberInput`: `primereact/inputnumber`
-- `PaginatedTable`: `primereact/datatable`
-- `TextArea`: `primereact/inputtextarea`
-- `TextInput`: `primereact/inputtext`
-- `Toggle`: `primereact/checkbox`
-- `ToggleInlineButton`: `primereact/selectbutton`
+- `ActionColumn`: `@primereact/ui/menu`
+- `AutoCompleteField`: `@primereact/ui/autocomplete`
+- `Avatar`: `@primereact/ui/avatar`
+- `Button`: `@primereact/ui/button`
+- `CardSkeleton`: `@primereact/ui/skeleton`
+- `CheckboxField`: `@primereact/ui/checkbox`
+- `ColorPickerInput`: `@primereact/ui/inputcolor`
+- `DateField`: `@primereact/ui/datepicker`
+- `DatePresets`: `@primereact/ui/button`
+- `Drawer`: `@primereact/ui/drawer`
+- `FormWizard`: `@primereact/ui/stepper`
+- `IndexColumn`: `@primereact/ui/datatable`
+- `Loading`: `@primereact/ui/progressspinner`
+- `MantisDataTable`: `@primereact/ui/datatable`
+- `MaskField`: `@primereact/ui/inputtext`
+- `MenuButton`: `@primereact/ui/menu`
+- `Modal`: `@primereact/ui/dialog`
+- `MultiSelectFilter`: `@primereact/ui/select`
+- `NumberField`: `@primereact/ui/inputnumber`
+- `OtpInput`: `@primereact/ui/inputotp`
+- `PageTabs`: `@primereact/ui/tabs`
+- `PaginatedTable`: `@primereact/ui/datatable`
+- `PasswordInput`: `@primereact/ui/inputpassword`
+- `PhoneInput`: `@primereact/ui/inputtext`
+- `RadioGroup`: `@primereact/ui/radiobutton`
+- `RangeSlider`: `@primereact/ui/slider`
+- `RatingInput`: `@primereact/ui/rating`
+- `SearchInput`: `@primereact/ui/inputtext`
+- `SelectField`: `@primereact/ui/select`
+- `SwitchField`: `@primereact/ui/toggleswitch`
+- `TableSkeleton`: `@primereact/ui/skeleton`
+- `Tag`: `@primereact/ui/tag`
+- `TagsInput`: `@primereact/ui/inputtags`
+- `TextArea`: `@primereact/ui/textarea`
+- `TextField`: `@primereact/ui/inputtext`
+- `Timeline`: `@primereact/ui/timeline`
+- `ToggleInlineButton`: `@primereact/ui/togglebutton`
+- `UserMenu`: `@primereact/ui/menu`
 
 ## Non-PrimeReact wrappers
 
 - `AdminPageLayout`: `React context + custom shell`
-- `AsyncSelect`: `react-select/async`
-- `CKEditorInput`: `@ckeditor/ckeditor5-react`
+- `BarChart`: `chart.js`
+- `CKEditorInput`: `ckeditor`
+- `DonutChart`: `chart.js`
 - `ErrorMessage`: `@hookform/error-message`
-- `HiddenField`: `react-hook-form`
-- `MapPicker`: `next/dynamic`
-- `MapPickerClient`: `react-leaflet`
-- `Select`: `react-select`
-- `TimePicker`: `react-datepicker`
+- `LineChart`: `chart.js`
+- `MapPicker`: `leaflet`
+- `MapPickerClient`: `leaflet`
+- `MapPickerOSM`: `leaflet`
 
 ## Custom components
 
@@ -41,56 +63,32 @@ Which base library each component wraps.
 - `AdminPageHeader`
 - `AdminPageLayoutShell`
 - `AppShell`
-- `Avatar`
-- `BarChart`
 - `Breadcrumbs`
-- `CardSkeleton`
 - `ChangePasswordForm`
-- `ColorPickerInput`
-- `Combobox`
 - `CommandPalette`
-- `CurrencyInput`
+- `ConfirmDialog`
 - `DataState`
-- `DatePresets`
-- `DateRangeInput`
 - `DescriptionList`
 - `DirtyFormGuard`
-- `DonutChart`
-- `Drawer`
 - `EmptyState`
 - `ErrorBoundary`
+- `FieldShell`
 - `FileDropzone`
+- `FilterPannel`
 - `ForgotPasswordForm`
 - `FormActionsBar`
 - `FormFieldRender`
 - `FormSection`
-- `FormWizard`
-- `LineChart`
-- `Loading`
+- `HiddenField`
 - `LoginForm`
-- `MapPickerOSM`
-- `Modal`
-- `OtpInput`
-- `PageTabs`
 - `PageTitle`
 - `Pagination`
-- `PasswordInput`
-- `PhoneInput`
-- `RadioGroup`
-- `RangeSlider`
-- `RatingInput`
 - `RenderField`
 - `ResetPasswordForm`
 - `RichTextPreview`
-- `SearchInput`
 - `StatCard`
 - `StatusBadge`
-- `Switch`
 - `TableFilterField`
-- `TableSkeleton`
 - `TableToolbar`
-- `Tag`
-- `TagsInput`
-- `Timeline`
 - `UploadFilesPreview`
-- `UserMenu`
+- `useFieldController`

package/docs/contracts/field-controller.md

@@ -0,0 +1,138 @@
+# Field Controller
+
+Shared react-hook-form contract for every form wrapper in `@mantis-core/ui` (PR11). One hook —
+`useFieldController` — wires RHF's `useController` and the field's presentation shell so each
+wrapper only maps `field.value`/`field.onChange` into its own component's shape.
+
+Source: `packages/mantis-core-ui/src/components/Forms/useFieldController.ts` and `FieldShell.tsx`.
+
+## `FieldControllerProps`
+
+Form wrappers extend this directly as their own props — there is **no** `controller={{ ... }}`
+object prop. `TFieldValues`/`TName` are generic over the caller's form so `name` is
+autocompleted/validated against real fields, and `defaultValue`/`rules` are typed by path.
+
+```ts
+interface FieldControllerProps<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>> {
+  name: TName;
+  control?: Control<TFieldValues>;
+  rules?: Omit<RegisterOptions<TFieldValues, TName>, 'valueAsNumber' | 'valueAsDate' | 'setValueAs' | 'disabled'>;
+  defaultValue?: FieldPathValue<TFieldValues, TName>;
+  shouldUnregister?: boolean;
+  disabled?: boolean;       // OR-ed with the form's isSubmitting state
+  label?: string;
+  labelMode?: LabelMode;    // 'ifta' | 'float' | 'beside' | 'top' | 'none' — defaults to MantisThemeProvider (ifta)
+  floatVariant?: FloatVariant; // 'over' | 'in' | 'on' — only used when labelMode='float'
+  addonBefore?: ReactNode;
+  addonAfter?: ReactNode;
+  variant?: InputVariant;   // 'outlined' | 'filled' — defaults to MantisThemeProvider
+  size?: FieldSize;         // 'small' | 'large' — defaults to MantisThemeProvider
+  fluid?: boolean;          // full-width override for this field
+  required?: boolean;       // presentational only — validation is `rules`
+  helpText?: string;
+  id?: string;              // override the generated id used to wire input <-> label <-> aria
+}
+```
+
+Usage — no `controller` wrapper, props are flat:
+
+```tsx
+<TextField name='email' control={control} label='Email' rules={{ required: 'Required' }} />
+```
+
+### `ChoiceFieldControllerProps` (bucket B: toggles, groups, ranges)
+
+For non-text-box controls (checkboxes, radio groups, rating, range), text-box-only affordances are
+removed **at the type level** so passing them fails to compile, not just render wrong:
+
+```ts
+type ChoiceFieldControllerProps<TFieldValues, TName> = Omit<
+  FieldControllerProps<TFieldValues, TName>,
+  'labelMode' | 'floatVariant' | 'addonBefore' | 'addonAfter' | 'variant'
+> & {
+  labelMode?: 'beside' | 'top' | 'none'; // 'beside' default for toggles, 'top' for groups
+};
+```
+
+A `<CheckboxField labelMode='float'>` or an addon on a `<RatingInput>` does not compile — `ifta` /
+`float` / `InputGroup` / `variant` don't apply to these controls.
+
+## `FieldShell` anatomy
+
+`FieldShell` owns label + addon + help + error composition; every wrapper supplies only its input
+node as `children`.
+
+```ts
+interface FieldShellProps {
+  id: string;
+  label?: string;
+  required?: boolean;
+  helpText?: string;
+  errorMessage?: string;
+  labelMode?: LabelMode;
+  floatVariant?: FloatVariant;
+  addonBefore?: ReactNode;
+  addonAfter?: ReactNode;
+  children: ReactNode;
+}
+```
+
+- **Label modes** (`LabelMode = 'ifta' | 'float' | 'beside' | 'top' | 'none'`):
+  - `ifta` — wraps input + label in PR11 `IftaLabel`.
+  - `float` — wraps input + label in PR11 `FloatLabel` (position per `floatVariant`: `over` / `in` / `on`).
+  - `beside` — label renders next to the control (row layout).
+  - `top` — label renders above the control.
+  - `none` — no label rendered even if `label` text is provided elsewhere.
+- **Addons** — `addonBefore`/`addonAfter` wrap the (already labeled) control in PR11's
+  `InputGroup.Root`, addons outer, labeled control inner.
+- **Fluid** — resolved from the `useFieldConfig()` context (not a per-shell prop); when on, wraps
+  the composed control in PR11's `<Fluid>`.
+- **Help/error** — rendered below the control as `<small id="${id}-help">` /
+  `<small id="${id}-error">`. Both render independently — if `helpText` and `errorMessage` are both
+  truthy, both `<small>` elements show at once; there is no suppression. The only precedence is in
+  `aria-describedby`, which prefers the error (see Aria wiring below).
+- **Required marker** — a presentational ` *` appended to the label, `aria-hidden`.
+
+### Aria wiring
+
+`useFieldController` owns aria, not `FieldShell`: PR11's `invalid` prop drives styling only, it does
+**not** emit `aria-invalid`. The hook returns an `aria` object —
+`{ 'aria-invalid': fieldState.invalid || undefined, 'aria-describedby': errorId | helpId | undefined }`
+(error id wins over help id when both are present) — spread onto the actual input/trigger element.
+
+## `useFieldController` return shape
+
+```ts
+const f = useFieldController({ name, control, rules, defaultValue, shouldUnregister, disabled, helpText, id, variant, size, fluid });
+// f.field, f.fieldState, f.formState  — raw RHF controller result
+// f.id, f.errorId, f.helpId           — stable ids for FieldShell + aria
+// f.variant, f.size, f.fluid          — resolved (prop ?? MantisThemeProvider config)
+// f.invalid                           — fieldState.invalid
+// f.disabled                          — disabled || formState.isSubmitting
+// f.errorMessage                      — fieldState.error?.message
+// f.aria                              — { 'aria-invalid', 'aria-describedby' }
+```
+
+## How to build a new form wrapper
+
+Canonical pattern (from `TextField.tsx`):
+
+1. Accept `FieldControllerProps<TFieldValues, TName>` (or `ChoiceFieldControllerProps` for bucket B)
+   intersected with the underlying PR11 primitive's own extra props (Omit the primitive's
+   controlled/state props — `value`, `onChange`, `invalid`, `disabled`, etc. — since the hook owns
+   those).
+2. Destructure the controller/presentation props out of `props`; call `useFieldController` with
+   `name, control, rules, defaultValue, shouldUnregister, disabled, helpText, id, variant, size, fluid`.
+3. Render `<FieldShell id={f.id} label={label} labelMode={labelMode} floatVariant={floatVariant}
+   addonBefore={addonBefore} addonAfter={addonAfter} required={required} helpText={helpText}
+   errorMessage={f.errorMessage}>` around the actual PR11 input.
+4. Wire the PR11 primitive to `f.field` (`name`, `value`, `onChange`/`onValueChange`, `onBlur`,
+   `ref`) and `f.id` (`id`), plus `invalid={f.invalid}`, `disabled={f.disabled}`,
+   `variant={f.variant}`, `size={f.size}`, `fluid={f.fluid}`, and spread `{...f.aria}` onto the
+   element that owns focus (native input, or the trigger button for portal-based compounds like
+   `Select`).
+5. Spread any remaining `...rest` primitive props straight onto the PR11 element as an escape hatch.
+
+Portal-based compounds (e.g. `Select`) have no native blur — call `f.field.onBlur()` from the
+compound's `onOpenChange` (fired on close) instead, and put id/aria on the trigger element rather
+than a bare `<input>`.

package/docs/contracts/style-imports.md

@@ -7,46 +7,27 @@
 ## All partials
 
 ```scss
-@use "@mantis-core/styles/scss/buttons.scss";
 @use "@mantis-core/styles/scss/ckeditor.scss";
 @use "@mantis-core/styles/scss/confirm-dialog.scss";
 @use "@mantis-core/styles/scss/data-state.scss";
 @use "@mantis-core/styles/scss/file-dropzone.scss";
 @use "@mantis-core/styles/scss/form-actions.scss";
-@use "@mantis-core/styles/scss/inputs.scss";
 @use "@mantis-core/styles/scss/rich-text-preview.scss";
-@use "@mantis-core/styles/scss/select-button.scss";
-@use "@mantis-core/styles/scss/select.scss";
 @use "@mantis-core/styles/scss/status-badge.scss";
-@use "@mantis-core/styles/scss/switch.scss";
 @use "@mantis-core/styles/scss/table.scss";
 ```
 
 ## Per component
 
-- `AsyncSelect`: `scss/select.scss`
-- `Button`: `scss/buttons.scss`
 - `CKEditorInput`: `scss/ckeditor.scss`
 - `ConfirmDialog`: `scss/confirm-dialog.scss`
-- `CurrencyInput`: `scss/inputs.scss`
 - `DataState`: `scss/data-state.scss`
-- `DateInput`: `scss/inputs.scss`
-- `DateRangeInput`: `scss/inputs.scss`
-- `DropDown`: `scss/inputs.scss`
 - `FileDropzone`: `scss/file-dropzone.scss`
 - `FormActionsBar`: `scss/form-actions.scss`
-- `MultiSelect`: `scss/inputs.scss`
-- `NumberInput`: `scss/inputs.scss`
+- `MantisDataTable`: `scss/table.scss`
 - `PaginatedTable`: `scss/table.scss`
-- `PasswordInput`: `scss/inputs.scss`
 - `RichTextPreview`: `scss/rich-text-preview.scss`
-- `Select`: `scss/select.scss`
 - `StatusBadge`: `scss/status-badge.scss`
-- `Switch`: `scss/switch.scss`
-- `TextArea`: `scss/inputs.scss`
-- `TextInput`: `scss/inputs.scss`
-- `TimePicker`: `scss/inputs.scss`
-- `ToggleInlineButton`: `scss/select-button.scss`
 
 ## Notes
 

package/llms.txt

@@ -3,104 +3,102 @@
 # Each line: Name — whenToUse — import — doc
 
 ## forms
-- AsyncSelect — Searchable select that loads options asynchronously via loadOptions callback. — `@mantis-core/ui/components/Forms/AsyncSelect` — docs/components/async-select.md
-- CKEditorInput — Rich-text WYSIWYG editor (CKEditor 5) wired to react-hook-form; emits HTML string. — `@mantis-core/ui/components/Forms/CKEditorInput` — docs/components/ckeditor-input.md
-- ColorPickerInput — Color picker (PrimeReact ColorPicker, hex format) wired to react-hook-form. — `@mantis-core/ui/components/Forms/ColorPickerInput` — docs/components/color-picker-input.md
-- Combobox — Autocomplete text input (PrimeReact AutoComplete) wired to react-hook-form; pass suggestions via the suggestions prop. — `@mantis-core/ui/components/Forms/Combobox` — docs/components/combobox.md
-- CurrencyInput — Numeric input pre-configured for currency display (mode=currency). — `@mantis-core/ui/components/Forms/CurrencyInput` — docs/components/currency-input.md
-- DateInput — Single date picker (PrimeReact Calendar, locale=es, format=dd/mm/yy). — `@mantis-core/ui/components/Forms/DateInput` — docs/components/date-input.md
-- DatePresets — Row of preset buttons (Hoy, 7 días, 30 días, Este mes) that fire onChange with a [Date, Date] range; pair with DateRangeInput. — `@mantis-core/ui/components/Forms/DatePresets` — docs/components/date-presets.md
-- DateRangeInput — Date range picker that stores [startDate, endDate] array; selectionMode is locked to 'range'. — `@mantis-core/ui/components/Forms/DateRangeInput` — docs/components/date-range-input.md
-- DirtyFormGuard — Blocks navigation when a react-hook-form has unsaved changes; also available as useDirtyFormGuard hook. — `@mantis-core/ui/components/Forms/DirtyFormGuard` — docs/components/dirty-form-guard.md
-- DropDown — PrimeReact Dropdown (single select with filter) wired to react-hook-form; use when you need PrimeReact styling over react-select. — `@mantis-core/ui/components/Forms/DropDown` — docs/components/drop-down.md
-- ErrorMessage — Displays a validation error string; use standalone when not using FormFieldRender. — `@mantis-core/ui/components/Forms/ErrorMessage` — docs/components/error-message.md
-- FileDropzone — Drag-and-drop file input with validation (type, size, count); supports react-hook-form mode and plain controlled mode. — `@mantis-core/ui/components/Forms/FileDropzone` — docs/components/file-dropzone.md
+- AutoCompleteField — Async (or sync) autocomplete text field wired to react-hook-form via `loadOptions`, with optional free-text `creatable` mode. Absorbs the former AsyncSelect + Combobox. — `@mantis-core/ui/components/Forms/AutoCompleteField` — docs/components/auto-complete-field.md
+- CheckboxField — Single boolean checkbox wired to react-hook-form. — `@mantis-core/ui/components/Forms/CheckboxField` — docs/components/checkbox-field.md
+- CKEditorInput — Rich-text WYSIWYG editor (CKEditor 5) wired to react-hook-form; emits an HTML string. — `@mantis-core/ui/components/Forms/CKEditorInput` — docs/components/ckeditor-input.md
+- ColorPickerInput — RHF-bound color picker over PR11's compound InputColor (area + sliders + swatch + eyedropper + hex input); value is a hex string. — `@mantis-core/ui/components/Forms/ColorPickerInput` — docs/components/color-picker-input.md
+- DateField — Single date, date-range, or time-only picker wired to react-hook-form; one wrapper covers all three via `selectionMode`/`timeOnly`/`showTime`. — `@mantis-core/ui/components/Forms/DateField` — docs/components/date-field.md
+- DatePresets — 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"`. — `@mantis-core/ui/components/Forms/DatePresets` — docs/components/date-presets.md
+- DirtyFormGuard — 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. — `@mantis-core/ui/components/Forms/DirtyFormGuard` — docs/components/dirty-form-guard.md
+- ErrorMessage — Standalone validation-error text for one named react-hook-form field, read from form context; use when composing a custom layout instead of FormFieldRender. — `@mantis-core/ui/components/Forms/ErrorMessage` — docs/components/error-message.md
+- FieldShell — 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). — `@mantis-core/ui/components/Forms/FieldShell` — docs/components/field-shell.md
+- FileDropzone — Drag-and-drop file input with validation (type, size, count); supports a react-hook-form binding or plain controlled value/onChange. — `@mantis-core/ui/components/Forms/FileDropzone` — docs/components/file-dropzone.md
 - FormActionsBar — Sticky-capable action bar with primary/secondary buttons and optional left/right slots for form pages. — `@mantis-core/ui/components/Forms/FormActionsBar` — docs/components/form-actions-bar.md
-- FormFieldRender — Wrapper that renders a label, the input slot, and a validation error message; use to compose any form control. — `@mantis-core/ui/components/Forms/FormFieldRender` — docs/components/form-field-render.md
-- FormWizard — Multi-step form navigator with step indicator and per-step validation; must render inside a FormProvider, parent owns the <form onSubmit>. — `@mantis-core/ui/components/Forms/FormWizard` — docs/components/form-wizard.md
-- HiddenField — Registers a hidden value in react-hook-form without rendering any UI. — `@mantis-core/ui/components/Forms/HiddenField` — docs/components/hidden-field.md
-- MultiSelect — Multi-value select (PrimeReact) wired to react-hook-form. — `@mantis-core/ui/components/Forms/MultiSelect` — docs/components/multi-select.md
-- NumberInput — Numeric input (integer or decimal) wired to react-hook-form. — `@mantis-core/ui/components/Forms/NumberInput` — docs/components/number-input.md
-- OtpInput — One-time password input (PrimeReact InputOtp) wired to react-hook-form. — `@mantis-core/ui/components/Forms/OtpInput` — docs/components/otp-input.md
-- PasswordInput — Password field with show/hide toggle; Controller pattern, same API as TextInput. — `@mantis-core/ui/components/Forms/PasswordInput` — docs/components/password-input.md
-- PhoneInput — Masked phone number input; default mask (999) 999-9999. — `@mantis-core/ui/components/Forms/PhoneInput` — docs/components/phone-input.md
-- RadioGroup — Renders a set of radio buttons from an options array; value is the selected option's value. — `@mantis-core/ui/components/Forms/RadioGroup` — docs/components/radio-group.md
-- RangeSlider — Dual-handle range slider that stores a [min, max] tuple; backed by PrimeReact Slider. — `@mantis-core/ui/components/Forms/RangeSlider` — docs/components/range-slider.md
-- RatingInput — Star rating input (PrimeReact Rating) wired to react-hook-form; stores numeric value. — `@mantis-core/ui/components/Forms/RatingInput` — docs/components/rating-input.md
-- RenderField — Low-level escape hatch: connects any custom UI to react-hook-form via a render prop. — `@mantis-core/ui/components/Forms/RenderField` — docs/components/render-field.md
-- SearchInput — Debounced text input that calls onSearch instead of using react-hook-form; ideal for live table/list filtering. — `@mantis-core/ui/components/Forms/SearchInput` — docs/components/search-input.md
-- Select — Single-value searchable select (react-select); supports creatable mode. — `@mantis-core/ui/components/Forms/Select` — docs/components/select.md
-- Switch — Toggle/boolean switch wired to react-hook-form. — `@mantis-core/ui/components/Forms/Switch` — docs/components/switch.md
-- TagsInput — Chip/tags input (PrimeReact Chips) wired to react-hook-form; stores value as string[]. — `@mantis-core/ui/components/Forms/TagsInput` — docs/components/tags-input.md
+- FormFieldRender — 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. — `@mantis-core/ui/components/Forms/FormFieldRender` — docs/components/form-field-render.md
+- FormWizard — 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>. — `@mantis-core/ui/components/Forms/FormWizard` — docs/components/form-wizard.md
+- HiddenField — Registers a react-hook-form value with no visible UI. — `@mantis-core/ui/components/Forms/HiddenField` — docs/components/hidden-field.md
+- MaskField — Generic masked text input (digit/letter/alphanumeric tokens) wired to react-hook-form; value is the masked display string. — `@mantis-core/ui/components/Forms/MaskField` — docs/components/mask-field.md
+- NumberField — Numeric input (integer, decimal, or currency) wired to react-hook-form. — `@mantis-core/ui/components/Forms/NumberField` — docs/components/number-field.md
+- OtpInput — RHF-bound one-time-password input over PR11's compound InputOtp; renders `length` segmented boxes. — `@mantis-core/ui/components/Forms/OtpInput` — docs/components/otp-input.md
+- PasswordInput — RHF-bound password field over PR11 InputPassword with a native show/hide toggle and a lightweight strength meter. — `@mantis-core/ui/components/Forms/PasswordInput` — docs/components/password-input.md
+- PhoneInput — Phone-number preset of MaskField; defaults to a US-style (999) 999-9999 mask. — `@mantis-core/ui/components/Forms/PhoneInput` — docs/components/phone-input.md
+- RadioGroup — Single-choice radio group over PR11's RadioButtonGroup; value is the selected option's value. — `@mantis-core/ui/components/Forms/RadioGroup` — docs/components/radio-group.md
+- RangeSlider — RHF-bound slider over PR11's compound Slider; single-handle by default, dual-handle range when the field holds a [number, number] tuple. — `@mantis-core/ui/components/Forms/RangeSlider` — docs/components/range-slider.md
+- RatingInput — RHF-bound star rating over PR11's compound Rating; stores a numeric value. — `@mantis-core/ui/components/Forms/RatingInput` — docs/components/rating-input.md
+- RenderField — Low-level escape hatch wrapping react-hook-form's Controller via a render prop; use to wire any custom or third-party input without building a full FieldControllerProps wrapper. — `@mantis-core/ui/components/Forms/RenderField` — docs/components/render-field.md
+- SearchInput — RHF-bound search box over PR11 InputText with a search icon and a debounced onSearch callback; ideal for live table/list filtering. — `@mantis-core/ui/components/Forms/SearchInput` — docs/components/search-input.md
+- SelectField — Single- or multi-select dropdown wired to react-hook-form over PR11's portal-based Select; pass `multiple` for array-value mode. Absorbs the former Select/DropDown/MultiSelect. — `@mantis-core/ui/components/Forms/SelectField` — docs/components/select-field.md
+- SwitchField — Boolean on/off toggle wired to react-hook-form. — `@mantis-core/ui/components/Forms/SwitchField` — docs/components/switch-field.md
+- TagsInput — RHF-bound tag/chip input over PR11's compound InputTags; stores value as string[]. — `@mantis-core/ui/components/Forms/TagsInput` — docs/components/tags-input.md
 - TextArea — Multi-line text field wired to react-hook-form. — `@mantis-core/ui/components/Forms/TextArea` — docs/components/text-area.md
-- TextInput — Single-line text field wired to react-hook-form. — `@mantis-core/ui/components/Forms/TextInput` — docs/components/text-input.md
-- TimePicker — Time-only picker (15-min intervals) wired to react-hook-form; renders as a styled InputText trigger. — `@mantis-core/ui/components/Forms/TimePicker` — docs/components/time-picker.md
-- Toggle — Checkbox-based boolean toggle wired to react-hook-form with configurable on/off labels. — `@mantis-core/ui/components/Forms/Toggle` — docs/components/toggle.md
-- ToggleInlineButton — Segmented button group (single or multi-select) wired to react-hook-form via a controller prop. — `@mantis-core/ui/components/Forms/ToggleInlineButton` — docs/components/toggle-inline-button.md
-- UploadFilesPreview — Drag-and-drop upload zone with live preview grid, drag-to-reorder, and async upload queue; designed for image galleries. — `@mantis-core/ui/components/Forms/UploadFilesPreview` — docs/components/upload-files-preview.md
+- TextField — Single-line text field wired to react-hook-form. — `@mantis-core/ui/components/Forms/TextField` — docs/components/text-field.md
+- ToggleInlineButton — Segmented single- or multi-choice control over PR11's ToggleButtonGroup; pass `multiple` for array-value mode. — `@mantis-core/ui/components/Forms/ToggleInlineButton` — docs/components/toggle-inline-button.md
+- UploadFilesPreview — Drag-and-drop upload zone with live preview grid, drag-to-reorder, and async upload queue; designed for image galleries, not react-hook-form bound. — `@mantis-core/ui/components/Forms/UploadFilesPreview` — docs/components/upload-files-preview.md
+- useFieldController — Hook every RHF field wrapper calls internally to wire useController + a stable id/aria/disabled/error-message resolution; call it directly only when hand-building a new field wrapper (see field-controller.md). — `@mantis-core/ui/components/Forms/useFieldController` — docs/components/use-field-controller.md
 
 ## tables
-- ActionColumn — Factory function that returns a PrimeReact Column with a dropdown action menu; call as ActionColumn(itemsFn, props). — `@mantis-core/ui/components/Tables/ActionColumn` — docs/components/action-column.md
-- FilterPannel — Slide-in sidebar filter panel for tables; wraps children in FormProvider and calls onApplyFilter with cleaned form data. — `@mantis-core/ui/components/Tables/FilterPannel` — docs/components/filter-pannel.md
-- IndexColumn — Returns a PrimeReact Column that renders the row's 1-based visual index; call as IndexColumn(colProps). — `@mantis-core/ui/components/Tables/IndexColumn` — docs/components/index-column.md
-- MenuButton — Dropdown button with a list of actions; used inside table rows. — `@mantis-core/ui/components/Tables/MenuButton` — docs/components/menu-button.md
-- MultiSelectFilter — PrimeReact MultiSelect wired for use as a DataTable column filter template. — `@mantis-core/ui/components/Tables/filters/MultiSelectFilter` — docs/components/multi-select-filter.md
-- PaginatedTable — Generic server-side paginated DataTable with built-in index column, action column, and Mantis Core CSS. Wraps PrimeReact DataTable. — `@mantis-core/ui/components/Tables/PaginatedTable` — docs/components/paginated-table.md
-- TableFilterField — Wraps a form control inside FilterPannel with a label; provides consistent layout. — `@mantis-core/ui/components/table-filter-field` — docs/components/table-filter-field.md
-- TableToolbar — Header bar above a table showing title, record count, and action buttons slot. — `@mantis-core/ui/components/table-toolbar` — docs/components/table-toolbar.md
+- ActionColumn — Factory that returns a row-action `ColumnDef` for MantisDataTable/PaginatedTable's `columns` array; each row's `body` renders a `MenuButton` populated by `items(row)`. — `@mantis-core/ui/components/Tables/ActionColumn` — docs/components/action-column.md
+- FilterPannel — Slide-in filter sidebar for tables; wraps RHF-bound filter fields in their own `FormProvider` and calls `onApplyFilter` with the cleaned form data. — `@mantis-core/ui/components/Tables/FilterPannel` — docs/components/filter-pannel.md
+- IndexColumn — Factory that returns a 1-based row-number `ColumnDef` for MantisDataTable/PaginatedTable's `columns` array. — `@mantis-core/ui/components/Tables/IndexColumn` — docs/components/index-column.md
+- MantisDataTable — 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. — `@mantis-core/ui/components/Tables/MantisDataTable` — docs/components/mantis-data-table.md
+- MenuButton — Row-action overlay menu — a trigger button that opens a popup list of actions; used inside `actionColumn`/table row cells, or standalone. — `@mantis-core/ui/components/Tables/MenuButton` — docs/components/menu-button.md
+- MultiSelectFilter — Multi-value header filter over the themed PR11 `Select` (multiple mode) — drops into a `ColumnDef`'s `filterElement` escape hatch when a column needs array-valued filtering instead of the scalar `filters` map. — `@mantis-core/ui/components/Tables/filters/MultiSelectFilter` — docs/components/multi-select-filter.md
+- PaginatedTable — Thin preset over MantisDataTable with `paginator` on by default plus optional index/action columns — the default table shell for admin list pages. — `@mantis-core/ui/components/Tables/PaginatedTable` — docs/components/paginated-table.md
+- TableFilterField — Wraps a form control with a `<label>` inside a `FilterPannel`, providing consistent layout. — `@mantis-core/ui/components/table-filter-field` — docs/components/table-filter-field.md
+- TableToolbar — Header bar above a table showing title, record-count meta, and an action buttons slot. — `@mantis-core/ui/components/table-toolbar` — docs/components/table-toolbar.md
 
 ## pages
-- AdminPageConfigurator — Sets the page title, description, and breadcrumbs in the admin layout shell via context; wrap each page's content with this. — `@mantis-core/ui/components/pages/admin-layout/AdminPageConfigurator` — docs/components/admin-page-configurator.md
-- AdminPageHeader — Gradient page header with title, optional description, breadcrumbs, and right-side actions slot; rendered by AdminPageLayoutShell — avoid rendering directly inside feature views. — `@mantis-core/ui/components/pages/AdminPageHeader` — docs/components/admin-page-header.md
-- AdminPageLayoutShell — Root layout shell for admin pages; renders AdminPageHeader from context set by AdminPageConfigurator and provides the layout grid. — `@mantis-core/ui/components/pages/admin-layout/AdminPageLayoutShell` — docs/components/admin-page-layout-shell.md
+- AdminPageConfigurator — Sets the page title, description, breadcrumbs, and actions in the admin layout shell via context; wrap each page's content with this. — `@mantis-core/ui/components/pages/admin-layout/AdminPageConfigurator` — docs/components/admin-page-configurator.md
+- AdminPageHeader — Gradient page header with title, optional description, breadcrumbs, and a right-side actions slot; rendered by AdminPageLayoutShell — avoid rendering directly inside feature views. — `@mantis-core/ui/components/pages/AdminPageHeader` — docs/components/admin-page-header.md
+- AdminPageLayoutShell — Root layout shell for admin pages; renders AdminPageHeader from context set by AdminPageConfigurator and provides the page grid/max-width. — `@mantis-core/ui/components/pages/admin-layout/AdminPageLayoutShell` — docs/components/admin-page-layout-shell.md
 - AppShell — Full-page app shell with responsive sidebar nav, topbar, and mobile drawer; use as the root layout wrapper for authenticated pages. — `@mantis-core/ui/components/pages/app-shell/AppShell` — docs/components/app-shell.md
 - Breadcrumbs — Standalone breadcrumb nav; renders nothing when items is empty. — `@mantis-core/ui/components/pages/app-shell/Breadcrumbs` — docs/components/breadcrumbs.md
 - FormSection — Bordered card section with a header (title + description + icon) and a padded body; groups related form fields. — `@mantis-core/ui/components/pages/FormSection` — docs/components/form-section.md
 - PageTitle — Centered display-font heading for public-facing pages. — `@mantis-core/ui/components/pages/PageTitle` — docs/components/page-title.md
 
 ## maps
-- MapPicker — Interactive Leaflet map that lets the user click to select a lat/lng coordinate; SSR-safe via next/dynamic. — `@mantis-core/ui/components/Maps/MapPicker` — docs/components/map-picker.md
-- MapPickerClient — Client-only Leaflet map that lets the user click to pick a coordinate; controlled via initialLat/initialLng. — `@mantis-core/ui/components/Maps/MapPickerClient` — docs/components/map-picker-client.md
-- MapPickerOSM — Script-injected Leaflet map (no SSR bundle cost) with click/drag marker and a save-location button. — `@mantis-core/ui/components/Maps/MapPickerOSM` — docs/components/map-picker-osm.md
+- MapPicker — SSR-safe entry point for the Leaflet lat/lng picker; lazy-loads MapPickerClient via next/dynamic (ssr:false). — `@mantis-core/ui/components/Maps/MapPicker` — docs/components/map-picker.md
+- MapPickerClient — Client-only react-leaflet map (click-to-pick marker); the piece MapPicker lazy-loads. Use directly only if you already own the ssr:false boundary. — `@mantis-core/ui/components/Maps/MapPickerClient` — docs/components/map-picker-client.md
+- MapPickerOSM — Script-injected Leaflet map (no react-leaflet/SSR bundle cost) with a draggable marker and an explicit "save location" button. — `@mantis-core/ui/components/Maps/MapPickerOSM` — docs/components/map-picker-osm.md
 
 ## overlays
-- Drawer — Slide-in side panel (PrimeReact Sidebar wrapper); defaults to right position. — `@mantis-core/ui/components/overlays/Drawer` — docs/components/drawer.md
-- Modal — Dialog/modal (PrimeReact Dialog wrapper); dismissable mask and non-draggable by default. — `@mantis-core/ui/components/overlays/Modal` — docs/components/modal.md
+- Drawer — 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. — `@mantis-core/ui/components/overlays/Drawer` — docs/components/drawer.md
+- Modal — Controlled dialog/modal; composes PR11's headless Dialog compound (Root/Portal/Backdrop/Positioner/Popup/Header/Content/Footer) behind a simple `open`/`title`/`footer` API. — `@mantis-core/ui/components/overlays/Modal` — docs/components/modal.md
 
 ## navigation
-- CommandPalette — Keyboard-driven command search overlay (Ctrl+K); pair with useCommandPalette hook to wire the shortcut. — `@mantis-core/ui/components/navigation/CommandPalette` — docs/components/command-palette.md
-- PageTabs — Tab menu bar for page-level navigation; auto-detects active tab from Next.js pathname when tabs have href. — `@mantis-core/ui/components/navigation/PageTabs` — docs/components/page-tabs.md
+- CommandPalette — Keyboard-driven command search overlay (Ctrl/Cmd+K); pair with the `useCommandPalette` hook to wire the shortcut. — `@mantis-core/ui/components/navigation/CommandPalette` — docs/components/command-palette.md
+- PageTabs — Page-level navigation tab bar (no panels) over PR11's Tabs compound; each tab navigates via `href` (Next.js router) or runs a `command`. Active tab is derived from the current pathname. — `@mantis-core/ui/components/navigation/PageTabs` — docs/components/page-tabs.md
 
 ## data
 - DescriptionList — Grid-based label/value list for detail views; supports 1, 2, or 3 columns. — `@mantis-core/ui/components/data/DescriptionList` — docs/components/description-list.md
 - StatCard — KPI card showing a metric label, large value, optional icon, trend indicator, and footer. — `@mantis-core/ui/components/data/StatCard` — docs/components/stat-card.md
-- Timeline — Vertical event timeline backed by PrimeReact Timeline; items render title, description, date, and optional icon. — `@mantis-core/ui/components/data/Timeline` — docs/components/timeline.md
+- Timeline — Vertical event timeline backed by the PR11 Timeline compound; items render a title, description, date, and optional icon/color. — `@mantis-core/ui/components/data/Timeline` — docs/components/timeline.md
 
 ## feedback
-- Avatar — User avatar that auto-generates initials from a name when no image is supplied; wraps PrimeReact Avatar. — `@mantis-core/ui/components/feedback/Avatar` — docs/components/avatar.md
-- CardSkeleton — Animated skeleton for card grid layouts while data loads. — `@mantis-core/ui/components/feedback/CardSkeleton` — docs/components/card-skeleton.md
-- ConfirmDialog — Modal confirmation dialog with confirm/cancel buttons and severity-aware styling. — `@mantis-core/ui/components/ui/ConfirmDialog` — docs/components/confirm-dialog.md
-- DataState — Full-area empty/error/loading state placeholder for data-fetching views. — `@mantis-core/ui/components/ui/DataState` — docs/components/data-state.md
+- Avatar — User avatar that renders an image or auto-derived initials; composes the PR11 headless Avatar (Root/Image/Fallback). — `@mantis-core/ui/components/feedback/Avatar` — docs/components/avatar.md
+- CardSkeleton — Animated skeleton for card-grid layouts while data loads; composes the PR11 Skeleton primitive. — `@mantis-core/ui/components/feedback/CardSkeleton` — docs/components/card-skeleton.md
+- ConfirmDialog — Confirm/cancel dialog for destructive or non-trivial actions; composed from the migrated Modal + Button. — `@mantis-core/ui/components/ui/ConfirmDialog` — docs/components/confirm-dialog.md
+- DataState — Loading/empty/error/ready placeholder for data-fetching views; renders `children` unchanged when `status="ready"`, otherwise a titled state panel. — `@mantis-core/ui/components/ui/DataState` — docs/components/data-state.md
 - EmptyState — Centered empty-state placeholder with icon, title, optional description, and action button. — `@mantis-core/ui/components/feedback/EmptyState` — docs/components/empty-state.md
-- ErrorBoundary — React error boundary; renders fallback UI on uncaught errors; fallback can be a ReactNode or render function. — `@mantis-core/ui/components/feedback/ErrorBoundary` — docs/components/error-boundary.md
-- Loading — Full-screen loading overlay with animated spinner; renders children when loading=false. — `@mantis-core/ui/components/Loaders/Loading` — docs/components/loading.md
-- Pagination — Standalone pagination control; use when not relying on PaginatedTable's built-in paginator. — `@mantis-core/ui/components/ui/Pagination` — docs/components/pagination.md
-- RichTextPreview — Safely renders a CKEditor HTML string with correct CKEditor content styles. — `@mantis-core/ui/components/ui/RichTextPreview` — docs/components/rich-text-preview.md
-- StatusBadge — Colored pill badge to communicate a status or label with semantic tone. — `@mantis-core/ui/components/ui/StatusBadge` — docs/components/status-badge.md
-- TableSkeleton — Animated skeleton placeholder that mimics a table grid while data loads. — `@mantis-core/ui/components/feedback/TableSkeleton` — docs/components/table-skeleton.md
-- Tag — Styled label chip (PrimeReact Tag wrapper with Mantis Core CSS); use for status labels, categories, or counts. — `@mantis-core/ui/components/feedback/Tag` — docs/components/tag.md
+- ErrorBoundary — React class error boundary; renders fallback UI on uncaught render errors in its children. — `@mantis-core/ui/components/feedback/ErrorBoundary` — docs/components/error-boundary.md
+- Loading — Full-screen loading overlay with a themed spinner; renders children unchanged when not loading. — `@mantis-core/ui/components/Loaders/Loading` — docs/components/loading.md
+- Pagination — Standalone page-number control (custom Tailwind markup, not PrimeReact Paginator); use when not relying on PaginatedTable's built-in paginator. — `@mantis-core/ui/components/ui/Pagination` — docs/components/pagination.md
+- RichTextPreview — Safely renders a CKEditor HTML string (sanitized by default) with CKEditor content styles applied. — `@mantis-core/ui/components/ui/RichTextPreview` — docs/components/rich-text-preview.md
+- StatusBadge — Colored pill badge to communicate a status with semantic tone (e.g. a lead or property status). — `@mantis-core/ui/components/ui/StatusBadge` — docs/components/status-badge.md
+- TableSkeleton — Animated skeleton placeholder that mimics a table grid while data loads; composes the PR11 Skeleton primitive. — `@mantis-core/ui/components/feedback/TableSkeleton` — docs/components/table-skeleton.md
+- Tag — Styled label chip for status labels, categories, or counts; wraps the PR11 Tag primitive. — `@mantis-core/ui/components/feedback/Tag` — docs/components/tag.md
 
 ## auth
-- ChangePasswordForm — Current + new + confirm password form for authenticated users. — `@mantis-core/ui/components/auth/ChangePasswordForm` — docs/components/change-password-form.md
-- ForgotPasswordForm — Email-only form to trigger password reset; caller owns the reset logic. — `@mantis-core/ui/components/auth/ForgotPasswordForm` — docs/components/forgot-password-form.md
-- LoginForm — Self-contained login form with email/username + password fields; pass onSubmit to wire signIn/Supabase from the app layer. — `@mantis-core/ui/components/auth/LoginForm` — docs/components/login-form.md
-- ResetPasswordForm — New password + confirm form; caller owns token validation and API call. — `@mantis-core/ui/components/auth/ResetPasswordForm` — docs/components/reset-password-form.md
-- UserMenu — Topbar user avatar + dropdown with custom nav items and sign-out; no auth lib coupling. — `@mantis-core/ui/components/auth/UserMenu` — docs/components/user-menu.md
+- ChangePasswordForm — Current + new + confirm password form for an authenticated user changing their own password. — `@mantis-core/ui/components/auth/ChangePasswordForm` — docs/components/change-password-form.md
+- ForgotPasswordForm — Email-only form to trigger a password-reset email; caller owns the actual reset request. — `@mantis-core/ui/components/auth/ForgotPasswordForm` — docs/components/forgot-password-form.md
+- LoginForm — Self-contained login form (identifier + password) built on migrated TextField/PasswordInput/Button; pass onSubmit to wire signIn/Supabase from the app layer. — `@mantis-core/ui/components/auth/LoginForm` — docs/components/login-form.md
+- ResetPasswordForm — New password + confirm-password form for a reset-token flow; caller owns token validation and the API call. — `@mantis-core/ui/components/auth/ResetPasswordForm` — docs/components/reset-password-form.md
+- UserMenu — Topbar avatar-triggered dropdown (custom nav items + sign-out); no auth-lib coupling. — `@mantis-core/ui/components/auth/UserMenu` — docs/components/user-menu.md
 
 ## buttons
-- Button — Primary action button; wraps PrimeReact Button with Mantis Core variant tokens and optional Next.js href navigation. — `@mantis-core/ui/components/Buttons/Button` — docs/components/button.md
+- Button — Primary action button; wraps PR11's `@primereact/ui/button`, mapping the Mantis semantic `variant` to PR11 `severity` and restoring the `label`/`icon`/`loading` affordances PR11 dropped. Supports `href` for Next.js client navigation. — `@mantis-core/ui/components/Buttons/Button` — docs/components/button.md
 
 ## charts
-- BarChart — Categorical comparisons rendered as a bar chart. Same prop shape as LineChart. — `@mantis-core/ui/components/charts/BarChart` — docs/components/bar-chart.md
-- DonutChart — Part-to-whole breakdown rendered as a doughnut chart. — `@mantis-core/ui/components/charts/DonutChart` — docs/components/donut-chart.md
-- LineChart — Time-series or trend data rendered as a line chart. Zero-config defaults with full options override. — `@mantis-core/ui/components/charts/LineChart` — docs/components/line-chart.md
+- BarChart — Categorical comparisons rendered as a bar chart, zero-config over chart.js defaults. — `@mantis-core/ui/components/charts/BarChart` — docs/components/bar-chart.md
+- DonutChart — Part-to-whole breakdown rendered as a doughnut chart, zero-config over chart.js defaults. — `@mantis-core/ui/components/charts/DonutChart` — docs/components/donut-chart.md
+- LineChart — Time-series/trend data rendered as a line chart, zero-config over chart.js defaults. — `@mantis-core/ui/components/charts/LineChart` — docs/components/line-chart.md