@mantis-core/ui 0.4.0 → 0.5.0

package/docs/components/range-slider.md

@@ -0,0 +1,20 @@
+---
+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
+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 }
+---
+## Example
+
+```tsx
+<RangeSlider controller={{ name: 'priceRange' }} min={0} max={500000} step={1000} block />
+```

package/docs/components/rating-input.md

@@ -0,0 +1,19 @@
+---
+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
+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 }
+---
+## Example
+
+```tsx
+<RatingInput controller={{ name: 'score' }} stars={5} />
+```

package/docs/components/render-field.md

@@ -1,24 +1,19 @@
-# 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: connects any custom UI to react-hook-form via a render prop.'
+baseLibrary: custom
+relatedNextCore: []
+props:
+  - { name: name, type: string, required: true }
+  - { name: render, type: '(props: RenderProps) => 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)}
-    />
-  )}
-/>
+<RenderField name='rating' render={({ field }) => <StarPicker value={field.value} onChange={field.onChange} />} />
 ```

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

@@ -0,0 +1,17 @@
+---
+name: ResetPasswordForm
+category: auth
+import: '@mantis-core/ui/components/auth/ResetPasswordForm'
+whenToUse: New password + confirm form; caller owns token validation and API call.
+baseLibrary: custom
+relatedNextCore: []
+props:
+  - { name: onSubmit, type: '(values: ResetPasswordFormValues) => void | Promise<void>', required: true }
+  - { name: minPasswordLength, type: number, required: false, default: '8' }
+  - { name: className, type: string, required: false }
+---
+## Example
+
+```tsx
+<ResetPasswordForm onSubmit={({ newPassword }) => resetPassword(token, newPassword)} />
+```

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

@@ -1,18 +1,19 @@
-# 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 with correct CKEditor content styles.
+baseLibrary: custom
+requiredStyles: [scss/rich-text-preview.scss]
+relatedComponents: [CKEditorInput]
+relatedNextCore: []
+props:
+  - { name: content, type: string, required: true }
+  - { name: size, type: '''sm'' | ''md'' | ''lg''', required: false }
+  - { name: className, type: string, required: false }
+---
 ## Example
 
 ```tsx
-<RichTextPreview
-  html={post.bodyHtml}
-  size="lg"
-  emptyFallback={<p>No content yet.</p>}
-/>
+<RichTextPreview content={post.body} size='md' />
 ```

package/docs/components/search-input.md

@@ -0,0 +1,19 @@
+---
+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
+relatedNextCore: []
+props:
+  - { name: controller, type: ControllerProps, required: true }
+  - { name: onSearch, type: '(value: string) => void', required: false }
+  - { 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 />
+```

package/docs/components/select.md

@@ -1,25 +1,25 @@
-# Select
-
-- Export: `Select`
-- Import: `import { Select } from "@mantis-core/ui";`
-- Base library: `react-select` or `react-select/creatable`
-- Base typing: `Omit<ReactSelectProps, "name" | "defaultValue"> & { controller: ControllerProps; block?: boolean; variant?: ButtonVariant; isCreatable?: boolean; onCreateOption?; formatCreateLabel? }`
-- Form contract: [`ControllerProps`](../contracts/controller-props.md)
-- Required styles: `@mantis-core/styles/scss/select.scss`
-
+---
+name: Select
+category: forms
+import: '@mantis-core/ui/components/Forms/Select'
+whenToUse: Single-value searchable select (react-select); supports creatable mode.
+baseLibrary: react-select
+formContract: ControllerProps
+requiredStyles: [scss/select.scss]
+relatedComponents: [FormFieldRender, AsyncSelect, DropDown]
+relatedNextCore: []
+props:
+  - { name: controller, type: ControllerProps, required: true }
+  - { name: options, type: OptionsOrGroups, required: false }
+  - { name: isCreatable, type: boolean, required: false, default: 'false' }
+  - { name: variant, type: ButtonVariant, required: false, default: '''primary''' }
+  - { name: block, type: boolean, required: false }
+  - { name: isLoading, type: boolean, required: false }
+---
 ## Example
 
 ```tsx
-<Select
-  controller={{ name: "agent", control: form.control }}
-  block
-  variant="secondary"
-  options={[
-    { label: "Alice", value: "alice" },
-    { label: "Bob", value: "bob" },
-  ]}
-  isClearable
-/>
+<Select controller={{ name: 'status' }} options={statusOptions} block />
 ```
 
 ## Notes

