# soma Librería headless de componentes compuestos para Svelte 5. Capa de comportamiento dentro de UIX — emite los `data-*` y `aria-*` que el contrato declara en `morfo`, gestiona estado y eventos, y delega lo visual a `eidos` mediante el DOM. > **Doctrina del API**: soma mantiene la forma compound (`Toggle.Provider`, > `Tabs.Provider + Tabs.Trigger + ...`) por simetria con los multi-parte. > Eidos no inventa una API flat paralela: aplica la capa visual sobre la > anatomia declarada por morfo y materializada por soma. ## Handoff 2026-05-14 Soma no debe crecer ahora con `ActiveSoma`/`EngineSoma` por simetria. El contrato minimo de `SomaRuntime` con `ActiveUix` (`dom`, `events`, `langs`, `format`, `prefs`) queda descrito en `src/uix/contracts.ts`. La regla de ownership ya queda cerrada: Soma no crea servicios compartidos. Recibe `dom` desde el scope `Soma.runtime(...)`; si no hay una superficie `ActiveDom`, falla en la raiz activa, no dentro de un componente. Punto critico para manana: confirmar que todo atributo mutable sigue pasando por el servicio DOM activo, y que ninguna ausencia de `dom` hace que Soma o Sema caigan a escrituras directas. --- ## 1. Proposito soma resuelve **behavior, accesibilidad, composicion y estado** para componentes compuestos. No resuelve presentacion visual — eso es responsabilidad de eidos. soma existe para: - keyboard navigation entre partes de un componente - focus management (trap, scope, roving) - ARIA relationships entre partes (trigger↔content, tab↔panel) - floating/positioning de overlays - portal rendering - presence management (enter/exit animations) - dismiss on outside click / Escape - gesture tracking (drag, swipe, resize) - state machines para componentes con multiples estados - form integration (hidden inputs, validation context) soma NO existe para: - colores, tipografia, espaciado, animaciones visuales - tokens de tema - responsive design - iconografia - componentes de una sola parte sin behavior complejo --- ## 2. Criterio de pertenencia Un componente pertenece a soma si cumple **ambos** criterios: ### Composicion de partes El componente tiene 2 o mas subcomponentes que se comunican via context. Ejemplo: Accordion tiene Root, Item, Trigger, Content — cada parte lee estado del padre. ### Behavior complejo El componente implementa al menos uno de: - Keyboard navigation no trivial (roving focus, arrow keys, typeahead) - Focus management (trap, scope, restore) - Floating positioning (popover, tooltip, dropdown) - ARIA relationships que requieren IDs cruzados (aria-controls, aria-labelledby) - State machine con transiciones (open/closed, editing/preview) - Drag/gesture behavior (slider, splitter, drawer, toast) - Form integration via context (validation state, hidden inputs) Si un componente cumple solo uno de los criterios o ninguno, no necesita pasar por soma — su lógica puede vivir directamente en el wrapper de eidos. --- ## 3. Independencia soma solo depende de: - svelte (runes: $state, $derived, $effect) - runed (Context, watch) - clsx (class merging) - @floating-ui (positioning) - `$libs/reactive`, `$libs/days`, `$libs/datagrid`, `$libs/forms`, etc. — utilidades puras del repo (no façades) - `$uix/morfo` — el contrato cross-layer (compileMorfo + SomaRuntime) - `$uix/sema` — vocabulario semántico + EngineSemantic soma NO depende de eidos. La capa visual lee del DOM y de los tipos públicos del soma; la dirección del acoplamiento es eidos → soma, no al revés. Los motores reutilizables que no son comportamiento headless viven fuera de Soma: `src/libs/datagrid` para tablas, `src/libs/forms` para estado/validacion de formularios y `src/libs/strings` para scoring/fuzzy search. Soma no los reexporta: los consumidores importan esos motores desde `$libs/*`, que es su fuente canonica. ### Imports **Dentro de un componente/layer Soma**: usar paths relativos para piezas del mismo componente o de Soma. Para servicios/utilidades cross-layer usar el alias canonico (`$libs/*`, `$uix/morfo`, `$adom`) para dejar clara la frontera de ownership. El alias `$soma/*` es superficie publica para consumidores, no para imports internos del propio Soma. ```ts // Inside a component — relative import { DRAWER_LANGS } from './langs'; import type { DrawerSide } from './types'; import { Presence } from '../../layers/presence.svelte'; // Cross-layer utility — alias import { createTable } from '$libs/datagrid'; ``` **Consumidores** (layouts, app code, test pages): usan el alias `$soma/` que configuran en su build. ```ts // Consumer code — alias import { Soma } from '$soma'; import * as Drawer from '$soma/components/drawer'; ``` soma **sí importa** del paquete hermano **morfo** (`$uix/morfo`), que es el contrato declarativo de la superficie DOM de cada componente (partes, data-attrs, ARIA, keyboard, focus). Ver §4b. --- ## 4. Estructura ``` src/uix/soma/ │ ├── README.md │ ├── reactive/ ← sistema reactivo (propio, sin deps externas) │ ├── reactive.svelte.ts ← state, readableActive, writableActive, autoReset │ └── index.ts │ ├── provider/ ← context + opts bridge │ ├── provider.svelte.ts ← ProviderOpts/WithRefOpts │ ├── context.ts ← context(name) — wraps runed Context │ └── index.ts │ ├── props/ ← prop merging │ ├── merge-props.ts ← mergeProps(...sources) │ ├── compose-handlers.ts │ └── index.ts │ ├── keyboard/ ← keyboard system │ ├── keys.ts ← KEYS constant │ ├── directional.ts ← getDirectionalKeys │ ├── is-using-keyboard.svelte.ts │ └── index.ts │ ├── dom/ ← DOM utilities │ ├── core.ts ← isHTMLElement, contains, getDocument, etc. │ ├── env.ts ← isBrowser, isIOS, isTouch │ ├── context.svelte.ts ← DOMContext class │ ├── focus/ ← focus utilities │ │ ├── focus.ts ← focus(), focusFirst(), focusWithoutScroll() │ │ ├── tabbable.ts ← getTabbableCandidates(), edges │ │ ├── roving-focus.svelte.ts ← RovingFocusGroup class │ │ ├── arrow-nav.ts ← useArrowNavigation() │ │ └── guards.ts ← isElementHidden, isFocusVisible │ └── index.ts │ ├── css/ ← style utilities │ ├── parse.ts ← cssToStyleObj, styleToString │ ├── sr-only.ts ← srOnlyStyles │ └── index.ts │ ├── id/ ← ID generation │ ├── create-id.ts │ └── index.ts │ ├── types/ ← shared types │ ├── component.ts ← WithChild, WithRefOpts, Orientation, Direction │ ├── events.ts ← SomaEvent, SomaKeyboardEvent, SomaMouseEvent │ ├── html.ts ← PrimitiveDivAttributes, PrimitiveButtonAttributes │ ├── guards.ts ← isNull, isFunction, isNumberString │ └── index.ts │ ├── layers/ ← behavior layers (ver §10) │ ├── presence.svelte.ts ← animation-aware mount/unmount │ ├── focus-scope.svelte.ts ← focus trap, auto-focus, restore │ ├── dismissal.svelte.ts ← escape + interact-outside (merged) │ ├── text-selection.svelte.ts ← prevenir selection overflow │ ├── scroll-lock.svelte.ts ← body scroll lock con refcount │ ├── resize-observer.svelte.ts ← ResizeObserver con lifecycle Svelte │ ├── floating/ ← posicionamiento relativo a anchor (@floating-ui) │ │ ├── floating.svelte.ts │ │ ├── use-floating.svelte.ts │ │ ├── safe-polygon.ts │ │ ├── types.ts │ │ ├── utils.ts │ │ └── index.ts │ ├── gesture/ ← drag/swipe/resize gesture tracking │ │ ├── gesture.svelte.ts ← Gesture.base(), Gesture.drag(), Gesture.resize() │ │ ├── velocity.ts ← ring buffer + velocity calculation (pure) │ │ ├── types.ts │ │ └── index.ts │ └── index.ts │ ├── core/ │ └── soma.svelte.ts ← Soma class (root instance, service accessors) │ ├── components/ │ ├── internal/ ← componentes Svelte internos de soma │ │ ├── arrow.svelte │ │ ├── visually-hidden.svelte │ │ ├── portal.svelte │ │ ├── portal-consumer.svelte │ │ └── index.ts │ │ │ └── [componente]/ ← each headless component │ ├── [comp]-provider.svelte.ts ← state classes concretas │ ├── types.ts ← public props + canonical field shapes │ ├── langs.ts ← optional idlangref constants for imperative strings │ ├── components/ ← svelte wrappers │ ├── exports.ts ← barrel (Provider, not Root) │ └── index.ts │ └── index.ts ← root scope only (`Soma`) ``` --- ## 4b. Morfo — contrato declarativo cross-layer Cada componente tiene un archivo en `src/uix/morfo/components/{kebab}.ts` que declara, en un único objeto tipado, la **superficie DOM pública** del componente: - **parts** — el árbol de partes (name, kebab, kind, defaultElement, role, states, supportsNesting). - **data** — qué data-attrs emite cada parte, con valores enum cuando aplica y severity (`required` / `recommended` / `optional`). - **aria** — qué atributos ARIA emite cada parte, con la fuente del valor tipada vía tagged union (`v.literal`, `v.stateRef`, `v.partRef`, `v.propRef`, `v.translationRef`) y condición de emisión opcional. - **keyboard** — los atajos de teclado relevantes por parte. - **focus** — política de foco para overlays (`initial`, `trap`, `return`, `restore`). - **translations** — catálogo de traducciones propio del componente, registrado bajo `components.{kebab}`. - **apg** — URL al patrón WAI-ARIA APG cuando aplica. - **scope** — las capas que implementan el componente: `['soma']`, `['soma', 'eidos']`, etc. El morfo es la **única fuente de verdad** del contrato público. soma, air, eidos, sema y la docs auto-generada lo consumen todos. ### ¿Por qué morfo existe? Antes de morfo, la información estructural de un componente vivía en seis sitios: 1. mapas manuales de attrs — nombres de partes dentro del provider. 2. registro manual de contrato — enums de data-attrs en el provider. 3. ARIA hard-coded en cada `$derived.by(...)` de props. 4. Keyboard handlers distribuidos por el provider. 5. Prose en el README. 6. Selectores en CSS de air/eidos, `.csem` de sema y tablas de docs. Renombrar una parte (`content` → `panel`) tocaba 6+ sitios sin verificación automática. Drift cross-layer (soma emite `data-dialog-content`, eidos estiliza `data-dialog-panel`) era silencioso. Con morfo, **todo se declara una sola vez**. `compileMorfo`, `registerMorfo`, `SomaRuntime` y el helper tipado `createAttrs` consumen el morfo directamente. El script `npm run morfo:check` valida el DOM real contra la declaración en CI. ### Cómo soma consume un morfo Cada provider raíz crea un runtime con su morfo. Ese paso registra el contrato `data-*`, compila la declaración y publica `morfo.translations` en los `ActiveLangs` conectados por `ActiveUix`: ```ts import { dialogMorfo } from '../../../morfo/components/dialog'; this.soma = Soma.require(); this.runtime = this.soma.runtime(dialogMorfo, sources); ``` Cuando un provider necesita un selector DOM, puede usar `createAttrs(morfo)` desde `$uix/morfo`. Es solo un helper tipado de nombres, no registra contrato ni escribe en el DOM: ```ts import { createAttrs } from '$uix/morfo'; const attrs = createAttrs(dialogMorfo); // { provider: 'data-dialog', trigger: 'data-dialog-trigger', ... } ``` `createAttrs` es **genérica con `const` type parameter** (TS 5.0+): infiere el tipo del objeto retornado a partir de la forma literal del morfo. Si un wrapper o provider escribe `attrs.trigerr`, es error de compilación. El soporte de autocomplete lista las partes válidas. El registro ejecutable ocurre al crear el runtime: `createSomaRuntime(morfo, sources)` y `soma.runtime(morfo, sources)` llaman internamente a `registerMorfo(morfo)`. Ese registro compila el morfo, registra su contrato `data-*` y publica `morfo.translations` en los `ActiveLangs` conectados por `ActiveUix`. **Requisito de autoría**: cada morfo se declara como `as const satisfies Morfo`: ```ts // ✅ Obligatorio export const dialogMorfo = { ... } as const satisfies Morfo; // ❌ Pierde literales, degrada `createAttrs` a `Record` export const dialogMorfo: Morfo = { ... }; ``` Ver el dev guide completo en [`src/uix/morfo/README.md`](../morfo/README.md). ### Validación Tres capas atrapan tres clases de drift: - **Schema (build/dev)**: `validateMorfo(morfo)` en `src/uix/morfo/schema.ts` valida shape (sium) + invariantes cruzados (kebabs únicos, `partRef.target` resuelve, `stateRef.state` está en `states[]`, etc.). - **Strict mode en `assertContract` (dev runtime)**: valida que los data-attrs emitidos por el provider tienen valores declarados en el morfo. Logs warnings en consola cuando algo se desvía. - **CI**: `npm run morfo:check` navega a cada demo y valida el DOM real contra el morfo; `npm run morfo:vocabulary` detecta divergencias de vocabulario canónico (`open|closed`, `active|inactive`, etc.). ### Qué NO va en morfo | No | Va en | | -------------------------------- | --------------------------------- | | Props del componente | `{component}/types.ts` con JSDoc | | Summary, comparativa, ejemplos | `{component}/README.md` | | Traducciones shared/common | app/langs catalog bajo `common.*` | | Constantes idlangref imperativas | `{component}/langs.ts`, opcional | | Event handlers, state machines | `{component}-provider.svelte.ts` | | Recetas visuales | `src/uix/eidos/` (futuro) | --- ## 5. Sistema reactivo Los runes de Svelte 5 (`$state`, `$derived`) son compiler magic — solo funcionan en archivos `.svelte` y `.svelte.ts`, y no se pueden pasar como valores entre clases o funciones en TypeScript puro. soma necesita exactamente eso: pasar estado reactivo como argumento de constructor para componer Providers, layers y gestures. La capa `reactive/` resuelve esto con contenedores (`Active`, `State`) que envuelven runes y exponen `.current` — el mismo patrón que React refs y Solid signals. Cuando Svelte ofrezca signals exportables de primera clase, esta capa se convierte en un alias thin migrable sin tocar los consumidores. ### Primitivas ```ts // Mutable container — backed by $state const count = state(0); count.current++; // Readonly derived — backed by $derived.by const double = readableActive(() => count.current * 2); double.current; // 2 // Writable derived — getter + setter (para two-way binding) const bound = writableActive( () => pressed, (v) => (pressed = v) ); ``` ### Tipos ```ts // Readonly reactive container type Active = { readonly current: T }; // Mutable reactive container type State = { current: T }; // Mapping helpers — wraps all properties type ActiveProps = { [K in keyof T]: Active }; type StateProps = { [K in keyof T]: State }; ``` ### Regla Los providers de soma reciben sus opciones como `Active` o `State`. Los wrappers svelte convierten props normales a Active/State con `readableActive`/`writableActive`. Esta conversion es la frontera entre el mundo de props de Svelte y el mundo de clases reactivas de soma. --- ## 6. Sistema de contexto Hay dos niveles: la funcion `context()` (interna) y los static methods de cada clase provider (API publica). ### Nivel interno — `context()` ```ts import { context } from '../provider'; const ctx = context('Accordion'); ctx.set(instance); // registra en Svelte context ctx.get(); // lee — throws si no existe ctx.getOr(fallback); // lee con fallback ``` `context()` wraps runed's `Context` con mensajes de error descriptivos. ### Nivel publico — static methods Los consumidores (sub-parts, otros componentes) nunca tocan `ctx` directamente. Usan los static methods: ```ts // Root provider registra via create() static create(opts) { return new AccordionProvider(opts); } private constructor(opts) { this.runtimePart = this.runtime.part('provider', { id: opts.id, ref: opts.ref, owner: this, context: AccordionProvider.ctx, syncAttrs: true }); } // Sub-parts leen via require() o get() this.provider = AccordionProvider.require(); // throws this.group = TooltipGroupProvider.get(); // undefined si no existe ``` | Method | Returns | Use | | ----------- | --------------------- | -------------------- | | `create()` | instance | Root crea + registra | | `get()` | instance \| undefined | Padre opcional | | `require()` | instance (throws) | Padre obligatorio | --- ## 7. Runtime parts Soma ya no usa una clase base `Provider`. Cada provider es una clase concreta del componente, y registra sus partes mediante `SomaRuntime`. El runtime es la autoridad de morfo en soma: registra la parte, crea el ref attachment, expone la identidad renderizable (`id`, marker `data-*`, archetype) y valida los props autorizados por el contrato. ```ts import { context, type WithRefOpts } from '../provider'; import { Soma } from '../core/soma.svelte'; import type { SomaRuntime, SomaRuntimePart } from '../runtime.svelte'; import { accordionMorfo } from '$uix/morfo/components/accordion'; export class AccordionProvider { static readonly ctx = context('Accordion'); static get() { return this.ctx.getOr(undefined) as AccordionProvider | undefined; } static require() { return this.ctx.get(); } readonly opts: AccordionOpts; readonly soma: Soma; readonly runtime: SomaRuntime; readonly runtimePart: SomaRuntimePart; static create(opts: AccordionOpts) { return new AccordionProvider(opts); } private constructor(opts: AccordionOpts) { this.opts = opts; this.soma = Soma.require(); this.runtime = this.soma.runtime(accordionMorfo, {}); this.runtimePart = this.runtime.part('provider', { id: opts.id, ref: opts.ref, owner: this, context: AccordionProvider.ctx, syncAttrs: true }); } readonly props = $derived.by(() => this.runtimePart.assert({ ...this.runtimePart.props, 'data-orientation': this.opts.orientation?.current, 'data-disabled': boolToEmptyStrOrUndef(this.opts.disabled.current) } as const) ); } ``` ### Lo que `runtime.part()` proporciona ```ts interface SomaRuntimePart { readonly attachment: RefAttachment; readonly props: { id, [partAttr], 'data-archetype'?, ...attachment }; resolveProps(bindings?): Record; assert

