@mantis-core/ui 0.4.0 → 0.6.0

package/docs/components/map-picker-client.md

@@ -1,22 +1,43 @@
-# MapPickerClient
-
-- Export: `MapPickerClient`
-- Extra exports: `MapPickerClientProps`
-- Import: `import { MapPickerClient } from "@mantis-core/ui";`
-- Base library: `react-leaflet` + `leaflet`
-- Base typing: `{ onLocationSelect: (lat: number, lng: number) => void; initialLat?: number | null; initialLng?: number | null }`
-- Required styles: Leaflet CSS is imported by the component
+---
+name: MapPickerClient
+category: maps
+import: '@mantis-core/ui/components/Maps/MapPickerClient'
+whenToUse: Client-only react-leaflet map (click-to-pick marker); the piece MapPicker lazy-loads. Use directly only if you already own the ssr:false boundary.
+baseLibrary: leaflet
+requiredStyles: []
+relatedComponents: [MapPicker, MapPickerOSM]
+relatedNextCore: []
+props:
+  - { name: onLocationSelect, type: '(lat: number, lng: number) => void', required: true, description: 'Fired on map click with the picked coordinates.' }
+  - { name: initialLat, type: 'number | null', required: false, description: 'Initial marker/center latitude; defaults to a fixed Yunguilla-area center when omitted.' }
+  - { name: initialLng, type: 'number | null', required: false, description: 'Initial marker/center longitude; defaults to a fixed Yunguilla-area center when omitted.' }
+---
 
 ## Example
 
 ```tsx
-<MapPickerClient
-  initialLat={-2.9}
-  initialLng={-79.0}
-  onLocationSelect={(lat, lng) => console.log(lat, lng)}
-/>
+'use client';
+import { useState } from 'react';
+import MapPickerClient from '@mantis-core/ui/components/Maps/MapPickerClient';
+
+function Example() {
+  const [coords, setCoords] = useState<{ lat: number; lng: number } | null>(null);
+
+  return (
+    <MapPickerClient
+      onLocationSelect={(lat, lng) => setCoords({ lat, lng })}
+      initialLat={-3.26}
+      initialLng={-79.28}
+    />
+  );
+}
 ```
 
 ## Notes
 
