@openpresentation/opf-editor 0.15.0 → 0.17.0

package/dist/design-options.js

@@ -5,6 +5,7 @@
 // session form that commits it with `meta.source: "design-option"`.
 import { getValueAtPath, opfPathToJsonPointer } from "./index.js";
 import { checkedDocument, designPatches, fail, same } from "./edit-helpers.js";
+import { listBuiltinVariables } from "@openpresentation/opf";
 import { checkFormat } from "./checks.js";
 
 /** The `design.logo` variant slots of a LogoSet, in schema order. */
@@ -24,8 +25,30 @@ export const LOGO_VARIANTS = Object.freeze([
 ]);
 export const HEADER_FOOTER_ZONES = Object.freeze(["left", "center", "right"]);
 // Flag fields of a header/footer zone: false is stored as "absent" (so is a `date` of false).
-const ZONE_FLAGS = ["logo", "slideNumber", "organization", "speaker", "socials", "section"];
-export const ZONE_FIELDS = Object.freeze(["logo", "text", "image", "slideNumber", "slideNumberFormat", "date", "dateFormat", "organization", "speaker", "socials", "section"]);
+const ZONE_FLAGS = ["logo", "socials"];
+export const ZONE_FIELDS = Object.freeze(["logo", "text", "image", "date", "dateFormat", "socials"]);
+// FA-31: generated values are `{{ }}` variables inside a zone's `text`. The keys 0.16 had for them are gone; say what to write instead.
+const REMOVED_ZONE_FIELDS = Object.freeze({
+  organization: "Write {{organization.name}} in the text.",
+  speaker: "Write {{speaker.name}} in the text.",
+  section: "Write {{slide.section}} in the text.",
+  slideNumber: "Write {{slide.number}} in the text.",
+  slideNumberFormat: "Write {{slide.number}} and {{deck.slideCount}} in the text.",
+});
+/**
+ * The values the "Insert value" menu of a header or footer zone offers, in menu order. `token` is what lands in the zone's `text`.
+ * `{{slide.number}}`, `{{deck.slideCount}}` and `{{slide.section}}` vary per slide; the others come from the deck's own fields.
+ */
+export const ZONE_VALUES = Object.freeze(
+  [
+    { name: "slide.number", label: "Slide number" },
+    { name: "deck.slideCount", label: "Slide count" },
+    { name: "slide.section", label: "Section" },
+    { name: "organization.name", label: "Organization" },
+    { name: "speaker.name", label: "Speaker" },
+    { name: "deck.name", label: "Deck name" },
+  ].map((entry) => Object.freeze({ ...entry, token: `{{${entry.name}}}` })),
+);
 /** Date tokens a `dateFormat` understands (English names, independent of the host locale). */
 export const DATE_FORMAT_TOKENS = Object.freeze(["yyyy", "yy", "MMMM", "MMM", "MM", "M", "dd", "d", "EEEE", "EEE"]);
 const ISO_DATE = /^[0-9]{4}-[0-9]{2}-[0-9]{2}$/;
@@ -36,7 +59,6 @@ function checkZoneField(key, value) {
   if (ZONE_FLAGS.includes(key) && typeof value !== "boolean") throw bad(`${key} is true or false.`);
   if (key === "text" && typeof value !== "string") throw bad("Text is a string.");
   if (key === "image" && typeof value !== "string" && !isObject(value)) throw bad("An image is a source, an asset reference or an asset object.");
-  if (key === "slideNumberFormat" && (typeof value !== "string" || !value.includes("{current}"))) throw bad("The slide number format must contain {current}, for example Page {current} of {total}.");
   if (key === "date" && typeof value !== "boolean" && typeof value !== "string") throw bad("A date is true (the current date) or a fixed date.");
   if (key === "dateFormat" && (typeof value !== "string" || !value.trim())) throw bad(`A date format uses tokens such as ${DATE_FORMAT_TOKENS.join(", ")}.`);
 }
@@ -90,20 +112,23 @@ function primaryOrganization(presentation) {
   return list.find((entry) => entry?.role === "primary") ?? list[0];
 }
 
-function firstSpeaker(presentation) {
-  const list = Array.isArray(presentation.speaker) ? presentation.speaker : presentation.speaker ? [presentation.speaker] : [];
-  return list[0];
-}
-
 /** Whether a logo resolves for the slide: slide design, then deck design, then the primary organization. */
 export function hasResolvableLogo(presentation, slideIndex) {
   return Boolean(presentation.slides?.[slideIndex]?.design?.logo ?? presentation.design?.logo ?? primaryOrganization(presentation)?.logo);
 }
 
