@mantis-core/ui 0.5.0 → 0.6.0

package/docs/components/toggle-inline-button.md

@@ -2,20 +2,52 @@
 name: ToggleInlineButton
 category: forms
 import: '@mantis-core/ui/components/Forms/ToggleInlineButton'
-whenToUse: Segmented button group (single or multi-select) wired to react-hook-form via a controller prop.
-baseLibrary: primereact/selectbutton
-formContract: ControllerProps
-requiredStyles: [scss/select-button.scss]
-relatedComponents: [FormFieldRender]
+whenToUse: Segmented single- or multi-choice control over PR11's ToggleButtonGroup; pass `multiple` for array-value mode.
+baseLibrary: '@primereact/ui/togglebutton'
+formContract: ChoiceFieldControllerProps
+relatedComponents: ['RadioGroup', 'SelectField']
 relatedNextCore: []
 props:
-  - { name: controller, type: ControllerProps, required: true, description: 'react-hook-form controller config' }
-  - { name: options, type: 'any[]', required: true, description: 'Options array passed to SelectButton' }
-  - { name: variant, type: ButtonVariant, required: false, default: '''primary''', description: 'Design-system color variant' }
-  - { name: multiple, type: boolean, required: false, default: 'false', description: 'Allow selecting multiple options' }
+  - { name: options, type: 'Record<string, unknown>[]', required: true, description: 'Option rows rendered as segments.' }
+  - { name: optionLabel, type: string, required: false, default: '''label''', description: 'Key read for each option''s display label.' }
+  - { name: optionValue, type: string, required: false, default: '''value''', description: 'Key read for each option''s bound value.' }
+  - { name: multiple, type: boolean, required: false, default: 'false', description: 'Array-value mode; toggles per-segment selection instead of single scalar selection.' }
+  - { name: renderOption, type: '(option: Record<string, unknown>, index: number) => ReactNode', required: false, description: 'Escape hatch: full custom per-segment render.' }
 ---
+
 ## Example
 
 ```tsx
-{/* TODO: add example */}
+import { ToggleInlineButton } from '@mantis-core/ui/components/Forms/ToggleInlineButton';
+import { useForm } from 'react-hook-form';
+
+const VIEWS = [
+  { label: 'List', value: 'list' },
+  { label: 'Grid', value: 'grid' },
+];
+
+function Example() {
+  const { control } = useForm({ defaultValues: { view: 'list' } });
+  return (
+    <ToggleInlineButton
+      name='view'
+      control={control}
+      label='View'
+      options={VIEWS}
+      optionLabel='label'
+      optionValue='value'
+    />
+  );
+}
 ```
+
+## Notes
+
+- Value shape: scalar (or `null`) by default; an ARRAY when `multiple` — selecting a segment
+  appends its value, deselecting filters it out.
+- `labelMode` defaults to `'beside'` for this wrapper (not the global config default).
+- PR11 `11.0.0-rc.1` gotcha (same as `RadioGroup`): the styled `ToggleButtonGroup` and
+  `ToggleButton.Root` are wired through two different React contexts in this rc, so the group's
+  `value`/`onValueChange` never reaches its children (verified in-browser). Until fixed upstream,
+  this wrapper binds each `ToggleButton.Root` individually via its documented `pressed`/
+  `onPressedChange` props; `ToggleButtonGroup` itself is used for layout/styling only.

package/docs/components/upload-files-preview.md

@@ -2,7 +2,7 @@
 name: UploadFilesPreview
 category: forms
 import: '@mantis-core/ui/components/Forms/UploadFilesPreview'
-whenToUse: Drag-and-drop upload zone with live preview grid, drag-to-reorder, and async upload queue; designed for image galleries.
+whenToUse: 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.
 baseLibrary: custom
 relatedComponents: [FileDropzone]
 relatedNextCore: []
@@ -17,8 +17,29 @@ props:
   - { name: disabledMessage, type: string, required: false, description: 'Message shown in the drop zone when disabled' }
   - { name: copy, type: 'Partial<UploadFilesPreviewCopy>', required: false, description: 'Override any UI text strings' }
 ---
+
 ## Example
 
 ```tsx
-{/* TODO: add example */}
+import UploadFilesPreview from '@mantis-core/ui/components/Forms/UploadFilesPreview';
+
+function Example() {
+  return (
+    <UploadFilesPreview
+      previews={[{ id: '1', fullUrl: 'https://example.com/photo.jpg' }]}
+      onUploadFile={async (file) => ({ id: file.name, fullUrl: URL.createObjectURL(file) })}
+      onFileUploaded={() => {}}
+      onRemoveFile={() => {}}
+      onReorder={() => {}}
+    />
+  );
+}
 ```
+
+## Notes
+
+- Generic over `TItem extends { id: string; fullUrl: string }` — pass richer item shapes for
+  gallery-specific metadata.
+- Uploads run per-file via `Promise.allSettled`; a failed `onUploadFile` marks that item `error` in
+  the queue with a discard action, it does not throw or block the rest of the batch.
+- Not react-hook-form bound — the parent owns `previews` state and persistence via the callbacks.

package/docs/components/use-field-controller.md

