@humanforest/nuxt-layer 0.1.0

package/packages/charts/src/FChartFrameSingle.vue

@@ -0,0 +1,91 @@
+<script setup lang="ts" generic="Data">
+// The single-container frame, for the non-XY charts (Donut, Sankey, Graph, Treemap). Same
+// doctrine as FChartFrame: wrap only ceremony — container, legend, tooltip wiring, repaint —
+// never mark props. `data` is whatever the mark's container expects (number[] for a donut,
+// { nodes, links } for a sankey) and passes through untyped by the frame, typed by the mark.
+import { computed, ref } from 'vue';
+import { VisSingleContainer, VisTooltip, VisBulletLegend } from '@unovis/vue';
+import type { BulletLegendItemInterface, TooltipConfigInterface } from '@unovis/ts';
+// Relative file imports (not the package barrel): the barrel exports this component, and a
+// self-import through it would create a module cycle.
+import { fromCategories } from './fromCategories';
+import { motionDuration } from './motionDuration';
+import { tooltipDefaults, tooltipContainer } from './presets';
+import { useThemeVersion } from './useThemeVersion';
+import { useTooltipSnap, nextTipId } from './snapTooltip';
+
+defineOptions({ inheritAttrs: false });
+
+const props = withDefaults(
+  defineProps<{
+    data: Data;
+    /** Optional: series colours + legend. Omit for charts that label directly (Sankey, Graph). */
+    categories?: Record<string, BulletLegendItemInterface>;
+    height?: number;
+    /** Rendered only when given — single-container tooltips need `triggers` to show anything. */
+    tooltip?: Partial<TooltipConfigInterface>;
+    /** Let the panel track the pointer instead of snapping to the hovered mark. Off by default:
+     *  the panel anchors to the centre of the shape under the cursor and holds there, so it moves
+     *  when the reading changes rather than with every pixel. Turn it on for a free-floating panel.
+     */
+    followCursor?: boolean;
+    legend?: boolean;
+    /** Where the legend sits. `bottom` (default) renders centred under the chart, caption-style;
+     *  `top` renders start-aligned above it, editorial-style. */
+    legendPosition?: 'top' | 'bottom';
+    /** Animation ms for the container's components. Default: motionDuration('slow'). */
+    duration?: number;
+    /** Extra signals that must remount the chart (theme flips and palette identity are automatic). */
+    repaintOn?: unknown[];
+  }>(),
+  { height: 260, legend: true, legendPosition: 'bottom', followCursor: false, repaintOn: () => [] },
+);
+
+defineSlots<{
+  mark(p: { data: Data; colors: string[] }): unknown;
+}>();
+
+const acc = computed(() => fromCategories(props.categories ?? {}));
+
+// As in FChartFrame: the panel is snapped to the hovered mark by useTooltipSnap, so what Unovis is
+// configured to do is the fallback for when the snap stands down. Pointer tracking is that
+// fallback — never the library's element pinning, which anchors to a bounding box that for these
+// marks (arcs, groups, links) is nothing like the shape under the cursor.
+const tipId = nextTipId();
+const tooltipConfig = computed<Partial<TooltipConfigInterface>>(() => ({
+  ...tooltipDefaults,
+  container: tooltipContainer(),
+  followCursor: true,
+  ...(props.tooltip || {}),
+  attributes: { ...(props.tooltip || {}).attributes, 'data-forest-tip': tipId },
+}));
+
+const rootEl = ref<HTMLElement>();
+useTooltipSnap(rootEl, tipId, 'mark', () => !props.followCursor);
+const resolvedDuration = computed(() => props.duration ?? motionDuration());
+
+const themeVersion = useThemeVersion();
+const repaintKey = computed(() =>
+  [themeVersion.value, acc.value.colors.join('|'), ...props.repaintOn].map(String).join('-'),
+);
+</script>
+
+<template>
+  <div ref="rootEl" style="display: flex; flex-direction: column; gap: 0.75rem">
+    <VisSingleContainer
+      :key="repaintKey"
+      :data="data"
+      :height="height"
+      :duration="resolvedDuration"
+      v-bind="$attrs"
+    >
+      <slot name="mark" :data="data" :colors="acc.colors" />
+      <VisTooltip v-if="tooltip" v-bind="tooltipConfig" />
+    </VisSingleContainer>
+    <VisBulletLegend
+      v-if="legend && acc.legendItems.length"
+      :items="acc.legendItems"
+      :style="legendPosition === 'top' ? { order: -1, alignSelf: 'flex-start' } : { alignSelf: 'center' }"
+    />
+  </div>
+</template>

