@openpresentation/opf-editor 0.11.3 → 0.12.1

package/README.md

@@ -411,6 +411,19 @@ sortTableRows(editor, "slides.4.blocks.1.table", 1, { direction: "desc" });
 setChartCells(editor, "slides.3.blocks.0.chart", [{ section: "body", row: 0, column: 1, text: "12,5" }], { decimal: "," });
 ```
 
+Chart columns and table headers may be `DataColumn` objects (`{ name, format }`; the grid keeps the format and shows a formatted column's numbers as the slide draws them, while editing and copy use the raw value), a chart or table may show a shared top-level dataset (the grid edits `/datasets/<id>` through `fields` and says how many items share it), each column has a number format field and each chart a category, X and series mapping (RR-54):
+
+```js
+import { setGridColumnFormat, setChartMapping, detachGridDataset } from "@openpresentation/opf-editor/data-grid";
+import { prepareDatasetImport, createDataContent } from "@openpresentation/opf-editor/data";
+
+setGridColumnFormat(editor, "slides.3.blocks.0.chart", 1, "$#,##0.0");   // header "Revenue" becomes { name: "Revenue", format }; null clears it
+setChartMapping(editor, "slides.3.blocks.0.chart", { category: "Region", series: ["Revenue"] });
+detachGridDataset(editor, "slides.3.blocks.1.table");                   // its own copy instead of the shared dataset
+const stored = prepareDatasetImport(editor.document, createDataContent(csv, { as: "chart" }), { id: "revenue" });
+editor.applyPatch([...stored.patches, { op: "add", path: "/slides/-", value: { id: "rev", title: "Revenue", ...stored.content } }]);
+```
+
 The number rules, paste and copy format, merged-cell behaviour, sorting, keyboard and accessibility are in [docs/data-grid.md](docs/data-grid.md).
 
 ## Design controls panel (RR-06)

package/dist/block-convert.js

@@ -103,7 +103,8 @@ export function metricGroupForSelection(document, selectedPath) {
  */
 export function blockConversionTargets(document, path, options = {}) {
   const found = readBlockContent(document, path);
-  return found ? contentConversionTargets(found.owner, options) : [];
+  // RR-54: a table that shows a shared dataset needs the document's datasets to convert to anything but a chart.
+  return found ? contentConversionTargets(found.owner, { document, ...options }) : [];
 }
 
 /**
@@ -116,7 +117,7 @@ export function prepareBlockConversion(document, path, kind, options = {}) {
   if (!found) throw refuse(CHOOSE, { path });
   const pointer = opfPathToJsonPointer(found.path);
   const from = found.kind;
-  const result = convertOwner(found.owner, kind, options);
+  const result = convertOwner(found.owner, kind, { document, ...options });
   if (!result.changed) return { document: structuredClone(document), patches: [], path: found.path.join("."), changed: false, lossless: true, loss: [], from, to: kind };
   const patches = [
     { op: "test", path: pointer, value: structuredClone(found.owner) },

package/dist/chart-data.d.ts

@@ -30,3 +30,5 @@ export declare function transposeChart(editor: EditorSession, chartPath: string,
 export declare function renameChartSeries(editor: EditorSession, chartPath: string, column: number, name: string, options?: { meta?: Record<string, unknown> }): GridChange;
 /** Rename a category: the first-column label of body row `row`. An empty name leaves it blank. */
 export declare function renameChartCategory(editor: EditorSession, chartPath: string, row: number, name: string, options?: { meta?: Record<string, unknown> }): GridChange;
+export { describeChartMapping, prepareChartMapping, setChartMapping, prepareDetachDataset, detachGridDataset } from "./grid-model.js";
+export type { ChartMappingColumns, ChartMappingDescription } from "./grid-model.js";

package/dist/chart-data.js

@@ -99,3 +99,4 @@ export function renameChartSeries(editor, chartPath, column, name, options = {})
 export function renameChartCategory(editor, chartPath, row, name, options = {}) {
   return setGridCells(editor, chartPath, [{ section: "body", row, column: 0, value: name === "" || name === null ? null : String(name) }], { ...options, kind: "chart" });
 }
+export { describeChartMapping, prepareChartMapping, setChartMapping, prepareDetachDataset, detachGridDataset } from "./grid-model.js";

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,9 +28,12 @@ import {
   moveGridRows,
   pasteGridText,
   resolveDataGridTarget,
+  setChartMapping,
   setGridCells,
+  setGridColumnFormat,
   setGridHeader,
   sortGridRows,
+  supportsChartTableData,
   transposeGridData,
 } from "./grid-model.js";
 import { NUMBER_FORMATS, parseDelimited, resolveNumberFormat, toDelimited } from "./grid-text.js";
@@ -66,6 +76,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 +163,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 +342,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 +358,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 +383,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 +437,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`);
@@ -437,11 +482,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());
     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 +505,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.document.datasets?.[target.dataset.id] : undefined, numberFormat]);
     } catch {
       return "";
     }