+/** The variable names a zone's `text` uses (`{{name}}` and `{{name|format}}`); a token with a backslash before it is literal text. */
+function zoneTextVariables(text) {
+  const names = [];
+  for (const match of text.matchAll(/(\\?)\{\{\s*([A-Za-z0-9_.-]+)\s*(?:\|[^{}]*)?\}\}/g)) if (!match[1]) names.push(match[2]);
+  return names;
+}
+
 /**
- * Plain-language warnings for settings that need a logo the document does not have: a header or
- * footer zone with `logo: true`, or picture bullets. The renderers fall back to a glyph or report
- * unresolved content; the editor surfaces it before export.
+ * Plain-language warnings for settings that need content the document does not have: a logo (a header or footer
+ * zone with `logo: true`, picture bullets), the organization's social profiles, or a value a zone's `text` asks for
+ * with a variable (`{{organization.name}}` without an organization, `{{slide.section}}` on a slide without a section).
+ * The renderers fall back to a glyph or report unresolved content; the editor surfaces it before export.
  */
 export function designWarnings(presentation, slideIndex = 0) {
   const slide = presentation.slides?.[slideIndex];
@@ -115,15 +140,25 @@ export function designWarnings(presentation, slideIndex = 0) {
       if (!hasLogo && isObject(design[which]) && design[which][zone]?.logo === true)
         warnings.push({ code: "unresolved-logo", path: `design.${which}.${zone}.logo`, message: `The ${which} ${zone} zone shows the logo, but no logo is set. Add a logo or an organization logo.` });
   const organization = primaryOrganization(presentation);
+  let builtins;
   for (const which of ["header", "footer"])
     for (const zone of HEADER_FOOTER_ZONES) {
       const item = isObject(design[which]) ? design[which][zone] : undefined;
-      if (item?.organization === true && !organization)
-        warnings.push({ code: "unresolved-content", path: `design.${which}.${zone}.organization`, message: `The ${which} ${zone} zone shows the organization, but the presentation has none.` });
-      if (item?.speaker === true && !firstSpeaker(presentation)?.name)
-        warnings.push({ code: "unresolved-content", path: `design.${which}.${zone}.speaker`, message: `The ${which} ${zone} zone shows the speaker, but the presentation has no named speaker.` });
       if (item?.socials === true && !organization?.socials)
         warnings.push({ code: "unresolved-content", path: `design.${which}.${zone}.socials`, message: `The ${which} ${zone} zone shows social profiles, but the organization has none.` });
+      // FA-31: a value the zone's text asks for and the document cannot give (the core validator reports the same as variable-builtin-missing).
+      const path = `design.${which}.${zone}.text`;
+      for (const name of new Set(typeof item?.text === "string" ? zoneTextVariables(item.text) : [])) {
+        if (name === "slide.section") {
+          if (!(typeof slide?.section === "string" && slide.section !== ""))
+            warnings.push({ code: "unresolved-content", path, message: `The ${which} ${zone} zone shows {{slide.section}}, but this slide has no section.` });
+          continue;
+        }
+        builtins ??= listBuiltinVariables(presentation);
+        const entry = builtins.find((candidate) => candidate.name === name);
+        if (entry?.scope === "deck" && !entry.available)
+          warnings.push({ code: "unresolved-content", path, message: `The ${which} ${zone} zone shows {{${name}}}, but the presentation has no value for it.` });
+      }
     }
   if (!hasLogo && design.listBullet === "image")
     warnings.push({ code: "unresolved-logo", path: "design.listBullet", message: "Picture bullets use the logo, but no logo is set, so lists draw the character bullet. Add a logo or an organization logo." });
@@ -343,8 +378,9 @@ export function readLogoVariants(presentation, options = {}) {
 
 /**
  * Compute the patch that edits one header or footer zone. `fields` merges into the zone (logo, text,
- * image, slideNumber, slideNumberFormat, date, dateFormat, organization, speaker, socials, section); `null`,
- * `false` for a flag, or an empty string removes a field. A zone left empty is removed, then an empty
+ * image, date, dateFormat, socials); `null`, `false` for a flag, or an empty string removes a field.
+ * Generated values (slide number, slide count, section, organization, speaker, deck name) are `{{ }}`
+ * variables in `text` (`ZONE_VALUES`, `insertZoneValue`). A zone left empty is removed, then an empty
  * header or footer, so a slide never carries `{}`. A slide's own header or footer replaces the deck's
  * whole one, so the first edit on a slide that has none of its own starts from a copy of the deck's
  * (the other zones stay); a slide emptied that way hides the furniture (`false`) instead of
@@ -356,7 +392,7 @@ export function prepareHeaderFooterZone(presentation, which, zone, fields, optio
   if (!HEADER_FOOTER_ZONES.includes(zone)) throw fail("invalid-design-value", `Zone is one of ${HEADER_FOOTER_ZONES.join(", ")}.`, { zone });
   if (!isObject(fields)) throw fail("invalid-design-value", "Pass the zone fields to change.", { fields });
   const unknown = Object.keys(fields).filter((key) => !ZONE_FIELDS.includes(key));
-  if (unknown.length) throw fail("invalid-design-value", `Unknown header/footer field: ${unknown[0]}.`, { fields });
+  if (unknown.length) throw fail("invalid-design-value", `Unknown header/footer field: ${unknown[0]}.${Object.hasOwn(REMOVED_ZONE_FIELDS, unknown[0]) ? ` ${REMOVED_ZONE_FIELDS[unknown[0]]}` : ""}`, { fields });
   const { scope, base, slideIndex } = scopeOf(presentation, "logo", options);
   const own = ownDesign(presentation, base)[which];
   const inherited = base.length ? presentation.design?.[which] : undefined;
@@ -387,6 +423,29 @@ export function setHeaderFooterZone(editor, which, zone, fields, options = {}) {
   const { meta, ...rest } = options;
   return apply(editor, prepareHeaderFooterZone(editor.presentation, which, zone, fields, rest), meta);
 }
+/**
+ * Compute the patch that inserts a value's token (`ZONE_VALUES`, for example `slide.number` for `{{slide.number}}`) into a zone's
+ * `text` at UTF-16 offsets `start` and `end` (a selection is replaced; default: the end of the text). The text is the one the scope
+ * shows (the slide's own zone, else the deck's), or `options.text` when a panel holds edits it has not committed yet.
+ */
+export function prepareZoneValue(presentation, which, zone, name, options = {}) {
+  const value = ZONE_VALUES.find((entry) => entry.name === name);
+  if (!value) throw fail("invalid-design-value", `Insert one of ${ZONE_VALUES.map((entry) => entry.name).join(", ")}.`, { value: name });
+  const { start, end, text: typed, ...rest } = options;
+  if (typed !== undefined && typeof typed !== "string") throw fail("invalid-design-value", "Text is a string.", { text: typed });
+  const current = typed ?? readHeaderFooterZone(presentation, which, zone, rest).text;
+  const text = typeof current === "string" ? current : "";
+  const from = start === undefined ? text.length : start;
+  const to = end === undefined ? from : end;
+  if (!Number.isInteger(from) || !Number.isInteger(to) || from < 0 || to < from || to > text.length) throw fail("invalid-selection", "The selection is outside the text.", { start: from, end: to });
+  return prepareHeaderFooterZone(presentation, which, zone, { text: `${text.slice(0, from)}${value.token}${text.slice(to)}` }, rest);
+}
+/** Insert a value's token into one zone's `text` as a single undoable transaction. */
+export function insertZoneValue(editor, which, zone, name, options = {}) {
+  checkEditor(editor);
+  const { meta, ...rest } = options;
+  return apply(editor, prepareZoneValue(editor.presentation, which, zone, name, rest), meta);
+}
 /**
  * One header or footer zone's fields as they apply at a scope: the slide's own header (or footer) when it
  * has one, else the deck's (`{}` when absent or suppressed). `headerFooterState` says which.

package/dist/export.d.ts

@@ -42,6 +42,11 @@ export interface ExportOptions {
   includeHidden?: boolean;
   /** "vector" (default): selectable text and vector shapes; "raster": an image per slide. */
   pdfMode?: "vector" | "raster";
+  /**
+   * Raster PDF only: the pdf-lib module (`import * as pdfLib from "pdf-lib"`). The renderer's `export-browser` entry imports no PDF library (opf-render 0.16), so the host passes it;
+   * without it a `pdfMode: "raster"` PDF rejects with the renderer's `converter-missing`. Vector PDF, PNG and SVG need no option.
+   */
+  pdfLib?: { PDFDocument: { create(options?: { updateMetadata?: boolean }): Promise<any> } };
   /** PNG pixel density (and the raster PDF's), 1 to 4; default 2. */
   scale?: number;
   /** The options the host draws its preview with (`catalogs`, `date`, ...); the fonts go in `fonts`. */
@@ -72,6 +77,6 @@ export interface ExportResult {
 }
 /**
  * Draw the deck with the renderer the preview uses and convert it. Rejects with an error whose `code` is `export-aborted`, `export-fonts-unlicensed` (the license rule left the PDF converter no face for some text), `export-no-slides`,
- * `export-format`, `export-unavailable` (PDF and PNG need the renderer's `export-browser` entry), `fonts-unavailable` or a renderer code.
+ * `export-format`, `export-unavailable` (PDF and PNG need the renderer's `export-browser` entry), `fonts-unavailable` or a renderer code (`converter-missing` for a raster PDF without `pdfLib`).
  */
 export declare function exportDeck(deck: unknown, options: ExportOptions): Promise<ExportResult>;

package/dist/export.js

@@ -124,6 +124,9 @@ async function loadConverters(options) {
  * - `format`: "pdf", "png" or "svg" (required).
  * - `slides`: "current" (with `slideIndex`), "all" (default; hidden slides only with `includeHidden`) or an array of slide numbers.
  * - `pdfMode`: "vector" (default: selectable text, vector shapes) or "raster" (each slide an image).
+ * - `pdfLib`: for `pdfMode: "raster"` only, the pdf-lib module (`import * as pdfLib from "pdf-lib"`). The renderer's `export-browser` entry imports no PDF library (RR-63, opf-render 0.16),
+ *   so a host that offers the raster PDF imports pdf-lib itself; without it a raster PDF rejects with the renderer's `converter-missing` (its `details.install` names the package).
+ *   Vector PDF, PNG and SVG need no option.
  * - `scale`: PNG pixel density, 1 to 4 (default 2); also the raster PDF's density.
  * - `renderOptions`: the render options the host draws with (`catalogs`, `date`, ...), the same as its preview.
  * - `catalogs`: the host's registered catalogs (`Catalog[]`, merged with `renderOptions.catalogs`). The deck is embedded first (core's
@@ -137,7 +140,7 @@ async function loadConverters(options) {
  *   `export-fonts-unlicensed` (the converter's error is its `cause`).
  * - `signal`, `onProgress({ stage, done, total, message })`, `onDiagnostic(diagnostic)`.
  * Resolves `{ download, files, diagnostics, slides }`. Rejects with an error whose `code` is `export-aborted`,
- * `export-fonts-unlicensed`, `export-no-slides`, `export-unavailable`, `fonts-unavailable` or a renderer code.
+ * `export-fonts-unlicensed`, `export-no-slides`, `export-unavailable`, `fonts-unavailable` or a renderer code (`converter-missing` for a raster PDF without `pdfLib`).
  */
 export async function exportDeck(input, options = {}) {
   const format = EXPORT_FORMATS[options.format];
@@ -213,6 +216,8 @@ export async function exportDeck(input, options = {}) {
         metadata,
         signal,
         fontData: pdfFontData(embeddedFonts),
+        // RR-63: the renderer's browser entry imports no pdf-lib; raster mode takes the module the host imported.
+        ...(options.pdfMode === "raster" && options.pdfLib ? { pdfLib: options.pdfLib } : {}),
         ...(options.fallbackFamily ? { defaultFontFamily: options.fallbackFamily } : {}),
         onDiagnostic: (diagnostic) => { const described = describeDiagnostic(diagnostic, "pdf"); if (keep(described)) note(described); },
         onProgress: ({ page, pages }) => progress("convert", page, pages, `Page ${page} of ${pages}`),

package/dist/find-replace.js

@@ -21,6 +21,11 @@ const REGION_KEY = /^(?:top|middle|bottom|left|center|right)(?:[+:]|$)/;
 const WORD_BEFORE = "(?<![\\p{L}\\p{N}_])";
 const WORD_AFTER = "(?![\\p{L}\\p{N}_])";
 
+// A variable token (`{{customer}}`, `{{slide.number}}`, `{{ deck.slideCount }}`, `{{revenue|0.0}}`). It is an instruction, not text: a match inside it is
+// never offered, because replacing part of a name would either break the variable or silently change which value it shows (FA-31). An
+// escaped `\{{` is literal text and is searched like the rest.
+const VARIABLE_TOKEN = /(?<!\\)\{\{\s*[A-Za-z][A-Za-z0-9_.-]*\s*(?:\|[^{}]*)?\}\}/g;
+
 const isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
 const runText = (run) => (typeof run === "string" ? run : isObject(run) && typeof run.text === "string" ? run.text : "");
 const isRuns = (value) => Array.isArray(value) && value.length > 0 && value.every((run) => typeof run === "string" || (isObject(run) && typeof run.text === "string"));
@@ -107,6 +112,7 @@ function payloadFields(fields, state, base, payload, prefix = "") {
     }));
   }
   if (isObject(payload.chart)) field(fields, state, at("chart", "alt"), payload.chart.alt, `${prefix}Chart alt text`, "alt");
+  if (isObject(payload.table)) field(fields, state, at("table", "alt"), payload.table.alt, `${prefix}Table alt text`, "alt");
   const table = payload.table;
   if (isObject(table)) {
     if (Array.isArray(table.columns)) table.columns.forEach((cell, c) => (isObject(cell) && !("value" in cell) ? field(fields, state, at("table", "columns", String(c), "name"), cell.name, `${prefix}Table header ${c + 1}`, "table") : cellFields(fields, state, at("table", "columns", String(c)), cell, `${prefix}Table header ${c + 1}`)));
@@ -204,7 +210,8 @@ function snippet(text, start, end) {
  * Search a document. Returns `{ matches, fieldCount, slideCount, truncated, error }`. A match is `{ id, pointer, path,
  * slideIndex, label, runs, start, end, text, groups, named, context: { before, match, after } }` where `start` and `end`
  * are offsets into the field's text. Options: those of `compileSearch`, plus `notes` and `slideIndex` of
- * `collectSearchFields`. Matches that are empty (a regular expression that matches nothing) are skipped.
+ * `collectSearchFields`. Matches that are empty (a regular expression that matches nothing) are skipped, and so is a match that
+ * touches a variable token (`{{slide.number}}`): the token is not text, and replacing part of it would break or change the variable.
  */
 export function findMatches(presentation, query, options = {}) {
   const compiled = compileSearch(query, options);
@@ -216,11 +223,13 @@ export function findMatches(presentation, query, options = {}) {
     compiled.regex.lastIndex = 0;
     let found;
     let hit = false;
+    const tokens = item.text.includes("{{") ? [...item.text.matchAll(VARIABLE_TOKEN)].map((token) => [token.index, token.index + token[0].length]) : [];
     while ((found = compiled.regex.exec(item.text))) {
       if (found[0] === "") {
         compiled.regex.lastIndex += 1;
         continue;
       }
+      if (tokens.some(([from, to]) => found.index < to && found.index + found[0].length > from)) continue;
       if (result.matches.length >= MAX_MATCHES) {
         result.truncated = true;
         break outer;

package/dist/font-gate.js

@@ -13,17 +13,6 @@ export const FONTS_UNAVAILABLE = "fonts-unavailable";
 
 const GATE = Symbol("opf-editor.fontGate");
 
-/**
- * The fonts a preview draws with: the handle's text measurement and nothing else. A full handle also lists `embeddedFonts`, which
- * the renderer writes into every SVG it returns (an export needs that, so the SVG carries its faces); a preview inside a page
- * that already loaded the faces would repeat megabytes of base64 in every canvas, thumbnail and panel preview. The measurement
- * is read from the handle at each use, so faces it loads later still measure.
- */
-export function previewFonts(fonts) {
-  if (!fonts || typeof fonts !== "object") return undefined;
-  return { get textMeasurement() { return fonts.textMeasurement; } };
-}
-
 /**
  * The gate over a fonts handle: the two calls the canvas and the export need, with the editor's error contract.
  *

package/dist/index.d.ts

@@ -72,6 +72,7 @@ export interface EditorHistory { undo: EditorHistoryEntry[]; redo: EditorHistory
 
 export interface EditorSession {
   paginateSlide(slideIndex: number, options?: PaginationOptions & EditorDiagnosticOptions, meta?: Record<string, unknown>): { change: EditorChange | null; pagination: PaginationResult };
+  /** Composes the slide with `{{slide.number}}`, `{{slide.section}}` and `{{deck.slideCount}}` substituted for `options.slideNumber` and `options.slideCount` (default: its place in the open deck and the deck's slide count); the document keeps the tokens. */
   composeSlide(slideIndex: number, options?: ComposeSlideOptions & EditorDiagnosticOptions): SlideComposition;
   setComposition(slideIndex: number, composition: Composition, meta?: Record<string, unknown>): EditorChange;
   readonly presentation: unknown;
@@ -162,6 +163,7 @@ export interface CatalogSelectOptions extends CatalogOptionsInput {
   path: string;
   catalogKind: string;
   label?: string;
+  onError?: (error: Error) => void;
   document?: { createElement(tagName: string): any };
 }
 

package/dist/index.js

@@ -1,3 +1,4 @@
+import { commitCatalogControl } from "./catalog-control.js";
 import { paginateSlide } from "@openpresentation/opf/pagination";
 import { OPFPatchError, applyPatch as applyCorePatch, applyPatchWithInverse, formatPointer, invertPatch, jsonEqual, parsePointer, readPointer } from "@openpresentation/opf/patch";
 import { collectReservedPresentationIds } from "./presentation-ids.js";
@@ -31,12 +32,14 @@ export {
 // theme, engine default), with the session's registered catalogs, so the editor measures and composes what the renderer draws
 // and the exporter writes. `options.fonts` is the renderer's fonts handle (its `textMeasurement` measures); `options.catalogs`
 // adds catalogs for this call; `options.onDiagnostic` hears each diagnostic (`unresolved-reference`);
-// any other option overrides the resolved one (`layout`, ...).
+// any other option overrides the resolved one (`layout`, ...). FA-31: `slide` is the slide to compose and draw, with `{{slide.number}}`,
+// `{{slide.section}}` and `{{deck.slideCount}}` substituted for `slideNumber` and `slideCount` (default: its place in the open deck and the
+// deck's length), the same numbers the options carry. Pagination takes the source slide instead and substitutes while it measures.
 function slideContext(presentation, slideIndex, catalogs, { fonts, catalogs: _extra, onDiagnostic, ...overrides } = {}) {
   if (!Number.isInteger(slideIndex) || !presentation.slides?.[slideIndex]) throw new OPFEditorError("slide-index-out-of-range", "Slide index is out of range.");
-  const { options, diagnostics } = resolveSlideContext(presentation, slideIndex, { fonts, catalogs });
+  const { slide, options, diagnostics } = resolveSlideContext(presentation, slideIndex, { fonts, catalogs, slideNumber: overrides.slideNumber, slideCount: overrides.slideCount });
   for (const diagnostic of diagnostics) onDiagnostic?.(diagnostic);
-  return { ...options, ...overrides };
+  return { slide, options: { ...options, ...overrides } };
 }
 
 export const packageName = "@openpresentation/opf-editor";
@@ -275,12 +278,13 @@ export function createEditorSession(input, options = {}) {
       });
     },
     composeSlide(slideIndex, options = {}) {
-      return composeSlide(presentation.slides?.[slideIndex], slideContext(presentation, slideIndex, mergeCatalogs(catalogs, options.catalogs), options));
+      const { slide, options: resolved } = slideContext(presentation, slideIndex, mergeCatalogs(catalogs, options.catalogs), options);
+      return composeSlide(slide, resolved);
     },
     paginateSlide(slideIndex, options = {}, meta = {}) {
       const list = mergeCatalogs(catalogs, options.catalogs);
       // Core pagination reads the measurement from `fonts`, so the resolved context hands it over that way.
-      const { textMeasurement, ...resolved } = slideContext(presentation, slideIndex, list, options);
+      const { textMeasurement, ...resolved } = slideContext(presentation, slideIndex, list, options).options;
       const pagination = paginateSlide(presentation.slides[slideIndex], {
         ...resolved,
         catalogs: list,
@@ -523,8 +527,19 @@ export function setCatalogId(editor, path, catalogKind, id, meta = {}) {
   const current = editor.get(path);
   const value = catalogReferenceValue(current, catalogId);
   const { catalogs: _catalogs, presentation: _presentation, ...commitMeta } = meta;
-  return editor.set(path, value, {
+  // Only documented design references may initialize their optional design parent.
+  // Ordinary set/applyPatch retain RFC 6902's existing-parent requirement.
+  const segments = splitOpfPath(path);
+  const designField = { themes: "theme", colorSchemes: "colorScheme", fontSchemes: "fontScheme" }[catalogKind];
+  const deckDesign = segments.length === 2 && segments[0] === "design";
+  const slideDesign = segments.length === 4 && segments[0] === "slides" && /^(0|[1-9][0-9]*)$/.test(segments[1]) && segments[2] === "design" && editor.get(segments.slice(0, 2));
+  const parent = segments.slice(0, -1);
+  const patches = designField === segments.at(-1) && (deckDesign || slideDesign) && !hasValueAtPath(editor.presentation, parent)
+    ? [{ op: "add", path: opfPathToJsonPointer(parent), value: { [designField]: value } }]
+    : createValuePatch(editor.presentation, path, value);
+  return editor.applyPatch(patches, {
     ...commitMeta,
+    rejectInvalid: true,
     catalogKind,
     catalogId,
     source: commitMeta.source ?? "catalog-control"
@@ -589,13 +604,13 @@ export function createCatalogSelect(editor, options) {
     const current = editor.get(path);
     select.value = typeof current === "object" && current ? current.id : current ?? "";
   };
-  const onChange = () => {
-    setCatalogId(editor, path, catalogKind, select.value, {
+  const onChange = () => commitCatalogControl(select, options?.onError, updateValue, () => {
+    return setCatalogId(editor, path, catalogKind, select.value, {
       catalogs: options?.catalogs,
       presentation: options?.presentation,
       source: "catalog-select"
     });
-  };
+  });
   const unsubscribe = editor.subscribe(updateValue);
 
   select.addEventListener?.("change", onChange);

package/dist/json-options.js

@@ -2,7 +2,7 @@ import { checkFormat, firstErrorMessage } from "./checks.js";
 import { listCatalogRecords } from "./catalogs.js";
 import { schemaAtPath, schemaVariants } from "./schema.js";
 import { applyEdits, findNodeAtLocation, findNodeAtOffset, getNodePath, modify, parseTree } from "jsonc-parser";
-import { populateLayoutPlaceholders } from "./layout-placeholders.js";
+import { layoutSlotSummary, layoutSlotTypes, populateLayoutPlaceholders } from "./layout-placeholders.js";
 // The catalog kind a field references (OPF 0.15: every content kind is `id` or `name:id`), read from where the field sits.
 const ROOT_REFERENCES = { narrative: "narratives", audience: "audiences", purpose: "purposes", tone: "tones" };
 const DESIGN_REFERENCES = { theme: "themes", colorScheme: "colorSchemes", fontScheme: "fontSchemes" };
@@ -21,10 +21,9 @@ function catalogAtPath(path) {
 }
 // Compare declared placeholders, including multiplicity. This describes a layout
 // contract, not a claim that arbitrary slide content will render without overflow.
+// FA-26: a record's placeholder groups compare by their leaf regions, the slots its content fills.
 function layoutTypes(record) {
-    if (!Array.isArray(record?.placeholders))
-        return undefined;
-    return record.placeholders.map(p => p.type).sort();
+    return layoutSlotTypes(record)?.sort();
 }
 function placeholderSummary(types) {
     if (!types)
@@ -57,8 +56,10 @@ function describeOptions(choices, records, current, catalog) {
         if (catalog !== "layouts")
             continue;
         const types = layoutTypes(option.value === current ? currentRecord : records.get(String(option.value)));
-        option.placeholderTypes = records.get(String(option.value))?.placeholders?.map(placeholder => placeholder.type);
-        option.placeholders = placeholderSummary(types);
+        const record = records.get(String(option.value));
+        option.placeholderTypes = layoutSlotTypes(record);
+        // A record with placeholder groups also shows how its slots nest.
+        option.placeholders = placeholderSummary(types) + (record?.placeholders?.some?.(entry => entry?.type === "group") ? ` · ${layoutSlotSummary(record)}` : "");
         const same = types && currentTypes && signature(types) === signature(currentTypes);
         const equivalent = types && currentTypes && signature(compatible(types)) === signature(compatible(currentTypes));
         const sameKinds = types && currentTypes && signature([...new Set(compatible(types))]) === signature([...new Set(compatible(currentTypes))]);

package/dist/layout-handles.js

@@ -60,6 +60,19 @@ export function createLayoutHandles(root, options) {
     lastGeometry=geometry;
     layer.replaceChildren();
     if(!enabled||options.isTextEditing())return;
+    // FA-26: the slots of a layout record with placeholder groups, drawn under the handles while arranging: each group and
+    // region as a dashed outline at its cell, deeper groups inset, an empty region labelled with its kind. They are the
+    // record's, not the document's, so they are not editable here; the content in a slot keeps its own selection.
+    for(const slot of geometry.slots??[]){
+      const node=doc.createElement('div');
+      node.dataset.layoutSlot=slot.path;node.dataset.layoutSlotType=slot.type;node.setAttribute('aria-hidden','true');
+      const group=slot.type==='group',empty=!group&&!slot.content;
+      node.title=group?`Layout group (${slot.path})`:`${empty?'Empty ':''}${slot.type} slot (${slot.path})`;
+      const inset=group?Math.min(4,slot.depth*2):0;
+      node.style.cssText=`position:absolute;pointer-events:none;box-sizing:border-box;left:calc(${slot.box.x/geometry.width*100}% + ${inset}px);top:calc(${slot.box.y/geometry.height*100}% + ${inset}px);width:calc(${slot.box.width/geometry.width*100}% - ${2*inset}px);height:calc(${slot.box.height/geometry.height*100}% - ${2*inset}px);border:1px dashed ${group?'#8170d5':'#8a78d7aa'};border-radius:4px;${empty?'background:#8a78d714;':''}`;
+      if(empty){const label=doc.createElement('span');label.textContent=`Empty ${slot.type} slot`;label.style.cssText='position:absolute;left:6px;top:4px;font:11px system-ui;color:#675394';node.append(label);}
+      layer.append(node);
+    }
     for(const flow of geometry.flows??[]){
       const {axis,size,tracks}=trackData(flow);
       if(tracks.length<2||tracks.length>12||flow.itemCount!==flow.slotCount)continue;

package/dist/layout-placeholders.js

@@ -1,5 +1,20 @@
+import {layoutLeaves,layoutStructure} from '@openpresentation/opf/composition';
 import {listBlockContainers,prepareBlockInsert} from './blocks.js';
 
+/**
+ * The slot kinds a layout record declares, in reading order: its headings and the leaf regions of its placeholder groups
+ * (FA-26), the kinds a slide's flat content fills. Undefined when the record states no placeholders.
+ */
+export function layoutSlotTypes(record){
+  if(!Array.isArray(record?.placeholders))return undefined;
+  try{return layoutLeaves(record).map(leaf=>leaf.type);}catch{return record.placeholders.filter(entry=>entry?.type!=='group').map(entry=>entry?.type);}
+}
+/** A one-line description of a record's slots, nested groups in parentheses: `title, column (text, text), chart`. */
+export function layoutSlotSummary(record){
+  if(!Array.isArray(record?.placeholders))return '';
+  try{return layoutStructure(record);}catch{return layoutSlotTypes(record).join(', ');}
+}
+
 const payloadFields=['text','items','bullets','image','video','chart','table','code','metric','quote','timeline'];
 const headingFields=new Set(['title','subtitle','tag']);
 const fields={text:'text',list:'items',image:'image',video:'video',chart:'chart',table:'table',code:'code',metric:'metric',quote:'quote',timeline:'timeline'};

package/dist/react.d.ts

@@ -14,6 +14,7 @@ export interface OPFCatalogSelectProps {
   path: string;
   catalogKind: string;
   label?: string;
+  onError?: (error: Error) => void;
   catalogOptions?: CatalogOption[];
   selectProps?: Record<string, unknown>;
   [key: string]: unknown;

package/dist/react.js

@@ -1,3 +1,4 @@
+import { commitCatalogControl } from "./catalog-control.js";
 import {
   getCatalogOptions,
   getValueAtPath,
@@ -56,6 +57,7 @@ export function createOPFReactComponents(React) {
     catalogKind,
     label,
     catalogOptions,
+    onError,
     selectProps = {},
     ...props
   }) {
@@ -78,7 +80,9 @@ export function createOPFReactComponents(React) {
           selectProps.onChange?.(event);
           props.onChange?.(event);
           if (!event.defaultPrevented) {
-            setCatalogId(editor, path, catalogKind, event.currentTarget.value, { source: "react-catalog-select" });
+            const node = event.currentTarget;
+            commitCatalogControl(node, onError, () => { node.value = currentId ?? ""; }, () =>
+              setCatalogId(editor, path, catalogKind, node.value, { source: "react-catalog-select" }));
           }
         }
       },

package/dist/slide-manager.js

@@ -7,6 +7,7 @@ import {
   addSection, addSlide, duplicateSlides, hasSections, listSections, moveSection, moveSlides, moveSlidesBy, removeSection, removeSlides, renameSection, setHidden, setSection, slideTitle,
 } from "./slides.js";
 import { listSwitchOptions } from "./switches.js";
+import { layoutSlotSummary } from "./layout-placeholders.js";
 
 let instances = 0;
 const SVG_NS = "http://www.w3.org/2000/svg";
@@ -503,7 +504,8 @@ export function createSlideManager(container, options) {
     };
     const describe = () => {
       const choice = choices.find((entry) => entry.id === select.value);
-      const slots = Array.isArray(choice?.record?.placeholders) ? choice.record.placeholders.map((slot) => slot.type).join(", ") : "";
+      // FA-26: nested placeholder groups show with their mode, for example `title, column (text, text), chart`.
+      const slots = layoutSlotSummary(choice?.record);
       detail.textContent = choice ? `${choice.record?.description ?? ""}${slots ? ` Slots: ${slots}.` : choice.record?.placeholders ? " An empty slide." : ""}`.trim() : "No layout matches.";
     };
     const form = el("form", { method: "dialog" },

package/dist/svelte.d.ts

@@ -11,6 +11,7 @@ export interface OPFCatalogSelectActionParams extends CatalogOptionsInput {
   path: string;
   catalogKind: string;
   label?: string;
+  onError?: (error: Error) => void;
 }
 
 export interface OPFTraceActionParams extends SvgTraceBindingOptions {

package/dist/svelte.js

@@ -1,3 +1,4 @@
+import { commitCatalogControl } from "./catalog-control.js";
 import {
   createSvgTraceBinding,
   getCatalogOptions,
@@ -59,11 +60,11 @@ export function opfCatalogSelect(node, params) {
       const value = editor.get(path);
       node.value = value && typeof value === "object" ? value.id : value ?? "";
     };
-    const onChange = () => setCatalogId(editor, path, catalogKind, node.value, {
+    const onChange = () => commitCatalogControl(node, nextParams.onError, sync, () => setCatalogId(editor, path, catalogKind, node.value, {
       catalogs: nextParams.catalogs,
       presentation: nextParams.presentation,
       source: "svelte-catalog-select"
-    });
+    }));
     const unsubscribe = editor.subscribe(sync);
 
     node.addEventListener?.("change", onChange);

package/dist/switches.js

@@ -13,7 +13,7 @@ import { chartOptionTarget } from "@openpresentation/opf/composition";
 import { createValuePatch, applyJsonPatch, getValueAtPath, opfPathToJsonPointer, splitOpfPath } from "./index.js";
 import { createContentBlock, prepareBlockReplace } from "./blocks.js";
 import { checkedDocument, designPatches, fail, same } from "./edit-helpers.js";
-import { populateLayoutPlaceholders } from "./layout-placeholders.js";
+import { layoutSlotTypes, populateLayoutPlaceholders } from "./layout-placeholders.js";
 import { blockConversionTargets, prepareBlockConversion } from "./block-convert.js";
 import { checkFormat } from "./checks.js";
 import { listCatalogRecords, mergeCatalogs } from "./catalogs.js";
@@ -273,7 +273,8 @@ export function prepareDimensionSwitch(presentation, dimension, value, options =
     if (withRecord.slides[slideIndex].layout !== choice.reference) {
       const layoutOps = createValuePatch(withRecord, ["slides", String(slideIndex), "layout"], choice.reference);
       const swapped = applyJsonPatch(withRecord, layoutOps);
-      const types = Array.isArray(record.placeholders) ? record.placeholders.map((placeholder) => placeholder.type) : undefined;
+      // FA-26: a record's placeholder groups contribute their leaf regions, in reading order.
+      const types = layoutSlotTypes(record);
       // Add the blank payloads the layout declares, as the JSON editor's layout choice does.
       const populated = types ? populateLayoutPlaceholders(swapped, slideIndex, types) : swapped;
       patches = same(populated.slides[slideIndex], swapped.slides[slideIndex])

package/dist/table-options.d.ts

@@ -37,7 +37,7 @@ export interface TableCellState extends TableCellAddress {
   rows: number;
 }
 export interface PreparedTableChange {
-  action: "merge" | "split" | "style" | "table-style";
+  action: "merge" | "split" | "style" | "table-style" | "table-alt";
   tablePath: string;
   presentation: unknown;
   patches: JsonPatchOperation[];
@@ -72,6 +72,11 @@ export declare function mergeTableCells(editor: EditorSession, tablePath: string
 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;
 export declare function setTableStyle(editor: EditorSession, tablePath: string, preset: keyof typeof TABLE_STYLE_PRESETS | Partial<TableStyle>, meta?: Record<string, unknown>): TableChange;
+/** FA-27: the table's text alternative as form state: `alt` (empty when absent or decorative) and `decorative` (the empty alt). */
+export declare function readTableAlt(table: unknown): { alt: string; decorative: boolean };
+/** FA-27: change the table's text alternative. `alt` is trimmed and an empty string or null removes it; `decorative: true` writes the empty alt and wins over `alt`; `decorative: false` removes an empty alt. Works on inline and dataset-backed tables. */
+export declare function prepareTableAlt(presentation: unknown, tablePath: string, change: { alt?: string | null; decorative?: boolean }): PreparedTableChange;
+export declare function setTableAlt(editor: EditorSession, tablePath: string, change: { alt?: string | null; decorative?: boolean }, meta?: Record<string, unknown>): TableChange;
 /** {@link readTableStyle} for a table object. */
 export declare function readTableStyleOfTable(table: unknown): (TableStyle | { header: "custom"; banding: "custom"; borders: "custom" }) & { preset: keyof typeof TABLE_STYLE_PRESETS | "custom" };
 /** Apply a table style to a table object in place (the structure operations use it to keep banding, header fill and borders correct). */