@humanforest/slidev-theme 0.1.0

package/assetUrl.js

@@ -0,0 +1,38 @@
+/*
+  A public-asset URL, resolved against the deck's own base path.
+
+  ★★ A DECK BUILT WITH `--base` REWRITES ITS HTML AND NOT ITS PROPS. Vite prefixes `/foo` wherever it
+  can see one at build time — `index.html`, CSS `url()`, an `<img src="/x">` written literally in a
+  template — and it CANNOT see one that arrives as a runtime value. `image: '/avatars/olivia.jpg'`
+  in a slide's props block is a string the component receives and hands to `:src`, so it stays
+  `/avatars/olivia.jpg` while every asset around it moved to `/design-system/avatars/olivia.jpg`.
+
+  Measured on this deck built with `--base /design-system/`: index.html asked for
+  `/design-system/assets/index-*.js` while eight avatars and the partner mark still asked for `/…`.
+  Every one 404s, and a missing image renders as a blank box rather than an error — the same silent
+  class the alt-text rule exists for. Nothing in the build reports it.
+
+  ⚠ ROOT-RELATIVE ONLY. A protocol URL (the photography on assets.forest.bike), a data: URI, and a
+  relative path are all returned untouched — the first two are already absolute and the third is
+  resolved by the browser against the page, which is what a caller writing one wants.
+
+  ⚠ AND IT IS IDEMPOTENT, because it has to be: `import.meta.env.BASE_URL` is `/` in dev, so a
+  helper that blindly concatenated would double the slash on every local asset in the dev server.
+*/
+const base = () => {
+  // `import.meta.env` exists under Vite (dev and build); the fallback keeps this callable from a
+  // plain Node context — a test, or a generator that imports the theme for its values.
+  const b = import.meta.env?.BASE_URL;
+  return typeof b === 'string' && b ? b : '/';
+};
+
+export function assetUrl(url) {
+  if (typeof url !== 'string' || !url) return url;
+  // Not root-relative: absolute, protocol-relative, a data/blob URI, or relative to the page.
+  if (!url.startsWith('/') || url.startsWith('//')) return url;
+  const b = base();
+  if (b === '/') return url;
+  // Already carries the base — a caller that resolved it themselves, or a second pass.
+  if (url.startsWith(b)) return url;
+  return b.replace(/\/$/, '') + url;
+}

package/components/Alert.vue

