svelte-kit-vice/src/uix/soma/SOMA_ARCHITECTURE.md

# Soma Architecture

Documento de referencia arquitectonica para `src/uix/soma`.

`soma` es la capa de primitives headless del sistema UIX. Implementa
behavior, accesibilidad y composicion de partes; la presentacion visual
es responsabilidad de eidos. Cada componente se describe primero como
**morfo** (contrato declarativo) y soma lo materializa mediante clases
concretas de estado que registran sus partes en `SomaRuntime`.

## 1. Proposito

`soma` existe para dar una base comun sobre la que construir interfaces complejas sin repetir la misma logica de:

- contexto compartido
- control de foco
- teclado y puntero
- `aria-*`
- `data-*`
- sincronizacion de estado
- integracion con servicios transversales
- animaciones de entrada/salida
- posicionamiento flotante

Su objetivo no es ser una capa visual ni de producto. `soma` define primitives reutilizables y predecibles; la capa visual decide el look and feel.

## 2. Arquitectura de capas

```
soma   → headless: behavior, accesibilidad, data-* contracts, context, servicios
eidos  → visual: tokens, CSS, temas, recipes, reacciones a data-event-*
events → percepcion: sound/haptic/hold y dispatch de ocurrencias semanticas
app    → producto: composicion final, contenido, logica de negocio
```

Cada capa tiene responsabilidades estrictas:

### soma aporta

- comportamiento (keyboard, focus, dismiss, scroll lock)
- accesibilidad (ARIA, roles, live regions)
- contratos `data-*` estables y validados
- contexto y composicion de partes
- servicios de runtime (`langs`, `format`, `logger`)
- sistema de animaciones (presence, data-starting/ending-style, onComplete)
- posicionamiento flotante (@floating-ui)

### La capa visual aporta

- apariencia (tokens, colores, tipografia, spacing)
- tono visual (temas light/dark, variantes)
- decisiones de diseno opinionated (sizes, recipes)
- motion CSS y reacciones visuales a `data-event-*`
- responsive design

### La capa visual NUNCA

- importa state classes internas de soma
- depende de estructura DOM incidental
- accede a propiedades privadas
- duplica behavior que soma ya resuelve
- usa `data-*` fuera de los contratos publicados

La frontera es los `data-*` attrs y las CSS variables que soma expone.

## 3. Principios de diseno

### 3.1 El desarrollador no necesita conocer los internos

Los layers, el sistema reactivo, el floating engine — son implementacion interna. El desarrollador de componentes interactua con:

- clases concretas de estado + `SomaRuntime`
- `Soma` class para servicios
- Barrel imports jerárquicos (`import { Dialog } from '$soma/components'`)

### 3.2 Un patron, no tres

Todo componente sigue el mismo patron:

1. State class concreta registra sus partes con `SomaRuntime.part(...)`
2. Wrapper `.svelte` fino convierte props → Active/State
3. Props derivados via `$derived.by` + `runtimePart.assert`
4. Contexto para comunicacion padre-hijo

Los roots sin DOM usan `ProviderOpts` (ref opcional), las partes con DOM usan
`WithRefOpts`. Las unicas excepciones son partes declarativas que pueden vivir
fuera de su provider (`AnnounceRegion`, `FeedSentinel`): si encuentran un
provider reutilizan su `runtime`; si no, crean un runtime propio desde el
`Soma` del scope actual.

### 3.3 Layers como behaviors, no como wrappers

Los layers se instancian en el constructor del Provider y exponen `.props` para merge. No hay nesting de componentes wrapper en template.

```ts
// Correcto: behaviors integrados
readonly focusScope = FocusScope.use({...});
readonly dismissal = Dismissal.use({...});
readonly props = $derived.by(() => this.runtimePart.assert({
    ...this.runtimePart.props,
    ...this.focusScope.props,
    ...this.dismissal.props,
}));
```

```svelte
<!-- Incorrecto: nesting de wrappers (patron terra) -->
<ScrollLock>
	<FocusScope>
		<DismissibleLayer>
			{content}
		</DismissibleLayer>
	</FocusScope>
</ScrollLock>
```

### 3.4 Soma es una clase, no una configuracion

`Soma` es la identidad runtime del framework. No es un archivo de configuracion — es el objeto raiz que provee servicios via context.

```ts
// En un Provider:
readonly soma = Soma.require();
const dir = this.soma.prefs.getDir();
```

### 3.5 Los data-\* son contrato publico

Los `data-*` attrs son la frontera entre soma y la capa visual. Cambiarlos es breaking change.

Convencion (obligatoria, sin excepciones):

- provider: `data-{component}` (no `data-{component}-provider`, **no `data-soma-*`**)
- parte: `data-{component}-{part}`
- estado: `data-state`, `data-disabled`, `data-side`, `data-align`, `data-orientation`
- animacion: `data-starting-style`, `data-ending-style`
- nesting: `data-nested`, `data-nested-open`

Los nombres los emite el compilador de morfo que consume `SomaRuntime`.
`createAttrs(morfo)` queda como helper tipado para `querySelector` y tooling,
no como sistema de registro ni escritura DOM. Cualquier selector CSS, cadena
en README o snippet debe coincidir exactamente con esos nombres generados. El
validador de contratos (`assertContract`) solo verifica valores enumerados, no
nombres ni presencia — la consistencia de nombres es responsabilidad del autor
del componente (checklist item 27).

### 3.6 La accesibilidad base no se delega

