@mantis-core/ui 0.4.0 → 0.5.0

package/COMPONENTS.md

@@ -1,20 +1,120 @@
-# @mantis-core/ui Component Index
+<!-- GENERATED by `pnpm gen:catalog` — do not edit. Source: docs/components/*.md -->
 
-The detailed package documentation is now split into focused files under [`docs/`](./docs/README.md).
+# @mantis-core/ui — Component Index
 
-## Start Here
+One doc per component under [`docs/components/`](./docs/components). Edit those `.md` files and run `pnpm gen:catalog` to refresh this index.
 
-- [Documentation index](./docs/README.md)
-- [Shared contracts](./docs/contracts/controller-props.md)
-- [Underlying library map](./docs/contracts/dependency-map.md)
-- [Style import guide](./docs/contracts/style-imports.md)
+## forms
 
-## Key component docs
+- [AsyncSelect](./docs/components/async-select.md) — Searchable select that loads options asynchronously via loadOptions callback.
+- [CKEditorInput](./docs/components/ckeditor-input.md) — Rich-text WYSIWYG editor (CKEditor 5) wired to react-hook-form; emits HTML string.
+- [ColorPickerInput](./docs/components/color-picker-input.md) — Color picker (PrimeReact ColorPicker, hex format) wired to react-hook-form.
+- [Combobox](./docs/components/combobox.md) — Autocomplete text input (PrimeReact AutoComplete) wired to react-hook-form; pass suggestions via the suggestions prop.
+- [CurrencyInput](./docs/components/currency-input.md) — Numeric input pre-configured for currency display (mode=currency).
+- [DateInput](./docs/components/date-input.md) — Single date picker (PrimeReact Calendar, locale=es, format=dd/mm/yy).
+- [DatePresets](./docs/components/date-presets.md) — Row of preset buttons (Hoy, 7 días, 30 días, Este mes) that fire onChange with a [Date, Date] range; pair with DateRangeInput.
+- [DateRangeInput](./docs/components/date-range-input.md) — Date range picker that stores [startDate, endDate] array; selectionMode is locked to 'range'.
+- [DirtyFormGuard](./docs/components/dirty-form-guard.md) — Blocks navigation when a react-hook-form has unsaved changes; also available as useDirtyFormGuard hook.
+- [DropDown](./docs/components/drop-down.md) — PrimeReact Dropdown (single select with filter) wired to react-hook-form; use when you need PrimeReact styling over react-select.
+- [ErrorMessage](./docs/components/error-message.md) — Displays a validation error string; use standalone when not using FormFieldRender.
+- [FileDropzone](./docs/components/file-dropzone.md) — Drag-and-drop file input with validation (type, size, count); supports react-hook-form mode and plain controlled mode.
+- [FormActionsBar](./docs/components/form-actions-bar.md) — Sticky-capable action bar with primary/secondary buttons and optional left/right slots for form pages.
+- [FormFieldRender](./docs/components/form-field-render.md) — Wrapper that renders a label, the input slot, and a validation error message; use to compose any form control.
+- [FormWizard](./docs/components/form-wizard.md) — Multi-step form navigator with step indicator and per-step validation; must render inside a FormProvider, parent owns the <form onSubmit>.
+- [HiddenField](./docs/components/hidden-field.md) — Registers a hidden value in react-hook-form without rendering any UI.
+- [MultiSelect](./docs/components/multi-select.md) — Multi-value select (PrimeReact) wired to react-hook-form.
+- [NumberInput](./docs/components/number-input.md) — Numeric input (integer or decimal) wired to react-hook-form.
+- [OtpInput](./docs/components/otp-input.md) — One-time password input (PrimeReact InputOtp) wired to react-hook-form.
+- [PasswordInput](./docs/components/password-input.md) — Password field with show/hide toggle; Controller pattern, same API as TextInput.
+- [PhoneInput](./docs/components/phone-input.md) — Masked phone number input; default mask (999) 999-9999.
+- [RadioGroup](./docs/components/radio-group.md) — Renders a set of radio buttons from an options array; value is the selected option's value.
+- [RangeSlider](./docs/components/range-slider.md) — Dual-handle range slider that stores a [min, max] tuple; backed by PrimeReact Slider.
+- [RatingInput](./docs/components/rating-input.md) — Star rating input (PrimeReact Rating) wired to react-hook-form; stores numeric value.
+- [RenderField](./docs/components/render-field.md) — Low-level escape hatch: connects any custom UI to react-hook-form via a render prop.
+- [SearchInput](./docs/components/search-input.md) — Debounced text input that calls onSearch instead of using react-hook-form; ideal for live table/list filtering.
+- [Select](./docs/components/select.md) — Single-value searchable select (react-select); supports creatable mode.
+- [Switch](./docs/components/switch.md) — Toggle/boolean switch wired to react-hook-form.
+- [TagsInput](./docs/components/tags-input.md) — Chip/tags input (PrimeReact Chips) wired to react-hook-form; stores value as string[].
+- [TextArea](./docs/components/text-area.md) — Multi-line text field wired to react-hook-form.
+- [TextInput](./docs/components/text-input.md) — Single-line text field wired to react-hook-form.
+- [TimePicker](./docs/components/time-picker.md) — Time-only picker (15-min intervals) wired to react-hook-form; renders as a styled InputText trigger.
+- [Toggle](./docs/components/toggle.md) — Checkbox-based boolean toggle wired to react-hook-form with configurable on/off labels.
+- [ToggleInlineButton](./docs/components/toggle-inline-button.md) — Segmented button group (single or multi-select) wired to react-hook-form via a controller prop.
+- [UploadFilesPreview](./docs/components/upload-files-preview.md) — Drag-and-drop upload zone with live preview grid, drag-to-reorder, and async upload queue; designed for image galleries.
 
-- [Button](./docs/components/button.md)
-- [TextInput](./docs/components/text-input.md)
-- [Select](./docs/components/select.md)
-- [PaginatedTable](./docs/components/paginated-table.md)
-- [ConfirmDialog](./docs/components/confirm-dialog.md)
-- [StatusBadge](./docs/components/status-badge.md)
-- [MapPicker](./docs/components/map-picker.md)
+## tables
+
+- [ActionColumn](./docs/components/action-column.md) — Factory function that returns a PrimeReact Column with a dropdown action menu; call as ActionColumn(itemsFn, props).
+- [FilterPannel](./docs/components/filter-pannel.md) — Slide-in sidebar filter panel for tables; wraps children in FormProvider and calls onApplyFilter with cleaned form data.
+- [IndexColumn](./docs/components/index-column.md) — Returns a PrimeReact Column that renders the row's 1-based visual index; call as IndexColumn(colProps).
+- [MenuButton](./docs/components/menu-button.md) — Dropdown button with a list of actions; used inside table rows.
+- [MultiSelectFilter](./docs/components/multi-select-filter.md) — PrimeReact MultiSelect wired for use as a DataTable column filter template.
+- [PaginatedTable](./docs/components/paginated-table.md) — Generic server-side paginated DataTable with built-in index column, action column, and Mantis Core CSS. Wraps PrimeReact DataTable.
+- [TableFilterField](./docs/components/table-filter-field.md) — Wraps a form control inside FilterPannel with a label; provides consistent layout.
+- [TableToolbar](./docs/components/table-toolbar.md) — Header bar above a table showing title, record count, and action buttons slot.
+
+## pages
+
+- [AdminPageConfigurator](./docs/components/admin-page-configurator.md) — Sets the page title, description, and breadcrumbs in the admin layout shell via context; wrap each page's content with this.
+- [AdminPageHeader](./docs/components/admin-page-header.md) — Gradient page header with title, optional description, breadcrumbs, and right-side actions slot; rendered by AdminPageLayoutShell — avoid rendering directly inside feature views.
+- [AdminPageLayout](./docs/components/admin-page-layout.md) — Overview of the admin page layout system — Provider, Configurator, and Shell exports that together compose admin pages.
+- [AdminPageLayoutShell](./docs/components/admin-page-layout-shell.md) — Root layout shell for admin pages; renders AdminPageHeader from context set by AdminPageConfigurator and provides the layout grid.
+- [AppShell](./docs/components/app-shell.md) — Full-page app shell with responsive sidebar nav, topbar, and mobile drawer; use as the root layout wrapper for authenticated pages.
+- [Breadcrumbs](./docs/components/breadcrumbs.md) — Standalone breadcrumb nav; renders nothing when items is empty.
+- [FormSection](./docs/components/form-section.md) — Bordered card section with a header (title + description + icon) and a padded body; groups related form fields.
+- [PageTitle](./docs/components/page-title.md) — Centered display-font heading for public-facing pages.
+
+## maps
+
+- [MapPicker](./docs/components/map-picker.md) — Interactive Leaflet map that lets the user click to select a lat/lng coordinate; SSR-safe via next/dynamic.
+- [MapPickerClient](./docs/components/map-picker-client.md) — Client-only Leaflet map that lets the user click to pick a coordinate; controlled via initialLat/initialLng.
+- [MapPickerOSM](./docs/components/map-picker-osm.md) — Script-injected Leaflet map (no SSR bundle cost) with click/drag marker and a save-location button.
+
+## overlays
+
+- [Drawer](./docs/components/drawer.md) — Slide-in side panel (PrimeReact Sidebar wrapper); defaults to right position.
+- [Modal](./docs/components/modal.md) — Dialog/modal (PrimeReact Dialog wrapper); dismissable mask and non-draggable by default.
+
+## navigation
+
+- [CommandPalette](./docs/components/command-palette.md) — Keyboard-driven command search overlay (Ctrl+K); pair with useCommandPalette hook to wire the shortcut.
+- [PageTabs](./docs/components/page-tabs.md) — Tab menu bar for page-level navigation; auto-detects active tab from Next.js pathname when tabs have href.
+
+## data
+
+- [DescriptionList](./docs/components/description-list.md) — Grid-based label/value list for detail views; supports 1, 2, or 3 columns.
+- [StatCard](./docs/components/stat-card.md) — KPI card showing a metric label, large value, optional icon, trend indicator, and footer.
+- [Timeline](./docs/components/timeline.md) — Vertical event timeline backed by PrimeReact Timeline; items render title, description, date, and optional icon.
+
+## feedback
+
+- [Avatar](./docs/components/avatar.md) — User avatar that auto-generates initials from a name when no image is supplied; wraps PrimeReact Avatar.
+- [CardSkeleton](./docs/components/card-skeleton.md) — Animated skeleton for card grid layouts while data loads.
+- [ConfirmDialog](./docs/components/confirm-dialog.md) — Modal confirmation dialog with confirm/cancel buttons and severity-aware styling.
+- [DataState](./docs/components/data-state.md) — Full-area empty/error/loading state placeholder for data-fetching views.
+- [EmptyState](./docs/components/empty-state.md) — Centered empty-state placeholder with icon, title, optional description, and action button.
+- [ErrorBoundary](./docs/components/error-boundary.md) — React error boundary; renders fallback UI on uncaught errors; fallback can be a ReactNode or render function.
+- [Loading](./docs/components/loading.md) — Full-screen loading overlay with animated spinner; renders children when loading=false.
+- [Pagination](./docs/components/pagination.md) — Standalone pagination control; use when not relying on PaginatedTable's built-in paginator.
+- [RichTextPreview](./docs/components/rich-text-preview.md) — Safely renders a CKEditor HTML string with correct CKEditor content styles.
+- [StatusBadge](./docs/components/status-badge.md) — Colored pill badge to communicate a status or label with semantic tone.
+- [TableSkeleton](./docs/components/table-skeleton.md) — Animated skeleton placeholder that mimics a table grid while data loads.
+- [Tag](./docs/components/tag.md) — Styled label chip (PrimeReact Tag wrapper with Mantis Core CSS); use for status labels, categories, or counts.
+
+## auth
+
+- [ChangePasswordForm](./docs/components/change-password-form.md) — Current + new + confirm password form for authenticated users.
+- [ForgotPasswordForm](./docs/components/forgot-password-form.md) — Email-only form to trigger password reset; caller owns the reset logic.
+- [LoginForm](./docs/components/login-form.md) — Self-contained login form with email/username + password fields; pass onSubmit to wire signIn/Supabase from the app layer.
+- [ResetPasswordForm](./docs/components/reset-password-form.md) — New password + confirm form; caller owns token validation and API call.
+- [UserMenu](./docs/components/user-menu.md) — Topbar user avatar + dropdown with custom nav items and sign-out; no auth lib coupling.
+
+## buttons
+
+- [Button](./docs/components/button.md) — Primary action button; wraps PrimeReact Button with Mantis Core variant tokens and optional Next.js href navigation.
+
+## charts
+
+- [BarChart](./docs/components/bar-chart.md) — Categorical comparisons rendered as a bar chart. Same prop shape as LineChart.
+- [DonutChart](./docs/components/donut-chart.md) — Part-to-whole breakdown rendered as a doughnut chart.
+- [LineChart](./docs/components/line-chart.md) — Time-series or trend data rendered as a line chart. Zero-config defaults with full options override.

package/docs/components/action-column.md

@@ -1,17 +1,18 @@
-# ActionColumn
-
-- Export: `ActionColumn`
-- Extra exports: `ActionColumnProps`
-- Import: `import { ActionColumn } from "@mantis-core/ui";`
-- Base library: `primereact/column`
-- Base typing: `ColumnProps & { label?: string; icon?: string }`
-- Required styles: usually `@mantis-core/styles/scss/table.scss` through table context
-
+---
+name: ActionColumn
+category: tables
+import: '@mantis-core/ui/components/Tables/ActionColumn'
+whenToUse: 'Factory function that returns a PrimeReact Column with a dropdown action menu; call as ActionColumn(itemsFn, props).'
+baseLibrary: primereact/column
+relatedComponents: [PaginatedTable, MenuButton]
+relatedNextCore: []
+props:
+  - { name: items, type: '(rowData: TRow) => ActionMenuItem[]', required: true }
+  - { name: label, type: string, required: false }
+  - { name: icon, type: string, required: false }
+---
 ## Example
 
 ```tsx
-{ActionColumn(
-  (row) => [{ label: "Open", route: `/admin/items/${row.id}` }],
-  { label: "Actions" },
-)}
+{ActionColumn((row) => [{ label: 'Delete', command: () => del(row.id) }])}
 ```

package/docs/components/admin-page-configurator.md

@@ -0,0 +1,23 @@
+---
+name: AdminPageConfigurator
+category: pages
+import: '@mantis-core/ui/components/pages/admin-layout/AdminPageConfigurator'
+whenToUse: Sets the page title, description, and breadcrumbs in the admin layout shell via context; wrap each page's content with this.
+baseLibrary: custom
+requiredStyles: []
+relatedComponents: ['AdminPageLayoutShell', 'AdminPageHeader']
+relatedNextCore: []
+props:
+  - { name: config, type: AdminPageLayoutConfig, required: true }
+  - { name: children, type: ReactNode, required: true }
+---
+
+## Example
+
+```tsx
+<AdminPageConfigurator config={{ title: 'Properties', description: 'Manage listings', breadcrumbs: [{ label: 'Home', href: '/' }, { label: 'Properties' }] }}><PropertiesView /></AdminPageConfigurator>
+```
+
+## Notes
+
+- Pairs with [AdminPageLayoutShell](./admin-page-layout-shell.md), which reads the config from context and renders the header. See [admin-page-layout.md](./admin-page-layout.md) for the overview.

package/docs/components/admin-page-header.md

@@ -1,21 +1,19 @@
-# AdminPageHeader
-
-- Export: `AdminPageHeader`
-- Import: `import { AdminPageHeader } from "@mantis-core/ui";`
-- Base library: custom header + `next/link`
-- Base typing: `{ title: string; description?: string; actions?: ReactNode; breadcrumbs?: readonly AdminBreadcrumbItem[] }`
-- Required styles: none
-
+---
+name: AdminPageHeader
+category: pages
+import: '@mantis-core/ui/components/pages/AdminPageHeader'
+whenToUse: 'Gradient page header with title, optional description, breadcrumbs, and right-side actions slot; rendered by AdminPageLayoutShell — avoid rendering directly inside feature views.'
+baseLibrary: custom
+relatedComponents: [AdminPageLayoutShell]
+relatedNextCore: []
+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
 
 ```tsx
-<AdminPageHeader
-  title="Clients"
-  description="Manage B2B accounts"
-  breadcrumbs={[
-    { label: "Dashboard", href: "/admin" },
-    { label: "Clients" },
-  ]}
-  actions={<Button label="New client" icon="pi pi-plus" />}
-/>
+<AdminPageHeader title='Blog' description='Manage posts' actions={<Button label='New Post' onClick={onCreate} />} />
 ```

package/docs/components/admin-page-layout-shell.md

@@ -0,0 +1,22 @@
+---
+name: AdminPageLayoutShell
+category: pages
+import: '@mantis-core/ui/components/pages/admin-layout/AdminPageLayoutShell'
+whenToUse: Root layout shell for admin pages; renders AdminPageHeader from context set by AdminPageConfigurator and provides the layout grid.
+baseLibrary: custom
+requiredStyles: []
+relatedComponents: ['AdminPageConfigurator', 'AdminPageHeader']
+relatedNextCore: []
+props:
+  - { name: children, type: ReactNode, required: true }
+---
+
+## Example
+
+```tsx
+<AdminPageLayoutShell>{children}</AdminPageLayoutShell>
+```
+
+## Notes
+
+- Reads page config from the context set by [AdminPageConfigurator](./admin-page-configurator.md). See [admin-page-layout.md](./admin-page-layout.md) for the overview.

package/docs/components/admin-page-layout.md

@@ -1,29 +1,20 @@
-# Admin Page Layout
-
-- Exports:
-  - `AdminPageLayoutProvider`
-  - `useAdminPageLayout`
-  - `AdminPageConfigurator`
-  - `AdminPageLayoutShell`
-  - `AdminBreadcrumbItem`
-  - `AdminPageLayoutConfig`
-- Import: `import { AdminPageLayoutProvider, AdminPageConfigurator, AdminPageLayoutShell } from "@mantis-core/ui";`
-- Base library: React context + custom shell
-- Required styles: none
-
+---
+name: AdminPageLayout
+category: pages
+whenToUse: Overview of the admin page layout system — Provider, Configurator, and Shell exports that together compose admin pages.
+baseLibrary: React context + custom shell
+relatedNextCore: []
+props: []
+---
 ## Example
 
 ```tsx
-<AdminPageLayoutProvider>
-  <AdminPageLayoutShell>
-    <AdminPageConfigurator config={{ title: "Leads" }}>
-      <LeadsTable />
-    </AdminPageConfigurator>
-  </AdminPageLayoutShell>
-</AdminPageLayoutProvider>
+{/* TODO: add example */}
 ```
 
 ## Notes
 
+> Overview doc — individual exports are documented in their own entries.
+
 - `useAdminPageLayout` must run inside `AdminPageLayoutProvider`.
 - `AdminPageLayoutShell` renders `AdminPageHeader` when `config.title` exists and `hideHeader` is not set.

package/docs/components/app-shell.md

@@ -0,0 +1,20 @@
+---
+name: AppShell
+category: pages
+import: '@mantis-core/ui/components/pages/app-shell/AppShell'
+whenToUse: 'Full-page app shell with responsive sidebar nav, topbar, and mobile drawer; use as the root layout wrapper for authenticated pages.'
+baseLibrary: custom
+relatedNextCore: []
+props:
+  - { name: navItems, type: 'AppNavItem[]', required: true }
+  - { name: children, type: ReactNode, required: true }
+  - { name: brand, type: ReactNode, required: false }
+  - { name: topbarActions, type: ReactNode, required: false }
+  - { name: user, type: ReactNode, required: false }
+  - { name: footer, type: ReactNode, required: false }
+---
+## Example
+
+```tsx
+<AppShell navItems={NAV_ITEMS} brand={<Logo />} user={<UserMenu />}>{children}</AppShell>
+```

package/docs/components/async-select.md

@@ -1,23 +1,24 @@
-# AsyncSelect
-
-- Export: `AsyncSelect`
-- Extra exports: `AsyncSelectProps`
-- Import: `import { AsyncSelect } from "@mantis-core/ui";`
-- Base library: `react-select/async` or `react-select/async-creatable`
-- Base typing: `Omit<ReactSelectProps<SelectOption>, "name" | "defaultValue" | "options"> & { controller: ControllerProps; block?: boolean; variant?: ButtonVariant; isCreatable?: boolean; loadOptions; defaultOptions?; cacheOptions?; debounceMs?; onCreateOption?; formatCreateLabel? }`
-- Form contract: [`ControllerProps`](../contracts/controller-props.md)
-- Required styles: `@mantis-core/styles/scss/select.scss`
-
+---
+name: AsyncSelect
+category: forms
+import: '@mantis-core/ui/components/Forms/AsyncSelect'
+whenToUse: Searchable select that loads options asynchronously via loadOptions callback.
+baseLibrary: react-select/async
+formContract: ControllerProps
+requiredStyles: [scss/select.scss]
+relatedComponents: [FormFieldRender, Select]
+relatedNextCore: []
+props:
+  - { name: controller, type: ControllerProps, required: true }
+  - { name: loadOptions, type: '(inputValue: string) => Promise<OptionsOrGroups>', required: true }
+  - { name: isCreatable, type: boolean, required: false, default: 'false' }
+  - { name: debounceMs, type: number, required: false, default: '250' }
+  - { name: block, type: boolean, required: false }
+---
 ## Example
 
 ```tsx