@@ -0,0 +1,209 @@
+<script setup>
+/*
+  A status panel — the deck's answer to Nuxt UI's UAlert: a block that names a state, with an icon,
+  a title and optional detail, at one of two VOLUMES.
+
+  ★ TWO VARIANTS, AND THE CHOICE IS ABOUT WHAT ELSE IS ON THE SLIDE. `subtle` is a tint you put
+  BESIDE other content — a note in a column, one of a row of four, an aside under a chart. `solid`
+  is the same five states when the alert IS the slide: a saturated block in the family's own 700,
+  the way a Chip is, for the one thing an audience must not read past. A row of solid alerts would
+  be five slabs of colour shouting at each other, which is why the default is the quiet one.
+
+  AN ALERT IS THE STATEMENT, NOT AN ASIDE. It carries a state and its colour IS the message, so it
+  is the loudest object on its slide by construction — it cannot comment on a neighbour, and it is
+  not the shape to reach for when something merely needs a remark beside it.
+
+  ⚠ This used to be written as "NOT a Callout", against a speech-bubble component that has since
+  been retired: the deck kept both, an aside and a statement, and only ever needed the statement.
+  The distinction is worth keeping without the comparison, because the pull is toward using an alert
+  for any set-apart text, which spends a status colour on something that has no status.
+
+  ★ THE STATUS IS A NAME, NEVER A COLOUR, and the four names are not this component's invention.
+  They are the alias contract the web product already publishes (forest-preset.ts): success->forest,
+  error->maple, info->river, warning->amber. A deck that picked its own families would be a second
+  opinion about what "warning" looks like, free to drift from the product the first time either
+  moved. Each name resolves to a SET of four generated tokens — fill, ink, icon, edge — all four
+  built off that name's semantic role in scripts/deck.ts and recomputed by the static suite.
+
+  ★★ `subtle` IS UAlert'S OWN CONSTRUCTION, WEAKNESS INCLUDED. Stock draws it as
+  `bg-<color>/10 text-<color> ring ring-inset ring-<color>/25` — one semantic role at two alpha
+  stops, with no `dark:` class anywhere in its theme; it changes register because the role does.
+  This component used to hold a deck-local pin instead (fill-100 under ink-900, an opaque
+  family-500 edge), which measured far better — 9.64 to 10.35 for the ink against 2.76 to 4.05 now —
+  and was a second opinion about the same five words. A specimen that draws a more legible alert
+  than the product ships is the more expensive kind of wrong.
+
+  What it costs is recorded in scripts/deck.ts and on the specimen slides: two of the five states
+  sit under the 3:1 this component's 36px body is held to on the light register, and the edge falls
+  from 3.06-4.55:1 to 1.29-1.36. The dark register clears its floor at 4.81-5.82.
+
+  Only the edge's WIDTH stays the deck's own — see the border rule below.
+*/
+import { computed } from 'vue';
+
+const STATUSES = ['info', 'success', 'warning', 'danger', 'neutral'];
+
+// The default lamp per status. A caller can override with `icon`, but never has to choose one to
+// get a correct alert — the status already implies which glyph belongs to it.
+const STATUS_ICON = {
+  info: 'i-lucide-info',
+  success: 'i-lucide-circle-check',
+  warning: 'i-lucide-triangle-alert',
+  danger: 'i-lucide-octagon-alert',
+  neutral: 'i-lucide-message-square',
+};
+
+const props = defineProps({
+  /** Which state this panel names. A NAME, never a colour — each resolves to a measured fill/ink/icon/edge set. */
+  status: {
+    type: String,
+    default: 'info',
+    // Inlined rather than closed over STATUSES above: defineProps() is hoisted out of setup() at
+    // build time, the same trap Grid and Placeholder both document.
+    validator: (s) => ['info', 'success', 'warning', 'danger', 'neutral'].includes(s),
+  },
+  /** 'subtle' — a tint beside other content · 'solid' — the saturated block, when the alert IS the
+   *  slide. */
+  variant: {
+    type: String,
+    default: 'subtle',
+    // Inlined for the same reason `status` is: defineProps() is hoisted out of setup() at build
+    // time, so a module const closed over here would be undefined by the time it runs.
+    validator: (v) => ['subtle', 'solid'].includes(v),
+  },
+  /** The headline. Optional — an alert with only body copy is still a valid alert. */
+  title: { type: String, default: '' },
+  /** Overrides the status's own lamp — a UnoCSS icon class, not a slug, the same vocabulary the chrome uses. `:icon="false"` draws no lamp at all. */
+  icon: { type: [String, Boolean], default: '' },
+});
+
+// Clamped in the CLASS, not only in the validator: a validator is stripped from a production build,
+// and an unknown status would mint a class with no rule — a panel with no fill, no ink and no edge,
+// which is a blank rectangle rather than a visible error.
+const safeStatus = computed(() => (STATUSES.includes(props.status) ? props.status : STATUSES[0]));
+// Clamped in the class for the same reason the status is — a validator is stripped from a
+// production build, and an unknown variant would leave the panel with neither treatment.
+const safeVariant = computed(() => (props.variant === 'solid' ? 'solid' : 'subtle'));
+const statusClass = computed(() => [`is-${safeStatus.value}`, `is-${safeVariant.value}`]);
+/*
+  ★ AN ALERT CAN BE ICONLESS: `:icon="false"`.
+
+  The lamp states the status twice — once as a hue, once as a shape — and the second telling earns
+  its default because hue alone fails a colour-blind reader. But it is not always wanted: a row of
+  alerts read as a legend, or one whose title already carries the word, is quieter without it.
+
+  ONE PROP, not two. A `no-icon` boolean beside `icon` could contradict it
+  (`icon="i-lucide-check" no-icon`) and there is no sensible answer to that; one prop cannot
+  disagree with itself.
+
+  And a BOOLEAN false rather than a reserved string. `icon="none"` also works mechanically — "none"
+  is not a valid UnoCSS class, so nothing legitimate is shadowed — but it reads as a value the
+  component might look up, and the author has to know it is special. `false` says off in the
+  language Vue already has, next to the `:cols="2"` and `:height="600"` bindings a deck writes
+  everywhere else.
+*/
+const showIcon = computed(() => props.icon !== false);
+const iconClass = computed(() =>
+  typeof props.icon === 'string' && props.icon ? props.icon : STATUS_ICON[safeStatus.value],
+);
+</script>
+
+<template>
+  <div class="deck-alert" :class="[statusClass, { 'deck-own-ground': variant === 'solid' }]" role="note">
+    <div v-if="showIcon" class="deck-alert-icon" :class="iconClass" aria-hidden="true" />
+    <div class="deck-alert-text">
+      <p v-if="title" class="deck-alert-title">{{ title }}</p>
+      <div class="deck-alert-body"><slot /></div>
+    </div>
+  </div>
+</template>
+
+<style scoped>
+/*
+  One custom property per slot, set by the status class and read by everything below. Without it the
+  icon and the edge become two more places to remember
+  which state is in play, and a panel whose lamp disagrees with its fill is the exact defect the
+  measured token sets exist to make unexpressible.
+*/
+.deck-alert {
+  --alert-fill: var(--deck-status-info-fill);
+  --alert-ink: var(--deck-status-info-ink);
+  --alert-icon: var(--deck-status-info-icon);
+  --alert-edge: var(--deck-status-info-edge);
+
+  display: flex;
+  gap: var(--deck-space-3);
+  align-items: flex-start;
+  background: var(--alert-fill);
+  color: var(--alert-ink);
+  /* 4px, twice the callout's, and the extra 2 is paying for the edge's own colour. It used to be an
+     opaque family-500 reading 3.06 - 4.55:1 against the cream; following the product's
+     `ring-<color>/25` drops the same hue to 1.29 - 1.36, which no width recovers. What width does
+     buy is that the outline reads as drawn rather than as an artefact of the fill — at presenting
+     size a hairline is most of a millimetre, and a hairline this quiet is nothing at all. */
+  border: calc(var(--deck-space-1) / 2) solid var(--alert-edge);
+  border-radius: var(--deck-radius-card);
+  padding: var(--deck-card-pad);
+}
+.deck-alert.is-success { --alert-fill: var(--deck-status-success-fill); --alert-ink: var(--deck-status-success-ink); --alert-icon: var(--deck-status-success-icon); --alert-edge: var(--deck-status-success-edge); }
+.deck-alert.is-warning { --alert-fill: var(--deck-status-warning-fill); --alert-ink: var(--deck-status-warning-ink); --alert-icon: var(--deck-status-warning-icon); --alert-edge: var(--deck-status-warning-edge); }
+.deck-alert.is-danger  { --alert-fill: var(--deck-status-danger-fill);  --alert-ink: var(--deck-status-danger-ink);  --alert-icon: var(--deck-status-danger-icon);  --alert-edge: var(--deck-status-danger-edge); }
+.deck-alert.is-neutral { --alert-fill: var(--deck-status-neutral-fill); --alert-ink: var(--deck-status-neutral-ink); --alert-icon: var(--deck-status-neutral-icon); --alert-edge: var(--deck-status-neutral-edge); }
+
+/* ── SOLID: the same five states, said loudly ──────────────────────────────────────────────────
+   Only the four custom properties change — every rule below reads them, so the layout, the lamp's
+   optical centring and the type all stay exactly as they are. The fill is the family's own 700 (the
+   level the subtle panel's LAMP uses, so the two volumes are one family rather than two palettes)
+   and the ink is the paired white the engine emits beside it, measured 6.45-10.41:1 across the five.
+
+   ★ THE LAMP AND THE EDGE JOIN THE INK HERE. On the subtle panel they are separate roles because
+   they sit on a pale tint and each needs its own measurement; on a saturated block there is one
+   ground, so a lamp in family-700 would be invisible on family-700 and an edge in family-500 would
+   read as a pale halo. One ground, one ink. */
+.deck-alert.is-solid {
+  --alert-fill: var(--deck-status-info-solid);
+  --alert-ink: var(--deck-on-status-info);
+  --alert-icon: var(--deck-on-status-info);
+  --alert-edge: var(--deck-status-info-solid);
+}
+.deck-alert.is-solid.is-success { --alert-fill: var(--deck-status-success-solid); --alert-ink: var(--deck-on-status-success); --alert-icon: var(--deck-on-status-success); --alert-edge: var(--deck-status-success-solid); }
+.deck-alert.is-solid.is-warning { --alert-fill: var(--deck-status-warning-solid); --alert-ink: var(--deck-on-status-warning); --alert-icon: var(--deck-on-status-warning); --alert-edge: var(--deck-status-warning-solid); }
+.deck-alert.is-solid.is-danger  { --alert-fill: var(--deck-status-danger-solid);  --alert-ink: var(--deck-on-status-danger);  --alert-icon: var(--deck-on-status-danger);  --alert-edge: var(--deck-status-danger-solid); }
+.deck-alert.is-solid.is-neutral { --alert-fill: var(--deck-status-neutral-solid); --alert-ink: var(--deck-on-status-neutral); --alert-icon: var(--deck-on-status-neutral); --alert-edge: var(--deck-status-neutral-solid); }
+
+/* A solid panel paints its own saturated ground, so anything markdown puts inside it needs the same
+   protection a Card on a named background carries — base.css keys those rules off `.deck-own-ground`, and the
+   class is applied from the template rather than duplicated here. */
+
+/* The lamp is the ONE thing not in the ink colour: it is the state stated twice, once as a shape
+   and once as a hue, so it takes the icon role (5.45-5.72 on the fill) rather than the body ink. */
+.deck-alert-icon {
+  flex: none;
+  width: var(--deck-space-5);
+  height: var(--deck-space-5);
+  color: var(--alert-icon);
+  background-color: currentColor;
+  /*
+    ★ CENTRED ON THE TITLE'S FIRST LINE, not flush with the top of its box. `align-items:
+    flex-start` puts both at the same y, but the glyph is --deck-space-5 (40px) and the title's line
+    box is 1lh (54px at the dense tier) — MEASURED, the icon's optical centre sat 7px above the
+    title's and read as slightly lifted. Half the difference puts them on one line.
+
+    `1lh` rather than a repeated 54: the line box is whatever the tier in play makes it, and a
+    hard-coded half-difference would be wrong the moment an alert appears in a column that changes
+    the tier. Clamped at 0 so a title bigger than the glyph never pulls the icon upward.
+  */
+  margin-block-start: max(0px, calc((1lh - var(--deck-space-5)) / 2));
+}
+.deck-alert-text { min-width: 0; }
+.deck-alert-title {
+  margin: 0;
+  font-weight: var(--type-deck-body-weight-strong, 700);
+  max-width: none;
+}
+.deck-alert-body :deep(p) { margin: 0; max-width: none; }
+.deck-alert-body :deep(p + p) { margin-top: var(--deck-space-2); }
+.deck-alert-title + .deck-alert-body { margin-top: var(--deck-space-1); }
+/* Two columns halve the measure, so an alert in one takes the dense tier with everything else. */
+.deck-alert, .deck-alert-body { font-size: var(--type-deck-body-sm-size); line-height: var(--type-deck-body-sm-line-height); }
+</style>