soma resuelve ARIA por defecto. El consumidor no necesita añadir `role`, `aria-modal`, `aria-expanded`, `aria-controls`, etc. — el Provider los genera.

Texto funcional se resuelve via `langs.ts()` con idlangref. El catalogo propio del componente vive en `morfo.translations` y se referencia con `v.translationRef(...)`; texto compartido como close/cancel/save vive en `common.*` y se referencia con `v.commonRef(...)` o un idlangref absoluto. `langs.ts` por componente queda como comodidad opcional para constantes imperativas, no como catalogo canonico.

### 3.7 DOM global via ActiveDom

Soma usa el `ActiveDom` del scope para escrituras gestionadas por UIX,
listeners de `document/window`, queries globales, foco imperativo y scroll de
ventana. No existe fachada `soma/events`: `dom.listen(...)` es la superficie
canonica para registrar listeners con cleanup.

Las lecturas locales de un elemento propio (`contains`, `closest`,
`getBoundingClientRect`, `clientWidth`, `scrollTop`) no se envuelven en
`ActiveDom`; son parte del comportamiento local del componente.

### 3.8 Props documentadas obligatoriamente

Todas las props de todos los componentes llevan JSDoc en `types.ts`. Cada prop: descripcion, `@default`, notas de comportamiento.

### 3.9 Comparacion con referencias

Cada componente se compara con ark-ui, bits-ui y radix-ui antes de implementar. Se documentan las props que otros tienen y soma no, con justificacion.

## 3.bis Arquitectura cerrada (post-2026-04-25)

El reparto de responsabilidades entre Morfo, Soma, Sema y ADom esta cerrado en
seis piezas con responsabilidades disjuntas:

```
Morfo          declara
SomaRuntime   transcribe (vive en soma/)
Provider       aporta sources, targets y handlers
Effects        sincronizan attrs derivados
EngineSemantic despacha senales a canales perceptivos
VisualChannel  materializa la senal en el DOM (data-event*, hold, cleanup)
ADom           aplica mutaciones DOM (commit estructural)
```

### SomaRuntime — la pieza nueva

`SomaRuntime` es la pieza que faltaba entre `Morfo` (declaracion) y
`Provider` (ejecucion). Lee el morfo y produce el comportamiento.

Una instancia por componente:

```ts
readonly soma = Soma.require();
readonly runtime = this.soma.runtime(morfo, {
	states: { open: () => this.opts.open.current },
	props: { disabled: () => this.opts.disabled.current },
	parts: { content: () => this.contentId.current },
	events: {
		open: () => {
			this.opts.open.current = true;
		},
		'close-cancel': () => {
			this.opts.open.current = false;
		}
	}
});
```

API V1:

- `runtime.part(part, opts)` — unica API publica para registrar una parte.
  Devuelve el handle (`props`, `resolveProps`, `assert`) y, con
  `syncAttrs: true`, sincroniza attrs derivados por morfo via `dom.apply`.
- `runtime.partProps(part)` — devuelve `{ id, ref, marker, data-archetype? }`. Solo identidad estatica (el `data-archetype` es classification cross-component, nunca cambia).
- `runtime.keydown(part, event)` — dispatch de teclas declaradas en `morfo.keyboard`.
- `runtime.trigger(eventName)` — orquesta la secuencia perceptiva + state.

### Provider en el modelo nuevo

El provider deja de tener helpers locales de resolucion de morfo. Solo
aporta:

- getters reactivos para `states`, `props`, `parts`
- handlers sincronos para los `events`
- glue de layers ortogonales (Presence, Dismissal, ScrollLock)

Cada part-provider conserva el handle devuelto por `runtime.part(...)`:

```ts
readonly runtimePart = runtime.part('trigger', {
	id: opts.id,
	ref: opts.ref,
	owner: this,
	syncAttrs: true
});

readonly props = $derived.by(() => this.runtimePart.props);
```

### Tres operaciones que cubren todos los escenarios

```ts
// Cambio estructural sin senal
provider.commitState(change);

// Cambio estructural con senal
provider.commitState(change, event);

// Senal sin cambio estructural
provider.emitEvent(event);
```

Internamente:

```ts
async commitState(change, event?) {
  if (event) await this.soma.events?.emit(event);
  this.soma.dom.apply(change);
}

emitEvent(event) {
  void this.soma.events?.emit(event);
}
```

### La secuencia de `runtime.trigger(eventName)`

```
1. prewrite imperativo (transient markers como data-last-action)
2. await events.emit(event)
3. handler sincrono del provider muta state
4. effects derivan y aplican attrs estructurales (data-state, aria-*)
```

Los effects del runtime escuchan los sources reactivos y reaplican attrs cada
vez que el estado cambia. ADom es el unico escritor de attrs mutables.

### Reglas operativas

- `partProps(part)` solo emite identidad estatica. Lo mutable lo escribe ADom.
- Lo que `dom.apply` escribe, Svelte no lo renderiza desde `partProps`.
- Event handlers son sincronos. Async va antes del trigger.
- Guards (`if (disabled) return`) van en el call-site, no dentro del handler.
- `events`/`VisualChannel` pueden usar `ActiveDom` a traves del projector
  inyectado; `ActiveDom` no conoce `events`.
- `morfo.events.commits` es descriptivo, no ejecutable. El smoke valida.

### Pilotaje (orden incremental)