-- Marker assets are expected under `/leaflet/*`.
+- `"use client"` component — imports `leaflet/dist/leaflet.css` and `react-leaflet` directly, so it
+  cannot render during SSR. Prefer `MapPicker` unless the caller already guarantees a client-only tree.
+- Marker icon assets are expected at `/leaflet/marker-icon.png`, `/leaflet/marker-icon-2x.png`,
+  `/leaflet/marker-shadow.png` (served from the consuming app's `public/`).
+- Internally handles container resize (`ResizeObserver` + `map.invalidateSize`) and recenters when
+  `initialLat`/`initialLng` change — no manual `invalidateSize` call needed from the caller.

package/docs/components/map-picker-osm.md

@@ -1,18 +1,38 @@
-# MapPickerOSM
-
-- Export: `MapPickerOSM`
-- Extra exports: `MapPickerOSMProps`, `LatLng`
-- Import: `import { MapPickerOSM } from "@mantis-core/ui";`
-- Base library: Leaflet loaded from CDN
-- Base typing: `{ initialPosition?: LatLng; zoom?: number; height?: string; onChange?: (pos: LatLng) => void; onSave?: (pos: LatLng) => void }`
-- Required styles: no `@mantis-core/styles` partial; Leaflet CSS is injected from CDN
+---
+name: MapPickerOSM
+category: maps
+import: '@mantis-core/ui/components/Maps/MapPickerOSM'
+whenToUse: Script-injected Leaflet map (no react-leaflet/SSR bundle cost) with a draggable marker and an explicit "save location" button.
+baseLibrary: leaflet
+requiredStyles: []
+relatedComponents: [MapPicker, MapPickerClient]
+relatedNextCore: []
+props:
+  - { name: initialPosition, type: LatLng, required: false, default: '{ lat: -12.0464, lng: -77.0428 }', description: 'Initial marker/center position.' }
+  - { name: zoom, type: number, required: false, default: '12' }
+  - { name: height, type: string, required: false, default: '''400px''', description: 'CSS height of the map container.' }
+  - { name: onChange, type: '(pos: LatLng) => void', required: false, description: 'Fired on every click or marker drag.' }
+  - { name: onSave, type: '(pos: LatLng) => void', required: false, description: 'Fired only when the user clicks the "Guardar ubicación" button.' }
+---
 
 ## Example
 
 ```tsx
-<MapPickerOSM
-  initialPosition={{ lat: -12.0464, lng: -77.0428 }}
-  onChange={(pos) => console.log(pos)}
-  onSave={(pos) => saveCoordinates(pos)}
-/>
+'use client';
+import MapPickerOSM from '@mantis-core/ui/components/Maps/MapPickerOSM';
+import type { LatLng } from '@mantis-core/ui/components/Maps/MapPickerOSM';
+
+function Example() {
+  const handleSave = (pos: LatLng) => console.log('saved', pos);
+
+  return <MapPickerOSM initialPosition={{ lat: -3.26, lng: -79.28 }} onSave={handleSave} />;
+}
 ```
+
+## Notes
+
+- Loads Leaflet from the `unpkg.com` CDN at runtime (script + stylesheet injected into
+  `document.head`/`document.body`) instead of importing the `leaflet` package — no bundler cost, but
+  requires network access to `unpkg.com` and has no offline/self-hosted mode.
+- Spanish-only UI strings are hardcoded ("Cargando mapa...", "Guardar ubicación", error text) — not
+  currently prop-configurable.

package/docs/components/map-picker.md

@@ -1,21 +1,39 @@
-# MapPicker
-
-- Export: `MapPicker`
-- Extra exports: `MapPickerProps`
-- Import: `import { MapPicker } from "@mantis-core/ui";`
-- Base library: `next/dynamic` wrapper over `MapPickerClient`
-- Base typing: `{ onLocationSelect: (lat: number, lng: number) => void; initialLat?: number | null; initialLng?: number | null }`
-- Required styles: Leaflet CSS comes from the client implementation
+---
+name: MapPicker
+category: maps
+import: '@mantis-core/ui/components/Maps/MapPicker'
+whenToUse: SSR-safe entry point for the Leaflet lat/lng picker; lazy-loads MapPickerClient via next/dynamic (ssr:false).
+baseLibrary: leaflet
+requiredStyles: []
+relatedComponents: [MapPickerClient, MapPickerOSM]
+relatedNextCore: []
+props:
+  - { name: onLocationSelect, type: '(lat: number, lng: number) => void', required: true, description: 'Fired on map click with the picked coordinates.' }
+  - { name: initialLat, type: 'number | null', required: false }
+  - { name: initialLng, type: 'number | null', required: false }
+---
 
 ## Example
 
 ```tsx
-<MapPicker
-  initialLat={-2.9}
-  initialLng={-79.0}
-  onLocationSelect={(lat, lng) => {
-    form.setValue("lat", lat);
-    form.setValue("lng", lng);
-  }}
-/>
+import { useState } from 'react';
+import MapPicker from '@mantis-core/ui/components/Maps/MapPicker';
+
+function Example() {
+  const [coords, setCoords] = useState<{ lat: number; lng: number } | null>(null);
+
+  return (
+    <MapPicker
+      onLocationSelect={(lat, lng) => setCoords({ lat, lng })}
+      initialLat={-3.26}
+      initialLng={-79.28}
+    />
+  );
+}
 ```
+
+## Notes
+
+- Just a `next/dynamic(() => import('./MapPickerClient'), { ssr: false })` wrapper — use this
+  (not `MapPickerClient` directly) in App Router pages/layouts to avoid a `leaflet` SSR crash.
+- Loading fallback is a plain `<p>Loading map...</p>` (not themed) while the client chunk loads.

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

@@ -1,22 +1,33 @@
-# MenuButton
-
-- Export: `MenuButton`
-- Extra exports: `MenuButtonProps`, `ActionMenuItem`
-- Import: `import { MenuButton } from "@mantis-core/ui";`
-- Base library: `primereact/tieredmenu`
-- Base typing:
-  - `ActionMenuItem extends MenuItem { route?: string; items?: ActionMenuItem[] | ActionMenuItem[][] }`
-  - `MenuButtonProps = { label?: string; icon?: string; items?: ActionMenuItem[] }`
-- Required styles: [`buttons.scss`](../../../../packages/mantis-core-styles/docs/styles/buttons.md) indirectly through `Button`
+---
+name: MenuButton
+category: tables
+import: '@mantis-core/ui/components/Tables/MenuButton'
+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: 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
-  label="Actions"
-  items={[
-    { label: "Edit", icon: "pi pi-pencil", route: "/admin/listings/1" },
-    { label: "Delete", icon: "pi pi-trash", command: () => setOpen(true) },
-  ]}
-/>
+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

@@ -0,0 +1,45 @@
+---
+name: Modal
+category: overlays
+import: '@mantis-core/ui/components/overlays/Modal'
+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: 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
+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

@@ -1,20 +1,36 @@
-# MultiSelectFilter
-
-- Export: `MultiSelectFilter`
-- Import: `import { MultiSelectFilter } from "@mantis-core/ui";`
-- Base library: `primereact/multiselect`
-- Base typing: `Omit<MultiSelectProps, "value" | "onChange"> & { filterProps: ColumnFilterElementTemplateOptions }`
-- Required styles: `@mantis-core/styles/scss/inputs.scss`
+---
+name: MultiSelectFilter
+category: tables
+import: '@mantis-core/ui/components/Tables/filters/MultiSelectFilter'
+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: 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
-filterElement={(filterProps) => (
-  <MultiSelectFilter
-    filterProps={filterProps}
-    options={statusOptions}
-    optionLabel="label"
-    optionValue="value"
-  />
-)}
+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

@@ -0,0 +1,31 @@
+---
+name: OtpInput
+category: forms
+import: '@mantis-core/ui/components/Forms/OtpInput'
+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: 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
+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

@@ -0,0 +1,35 @@
+---
+name: PageTabs
+category: navigation
+import: '@mantis-core/ui/components/navigation/PageTabs'
+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, 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
+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

@@ -1,13 +1,20 @@
-# PageTitle
-
-- Export: `PageTitle`
-- Import: `import { PageTitle } from "@mantis-core/ui";`
-- Base library: custom typographic wrapper
-- Base typing: `PropsWithChildren`
-- Required styles: none
+---
+name: PageTitle
+category: pages
+import: '@mantis-core/ui/components/pages/PageTitle'
+whenToUse: Centered display-font heading for public-facing pages.
+baseLibrary: custom
+relatedNextCore: []
+props:
+  - { name: children, type: ReactNode, required: true }
+---
 
 ## Example
 
 ```tsx
-<PageTitle>Inventory Overview</PageTitle>
+import PageTitle from '@mantis-core/ui/components/pages/PageTitle';
+
+function Example() {
+  return <PageTitle>Propiedades en Venta</PageTitle>;
+}
 ```

package/docs/components/paginated-table.md

@@ -1,35 +1,51 @@
-# PaginatedTable
-
-- Export: `PaginatedTable`
-- Extra exports: `PaginatedTableProps`
-- Import: `import { PaginatedTable } from "@mantis-core/ui";`
-- Base library: `primereact/datatable` + `primereact/column`
-- Base typing: `DataTableBaseProps<TValue> & { showIndexColumn?; showActionColumn?; useMantisCoreStyles?; indexColumnProps?; actionColumnProps?; actionColumnItems? }`
-- Required styles: `@mantis-core/styles/scss/table.scss`
+---
+name: PaginatedTable
+category: tables
+import: '@mantis-core/ui/components/Tables/PaginatedTable'
+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: [MantisDataTable, ActionColumn, IndexColumn, TableToolbar, FilterPannel]
+relatedNextCore: []
+props:
+  - { name: rows, type: 'T[]', required: true }
+  - { name: columns, type: 'ColumnDef<T>[]', required: true }
+  - { name: paginator, type: boolean, required: false, default: 'true', description: 'PR11 Root prop; PaginatedTable flips the MantisDataTable default on.' }
+  - { name: showIndexColumn, type: boolean, required: false, default: 'true', description: 'Prepend a 1-based row-number column.' }
+  - { name: indexColumnOptions, type: 'Partial<ColumnDef<T>>', required: false, description: 'Overrides for the prepended index column.' }
+  - { name: showActionColumn, type: boolean, required: false, default: 'false', description: 'Append a row-action menu column.' }
+  - { name: actionColumnItems, type: '(row: T) => ActionMenuItem[]', required: false, description: 'Per-row action items for the appended action column.' }
+  - { name: actionColumnOptions, type: 'ActionColumnOptions<T>', required: false, description: 'Overrides for the appended action column.' }
+---
 
 ## Example
 
 ```tsx
-import { Column } from "primereact/column";
+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' }];
 
-<PaginatedTable
-  value={rows}
-  totalRecords={total}
-  lazy
-  first={first}
-  rows={pageSize}
-  onPage={onPage}
-  showActionColumn
-  actionColumnItems={(row) => [
-    { label: "Edit", icon: "pi pi-pencil", route: `/admin/listings/${row.id}` },
-  ]}
->
-  <Column field="name" header="Name" sortable />
-  <Column field="status" header="Status" />
-</PaginatedTable>
+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

@@ -1,27 +1,37 @@
-# Pagination, PaginationInfo, and PageSizeSelector
-
-- Exports: `Pagination`, `PaginationInfo`, `PageSizeSelector`
-- Extra exports: `PaginationProps`, `PaginationInfoProps`, `PageSizeSelectorProps`
-- Import: `import { Pagination, PaginationInfo, PageSizeSelector } from "@mantis-core/ui";`
-- Base library: custom pagination UI using `@mantis-core/utils`
-- Required styles: none
+---
+name: Pagination
+category: feedback
+import: '@mantis-core/ui/components/ui/Pagination'
+whenToUse: Standalone page-number control (custom Tailwind markup, not PrimeReact Paginator); use when not relying on PaginatedTable's built-in paginator.
+baseLibrary: custom
+relatedComponents: ['PaginatedTable']
+relatedNextCore: []
+props:
+  - { name: currentPage, type: number, required: true }
+  - { name: totalPages, type: number, required: true }
+  - { name: onPageChange, type: '(page: number) => void', required: true }
+  - { name: hasNextPage, type: boolean, required: false, default: 'currentPage < totalPages' }
+  - { name: hasPreviousPage, type: boolean, required: false, default: 'currentPage > 1' }
+  - { name: maxVisible, type: number, required: false, default: '7' }
+  - { name: showFirstLast, type: boolean, required: false, default: 'true' }
+  - { name: disabled, type: boolean, required: false, default: 'false' }
+  - { name: className, type: string, required: false }
+---
 
 ## Example
 
 ```tsx
-<Pagination
-  currentPage={page}
-  totalPages={totalPages}
-  onPageChange={setPage}
-  maxVisible={5}
-/>
-
-<PaginationInfo currentPage={page} pageSize={pageSize} totalCount={total} />
+import { Pagination } from '@mantis-core/ui/components/ui/Pagination';
+import { useState } from 'react';
 
-<PageSizeSelector pageSize={pageSize} onPageSizeChange={setPageSize} />
+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.