@mantis-core/ui 0.4.0 → 0.5.0

package/docs/components/confirm-dialog.md

@@ -1,21 +1,23 @@
-# ConfirmDialog
-
-- Export: `ConfirmDialog`
-- Extra exports: `ConfirmDialogProps`, `ConfirmDialogSeverity`
-- Import: `import { ConfirmDialog } from "@mantis-core/ui";`
-- Base library: `primereact/dialog`
-- Base typing: explicit `ConfirmDialogProps`
-- Required styles: `@mantis-core/styles/scss/confirm-dialog.scss`
-
+---
+name: ConfirmDialog
+category: feedback
+import: '@mantis-core/ui/components/ui/ConfirmDialog'
+whenToUse: Modal confirmation dialog with confirm/cancel buttons and severity-aware styling.
+baseLibrary: primereact/dialog
+requiredStyles: [scss/confirm-dialog.scss]
+relatedNextCore: []
+props:
+  - { name: visible, type: boolean, required: true }
+  - { name: onConfirm, type: '() => void', required: true }
+  - { name: onCancel, type: '() => void', required: true }
+  - { name: title, type: ReactNode, required: false }
+  - { name: message, type: ReactNode, required: false }
+  - { name: confirmSeverity, type: '''primary'' | ''info'' | ''success'' | ''warning'' | ''danger''', required: false, default: '''danger''' }
+  - { name: loading, type: boolean, required: false }
+  - { name: width, type: string, required: false, default: '''30rem''' }
+---
 ## Example
 
 ```tsx
-<ConfirmDialog
-  visible={open}
-  title="Delete listing"
-  message="This action cannot be undone."
-  confirmSeverity="danger"
-  onConfirm={handleDelete}
-  onCancel={() => setOpen(false)}
-/>
+<ConfirmDialog visible={showConfirm} title='Delete?' message='This cannot be undone.' confirmSeverity='danger' onConfirm={handleDelete} onCancel={() => setShowConfirm(false)} />
 ```

package/docs/components/currency-input.md

@@ -0,0 +1,21 @@
+---
+name: CurrencyInput
+category: forms
+import: '@mantis-core/ui/components/Forms/CurrencyInput'
+whenToUse: 'Numeric input pre-configured for currency display (mode=currency).'
+baseLibrary: custom
+formContract: ControllerProps
+requiredStyles: [scss/inputs.scss]
+relatedComponents: [FormFieldRender, NumberInput]
+relatedNextCore: []
+props:
+  - { name: controller, type: ControllerProps, required: true }
+  - { name: currency, type: string, required: false, default: '''USD''' }
+  - { name: locale, type: string, required: false, default: '''en-US''' }
+  - { name: block, type: boolean, required: false }
+---
+## Example
+
+```tsx
+<CurrencyInput controller={{ name: 'price' }} currency='USD' block />
+```

package/docs/components/data-state.md

@@ -1,19 +1,19 @@
-# DataState
-
-- Export: `DataState`
-- Extra exports: `DataStateProps`, `DataStateStatus`
-- Import: `import { DataState } from "@mantis-core/ui";`
-- Base library: custom state wrapper + `Button`
-- Base typing: explicit `DataStateProps`
-- Required styles: `@mantis-core/styles/scss/data-state.scss`
-
+---
+name: DataState
+category: feedback
+import: '@mantis-core/ui/components/ui/DataState'
+whenToUse: Full-area empty/error/loading state placeholder for data-fetching views.
+baseLibrary: custom
+requiredStyles: [scss/data-state.scss]
+relatedComponents: [StatusBadge, Loading]
+relatedNextCore: []
+props:
+  - { name: status, type: DataStateStatus, required: true }
+  - { name: message, type: string, required: false }
+  - { name: action, type: ReactNode, required: false }
+---
 ## Example
 
 ```tsx
-<DataState
-  status={query.isError ? "error" : query.isLoading ? "loading" : rows.length === 0 ? "empty" : "ready"}
-  onRetry={() => query.refetch()}
->
-  <PaginatedTable value={rows}>{/* columns */}</PaginatedTable>
-</DataState>
+<DataState status='empty' message='No properties found' action={<Button label='Add first' onClick={onCreate} />} />
 ```

package/docs/components/date-input.md