@@ -0,0 +1,58 @@
+---
+name: useFieldController
+category: forms
+import: '@mantis-core/ui/components/Forms/useFieldController'
+whenToUse: '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).'
+baseLibrary: custom
+formContract: FieldControllerProps
+relatedComponents: ['FieldShell', 'TextField']
+relatedNextCore: []
+props: []
+---
+
+## Example
+
+```tsx
+import { FieldShell } from '@mantis-core/ui/components/Forms/FieldShell';
+import { useFieldController, type FieldControllerProps } from '@mantis-core/ui/components/Forms/useFieldController';
+import { useForm, type FieldValues, type FieldPath } from 'react-hook-form';
+
+function RatingField<TFieldValues extends FieldValues, TName extends FieldPath<TFieldValues>>(
+  props: FieldControllerProps<TFieldValues, TName>,
+) {
+  const f = useFieldController<TFieldValues, TName>(props);
+  return (
+    <FieldShell id={f.id} label={props.label} errorMessage={f.errorMessage}>
+      <input
+        id={f.id}
+        type='number'
+        value={(f.field.value as number) ?? 0}
+        onChange={(e) => f.field.onChange(Number(e.target.value))}
+        onBlur={f.field.onBlur}
+        disabled={f.disabled}
+        {...f.aria}
+      />
+    </FieldShell>
+  );
+}
+
+function Example() {
+  const { control } = useForm({ defaultValues: { rating: 0 } });
+  return <RatingField name='rating' control={control} label='Rating' />;
+}
+```
+
+## Notes
+
+- Takes `FieldControllerProps` verbatim (no extra params) — see
+  [`field-controller.md`](../contracts/field-controller.md) for the full prop list.
+- Returns `{ field, fieldState, formState, id, errorId, helpId, variant, size, fluid, invalid,
+  disabled, errorMessage, aria }`. `disabled` is `props.disabled || formState.isSubmitting`;
+  `aria` is `{ 'aria-invalid', 'aria-describedby' }` (error id wins over help id) — PR11's own
+  `invalid` prop only drives styling, so this hook is the one place aria-invalid gets emitted.
+- Portal-based compounds (e.g. `Select`) have no native blur — call `field.onBlur()` from the
+  compound's `onOpenChange` (fired on close) instead of relying on a bare blur event, and spread
+  `aria` onto the trigger element rather than a hidden input.
+- `TFieldValues` defaults to `FieldValues` (untyped): if a caller omits both `control` and an
+  explicit generic, `name` silently accepts any string — pass `control` (or an explicit generic) to
+  keep full path-typing.

package/docs/components/user-menu.md

@@ -2,18 +2,38 @@
 name: UserMenu
 category: auth
 import: '@mantis-core/ui/components/auth/UserMenu'
-whenToUse: Topbar user avatar + dropdown with custom nav items and sign-out; no auth lib coupling.
-baseLibrary: custom
+whenToUse: Topbar avatar-triggered dropdown (custom nav items + sign-out); no auth-lib coupling.
+baseLibrary: '@primereact/ui/menu'
+requiredStyles: []
+relatedComponents: [Avatar]
 relatedNextCore: []
 props:
-  - { name: user, type: UserMenuUser, required: true }
-  - { name: items, type: 'UserMenuItem[]', required: false }
-  - { name: onSignOut, type: '() => void', required: false }
+  - { name: user, type: UserMenuUser, required: true, description: '{ name?, email?, avatarUrl? } — displayName falls back to email.' }
+  - { name: items, type: 'UserMenuItem[]', required: false, description: '{ label, icon?, href?, onClick? }; href navigates via next/navigation, otherwise onClick fires.' }
+  - { name: onSignOut, type: '() => void', required: false, description: 'When set, appends a separator + sign-out item.' }
   - { name: signOutLabel, type: string, required: false, default: '"Cerrar sesión"' }
   - { name: className, type: string, required: false }
 ---
+
 ## Example
 
 ```tsx
-<UserMenu user={{ name: session.user.name, email: session.user.email }} onSignOut={() => signOut({ callbackUrl: '/login' })} />
+import UserMenu from '@mantis-core/ui/components/auth/UserMenu';
+
+function Example() {
+  return (
+    <UserMenu
+      user={{ name: 'Diego Condo', email: 'diego@example.com' }}
+      items={[{ label: 'Perfil', icon: 'pi pi-user', href: '/perfil' }]}
+      onSignOut={() => console.log('sign out')}
+    />
+  );
+}
 ```
+
+## Notes
+
+- Migrated to PR11's compound `Menu`: `Menu.Root` owns open state; `Menu.Trigger` renders `as="button"`
+  wrapping the migrated `Avatar`. No manual outside-click listener or inline dropdown (PR10 shape) left.
+- Each entry fires through `onSelect` — `href` items call `router.push` (next/navigation), `onClick`
+  items just run their handler. `icon` is a PrimeIcons class string (e.g. `pi pi-cog`), not a component.

package/docs/contracts/STORYBOOK_IMPLEMENTATION_AND_VOBO.md

