@openpresentation/opf-editor 0.7.1 → 0.9.0

package/dist/galleries.js

@@ -117,6 +117,53 @@ export async function loadOpfGallery(input, options = {}) {
     })),
   };
 }
+const FONT_SCHEME_ENUMS = {
+  type: ["sans-serif", "serif", "monospace"],
+  app: ["PowerPoint", "Google Slides"],
+  languageFamily: ["latin", "ea", "cs"],
+};
+// A Font role object ({ family, weight?, style?, letterSpacing? }), or undefined.
+function fontRole(value) {
+  if (typeof value === "string") return value ? { family: value } : undefined;
+  if (!value || typeof value !== "object" || typeof value.family !== "string")
+    return undefined;
+  const role = { family: value.family };
+  if (typeof value.weight === "number" && Number.isFinite(value.weight))
+    role.weight = value.weight;
+  if (value.style === "normal" || value.style === "italic")
+    role.style = value.style;
+  if (
+    typeof value.letterSpacing === "number" &&
+    Number.isFinite(value.letterSpacing)
+  )
+    role.letterSpacing = value.letterSpacing;
+  return role;
+}
+// Keep every font-scheme role that the catalog record schema defines: the OOXML
+// pair and `code`. Gallery `heading`/`body` (string or Font object) map onto
+// major/minor only, never role objects, so a later inline design.fontScheme
+// major/minor override still wins (resolveFontFamilies checks roles before the
+// pair). `accent` is not part of the record schema and is dropped.
+function fontSchemeRecord(source, id) {
+  const record = {
+    $schema: "https://openpresentation.org/schema/opf-font-scheme/v1",
+    id,
+    name: source.name ?? id,
+    major:
+      typeof source.major === "string"
+        ? source.major
+        : fontRole(source.heading)?.family,
+    minor:
+      typeof source.minor === "string"
+        ? source.minor
+        : fontRole(source.body)?.family,
+  };
+  for (const [field, values] of Object.entries(FONT_SCHEME_ENUMS))
+    if (values.includes(source[field])) record[field] = source[field];
+  const code = fontRole(source.code);
+  if (code) record.code = code;
+  return record;
+}
 function attachDefinition(document, descriptor) {
   const source = descriptor.metadata?.source,
     category = descriptor.category ?? descriptor.metadata?.category;
@@ -161,14 +208,7 @@ function attachDefinition(document, descriptor) {
           }
         : {}),
     };
