@foi/design-system 0.0.11 → 0.0.13

package/README.md

@@ -50,8 +50,10 @@ npm publish --access public
 | `Icon`       | Font-based icon using Material Symbols Rounded — pass a `name` prop |
 | `IconButton` | Clickable icon with button semantics                                |
 | `Input`      | Text input field with label, helper text, and error state           |
+| `Pagination` | Page navigation bar with first/prev/next/last buttons and optional rows-per-page selector |
 | `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                                   |
 | `Switch`     | Toggle switch — boolean RHF field                                   |
 
@@ -61,8 +63,15 @@ npm publish --access public
 | --------------- | -------------------------------------------------------------- |
 | `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        |
 
+### Organisms
+
+| 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
 
 All field components share the same integration pattern. Define a Zod schema, pass `control` down, and let the component handle registration, value sync, and error display.
@@ -206,13 +215,144 @@ Any component also accepts a `theme` prop — a partial `EVENTS` object — to o
 <Button label='Special' theme={{ ENABLED: { 'background-color': '#7c3aed' } }} />
 ```
 
+## DataGrid
+
+An async data table that delegates all data operations to the server via `onFetch`.
+
+### Defining columns
+
+```tsx
+import DataGrid from '@components/organisms/DataGrid';
+import type { DataGridColumn } from '@components/organisms/DataGrid';
+
+interface Product { id: number; name: string; price: number; }
+
+const columns: DataGridColumn<Product>[] = [
+  {
+    key: 'name',
+    label: 'Product',
+    type: 'text',
+    filter: { type: 'search' },
+  },
+  {
+    key: 'price',
+    label: 'Price',
+    type: 'number',
+    render: value => `$${Number(value).toLocaleString('es-CL')}`,
+  },
+];
+```
+
+### The `onFetch` contract
+
+`onFetch` receives `{ page, pageSize, sort?, filters? }` and must return `{ data, total }`. It is called automatically whenever the page, sort, or any filter changes.
+
+```tsx
+const onFetch = async ({ page, pageSize, sort, filters }) => {
+  const response = await api.getProducts({ page, pageSize, sort, filters });
+  return { data: response.items, total: response.total };
+};
+
+<DataGrid<Product> columns={columns} onFetch={onFetch} />
+```
+
+### Action columns
+
+Add a column with `type: 'options'` and a `render` prop to define row-level actions. The `render` receives `(value, row)` — use `row` to call your handlers or control Modal state.
+
+```tsx
+const [pendingDelete, setPendingDelete] = useState<Product | null>(null);
+
+const columnsWithActions: DataGridColumn<Product>[] = [
+  ...columns,
+  {
+    key: 'actions',
+    label: '',
+    type: 'options',
+    sortable: false,
+    render: (_value, row) => (
+      <>
+        <IconButton icon={<Icon name='edit' size='sm' />} onClick={() => onEdit(row)} aria-label='Edit' />
+        <IconButton icon={<Icon name='delete' size='sm' />} onClick={() => setPendingDelete(row)} aria-label='Delete' />
+      </>
+    ),
+  },
+];
+```
+
+### Pagination modes
+
+| 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      |
+
+## Modal
+
+A portal-based overlay dialog. Renders into `document.body` so it sits above all other content regardless of DOM nesting.
+
+### Basic usage
+
+```tsx
+import Modal from '@components/molecules/Modal';
+import Button from '@components/atoms/Button';
+import Icon from '@components/atoms/Icon';
+
+const [open, setOpen] = useState(false);
+
+<Modal
+  open={open}
+  onClose={() => setOpen(false)}
+  header={
+    <>
+      <Icon name='info' />
+      <span className='--MODAL-title'>Información</span>
+    </>
+  }
+  footer={
+    <>
+      <Button onClick={() => setOpen(false)} variant='ghost'>Cancelar</Button>
+      <Button onClick={() => setOpen(false)}>Aceptar</Button>
+    </>
+  }
+>
+  Contenido del 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                |
+
+### Close triggers
+
+| Trigger          | `staticBackdrop=false` | `staticBackdrop=true` |
+| ---------------- | ---------------------- | --------------------- |
+| × button         | ✓                      | ✓                     |
+| Backdrop click   | ✓                      | —                     |
+| Escape key       | ✓                      | —                     |
+
 ## Project structure
 
 ```
 src/
 ├── components/
 │   ├── atoms/       # Primitive UI components
-│   └── molecules/   # Composed components built from atoms
+│   ├── molecules/   # Composed components built from atoms
+│   └── organisms/   # Complex components composed from molecules and atoms
 ├── hocs/
 │   ├── ThemeProvider/   # Global theme context and CSS-variable injection
 │   ├── MarginPage/      # Page layout wrapper