@humanforest/slidev-theme 0.1.0

package/components/SankeyChart.vue

@@ -0,0 +1,223 @@
+<script setup>
+/*
+  A Sankey sized for a room — where a quantity goes as it moves through stages, with the WIDTH of
+  every ribbon being the quantity itself.
+
+  A Sankey is the right mark when the story is CONSERVATION: a total arrives, it splits, and every
+  part of it lands somewhere. Where the columns are only categories measured twice, the ribbons
+  claim a continuity that is not there and the chart wants bars.
+
+  Real @unovis/vue mark, ChartFrame.vue for ceremony, chartData.ts for the palette and the states.
+
+  ★ THE FIVE-COLOUR CEILING COUNTS NODES, and it bites harder here than on a line chart by design.
+  Colour in a Sankey is IDENTITY — it is how an audience traces one flow across three columns — so
+  a sixth block cannot borrow a colour that has already been spent without telling the room that two
+  different things are the same thing. Past five, chartData's `over-capacity` message draws instead.
+  Aggregate the tail into a "Rest" node at the call site, the way a donut's slices do.
+
+  Ribbons take the colour of the block they LEAVE, which is what makes a split legible: three
+  ribbons out of one node read as one green dividing, rather than as three unrelated bands.
+
+  ★ NODE COLOUR MUST BE A FUNCTION, NEVER AN ARRAY, and the failure is silent all the way down.
+  VisLine and VisDonut take a colours ARRAY because they hand the library's `getColor` an index; the
+  Sankey calls `getColor(node, config.nodeColor)` with no index at all (components/sankey/modules/
+  node.js), so the `Array.isArray(accessor) && isFinite(index)` branch never fires and `getString`
+  returns the array itself — a non-function accessor is passed straight back (utils/data.js,
+  `getValue`). d3 stringifies that into a comma-joined list, which is not a valid paint, so
+  `setProperty` drops the declaration and every block falls back to the class rule's
+  `--vis-sankey-node-color`. That resolves to `--vis-color-main`, declared on `:root` and therefore
+  computed there — out of reach of ChartFrame's `--vis-color0` override, which is declared on
+  `.deck-chart`. The whole diagram comes out in Unovis' own default blue, with no error anywhere.
+
+  ★ `heightNormalizationCoeff` IS A DEAD KEY in @unovis/ts 1.6.7. It is declared in the config
+  interface and defaulted to 1/16, and nothing in the shipped package ever reads it — the only
+  matches in the whole build are the declaration, the default and the sourcemap. If a Sankey ever
+  comes out shorter than the height it was given, this is not the lever.
+
+  Two of the library's own label defaults are wrong on this canvas. `--vis-sankey-node-label-color`
+  is a literal grey rather than a role (components/sankey/style.js), so it vanishes on a
+  `class: deck-dark` slide — `labelColor` is passed a deck token instead and flips with the slide.
+  `--vis-sankey-node-label-font-weight` is 600, which is off the deck's two-weight system, and is
+  left alone deliberately: forest-fonts.css declares exactly two GT Haptik faces, 400 and 700, and
+  CSS weight matching resolves a request above 500 UP to the next real file rather than synthesising
+  one, so the rendered label is already on-system.
+*/
+import { computed } from 'vue';
+import { VisSingleContainer, VisSankey, VisTooltip, VisSankeySelectors } from '@unovis/vue';
+import { deckTooltip, tipFrame } from './chartTip';
+import ChartFrame from './ChartFrame.vue';
+import { SERIES_CEILING, formatValue, isPlottable, seriesVar, stateMessage } from './chartData';
+
+/*
+  --type-deck-body-sm-size is 2.25rem against the deck's 16px root: 36px, the same tier ChartFrame
+  sets every axis tick label at. Restated here as a NUMBER because `labelFontSize` is a layout input
+  rather than a style — Unovis measures it to reserve the bleed a label needs (`labelFontSize * 2.5`
+  plus block padding, for an assumed 2.5 lines, components/sankey/index.js) before any of this has
+  rendered. Left unset it falls back to `--vis-sankey-node-label-font-size`, which is 12px: a
+  caption on a dashboard and a speck in a room. It is not a prop, because a deck cannot express an
+  off-system size.
+*/
+const LABEL_FONT_SIZE = 36;
+
+const props = defineProps({
+  /**
+   * Stages: `[{ id, label }]`, in the order they take their colours. `id` is what links name it by;
+   * `label` is what the room reads.
+   *
+   * ★ Give every node a STRING id. Unovis' graph model matches a link's `source`/`target` against
+   * `node.id` when it is a string, but treats a NUMBER as an INDEX into this array
+   * (data-models/graph.js, `findNode`) — so `id: 0` and `source: 0` agree by accident and stop
+   * agreeing the moment the array is reordered. A node carrying no id at all falls back to its own
+   * index, here and in the library alike.
+   */
+  nodes: { type: Array, required: true },
+  /** Flows: `[{ source, target, value }]`. `source` and `target` are node ids; `value` is the ribbon's width. A flow with no width, one whose endpoint names no node, and one pointing a node at itself are all dropped before the mark sees them. */
+  links: { type: Array, required: true },
+  /** Plot height in px. 0 FILLS, and is the default: the chart takes whatever box it is given,
+   *  which is what a chart under a heading wants. Unovis resolves `config.height || containerHeight`,
+   *  so a falsy height makes the container measure itself. Pass a number where the box has no
+   *  definite height of its own — a tiled grid cell, a figure beside copy. */
+  height: { type: Number, default: 0 },
+  /** Block width in px. The library's 25 is a sliver standing next to 36px type. */
+  nodeWidth: { type: Number, default: 40 },
+  /** Vertical gap between the blocks in one column, in px. The library's 2 does not exist at this distance. */
+  nodePadding: { type: Number, default: 24 },
+  /** Draw the node legend. The diagram already labels every block on the canvas, so this repeats those names underneath it. */
+  legend: { type: Boolean, default: true },
+  /** Where the legend sits: `top-left`, `top-center`, `top-right`, `bottom-left`, `bottom-center`
+   *  or `bottom-right`. The EDGE is reading order — above is read before the marks, below is a
+   *  caption read after them; the ALIGNMENT is for the column the chart sits in, centred under a
+   *  full-width plot and pulled to an edge where a centred key would float in a gutter. */
+  legendPosition: {
+    type: String,
+    default: 'bottom-center',
+    validator: (p) => ['top-left', 'top-center', 'top-right', 'bottom-left', 'bottom-center', 'bottom-right'].includes(p),
+  },
+  /** The sentence drawn when there is nothing to plot. */
+  empty: { type: String, default: 'No data' },
+});
+
+/*
+  ★ EVERY NODE IS GIVEN AN ID HERE, because the library gives it one anyway and the two have to be
+  the same one. `nodeId` (data-models/graph.js) takes `n.id` when it is a string or a finite number
+  and falls back to the node's INDEX otherwise, PER NODE — so a set of id-less nodes still draws as
+  N distinct blocks, while any map this component keys by `String(n.id)` collapses them into one
+  "undefined" entry and paints every block the last node's colour. That is exactly the lie the
+  header says a repeated colour tells a room, arriving with no message at all. Deriving the same
+  fallback here keeps the colour map, the legend keys and the blocks on the canvas naming the same
+  things.
+
+  It is written onto a COPY, which is what makes it true for Unovis too: the id this component
+  resolved is the id the library receives. Endpoints are matched against those ids as strings, so a
+  link naming a node OBJECT rather than an id is not supported — the filter below drops it.
+*/
+const idOf = (n, i) => (typeof n?.id === 'string' || Number.isFinite(n?.id) ? String(n.id) : String(i));
+const labelOf = (n) => String(n.label ?? n.id);
+
+const blocks = computed(() => (props.nodes ?? []).map((n, i) => ({ ...n, id: idOf(n, i) })));
+
+/*
+  A ribbon with no width is not a flow; a link whose endpoint names no node is not one either; and a
+  link from a node to itself is not one at all. Unovis drops the last two on its own
+  (data-models/graph.js filters `source === target` with a console.warn, then any endpoint
+  `findNode` could not resolve) — but silently as far as the room is concerned, so a diagram built
+  entirely from them renders as a bare column of rectangles with nothing between them and no hint
+  that the flows were meant to be there.
+
+  Filtered HERE, and the same filtered table is what the mark is handed, so the emptiness decision
+  and the drawing agree. Unovis does not check the value: a NEGATIVE one survives untouched and
+  d3-sankey sums it into the node's own height, laying out a ribbon of negative width.
+
+  A partial drop is still silent — four good flows and one bad one draws four ribbons and says
+  nothing. Reporting that needs a state chartData.ts does not carry.
+*/
+const flows = computed(() => {
+  const ids = new Set(blocks.value.map((n) => n.id));
+  return (props.links ?? []).filter(
+    (l) =>
+      isPlottable(l.value) &&
+      l.value > 0 &&
+      ids.has(String(l.source)) &&
+      ids.has(String(l.target)) &&
+      String(l.source) !== String(l.target),
+  );
+});
+
+/*
+  A graph is not a table, so `chartState` — which reads rows against a series per column — cannot
+  make this decision and the decision is made here. The WORDING still comes from `stateMessage`:
+  one pinned string shared across every chart in this folder, rather than a seventh that drifts.
+
+  ⚠ This belongs in chartData.ts as `sankeyState(nodes, links)`, beside `shareState` and
+  `scatterState`, where the package's node-only vitest run can reach the rules. It is the only
+  chart-state logic in this folder no test can see. Left here until that export exists.
+*/
+const state = computed(() => {
+  if (blocks.value.length === 0) return { kind: 'empty', reason: 'no-rows' };
+  if (blocks.value.length > SERIES_CEILING) return { kind: 'over-capacity', count: blocks.value.length };
+  if (flows.value.length === 0) return { kind: 'empty', reason: 'no-values' };
+
+  return {
+    kind: 'ready',
+    // Past the ceiling the colours are never asked for at all: the branch above has already stopped
+    // the chart, and `seriesVar` throws rather than wrapping the palette back to its first colour.
+    series: blocks.value.map((n, i) => ({ key: n.id, name: labelOf(n), color: seriesVar(i) })),
+  };
+});
+
+const message = computed(() => (state.value.kind === 'ready' ? null : stateMessage(state.value, props.empty)));
+const seriesList = computed(() => (state.value.kind === 'ready' ? state.value.series : []));
+
+// Unovis wants the two tables as one object; the split into two props is only at the call site.
+const data = computed(() => ({ nodes: blocks.value, links: flows.value }));
+const colourOf = computed(() => new Map(seriesList.value.map((s) => [s.key, s.color])));
+
+const nodeColor = (n) => colourOf.value.get(n.id);
+// `l.source` is the resolved node OBJECT by the time an accessor runs — the graph model replaces
+// the id with it before d3-sankey sees the link — and every node in it carries the id assigned
+// above, so there is no raw-endpoint case left to fall back to.
+const linkColor = (l) => colourOf.value.get(l.source?.id);
+
+/*
+  THE RIBBON CARRIES THE TOOLTIP, and only the ribbon. A flow is the reading a Sankey exists for —
+  this much, from here to there — and it is the one a block cannot show, since a block's total is
+  just the ribbons meeting at it.
+
+  The block carries a second one: a block's total is only ever the ribbons meeting at it, so the
+  reading it adds is the sum, named.
+*/
+const nodeTip = (n) => tipFrame(
+  labelOf(n ?? {}),
+  [{ swatch: nodeColor(n), label: 'Total', value: formatValue(n?.value ?? 0) }],
+);
+const linkTip = (l) => tipFrame(
+  `${labelOf(l?.source ?? {})} \u2192 ${labelOf(l?.target ?? {})}`,
+  [{ swatch: linkColor(l), label: 'Flow', value: formatValue(l?.value ?? 0) }],
+);
+</script>
+
+<template>
+  <ChartFrame
+    :series="seriesList"
+    :height="height"
+    :legend="legend"
+    :legend-position="legendPosition"
+    :message="message"
+  >
+    <VisSingleContainer :data="data" :height="height" :duration="0">
+      <!-- No margin: the Sankey computes its own bleed from the labels it is about to draw, and a
+           margin on top of that is space subtracted from the ribbons twice. -->
+      <VisSankey
+        :node-width="nodeWidth"
+        :node-padding="nodePadding"
+        :node-color="nodeColor"
+        :link-color="linkColor"
+        :label="labelOf"
+        :label-font-size="LABEL_FONT_SIZE"
+        label-color="var(--deck-fg)"
+        label-fit="wrap"
+      />
+      <VisTooltip v-bind="deckTooltip()" :triggers="{ [VisSankeySelectors.link]: linkTip, [VisSankeySelectors.node]: nodeTip }" />
+    </VisSingleContainer>
+  </ChartFrame>
+</template>