1. **Toggle** — primer caso, solo `partProps`.
2. **Collapsible** — anade `keydown`.
3. **Toast** — primer test real de `trigger()` con `intent`.
4. **Dialog** — al final, cuando layers + portal ya esten validados.

Ver tambien:

- [src/uix/morfo/README.md](../morfo/README.md) — declaracion, archetypes, regla 2-de-3
- [src/uix/sema/README.md](../sema/README.md) — contrato de `emit`, vocabulario de verbs
- [src/uix/adom/README.md](../adom/README.md) — `dom.apply`
- [src/uix/eidos/README.md](../eidos/README.md) — qué consume eidos del DOM
- [src/uix/README.md](../README.md) §2.bis — vista cross-layer

### Cross-layer hooks que soma emite por la regla 2-de-3

Soma escribe al DOM no solo lo que necesita; escribe también lo que sema y
eidos van a consumir. La regla "2-de-3" justifica qué entra al morfo y por
tanto qué emite el runtime:

- **`data-archetype`** — emitido por `partProps` cuando la parte declara
  archetype. Eidos lo usa para selectores transversales
  (`[data-archetype=trigger] { ... }`); sema puede asociar verbs por
  archetype.
- **`data-event*`** — emitido por `events.emit` (a través del VisualChannel)
  durante un hold configurable (240ms emerge/commit/handle, 600ms alert/sustain
  por defecto). Eidos lo usa para tintar transiciones de eventos
  (`[data-event^=dismiss]`).
- **`data-{component}` / `data-{component}-{part}`** — los markers
  estructurales clásicos. Eidos los usa para selectores per-componente.

## 4. Modelo de componente

La forma base de soma es `Componente.Parte`:

```ts
import { Dialog } from '$soma/components';

Dialog.Provider; // root — crea contexto
Dialog.Trigger; // accion — abre/cierra
Dialog.Content; // contenido — layers integrados
Dialog.Overlay; // fondo — presence
Dialog.Title; // metadata ARIA
Dialog.Description; // metadata ARIA
Dialog.Close; // accion — cierra
```

### Provider (root)

Crea el estado central, lo registra en context, gestiona presence para content y overlay. Puede o no renderizar DOM:

- **Con DOM** (Collapsible, Accordion): usa `WithRefOpts`, renderiza `<div>`
- **Sin DOM** (Dialog, Popover): usa `ProviderOpts`, solo renderiza children

### Subcomponentes

Leen estado del root via `.require()`. No reimplementan logica — derivan props, ARIA, data-\*, events del estado del padre.

### Portal

Componente interno (`components/internal/portal.svelte`). Renderiza hijos en otro nodo DOM. El contexto de Svelte se preserva.

### Picker composition (shared state across providers)

Pickers (`DatePicker`, `DateRangePicker`, `TimePicker`, y futuros `TimeRangePicker`) no reimplementan Popover / Field / Calendar — los **componen** con estado compartido. El root wrapper crea tres (o más) Providers que apuntan a los mismos `writableActive` refs:

```ts
// Root wrapper
const sharedValue = writableActive(() => value, (v) => (value = v));
const sharedPlaceholder = writableActive(() => placeholder, (v) => (placeholder = v));
const sharedOpen = writableActive(() => open, (v) => (open = v));

{Name}PickerProvider.create({ value: sharedValue, placeholder: sharedPlaceholder, open: sharedOpen, ...config });
PopoverProvider.create({ open: sharedOpen, ... });
{Base}FieldProvider.create({ value: sharedValue, placeholder: sharedPlaceholder, ...config });
// Calendar/RangeCalendar/slider providers are created in their own wrapper (DatePicker.Calendar, TimePicker.HourSlider, …)
```

El picker expone **solo** wrappers únicos para `Provider`, `Trigger`, y el puente al calendario/slider. Los demás exports re-exportan desde los componentes compuestos — sus `data-*` nativos (`data-popover-*`, `data-date-field-*`, `data-calendar-*`, `data-slider-*`) siguen siendo la API de estilo autoritativa. El picker sólo añade atributos de identidad (`data-{picker}-trigger`, `data-{picker}-calendar`) en sus propios wrappers.

**Auto-close / auto-anchor**: el PickerProvider expone `handleSelect()` que el wrapper del calendario llama al completarse una selección. Los range pickers re-anclan `placeholder` para que el mes final caiga en la columna más a la derecha visible, evitando mostrar al usuario un mes que no contiene su selección.

Ver A27 en `COMPONENT_GUIDE.md` para el checklist completo.

## 5. Runtime parts

```ts
readonly soma = Soma.require();
readonly runtime = this.soma.runtime(accordionMorfo, {});
const runtimePart = this.runtime.part('provider', {
	id: opts.id,
	ref: opts.ref,
	owner: this,
	context: AccordionProvider.ctx
});

readonly props = $derived.by(() =>
    runtimePart.assert({
        ...runtimePart.props,
        'data-state': this.state
    })
);
```

`SomaRuntime.part()` centraliza lo mecanico de cada parte:

```ts
interface SomaRuntimePart {
	readonly attachment: RefAttachment | undefined;
	readonly props: Record<string, unknown>;
	resolveProps(bindings?): Record<string, unknown>;
	assert<P extends Record<string, unknown>>(props: P): P;
}
```

`syncAttrs: true` activa la escritura imperativa por `uix.dom` para partes
cuyos sources ya estan declarados en el runtime. Si un provider sigue
componiendo attrs en render props, no activa `syncAttrs`.

