svelte-kit-vice/src/uix/eidos/components/README.md

# `eidos/components/`

Recipes + wrappers visuales por componente. Cada componente vive en su
**subdirectorio** con la forma canónica documentada abajo. Los `.css`
sueltos al nivel raíz son legacy de la fase "eidos = solo CSS" y se
migran progresivamente.

> **⚠️ Contrato de construcción — leer antes de escribir un recipe/wrapper.** La
> **fuente de verdad** de qué tokens/arquetipos consume un componente visual es la
> tabla **«Build contract»** de
> [`docs/guides/component-guide.md`](../../../../docs/guides/component-guide.md)
> (migrada allí el 2026-07-11, DOC-1; el audit de 2026-06-19 que la sembró queda
> como historia): elevación vía `data-depth` (bundle completo) · estado vía
> `--state-*` · radio vía factor global + `[data-shape-nest]` · foco outline
> `--focus-ring-*` (§32) · label de campo canónico · bundle `--size-*` ·
> touch-target §37 · color por token (cero hex) · densidad
> `--space-*`/`--control-height-*` · RTL lógico + `:dir(rtl)` (nunca
> `[dir='rtl']`), y el provider estampa el `dir` crudo si el recipe ramifica con
> `:dir()` — sin estampar, `:dir()` sólo ve la dirección heredada
> ([contrato de dirección](../../../../docs/canon/direction-contract.md)) · i18n
> `langs.ts` · portal-safe · composición. **Todos los ejes están LIVE** con su
> guard (R-\*, contracts, elevation-plane).

---

## Forma canónica (disciplined option C — vigente desde 2026-05-10)

Convención unificada para TODOS los componentes multi-part. Sigue la
estructura de `air` (la rama legacy, ya retirada del árbol) y la ergonomía moderna de bits-ui /
shadcn-svelte: una sola entidad mental — `<Drawer>` — con hijos
accesibles como propiedades — `<Drawer.Trigger>`, `<Drawer.Content>`, etc.

### Reglas duras

1. **Un solo punto de entrada por componente**: la default export es el
   componente root visual. Se llama igual que el componente
   (`<Drawer>`, `<Tabs>`, `<Checkbox>`, …) — **no** `<Drawer.Provider>`,
   **no** `<Drawer.Root>`.
2. **El root vive en `{name}.svelte`** — NO en `{name}-provider.svelte`.
   El nombre del fichero coincide con el nombre del componente.
3. **No exportar `Provider` públicamente**. La separación
   "Provider compound vs flat" es una invención previa que se ha
   retirado: hay UNA forma compound — el root + sus hijos atados.
4. **Los hijos siguen el naming de air / headless**: `Trigger`, `Content`,
   `Overlay`, `Title`, `Description`, `Close`, `Portal`, `Header`,
   `Footer`, `Item`, `Indicator`, `HiddenInput`, `Group`, `Label`, etc.
   No inventar nombres nuevos.
5. **`Portal` se incluye donde air lo tenía** (Dialog, Drawer, Popover,
   Tooltip — overlays portaled). Importado de
   `$soma/components/internal`.
6. **No flat con snippet slots como API principal**. La invención
   `<Drawer trigger={...} title={...} actions={...}>` está retirada —
   esconde decisiones de composición que deberían ser explícitas en
   componentes con portal/overlay/content/close.
7. **Los hijos se atan al root con asignación explícita**, no
   `Object.assign` (que en Svelte 5 puede causar issues sutiles de
   hidratación):
   ```ts
   const Drawer = DrawerComponent as DrawerNamespace;
   Drawer.Trigger = Trigger;
   Drawer.Content = Content;
   // ...
   ```

### Estructura de directorio

```
drawer/
  drawer.svelte                ← root (lo que era air's Provider)
  drawer-trigger.svelte
  drawer-overlay.svelte
  drawer-content.svelte
  drawer-handle.svelte
  drawer-title.svelte
  drawer-description.svelte
  drawer-close.svelte
  drawer-header.svelte         ← eidos-only layout shell (cuando aplique)
  drawer-footer.svelte         ← idem
  drawer.css                   ← recipe
  types.ts                     ← extiende las props públicas de Soma
  index.ts                     ← compone Drawer + hijos
```

