@mantis-core/ui 0.4.0 → 0.6.0

package/docs/components/password-input.md

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

@@ -0,0 +1,28 @@
+---
+name: PhoneInput
+category: forms
+import: '@mantis-core/ui/components/Forms/PhoneInput'
+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: mask, type: string, required: false, default: "'(999) 999-9999'", description: 'Override the phone mask for other formats.' }
+---
+
+## Example
+
+```tsx
+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

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

@@ -0,0 +1,32 @@
+---
+name: RangeSlider
+category: forms
+import: '@mantis-core/ui/components/Forms/RangeSlider'
+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: min, type: number, required: false }
+  - { name: max, type: number, required: false }
+  - { name: step, type: number, required: false }
+  - { name: orientation, type: "'horizontal' | 'vertical'", required: false }
+---
+
+## Example
+
+```tsx
+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

@@ -0,0 +1,30 @@
+---
+name: RatingInput
+category: forms
+import: '@mantis-core/ui/components/Forms/RatingInput'
+whenToUse: RHF-bound star rating over PR11's compound Rating; stores a numeric value.
+baseLibrary: '@primereact/ui/rating'
+formContract: ChoiceFieldControllerProps
+relatedComponents: []
+relatedNextCore: []
+props:
+  - { name: stars, type: number, required: false, default: '5', description: 'How many star options render.' }
+---
+
+## Example
+
+```tsx
+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`.

package/docs/components/render-field.md

@@ -1,24 +1,47 @@
-# RenderField
-
-- Export: `RenderField`
-- Extra exports: `RenderFieldProps`
-- Import: `import { RenderField } from "@mantis-core/ui";`
-- Base library: `react-hook-form` `Controller`
-- Base typing: `{ name: string; defaultValue?: any; control?: Control; render: (props: RenderProps) => ReactElement; rules?: RegisterOptions }`
-- Required styles: none
+---
+name: RenderField
+category: forms
+import: '@mantis-core/ui/components/Forms/RenderField'
+whenToUse: 'Low-level escape hatch wrapping react-hook-form''s Controller via a render prop; use to wire any custom or third-party input without building a full FieldControllerProps wrapper.'
+baseLibrary: custom
+relatedComponents: ['FormFieldRender', 'useFieldController']
+relatedNextCore: []
+props:
+  - { name: name, type: string, required: true }
+  - { name: render, type: '(props: { field, fieldState, formState, value }) => ReactElement', required: true }
+  - { name: defaultValue, type: any, required: false }
+  - { name: rules, type: RegisterOptions, required: false }
+  - { name: control, type: Control, required: false }
+---
 
 ## Example
 
 ```tsx
-<RenderField
-  name="featured"
-  control={form.control}
-  render={({ field }) => (
-    <input
-      type="checkbox"
-      checked={!!field.value}
-      onChange={(e) => field.onChange(e.target.checked)}
+import RenderField from '@mantis-core/ui/components/Forms/RenderField';
+import { useForm, type FieldValues } from 'react-hook-form';
+
+function Example() {
+  const { control } = useForm<FieldValues>({ defaultValues: { rating: 0 } });
+  return (
+    <RenderField
+      name='rating'
+      control={control}
+      render={({ field }) => (
+        <input
+          type='number'
+          value={field.value}
+          onChange={(e) => field.onChange(Number(e.target.value))}
+        />
+      )}
     />
-  )}
-/>
+  );
+}
 ```
+
+## Notes
+
+- Thin pass-through over RHF's `<Controller>` — `field`/`fieldState`/`formState`/`control` are
+  untyped (`any`-form), unlike `FieldControllerProps`, which types `name`/`defaultValue`/`rules` by
+  path against the caller's form shape.
+- No presentation (label/help/error/aria) — pair with `FormFieldRender` or `ErrorMessage` for that,
+  or build a proper wrapper with `useFieldController` + `FieldShell` if it will be reused.

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

