@mantis-core/ui 0.4.0 → 0.6.0

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

@@ -1,29 +1,49 @@
-# 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 — a context Provider plus a Configurator and a Shell that together compose admin pages without prop-drilling page title/description/breadcrumbs/actions.
+baseLibrary: React context + custom shell
+relatedComponents: ['AdminPageConfigurator', 'AdminPageLayoutShell', 'AdminPageHeader']
+relatedNextCore: []
+props: []
+---
 
 ## Example
 
 ```tsx
-<AdminPageLayoutProvider>
-  <AdminPageLayoutShell>
-    <AdminPageConfigurator config={{ title: "Leads" }}>
-      <LeadsTable />
-    </AdminPageConfigurator>
-  </AdminPageLayoutShell>
-</AdminPageLayoutProvider>
+import {
+  AdminPageLayoutProvider,
+  AdminPageConfigurator,
+  AdminPageLayoutShell,
+} from '@mantis-core/ui';
+
+function Example() {
+  return (
+    <AdminPageLayoutProvider>
+      <AdminPageConfigurator
+        config={{
+          title: 'Properties',
+          breadcrumbs: [{ label: 'Home', href: '/' }, { label: 'Properties' }],
+        }}>
+        <AdminPageLayoutShell>
+          <div>Page content</div>
+        </AdminPageLayoutShell>
+      </AdminPageConfigurator>
+    </AdminPageLayoutProvider>
+  );
+}
 ```
 
 ## Notes
 
-- `useAdminPageLayout` must run inside `AdminPageLayoutProvider`.
-- `AdminPageLayoutShell` renders `AdminPageHeader` when `config.title` exists and `hideHeader` is not set.
+> Overview doc — each export below has its own entry with the full prop list.
+
+- `AdminPageLayoutProvider` (root layout, once) holds the current `AdminPageLayoutConfig` in
+  context; `useAdminPageLayout()` reads/writes it and throws if called outside the provider.
+- `AdminPageConfigurator` (per page) pushes its `config` into context via `useEffect` — it renders
+  no markup of its own, just `children`.
+- `AdminPageLayoutShell` (root layout, once, inside the Provider) reads the context config and
+  renders `AdminPageHeader` when `config.title` is set and `config.hideHeader` is not, then renders
+  `children` below it.
+- All four names (`AdminPageLayoutProvider`, `useAdminPageLayout`, `AdminPageConfigurator`,
+  `AdminPageLayoutShell`) are re-exported from the `@mantis-core/ui` package root.

package/docs/components/app-shell.md

@@ -0,0 +1,45 @@
+---
+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
+relatedComponents: ['Drawer', 'Breadcrumbs']
+relatedNextCore: []
+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
+
+```tsx
+import AppShell from '@mantis-core/ui/components/pages/app-shell/AppShell';
+
+function Example() {
+  return (
+    <AppShell
+      navItems={[
+        { label: 'Dashboard', href: '/admin' },
+        { label: 'Properties', href: '/admin/properties' },
+      ]}
+      brand={<span>Atlas</span>}>
+      <div>Page content</div>
+    </AppShell>
+  );
+}
+```
+
+## Notes
+
+- Requires Next.js App Router (`usePathname` drives active-link highlighting; nav item `href` links
+  render as `next/link`, items without `href` render as a `<button>`).
+- Mobile nav is a left-side PR11 `Drawer` toggled by a hamburger button that only shows below the
+  `lg` breakpoint; the desktop `<aside>` sidebar is hidden below that breakpoint instead.
+- `collapsible` only affects the desktop sidebar; the mobile drawer always renders expanded.

package/docs/components/auto-complete-field.md

