@foi/design-system 0.0.17 → 0.0.19

package/README.md

@@ -46,12 +46,13 @@ npm publish --access public
 | ------------- | ------------------------------------------------------------------------------------------ |
 | `Button`      | Primary action button with variant/size/color support                                      |
 | `Checkbox`    | Single checkbox — standalone, RHF, or inside a group                                       |
+| `Chip`        | Compact inline label for statuses and tags — themed variants, accepts text or ReactNode    |
 | `DatePicker`  | Date input with calendar menu, integrates with RHF                                         |
 | `Icon`        | Font-based icon using Material Symbols Rounded — pass a `name` prop                        |
-| `IconButton`  | Clickable icon with button semantics                                                        |
+| `IconButton`  | Clickable icon with button semantics                                                       |
 | `NumberField` | Numeric input with increment/decrement buttons, min/max/step support, and two layout modes |
 | `Pagination`  | Page navigation bar with first/prev/next/last buttons and optional rows-per-page selector  |
-| `Radio`       | Single radio button — used inside `RadioGroup`                                              |
+| `Radio`       | Single radio button — used inside `RadioGroup`                                             |
 | `Select`      | Dropdown select with RHF integration                                                       |
 | `Skeleton`    | Animated placeholder shown while content is loading — rectangular or circular              |
 | `Slider`      | Range slider with RHF integration                                                          |
@@ -60,17 +61,18 @@ npm publish --access public
 
 ### Molecules
 
-| Component       | Description                                                    |
-| --------------- | -------------------------------------------------------------- |
-| `CheckboxGroup` | Manages a set of `Checkbox` children as a `string[]` RHF field |
-| `CheckboxTree`  | Hierarchical checkbox group with parent/child selection logic  |
+| Component       | Description                                                                       |
+| --------------- | --------------------------------------------------------------------------------- |
+| `CheckboxGroup` | Manages a set of `Checkbox` children as a `string[]` RHF field                    |
+| `CheckboxTree`  | Hierarchical checkbox group with parent/child selection logic                     |
 | `Modal`         | Overlay dialog rendered via React portal — closes on ×, backdrop click, or Escape |
-| `RadioGroup`    | Manages a set of `Radio` children as a single RHF field        |
+| `RadioGroup`    | Manages a set of `Radio` children as a single RHF field                           |
+| `Toast`         | Notification system — push transient messages from anywhere via `useToast`        |
 
 ### Organisms
 
-| Component  | Description                                                                                              |
-| ---------- | -------------------------------------------------------------------------------------------------------- |
+| Component  | Description                                                                                                                                                                |
+| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `DataGrid` | Async data table with server-side sorting, filtering (search / multiselect), pagination or infinite scroll, skeleton loading state, and custom action columns via `render` |
 
 ## Usage with React Hook Form
@@ -139,25 +141,25 @@ A text input field with a floating label, helper text, and full error state inte
 
 ### Props
 
-| Prop            | Type                                      | Default    | Description                                          |
-| --------------- | ----------------------------------------- | ---------- | ---------------------------------------------------- |
-| `name`          | `string`                                  | —          | Field name, used by RHF                              |
-| `label`         | `string`                                  | —          | Floating label text                                  |
-| `control`       | `Control`                                 | —          | RHF control object; omit for uncontrolled mode       |
-| `value`         | `string`                                  | —          | Value in uncontrolled mode                           |
-| `onValueChange` | `(value: string) => void`                 | —          | Change handler in uncontrolled mode                  |
-| `type`          | `'text' \| 'password' \| 'email'`         | `'text'`   | HTML input type                                      |
-| `width`         | `'small' \| 'medium' \| 'large' \| 'full'` | —        | Preset width                                         |
-| `helperText`    | `string`                                  | —          | Hint text shown below the field when there is no error |
-| `showErrorText` | `boolean`                                 | `true`     | Show the validation error message below the field    |
-| `hasPadding`    | `boolean`                                 | `false`    | Add bottom padding to reserve space for helper/error text |
-| `startAdornment`| `JSX.Element`                             | —          | Element rendered to the left of the input            |
-| `endAdornment`  | `JSX.Element`                             | —          | Element rendered to the right of the input           |
-| `regex`         | `RegExp`                                  | —          | Block keystrokes that don't match the pattern        |
-| `format`        | `(value: string) => string`               | —          | Transform the value before it is stored              |
-| `disabled`      | `boolean`                                 | `false`    | Disable the field                                    |
-| `theme`         | `EVENTS`                                  | —          | One-off token override for this instance             |
-| `variant`       | `string`                                  | `'default'`| Theme variant name                                   |
+| Prop             | Type                                       | Default     | Description                                               |
+| ---------------- | ------------------------------------------ | ----------- | --------------------------------------------------------- |
+| `name`           | `string`                                   | —           | Field name, used by RHF                                   |
+| `label`          | `string`                                   | —           | Floating label text                                       |
+| `control`        | `Control`                                  | —           | RHF control object; omit for uncontrolled mode            |
+| `value`          | `string`                                   | —           | Value in uncontrolled mode                                |
+| `onValueChange`  | `(value: string) => void`                  | —           | Change handler in uncontrolled mode                       |
+| `type`           | `'text' \| 'password' \| 'email'`          | `'text'`    | HTML input type                                           |
+| `width`          | `'small' \| 'medium' \| 'large' \| 'full'` | —           | Preset width                                              |
+| `helperText`     | `string`                                   | —           | Hint text shown below the field when there is no error    |
+| `showErrorText`  | `boolean`                                  | `true`      | Show the validation error message below the field         |
+| `hasPadding`     | `boolean`                                  | `false`     | Add bottom padding to reserve space for helper/error text |
+| `startAdornment` | `JSX.Element`                              | —           | Element rendered to the left of the input                 |
+| `endAdornment`   | `JSX.Element`                              | —           | Element rendered to the right of the input                |
+| `regex`          | `RegExp`                                   | —           | Block keystrokes that don't match the pattern             |
+| `format`         | `(value: string) => string`                | —           | Transform the value before it is stored                   |
+| `disabled`       | `boolean`                                  | `false`     | Disable the field                                         |
+| `theme`          | `EVENTS`                                   | —           | One-off token override for this instance                  |
+| `variant`        | `string`                                   | `'default'` | Theme variant name                                        |
 
 ### Example
 
