Saltar al contenido principal

Actualizar de 0.1 a 0.2

La 0.2.0 es la primera versión con cambios incompatibles. Los hice todos juntos a propósito: mientras la suite está en 0.x prefiero romper una vez, con una guía, que arrastrar decisiones que ya sé que son malas. Esta página reúne todo lo que hay que tocar en una aplicación que usa la 0.1.0. El detalle de cada cambio está en el CHANGELOG.md de su paquete.

Hay tres motivos detrás de casi todo:

  1. Sin bibliotecas de UI. El binding de React estaba hecho sobre radix-ui. Ahora usa primitivas propias sobre la plataforma (<dialog>, Popover API), con la misma lógica que el modo sin framework. Cambia el marcado de las capas y desaparecen las variables --radix-*.
  2. Contraste medido. La validación de tokens mide ahora los pares de color que las hojas usan de verdad. Varios no llegaban al mínimo de WCAG 2.2 AA y cambiaron de valor.
  3. Node 20 terminó su soporte el 2026-04-30. El mínimo pasa a Node 22.12.

Antes de empezar​

Requisito0.10.2
Node20 o posterior22.12 o posterior
React y React DOM (solo para el binding)1919. React 18 no se admite
NavegadoresSin línea declaradaChrome y Edge 116, Firefox 125, Safari 17, Safari de iOS 18.3 (Compatibilidad)
Dependencias que instala zuizuix-tokens y radix-uiSolo zuix-tokens

Los cinco paquetes se actualizan juntos. En 0.x el rango ^0.1.0 no llega a la 0.2.0, así que una actualización normal (pnpm up, npm update) deja la aplicación donde estaba: hay que pedir la versión nueva.

pnpm up --latest "@zuccadev-labs/*"
npm install @zuccadev-labs/zuix@^0.2.0 # con npm; si usas los paquetes sueltos, cada uno con @^0.2.0

pnpm no instala por defecto una versión publicada hace menos de un día: el mismo día de la publicación, pnpm up --latest puede responder que todo está al día.

