@mantis-core/ui 0.5.0 → 0.7.0

package/catalog.json

@@ -0,0 +1,3031 @@
+{
+  "_generated": "GENERATED by `pnpm gen:catalog` — do not edit. Source: docs/components/*.md",
+  "package": "@mantis-core/ui",
+  "categories": {
+    "forms": [
+      {
+        "name": "AutoCompleteField",
+        "import": "@mantis-core/ui/components/Forms/AutoCompleteField",
+        "category": "forms",
+        "whenToUse": "Async (or sync) autocomplete text field wired to react-hook-form via `loadOptions`, with optional free-text `creatable` mode. Absorbs the former AsyncSelect + Combobox.",
+        "props": [
+          {
+            "name": "loadOptions",
+            "type": "(query: string) => Promise<readonly Record<string, unknown>[]> | readonly Record<string, unknown>[]",
+            "required": true,
+            "description": "Called on each query change (PR11 debounces via delay/minLength internally); replaces the old hand-rolled AsyncSelect debounce."
+          },
+          {
+            "name": "creatable",
+            "type": "boolean",
+            "required": false,
+            "default": "false",
+            "description": "Allow committing free text matching no option; typed text commits on each keystroke instead of being cleared on blur."
+          },
+          {
+            "name": "optionLabel",
+            "type": "string",
+            "required": false,
+            "default": "'label'",
+            "description": "Key read for each option's display label."
+          },
+          {
+            "name": "optionValue",
+            "type": "string",
+            "required": false,
+            "description": "Key read for each option's bound scalar value."
+          },
+          {
+            "name": "placeholder",
+            "type": "string",
+            "required": false
+          },
+          {
+            "name": "optionTemplate",
+            "type": "'default' | 'twoLine'",
+            "required": false,
+            "default": "'default'",
+            "description": "Named per-option render preset; 'twoLine' adds a second line from `descriptionField`."
+          },
+          {
+            "name": "descriptionField",
+            "type": "string",
+            "required": false,
+            "description": "Row key for the second line when optionTemplate is 'twoLine'."
+          },
+          {
+            "name": "renderOption",
+            "type": "(option: Record<string, unknown>, index: number) => ReactNode",
+            "required": false,
+            "description": "Escape hatch: full custom per-option render, overrides optionTemplate."
+          },
+          {
+            "name": "className",
+            "type": "string",
+            "required": false
+          }
+        ],
+        "example": "import { AutoCompleteField } from '@mantis-core/ui/components/Forms/AutoCompleteField';\nimport { useForm } from 'react-hook-form';\n\nconst CITIES = [\n  { label: 'Quito', value: 'UIO' },\n  { label: 'Cuenca', value: 'CUE' },\n];\n\nasync function searchCities(query: string) {\n  return CITIES.filter((c) => c.label.toLowerCase().includes(query.toLowerCase()));\n}\n\nfunction Example() {\n  const { control } = useForm({ defaultValues: { city: null } });\n  return (\n    <AutoCompleteField\n      name='city'\n      control={control}\n      label='City'\n      optionLabel='label'\n      optionValue='value'\n      loadOptions={searchCities}\n    />\n  );\n}"
+      },
+      {
+        "name": "CheckboxField",
+        "import": "@mantis-core/ui/components/Forms/CheckboxField",
+        "category": "forms",
+        "whenToUse": "Single boolean checkbox wired to react-hook-form.",
+        "props": [],
+        "example": "import { CheckboxField } from '@mantis-core/ui/components/Forms/CheckboxField';\nimport { useForm } from 'react-hook-form';\n\nfunction Example() {\n  const { control } = useForm({ defaultValues: { acceptsTerms: false } });\n  return (\n    <CheckboxField\n      name='acceptsTerms'\n      control={control}\n      label='I accept the terms'\n      rules={{ required: 'You must accept.' }}\n    />\n  );\n}"
+      },
+      {
+        "name": "CKEditorInput",
+        "import": "@mantis-core/ui/components/Forms/CKEditorInput",
+        "category": "forms",
+        "whenToUse": "Rich-text WYSIWYG editor (CKEditor 5) wired to react-hook-form; emits an HTML string.",
+        "props": [
+          {
+            "name": "controller",
+            "type": "Pick<FieldControllerProps, \"name\" | \"control\" | \"rules\" | \"defaultValue\" | \"shouldUnregister\">",
+            "required": true,
+            "description": "Nested react-hook-form binding."
+          },
+          {
+            "name": "placeholder",
+            "type": "string",
+            "required": false,
+            "default": "'Escribe aqui...'"
+          },
+          {
+            "name": "disabled",
+            "type": "boolean",
+            "required": false
+          },
+          {
+            "name": "readOnly",
+            "type": "boolean",
+            "required": false
+          },
+          {
+            "name": "className",
+            "type": "string",
+            "required": false
+          },
+          {
+            "name": "preset",
+            "type": "'default' | 'blog' | 'property' | 'note'",
+            "required": false,
+            "default": "'default'",
+            "description": "Picks a bundled toolbar layout + min-height + stats visibility."
+          },
+          {
+            "name": "toolbarItems",
+            "type": "string[]",
+            "required": false,
+            "description": "Overrides the preset's toolbar items."
+          },
+          {
+            "name": "minHeight",
+            "type": "string",
+            "required": false,
+            "description": "Overrides the preset's min-height (CSS value)."
+          },
+          {
+            "name": "maxHeight",
+            "type": "string",
+            "required": false
+          },
+          {
+            "name": "showStats",
+            "type": "boolean",
+            "required": false,
+            "description": "Overrides the preset's word/character/read-time footer."
+          },
+          {
+            "name": "validateNonEmptyHtml",
+            "type": "boolean",
+            "required": false,
+            "default": "true",
+            "description": "When `rules.required` is set, also rejects HTML that has no plain-text content."
+          },
+          {
+            "name": "requiredMessage",
+            "type": "string",
+            "required": false,
+            "default": "'Este campo es obligatorio'"
+          },
+          {
+            "name": "config",
+            "type": "EditorConfig",
+            "required": false,
+            "description": "Deep-merged on top of the preset's CKEditor config (plugins/translations override rather than merge)."
+          },
+          {
+            "name": "onReady",
+            "type": "(editor: any) => void",
+            "required": false
+          },
+          {
+            "name": "onHtmlChange",
+            "type": "(html: string) => void",
+            "required": false
+          },
+          {
+            "name": "onPlainTextChange",
+            "type": "(plainText: string) => void",
+            "required": false
+          },
+          {
+            "name": "onMetricsChange",
+            "type": "(metrics: CKEditorContentMetrics) => void",
+            "required": false,
+            "description": "`{ plainText, words, characters, readTimeMinutes }`."
+          }
+        ],
+        "example": "import CKEditorInput from '@mantis-core/ui/components/Forms/CKEditorInput';\nimport { useForm, type FieldValues } from 'react-hook-form';\n\nfunction Example() {\n  const { control } = useForm<FieldValues>({ defaultValues: { body: '' } });\n  return (\n    <CKEditorInput\n      controller={{ name: 'body', control, rules: { required: true } }}\n      preset='blog'\n    />\n  );\n}"
+      },
+      {
+        "name": "ColorPickerInput",
+        "import": "@mantis-core/ui/components/Forms/ColorPickerInput",
+        "category": "forms",
+        "whenToUse": "RHF-bound color picker over PR11's compound InputColor (area + sliders + swatch + eyedropper + hex input); value is a hex string.",
+        "props": [
+          {
+            "name": "format",
+            "type": "ColorSpace",
+            "required": false,
+            "description": "Picker color space (e.g. hsb, rgb) — the bound RHF value is always normalized to hex regardless."
+          }
+        ],
+        "example": "import { ColorPickerInput } from '@mantis-core/ui/components/Forms/ColorPickerInput';\nimport { useForm } from 'react-hook-form';\n\nfunction Example() {\n  const { control } = useForm({ defaultValues: { brand: '#276def' } });\n  return <ColorPickerInput name='brand' control={control} label='Color' />;\n}"
+      },
+      {
+        "name": "DateField",
+        "import": "@mantis-core/ui/components/Forms/DateField",
+        "category": "forms",
+        "whenToUse": "Single date, date-range, or time-only picker wired to react-hook-form; one wrapper covers all three via `selectionMode`/`timeOnly`/`showTime`.",
+        "props": [
+          {
+            "name": "selectionMode",
+            "type": "'single' | 'multiple' | 'range'",
+            "required": false,
+            "default": "'single'",
+            "description": "Drives the value shape: Date for single, Date[] for multiple, (Date|null)[] for range."
+          },
+          {
+            "name": "showTime",
+            "type": "boolean",
+            "required": false,
+            "default": "false",
+            "description": "Adds hour/minute pickers alongside the calendar."
+          },
+          {
+            "name": "timeOnly",
+            "type": "boolean",
+            "required": false,
+            "default": "false",
+            "description": "Hides the calendar, showing only the time pickers."
+          },
+          {
+            "name": "hourFormat",
+            "type": "'12' | '24'",
+            "required": false,
+            "default": "'24'",
+            "description": "Adds an AM/PM picker when set to 12."
+          },
+          {
+            "name": "showSeconds",
+            "type": "boolean",
+            "required": false,
+            "default": "false",
+            "description": "Adds a seconds picker (with showTime/timeOnly)."
+          },
+          {
+            "name": "minDate",
+            "type": "Date",
+            "required": false
+          },
+          {
+            "name": "maxDate",
+            "type": "Date",
+            "required": false
+          },
+          {
+            "name": "placeholder",
+            "type": "string",
+            "required": false
+          },
+          {
+            "name": "showButtonBar",
+            "type": "boolean",
+            "required": false,
+            "default": "false",
+            "description": "Renders a Today + Clear footer inside the panel."
+          }
+        ],
+        "example": "import { DateField } from '@mantis-core/ui/components/Forms/DateField';\nimport { useForm } from 'react-hook-form';\n\nfunction Example() {\n  const { control } = useForm({ defaultValues: { fecha: null as Date | null } });\n  return <DateField name='fecha' control={control} label='Fecha' />;\n}"
+      },
+      {
+        "name": "DatePresets",
+        "import": "@mantis-core/ui/components/Forms/DatePresets",
+        "category": "forms",
+        "whenToUse": "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\"`.",
+        "props": [
+          {
+            "name": "onChange",
+            "type": "(range: [Date, Date]) => void",
+            "required": true
+          },
+          {
+            "name": "presets",
+            "type": "{ label: string; resolve: () => [Date, Date] }[]",
+            "required": false,
+            "description": "Defaults to Today / 7 días / 30 días / Este mes."
+          },
+          {
+            "name": "className",
+            "type": "string",
+            "required": false
+          },
+          {
+            "name": "disabled",
+            "type": "boolean",
+            "required": false
+          }
+        ],
+        "example": "import DatePresets from '@mantis-core/ui/components/Forms/DatePresets';\nimport { useState } from 'react';\n\nfunction Example() {\n  const [range, setRange] = useState<[Date, Date] | null>(null);\n  return <DatePresets onChange={setRange} />;\n}"
+      },
+      {
+        "name": "DirtyFormGuard",
+        "import": "@mantis-core/ui/components/Forms/DirtyFormGuard",
+        "category": "forms",
+        "whenToUse": "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.",
+        "props": [
+          {
+            "name": "isDirty",
+            "type": "boolean",
+            "required": true,
+            "description": "Pass formState.isDirty from react-hook-form"
+          },
+          {
+            "name": "enabled",
+            "type": "boolean",
+            "required": false,
+            "default": "true",
+            "description": "Set to false to temporarily disable the guard"
+          },
+          {
+            "name": "message",
+            "type": "string",
+            "required": false,
+            "description": "Custom confirmation message shown to the user"
+          }
+        ],
+        "example": "import DirtyFormGuard from '@mantis-core/ui/components/Forms/DirtyFormGuard';\nimport { useForm } from 'react-hook-form';\n\nfunction Example() {\n  const { formState } = useForm({ defaultValues: { name: '' } });\n  return <DirtyFormGuard isDirty={formState.isDirty} />;\n}"
+      },
+      {
+        "name": "ErrorMessage",
+        "import": "@mantis-core/ui/components/Forms/ErrorMessage",
+        "category": "forms",
+        "whenToUse": "Standalone validation-error text for one named react-hook-form field, read from form context; use when composing a custom layout instead of FormFieldRender.",
+        "props": [
+          {
+            "name": "name",
+            "type": "string",
+            "required": true,
+            "description": "The RHF field name to read the error for."
+          }
+        ],
+        "example": "import ErrorMessage from '@mantis-core/ui/components/Forms/ErrorMessage';\nimport { FormProvider, useForm } from 'react-hook-form';\n\nfunction Example() {\n  const methods = useForm({ defaultValues: { email: '' } });\n  return (\n    <FormProvider {...methods}>\n      <ErrorMessage name='email' />\n    </FormProvider>\n  );\n}"
+      },
+      {
+        "name": "FieldShell",
+        "import": "@mantis-core/ui/components/Forms/FieldShell",
+        "category": "forms",
+        "whenToUse": "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).",
+        "props": [
+          {
+            "name": "id",
+            "type": "string",
+            "required": true,
+            "description": "Input id; also roots the generated help/error ids (`${id}-help` / `${id}-error`)."
+          },
+          {
+            "name": "label",
+            "type": "string",
+            "required": false
+          },
+          {
+            "name": "required",
+            "type": "boolean",
+            "required": false,
+            "description": "Presentational ` *` marker on the label; validation is still driven by rules."
+          },
+          {
+            "name": "helpText",
+            "type": "string",
+            "required": false
+          },
+          {
+            "name": "errorMessage",
+            "type": "string",
+            "required": false,
+            "description": "Typically `useFieldController(...).errorMessage`."
+          },
+          {
+            "name": "labelMode",
+            "type": "LabelMode",
+            "required": false,
+            "description": "'ifta' | 'float' | 'beside' | 'top' | 'none' — defaults to MantisThemeProvider."
+          },
+          {
+            "name": "floatVariant",
+            "type": "FloatVariant",
+            "required": false,
+            "description": "'over' | 'in' | 'on' — only used when labelMode='float'."
+          },
+          {
+            "name": "addonBefore",
+            "type": "ReactNode",
+            "required": false
+          },
+          {
+            "name": "addonAfter",
+            "type": "ReactNode",
+            "required": false
+          },
+          {
+            "name": "children",
+            "type": "ReactNode",
+            "required": true,
+            "description": "The input/trigger element."
+          }
+        ],
+        "example": "import { FieldShell } from '@mantis-core/ui/components/Forms/FieldShell';\n\nfunction Example() {\n  return (\n    <FieldShell id='email' label='Email' helpText='We will never share it.'>\n      <input id='email' type='email' />\n    </FieldShell>\n  );\n}"
+      },
+      {
+        "name": "FileDropzone",
+        "import": "@mantis-core/ui/components/Forms/FileDropzone",
+        "category": "forms",
+        "whenToUse": "Drag-and-drop file input with validation (type, size, count); supports a react-hook-form binding or plain controlled value/onChange.",
+        "props": [
+          {
+            "name": "controller",
+            "type": "Pick<FieldControllerProps, \"name\" | \"control\" | \"rules\" | \"defaultValue\" | \"shouldUnregister\">",
+            "required": false,
+            "description": "When provided, wires the dropzone to react-hook-form via this nested object."
+          },
+          {
+            "name": "value",
+            "type": "File[]",
+            "required": false,
+            "description": "Controlled file list (plain mode, when `controller` is omitted)"
+          },
+          {
+            "name": "onChange",
+            "type": "(files: File[]) => void",
+            "required": false,
+            "description": "Change handler (plain mode)"
+          },
+          {
+            "name": "onFilesAccepted",
+            "type": "(files: File[]) => void",
+            "required": false,
+            "description": "Called with accepted files after drop"
+          },
+          {
+            "name": "onFilesRejected",
+            "type": "(rejections: FileDropzoneRejectedFile[]) => void",
+            "required": false,
+            "description": "Called with rejected files after drop"
+          },
+          {
+            "name": "multiple",
+            "type": "boolean",
+            "required": false,
+            "default": "true",
+            "description": "Allow multiple files"
+          },
+          {
+            "name": "maxFiles",
+            "type": "number",
+            "required": false,
+            "default": "10",
+            "description": "Maximum number of files"
+          },
+          {
+            "name": "maxSizeBytes",
+            "type": "number",
+            "required": false,
+            "default": "10485760",
+            "description": "Max file size in bytes (default 10 MB)"
+          },
+          {
+            "name": "accept",
+            "type": "string | string[]",
+            "required": false,
+            "description": "Accepted MIME types or extensions"
+          },
+          {
+            "name": "disabled",
+            "type": "boolean",
+            "required": false,
+            "default": "false",
+            "description": "Disable the dropzone"
+          },
+          {
+            "name": "block",
+            "type": "boolean",
+            "required": false,
+            "default": "true",
+            "description": "Full-width layout"
+          },
+          {
+            "name": "label",
+            "type": "string",
+            "required": false,
+            "description": "Optional label above the zone"
+          },
+          {
+            "name": "hint",
+            "type": "string",
+            "required": false,
+            "description": "Hint text inside the zone"
+          },
+          {
+            "name": "dropTitle",
+            "type": "string",
+            "required": false,
+            "description": "Title text when idle"
+          },
+          {
+            "name": "dragOverTitle",
+            "type": "string",
+            "required": false,
+            "description": "Title text while dragging over"
+          },
+          {
+            "name": "className",
+            "type": "string",
+            "required": false,
+            "description": "Additional CSS class on the root element"
+          }
+        ],
+        "example": "import FileDropzone from '@mantis-core/ui/components/Forms/FileDropzone';\nimport { useForm, type FieldValues } from 'react-hook-form';\n\nfunction Example() {\n  const { control } = useForm<FieldValues>({ defaultValues: { documents: [] as File[] } });\n  return (\n    <FileDropzone\n      controller={{ name: 'documents', control }}\n      accept={['.pdf', '.jpg']}\n      maxFiles={5}\n    />\n  );\n}"
+      },
+      {
+        "name": "FormActionsBar",
+        "import": "@mantis-core/ui/components/Forms/FormActionsBar",
+        "category": "forms",
+        "whenToUse": "Sticky-capable action bar with primary/secondary buttons and optional left/right slots for form pages.",
+        "props": [
+          {
+            "name": "className",
+            "type": "string",
+            "required": false,
+            "description": "Additional CSS class on the root element"
+          },
+          {
+            "name": "align",
+            "type": "'start' | 'end' | 'between'",
+            "required": false,
+            "default": "'between'",
+            "description": "Horizontal alignment of action groups"
+          },
+          {
+            "name": "sticky",
+            "type": "boolean",
+            "required": false,
+            "default": "false",
+            "description": "Fix bar to bottom of viewport"
+          },
+          {
+            "name": "leftSlot",
+            "type": "ReactNode",
+            "required": false,
+            "description": "Content rendered on the left side"
+          },
+          {
+            "name": "rightSlot",
+            "type": "ReactNode",
+            "required": false,
+            "description": "Content rendered before the action buttons on the right"
+          },
+          {
+            "name": "primaryLabel",
+            "type": "string",
+            "required": false,
+            "default": "'Guardar'",
+            "description": "Label for the primary button"
+          },
+          {
+            "name": "primaryVariant",
+            "type": "ButtonVariant",
+            "required": false,
+            "default": "'primary'",
+            "description": "Design-system variant for primary button"
+          },
+          {
+            "name": "primaryType",
+            "type": "'button' | 'submit' | 'reset'",
+            "required": false,
+            "default": "'submit'",
+            "description": "HTML type for primary button"
+          },
+          {
+            "name": "primaryLoading",
+            "type": "boolean",
+            "required": false,
+            "default": "false",
+            "description": "Show loading spinner on primary button"
+          },
+          {
+            "name": "primaryDisabled",
+            "type": "boolean",
+            "required": false,
+            "default": "false",
+            "description": "Disable primary button"
+          },
+          {
+            "name": "onPrimaryClick",
+            "type": "() => void",
+            "required": false,
+            "description": "Click handler for primary button"
+          },
+          {
+            "name": "secondaryLabel",
+            "type": "string",
+            "required": false,
+            "description": "Label for the secondary button; omit to hide it"
+          },
+          {
+            "name": "secondaryVariant",
+            "type": "ButtonVariant",
+            "required": false,
+            "default": "'secondary'",
+            "description": "Design-system variant for secondary button"
+          },
+          {
+            "name": "secondaryType",
+            "type": "'button' | 'submit' | 'reset'",
+            "required": false,
+            "default": "'button'",
+            "description": "HTML type for secondary button"
+          },
+          {
+            "name": "secondaryOutlined",
+            "type": "boolean",
+            "required": false,
+            "default": "true",
+            "description": "Render secondary button as outlined"
+          },
+          {
+            "name": "secondaryDisabled",
+            "type": "boolean",
+            "required": false,
+            "default": "false",
+            "description": "Disable secondary button"
+          },
+          {
+            "name": "onSecondaryClick",
+            "type": "() => void",
+            "required": false,
+            "description": "Click handler for secondary button"
+          }
+        ],
+        "example": "import FormActionsBar from '@mantis-core/ui/components/Forms/FormActionsBar';\n\nfunction Example() {\n  return (\n    <FormActionsBar\n      primaryLabel='Save'\n      secondaryLabel='Cancel'\n      onPrimaryClick={() => {}}\n      onSecondaryClick={() => {}}\n    />\n  );\n}"
+      },
+      {
+        "name": "FormFieldRender",
+        "import": "@mantis-core/ui/components/Forms/FormFieldRender",
+        "category": "forms",
+        "whenToUse": "Composes a label, a render-prop input slot, and an inline ErrorMessage for one field; use to wrap a custom/non-Mantis input with the same label+error layout as the field wrappers.",
+        "props": [
+          {
+            "name": "name",
+            "type": "string",
+            "required": true,
+            "description": "RHF field name; forwarded to `render` and to the inline ErrorMessage."
+          },
+          {
+            "name": "label",
+            "type": "string | ReactElement",
+            "required": true
+          },
+          {
+            "name": "labelProps",
+            "type": "LabelHTMLAttributes<HTMLLabelElement>",
+            "required": false
+          },
+          {
+            "name": "containerClassName",
+            "type": "string",
+            "required": false
+          },
+          {
+            "name": "render",
+            "type": "({ name }: { name: string }) => ReactElement | ReactNode",
+            "required": true,
+            "description": "Renders the actual input; receives `name` to wire to your own Controller/register call."
+          }
+        ],
+        "example": "import FormFieldRender from '@mantis-core/ui/components/Forms/FormFieldRender';\nimport { Controller, FormProvider, useForm, type FieldValues } from 'react-hook-form';\n\nfunction Example() {\n  const methods = useForm<FieldValues>({ defaultValues: { email: '' } });\n  return (\n    <FormProvider {...methods}>\n      <FormFieldRender\n        name='email'\n        label='Email'\n        render={({ name }) => (\n          <Controller\n            name={name}\n            control={methods.control}\n            render={({ field }) => <input {...field} id={name} />}\n          />\n        )}\n      />\n    </FormProvider>\n  );\n}"
+      },
+      {
+        "name": "FormWizard",
+        "import": "@mantis-core/ui/components/Forms/FormWizard",
+        "category": "forms",
+        "whenToUse": "Multi-step form navigator with a PR11 Stepper step indicator and per-step field validation; must render inside a FormProvider, parent owns the <form onSubmit>.",
+        "props": [
+          {
+            "name": "steps",
+            "type": "FormWizardStep[]",
+            "required": true,
+            "description": "Each step: `{ label, fields?: string[], content: ReactNode }`. `fields` are validated (via `trigger`) before advancing."
+          },
+          {
+            "name": "onComplete",
+            "type": "() => void | Promise<void>",
+            "required": false,
+            "description": "Escape hatch for wizard usage outside a <form> element; when set, the final step's button uses type=\"button\" instead of \"submit\"."
+          },
+          {
+            "name": "submitLabel",
+            "type": "string",
+            "required": false,
+            "default": "'Finalizar'"
+          },
+          {
+            "name": "className",
+            "type": "string",
+            "required": false
+          }
+        ],
+        "example": "import FormWizard from '@mantis-core/ui/components/Forms/FormWizard';\nimport { FormProvider, useForm } from 'react-hook-form';\n\nfunction Example() {\n  const form = useForm({ defaultValues: { name: '', email: '' } });\n  return (\n    <FormProvider {...form}>\n      <form onSubmit={form.handleSubmit(() => {})}>\n        <FormWizard\n          steps={[\n            { label: 'Data', fields: ['name', 'email'], content: <div>Step 1</div> },\n            { label: 'Confirm', content: <div>Step 2</div> },\n          ]}\n          submitLabel='Save'\n        />\n      </form>\n    </FormProvider>\n  );\n}"
+      },
+      {
+        "name": "HiddenField",
+        "import": "@mantis-core/ui/components/Forms/HiddenField",
+        "category": "forms",
+        "whenToUse": "Registers a react-hook-form value with no visible UI.",
+        "props": [],
+        "example": "import { HiddenField } from '@mantis-core/ui/components/Forms/HiddenField';\nimport { useForm } from 'react-hook-form';\n\nfunction Example() {\n  const { control } = useForm({ defaultValues: { id: '' } });\n  return <HiddenField name='id' control={control} />;\n}"
+      },
+      {
+        "name": "MaskField",
+        "import": "@mantis-core/ui/components/Forms/MaskField",
+        "category": "forms",
+        "whenToUse": "Generic masked text input (digit/letter/alphanumeric tokens) wired to react-hook-form; value is the masked display string.",
+        "props": [
+          {
+            "name": "mask",
+            "type": "string",
+            "required": true,
+            "description": "Pattern: '9'=digit, 'a'=letter, '*'=alphanumeric; any other character is a literal emitted automatically."
+          }
+        ],
+        "example": "import { MaskField } from '@mantis-core/ui/components/Forms/MaskField';\nimport { useForm } from 'react-hook-form';\n\nfunction Example() {\n  const { control } = useForm({ defaultValues: { code: '' } });\n  return <MaskField name='code' control={control} mask='999-999' label='Code' />;\n}"
+      },
+      {
+        "name": "NumberField",
+        "import": "@mantis-core/ui/components/Forms/NumberField",
+        "category": "forms",
+        "whenToUse": "Numeric input (integer, decimal, or currency) wired to react-hook-form.",
+        "props": [
+          {
+            "name": "mode",
+            "type": "'decimal' | 'currency'",
+            "required": false,
+            "description": "PR11 InputNumber Root config. `currency` is the sole replacement for the removed CurrencyInput wrapper."
+          },
+          {
+            "name": "currency",
+            "type": "string",
+            "required": false,
+            "description": "ISO currency code, only used when mode=\"currency\" (e.g. \"USD\")."
+          },
+          {
+            "name": "locale",
+            "type": "string",
+            "required": false,
+            "description": "Intl locale for formatting."
+          },
+          {
+            "name": "min",
+            "type": "number",
+            "required": false
+          },
+          {
+            "name": "max",
+            "type": "number",
+            "required": false
+          },
+          {
+            "name": "step",
+            "type": "number",
+            "required": false
+          }
+        ],
+        "example": "import { NumberField } from '@mantis-core/ui/components/Forms/NumberField';\nimport { useForm } from 'react-hook-form';\n\nfunction Example() {\n  const { control } = useForm({ defaultValues: { price: null as number | null } });\n  return (\n    <NumberField name='price' control={control} label='Price' mode='currency' currency='USD' />\n  );\n}"
+      },
+      {
+        "name": "OtpInput",
+        "import": "@mantis-core/ui/components/Forms/OtpInput",
+        "category": "forms",
+        "whenToUse": "RHF-bound one-time-password input over PR11's compound InputOtp; renders `length` segmented boxes.",
+        "props": [
+          {
+            "name": "length",
+            "type": "number",
+            "required": false,
+            "default": "6",
+            "description": "How many segmented slots render."
+          },
+          {
+            "name": "integerOnly",
+            "type": "boolean",
+            "required": false,
+            "description": "Restrict input to digits."
+          },
+          {
+            "name": "mask",
+            "type": "boolean",
+            "required": false,
+            "description": "Obscure each slot like a password."
+          }
+        ],
+        "example": "import { OtpInput } from '@mantis-core/ui/components/Forms/OtpInput';\nimport { useForm } from 'react-hook-form';\n\nfunction Example() {\n  const { control } = useForm({ defaultValues: { code: '' } });\n  return <OtpInput name='code' control={control} label='Código' length={6} integerOnly />;\n}"
+      },
+      {
+        "name": "PasswordInput",
+        "import": "@mantis-core/ui/components/Forms/PasswordInput",
+        "category": "forms",
+        "whenToUse": "RHF-bound password field over PR11 InputPassword with a native show/hide toggle and a lightweight strength meter.",
+        "props": [
+          {
+            "name": "showToggle",
+            "type": "boolean",
+            "required": false,
+            "default": "true",
+            "description": "Renders the Eye/EyeSlash show/hide toggle."
+          },
+          {
+            "name": "feedback",
+            "type": "boolean",
+            "required": false,
+            "default": "true",
+            "description": "Renders the strength meter below the input."
+          }
+        ],
+        "example": "import { PasswordInput } from '@mantis-core/ui/components/Forms/PasswordInput';\nimport { useForm } from 'react-hook-form';\n\nfunction Example() {\n  const { control } = useForm({ defaultValues: { password: '' } });\n  return <PasswordInput name='password' control={control} label='Contraseña' rules={{ required: true }} />;\n}"
+      },
+      {
+        "name": "PhoneInput",
+        "import": "@mantis-core/ui/components/Forms/PhoneInput",
+        "category": "forms",
+        "whenToUse": "Phone-number preset of MaskField; defaults to a US-style (999) 999-9999 mask.",
+        "props": [
+          {
+            "name": "mask",
+            "type": "string",
+            "required": false,
+            "default": "'(999) 999-9999'",
+            "description": "Override the phone mask for other formats."
+          }
+        ],
+        "example": "import { PhoneInput } from '@mantis-core/ui/components/Forms/PhoneInput';\nimport { useForm } from 'react-hook-form';\n\nfunction Example() {\n  const { control } = useForm({ defaultValues: { phone: '' } });\n  return <PhoneInput name='phone' control={control} label='Teléfono' />;\n}"
+      },
+      {
+        "name": "RadioGroup",
+        "import": "@mantis-core/ui/components/Forms/RadioGroup",
+        "category": "forms",
+        "whenToUse": "Single-choice radio group over PR11's RadioButtonGroup; value is the selected option's value.",
+        "props": [
+          {
+            "name": "options",
+            "type": "Record<string, unknown>[]",
+            "required": true,
+            "description": "Option rows rendered as radio items."
+          },
+          {
+            "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": "renderOption",
+            "type": "(option: Record<string, unknown>, index: number) => ReactNode",
+            "required": false,
+            "description": "Escape hatch: full custom per-item label render."
+          }
+        ],
+        "example": "import { RadioGroup } from '@mantis-core/ui/components/Forms/RadioGroup';\nimport { useForm } from 'react-hook-form';\n\nconst PLANS = [\n  { label: 'Basic', value: 'basic' },\n  { label: 'Pro', value: 'pro' },\n];\n\nfunction Example() {\n  const { control } = useForm({ defaultValues: { plan: 'basic' } });\n  return (\n    <RadioGroup\n      name='plan'\n      control={control}\n      label='Plan'\n      options={PLANS}\n      optionLabel='label'\n      optionValue='value'\n    />\n  );\n}"
+      },
+      {
+        "name": "RangeSlider",
+        "import": "@mantis-core/ui/components/Forms/RangeSlider",
+        "category": "forms",
+        "whenToUse": "RHF-bound slider over PR11's compound Slider; single-handle by default, dual-handle range when the field holds a [number, number] tuple.",
+        "props": [
+          {
+            "name": "min",
+            "type": "number",
+            "required": false
+          },
+          {
+            "name": "max",
+            "type": "number",
+            "required": false
+          },
+          {
+            "name": "step",
+            "type": "number",
+            "required": false
+          },
+          {
+            "name": "orientation",
+            "type": "'horizontal' | 'vertical'",
+            "required": false
+          }
+        ],
+        "example": "import { RangeSlider } from '@mantis-core/ui/components/Forms/RangeSlider';\nimport { useForm } from 'react-hook-form';\n\nfunction Example() {\n  const { control } = useForm({ defaultValues: { price: 100 } });\n  return <RangeSlider name='price' control={control} label='Precio' min={0} max={500} />;\n}"
+      },
+      {
+        "name": "RatingInput",
+        "import": "@mantis-core/ui/components/Forms/RatingInput",
+        "category": "forms",
+        "whenToUse": "RHF-bound star rating over PR11's compound Rating; stores a numeric value.",
+        "props": [
+          {
+            "name": "stars",
+            "type": "number",
+            "required": false,
+            "default": "5",
+            "description": "How many star options render."
+          }
+        ],
+        "example": "import { RatingInput } from '@mantis-core/ui/components/Forms/RatingInput';\nimport { useForm } from 'react-hook-form';\n\nfunction Example() {\n  const { control } = useForm({ defaultValues: { score: null as number | null } });\n  return <RatingInput name='score' control={control} label='Puntaje' stars={5} />;\n}"
+      },
+      {
+        "name": "RenderField",
+        "import": "@mantis-core/ui/components/Forms/RenderField",
+        "category": "forms",
+        "whenToUse": "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.",
+        "props": [
+          {
+            "name": "name",
+            "type": "string",
+            "required": true
+          },
+          {
+            "name": "render",
+            "type": "(props: { field, fieldState, formState, value }) => ReactElement",
+            "required": true
+          },
+          {
+            "name": "defaultValue",
+            "type": "any",
+            "required": false
+          },
+          {
+            "name": "rules",
+            "type": "RegisterOptions",
+            "required": false
+          },
+          {
+            "name": "control",
+            "type": "Control",
+            "required": false
+          }
+        ],
+        "example": "import RenderField from '@mantis-core/ui/components/Forms/RenderField';\nimport { useForm, type FieldValues } from 'react-hook-form';\n\nfunction Example() {\n  const { control } = useForm<FieldValues>({ defaultValues: { rating: 0 } });\n  return (\n    <RenderField\n      name='rating'\n      control={control}\n      render={({ field }) => (\n        <input\n          type='number'\n          value={field.value}\n          onChange={(e) => field.onChange(Number(e.target.value))}\n        />\n      )}\n    />\n  );\n}"
+      },
+      {
+        "name": "SearchInput",
+        "import": "@mantis-core/ui/components/Forms/SearchInput",
+        "category": "forms",
+        "whenToUse": "RHF-bound search box over PR11 InputText with a search icon and a debounced onSearch callback; ideal for live table/list filtering.",
+        "props": [
+          {
+            "name": "onSearch",
+            "type": "(value: string) => void",
+            "required": false,
+            "description": "Fires debounced with the current value on each change."
+          },
+          {
+            "name": "debounceMs",
+            "type": "number",
+            "required": false,
+            "default": "300"
+          }
+        ],
+        "example": "import { SearchInput } from '@mantis-core/ui/components/Forms/SearchInput';\nimport { useForm } from 'react-hook-form';\n\nfunction Example() {\n  const { control } = useForm({ defaultValues: { q: '' } });\n  return <SearchInput name='q' control={control} label='Buscar' onSearch={(value) => console.log(value)} />;\n}"
+      },
+      {
+        "name": "SelectField",
+        "import": "@mantis-core/ui/components/Forms/SelectField",
+        "category": "forms",
+        "whenToUse": "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.",
+        "props": [
+          {
+            "name": "options",
+            "type": "Record<string, unknown>[]",
+            "required": true,
+            "description": "Option rows rendered in the popup."
+          },
+          {
+            "name": "optionLabel",
+            "type": "string",
+            "required": false,
+            "default": "'label'",
+            "description": "Key read for each option's display label."
+          },
+          {
+            "name": "optionValue",
+            "type": "string",
+            "required": false,
+            "description": "Key read for each option's bound value; falls back to the whole row."
+          },
+          {
+            "name": "multiple",
+            "type": "boolean",
+            "required": false,
+            "default": "false",
+            "description": "Array-value mode with in-popup filter + checkmark indicators; empty selection binds `[]`, never `null`."
+          },
+          {
+            "name": "placeholder",
+            "type": "string",
+            "required": false,
+            "description": "Trigger placeholder; suppressed automatically in floating label modes (ifta/float) when a label is set."
+          },
+          {
+            "name": "optionTemplate",
+            "type": "'default' | 'twoLine'",
+            "required": false,
+            "default": "'default'",
+            "description": "Named per-option render preset; 'twoLine' adds a second line from `descriptionField`."
+          },
+          {
+            "name": "descriptionField",
+            "type": "string",
+            "required": false,
+            "description": "Row key for the second line when optionTemplate is 'twoLine'."
+          },
+          {
+            "name": "renderOption",
+            "type": "(option: Record<string, unknown>, index: number) => ReactNode",
+            "required": false,
+            "description": "Escape hatch: full custom per-option render, overrides optionTemplate."
+          },
+          {
+            "name": "className",
+            "type": "string",
+            "required": false
+          }
+        ],
+        "example": "import { SelectField } from '@mantis-core/ui/components/Forms/SelectField';\nimport { useForm } from 'react-hook-form';\n\nconst CITIES = [\n  { label: 'Quito', value: 'UIO' },\n  { label: 'Cuenca', value: 'CUE' },\n];\n\nfunction Example() {\n  const { control } = useForm({ defaultValues: { city: null } });\n  return (\n    <SelectField\n      name='city'\n      control={control}\n      label='City'\n      options={CITIES}\n      optionLabel='label'\n      optionValue='value'\n    />\n  );\n}"
+      },
+      {
+        "name": "SwitchField",
+        "import": "@mantis-core/ui/components/Forms/SwitchField",
+        "category": "forms",
+        "whenToUse": "Boolean on/off toggle wired to react-hook-form.",
+        "props": [],
+        "example": "import { SwitchField } from '@mantis-core/ui/components/Forms/SwitchField';\nimport { useForm } from 'react-hook-form';\n\nfunction Example() {\n  const { control } = useForm({ defaultValues: { featured: false } });\n  return <SwitchField name='featured' control={control} label='Featured' />;\n}"
+      },
+      {
+        "name": "TagsInput",
+        "import": "@mantis-core/ui/components/Forms/TagsInput",
+        "category": "forms",
+        "whenToUse": "RHF-bound tag/chip input over PR11's compound InputTags; stores value as string[].",
+        "props": [
+          {
+            "name": "placeholder",
+            "type": "string",
+            "required": false,
+            "description": "Shown on the entry input only while no tags are present."
+          },
+          {
+            "name": "max",
+            "type": "number",
+            "required": false,
+            "description": "Max number of tags."
+          },
+          {
+            "name": "delimiter",
+            "type": "string | RegExp",
+            "required": false,
+            "description": "Extra character(s) that commit a tag besides Enter."
+          },
+          {
+            "name": "allowDuplicate",
+            "type": "boolean",
+            "required": false
+          }
+        ],
+        "example": "import { TagsInput } from '@mantis-core/ui/components/Forms/TagsInput';\nimport { useForm } from 'react-hook-form';\n\nfunction Example() {\n  const { control } = useForm({ defaultValues: { tags: [] as string[] } });\n  return <TagsInput name='tags' control={control} label='Etiquetas' placeholder='Agregar etiqueta...' />;\n}"
+      },
+      {
+        "name": "TextArea",
+        "import": "@mantis-core/ui/components/Forms/TextArea",
+        "category": "forms",
+        "whenToUse": "Multi-line text field wired to react-hook-form.",
+        "props": [
+          {
+            "name": "rows",
+            "type": "number",
+            "required": false,
+            "description": "Native <textarea> passthrough beyond FieldControllerProps."
+          }
+        ],
+        "example": "import { TextArea } from '@mantis-core/ui/components/Forms/TextArea';\nimport { useForm } from 'react-hook-form';\n\nfunction Example() {\n  const { control } = useForm({ defaultValues: { notes: '' } });\n  return <TextArea name='notes' control={control} label='Notes' rows={4} />;\n}"
+      },
+      {
+        "name": "TextField",
+        "import": "@mantis-core/ui/components/Forms/TextField",
+        "category": "forms",
+        "whenToUse": "Single-line text field wired to react-hook-form.",
+        "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": "import { TextField } from '@mantis-core/ui/components/Forms/TextField';\nimport { useForm } from 'react-hook-form';\n\nfunction Example() {\n  const { control } = useForm({ defaultValues: { title: '' } });\n  return <TextField name='title' control={control} label='Title' rules={{ required: true }} />;\n}"
+      },
+      {
+        "name": "ToggleInlineButton",
+        "import": "@mantis-core/ui/components/Forms/ToggleInlineButton",
+        "category": "forms",
+        "whenToUse": "Segmented single- or multi-choice control over PR11's ToggleButtonGroup; pass `multiple` for array-value mode.",
+        "props": [
+          {
+            "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": "import { ToggleInlineButton } from '@mantis-core/ui/components/Forms/ToggleInlineButton';\nimport { useForm } from 'react-hook-form';\n\nconst VIEWS = [\n  { label: 'List', value: 'list' },\n  { label: 'Grid', value: 'grid' },\n];\n\nfunction Example() {\n  const { control } = useForm({ defaultValues: { view: 'list' } });\n  return (\n    <ToggleInlineButton\n      name='view'\n      control={control}\n      label='View'\n      options={VIEWS}\n      optionLabel='label'\n      optionValue='value'\n    />\n  );\n}"
+      },
+      {
+        "name": "UploadFilesPreview",
+        "import": "@mantis-core/ui/components/Forms/UploadFilesPreview",
+        "category": "forms",
+        "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.",
+        "props": [
+          {
+            "name": "previews",
+            "type": "TItem[]",
+            "required": false,
+            "default": "[]",
+            "description": "Already-uploaded items to display in the preview grid"
+          },
+          {
+            "name": "onUploadFile",
+            "type": "(file: File) => Promise<TItem>",
+            "required": true,
+            "description": "Called per file; resolves to the stored item"
+          },
+          {
+            "name": "onFileUploaded",
+            "type": "(file: TItem) => void",
+            "required": true,
+            "description": "Called after each successful upload"
+          },
+          {
+            "name": "onRemoveFile",
+            "type": "(item: TItem) => void",
+            "required": true,
+            "description": "Called when user removes a preview item"
+          },
+          {
+            "name": "onReorder",
+            "type": "(items: TItem[]) => void",
+            "required": true,
+            "description": "Called after drag-to-reorder with new order"
+          },
+          {
+            "name": "accept",
+            "type": "string",
+            "required": false,
+            "default": "'image/*'",
+            "description": "Accepted MIME types for the file input"
+          },
+          {
+            "name": "disabled",
+            "type": "boolean",
+            "required": false,
+            "default": "false",
+            "description": "Disable uploads and interactions"
+          },
+          {
+            "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": "import UploadFilesPreview from '@mantis-core/ui/components/Forms/UploadFilesPreview';\n\nfunction Example() {\n  return (\n    <UploadFilesPreview\n      previews={[{ id: '1', fullUrl: 'https://example.com/photo.jpg' }]}\n      onUploadFile={async (file) => ({ id: file.name, fullUrl: URL.createObjectURL(file) })}\n      onFileUploaded={() => {}}\n      onRemoveFile={() => {}}\n      onReorder={() => {}}\n    />\n  );\n}"
+      },
+      {
+        "name": "useFieldController",
+        "import": "@mantis-core/ui/components/Forms/useFieldController",
+        "category": "forms",
+        "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).",
+        "props": [],
+        "example": "import { FieldShell } from '@mantis-core/ui/components/Forms/FieldShell';\nimport { useFieldController, type FieldControllerProps } from '@mantis-core/ui/components/Forms/useFieldController';\nimport { useForm, type FieldValues, type FieldPath } from 'react-hook-form';\n\nfunction RatingField<TFieldValues extends FieldValues, TName extends FieldPath<TFieldValues>>(\n  props: FieldControllerProps<TFieldValues, TName>,\n) {\n  const f = useFieldController<TFieldValues, TName>(props);\n  return (\n    <FieldShell id={f.id} label={props.label} errorMessage={f.errorMessage}>\n      <input\n        id={f.id}\n        type='number'\n        value={(f.field.value as number) ?? 0}\n        onChange={(e) => f.field.onChange(Number(e.target.value))}\n        onBlur={f.field.onBlur}\n        disabled={f.disabled}\n        {...f.aria}\n      />\n    </FieldShell>\n  );\n}\n\nfunction Example() {\n  const { control } = useForm({ defaultValues: { rating: 0 } });\n  return <RatingField name='rating' control={control} label='Rating' />;\n}"
+      }
+    ],
+    "tables": [
+      {
+        "name": "ActionColumn",
+        "import": "@mantis-core/ui/components/Tables/ActionColumn",
+        "category": "tables",
+        "whenToUse": "Factory that returns a row-action `ColumnDef` for MantisDataTable/PaginatedTable's `columns` array; each row's `body` renders a `MenuButton` populated by `items(row)`.",
+        "props": [
+          {
+            "name": "items",
+            "type": "(row: T) => ActionMenuItem[]",
+            "required": true,
+            "description": "First factory argument — produces the per-row menu entries."
+          },
+          {
+            "name": "label",
+            "type": "string",
+            "required": false,
+            "description": "Second argument (ActionColumnOptions): trigger button label."
+          },
+          {
+            "name": "icon",
+            "type": "string",
+            "required": false,
+            "description": "Second argument (ActionColumnOptions): trigger button icon (PrimeIcons class)."
+          }
+        ],
+        "example": "import { actionColumn } from '@mantis-core/ui/components/Tables/ActionColumn';\nimport { MantisDataTable } from '@mantis-core/ui/components/Tables/MantisDataTable';\nimport type { ColumnDef } from '@mantis-core/ui/components/Tables/columns';\n\ninterface Property {\n  id: string;\n  name: string;\n}\n\nfunction Example() {\n  const rows: Property[] = [{ id: '1', name: 'Casa Ceibos' }];\n  const columns: ColumnDef<Property>[] = [\n    { field: 'name', header: 'Name' },\n    actionColumn<Property>((p) => [\n      { label: 'Edit', icon: 'pi pi-pencil', route: `/properties/${p.id}/edit` },\n      { label: 'Delete', icon: 'pi pi-trash', command: () => console.log(p.id) },\n    ]),\n  ];\n  return <MantisDataTable rows={rows} columns={columns} />;\n}"
+      },
+      {
+        "name": "FilterPannel",
+        "import": "@mantis-core/ui/components/Tables/FilterPannel",
+        "category": "tables",
+        "whenToUse": "Slide-in filter sidebar for tables; wraps RHF-bound filter fields in their own `FormProvider` and calls `onApplyFilter` with the cleaned form data.",
+        "props": [
+          {
+            "name": "onApplyFilter",
+            "type": "(data: T) => Promise<void>",
+            "required": true,
+            "description": "Called with the cleaned form data on submit (Aplicar), or `{}` on reset (Restaurar)."
+          }
+        ],
+        "example": "import FilterPannel from '@mantis-core/ui/components/Tables/FilterPannel';\nimport TableFilterField from '@mantis-core/ui/components/table-filter-field';\nimport { useFormContext } from 'react-hook-form';\n\ninterface Filters {\n  search: string;\n}\n\nfunction SearchField() {\n  const { register } = useFormContext<Filters>();\n  return (\n    <TableFilterField label='Search' htmlFor='search'>\n      <input id='search' {...register('search')} />\n    </TableFilterField>\n  );\n}\n\nfunction Example() {\n  const onApplyFilter = async (data: Filters) => console.log(data);\n  return (\n    <FilterPannel<Filters> onApplyFilter={onApplyFilter}>\n      <SearchField />\n    </FilterPannel>\n  );\n}"
+      },
+      {
+        "name": "IndexColumn",
+        "import": "@mantis-core/ui/components/Tables/IndexColumn",
+        "category": "tables",
+        "whenToUse": "Factory that returns a 1-based row-number `ColumnDef` for MantisDataTable/PaginatedTable's `columns` array.",
+        "props": [
+          {
+            "name": "overrides",
+            "type": "Partial<ColumnDef<T>>",
+            "required": false,
+            "description": "Overrides merged onto the default index ColumnDef (field/header/width/body)."
+          }
+        ],
+        "example": "import { indexColumn } from '@mantis-core/ui/components/Tables/IndexColumn';\nimport { MantisDataTable } from '@mantis-core/ui/components/Tables/MantisDataTable';\nimport type { ColumnDef } from '@mantis-core/ui/components/Tables/columns';\n\ninterface Property {\n  id: string;\n  name: string;\n}\n\nfunction Example() {\n  const rows: Property[] = [{ id: '1', name: 'Casa Ceibos' }];\n  const columns: ColumnDef<Property>[] = [indexColumn<Property>({ width: '3rem' }), { field: 'name', header: 'Name' }];\n  return <MantisDataTable rows={rows} columns={columns} />;\n}"
+      },
+      {
+        "name": "MantisDataTable",
+        "import": "@mantis-core/ui/components/Tables/MantisDataTable",
+        "category": "tables",
+        "whenToUse": "The 90% shortcut over PR11's compound DataTable — one flat `columns: ColumnDef[]` array renders the whole TableContainer→Table→THead→TBody→EmptyTBody tree with striped rows + gridlines. Default table for any grid; drop to `PaginatedTable` for pagination + index/action columns baked in.",
+        "props": [
+          {
+            "name": "rows",
+            "type": "T[]",
+            "required": true,
+            "description": "Row data (PR11's `data`, renamed since PR11 root's own `rows` means page size)."
+          },
+          {
+            "name": "columns",
+            "type": "ColumnDef<T>[]",
+            "required": true,
+            "description": "Flat column descriptor array — see ColumnDef shape below."
+          },
+          {
+            "name": "rowsPerPage",
+            "type": "number",
+            "required": false,
+            "description": "Forwarded to PR11 Root's `rows` (page size). Only relevant with `paginator`."
+          },
+          {
+            "name": "selectable",
+            "type": "boolean",
+            "required": false,
+            "default": "false",
+            "description": "Prepends a checkbox selection column. Requires `selectionMode` on the passthrough root props."
+          },
+          {
+            "name": "emptyMessage",
+            "type": "ReactNode",
+            "required": false,
+            "default": "'No records'"
+          },
+          {
+            "name": "filters",
+            "type": "Record<string, string>",
+            "required": false,
+            "description": "Current per-field filter values (page-owned state, not RHF)."
+          },
+          {
+            "name": "onFilterChange",
+            "type": "(field: string, value: string) => void",
+            "required": false,
+            "description": "Fires when a header filter control (text/dropdown preset or custom filterElement) changes."
+          }
+        ],
+        "example": "import { MantisDataTable } from '@mantis-core/ui/components/Tables/MantisDataTable';\nimport { currencyCell, badgeCell } from '@mantis-core/ui/components/Tables/cell-presets';\nimport type { ColumnDef } from '@mantis-core/ui/components/Tables/columns';\n\ninterface Property {\n  id: string;\n  name: string;\n  price: number;\n  status: string;\n}\n\nconst COLUMNS: ColumnDef<Property>[] = [\n  { field: 'name', header: 'Name', sortable: true, filter: 'text' },\n  { field: 'price', header: 'Price', cell: currencyCell({ currency: 'USD' }) },\n  {\n    field: 'status',\n    header: 'Status',\n    cell: badgeCell({ styles: { active: 'bg-green-100 text-green-700' } }),\n    filter: 'dropdown',\n    filterOptions: [\n      { label: 'Active', value: 'active' },\n      { label: 'Draft', value: 'draft' },\n    ],\n  },\n];\n\nfunction Example() {\n  const rows: Property[] = [{ id: '1', name: 'Casa Ceibos', price: 125000, status: 'active' }];\n  return <MantisDataTable rows={rows} columns={COLUMNS} emptyMessage='No properties yet' />;\n}"
+      },
+      {
+        "name": "MenuButton",
+        "import": "@mantis-core/ui/components/Tables/MenuButton",
+        "category": "tables",
+        "whenToUse": "Row-action overlay menu — a trigger button that opens a popup list of actions; used inside `actionColumn`/table row cells, or standalone.",
+        "props": [
+          {
+            "name": "label",
+            "type": "string",
+            "required": false,
+            "description": "Trigger button label."
+          },
+          {
+            "name": "icon",
+            "type": "string",
+            "required": false,
+            "default": "'pi pi-cog'",
+            "description": "Trigger button icon (PrimeIcons class)."
+          },
+          {
+            "name": "items",
+            "type": "ActionMenuItem[]",
+            "required": false,
+            "default": "[]"
+          }
+        ],
+        "example": "import MenuButton, { type ActionMenuItem } from '@mantis-core/ui/components/Tables/MenuButton';\n\nfunction Example() {\n  const items: ActionMenuItem[] = [\n    { label: 'Edit', icon: 'pi pi-pencil', route: '/properties/1/edit' },\n    { label: 'Delete', icon: 'pi pi-trash', command: () => console.log('delete') },\n  ];\n  return <MenuButton items={items} label='Actions' />;\n}"
+      },
+      {
+        "name": "MultiSelectFilter",
+        "import": "@mantis-core/ui/components/Tables/filters/MultiSelectFilter",
+        "category": "tables",
+        "whenToUse": "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.",
+        "props": [
+          {
+            "name": "options",
+            "type": "FilterOption[]",
+            "required": true
+          },
+          {
+            "name": "value",
+            "type": "string[]",
+            "required": false,
+            "default": "[]"
+          },
+          {
+            "name": "onChange",
+            "type": "(value: string[]) => void",
+            "required": true
+          },
+          {
+            "name": "loading",
+            "type": "boolean",
+            "required": false,
+            "default": "false",
+            "description": "Disables the control while the option list loads."
+          },
+          {
+            "name": "placeholder",
+            "type": "string",
+            "required": false,
+            "default": "'Seleccione'"
+          }
+        ],
+        "example": "import MultiSelectFilter from '@mantis-core/ui/components/Tables/filters/MultiSelectFilter';\nimport { useState } from 'react';\n\nfunction Example() {\n  const [selected, setSelected] = useState<string[]>([]);\n  const options = [\n    { label: 'Active', value: 'active' },\n    { label: 'Draft', value: 'draft' },\n  ];\n  return <MultiSelectFilter options={options} value={selected} onChange={setSelected} />;\n}"
+      },
+      {
+        "name": "PaginatedTable",
+        "import": "@mantis-core/ui/components/Tables/PaginatedTable",
+        "category": "tables",
+        "whenToUse": "Thin preset over MantisDataTable with `paginator` on by default plus optional index/action columns — the default table shell for admin list pages.",
+        "props": [
+          {
+            "name": "rows",
+            "type": "T[]",
+            "required": true
+          },
+          {
+            "name": "columns",
+            "type": "ColumnDef<T>[]",
+            "required": true
+          },
+          {
+            "name": "paginator",
+            "type": "boolean",
+            "required": false,
+            "default": "true",
+            "description": "PR11 Root prop; PaginatedTable flips the MantisDataTable default on."
+          },
+          {
+            "name": "showIndexColumn",
+            "type": "boolean",
+            "required": false,
+            "default": "true",
+            "description": "Prepend a 1-based row-number column."
+          },
+          {
+            "name": "indexColumnOptions",
+            "type": "Partial<ColumnDef<T>>",
+            "required": false,
+            "description": "Overrides for the prepended index column."
+          },
+          {
+            "name": "showActionColumn",
+            "type": "boolean",
+            "required": false,
+            "default": "false",
+            "description": "Append a row-action menu column."
+          },
+          {
+            "name": "actionColumnItems",
+            "type": "(row: T) => ActionMenuItem[]",
+            "required": false,
+            "description": "Per-row action items for the appended action column."
+          },
+          {
+            "name": "actionColumnOptions",
+            "type": "ActionColumnOptions<T>",
+            "required": false,
+            "description": "Overrides for the appended action column."
+          }
+        ],
+        "example": "import { PaginatedTable } from '@mantis-core/ui/components/Tables/PaginatedTable';\nimport type { ColumnDef } from '@mantis-core/ui/components/Tables/columns';\n\ninterface Property {\n  id: string;\n  name: string;\n}\n\nconst COLUMNS: ColumnDef<Property>[] = [{ field: 'name', header: 'Name' }];\n\nfunction Example() {\n  const rows: Property[] = [{ id: '1', name: 'Casa Ceibos' }];\n  return (\n    <PaginatedTable\n      rows={rows}\n      columns={COLUMNS}\n      rowsPerPage={10}\n      showActionColumn\n      actionColumnItems={(p) => [{ label: 'Edit', route: `/properties/${p.id}/edit` }]}\n    />\n  );\n}"
+      },
+      {
+        "name": "TableFilterField",
+        "import": "@mantis-core/ui/components/table-filter-field",
+        "category": "tables",
+        "whenToUse": "Wraps a form control with a `<label>` inside a `FilterPannel`, providing consistent layout.",
+        "props": [
+          {
+            "name": "label",
+            "type": "ReactNode",
+            "required": true
+          },
+          {
+            "name": "htmlFor",
+            "type": "string",
+            "required": true
+          },
+          {
+            "name": "className",
+            "type": "string",
+            "required": false
+          },
+          {
+            "name": "labelClassName",
+            "type": "string",
+            "required": false
+          }
+        ],
+        "example": "import TableFilterField from '@mantis-core/ui/components/table-filter-field';\n\nfunction Example() {\n  return (\n    <TableFilterField label='Status' htmlFor='filter-status'>\n      <select id='filter-status'>\n        <option value='active'>Active</option>\n      </select>\n    </TableFilterField>\n  );\n}"
+      },
+      {
+        "name": "TableToolbar",
+        "import": "@mantis-core/ui/components/table-toolbar",
+        "category": "tables",
+        "whenToUse": "Header bar above a table showing title, record-count meta, and an action buttons slot.",
+        "props": [
+          {
+            "name": "title",
+            "type": "ReactNode",
+            "required": false
+          },
+          {
+            "name": "totalRecords",
+            "type": "number",
+            "required": false,
+            "description": "When `meta` is omitted, renders as \"{n} registros disponibles\"."
+          },
+          {
+            "name": "meta",
+            "type": "ReactNode",
+            "required": false,
+            "description": "Overrides the auto-generated `totalRecords` copy."
+          },
+          {
+            "name": "actions",
+            "type": "ReactNode",
+            "required": false
+          },
+          {
+            "name": "className",
+            "type": "string",
+            "required": false
+          },
+          {
+            "name": "copyClassName",
+            "type": "string",
+            "required": false,
+            "description": "Extra class on the title+meta wrapper."
+          },
+          {
+            "name": "actionsClassName",
+            "type": "string",
+            "required": false,
+            "description": "Extra class on the actions wrapper."
+          }
+        ],
+        "example": "import TableToolbar from '@mantis-core/ui/components/table-toolbar';\nimport Button from '@mantis-core/ui/components/Buttons/Button';\n\nfunction Example() {\n  return <TableToolbar title='Users' totalRecords={42} actions={<Button label='New' />} />;\n}"
+      }
+    ],
+    "pages": [
+      {
+        "name": "AdminPageConfigurator",
+        "import": "@mantis-core/ui/components/pages/admin-layout/AdminPageConfigurator",
+        "category": "pages",
+        "whenToUse": "Sets the page title, description, breadcrumbs, and actions in the admin layout shell via context; wrap each page's content with this.",
+        "props": [
+          {
+            "name": "config",
+            "type": "AdminPageLayoutConfig",
+            "required": true,
+            "description": "{ title?, description?, breadcrumbs?, actions?, hideHeader? }"
+          },
+          {
+            "name": "children",
+            "type": "ReactNode",
+            "required": true
+          }
+        ],
+        "example": "import AdminPageConfigurator from '@mantis-core/ui/components/pages/admin-layout/AdminPageConfigurator';\nimport { AdminPageLayoutProvider } from '@mantis-core/ui';\n\nfunction Example() {\n  return (\n    <AdminPageLayoutProvider>\n      <AdminPageConfigurator\n        config={{\n          title: 'Properties',\n          description: 'Manage listings',\n          breadcrumbs: [{ label: 'Home', href: '/' }, { label: 'Properties' }],\n        }}>\n        <div>Properties view</div>\n      </AdminPageConfigurator>\n    </AdminPageLayoutProvider>\n  );\n}"
+      },
+      {
+        "name": "AdminPageHeader",
+        "import": "@mantis-core/ui/components/pages/AdminPageHeader",
+        "category": "pages",
+        "whenToUse": "Gradient page header with title, optional description, breadcrumbs, and a right-side actions slot; rendered by AdminPageLayoutShell — avoid rendering directly inside feature views.",
+        "props": [
+          {
+            "name": "title",
+            "type": "string",
+            "required": true
+          },
+          {
+            "name": "description",
+            "type": "string",
+            "required": false
+          },
+          {
+            "name": "actions",
+            "type": "ReactNode",
+            "required": false
+          },
+          {
+            "name": "breadcrumbs",
+            "type": "readonly AdminBreadcrumbItem[]",
+            "required": false
+          }
+        ],
+        "example": "import AdminPageHeader from '@mantis-core/ui/components/pages/AdminPageHeader';\nimport Button from '@mantis-core/ui/components/Buttons/Button';\n\nfunction Example() {\n  return (\n    <AdminPageHeader\n      title='Blog'\n      description='Manage posts'\n      actions={<Button label='New Post' onClick={() => {}} />}\n    />\n  );\n}"
+      },
+      {
+        "name": "AdminPageLayoutShell",
+        "import": "@mantis-core/ui/components/pages/admin-layout/AdminPageLayoutShell",
+        "category": "pages",
+        "whenToUse": "Root layout shell for admin pages; renders AdminPageHeader from context set by AdminPageConfigurator and provides the page grid/max-width.",
+        "props": [
+          {
+            "name": "children",
+            "type": "ReactNode",
+            "required": true
+          }
+        ],
+        "example": "import AdminPageLayoutShell from '@mantis-core/ui/components/pages/admin-layout/AdminPageLayoutShell';\nimport { AdminPageLayoutProvider } from '@mantis-core/ui';\n\nfunction Example() {\n  return (\n    <AdminPageLayoutProvider>\n      <AdminPageLayoutShell>\n        <div>Page content</div>\n      </AdminPageLayoutShell>\n    </AdminPageLayoutProvider>\n  );\n}"
+      },
+      {
+        "name": "AppShell",
+        "import": "@mantis-core/ui/components/pages/app-shell/AppShell",
+        "category": "pages",
+        "whenToUse": "Full-page app shell with responsive sidebar nav, topbar, and mobile drawer; use as the root layout wrapper for authenticated pages.",
+        "props": [
+          {
+            "name": "navItems",
+            "type": "AppNavItem[]",
+            "required": true,
+            "description": "Each item: { label, href?, icon?, children? }. Items with children render as a collapsible group."
+          },
+          {
+            "name": "children",
+            "type": "ReactNode",
+            "required": true
+          },
+          {
+            "name": "brand",
+            "type": "ReactNode",
+            "required": false,
+            "description": "Logo/name slot rendered in the sidebar header and mobile topbar."
+          },
+          {
+            "name": "topbarActions",
+            "type": "ReactNode",
+            "required": false
+          },
+          {
+            "name": "user",
+            "type": "ReactNode",
+            "required": false,
+            "description": "Rendered at the end of the topbar."
+          },
+          {
+            "name": "footer",
+            "type": "ReactNode",
+            "required": false,
+            "description": "Rendered at the bottom of the sidebar and mobile drawer."
+          },
+          {
+            "name": "collapsible",
+            "type": "boolean",
+            "required": false,
+            "default": false,
+            "description": "Enables a toggle button to collapse the desktop sidebar to icons-only."
+          },
+          {
+            "name": "defaultCollapsed",
+            "type": "boolean",
+            "required": false,
+            "default": false
+          }
+        ],
+        "example": "import AppShell from '@mantis-core/ui/components/pages/app-shell/AppShell';\n\nfunction Example() {\n  return (\n    <AppShell\n      navItems={[\n        { label: 'Dashboard', href: '/admin' },\n        { label: 'Properties', href: '/admin/properties' },\n      ]}\n      brand={<span>Atlas</span>}>\n      <div>Page content</div>\n    </AppShell>\n  );\n}"
+      },
+      {
+        "name": "Breadcrumbs",
+        "import": "@mantis-core/ui/components/pages/app-shell/Breadcrumbs",
+        "category": "pages",
+        "whenToUse": "Standalone breadcrumb nav; renders nothing when items is empty.",
+        "props": [
+          {
+            "name": "items",
+            "type": "readonly AdminBreadcrumbItem[]",
+            "required": true,
+            "description": "Each item: { label, href? }. The last item never links even if it has an href."
+          }
+        ],
+        "example": "import Breadcrumbs from '@mantis-core/ui/components/pages/app-shell/Breadcrumbs';\n\nfunction Example() {\n  return <Breadcrumbs items={[{ label: 'Home', href: '/' }, { label: 'Settings' }]} />;\n}"
+      },
+      {
+        "name": "FormSection",
+        "import": "@mantis-core/ui/components/pages/FormSection",
+        "category": "pages",
+        "whenToUse": "Bordered card section with a header (title + description + icon) and a padded body; groups related form fields.",
+        "props": [
+          {
+            "name": "title",
+            "type": "string",
+            "required": true
+          },
+          {
+            "name": "description",
+            "type": "string",
+            "required": false
+          },
+          {
+            "name": "icon",
+            "type": "ReactNode",
+            "required": false
+          },
+          {
+            "name": "children",
+            "type": "ReactNode",
+            "required": true
+          },
+          {
+            "name": "className",
+            "type": "string",
+            "required": false
+          }
+        ],
+        "example": "import FormSection from '@mantis-core/ui/components/pages/FormSection';\nimport { TextField } from '@mantis-core/ui/components/Forms/TextField';\nimport { useForm } from 'react-hook-form';\n\nfunction Example() {\n  const { control } = useForm({ defaultValues: { email: '' } });\n  return (\n    <FormSection title='Contact Info' description='Public contact details'>\n      <TextField name='email' control={control} label='Email' />\n    </FormSection>\n  );\n}"
+      },
+      {
+        "name": "PageTitle",
+        "import": "@mantis-core/ui/components/pages/PageTitle",
+        "category": "pages",
+        "whenToUse": "Centered display-font heading for public-facing pages.",
+        "props": [
+          {
+            "name": "children",
+            "type": "ReactNode",
+            "required": true
+          }
+        ],
+        "example": "import PageTitle from '@mantis-core/ui/components/pages/PageTitle';\n\nfunction Example() {\n  return <PageTitle>Propiedades en Venta</PageTitle>;\n}"
+      }
+    ],
+    "maps": [
+      {
+        "name": "MapPicker",
+        "import": "@mantis-core/ui/components/Maps/MapPicker",
+        "category": "maps",
+        "whenToUse": "SSR-safe entry point for the Leaflet lat/lng picker; lazy-loads MapPickerClient via next/dynamic (ssr:false).",
+        "props": [
+          {
+            "name": "onLocationSelect",
+            "type": "(lat: number, lng: number) => void",
+            "required": true,
+            "description": "Fired on map click with the picked coordinates."
+          },
+          {
+            "name": "initialLat",
+            "type": "number | null",
+            "required": false
+          },
+          {
+            "name": "initialLng",
+            "type": "number | null",
+            "required": false
+          }
+        ],
+        "example": "import { useState } from 'react';\nimport MapPicker from '@mantis-core/ui/components/Maps/MapPicker';\n\nfunction Example() {\n  const [coords, setCoords] = useState<{ lat: number; lng: number } | null>(null);\n\n  return (\n    <MapPicker\n      onLocationSelect={(lat, lng) => setCoords({ lat, lng })}\n      initialLat={-3.26}\n      initialLng={-79.28}\n    />\n  );\n}"
+      },
+      {
+        "name": "MapPickerClient",
+        "import": "@mantis-core/ui/components/Maps/MapPickerClient",
+        "category": "maps",
+        "whenToUse": "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.",
+        "props": [
+          {
+            "name": "onLocationSelect",
+            "type": "(lat: number, lng: number) => void",
+            "required": true,
+            "description": "Fired on map click with the picked coordinates."
+          },
+          {
+            "name": "initialLat",
+            "type": "number | null",
+            "required": false,
+            "description": "Initial marker/center latitude; defaults to a fixed Yunguilla-area center when omitted."
+          },
+          {
+            "name": "initialLng",
+            "type": "number | null",
+            "required": false,
+            "description": "Initial marker/center longitude; defaults to a fixed Yunguilla-area center when omitted."
+          }
+        ],
+        "example": "'use client';\nimport { useState } from 'react';\nimport MapPickerClient from '@mantis-core/ui/components/Maps/MapPickerClient';\n\nfunction Example() {\n  const [coords, setCoords] = useState<{ lat: number; lng: number } | null>(null);\n\n  return (\n    <MapPickerClient\n      onLocationSelect={(lat, lng) => setCoords({ lat, lng })}\n      initialLat={-3.26}\n      initialLng={-79.28}\n    />\n  );\n}"
+      },
+      {
+        "name": "MapPickerOSM",
+        "import": "@mantis-core/ui/components/Maps/MapPickerOSM",
+        "category": "maps",
+        "whenToUse": "Script-injected Leaflet map (no react-leaflet/SSR bundle cost) with a draggable marker and an explicit \"save location\" button.",
+        "props": [
+          {
+            "name": "initialPosition",
+            "type": "LatLng",
+            "required": false,
+            "default": "{ lat: -12.0464, lng: -77.0428 }",
+            "description": "Initial marker/center position."
+          },
+          {
+            "name": "zoom",
+            "type": "number",
+            "required": false,
+            "default": "12"
+          },
+          {
+            "name": "height",
+            "type": "string",
+            "required": false,
+            "default": "'400px'",
+            "description": "CSS height of the map container."
+          },
+          {
+            "name": "onChange",
+            "type": "(pos: LatLng) => void",
+            "required": false,
+            "description": "Fired on every click or marker drag."
+          },
+          {
+            "name": "onSave",
+            "type": "(pos: LatLng) => void",
+            "required": false,
+            "description": "Fired only when the user clicks the \"Guardar ubicación\" button."
+          }
+        ],
+        "example": "'use client';\nimport MapPickerOSM from '@mantis-core/ui/components/Maps/MapPickerOSM';\nimport type { LatLng } from '@mantis-core/ui/components/Maps/MapPickerOSM';\n\nfunction Example() {\n  const handleSave = (pos: LatLng) => console.log('saved', pos);\n\n  return <MapPickerOSM initialPosition={{ lat: -3.26, lng: -79.28 }} onSave={handleSave} />;\n}"
+      }
+    ],
+    "overlays": [
+      {
+        "name": "Drawer",
+        "import": "@mantis-core/ui/components/overlays/Drawer",
+        "category": "overlays",
+        "whenToUse": "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.",
+        "props": [
+          {
+            "name": "open",
+            "type": "boolean",
+            "required": true,
+            "description": "Controlled visibility."
+          },
+          {
+            "name": "onOpenChange",
+            "type": "(open: boolean) => void",
+            "required": true,
+            "description": "Fires with the next open value when the backdrop/close toggles it."
+          },
+          {
+            "name": "side",
+            "type": "'left' | 'right' | 'top' | 'bottom'",
+            "required": false,
+            "default": "'right'",
+            "description": "Edge the panel slides in from — maps to PR11 `position`."
+          },
+          {
+            "name": "title",
+            "type": "ReactNode",
+            "required": false,
+            "description": "Header title. Omit to render no header."
+          },
+          {
+            "name": "footer",
+            "type": "ReactNode",
+            "required": false,
+            "description": "Footer content. Omit to render no footer."
+          },
+          {
+            "name": "className",
+            "type": "string",
+            "required": false,
+            "description": "Extra class on the Popup element."
+          },
+          {
+            "name": "children",
+            "type": "ReactNode",
+            "required": false
+          }
+        ],
+        "example": "import Drawer from '@mantis-core/ui/components/overlays/Drawer';\nimport { useState } from 'react';\n\nfunction Example() {\n  const [open, setOpen] = useState(false);\n  return (\n    <Drawer open={open} onOpenChange={setOpen} side='right' title='Filters'>\n      <p>Filter form</p>\n    </Drawer>\n  );\n}"
+      },
+      {
+        "name": "Modal",
+        "import": "@mantis-core/ui/components/overlays/Modal",
+        "category": "overlays",
+        "whenToUse": "Controlled dialog/modal; composes PR11's headless Dialog compound (Root/Portal/Backdrop/Positioner/Popup/Header/Content/Footer) behind a simple `open`/`title`/`footer` API.",
+        "props": [
+          {
+            "name": "open",
+            "type": "boolean",
+            "required": true,
+            "description": "Controlled visibility."
+          },
+          {
+            "name": "onOpenChange",
+            "type": "(open: boolean) => void",
+            "required": true,
+            "description": "Fires with the next open value when the backdrop/close toggles it."
+          },
+          {
+            "name": "title",
+            "type": "ReactNode",
+            "required": false,
+            "description": "Header title. Omit to render no header."
+          },
+          {
+            "name": "footer",
+            "type": "ReactNode",
+            "required": false,
+            "description": "Footer content, usually action buttons. Omit to render no footer."
+          },
+          {
+            "name": "size",
+            "type": "'sm' | 'md' | 'lg' | 'xl'",
+            "required": false,
+            "default": "'md'",
+            "description": "Popup width preset."
+          },
+          {
+            "name": "modal",
+            "type": "boolean",
+            "required": false,
+            "default": "true",
+            "description": "Whether the dialog blocks pointer events behind it."
+          },
+          {
+            "name": "className",
+            "type": "string",
+            "required": false,
+            "description": "Extra class on the Popup element."
+          },
+          {
+            "name": "children",
+            "type": "ReactNode",
+            "required": false
+          }
+        ],
+        "example": "import Modal from '@mantis-core/ui/components/overlays/Modal';\nimport { useState } from 'react';\n\nfunction Example() {\n  const [open, setOpen] = useState(false);\n  return (\n    <Modal\n      open={open}\n      onOpenChange={setOpen}\n      title='Edit property'\n      size='lg'\n      footer={<button onClick={() => setOpen(false)}>Close</button>}>\n      <p>Modal content</p>\n    </Modal>\n  );\n}"
+      }
+    ],
+    "navigation": [
+      {
+        "name": "CommandPalette",
+        "import": "@mantis-core/ui/components/navigation/CommandPalette",
+        "category": "navigation",
+        "whenToUse": "Keyboard-driven command search overlay (Ctrl/Cmd+K); pair with the `useCommandPalette` hook to wire the shortcut.",
+        "props": [
+          {
+            "name": "commands",
+            "type": "{ id: string; label: string; icon?: ReactNode; keywords?: string[]; onSelect: () => void }[]",
+            "required": true
+          },
+          {
+            "name": "open",
+            "type": "boolean",
+            "required": false,
+            "default": "false"
+          },
+          {
+            "name": "onOpenChange",
+            "type": "(open: boolean) => void",
+            "required": false
+          }
+        ],
+        "example": "import CommandPalette, { useCommandPalette } from '@mantis-core/ui/components/navigation/CommandPalette';\nimport { useState } from 'react';\n\nfunction Example() {\n  const [open, setOpen] = useState(false);\n  useCommandPalette(() => setOpen(true));\n  return (\n    <CommandPalette\n      open={open}\n      onOpenChange={setOpen}\n      commands={[{ id: 'new', label: 'New property', onSelect: () => console.log('new') }]}\n    />\n  );\n}"
+      },
+      {
+        "name": "PageTabs",
+        "import": "@mantis-core/ui/components/navigation/PageTabs",
+        "category": "navigation",
+        "whenToUse": "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.",
+        "props": [
+          {
+            "name": "tabs",
+            "type": "{ label: string; icon?: ReactNode; href?: string; command?: () => void }[]",
+            "required": true
+          },
+          {
+            "name": "activeIndex",
+            "type": "number",
+            "required": false,
+            "description": "Forces the active tab index; otherwise derived from the pathname (matched against the tab `href`)."
+          },
+          {
+            "name": "className",
+            "type": "string",
+            "required": false,
+            "default": "'mantis-core-page-tabs'"
+          }
+        ],
+        "example": "import PageTabs from '@mantis-core/ui/components/navigation/PageTabs';\n\nfunction Example() {\n  return (\n    <PageTabs\n      tabs={[\n        { label: 'General', href: '/admin/settings' },\n        { label: 'Security', href: '/admin/settings/security' },\n      ]}\n    />\n  );\n}"
+      }
+    ],
+    "data": [
+      {
+        "name": "DescriptionList",
+        "import": "@mantis-core/ui/components/data/DescriptionList",
+        "category": "data",
+        "whenToUse": "Grid-based label/value list for detail views; supports 1, 2, or 3 columns.",
+        "props": [
+          {
+            "name": "items",
+            "type": "{ label: string; value: ReactNode }[]",
+            "required": true
+          },
+          {
+            "name": "columns",
+            "type": "1 | 2 | 3",
+            "required": false,
+            "default": "1"
+          }
+        ],
+        "example": "import DescriptionList from '@mantis-core/ui/components/data/DescriptionList';\n\nfunction Example() {\n  return (\n    <DescriptionList\n      columns={2}\n      items={[\n        { label: 'Name', value: 'Jane Doe' },\n        { label: 'Email', value: 'jane@example.com' },\n      ]}\n    />\n  );\n}"
+      },
+      {
+        "name": "StatCard",
+        "import": "@mantis-core/ui/components/data/StatCard",
+        "category": "data",
+        "whenToUse": "KPI card showing a metric label, large value, optional icon, trend indicator, and footer.",
+        "props": [
+          {
+            "name": "label",
+            "type": "string",
+            "required": true
+          },
+          {
+            "name": "value",
+            "type": "ReactNode",
+            "required": true
+          },
+          {
+            "name": "icon",
+            "type": "ReactNode",
+            "required": false
+          },
+          {
+            "name": "trend",
+            "type": "{ value: number; direction: 'up' | 'down' }",
+            "required": false
+          },
+          {
+            "name": "footer",
+            "type": "ReactNode",
+            "required": false
+          }
+        ],
+        "example": "import StatCard from '@mantis-core/ui/components/data/StatCard';\n\nfunction Example() {\n  return <StatCard label='Leads' value={142} trend={{ value: 12, direction: 'up' }} />;\n}"
+      },
+      {
+        "name": "Timeline",
+        "import": "@mantis-core/ui/components/data/Timeline",
+        "category": "data",
+        "whenToUse": "Vertical event timeline backed by the PR11 Timeline compound; items render a title, description, date, and optional icon/color.",
+        "props": [
+          {
+            "name": "items",
+            "type": "{ title: string; description?: string; date?: string; icon?: ReactNode; color?: string }[]",
+            "required": true
+          }
+        ],
+        "example": "import Timeline from '@mantis-core/ui/components/data/Timeline';\n\nfunction Example() {\n  return (\n    <Timeline\n      items={[\n        { title: 'Lead created', date: '2025-01-10', description: 'Web form' },\n        { title: 'Contacted', date: '2025-01-11' },\n      ]}\n    />\n  );\n}"
+      }
+    ],
+    "feedback": [
+      {
+        "name": "Avatar",
+        "import": "@mantis-core/ui/components/feedback/Avatar",
+        "category": "feedback",
+        "whenToUse": "User avatar that renders an image or auto-derived initials; composes the PR11 headless Avatar (Root/Image/Fallback).",
+        "props": [
+          {
+            "name": "name",
+            "type": "string",
+            "required": false,
+            "description": "Derives initials (first + last word) when no image/label is given."
+          },
+          {
+            "name": "image",
+            "type": "string",
+            "required": false,
+            "description": "Image source; when set, no fallback initials render."
+          },
+          {
+            "name": "label",
+            "type": "string",
+            "required": false,
+            "description": "Overrides the name-derived initials."
+          },
+          {
+            "name": "size",
+            "type": "'normal' | 'large' | 'xlarge'",
+            "required": false,
+            "default": "'normal'"
+          },
+          {
+            "name": "shape",
+            "type": "'circle' | 'square'",
+            "required": false,
+            "default": "'square'"
+          }
+        ],
+        "example": "import Avatar from '@mantis-core/ui/components/feedback/Avatar';\n\nfunction Example() {\n  return <Avatar name='Diego Condo' size='large' shape='circle' />;\n}"
+      },
+      {
+        "name": "CardSkeleton",
+        "import": "@mantis-core/ui/components/feedback/CardSkeleton",
+        "category": "feedback",
+        "whenToUse": "Animated skeleton for card-grid layouts while data loads; composes the PR11 Skeleton primitive.",
+        "props": [
+          {
+            "name": "count",
+            "type": "number",
+            "required": false,
+            "default": "3"
+          }
+        ],
+        "example": "import CardSkeleton from '@mantis-core/ui/components/feedback/CardSkeleton';\n\nfunction Example() {\n  return <CardSkeleton count={6} />;\n}"
+      },
+      {
+        "name": "ConfirmDialog",
+        "import": "@mantis-core/ui/components/ui/ConfirmDialog",
+        "category": "feedback",
+        "whenToUse": "Confirm/cancel dialog for destructive or non-trivial actions; composed from the migrated Modal + Button.",
+        "props": [
+          {
+            "name": "visible",
+            "type": "boolean",
+            "required": true
+          },
+          {
+            "name": "onConfirm",
+            "type": "() => void | Promise<void>",
+            "required": true
+          },
+          {
+            "name": "onCancel",
+            "type": "() => void",
+            "required": true
+          },
+          {
+            "name": "title",
+            "type": "ReactNode",
+            "required": false,
+            "default": "'Confirmar accion'"
+          },
+          {
+            "name": "message",
+            "type": "ReactNode",
+            "required": false,
+            "default": "'Esta accion no se puede deshacer.'"
+          },
+          {
+            "name": "icon",
+            "type": "ReactNode",
+            "required": false
+          },
+          {
+            "name": "confirmLabel",
+            "type": "string",
+            "required": false,
+            "default": "'Confirmar'"
+          },
+          {
+            "name": "cancelLabel",
+            "type": "string",
+            "required": false,
+            "default": "'Cancelar'"
+          },
+          {
+            "name": "confirmSeverity",
+            "type": "'primary' | 'info' | 'success' | 'warning' | 'danger'",
+            "required": false,
+            "default": "'danger'"
+          },
+          {
+            "name": "loading",
+            "type": "boolean",
+            "required": false,
+            "default": "false"
+          },
+          {
+            "name": "disabled",
+            "type": "boolean",
+            "required": false,
+            "default": "false"
+          },
+          {
+            "name": "className",
+            "type": "string",
+            "required": false
+          }
+        ],
+        "example": "import ConfirmDialog from '@mantis-core/ui/components/ui/ConfirmDialog';\nimport { useState } from 'react';\n\nfunction Example() {\n  const [visible, setVisible] = useState(false);\n  return (\n    <ConfirmDialog\n      visible={visible}\n      title='Delete property?'\n      message='This cannot be undone.'\n      confirmSeverity='danger'\n      onConfirm={() => setVisible(false)}\n      onCancel={() => setVisible(false)}\n    />\n  );\n}"
+      },
+      {
+        "name": "DataState",
+        "import": "@mantis-core/ui/components/ui/DataState",
+        "category": "feedback",
+        "whenToUse": "Loading/empty/error/ready placeholder for data-fetching views; renders `children` unchanged when `status=\"ready\"`, otherwise a titled state panel.",
+        "props": [
+          {
+            "name": "status",
+            "type": "'ready' | 'loading' | 'empty' | 'error'",
+            "required": true
+          },
+          {
+            "name": "className",
+            "type": "string",
+            "required": false
+          },
+          {
+            "name": "children",
+            "type": "ReactNode",
+            "required": false,
+            "description": "Rendered as-is only when `status` is `\"ready\"`."
+          },
+          {
+            "name": "icon",
+            "type": "ReactNode",
+            "required": false,
+            "description": "Overrides the default per-status icon (spinner/inbox/triangle)."
+          },
+          {
+            "name": "loadingTitle",
+            "type": "ReactNode",
+            "required": false,
+            "default": "'Cargando informacion'"
+          },
+          {
+            "name": "loadingDescription",
+            "type": "ReactNode",
+            "required": false,
+            "default": "'Espera un momento mientras consultamos los datos.'"
+          },
+          {
+            "name": "emptyTitle",
+            "type": "ReactNode",
+            "required": false,
+            "default": "'Sin resultados'"
+          },
+          {
+            "name": "emptyDescription",
+            "type": "ReactNode",
+            "required": false,
+            "default": "'No hay registros para mostrar con los filtros actuales.'"
+          },
+          {
+            "name": "emptyAction",
+            "type": "ReactNode",
+            "required": false
+          },
+          {
+            "name": "errorTitle",
+            "type": "ReactNode",
+            "required": false,
+            "default": "'No se pudo cargar la informacion'"
+          },
+          {
+            "name": "errorDescription",
+            "type": "ReactNode",
+            "required": false,
+            "default": "'Ocurrio un error al consultar los datos.'"
+          },
+          {
+            "name": "errorAction",
+            "type": "ReactNode",
+            "required": false,
+            "description": "Overrides the default retry Button built from `onRetry`."
+          },
+          {
+            "name": "onRetry",
+            "type": "() => void",
+            "required": false,
+            "description": "Renders a default retry Button on `error` when `errorAction` is not given."
+          },
+          {
+            "name": "retryLabel",
+            "type": "string",
+            "required": false,
+            "default": "'Reintentar'"
+          }
+        ],
+        "example": "import DataState from '@mantis-core/ui/components/ui/DataState';\n\nfunction Example() {\n  return (\n    <DataState status='empty' emptyTitle='No properties found' emptyDescription='Try adjusting your filters.'>\n      <ul />\n    </DataState>\n  );\n}"
+      },
+      {
+        "name": "EmptyState",
+        "import": "@mantis-core/ui/components/feedback/EmptyState",
+        "category": "feedback",
+        "whenToUse": "Centered empty-state placeholder with icon, title, optional description, and action button.",
+        "props": [
+          {
+            "name": "title",
+            "type": "ReactNode",
+            "required": true
+          },
+          {
+            "name": "icon",
+            "type": "ReactNode",
+            "required": false
+          },
+          {
+            "name": "description",
+            "type": "ReactNode",
+            "required": false
+          },
+          {
+            "name": "action",
+            "type": "ReactNode",
+            "required": false
+          }
+        ],
+        "example": "import EmptyState from '@mantis-core/ui/components/feedback/EmptyState';\n\nfunction Example() {\n  return <EmptyState title='No properties yet' description='Create your first property to get started.' />;\n}"
+      },
+      {
+        "name": "ErrorBoundary",
+        "import": "@mantis-core/ui/components/feedback/ErrorBoundary",
+        "category": "feedback",
+        "whenToUse": "React class error boundary; renders fallback UI on uncaught render errors in its children.",
+        "props": [
+          {
+            "name": "children",
+            "type": "ReactNode",
+            "required": true
+          },
+          {
+            "name": "fallback",
+            "type": "ReactNode | ((error: Error) => ReactNode)",
+            "required": false
+          },
+          {
+            "name": "onError",
+            "type": "(error: Error, info: ErrorInfo) => void",
+            "required": false
+          }
+        ],
+        "example": "import ErrorBoundary from '@mantis-core/ui/components/feedback/ErrorBoundary';\n\nfunction Example() {\n  return (\n    <ErrorBoundary fallback={<p>Something went wrong.</p>}>\n      <div>Feature content</div>\n    </ErrorBoundary>\n  );\n}"
+      },
+      {
+        "name": "Loading",
+        "import": "@mantis-core/ui/components/Loaders/Loading",
+        "category": "feedback",
+        "whenToUse": "Full-screen loading overlay with a themed spinner; renders children unchanged when not loading.",
+        "props": [
+          {
+            "name": "loading",
+            "type": "boolean",
+            "required": false,
+            "default": "false"
+          },
+          {
+            "name": "texto",
+            "type": "string",
+            "required": false,
+            "default": "'Cargando...'"
+          },
+          {
+            "name": "className",
+            "type": "string",
+            "required": false
+          },
+          {
+            "name": "children",
+            "type": "ReactNode",
+            "required": false
+          }
+        ],
+        "example": "import Loading from '@mantis-core/ui/components/Loaders/Loading';\n\nfunction Example() {\n  return (\n    <Loading loading={true} texto='Loading...'>\n      <div>Page content</div>\n    </Loading>\n  );\n}"
+      },
+      {
+        "name": "Pagination",
+        "import": "@mantis-core/ui/components/ui/Pagination",
+        "category": "feedback",
+        "whenToUse": "Standalone page-number control (custom Tailwind markup, not PrimeReact Paginator); use when not relying on PaginatedTable's built-in paginator.",
+        "props": [
+          {
+            "name": "currentPage",
+            "type": "number",
+            "required": true
+          },
+          {
+            "name": "totalPages",
+            "type": "number",
+            "required": true
+          },
+          {
+            "name": "onPageChange",
+            "type": "(page: number) => void",
+            "required": true
+          },
+          {
+            "name": "hasNextPage",
+            "type": "boolean",
+            "required": false,
+            "default": "currentPage < totalPages"
+          },
+          {
+            "name": "hasPreviousPage",
+            "type": "boolean",
+            "required": false,
+            "default": "currentPage > 1"
+          },
+          {
+            "name": "maxVisible",
+            "type": "number",
+            "required": false,
+            "default": "7"
+          },
+          {
+            "name": "showFirstLast",
+            "type": "boolean",
+            "required": false,
+            "default": "true"
+          },
+          {
+            "name": "disabled",
+            "type": "boolean",
+            "required": false,
+            "default": "false"
+          },
+          {
+            "name": "className",
+            "type": "string",
+            "required": false
+          }
+        ],
+        "example": "import { Pagination } from '@mantis-core/ui/components/ui/Pagination';\nimport { useState } from 'react';\n\nfunction Example() {\n  const [page, setPage] = useState(1);\n  return <Pagination currentPage={page} totalPages={12} onPageChange={setPage} />;\n}"
+      },
+      {
+        "name": "RichTextPreview",
+        "import": "@mantis-core/ui/components/ui/RichTextPreview",
+        "category": "feedback",
+        "whenToUse": "Safely renders a CKEditor HTML string (sanitized by default) with CKEditor content styles applied.",
+        "props": [
+          {
+            "name": "html",
+            "type": "string | null",
+            "required": false,
+            "description": "HTML source. `null`/undefined is treated as empty."
+          },
+          {
+            "name": "className",
+            "type": "string",
+            "required": false
+          },
+          {
+            "name": "sanitize",
+            "type": "boolean",
+            "required": false,
+            "default": "true",
+            "description": "Runs the HTML through `sanitizeHtmlContent` (`@mantis-core/utils`) before rendering."
+          },
+          {
+            "name": "size",
+            "type": "'sm' | 'md' | 'lg'",
+            "required": false,
+            "default": "'md'"
+          },
+          {
+            "name": "emptyFallback",
+            "type": "ReactNode",
+            "required": false,
+            "default": "null",
+            "description": "Rendered instead when the (sanitized) content is empty/whitespace-only."
+          }
+        ],
+        "example": "import RichTextPreview from '@mantis-core/ui/components/ui/RichTextPreview';\n\nfunction Example() {\n  return <RichTextPreview html={'<p>Hello <strong>world</strong></p>'} size='md' />;\n}"
+      },
+      {
+        "name": "StatusBadge",
+        "import": "@mantis-core/ui/components/ui/StatusBadge",
+        "category": "feedback",
+        "whenToUse": "Colored pill badge to communicate a status with semantic tone (e.g. a lead or property status).",
+        "props": [
+          {
+            "name": "label",
+            "type": "ReactNode",
+            "required": false,
+            "description": "Takes precedence over `children` when both are given."
+          },
+          {
+            "name": "tone",
+            "type": "'success' | 'muted' | 'warning' | 'info' | 'danger'",
+            "required": false,
+            "default": "'muted'"
+          },
+          {
+            "name": "size",
+            "type": "'sm' | 'md'",
+            "required": false,
+            "default": "'md'"
+          },
+          {
+            "name": "block",
+            "type": "boolean",
+            "required": false,
+            "default": "false"
+          },
+          {
+            "name": "children",
+            "type": "ReactNode",
+            "required": false,
+            "description": "Fallback content when `label` is not given."
+          }
+        ],
+        "example": "import StatusBadge from '@mantis-core/ui/components/ui/StatusBadge';\n\nfunction Example() {\n  return <StatusBadge label='Active' tone='success' />;\n}"
+      },
+      {
+        "name": "TableSkeleton",
+        "import": "@mantis-core/ui/components/feedback/TableSkeleton",
+        "category": "feedback",
+        "whenToUse": "Animated skeleton placeholder that mimics a table grid while data loads; composes the PR11 Skeleton primitive.",
+        "props": [
+          {
+            "name": "rows",
+            "type": "number",
+            "required": false,
+            "default": "5"
+          },
+          {
+            "name": "columns",
+            "type": "number",
+            "required": false,
+            "default": "4"
+          }
+        ],
+        "example": "import TableSkeleton from '@mantis-core/ui/components/feedback/TableSkeleton';\n\nfunction Example() {\n  return <TableSkeleton rows={8} columns={5} />;\n}"
+      },
+      {
+        "name": "Tag",
+        "import": "@mantis-core/ui/components/feedback/Tag",
+        "category": "feedback",
+        "whenToUse": "Styled label chip for status labels, categories, or counts; wraps the PR11 Tag primitive.",
+        "props": [
+          {
+            "name": "children",
+            "type": "ReactNode",
+            "required": false,
+            "description": "Tag content — PR11 dropped value/icon; content is now children."
+          },
+          {
+            "name": "severity",
+            "type": "'secondary' | 'success' | 'info' | 'warn' | 'danger' | 'contrast'",
+            "required": false
+          },
+          {
+            "name": "rounded",
+            "type": "boolean",
+            "required": false,
+            "default": "false"
+          }
+        ],
+        "example": "import Tag from '@mantis-core/ui/components/feedback/Tag';\n\nfunction Example() {\n  return <Tag severity='success' rounded>Sold</Tag>;\n}"
+      }
+    ],
+    "auth": [
+      {
+        "name": "ChangePasswordForm",
+        "import": "@mantis-core/ui/components/auth/ChangePasswordForm",
+        "category": "auth",
+        "whenToUse": "Current + new + confirm password form for an authenticated user changing their own password.",
+        "props": [
+          {
+            "name": "onSubmit",
+            "type": "(values: ChangePasswordFormValues) => void | Promise<void>",
+            "required": true,
+            "description": "Receives { currentPassword, newPassword, confirmPassword }; form manages isSubmitting via RHF."
+          },
+          {
+            "name": "title",
+            "type": "string",
+            "required": false,
+            "default": "\"Cambiar contraseña\""
+          },
+          {
+            "name": "submitLabel",
+            "type": "string",
+            "required": false,
+            "default": "\"Actualizar contraseña\""
+          },
+          {
+            "name": "minPasswordLength",
+            "type": "number",
+            "required": false,
+            "default": "8",
+            "description": "Feeds minLengthRule for the newPassword field."
+          },
+          {
+            "name": "className",
+            "type": "string",
+            "required": false
+          }
+        ],
+        "example": "import ChangePasswordForm from '@mantis-core/ui/components/auth/ChangePasswordForm';\nimport type { ChangePasswordFormValues } from '@mantis-core/ui/components/auth/ChangePasswordForm';\n\nfunction Example() {\n  const handleSubmit = async (values: ChangePasswordFormValues) => {\n    await fetch('/api/auth/change-password', { method: 'POST', body: JSON.stringify(values) });\n  };\n\n  return <ChangePasswordForm onSubmit={handleSubmit} />;\n}"
+      },
+      {
+        "name": "ForgotPasswordForm",
+        "import": "@mantis-core/ui/components/auth/ForgotPasswordForm",
+        "category": "auth",
+        "whenToUse": "Email-only form to trigger a password-reset email; caller owns the actual reset request.",
+        "props": [
+          {
+            "name": "onSubmit",
+            "type": "(values: ForgotPasswordFormValues) => void | Promise<void>",
+            "required": true,
+            "description": "Receives { email }; form manages isSubmitting via RHF."
+          },
+          {
+            "name": "title",
+            "type": "string",
+            "required": false,
+            "default": "\"Recuperar contraseña\""
+          },
+          {
+            "name": "subtitle",
+            "type": "string",
+            "required": false
+          },
+          {
+            "name": "submitLabel",
+            "type": "string",
+            "required": false,
+            "default": "\"Enviar enlace\""
+          },
+          {
+            "name": "backSlot",
+            "type": "ReactNode",
+            "required": false,
+            "description": "Rendered below the submit button (e.g. a \"back to login\" link)."
+          },
+          {
+            "name": "className",
+            "type": "string",
+            "required": false
+          }
+        ],
+        "example": "import ForgotPasswordForm from '@mantis-core/ui/components/auth/ForgotPasswordForm';\nimport type { ForgotPasswordFormValues } from '@mantis-core/ui/components/auth/ForgotPasswordForm';\n\nfunction Example() {\n  const handleSubmit = async ({ email }: ForgotPasswordFormValues) => {\n    await fetch('/api/auth/forgot-password', { method: 'POST', body: JSON.stringify({ email }) });\n  };\n\n  return <ForgotPasswordForm onSubmit={handleSubmit} />;\n}"
+      },
+      {
+        "name": "LoginForm",
+        "import": "@mantis-core/ui/components/auth/LoginForm",
+        "category": "auth",
+        "whenToUse": "Self-contained login form (identifier + password) built on migrated TextField/PasswordInput/Button; pass onSubmit to wire signIn/Supabase from the app layer.",
+        "props": [
+          {
+            "name": "onSubmit",
+            "type": "(values: LoginFormValues) => void | Promise<void>",
+            "required": true,
+            "description": "Receives { identifier, password }; form manages isSubmitting via RHF."
+          },
+          {
+            "name": "brand",
+            "type": "ReactNode",
+            "required": false,
+            "description": "Rendered above the title."
+          },
+          {
+            "name": "title",
+            "type": "string",
+            "required": false,
+            "default": "\"Iniciar sesión\""
+          },
+          {
+            "name": "subtitle",
+            "type": "string",
+            "required": false
+          },
+          {
+            "name": "footer",
+            "type": "ReactNode",
+            "required": false,
+            "description": "Rendered below the submit button (e.g. forgot-password link)."
+          },
+          {
+            "name": "identifierField",
+            "type": "'email' | 'username'",
+            "required": false,
+            "default": "\"email\"",
+            "description": "Switches the identifier field's validation, type, and autoComplete between email and plain username."
+          },
+          {
+            "name": "identifierLabel",
+            "type": "string",
+            "required": false,
+            "description": "Overrides the default label (\"Correo electrónico\" / \"Usuario\") derived from identifierField."
+          },
+          {
+            "name": "identifierPlaceholder",
+            "type": "string",
+            "required": false
+          },
+          {
+            "name": "passwordLabel",
+            "type": "string",
+            "required": false,
+            "default": "\"Contraseña\""
+          },
+          {
+            "name": "passwordPlaceholder",
+            "type": "string",
+            "required": false
+          },
+          {
+            "name": "submitLabel",
+            "type": "string",
+            "required": false,
+            "default": "\"Ingresar\""
+          },
+          {
+            "name": "className",
+            "type": "string",
+            "required": false
+          }
+        ],
+        "example": "import LoginForm from '@mantis-core/ui/components/auth/LoginForm';\nimport type { LoginFormValues } from '@mantis-core/ui/components/auth/LoginForm';\n\nfunction Example() {\n  const handleSubmit = async (values: LoginFormValues) => {\n    await fetch('/api/auth/login', { method: 'POST', body: JSON.stringify(values) });\n  };\n\n  return <LoginForm onSubmit={handleSubmit} identifierField='email' />;\n}"
+      },
+      {
+        "name": "ResetPasswordForm",
+        "import": "@mantis-core/ui/components/auth/ResetPasswordForm",
+        "category": "auth",
+        "whenToUse": "New password + confirm-password form for a reset-token flow; caller owns token validation and the API call.",
+        "props": [
+          {
+            "name": "onSubmit",
+            "type": "(values: ResetPasswordFormValues) => void | Promise<void>",
+            "required": true,
+            "description": "Receives { newPassword, confirmPassword }; form manages isSubmitting via RHF."
+          },
+          {
+            "name": "title",
+            "type": "string",
+            "required": false,
+            "default": "\"Nueva contraseña\""
+          },
+          {
+            "name": "subtitle",
+            "type": "string",
+            "required": false
+          },
+          {
+            "name": "submitLabel",
+            "type": "string",
+            "required": false,
+            "default": "\"Guardar contraseña\""
+          },
+          {
+            "name": "minPasswordLength",
+            "type": "number",
+            "required": false,
+            "default": "8",
+            "description": "Feeds minLengthRule for the newPassword field."
+          },
+          {
+            "name": "className",
+            "type": "string",
+            "required": false
+          }
+        ],
+        "example": "import ResetPasswordForm from '@mantis-core/ui/components/auth/ResetPasswordForm';\nimport type { ResetPasswordFormValues } from '@mantis-core/ui/components/auth/ResetPasswordForm';\n\nfunction Example() {\n  const handleSubmit = async ({ newPassword }: ResetPasswordFormValues) => {\n    await fetch('/api/auth/reset-password', { method: 'POST', body: JSON.stringify({ newPassword }) });\n  };\n\n  return <ResetPasswordForm onSubmit={handleSubmit} minPasswordLength={10} />;\n}"
+      },
+      {
+        "name": "UserMenu",
+        "import": "@mantis-core/ui/components/auth/UserMenu",
+        "category": "auth",
+        "whenToUse": "Topbar avatar-triggered dropdown (custom nav items + sign-out); no auth-lib coupling.",
+        "props": [
+          {
+            "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": "import UserMenu from '@mantis-core/ui/components/auth/UserMenu';\n\nfunction Example() {\n  return (\n    <UserMenu\n      user={{ name: 'Diego Condo', email: 'diego@example.com' }}\n      items={[{ label: 'Perfil', icon: 'pi pi-user', href: '/perfil' }]}\n      onSignOut={() => console.log('sign out')}\n    />\n  );\n}"
+      }
+    ],
+    "buttons": [
+      {
+        "name": "Button",
+        "import": "@mantis-core/ui/components/Buttons/Button",
+        "category": "buttons",
+        "whenToUse": "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.",
+        "props": [
+          {
+            "name": "variant",
+            "type": "'primary' | 'secondary' | 'success' | 'warning' | 'error' | 'info' | 'gray' | 'danger'",
+            "required": false,
+            "default": "'primary'",
+            "description": "Maps to PR11 `severity`: `primary` = PR11 default (no severity), `gray`→`contrast`, `warning`→`warn`, `error`/`danger`→`danger`."
+          },
+          {
+            "name": "outlined",
+            "type": "boolean",
+            "required": false,
+            "default": "false",
+            "description": "PR11 `variant=\"outlined\"`."
+          },
+          {
+            "name": "text",
+            "type": "boolean",
+            "required": false,
+            "default": "false",
+            "description": "PR11 `variant=\"text\"`; wins over `outlined` when both are set."
+          },
+          {
+            "name": "block",
+            "type": "boolean",
+            "required": false,
+            "default": "false",
+            "description": "Full width — maps to PR11 `fluid`."
+          },
+          {
+            "name": "sm",
+            "type": "boolean",
+            "required": false,
+            "default": "false",
+            "description": "→ size='small'."
+          },
+          {
+            "name": "lg",
+            "type": "boolean",
+            "required": false,
+            "default": "false",
+            "description": "→ size='large'."
+          },
+          {
+            "name": "rounded",
+            "type": "boolean",
+            "required": false,
+            "default": "false"
+          },
+          {
+            "name": "label",
+            "type": "ReactNode",
+            "required": false,
+            "description": "Rendered as a child span — PR11 Button has no `label` prop."
+          },
+          {
+            "name": "icon",
+            "type": "string",
+            "required": false,
+            "description": "PrimeIcons class string, e.g. `pi pi-filter`; rendered before the label."
+          },
+          {
+            "name": "loading",
+            "type": "boolean",
+            "required": false,
+            "default": "false",
+            "description": "Shows a spinner icon and disables the button — PR11 Button has no `loading` prop."
+          },
+          {
+            "name": "href",
+            "type": "string",
+            "required": false,
+            "description": "Internal path; pushed with `next/navigation` router after `onClick` runs."
+          },
+          {
+            "name": "type",
+            "type": "'button' | 'submit' | 'reset'",
+            "required": false,
+            "default": "'button'"
+          },
+          {
+            "name": "disabled",
+            "type": "boolean",
+            "required": false
+          },
+          {
+            "name": "onClick",
+            "type": "(evt: MouseEvent<HTMLButtonElement>) => void",
+            "required": false
+          },
+          {
+            "name": "children",
+            "type": "ReactNode",
+            "required": false
+          }
+        ],
+        "example": "import Button from '@mantis-core/ui/components/Buttons/Button';\n\nfunction Example() {\n  return (\n    <Button\n      variant='danger'\n      outlined\n      label='Delete'\n      icon='pi pi-trash'\n      onClick={() => console.log('deleted')}\n    />\n  );\n}"
+      }
+    ],
+    "charts": [
+      {
+        "name": "BarChart",
+        "import": "@mantis-core/ui/components/charts/BarChart",
+        "category": "charts",
+        "whenToUse": "Categorical comparisons rendered as a bar chart, zero-config over chart.js defaults.",
+        "props": [
+          {
+            "name": "labels",
+            "type": "string[]",
+            "required": true
+          },
+          {
+            "name": "datasets",
+            "type": "BarChartDataset[]",
+            "required": true,
+            "description": "ChartDataset<'bar'> minus 'data', plus data: number[]."
+          },
+          {
+            "name": "options",
+            "type": "ChartOptions<'bar'>",
+            "required": false,
+            "description": "Deep-merged over defaultBarOptions (plugins/scales merge shallowly one level)."
+          },
+          {
+            "name": "colors",
+            "type": "string[]",
+            "required": false,
+            "default": "DEFAULT_COLORS (8-color palette)",
+            "description": "Applied per-dataset (cycled by index) to datasets that don't specify their own backgroundColor/borderColor."
+          },
+          {
+            "name": "height",
+            "type": "number",
+            "required": false,
+            "default": "300",
+            "description": "Container height in px."
+          },
+          {
+            "name": "className",
+            "type": "string",
+            "required": false
+          }
+        ],
+        "example": "import BarChart from '@mantis-core/ui/components/charts/BarChart';\n\nfunction Example() {\n  return (\n    <BarChart\n      labels={['Q1', 'Q2', 'Q3']}\n      datasets={[{ label: 'Sales', data: [40, 70, 55] }]}\n    />\n  );\n}"
+      },
+      {
+        "name": "DonutChart",
+        "import": "@mantis-core/ui/components/charts/DonutChart",
+        "category": "charts",
+        "whenToUse": "Part-to-whole breakdown rendered as a doughnut chart, zero-config over chart.js defaults.",
+        "props": [
+          {
+            "name": "labels",
+            "type": "string[]",
+            "required": true
+          },
+          {
+            "name": "datasets",
+            "type": "{ data: number[]; label?: string }[]",
+            "required": true,
+            "description": "Typically a single-entry array — one value per label/slice."
+          },
+          {
+            "name": "options",
+            "type": "ChartOptions<'doughnut'>",
+            "required": false,
+            "description": "Deep-merged over defaultDonutOptions (plugins merge shallowly one level)."
+          },
+          {
+            "name": "colors",
+            "type": "string[]",
+            "required": false,
+            "default": "DEFAULT_COLORS (8-color palette)",
+            "description": "Applied per-slice (cycled by label index) unless the dataset supplies its own backgroundColor/borderColor."
+          },
+          {
+            "name": "height",
+            "type": "number",
+            "required": false,
+            "default": "300",
+            "description": "Container height in px."
+          },
+          {
+            "name": "className",
+            "type": "string",
+            "required": false
+          }
+        ],
+        "example": "import DonutChart from '@mantis-core/ui/components/charts/DonutChart';\n\nfunction Example() {\n  return (\n    <DonutChart\n      labels={['Leads', 'Closed', 'Lost']}\n      datasets={[{ data: [60, 25, 15] }]}\n    />\n  );\n}"
+      },
+      {
+        "name": "LineChart",
+        "import": "@mantis-core/ui/components/charts/LineChart",
+        "category": "charts",
+        "whenToUse": "Time-series/trend data rendered as a line chart, zero-config over chart.js defaults.",
+        "props": [
+          {
+            "name": "labels",
+            "type": "string[]",
+            "required": true
+          },
+          {
+            "name": "datasets",
+            "type": "LineChartDataset[]",
+            "required": true,
+            "description": "ChartDataset<'line'> minus 'data', plus data: number[]."
+          },
+          {
+            "name": "options",
+            "type": "ChartOptions<'line'>",
+            "required": false,
+            "description": "Deep-merged over defaultLineOptions (plugins/scales merge shallowly one level)."
+          },
+          {
+            "name": "colors",
+            "type": "string[]",
+            "required": false,
+            "default": "DEFAULT_COLORS (8-color palette)",
+            "description": "Applied per-dataset (cycled by index) to datasets that don't specify their own borderColor/backgroundColor."
+          },
+          {
+            "name": "height",
+            "type": "number",
+            "required": false,
+            "default": "300",
+            "description": "Container height in px."
+          },
+          {
+            "name": "className",
+            "type": "string",
+            "required": false
+          }
+        ],
+        "example": "import LineChart from '@mantis-core/ui/components/charts/LineChart';\n\nfunction Example() {\n  return (\n    <LineChart\n      labels={['Jan', 'Feb', 'Mar']}\n      datasets={[{ label: 'Revenue', data: [100, 200, 150] }]}\n      height={250}\n    />\n  );\n}"
+      }
+    ]
+  }
+}