From f3bf6a02996eb64fa11d25b7d875ce7b4e413584 Mon Sep 17 00:00:00 2001 From: dev Date: Wed, 19 Aug 2026 00:26:26 +0200 Subject: [PATCH] =?UTF-8?q?docs(blocks):=20la=20ficha=20del=20shell=20cab?= =?UTF-8?q?=C3=ADa=20en=20cinco=20l=C3=ADneas=20porque=20no=20miraba=20el?= =?UTF-8?q?=20ecosistema?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fase 0 de F3.1 `app-shell`, firmada. La ficha original se escribió antes de que existieran el canon `Sidebar` y la capa `affix`, y el autor preguntó lo que había que preguntar: si su alcance tenía delante `active-app` y `active-uix` enteros. No los tenía. Las cuatro decisiones que se firman, y lo que las obligó: - **Q1 — el block NO cablea servicios.** La integración del ecosistema se demuestra en una app de referencia en app-land, no dentro del block. Un shell que leyera `App.session` para dibujar el menú de usuario sería una raíz de composición disfrazada: funcionaría, y metería el arranque del ecosistema dentro de una pieza que ha de poder caer en cualquier app. - **Q2 — dos modelos de scroll por prop.** `main` (rejilla 100dvh, sin fixed, sin números) es lo que cierra A-95 por construcción; `body` es lo que `docs-shell` necesitará para anclas y TOC pegada. - **Q3 — cabecera dentro del inset.** El provider del `Sidebar` ES la fila flex, así que su `Trigger` sólo vive dentro. Una cabecera a todo lo ancho exigiría partir ese provider: queda como gap de canon para v2. - **Q4 — canon `skip-link` + uno por región montada** (técnica G124). De paso, tres cosas que estaban mal escritas y ahora lo dicen: - El dossier afirmaba que **ninguna referencia trae skip-link** y que era superación nuestra. Es falso: Polaris lo trae en `Frame` y Atlassian genera un menú entero. La superación real es generarlos del mismo contrato que estampa el landmark. Y el icon-rail no es de Mantine (su `collapsed` es booleano); es de shadcn, AntD, Toolpad y Atlassian. El dossier tampoco miró nunca el `navigation-system` actual de Atlassian, y el `page-layout` que sí miró está deprecado. - **D-BLK.6 ha derivado**: la celda dice «ni prefs ni langs ni eidos» y la doctrina vigente (`blocks.md` §Services) sancionó dos servicios en julio y agosto. Queda enmendada con lo que sigue siendo cierto: ningún block CREA ni cablea servicios. - **E-5 está desfasada**: `Command.Dialog` ya trae el atajo (`shortcut`, `mod+k` por defecto). El listener a mano de F4.1 no hay que escribirlo. - **F3.2 `auth`**: la ficha dice cuatro vistas y el dominio tiene seis. Falta `update-password`, que no es un lujo — es donde aterriza el enlace de recuperación, y sin ella el camino de `recover` no termina. `blocks.md` gana un párrafo «Shells» bajo §Conventions: qué poseen (geometría, landmarks, alturas) y dónde está la línea (la raíz de composición es de la app). Verificado en código antes de escribirlo: `Sidebar.Inset` acepta `child`, `Box` expone minHeight/position/overflow y `Grid` templateRows —la rejilla del shell no necesita CSS propio—, y `Sticky` expone `root`. docs:check 0 errores, 0 avisos (635 docs). Co-Authored-By: Claude Opus 5 --- docs/architecture/blocks.md | 18 +++ docs/process/PLAN-blocks.md | 166 ++++++++++++++++++--- docs/process/RESEARCH-blocks-references.md | 105 +++++++------ 3 files changed, 213 insertions(+), 76 deletions(-) diff --git a/docs/architecture/blocks.md b/docs/architecture/blocks.md index c924ecc35..4c882fb43 100644 --- a/docs/architecture/blocks.md +++ b/docs/architecture/blocks.md @@ -151,6 +151,24 @@ asserts its own detectors against inline fixtures on every run). announcer on the page. Anything beyond these two is the app's, or the admission rule firing. +- **Shells (`app-shell`, `docs-shell`) — geometría, no cableado.** A shell is + the block that owns a page's REGIONS: their landmarks, their skip links and + their heights. That last one is why the tier needs it at all — an affixed + notice and a pinned header fight for the same edge, and no component can + arbitrate because none of them owns the page (ledger A-95). What a shell owns: + the grid, the scroll model, the landmark set, and the state that its own + regions share (a collapsed nav, a folded aside). What a shell does NOT own, + and this is the line that matters: **the composition root**. Creating + `ActiveApp`, attaching `ActiveUix`, mounting ``, wiring `modeSource` / + `densitySource` into `ActiveEidos`, projecting prefs onto the document, + persisting them — all of that is the application's, exactly as it is for every + other block (§Services above; only composition roots create services). A shell + that read `App.session` to draw a user menu would be a composition root + wearing a block's clothes: it would work, and it would put the ecosystem's + boot inside a piece meant to be droppable into any app. The seam is the same + one every block uses — snippets and props — and the proof that it suffices is + an application built on it, not a paragraph. + - **Prop naming — `size` es del BLOCK, nunca de una pieza interna**: un block que reenvía el eje de tamaño de algo que envuelve lo nombra **`{pieza}Size`** (`containerSize` para la medida del `Container`, `sectionSize` para el aire del diff --git a/docs/process/PLAN-blocks.md b/docs/process/PLAN-blocks.md index ce40f248b..bc6f7e506 100644 --- a/docs/process/PLAN-blocks.md +++ b/docs/process/PLAN-blocks.md @@ -84,15 +84,15 @@ quedó enmendada** respecto a la propuesta original del plan (que proponía `src/blocks/`); el resto se firmó tal como estaba propuesto. D-BLK.3/4/5 derivan de doctrina ya vigente y se firmaron por no-objeción. -| # | Decisión | FIRMADO | -| ----------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| **D-BLK.1** | Ubicación y alias | **`src/uix/blocks/`** + alias `$blocks` (decisión de usuario: el tier es UI y vive junto a las capas). La prueba de encapsulación se conserva íntegra: borrar `src/uix/blocks/` deja `npm run check` verde y NADA del canon (`morfo/soma/sema/eidos/active-uix/langs`) lo importa — blocks es un tier bajo `src/uix/`, no una quinta capa. | -| **D-BLK.2** | Estilos | **Layout-components-first**: el layout se hace componiendo `Container/Section/Stack/Flex/Grid/AutoGrid/Wrap/Group/Separator/AspectRatio/Surface` y sus props. Un block NO trae `.css` propio; un `