@@ -0,0 +1,60 @@
+---
+name: AutoCompleteField
+category: forms
+import: '@mantis-core/ui/components/Forms/AutoCompleteField'
+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.
+baseLibrary: '@primereact/ui/autocomplete'
+formContract: FieldControllerProps
+relatedComponents: ['SelectField', 'RadioGroup']
+relatedNextCore: []
+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
+
+```tsx
+import { AutoCompleteField } from '@mantis-core/ui/components/Forms/AutoCompleteField';
+import { useForm } from 'react-hook-form';
+
+const CITIES = [
+  { label: 'Quito', value: 'UIO' },
+  { label: 'Cuenca', value: 'CUE' },
+];
+
+async function searchCities(query: string) {
+  return CITIES.filter((c) => c.label.toLowerCase().includes(query.toLowerCase()));
+}
+
+function Example() {
+  const { control } = useForm({ defaultValues: { city: null } });
+  return (
+    <AutoCompleteField
+      name='city'
+      control={control}
+      label='City'
+      optionLabel='label'
+      optionValue='value'
+      loadOptions={searchCities}
+    />
+  );
+}
+```
+
+## Notes
+
+- Value shape: selecting a listed option commits its scalar `optionValue`. In `creatable` mode, typed
+  free text that matches no option is committed as-is; with `creatable` off (default), PR11's
+  `forceSelection` clears unmatched text to `null` on blur.
+- Async responses are guarded against out-of-order replies: a slower, stale `loadOptions` call is
+  dropped if a newer query has since started.
+- The visible input is real (`AutoComplete.Input as={InputText}`), so PR11 emits `aria-invalid`
+  itself — no manual aria wiring like the portal-trigger components.

package/docs/components/avatar.md

@@ -0,0 +1,29 @@
+---
+name: Avatar
+category: feedback
+import: '@mantis-core/ui/components/feedback/Avatar'
+whenToUse: User avatar that renders an image or auto-derived initials; composes the PR11 headless Avatar (Root/Image/Fallback).
+baseLibrary: '@primereact/ui/avatar'
+relatedComponents: ['Tag', 'UserMenu']
+relatedNextCore: []
+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
+
+```tsx
+import Avatar from '@mantis-core/ui/components/feedback/Avatar';
+
+function Example() {
+  return <Avatar name='Diego Condo' size='large' shape='circle' />;
+}
+```
+
+## Notes
+
+- PR11's `Avatar.Root` dropped the PR10 `label`/`image` props; the wrapper composes `Root`/`Image`/`Fallback` manually while keeping the old public API.

package/docs/components/bar-chart.md

@@ -0,0 +1,39 @@
+---
+name: BarChart
+category: charts
+import: '@mantis-core/ui/components/charts/BarChart'
+whenToUse: Categorical comparisons rendered as a bar chart, zero-config over chart.js defaults.
+baseLibrary: chart.js
+requiredStyles: []
+relatedComponents: [LineChart, DonutChart]
+relatedNextCore: []
+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
+
+```tsx
+import BarChart from '@mantis-core/ui/components/charts/BarChart';
+
+function Example() {
+  return (
+    <BarChart
+      labels={['Q1', 'Q2', 'Q3']}
+      datasets={[{ label: 'Sales', data: [40, 70, 55] }]}
+    />
+  );
+}
+```
+
+## Notes
+
+- Not re-exported from the package root — import from the deep path above (`@mantis-core/ui/components/charts/BarChart`), not `@mantis-core/ui`.
+- Calls `registerCharts()` (module-level, from `./chart-setup`) on import to register the chart.js
+  controllers/elements/plugins it needs — no separate `Chart.register(...)` call required by callers.
+- Wraps `react-chartjs-2`'s `Bar`; any prop `Bar` accepts besides `data`/`options` passes through via `...rest`.

package/docs/components/breadcrumbs.md

@@ -0,0 +1,28 @@
+---
+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
+relatedComponents: ['AdminPageHeader']
+relatedNextCore: []
+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
+
+```tsx
+import Breadcrumbs from '@mantis-core/ui/components/pages/app-shell/Breadcrumbs';
+
+function Example() {
+  return <Breadcrumbs items={[{ label: 'Home', href: '/' }, { label: 'Settings' }]} />;
+}
+```
+
+## Notes
+
+- Links use `next/link`; the last (current) item always renders as plain text, styled with the
+  primary color, regardless of whether it has an `href`.
+- `AdminPageHeader` renders this internally for its own `breadcrumbs` prop — most admin pages
+  configure breadcrumbs through `AdminPageConfigurator` rather than rendering this directly.

package/docs/components/button.md

