@humanforest/charts 0.3.6 → 0.4.0

package/src/londonAreas.ts

@@ -39,9 +39,9 @@ export const LONDON_BOROUGHS = boroughs as unknown as LondonAreaSet;
 /**
  * The wards, fetched on first use.
  *
- * Wards are three times the weight of the boroughs and most maps never draw them, so they are a
- * separate chunk rather than part of the barrel. The promise is cached, so concurrent callers and
- * re-renders share one request.
+ * Wards are more than four times the weight of the boroughs and most maps never draw them, so they
+ * are a separate chunk rather than part of the barrel. The promise is cached, so concurrent callers
+ * and re-renders share one request.
  */
 let wardsPromise: Promise<LondonAreaSet> | null = null;
 export const loadLondonWards = (): Promise<LondonAreaSet> => {
@@ -73,3 +73,85 @@ export const indexAreas = (areas: LondonArea[]): Map<string, LondonArea> => {
   }
   return byKey;
 };
+
+/**
+ * What a London map's areas take: pointer affordance (`interactive`) and a tab stop (`focusable`).
+ *
+ * Selection is an action the caller asked for, so a selectable map takes clicks and focus at every
+ * size and level, whatever the chrome. A tooltip is chrome: it needs chrome on, and reaches the
+ * keyboard only at borough level, where 33 stops is navigation rather than 704 obstacles.
+ */
+export const areaInteraction = (map: {
+  level: AreaLevel;
+  chrome: boolean;
+  tooltip: boolean;
+  selectable: boolean;
+}): { interactive: boolean; focusable: boolean } => {
+  const hover = map.tooltip && map.chrome;
+  return {
+    interactive: map.selectable || hover,
+    focusable: map.selectable || (hover && map.level === 'borough'),
+  };
+};
+
+/**
+ * One area framed to itself: the area `key` names (by code or name, either case) and a viewBox of
+ * its stored box, padded on every side by `pad` × its longer side. Undefined for a key the set does
+ * not hold, so an unknown area draws nothing rather than a stray full-London frame.
+ */
+export const frameArea = (
+  areas: LondonArea[],
+  key: string,
+  pad: number,
+): { area: LondonArea; viewBox: string } | undefined => {
+  const area = indexAreas(areas).get(key.toLowerCase());
+  if (!area) return undefined;
+  const p = Math.max(area.w, area.h) * pad;
+  return { area, viewBox: `${area.x - p} ${area.y - p} ${area.w + p * 2} ${area.h + p * 2}` };
+};
+
+const FIT_PAD = 0.06;
+const LABEL_EM = 9;
+
+/**
+ * What a map of `set` draws, the viewBox it draws it in, and which drawn areas carry a name.
+ *
+ * `fit: 'selection'` draws only the areas whose codes `matched` holds, framed to the union of their
+ * bounding boxes padded by 6% of its longer side. With `fit: 'city'`, or nothing matched, it draws
+ * every area in the set's viewBox. `font` is the label size in viewBox units at the rendered `width`.
+ *
+ * With `labels` set, areas are named biggest bounding box first, and a label whose box would overlap
+ * one already placed is dropped: a neighbour's label can reach across an area that has room by its
+ * own box.
+ */
+export const layoutAreas = (
+  set: LondonAreaSet,
+  map: { matched: ReadonlySet<string>; fit: 'city' | 'selection'; width: number; labels: boolean },
+): { drawn: LondonArea[]; frame: readonly number[]; font: number; labelled: LondonArea[] } => {
+  const fitted = map.fit === 'selection' && set.areas.some((a) => map.matched.has(a.code));
+  const drawn = fitted ? set.areas.filter((a) => map.matched.has(a.code)) : set.areas;
+  let frame: readonly number[] = set.viewBox;
+  if (fitted) {
+    const x0 = Math.min(...drawn.map((a) => a.x));
+    const y0 = Math.min(...drawn.map((a) => a.y));
+    const x1 = Math.max(...drawn.map((a) => a.x + a.w));
+    const y1 = Math.max(...drawn.map((a) => a.y + a.h));
+    const pad = Math.max(x1 - x0, y1 - y0) * FIT_PAD;
+    frame = [x0 - pad, y0 - pad, x1 - x0 + pad * 2, y1 - y0 + pad * 2];
+  }
+  const font = (frame[2]! / map.width) * LABEL_EM;
+  const labelled: LondonArea[] = [];
+  if (map.labels) {
+    const placed: { x0: number; x1: number; y0: number; y1: number }[] = [];
+    for (const a of [...drawn].sort((p, q) => q.w * q.h - p.w * p.h)) {
+      // Average glyph advance at small sizes: enough to reserve room without measuring text.
+      const halfW = (a.name.length * font * 0.55) / 2;
+      const halfH = font * 0.75;
+      const box = { x0: a.cx - halfW, x1: a.cx + halfW, y0: a.cy - halfH, y1: a.cy + halfH };
+      if (placed.some((p) => box.x0 < p.x1 && box.x1 > p.x0 && box.y0 < p.y1 && box.y1 > p.y0)) continue;
+      placed.push(box);
+      labelled.push(a);
+    }
+  }
+  return { drawn, frame, font, labelled };
+};

