Build: A Station Bar Chart That Updates

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

chart module

A file that exports one function, such as drawStationsBar, which draws a chart into a container and returns its controls.

update function

A function returned by the chart. Calling it with new rows changes the chart to match them.

container

The page element the chart is drawn into.

shared maximum

One number that every update uses for the full-length bar, so bars from different months can be compared.

guard

A check at the entrance of a function that keeps bad data out (a row with no number).

1. 1

   Show only the top ten

   In forMonth add .sort((a, b) => b.rides - a.rides).slice(0, 10) before the map. Switching month now moves stations in and out of the top ten: that is real enter and exit, driven by rank, and a clear reason to key by station id.

2. 2

   Ask for a wrong month

   In the second example add "Smarch" to the end of the MONTHS list and pick it in the selector. byMonth.get returns undefined, the ?? [] makes it an empty list, and the box shows "No stations had any rides in this period." (zero rows, aria-label Rides per station: no data). Take it out again afterwards.

3. 3

   Remove the shared maximum

   Delete { max: d3.max(rows, (d) => d.rides) } from the drawStationsBar call. Every month now stretches its own top bar to full width: January's Quay (2,994) looks as long as July's Lantern (7,260). The picture is tidy and misleading.

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

// A horizontal bar chart of stations, busiest at the top. It never loads data and never decides which month to show:
// the caller hands it rows, and calls update() again with new rows. Each row: { id, name, rides }.
import * as d3 from "d3";
import { formatNumber } from "../utils/format.js";

const MARGIN = { top: 4, right: 56, bottom: 4, left: 92 }; // room for the names on the left and the numbers on the right

/**
 * drawStationsBar(container, data, options) -> { update(data) }
 * options: width (default 420), rowHeight (20), max (the number that gets a full-length bar; default: the biggest row),
 *          label (the start of the screen-reader text).
 */
export function drawStationsBar(container, data, options = {}) {
  const { width = 420, rowHeight = 20, max, label = "Rides per station" } = options;
  const innerWidth = width - MARGIN.left - MARGIN.right;

  const root = d3.select(container);
  const svg = root.append("svg").attr("role", "img").style("width", "100%").style("max-width", width + "px").style("height", "auto");
  const empty = root.append("p").attr("role", "status").style("margin", "0").style("color", "#5b6b78");

  function update(rows) {
    // 1. Look after the data first. A row without a usable number would put NaN in an attribute.
    const usable = rows.filter((d) => Number.isFinite(d.rides));
    if (usable.length < rows.length) console.warn(rows.length - usable.length + " row(s) without a rides number were left out");
    const sorted = [...usable].sort((a, b) => d3.descending(a.rides, b.rides)); // a copy: never reorder the caller's array

    // 2. The number that gets a full-length bar. An empty or all-zero list must not divide by zero.
    const most = max ?? d3.max(sorted, (d) => d.rides) ?? 0;
    const length = (rides) => (most > 0 ? Math.min(rides / most, 1) * innerWidth : 0);

    // 3. The box: as tall as the number of rows, and a sentence when there is nothing to draw.
    const height = MARGIN.top + MARGIN.bottom + rowHeight * sorted.length;
    svg.attr("viewBox", "0 0 " + width + " " + Math.max(height, 1));
    svg.style("display", sorted.length === 0 ? "none" : null);
    empty.text(sorted.length === 0 ? "No stations had any rides in this period." : "");
    const shown = sorted.length + (sorted.length === 1 ? " station" : " stations") + " shown";
    svg.attr("aria-label", sorted.length === 0 ? label + ": no data" : sorted[0].rides > 0 ? label + ": " + sorted[0].name + " is busiest with " + formatNumber(sorted[0].rides) + ". " + shown + "." : label + ": " + shown + ", none with any rides.");

    // 4. The data join, keyed by station id: a station keeps its own <g> from one update to the next.
    const rowsSel = svg
      .selectAll("g.row")
      .data(sorted, (d) => d.id)
      .join((enter) => {
        const g = enter.append("g").attr("class", "row");
        g.append("rect").attr("x", 0).attr("height", rowHeight - 4).attr("rx", 2).attr("fill", "#2a9d8f");
        g.append("text").attr("class", "name").attr("x", -6).attr("y", (rowHeight - 4) / 2).attr("dy", "0.35em").attr("text-anchor", "end").attr("font-size", 12).attr("fill", "#1d2b36");
        g.append("text").attr("class", "value").attr("y", (rowHeight - 4) / 2).attr("dy", "0.35em").attr("font-size", 12).attr("fill", "#5b6b78");
        return g;
      })
      .attr("transform", (d, i) => "translate(" + MARGIN.left + "," + (MARGIN.top + i * rowHeight) + ")");

    // 5. Enter rows and kept rows are both in rowsSel, so one block sets what depends on the data.
    // select() passes each row's datum down to its children.
    rowsSel.select("rect").attr("width", (d) => length(d.rides));
    rowsSel.select("text.name").text((d) => d.name);
    rowsSel.select("text.value").attr("x", (d) => length(d.rides) + 6).text((d) => formatNumber(d.rides));
  }

  update(data);
  return { update };
}

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

1. 1

   The need is met. Arjun's chart no longer breaks when the data changes. drawStationsBar(container, data, options) draws once and returns { update(data) }. Priya picks May instead of July, the main file calls update with May's rows, and the join does the rest: Windmill and the three other May stations enter (they had no rides before 10 May), and in April they exit again.

2. 2

   How it plugs in. The project from Phase 4 gets four changes. src/charts/stations-bar.js is new and holds the chart. src/data/load.js gains loadStationMonth() for station-month.csv. src/main.js starts the stations chart in its own function, with its own loading and error text, so a problem there never hides the key numbers. index.html gets a new #stations-bar box. The hand-made "running low" bars from Phase 2 move into their own box, #status, because they answer a different question (bikes now, not rides last month) and still wait for live data.

3. 3

   Design choices to notice. The chart never loads data and never picks the month: the caller does (so Phase 8 can drive it from another chart). A copy of the rows is sorted, never the caller's array. Rows without a finite number are skipped with a console warning, so NaN cannot reach an attribute. Bar length uses one shared maximum across all months, so a bar in January and one in July mean the same number of rides. The aria-label is rebuilt on every update, so a screen reader hears the current month's story (Phase 15 goes further).

4. 4

   What the dashboard can do now that it could not before: show any month's 21 or 25 stations ranked with their numbers, update without redrawing, say "No stations had any rides in this period" when a month is empty, and survive a missing station-month.csv with a message inside the box while the key numbers stay.

5. 5

   What is still missing. The bars jump: they change place at once, which is hard to follow (Phase 9 adds transitions, and the keys are what make that possible). Bar lengths are hand arithmetic (rides ÷ max × width): Phase 6 replaces it with D3 scales and adds axes. No tooltips or highlighting yet (Phase 8). Colours, fonts and the narrow-screen layout are plain (Phase 10). The "running low" chart is still hand-drawn, until the live status feed is drawn from data later in the course.

• ↔

  Keeping chart code in one function that returns update is simple. A class or component adds more structure (destroy, resize) that you need when charts come and go (Phase 14).

• I can write a chart module that returns { update }.

• I can say what enters, updates and exits when the month changes.

• I handled empty, one-row and broken rows inside the chart.

• I can explain the shared maximum.