@openpresentation/opf-editor 0.10.6 → 0.11.0

package/dist/chart-data.js

@@ -0,0 +1,101 @@
+// Chart data (RR-24): edit the inline data of a chart, `{ type, data: { columns, rows } }`. The first column holds the categories
+// and every further column is a series named by its column label (a scatter chart with three or more columns reads x values from the
+// second). Cells are text for names and categories and numbers for values; a gap is null and stays a gap, never 0. Each operation is
+// one validated, undoable patch (grid-model.js has the implementation; grid-text.js documents number reading).
+//
+// `prepare*` computes `{ document, patches, changed }` without touching a session; the session forms apply it as one undo step.
+import {
+  prepareGridCells,
+  preparePaste,
+  prepareInsertRows,
+  prepareDeleteRows,
+  prepareMoveRows,
+  prepareInsertColumns,
+  prepareDeleteColumns,
+  prepareMoveColumns,
+  prepareSortRows,
+  setGridCells,
+  pasteGridText,
+  insertGridRows,
+  deleteGridRows,
+  moveGridRows,
+  insertGridColumns,
+  deleteGridColumns,
+  moveGridColumns,
+  sortGridRows,
+  prepareTranspose,
+  transposeGridData,
+} from "./grid-model.js";
+export function prepareChartCells(document, chartPath, edits, options = {}) {
+  return prepareGridCells(document, chartPath, edits, { ...options, kind: "chart" });
+}
+export function setChartCells(editor, chartPath, edits, options = {}) {
+  return setGridCells(editor, chartPath, edits, { ...options, kind: "chart" });
+}
+export function prepareChartPaste(document, chartPath, anchor, source, options = {}) {
+  return preparePaste(document, chartPath, anchor, source, { ...options, kind: "chart" });
+}
+export function pasteChartText(editor, chartPath, anchor, source, options = {}) {
+  return pasteGridText(editor, chartPath, anchor, source, { ...options, kind: "chart" });
+}
+export function prepareChartInsertRows(document, chartPath, at, count = 1, options = {}) {
+  return prepareInsertRows(document, chartPath, at, count, { ...options, kind: "chart" });
+}
+export function insertChartRows(editor, chartPath, at, count = 1, options = {}) {
+  return insertGridRows(editor, chartPath, at, count, { ...options, kind: "chart" });
+}
+export function prepareChartDeleteRows(document, chartPath, indices, options = {}) {
+  return prepareDeleteRows(document, chartPath, indices, { ...options, kind: "chart" });
+}
+export function deleteChartRows(editor, chartPath, indices, options = {}) {
+  return deleteGridRows(editor, chartPath, indices, { ...options, kind: "chart" });
+}
+export function prepareChartMoveRows(document, chartPath, from, to, count = 1, options = {}) {
+  return prepareMoveRows(document, chartPath, from, to, count, { ...options, kind: "chart" });
+}
+export function moveChartRows(editor, chartPath, from, to, count = 1, options = {}) {
+  return moveGridRows(editor, chartPath, from, to, count, { ...options, kind: "chart" });
+}
+export function prepareChartInsertColumns(document, chartPath, at, count = 1, options = {}) {
+  return prepareInsertColumns(document, chartPath, at, count, { ...options, kind: "chart" });
+}
+export function insertChartColumns(editor, chartPath, at, count = 1, options = {}) {
+  return insertGridColumns(editor, chartPath, at, count, { ...options, kind: "chart" });
+}
+export function prepareChartDeleteColumns(document, chartPath, indices, options = {}) {
+  return prepareDeleteColumns(document, chartPath, indices, { ...options, kind: "chart" });
+}
+export function deleteChartColumns(editor, chartPath, indices, options = {}) {
+  return deleteGridColumns(editor, chartPath, indices, { ...options, kind: "chart" });
+}
+export function prepareChartMoveColumns(document, chartPath, from, to, count = 1, options = {}) {
+  return prepareMoveColumns(document, chartPath, from, to, count, { ...options, kind: "chart" });
+}
+export function moveChartColumns(editor, chartPath, from, to, count = 1, options = {}) {
+  return moveGridColumns(editor, chartPath, from, to, count, { ...options, kind: "chart" });
+}
+export function prepareChartSort(document, chartPath, column, options = {}) {
+  return prepareSortRows(document, chartPath, column, { ...options, kind: "chart" });
+}
+export function sortChartRows(editor, chartPath, column, options = {}) {
+  return sortGridRows(editor, chartPath, column, { ...options, kind: "chart" });
+}
+
+/** Swap categories and series: the first column's values become the series names and each series becomes a row. See {@link prepareTranspose}. */
+export function prepareChartTranspose(document, chartPath) {
+  return prepareTranspose(document, chartPath);
+}
+export function transposeChart(editor, chartPath, options = {}) {
+  return transposeGridData(editor, chartPath, options);
+}
+
+/** Rename a series: the label of data column `column` (1 or more). */
+export function renameChartSeries(editor, chartPath, column, name, options = {}) {
+  if (!Number.isInteger(column) || column < 1) throw new TypeError("A series is a column after the first.");
+  return setGridCells(editor, chartPath, [{ section: "header", column, value: String(name) }], { ...options, kind: "chart" });
+}
+
+/** Rename a category: the first-column label of body row `row`. An empty name leaves the category blank. */
+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" });
+}

