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.
La idea en 30 segundos
Sección titulada «La idea en 30 segundos»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.
Lo que ve el cliente
Sección titulada «Lo que ve el cliente»| 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 |
Cambiar la etapa
Sección titulada «Cambiar la etapa»Cualquiera de estas anima el diagrama:
const seguimiento = document.querySelector('fluxy-gram');
seguimiento.stage = 'out'; // propiedadseguimiento.setAttribute('stage', 'out'); // atributoseguimiento.setStage('out', 'warning'); // etapa y estado en una sola animaciónseguimiento.setStage('delivered', 'success'); // el finalPrefiere 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';});Cómo diseñar el diagrama
Sección titulada «Cómo diseñar el diagrama»-
Usa un
flow, un bloque por etapa, conectados en el orden en que pasan las cosas. Ponkind: "start"ykind: "end"en el primer y el último bloque. -
Usa como ids los valores de estado de tu sistema. Si tu base de datos dice
shipped, el id del bloque esshipped. Los ids son el contrato entre tu aplicación y el diagrama; los nombres visibles pueden cambiar, reescribirse o traducirse libremente. -
Escribe los nombres para el cliente, no para tu equipo: “En camino” en vez de “OUT_FOR_DELIVERY”. Un
descriptionagrega una segunda línea corta (“te devolvemos todo”). -
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. -
Agrega
stepssolo 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" } ]}Ramas y ciclos: history
Sección titulada «Ramas y ciclos: history»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.
Conectarlo a tus datos
Sección titulada «Conectarlo a tus datos»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:
1. Con la página
Sección titulada «1. Con la página»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>2. Consultando cada cierto tiempo
Sección titulada «2. Consultando cada cierto tiempo»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);3. En tiempo real
Sección titulada «3. En tiempo real»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);};¿Tus estados no coinciden con los bloques?
Sección titulada «¿Tus estados no coinciden con los bloques?»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);Una frase debajo del diagrama
Sección titulada «Una frase debajo del diagrama»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').
Traducciones
Sección titulada «Traducciones»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>Varios en una página
Sección titulada «Varios en una página»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.
Preguntas
Sección titulada «Preguntas»¿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.