@humanforest/slidev-theme 0.1.0

package/components/Marquee.vue

@@ -0,0 +1,263 @@
+<script setup>
+/*
+  A band of words moving slowly across the slide — city names, values, partner names, the fleet's
+  vehicle types. It is the one piece of MOTION this deck owns as content rather than as a
+  transition, and it earns its place for a reason that only applies in a room: a static list of
+  twenty place names is a wall of small type, while the same twenty moving through a single band
+  are read one at a time, at full size, by an audience that is looking at the presenter anyway.
+
+  ★★ THE TRACK IS DUPLICATED, AND THAT IS THE WHOLE MECHANISM. One copy of the items translated
+  from 0% to -100% snaps back to a gap; two identical copies translated by exactly -50% of the pair
+  put copy B where copy A started, so the loop has no seam. `aria-hidden` on the second copy stops a
+  screen reader announcing every item twice.
+
+  ★ IT MUST BE LEGIBLE STANDING STILL, which is not a nicety — it is the state this thing is in
+  whenever it matters most:
+
+    · REDUCED MOTION. The engine's floor (@humanforest/tokens/motion/motion.css) sets
+      `animation-duration: 1ms` and `animation-iteration-count: 1` on everything, so the band lands
+      on its first frame and stops. That frame is the track at translate(0), i.e. the items in
+      order from the left — which is why the animation runs 0 -> -50% and never the reverse. A
+      marquee written to start mid-cycle would honour reduced motion by freezing on a half-word.
+    · EXPORT. `slidev export` drives a real browser and screenshots it, so a PDF would otherwise
+      catch the band wherever it happened to be. Slidev wraps the printed deck in `#print-container`
+      — the animation is switched off inside it, so an exported slide shows the same first frame.
+
+  No `background` or `variant`. A marquee is a band of text on the slide's own ground; a coloured strip
+  behind it is a Card's job, and a deck that wants one wraps this in one.
+*/
+import { computed, onMounted, ref } from 'vue';
+import { iconUrlOrFallback } from './iconUrl';
+import { assetUrl } from '../assetUrl.js';
+
+const props = defineProps({
+  /**
+   * The items, in order. Short — each one is read on its own as it passes. Either a plain string,
+   * or `{ label?, icon?, image? }`:
+   *   · `icon`  — a namespaced slug (`forest:bike`, `lucide:battery`), drawn as a CSS mask in the
+   *               deck's own ink, so it inherits the band's colour like the words beside it do.
+   *   · `image` — a URL, for artwork this repo does not own the vector of (a partner mark, a photo).
+   * A mark with no `label` is aria-hidden in BOTH copies rather than only the second: an icon with
+   * no words is decoration, and a screen reader announcing "image" eleven times is worse than
+   * silence.
+   */
+  items: {
+    type: Array,
+    required: true,
+    validator: (v) =>
+      Array.isArray(v) &&
+      v.length > 0 &&
+      v.every((i) =>
+        typeof i === 'string'
+          ? i.trim().length > 0
+          : !!i && typeof i === 'object' && [i.label, i.icon, i.image].some((f) => typeof f === 'string' && f.trim()),
+      ),
+  },
+  /** Seconds for one full cycle. Longer is slower; the default is tuned so a word stays readable
+   *  for about as long as it takes to say it. */
+  duration: { type: Number, default: 40 },
+  /** Run right-to-left instead. Two marquees at opposite settings is the classic pair — it reads as
+   *  a texture rather than as a list going somewhere. */
+  reverse: { type: Boolean, default: false },
+  /**
+   * Height of an `image` item, in px. 0 (the default) sizes it against the band's own type instead,
+   * which is right when a picture travels BESIDE a word and wrong when it travels alone: a band of
+   * pictures with no labels has no type to be in proportion to, and inherits a height set for a
+   * mark sitting next to a title. Icons are deliberately not covered — a mark is punctuation for
+   * the word beside it and stays locked to it.
+   */
+  imageHeight: { type: Number, default: 0 },
+});
+
+/*
+  ★★ THE BAND DOES NOT PAINT UNTIL ITS OWN METRICS ARE FINAL, and that is a layout fact rather than
+  a polish one. Every item is `inline-flex` inside a `width: max-content` track, so each width is
+  its own content's and a late arrival re-widths the whole row — and because the row is a row, the
+  deltas ACCUMULATE: item two moves by item one's change, item three by the sum of both. Measured on
+  the specimen's own three bands, with each cause isolated:
+
+    · the webfont swap   the eighth word of the city band lands 123px from where the fallback face
+                         put it (packages/fonts sets `font-display: swap`, so the fallback really is
+                         rendered first).
+    · a remote picture   2114px by the tenth item of the image band. An <img> whose height is CSS
+                         and whose src is a URL is a REAL height and a ZERO width until it lands, so
+                         the pictures shove each other along the track as they arrive one by one.
+
+  Hidden, never unmounted, and that is the whole reason this is `visibility` rather than `v-if` or
+  `display: none`: the band's HEIGHT is CSS in every case (a line box, or --marquee-image-h), never
+  content, so the space is already the right size and nothing below the band moves when it appears.
+  The track keeps animating while hidden, so it reveals mid-scroll rather than from a standing
+  start — the first frame contract above is about a STOPPED marquee, which is a different state.
+*/
+const band = ref(null);
+const ready = ref(false);
+onMounted(async () => {
+  const root = band.value;
+  /* The band's OWN face, asked for by name rather than waiting on document.fonts.ready alone:
+     `ready` resolves whenever font loading happens to be idle, which at mount can be before this
+     slide's faces have been requested at all. */
+  const item = root?.querySelector('.deck-marquee-item');
+  const settled = Promise.all([
+    item && document.fonts ? document.fonts.load(`1em ${getComputedStyle(item).fontFamily}`).catch(() => {}) : null,
+    ...[...(root?.querySelectorAll('img') ?? [])].map((img) => img.decode().catch(() => {})),
+  ]);
+  /* ★ THE HOLD HAS A CEILING, and it is the same 3s font-display: block would have used. Catching
+     every rejection covers a 404 picture and a face that fails to resolve; it does NOT cover a
+     request that simply never answers, which is the projector-on-hotel-wifi case — and a band that
+     stays blank for the length of the talk is a worse failure than the jump it was hiding. */
+  await Promise.race([settled, new Promise((resolve) => setTimeout(resolve, 3000))]);
+  ready.value = true;
+});
+
+/* One shape for the template to iterate, so the string form stays the shorthand it always was and
+   the template never branches on the item's TYPE — only on which parts it carries. */
+const normalised = computed(() =>
+  props.items.map((item) => {
+    const it = typeof item === 'string' ? { label: item } : item;
+    return {
+      label: typeof it.label === 'string' ? it.label : '',
+      image: typeof it.image === 'string' ? it.image : '',
+      // Resolved here, not in the template: iconUrlOrFallback falls back to the Forest mark, so a
+      // slug that never resolves is visibly the wrong glyph rather than an invisible gap in the
+      // band — which is what an unresolved mask leaves, with no console error and geometry the
+      // audit still measures as fine.
+      mask: it.icon ? `url("${iconUrlOrFallback(it.icon)}")` : '',
+    };
+  }),
+);
+</script>
+
+<template>
+  <div
+    ref="band"
+    class="deck-marquee"
+    :class="{ 'is-reverse': reverse, 'is-ready': ready }"
+    :style="{ '--marquee-duration': `${duration}s`, ...(imageHeight ? { '--marquee-image-h': `${imageHeight}px` } : {}) }"
+  >
+    <div class="deck-marquee-track">
+      <!-- Copy A: the real one, and the one a stopped marquee shows. -->
+      <span
+        v-for="(item, i) in normalised"
+        :key="`a-${i}`"
+        class="deck-marquee-item"
+        :aria-hidden="item.label ? undefined : 'true'"
+      >
+        <img v-if="item.image" class="deck-marquee-image" :src="assetUrl(item.image)" :alt="item.label" decoding="async" >
+        <span v-else-if="item.mask" class="deck-marquee-glyph" :style="{ maskImage: item.mask, webkitMaskImage: item.mask }" />
+        <span v-if="item.label" class="deck-marquee-label">{{ item.label }}</span>
+      </span>
+      <!-- Copy B: the seam filler. Hidden from assistive tech — same items, no second reading. -->
+      <span v-for="(item, i) in normalised" :key="`b-${i}`" class="deck-marquee-item" aria-hidden="true">
+        <img v-if="item.image" class="deck-marquee-image" :src="assetUrl(item.image)" alt="" decoding="async" >
+        <span v-else-if="item.mask" class="deck-marquee-glyph" :style="{ maskImage: item.mask, webkitMaskImage: item.mask }" />
+        <span v-if="item.label" class="deck-marquee-label">{{ item.label }}</span>
+      </span>
+    </div>
+  </div>
+</template>
+
+<style scoped>
+.deck-marquee {
+  overflow: hidden;
+  /* The band is a full-bleed device — it wants the slide's whole width, not the text measure. The
+     layout's own padding is escaped by the deck's inset so the words really do run off both edges,
+     which is what makes it read as a band rather than as a wide paragraph. */
+  width: 100%;
+  -webkit-mask-image: linear-gradient(to right, transparent, #000 6%, #000 94%, transparent);
+  mask-image: linear-gradient(to right, transparent, #000 6%, #000 94%, transparent);
+}
+
+.deck-marquee-track {
+  display: flex;
+  width: max-content;
+  align-items: center;
+  animation: deck-marquee-scroll var(--marquee-duration) linear infinite;
+}
+/* See the `ready` block in the script — the track holds its space and its animation, and paints
+   only once the face and the pictures that set its widths have both landed. */
+.deck-marquee:not(.is-ready) .deck-marquee-track {
+  visibility: hidden;
+}
+.is-reverse .deck-marquee-track {
+  animation-direction: reverse;
+}
+
+/* ★ -50%, NOT -100%. The track holds TWO copies of the list, so half its width is one full cycle,
+   and at -50% copy B sits exactly where copy A began. Animating `translate` rather than `transform`
+   deliberately: in this system `transform` is a separate property and naming the wrong one animates
+   nothing here while leaving the element still transformed elsewhere. */
+@keyframes deck-marquee-scroll {
+  from { translate: 0 0; }
+  to { translate: -50% 0; }
+}
+
+/* ★★ THE EXPORT FREEZE IS NOT HERE, AND IT CANNOT BE. It lives in styles/base.css, unscoped,
+   because Vue's scoped-CSS compiler DESTROYS the rule this component needs:
+
+       written    :global(#print-container) .deck-marquee-track { animation: none }
+       compiled   #print-container { animation: none }
+
+   The descendant is dropped and the declaration lands on the print container itself, which is a
+   no-op — so the band kept animating and the exported PDF caught it mid-word ("…thwark" where
+   "Southwark" should be). Verified by reading the compiled stylesheet out of dist/, after the PDF
+   showed it. A rule whose subject is an ANCESTOR outside this component belongs with the other
+   Slidev-integration rules, not in a scoped block that will silently rewrite it. */
+
+.deck-marquee-item {
+  /* inline-flex, so a mark and its word sit on one baseline-centred row. The dot below is a flex
+     child now rather than an inline box — which is why it is centred by `align-items` here and not
+     by its own `vertical-align`. */
+  display: inline-flex;
+  align-items: center;
+  gap: var(--deck-space-3);
+  font-family: var(--type-deck-title-family);
+  font-size: var(--type-deck-title-size);
+  font-weight: var(--type-deck-title-weight);
+  line-height: 1.1;
+  color: var(--deck-fg);
+  white-space: nowrap;
+  padding-inline: var(--deck-space-5);
+}
+
+/* A mark is sized against the TYPE it travels with, in `em`, not against a spacing rung: the band's
+   whole premise is that an item is read at title size as it passes, and a glyph pinned to a fixed
+   px would drift out of proportion the moment the type ramp moves. */
+.deck-marquee-glyph {
+  display: block;
+  flex: none;
+  width: 1.1em;
+  height: 1.1em;
+  /* currentColor, so a mark inherits the band's ink exactly as the words beside it do — the mask
+     technique's one real advantage over an <img> for artwork this repo owns the vector of. */
+  background-color: currentColor;
+  mask-repeat: no-repeat;
+  mask-position: center;
+  mask-size: contain;
+  -webkit-mask-repeat: no-repeat;
+  -webkit-mask-position: center;
+  -webkit-mask-size: contain;
+}
+
+/* An image cannot take the band's ink, so it keeps its own colour — correct for a partner mark,
+   which is exactly the case that cannot be a mask. Height-constrained and width-auto so logos of
+   different aspect ratios all sit on the same optical line. */
+.deck-marquee-image {
+  display: block;
+  flex: none;
+  height: var(--marquee-image-h, 1.4em);
+  width: auto;
+  object-fit: contain;
+}
+/* The separator is a dot in the accent, drawn between items rather than after them — an item is
+   the thing being read, the dot is only there so two words do not run together. */
+.deck-marquee-item::after {
+  content: '';
+  display: inline-block;
+  width: 0.28em;
+  height: 0.28em;
+  border-radius: var(--deck-radius-full);
+  background: var(--deck-accent);
+  vertical-align: 0.28em;
+  margin-inline-start: var(--deck-space-5);
+}
+</style>

package/components/NestedDonutChart.vue

@@ -0,0 +1,295 @@
+<script setup>
+/*
+  A nested donut sized for a room — one whole, split, and each part split again.
+
+  Reach for this over DonutChart.vue only when the second level is the POINT. A donut is already
+  read by area rather than angle, and a second ring asks the audience to compare areas inside areas;
+  if the inner split is incidental, it costs the outer comparison and buys nothing. Two rings is the
+  honest ceiling, and the geometry below says why: a third leaves no hole for the total.
+
+  THE OUTER RING IS THE CHART. It carries the five-colour palette and the legend, and inherits the
+  ceiling whole — chartData.ts's `shareState` is handed one row per top-level group, so six groups
+  draws the over-capacity message rather than a sixth colour that does not exist. The inner ring
+  carries no colours of its own: each segment is a TINT of its parent, so the family reads as a
+  family and the inner ring can hold as many slices as the arcs can fit.
+
+  ★ THE LIBRARY'S OWN TINT RAMP IS UNUSABLE AT ROOM SCALE, which is why `segmentColor` below is
+  passed rather than left to default. With no accessor, @unovis/ts inherits the parent's fill and
+  fades it with `scaleLinear().domain([-1, n]).range([1, 0])` (components/nested-donut/index.js),
+  so child i of n lands at alpha 1 − (i+1)/(n+1): five children give 0.83, 0.67, 0.5, 0.33, 0.17.
+  The last is the slide ground with a rumour of colour on it — a dashboard's idea of a subtle
+  distinction, and the same defect class as a 2px line on a projector. The mix here runs 85% of the
+  base down to 55% instead, and mixes toward `--deck-bg` rather than toward transparency, so the
+  ramp runs the same direction on a light slide and a dark one and stays a `var()` reference that
+  re-resolves on a theme flip. Both ends of that range are load-bearing — see `TINT_CEILING`.
+
+  ROW ORDER IS THE RAMP ORDER. Unovis leaves `sort` undefined and d3's pie keeps input order, so
+  the first sub-row of a group is the strongest tint. A lightness ramp reads as an ordering whether
+  or not one was meant, so order the rows by the quantity, or by something the audience already
+  knows the order of.
+
+  Real @unovis/vue mark, ChartFrame.vue for ceremony, chartData.ts for shaping.
+*/
+import { computed } from 'vue';
+import { VisSingleContainer, VisNestedDonut, VisTooltip, VisNestedDonutSelectors } from '@unovis/vue';
+import { deckTooltip, tipFrame } from './chartTip';
+import ChartFrame from './ChartFrame.vue';
+import { formatValue, isPlottable, scatterGroups, shareState, stateMessage } from './chartData';
+
+const props = defineProps({
+  /** Rows, one per leaf: `[{ <outer field>, <inner field>, value }]`. Flat — the rings are derived, not nested. A row that does not name EVERY ring cannot be drawn on all of them, so it is dropped from the chart, the legend and the centre total alike. */
+  data: { type: Array, required: true },
+  /** Field names, OUTERMOST FIRST — Unovis' default `inwards` direction puts the first layer on the outer radius. Omit and every string field of the first row becomes a ring, in declaration order. */
+  layers: { type: Array, default: null },
+  /** The figure in the hole. Omit and the groups' own total is used; pass an empty string for no centre at all. */
+  centralLabel: { type: String, default: null },
+  /** The word under that figure — what the total counts. One line: it does not wrap, and the hole is 208px wide at the default geometry, so a phrase runs out over the arcs. */
+  centralSubLabel: { type: String, 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 },
+  /** Thickness of ONE ring in px — DonutChart's `arcWidth` is the same measurement for its single ring. The hole is what is left: `min(width, height) / 2 − rings × ringWidth − (rings − 1) × 8`. At the default height with two rings that is a 208px hole, which holds a 60px figure over a 36px sub-label; three rings at the same height leaves 32px and needs a taller chart or a thinner ring. The library's own default (`radius × 0.75 / rings`, a 120px hole at two rings) does not. */
+  ringWidth: { type: Number, default: 64 },
+  /** Name the arcs in place. Off by default: Unovis measures a `perpendicular` label against the RING WIDTH and hides what overflows, so a 36px label inside a 64px ring is hidden on nearly every arc. `along` is the alignment that fits, and it rotates the text — worth switching on only for a handful of short names. */
+  segmentLabels: { type: Boolean, default: false },
+  /** Draw the group legend. It names the outer ring; nothing names the inner one but `segmentLabels`. */
+  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 default centre figure. Ignored when `centralLabel` is set. */
+  format: { type: Function, default: formatValue },
+  /** The sentence drawn when there is nothing to plot — including a set of groups that all sum to zero. */
+  empty: { type: String, default: 'No data' },
+});
+
+const layerKeys = computed(() => {
+  if (props.layers?.length) return props.layers;
+  const first = props.data?.[0] ?? {};
+  return Object.keys(first).filter((k) => typeof first[k] === 'string');
+});
+
+/*
+  ★★ A ROW MUST NAME EVERY RING, AND THIS IS THE ONLY LIST ANYTHING READS — the legend, the centre
+  figure and the data the mark is handed all come from here, which is the whole reason it exists.
+
+  Unovis keeps a segment only when it has a key AND its parent has a value
+  (`descendants().filter(d => d.parent?.value && d.data.key)`, components/nested-donut/index.js).
+  That drops an empty-keyed node but NOT its children. Passing the raw rows while filtering only the
+  totals therefore paints the one picture this chart must never paint: a row with no outer field is
+  absent from the legend and from the centre, its own outer arc is dropped for an empty key — and
+  its inner-ring child survives, inheriting the fill that dropped parent was handed. That fill comes
+  out of Unovis' own --vis-color ramp by index, because `getColor` falls back whenever
+  `segmentColor` cannot resolve a root it has never seen: replayed over six rows with one such
+  orphan, the leaf drew at `var(--vis-color2)` and 0.5 opacity — half-strength series 3, sitting
+  under a hole in the outer ring, for a group in neither the legend nor the total. The centre read
+  29 while the geometry divided 32. Filtering ONCE, here, is what keeps the three agreeing about
+  what the whole is.
+*/
+const rows = computed(() => {
+  const keys = layerKeys.value;
+  if (!keys.length) return [];
+  return (props.data ?? []).filter((row) => keys.every((k) => String(row?.[k] ?? '') !== ''));
+});
+
+/*
+  One row per top-level group, which is the shape `shareState` already decides on — so the ceiling,
+  the empty cases and the wording all come from chartData.ts rather than being restated here.
+  `scatterGroups` is the distinct-values-in-first-seen-order helper; it is named for the scatter
+  because that is what first needed it, but nothing in it is about points.
+*/
+const groupTotals = computed(() => {
+  const [outer] = layerKeys.value;
+  if (!outer) return [];
+  return scatterGroups(rows.value, outer).map((name) => ({
+    label: name,
+    value: rows.value.reduce(
+      (sum, row) => sum + (String(row[outer]) === name && isPlottable(row.value) ? row.value : 0),
+      0,
+    ),
+  }));
+});
+
+const state = computed(() => shareState(groupTotals.value));
+const message = computed(() => (state.value.kind === 'ready' ? null : stateMessage(state.value, props.empty)));
+
+/* The legend key is the group NAME rather than `shareState`'s own. That default is `String(value)`,
+   and the values handed to it here are group SUMS — two groups that happen to sum alike would carry
+   the same key through ChartFrame's `v-for`. Names cannot collide: `scatterGroups` returns each one
+   once. */
+const seriesList = computed(() =>
+  state.value.kind === 'ready' ? state.value.series.map((s) => ({ ...s, key: s.name })) : [],
+);
+
+const total = computed(() => groupTotals.value.reduce((sum, g) => sum + g.value, 0));
+const centre = computed(() => props.centralLabel ?? props.format(total.value));
+
+/** Group name → its palette colour, so an arc and its legend key are tied by NAME. Position would
+ *  also work today — d3's pie leaves unsorted children in data order — but a name cannot drift. */
+const tone = computed(() => new Map(seriesList.value.map((s) => [s.name, s.color])));
+
+const layerAccessors = computed(() => layerKeys.value.map((k) => (d) => String(d[k] ?? '')));
+
+/* ★ AN ACCESSOR, NOT THE SETTINGS OBJECT ITSELF. The @unovis/vue wrapper declares
+   `layerSettings: { type: [Function, null] }` (components/nested-donut/index.js), and Vue's
+   `assertType` reads `Function` as a simple type: an object fails `value instanceof Function`, and
+   the `null` arm wants `value === null`. A plain object matches neither, so every mount of every
+   nested-donut slide logs `Invalid prop: type check failed for prop "layerSettings"`. The value
+   does still reach the config — validation only warns — but a deck that cries wolf on its own
+   components is a deck whose console nobody reads. `getValue(layerId, layerSettings)` calls a
+   function accessor and returns anything else unchanged, so the two forms are identical downstream
+   and this costs one closure. */
+const layerSettings = computed(() => () => ({ width: props.ringWidth, labelAlignment: 'along' }));
+
+const value = (d) => (isPlottable(d.value) ? d.value : 0);
+
+/** The ends of the tint ramp, as a percentage of the parent's own palette colour.
+ *
+ *  The top is not 100. `color-mix(in oklab, <base> 100%, …)` IS the base, so a ramp starting there
+ *  hands the first — and largest — child of every group its parent's exact fill: two rings of one
+ *  hue meeting edge to edge, which is the reading the 8px of layer padding is there to break, and
+ *  more than 8px on a 1920px canvas can break on its own.
+ *
+ *  The bottom is not lower because below roughly half, a mid-tone palette colour mixed into the
+ *  ground stops reading as that colour at all. */
+const TINT_CEILING = 85;
+const TINT_FLOOR = 55;
+
+/* Every node carries `data.root` — the key of its top-level ancestor, filled in by Unovis' own
+   breadth-first pass — so the base colour is one lookup at any depth rather than a parent walk. */
+function segmentColor(segment) {
+  const base = tone.value.get(segment.data.root);
+  if (!base) return null;
+  if (segment.depth === 1) return base;
+  const siblings = segment.parent?.children ?? [];
+  const step = siblings.length > 1 ? siblings.indexOf(segment) / (siblings.length - 1) : 0;
+  const mix = Math.round(TINT_CEILING - step * (TINT_CEILING - TINT_FLOOR));
+  return `color-mix(in oklab, ${base} ${mix}%, var(--deck-bg))`;
+}
+
+/* Passed rather than left to the library's brightness test, which cannot run here: it parses the
+   fill with d3-color, and d3-color returns null for a `color-mix()` string, so every tinted arc
+   would score brightness 0 and take the light-on-dark ink whatever it is actually sitting on.
+   The rule is simpler than the test anyway — depth 1 is the palette colour at full strength, so the
+   ground is the right ink for it; every depth-2 arc is that colour moved TOWARDS the ground, 85% of
+   it at the very most, so the ground is the wrong ink for those. The two cases cannot meet in the
+   middle precisely because the ramp starts below 100%. */
+const segmentLabelColor = (segment) => (segment.depth === 1 ? 'var(--deck-bg)' : 'var(--deck-fg)');
+
+/*
+  A nested donut's segment carries its own ring, so the tooltip names the value and leaves the
+  hierarchy to the drawing — which ring a segment sits in is the one thing the picture already says
+  unambiguously.
+*/
+const tip = (d) => tipFrame(String(d?.data?.key ?? d?.key ?? d?.data?.label ?? ''), [
+  { label: 'Value', value: props.format(d?.value ?? 0) },
+]);
+</script>
+
+<template>
+  <ChartFrame
+    class="deck-nested-donut"
+    :series="seriesList"
+    :height="height"
+    :legend="legend"
+    :legend-position="legendPosition"
+    :message="message"
+  >
+    <VisSingleContainer :data="rows" :height="height" :duration="0">
+      <!-- 8px between rings, on top of the 4px ground stroke each arc already carries: the stroke
+           separates neighbours WITHIN a ring, but two rings of the same hue meeting edge to edge
+           read as one thick arc, which is the one relationship this chart exists to show.
+
+           ★ `central-sub-label-wrap` OFF, because the library wraps that text against the wrong
+           radius here. `_render` calls `wrapSVGText(this.centralSubLabel, layers[0]._innerRadius *
+           1.9)`, and `_getLayerSettings` REVERSES the layer array for the `inwards` direction — the
+           default, and the one that puts the first layer on the outside — so `layers[0]` is the
+           outermost ring rather than the hole. At the documented geometry (height 480, ringWidth 64,
+           layerPadding 8) that is 176 × 1.9 = 334px of wrap width inside a 208px hole: a sub-label
+           long enough to wrap breaks out over the arcs instead of staying in the middle. VisDonut
+           has no such problem — its `layers[0]` inner radius IS the hole. Off, a sub-label that does
+           not fit overruns in one line the author can see and shorten. -->
+      <VisNestedDonut
+        :value="value"
+        :layers="layerAccessors"
+        :layer-settings="layerSettings"
+        :layer-padding="8"
+        :segment-color="segmentColor"
+        :segment-label-color="segmentLabelColor"
+        :show-segment-labels="segmentLabels"
+        :corner-radius="8"
+        :central-label="centre"
+        :central-sub-label="centralSubLabel ?? undefined"
+        :central-sub-label-wrap="false"
+      />
+      <VisTooltip v-bind="deckTooltip()" :triggers="{ [VisNestedDonutSelectors.segment]: tip }" />
+    </VisSingleContainer>
+  </ChartFrame>
+</template>
+
+<style scoped>
+/*
+  The nested donut has its OWN variable namespace, and it is not the donut's: `--vis-nested-donut-*`
+  against `--vis-donut-*`, with `sublabel` where the donut writes `sub-label`. None of ChartFrame's
+  donut block reaches this mark, so the type ramp and the arc separator are restated here — same
+  values, same reasoning, different names.
+
+  Declared on the frame's own element rather than `:root`, for both of the reasons ChartFrame
+  records: Unovis injects its `:root` defaults at runtime and would win on order, and a custom
+  property computes where it is declared, so a reference resolved here flips with a `deck-dark`
+  slide and one resolved at `:root` would not. The `--vis-dark-nested-donut-*` twins are left alone
+  for the same reason — the deck's tokens already carry the dark values.
+
+  Left at the library default: `--vis-nested-donut-background-color`, which only paints under
+  `showBackground`, and that stays off.
+*/
+.deck-nested-donut {
+  /* The arc separator is the SLIDE GROUND, so segments read as separated rather than outlined.
+     The library's default is its own background lilac at 1px — an off-brand hairline. */
+  --vis-nested-donut-segment-stroke-color: var(--deck-bg);
+  --vis-nested-donut-segment-stroke-width: 4px;
+
+  /* The centre. Title tier for the figure, small body for what it counts — the same pair
+     ChartFrame sets for the donut, and the pair its offset correction below is measured against. */
+  --vis-nested-donut-central-label-font-size: var(--type-deck-title-size);
+  --vis-nested-donut-central-label-font-weight: var(--type-deck-title-weight);
+  --vis-nested-donut-central-label-text-color: var(--deck-fg);
+  --vis-nested-donut-central-sublabel-font-size: var(--type-deck-body-sm-size);
+  --vis-nested-donut-central-sublabel-font-weight: var(--type-deck-body-sm-weight);
+  --vis-nested-donut-central-sublabel-text-color: var(--deck-fg-muted);
+
+  /* Caption tier for an arc label. This is a step DOWN from the library's `1em`, which inherits the
+     slide's body (3rem / 48px) and fits no arc at all — but it is not a step below the axis ticks:
+     caption, body-sm and label all resolve to 2.25rem / 36px on this deck (packages/tokens/type/
+     type.deck.css), and the only smaller role in the ramp is overline, which is an eyebrow rather
+     than a label. 36px is why `segmentLabels` is off by default: it fits the long arcs and nothing
+     else. */
+  --vis-nested-donut-segment-label-font-size: var(--type-deck-caption-size);
+}
+
+/*
+  ★★ CHARTFRAME'S CENTRE CORRECTION ONLY HALF-REACHES THIS MARK, and half is worse than none.
+
+  Both donuts place the pair at dy ∓0.55em of their OWN unequal font sizes, so both hang above the
+  ring's true centre and both want the same downward nudge. ChartFrame applies it with
+  `[class*='-central-label']`, which works there because @unovis/ts's donut labels BOTH texts
+  `central-label` (components/donut/style.js). The nested donut labels its second text
+  `central-sub-label` — and `-central-sub-label` does not contain the substring `-central-label`.
+  Unpatched, the figure moves 16.8px and the sub-label stays, splitting a pair the correction exists
+  to keep together.
+
+  Same expression as ChartFrame's, deliberately: it is one measurement, not two, and writing it
+  again as a literal would let the halves drift apart the moment either type role is retuned.
+*/
+:deep([class*='-central-sub-label']) {
+  translate: 0 calc((var(--type-deck-title-size) - var(--type-deck-body-sm-size)) * 0.7);
+}
+</style>

package/components/Placeholder.vue

@@ -0,0 +1,88 @@
+<script setup>
+/*
+  "An image goes here." Deliberately obvious rather than decorative — a placeholder that looks like
+  a real image invites someone to ship it.
+
+  Drawn from --deck-* roles: no network, no raster asset, no licensing question, and identical
+  dimensions on every run. That last property is what keeps scripts/deckAudit.ts meaningful — a real
+  photo's intrinsic size varies and would make overflow results non-repeatable.
+
+  ★★ HATCHING, NOT AN ICON, AND THE REASON IS WHAT THE THING IS FOR. This drew a small picture-frame
+  glyph — a rect, a circle and a mountain path, hand-drawn here rather than taken from any icon set,
+  which made it the only hand-authored pictogram in the theme and a fourth place to maintain one.
+  Worse, it read as CONTENT: a tidy centred icon on a clean fill is what an empty state looks like,
+  and an empty state is a thing that is finished. Diagonal hatching cannot be mistaken for finished
+  work — it is the universal "nothing here yet" of a drawing, and it survives being glanced at from
+  the back of a room, which is the only viewing condition this deck has.
+
+  The stripes are a repeating gradient rather than an SVG <pattern> because a gradient scales with
+  the box for free: the same 12px pitch holds at every ratio and every size without a viewBox to
+  keep in sync.
+*/
+const RATIOS = { '16:9': 16 / 9, '4:3': 4 / 3, '1:1': 1, '3:4': 3 / 4 };
+
+defineProps({
+  /** Aspect ratio of the frame. Matches how the layouts reserve space for real media. */
+  ratio: {
+    type: String,
+    default: '16:9',
+    // Vue hoists defineProps() out of setup() at build time, so this validator cannot close over
+    // the RATIOS const above (that only compiles in dev, not in a production build) — it repeats
+    // the same four keys inline instead.
+    validator: (r) => ['16:9', '4:3', '1:1', '3:4'].includes(r),
+  },
+  /** Short caption naming what belongs here, e.g. "Rider on a Forest bike". */
+  label: { type: String, default: 'Image' },
+});
+</script>
+
+<template>
+  <div class="deck-placeholder" :style="{ aspectRatio: String(RATIOS[ratio] ?? 16 / 9) }" role="img" :aria-label="`Placeholder: ${label}`">
+    <span class="deck-placeholder-label">{{ label }}</span>
+  </div>
+</template>
+
+<style scoped>
+.deck-placeholder {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 100%;
+  /*
+    The hatch sits on the subtle fill rather than replacing it, so the box still reads as a surface
+    when the stripes are too fine to resolve at a distance. `--deck-border` (not -strong) keeps the
+    stripes quieter than the dashed edge that frames them: the border says "this is a box", the
+    hatch says "and it is empty", and the border has to win that hierarchy or the panel turns into
+    texture with no shape.
+  */
+  background-color: var(--deck-surface);
+  background-image: repeating-linear-gradient(
+    -45deg,
+    var(--deck-border) 0,
+    var(--deck-border) 1.5px,
+    transparent 1.5px,
+    transparent 12px
+  );
+  /* 4px, not 2. CSS derives the dash LENGTH from the border width, so a thin dashed border is also
+     a finely dashed one — at 2px on a 1920 canvas the dashes fall under a pixel once the slide is
+     scaled to any real screen and the edge reads as a plain hairline. The dashes have to survive
+     the room, same as the hatch. */
+  border: 4px dashed var(--deck-border-strong);
+  border-radius: var(--deck-radius-card);
+  color: var(--deck-fg-muted);
+}
+.deck-placeholder-label {
+  /*
+    The label needs its own ground: set straight onto the hatch it is read through the stripes, and
+    at caption size the 1.5px lines cross the letterforms. The chip is the fill without the hatch,
+    which is why it uses the same token rather than a new one.
+  */
+  padding: var(--deck-space-1) var(--deck-space-2);
+  background: var(--deck-surface);
+  border-radius: var(--deck-radius-nested);
+  font-size: var(--type-deck-caption-size);
+  font-family: var(--font-sans);
+  text-align: center;
+  max-width: 20em;
+}
+</style>