(props: P): P; // validates data-* contract } ``` `runtime.part()` es la única API pública para registrar partes. Cuando una parte ya declara sus `states`/`props` como sources del runtime, activa `syncAttrs: true`; en ese modo los attrs derivados por morfo se escriben mediante `uix.dom`. Si el provider todavía compone attrs en sus props renderizados, deja `syncAttrs` sin activar para evitar doble autoridad DOM. ### Lo que cada componente define - `static ctx` — solo si usa context - `static create()` / `get()` / `require()` — static method convention - Constructor — asigna `opts` y registra `runtimePart` - `readonly props = $derived.by(...)` — ARIA, data-\*, events - Event handlers — logica de interaccion - Derived state — valores computados --- ## 8. Sistema de attrs ```ts import { createAttrs } from '$uix/morfo'; import { accordionMorfo } from '$uix/morfo/components/accordion'; const attrs = createAttrs(accordionMorfo); attrs.provider; // "data-accordion" attrs.item; // "data-accordion-item" attrs.trigger; // "data-accordion-trigger" // Selector: `[${attrs.content}]` ``` `createAttrs` vive en `morfo` y solo expone nombres tipados para selectors o tooling. La emisión de markers (`data-accordion`, `data-accordion-item`, etc.) y la escritura de attrs dinámicos pertenecen a `SomaRuntime.part(...)`. ### Regla de naming - La parte `provider` genera `data-{component}` (sin sufijo `-provider`) - Las demas partes generan `data-{component}-{part}` - Estos attrs son API publica — cambiarlos es breaking change - air/eidos los usa como selectores CSS ### Contracts (via morfo) El morfo declara cada parte y sus `data-*` attrs (`required`/`recommended`/`optional`, con valores enumerados cuando aplica). `runtimePart.assert()` valida en desarrollo que los atributos emitidos cumplen el morfo. `scripts/morfo-check.ts` valida contra el DOM real. ### Boolean helpers ```ts boolToStr(true); // 'true' boolToEmptyStrOrUndef(true); // '' boolToEmptyStrOrUndef(false); // undefined boolToTrueOrUndef(true); // true boolToTrueOrUndef(false); // undefined ``` --- ## 9. mergeProps ```ts const merged = mergeProps(restProps, state.props); ``` Comportamiento: - Event handlers (`onclick`, `onfocus`, etc.) → compuestos con `composeHandlers` - `class` → merged con clsx - `style` → merged (object + string) - `hidden: false` / `disabled: false` → eliminados (fix Svelte) - Resto → last wins --- ## 10. Layers Los layers son infraestructura compartida que los componentes compuestos usan para resolver problemas transversales. ### Principio `layers/` contiene **solo clases de comportamiento** (`.svelte.ts`). Son infraestructura consumida por Providers. Los componentes Svelte internos de soma (Portal, Arrow, VisuallyHidden) viven en `components/internal/` — no son layers. ### Behavior layers — consumo en Provider Los behavior layers se instancian dentro del Provider y exponen `.props` para merge: ```ts class DrawerContentProvider { readonly focusScope = FocusScope.use({ ref, trap, ... }); readonly dismissal = Dismissal.use({ ref, onEscapeKeydown, ... }); readonly scrollLock = new ScrollLock(); readonly gesture = Gesture.drag({ ref, direction, threshold, ... }); readonly props = $derived.by(() => this.runtimePart.assert({ ...this.runtimePart.props, ...this.focusScope.props, ...this.dismissal.props, ...this.gesture.props, role: 'dialog', })); } ``` ### Convencion `.use()` vs `new` vs `Gesture.x()` - `X.use(opts)` — el layer gestiona su propio lifecycle via `watch`/`$effect`. Constructor privado. - `new X(opts)` — el consumidor controla el lifecycle. - `Gesture.base/drag/resize(opts)` — factory functions, tres especializaciones. | Layer | API | Props | Descripcion | | ----------------- | --------------------------------- | ----------------------------------- | -------------------------------------------------- | | `Presence` | `new Presence(opts)` | — | Animation-aware mount/unmount. Expone `isPresent`. | | `FocusScope` | `FocusScope.use(opts)` | `{ tabindex: -1 }` | Focus trap, loop, auto-focus, restore. | | `Dismissal` | `Dismissal.use(opts)` | `{ onfocuscapture, onblurcapture }` | Escape + interact-outside. Global registry. | | `TextSelection` | `TextSelection.use(opts)` | — | Previene selection overflow durante drag. | | `ScrollLock` | `new ScrollLock()` | — | Body scroll lock con refcount. | | `ResizeObserver$` | `new ResizeObserver$(getter, cb)` | — | ResizeObserver con lifecycle Svelte. | | `Gesture.base` | `Gesture.base(opts)` | `{ onpointerdown }` | Pointer tracking + axis lock + velocity. | | `Gesture.drag` | `Gesture.drag(opts)` | `{ onpointerdown }` | Base + progress + snap points + dismiss. | | `Gesture.resize` | `Gesture.resize(opts)` | `{ onpointerdown }` | Base + delta + min/max constraints. | | `SafePolygon` | `new SafePolygon(opts)` | — | Hover-gap corridor between trigger↔content. | ### Gesture layer Three specializations, shared base. The layer measures — the component decides what it means. ``` Gesture.base() → pointer tracking + axis lock + velocity + cancel Gesture.drag() → base + offset + progress + snap points + threshold + dismiss Gesture.resize() → base + delta forwarding + min/max constraints ``` Key rules: - `setPointerCapture` deferred until moveBuffer exceeded for containers with child buttons (Drawer, Slider). Pure drag handles (Splitter) capture immediately — the handle IS the drag target - Cleanup on unmount: `$effect(() => { return () => { this.gesture.cancel(); }; })` - CSS vars (`--drawer-progress`, `--drawer-offset-x/y`) set by provider, consumed by visual layer - During drag: `transition: none` + inline `transform` for immediate feedback - Design: `src/uix/soma/layers/GESTURES.md` ### SafePolygon Handles pointer gap between trigger and floating content (DropdownMenu submenus, Tooltip). Calculates a corridor polygon — pointer can traverse the gap without closing. Used by any component where trigger and content have physical separation. ### Patterns **Registry over DOM queries**: Sub-parts register in a Map on mount, unregister on unmount. Keyboard nav iterates the registry instead of `querySelectorAll`. Used by Stepper triggers, Select labels. **Virtual focus (`aria-activedescendant`)**: For Select, Combobox — focus stays on trigger, items highlighted via `data-highlighted`. DOM focus (roving tabindex) for Menu, Toolbar, RadioGroup. **Exit animation via Presence**: Toast, Drawer — dismiss marks element as `dismissing`, Presence animates exit, `onComplete` removes from array. ### Naming - Archivo = concepto: `dismissal.svelte.ts`, `presence.svelte.ts` - Clase = concepto: `Dismissal`, `Presence`, `FocusScope`, `ScrollLock`, `Gesture` - Opts type: `{Concepto}Opts`: `DismissalOpts`, `GestureBaseOpts` - Sin sufijos redundantes: no `Layer`, no `State`, no `Body` --- ## 11. Keyboard ```ts KEYS.ENTER; // 'Enter' KEYS.ESCAPE; // 'Escape' KEYS.ARROW_DOWN; // 'ArrowDown' KEYS.SPACE; // ' ' const { nextKey, prevKey } = getDirectionalKeys('ltr', 'horizontal'); // nextKey: 'ArrowRight', prevKey: 'ArrowLeft' IsUsingKeyboard.current; // boolean — teclado vs pointer ``` --- ## 12. DOM utilities ### Focus ```ts focusWithoutScroll(element) focusFirst(candidates[]) getTabbableCandidates(container) getTabbableEdges(container) ``` ### Roving Focus ```ts const roving = new RovingFocusGroup({ candidateAttr: attrs.trigger, rootNode: ref, loop: true, orientation: 'horizontal' }); roving.handleKeydown(currentElement, event); ``` ### Scroll Lock ```ts const lock = new ScrollLock(); lock.locked.current = true; // locks body scroll lock.locked.current = false; // restores ``` --- ## 13. Soma (root instance) Soma es el scope runtime de componentes. Lee `ActiveUix` desde context y expone solo la superficie que los providers necesitan: `dom`, `events`, `langs`, formatters, prefs y logger. No crea servicios propios. Las traducciones de componentes se declaran en `morfo.translations` y `ActiveUix` las registra en `ActiveLangs` cuando el morfo entra en el registro. ### Clase ```ts class Soma { static create(opts?: SomaOptions): Soma; // crea y registra en context static get(): Soma | undefined; // lee del context (safe) static require(): Soma; // throws si no existe readonly uix: ActiveUix; readonly portalTo: string | HTMLElement | undefined; // Service accessors (delegan a ActiveUix) get langs(): ActiveLangs; get nums(): ActiveNumbers | undefined; get money(): ActiveCurrency | undefined; get dates(): ActiveDates | undefined; get units(): ActiveUnits | undefined; get prefs(): ActiveUixPrefsView; // adaptador historico respaldado por uix.prefs get logger(): EngineLogger; runtime(morfo, sources): SomaRuntime; } ``` ### Traducciones El catálogo nuevo de traducciones de componente vive en el morfo: ```ts export const drawerMorfo = { name: 'Drawer', kebab: 'drawer', translations: { trigger: { es: 'Abrir cajon', en: 'Open drawer' } } // ... } as const satisfies Morfo; ``` `ActiveUix` conecta el registro de morfos con `ActiveLangs`: cuando un provider crea `createSomaRuntime(morfo, sources)` o llama `soma.runtime(morfo, sources)`, el morfo se registra y sus `translations` se extienden bajo `components.{kebab}`. `commonLangs` en `src/uix/langs.ts` aporta los defaults para `v.commonRef(...)` (`common.buttons.close`, `common.buttons.cancel`, etc.). El integrador puede predefinir sus propias claves en el schema de langs; `ActiveUix` solo rellena las que falten. No existe catálogo global por componente. `ActiveUix` conecta el registro de morfos; cada componente publica sus textos cuando su morfo se registra. Namespace structure: ``` common.buttons.close ← shared (soma + eidos + app) common.buttons.open components.dialog.trigger ← component-specific components.drawer.trigger ``` ### Uso en Providers ```ts // drawer/langs.ts — optional constants for imperative strings export const DRAWER_LANGS = { CLOSE: '#?common.buttons.close|Close' } as const; // drawer-provider.svelte.ts import { DRAWER_LANGS } from './langs'; class DrawerCloseProvider { readonly props = $derived.by(() => ({ 'aria-label': this.provider.soma?.langs.ts(DRAWER_LANGS.CLOSE) })); } ``` Rules: - `langs.ts()` for simple strings, `langs.t()` only for interpolated templates - Fallback inline via idlangref (`#?path|fallback`), never `?? 'fallback'` - No `translate()` helpers in providers - Text owned by the component goes in `morfo.translations` and is referenced with `v.translationRef` - Common keys (`close`, `open`, `cancel`) use `common.*` / `v.commonRef`, not per-component duplicates ### Setup ```svelte ``` --- ## 14. Naming conventions ### Clases - `AccordionProvider` — root provider del componente - `AccordionItemProvider` — sub-parte - `AccordionTriggerProvider` — sub-parte ### Files - `accordion-provider.svelte.ts` — state classes/providers (NOT `accordion.svelte.ts`) - `accordion.svelte` — root wrapper (in `components/`) - `accordion-item.svelte` — sub-part wrapper - `types.ts` — public props + canonical field shapes - `langs.ts` — optional idlangref constants for imperative provider strings - `exports.ts` — barrel (exports `Provider`, not `Root`) ### Props - `AccordionProps` not `AccordionProviderProps` (root doesn't need "Provider" suffix in type name) - `AccordionItemProps` — sub-part - `AccordionTriggerProps` — sub-part ### Documentacion de props (norma obligatoria) Todas las props de todos los componentes deben documentarse con JSDoc en `types.ts`. Cada prop lleva: descripcion, `@default` si tiene valor por defecto, notas de comportamiento si aplica. ### Comparacion con librerias de referencia Cada componente headless debe compararse con su equivalente en ark-ui, bits-ui y radix-ui. Documentar: que props tienen ellos que soma no, y justificar si se omiten o se incluyen. ### Attrs - `data-accordion` — root (sin `-root`) - `data-accordion-item` — sub-parte - `data-state` — estado compartido (`open`/`closed`, `on`/`off`, `checked`/`unchecked`) - `data-disabled` — flag de disabled - `data-orientation` — orientacion - `data-dragging` — gesture activo ### Events - DOM handlers: `onclick`, `onkeydown`, `onfocus` (lowercase, Svelte convention) - User callbacks: `onOpenChange`, `onValueChange` (camelCase) ### Layers - Archivo = concepto: `dismissal.svelte.ts`, `presence.svelte.ts` - Clase = concepto: `Dismissal`, `Presence`, `FocusScope`, `ScrollLock`, `Gesture` - Opts = `{Concepto}Opts`: `DismissalOpts`, `GestureBaseOpts` - Sin sufijos redundantes --- ## 15. Patron de componente ### Provider ({name}-provider.svelte.ts) ```ts import { accordionMorfo } from '$uix/morfo/components/accordion'; // Canonical field shapes defined in types.ts, referenced here interface AccordionOpts extends WithRefOpts, StateProps, ActiveProps {} export class AccordionProvider { static readonly ctx = context('Accordion'); static get() { return this.ctx.getOr(undefined) as AccordionProvider | undefined; } static require() { return this.ctx.get(); } readonly opts: AccordionOpts; readonly soma: Soma; readonly runtime: SomaRuntime; readonly runtimePart: SomaRuntimePart; static create(opts: AccordionOpts) { return new AccordionProvider(opts); } private constructor(opts: AccordionOpts) { this.opts = opts; this.soma = Soma.require(); this.runtime = this.soma.runtime(accordionMorfo, {}); this.runtimePart = this.runtime.part('provider', { id: opts.id, ref: opts.ref, owner: this, context: AccordionProvider.ctx, syncAttrs: true }); } readonly props = $derived.by(() => this.runtimePart.assert({ ...this.runtimePart.props, 'data-orientation': this.opts.orientation?.current, 'data-disabled': boolToEmptyStrOrUndef(this.opts.disabled.current) } as const) ); } ``` ### Wrapper svelte ({name}.svelte) ```svelte {#if child} {@render child({ props: mergedProps })} {:else}