package/packages/charts/src/FChartLegend.vue

@@ -0,0 +1,26 @@
+<script setup lang="ts">
+// The house-positioned legend, for charts assembled without a frame. FChartFrame and
+// FChartFrameSingle place their own legend; a bare VisBulletLegend has no opinion about where it
+// sits, so direct charts would otherwise each hand-roll the same wrapper. Same items prop and the
+// same two positions the frames take, so a chart reads identically whichever way it is built.
+import { VisBulletLegend } from '@unovis/vue';
+import type { BulletLegendItemInterface } from '@unovis/ts';
+
+withDefaults(
+  defineProps<{
+    items: BulletLegendItemInterface[];
+    /** `bottom` (default) centres it under the chart; `top` sits it start-aligned above. */
+    position?: 'top' | 'bottom';
+  }>(),
+  { position: 'bottom' },
+);
+</script>
+
+<template>
+  <div
+    style="display: flex"
+    :style="{ justifyContent: position === 'top' ? 'flex-start' : 'center' }"
+  >
+    <VisBulletLegend :items="items" />
+  </div>
+</template>

package/packages/charts/src/FDistributionBar.vue

@@ -0,0 +1,224 @@
+<script setup lang="ts">
+// One bar split into its parts: what a figure is made of, at the size of a figure. Sits in an FKpi
+// `visual` slot beside the number it decomposes, where a donut would need a legend, a centre label
+// and more height than a tile has.
+//
+// Plain DOM on a grid rather than SVG. Grid takes the gaps out of the track widths itself, so the
+// segments still sum to the bar — the same layout in flex needs percentages that the gaps then
+// overflow.
+//
+// Deliberately not a stacked bar chart: one bar, one moment. A composition that moves over time is
+// a chart, and FChartFrame is the component for that.
+//
+// Two looks. Split (default) gives each part its own pill, which says "these are separate things,
+// here is their relative size". `joined` closes the gaps and rounds only the bar's outside corners,
+// which says "this is one quantity, here is what it is made of". The corner shaping is what does
+// the work: pills at gap 0 pinch at every seam.
+//
+// Joined is NOT the component for a plain progress or capacity bar — one value against a maximum,
+// no parts, is UProgress, which owns the semantics (role, value text, step labels) and the intent
+// colours. This is for the case UProgress cannot draw: the filled length itself split by what made
+// it up.
+//
+// In an FKpi `visual` slot, pass `visual-fit="inset"` on the tile. The slot's default fit bleeds to
+// the card's side and bottom edges, which is right for a sparkline — it holds no text and its
+// baseline is the card's. This holds a legend, so it wants the padding back and top alignment.
+import { computed, ref } from 'vue';
+import { categoricalVar, type CategoricalPalette } from './useChartPalette';
+import {
+  distributionShares,
+  formatShare,
+  segmentRadius,
+  type DistributionSegment,
+} from './distribution';
+
+const props = withDefaults(
+  defineProps<{
+    /** The parts. Order is the drawing order, left to right, and fixes each part's palette slot. */
+    data: DistributionSegment[];
+    /**
+     * The whole the parts are measured against. Defaults to their sum, which makes the bar a pure
+     * composition. Pass a larger number to leave a remainder — "78% of capacity, and here is what
+     * used it" is one bar, not two.
+     */
+    total?: number;
+    /** Bar thickness. */
+    height?: number;
+    /** Space between segments. Ignored when `joined` — a joined bar has no space to give. */
+    gap?: number;
+    /**
+     * Draws the parts as ONE continuous bar: no gaps, and only the outside corners rounded, so the
+     * seams are square. For a quantity read as one thing that happens to be made of parts, where
+     * separate pills would read as separate objects. One value and no parts is UProgress, not this.
+     */
+    joined?: boolean;
+    palette?: CategoricalPalette;
+    legend?: boolean;
+    /** Adds each part's percentage to its legend entry. The bar states shares by length either way. */
+    showShare?: boolean;
+    locale?: string;
+    /**
+     * Hover and focus text on the segments. `true` uses "<label> — <value> (<share>)"; a function
+     * writes its own. Given either, the segments become real buttons so a keyboard reaches them —
+     * which is also why it is opt-in: three tiles of three parts is nine extra tab stops for a
+     * figure the legend already states.
+     */
+    tooltip?: boolean | ((segment: DistributionSegment, share: number) => string);
+    /** Overrides the generated sentence for assistive tech. */
+    ariaLabel?: string;
+  }>(),
+  {
+    height: 8,
+    gap: 2,
+    joined: false,
+    palette: 'cvdSafe',
+    legend: true,
+    showShare: false,
+    locale: 'en-GB',
+    total: undefined,
+    /* Vue casts an ABSENT Boolean-typed prop to false, which is the intended default here — but it
+       is spelled out so the union with the formatter function keeps a declared default either way. */
+    tooltip: false,
+    ariaLabel: undefined,
+  },
+);
+
+const shares = computed(() => distributionShares(props.data, props.total));
+
+const colorOf = (part: { segment: DistributionSegment; index: number }) =>
+  part.segment.color ?? categoricalVar(props.palette, part.index);
+
+// A zero-width track would still take its share of the gap, leaving a stray notch where nothing is.
+const drawn = computed(() => shares.value.parts.filter((p) => p.share > 0));
+
+// Grid tracks in fr, so the gaps come out of the tracks rather than pushing the last one out.
+const columns = computed(() => {
+  const tracks = drawn.value.map((p) => `${p.share}fr`);
+  if (shares.value.remainder > 0) tracks.push(`${shares.value.remainder}fr`);
+  return tracks.join(' ');
+});
+
+// How many tracks actually render — the drawn segments plus the remainder when there is one. The
+// corner shaping needs this, and it is NOT `data.length`: zero-share parts are filtered out, so the
+// last DRAWN segment is what carries the bar's right-hand corners.
+const trackCount = computed(() => drawn.value.length + (shares.value.remainder > 0 ? 1 : 0));
+const radiusAt = (index: number) =>
+  segmentRadius(index, trackCount.value, props.height / 2, props.joined);
+
+// The bar's lengths are the only place the shares are stated unless `showShare` is on, so the
+// sentence carries them regardless.
+const label = computed(() => {
+  if (props.ariaLabel) return props.ariaLabel;
+  const parts = shares.value.parts.map(
+    (p) => `${p.segment.label} ${formatShare(p.share, props.locale)}`,
+  );
+  if (shares.value.remainder > 0)
+    parts.push(`unaccounted ${formatShare(shares.value.remainder, props.locale)}`);
+  return parts.join(', ');
+});
+
+const interactive = computed(() => props.tooltip !== false);
+
+const num = (n: number) => n.toLocaleString(props.locale);
+
+const tipFor = (segment: DistributionSegment, share: number) =>
+  typeof props.tooltip === 'function'
+    ? props.tooltip(segment, share)
+    : `${segment.label} — ${num(segment.value)} (${formatShare(share, props.locale)})`;
+
+// The remainder is not one of `data`, so it has no segment to hand a formatter. It gets the same
+// sentence shape from the numbers the shares already carry.
+const remainderTip = computed(
+  () =>
+    `Unaccounted — ${num(Math.round(shares.value.remainder * shares.value.total))} (${formatShare(shares.value.remainder, props.locale)})`,
+);
+
+// One UTooltip for the whole bar, re-anchored to the segment under the pointer, rather than one
+// per segment: `reference` moves the popper's anchor while the trigger stays the bar itself, so a
+// bar of any width costs a single tooltip root.
+//
+// `tipOpen` owns visibility; the text and the anchor are left alone on close. Clearing them
+// together with the flag emptied the bubble mid-exit-animation and dropped the anchor back to the
+// trigger, so leaving a segment flashed a blank pill at the container's centre for ~80ms.
+//
+// Anchored to the segment, not the pointer, so a keyboard focus places it too.
+const tip = ref<{ text: string; el: HTMLElement | null }>({ text: '', el: null });
+const tipOpen = ref(false);
+const showTip = (event: Event, text: string) => {
+  tip.value = { text, el: event.currentTarget as HTMLElement };
+  tipOpen.value = true;
+};
+const hideTip = () => {
+  tipOpen.value = false;
+};
+</script>
+
+<template>
+  <div class="flex w-full flex-col gap-2">
+    <!-- `img` makes its contents presentational, which is right while the bar is a graphic and
+         wrong the moment the segments are buttons — the buttons would be hidden from the very
+         readers the role is for. Interactive, it becomes a labelled group whose children stay
+         reachable, and each segment states itself. -->
+    <UTooltip :text="tip.text" :reference="tip.el" :open="tipOpen">
+      <div
+        class="grid w-full"
+        :role="interactive ? 'group' : 'img'"
+        :aria-label="label"
+        :style="{
+          gridTemplateColumns: columns,
+          gap: `${joined ? 0 : gap}px`,
+          height: `${height}px`,
+        }"
+      >
+      <component
+        :is="interactive ? 'button' : 'span'"
+        v-for="(p, i) in drawn"
+        :key="p.index"
+        :type="interactive ? 'button' : undefined"
+        :class="
+          interactive
+            ? 'cursor-pointer transition-[filter] duration-150 hover:brightness-110 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--ui-primary)]'
+            : ''
+        "
+        :style="{ background: colorOf(p), borderRadius: radiusAt(i) }"
+        :aria-label="interactive ? tipFor(p.segment, p.share) : undefined"
+        @mouseenter="interactive && showTip($event, tipFor(p.segment, p.share))"
+        @mouseleave="hideTip"
+        @focus="interactive && showTip($event, tipFor(p.segment, p.share))"
+        @blur="hideTip"
+      />
+      <!-- The remainder is the track colour, not a palette slot: it is the absence of a category,
+           and giving it a colour would make it read as one more. -->
+      <component
+        :is="interactive ? 'button' : 'span'"
+        v-if="shares.remainder > 0"
+        :type="interactive ? 'button' : undefined"
+        class="bg-[var(--ui-bg-accented)]"
+        :class="
+          interactive
+            ? 'cursor-pointer transition-[filter] duration-150 hover:brightness-110 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--ui-primary)]'
+            : ''
+        "
+        :style="{ borderRadius: radiusAt(trackCount - 1) }"
+        :aria-label="interactive ? remainderTip : undefined"
+        @mouseenter="interactive && showTip($event, remainderTip)"
+        @mouseleave="hideTip"
+        @focus="interactive && showTip($event, remainderTip)"
+        @blur="hideTip"
+        />
+      </div>
+    </UTooltip>
+
+    <!-- Centred: the entries are a caption for the bar rather than a column of their own, and a
+         wrapped second row reads as ragged against a left edge the bar does not share. -->
+    <div v-if="legend" class="flex flex-wrap items-center justify-center gap-x-4 gap-y-1">
+      <span v-for="p in shares.parts" :key="p.index" class="flex items-center gap-1.5">
+        <span class="size-2 rounded-full" :style="{ background: colorOf(p) }" aria-hidden="true" />
+        <span class="type-caption text-muted">{{ p.segment.label }}</span>
+        <span v-if="showShare" class="type-caption text-dimmed">
+          {{ formatShare(p.share, locale) }}
+        </span>
+      </span>
+    </div>
+  </div>
+</template>

package/packages/charts/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>