@mantis-core/ui 0.4.0 → 0.6.0

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

@@ -0,0 +1,120 @@
+# Component Doc Schema
+
+Single source of truth for each component in `@mantis-core/ui`. One file per component at
+`docs/components/<kebab-name>.md`. The file has **YAML frontmatter** (machine data) plus a short
+prose body (`## Example`, optional `## Notes`).
+
+`catalog.json`, `COMPONENTS.md`, `llms.txt`, `docs/contracts/dependency-map.md`, and
+`docs/contracts/style-imports.md` are **generated** from these files by `pnpm gen:catalog` — never
+edit them by hand. To document a component, edit its `.md` here and re-run the generator.
+
+## File shape
+
+```md
+---
+name: TextField
+category: forms
+import: '@mantis-core/ui/components/Forms/TextField'
+whenToUse: Single-line text field wired to react-hook-form.
+baseLibrary: '@primereact/ui/inputtext'
+formContract: FieldControllerProps
+requiredStyles: ['scss/inputs.scss']
+relatedComponents: ['SelectField', 'FieldShell']
+relatedNextCore: []
+props:
+  - { 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
+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
+
+- Optional prose. Gotchas, variants, edge cases. Keep terse — LLM-optimized, no over-info.
+```
+
+## Frontmatter fields
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `name` | string | ✅ | Component identifier, PascalCase. Matches the export. |
+| `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. 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[]`. 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`. 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 |
+|---|---|
+| `catalog.json` | All frontmatter, grouped by `category`. Shape: `{ name, import, whenToUse, props, example, category }`. |
+| `COMPONENTS.md` | Index linking every `docs/components/*.md`. |
+| `llms.txt` | LLM entry-point: `name · whenToUse · import · link`, grouped by category. |
+| `docs/contracts/dependency-map.md` | `name → baseLibrary`, sectioned PrimeReact / non-PrimeReact / custom. |
+| `docs/contracts/style-imports.md` | `name → requiredStyles`, plus the consolidated `@use` block. |
+
+## Hand-maintained (not generated)
+
+- `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.

package/docs/contracts/dependency-map.md

@@ -1,57 +1,94 @@
+<!-- GENERATED by `pnpm gen:catalog` — do not edit. Source: docs/components/*.md -->
+
 # Underlying Library Map
 
-Use this file when you need to know which base library a component wraps.
+Which base library each component wraps.
 
 ## PrimeReact wrappers
 
-- `Button`: `primereact/button`
-- `DateInput`: `primereact/calendar`
-- `DropDown`: `primereact/dropdown`
-- `MultiSelect`: `primereact/multiselect`
-- `NumberInput`: `primereact/inputnumber`
-- `TextInput`: `primereact/inputtext`
-- `TextArea`: `primereact/inputtextarea`
-- `Toggle`: `primereact/checkbox`
-- `ToggleInlineButton`: `primereact/selectbutton`
-- `PaginatedTable`: `primereact/datatable`
-- `ActionColumn`: `primereact/column`
-- `IndexColumn`: `primereact/column`
-- `MenuButton`: `primereact/tieredmenu`
-- `FilterPannel`: `primereact/sidebar`
-- `MultiSelectFilter`: `primereact/multiselect`
-- `ConfirmDialog`: `primereact/dialog`
+- `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
 
-- `Select`: `react-select`
-- `AsyncSelect`: `react-select/async`
-- `CKEditorInput`: `@ckeditor/ckeditor5-react` + `ckeditor5`
-- `TimePicker`: `react-datepicker`
-- `MapPickerClient`: `react-leaflet` + `leaflet`
-- `MapPickerOSM`: Leaflet loaded from CDN
-- `MapPicker`: `next/dynamic` wrapper over `MapPickerClient`
+- `AdminPageLayout`: `React context + custom shell`
+- `BarChart`: `chart.js`
+- `CKEditorInput`: `ckeditor`
+- `DonutChart`: `chart.js`
+- `ErrorMessage`: `@hookform/error-message`
+- `LineChart`: `chart.js`
+- `MapPicker`: `leaflet`
+- `MapPickerClient`: `leaflet`
+- `MapPickerOSM`: `leaflet`
 
 ## Custom components
 
-- `Loading`
+- `AdminPageConfigurator`
+- `AdminPageHeader`
+- `AdminPageLayoutShell`
+- `AppShell`
+- `Breadcrumbs`
+- `ChangePasswordForm`
+- `CommandPalette`
+- `ConfirmDialog`
+- `DataState`
+- `DescriptionList`
+- `DirtyFormGuard`
+- `EmptyState`
+- `ErrorBoundary`
+- `FieldShell`
 - `FileDropzone`
-- `UploadFilesPreview`
+- `FilterPannel`
+- `ForgotPasswordForm`
 - `FormActionsBar`
 - `FormFieldRender`
-- `RenderField`
-- `DirtyFormGuard`
-- `useDirtyFormGuard`
-- `TableToolbar`
-- `TableFilterField`
-- `PageTitle`
 - `FormSection`
-- `AdminPageHeader`
-- `AdminPageLayoutProvider`
-- `AdminPageConfigurator`
-- `AdminPageLayoutShell`
+- `HiddenField`
+- `LoginForm`
+- `PageTitle`
 - `Pagination`
-- `PaginationInfo`
-- `PageSizeSelector`
+- `RenderField`
+- `ResetPasswordForm`
 - `RichTextPreview`
+- `StatCard`
 - `StatusBadge`
-- `DataState`
+- `TableFilterField`
+- `TableToolbar`
+- `UploadFilesPreview`
+- `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

@@ -1,27 +1,34 @@
+<!-- GENERATED by `pnpm gen:catalog` — do not edit. Source: docs/components/*.md -->
+
 # Style Import Guide
 
 `@mantis-core/ui` does not inject CSS automatically. Import the matching partials from `@mantis-core/styles`.
 
-## Common imports
+## All partials
 
 ```scss
-@use "@mantis-core/styles/scss/buttons.scss";
-@use "@mantis-core/styles/scss/inputs.scss";
-@use "@mantis-core/styles/scss/select.scss";
-@use "@mantis-core/styles/scss/select-button.scss";
-@use "@mantis-core/styles/scss/table.scss";
-@use "@mantis-core/styles/scss/status-badge.scss";
-@use "@mantis-core/styles/scss/data-state.scss";
+@use "@mantis-core/styles/scss/ckeditor.scss";
 @use "@mantis-core/styles/scss/confirm-dialog.scss";
-@use "@mantis-core/styles/scss/form-actions.scss";
+@use "@mantis-core/styles/scss/data-state.scss";
 @use "@mantis-core/styles/scss/file-dropzone.scss";
-@use "@mantis-core/styles/scss/ckeditor.scss";
+@use "@mantis-core/styles/scss/form-actions.scss";
 @use "@mantis-core/styles/scss/rich-text-preview.scss";
-@use "@mantis-core/styles/scss/switch.scss";
+@use "@mantis-core/styles/scss/status-badge.scss";
+@use "@mantis-core/styles/scss/table.scss";
 ```
 
+## Per component
+
+- `CKEditorInput`: `scss/ckeditor.scss`
+- `ConfirmDialog`: `scss/confirm-dialog.scss`
+- `DataState`: `scss/data-state.scss`
+- `FileDropzone`: `scss/file-dropzone.scss`
+- `FormActionsBar`: `scss/form-actions.scss`
+- `MantisDataTable`: `scss/table.scss`
+- `PaginatedTable`: `scss/table.scss`
+- `RichTextPreview`: `scss/rich-text-preview.scss`
+- `StatusBadge`: `scss/status-badge.scss`
+
 ## Notes
 
-- `Pagination` is a custom component and does not use `paginator.scss`.
-- `Select` and `AsyncSelect` require `select.scss`, not PrimeReact input styles.
-- Components like `Loading`, `UploadFilesPreview`, `PageTitle`, and `FormSection` rely mainly on utility classes or inline styles.
+- Components not listed above rely on utility classes or inline styles only.