Ir al contenido

Estado en vivo (modo seguimiento)

Un diagrama normalmente explica un proceso. En modo seguimiento muestra dónde está algo real ahora mismo: un pedido en camino, un domicilio, un ticket de soporte, una postulación a un empleo, un trámite. Tu sitio ya conoce el estado; Fluxygram lo convierte en una imagen animada que tus clientes entienden de un vistazo.

Dibujas el proceso una vez, como un diagrama flow normal. Después, en cada página, le dices al componente cuál bloque es la etapa actual:

<script type="module" src="https://cdn.jsdelivr.net/npm/fluxygram@0.3"></script>
<fluxy-gram src="pedido.flux.json" mode="tracker" stage="shipped"></fluxy-gram>

Eso es todo. Cuando cambia la etapa, cambias el atributo y el diagrama se anima solo hasta la etapa nueva.

Parte del diagrama Cómo se ve
Etapas ya cumplidas Verdes, con un check
La etapa actual Según status (abajo), y una partícula llega hasta ella
Etapas que faltan Atenuadas: se ve el camino completo, pero destaca lo recorrido
Barra de pasos, reproducción automática Ocultas: un seguimiento muestra el estado y nada más

El status de la etapa actual dice cómo va:

status Significa Úsalo para
pending (por defecto) En curso Casi siempre
success Terminado (verde) La última etapa, cuando el proceso acaba
warning Requiere atención (ámbar) Un retraso, esperando al cliente
error Algo salió mal (rojo) Un pago rechazado, una solicitud negada

Cualquiera de estas anima el diagrama:

const seguimiento = document.querySelector('fluxy-gram');
seguimiento.stage = 'out'; // propiedad
seguimiento.setAttribute('stage', 'out'); // atributo
seguimiento.setStage('out', 'warning'); // etapa y estado en una sola animación
seguimiento.setStage('delivered', 'success'); // el final

Prefiere setStage() cuando cambian los dos: asignar stage y status por separado también funciona (se agrupan), pero setStage() dice lo que quieres.

Cada cambio dispara fluxy-stage, útil para actualizar textos junto al diagrama:

seguimiento.addEventListener('fluxy-stage', (e) => {
const { stage, status, history } = e.detail;
document.querySelector('#llegada').hidden = stage === 'delivered';
});
  1. Usa un flow, un bloque por etapa, conectados en el orden en que pasan las cosas. Pon kind: "start" y kind: "end" en el primer y el último bloque.

  2. Usa como ids los valores de estado de tu sistema. Si tu base de datos dice shipped, el id del bloque es shipped. Los ids son el contrato entre tu aplicación y el diagrama; los nombres visibles pueden cambiar, reescribirse o traducirse libremente.

  3. Escribe los nombres para el cliente, no para tu equipo: “En camino” en vez de “OUT_FOR_DELIVERY”. Un description agrega una segunda línea corta (“te devolvemos todo”).

  4. Dale a cada fallo su propio bloque, conectado desde la etapa donde puede ocurrir: received → declined. Así, stage="declined" status="error" pone esa rama en rojo.

  5. Agrega steps solo si también quieres que el diagrama explique el proceso en otra parte: el modo seguimiento los ignora, así que el mismo archivo sirve para las dos cosas.

{
"type": "flow",
"title": "Tu pedido",
"nodes": [
{ "id": "received", "label": "Pedido recibido", "kind": "start", "icon": "cart" },
{ "id": "paid", "label": "Pago confirmado", "icon": "card" },
{ "id": "declined", "label": "Pago rechazado", "description": "prueba otra tarjeta", "icon": "alert" },
{ "id": "shipped", "label": "Enviado", "icon": "truck" },
{ "id": "delivered", "label": "Entregado", "kind": "end", "icon": "home" }
],
"edges": [
{ "from": "received", "to": "paid" },
{ "from": "received", "to": "declined" },
{ "from": "paid", "to": "shipped" },
{ "from": "shipped", "to": "delivered" }
]
}

Por defecto, Fluxygram deduce qué está cumplido siguiendo las conexiones hacia atrás desde la etapa actual. Para una línea recta con ramas de fallo es perfecto, y solo necesitas stage.

Hay dos casos en los que no puede adivinar:

  • Caminos que se juntan. En una postulación, No seleccionado puede venir después de la Revisión de hoja de vida o después de la Entrevista. Siguiendo las conexiones hacia atrás, las dos parecen cumplidas.
  • Ciclos. Un ticket de soporte va Trabajando en ello → Esperando tu respuesta → Trabajando en ello otra vez.

Para esos, pasa en history las etapas por las que realmente pasó, en orden. Solo esas quedan en verde, y solo las conexiones entre etapas seguidas:

<fluxy-gram src="postulacion.flux.json" mode="tracker"
stage="rejected" status="error"
history="applied,screening,interview,rejected"></fluxy-gram>
seguimiento.history = ['open', 'assigned', 'working', 'waiting', 'working'];
seguimiento.setStage('working');