package/dist/chart-options-panel.d.ts

@@ -0,0 +1,16 @@
+import type { EditorSession } from "./index.js";
+
+export interface ChartOptionsPanelOptions {
+  editor: EditorSession;
+  /** The selected OPF path; any path inside a chart selects it. */
+  getSelectedPath: () => string | undefined;
+  onStatus?: (message: string) => void;
+}
+export interface ChartOptionsPanel {
+  /** The panel's root element; undefined when the installed core has no chart option fields. */
+  element: HTMLElement | undefined;
+  /** Re-read the selection and the chart; the panel also refreshes on every editor change. */
+  refresh(): void;
+  destroy(): void;
+}
+export declare function createChartOptionsPanel(host: HTMLElement, options: ChartOptionsPanelOptions): ChartOptionsPanel;

package/dist/chart-options-panel.js

@@ -0,0 +1,127 @@
+// The chart options panel (RR-35): axis titles, legend position and data labels for the selected chart.
+// It mounts into any host element over an editor session; every control commits one undoable change through
+// `setChartOptions` (src/chart-options.js), the canvas redraws, and Undo restores the chart. The panel shows only what
+// the selected chart type can show (core's support table), and hides itself when no chart is selected.
+import { CHART_LABEL_CONTENT, CHART_LEGEND_POSITIONS, chartOptionsAvailable, parseChartPath, readChartOptions, setChartOptions } from "./chart-options.js";
+
+const LEGEND_LABELS = { default: "Default", none: "None", top: "Top", bottom: "Bottom", left: "Left", right: "Right" };
+const CONTENT_LABELS = { category: "Category", value: "Value", percent: "Percent" };
+const POSITION_LABELS = { auto: "Automatic", center: "Center", "inside-end": "Inside end", "inside-base": "Inside base", "outside-end": "Outside end", above: "Above", below: "Below", left: "Left", right: "Right" };
+
+let counter = 0;
+
+/**
+ * Mount the panel in `host`. `getSelectedPath()` returns the selected OPF path (any path inside a chart selects it);
+ * `onStatus(message)` receives a short message after each change. Returns `{ element, refresh, destroy }`;
+ * call `refresh()` when the selection changes (the panel also refreshes on every editor change).
+ */
+export function createChartOptionsPanel(host, { editor, getSelectedPath, onStatus = () => {} }) {
+  if (!chartOptionsAvailable()) return { refresh() {}, destroy() {}, element: undefined };
+  const id = `opf-chart-options-${++counter}`;
+  const root = document.createElement("section");
+  root.className = "opf-chart-options";
+  root.setAttribute("aria-label", "Chart options");
+  root.hidden = true;
+  root.innerHTML = `
+    <h3 class="opf-co-title">Chart options</h3>
+    <div class="opf-co-group" data-group="axisTitles">
+      <label class="opf-co-row" data-axis="category"><span>Category axis title</span><input type="text" id="${id}-category" aria-label="Category axis title" data-opf-chart-option="axisTitles.category" autocomplete="off"></label>
+      <label class="opf-co-row" data-axis="value"><span>Value axis title</span><input type="text" id="${id}-value" aria-label="Value axis title" data-opf-chart-option="axisTitles.value" autocomplete="off"></label>
+    </div>
+    <div class="opf-co-group" data-group="legend">
+      <label class="opf-co-row"><span>Legend</span><select id="${id}-legend" aria-label="Legend" data-opf-chart-option="legend">${CHART_LEGEND_POSITIONS.map((value) => `<option value="${value}">${LEGEND_LABELS[value]}</option>`).join("")}</select></label>
+    </div>
+    <div class="opf-co-group" data-group="dataLabels">
+      <label class="opf-co-row opf-co-check"><input type="checkbox" id="${id}-labels" aria-label="Data labels" data-opf-chart-option="dataLabels.on"><span>Data labels</span></label>
+      <fieldset class="opf-co-content"><legend>Label shows</legend>${CHART_LABEL_CONTENT.map((part) => `<label class="opf-co-check"><input type="checkbox" value="${part}" aria-label="Label shows ${CONTENT_LABELS[part].toLowerCase()}" data-opf-chart-option="dataLabels.content.${part}"><span>${CONTENT_LABELS[part]}</span></label>`).join("")}</fieldset>
+      <label class="opf-co-row" data-row="position"><span>Label position</span><select id="${id}-position" aria-label="Label position" data-opf-chart-option="dataLabels.position"></select></label>
+      <label class="opf-co-row" data-row="separator"><span>Separator</span><input type="text" id="${id}-separator" aria-label="Label separator" data-opf-chart-option="dataLabels.separator" autocomplete="off"></label>
+    </div>`;
+  host.append(root);
+  const $ = (selector) => root.querySelector(selector);
+  const fields = {
+    category: $(`#${id}-category`), value: $(`#${id}-value`), legend: $(`#${id}-legend`), labels: $(`#${id}-labels`),
+    position: $(`#${id}-position`), separator: $(`#${id}-separator`), contents: [...root.querySelectorAll("[data-opf-chart-option^='dataLabels.content.']")],
+  };
+  let chartPath;
+
+  function refresh() {
+    const path = parseChartPath(getSelectedPath?.() ?? "");
+    let chart;
+    try { chart = path ? editor.get(path) : undefined; } catch { chart = undefined; }
+    if (!path || !chart || typeof chart !== "object" || typeof chart.type !== "string") {
+      root.hidden = true;
+      chartPath = undefined;
+      return;
+    }
+    chartPath = path;
+    const { fields: support, state } = readChartOptions(chart);
+    root.hidden = false;
+    const setValue = (input, value) => { if (input !== document.activeElement && input.value !== value) input.value = value; };
+    for (const axis of ["category", "value"]) {
+      $(`[data-axis="${axis}"]`).hidden = !support.axisTitles[axis];
+      setValue(fields[axis], state.axisTitles[axis]);
+    }
+    $("[data-group='axisTitles']").hidden = !support.axisTitles.category && !support.axisTitles.value;
+    $("[data-group='legend']").hidden = !support.legend;
+    fields.legend.value = state.legend;
+    $("[data-group='dataLabels']").hidden = !support.dataLabels.supported;
+    fields.labels.checked = state.dataLabels.on;
+    const off = !state.dataLabels.on;
+    for (const input of fields.contents) {
+      input.closest("label").hidden = !support.dataLabels.content.includes(input.value);
+      input.checked = state.dataLabels.content.includes(input.value);
+      input.disabled = off;
+    }
+    const positions = ["auto", ...support.dataLabels.positions];
+    $("[data-row='position']").hidden = support.dataLabels.positions.length === 0;
+    if (fields.position.dataset.options !== positions.join()) {
+      fields.position.innerHTML = positions.map((value) => `<option value="${value}">${POSITION_LABELS[value]}</option>`).join("");
+      fields.position.dataset.options = positions.join();
+    }
+    fields.position.value = positions.includes(state.dataLabels.position) ? state.dataLabels.position : "auto";
+    fields.position.disabled = off;
+    setValue(fields.separator, state.dataLabels.separator);
+    fields.separator.disabled = off || state.dataLabels.content.length < 2;
+    $("[data-row='separator']").hidden = support.dataLabels.content.length < 2;
+  }
+
+  function commit(change, message) {
+    if (!chartPath) return;
+    try {
+      const result = setChartOptions(editor, chartPath, change, { source: "chart-options-panel" });
+      if (result.changed) onStatus(message);
+    } catch (error) {
+      onStatus(error?.message ?? String(error));
+    }
+    refresh();
+  }
+
+  const selectedContent = () => fields.contents.filter((input) => input.checked && !input.closest("label").hidden).map((input) => input.value);
+  const listeners = [
+    [fields.category, "change", () => commit({ axisTitles: { category: fields.category.value } }, "Changed the category axis title. Undo restores it.")],
+    [fields.value, "change", () => commit({ axisTitles: { value: fields.value.value } }, "Changed the value axis title. Undo restores it.")],
+    [fields.legend, "change", () => commit({ legend: fields.legend.value }, "Changed the legend. Undo restores it.")],
+    [fields.labels, "change", () => commit({ dataLabels: fields.labels.checked }, fields.labels.checked ? "Showing data labels. Undo restores the chart." : "Hid the data labels. Undo restores them.")],
+    [fields.position, "change", () => commit({ dataLabels: { position: fields.position.value } }, "Moved the data labels. Undo restores them.")],
+    [fields.separator, "change", () => commit({ dataLabels: { separator: fields.separator.value } }, "Changed the label separator. Undo restores it.")],
+    ...fields.contents.map((input) => [input, "change", () => {
+      const content = selectedContent();
+      // A label always shows something: unticking the last part keeps it.
+      if (!content.length) { input.checked = true; return; }
+      commit({ dataLabels: { content } }, "Changed what the data labels show. Undo restores them.");
+    }]),
+  ];
+  for (const [element, type, handler] of listeners) element.addEventListener(type, handler);
+  const unsubscribe = editor.subscribe?.(refresh);
+  refresh();
+  return {
+    element: root,
+    refresh,
+    destroy() {
+      for (const [element, type, handler] of listeners) element.removeEventListener(type, handler);
+      if (typeof unsubscribe === "function") unsubscribe();
+      root.remove();
+    },
+  };
+}