package/components/ScatterChart.vue

@@ -0,0 +1,142 @@
+<script setup>
+/*
+  A scatter sized for a room — two measurements against each other, one dot per observation, with
+  an optional third read as dot size.
+
+  What a scatter is FOR is the shape of a cloud: a correlation, a cluster, an outlier. It is the one
+  chart on this deck whose message is not a number, which is why it carries no value labels by
+  default — an audience reads the pattern, and the presenter says what it means.
+
+  Deck-scale dots are large (18–64px, against the library's 4–10), because a 6px dot projected
+  across a room is dust. That makes overlap the real risk, so points carry a ground-coloured stroke
+  and a little transparency: two overlapping dots stay countable instead of merging into a blob.
+
+  Real @unovis/vue mark, ChartFrame.vue for ceremony, chartData.ts for shaping.
+*/
+import { computed } from 'vue';
+import { VisXYContainer, VisAxis, VisScatter, VisTooltip, VisScatterSelectors } from '@unovis/vue';
+import { deckTooltip, tipFrame } from './chartTip';
+import ChartFrame from './ChartFrame.vue';
+import { formatValue, scatterGroups, scatterState, stateMessage } from './chartData';
+
+const props = defineProps({
+  /** Rows: `[{ x, y, size?, label?, group? }]`. `x` and `y` are required numbers; a row missing either is not a point. */
+  data: { type: Array, required: true },
+  /** Plot height in px. 0 FILLS, and is the default: the chart takes whatever box it is given,
+   *  which is what a chart under a heading wants. Unovis resolves `config.height || containerHeight`,
+   *  so a falsy height makes the container measure itself. Pass a number where the box has no
+   *  definite height of its own — a tiled grid cell, a figure beside copy. */
+  height: { type: Number, default: 0 },
+  /** Draw the group legend. Only meaningful when the rows carry a `group`. */
+  legend: { type: Boolean, default: true },
+  /** Where the legend sits: `top-left`, `top-center`, `top-right`, `bottom-left`, `bottom-center`
+   *  or `bottom-right`. The EDGE is reading order — above is read before the marks, below is a
+   *  caption read after them; the ALIGNMENT is for the column the chart sits in, centred under a
+   *  full-width plot and pulled to an edge where a centred key would float in a gutter. */
+  legendPosition: {
+    type: String,
+    default: 'bottom-center',
+    validator: (p) => ['top-left', 'top-center', 'top-right', 'bottom-left', 'bottom-center', 'bottom-right'].includes(p),
+  },
+  /** Title under the x axis. A scatter almost always needs both, because neither axis is self-evident. */
+  xLabel: { type: String, default: null },
+  /** Title beside the y axis. */
+  yLabel: { type: String, default: null },
+  /** Formats both axes' tick labels. Defaults to British grouping, compact past four digits. */
+  format: { type: Function, default: formatValue },
+  /** Smallest and largest dot diameter in px, mapped across the rows' `size` values. */
+  sizeRange: { type: Array, default: () => [18, 64] },
+  /** Print each row's `label` beside its dot. Off by default — a cloud of labels is not a chart. */
+  labels: { type: Boolean, default: false },
+  /** The sentence drawn when there is nothing to plot. */
+  empty: { type: String, default: 'No data' },
+});
+
+const state = computed(() => scatterState(props.data));
+const message = computed(() => (state.value.kind === 'ready' ? null : stateMessage(state.value, props.empty)));
+// A single unnamed cloud has nothing to put in a legend, so the frame draws none.
+const seriesList = computed(() => {
+  if (state.value.kind !== 'ready') return [];
+  return state.value.series.length === 1 && state.value.series[0].key === 'points' ? [] : state.value.series;
+});
+
+const groups = computed(() => scatterGroups(props.data ?? []));
+const x = (d) => d.x;
+const y = (d) => d.y;
+const size = (d) => (typeof d.size === 'number' && Number.isFinite(d.size) ? d.size : 1);
+const color = (d) => {
+  if (state.value.kind !== 'ready') return undefined;
+  const name = d.group == null ? '' : String(d.group);
+  const i = groups.value.indexOf(name);
+  return state.value.series[Math.max(i, 0)]?.color;
+};
+const label = (d) => (props.labels && d.label != null ? String(d.label) : '');
+
+/*
+  A scatter's point IS the datum, so the tooltip hangs off the mark rather than a column — there is
+  no shared x to snap to, which is the difference between this and the line family.
+
+  Rows are named by the AXIS LABELS where the slide gave them: a bare `x` and `y` name the geometry
+  rather than the measurement.
+*/
+const tip = (d) => tipFrame(String(d?.label ?? d?.group ?? ''), [
+  { swatch: color(d), label: props.xLabel ?? 'x', value: props.format(d?.x ?? 0) },
+  { label: props.yLabel ?? 'y', value: props.format(d?.y ?? 0) },
+]);
+</script>
+
+<template>
+  <ChartFrame
+    :series="seriesList"
+    :height="height"
+    :legend="legend"
+    :legend-position="legendPosition"
+    :message="message"
+  >
+    <!-- `padding` insets the MARKS from the plot edges while the axes stay put — the one thing a
+         scatter needs that no other chart here does. Deck dots are up to 64px across, so a point at
+         the extreme of either scale would otherwise be sliced in half by the plot's own boundary.
+         Half the largest dot, rounded up. -->
+    <VisXYContainer
+      :data="data"
+      :height="height"
+      :duration="0"
+      :margin="{ top: 32, right: 40, bottom: 0, left: 0 }"
+      :padding="{ top: 40, right: 40, bottom: 40, left: 40 }"
+    >
+      <VisScatter
+        :x="x"
+        :y="y"
+        :size="size"
+        :color="color"
+        :size-range="sizeRange"
+        :label="label"
+        label-hide-overlapping
+      />
+      <!-- Both axes carry grid lines here, unlike the category charts: neither axis of a scatter is
+           a list of names, so a reader needs to be able to trace a dot back to both scales. -->
+      <VisAxis
+        type="x"
+        grid-line
+        :tick-line="false"
+        :num-ticks="4"
+        :tick-format="format"
+        :tick-padding="16"
+        :label="xLabel"
+        :label-margin="24"
+        tick-text-hide-overlapping
+      />
+      <VisAxis
+        type="y"
+        :num-ticks="4"
+        :tick-format="format"
+        :tick-line="false"
+        :domain-line="false"
+        :tick-padding="16"
+        :label="yLabel"
+        :label-margin="24"
+      />
+      <VisTooltip v-bind="deckTooltip()" :triggers="{ [VisScatterSelectors.point]: tip }" />
+    </VisXYContainer>
+  </ChartFrame>
+</template>

