@colixsystems/widget-sdk 0.245.0 → 0.247.0

package/dist/chart-logic.js

@@ -0,0 +1,575 @@
+// The geometry `<Chart>` draws, as plain numbers and SVG path strings. No
+// React and no renderer, so both hosts draw the same marks and node tests
+// can pin them.
+
+export const CHART_TYPES = Object.freeze(["bar", "hbar", "line", "area", "donut", "sparkline"]);
+export const DEFAULT_CHART_TYPE = "bar";
+export const DEFAULT_CHART_HEIGHT = 220;
+export const DEFAULT_SPARKLINE_HEIGHT = 48;
+export const VALUE_FORMATS = Object.freeze(["number", "compact", "percent"]);
+
+// The single series a chart draws when the caller names none.
+export const DEFAULT_SERIES_KEY = "value";
+// A screen reader hears at most this many values, over all series.
+export const SPOKEN_VALUES_MAX = 24;
+/** The tail of a cut-short spoken list, until a widget passes `moreText`. */
+export const DEFAULT_MORE_TEXT = (count) => `and ${count} more`;
+
+const TYPE_NAMES = Object.freeze({
+  bar: "Bar chart",
+  hbar: "Horizontal bar chart",
+  line: "Line chart",
+  area: "Area chart",
+  donut: "Donut chart",
+  sparkline: "Sparkline",
+});
+
+// Average glyph width as a share of the font size, for fitting labels.
+const GLYPH_WIDTH = 0.58;
+const TICK_COUNT = 4;
+// A crowded axis keeps every n-th label once labels would shrink below this.
+const LABEL_MIN_CHARS = 6;
+const TICK_GAP = 6;
+const GROUP_SHARE = 0.72;
+const BAR_MAX_WIDTH = 48;
+const BAR_MIN_WIDTH = 2;
+const DONUT_HOLE = 0.62;
+const DOTS_MAX_POINTS = 24;
+const HBAR_LABEL_SHARE = 0.38;
+const HBAR_ROW_SHARE = 0.7;
+// A horizontal bar's label needs its line height; crowded rows label every n-th.
+const HBAR_LABEL_GAP = 4;
+
+export function normaliseChartType(type) {
+  return CHART_TYPES.includes(type) ? type : DEFAULT_CHART_TYPE;
+}
+
+/** The plot's height: a positive number, else the type's own default. */
+export function chartHeight(type, height) {
+  if (typeof height === "number" && Number.isFinite(height) && height > 0) return height;
+  return type === "sparkline" ? DEFAULT_SPARKLINE_HEIGHT : DEFAULT_CHART_HEIGHT;
+}
+
+function labelText(value) {
+  if (value === null || value === undefined) return "";
+  if (typeof value === "object" && typeof value.label === "string") return value.label;
+  return String(value);
+}
+
+function numberOrNull(value) {
+  if (value === null || value === undefined || value === "") return null;
+  const n = typeof value === "number" ? value : Number(value);
+  return Number.isFinite(n) ? n : null;
+}
+
+/**
+ * Turn `data` (and the optional `series`) into the labels and the value rows
+ * every chart type reads. Without `series` each item is `{ label, value }`;
+ * with it, each item carries one number per series key.
+ *
+ * @returns {{ labels: string[], series: Array<{ key: string, label: string, color?: string, values: Array<number|null> }> }}
+ */
+export function normaliseChartData(data, series) {
+  const rows = Array.isArray(data) ? data.filter((row) => row && typeof row === "object") : [];
+  const declared = Array.isArray(series)
+    ? series.filter((s) => s && typeof s === "object" && typeof s.key === "string" && s.key)
+    : [];
+  const lines = declared.length
+    ? declared.map((s) => ({
+        key: s.key,
+        label: labelText(s.label ?? s.key),
+        color: typeof s.color === "string" && s.color ? s.color : undefined,
+      }))
+    : [{ key: DEFAULT_SERIES_KEY, label: "", color: undefined }];
+  return {
+    labels: rows.map((row) => labelText(row.label)),
+    series: lines.map((line) => ({ ...line, values: rows.map((row) => numberOrNull(row[line.key])) })),
+  };
+}
+
+/** The values a donut draws: the first series, positive values only. */
+function donutValues(model) {
+  const first = model.series[0];
+  return first ? first.values.map((v) => (v !== null && v > 0 ? v : 0)) : [];
+}
+
+/** True when there is nothing to plot, so the chart shows its empty state. */
+export function isChartEmpty(model, type) {
+  if (!model || model.labels.length === 0) return true;
+  if (type === "donut") return donutValues(model).reduce((sum, v) => sum + v, 0) <= 0;
+  return !model.series.some((s) => s.values.some((v) => v !== null));
+}
+
+// `locale` is the app's language; an unknown one falls back to the device's.
+function localNumber(value, digits, locale) {
+  try {
+    return value.toLocaleString(locale, { maximumFractionDigits: digits });
+  } catch {
+    return String(Number(value.toFixed(digits)));
+  }
+}
+
+function compactNumber(value, locale) {
+  const abs = Math.abs(value);
+  for (const [size, suffix] of [
+    [1e12, "T"],
+    [1e9, "B"],
+    [1e6, "M"],
+    [1e3, "k"],
+  ]) {
+    if (abs >= size) return `${localNumber(value / size, abs / size < 10 ? 1 : 0, locale)}${suffix}`;
+  }
+  return localNumber(value, abs < 10 ? 2 : 1, locale);
+}
+
+/**
+ * One value as text. `format` is a function of the number, or `"number"`
+ * (default, grouped), `"compact"` (1.2k, 3M) or `"percent"`, which appends a
+ * percent sign to a value that is already a percentage (42 reads "42%"; it
+ * never multiplies by 100). Digits are grouped for `locale`, the app's language.
+ */
+export function formatChartValue(value, format, locale) {
+  if (typeof value !== "number" || !Number.isFinite(value)) return "";
+  if (typeof format === "function") {
+    try {
+      return String(format(value));
+    } catch {
+      return localNumber(value, 2, locale);
+    }
+  }
+  if (format === "compact") return compactNumber(value, locale);
+  if (format === "percent") return `${localNumber(value, 2, locale)}%`;
+  return localNumber(value, 2, locale);
+}
+
+/** An axis tick as text: compact unless the caller formats values itself. */
+export function formatChartTick(value, format, locale) {
+  if (typeof format === "function" || format === "percent") return formatChartValue(value, format, locale);
+  return compactNumber(value, locale);
+}
+
+function niceStep(raw) {
+  const power = 10 ** Math.floor(Math.log10(raw));
+  const fraction = raw / power;
+  const nice = fraction < 1.5 ? 1 : fraction < 3 ? 2 : fraction < 7 ? 5 : 10;
+  return nice * power;
+}
+
+function cleanFloat(value) {
+  return Number(value.toPrecision(12));
+}
+
+/**
+ * Round a value range out to "nice" tick values (0, 25, 50 …).
+ *
+ * @returns {{ min: number, max: number, ticks: number[] }}
+ */
+export function niceTicks(min, max, count = TICK_COUNT) {
+  let low = Number.isFinite(min) ? min : 0;
+  let high = Number.isFinite(max) ? max : 0;
+  if (low > high) [low, high] = [high, low];
+  if (low === high) {
+    if (low === 0) high = 1;
+    else if (low > 0) low = 0;
+    else high = 0;
+  }
+  const step = niceStep((high - low) / Math.max(1, count));
+  const niceMin = cleanFloat(Math.floor(low / step) * step);
+  const niceMax = cleanFloat(Math.ceil(high / step) * step);
+  const ticks = [];
+  for (let tick = niceMin; tick <= niceMax + step / 2; tick += step) ticks.push(cleanFloat(tick));
+  return { min: niceMin, max: niceMax, ticks };
+}
+
+/** Map `[d0, d1]` onto `[r0, r1]`; a zero-width domain maps to the middle. */
+export function linearScale(d0, d1, r0, r1) {
+  const span = d1 - d0;
+  if (!span) return () => (r0 + r1) / 2;
+  return (value) => r0 + ((value - d0) / span) * (r1 - r0);
+}
+
+function round(value) {
+  return Math.round(value * 100) / 100;
+}
+
+/**
+ * A line through the points, broken where a point is null (a missing value).
+ *
+ * @param {Array<{x:number,y:number}|null>} points
+ */
+export function linePath(points) {
+  let d = "";
+  let pen = false;
+  for (const point of points) {
+    if (!point) {
+      pen = false;
+      continue;
+    }
+    d += `${d ? " " : ""}${pen ? "L" : "M"} ${round(point.x)} ${round(point.y)}`;
+    pen = true;
+  }
+  return d;
+}
+
+/** The area under each unbroken run of points, closed down to `baseY`. */
+export function areaPath(points, baseY) {
+  const runs = [];
+  let run = [];
+  for (const point of points) {
+    if (point) run.push(point);
+    else if (run.length) {
+      runs.push(run);
+      run = [];
+    }
+  }
+  if (run.length) runs.push(run);
+  return runs
+    .map((part) => {
+      const first = part[0];
+      const last = part[part.length - 1];
+      const top = part.map((p) => `L ${round(p.x)} ${round(p.y)}`).join(" ");
+      return `M ${round(first.x)} ${round(baseY)} ${top} L ${round(last.x)} ${round(baseY)} Z`;
+    })
+    .join(" ");
+}
+
+/**
+ * A bar rounded only at its far end (`edge`: "top" | "bottom" | "right" |
+ * "left"), so it stands square on its baseline.
+ */
+export function barPath({ x, y, width, height }, radius, edge = "top") {
+  const across = edge === "top" || edge === "bottom" ? width : height;
+  const along = edge === "top" || edge === "bottom" ? height : width;
+  const r = Math.max(0, Math.min(radius || 0, across / 2, along));
+  const [x0, y0, x1, y1] = [x, y, x + width, y + height].map(round);
+  if (r <= 0) return `M ${x0} ${y0} L ${x1} ${y0} L ${x1} ${y1} L ${x0} ${y1} Z`;
+  const q = round(r);
+  const arc = (tx, ty) => `A ${q} ${q} 0 0 1 ${round(tx)} ${round(ty)}`;
+  if (edge === "top") {
+    return `M ${x0} ${y1} L ${x0} ${round(y + r)} ${arc(x + r, y)} L ${round(x + width - r)} ${y0} ${arc(x + width, y + r)} L ${x1} ${y1} Z`;
+  }
+  if (edge === "bottom") {
+    return `M ${x1} ${y0} L ${x1} ${round(y + height - r)} ${arc(x + width - r, y + height)} L ${round(x + r)} ${y1} ${arc(x, y + height - r)} L ${x0} ${y0} Z`;
+  }
+  if (edge === "right") {
+    return `M ${x0} ${y0} L ${round(x + width - r)} ${y0} ${arc(x + width, y + r)} L ${x1} ${round(y + height - r)} ${arc(x + width - r, y + height)} L ${x0} ${y1} Z`;
+  }
+  return `M ${x1} ${y1} L ${round(x + r)} ${y1} ${arc(x, y + height - r)} L ${x0} ${round(y + r)} ${arc(x + r, y)} L ${x1} ${y0} Z`;
+}
+
+function polar(cx, cy, r, angle) {
+  return { x: cx + r * Math.cos(angle), y: cy + r * Math.sin(angle) };
+}
+
+function circlePath(cx, cy, r, sweep) {
+  const top = `${round(cx)} ${round(cy - r)}`;
+  const bottom = `${round(cx)} ${round(cy + r)}`;
+  const q = round(r);
+  return `M ${top} A ${q} ${q} 0 1 ${sweep} ${bottom} A ${q} ${q} 0 1 ${sweep} ${top} Z`;
+}
+
+/** One ring segment from `start` to `end` (radians, 0 = 3 o'clock, clockwise). */
+export function ringSlicePath(cx, cy, outer, inner, start, end) {
+  if (end - start >= Math.PI * 2 - 1e-6) {
+    // A whole ring: the hole is cut out by the opposite winding.
+    return `${circlePath(cx, cy, outer, 1)} ${inner > 0 ? circlePath(cx, cy, inner, 0) : ""}`.trim();
+  }
+  const large = end - start > Math.PI ? 1 : 0;
+  const a = polar(cx, cy, outer, start);
+  const b = polar(cx, cy, outer, end);
+  const c = polar(cx, cy, inner, end);
+  const d = polar(cx, cy, inner, start);
+  const o = round(outer);
+  const i = round(inner);
+  return (
+    `M ${round(a.x)} ${round(a.y)} A ${o} ${o} 0 ${large} 1 ${round(b.x)} ${round(b.y)} ` +
+    `L ${round(c.x)} ${round(c.y)} A ${i} ${i} 0 ${large} 0 ${round(d.x)} ${round(d.y)} Z`
+  );
+}
+
+function estimateWidth(text, fontSize) {
+  return String(text).length * fontSize * GLYPH_WIDTH;
+}
+
+/** Shorten a label to fit `maxWidth`, ending it with an ellipsis. */
+export function fitLabel(text, maxWidth, fontSize) {
+  const value = String(text);
+  if (estimateWidth(value, fontSize) <= maxWidth) return value;
+  const chars = Math.max(1, Math.floor(maxWidth / (fontSize * GLYPH_WIDTH)) - 1);
+  return `${value.slice(0, chars)}…`;
+}
+
+function valueExtent(model) {
+  let min = Infinity;
+  let max = -Infinity;
+  for (const s of model.series) {
+    for (const v of s.values) {
+      if (v === null) continue;
+      if (v < min) min = v;
+      if (v > max) max = v;
+    }
+  }
+  return Number.isFinite(min) ? { min, max } : { min: 0, max: 0 };
+}
+
+// Bars and areas stand on zero; a line or sparkline shows its own range.
+function valueDomain(model, type) {
+  const { min, max } = valueExtent(model);
+  if (type === "line" || type === "sparkline") return { min, max };
+  return { min: Math.min(0, min), max: Math.max(0, max) };
+}
+
+// A bar's thickness: its share of the group, at least a hairline, never past its slot.
+function barThickness(groupSize, groups, slot) {
+  return Math.min(Math.max(BAR_MIN_WIDTH, groupSize / groups), slot / groups);
+}
+
+// Every n-th category label, so neighbouring labels never overlap.
+function labelStride(labels, slot, fontSize) {
+  const longest = labels.reduce((m, l) => Math.max(m, Math.min(String(l).length, LABEL_MIN_CHARS)), 1);
+  const needed = longest * fontSize * GLYPH_WIDTH + TICK_GAP;
+  return Math.max(1, Math.ceil(needed / Math.max(1, slot)));
+}
+
+function pointsFor(values, xAt, scale) {
+  return values.map((v, i) => (v === null ? null : { x: xAt(i), y: scale(v) }));
+}
+
+function verticalLayout({ type, width, height, model, fontSize, valueFormat, locale }) {
+  const sparkline = type === "sparkline";
+  const domain = valueDomain(model, type);
+  const nice = sparkline ? { ...domain, ticks: [] } : niceTicks(domain.min, domain.max);
+  const tickTexts = nice.ticks.map((t) => formatChartTick(t, valueFormat, locale));
+  const stroke = sparkline ? 2 : 0;
+  const left = sparkline ? stroke : Math.ceil(tickTexts.reduce((m, t) => Math.max(m, estimateWidth(t, fontSize)), 0)) + TICK_GAP;
+  const right = sparkline ? stroke : Math.ceil(fontSize / 2);
+  const top = sparkline ? stroke : Math.ceil(fontSize / 2) + 1;
+  const bottom = sparkline ? stroke : fontSize + TICK_GAP + 2;
+  const plotW = Math.max(1, width - left - right);
+  const plotH = Math.max(1, height - top - bottom);
+  const scale = linearScale(nice.min, nice.max, top + plotH, top);
+  const baseY = scale(Math.min(Math.max(0, nice.min), nice.max));
+  const count = model.labels.length;
+
+  const out = {
+    plot: { left, top, width: plotW, height: plotH },
+    gridLines: nice.ticks.map((t) => ({ x1: left, x2: left + plotW, y: round(scale(t)) })),
+    tickLabels: nice.ticks.map((t, i) => ({ x: left - TICK_GAP, y: round(scale(t) + fontSize / 3), text: tickTexts[i], anchor: "end" })),
+    baseline: sparkline ? null : { x1: left, x2: left + plotW, y: round(baseY) },
+    categoryLabels: [],
+    bars: [],
+    lines: [],
+    areas: [],
+    dots: [],
+  };
+
+  if (type === "bar") {
+    const slot = plotW / Math.max(1, count);
+    const groups = model.series.length;
+    const groupW = Math.min(slot * GROUP_SHARE, BAR_MAX_WIDTH * groups);
+    const barW = barThickness(groupW, groups, slot);
+    model.series.forEach((s, si) => {
+      s.values.forEach((v, i) => {
+        if (v === null) return;
+        const x = left + i * slot + (slot - barW * groups) / 2 + si * barW;
+        const y = scale(v);
+        const up = y <= baseY;
+        out.bars.push({
+          seriesIndex: si,
+          index: i,
+          rect: { x, y: up ? y : baseY, width: barW, height: Math.abs(baseY - y) },
+          edge: up ? "top" : "bottom",
+        });
+      });
+    });
+    const stride = labelStride(model.labels, slot, fontSize);
+    model.labels.forEach((label, i) => {
+      if (i % stride) return;
+      out.categoryLabels.push({
+        x: round(left + i * slot + slot / 2),
+        y: round(top + plotH + TICK_GAP + fontSize * 0.8),
+        text: fitLabel(label, slot * stride - TICK_GAP, fontSize),
+        anchor: "middle",
+      });
+    });
+    return out;
+  }
+
+  const xAt = count > 1 ? (i) => left + (i * plotW) / (count - 1) : () => left + plotW / 2;
+  model.series.forEach((s, si) => {
+    const points = pointsFor(s.values, xAt, scale);
+    out.lines.push({ seriesIndex: si, d: linePath(points) });
+    if (type === "area") out.areas.push({ seriesIndex: si, d: areaPath(points, baseY) });
+    if (sparkline) {
+      const last = [...points].reverse().find(Boolean);
+      if (last) out.dots.push({ seriesIndex: si, cx: round(last.x), cy: round(last.y) });
+    } else if (count <= DOTS_MAX_POINTS) {
+      points.forEach((p) => p && out.dots.push({ seriesIndex: si, cx: round(p.x), cy: round(p.y) }));
+    }
+  });
+  if (!sparkline) {
+    const slot = count > 1 ? plotW / (count - 1) : plotW;
+    const stride = labelStride(model.labels, slot, fontSize);
+    model.labels.forEach((label, i) => {
+      if (i % stride) return;
+      const first = i === 0 && count > 1;
+      const last = i === count - 1 && count > 1;
+      out.categoryLabels.push({
+        x: round(xAt(i)),
+        y: round(top + plotH + TICK_GAP + fontSize * 0.8),
+        text: fitLabel(label, Math.max(slot * stride - TICK_GAP, fontSize * 3), fontSize),
+        anchor: first ? "start" : last ? "end" : "middle",
+      });
+    });
+  }
+  return out;
+}
+
+function horizontalLayout({ width, height, model, fontSize, valueFormat, locale }) {
+  const domain = valueDomain(model, "hbar");
+  const nice = niceTicks(domain.min, domain.max);
+  const count = model.labels.length;
+  const longest = model.labels.reduce((m, l) => Math.max(m, estimateWidth(l, fontSize)), 0);
+  const left = Math.ceil(Math.min(longest, width * HBAR_LABEL_SHARE)) + TICK_GAP;
+  const lastTick = formatChartTick(nice.ticks[nice.ticks.length - 1], valueFormat, locale);
+  const right = Math.ceil(estimateWidth(lastTick, fontSize) / 2) + 2;
+  const top = 2;
+  const bottom = fontSize + TICK_GAP + 2;
+  const plotW = Math.max(1, width - left - right);
+  const plotH = Math.max(1, height - top - bottom);
+  const scale = linearScale(nice.min, nice.max, left, left + plotW);
+  const baseX = scale(Math.min(Math.max(0, nice.min), nice.max));
+  const slot = plotH / Math.max(1, count);
+  const groups = model.series.length;
+  const groupH = Math.min(slot * HBAR_ROW_SHARE, BAR_MAX_WIDTH * groups);
+  const barH = barThickness(groupH, groups, slot);
+  // The chart keeps its height, so rows thinner than a line of text label every n-th.
+  const stride = Math.max(1, Math.ceil((fontSize + HBAR_LABEL_GAP) / Math.max(slot, 1e-6)));
+  const out = {
+    plot: { left, top, width: plotW, height: plotH },
+    gridLines: nice.ticks.map((t) => ({ y1: top, y2: top + plotH, x: round(scale(t)) })),
+    tickLabels: nice.ticks.map((t) => ({ x: round(scale(t)), y: round(top + plotH + TICK_GAP + fontSize * 0.8), text: formatChartTick(t, valueFormat, locale), anchor: "middle" })),
+    baseline: { y1: top, y2: top + plotH, x: round(baseX) },
+    categoryLabels: model.labels.flatMap((label, i) =>
+      i % stride
+        ? []
+        : [{ x: left - TICK_GAP, y: round(top + i * slot + slot / 2 + fontSize / 3), text: fitLabel(label, left - TICK_GAP, fontSize), anchor: "end" }],
+    ),
+    bars: [],
+    lines: [],
+    areas: [],
+    dots: [],
+  };
+  model.series.forEach((s, si) => {
+    s.values.forEach((v, i) => {
+      if (v === null) return;
+      const x = scale(v);
+      const forward = x >= baseX;
+      out.bars.push({
+        seriesIndex: si,
+        index: i,
+        rect: { x: forward ? baseX : x, y: top + i * slot + (slot - barH * groups) / 2 + si * barH, width: Math.abs(x - baseX), height: barH },
+        edge: forward ? "right" : "left",
+      });
+    });
+  });
+  return out;
+}
+
+/**
+ * Everything a bar, horizontal bar, line, area or sparkline chart draws, in
+ * the pixel space of a `width` x `height` SVG.
+ */
+export function cartesianLayout({ type, width, height, model, fontSize = 12, valueFormat, locale }) {
+  const kind = normaliseChartType(type);
+  if (kind === "hbar") return horizontalLayout({ width, height, model, fontSize, valueFormat, locale });
+  return verticalLayout({ type: kind, width, height, model, fontSize, valueFormat, locale });
+}
+
+/** The ring segments of a donut, one per positive value of the first series. */
+export function donutLayout({ width, height, model }) {
+  const values = donutValues(model);
+  const total = values.reduce((sum, v) => sum + v, 0);
+  const size = Math.max(0, Math.min(width, height));
+  const cx = width / 2;
+  const cy = height / 2;
+  const outer = size / 2;
+  const inner = outer * DONUT_HOLE;
+  const slices = [];
+  let angle = -Math.PI / 2;
+  values.forEach((v, index) => {
+    if (v <= 0 || total <= 0) return;
+    const sweep = (v / total) * Math.PI * 2;
+    slices.push({ index, d: ringSlicePath(cx, cy, outer, inner, angle, angle + sweep), share: v / total });
+    angle += sweep;
+  });
+  return { cx, cy, outer, inner, total, slices };
+}
+
+function spokenValues(labels, values, { format, locale, moreText, budget }) {
+  const said = [];
+  values.forEach((v, i) => {
+    if (v === null || said.length >= budget) return;
+    said.push(`${labels[i]} ${formatChartValue(v, format, locale)}`.trim());
+  });
+  const shown = values.filter((v) => v !== null).length;
+  const rest = shown - said.length;
+  return rest > 0 ? `${said.join(", ")}, ${moreText(rest)}` : said.join(", ");
+}
+
+function highest(labels, values) {
+  let best = -1;
+  values.forEach((v, i) => {
+    if (v !== null && (best === -1 || v > values[best])) best = i;
+  });
+  return best === -1 ? null : { label: labels[best], value: values[best] };
+}
+
+function plural(count, one, many) {
+  return `${count} ${count === 1 ? one : many}`;
+}
+
+/**
+ * What a screen reader hears: a one-line summary, then the values, at most
+ * `SPOKEN_VALUES_MAX` of them over all series. `lead` replaces the summary (a
+ * widget passes its translated title there) and `moreText(count)` the tail
+ * of a list cut short, so a widget can say both in the app's language.
+ */
+export function chartSummary({ type, model, valueFormat, lead, locale, moreText }) {
+  const kind = normaliseChartType(type);
+  const name = TYPE_NAMES[kind];
+  const labels = model.labels;
+  const tail = typeof moreText === "function" ? moreText : DEFAULT_MORE_TEXT;
+  const say = (values, budget = SPOKEN_VALUES_MAX) =>
+    spokenValues(labels, values, { format: valueFormat, locale, moreText: tail, budget });
+  const value = (v) => formatChartValue(v, valueFormat, locale);
+  if (kind === "donut") {
+    const values = donutValues(model).map((v) => (v > 0 ? v : null));
+    const total = values.reduce((sum, v) => sum + (v || 0), 0);
+    const top = highest(labels, values);
+    const share = top && total > 0 ? Math.round((top.value / total) * 100) : 0;
+    const summary = top
+      ? `${name}, ${plural(values.filter((v) => v !== null).length, "slice", "slices")}, largest: ${top.label} ${value(top.value)} (${share}%)`
+      : name;
+    return `${lead || summary}. ${say(values)}`;
+  }
+  if (model.series.length > 1) {
+    let best = null;
+    for (const s of model.series) {
+      const top = highest(labels, s.values);
+      if (top && (!best || top.value > best.value)) best = { ...top, series: s.label };
+    }
+    const summary = best
+      ? `${name}, ${plural(model.series.length, "series", "series")} of ${plural(labels.length, "value", "values")}, highest: ${best.series}, ${best.label} ${value(best.value)}`
+      : name;
+    const each = Math.max(1, Math.floor(SPOKEN_VALUES_MAX / model.series.length));
+    const spoken = model.series.map((s) => `${s.label}: ${say(s.values, each)}`).join("; ");
+    return `${lead || summary}. ${spoken}`;
+  }
+  const values = model.series[0] ? model.series[0].values : [];
+  const top = highest(labels, values);
+  const summary = top
+    ? `${name}, ${plural(values.filter((v) => v !== null).length, "value", "values")}, highest: ${top.label} ${value(top.value)}`
+    : name;
+  return `${lead || summary}. ${say(values)}`;
+}