@openpresentation/opf-editor 0.11.3 → 0.14.2

package/dist/data-grid.js

@@ -8,12 +8,19 @@
 // Keyboard: arrows move (Shift extends), Home/End, Ctrl+Home/End, PageUp/PageDown, Enter or F2 edits, typing replaces the text,
 // Enter/Shift+Enter and Tab/Shift+Tab commit and move, Escape cancels, Delete clears, Ctrl+C/X/V copy, cut and paste TSV, Ctrl+A selects
 // all, Ctrl+Z / Ctrl+Y undo and redo. Outside an edit Tab leaves the grid. Row and column operations are in the toolbar.
+//
+// RR-54: a header may be a DataColumn (the grid shows its name and keeps its number format); the column format field sets or
+// clears the selected column's format; a chart's "Chart columns" panel sets the category, X and series columns (`chart.mapping`);
+// and a chart or table that shows a shared dataset edits the dataset (the status line says how many items share it).
 import {
+  columnFormatError,
   columnLabel,
   deleteGridColumns,
   deleteGridRows,
   describeAddress,
+  describeChartMapping,
   describeDataGrid,
+  detachGridDataset,
   gridCellIssues,
   insertGridColumns,
   insertGridRows,
@@ -21,7 +28,9 @@ import {
   moveGridRows,
   pasteGridText,
   resolveDataGridTarget,
+  setChartMapping,
   setGridCells,
+  setGridColumnFormat,
   setGridHeader,
   sortGridRows,
   transposeGridData,
@@ -66,6 +75,17 @@ const CSS = `
 .opf-grid-status{margin:6px 0 0;font-size:11px;color:#3d5e47;min-height:1.2em}.opf-grid-error{margin:6px 0 0;font-size:11px;color:var(--g-error)}.opf-grid-error:empty{display:none}
 .opf-grid details{margin:6px 0 0;font-size:11px}.opf-grid details summary{cursor:pointer}.opf-grid details textarea{display:block;width:100%;box-sizing:border-box;min-height:64px;margin:4px 0;font:11px ui-monospace,monospace}
 .opf-grid-help{margin:6px 0 0;font-size:10px;color:var(--g-muted)}
+.opf-grid-dataset,.opf-grid-format{display:flex;flex-wrap:wrap;gap:6px;align-items:center;margin:0 0 6px;font-size:11px;color:var(--g-muted)}
+.opf-grid-dataset[hidden],.opf-grid-format[hidden],.opf-grid-mapping[hidden]{display:none!important}
+.opf-grid-dataset strong{color:var(--g-text)}
+.opf-grid-dataset button,.opf-grid-format button,.opf-grid-format input,.opf-grid-mapping select{font:inherit;min-height:28px;border:1px solid var(--g-border);border-radius:4px;background:#fff;color:inherit;padding:2px 8px}
+.opf-grid-dataset button,.opf-grid-format button{cursor:pointer}.opf-grid-dataset button:hover,.opf-grid-format button:hover{background:#f1effa}
+.opf-grid-format [aria-disabled=true]{opacity:.45;cursor:default}
+.opf-grid-format input{width:150px}.opf-grid-format input[aria-invalid=true]{border-color:var(--g-error)}
+.opf-grid-format-error{color:var(--g-error)}.opf-grid-format-error:empty{display:none}
+.opf-grid-mapping{margin:6px 0 0;font-size:11px}.opf-grid-mapping label{display:inline-flex;gap:4px;align-items:center;margin:0 10px 4px 0}
+.opf-grid-mapping fieldset{border:1px solid var(--g-border);border-radius:4px;margin:4px 0 0;padding:4px 8px}.opf-grid-mapping legend{font-size:11px;color:var(--g-muted)}
+.opf-grid-mapping p{margin:4px 0 0;color:var(--g-muted)}
 @media (forced-colors:active){.opf-grid td.opf-grid-active{outline:3px solid Highlight}.opf-grid td[aria-selected=true]{outline:1px solid Highlight}.opf-grid td[aria-invalid=true]{outline:2px solid LinkText}}
 `;
 
@@ -142,7 +162,22 @@ export function createDataGrid(container, options = {}) {
   const pasteButton = h("button", { type: "button", "aria-disabled": "false" }, "Paste at selected cell");
   const pasteBox = h("details", { class: "opf-grid-paste" }, h("summary", {}, "Paste text"), h("label", { for: `${uid}-paste` }, "Text from a spreadsheet or CSV file"), pasteArea, pasteButton);
   table.setAttribute("aria-describedby", help.id);
-  root.append(h("div", { class: "opf-grid-title" }, titleText, pathText), unavailable, toolbar, scroll, notes, help, pasteBox, statusEl, errorEl);
+  // A shared dataset: which one, how many items use it, and a way to stop sharing.
+  const datasetText = h("span", { "data-role": "dataset-note" });
+  const detachButton = h("button", { type: "button", "data-action": "detach-dataset", title: "Give this item its own copy of the data. The shared dataset stays for the other items." }, "Use a copy of the data");
+  const datasetRow = h("div", { class: "opf-grid-dataset", role: "note", hidden: true }, datasetText, detachButton);
+  // The number format of the selected column.
+  const formatInput = h("input", { type: "text", id: `${uid}-format`, "data-role": "column-format", list: `${uid}-formats`, autocomplete: "off", spellcheck: "false", placeholder: "General" });
+  const formatList = h("datalist", { id: `${uid}-formats` }, ["#,##0", "#,##0.0", "#,##0.00", "0%", "0.0%", "$#,##0", "$#,##0.00", "0.00"].map((value) => h("option", { value })));
+  const formatLabel = h("label", { for: formatInput.id }, "Column format");
+  const formatApply = h("button", { type: "button", "data-action": "apply-format", "aria-disabled": "false" }, "Apply");
+  const formatClear = h("button", { type: "button", "data-action": "clear-format", "aria-disabled": "false" }, "Clear");
+  const formatError = h("span", { class: "opf-grid-format-error", role: "alert", "data-role": "format-error" });
+  const formatRow = h("div", { class: "opf-grid-format", hidden: true }, formatLabel, formatInput, formatList, formatApply, formatClear, formatError);
+  // A chart's category, X and series columns.
+  const mappingBody = h("div", { "data-role": "mapping-body" });
+  const mappingBox = h("details", { class: "opf-grid-mapping", hidden: true }, h("summary", {}, "Chart columns"), mappingBody);
+  root.append(h("div", { class: "opf-grid-title" }, titleText, pathText), unavailable, datasetRow, toolbar, formatRow, scroll, mappingBox, notes, help, pasteBox, statusEl, errorEl);
   container.append(root);
   scroll.style.setProperty("--opf-grid-max-height", options.maxHeight ?? "320px");
 
@@ -306,7 +341,9 @@ export function createDataGrid(container, options = {}) {
     rulerRow.append(corner);
     for (let c = 0; c < grid.columnCount; c += 1) {
       const role = roles[c];
-      const hint = role === "category" ? "categories" : role === "series" ? "series" : role === "x" ? "x values" : role === "label" ? "labels" : "";
+      const role_ = role === "category" ? "categories" : role === "series" ? "series" : role === "x" ? "x values" : role === "label" ? "labels" : role === "other" ? "not plotted" : "";
+      const format = grid.columnFormats?.[c];
+      const hint = [role_, format ? `format ${format}` : ""].filter(Boolean).join(" · ");
       const th = h("th", { role: "columnheader", scope: "col", "aria-colindex": c + 2, "data-ruler": "column", "data-column": c, "aria-label": `Column ${columnLabel(c)}${hint ? `, ${hint}` : ""}` }, columnLabel(c), hint ? h("span", { class: "opf-grid-role" }, hint) : null);
       rulerRow.append(th);
     }
@@ -320,7 +357,7 @@ export function createDataGrid(container, options = {}) {
       for (const cell of line) {
         if (cell.covered) continue;
         const merged = cell.rowSpan > 1 || cell.colSpan > 1;
-        const numeric = target.kind === "chart" && !header && roles[cell.column] !== "category" && roles[cell.column] !== "label";
+        const numeric = target.kind === "chart" && !header && roles[cell.column] !== "category" && roles[cell.column] !== "label" && roles[cell.column] !== "other";
         const classes = ["opf-grid-cell"];
         if (header) classes.push("opf-grid-header");
         if (numeric) classes.push("opf-grid-number");
@@ -345,7 +382,12 @@ export function createDataGrid(container, options = {}) {
           title: cell.warning,
         });
         if (cell.runs) renderRuns(td, cell.runs);
-        else td.textContent = cell.text;
+        else if (cell.display !== undefined) {
+          // The number as the slide draws it; the raw value is what editing and copying use.
+          td.textContent = cell.display;
+          td.classList.add("opf-grid-formatted");
+          if (!cell.warning) td.title = `Stored as ${cell.text}`;
+        } else td.textContent = cell.text;
         tr.append(td);
       }
       tbody.append(tr);
@@ -394,12 +436,14 @@ export function createDataGrid(container, options = {}) {
       transpose: target.kind !== "chart" || grid.columnCount < 2,
     };
     for (const [name, button] of buttons) button.setAttribute("aria-disabled", String(Boolean(disabled[name])));
-    buttons.get("transpose").hidden = target.kind !== "chart";
+    const shared = Boolean(target.dataset);
+    buttons.get("transpose").hidden = target.kind !== "chart" || shared;
     // The toolbar stays one tab stop even when the button that held it is hidden for this kind of content.
     const visible = [...toolbar.querySelectorAll("button")].filter((button) => !button.hidden);
     if (!visible.some((button) => button.tabIndex === 0) && visible.length) visible[0].tabIndex = 0;
-    headerLabel.hidden = target.kind !== "table";
+    headerLabel.hidden = target.kind !== "table" || shared;
     headerBox.checked = grid.hasHeader;
+    updateFormatRow();
     const nameRows = count > 1 ? `${count} rows` : "row";
     buttons.get("delete-rows").textContent = count > 1 ? `Delete ${count} rows` : "Delete rows";
     buttons.get("insert-row-above").setAttribute("aria-label", `Insert ${nameRows === "row" ? "row" : nameRows} above`);
@@ -411,7 +455,7 @@ export function createDataGrid(container, options = {}) {
   function resolveTarget() {
     const path = getPath();
     if (!path) return undefined;
-    return resolveDataGridTarget(editor.document, path);
+    return resolveDataGridTarget(editor.presentation, path);
   }
 
   function rebuild() {
@@ -437,11 +481,14 @@ export function createDataGrid(container, options = {}) {
     scroll.hidden = toolbar.hidden = notes.hidden = pasteBox.hidden = help.hidden = next.editable === false;
     if (next.editable === false) {
       unavailable.textContent = next.reason;
+      datasetRow.hidden = formatRow.hidden = mappingBox.hidden = true;
       grid = undefined;
       return;
     }
-    grid = describeDataGrid(editor.document, next.path, opts());
+    grid = describeDataGrid(editor.presentation, next.path, opts());
     buildTable();
+    buildDatasetRow();
+    buildMapping();
     const clamped = clampCell(selection.focus.u, selection.focus.c);
     const anchor = clampCell(selection.anchor.u, selection.anchor.c);
     const f = anchorOf(clamped.u, clamped.c);
@@ -457,7 +504,7 @@ export function createDataGrid(container, options = {}) {
   function dataSignature() {
     if (!target || target.editable === false) return "";
     try {
-      return JSON.stringify([target.path, editor.get(target.path), numberFormat]);
+      return JSON.stringify([target.path, editor.get(target.path), target.dataset ? editor.presentation.datasets?.[target.dataset.id] : undefined, numberFormat]);
     } catch {
       return "";
     }
@@ -488,6 +535,128 @@ export function createDataGrid(container, options = {}) {
   }
   const unsubscribe = editor.subscribe(() => sync());
 
+  // --- shared dataset, number format, mapping (RR-54) -----------------------------------------------
+  function buildDatasetRow() {
+    const info = target?.dataset;
+    datasetRow.hidden = !info;
+    if (!info) return;
+    const used = info.count === 1 ? "used by 1 item" : `used by ${info.count} items`;
+    datasetText.replaceChildren("Shared dataset \u2018", h("strong", {}, info.id), `\u2019 \u2014 ${used}.${info.fields ? ` Showing ${info.fields.join(", ")}.` : ""} Edits change the dataset for every item that uses it.`);
+    datasetRow.setAttribute("aria-label", `Shared dataset ${info.id}, ${used}`);
+  }
+
+  const formatColumn = () => activeCell()?.column ?? 0;
+  // The column the field is for. It follows the selected column, but not while someone types in the field: a click on another cell
+  // moves the selection before the field's change event fires, and the format typed for one column must not land on the next.
+  let formatBound = 0;
+  function updateFormatRow() {
+    const visible = Boolean(grid?.hasHeader) && target?.editable !== false;
+    formatRow.hidden = !visible;
+    if (!visible) return;
+    if (doc.activeElement !== formatInput) {
+      formatBound = formatColumn();
+      formatInput.value = grid.columnFormats?.[formatBound] ?? "";
+      formatInput.removeAttribute("aria-invalid");
+      formatError.textContent = "";
+    }
+    const column = formatBound;
+    const name = grid.columnNames?.[column];
+    formatLabel.textContent = `Format of column ${columnLabel(column)}${name ? ` (${name})` : ""}${target?.dataset ? " in the shared dataset" : ""}`;
+    formatClear.setAttribute("aria-disabled", String(grid.columnFormats?.[column] === undefined));
+  }
+  formatInput.addEventListener("input", () => {
+    const error = columnFormatError(formatInput.value);
+    formatError.textContent = error ?? "";
+    if (error) formatInput.setAttribute("aria-invalid", "true");
+    else formatInput.removeAttribute("aria-invalid");
+  });
+  function applyFormat(value) {
+    const column = formatBound;
+    const error = columnFormatError(value);
+    if (error) {
+      formatInput.setAttribute("aria-invalid", "true");
+      formatError.textContent = error;
+      return;
+    }
+    formatError.textContent = "";
+    formatInput.removeAttribute("aria-invalid");
+    if ((grid.columnFormats?.[column] ?? "") === value) return;
+    const cleared = value === "";
+    attempt(() => setGridColumnFormat(editor, target.path, column, cleared ? null : value, {}), cleared ? `Column ${columnLabel(column)} shows numbers as they are.` : `Column ${columnLabel(column)} shows numbers as ${value}.`, (failure) => {
+      formatError.textContent = messageOf(failure);
+    });
+  }
+  formatInput.addEventListener("keydown", (event) => {
+    if (event.key === "Enter") {
+      event.preventDefault();
+      applyFormat(formatInput.value);
+    } else if (event.key === "Escape") {
+      event.preventDefault();
+      formatInput.value = grid?.columnFormats?.[formatBound] ?? "";
+      formatError.textContent = "";
+      formatInput.removeAttribute("aria-invalid");
+    }
+  });
+  formatInput.addEventListener("change", () => applyFormat(formatInput.value));
+  formatApply.addEventListener("click", () => applyFormat(formatInput.value));
+  formatClear.addEventListener("click", () => {
+    if (formatClear.getAttribute("aria-disabled") === "true") return;
+    formatInput.value = "";
+    applyFormat("");
+  });
+  detachButton.addEventListener("click", () => {
+    if (!target?.dataset) return;
+    const id = target.dataset.id;
+    attempt(() => detachGridDataset(editor, target.path, {}), `This ${target.kind} now has its own copy of dataset \u2018${id}\u2019.`);
+  });
+
+  function buildMapping() {
+    mappingBody.replaceChildren();
+    mappingBox.hidden = !grid || target?.kind !== "chart";
+    if (mappingBox.hidden) return;
+    let view;
+    try {
+      view = describeChartMapping(editor.presentation, target.path);
+    } catch {
+      mappingBox.hidden = true;
+      return;
+    }
+    const names = view.columns.map((column) => column.name);
+    const selectOf = (label, value, onChange, allowed) => {
+      const select = h("select", { "aria-label": label }, names.map((name, index) => (allowed(index) ? h("option", { value: name }, name || `(column ${columnLabel(index)})`) : null)));
+      select.value = value;
+      select.addEventListener("change", () => onChange(select.value));
+      return h("label", {}, label, select);
+    };
+    const category = names.indexOf(view.category);
+    mappingBody.append(selectOf(view.xy ? "Label column" : "Category column", view.category, (name) => setMapping({ category: name }, `The category column is now ${JSON.stringify(name)}.`), () => true));
+    if (view.xy) mappingBody.append(selectOf("X column", view.x ?? "", (name) => setMapping({ x: name }, `The X column is now ${JSON.stringify(name)}.`), (index) => index !== category));
+    const plotted = new Set(view.series);
+    const boxes = view.columns.map((column, index) => {
+      if (column.name === view.category || column.name === view.x) return null;
+      const input = h("input", { type: "checkbox", value: column.name, checked: plotted.has(column.name) || undefined });
+      input.checked = plotted.has(column.name);
+      input.addEventListener("change", () => {
+        const wanted = [...view.series.filter((name) => name !== column.name), ...(input.checked ? [column.name] : [])];
+        // Series that run in column order stay in column order; series someone arranged keep their order and a column switched on goes after them.
+        const inColumnOrder = view.series.every((name, at) => at === 0 || names.indexOf(view.series[at - 1]) < names.indexOf(name));
+        const ordered = inColumnOrder ? names.filter((name) => wanted.includes(name)) : [...view.series.filter((name) => wanted.includes(name)), ...names.filter((name) => wanted.includes(name) && !view.series.includes(name))];
+        setMapping({ series: ordered }, input.checked ? `${column.name || `Column ${columnLabel(index)}`} is now plotted.` : `${column.name || `Column ${columnLabel(index)}`} is no longer plotted.`, () => {
+          input.checked = !input.checked;
+        });
+      });
+      return h("label", {}, input, column.name || `(column ${columnLabel(index)})`);
+    });
+    mappingBody.append(h("fieldset", {}, h("legend", {}, "Series (plotted columns)"), boxes));
+    mappingBody.append(h("p", {}, view.authored ? "This chart has its own column mapping. Choosing the default columns removes it." : "Default: the first column labels the categories and every other column is a series."));
+  }
+  function setMapping(wanted, message, onFail) {
+    attempt(() => setChartMapping(editor, target.path, wanted, {}), message, (failure) => {
+      onFail?.(failure);
+      buildMapping();
+    });
+  }
+
   // --- editing --------------------------------------------------------------------------------------
   function mountEditor(u, c, text, caret) {
     const node = cellNode(u, c);
@@ -524,7 +693,7 @@ export function createDataGrid(container, options = {}) {
   }
 
   function checkLive(area, u, c) {
-    const issues = gridCellIssues(editor.document, target.path, [{ ...addr(u, c), text: area.value }], opts());
+    const issues = gridCellIssues(editor.presentation, target.path, [{ ...addr(u, c), text: area.value }], opts());
     if (issues.length) {
       area.setAttribute("aria-invalid", "true");
       complain(issues[0].message);

package/dist/data.d.ts

@@ -1,2 +1,23 @@
-export {parseTabularData, createDataContent, OPFDataImportError} from "@openpresentation/opf/data";
-export type {TabularData, DataImportOptions, DataContentOptions} from "@openpresentation/opf/data";
+export {parseTabularData, importData, OPFDataImportError} from "@openpresentation/opf/data";
+export type {TabularData, DataImportOptions, ImportDataOptions} from "@openpresentation/opf/data";
+import type { JsonPatchOperation } from "./index.js";
+
+/** The id pattern of a top-level dataset (the assets id pattern). */
+export declare const DATASET_ID_PATTERN: RegExp;
+export interface DatasetImportOptions {
+  /** The dataset id: letters, digits, ".", "_" or "-", starting with a letter or digit. */
+  id: string;
+  /** Provenance to record in the dataset's `source` (merged into an existing one). Engines never read it. */
+  source?: { src: string; retrieved?: string; sheet?: string; range?: string; description?: string };
+}
+export interface DatasetImport {
+  id: string;
+  /** The imported table or chart, holding `{ dataset: id }` instead of its rows. */
+  content: { table: { dataset: string } } | { chart: { type: string; data: { dataset: string } } };
+  /** Patches that write `datasets.<id>`; apply them with the patch that places `content`, in one call. */
+  patches: JsonPatchOperation[];
+  /** True when a dataset of that id existed and its columns and rows were replaced. */
+  replaced: boolean;
+}
+/** Store imported data (the result of `importData`) as a shared dataset, as `opf import-data --dataset <id>` does. Throws `dataset-id-invalid`. */
+export declare function prepareDatasetImport(presentation: unknown, content: { table: unknown } | { chart: { type: string; data: unknown } }, options: DatasetImportOptions): DatasetImport;

package/dist/data.js

@@ -1 +1,40 @@
-export {parseTabularData, createDataContent, OPFDataImportError} from "@openpresentation/opf/data";
+export {parseTabularData, importData, OPFDataImportError} from "@openpresentation/opf/data";
+import { opfPathToJsonPointer } from "./index.js";
+import { fail } from "./edit-helpers.js";
+
+/** The id pattern of a top-level dataset (the assets id pattern). */
+export const DATASET_ID_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
+
+const isObject = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+
+/**
+ * Store imported data as a shared dataset (RR-54), as `opf import-data --dataset <id>` does. `content` is what `importData` returns
+ * (`{ table }` or `{ chart: { type, data } }`). Returns `{ id, content, patches, replaced }`: `content` is the same table or chart holding
+ * `{ dataset: id }` instead of the rows, and `patches` write `datasets.<id>` (the imported columns and rows replace those of an existing
+ * dataset of that id, which keeps its title, description and source; `source` is merged into its `source`). Apply `patches` and the patch that
+ * places `content` in one `applyPatch` call so the import is one undoable edit. Throws `dataset-id-invalid`.
+ */
+export function prepareDatasetImport(presentation, content, options = {}) {
+  const id = options.id;
+  if (typeof id !== "string" || !DATASET_ID_PATTERN.test(id)) throw fail("dataset-id-invalid", 'A dataset id starts with a letter or digit and holds letters, digits, ".", "_" or "-".', { id });
+  const isTable = isObject(content) && isObject(content.table);
+  if (!isTable && !(isObject(content) && isObject(content.chart) && isObject(content.chart.data))) throw fail("dataset-content-invalid", "Give the table or chart that importData returned.", {});
+  const data = isTable ? content.table : content.chart.data;
+  const datasets = isObject(presentation) && isObject(presentation.datasets) ? presentation.datasets : undefined;
+  const previous = datasets && Object.hasOwn(datasets, id) && isObject(datasets[id]) ? datasets[id] : undefined;
+  const origin = isObject(options.source) && typeof options.source.src === "string" ? options.source : undefined;
+  const entry = {
+    ...(previous ?? {}),
+    columns: structuredClone(data.columns),
+    rows: structuredClone(data.rows),
+    ...(origin ? { source: { ...(isObject(previous?.source) ? previous.source : {}), ...origin } } : {}),
+  };
+  const pointer = opfPathToJsonPointer(["datasets", id]);
+  const patches = !datasets
+    ? [{ op: "add", path: "/datasets", value: { [id]: entry } }]
+    : previous
+      ? [{ op: "test", path: pointer, value: structuredClone(previous) }, { op: "replace", path: pointer, value: entry }]
+      : [{ op: "add", path: pointer, value: entry }];
+  const referenced = isTable ? { table: { dataset: id } } : { chart: { type: content.chart.type, data: { dataset: id } } };
+  return { id, content: referenced, patches, replaced: Boolean(previous) };
+}

package/dist/dataset-refs.d.ts

@@ -0,0 +1,17 @@
+/** A chart or table that references a dataset: `chart.data = { dataset, fields? }` or `table = { dataset, fields? }`. */
+export interface DatasetItem {
+  kind: "chart" | "table";
+  id: string;
+  /** Path parts of the chart or table. */
+  parts: string[];
+  item: Record<string, any>;
+  /** Path parts of the object that holds `dataset` and `fields` (`chart.data`, or the table itself). */
+  refParts: string[];
+  ref: Record<string, any>;
+}
+/** The dataset reference test (core's `isDatasetRef`). */
+export declare function isDatasetRef(value: unknown): boolean;
+/** Visit every chart and table that references a dataset (slides, nested blocks and promoted regions). */
+export declare function walkDatasetItems(presentation: unknown, visit: (entry: DatasetItem) => void): void;
+/** The charts and tables that use dataset `id`, in document order. */
+export declare function datasetUsage(presentation: unknown, id: string): Array<{ kind: "chart" | "table"; path: string; parts: string[] }>;

package/dist/dataset-refs.js

@@ -0,0 +1,45 @@
+// Where charts and tables use a shared dataset (RR-54). A top-level `datasets` entry is referenced by a chart as
+// `chart.data = { dataset, fields? }` and by a table as `table = { dataset, fields? }`. These helpers find those
+// references anywhere in a document (slides, nested blocks and promoted regions), so the data grid can say how many items
+// share a dataset and keep their `fields` and `mapping` names in step when a column is renamed.
+
+const isObject = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+const REGION_KEY = /^(?:top|middle|bottom|left|center|right)(?:[+:]|$)/;
+
+/** The dataset reference test (the same as core's `isDatasetRef`): an object with a string `dataset`. */
+export const isDatasetRef = (value) => isObject(value) && typeof value.dataset === "string";
+
+/**
+ * Visit every chart and table that references a dataset. `visit({ kind, id, parts, item, refParts, ref })`:
+ * `item` is the chart or table object, `parts` its path, and `ref` the object that holds `dataset` and `fields`
+ * (`chart.data` for a chart, the table itself for a table) at `refParts`.
+ */
+export function walkDatasetItems(presentation, visit) {
+  if (!isObject(presentation) || !Array.isArray(presentation.slides)) return;
+  const walk = (payload, base, depth, ancestors) => {
+    if (isObject(payload.chart) && isDatasetRef(payload.chart.data))
+      visit({ kind: "chart", id: payload.chart.data.dataset, parts: [...base, "chart"], item: payload.chart, refParts: [...base, "chart", "data"], ref: payload.chart.data });
+    if (isObject(payload.table) && isDatasetRef(payload.table))
+      visit({ kind: "table", id: payload.table.dataset, parts: [...base, "table"], item: payload.table, refParts: [...base, "table"], ref: payload.table });
+    if (depth >= 32 || ancestors.includes(payload) || !Array.isArray(payload.blocks)) return;
+    const nested = [...ancestors, payload];
+    payload.blocks.forEach((block, index) => {
+      if (isObject(block)) walk(block, [...base, "blocks", String(index)], depth + 1, nested);
+    });
+  };
+  presentation.slides.forEach((slide, index) => {
+    if (!isObject(slide)) return;
+    const base = ["slides", String(index)];
+    walk(slide, base, 0, []);
+    for (const [key, value] of Object.entries(slide)) if (isObject(value) && REGION_KEY.test(key)) walk(value, [...base, key], 1, [slide]);
+  });
+}
+
+/** The charts and tables that use dataset `id`: `[{ kind, path, parts }]` in document order. */
+export function datasetUsage(presentation, id) {
+  const items = [];
+  walkDatasetItems(presentation, (entry) => {
+    if (entry.id === id) items.push({ kind: entry.kind, path: entry.parts.join("."), parts: entry.parts });
+  });
+  return items;
+}