package/components/StackedBarChart.vue

@@ -0,0 +1,143 @@
+<script setup>
+/*
+  A stacked bar chart sized for a room: each column is one category, split into the parts that make
+  it up. Real @unovis/vue marks, ChartFrame.vue for ceremony, chartData.ts for shaping.
+
+  Stacking is a CLAIM: the segments sum to the column, and the column is the thing being compared.
+  When the series are independent quantities that merely share an axis, the honest mark is
+  GroupedBarChart.vue — a stack invites the audience to read a total that does not exist.
+
+  Bars start at zero. Not because a truncated axis is always a lie — it isn't, and the research does
+  not support the absolute rule — but because a slide is read in seconds from the back of a room,
+  with no axis to inspect, so length has to be the whole message. Unovis stacks from zero and this
+  component never moves the baseline.
+
+  Vertical by default because a stack reads as a column of parts. A category set whose labels are
+  long words wants Bars.vue instead, which lays them out horizontally and labels each bar directly.
+*/
+import { computed } from 'vue';
+import { VisXYContainer, VisAxis, VisStackedBar, VisCrosshair, VisTooltip } from '@unovis/vue';
+import { deckTooltip, seriesTip } from './chartTip';
+import { motionDuration } from './motionDuration';
+import ChartFrame from './ChartFrame.vue';
+import { chartState, formatValue, labelAt, stateMessage, tickIndices, CROSSHAIR_CIRCLE_R, CROSSHAIR_HIDE_WHEN_FAR } from './chartData';
+
+const props = defineProps({
+  /** Rows: `[{ label, <seriesKey>: number, … }]`. One row is one column; `label` names it. */
+  data: { type: Array, required: true },
+  /** Series to stack, bottom to top and in legend order: `[{ key, name }]`. Omit and every numeric field on the first row becomes a series. */
+  series: { type: Array, default: null },
+  /** Plot height in px. 0 FILLS, and is the default: the chart takes whatever box it is given,
+   *  which is what a chart under a heading wants. Unovis resolves `config.height || containerHeight`,
+   *  so a falsy height makes the container measure itself. Pass a number where the box has no
+   *  definite height of its own — a tiled grid cell, a figure beside copy. */
+  height: { type: Number, default: 0 },
+  /** Draw the series legend. A stack is unreadable without one unless the segments are labelled some other way. */
+  legend: { type: Boolean, default: true },
+  /** Where the legend sits: `top-left`, `top-center`, `top-right`, `bottom-left`, `bottom-center`
+   *  or `bottom-right`. The EDGE is reading order — above is read before the marks, below is a
+   *  caption read after them; the ALIGNMENT is for the column the chart sits in, centred under a
+   *  full-width plot and pulled to an edge where a centred key would float in a gutter. */
+  legendPosition: {
+    type: String,
+    default: 'bottom-center',
+    validator: (p) => ['top-left', 'top-center', 'top-right', 'bottom-left', 'bottom-center', 'bottom-right'].includes(p),
+  },
+  /** Title under the x axis. Omit when the labels already say what they are. */
+  xLabel: { type: String, default: null },
+  /** Title beside the y axis. Omit when the unit is in the slide's heading. */
+  yLabel: { type: String, default: null },
+  /** Formats the y tick labels. Defaults to British grouping, compact past four digits. */
+  format: { type: Function, default: formatValue },
+  /** Ceiling on x tick labels. Deck labels are 36px, so more than a handful collide. */
+  maxTicks: { type: Number, default: 8 },
+  /** Draw the two axes. Off is a SHAPE reading — the marks alone, no scale — for a chart that is
+   *  being shown rather than read: a specimen, a register test, a sparkline beside a figure.
+   *
+   *  ★ IT REMOVES THEM, IT DOES NOT HIDE THEM. Unovis reserves the axis band whether or not the
+   *  axis paints, so hiding one in CSS leaves the plot inset by a tick row and a label column that
+   *  are no longer there — measured at a 150px plot, the marks drew 22px of a 63px box. Not
+   *  rendering the component is what gives the room back.
+   *
+   *  ⚠ A chart carrying VALUES needs its scale. Turning this off says the reading is the shape. */
+  axes: { type: Boolean, default: true },
+  /** The sentence drawn when there is nothing to plot. */
+  empty: { type: String, default: 'No data' },
+});
+
+const state = computed(() => chartState(props.data, props.series));
+const message = computed(() => (state.value.kind === 'ready' ? null : stateMessage(state.value, props.empty)));
+const seriesList = computed(() => (state.value.kind === 'ready' ? state.value.series : []));
+
+const x = (_d, i) => i;
+const y = computed(() => seriesList.value.map((s) => (d) => d[s.key]));
+const colors = computed(() => seriesList.value.map((s) => s.color));
+
+// Half a column of outer gutter, so the first and last bars stop sitting flush against the plot
+// edges — the same rule packages/charts' FChartFrame applies to every index chart.
+const xDomain = computed(() => [-0.5, (props.data?.length ?? 0) - 0.5]);
+const xTicks = computed(() => tickIndices(props.data?.length ?? 0, props.maxTicks));
+const xFormat = (v) => labelAt(props.data ?? [], v);
+
+/*
+  The crosshair carries the tooltip: every series has a value at the hovered x, so the target is the
+  COLUMN rather than any one mark — which is also the only target anyone can hit from a lectern.
+  `forestTooltip` titles the row from its first property, and the deck's rows lead with `label`.
+*/
+/* Read at mount so `prefers-reduced-motion` is honoured; see motionDuration.ts. */
+const crosshairMs = motionDuration('instant');
+
+const tip = computed(() => seriesTip(seriesList.value, props.format));
+</script>
+
+<template>
+  <ChartFrame
+    :series="seriesList"
+    :height="height"
+    :legend="legend"
+    :legend-position="legendPosition"
+    :message="message"
+  >
+    <VisXYContainer
+      :data="data"
+      :height="height"
+      :duration="0"
+      :x-domain="xDomain"
+      :margin="{ top: 16, right: 24, bottom: 0, left: 0 }"
+    >
+      <!-- 8px corners, matching --deck-radius-item: Unovis clamps the radius against the segment
+           height, so a thin slice degrades to a square rather than deforming. -->
+      <VisStackedBar :x="x" :y="y" :color="colors" :rounded-corners="8" :bar-padding="0.25" />
+      <VisAxis
+        v-if="axes"
+        type="x"
+        :grid-line="false"
+        :tick-line="false"
+        :tick-values="xTicks"
+        :tick-format="xFormat"
+        :tick-padding="16"
+        :label="xLabel"
+        :label-margin="24"
+        tick-text-hide-overlapping
+      />
+      <VisAxis
+        v-if="axes"
+        type="y"
+        :tick-format="format"
+        :num-ticks="4"
+        :tick-line="false"
+        :domain-line="false"
+        :tick-padding="16"
+        :label="yLabel"
+        :label-margin="24"
+      />
+      <!-- ★★ `y-stacked`, NOT `y`, WHEREVER THE MARKS STACK. The crosshair plots a circle per
+           series, and given `y` it plots each at its RAW value — which on a stacked chart is a
+           position nothing is drawn at: the second series' circle lands inside the first band
+           rather than on the boundary between them. `yStacked` is Unovis' own accumulator, so the
+           circles sit where the bands actually meet. -->
+      <VisCrosshair :duration="crosshairMs" :hideWhenFarFromPointer="CROSSHAIR_HIDE_WHEN_FAR" :circleRadius="CROSSHAIR_CIRCLE_R" :x="x" :yStacked="y" :template="tip" :color="colors" />
+      <VisTooltip v-bind="deckTooltip()" />
+    </VisXYContainer>
+  </ChartFrame>
+</template>

