Build: The Ardenvale Station Map

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

// The station map: the real shapes of Ardenvale (districts, coast, river from TopoJSON) in an SVG layer, and two stacked canvases on top:
// a base layer other charts draw on (the year of rides), and a marks layer with one circle per station that handles hover, click, touch
// and the keyboard. Circle size = docks. Circle colour = bikes there now (darker = more), with a red ring when a station is running low.
import * as d3 from "d3";
import * as topojson from "topojson-client";
import { setupCanvas } from "../utils/canvas.js";
import { pointerPoint, reachFor, createHitTester } from "../utils/hit-test.js";

/** A canvas ignores var(): read the theme token from the page's CSS at every draw, and fall back when the page has none. */
export function token(name, fallback) {
  const value = getComputedStyle(document.documentElement).getPropertyValue(name).trim();
  return value || fallback;
}

const LOW = 0.35; // a station with this share of its docks filled, or less, is "running low"

/** One projection for the whole island, fitted to the coast. Returns null when there is no usable topology. */
export function fitIsland(topology, width, height, pad = 12) {
  try {
    const coast = topojson.feature(topology, topology.objects.coast);
    const projection = d3.geoMercator().fitExtent([[pad, pad], [width - pad, height - pad]], coast);
    return Number.isFinite(projection.scale()) ? projection : null;
  } catch {
    return null; // a missing or broken topology: the caller falls back to the flat projection
  }
}

/**
 * Places stations on a width x height box (the flat fallback; the real map uses fitIsland). Longitude is squeezed by cos(latitude) so the island keeps its shape.
 * Returns a Map of station id to [x, y]. Stations with a missing or non-numeric position are left out.
 */
export function projectStations(stations, width, height, pad = 32, topology = null) {
  const ok = stations.filter((s) => Number.isFinite(s.lon) && Number.isFinite(s.lat));
  const spots = new Map();
  if (ok.length === 0) return spots;
  const island = topology && fitIsland(topology, width, height);
  if (island) { // the real map: the same projection draws the land and places the stations
    for (const s of ok) spots.set(s.id, island([s.lon, s.lat]));
    return spots;
  }
  const flat = Math.cos((d3.mean(ok, (s) => s.lat) * Math.PI) / 180);
  const [x0, x1] = d3.extent(ok, (s) => s.lon * flat);
  const [y0, y1] = d3.extent(ok, (s) => s.lat);
  const k = Math.min((width - 2 * pad) / (x1 - x0 || 1), (height - 2 * pad) / (y1 - y0 || 1)); // one factor for both axes
  const left = (width - (x1 - x0) * k) / 2;
  const top = (height - (y1 - y0) * k) / 2;
  for (const s of ok) spots.set(s.id, [left + (s.lon * flat - x0) * k, height - top - (s.lat - y0) * k]);
  return spots;
}

/**
 * Draws the stations and returns { base, spot, select, selected, note, repaint, resize }.
 * options: width, height, onSelect(station or null), topology (the parsed ardenvale.topojson), status (the parsed status.json, or null). base() is the layer under the stations, { ctx, width, height }.
 * note(key, text) adds a line to the readout under the map. repaint() draws the marks again (after a theme change).
 * resize(width) rebuilds both canvases, so the caller must draw its own layer again. setStatus(status) colours the circles again.
 */
