@humanforest/charts 0.3.5 → 0.3.7

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+Every @humanforest package shares one version, so one entry covers all seven packages. Newest first.
+
+## 0.3.7 — 2026-09-13
+
+### Features
+
+- **ui**: add FMapContextMenu, a right-click menu on the map
+- **charts**: chart frames and sparklines can be named for screen readers
+
+### Fixes
+
+- **charts**: CellScale types what useCellScale returns
+- **charts**: an empty distribution bar is still named, as "No data"
+- **charts**: a bar sparkline warns that :curve="false" is ignored
+- **charts**: a sparkline leaves non-finite readings off its scale
+- **tokens**: the sub-logo builder passes noUncheckedIndexedAccess

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@humanforest/charts",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "type": "module",
   "files": [
-    "src"
+    "src",
+    "CHANGELOG.md"
   ],
   "exports": {
     ".": "./src/index.ts",
@@ -13,6 +14,9 @@
     "./forestTooltip": "./src/forestTooltip.ts",
     "./useChartRepaintKey": "./src/useChartRepaintKey.ts"
   },
+  "scripts": {
+    "test": "vitest run"
+  },
   "peerDependencies": {
     "@nuxt/ui": "^4",
     "@unovis/ts": "^1.6.7",
@@ -21,10 +25,11 @@
   },
   "devDependencies": {
     "@unovis/ts": "^1.6.7",
+    "vitest": "^4.1.10",
     "vue": "^3.5.22"
   },
   "dependencies": {
-    "@humanforest/tokens": "^0.3.5"
+    "@humanforest/tokens": "^0.3.7"
   },
   "publishConfig": {
     "access": "public"

package/src/FBoroughShape.vue

@@ -6,7 +6,7 @@
 // Deliberately does one thing. No data, no ramp, no labels, no wards, no selection — the moment a
 // caller wants any of those they want FLondonMap. Keeping this presentational is the whole point.
 import { computed } from 'vue';
-import { LONDON_BOROUGHS, indexAreas } from './londonAreas';
+import { LONDON_BOROUGHS, frameArea } from './londonAreas';
 
 const props = withDefaults(
   defineProps<{
@@ -24,22 +24,14 @@ const props = withDefaults(
 );
 
 // Boroughs only — the ward set is loaded on demand elsewhere, and a glyph has no reason to pull it.
-const area = computed(() => indexAreas(LONDON_BOROUGHS.areas).get(props.borough.toLowerCase()));
-
-// Framed to the shape's own bounds, from the stored box — no path parsing. An unknown borough draws
-// nothing rather than a stray full-London frame.
-const viewBox = computed(() => {
-  const a = area.value;
-  if (!a) return undefined;
-  const p = Math.max(a.w, a.h) * props.pad;
-  return `${a.x - p} ${a.y - p} ${a.w + p * 2} ${a.h + p * 2}`;
-});
+// Framed to the shape's own bounds from the stored box, no path parsing.
+const framed = computed(() => frameArea(LONDON_BOROUGHS.areas, props.borough, props.pad));
 </script>
 
 <template>
   <svg
-    v-if="area"
-    :viewBox="viewBox"
+    v-if="framed"
+    :viewBox="framed.viewBox"
     xmlns="http://www.w3.org/2000/svg"
     :role="label ? 'img' : undefined"
     :aria-label="label"
@@ -47,6 +39,6 @@ const viewBox = computed(() => {
   >
     <!-- currentColor so a text-* class paints the fill; non-scaling-stroke keeps any border the
          caller adds one hairline whatever the rendered size. -->
-    <path :d="area.d" fill="currentColor" vector-effect="non-scaling-stroke" />
+    <path :d="framed.area.d" fill="currentColor" vector-effect="non-scaling-stroke" />
   </svg>
 </template>

package/src/FChartFrame.vue

@@ -15,7 +15,7 @@ import type {
 } 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 { chartLabel, fromCategories } from './fromCategories';
 import { forestTooltip, type ForestTooltipOptions } from './forestTooltip';
 import { motionDuration } from './motionDuration';
 import {
@@ -70,6 +70,8 @@ const props = withDefaults(
     duration?: number;
     /** Extra signals that must remount the chart (theme flips and palette identity are automatic). */
     repaintOn?: unknown[];
+    /** The chart's accessible name. Defaults to its series, as "Chart: Trips, Utilisation". */
+    ariaLabel?: string;
   }>(),
   {
     height: 280,
@@ -164,7 +166,12 @@ const repaintKey = computed(() =>
 </script>
 
 <template>
-  <div ref="rootEl" style="display: flex; flex-direction: column; gap: 0.75rem">
+  <div
+    ref="rootEl"
+    role="img"
+    :aria-label="chartLabel(categories, ariaLabel)"
+    style="display: flex; flex-direction: column; gap: 0.75rem"
+  >
     <VisXYContainer
       :key="repaintKey"
       :data="data"

package/src/FChartFrameSingle.vue

@@ -8,7 +8,7 @@ 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 { chartLabel, fromCategories } from './fromCategories';
 import { motionDuration } from './motionDuration';
 import { tooltipDefaults, tooltipContainer } from './presets';
 import { useThemeVersion } from './useThemeVersion';
@@ -37,6 +37,9 @@ const props = withDefaults(
     duration?: number;
     /** Extra signals that must remount the chart (theme flips and palette identity are automatic). */
     repaintOn?: unknown[];
+    /** The chart's accessible name. Defaults to its categories, as "Chart: Trips, Utilisation", or
+     *  "Chart" without any — a chart that labels directly should name itself here. */
+    ariaLabel?: string;
   }>(),
   { height: 260, legend: true, legendPosition: 'bottom', followCursor: false, repaintOn: () => [] },
 );
@@ -71,7 +74,12 @@ const repaintKey = computed(() =>
 </script>
 
 <template>
-  <div ref="rootEl" style="display: flex; flex-direction: column; gap: 0.75rem">
+  <div
+    ref="rootEl"
+    role="img"
+    :aria-label="chartLabel(categories, ariaLabel)"
+    style="display: flex; flex-direction: column; gap: 0.75rem"
+  >
     <VisSingleContainer
       :key="repaintKey"
       :data="data"

package/src/FDistributionBar.vue

@@ -26,6 +26,7 @@
 import { computed, ref } from 'vue';
 import { categoricalVar, type CategoricalPalette } from './useChartPalette';
 import {
+  distributionLabel,
   distributionShares,
   formatShare,
   segmentRadius,
@@ -105,17 +106,7 @@ const trackCount = computed(() => drawn.value.length + (shares.value.remainder >
 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 label = computed(() => props.ariaLabel || distributionLabel(shares.value, props.locale));
 
 const interactive = computed(() => props.tooltip !== false);
 

package/src/FSparkline.vue

@@ -18,7 +18,7 @@ import { VisXYContainer, VisLine, VisArea } from '@unovis/vue';
 import { CurveType } from '@unovis/ts';
 import { motionDuration } from './motionDuration';
 import { useThemeVersion } from './useThemeVersion';
-import { sparklineDomain } from './sparklineDomain';
+import { sparklineBar, sparklineBarDomain, sparklineDomain, sparklineEndpoint } from './sparklineDomain';
 
 const props = withDefaults(
   defineProps<{
@@ -74,9 +74,15 @@ const props = withDefaults(
      * counts belong to them.
      *
      * `compare`, `area`, `endpoint` and `curve` are line-only; a dev-mode warning fires if one is
-     * passed alongside `bar` rather than being silently dropped.
+     * set alongside `bar` rather than being silently dropped. `curve` is on by default, so for it
+     * the warning is for `:curve="false"`.
      */
     mark?: 'line' | 'bar';
+    /**
+     * The graphic's accessible name. With it the sparkline is announced as an image; without it it is
+     * decorative and hidden from the accessibility tree, the reading being the figure beside it.
+     */
+    ariaLabel?: string;
   }>(),
   { height: 32, color: 'var(--ui-primary)', area: false, endpoint: false, fill: false, curve: true, mark: 'line', compare: undefined, compareColor: undefined },
 );
@@ -84,7 +90,10 @@ const props = withDefaults(
 if (import.meta.env.DEV) {
   watchEffect(() => {
     if (props.mark !== 'bar') return;
-    const ignored = (['compare', 'area', 'endpoint'] as const).filter((k) => props[k]);
+    const ignored = [
+      ...(['compare', 'area', 'endpoint'] as const).filter((k) => props[k]),
+      ...(props.curve ? [] : ['curve']),
+    ];
     if (ignored.length)
       console.warn(`[FSparkline] \`${ignored.join('`, `')}\` ${ignored.length > 1 ? 'are' : 'is'} line-only and ignored under mark="bar".`);
   });
@@ -114,47 +123,24 @@ const hasCompare = computed(() => !!props.compare?.some((v) => v !== null && v !
 // the floor at 0 it runs from 0 up to each reading's height above the floor.
 const frame = computed(() => sparklineDomain(props.data, props.compare, props.area));
 
-// Bars are the exception: they are measured from zero, not from the data's own floor. A bar reads
-// as a LENGTH, and a bar that starts anywhere but zero has a length no longer proportional to its
-// value. The bar domain therefore always contains zero, which also puts negative readings below the
-// baseline instead of quietly flipping them.
-const barDomain = computed(() => {
-  const vals = props.data.filter((v): v is number => v !== null);
-  const lo = Math.min(0, ...vals);
-  const hi = Math.max(0, ...vals);
-  return { lo, span: hi - lo || 1 };
-});
-
-/** Bottom offset and height as percentages, or null for a gap. */
-const barFor = (v: number | null) => {
-  if (v === null) return null;
-  const { lo, span } = barDomain.value;
-  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)`,
-  };
-};
+// Bars are the exception: measured from zero, not from the data's own floor. Why lives in
+// sparklineBarDomain.
+const barDomain = computed(() => sparklineBarDomain(props.data));
+const barFor = (v: number | null) => sparklineBar(v, barDomain.value);
 
-const last = computed(() => {
-  for (let i = props.data.length - 1; i >= 0; i--) if (props.data[i] !== null) return props.data[i] as number;
-  return null;
-});
-// Fraction of the height the final point sits at, for the endpoint dot.
-const endpointTop = computed(() => {
-  const [lo, hi] = frame.value.domain ?? [0, 0];
-  if (last.value === null || hi === lo) return 50;
-  return (1 - (last.value - frame.value.floor - lo) / (hi - lo)) * 100;
-});
+// Percentage down the height for the endpoint dot, or null when there is no reading to mark.
+const endpointTop = computed(() => sparklineEndpoint(props.data, frame.value));
 </script>
 
 <template>
-  <div class="relative w-full" :class="fill ? 'h-full' : ''" :style="fill ? { minHeight: `${height}px`, color } : { height: `${height}px`, color }">
+  <div
+    class="relative w-full"
+    :class="fill ? 'h-full' : ''"
+    :style="fill ? { minHeight: `${height}px`, color } : { height: `${height}px`, color }"
+    :role="ariaLabel ? 'img' : undefined"
+    :aria-label="ariaLabel || undefined"
+    :aria-hidden="ariaLabel ? undefined : 'true'"
+  >
     <!-- Plain DOM rather than a mark: there are no axes, scales or tooltip to share with the XY
          container, so a flex row of columns is the whole implementation and costs no chart runtime.
          The 2px gap is fixed, so the bucket count sets how thin the bars get: n buckets across w
@@ -162,7 +148,7 @@ const endpointTop = computed(() => {
          2.7px — still bars; past roughly 60 the gap outweighs the bar and the row reads as a
          texture, where the measure belongs to a line instead. Each bar is rounded at both ends:
          no baseline is drawn for a square end to sit on. -->
-    <div v-if="mark === 'bar'" class="flex w-full items-end gap-0.5" :class="fill ? 'absolute inset-0' : 'h-full'" aria-hidden="true">
+    <div v-if="mark === 'bar'" class="flex w-full items-end gap-0.5" :class="fill ? 'absolute inset-0' : 'h-full'">
       <span
         v-for="(v, i) in data"
         :key="i"
@@ -211,7 +197,7 @@ const endpointTop = computed(() => {
       <VisLine :x="x" :y="y" :color="color" :line-width="1.5" :curve-type="curve ? CurveType.MonotoneX : CurveType.Linear" />
     </VisXYContainer>
     <span
-      v-if="mark === 'line' && endpoint && last !== null"
+      v-if="mark === 'line' && endpoint && endpointTop !== null"
       class="pointer-events-none absolute right-0 size-1.5 -translate-y-1/2 rounded-full bg-current"
       :style="{ top: `${endpointTop}%` }"
       aria-hidden="true"

package/src/distribution.ts

@@ -88,6 +88,18 @@ export function segmentRadius(index: number, count: number, radius: number, join
   return '0';
 }
 
+/**
+ * The bar's sentence for assistive tech: each part with its share, then any remainder, as
+ * "Food 62%, Software 24%, unaccounted 14%". The bar's lengths are the only place the shares are
+ * stated unless `showShare` is on, so the sentence carries them regardless. A bar with nothing to
+ * state is "No data", because the element carrying it needs a non-empty name.
+ */
+export function distributionLabel(shares: DistributionShares, locale = 'en-GB'): string {
+  const parts = shares.parts.map((p) => `${p.segment.label} ${formatShare(p.share, locale)}`);
+  if (shares.remainder > 0) parts.push(`unaccounted ${formatShare(shares.remainder, locale)}`);
+  return parts.join(', ') || 'No data';
+}
+
 /**
  * A share as a percentage. Whole numbers: at the width this component is read at, a decimal place
  * is precision the bar itself cannot show. A non-zero share that would round to nothing is stated

package/src/forestTooltip.ts

@@ -97,7 +97,7 @@ export function forestTooltip<Datum extends Record<string, unknown>>(
     const present = keys.filter((k) => k in d);
     const title = opts.titleFormatter ? opts.titleFormatter(d) : Object.values(d)[0];
     const rows: ForestTipRow[] = present.map((k, i) => {
-      const item = categories[k];
+      const item = categories[k]!;
       const raw = d[k];
       return {
         swatch: typeof item.color === 'string' ? item.color : `var(--vis-color${i})`,

package/src/fromCategories.ts

@@ -35,9 +35,22 @@ export function fromCategories<Datum extends Record<string, unknown>>(
       : Array.isArray(item.color) && typeof item.color[0] === 'string' ? item.color[0]
         : `var(--vis-color${i})`;
   return {
-    colors: keys.map((k, i) => colorOf(categories[k], i)),
-    legendItems: keys.map((k, i) => ({ ...categories[k], color: colorOf(categories[k], i) })),
+    colors: keys.map((k, i) => colorOf(categories[k]!, i)),
+    legendItems: keys.map((k, i) => ({ ...categories[k]!, color: colorOf(categories[k]!, i) })),
     yAccessors: keys.map((k) => (d: Datum) => d[k] as number | null | undefined),
     xAccessor: xKey ? (d) => d[xKey] as number : (_d, i) => i,
   };
 }
+
+/**
+ * A chart frame's accessible name: `ariaLabel` when given, otherwise the series it plots, as
+ * "Chart: Trips, Utilisation". With no categories it is "Chart".
+ */
+export function chartLabel(
+  categories: Record<string, BulletLegendItemInterface> | undefined,
+  ariaLabel?: string,
+): string {
+  if (ariaLabel) return ariaLabel;
+  const names = Object.entries(categories ?? {}).map(([key, item]) => String(item.name ?? key));
+  return names.length ? `Chart: ${names.join(', ')}` : 'Chart';
+}

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,19 @@ export const indexAreas = (areas: LondonArea[]): Map<string, LondonArea> => {
   }
   return byKey;
 };
+
+/**
+ * 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}` };
+};

package/src/resolveVar.ts

@@ -16,6 +16,6 @@
 /** The computed value of a `var(--x)` string. Non-var strings pass through untouched. */
 export function resolveVar(value: string, context: Element = document.documentElement): string {
   if (typeof window === 'undefined' || !value.startsWith('var(--')) return value;
-  const name = value.slice(4, -1).split(',')[0].trim();
+  const name = value.slice(4, -1).split(',')[0]!.trim();
   return getComputedStyle(context).getPropertyValue(name).trim() || value;
 }

package/src/snapTooltip.ts

@@ -40,7 +40,7 @@ const clamp = (v: number, lo: number, hi: number): number => Math.min(Math.max(v
  *  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 } {
+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 +63,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(
@@ -104,24 +129,17 @@ 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';

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,65 @@ 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;
+}

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';
@@ -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();
@@ -118,9 +121,9 @@ export function useCellScale<D>(options: CellScaleOptions<D>) {
       const stops = swatches.value;
       // A flat domain has no gradient to express — everything sits at the top stop rather than
       // dividing by zero.
-      if (hi <= lo) return stops[stops.length - 1];
+      if (hi <= lo) return stops[stops.length - 1]!;
       const t = Math.min(1, Math.max(0, (v - lo) / (hi - lo)));
-      return stops[Math.min(stops.length - 1, Math.floor(t * stops.length))];
+      return stops[Math.min(stops.length - 1, Math.floor(t * stops.length))]!;
     }
     const states = unref(options.states) ?? {};
     const key = options.state!(d as D) as string;