@@ -1,25 +1,49 @@
-# 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 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.
+baseLibrary: '@primereact/ui/button'
+relatedComponents: ['ConfirmDialog', 'DataState']
+relatedNextCore: []
+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
 
 ```tsx
-<Button
-  label="Save"
-  icon="pi pi-check"
-  variant="primary"
-  rounded
-  onClick={() => console.log("saved")}
-/>
+import Button from '@mantis-core/ui/components/Buttons/Button';
+
+function Example() {
+  return (
+    <Button
+      variant='danger'
+      outlined
+      label='Delete'
+      icon='pi pi-trash'
+      onClick={() => console.log('deleted')}
+    />
+  );
+}
 ```
 
 ## Notes
 
-- PrimeReact props still pass through.
-- `href` triggers client navigation with `next/navigation`.
-- `ButtonVariant` accepts `danger`, but the tokenized SCSS loop is defined around `error`.
+- No `requiredStyles`: fully preset-themed — `buttons.scss` was removed with the PR11 migration.
+- `disabled` is forced `true` while `loading` is `true`.
+- Native `<button>` attributes (except `onClick`/`type`, which are typed above) pass through.

package/docs/components/card-skeleton.md

@@ -0,0 +1,21 @@
+---
+name: CardSkeleton
+category: feedback
+import: '@mantis-core/ui/components/feedback/CardSkeleton'
+whenToUse: Animated skeleton for card-grid layouts while data loads; composes the PR11 Skeleton primitive.
+baseLibrary: '@primereact/ui/skeleton'
+relatedComponents: ['TableSkeleton']
+relatedNextCore: []
+props:
+  - { name: count, type: number, required: false, default: '3' }
+---
+
+## Example
+
+```tsx
+import CardSkeleton from '@mantis-core/ui/components/feedback/CardSkeleton';
+
+function Example() {
+  return <CardSkeleton count={6} />;
+}
+```

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

@@ -0,0 +1,36 @@
+---
+name: ChangePasswordForm
+category: auth
+import: '@mantis-core/ui/components/auth/ChangePasswordForm'
+whenToUse: Current + new + confirm password form for an authenticated user changing their own password.
+baseLibrary: custom
+requiredStyles: []
+relatedComponents: [ResetPasswordForm, LoginForm]
+relatedNextCore: []
+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
+
+```tsx
+import ChangePasswordForm from '@mantis-core/ui/components/auth/ChangePasswordForm';
+import type { ChangePasswordFormValues } from '@mantis-core/ui/components/auth/ChangePasswordForm';
+
+function Example() {
+  const handleSubmit = async (values: ChangePasswordFormValues) => {
+    await fetch('/api/auth/change-password', { method: 'POST', body: JSON.stringify(values) });
+  };
+
+  return <ChangePasswordForm onSubmit={handleSubmit} />;
+}
+```
+
+## Notes
+
+- `confirmPassword`'s match-check against `newPassword` is hardcoded in the component, not a prop.
+- No `subtitle`/`backSlot` props (unlike ForgotPasswordForm) — this form has no "back" affordance.

package/docs/components/checkbox-field.md

@@ -0,0 +1,38 @@
+---
+name: CheckboxField
+category: forms
+import: '@mantis-core/ui/components/Forms/CheckboxField'
+whenToUse: Single boolean checkbox wired to react-hook-form.
+baseLibrary: '@primereact/ui/checkbox'
+formContract: ChoiceFieldControllerProps
+relatedComponents: ['SwitchField', 'RadioGroup']
+relatedNextCore: []
+props: []
+---
+
+## Example
+
+```tsx
+import { CheckboxField } from '@mantis-core/ui/components/Forms/CheckboxField';
+import { useForm } from 'react-hook-form';
+
+function Example() {
+  const { control } = useForm({ defaultValues: { acceptsTerms: false } });
+  return (
+    <CheckboxField
+      name='acceptsTerms'
+      control={control}
+      label='I accept the terms'
+      rules={{ required: 'You must accept.' }}
+    />
+  );
+}
+```
+
+## Notes
+
+- Value is a plain `boolean` (`Boolean(field.value)`).
+- `labelMode` defaults to `'beside'` (not the text-field default `'ifta'`) — `ChoiceFieldControllerProps`
+  only allows `'beside' | 'top' | 'none'`.
+- Wraps PR11 compound `Checkbox.Root` (+ `Checkbox.Box`/`Checkbox.Indicator`); any remaining
+  `CheckboxRootProps` pass through via `...rest`.

