@humanforest/slidev-theme 0.1.0

package/components/ChartFrame.vue

@@ -0,0 +1,426 @@
+<script setup>
+/*
+  The ceremony every deck chart shares: the room-scale Unovis type ramp, the legend, and the
+  empty state. The MARK never comes through here — each chart component mounts its own
+  @unovis/vue mark in the default slot, exactly the way packages/charts' FChartFrame keeps mark
+  props out of the frame. Wrap ceremony, never the chart.
+
+  ★ THE TYPE RAMP IS THE POINT. Unovis ships 12px axis tick labels and a 9px legend bullet, which
+  are correct on a dashboard and invisible from the back of a room. The `--vis-*` block below
+  re-points every one of them at the deck type roles (--type-deck-*), so a chart on a 1920x1080
+  canvas carries 36px axis labels — the same tier Bars.vue already sets its category labels at, and
+  unconditionally WCAG large text, so the 3:1 floor is the one that governs the muted ink.
+
+  ★★ DECLARED ON `.deck-chart`, NOT ON `:root`, and both halves of that matter.
+
+    1. Unovis injects its OWN `:root` defaults at RUNTIME, after this sheet has loaded, so a `:root`
+       block here loses on order (packages/tokens/dataviz/unovis.css fights the same battle with a
+       `:root:root` specificity bump). A declaration on the chart's own element sidesteps the
+       contest entirely: custom properties inherit, and a value declared ON the element always beats
+       one inherited from an ancestor, whatever either selector's specificity.
+    2. A custom property computes ONCE where it is declared. Declared at `:root`, every
+       `var(--deck-fg-muted)` below would freeze at the LIGHT value and a `class: deck-dark` slide
+       would draw light-mode axis ink on a dark ground — the same island trap deck.css's own derived
+       surfaces carry a three-selector fix for. Declared here, the reference resolves at a node that
+       is INSIDE the `.deck-dark` subtree, so it flips with the slide and no JS runs at all.
+
+  Colours reach the marks as `var()` REFERENCES rather than resolved values for the same reason:
+  CSS re-resolves them continuously, so a theme flip repaints with no remount, no repaint key and no
+  cached-palette bug to work around.
+
+  EVERY CHART CONTAINER SETS `:duration="0"` — the chart is finished the moment its slide is.
+  Slidev pre-renders neighbouring slides, so an entry animation runs while nobody is looking and is
+  already over (or worse, caught mid-flight) by the time the slide is on screen; and the deck's
+  reduced-motion floor suppresses it for part of the audience anyway, so the animated version is
+  never the one everyone sees. A chart that draws itself in is a dashboard idea.
+
+  ★ THE GRID IS DELIBERATELY FINER THAN THE LABELS, and it is the library's decision, not a defect
+  to chase. @unovis/ts's Axis builds its grid from `this._getNumTicks() * 2` (components/axis/
+  index.js, `_buildGrid`), so four labelled ticks paint seven or eight grid lines — minor rules
+  between the labelled ones. Read back from the live DOM, the axis holds two sets of `.tick` nodes:
+  four carrying the labels with their tick MARK suppressed, and a second set with empty text whose
+  lines span the plot. The only way to make the two agree is to pass explicit `tickValues` (the same
+  `_buildGrid` prefers them over its doubled count when they are set), which means computing the
+  domain and a nice-number ladder here instead of letting the library scale itself. Not worth it:
+  the minor rules are pale (--deck-border) and give the eye a halfway reference. Recorded so the
+  next reader does not spend an afternoon hunting a bug that is not there.
+*/
+defineProps({
+  /** Resolved series for the legend — `[{ key, name, color }]`, as `chartData.ts` returns them. */
+  series: { type: Array, default: () => [] },
+  /**
+   * Plot height in px. The deck default fills a content column under a heading; a chart that owns a
+   * whole slide wants more.
+   *
+   * ★ 0 MEANS FILL — take whatever the parent gives, rather than a number the slide had to guess.
+   * The same convention DeckMap's own `height` already uses, and it is the library's behaviour
+   * rather than an invention: Unovis' container resolves `config.height || containerHeight`, so a
+   * falsy height makes it MEASURE its box, and it keeps a ResizeObserver on that box to re-fit.
+   *
+   * ⚠ THE CELL HAS TO HAVE A HEIGHT TO GIVE. A percentage resolves against a definite ancestor, so
+   * a frame in an auto-sized grid row fills nothing — put it in a row that stretches.
+   */
+  height: { type: Number, default: 0 },
+  /** Draw the series legend. Off for a chart that labels its marks directly. */
+  legend: { type: Boolean, default: true },
+  /**
+   * Where the legend sits: one of `top-left`, `top-center`, `top-right`, `bottom-left`,
+   * `bottom-center`, `bottom-right`.
+   *
+   * Two axes in one name, because they are two different decisions. The EDGE is about reading
+   * order — a legend above is read before the marks and belongs to a chart whose colours need
+   * introducing; one below is a caption, read after the picture has been looked at. The ALIGNMENT
+   * is about the column the chart sits in: centred under a plot that fills the frame, and pulled to
+   * an edge when the chart shares a row with copy and a centred key would float in the gutter.
+   *
+   * `bottom-center` is the default because a caption is the common case.
+   *
+   * This replaced a two-value `top`/`bottom` enum in which the alignment was BAKED IN — `top` was
+   * always start-aligned and `bottom` always centred — so half of the six were unreachable and the
+   * two that existed could not be told apart from their own names.
+   */
+  legendPosition: {
+    type: String,
+    default: 'bottom-center',
+    validator: (p) => ['top-left', 'top-center', 'top-right', 'bottom-left', 'bottom-center', 'bottom-right'].includes(p),
+  },
+  /** When set, the frame draws this sentence in place of the chart — the honest empty state. Null renders the mark. */
+  message: { type: String, default: null },
+});
+</script>
+
+<template>
+  <div class="deck-chart" :class="{ 'is-fill': !height }">
+    <!-- The empty state is a real WELL, not a bare line of text: a chart that has nothing to say
+         should still occupy the space the chart would have, so a slide does not reflow around
+         missing data and an audience can see that something was meant to be there. -->
+    <div v-if="message" class="deck-chart-empty" :style="height ? { height: `${height}px` } : undefined">
+      {{ message }}
+    </div>
+    <template v-else>
+      <div class="deck-chart-plot">
+        <slot :height="height" />
+      </div>
+      <!-- The legend sits AFTER the plot in the DOM and is lifted by `order` when it belongs above.
+           Source order is the caption case, which is the default, so the common reading order is
+           the one that needs no reordering at all.
+
+           Two classes come out of one prop name: the edge decides source order, the alignment
+           decides the row. Split rather than six classes so the CSS below stays two small tables. -->
+      <div
+        v-if="legend && series.length"
+        class="deck-chart-legend"
+        :class="[
+          legendPosition.startsWith('top') ? 'is-top' : 'is-bottom',
+          `is-${legendPosition.slice(legendPosition.indexOf('-') + 1)}`,
+        ]"
+      >
+        <!-- Hand-drawn rather than <VisBulletLegend>: the library's legend is a flex row of spans
+             sized off --vis-legend-*, which works, but a deck legend also has to survive being read
+             at distance and wrap cleanly inside a half-slide column. Owning the markup is what lets
+             the bullet be a real disc at deck scale and the label take the deck's own body tier. -->
+        <span v-for="s in series" :key="s.key" class="deck-chart-key">
+          <span class="deck-chart-bullet" :style="{ background: s.color }" />
+          {{ s.name }}
+        </span>
+      </div>
+    </template>
+  </div>
+</template>
+
+<style scoped>
+.deck-chart {
+  display: flex;
+  flex-direction: column;
+  gap: var(--deck-space-3);
+  width: 100%;
+
+  /* ── The Unovis adapter, at room scale ──────────────────────────────────────────────────── */
+  --vis-font-family: var(--font-sans);
+  --vis-axis-font-family: var(--font-sans);
+  --vis-legend-font-family: var(--font-sans);
+
+  /* Series colours. SIX: --deck-series-1…6 alias the published categorical palette
+     in the product's order, and the palette's ceiling is six. Leaving --vis-color5 and up
+     undefined is deliberate — a chart that somehow reaches for a sixth gets Unovis' own off-brand
+     default rather than a Forest colour that was never designed, and chartData.ts's
+     `over-capacity` state stops it before it renders at all. */
+  --vis-color0: var(--deck-series-1);
+  --vis-color1: var(--deck-series-2);
+  --vis-color2: var(--deck-series-3);
+  --vis-color3: var(--deck-series-4);
+  --vis-color4: var(--deck-series-5);
+  --vis-color5: var(--deck-series-6);
+
+  /* Axis ink and rules. The grid is the deck's own border role, so it reads as structure rather
+     than as data — one step of ink on the page, no more. */
+  --vis-axis-grid-color: var(--deck-border);
+  --vis-axis-tick-color: var(--deck-border);
+  --vis-axis-domain-color: var(--deck-border-strong);
+  --vis-axis-grid-line-width: 2px;
+  --vis-axis-tick-line-width: 2px;
+  --vis-axis-domain-line-width: 2px;
+
+  /* Tick labels take the small body tier (36px) — the same tier Bars.vue's category labels use,
+     and the smallest thing on this deck that is still a sentence rather than a caption. */
+  --vis-axis-tick-label-color: var(--deck-fg-muted);
+  --vis-axis-tick-label-font-size: var(--type-deck-body-sm-size);
+  --vis-axis-tick-label-weight: var(--type-deck-body-sm-weight);
+  /* An axis TITLE is a label role: same size, bold — the two-weight system has nothing between. */
+  --vis-axis-label-color: var(--deck-fg);
+  --vis-axis-label-font-size: var(--type-deck-label-size);
+  --vis-axis-label-weight: var(--type-deck-label-weight);
+
+  /* The donut's centre. Title tier for the figure, small body for what it counts. */
+  --vis-donut-central-label-font-size: var(--type-deck-title-size);
+  --vis-donut-central-label-font-weight: var(--type-deck-title-weight);
+  --vis-donut-central-label-font-family: var(--font-sans);
+  --vis-donut-central-label-text-color: var(--deck-fg);
+  --vis-donut-central-sub-label-font-size: var(--type-deck-body-sm-size);
+  --vis-donut-central-sub-label-font-weight: var(--type-deck-body-sm-weight);
+  --vis-donut-central-sub-label-font-family: var(--font-sans);
+  --vis-donut-central-sub-label-text-color: var(--deck-fg-muted);
+
+  /*
+    ★★ THESE WERE INERT. Every declaration below sat inside the `:deep([class*='-central-label'])`
+    rule further down, so they were declared on the central LABEL — a text node that is a sibling of
+    the marks, not an ancestor of them. Custom properties inherit downwards only, so the arcs, bars,
+    scatter points and areas never saw one of them and drew Unovis' own defaults for the whole life
+    of this file, while the comments beside them described a treatment nobody was getting.
+
+    READ BACK FROM THE LIVE DOM before the move, on the specimen's donut slide: the frame reported
+    an EMPTY `--vis-donut-segment-stroke-color`, the label reported the cream, and the arc itself
+    was stroked `oklab(0.782…)` at 2px — the library default, not `--deck-bg` at 4px. Scatter and
+    area read 1px and 0px against the 3px and 4px written here.
+
+    Nothing about the values changed in moving them; only where they are declared.
+  */
+
+  /*
+    ── THE CROSSHAIR ─────────────────────────────────────────────────────────────────────────────
+
+    The circle sits ON the series it reports, so it takes that series' colour as its fill and the
+    chart's own ground as its ring — the same treatment the donut segment gets, and the reason it
+    reads as a mark lifted off the line rather than a bead threaded onto it. Unovis rings it at 1px,
+    which at this size is a hairline around a 9px dot.
+
+    The line itself is a guide, not a mark: it takes the border's weight, not a series colour.
+  */
+  --vis-crosshair-circle-stroke-color: var(--deck-bg);
+  --vis-crosshair-circle-stroke-width: 4;
+  --vis-crosshair-line-stroke-color: var(--deck-border-strong);
+  --vis-crosshair-line-stroke-width: 2;
+
+  /*
+    ── THE TOOLTIP ───────────────────────────────────────────────────────────────────────────────
+
+    ⚠ ITS VARIABLES ARE NOT HERE, and cannot be. The panel is mounted on `document.body`, so nothing
+    declared on this element reaches it — custom properties inherit downwards. They live on `:root`
+    in base.css, beside the note explaining why the body is the only container that can position a
+    tooltip correctly on a slide the deck scales.
+  */
+
+  /* The track behind the arcs. Our slices always sum to the whole, so a visible track can only
+     ever surface in the gaps — where any opaque colour is wrong the moment the slide is dark. */
+  --vis-donut-background-color: transparent;
+  /* The arc separator is the SLIDE GROUND, so segments read as separated rather than outlined. */
+  --vis-donut-segment-stroke-color: var(--deck-bg);
+  --vis-donut-segment-stroke-width: 4px;
+
+  /* Marks. The stroke that lifts a bar off its neighbour is the ground, same reasoning as the
+     donut's; the scatter carries one too so overlapping points stay countable. */
+  --vis-stacked-bar-stroke-color: var(--deck-bg);
+  --vis-stacked-bar-stroke-width: 3px;
+  --vis-grouped-bar-stroke-color: var(--deck-bg);
+  --vis-grouped-bar-stroke-width: 0px;
+  --vis-scatter-stroke-color: var(--deck-bg);
+  --vis-scatter-stroke-width: 3px;
+  --vis-scatter-fill-opacity: 0.85;
+  /* Unovis paints a scatter's point labels in its OWN default #5b5f6d, which nothing here ever
+     re-pointed — the block above sets the mark's stroke, width and fill, not its label. Measured
+     against the well's own edge (--deck-border resolves to #dad5cf) that is 4.36:1, under the 4.5
+     floor a 12px/500 label is held to; --deck-fg-muted takes it to 5.32:1 there and 7.42:1 on the
+     plot's own ground. */
+  --vis-scatter-point-label-text-color-dark: var(--deck-fg-muted);
+  --vis-area-stroke-width: 4px;
+}
+
+/*
+  ★ THE CENTRE BLOCK IS NOT CENTRED, and it cannot be from inside Unovis. The library places the
+  figure and its sub-label at dy -0.55em and +0.55em — of their OWN font sizes, which the deck
+  deliberately makes different (title 60px over body-sm 36px). Equal fractions of unequal sizes are
+  unequal offsets, so the pair hangs above the ring's true centre by half their difference.
+
+  MEASURED on apps/deck's donut slides, ring centre against the union of the two text
+  boxes: 16.8px high, or 0.7 of the 24px the two roles differ by. Written as that subtraction so the
+  correction follows the roles if either is retuned; the 0.7 is the empirical part, true at the one
+  size pair this deck ships. Residual after it: 1.9px, which is glyph-box noise rather than offset.
+
+  ⚠ MEASURE THIS WITH THE FONTS LOADED. The first reading said 12px and was taken mid-swap, on
+  fallback metrics — correcting to it left the block visibly high and the second measurement
+  disagreed with the first by 40%.
+
+  Both lines carry a `-central-label` suffix (the prefix is an emotion hash and changes per build),
+  so the selector matches on the suffix and moves the pair together — correcting one would re-open
+  the gap between them.
+*/
+/*
+  ★★ THE CHART DOCTRINE HAD A HOLE IN IT, AND THE HOLE WAS A CSS TRANSITION. Every container in this
+  theme sets :duration="0" and the comment at the top of this file says why — "the chart is finished
+  the moment its slide is". That prop governs Unovis' own data animation. It does not reach the
+  opacity transition Unovis puts on axis tick labels, so charts animated anyway, in the one way
+  nobody had thought to switch off.
+
+  What it looked like, and why it read as a bug rather than a flourish: Slidev mounts every slide, so
+  a chart is laid out long before it is shown — at 0x0. With no width every x tick collapses onto the
+  same point, Unovis' overlap-hider does exactly its job and keeps the FIRST label while hiding the
+  rest at opacity 0. Arrive on the slide, the container finally has width, the hider recomputes, and
+  the five it had hidden fade back in over ~436ms while the first one — never hidden, so nothing to
+  animate — is simply there. One label pops, the others drift in behind it. Measured on slide 82
+  arriving from 81: Camden opacity 1 at frame zero, the other five 0 -> 1 at 436ms.
+
+  A full page load hides this completely: the container has width from the start, every label begins
+  hidden, and they all fade together. It only appears when moving slide to slide, which is the only
+  way a deck is ever actually shown.
+
+  The transition goes, not the opacity — a label that genuinely overlaps at real width should still
+  be hidden, because that is the hider doing useful work. Only the drift between the two states is
+  removed, which is what :duration="0" was always meant to say.
+
+  Substring-matched on the emotion class for the reason the central-label rule below is: the hash in
+  css-6qjh0y-tick-label-hideable is generated and must never be written down.
+*/
+:deep([class*='-tick-label']) {
+  transition: none;
+}
+
+:deep([class*='-central-label']) {
+  /* ★ `translate`, NOT `transform`. Unovis positions these texts with a transform ATTRIBUTE, and a
+     CSS `transform` property replaces it outright rather than composing — the label left the ring
+     entirely and landed at the plot's origin. `translate` is its own property and composes after. */
+  translate: 0 calc((var(--type-deck-title-size) - var(--type-deck-body-sm-size)) * 0.7);
+}
+
+.deck-chart-plot {
+  width: 100%;
+}
+
+/*
+  ★★ FILL MODE, AND IT IS THREE RULES BECAUSE THE HEIGHT HAS TO BE HANDED DOWN A CHAIN. The frame
+  takes the cell, the plot takes what the frame has left once the legend is laid out, and the
+  container Unovis renders takes the plot — a percentage stops at the first ancestor with no
+  definite height, so skipping any one of the three leaves the chart measuring zero and falling back
+  to the library's 150px default.
+
+  `min-height: 0` on the plot because it is a flex item: without it a flex child refuses to shrink
+  below its content, and a chart that overflows its cell pushes the legend off the frame instead of
+  giving up its own space.
+*/
+.deck-chart.is-fill {
+  height: 100%;
+}
+.deck-chart.is-fill .deck-chart-plot {
+  flex: 1;
+  min-height: 0;
+}
+.deck-chart.is-fill .deck-chart-plot > :deep(*),
+.deck-chart.is-fill .deck-chart-empty {
+  height: 100%;
+}
+/*
+  ★★ AND ONE STEP DEEPER FOR THE TWO MARKS THAT WRAP THEIR CONTAINER. Unovis reads
+  `config.height || containerHeight`, and containerHeight is the clientHeight of the element IT was
+  handed — so the chain has to reach that element, not merely the plot's first child. Ten of the
+  twelve charts put the container there directly; ChordChart and TimelineChart each wrap theirs in a
+  div of their own, so the wrapper took the 100% and the container inside it measured zero and fell
+  back to the library's 300px default: measured on the chord at a 559px plot, svg height="300",
+  unmoved by a window resize because nothing about its own box had changed.
+
+  Named rather than matched with a universal descendant: `:deep(*)` would also reach inside the SVG,
+  and a 100% height on a <g> is not nothing.
+*/
+.deck-chart.is-fill .deck-chart-plot > :deep(.deck-chord),
+.deck-chart.is-fill .deck-chart-plot > :deep(.deck-timeline),
+.deck-chart.is-fill .deck-chart-plot > :deep(.deck-chord) > *,
+.deck-chart.is-fill .deck-chart-plot > :deep(.deck-timeline) > * {
+  height: 100%;
+}
+
+.deck-chart-legend {
+  display: flex;
+  flex-wrap: wrap;
+  /* ROW gap space-1, column gap unchanged. Only the wrapped case is affected — a legend that fits on
+     one line never uses a row gap at all — and that is exactly the case that overflows: on
+     deck-template slide 40 four keys wrap 3 + 1, putting the second row's baseline 4px past the 96px
+     text inset. 8px buys twice the overrun.
+
+     ★ NOT `.deck-chart`'s own gap, which is the obvious one-line fix and the wrong one. That gap is
+     the plot-to-legend rhythm LondonMap deliberately mirrors ("a map key and a chart key read as
+     the same furniture"), and a4fe8cd resized two maps rather than move it. Trimming it here would
+     undo that from the other side. This is the legend's own internal wrap spacing — a different
+     measurement that no other component copies. */
+  gap: var(--deck-space-1) var(--deck-space-5);
+  font-size: var(--type-deck-body-sm-size);
+  line-height: var(--type-deck-body-sm-line-height);
+  color: var(--deck-fg);
+}
+/* The EDGE. Source order is the caption case, so only `top` reorders — the legend sits after the
+   plot in the DOM, which is the reading order a screen reader gets either way. */
+.deck-chart-legend.is-top {
+  order: -1;
+}
+/* The ALIGNMENT, as its own table. These used to be welded to the edge — `top` implied
+   start-aligned and `bottom` implied centred — which made four of the six arrangements
+   unreachable and the other two impossible to name honestly. */
+.deck-chart-legend.is-left {
+  justify-content: flex-start;
+}
+.deck-chart-legend.is-center {
+  justify-content: center;
+}
+.deck-chart-legend.is-right {
+  justify-content: flex-end;
+}
+.deck-chart-key {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--deck-space-2);
+  white-space: nowrap;
+}
+.deck-chart-bullet {
+  /* A real disc at reading distance. The library's 9px bullet is a speck beside 36px type. */
+  width: 0.6em;
+  height: 0.6em;
+  border-radius: var(--deck-radius-full);
+  flex: none;
+}
+
+.deck-chart-empty {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  text-align: center;
+  padding: var(--deck-space-5);
+  background: var(--deck-surface);
+  border-radius: var(--deck-radius-nested);
+  color: var(--deck-fg-muted);
+  font-size: var(--type-deck-body-size);
+  line-height: var(--type-deck-body-line-height);
+}
+
+/*
+  ★ THE TOOLTIP'S SWATCH IS THE ONE THING IN THE HOUSE TEMPLATE THAT IS NOT A CUSTOM PROPERTY.
+  Every size, colour and padding in `forestTipFrame` is themeable — the dot's 8px width and height
+  are written inline, and only its border-radius is a variable. Eight pixels beside 36px type is a
+  speck, so it is matched to the crosshair's own circle instead.
+
+  Selected by the `aspect-ratio` in that inline style, which is the stable half of the contract: the
+  swatch is the only element the template gives one to. `!important` is required because the value
+  it overrides is inline, which no stylesheet rule outranks by specificity or source order.
+*/
+:deep([class*='tooltip'] span[style*='aspect-ratio']) {
+  width: 18px !important;
+  height: 18px !important;
+  border-radius: 9px !important;
+}
+</style>