Build: The Live Operations Dashboard

New words in this topic, in plain English. Come back here whenever one feels fuzzy.

useKpis

The hook in App.jsx that fills the #kpis section with grey tiles, then real tiles.

LiveStatus

The component that starts the live feed on the #status box and stops it when the page goes away.

makeSource

The option that makes the message source. Today a simulated one, later new EventSource(url).

AbortSignal

A signal passed to the feed. Aborting it stops the feed, which React's StrictMode needs.

Message

The React component for a box's loading, empty and error states.

1. 1

   Slow the status box down

   In LiveStatus add redrawEvery: 3000 to the options of startStatusFeed. The bars now change every three seconds, however fast the simulated messages arrive.

2. 2

   Make the wrong file right

   In the example change stations-2026.csv to stations.csv. The stations box now loads (loadWrongFile returns an empty list) and shows nothing at all: a box that is ready with no content is a blank box, which this phase avoids. (The example's own log lines that read that box's message now stop with Cannot read properties of null (reading 'className'): the box has no state to read.) Give it a Message kind="empty" like the late returns box. Change the name back to see the error and Try again.

3. 3

   Pick dates, then export

   In your project, press the Summer button and then Download CSV. The file name contains the dates (lumen-rides-2025-06-01-2025-08-31.csv) and the file holds only those 92 days.

Your lumen-dashboard project after this topic. Click a file to see it in full.

// What a box shows while it waits, when it has nothing to show, and when something went wrong. Never a blank box.

/** The box with its first <h2> kept and everything else removed: the way to start a box over (a retry, or a new state). */
export function resetBox(box) {
  const keep = box.querySelector(":scope > h2");
  for (const child of [...box.children]) if (child !== keep) child.remove();
}

/** Removes the state message of a box (loading, empty or error), if it has one. */
export function clearState(box) {
  for (const old of box.querySelectorAll(":scope > .state")) old.remove();
}

/**
 * Shows one state message at the end of a box, replacing an older one. kind: "loading" (grey bars and a sentence),
 * "empty" (a sentence that says why there is nothing) or "error" (a sentence and, with onRetry, a Try again button).
 */
export function showState(box, kind, text, onRetry) {
  clearState(box);
  const area = document.createElement("div");
  area.className = "state " + kind;
  area.setAttribute("role", kind === "error" ? "alert" : "status"); // a screen reader announces the change
  if (kind === "loading") {
    for (let i = 0; i < 3; i += 1) {
      const bone = document.createElement("span");
      bone.className = "bone";
      bone.setAttribute("aria-hidden", "true"); // decoration: the sentence below says the same
      area.append(bone);
    }
  }
  const message = document.createElement("p");
  message.textContent = text; // text only: an error message that came from a server is never markup
  area.append(message);
  if (kind === "error" && onRetry) {
    const button = document.createElement("button");
    button.type = "button";
    button.textContent = "Try again";
    button.onclick = () => {
      button.disabled = true; // one click, one retry
      onRetry();
    };
    area.append(button);
  }
  box.append(area);
  return area;
}

/** The age of some data in words: "just now", "42 seconds ago", "3 minutes ago", "2 hours ago", "3 days ago". */
export function ageText(seconds) {
  if (!Number.isFinite(seconds) || seconds < 0) return "at an unknown time"; // a clock that is wrong must not print "-5 seconds ago"
  if (seconds < 5) return "just now";
  if (seconds < 60) return Math.floor(seconds) + " seconds ago";
  const minutes = Math.floor(seconds / 60);
  if (minutes < 60) return minutes + (minutes === 1 ? " minute ago" : " minutes ago");
  const hours = Math.floor(minutes / 60);
  if (hours < 24) return hours + (hours === 1 ? " hour ago" : " hours ago");
  const days = Math.floor(hours / 24);
  return days + (days === 1 ? " day ago" : " days ago");
}

/** Marks a box as showing old numbers, with their age. Pass null when the data is fresh again. */
export function setStale(box, seconds) {
  let badge = box.querySelector(":scope > .stale");
  if (seconds === null) {
    if (badge) badge.remove();
    return;
  }
  if (!badge) {
    badge = document.createElement("p");
    badge.className = "stale";
    badge.setAttribute("role", "status");
    box.append(badge);
  }
  const words = "Showing old numbers. Last update " + ageText(seconds) + ".";
  if (badge.textContent !== words) badge.textContent = words; // change the text only when the words change, so a screen reader is not interrupted every second
}

