Enviar eventos desde la UI: send, payload y por qué la vista solo avisa

En la interfaz clásica, el handler de un botón hace cosas: valida, decide, muta estado, quizá dispara un efecto. Con una máquina, el handler hace una sola cosa —enviar un evento— y renuncia a decidir qué ocurre después. send({ type: "GUARDAR" }) no es una orden, es un aviso: “el usuario pulsó guardar”. Si la máquina está en un estado que acepta GUARDAR, transicionará; si no, el evento se ignora sin ruido. Esta renuncia deliberada de la vista a decidir es lo que convierte una UI en una proyección fiel de la máquina, y es también lo que la hace trivial de razonar: toda la lógica de qué-lleva-a-qué vive en un solo lugar, no repartida por cuarenta manejadores.

El handler solo avisa

XState v5 exige que los eventos sean objetos con una propiedad type: se acabó el send("GUARDAR") de string suelto de v4, porque el objeto habilita el tipado estricto del payload. Un handler idiomático es una línea. No comprueba en qué estado está la máquina para decidir si puede guardar —eso es competencia de la máquina—; simplemente traduce el gesto del usuario a un evento y lo empuja al buzón del actor.

export function Editor() {
  const [state, send] = useMachine(maquinaFormulario);

  return (
    <form onSubmit={(e) => { e.preventDefault(); send({ type: "GUARDAR" }); }}>
      <button type="submit">Guardar</button>
      <button type="button" onClick={() => send({ type: "CANCELAR" })}>Cancelar</button>
    </form>
  );
}

Nombrar bien los eventos es media arquitectura. Un evento describe un hecho ocurrido —ENVIO_FORMULARIO, LLEGO_RESPUESTA, EXPIRO_SESION—, no una orden imperativa a la máquina —irAGuardando, mostrarError—. La diferencia no es cosmética: si el evento nombra el hecho, la misma señal puede provocar transiciones distintas según el estado, que es justo lo que un statechart hace bien y una maraña de if hace mal. Un CLIC_GUARDAR desde editando guarda; desde guardando no hace nada; desde fallo reintenta. Un único evento, tres respuestas, todas decididas por la máquina y ninguna por la vista.

Nótese la dirección del flujo: el gesto entra como evento, la máquina transiciona, el nuevo snapshot sale hacia la vista y la vista se repinta. Nunca al revés. Ese lazo cerrado y unidireccional —la vista avisa, la máquina decide, la vista refleja— es el mismo que impondrá Redux más adelante en el track, pero aquí lo obtienes de balde por el simple hecho de usar una máquina en lugar de un puñado de manejadores sueltos.

Eventos con payload

Los eventos rara vez son señales vacías; suelen llevar datos: el texto de un input, el id de un elemento, las coordenadas de un click. El payload viaja como propiedades adicionales del objeto de evento, y la máquina lo recoge en assign mediante ({ event }) => event.valor. El tipado que declaraste en setup({ types: { events } }) obliga a que el payload enviado y el leído coincidan, de modo que un evento mal formado es un error de compilación, no de ejecución.

// La vista envía el dato como parte del evento
<input
  value={state.context.texto}
  onChange={(e) => send({ type: "ESCRIBIR", valor: e.target.value })}
/>

// La maquina declara el evento con payload y lo recoge con assign
events: {} as { type: "ESCRIBIR"; valor: string } | { type: "GUARDAR" },
// ...
editando: {
  on: {
    ESCRIBIR: { actions: assign({ texto: ({ event }) => event.valor }) },
    GUARDAR: "guardando",
  },
},

Este patrón hace del input un componente controlado por la máquina: su value sale de state.context.texto y su onChange reporta el cambio como evento. La máquina es la única fuente de verdad del texto; la vista lo muestra y avisa de las ediciones, pero no lo custodia. Una disciplina útil sobre el payload: transporta el dato mínimo que la máquina no puede deducir por sí sola —el texto tecleado, el id pulsado, el fichero soltado— y nada más. No metas en el evento estado que la máquina ya guarda en su contexto ni copies en él valores derivados, porque eso reintroduce la duplicación y la desincronización que la máquina venía a eliminar.

can: preguntar antes de ofrecer

A veces la vista sí necesita saber si una acción tiene sentido ahora —para deshabilitar un botón, atenuar un menú— sin duplicar las reglas de la máquina. Para eso está state.can({ type: "GUARDAR" }): devuelve true si, en el estado actual, ese evento produciría alguna transición o acción. La vista pregunta, no calcula; la respuesta la da la máquina a partir de sus propias reglas, así que la habilitación del botón nunca se desincroniza de lo que la máquina realmente acepta.

<button
  type="submit"
  disabled={!state.can({ type: "GUARDAR" })}
>
  Guardar
</button>

state.can es, en el fondo, una simulación pura: la máquina calcula qué ocurriría con ese evento en el snapshot actual sin ejecutar efectos ni mutar nada, y devuelve si habría cambio. Por eso llamarlo en cada render es barato, y por eso su respuesta concuerda siempre con lo que sucederá de verdad al enviar el evento: es la misma máquina contestando dos veces la misma pregunta, una para pintar el control y otra para transicionar.

No solo el usuario avisa: eventos del sistema

send desde un handler es solo una de las fuentes de eventos, y verlo así completa la imagen. Cuando la máquina invoca un actor con invoke, su resolución llega como los eventos internos onDone u onError; un bloque after convierte el paso del tiempo en un evento de expiración; un actor hijo notifica al padre con sendParent. Para la máquina todos son iguales: hechos que entran por el buzón y que ella interpreta según el estado en el que se encuentra.

flowchart LR
U[clic del usuario send] --> B[buzon del actor]
P[promesa onDone onError] --> B
T[timeout after] --> B
H[actor hijo sendParent] --> B
B --> D[la maquina decide segun el estado]

cargando: {
  invoke: {
    src: "pedirResultados",
    onDone: "listo",    // evento interno: la promesa se resolvio
    onError: "fallo",   // evento interno: la promesa fallo
  },
  after: { 8000: "fallo" },   // evento de tiempo: expiro el plazo
},

Que un timeout y un click compartan el mismo mecanismo —un evento que la máquina resuelve— es lo que mantiene uniforme la lógica de la UI. No hay un camino para las acciones del usuario y otro para los efectos del sistema: hay un solo buzón y un solo conjunto de reglas, y por eso la traza de una sesión es una simple lista de eventos que puedes registrar, reproducir y usar como test.