Si tu aplicación importaba algo de radix-ui o de @radix-ui/* aprovechando que zui lo instalaba, decláralo ahora en tu propio package.json: ya no llega de forma transitiva.

Lista rápida​

Búsquedas que encuentran casi todo lo que hay que cambiar en el código de una aplicación:

grep -rnE -- "--radix-|data-radix-|radix-" src/ # variables y atributos que ya no existen
grep -rnE "z-overlay-scrim|\[role=.?dialog.?\]" src/ # velo y selectores de diálogo y de Popover modal
grep -rnE "> *\.z-toast-viewport" src/ # la región de avisos cambia de sitio en el documento
grep -rnE "data-elevated|asChild|forceMount" src/ # atributos y props retirados
grep -rnE "<ToastProvider[^>]* label=" src/ # prop renombrada
grep -rnE "<Popover" src/ # ahora exige label o aria-labelledby
grep -rnE 'data-side="(left|right)"' src/ # tiradores de zout escritos a mano

CSS y marcado​

Afecta a quien escribió selectores propios sobre el marcado de zui, y a quien escribió a mano el HTML del contrato.

Diálogos​

Modal, Drawer, ConfirmDialog y CommandPalette de React pintan un <dialog>, como ya hacía el modo sin framework. Antes eran un div[role=dialog] con un div.z-overlay-scrim aparte.

AntesAhora
.z-modal[role=dialog]dialog.z-modal
.z-overlay-scrim y sus modificadoresdialog::backdrop. La clase ya no existe
Sin title, un h2.z-sr-only daba el nombreSin title, el nombre va en aria-label
[data-elevated] para subir una capaNo existe: todo va en la capa superior del navegador

En pruebas de extremo a extremo, un diálogo abierto se localiza con dialog:modal o dialog[open]. El fondo queda inerte por el propio navegador: ya no lleva aria-hidden.

Popover modal​

<Popover modal> es también un <dialog> abierto con showModal(). El no modal sigue siendo un div[role=dialog] en la capa superior.

AntesAhora
.z-popover[role=dialog] con aria-modaldialog.z-popover
El resto de la página se marcaba con aria-hidden y se le quitaba el punteroQueda inerte por el navegador: ni puntero, ni foco, ni lectores de pantalla
Una pulsación fuera lo cerrabaIgual: lo cierra y no llega a lo que hay debajo

dialog:modal encuentra ahora también un Popover modal abierto. Si una prueba cuenta diálogos con ese selector, acótalo con la clase (dialog.z-modal:modal).

Avisos con un diálogo abierto​

Con un <dialog> modal abierto, el navegador deja inerte todo lo que queda fuera de él, también la región de avisos. Para que un aviso se pueda leer, enfocar y descartar, la región se muda al diálogo de arriba mientras está abierto y vuelve a <body> cuando se cierra.

AntesAhora
toast() de zui/dom.z-toast-viewport siempre en <body>En <body>, o dentro del <dialog> modal abierto más reciente
Toast de ReactLa región se pintaba donde estuviera ToastProvider en el árbolSale por un portal a un div[data-z-toast-root] con display: contents, que cuelga de <body> o del <dialog> modal abierto más reciente

Un selector que dependa de dónde cuelga la región (body > .z-toast-viewport, #app .z-toast-viewport) deja de valer; .z-toast-viewport a secas sigue encontrándola.

Variables CSS​

No queda ningún --radix-*, data-radix-* ni id radix-….

AntesAhora
--radix-select-trigger-width--z-anchor-width (la escriben Select y Combobox)
--radix-popover-trigger-widthSin sustituto: Popover no escribe el ancho de su disparador. Usa la prop width
--radix-*-content-available-height--z-available-height
--radix-*-content-available-width--z-available-width
--radix-toast-swipe-move-x, -move-y, -end-x, -end-y--z-toast-swipe-move-x, -move-y, -end-x, -end-y
--radix-accordion-content-height--z-accordion-content-height

Resto del marcado​

ComponenteQué cambia
Toast (React y toast())La región es div.z-toast-viewport[role=region] con nombre y cada aviso un div.z-toast[role=status|alert]. Antes eran ol y li. La región solo existe mientras hay avisos
Menu, ContextMenu (React)Cada entrada es un button[role=menuitem] (antes div) y el separador lleva role="separator"
Select (React)role="listbox" va en .z-listbox__viewport, dentro de .z-listbox, y las opciones llevan data-value. Con name o required, el campo de formulario es un <select> nativo oculto (.z-native-input), no un input[type=hidden]
Checkbox, Switch, RadioEl campo nativo oculto lleva la clase z-native-input (antes estilos en línea) y está siempre en el marcado. RadioGroup y SegmentedControl ya no llevan dir ni tabindex en el grupo
TabsLos ids son …-tab-<valor> y …-panel-<valor>; cada pestaña lleva data-value
AccordionLa cabecera es un h2…h6 real según headingLevel (antes h3 con aria-level). El contenido de una sección cerrada sigue montado, oculto con hidden. .z-accordion lleva data-type
Slider (React)Los tiradores son hijos directos de .z-slider y la pista se sitúa con inset-inline-start y -end. El contenedor lleva data-min, data-max, data-step y data-value

El marcado que emite React es ahora exactamente el del contrato (html.json): se puede copiar a una página sin React.

Props y tipos de React​

ComponenteAntesAhora
Popoverlabel opcionalEl nombre accesible es obligatorio en los tipos: label, o aria-labelledby con el id de un encabezado del panel
ToastProviderlabelregionLabel: nombre de la región, por defecto Notifications (F8)
Checkbox, Switch, Radio, RadioGroup, Slider, ToggleSus *Props extendían los tipos de la biblioteca anteriorSon los atributos del elemento más las props propias (checked, defaultChecked, onCheckedChange, value, onValueChange, pressed, onPressedChange…). Desaparecen asChild, dir, loop y forceMount, y tres que la suite no usaba: form en RadioGroup, checked y required en Radio (los decide el grupo) y preserveThumbOrder en Slider. RadioGroup value ya no admite null
Slider con varios tiradoresEnviaba name[]Envía un campo por tirador con el mismo name
Button, IconButton con loadingdisabledaria-disabled="true". Ver abajo

NavLink asChild se mantiene.

Comportamiento​

Nada de esto exige cambiar código, pero cambia lo que ve y lo que hace quien usa la aplicación. Conviene repasar las pruebas que dependan de ello.

QuéAntesAhora
Button e IconButton con loadingDeshabilitados: el foco del teclado se perdía al empezar la cargaaria-disabled: no ejecutan onClick ni envían el formulario (pasan a type="button" mientras cargan), pero conservan el foco. Un selector :disabled ya no los encuentra
Dirección de escrituraTabs, Menu, Slider, RadioGroup y SegmentedControl de React la leían de una prop o de un proveedorSe lee del DOM: dentro de dir="rtl" las flechas se reflejan sin configurar nada
EscapeEn un SearchInput con texto dentro de un Modal, limpiaba el campo y además cerraba el diálogoCierra solo la capa de arriba y respeta un evento ya cancelado: la primera pulsación limpia el campo y la segunda cierra el diálogo. En un submenú cierra ese nivel
SegmentedControl, RadioGroup—Las flechas mueven el foco y la selección, con vuelta al otro extremo
Menu y ContextMenu (React)Abiertos con el puntero, el foco iba al menú sin resaltar ninguna entradaEl foco va a la primera entrada, se abran con el teclado o con el puntero, como en zui/dom. Una prueba que abre con un clic y pulsa Flecha abajo llega ahora a la segunda entrada. Las flechas dan la vuelta del último al primero
Popover no modal—Salir con Tab por un extremo lo cierra y devuelve el foco al disparador
Popover modal—Retiene el foco (Tab da la vuelta), bloquea el desplazamiento y el resto de la página queda inerte. Ver «Popover modal» arriba
DatePicker requiredEl botón llevaba aria-requiredLa obligatoriedad la valida un campo nativo oculto, que impide enviar el formulario vacío
confirm() de zui/domEscape no hacía nadaEscape cancela (resuelve false), como ConfirmDialog en React. El clic en el velo sigue sin cerrar
ConfirmDialogCerrar con Escape solo llamaba a onOpenChange(false)Llama también a onCancel
Tooltip (React y data-z-tooltip)La burbuja ignoraba el punteroLa burbuja recibe el puntero y Escape la cierra (WCAG 1.4.13)
Link disabledEjecutaba onClickNo lo ejecuta
z:close en un <dialog>Solo al cerrar con closeDialog()También con dialog.close() y con <form method="dialog">; data-state pasa a closed
Casilla (role="checkbox") en zui/domIntro la cambiabaSolo Espacio, como en React
Clic en el velo de un <dialog>Soltar sobre el velo cerrabaSolo cierra si la pulsación empezó también en el velo
Diálogos en zui/dom—Bloquean el desplazamiento de la página y Tab da la vuelta dentro del diálogo
Pagination, DataTable, CommandPalette—page se redondea; los NaN se ordenan al final; la búsqueda de la paleta ignora acentos

Tokens y color​

Ningún token se elimina ni se renombra. Cambian valores, y hay tokens nuevos que conviene usar.

Valores que cambian​

TokenQué cambiaEfecto visible
--z-fg-subtleMás opaco en todas las marcas y temasEl texto sutil se ve algo más marcado
--z-control-border, --z-control-border-hoverDe --z-line a --z-fg al 50 % y a --z-fg-mutedLos campos de formulario tienen un borde más marcado (3:1)
--z-accent-ring, --z-focus-ringDe --z-accent al 45 % a --z-accent-text, opacoEl anillo de foco es más visible
--z-accent-solid-hoverOscurece en lugar de aclararEl botón primario se oscurece al pasar el puntero
Marca zutool, tema oscuroDegradado del fondo atenuado; cristal de 0.66 a 0.82 de opacidad; fg-muted y canvas-fg-muted más opacosEl cristal deja pasar menos fondo
Marca dazlabs, tema oscuroCristal de 0.66 a 0.72 de opacidadIgual, más leve

Tokens nuevos​

ParaUsaEn lugar de
Texto de color y enlaces--z-accent-text, --z-success-text, --z-warning-text, --z-danger-text, --z-info-text--z-accent, --z-success…
Fondo con texto encima--z-success-solid, --z-warning-solid, --z-danger-solid, --z-info-solid (y el --z-accent-solid que ya existía)El color sin sufijo

Si tu aplicación pinta texto con var(--z-accent) o var(--z-danger), cámbialo al -text: el color sin sufijo queda para rellenos, bordes e iconos, y como texto no llega a 4.5:1 en todas las superficies.

Componentes que cambian de color​

Los componentes de zui ya usan los tokens nuevos. Cambia el tono de: los enlaces (.z-link, cuyo hover se distingue ahora por el subrayado pleno), el texto de peligro (Button variant="danger", errores de Field, entradas de menú con data-danger), el texto y el fondo de Badge en sus tres variantes, el delta de StatTile, las estrellas vacías de Rating, el día de hoy del calendario y el velo de LoadingOverlay, que pasa a ser del color del lienzo.

Layouts (zout)​

QuéAntesAhoraQué hacer
TitleBar<div><header> (región banner). Las clases no cambianSi ya tienes otro banner en la página, as="div". Un selector div.z-titlebar pasa a .z-titlebar
Tirador de los paneles del Shelldata-side="right" (sidebar) y "left" (inspector)data-side="end" y "start"Solo si escribiste el marcado a mano o tienes selectores sobre ese atributo
Cierre de una pestaña de TabStrip18 × 18 px24 × 24 pxNada; revisa si ajustaste el alto de la tira
Panel auto del Shell antes de medirseSe veía acoplado un instanteNo se muestra si no cabe. .z-shell es un contenedor de consultas (container: z-shell / inline-size)Nada, salvo que tu CSS declare otro container-name sobre .z-shell

Iconos (zicon) y paraguas​

No hay cambios incompatibles. <z-icon hidden> ahora se oculta de verdad, y Icon con aria-label deja de ir con aria-hidden. El paraguas gana entradas (/zui/dom/carousel-gl, /tokens/<marca>.css, /tailwind.css, /docusaurus.css).

Si usas una política de seguridad de contenido​

zui/dom crea la política de Trusted Types zuix-zui. Si tu CSP declara require-trusted-types-for 'script', añade trusted-types zuix-zui (CSP y Trusted Types).

Comprobar el resultado​

  1. tsc --noEmit: los tipos señalan Popover sin nombre, ToastProvider label y las props retiradas.
  2. Abrir cada diálogo, menú y selector de la aplicación, con teclado y con puntero.
  3. Repasar en los dos temas las pantallas con texto de color, insignias y formularios.
  4. Si tienes pruebas de extremo a extremo, revisar los selectores de diálogo, de avisos y de botones en carga.