{@render children?.()}
{/if} ``` --- ## 16. Patron de composicion Los componentes compuestos siguen el patron Provider → Parts con contexto: ```svelte Click me Content here ``` ### Flujo de datos ``` Provider ├── crea AccordionProvider ├── registra en context via runtime.part(..., { context, owner }) └── children ├── Item │ ├── crea AccordionItemProvider │ ├── lee AccordionProvider via AccordionProvider.require() │ └── children │ ├── Trigger → lee AccordionItemProvider.require() │ └── Content → lee AccordionItemProvider.require() └── Item └── ... ``` ### Regla de context - Root siempre registra en context al crear su `runtimePart` (`runtime.part(..., { owner: this, context: XProvider.ctx })`) - Sub-parts leen con `XProvider.require()` (obligatorio) o `XProvider.get()` (opcional) - Si una sub-part tiene hijos que necesitan su estado, crea su propio context (Item tiene ctx, Trigger lo lee) - El context es por componente instance — multiples Accordion en la misma pagina funcionan independientemente --- ## 17. Relacion con air/eidos ``` soma → headless behavior, accesibilidad, data-* contracts, context air → visual layer: tokens, CSS recipes, sizes, variants eidos → enhanced visual layer: motion, sound, advanced interactions ``` air/eidos consume soma: - Importa componentes: `import { Accordion } from '$soma/components'` - Responde a data-\*: `[data-accordion][data-state='open'] { ... }` - Añade props visuales: `size`, `variant`, `color` - Usa mismas translations: `#?common.buttons.close|Close`, `#?components.dialog.trigger|Open dialog` air/eidos NUNCA: - Importa Provider classes internas de soma - Depende de estructura DOM incidental - Accede a propiedades privadas - Duplica behavior que soma ya resuelve --- ## 18. Checklist de componente nuevo Referencia completa con todos los pasos en `COMPONENT_GUIDE.md`. Resumen: ``` [ ] 1. Comparar con ark-ui, bits-ui, radix-ui — feature table [ ] 2. Verificar criterio de pertenencia [ ] 3. Definir partes + attrs + contract [ ] 4. Crear types.ts (props + canonical field shapes) [ ] 5. Añadir `morfo.translations` para texto propio; `langs.ts` solo si hacen falta constantes imperativas [ ] 6. Crear {name}-provider.svelte.ts (state classes concretas, sin heredar de Provider) [ ] 7. Crear wrappers .svelte (thin) [ ] 8. Crear exports.ts + index.ts [ ] 9. Crear test page + link en index [ ] 10. svelte-check + test in browser ``` --- ## 19. Inventory ### Implemented Accordion, AlertDialog, Announce, Breadcrumb, Calendar, Carousel, Checkbox (Group), Clipboard, Collapsible, ColorField, ColorPicker, Combobox, Command, ContextMenu, DateField, DatePicker, DateRangeField, DateRangePicker, Dialog, DragDrop, Drawer, DropdownMenu, Editable, Feed, Field, FileUpload, Form, GridList, LinkPreview, Listbox, Menubar, Meter, NavigationMenu, NumberField, Pagination, PinInput, Popover, Progress, RadioGroup, RangeCalendar, RatingGroup, ScrollArea, SearchField, Select, Slider, Splitter, Stepper, Switch, Tabs, Table, TagGroup, TagsInput, TimeField, TimePicker, TimeRangeField, TimeRangePicker, Toast, Toggle (Group), Toolbar, Tooltip, TreeGrid, TreeView, VirtualGrid and VirtualList. ### Planned No hay tiers planned vigentes en este documento. Nuevas piezas se aceptan solo si cumplen el criterio de pertenencia de §2 y declaran primero su morfo. ### Visual-native (no soma) Avatar, Icon y SVG son eidos-native hoy. Primitivas de una sola parte como Badge, Button, Label, Separator, Spinner, AspectRatio, Typography o Layout deben seguir eidos-native salvo que aparezca behavior compuesto real.