package/components/AreaBox.vue

@@ -0,0 +1,152 @@
+<script setup>
+/*
+  A NAMED REGION OF A LAYOUT, DRAWN AS ITSELF.
+
+  This exists so a layout can be shown as its AREAS rather than as its content: drop one of these
+  into every slot a layout exposes and the slide stops being a page about e-bikes and becomes a
+  diagram of the frame it is sitting in.
+
+  ★★ IT IS NOT A PICTURE OF A LAYOUT — IT IS THE LAYOUT. The obvious way to draw this section was a
+  miniature: an SVG of a slide with rectangles in it, sized from the ratio. That would have been a
+  second copy of the truth, and the first time a grid-template changed the diagram would go on
+  confidently showing the old one. Here the boxes are placed by the real layout, in the real slots,
+  at the real canvas size — split's own grid decides where the figure column starts, not this file.
+  A layout that is implemented wrongly draws itself wrongly, which is the entire point.
+
+  Deliberately NOT the schematic ruler in global-top.vue. That instrument answers "how far is this
+  from the edge" and speaks in dashed and dotted frames over live content. This one answers "what
+  region am I looking at, and how much of the slide does it get", and speaks in filled, named
+  blocks. Same family, different question — so the ruler keeps dashes and dots, and this keeps
+  fills and labels, and neither is mistaken for the other when both are on screen.
+*/
+const TONES = ['content', 'figure'];
+
+defineProps({
+  /** The area's name, as the layout itself calls it — 'content', 'band', 'aside'. */
+  name: { type: String, required: true },
+  /**
+   * What the layout gives this area: a track share ('3fr'), a slot name, a rule of thumb.
+   * Optional — a region whose size is not the point does not need a number under it.
+   */
+  note: { type: String, default: '' },
+  /**
+   * Which kind of region this is. TWO, because a frame only makes two kinds of promise: the column
+   * that holds the reading, and the cell that holds a figure. A third — 'chrome', for a header or
+   * footer — was written and removed: the deck's furniture is drawn by slide-top/slide-bottom for
+   * every slide alike, so it is not one of the layout's areas and drawing it as one says the frame
+   * owns something it does not.
+   */
+  tone: {
+    type: String,
+    default: 'content',
+    // Repeated inline: defineProps() is hoisted out of setup() at build time, so this validator
+    // cannot close over TONES above (that compiles in dev and not in a production build).
+    validator: (t) => ['content', 'figure'].includes(t),
+  },
+  /**
+   * Where the label sits inside the region. 'center' is right for a region that stands alone;
+   * 'top' is for a region something else is drawn ON TOP OF — bleed's media fills the whole frame
+   * and the content sits over it, so two centred labels land in the same place and overprint each
+   * other. They are siblings in the DOM (the media is absolutely positioned), so no CSS selector
+   * can spot the overlap and move one out of the way on its own.
+   */
+  align: {
+    type: String,
+    default: 'center',
+    validator: (a) => ['center', 'top'].includes(a),
+  },
+});
+</script>
+
+<template>
+  <div class="area-box" :class="[`is-${tone}`, `is-${align}`]">
+    <span class="area-box-name">{{ name }}</span>
+    <span v-if="note" class="area-box-note">{{ note }}</span>
+  </div>
+</template>
+
+<style scoped>
+.area-box {
+  /*
+    Fills whatever cell it is handed, and refuses to be the reason a track is a given size:
+    min-height/min-width 0 so a grid row can shrink it rather than overflow the slide. A diagram
+    that changed the layout it is diagramming would be worse than no diagram.
+  */
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: var(--deck-space-1);
+  width: 100%;
+  /*
+    ★ flex: 1 AND align-self: stretch, NOT height: 100%. These land in two different kinds of parent
+    — a grid cell (split's figure column) and a flex column (the default slot, under a heading) —
+    and `height: 100%` is only correct in the first. In the second it resolves against the WHOLE
+    column while a heading is already occupying part of it, so the box overran its own slot and sat
+    on top of the footer. Measured on the first draft of this section: the content area overlapped
+    the footer area by about a third of its height, which read as a layout defect and was mine.
+    So both are set, and the flex BASIS is 0 rather than auto — that is the part that makes them
+    coexist. In a flex parent, basis 0 + grow fills exactly what is left and the height is ignored;
+    in a block parent (split-content is `display: block`) the flex properties are inert and the
+    height fills the column. Measured: with `flex: 1 1 auto` alone the box came out 75px inside a
+    266px column, because a block parent does not read flex at all.
+
+    ★★ AND `height: 100%` CAME BACK OUT, BECAUSE THAT LAST SENTENCE IS ONLY TRUE OF AN ONLY CHILD.
+
+    A percentage height resolves against the parent's whole content box, not against what is left of
+    it. In a block parent with a SIBLING above, the box therefore starts below the sibling and still
+    claims the full height — overflowing by exactly the sibling's height. Measured on the cover's own
+    area specimen: `.cover-content` is 195 tall and block, `.cover-rule` plus its margin takes 40 at
+    the top, and the box ran 482 → 678 against a region ending at 638. Forty pixels out of its own
+    region, which the schematic ruler drew correctly and which read as the ruler being wrong.
+
+    So the sizing is `flex` and `align-self` only, and the containers that hold one lay out as a
+    column (see the `:has(> .area-box)` rule in styles/base.css). Both parents this was written for
+    still work: a grid cell fills through `align-self: stretch`, a flex column through `flex: 1 1 0%`.
+    What is gone is the third case nobody checked — block, with something above it.
+  */
+  flex: 1 1 0%;
+  align-self: stretch;
+  min-width: 0;
+  min-height: 0;
+  padding: var(--deck-space-2);
+  border-radius: var(--deck-radius-item);
+  text-align: center;
+  /*
+    The tint and the edge are the SAME role at two strengths, so a region reads as one block rather
+    than as a box with a border round it.
+
+    ★★ MIXED TOWARD --deck-bg, NOT TOWARD transparent, and the difference is legibility rather than
+    taste. A translucent fill takes whatever is behind it: on the divider slide that is the accent
+    green, where the label came out at 2.79:1 and its note at 1.20:1 against a 3:1 floor; on the
+    bleed slide it is the media, where the contrast sweep could not resolve a ground at all and
+    reported UNRESOLVED rather than a pass. Mixing toward the register's own background instead
+    gives an opaque box that still self-adjusts — --deck-bg is light on light slides and dark on
+    dark ones — so the same declaration reads on every ground the deck has.
+  */
+  background: color-mix(in oklab, var(--area-role), var(--deck-bg) 84%);
+  box-shadow: inset 0 0 0 3px color-mix(in oklab, var(--area-role), var(--deck-bg) 40%);
+  color: var(--deck-fg);
+}
+/* Two roles, far enough apart in hue to be told apart from the back of a room, which is the only
+   viewing distance this deck has. */
+.area-box.is-top { justify-content: flex-start; }
+
+.area-box.is-content { --area-role: var(--deck-accent); }
+.area-box.is-figure { --area-role: var(--deck-series-3); }
+
+.area-box-name {
+  font-family: var(--font-sans);
+  font-size: var(--type-deck-label-size);
+  font-weight: var(--type-deck-label-weight);
+  letter-spacing: var(--type-deck-label-tracking);
+  text-transform: uppercase;
+}
+/* The share sits under the name in the tabular treatment, because these are numbers a reader is
+   comparing down a ladder of slides — 3fr against 2fr against 1fr — not prose. */
+.area-box-note {
+  font-family: var(--font-mono);
+  font-size: var(--type-deck-caption-size);
+  color: var(--deck-fg-muted);
+}
+</style>