@@ -0,0 +1,92 @@
+# Storybook Implementation & VoBo Rules — Mantis Core PR11 Forms stage
+
+This is the executable contract for finishing the PrimeReact 11 migration of the **reusable** surface
+(Forms family + `Button` + Toast) using Storybook as the isolated workbench and sign-off (VoBo) surface.
+A subagent implementing a component MUST follow **Rule Set 1**; a reviewer/supervisor signing off MUST
+apply **Rule Set 2**. Non-Forms components and `apps/demo-prime11` are FROZEN this stage (do not touch).
+
+Scope this stage: existing Forms wrappers (buckets A/B/C), `Button`, Toast migration, and the
+`useDataTableQuery` hook. **Deferred** (segregated but NOT built now): CheckboxGroup, Knob, Listbox,
+ToggleButtonGroup, ButtonGroup, SpeedDial.
+
+---
+
+## Forms segregation by compatibility (READ FIRST)
+
+`ifta`/`float` label modes and icon-fields (`InputGroup` addons) apply **only** to text-box inputs.
+Wrapping a checkbox/rating/otp in `FloatLabel`/`IftaLabel`/`InputGroup` breaks the render. Fields are
+segregated into buckets; the props contract is restricted per bucket so misuse fails at compile time.
+
+| Bucket | Components | labelMode | Icon addons | Props contract |
+| --- | --- | --- | --- | --- |
+| **A — text-box** | TextField, TextArea\*, NumberField, PasswordInput, SearchInput, MaskField, PhoneInput, SelectField, AutoCompleteField, DateField, TagsInput | `ifta` \| `float`(in/on/over) \| `beside` \| `none` | **Yes** (`addonBefore`/`addonAfter`) | `FieldControllerProps` (full) |
+| **B1 — toggle inline** | CheckboxField, SwitchField, ToggleInlineButton | `beside` \| `none` (default `beside`) | No | `ChoiceFieldControllerProps` |
+| **B2 — group/range** | RadioGroup, RangeSlider, RatingInput, OtpInput, ColorPickerInput | `top` \| `none` (default `top`) | No | `ChoiceFieldControllerProps` |
+| **C — special** | CKEditorInput, FileDropzone (+UploadFilesPreview) → `top`/`none`; HiddenField → no shell | per row | No | own |
+
+\* TextArea: label modes yes; icon addons limited/none (document it). PasswordInput/SearchInput/DateField
+have a built-in icon/trigger — document interaction with `addonAfter`.
+
+`ChoiceFieldControllerProps = Omit<FieldControllerProps, "labelMode"|"floatVariant"|"addonBefore"|"addonAfter"|"variant"> & { labelMode?: "beside"|"top"|"none" }`.
+
+---
+
+## Rule Set 1 — Implementation
+
+### 1a. General (every reusable component)
+
+1. **Clean PR11 API.** No legacy PR10 aliases; named imports from PR11 subpaths; use the primitive's compound/headless model.
+2. **Reusable wrapper contract.** Extend/compose the primitive props; **merge `className`/`style`** (never swallow); spread safe `...rest`; overrideable defaults; **typed variants**; `forwardRef` when focus/overlay/scroll/interop matters.
+3. **Token styling.** Base tokens / CSS vars only; **no hardcoded colors**; keep the `mantis-core-*` namespace; `cssLayer` order `theme, base, primereact`.
+4. **Layers.** `app → modules|components|lib`, `components → lib`. Forbidden: `components→modules`, `lib→modules`, `lib→app`.
+5. **Strict typing.** No `any`; `pnpm -s tsc --noEmit` clean.
+6. **Story required**, co-located, with the bucket's minimum set. No story ⇒ not done.
+7. **Fix = root cause.** A defect a story reveals is fixed at the shared point, not patched per caller.
+
+### 1b. Forms-specific (configurable fields + RHF)
+
+8. **Every field routes through the shared contract:** `useFieldController` (RHF binding + aria + id) → `FieldShell` (label/addon/help/error). Do not re-implement binding or label placement in the field.
+9. **Honor the axis per bucket:** A respects `labelMode`(ifta/float/beside/none), `floatVariant`, `variant`, `size`, `fluid` from `useFieldConfig` with per-prop override; B1/B2 use `ChoiceFieldControllerProps` (label `beside`/`top`/`none`, no float/ifta/addons/variant). Never hardcode an applicable axis.
+10. **Wire value/onChange/onBlur** correctly to the PR11 primitive; **one** `useController` per component.
+11. **Type coercion at the controller level** when the primitive emits a different shape than the form (NumberField, DateField, OtpInput…). Document the `field.value` shape.
+12. **Icon groups only in bucket A** via `addonBefore`/`addonAfter`. Pass the addon **wrapped in `InputGroup.Addon`** (from `@primereact/ui/inputgroup`), e.g. `addonBefore={<InputGroup.Addon>@</InputGroup.Addon>}` — raw content (a bare `<span>`) renders detached/unstyled. `FieldShell` owns `InputGroup.Root`; the consumer never wraps the whole field. B/C expose no addons.
+13. **Cross-field dependencies** use `useWatch` (never `watch()` in render).
+14. **`required` marker is presentational**; validation lives in `rules`.
+15. **Docs.** Update the component doc frontmatter / `catalog.json` (`pnpm gen:catalog`) with the `field.value` shape and supported config axes.
+
+### Parametrization (cross-cutting)
+
+Every component must be configurable **globally** (context provider: `MantisThemeProvider` → theme/colors/surfaces/dark + `FieldConfigProvider` → labelMode/floatVariant/variant/size/fluid) **or independently** (per-prop override). `Button` and Toast are parametrized by **theme tokens** (no hardcoded color). Everything is exercised from Storybook: global axes via toolbar `globalTypes`, overrides via per-story args.
+
+### Story taxonomy (CSF3) — per bucket
+
+Common to all: `Default`, `Playground` (args via `argTypes`), `Invalid` (with `errorMessage`), `Disabled`,
+`HelpText`, `WithReactHookForm` (form-decorator with `defaultValues` + submit that shows the captured value).
+Dark mode and size/variant are exercised via toolbar toggles, not separate stories.
+
+- **A (text-box)** — add: `LabelModes` (matrix ifta / float·in / float·on / float·over / beside / none), `Sizes`, `Variants` (outlined/filled), `Fluid`, `WithAddons`. `Async`/`Empty` where applicable (Select/AutoComplete).
+- **B1 (toggle inline)** — add: `LabelBeside`, `LabelNone`. NO float/ifta `LabelModes`, NO `WithAddons`.
+- **B2 (group/range)** — add: `LabelTop`, `LabelNone`, plus control-specific stories (RadioGroup `Options`/`renderOption`, Rating `stars`, Slider `range`). NO float/ifta, NO addons.
+- **C (special)** — a story fitting the component; no label/addon axes.
+- **Button** — `Variants`, `Sizes`, `Severities`, `Outlined`, `Text`, `Rounded`, `Loading`, `Disabled`.
+
+---
+
+## Rule Set 2 — Review & VoBo
+
+A component gets VoBo only when **ALL** hold:
+
+1. **Typing** — `pnpm -s tsc --noEmit` clean; no `any`; generics `<TFieldValues, TName>` correct.
+2. **Best practices / lint** — `pnpm lint` clean; meets the wrapper contract (merge `className`, `...rest`, `forwardRef`, defaults, typed variants); no hardcoded colors.
+3. **Scalability** — composes over the primitive (does not duplicate it); honors the config axis; no layer-breaking coupling.
+4. **Meets Rule Set 1** — item-by-item (incl. 1b for Forms).
+5. **Risk tests** — Vitest green: RHF (value shape, coercion), state, async, transformation.
+6. **Visual VoBo (most important)** — in the running Storybook, walk **every** story: it looks right; styles not bugged; **no overflow / no "arrows sticking out"**; alignment/spacing/focus/hover/dark/size correct; overlays/portals positioned; **zero console errors**. Check each `labelMode`/`floatVariant` and the icon groups specifically.
+7. **Supervisor VoBo** — final human sign-off, recorded per component in the ledger.
+
+**Support automation (cheap, advisory):** a11y addon (axe) 0 violations per story; render-smoke with no console
+errors. `@storybook/test-runner` (Playwright) and Chromatic are deferred — add only if manual visual review
+stops scaling.
+
+Record sign-off in `STORYBOOK_VOBO_LEDGER.md`. A component is not `done` until its row is complete and the
+supervisor has signed.

