@humanforest/nuxt-layer 0.1.0

package/packages/charts/src/FStatusTrack.vue

@@ -0,0 +1,151 @@
+<script setup lang="ts" generic="D extends Record<string, unknown>">
+// A row of segments, one per bucket, each carrying a state or an intensity. One asset per track:
+// a dock's health across ninety days, a bike's week. Colour resolution is useCellScale's; this
+// component is layout, labels and the interaction surface.
+//
+// Plain DOM rather than SVG — the segments are a flex row, so the browser does the layout, and an
+// interactive segment can be a real <button> that focuses and announces itself.
+import { computed, ref } from 'vue';
+import type { BulletLegendItemInterface } from '@unovis/ts';
+import { useCellScale, CELL_EMPTY_COLOR, type SequentialRamp } from './useCellScale';
+import { CELL_SIZES, orElse, type CellSize } from './cellSize';
+import FCellLegend from './FCellLegend.vue';
+
+const props = withDefaults(
+  defineProps<{
+    data: D[];
+    /** `state` colours by category, `intensity` buckets a number onto a sequential ramp. */
+    mode?: 'state' | 'intensity';
+    /** State mode: same map shape as `categories` elsewhere. */
+    states?: Record<string, BulletLegendItemInterface>;
+    /** State accessor. Returning null/undefined makes the segment empty. */
+    state?: (d: D) => string | null | undefined;
+    /** Intensity accessor. A non-number makes the segment empty. */
+    value?: (d: D) => number | null | undefined;
+    ramp?: SequentialRamp;
+    /** Intensity domain. Set it explicitly when two tracks are read against each other. */
+    domain?: [number, number];
+    steps?: number;
+    /** Leading gutter label — the asset this track is about. */
+    label?: string;
+    /** Size step. Sets the track height and segment spacing, and whether the label, captions,
+     *  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 — label, captions, summary, legend and
+     *  tooltips together. `legend` still wins over it for the legend alone. */
+    chrome?: boolean;
+    height?: number;
+    segmentGap?: number;
+    radius?: number;
+    legend?: boolean;
+    /** Start and end captions under the track, e.g. ['90 days ago', 'Today']. */
+    caption?: [string, string];
+    /** Hover and focus text. Given one, segments become focusable buttons and get the house bubble.
+     *  Suppressed at xs and sm, where a segment is too thin to hit reliably. */
+    tooltip?: (d: D, i: number) => string;
+    /** Sentence for assistive tech describing the whole track. */
+    ariaLabel?: string;
+  }>(),
+  {
+    mode: 'state',
+    size: 'md',
+    steps: 5,
+    /* 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,
+  },
+);
+
+// Three tiers, narrowest first: an individual prop beats `chrome`, which beats the size step.
+const spec = computed(() => CELL_SIZES[props.size]);
+const height = computed(() => orElse(props.height, spec.value.trackHeight));
+const segmentGap = computed(() => orElse(props.segmentGap, spec.value.trackGap));
+const radius = computed(() => orElse(props.radius, spec.value.radius));
+const showChrome = computed(() => orElse(props.chrome, spec.value.chrome));
+const showLegend = computed(() => orElse(props.legend, showChrome.value));
+const interactive = computed(() => !!props.tooltip && showChrome.value);
+
+const scale = useCellScale<D>({
+  mode: 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: props.value,
+  state: props.state,
+});
+
+// The label an assistive reader gets per segment. Without a tooltip the segments are decorative and
+// the track's own label carries the meaning, so this is only consulted when one is given.
+const labelFor = (d: D, i: number) => props.tooltip?.(d, i) ?? '';
+
+const trackLabel = computed(
+  () => props.ariaLabel ?? `${props.label ? `${props.label}: ` : ''}${props.data.length} segments`,
+);
+
+// One UTooltip for the track, re-anchored to the segment under the pointer via `reference`, rather
+// than one per segment: a ninety-day track costs a single tooltip root either way.
+//
+// `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 rather than the pointer, so a keyboard focus places it too.
+const tip = ref<{ text: string; el: Element | null }>({ text: '', el: null });
+const tipOpen = ref(false);
+const showTip = (event: Event, text: string) => {
+  tip.value = { text, el: event.currentTarget as Element };
+  tipOpen.value = true;
+};
+const hideTip = () => {
+  tipOpen.value = false;
+};
+</script>
+
+<template>
+  <div class="flex w-full flex-col gap-2">
+    <div class="flex items-center gap-3">
+      <span v-if="label && showChrome" class="type-label shrink-0 text-default">{{ label }}</span>
+      <UTooltip :text="tip.text" :reference="tip.el" :open="tipOpen">
+        <div
+          class="flex min-w-0 flex-1"
+          :role="interactive ? 'group' : 'img'"
+          :aria-label="trackLabel"
+          :style="{ gap: `${segmentGap}px`, height: `${height}px` }"
+        >
+          <component
+            :is="interactive ? 'button' : 'div'"
+            v-for="(d, i) in data"
+            :key="i"
+            :type="interactive ? 'button' : undefined"
+            class="min-w-0 flex-1 transition-[filter] duration-150 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--ui-primary)]"
+            :class="interactive ? 'cursor-pointer hover:brightness-110' : ''"
+            :style="{ background: scale.colorOf(d), borderRadius: `${radius}px` }"
+            :aria-label="interactive ? labelFor(d, i) : undefined"
+            :aria-hidden="interactive ? undefined : 'true'"
+            @mouseenter="interactive && showTip($event, labelFor(d, i))"
+            @mouseleave="hideTip"
+            @focus="interactive && showTip($event, labelFor(d, i))"
+            @blur="hideTip"
+          />
+        </div>
+      </UTooltip>
+      <span v-if="$slots.summary && showChrome" class="type-label shrink-0 text-muted"><slot name="summary" /></span>
+    </div>
+
+    <div v-if="caption && showChrome" class="flex justify-between">
+      <span class="type-caption text-dimmed">{{ caption[0] }}</span>
+      <span class="type-caption text-dimmed">{{ caption[1] }}</span>
+    </div>
+
+    <FCellLegend
+      v-if="showLegend"
+      :legend="scale.legend.value"
+      :show-empty="data.some((d) => scale.isEmpty(d))"
+      :empty-color="CELL_EMPTY_COLOR"
+    />
+  </div>
+</template>

package/packages/charts/src/cellSize.ts

@@ -0,0 +1,46 @@
+// Size scale for the cell components, and the chrome that comes with each step.
+//
+// A size is not only a cell dimension: below a certain size the furniture stops being legible and
+// starts being noise. A 6px cell cannot carry a weekday label beside it, a legend under a 12px
+// track is taller than the track, and a tooltip on a 6px target is a coin toss. So each step
+// declares whether chrome is on, and the components read that as the DEFAULT — an explicit prop
+// always wins, because a caller who asks for a legend at xs has a reason.
+export type CellSize = 'xs' | 'sm' | 'md' | 'lg';
+
+export interface CellSizeSpec {
+  /** Calendar cell edge, px. */
+  cell: number;
+  /** Space between cells, px. Also the calendar's month-rule bed. */
+  gap: number;
+  /** Corner radius, px. */
+  radius: number;
+  /** Status track height, px. */
+  trackHeight: number;
+  /** Space between track segments, px. */
+  trackGap: number;
+  /** Dotted map dot diameter, px. */
+  dot: number;
+  /** Space between dots, px. */
+  dotGap: number;
+  /** Labels, legend and tooltips default on at this size. */
+  chrome: boolean;
+}
+
+// The dot steps are their own numbers rather than the cell ones. A map is ninety-six dots across
+// where a calendar is fifty-two weeks and a track is one row, so reusing `cell` would make the
+// smallest map wider than the largest calendar. What the steps share is the chrome decision, which
+// is the part that has to agree across the family.
+export const CELL_SIZES: Record<CellSize, CellSizeSpec> = {
+  // FSparkline scale: a texture, read at a glance inside a table cell or a KPI tile.
+  xs: { cell: 6, gap: 1, radius: 1, trackHeight: 12, trackGap: 1, dot: 2, dotGap: 0, chrome: false },
+  // Compact: still a picture rather than a chart. Chrome off — an 8px cell leaves no room beside it.
+  sm: { cell: 8, gap: 2, radius: 2, trackHeight: 20, trackGap: 2, dot: 3, dotGap: 1, chrome: false },
+  // The documented default, and the size the guidance is written for.
+  md: { cell: 11, gap: 3, radius: 2, trackHeight: 32, trackGap: 2, dot: 5, dotGap: 1, chrome: true },
+  // Presentation scale: a chart that owns its section.
+  lg: { cell: 14, gap: 4, radius: 3, trackHeight: 44, trackGap: 3, dot: 7, dotGap: 1, chrome: true },
+};
+
+/** `explicit ?? fallback`, written out because `||` would swallow a deliberate 0. */
+export const orElse = <T>(explicit: T | undefined, fallback: T): T =>
+  explicit === undefined ? fallback : explicit;

package/packages/charts/src/distribution.ts

@@ -0,0 +1,99 @@
+// Share maths and track geometry for FDistributionBar, kept out of the SFC so both can be tested
+// without a DOM.
+
+export interface DistributionSegment {
+  label: string;
+  value: number;
+  /** Any CSS colour. Defaults to the palette slot for the segment's position. */
+  color?: string;
+}
+
+export interface DistributionShare {
+  segment: DistributionSegment;
+  /** Position in the original `data`, so the palette slot survives filtering. */
+  index: number;
+  /** 0–1 of the total. */
+  share: number;
+}
+
+export interface DistributionShares {
+  parts: DistributionShare[];
+  /** 0–1 of the total that no segment accounts for. Zero unless `total` exceeds the values' sum. */
+  remainder: number;
+  total: number;
+}
+
+/**
+ * Shares of the whole.
+ *
+ * `total` defaults to the values' sum, which makes the bar a pure composition — the parts fill it.
+ * Passing a larger total leaves a remainder, which makes it a figure measured against its ceiling:
+ * 78% of capacity, split by what used it.
+ *
+ * A negative value is read as zero. A bar cannot draw a negative width, and folding one into the
+ * total would shrink every other segment to pay for it — the figure would be wrong rather than
+ * merely missing. A total smaller than the sum is raised to the sum for the same reason: the
+ * alternative is shares over 100% and a bar that overflows its own track.
+ */
+export function distributionShares(
+  data: readonly DistributionSegment[],
+  total?: number,
+): DistributionShares {
+  const parts = data.map((segment, index) => ({
+    segment,
+    index,
+    value: Math.max(0, segment.value) || 0,
+  }));
+  const sum = parts.reduce((n, p) => n + p.value, 0);
+  const whole = Math.max(sum, total ?? 0);
+
+  // No whole means no shares to state. Returning zeros rather than dividing keeps NaN out of the
+  // grid template, where it would collapse every track instead of rendering an empty bar.
+  if (whole <= 0) {
+    return { parts: parts.map((p) => ({ segment: p.segment, index: p.index, share: 0 })), remainder: 0, total: 0 };
+  }
+
+  return {
+    parts: parts.map((p) => ({ segment: p.segment, index: p.index, share: p.value / whole })),
+    remainder: (whole - sum) / whole,
+    total: whole,
+  };
+}
+
+/**
+ * One track's `border-radius`.
+ *
+ * Split (the default), every track is its own pill — the gap is what separates them, and the round
+ * ends are what make each one read as a separate object.
+ *
+ * Joined, the gap is gone, so pills would butt into each other and pinch at every seam. The bar has
+ * to be shaped as ONE object instead: the outside corners of the whole bar are round and every
+ * internal seam is square. A single track is both ends at once, so it stays a full pill.
+ *
+ * `count` is the number of tracks actually drawn — zero-share segments are filtered out before this
+ * and the remainder, when there is one, counts as the last track. So `index` is a position among
+ * drawn tracks, NOT an index into `data`.
+ *
+ * Left-to-right, matching the drawing order the component documents; a right-to-left bar would need
+ * the logical corner properties instead of this shorthand.
+ */
+export function segmentRadius(index: number, count: number, radius: number, joined: boolean): string {
+  const r = `${radius}px`;
+  if (!joined) return r;
+  const first = index === 0;
+  const last = index === count - 1;
+  if (first && last) return r;
+  if (first) return `${r} 0 0 ${r}`;
+  if (last) return `0 ${r} ${r} 0`;
+  return '0';
+}
+
+/**
+ * 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
+ * as "<1%" rather than "0%", which would read as a category that isn't there.
+ */
+export function formatShare(share: number, locale = 'en-GB'): string {
+  if (share > 0 && share < 0.005) return `<1%`;
+  return new Intl.NumberFormat(locale, { style: 'percent', maximumFractionDigits: 0 }).format(share);
+}

package/packages/charts/src/engine.ts

@@ -0,0 +1,15 @@
+// Palette data seam. The colour engine is canonical at packages/tokens/src/colourEngine.ts — the
+// package whose CSS and JSON it generates — and is reached here in exactly one place, the same way
+// scripts/dataviz.ts reaches it at build time. Everything else in this package goes through this
+// re-export, so a future move of the engine touches one line.
+//
+// Relative, not `@humanforest/tokens/colourEngine`: the Nuxt layer mirrors these trees at
+// repo-relative paths and never rewrites their imports, and a bare specifier would need tokens
+// resolvable from the layer — which it is not, since nothing @humanforest/* is published yet.
+export {
+  DATAVIZ,
+  DATAVIZ_PAIRS,
+  DATAVIZ_CATEGORICAL,
+  DATAVIZ_SEQUENTIAL,
+  DATAVIZ_DIVERGING,
+} from '@humanforest/tokens/colourEngine';

package/packages/charts/src/forestTooltip.ts

@@ -0,0 +1,110 @@
+// Crosshair/tooltip template builder. Unovis crosshair and tooltip config take a function that
+// returns an HTML STRING, so this is code, not config. The markup is the house tooltip — a title
+// row, then a swatch/label/value grid with tabular numerals — styled through the --vis-tooltip-*
+// custom properties the adapter themes, so nothing here hardcodes a colour.
+import type { BulletLegendItemInterface } from '@unovis/ts';
+
+// Every interpolated string passes through here: the output is innerHTML on the tooltip element,
+// and titles, series names and formatted values are arbitrary text.
+const esc = (value: unknown): string =>
+  String(value)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+
+export interface ForestTooltipOptions<Datum> {
+  /** Title text for the hovered row. Default: the datum's first property value. */
+  titleFormatter?: (d: Datum) => string | number;
+  /** Formats each series value. Default: the raw value, stringified. */
+  valueFormatter?: (value: number) => string | number;
+}
+
+const TITLE_STYLE = (hasRows: boolean) =>
+  'color:var(--vis-tooltip-title-color,#000);' +
+  'text-transform:var(--vis-tooltip-title-text-transform,capitalize);' +
+  `border-bottom:${hasRows ? 'var(--vis-tooltip-title-border-bottom,1px solid #e5e7eb)' : 'none'};` +
+  'padding:var(--vis-tooltip-title-padding,0.75rem 0.75rem 0.5rem 0.75rem);' +
+  `margin:${hasRows ? 'var(--vis-tooltip-title-margin,0 0 0.25rem 0)' : '0'};` +
+  'font-size:var(--vis-tooltip-title-font-size,0.875rem);' +
+  'line-height:var(--vis-tooltip-title-line-height,100%);' +
+  'font-weight:var(--vis-tooltip-title-font-weight,600)';
+
+const GRID_STYLE =
+  'display:grid;grid-template-columns:auto 1fr auto;align-items:center;' +
+  'gap:var(--vis-tooltip-content-gap,0.25rem 0.5rem);' +
+  'padding:var(--vis-tooltip-content-padding,0 0.75rem 0.5rem 0.75rem)';
+
+const DOT_STYLE =
+  'width:8px;height:8px;aspect-ratio:1;flex-shrink:0;' +
+  'border-radius:var(--vis-tooltip-dot-border-radius,4px);' +
+  'margin:var(--vis-tooltip-dot-margin,0);';
+
+const LABEL_STYLE =
+  'font-weight:var(--vis-tooltip-label-font-weight,400);' +
+  'font-size:var(--vis-tooltip-label-font-size,0.875rem);' +
+  'color:var(--vis-tooltip-label-color,inherit);' +
+  'margin:var(--vis-tooltip-label-margin,0 1rem 0 0);white-space:nowrap';
+
+const VALUE_STYLE =
+  'font-size:var(--vis-tooltip-value-font-size,0.875rem);' +
+  'font-weight:var(--vis-tooltip-value-font-weight,600);' +
+  'color:var(--vis-tooltip-value-color,inherit);' +
+  'text-align:right;font-variant-numeric:tabular-nums';
+
+export interface ForestTipRow {
+  /** Swatch dot colour (any CSS colour string). Omit for a row without a dot. */
+  swatch?: string;
+  label: string;
+  value: string | number;
+}
+
+/**
+ * The house tooltip chrome — title bar plus swatch/label/value grid — as a plain string builder,
+ * for bespoke templates (Donut/Bubble/Gantt/Treemap `triggers`, custom crosshairs) that need the
+ * house look without the categories-map plumbing. The chrome carries its own padding: the adapter
+ * zeroes --vis-tooltip-padding on the container, so a template built outside this frame renders
+ * cramped against the tooltip edge.
+ */
+export function forestTipFrame(title: string | number, rows: ForestTipRow[] = []): string {
+  const body = rows
+    .map((r) =>
+      `<span style="${DOT_STYLE}${r.swatch ? `background-color:${esc(r.swatch)}` : 'visibility:hidden'}"></span>` +
+      `<span style="${LABEL_STYLE}">${esc(r.label)}</span>` +
+      `<span style="${VALUE_STYLE}">${esc(r.value)}</span>`,
+    )
+    .join('');
+  return (
+    '<div style="display:flex;flex-direction:column">' +
+    `<div style="${TITLE_STYLE(rows.length > 0)}">${esc(title)}</div>` +
+    (rows.length > 0 ? `<div style="${GRID_STYLE}">${body}</div>` : '') +
+    '</div>'
+  );
+}
+
+/**
+ * Builds the template function for `<VisCrosshair :template>` (or tooltip `triggers`). Rows are
+ * the category keys present on the hovered datum, in category order; a series without a string
+ * colour wears the adapter's --vis-colorN slot, mirroring the legend.
+ */
+export function forestTooltip<Datum extends Record<string, unknown>>(
+  categories: Record<string, BulletLegendItemInterface>,
+  opts: ForestTooltipOptions<Datum> = {},
+): (d: Datum) => string {
+  const keys = Object.keys(categories);
+  return (d: Datum): string => {
+    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 raw = d[k];
+      return {
+        swatch: typeof item.color === 'string' ? item.color : `var(--vis-color${i})`,
+        label: String(item.name),
+        value: opts.valueFormatter ? opts.valueFormatter(Number(raw)) : String(raw),
+      };
+    });
+    return forestTipFrame(String(title), rows);
+  };
+}