@@ -1,22 +1,21 @@
-# DateInput
-
-- Export: `DateInput`
-- Extra exports: `DateInputProps`
-- Import: `import { DateInput } from "@mantis-core/ui";`
-- Base library: `primereact/calendar`
-- Base typing: `Omit<CalendarProps, "name" | "defaultValue"> & { controller: ControllerProps; block?: boolean }`
-- Form contract: [`ControllerProps`](../contracts/controller-props.md)
-- Required styles:
-  - `@mantis-core/styles/scss/inputs.scss`
-  - `@mantis-core/styles/scss/date-picker.scss`
-
+---
+name: DateInput
+category: forms
+import: '@mantis-core/ui/components/Forms/DateInput'
+whenToUse: 'Single date picker (PrimeReact Calendar, locale=es, format=dd/mm/yy).'
+baseLibrary: primereact/calendar
+formContract: ControllerProps
+requiredStyles: [scss/inputs.scss]
+relatedComponents: [FormFieldRender, DateRangeInput]
+relatedNextCore: []
+props:
+  - { name: controller, type: ControllerProps, required: true }
+  - { name: block, type: boolean, required: false }
+  - { name: showTime, type: boolean, required: false }
+  - { name: minDate, type: Date, required: false }
+---
 ## Example
 
 ```tsx
-<DateInput
-  controller={{ name: "publishAt", control: form.control }}
-  block
-  showIcon
-  dateFormat="yy-mm-dd"
-/>
+<DateInput controller={{ name: 'publishedAt' }} block />
 ```

package/docs/components/date-presets.md

@@ -0,0 +1,18 @@
+---
+name: DatePresets
+category: forms
+import: '@mantis-core/ui/components/Forms/DatePresets'
+whenToUse: 'Row of preset buttons (Hoy, 7 días, 30 días, Este mes) that fire onChange with a [Date, Date] range; pair with DateRangeInput.'
+baseLibrary: custom
+relatedNextCore: []
+props:
+  - { name: onChange, type: '(range: [Date, Date]) => void', required: true }
+  - { name: presets, type: '{ label: string; resolve: () => [Date, Date] }[]', required: false }
+  - { name: disabled, type: boolean, required: false }
+  - { name: className, type: string, required: false }
+---
+## Example
+
+```tsx
+<DatePresets onChange={(range) => setValue('period', range)} />
+```

package/docs/components/date-range-input.md

@@ -0,0 +1,20 @@
+---
+name: DateRangeInput
+category: forms
+import: '@mantis-core/ui/components/Forms/DateRangeInput'
+whenToUse: 'Date range picker that stores [startDate, endDate] array; selectionMode is locked to ''range''.'
+baseLibrary: custom
+formContract: ControllerProps
+requiredStyles: [scss/inputs.scss]
+relatedComponents: [FormFieldRender, DateInput]
+relatedNextCore: []
+props:
+  - { name: controller, type: ControllerProps, required: true }
+  - { name: block, type: boolean, required: false }
+  - { name: showTime, type: boolean, required: false }
+---
+## Example
+
+```tsx
+<DateRangeInput controller={{ name: 'period' }} block />
+```

package/docs/components/description-list.md

@@ -0,0 +1,16 @@
+---
+name: DescriptionList
+category: data
+import: '@mantis-core/ui/components/data/DescriptionList'
+whenToUse: 'Grid-based label/value list for detail views; supports 1, 2, or 3 columns.'
+baseLibrary: custom
+relatedNextCore: []
+props:
+  - { name: items, type: '{ label: string; value: ReactNode }[]', required: true }
+  - { name: columns, type: '1 | 2 | 3', required: false, default: '1' }
+---
+## Example
+
+```tsx
+<DescriptionList columns={2} items={[{ label: 'Nombre', value: lead.name }, { label: 'Email', value: lead.email }]} />
+```

package/docs/components/dirty-form-guard.md

@@ -1,28 +1,20 @@
-# DirtyFormGuard and useDirtyFormGuard
-
-- Exports: `DirtyFormGuard`, `useDirtyFormGuard`
-- Extra exports: `DirtyFormGuardProps`, `UseDirtyFormGuardOptions`, `UseDirtyFormGuardResult`
-- Base library: browser `beforeunload` + `window.confirm`
-- Required styles: none
-
-## Component example
+---
+name: DirtyFormGuard
+category: forms
+import: '@mantis-core/ui/components/Forms/DirtyFormGuard'
+whenToUse: Blocks navigation when a react-hook-form has unsaved changes; also available as useDirtyFormGuard hook.
+baseLibrary: custom
+relatedComponents: [FormActionsBar]
+relatedNextCore: []
+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
 
 ```tsx
-<DirtyFormGuard
-  isDirty={form.formState.isDirty}
-  message="You have unsaved changes."
-/>
-```
-
-## Hook example
-
-```tsx
-const guard = useDirtyFormGuard({
-  isDirty: form.formState.isDirty,
-  message: "Leave without saving?",
-});
-
-void guard.confirmIfDirty(async () => router.push("/admin"));
+{/* TODO: add example */}
 ```
 
 ## Notes