### `{name}.svelte` — el root

Wrapper directo sobre el provider público de Soma. Setea el
contexto headless, acepta los bindables del estado (`open`, `value`,
`pressed`, etc.), añade los data-attrs visuales propios de eidos
(`data-size`, `data-variant`, `data-color`, …), y renderiza
`{@render children?.()}` para que los hijos se compongan dentro.

```svelte
<script lang="ts">
	/**
	 * Eidos `<Drawer>` — root component. Wraps the Soma
	 * to set up the component context.
	 */
	import * as Drawer from '$soma/components/drawer';
	import type { DrawerProps } from './types';

	let {
		open = $bindable(false),
		activeSnapPoint = $bindable(null),
		isDragging = $bindable(false),
		children,
		...rest
	}: DrawerProps = $props();
</script>

<Drawer.Provider {...rest} bind:open bind:activeSnapPoint bind:isDragging>
	{@render children?.()}
</Drawer.Provider>
```

> **Patrón de import interno**: `import * as Drawer from '$soma/components/drawer'`.
> Eidos no crea una fachada headless propia por componente; envuelve las
> partes públicas de Soma directamente como `<Drawer.Provider>`,
> `<Drawer.Trigger>`, etc.

#### Prohibiciones de naming interno

El namespace interno que apunta a Soma se llama igual que el componente. No se
prefija ni se renombra:

```svelte
<!-- Correcto -->
import * as Collapsible from '$soma/components/collapsible';

<Collapsible.Provider>
	<Collapsible.Trigger />
</Collapsible.Provider>
```

Formas prohibidas:

- `import * as Parts from '$soma/components/collapsible'`
- `import * as CollapsibleBase from '$soma/components/collapsible'`
- `import { Provider as SomaCollapsibleProvider } from '$soma/components/collapsible'`
- etiquetas sueltas `<Provider>`, `<Trigger>`, `<Content>` dentro de Eidos
- tipos o aliases internos `SomaXxxProvider`, `XxxBase`, `XxxRoot`

Motivo: Eidos ya declara la capa en el path. El import interno debe expresar la
entidad headless concreta de Soma, no una abstraccion inventada. Si un wrapper
Eidos necesita el provider de Soma, escribe `<Collapsible.Provider>`; si
necesita una parte, escribe `<Collapsible.Trigger>`, `<Collapsible.Content>`,
etc.

### Guardia de componentes compuestos de fecha

Incidencia 2026-05-20: DateField, DatePicker y DateRangePicker no pueden
cerrarse con wrappers Eidos si Morfo/Soma y la demo no estan cerrados primero.
Para componentes compuestos de fecha:

- Comparar antes con `morfo-runtime` (`air` / `terra`) y referencias React Aria,
  Ark UI, Bits UI y shadcn-svelte.
- Completar Morfo con partes, `data-*`, ARIA, estados, keyboard y eventos
  observables de la superficie compuesta.
- La demo no puede inventar `data-calendar-*` o `data-range-calendar-*`; si la
  receta los necesita, pertenecen a Morfo/Soma.
- Cada control visible (`granularity`, `hourCycle`, segmentos, min/max,
  `pagedNavigation`, modal/no-modal, clear) debe cambiar algo visible en el
  stage y estar reflejado en los snippets.
- Verificar visualmente popup, uno/dos meses, seleccion, deseleccion parcial,
  limites y accion de borrado antes de documentarlo como listo.

### `{name}-{part}.svelte` — hijos passthrough

Cada hijo es un wrapper delgado sobre la part del Soma. Si
añade visual-only data-attrs, los stamp aquí (ej. `data-size` en
Content). Si es passthrough puro (Trigger, Close), trivial.

