@uiresponse/renderer-react 0.1.0

package/src/blocks/viz.jsx

@@ -0,0 +1,616 @@
+/**
+ * The visual leaves: `chart`, `metric`, `progress`, `badge`.
+ *
+ * `chart` is where we lean hardest on OpenUI's MIT component layer: their Recharts wrappers carry
+ * tooltips, legends, responsive sizing, scroll behaviour and axis ticks that would be months of work
+ * to rebuild, and they already look the way we want. So we do not restyle them and we do not hand
+ * them a palette — we format the DATA before it reaches them, because a `format` per binding, a
+ * currency code on a column and an `empty` policy are semantics their props cannot carry.
+ *
+ * Their pixels, our meaning (DECISIONS X4). The one exception is the donut, which we draw ourselves;
+ * the reason is written above `Donut`.
+ */
+import React, { useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
+import { AreaChart, BarChart, LineChart, MiniLineChart } from "@openuidev/react-ui";
+import { useUIResponse, scopeFor } from "./context.js";
+import { Value, Absent, BlockError } from "./primitives.jsx";
+import { formatValue } from "../core/format.js";
+import { resolveValue, resolveBinding, boundColumn, isBinding } from "../core/value.js";
+import { isEmptyValue } from "../core/empty.js";
+import { runWithConfirm } from "../core/actions.js";
+
+// ───────────────────────────────────────────────────────────────────────────────
+// metric — the one number
+// ───────────────────────────────────────────────────────────────────────────────
+/**
+ * DELTA — `metric.delta` (DECISIONS MET4), drawn as the design's own status-tone chip.
+ *
+ * That treatment remains a STAND-IN, and it is worth saying plainly: `UIR-element-system.dc.html`
+ * contains no arrows, no triangles and no signed percentages, so there is no delta in the design to
+ * copy. The chip is the nearest thing the design does define. Before this reaches a user, the design
+ * file should say what a delta looks like — a signed number with a colour means something different
+ * in every product. Recorded in `design/NOTES-designsync.md` D3.
+ *
+ * Three things here are the SCHEMA's, not this renderer's, and may not drift (metric.schema.json):
+ *   · direction is the sign of the resolved value; the page does no arithmetic (B9)
+ *   · no `direction_good` means a NEUTRAL tone — a page that never said which way is good has not
+ *     earned a green chip, and guessing "up is good" paints a rising cost as a win
+ *   · a delta that resolves to null, or to something that is not a number, DRAWS NOTHING. Not a
+ *     zero, not an empty chip. A tile that understates is honest; one that invents a flat trend is
+ *     not, and that honesty is exactly what makes `delta` safe to ignore on an older renderer.
+ */
+const DELTA_TONE = {
+  up: { up: "positive", down: "negative", flat: "neutral" },
+  down: { up: "negative", down: "positive", flat: "neutral" },
+};
+const DELTA_GLYPH = { up: "▲", down: "▼", flat: "–" };
+const DELTA_WORD = { up: "up", down: "down", flat: "unchanged" };
+
+function MetricDelta({ delta, scope, now }) {
+  if (!delta) return null;
+
+  let raw;
+  try {
+    raw = resolveValue(delta.value, scope);
+  } catch {
+    return null; // an unresolvable delta is an absent delta, never a zero
+  }
+  if (isEmptyValue(raw) || !Number.isFinite(Number(raw))) return null;
+
+  const n = Number(raw);
+  const direction = n > 0 ? "up" : n < 0 ? "down" : "flat";
+  const tone = DELTA_TONE[delta.direction_good]?.[direction] ?? "neutral";
+
+  const bind = isBinding(delta.value) ? delta.value.$bind : null;
+  // The glyph carries the sign, once. Letting `format.sign` carry it too reads as "+▲80%".
+  const text = formatValue(Math.abs(n), { ...(bind?.format ?? {}), sign: "never" }, { column: bind ? boundColumn(bind, scope) : null, now });
+  const spoken = `${DELTA_WORD[direction]} ${text}${delta.vs ? ` ${delta.vs}` : ""}`;
+
+  return (
+    <span className="uir-metric__delta" data-tone={tone} data-direction={direction} aria-label={spoken}>
+      <em aria-hidden="true">{DELTA_GLYPH[direction]}&thinsp;{text}</em>
+      {delta.vs && <span aria-hidden="true">{delta.vs}</span>}
+    </span>
+  );
+}
+
+/** Anyone who asked their system to stop moving things gets the number, immediately. */
+const prefersReducedMotion = () =>
+  typeof window !== "undefined" && typeof window.matchMedia === "function"
+    ? window.matchMedia("(prefers-reduced-motion: reduce)").matches
+    : false;
+
+const COUNT_UP_MS = 750; // the chat prototype's `startCount` duration (`uir-chat.dc.html:411-421`), exactly.
+
+/**
+ * Where a metric's LAST SHOWN value survives a close (behavior parity F4).
+ *
+ * `sessionStorage`, deliberately: the point is that reopening a saved view climbs from the number
+ * you last saw to the number that is now true — "the world moved while you were away", said in
+ * motion. That story only makes sense within a sitting, and a sitting is what sessionStorage is.
+ * Persisting it would be a durable-data commitment for a decoration; localStorage says no here.
+ */
+const seenKey = (pageId, blockId) => (pageId && blockId ? `uir-count:${pageId}:${blockId}` : null);
+function lastSeen(key) {
+  if (!key || typeof window === "undefined") return null;
+  try {
+    const raw = window.sessionStorage.getItem(key);
+    const n = raw === null ? NaN : Number(raw);
+    return Number.isFinite(n) ? n : null;
+  } catch {
+    return null; // storage denied is a browser mood, not an error
+  }
+}
+function rememberSeen(key, value) {
+  if (!key || typeof window === "undefined") return;
+  try {
+    window.sessionStorage.setItem(key, String(value));
+  } catch {
+    /* full or denied storage costs the seed, nothing else */
+  }
+}
+
+/**
+ * COUNT-UP — the number climbs to itself the first time its data lands.
+ *
+ * ADOPTED BY THE DESIGN. This began as a renderer invention (NOTES-designsync.md D7); the chat
+ * prototype now specifies it — 750ms, cubic ease-out, starting when the tile LANDS — so the
+ * duration above is extracted, not chosen.
+ *
+ * Three rules, and each of them is about not lying:
+ *   · It runs ONCE, on the first non-empty numeric value. A metric that re-resolves after a filter
+ *     change SNAPS. Re-animating would say "new information arrived" when the user caused it, and it
+ *     would turn a filter into a slot machine.
+ *   · It never runs on a non-number. A date counting up from 1970 is not charming.
+ *   · `prefers-reduced-motion` skips it entirely — the number is information, the climb is not.
+ *
+ * And one memory: a REOPENED view climbs from the value it last showed, not from 0 (`seedKey`).
+ * From-zero says "here is a number"; from-last-seen says "here is what changed" — the second is
+ * the true one, and when nothing changed, nothing moves.
+ *
+ * The eased curve is `1 - (1 - t)³`, not the design's `cubic-bezier(0.2, 0.7, 0.3, 1)`: a bezier is a
+ * CSS timing function, and there is no CSS property here to time. The shapes are close and the
+ * difference is unobservable on a 750ms count. Said plainly rather than left for someone to discover.
+ */
+function useCountUp(target, active, seedKey = null) {
+  const [shown, setShown] = useState(target);
+  const animated = useRef(false);
+
+  useEffect(() => {
+    if (!active || animated.current || prefersReducedMotion()) {
+      setShown(target);
+      if (active) {
+        animated.current = true;
+        rememberSeen(seedKey, target);
+      }
+      return undefined;
+    }
+    animated.current = true;
+    const from = lastSeen(seedKey) ?? 0;
+    rememberSeen(seedKey, target);
+    if (from === target) {
+      setShown(target); // the world did not move; neither does the number
+      return undefined;
+    }
+
+    let raf = 0;
+    const t0 = performance.now();
+    const tick = (t) => {
+      const p = Math.min(1, (t - t0) / COUNT_UP_MS);
+      setShown(from + (target - from) * (1 - (1 - p) ** 3));
+      if (p < 1) raf = requestAnimationFrame(tick);
+      else setShown(target); // land on the exact value, never on 999,999.4
+    };
+    raf = requestAnimationFrame(tick);
+    return () => cancelAnimationFrame(raf);
+  }, [target, active, seedKey]);
+
+  return shown;
+}
+
+/** `date` and `relative_time` are numbers a renderer must never treat as quantities. */
+const NON_COUNTABLE = new Set(["date", "relative_time"]);
+
+export function MetricBlock({ block, emphasis }) {
+  const uir = useUIResponse();
+  const scope = scopeFor(uir);
+  const column = isBinding(block.value) ? boundColumn(block.value.$bind, scope) : null;
+  const format = isBinding(block.value) ? block.value.$bind.format : undefined;
+  const empty = isBinding(block.value) ? block.value.$bind.empty : undefined;
+
+  // `row: "only"` over ≠1 row throws, by design (B6). It must not throw *between* hooks: a render
+  // that runs three hooks and a render that runs none is a hook-order crash, and it would take the
+  // whole page down to report one tile's assertion. Resolve, hold the error, keep the hooks.
+  let value = null;
+  let failed = null;
+  try {
+    value = resolveValue(block.value, scope);
+  } catch (e) {
+    failed = e;
+  }
+
+  const countable =
+    typeof value === "number" && Number.isFinite(value) &&
+    !NON_COUNTABLE.has(format?.as) && column?.type !== "date";
+  const shownValue = useCountUp(countable ? value : 0, countable, countable ? seenKey(uir.pageId, block.id) : null);
+
+  if (failed) return <BlockError message={failed.message} />;
+
+  const body = (
+    <div className="uir-metric" data-emphasis={emphasis}>
+      <span className="uir-eyebrow uir-metric__label">{block.label}</span>
+      <span className="uir-metric__value">
+        <Value value={countable ? shownValue : value} format={format} empty={empty} column={column} now={uir.now} />
+        {/* A unit is suppressed when the format already carries one — a voice renderer would
+            otherwise say "pounds" twice (VERSIONING §9, `metric.unit.redundant`). */}
+        {block.unit && !isEmptyValue(value) && !UNIT_BEARING.has(format?.as) && (
+          <span className="uir-metric__unit">{block.unit}</span>
+        )}
+      </span>
+      <MetricDelta delta={block.delta} scope={scope} now={uir.now} />
+    </div>
+  );
+
+  if (!block.on_click) return body;
+  return (
+    <button type="button" className="uir-metric--clickable" onClick={() => runWithConfirm(block.on_click, { ...uir.actionCtx, scope })}>
+      {body}
+    </button>
+  );
+}
+const UNIT_BEARING = new Set(["currency", "percent", "bytes", "duration"]);
+
+// ───────────────────────────────────────────────────────────────────────────────
+// progress — how much of a bounded thing is done
+// ───────────────────────────────────────────────────────────────────────────────
+export function ProgressBlock({ block }) {
+  const uir = useUIResponse();
+  const scope = scopeFor(uir);
+  const value = resolveValue(block.value, scope);
+  const total = resolveValue(block.total, scope);
+  const column = isBinding(block.value) ? boundColumn(block.value.$bind, scope) : null;
+  const format = isBinding(block.value) ? block.value.$bind.format : undefined;
+
+  const known = !isEmptyValue(value) && !isEmptyValue(total) && Number(total) > 0;
+  const pct = known ? Math.max(0, Math.min(100, (Number(value) / Number(total)) * 100)) : 0;
+
+  return (
+    <div className="uir-progress">
+      <div className="uir-progress__head">
+        {block.label && <span className="uir-eyebrow">{block.label}</span>}
+        <span className="uir-progress__value">
+          {known ? (
+            <>
+              {formatValue(value, format, { column, now: uir.now })}
+              <span className="uir-progress__ratio"> / {formatValue(total, format, { column, now: uir.now })}</span>
+            </>
+          ) : (
+            // Progress against an unknown total is not 0%. It is unknown, and it says so.
+            <Absent policy={isBinding(block.value) ? block.value.$bind.empty : undefined} />
+          )}
+        </span>
+      </div>
+      <div
+        className="uir-progress__track"
+        role="progressbar"
+        aria-valuenow={known ? Math.round(pct) : undefined}
+        aria-valuemin={0}
+        aria-valuemax={100}
+        aria-label={block.label ?? "Progress"}
+      >
+        <div className="uir-progress__fill" style={{ width: `${pct}%` }} />
+      </div>
+    </div>
+  );
+}
+
+// ───────────────────────────────────────────────────────────────────────────────
+// badge — a status, stated
+// ───────────────────────────────────────────────────────────────────────────────
+export function BadgeBlock({ block }) {
+  const uir = useUIResponse();
+  const scope = scopeFor(uir, uir.row);
+  const value = resolveValue(block.value, scope);
+  // `tone_map` is data-driven tone; `tone` is static. They are mutually exclusive in the schema.
+  const mapped = block.tone_map?.find((e) => e.value === value)?.tone;
+  const tone = block.tone ?? mapped ?? "neutral";
+
+  if (isEmptyValue(value)) return <Absent policy={isBinding(block.value) ? block.value.$bind.empty : undefined} />;
+
+  return (
+    <span className="uir-badge" data-tone={tone}>
+      {block.label && <span className="uir-badge__label">{block.label}</span>}
+      {String(value)}
+    </span>
+  );
+}
+
+// ───────────────────────────────────────────────────────────────────────────────
+// stage_checklist — a position in an ordered process
+// ───────────────────────────────────────────────────────────────────────────────
+/**
+ * The block asserts ONE thing: where a record has got to in a fixed, ordered process. The stages are
+ * authored, so their order is the array's order and this renderer never reorders them.
+ *
+ * "Where you are" — the first not-done stage — is DERIVED here and is not in the document. It is a
+ * drawing of the data, not a claim about it: a voice renderer that reads "Approved: pending" has
+ * already said everything the marker says. Deriving it in the renderer is what keeps `current` out
+ * of the schema, where it would be a second source of truth that could disagree with `done`.
+ *
+ * A stage whose `done` cannot be resolved is drawn as PENDING, not as done. An unknown state is not
+ * an achievement.
+ */
+export function StageChecklistBlock({ block }) {
+  const uir = useUIResponse();
+  const scope = scopeFor(uir, uir.row);
+
+  const stages = (block.stages ?? []).map((stage) => {
+    let done = false;
+    try {
+      done = resolveValue(stage.done, scope) === true;
+    } catch {
+      done = false;
+    }
+    return { label: stage.label, done };
+  });
+
+  const currentIndex = stages.findIndex((s) => !s.done);
+
+  return (
+    <ol className="uir-stages" aria-label={block.title ?? "Stages"}>
+      {stages.map((stage, i) => (
+        <li
+          className="uir-stages__stage"
+          key={i}
+          data-done={stage.done || undefined}
+          data-current={i === currentIndex || undefined}
+        >
+          {/* The tick is decoration over text that already says it. A screen reader hears the state
+              from the visually-hidden word, not from a glyph it would have to name. */}
+          <span className="uir-stages__mark" aria-hidden="true">{stage.done ? "✓" : ""}</span>
+          <span className="uir-stages__label">{stage.label}</span>
+          <span className="uir-stages__state">{stage.done ? "done" : "pending"}</span>
+        </li>
+      ))}
+    </ol>
+  );
+}
+
+// ───────────────────────────────────────────────────────────────────────────────
+// chart — ONE block, kinds are props
+// ───────────────────────────────────────────────────────────────────────────────
+const CHART_HEIGHT = 300;
+
+/**
+ * Their chart containers measure their own width ONCE, on mount, and never again. Inside a CSS grid
+ * whose track resolves after first layout — which is what the section rail is — they measure zero
+ * and draw a 36px chart in a 960px frame. Nothing errors; the chart is simply not there.
+ *
+ * So we own the measurement, and use it only as a GATE: nothing renders until the frame has a width,
+ * at which point their own observer measures correctly. We do not pass `width` — that prop is
+ * applied to the outer container while the plot still subtracts the sticky y-axis column, and the
+ * bars drift out from under their labels by exactly the axis's width.
+ *
+ * This is the tax on wrapping someone else's component. It is much cheaper than a fork.
+ */
+function useMeasuredWidth() {
+  const ref = useRef(null);
+  const [width, setWidth] = useState(0);
+
+  useLayoutEffect(() => {
+    const el = ref.current;
+    if (!el) return undefined;
+    const measure = () => setWidth(el.clientWidth);
+    measure();
+    const ro = new ResizeObserver(measure);
+    ro.observe(el);
+    return () => ro.disconnect();
+  }, []);
+
+  return [ref, width];
+}
+
+/**
+ * The donut is OURS, not theirs — the one chart we draw ourselves.
+ *
+ * Their `PieChart` grows its ring to fill whatever box it is handed and stacks its legend beneath.
+ * On a tile that produced a bloated hoop with one dominant slice and the small categories bunched
+ * into slivers you could not read or name. A pie's whole job is comparing parts to a whole, so the
+ * category, its value and its share have to sit next to the arc that represents them.
+ *
+ * Sixty lines of trigonometry buys: a ring sized to the tile rather than to the box, a legend that
+ * reads `label · value · share` beside the arcs, slices ordered largest-first so the eye can compare
+ * them, and a `—` for a share of nothing rather than `0.0%`. Their area/line/bar charts stay theirs;
+ * this one was cheaper to own than to fight.
+ */
+const TAU = Math.PI * 2;
+const polar = (cx, cy, r, a) => [cx + r * Math.cos(a - Math.PI / 2), cy + r * Math.sin(a - Math.PI / 2)];
+
+function arcPath(cx, cy, rOuter, rInner, start, end) {
+  // A single slice that is the entire circle cannot be drawn as an arc: its start and end points
+  // coincide and the path collapses. Two half-arcs draw the same ring.
+  if (end - start >= TAU - 1e-6) {
+    return [
+      `M ${cx - rOuter} ${cy}`, `A ${rOuter} ${rOuter} 0 1 1 ${cx + rOuter} ${cy}`, `A ${rOuter} ${rOuter} 0 1 1 ${cx - rOuter} ${cy}`,
+      `M ${cx - rInner} ${cy}`, `A ${rInner} ${rInner} 0 1 0 ${cx + rInner} ${cy}`, `A ${rInner} ${rInner} 0 1 0 ${cx - rInner} ${cy}`, "Z",
+    ].join(" ");
+  }
+  const large = end - start > Math.PI ? 1 : 0;
+  const [x1, y1] = polar(cx, cy, rOuter, start);
+  const [x2, y2] = polar(cx, cy, rOuter, end);
+  const [x3, y3] = polar(cx, cy, rInner, end);
+  const [x4, y4] = polar(cx, cy, rInner, start);
+  return `M ${x1} ${y1} A ${rOuter} ${rOuter} 0 ${large} 1 ${x2} ${y2} L ${x3} ${y3} A ${rInner} ${rInner} 0 ${large} 0 ${x4} ${y4} Z`;
+}
+
+function Donut({ slices, palette, format, column, now }) {
+  const total = slices.reduce((sum, s) => sum + s.value, 0);
+  const size = 148, cx = size / 2, cy = size / 2, rOuter = 68, rInner = 44;
+
+  let cursor = 0;
+  const arcs = slices.map((s, i) => {
+    const sweep = total > 0 ? (s.value / total) * TAU : 0;
+    const d = arcPath(cx, cy, rOuter, rInner, cursor, cursor + sweep);
+    cursor += sweep;
+    return { d, color: palette[i % palette.length], ...s };
+  });
+
+  const share = (v) => (total > 0 ? `${((v / total) * 100).toFixed(total > 0 && v / total < 0.1 ? 1 : 0)}%` : null);
+
+  return (
+    <div className="uir-pie">
+      <svg width={size} height={size} viewBox={`0 0 ${size} ${size}`} role="img" aria-label={`${slices.length} categories`}>
+        {arcs.map((a, i) => (
+          <path key={i} d={a.d} fill={a.color} stroke="var(--uir-color-sheet)" strokeWidth="1.5">
+            <title>{`${a.label}: ${a.value}`}</title>
+          </path>
+        ))}
+        <text x={cx} y={cy - 3} textAnchor="middle" fill="var(--uir-color-ink)"
+          style={{ font: `600 20px var(--uir-font-body)`, fontVariantNumeric: "tabular-nums" }}>
+          {formatValue(total, format, { column, now })}
+        </text>
+        <text x={cx} y={cy + 14} textAnchor="middle" fill="var(--uir-color-faint)"
+          style={{ font: `400 10px var(--uir-font-body)` }}>total</text>
+      </svg>
+
+      <div className="uir-pie__legend">
+        {arcs.map((a, i) => (
+          <div className="uir-pie__row" key={i}>
+            <span className="uir-pie__swatch" style={{ background: a.color }} />
+            <span className="uir-pie__label" title={a.label}>{a.label}</span>
+            <span className="uir-pie__value">{formatValue(a.value, format, { column, now })}</span>
+            {/* A share of nothing is not 0%. It is unknown, and the block says so. */}
+            <span className="uir-pie__pct">{share(a.value) ?? <Absent />}</span>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+/**
+ * The multi-series legend (`02 · Chart`, "Plays vs downloads"): swatch and label, in the order the
+ * series are drawn, so the colour a reader sees on the plot is the colour they can name.
+ *
+ * `y` is always series 0 — that is CH5's whole design — so its swatch is the palette's first entry
+ * and `series[]` continues from there. A single-series chart draws no legend: one entry would only
+ * repeat the tile's own label.
+ */
+function ChartLegend({ names, values, palette }) {
+  if (names.length < 2) return null;
+  return (
+    <div className="uir-chart__legend">
+      {names.map((name, i) => (
+        <span className="uir-chart__legend-item" key={i}>
+          <span className="uir-chart__swatch" style={{ background: palette[i % palette.length] }} />
+          <span className="uir-chart__legend-label">{name}</span>
+          <span className="uir-chart__legend-value">{values[i]}</span>
+        </span>
+      ))}
+    </div>
+  );
+}
+
+export function ChartBlock({ block }) {
+  const uir = useUIResponse();
+  // `scopeFor` builds a fresh object, so memoising against it would memoise nothing: `data` would
+  // get a new identity every render, and Recharts restarts its enter animation whenever `data`
+  // changes identity. The area never finished drawing — it was permanently at frame zero.
+  // `uir` is itself memoised by <UIResponsePage>, so this is stable until the data or params actually move.
+  const scope = useMemo(() => scopeFor(uir), [uir]);
+
+  /**
+   * MULTI-SERIES (CH5). Their charts derive one series per non-category key of each row, so a chart
+   * of N quantities is N numeric keys. `y` is series 0 and `series[]` follows: a renderer that had
+   * never heard of `series[]` would draw `y` alone, which is the one true line CH5 chose this shape
+   * to preserve.
+   *
+   * Keys are the series' NAMES, so they must be distinct — two series bound to columns with the same
+   * label would silently collapse into one line. We suffix a collision rather than drop a series.
+   */
+  const { data, xKey, yKey, yValues, names, legendValues } = useMemo(() => {
+    const yBind = block.y.$bind;
+    const yCol = boundColumn(yBind, scope);
+    const ys = resolveBinding(yBind, scope);
+    const primary = yCol?.label ?? yBind.field;
+
+    if (!block.x) return { data: [], xKey: null, yKey: primary, yValues: ys.map(Number), names: [primary], legendValues: [] };
+
+    const xBind = block.x.$bind;
+    const xCol = boundColumn(xBind, scope);
+    const xs = resolveBinding(xBind, scope);
+    const xKeyName = xCol?.label ?? xBind.field;
+
+    // `label` is REQUIRED on every `series[]` entry precisely so this is never a guess.
+    const extra = (block.series ?? []).filter((s) => s?.y?.$bind).map((s) => ({
+      name: s.label,
+      values: resolveBinding(s.y.$bind, scope),
+      bind: s.y.$bind,
+      column: boundColumn(s.y.$bind, scope),
+    }));
+
+    const taken = new Set([xKeyName, primary]);
+    for (const s of extra) {
+      let name = s.name;
+      for (let n = 2; taken.has(name); n++) name = `${s.name} (${n})`;
+      taken.add(name);
+      s.name = name;
+    }
+
+    // The x axis is FORMATTED before it reaches Recharts: a date column drawn as "Jul 2026" is the
+    // page's `format.date_style` at work, and their axis has no idea OBL has one.
+    const rows = xs.map((x, i) => {
+      const row = {
+        [xKeyName]: formatValue(x, xBind.format, { column: xCol, now: uir.now }),
+        [primary]: Number(ys[i]),
+      };
+      for (const s of extra) row[s.name] = Number(s.values[i]);
+      return row;
+    });
+
+    const latest = (values) => [...values].reverse().find((value) => value !== null && value !== undefined);
+    const values = [
+      formatValue(latest(ys), yBind.format, { column: yCol, now: uir.now }),
+      ...extra.map((series) => formatValue(latest(series.values), series.bind.format, { column: series.column, now: uir.now })),
+    ];
+    return { data: rows, xKey: xKeyName, yKey: primary, yValues: ys.map(Number), names: [primary, ...extra.map((s) => s.name)], legendValues: values };
+  }, [block, scope, uir.now]);
+
+  /**
+   * A series may declare its own `kind`, and the observed dashboard chart genuinely mixes three lines
+   * with one bar. Their chart components draw every series in ONE shape — a `LineChart` has no bars.
+   *
+   * So we draw them all in the block's `kind` and SAY SO. Silently flattening a bar into a line is
+   * how a chart becomes a lie (VERSIONING §4 rule 3); refusing to draw it at all would be worse. The
+   * notice fires once, on mount, not on every render.
+   */
+  const mixed = (block.series ?? []).filter((s) => s.kind && s.kind !== block.kind).map((s) => s.label);
+  const notify = uir.actionCtx?.onNotice;
+  useEffect(() => {
+    if (!mixed.length) return;
+    notify?.(`This renderer draws every series in one shape. ${mixed.length === 1 ? `"${mixed[0]}" is` : `${mixed.length} series are`} drawn as ${block.kind} rather than the shape the page asked for.`);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [block.id, mixed.length, notify]);
+
+  const palette = uir.theme.chart;
+  const [frameRef, width] = useMeasuredWidth();
+
+  // A pie's slices are (category, value) pairs. Largest first: a pie exists to compare parts, and
+  // an unsorted ring makes the reader do the sorting.
+  const slices = useMemo(() => {
+    if (block.kind !== "pie" || !block.x) return [];
+    return data
+      .map((row) => ({ label: String(row[xKey]), value: Number(row[yKey]) }))
+      .filter((s) => Number.isFinite(s.value) && s.value > 0)
+      .sort((a, b) => b.value - a.value);
+  }, [block.kind, block.x, data, xKey, yKey]);
+
+  if (block.kind === "sparkline") {
+    return <MiniLineChart data={yValues} size="100%" />;
+  }
+
+  if (!data.length) return null;
+
+  if (block.kind === "pie") {
+    const yCol = boundColumn(block.y.$bind, scope);
+    return <Donut slices={slices} palette={uir.theme.pie} format={block.y.$bind.format} column={yCol} now={uir.now} />;
+  }
+
+  const inner = Math.max(0, width);
+  // We pass the measured frame width as `width`, and it is load-bearing for AXIS ALIGNMENT, not for
+  // sizing. Their charts give each category a fixed band (`ELEMENT_SPACING`, ~72px) and a "natural"
+  // content width of `categories × band`. When the frame is WIDER than that — three or eight bars in
+  // a 1000px tile — the plot stretches the bars to fill (its inner track is `minWidth:100%`) while
+  // the x-axis is centre-padded to the natural width instead. The result is the trial's defect: bars
+  // spread across the frame, labels bunched in the middle under the wrong bars. Handing them an
+  // explicit `width` makes the two agree — the chart renders at its natural width, centred, every
+  // label back beneath its bar. Verified in the preview harness for 3 and 8 categories, y-axis intact.
+  //
+  // An earlier note here claimed the OPPOSITE: that `width` drifts bars from labels by the axis's
+  // width. That was the behaviour BEFORE we gated rendering on a measured frame (`inner > 0`); a
+  // width handed to a not-yet-laid-out container was stale. With the gate, `width` is the fix, not
+  // the wound — measured before, corrected here.
+  const common = { data, categoryKey: xKey, height: CHART_HEIGHT, legend: false, isAnimationActive: true, width: inner };
+
+  return (
+    <div className="uir-chart-frame">
+      <ChartLegend names={names} values={legendValues} palette={palette} />
+      <div className="uir-chart-frame__inner" ref={frameRef}>
+        {/* Draw nothing until we have measured. A chart drawn at zero width and then corrected
+            flashes; a chart that appears once, correct, does not. */}
+        {inner === 0 ? (
+          <div style={{ height: CHART_HEIGHT }} />
+        ) : (
+          <>
+            {/* No `customPalette`. Their charts already look right; handing them our colours was
+                how they stopped looking like theirs. The one chart we colour is the donut below,
+                because we draw it. */}
+            {block.kind === "area" && <AreaChart {...common} grid showYAxis />}
+            {block.kind === "line" && <LineChart {...common} grid showYAxis />}
+            {block.kind === "bar" && <BarChart {...common} grid showYAxis radius={2} />}
+          </>
+        )}
+      </div>
+    </div>
+  );
+}