package/packages/charts/src/fromCategories.ts

@@ -0,0 +1,43 @@
+// The derivation every direct-Unovis call site hand-writes: a `categories` map (as returned by
+// useChartPalette's accessors) unpacked into the ordered arrays Unovis components actually take.
+import type { BulletLegendItemInterface } from '@unovis/ts';
+
+export interface ChartAccessors<Datum> {
+  /** Ordered series colours; a category without a string colour falls back to the adapter's --vis-colorN slot. */
+  colors: string[];
+  /** Ordered legend entries for `<VisBulletLegend :items>`; multi-colour series show their first colour. */
+  legendItems: BulletLegendItemInterface[];
+  /**
+   * One accessor per series key, in category order. Values pass through untouched — a null or
+   * undefined cell stays null/undefined (Unovis' NumericAccessor accepts both and renders the
+   * gap); coercing would plot missing data as zero.
+   */
+  yAccessors: Array<(d: Datum) => number | null | undefined>;
+  /** X accessor: the row's `xKey` value when one is given, otherwise the array index —
+   *  the house convention: rows are evenly spaced, the axis formats the label. */
+  xAccessor: (d: Datum, i: number) => number;
+}
+
+/**
+ * Derives `{ colors, legendItems, yAccessors, xAccessor }` from a categories map.
+ * `data` is never read — pass it (or the datum type parameter) to anchor the accessors' typing.
+ * `xKey` names a numeric field (e.g. a timestamp) to plot on x instead of the row index.
+ */
+export function fromCategories<Datum extends Record<string, unknown>>(
+  categories: Record<string, BulletLegendItemInterface>,
+  data?: readonly Datum[],
+  xKey?: keyof Datum & string,
+): ChartAccessors<Datum> {
+  void data;
+  const keys = Object.keys(categories);
+  const colorOf = (item: BulletLegendItemInterface, i: number): string =>
+    typeof item.color === 'string' ? item.color
+      : 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) })),
+    yAccessors: keys.map((k) => (d: Datum) => d[k] as number | null | undefined),
+    xAccessor: xKey ? (d) => d[xKey] as number : (_d, i) => i,
+  };
+}

