@mantis-core/ui 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -0,0 +1,155 @@
+# @mantis-core/ui
+
+## 0.7.0
+
+### Minor Changes
+
+- fbd4637: Add the `mantis-llm` CLI (`pnpm exec mantis-llm`) so consuming projects can wire LLM discovery in one command.
+
+  - New `bin` shipped with the package: `mantis-llm` writes/updates a managed pointer block into the consuming project's `CLAUDE.md` / `AGENTS.md` (creating them if missing, idempotent), so any LLM working in that repo discovers the installed `@mantis-core/*` docs in `node_modules` without being told each session.
+  - The block carries the key usage rules inline (import from `@mantis-core/ui`, flat `FieldControllerProps`, mount providers when `next-core` is present) plus per-package pointers — all conditioned on which `@mantis-core/*` packages are actually installed.
+  - `--check` fails (exit ≠0) when the block is missing or stale, for use in a consumer's CI; `--files=` targets specific files.
+  - Tightened the published `files` allowlist so internal contributor docs (`STORYBOOK_*`, `component-doc-schema.md`) no longer ship to consumers, while all consumer-facing docs (`components/`, `field-controller.md`, `style-imports.md`, `dependency-map.md`) still do.
+
+## 0.6.0
+
+### Minor Changes
+
+- 4fbdfb2: PrimeReact 11 migration + LLM-first documentation.
+
+  **Breaking (PrimeReact 10 → 11):**
+
+  - **Forms** now use a flattened `FieldControllerProps` API — wrappers take `name`/`control`/`rules`/`label`
+    directly, there is no `controller={{ ... }}` object prop and `ControllerProps` is removed. See
+    `docs/contracts/field-controller.md`.
+  - **`@mantis-core/ui` removed react-select and react-datepicker.** The `Select`, `AsyncSelect`, `MultiSelect`,
+    `Combobox`, `DropDown`, `DateInput`, `DateRangeInput`, `TimePicker`, `CurrencyInput`, `Toggle`, `TextInput`,
+    and `NumberInput` components are gone — use `SelectField` / `AutoCompleteField` (async + creatable),
+    `DateField` (single/range/time), `NumberField` (`mode="currency"`), `TextField`, `SwitchField`.
+  - **Tables** are descriptor-driven: `MantisDataTable` / `PaginatedTable` take `rows` + `columns` (`ColumnDef[]`)
+    and `paginator`, replacing the old `value`/`totalRecords`/`lazy` children API. Adds cell presets and a
+    headless pager.
+  - **`@mantis-core/next-core`** ships native PrimeReact 11 theming (`./theme`: `MantisThemeProvider`, presets,
+    `buildPreset`, config persistence) and a native toast host (`MantisToaster` / `useMantisToasts`);
+    `react-hot-toast` is retired. `MantisCoreBaseProvider` still mounts the PrimeReact 10 provider
+    (`primereact/api`) — `primereact` remains a required peer — while `MantisThemeProvider` mounts the
+    PrimeReact 11 provider.
+  - **`@mantis-core/styles`** removed the dead `select`, `select-button`, `date-picker`, `switch`, and `buttons`
+    SCSS partials (component colors now come from the PrimeReact 11 preset).
+  - **`@mantis-core/nuqs`** now requires `react ^19` and exports `useDataTableQuery` (headless pagination +
+    sorting + filtering with optional URL sync).
+
+  **Peer dependencies:** `@primereact/ui`, `@primereact/core`, `@primereact/types` `11.0.0-rc.1`,
+  `@primeuix/themes` `3.0.0-rc.1`, `@primeicons/react` `8.0.0-rc.1`.
+
+  **LLM-first docs (consumable from `node_modules`):** every package ships an `llms.txt` (exports `./llms.txt`);
+  `@mantis-core/ui` ships `catalog.json` (exports `./catalog.json`) plus per-component docs; `@mantis-core/next-core`
+  ships `docs/setup.md`. A CI gate (`check:doc-examples`) type-checks every documentation example against source.
+
+### Patch Changes
+
+- Updated dependencies [4fbdfb2]
+  - @mantis-core/utils@0.5.1
+
+## 0.5.0
+
+### Minor Changes
+
+- b553a87: Component docs are now LLM-first and single-source: each component is one `docs/components/<name>.md` with YAML frontmatter, and `catalog.json`, `COMPONENTS.md`, `llms.txt`, `dependency-map.md`, and `style-imports.md` are generated from them via `pnpm gen:catalog` (with `pnpm check:catalog` as a drift guard wired into the release gate).
+
+  - The package now ships `llms.txt` (LLM entry-point) and a complete per-component doc set so documentation is visible at install time.
+  - 9 components that were documented in prose but absent from the catalog are now first-class catalog entries.
+  - Removed the dead `PRIMEREACT_MAPPING.md` redirect stub.
+
+## 0.4.0
+
+### Minor Changes
+
+- b3beda0: Add reusable Auth UI components: PasswordInput, LoginForm, ForgotPasswordForm, ResetPasswordForm, ChangePasswordForm, UserMenu
+- 68f6475: Add reusable chart components (LineChart, BarChart, DonutChart) powered by chart.js + react-chartjs-2. Generic, extensible wrappers for building any dashboard — zero-config defaults, fully overridable options, color palette, className passthrough, and TypeScript strict types.
+- 9ea7de9: Add P1 UI coverage (no new dependencies; PrimeReact/lucide-react wrappers, all extensible per the contribution contract):
+
+  - Feedback: `EmptyState`, `ErrorBoundary`, `TableSkeleton`, `CardSkeleton`, `Avatar`, `Tag`.
+  - Overlays: `Drawer` (Sidebar), `Modal` (Dialog).
+  - Form inputs: `Combobox`, `TagsInput`, `OtpInput`, `ColorPickerInput`, `RatingInput`, `DatePresets`.
+  - Navigation: `PageTabs`, `CommandPalette` (+ `useCommandPalette` hook).
+  - Data display: `StatCard`, `Timeline`, `DescriptionList`.
+  - `AppShell` gains optional `collapsible` / `defaultCollapsed` (backward-compatible collapsible sidebar).
+
+- 3a759d1: Add react-hook-form rule builders via `@mantis-core/ui/validation`: `requiredRule`, `notEmptyRule`, `emailRule`, `phoneRule`, `cedulaRule`, `rucRule`, `minLengthRule`, `maxLengthRule`. Optional Zod resolver re-export via `@mantis-core/ui/validation/zod`.
+
+### Patch Changes
+
+- Updated dependencies [3a759d1]
+  - @mantis-core/utils@0.5.0
+
+## 0.3.0
+
+### Minor Changes
+
+- 8a85ace: Add reusable layout + form inputs (no new dependencies — all on existing PrimeReact peers):
+
+  - Layout: `AppShell` (config-driven sidebar + topbar + mobile drawer) and a standalone `Breadcrumbs` component under `components/pages/app-shell`. `AdminPageHeader` now reuses `Breadcrumbs` (single source).
+  - Form inputs (Controller pattern): `RadioGroup`, `SearchInput` (debounced, optional controller), `DateRangeInput`, `RangeSlider`, `PhoneInput`, `CurrencyInput`.
+  - Multi-step forms: `FormWizard` (PrimeReact `Steps` + react-hook-form, per-step validation; composes inside an existing `FormProvider`).
+
+  All importable by path, e.g. `@mantis-core/ui/components/Forms/CurrencyInput`, `@mantis-core/ui/components/pages/app-shell/AppShell`.
+
+## 0.2.0
+
+### Minor Changes
+
+- 83d6e71: Harden package publishing and quality gates across the monorepo.
+
+  - add `prepack` and `prepublishOnly` scripts to guarantee build artifacts before publish
+  - add package metadata (`license`, `engines`, and `sideEffects` for TS packages)
+  - add package test coverage with Vitest and include tests in release checks
+  - add tarball content validation script to ensure npm packages include expected build outputs
+  - decouple `@mantis-core/ui` from `@mantis-core/supabase-core` by consuming pagination helper from `@mantis-core/utils`
+  - expose `getPaginationRange` from `@mantis-core/utils`
+  - add reusable `StatusBadge`, `DataState`, and `ConfirmDialog` components to `@mantis-core/ui`
+  - add form primitives in `@mantis-core/ui`: `AsyncSelect`, `FormActionsBar`, `DirtyFormGuard`, and `FileDropzone`
+
+### Patch Changes
+
+- Updated dependencies [83d6e71]
+  - @mantis-core/utils@0.4.0
+
+## 0.1.3
+
+### Patch Changes
+
+- 83d6e71: Harden package publishing and quality gates across the monorepo.
+
+  - add `prepack` and `prepublishOnly` scripts to guarantee build artifacts before publish
+  - add package metadata (`license`, `engines`, and `sideEffects` for TS packages)
+  - add package test coverage with Vitest and include tests in release checks
+  - add tarball content validation script to ensure npm packages include expected build outputs
+  - decouple `@mantis-core/ui` from `@mantis-core/supabase-core` by consuming pagination helper from `@mantis-core/utils`
+  - expose `getPaginationRange` from `@mantis-core/utils`
+
+- Updated dependencies [83d6e71]
+  - @mantis-core/utils@0.3.0
+
+## 0.1.2
+
+### Patch Changes
+
+- Updated dependencies [05ef1e4]
+  - @mantis-core/utils@0.2.0
+
+## 0.1.1
+
+### Patch Changes
+
+- chore: prepare @mantis-core packages for npm release
+
+  - add npm metadata (`repository`, `bugs`, `homepage`, `keywords`) in all packages
+  - add `prepack` build script in all packages
+  - include `COMPONENTS.md` in `@mantis-core/ui` published files
+  - enforce `npm pack --dry-run` in release quality gates
+  - enable npm provenance in release workflow
+
+- Updated dependencies
+  - @mantis-core/supabase-core@0.1.1
+  - @mantis-core/utils@0.1.1