package/components/AreaChart.vue

@@ -0,0 +1,145 @@
+<script setup>
+/*
+  An area chart sized for a room. Same stack as LineChart.vue — real @unovis/vue marks,
+  ChartFrame.vue for ceremony, chartData.ts for shaping — with the fill doing the arguing.
+
+  STACKED BY DEFAULT, and that is a claim about the data, not a style. Stacked areas say "these
+  parts sum to a whole"; overlaid ones say "these are independent quantities that happen to share
+  an axis". Passing `overlaid` switches the claim, and the mark changes with it: Unovis stacks when
+  a single <VisArea> is handed an ARRAY of y accessors, and overlays when each series gets its own
+  mark. Nothing here fakes one with the other.
+
+  Overlaid areas are drawn semi-transparent with their own top line, because three opaque fills on
+  top of each other hide two of them.
+*/
+import { computed } from 'vue';
+import { VisXYContainer, VisAxis, VisArea, 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, … }]`. `label` names the point on the x axis. */
+  data: { type: Array, required: true },
+  /** Series to plot, in stacking and legend order: `[{ key, name }]`. Omit and every numeric field on the first row becomes a series. */
+  series: { type: Array, default: null },
+  /** Draw the series as independent translucent layers instead of stacking them. Use when they do not sum to a whole. */
+  overlaid: { type: Boolean, default: false },
+  /** 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. */
+  legend: { type: Boolean, default: true },
+  /** Where the legend sits: `top-left`, `top-center`, `top-right`, `bottom-left`, `bottom-center`
+   *  or `bottom-right`. The EDGE is reading order — above is read before the marks, below is a
+   *  caption read after them; the ALIGNMENT is for the column the chart sits in, centred under a
+   *  full-width plot and pulled to an edge where a centred key would float in a gutter. */
+  legendPosition: {
+    type: String,
+    default: 'bottom-center',
+    validator: (p) => ['top-left', 'top-center', 'top-right', 'bottom-left', 'bottom-center', 'bottom-right'].includes(p),
+  },
+  /** Title under the x axis. Omit when the labels already say what they are. */
+  xLabel: { type: String, default: null },
+  /** Title beside the y axis. Omit when the unit is in the slide's heading. */
+  yLabel: { type: String, default: null },
+  /** Formats the y tick labels. Defaults to British grouping, compact past four digits. */
+  format: { type: Function, default: formatValue },
+  /** Ceiling on x tick labels. Deck labels are 36px, so more than a handful collide. */
+  maxTicks: { type: Number, default: 6 },
+  /** Draw the two axes. Off is a SHAPE reading — the marks alone, no scale — for a chart that is
+   *  being shown rather than read: a specimen, a register test, a sparkline beside a figure.
+   *
+   *  ★ IT REMOVES THEM, IT DOES NOT HIDE THEM. Unovis reserves the axis band whether or not the
+   *  axis paints, so hiding one in CSS leaves the plot inset by a tick row and a label column that
+   *  are no longer there — measured at a 150px plot, the marks drew 22px of a 63px box. Not
+   *  rendering the component is what gives the room back.
+   *
+   *  ⚠ A chart carrying VALUES needs its scale. Turning this off says the reading is the shape. */
+  axes: { type: Boolean, default: true },
+  /** The sentence drawn when there is nothing to plot. */
+  empty: { type: String, default: 'No data' },
+});
+
+const state = computed(() => chartState(props.data, props.series));
+const message = computed(() => (state.value.kind === 'ready' ? null : stateMessage(state.value, props.empty)));
+const seriesList = computed(() => (state.value.kind === 'ready' ? state.value.series : []));
+
+const x = (_d, i) => i;
+const y = computed(() => seriesList.value.map((s) => (d) => d[s.key]));
+const colors = computed(() => seriesList.value.map((s) => s.color));
+
+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" :margin="{ top: 16, right: 24, bottom: 0, left: 0 }">
+      <!-- The array-of-accessors form IS the stack: Unovis routes every accessor through d3's
+           stacking the moment `y` is an array. Overlaid series are separate marks, one each. -->
+      <VisArea v-if="!overlaid" :x="x" :y="y" :color="colors" />
+      <template v-else>
+        <VisArea
+          v-for="(yAcc, i) in y"
+          :key="seriesList[i].key"
+          :x="x"
+          :y="yAcc"
+          :color="colors[i]"
+          :opacity="0.35"
+          :line-width="6"
+          line
+        />
+      </template>
+      <VisAxis
+        v-if="axes"
+        type="x"
+        :grid-line="false"
+        :tick-line="false"
+        :tick-values="xTicks"
+        :tick-format="xFormat"
+        :tick-padding="16"
+        :label="xLabel"
+        :label-margin="24"
+        tick-text-hide-overlapping
+      />
+      <VisAxis
+        v-if="axes"
+        type="y"
+        :tick-format="format"
+        :num-ticks="4"
+        :tick-line="false"
+        :domain-line="false"
+        :tick-padding="16"
+        :label="yLabel"
+        :label-margin="24"
+      />
+      <!-- ★★ `y-stacked`, NOT `y`, WHEREVER THE MARKS STACK. The crosshair plots a circle per
+           series, and given `y` it plots each at its RAW value — which on a stacked chart is a
+           position nothing is drawn at: the second series' circle lands inside the first band
+           rather than on the boundary between them. `yStacked` is Unovis' own accumulator, so the
+           circles sit where the bands actually meet. -->
+      <VisCrosshair :duration="crosshairMs" :hideWhenFarFromPointer="CROSSHAIR_HIDE_WHEN_FAR" :circleRadius="CROSSHAIR_CIRCLE_R" :x="x" :y="overlaid ? y : undefined" :yStacked="overlaid ? undefined : y" :template="tip" :color="colors" />
+      <VisTooltip v-bind="deckTooltip()" />
+    </VisXYContainer>
+  </ChartFrame>
+</template>