ywana-core8 0.2.150 → 0.2.151

package/COMPONENT_CONTRACTS.md

@@ -0,0 +1,1392 @@
+# Contrato de componentes — ywana-core8
+
+> Este documento describe el **contrato de uso público** (props, callbacks, ejemplos) de los
+> componentes exportados por `ywana-core8`. Está pensado para que lo consuman **agentes de IA
+> de otras aplicaciones** que importan esta librería, de forma que puedan generar código
+> correcto sin tener que leer el código fuente del paquete.
+>
+> Todos los componentes se importan desde el paquete raíz:
+> ```jsx
+> import { NombreComponente } from 'ywana-core8'
+> ```
+> No uses rutas internas (`ywana-core8/html/...`, `ywana-core8/widgets/...`, etc.) — la única
+> API soportada es el export raíz.
+
+## Convenciones generales
+
+- **Callbacks con id primero**: la mayoría de callbacks siguen el patrón `onChange(id, value, ...)`
+  en vez de `onChange(event)`. Revisa la firma exacta en cada componente antes de asumir nada.
+- **Controlado vs no controlado**: cuando un componente indica "Controlado" por una prop (p.ej.
+  `value`, `selected`, `checkedFiles`), ese componente **no** gestiona el valor internamente — si
+  no actualizas la prop en tu `onChange`, la UI no cambia. Cuando indica "No controlado", el
+  componente mantiene su propio estado y solo notifica cambios vía callback.
+- **Iconos**: la prop `icon` (y variantes `menuIcon`, `emptyIcon`, etc.) siempre espera el nombre
+  de un [Material Icon](https://fonts.google.com/icons) en formato `snake_case` (ej. `delete`,
+  `arrow_back`, `folder_open`), nunca un componente ni una URL.
+- **`id` obligatorio en inputs**: `CheckBox`, `TextField` (y alias), `RadioButton`, `DropDown`,
+  `DateRange` requieren `id` — sin él, algunos emiten `console.warn` y otros fallan al asociar
+  label/input.
+- **i18n**: varios componentes (`TextField`, `Text`, `Site`/`SiteProvider`) usan internamente un
+  `TranslationContext`; si tu app no lo provee, funcionan igual pero sin traducir literales
+  especiales.
+- **CSS por variables**: varios widgets (p.ej. `FileExplorer`, densidades de grid) se personalizan
+  sobreescribiendo custom properties CSS en vez de props — revisa la doc específica del
+  componente si necesitas cambiar tamaños/colores.
+- **Componentes "V2" o "2"**: cuando existen dos versiones (`TextField`/`TextField2`,
+  `Header`/`Header2`, `Tree`/`Tree2`, `DataTable`/`DataTable2`/`DataTable3`, `upload`/`upload2`),
+  la versión sin sufijo (o la de número más alto) es la recomendada; la otra se mantiene solo por
+  compatibilidad hacia atrás y no debe usarse en código nuevo salvo migración.
+
+---
+
+## Índice
+
+1. [HTML — Inputs y controles](#1-html--inputs-y-controles)
+2. [HTML — Layout, visualización y datos](#2-html--layout-visualización-y-datos)
+3. [Site — Shell de aplicación](#3-site--shell-de-aplicación)
+4. [Widgets — Componentes de negocio genéricos](#4-widgets--componentes-de-negocio-genéricos)
+
+---
+
+## 1. HTML — Inputs y controles
+
+### `Button`
+Import: `import { Button } from 'ywana-core8'`
+Story: [src/html/Button.stories.jsx](src/html/Button.stories.jsx)
+
+Propósito: Botón accesible con soporte para iconos, estados de carga y múltiples variantes visuales.
+
+Props:
+| Prop | Tipo | Default | Requerido | Descripción |
+| --- | --- | --- | --- | --- |
+| id | string | — | No | Identificador único del botón |
+| label | string \| React.Element | — | Sí (o icon o ariaLabel) | Texto o componente del botón |
+| icon | string | — | No | Nombre del icono Material Icon a mostrar |
+| rightIcon | string | — | No | Icono a mostrar en el lado derecho |
+| action | function | — | No | Alias para onClick (callback) |
+| disabled | boolean | false | No | Desactiva el botón |
+| loading | boolean | false | No | Estado de carga (muestra spinner) |
+| outlined | boolean | false | No | Estilo con borde (sin relleno) |
+| raised | boolean | false | No | Estilo elevado (sombra) |
+| size | 'small' \| 'normal' \| 'large' | 'normal' | No | Tamaño del botón |
+| type | 'button' \| 'submit' \| 'reset' | 'button' | No | Tipo HTML del botón |
+| className | string | — | No | Clases CSS adicionales |
+| ariaLabel | string | — | No | Etiqueta ARIA para accesibilidad |
+| tooltip | string | — | No | Texto de tooltip |
+| form | string | — | No | ID del formulario asociado |
+
+Callbacks: `onClick(event)`, `action(event)`, `onFocus(event)`, `onBlur(event)`, `onKeyDown(event)`
+
+Controlado/No controlado: No controlado (loading/hover internos, responde a callbacks).
+
+Ejemplo mínimo:
+```jsx
+<Button label="Click me" onClick={() => handleClick()} />
+```
+
+Notas: Requiere al menos una de `label`, `icon` o `ariaLabel`.
+
+---
+
+### `ActionButton`
+Import: `import { ActionButton } from 'ywana-core8'`
+Story: [src/html/Button.stories.jsx](src/html/Button.stories.jsx)
+
+Propósito: Botón que cambia entre múltiples estados predefinidos y ejecuta acciones asociadas a cada estado.
+
+Props:
+| Prop | Tipo | Default | Requerido | Descripción |
+| --- | --- | --- | --- | --- |
+| states | object | — | Sí | Mapa de nombre de estado a `{label, icon, action, autoexec}` |
+| state | string | — | Sí | Estado actual del botón |
+| className | string | — | No | Clases CSS adicionales |
+| disabled | boolean | false | No | Desactiva el botón |
+| onStateChange | function | — | No | Callback cuando cambia el estado |
+
+Callbacks: `onStateChange(newState)`
+
+Controlado/No controlado: Controlado por `state`.
+
+Ejemplo mínimo:
+```jsx
+<ActionButton
+  state="idle"
+  states={{ idle: { label: 'Start' }, loading: { label: 'Loading...', autoexec: true } }}
+  onStateChange={(state) => setCurrentState(state)}
+/>
+```
+
+Notas: `autoexec: true` en la configuración de un estado ejecuta su `action` automáticamente al entrar en ese estado.
+
+---
+
+### `CheckBox`
+Import: `import { CheckBox } from 'ywana-core8'`
+Story: [src/html/Checkbox.stories.jsx](src/html/Checkbox.stories.jsx)
+
+Propósito: Casilla de verificación accesible con soporte para estados indeterminado, error y lectura.
+
+Props:
+| Prop | Tipo | Default | Requerido | Descripción |
+| --- | --- | --- | --- | --- |
+| id | string | — | **Sí** | Identificador único |
+| label | string | — | No | Etiqueta de texto |
+| value | boolean | false | No | Estado checado actual |
+| readOnly | boolean | false | No | Solo lectura |
+| disabled | boolean | false | No | Deshabilitado |
+| indeterminate | boolean | false | No | Estado indeterminado (símbolo -) |
+| error | boolean \| string | false | No | Estado error; si es string, muestra el mensaje |
+| required | boolean | false | No | Campo requerido |
+| className | string | — | No | Clases CSS adicionales |
+| ariaLabel | string | — | No | Etiqueta ARIA |
+
+Callbacks: `onChange(id, checked)`
+
+Controlado/No controlado: Controlado por `value`.
+
+Ejemplo mínimo:
+```jsx
+<CheckBox id="agree" label="I agree" value={isChecked} onChange={(id, checked) => setIsChecked(checked)} />
+```
+
+Notas: `indeterminate` es independiente de `value` (no se deriva de él).
+
+---
+
+### `RadioButton`
+Import: `import { RadioButton } from 'ywana-core8'`
+Story: [src/html/Radio.stories.jsx](src/html/Radio.stories.jsx)
+
+Propósito: Botón de opción individual con validación y estados de error/lectura.
+
+Props:
+| Prop | Tipo | Default | Requerido | Descripción |
+| --- | --- | --- | --- | --- |
+| id | string | — | **Sí** | Identificador único |
+| name | string | — | **Sí** | Atributo `name` para agrupar |
+| label | string | — | No | Etiqueta de texto |
+| value | string \| number | id | No | Valor del radio |
+| checked | boolean | false | No | Si está seleccionado |
+| disabled | boolean | false | No | Deshabilitado |
+| readOnly | boolean | false | No | Solo lectura |
+| error | boolean \| string | false | No | Estado error |
+| required | boolean | false | No | Campo requerido |
+
+Callbacks: `onChange(id, value, event)`
+
+Controlado/No controlado: Controlado por `checked`.
+
+Ejemplo mínimo:
+```jsx
+<RadioButton id="opt1" name="group" label="Option 1" checked={selected === 'opt1'} onChange={(id, val) => setSelected(val)} />
+```
+
+Notas: Usa `RadioGroup` en vez de instancias sueltas cuando sea posible; simplifica el manejo de `name`.
+
+---
+
+### `RadioGroup`
+Import: `import { RadioGroup } from 'ywana-core8'`
+Story: [src/html/Radio.stories.jsx](src/html/Radio.stories.jsx)
+
+Propósito: Grupo de botones de opción con gestión centralizada y sincronización.
+
+Props:
+| Prop | Tipo | Default | Requerido | Descripción |
+| --- | --- | --- | --- | --- |
+| id | string | — | No | Identificador único del grupo |
+| label | string | — | No | Etiqueta del grupo |
+| value | string \| number | — | No | Valor seleccionado |
+| options | array | [] | No | `[{id, label, value, disabled, ariaLabel}]` |
+| disabled | boolean | false | No | Deshabilita el grupo |
+| readOnly | boolean | false | No | Solo lectura |
+| error | boolean \| string | false | No | Estado error |
+| required | boolean | false | No | Campo requerido |
+
+Callbacks: `onChange(groupId, value, event)`
+
+Controlado/No controlado: Controlado por `value`.
+
+Ejemplo mínimo:
+```jsx
+<RadioGroup label="Choose one" value={selected} options={[{ label: 'A' }, { label: 'B' }]} onChange={(id, val) => setSelected(val)} />
+```
+
+Notas: Genera automáticamente `id`/`name` internos para cada `RadioButton` si no se proporcionan.
+
+---
+
+### `Switch`
+Import: `import { Switch } from 'ywana-core8'`
+Story: [src/html/Switch.stories.jsx](src/html/Switch.stories.jsx)
+
+Propósito: Control deslizante on/off con soporte para colores personalizados y tamaños.
+
+Props:
+| Prop | Tipo | Default | Requerido | Descripción |
+| --- | --- | --- | --- | --- |
+| id | string | — | No | Identificador único |
+| label | string | — | No | Etiqueta de texto |
+| checked | boolean | false | No | Estado actual |
+| disabled | boolean | false | No | Deshabilitado |
+| readOnly | boolean | false | No | Solo lectura |
+| error | boolean \| string | false | No | Estado error |
+| required | boolean | false | No | Campo requerido |
+| size | 'small' \| 'normal' \| 'large' | 'normal' | No | Tamaño |
+| onColor | string | '#007bff' | No | Color cuando está ON |
+| offColor | string | '#ccc' | No | Color cuando está OFF |
+
+Callbacks: `onChange(id, checked)`
+
+Controlado/No controlado: Controlado por `checked`.
+
+Ejemplo mínimo:
+```jsx
+<Switch id="toggle" label="Enabled" checked={isOn} onChange={(id, val) => setIsOn(val)} />
+```
+
+Notas: Acepta Espacio/Enter por teclado.
+
+---
+
+### `TextField`
+Import: `import { TextField } from 'ywana-core8'`
+Story: [src/html/TextField.stories.jsx](src/html/TextField.stories.jsx)
+
+Propósito: Campo de entrada de texto universal con soporte para múltiples tipos, validación y debounce.
+
+Props:
+| Prop | Tipo | Default | Requerido | Descripción |
+| --- | --- | --- | --- | --- |
+| id | string | — | **Sí** | Identificador único |
+| type | string | 'text' | No | Tipo HTML: text, email, password, number, tel, url, search, date, time, etc. |
+| label | string \| React.Element | — | No | Etiqueta |
+| labelPosition | 'top' \| 'left' | 'top' | No | Posición de la etiqueta |
+| placeholder | string | — | No | Placeholder |
+| value | string \| number | — | No | Valor actual |
+| outlined | boolean | false | No | Estilo con borde |
+| readOnly / disabled / required | boolean | false | No | Estados estándar |
+| canClear | boolean | true | No | Muestra botón limpiar |
+| showPasswordToggle | boolean | true | No | Toggle mostrar/ocultar (solo type="password") |
+| autoComplete | string | 'off' | No | Atributo HTML autocomplete |
+| error | string | — | No | Mensaje de error |
+| helperText | string | — | No | Texto de ayuda |
+| maxLength / minLength / pattern / step / min / max | — | — | No | Restricciones estándar de input |
+| rows | number | 3 | No | Filas (solo `TextArea`) |
+| validation | function | — | No | `(value) => boolean \| {valid, message}` |
+| debounceMs | number | 0 | No | Debounce de `onChange` en ms |
+
+Callbacks: `onChange(id, value, event)`, `onEnter(id, value, event)`, `onKeyDown(id, key, event)`, `onValidation(id, isValid, errorMessage)`, `onFocus(event)`, `onBlur(event)`
+
+Controlado/No controlado: Controlado por `value`.
+
+Ejemplo mínimo:
+```jsx
+<TextField id="email" type="email" placeholder="user@example.com" value={email} onChange={(id, val) => setEmail(val)} />
+```
+
+Notas: La validación se evalúa tras la primera interacción del usuario (touched), no en el primer render.
+
+---
+
+### `TextArea`
+Import: `import { TextArea } from 'ywana-core8'`
+Story: [src/html/TextField.stories.jsx](src/html/TextField.stories.jsx)
+
+Propósito: Alias de `TextField` con `type="textarea"` para texto multilínea. Mismas props/callbacks que `TextField`, más `rows`.
+
+Ejemplo mínimo:
+```jsx
+<TextArea id="message" placeholder="Enter message" value={text} onChange={(id, val) => setText(val)} rows={5} />
+```
+
+---
+
+### `PasswordField`
+Import: `import { PasswordField } from 'ywana-core8'`
+Story: [src/html/TextField.stories.jsx](src/html/TextField.stories.jsx)
+
+Propósito: Alias de `TextField` con `type="password"` y toggle mostrar/ocultar. Mismas props/callbacks que `TextField`.
+
+Ejemplo mínimo:
+```jsx
+<PasswordField id="pwd" value={password} onChange={(id, val) => setPassword(val)} showPasswordToggle />
+```
+
+---
+
+### `DropDown`
+Import: `import { DropDown } from 'ywana-core8'`
+Story: [src/html/TextField.stories.jsx](src/html/TextField.stories.jsx)
+
+Propósito: Selector desplegable con soporte para búsqueda, selección múltiple, agrupación y renderizado personalizado.
+
+Props:
+| Prop | Tipo | Default | Requerido | Descripción |
+| --- | --- | --- | --- | --- |
+| id | string | — | **Sí** | Identificador único |
+| options | array | [] | No | `[{value, label, disabled, ...}]` |
+| value | string \| number \| array | — | No | Seleccionado (array si `multiple`) |
+| placeholder / label | string | — | No | Textos |
+| outlined / disabled / readOnly / required | boolean | false | No | Estados estándar |
+| searchable | boolean | false | No | Búsqueda en opciones |
+| clearable | boolean | false | No | Botón limpiar |
+| multiple | boolean | false | No | Selección múltiple |
+| groupBy | string \| function | — | No | Agrupar opciones |
+| filterFunction | function | — | No | Filtro custom |
+| renderOption / renderValue | function | — | No | Render personalizado |
+| position | 'top' \| 'bottom' | 'bottom' | No | Posición del menú |
+| menuPortal | boolean | false | No | Renderiza el menú en un portal |
+| predictive / verbose / editable | boolean | — | No | Legacy: alias de `searchable` / mostrar label / entrada libre |
+
+Callbacks: `onChange(id, value, option)`, `onOpen()`, `onClose()`, `onSearch(searchTerm)`, `onBlur(event)`
+
+Controlado/No controlado: Controlado por `value`.
+
+Ejemplo mínimo:
+```jsx
+<DropDown id="select" options={[{ value: 1, label: 'A' }, { value: 2, label: 'B' }]} value={selected} onChange={(id, val) => setSelected(val)} />
+```
+
+---
+
+### `DateRange`
+Import: `import { DateRange } from 'ywana-core8'`
+Story: [src/html/TextField.stories.jsx](src/html/TextField.stories.jsx)
+
+Propósito: Selector de rango de fechas con validación de rango y restricciones min/max.
+
+Props:
+| Prop | Tipo | Default | Requerido | Descripción |
+| --- | --- | --- | --- | --- |
+| id | string | — | **Sí** | Identificador único |
+| value | `{from, to}` (ISO strings) | — | No | Rango actual |
+| minDate / maxDate | string (ISO) | — | No | Límites permitidos |
+| required | boolean | false | No | Ambas fechas requeridas |
+| canClear | boolean | true | No | Botón limpiar |
+
+Callbacks: `onChange(id, {from, to})`, `onValidation(id, isValid, errorMessage)`
+
+Controlado/No controlado: Controlado por `value`.
+
+Ejemplo mínimo:
+```jsx
+<DateRange id="dateRange" value={{ from: '2024-01-01', to: '2024-12-31' }} onChange={(id, range) => setRange(range)} />
+```
+
+Notas: Valida `from < to` y límites `minDate`/`maxDate`. No es error si falta una fecha salvo `required`.
+
+---
+
+### `TokenField`
+Import: `import { TokenField } from 'ywana-core8'`
+Story: [src/html/TokenField.stories.jsx](src/html/TokenField.stories.jsx)
+
+Propósito: Campo para entrada de múltiples tokens/etiquetas con validación, separadores y opciones desplegables.
+
+Props:
+| Prop | Tipo | Default | Requerido | Descripción |
+| --- | --- | --- | --- | --- |
+| tokens | array | [] | No | Tokens actuales (controlado) |
+| options | array | — | No | Opciones predefinidas para autocompletar |
+| maxTokens / minTokens | number | — / 0 | No | Límites |
+| allowDuplicates | boolean | true | No | Permite tokens duplicados |
+| validateToken | function | — | No | `(token, tokens) => {isValid, error}` |
+| tokenSeparators | array | `[',', ';', '\n']` | No | Caracteres separadores |
+| searchable / sortable / clearable | boolean | false | No | Comportamiento del dropdown |
+| placeholder | string | 'Add token...' | No | Placeholder |
+
+Callbacks: `onChange(id, tokens)`, `onTokenAdd(token, index)`, `onTokenRemove(token, index)`, `onValidationError(error, token)`, `onClear()`, `onFocus(event)`, `onBlur(event)`
+
+Controlado/No controlado: Controlado por `tokens`.
+
+Ejemplo mínimo:
+```jsx
+<TokenField id="tags" tokens={myTags} onChange={(id, tokens) => setMyTags(tokens)} placeholder="Add tags..." />
+```
+
+Notas: Backspace en input vacío elimina el último token; pegar texto con separadores crea varios tokens de golpe.
+
+---
+
+### `MultiSelector`
+Import: `import { MultiSelector } from 'ywana-core8'`
+Story: [src/html/Selector.stories.jsx](src/html/Selector.stories.jsx)
+
+Propósito: Selector visual de múltiples opciones (renderiza `ToggleButton` por opción) con búsqueda y límites de selección.
+
+Props:
+| Prop | Tipo | Default | Requerido | Descripción |
+| --- | --- | --- | --- | --- |
+| options | array | [] | No | `[{value, label, selected, disabled}]` |
+| maxSelections / minSelections | number | — / 0 | No | Límites de selección |
+| searchable | boolean | false | No | Búsqueda de opciones |
+| allowClear | boolean | false | No | Botón "Clear All" |
+| loading / empty | boolean | false | No | Estados especiales |
+| emptyMessage | string | 'No options available' | No | Mensaje vacío |
+
+Callbacks: `onChange(selectedValues)`, `onClear()`
+
+Controlado/No controlado: Semi-controlado — la selección inicial viene de `options[].selected`, pero el toggle se gestiona internamente; `onChange` reporta cada cambio.
+
+Ejemplo mínimo:
+```jsx
+<MultiSelector options={[{ value: 'a', label: 'Option A' }, { value: 'b', label: 'Option B', selected: true }]} onChange={(selections) => console.log(selections)} />
+```
+
+---
+
+### `ToggleButton`
+Import: `import { ToggleButton } from 'ywana-core8'`
+Story: [src/html/Selector.stories.jsx](src/html/Selector.stories.jsx)
+
+Propósito: Botón seleccionable on/off, normalmente usado dentro de `MultiSelector`.
+
+Props: `label`, `value`, `selected` (boolean, controlado), `disabled`, `icon`, `variant`, `size`, `tooltip`.
+
+Callbacks: `onToggle(value)`
+
+Ejemplo mínimo:
+```jsx
+<ToggleButton label="Option" value="opt1" selected={isSelected} onToggle={(val) => handleToggle(val)} />
+```
+
+---
+
+### `Slider`
+Import: `import { Slider } from 'ywana-core8'`
+Story: [src/html/slider.stories.jsx](src/html/slider.stories.jsx)
+
+Propósito: Control deslizante de rango numérico.
+
+Props: `min` (0), `max` (100), `step` (1), `value` (0, controlado), `showValue` (true), `disabled`.
+
+Callbacks: `onChange(newValue)`
+
+Ejemplo mínimo:
+```jsx
+<Slider min={0} max={100} value={volume} onChange={(val) => setVolume(val)} />
+```
+
+Notas: No requiere `id`. Incluye un `<input type="range">` oculto para accesibilidad.
+
+---
+
+### `ColorField`
+Import: `import { ColorField } from 'ywana-core8'`
+Story: [src/html/Color.stories.jsx](src/html/Color.stories.jsx)
+
+Propósito: Selector de color con soporte para múltiples formatos y colores predefinidos.
+
+Props:
+| Prop | Tipo | Default | Requerido | Descripción |
+| --- | --- | --- | --- | --- |
+| value | string | — | No | Color actual (hex/rgb/hsl) |
+| format | 'hex' \| 'rgb' \| 'hsl' | 'hex' | No | Formato de salida |
+| shape | 'rectangle' \| 'circle' | 'rectangle' | No | Forma del picker |
+| allowTransparent | boolean | false | No | Permite `'transparent'` |
+| presetColors | array | [] | No | Colores predefinidos seleccionables |
+| clearable | boolean | false | No | Botón limpiar |
+
+Callbacks: `onChange(id, color)`, `onFocus(event)`, `onBlur(event)`, `onClear()`
+
+Controlado/No controlado: Controlado por `value`.
+
+Ejemplo mínimo:
+```jsx
+<ColorField id="bgColor" value="#ff0000" onChange={(id, color) => setColor(color)} />
+```
+
+---
+
+### `Form`
+Import: `import { Form } from 'ywana-core8'`
+Story: [src/html/Form.stories.jsx](src/html/Form.stories.jsx)
+
+Propósito: Contenedor de formulario que gestiona múltiples campos hijos, validación agregada y grid de columnas.
+
+Props:
+| Prop | Tipo | Default | Requerido | Descripción |
+| --- | --- | --- | --- | --- |
+| id / title | string | — | No | Identificador y título |
+| columns | number | 1 | No | Columnas del grid |
+| children | ReactNode | — | **Sí** | Campos (deben tener `id`) |
+| outlined / disabled / loading | boolean | false | No | Estados aplicados a los hijos |
+| autoComplete | 'on' \| 'off' | 'on' | No | Atributo HTML |
+| noValidate | boolean | false | No | Desactiva validación HTML5 |
+
+Callbacks: `onChange(formData, isValid)`, `onSubmit(formData, event)` (async-safe), `onReset(event)`, `onValidationChange(isValid, fields)`
+
+Controlado/No controlado: Los campos hijos se "elevan" al `Form`, que centraliza el estado.
+
+Ejemplo mínimo:
+```jsx
+<Form columns={2} onSubmit={(data) => console.log('Submit:', data)}>
+  <TextField id="name" label="Name" value="" />
+  <TextField id="email" label="Email" value="" />
+</Form>
+```
+
+Notas: Cada hijo debe declarar `id` para que `Form` pueda componer `formData`.
+
+---
+
+## 2. HTML — Layout, visualización y datos
+
+### `Accordion`
+Import: `import { Accordion } from 'ywana-core8'`
+Story: [src/html/Accordion.stories.jsx](src/html/Accordion.stories.jsx)
+
+Propósito: Secciones colapsables, con soporte para múltiples abiertas a la vez y checkboxes opcionales por sección.
+
+Props: `sections` (array `{id, open, checked, icon, title, subtitle, disabled, children}`, requerido), `disabled`, `allowMultiple` (true), `animated` (true), `loading`, `skeleton`, `skeletonCount` (4), `emptyMessage`/`emptyIcon`.
+
+Callbacks: `onToggle(index, isOpen, section)`, `onCheck(index, isChecked, sectionId, section)`, `onSectionChange(action, index, value, section)`
+
+Controlado/No controlado: No controlado (abre/cierra internamente).
+
+Ejemplo mínimo:
+```jsx
+<Accordion sections={[{ id: 'sec1', title: 'Sección 1', children: <p>Contenido</p> }]} onToggle={(idx, open) => console.log(idx, open)} />
+```
+
+Notas: Una sección muestra checkbox solo si define `checked` (no `undefined`).
+
+---
+
+### `ActionsCell`
+Import: `import { ActionsCell } from 'ywana-core8'`
+Story: [src/html/ActionsCell.stories.jsx](src/html/ActionsCell.stories.jsx)
+
+Propósito: Contenedor de acciones (botones) que detecta overflow automáticamente y colapsa a un menú `⋮` cuando no caben.
+
+Props: `actions` (ReactNode, requerido — normalmente botones), `maxWidth` (200), `menuIcon` ('more_horiz'), `menuAlign`, `menuSize`, `gap`.
+
+Ejemplo mínimo:
+```jsx
+<ActionsCell maxWidth={150} actions={<><Button icon="edit" onClick={handleEdit} /><Button icon="delete" onClick={handleDelete} /></>} />
+```
+
+Notas: Extrae `icon`/`title`/`label`/`onClick`/`disabled` de los botones hijos para reconstruirlos como items de menú. Útil en celdas de tabla.
+
+---
+
+### `Header`
+Import: `import { Header } from 'ywana-core8'`
+Story: [src/html/Header.stories.jsx](src/html/Header.stories.jsx)
+
+Propósito: Encabezado simple con título, icono opcional y acciones (children). Sin estado propio.
+
+Props: `title` (string|ReactNode), `icon`, `iconSrc`, `img` (fondo), `caption`/`prominent`/`dense` (variantes de altura), `primary`/`secondary` (tema), `clickable`, `action`.
+
+Callbacks: `action(event)` si `clickable`.
+
+Ejemplo mínimo:
+```jsx
+<Header title="Mi Sección" icon="dashboard" primary><Button label="Acción" /></Header>
+```
+
+---
+
+### `Header2`
+Import: `import { Header2 } from 'ywana-core8'`
+Story: — (sin fichero .stories.jsx; ver src/html/header2.example.js)
+
+Propósito: Versión mejorada de `Header` (misma apariencia) con mejor accesibilidad, `loading`/`disabled` y callback de icono independiente. Preferir sobre `Header` en código nuevo.
+
+Props: igual que `Header` más `disabled`, `loading`, `role` ('banner').
+
+Callbacks: `onClick(event)`, `onIconClick(event)` (prioridad sobre `action`).
+
+Ejemplo mínimo:
+```jsx
+<Header2 title="Dashboard" icon="dashboard" loading={isLoading} onIconClick={handleIconClick} />
+```
+
+---
+
+### `Icon`
+Import: `import { Icon } from 'ywana-core8'`
+Story: [src/html/Icon.stories.jsx](src/html/Icon.stories.jsx)
+
+Propósito: Wrapper de Material Icons con estados interactivos, tooltip y accesibilidad — primitiva usada en casi todos los demás componentes.
+
+Props: `icon` (string, **requerido**), `size` ('small'|'normal'|'large'), `clickable`, `disabled`, `action`, `eventPropagation` (false — por defecto detiene la propagación del click), `tooltip` (`{text, top, left}`), `ariaLabel`.
+
+Callbacks: `action(event)` si `clickable`.
+
+Ejemplo mínimo:
+```jsx
+<Icon icon="delete" clickable action={handleDelete} tooltip={{ text: 'Eliminar' }} />
+```
+
+Notas: Soporta Enter/Espacio por teclado cuando `clickable`. Con `eventPropagation={false}` (default) el click no burbujea — importante si el icono vive dentro de un elemento con su propio `onClick`.
+
+---
+
+### `IconButtonGroup`
+Import: `import { IconButtonGroup } from 'ywana-core8'`
+Story: [src/html/IconButtonGroup.stories.jsx](src/html/IconButtonGroup.stories.jsx)
+
+Propósito: Grupo segmentado de botones de icono con un único valor activo (toggles de vista/tamaño).
+
+Props: `value` (requerido), `onChange` (**requerido**), `items` (`[{value, icon, tooltip?}]`).
+
+Callbacks: `onChange(nextValue)`
+
+Controlado/No controlado: **Controlado** por `value`.
+
+Ejemplo mínimo:
+```jsx
+<IconButtonGroup value="grid" onChange={setViewMode} items={[{ value: 'list', icon: 'list' }, { value: 'grid', icon: 'grid_view' }]} />
+```
+
+---
+
+### `List`
+Import: `import { List } from 'ywana-core8'`
+Story: [src/html/List.stories.jsx](src/html/List.stories.jsx)
+
+Propósito: Lista avanzada con búsqueda, ordenamiento, selección (simple/múltiple), agrupamiento y estados vacío/cargando.
+
+Props: `items` (`[{id, line1, line2}]`), `selected` (id o array), `groupBy`, `groupRenderer`, `loading`/`empty`/`emptyMessage`/`emptyIcon`, `searchable`/`searchPlaceholder`/`searchBy` (`['line1','line2']`), `sortable`/`sortBy`/`sortDirection`, `multiSelect`, `dense`, `disabled`, `maxHeight`.
+
+Callbacks: `onSelect(id, event)`, `onMultiSelect(selectedIds)`, `onSort(config)`
+
+Controlado/No controlado: `selected` es controlado; búsqueda/orden son internos.
+
+Ejemplo mínimo:
+```jsx
+<List items={[{ id: 1, line1: 'Item 1' }]} selected={selectedId} onSelect={setSelectedId} searchable />
+```
+
+---
+
+### `MenuIcon`, `MenuButton`, `MenuBar`, `Menu`, `MenuItem`, `MenuSeparator`
+Import: `import { MenuIcon, MenuButton, MenuBar, Menu, MenuItem, MenuSeparator } from 'ywana-core8'`
+Story: [src/html/Menu.stories.jsx](src/html/Menu.stories.jsx)
+
+Propósito: Familia de componentes de menú desplegable.
+- `MenuIcon`: icono clickeable que abre un menú vertical (`position`: bottom-left/right, top-left/right, left/right/top/bottom; `menuSize`).
+- `MenuButton`: botón con label que abre el mismo tipo de menú (`showArrow`, `outlined`, `raised`).
+- `MenuBar`: contenedor horizontal para agrupar varios `MenuButton` (estilo barra de menú tipo app de escritorio).
+- `Menu`: contenedor base de bajo nivel (rara vez se usa directamente).
+- `MenuItem`: opción individual — `label` (**requerido**), `icon`, `meta` (ReactNode, p.ej. atajo de teclado), `disabled`, `onSelect()`.
+- `MenuSeparator`: línea divisoria, sin props.
+
+Callbacks: `MenuItem.onSelect()` (cierra el menú padre automáticamente al seleccionar).
+
+Ejemplo mínimo:
+```jsx
+<MenuIcon icon="more_vert" position="bottom-right">
+  <MenuItem icon="edit" label="Editar" onSelect={handleEdit} />
+  <MenuSeparator />
+  <MenuItem icon="delete" label="Eliminar" onSelect={handleDelete} />
+</MenuIcon>
+```
+
+Notas: Los hijos de `MenuIcon`/`MenuButton`/`Menu` deben ser `MenuItem`/`MenuSeparator`; los de `MenuBar` deben ser `MenuButton`.
+
+---
+
+### `CircularProgress`, `LinearProgress`, `RadialProgress`, `StepProgress`, `MultiProgress`
+Import: `import { CircularProgress, LinearProgress, RadialProgress, StepProgress, MultiProgress } from 'ywana-core8'`
+Story: [src/html/Progress.stories.jsx](src/html/Progress.stories.jsx)
+
+Propósito: Familia de indicadores de progreso, todos **controlados** por `value`/`currentStep`/`items` (sin estado interno de progreso).
+
+- `CircularProgress` / `RadialProgress`: progreso circular SVG. Props comunes: `value`, `max` (100), `size`, `thickness`, `variant` ('determinate'|'indeterminate', solo en `CircularProgress`), `showValue`, `showLabel`, `label`, `icon`, `animated`, `formatValue(value, max)`.
+- `LinearProgress`: barra horizontal. Añade `buffer` (pre-buffering), `striped`, `rounded`, `estimatedTime`, `speed`.
+- `StepProgress`: progreso multi-paso tipo wizard. `steps` (`[{id, label, description?, icon?, error?}]`, **requerido**), `currentStep` (0), `variant` ('horizontal'|'vertical'), `allowClickNavigation`.
+- `MultiProgress`: varias `LinearProgress` con etiqueta. `items` (`[{id, label, value, max, color?, formatValue?}]`, **requerido**).
+
+Callbacks: `onComplete()` (cuando `value >= max`, en Circular/Linear), `onStepClick(stepIndex, step)` (StepProgress, solo si `allowClickNavigation`).
+
+Ejemplo mínimo:
+```jsx
+<CircularProgress value={65} max={100} variant="determinate" showValue />
+<StepProgress steps={[{ label: 'Paso 1' }, { label: 'Paso 2' }]} currentStep={1} />
+```
+
+---
+
+### `Property`
+Import: `import { Property } from 'ywana-core8'`
+Story: [src/html/Property.stories.jsx](src/html/Property.stories.jsx)
+
+Propósito: Fila "etiqueta + valor/input" para formularios inline tipo ficha de detalle, con validación integrada.
+
+Props: `id`/`label` (**requeridos**), `value`, `initial` (fallback), `editable` (false = solo lectura), `type` ('text' etc.), `multiline`/`rows`, `options` (para modo select), `validateValue(val) => {isValid, error}`, `layout` ('horizontal'|'vertical'), `nameWidth` ('50%'), `copyable`, `clearable` (true).
+
+Callbacks: `onChange(id, newValue)`, `onFocus(event)`, `onBlur(event)`, `onValidationError(error, value)`
+
+Controlado/No controlado: Controlado por `value`.
+
+Ejemplo mínimo:
+```jsx
+<Property id="email" label="Email" value={email} editable onChange={(id, val) => setEmail(val)} type="email" required />
+```
+
+---
+
+### `Section`
+Import: `import { Section } from 'ywana-core8'`
+Story: [src/html/Section.stories.jsx](src/html/Section.stories.jsx)
+
+Propósito: Sección colapsable con `Header` integrado (título + icono) y contenido plegable.
+
+Props: `title`, `icon`, `open` (estado inicial, false), `canCollapse` (true), `actions` (ReactNode extra en el header).
+
+Controlado/No controlado: No controlado (gestiona `open` internamente tras el montaje).
+
+Ejemplo mínimo:
+```jsx
+<Section title="Detalles" icon="info" open={false}><p>Contenido de la sección</p></Section>
+```
+
+---
+
+### `Tabs`, `Tab`, `Stack`
+Import: `import { Tabs, Tab, Stack } from 'ywana-core8'`
+Story: [src/html/Tab.stories.jsx](src/html/Tab.stories.jsx)
+
+Propósito: Sistema de pestañas.
+- `Tabs`: contenedor — `selected` (**controlado**, id o índice), `onChange(idOrIndex)` (**requerido para que funcione**), `orientation` ('horizontal'|'vertical'), `variant` ('standard'|'scrollable'|'fullWidth'), `centered`, `persistent`/`persistKey` (guarda selección en localStorage), `beforeChange(idOrIndex, currentSelected) => canChange` (hook cancelable, puede ser async).
+- `Tab`: pestaña individual — `label` (**requerido**), `id`, `icon`, `badge`, `disabled`, `closeable`, `onClose(tabId)`, `tooltip`.
+- `Stack`: renderiza solo el hijo en el índice `selected` (**controlado**) — útil para wizards fuera de `Tabs`.
+
+Ejemplo mínimo:
+```jsx
+<Tabs selected={selectedTab} onChange={setSelectedTab}>
+  <Tab id="tab1" label="Tab 1" icon="home">Contenido 1</Tab>
+  <Tab id="tab2" label="Tab 2" icon="settings">Contenido 2</Tab>
+</Tabs>
+```
+
+---
+
+### `Text`
+Import: `import { Text, TEXTFORMATS } from 'ywana-core8'`
+Story: [src/html/Text.stories.jsx](src/html/Text.stories.jsx)
+
+Propósito: Texto con formateo automático (números, fechas, moneda, etc.) e i18n vía `Intl`.
+
+Props: `format` (uno de `TEXTFORMATS`: HTML, STRING, NUMERIC, CURRENCY, PERCENTAGE, DATE, TIME, DATETIME, EMAIL, PHONE, URL, CAPITALIZE, UPPERCASE, LOWERCASE, TRUNCATE — default HTML), `children` (valor a formatear), `locale`, `currency` ('USD'), `dateStyle`/`timeStyle`, `truncate`/`maxLength`, `fallback`, `loading`/`skeleton`, `copyable`, `as` ('span' por defecto).
+
+Ejemplo mínimo:
+```jsx
+<Text format={TEXTFORMATS.CURRENCY} currency="EUR">{1234.56}</Text>
+```
+
+Notas: Usa `Intl.NumberFormat`/`Intl.DateTimeFormat` — pasa el valor crudo (number/Date), no ya formateado.
+
+---
+
+### `Thumbnail`
+Import: `import { Thumbnail } from 'ywana-core8'`
+Story: [src/html/Thumbnail.stories.jsx](src/html/Thumbnail.stories.jsx)
+
+Propósito: Imagen miniatura con estados carga/error, placeholder, overlay y badge.
+
+Props: `src`, `alt`, `title`, `loading` ('lazy'|'eager'), `placeholder`/`fallback` (ReactNode), `objectFit` ('cover' por defecto), `size` ('small'|'medium'|'large'|'xlarge'), `shape` ('square'|'circle'|'rounded'), `bordered`/`shadow`, `clickable`, `overlay`, `badge`.
+
+Callbacks: `onClick(event)`, `onLoad(event)`, `onError(event)`
+
+Ejemplo mínimo:
+```jsx
+<Thumbnail src="/image.jpg" size="large" shape="circle" badge="New" clickable />
+```
+
+---
+
+### `Tooltip`
+Import: `import { Tooltip } from 'ywana-core8'`
+Story: [src/html/Tooltip.stories.jsx](src/html/Tooltip.stories.jsx)
+
+Propósito: Envuelve contenido para mostrar un tooltip posicionado en hover.
+
+Props: `text` (string|ReactNode), `top`/`left` (posición CSS, defaults `'1rem'`).
+
+Ejemplo mínimo:
+```jsx
+<Tooltip text="Haz click aquí"><Button label="Acción" /></Tooltip>
+```
+
+Notas: Muchos otros componentes (Icon, Chip, IconButtonGroup...) ya aceptan una prop `tooltip={{text}}` propia — no hace falta envolverlos con este componente en esos casos.
+
+---
+
+### `Tree`, `TreeNode`, `TreeItem`
+Import: `import { Tree, TreeNode, TreeItem } from 'ywana-core8'`
+Story: [src/html/Tree.stories.jsx](src/html/Tree.stories.jsx)
+
+Propósito: Árbol jerárquico declarativo (vía JSX anidado) con búsqueda, multi-selección y drag&drop.
+
+Props (`Tree`): `searchable`/`searchPlaceholder`/`searchBy` (`['label']`), `multiSelect`, `onMultiSelect(selectedIds)`, `showExpandIcon` (control global expandir/colapsar todo), `loading`/`empty`/`emptyMessage`/`emptyIcon`.
+
+Props (`TreeNode`, rama con hijos): `id`/`label` (**requeridos**), `icon` ('folder'), `open` (estado inicial), `expandable` (true), `disabled`, `draggable`, `badge`, `actions`, `onSelect(id)`, `onDragStart(id, event)`, `onDrop(draggedId, targetId, event)`.
+
+Props (`TreeItem`, hoja): `id`/`label` (**requeridos**), `icon` ('description'), `selected`, `checked`, `onSelect(id)`, `onCheck(id, checked)`.
+
+Ejemplo mínimo:
+```jsx
+<Tree searchable showExpandIcon>
+  <TreeNode id="folder1" label="Carpeta 1" icon="folder">
+    <TreeItem id="file1" label="Archivo 1" onSelect={handleSelect} />
+  </TreeNode>
+</Tree>
+```
+
+Notas: Click en la fila de un `TreeNode` (fuera del chevron) selecciona y expande/colapsa a la vez. La multi-selección aplica solo a `TreeItem` con `multiSelect` activo en el `Tree` padre.
+
+---
+
+### `Tree2`, `TreeNode2`, `TreeItem2`
+Import: `import { Tree2, TreeNode2, TreeItem2 } from 'ywana-core8'`
+Story: [src/html/tree2.stories.jsx](src/html/tree2.stories.jsx)
+
+Propósito: Variante de árbol con **lazy loading** async por nodo (para árboles muy grandes/remotos), con estados de error y vacío por nodo.
+
+Props (`TreeNode2`): `id`/`label` (**requeridos**), `icon` ('folder'), `loadOnExpand` (activa carga diferida), `onExpand(nodeId) => Promise<childrenPropsArray>`, `onRefresh(nodeId) => Promise<...>`, `loading`/`error`/`empty`, `contextMenu` (`[{label, icon, onClick}]`).
+
+Props (`TreeItem2`): `id`/`label` (**requeridos**), `icon` ('description'), `onSelect(itemId)`, `selected`, `contextMenu`.
+
+Ejemplo mínimo:
+```jsx
+<Tree2>
+  <TreeNode2
+    id="folder1" label="Documentos" icon="folder" loadOnExpand
+    onExpand={async (nodeId) => {
+      const children = await fetchFolderContents(nodeId)
+      return children.map(c => ({ id: c.id, label: c.name, icon: c.isFolder ? 'folder' : 'description', isLeaf: !c.isFolder, loadOnExpand: c.isFolder }))
+    }}
+  />
+</Tree2>
+```
+
+Notas: `onExpand`/`onRefresh` deben devolver un array de props listo para renderizar (`isLeaf: true` renderiza automáticamente como `TreeItem2`).
+
+---
+
+### `DataTable` (deprecated)
+Import: `import { DataTable } from 'ywana-core8'`
+Story: [src/html/Table.stories.jsx](src/html/Table.stories.jsx)
+
+⚠️ **Deprecated** — usar `DataTable2` (uso general) o `DataTable3` (>1000 filas). Se mantiene solo por compatibilidad.
+
+Props mínimas: `columns` (formato legacy), `rows` (**requeridos**), `editable`, `multisort`, `filterable`.
+
+Callbacks: `onRowSelection(row, event)`, `onSort(draggedRow, droppedRow)`, `onCheckAll(ids, value)`, `onClearFilters()`
+
+---
+
+### `DataTable2`
+Import: `import { DataTable2 } from 'ywana-core8'`
+Story: [src/html/Table2.stories.jsx](src/html/Table2.stories.jsx)
+
+Propósito: Tabla avanzada recomendada por defecto — ordenamiento, filtrado, selección, resize de columnas, sidebar de herramientas, exportación, agrupación y temas.
+
+Props principales:
+| Prop | Tipo | Default | Descripción |
+| --- | --- | --- | --- |
+| `columns` | array | [] | `{id, label, sortable?, filterable?, width?, minWidth?, maxWidth?, render?(value, row), className?}` |
+| `rows` | array | [] | Cada fila necesita `id`; `info: () => ReactNode` para contenido expandible |
+| `sortDir` | object | — | Controlado: `{ [columnId]: 1 \| -1 }` |
+| `selectedRows` | array | [] | Ids seleccionados (controlado) |
+| `filters` | object | {} | Estado de filtros (controlado) |
+| `showSelectAll` / `showRowNumbers` | boolean | false | Extras de columna |
+| `editable` | boolean | false | Edición inline de celdas |
+| `theme` | 'default'\|'dark'\|'minimal'\|'readable' | 'default' | Tema visual |
+| `density` | 'compact'\|'normal'\|'comfortable' | 'normal' | Densidad de filas |
+| `stickyHeader` / `resizable` | boolean | false / true | Comportamiento de header/columnas |
+| `showSidebar` / `exportable` | boolean | false | Panel lateral / exportar datos |
+| `groupBy` | string \| function | — | Agrupar filas |
+
+Callbacks: `onSort(columnId, dir)`, `onSelect(rowId, event)` (y alias `onRowSelection(row, event)`), `onCheckAll(rowIds, value)`, `onCellEdit(rowId, columnId, value)`, `onCellClick(event, colId, rowId, value)`, `onRowDoubleClick(row)`, `onClearFilters()`, `onColumnResize(colId, width)`, `onExport(data, format)`, `onGroupByChange(value)`
+
+Controlado/No controlado: `selectedRows`, `sortDir`, `filters` son controlados si se pasan; si no, estado interno.
+
+Ejemplo mínimo:
+```jsx
+<DataTable2
+  columns={[{ id: 'name', label: 'Nombre', sortable: true }, { id: 'email', label: 'Email', filterable: true }]}
+  rows={users}
+  selectedRows={selectedRows}
+  onSelect={(id) => setSelectedRows([id])}
+/>
+```
+
+Notas: hay documentación extendida en `src/html/table2.md`.
+
+---
+
+### `DataTable3`
+Import: `import { DataTable3 } from 'ywana-core8'`
+Story: [src/html/Table3.stories.jsx](src/html/Table3.stories.jsx)
+
+Propósito: Igual que `DataTable2` pero con **virtualización** — usar solo si el dataset supera ~1000 filas.
+
+Props relevantes además de las compartidas con `DataTable2`: `height`/`maxHeight` (recomendado fijar altura), `rowHeight` (44), `overscan` (8), `virtualize` (true), `virtualizeThreshold` (200), `showColumnsPanel`.
+
+Callbacks: mismos patrones que `DataTable2` (`onSort`, `onSelect`, `onCellClick`, `onCellDoubleClick`, `onColumnResize`, `onExport`).
+
+Ejemplo mínimo:
+```jsx
+<DataTable3 columns={columns} rows={largeDataset} selectedRows={selected} onSelect={setSelected} height="600px" virtualize exportable />
+```
+
+---
+
+## 3. Site — Shell de aplicación
+
+Estos componentes forman el **layout raíz** típico de una app construida con `ywana-core8`:
+`SiteProvider` (contexto global) → `Site` (shell visual) → `Page` (una por sección) → `View`/`Dialog` dentro de cada página según necesidad.
+
+### `SiteProvider`
+Import: `import { SiteProvider } from 'ywana-core8'`
+Story: [src/site/site.stories.jsx](src/site/site.stories.jsx)
+
+Propósito: Provider de contexto raíz — navegación, diálogos, notificaciones, logs e i18n. Debe envolver toda la app.
+
+Props: `children` (**requerido**), `siteLang` (**requerido**), `siteDictionary` (**requerido**, `{key: {lang: value}}`).
+
+Contexto expuesto (via `SiteContext`): navegación (`page`, `goto(id)`, `goBack()`, `gotoNewTab(pageId, params)`, `readPageParams(pageId)`, `direction`), i18n (`lang`, `setLang`, `translate(key)`), menú (`sideNav`, `showNav`, `setShowNav`), diálogos (`dialog`, `openDialog(content)`, `closeDialog()`, `promptDialog`, `openPromptDialog`/`closePromptDialog`), preview (`openPreview(content)`/`closePreview()`), notificaciones (`notify({title, body, type, duration, onRemoval})`), info/breadcrumb, consola de logs (`writeLog`, `clearLog`), y legacy `confirm()`/`prompt()`.
+
+Ejemplo mínimo:
+```jsx
+<SiteProvider siteLang="es" siteDictionary={dict}>
+  <Site title="Mi App">{/* Pages */}</Site>
+</SiteProvider>
+```
+
+Notas: Requiere `react-toastify` para notificaciones. Integra `TranslationProvider` internamente.
+
+---
+
+### `Site`
+Import: `import { Site } from 'ywana-core8'`
+Story: [src/site/site.stories.jsx](src/site/site.stories.jsx)
+
+Propósito: Shell visual completo: header, menú lateral navegable (construido a partir de los `Page` hijos), área de contenido, preview lateral, consola y footer.
+
+Props: `children` (`Page[]`, **requerido**), `icon` ('equalizer'), `iconSrc` (logo, prevalece sobre `icon`), `title`, `toolbar`, `footer`, `init` (id de página inicial), `min` (menú colapsado al inicio), `lang`/`dictionary`.
+
+Controlado/No controlado: No controlado (navegación vía hash URL).
+
+Ejemplo mínimo:
+```jsx
+<Site title="Mi App" icon="widgets" init="HOME">
+  <Page id="HOME" title="Inicio" icon="home"><HomePage /></Page>
+  <Page id="ABOUT" title="Acerca de" icon="info"><AboutPage /></Page>
+</Site>
+```
+
+Notas: Cada `Page` hijo directo aparece automáticamente en el menú lateral usando su `title`/`icon`.
+
+---
+
+### `SiteContext`
+Import: `import { SiteContext } from 'ywana-core8'`
+Story: [src/site/site.stories.jsx](src/site/site.stories.jsx)
+
+Propósito: React Context consumido con `useContext(SiteContext)` para acceder a navegación/diálogos/notificaciones desde cualquier componente descendiente de `SiteProvider`.
+
+Ejemplo mínimo:
+```jsx
+const site = useContext(SiteContext)
+site.goto('DETAIL')
+site.notify({ title: 'Guardado', type: 'success' })
+```
+
+---
+
+### `Page`, `PageContext`, `PageProvider`
+Import: `import { Page, PageContext, PageProvider } from 'ywana-core8'`
+Story: [src/site/site.stories.jsx](src/site/site.stories.jsx)
+
+Propósito: `Page` renderiza una sección de `Site`; solo una está visible a la vez (controlada por hash URL). Cada `Page` trae su propio contexto local (`PageContext`) para estado aislado a esa página.
+
+Props (`Page`): `id` (**requerido**, usado en el hash), `children` (**requerido**), `layout` ('simple'), `context` (estado inicial de `PageContext`), `title`/`icon` (usados por `Site` para el menú, opcionales pero recomendados).
+
+`PageContext`: `[pageCtx, setPageCtx] = useContext(PageContext)` — estado local a la página actual.
+
+`PageProvider`: wrapper manual de `PageContext` (`Page` ya lo incluye; rara vez se usa suelto).
+
+Ejemplo mínimo:
+```jsx
+<Page id="HOME" title="Inicio" icon="home">
+  <h1>Bienvenido</h1>
+</Page>
+```
+
+Notas: `Page` debe ser hijo directo de `Site`.
+
+---
+
+### `Dialog`
+Import: `import { Dialog } from 'ywana-core8'`
+Story: [src/site/site.stories.jsx](src/site/site.stories.jsx)
+
+Propósito: Modal renderizado sobre overlay. **No se monta directamente** — se abre/cierra vía `SiteContext.openDialog()`/`closeDialog()`.
+
+Props: `title` ('Dialog'), `icon`, `children` (**requerido**), `actions` (footer con botones), `toolbar`, `className` ('prompt' para una segunda capa modal sobre otro diálogo), `onClose`, `overlayCanClose` (true — click fuera cierra).
+
+Ejemplo mínimo:
+```jsx
+const site = useContext(SiteContext)
+site.openDialog(
+  <Dialog title="¿Confirmar?" actions={<Button onClick={() => site.closeDialog()}>Aceptar</Button>}>
+    <p>¿Estás seguro?</p>
+  </Dialog>
+)
+```
+
+---
+
+### `View`, `TabbedView`
+Import: `import { View, TabbedView } from 'ywana-core8'`
+Story: [src/site/site.stories.jsx](src/site/site.stories.jsx)
+
+Propósito: Sección visual reutilizable con header colapsable, toolbar, menú e info en footer — usable dentro de una `Page` o en cualquier otro lugar. `TabbedView` es la variante que además renderiza tabs en el toolbar (cada hijo con prop `label` es una pestaña).
+
+Props (`View`): `title`, `icon`, `toolbar`, `menu` (esquina superior derecha), `info` (footer), `children` (**requerido**), `canCollapse` (false), `onClose`.
+
+Props (`TabbedView`): `title`, `selected` (índice, controlado externamente), `children` (**requerido**, cada uno con `label`).
+
+Ejemplo mínimo:
+```jsx
+<View title="Configuración" icon="settings" canCollapse>
+  <p>Contenido aquí</p>
+</View>
+
+<TabbedView title="Análisis" selected={tabIndex}>
+  <div label="Resumen">…</div>
+  <div label="Detalles">…</div>
+</TabbedView>
+```
+
+---
+
+### `PageLink`
+Import: `import { PageLink } from 'ywana-core8'`
+Story: [src/site/site.stories.jsx](src/site/site.stories.jsx)
+
+Propósito: `<a>` declarativo que navega entre páginas usando `SiteContext` (alternativa a llamar `site.goto()` manualmente).
+
+Props: `page` (id destino, **requerido**), `children` (**requerido**), `className`, `style`.
+
+Ejemplo mínimo:
+```jsx
+<PageLink page="DETAIL">Ver detalle</PageLink>
+```
+
+---
+
+### `useHashPage`
+Import: `import { useHashPage } from 'ywana-core8'`
+Story: — (sin fichero .stories.jsx; hook interno de src/site/site.js)
+
+Propósito: Hook de navegación por hash URL con historial y dirección de transición (usado internamente por `SiteProvider`; rara vez se llama directamente).
+
+Firma: `useHashPage(defaultPage = 'home')` → `{ page, goto(id, dir?), goBack(), history, direction }`.
+
+---
+
+### `Workspace`
+Import: `import { Workspace } from 'ywana-core8'`
+Story: — (sin fichero .stories.jsx)
+
+Propósito: Layout experimental (WIP) con áreas colapsables (menú/header/nav/main/aside) y transiciones responsive. **No recomendado para producción.**
+
+---
+
+## 4. Widgets — Componentes de negocio genéricos
+
+### `LoginBox`
+Import: `import { LoginBox } from 'ywana-core8'`
+Story: [src/widgets/login/Login.stories.jsx](src/widgets/login/Login.stories.jsx)
+
+Propósito: Formulario de login (usuario + contraseña) con estados de carga y mensaje de error.
+
+Props: `userLabel`/`passwordLabel`/`loginLabel` (textos), `userValue`/`passwordValue` (iniciales), `message` (error/info), `loading`, `disabled`, `children` (contenido extra, p.ej. link "¿Olvidaste tu contraseña?").
+
+Callbacks: `onOK(user, password)`
+
+Controlado/No controlado: No controlado (estado interno de los campos).
+
+Ejemplo mínimo:
+```jsx
+<LoginBox onOK={(user, pwd) => authenticate(user, pwd)} message={error} loading={isLoading} />
+```
+
+Notas: Solo valida que ambos campos no estén vacíos; la validación real de credenciales es responsabilidad del `onOK`.
+
+---
+
+### `ResetPasswordBox`
+Import: `import { ResetPasswordBox } from 'ywana-core8'`
+Story: [src/widgets/login/Login.stories.jsx](src/widgets/login/Login.stories.jsx)
+
+Propósito: Formulario de cambio/reset de contraseña con validación de fortaleza integrada.
+
+Props: `userRequired` (true), `oldPwdRequired` (false), `validator(password) => [boolean, errorMessage]` (custom), `showStrength` (true), `submitLabel` ('OK'), `loading`/`disabled`.
+
+Callbacks: `onOK({ user?, oldPassword?, password1, password2 })`
+
+Ejemplo mínimo:
+```jsx
+<ResetPasswordBox userRequired={false} oldPwdRequired onOK={(form) => changePassword(form.password1)} />
+```
+
+Notas: El módulo `login/validations.js` expone además utilidades sueltas (`validatePassword`, `getPasswordStrength`, `createPasswordValidator`, etc.) reutilizables fuera del componente. `login/context.js`/`login/dialogs.js`/`login/actions.js` aportan un contexto y diálogos de soporte (recuperar contraseña, desbloquear usuario) pensados para integrarse con un backend propio — revisa el código si necesitas personalizarlos.
+
+---
+
+### `WaitScreen`
+Import: `import { WaitScreen } from 'ywana-core8'`
+Story: — (sin fichero .stories.jsx)
+
+Propósito: Pantalla de espera con spinner centrado. Sin props.
+
+Ejemplo mínimo:
+```jsx
+<WaitScreen />
+```
+
+---
+
+### `Viewer`
+Import: `import { Viewer } from 'ywana-core8'`
+Story: [src/widgets/viewer/Viewer.stories.jsx](src/widgets/viewer/Viewer.stories.jsx)
+
+Propósito: Visor universal de ficheros (imagen, vídeo, PDF, audio) con detección automática de tipo y navegación entre varios ficheros.
+
+Props: modo un solo fichero — `src`/`title` (requeridos en ese modo); modo múltiple — `files` (`[{id, title, src, filename, mimeType, thumbnail, info}]`), `initialFileId`, `showThumbnails`. Comunes: `filename`, `mimeType`, `info` (panel lateral), `actions` (array de componentes), `tools` (toolbar de controles), `onClose` (**requerido**).
+
+Callbacks: `onClose()`, `onFileChange(file, index)`
+
+Ejemplo mínimo:
+```jsx
+<Viewer src="https://example.com/image.jpg" title="Sample" onClose={() => setOpen(false)} tools />
+```
+
+Notas: Requiere red para cargar los ficheros; detecta tipo por `mimeType`/extensión.
+
+---
+
+### `Kanban`
+Import: `import { Kanban } from 'ywana-core8'`
+Story: [src/widgets/kanban/Kanban.stories.jsx](src/widgets/kanban/Kanban.stories.jsx)
+
+Propósito: Tablero kanban con columnas, swimlanes y drag&drop (usa `@dnd-kit`).
+
+Props: `children` (**requerido** — `KanbanColumn`/`KanbanSwimlane`/`KanbanCard`, importados aparte), `enableDragDrop` (false), `animated` (true), `loading`.
+
+Callbacks: `onCardMove(cardId, fromColumn, toColumn, fromSwimlane, toSwimlane, { fromIndex, toIndex, overId, overType })`, `onColumnEmptyAreaClick`
+
+Ejemplo mínimo:
+```jsx
+<Kanban enableDragDrop onCardMove={(id, from, to) => moveCard(id, from, to)}>
+  <KanbanColumn id="todo" title="To Do">
+    <KanbanCard id="card1">Task 1</KanbanCard>
+  </KanbanColumn>
+</Kanban>
+```
+
+---
+
+### `Avatar`
+Import: `import { Avatar } from 'ywana-core8'`
+Story: [src/widgets/avatar/Avatar.stories.jsx](src/widgets/avatar/Avatar.stories.jsx)
+
+Propósito: Avatar con imagen o iniciales (color determinista por nombre), badge de verificado.
+
+Props: `src`, `name` (para iniciales/color; sin nombre muestra "?"), `verified`, `size` ('small'|'medium'|'large'|'xlarge'), `clickable`, `action(id)`.
+
+Ejemplo mínimo:
+```jsx
+<Avatar src={user.avatar} name={user.name} verified={user.isVerified} size="large" />
+```
+
+Notas: Si `src` falla al cargar, cae automáticamente a iniciales.
+
+---
+
+### `Calendar`
+Import: `import { Calendar } from 'ywana-core8'`
+Story: [src/widgets/calendar/Calendar.stories.jsx](src/widgets/calendar/Calendar.stories.jsx)
+
+Propósito: Calendario multi-vista (año/mes/semana/día) con eventos y navegación.
+
+Props: `events` (array), `view` ('year'|'month'|'week'|'day'), `position` (fecha, semi-controlado), `availableViews` (`['year','month']`), `hideNavigation`, `enableDragDrop`.
+
+Callbacks: `onChange(position, range)`, `onViewChange(newView)`, `onEventClick(event)`, `onCellDoubleClick(date)`
+
+Ejemplo mínimo:
+```jsx
+<Calendar events={events} view="month" onChange={(pos) => setPosition(pos)} />
+```
+
+---
+
+### `DateRangePicker`
+Import: `import { DateRangePicker } from 'ywana-core8'`
+Story: [src/widgets/calendar/DateRangePicker/DateRangePicker.stories.jsx](src/widgets/calendar/DateRangePicker/DateRangePicker.stories.jsx)
+
+Propósito: Selector de rango de fechas horizontal con zoom/pan, minimap y selección por arrastre (usa `moment.js`).
+
+Props: `startDate`/`endDate` (rango total, **requeridos**), `selectedStart`/`selectedEnd` (rango seleccionado, controlado), `unit` ('day'|'week'|'month'|'year'), `weekStartsOnMonday` (true), `height` (160), `showMinimap` (true), `markers` (`[{date, label, color, backgroundColor}]`), `showUnitSelector` (true), `persistent`/`persistKey` (guarda en localStorage).
+
+Callbacks: `onRangeChange(start, end)` (objetos Moment), `onUnitChange(unit)`
+
+Ejemplo mínimo:
+```jsx
+<DateRangePicker startDate="2024-01-01" endDate="2024-12-31" selectedStart="2024-06-01" selectedEnd="2024-06-30" onRangeChange={(start, end) => console.log(start, end)} />
+```
+
+---
+
+### `Planner`
+Import: `import { Planner } from 'ywana-core8'`
+Story: — (sin fichero .stories.jsx)
+
+Propósito: Planificador con carriles (lanes/recursos) y eventos en un grid de fechas (usa `moment.js`).
+
+Props: `title`, `events`, `lanes` (recursos), `navigation` (true), `focusEvent` (id a enfocar), `config` (`{range: 'week'|'month'|'year', from, to}`).
+
+Callbacks: `onSelectCell(lane, date)`, `onChange(config)`
+
+Ejemplo mínimo:
+```jsx
+<Planner title="Roadmap" lanes={teams} events={tasks} onSelectCell={(lane, date) => addTask(lane, date)} />
+```
+
+---
+
+### `UploadV2`, `UploadButtonV2`, `UploadDialogV2`, `UploadDropZone`
+Import: `import { UploadV2, UploadButtonV2, UploadDialogV2, UploadDropZone } from 'ywana-core8'`
+Story: [src/widgets/upload2/Upload2.stories.jsx](src/widgets/upload2/Upload2.stories.jsx)
+
+Propósito: Familia moderna de subida de ficheros (basada en Axios/Fetch). Preferir sobre el paquete `upload` legacy (deprecated, basado en ResumableJS).
+
+- `UploadV2`: componente completo (drop-zone + lista/grid + progreso). Props: `url` (**requerido**), `uploadService` (custom, por defecto axios), `headers`, `accept`, `maxSize`, `maxFiles`, `multiple` (true), `autoUpload` (true), `simultaneousUploads` (3), `view` ('list'|'grid'). Callbacks: `onFileSuccess(file)`, `onFileError(file, error)`, `onAllComplete(stats)`.
+- `UploadButtonV2`: botón que solo abre el selector de ficheros (no sube nada). Props: `accept`, `multiple`, `label` ('Upload Files'), `icon`. Callback: `onFilesSelected(files)`.
+- `UploadDialogV2`: `UploadV2` envuelto en `Dialog`. Añade `open` (controlado), `onClose` (**requerido**), `title`, `additionalActions`.
+- `UploadDropZone`: solo el área de drag&drop con validación (sin lista/progreso). Props: `accept`, `maxSize`, `maxFiles`. Callbacks: `onFilesSelected(files)`, `onValidationError(errors)`.
+
+Ejemplo mínimo:
+```jsx
+<UploadV2 url="/api/upload" accept="image/*" maxSize={5242880} onFileSuccess={(f) => console.log(f.name)} />
+```
+
+---
+
+### `EmptyMessage`
+Import: `import { EmptyMessage } from 'ywana-core8'`
+Story: — (sin fichero .stories.jsx)
+
+Propósito: Mensaje de estado vacío (icono + texto centrados), usado por defecto dentro de listas/tablas/grids de esta librería cuando no hay datos.
+
+Props: `icon` (**requerido**), `text` (**requerido**).
+
+Ejemplo mínimo:
+```jsx
+<EmptyMessage icon="inbox" text="No messages yet" />
+```
+
+---
+
+### `ImageViewer`
+Import: `import { ImageViewer } from 'ywana-core8'`
+Story: — (sin fichero .stories.jsx)
+
+Propósito: Visor de imagen con zoom/rotación/pan controlado imperativamente vía `ref`.
+
+Props: `image` (**requerido**), `ref`.
+
+Métodos del ref: `zoomIn()`, `zoomOut()`, `resetZoom()`, `rotateLeft()`, `rotateRight()`, `flipHorizontal()`, `flipVertical()`, `resetTransform()`.
+
+Ejemplo mínimo:
+```jsx
+const imgRef = useRef()
+<ImageViewer ref={imgRef} image="https://example.com/image.jpg" />
+// imgRef.current.zoomIn()
+```
+
+---
+
+### `QueryBuilder`, `QuerySerializer`
+Import: `import { QueryBuilder, QuerySerializer } from 'ywana-core8'`
+Story: [src/widgets/querybuilder/QueryBuilder.stories.jsx](src/widgets/querybuilder/QueryBuilder.stories.jsx)
+
+Propósito: Constructor visual de queries (cláusulas + operadores + valores según tipo de campo) y utilidad de (de)serialización a filtros planos.
+
+Props (`QueryBuilder`): `fields` (`[{id, label, type, operators}]`, **requerido**), `descriptor` (`{logic, clauses}`, controlado), `onChange(descriptor)`.
+
+`QuerySerializer` (no es un componente, es un objeto utilitario): `toFilters(descriptor)`, `fromFilters(filters)`, `empty()`.
+
+Ejemplo mínimo:
+```jsx
+<QueryBuilder
+  fields={[{ id: 'name', label: 'Name', type: 'text' }]}
+  descriptor={{ logic: 'AND', clauses: [] }}
+  onChange={(q) => setQuery(q)}
+/>
+const filters = QuerySerializer.toFilters(descriptor) // { name: 'John' }
+```
+
+Notas: Los operadores disponibles dependen del `type` declarado en cada field.
+
+---
+
+### `AsyncImage`, `useInView`
+Import: `import { AsyncImage, useInView } from 'ywana-core8'`
+Story: [src/widgets/asyncimage/AsyncImage.stories.jsx](src/widgets/asyncimage/AsyncImage.stories.jsx)
+
+Propósito: `AsyncImage` es una `<img>` con estados carga/error y cancelación automática (AbortController) al cambiar `src` o desmontar. `useInView` es un hook de `IntersectionObserver` para lazy-loading, pensado para combinarse con `AsyncImage`.
+
+Props (`AsyncImage`): `src` (**requerido**), `alt`, `defaultStatus` ('loaded'|'error'), `onStatusChange(status)`, `loadingSlot`/`errorSlot` (ReactNode custom).
+
+`useInView(options = {})` → `{ ref, inView }` (options soporta `rootMargin` de `IntersectionObserverInit`).
+
+Ejemplo mínimo:
+```jsx
+const { ref, inView } = useInView({ rootMargin: '200px' })
+return <div ref={ref}>{inView && <AsyncImage src={url} onStatusChange={setStatus} />}</div>
+```
+
+---
+
+### `Chat`
+Import: `import { Chat } from 'ywana-core8'`
+Story: [src/widgets/chat/chat.stories.jsx](src/widgets/chat/chat.stories.jsx)
+
+Propósito: Chat genérico (lista de mensajes + input), sin backend integrado.
+
+Props: `messages` (`[{user, userName, text, date}]`, controlado), `user` (id del usuario actual, **requerido**), `readOnly` (false — oculta el input), `emptyMessage`, `formatDate(isoString)`, `theme`, `messageBg`.
+
+Callbacks: `onSend({user, text, date})`
+
+Ejemplo mínimo:
+```jsx
+<Chat messages={chatMessages} user={currentUserId} onSend={(msg) => sendMessage(msg)} />
+```
+
+Notas: Detecta mensajes propios comparando `message.user === user`. Ctrl/Cmd+Enter envía.
+
+---
+
+### `FileExplorer`
+Import: `import { FileExplorer } from 'ywana-core8'`
+Story: [src/widgets/explorer/Explorer.stories.jsx](src/widgets/explorer/Explorer.stories.jsx)
+
+Propósito: Explorador de ficheros completo (árbol de carpetas, vistas grid/tabla, búsqueda, selección múltiple/marcado con barra de acciones, drag&drop, paneles de edición lateral de fichero y de carpeta, agrupación, temas).
+
+Props destacadas: `files`, `folders`, `columns`, `onSelectFile`/`onOpenFile`/`onDeleteFile`/`onRenameFile`, `multiSelect`, `checkable`/`checkedFiles`/`onCheckFiles`/`checkedActions`, `searchBy`/`globalSearch`, `theme`, `groupBy`/`groupMode`, `editorComponent`/`folderEditorComponent`, `sidebarWidth`/`collapsible`/`menuActions`, `defaultFolderEditorCollapsed`.
+
+Ejemplo mínimo:
+```jsx
+<FileExplorer files={fileList} folders={folderTree} defaultFolder="images" onSelectFile={(f) => openFile(f)} />
+```
+
+**Documentación completa**: [src/widgets/explorer/Explorer.doc.md](src/widgets/explorer/Explorer.doc.md) — modelo de datos, las 50+ props, layout, recetas y errores frecuentes. Consulta ese fichero antes de integrar `FileExplorer` en profundidad; esta entrada es solo un resumen.