Dos interfaces de opts:

- `ProviderOpts` — `{ id: Active<string>; ref?: State<HTMLElement | null> }` — para roots sin DOM
- `WithRefOpts` — `{ id: Active<string>; ref: State<HTMLElement | null> }` — para parts con DOM

## 6. Layers

`layers/` contiene solo clases de comportamiento (`.svelte.ts`). Son infraestructura consumida por Providers, nunca directamente por el consumidor.

### Inventario

| Layer             | API                                                               | Responsabilidad                                                              |
| ----------------- | ----------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| `Presence`        | `new Presence(opts)`                                              | Mount/unmount con animaciones. `isPresent`, `transitionAttrs`, `onComplete`. |
| `FocusScope`      | `FocusScope.use(opts)`                                            | Focus trap, loop, auto-focus, restore. Singleton manager con stack.          |
| `Dismissal`       | `Dismissal.use(opts)`                                             | Escape + click-outside. Registry global. Behaviors: close, ignore, defer.    |
| `TextSelection`   | `TextSelection.use(opts)`                                         | Previene selection overflow durante drag.                                    |
| `ScrollLock`      | `new ScrollLock(initial?, delay?)`                                | Body scroll lock con refcount. Soporta delay para animaciones.               |
| `ResizeObserver$` | `new ResizeObserver$(getter, cb)`                                 | ResizeObserver con lifecycle Svelte.                                         |
| `Floating*`       | `FloatingProvider.create()`, `FloatingContent.create(opts)`, etc. | Posicionamiento relativo a anchor via @floating-ui.                          |
| `Gesture.base`    | `Gesture.base(opts)`                                              | Pointer tracking + axis lock + velocity.                                     |
| `Gesture.drag`    | `Gesture.drag(opts)`                                              | Base + progress + snap points + dismiss.                                     |
| `Gesture.resize`  | `Gesture.resize(opts)`                                            | Base + delta + min/max constraints.                                          |
| `SafePolygon`     | `new SafePolygon(opts)`                                           | Hover-gap corridor between trigger↔content.                                  |

`layers/floating/placement.ts` es la fuente unica para `Side`, `Align`,
`Boundary`, `SIDE_OPTIONS` y `ALIGN_OPTIONS`. `floating/types.ts` consume esa
fuente y no importa del runtime `floating.svelte.ts`, evitando ciclos entre
tipos y clases.

### Cobertura P0 actual

Los tests por componente estan creciendo desde las piezas de mayor riesgo. A
2026-05-15 existen tests directos para:

- `$libs/datagrid/table-core.svelte.test.ts` — motor de data grid.
- `$libs/forms/form-core.svelte.test.ts` — motor de formularios + Standard Schema.
- `dialog/dialog-provider.svelte.test.ts` — open/close, fallback target y
  eventos morfo.
- `drawer/drawer-provider.svelte.test.ts` — direccion logica, dismiss y modo
  persistent.
- `command/command-provider.svelte.test.ts` — filtro, visibilidad, navegación
  y selección.
- `combobox/combobox-provider.svelte.test.ts` — selección, `inputValue` y
  navegación sin items disabled.
- `select/select-provider.svelte.test.ts` — selección single/multiple y
  navegación sin items disabled.
- `popover/popover-provider.svelte.test.ts` — toggle, hover timers y señales
  runtime.
- `toast/toaster.svelte.test.ts` — overflow, dismiss/remove y promesas.
- `calendar/calendar-provider.svelte.test.ts` — placeholder, meses, selección
  y flags.
- `range-calendar/range-calendar-provider.svelte.test.ts` — placeholder,
  orden de endpoints y limites min/max.
- `date-field/date-field-provider.svelte.test.ts` — helpers UI de segmentos,
  lectura DOM, navegación por `ActiveDom`, validación y commit segmentado.
- `date-picker/date-picker-provider.svelte.test.ts` — registro runtime y
  cierre controlado por `closeOnDateSelect`.
- `date-range-picker/date-range-picker-provider.svelte.test.ts` — registro
  runtime y cierre controlado por `closeOnRangeSelect`.
- `time-picker/time-picker-provider.svelte.test.ts` — registro runtime,
  valores de placeholder y escritura de sliders al valor compartido.
- `time-range-picker/time-range-picker-provider.svelte.test.ts` — valores por
  endpoint, escritura de sliders y cierre al completar rango.
- `time-range-field/time-range-field-provider.svelte.test.ts` — validación de
  orden/min/max, validación custom y foco de label via `ActiveDom`.
- `time-field/time-field-provider.svelte.test.ts` — validación, sincronización
  de segmentos 12h y commit solo cuando los segmentos renderizados estan
  completos.
- `date-range-field/date-range-field-provider.svelte.test.ts` — validación de
  orden/min/max, validación custom y foco de label via `ActiveDom`.
- `virtual-list/virtual-list-provider.svelte.test.ts` — cálculo de ventana,
  `scrollToIndex` y compensación anti-jump via `ActiveDom`.
- `virtual-grid/virtual-grid-provider.svelte.test.ts` — cálculo de ventana 2D
  y `scrollToCell` via `ActiveDom`.
- `number-field/number-field-provider.svelte.test.ts` — parsing localizable,
  teclado spinbutton, triggers, props ARIA y scrubber.
- `file-upload/file-upload-provider.svelte.test.ts` — aceptación/rechazo,
  dropzone, input oculto, items, progress y acciones remove/clear.