package/dist/chart-options.d.ts

@@ -0,0 +1,49 @@
+import type { EditorChange, EditorSession, JsonPatchOperation } from "./index.js";
+
+export type ChartLegendChoice = "default" | "none" | "top" | "bottom" | "left" | "right";
+export type ChartLabelContent = "category" | "value" | "percent";
+export type ChartLabelPosition = "center" | "inside-end" | "inside-base" | "outside-end" | "above" | "below" | "left" | "right";
+
+export declare const CHART_LEGEND_POSITIONS: readonly ["default", "none", "top", "bottom", "left", "right"];
+export declare const CHART_LABEL_CONTENT: readonly ["category", "value", "percent"];
+
+/** What a chart type can show (core's `chartOptionSupport`). */
+export interface ChartOptionFields {
+  axisTitles: { category: boolean; value: boolean };
+  legend: boolean;
+  dataLabels: {
+    supported: boolean;
+    content: ChartLabelContent[];
+    /** Empty when labels have no position choice (area, doughnut, radar, funnel, treemap). */
+    positions: ChartLabelPosition[];
+    defaultPosition: ChartLabelPosition | null;
+    /** True for the constructs that label their marks by default (funnel, treemap). */
+    defaultOn: boolean;
+  };
+}
+/** The three fields as form state. */
+export interface ChartOptionState {
+  axisTitles: { category: string; value: string };
+  legend: ChartLegendChoice;
+  dataLabels: { on: boolean; explicit: boolean; content: ChartLabelContent[]; position: ChartLabelPosition | "auto"; separator: string };
+}
+export interface ChartOptionChange {
+  axisTitles?: { category?: string; value?: string };
+  legend?: ChartLegendChoice;
+  dataLabels?: boolean | null | { content?: ChartLabelContent[]; position?: ChartLabelPosition | "auto"; separator?: string };
+}
+export interface PreparedChartOptions {
+  action: "chart-options";
+  chartPath: string;
+  changed: boolean;
+  patches: JsonPatchOperation[];
+  document: unknown;
+}
+
+/** True when the installed core knows the chart option fields. */
+export declare function chartOptionsAvailable(): boolean;
+/** The chart path a selection path points at, or undefined. */
+export declare function parseChartPath(path: string): string | undefined;
+export declare function readChartOptions(chart: unknown): { target: unknown; fields: ChartOptionFields; state: ChartOptionState };
+export declare function prepareChartOptions(document: unknown, chartPath: string, change: ChartOptionChange): PreparedChartOptions;
+export declare function setChartOptions(editor: EditorSession, chartPath: string, change: ChartOptionChange, meta?: Record<string, unknown>): EditorChange & { action: "chart-options"; chartPath: string; changed: boolean };

