@humanforest/slidev-theme 0.1.0

package/components/ChordChart.vue

@@ -0,0 +1,264 @@
+<script setup>
+/*
+  A chord diagram sized for a room — the flows BETWEEN the members of one set, drawn as a ring.
+
+  A chord answers "who trades with whom": every member both sends and receives, and the ribbon
+  joining a pair is the volume between them. When the flow only ever runs forwards, through stages
+  that never send anything back — visits into sign-ups into rides — the ring is the wrong shape and
+  the chart is a Sankey. A circle invites an audience to look for a circularity the data does not
+  contain.
+
+  FIVE NODES, no sixth. The ring inherits the palette ceiling, and here the ceiling is doing
+  legibility work as well as palette work: five members already allow ten ribbons, which makes this
+  the densest mark in the deck's set. A sixth draws chartData.ts's `over-capacity` sentence instead.
+
+  ONE LEVEL. `nodeLevels` bands the ring into parents and children, which is a drill-down for a
+  dashboard somebody can hover; a slide is read in seconds and has no hover, so the ring stays flat.
+  That also makes `radiusScaleExponent` inert — with a single level every leaf sits at y1 = 1, the
+  top of the radius scale's domain, so the exponent has nothing to bend.
+
+  Real @unovis/vue mark, ChartFrame.vue for the ceremony, chartData.ts for the palette and states.
+*/
+import { computed } from 'vue';
+import { VisSingleContainer, VisChordDiagram, VisTooltip, VisChordDiagramSelectors } from '@unovis/vue';
+import { deckTooltip, tipFrame } from './chartTip';
+import ChartFrame from './ChartFrame.vue';
+import { SERIES_CEILING, formatValue, isPlottable, seriesVar, stateMessage } from './chartData';
+
+const props = defineProps({
+  /** The ring's members: `[{ id, label }]`, clockwise from twelve. `id` is what the links point at, compared as text, so `1` and `'1'` name the same member; `label` is what the legend calls it. */
+  nodes: { type: Array, required: true },
+  /** The flows: `[{ source, target, value }]`, source and target being node ids. A flow from a member to itself is not a chord, and neither is one naming an id that is not in `nodes`: both are dropped, and a ring left with no flows draws the empty state. */
+  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 },
+  /** Thickness of the arc band in px. The library's 15 is a rim on a dashboard and a hairline on a projector. */
+  nodeWidth: { type: Number, default: 28 },
+  /** Name each arc on the ring itself. Off by default — see the note at the mark; the labels are charged against the radius. */
+  nodeLabels: { type: Boolean, default: false },
+  /** Id of the one node the slide is about: its arc and every ribbon touching it stay lit, everything else dims. An id no node carries is not a highlight. */
+  highlight: { type: String, default: null },
+  /** Draw the node legend. A ring with neither legend nor labels says nothing. */
+  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 — including a set of flows that are all zero. */
+  empty: { type: String, default: 'No data' },
+});
+
+/** The identity a node is matched on, here and inside Unovis: its own id, or its position. */
+const idOf = (n, i) => String(n?.id ?? i);
+
+const nodeList = computed(() => (Array.isArray(props.nodes) ? props.nodes : []));
+const ids = computed(() => new Set(nodeList.value.map(idOf)));
+
+/*
+  ★ A LINK UNOVIS WOULD NOT DRAW NEVER REACHES IT, and none of these three clauses is tidiness.
+  Each is the difference between an honest empty state and a ring of slivers.
+
+  NO FINITE, POSITIVE VALUE. `_layoutData` adds every link's value into BOTH endpoints' running
+  totals and only afterwards filters the valueless links out (`links.filter(d => d._state.value)`),
+  so a MISSING `value` — undefined, or any non-numeric field — puts `0 + undefined`, NaN, into two
+  nodes' totals. d3's `sum` reads that back as `+NaN || 0`, both arcs collapse, and every other
+  ribbon at those two nodes is then sized by `value / node.value`, i.e. divided by nought. One bad
+  row, two dead arcs, no error. A `null` is the quiet case — `0 + null` is 0, so it poisons nothing
+  — but it is still not a flow, and a negative one has no ribbon either: the width would run
+  backwards.
+
+  AN ENDPOINT THAT IS NOT A MEMBER, OR IS BOTH ENDPOINTS. The graph data model drops both itself
+  (data-models/graph.js: `l.source === l.target` with a console warning, then `l.source && l.target`
+  once `findNode` has failed) — but it does that AFTER this component has already called the chart
+  ready, so without these clauses a slide whose links name a member that was since renamed draws the
+  slivers described below and says nothing about why. Matched as text against the ids handed to
+  Unovis, which is why the set is built from `idOf` rather than from `n.id`.
+*/
+const flows = computed(() =>
+  (Array.isArray(props.links) ? props.links : []).filter(
+    (l) =>
+      isPlottable(l.value) &&
+      l.value > 0 &&
+      String(l.source) !== String(l.target) &&
+      ids.value.has(String(l.source)) &&
+      ids.value.has(String(l.target)),
+  ),
+);
+
+/*
+  The ring's own state decision, spoken in chartData.ts's vocabulary so `stateMessage` prints the
+  same sentences the rest of the chart set does. The palette ceiling counts NODES here, and a ring
+  whose flows have all dropped out is `no-values`: Unovis would still draw the members, as a set of
+  disconnected slivers each exactly Math.PI/180 wide — one degree, the arc generator's Math.PI/360
+  either side of a node whose value is nought — which looks like a chart rather than like missing
+  data.
+*/
+const state = computed(() => {
+  const nodes = nodeList.value;
+  if (nodes.length === 0) return { kind: 'empty', reason: 'no-rows' };
+  if (nodes.length > SERIES_CEILING) return { kind: 'over-capacity', count: nodes.length };
+  if (flows.value.length === 0) return { kind: 'empty', reason: 'no-values' };
+  return {
+    kind: 'ready',
+    series: nodes.map((n, i) => ({ key: idOf(n, i), name: String(n.label ?? n.id ?? i + 1), 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 : []));
+
+/*
+  Both tables are normalised to the id space above before the model sees them, endpoints included.
+  `findNode` reads a NUMERIC source as an INDEX into the node array and a string as an id, so an
+  unstringed `source: 1` beside a node carrying `id: 1` resolves to whichever member happens to sit
+  second — agreeing with this component's own matching by accident, and stopping the moment the
+  array is reordered. Handing Unovis strings removes the second addressing mode entirely.
+*/
+const data = computed(() => ({
+  nodes: nodeList.value.map((n, i) => ({ ...n, id: idOf(n, i) })),
+  links: flows.value.map((l) => ({ ...l, source: String(l.source), target: String(l.target) })),
+}));
+
+// Accessors key off the id, never object identity: the graph data model deep-clones what it is
+// handed, so the node this is called with is never the node the slide wrote.
+const colorById = computed(() => new Map(seriesList.value.map((s) => [s.key, s.color])));
+const nodeColor = (n) => colorById.value.get(String(n.id)) ?? '';
+// A ribbon takes its SOURCE's colour, so the ring reads as "what leaves each member" rather than as
+// a set of unattributable bands. Unovis' own default is a flat pale blue for every flow.
+const linkColor = (l) => colorById.value.get(String(l.source?.id)) ?? '';
+
+/*
+  ★ THE ACCESSOR'S IDENTITY IS THE PROP, which is why this is a computed and not one stable arrow
+  reading `props.nodeLabels` from inside. The @unovis/vue wrapper re-configures its mark only when
+  `arePropsEqual` reports the forwarded props changed, and that comparison ends at `a === b` for
+  anything that is not an object (utils/data.js, `isEqual`) — so a function whose reference never
+  changes is never a change, whatever it has closed over. `nodeLabels` is not forwarded to the mark
+  at all, so nothing else would fire either, and `:node-labels="$clicks > 0"` would reveal nothing
+  until an unrelated prop happened to change in the same tick.
+*/
+const nodeLabel = computed(() => (props.nodeLabels ? (n) => String(n.label ?? n.id) : () => ''));
+
+/*
+  ★ `undefined`, NOT null, for the highlight: `_forceHighlight` tests `highlightedNodeId !==
+  undefined`, so a null turns the dimming on and lights nothing. An id no member carries does the
+  same thing for a different reason — the whole ring at 0.25 opacity, no explanation — so it is not
+  a highlight either.
+*/
+const highlighted = computed(() =>
+  props.highlight != null && ids.value.has(props.highlight) ? props.highlight : undefined,
+);
+
+/*
+  ★★ HIGHLIGHTING A NODE DIMS EVERY RIBBON, ITS OWN INCLUDED, unless this list is computed here.
+  Setting `highlightedNodeId` turns on the component's `_forceHighlight`, which puts the `transparent`
+  class on the whole group; that class drops every link WITHOUT the highlighted class to 0.25
+  opacity, and the only thing that ever adds the highlighted class is
+  `highlightedLinkIds?.includes(id)`. Unovis fills that list from hover, which a projected slide
+  never receives, so a deck has to name the ribbons itself.
+
+  The id each link is matched on is its own `id` when it has one and otherwise `_indexGlobal`, its
+  INDEX in the array handed to the container — which is why this maps over the filtered flows and
+  not the prop.
+*/
+const highlightedLinkIds = computed(() =>
+  highlighted.value === undefined
+    ? []
+    : flows.value.flatMap((l, i) =>
+        String(l.source) === highlighted.value || String(l.target) === highlighted.value ? [l.id ?? i] : [],
+      ),
+);
+
+/*
+  A chord answers the same two questions a Sankey does — a NODE is everything through one member, a
+  RIBBON is one pair — so it takes the same pair of templates.
+
+  ★ THE NAME IS READ DIRECTLY, not through `nodeLabel`: that computed returns an empty string when
+  `nodeLabels` is off, which is right for the ring and wrong for a tooltip, whose whole job is to
+  name the thing under the pointer.
+*/
+const chordName = (n) => String(n?.label ?? n?.id ?? n?.data?.id ?? '');
+const nodeTip = (n) => tipFrame(chordName(n?.data ?? n), [
+  { swatch: nodeColor(n?.data ?? n), label: 'Total', value: formatValue(n?.value ?? 0) },
+]);
+const linkTip = (l) => tipFrame(
+  `${chordName(l?.source?.data ?? l?.source)} ↔ ${chordName(l?.target?.data ?? l?.target)}`,
+  [{ label: 'Flow', value: formatValue(l?.data?.value ?? l?.value ?? 0) }],
+);
+</script>
+
+<template>
+  <ChartFrame
+    :series="seriesList"
+    :height="height"
+    :legend="legend"
+    :legend-position="legendPosition"
+    :message="message"
+  >
+    <div class="deck-chord">
+      <VisSingleContainer :data="data" :height="height" :duration="0">
+        <!--
+          `perpendicular` labels, never the library's `along`. An along-label is set on a textPath
+          following its own arc, so it reads upside down for every member on the bottom half of the
+          ring, and it is charged against the length of that arc: modules/label.js trims the string
+          to fit BEFORE it measures, so the ordinary outcome for a long name is a middle-ellipsised
+          one, and the residual case — where even the trimmed string still measures wider than the
+          arc — appends no textPath at all and drops the label silently. Perpendicular labels are
+          always drawn and always upright; what they cost is radius, which is what the style block
+          measures and why `nodeLabels` is off.
+
+          0.04rad of pad, against the library's 0.02: the pad is the ONLY thing separating two arcs
+          here, where the donut also carries a 4px stroke in the ground colour. A gap is
+          padAngle × radius — about 4px at this height, where 9px reads from the back of a room.
+
+          Corner radius 4, not the donut's 8: a radius approaching half of the 28px band would turn
+          each arc into a pill.
+        -->
+        <VisChordDiagram
+          :node-color="nodeColor"
+          :link-color="linkColor"
+          :node-width="nodeWidth"
+          :node-label="nodeLabel"
+          node-label-color="var(--deck-fg)"
+          node-label-alignment="perpendicular"
+          :pad-angle="0.04"
+          :corner-radius="4"
+          :highlighted-node-id="highlighted"
+          :highlighted-link-ids="highlightedLinkIds"
+        />
+        <VisTooltip v-bind="deckTooltip()" :triggers="{ [VisChordDiagramSelectors.node]: nodeTip, [VisChordDiagramSelectors.link]: linkTip }" />
+      </VisSingleContainer>
+    </div>
+  </ChartFrame>
+</template>
+
+<style scoped>
+.deck-chord {
+  /*
+    The label tier, and it is not only a type decision. Unovis sizes chord labels at `1em`, which
+    inherits whatever the slide is running, so a ring label would silently be a different size from
+    every axis tick in the deck; this pins it to the same small body tier (2.25rem / 36px) that
+    ChartFrame gives the axes.
+
+    ★ THE SAME NUMBER SETS THE RADIUS. `bleed` reads this variable back out of the DOM
+    (getCSSVariableValueInPixels against the chord's own element — a computed custom property is
+    inherited, so any ancestor would serve; it is declared HERE rather than in ChartFrame's adapter
+    because it belongs to this one mark and the adapter is the ceremony every chart shares) and
+    charges each label's ESTIMATED width against the ring: chars × font-size × --vis-font-wh-ratio,
+    the ratio being 0.5 and read off document.body. Radius is then min(width, height) / 2 minus the
+    widest of those, each of which also carries the library's own 3px of padding either side.
+
+    So at 36px each character of the longest name costs 18px of radius. "Westminster" is eleven of
+    them: 198px, 204px of bleed with the padding, and on the default 480px plot — a 240px radius —
+    that leaves a 36px ring. Short names, or no names, which is what the legend is for and why
+    `nodeLabels` defaults off.
+  */
+  --vis-chord-diagram-label-text-font-size: var(--type-deck-body-sm-size);
+}
+</style>

package/components/ComposedChart.vue

@@ -0,0 +1,187 @@
+<script setup>
+/*
+  A composed chart sized for a room: volume as bars, with a second quantity drawn over them as a
+  line, on one shared x axis. Real @unovis/vue marks — VisStackedBar and VisLine inside ONE
+  VisXYContainer — ChartFrame.vue for ceremony, chartData.ts for shaping.
+
+  ★ BOTH MARKS ARE MEASURED AGAINST THE SAME Y SCALE. An XY container resolves one y domain across
+  every child — `_updateScalesDomain` merges every component's extent and sets the SAME domain on
+  all of them — so the line reads off the axis the bars read off, and there is no second axis here
+  to rescue it. That is honest only while the two carry the SAME UNIT — rides against rides, pounds
+  against pounds — where the line is a subtotal, a rolling mean, a target, or last year's version of
+  the quantity the bars count.
+
+  Two different units on that one scale is where the chart starts lying, and it lies in both
+  directions. A percentage plotted beside a count in the thousands lies flat along the floor and
+  says nothing is happening. Rescaling it to be visible — the twin-axis chart every spreadsheet
+  offers — is worse, because the height at which the line crosses the bars is then chosen by
+  whoever picked the scaling: any two series can be made to appear to move together, or not to, and
+  an audience reading a slide in seconds has no way to see which was done.
+
+  So when the units differ, fix it at the CALL SITE, not with a second axis. Either express the
+  second quantity in the bars' own unit — 8% of 13,000 rides is 1,040 rides, so plot 1,040 — or
+  draw two charts stacked over the same x, each keeping its own axis, where neither mark borrows
+  authority from the other.
+
+  Note also that the bars' contribution to that shared domain is the STACK TOTAL, not any one
+  segment: StackedBar overrides `getYDataExtent` to return the summed extent. A line whose values
+  are of the order of a single segment sits low against a tall stack, which is correct arithmetic
+  and still a poor picture — another case for two charts rather than one.
+
+  Which series is a bar and which is a line is not something the data can say, so nothing is
+  inferred here: `barSeries` and `lineSeries` are both required and both explicit. The two resolve
+  through a single chartData call so the palette runs across the pair without repeating a colour,
+  and so the five-colour ceiling counts the whole chart rather than each mark separately.
+*/
+import { computed } from 'vue';
+import { VisXYContainer, VisAxis, VisStackedBar, VisLine, 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 drawn as bars, stacked bottom to top and first in legend order: `[{ key, name }]`. */
+  barSeries: { type: Array, required: true },
+  /** Series drawn as lines, over the bars and after them in legend order: `[{ key, name }]`. Same unit as the bars — see the header. */
+  lineSeries: { 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 series legend. Two marks on one axis are unreadable without one. */
+  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. It titles BOTH marks, so name the unit the two share. */
+  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 },
+  /** The sentence drawn when there is nothing to plot. */
+  empty: { type: String, default: 'No data' },
+});
+
+// Bars first, then lines, as one list: resolveSeries colours by position, so this ordering is what
+// makes the palette run across the two marks instead of starting again at series 1 for the line.
+// Passing an empty list would send chartData off to INFER series from the first row, which is the
+// one thing this chart must not do — the inference cannot know which column is a line, and every
+// column would land on the wrong side of the split below. Empty is the empty state instead.
+const declared = computed(() => [...(props.barSeries ?? []), ...(props.lineSeries ?? [])]);
+const state = computed(() =>
+  declared.value.length ? chartState(props.data, declared.value) : { kind: 'empty', reason: 'no-series' },
+);
+const message = computed(() => (state.value.kind === 'ready' ? null : stateMessage(state.value, props.empty)));
+const seriesList = computed(() => (state.value.kind === 'ready' ? state.value.series : []));
+
+// The same split, back apart, at the boundary the two props defined. The legend keeps the whole
+// list — one chart, one key — which does mean a line and a bar both read as a disc there. Name the
+// line series for what it is ("Rolling mean", "Target") and the name carries what the bullet cannot.
+const barList = computed(() => seriesList.value.slice(0, props.barSeries?.length ?? 0));
+const lineList = computed(() => seriesList.value.slice(props.barSeries?.length ?? 0));
+
+const x = (_d, i) => i;
+const barY = computed(() => barList.value.map((s) => (d) => d[s.key]));
+const lineY = computed(() => lineList.value.map((s) => (d) => d[s.key]));
+const barColors = computed(() => barList.value.map((s) => s.color));
+const lineColors = computed(() => lineList.value.map((s) => s.color));
+/* The crosshair spans BOTH families, so its swatches are the whole series list in legend order —
+   bars then lines — not one of the two colour arrays the marks bind. */
+const allColors = computed(() => seriesList.value.map((s) => s.color));
+const allY = computed(() => seriesList.value.map((s) => (d) => d[s.key]));
+
+// Half a column of outer gutter, as in StackedBarChart.vue. Both marks read the same index
+// accessor against it, which is what puts each line point over the centre of its own column.
+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 }"
+    >
+      <!-- DECLARATION ORDER IS Z-ORDER, and it is load-bearing rather than incidental: XYContainer
+           appends each component's element to the SVG in the order the components registered, after
+           both axes, and the Vue wrappers register on mount in template order. So the bars are
+           declared first and the line lands on top of them, which is the only stacking that works —
+           a line hidden behind a column is a line nobody reads.
+           8px corners, matching --deck-radius-item: Unovis clamps the radius against the segment's
+           own height, so a thin slice degrades to a square rather than deforming. -->
+      <VisStackedBar :x="x" :y="barY" :color="barColors" :rounded-corners="8" :bar-padding="0.25" />
+      <!-- 6px, as in LineChart.vue: a 2px stroke is a hairline on a projector, and here it also has
+           to hold its own against columns of solid colour underneath it.
+
+           ⚠ A ONE-COLUMN COMPOSED CHART DRAWS ITS BAR AND NO LINE, with no message. Unovis builds
+           the stroke with d3-shape's `line()`, which emits `M100,50Z` for a single point — a
+           zero-length subpath — and sets no `stroke-linecap`, so at the default `butt` nothing is
+           painted. The state stays `ready` because the row and the reading both exist. Harmless in
+           the two-mark case this chart is for (a target line needs a run to be a target), and
+           recorded because the bars still render, so the slide LOOKS finished while a whole series
+           is missing. A composed chart wants at least two columns; one column is a Kpi. -->
+      <VisLine :x="x" :y="lineY" :color="lineColors" :line-width="6" />
+      <VisAxis
+        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
+      />
+      <!-- One y axis, titled once, because there is one unit. See the header for the case where
+           that is not true and what to do about it. -->
+      <VisAxis
+        type="y"
+        :tick-format="format"
+        :num-ticks="4"
+        :tick-line="false"
+        :domain-line="false"
+        :tick-padding="16"
+        :label="yLabel"
+        :label-margin="24"
+      />
+      <!-- ★ BOTH, because this chart is both: the bar family stacks and the line family
+           rides over it, so the bars' circles come from the accumulator and the lines' from their
+           own values. Passing one accessor for all of them puts a circle where neither mark is. -->
+      <VisCrosshair :duration="crosshairMs" :hideWhenFarFromPointer="CROSSHAIR_HIDE_WHEN_FAR" :circleRadius="CROSSHAIR_CIRCLE_R" :x="x" :y="lineY" :yStacked="barY" :template="tip" :color="allColors" />
+      <VisTooltip v-bind="deckTooltip()" />
+    </VisXYContainer>
+  </ChartFrame>
+</template>

package/components/Contents.vue

@@ -0,0 +1,86 @@
+<!--
+  The deck's contents page, built from the dividers rather than from a per-slide declaration.
+
+  ★★ THIS EXISTS BECAUSE SLIDEV'S OWN `<Toc>` CANNOT BE MADE TO NEST WITHOUT TOUCHING EVERY SLIDE.
+
+  `useTocTree` builds its tree from every slide that has a TITLE — and a title is just the first
+  `#`-heading in the body, so all 294 slides in the specimen book qualify, not the 34 that are
+  structure. Depth comes from a `level` frontmatter key, defaulting to the heading's own depth, so
+  an ordinary content slide is `level: 1` and sits at the TOP of the tree. The next subsection then
+  nests under THAT SLIDE rather than under its section, and `filterTree` — which drops a hidden item
+  together with its whole subtree — deletes the subsection along with the content slide hiding it.
+
+  Two things follow, both measured on the running deck rather than argued:
+
+    · Nesting needs a deeper `level` on all 260 content slides. There is no way round it: the
+      parser reads `slide.level` from a slide's OWN frontmatter BEFORE the headmatter's `defaults:`
+      merge, so it cannot be defaulted. Tried it — the contents came back with FIFTEEN entries
+      instead of thirty-four, the nine sections plus only the first subsection of each, those being
+      the ones with no content slide between them and their divider.
+
+    · `Toc.vue` imports `TocList.vue` by RELATIVE PATH, and neither takes a slot. A theme cannot
+      override either, so an entry cannot be restyled at all — which this deck needs, since a
+      contents page here is typeset like everything else.
+
+  So the tree is derived from what the dividers ALREADY say. `divider()` and `subsection()` write a
+  `rank`, that rank is the depth, and no other slide in the deck carries a single key for the sake
+  of this page.
+
+  ★ `hideInToc` IS STILL READ, and three slides set it. A divider is not automatically a contents
+  entry: the Frames section specimens the divider layout itself, and those slides carry a real
+  `rank` and a real h1 while being PICTURES of openers rather than openers. Without the opt-out the
+  contents lists sections called "Section" and "Subsection". The key is Slidev's own and means
+  exactly what it says here, which is why it is reused rather than replaced with a private one.
+-->
+<script setup>
+import { computed } from 'vue';
+import { useNav } from '@slidev/client';
+
+const { slides } = useNav();
+
+/*
+  ★ A DIVIDER WITH NO TITLE IS NOT AN ENTRY EITHER, and that is load-bearing rather than defensive:
+  the layout gallery at the head of Frames draws one slide per layout including `divider`, and that
+  slide has no h1 because it is a diagram of the layout's regions. It needs no opt-out — it has
+  nothing to list — so the title check does the work and the frontmatter stays clean.
+
+  `topic` is excluded by rank: it is the third divider rank, used inside a run rather than to open
+  one, and a contents page that listed topics would be a list of slides again.
+*/
+const entries = computed(() => {
+  const out = [];
+  for (const route of slides.value) {
+    const fm = route.meta?.slide?.frontmatter ?? {};
+    const title = route.meta?.slide?.title;
+    if (fm.layout !== 'divider' || !title || fm.hideInToc) continue;
+    // `rank` defaults to section in divider.vue, so an absent rank is a section here too.
+    const rank = fm.rank ?? 'section';
+    if (rank === 'topic') continue;
+    if (rank === 'subsection' && out.length) out[out.length - 1].children.push({ no: route.no, title });
+    else out.push({ no: route.no, title, children: [] });
+  }
+  return out;
+});
+</script>
+
+<template>
+  <div class="deck-contents">
+    <!--
+    ★ `<Link>` RATHER THAN A MARKDOWN LINK OR A BARE <a>, and the difference is whether it works.
+    Measured on this page in an earlier cut: `[**Frames**](/21)` changed location.pathname to /21
+    and left the deck on slide 3 — a plain href is not a RouterLink, vue-router does not intercept
+    it, and no full load happens either. Slidev ships the component for exactly this, and it falls
+    back to an `#N` anchor in print mode.
+    -->
+    <ol class="deck-contents-sections">
+      <li v-for="section of entries" :key="section.no" class="deck-contents-section">
+        <Link :to="section.no" class="deck-contents-link is-section">{{ section.title }}</Link>
+        <ol v-if="section.children.length" class="deck-contents-subsections">
+          <li v-for="child of section.children" :key="child.no" class="deck-contents-subsection">
+            <Link :to="child.no" class="deck-contents-link">{{ child.title }}</Link>
+          </li>
+        </ol>
+      </li>
+    </ol>
+  </div>
+</template>