Usar o extender zuix fuera de React
Cómo se escribe marcado del contrato y cómo se añade comportamiento sin framework. La guía de uso para personas está en Frameworks.
Reglas
- El contrato es HTML + CSS + tokens. La apariencia de un componente vive en su hoja de estilos,
por clases
z-*y atributos (data-state,data-size,aria-*). Nunca en lógica de un framework. - El marcado se copia del contrato. Fuente:
zui/html.jsonyzout/html.json. No se inventan clases ni estructura. - Iconos con
<z-icon name="…">,iconElement()en código que construye el DOM, oiconSvg()cuando hace falta una cadena. Sin SVG a mano ni emojis. - Comportamiento con
@zuccadev-labs/zuix-zui/domy, en layouts,@zuccadev-labs/zuix-zout/dom. No se reimplementa un diálogo, un menú, un cajón delShellni un divisor en la aplicación. - Un componente nuevo se diseña primero como marcado. Si su aspecto solo funciona con React, está mal hecho. El binding de React se escribe después y debe producir ese marcado.
behaviordice la verdad.none,domoreacten el manifiesto, según lo que hoy funciona.- Una sola lógica. Un cálculo que necesitan React y el modo DOM vive en
zui/src/core/y lo consumen los dos. No se escribe dos veces. - El texto de la aplicación entra por
textContentosetAttribute. Nunca concatenado en marcado. El marcado propio del módulo pasa porsetMarkup(zui/src/dom/shared.ts), el único punto que escribe HTML. - Un atributo que nombra otro elemento se resuelve con
byRef, no conquerySelectorsobre el valor. - Plataforma primero.
<dialog>conshowModal()para lo modal,popover="manual"para lo flotante. Sinz-indexni portales.
Patrones
Página sin framework
<body class="z-root z-canvas" data-z-dom>
…marcado del contrato…
<script type="module">
import "@zuccadev-labs/zuix-zicon/element";
import { init } from "@zuccadev-labs/zuix-zui/dom";
init();
</script>
</body>
Componente en otro framework (ejemplo Svelte)
<script>
export let variant = "secondary";
export let size = "md";
export let icon;
</script>
<button type="button" class="z-btn z-btn--{variant}" data-size={size} {...$$restProps}>
{#if icon}<z-icon name={icon} size="16"></z-icon>{/if}
<slot />
</button>
Marcado escrito a mano en un manifiesto
Lo que React monta por portal no aparece en el render estático. Su contrato se fija en el manifiesto:
{
"behavior": "dom",
"html": [{ "title": "Modal con pie", "code": "<button data-z-open=\"#m\">…</button>\n<dialog id=\"m\" class=\"z-liquid z-modal\">…</dialog>", "script": "opcional" }]
}
Añadir comportamiento a zui/dom
- Entrada:
zui/src/dom/index.ts, con un módulo por grupo al lado. Sin dependencias; solo APIs del navegador y la lógica dezui/src/core/. - Los listeners del documento se registran con la señal de
init(), para quedestroy()los retire. - Código pesado que casi nadie usa (los shaders del Carousel): módulo aparte cargado con
import()(zui/src/dom/carousel-gl.ts). Necesita su entrada enexportsypublishConfig.exports, su bundle entools/dist.mjs(listatargetsy mapaLAZY) y una caída sin él. - Los mismos atributos de estado que el binding de React, y el mismo teclado, también en
dir="rtl"(core/dir). - Compatible con
require-trusted-types-for 'script'y constyle-src 'self': las medidas se escriben por la API de estilos, no con atributosstyleen cadenas. - Lo que cambia solo con un clic se activa dentro de
[data-z-dom], para no chocar con React en la misma página. - Reglas de estilo que neutralizan el navegador:
zui/src/styles/native.css.
Verificación
| Comando | Comprueba |
|---|---|
pnpm html | El contrato se regenera sin errores |
pnpm dist | CSS y módulos empaquetados; examples/html regenerado |
pnpm test:unit | La lógica de core/ y de los módulos DOM cubiertos |
pnpm test:html | examples/html en Chrome, sin React: capas, teclado, tema, marca, móvil, RTL, CSP y Trusted Types |
pnpm check | Incluye html y dist |
Un componente con behavior: "dom" no está terminado hasta que tiene un caso en tests/html/cases/.