@humanforest/nuxt-layer 0.1.0

package/packages/charts/src/londonGrid.ts

@@ -0,0 +1,67 @@
+// Geometry data seam, the same shape as engine.ts: the generated grids are reached across the
+// workspace boundary in exactly one place.
+//
+// The grids are built by scripts/londonDots.ts and are not editable by hand — change the sources in
+// scripts/data/ and rebuild.
+import fine from '@humanforest/tokens/geo/london-dots-fine.json';
+
+/**
+ * How many dots the map is sampled into, which is not the same question as how large it is drawn.
+ * `size` is pixels; this is resolution. A coarse grid at lg is big dots read from across a room; a
+ * fine grid at sm is a texture.
+ */
+export type DotDensity = 'coarse' | 'medium' | 'fine' | 'ultra';
+
+export interface LondonGrid {
+  /** [lng0, lat0, lng1, lat1]. */
+  bbox: [number, number, number, number];
+  width: number;
+  height: number;
+  /** Land dots as [column, row]. Everything outside the boundary is simply absent. */
+  dots: [number, number][];
+  /** The Thames, same indexing. Painted rather than left as a hole, and never carries data. */
+  river: [number, number][];
+}
+
+/** The Thames. A flat token, not a ramp stop — the river is a label on the map, not a reading. */
+export const RIVER_COLOR = 'var(--dataviz-categorical-vivid-sky)';
+
+/** The default resolution, bundled so the common case needs no request. */
+export const LONDON_GRID = fine as unknown as LondonGrid;
+
+// The other three are fetched on use. Four grids is four times the bytes and a consumer draws at
+// one resolution, so bundling them all would charge everyone for the three they do not draw.
+const cache = new Map<DotDensity, Promise<LondonGrid>>([['fine', Promise.resolve(LONDON_GRID)]]);
+
+export const loadLondonGrid = (density: DotDensity): Promise<LondonGrid> => {
+  const hit = cache.get(density);
+  if (hit) return hit;
+  // Spelt out per case rather than built from a template: a bundler can only pre-resolve a dynamic
+  // import whose specifier it can read statically.
+  const load =
+    density === 'coarse'
+      ? import('@humanforest/tokens/geo/london-dots-coarse.json')
+      : density === 'medium'
+        ? import('@humanforest/tokens/geo/london-dots-medium.json')
+        : import('@humanforest/tokens/geo/london-dots-ultra.json');
+  const p = load.then((m) => ((m as { default?: unknown }).default ?? m) as unknown as LondonGrid);
+  cache.set(density, p);
+  return p;
+};
+
+/**
+ * A position to its dot, or null when it falls outside the grid's box.
+ *
+ * The inverse of the build step's projection — equirectangular, which over London tracks Web
+ * Mercator to well under one dot. Returning a cell that holds no land is intentional: only the
+ * caller of this can tell "outside London" from "in the river", and both are dropped alike.
+ */
+export const dotAt = (grid: LondonGrid, lat: number, lng: number): [number, number] | null => {
+  const [lng0, lat0, lng1, lat1] = grid.bbox;
+  const col = Math.floor(((lng - lng0) / (lng1 - lng0)) * grid.width);
+  const row = Math.floor(((lat1 - lat) / (lat1 - lat0)) * grid.height);
+  if (col < 0 || row < 0 || col >= grid.width || row >= grid.height) return null;
+  return [col, row];
+};
+
+export const dotKey = (col: number, row: number) => `${col},${row}`;

package/packages/charts/src/motionDuration.ts