```svelte
<!-- drawer-trigger.svelte -->
<script lang="ts">
	import * as Drawer from '$soma/components/drawer';
	import type { DrawerTriggerProps } from './types';

	let { children, ...rest }: DrawerTriggerProps = $props();
</script>

<Drawer.Trigger {...rest}>
	{@render children?.()}
</Drawer.Trigger>
```

### `index.ts` — compone el namespace

Asignación explícita per-property sobre el root component. **NO** usar
`Object.assign(DrawerComponent, { Trigger, ... })` — Svelte 5 puede manejar
mal la mutación bulk del component constructor durante hidratación,
causando que los hijos aparezcan y desaparezcan después de mount.

```ts
import DrawerComponent from './drawer.svelte';
import Trigger from './drawer-trigger.svelte';
import Overlay from './drawer-overlay.svelte';
import Content from './drawer-content.svelte';
import Title from './drawer-title.svelte';
import Description from './drawer-description.svelte';
import Close from './drawer-close.svelte';
import Header from './drawer-header.svelte';
import Footer from './drawer-footer.svelte';
import Handle from './drawer-handle.svelte';
import { Portal } from '$soma/components/internal';

type DrawerNamespace = typeof DrawerComponent & {
	Trigger: typeof Trigger;
	Portal: typeof Portal;
	Overlay: typeof Overlay;
	Content: typeof Content;
	Handle: typeof Handle;
	Title: typeof Title;
	Description: typeof Description;
	Close: typeof Close;
	Header: typeof Header;
	Footer: typeof Footer;
};

const Drawer = DrawerComponent as DrawerNamespace;
Drawer.Trigger = Trigger;
Drawer.Portal = Portal;
Drawer.Overlay = Overlay;
Drawer.Content = Content;
Drawer.Handle = Handle;
Drawer.Title = Title;
Drawer.Description = Description;
Drawer.Close = Close;
Drawer.Header = Header;
Drawer.Footer = Footer;

export { Drawer };
export default Drawer;

export type {
	DrawerProps,
	DrawerTriggerProps as TriggerProps,
	DrawerOverlayProps as OverlayProps,
	DrawerContentProps as ContentProps
	// … etc
} from './types';
```

### `types.ts` — passthrough + adiciones eidos

```ts
import type {
	ProviderProps,
	TriggerProps,
	ContentProps
	// …
} from '$soma/components/drawer';

export type DrawerProps = ProviderProps;
export type DrawerTriggerProps = TriggerProps;

// Eidos añade props visuales que el recipe consume vía data-attrs
export type DrawerContentProps = ContentProps & {
	size?: ResponsiveProp<DrawerSize>;
};
```

> **Sin `XxxFlatProps`, sin `XxxProviderProps as ProviderProps` aliases.**
> Hay un solo `XxxProps` (el del root) y los `XxxPartProps` per hijo.

Cuando el tipo root de Soma se importa como `ProviderProps`, se usa solo como
tipo local dentro de `types.ts`. No se exporta al consumidor con nombre
`ProviderProps` desde Eidos ni se crea un alias `SomaXxxProviderProps`.

### Tipos visuales canonicos

No se redeclaran variantes, colores ni tamanos a mano en cada componente.
La unica fuente para las props visuales compartidas es
`src/uix/eidos/lib/types.ts`:

- `Size` y `ResponsiveProp<T>` para escalas responsivas.
- `ControlVariant`, `SelectionVariant`, `ChipVariant`, `MarkerVariant`,
  `SurfaceVariant`, etc. para variantes canonicas por familia visual.
- `ColorRole` para la paleta de intents UIX (`primary`, `secondary`,
  `neutral`, `affirm`, `fulfill`, `risk`, `threat`, `loss`).

Cuando un componente necesita restringir una familia compartida, usa
`Extract<>` sobre el tipo canonico. No se crean unions locales con literales
duplicados:

```ts
import type { ColorRole, ControlVariant, Size } from '$uix/eidos/lib/types';

export type DateFieldSize = Extract<Size, 'sm' | 'md' | 'lg'>;
export type DateFieldVariant = ControlVariant;
export type DateFieldColor = ColorRole;
```