package/COMPONENTS.md

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

package/README.md

@@ -9,7 +9,7 @@ Reusable React component library for Mantis Core applications.
 ## Scope
 
 - Reusable React components and helper types.
-- Wrappers around PrimeReact, `react-select`, CKEditor, and Leaflet where Mantis needs a stable contract.
+- Wrappers around PrimeReact 11, CKEditor, and Leaflet where Mantis needs a stable contract.
 - Components that optionally consume the visual contracts defined in `@mantis-core/styles`.
 
 ## Out of Scope
@@ -33,14 +33,14 @@ Required peers:
 - `primeicons`
 - `react-hook-form`
 
-Some exports also require optional peers already pulled by this package surface, such as CKEditor, `react-select`, `react-datepicker`, `leaflet`, and `react-leaflet`.
+Some exports also require optional peers already pulled by this package surface, such as CKEditor, `leaflet`, `react-leaflet`, `chart.js`, and `react-chartjs-2`.
 
 ## Import Strategy
 
 Preferred:
 
 ```ts
-import { PaginatedTable, TableToolbar, TextInput } from "@mantis-core/ui";
+import { PaginatedTable, TableToolbar, TextField } from "@mantis-core/ui";
 ```
 
 Supported subpaths:
@@ -73,7 +73,20 @@ Example:
 
 - [docs/README.md](./docs/README.md): package documentation index
 - [COMPONENTS.md](./COMPONENTS.md): lightweight component index