-<AsyncSelect
-  controller={{ name: "city", control: form.control }}
-  block
-  loadOptions={async (input) => searchCities(input)}
-  defaultOptions
-  debounceMs={300}
-/>
+<AsyncSelect controller={{ name: 'client' }} loadOptions={searchClients} block />
 ```
 
 ## Notes

package/docs/components/avatar.md

@@ -0,0 +1,19 @@
+---
+name: Avatar
+category: feedback
+import: '@mantis-core/ui/components/feedback/Avatar'
+whenToUse: User avatar that auto-generates initials from a name when no image is supplied; wraps PrimeReact Avatar.
+baseLibrary: custom
+relatedNextCore: []
+props:
+  - { name: name, type: string, required: false }
+  - { name: image, type: string, required: false }
+  - { name: label, type: string, required: false }
+  - { name: size, type: '''normal'' | ''large'' | ''xlarge''', required: false }
+  - { name: shape, type: '''square'' | ''circle''', required: false }
+---
+## Example
+
+```tsx
+<Avatar name='Diego Condo' size='large' shape='circle' />
+```

package/docs/components/bar-chart.md

@@ -0,0 +1,21 @@
+---
+name: BarChart
+category: charts
+import: '@mantis-core/ui/components/charts/BarChart'
+whenToUse: Categorical comparisons rendered as a bar chart. Same prop shape as LineChart.
+baseLibrary: custom
+relatedComponents: [LineChart, DonutChart]
+relatedNextCore: []
+props:
+  - { name: labels, type: 'string[]', required: true }
+  - { name: datasets, type: 'BarChartDataset[]', required: true }
+  - { name: options, type: 'ChartOptions<''bar''>', 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
+<BarChart labels={['Q1','Q2','Q3']} datasets={[{ label: 'Sales', data: [40,70,55] }]} />
+```