package/docs/contracts/STORYBOOK_VOBO_LEDGER.md

@@ -0,0 +1,195 @@
+# Storybook VoBo Ledger — PR11 Forms stage
+
+Sign-off tracker. A component is **done** only when every column is ✅ and the supervisor has signed.
+Legend: ✅ pass · ⬜ pending · ❌ failing/blocked · N/A not applicable.
+Columns map to `STORYBOOK_IMPLEMENTATION_AND_VOBO.md` Rule Set 2 (typing / lint / rules = Rule Set 1 / tests / visual / supervisor).
+
+## Batch S — Contract segregation
+
+| Item | typing | lint | rules | tests | visual | supervisor |
+| --- | :--: | :--: | :--: | :--: | :--: | :--: |
+| ChoiceFieldControllerProps | ✅ | ⬜ | ✅ | ✅ | N/A | ⬜ |
+| FieldShell `top` mode (hard-cap = type+default, not runtime) | ✅ | ⬜ | ✅ | ✅ | ⬜ (via B2 stories) | ⬜ |
+| field-typing.test-d (B1/B2 reject float/ifta labelMode) | ✅ | ⬜ | ✅ | ✅ | N/A | ⬜ |
+
+## Bucket A — text-box  ✅ supervisor VoBo 2026-07-05
+
+Story taxonomy + WithAddons (InputGroup.Addon) done; 4 render defects fixed root-cause vs official PR11 docs
+(NumberField addons `InputNumber.Root as={Fragment}`; PasswordInput expose size/variant; SearchInput `fluid`).
+lint column: repo-wide `react-hooks/refs` debt pre-exists on unchanged lines — no NEW lint introduced (†).
+
+| Component | typing | lint | rules | tests | visual | supervisor |
+| --- | :--: | :--: | :--: | :--: | :--: | :--: |
+| TextField | ✅ | †  | ✅ | ✅ | ✅ | ✅ |
+| TextArea | ✅ | †  | ✅ | N/A | ✅ | ✅ |
+| NumberField | ✅ | †  | ✅ | N/A | ✅ | ✅ |
+| PasswordInput | ✅ | †  | ✅ | ✅ | ✅ | ✅ |
+| SearchInput | ✅ | †  | ✅ | N/A | ✅ | ✅ |
+| MaskField | ✅ | †  | ✅ | ✅ | ✅ | ✅ |
+| PhoneInput | ✅ | †  | ✅ | ✅ | ✅ | ✅ |
+| SelectField | ✅ | †  | ✅ | N/A | ✅‡ | ✅ |
+| AutoCompleteField | ✅ | †  | ✅ | N/A | ✅‡ | ✅ |
+| DateField | ✅ | †  | ✅ | ✅ | ✅‡ | ✅ |
+| TagsInput | ✅ | †  | ✅ | ✅ | ✅‡ | ✅ |
+
+‡ Visual self-verified via Playwright + preview server (DOM measurement + screenshots) after fixing: placeholder overlap, multiselect filter/checkmark, creatable-in-portal, Today/Clear button bar, themed chips, **TagsInput nested focus ring** (the `.p-inputtags` container owns the field border/focus ring — the entry `InputText` was rendering a SECOND border+focus box-shadow/outline; made it chrome-less via inline `border/background/box-shadow/outline:0`, matching PR11's own `.p-inputtags .p-autocomplete-input` rule), and the **fluid axis** (see below). Awaiting final supervisor sign-off.
+
+**FLUID AXIS — root-caused + fixed (verified by DOM width measurement, fluid on↔off via the SB globals channel).**
+Root cause: in PrimeReact 11.0.0-rc.1 the `<Fluid>` **context does NOT propagate** to composed inputs inside `FieldShell`
+(`.p-fluid` wrapper renders full-width but the inner `.p-inputtext` stayed inline-block ~181px — no `p-inputtext-fluid`).
+So NO plain field was actually full-width under `config.fluid`; the earlier overlay `w-full` hacks only masked it on Select/Date/AutoComplete.
+Fix (PR11-idiomatic): every PR11 field primitive reads `props.fluid ?? context.$fluid` and applies its `p-<name>-fluid` width:100% class,
+so `useFieldController` now resolves `fluid = props.fluid ?? config.fluid` and each bucket-A field passes `fluid={f.fluid}` to its primitive.
+Verified widths in the 480px story frame (fluid ON → ~416, OFF → intrinsic): TextField 416↔181, TextArea 416↔166, NumberField 416↔181,
+SelectField 416↔62, AutoCompleteField 416↔181, DateField 416↔205 (root **and** inner input — the input sits in `IconField` where the
+`fluid` prop resolves to ~46px, so it keeps `w-full` to fill the fluid-driven root), MaskField/PhoneInput 416↔181.
+Intentionally **always full-width** (their root is a block-level container that fills the parent regardless of the prop — auto-mode would
+leave a mismatched input, and full is the sensible default): SearchInput (`IconField`), PasswordInput (`IconField` in toggle mode), TagsInput (`InputTags`).
+
+† Pre-existing repo lint debt (`react-hooks/refs` flags `{...f.aria}`/`f.disabled` spreads across ALL fields, on lines untouched by this work). Tracked as a separate cleanup, not a blocker for this stage.
+| SelectField | ⬜ | ⬜ | ⬜ | ⬜ | ⬜ | ⬜ |
+| AutoCompleteField | ⬜ | ⬜ | ⬜ | ⬜ | ⬜ | ⬜ |
+| DateField | ⬜ | ⬜ | ⬜ | ⬜ | ⬜ | ⬜ |
+| TagsInput | ⬜ | ⬜ | ⬜ | ⬜ | ⬜ | ⬜ |
+
+## Bucket B1 — toggle inline
+
+Stories done (Default/HelpText/Required/Disabled/LabelBeside/LabelNone; Toggle adds Multiple/WithRenderOption).
+Visual self-verified via Playwright DOM+interaction (screenshots were flaky): themed controls, label beside,
+click→checked/on/pressed all render (incl. ToggleButton rc-context workaround). No defects. lint = repo debt (†).
+
+| Component | typing | lint | rules | tests | visual | supervisor |
+| --- | :--: | :--: | :--: | :--: | :--: | :--: |
+| CheckboxField | ✅ | †  | ✅ | N/A | ✅‡ | ✅ |
+| SwitchField | ✅ | †  | ✅ | N/A | ✅‡ | ✅ |
+| ToggleInlineButton | ✅ | †  | ✅ | N/A | ✅‡ | ✅ |
+
+## Bucket B2 — group/range
+
+Stories done (Default/HelpText/Required/Disabled/LabelTop/LabelNone + control-specific). Visual self-verified via
+Playwright (label on top, themed controls). Fix: RangeSlider range mode rendered ONE handle → now two indexed
+handles (official Slider Range example). lint = repo debt (†). Awaiting final supervisor sign-off.
+
+| Component | typing | lint | rules | tests | visual | supervisor |
+| --- | :--: | :--: | :--: | :--: | :--: | :--: |
+| RadioGroup | ✅ | †  | ✅ | ✅ | ✅‡ | ✅ |
+| RangeSlider | ✅ | †  | ✅ | ✅ | ✅‡ (fixed range handles) | ✅ |
+| RatingInput | ✅ | †  | ✅ | ✅ | ✅‡ | ✅ |
+| OtpInput | ✅ | †  | ✅ | ✅ | ✅‡ | ✅ |
+| ColorPickerInput | ✅ | †  | ✅ | N/A | ✅‡ | ✅ |
+
+## Bucket C — special
+
+Stories written; typecheck + build green. Playwright pass: CKEditor + HiddenField OK; FileDropzone/UploadFilesPreview
+have an open rendering issue (see notes). Batch-0 baseline improved: wired `@mantis-core/styles` SCSS (via sass) into
+`.storybook/preview.tsx`, and CKEditorInput now self-imports `ckeditor5/ckeditor5.css`.
+
+| Component | typing | lint | rules | tests | visual | supervisor |
+| --- | :--: | :--: | :--: | :--: | :--: | :--: |
+| CKEditorInput | ✅ | †  | ✅ | ✅ | ✅‡ (self-imports ckeditor CSS + respects tokens) | ✅ |
+| FileDropzone | ✅ | †  | ✅ | N/A | ✅‡ (respects tokens — dashed border/surface/icon) | ✅ |
+| UploadFilesPreview | ✅ | †  | ✅ | N/A | ✅‡ (respects tokens — dropzone + cover-badge tiles) | ✅ |
+| HiddenField | ✅ | †  | ✅ | N/A | N/A (invisible, wiring verified) | ✅‡ |
+
+RESOLVED — theme unification + dark mode for the 3 Mantis-token consumers (CKEditor / FileDropzone / UploadFilesPreview):
+these are the ONLY Forms components that paint from the Mantis `--*` token layer (via `@mantis-core/styles` SCSS); every
+other field renders through PrimeReact primitives (`--p-*`) and already followed the toolbar + dark. Two defects, both fixed:
+
+1. **Tokens were static** — `tokens.template.scss` is a fixed brand palette (green, no working dark: its `.dark` block
+   keyed off `.dark` while the app toggles `.p-dark`). So the 3 never followed the toolbar primary/surface/dark. Fix:
+   `MantisStorybookProvider` now derives the Mantis tokens (`--background/--foreground/--card/--primary/--accent/--muted/
+   --border/--input/--ring`) from the SAME `primary`/`surface`/`dark` globals that drive the PR11 preset, set inline on
+   `<html>` per active light/dark. `--accent` tracks the primary hue (one step off) so idle/hover two-tone survives.
+
+2. **SCSS anchored fills to literal `white`** — `color-mix(var(--primary), white 96%)` forced near-white surfaces
+   regardless of theme (dark impossible). Fix: `white` → `var(--card)` in `file-dropzone.scss`, `ckeditor.scss`
+   (blockquote), and `UploadFilesPreview.tsx` inline styles — zero light change (`--card`=white in light), correct in dark.
+   Plus a `--ck-*` chrome bridge in `ckeditor.scss` so the CKEditor toolbar/buttons/dropdowns follow the theme (else dark
+   icons on dark surface). Verified via Playwright in light+emerald and dark+{rose,ocean}; `build-storybook` exit 0.
+
+## Form utilities
+
+| Component | typing | lint | rules | tests | visual | supervisor |
+| --- | :--: | :--: | :--: | :--: | :--: | :--: |
+Baseline fix this batch: `next/navigation` `useRouter()` crashed all Button-based components in react-vite Storybook
+("invariant expected app router to be mounted") → aliased to a no-op stub (`.storybook/next-navigation-mock.ts` +
+`main.ts` resolve.alias). Self-verified via Playwright.
+
+| FormActionsBar | ✅ | †  | ✅ | N/A | ✅‡ (renders after useRouter stub; primary "Guardar" faintness RESOLVED — was missing token layer, `--primary` now resolves) | ⬜ |
+| FormWizard | ✅ | †  | ✅ | N/A | ✅‡ (stepper + fields + submit render) | ⬜ |
+| DirtyFormGuard | ✅ | †  | ✅ | ⚠️ needs `useDirtyFormGuard.test.ts` (missing; logic-only) | N/A (invisible) | ⬜ |
+| ErrorMessage | ✅ | †  | ✅ | ⚠️ small render test recommended | ✅‡ (shows on Submit) | ⬜ |
+| RenderField / FormFieldRender | ✅ | †  | ✅ | N/A | ✅‡ (renders fields from descriptor) | ⬜ |
+
+## Buttons
+
+Stories authored (co-located `Button.stories.tsx`, title `Buttons/Button`): Default, Variants (8), Outlined, Text,
+Sizes, Rounded, WithIcon, IconOnly, Loading, Disabled, Block, Playground. Visual self-verified via Playwright (light+emerald,
+dark+ocean).
+
+**MIGRATED to PR11's native design system (removed the deprecated PR10 SCSS layer)** — supervisor decisions: use PR11
+severity colors from the preset (delete `buttons.scss`), and drop the unused `accent`/`premium` variants.
+- `packages/mantis-core-styles/scss/buttons.scss` **DELETED** (+ its `@use` in `index.scss`). It was the PR10-style layer:
+  per-variant `.p-button-<variant>` mixins coloring buttons from Mantis `--*` tokens, plus dead `.p-button-premium`/`accent`.
+- `Button.tsx`: `ButtonVariant` drops `accent` (8 variants); `variant`→PR11 `severity` only (no more `p-button-<variant>` class).
+  ALL button colors now come from the PR11 preset. Consequences (intended): `secondary` is now PR11 neutral (was amber),
+  `gray`→`contrast` (near-black light / near-white dark), success/warn/danger/info use the Aura severity palettes. `primary`
+  follows the toolbar primary ramp. `accent`/`premium` unused repo-wide, so removing them is caller-safe (verified by grep).
+- `Button.test.tsx` updated: assert only the PR11 severity class (`p-button-warn`/`p-button-danger`), not the removed wrapper class. 5/5 pass.
+- **PrimeIcons font**: Button's `icon` string prop (`pi pi-*`) + loading spinner (`pi pi-spin`) need `primeicons/primeicons.css`,
+  imported nowhere → added to `.storybook/preview.tsx` + `primeicons` devDep. (Forms use `@primeicons/react` SVG, so it only surfaced here.)
+The earlier "primary Guardar faint" (FormActionsBar) is RESOLVED — was the missing token layer; `--primary` now resolves.
+
+**Global severity colors — now controllable via the PR11 preset (not SCSS).** PR11 severity components read from the
+primitive palettes (`success`→`{green}`, `warn`→`{orange}`, `danger`→`{red}`, `info`→`{sky}`; `secondary`/`contrast`→`{surface}`,
+already toolbar-driven). `buildPreset(preset, primary, surface, severities?)` now takes optional per-severity ramps and injects
+`primitive: { green, orange, red, sky }` — recoloring ALL severity components globally (buttons/tags/badges/messages), not just
+buttons. Wired into `MantisThemeConfig.severities` (real `MantisThemeProvider`) + 4 Storybook toolbar dropdowns (Success/Warn/
+Danger/Info), reusing the `PRIMARY_RAMPS` pool. Default (unset) = Aura defaults, byte-identical (no `primitive` block emitted).
+Verified via Playwright: default success=green#22c55e/danger=red#ef4444/warn=orange#f97316/info=sky#0ea5e9; overriding sevSuccess→rose
+recolors the success button to rose (and any severity component) live. next-core + ui typecheck, theme tests 13/13, build green.
+
+| Component | typing | lint | rules | tests | visual | supervisor |
+| --- | :--: | :--: | :--: | :--: | :--: | :--: |
+| Button | ✅ | †  | ✅ | ✅ (Button.test.tsx 5/5) | ✅‡ (8 variants PR11-native severities, light+dark, follow toolbar primary; icons+spinner render) | ⬜ |
+
+## Toast (PR11 migration)
+
+Migrated `@mantis-core/next-core/toasts` off `react-hot-toast` to PR11's NATIVE toaster (Zag-based singleton `toast` from
+`@primereact/ui/toaster` + `Toast`/`Toaster` compound). `useMantisToasts` API PRESERVED (add{Success,Error,Info,Warning,Loading}Toast,
+promiseToast, jsxToast, dismiss, remove) — now built on `toast.{success,info,warn,error}`/`.promise`/`.dismiss`. Deleted
+`mantis-toast-theme.ts`(+ test) — styling is now native (severity colors from the preset, follow the toolbar). New `MantisToaster`
+host (promoted from the demo's app-toaster pattern) mounted by `MantisCoreBaseProvider` (replaces the react-hot-toast `<Toaster>`;
+`toasterProps` removed). `react-hot-toast` dep removed; `@primereact/ui` added to next-core peers. API deltas (intended): `opts` type
+is now `MantisToastOptions` (Pick of ToastType) not react-hot-toast's; `addLoadingToast` uses `loading:true` + duration Infinity;
+`remove`≡`dismiss`; `jsxToast` callback no longer gets a live toast handle (use the returned id + `dismiss`). CRUD hooks unaffected
+(they mock `../toasts`; crud-hooks.test 6/6). Story `Feedback/Toast` (mounts MantisToaster + buttons per severity + promise + dismiss-all).
+Visual self-verified via playwright-cli: toasts fire, animate in to opacity 1, render severity-themed (success green "Guardado correctamente",
+etc.), auto-dismiss ~5s, loading persists; Zag collapses the stack by default (front shown, hover-expands) — native PR11 behavior.
+typecheck (next-core + ui), build-storybook exit 0.
+
+| Item | typing | lint | rules | tests | visual | supervisor |
+| --- | :--: | :--: | :--: | :--: | :--: | :--: |
+| useMantisToasts (PR11, API preserved) | ✅ | †  | ✅ | ✅ (crud-hooks 6/6, mocked) | ✅‡ (fires + severity-themed + auto-dismiss + loading persists) | ⬜ |
+| MantisToaster host | ✅ | †  | ✅ | N/A | ✅‡ (renders toasts top-right, Zag stack) | ⬜ |
+
+## Hook
+
+Headless `useDataTableQuery` in `@mantis-core/nuqs` (`src/use-data-table-query.ts`): pagination + sorting + filtering in one
+state object, with OPT-IN URL sync via nuqs. Two backends selected by the (construction-time constant) `urlSync`: `useState`
+(headless, no routing) or nuqs `useQueryStates` (deep-link + back/forward) — identical `DataTableQuery<F>` return in both.
+Filter kinds map to parsers: text→`parseAsString`, enum→`createParseAsEnumArray`, stringArray→`parseAsStringArray`, json→`parseAsSuperJson`.
+`setPageSize`/`setFilter`/`setFilters`/`clearFilter`/`resetFilters` reset page to 0; `toggleSort` cycles asc→desc→cleared; `multiSort`
+keeps an array; `queryParams` is the backend-ready `{page,pageSize,sort,filters}`. Root-cause fix along the way: `parseAsSuperJson`
+had an unannotated `createParser` generic that inferred to `null`, making `.withDefault()` uncallable for every caller → annotated
+`createParser<unknown>`. Story `Hooks/useDataTableQuery` — a rich, themed "Directorio de cuentas" admin demo built from the **Mantis
+Forms wrappers** (TextField/SelectField×2 multiple/TagsInput/RangeSlider/DateField/SwitchField in a RHF form bridged one-way to the
+hook via useWatch→setFilters, with a useRef dedupe so unrelated re-renders don't reset page) + a themed sortable table (Tag status
+badges) + Prev/Next + rows-per-page, wired to **REAL nuqs URL sync** via `NuqsAdapter` (`nuqs/adapters/react`, `keyPrefix:"dt"`) and a
+live "URL / queryParams" panel. Verified via playwright-cli in light+emerald AND dark+ocean: typing search → `?dtq=…` + table narrows;
+paginate → `dtpage` (1-based via parseAsIndex) persists (no bridge-reset); sort → `dtsort={json…}`; switch → `dtactiveOnly={json:true}`
++ page resets; Limpiar → URL clean. All complex state (arrays/dates/ranges/booleans/sort) round-trips through the URL.
+
+| Item | typing | lint | rules | tests | visual | supervisor |
+| --- | :--: | :--: | :--: | :--: | :--: | :--: |
+| useDataTableQuery | ✅ | †  | ✅ | ✅ (17/17: local + URL round-trip per filter kind) | ✅‡ (live: paginate 01-05→06-10, search resets page, enum filter, reset — all correct) | ⬜ |