package/components/StatCard.vue

@@ -0,0 +1,134 @@
+<script setup>
+/*
+  A stat inside a card: the deck's <Kpi> figure, framed by the deck's one container.
+
+  This is NOT a second definition of a KPI — Kpi.vue already owns the numeral treatment, the
+  label treatment and the delta rule (arrow = direction, colour = judgement), and this component
+  reuses all three wholesale rather than restating them. StatCard's own job is FRAMING
+  only: which background the stat sits on, how the figure aligns in the tile, and — on a named
+  background specifically — keeping Card's own promise that "text inside it stays legible without the
+  author picking a colour". Card already fulfils that promise for plain prose by re-pointing
+  h1–h6/p/.deck-caption to the pair's ink (see base.css's `.deck-card.bg-*` rules), but Kpi's
+  figure, label and delta are their own classes, not those elements, so that rule never reaches
+  them: measured live when this was the accent variant, `<Card variant="accent"><Kpi/></Card>`
+  rendered the figure in `--deck-accent` text on a `--deck-accent` fill — the exact same colour,
+  invisible. Re-pointing those classes to the card's ink when framed this way is the one place this
+  component touches colour, and it is Card's contract StatCard is completing, not a second
+  definition of Kpi's judgement-colour rule.
+
+  Every prop below except `background`, `dark` and `align` is Kpi's own name, passed straight through
+  unchanged — including its slots: `#metric` forwards for pre-formatted text, so
+  `<StatCard><template #metric>12k</template></StatCard>` — the usage this component's own doc used
+  to describe without actually wiring it up — works. Inventing a parallel name (`value` for
+  `metric`, say) is exactly the drift this component exists to avoid.
+*/
+import { BACKGROUND_NAMES, CARD_BACKGROUNDS } from './backgrounds.js';
+
+defineProps({
+  /** What the stat sits on — 'transparent' for no fill at all, 'surface' the quiet fill, or 'warm' | 'accent' | 'vivid' | 'neutral', a named background. Forwarded to Card's own `background`. */
+  background: {
+    type: String,
+    default: 'surface',
+    validator: (b) => CARD_BACKGROUNDS.includes(b),
+  },
+  /** Render the card in the dark register. Forwarded to Card's own `dark`, which clamps it on `transparent`. */
+  dark: { type: Boolean, default: false },
+  /** The card's edge: 'none' (the default) | 'hairline' | 'strong'. Forwarded to Card's own `border`. */
+  border: {
+    type: String,
+    default: 'none',
+    validator: (e) => ['none', 'hairline', 'strong'].includes(e),
+  },
+  /** How the figure sits in the tile: 'center' (default) reads best as one tile among several in a grid; 'start' keeps Kpi's own left-aligned layout. */
+  align: {
+    type: String,
+    // A prop rather than a bare scoped rule: `.stat-card` is scoped, so its `[data-v-…]` selector
+    // outranks a plain `items-start`/`text-left` utility passed at the tag — the same reason Grid
+    // exposes `align` instead of leaving cross-axis alignment to a class an author would
+    // reasonably expect to work.
+    default: 'center',
+    validator: (a) => ['center', 'start'].includes(a),
+  },
+  /** Kpi's name for the figure, shown above it. */
+  label: { type: String, required: true },
+  /** Kpi's number. Pre-formatted text goes through the `#metric` slot instead — forwarded to Kpi's own slot of the same name. */
+  metric: { type: Number, default: null },
+  /** How the figure is notated: 'full' spells out every digit, 'compact' abbreviates (1.2m, 999k). Kpi's own prop, forwarded unchanged. */
+  format: { type: String, default: 'compact' },
+  /** Decimal places to force on the formatted figure; omit to let the format's own rounding decide. Kpi's own prop, forwarded unchanged. */
+  precision: { type: Number, default: undefined },
+  /** Locale the figure and its delta are formatted in, e.g. 'en-GB'. Kpi's own prop, forwarded unchanged. */
+  locale: { type: String, default: 'en-GB' },
+  /** Suffix rendered immediately after the figure, e.g. '%' or 'km'. */
+  unit: { type: String, default: '' },
+  /** Required for an aggregate ("last 7 days"); omit for an instantaneous reading. */
+  period: { type: String, default: '' },
+  /** Rendered, never tooltip-only — a figure with a caveat has the caveat on the slide. */
+  caveat: { type: String, default: '' },
+  /** 'higher-is-better' | 'lower-is-better' | 'neutral' — Kpi's own delta-colour rule. */
+  sentiment: { type: String, default: 'neutral' },
+  /** { value, unit: 'percent'|'pp'|'absolute', comparisonLabel, previous?, display? } — Kpi's own delta shape. */
+  delta: { type: Object, default: undefined },
+});
+</script>
+
+<template>
+  <Card
+    :background="background"
+    :dark="dark"
+    :border="border"
+    class="stat-card"
+    :class="[{ 'is-named': BACKGROUND_NAMES.includes(background) }, `is-align-${align === 'start' ? 'start' : 'center'}`]"
+  >
+    <Kpi
+      :label="label"
+      :metric="metric"
+      :format="format"
+      :precision="precision"
+      :locale="locale"
+      :unit="unit"
+      :period="period"
+      :caveat="caveat"
+      :sentiment="sentiment"
+      :delta="delta"
+    >
+      <template v-if="$slots.metric" #metric><slot name="metric" /></template>
+    </Kpi>
+  </Card>
+</template>
+
+<style scoped>
+/* Framing only — nothing here touches a type role Kpi already owns. Kpi's own label/figure/
+   delta/foot rows are left-aligned block-and-flex content, so `text-align` on the card alone
+   reaches the label and figure but not the flex rows — those need their own `justify-content`. */
+.stat-card.is-align-center {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  text-align: center;
+}
+.stat-card.is-align-center :deep(.kpi-delta),
+.stat-card.is-align-center :deep(.kpi-foot) {
+  justify-content: center;
+}
+
+/* Completing Card's own legibility contract on a named background — see the doc comment above
+   for why base.css's `.deck-card.bg-*` rules never reach these classes on their own. One flat ink
+   for every role, inherited from the card, matching how base.css already flattens h1–h6/p to it: a
+   claim card states one thing, not a nuanced multi-colour reading. `surface` and `transparent`
+   need nothing here, dark or not — they borrow the page's ink, Kpi's own roles are tokens, and
+   `.deck-dark` on the card flips them. */
+.stat-card.is-named :deep(.kpi-label),
+.stat-card.is-named :deep(.kpi-figure),
+.stat-card.is-named :deep(.kpi-delta),
+.stat-card.is-named :deep(.kpi-delta.is-success),
+.stat-card.is-named :deep(.kpi-delta.is-error),
+.stat-card.is-named :deep(.kpi-foot) {
+  color: inherit;
+}
+.stat-card.is-named :deep(.kpi-comparison),
+.stat-card.is-named :deep(.kpi-caveat) {
+  color: inherit;
+  opacity: 0.85;
+}
+</style>