@mantis-core/ui 0.5.0 → 0.6.0

package/docs/components/mask-field.md

@@ -0,0 +1,31 @@
+---
+name: MaskField
+category: forms
+import: '@mantis-core/ui/components/Forms/MaskField'
+whenToUse: Generic masked text input (digit/letter/alphanumeric tokens) wired to react-hook-form; value is the masked display string.
+baseLibrary: '@primereact/ui/inputtext'
+formContract: FieldControllerProps
+relatedComponents: ['PhoneInput', 'TextField']
+relatedNextCore: []
+props:
+  - { name: mask, type: string, required: true, description: "Pattern: '9'=digit, 'a'=letter, '*'=alphanumeric; any other character is a literal emitted automatically." }
+---
+
+## Example
+
+```tsx
+import { MaskField } from '@mantis-core/ui/components/Forms/MaskField';
+import { useForm } from 'react-hook-form';
+
+function Example() {
+  const { control } = useForm({ defaultValues: { code: '' } });
+  return <MaskField name='code' control={control} mask='999-999' label='Code' />;
+}
+```
+
+## Notes
+
+- PR11 dropped the `inputmask` primitive — this wrapper owns masking itself over plain `InputText`, no `react-imask` dependency.
+- Value = the **masked** string as displayed (e.g. `"(555) 123-4567"`), not the raw digits — that's exactly what gets stored in the form.
+- Also exports `applyMask(raw, mask)`, the pure formatter used internally, for previewing/testing a mask outside the field.
+- `PhoneInput` is the phone preset built on top of this (`mask="(999) 999-9999"` by default).

package/docs/components/menu-button.md

@@ -2,17 +2,32 @@
 name: MenuButton
 category: tables
 import: '@mantis-core/ui/components/Tables/MenuButton'
-whenToUse: Dropdown button with a list of actions; used inside table rows.
-baseLibrary: primereact/tieredmenu
-relatedComponents: [ActionColumn]
+whenToUse: 'Row-action overlay menu — a trigger button that opens a popup list of actions; used inside `actionColumn`/table row cells, or standalone.'
+baseLibrary: '@primereact/ui/menu'
+relatedComponents: [ActionColumn, MantisDataTable]
 relatedNextCore: []
 props:
-  - { name: items, type: 'ActionMenuItem[]', required: true }
-  - { name: label, type: string, required: false }
-  - { name: icon, type: string, required: false }
+  - { 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
 
 ```tsx
-<MenuButton items={[{ label: 'Edit', command: onEdit }, { label: 'Delete', command: onDelete }]} />
+import MenuButton, { type ActionMenuItem } from '@mantis-core/ui/components/Tables/MenuButton';
+
+function Example() {
+  const items: ActionMenuItem[] = [
+    { label: 'Edit', icon: 'pi pi-pencil', route: '/properties/1/edit' },
+    { label: 'Delete', icon: 'pi pi-trash', command: () => console.log('delete') },
+  ];
+  return <MenuButton items={items} label='Actions' />;
+}
 ```
+
+## Notes
+
+- Not re-exported from the package root — import the deep path.
+- `ActionMenuItem`: `label`, `icon?`, `route?` (navigates via `next/router`, wins over `command`), `command?` (ignored when `route` is set), `disabled?` (never fires `onSelect`).
+- Migrated to PR11's compound `Menu`: `Menu.Root` owns its own open state; the trigger renders the migrated `Button` via `Menu.Trigger as={Button}` — PR11's `asChild` does NOT wire the trigger (no `aria-haspopup`, overlay never opens), so the `as` prop is required.

package/docs/components/modal.md

@@ -2,19 +2,44 @@
 name: Modal
 category: overlays
 import: '@mantis-core/ui/components/overlays/Modal'
-whenToUse: Dialog/modal (PrimeReact Dialog wrapper); dismissable mask and non-draggable by default.
-baseLibrary: custom
+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.
+baseLibrary: '@primereact/ui/dialog'
+relatedComponents: ['Drawer', 'ConfirmDialog', 'CommandPalette']
 relatedNextCore: []
 props:
-  - { name: visible, type: boolean, required: true }
-  - { name: onHide, type: '() => void', required: true }
-  - { name: header, type: ReactNode, required: false }
-  - { name: footer, type: ReactNode, required: false }
-  - { name: style, type: CSSProperties, required: false }
-  - { name: className, type: string, required: false }
+  - { 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
 
 ```tsx
-<Modal visible={showModal} onHide={() => setShowModal(false)} header='Editar propiedad' style={{ width: '40rem' }}><PropertyForm /></Modal>
+import Modal from '@mantis-core/ui/components/overlays/Modal';
+import { useState } from 'react';
+
+function Example() {
+  const [open, setOpen] = useState(false);
+  return (
+    <Modal
+      open={open}
+      onOpenChange={setOpen}
+      title='Edit property'
+      size='lg'
+      footer={<button onClick={() => setOpen(false)}>Close</button>}>
+      <p>Modal content</p>
+    </Modal>
+  );
+}
 ```
+
+## Notes
+
+- Controlled-only: `open`/`onOpenChange`, not `visible`/`onHide` — matches PR11's Root controlled-state naming.
+- Width is a class on the Popup (from the `size` preset), not a `style` prop; override via `className` for custom widths.
+- No `requiredStyles` — preset-themed.

package/docs/components/multi-select-filter.md

@@ -2,17 +2,35 @@
 name: MultiSelectFilter
 category: tables
 import: '@mantis-core/ui/components/Tables/filters/MultiSelectFilter'
-whenToUse: PrimeReact MultiSelect wired for use as a DataTable column filter template.
-baseLibrary: primereact/multiselect
-relatedComponents: [FilterPannel]
+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.'
+baseLibrary: '@primereact/ui/select'
+relatedComponents: [FilterPannel, MantisDataTable]
 relatedNextCore: []
 props:
-  - { name: filterProps, type: ColumnFilterElementTemplateOptions, required: true }
-  - { name: options, type: 'any[]', required: false }
-  - { name: loading, type: boolean, required: false }
+  - { 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
 
 ```tsx
-<Column field='status' filterElement={(opts) => <MultiSelectFilter filterProps={opts} options={statusOptions} />} />
+import MultiSelectFilter from '@mantis-core/ui/components/Tables/filters/MultiSelectFilter';
+import { useState } from 'react';
+
+function Example() {
+  const [selected, setSelected] = useState<string[]>([]);
+  const options = [
+    { label: 'Active', value: 'active' },
+    { label: 'Draft', value: 'draft' },
+  ];
+  return <MultiSelectFilter options={options} value={selected} onChange={setSelected} />;
+}
 ```
+
+## Notes
+
+- Not re-exported from the package root — import the deep path.
+- Migrated replacement for the PR10 `primereact/multiselect`; page-owned `value`/`onChange` (not RHF), so it fits `ColumnDef.filterElement` directly — it does not accept the scalar `{ value, onChange }` shape used by the built-in `text`/`dropdown` filter presets.

package/docs/components/number-field.md

@@ -0,0 +1,40 @@
+---
+name: NumberField
+category: forms
+import: '@mantis-core/ui/components/Forms/NumberField'
+whenToUse: Numeric input (integer, decimal, or currency) wired to react-hook-form.
+baseLibrary: '@primereact/ui/inputnumber'
+formContract: FieldControllerProps
+relatedComponents: ['TextField', 'SelectField']
+relatedNextCore: []
+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
+
+```tsx
+import { NumberField } from '@mantis-core/ui/components/Forms/NumberField';
+import { useForm } from 'react-hook-form';
+
+function Example() {
+  const { control } = useForm({ defaultValues: { price: null as number | null } });
+  return (
+    <NumberField name='price' control={control} label='Price' mode='currency' currency='USD' />
+  );
+}
+```
+
+## Notes
+
+- Value is `number | null` — an emptied input normalizes to `null` (not `NaN`), so `number | null`
+  RHF fields can actually be cleared.
+- Compound primitive: emits `onValueChange` with a `{ value }` event, not native `onChange`. The
+  wrapper handles this internally; callers just get a plain controlled number value.
+- Root config (`mode`, `currency`, `locale`, `min`, `max`, `step`, …) lives on `InputNumberRootProps`
+  and passes through via `...rest`.

package/docs/components/otp-input.md

@@ -2,17 +2,30 @@
 name: OtpInput
 category: forms
 import: '@mantis-core/ui/components/Forms/OtpInput'
-whenToUse: One-time password input (PrimeReact InputOtp) wired to react-hook-form.
-baseLibrary: custom
-formContract: ControllerProps
+whenToUse: RHF-bound one-time-password input over PR11's compound InputOtp; renders `length` segmented boxes.
+baseLibrary: '@primereact/ui/inputotp'
+formContract: ChoiceFieldControllerProps
+relatedComponents: []
 relatedNextCore: []
 props:
-  - { name: controller, type: ControllerProps, required: true }
-  - { name: length, type: number, required: false, default: '6' }
-  - { name: block, type: boolean, required: false }
+  - { 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
 
 ```tsx
-<OtpInput controller={{ name: 'otp', rules: { required: true } }} length={6} />
+import { OtpInput } from '@mantis-core/ui/components/Forms/OtpInput';
+import { useForm } from 'react-hook-form';
+
+function Example() {
+  const { control } = useForm({ defaultValues: { code: '' } });
+  return <OtpInput name='code' control={control} label='Código' length={6} integerOnly />;
+}
 ```
+
+## Notes
+
+- Value shape: the concatenated `string` code, `""` when unset. Typing advances focus, backspace retreats, paste distributes across slots.
+- Uses `ChoiceFieldControllerProps` (bucket B) — no `labelMode="float"`/addons/`variant`, defaults `labelMode` to `top`.

package/docs/components/page-tabs.md

@@ -2,15 +2,34 @@
 name: PageTabs
 category: navigation
 import: '@mantis-core/ui/components/navigation/PageTabs'
-whenToUse: Tab menu bar for page-level navigation; auto-detects active tab from Next.js pathname when tabs have href.
-baseLibrary: custom
+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.
+baseLibrary: '@primereact/ui/tabs'
+relatedComponents: ['AppShell']
 relatedNextCore: []
 props:
   - { name: tabs, type: '{ label: string; icon?: ReactNode; href?: string; command?: () => void }[]', required: true }
-  - { name: activeIndex, type: number, required: false }
+  - { 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
 
 ```tsx
-<PageTabs tabs={[{ label: 'General', href: '/admin/settings' }, { label: 'Seguridad', href: '/admin/settings/security' }]} />
+import PageTabs from '@mantis-core/ui/components/navigation/PageTabs';
+
+function Example() {
+  return (
+    <PageTabs
+      tabs={[
+        { label: 'General', href: '/admin/settings' },
+        { label: 'Security', href: '/admin/settings/security' },
+      ]}
+    />
+  );
+}
 ```
+
+## Notes
+
+- This is a nav bar, not a tabbed content panel — selecting a tab pushes `href` or runs `command`, it does not toggle any `Tabs.Panel`.
+- No `requiredStyles` — preset-themed.

package/docs/components/page-title.md

@@ -8,8 +8,13 @@ relatedNextCore: []
 props:
   - { name: children, type: ReactNode, required: true }
 ---
+
 ## Example
 
 ```tsx
-<PageTitle>Propiedades en Venta</PageTitle>
+import PageTitle from '@mantis-core/ui/components/pages/PageTitle';
+
+function Example() {
+  return <PageTitle>Propiedades en Venta</PageTitle>;
+}
 ```

package/docs/components/paginated-table.md

@@ -2,27 +2,50 @@
 name: PaginatedTable
 category: tables
 import: '@mantis-core/ui/components/Tables/PaginatedTable'
-whenToUse: 'Generic server-side paginated DataTable with built-in index column, action column, and Mantis Core CSS. Wraps PrimeReact DataTable.'
-baseLibrary: primereact/datatable
+whenToUse: 'Thin preset over MantisDataTable with `paginator` on by default plus optional index/action columns — the default table shell for admin list pages.'
+baseLibrary: '@primereact/ui/datatable'
 requiredStyles: [scss/table.scss]
-relatedComponents: [ActionColumn, IndexColumn, TableToolbar, FilterPannel]
+relatedComponents: [MantisDataTable, ActionColumn, IndexColumn, TableToolbar, FilterPannel]
 relatedNextCore: []
 props:
-  - { name: value, type: TValue, required: true }
-  - { name: totalRecords, type: number, required: false }
-  - { name: showIndexColumn, type: boolean, required: false, default: 'true' }
-  - { name: showActionColumn, type: boolean, required: false, default: 'false' }
-  - { name: actionColumnItems, type: '(rowData: TValue[number]) => ActionMenuItem[]', required: false }
-  - { name: useMantisCoreStyles, type: boolean, required: false, default: 'true' }
-  - { name: lazy, type: boolean, required: false, default: 'true' }
+  - { 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
 
 ```tsx
-<PaginatedTable value={rows} totalRecords={total} showActionColumn actionColumnItems={(row) => [{ label: 'Edit', command: () => edit(row) }]}><Column field='name' header='Name' /></PaginatedTable>
+import { PaginatedTable } from '@mantis-core/ui/components/Tables/PaginatedTable';
+import type { ColumnDef } from '@mantis-core/ui/components/Tables/columns';
+
+interface Property {
+  id: string;
+  name: string;
+}
+
+const COLUMNS: ColumnDef<Property>[] = [{ field: 'name', header: 'Name' }];
+
+function Example() {
+  const rows: Property[] = [{ id: '1', name: 'Casa Ceibos' }];
+  return (
+    <PaginatedTable
+      rows={rows}
+      columns={COLUMNS}
+      rowsPerPage={10}
+      showActionColumn
+      actionColumnItems={(p) => [{ label: 'Edit', route: `/properties/${p.id}/edit` }]}
+    />
+  );
+}
 ```
 
 ## Notes
 
-- It sets Mantis defaults for pagination, stripes, gridlines, sorting, empty state, and responsive layout.
-- Set `useMantisCoreStyles={false}` only if you want plain PrimeReact styling.
+- Reshaped from the PR10 children-driven `PaginatedTable` to the descriptor-driven PR11 model: it assembles the final `columns` array (index column prepended, action column appended) and forwards everything else — including `rows`, `rowsPerPage`, and any other `MantisDataTableProps<T>`/PR11 root passthrough — straight to `MantisDataTable`.
+- The old `value`/`totalRecords`/`lazy` prop shape is gone; use `rows`/`columns`/`rowsPerPage` and the PR11 root passthrough (`paginator`, `lazy`, `onLazyLoad`, …) documented on `MantisDataTable`.

package/docs/components/pagination.md

@@ -2,23 +2,36 @@
 name: Pagination
 category: feedback
 import: '@mantis-core/ui/components/ui/Pagination'
-whenToUse: Standalone pagination control; use when not relying on PaginatedTable's built-in paginator.
+whenToUse: Standalone page-number control (custom Tailwind markup, not PrimeReact Paginator); use when not relying on PaginatedTable's built-in paginator.
 baseLibrary: custom
-relatedComponents: [PaginationInfo, PageSizeSelector]
+relatedComponents: ['PaginatedTable']
 relatedNextCore: []
 props:
-  - { name: totalRecords, type: number, required: true }
-  - { name: pageSize, type: number, required: true }
   - { 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
 
 ```tsx
-<Pagination totalRecords={200} pageSize={20} currentPage={page} onPageChange={setPage} />
+import { Pagination } from '@mantis-core/ui/components/ui/Pagination';
+import { useState } from 'react';
+
+function Example() {
+  const [page, setPage] = useState(1);
+  return <Pagination currentPage={page} totalPages={12} onPageChange={setPage} />;
+}
 ```
 
 ## Notes
 
-- This is not PrimeReact `Paginator`.
-- `paginator.scss` styles PrimeReact paginator markup, not these exports.
+- Renders `null` when `totalPages <= 1`.
+- Same import path also exports `PaginationInfo` — `{ currentPage, pageSize, totalCount, className? }`, a "Showing X to Y of Z results" line — and `PageSizeSelector` — `{ pageSize, onPageSizeChange, options?: number[] (default `[10, 25, 50, 100]`), disabled?, className? }`, a page-size `<select>`.
+- `paginator.scss` styles PrimeReact's own paginator markup (used e.g. by `PaginatedTable`), not this component — no `requiredStyles` here.

package/docs/components/password-input.md

@@ -2,18 +2,30 @@
 name: PasswordInput
 category: forms
 import: '@mantis-core/ui/components/Forms/PasswordInput'
-whenToUse: 'Password field with show/hide toggle; Controller pattern, same API as TextInput.'
-baseLibrary: custom
-formContract: ControllerProps
-requiredStyles: [scss/inputs.scss]
+whenToUse: RHF-bound password field over PR11 InputPassword with a native show/hide toggle and a lightweight strength meter.
+baseLibrary: '@primereact/ui/inputpassword'
+formContract: FieldControllerProps
+relatedComponents: ['TextField']
 relatedNextCore: []
 props:
-  - { name: controller, type: ControllerProps, required: true }
-  - { name: block, type: boolean, required: false }
-  - { name: showToggle, type: boolean, required: false, default: 'true' }
+  - { 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
 
 ```tsx
-<PasswordInput controller={{ name: 'password', rules: notEmptyRule() }} block />
+import { PasswordInput } from '@mantis-core/ui/components/Forms/PasswordInput';
+import { useForm } from 'react-hook-form';
+
+function Example() {
+  const { control } = useForm({ defaultValues: { password: '' } });
+  return <PasswordInput name='password' control={control} label='Contraseña' rules={{ required: true }} />;
+}
 ```
+
+## Notes
+
+- Show/hide uses PR11 `InputPassword`'s own native mask state (`mask`/`onMaskChange`), not a custom-positioned button.
+- `feedback` renders a deterministic 0–4 strength score from length + character-class variety — not zxcvbn or any external scoring lib.
+- `variant`/`size` are not exposed: `InputPasswordProps` doesn't carry them in `11.0.0-rc.1`, unlike `TextField`.

package/docs/components/phone-input.md

@@ -2,17 +2,27 @@
 name: PhoneInput
 category: forms
 import: '@mantis-core/ui/components/Forms/PhoneInput'
-whenToUse: Masked phone number input; default mask (999) 999-9999.
-baseLibrary: custom
-formContract: ControllerProps
+whenToUse: Phone-number preset of MaskField; defaults to a US-style (999) 999-9999 mask.
+baseLibrary: '@primereact/ui/inputtext'
+formContract: FieldControllerProps
+relatedComponents: ['MaskField']
 relatedNextCore: []
 props:
-  - { name: controller, type: ControllerProps, required: true }
-  - { name: mask, type: string, required: false, default: '''(999) 999-9999''' }
-  - { name: block, type: boolean, required: false }
+  - { name: mask, type: string, required: false, default: "'(999) 999-9999'", description: 'Override the phone mask for other formats.' }
 ---
+
 ## Example
 
 ```tsx
-<PhoneInput controller={{ name: 'phone', rules: { required: true } }} block />
+import { PhoneInput } from '@mantis-core/ui/components/Forms/PhoneInput';
+import { useForm } from 'react-hook-form';
+
+function Example() {
+  const { control } = useForm({ defaultValues: { phone: '' } });
+  return <PhoneInput name='phone' control={control} label='Teléfono' />;
+}
 ```
+
+## Notes
+
+- Thin preset over `MaskField` — no rendering logic of its own, just a default `mask`. Value = the masked string (e.g. `"(555) 123-4567"`).

package/docs/components/radio-group.md

@@ -2,19 +2,49 @@
 name: RadioGroup
 category: forms
 import: '@mantis-core/ui/components/Forms/RadioGroup'
-whenToUse: Renders a set of radio buttons from an options array; value is the selected option's value.
-baseLibrary: custom
-formContract: ControllerProps
+whenToUse: Single-choice radio group over PR11's RadioButtonGroup; value is the selected option's value.
+baseLibrary: '@primereact/ui/radiobutton'
+formContract: ChoiceFieldControllerProps
+relatedComponents: ['ToggleInlineButton', 'SelectField']
 relatedNextCore: []
 props:
-  - { name: controller, type: ControllerProps, required: true }
-  - { name: options, type: '{ label: string; value: any }[]', required: true }
-  - { name: block, type: boolean, required: false }
-  - { name: disabled, type: boolean, required: false }
-  - { name: className, type: string, required: false }
+  - { 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
 
 ```tsx
-<RadioGroup controller={{ name: 'role' }} options={[{ label: 'Admin', value: 'admin' }, { label: 'User', value: 'user' }]} />
+import { RadioGroup } from '@mantis-core/ui/components/Forms/RadioGroup';
+import { useForm } from 'react-hook-form';
+
+const PLANS = [
+  { label: 'Basic', value: 'basic' },
+  { label: 'Pro', value: 'pro' },
+];
+
+function Example() {
+  const { control } = useForm({ defaultValues: { plan: 'basic' } });
+  return (
+    <RadioGroup
+      name='plan'
+      control={control}
+      label='Plan'
+      options={PLANS}
+      optionLabel='label'
+      optionValue='value'
+    />
+  );
+}
 ```
+
+## Notes
+
+- `labelMode` defaults to `'top'` for this wrapper (not the global config default).
+- PR11 `11.0.0-rc.1` gotcha: the styled `RadioButtonGroup` and `RadioButton.Root` are wired through
+  two different React contexts in this rc, so the group's `value`/`onValueChange` never reaches its
+  children (verified in-browser). Until fixed upstream, this wrapper binds each `RadioButton.Root`
+  individually via its documented `checked`/`onCheckedChange` props; `RadioButtonGroup` itself is
+  used for layout/styling only, not for value propagation.

package/docs/components/range-slider.md

@@ -2,19 +2,31 @@
 name: RangeSlider
 category: forms
 import: '@mantis-core/ui/components/Forms/RangeSlider'
-whenToUse: 'Dual-handle range slider that stores a [min, max] tuple; backed by PrimeReact Slider.'
-baseLibrary: custom
-formContract: ControllerProps
+whenToUse: RHF-bound slider over PR11's compound Slider; single-handle by default, dual-handle range when the field holds a [number, number] tuple.
+baseLibrary: '@primereact/ui/slider'
+formContract: ChoiceFieldControllerProps
+relatedComponents: []
 relatedNextCore: []
 props:
-  - { name: controller, type: ControllerProps, required: true }
   - { name: min, type: number, required: false }
   - { name: max, type: number, required: false }
   - { name: step, type: number, required: false }
-  - { name: block, type: boolean, required: false }
+  - { name: orientation, type: "'horizontal' | 'vertical'", required: false }
 ---
+
 ## Example
 
 ```tsx
-<RangeSlider controller={{ name: 'priceRange' }} min={0} max={500000} step={1000} block />
+import { RangeSlider } from '@mantis-core/ui/components/Forms/RangeSlider';
+import { useForm } from 'react-hook-form';
+
+function Example() {
+  const { control } = useForm({ defaultValues: { price: 100 } });
+  return <RangeSlider name='price' control={control} label='Precio' min={0} max={500} />;
+}
 ```
+
+## Notes
+
+- Value shape mirrors PR11 `Slider`: a scalar `number` (single handle) by default, or a `[number, number]` tuple (two handles) when the RHF field holds an array.
+- Uses `ChoiceFieldControllerProps` (bucket B); `labelMode` defaults to `top` — a squeezed inline slider is unusable beside a label.

package/docs/components/rating-input.md

@@ -2,18 +2,29 @@
 name: RatingInput
 category: forms
 import: '@mantis-core/ui/components/Forms/RatingInput'
-whenToUse: Star rating input (PrimeReact Rating) wired to react-hook-form; stores numeric value.
-baseLibrary: custom
-formContract: ControllerProps
+whenToUse: RHF-bound star rating over PR11's compound Rating; stores a numeric value.
+baseLibrary: '@primereact/ui/rating'
+formContract: ChoiceFieldControllerProps
+relatedComponents: []
 relatedNextCore: []
 props:
-  - { name: controller, type: ControllerProps, required: true }
-  - { name: stars, type: number, required: false, default: '5' }
-  - { name: cancel, type: boolean, required: false }
-  - { name: block, type: boolean, required: false }
+  - { name: stars, type: number, required: false, default: '5', description: 'How many star options render.' }
 ---
+
 ## Example
 
 ```tsx
-<RatingInput controller={{ name: 'score' }} stars={5} />
+import { RatingInput } from '@mantis-core/ui/components/Forms/RatingInput';
+import { useForm } from 'react-hook-form';
+
+function Example() {
+  const { control } = useForm({ defaultValues: { score: null as number | null } });
+  return <RatingInput name='score' control={control} label='Puntaje' stars={5} />;
+}
 ```
+
+## Notes
+
+- Value shape: `number` (stars selected), `null` when unset.
+- Whole-star by default (`allowHalf={false}`) so the bound value stays an integer score; pass `allowHalf` to opt back into PR11's half-star behavior.
+- Uses `ChoiceFieldControllerProps` (bucket B); `labelMode` defaults to `top`.