@openpresentation/opf-editor 0.14.2 → 0.15.0

package/dist/catalogs.js

@@ -0,0 +1,217 @@
+// Catalogs (FA-23, OPF 0.15). The editor never ships or imports catalog data: the host registers its catalogs (`Catalog[]`,
+// the shape core's `CatalogOptions.catalogs` takes, for example `defaultCatalog` from `@openpresentation/opf/catalog`), on the
+// session (`createEditorSession(doc, { catalogs })`) or per call. `mergeCatalogs` is the one function that turns those into the
+// one list the editor hands to core (resolution, validation, embedding, copying, updates), to the renderer and to the exporter.
+// Pickers list core's `catalogRecords` and write the reference it gives (`id` or `name:id`); saving and exporting embed every
+// referenced record with core's `embed`, so a saved document renders the same with no catalog registered.
+import { catalogKinds, catalogRecords, embed, moveToCustom as coreMoveToCustom, updateFromCatalog } from "@openpresentation/opf";
+import { OPFEditorError } from "./index.js";
+
+const isObject = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+
+/**
+ * One catalog list from any number of lists (or single catalogs): the session's registration first, then each host list, in order.
+ * A catalog is identified by its `source`; the first catalog with a source wins and later ones with the same source are dropped,
+ * so the host default (the first entry) never moves. Entries that are not catalogs throw `invalid-catalogs` (core's
+ * `OPFCatalogsOptionError` code).
+ */
+export function mergeCatalogs(...lists) {
+  const merged = [];
+  const sources = new Set();
+  for (const list of lists) {
+    if (list === undefined || list === null) continue;
+    for (const catalog of Array.isArray(list) ? list : [list]) {
+      if (catalog === undefined || catalog === null) continue;
+      if (!isObject(catalog) || typeof catalog.source !== "string" || catalog.source === "")
+        throw new OPFEditorError("invalid-catalogs", "A registered catalog is an object with a non-empty source, such as defaultCatalog from @openpresentation/opf/catalog.", { catalog });
+      if (sources.has(catalog.source)) continue;
+      sources.add(catalog.source);
+      merged.push(catalog);
+    }
+  }
+  return Object.freeze(merged);
+}
+
+/** The catalogs for one operation: the session's registered list (when `editor` is given), then `options.catalogs`. */
+export function catalogsFor(editor, options = {}) {
+  return mergeCatalogs(editor?.catalogs, options?.catalogs);
+}
+
+/** The label a picker shows for a record: its name, then its gallery label, then the id. */
+export function catalogRecordLabel(record, id) {
+  const gallery = isObject(record?.["x-gallery"]) ? record["x-gallery"] : {};
+  for (const value of [record?.name, record?.title, record?.label, gallery.label, gallery.name]) if (typeof value === "string" && value) return value;
+  return String(id);
+}
+
+/**
+ * Every record a picker can offer for `kind`, from core's `catalogRecords`: the document's embedded records first, then the
+ * registered catalogs'. Each entry is `{ id, reference, label, description, record, group, source, origin }`; `id` and
+ * `reference` are the reference to write (`id` or `name:id`). A reference is listed once.
+ */
+export function listCatalogRecords(presentation, kind, options = {}) {
+  const seen = new Set();
+  const out = [];
+  for (const entry of catalogRecords(presentation ?? {}, kind, { catalogs: mergeCatalogs(options.catalogs) })) {
+    if (seen.has(entry.reference)) continue;
+    seen.add(entry.reference);
+    const record = isObject(entry.record) ? entry.record : {};
+    out.push({
+      id: entry.reference,
+      reference: entry.reference,
+      label: catalogRecordLabel(record, entry.id),
+      ...(typeof record.description === "string" ? { description: record.description } : {}),
+      record,
+      group: entry.group,
+      ...(entry.source !== undefined ? { source: entry.source } : {}),
+      origin: entry.origin,
+    });
+  }
+  return out;
+}
+
+/**
+ * The document to save or hand on: core's `embed` adds every record the document references, once, under its catalog group
+ * (with the records those reference, `x-*` display metadata stripped), so it renders the same with no catalog registered.
+ * Returns `{ document, added, unresolved }`; the input is not changed.
+ */
+export function prepareSave(presentation, options = {}) {
+  const result = embed(presentation, { catalogs: mergeCatalogs(options.catalogs) });
+  return { document: result.document, added: result.added ?? [], unresolved: result.unresolved ?? [] };
+}
+
+/** `prepareSave` for the session's document, with the session's catalogs and `options.catalogs`. The session is not changed. */
+export function saveDocument(editor, options = {}) {
+  assertSession(editor);
+  return prepareSave(editor.presentation, { catalogs: catalogsFor(editor, options) });
+}
+
+/**
+ * The "Update from catalog" check: core's `updateFromCatalog` compares every record embedded under `default` or a named group
+ * (never `custom`) with the registered catalog's current record. Returns `{ changes, patch }`; nothing is applied. `refs` limits
+ * the check to some references (`[{ kind, reference }]`).
+ */
+export function checkCatalogUpdates(presentation, options = {}) {
+  const update = updateFromCatalog(presentation, mergeCatalogs(options.catalogs), options.refs);
+  return { changes: update.changes ?? [], patch: update.patch ?? [] };
+}
+
+/**
+ * Apply an update the author approved, as ONE undoable step. `options.refs` names the approved changes (`[{ kind, reference }]`);
+ * the update is recomputed for exactly those against the session's current document, so a stale review never applies. Returns
+ * the session change plus `changes` (what was applied) and `changed`.
+ */
+export function applyCatalogUpdate(editor, options = {}) {
+  assertSession(editor);
+  if (!Array.isArray(options.refs) || !options.refs.length) throw new OPFEditorError("no-approved-updates", "Choose the catalog updates to apply.");
+  const update = checkCatalogUpdates(editor.presentation, { catalogs: catalogsFor(editor, options), refs: options.refs });
+  if (!update.patch.length) return { changed: false, changes: [], presentation: editor.presentation, patches: [], inversePatches: [], validation: editor.validation };
+  const change = editor.applyPatch(update.patch, { ...options.meta, source: options.meta?.source ?? "catalog-update", catalogRecordEdit: "in-place", catalogUpdate: update.changes.map(({ kind, reference }) => ({ kind, reference })) });
+  return { ...change, changed: true, changes: update.changes };
+}
+
+/**
+ * Core finding codes about catalog references and embedded records, which the editor surfaces next to its catalog controls:
+ * a reference that resolves nowhere, a prefix with no catalog group, and a record embedded under a catalog's group that the
+ * registered catalog does not publish (offer `moveToCustom`).
+ */
+export const REFERENCE_FINDING_CODES = Object.freeze(["opf/unresolved-reference", "opf/undeclared-catalog", "opf/catalog-record-not-in-source"]);
+
+/** The reference and embedded-record findings (`REFERENCE_FINDING_CODES`) of a validation report (the session's `validation`). */
+export function referenceFindings(validation) {
+  return (validation?.findings ?? []).filter((finding) => REFERENCE_FINDING_CODES.includes(finding.ruleId ?? finding.code));
+}
+
+function assertSession(editor) {
+  if (!editor || typeof editor.applyPatch !== "function" || typeof editor.subscribe !== "function")
+    throw new OPFEditorError("invalid-editor", "Expected an editor session created by createEditorSession.");
+}
+
+/**
+ * The record an `opf/catalog-record-not-in-source` finding names, from its path (`/catalogs/<group>/<kind>/<id>` or the dotted
+ * form): `{ group, kind, id }`, or undefined for a path that names no embedded record.
+ */
+export function catalogRecordAt(path) {
+  const parts = typeof path === "string" ? (path.startsWith("/") ? path.slice(1).split("/").map((part) => part.replace(/~1/g, "/").replace(/~0/g, "~")) : path.split(".")) : [];
+  if (parts.length !== 4 || parts[0] !== "catalogs" || !catalogKinds.includes(parts[2])) return undefined;
+  return { group: parts[1], kind: parts[2], id: parts[3] };
+}
+
+const sameJson = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+
+/**
+ * Move a record embedded under `default` or a named group into `catalogs.custom` (the fix the `opf/catalog-record-not-in-source`
+ * finding offers, and the fork an edit makes) with core's `moveToCustom`: the document owns it from then on. Every reference that
+ * resolved to it is rewritten to the custom id (`options.id`, else its id, `<id>-2` and up on a conflict), and references written
+ * inside it keep naming what they named. Returns `{ presentation, patches, changed, from, to, references }`.
+ */
+export function prepareMoveToCustom(presentation, target, options = {}) {
+  const { group, kind, id } = target ?? {};
+  const groups = isObject(presentation?.catalogs) ? presentation.catalogs : {};
+  const record = isObject(groups[group]?.[kind]) ? groups[group][kind][id] : undefined;
+  if (group === "custom" || record === undefined) throw new OPFEditorError("not-a-catalog-record", "Choose a record embedded under catalogs.default or a named catalog group.", { group, kind, id });
+  // Core's moveToCustom is the one implementation: references follow, the record's own references keep naming what they named.
+  const reference = group === "default" ? id : `${group}:${id}`;
+  const moved = coreMoveToCustom(presentation, { kind, reference }, { catalogs: mergeCatalogs(options.catalogs), ...(options.id ? { id: options.id } : {}) });
+  const patches = [{ op: "test", path: "/catalogs", value: structuredClone(presentation.catalogs) }, ...moved.patch];
+  return { presentation: moved.document, patches, changed: true, from: { group, kind, id }, to: { group: "custom", kind, id: moved.to.id }, references: moved.references ?? [] };
+}
+
+/**
+ * `prepareMoveToCustom` on the session's document, as ONE undoable step (`meta.source: "catalog-move-to-custom"`). `options.id` names
+ * the custom record (default: the record's id, `<id>-2` on a conflict).
+ */
+export function moveToCustom(editor, target, options = {}) {
+  assertSession(editor);
+  const prepared = prepareMoveToCustom(editor.presentation, target, { catalogs: catalogsFor(editor, options), ...(options.id ? { id: options.id } : {}) });
+  const change = editor.applyPatch(prepared.patches, { ...options.meta, source: options.meta?.source ?? "catalog-move-to-custom", catalogRecordEdit: "in-place" });
+  return { ...change, changed: true, from: prepared.from, to: prepared.to };
+}
+
+/** The record kinds a user edits, which an edit forks into `catalogs.custom` when they live under a catalog's group. */
+export const FORKED_RECORD_KINDS = Object.freeze(["layouts", "themes", "colorSchemes", "fontSchemes"]);
+
+/**
+ * Records under `catalogs.default` or a named group whose content an edit from `before` to `after` changed (present in both, not
+ * equal). An added or removed record is not an edit. Returns `[{ group, kind, id }]`.
+ */
+export function editedCatalogRecords(before, after) {
+  const out = [];
+  const groupsBefore = isObject(before?.catalogs) ? before.catalogs : {};
+  const groupsAfter = isObject(after?.catalogs) ? after.catalogs : {};
+  for (const [group, value] of Object.entries(groupsAfter)) {
+    if (group === "custom" || !isObject(value) || !isObject(groupsBefore[group])) continue;
+    for (const kind of FORKED_RECORD_KINDS) {
+      const was = isObject(groupsBefore[group][kind]) ? groupsBefore[group][kind] : {};
+      const now = isObject(value[kind]) ? value[kind] : {};
+      for (const id of Object.keys(now)) if (Object.hasOwn(was, id) && !sameJson(was[id], now[id])) out.push({ group, kind, id });
+    }
+  }
+  return out;
+}
+
+/** The notice an editor shows after a fork: the record is the deck's own now and no longer receives catalog updates. */
+export function forkNotice(fork) {
+  const label = { layouts: "layout", themes: "theme", colorSchemes: "color scheme", fontSchemes: "font scheme" }[fork.from.kind] ?? fork.from.kind;
+  return `The ${label} ${fork.from.id} is now this presentation's own (${fork.to.id}); it no longer receives catalog updates.`;
+}
+
+/**
+ * Owner rule (FA-23): editing a record that lives under `catalogs.default` or a named group forks it into `catalogs.custom` instead
+ * of changing the catalog's record in place. Given the document before and after an edit, returns the document after the forks
+ * (each edited record moved to custom as `<id>-custom`, or `forkIds[<group>:<kind>:<id>]`, every reference rewritten, the
+ * original dropped) and `forks: [{ from, to }]`. Nothing to fork returns `after` and `[]`.
+ */
+export function forkEditedRecords(before, after, options = {}) {
+  let document = after;
+  const forks = [];
+  for (const target of editedCatalogRecords(before, after)) {
+    const custom = isObject(document.catalogs?.custom?.[target.kind]) ? document.catalogs.custom[target.kind] : {};
+    let id = options.forkIds?.[`${target.group}:${target.kind}:${target.id}`] ?? `${target.id}-custom`;
+    for (let n = 2; Object.hasOwn(custom, id); n += 1) id = `${target.id}-custom-${n}`;
+    const moved = prepareMoveToCustom(document, target, { catalogs: options.catalogs, id });
+    document = moved.presentation;
+    forks.push({ from: moved.from, to: moved.to });
+  }
+  return { document, forks };
+}