package/docs/contracts/component-doc-schema.md

@@ -12,25 +12,30 @@ edit them by hand. To document a component, edit its `.md` here and re-run the g
 
 ```md
 ---
-name: TextInput
+name: TextField
 category: forms
-import: '@mantis-core/ui/components/Forms/TextInput'
+import: '@mantis-core/ui/components/Forms/TextField'
 whenToUse: Single-line text field wired to react-hook-form.
-baseLibrary: primereact/inputtext
-formContract: ControllerProps
+baseLibrary: '@primereact/ui/inputtext'
+formContract: FieldControllerProps
 requiredStyles: ['scss/inputs.scss']
-relatedComponents: ['FormFieldRender', 'TextArea']
+relatedComponents: ['SelectField', 'FieldShell']
 relatedNextCore: []
 props:
-  - { name: controller, type: ControllerProps, required: true }
-  - { name: block, type: boolean, required: false, default: false }
-  - { name: defaultValue, type: string, required: false, default: "''" }
+  - { name: placeholder, type: string, required: false, description: 'Native <input> passthrough beyond FieldControllerProps.' }
+  - { name: maxLength, type: number, required: false, description: 'Native <input> passthrough beyond FieldControllerProps.' }
 ---
 
 ## Example
 
 ```tsx
-<TextInput controller={{ name: 'title' }} block />
+import { TextField } from '@mantis-core/ui/components/Forms/TextField';
+import { useForm } from 'react-hook-form';
+
+function Example() {
+  const { control } = useForm({ defaultValues: { title: '' } });
+  return <TextField name='title' control={control} label='Title' />;
+}
 ```
 
 ## Notes
@@ -46,21 +51,58 @@ props:
 | `category` | string | ✅ | One of: `forms`, `tables`, `pages`, `maps`, `overlays`, `navigation`, `data`, `feedback`, `auth`, `buttons`, `charts`. Groups `catalog.json`. |
 | `import` | string | ✅¹ | **Deep path**, verbatim into `catalog.json.import`. Form `@mantis-core/ui/components/<Area>/<Name>`. Exceptions exist (`.../components/table-toolbar`, `.../components/table-filter-field`) — store the real path, do not derive it. ¹Omit **only** for overview/guide docs (e.g. `admin-page-layout.md`): an `import`-less file ships but is excluded from `catalog.json` and `llms.txt`. |
 | `whenToUse` | string | ✅ | One line. Drives `catalog.json.whenToUse` + the `llms.txt` index. |
-| `baseLibrary` | string | ➖ | Underlying lib (`primereact/inputtext`, `react-select`, `custom`). Drives `dependency-map.md`. Use `custom` for components with no third-party base. |
-| `formContract` | string | ➖ | Shared contract the component follows, e.g. `ControllerProps`. Omit if none. |
+| `baseLibrary` | string | ➖ | Underlying lib. One of: `@primereact/ui/<part>` (e.g. `@primereact/ui/select`, `@primereact/ui/inputtext`, `@primereact/ui/datatable`), `chart.js`, `leaflet`, `ckeditor`, or `custom` for components with no third-party base. Drives `dependency-map.md`. |
+| `formContract` | string | ➖ | Shared contract the component follows. RHF-bound field wrappers use `FieldControllerProps` (see [`field-controller.md`](./field-controller.md)); non-text-box fields (toggles, groups, ranges) use `ChoiceFieldControllerProps`. Omit if the component isn't RHF-bound. |
 | `requiredStyles` | string[] | ➖ | SCSS partials from `@mantis-core/styles`, e.g. `['scss/inputs.scss']`. Drives `style-imports.md`. Empty/omit when the component uses only utility classes or inline styles. |
 | `relatedComponents` | string[] | ➖ | Sibling component `name`s. Cross-reference for LLMs. |
 | `relatedNextCore` | string[] | ➖ | Hooks/utils from `@mantis-core/next-core` it pairs with, e.g. `['useList']`. Empty for stateless components. |
-| `props` | object[] | ✅ | Each: `{ name, type, required, default?, description? }`. `name`/`type` strings, `required` boolean, `default`/`description` optional strings. Maps 1:1 to `catalog.json.props[]`. Empty array `[]` for components with no documented props (factories, etc.). |
+| `props` | object[] | ✅ | Each: `{ name, type, required, default?, description? }`. `name`/`type` strings, `required` boolean, `default`/`description` optional strings. Maps 1:1 to `catalog.json.props[]`. For a wrapper extending `FieldControllerProps`/`ChoiceFieldControllerProps`, list only the props it adds or overrides beyond the shared contract (link the contract via `formContract` instead of repeating `name`/`control`/`rules`/… on every wrapper). Empty array `[]` for components with no documented props (factories, etc.). |
+
+## `formContract`: the flattened API (PR11)
+
+Form wrappers no longer take a `controller={{ ... }}` object prop. They extend
+`FieldControllerProps` (or `ChoiceFieldControllerProps` for non-text-box fields) directly as their
+own props, alongside their component-specific props:
+
+```tsx
+// PR11 — flattened, no `controller` object
+<TextField name='email' control={control} label='Email' rules={{ required: true }} />
+
+// NOT this (PR10 shape, removed)
+<TextInput controller={{ name: 'email', control }} label='Email' />
+```
+
+See [`field-controller.md`](./field-controller.md) for the full prop list, `FieldShell` label
+modes, and the recipe for building a new wrapper.
 
 ## Body
 
 - `## Example` — **enforced**: if the `## Example` heading is present it MUST contain exactly one fenced
   ```tsx block (closing fence on its own line) — the generator throws otherwise. The code inside is
-  extracted verbatim into `catalog.json.example`. Keep it copy-pasteable. Use the heading `## Example`
-  (singular); `## Examples` is not recognized. Avoid an inline ``` inside the snippet.
+  extracted verbatim into `catalog.json.example`. Use the heading `## Example` (singular); `##
+  Examples` is not recognized. Avoid an inline ``` inside the snippet.
+- **Self-contained and compilable**: the `## Example` snippet MUST include its own `import`
+  statements — importing the component from the exact deep path declared in frontmatter `import`,
+  plus any other modules it uses (`react-hook-form`, other Mantis Core components, etc.) — and MUST
+  define a `function Example() { ... }` component that renders the snippet's JSX. A CI check
+  compiles every doc's `## Example` block in isolation (no ambient imports, no shared scope across
+  docs), so a snippet missing an import or referencing an undefined variable fails the build. Only
+  this `## Example` fence is compiled by `check-doc-examples`; other ```tsx fences elsewhere in a
+  doc are illustrative and not type-checked. Keep it copy-pasteable and minimal — one realistic
+  usage, not a feature tour.
 - `## Notes` — optional prose. Not consumed by the generator beyond shipping in the `.md`.
 
+## Multi-package docs
+
+The same frontmatter-driven approach extends beyond `@mantis-core/ui` to `@mantis-core/next-core`,
+`@mantis-core/nuqs`, and `@mantis-core/styles`. Each package's `docs/*.md` files use the same
+minimal frontmatter subset — `name`, `import`, `whenToUse`, `props` — with `category` taking
+per-package values (e.g. `providers`, `theme`, `toasts` for `next-core`; `hooks`, `parsers` for
+`nuqs`; `styles` for `styles`). A generator produces a per-package `llms.txt` from these files, the
+same way `pnpm gen:catalog` does for `@mantis-core/ui`. This section is a pointer only — the
+frontmatter contract and `## Example` rules above apply as-is; generator specifics live with that
+package's own generator script, not here.
+
 ## Generated outputs (do not hand-edit)
 
 | Output | Built from |
@@ -73,6 +115,6 @@ props:
 
 ## Hand-maintained (not generated)
 
-- `docs/contracts/controller-props.md` — shared contract, not derivable from one component.
+- `docs/contracts/field-controller.md` — shared RHF contract, not derivable from one component.
 - `docs/README.md`, `README.md` — narrative docs.
 - Each component's `## Notes` prose.