/**
 * Runs task(attempt) and tries again when it fails, waiting wait, then 2 x wait, then 4 x wait (exponential backoff).
 * A failure with an HTTP status from 400 to 499 is the caller's mistake, so it is not tried again.
 * sleep and onRetry can be replaced, which is how the tests run without waiting.
 */
export async function withRetry(task, options = {}) {
  const {
    tries = 3,
    wait = 500,
    sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
    onRetry = () => {},
    shouldRetry = (problem) => !(problem && problem.status >= 400 && problem.status < 500),
  } = options;
  let last;
  for (let attempt = 1; attempt <= tries; attempt += 1) {
    try {
      return await task(attempt);
    } catch (problem) {
      last = problem;
      if (attempt === tries || !shouldRetry(problem)) break;
      const delay = wait * 2 ** (attempt - 1);
      onRetry(attempt, delay, problem);
      await sleep(delay);
    }
  }
  throw last;
}

Errors are the best teachers. Make each change, read the error, guess what went wrong, then reveal the answer.

1. 1

   Tomás's need is met. The dashboard now runs on a wall without a person next to it: the key numbers show how the week went against the week before, the station box updates by itself, every box has a state for loading, empty, error and stale, and a failed box offers Try again while the rest keep working. People who want the numbers can download them, and the page prints cleanly.

2. 2

   Starting point: the Phase 15 dashboard. You have lumen-dashboard/ as a React app from Phase 14, with the accessible charts and table twins of Phase 15 (describe.js, table-twin.js, the changed RidesLine.jsx and StationsBar.jsx, the accessible D3 charts and charts.css). Those files do not change. Six files are new: states.js, kpi.js, live.js, export.js, production.css and tests/scales.test.js. Three change: App.jsx, main.jsx (one import) and package.json (Vitest and npm test). index.html does not change: the key numbers and the status box were already there.

3. 3

   How it plugs in. The four plain modules know nothing about React, so they are tested as they are. App.jsx calls them: useKpis fills the #kpis section (which belongs to index.html, not to React), LiveStatus hands the #status box to the live feed and stops it in its cleanup, Message is the React version of showState, and ExportBar sits under the rides line. useLoad now retries with backoff and returns a retry function for the Try again button.

4. 4

   Phase 15 is kept. The live station chart has a role="img" label that is rebuilt from the data at every draw, and a table twin that updates with it (makeTwin passes in tableTwin). The stale badge and error messages are live regions that speak politely or at once. The skeleton bars are hidden from screen readers and the sentence beside them is read.

5. 5

   The checks inside. An empty rides file shows The ride file has no days in it, so there is nothing to draw. instead of a crash. A tile without an earlier value says so, not Infinity%. A failed load is retried twice for a hiccup and not at all for a 404. Late messages are ignored, counts are clamped, and the feed stops when the page or the box goes away.

6. 6

   What the dashboard can do now that it could not before: update a box by itself, show a number's change and trend, survive one failed request, say when data is old, export the picture and the numbers, print, and run a test suite in about a second. Still missing: a real server feed (the preview and your project use a simulated one; swap makeSource for an EventSource), URL-stored filters (Topic 16.2 showed the pattern), the story page for the public (Phase 17), and the capstone steps: your own S3 bucket and publishing (Phase 18).

• ↔

  Handing the status box to plain JavaScript keeps the feed testable and framework-free, at the cost of a node React does not manage. Rewriting it as a React component would let React own it, at the cost of rewriting live.js's timers as hooks.

• ↔

  Retrying inside useLoad hides short hiccups from the reader but delays the error message by up to 1.5 seconds. For a wall display that is the right trade.

• My project has the four modules, production.css, the test file, and the changed App.jsx, main.jsx and package.json.

• The status box updates by itself, has a table twin, and stops when I leave the page.

• I made the daily file fail on purpose, saw the Try again notice, and the rest of the page kept working.

• npm test passes and npm run build finishes.

• I can say what the dashboard still lacks and which phase adds it.