package/docs/components/donut-chart.md

@@ -0,0 +1,21 @@
+---
+name: DonutChart
+category: charts
+import: '@mantis-core/ui/components/charts/DonutChart'
+whenToUse: Part-to-whole breakdown rendered as a doughnut chart.
+baseLibrary: custom
+relatedComponents: [LineChart, BarChart]
+relatedNextCore: []
+props:
+  - { name: labels, type: 'string[]', required: true }
+  - { name: datasets, type: '{ data: number[]; label?: string }[]', required: true }
+  - { name: options, type: 'ChartOptions<''doughnut''>', required: false }
+  - { name: colors, type: 'string[]', required: false, default: DEFAULT_COLORS palette }
+  - { name: height, type: number, required: false, default: '300' }
+  - { name: className, type: string, required: false }
+---
+## Example
+
+```tsx
+<DonutChart labels={['Leads','Closed','Lost']} datasets={[{ data: [60,25,15] }]} />
+```

package/docs/components/drawer.md

@@ -0,0 +1,19 @@
+---
+name: Drawer
+category: overlays
+import: '@mantis-core/ui/components/overlays/Drawer'
+whenToUse: Slide-in side panel (PrimeReact Sidebar wrapper); defaults to right position.
+baseLibrary: custom
+relatedNextCore: []
+props:
+  - { name: visible, type: boolean, required: true }
+  - { name: onHide, type: '() => void', required: true }
+  - { name: position, type: '''left'' | ''right'' | ''top'' | ''bottom''', required: false, default: '''right''' }
+  - { name: header, type: ReactNode, required: false }
+  - { name: className, type: string, required: false }
+---
+## Example
+
+```tsx
+<Drawer visible={open} onHide={() => setOpen(false)} header='Filtros'><FilterForm /></Drawer>
+```

package/docs/components/drop-down.md

@@ -1,26 +1,24 @@
-# DropDown
-
-- Export: `DropDown`
-- Extra exports: `DropDownProps`
-- Import: `import { DropDown } from "@mantis-core/ui";`
-- Base library: `primereact/dropdown`
-- Base typing: `Omit<DropdownProps, "name" | "defaultValue"> & { controller: ControllerProps; block?: boolean }`
-- Form contract: [`ControllerProps`](../contracts/controller-props.md)
-- Required styles: `@mantis-core/styles/scss/inputs.scss`
-
+---
+name: DropDown
+category: forms
+import: '@mantis-core/ui/components/Forms/DropDown'
+whenToUse: PrimeReact Dropdown (single select with filter) wired to react-hook-form; use when you need PrimeReact styling over react-select.
+baseLibrary: primereact/dropdown
+formContract: ControllerProps
+requiredStyles: [scss/inputs.scss]
+relatedComponents: [FormFieldRender]
+relatedNextCore: []
+props:
+  - { name: controller, type: ControllerProps, required: true }
+  - { name: options, type: 'any[]', required: false }
+  - { name: optionLabel, type: string, required: false }
+  - { name: optionValue, type: string, required: false }
+  - { name: block, type: boolean, required: false }
+---
 ## Example
 
 ```tsx
-<DropDown
-  controller={{ name: "status", control: form.control }}
-  block
-  options={[
-    { label: "Draft", value: "draft" },
-    { label: "Published", value: "published" },
-  ]}
-  optionLabel="label"
-  optionValue="value"
-/>
+<DropDown controller={{ name: 'category' }} options={categories} optionLabel='name' optionValue='id' block />
 ```
 
 ## Notes

package/docs/components/empty-state.md

@@ -0,0 +1,18 @@
+---
+name: EmptyState
+category: feedback
+import: '@mantis-core/ui/components/feedback/EmptyState'
+whenToUse: 'Centered empty-state placeholder with icon, title, optional description, and action button.'
+baseLibrary: custom
+relatedNextCore: []
+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
+
+```tsx
+<EmptyState icon={<i className='pi pi-inbox' />} title='Sin propiedades' description='Crea tu primera propiedad.' action={<Button label='Nueva' onClick={onCreate} />} />
+```

package/docs/components/error-boundary.md

@@ -0,0 +1,17 @@
+---
+name: ErrorBoundary
+category: feedback
+import: '@mantis-core/ui/components/feedback/ErrorBoundary'
+whenToUse: React error boundary; renders fallback UI on uncaught errors; fallback can be a ReactNode or render function.
+baseLibrary: custom
+relatedNextCore: []
+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
+
+```tsx
+<ErrorBoundary fallback={<p>Algo salió mal.</p>}><FeatureView /></ErrorBoundary>
+```