- `color-field/color-field-provider.svelte.test.ts` — commit por segmentos,
  edición hex por teclado, selector de formato, input oculto y foco via
  `ActiveDom`.
- `color-picker/color-picker-provider.svelte.test.ts` — helpers de canales,
  trigger/value/hidden, area 2D, slider de canal y swatches.
- `navigation-menu/navigation-menu-provider.svelte.test.ts` — timers UIX,
  enlace item/trigger/content, foco por teclado y props de list/link.
- `tree-grid/tree-grid-provider.svelte.test.ts` — expansión, selección/rango,
  filas visibles, navegación y props de row/cell/header/expand trigger.
- `dropdown-menu/dropdown-menu-provider.svelte.test.ts` — trigger open/close,
  scoping de items, selección, checkbox/radio groups, submenu y group/separator.
- `context-menu/context-menu-provider.svelte.test.ts` — apertura por
  `contextmenu`, anchor virtual, scoping de items, selección, checkbox/radio,
  submenu y group/separator.
- `menubar/menubar-provider.svelte.test.ts` — coordinación de menús hermanos,
  hover-follow, navegación horizontal y cambio de menú desde content.
- `listbox/listbox-provider.svelte.test.ts` — props ARIA root, selección,
  navegación, typeahead, indicador de item y grupos.
- `tree-view/tree-view-provider.svelte.test.ts` — expansión/selección,
  navegación root, typeahead, props de ramas/hojas y partes auxiliares.
- `accordion/accordion-provider.svelte.test.ts` — modos single/multiple,
  eventos `open/close` por item, navegación de triggers y header/content.
- `checkbox/checkbox-provider.svelte.test.ts` — commits check/uncheck,
  indeterminate, hidden input y sincronización con `CheckboxGroup`.
- `radio-group/radio-group-provider.svelte.test.ts` — roving tabindex,
  selección síncrona, navegación con auto-select, hidden input y guardas.
- `switch/switch-provider.svelte.test.ts` — `commit-toggle` runtime,
  keyboard, hidden input, integración con `FieldProvider` y thumb.
- `toggle/toggle-provider.svelte.test.ts` — `commit-toggle` runtime, attrs DOM
  via `ActiveDom`, integración con `FieldProvider` y guardas.
- `toggle-group/toggle-group-provider.svelte.test.ts` — modos single/multiple,
  roving tabindex y navegación de items saltando disabled.
- `tabs/tabs-provider.svelte.test.ts` — registros trigger/content, activacion
  automatic/manual, navegacion roving, fallback tab stop y partes auxiliares.
- `slider/slider-provider.svelte.test.ts` — contrato provider/range/thumb/tick,
  snapping/clamping, drag pointer confirmado y teclado de thumb.
- `progress/progress-provider.svelte.test.ts` y
  `meter/meter-provider.svelte.test.ts` — `data-value/data-min/data-max`
  emitidos por morfo/runtime, estados derivados e indicador sincronizado.
- `collapsible/collapsible-provider.svelte.test.ts` — refs cruzadas
  trigger/content, eventos `expand/collapse` y guardas disabled.

Pendiente: seguir ampliando cobertura por el resto del catalogo Soma, ya por
componentes de riesgo medio y familias menos centrales. `table-core`,
`form-core` y el scorer de Command ya no viven dentro de Soma: se consumen
desde `$libs/datagrid`, `$libs/forms` y `$libs/strings`.

### Convencion

- `.use(opts)` → lifecycle auto-gestionado (watch/$effect internos). Constructor privado.
- `new X(opts)` → lifecycle manual. El consumidor controla.
- `.props` → objeto para spread en el Provider.

### Animaciones (Presence)

Lifecycle:

```
OPENING:
  open=true → shouldRender=true + data-starting-style
  → next rAF: data-starting-style removed (triggers CSS transition)
  → getAnimations().finished → onComplete(true)

CLOSING:
  open=false → data-ending-style (element stays in DOM!)
  → getAnimations().finished
  → shouldRender=false + data-ending-style removed → onComplete(false)
```

- `forceMount` mantiene el elemento en DOM siempre (para transiciones CSS)
- `onComplete` usa `getAnimations()` API, no eventos `transitionend`/`animationend`
- Run ID cancellation previene callbacks stale en toggle rapido

## 7. Soma class (component runtime scope)

Soma reads `ActiveUix` from context and exposes services to components.
Components import from `$soma`, never from `$active-app`. Nestable: child
`<Soma portalTo="#modals">` overrides parent.

```ts
class Soma {
	static create(opts?: SomaOptions): Soma; // factory + context set
	static get(): Soma | undefined; // safe read
	static require(): Soma; // throws if not found

	readonly uix: ActiveUix;
	readonly portalTo: string | HTMLElement | undefined;

	// Service accessors (delegate to ActiveUix)
	get langs(): ActiveLangs;
	get nums(): ActiveNumbers | undefined;
	get money(): ActiveCurrency | undefined;
	get dates(): ActiveDates | undefined;
	get units(): ActiveUnits | undefined;
	get prefs(): ActiveUixPrefsView;
	get logger(): EngineLogger;
}
```

### Service access from components

Components access services through Soma, never through App directly:

```ts
const soma = Soma.get();
soma?.langs.ts('#?common.buttons.close|Close'); // translation via idlangref
soma?.prefs.getDir(); // effective direction from uix.prefs.direction
soma?.money?.format(1099); // currency formatting
soma?.dates?.getDateOrder(); // DMY / MDY / YMD
soma?.dates?.getHourCycle(); // 12 | 24 (numeric — not '12h' / '24h')
soma?.portalTo; // portal target
```

