@openpresentation/opf-editor 0.12.1 → 0.15.0

package/dist/background-options.js

@@ -1,17 +1,22 @@
-// Backgrounds (RR-06): every background form the schema has, with validation that explains itself.
-// A background is a theme slot, a solid color, a linear gradient, an image or a pattern, at the deck
-// or on one slide. `setBackground` is one undoable patch through the `backgrounds` switch, so the
-// preview, export and Undo behave like every other dimension.
+// Backgrounds (RR-06, FA-22/FA-23): every background form the schema has, with validation that explains itself.
+// A background is a theme slot, a solid color, a linear gradient, an image or a pattern, at the deck or on one slide. It is
+// the only canvas fill and never moves content. The image form is flat (OPF 0.15): `{ type: "image", src, alt, fit, focus,
+// opacity, recolor, overlay }`; an image source string (`asset:`, `https://`, `data:`, `./`, `../`) is the cover-image shorthand.
+// `setBackground` is one undoable patch through the `backgrounds` switch, so the preview, export and Undo behave like every
+// other dimension.
 import { prepareDimensionSwitch, switchDimension } from "./switches.js";
 import { fail } from "./edit-helpers.js";
+import { normalizeFocus, normalizeOverlay, normalizeRecolor } from "./image-options.js";
 
 export const BACKGROUND_TYPES = Object.freeze(["theme", "solid", "gradient", "image", "pattern"]);
 export const THEME_BACKGROUND_SLOTS = Object.freeze(["light1", "light2", "dark1", "dark2"]);
-export const IMAGE_BACKGROUND_FITS = Object.freeze(["cover", "contain", "tile"]);
+export const IMAGE_BACKGROUND_FITS = Object.freeze(["cover", "contain", "stretch", "tile"]);
+/** Image sources the background string shorthand accepts (the schema's ImageSource). */
+export const IMAGE_SOURCE = /^(?:asset:|https:\/\/|data:|\.\/|\.\.\/)/;
 /** Scheme slots and roles a ColorRef may name (the schema's ColorRef enum), besides hex colors and `var:<id>`. */
 export const COLOR_NAMES = Object.freeze([
   "accent1", "accent2", "accent3", "accent4", "accent5", "accent6", "dark1", "dark2", "light1", "light2", "hyperlink", "followedHyperlink",
-  "primary", "secondary", "accent", "background", "surface", "text", "textSecondary",
+  "primary", "secondary", "accent", "background", "surface", "surfaceAlt", "text", "textSecondary",
 ]);
 /**
  * The 54 DrawingML preset patterns (ECMA-376 ST_PresetPatternVal) by family. PPTX export writes them as
@@ -55,7 +60,8 @@ export function normalizeBackground(spec) {
   if (typeof spec === "string") {
     if (THEME_BACKGROUND_SLOTS.includes(spec)) return spec;
     if (HEX.test(spec)) return spec.toUpperCase();
-    throw fail("invalid-background", `A background shorthand is a theme slot (${THEME_BACKGROUND_SLOTS.join(", ")}) or a hex color.`, { spec });
+    if (IMAGE_SOURCE.test(spec.trim())) return spec.trim();
+    throw fail("invalid-background", `A background shorthand is a theme slot (${THEME_BACKGROUND_SLOTS.join(", ")}), a hex color, or an image source starting with asset:, https://, data:, ./ or ../.`, { spec });
   }
   if (!isObject(spec)) throw fail("invalid-background", "Describe the background as { type, ... } or a theme slot / hex shorthand.", { spec });
   const opacity = opacityOf(spec);
@@ -83,10 +89,25 @@ export function normalizeBackground(spec) {
       return withOpacity({ type: "gradient", gradient: { ...(angle === undefined ? {} : { angle }), stops } });
     }
     case "image": {
-      const image = spec.image;
-      if (!isObject(image) || typeof image.src !== "string" || !image.src.trim()) throw fail("invalid-background", "An image background needs an image: choose a file or enter a source.", { spec });
-      if (image.fit !== undefined && image.fit !== "" && !IMAGE_BACKGROUND_FITS.includes(image.fit)) throw fail("invalid-background", `Image fit is one of ${IMAGE_BACKGROUND_FITS.join(", ")}.`, { spec });
-      return withOpacity({ type: "image", image: { src: image.src.trim(), ...(image.fit ? { fit: image.fit } : {}) } });
+      if (typeof spec.src !== "string" || !spec.src.trim()) throw fail("invalid-background", "An image background needs an image: choose a file or enter a source.", { spec });
+      const src = spec.src.trim();
+      if (!IMAGE_SOURCE.test(src)) throw fail("invalid-background", "An image source starts with asset:, https://, data:, ./ or ../.", { spec });
+      const fit = spec.fit === "" || spec.fit === null ? undefined : spec.fit;
+      if (fit !== undefined && !IMAGE_BACKGROUND_FITS.includes(fit)) throw fail("invalid-background", `Image fit is one of ${IMAGE_BACKGROUND_FITS.join(", ")}.`, { spec });
+      const alt = typeof spec.alt === "string" && spec.alt.trim() ? spec.alt.trim() : undefined;
+      const wrap = (call) => {
+        try {
+          return call();
+        } catch (error) {
+          throw fail("invalid-background", error.message, { spec });
+        }
+      };
+      const focus = spec.focus === undefined || spec.focus === null ? undefined : wrap(() => normalizeFocus(spec.focus));
+      const overlay = spec.overlay === undefined || spec.overlay === null ? undefined : wrap(() => normalizeOverlay(spec.overlay));
+      const recolor = spec.recolor === undefined || spec.recolor === null || spec.recolor === "" ? undefined : wrap(() => normalizeRecolor(spec.recolor));
+      const value = { type: "image", src, ...(alt ? { alt } : {}), ...(fit ? { fit } : {}), ...(focus ? { focus } : {}), ...(opacity === undefined ? {} : { opacity }), ...(recolor ? { recolor } : {}), ...(overlay ? { overlay } : {}) };
+      // A cover image with nothing else is the shorthand string.
+      return Object.keys(value).length === 2 ? src : value;
     }
     case "pattern": {
       const pattern = spec.pattern;
@@ -102,8 +123,8 @@ export function normalizeBackground(spec) {
 }
 
 /** Compute the patch that sets (or, for `null`, removes) the background, without touching a session. Options as `prepareDimensionSwitch` (`slideIndex`, `clearSlideOverrides`). */