package/dist/chart-options.js

@@ -0,0 +1,157 @@
+// Chart options (RR-35): axis titles, legend position and data labels. A chart is
+// `{ type, data, axisTitles?, legend?, dataLabels? }`. These helpers read the three fields as form
+// state and edit them as one validated, undoable patch (a few add / replace / remove operations
+// on the chart, one undo step), so the canvas redraws the legend, titles and labels and Undo
+// restores the chart. Which fields a chart offers follows core's support table
+// (`chartOptionSupport`): a pie has no axis titles, area and radar labels have no position
+// choice, and only a pie or doughnut can show percent. Nothing here invents text.
+import * as core from "@openpresentation/opf";
+import { getValueAtPath, opfPathToJsonPointer, splitOpfPath, validateOpfDocument } from "./index.js";
+import { checkedDocument, fail, same } from "./edit-helpers.js";
+
+export const CHART_LEGEND_POSITIONS = Object.freeze(["default", "none", "top", "bottom", "left", "right"]);
+export const CHART_LABEL_CONTENT = Object.freeze(["category", "value", "percent"]);
+
+const isObject = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+const CONTENT_ORDER = CHART_LABEL_CONTENT;
+const POSITIONS = new Set(["center", "inside-end", "inside-base", "outside-end", "above", "below", "left", "right"]);
+
+/** True when the installed core knows the chart option fields; an older core leaves the panel out. */
+export function chartOptionsAvailable() {
+  return typeof core.chartOptionSupport === "function" && typeof core.chartOptionTarget === "function" && typeof core.resolveChartOptions === "function";
+}
+
+/** The chart path a selection path points at (`…chart`, `…chart.data.rows.0.1`), or undefined. */
+export function parseChartPath(path) {
+  let parts;
+  try {
+    parts = splitOpfPath(path);
+  } catch {
+    return undefined;
+  }
+  const index = parts.lastIndexOf("chart");
+  return index >= 1 ? parts.slice(0, index + 1).join(".") : undefined;
+}
+
+function chartAt(document, chartPath) {
+  const parts = splitOpfPath(chartPath);
+  const chart = getValueAtPath(document, parts);
+  if (!isObject(chart) || typeof chart.type !== "string") throw fail("chart-not-found", "Choose a chart (a path ending in .chart).", { chartPath });
+  return { parts, chart };
+}
+
+/**
+ * What the chart options offer for `chart`, and the form state of the three fields.
+ * `fields.axisTitles.category` and `.value` say whether the type has that axis; `fields.legend` whether it has a legend;
+ * `fields.dataLabels` the contents and positions it accepts (`positions` is empty when labels have no position choice).
+ */
+export function readChartOptions(chart) {
+  if (!chartOptionsAvailable()) throw fail("chart-options-unavailable", "The installed @openpresentation/opf does not know the chart option fields.");
+  const target = core.chartOptionTarget(chart?.type);
+  // A chart type outside the catalog is never restricted: every field is offered.
+  const support = target ? core.chartOptionSupport(target) : {
+    axisTitles: { category: true, value: true }, legend: true,
+    dataLabels: { supported: true, content: CONTENT_ORDER, positions: [...POSITIONS], defaultPosition: null, defaultOn: false },
+  };
+  const titles = isObject(chart?.axisTitles) ? chart.axisTitles : {};
+  const labels = chart?.dataLabels;
+  const labelObject = isObject(labels) ? labels : {};
+  return {
+    target,
+    fields: {
+      axisTitles: { ...support.axisTitles },
+      legend: support.legend,
+      dataLabels: { ...support.dataLabels, content: [...support.dataLabels.content], positions: [...support.dataLabels.positions] },
+    },
+    state: {
+      axisTitles: { category: typeof titles.category === "string" ? titles.category : "", value: typeof titles.value === "string" ? titles.value : "" },
+      legend: typeof chart?.legend === "string" ? chart.legend : "default",
+      dataLabels: {
+        // Funnel and treemap label their marks by default, so `dataLabels: false` is what switches them off.
+        on: labels === true || isObject(labels) || (labels === undefined && support.dataLabels.defaultOn),
+        explicit: labels !== undefined,
+        content: Array.isArray(labelObject.content) && labelObject.content.length ? CONTENT_ORDER.filter((part) => labelObject.content.includes(part)) : (labels === undefined && support.dataLabels.defaultOn ? [target?.kind === "treemap" ? "category" : "value"] : ["value"]),
+        position: typeof labelObject.position === "string" ? labelObject.position : "auto",
+        separator: typeof labelObject.separator === "string" ? labelObject.separator : ", ",
+      },
+    },
+  };
+}
+
+// The desired value of each field (undefined removes it), from the chart and a patch.
+function desired(chart, change, support) {
+  const out = {};
+  const current = readChartOptions(chart).state;
+  if (change.axisTitles !== undefined) {
+    const titles = {};
+    for (const axis of ["category", "value"]) {
+      const value = change.axisTitles?.[axis] !== undefined ? change.axisTitles[axis] : current.axisTitles[axis];
+      if (typeof value === "string" && value.trim() && support.axisTitles[axis]) titles[axis] = value.trim();
+    }
+    out.axisTitles = Object.keys(titles).length ? titles : undefined;
+  }
+  if (change.legend !== undefined) {
+    if (change.legend !== "default" && !CHART_LEGEND_POSITIONS.includes(change.legend)) throw fail("invalid-chart-option", `'${change.legend}' is not a legend position.`, { legend: change.legend });
+    out.legend = change.legend === "default" || !support.legend ? undefined : change.legend;
+  }
+  if (change.dataLabels !== undefined) {
+    const labels = change.dataLabels;
+    if (labels === null || labels === false || labels === "off") {
+      // false is only meaningful where a construct labels its marks by default; elsewhere no labels is the absence of the field.
+      out.dataLabels = support.dataLabels.defaultOn && labels !== null ? false : undefined;
+    } else if (!support.dataLabels.supported) {
+      out.dataLabels = undefined;
+    } else {
+      const base = isObject(chart.dataLabels) ? chart.dataLabels : {};
+      const merged = labels === true ? {} : { ...base, ...labels };
+      const next = {};
+      const content = Array.isArray(merged.content) ? CONTENT_ORDER.filter((part) => merged.content.includes(part) && support.dataLabels.content.includes(part)) : [];
+      if (content.length && !(content.length === 1 && content[0] === "value")) next.content = content;
+      if (typeof merged.position === "string" && merged.position !== "auto" && support.dataLabels.positions.includes(merged.position)) next.position = merged.position;
+      if (typeof merged.separator === "string" && merged.separator !== ", " && merged.separator !== "") next.separator = merged.separator.replace(/[\r\n]+/g, " ");
+      out.dataLabels = Object.keys(next).length ? next : true;
+    }
+  }
+  return out;
+}
+
+/**
+ * Prepare one validated patch for a change to the chart's options. `change` is
+ * `{ axisTitles?: { category?, value? }, legend?, dataLabels? }`: `axisTitles` entries are strings (empty removes a title),
+ * `legend` is `"default"` (remove the field), `"none"`, `"top"`, `"bottom"`, `"left"` or `"right"`, and `dataLabels` is
+ * `true`, `false` (or `null`, which removes the field), or `{ content?, position?, separator? }` merged over the current labels.
+ * Fields the chart type cannot show are never written. The document is not modified.
+ */
+export function prepareChartOptions(document, chartPath, change) {
+  if (!chartOptionsAvailable()) throw fail("chart-options-unavailable", "The installed @openpresentation/opf does not know the chart option fields.");
+  const before = validateOpfDocument(document);
+  const { parts, chart } = chartAt(document, chartPath);
+  const support = readChartOptions(chart).fields;
+  const wanted = desired(chart, change, support);
+  const patches = [];
+  for (const [key, value] of Object.entries(wanted)) {
+    const path = opfPathToJsonPointer([...parts, key]);
+    const present = Object.hasOwn(chart, key);
+    if (value === undefined) {
+      if (present) patches.push({ op: "remove", path });
+    } else if (!present) patches.push({ op: "add", path, value: structuredClone(value) });
+    else if (!same(chart[key], value)) patches.push({ op: "replace", path, value: structuredClone(value) });
+  }
+  const next = checkedDocument(document, patches, before);
+  return { action: "chart-options", chartPath, changed: patches.length > 0, patches, document: next };
+}
+
+function checkEditor(editor) {
+  if (!editor || typeof editor.applyPatch !== "function" || typeof editor.subscribe !== "function") throw fail("invalid-editor", "Expected an editor session created by createEditorSession.");
+}
+
+/** Apply a chart option change to an editor session as one undoable edit. Returns the editor change. */
+export function setChartOptions(editor, chartPath, change, meta = {}) {
+  checkEditor(editor);
+  const prepared = prepareChartOptions(editor.document, chartPath, change);
+  const { document, patches, ...summary } = prepared;
+  void document;
+  if (!prepared.changed) return { ...summary, document: editor.document, patches: [], inversePatches: [], validation: editor.validation };
+  const applied = editor.applyPatch(patches, { ...meta, source: meta.source ?? "chart-option", action: prepared.action, path: chartPath });
+  return { ...applied, ...summary };
+}