package/docs/components/breadcrumbs.md

@@ -0,0 +1,15 @@
+---
+name: Breadcrumbs
+category: pages
+import: '@mantis-core/ui/components/pages/app-shell/Breadcrumbs'
+whenToUse: Standalone breadcrumb nav; renders nothing when items is empty.
+baseLibrary: custom
+relatedNextCore: []
+props:
+  - { name: items, type: 'readonly AdminBreadcrumbItem[]', required: true }
+---
+## Example
+
+```tsx
+<Breadcrumbs items={[{ label: 'Home', href: '/' }, { label: 'Settings' }]} />
+```

package/docs/components/button.md

@@ -1,21 +1,26 @@
-# Button
-
-- Export: `Button`
-- Import: `import { Button } from "@mantis-core/ui";`
-- Base library: `primereact/button`
-- Base typing: `Omit<PrimeButtonProps, "onClick" | "ref">` plus `href`, `variant`, `block`, `sm`, `lg`, `outlined`, `text`, `rounded`
-- Required styles: `@mantis-core/styles/scss/buttons.scss`
-
+---
+name: Button
+category: buttons
+import: '@mantis-core/ui/components/Buttons/Button'
+whenToUse: Primary action button; wraps PrimeReact Button with Mantis Core variant tokens and optional Next.js href navigation.
+baseLibrary: primereact/button
+requiredStyles: [scss/buttons.scss]
+relatedNextCore: []
+props:
+  - { name: variant, type: '''primary'' | ''secondary'' | ''accent'' | ''success'' | ''warning'' | ''error'' | ''info'' | ''gray'' | ''danger''', required: false, default: '''primary''' }
+  - { name: label, type: string, required: false }
+  - { name: icon, type: string, required: false }
+  - { name: href, type: string, required: false }
+  - { name: outlined, type: boolean, required: false }
+  - { name: block, type: boolean, required: false }
+  - { name: text, type: boolean, required: false }
+  - { name: loading, type: boolean, required: false }
+  - { name: disabled, type: boolean, required: false }
+---
 ## Example
 
 ```tsx
-<Button
-  label="Save"
-  icon="pi pi-check"
-  variant="primary"
-  rounded
-  onClick={() => console.log("saved")}
-/>
+<Button variant='danger' outlined label='Delete' icon={PrimeIcons.TRASH} onClick={onDelete} />
 ```
 
 ## Notes

