Zag.js: máquinas para componentes headless

Un menú desplegable accesible tiene alrededor de cuarenta reglas de comportamiento: qué tecla mueve el resaltado, qué pasa al escribir varias letras seguidas, dónde vuelve el foco al cerrar, qué ocurre si el puntero entra mientras el teclado navega, cuándo se cierra al hacer clic fuera y en qué orden si hay dos capas abiertas. Ninguna de esas reglas es visual y todas son estado. Zag.js parte de esa observación y la lleva hasta su conclusión industrial: si el comportamiento de un componente es una máquina, entonces se puede escribir una sola vez, verificar contra una especificación y ejecutar en React, Vue, Solid o Svelte sin reescribirlo. Lo interesante para este nivel no es que Zag sea una alternativa a XState —lo es, y con una implementación propia— sino que demuestra dónde vive el valor real de una máquina en la práctica cotidiana.

El patrón de tres piezas

Un componente de Zag no se importa como componente: se importa como máquina más proyección. El consumo tiene siempre la misma forma, y esa uniformidad es deliberada porque es lo que permite que un mismo cerebro sirva para cuarenta componentes distintos.

import * as menu from '@zag-js/menu'
import { useMachine, normalizeProps } from '@zag-js/react'

export function useMenu(id: string) {
  const servicio = useMachine(menu.machine, { id })        // 1. la maquina, viva y con identidad
  const api = menu.connect(servicio, normalizeProps)       // 2. proyeccion a propiedades de DOM
  return api                                                // 3. el framework solo reparte props
}

La segunda línea es la que conviene mirar despacio. connect es una función pura del estado actual de la máquina a una descripción de la interfaz: no renderiza nada, no conoce React y no decide etiquetas. Devuelve grupos de propiedades listos para repartir sobre los elementos que tú elijas, con toda la semántica accesible ya resuelta.

const disparador = api.getTriggerProps()
// id: 'menu:v1:trigger'
// aria-haspopup: 'menu'
// aria-expanded: false
// aria-controls: 'menu:v1:content'
// onPointerDown, onKeyDown, onBlur ... enlazados al envio de eventos

Ese objeto es, literalmente, la vista de la máquina en el sentido en que las arquitecturas unidireccionales usan la palabra: una proyección del estado, sin decisiones propias. Y normalizeProps es el adaptador que traduce esa descripción neutra al dialecto de cada framework, porque el mismo concepto se escribe de tres maneras según dónde aterrice: el nombre del manejador de eventos, la propiedad de clase, la forma de los estilos en línea. Esa traducción, que ocupa muy poco código, es lo que hace innecesario un compilador para conseguir portabilidad.

El componente accesible es un protocolo

Aquí está el hallazgo conceptual que justifica todo lo demás. Las prácticas de autoría de WAI-ARIA no describen apariencias: describen estados, eventos y transiciones. Cuando una guía dice que en un menú abierto la flecha abajo mueve el resaltado al siguiente elemento y que al llegar al final vuelve al principio, está escribiendo una tabla de transiciones en prosa. Codificarla como máquina no es una traducción creativa, es una transcripción, y transcribir tiene tres consecuencias inmediatas.

flowchart LR
A[especificacion de autoria accesible] --> B[maquina del componente]
B --> C[estado actual y envio de eventos]
C --> D[connect proyecta propiedades neutras]
D --> E[normalizeProps traduce al framework]
E --> F[React]
E --> G[Vue]
E --> H[Solid]
style B fill:#cba6f7,color:#11111b
style D fill:#89b4fa,color:#11111b

La forma interna de estas máquinas es reconocible aunque el núcleo de Zag sea propio y no dependa de XState. Estados con nombre, transiciones por evento, acciones nombradas que se resuelven en un solo sitio y efectos ligados al estado que los necesita.

// forma simplificada de la maquina de una capa desplegable
const maquina = createMachine({
  initialState: () => 'cerrado',
  states: {
    cerrado: {
      on: { ABRIR: { target: 'abierto', actions: ['invocarAlAbrir'] } },
    },
    abierto: {
      effects: ['atraparFoco', 'cerrarAlPulsarFuera', 'colocarCapaFlotante'],
      on: {
        CERRAR: { target: 'cerrado', actions: ['devolverFocoAlDisparador'] },
        SIGUIENTE: { actions: ['moverResaltado'] },            // transicion interna, no sale del estado
      },
    },
  },
})

La transición interna de SIGUIENTE es un detalle instructivo: mover el resaltado no cambia de estado, así que no debe reejecutar los efectos de entrada. Un modelo que no distinguiera transición interna de externa volvería a atrapar el foco en cada pulsación de flecha. Estas librerías se toman esa distinción muy en serio porque el coste de equivocarse es un componente que parpadea o que roba el foco, y ese es exactamente el tipo de defecto que nadie reproduce en desarrollo y todo el mundo sufre en producción.

Consumir, adaptar o escribir la tuya

Consumir una máquina ajena tiene una consecuencia que conviene aceptar con los ojos abiertos: el grafo no es tuyo. Puedes influir en él por los bordes —opciones de creación, propiedades reactivas, interceptar el cambio de estado, decidir el marcado— pero no puedes añadir un estado intermedio ni cambiar qué transición es legal. Cuando tu requisito no cabe en los bordes, no hay parche elegante posible, y esa rigidez es el precio directo de la garantía de conformidad.

Los bordes por los que sí puedes influir tienen una forma reconocible, y merece la pena verlos juntos porque delimitan con exactitud el espacio de personalización disponible.

const servicio = useMachine(menu.machine, {
  id: useId(),                                   // identidad estable entre servidor y cliente
  open: abierto,                                 // propiedad gobernada desde fuera
  onOpenChange: (d) => setAbierto(d.open),       // interceptas el resultado, no la transicion
  onSelect: (d) => ejecutarAccionDeDominio(d.value),
})

El identificador no es un detalle administrativo: de él se derivan todos los atributos que relacionan disparador y contenido, así que tiene que coincidir entre el marcado del servidor y el del cliente o la hidratación romperá silenciosamente las referencias accesibles. Y la pareja de propiedad gobernada más devolución de llamada es la única forma de compartir el control: delegas una variable del contexto hacia fuera, no el grafo. Puedes decidir si la capa está abierta, pero no puedes decidir que entre abierta y cerrada exista un tercer estado intermedio, y confundir ambas capacidades es la fuente habitual de frustración con estas librerías.

La última fila del cuadro esconde la decisión más importante y la que más equipos se saltan: no mezcles el dominio con el componente. La máquina del menú sabe abrir, resaltar y cerrar; no debe saber qué significa el elemento que has resaltado ni qué proceso de negocio dispara. Cuando aparece la tentación de meter una regla de tu aplicación dentro de la máquina del componente, la respuesta correcta casi siempre es tener dos máquinas y hacer que hablen: la del componente gobierna la interacción, la tuya gobierna el proceso, y la comunicación entre ambas se limita a eventos con nombre. Es el mismo reparto de propiedades que aplicaste al separar la cache de datos del grafo de flujo en el nivel dieciséis.