package/packages/charts/src/index.ts

@@ -0,0 +1,87 @@
+// @humanforest/charts — the chart frames plus palette accessors and helpers for building charts
+// directly on @unovis/vue. The frames wrap ceremony only (container, axes, legend,
+// tooltip/crosshair, repaint, motion); marks stay real @unovis/vue components in the #mark slot.
+// Importing this barrel needs an SFC pipeline (Vite/Nuxt) — everything here is browser-bound.
+export { default as FChartFrame } from './FChartFrame.vue';
+export { default as FChartFrameSingle } from './FChartFrameSingle.vue';
+export { default as FChartLegend } from './FChartLegend.vue';
+// Word-sized graphic for a KPI tile's `visual` slot: shape only, no axes, no tooltip.
+export { default as FSparkline } from './FSparkline.vue';
+// The other tile-sized graphic: one bar split into its parts, for what a figure is made of.
+export { default as FDistributionBar } from './FDistributionBar.vue';
+export {
+  distributionShares,
+  formatShare,
+  type DistributionSegment,
+  type DistributionShare,
+  type DistributionShares,
+} from './distribution';
+// Cell components — regular DOM on a grid, not Unovis marks. State or intensity per bucket.
+export { default as FStatusTrack } from './FStatusTrack.vue';
+export { default as FCalendarGrid } from './FCalendarGrid.vue';
+export { default as FDottedMap } from './FDottedMap.vue';
+export { default as FLondonMap } from './FLondonMap.vue';
+// A single borough as a styleable graphic (currentColor glyph), not a data-filled chart.
+export { default as FBoroughShape } from './FBoroughShape.vue';
+export {
+  LONDON_GRID,
+  RIVER_COLOR,
+  loadLondonGrid,
+  dotAt,
+  dotKey,
+  type LondonGrid,
+  type DotDensity,
+} from './londonGrid';
+export {
+  LONDON_BOROUGHS,
+  loadLondonWards,
+  indexAreas,
+  type LondonArea,
+  type LondonAreaSet,
+  type AreaLevel,
+} from './londonAreas';
+export { default as FCellLegend } from './FCellLegend.vue';
+export { CELL_SIZES, orElse, type CellSize, type CellSizeSpec } from './cellSize';
+export {
+  useCellScale,
+  CELL_EMPTY_COLOR,
+  type CellScaleOptions,
+  type CellScale,
+  // The interface keeps its unprefixed name — the F prefix marks components, not types. It no
+  // longer collides with the component now that one is FCellLegend, but the public alias stays as
+  // it was so consumers do not have to change.
+  type CellLegend as CellLegendData,
+  type CellLegendEntry,
+  type SequentialRamp,
+} from './useCellScale';
+export { useThemeVersion } from './useThemeVersion';
+export { resolveVar } from './resolveVar';
+export {
+  useChartPalette,
+  safeVar,
+  vividVar,
+  pairsVar,
+  categoricalVar,
+  sequentialVar,
+  divergingVar,
+  type SeriesDef,
+  type CategoricalPalette,
+} from './useChartPalette';
+export {
+  axisX,
+  axisY,
+  legendDefaults,
+  tooltipDefaults,
+  houseTooltip,
+  tooltipContainer,
+  treemapDefaults,
+  nestedDonutDefaults,
+} from './presets';
+export { fromCategories, type ChartAccessors } from './fromCategories';
+export { forestTooltip, forestTipFrame, type ForestTooltipOptions, type ForestTipRow } from './forestTooltip';
+export { useChartRepaintKey } from './useChartRepaintKey';
+export { motionDuration, type MotionToken } from './motionDuration';
+// For a Vue app with no Nuxt UI. Five components wrap their marks in `<UTooltip>` — a name, not an
+// import — and this answers that name with a trigger-only stand-in. Inert wherever Nuxt UI's own
+// build plugin already resolved the tag, which is every app that has Nuxt UI.
+export { chartsWithoutNuxtUI, TooltipStandIn } from './tooltipStandIn';