### Date / time types and formatting

Soma imports date-related symbols from `$libs/days`, the canonical date library. Components **never** import from `$lib/util/dates` (legacy) or `@internationalized/date` directly. There is no Soma re-export façade for the date domain.

- Value types: `CalendarDate`, `CalendarDateTime`, `Time`, `ZonedDateTime`
- Types: `DateValue`, `TimeValue`, `DateRange`, `DateMatcher`, `Month`, `WeekStartsOn`, `HourCycle`, `TimeGranularity`, `DateOrder`, `Granularity`, `SegmentPart`, `EditableTimeSegmentPart`, `TimeSegmentObj`, `SegmentValueObj`, `DayPeriod`, …
- Queries: `isSameDay`, `hasTime`, `isZonedDateTime`, `isTimeBefore`, `isTimeAfter`, `today`, `now`, `startOfMonth`, `endOfMonth`, `getLastFirstDayOfWeek`, `getNextLastDayOfWeek`, …
- Operations: `dateValueToDate`, `convertTimeValueToDateValue`, `convertTimeValueToTime`, `toCalendarDate`, `toZoned`, …
- Parsing: `parseDate`, `parseDateTime`, `parseTime`
- Formatting: `DateFormatter`, `getCachedDateFormat`, `getPlaceholder`, `getDefaultDate`, `getDefaultTime`, `inferGranularity`, `inferTimeGranularity`, `getDefaultHourCycle`, `resolveDateOrder(locale)`, `resolveHourCycle(locale)`
- **Segments (dias/segments.ts)**: constants (`DATE_SEGMENT_PARTS`, `EDITABLE_TIME_SEGMENT_PARTS`, …), type guards (`isDateSegmentPart`, `isEditableTimeSegmentPart`, `isDateAndTimeSegmentObj`, …), pure helpers (`initializeSegmentValues`, `initializeTimeSegmentValues`, `getValueFromSegments`, `getTimeValueFromSegments`, `areAllSegmentsFilled`, `createSegmentContent`, `createTimeSegmentContent`, `getOptsByGranularity`, `getOptsByTimeGranularity`).

`HourCycle` is canonically the numeric form `12 | 24` across the whole framework, matching `Intl.DateTimeFormat`'s `hour12` resolved option. String forms like `'12h'`/`'24h'` are legacy and must not appear in new code.

**`soma/datetime/` holds only UI-level helpers** (screen-reader announcer, DOM segment navigation, `SegmentState` shape with `lastKeyZero`/`hasLeftFocus`/`updating`, `isAcceptableSegmentKey` using KEYS, description-element DOM writers). It must not re-export `$libs/days` symbols — consumers import from `$libs/days` directly. Extending `$libs/days` is the default for new date/time helpers; adding to `soma/datetime/` is only correct when the helper is genuinely UI-specific.

### Static method convention (project-wide)

All classes that use Svelte context follow the same pattern:

| Method           | Returns                 | Use when                          |
| ---------------- | ----------------------- | --------------------------------- |
| `X.create(opts)` | instance                | Creating + registering in context |
| `X.get()`        | instance or `undefined` | Parent/context is optional        |
| `X.require()`    | instance (throws)       | Parent/context is required        |

This applies to `App`, `Soma`, and all state classes that use context. No
standalone functions. No `from()`. No `ctx` exposed.

### Texto funcional

Las traducciones propias del componente se declaran en el morfo:

```ts
export const drawerMorfo = {
	name: 'Drawer',
	kebab: 'drawer',
	translations: {
		trigger: { es: 'Abrir cajon', en: 'Open drawer' }
	},
	parts: [
		{
			name: 'Trigger',
			kebab: 'trigger',
			aria: [{ attr: 'aria-label', value: v.translationRef('trigger', 'Open drawer') }]
		}
	]
} as const satisfies Morfo;
```

Las traducciones compartidas no se duplican por componente:

```ts
value: v.commonRef('buttons.close', 'Close'); // #?common.buttons.close|Close
```

`ActiveUix` conecta el registro de morfos con `ActiveLangs`. Cuando el
provider crea `createSomaRuntime(morfo, sources)` o `soma.runtime(morfo,
sources)`, `registerMorfo(morfo)` registra el contrato `data-*` y publica
`morfo.translations` bajo `components.{kebab}`.

`commonLangs` en `core/langs.ts` aporta los defaults de `common.*`.
`ActiveUix` los registra sin pisar hojas existentes, de modo que el
integrador puede pasar sus propias traducciones y UIX solo completa lo que
falte.

No existe catálogo global por componente. `ActiveUix` conecta el registro de
morfos; cada componente publica sus textos cuando su morfo se registra.

## 8. Sistema reactivo

Capa fina sobre runes de Svelte 5 que permite pasar estado reactivo por referencia entre clases.

- `state<T>(initial)` → `State<T>` (mutable, `.current`)
- `readableActive(() => value)` → `Active<T>` (readonly derived)
- `writableActive(getter, setter)` → `State<T>` (two-way binding)

Los wrappers `.svelte` convierten props normales a `Active`/`State` con estas funciones. Esta conversion es la frontera entre el mundo de props de Svelte y el mundo de clases reactivas de soma.

## 9. Contratos data-\*

