Build: A Dashboard Meera Can Use

The whole file after this topic. If yours differs, you can copy this one and carry on.

// Writes the words for a chart from its data, so the words can never disagree with the picture. Also speaks short messages to screen readers.
import { formatDay, formatNumber } from "../utils/format.js";

let counter = 0; // makes each description paragraph's id different

/** Say something to a screen reader without moving focus. One polite live region for the whole page, made on first use. */
export function announce(text) {
  let region = document.getElementById("announcer");
  if (!region) {
    region = document.createElement("div");
    region.id = "announcer";
    region.setAttribute("role", "status"); // role=status is a polite live region
    region.style.cssText = "position:absolute;width:1px;height:1px;overflow:hidden;clip-path:inset(50%);white-space:nowrap";
    document.body.append(region);
  }
  region.textContent = ""; // clear first: the same sentence twice in a row is only spoken if the text really changes
  setTimeout(() => { region.textContent = text; }, 100);
}

/**
 * Give a chart (an <svg> or a <canvas>) its short name and its longer description.
 * The name goes in aria-label. The description becomes a visible paragraph under the chart, joined with aria-describedby.
 * Call it again after every update: the paragraph is changed in place, so the words follow the data.
 */
export function labelChart(node, { name, text }) {
  let note = node.nextElementSibling;
  if (!note || !note.classList.contains("desc")) {
    note = document.createElement("p");
    note.className = "desc";
    note.id = "desc-" + ++counter;
    node.after(note);
  }
  note.textContent = text; // text only, never markup
  node.setAttribute("aria-label", name);
  node.setAttribute("aria-describedby", note.id);
  if (node.tagName === "CANVAS") node.textContent = name + ". " + text; // what a browser without canvas support shows
}

const plural = (n, one, many) => formatNumber(n) + " " + (n === 1 ? one : many);

/** rows: [{ date, rides }]. notes: { "2025-08-14": "App down" }, a word for a day people will ask about. */
export function describeRides(rows, notes = {}) {
  const name = "Line chart of rides per day";
  const days = rows.filter((d) => Number.isFinite(d.rides)).sort((a, b) => a.date - b.date);
  if (days.length === 0) return { name: name + ": no data", text: "There are no rides to show." };
  const first = days[0], last = days[days.length - 1];
  const gaps = rows.length - days.length; // rows with no usable number: the line shows a gap there
  const gapText = gaps > 0 ? " (" + plural(gaps, "day has", "days have") + " no number and show" + (gaps === 1 ? "s" : "") + " as a gap)" : "";
  if (days.length === 1) return { name, text: "One day with a number: " + formatDay(first.date) + ", " + plural(first.rides, "ride", "rides") + gapText + "." };
  const high = days.reduce((a, b) => (b.rides > a.rides ? b : a));
  const low = days.reduce((a, b) => (b.rides < a.rides ? b : a));
  const word = notes[low.date.toISOString().slice(0, 10)];
  let text = plural(rows.length, "day", "days") + ", from " + formatDay(first.date) + " to " + formatDay(last.date) + gapText + ". ";
  if (high.rides === low.rides) text += "Every day had " + plural(high.rides, "ride", "rides") + ".";
  else {
    text += "It starts at " + formatNumber(first.rides) + " rides, peaks at " + formatNumber(high.rides) + " on " + formatDay(high.date) +
      " and ends at " + formatNumber(last.rides) + ". The quietest day is " + formatDay(low.date) + ", with " + formatNumber(low.rides) +
      " rides" + (word ? " (" + word.toLowerCase() + ")" : "") + ".";
  }
  return { name, text };
}