@@ -172,7 +174,7 @@ import Icon from '@components/atoms/Icon';
   type='email'
   startAdornment={<Icon name='mail' />}
   helperText='We will never share your email'
-/>
+/>;
 ```
 
 ## NumberField
@@ -183,12 +185,12 @@ A numeric input that stores a `number` in RHF (or `undefined` when empty). The f
 
 All `TextField` props apply except `type`, `endAdornment`, and `startAdornment` (in `spinner` mode). The following props are specific to `NumberField`:
 
-| Prop      | Type                          | Default      | Description                                                              |
-| --------- | ----------------------------- | ------------ | ------------------------------------------------------------------------ |
-| `min`     | `number`                      | —            | Minimum allowed value; decrement button disables at this bound           |
-| `max`     | `number`                      | —            | Maximum allowed value; increment button disables at this bound           |
-| `step`    | `number`                      | `1`          | Amount added or subtracted on each button click                          |
-| `display` | `'standard' \| 'spinner'`     | `'standard'` | `standard`: both buttons on the right; `spinner`: remove left, input centre, add right |
+| Prop      | Type                      | Default      | Description                                                                            |
+| --------- | ------------------------- | ------------ | -------------------------------------------------------------------------------------- |
+| `min`     | `number`                  | —            | Minimum allowed value; decrement button disables at this bound                         |
+| `max`     | `number`                  | —            | Maximum allowed value; increment button disables at this bound                         |
+| `step`    | `number`                  | `1`          | Amount added or subtracted on each button click                                        |
+| `display` | `'standard' \| 'spinner'` | `'standard'` | `standard`: both buttons on the right; `spinner`: remove left, input centre, add right |
 
 ### Display modes
 
@@ -249,11 +251,35 @@ A theme is a plain object with a `name`, an optional `fonts` map, and a `compone
 
 Each variant contains:
 
-- `ROOT` — static styles applied unconditionally (e.g. `border-radius`)
-- `EVENTS` — styles scoped to interaction states (`ENABLED`, `HOVER`, `FOCUS`, `ERROR`, `DISABLED`, etc.)
+- `ROOT` — static styles applied unconditionally (e.g. `border-radius`, `background-color`)
+- `EVENTS` — styles scoped to interaction states. The complete set of possible states is:
+
+| State | Description |
+| --- | --- |
+| `ENABLED` | Default resting state — element is interactive and fully visible |
+| `VALUE` | The filled or selected part of the element (e.g. track fill, typed text colour) |
+| `HOVER` | While the pointer is over the element |
+| `ACTIVE` | While the element is being pressed |
+| `FOCUS` | When the element has keyboard focus |
+| `ERROR` | Container styles when validation fails |
+| `ERROR_VALUE` | Value part when in error state |
+| `ERROR_HOVER` | Hover while in error state |
+| `ERROR_ACTIVE` | Press while in error state |
+| `ERROR_FOCUS` | Focus while in error state |
+| `DISABLED` | When the element is not interactive |
+| `DISABLED_VALUE` | Value part when disabled |
+| `LOADING` | During a pending async operation |
+| `LOADING_VALUE` | Value part during loading |
+
+Not every component uses all states — each component defines only the states relevant to its interaction model. The TypeScript type exported from the component's theme file tells you exactly which states are available:
+
+```ts
+import type { EVENTS } from '@hocs/ThemeProvider/components/atoms/Button';
+// Autocomplete will show only the states Button actually supports
+```
 
 ```ts
-import type { BUTTON } from '@hocs/ThemeProvider/components/Button';
+import type { BUTTON } from '@hocs/ThemeProvider/components/atoms/Button';
 
 const component = {
   BUTTON: {
@@ -324,12 +350,16 @@ An async data table that delegates all data operations to the server via `onFetc
 import DataGrid from '@components/organisms/DataGrid';
 import type { DataGridColumn } from '@components/organisms/DataGrid';
 