@@ -0,0 +1,49 @@
+// Resolves a Forest --motion-* duration token to the millisecond number Unovis' `duration`
+// config takes. Charts animate on the system's motion tokens — never Unovis' built-in 600 ms,
+// never a hardcoded number — and the value is read off the live computed style, so a host that
+// re-themes the tokens changes chart timing without touching this file.
+
+export type MotionToken = 'instant' | 'fast' | 'base' | 'slow';
+
+/**
+ * The ladder's documented values, for the paths with no DOM to read (SSR, node tests).
+ *
+ * These are a COPY, and deliberately so — there is no computed style to resolve under SSR, and this
+ * file cannot import the generated packages/tokens/motion/motion.json either: packages/charts/src is
+ * mirrored into the Nuxt layer by scripts/layer.ts, whose self-containment guard rejects a relative
+ * climb into a tree the layer does not carry.
+ *
+ * So the copy is PINNED instead of trusted: packages/ui/test/motion-tokens.static.test.ts asserts this
+ * map against motion.json on every CI run, and fails if either side moves without the other.
+ */
+const TOKEN_FALLBACK_MS: Record<MotionToken, number> = {
+  instant: 80,
+  fast: 140,
+  base: 180,
+  slow: 240,
+};
+
+/**
+ * Millisecond value of a `--motion-*` token, for Unovis `duration` configs.
+ *
+ * The default is `slow` (240 ms): a chart entrance animates the whole plot area — the largest
+ * travel of any Forest animation — which is exactly the "larger travel" bucket --motion-slow
+ * names, and the slowest duration the system allows.
+ *
+ * `prefers-reduced-motion: reduce` resolves to 0, unconditionally.
+ */
+export function motionDuration(token: MotionToken = 'slow'): number {
+  if (typeof window === 'undefined' || typeof document === 'undefined') {
+    return TOKEN_FALLBACK_MS[token];
+  }
+  if (window.matchMedia?.('(prefers-reduced-motion: reduce)').matches) return 0;
+  const raw = getComputedStyle(document.documentElement)
+    .getPropertyValue(`--motion-${token}`)
+    .trim();
+  const ms = raw.endsWith('ms')
+    ? Number.parseFloat(raw)
+    : raw.endsWith('s')
+      ? Number.parseFloat(raw) * 1000
+      : Number.parseFloat(raw);
+  return Number.isFinite(ms) ? ms : TOKEN_FALLBACK_MS[token];
+}

package/packages/charts/src/presets.ts

@@ -0,0 +1,143 @@
+// Shared per-site Unovis config. Each preset carries only what direct call sites repeat verbatim —
+// per-chart concerns (tick values, formatters, counts, domains) stay at the call site. Spread with
+// v-bind and override next to it: `<VisAxis v-bind="axisX" :tick-values="…" />`.
+import { Position } from '@unovis/ts';
+import type {
+  AxisConfigInterface,
+  BulletLegendConfigInterface,
+  TooltipConfigInterface,
+} from '@unovis/ts';
+
+/** X axis: no grid lines. No duration here — animation timing is container-owned: the frame
+ *  resolves a --motion-* token onto the container and Unovis propagates it to axes; pages that
+ *  want a static chart pass 0 at the container. */
+export const axisX: Partial<AxisConfigInterface<unknown>> = Object.freeze({
+  type: 'x',
+  gridLine: false,
+});
+
+/** Y axis: grid lines stay on (they carry the value scale). Duration container-owned, as above. */
+export const axisY: Partial<AxisConfigInterface<unknown>> = Object.freeze({
+  type: 'y',
+});
+
+/** 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. */
+export const legendDefaults: Partial<BulletLegendConfigInterface> = Object.freeze({});
+
+/** Tooltip: above-right of the anchor, held clear of the pointer.
+ *
+ *  followCursor is off so a tooltip pins to the hovered mark and holds still while the pointer
+ *  moves inside it — readable, and reachable when `allowHover` is on. Two things bound that.
+ *  Crosshair force-sets followCursor back to true on every show, so XY charts with a crosshair
+ *  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.
+ *
+ *  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
+ *  real gap on both axes. They apply only because placement is Left/Right and Top/Bottom — under
+ *  Position.Auto or Center the library ignores them.
+ *
+ *  Container styling is not set here; it lives on the --vis-tooltip-* custom properties the
+ *  adapter themes. The `container` (which bounds the tooltip) is set by the frames, not here —
+ *  it needs `document`, which a module-scope constant must not touch. */
+export const tooltipDefaults: Partial<TooltipConfigInterface> = Object.freeze({
+  followCursor: false,
+  horizontalPlacement: Position.Right,
+  verticalPlacement: Position.Top,
+  horizontalShift: 12,
+  verticalShift: 12,
+});
+
+/** The element the tooltip is positioned and clamped inside. Unovis defaults this to the chart
+ *  container, and then clamps the panel to it — on a 280px-tall chart a low hover has nowhere to
+ *  go, so the clamp drags the tooltip back down over the pointer, which is the exact collision the
+ *  shifts above are meant to prevent. Bounding it by the viewport instead gives it the room to stay
+ *  clear; the cost is that the panel may overhang the chart's card, which is what a tooltip should
+ *  do. Returns undefined outside the browser so the frames stay render-safe without a DOM. */
+export function tooltipContainer(): HTMLElement | undefined {
+  return typeof document === 'undefined' ? undefined : document.body;
+}
+
+/** The whole house tooltip config, container included — what a call site mounting its own
+ *  `<VisTooltip>` should bind. Bars and scatters do exactly that (they carry `triggers` keyed by
+ *  mark selector rather than riding a crosshair), and binding `tooltipDefaults` alone leaves them
+ *  clamped inside the chart box, which is the collision described above. Call it in the template:
+ *  `<VisTooltip v-bind="houseTooltip()" :triggers="…" />`. */
+export function houseTooltip(): Partial<TooltipConfigInterface> {
+  return { ...tooltipDefaults, container: tooltipContainer() };
+}
+
+/** 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.
+ *
+ *  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
+ *  bound alongside then fails to match the caller's row type. These keys are plain numbers, so a
+ *  structural type keeps the component's inference free. */
+export const treemapDefaults: {
+  tileBorderRadius: number;
+  tilePadding: number;
+  tilePaddingTop: number;
+  showTileClickAffordance: boolean;
+  labelOffsetX: number;
+  labelOffsetY: number;
+  tileLabelSmallFontSize: number;
+  tileLabelMediumFontSize: number;
+  tileLabelLargeFontSize: number;
+} = Object.freeze({
+  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.
+  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.
+  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
+  // 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,
+  tileLabelMediumFontSize: 14,
+  tileLabelLargeFontSize: 16,
+});
+
+/** Nested donut ring shape. Unovis ships square corners and no ring gap, which reads as one solid
+ *  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.
+ *
+ *  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
+ *  accessor bound alongside then fails to match the caller's row type. */
+export const nestedDonutDefaults: {
+  cornerRadius: number;
+  layerPadding: number;
+  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.
+  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
+  // that is not that colour — the same call the adapter makes for the flat donut's track.
+  showBackground: false,
+});