Los `data-*` son API publica formal, validados con `assertContract()`.

Convencion:

```
data-dialog                    → provider (sin -provider, sin -root)
data-dialog-trigger            → parte
data-dialog-content            → parte
data-state="open|closed"       → estado
data-disabled                  → flag
data-side="top|right|bottom|left" → posicion flotante
data-align="start|center|end"  → alineacion
data-starting-style            → animacion de entrada (1 frame)
data-ending-style              → animacion de salida (persiste)
data-nested                    → es hijo de otro del mismo tipo
data-nested-open               → tiene un hijo abierto
data-dragging                  → gesture drag activo
data-highlighted               → item con virtual focus (aria-activedescendant)
data-resizing                  → splitter resize activo
```

CSS variables expuestas:

```
--soma-floating-transform-origin
--soma-floating-available-width
--soma-floating-available-height
--soma-floating-anchor-width
--soma-floating-anchor-height
--soma-dialog-depth
--soma-dialog-nested-count
--drawer-progress              → 0-1 drag progress
--drawer-offset-x / y          → drag offset in px
--soma-toast-swipe-move-x / y  → toast swipe offset
```

## 10. IDs

Los IDs se generan con contexto de componente:

```
soma-dialog-c12
soma-dialog-trigger-c13
soma-dialog-content-c14
```

Pattern: `soma-{component}-{part}-{uid}`. Descriptivos e inspeccionables.

## 11. Barrel exports

### Componentes (jerárquico)

```ts
// $soma/components/index.ts
export * as Collapsible from './collapsible';
export * as Dialog from './dialog';
export * as Popover from './popover';
```

Consumo:

```ts
import { Dialog, Popover } from '$soma/components';
Dialog.Provider; // no SomaDialogProvider, no TerraDialogProvider
Dialog.Trigger;
```

### Internal

```ts
import { Portal, Arrow, VisuallyHidden, Soma } from '$soma/components/internal';
```

## 12. Fronteras externas

`soma` distingue entre:

- internos: `layers/`, `reactive/`, `dom/`, `provider/` — helpers propios
- externos: `@floating-ui/dom`, `runed`, `tabbable` — dependencias npm

Si una dependencia tiene API inestable o podria cambiar, se accede a traves de una frontera formal (como `layers/floating/` wrappea @floating-ui). Las dependencias estables (runed, svelte) se importan directamente.

## 13. Estructura del directorio

```
src/uix/soma/
├── SOMA_ARCHITECTURE.md       ← this document
├── COMPONENT_GUIDE.md         ← step-by-step implementation guide
├── README.md                  ← API reference
├── runtime.svelte.ts          ← SomaRuntime (morfo interpreter)
├── errors.ts                  ← typed runtime/context errors
├── core/
│   ├── soma.svelte.ts         ← Soma class (root instance)
│   └── langs.ts               ← shared commonLangs defaults
├── reactive/                  ← reactive system
├── provider/                  ← context + opts bridge
├── props/                     ← mergeProps, composeHandlers
├── keyboard/                  ← KEYS, directional
├── dom/                       ← DOM utilities, focus
├── css/                       ← styleToString, cssToStyleObj
├── id/                        ← createId, useId
├── types/                     ← shared types + service interfaces
├── layers/                    ← behavior layers (classes only)
│   ├── presence.svelte.ts
│   ├── focus-scope.svelte.ts
│   ├── dismissal.svelte.ts
│   ├── text-selection.svelte.ts
│   ├── scroll-lock.svelte.ts
│   ├── resize-observer.svelte.ts
│   └── floating/
├── datetime/                 ← UI-only helpers (announcer, segment DOM nav,
│                                segment UI-state shapes, segment-key predicates,
│                                description-element writers). NO date math,
│                                NO re-exports of days — import `$libs/days`
│                                directly.
├── components/
│   ├── internal/              ← Portal, Arrow, VisuallyHidden, <Soma>
│   ├── {name}/                ← each headless component
│   │   ├── {name}-provider.svelte.ts  ← state classes (NOT {name}.svelte.ts)
│   │   ├── types.ts                  ← public props + canonical field shapes
│   │   ├── langs.ts                  ← optional idlangref constants for imperative strings
│   │   ├── exports.ts
│   │   ├── index.ts
│   │   └── components/
│   │       ├── {name}.svelte          ← root wrapper
│   │       ├── {name}-trigger.svelte
│   │       └── ...
│   └── index.ts               ← hierarchical barrel
└── index.ts                   ← main barrel
```

### File naming convention

- State class: `{name}-provider.svelte.ts` — NOT `{name}.svelte.ts`
  - Avoids Vite module resolution ambiguity with `{name}.svelte` wrapper
- Reflects what's inside: provider/state classes
- Root wrapper: `{name}.svelte` in `components/` subdirectory
- Export name: always `Provider`, never `Root`

## 14. Anti-patterns

Avoid in soma:

