@humanforest/charts 0.1.0

package/src/FDottedMap.vue

@@ -0,0 +1,335 @@
+<script setup lang="ts" generic="P extends Record<string, unknown>">
+// London as a grid of dots, coloured by how many points land in each. Third of the cell components:
+// FStatusTrack puts cells in a sequence, FCalendarGrid puts them on a date grid, this puts them on a
+// geography. Colour resolution is useCellScale's; this component owns the binning and the layout.
+//
+// It is not a map. There is no pan, no zoom and no projection at read time — a dot is roughly a
+// square kilometre and locates nothing. Real geography is Mapbox's job. This answers "where in
+// London" at a glance, with no tiles and no network.
+import { computed, ref, shallowRef, watchEffect } from 'vue';
+import { useCellScale, type SequentialRamp } from './useCellScale';
+import { CELL_SIZES, orElse, type CellSize } from './cellSize';
+import {
+  LONDON_GRID,
+  RIVER_COLOR,
+  loadLondonGrid,
+  dotAt,
+  dotKey,
+  type DotDensity,
+  type LondonGrid,
+} from './londonGrid';
+import FCellLegend from './FCellLegend.vue';
+
+interface DotInfo {
+  col: number;
+  row: number;
+  value: number;
+}
+
+const props = withDefaults(
+  defineProps<{
+    points: P[];
+    lat: (p: P) => number;
+    lng: (p: P) => number;
+    /** Summed per dot as `value(p) ?? 1`, so the default reading is a count of points. */
+    value?: (p: P) => number | null | undefined;
+    ramp?: SequentialRamp;
+    /** Intensity domain, in the caller's units. Two maps compared side by side must both set it. */
+    domain?: [number, number];
+    steps?: number;
+    /** How a dot's total is spaced along the ramp. See `spaced` below for why this exists. */
+    scale?: 'linear' | 'sqrt' | 'log';
+    /** How many dots the map is sampled into. Separate from `size`, which is how big it is drawn:
+     *  a coarse grid at lg is big dots, a fine grid at sm is a texture. Anything but the default is
+     *  fetched on use. */
+    density?: DotDensity;
+    /** Size step. Sets the dot dimensions, and whether legend and tooltips default on:
+     *  xs and sm are too small to carry chrome, so it defaults off there. Any explicit prop wins. */
+    size?: CellSize;
+    /** Forces the size step's chrome decision either way. `legend` still wins over it. */
+    chrome?: boolean;
+    dotSize?: number;
+    dotGap?: number;
+    /** Corner radius. Defaults to half the dot, which is a circle; 0 gives squares. */
+    radius?: number;
+    legend?: boolean;
+    /** Paint the Thames. Off, its cells are ordinary land — they take data and are coloured like
+     *  any other dot, rather than leaving a gap where the channel was. */
+    river?: boolean;
+    /** Hover text. Suppressed at xs and sm, where the target is too small to hit reliably. */
+    tooltip?: (info: DotInfo) => string;
+    ariaLabel?: string;
+  }>(),
+  {
+    density: 'fine',
+    size: 'md',
+    steps: 5,
+    scale: 'linear',
+    /* Vue casts an ABSENT Boolean-typed prop to false, so without these the size step could never
+       switch chrome on: `orElse` would read that false as a deliberate "off" at every size. */
+    legend: undefined,
+    chrome: undefined,
+    river: true,
+  },
+);
+
+// Three tiers, narrowest first: an individual prop beats `chrome`, which beats the size step.
+const spec = computed(() => CELL_SIZES[props.size]);
+
+// Size sets the rendered width; the dot size follows from it and the density.
+//
+// Fixing the dot in pixels made the two settings the same setting — a denser grid simply drew a
+// bigger map, so density could not be varied without resizing the chart. Deriving the dot from the
+// width means a coarse grid at lg is big dots and a fine grid at lg is small ones, both filling the
+// same frame. The widths match the London map step for step so the two sit at the same scale.
+const MAP_WIDTH: Record<CellSize, number> = { xs: 192, sm: 383, md: 575, lg: 767 };
+/** How much of each cell the dot fills; the remainder is the gap. */
+const DOT_FILL = 0.78;
+// Left fractional. Rounding the dot and the gap to whole pixels made the rendered width miss its
+// target by up to ten per cent, and differently per density — which is the coupling this was meant
+// to remove. These are path coordinates, so a fraction costs nothing.
+const pitchFor = computed(() => MAP_WIDTH[props.size] / grid.value.width);
+const dotSize = computed(() => orElse(props.dotSize, pitchFor.value * DOT_FILL));
+const dotGap = computed(() => orElse(props.dotGap, pitchFor.value * (1 - DOT_FILL)));
+const radius = computed(() => orElse(props.radius, dotSize.value / 2));
+const showChrome = computed(() => orElse(props.chrome, spec.value.chrome));
+const showLegend = computed(() => orElse(props.legend, showChrome.value));
+const interactive = computed(() => !!props.tooltip && showChrome.value);
+
+// The bundled resolution stands in while another loads, so changing density never blanks the map —
+// the silhouette is the same either way, only how finely it is sampled changes.
+const loaded = shallowRef<LondonGrid>(LONDON_GRID);
+watchEffect(() => {
+  const want = props.density;
+  void loadLondonGrid(want).then((g) => {
+    if (props.density === want) loaded.value = g;
+  });
+});
+const grid = computed(() => loaded.value);
+
+// With the river off, its cells become ordinary land rather than disappearing.
+//
+// The build step files them separately, so hiding the painting alone left a white channel through
+// the middle of the map — "do not draw the Thames" read as "cut a hole where it was". They also have
+// to rejoin the binning, or they would render as a guaranteed-zero stripe: points landing on them
+// are dropped while they count as river.
+const landDots = computed(() =>
+  props.river ? grid.value.dots : [...grid.value.dots, ...grid.value.river],
+);
+
+const land = computed(() => new Set(landDots.value.map(([c, r]) => dotKey(c, r))));
+
+// Points are summed into their dot. A point outside the boundary, or on the river, has nowhere to
+// land — those are counted rather than quietly absorbed, so a caller feeding the wrong city or the
+// wrong coordinate order can see it. The river is drawn but is not a bucket: a ride does not start
+// in the Thames, and letting one land there would put a reading on a dot that cannot have one.
+const binned = computed(() => {
+  const totals = new Map<string, number>();
+  let dropped = 0;
+  for (const p of props.points) {
+    const at = dotAt(grid.value, props.lat(p), props.lng(p));
+    const key = at && dotKey(at[0], at[1]);
+    if (!key || !land.value.has(key)) {
+      dropped++;
+      continue;
+    }
+    totals.set(key, (totals.get(key) ?? 0) + (props.value?.(p) ?? 1));
+  }
+  return { totals, dropped };
+});
+
+// Every land dot gets a cell, whether or not a point reached it.
+//
+// This is where the family's "empty is a third outcome" rule inverts, and inverting it is what keeps
+// the reading honest here. On a calendar a day with no datum might not have been measured; on a
+// density map the coverage is complete by construction, so a dot with no points means zero events
+// happened there. Colouring that as "no data" would assert something the data does not. Unhit dots
+// therefore take the ramp's low stop, and the legend carries no empty swatch.
+const cells = computed<DotInfo[]>(() =>
+  landDots.value.map(([col, row]) => ({
+    col,
+    row,
+    value: binned.value.totals.get(dotKey(col, row)) ?? 0,
+  })),
+);
+
+// How a total is spaced along the ramp.
+//
+// Density is heavy-tailed, and linearly spacing a heavy tail produces a blank map: with a typical
+// week of rides the median dot holds 1 and the busiest holds over a hundred, so five equal buckets
+// put roughly ninety per cent of the city in the palest one and the picture says nothing. Compress
+// the tail and the structure appears. Nothing is compressed by default — a transform the caller did
+// not ask for would quietly change what the ramp claims — but a density map usually wants one.
+const spaced = (v: number) =>
+  props.scale === 'sqrt' ? Math.sqrt(v) : props.scale === 'log' ? Math.log1p(v) : v;
+
+// The domain prop is in the caller's units, so it is spaced too — otherwise setting one would
+// silently mean something different from leaving it off.
+const spacedDomain = computed<[number, number] | undefined>(() =>
+  props.domain ? [spaced(props.domain[0]), spaced(props.domain[1])] : undefined,
+);
+
+const scale = useCellScale<DotInfo>({
+  mode: 'intensity',
+  ramp: computed(() => props.ramp ?? ('forest' as SequentialRamp)),
+  domain: spacedDomain,
+  steps: computed(() => props.steps),
+  data: cells,
+  value: (d) => spaced(d.value),
+});
+
+const pitch = computed(() => dotSize.value + dotGap.value);
+const width = computed(() => grid.value.width * pitch.value - dotGap.value);
+const height = computed(() => grid.value.height * pitch.value - dotGap.value);
+
+// Dots are drawn as one path per colour, not one element per dot.
+//
+// At this density a rect each means four and a half thousand nodes per map, and a page showing
+// several sizes of the same map put thirty thousand in one document — enough that the browser spends
+// its time in layout rather than paint. Grouping by fill takes that to about seven nodes, because a
+// path can hold any number of disjoint subpaths and every dot sharing a bucket also shares a fill.
+const subpath = (col: number, row: number): string => {
+  const x = col * pitch.value;
+  const y = row * pitch.value;
+  const s = dotSize.value;
+  const r = Math.min(radius.value, s / 2);
+  if (r <= 0) return `M${x},${y}h${s}v${s}h${-s}z`;
+  // A radius of half the dot is a circle, which is the default and the common case.
+  if (r >= s / 2) return `M${x},${y + r}a${r},${r} 0 1,0 ${s},0a${r},${r} 0 1,0 ${-s},0`;
+  const m = s - 2 * r;
+  return `M${x + r},${y}h${m}a${r},${r} 0 0,1 ${r},${r}v${m}a${r},${r} 0 0,1 ${-r},${r}h${-m}a${r},${r} 0 0,1 ${-r},${-r}v${-m}a${r},${r} 0 0,1 ${r},${-r}z`;
+};
+
+/** One entry per distinct fill, in ramp order so the layer list is stable across renders. */
+const layers = computed(() => {
+  const byFill = new Map<string, string[]>();
+  for (const cell of cells.value) {
+    const fill = scale.colorOf(cell);
+    const parts = byFill.get(fill);
+    if (parts) parts.push(subpath(cell.col, cell.row));
+    else byFill.set(fill, [subpath(cell.col, cell.row)]);
+  }
+  return [...byFill].map(([fill, parts]) => ({ fill, d: parts.join('') }));
+});
+
+const riverPath = computed(() =>
+  props.river ? grid.value.river.map(([c, r]) => subpath(c, r)).join('') : '',
+);
+
+/** Cells by grid position, so a pointer lands on its dot by arithmetic rather than by hit-testing. */
+const byPosition = computed(() => {
+  const m = new Map<string, DotInfo>();
+  for (const c of cells.value) m.set(dotKey(c.col, c.row), c);
+  return m;
+});
+
+const mapLabel = computed(() => {
+  if (props.ariaLabel) return props.ariaLabel;
+  // The busiest dot in the caller's units. scale.domain is in spaced units and would report a
+  // logarithm as though it were a ride count.
+  const hi = props.domain?.[1] ?? cells.value.reduce((m, c) => (c.value > m ? c.value : m), 0);
+  const placed = props.points.length - binned.value.dropped;
+  return `London, as a grid of dots shaded by density. The busiest holds ${hi.toLocaleString('en-GB')}, across ${placed.toLocaleString('en-GB')} of ${props.points.length.toLocaleString('en-GB')} points.`;
+});
+
+// Anchored to the dot rather than the pointer. Dots are not focusable and deliberately so: promoting
+// four thousand of them to buttons the way FCalendarGrid promotes 365 cells would put four thousand
+// tab stops in the page. The summary on the wrapper carries the reading for anyone not using a
+// pointer.
+// The dot has no element of its own to anchor to — it is painted into a merged path — so the
+// tooltip is given a VIRTUAL reference: floating-ui only ever asks an anchor for its bounding box,
+// and here that box is the arithmetic the hit-testing already does.
+const tip = ref<{ text: string; box: { x: number; y: number; w: number; h: number } | null }>({
+  text: '',
+  box: null,
+});
+const tipOpen = ref(false);
+const tipReference = computed(() =>
+  tip.value.box
+    ? { getBoundingClientRect: () => new DOMRect(tip.value.box!.x, tip.value.box!.y, tip.value.box!.w, tip.value.box!.h) }
+    : null,
+);
+
+// One listener on an overlay, rather than one per dot. The grid is regular, so the dot under the
+// pointer is arithmetic — which is both cheaper than four thousand hit targets and more accurate,
+// because the gaps between dots resolve to their dot instead of falling through to nothing.
+const trackPointer = (event: MouseEvent) => {
+  const box = (event.currentTarget as SVGRectElement).getBoundingClientRect();
+  // The svg is scaled to fit its container, so client pixels are converted through the viewBox
+  // rather than assumed to be user units.
+  const scaleX = width.value / box.width;
+  const col = Math.floor(((event.clientX - box.left) * scaleX) / pitch.value);
+  const row = Math.floor(((event.clientY - box.top) * (height.value / box.height)) / pitch.value);
+  const cell = byPosition.value.get(dotKey(col, row));
+  if (!cell) {
+    tipOpen.value = false;
+    return;
+  }
+  // Anchored to the dot, not the pointer: inside a 5px target a bubble that follows the cursor
+  // only jitters.
+  const scaleY = height.value / box.height;
+  tip.value = {
+    text: props.tooltip!(cell),
+    box: {
+      x: box.left + (col * pitch.value) / scaleX,
+      y: box.top + (row * pitch.value) / scaleY,
+      w: pitch.value / scaleX,
+      h: pitch.value / scaleY,
+    },
+  };
+  tipOpen.value = true;
+};
+const hideTip = () => {
+  tipOpen.value = false;
+};
+
+defineExpose({
+  /** Points that fell outside the landmass — off the grid entirely, or on the river. */
+  outOfBounds: computed(() => binned.value.dropped),
+});
+</script>
+
+<template>
+  <div class="flex w-full flex-col gap-3">
+    <div class="overflow-x-auto">
+      <!-- max-width and height are inline rather than utilities: Tailwind does not scan this
+           package, so a class used only here is never generated and the rule silently does
+           nothing. width and height stay attributes for the intrinsic size, and height:auto is
+           what keeps the aspect once max-width takes over in a container narrower than the map. -->
+      <UTooltip :text="tip.text" :reference="tipReference" :open="tipOpen">
+      <svg
+        :width="width"
+        :height="height"
+        :viewBox="`0 0 ${width} ${height}`"
+        role="img"
+        :aria-label="mapLabel"
+        class="mx-auto block"
+        style="max-width: 100%; height: auto"
+      >
+        <!-- The river first, so a land dot wins any overlap. It carries no data and takes no hover:
+             the Thames is a label on the map, not a bucket with a reading. -->
+        <path v-if="riverPath" :d="riverPath" :fill="RIVER_COLOR" />
+
+        <path v-for="layer in layers" :key="layer.fill" :d="layer.d" :fill="layer.fill" />
+
+        <!-- One transparent target over the whole grid. The dot under the pointer is computed, so
+             the map keeps its tooltip without giving every dot its own node. -->
+        <rect
+          v-if="interactive"
+          :width="width"
+          :height="height"
+          fill="transparent"
+          @mousemove="trackPointer"
+          @mouseleave="hideTip"
+        />
+      </svg>
+      </UTooltip>
+    </div>
+
+    <!-- Centred with the map above it. The legend component itself is shared with the track and the
+         calendar, which are left-aligned, so the alignment belongs here rather than in it. -->
+    <div v-if="showLegend" class="flex justify-center">
+      <FCellLegend :legend="scale.legend.value" />
+    </div>
+  </div>
+</template>