@mantis-core/ui 0.5.0 → 0.7.0

package/docs/components/render-field.md

@@ -2,18 +2,46 @@
 name: RenderField
 category: forms
 import: '@mantis-core/ui/components/Forms/RenderField'
-whenToUse: 'Low-level escape hatch: connects any custom UI to react-hook-form via a render prop.'
+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: RenderProps) => ReactElement', 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='rating' render={({ field }) => <StarPicker value={field.value} onChange={field.onChange} />} />
+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

@@ -2,16 +2,36 @@
 name: ResetPasswordForm
 category: auth
 import: '@mantis-core/ui/components/auth/ResetPasswordForm'
-whenToUse: New password + confirm form; caller owns token validation and API call.
+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 }
-  - { name: minPasswordLength, type: number, required: false, default: '8' }
+  - { 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
-<ResetPasswordForm onSubmit={({ newPassword }) => resetPassword(token, newPassword)} />
+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

@@ -2,18 +2,30 @@
 name: RichTextPreview
 category: feedback
 import: '@mantis-core/ui/components/ui/RichTextPreview'
-whenToUse: Safely renders a CKEditor HTML string with correct CKEditor content styles.
+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]
+relatedComponents: ['CKEditorInput']
 relatedNextCore: []
 props:
-  - { name: content, type: string, required: true }
-  - { name: size, type: '''sm'' | ''md'' | ''lg''', required: false }
+  - { 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 content={post.body} size='md' />
+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

@@ -2,18 +2,29 @@
 name: SearchInput
 category: forms
 import: '@mantis-core/ui/components/Forms/SearchInput'
-whenToUse: Debounced text input that calls onSearch instead of using react-hook-form; ideal for live table/list filtering.
-baseLibrary: custom
-formContract: ControllerProps
+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: controller, type: ControllerProps, required: true }
-  - { name: onSearch, type: '(value: string) => void', required: false }
+  - { 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' }
-  - { name: block, type: boolean, required: false }
 ---
+
 ## Example
 
 ```tsx
-<SearchInput controller={{ name: 'q' }} onSearch={setQuery} debounceMs={400} block />
+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

@@ -2,18 +2,29 @@
 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.'
+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: trend, type: "{ value: number; direction: 'up' | 'down' }", required: false }
   - { name: footer, type: ReactNode, required: false }
 ---
+
 ## Example
 
 ```tsx
-<StatCard label='Leads' value={142} icon={<i className='pi pi-users' />} trend={{ value: 12, direction: 'up' }} />
+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

@@ -2,19 +2,29 @@
 name: StatusBadge
 category: feedback
 import: '@mantis-core/ui/components/ui/StatusBadge'
-whenToUse: Colored pill badge to communicate a status or label with semantic tone.
+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]
+relatedComponents: ['DataState']
 relatedNextCore: []
 props:
-  - { name: label, type: ReactNode, required: false }
-  - { 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 }
+  - { 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 label='Activo' tone='success' />
+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

@@ -2,16 +2,34 @@
 name: TableFilterField
 category: tables
 import: '@mantis-core/ui/components/table-filter-field'
-whenToUse: Wraps a form control inside FilterPannel with a label; provides consistent layout.
+whenToUse: 'Wraps a form control with a `<label>` inside a `FilterPannel`, providing consistent layout.'
 baseLibrary: custom
+relatedComponents: [FilterPannel]
 relatedNextCore: []
 props:
-  - { name: label, type: string, required: true }
-  - { name: htmlFor, type: string, required: false }
+  - { 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='filter-status'><DropDown controller={{ name: 'status' }} options={statusOpts} /></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

@@ -2,15 +2,21 @@
 name: TableSkeleton
 category: feedback
 import: '@mantis-core/ui/components/feedback/TableSkeleton'
-whenToUse: Animated skeleton placeholder that mimics a table grid while data loads.
-baseLibrary: custom
+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
-<TableSkeleton rows={8} columns={5} />
+import TableSkeleton from '@mantis-core/ui/components/feedback/TableSkeleton';
+
+function Example() {
+  return <TableSkeleton rows={8} columns={5} />;
+}
 ```

package/docs/components/table-toolbar.md

@@ -2,19 +2,32 @@
 name: TableToolbar
 category: tables
 import: '@mantis-core/ui/components/table-toolbar'
-whenToUse: 'Header bar above a table showing title, record count, and action buttons slot.'
+whenToUse: 'Header bar above a table showing title, record-count meta, and an action buttons slot.'
 baseLibrary: custom
-relatedComponents: [PaginatedTable, Button]
+relatedComponents: [PaginatedTable, MantisDataTable, Button]
 relatedNextCore: []
 props:
   - { name: title, type: ReactNode, required: false }
-  - { name: totalRecords, type: number, 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: meta, 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='Users' totalRecords={total} actions={<Button label='New' onClick={onCreate} />} />
+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.

package/docs/components/tag.md

@@ -2,17 +2,26 @@
 name: Tag
 category: feedback
 import: '@mantis-core/ui/components/feedback/Tag'
-whenToUse: 'Styled label chip (PrimeReact Tag wrapper with Mantis Core CSS); use for status labels, categories, or counts.'
-baseLibrary: custom
+whenToUse: Styled label chip for status labels, categories, or counts; wraps the PR11 Tag primitive.
+baseLibrary: '@primereact/ui/tag'
+relatedComponents: ['StatusBadge', 'Avatar']
 relatedNextCore: []
 props:
-  - { name: value, type: ReactNode, required: false }
-  - { name: severity, type: '''success'' | ''info'' | ''warning'' | ''danger'' | null', required: false }
-  - { name: icon, type: string, required: false }
-  - { name: rounded, type: boolean, required: false }
+  - { name: children, type: ReactNode, required: false, description: 'Tag content — PR11 dropped value/icon; content is now children.' }
+  - { name: severity, type: "'secondary' | 'success' | 'info' | 'warn' | 'danger' | 'contrast'", required: false }
+  - { name: rounded, type: boolean, required: false, default: 'false' }
 ---
+
 ## Example
 
 ```tsx
-<Tag value='Vendido' severity='success' rounded />
+import Tag from '@mantis-core/ui/components/feedback/Tag';
+
+function Example() {
+  return <Tag severity='success' rounded>Sold</Tag>;
+}
 ```
+
+## Notes
+
+- PR11 `Tag` has no `value`/`icon` props like PR10 did — pass content as `children` instead.

package/docs/components/tags-input.md

@@ -2,18 +2,31 @@
 name: TagsInput
 category: forms
 import: '@mantis-core/ui/components/Forms/TagsInput'
-whenToUse: 'Chip/tags input (PrimeReact Chips) wired to react-hook-form; stores value as string[].'
-baseLibrary: custom
-formContract: ControllerProps
+whenToUse: RHF-bound tag/chip input over PR11's compound InputTags; stores value as string[].
+baseLibrary: '@primereact/ui/inputtags'
+formContract: FieldControllerProps
+relatedComponents: []
 relatedNextCore: []
 props:
-  - { name: controller, type: ControllerProps, required: true }
-  - { name: placeholder, type: string, required: false }
-  - { name: max, type: number, required: false }
-  - { name: block, type: boolean, required: false }
+  - { name: placeholder, type: string, required: false, description: 'Shown on the entry input only while no tags are present.' }
+  - { name: max, type: number, required: false, description: 'Max number of tags.' }
+  - { name: delimiter, type: 'string | RegExp', required: false, description: 'Extra character(s) that commit a tag besides Enter.' }
+  - { name: allowDuplicate, type: boolean, required: false }
 ---
+
 ## Example
 
 ```tsx
-<TagsInput controller={{ name: 'amenities' }} placeholder='Agregar etiqueta...' block />
+import { TagsInput } from '@mantis-core/ui/components/Forms/TagsInput';
+import { useForm } from 'react-hook-form';
+
+function Example() {
+  const { control } = useForm({ defaultValues: { tags: [] as string[] } });
+  return <TagsInput name='tags' control={control} label='Etiquetas' placeholder='Agregar etiqueta...' />;
+}
 ```
+
+## Notes
+
+- Value shape: `string[]`, `[]` when unset. Enter (or `delimiter`) commits a tag; Backspace on an empty entry removes the last one.
+- Chips render as themed `Chip.*`; the entry input is chrome-less (`.p-inputtags` owns the border/focus ring) to avoid a doubled focus ring.

package/docs/components/text-area.md

@@ -3,18 +3,28 @@ name: TextArea
 category: forms
 import: '@mantis-core/ui/components/Forms/TextArea'
 whenToUse: Multi-line text field wired to react-hook-form.
-baseLibrary: primereact/inputtextarea
-formContract: ControllerProps
-requiredStyles: [scss/inputs.scss]
-relatedComponents: [FormFieldRender, TextInput]
+baseLibrary: '@primereact/ui/textarea'
+formContract: FieldControllerProps
+relatedComponents: ['TextField']
 relatedNextCore: []
 props:
-  - { name: controller, type: ControllerProps, required: true }
-  - { name: block, type: boolean, required: false }
-  - { name: rows, type: number, required: false }
+  - { name: rows, type: number, required: false, description: 'Native <textarea> passthrough beyond FieldControllerProps.' }
 ---
+
 ## Example
 
 ```tsx
-<TextArea controller={{ name: 'description' }} rows={4} block />
+import { TextArea } from '@mantis-core/ui/components/Forms/TextArea';
+import { useForm } from 'react-hook-form';
+
+function Example() {
+  const { control } = useForm({ defaultValues: { notes: '' } });
+  return <TextArea name='notes' control={control} label='Notes' rows={4} />;
+}
 ```
+
+## Notes
+
+- Thin wrapper over PR11 `Textarea`: value/onChange are native (`e.target.value`).
+- Any extra prop not listed above (native `<textarea>` attrs or `TextareaProps`) passes straight
+  through as an escape hatch.

package/docs/components/text-field.md

@@ -0,0 +1,32 @@
+---
+name: TextField
+category: forms
+import: '@mantis-core/ui/components/Forms/TextField'
+whenToUse: Single-line text field wired to react-hook-form.
+baseLibrary: '@primereact/ui/inputtext'
+formContract: FieldControllerProps
+relatedComponents: ['TextArea', 'NumberField', 'FieldShell']
+relatedNextCore: []
+props:
+  - { name: placeholder, type: string, required: false, description: 'Native <input> passthrough beyond FieldControllerProps.' }
+  - { name: maxLength, type: number, required: false, description: 'Native <input> passthrough beyond FieldControllerProps.' }
+---
+
+## Example
+
+```tsx
+import { TextField } from '@mantis-core/ui/components/Forms/TextField';
+import { useForm } from 'react-hook-form';
+
+function Example() {
+  const { control } = useForm({ defaultValues: { title: '' } });
+  return <TextField name='title' control={control} label='Title' rules={{ required: true }} />;
+}
+```
+
+## Notes
+
+- Thin wrapper over PR11 `InputText`: value/onChange are native (`e.target.value`), unlike the
+  compound `InputNumber`/`Select` primitives.
+- Any extra prop not listed above (native `<input>` attrs or `InputTextProps`) passes straight
+  through as an escape hatch.

package/docs/components/timeline.md

@@ -2,14 +2,30 @@
 name: Timeline
 category: data
 import: '@mantis-core/ui/components/data/Timeline'
-whenToUse: 'Vertical event timeline backed by PrimeReact Timeline; items render title, description, date, and optional icon.'
-baseLibrary: custom
+whenToUse: Vertical event timeline backed by the PR11 Timeline compound; items render a title, description, date, and optional icon/color.
+baseLibrary: '@primereact/ui/timeline'
 relatedNextCore: []
 props:
   - { name: items, type: '{ title: string; description?: string; date?: string; icon?: ReactNode; color?: string }[]', required: true }
 ---
+
 ## Example
 
 ```tsx
-<Timeline items={[{ title: 'Lead creado', date: '2025-01-10', description: 'Formulario web' }, { title: 'Contactado', date: '2025-01-11' }]} />
+import Timeline from '@mantis-core/ui/components/data/Timeline';
+
+function Example() {
+  return (
+    <Timeline
+      items={[
+        { title: 'Lead created', date: '2025-01-10', description: 'Web form' },
+        { title: 'Contacted', date: '2025-01-11' },
+      ]}
+    />
+  );
+}
 ```
+
+## Notes
+
+- PR11's `Timeline` is fully compound (`Root`/`Event`/`Separator`/`Marker`/`Connector`/`Content`) with no render-prop API — the wrapper maps each `items` entry onto the sub-part tree for you, so callers keep the old flat item-list shape.