package/docs/components/stat-card.md

@@ -0,0 +1,19 @@
+---
+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
+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
+<StatCard label='Leads' value={142} icon={<i className='pi pi-users' />} trend={{ value: 12, direction: 'up' }} />
+```

package/docs/components/status-badge.md

@@ -1,14 +1,20 @@
-# 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 or label with semantic tone.
+baseLibrary: custom
+requiredStyles: [scss/status-badge.scss]
+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 }
+---
 ## Example
 
 ```tsx
-<StatusBadge tone="success" size="sm" label="Published" />
+<StatusBadge label='Activo' tone='success' />
 ```

package/docs/components/switch.md

@@ -1,25 +1,22 @@
-# Switch
-
-- Export: `Switch`
-- Extra exports: `SwitchProps`
-- Import: `import { Switch } from "@mantis-core/ui";`
-- Base library: custom bootstrap-switch-like markup
-- Base typing: `ControllerProps & { onLabel?; offLabel?; size?; onStyle?; offStyle?; width?; height?; disabled?; onChange?; className?; style? }`
-- Form contract: [`ControllerProps`](../contracts/controller-props.md)
-- Required styles: `@mantis-core/styles/scss/switch.scss`
-
+---
+name: Switch
+category: forms
+import: '@mantis-core/ui/components/Forms/Switch'
+whenToUse: Toggle/boolean switch wired to react-hook-form.
+baseLibrary: custom
+formContract: ControllerProps
+requiredStyles: [scss/switch.scss]
+relatedComponents: [FormFieldRender, Toggle]
+relatedNextCore: []
+props:
+  - { name: controller, type: ControllerProps, required: true }
+  - { name: label, type: string, required: false }
+  - { name: block, type: boolean, required: false }
+---
 ## Example
 
 ```tsx
-<Switch
-  name="enabled"
-  control={form.control}
-  defaultValue={true}
-  onLabel="Enabled"
-  offLabel="Disabled"
-  onStyle="success"
-  offStyle="light"
-/>
+<Switch controller={{ name: 'isActive' }} label='Active' />
 ```
 
 ## Notes

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

@@ -1,21 +1,17 @@
-# 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 inside FilterPannel with a label; provides consistent layout.
+baseLibrary: custom
+relatedNextCore: []
+props:
+  - { name: label, type: string, required: true }
+  - { name: htmlFor, type: string, required: false }
+  - { name: className, 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>
+<TableFilterField label='Status' htmlFor='filter-status'><DropDown controller={{ name: 'status' }} options={statusOpts} /></TableFilterField>
 ```

package/docs/components/table-skeleton.md

@@ -0,0 +1,16 @@
+---
+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
+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} />
+```

package/docs/components/table-toolbar.md

@@ -1,19 +1,20 @@
-# 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, and action buttons slot.'
+baseLibrary: custom
+relatedComponents: [PaginatedTable, Button]
+relatedNextCore: []
+props:
+  - { name: title, type: ReactNode, required: false }
+  - { name: totalRecords, type: number, required: false }
+  - { name: actions, type: ReactNode, required: false }
+  - { name: meta, type: ReactNode, required: false }
+  - { name: className, type: string, required: false }
+---
 ## Example
 
 ```tsx
