slidemind 0.3.19 → 0.4.0

package/src/builders/chart-labels.mjs

@@ -0,0 +1,326 @@
+// A chart's own labelling drawn as separate elements — a legend of swatch and
+// name rows, value labels set beside the bars, category names under the axis —
+// belongs to the chart, and the chart draws it natively. x111 QBR 3 drew its
+// doughnut's legend as four texts ("DE–PL lane  21%"); x108 cloud 5 as swatch,
+// figure and name in three boxes per row; x110 QBR 2 set every category and
+// value of its bridge beside it as text. Built so, they are boxes that drift
+// from the data and that nobody can edit with it.
+//
+// Folded here, before any layout, on declaration and evidence, never on
+// geometry: the elements the reader declared the chart's own (`chart.owns`),
+// and texts whose words ARE the chart's data — a category name (alone, or with
+// that category's value), a series name of a chart with more than one series,
+// or a figure the reader listed among the chart's labels that equals one of
+// its values. A legend row's key (the wordless parts of a declared stack row
+// whose text folded) goes with it. The chart is told what it now draws itself
+// (`chart.folded`) and chart-jsx.mjs switches its legend, category labels and
+// value labels on. What a doughnut paints inside its hole is the chart's own
+// content, not its labelling: claimed first (chart-hole.mjs), never folded.
+import { claimHoles, holeMembers } from "./chart-hole.mjs";
+import { nativeChartData } from "./concept-geometry.mjs";
+
+const TEXT = new Set(["text", "number"]);
+// Marks a legend draws beside its names: a swatch, a dot, a tick.
+const KEY = new Set(["shape", "disc", "badge", "rule", "bar", "icon"]);
+// What a short label may carry beside its figure: a sign, a unit.
+const UNIT = /^[\s%‰$€£¥+\-−–(),.:]*(?:pp|pts?|bn|mn|[kmb]|x|×)?[\s%‰$€£¥+\-−–(),.:]*$/i;
+
+/** A label's words as compared: no list glyph, one space, no trailing colon, any case. */
+export function labelKey(text) {
+  return String(text ?? "")
+    .replace(/^[\s•·▪◦‣■□●○◆◇▶►✓✔✗-]+/u, "")
+    .replace(/\s+/g, " ")
+    .trim()
+    .replace(/:$/, "")
+    .toLowerCase();
+}
+
+// The one figure a short label carries, as a number: "21%" 21, "$610k" 610,
+// "−1.1 pp" -1.1, "1,200" 1200, "95,4" 95.4. Null for none or several.
+export function figureOf(text) {
+  const found = String(text ?? "").match(/[-+−]?\d[\d.,\s]*\d|[-+−]?\d/g);
+  if (!found || found.length !== 1) return null;
+  let digits = found[0].replace(/\s/g, "").replace("−", "-").replace("+", "");
+  if (/^-?\d{1,3}(,\d{3})+(\.\d+)?$/.test(digits)) digits = digits.replace(/,/g, "");
+  else if (/^-?\d{1,3}(\.\d{3})+(,\d+)?$/.test(digits)) digits = digits.replace(/\./g, "").replace(",", ".");
+  else digits = digits.replace(",", ".");
+  const value = Number(digits);
+  return Number.isFinite(value) ? value : null;
+}
+
+const sameValue = (a, v) => a != null && Number.isFinite(v) && Math.abs(Math.abs(a) - Math.abs(v)) <= 0.051 + Math.abs(v) * 0.005;
+
+// A label that says nothing but its figure (and a sign or unit).
+export const onlyFigure = (text) => figureOf(text) != null && UNIT.test(String(text).replace(/[-+−]?\d[\d.,\s]*\d|[-+−]?\d/, ""));
+
+/**
+ * What one text is to one chart, from its words alone, or null: `as` "legend"
+ * (a slice's or a series' name), "category" (a category name of a plotted
+ * chart) or "value" (a figure among the chart's labels that equals one of its
+ * values); `value` true when a name carries its own value beside it.
+ */
+export function chartLabelOf(text, chart, data, { declared = false } = {}) {
+  const key = labelKey(text);
+  if (!key) return null;
+  const sliced = ["pie", "doughnut"].includes(chart.type);
+  const named = sliced ? "legend" : "category";
+  const valuesAt = (i) => data.series.map((s) => s.values[i]);
+  for (const [i, category] of data.categories.entries()) {
+    const name = labelKey(category);
+    if (!name) continue;
+    if (key === name) return { as: named, value: false };
+    for (const rest of [key.startsWith(`${name} `) ? key.slice(name.length) : null, key.endsWith(` ${name}`) ? key.slice(0, -name.length) : null]) {
+      if (rest != null && onlyFigure(rest) && valuesAt(i).some((v) => sameValue(figureOf(rest), v))) return { as: named, value: true };
+    }
+  }
+  if (data.series.length > 1 && data.series.some((s) => labelKey(s.name) === key)) return { as: "legend", value: false };
+  // A series named at one of its own points, with that point's value: a
+  // target line's "Target 96.5%" (x113 QBR 3). The chart labels the series'
+  // last point with its name and value.
+  for (const [s, series] of data.series.entries()) {
+    const name = labelKey(series.name);
+    const rest = name && key.startsWith(`${name} `) ? key.slice(name.length) : null;
+    if (rest != null && onlyFigure(rest) && series.values.some((v) => sameValue(figureOf(rest), v))) return { as: "series", value: true, series: s };
+  }
+  const listed = declared || (chart.labels ?? []).some((l) => labelKey(l) === key);
+  if (listed && onlyFigure(text) && data.series.some((s) => s.values.some((v) => sameValue(figureOf(text), v)))) return { as: "value", value: true };
+  return null;
+}
+
+// A figure's format: its words and signs around the digits ("21%" and "52%"
+// are one format, "9" another).
+const formatOf = (text) => String(text).replace(/[-+−]?\d[\d.,\s]*\d|[-+−]?\d/, "#").replace(/\s+/g, "").toLowerCase();
+
+/**
+ * Which of `texts` are one chart's own labelling, each as `chartLabelOf` says
+ * or null — judged as sets, because a legend, an axis and a row of value
+ * labels are sets: names count only when they cover at least two and at least
+ * half of the chart's categories (or series) — one name alone is a heading or a
+ * callout (x107 QBR 3: "On-time delivery" over a two-series chart) — and
+ * figures only as one format labelling every point of a series (x111 GTM 1:
+ * "9%", "27%", "12%" — not the unrelated "9" beside them). `declared`
+ * (indices) are the reader's: they count alone.
+ */
+export function chartLabelling(texts, chart, data, { declared = new Set() } = {}) {
+  const out = texts.map((t, i) => chartLabelOf(t, chart, data, { declared: declared.has(i) }));
+  const nameOf = (t) => {
+    const key = labelKey(t);
+    const i = data.categories.findIndex((c) => { const n = labelKey(c); return n && (key === n || key.startsWith(`${n} `) || key.endsWith(` ${n}`)); });
+    return i >= 0 ? `c${i}` : `s${data.series.findIndex((s) => labelKey(s.name) === key)}`;
+  };
+  // A typed legend or axis covers most of what it names: at least two of the
+  // chart's categories (series) and at least half of them. Two of a bridge's
+  // six category names under two KPI figures are captions (x112 QBR 2:
+  // "actual", "plan" beside "18.6%" and "19.5%").
+  out.forEach((l, i) => { if (l?.as === "series" && !declared.has(i)) out[i] = null; });
+  const named = new Set(out.map((l, i) => (l && l.as !== "value" && !declared.has(i) ? nameOf(texts[i]) : null)).filter(Boolean));
+  const covers = (prefix, total) => { const n = [...named].filter((k) => k.startsWith(prefix)).length; return n >= 2 && n >= Math.ceil(total / 2); };
+  const categoriesSet = covers("c", data.categories.filter((c) => labelKey(c)).length);
+  const seriesSet = covers("s", data.series.length);
+  out.forEach((l, i) => {
+    if (!l || l.as === "value" || declared.has(i)) return;
+    if (!(nameOf(texts[i]).startsWith("c") ? categoriesSet : seriesSet)) out[i] = null;
+  });
+  const groups = new Map();
+  out.forEach((l, i) => { if (l?.as === "value" && !declared.has(i)) groups.set(formatOf(texts[i]), [...(groups.get(formatOf(texts[i])) ?? []), i]); });
+  for (const members of groups.values()) {
+    const set = new Set((seriesLabelSet(members.map((i) => texts[i]), data) ?? []).map((k) => members[k]));
+    for (const i of members) if (!set.has(i)) out[i] = null;
+  }
+  return out;
+}
+
+/**
+ * Fold every native chart's own labelling into the chart (see the header).
+ * Mutates `spec`: drops the folded elements, prunes the structures that named
+ * them (stacks, grids, repeats, connectors), records `chart.folded` and says
+ * what it did in `notes` (default `spec.notes`). Idempotent.
+ */
+export function foldChartLabels(spec, notes = null) {
+  const elements = spec.elements ?? [];
+  const charts = elements.filter((e) => e.kind === "chart" && e.w > 0 && e.h > 0 && nativeChartData(e.chart));
+  if (!charts.length) return spec;
+  const said = notes ?? (spec.notes ??= []);
+  const say = (note) => { if (!said.includes(note)) said.push(note); };
+  for (const note of claimHoles(spec)) say(note);
+  const inHole = holeMembers(elements);
+  const byId = new Map(elements.map((e) => [e.id, e]));
+  const parents = new Set(elements.map((e) => e.parent).filter(Boolean));
+  const ancestors = (e) => { const out = new Set(); for (let p = byId.get(e.parent); p && !out.has(p.id); p = byId.get(p.parent)) out.add(p.id); return out; };
+  const rows = (spec.stacks ?? []).flatMap((s) => s.rows ?? []);
+  const gone = new Set();
+  // Which chart the reader declared each element the own labelling of: a text
+  // another chart owns is never this chart's, however its words read (x113 QBR
+  // 1: eight mini charts with the same "Q2"/"Q3" names — the first took every
+  // card's category labels and the other seven drew none).
+  const ownerOf = new Map();
+  for (const c of charts) for (const id of Array.isArray(c.chart.owns) ? c.chart.owns : []) if (!ownerOf.has(id)) ownerOf.set(id, c.id);
+  for (const c of charts) {
+    const data = nativeChartData(c.chart);
+    const own = ancestors(c);
+    const foldable = (e) => e && !gone.has(e.id) && e !== c && e.kind !== "chart" && !own.has(e.id) && !parents.has(e.id) && !inHole.has(e.id)
+      && (ownerOf.get(e.id) ?? c.id) === c.id
+      // Undeclared, a text is this chart's only where it shares the chart's
+      // container — beside several charts, words alone do not say whose.
+      && (ownerOf.has(e.id) || charts.length === 1 || !c.parent || ancestors(e).has(c.parent));
+    const before = c.chart.folded ?? {};
+    const folded = { legend: !!before.legend, categories: !!before.categories, values: !!before.values, side: before.side ?? null, texts: [...(before.texts ?? [])], ids: [...(before.ids ?? [])], ...(before.axis ? { axis: before.axis } : {}), ...(before.seriesLabels ? { seriesLabels: [...before.seriesLabels] } : {}), ...(before.frame ? { frame: before.frame } : {}) };
+    const take = (e, label) => {
+      gone.add(e.id);
+      folded.ids.push(e.id);
+      if (e.text != null) folded.texts.push(String(e.text));
+      if (label?.as === "legend") folded.legend = true;
+      if (label?.as === "category") folded.categories = true;
+      if (label?.as === "series") folded.seriesLabels = [...new Set([...(folded.seriesLabels ?? []), label.series])];
+      if (label?.value) folded.values = folded.values || label.as !== "series";
+    };
+    const declared = new Set(Array.isArray(c.chart.owns) ? c.chart.owns : []);
+    // The texts: those whose words are this chart's own data — the reader's
+    // declaration names them first, the evidence finds the rest. A declared
+    // text whose words are not the chart's data stays, and is said.
+    const candidates = elements.filter((e) => foldable(e) && TEXT.has(e.kind) && e.text != null);
+    const labels = chartLabelling(candidates.map((e) => String(e.text)), c.chart, data, {
+      declared: new Set(candidates.map((e, i) => (declared.has(e.id) ? i : -1)).filter((i) => i >= 0)),
+    });
+    // A declared run of figures that are not the chart's data but step evenly
+    // through one format is its value axis, painted with its ticks (x113 QBR 3:
+    // 94.5% … 97.0% beside the line): the chart draws that axis natively.
+    const dataValues = data.series.flatMap((s) => s.values).filter(Number.isFinite);
+    const ticks = axisTicks(candidates.filter((e) => declared.has(e.id)), dataValues);
+    if (ticks) {
+      for (const e of ticks.elements) take(e, null);
+      folded.axis = ticks.axis;
+    }
+    candidates.forEach((e, i) => {
+      if (ticks?.elements.includes(e)) return;
+      if (labels[i]) take(e, labels[i]);
+      else if (declared.has(e.id)) say(`chart ${c.id}: ${e.id} was declared the chart's own, but "${String(e.text).slice(0, 40)}" is not its data (a category, a series or one of its values) — kept as text`);
+    });
+    // A legend's keys go with its names: the wordless marks the reader declared
+    // the chart's, and those in a declared stack row whose text folded.
+    if (folded.legend) {
+      const inRow = new Set(rows.filter((row) => row.some((id) => folded.ids.includes(id))).flat());
+      for (const e of elements) {
+        if (foldable(e) && KEY.has(e.kind) && e.text == null && (declared.has(e.id) || inRow.has(e.id))) take(e, null);
+      }
+    }
+    // Where the image drew the legend rows: the side of the chart they stand on.
+    const legendTexts = folded.ids.map((id) => byId.get(id)).filter((e) => e && e.text != null && [e.x, e.y, e.w, e.h].every(Number.isFinite));
+    if (folded.legend && legendTexts.length && !folded.side) {
+      const cx = legendTexts.reduce((a, e) => a + e.x + e.w / 2, 0) / legendTexts.length;
+      const cy = legendTexts.reduce((a, e) => a + e.y + e.h / 2, 0) / legendTexts.length;
+      folded.side = cy >= c.y + c.h ? "bottom" : cy <= c.y ? "top" : cx <= c.x ? "left" : "right";
+    }
+    // The chart's frame holds its own labelling: the boxes the folded legend
+    // rows, axis and value labels were drawn in join the chart's (x113 QBR 3:
+    // a 190px doughnut whose legend stood beside it shrank to a dot once the
+    // legend was drawn inside its frame).
+    const newly = folded.ids.slice((before.ids ?? []).length).map((id) => byId.get(id)).filter((e) => e && [e.x, e.y, e.w, e.h].every(Number.isFinite));
+    if (newly.length) {
+      const x0 = Math.min(c.x, ...newly.map((e) => e.x));
+      const y0 = Math.min(c.y, ...newly.map((e) => e.y));
+      const x1 = Math.max(c.x + c.w, ...newly.map((e) => e.x + e.w));
+      const y1 = Math.max(c.y + c.h, ...newly.map((e) => e.y + e.h));
+      if (x0 < c.x || y0 < c.y || x1 > c.x + c.w || y1 > c.y + c.h) {
+        folded.frame = { from: { x: c.x, y: c.y, w: c.w, h: c.h } };
+        Object.assign(c, { x: x0, y: y0, w: x1 - x0, h: y1 - y0 });
+      }
+    }
+    if (folded.ids.length > (before.ids ?? []).length) {
+      const drawn = [folded.legend && "legend", folded.categories && "category labels", folded.values && "value labels"].filter(Boolean);
+      say(`chart ${c.id}: ${folded.ids.join(", ")} drew the chart's own ${drawn.join(" and ") || "labelling"} beside it — folded into the chart, which shows ${drawn.length ? "them" : "it"} natively`);
+    }
+    c.chart.folded = folded;
+  }
+  if (!gone.size) return spec;
+  spec.elements = elements.filter((e) => !gone.has(e.id));
+  pruneStructures(spec, gone);
+  return spec;
+}
+
+/**
+ * A value axis painted with its tick labels, among a chart's declared figures:
+ * the longest run of at least three in one format that step evenly (94.5% 95.0%
+ * … 97.0% beside the value labels 95.4% 95.9% 96.2%), of which at least two are
+ * not the chart's data — evenly spaced value labels (10 20 30) are labels, not
+ * an axis. Returns the run's elements and the axis (`min`, `max`, `step`, the
+ * ticks' `format` as an Excel number format), or null.
+ */
+export function axisTicks(elements, dataValues = []) {
+  const figures = elements.filter((e) => onlyFigure(e.text)).map((e) => ({ e, v: figureOf(e.text), f: formatOf(e.text) }));
+  let best = null;
+  for (const f of new Set(figures.map((x) => x.f))) {
+    const same = figures.filter((x) => x.f === f);
+    const values = [...new Set(same.map((x) => x.v))].sort((a, b) => a - b);
+    for (let i = 0; i < values.length; i++) {
+      for (let j = i + 1; j < values.length; j++) {
+        const step = values[j] - values[i];
+        const at = (v) => same.find((x) => Math.abs(x.v - v) <= step * 1e-3);
+        const run = [];
+        for (let k = 0; at(values[i] + k * step); k++) run.push(at(values[i] + k * step));
+        // A tick IS a data value only at the tick's own precision (95.0% is not
+        // the value 95.4).
+        const isData = (x) => { const dec = (/[.,](\d+)\D*$/.exec(String(x.e.text))?.[1] ?? "").length; return dataValues.some((d) => Math.abs(x.v - d) <= 0.5 * 10 ** -dec + 1e-9); };
+        if (run.length < 3 || run.filter((x) => !isData(x)).length < 2) continue;
+        if (!best || run.length > best.run.length) best = { run, step };
+      }
+    }
+  }
+  if (!best) return null;
+  const { run, step } = best;
+  const sample = String(run[0].e.text).trim();
+  const decimals = (/[.,](\d+)/.exec(sample.replace(/^[^\d]*/, ""))?.[1] ?? "").length;
+  const [pre, post] = sample.split(/[-+−]?\d[\d.,\s]*\d|[-+−]?\d/).map((s) => s.trim().replace(/"/g, ""));
+  const body = `0${decimals ? `.${"0".repeat(decimals)}` : ""}`;
+  const format = pre || post || decimals ? `${pre ? `"${pre}"` : ""}${body}${post ? `"${post}"` : ""}` : null;
+  const round = (v) => Number(v.toFixed(decimals + 2));
+  return { elements: run.map((x) => x.e), axis: { min: round(run[0].v), max: round(run[run.length - 1].v), step: round(step), ...(format ? { format } : {}) } };
+}
+
+/**
+ * The indices of `texts` that label every value of one series, one text per
+ * value (the first series they cover), or null. Spare copies of a value (a
+ * doughnut's centre "58%" beside its legend's "58%") are not part of the set.
+ */
+export function seriesLabelSet(texts, data) {
+  for (const series of data.series) {
+    if (!series.values.length) continue;
+    const free = texts.map((t, i) => i);
+    const picked = [];
+    const complete = series.values.every((v) => {
+      const k = free.findIndex((i) => sameValue(figureOf(texts[i]), v));
+      if (k < 0) return false;
+      picked.push(free[k]);
+      free.splice(k, 1);
+      return true;
+    });
+    if (complete) return picked;
+  }
+  return null;
+}
+
+/** Whether `texts` carry every value of at least one series, one text each. */
+export const labelsEverySeriesPoint = (texts, data) => seriesLabelSet(texts, data) != null;
+
+// The structures that named a folded element follow it: a stack row loses it
+// (an empty row goes, a stack of fewer than two rows goes, and a grid whose
+// column lost its stack), a repeat member loses it, a connector to it goes.
+function pruneStructures(spec, gone) {
+  if (Array.isArray(spec.stacks)) {
+    spec.stacks = spec.stacks
+      .map((s) => ({ ...s, rows: (s.rows ?? []).map((r) => r.filter((id) => !gone.has(id))).filter((r) => r.length) }))
+      .filter((s) => s.rows.length >= 2);
+  }
+  if (Array.isArray(spec.grids)) {
+    const stackOf = (col) => (spec.stacks ?? []).find((s) => s.parent === col);
+    spec.grids = spec.grids.filter((g) => (g.columns ?? []).every((col) => stackOf(col)?.rows.length === g.rows));
+  }
+  if (Array.isArray(spec.repeats)) {
+    spec.repeats = spec.repeats
+      .map((g) => ({ ...g, members: (g.members ?? []).map((m) => (Array.isArray(m) ? m.filter((id) => !gone.has(id)) : gone.has(m) ? null : m)).filter((m) => m != null && (!Array.isArray(m) || m.length)) }))
+      .filter((g) => g.members.length >= 2);
+  }
+  if (Array.isArray(spec.connectors)) {
+    spec.connectors = spec.connectors.filter((x) => !gone.has(x.from) && !gone.has(x.to));
+  }
+}