@@ -0,0 +1,37 @@
+---
+name: ResetPasswordForm
+category: auth
+import: '@mantis-core/ui/components/auth/ResetPasswordForm'
+whenToUse: New password + confirm-password form for a reset-token flow; caller owns token validation and the API call.
+baseLibrary: custom
+requiredStyles: []
+relatedComponents: [ForgotPasswordForm, ChangePasswordForm, LoginForm]
+relatedNextCore: []
+props:
+  - { name: onSubmit, type: '(values: ResetPasswordFormValues) => void | Promise<void>', required: true, description: 'Receives { newPassword, confirmPassword }; form manages isSubmitting via RHF.' }
+  - { name: title, type: string, required: false, default: '"Nueva contraseña"' }
+  - { name: subtitle, type: string, required: false }
+  - { name: submitLabel, type: string, required: false, default: '"Guardar 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 ResetPasswordForm from '@mantis-core/ui/components/auth/ResetPasswordForm';
+import type { ResetPasswordFormValues } from '@mantis-core/ui/components/auth/ResetPasswordForm';
+
+function Example() {
+  const handleSubmit = async ({ newPassword }: ResetPasswordFormValues) => {
+    await fetch('/api/auth/reset-password', { method: 'POST', body: JSON.stringify({ newPassword }) });
+  };
+
+  return <ResetPasswordForm onSubmit={handleSubmit} minPasswordLength={10} />;
+}
+```
+
+## Notes
+
+- `confirmPassword`'s match-check (`v === watch('newPassword')`) is hardcoded in the component, not
+  a prop — it is not configurable beyond `minPasswordLength`.

package/docs/components/rich-text-preview.md

@@ -1,18 +1,31 @@
-# RichTextPreview
-
-- Export: `RichTextPreview`
-- Extra exports: `RichTextPreviewProps`
-- Import: `import { RichTextPreview } from "@mantis-core/ui";`
-- Base library: sanitized HTML renderer via `@mantis-core/utils`
-- Base typing: `{ html?: string | null; className?: string; sanitize?: boolean; size?: "sm" | "md" | "lg"; emptyFallback?: ReactNode }`
-- Required styles: `@mantis-core/styles/scss/rich-text-preview.scss`
+---
+name: RichTextPreview
+category: feedback
+import: '@mantis-core/ui/components/ui/RichTextPreview'
+whenToUse: Safely renders a CKEditor HTML string (sanitized by default) with CKEditor content styles applied.
+baseLibrary: custom
+requiredStyles: [scss/rich-text-preview.scss]
+relatedComponents: ['CKEditorInput']
+relatedNextCore: []
+props:
+  - { name: html, type: 'string | null', required: false, description: 'HTML source. `null`/undefined is treated as empty.' }
+  - { name: className, type: string, required: false }
+  - { name: sanitize, type: boolean, required: false, default: 'true', description: 'Runs the HTML through `sanitizeHtmlContent` (`@mantis-core/utils`) before rendering.' }
+  - { name: size, type: "'sm' | 'md' | 'lg'", required: false, default: "'md'" }
+  - { name: emptyFallback, type: ReactNode, required: false, default: 'null', description: 'Rendered instead when the (sanitized) content is empty/whitespace-only.' }
+---
 
 ## Example
 
 ```tsx
-<RichTextPreview
-  html={post.bodyHtml}
-  size="lg"
-  emptyFallback={<p>No content yet.</p>}
-/>
+import RichTextPreview from '@mantis-core/ui/components/ui/RichTextPreview';
+
+function Example() {
+  return <RichTextPreview html={'<p>Hello <strong>world</strong></p>'} size='md' />;
+}
 ```
+
+## Notes
+
+- Renders via `dangerouslySetInnerHTML` — keep `sanitize` on (default) for any untrusted HTML source.
+- Applies the `ck-content` class so CKEditor's own content styles apply to the preview.

package/docs/components/search-input.md

@@ -0,0 +1,30 @@
+---
+name: SearchInput
+category: forms
+import: '@mantis-core/ui/components/Forms/SearchInput'
+whenToUse: RHF-bound search box over PR11 InputText with a search icon and a debounced onSearch callback; ideal for live table/list filtering.
+baseLibrary: '@primereact/ui/inputtext'
+formContract: FieldControllerProps
+relatedComponents: ['TextField']
+relatedNextCore: []
+props:
+  - { name: onSearch, type: '(value: string) => void', required: false, description: 'Fires debounced with the current value on each change.' }
+  - { name: debounceMs, type: number, required: false, default: '300' }
+---
+
+## Example
+
+```tsx
+import { SearchInput } from '@mantis-core/ui/components/Forms/SearchInput';
+import { useForm } from 'react-hook-form';
+
+function Example() {
+  const { control } = useForm({ defaultValues: { q: '' } });
+  return <SearchInput name='q' control={control} label='Buscar' onSearch={(value) => console.log(value)} />;
+}
+```
+
+## Notes
+
+- The RHF field itself updates immediately (undebounced); only `onSearch` is debounced — use the field's `value` for the input, `onSearch` for the expensive call (query/filter).
+- A clear (✕) icon appears once the field is non-empty and resets both the field and `onSearch("")`.

package/docs/components/select-field.md

@@ -0,0 +1,55 @@
+---
+name: SelectField
+category: forms
+import: '@mantis-core/ui/components/Forms/SelectField'
+whenToUse: Single- or multi-select dropdown wired to react-hook-form over PR11's portal-based Select; pass `multiple` for array-value mode. Absorbs the former Select/DropDown/MultiSelect.
+baseLibrary: '@primereact/ui/select'
+formContract: FieldControllerProps
+relatedComponents: ['AutoCompleteField', 'RadioGroup']
+relatedNextCore: []
+props:
+  - { name: options, type: 'Record<string, unknown>[]', required: true, description: 'Option rows rendered in the popup.' }
+  - { 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 value; falls back to the whole row.' }
+  - { name: multiple, type: boolean, required: false, default: 'false', description: 'Array-value mode with in-popup filter + checkmark indicators; empty selection binds `[]`, never `null`.' }
+  - { name: placeholder, type: string, required: false, description: 'Trigger placeholder; suppressed automatically in floating label modes (ifta/float) when a label is set.' }
+  - { 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 { SelectField } from '@mantis-core/ui/components/Forms/SelectField';
+import { useForm } from 'react-hook-form';
+
+const CITIES = [
+  { label: 'Quito', value: 'UIO' },
+  { label: 'Cuenca', value: 'CUE' },
+];
+
+function Example() {
+  const { control } = useForm({ defaultValues: { city: null } });
+  return (
+    <SelectField
+      name='city'
+      control={control}
+      label='City'
+      options={CITIES}
+      optionLabel='label'
+      optionValue='value'
+    />
+  );
+}
+```
+
+## Notes
+
+- Value shape: scalar (or `null`) by default; an ARRAY when `multiple`. Clearing a `multiple` field
+  binds `[]`, never `null`, so consumers can `.map()`/`.length` it without a guard.
+- Portal-based: id + aria live on `Select.Trigger` (a button, not `<input>`); `field.onBlur()` fires
+  on popup close, not native blur.
+- `fluid` does not stretch automatically inside PR11's `<Fluid>` context for `Select` — pass it
+  explicitly if needed (handled internally by the wrapper's own `fluid` resolution).

package/docs/components/stat-card.md

@@ -0,0 +1,30 @@
+---
+name: StatCard
+category: data
+import: '@mantis-core/ui/components/data/StatCard'
+whenToUse: KPI card showing a metric label, large value, optional icon, trend indicator, and footer.
+baseLibrary: custom
+relatedComponents: ['DescriptionList']
+relatedNextCore: []
+props:
+  - { name: label, type: string, required: true }
+  - { name: value, type: ReactNode, required: true }
+  - { name: icon, type: ReactNode, required: false }
+  - { name: trend, type: "{ value: number; direction: 'up' | 'down' }", required: false }
+  - { name: footer, type: ReactNode, required: false }
+---
+
+## Example
+
+```tsx
+import StatCard from '@mantis-core/ui/components/data/StatCard';
+
+function Example() {
+  return <StatCard label='Leads' value={142} trend={{ value: 12, direction: 'up' }} />;
+}
+```
+
+## Notes
+
+- Not re-exported from the package root — import the deep path shown above.
+- Presentational only (inline styles, no PrimeReact base) — pass `icon` as a rendered node (e.g. a PrimeIcons `<i>` element).

package/docs/components/status-badge.md

@@ -1,14 +1,30 @@
-# StatusBadge
-
-- Export: `StatusBadge`
-- Extra exports: `StatusBadgeProps`, `StatusBadgeTone`, `StatusBadgeSize`
-- Import: `import { StatusBadge } from "@mantis-core/ui";`
-- Base library: custom span primitive
-- Base typing: `Omit<HTMLAttributes<HTMLSpanElement>, "children"> & { label?: ReactNode; tone?: "success" | "muted" | "warning" | "info" | "danger"; size?: "sm" | "md"; block?: boolean; children?: ReactNode }`
-- Required styles: `@mantis-core/styles/scss/status-badge.scss`
+---
+name: StatusBadge
+category: feedback
+import: '@mantis-core/ui/components/ui/StatusBadge'
+whenToUse: Colored pill badge to communicate a status with semantic tone (e.g. a lead or property status).
+baseLibrary: custom
+requiredStyles: [scss/status-badge.scss]
+relatedComponents: ['DataState']
+relatedNextCore: []
+props:
+  - { name: label, type: ReactNode, required: false, description: 'Takes precedence over `children` when both are given.' }
+  - { name: tone, type: "'success' | 'muted' | 'warning' | 'info' | 'danger'", required: false, default: "'muted'" }
+  - { name: size, type: "'sm' | 'md'", required: false, default: "'md'" }
+  - { name: block, type: boolean, required: false, default: 'false' }
+  - { name: children, type: ReactNode, required: false, description: 'Fallback content when `label` is not given.' }
+---
 
 ## Example
 
 ```tsx
-<StatusBadge tone="success" size="sm" label="Published" />
+import StatusBadge from '@mantis-core/ui/components/ui/StatusBadge';
+
+function Example() {
+  return <StatusBadge label='Active' tone='success' />;
+}
 ```
+
+## Notes
+
+- Extends native `<span>` attributes (`Omit<HTMLAttributes<HTMLSpanElement>, 'children'>`) — passes through beyond `className`.

package/docs/components/switch-field.md

@@ -0,0 +1,32 @@
+---
+name: SwitchField
+category: forms
+import: '@mantis-core/ui/components/Forms/SwitchField'
+whenToUse: Boolean on/off toggle wired to react-hook-form.
+baseLibrary: '@primereact/ui/toggleswitch'
+formContract: ChoiceFieldControllerProps
+relatedComponents: ['CheckboxField']
+relatedNextCore: []
+props: []
+---
+
+## Example
+
+```tsx
+import { SwitchField } from '@mantis-core/ui/components/Forms/SwitchField';
+import { useForm } from 'react-hook-form';
+
+function Example() {
+  const { control } = useForm({ defaultValues: { featured: false } });
+  return <SwitchField name='featured' control={control} label='Featured' />;
+}
+```
+
+## Notes
+
+- Value is a plain `boolean` (`Boolean(field.value)`).
+- `labelMode` defaults to `'beside'` — `ChoiceFieldControllerProps` only allows `'beside' | 'top' | 'none'`.
+- The single on/off survivor of the PR11 migration: the legacy `Switch` + `Toggle` wrappers were
+  removed. Use `CheckboxField` instead when the semantic is "check a box", not "flip a switch".
+- Wraps PR11 compound `ToggleSwitch.Root` (+ `Control`/`Handle`); any remaining
+  `ToggleSwitchRootProps` pass through via `...rest`.

package/docs/components/table-filter-field.md

@@ -1,21 +1,35 @@
-# TableFilterField
-
-- Export: `TableFilterField`
-- Extra exports: `TableFilterFieldProps`
-- Import: `import { TableFilterField } from "@mantis-core/ui";`
-- Base library: custom filter wrapper
-- Base typing: `{ label: ReactNode; htmlFor: string; children: ReactNode; className?: string; labelClassName?: string }`
-- Required styles: `@mantis-core/styles/scss/table.scss`
+---
+name: TableFilterField
+category: tables
+import: '@mantis-core/ui/components/table-filter-field'
+whenToUse: 'Wraps a form control with a `<label>` inside a `FilterPannel`, providing consistent layout.'
+baseLibrary: custom
+relatedComponents: [FilterPannel]
+relatedNextCore: []
+props:
+  - { name: label, type: ReactNode, required: true }
+  - { name: htmlFor, type: string, required: true }
+  - { name: className, type: string, required: false }
+  - { name: labelClassName, type: string, required: false }
+---
 
 ## Example
 
 ```tsx
-<TableFilterField label="Status" htmlFor="status-filter">
-  <DropDown
-    controller={{ name: "status", control: form.control }}
-    block
-    inputId="status-filter"
-    options={statusOptions}
-  />
-</TableFilterField>
+import TableFilterField from '@mantis-core/ui/components/table-filter-field';
+
+function Example() {
+  return (
+    <TableFilterField label='Status' htmlFor='filter-status'>
+      <select id='filter-status'>
+        <option value='active'>Active</option>
+      </select>
+    </TableFilterField>
+  );
+}
 ```
+
+## Notes
+
+- Plain `div`/`label` with `mantis-core-table-filters__*` class hooks — no PrimeReact base, no `requiredStyles` partial.
+- `htmlFor` is required (unlike the pre-PR11 doc, which marked it optional) — the child control must carry a matching `id`.

package/docs/components/table-skeleton.md

@@ -0,0 +1,22 @@
+---
+name: TableSkeleton
+category: feedback
+import: '@mantis-core/ui/components/feedback/TableSkeleton'
+whenToUse: Animated skeleton placeholder that mimics a table grid while data loads; composes the PR11 Skeleton primitive.
+baseLibrary: '@primereact/ui/skeleton'
+relatedComponents: ['CardSkeleton']
+relatedNextCore: []
+props:
+  - { name: rows, type: number, required: false, default: '5' }
+  - { name: columns, type: number, required: false, default: '4' }
+---
+
+## Example
+
+```tsx
+import TableSkeleton from '@mantis-core/ui/components/feedback/TableSkeleton';
+
+function Example() {
+  return <TableSkeleton rows={8} columns={5} />;
+}
+```

package/docs/components/table-toolbar.md

@@ -1,19 +1,33 @@
-# TableToolbar
-
-- Export: `TableToolbar`
-- Extra exports: `TableToolbarProps`
-- Import: `import { TableToolbar } from "@mantis-core/ui";`
-- Base library: custom layout
-- Base typing: `{ title?: ReactNode; totalRecords?: number; meta?: ReactNode; actions?: ReactNode; className?: string; copyClassName?: string; actionsClassName?: string }`
-- Required styles: `@mantis-core/styles/scss/table.scss`
+---
+name: TableToolbar
+category: tables
+import: '@mantis-core/ui/components/table-toolbar'
+whenToUse: 'Header bar above a table showing title, record-count meta, and an action buttons slot.'
+baseLibrary: custom
+relatedComponents: [PaginatedTable, MantisDataTable, Button]
+relatedNextCore: []
+props:
+  - { name: title, type: ReactNode, required: false }
+  - { name: totalRecords, type: number, required: false, description: 'When `meta` is omitted, renders as "{n} registros disponibles".' }
+  - { name: meta, type: ReactNode, required: false, description: 'Overrides the auto-generated `totalRecords` copy.' }
+  - { name: actions, type: ReactNode, required: false }
+  - { name: className, type: string, required: false }
+  - { name: copyClassName, type: string, required: false, description: 'Extra class on the title+meta wrapper.' }
+  - { name: actionsClassName, type: string, required: false, description: 'Extra class on the actions wrapper.' }
+---
 
 ## Example
 
 ```tsx
-<TableToolbar
-  title="Listings"
-  totalRecords={total}
-  meta="Updated today"
-  actions={<Button label="New listing" icon="pi pi-plus" />}
-/>
+import TableToolbar from '@mantis-core/ui/components/table-toolbar';
+import Button from '@mantis-core/ui/components/Buttons/Button';
+
+function Example() {
+  return <TableToolbar title='Users' totalRecords={42} actions={<Button label='New' />} />;
+}
 ```
+
+## Notes
+
+- Plain `div`s with `mantis-core-table-toolbar*` class hooks — no PrimeReact base, no `requiredStyles` partial (styled via the consuming app's own CSS/Tailwind).
+- The title/meta block only renders when `title` or a resolved `meta` (explicit or from `totalRecords`) is present; the actions block only renders when `actions` is passed.