-<TableToolbar
-  title="Listings"
-  totalRecords={total}
-  meta="Updated today"
-  actions={<Button label="New listing" icon="pi pi-plus" />}
-/>
+<TableToolbar title='Users' totalRecords={total} actions={<Button label='New' onClick={onCreate} />} />
 ```

package/docs/components/tag.md

@@ -0,0 +1,18 @@
+---
+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
+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 }
+---
+## Example
+
+```tsx
+<Tag value='Vendido' severity='success' rounded />
+```

package/docs/components/tags-input.md

@@ -0,0 +1,19 @@
+---
+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
+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 }
+---
+## Example
+
+```tsx
+<TagsInput controller={{ name: 'amenities' }} placeholder='Agregar etiqueta...' block />
+```

package/docs/components/text-area.md

@@ -1,20 +1,20 @@
-# TextArea
-
-- Export: `TextArea`
-- Extra exports: `TextAreaProps`
-- Import: `import { TextArea } from "@mantis-core/ui";`
-- Base library: `primereact/inputtextarea`
-- Base typing: `Omit<InputTextareaProps, "name" | "defaultValue" | "ref" | "onChange"> & { controller: ControllerProps; block?: boolean; loading?: boolean }`
-- Form contract: [`ControllerProps`](../contracts/controller-props.md)
-- Required styles: `@mantis-core/styles/scss/inputs.scss`
-
+---
+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]
+relatedNextCore: []
+props:
+  - { name: controller, type: ControllerProps, required: true }
+  - { name: block, type: boolean, required: false }
+  - { name: rows, type: number, required: false }
+---
 ## Example
 
 ```tsx
-<TextArea
-  controller={{ name: "description", control: form.control }}
-  block
-  rows={6}
-  autoResize
-/>
+<TextArea controller={{ name: 'description' }} rows={4} block />
 ```

package/docs/components/text-input.md

@@ -1,21 +1,22 @@
-# TextInput
-
-- Export: `TextInput`
-- Extra exports: `TextInputProps`
-- Import: `import { TextInput } from "@mantis-core/ui";`
-- Base library: `primereact/inputtext`
-- Base typing: `Omit<InputTextProps, "name" | "defaultValue"> & { controller: ControllerProps; block?: boolean; defaultValue?: string }`
-- Form contract: [`ControllerProps`](../contracts/controller-props.md)
-- Required styles: `@mantis-core/styles/scss/inputs.scss`
-
+---
+name: TextInput
+category: forms
+import: '@mantis-core/ui/components/Forms/TextInput'
+whenToUse: Single-line text field wired to react-hook-form.
+baseLibrary: primereact/inputtext
+formContract: ControllerProps
+requiredStyles: [scss/inputs.scss]
+relatedComponents: [FormFieldRender, TextArea]
+relatedNextCore: []
+props:
+  - { name: controller, type: ControllerProps, required: true }
+  - { name: block, type: boolean, required: false, default: 'false' }
+  - { name: defaultValue, type: string, required: false, default: '''''' }
+---
 ## Example
 
 ```tsx
-<TextInput
-  controller={{ name: "title", control: form.control }}
-  block
-  placeholder="Listing title"
-/>
+<TextInput controller={{ name: 'email', rules: { required: true } }} block />
 ```
 
 ## Notes

package/docs/components/time-picker.md

@@ -1,20 +1,23 @@
-# TimePicker
-
-- Export: `TimePicker`
-- Import: `import { TimePicker } from "@mantis-core/ui";`
-- Base library: `react-datepicker`
-- Base typing: explicit `TimePickerProps`
-- Form contract: [`ControllerProps`](../contracts/controller-props.md)
-- Required styles: none
-
+---
+name: TimePicker
+category: forms
+import: '@mantis-core/ui/components/Forms/TimePicker'
+whenToUse: Time-only picker (15-min intervals) wired to react-hook-form; renders as a styled InputText trigger.
+baseLibrary: react-datepicker
+formContract: ControllerProps
+requiredStyles: [scss/inputs.scss]
+relatedNextCore: []
+props:
+  - { name: controller, type: ControllerProps, required: true, description: 'react-hook-form controller config' }
+  - { name: block, type: boolean, required: false, default: 'false', description: 'Expand to full width' }
+  - { name: datePicker, type: DatePickerProps, required: false, description: 'Passthrough props for react-datepicker' }
+  - { name: className, type: string, required: false, description: 'Additional CSS class on the DatePicker wrapper' }
+  - { name: timePeriod, type: '''AM'' | ''PM''', required: false, description: 'Default time period hint' }
+---
 ## Example
 
 ```tsx
