El wizard como máquina: cada paso un estado

Casi todo el modelado empieza con un trabajo arqueológico: descubrir qué estructura escondía un código que creció añadiendo una bandera cada vez que apareció un caso nuevo. Con un asistente por pasos ese trabajo no existe. La estructura viene impresa en la especificación, dibujada en el prototipo y enunciada en voz alta por quien la pidió: primero los datos personales, luego la dirección, luego el pago, luego la revisión y el envío. El dominio llega ya en forma de grafo dirigido, con nodos que tienen nombre propio y aristas etiquetadas con acciones del usuario. Y aun así la implementación habitual traduce ese grafo a un entero que se incrementa, perdiendo en la traducción justo aquello que el grafo garantizaba. La pérdida no es cosmética: un entero admite operaciones que el flujo prohíbe y borra distinciones que el flujo necesita.

El grafo que ya venía dibujado

Para que un patrón sirva de caso canónico tiene que cumplir tres condiciones incómodas a la vez, y el asistente las cumple sin esfuerzo. La primera es que el conjunto de situaciones sea finito, pequeño y conocido de antemano: un alta tiene cinco pasos, no un número que dependa de los datos. La segunda es que las transiciones tengan causa externa y nombre natural: nadie avanza solo, se avanza porque alguien pulsó continuar. La tercera, la más rara, es que el diagrama resultante sea legible por personas que no programan. El statechart de un asistente es exactamente el mismo dibujo que diseño ya tenía en su documento, y esa coincidencia convierte el modelo en artefacto compartido en lugar de en jerga de ingeniería.

Hay una cuarta razón, menos evidente y más pedagógica: el asistente exhibe en un espacio diminuto casi todo el repertorio del track. Necesita guardas para impedir el avance con datos inválidos, necesita historia para volver sin perder lo escrito, necesita transiciones condicionales para las ramas que dependen de respuestas previas, necesita un actor invocado para el envío y estados finales con salida para devolver el resultado. Quien modela bien un asistente ha ejercitado el vocabulario completo sobre un dominio que entiende sin que nadie se lo explique.

El entero que sabe demasiada aritmética

La implementación por defecto guarda un número y lo incrementa. Un entero, sin embargo, es un elemento de una estructura algebraica con operaciones cerradas: se le puede sumar, restar y multiplicar, y el resultado sigue siendo un entero legítimo. Un flujo de pasos no tiene ninguna de esas propiedades. No existe la suma de dos pasos, no existe el paso menos uno y no existe el paso siete cuando solo hay cinco. Al elegir el entero como representación se importa toda esa aritmética a un dominio que no la admite, y el sistema de tipos deja de poder ayudar porque para él cualquier número es un valor válido.

La fila de la inserción es la que más dinero cuesta. Un índice es una medida ordinal: codifica posición, que es una propiedad accidental, y no identidad, que es la esencial. Cuando negocio pide meter un paso de verificación entre la dirección y el pago, todas las condiciones que decían tres pasan a referirse a otra pantalla sin que nada falle en compilación ni en ejecución. Con nombres, insertar es una operación local y el resto del grafo ni se entera.

Pasos como estados, botones como eventos

La traducción es mecánica y por eso conviene hacerla despacio una vez. Cada pantalla es un estado. Cada botón es un evento con nombre de intención, no de destino. Y la tabla de transiciones concentra en un único lugar la respuesta a la pregunta de qué viene después de qué.

import { setup, assign } from 'xstate'

type Datos = { nombre: string; email: string; calle: string; ciudad: string; tarjeta: string }

export const alta = setup({
  types: {
    context: {} as { datos: Partial<Datos> },
    events: {} as
      | { type: 'SIGUIENTE'; parche: Partial<Datos> }
      | { type: 'ATRAS' }
      | { type: 'CONFIRMAR' },
  },
  actions: {
    acumular: assign({
      datos: ({ context, event }) =>
        event.type === 'SIGUIENTE' ? { ...context.datos, ...event.parche } : context.datos,
    }),
  },
}).createMachine({
  id: 'alta',
  initial: 'datos',
  context: { datos: {} },
  states: {
    datos: { on: { SIGUIENTE: { target: 'direccion', actions: 'acumular' } } },
    direccion: {
      on: { SIGUIENTE: { target: 'pago', actions: 'acumular' }, ATRAS: 'datos' },
    },
    pago: {
      on: { SIGUIENTE: { target: 'revision', actions: 'acumular' }, ATRAS: 'direccion' },
    },
    revision: { on: { CONFIRMAR: 'enviado', ATRAS: 'pago' } },
    enviado: { type: 'final' },
  },
})

Lo decisivo de este código no es lo que hace sino lo que deja de estar en otro sitio. El componente del paso de dirección ya no sabe que después viene el pago: emite SIGUIENTE y se desentiende. Esa inversión rompe el acoplamiento en cadena típico de los asistentes escritos a mano, donde cada pantalla importa el nombre de la siguiente y reordenar el flujo obliga a tocar todas. Aquí el orden vive en un solo archivo, y ese archivo es también el diagrama.

stateDiagram-v2
[*] --> datos
datos --> direccion: SIGUIENTE
direccion --> datos: ATRAS
direccion --> pago: SIGUIENTE
pago --> direccion: ATRAS
pago --> revision: SIGUIENTE
revision --> pago: ATRAS
revision --> enviado: CONFIRMAR
enviado --> [*]

Posición, acumulación y todo lo derivado

Un asistente tiene dos ejes y confundirlos es el error de modelado más caro del patrón. El primero es la posición: finita, discreta, con nombres, y por eso vive en los estados. El segundo es la acumulación de lo que el usuario ha ido escribiendo: dominio inmenso, no enumerable, y por eso vive en context. La distinción no es una convención de la librería, es lo que mantiene el modelo analizable: si metieras el correo del usuario en la identidad del estado tendrías tantos estados como correos posibles y ninguna herramienta podría recorrerlos.

Con esa separación clara, casi todo lo que la interfaz necesita deja de guardarse y pasa a calcularse. El número de paso, el porcentaje de progreso, el texto del botón, si el retroceso está disponible: todo es una función pura de la posición actual y del contexto.

const ORDEN = ['datos', 'direccion', 'pago', 'revision'] as const

export function progreso(snapshot: Snapshot) {
  const actual = ORDEN.findIndex((paso) => snapshot.matches(paso))
  return {
    indice: actual + 1,
    total: ORDEN.length,
    porcentaje: actual < 0 ? 100 : Math.round((actual / ORDEN.length) * 100),
    puedeVolver: snapshot.can({ type: 'ATRAS' }),
  }
}

El número reaparece, pero invertido: ahora es una salida del modelo y no su fuente de verdad. Esa inversión es exactamente la diferencia entre un asistente que se puede reordenar en una tarde y uno que nadie se atreve a tocar. Y fíjate en la última línea: preguntarle a la máquina si admite un evento evita que el componente reimplemente la regla de cuándo se puede retroceder, que es la primera regla que se desincroniza cuando aparecen las ramas condicionales.