@foi/design-system 0.0.18 → 0.0.20

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
@@ -81,9 +83,7 @@ All field components share the same integration pattern. Define a Zod schema, pa
 import { useForm } from 'react-hook-form';
 import { zodResolver } from '@hookform/resolvers/zod';
 import { z } from 'zod';
-import TextField from '@components/atoms/TextField';
-import NumberField from '@components/atoms/NumberField';
-import Button from '@components/atoms/Button';
+import { TextField, NumberField, Button } from '@foi/design-system';
 
 const schema = z.object({
   email: z.string().email('Invalid email'),
@@ -139,31 +139,30 @@ 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
 
 ```tsx
-import TextField from '@components/atoms/TextField';
-import Icon from '@components/atoms/Icon';
+import { TextField, Icon } from '@foi/design-system';
 
 <TextField
   name='email'
@@ -172,7 +171,7 @@ import Icon from '@components/atoms/Icon';
   type='email'
   startAdornment={<Icon name='mail' />}
   helperText='We will never share your email'
-/>
+/>;
 ```
 
 ## NumberField
@@ -183,12 +182,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
 
@@ -207,7 +206,7 @@ All `TextField` props apply except `type`, `endAdornment`, and `startAdornment`
 ### Example
 
 ```tsx
-import NumberField from '@components/atoms/NumberField';
+import { NumberField } from '@foi/design-system';
 
 // Standard — quantity picker with bounds
 <NumberField
@@ -235,8 +234,8 @@ import NumberField from '@components/atoms/NumberField';
 Wrap your app in `ThemeProvider` and pass one or more named themes. The active theme is selected by the `theme` prop and its tokens are injected as CSS custom properties that every component consumes.
 
 ```tsx
-import ThemeProvider from '@hocs/ThemeProvider';
-import darkTheme from './themes/dark';
+import { ThemeProvider } from '@foi/design-system';
+import { darkTheme } from '@foi/design-system/theme';
 
 <ThemeProvider themes={[darkTheme]} theme='dark'>
   <App />
@@ -249,11 +248,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 { BUTTON } from '@foi/design-system/theme';
+// BUTTON includes the EVENTS type — autocomplete shows only the states Button supports
+```
 
 ```ts
-import type { BUTTON } from '@hocs/ThemeProvider/components/Button';
+import type { BUTTON } from '@foi/design-system/theme';
 
 const component = {
   BUTTON: {
@@ -321,15 +344,19 @@ An async data table that delegates all data operations to the server via `onFetc
 ### Defining columns
 
 ```tsx
-import DataGrid from '@components/organisms/DataGrid';
-import type { DataGridColumn } from '@components/organisms/DataGrid';
+import { DataGrid } from '@foi/design-system';
+import type { DataGridColumn } from '@foi/design-system';
 
-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' },
   },
@@ -345,7 +372,7 @@ const columns: DataGridColumn<Product>[] = [
 `label` accepts any `ReactNode`. A plain string is automatically wrapped in the themed `--DATAGRID-thLabel` span so it inherits the header typography. Pass a custom node to render icons, badges, or anything else without that wrapper:
 
 ```tsx
-import Icon from '@components/atoms/Icon';
+import { Icon } from '@foi/design-system';
 
 {
   key: 'price',
@@ -369,7 +396,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 +425,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
 
@@ -411,9 +438,7 @@ A portal-based overlay dialog. Renders into `document.body` so it sits above all
 ### Basic usage
 
 ```tsx
-import Modal from '@components/molecules/Modal';
-import Button from '@components/atoms/Button';
-import Icon from '@components/atoms/Icon';
+import { Modal, Button, Icon } from '@foi/design-system';
 
 const [open, setOpen] = useState(false);
 
@@ -428,38 +453,601 @@ 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, Icon } from '@foi/design-system';
+
+<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 '@foi/design-system';
+
+<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, Icon } from '@foi/design-system';
+
+<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 '@foi/design-system';
+
+// 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 '@foi/design-system';
+
+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 '@foi/design-system';
+
+<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, Icon } from '@foi/design-system';
+
+<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 '@foi/design-system';
+
+// 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 '@foi/design-system';
+
+// 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 '@foi/design-system';
+
+<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, Checkbox } from '@foi/design-system';
+
+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, Checkbox } from '@foi/design-system';
+
+<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, Radio } from '@foi/design-system';
+
+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 '@foi/design-system';
+
+// 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 '@foi/design-system/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 '@foi/design-system/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 '@foi/design-system/theme';
+
+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