package/src/londonGrid.ts

@@ -65,3 +65,30 @@ export const dotAt = (grid: LondonGrid, lat: number, lng: number): [number, numb
 };
 
 export const dotKey = (col: number, row: number) => `${col},${row}`;
+
+/**
+ * Sums points into their dot. A point off the grid, or on a cell not in `land`, is dropped and
+ * counted. Without `value` each point counts one; a null, undefined or non-finite return adds nothing.
+ */
+export const binPoints = <P>(
+  grid: LondonGrid,
+  land: Set<string>,
+  points: readonly P[],
+  lat: (p: P) => number,
+  lng: (p: P) => number,
+  value?: (p: P) => number | null | undefined,
+) => {
+  const totals = new Map<string, number>();
+  let dropped = 0;
+  for (const p of points) {
+    const at = dotAt(grid, lat(p), lng(p));
+    const key = at && dotKey(at[0], at[1]);
+    if (!key || !land.has(key)) {
+      dropped++;
+      continue;
+    }
+    const v = value ? value(p) : 1;
+    totals.set(key, (totals.get(key) ?? 0) + (typeof v === 'number' && Number.isFinite(v) ? v : 0));
+  }
+  return { totals, dropped };
+};

package/src/presets.ts

@@ -22,8 +22,9 @@ export const axisY: Partial<AxisConfigInterface<unknown>> = Object.freeze({
 });
 
 /** Legend: currently empty. A bare `<VisBulletLegend :items="…">` already renders the house look —
- *  spacing and type come from the adapter's --vis-legend-* custom properties, and no call site
- *  repeats any config. The object exists so shared legend config has one home when it appears. */
+ *  the adapter sets its label colour and the --vis-font-family its type falls back to, Unovis's
+ *  own --vis-legend-* defaults set the sizes and spacing, and no call site repeats any config. The
+ *  object exists so shared legend config has one home when it appears. */
 export const legendDefaults: Partial<BulletLegendConfigInterface> = Object.freeze({});
 
 /** Tooltip: above-right of the anchor, held clear of the pointer.
@@ -34,7 +35,8 @@ export const legendDefaults: Partial<BulletLegendConfigInterface> = Object.freez
  *  track the pointer whatever is set here. And pinning anchors to the hovered element's BOUNDING
  *  BOX, so it only reads as "next to what I hovered" when the box is the mark: right for a bar,
  *  wrong for a donut arc or a treemap group, whose boxes are far larger than the shape under the
- *  cursor. Hence FChartFrameSingle, which carries exactly those marks, defaults the other way.
+ *  cursor. Hence both frames set followCursor back to true, and by default useTooltipSnap then
+ *  places the panel.
  *
  *  The shifts are what keep the pointer off the panel on that tracking path. Unovis adds a fixed
  *  5px margin, which puts the tooltip's corner under the cursor's own hotspot; these open that to a
@@ -73,7 +75,8 @@ export function houseTooltip(): Partial<TooltipConfigInterface> {
 
 /** Treemap tile shape. Unovis ships 2px corners and a 2px gap, which reads as a raw partition;
  *  the house tile is a rounded slab with room to breathe, matching the card radius family. The
- *  gap works with the adapter's tile stroke — padding separates, stroke defines the edge.
+ *  gap is the separator: the adapter draws no tile stroke, and inside a group the gap shows the
+ *  group tile beneath.
  *
  *  Typed structurally rather than as `Partial<TreemapConfigInterface<…>>`: v-binding a config
  *  object carrying the Datum generic pins it to whatever that object declares, and every accessor
@@ -93,19 +96,19 @@ export const treemapDefaults: {
   tileBorderRadius: 12,
   tilePadding: 4,
   // The strip a group reserves for its own heading. It has to clear the heading type the adapter
-  // sets on internal labels — too small and the zone name is cut off by its own group.
+  // sets on internal labels — too small and the group's own top tiles cover its label.
   tilePaddingTop: 26,
-  // Unovis draws group and leaf tiles as flat sibling rects with one shared rx, so nesting has no
-  // radius of its own. This flag is the only thing that marks leaves in the DOM (it adds a class to
-  // tiles with no children), which is what lets the adapter give them the concentric inner radius.
-  // Its other effect is a pointer cursor on leaves — correct here, since leaves carry the tooltip.
+  // Unovis draws group and leaf tiles as flat sibling rects under one corner rule, so nesting has
+  // no radius of its own. This flag is the only thing that marks leaf tiles in the DOM (it adds a
+  // class to tiles with no children), which is what lets the adapter give them the concentric inner
+  // radius. Its other effect is a pointer cursor on leaves.
   showTileClickAffordance: true,
   // Plain inset from the tile edge, independent of the radius: the adapter squares the label clip,
   // so a label is no longer sliced by its own clip corner and these do not have to dodge an arc.
   labelOffsetX: 8,
   labelOffsetY: 6,
   // Leaf label type. Unovis buckets leaves into three sizes by sqrt(value) against the largest
-  // leaf, and its own 8/12/22 steps +4 then +10 — so two stations of similar size can land either
+  // leaf, and its own 8/12/22 steps +4 then +10 — so two leaves of similar size can land either
   // side of the top threshold and differ by nearly double. These are evenly spaced and top out
   // level with the group heading, which stays distinct on weight rather than size.
   tileLabelSmallFontSize: 12,
@@ -117,11 +120,10 @@ export const treemapDefaults: {
  *  disc cut into wedges; the house rings are separated slabs with the same rounded feel as the
  *  treemap tile and the donut arc.
  *
- *  cornerRadius is the one number to be careful with. The flat donut clamps it to half the arc
- *  width, so an over-large value degrades gracefully there — the nested donut has NO such clamp,
- *  so a radius that suits the outer ring will visibly deform a short inner segment. 6 is the
- *  largest value that stays clean on the thinnest ring this chart is meant to carry; the flat
- *  donut's 4 is the comparable figure at its own 28px arc width.
+ *  cornerRadius is the one number to be careful with. d3's arc generator, which draws both donuts,
+ *  limits it to half the ring's width and shrinks it further on a narrow segment. 6 is the largest
+ *  value that stays clean on the thinnest ring this chart is meant to carry; the flat donut's 4 is
+ *  the comparable figure at its own 28px arc width.
  *
  *  Typed structurally rather than as `Partial<NestedDonutConfigInterface<…>>` for the same reason
  *  treemapDefaults is: v-binding a config object carrying the Datum generic pins it, and every
@@ -132,9 +134,8 @@ export const nestedDonutDefaults: {
   showBackground: boolean;
 } = Object.freeze({
   cornerRadius: 6,
-  // The ring gap. Segments carry a stroke rather than a real gap, so this works with the adapter's
-  // segment stroke the way tilePadding works with the treemap's — padding separates the rings,
-  // the stroke defines each segment's edge against its neighbours in the same ring.
+  // The ring gap. Segments in a ring have no gap between them, so the adapter's segment stroke
+  // separates those; this padding separates the rings.
   layerPadding: 4,
   // The track behind the segments. Our rings always sum to the whole, so a visible track only ever
   // surfaces in the gaps, where any opaque colour is wrong the moment the chart sits on a surface

package/src/resolveVar.ts

@@ -13,9 +13,10 @@
 // Read fresh on every call: the point is to defeat a cache, so adding one here would restore the
 // bug. Callers should invoke this inside a render that re-runs on `useThemeVersion`.
 
-/** The computed value of a `var(--x)` string. Non-var strings pass through untouched. */
-export function resolveVar(value: string, context: Element = document.documentElement): string {
+/** The computed value of a `var(--x)` string, read off `context` or the root element. Non-var
+ *  strings, and every string outside the browser, pass through untouched. */
+export function resolveVar(value: string, context?: Element): string {
   if (typeof window === 'undefined' || !value.startsWith('var(--')) return value;
   const name = value.slice(4, -1).split(',')[0]!.trim();
-  return getComputedStyle(context).getPropertyValue(name).trim() || value;
+  return getComputedStyle(context ?? document.documentElement).getPropertyValue(name).trim() || value;
 }

package/src/rovingFocus.ts

@@ -0,0 +1,26 @@
+// Roving focus for the cell components: a track or a grid is one Tab stop, and the keys move it.
+// Cells are one flat run in reading order; the component maps an index back to its element.
+
+/**
+ * The index focus moves to for a key, or null when the key is not a move. ArrowLeft and ArrowRight
+ * step by `across`, ArrowUp and ArrowDown by `down` (0 leaves them to the page), and Home and End
+ * jump to `first` and `last`. A step that would leave the run stays put. A modified key is never a
+ * move, so browser shortcuts such as Cmd+ArrowLeft keep working.
+ */
+export function rovingIndex(
+  event: Pick<KeyboardEvent, 'key' | 'altKey' | 'ctrlKey' | 'metaKey'>,
+  index: number,
+  first: number,
+  last: number,
+  across = 1,
+  down = 0,
+): number | null {
+  if (event.altKey || event.ctrlKey || event.metaKey) return null;
+  if (event.key === 'Home') return first;
+  if (event.key === 'End') return last;
+  const steps: Record<string, number> = { ArrowRight: across, ArrowLeft: -across, ArrowDown: down, ArrowUp: -down };
+  const step = steps[event.key];
+  if (!step) return null;
+  const next = index + step;
+  return next < first || next > last ? index : next;
+}

package/src/snapTooltip.ts

@@ -13,9 +13,11 @@
 // Two anchors, matching how the two frames are read:
 //   crosshair — the crosshair line's x, panel held at the top of the plot. It steps as the
 //               crosshair snaps between rows and holds still in between, which is the whole point.
-//   mark      — the centroid of the hovered shape, panel just outside it on the side with room.
-//               Sampled along the outline rather than taken from the box, so an arc anchors at its
-//               own mid-angle instead of at the corner of a box it never touches.
+//   mark      — the centroid of the hovered shape, panel on the side away from the frame's centre
+//               with its near edge 12px from the centroid, then held 8px inside the viewport, so it
+//               overlaps the outer half of any mark wider than 24px. The centroid is sampled along
+//               the outline rather than taken from the box, so an arc anchors at its own mid-angle
+//               instead of at the corner of a box it never touches.
 import { onBeforeUnmount, onMounted, type Ref } from 'vue';
 import { Crosshair } from '@unovis/ts';
 
@@ -36,11 +38,12 @@ export function nextTipId(): string {
 
 const clamp = (v: number, lo: number, hi: number): number => Math.min(Math.max(v, lo), hi);
 
-/** Centre of a shape, in viewport coordinates. Paths are sampled along their outline and averaged:
- *  for a donut arc that lands at mid-angle, mid-radius — the middle of the visible band — where the
- *  box centre would land in the hole, or outside the wedge entirely on a small segment. Anything
- *  without a length (rects) falls back to its box, which for those IS the mark. */
-function shapeCentre(el: SVGGraphicsElement): { x: number; y: number } {
+/** Centre of a shape, in viewport coordinates. Every SVGGeometryElement, rects included, is sampled
+ *  along its outline and averaged: for a donut arc that lands at mid-angle, mid-radius — the middle
+ *  of the visible band — where the box centre would land in the hole, or outside the wedge entirely
+ *  on a small segment. An element with no outline to measure (a group, text), a zero length or no
+ *  screen matrix falls back to its box. */
+export function shapeCentre(el: SVGGraphicsElement): { x: number; y: number } {
   const path = el as SVGPathElement;
   if (typeof path.getTotalLength === 'function') {
     const total = path.getTotalLength();
@@ -63,6 +66,31 @@ function shapeCentre(el: SVGGraphicsElement): { x: number; y: number } {
 
 export type SnapMode = 'crosshair' | 'mark';
 
+/** Where the panel lands, in viewport pixels: beside its anchor, then held EDGE inside the viewport. */
+export function tipPlacement(
+  mode: SnapMode,
+  anchor: { x: number; y: number },
+  box: { x: number; y: number; width: number },
+  tip: { width: number; height: number },
+  viewport: { width: number; height: number },
+): { left: number; top: number } {
+  // Which way the panel opens, and the two modes want opposite answers. A crosshair spans the
+  // plot, so the empty half is the one the line is NOT in: open away from it, which also puts the
+  // panel away from the pointer. A mark sits somewhere in the chart with the rest of the chart
+  // around it, so opening inward would lay the panel over the other marks — over the donut's hole
+  // and its central label, in the case that made this obvious. Open outward instead.
+  const cx = box.x + box.width / 2;
+  const toRight = mode === 'crosshair' ? anchor.x <= cx : anchor.x > cx;
+  const left = toRight ? anchor.x + GAP : anchor.x - tip.width - GAP;
+  // A crosshair panel rides at the top of the plot: fixed, so it never drifts vertically with a
+  // pointer whose y means nothing to the reading. A mark panel centres on its own shape.
+  const top = mode === 'crosshair' ? box.y + GAP : anchor.y - tip.height / 2;
+  return {
+    left: clamp(left, EDGE, viewport.width - tip.width - EDGE),
+    top: clamp(top, EDGE, viewport.height - tip.height - EDGE),
+  };
+}
+
 /** Installs the snap on a frame. `enabled` is read live so a frame can hand positioning back to
  *  Unovis (the `followCursor` escape hatch) without tearing anything down. */
 export function useTooltipSnap(
@@ -77,7 +105,6 @@ export function useTooltipSnap(
   // Guards the observer against our own writes, which would otherwise re-enter it forever.
   let writing = false;
   let observer: MutationObserver | undefined;
-  let frame = 0;
 
   function onPointerMove(e: Event): void {
     const t = e.target;
@@ -104,37 +131,31 @@ export function useTooltipSnap(
     const anchor = anchorFor(host);
     if (!anchor) return;
 
-    const w = tip.offsetWidth;
-    const h = tip.offsetHeight;
-    const box = host.getBoundingClientRect();
-    // Which way the panel opens, and the two modes want opposite answers. A crosshair spans the
-    // plot, so the empty half is the one the line is NOT in: open away from it, which also puts the
-    // panel away from the pointer. A mark sits somewhere in the chart with the rest of the chart
-    // around it, so opening inward would lay the panel over the other marks — over the donut's hole
-    // and its central label, in the case that made this obvious. Open outward instead.
-    const cx = box.x + box.width / 2;
-    const toRight = mode === 'crosshair' ? anchor.x <= cx : anchor.x > cx;
-    const left = toRight ? anchor.x + GAP : anchor.x - w - GAP;
-    // A crosshair panel rides at the top of the plot: fixed, so it never drifts vertically with a
-    // pointer whose y means nothing to the reading. A mark panel centres on its own shape.
-    const top = mode === 'crosshair' ? box.y + GAP : anchor.y - h / 2;
+    const { left, top } = tipPlacement(
+      mode,
+      anchor,
+      host.getBoundingClientRect(),
+      { width: tip.offsetWidth, height: tip.offsetHeight },
+      { width: window.innerWidth, height: window.innerHeight },
+    );
 
     writing = true;
-    tip.style.left = `${clamp(left, EDGE, window.innerWidth - w - EDGE)}px`;
-    tip.style.top = `${clamp(top, EDGE, window.innerHeight - h - EDGE)}px`;
+    tip.style.left = `${left}px`;
+    tip.style.top = `${top}px`;
     // Unovis positions by `bottom` when the tooltip is not attached to body; clear it so our `top`
     // is the only vertical rule in play whichever container the frame ends up with.
     tip.style.bottom = 'unset';
     writing = false;
   }
 
+  // The panel is looked up each time the pointer enters the chart, the only time it can show.
+  // VisTooltip creates it after mount, a remount (a theme or palette change) replaces it, and a
+  // frame without a tooltip has none. A panel replaced while the pointer is inside is picked up on
+  // the next entry.
   function attach(): void {
+    observer?.disconnect();
     const tip = document.querySelector<HTMLElement>(`[data-forest-tip="${tipId}"]`);
-    if (!tip) {
-      // VisTooltip creates its element on its own schedule; wait for it rather than racing mount.
-      frame = requestAnimationFrame(attach);
-      return;
-    }
+    if (!tip) return;
     observer = new MutationObserver(() => {
       if (!writing) reposition(tip);
     });
@@ -143,12 +164,12 @@ export function useTooltipSnap(
 
   onMounted(() => {
     root.value?.addEventListener('pointermove', onPointerMove, { capture: true });
-    attach();
+    root.value?.addEventListener('pointerenter', attach);
   });
 
   onBeforeUnmount(() => {
-    cancelAnimationFrame(frame);
     observer?.disconnect();
     root.value?.removeEventListener('pointermove', onPointerMove, { capture: true });
+    root.value?.removeEventListener('pointerenter', attach);
   });
 }

package/src/sparklineDomain.ts

@@ -1,3 +1,8 @@
+// FSparkline's geometry, kept out of the SFC so it can be tested without a DOM.
+
+/** A reading that can be drawn. Null is a gap, and NaN or ±Infinity has no place on a scale. */
+const drawable = (v: number | null | undefined): v is number => Number.isFinite(v);
+
 /**
  * The frame a sparkline's line marks are plotted in: the floor and ceiling of everything drawn,
  * shared by the series and its comparison, or null when there is nothing to draw so the container
@@ -16,10 +21,74 @@ export function sparklineDomain(
   compare: (number | null)[] | undefined,
   area: boolean,
 ): { floor: number; domain: [number, number] | null } {
-  const vals = [...data, ...(compare ?? [])].filter((v): v is number => typeof v === 'number');
+  const vals = [...data, ...(compare ?? [])].filter(drawable);
   if (!vals.length) return { floor: 0, domain: null };
   const lo = Math.min(...vals);
   const hi = Math.max(...vals);
   const floor = area ? lo : 0;
   return { floor, domain: [lo - floor, hi - floor] };
 }
+
+export interface SparklineBarDomain {
+  lo: number;
+  span: number;
+}
+
+/**
+ * The bars' range, as its lowest value and its span. Bars are measured from zero, not from the
+ * data's own floor like the line: a bar reads as a LENGTH, and a bar that starts anywhere but zero
+ * has a length no longer proportional to its value. The range therefore always contains zero, which
+ * also puts negative readings below the baseline instead of quietly flipping them. A range with no
+ * span is given a span of 1, so an all-zero series divides by something.
+ */
+export function sparklineBarDomain(data: (number | null)[]): SparklineBarDomain {
+  const vals = data.filter(drawable);
+  const lo = Math.min(0, ...vals);
+  const hi = Math.max(0, ...vals);
+  return { lo, span: hi - lo || 1 };
+}
+
+/** One bar's bottom offset and height as CSS percentages, from zero to the reading, or null for a gap. */
+export function sparklineBar(
+  v: number | null,
+  { lo, span }: SparklineBarDomain,
+): { bottom: string; height: string } | null {
+  if (!drawable(v)) return null;
+  const zero = (0 - lo) / span;
+  const value = (v - lo) / span;
+  const from = Math.min(zero, value);
+  const to = Math.max(zero, value);
+  return {
+    bottom: `${from * 100}%`,
+    // A reading of zero keeps a hairline. Zero is a real measurement and a gap is the absence of
+    // one; collapsing the bar to nothing would render the two identically.
+    height: `max(${(to - from) * 100}%, 1px)`,
+  };
+}
+
+/**
+ * Where the endpoint dot sits: the last drawable reading's distance down the frame, as a
+ * percentage, or null when there is no reading to mark. A frame with no span puts the dot at 50%,
+ * the middle of the height, where the flat line itself is drawn.
+ */
+export function sparklineEndpoint(
+  data: (number | null)[],
+  { floor, domain }: { floor: number; domain: [number, number] | null },
+): number | null {
+  for (let i = data.length - 1; i >= 0; i--) {
+    const v = data[i];
+    if (!drawable(v)) continue;
+    const [lo, hi] = domain ?? [0, 0];
+    return hi === lo ? 50 : (1 - (v - floor - lo) / (hi - lo)) * 100;
+  }
+  return null;
+}
+
+/**
+ * A reading's y on the line marks: its height above the frame's floor, or undefined when there is no
+ * reading to draw, so the line breaks there. Undefined, not null: Unovis' line tests each point with
+ * the global isFinite, which passes a null and plots it at zero.
+ */
+export function sparklineY(v: number | null | undefined, floor: number): number | undefined {
+  return drawable(v) ? v - floor : undefined;
+}

package/src/useCellScale.ts

@@ -1,4 +1,4 @@
-// The cell colour contract, shared by FStatusTrack and FCalendarGrid.
+// The cell colour contract, shared by FStatusTrack, FCalendarGrid, FDottedMap and FLondonMap.
 //
 // Cell components answer two different questions with the same rectangle: which STATE a bucket was
 // in, and how MUCH happened in it. Both resolve a datum to a colour and need a legend, so the
@@ -6,7 +6,7 @@
 //
 // Empty is a third outcome, not a zero and not a first state: a bucket with no reading and a bucket
 // reading zero are different claims, and colouring them alike asserts something the data does not.
-import { computed, unref, type MaybeRef } from 'vue';
+import { computed, unref, type ComputedRef, type MaybeRef } from 'vue';
 import type { BulletLegendItemInterface } from '@unovis/ts';
 import { sequentialVar } from './useChartPalette';
 import { DATAVIZ_SEQUENTIAL } from './engine';
@@ -29,7 +29,7 @@ export interface CellLegend {
 }
 
 export interface CellScaleOptions<D> {
-  mode: 'state' | 'intensity';
+  mode: MaybeRef<'state' | 'intensity'>;
   /** State mode. Same shape as `categories` elsewhere, so useChartPalette output feeds it as-is. */
   states?: MaybeRef<Record<string, BulletLegendItemInterface> | undefined>;
   /** Intensity mode. */
@@ -46,9 +46,12 @@ export interface CellScaleOptions<D> {
 export interface CellScale<D> {
   colorOf: (d: D | null | undefined) => string;
   isEmpty: (d: D | null | undefined) => boolean;
-  legend: CellLegend;
+  /** The descriptor FCellLegend draws, as `scale.legend.value`. */
+  legend: ComputedRef<CellLegend>;
   /** The resolved intensity domain — read it back when a caller wants to label the ends. */
-  domain: [number, number];
+  domain: ComputedRef<[number, number]>;
+  /** The ramp sampled into `steps` stops, low → high, reversed in dark mode. */
+  swatches: ComputedRef<string[]>;
 }
 
 /** The fill for a bucket with no reading. A token, so it flips with the mode like everything else. */
@@ -70,7 +73,7 @@ const prefersInvertedRamp = (): boolean => {
   return root.classList.contains('dark') || root.dataset.theme === 'dark';
 };
 
-export function useCellScale<D>(options: CellScaleOptions<D>) {
+export function useCellScale<D>(options: CellScaleOptions<D>): CellScale<D> {
   const stepsOf = () => Math.max(2, unref(options.steps) ?? 5);
   // Read so the sampling recomputes on a colour-mode flip; the value itself is not used.
   const themeVersion = useThemeVersion();
@@ -102,7 +105,7 @@ export function useCellScale<D>(options: CellScaleOptions<D>) {
 
   const isEmpty = (d: D | null | undefined): boolean => {
     if (d === null || d === undefined) return true;
-    if (options.mode === 'intensity') {
+    if (unref(options.mode) === 'intensity') {
       const v = options.value?.(d);
       return typeof v !== 'number' || !Number.isFinite(v);
     }
@@ -112,7 +115,7 @@ export function useCellScale<D>(options: CellScaleOptions<D>) {
 
   const resolve = (d: D | null | undefined): string => {
     if (isEmpty(d)) return CELL_EMPTY_COLOR;
-    if (options.mode === 'intensity') {
+    if (unref(options.mode) === 'intensity') {
       const [lo, hi] = domain.value;
       const v = options.value!(d as D) as number;
       const stops = swatches.value;
@@ -131,7 +134,7 @@ export function useCellScale<D>(options: CellScaleOptions<D>) {
   };
 
   const legend = computed<CellLegend>(() => {
-    if (options.mode === 'intensity') {
+    if (unref(options.mode) === 'intensity') {
       return {
         mode: 'intensity',
         entries: swatches.value.map((swatch, i) => ({ key: String(i), swatch })),
@@ -153,3 +156,29 @@ export function useCellScale<D>(options: CellScaleOptions<D>) {
 
   return { colorOf: resolve, isEmpty, legend, domain, swatches };
 }
+
+/** The colour props FStatusTrack and FCalendarGrid share. */
+export interface CellScaleProps<D> {
+  data: readonly D[];
+  mode: 'state' | 'intensity';
+  states?: Record<string, BulletLegendItemInterface>;
+  state?: (d: D) => string | null | undefined;
+  value?: (d: D) => number | null | undefined;
+  ramp?: SequentialRamp;
+  domain?: [number, number];
+  steps: number;
+}
+
+/** useCellScale over a component's colour props, every one read live, the accessors included. */
+export function useCellScaleProps<D>(props: CellScaleProps<D>): CellScale<D> {
+  return useCellScale<D>({
+    mode: computed(() => props.mode),
+    states: computed(() => props.states),
+    ramp: computed(() => props.ramp ?? ('forest' as SequentialRamp)),
+    domain: computed(() => props.domain),
+    steps: computed(() => props.steps),
+    data: computed(() => props.data),
+    value: (d) => props.value?.(d),
+    state: (d) => props.state?.(d),
+  });
+}

package/src/useChartPalette.ts

@@ -12,7 +12,7 @@ export interface SeriesDef { key: string; name: string }
 // There is deliberately NO generic `categorical()` — the generic name used to return the VIVID set,
 // which meant the one palette that is not colour-blind-safe owned the most authoritative-sounding name.
 const SAFE = Object.keys(DATAVIZ.light); // 1..6 — brand-led CVD-safe, consumed by index
-const VIVID = DATAVIZ_CATEGORICAL.names; // green, amber, red, … (first 6 = the curated 6)
+const VIVID = DATAVIZ_CATEGORICAL.names; // green, amber, sky, … (first 6 = the curated 6)
 const PAIRS = Object.keys(DATAVIZ_PAIRS.light); // forest-deep, forest-soft, warm-deep, … (family-grouped)
 
 export const safeVar = (i: number) => `var(--dataviz-categorical-safe-${SAFE[i % SAFE.length]})`;
@@ -37,13 +37,15 @@ const build = (series: SeriesDef[], color: (i: number) => string): Categories =>
 export function useChartPalette() {
   return {
     /** The 6-colour brand-led CVD-safe set — what the Unovis adapter already ships on --vis-color0..5.
-     *  The default: colour alone separates the series, so it needs no second channel. */
+     *  The default: the six stay separable on colour alone under all three simulated dichromacies,
+     *  and a second cue (direct labels, dash or marker) covers what the simulation cannot, such as a
+     *  photocopy or a projector. A legend keyed by colour is not that cue. */
     cvdSafe: (series: SeriesDef[]) => build(series, safeVar),
     /** Vivid categorical (palette order). ≤6 where you can; 7–12 are label-only.
-     *  NOT CVD-safe — the caller MUST add a second channel (legend, direct labels, dash or marker). */
+     *  NOT CVD-safe — the caller MUST add a second channel (direct labels, dash or marker). */
     vivid: (series: SeriesDef[]) => build(series, vividVar),
     /** Brand pairs — 3 brand hues × deep/soft, family-grouped. Brand-forward work: decks, marketing.
-     *  NOT CVD-safe — the caller MUST add a second channel (legend, direct labels, dash or marker). */
+     *  NOT CVD-safe — the caller MUST add a second channel (direct labels, dash or marker). */
     pairs: (series: SeriesDef[]) => build(series, pairsVar),
     /** One of the three sets, chosen at runtime. For the docs' palette picker — production code
      *  should name the set it means, so the CVD contract above is visible at the call site. */