package/dist/content-actions.d.ts

@@ -0,0 +1,91 @@
+import type { ImageTarget, PromoteImageOptions } from "@openpresentation/opf/convert";
+import type { PresentationPaginationOptions, PaginatedPage } from "@openpresentation/opf/pagination";
+import type { EditorChange, EditorSession, JsonPatchOperation } from "./index.js";
+
+export type { ImageTarget, PromoteImageOptions } from "@openpresentation/opf/convert";
+export type SlidePages = readonly (PaginatedPage & { sourceSlideIndex: number })[];
+
+/** What every prepare function returns without touching a session. A refusal throws `content-action-refused`. */
+export interface PreparedContentAction {
+  document: unknown;
+  /** A `test` of what was read, then `replace`, or per-slide `remove` and `add`. Empty when nothing changed. */
+  patches: JsonPatchOperation[];
+  /** The path of the block or slide the change touched: select it again after applying. */
+  path: string;
+  changed: boolean;
+  /** True when nothing is lost; otherwise `loss` names what the result cannot carry. */
+  lossless: boolean;
+  loss: string[];
+  /** Why nothing changed (`changed` is false), when core can say. */
+  reason?: string;
+  /** List shifts: the nesting level of every item after the change. */
+  levels?: number[];
+  /** Slide edits: the old slides replaced (`deleteCount` from `start`) and how many slides replace them. */
+  range?: { start: number; deleteCount: number };
+  slideCount?: number;
+  /** Split on overflow: the pagination mapping of the new slides, for `unpaginateSlides`. */
+  pages?: (PaginatedPage & { sourceSlideIndex: number })[];
+}
+/** The session change of an applied action, with the same report fields. One undo step. */
+export interface ContentActionChange extends Omit<EditorChange, "document" | "patches"> {
+  document: unknown;
+  patches: JsonPatchOperation[];
+  changed: boolean;
+  lossless: boolean;
+  loss: string[];
+  path: string;
+  levels?: number[];
+  reason?: string;
+  range?: { start: number; deleteCount: number };
+  slideCount?: number;
+  pages?: (PaginatedPage & { sourceSlideIndex: number })[];
+}
+
+/** Every prepare function takes `validate: false` in its options for a dry run that skips the whole-document validation (the converted slide is still validated). Applying always validates. */
+export interface DryRunOptions {
+  validate?: boolean;
+}
+
+export interface ListShiftOptions extends DryRunOptions {
+  /** Move the items nested under each selected item with it (default true). */
+  withChildren?: boolean;
+}
+
+/** The index of the list item a selection points at (`slides.0.blocks.1.items.2.text` gives 2), or undefined. */
+export declare function listItemIndexForSelection(selectedPath: string, blockPath: string): number | undefined;
+export declare function prepareListShift(document: unknown, blockPath: string, indices: number[], delta: number, options?: ListShiftOptions): PreparedContentAction;
+/** Nest (`delta` 1) or un-nest (`delta` -1) list items as one undoable step. */
+export declare function shiftListItems(editor: EditorSession, blockPath: string, indices: number[], delta: number, options?: ListShiftOptions, meta?: Record<string, unknown>): ContentActionChange;
+
+export declare function prepareGroupBlocks(document: unknown, containerPath: string, indices: number[], options?: DryRunOptions & { composition?: Record<string, unknown> }): PreparedContentAction;
+export declare function prepareUngroupBlock(document: unknown, groupPath: string, options?: DryRunOptions): PreparedContentAction;
+export declare function prepareBlocksToRegions(document: unknown, slideIndex: number, regions: string[], options?: DryRunOptions): PreparedContentAction;
+export declare function prepareRegionsToBlocks(document: unknown, slideIndex: number, options?: DryRunOptions): PreparedContentAction;
+export declare function prepareMoveRegion(document: unknown, slideIndex: number, from: string, to: string, options?: DryRunOptions & { swap?: boolean }): PreparedContentAction;
+export declare function prepareImageToDesign(document: unknown, blockPath: string, target: ImageTarget, options?: DryRunOptions & PromoteImageOptions): PreparedContentAction;
+export declare function prepareImageToContent(document: unknown, slideIndex: number, source: ImageTarget, options?: DryRunOptions & { index?: number; region?: string }): PreparedContentAction;
+
+/** Wrap the blocks at `indices` of a slide, group or region group in a new group. */
+export declare function groupBlocks(editor: EditorSession, containerPath: string, indices: number[], options?: { composition?: Record<string, unknown> }, meta?: Record<string, unknown>): ContentActionChange;
+/** Replace a group by its blocks; its composition and id are reported in `loss`. */
+export declare function ungroupBlock(editor: EditorSession, groupPath: string, meta?: Record<string, unknown>): ContentActionChange;
+export declare function placeBlocksInRegions(editor: EditorSession, slideIndex: number, regions: string[], meta?: Record<string, unknown>): ContentActionChange;
+export declare function regionsAsBlocks(editor: EditorSession, slideIndex: number, meta?: Record<string, unknown>): ContentActionChange;
+export declare function moveSlideRegion(editor: EditorSession, slideIndex: number, from: string, to: string, options?: { swap?: boolean }, meta?: Record<string, unknown>): ContentActionChange;
+/** Move an image block into the slide's design as its slide image, background or watermark. */
+export declare function moveImageToDesign(editor: EditorSession, blockPath: string, target: ImageTarget, options?: PromoteImageOptions, meta?: Record<string, unknown>): ContentActionChange;
+/** Move a slide's own slide image, background image or watermark back into its content as an image block. */
+export declare function moveImageToContent(editor: EditorSession, slideIndex: number, source: ImageTarget, options?: { index?: number; region?: string }, meta?: Record<string, unknown>): ContentActionChange;
+
+export declare function prepareSplitSlide(document: unknown, slideIndex: number, options?: { at?: number[]; each?: boolean; repeatHeadings?: boolean }): PreparedContentAction;
+export declare function prepareSplitSlideOnOverflow(document: unknown, slideIndex: number, options?: PresentationPaginationOptions): PreparedContentAction;
+export declare function prepareMergeSlides(document: unknown, start: number, count?: number): PreparedContentAction;
+export declare function prepareUnpaginate(document: unknown, pages: SlidePages, options?: { sourceSlideIndex?: number }): PreparedContentAction;
+/** Split a slide by its blocks into several slides, as one undoable step. */
+export declare function splitSlideByBlocks(editor: EditorSession, slideIndex: number, options?: { at?: number[]; each?: boolean; repeatHeadings?: boolean }, meta?: Record<string, unknown>): ContentActionChange;
+/** Split a slide that overflows with the existing pagination; the change carries `pages` for `unpaginateSlides`. */
+export declare function splitSlideOnOverflow(editor: EditorSession, slideIndex: number, options?: PresentationPaginationOptions, meta?: Record<string, unknown>): ContentActionChange;
+/** Merge consecutive slides into one. The first slide's id, headings and design win; what is dropped is reported in `loss`. */
+export declare function mergeSlides(editor: EditorSession, start: number, count?: number, meta?: Record<string, unknown>): ContentActionChange;
+/** Put paginated continuation slides back together, given the `pages` mapping of the pagination. */
+export declare function unpaginateSlides(editor: EditorSession, pages: SlidePages, options?: { sourceSlideIndex?: number }, meta?: Record<string, unknown>): ContentActionChange;