-export function prepareBackground(document, spec, options = {}) {
-  return prepareDimensionSwitch(document, "backgrounds", spec === null ? null : normalizeBackground(spec), options);
+export function prepareBackground(presentation, spec, options = {}) {
+  return prepareDimensionSwitch(presentation, "backgrounds", spec === null ? null : normalizeBackground(spec), options);
 }
 
 /** Set the background as one undoable transaction; `null` removes it so the theme's (or the deck's) shows again. */
@@ -113,21 +134,25 @@ export function setBackground(editor, spec, options = {}) {
 
 /**
  * The background that applies at a scope as a flat description for a form:
- * `{ type, slot?, color?, opacity?, angle?, stops?, src?, fit?, preset?, foregroundColor?, backgroundColor?, scope, value }`.
+ * `{ type, slot?, color?, opacity?, angle?, stops?, src?, alt?, fit?, focus?, recolor?, overlay?, preset?, foregroundColor?, backgroundColor?, scope, value }`.
  * `type` is undefined when nothing is set; `scope` is "slide" when the slide sets its own, else "deck".
  */
-export function readBackground(document, { slideIndex } = {}) {
-  const own = slideIndex === undefined ? undefined : document.slides?.[slideIndex]?.design?.background;
-  const value = own !== undefined ? own : document.design?.background;
+export function readBackground(presentation, { slideIndex } = {}) {
+  const own = slideIndex === undefined ? undefined : presentation.slides?.[slideIndex]?.design?.background;
+  const value = own !== undefined ? own : presentation.design?.background;
   const scope = own !== undefined ? "slide" : "deck";
   if (value === undefined) return { scope };
-  if (typeof value === "string") return THEME_BACKGROUND_SLOTS.includes(value) ? { type: "theme", slot: value, scope, value } : { type: "solid", color: value, scope, value };
+  if (typeof value === "string") {
+    if (THEME_BACKGROUND_SLOTS.includes(value)) return { type: "theme", slot: value, scope, value };
+    if (IMAGE_SOURCE.test(value)) return { type: "image", src: value, fit: "cover", scope, value };
+    return { type: "solid", color: value, scope, value };
+  }
   if (!isObject(value)) return { scope, value };
   const base = { type: value.type, opacity: value.opacity, scope, value };
   if (value.type === "theme") return { ...base, slot: value.slot };
   if (value.type === "solid") return { ...base, color: value.color };
   if (value.type === "gradient") return { ...base, angle: value.gradient?.angle, stops: structuredClone(value.gradient?.stops ?? []) };
-  if (value.type === "image") return { ...base, src: value.image?.src, fit: value.image?.fit };
+  if (value.type === "image") return { ...base, src: value.src, alt: value.alt, fit: value.fit, focus: value.focus && { ...value.focus }, recolor: value.recolor && structuredClone(value.recolor), overlay: value.overlay && { ...value.overlay } };
   if (value.type === "pattern") return { ...base, preset: value.pattern?.preset, foregroundColor: value.pattern?.foregroundColor, backgroundColor: value.pattern?.backgroundColor };
   return base;
 }

package/dist/block-controls.js

@@ -13,18 +13,18 @@ export function createBlockControls(root, options) {
   function apply(prepared){
     if(!prepared?.changed){cancel();return true;}
     // Retain changes outside the guarded containers and preflight the exact candidate.
-    const candidate=applyJsonPatch(editor.document,prepared.patches);
+    const candidate=applyJsonPatch(editor.presentation,prepared.patches);
     options.validate(candidate);
     committing=true;
     try{cancel();editor.applyPatch(prepared.patches,{source:'canvas-block-edit',rejectInvalid:true});options.onMove?.(prepared.path);([ ...layer.querySelectorAll("[data-block-path]")].find(node=>node.dataset.blockPath===prepared.path)??layer.querySelector('[data-block-add]'))?.focus();options.clearError?.();options.onCommit?.({path:prepared.path,editor});return true;}
     finally{committing=false;}
   }
-  function move(from,to,index,base=editor.document){
+  function move(from,to,index,base=editor.presentation){
     try{return apply(prepareBlockMove(base,from,to,index));}catch(error){cancel();options.onError(error);return false;}
   }
   function open(path){
     if(!options.beforeEdit())return;
-    cancel();returnFocus=doc.activeElement;path=opfPathToJsonPointer(path);const base=editor.document,parts=splitOpfPath(path),container=opfPathToJsonPointer(parts.slice(0,-2)),index=Number(parts.at(-1));
+    cancel();returnFocus=doc.activeElement;path=opfPathToJsonPointer(path);const base=editor.presentation,parts=splitOpfPath(path),container=opfPathToJsonPointer(parts.slice(0,-2)),index=Number(parts.at(-1));
     const source=getValueAtPath(base,[...parts.slice(0,-2),'blocks']);
     if(parts.at(-2)!=='blocks'||!Number.isInteger(index)||index<0||!Array.isArray(source)||index>=source.length){options.onError(new Error('Choose an existing content block.'));return;}
     const count=source.length;
@@ -56,7 +56,7 @@ export function createBlockControls(root, options) {
   }
   function openInsert(containerPath,index) {
     if(!options.beforeEdit())return;
-    cancel();returnFocus=doc.activeElement;const base=editor.document;
+    cancel();returnFocus=doc.activeElement;const base=editor.presentation;
     const containers=listBlockContainers(base,{slideIndex:options.slideIndex(),includeImplicit:true});
     if(!containers.length){options.onError(new Error('No content container is available on this slide.'));return;}
     const requested=containerPath===undefined?containers[0].path:opfPathToJsonPointer(containerPath);
@@ -91,7 +91,7 @@ export function createBlockControls(root, options) {
     panel.append(add,close);panel.onkeydown=event=>{if(event.key==='Escape'){event.preventDefault();event.stopPropagation();cancel();}};
     layer.append(panel);kind.focus();
   }
-  function update(document,nextGeometry){
+  function update(presentation,nextGeometry){
     geometry=nextGeometry;
     if(drag)return;
     cancel();layer.replaceChildren();cells=[];
@@ -99,7 +99,7 @@ export function createBlockControls(root, options) {
     const add=doc.createElement('button');add.type='button';add.textContent='+ Add content';add.setAttribute('aria-label','Add content');add.dataset.blockAdd='';
     add.style.cssText='position:absolute;right:8px;top:8px;pointer-events:auto;padding:5px 9px;background:#f6f3fc;color:#675394;border:1px solid #cfc4e7;border-radius:5px;font:12px system-ui;cursor:pointer';add.onclick=()=>openInsert();layer.append(add);
     for(const flow of geometry.flows??[]){
-      const blocks=getValueAtPath(document,[...splitOpfPath(flow.path),'blocks']);
+      const blocks=getValueAtPath(presentation,[...splitOpfPath(flow.path),'blocks']);
       if(!Array.isArray(blocks)||blocks.length!==flow.itemCount)continue;
       blocks.forEach((block,index)=>{
         const col=flow.columns[index%flow.columns.length],row=flow.rows[Math.floor(index/flow.columns.length)];if(!col||!row)return;
@@ -116,7 +116,7 @@ export function createBlockControls(root, options) {
         node.onkeydown=event=>{if(['ArrowLeft','ArrowUp','ArrowRight','ArrowDown'].includes(event.key)){event.preventDefault();event.stopPropagation();if(!options.beforeEdit())return;const delta=['ArrowLeft','ArrowUp'].includes(event.key)?-1:1;if(index+delta>=0&&index+delta<blocks.length)move(path,container,index+(delta>0?2:-1));}};
         node.ondragstart=event=>{
           if(!options.beforeEdit()){event.preventDefault();return;}
-          cancel();drag={from:path,container,index,base:editor.document,signature:signature(container),cells:[...cells],prepared:null};
+          cancel();drag={from:path,container,index,base:editor.presentation,signature:signature(container),cells:[...cells],prepared:null};
           event.dataTransfer.effectAllowed='move';event.dataTransfer.setData('text/plain',path);
         };
         node.ondragend=()=>{cancel();options.render();};layer.append(node);

package/dist/block-convert.d.ts

@@ -32,7 +32,7 @@ export interface BlockConversionTarget {
   reason?: string;
 }
 export interface PreparedBlockConversion {
-  document: unknown;
+  presentation: unknown;
   patches: JsonPatchOperation[];
   path: string;
   changed: boolean;
@@ -41,8 +41,8 @@ export interface PreparedBlockConversion {
   from: BlockKind;
   to: BlockKind;
 }
-export interface BlockConversionChange extends Omit<EditorChange, "document" | "patches"> {
-  document: unknown;
+export interface BlockConversionChange extends Omit<EditorChange, "presentation" | "patches"> {
+  presentation: unknown;
   patches: JsonPatchOperation[];
   lossless: boolean;
   loss: string[];
@@ -53,12 +53,12 @@ export interface BlockConversionChange extends Omit<EditorChange, "document" | "
 }
 
 /** The single content payload of the block at `path`, or undefined (image-only, groups and blocks with several fields have none to convert). */
-export declare function readBlockContent(document: unknown, path: string | string[]): BlockContent | undefined;
+export declare function readBlockContent(presentation: unknown, path: string | string[]): BlockContent | undefined;
 /** The block that contains a selected path (slides.0.blocks.1.text maps to slides.0.blocks.1), or undefined. */
-export declare function blockPathForSelection(document: unknown, selectedPath: string): string | undefined;
+export declare function blockPathForSelection(presentation: unknown, selectedPath: string): string | undefined;
 /** The kinds the block can convert to, each with its loss report or the reason it is unavailable. */
-export declare function blockConversionTargets(document: unknown, path: string | string[]): BlockConversionTarget[];
+export declare function blockConversionTargets(presentation: unknown, path: string | string[]): BlockConversionTarget[];
 /** Compute the conversion patch without touching a session. Throws `block-not-convertible` for an unsupported pair or content that does not fit. */
-export declare function prepareBlockConversion(document: unknown, path: string | string[], kind: BlockKind, options?: ConvertOptions): PreparedBlockConversion;
+export declare function prepareBlockConversion(presentation: unknown, path: string | string[], kind: BlockKind, options?: ConvertOptions): PreparedBlockConversion;
 /** Convert one block as a single undoable transaction. */
 export declare function convertBlock(editor: EditorSession, path: string | string[], kind: BlockKind, meta?: Record<string, unknown>, options?: ConvertOptions): BlockConversionChange;

package/dist/block-convert.js

@@ -5,9 +5,10 @@
 // transaction around them: it finds the block, turns the converted payload into one guarded patch, validates
 // the document, and applies it as one undoable step.
 import { CONTENT_CONVERSIONS, CONTENT_KIND_LABELS, OPFConversionError, contentConversionTargets, convertContent, readContent } from "@openpresentation/opf/convert";
-import { applyJsonPatch, getValueAtPath, opfPathToJsonPointer, splitOpfPath, validateOpfDocument } from "./index.js";
+import { applyJsonPatch, getValueAtPath, opfPathToJsonPointer, splitOpfPath } from "./index.js";
 import { listBlockContainers } from "./blocks.js";
 import { fail } from "./edit-helpers.js";
+import { firstErrorMessage, errorFindings, checkFormat } from "./checks.js";
 
 /** Every content kind a block can hold, with its display label. */
 export const BLOCK_KIND_LABELS = CONTENT_KIND_LABELS;
@@ -32,7 +33,7 @@ function convertOwner(owner, kind, options) {
  * region that holds exactly one content field), or a group of metric blocks (a `blocks` array in a
  * slide, region or group). Returns undefined when there is none.
  */
-export function readBlockContent(document, path) {
+export function readBlockContent(presentation, path) {
   let parts;
   try {
     parts = splitOpfPath(path);
@@ -41,7 +42,7 @@ export function readBlockContent(document, path) {
   }
   const pointer = opfPathToJsonPointer(parts);
   const explicit = parts.at(-2) === "blocks" && /^(0|[1-9][0-9]*)$/.test(parts.at(-1) ?? "");
-  const owner = getValueAtPath(document, parts);
+  const owner = getValueAtPath(presentation, parts);
   if (!owner || typeof owner !== "object" || Array.isArray(owner)) return undefined;
   if (Array.isArray(owner.blocks)) {
     // Only a set of metrics converts as a group; any other group has nothing to offer.
@@ -49,7 +50,7 @@ export function readBlockContent(document, path) {
     return { path: parts, explicit, owner, key: "blocks", kind: "group", content: owner.blocks };
   }
   if (!explicit) {
-    const implicit = listBlockContainers(document, { includeImplicit: true }).find((entry) => entry.path === pointer && entry.implicit);
+    const implicit = listBlockContainers(presentation, { includeImplicit: true }).find((entry) => entry.path === pointer && entry.implicit);
     if (!implicit || implicit.count !== 1) return undefined;
   }
   const info = readContent(owner);
@@ -58,7 +59,7 @@ export function readBlockContent(document, path) {
 }
 
 /** Whether `path` is inside a block and, if so, that block's path. A selection such as slides.0.blocks.1.text maps to slides.0.blocks.1. */
-export function blockPathForSelection(document, selectedPath) {
+export function blockPathForSelection(presentation, selectedPath) {
   let parts;
   try {
     parts = splitOpfPath(selectedPath);
@@ -68,7 +69,7 @@ export function blockPathForSelection(document, selectedPath) {
   for (let length = parts.length; length >= 2; length -= 1) {
     const candidate = parts.slice(0, length);
     if (candidate[0] !== "slides") return undefined;
-    const found = readBlockContent(document, candidate);
+    const found = readBlockContent(presentation, candidate);
     // A slide or region that holds one payload inline is a block only when the selection is that payload.
     if (found && found.kind !== "group" && (found.explicit || parts[length] === found.key)) return candidate.join(".");
   }
@@ -79,7 +80,7 @@ export function blockPathForSelection(document, selectedPath) {
  * The nearest group of metric blocks around a selection (`slides.0.blocks.2.metric` finds `slides.0` when the
  * slide's blocks are all metrics), or undefined. A group of metrics converts to a table as a whole.
  */
-export function metricGroupForSelection(document, selectedPath) {
+export function metricGroupForSelection(presentation, selectedPath) {
   let parts;
   try {
     parts = splitOpfPath(selectedPath);
@@ -89,7 +90,7 @@ export function metricGroupForSelection(document, selectedPath) {
   if (parts[0] !== "slides") return undefined;
   for (let length = parts.length; length >= 2; length -= 1) {
     const candidate = parts.slice(0, length);
-    const found = readBlockContent(document, candidate);
+    const found = readBlockContent(presentation, candidate);
     if (found?.kind === "group") return candidate.join(".");
   }
   return undefined;
@@ -101,10 +102,10 @@ export function metricGroupForSelection(document, selectedPath) {
  * Returns [] for a block with no convertible content (image, video, a group that is not a set of metrics, several fields).
  * `options` are core's conversion options (`looseWhen`, `fences`, `headings`, `columns`, `delimiter`, `header`).
  */
-export function blockConversionTargets(document, path, options = {}) {
-  const found = readBlockContent(document, path);
+export function blockConversionTargets(presentation, path, options = {}) {
+  const found = readBlockContent(presentation, path);
   // RR-54: a table that shows a shared dataset needs the document's datasets to convert to anything but a chart.
-  return found ? contentConversionTargets(found.owner, { document, ...options }) : [];
+  return found ? contentConversionTargets(found.owner, { presentation: presentation, ...options }) : [];
 }
 
 /**
@@ -112,21 +113,21 @@ export function blockConversionTargets(document, path, options = {}) {
  * Throws `block-not-convertible` for a pair with no safe mapping or content that does not fit.
  * `prepared.loss` lists what the target cannot carry; `lossless` is true when nothing is lost.
  */
-export function prepareBlockConversion(document, path, kind, options = {}) {
-  const found = readBlockContent(document, path);
+export function prepareBlockConversion(presentation, path, kind, options = {}) {
+  const found = readBlockContent(presentation, path);
   if (!found) throw refuse(CHOOSE, { path });
   const pointer = opfPathToJsonPointer(found.path);
   const from = found.kind;
-  const result = convertOwner(found.owner, kind, { document, ...options });
-  if (!result.changed) return { document: structuredClone(document), patches: [], path: found.path.join("."), changed: false, lossless: true, loss: [], from, to: kind };
+  const result = convertOwner(found.owner, kind, { presentation: presentation, ...options });
+  if (!result.changed) return { presentation: structuredClone(presentation), patches: [], path: found.path.join("."), changed: false, lossless: true, loss: [], from, to: kind };
   const patches = [
     { op: "test", path: pointer, value: structuredClone(found.owner) },
     { op: "replace", path: pointer, value: result.payload },
   ];
-  const next = applyJsonPatch(document, patches);
-  const validation = validateOpfDocument(next);
-  if (!validation.valid) throw fail("invalid-opf-edit", validation.errors[0]?.message ?? "The converted block is not valid OPF.", { issues: validation.errors, patches });
-  return { document: next, patches, path: found.path.join("."), changed: true, lossless: result.lossless, loss: result.loss, from, to: kind };
+  const next = applyJsonPatch(presentation, patches);
+  const validation = checkFormat(next);
+  if (!validation.valid) throw fail("invalid-opf-edit", firstErrorMessage(validation, "The converted block is not valid OPF."), { issues: errorFindings(validation), patches });
+  return { presentation: next, patches, path: found.path.join("."), changed: true, lossless: result.lossless, loss: result.loss, from, to: kind };
 }
 
 /**
@@ -135,9 +136,9 @@ export function prepareBlockConversion(document, path, kind, options = {}) {
  */
 export function convertBlock(editor, path, kind, meta = {}, options = {}) {
   if (!editor || typeof editor.applyPatch !== "function") throw fail("invalid-editor", "Expected an editor session created by createEditorSession.");
-  const prepared = prepareBlockConversion(editor.document, path, kind, options);
+  const prepared = prepareBlockConversion(editor.presentation, path, kind, options);
   const summary = { lossless: prepared.lossless, loss: prepared.loss, from: prepared.from, to: prepared.to, path: prepared.path, changed: prepared.changed };
-  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(prepared.patches, { ...meta, source: meta.source ?? "block-conversion", blockPath: prepared.path, from: prepared.from, to: prepared.to });
   return { ...change, ...summary };
 }

package/dist/blocks.d.ts

@@ -1,15 +1,15 @@
 import type {JsonPatchOperation} from './index.js';
 /** Move a complete block; toIndex is the insertion position before removal. */
-export declare function prepareBlockMove(document:unknown,fromPath:string,toContainerPath:string,toIndex:number):{
- document:unknown;patches:JsonPatchOperation[];path:string;changed:boolean;
+export declare function prepareBlockMove(presentation:unknown,fromPath:string,toContainerPath:string,toIndex:number):{
+ presentation:unknown;patches:JsonPatchOperation[];path:string;changed:boolean;
 };
-export declare function listBlockContainers(document:unknown,options?:{slideIndex?:number;includeImplicit?:boolean}):{path:string;label:string;count:number;implicit?:boolean}[];
+export declare function listBlockContainers(presentation:unknown,options?:{slideIndex?:number;includeImplicit?:boolean}):{path:string;label:string;count:number;implicit?:boolean}[];
 
-export interface PreparedBlockChange { document:unknown;patches:JsonPatchOperation[];path:string;changed:boolean }
-export declare function prepareBlockInsert(document:unknown,containerPath:string,block:unknown,index?:number):PreparedBlockChange;
-export declare function prepareBlockDuplicate(document:unknown,path:string):PreparedBlockChange;
-export declare function prepareBlockRemove(document:unknown,path:string):PreparedBlockChange;
+export interface PreparedBlockChange { presentation:unknown;patches:JsonPatchOperation[];path:string;changed:boolean }
+export declare function prepareBlockInsert(presentation:unknown,containerPath:string,block:unknown,index?:number):PreparedBlockChange;
+export declare function prepareBlockDuplicate(presentation:unknown,path:string):PreparedBlockChange;
+export declare function prepareBlockRemove(presentation:unknown,path:string):PreparedBlockChange;
 /** Replace one complete block (or a slide/region's single content field). Replacement only: the old payload is discarded and nothing is converted between content types. Keeps `id` and `extensions` when the new block sets none. */
-export declare function prepareBlockReplace(document:unknown,path:string,block:unknown):PreparedBlockChange;
+export declare function prepareBlockReplace(presentation:unknown,path:string,block:unknown):PreparedBlockChange;
 export type ContentBlockKind='text'|'list'|'chart'|'table'|'metric'|'quote'|'code'|'timeline'|'group'|'image'|'video';
 export declare function createContentBlock(kind:ContentBlockKind,options?:{source?:string}):Record<string,unknown>;

package/dist/blocks.js

@@ -1,20 +1,21 @@
-import {splitOpfPath,opfPathToJsonPointer,getValueAtPath,applyJsonPatch,validateOpfDocument} from './index.js';
+import { splitOpfPath, opfPathToJsonPointer, getValueAtPath, applyJsonPatch } from './index.js';
+import { firstErrorMessage, checkFormat } from "./checks.js";
 const prefix=(a,b)=>a.length<=b.length&&a.every((part,i)=>part===b[i]);
 
 /** Move one complete block. The insertion index refers to the destination before removal. */
-export function prepareBlockMove(document,fromPath,toContainerPath,toIndex) {
+export function prepareBlockMove(presentation,fromPath,toContainerPath,toIndex) {
   const from=splitOpfPath(fromPath),to=splitOpfPath(toContainerPath);
   if(from.at(-2)!=='blocks'||!/^(0|[1-9][0-9]*)$/.test(from.at(-1)??''))throw new TypeError('Move a complete block using its blocks/index path.');
   const sourceIndex=Number(from.at(-1)),sourceContainer=from.slice(0,-2),sourceArray=from.slice(0,-1);
-  const containers=new Set(listBlockContainers(document).map(item=>item.path));
+  const containers=new Set(listBlockContainers(presentation).map(item=>item.path));
   if(!containers.has(opfPathToJsonPointer(sourceContainer))||!containers.has(opfPathToJsonPointer(to)))throw new TypeError('Choose slide or group block containers.');
-  const source=getValueAtPath(document,sourceArray),destination=getValueAtPath(document,[...to,'blocks']);
+  const source=getValueAtPath(presentation,sourceArray),destination=getValueAtPath(presentation,[...to,'blocks']);
   if(!Array.isArray(source)||sourceIndex>=source.length||!Array.isArray(destination))throw new RangeError('Source and destination must be existing block containers.');
   if(!Number.isInteger(toIndex)||toIndex<0||toIndex>destination.length)throw new RangeError('Destination insertion index is out of range.');
   if(prefix(from,to))throw new Error('A group cannot move into itself or one of its descendants.');
   const same=JSON.stringify(sourceContainer)===JSON.stringify(to);
   const index=same&&toIndex>sourceIndex?toIndex-1:toIndex;
-  if(same&&index===sourceIndex)return {document:structuredClone(document),patches:[],path:opfPathToJsonPointer(from),changed:false};
+  if(same&&index===sourceIndex)return {presentation:structuredClone(presentation),patches:[],path:opfPathToJsonPointer(from),changed:false};
   if(!same&&source.length===1)throw new Error('This move would leave an empty block container. Move the group or add another block first.');
   // Removing a preceding sibling shifts a destination group's address.
   const rebased=[...to];
@@ -22,16 +23,16 @@ export function prepareBlockMove(document,fromPath,toContainerPath,toIndex) {
     rebased[sourceArray.length]=String(Number(to[sourceArray.length])-1);
   const target=[...rebased,'blocks',String(index)];
   const guards=[sourceContainer,...(same?[]:[to])].filter((path,i,all)=>!all.some((other,j)=>j!==i&&other.length<path.length&&prefix(other,path)));
-  const patches=[...guards.map(path=>({op:'test',path:opfPathToJsonPointer(path),value:structuredClone(getValueAtPath(document,path))})),
+  const patches=[...guards.map(path=>({op:'test',path:opfPathToJsonPointer(path),value:structuredClone(getValueAtPath(presentation,path))})),
     {op:'remove',path:opfPathToJsonPointer(from)},
     {op:'add',path:opfPathToJsonPointer(target),value:structuredClone(source[sourceIndex])}];
-  const next=applyJsonPatch(document,patches),validation=validateOpfDocument(next);
-  if(!validation.valid)throw new Error(validation.errors[0]?.message??'The moved document is not valid OPF.');
-  return {document:next,patches,path:opfPathToJsonPointer(target),changed:true};
+  const next=applyJsonPatch(presentation,patches),validation=checkFormat(next);
+  if(!validation.valid)throw new Error(firstErrorMessage(validation, 'The moved document is not valid OPF.'));
+  return {presentation:next,patches,path:opfPathToJsonPointer(target),changed:true};
 }
 
 /** Discover actual block containers without interpreting imported content as instructions. */
-export function listBlockContainers(document,{slideIndex,includeImplicit=false}={}) {
+export function listBlockContainers(presentation,{slideIndex,includeImplicit=false}={}) {
   const result=[];
   function visit(value,path,label,depth=0){
     if(!value||typeof value!=='object'||depth>32)return;
@@ -40,7 +41,7 @@ export function listBlockContainers(document,{slideIndex,includeImplicit=false}=
       value.blocks.forEach((block,i)=>visit(block,[...path,'blocks',String(i)],`${label} › Group ${i+1}`,depth+1));
     }
   }
-  (document?.slides??[]).forEach((slide,i)=>{
+  (presentation?.slides??[]).forEach((slide,i)=>{
     if(slideIndex!==undefined&&slideIndex!==i)return;
     const path=['slides',String(i)],label=`Slide ${i+1}`;
     if(includeImplicit&&!Array.isArray(slide.blocks)&&!Object.keys(slide).some(isRegion))result.push({path:opfPathToJsonPointer(path),label,count:contentFields.filter(key=>Object.hasOwn(slide,key)).length,implicit:true});
@@ -53,20 +54,20 @@ export function listBlockContainers(document,{slideIndex,includeImplicit=false}=
 
 const contentFields=['text','items','bullets','image','video','chart','table','code','metric','quote','timeline'];
 const isRegion=key=>/^(?:(?:top|middle|bottom)(?:\+(?:top|middle|bottom))*(?::(?:left|center|right)(?:\+(?:left|center|right))*)?|(?:left|center|right)(?:\+(?:left|center|right))*)$/.test(key);
-function preparedChange(document,container,next,path) {
+function preparedChange(presentation,container,next,path) {
   const pointer=opfPathToJsonPointer(container);
-  const patches=[{op:'test',path:pointer,value:structuredClone(getValueAtPath(document,container))},
+  const patches=[{op:'test',path:pointer,value:structuredClone(getValueAtPath(presentation,container))},
     {op:'replace',path:pointer,value:next}];
-  const result=applyJsonPatch(document,patches),validation=validateOpfDocument(result);
-  if(!validation.valid)throw new Error(validation.errors[0]?.message??'The changed document is not valid OPF.');
-  return {document:result,patches,path:opfPathToJsonPointer(path),changed:true};
+  const result=applyJsonPatch(presentation,patches),validation=checkFormat(result);
+  if(!validation.valid)throw new Error(firstErrorMessage(validation, 'The changed document is not valid OPF.'));
+  return {presentation:result,patches,path:opfPathToJsonPointer(path),changed:true};
 }
 /** Insert into a slide, existing group or named region. Implicit payloads become blocks. */
-export function prepareBlockInsert(document,containerPath,block,index) {
+export function prepareBlockInsert(presentation,containerPath,block,index) {
   const path=splitOpfPath(containerPath),pointer=opfPathToJsonPointer(path);
-  if(!listBlockContainers(document,{includeImplicit:true}).some(c=>c.path===pointer))throw new TypeError('Choose a slide, group or named region content container.');
+  if(!listBlockContainers(presentation,{includeImplicit:true}).some(c=>c.path===pointer))throw new TypeError('Choose a slide, group or named region content container.');
   if(!block||typeof block!=='object'||Array.isArray(block))throw new TypeError('Insert an OPF content block object.');
-  const next=structuredClone(getValueAtPath(document,path));
+  const next=structuredClone(getValueAtPath(presentation,path));
   if(!Array.isArray(next.blocks)){
     next.blocks=contentFields.filter(key=>Object.hasOwn(next,key)).map(key=>({...(next.type?{type:next.type}:{}),[key]:next[key]}));
     for(const key of [...contentFields,'type'])delete next[key];
@@ -74,12 +75,12 @@ export function prepareBlockInsert(document,containerPath,block,index) {
   const at=index??next.blocks.length;
   if(!Number.isInteger(at)||at<0||at>next.blocks.length)throw new RangeError('Insertion index is out of range.');
   next.blocks.splice(at,0,structuredClone(block));
-  return preparedChange(document,path,next,[...path,'blocks',String(at)]);
+  return preparedChange(presentation,path,next,[...path,'blocks',String(at)]);
 }
-function checkedBlock(document,path) {
+function checkedBlock(presentation,path) {
   const parts=splitOpfPath(path),container=parts.slice(0,-2),index=Number(parts.at(-1));
-  if(parts.at(-2)!=='blocks'||!/^(0|[1-9][0-9]*)$/.test(parts.at(-1)??'')||!listBlockContainers(document).some(c=>c.path===opfPathToJsonPointer(container)))throw new TypeError('Choose a complete block using its blocks/index path.');
-  const blocks=getValueAtPath(document,[...container,'blocks']);
+  if(parts.at(-2)!=='blocks'||!/^(0|[1-9][0-9]*)$/.test(parts.at(-1)??'')||!listBlockContainers(presentation).some(c=>c.path===opfPathToJsonPointer(container)))throw new TypeError('Choose a complete block using its blocks/index path.');
+  const blocks=getValueAtPath(presentation,[...container,'blocks']);
   if(index>=blocks.length)throw new RangeError('Block does not exist.');
   return {parts,container,index,blocks};
 }
@@ -90,21 +91,21 @@ function checkedBlock(document,path) {
  * region payload (exactly one content field, no `blocks`) is replaced in place, keeping its
  * other slide fields. The test guard fails if the block changed since it was read.
  */
-export function prepareBlockReplace(document,path,block) {
+export function prepareBlockReplace(presentation,path,block) {
   if(!block||typeof block!=='object'||Array.isArray(block))throw new TypeError('Replace with an OPF content block object.');
   const parts=splitOpfPath(path),pointer=opfPathToJsonPointer(parts);
   const explicit=parts.at(-2)==='blocks'&&/^(0|[1-9][0-9]*)$/.test(parts.at(-1)??'');
   let old,next;
   if(explicit){
-    const {index,blocks}=checkedBlock(document,path);
+    const {index,blocks}=checkedBlock(presentation,path);
     old=blocks[index];
     next=structuredClone(block);
     for(const key of ['id','extensions'])if(next[key]===undefined&&old[key]!==undefined)next[key]=structuredClone(old[key]);
   } else {
-    const implicit=listBlockContainers(document,{includeImplicit:true}).find(c=>c.path===pointer&&c.implicit);
+    const implicit=listBlockContainers(presentation,{includeImplicit:true}).find(c=>c.path===pointer&&c.implicit);
     if(!implicit)throw new TypeError('Choose a complete block using its blocks/index path, or a slide or region with one content field.');
     if(implicit.count!==1)throw new TypeError('This slide or region holds several content fields. Choose one block, or insert and remove blocks.');
-    old=getValueAtPath(document,parts);
+    old=getValueAtPath(presentation,parts);
     next=structuredClone(old);
     for(const key of [...contentFields,'type'])delete next[key];
     // The block's own id and extensions would overwrite the slide's; they are not carried over.
@@ -112,28 +113,28 @@ export function prepareBlockReplace(document,path,block) {
     Object.assign(next,payload);
   }
   const patches=[{op:'test',path:pointer,value:structuredClone(old)},{op:'replace',path:pointer,value:next}];
-  const result=applyJsonPatch(document,patches),validation=validateOpfDocument(result);
-  if(!validation.valid)throw new Error(validation.errors[0]?.message??'The replaced block is not valid OPF.');
-  return {document:result,patches,path:pointer,changed:JSON.stringify(old)!==JSON.stringify(next)};
+  const result=applyJsonPatch(presentation,patches),validation=checkFormat(result);
+  if(!validation.valid)throw new Error(firstErrorMessage(validation, 'The replaced block is not valid OPF.'));
+  return {presentation:result,patches,path:pointer,changed:JSON.stringify(old)!==JSON.stringify(next)};
 }
 /** Duplicate the entire block immediately after itself, preserving formatting and asset references. */
-export function prepareBlockDuplicate(document,path) {
-  const {container,index,blocks}=checkedBlock(document,path);
-  return prepareBlockInsert(document,opfPathToJsonPointer(container),blocks[index],index+1);
+export function prepareBlockDuplicate(presentation,path) {
+  const {container,index,blocks}=checkedBlock(presentation,path);
+  return prepareBlockInsert(presentation,opfPathToJsonPointer(container),blocks[index],index+1);
 }
 /** Delete a block and prune empty ancestor groups; a slide itself is never deleted. */
-export function prepareBlockRemove(document,path) {
-  let {parts,container,index,blocks}=checkedBlock(document,path);
+export function prepareBlockRemove(presentation,path) {
+  let {parts,container,index,blocks}=checkedBlock(presentation,path);
   while(blocks.length===1&&container.length>2){
     if(container.length===3&&isRegion(container[2])){
-      const slidePath=container.slice(0,2),next=structuredClone(getValueAtPath(document,slidePath));delete next[container[2]];
-      return preparedChange(document,slidePath,next,slidePath);
+      const slidePath=container.slice(0,2),next=structuredClone(getValueAtPath(presentation,slidePath));delete next[container[2]];
+      return preparedChange(presentation,slidePath,next,slidePath);
     }
-    ({parts,container,index,blocks}=checkedBlock(document,container));
+    ({parts,container,index,blocks}=checkedBlock(presentation,container));
   }
-  const next=structuredClone(getValueAtPath(document,container));next.blocks.splice(index,1);
+  const next=structuredClone(getValueAtPath(presentation,container));next.blocks.splice(index,1);
   const selection=next.blocks.length?[...container,'blocks',String(Math.min(index,next.blocks.length-1))]:container;
-  return preparedChange(document,container,next,selection);
+  return preparedChange(presentation,container,next,selection);
 }
 
 /** Small, schema-valid starting points. Media requires an explicit source. */

package/dist/canvas-fields.js

@@ -1,11 +1,6 @@
-import {
-  applyJsonPatch,
-  createValuePatch,
-  validateOpfDocument,
-  splitOpfPath,
-  opfPathToJsonPointer,
-} from "./index.js";
+import { applyJsonPatch, createValuePatch, splitOpfPath, opfPathToJsonPointer } from "./index.js";
 import {preserveTextLineEndings} from './text-input.js';
+import { firstErrorMessage, checkFormat } from "./checks.js";
 export {preserveTextLineEndings} from './text-input.js';
 /** Scalar fields and collection paths use JSON Pointer to preserve arbitrary object keys. */
 export function getEditableFields(value, path) {
@@ -52,15 +47,43 @@ export function parseCanvasValue(text, type, original) {
   return type === 'string' && typeof original === 'string' ? preserveTextLineEndings(original,String(text)) : text;
 }
 
-export function createCanvasDraft(document, path, value) {
+export function createCanvasDraft(presentation, path, value) {
   const draft = applyJsonPatch(
-    document,
-    createValuePatch(document, path, value),
+    presentation,
+    createValuePatch(presentation, path, value),
   );
-  const validation = validateOpfDocument(draft);
+  const validation = checkFormat(draft);
   if (!validation.valid)
     throw new Error(
-      validation.errors[0]?.message ?? "This change is not valid OPF.",
+      firstErrorMessage(validation, "This change is not valid OPF."),
     );
   return draft;
 }
+
+/** The progress states of a timeline event (`TimelineEvent.status`). */
+export const TIMELINE_STATUS_CHOICES = Object.freeze(["done", "current", "planned"]);
+/** The fixed choices of a form field, or undefined for free text: an event's `status` inside a timeline payload. */
+export function fieldChoices(field) {
+  const segments = splitOpfPath(field.path);
+  return segments.at(-1) === "status" && segments.at(-3) === "timeline"
+    ? TIMELINE_STATUS_CHOICES
+    : segments.at(-1) === "status" && segments.at(-3) === "events" && segments.at(-4) === "timeline"
+      ? TIMELINE_STATUS_CHOICES
+      : undefined;
+}
+/**
+ * A blank copy of `value`'s shape for the "Add" button: texts empty, numbers 0, booleans false, `type`, `mode` and
+ * `language` kept. A timeline event's `status` is left out, so a new event starts with no status instead of a copy.
+ */
+export function emptyLike(value, key = "") {
+  if (Array.isArray(value)) return value.map((child) => emptyLike(child));
+  if (value && typeof value === "object")
+    return Object.fromEntries(
+      Object.entries(value)
+        .filter(([name]) => name !== "status")
+        .map(([name, child]) => [name, emptyLike(child, name)]),
+    );
+  if (typeof value === "number") return 0;
+  if (typeof value === "boolean") return false;
+  return ["type", "mode", "language"].includes(key) ? value : "";
+}