package/docs/components/card-skeleton.md

@@ -0,0 +1,15 @@
+---
+name: CardSkeleton
+category: feedback
+import: '@mantis-core/ui/components/feedback/CardSkeleton'
+whenToUse: Animated skeleton for card grid layouts while data loads.
+baseLibrary: custom
+relatedNextCore: []
+props:
+  - { name: count, type: number, required: false, default: '3' }
+---
+## Example
+
+```tsx
+<CardSkeleton count={6} />
+```

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

@@ -0,0 +1,17 @@
+---
+name: ChangePasswordForm
+category: auth
+import: '@mantis-core/ui/components/auth/ChangePasswordForm'
+whenToUse: Current + new + confirm password form for authenticated users.
+baseLibrary: custom
+relatedNextCore: []
+props:
+  - { name: onSubmit, type: '(values: ChangePasswordFormValues) => void | Promise<void>', required: true }
+  - { name: minPasswordLength, type: number, required: false, default: '8' }
+  - { name: className, type: string, required: false }
+---
+## Example
+
+```tsx
+<ChangePasswordForm onSubmit={changePassword} />
+```

package/docs/components/ckeditor-input.md

@@ -1,22 +1,21 @@
-# CKEditorInput
-
-- Export: `CKEditorInput`
-- Extra exports: `CKEditorInputProps`, `CKEditorContentMetrics`
-- Import: `import { CKEditorInput } from "@mantis-core/ui";`
-- Base library: `@ckeditor/ckeditor5-react` + `ckeditor5`
-- Base typing: explicit `CKEditorInputProps`
-- Form contract: [`ControllerProps`](../contracts/controller-props.md)
-- Required styles: `@mantis-core/styles/scss/ckeditor.scss`
-
+---
+name: CKEditorInput
+category: forms
+import: '@mantis-core/ui/components/Forms/CKEditorInput'
+whenToUse: Rich-text WYSIWYG editor (CKEditor 5) wired to react-hook-form; emits HTML string.
+baseLibrary: '@ckeditor/ckeditor5-react'
+formContract: ControllerProps
+requiredStyles: [scss/ckeditor.scss]
+relatedComponents: [FormFieldRender, RichTextPreview]
+relatedNextCore: []
+props:
+  - { name: controller, type: ControllerProps, required: true }
+  - { name: block, type: boolean, required: false }
+---
 ## Example
 
 ```tsx
-<CKEditorInput
-  controller={{ name: "body", control: form.control }}
-  minHeight="20rem"
-  showStats
-  onMetricsChange={(metrics) => console.log(metrics.words)}
-/>
+<CKEditorInput controller={{ name: 'body', rules: { required: true } }} block />
 ```
 
 ## Notes

