Build: The Trips Canvas

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

setupCanvas

Our helper in src/utils/canvas.js: sizes the grid for the screen, sets the box, scales the context once and returns it.

jitter

A small repeatable offset that spreads dots of the same station apart.

table twin

The same numbers as a real HTML table next to the canvas.

empty state

What the chart shows when there are no trips: a sentence, not a blank box.

1. 1

   Empty the data

   In startTrips, replace trips by [] in the drawTripsCanvas call. The canvas says No trips to show., its label says the same, and the table is empty.

2. 2

   Send a trip from an unknown station

   Add { id: "T0", start_station: "S99" } to the trips. The console warns 1 trip(s) were left out: their start station is not in the stations list. and the picture is unchanged.

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

// Makes a canvas sharp on every screen: the pixel grid is as big as the screen's real pixels, and the box on the page keeps its CSS size.
const MAX_RATIO = 3; // a ratio above 3 only costs memory: no phone screen needs more

/**
 * Sizes a canvas to cssWidth x cssHeight CSS pixels and returns its 2D context, already scaled so you draw in CSS pixels.
 * Setting width or height erases the canvas, so call this again after every resize, and draw again.
 */
export function setupCanvas(canvas, cssWidth, cssHeight, ratio = window.devicePixelRatio) {
  if (!(cssWidth > 0) || !(cssHeight > 0)) {
    throw new Error("setupCanvas needs a width and a height above 0, but got " + cssWidth + " x " + cssHeight + ".");
  }
  const r = Math.min(Math.max(Number.isFinite(ratio) ? ratio : 1, 1), MAX_RATIO);
  canvas.width = Math.round(cssWidth * r); // the pixel grid, in device pixels
  canvas.height = Math.round(cssHeight * r);
  canvas.style.width = cssWidth + "px"; // the box on the page, in CSS pixels
  canvas.style.height = cssHeight + "px";
  const ctx = canvas.getContext("2d");
  if (!ctx) throw new Error("This browser could not give a 2D drawing context for the canvas.");
  // Use the real ratio of the rounded grid, so a fractional device ratio still fills the box exactly
  ctx.setTransform(canvas.width / cssWidth, 0, 0, canvas.height / cssHeight, 0, 0);
  return ctx;
}

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

1. 1

   Arjun's need is met. All 10,000 trips are on the page as one picture, and it appears at once because the canvas holds one element, not 10,000. On a phone it is sharp, because setupCanvas makes the grid as big as the screen's pixels.

2. 2

   Starting point: the Phase 10 dashboard. You have lumen-dashboard/ with everything from Phases 4 to 10: the loaders (loadStations, loadTrips), the crosshair, brush and presets, the keyed transitions, the themes (theme.css, charts.css, the theme button) and onResize. Three files change: src/utils/canvas.js is new, src/charts/trips-canvas.js is new, and src/main.js keeps all of that and gains one box and startTrips(). index.html does not change, because the box is added by addBox.

3. 3

   Themed and responsive. A canvas ignores var(), so trips-canvas.js reads --chart-accent, --chart-ink and --chart-muted with getComputedStyle at every draw. main.js draws again after every theme change and onResize calls resize(width).

4. 4

   The checks inside the chart. Trips whose station is not in the list are skipped with a console warning. With no trips the canvas says No trips to show. in pixels and in its label. The summary names the busiest start station (Quay, 623 trips) and every station appears in the table twin. setupCanvas throws a clear error for a zero size and for a missing context.

5. 5

   What the dashboard can do now that it could not before: draw ten thousand marks without slowing the page, stay sharp on high-resolution screens, and describe a picture in words and in a table. Still missing: you cannot click or hover a dot (Phase 12 adds hit-testing), the cloud does not sit on a real map of Ardenvale (Phase 13), a full year of trips needs aggregation (Phase 12), and the table twin is basic (Phase 15).

• My project has canvas.js, trips-canvas.js and the new main.js.

• The page shows the dot clouds, the three names and the table twin.

• I made the trips file fail on purpose and saw only this box change.

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