package/packages/charts/src/londonAreas.ts

@@ -0,0 +1,75 @@
+// Geometry data seam for the vector maps, the same shape as engine.ts and londonGrid.ts: the
+// generated paths are reached across the workspace boundary in exactly one place.
+//
+// Built by scripts/londonAreas.ts and not editable by hand. Both levels share one viewBox, which is
+// what lets a ward map carry a borough outline over it.
+import boroughs from '@humanforest/tokens/geo/london-boroughs.json';
+
+export interface LondonArea {
+  /** ONS code — E09… for a borough, E05… for a ward. */
+  code: string;
+  name: string;
+  /** SVG path data, in viewBox units. */
+  d: string;
+  /** Label anchor: the area-weighted centroid of the area's largest ring. */
+  cx: number;
+  cy: number;
+  /**
+   * Bounding box of that ring, in viewBox units: origin (`x`, `y`) then size (`w`, `h`). `w`/`h`
+   * decide whether a label fits; the full box lets a map frame itself to one area, no path parsing.
+   */
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+  /** Wards only — the code of the borough containing this ward. */
+  borough?: string;
+}
+
+export interface LondonAreaSet {
+  viewBox: [number, number, number, number];
+  bbox: [number, number, number, number];
+  areas: LondonArea[];
+}
+
+export type AreaLevel = 'borough' | 'ward';
+
+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.
+ */
+let wardsPromise: Promise<LondonAreaSet> | null = null;
+export const loadLondonWards = (): Promise<LondonAreaSet> => {
+  wardsPromise ??= import('@humanforest/tokens/geo/london-wards.json').then(
+    (m) => (m.default ?? m) as unknown as LondonAreaSet,
+  );
+  return wardsPromise;
+};
+
+/**
+ * Look an area up by ONS code or by name, case-insensitively.
+ *
+ * Callers' data is keyed either way in practice — a warehouse table holds codes, a spreadsheet
+ * someone typed holds names — and requiring one of them would mean every caller writing the same
+ * lookup. Codes are checked first because they are unambiguous; two boroughs never share a name, but
+ * ward names repeat across boroughs, so a ward is only findable by name when that name is unique.
+ */
+export const indexAreas = (areas: LondonArea[]): Map<string, LondonArea> => {
+  const byKey = new Map<string, LondonArea>();
+  const nameCount = new Map<string, number>();
+  for (const a of areas) {
+    const n = a.name.toLowerCase();
+    nameCount.set(n, (nameCount.get(n) ?? 0) + 1);
+  }
+  for (const a of areas) {
+    byKey.set(a.code.toLowerCase(), a);
+    const n = a.name.toLowerCase();
+    if (nameCount.get(n) === 1) byKey.set(n, a);
+  }
+  return byKey;
+};