- Complex logic inside wrapper `.svelte` — belongs in Provider
- Props drilling when context is the correct pattern
- `data-*` attrs outside of contract
- Inventing part names without checking reference library anatomies (ark-ui, bits-ui, radix-ui)
- Nesting layers as component wrappers in templates
- Inline `z-index: auto` that overrides CSS
- Coupling primitives to app libraries
- Product copy inside the primitive
- Speculative abstractions ("just in case")
- One-line files that only re-export (merge into parent)
- Redundant naming prefixes (SomaDialog, DialogLayerState)
- Dummy refs to satisfy a type — use `ProviderOpts` for no-DOM roots
- **State class file named same as wrapper** — `select.svelte.ts` + `components/select.svelte` causes Vite module duplication. Always use `{name}-provider.svelte.ts`
- **Event handlers not in props** — defining onclick as a class method but not including it in the props derived object
- **getContext in event handlers** — getContext only works during initialization. Capture references in constructor
- **Exporting as Root** — always `Provider`, never `Root`
- **Skipping reference library comparison** — mandatory step, no exceptions
- **Comments in Spanish** — all code comments in English
- **Standalone context functions** — no `createX()`, `getX()`, `useX()` as loose functions. Use `X.create()`, `X.get()`, `X.require()` static methods
- **Importing from `$lib/ext/app`** in components — components access services through `Soma`, never App directly
- **`from()` as factory name** — use `create()` consistently
- **Re-implementing date/time helpers inside soma** — extend `$libs/days` (A23). Importing from `$lib/util/dates` (legacy vendored) or `@internationalized/date` directly is forbidden; use `$libs/days`.
- **Re-export façades over days** — a soma module whose only job is to forward `$libs/days` symbols is dead weight. Consumers import from `$libs/days` directly.
- **UI-level helpers in dias, or date math in `soma/datetime/`** — dias is pure (no DOM, no Svelte, no KEYS); `soma/datetime/` is UI-only (screen-reader announcer, DOM segment navigation, `SegmentState` shapes, KEYS-based predicates). No crossover
- **`readonlySegments` without a concrete value anchor** — A24: warn via `soma?.logger.warn` when `value` is undefined. Range components split into `startReadonlySegments` / `endReadonlySegments` (A25)
- **`keydown.preventDefault()` as the only guard on contenteditable segments** — IME/paste/drop bypass keydown. Always add `onbeforeinput: e => e.preventDefault()` (A26)
- **Time placeholders as `'––'`** — use `createSegmentContent` / `createTimeSegmentContent` from `dias/segments.ts`; time parts render as `hh`/`mm`/`ss` (A28)
- **Pickers that reimplement field/calendar/popover** — compose via shared `writableActive` refs (A27). Only `Provider`, `Trigger`, and the calendar/slider bridge are unique parts
- **Demo pages as galleries of canned snippets** — every soma demo must be an interactive testbed wiring every public prop to a live control, including a Field-integration section (A29)
- **`HourCycle` as `'12h' \| '24h'`** — canonical form is numeric `12 \| 24` (matches `Intl.DateTimeFormat.hour12`). String forms are legacy

## 15. Estado actual y deuda histórica

Soma ha pasado por varias fases. La forma actual (rama `active-uix`,
post-2026-05-08):

- **Provider inheritance dropped** — los providers ya no heredan de un
  base abstracto; son clases concretas. La mecanica DOM comun vive en
  `SomaRuntime.part(...)`, y los casos que necesitan eventos semanticos
  usan el mismo `SomaRuntime` para `trigger`/`keydown`.
- **SomaRuntime cachea** la compilación del morfo (`compileMorfo` por
  WeakMap) y registra los `effects` que sincronizan `state → attrs` vía
  `dom.apply`.
- **Naming**: `Provider` (nunca `Root`); child providers referencian al
  padre como `provider`, nunca `root`. El export de un componente
  multi-parte sigue la forma compound `Toggle.Provider + Toggle.Trigger
  - ...`.
- **Data-attr naming**: `data-{component}` (provider) y
  `data-{component}-{kebab}` (sub-parts). Sin prefijo `data-soma-*`. El
  compiler emite estos via `compiled.parts.attrs`.
- **State files**: `{name}-provider.svelte.ts` (explicit, no ambiguity).
- **IDs**: descriptive (`soma-dialog-trigger-c13`).

## 16. Regla de estabilidad

Un componente de soma se considera estable cuando:

- su API publica esta clara y documentada con JSDoc
- sus `data-*` estan registrados y validados con `assertContract`
- el wrapper y el Provider siguen el patron general
- su accesibilidad base esta resuelta (ARIA, roles, keyboard)
- sus props se han comparado con ark-ui, bits-ui y radix-ui
- tiene demo page funcional en `web/routes/{componente}/`
- no depende de hacks locales, z-index hardcodeados, ni demo CSS para sostenerse
- compila con 0 errores (`svelte-check`)

## 17. New component checklist

See `COMPONENT_GUIDE.md` for the full step-by-step process (27 general steps + 4 date/time specific, with rules A1–A29). Summary:

```
[ ] 1. Compare with ark-ui, bits-ui, radix-ui — feature table
[ ] 2. Verify membership criteria
[ ] 3. Define parts + attrs + morfo.translations when the component owns text
[ ] 4. Create types.ts (props + canonical field shapes)
[ ] 5. Create langs.ts only for imperative idlangref constants, not as the catalog
[ ] 6. Create {name}-provider.svelte.ts (concrete state classes, no Provider inheritance)
[ ] 7. Create wrapper .svelte files (thin)
[ ] 8. Create exports.ts + index.ts
[ ] 9. Create interactive demo page + link in index (A29)
[ ] 10. README.md with anatomy, ARIA, data-attrs, comparison table
[ ] 11. svelte-check + test in browser
[ ] 12. Date/time components: only consume date/time domain via `$libs/days`,
        `onbeforeinput` on contenteditable, readonly-without-value warning,
        picker composition pattern (A23–A28)
```