@openpresentation/opf-editor 0.12.1 → 0.14.2

package/dist/chart-options.d.ts

@@ -9,7 +9,8 @@ export declare const CHART_LABEL_CONTENT: readonly ["category", "value", "percen
 
 /** What a chart type can show (core's `chartOptionSupport`). */
 export interface ChartOptionFields {
-  axisTitles: { category: boolean; value: boolean };
+  /** `secondary`: the type can title a secondary value axis (combo charts). */
+  axisTitles: { category: boolean; value: boolean; secondary: boolean };
   legend: boolean;
   dataLabels: {
     supported: boolean;
@@ -20,30 +21,55 @@ export interface ChartOptionFields {
     /** True for the constructs that label their marks by default (funnel, treemap). */
     defaultOn: boolean;
   };
+  /** What `chart.highlight` can name on this chart type: series, categories (one slice of a pie, one point of a line). */
+  highlight: { series: boolean; categories: boolean };
 }
-/** The three fields as form state. */
+/** The names a highlight can take on a chart, from its resolved data (empty when the data does not resolve). */
+export interface ChartHighlightChoices { series: string[]; categories: string[] }
+/** A plotted series of a combo chart: drawn as columns ("bar") or as a line, on the primary or secondary value axis (FA-15). */
+export interface ChartComboSeriesState {
+  name: string;
+  role: "bar" | "line";
+  axis: "primary" | "secondary";
+}
+/** The fields as form state. */
 export interface ChartOptionState {
-  axisTitles: { category: string; value: string };
+  /** The chart's text alternative (empty when absent or decorative). */
+  alt: string;
+  /** True when the chart is marked decorative (alt is the empty string). */
+  decorative: boolean;
+  axisTitles: { category: string; value: string; secondary: string };
   legend: ChartLegendChoice;
   dataLabels: { on: boolean; explicit: boolean; content: ChartLabelContent[]; position: ChartLabelPosition | "auto"; separator: string };
+  /** The series and categories `chart.highlight` names (empty lists when it is absent). */
+  highlight: { series: string[]; categories: string[] };
 }
 export interface ChartOptionChange {
-  axisTitles?: { category?: string; value?: string };
+  /** The text alternative: what the data shows. Trimmed; an empty string or null removes it. */
+  alt?: string | null;
+  /** true marks the chart decorative (alt ""); false removes an empty alt. */
+  decorative?: boolean;
+  axisTitles?: { category?: string; value?: string; secondary?: string };
+  /** Combo charts: the series drawn as lines, by name (at least one, and not every series). */
+  line?: string[];
+  /** Combo charts: the line series on the secondary value axis, by name. */
+  secondaryAxis?: string[];
   legend?: ChartLegendChoice;
   dataLabels?: boolean | null | { content?: ChartLabelContent[]; position?: ChartLabelPosition | "auto"; separator?: string };
+  /** `null` removes the highlight; a list replaces that part (an empty list removes it) and the other part is kept. */
+  highlight?: null | { series?: string[]; categories?: string[] };
 }
 export interface PreparedChartOptions {
   action: "chart-options";
   chartPath: string;
   changed: boolean;
   patches: JsonPatchOperation[];
-  document: unknown;
+  presentation: 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;
+/** `combo` is present on a combo chart: its plotted series in data order. Pass the `document` for a dataset-backed chart. */
+export declare function readChartOptions(chart: unknown, presentation?: unknown): { target: unknown; fields: ChartOptionFields; choices: ChartHighlightChoices; state: ChartOptionState; combo?: { series: ChartComboSeriesState[] } };
+export declare function prepareChartOptions(presentation: 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

@@ -1,13 +1,18 @@
-// 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
+// Chart options (RR-35): axis titles, legend position and data labels, plus (FA-09) the chart's text alternative `alt` and (FA-14) the
+// highlight. A chart is `{ type, data, alt?, axisTitles?, legend?, dataLabels?, highlight? }`. These helpers read the 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";
+// choice, and only a pie or doughnut can show percent. A highlight names plotted series and category labels (the
+// choices come from the chart's resolved data, so a dataset chart offers its dataset's columns and rows); a pie
+// highlights slices (categories), an area only series. Nothing here invents text. A combo chart (FA-15) also offers which series are lines (`line`), which lines use the secondary value
+// axis (`secondaryAxis`) and that axis's title.
+import { resolveChartData } from "@openpresentation/opf";
+import { chartOptionSupport, chartOptionTarget } from "@openpresentation/opf/composition";
+import { getValueAtPath, opfPathToJsonPointer, splitOpfPath } from "./index.js";
 import { checkedDocument, fail, same } from "./edit-helpers.js";
+import { checkFormat } from "./checks.js";
 
 export const CHART_LEGEND_POSITIONS = Object.freeze(["default", "none", "top", "bottom", "left", "right"]);
 export const CHART_LABEL_CONTENT = Object.freeze(["category", "value", "percent"]);
@@ -16,11 +21,6 @@ const isObject = (value) => Boolean(value) && typeof value === "object" && !Arra
 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;
@@ -33,38 +33,64 @@ export function parseChartPath(path) {
   return index >= 1 ? parts.slice(0, index + 1).join(".") : undefined;
 }
 
-function chartAt(document, chartPath) {
+function chartAt(presentation, chartPath) {
   const parts = splitOpfPath(chartPath);
-  const chart = getValueAtPath(document, parts);
+  const chart = getValueAtPath(presentation, 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 };
 }
 
+// The names a highlight can take, from the chart's resolved data: the plotted series (the columns after the category and, on a
+// scatter chart, the X column) and the distinct non-empty row labels. Empty when the data does not resolve.
+function highlightChoices(chart, document) {
+  const none = { series: [], categories: [] };
+  let resolved;
+  try { resolved = resolveChartData(chart, document); } catch { return none; }
+  if (!resolved?.ok || resolved.columns.length < 2) return none;
+  const first = resolved.hasX ? 2 : 1;
+  const label = (cell) => (cell === null || cell === undefined ? "" : String(cell));
+  return { series: resolved.columns.slice(first), categories: [...new Set(resolved.rows.map((row) => label(row[0])).filter(Boolean))] };
+}
+
+const names = (value) => (Array.isArray(value) ? [...new Set(value.filter((entry) => typeof entry === "string"))] : []);
+
 /**
- * What the chart options offer for `chart`, and the form state of the three fields.
+ * What the chart options offer for `chart`, and the form state of the fields. `presentation` (optional) resolves a dataset-backed
+ * chart's columns and rows for the highlight choices.
  * `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).
+ * `fields.axisTitles.secondary` is true on a combo chart, whose `combo.series` lists the plotted series ({ name, role, axis });
+ * pass the `presentation` for a dataset-backed chart.
  */
-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,
+export function readChartOptions(chart, presentation) {
+  const target = chartOptionTarget(chart?.type);
+  // A chart type outside the catalog is never restricted: every field is offered (a secondary axis exists only on combo charts).
+  const support = target ? chartOptionSupport(target) : {
+    axisTitles: { category: true, value: true, secondary: false }, legend: true,
     dataLabels: { supported: true, content: CONTENT_ORDER, positions: [...POSITIONS], defaultPosition: null, defaultOn: false },
+    highlight: { series: true, categories: true },
   };
   const titles = isObject(chart?.axisTitles) ? chart.axisTitles : {};
   const labels = chart?.dataLabels;
   const labelObject = isObject(labels) ? labels : {};
+  const combo = target?.kind === "combo" ? comboSeries(chart, presentation) : undefined;
   return {
     target,
     fields: {
-      axisTitles: { ...support.axisTitles },
+      axisTitles: { ...support.axisTitles, secondary: support.axisTitles.secondary === true },
       legend: support.legend,
       dataLabels: { ...support.dataLabels, content: [...support.dataLabels.content], positions: [...support.dataLabels.positions] },
+      highlight: { ...support.highlight },
     },
+    // FA-15: a combo chart's plotted series, each drawn as columns ("bar") or as a line, on the primary or secondary value axis.
+    ...(combo ? { combo: { series: combo } } : {}),
+    choices: highlightChoices(chart, presentation),
     state: {
-      axisTitles: { category: typeof titles.category === "string" ? titles.category : "", value: typeof titles.value === "string" ? titles.value : "" },
+      // FA-09: the text alternative. `decorative` is the empty alt, a reviewed choice, not a missing one.
+      alt: typeof chart?.alt === "string" ? chart.alt : "",
+      decorative: chart?.alt === "",
+      highlight: { series: names(chart?.highlight?.series), categories: names(chart?.highlight?.categories) },
+      axisTitles: { category: typeof titles.category === "string" ? titles.category : "", value: typeof titles.value === "string" ? titles.value : "", secondary: typeof titles.secondary === "string" ? titles.secondary : "" },
       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.
@@ -78,18 +104,64 @@ export function readChartOptions(chart) {
   };
 }
 
+/**
+ * FA-15: a combo chart's plotted series ({ name, role, axis }) in the data's plotted order (the mapping, else the columns), with
+ * the role and axis core resolves for each; [] when the data does not resolve.
+ */
+function comboSeries(chart, document) {
+  const resolved = resolveChartData(chart, document);
+  if (!resolved.ok || !Array.isArray(resolved.combo)) return [];
+  const plan = new Map(resolved.columns.slice(1).map((name, index) => [name, resolved.combo[index]]));
+  const { line: _line, secondaryAxis: _secondary, ...plain } = chart;
+  const plotted = resolveChartData({ ...plain, type: "column" }, document);
+  const names = plotted.ok ? plotted.columns.slice(1) : [...plan.keys()];
+  return names.filter((name) => plan.has(name)).map((name) => ({ name, role: plan.get(name)?.role ?? "bar", axis: plan.get(name)?.axis ?? "primary" }));
+}
+
+// FA-15: `line` and `secondaryAxis` for a combo chart from the wanted line and secondary-axis names. `line` is written only when
+// it differs from the default (the last plotted series), names keep the data's order, and only a line can use the secondary axis.
+function comboFields(chart, change, document) {
+  const series = comboSeries(chart, document);
+  const plotted = series.map((entry) => entry.name);
+  const currentLines = series.filter((entry) => entry.role === "line").map((entry) => entry.name);
+  const currentSecondary = series.filter((entry) => entry.axis === "secondary").map((entry) => entry.name);
+  const wanted = (value, current, field) => {
+    if (value === undefined) return current;
+    if (!Array.isArray(value) || value.some((name) => typeof name !== "string")) throw fail("invalid-chart-option", `${field} is a list of series names.`, { [field]: value });
+    const unknown = value.filter((name) => !plotted.includes(name));
+    if (unknown.length) throw fail("invalid-chart-option", `${unknown.map((name) => `'${name}'`).join(", ")} ${unknown.length === 1 ? "is not a plotted series" : "are not plotted series"} of this chart.`, { [field]: value });
+    return value;
+  };
+  const lines = wanted(change.line, currentLines, "line");
+  if (!lines.length) throw fail("invalid-chart-option", "A combo chart draws at least one series as a line; choose a column chart for columns only.", { line: change.line });
+  if (lines.length >= plotted.length) throw fail("invalid-chart-option", "A combo chart keeps at least one series as columns.", { line: change.line });
+  const ordered = plotted.filter((name) => lines.includes(name));
+  const secondary = plotted.filter((name) => ordered.includes(name) && wanted(change.secondaryAxis, currentSecondary, "secondaryAxis").includes(name));
+  const defaultLine = ordered.length === 1 && ordered[0] === plotted[plotted.length - 1];
+  return { line: defaultLine ? undefined : ordered, secondaryAxis: secondary.length ? secondary : undefined };
+}
+
 // The desired value of each field (undefined removes it), from the chart and a patch.
-function desired(chart, change, support) {
+function desired(chart, change, support, choices, current, document) {
   const out = {};
-  const current = readChartOptions(chart).state;
-  if (change.axisTitles !== undefined) {
+  const combo = support.axisTitles.secondary === true;
+  if (change.line !== undefined || change.secondaryAxis !== undefined) {
+    // Only a combo chart has line series; elsewhere the fields are removed.
+    Object.assign(out, combo ? comboFields(chart, change, document) : { line: undefined, secondaryAxis: undefined });
+  }
+  // The secondary axis title exists only while a series uses the secondary axis.
+  const hasSecondary = combo && (Object.hasOwn(out, "secondaryAxis") ? out.secondaryAxis !== undefined : Array.isArray(chart.secondaryAxis) && chart.secondaryAxis.length > 0);
+  if (change.axisTitles !== undefined || (current.axisTitles.secondary && !hasSecondary)) {
     const titles = {};
-    for (const axis of ["category", "value"]) {
+    for (const axis of ["category", "value", "secondary"]) {
       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();
+      if (typeof value === "string" && value.trim() && support.axisTitles[axis] && (axis !== "secondary" || hasSecondary)) titles[axis] = value.trim();
     }
     out.axisTitles = Object.keys(titles).length ? titles : undefined;
   }
+  if (change.decorative === true) out.alt = "";
+  else if (change.alt !== undefined) out.alt = typeof change.alt === "string" && change.alt.trim() ? change.alt.trim() : undefined;
+  else if (change.decorative === false && chart.alt === "") out.alt = 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;
@@ -112,22 +184,43 @@ function desired(chart, change, support) {
       out.dataLabels = Object.keys(next).length ? next : true;
     }
   }
+  if (change.highlight !== undefined) {
+    if (change.highlight === null) out.highlight = undefined;
+    else {
+      const next = {};
+      for (const part of ["series", "categories"]) {
+        const requested = change.highlight[part] !== undefined ? change.highlight[part] : current.highlight[part];
+        if (!Array.isArray(requested) || requested.some((entry) => typeof entry !== "string")) throw fail("invalid-chart-option", `Highlight ${part} must be a list of names.`, { part });
+        const listed = names(requested);
+        // A part the chart type cannot highlight is never written (a pie highlights slices, not series).
+        if (!support.highlight[part] || !listed.length) continue;
+        const unknown = choices[part].length ? listed.find((entry) => !choices[part].includes(entry)) : undefined;
+        if (unknown !== undefined) throw fail("invalid-chart-option", `'${unknown}' is not a ${part === "series" ? "plotted series" : "category label"} of this chart.`, { part, name: unknown });
+        next[part] = listed;
+      }
+      out.highlight = Object.keys(next).length ? next : undefined;
+    }
+  }
   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),
+ * `{ alt?, decorative?, axisTitles?: { category?, value?, secondary? }, legend?, dataLabels?, highlight?, line?, secondaryAxis? }`: `alt` is the text alternative (trimmed; empty or `null`
+ * removes it), `decorative: true` writes the empty alt (and wins over `alt`), `decorative: false` removes an empty alt; `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.
+ * `true`, `false` (or `null`, which removes the field), or `{ content?, position?, separator? }` merged over the current labels, and
+ * `highlight` is `null` (remove the field) or `{ series?, categories? }`: each list replaces that part (an empty list removes it, a name the
+ * chart does not have is refused) and the other part is kept. On a combo chart (FA-15), `line` lists the series drawn as lines and
+ * `secondaryAxis` the lines on the secondary value axis, by name; at least one series stays columns and at least one is a line, `line`
+ * is written only when it differs from the default (the last series), and the secondary axis title goes when no series uses that axis.
  * 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);
+export function prepareChartOptions(presentation, chartPath, change) {
+  const before = checkFormat(presentation);
+  const { parts, chart } = chartAt(presentation, chartPath);
+  const read = readChartOptions(chart, presentation);
+  const wanted = desired(chart, change, read.fields, read.choices, read.state, presentation);
   const patches = [];
   for (const [key, value] of Object.entries(wanted)) {
     const path = opfPathToJsonPointer([...parts, key]);
@@ -137,8 +230,8 @@ export function prepareChartOptions(document, chartPath, change) {
     } 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 };
+  const next = checkedDocument(presentation, patches, before);
+  return { action: "chart-options", chartPath, changed: patches.length > 0, patches, presentation: next };
 }
 
 function checkEditor(editor) {
@@ -148,10 +241,10 @@ function checkEditor(editor) {
 /** 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 prepared = prepareChartOptions(editor.presentation, chartPath, change);
+  const { presentation, patches, ...summary } = prepared;
+  void presentation;
+  if (!prepared.changed) return { ...summary, presentation: editor.presentation, 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/checks.js

@@ -0,0 +1,21 @@
+// The editor's one use of core's checker. Every edit is validated with `validate(presentation, { only: ["format"] })`: the
+// schema and semantic OPF rules, with no layout built, so it is cheap enough to run on every keystroke and undo. The full
+// report (accessibility, layout, content) belongs to the Review panel, which runs it on idle (`./review.js`).
+import { validate } from "@openpresentation/opf";
+
+const FORMAT_ONLY = Object.freeze({ only: Object.freeze(["format"]) });
+
+/** Core's `ValidationReport` for the `format` category: `valid`, `findings`, `counts`, `schemaValid`. */
+export function checkFormat(presentation) {
+  return validate(presentation, FORMAT_ONLY);
+}
+
+/** The error-severity findings of a report: what makes it invalid. */
+export function errorFindings(report) {
+  return (report?.findings ?? []).filter((finding) => finding.severity === "error");
+}
+
+/** The message of the first error finding, or `fallback` when the report has none. */
+export function firstErrorMessage(report, fallback) {
+  return errorFindings(report)[0]?.message ?? fallback;
+}

package/dist/color-authoring.js

@@ -6,7 +6,7 @@ const SCHEME_SLOTS = new Set([
 ]);
 
 const ROLE_KEYS = new Set([
-  "primary", "secondary", "accent", "background", "surface", "text", "textSecondary",
+  "primary", "secondary", "accent", "background", "surface", "surfaceAlt", "text", "textSecondary",
 ]);
 
 /** Whether a toolbar-authored text color matches documented ColorRef / TextRun forms. */

package/dist/content-actions.d.ts

@@ -7,7 +7,7 @@ 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;
+  presentation: 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. */
@@ -27,8 +27,8 @@ export interface PreparedContentAction {
   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;
+export interface ContentActionChange extends Omit<EditorChange, "presentation" | "patches"> {
+  presentation: unknown;
   patches: JsonPatchOperation[];
   changed: boolean;
   lossless: boolean;
@@ -53,17 +53,17 @@ export interface ListShiftOptions extends DryRunOptions {
 
 /** 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;
+export declare function prepareListShift(presentation: 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;
+export declare function prepareGroupBlocks(presentation: unknown, containerPath: string, indices: number[], options?: DryRunOptions & { composition?: Record<string, unknown> }): PreparedContentAction;
+export declare function prepareUngroupBlock(presentation: unknown, groupPath: string, options?: DryRunOptions): PreparedContentAction;
+export declare function prepareBlocksToRegions(presentation: unknown, slideIndex: number, regions: string[], options?: DryRunOptions): PreparedContentAction;
+export declare function prepareRegionsToBlocks(presentation: unknown, slideIndex: number, options?: DryRunOptions): PreparedContentAction;
+export declare function prepareMoveRegion(presentation: unknown, slideIndex: number, from: string, to: string, options?: DryRunOptions & { swap?: boolean }): PreparedContentAction;
+export declare function prepareImageToDesign(presentation: unknown, blockPath: string, target: ImageTarget, options?: DryRunOptions & PromoteImageOptions): PreparedContentAction;
+export declare function prepareImageToContent(presentation: 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;
@@ -77,10 +77,10 @@ export declare function moveImageToDesign(editor: EditorSession, blockPath: stri
 /** 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;
+export declare function prepareSplitSlide(presentation: unknown, slideIndex: number, options?: { at?: number[]; each?: boolean; repeatHeadings?: boolean }): PreparedContentAction;
+export declare function prepareSplitSlideOnOverflow(presentation: unknown, slideIndex: number, options?: PresentationPaginationOptions): PreparedContentAction;
+export declare function prepareMergeSlides(presentation: unknown, start: number, count?: number): PreparedContentAction;
+export declare function prepareUnpaginate(presentation: 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`. */