package/docs/components/ckeditor-input.md

@@ -1,24 +1,55 @@
-# 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 an HTML string.
+baseLibrary: ckeditor
+requiredStyles: [scss/ckeditor.scss]
+relatedComponents: [RichTextPreview]
+relatedNextCore: []
+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
 
 ```tsx
-<CKEditorInput
-  controller={{ name: "body", control: form.control }}
-  minHeight="20rem"
-  showStats
-  onMetricsChange={(metrics) => console.log(metrics.words)}
-/>
+import CKEditorInput from '@mantis-core/ui/components/Forms/CKEditorInput';
+import { useForm, type FieldValues } from 'react-hook-form';
+
+function Example() {
+  const { control } = useForm<FieldValues>({ defaultValues: { body: '' } });
+  return (
+    <CKEditorInput
+      controller={{ name: 'body', control, rules: { required: true } }}
+      preset='blog'
+    />
+  );
+}
 ```
 
 ## Notes
 
-- This wrapper adds metrics, presets, and optional non-empty HTML validation on top of CKEditor.
+- `controller` is a nested object (legacy pattern), not the flattened `FieldControllerProps` other
+  PR11 field wrappers accept as top-level props.
+- Ships CKEditor's own stylesheet import (`ckeditor5/ckeditor5.css`) so the toolbar/editor render
+  themed with no consumer setup; `requiredStyles: ckeditor.scss` only layers Mantis's wrapper theming
+  (invalid/disabled states) on top.
+- `validateNonEmptyHtml` only activates when `controller.rules.required` is truthy — it strips tags
+  and rejects content that decodes to empty plain text, catching "just an empty `<p></p>`" submits.

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

@@ -0,0 +1,30 @@
+---
+name: ColorPickerInput
+category: forms
+import: '@mantis-core/ui/components/Forms/ColorPickerInput'
+whenToUse: RHF-bound color picker over PR11's compound InputColor (area + sliders + swatch + eyedropper + hex input); value is a hex string.
+baseLibrary: '@primereact/ui/inputcolor'
+formContract: ChoiceFieldControllerProps
+relatedComponents: []
+relatedNextCore: []
+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
+
+```tsx
+import { ColorPickerInput } from '@mantis-core/ui/components/Forms/ColorPickerInput';
+import { useForm } from 'react-hook-form';
+
+function Example() {
+  const { control } = useForm({ defaultValues: { brand: '#276def' } });
+  return <ColorPickerInput name='brand' control={control} label='Color' />;
+}
+```
+
+## Notes
+
+- Value shape: a hex string (e.g. `"#276def"`) for storage/JSON portability — internally converted to/from PR11's `ColorInstance` via `parseColor`.
+- An empty/invalid stored value falls back to `#276def` so `parseColor` never throws.
+- Uses `ChoiceFieldControllerProps` (bucket B), defaults `labelMode` to `top`.

package/docs/components/command-palette.md

@@ -0,0 +1,38 @@
+---
+name: CommandPalette
+category: navigation
+import: '@mantis-core/ui/components/navigation/CommandPalette'
+whenToUse: Keyboard-driven command search overlay (Ctrl/Cmd+K); pair with the `useCommandPalette` hook to wire the shortcut.
+baseLibrary: custom
+relatedComponents: ['Modal']
+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
+import CommandPalette, { useCommandPalette } from '@mantis-core/ui/components/navigation/CommandPalette';
+import { useState } from 'react';
+
+function Example() {
+  const [open, setOpen] = useState(false);
+  useCommandPalette(() => setOpen(true));
+  return (
+    <CommandPalette
+      open={open}
+      onOpenChange={setOpen}
+      commands={[{ id: 'new', label: 'New property', onSelect: () => console.log('new') }]}
+    />
+  );
+}
+```
+
+## Notes
+
+- Renders inside a headerless `size="md"` Modal with a native filter input (no PrimeReact InputText) — filters `commands` by label or `keywords`.
+- `useCommandPalette(onOpen)` is a separate hook export: it binds a `Ctrl/Cmd+K` `keydown` listener that calls `onOpen`; it does not manage the `open` state itself.
+- No `requiredStyles` — preset-themed.