@@ -488,6 +536,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 && supportsChartTableData;
+    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" || !supportsChartTableData;
+    if (mappingBox.hidden) return;
+    let view;
+    try {
+      view = describeChartMapping(editor.document, 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);

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";
+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 `createDataContent`) as a shared dataset, as `opf import-data --dataset <id>` does. Throws `dataset-id-invalid`. */
+export declare function prepareDatasetImport(document: 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";
+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 `createDataContent` 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(document, 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 createDataContent returned.", {});
+  const data = isTable ? content.table : content.chart.data;
+  const datasets = isObject(document) && isObject(document.datasets) ? document.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(document: unknown, visit: (entry: DatasetItem) => void): void;
+/** The charts and tables that use dataset `id`, in document order. */
+export declare function datasetUsage(document: 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(document, visit) {
+  if (!isObject(document) || !Array.isArray(document.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);
+    });
+  };
+  document.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(document, id) {
+  const items = [];
+  walkDatasetItems(document, (entry) => {
+    if (entry.id === id) items.push({ kind: entry.kind, path: entry.parts.join("."), parts: entry.parts });
+  });
+  return items;
+}

package/dist/design-controls.js

@@ -1009,9 +1009,11 @@ export function createDesignControls(container, options = {}) {
       const tablePath = parsed?.tablePath ?? (content?.key === "table" ? `${blockPath}.table` : undefined);
       dynamic.tablePath = tablePath;
       dynamic.cell = parsed?.cell;
-      tableUi.details.hidden = !tablePath;
-      if (tablePath) {
-        const table = editor.get(tablePath);
+      // A table that shows a shared dataset (RR-54) has no cell styles or merges: the table panel is for inline tables.
+      const tableValue = tablePath ? editor.get(tablePath) : undefined;
+      tableUi.details.hidden = !tablePath || !Array.isArray(tableValue?.rows);
+      if (tablePath && !tableUi.details.hidden) {
+        const table = tableValue;
         tableUi.summary.textContent = `Table (${tablePath})`;
         const style = readTableStyle(document_, tablePath);
         dynamic.tableStyle = style.preset === "custom" ? { header: "theme", banding: false, borders: "theme" } : { header: style.header, banding: style.banding, borders: style.borders };

package/dist/find-replace.js

@@ -97,14 +97,16 @@ function payloadFields(fields, state, base, payload, prefix = "") {
   const chart = payload.chart;
   if (isObject(chart) && isObject(chart.data)) {
     const { columns, rows } = chart.data;
-    if (Array.isArray(columns)) columns.forEach((value, index) => field(fields, state, at("chart", "data", "columns", String(index)), value, `${prefix}Chart label ${index + 1}`, "chart"));
+    // A column name that `mapping` addresses is not replaced: the mapping would stop finding it.
+    if (Array.isArray(columns) && !isObject(chart.mapping))
+      columns.forEach((value, index) => (isObject(value) ? field(fields, state, at("chart", "data", "columns", String(index), "name"), value.name, `${prefix}Chart label ${index + 1}`, "chart") : field(fields, state, at("chart", "data", "columns", String(index)), value, `${prefix}Chart label ${index + 1}`, "chart")));
     if (Array.isArray(rows)) rows.forEach((row, r) => Array.isArray(row) && row.forEach((value, c) => {
       if (typeof value === "string") field(fields, state, at("chart", "data", "rows", String(r), String(c)), value, `${prefix}Chart row ${r + 1}, column ${c + 1}`, "chart");
     }));
   }
   const table = payload.table;
   if (isObject(table)) {
-    if (Array.isArray(table.columns)) table.columns.forEach((cell, c) => cellFields(fields, state, at("table", "columns", String(c)), cell, `${prefix}Table header ${c + 1}`));
+    if (Array.isArray(table.columns)) table.columns.forEach((cell, c) => (isObject(cell) && !("value" in cell) ? field(fields, state, at("table", "columns", String(c), "name"), cell.name, `${prefix}Table header ${c + 1}`, "table") : cellFields(fields, state, at("table", "columns", String(c)), cell, `${prefix}Table header ${c + 1}`)));
     if (Array.isArray(table.rows)) table.rows.forEach((row, r) => Array.isArray(row) && row.forEach((cell, c) => cellFields(fields, state, at("table", "rows", String(r), String(c)), cell, `${prefix}Table row ${r + 1}, column ${c + 1}`)));
   }
   if (isObject(payload.image)) field(fields, state, at("image", "alt"), payload.image.alt, `${prefix}Image alt text`, "alt");
@@ -139,6 +141,16 @@ export function collectSearchFields(document, options = {}) {
     field(fields, deck, ["description"], document.description, "Presentation description", "deck");
     furnitureFields(fields, deck, [], document.design);
   }
+  // RR-54: the text cells of a shared dataset belong to the deck. Its column names are left alone (`fields` and `mapping` address them).
+  if (only === undefined && isObject(document.datasets)) {
+    const deck = { slideIndex: -1 };
+    for (const [id, dataset] of Object.entries(document.datasets)) {
+      if (!isObject(dataset) || !Array.isArray(dataset.rows)) continue;
+      dataset.rows.forEach((row, r) => Array.isArray(row) && row.forEach((value, c) => {
+        if (typeof value === "string") field(fields, deck, ["datasets", id, "rows", String(r), String(c)], value, `Dataset ${id}, row ${r + 1}, column ${c + 1}`, "dataset");
+      }));
+    }
+  }
   (Array.isArray(document.slides) ? document.slides : []).forEach((slide, slideIndex) => {
     if (only !== undefined && slideIndex !== only) return;
     if (!isObject(slide)) return;