### Capas compartidas (shared layers)

Cuando VARIOS componentes necesitan la misma geometría, no se copia: se declara
una vez y se engancha por un **attr de capa** que cada consumidor estampa sobre
el elemento que ya tiene. Sin nodo envoltorio, sin anidar componentes.

Ejemplares vivos: `lib/list-surface.css` (ritmo de menú/listbox, consumido por
dropdown-menu · context-menu · menubar · select · combobox · command),
`eidos/lib/viewport-placement.css` (colocación contra el viewport, consumida por
`Affix` · `Fab` · `MenuDial`) y `lib/calendar-surface.css` (ritmo de la rejilla
de fechas y forma del anillo de evento, consumida por `Calendar` ·
`RangeCalendar` · `MonthGrid` · `YearGrid` y los wrappers de `DatePicker` /
`DateRangePicker`).

`calendar-surface` es el ejemplar HÍBRIDO y conviene leerlo antes de escribir
otra capa: las dos primeras componen primitivos del sistema, así que declaran
sus públicos en el propio fichero y no tienen entrada en `recipes/base.ts`. La
familia calendar no puede — su vocabulario son 76 claves SEMÁNTICAS que un tema
alcanza una a una por config —, así que la entrada `calendar` de la receta es la
de la FAMILIA y la capa posee sólo lo que una entrada de receta no sabe
expresar: la resolución por talla sobre un hook compartido, y la forma del
anillo.

Las reglas, y las tres primeras se aprendieron rompiéndose:

1. **La geometría engancha en el attr de CAPA, nunca en la identidad del
   componente.** `morfo-check` selecciona `[data-{kebab}]` en toda la página y
   valida cada coincidencia contra ese morfo — si un consumidor estampara la
   identidad para heredar la geometría, quedaría soldado a un contrato ajeno.
2. **Un eje = un token público + una ranura privada**, consumido como
   `var(--_x, var(--x))`. La capa posee el default; el consumidor escribe la
   ranura si ha evaluado el eje y aterriza en otro sitio. Un consumidor **no
   acuña `--{componente}-{eje}`**: sería un vocabulario paralelo para valores que
   la capa ya posee. Y si el prop escribiera el mismo nombre que la capa lee, un
   valor que referencie el token se vuelve una custom property cíclica —
   _guaranteed-invalid_, `calc()` muerto, insets a `auto`.
3. **El puente reafirma `position` si el primitivo compuesto declara uno.** La
   regla base de la capa tiene especificidad (0,1,0) y los ficheros van
   code-split, así que un `position` del primitivo al mismo peso decide por orden
   de carga. `Fab` lo debe (compone `<Button>`); `MenuDial` no (no compone nada
   en el marco).
4. **Se guarda con dos redes**, porque ninguna basta sola: el texto
   (`shared-layer-contract.test.ts`) ve lo que el navegador no puede — un
   `env()` ya sustituido —, y `npm run layer:check` ve lo que el texto no puede
   — quién gana la cascada de verdad.

### Partes Eidos-only

Algunas partes existen solo para componer la superficie visual: `Header`,
`Footer`, `Status`, `Main`, `Handle`, filas/labels planas, indicadores
decorativos o primitives `svg`. No necesitan morfo propio mientras cumplan
las cuatro reglas:

1. No crean comportamiento ni estado.
2. No son target de eventos perceptivos.
3. No poseen ARIA obligatoria ni relaciones accesibles propias.
4. Solo emiten estructura, clase/estilo passthrough o `data-*` visuales que
   el recipe consume.

Si cualquiera de esas reglas deja de cumplirse, la parte deja de ser
Eidos-only y debe subir al contrato correspondiente: primero morfo, luego Soma
si necesita runtime.

El agregador `scripts/eidos-lint-all.ts` mantiene una allowlist explícita de
estos attrs/parts visuales. El lint base sigue siendo estricto con valores
inválidos de enums morfo; la allowlist solo evita que el reporte de drift se
llene de partes visuales intencionales.