-  } else if (kind === "fontSchemes")
-    record = {
-      $schema: "https://openpresentation.org/schema/opf-font-scheme/v1",
-      id,
-      name: source.name ?? id,
-      major: source.major ?? source.heading,
-      minor: source.minor ?? source.body,
-    };
+  } else if (kind === "fontSchemes") record = fontSchemeRecord(source, id);
   else {
     record = {
       ...source,

package/dist/index.d.ts

@@ -1,5 +1,8 @@
 import type { PaginationOptions, PaginationResult } from "@openpresentation/opf/pagination";
 import type { Composition, ComposeSlideOptions, SlideComposition } from "@openpresentation/opf/composition";
+/** Reported when a font-scheme id matches no inline or bundled record; the default font scheme (`aptos`) is the base. */
+export interface FontSchemeDiagnostic { code: "unresolved-font-scheme"; path: string; message: string; id: string; fallback: string }
+export interface EditorDiagnosticOptions { onDiagnostic?: (diagnostic: FontSchemeDiagnostic) => void }
 export declare const packageName = "@openpresentation/opf-editor";
 
 export declare const releaseLane: Readonly<{
@@ -26,6 +29,7 @@ export type JsonPatchOperation =
 export interface OPFValidationSummary {
   valid: boolean;
   errors: unknown[];
+  warnings: unknown[];
   result: unknown;
 }
 
@@ -57,8 +61,8 @@ export interface EditorEvent {
 }
 
 export interface EditorSession {
-  paginateSlide(slideIndex: number, options?: PaginationOptions, meta?: Record<string, unknown>): { change: EditorChange | null; pagination: PaginationResult };
-  composeSlide(slideIndex: number, options?: ComposeSlideOptions): SlideComposition;
+  paginateSlide(slideIndex: number, options?: PaginationOptions & EditorDiagnosticOptions, meta?: Record<string, unknown>): { change: EditorChange | null; pagination: PaginationResult };
+  composeSlide(slideIndex: number, options?: ComposeSlideOptions & EditorDiagnosticOptions): SlideComposition;
   setComposition(slideIndex: number, composition: Composition, meta?: Record<string, unknown>): EditorChange;
   readonly document: unknown;
   readonly validation: OPFValidationSummary;
@@ -158,6 +162,9 @@ export declare function invertJsonPatch(document: unknown, operations: JsonPatch
 
 export declare function validateOpfDocument(document: unknown, validator?: (document: unknown) => unknown): OPFValidationSummary;
 
+/** Font families the slide resolves to (slide, deck, theme, then the shared default scheme). */
+export declare function resolveSlideFonts(document: unknown, slideIndex?: number, options?: EditorDiagnosticOptions): { heading?: string; body?: string; code?: string; [role: string]: string | undefined };
+
 export declare function createEditorSession(input: unknown, options?: CreateEditorSessionOptions): EditorSession;
 
 export declare function createSvgTraceBinding(

package/dist/index.js

@@ -1,4 +1,6 @@
 import { paginateSlide } from "@openpresentation/opf/pagination";
+import { collectReservedPresentationIds } from "./presentation-ids.js";
+import { DEFAULT_FONT_SCHEME, resolveFontSchemeReference } from "./font-defaults.js";
 import { composeSlide, resolveCanvasDimensions, resolveFontFamilies } from "@openpresentation/opf/composition";
 import {
   catalogKinds,
@@ -6,7 +8,7 @@ import {
   validatePresentation
 } from "@openpresentation/opf";
 
-function resolveCompositionOptions(document, slideIndex, options = {}) {
+function resolveCompositionOptions(document, slideIndex, { onDiagnostic, ...options } = {}) {
       const slide = document.slides?.[slideIndex];
       if (!Number.isInteger(slideIndex) || !slide) throw new OPFEditorError("slide-index-out-of-range", "Slide index is out of range.");
       const inline = document.catalogs?.layouts?.records ?? [];
@@ -16,12 +18,22 @@ function resolveCompositionOptions(document, slideIndex, options = {}) {
       const themeId = typeof themeReference === "string" ? themeReference : themeReference.id;
       const theme = document.catalogs?.themes?.records?.find(record => record.id === themeId)
         ?? bundledCatalogs.themes.find(record => record.id === themeId);
-      const reference = slide.design?.fontScheme ?? document.design?.fontScheme ?? theme?.fontScheme ?? "roboto";
-      const id = typeof reference === "string" ? reference : reference.id;
-      const fontScheme = {...(document.catalogs?.fontSchemes?.records?.find(record=>record.id===id) ?? bundledCatalogs.fontSchemes.find(record=>record.id===id)),...(typeof reference === "object" ? reference : {})};
+      const reference = slide.design?.fontScheme ?? document.design?.fontScheme ?? theme?.fontScheme ?? DEFAULT_FONT_SCHEME;
+      const fontPath = slide.design?.fontScheme !== undefined ? `slides.${slideIndex}.design.fontScheme` : document.design?.fontScheme !== undefined ? "design.fontScheme" : slide.design?.theme !== undefined ? `slides.${slideIndex}.design.theme` : "design.theme";
+      const { scheme: fontScheme, diagnostic } = resolveFontSchemeReference(reference, id => document.catalogs?.fontSchemes?.records?.find(record=>record.id===id) ?? bundledCatalogs.fontSchemes.find(record=>record.id===id), fontPath);
+      if (diagnostic) onDiagnostic?.(diagnostic);
       return { ...resolveCanvasDimensions(slide.design?.dimensions ?? document.design?.dimensions ?? theme?.dimensions), fonts:resolveFontFamilies(fontScheme), contentAlignment:slide.design?.contentAlignment??document.design?.contentAlignment, titleAlignment:slide.design?.titleAlignment??document.design?.titleAlignment, contentBox:slide.design?.contentBox??document.design?.contentBox, presentation:document, ...options, layout, slideIndex };
 }
 
+/**
+ * The font families a slide resolves to (`heading`, `body`, `code`), by the same slide, deck,
+ * theme, default order that composition, pagination and export use. Hosts read this after a
+ * font-scheme or theme switch to show the fonts the preview now uses.
+ */
+export function resolveSlideFonts(document, slideIndex = 0, options = {}) {
+  return resolveCompositionOptions(document, slideIndex, options).fonts;
+}
+
 export const packageName = "@openpresentation/opf-editor";
 
 export const releaseLane = Object.freeze({
@@ -142,6 +154,7 @@ export function validateOpfDocument(document, validator = validatePresentation)
   return {
     valid,
     errors: Array.isArray(result?.errors) ? result.errors : [],
+    warnings: Array.isArray(result?.warnings) ? result.warnings : [],
     result
   };
 }
@@ -243,7 +256,10 @@ export function createEditorSession(input, options = {}) {
     },
     paginateSlide(slideIndex, options = {}, meta = {}) {
       const resolved = resolveCompositionOptions(document, slideIndex, options);
-      const pagination = paginateSlide(document.slides[slideIndex], { ...resolved, reservedIds: document.slides.map(slide => slide.id).filter(Boolean) });
+      const pagination = paginateSlide(document.slides[slideIndex], {
+        ...resolved,
+        reservedIds: collectReservedPresentationIds(document),
+      });
       // Pagination can persist a readability policy without adding a page. Commit
       // that change too, so preview/export use the same minimum that was evaluated.
       if (pagination.slides.length === 1 && jsonEqual(pagination.slides[0], document.slides[slideIndex])) return { change: null, pagination };

package/dist/layout.d.ts

@@ -5,6 +5,6 @@ export declare function prepareTrackResize(document:unknown,flow:ComposedFlow,bo
   document:unknown;patches:JsonPatchOperation[];composition:Composition;fraction:number;
 };
 
-export {prepareBlockMove,listBlockContainers,prepareBlockInsert,prepareBlockDuplicate,prepareBlockRemove,createContentBlock} from './blocks.js';
+export {prepareBlockMove,listBlockContainers,prepareBlockInsert,prepareBlockDuplicate,prepareBlockRemove,prepareBlockReplace,createContentBlock} from './blocks.js';
 
 export type {PreparedBlockChange,ContentBlockKind} from './blocks.js';

package/dist/layout.js

@@ -31,4 +31,4 @@ export function prepareTrackResize(document, flow, boundary, fraction) {
   return {document:next,patches,composition,fraction:share};
 }
 
-export {prepareBlockMove,listBlockContainers,prepareBlockInsert,prepareBlockDuplicate,prepareBlockRemove,createContentBlock} from './blocks.js';
+export {prepareBlockMove,listBlockContainers,prepareBlockInsert,prepareBlockDuplicate,prepareBlockRemove,prepareBlockReplace,createContentBlock} from './blocks.js';

package/dist/presentation-ids.js

@@ -0,0 +1,68 @@
+/** Shared slide and content-payload id collection (matches @openpresentation/opf pagination). */
+
+const promotedRegionKeys = [
+  "left", "center", "right", "left+center", "center+right", "left+center+right",
+  "top", "middle", "bottom", "top+middle", "middle+bottom", "top+middle+bottom",
+  "top:left", "top:center", "top:right", "top:left+center", "top:center+right", "top:left+center+right",
+  "middle:left", "middle:center", "middle:right", "middle:left+center", "middle:center+right", "middle:left+center+right",
+  "bottom:left", "bottom:center", "bottom:right", "bottom:left+center", "bottom:center+right", "bottom:left+center+right",
+  "top+middle:left", "top+middle:center", "top+middle:right", "top+middle:left+center", "top+middle:center+right", "top+middle:left+center+right",
+  "middle+bottom:left", "middle+bottom:center", "middle+bottom:right", "middle+bottom:left+center", "middle+bottom:center+right", "middle+bottom:left+center+right",
+  "top+middle+bottom:left", "top+middle+bottom:center", "top+middle+bottom:right", "top+middle+bottom:left+center", "top+middle+bottom:center+right", "top+middle+bottom:left+center+right",
+];
+
+const MAX_COMPOSITION_DEPTH = 8;
+
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function visitContentPayloads(slide, slidePath, visit) {
+  const walk = (payload, path, depth, ancestors) => {
+    visit(payload, path);
+    if (!Array.isArray(payload.blocks) || depth >= MAX_COMPOSITION_DEPTH || ancestors.includes(payload)) return;
+    const nested = [...ancestors, payload];
+    payload.blocks.forEach((block, index) => {
+      if (isRecord(block)) walk(block, path ? `${path}.blocks.${index}` : `blocks.${index}`, depth + 1, nested);
+    });
+  };
+  if (Array.isArray(slide?.blocks)) {
+    slide.blocks.forEach((block, index) => {
+      if (isRecord(block)) walk(block, slidePath ? `${slidePath}.blocks.${index}` : `blocks.${index}`, 0, []);
+    });
+  }
+  for (const key of promotedRegionKeys) {
+    const region = slide?.[key];
+    if (isRecord(region)) walk(region, slidePath ? `${slidePath}.${key}` : key, 0, []);
+  }
+}
+
+export function slideIds(slide) {
+  const ids = typeof slide?.id === "string" ? [slide.id] : [];
+  if (isRecord(slide)) {
+    visitContentPayloads(slide, "", (payload) => {
+      if (typeof payload.id === "string") ids.push(payload.id);
+    });
+  }
+  return ids;
+}
+
+export function collectReservedPresentationIds(document) {
+  const ids = [];
+  for (const slide of document.slides ?? []) ids.push(...slideIds(slide));
+  return ids.filter(Boolean);
+}
+
+function remapNodeId(node, ids) {
+  if (typeof node.id !== "string") return;
+  const base = node.id;
+  let suffix = 2;
+  while (ids.has(node.id)) node.id = `${base}-${suffix++}`;
+  ids.add(node.id);
+}
+
+/** Remap slide and payload ids when inserting slides (shared document namespace). */
+export function remapSlideTreeIds(slide, ids) {
+  remapNodeId(slide, ids);
+  visitContentPayloads(slide, "", (payload) => remapNodeId(payload, ids));
+}

package/dist/rich-text-toolbar.js

@@ -1,4 +1,5 @@
 import {richTextContent, formatRichTextRange, replaceRichTextRange} from './rich-text.js';
+import { isAuthoringColorRef } from './color-authoring.js';
 
 /** Native SVG selection stays on the exact rendered glyphs; no HTML reflow. */
 export function createRichTextToolbar(root, {editor, report, beforeChange, onProperties, onTyping, validateChange, onChange}) {
@@ -80,7 +81,7 @@ export function createRichTextToolbar(root, {editor, report, beforeChange, onPro
     toolbar.append(input);return input;
   }
   const color=field('Text color');
-  color.onchange=()=>{try {if(color.value&&!/^#(?:[\da-f]{3}|[\da-f]{6}|[\da-f]{8})$/i.test(color.value))throw new Error('Use a hex text color, such as #2563eb.');apply({color:color.value||null});}catch(error){report(error);}};
+  color.onchange=()=>{try {if(color.value&&!isAuthoringColorRef(color.value))throw new Error('Use a hex color, scheme slot or role, or var:<id> (for example #2563eb, accent2, text, or var:risk).');apply({color:color.value||null});}catch(error){report(error);}};
   const size=field('Font size (pt)','number');size.min='0.1';size.step='0.5';size.style.width='80px';
   size.onchange=()=>{try{apply({fontSize:size.value?Number(size.value):null});}catch(error){report(error);}};
   const family=field('Font family');family.onchange=()=>{try{apply({fontFamily:family.value||null});}catch(error){report(error);}};

package/dist/schema-inspector.js

@@ -17,8 +17,10 @@ export function createSchemaInspector(container, {editor,path='',onDraft,onCommi
   function check(){
     const validation=validateOpfDocument(draft);
     apply.disabled=!dirty||!validation.valid;
-    status.textContent=dirty?'Draft changes · apply to save':'No pending changes';
-    showError(validation.valid?'':validation.errors.slice(0,3).map(error=>`${error.path||'/'}: ${error.message}`).join('\n'));
+    const warningNote=validation.warnings?.length?` · ${validation.warnings.length} warning${validation.warnings.length===1?'':'s'}`:'';
+    status.textContent=dirty?`Draft changes · apply to save${warningNote}`:`No pending changes${warningNote}`;
+    const issues=[...(validation.valid?[]:validation.errors.slice(0,3).map(error=>`${error.path||'/'}: ${error.message}`)),...(validation.warnings?.slice(0,2).map(warning=>`${warning.path||'/'}: ${warning.message}`)??[])];
+    showError(issues.join('\n'));
     if(validation.valid)try{onDraft?.({document:structuredClone(draft),path:selected,dirty});}catch(error){showError(`Preview: ${error.message}`);onError?.(error);}
   }
   function mutate(operations,redraw=true){draft=applyJsonPatch(draft,operations);dirty=JSON.stringify(draft)!==base;if(redraw)render();check();}

package/dist/switches.d.ts

@@ -0,0 +1,77 @@
+import type { EditorChange, EditorSession, JsonPatchOperation } from "./index.js";
+
+/** The 14 pptx.gallery dimensions. */
+export declare const SWITCH_DIMENSIONS: readonly [
+  "layouts",
+  "color-schemes",
+  "font-schemes",
+  "languages",
+  "backgrounds",
+  "narratives",
+  "charts",
+  "themes",
+  "audiences",
+  "tones",
+  "socials",
+  "headers-footers",
+  "blocks",
+  "image-treatments",
+];
+export type SwitchDimension = (typeof SWITCH_DIMENSIONS)[number];
+
+export interface DimensionSwitchOptions {
+  /** Required for layouts and charts; for design dimensions it scopes the switch to one slide (default: the deck). */
+  slideIndex?: number;
+  /** blocks: the complete block (`slides.0.blocks.1`) or one-payload slide/region to replace. charts: the block holding the chart (default: the slide's first chart). */
+  path?: string | string[];
+  /** A gallery item's catalog record, added inline in the same transaction when the id is not already defined. */
+  record?: Record<string, unknown> & { id: string };
+  /** Extra caller-loaded catalog records by kind. */
+  catalogs?: Record<string, unknown>;
+  catalogSources?: Record<string, unknown>;
+  /** themes: also write the theme's color scheme, font scheme, background and dimensions to the deck design (default true). */
+  bundle?: boolean;
+  /** Deck-scope design switches: remove slide-level values that would hide the switch. */
+  clearSlideOverrides?: boolean;
+  /** socials: which document field holds the handle (default "speaker") and, for an array, which entry (default 0). */
+  owner?: "speaker" | "organization";
+  index?: number;
+  /** blocks: media source for the image and video kinds. */
+  source?: string;
+  /** Session change metadata (switchDimension only). */
+  meta?: Record<string, unknown>;
+}
+
+export type DimensionSwitchValue =
+  | string
+  | string[]
+  | { platform: string; handle: string }
+  | { header?: unknown; footer?: unknown }
+  | { slideImage?: unknown; imageFill?: string | null }
+  | Record<string, unknown>;
+
+export interface PreparedDimensionSwitch {
+  dimension: SwitchDimension;
+  scope: "deck" | "slide" | "block";
+  slideIndex?: number;
+  document: unknown;
+  patches: JsonPatchOperation[];
+  changed: boolean;
+  /** Slides whose own design hides a deck-level switch. */
+  shadowed: number[];
+}
+
+export interface DimensionSwitchChange extends Omit<EditorChange, "document" | "patches"> {
+  document: unknown;
+  patches: JsonPatchOperation[];
+  dimension: SwitchDimension;
+  scope: "deck" | "slide" | "block";
+  slideIndex?: number;
+  changed: boolean;
+  shadowed: number[];
+}
+
+/** Compute and validate the patch for one dimension without changing any session. */
+export declare function prepareDimensionSwitch(document: unknown, dimension: SwitchDimension, value: DimensionSwitchValue, options?: DimensionSwitchOptions): PreparedDimensionSwitch;
+/** Apply one dimension switch to a session as a single undoable transaction. */
+export declare function switchDimension(editor: EditorSession, dimension: SwitchDimension, value: DimensionSwitchValue, options?: DimensionSwitchOptions): DimensionSwitchChange;