package/dist/checks.js

@@ -1,13 +1,15 @@
-// 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`).
+// The editor's one use of core's checker. Every edit is validated with core's `validate` for the `format` category and the two
+// catalog rules (`opf/unresolved-reference`, `opf/undeclared-catalog`, `opf/catalog-record-not-in-source`): the schema and semantic OPF rules, with no
+// layout built, so it is cheap enough to run on every keystroke and undo. `catalogs` are the host's registered catalogs, so a
+// reference that resolves in one of them is not reported. 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"]) });
+const EDIT_CATEGORIES = Object.freeze(["format", "opf/unresolved-reference", "opf/undeclared-catalog", "opf/catalog-record-not-in-source"]);
 
-/** Core's `ValidationReport` for the `format` category: `valid`, `findings`, `counts`, `schemaValid`. */
-export function checkFormat(presentation) {
-  return validate(presentation, FORMAT_ONLY);
+/** Core's `ValidationReport` for the `format` category and the catalog reference rules: `valid`, `findings`, `counts`, `schemaValid`. */
+export function checkFormat(presentation, options = {}) {
+  return validate(presentation, { only: EDIT_CATEGORIES, ...(options.catalogs?.length ? { catalogs: options.catalogs } : {}) });
 }
 
 /** The error-severity findings of a report: what makes it invalid. */

package/dist/content-actions.d.ts

@@ -72,9 +72,9 @@ export declare function ungroupBlock(editor: EditorSession, groupPath: string, m
 export declare function placeBlocksInRegions(editor: EditorSession, slideIndex: number, regions: string[], meta?: Record<string, unknown>): ContentActionChange;
 export declare function regionsAsBlocks(editor: EditorSession, slideIndex: number, meta?: Record<string, unknown>): ContentActionChange;
 export declare function moveSlideRegion(editor: EditorSession, slideIndex: number, from: string, to: string, options?: { swap?: boolean }, meta?: Record<string, unknown>): ContentActionChange;
-/** Move an image block into the slide's design as its slide image, background or watermark. */
+/** Move an image block into the slide's design as its background or watermark. */
 export declare function moveImageToDesign(editor: EditorSession, blockPath: string, target: ImageTarget, options?: PromoteImageOptions, meta?: Record<string, unknown>): ContentActionChange;
-/** Move a slide's own slide image, background image or watermark back into its content as an image block. */
+/** Move a slide's own 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(presentation: unknown, slideIndex: number, options?: { at?: number[]; each?: boolean; repeatHeadings?: boolean }): PreparedContentAction;

package/dist/content-actions.js

@@ -1,4 +1,4 @@
-// Content actions (RR-26): list levels, grouping, regions, images between content and design, and slide
+// Content actions (RR-26): list levels, grouping, regions, images between content and design (background or watermark), and slide
 // split and merge, as editor transactions. The pure transforms live in core (`@openpresentation/opf/convert`);
 // each action here finds its target in the document, calls the transform, turns the result into a guarded patch
 // (`test` of what was read, then `replace`, or per-slide `remove` and `add`), validates the document and, in the
@@ -143,12 +143,12 @@ export function prepareMoveRegion(presentation, slideIndex, from, to, options =
   slideParts(presentation, `slides.${slideIndex}`, "a slide");
   return slideAction(presentation, slideIndex, (slide) => moveRegion(slide, from, to, options), undefined, options.validate !== false);
 }
-/** Move the image block at `blockPath` into the slide's design as `slideImage`, `background` or `watermark`. */
+/** Move the image block at `blockPath` into the slide's design as its `background` or `watermark` (core's `promoteImage`). */
 export function prepareImageToDesign(presentation, blockPath, target, options = {}) {
   const { slideIndex, relative } = slideParts(presentation, blockPath, "an image block");
   return slideAction(presentation, slideIndex, (slide) => promoteImage(slide, asNumbers(relative), target, options), `slides.${slideIndex}`, options.validate !== false);
 }
-/** Move a slide's own `slideImage`, `background` image or `watermark` back into its content as an image block. */
+/** Move a slide's own `background` image or `watermark` back into its content as an image block (core's `demoteImage`). */
 export function prepareImageToContent(presentation, slideIndex, source, options = {}) {
   slideParts(presentation, `slides.${slideIndex}`, "a slide");
   return slideAction(presentation, slideIndex, (slide) => demoteImage(slide, source, options), undefined, options.validate !== false);

package/dist/content-controls.js

@@ -36,20 +36,20 @@ export const REGION_LAYOUTS = Object.freeze({
   4: [{ id: "grid", label: "Two by two", regions: ["top:left", "top:right", "bottom:left", "bottom:right"] }],
 });
 
-/** Where an image block can go in the slide's design. The value is `<target>` or `<target>:<position>`. */
+/**
+ * Where an image block can go in the slide's design (OPF 0.15): its background (a full-bleed photo behind the content) or its
+ * watermark. Bleeding an image to one edge beside the content is not a move: it is the block's `placement` (image-options.js).
+ */
 export const IMAGE_DESTINATIONS = Object.freeze([
-  { value: "slideImage:right", label: "Slide image, on the right", target: "slideImage", options: { position: "right" } },
-  { value: "slideImage:left", label: "Slide image, on the left", target: "slideImage", options: { position: "left" } },
-  { value: "slideImage:top", label: "Slide image, along the top", target: "slideImage", options: { position: "top" } },
-  { value: "slideImage:bottom", label: "Slide image, along the bottom", target: "slideImage", options: { position: "bottom" } },
-  { value: "slideImage:background", label: "Slide image, full slide behind the content", target: "slideImage", options: { position: "background" } },
-  { value: "background", label: "Slide background", target: "background", options: {} },
+  { value: "background", label: "Slide background, full slide behind the content", target: "background", options: {} },
   { value: "watermark", label: "Watermark", target: "watermark", options: {} },
 ]);
 
 const REGION_KEY = /^(?:(?:top|middle|bottom)(?:\+(?:top|middle|bottom))*(?::(?:left|center|right)(?:\+(?:left|center|right))*)?|(?:left|center|right)(?:\+(?:left|center|right))*)$/;
 const regionKeysOfSlide = (slide) => Object.keys(slide).filter((key) => REGION_KEY.test(key));
-const DESIGN_IMAGE_LABELS = { slideImage: "slide image", background: "background image", watermark: "watermark" };
+const DESIGN_IMAGE_LABELS = { background: "background image", watermark: "watermark" };
+// An image block's own framing fields (FA-22) do not stop it being "a block that holds only an image".
+const IMAGE_BLOCK_FIELDS = new Set(["id", "extensions", "type", "fit", "focus", "aspectRatio", "shape", "cornerRadius", "border", "opacity", "recolor", "overlay", "placement"]);
 const messageOf = (error) => error?.issues?.[0]?.message ?? error?.message ?? String(error);
 const lossText = (prepared) => (prepared.loss.length ? `Not carried over: ${prepared.loss.join(", ")}.` : "Nothing is lost.");
 
@@ -321,6 +321,6 @@ export function createContentControls(ctx) {
 function isImageBlock(editor, blockPath) {
   const block = editor.get(blockPath);
   if (!block || typeof block !== "object" || Array.isArray(block)) return false;
-  const keys = Object.keys(block).filter((key) => key !== "id" && key !== "extensions" && key !== "type");
+  const keys = Object.keys(block).filter((key) => !IMAGE_BLOCK_FIELDS.has(key));
   return keys.length === 1 && keys[0] === "image";
 }

package/dist/design-controls.d.ts

@@ -1,7 +1,13 @@
+import type { Catalog } from "@openpresentation/opf";
 import type { EditorSession } from "./index.js";
+import type { SwitchVocabularies } from "./switches.js";
 
-export type DesignControlSection = "look" | "background" | "slide-image" | "header-footer" | "brand" | "layout-options" | "info" | "selection" | "table" | "slide-content";
-/** Every section, in panel order. `selection` and `table` follow the host's current selection; `slide-content` (RR-26: blocks and regions, images between content and design) follows the current slide. */
+export type DesignControlSection = "look" | "background" | "header-footer" | "brand" | "layout-options" | "info" | "selection" | "image" | "table" | "slide-content" | "catalog";
+/**
+ * Every section, in panel order. `selection`, `image` (the selected image block's fit, focus, treatments and placement) and `table`
+ * follow the host's current selection; `slide-content` (RR-26: blocks and regions, images between content and design) follows the
+ * current slide; `catalog` lists the catalog reference findings and runs the explicit "Update from catalog".
+ */
 export declare const DESIGN_CONTROL_SECTIONS: readonly DesignControlSection[];
 
 export interface DesignControlsOptions {
@@ -14,9 +20,10 @@ export interface DesignControlsOptions {
   sections?: readonly DesignControlSection[];
   /** Initial "Applies to" choice. */
   scope?: "deck" | "slide";
-  /** Caller-loaded catalog records by kind (layouts, font schemes, themes, ...) for options the bundled catalogs do not have. */
-  catalogs?: Record<string, unknown>;
-  catalogSources?: Record<string, unknown>;
+  /** Host catalogs for the pickers, merged after the session's registered ones. */
+  catalogs?: readonly Catalog[];
+  /** Display metadata for the engine vocabularies (languages, chart types, social platforms): `catalogDisplay` from `@openpresentation/opf/catalog`. */
+  vocabularies?: SwitchVocabularies;
   /** Called after every committed change (never for a refused one). */
   onChange?: (change: unknown) => void;
   /** Called after a content conversion or replacement with the path to keep selected (the block, or the inline payload field), since the old selection path may no longer exist. */