slidemind 0.3.19 → 0.4.0

package/src/builders/chart-jsx.mjs

@@ -0,0 +1,410 @@
+// One read chart as a native `<Chart>`: its data, the design's chart colours by
+// what each mark means, and the labels the image shows — on the chart itself,
+// in the number format it sets them in. The data and the labels come from the
+// reader's spec; the colours from the design bundle (design-tokens.mjs
+// `chartPalette`), never from the painting.
+import { chartPalette, contrastRatio } from "./design-tokens.mjs";
+import { waterfallAsStacked } from "./concept-geometry.mjs";
+import { holeSizeFor, ringRect } from "./chart-hole.mjs";
+import { figureOf, labelKey, onlyFigure } from "./chart-labels.mjs";
+
+const q = (s) => JSON.stringify(String(s));
+
+// A figure in a label: "95.4%", "€1.4m", "1,200", "+3.7pp", "95,4 %".
+const FIGURE = /^(.*?)([-+−]?)(\d[\d.,\s]*\d|\d)(.*)$/s;
+const num = (t) => {
+  const m = /-?\d+(?:[.,]\d+)?/.exec(String(t).replace(/(\d),(\d{3})/g, "$1$2"));
+  return m ? Number(m[0].replace(",", ".")) : null;
+};
+const near = (a, b) => a != null && b != null && Math.abs(a - b) <= Math.max(0.05, Math.abs(b) * 0.01);
+
+// A figure's digits, each way its separators can be read: "1,200" is 1200
+// grouped or 1.2 with a decimal comma; "95.4" is 95.4.
+function readings(digits) {
+  const plain = digits.replace(/\s/g, "");
+  const out = [{ read: Number(plain.replace(/[.,]/g, "")), decimals: 0, grouped: /[.,]/.test(plain) }];
+  for (const sep of [".", ","]) {
+    const at = plain.lastIndexOf(sep);
+    const decimals = plain.length - at - 1;
+    if (at < 0 || decimals < 1 || decimals > 3) continue;
+    out.push({
+      read: Number(`${plain.slice(0, at).replace(/[.,]/g, "")}.${plain.slice(at + 1)}`),
+      decimals,
+      grouped: /[.,]/.test(plain.slice(0, at)),
+    });
+  }
+  return out;
+}
+
+// A label carries a value when its figure IS the value at the label's own
+// precision: "95.4%" carries 95.4, the axis tick "96%" beside it does not.
+const carries = (reading, value) => Math.abs(reading.read - Math.abs(value)) <= 0.5 * 10 ** -reading.decimals + 1e-9;
+
+const literal = (s) => (s ? `"${s.replace(/"/g, "")}"` : "");
+
+/**
+ * The number format the image's value labels are set in — decimals, thousands,
+ * a sign, a unit before or after the figure — read from the labels that carry
+ * the chart's own values: "95.4%" -> `0.0"%"`, "€1.4m" -> `"€"0.0"m"`,
+ * "+3.7pp" -> `+0.0"pp";-0.0"pp";0.0"pp"`. The decimal separator is the
+ * viewer's (PowerPoint localises it), so a German PowerPoint shows "95,4%".
+ * Null when no label carries a value, the labels disagree, or they say no more
+ * than General does.
+ */
+export function labelNumberFormat(values, seen) {
+  const forms = [];
+  for (const value of values) {
+    for (const label of seen) {
+      const m = FIGURE.exec(String(label).trim());
+      const reading = m && readings(m[3]).find((r) => carries(r, value));
+      if (!reading) continue;
+      forms.push({ pre: m[1].trim(), sign: m[2] === "+", decimals: reading.decimals, grouped: reading.grouped, post: m[4].trim() });
+      break;
+    }
+  }
+  if (!forms.length) return null;
+  const [first] = forms;
+  if (forms.some((f) => f.pre !== first.pre || f.post !== first.post)) return null;
+  const decimals = Math.max(...forms.map((f) => f.decimals));
+  const grouped = forms.some((f) => f.grouped);
+  const signed = forms.some((f) => f.sign);
+  if (!first.pre && !first.post && !decimals && !grouped && !signed) return null;
+  const body = `${grouped ? "#,##0" : "0"}${decimals ? `.${"0".repeat(decimals)}` : ""}`;
+  const part = (sign) => `${sign}${literal(first.pre)}${body}${literal(first.post)}`;
+  return signed ? `${part("+")};${part("-")};${part("")}` : part("");
+}
+
+/**
+ * The ground a chart is drawn on: the nearest container holding it that the
+ * reader saw painted, else the slide's own (the design's light or dark ground).
+ */
+function groundOf(e, spec, tokens) {
+  const byId = new Map((spec.elements ?? []).map((o) => [o.id, o]));
+  for (let p = byId.get(e.parent); p; p = byId.get(p.parent)) {
+    if (p.fill && p.fill !== "none" && p.fillHex) return p.fillHex;
+  }
+  const name = spec.background === "dark" ? "--theme-tx1" : "--theme-bg1";
+  return tokens.find((t) => t.name === name)?.hex ?? null;
+}
+
+// A filled mark the ground swallows is no colour for this chart.
+const SEEN_ON_GROUND = 1.25;
+const QUIET_ON_GROUND = 1.1;
+
+/**
+ * The design's chart palette as this chart's ground shows it: a slot the ground
+ * swallows (a pale fill on a pale card, a dark one on an ink panel) leaves the
+ * cycle, and a role painted in it takes the first colour that stays. Null when
+ * the bundle declares no theme: the master then paints its own series.
+ */
+function paletteOn(e, spec, tokens) {
+  const palette = chartPalette(tokens);
+  if (!palette) return null;
+  const ground = groundOf(e, spec, tokens);
+  const hexOf = (p) => (p?.rgb ? `#${p.rgb}` : tokens.find((t) => t.name === `--theme-${p?.scheme}`)?.hex ?? null);
+  const seen = (p) => { const hex = hexOf(p); return !ground || !hex || (contrastRatio(hex, ground) ?? 0) >= SEEN_ON_GROUND; };
+  const kept = palette.series.filter(seen);
+  const series = kept.length ? kept : palette.series;
+  const roles = Object.fromEntries(Object.entries(palette.roles).map(([r, p]) => [r, p && seen(p) ? p : series[0]]));
+  // A mark set back only needs to part from the ground, not carry a series.
+  const quietSeen = (p) => { const hex = hexOf(p); return !ground || !hex || (contrastRatio(hex, ground) ?? 0) >= QUIET_ON_GROUND; };
+  return { series, roles, quiet: (palette.quiet ?? []).filter(quietSeen) };
+}
+
+/**
+ * One paint per series (or point): the colour its role names where the reader
+ * judged one, else the next colour of the palette that no role on this chart
+ * has taken — so a highlighted bar never shares its colour with a plain one.
+ */
+function paintsFor(roles, count, palette) {
+  const key = (p) => JSON.stringify(p);
+  const named = (r) => r && r !== "series" && palette.roles[r];
+  const taken = new Set(roles.filter(named).map((r) => key(palette.roles[r])));
+  // Several marks set back take the design's quiet neutrals one by one, never
+  // one grey for all (x113 QBR 3: three slices beside the highlighted lane all
+  // context grey); a colour another role here has taken stays that role's.
+  const contexts = roles.slice(0, count).filter((r) => r === "context").length;
+  const others = new Set(roles.filter((r) => named(r) && r !== "context").map((r) => key(palette.roles[r])));
+  const quiet = contexts > 1 ? (palette.quiet ?? []).filter((p) => p && !others.has(key(p))) : [];
+  for (const p of quiet.slice(0, contexts)) taken.add(key(p));
+  // The series palette first, then the role colours no mark here has taken:
+  // more slices than the palette holds still read apart before it repeats.
+  const cycle = [];
+  for (const p of [...palette.series, ...Object.values(palette.roles)]) {
+    if (p && !taken.has(key(p)) && !cycle.some((q) => key(q) === key(p))) cycle.push(p);
+  }
+  if (!cycle.length) cycle.push(...palette.series);
+  let k = 0;
+  let c = 0;
+  return Array.from({ length: count }, (_, i) => {
+    if (roles[i] === "context" && quiet.length) return c < quiet.length ? quiet[c++] : cycle[k++ % cycle.length];
+    return named(roles[i]) ? palette.roles[roles[i]] : cycle[k++ % cycle.length];
+  });
+}
+
+// How a mark is drawn, as the reader read it (`chart.draws`), never its colour:
+// a plan or target bar as an empty dashed outline, a target as a dashed line.
+const DASH = { dashed: "dash", dotted: "sysDot" };
+const hollow = (draw) => draw === "outlined" || draw === "dashed" || draw === "dotted";
+
+/** A filled mark's style (a bar, a slice, a point of either) in `paint`, drawn as read. */
+function markStyle(paint, draw) {
+  if (!hollow(draw)) return paint ? { fill: paint } : {};
+  return { fill: "none", line: { ...(paint ? { color: paint } : {}), widthPt: 1.25, ...(DASH[draw] ? { dash: DASH[draw] } : {}) } };
+}
+
+/** A line series' style in `paint`, drawn as read: a dashed or dotted line marks no points. */
+function lineStyle(paint, draw) {
+  const dash = DASH[draw];
+  return { line: { ...(paint ? { color: paint } : {}), ...(dash ? { dash } : {}) }, ...(dash ? { marker: { symbol: "none" } } : {}) };
+}
+
+/**
+ * The value axis as the image paints it: the axis the reader's tick labels
+ * spell (folded back by chart-labels.mjs: visible, its range, its step, its
+ * format), else the start the reader read where the marks visibly do not stand
+ * on 0 (`axisStart`, a cut axis — x113 QBR 2: ±1pp steps beside 19% totals
+ * drawn as slivers) — kept only below every mark, never cutting one off.
+ * Null: the axis stays as the chart's defaults draw it.
+ */
+function valueAxisOf(c, lowest, notes, id) {
+  const axis = c.folded?.axis;
+  if (axis && Number.isFinite(axis.min) && Number.isFinite(axis.max) && axis.max > axis.min) {
+    return { visible: true, majorGridlines: false, min: axis.min, max: axis.max, ...(axis.step > 0 ? { majorUnit: axis.step } : {}), ...(axis.format ? { numberFormat: axis.format } : {}) };
+  }
+  const start = typeof c.axisStart === "number" && Number.isFinite(c.axisStart) ? c.axisStart : null;
+  if (start == null || start === 0) return null;
+  if (!(lowest > start)) {
+    notes.push(`chart ${id}: the reader read the value axis starting at ${start}, but a mark ends at ${lowest} — kept on 0, the axis never cuts a mark off`);
+    return null;
+  }
+  return { visible: false, majorGridlines: false, min: start };
+}
+
+const LEGEND_POS = { top: "t", bottom: "b", left: "l", right: "r" };
+
+/**
+ * The chart's legend as the image draws it: where the reader saw one (or where
+ * the chart's own legend rows were drawn as separate texts and folded back,
+ * chart-labels.mjs), at the side it names. A spec that says nothing: a legend
+ * for more than one series, and for a pie whose slices the image names.
+ */
+function legendOf(c, type, seriesCount, small, categories = []) {
+  const declared = typeof c.legend === "string" ? c.legend : null;
+  // A pie's legend names its slices: shown where the image names them (x111
+  // QBR 3: the doughnut's slice names were read, no legend was built, and the
+  // agent typed one beside it as four text boxes).
+  const sliced = ["pie", "doughnut"].includes(type);
+  const named = sliced && (c.labels ?? []).some((t) => categories.some((cat) => cat && String(t).trim().toLowerCase() === String(cat).trim().toLowerCase()));
+  const show = c.folded?.legend === true || (!small && (declared ? declared !== "none" : seriesCount > 1 || named));
+  return { show, pos: LEGEND_POS[declared] ?? LEGEND_POS[c.folded?.side] ?? (sliced ? "r" : "b") };
+}
+
+// The painted label that carries `value` at its own precision, or null.
+function labelCarrying(value, seen) {
+  for (const label of seen) {
+    const m = FIGURE.exec(String(label).trim());
+    if (m && readings(m[3]).some((r) => carries(r, value))) return m;
+  }
+  return null;
+}
+
+/**
+ * A read waterfall as its stacked-column construction (`waterfallAsStacked`):
+ * the bars the reader named stand on the axis, every step starts where the bar
+ * before it ends; the bars the image labels are labelled — a step with its
+ * signed change just above the bar, a total inside its end — in the image's own
+ * number format; connector lines only where the image draws them. Figures that
+ * do not bridge are built as read and reported in `notes`.
+ */
+function waterfallJsx(e, spec, tokens, data, base, notes) {
+  const c = e.chart;
+  const values = data.series[0].values;
+  const small = e.w < 180 || e.h < 110;
+  const isCategory = (t) => data.categories.some((cat) => cat && String(cat).trim().toLowerCase() === t.trim().toLowerCase().replace(/\s+/g, " "));
+  const seen = [...(Array.isArray(c.labels) ? c.labels : []), ...(c.folded?.texts ?? [])].map(String).filter((t) => !isCategory(t));
+  // A small chart carries the labels its image paints on it (folded back), and
+  // no others.
+  const labelled = small && c.folded?.values !== true ? [] : values.map((v, i) => (labelCarrying(v, seen) ? i : -1)).filter((i) => i >= 0);
+  const w = waterfallAsStacked(data, { labelled });
+  const totals = new Set(w.totals);
+  const name = (i) => JSON.stringify(String(data.categories[i] ?? i + 1).replace(/\s+/g, " ").trim());
+  for (const m of w.mismatches) {
+    notes.push(`chart ${e.id}: the steps before total ${name(m.index)} end at ${m.running}, but that total reads ${m.total} — the figures do not bridge; check them against the approved plan (built as read, not corrected)`);
+  }
+  if (!w.declared) {
+    const later = w.totals.filter((i) => i > 0).map(name);
+    notes.push(`chart ${e.id}: the reader named no waterfall totals; the first bar stands on the axis${later.length ? `, and ${later.join(", ")} because ${later.length === 1 ? "it equals" : "each equals"} the running sum` : ""} — check which bars the concept draws standing on the axis`);
+  }
+  // Each sign in the format the image sets it in; a fall's bar is drawn as a
+  // height, so its label carries the painted minus as a literal.
+  const rises = values.filter((v, i) => !totals.has(i) && v >= 0);
+  const falls = values.filter((v, i) => !totals.has(i) && v < 0);
+  const riseFormat = labelNumberFormat(rises, seen);
+  const fallSign = falls.map((v) => labelCarrying(v, seen)?.[2]).find((s) => s === "-" || s === "−");
+  const fallBody = labelNumberFormat(falls.map(Math.abs), seen.map((t) => t.replace(/^(\D*?)[-−]/, "$1"))) ?? "General";
+  const fallFormat = fallSign ? `"${fallSign}"${fallBody}` : fallBody;
+  const totalFormat = labelNumberFormat(values.filter((_, i) => totals.has(i)), seen);
+  const label = (format, position) => ({ show: true, value: true, position, ...(format ? { numberFormat: format } : {}) });
+  // Each bar in its role's colour: what the reader judged it means, else a total
+  // is the highlight and a step a rise or a fall.
+  const palette = paletteOn(e, spec, tokens);
+  const roles = values.map((v, i) => (Array.isArray(c.roles) && c.roles[i] && c.roles[i] !== "series" ? c.roles[i] : totals.has(i) ? "highlight" : v >= 0 ? "positive" : "negative"));
+  const paints = palette ? paintsFor(roles, values.length, palette) : [];
+  const draws = Array.isArray(c.draws) ? c.draws : [];
+  const fill = (i) => markStyle(paints[i], draws[i]);
+  const style = w.data.series.map(() => ({ labels: { show: false } }));
+  style[w.index.base] = { fill: "none", labels: { show: false } };
+  style[w.index.bars] = {
+    labels: { show: false },
+    points: values
+      .map((_, i) => ({ idx: i, ...fill(i), ...(totals.has(i) && labelled.includes(i) ? { label: label(totalFormat, "inEnd") } : {}) }))
+      .filter((p) => Object.keys(p).length > 1),
+  };
+  if (w.index.below != null) {
+    style[w.index.below] = { labels: { show: false }, points: values.map((_, i) => ({ idx: i, ...fill(i) })).filter((p, i) => w.data.series[w.index.below].values[i] != null && Object.keys(p).length > 1) };
+  }
+  if (w.index.change != null) {
+    style[w.index.change] = {
+      fill: "none",
+      labels: { show: false },
+      points: labelled.filter((i) => !totals.has(i)).map((i) => ({ idx: i, label: label(values[i] >= 0 ? riseFormat : fallFormat, "inBase") })),
+    };
+  }
+  const connector = palette?.roles.reference ?? null;
+  for (const k of w.index.connectors) {
+    style[k] = { line: { ...(connector ? { color: connector } : {}), widthPt: 0.75, dash: "dash" }, marker: { symbol: "none" }, labels: { show: false } };
+  }
+  const showCategories = c.folded?.categories === true || (!small && (!Array.isArray(c.labels) || data.categories.some((cat) => cat && c.labels.some((t) => String(t).trim().toLowerCase().replace(/\s+/g, " ") === String(cat).trim().toLowerCase().replace(/\s+/g, " ")))));
+  // Where each bar's ink ends lowest: a total from its top down to the axis, a
+  // step between the running value before and after it.
+  let running = 0;
+  let lowest = Infinity;
+  values.forEach((v, i) => {
+    if (totals.has(i)) { lowest = Math.min(lowest, v); running = v; } else { lowest = Math.min(lowest, running, running + v); running += v; }
+  });
+  const value = valueAxisOf(c, lowest, notes, e.id) ?? { visible: false, majorGridlines: false };
+  const axes = ` axes={${JSON.stringify({ category: { visible: showCategories, majorGridlines: false }, value })}}`;
+  return `<B ${base} h={${e.h}}><Chart type="column" data={${JSON.stringify(w.data)}}${axes} labels={{ show: false }} legend={{ show: false, pos: "b" }} layout={${JSON.stringify({ overlap: 100, gapWidth: 60 })}} dispBlanksAs="gap" seriesStyle={${JSON.stringify(style)}} style={{ width: ${e.w}, height: ${e.h} }} /></B>`;
+}
+
+/**
+ * The `<B>` holding one read chart with its native `<Chart>`. `data` is the
+ * renderable payload (`nativeChartData`); `base` the element's id and position
+ * attributes; `notes` collects what the agent must check.
+ */
+export function chartJsx(e, spec, tokens, data, base, notes = []) {
+  const c = e.chart;
+  const type = c.type;
+  if (type === "waterfall") return waterfallJsx(e, spec, tokens, data, base, notes);
+  // A thumbnail-sized chart (x28 cloud 8: four charts under 180px) cannot
+  // carry value labels and a legend without overlapping itself — unless its
+  // image paints them there (x113 QBR 1: eight 107px KPI charts, each with its
+  // values and quarters), folded back as the chart's own.
+  const small = e.w < 180 || e.h < 110;
+  const folded = c.folded ?? {};
+  const sliced = ["pie", "doughnut"].includes(type);
+  // A pie's legend rows that carry each slice's value ("DE–PL lane 21%") name
+  // the slices so: the legend lists name and value as the image does.
+  const legendRows = sliced && folded.legend ? legendWithValues(data, folded.texts ?? []) : null;
+  if (legendRows) data = { ...data, categories: legendRows };
+  // The design's colours by what each series (each slice of a pie; each bar of a
+  // single series whose bars mean different things) stands for.
+  const palette = paletteOn(e, spec, tokens);
+  const roles = Array.isArray(c.roles) ? c.roles : [];
+  const draws = Array.isArray(c.draws) ? c.draws : [];
+  const perPoint = sliced
+    || (data.series.length === 1 && data.categories.length > 1 && (
+      (roles.length === data.categories.length && new Set(roles).size > 1)
+      || (draws.length === data.categories.length && new Set(draws).size > 1)));
+  const count = perPoint ? data.categories.length : data.series.length;
+  const paints = palette ? paintsFor(roles, count, palette) : [];
+  const styled = paints.length > 0 || draws.some(hollow) || draws.some((d) => DASH[d]);
+  const seriesStyle = styled
+    ? perPoint
+      ? [{ points: Array.from({ length: count }, (_, idx) => ({ idx, ...markStyle(paints[idx], draws[idx]) })).filter((p) => Object.keys(p).length > 1) }]
+      : data.series.map((_, i) => (["line", "scatter"].includes(type) ? lineStyle(paints[i], draws[i]) : markStyle(paints[i], draws[i])))
+    : [];
+  // Labels are what the image labels. Values ride on the marks only where the
+  // image labels every value — and not where texts of their own already carry
+  // them (x67 QBR 3: a donut's centre read "48%", the chart printed "48" and
+  // "52" on its slices as well) — in the format the image sets them in.
+  // Categories show where the image names them. A spec without observed
+  // labels keeps the size rule alone.
+  // Texts the image drew as the chart's own legend, value or category labels are
+  // folded back into the chart (chart-labels.mjs); they are labels it shows.
+  const seen = Array.isArray(c.labels) || folded.texts?.length ? [...(c.labels ?? []), ...(folded.texts ?? [])].map(String) : null;
+  const inside = (o) => o !== e && o.text != null && o.x >= e.x - 2 && o.y >= e.y - 2 && o.x + o.w <= e.x + e.w + 2 && o.y + o.h <= e.y + e.h + 2;
+  const values = data.series.flatMap((sr) => sr.values).filter(Number.isFinite);
+  const texts = (spec.elements ?? []).filter(inside).map((o) => num(o.text));
+  const showValues = folded.values === true || (!small && (!seen || (values.every((v) => seen.some((t) => near(num(t), v))) && !values.some((v) => texts.some((t) => near(t, v))))));
+  const showCategories = folded.categories === true || (!small && (!seen || data.categories.some((cat) => cat && seen.some((t) => t.trim().toLowerCase() === String(cat).trim().toLowerCase()))));
+  // A category name ("Q3", "2024") carries a figure too; it is no value label.
+  const isCategory = (t) => data.categories.some((cat) => cat && String(cat).trim().toLowerCase() === t.trim().toLowerCase());
+  const format = showValues && seen ? labelNumberFormat(values, seen.filter((t) => !isCategory(t))) : null;
+  // A series the image names at one of its points (a target line's "Target
+  // 96.5%"): its last point carries its name and value, its other points none.
+  for (const s of folded.seriesLabels ?? []) {
+    const last = data.series[s]?.values.length - 1;
+    if (!(last >= 0)) continue;
+    seriesStyle[s] = seriesStyle[s] ?? {};
+    seriesStyle[s].labels = { show: false };
+    seriesStyle[s].points = [...(seriesStyle[s].points ?? []), { idx: last, label: { show: true, value: true, seriesName: true, separator: " ", ...(type === "line" ? { position: "right" } : {}), ...(format ? { numberFormat: format } : {}) } }];
+  }
+  const labels = `{ show: ${showValues}, value: ${showValues}${format ? `, numberFormat: ${q(format)}` : ""} }`;
+  // Mockup charts are labelled, not gridded: values ride on the marks, so the
+  // value axis and every gridline stay off (x55 QBR 2: default axes and
+  // gridlines read as "default-style plots") — unless the image paints the
+  // axis with its ticks, or cuts it (valueAxisOf).
+  const value = sliced ? null : valueAxisOf(c, Math.min(...values.map((v) => (["line", "scatter", "area"].includes(type) ? v : Math.max(v, 0)))), notes, e.id) ?? { visible: false, majorGridlines: false };
+  const axes = sliced ? "" : ` axes={${JSON.stringify({ category: { visible: showCategories, majorGridlines: false }, value })}}`;
+  const legend = legendOf(c, type, data.series.length, small, data.categories);
+  // A pie's slices vary: its legend then lists the slices, not the one series
+  // (`c:varyColors` 0 gives a single "Spend mix" entry, x108 cloud 5).
+  // A doughnut's hole holds what stands in it (chart-hole.mjs).
+  const hole = type === "doughnut" ? holeSizeFor(spec, e) : null;
+  if (hole && !hole.fits) notes.push(`chart ${e.id}: what stands in its hole is wider than the widest hole a doughnut draws (90% of the ring) — it runs onto the ring; make it smaller or the ring larger`);
+  const layout = sliced ? ` layout={{ varyColors: true${hole ? `, holeSize: ${hole.size}` : ""} }}` : "";
+  const style = seriesStyle.length ? ` seriesStyle={${JSON.stringify(seriesStyle.map((x) => x ?? {}))}}` : "";
+  const plot = sliced ? ringPlot(e, hole != null && !legend.show) : null;
+  const plotArea = plot ? ` plotArea={{ layout: ${JSON.stringify(plot)} }}` : "";
+  return `<B ${base} h={${e.h}}><Chart type=${q(type)} data={${JSON.stringify(data)}}${axes} labels={${labels}} legend={{ show: ${legend.show}, pos: ${q(legend.pos)} }}${layout}${plotArea}${style} style={{ width: ${e.w}, height: ${e.h} }} /></B>`;
+}
+
+/**
+ * Where a pie or doughnut draws its ring, as the plot area's manual layout
+ * (fractions of the chart's frame): where its frame grew to hold its folded
+ * legend or labels (chart-labels.mjs `folded.frame`), the ring stays the size
+ * and place the image painted it — left to PowerPoint, the ring shrinks and
+ * moves beside the native legend (x114 QBR 3: the globe in the hole sat on the
+ * ring's edge); and a ring with something in its hole and no legend (`whole`)
+ * fills its frame, so the hole is the size `holeSizeFor` gave it. null
+ * otherwise: PowerPoint lays the ring out.
+ */
+function ringPlot(e, whole = false) {
+  const ring = ringRect(e);
+  if (ring.x === e.x && ring.y === e.y && ring.w === e.w && ring.h === e.h && !whole) return null;
+  if (!(e.w > 0 && e.h > 0 && ring.w > 0 && ring.h > 0)) return null;
+  const f = (v) => Math.round(Math.min(1, Math.max(0, v)) * 10000) / 10000;
+  return { x: f((ring.x - e.x) / e.w), y: f((ring.y - e.y) / e.h), w: f(ring.w / e.w), h: f(ring.h / e.h) };
+}
+
+/**
+ * A pie's slice names as its legend rows read them, with each slice's value
+ * where every row carries it ("DE–PL lane" + "21%" -> "DE–PL lane 21%"); null
+ * when the rows name the slices alone.
+ */
+function legendWithValues(data, texts) {
+  const values = data.series[0]?.values ?? [];
+  const rows = data.categories.map((cat, i) => {
+    const name = labelKey(cat);
+    for (const t of texts) {
+      const key = labelKey(t);
+      if (!name || !key.startsWith(`${name} `)) continue;
+      const rest = String(t).replace(/\s+/g, " ").trim().slice(String(cat).replace(/\s+/g, " ").trim().length).trim();
+      if (onlyFigure(rest) && Math.abs(Math.abs(figureOf(rest)) - Math.abs(values[i])) <= 0.051 + Math.abs(values[i]) * 0.005) return `${String(cat).trim()} ${rest}`;
+    }
+    return null;
+  });
+  return rows.every(Boolean) ? rows : null;
+}