La mayoría de los sistemas ya guardan esto (el registro de estados de un pedido, la línea de tiempo de un ticket). La etapa actual puede ser el último elemento de history o no: funciona de las dos formas.

Fluxygram no consulta nada por su cuenta: tu página decide de dónde sale el estado. Tres formas comunes, de la más simple a la más en vivo:

Tu servidor ya conoce el pedido cuando arma la página. Escribe la etapa en el HTML y listo; el cliente ve el último estado cada vez que la abre.

// React, Next.js, Remix, Astro…
<fluxy-gram src="/pedido.flux.json" mode="tracker" stage={pedido.estado} />
<fluxy-gram src="/pedido.flux.json" mode="tracker" stage="<?= htmlspecialchars($pedido->estado) ?>"></fluxy-gram>

Para una página que se queda abierta (un domicilio en camino), pide el estado a tu API cada 30 segundos o algo así. Si nada cambió, nada se anima.

const seguimiento = document.querySelector('fluxy-gram');
async function actualizar() {
const res = await fetch(`/api/pedidos/${idPedido}`);
const pedido = await res.json();
seguimiento.setStage(pedido.estado, pedido.estado === 'delivered' ? 'success' : 'pending');
}
actualizar();
setInterval(actualizar, 30_000);

Si tu backend puede enviar eventos (Server-Sent Events, WebSockets, Firebase, Supabase Realtime, Pusher…), llama a setStage() cuando llegue uno:

const eventos = new EventSource(`/api/pedidos/${idPedido}/eventos`);
eventos.onmessage = (e) => {
const { estado, historial } = JSON.parse(e.data);
seguimiento.history = historial;
seguimiento.setStage(estado);
};

Tradúcelos en un solo lugar. Ahí también decides qué estado significa un retraso o un problema:

const ETAPAS = {
PENDIENTE_PAGO: ['received', 'pending'],
PAGO_FALLIDO: ['declined', 'error'],
ALISTANDO: ['packed', 'pending'],
TRANSPORTADORA_RETRASADA: ['shipped', 'warning'],
ENTREGADO: ['delivered', 'success'],
};
const [etapa, estado] = ETAPAS[pedido.estado] ?? [undefined, 'pending'];
if (etapa) seguimiento.setStage(etapa, estado);

caption muestra una línea corta debajo del diagrama, para lo que la imagen no dice: una fecha, un número de guía, qué hacer después.

<fluxy-gram src="pedido.flux.json" mode="tracker" stage="out" caption="Llega hoy antes de las 6 pm"></fluxy-gram>

Cámbiala como cualquier atributo: seguimiento.setAttribute('caption', 'Retrasado por la transportadora: llega mañana').

Mantén los mismos ids en todos los idiomas y traduce solo los nombres: un archivo por idioma (pedido.en.flux.json, pedido.es.flux.json), y elige el archivo según el idioma del cliente. Tu código sigue enviando los mismos valores de stage. Pon lang para que los textos propios del componente también coincidan.

<fluxy-gram src="/pedido.es.flux.json" lang="es" mode="tracker" stage="shipped"></fluxy-gram>

Cada <fluxy-gram> es independiente: una lista de pedidos puede mostrar un seguimiento por pedido, todos con el mismo src. El archivo se carga una vez por elemento; es pequeño y el navegador lo guarda en caché.

<fluxy-gram src="/pedido.flux.json" mode="tracker" stage="paid"></fluxy-gram>
<fluxy-gram src="/pedido.flux.json" mode="tracker" stage="delivered" status="success"></fluxy-gram>

Cualquier cosa con etapas que alguien espera:

  • Tiendas: pedido, devolución, reembolso, reparación, producto hecho a la medida.
  • Entregas: comida, mercado, paquetes, trasteos.
  • Servicios: tickets de soporte, reclamaciones de seguros, garantías, taller del carro.
  • Trámites: visa, licencia, préstamo, apertura de cuenta, matrícula.
  • Personas: postulaciones, onboarding, citas médicas (“triaje → médico → resultados”).
  • Equipos: un despliegue, la aprobación de un contenido, una solicitud de compra.

¿Y si stage es un bloque que no existe? El diagrama se ve neutro, como si el proceso no hubiera empezado. Nunca se rompe; revisa el id si esperabas otra cosa.

¿Necesita cuenta o servidor? No. El modo seguimiento funciona completo en la página, con el componente gratuito y de código abierto. Fluxygram Cloud sumará seguimientos alojados que se actualizan solos desde tu backend, con un link para compartir por pedido.

¿Puedo volver a una etapa anterior? Sí, asígnala. Sin history, todo lo anterior vuelve a quedar en verde; con history, muestra exactamente el camino que pasas.

¿Se puede seguir arrastrando y haciendo zoom? Sí: arrastrar, hacer zoom y hacer clic en un bloque funcionan como en cualquier diagrama.

¿La lógica está disponible fuera del navegador? Sí: @fluxygram/core exporta trackerState(layout, stage, status, history), que devuelve qué bloques están cumplidos, cuál es el actual y cuáles quedan atenuados. Sirve para pruebas o para tu propio renderizador.