`src/uix/eidos/component-api-contract.test.ts` protege la forma pública del
barrel: sin `Object.assign`, sin `Provider` público, root en
`{component}.svelte` y miembros del `XxxNamespace` sincronizados con sus
asignaciones explícitas (`Drawer.Trigger = Trigger`, etc.).

La guardia `src/uix/eidos/component-visual-attrs.test.ts` fija el cableado
mínimo entre wrapper y recipe: si un wrapper visual declara una prop que se
consume como `data-*` (`size`, `variant`, `color`, `position`, `columns`,
etc.), el fichero debe seguir estampando ese atributo. Esto no añade
comportamiento a Eidos; solo evita que la capa visual trague props en silencio.

### Uso del consumidor

```svelte
<script lang="ts">
	import { Drawer } from '$uix/eidos/components/drawer';
	let open = $state(false);
</script>

<Drawer bind:open variant="overlay" direction="right">
	<Drawer.Trigger>Open</Drawer.Trigger>
	<Drawer.Portal>
		<Drawer.Overlay />
		<Drawer.Content>
			<Drawer.Header>
				<Drawer.Title>Title</Drawer.Title>
				<Drawer.Description>Subtitle</Drawer.Description>
			</Drawer.Header>
			<p>body</p>
			<Drawer.Footer>
				<Drawer.Close>Close</Drawer.Close>
			</Drawer.Footer>
		</Drawer.Content>
	</Drawer.Portal>
</Drawer>
```

### Componentes single-part (toggle, icon)

Sin hijos compound. El default export ES el componente entero. Sin
namespace, sin asignación de propiedades, sin `Provider` alias.

```ts
// toggle/index.ts
export { default } from './toggle.svelte';
export type { ToggleProps, ToggleVariant, ToggleSize } from './types';
```

```svelte
import Toggle from '$uix/eidos/components/toggle';
<Toggle bind:pressed variant="solid">Bold</Toggle>
```

### Partes visuales por defecto

Algunos componentes multi-part necesitan una parte visual minima para no
renderizar una superficie rota. `Switch` es el caso canonico: el root sigue
exponiendo `Switch.Thumb`, pero si el consumidor no aporta children, `<Switch />`
monta un thumb visual por defecto. Esto no crea una API flat ni esconde el
contrato de Soma; solo evita que el uso minimo renderice un track sin indicador.

---

## Toast — caso especial (dos roots independientes)

`Toast` tiene dos roots públicos que NO se anidan:

- `<Toast>` — manual compound (Provider+Viewport+Item iteración del
  consumer). Children attached: Viewport, Item, Status, Main, Title,
  Description, Action, Close.
- `<Toaster />` — imperative auto-mount. Renderiza Provider+Viewport+
  Item-loop con un template default. Pasas `toaster` de
  `createToaster()`. Export separado, no `Toast.Toaster` porque es un
  root competidor, no un hijo.

```ts
import { Toast, Toaster, createToaster } from '$uix/eidos/components/toast';

const t = createToaster();

// Imperative
<Toaster toaster={t} />

// Manual
<Toast toaster={t}>
  <Toast.Viewport>
    {#each t.toasts as toast}
      <Toast.Item {toast}>
        <Toast.Title>{toast.title}</Toast.Title>
      </Toast.Item>
    {/each}
  </Toast.Viewport>
</Toast>
```

---

## Convenciones de naming de tokens CSS

Los tokens CSS llevan el nombre del **componente**, no de la **capa**.
Sin prefijos de capa — ni `--eidos-`, ni `--air-`, ni `--terra-`,
ni `--soma-`.

| Forma              | Uso                                                   | Ejemplo                                     |
| ------------------ | ----------------------------------------------------- | ------------------------------------------- |
| `--{component}-…`  | tokens públicos (sobreescribibles por el consumer)    | `--dialog-content-bg`, `--toggle-height-md` |
| `--_{component}-…` | tokens internos del recipe (no parte del API público) | `--_tabs-trigger-height`, `--_toggle-bg`    |