package/docs/components/color-picker-input.md

@@ -0,0 +1,19 @@
+---
+name: ColorPickerInput
+category: forms
+import: '@mantis-core/ui/components/Forms/ColorPickerInput'
+whenToUse: 'Color picker (PrimeReact ColorPicker, hex format) wired to react-hook-form.'
+baseLibrary: custom
+formContract: ControllerProps
+relatedNextCore: []
+props:
+  - { name: controller, type: ControllerProps, required: true }
+  - { name: format, type: '''hex'' | ''rgb'' | ''hsb''', required: false, default: '''hex''' }
+  - { name: inline, type: boolean, required: false }
+  - { name: block, type: boolean, required: false }
+---
+## Example
+
+```tsx
+<ColorPickerInput controller={{ name: 'brandColor' }} />
+```

package/docs/components/combobox.md

@@ -0,0 +1,19 @@
+---
+name: Combobox
+category: forms
+import: '@mantis-core/ui/components/Forms/Combobox'
+whenToUse: Autocomplete text input (PrimeReact AutoComplete) wired to react-hook-form; pass suggestions via the suggestions prop.
+baseLibrary: custom
+formContract: ControllerProps
+relatedNextCore: []
+props:
+  - { name: controller, type: ControllerProps, required: true }
+  - { name: suggestions, type: 'any[]', required: false }
+  - { name: completeMethod, type: '(e: AutoCompleteCompleteEvent) => void', required: false }
+  - { name: block, type: boolean, required: false }
+---
+## Example
+
+```tsx
+<Combobox controller={{ name: 'city' }} suggestions={cities} completeMethod={searchCities} block />
+```

package/docs/components/command-palette.md

@@ -0,0 +1,17 @@
+---
+name: CommandPalette
+category: navigation
+import: '@mantis-core/ui/components/navigation/CommandPalette'
+whenToUse: Keyboard-driven command search overlay (Ctrl+K); pair with useCommandPalette hook to wire the shortcut.
+baseLibrary: custom
+relatedNextCore: []
+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
+
+```tsx
+<CommandPalette commands={cmds} open={paletteOpen} onOpenChange={setPaletteOpen} />
+```