@pixerate/editor 0.162.1 → 0.164.0

package/dist/{chunk-XDCFJEU7.js → chunk-SZA42R4N.js}

@@ -7,27 +7,36 @@ import {
   r2,
   sameChartSelection,
   summarizeChartSeries
-} from "./chunk-DTSTNRPH.js";
+} from "./chunk-Z4P2RBMJ.js";
 import {
   CHART_TYPE_LABELS,
   DEFAULT_CHART_PALETTE,
   DEFAULT_CHART_THEME,
-  chartColorsByCategory,
   chartDataFromTable,
   chartFamily,
   chartSeriesColor,
   chartSliceColor,
+  chartSpecColorsByCategory,
+  chartTreeDepth,
+  chartTreeFromRows,
+  chartTreeFromTable,
+  chartTreeToRows,
   checkChartColors,
   cloneChartSeries,
   cloneChartSpec,
+  cloneChartTree,
   defaultChartAxis,
   describeChartErrorBars,
+  findChartTreeNode,
+  normalizeChartReferenceBand,
+  normalizeChartReferenceLine,
   normalizeChartSpec,
+  normalizeChartTree,
   normalizeChartTrendline,
   parseChartValue,
   shadeChartColor,
   uniqueChartSeriesId
-} from "./chunk-HLOKB7WW.js";
+} from "./chunk-3NEZJCBY.js";
 import {
   parseCsv,
   parseTsv
@@ -64,7 +73,7 @@ function splitOutside(text, sep) {
 }
 function chartMermaidFamily(spec) {
   const family = chartFamily(spec);
-  if (family === "pie" || family === "funnel" || family === "treemap") return "pie";
+  if (family === "pie" || family === "funnel" || family === "treemap" || family === "parliament" || family === "sunburst") return "pie";
   if (family === "radar") return "radar";
   return "xychart";
 }
@@ -430,7 +439,7 @@ function findMermaidCharts(text) {
 function summarizeChart(spec, size = { width: 640, height: 400 }, scene = layoutChart(spec, { ...size, selection: null })) {
   const visible = spec.series.filter((s) => !s.hidden);
   const series = visible.map((s) => summarizeChartSeries(s, spec.categories));
-  const colors = chartColorsByCategory(spec.type) ? spec.categories.map((_, i) => visible[0]?.pointColors?.[i] || chartSliceColor(spec, i)) : visible.map((s) => chartSeriesColor(spec, spec.series.indexOf(s)));
+  const colors = chartSpecColorsByCategory(spec) ? spec.categories.map((_, i) => visible[0]?.pointColors?.[i] || chartSliceColor(spec, i)) : visible.map((s) => chartSeriesColor(spec, spec.series.indexOf(s)));
   const check = checkChartColors(colors, { surface: scene.theme.surface.startsWith("var(") ? "#ffffff" : scene.theme.surface });
   const axis = (s, a) => s ? { min: s.domain[0], max: s.domain[1], ticks: [...s.ticks], ...s.logBase ? { logBase: s.logBase } : {}, ...a.reverse ? { reversed: true } : {} } : void 0;
   return {
@@ -454,14 +463,50 @@ function describeChart(spec, series = spec.series.filter((s) => !s.hidden).map((
   const fmt = (v) => v === null ? "blank" : formatChartNumber(v, format);
   const head = spec.title ? `${spec.title}: a ${kind} chart` : `A ${kind} chart`;
   if (!series.length || series.every((s) => s.count === 0)) return `${head} with no data.`;
-  if (family === "pie" || family === "funnel" || family === "treemap") {
+  if (family === "pie" || family === "funnel" || family === "treemap" || family === "sunburst") {
     const s = series[0];
     const total = s.sum ?? 0;
     const share = (v) => total && v !== null ? ` (${Math.round(v / total * 100)}%)` : "";
     parts.push(`${head} of ${s.name} across ${spec.categories.length} categories, totalling ${fmt(s.sum)}.`);
     parts.push(`The largest is ${s.maxAt} at ${fmt(s.max)}${share(s.max)}; the smallest is ${s.minAt} at ${fmt(s.min)}${share(s.min)}.`);
+    if (spec.tree.length) {
+      const depth = chartTreeDepth(spec.tree);
+      const items = chartTreeToRows(spec.tree).length;
+      parts.push(`The data is grouped ${depth} level${depth === 1 ? "" : "s"} deep with ${items} item${items === 1 ? "" : "s"}.`);
+    }
     return parts.join(" ");
   }
+  if (family === "parliament") {
+    const s = spec.series.find((x) => !x.hidden);
+    const seats = spec.categories.map((c, i) => ({ c, n: Math.max(0, Math.round(s.values[i] ?? 0)) }));
+    const total = seats.reduce((t, x) => t + x.n, 0);
+    const majority = spec.parliamentMajority ?? Math.floor(total / 2) + 1;
+    const largest = [...seats].sort((a, b) => b.n - a.n)[0];
+    const verdict = largest && largest.n >= majority ? `${largest.c} holds a majority with ${largest.n}` : `no group reaches the majority of ${majority}; the largest is ${largest?.c} with ${largest?.n}`;
+    return `${head} of ${total} seats across ${seats.length} groups: ${verdict}.`;
+  }
+  if (family === "slope") {
+    const [a, b] = spec.series.filter((x) => !x.hidden);
+    if (!b) return `${head} that needs a second series to compare against.`;
+    const moves = spec.categories.map((c, i) => ({ c, d: a.values[i] !== null && b.values[i] !== null ? b.values[i] - a.values[i] : null })).filter((m) => m.d !== null);
+    const up = moves.filter((m) => m.d > 0).length;
+    const down = moves.filter((m) => m.d < 0).length;
+    const top = [...moves].sort((x, y) => y.d - x.d);
+    const extremes = top.length ? ` The biggest rise is ${top[0].c} (${fmt(top[0].d)}); the biggest fall is ${top[top.length - 1].c} (${fmt(top[top.length - 1].d)}).` : "";
+    return `${head} from ${a.name} to ${b.name}: ${up} of ${moves.length} rose and ${down} fell.${extremes}`;
+  }
+  if (family === "likert") {
+    const answers = spec.series.filter((x) => !x.hidden);
+    const side = Math.floor(answers.length / 2);
+    const agree = spec.categories.map((c, i) => {
+      const vals = answers.map((x) => Math.max(0, x.values[i] ?? 0));
+      const total = vals.reduce((t, v) => t + v, 0);
+      return { c, share: total ? vals.slice(answers.length - side).reduce((t, v) => t + v, 0) / total : 0 };
+    });
+    const best = [...agree].sort((x, y) => y.share - x.share);
+    const pct = (v) => `${Math.round(v * 100)}%`;
+    return `${head} of ${spec.categories.length} questions with ${answers.length} answers from ${answers[0]?.name} to ${answers[answers.length - 1]?.name}. Most positive: ${best[0]?.c} (${pct(best[0]?.share ?? 0)}); least: ${best[best.length - 1]?.c} (${pct(best[best.length - 1]?.share ?? 0)}).`;
+  }
   if (family === "waterfall") {
     const s = spec.series.find((x) => !x.hidden);
     const steps = s.values.filter((v, i) => v !== null && Number.isFinite(v) && !/\b(sub)?total\b/i.test(spec.categories[i] ?? ""));
@@ -632,6 +677,10 @@ function chartPresetPatch(options) {
 }
 
 // src/chart/controller.ts
+function pointLists(s) {
+  const lists = [s.values, s.x, s.sizes, s.pointColors, s.callouts, s.errorBars?.plus, s.errorBars?.minus, s.xErrorBars?.plus, s.xErrorBars?.minus];
+  return lists.filter((l) => Array.isArray(l));
+}
 function sameChartJson(a, b) {
   if (a === b) return true;
   if (typeof a !== "object" || typeof b !== "object" || a === null || b === null) return Number.isNaN(a) && Number.isNaN(b);
@@ -861,13 +910,16 @@ var ChartController = class {
    * to the categories; all-or-nothing like `update`.
    */
   setData(data, options = {}) {
-    return this.update({ ...data.categories ? { categories: data.categories } : {}, ...data.series ? { series: data.series } : {} }, { label: options.label ?? "Edit chart data" });
+    const clear = (data.categories || data.series) && this.spec.tree.length ? { tree: [] } : {};
+    return this.update({ ...data.categories ? { categories: data.categories } : {}, ...data.series ? { series: data.series } : {}, ...clear }, { label: options.label ?? "Edit chart data" });
   }
   /**
    * Sets one value (numbers, numeric text such as `1,200` or `12%`, or blank for a gap).
    * One undo step, or part of the current gesture.
    */
   setValue(seriesId, index, value, options = {}) {
+    const grouped = this.treeLocked();
+    if (grouped) return grouped;
     const series = this.getSeries(seriesId);
     if (!series) return this.unknownSeries(seriesId);
     if (!Number.isInteger(index) || index < 0 || index >= this.spec.categories.length) return this.badIndex(index);
@@ -888,6 +940,8 @@ var ChartController = class {
   }
   /** Several values as one undo step (all-or-nothing). */
   setValues(cells, options = {}) {
+    const grouped = this.treeLocked();
+    if (grouped) return grouped;
     const issues = [];
     const parsed = [];
     for (const cell of cells) {
@@ -925,6 +979,7 @@ var ChartController = class {
       `Delete series "${series.name}"`,
       this.edited((d) => {
         d.series = d.series.filter((s) => s.id !== id);
+        d.highlight = d.highlight.filter((h) => h !== id && (h !== series.name || d.series.some((s) => s.name === h) || d.categories.includes(h)));
       })
     );
     return { ok: true };
@@ -942,7 +997,7 @@ var ChartController = class {
       if (patch.hidden) next.hidden = true;
       else delete next.hidden;
     }
-    const resettable = ["axis", "x", "sizes", "pointColors", "marker", "curve", "dataLabels", "format", "errorBars", "xErrorBars"];
+    const resettable = ["axis", "x", "sizes", "pointColors", "callouts", "marker", "curve", "dataLabels", "format", "errorBars", "xErrorBars"];
     for (const key of resettable) {
       if (!(key in patch) || patch[key] === void 0) continue;
       if (patch[key] === null) delete next[key];
@@ -950,7 +1005,9 @@ var ChartController = class {
     }
     if (next.axis === "primary") delete next.axis;
     const series2 = this.spec.series.map((s) => s.id === id ? next : s);
-    const { spec, issues } = normalizeChartSpec({ ...this.spec, series: series2 });
+    const renamed = next.name !== series.name && this.spec.highlight.includes(series.name) && !this.spec.categories.includes(series.name);
+    const highlight = renamed ? this.spec.highlight.map((h) => h === series.name ? next.name : h) : this.spec.highlight;
+    const { spec, issues } = normalizeChartSpec({ ...this.spec, series: series2, highlight });
     if (issues.length) return this.reject(issues.map((i) => i.message).join(" "), issues);
     if (JSON.stringify(spec.series) === JSON.stringify(this.spec.series)) return { ok: true };
     const label = patch.hidden !== void 0 && Object.keys(patch).length === 1 ? `${patch.hidden ? "Hide" : "Show"} "${series.name}"` : patch.name !== void 0 && Object.keys(patch).length === 1 ? "Rename series" : `Change series "${series.name}"`;
@@ -979,41 +1036,52 @@ var ChartController = class {
   }
   /** Inserts a category (with gaps in every series) at `at` (default: the end). Returns its index. */
   addCategory(label, options = {}) {
+    const grouped = this.treeLocked();
+    if (grouped) return grouped;
     const at = Math.max(0, Math.min(this.spec.categories.length, options.at ?? this.spec.categories.length));
     const name = label ?? `${this.spec.categories.length + 1}`;
     this.commit(
       `Add category "${name}"`,
       this.edited((d) => {
         d.categories.splice(at, 0, name);
-        for (const s of d.series) s.values.splice(at, 0, null);
+        for (const s of d.series) for (const list of pointLists(s)) list.splice(at, 0, null);
       }),
       { kind: "category", index: at }
     );
     return { ok: true, index: at };
   }
   removeCategory(index) {
+    const grouped = this.treeLocked();
+    if (grouped) return grouped;
     if (!Number.isInteger(index) || index < 0 || index >= this.spec.categories.length) return this.badIndex(index);
     this.commit(
       `Delete category "${this.spec.categories[index]}"`,
       this.edited((d) => {
-        d.categories.splice(index, 1);
-        for (const s of d.series) s.values.splice(index, 1);
+        const [label] = d.categories.splice(index, 1);
+        for (const s of d.series) for (const list of pointLists(s)) list.splice(index, 1);
+        if (!d.categories.includes(label)) d.highlight = d.highlight.filter((h) => h !== label);
       })
     );
     return { ok: true };
   }
   renameCategory(index, label) {
+    const grouped = this.treeLocked();
+    if (grouped) return grouped;
     if (!Number.isInteger(index) || index < 0 || index >= this.spec.categories.length) return this.badIndex(index);
     if (this.spec.categories[index] === label) return { ok: true };
     this.commit(
       "Rename category",
       this.edited((d) => {
+        const before = d.categories[index];
         d.categories[index] = String(label);
+        if (d.highlight.includes(before) && !d.categories.includes(before)) d.highlight = d.highlight.map((h) => h === before ? String(label) : h);
       })
     );
     return { ok: true };
   }
   moveCategory(from, to) {
+    const grouped = this.treeLocked();
+    if (grouped) return grouped;
     if (!Number.isInteger(from) || from < 0 || from >= this.spec.categories.length) return this.badIndex(from);
     const target = Math.max(0, Math.min(this.spec.categories.length - 1, to));
     if (target === from) return { ok: true };
@@ -1025,7 +1093,7 @@ var ChartController = class {
       "Reorder categories",
       this.edited((d) => {
         move(d.categories);
-        for (const s of d.series) move(s.values);
+        for (const s of d.series) for (const list of pointLists(s)) move(list);
       })
     );
     return { ok: true };
@@ -1036,6 +1104,8 @@ var ChartController = class {
    * grid grows to fit. Non-numeric value cells become gaps and are reported in `issues`.
    */
   pasteCells(row, column, cells) {
+    const grouped = this.treeLocked();
+    if (grouped) return grouped;
     const rows = typeof cells === "string" ? cells.includes("	") ? parseTsv(cells) : parseCsv(cells) : cells.map((r) => [...r]);
     if (!rows.length) return { ok: true };
     const issues = [];
@@ -1083,7 +1153,7 @@ var ChartController = class {
       const old = byName.get(s.name);
       return { ...s, ...old?.color ? { color: old.color } : {}, ...old?.type ? { type: old.type } : {}, ...old ? { id: old.id } : {} };
     });
-    const { spec } = normalizeChartSpec({ ...this.spec, categories: data.categories, series });
+    const { spec } = normalizeChartSpec({ ...this.spec, categories: data.categories, series, tree: [] });
     this.commit("Import data", spec);
     if (data.issues.length) {
       this.issues = data.issues;
@@ -1098,6 +1168,252 @@ var ChartController = class {
     return this.importTable(parseCsv(text, { delimiter }), options);
   }
   // -------------------------------------------------------------------------
+  // Grouped data (tree)
+  // -------------------------------------------------------------------------
+  /** A refusal while the data is a tree (cell edits would be overwritten by its totals), else null. */
+  treeLocked() {
+    if (!this.spec.tree.length) return null;
+    return this.reject(
+      "This chart's data is grouped (a tree): its categories and values are the top-level groups and their totals. Change it with setTree / the tree node edits (set_chart_tree, add_chart_tree_node, update_chart_tree_node, remove_chart_tree_node), or replace it with new data."
+    );
+  }
+  /** Replaces the grouped data (an empty list goes back to the table, keeping the totals as values). One undo step. */
+  setTree(tree, options = {}) {
+    const issues = [];
+    const next = normalizeChartTree(tree, issues);
+    if (issues.length) return this.reject(issues.map((i) => i.message).join(" "), issues);
+    return this.update({ tree: next }, { label: options.label ?? (next.length ? "Replace grouped data" : "Ungroup data") });
+  }
+  /**
+   * Replaces the grouped data from rows of names and a value (group, …, item, value), as the
+   * data grid edits it; colours of nodes whose path is unchanged are kept. All-or-nothing.
+   */
+  setTreeRows(rows, options = {}) {
+    const issues = [];
+    const next = chartTreeFromRows(rows, issues);
+    if (issues.length) return this.reject(issues.map((i) => i.message).join(" "), issues);
+    const keepColors = (list, prefix) => {
+      for (const n of list) {
+        const old = findChartTreeNode(this.spec.tree, [...prefix, n.name]);
+        if (old?.color) n.color = old.color;
+        if (n.children) keepColors(n.children, [...prefix, n.name]);
+      }
+    };
+    keepColors(next, []);
+    return this.update({ tree: next }, { label: options.label ?? "Edit grouped data" });
+  }
+  /** Replaces the data with a table of names and values (group, …, item, value); see `chartTreeFromTable`. */
+  importTreeTable(rows, options = {}) {
+    const issues = [];
+    const next = chartTreeFromTable(rows, options, issues);
+    if (issues.length) return this.reject(issues.map((i) => i.message).join(" "), issues);
+    if (!next.length) return this.reject('There is no grouped data to import: expected rows of names followed by a value, e.g. "Europe,France,40".');
+    return this.update({ tree: next }, { label: "Import grouped data" });
+  }
+  nodeAt(path) {
+    const node = findChartTreeNode(this.spec.tree, path);
+    if (node) return node;
+    const known = path.length > 1 ? findChartTreeNode(this.spec.tree, path.slice(0, -1)) : null;
+    const siblings = (path.length > 1 ? known?.children : this.spec.tree) ?? [];
+    return fail(
+      `There is no node ${JSON.stringify(path)}. ${siblings.length ? `${path.length > 1 && known ? `"${known.name}" contains` : "The top level has"} ${siblings.map((n) => `"${n.name}"`).slice(0, 20).join(", ")}.` : "The chart has no grouped data yet; add nodes with add_chart_tree_node or set_chart_tree."}`
+    );
+  }
+  /** Adds a node under the group at `parent` ([] for the top level) at `at` (default: the end). Returns its path. */
+  addTreeNode(parent, input, options = {}) {
+    let siblings = this.spec.tree;
+    if (parent.length) {
+      const group = this.nodeAt(parent);
+      if ("ok" in group) return group;
+      if (!group.children) return this.reject(`"${group.name}" is an item with its own value, not a group; add the node next to it, or turn it into a group by replacing the tree with set_chart_tree.`);
+      siblings = group.children;
+    }
+    const issues = [];
+    const [node] = normalizeChartTree([input], issues, "node");
+    if (!node || issues.length) return this.reject(issues.map((i) => i.message).join(" ") || "The node is not valid.", issues);
+    if (siblings.some((n) => n.name === node.name)) return this.reject(`"${node.name}" is already there; names under one group must be unique.`);
+    const at = Math.max(0, Math.min(siblings.length, options.at ?? siblings.length));
+    const tree = cloneChartTree(this.spec.tree);
+    const list = parent.length ? findChartTreeNode(tree, parent).children : tree;
+    list.splice(at, 0, node);
+    const result = this.update({ tree }, { label: `Add "${node.name}"` });
+    if (!result.ok) return result;
+    return { ok: true, path: [...parent, node.name] };
+  }
+  /** Renames, revalues (items only) or recolours a node; `color: null` goes back to the palette. Returns its path. */
+  updateTreeNode(path, patch) {
+    const node = this.nodeAt(path);
+    if ("ok" in node) return node;
+    if (patch.value !== void 0 && node.children) return this.reject(`"${node.name}" is a group: its value is the sum of its items. Change the items instead.`);
+    const name = patch.name !== void 0 ? String(patch.name).trim() : node.name;
+    const siblings = (path.length > 1 ? findChartTreeNode(this.spec.tree, path.slice(0, -1)).children : this.spec.tree).filter((n) => n !== node);
+    if (siblings.some((n) => n.name === name)) return this.reject(`There is already a "${name}" next to "${node.name}"; names under one group must be unique.`);
+    const tree = cloneChartTree(this.spec.tree);
+    const target = findChartTreeNode(tree, path);
+    const merged = { ...target, name };
+    if (patch.value !== void 0) merged.value = patch.value;
+    if (patch.color === null) delete merged.color;
+    else if (patch.color !== void 0) merged.color = patch.color;
+    const issues = [];
+    const [checked] = normalizeChartTree([merged], issues, "node");
+    if (!checked || issues.length) return this.reject(issues.map((i) => i.message).join(" "), issues);
+    Object.assign(target, checked);
+    if (patch.color === null) delete target.color;
+    const result = this.update({ tree }, { label: patch.name !== void 0 && patch.name !== node.name ? "Rename group" : `Change "${node.name}"` });
+    if (!result.ok) return result;
+    return { ok: true, path: [...path.slice(0, -1), name] };
+  }
+  /** Removes a node (with everything under it). A group left empty becomes an item with value 0. */
+  removeTreeNode(path) {
+    const node = this.nodeAt(path);
+    if ("ok" in node) return node;
+    const tree = cloneChartTree(this.spec.tree);
+    const parent = path.length > 1 ? findChartTreeNode(tree, path.slice(0, -1)) : null;
+    const list = parent ? parent.children : tree;
+    list.splice(
+      list.findIndex((n) => n.name === node.name),
+      1
+    );
+    if (parent && !parent.children.length) {
+      delete parent.children;
+      parent.value = 0;
+    }
+    return this.update({ tree }, { label: `Delete "${node.name}"` });
+  }
+  // -------------------------------------------------------------------------
+  // Annotations
+  // -------------------------------------------------------------------------
+  /** Sets the note written under the chart ("" removes it). */
+  setNote(note) {
+    return this.update({ note }, { label: note ? "Edit note" : "Remove note" });
+  }
+  /**
+   * Draws the named categories (labels) and series (names or ids) normally and mutes the
+   * rest; an empty list shows everything. Unknown names change nothing. Returns the category
+   * indexes and series ids that matched.
+   */
+  setHighlight(names) {
+    const s = this.spec;
+    const list = [...new Set(names.map(String))];
+    const unknown = list.filter((n) => !s.categories.includes(n) && !s.series.some((x) => x.id === n || x.name === n));
+    if (unknown.length)
+      return this.reject(
+        `${unknown.map((u) => `"${u}"`).join(", ")} ${unknown.length === 1 ? "is" : "are"} neither a category nor a series. Categories: ${s.categories.slice(0, 20).map((c) => `"${c}"`).join(", ") || "(none)"}; series: ${s.series.map((x) => `"${x.name}"`).join(", ") || "(none)"}.`
+      );
+    const result = this.update({ highlight: list }, { label: list.length ? "Highlight" : "Clear highlight" });
+    if (!result.ok) return result;
+    return {
+      ok: true,
+      categories: s.categories.flatMap((c, i) => list.includes(c) ? [i] : []),
+      series: s.series.filter((x) => list.includes(x.id) || list.includes(x.name)).map((x) => x.id)
+    };
+  }
+  /** Why a reference on `axis` at `values` cannot be drawn on this chart, or null. */
+  referenceProblem(axis, values) {
+    const s = this.spec;
+    const family = chartFamily(s);
+    if (family !== "cartesian" && family !== "xy") return `Reference lines and bands are drawn on bar, line, area, scatter and bubble charts; this is a ${s.type} chart.`;
+    if (axis === "x" && family !== "xy") return 'axis "x" needs a scatter or bubble chart with numeric x values; use "y" for the value axis.';
+    if (axis === "y2" && (family !== "cartesian" || !s.series.some((x) => !x.hidden && x.axis === "secondary")))
+      return 'axis "y2" needs a visible series on the secondary axis (set one with update_chart_series axis "secondary"), or use "y".';
+    const scale = (axis === "x" ? s.xAxis : axis === "y2" ? s.yAxis2 : s.yAxis).scale;
+    if (scale === "log" && values.some((v) => !(v > 0))) return "That axis is logarithmic, so the values must be above 0.";
+    return null;
+  }
+  editReferences(kind, label, edit, select) {
+    this.commit(
+      label,
+      this.edited((d) => edit(d[kind])),
+      select
+    );
+  }
+  /** Adds a reference line (a target, floor or average). Returns its index. */
+  addReferenceLine(input) {
+    const issues = [];
+    const line = normalizeChartReferenceLine(input, "referenceLine", issues);
+    if (!line || issues.length) return this.reject(issues.map((i) => i.message).join(" "), issues);
+    const problem = this.referenceProblem(line.axis, [line.value]);
+    if (problem) return this.reject(problem);
+    const index = this.spec.referenceLines.length;
+    this.editReferences("referenceLines", `Add reference line${line.label ? ` "${line.label}"` : ""}`, (list) => list.push(line));
+    return { ok: true, index };
+  }
+  /** Changes a reference line (all-or-nothing); `null` removes its label, colour or axis. */
+  updateReferenceLine(index, patch) {
+    const current = this.spec.referenceLines[index];
+    if (!current) return fail(this.noReference("reference line", this.spec.referenceLines.length, index));
+    const merged = { ...current, ...patch };
+    for (const [k, v] of Object.entries(patch)) if (v === null) delete merged[k];
+    const issues = [];
+    const line = normalizeChartReferenceLine(merged, "referenceLine", issues);
+    if (!line || issues.length) return this.reject(issues.map((i) => i.message).join(" "), issues);
+    const problem = this.referenceProblem(line.axis, [line.value]);
+    if (problem) return this.reject(problem);
+    this.editReferences("referenceLines", "Change reference line", (list) => list[index] = line);
+    return { ok: true };
+  }
+  removeReferenceLine(index) {
+    if (!this.spec.referenceLines[index]) return fail(this.noReference("reference line", this.spec.referenceLines.length, index));
+    this.editReferences("referenceLines", "Delete reference line", (list) => list.splice(index, 1));
+    return { ok: true };
+  }
+  /** Adds a reference band (a target range). Returns its index. */
+  addReferenceBand(input) {
+    const issues = [];
+    const band = normalizeChartReferenceBand(input, "referenceBand", issues);
+    if (!band || issues.length) return this.reject(issues.map((i) => i.message).join(" "), issues);
+    const problem = this.referenceProblem(band.axis, [band.from, band.to]);
+    if (problem) return this.reject(problem);
+    const index = this.spec.referenceBands.length;
+    this.editReferences("referenceBands", `Add reference band${band.label ? ` "${band.label}"` : ""}`, (list) => list.push(band));
+    return { ok: true, index };
+  }
+  /** Changes a reference band (all-or-nothing); `null` removes its label, colour or axis. */
+  updateReferenceBand(index, patch) {
+    const current = this.spec.referenceBands[index];
+    if (!current) return fail(this.noReference("reference band", this.spec.referenceBands.length, index));
+    const merged = { ...current, ...patch };
+    for (const [k, v] of Object.entries(patch)) if (v === null) delete merged[k];
+    const issues = [];
+    const band = normalizeChartReferenceBand(merged, "referenceBand", issues);
+    if (!band || issues.length) return this.reject(issues.map((i) => i.message).join(" "), issues);
+    const problem = this.referenceProblem(band.axis, [band.from, band.to]);
+    if (problem) return this.reject(problem);
+    this.editReferences("referenceBands", "Change reference band", (list) => list[index] = band);
+    return { ok: true };
+  }
+  removeReferenceBand(index) {
+    if (!this.spec.referenceBands[index]) return fail(this.noReference("reference band", this.spec.referenceBands.length, index));
+    this.editReferences("referenceBands", "Delete reference band", (list) => list.splice(index, 1));
+    return { ok: true };
+  }
+  noReference(what, count, index) {
+    return `There is no ${what} ${index}; ${count ? `expected 0 to ${count - 1}` : `the chart has none yet`}.`;
+  }
+  /**
+   * Pins a label to one bar or point (`null` or "" removes it) and selects the point. The
+   * point must have a value, on a bar, line, area, scatter or bubble chart.
+   */
+  setCallout(seriesId, index, label) {
+    const series = this.getSeries(seriesId);
+    if (!series) return this.unknownSeries(seriesId);
+    if (!Number.isInteger(index) || index < 0 || index >= this.spec.categories.length) return this.badIndex(index);
+    const family = chartFamily(this.spec);
+    const text = label === null ? "" : String(label).trim();
+    if (text && family !== "cartesian" && family !== "xy") return this.reject(`Callouts are drawn on bar, line, area, scatter and bubble charts; this is a ${this.spec.type} chart.`);
+    if (text && (series.values[index] === null || series.values[index] === void 0))
+      return this.reject(`"${series.name}" has no value at "${this.spec.categories[index]}", so there is nothing to point at; set a value first.`);
+    const next = this.edited((d) => {
+      const s = d.series.find((x) => x.id === seriesId);
+      const labels = s.callouts ? [...s.callouts] : d.categories.map(() => null);
+      labels[index] = text || null;
+      if (labels.some((l) => l)) s.callouts = labels;
+      else delete s.callouts;
+    });
+    this.commit(text ? "Add callout" : "Remove callout", next, { kind: "point", seriesId, index });
+    return { ok: true };
+  }
+  // -------------------------------------------------------------------------
   // Trendlines
   // -------------------------------------------------------------------------
   /** Adds a trendline to a series and selects it. Returns its index (and the fit, when it can be computed). */
@@ -1182,6 +1498,8 @@ var ChartController = class {
    * undo step). Series colours, types and other per-series settings are dropped.
    */
   transpose() {
+    const grouped = this.treeLocked();
+    if (grouped) return grouped;
     const s = this.spec;
     if (!s.series.length || !s.categories.length) return this.reject("There is no data to switch: the chart needs at least one series and one category.");
     const used = /* @__PURE__ */ new Set();
@@ -1235,6 +1553,8 @@ var ChartController = class {
   }
   /** Adds `delta` to a value (a gap counts as 0). */
   nudgeValue(seriesId, index, delta) {
+    const grouped = this.treeLocked();
+    if (grouped) return grouped;
     const series = this.getSeries(seriesId);
     if (!series) return this.unknownSeries(seriesId);
     const current = series.values[index] ?? 0;
@@ -1343,6 +1663,18 @@ function updateLabel(patch) {
     overlap: "Change bar overlap",
     bins: "Change histogram bins",
     showTotal: "Toggle waterfall total",
+    note: "Edit note",
+    highlight: "Change highlight",
+    referenceLines: "Change reference lines",
+    referenceBands: "Change reference bands",
+    varyColors: "Toggle colour by category",
+    likertNeutral: "Change neutral answer",
+    likertSort: "Sort questions",
+    parliamentArc: "Change hemicycle sweep",
+    parliamentMajority: "Change majority",
+    parliamentLabel: "Edit seat caption",
+    sunburstLabel: "Edit centre caption",
+    tree: "Replace grouped data",
     radarTicks: "Change radar rings",
     radarGraticule: "Change radar grid",
     legend: "Change legend",

package/dist/{chunk-GLMP22FT.js → chunk-TALQONZ5.js}

@@ -7,7 +7,7 @@ import {
 import {
   CHART_OOXML_NS,
   chartFromOoxml
-} from "./chunk-7CKPUUN4.js";
+} from "./chunk-POR54B55.js";
 import {
   compareDocuments
 } from "./chunk-V5OOP74P.js";
@@ -34,10 +34,10 @@ import {
   searchDocument,
   sliceContainsTable,
   syncInitialContent
-} from "./chunk-CX6JLDFC.js";
+} from "./chunk-OXERWBKE.js";
 import {
   chartDataToTable
-} from "./chunk-HLOKB7WW.js";
+} from "./chunk-3NEZJCBY.js";
 import {
   PIXERATE_DOCUMENT_MIME,
   getClipboardData,