package/docs/components/error-message.md

@@ -1,13 +1,15 @@
-# ErrorMessage
-
-- Export: `ErrorMessage`
-- Import: `import { ErrorMessage } from "@mantis-core/ui";`
-- Base library: `@hookform/error-message`
-- Base typing: wrapper export around hook-form error rendering
-- Required styles: none
-
+---
+name: ErrorMessage
+category: forms
+import: '@mantis-core/ui/components/Forms/ErrorMessage'
+whenToUse: Displays a validation error string; use standalone when not using FormFieldRender.
+baseLibrary: '@hookform/error-message'
+relatedNextCore: []
+props:
+  - { name: message, type: string, required: false }
+---
 ## Example
 
 ```tsx
-<ErrorMessage errors={form.formState.errors} name="title" />
+<ErrorMessage message={errors.email?.message} />
 ```

package/docs/components/file-dropzone.md

@@ -1,22 +1,34 @@
-# FileDropzone
-
-- Export: `FileDropzone`
-- Extra exports: `FileDropzoneProps`, `FileDropzoneRejectedFile`, `FileDropzoneRejectCode`
-- Import: `import { FileDropzone } from "@mantis-core/ui";`
-- Base library: custom drag-and-drop file input
-- Base typing: explicit `FileDropzoneProps`
-- Required styles: `@mantis-core/styles/scss/file-dropzone.scss`
-
+---
+name: FileDropzone
+category: forms
+import: '@mantis-core/ui/components/Forms/FileDropzone'
+whenToUse: Drag-and-drop file input with validation (type, size, count); supports react-hook-form mode and plain controlled mode.
+baseLibrary: custom
+requiredStyles: [scss/file-dropzone.scss]
+relatedComponents: [UploadFilesPreview]
+relatedNextCore: []
+props:
+  - { name: controller, type: ControllerProps, required: false, description: 'When provided, wires to react-hook-form' }
+  - { name: value, type: 'File[]', required: false, description: 'Controlled file list (plain mode)' }
+  - { 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
 
 ```tsx
-<FileDropzone
-  controller={{ name: "attachments", control: form.control, defaultValue: [] }}
-  accept={["image/*", ".pdf"]}
-  maxFiles={5}
-  maxSizeBytes={5 * 1024 * 1024}
-  label="Attachments"
-/>
+{/* TODO: add example */}
 ```
 
 ## Notes

package/docs/components/filter-pannel.md

@@ -1,20 +1,18 @@
-# FilterPannel
-
-- Export: `FilterPannel`
-- Import: `import { FilterPannel } from "@mantis-core/ui";`
-- Base library: `primereact/sidebar` + `react-hook-form`
-- Base typing: `PropsWithChildren<{ onApplyFilter: (data: T) => Promise<void> }>`
-- Required styles: none
-
+---
+name: FilterPannel
+category: tables
+import: '@mantis-core/ui/components/Tables/FilterPannel'
+whenToUse: Slide-in sidebar filter panel for tables; wraps children in FormProvider and calls onApplyFilter with cleaned form data.
+baseLibrary: primereact/sidebar
+relatedComponents: [PaginatedTable, MultiSelectFilter]
+relatedNextCore: []
+props:
+  - { name: onApplyFilter, type: '(data: T) => Promise<void>', required: true }
+---
 ## Example
 
 ```tsx
-<FilterPannel<{ status: string | null; city: string | null }>
-  onApplyFilter={async (filters) => setFilters(filters)}
->
-  <DropDown controller={{ name: "status" }} options={statusOptions} />
-  <DropDown controller={{ name: "city" }} options={cityOptions} />
-</FilterPannel>
+<FilterPannel onApplyFilter={pagination.applyFilters}><TableFilterField label='Search'><TextInput controller={{ name: 'search' }} /></TableFilterField></FilterPannel>
 ```
 
 ## Notes

package/docs/components/forgot-password-form.md

@@ -0,0 +1,18 @@
+---
+name: ForgotPasswordForm
+category: auth
+import: '@mantis-core/ui/components/auth/ForgotPasswordForm'
+whenToUse: Email-only form to trigger password reset; caller owns the reset logic.
+baseLibrary: custom
+relatedNextCore: []
+props:
+  - { name: onSubmit, type: '(values: { email: string }) => void | Promise<void>', required: true }
+  - { name: title, type: string, required: false }
+  - { name: backSlot, type: ReactNode, required: false }
+  - { name: className, type: string, required: false }
+---
+## Example
+
+```tsx
+<ForgotPasswordForm onSubmit={({ email }) => sendResetEmail(email)} />
+```

package/docs/components/form-actions-bar.md

@@ -1,22 +1,33 @@
-# FormActionsBar
-
-- Export: `FormActionsBar`
-- Import: `import { FormActionsBar } from "@mantis-core/ui";`
-- Base library: custom layout + `Button`
-- Base typing: explicit `FormActionsBarProps`
-- Required styles: `@mantis-core/styles/scss/form-actions.scss`
-
+---
+name: FormActionsBar
+category: forms
+import: '@mantis-core/ui/components/Forms/FormActionsBar'
+whenToUse: Sticky-capable action bar with primary/secondary buttons and optional left/right slots for form pages.
+baseLibrary: custom
+requiredStyles: [scss/form-actions.scss]
+relatedComponents: [FormFieldRender, DirtyFormGuard]
+relatedNextCore: []
+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
 
 ```tsx
-<FormActionsBar
-  align="between"
-  sticky
-  leftSlot={<span>Unsaved changes</span>}
-  primaryLabel="Save"
-  primaryType="submit"
-  secondaryLabel="Cancel"
-  secondaryOutlined
-  onSecondaryClick={() => router.back()}
-/>
+{/* TODO: add example */}
 ```

package/docs/components/form-field-render.md

@@ -1,20 +1,20 @@
-# FormFieldRender
-
-- Export: `FormFieldRender`
-- Extra exports: `FormFieldRenderProps`
-- Import: `import { FormFieldRender } from "@mantis-core/ui";`
-- Base library: custom label and error wrapper
-- Base typing: `{ name: string; label: string | ReactElement; labelProps?; containerClassName?; render: ({ name }) => ReactElement | ReactNode }`
-- Required styles: none
-
+---
+name: FormFieldRender
+category: forms
+import: '@mantis-core/ui/components/Forms/FormFieldRender'
+whenToUse: 'Wrapper that renders a label, the input slot, and a validation error message; use to compose any form control.'
+baseLibrary: custom
+relatedComponents: [TextInput, FormActionsBar]
+relatedNextCore: []
+props:
+  - { name: label, type: string, required: false }
+  - { name: htmlFor, type: string, required: false }
+  - { name: error, type: 'string | FieldError', required: false }
+  - { name: required, type: boolean, required: false }
+  - { name: className, type: string, required: false }
+---
 ## Example
 
 ```tsx
-<FormFieldRender
-  name="email"
-  label="Email"
-  render={({ name }) => (
-    <TextInput controller={{ name, control: form.control }} block />
-  )}
-/>
+<FormFieldRender label='Email' htmlFor='email' error={errors.email}><TextInput controller={{ name: 'email' }} id='email' block /></FormFieldRender>
 ```

package/docs/components/form-section.md

@@ -1,15 +1,19 @@
-# FormSection
-
-- Export: `FormSection`
-- Import: `import { FormSection } from "@mantis-core/ui";`
-- Base library: custom card section
-- Base typing: `{ title: string; description?: string; icon?: ReactNode; children: ReactNode; className?: string }`
-- Required styles: none
-
+---
+name: FormSection
+category: pages
+import: '@mantis-core/ui/components/pages/FormSection'
+whenToUse: Bordered card section with a header (title + description + icon) and a padded body; groups related form fields.
+baseLibrary: custom
+relatedNextCore: []
+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
 
 ```tsx
-<FormSection title="Publishing" description="Visibility and timing controls">
-  <Switch name="published" control={form.control} />
-</FormSection>
+<FormSection title='Contact Info' description='Public contact details'><TextInput controller={{ name: 'email' }} block /></FormSection>
 ```

package/docs/components/form-wizard.md

@@ -0,0 +1,18 @@
+---
+name: FormWizard
+category: forms
+import: '@mantis-core/ui/components/Forms/FormWizard'
+whenToUse: 'Multi-step form navigator with step indicator and per-step validation; must render inside a FormProvider, parent owns the <form onSubmit>.'
+baseLibrary: custom
+relatedNextCore: []
+props:
+  - { name: steps, type: 'FormWizardStep[]', required: true }
+  - { name: onComplete, type: '() => void | Promise<void>', required: false }
+  - { name: submitLabel, type: string, required: false, default: '''Finalizar''' }
+  - { name: className, type: string, required: false }
+---
+## Example
+
+```tsx
+<FormProvider {...form}><form onSubmit={form.handleSubmit(onSubmit)}><FormWizard steps={[{ label: 'Datos', fields: ['name', 'email'], content: <Step1 /> }, { label: 'Confirmar', content: <Step2 /> }]} submitLabel='Guardar' /></form></FormProvider>
+```