@humanforest/slidev-theme 0.1.0

package/components/TimelineChart.vue

@@ -0,0 +1,329 @@
+<script setup>
+/*
+  A timeline chart sized for a room — labelled rows of bars, each bar a real span of dates.
+
+  ★ THIS IS NOT Timeline.vue, AND THE TWO ARE NOT SUBSTITUTES. Timeline.vue is presentational: a
+  sequence of stops on a rule, evenly spaced whatever their dates say, because its subject is the
+  ORDER things happened in and how far along the journey is. This one is a CHART — the x axis is
+  time to scale, so a bar's position is its real start and its width is its real duration, and a
+  three-month piece of work is a quarter of the width of a year-long one. Reach for Timeline.vue to
+  tell a story (2021 · 2023 · 2025 · now); reach for this when the OVERLAP is the point — what runs
+  alongside what, what waits on what, where the crunch is.
+
+  NO LEGEND, and the row labels are the reason. Every other chart here needs a legend because its
+  marks are unnamed; a timeline draws each row's name beside it, in place, at the height of the bars
+  it belongs to. A legend would say the same thing a second time and spend a whole line of the slide
+  doing it. Colour still carries the row — it is what lets the eye trace a bar back across a wide
+  plot to the name at the left — so the palette's five-colour ceiling is this chart's ROW ceiling,
+  and a sixth row draws the over-capacity message rather than a repeated colour. Those labels are
+  drawn only because `showRowLabels` is BOUND; the template records why that is not a formality.
+
+  THE FRAME TAKES ITS HEIGHT FROM ITS ROWS, unlike its siblings, because rows are discrete: two
+  rows in a 480px well would be two bars adrift in a field of nothing. Height is `rowHeight` per row
+  plus the top margin plus an allowance for the axis, so a two-row timeline is short and a five-row
+  one is tall — the same reason a table with two rows is shorter than one with five. `height` still
+  sizes the empty-state well.
+
+  Real @unovis/vue mark, ChartFrame.vue for ceremony, chartData.ts for shaping.
+*/
+import { computed } from 'vue';
+import { VisXYContainer, VisAxis, VisTimeline, VisTooltip, VisTimelineSelectors } from '@unovis/vue';
+import { deckTooltip, tipFrame } from './chartTip';
+import ChartFrame from './ChartFrame.vue';
+import { SERIES_CEILING, isPlottable, scatterGroups, seriesVar, stateMessage, tickIndices } from './chartData';
+
+const props = defineProps({
+  /** Rows: `[{ label, start, end, row? }]`. `start`/`end` are Dates or anything `new Date()` parses — a timeline's x is time, so a bare year number reads as 1970. `row` groups bars onto one line; omit it and each item gets its own row, named by its `label`. */
+  data: { type: Array, required: true },
+  /** Height of the EMPTY-STATE well in px; 0 fills. A drawn timeline ignores it — the frame takes
+   *  `rowHeight` per row plus the axis, for the reason the header gives, so a number here can
+   *  neither stretch nor squash the rows. */
+  height: { type: Number, default: 0 },
+  /** Height of one row in px, bar and gutter together. */
+  rowHeight: { type: Number, default: 96 },
+  /** Bar thickness in px. The remainder of `rowHeight` is the gutter, split above and below. */
+  barWidth: { type: Number, default: 56 },
+  /** Width of the row-label gutter in px. Fixed rather than measured, so consecutive timeline slides start their plots at the same x instead of shuffling. Longer names are trimmed at the end. */
+  labelWidth: { type: Number, default: 320 },
+  /** Formats the date tick labels. The default is resolved in the component rather than here because it reads the data's extent: a British short month, with the year added only when the timeline crosses one. */
+  format: { type: Function, default: null },
+  /** Ceiling on date tick labels. Deck labels are 36px, so more than a handful collide. */
+  maxTicks: { type: Number, default: 6 },
+  /** The sentence drawn when there is nothing to plot. */
+  empty: { type: String, default: 'No data' },
+});
+
+const toTime = (v) => (v instanceof Date ? v.getTime() : typeof v === 'string' ? Date.parse(v) : v);
+
+/*
+  The row key is resolved HERE rather than left to an accessor, and it is never allowed to be empty
+  — not even when a caller passes `row: ''`. Unovis keys a row by
+  ``getString(d, config.lineRow) || `${i + 1}` `` (components/timeline/index.js, `_getRowLabels`), so
+  a falsy key silently becomes the item's own index: a set of unnamed items would split into N
+  numbered rows in the mark while this file, seeing one empty key, counted a single row and painted
+  them all series 1. Baking a non-empty key into the datum keeps the two counts the same by
+  construction.
+
+  A span with a missing or unparseable date is not a span, and neither is a backwards one — Unovis
+  warns on a negative length and draws nothing — so they are dropped here. A PARTIAL drop is SILENT:
+  the state below speaks only when nothing is left to plot, which is the same rule `scatterState`
+  applies to a point with no y. Worth knowing when a row goes missing from a slide.
+*/
+const spans = computed(() =>
+  (Array.isArray(props.data) ? props.data : [])
+    .map((d, i) => ({
+      ...d,
+      row: String(d.row ?? d.label ?? '') || String(i + 1),
+      start: toTime(d.start),
+      end: toTime(d.end),
+    }))
+    .filter((d) => isPlottable(d.start) && isPlottable(d.end) && d.end >= d.start),
+);
+
+// The deck's distinct-in-first-seen-order helper. The name is the scatter's; the behaviour is general.
+const rows = computed(() => scatterGroups(spans.value, 'row'));
+
+/*
+  ⚠ FIRST-SEEN ORDER IS THE COLOUR ORDER, NOT ALWAYS THE VERTICAL ORDER. Unovis builds its rows with
+  `groupBy` — a plain-object reduce — and reads them back with `Object.entries`, which puts
+  integer-like keys FIRST and in ascending numeric order, so rows named "2024" and "2026" jump above
+  every worded row whatever the data said. Colour is keyed on the row NAME here, so it stays attached
+  to the right row either way; only the stacking order moves. Name rows with words and the two agree.
+
+  The decision itself is hand-rolled rather than taken from chartData.ts: `chartState` resolves
+  series from a row's numeric COLUMNS and would report `no-series` for every span list. The wording
+  and the ceiling still come from the shared module, so the sentence on the slide is the one every
+  other chart prints — but these three rules are not covered by test/chartData.static.test.ts.
+*/
+const state = computed(() => {
+  if (!Array.isArray(props.data) || props.data.length === 0) return { kind: 'empty', reason: 'no-rows' };
+  if (spans.value.length === 0) return { kind: 'empty', reason: 'no-values' };
+  if (rows.value.length > SERIES_CEILING) return { kind: 'over-capacity', count: rows.value.length };
+  return { kind: 'ready', series: rows.value.map((name, i) => ({ key: name, name, color: seriesVar(i) })) };
+});
+const message = computed(() => (state.value.kind === 'ready' ? null : stateMessage(state.value, props.empty)));
+
+const extent = computed(() => {
+  if (!spans.value.length) return [0, 0];
+  return [Math.min(...spans.value.map((s) => s.start)), Math.max(...spans.value.map((s) => s.end))];
+});
+
+/*
+  A moment — an item whose start and end are the same day — has zero width and draws nothing at all:
+  the mark's own floor is `Math.max(0, lineLength)` unless `showEmptySegments` is on, and that switch
+  also re-lengths and re-centres every short bar, which is a lie about a duration. The floor here is
+  1% of the timeline's own extent, which over a year is 3.6 days and about 15px across a full-slide
+  plot: visible as a narrow bar, and far too small to inflate a span anyone is reading off the axis.
+  It scales with the data rather than being a fixed number of days, so a two-week timeline and a
+  five-year one both get a mark of the same size.
+
+  ★ AND WHEN EVERY SPAN IS THE SAME MOMENT the extent itself is zero, so a floor derived from it is
+  zero too: the chart drew nothing while its state still said ready — an empty plot with no sentence,
+  the exact silent failure the states exist to prevent. A collapsed extent therefore gets a one-day
+  window centred on the instant, passed as an explicit `xDomain`. Widening only the DURATION would
+  not do: the container derives its own domain from start + duration, so the moment would come back
+  as a bar filling the whole plot. `null` is the auto case — the container reads
+  `xDomain?.[0] ?? min` (containers/xy-container/index.js, `_updateScalesDomain`).
+*/
+const DAY = 24 * 60 * 60 * 1000;
+const axisSpan = computed(() => extent.value[1] - extent.value[0] || DAY);
+const xDomain = computed(() => {
+  const [from, to] = extent.value;
+  return to > from ? null : [from - axisSpan.value / 2, from + axisSpan.value / 2];
+});
+const minSpan = computed(() => axisSpan.value * 0.01);
+
+const x = (d) => d.start;
+const lineDuration = (d) => Math.max(d.end - d.start, minSpan.value);
+const lineRow = (d) => d.row;
+const color = (d) => (state.value.kind === 'ready' ? state.value.series[rows.value.indexOf(d.row)]?.color : undefined);
+
+/*
+  The plot's own height: a row band each, plus the top margin, plus an allowance for the axis.
+
+  The container hands its components `containerHeight - margin.top - margin.bottom`, where that
+  margin is the authored one PLUS the axis's own measured bbox (xy-container's `_getMargin`), so
+  anything left out of this sum comes off the ROW STACK — and the mark clips its rows to the height
+  it is given. 64px for the axis is arithmetic off the type roles rather than a measurement: a 36px
+  tick label plus 16px of tick padding plus the 2px domain rule is 54, and the remainder is the
+  label's descender and half-leading. Deliberately generous, because the two directions fail
+  differently — over-allow and the rows sit in a little spare ground with nothing drawn in it;
+  under-allow and the bottom row is clipped AND the mark's own scrollbar surfaces on the slide.
+*/
+const MARGIN_TOP = 16;
+const AXIS_HEIGHT = 64;
+const plotHeight = computed(() => rows.value.length * props.rowHeight + MARGIN_TOP + AXIS_HEIGHT);
+
+/*
+  The ticks are the data's OWN boundaries — every distinct start and end — rather than a scale's
+  round numbers. On a deck that is the better axis: the dates an audience wants are the ones things
+  begin and end on, and a tick that lands exactly on a bar's edge needs no tracing back. `tickIndices`
+  thins them the same way it thins a line chart's categories, which also guarantees the last boundary
+  keeps its label — an axis whose final date is missing reads as though the work stops early.
+
+  Thinning is by index, so two boundaries a day apart can both survive it; `tickTextHideOverlapping`
+  drops the loser at paint time.
+*/
+const xTicks = computed(() => {
+  const marks = [...new Set(spans.value.flatMap((s) => [s.start, s.end]))].sort((a, b) => a - b);
+  return tickIndices(marks.length, props.maxTicks).map((i) => marks[i]);
+});
+
+// Within one calendar year the year is on every tick and says nothing six times over.
+const MONTH = new Intl.DateTimeFormat('en-GB', { month: 'short' });
+const MONTH_YEAR = new Intl.DateTimeFormat('en-GB', { month: 'short', year: 'numeric' });
+const sameYear = computed(() => new Date(extent.value[0]).getFullYear() === new Date(extent.value[1]).getFullYear());
+const xFormat = computed(() => props.format ?? ((t) => (sameYear.value ? MONTH : MONTH_YEAR).format(t)));
+
+/*
+  A timeline bar is a DURATION, so the tooltip says when it starts and ends rather than repeating
+  the row label the axis already carries. Both dates go through the axis' own formatter, or the
+  panel and the ticks would spell the same day two ways.
+*/
+const tip = (d) => tipFrame(String(d?.label ?? d?.row ?? ''), [
+  { label: 'From', value: xFormat.value(d?.start) },
+  { label: 'To', value: xFormat.value(d?.end) },
+]);
+</script>
+
+<template>
+  <ChartFrame :height="message ? height : plotHeight" :legend="false" :message="message">
+    <!-- The row labels are this chart's legend, drawn in place. See the header.
+    
+    ★ THE FRAME IS HANDED THE PLOT'S OWN HEIGHT, which is what keeps it off ChartFrame's fill
+    path. `height: 0` there means FILL, and a filling frame stretches to the slide while the rows
+    stay `rowHeight` apart: the surplus lands as dead ground under the axis — measured on the
+    specimen's Timeline chart slide, a 337px plot in a 487px box — and it also swallows the free
+    space `align: body-center` exists to split, so its three auto margins all resolve to 0 and the
+    block sits hard under the heading. The empty state keeps `height`, which has a well to size. -->
+    <div class="deck-timeline">
+      <VisXYContainer
+        :data="spans"
+        :height="plotHeight"
+        :duration="0"
+        :x-domain="xDomain"
+        :margin="{ top: MARGIN_TOP, right: 24, bottom: 0, left: 0 }"
+      >
+        <!-- ★★ camelCase ON THIS ONE COMPONENT, kebab-case on its siblings in the same template,
+             and the difference is not a style choice.
+
+             @unovis/vue's timeline wrapper calls `defineComponent` with NO `props` option
+             (node_modules/@unovis/vue/components/timeline/index.js) — one of two wrappers in 1.6.7
+             that does, crosshair being the other. Vue files every undeclared prop under the key
+             exactly as authored (runtime-core's `setFullProps`: `attrs[key] = value`, no camelize),
+             and the wrapper's `useForwardProps` spreads those attrs straight over the config. So
+             `:row-height` arrives as the config key "row-height", which `merge(defaultConfig,
+             config)` keeps as a junk property while `rowHeight` sits at its default of 22. Compiled
+             the template to check the other half: the compiler preserves an attribute name's
+             authored case verbatim, so camelCase here reaches the config and kebab-case does not.
+
+             What that cost while it was kebab: `lineDuration` unset falls back to the deprecated
+             `length`, whose default reads `d.length` — undefined, so `Math.max(0, 0)` was the whole
+             bar and EVERY bar was a zero-width rect. `lineRow` unset falls back to `type`, so each
+             item became its own numbered row. `showRowLabels` unset falls back to `showLabels`,
+             which is false, so the labels this chart uses INSTEAD of a legend never drew.
+
+             `showRowLabels` is bound rather than written as a bare attribute for a second reason: a
+             valueless attribute compiles to the empty string, and the mark reads
+             `config.showRowLabels ?? config.showLabels` — "" is falsy but not nullish, so it takes
+             neither branch's truth and the labels stay off.
+
+             VisXYContainer and VisAxis both declare their props, so kebab is correct there.
+
+             One consequence there is no reaching from out here: the wrapper leaves `inheritAttrs` at
+             its default, so these also land on its empty `<div data-vis-component>` as DOM
+             attributes. Inert, and the price of the only channel the wrapper offers.
+
+             ★ THE CURRENT NAMES, NOT THE ALIASES. `type`, `length`, `showLabels`, `labelWidth` and
+             `maxLabelWidth` all still work and are all deprecated, and the config reads them as
+             fallbacks (`rowLabelWidth ?? labelWidth`), so a file mixing the two generations gets
+             whichever the reader did not expect.
+
+             `rowFillEmptySpace` is off because the row bands are the ROWS: left on, the mark fills
+             any spare height with further banded rects, which at deck scale reads as empty rows
+             nobody passed. -->
+        <VisTimeline
+          :x="x"
+          :color="color"
+          :lineRow="lineRow"
+          :lineDuration="lineDuration"
+          :rowHeight="rowHeight"
+          :lineWidth="barWidth"
+          :showRowLabels="true"
+          :rowLabelWidth="labelWidth"
+          :rowLabelMargin="[0, 24]"
+          :rowFillEmptySpace="false"
+          rowLabelTrimMode="end"
+        />
+        <!-- The grid runs here, unlike the category charts: a bar's ends are numbers on a scale rather
+             than names in a list, so a reader has to be able to drop a line from one to the axis. -->
+        <VisAxis
+          type="x"
+          grid-line
+          :tick-line="false"
+          :tick-values="xTicks"
+          :tick-format="xFormat"
+          :tick-padding="16"
+          tick-text-hide-overlapping
+        />
+        <VisTooltip v-bind="deckTooltip()" :triggers="{ [VisTimelineSelectors.line]: tip }" />
+    </VisXYContainer>
+    </div>
+  </ChartFrame>
+</template>
+
+<style scoped>
+/*
+  ★★ THE ROW BANDS SHIP OPAQUE AND LIGHT, and turning them off does not help. Unovis injects
+  `--vis-timeline-row-even-fill-color` and `--vis-timeline-row-odd-fill-color` at `:root` at runtime
+  — a flat white and a pale grey-blue — and paints EVERY row rect with one of them at opacity 1, so
+  on a `deck-dark` slide the plot is a pale slab with the bars sitting on top of it.
+  `alternatingRowColors: false` only stops the odd class being added; the rects still fill, now
+  uniformly light. Re-pointing the two variables is the only fix, and the banding is worth keeping
+  once it is a deck colour: on a wide plot it is what carries the eye from a row's label across to
+  its bars.
+
+  Declared on a wrapper INSIDE the frame, the way ChordChart.vue declares its label size, and both
+  halves of that matter for the reasons ChartFrame's own adapter block records. A custom property
+  resolves at the NEAREST ancestor that declares it, so a wrapper around the mark beats a `:root`
+  default injected later whatever either selector's specificity; and that wrapper sits inside the
+  `.deck-dark` subtree, so `var(--deck-surface)` re-resolves with the slide instead of freezing at
+  its light value.
+
+  These live here rather than in ChartFrame because no other deck chart mounts a VisTimeline.
+*/
+.deck-timeline {
+  --vis-timeline-row-even-fill-color: transparent;
+  /*
+    A TINT OF THE INK RATHER THAN THE `--deck-surface` FILL, for two reasons that pull the same
+    way. A band is the largest area this chart paints — 96px tall and the full plot wide — and a
+    tint reads heavier the more of it there is, so the well's 8% that is right for a status track's
+    thin gutter comes out as a slab here. And a mix against `transparent` composites over whatever
+    ground the chart is standing on, where a mix against `--deck-bg` bakes in the slide's own.
+  */
+  --vis-timeline-row-odd-fill-color: color-mix(in oklab, var(--deck-fg) 5%, transparent);
+
+  /* 12px and a grey-blue by default — a caption for a dashboard, invisible in a room. The row names
+     are the subject of this chart, not its scale, so they take full-strength ink where the date
+     ticks take the muted axis colour. */
+  --vis-timeline-label-font-size: var(--type-deck-body-sm-size);
+  --vis-timeline-label-color: var(--deck-fg);
+}
+
+/*
+  THE BAR CORNERS, WHICH THE COMPONENT'S OWN CONFIG CANNOT SET AT THIS SIZE. `lineCap` is the only
+  knob Unovis offers and it is binary: `.attr('rx', d => config.lineCap ? d._height / 2 : null)`, so
+  `true` on a 56px bar is a 28px corner — a pill, which reads as a token rather than as a span with
+  a start and an end. `false` (the built default, whatever config.d.ts's comment says) is the sharp
+  rect this file shipped. The item rung sits between them.
+
+  Matched on the class SUFFIX because Unovis emits emotion-hashed names — the bar is
+  `css-1my6t8v-line`, with no bare `.line` beside it — and `$=` rather than `*=` because
+  `-line-group`, `-line-start-icon` and `-lines` all contain the same four letters. The hash is not
+  in the selector, only the semantic tail emotion appends, which is the same handle base.css uses
+  for the donut's central label.
+*/
+.deck-timeline :deep(rect[class$='-line']) {
+  rx: var(--deck-radius-item);
+}
+</style>

package/components/TreemapChart.vue

@@ -0,0 +1,267 @@
+<script setup>
+/*
+  A treemap sized for a room — part-to-whole when the parts are too many, or too uneven, for a donut.
+
+  A donut is read by ANGLE and dies past a handful of slices; a treemap is read by AREA and every
+  tile carries its own name, so twenty parts stay countable. The price is precision: nobody reads a
+  ratio off two rectangles of different aspect. It is the right mark when the point is "this one is
+  most of it", and the wrong one when the point is "these two are close".
+
+  ★ COLOUR IS BY GROUP, NOT BY TILE, which is the whole reason this chart can carry more parts than
+  the palette has colours. Rows with no `group` form one unnamed group and share series 1 — an
+  ungrouped treemap is deliberately monochrome, because the AREA is already the encoding and a
+  second one would be decoration. Grouped, the five-colour ceiling applies to the GROUPS, so five
+  groups of twenty tiles is a chart this palette can honestly paint, and a sixth group is the
+  over-capacity state rather than an invented colour.
+
+  Real @unovis/vue mark, ChartFrame.vue for ceremony, chartData.ts for shaping.
+*/
+import { computed } from 'vue';
+import { VisSingleContainer, VisTreemap, VisTooltip, VisTreemapSelectors } from '@unovis/vue';
+import { deckTooltip, tipFrame } from './chartTip';
+import ChartFrame from './ChartFrame.vue';
+import { formatValue, isPlottable, labelAt, scatterGroups, shareState, stateMessage } from './chartData';
+
+const props = defineProps({
+  /** Rows: `[{ label, value, group? }]`. `group` is optional; when present it is what the tile is coloured and legended by. */
+  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. Ignored when nothing is grouped — there is one colour and the tiles name themselves. On a GROUPED treemap the legend is the only thing that names a group, so turning it off leaves colour-coded tiles with nothing saying what the colours mean. */
+  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),
+  },
+  /** Formats the figure printed beside each tile's name. */
+  format: { type: Function, default: formatValue },
+  /** The sentence drawn when there is nothing to plot. */
+  empty: { type: String, default: 'No data' },
+});
+
+// The same mapping scatterGroups() uses, so the group a row is COUNTED in and the group it is DRAWN
+// in can never disagree.
+const groupOf = (row) => (row.group == null ? '' : String(row.group));
+
+// What the legend calls the bucket that rows with no `group` land in. Only ever read in the MIXED
+// case — with nothing grouped the legend is suppressed outright — but that case is the one that
+// breaks without it: shareState() passes '' through as a series NAME (its `typeof r.label ===
+// 'string'` test accepts the empty string), so ChartFrame draws a coloured bullet followed by
+// nothing. ScatterChart closes the same hole with `name || 'Points'`.
+const UNGROUPED = 'Other';
+
+// A tile is an area, so only a positive reading can be one. A gap has no area to draw, and a
+// negative value is summed into its parent by d3 and silently misallocates every sibling's share —
+// so both are dropped here rather than passed through as a rect nobody can see.
+const rows = computed(() => (props.data ?? []).filter((r) => isPlottable(r.value) && r.value > 0));
+
+const groups = computed(() => scatterGroups(rows.value));
+const grouped = computed(() => groups.value.some((g) => g !== ''));
+
+/*
+  The state decision is the DONUT's — shareState() — taken over the GROUPS rather than the rows,
+  because the groups are what ask for colours. Ten tiles in three groups is `ready`; six groups is
+  over-capacity and says so on the slide.
+
+  ⚠ stateMessage() words that state "6 series — this palette carries 5". The count is right and the
+  ceiling is right; the NOUN is `series` where this chart is gating GROUPS, over an arbitrary number
+  of tiles. Left alone rather than patched around here: the wording lives in chartData.ts precisely
+  so it is one string a test can pin, and rewriting it downstream is how six components end up with
+  six near-identical sentences.
+*/
+const groupRows = computed(() =>
+  groups.value.map((g) => ({
+    label: g || UNGROUPED,
+    value: rows.value.reduce((sum, r) => (groupOf(r) === g ? sum + r.value : sum), 0),
+  })),
+);
+const state = computed(() => shareState(groupRows.value));
+const message = computed(() => (state.value.kind === 'ready' ? null : stateMessage(state.value, props.empty)));
+
+// Re-keyed by POSITION. shareState() keys a series by its own value, which is unique enough for a
+// donut's hand-authored slice rows but not here: the values it is handed are group SUMS, and two
+// groups that happen to sum equal produce the same key twice in ChartFrame's legend `v-for` — a Vue
+// warning, and a list that can mis-patch. A group's position is unique by construction
+// (scatterGroups() dedupes), and this list, `groups` and the palette below all share that order.
+const seriesList = computed(() =>
+  state.value.kind === 'ready' ? state.value.series.map((s, i) => ({ ...s, key: String(i) })) : [],
+);
+
+/*
+  The layers ARE the hierarchy: one accessor per level, each naming the node a row belongs to.
+  Unovis calls them as `getString(data[i], accessor, i)`, so the second argument is the row's own
+  index — exactly what labelAt() wants, including its fallback for a row with no label.
+
+  UNGROUPED, two rows of the same name MERGE into one tile whose value is their sum: d3's `group`
+  collects them under one key, and `rootNode.sum()` runs before the library collapses the extra
+  level of nesting. GROUPED they do NOT — the same label under two different groups is two separate
+  depth-2 nodes — and Unovis keys its tile data-join `${d.data.key}-${d.depth}`, with no parent in
+  it, so those two collide in the join and one exits and re-enters on every render. Inert at
+  `:duration="0"`, which every container here sets, but it is why a label is worth keeping unique
+  within its group.
+*/
+const labelOf = (_row, i) => labelAt(rows.value, i);
+const layers = computed(() => (grouped.value ? [groupOf, labelOf] : [labelOf]));
+
+const value = (d) => d.value;
+const bySize = (a, b) => b.value - a.value;
+
+/*
+  ★★ EVERY NODE IS GIVEN A COLOUR, or the library invents one. A tile below the first level whose
+  accessor returns nothing falls through to `brighter(parent fill, …)` — an hcl lift that lands
+  outside the palette — and `enableLightnessVariance` (pinned off below) is a second helping of the
+  same idea. Answering for every node at every depth closes both paths.
+
+  ★★ AN INTERNAL TILE TAKES THE GROUND, NOT ITS GROUP'S COLOUR. The parent rect is painted UNDER its
+  children, and the padding between them is a hole in the children rather than in the parent — so a
+  group rect wearing the group colour shows that colour in every gap and its tiles fuse into one
+  blob. Painting it --deck-bg puts the slide back in the gaps, which is where the donut's segment
+  stroke and the bar's already are. It is also why the group name cannot be drawn on the group rect:
+  everything but a six-pixel band of it is covered by its own children.
+*/
+const tileColor = computed(() => {
+  // `groups`, `seriesList` and this map are one order — the index is the only thing tying a group
+  // to its colour, and shareState() resolved the colours in exactly this sequence.
+  const palette = new Map(groups.value.map((g, i) => [g, seriesList.value[i]?.color]));
+  const [first] = seriesList.value;
+  // Ungrouped, the top-level parent IS the tile and its key is the row's label, so the lookup misses
+  // and every tile lands on series 1 — the monochrome case, by construction.
+  return (d) => (d.children ? 'var(--deck-bg)' : (palette.get(d.topLevelParent?.data?.key) ?? first?.color));
+});
+
+const tileLabel = (node) => `${node.data.key} ${props.format(node.value)}`;
+
+/*
+  ★★ THE TILE LABEL TAKES --deck-on-accent, THE SYSTEM'S OWN INK-ON-A-FILL ROLE. A tile is a
+  saturated fill carrying text, which is the one question that role exists to answer, and it is the
+  house rule this chart was breaking: a fill at 500 and above takes white (or a 50/100 tint), and
+  only at 400 and below does a dark ink belong on it. The deck's series are Tailwind 600 steps on
+  light and 400 on dark, so the ink has to TURN OVER with the register — which is exactly what the
+  role does: white on light, #002a24 on dark.
+
+  The library's own choice fails this palette twice and is still overridden here:
+    1. It picks between --vis-treemap-label-text-color and …-light from `isColorDark(fill)`, a
+       NON-linearised brightness against a 0.55 threshold. The dark register's pink reads as dark at
+       0.541, takes the light ink, and lands at 2.76:1 — under the 3:1 large-text floor.
+    2. --vis-treemap-label-opacity ships at 0.8, which fades whichever ink wins by about a fifth, so
+       even the tiles it gets right fail. Pinned to 1.
+
+  MEASURED on all twelve tiles (six colours × both registers), against the 3:1 large-text floor:
+  light 3.28 / 3.20 / 4.09 / 6.46 / 4.64 / 4.87, dark 8.70 / 9.04 / 7.02 / 5.00 / 5.60 / 5.39.
+  Worst case 3.20 on the light amber.
+
+  ⚠ THIS WAS A RAW --neutral-950, and the note defending it said the ink could not follow the slide
+  "because --deck-series-* is bound to `.dark` alone, so a dark slide inside a light deck paints
+  light-register tiles". That stopped being true when deck.css grew its `.deck-dark` block: the
+  series re-point per SLIDE now, measured on the charts-on-dark slide, so the ground under this ink
+  does follow the register and the ink can follow it back. Black scored 3.07 at its worst (the light
+  indigo) — it was never the safer choice, only the mode-invariant one.
+*/
+const labelInk = {
+  '--vis-treemap-label-text-color': 'var(--deck-on-accent)',
+  '--vis-treemap-label-text-color-light': 'var(--deck-on-accent)',
+  '--vis-treemap-label-opacity': '1',
+};
+
+
+/*
+  The tile already prints its own name and value, so the tooltip adds the one thing the picture only
+  approximates: the share of the whole. Unovis hands the hierarchy node, whose `value` is the summed
+  leaf and whose `data.key` is the row's own label.
+*/
+const treemapTotal = computed(() => rows.value.reduce((a, r) => a + (r.value ?? 0), 0));
+const tip = (node) => {
+  const v = node?.value ?? 0;
+  const share = treemapTotal.value > 0 ? Math.round((v / treemapTotal.value) * 100) : 0;
+  return tipFrame(String(node?.data?.key ?? ''), [{ label: `${share}%`, value: props.format(v) }]);
+};
+</script>
+
+<template>
+  <ChartFrame
+    :series="seriesList"
+    :height="height"
+    :legend="legend && grouped"
+    :legend-position="legendPosition"
+    :message="message"
+    :style="labelInk"
+  >
+    <VisSingleContainer :data="rows" :height="height" :duration="0">
+      <!-- ★ THE THREE LABEL SIZES ARE NOT OPTIONAL. `enableTileLabelFontSizeVariation` ships TRUE in
+           @unovis/ts 1.6.7's TreemapDefaultConfig (its own docstring says false), and it reaches the
+           config as true whether or not it is passed — the Vue wrapper forwards only the props the
+           parent actually wrote, so an absent Boolean is absent rather than the `false` Vue would
+           otherwise coerce it to. While it is on, leaf labels take these three numbers by value and
+           never read --vis-treemap-label-font-size at all: a deck that sets nothing here draws its
+           tiles at the library's 8/12/22px. The ladder is three deck roles — body-sm, body, title
+           (36/48/60px), the same tier ChartFrame gives the axis. Plain numbers because the config
+           takes numbers; no token can reach them, so a retune of --type-deck-* leaves them behind.
+
+           minTileSizeForLabel is 360, not the library's 20: below that a tile cannot hold a label
+           and the trim does not save it.
+
+           ★★ IT WAS 120, AND THAT WAS TUNED AGAINST THE WRONG TYPE. The reasoning said "at 36px
+           type... a smaller tile carries about five characters" — but 36px is the SMALL rung of the
+           ladder three lines up, and a real tile draws at 48 or 60. Measured on six boroughs: at
+           60px "Lambeth 91k" is 353px wide, so 120 admits a tile that cannot hold any label at all.
+           Camden's tile came out 158px wide carrying a 231px label and Wandsworth's 218px carrying
+           307px — both cut, both with the ellipsis already spent, so the cut fell PAST the "…" and
+           was unmarked. scripts/deckAudit.ts caught it as 31% hidden, 73px off the right; nothing
+           about it looked wrong in a screenshot, because a trimmed label and an over-trimmed one
+           are the same shape.
+
+           ★★ AND THE PROP COMPARES min(width, height), NOT WIDTH — established by measurement, not
+           from the docs. Setting it to 360 dropped EVERY label including the 932px-wide tile, which
+           only makes sense against the short side. At 260 exactly the tiles whose smaller dimension
+           fell below it went bare (Islington 237, Lambeth 250, Camden 158, Wandsworth 218) while
+           580-tall tiles kept theirs. That is lucky rather than clever: a tile too narrow for a
+           horizontal label is narrow on its SHORT side, so the library's predicate guards the
+           dimension that actually matters here.
+
+           230 because "Camden…" measures 231px at the ladder's 48px rung — so the threshold is
+           "the tile must be at least as wide as the shortest label we would draw", which is a
+           number with a reason rather than one fitted to this dataset. Below it the tile stays a
+           bare rectangle, which is what this prop was always for; 120 was simply describing a font
+           size the component had stopped using.
+
+           tilePadding is 6 rather than 2 — twice the stacked bar's stroke, because a treemap's gaps
+           are its ONLY structure: no axis, no baseline, no rule anywhere else on the mark.
+
+           ★ TRIM, NOT WRAP, AND THE TRIM HAS TO BE ASKED FOR. Left at the library defaults a label
+           wider than its tile is CLIPPED at the tile edge — measured, "Wandsworth 65k" rendered as
+           "Wandsw" against a hard edge, which reads as a rendering fault rather than as a name that
+           did not fit. `trim` with `end` ellipsises instead, so a narrow tile still says which
+           borough it is and admits it ran out of room. Wrapping is the wrong half of that choice
+           here: a tile is only as tall as its share of the area, so a second line is exactly what
+           the smallest tiles have no room for. -->
+      <VisTreemap
+        :value="value"
+        :layers="layers"
+        :tile-color="tileColor"
+        :tile-label="tileLabel"
+        :tile-sort="bySize"
+        :tile-padding="6"
+        :tile-border-radius="8"
+        :label-offset-x="12"
+        :label-offset-y="12"
+        :enable-lightness-variance="false"
+        :enable-tile-label-font-size-variation="true"
+        :tile-label-small-font-size="36"
+        :tile-label-medium-font-size="48"
+        :tile-label-large-font-size="60"
+        :min-tile-size-for-label="230"
+        label-fit="trim"
+        label-trim-mode="end"
+      />
+      <VisTooltip v-bind="deckTooltip()" :triggers="{ [VisTreemapSelectors.tile]: tip }" />
+    </VisSingleContainer>
+  </ChartFrame>
+</template>