package/packages/charts/src/resolveVar.ts

@@ -0,0 +1,21 @@
+// Resolve a `var(--x)` string to the value it currently computes to, without caching.
+//
+// Why this exists: @unovis/ts resolves CSS variables through its own getCSSVariableValue, which
+// memoises each variable per element in a module-level WeakMap and never invalidates it. Anything
+// Unovis decides in JS from a resolved value — the treemap's label ink is the one in this repo —
+// therefore keeps the palette it saw on first paint, and a colour-mode flip cannot change it. A
+// remount does not help: the container is new, the cache is not. Only a page reload clears it.
+//
+// Fills passed as `var()` strings are unaffected, because CSS resolves those continuously. This is
+// only needed where a value has to be correct AT THE MOMENT UNOVIS READS IT — hand it a plain
+// colour and its cache is never consulted.
+//
+// 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 {
+  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;
+}

package/packages/charts/src/snapTooltip.ts

@@ -0,0 +1,154 @@
+// Anchors a frame's tooltip to the datum rather than to the pointer.
+//
+// Unovis offers two anchors and neither is the one we want: the raw pointer (which free-floats,
+// since the panel drifts with every pixel of mouse movement even though the reading it shows only
+// changes datum to datum), or the hovered element's bounding box (which is the mark only when the
+// mark fills its box — true of a bar, false of a donut arc, whose box is most of the ring).
+//
+// So we let Unovis show, hide and fill the panel, and take over only where it lands: a
+// MutationObserver catches each placement and rewrites `left`/`top` against an anchor we compute.
+// Writing from the observer callback lands in the same microtask, before paint, so the corrected
+// position is the only one that ever renders — no flicker, no second frame.
+//
+// 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.
+import { onBeforeUnmount, onMounted, type Ref } from 'vue';
+import { Crosshair } from '@unovis/ts';
+
+/** Gap between anchor and panel. Matches the tooltip preset's shifts, so the snapped panel sits
+ *  the same distance off its anchor as a cursor-following one sits off the pointer. */
+const GAP = 12;
+/** Keep the panel this far inside the viewport when an anchor sits near an edge. */
+const EDGE = 8;
+
+let seq = 0;
+/** Per-instance id, written onto the tooltip as a data attribute so a frame can find its own panel.
+ *  Necessary because the tooltips are children of `body` (see `tooltipContainer`), so a frame
+ *  cannot simply look inside itself for one. */
+export function nextTipId(): string {
+  seq += 1;
+  return `forest-tip-${seq}`;
+}
+
+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 } {
+  const path = el as SVGPathElement;
+  if (typeof path.getTotalLength === 'function') {
+    const total = path.getTotalLength();
+    const ctm = el.getScreenCTM();
+    if (total > 0 && ctm) {
+      const SAMPLES = 24;
+      let sx = 0;
+      let sy = 0;
+      for (let i = 0; i < SAMPLES; i += 1) {
+        const p = path.getPointAtLength((total * i) / SAMPLES);
+        sx += p.x * ctm.a + p.y * ctm.c + ctm.e;
+        sy += p.x * ctm.b + p.y * ctm.d + ctm.f;
+      }
+      return { x: sx / SAMPLES, y: sy / SAMPLES };
+    }
+  }
+  const r = el.getBoundingClientRect();
+  return { x: r.x + r.width / 2, y: r.y + r.height / 2 };
+}
+
+export type SnapMode = 'crosshair' | 'mark';
+
+/** 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(
+  root: Ref<HTMLElement | undefined>,
+  tipId: string,
+  mode: SnapMode,
+  enabled: () => boolean,
+): void {
+  // The shape under the pointer, for `mark` mode. Read from the event rather than from Unovis,
+  // which keeps its hovered element private.
+  let hovered: SVGGraphicsElement | undefined;
+  // 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;
+    hovered = t instanceof SVGGraphicsElement && t.ownerSVGElement ? t : undefined;
+  }
+
+  function anchorFor(host: HTMLElement): { x: number; y: number } | undefined {
+    if (mode === 'crosshair') {
+      const line = host.querySelector<SVGGraphicsElement>(`.${Crosshair.selectors.line}`);
+      if (!line) return undefined;
+      const r = line.getBoundingClientRect();
+      // The line spans the plot, so its box gives both the snapped x and the plot's top edge.
+      return { x: r.x + r.width / 2, y: r.y };
+    }
+    if (!hovered || !host.contains(hovered)) return undefined;
+    return shapeCentre(hovered);
+  }
+
+  function reposition(tip: HTMLElement): void {
+    const host = root.value;
+    if (!host || !enabled()) return;
+    // Nothing to place while hidden, and reading layout then would force a pointless reflow.
+    if (getComputedStyle(tip).opacity === '0') return;
+    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;
+
+    writing = true;
+    tip.style.left = `${clamp(left, EDGE, window.innerWidth - w - EDGE)}px`;
+    tip.style.top = `${clamp(top, EDGE, window.innerHeight - h - EDGE)}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;
+  }
+
+  function attach(): void {
+    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;
+    }
+    observer = new MutationObserver(() => {
+      if (!writing) reposition(tip);
+    });
+    observer.observe(tip, { attributes: true, attributeFilter: ['style', 'class'] });
+  }
+
+  onMounted(() => {
+    root.value?.addEventListener('pointermove', onPointerMove, { capture: true });
+    attach();
+  });
+
+  onBeforeUnmount(() => {
+    cancelAnimationFrame(frame);
+    observer?.disconnect();
+    root.value?.removeEventListener('pointermove', onPointerMove, { capture: true });
+  });
+}

package/packages/charts/src/tooltipStandIn.ts

@@ -0,0 +1,58 @@
+// Lets the five hover-capable chart components render in an app that has no Nuxt UI.
+//
+// FDistributionBar, FDottedMap, FStatusTrack, FCalendarGrid and FLondonMap each wrap their marks in
+// one `<UTooltip>`. That tag is the ONLY thing in this package that reaches Nuxt UI, and it reaches
+// it by NAME, not by import — so no import grep sees it, and neither does a bundle sweep.
+//
+// How the name resolves decides everything, and it resolves two different ways:
+//
+//   · In a build that runs unplugin-vue-components (apps/docs does, through `@nuxt/ui/vite`), the
+//     plugin rewrites the compiled `_resolveComponent("UTooltip")` call into a direct import of
+//     @nuxt/ui's Tooltip.vue. Resolution happens at BUILD time and never consults the app's global
+//     registry, so nothing registered here can reach it — installing this plugin there is inert,
+//     and cannot take a tooltip away from the product.
+//
+//   · In a plain Vue app with no such plugin (a Slidev deck, say), the call survives to runtime and
+//     asks the app's global components for `UTooltip`. Unanswered, Vue warns and falls back to a
+//     native `<utooltip>` element — an unknown inline box wrapped around a flex row or an SVG,
+//     which is a layout defect, not a missing tooltip.
+//
+// Answering that lookup with a stand-in is what this file does. The stand-in renders the trigger
+// and nothing else: a projected slide has no pointer to hover and no presenter who could, so the
+// tooltip is dead weight there rather than a feature lost.
+//
+// This is a stand-in, not a port. It carries none of Nuxt UI's tooltip behaviour — no panel, no
+// portal, no positioning. An app that wants tooltips wants Nuxt UI.
+import { defineComponent, type Component, type Plugin } from 'vue';
+
+/** Renders its trigger, drops the tooltip. `inheritAttrs: false` keeps `text`, `reference` and
+ *  `open` off the DOM — they are Nuxt UI props here, and as attributes they would be markup. */
+export const TooltipStandIn: Component = defineComponent({
+  name: 'TooltipStandIn',
+  inheritAttrs: false,
+  setup(_props, { slots }) {
+    return () => {
+      const children = slots.default?.();
+      if (!children?.length) return null;
+      // One child is the shape every call site has, and returning the vnode itself rather than a
+      // one-item array keeps the trigger a single root: no fragment anchors between it and the
+      // flex or grid parent that lays it out.
+      return children.length === 1 ? children[0] : children;
+    };
+  },
+});
+
+/** Registers the stand-ins this package's components look up by name. Install it on a Vue app that
+ *  has no Nuxt UI:
+ *
+ *  ```ts
+ *  app.use(chartsWithoutNuxtUI);
+ *  ```
+ *
+ *  A name the app already answers is left alone, so installing this alongside a real Nuxt UI
+ *  registration cannot shadow it. */
+export const chartsWithoutNuxtUI: Plugin = {
+  install(app) {
+    if (!app.component('UTooltip')) app.component('UTooltip', TooltipStandIn);
+  },
+};