/** rows: [{ name, rides }], any order. label: the chart's subject, for example "Rides per station". */
export function describeBars(rows, subject) {
  const sorted = rows.filter((d) => Number.isFinite(d.rides)).sort((a, b) => b.rides - a.rides);
  const name = subject + ", bar chart";
  if (sorted.length === 0) return { name: name + ": no data", text: "No stations had any rides in this period." };
  const top = sorted[0], bottom = sorted[sorted.length - 1];
  const total = sorted.reduce((sum, d) => sum + d.rides, 0);
  let text = plural(sorted.length, "station", "stations") + ", " + plural(total, "ride", "rides") + " in all. ";
  if (top.rides === bottom.rides) text += "Every station had " + formatNumber(top.rides) + ".";
  else {
    text += top.name + " is busiest with " + formatNumber(top.rides) + " and " + bottom.name + " is quietest with " + formatNumber(bottom.rides) + ".";
    if (sorted.length >= 4) text += " Next after " + top.name + ": " + sorted.slice(1, 3).map((d) => d.name + " " + formatNumber(d.rides)).join(", ") + ".";
  }
  return { name, text };
}

/** months: [{ month, total }]; districts: [{ name, total }]. Both are the sums the chart draws. */
export function describeStacked(months, districts) {
  const name = "Stacked bar chart of rides per month by district";
  const total = months.reduce((sum, d) => sum + d.total, 0);
  if (total === 0) return { name: name + ": no data", text: "There are no rides to show." };
  const busy = months.reduce((a, b) => (b.total > a.total ? b : a));
  const quiet = months.reduce((a, b) => (b.total < a.total ? b : a));
  const lead = districts.reduce((a, b) => (b.total > a.total ? b : a));
  return {
    name,
    text: plural(total, "ride", "rides") + " in " + plural(months.length, "month", "months") + ". The busiest month is " + busy.month + " with " + formatNumber(busy.total) +
      " and the quietest is " + quiet.month + " with " + formatNumber(quiet.total) + ". " + lead.name + " carried the most, " +
      Math.round((lead.total / total) * 100) + " percent of all rides.",
  };
}

/** cells: [{ day, hour, rides }]. */
export function describeHeatmap(cells) {
  const name = "Heatmap of rides per hour in June, days down and hours across";
  const total = cells.reduce((sum, d) => sum + d.rides, 0);
  if (cells.length === 0 || total === 0) return { name: name + ": no data", text: "There are no rides to show." };
  const byHour = new Map();
  for (const d of cells) byHour.set(d.hour, (byHour.get(d.hour) ?? 0) + d.rides);
  const [hour, hourTotal] = [...byHour].reduce((a, b) => (b[1] > a[1] ? b : a));
  const hot = cells.reduce((a, b) => (b.rides > a.rides ? b : a));
  const at = (h) => String(h).padStart(2, "0") + ":00";
  return {
    name,
    text: "Across the month the busiest hour of the day is " + at(hour) + ", with " + formatNumber(hourTotal) + " rides. The single busiest hour was " +
      at(hot.hour) + " on " + hot.day + " June, with " + formatNumber(hot.rides) + " rides.",
  };
}

/** For the station map: stations is [{ name, district, docks }]. */
export function describeStations(stations) {
  const name = "Map of the bike stations";
  if (stations.length === 0) return { name: name + ": no data", text: "There are no stations to show." };
  const districts = new Set(stations.map((s) => s.district));
  const big = stations.reduce((a, b) => (b.docks > a.docks ? b : a));
  return {
    name,
    text: plural(stations.length, "station", "stations") + " in " + plural(districts.size, "district", "districts") + ". Circle size shows docks: " + big.name + " is the biggest with " + formatNumber(big.docks) +
      ". The table lists every station. Dots from the rides layer sit near their station: they show how many rides start there, not where on the street.",
  };
}

/** For the fleet treemap: bikes is the total, districts is [{ name, bikes }], count the number of stations. */
export function describeFleet(bikes, districts, count) {
  const name = "Treemap of the fleet by district and station";
  if (!(bikes > 0)) return { name: name + ": no data", text: "There are no bikes in the fleet data." };
  const lead = districts.reduce((a, b) => (b.bikes > a.bikes ? b : a));
  return { name, text: plural(bikes, "bike", "bikes") + " in " + plural(districts.length, "district", "districts") + " and " + plural(count, "station", "stations") + ". Area shows bikes. " + lead.name + " has the most, " + formatNumber(lead.bikes) + "." };
}