export function drawStationMap(container, stations, options = {}) {
  let width = options.width ?? 640;
  const height = options.height ?? 360;
  const onSelect = options.onSelect ?? (() => {});
  const root = d3.select(container);
  root.selectAll("*").remove();

  const stack = root.append("div").style("position", "relative");
  const land = stack.append("svg").attr("aria-hidden", "true").style("position", "absolute").style("left", 0).style("top", 0); // under both canvases
  const baseCanvas = stack.append("canvas").attr("aria-hidden", "true").node();
  const marksCanvas = stack.append("canvas").attr("tabindex", 0).attr("role", "application")
    .attr("aria-label", "Station map with " + stations.length + " stations. Use the left and right arrow keys to move between stations, and Enter to select one.")
    .style("position", "absolute").style("left", 0).style("top", 0).node();
  d3.select(baseCanvas).style("position", "relative"); // the base canvas sits above the land and below the marks
  const status = root.append("p").attr("aria-live", "polite").style("margin", "6px 0 0").style("font-size", "14px");
  const readout = root.append("p").style("margin", "2px 0 0").style("font-size", "12px").style("color", "var(--chart-muted, #5b6b78)");

  let base, ctx, spots, marks, tester, byName;
  let state = options.status ?? null; // { updated, stations: [{ id, bikes, ... }] } or null
  const bikesOf = () => new Map((state?.stations ?? []).map((s) => [s.id, s.bikes]));
  const mostBikes = () => d3.max([...bikesOf().values()]) || 1;

  function drawLand() { // districts, the borders between them (drawn once), coast and river: the same projection as the stations
    land.attr("width", width).attr("height", height).selectAll("*").remove();
    const topology = options.topology;
    const projection = topology && fitIsland(topology, width, height);
    if (!projection) return; // no shapes: the stations still show, on a plain background
    const path = d3.geoPath(projection);
    const districts = topojson.feature(topology, topology.objects.districts);
    land.selectAll("path.district").data(districts.features).join("path").attr("class", "district").attr("d", path).attr("fill", "var(--chart-bg, #eef2f4)");
    land.append("path").attr("d", path(topojson.mesh(topology, topology.objects.districts, (a, b) => a !== b))).attr("fill", "none").attr("stroke", "#fff").attr("stroke-width", 2);
    land.append("path").attr("d", path(topojson.feature(topology, topology.objects.coast))).attr("fill", "none").attr("stroke", "#9db4c0");
    land.append("path").attr("d", path(topojson.feature(topology, topology.objects.river))).attr("fill", "none").attr("stroke", "#3a86c8").attr("stroke-width", 3).attr("stroke-linecap", "round");
  }

  function layout() {
    drawLand();
    stack.style("width", width + "px").style("height", height + "px");
    base = { ctx: setupCanvas(baseCanvas, width, height), width, height };
    ctx = setupCanvas(marksCanvas, width, height);
    spots = projectStations(stations, width, height, 32, options.topology);
    const radius = d3.scaleSqrt([0, d3.max(stations, (s) => s.docks) || 1], [0, 14]);
    marks = stations
      .filter((s) => spots.has(s.id))
      .map((s) => ({ ...s, x: spots.get(s.id)[0], y: spots.get(s.id)[1], r: Math.max(radius(s.docks || 0), 3) }));
    tester = createHitTester(marks);
    byName = [...marks].sort((a, b) => a.name.localeCompare(b.name));
  }
  layout();
  if (marks.length < stations.length) console.warn((stations.length - marks.length) + " station(s) have no position and are not on the map.");

  const notes = new Map(); // key -> text, in the order the keys were first used
  function note(key, text) {
    notes.set(key, text);
    readout.text(Array.from(notes.values()).join(" | "));
  }

  let hover = null; // station ids, so a rebuild at a new width keeps them
  let chosen = null;
  const byId = (id) => marks.find((m) => m.id === id) ?? null;
  function paint() { // the marks layer is only 25 circles, so redrawing it on every hover change costs almost nothing
    const start = performance.now();
    ctx.clearRect(0, 0, width, height);
    const bikes = bikesOf();
    const shade = d3.scaleSequential([0, mostBikes()], d3.interpolateBlues);
    for (const m of marks) {
      const count = bikes.get(m.id);
      const low = count !== undefined && m.docks > 0 && count / m.docks <= LOW;
      ctx.beginPath();
      ctx.arc(m.x, m.y, m.r, 0, Math.PI * 2);
      // colour = bikes there now. No status for this station, or none at all: the theme's ink, a little see-through
      ctx.fillStyle = m.id === chosen ? token("--chart-accent", "#e76f51") : count === undefined ? token("--chart-ink", "#264653") : shade(count);
      ctx.globalAlpha = m.id === chosen || count !== undefined ? 1 : 0.6;
      ctx.fill();
      ctx.globalAlpha = 1;
      if (low) { // a red ring: running low
        ctx.lineWidth = 3;
        ctx.strokeStyle = "#d1495b";
        ctx.stroke();
      } else if (count !== undefined) {
        ctx.lineWidth = 1;
        ctx.strokeStyle = token("--chart-ink", "#1d2b36");
        ctx.stroke();
      }
      if (m.id === hover) {
        ctx.lineWidth = 2.5;
        ctx.strokeStyle = token("--chart-ink", "#1d2b36");
        ctx.stroke();
      }
    }
    note("marks", "marks layer " + (performance.now() - start).toFixed(1) + " ms");
  }
  function choose(next) {
    chosen = next ? next.id : null;
    const now = bikesOf().get(next?.id);
    status.text(next ? next.name + ", " + next.district + " district, " + next.docks + " docks" + (now === undefined ? "" : ", " + now + " bikes now") : "No station selected.");
    paint();
    onSelect(next ? stations.find((s) => s.id === next.id) : null);
  }

  marksCanvas.addEventListener("pointermove", (event) => {
    const [px, py] = pointerPoint(marksCanvas, event, width, height);
    const found = tester.find(px, py, reachFor(event)); // 8 px beyond the dot for a mouse, 24 for a finger
    const id = found ? found.id : null;
    if (id !== hover) {
      hover = id;
      marksCanvas.style.cursor = found ? "pointer" : "default";
      paint();
    }
  });
  marksCanvas.addEventListener("pointerleave", () => {
    hover = null;
    paint();
  });
  marksCanvas.addEventListener("click", (event) => {
    const [px, py] = pointerPoint(marksCanvas, event, width, height);
    choose(tester.find(px, py, reachFor(event))); // a click on empty space clears the selection
  });
  marksCanvas.addEventListener("keydown", (event) => {
    if (marks.length === 0) return;
    if (event.key === "ArrowRight" || event.key === "ArrowLeft") {
      event.preventDefault();
      const i = hover ? byName.findIndex((m) => m.id === hover) : -1;
      const step = event.key === "ArrowRight" ? 1 : -1;
      const next = i < 0 ? byName[step > 0 ? 0 : byName.length - 1] : byName[(i + step + byName.length) % byName.length];
      hover = next.id;
      status.text(next.name + ", " + next.district + " district. Press Enter to select.");
      paint();
    } else if (event.key === "Enter" && hover) {
      event.preventDefault();
      choose(byId(hover));
    }
  });

  status.text(marks.length === 0 ? "No stations to show." : "No station selected.");
  paint();
  if (!options.topology) note("shapes", "no map shapes"); else if (!fitIsland(options.topology, width, height)) note("shapes", "map shapes unusable");
  note("status", state ? "status at " + state.updated : "bike counts not available");
  return {
    base: () => base,
    note,
    spot: (id) => spots.get(id),
    select: (id) => choose(byId(id)),
    selected: () => chosen,
    repaint: paint,
    setStatus(next) { state = next ?? null; paint(); note("status", state ? "status at " + state.updated : "bike counts not available"); },
    resize(nextWidth) {
      if (!(nextWidth > 0) || nextWidth === width) return false;
      width = nextWidth;
      layout();
      paint();
      return true;
    },
  };
}