package/packages/charts/src/useCellScale.ts

@@ -0,0 +1,155 @@
+// The cell colour contract, shared by FStatusTrack and FCalendarGrid.
+//
+// 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
+// resolution lives here and the components stay layout.
+//
+// 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 type { BulletLegendItemInterface } from '@unovis/ts';
+import { sequentialVar } from './useChartPalette';
+import { DATAVIZ_SEQUENTIAL } from './engine';
+import { useThemeVersion } from './useThemeVersion';
+
+export type SequentialRamp = keyof typeof DATAVIZ_SEQUENTIAL;
+
+/** One legend entry. `swatch` is a var() string; intensity entries carry no name. */
+export interface CellLegendEntry {
+  key: string;
+  name?: string;
+  swatch: string;
+}
+
+export interface CellLegend {
+  mode: 'state' | 'intensity';
+  entries: CellLegendEntry[];
+  /** Intensity only — the Less/More end captions. */
+  bounds?: [string, string];
+}
+
+export interface CellScaleOptions<D> {
+  mode: 'state' | 'intensity';
+  /** State mode. Same shape as `categories` elsewhere, so useChartPalette output feeds it as-is. */
+  states?: MaybeRef<Record<string, BulletLegendItemInterface> | undefined>;
+  /** Intensity mode. */
+  ramp?: MaybeRef<SequentialRamp>;
+  /** Intensity domain. Defaults to [0, max over data] — state it explicitly to compare two charts. */
+  domain?: MaybeRef<[number, number] | undefined>;
+  /** Number of buckets the ramp is sampled into. */
+  steps?: MaybeRef<number>;
+  data?: MaybeRef<readonly D[]>;
+  value?: (d: D) => number | null | undefined;
+  state?: (d: D) => string | null | undefined;
+}
+
+export interface CellScale<D> {
+  colorOf: (d: D | null | undefined) => string;
+  isEmpty: (d: D | null | undefined) => boolean;
+  legend: CellLegend;
+  /** The resolved intensity domain — read it back when a caller wants to label the ends. */
+  domain: [number, number];
+}
+
+/** The fill for a bucket with no reading. A token, so it flips with the mode like everything else. */
+export const CELL_EMPTY_COLOR = 'var(--ui-bg-accented)';
+
+const colorOf = (item: BulletLegendItemInterface | undefined, i: number): string => {
+  if (typeof item?.color === 'string') return item.color;
+  if (Array.isArray(item?.color) && typeof item.color[0] === 'string') return item.color[0];
+  return `var(--vis-color${i})`;
+};
+
+// Unlike the categorical sets, the sequential ramps are declared once and are not redefined for
+// dark mode: a ramp runs pale → deep, which reads as low → high on a white page and backwards on a
+// dark one, where the deep end sinks into the background. The house rule in the token file is to
+// invert the stop order in dark mode, and doing it here means every cell chart obeys it for free.
+const prefersInvertedRamp = (): boolean => {
+  if (typeof document === 'undefined') return false;
+  const root = document.documentElement;
+  return root.classList.contains('dark') || root.dataset.theme === 'dark';
+};
+
+export function useCellScale<D>(options: CellScaleOptions<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();
+
+  // Sampled ramp stops, low → high. sequentialVar indexes the ramp's own stops, so a request for
+  // more steps than the ramp has simply repeats stops rather than inventing colours.
+  const swatches = computed<string[]>(() => {
+    void themeVersion.value;
+    const ramp = unref(options.ramp) ?? ('forest' as SequentialRamp);
+    const len = DATAVIZ_SEQUENTIAL[ramp].length;
+    const n = stepsOf();
+    const stops = Array.from({ length: n }, (_, i) =>
+      sequentialVar(ramp, Math.round((i * (len - 1)) / (n - 1))),
+    );
+    return prefersInvertedRamp() ? stops.reverse() : stops;
+  });
+
+  const domain = computed<[number, number]>(() => {
+    const given = unref(options.domain);
+    if (given) return given;
+    const rows = unref(options.data) ?? [];
+    let max = 0;
+    for (const d of rows) {
+      const v = options.value?.(d);
+      if (typeof v === 'number' && Number.isFinite(v) && v > max) max = v;
+    }
+    return [0, max];
+  });
+
+  const isEmpty = (d: D | null | undefined): boolean => {
+    if (d === null || d === undefined) return true;
+    if (options.mode === 'intensity') {
+      const v = options.value?.(d);
+      return typeof v !== 'number' || !Number.isFinite(v);
+    }
+    const s = options.state?.(d);
+    return s === null || s === undefined || s === '';
+  };
+
+  const resolve = (d: D | null | undefined): string => {
+    if (isEmpty(d)) return CELL_EMPTY_COLOR;
+    if (options.mode === 'intensity') {
+      const [lo, hi] = domain.value;
+      const v = options.value!(d as D) as number;
+      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];
+      const t = Math.min(1, Math.max(0, (v - lo) / (hi - lo)));
+      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;
+    const keys = Object.keys(states);
+    const i = keys.indexOf(key);
+    // An unmapped state is missing information, not a colour to invent.
+    return i === -1 ? CELL_EMPTY_COLOR : colorOf(states[key], i);
+  };
+
+  const legend = computed<CellLegend>(() => {
+    if (options.mode === 'intensity') {
+      return {
+        mode: 'intensity',
+        entries: swatches.value.map((swatch, i) => ({ key: String(i), swatch })),
+        bounds: ['Less', 'More'],
+      };
+    }
+    const states = unref(options.states) ?? {};
+    return {
+      mode: 'state',
+      entries: Object.keys(states).map((key, i) => ({
+        key,
+        // BulletLegendItemInterface types `name` as string | number, so a numeric series name
+        // reaches the legend as a number.
+        name: String(states[key]?.name ?? key),
+        swatch: colorOf(states[key], i),
+      })),
+    };
+  });
+
+  return { colorOf: resolve, isEmpty, legend, domain, swatches };
+}