From f76b30499aedcd898c493a5d3f6bef10258916ff Mon Sep 17 00:00:00 2001 From: dev Date: Thu, 14 May 2026 01:52:01 +0200 Subject: [PATCH] Align Soma docs with runtime contracts --- src/uix/soma/README.md | 22 +++++++++---------- src/uix/soma/SOMA_ARCHITECTURE.md | 36 +++++++++++++++---------------- 2 files changed, 29 insertions(+), 29 deletions(-) diff --git a/src/uix/soma/README.md b/src/uix/soma/README.md index c0c6b34e0..40b398e7a 100644 --- a/src/uix/soma/README.md +++ b/src/uix/soma/README.md @@ -6,9 +6,9 @@ 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.Root + Tabs.Trigger + ...`) por simetría con los multi-parte. La -> forma flat (``) la expone `eidos` para componentes single-part. -> Convención 10 en [`src/docs/sema-implementation-guide.md`](../../docs/sema-implementation-guide.md). +> `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-13 @@ -213,7 +213,7 @@ src/uix/soma/ │ │ └── index.ts │ │ │ └── [componente]/ ← each headless component -│ ├── [comp]-provider.svelte.ts ← Provider subclasses +│ ├── [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 @@ -703,13 +703,13 @@ class Soma { readonly portalTo: string | HTMLElement | undefined; // Service accessors (delegan a ActiveUix) - get langs(): AppLangs; - get nums(): AppNums | undefined; - get money(): AppMoney | undefined; - get dates(): AppDates | undefined; - get units(): AppUnits | undefined; + 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(): AppLogger; + get logger(): EngineLogger; runtime(morfo, sources): SomaRuntime; } @@ -1018,7 +1018,7 @@ Referencia completa con todos los pasos en `COMPONENT_GUIDE.md`. Resumen: [ ] 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 (Provider subclasses) +[ ] 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 diff --git a/src/uix/soma/SOMA_ARCHITECTURE.md b/src/uix/soma/SOMA_ARCHITECTURE.md index b88cca7d0..a9019ec63 100644 --- a/src/uix/soma/SOMA_ARCHITECTURE.md +++ b/src/uix/soma/SOMA_ARCHITECTURE.md @@ -5,10 +5,8 @@ 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 como un Provider - -- SomaRuntime que escribe los `data-*` y `aria-*` que el contrato - declara. +**morfo** (contrato declarativo) y soma lo materializa mediante clases +concretas de estado que registran sus partes en `SomaRuntime`. ## 1. Proposito @@ -26,12 +24,13 @@ es responsabilidad de eidos. Cada componente se describe primero como 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 3 capas +## 2. Arquitectura de capas ``` -soma → headless: behavior, accesibilidad, data-* contracts, context, servicios -capa visual → apariencia: tokens, CSS, temas, motion, sound, semanticas -app → producto: composicion final, contenido, logica de negocio +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: @@ -51,7 +50,7 @@ Cada capa tiene responsabilidades estrictas: - apariencia (tokens, colores, tipografia, spacing) - tono visual (temas light/dark, variantes) - decisiones de diseno opinionated (sizes, recipes) -- motion y sound semanticos +- motion CSS y reacciones visuales a `data-event-*` - responsive design ### La capa visual NUNCA @@ -70,7 +69,7 @@ La frontera es los `data-*` attrs y las CSS variables que soma expone. Los layers, el sistema reactivo, el floating engine — son implementacion interna. El desarrollador de componentes interactua con: -- clases provider concretas + `SomaRuntime` +- clases concretas de estado + `SomaRuntime` - `Soma` class para servicios - Barrel imports jerárquicos (`import { Dialog } from '$soma/components'`) @@ -458,13 +457,13 @@ class Soma { readonly portalTo: string | HTMLElement | undefined; // Service accessors (delegate to ActiveUix) - get langs(): AppLangs; - get nums(): AppNums | undefined; - get money(): AppMoney | undefined; - get dates(): AppDates | undefined; - get units(): AppUnits | undefined; + get langs(): ActiveLangs; + get nums(): ActiveNumbers | undefined; + get money(): ActiveCurrency | undefined; + get dates(): ActiveDates | undefined; + get units(): ActiveUnits | undefined; get prefs(): ActiveUixPrefsView; - get logger(): AppLogger; + get logger(): EngineLogger; } ``` @@ -508,7 +507,8 @@ All classes that use Svelte context follow the same pattern: | `X.get()` | instance or `undefined` | Parent/context is optional | | `X.require()` | instance (throws) | Parent/context is required | -This applies to `App`, `Soma`, and all `Provider` subclasses. No standalone functions. No `from()`. No `ctx` exposed. +This applies to `App`, `Soma`, and all state classes that use context. No +standalone functions. No `from()`. No `ctx` exposed. ### Texto funcional @@ -785,7 +785,7 @@ See `COMPONENT_GUIDE.md` for the full step-by-step process (27 general steps + 4 [ ] 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 (Provider subclasses) +[ ] 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)