-<TimePicker
-  controller={{ name: "openingTime", control: form.control }}
-  block
-  datePicker={{ showTimeSelectOnly: true, timeIntervals: 30 }}
-/>
+{/* TODO: add example */}
 ```
 
 ## Notes

package/docs/components/timeline.md

@@ -0,0 +1,15 @@
+---
+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
+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' }]} />
+```

package/docs/components/toggle-inline-button.md

@@ -1,22 +1,21 @@
-# ToggleInlineButton
-
-- Export: `ToggleInlineButton`
-- Extra exports: `ToggleInlineButtonProps`
-- Import: `import { ToggleInlineButton } from "@mantis-core/ui";`
-- Base library: `primereact/selectbutton`
-- Base typing: `{ controller: ControllerProps; options: any[]; variant?: ButtonVariant; multiple?: boolean }`
-- Form contract: [`ControllerProps`](../contracts/controller-props.md)
-- Required styles: `@mantis-core/styles/scss/select-button.scss`
-
+---
+name: ToggleInlineButton
+category: forms
+import: '@mantis-core/ui/components/Forms/ToggleInlineButton'
+whenToUse: Segmented button group (single or multi-select) wired to react-hook-form via a controller prop.
+baseLibrary: primereact/selectbutton
+formContract: ControllerProps
+requiredStyles: [scss/select-button.scss]
+relatedComponents: [FormFieldRender]
+relatedNextCore: []
+props:
+  - { name: controller, type: ControllerProps, required: true, description: 'react-hook-form controller config' }
+  - { name: options, type: 'any[]', required: true, description: 'Options array passed to SelectButton' }
+  - { name: variant, type: ButtonVariant, required: false, default: '''primary''', description: 'Design-system color variant' }
+  - { name: multiple, type: boolean, required: false, default: 'false', description: 'Allow selecting multiple options' }
+---
 ## Example
 
 ```tsx
-<ToggleInlineButton
-  controller={{ name: "visibility", control: form.control }}
-  variant="accent"
-  options={[
-    { label: "Public", value: "public" },
-    { label: "Private", value: "private" },
-  ]}
-/>
+{/* TODO: add example */}
 ```

package/docs/components/toggle.md

@@ -1,21 +1,24 @@
-# Toggle
-
-- Export: `Toggle`
-- Extra exports: `ToggleProps`
-- Import: `import { Toggle } from "@mantis-core/ui";`
-- Base library: `primereact/checkbox`
-- Base typing: `ControllerProps & { on?; off?; size?; offstyle?; onstyle?; onClick?; active? }`
-- Form contract: [`ControllerProps`](../contracts/controller-props.md)
-- Required styles: none
-
+---
+name: Toggle
+category: forms
+import: '@mantis-core/ui/components/Forms/Toggle'
+whenToUse: Checkbox-based boolean toggle wired to react-hook-form with configurable on/off labels.
+baseLibrary: primereact/checkbox
+formContract: ControllerProps
+relatedComponents: [FormFieldRender, Switch]
+relatedNextCore: []
+props:
+  - { name: controller, type: ControllerProps, required: true, description: 'react-hook-form controller config (name, rules, defaultValue)' }
+  - { name: on, type: 'string | any', required: false, default: '''SI''', description: 'Label shown when value is true' }
+  - { name: off, type: 'string | any', required: false, default: '''NO''', description: 'Label shown when value is false' }
+  - { name: size, type: '''sm'' | ''lg'' | ''md''', required: false, description: 'Visual size variant' }
+  - { name: offstyle, type: '''primary'' | ''secondary'' | ''dark''', required: false, description: 'Style when off' }
+  - { name: onstyle, type: '''primary'' | ''secondary'' | ''dark''', required: false, description: 'Style when on' }
+  - { name: onClick, type: any, required: false, description: 'Click handler passthrough' }
+  - { name: active, type: boolean, required: false, description: 'Controlled active state' }
+---
 ## Example
 
 ```tsx
-<Toggle
-  name="published"
-  control={form.control}
-  defaultValue={false}
-  on="YES"
-  off="NO"
-/>
+{/* TODO: add example */}
 ```