Los `[data-{component}]` y `[data-{component}-{part}]` selectors son la
única vía pública para que el recipe se acople al runtime — toda
información cross-layer pasa por data-attrs declarados en el morfo.
Cada `--{component}-*` consumido por CSS debe salir de `EidosConfig.recipes`;
si un alias publico queda sin consumidor real, el test
`src/uix/eidos/recipe-css-contract.test.ts` falla.

---

## Comparativa obligatoria por componente

Ningun componente Eidos se declara cerrado solo por envolver Soma. Antes de
implementar o revisar un componente:

1. Leer Air en la rama anterior (`morfo-runtime:src/uix/air/components/{name}`)
   cuando exista. Air es la primera baseline visual.
2. Leer Soma/Morfo actuales para separar comportamiento, ARIA, estado,
   traducciones y data-attrs de la superficie visual Eidos.
3. Auditar Morfo/Sema. El morfo no se considera correcto solo porque compile:
   - Clasificar el componente como pasivo, interactivo o mixto.
   - Justificar cualquier `0 events` de forma explicita.
   - Para cada accion real de usuario revisar `family`, `verb`, `sequence`,
     `intent`, `target`, `prewrite` y `commit`.
   - Verificar que Soma dispara esas ocurrencias con `runtime.trigger(...)`.
   - Evitar eventos de alta frecuencia para cambios continuos; normalmente se
     modelan inicio/drag confirmado/commit, no cada frame.
4. Comparar contra referentes externos relevantes: Radix/Radix Themes, Ark UI,
   Bits UI, shadcn-svelte y React Aria cuando aplique.
5. Crear/actualizar `components/{name}/README.md` con tabla de funcionalidades,
   tabla Morfo/Sema, gaps y decisiones. Cada `⚠️` / `❌` debe acabar en una
   decision explicita: implementar ahora, diferir a Morfo/Soma, diferir a v2 o
   descartar por no pertenecer a Eidos.
6. Si hay demo en `web/routes/uix/components/{name}`, sus snippets forman parte
   de la arquitectura del componente: deben reproducir el mismo contrato visible
   que el preview. En componentes schema-driven (`form`, `auto-fields`,
   date/time con formatos, etc.) no se permite un schema reducido que omita
   campos visibles, validators o defaults reales.
7. Solo despues tocar wrapper, recipe o tokens.

El objetivo no es copiar APIs, sino que Eidos no quede por debajo de Air ni de
los referentes en funcionalidades reales. Si una capacidad pertenece a Soma, la
tabla debe decirlo; si es visual, Eidos debe cubrirla o justificar el gap.

### Reglas especificas para demos de formularios

- La validacion en tiempo real se modela como
  `validationBehaviour: 'onChange'`.
- Si una demo arranca en `onChange`, los defaults iniciales deben ser validos
  salvo que el README y la UI digan explicitamente que se esta mostrando un
  formulario inicialmente invalido.
- El snippet de Soma y el snippet de Eidos deben declarar los mismos campos
  visibles que el preview: imports SIUM, schema, defaults, `Form + Field` y
  `Form.AutoFields`. No se admiten snippets que omiten `age`, `role`,
  campos de fecha, arrays u otros datos que el preview valida.
- `Form.AutoFields` es renderer reflectivo de SIUM. Si necesita comportamiento
  nuevo, se cambia Soma / `$libs/forms` / Morfo antes que Eidos.

---

## Forma legacy (CSS-only, retired)

Hubo una fase anterior cuando eidos sólo emitía CSS (`accordion.css`,
`dialog.css`, etc., al nivel raíz de `components/`). Todos los
componentes han sido migrados a la forma canónica del subdirectorio.
Si encuentras un `.css` suelto, es un descuido — debe vivir dentro de
su subdirectorio.

---

## Inventario

El inventario vivo de wrappers es el árbol de subdirectorios de
`components/` + `npm run component:audit`. La tabla de estado de la
migración 2026-05 (completada) se conserva en
[`docs/process/handoffs-2026-05.md`](../../../../docs/process/handoffs-2026-05.md).