-- [PRIMEREACT_MAPPING.md](./PRIMEREACT_MAPPING.md): lightweight dependency-map pointer
+- [docs/contracts/dependency-map.md](./docs/contracts/dependency-map.md): which underlying PrimeReact 11 module each component wraps (generated via `pnpm gen:catalog`)
+
+## LLM discovery
+
+This package ships `llms.txt` (component index), `catalog.json` (machine-readable catalog), and
+per-component `docs/` as published files, so a consuming app's LLM can read them straight from
+`node_modules/@mantis-core/ui/`. To point the LLM at them, run once per consuming project:
+
+```bash
+pnpm exec mantis-llm      # or: npx mantis-llm  ·  yarn mantis-llm
+```
+
+This writes a managed pointer block into the project's `CLAUDE.md` / `AGENTS.md` (idempotent;
+`--check` for CI). See the "LLM discovery" section in the repo root `docs/consumir/GETTING_STARTED.md`.
 
 ## Public API Summary
 
@@ -81,7 +94,7 @@ Main export groups:
 
 - Buttons: `Button`
 - Loaders: `Loading`
-- Forms: `TextInput`, `TextArea`, `NumberInput`, `DropDown`, `DateInput`, `Select`, `AsyncSelect`, `Switch`, `Toggle`, `ToggleInlineButton`, `CKEditorInput`, `FileDropzone`, `UploadFilesPreview`
+- Forms: `TextField`, `TextArea`, `NumberField`, `SelectField`, `AutoCompleteField`, `DateField`, `CheckboxField`, `SwitchField`, `RadioGroup`, `ToggleInlineButton`, `CKEditorInput`, `FileDropzone`, `UploadFilesPreview` — every field wrapper extends `FieldControllerProps` (flat `name`/`control`/`rules`/`label`, no `controller={{...}}` object); see `docs/contracts/field-controller.md`
 - Form helpers: `RenderField`, `FormFieldRender`, `FormActionsBar`, `DirtyFormGuard`, `useDirtyFormGuard`, `ErrorMessage`, `HiddenField`
 - Tables: `PaginatedTable`, `TableToolbar`, `TableFilterField`, `ActionColumn`, `MenuButton`, `IndexColumn`, `FilterPannel`, `MultiSelectFilter`
 - Page layout: `AdminPageConfigurator`, `AdminPageLayoutProvider`, `useAdminPageLayout`, `AdminPageLayoutShell`, `AdminPageHeader`, `FormSection`, `PageTitle`
@@ -93,7 +106,7 @@ Main export groups:
 1. Keep new exports domain-agnostic.
 2. Keep the public API anchored in `src/index.ts`.
 3. Document new exports in `COMPONENTS.md`.
-4. Update `PRIMEREACT_MAPPING.md` when the underlying implementation library changes.
+4. Run `pnpm gen:catalog` to regenerate `docs/contracts/dependency-map.md` (and `catalog.json`) when the underlying implementation library changes — edit the per-component `.md` in `docs/components/`, not the generated files.
 5. Preserve the `mantis-core-*` style contract where shared styles are intended.
 
 ## Local Validation