@openpresentation/opf-editor 0.12.1 → 0.15.0

package/dist/table-options.d.ts

@@ -39,15 +39,15 @@ export interface TableCellState extends TableCellAddress {
 export interface PreparedTableChange {
   action: "merge" | "split" | "style" | "table-style";
   tablePath: string;
-  document: unknown;
+  presentation: unknown;
   patches: JsonPatchOperation[];
   changed: boolean;
   [key: string]: unknown;
 }
-export interface TableChange extends Omit<EditorChange, "document" | "patches"> {
+export interface TableChange extends Omit<EditorChange, "presentation" | "patches"> {
   action: PreparedTableChange["action"];
   tablePath: string;
-  document: unknown;
+  presentation: unknown;
   patches: JsonPatchOperation[];
   changed: boolean;
   [key: string]: unknown;
@@ -60,14 +60,14 @@ export declare function tableMerges(table: unknown): TableMerge[];
 /** The state of one cell, including merge anchor/covered status. */
 export declare function describeTableCell(table: unknown, cell: TableCellAddress): TableCellState;
 /** Merge `span.colSpan` x `span.rowSpan` cells from `cell`. `join` keeps the text of covered cells by joining it into the anchor; without it, covered text refuses with `merge-would-lose-content`. */
-export declare function prepareTableMerge(document: unknown, tablePath: string, cell: TableCellAddress, span: { colSpan?: number; rowSpan?: number }, options?: { join?: boolean }): PreparedTableChange;
-export declare function prepareTableSplit(document: unknown, tablePath: string, cell: TableCellAddress): PreparedTableChange;
+export declare function prepareTableMerge(presentation: unknown, tablePath: string, cell: TableCellAddress, span: { colSpan?: number; rowSpan?: number }, options?: { join?: boolean }): PreparedTableChange;
+export declare function prepareTableSplit(presentation: unknown, tablePath: string, cell: TableCellAddress): PreparedTableChange;
 /** Merge style fields into the cells' styles (null removes a field, `style: null` clears). */
-export declare function prepareTableCellStyle(document: unknown, tablePath: string, cells: TableCellAddress | TableCellAddress[], style: Record<string, unknown> | null): PreparedTableChange;
+export declare function prepareTableCellStyle(presentation: unknown, tablePath: string, cells: TableCellAddress | TableCellAddress[], style: Record<string, unknown> | null): PreparedTableChange;
 /** Apply `{ header, banding, borders }` (missing fields mean theme/false) or a named preset: sets the header fill, banded-row fill and borders of every cell and clears them elsewhere; `theme` removes a previous style. */
-export declare function prepareTableStyle(document: unknown, tablePath: string, preset: keyof typeof TABLE_STYLE_PRESETS | Partial<TableStyle>): PreparedTableChange;
+export declare function prepareTableStyle(presentation: unknown, tablePath: string, preset: keyof typeof TABLE_STYLE_PRESETS | Partial<TableStyle>): PreparedTableChange;
 /** The current style per axis, or "custom" in every field when the fills and borders are not one this module writes. */
-export declare function readTableStyle(document: unknown, tablePath: string): (TableStyle | { header: "custom"; banding: "custom"; borders: "custom" }) & { preset: keyof typeof TABLE_STYLE_PRESETS | "custom" };
+export declare function readTableStyle(presentation: unknown, tablePath: string): (TableStyle | { header: "custom"; banding: "custom"; borders: "custom" }) & { preset: keyof typeof TABLE_STYLE_PRESETS | "custom" };
 export declare function mergeTableCells(editor: EditorSession, tablePath: string, cell: TableCellAddress, span: { colSpan?: number; rowSpan?: number }, options?: { join?: boolean; meta?: Record<string, unknown> }): TableChange;
 export declare function splitTableCell(editor: EditorSession, tablePath: string, cell: TableCellAddress, meta?: Record<string, unknown>): TableChange;
 export declare function setTableCellStyle(editor: EditorSession, tablePath: string, cells: TableCellAddress | TableCellAddress[], style: Record<string, unknown> | null, meta?: Record<string, unknown>): TableChange;

package/dist/table-options.js

@@ -5,8 +5,9 @@
 // Cells are addressed by `{ section: "header" | "body", row, column }`; `row` is ignored for the
 // header section. Nothing here invents text: merging cells that hold text refuses unless you pass
 // `join: true`, which keeps every word in the merged cell.
-import { getValueAtPath, opfPathToJsonPointer, splitOpfPath, validateOpfDocument } from "./index.js";
+import { getValueAtPath, opfPathToJsonPointer, splitOpfPath } from "./index.js";
 import { checkedDocument, fail } from "./edit-helpers.js";
+import { checkFormat } from "./checks.js";
 
 /**
  * Table styles. A style is `{ header, banding, borders }`. The renderers' table defaults are a header
@@ -27,7 +28,7 @@ export const TABLE_BORDER_STYLES = Object.freeze(["theme", "none", "horizontal",
 // The style fields a table style owns; text color, alignment and padding are never touched.
 const STYLE_KEYS = ["fill", "borders"];
 const HEADER_FILL = Object.freeze({ plain: "surface", accent: "accent" });
-const BAND_FILL = "background";
+const BAND_FILL = "surfaceAlt";
 const RULE_COLOR = "textSecondary";
 
 const isObject = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
@@ -59,9 +60,9 @@ export function parseTableCellPath(path) {
   return undefined;
 }
 
-function tableAt(document, tablePath) {
+function tableAt(presentation, tablePath) {
   const parts = splitOpfPath(tablePath);
-  const table = getValueAtPath(document, parts);
+  const table = getValueAtPath(presentation, parts);
   if (isObject(table) && !Array.isArray(table.rows) && typeof table.dataset === "string")
     throw fail("table-dataset-backed", `This table shows the shared dataset '${table.dataset}', which holds no cell styles or merged cells. Use a copy of the data (in the data grid) to style it.`, { tablePath, dataset: table.dataset });
   if (!isObject(table) || !Array.isArray(table.rows)) throw fail("table-not-found", "Choose a table (a path ending in .table).", { tablePath });
@@ -163,16 +164,16 @@ function withCell(cell, patch) {
   return keys.length === 1 && keys[0] === "value" ? merged.value : merged;
 }
 
-function transaction(document, tablePath, change, extra = {}) {
-  const { parts, table } = tableAt(document, tablePath);
+function transaction(presentation, tablePath, change, extra = {}) {
+  const { parts, table } = tableAt(presentation, tablePath);
   const next = clone(table);
   const info = change(next);
   const pointer = opfPathToJsonPointer(parts);
   const changed = JSON.stringify(table) !== JSON.stringify(next);
   const patches = changed ? [{ op: "test", path: pointer, value: clone(table) }, { op: "replace", path: pointer, value: next }] : [];
-  const before = validateOpfDocument(document);
-  const result = changed ? checkedDocument(document, patches, before) : document;
-  return { ...extra, ...info, tablePath: parts.join("."), document: clone(result), patches, changed };
+  const before = checkFormat(presentation);
+  const result = changed ? checkedDocument(presentation, patches, before) : presentation;
+  return { ...extra, ...info, tablePath: parts.join("."), presentation: clone(result), patches, changed };
 }
 
 // --- merge and split ---------------------------------------------------------------------------
@@ -200,11 +201,11 @@ function unmerge(table, cell) {
  * `merge-overlap` for a rectangle that crosses another merged cell. A header cell merges across the
  * header only (`rowSpan` 1). Re-merging an anchor first undoes its old merge.
  */
-export function prepareTableMerge(document, tablePath, cell, span, options = {}) {
+export function prepareTableMerge(presentation, tablePath, cell, span, options = {}) {
   const colSpan = span.colSpan ?? 1;
   const rowSpan = span.rowSpan ?? 1;
   if (!Number.isInteger(colSpan) || colSpan < 1 || !Number.isInteger(rowSpan) || rowSpan < 1) throw fail("invalid-table-span", "Spans are whole numbers of 1 or more.", { span });
-  return transaction(document, tablePath, (table) => {
+  return transaction(presentation, tablePath, (table) => {
     const target = { section: cell.section, row: cell.section === "header" ? 0 : cell.row, column: cell.column };
     const existing = describeTableCell(table, target);
     if (existing.covered) throw fail("merge-overlap", "This cell is covered by a merged cell. Select the merged cell itself.", { cell });
@@ -242,8 +243,8 @@ export function prepareTableMerge(document, tablePath, cell, span, options = {})
 }
 
 /** Compute the patch that splits a merged cell back into single cells (covered positions become empty text). */
-export function prepareTableSplit(document, tablePath, cell) {
-  return transaction(document, tablePath, (table) => {
+export function prepareTableSplit(presentation, tablePath, cell) {
+  return transaction(presentation, tablePath, (table) => {
     const target = { section: cell.section, row: cell.section === "header" ? 0 : cell.row, column: cell.column };
     const entry = describeTableCell(table, target);
     if (entry.covered) throw fail("table-cell-covered", "This position is covered by a merged cell. Select the merged cell to split it.", { cell });
@@ -259,11 +260,11 @@ export function prepareTableSplit(document, tablePath, cell) {
  * clears the whole style. Covered (merged) positions are skipped. A cell left with no style or spans
  * becomes a plain value again. Style is appearance only: values and spans are untouched.
  */
-export function prepareTableCellStyle(document, tablePath, cells, style) {
+export function prepareTableCellStyle(presentation, tablePath, cells, style) {
   const list = Array.isArray(cells) ? cells : [cells];
   if (!list.length) throw fail("table-cell-not-found", "Choose at least one cell.", {});
   if (style !== null && !isObject(style)) throw fail("invalid-table-style", "A cell style is an object, or null to clear it.", { style });
-  return transaction(document, tablePath, (table) => {
+  return transaction(presentation, tablePath, (table) => {
     let skipped = 0;
     for (const cell of list) {
       const target = { section: cell.section, row: cell.section === "header" ? 0 : cell.row, column: cell.column };
@@ -329,12 +330,12 @@ function resolveStyle(preset) {
  * `theme`/false) or a named preset from `TABLE_STYLE_PRESETS`. It sets the header fill, the
  * alternating body-row fill and the cell borders, and clears those fields on every other cell, so
  * `theme` removes a previous style. Text color, alignment, padding, values and merges are kept.
- * Fills use scheme roles (surface, accent, background), so they follow the color scheme and the
+ * Fills use scheme roles (surface, surfaceAlt, accent, background), so they follow the color scheme and the
  * renderers' automatic text contrast keeps text readable.
  */
-export function prepareTableStyle(document, tablePath, preset) {
+export function prepareTableStyle(presentation, tablePath, preset) {
   const style = resolveStyle(preset);
-  return transaction(document, tablePath, (table) => {
+  return transaction(presentation, tablePath, (table) => {
     styleTable(table, style);
     return {};
   }, { action: "table-style", style });
@@ -367,8 +368,8 @@ export function applyTableStyleToTable(table, preset) {
  * its fills and borders are not one of the styles this module writes (for example hand-set fills).
  * `preset` is the named preset the style equals, or "custom".
  */
-export function readTableStyle(document, tablePath) {
-  return readTableStyleOfTable(tableAt(document, tablePath).table);
+export function readTableStyle(presentation, tablePath) {
+  return readTableStyleOfTable(tableAt(presentation, tablePath).table);
 }
 
 /** {@link readTableStyle} for a table object. */
@@ -396,10 +397,10 @@ export * from "./table-structure.js";
 // --- session forms ----------------------------------------------------------------------------
 
 function commit(editor, prepared, meta = {}) {
-  const { document, patches, ...summary } = prepared;
-  void document;
+  const { presentation, patches, ...summary } = prepared;
+  void presentation;
   if (!editor || typeof editor.applyPatch !== "function") throw fail("invalid-editor", "Expected an editor session created by createEditorSession.");
-  if (!prepared.changed) return { ...summary, document: editor.document, patches: [], inversePatches: [], validation: editor.validation };
+  if (!prepared.changed) return { ...summary, presentation: editor.presentation, patches: [], inversePatches: [], validation: editor.validation };
   const change = editor.applyPatch(patches, { ...meta, source: meta.source ?? "table-option", action: prepared.action, path: prepared.tablePath });
   return { ...change, ...summary };
 }
@@ -410,20 +411,20 @@ function checkEditor(editor) {
 export function mergeTableCells(editor, tablePath, cell, span, options = {}) {
   checkEditor(editor);
   const { meta, ...rest } = options;
-  return commit(editor, prepareTableMerge(editor.document, tablePath, cell, span, rest), meta);
+  return commit(editor, prepareTableMerge(editor.presentation, tablePath, cell, span, rest), meta);
 }
 /** Split a merged cell as one undoable transaction. */
 export function splitTableCell(editor, tablePath, cell, meta = {}) {
   checkEditor(editor);
-  return commit(editor, prepareTableSplit(editor.document, tablePath, cell), meta);
+  return commit(editor, prepareTableSplit(editor.presentation, tablePath, cell), meta);
 }
 /** Style cells as one undoable transaction. See {@link prepareTableCellStyle}. */
 export function setTableCellStyle(editor, tablePath, cells, style, meta = {}) {
   checkEditor(editor);
-  return commit(editor, prepareTableCellStyle(editor.document, tablePath, cells, style), meta);
+  return commit(editor, prepareTableCellStyle(editor.presentation, tablePath, cells, style), meta);
 }
 /** Apply a table style as one undoable transaction. See {@link prepareTableStyle}. */
 export function setTableStyle(editor, tablePath, preset, meta = {}) {
   checkEditor(editor);
-  return commit(editor, prepareTableStyle(editor.document, tablePath, preset), meta);
+  return commit(editor, prepareTableStyle(editor.presentation, tablePath, preset), meta);
 }

package/dist/table-structure.d.ts

@@ -2,29 +2,29 @@ import type { EditorSession } from "./index.js";
 import type { GridAddress, GridCellEdit, GridChange, GridOptions, GridSortOptions, PreparedGridChange } from "./grid-model.js";
 
 /** Set cell text (or typed values) in a table. Rich cells keep their runs' formatting and styled cells their style and spans. One patch; every problem is in `error.issues`. */
-export declare function prepareTableCells(document: unknown, tablePath: string, edits: GridCellEdit[], options?: GridOptions): PreparedGridChange;
+export declare function prepareTableCells(presentation: unknown, tablePath: string, edits: GridCellEdit[], options?: GridOptions): PreparedGridChange;
 export declare function setTableCells(editor: EditorSession, tablePath: string, edits: GridCellEdit[], options?: GridOptions): GridChange;
 /** Paste TSV/CSV text or rows at a cell, growing the table as needed. Covered (merged) positions refuse the paste. One patch. */
-export declare function prepareTablePaste(document: unknown, tablePath: string, anchor: GridAddress, source: string | string[][], options?: GridOptions): PreparedGridChange;
+export declare function prepareTablePaste(presentation: unknown, tablePath: string, anchor: GridAddress, source: string | string[][], options?: GridOptions): PreparedGridChange;
 export declare function pasteTableText(editor: EditorSession, tablePath: string, anchor: GridAddress, source: string | string[][], options?: GridOptions): GridChange;
 /** Insert `count` rows so the first is body row `at`. A merged cell spanning that position grows. */
-export declare function prepareTableInsertRows(document: unknown, tablePath: string, at: number, count?: number, options?: GridOptions): PreparedGridChange;
+export declare function prepareTableInsertRows(presentation: unknown, tablePath: string, at: number, count?: number, options?: GridOptions): PreparedGridChange;
 export declare function insertTableRows(editor: EditorSession, tablePath: string, at: number, count?: number, options?: GridOptions): GridChange;
 /** Delete body rows. A merged cell spanning a deleted row shrinks and keeps its text. The last row cannot be deleted. */
-export declare function prepareTableDeleteRows(document: unknown, tablePath: string, indices: number[], options?: GridOptions): PreparedGridChange;
+export declare function prepareTableDeleteRows(presentation: unknown, tablePath: string, indices: number[], options?: GridOptions): PreparedGridChange;
 export declare function deleteTableRows(editor: EditorSession, tablePath: string, indices: number[], options?: GridOptions): GridChange;
 /** Move `count` rows from `from` so the first is at `to`. Refused when it would split a merged cell. */
-export declare function prepareTableMoveRows(document: unknown, tablePath: string, from: number, to: number, count?: number, options?: GridOptions): PreparedGridChange;
+export declare function prepareTableMoveRows(presentation: unknown, tablePath: string, from: number, to: number, count?: number, options?: GridOptions): PreparedGridChange;
 export declare function moveTableRows(editor: EditorSession, tablePath: string, from: number, to: number, count?: number, options?: GridOptions): GridChange;
-export declare function prepareTableInsertColumns(document: unknown, tablePath: string, at: number, count?: number, options?: GridOptions): PreparedGridChange;
+export declare function prepareTableInsertColumns(presentation: unknown, tablePath: string, at: number, count?: number, options?: GridOptions): PreparedGridChange;
 export declare function insertTableColumns(editor: EditorSession, tablePath: string, at: number, count?: number, options?: GridOptions): GridChange;
-export declare function prepareTableDeleteColumns(document: unknown, tablePath: string, indices: number[], options?: GridOptions): PreparedGridChange;
+export declare function prepareTableDeleteColumns(presentation: unknown, tablePath: string, indices: number[], options?: GridOptions): PreparedGridChange;
 export declare function deleteTableColumns(editor: EditorSession, tablePath: string, indices: number[], options?: GridOptions): GridChange;
-export declare function prepareTableMoveColumns(document: unknown, tablePath: string, from: number, to: number, count?: number, options?: GridOptions): PreparedGridChange;
+export declare function prepareTableMoveColumns(presentation: unknown, tablePath: string, from: number, to: number, count?: number, options?: GridOptions): PreparedGridChange;
 export declare function moveTableColumns(editor: EditorSession, tablePath: string, from: number, to: number, count?: number, options?: GridOptions): GridChange;
 /** Sort the body rows by a column, stably and by type (numbers, ISO dates, text; empty cells last). Rows joined by a row-spanning merge move as a block. */
-export declare function prepareTableSort(document: unknown, tablePath: string, column: number, options?: GridSortOptions): PreparedGridChange;
+export declare function prepareTableSort(presentation: unknown, tablePath: string, column: number, options?: GridSortOptions): PreparedGridChange;
 export declare function sortTableRows(editor: EditorSession, tablePath: string, column: number, options?: GridSortOptions): GridChange;
 /** Turn the header row on (the first row becomes the header, or `{ use: "new" }` adds an empty one) or off. */
-export declare function prepareTableHeader(document: unknown, tablePath: string, enabled: boolean, options?: { use?: "first-row" | "new" }): PreparedGridChange;
+export declare function prepareTableHeader(presentation: unknown, tablePath: string, enabled: boolean, options?: { use?: "first-row" | "new" }): PreparedGridChange;
 export declare function setTableHeader(editor: EditorSession, tablePath: string, enabled: boolean, options?: { use?: "first-row" | "new"; meta?: Record<string, unknown> }): GridChange;

package/dist/table-structure.js

@@ -5,7 +5,7 @@
 // correct. A table cell is a plain value, rich runs or a styled cell; editing keeps runs' formatting and a cell's style and spans.
 // Rows are addressed from 0 in the body; the header row is addressed as `{ section: "header", column }`.
 //
-// `prepare*` computes `{ document, patches, changed }` without touching a session; the session forms apply it as one undo step.
+// `prepare*` computes `{ presentation, patches, changed }` without touching a session; the session forms apply it as one undo step.
 import {
   prepareGridCells,
   preparePaste,
@@ -28,64 +28,64 @@ import {
   prepareSetHeader,
   setGridHeader,
 } from "./grid-model.js";
-export function prepareTableCells(document, tablePath, edits, options = {}) {
-  return prepareGridCells(document, tablePath, edits, { ...options, kind: "table" });
+export function prepareTableCells(presentation, tablePath, edits, options = {}) {
+  return prepareGridCells(presentation, tablePath, edits, { ...options, kind: "table" });
 }
 export function setTableCells(editor, tablePath, edits, options = {}) {
   return setGridCells(editor, tablePath, edits, { ...options, kind: "table" });
 }
-export function prepareTablePaste(document, tablePath, anchor, source, options = {}) {
-  return preparePaste(document, tablePath, anchor, source, { ...options, kind: "table" });
+export function prepareTablePaste(presentation, tablePath, anchor, source, options = {}) {
+  return preparePaste(presentation, tablePath, anchor, source, { ...options, kind: "table" });
 }
 export function pasteTableText(editor, tablePath, anchor, source, options = {}) {
   return pasteGridText(editor, tablePath, anchor, source, { ...options, kind: "table" });
 }
-export function prepareTableInsertRows(document, tablePath, at, count = 1, options = {}) {
-  return prepareInsertRows(document, tablePath, at, count, { ...options, kind: "table" });
+export function prepareTableInsertRows(presentation, tablePath, at, count = 1, options = {}) {
+  return prepareInsertRows(presentation, tablePath, at, count, { ...options, kind: "table" });
 }
 export function insertTableRows(editor, tablePath, at, count = 1, options = {}) {
   return insertGridRows(editor, tablePath, at, count, { ...options, kind: "table" });
 }
-export function prepareTableDeleteRows(document, tablePath, indices, options = {}) {
-  return prepareDeleteRows(document, tablePath, indices, { ...options, kind: "table" });
+export function prepareTableDeleteRows(presentation, tablePath, indices, options = {}) {
+  return prepareDeleteRows(presentation, tablePath, indices, { ...options, kind: "table" });
 }
 export function deleteTableRows(editor, tablePath, indices, options = {}) {
   return deleteGridRows(editor, tablePath, indices, { ...options, kind: "table" });
 }
-export function prepareTableMoveRows(document, tablePath, from, to, count = 1, options = {}) {
-  return prepareMoveRows(document, tablePath, from, to, count, { ...options, kind: "table" });
+export function prepareTableMoveRows(presentation, tablePath, from, to, count = 1, options = {}) {
+  return prepareMoveRows(presentation, tablePath, from, to, count, { ...options, kind: "table" });
 }
 export function moveTableRows(editor, tablePath, from, to, count = 1, options = {}) {
   return moveGridRows(editor, tablePath, from, to, count, { ...options, kind: "table" });
 }
-export function prepareTableInsertColumns(document, tablePath, at, count = 1, options = {}) {
-  return prepareInsertColumns(document, tablePath, at, count, { ...options, kind: "table" });
+export function prepareTableInsertColumns(presentation, tablePath, at, count = 1, options = {}) {
+  return prepareInsertColumns(presentation, tablePath, at, count, { ...options, kind: "table" });
 }
 export function insertTableColumns(editor, tablePath, at, count = 1, options = {}) {
   return insertGridColumns(editor, tablePath, at, count, { ...options, kind: "table" });
 }
-export function prepareTableDeleteColumns(document, tablePath, indices, options = {}) {
-  return prepareDeleteColumns(document, tablePath, indices, { ...options, kind: "table" });
+export function prepareTableDeleteColumns(presentation, tablePath, indices, options = {}) {
+  return prepareDeleteColumns(presentation, tablePath, indices, { ...options, kind: "table" });
 }
 export function deleteTableColumns(editor, tablePath, indices, options = {}) {
   return deleteGridColumns(editor, tablePath, indices, { ...options, kind: "table" });
 }
-export function prepareTableMoveColumns(document, tablePath, from, to, count = 1, options = {}) {
-  return prepareMoveColumns(document, tablePath, from, to, count, { ...options, kind: "table" });
+export function prepareTableMoveColumns(presentation, tablePath, from, to, count = 1, options = {}) {
+  return prepareMoveColumns(presentation, tablePath, from, to, count, { ...options, kind: "table" });
 }
 export function moveTableColumns(editor, tablePath, from, to, count = 1, options = {}) {
   return moveGridColumns(editor, tablePath, from, to, count, { ...options, kind: "table" });
 }
-export function prepareTableSort(document, tablePath, column, options = {}) {
-  return prepareSortRows(document, tablePath, column, { ...options, kind: "table" });
+export function prepareTableSort(presentation, tablePath, column, options = {}) {
+  return prepareSortRows(presentation, tablePath, column, { ...options, kind: "table" });
 }
 export function sortTableRows(editor, tablePath, column, options = {}) {
   return sortGridRows(editor, tablePath, column, { ...options, kind: "table" });
 }
 
 /** Turn the header row on or off. On uses the first row as the header, or adds an empty one with `{ use: "new" }`. See {@link prepareSetHeader}. */
-export function prepareTableHeader(document, tablePath, enabled, options = {}) {
-  return prepareSetHeader(document, tablePath, enabled, options);
+export function prepareTableHeader(presentation, tablePath, enabled, options = {}) {
+  return prepareSetHeader(presentation, tablePath, enabled, options);
 }
 export function setTableHeader(editor, tablePath, enabled, options = {}) {
   return setGridHeader(editor, tablePath, enabled, options);

package/dist/template-panel.d.ts

@@ -4,11 +4,11 @@ import type { TemplateFill, TemplateFillApplyResult } from "./templates.js";
 export interface TemplatePanelOptions {
   editor: EditorSession;
   /**
-   * Draw the live preview: return the SVG of one slide of `document` with `variables` (the values typed so far)
-   * as an SVG string, or a promise of one. Typically `renderSvg(document, { variables, slideIndex, ... })` from
+   * Draw the live preview: return the SVG of one slide of `presentation` with `variables` (the values typed so far)
+   * as an SVG string, or a promise of one. Typically `renderSlideSvg(presentation, slideIndex, { variables, ... })` from
    * `@openpresentation/opf-render` with the host's fonts. Omit for no preview.
    */
-  renderPreview?: (input: { document: unknown; variables: Record<string, unknown>; slideIndex: number }) => string | Promise<string>;
+  renderPreview?: (input: { presentation: unknown; variables: Record<string, unknown>; slideIndex: number }) => string | Promise<string>;
   /** The slide the preview starts on. Call `refresh()` when it changes. */
   getSlideIndex?: () => number;
   /** The text field a variable token is inserted into: its OPF path and, optionally, the selection as UTF-16 offsets. Omit to hide the insert section. */

package/dist/template-panel.js

@@ -8,10 +8,11 @@ import {
   createTemplateFill,
   insertVariableToken,
   isTemplateDocument,
+  listBuiltins,
   setTemplate,
   suggestVariableId,
-  templatesAvailable,
 } from "./templates.js";
+import { slideTitle } from "./slides.js";
 
 const KIND_LABELS = { text: "Text", number: "Number", date: "Date", image: "Image", url: "Link", list: "List", color: "Color" };
 const STATUS_TEXT = { filled: "Filled", default: "Default value", unfilled: "Needs a value", optional: "Optional" };
@@ -20,6 +21,13 @@ const NEW_VARIABLE_KINDS = ["text", "number", "date", "image", "url", "list"];
 
 let panelCounter = 0;
 
+/** A short display of a built-in's source value. */
+function builtinValueText(entry) {
+  const value = entry.value;
+  const text = Array.isArray(value) ? value.join(", ") : value && typeof value === "object" ? String(value.src ?? "") : String(value ?? "");
+  return text.length > 60 ? `${text.slice(0, 57)}...` : text;
+}
+
 function h(doc, tag, attributes = {}, ...children) {
   const element = doc.createElement(tag);
   for (const [key, value] of Object.entries(attributes)) {
@@ -34,13 +42,12 @@ function h(doc, tag, attributes = {}, ...children) {
 }
 
 /**
- * Mount the Fill template panel. Options: `editor` (a session), `renderPreview({document, variables, slideIndex})`
+ * Mount the Fill template panel. Options: `editor` (a session), `renderPreview({presentation, variables, slideIndex})`
  * returning an SVG string (or a promise of one) for the live preview (omit for no preview), `getSlideIndex`,
  * `getTarget()` returning `{path, start?, end?}` for the text field a token is inserted into, `onStatus(message,
  * {error})`, `onApply(result)`, `readFile(file)` (default: FileReader as a data URL) for image uploads.
  */
 export function createTemplatePanel(container, options) {
-  if (!templatesAvailable()) throw new Error("The Fill template panel needs a core release that ships resolveVariables.");
   const { editor, renderPreview, getTarget, onStatus, onApply } = options;
   const doc = container.ownerDocument;
   const fill = createTemplateFill(editor);
@@ -56,6 +63,12 @@ export function createTemplatePanel(container, options) {
   const modeBox = h(doc, "input", { type: "checkbox", id: `${id}-mode` });
   modeLabel.append(modeBox, " This presentation is a template (it may have unfilled variables)");
   const fieldList = h(doc, "div", { class: "opf-template-fields" });
+  // Built-in variables: read-only values from the document's own speaker, organization and deck fields.
+  const builtinList = h(doc, "ul", { class: "opf-template-builtin-list" });
+  const builtinSection = h(doc, "details", { class: "opf-template-builtins", "data-opf-component": "template-builtins" },
+    h(doc, "summary", { text: "Built-in variables" }),
+    h(doc, "p", { class: "opf-template-help", text: "Read from the presentation's own speaker, organization and deck fields; edit those fields to change them. Use them like any variable: {{speaker.name}} inside text, or var:speaker.photo as a whole image field." }),
+    builtinList);
   const live = h(doc, "p", { class: "opf-template-live", role: "status", "aria-live": "polite" });
   const applyButton = h(doc, "button", { type: "button", class: "opf-template-apply primary", text: "Fill the presentation" });
   const partialButton = h(doc, "button", { type: "button", class: "opf-template-partial secondary", text: "Fill what is ready" });
@@ -85,7 +98,7 @@ export function createTemplatePanel(container, options) {
         h(doc, "label", { for: `${id}-new-sample`, text: "Sample value" }), newSample, newButton))
     : null;
 
-  root.append(summary, modeLabel, fieldList, actions, live);
+  root.append(summary, modeLabel, fieldList, builtinSection, actions, live);
   if (previewSection) root.append(previewSection);
   if (insertSection) root.append(insertSection);
   container.append(root);
@@ -152,7 +165,7 @@ export function createTemplatePanel(container, options) {
       extras.push(colorInput);
     }
     if (field.kind === "image") {
-      const assets = editor.document.assets && typeof editor.document.assets === "object" ? Object.keys(editor.document.assets) : [];
+      const assets = editor.presentation.assets && typeof editor.presentation.assets === "object" ? Object.keys(editor.presentation.assets) : [];
       if (assets.length) {
         assetSelect = h(doc, "select", { "aria-label": `${field.label}: pick a registered asset` }, h(doc, "option", { value: "", text: "Pick an asset…" }), ...assets.map((key) => h(doc, "option", { value: `asset:${key}`, text: key })));
         assetSelect.addEventListener("change", () => {
@@ -214,11 +227,22 @@ export function createTemplatePanel(container, options) {
       rows.set(field.id, row);
       fieldList.append(row.element);
     }
-    insertSelect.replaceChildren(...fields.map((field) => h(doc, "option", { value: field.id, text: `${field.label} (${KIND_LABELS[field.kind]})` })));
-    slideSelect.replaceChildren(...(editor.document.slides ?? []).map((slide, index) => h(doc, "option", { value: String(index), text: `${index + 1}. ${typeof slide.title === "string" && slide.title ? slide.title : "Untitled"}` })));
-    previewSlide = Math.min(previewSlide, Math.max(0, (editor.document.slides?.length ?? 1) - 1));
+    const builtins = listBuiltins(editor.presentation);
+    insertSelect.replaceChildren(
+      ...fields.map((field) => h(doc, "option", { value: field.id, text: `${field.label} (${KIND_LABELS[field.kind]})` })),
+      ...(builtins.length ? [h(doc, "optgroup", { label: "Built-in variables" }, ...builtins.map((entry) => h(doc, "option", { value: entry.name, text: `${entry.label} (${entry.name})` })))] : []),
+    );
+    builtinSection.hidden = !builtins.length;
+    builtinList.replaceChildren(...builtins.map((entry) => {
+      const shown = builtinValueText(entry);
+      const uses = entry.uses.length;
+      return h(doc, "li", { "data-builtin": entry.name, "data-kind": entry.kind, "data-available": entry.available ? "true" : "false" },
+        h(doc, "code", { text: `{{${entry.name}}}` }), ` ${entry.label}: `, entry.available ? shown : h(doc, "em", { text: "not set" }), uses ? ` (used ${uses} time${uses === 1 ? "" : "s"})` : "");
+    }));
+    slideSelect.replaceChildren(...(editor.presentation.slides ?? []).map((slide, index) => h(doc, "option", { value: String(index), text: `${index + 1}. ${slideTitle(slide) || "Untitled"}` })));
+    previewSlide = Math.min(previewSlide, Math.max(0, (editor.presentation.slides?.length ?? 1) - 1));
     slideSelect.value = String(previewSlide);
-    modeBox.checked = isTemplateDocument(editor.document);
+    modeBox.checked = isTemplateDocument(editor.presentation);
     update();
   }
 
@@ -263,7 +287,7 @@ export function createTemplatePanel(container, options) {
     if (!renderPreview) return;
     const token = ++previewToken;
     try {
-      const svg = await renderPreview({ document: editor.document, variables: fill.values, slideIndex: previewSlide });
+      const svg = await renderPreview({ presentation: editor.presentation, variables: fill.values, slideIndex: previewSlide });
       if (token !== previewToken || destroyed) return;
       previewBox.innerHTML = svg;
       const preview = fill.preview();
@@ -304,7 +328,7 @@ export function createTemplatePanel(container, options) {
       setTemplate(editor, modeBox.checked);
       say(modeBox.checked ? "Marked as a template." : "Marked as a normal presentation.");
     } catch (error) {
-      modeBox.checked = isTemplateDocument(editor.document);
+      modeBox.checked = isTemplateDocument(editor.presentation);
       say(messageOf(error), true);
     }
   });
@@ -335,13 +359,13 @@ export function createTemplatePanel(container, options) {
       say("Give the new variable a name.", true);
       return;
     }
-    const variableId = suggestVariableId(editor.document, name);
+    const variableId = suggestVariableId(editor.presentation, name);
     const kind = newKind.value;
     const declaration = { type: kind, label: name };
     const sample = newSample.value.trim();
     if (sample) {
       // A template keeps the sample as an example (the slot stays unfilled); a normal deck needs a real value.
-      const field = isTemplateDocument(editor.document) ? "example" : "value";
+      const field = isTemplateDocument(editor.presentation) ? "example" : "value";
       declaration[field] = kind === "number" && Number.isFinite(Number(sample)) ? Number(sample) : kind === "list" ? sample.split(/\r?\n|,/).map((entry) => entry.trim()).filter(Boolean) : sample;
     }
     try {

package/dist/templates.d.ts

@@ -55,25 +55,23 @@ export interface TemplatePreview {
   complete: boolean;
 }
 
-/** True when the core this editor runs on can resolve template variables. */
-export declare function templatesAvailable(): boolean;
-export declare function isTemplateDocument(document: unknown): boolean;
+export declare function isTemplateDocument(presentation: unknown): boolean;
 /** True when the document is a template or declares a variable that is not a color. */
-export declare function hasTemplateVariables(document: unknown): boolean;
+export declare function hasTemplateVariables(presentation: unknown): boolean;
 export declare function valueToFieldText(kind: TemplateVariableKind, value: unknown): string;
 /** Parse a form control's text. A blank control clears the value. */
 export declare function fieldTextToValue(kind: TemplateVariableKind, text: string): { ok: true; value: unknown } | { ok: false; message: string };
-export declare function listTemplateFields(document: unknown, values?: Record<string, unknown>): TemplateField[];
-export declare function templateStatus(document: unknown, values?: Record<string, unknown>): TemplateStatus;
+export declare function listTemplateFields(presentation: unknown, values?: Record<string, unknown>): TemplateField[];
+export declare function templateStatus(presentation: unknown, values?: Record<string, unknown>): TemplateStatus;
 /** The concrete deck for the values with each unfilled variable's example. Never throws for missing values. */
-export declare function previewTemplate(document: unknown, values?: Record<string, unknown>): TemplatePreview;
+export declare function previewTemplate(presentation: unknown, values?: Record<string, unknown>): TemplatePreview;
 
 export interface TemplateFillOptions {
   /** Extra session meta for the fill edit. */
   meta?: Record<string, unknown>;
 }
 export interface TemplateFillApplyResult {
-  document: unknown;
+  presentation: unknown;
   patches: unknown[];
   inversePatches: unknown[];
   validation: unknown;
@@ -103,9 +101,22 @@ export interface TemplateFill {
 }
 export declare function createTemplateFill(editor: EditorSession, options?: TemplateFillOptions): TemplateFill;
 
-/** `{{id}}`, or `{{id|format}}`. */
+/** The token for a declared variable id or a built-in name such as `speaker.name`. */
 export declare function variableToken(id: string, format?: string): string;
-export declare function suggestVariableId(document: unknown, label?: string): string;
+/** One built-in variable of a document (core `listBuiltinVariables`). */
+export interface BuiltinInfo {
+  /** Dotted name, as written inside `{{...}}`. */
+  name: string;
+  kind: "text" | "image" | "list";
+  label: string;
+  /** The source value, when the document has one. */
+  value?: unknown;
+  available: boolean;
+  uses: { id: string; path: string; form: "token" | "reference" }[];
+}
+/** The presentation's built-in variables, read-only. */
+export declare function listBuiltins(presentation: unknown): BuiltinInfo[];
+export declare function suggestVariableId(presentation: unknown, label?: string): string;
 /** Declare a variable as one undoable edit. */
 export declare function declareVariable(editor: EditorSession, id: string, declaration: string | Record<string, unknown>, meta?: Record<string, unknown>): unknown;
 /** Mark the document as a template, or as a normal deck with `false`, as one undoable edit. */
@@ -123,4 +134,4 @@ export interface InsertVariableTokenOptions {
   meta?: Record<string, unknown>;
 }
 /** Insert a variable token into a text field as one undoable edit. */
-export declare function insertVariableToken(editor: EditorSession, path: string, id: string, options?: InsertVariableTokenOptions): { token: string; document: unknown; patches: unknown[]; inversePatches: unknown[]; validation: unknown };
+export declare function insertVariableToken(editor: EditorSession, path: string, id: string, options?: InsertVariableTokenOptions): { token: string; presentation: unknown; patches: unknown[]; inversePatches: unknown[]; validation: unknown };