-interface Product { id: number; name: string; price: number; }
+interface Product {
+  id: number;
+  name: string;
+  price: number;
+}
 
 const columns: DataGridColumn<Product>[] = [
   {
     key: 'name',
-    label: 'Product',      // string → wrapped in the themed --DATAGRID-thLabel span
+    label: 'Product', // string → wrapped in the themed --DATAGRID-thLabel span
     type: 'text',
     filter: { type: 'search' },
   },
@@ -369,7 +399,7 @@ const onFetch = async ({ page, pageSize, sort, filters }) => {
   return { data: response.items, total: response.total };
 };
 
-<DataGrid<Product> columns={columns} onFetch={onFetch} />
+<DataGrid<Product> columns={columns} onFetch={onFetch} />;
 ```
 
 ### Action columns
@@ -398,11 +428,11 @@ const columnsWithActions: DataGridColumn<Product>[] = [
 
 ### Pagination modes
 
-| Prop              | Value          | Behaviour                                      |
-| ----------------- | -------------- | ---------------------------------------------- |
+| Prop              | Value          | Behaviour                                              |
+| ----------------- | -------------- | ------------------------------------------------------ |
 | `paginationType`  | `'pagination'` | Renders a `<Pagination>` bar below the table (default) |
-| `paginationType`  | `'scroll'`     | Appends rows as the user scrolls down          |
-| `pageSizeOptions` | `number[]`     | Shows a rows-per-page selector in the bar      |
+| `paginationType`  | `'scroll'`     | Appends rows as the user scrolls down                  |
+| `pageSizeOptions` | `number[]`     | Shows a rows-per-page selector in the bar              |
 
 ## Modal
 
@@ -428,38 +458,603 @@ const [open, setOpen] = useState(false);
   }
   footer={
     <>
-      <Button onClick={() => setOpen(false)} variant='ghost'>Cancelar</Button>
+      <Button onClick={() => setOpen(false)} variant='ghost'>
+        Cancelar
+      </Button>
       <Button onClick={() => setOpen(false)}>Aceptar</Button>
     </>
   }
 >
   Contenido del modal.
-</Modal>
+</Modal>;
 ```
 
 Apply `--MODAL-title` to the title element inside `header` to receive the themed font and colour styles.
 
 ### Props
 
-| Prop             | Type          | Default | Description                                       |
-| ---------------- | ------------- | ------- | ------------------------------------------------- |
-| `open`           | `boolean`     | —       | Controls visibility                               |
-| `onClose`        | `() => void`  | —       | Called when the modal requests to close           |
-| `header`         | `ReactNode`   | —       | Full header bar content (rendered before ×)       |
-| `showCloseButton`| `boolean`     | `true`  | Whether to render the × icon button               |
-| `size`           | `'md' \| 'lg'`| `'md'`  | `'md'` = 480 px, `'lg'` = 720 px                 |
-| `children`       | `ReactNode`   | —       | Main body content                                 |
-| `footer`         | `ReactNode`   | —       | Footer row content (typically action buttons)     |
-| `staticBackdrop` | `boolean`     | `false` | When `true`, backdrop click and Escape do nothing |
-| `className`      | `string`      | —       | Extra CSS class on the modal panel                |
+| Prop              | Type           | Default | Description                                       |
+| ----------------- | -------------- | ------- | ------------------------------------------------- |
+| `open`            | `boolean`      | —       | Controls visibility                               |
+| `onClose`         | `() => void`   | —       | Called when the modal requests to close           |
+| `header`          | `ReactNode`    | —       | Full header bar content (rendered before ×)       |
+| `showCloseButton` | `boolean`      | `true`  | Whether to render the × icon button               |
+| `size`            | `'md' \| 'lg'` | `'md'`  | `'md'` = 480 px, `'lg'` = 720 px                  |
+| `children`        | `ReactNode`    | —       | Main body content                                 |
+| `footer`          | `ReactNode`    | —       | Footer row content (typically action buttons)     |
+| `staticBackdrop`  | `boolean`      | `false` | When `true`, backdrop click and Escape do nothing |
+| `className`       | `string`       | —       | Extra CSS class on the modal panel                |
 
 ### Close triggers
 
-| Trigger          | `staticBackdrop=false` | `staticBackdrop=true` |
-| ---------------- | ---------------------- | --------------------- |
-| × button         | ✓                      | ✓                     |
-| Backdrop click   | ✓                      | —                     |
-| Escape key       | ✓                      | —                     |
+| Trigger        | `staticBackdrop=false` | `staticBackdrop=true` |
+| -------------- | ---------------------- | --------------------- |
+| × button       | ✓                      | ✓                     |
+| Backdrop click | ✓                      | —                     |
+| Escape key     | ✓                      | —                     |
+
+## Button
+
+The primary interactive element. Accepts any `ReactNode` as children and natively supports all standard `<button>` HTML attributes.
+
+### Props
+
+| Prop        | Type                   | Default     | Description                                              |
+| ----------- | ---------------------- | ----------- | -------------------------------------------------------- |
+| `children`  | `ReactNode`            | —           | Button label or content                                  |
+| `type`      | `'button' \| 'submit'` | `'button'`  | HTML button type                                         |
+| `iconStart` | `JSX.Element`          | —           | Icon rendered before the label                           |
+| `iconEnd`   | `JSX.Element`          | —           | Icon rendered after the label                            |
+| `loading`   | `boolean`              | `false`     | Shows a loading indicator; button stays mounted          |
+| `disabled`  | `boolean`              | `false`     | Prevents interaction                                     |
+| `className` | `string`               | —           | Extra CSS class                                          |
+| `variant`   | `string`               | `'default'` | Theme variant                                            |
+| `theme`     | `EVENTS`               | —           | One-off token override                                   |
+
+### Example
+
+```tsx
+import Button from '@components/atoms/Button';
+import Icon from '@components/atoms/Icon';
+
+<Button onClick={handleSave}>Guardar</Button>
+<Button type='submit' iconStart={<Icon name='send' />}>Enviar</Button>
+<Button loading={isSaving} disabled={isSaving}>Guardando…</Button>
+<Button variant='danger' onClick={handleDelete}>Eliminar</Button>
+```
+
+## Icon
+
+Renders a single icon from the [Material Symbols Rounded](https://fonts.google.com/icons) font. The font is loaded automatically by `ThemeProvider`.
+
+### Props
+
+| Prop        | Type                          | Default  | Description                              |
+| ----------- | ----------------------------- | -------- | ---------------------------------------- |
+| `name`      | `string`                      | —        | Material Symbols ligature name           |
+| `fill`      | `boolean`                     | `false`  | Use the filled variant of the icon       |
+| `size`      | `'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | Icon size                                |
+| `className` | `string`                      | —        | Extra CSS class                          |
+| `style`     | `CSSProperties`               | —        | Inline styles                            |
+
+### Example
+
+```tsx
+import Icon from '@components/atoms/Icon';
+
+<Icon name='home' />
+<Icon name='search' size='lg' />
+<Icon name='favorite' fill />
+```
+
+## IconButton
+
+A button that renders a single icon with no visible text. Accepts all standard `<button>` HTML attributes.
+
+### Props
+
+| Prop        | Type          | Default     | Description                                            |
+| ----------- | ------------- | ----------- | ------------------------------------------------------ |
+| `icon`      | `JSX.Element` | —           | Icon element to render (use `<Icon />`)                |
+| `onClick`   | `function`    | —           | Click handler                                          |
+| `isFlipped` | `boolean`     | `false`     | Mirrors the icon horizontally (useful for arrows)      |
+| `disabled`  | `boolean`     | `false`     | Prevents interaction                                   |
+| `className` | `string`      | —           | Extra CSS class                                        |
+| `variant`   | `string`      | `'default'` | Theme variant                                          |
+| `theme`     | `EVENTS`      | —           | One-off token override                                 |
+
+### Example
+
+```tsx
+import IconButton from '@components/atoms/IconButton';
+import Icon from '@components/atoms/Icon';
+
+<IconButton icon={<Icon name='close' />} onClick={() => setOpen(false)} />
+<IconButton icon={<Icon name='arrow_forward' />} isFlipped onClick={goBack} />
+```
+
+## Checkbox
+
+A single checkbox. Can be used standalone (controlled or RHF), or as a child of `CheckboxGroup` / `CheckboxTree`.
+
+### Props
+
+| Prop            | Type                      | Default     | Description                                           |
+| --------------- | ------------------------- | ----------- | ----------------------------------------------------- |
+| `name`          | `string`                  | —           | RHF field name (required in standalone RHF mode)      |
+| `control`       | `Control`                 | —           | RHF control object                                    |
+| `checked`       | `boolean`                 | —           | Controlled mode value (use with `onChecked`)          |
+| `onChecked`     | `(checked: boolean) => void` | —        | Controlled mode change handler                        |
+| `label`         | `string`                  | —           | Text label next to the checkbox                       |
+| `icon`          | `JSX.Element`             | checkmark   | Custom icon shown when checked                        |
+| `disabled`      | `boolean`                 | `false`     | Prevents interaction                                  |
+| `helperText`    | `string`                  | —           | Hint text below the checkbox                          |
+| `showErrorText` | `boolean`                 | `true`      | Show validation error message                         |
+| `variant`       | `string`                  | `'default'` | Theme variant                                         |
+| `theme`         | `EVENTS`                  | —           | One-off token override                                |
+
+### Example
+
+```tsx
+import Checkbox from '@components/atoms/Checkbox';
+
+// RHF
+<Checkbox name='agree' control={control} label='Acepto los términos' />
+
+// Controlled
+const [checked, setChecked] = useState(false);
+<Checkbox checked={checked} onChecked={setChecked} label='Recordarme' />
+```
+
+## Radio
+
+A single radio button. Always used inside `RadioGroup` — it receives its state from the group context automatically.
+
+### Props
+
+| Prop        | Type          | Default     | Description                                      |
+| ----------- | ------------- | ----------- | ------------------------------------------------ |
+| `value`     | `string`      | —           | The value this option represents                 |
+| `label`     | `string`      | —           | Text label next to the radio                     |
+| `icon`      | `JSX.Element` | filled dot  | Custom icon shown when selected                  |
+| `disabled`  | `boolean`     | `false`     | Overrides the group `disabled` for this item     |
+| `variant`   | `string`      | `'default'` | Theme variant                                    |
+| `theme`     | `EVENTS`      | —           | One-off token override                           |
+
+## Select
+
+A dropdown select field backed by a virtual-scroll list. Integrates with RHF and stores the selected `value` string.
+
+### Props
+
+| Prop               | Type            | Default     | Description                                               |
+| ------------------ | --------------- | ----------- | --------------------------------------------------------- |
+| `name`             | `string`        | —           | RHF field name                                            |
+| `label`            | `string`        | —           | Floating label                                            |
+| `control`          | `Control`       | —           | RHF control object                                        |
+| `options`          | `OptionProp[]`  | —           | List of `{ value, label, description? }` items            |
+| `disabled`         | `boolean`       | `false`     | Prevents interaction                                      |
+| `range`            | `number`        | `100`       | Options per page (virtual scroll activates above 3)       |
+| `hasSearch`        | `boolean`       | `false`     | Shows a search input — filters after 3 characters        |
+| `hasDescription`   | `boolean`       | `false`     | Renders a secondary description line per option           |
+| `hasStaticOptions` | `boolean`       | `false`     | Renders dropdown inline (no absolute positioning)         |
+| `helperText`       | `string`        | —           | Hint text below the field                                 |
+| `showErrorText`    | `boolean`       | `true`      | Show validation error message                             |
+| `hasPadding`       | `boolean`       | `false`     | Add bottom padding for helper/error text                  |
+| `variant`          | `string`        | `'default'` | Theme variant                                             |
+| `theme`            | `EVENTS`        | —           | One-off token override                                    |
+
+### Example
+
+```tsx
+import Select from '@components/atoms/Select';
+
+const options = [
+  { value: 'cl', label: 'Chile' },
+  { value: 'ar', label: 'Argentina', description: 'Buenos Aires' },
+];
+
+<Select name='country' control={control} label='País' options={options} hasSearch />
+```
+
+## DatePicker
+
+A date input field with an inline or floating calendar. Stores a `Date` value in RHF.
+
+### Props
+
+| Prop               | Type             | Default     | Description                                              |
+| ------------------ | ---------------- | ----------- | -------------------------------------------------------- |
+| `name`             | `string`         | —           | RHF field name                                           |
+| `label`            | `string`         | —           | Floating label                                           |
+| `control`          | `Control`        | —           | RHF control object                                       |
+| `language`         | `'es' \| 'en'`   | browser     | Date format and labels (`DD/MM/YYYY` vs `MM/DD/YYYY`)    |
+| `minDate`          | `Date`           | —           | Earliest selectable date                                 |
+| `maxDate`          | `Date`           | —           | Latest selectable date                                   |
+| `disablePast`      | `boolean`        | `false`     | Disables all dates before today                          |
+| `disableFuture`    | `boolean`        | `false`     | Disables all dates after today                           |
+| `hasStaticOptions` | `boolean`        | `false`     | Renders calendar inline instead of floating              |
+| `disabled`         | `boolean`        | `false`     | Prevents interaction                                     |
+| `helperText`       | `string`         | —           | Hint text below the field                                |
+| `showErrorText`    | `boolean`        | `true`      | Show validation error message                            |
+| `hasPadding`       | `boolean`        | `false`     | Add bottom padding for helper/error text                 |
+| `variant`          | `string`         | `'default'` | Theme variant                                            |
+| `theme`            | `EVENTS`         | —           | One-off token override                                   |
+
+### Example
+
+```tsx
+import DatePicker from '@components/atoms/DatePicker';
+
+<DatePicker
+  name='birthDate'
+  control={control}
+  label='Fecha de nacimiento'
+  language='es'
+  disableFuture
+  maxDate={new Date('2005-01-01')}
+/>
+```
+
+## Switch
+
+A toggle switch that stores a `boolean` value in RHF.
+
+### Props
+
+| Prop        | Type       | Default     | Description                                 |
+| ----------- | ---------- | ----------- | ------------------------------------------- |
+| `name`      | `string`   | —           | RHF field name                              |
+| `control`   | `Control`  | —           | RHF control object                          |
+| `label`     | `string`   | —           | Text label next to the switch               |
+| `iconOn`    | `JSX.Element` | —        | Icon on the thumb when on                   |
+| `iconOff`   | `JSX.Element` | —        | Icon on the thumb when off                  |
+| `disabled`  | `boolean`  | `false`     | Prevents interaction                        |
+| `helperText`| `string`   | —           | Hint text below the switch                  |
+| `variant`   | `string`   | `'default'` | Theme variant                               |
+| `theme`     | `EVENTS`   | —           | One-off token override                      |
+
+### Example
+
+```tsx
+import Switch from '@components/atoms/Switch';
+import Icon from '@components/atoms/Icon';
+
+<Switch
+  name='notifications'
+  control={control}
+  label='Activar notificaciones'
+  iconOn={<Icon name='notifications' />}
+  iconOff={<Icon name='notifications_off' />}
+/>
+```
+
+## Slider
+
+A range slider that stores a `number[]` value in RHF. Single-thumb mode uses a 1-element array; range mode uses a 2-element array.
+
+### Props
+
+| Prop         | Type                            | Default        | Description                                            |
+| ------------ | ------------------------------- | -------------- | ------------------------------------------------------ |
+| `name`       | `string`                        | —              | RHF field name                                         |
+| `control`    | `Control`                       | —              | RHF control object                                     |
+| `min`        | `number`                        | —              | Minimum value                                          |
+| `max`        | `number`                        | —              | Maximum value (`Infinity` disables click-to-seek)      |
+| `step`       | `number`                        | `1`            | Snap granularity                                       |
+| `distance`   | `number`                        | `0`            | Minimum gap between thumbs (range mode only)           |
+| `direction`  | `'horizontal' \| 'vertical'`    | `'horizontal'` | Slider orientation                                     |
+| `track`      | `'normal' \| 'inverted'`        | `'normal'`     | Fill direction of the track                            |
+| `showMarks`  | `boolean`                       | `false`        | Show a dot at every `step` position                    |
+| `iconMin`    | `JSX.Element`                   | —              | Icon inside the min/single thumb                       |
+| `iconMax`    | `JSX.Element`                   | —              | Icon inside the max thumb (range mode only)            |
+| `helperText` | `string`                        | —              | Hint text below the slider                             |
+| `disabled`   | `boolean`                       | `false`        | Prevents interaction                                   |
+| `variant`    | `string`                        | `'default'`    | Theme variant                                          |
+| `theme`      | `EVENTS`                        | —              | One-off token override                                 |
+
+### Example
+
+```tsx
+import Slider from '@components/atoms/Slider';
+
+// Single thumb — value is [number]
+<Slider name='volume' control={control} min={0} max={100} />
+
+// Range — value is [number, number]
+<Slider name='priceRange' control={control} min={0} max={10000} step={100} distance={500} showMarks />
+```
+
+## Skeleton
+
+An animated placeholder rendered while content is loading. Has no logic — simply swap it out once your data arrives.
+
+### Props
+
+| Prop        | Type                              | Default          | Description                      |
+| ----------- | --------------------------------- | ---------------- | -------------------------------- |
+| `variant`   | `'rectangular' \| 'circular'`     | `'rectangular'`  | Shape of the placeholder         |
+| `width`     | `string \| number`                | —                | CSS width or pixel number        |
+| `height`    | `string \| number`                | —                | CSS height or pixel number       |
+| `className` | `string`                          | —                | Extra CSS class                  |
+
+### Example
+
+```tsx
+import Skeleton from '@components/atoms/Skeleton';
+
+// While loading a user avatar
+{isLoading ? <Skeleton variant='circular' width={40} height={40} /> : <Avatar src={user.photo} />}
+
+// While loading a text block
+{isLoading ? <Skeleton width='100%' height={20} /> : <p>{content}</p>}
+```
+
+## Pagination
+
+A standalone page-navigation bar. `DataGrid` uses this internally, but it can also be used independently.
+
+### Props
+
+| Prop               | Type               | Default | Description                                         |
+| ------------------ | ------------------ | ------- | --------------------------------------------------- |
+| `page`             | `number`           | —       | Zero-based current page index                       |
+| `total`            | `number`           | —       | Total row count (used to compute page count)        |
+| `pageSize`         | `number`           | —       | Rows per page                                       |
+| `onPageChange`     | `(page: number) => void` | — | Fired when the user navigates to a different page   |
+| `pageSizeOptions`  | `number[]`         | —       | Shows a rows-per-page selector with these options   |
+| `onPageSizeChange` | `(size: number) => void` | — | Fired when the user changes the page size           |
+| `loading`          | `boolean`          | `false` | Disables all controls while data is fetching        |
+
+### Example
+
+```tsx
+import Pagination from '@components/atoms/Pagination';
+
+<Pagination
+  page={page}
+  total={total}
+  pageSize={pageSize}
+  onPageChange={setPage}
+  pageSizeOptions={[10, 25, 50]}
+  onPageSizeChange={setPageSize}
+/>
+```
+
+## CheckboxGroup
+
+Manages a set of `Checkbox` children as a `string[]` RHF field. The group value is the array of `value` props of all checked children.
+
+### Props
+
+| Prop            | Type                           | Default      | Description                                     |
+| --------------- | ------------------------------ | ------------ | ----------------------------------------------- |
+| `name`          | `string`                       | —            | RHF field name                                  |
+| `control`       | `Control`                      | —            | RHF control object                              |
+| `children`      | `ReactNode`                    | —            | `<Checkbox>` elements (each must have `value`)  |
+| `label`         | `string`                       | —            | Group label above the checkboxes                |
+| `direction`     | `'vertical' \| 'horizontal'`   | `'vertical'` | Layout direction of the items                   |
+| `disabled`      | `boolean`                      | `false`      | Disables all children                           |
+| `helperText`    | `string`                       | —            | Hint text below the group                       |
+| `showErrorText` | `boolean`                      | `true`       | Show validation error message                   |
+| `variant`       | `string`                       | `'default'`  | Theme variant                                   |
+| `theme`         | `EVENTS`                       | —            | One-off token override                          |
+
+### Example
+
+```tsx
+import CheckboxGroup from '@components/molecules/CheckboxGroup';
+import Checkbox from '@components/atoms/Checkbox';
+
+const schema = z.object({
+  skills: z.array(z.string()).min(1, 'Selecciona al menos una'),
+});
+
+<CheckboxGroup name='skills' control={control} label='Habilidades' direction='horizontal'>
+  <Checkbox value='react' label='React' />
+  <Checkbox value='vue' label='Vue' />
+  <Checkbox value='svelte' label='Svelte' />
+</CheckboxGroup>
+```
+
+## CheckboxTree
+
+A hierarchical checkbox group. The parent checkbox controls all children simultaneously and shows an indeterminate state when some (but not all) children are checked.
+
+### Props
+
+| Prop                | Type          | Default          | Description                                          |
+| ------------------- | ------------- | ---------------- | ---------------------------------------------------- |
+| `name`              | `string`      | —                | RHF field name                                       |
+| `control`           | `Control`     | —                | RHF control object                                   |
+| `children`          | `ReactNode`   | —                | `<Checkbox>` elements (each must have `value`)       |
+| `label`             | `string`      | —                | Label on the parent (select-all) checkbox            |
+| `iconChecked`       | `JSX.Element` | checkmark        | Icon on the parent when all children are checked     |
+| `iconIndeterminate` | `JSX.Element` | dash             | Icon on the parent when some children are checked    |
+| `disabled`          | `boolean`     | `false`          | Disables the parent and all children                 |
+| `helperText`        | `string`      | —                | Hint text below the tree                             |
+| `showErrorText`     | `boolean`     | `true`           | Show validation error message                        |
+| `variant`           | `string`      | `'default'`      | Theme variant                                        |
+| `theme`             | `EVENTS`      | —                | One-off token override                               |
+
+### Example
+
+```tsx
+import CheckboxTree from '@components/molecules/CheckboxTree';
+import Checkbox from '@components/atoms/Checkbox';
+
+<CheckboxTree name='permissions' control={control} label='Seleccionar todo'>
+  <Checkbox value='read' label='Leer' />
+  <Checkbox value='write' label='Escribir' />
+  <Checkbox value='delete' label='Eliminar' />
+</CheckboxTree>
+```
+
+## RadioGroup
+
+Manages a set of `Radio` children as a single `string` RHF field. The value is the `value` prop of the selected child.
+
+### Props
+
+| Prop            | Type                           | Default      | Description                                    |
+| --------------- | ------------------------------ | ------------ | ---------------------------------------------- |
+| `name`          | `string`                       | —            | RHF field name                                 |
+| `control`       | `Control`                      | —            | RHF control object                             |
+| `children`      | `ReactNode`                    | —            | `<Radio>` elements (each must have `value`)    |
+| `label`         | `string`                       | —            | Group label above the radios                   |
+| `direction`     | `'vertical' \| 'horizontal'`   | `'vertical'` | Layout direction of the items                  |
+| `disabled`      | `boolean`                      | `false`      | Disables all children                          |
+| `helperText`    | `string`                       | —            | Hint text below the group                      |
+| `showErrorText` | `boolean`                      | `true`       | Show validation error message                  |
+| `variant`       | `string`                       | `'default'`  | Theme variant                                  |
+| `theme`         | `EVENTS`                       | —            | One-off token override                         |
+
+### Example
+
+```tsx
+import RadioGroup from '@components/molecules/RadioGroup';
+import Radio from '@components/atoms/Radio';
+
+const schema = z.object({
+  plan: z.string().min(1, 'Selecciona un plan'),
+});
+
+<RadioGroup name='plan' control={control} label='Plan' direction='horizontal'>
+  <Radio value='free' label='Gratis' />
+  <Radio value='pro' label='Pro' />
+  <Radio value='enterprise' label='Enterprise' />
+</RadioGroup>
+```
+
+## Chip
+
+A compact inline label for displaying statuses, tags, or categories. Height is fixed at 24px and width adapts to its content.
+
+### Props
+
+| Prop        | Type        | Default     | Description                                                   |
+| ----------- | ----------- | ----------- | ------------------------------------------------------------- |
+| `children`  | `ReactNode` | —           | Label text or custom content                                  |
+| `variant`   | `string`    | `'default'` | Theme variant — any key defined under `CHIP` in your theme    |
+| `className` | `string`    | —           | Extra CSS class                                               |
+| `theme`     | `EVENTS`    | —           | One-off token override                                        |
+
+When `children` is a plain string it is wrapped in a `span.--CHIP-label` that applies horizontal padding. Pass a `ReactNode` to render custom content (e.g. icon + text) directly inside the chip.
+
+### Example
+
+```tsx
+import Chip from '@components/atoms/Chip';
+
+// Plain string — wrapped in a padded span automatically
+<Chip>Activo</Chip>
+<Chip variant='myVariant'>Pendiente</Chip>
+
+// Custom content — ReactNode renders directly inside the chip
+<Chip variant='myVariant'>
+  <Icon name='star' />
+  <span>Destacado</span>
+</Chip>
+```
+
+## Toast
+
+A notification system built around a React context. `ThemeProvider` automatically includes the provider — no additional setup required. Call `useToast` from anywhere inside the tree to push transient messages.
+
+### Setup
+
+`ThemeProvider` includes `ToastProvider` internally. Optionally configure position and default duration via the `toast` prop:
+
+```tsx
+<ThemeProvider themes={[darkTheme]} theme='dark' toast={{ position: 'top-right', duration: 4000 }}>
+  <App />
+</ThemeProvider>
+```
+
+### `useToast`
+
+```tsx
+import { useToast } from '@hooks';
+
+const { push } = useToast();
+
+push('Archivo guardado', { variant: 'success', icon: 'check_circle' });
+```
+
+### `push` options
+
+| Option     | Type      | Default     | Description                                        |
+| ---------- | --------- | ----------- | -------------------------------------------------- |
+| `variant`  | `string`  | `'default'` | Theme variant (maps to a key defined in the theme) |
+| `icon`     | `string`  | —           | Material Symbols icon name rendered on the left    |
+| `duration` | `number`  | `3000`      | Milliseconds before the toast auto-dismisses       |
+| `closable` | `boolean` | `false`     | Render a × button so the user can dismiss manually |
+
+### `ToastPosition`
+
+| Value             | Description  |
+| ----------------- | ------------ |
+| `'bottom-right'`  | Default      |
+| `'bottom-center'` | Bottom center |
+| `'bottom-left'`   | Bottom left  |
+| `'top-right'`     | Top right    |
+| `'top-center'`    | Top center   |
+| `'top-left'`      | Top left     |
+
+### Example
+
+```tsx
+import { useToast } from '@hooks';
+
+const Notifier = () => {
+  const { push } = useToast();
+
+  const save = async () => {
+    try {
+      await api.save();
+      push('Guardado correctamente', { icon: 'check_circle' });
+    } catch {
+      push('No se pudo guardar', { icon: 'error', closable: true, duration: 8000 });
+    }
+  };
+
+  return <Button onClick={save}>Guardar</Button>;
+};
+```
+
+### Defining toast variants in the theme
+
+Toast variants are defined in the theme under the `TOAST` key. Each variant must be self-contained (all tokens, not just overrides) because `useCreateComponentStyles` loads only the requested variant:
+
+```ts
+import type { TOAST } from '@hocs/ThemeProvider/components/molecules/Toast';
+
+const toast = {
+  TOAST: {
+    DEFAULT: {
+      ROOT: { 'background-color': '#1e293b', 'border-radius': '6px' },
+      EVENTS: {
+        ENABLED: {
+          'color-primary': '#f8fafc',
+          'border-color': '#334155',
+          'icon-color': '#94a3b8',
+        },
+      },
+    },
+    // Add as many named variants as your design requires
+    MY_VARIANT: {
+      ROOT: { 'background-color': '#1e293b', 'border-radius': '6px' },
+      EVENTS: {
+        ENABLED: {
+          'color-primary': '#f8fafc',
+          'border-color': '#10b981',
+          'icon-color': '#10b981',
+        },
+      },
+    },
+  },
+} as const satisfies TOAST;
+```
 
 ## Project structure