@openpresentation/opf-editor 0.11.0 → 0.11.2

package/README.md

@@ -2,7 +2,7 @@
 
 Unfinished prepared shaping work is preserved in the [September 15 roadmap](docs/roadmap-shaping-20260915.md); it is not part of the published runtime.
 
-Version 0.11.0 requires `@openpresentation/opf` ^0.12.0 (composed font sizes on PowerPoint's 0.01 pt grid, hanging wrap whitespace, promoted regions in reading order, right-to-left decks composed mirrored; install it with renderer 0.12.0 and PPTX 0.12.0 so the canvas, preview and export resolve the same core) and ships the new entry points listed in the changelog. Version 0.10.6 changes no editor source: it requires `@openpresentation/opf` ^0.11.4 (the design fields compose, cover tag and subtitle follow the title alignment, picture bullets and furniture images change geometry; install it with renderer 0.11.9 and PPTX 0.11.7 so the canvas, preview and export resolve the same core). Version 0.10.5 changes no editor source: its playground example loads its base faces through the renderer's `extraLazyFonts` (renderer 0.11.7 or later; the editor package itself runs with the optional peer ^0.11.0 as before). Version 0.10.4 changes no editor behavior: it requires `@openpresentation/opf` ^0.11.3 (the 70 legacy gallery layout ids and their geometry; install it with renderer 0.11.6 and PPTX 0.11.4 so the canvas, preview and export resolve the same core). Version 0.10.3 passes the host's render options (`catalogs`) through the font gate to the registry, so layouts and font schemes that only the host's catalogs know load their faces, and asks the script and vendored-face loaders separately; it keeps the 0.10.2 requirements and gates nothing new on renderers before 0.11.5. Version 0.10.2 adds pointer caret entry on the canvas (one click puts the caret where you click; new `textEntry` option; keyboard entry still selects all) and keeps the 0.10.1 and 0.10.0 requirements. Version 0.10.1 adds the opt-in font gate (`createFontGate`, FF-41) and keeps the 0.10.0 requirements; develop and test it against renderer 0.11.2 and PPTX 0.11.1. Version 0.10.0 requires `@openpresentation/opf` ^0.11.2, renderer ^0.11.0, and PPTX ^0.11.0 (install them together so cover centering resolves the same core everywhere; renderer 0.11.0 also activates the playground's automatic script fonts and lazy Intos fonts). Version 0.9.0 required `@openpresentation/opf` ^0.11.1, renderer ^0.10.0, and PPTX ^0.10.0. Composition and slide transfer fall back to the shared `aptos` font scheme and report unknown scheme ids through `onDiagnostic`; gallery apply keeps every font-scheme role.
+Version 0.11.2 adds the slide-size and purpose switches (additive; same requirements as 0.11.0). Version 0.11.0 requires `@openpresentation/opf` ^0.12.0 (composed font sizes on PowerPoint's 0.01 pt grid, hanging wrap whitespace, promoted regions in reading order, right-to-left decks composed mirrored; install it with renderer 0.12.0 and PPTX 0.12.0 so the canvas, preview and export resolve the same core) and ships the new entry points listed in the changelog. Version 0.10.6 changes no editor source: it requires `@openpresentation/opf` ^0.11.4 (the design fields compose, cover tag and subtitle follow the title alignment, picture bullets and furniture images change geometry; install it with renderer 0.11.9 and PPTX 0.11.7 so the canvas, preview and export resolve the same core). Version 0.10.5 changes no editor source: its playground example loads its base faces through the renderer's `extraLazyFonts` (renderer 0.11.7 or later; the editor package itself runs with the optional peer ^0.11.0 as before). Version 0.10.4 changes no editor behavior: it requires `@openpresentation/opf` ^0.11.3 (the 70 legacy gallery layout ids and their geometry; install it with renderer 0.11.6 and PPTX 0.11.4 so the canvas, preview and export resolve the same core). Version 0.10.3 passes the host's render options (`catalogs`) through the font gate to the registry, so layouts and font schemes that only the host's catalogs know load their faces, and asks the script and vendored-face loaders separately; it keeps the 0.10.2 requirements and gates nothing new on renderers before 0.11.5. Version 0.10.2 adds pointer caret entry on the canvas (one click puts the caret where you click; new `textEntry` option; keyboard entry still selects all) and keeps the 0.10.1 and 0.10.0 requirements. Version 0.10.1 adds the opt-in font gate (`createFontGate`, FF-41) and keeps the 0.10.0 requirements; develop and test it against renderer 0.11.2 and PPTX 0.11.1. Version 0.10.0 requires `@openpresentation/opf` ^0.11.2, renderer ^0.11.0, and PPTX ^0.11.0 (install them together so cover centering resolves the same core everywhere; renderer 0.11.0 also activates the playground's automatic script fonts and lazy Intos fonts). Version 0.9.0 required `@openpresentation/opf` ^0.11.1, renderer ^0.10.0, and PPTX ^0.10.0. Composition and slide transfer fall back to the shared `aptos` font scheme and report unknown scheme ids through `onDiagnostic`; gallery apply keeps every font-scheme role.
 
 Version 0.8.0 required `@openpresentation/opf` ^0.11.0, renderer ^0.9.0, and PPTX ^0.9.0. Named ColorRefs (scheme slots, roles, and `var:<id>`) paint through the published renderer and hex-resolve on export. Payload ids share the slide id namespace for pagination and transfer. Native `schemeClr`, theme write, and `p:hf` remain out of scope.
 
@@ -205,7 +205,7 @@ Invalid IDs throw before they reach the document. Existing object-form reference
 
 ## Dimension switches
 
-`@openpresentation/opf-editor/switches` turns "switch this pptx.gallery dimension to X" into one validated, undoable transaction. It covers the 14 gallery dimensions (FF-16, [font-fidelity-everywhere](https://github.com/OpenPresentation/opf/tree/main/docs/programs/font-fidelity-everywhere)):
+`@openpresentation/opf-editor/switches` turns "switch this pptx.gallery dimension to X" into one validated, undoable transaction. It covers the 14 gallery dimensions (FF-16, [font-fidelity-everywhere](https://github.com/OpenPresentation/opf/tree/main/docs/programs/font-fidelity-everywhere)) and, after them in `SWITCH_DIMENSIONS`, the two document-level choices the gallery does not page yet: `slide-sizes` and `purposes` (RR-41, [opf#293](https://github.com/OpenPresentation/opf/issues/293)):
 
 ```js
 import { switchDimension, prepareDimensionSwitch, SWITCH_DIMENSIONS } from "@openpresentation/opf-editor/switches";
@@ -229,6 +229,8 @@ const { patches, document } = prepareDimensionSwitch(editor.document, "themes",
 | `socials` | `/speaker/socials/<platform>` or the `organization` | `{platform, handle}` with `owner` and `index`; the owner must exist. |
 | `charts` | `<chart owner>/chart/type` | The slide's first chart, or the block named by `path`. The data is kept as it is and only the document schema is checked: switching does not verify that the data suits the new type (`compatibleChartTypes` lists the types the data can use; map types, for example, expect their own data). |
 | `blocks` | replaces one block, or with `convert: true` moves its content to the new kind | `path` names a complete `blocks/N` block or a slide/region with one content field. The value is a block kind or a block object. See *Content-type conversion*. |
+| `slide-sizes` | `/design/dimensions` | One of the schema's seven presets (`SLIDE_SIZE_PRESETS`: `16:9`, `4:3`, `16:10`, `letter`, `a4`, `widescreen`, `standard`). Deck only (`slideIndex` is refused: a presentation has one slide size). The preview recomposes at the new canvas and the PowerPoint export writes the matching `p:sldSz`; a custom size (inches) is replaced by the preset. `listSwitchOptions` labels each preset with its inches; `currentSwitchValue` reads `design.dimensions`, else the theme's size. Slides that carry their own `design.dimensions` are listed in `shadowed`, and `clearSlideOverrides` removes them. A theme switch still writes its own size. |
+| `purposes` | `/purpose` | A `purposes` catalog id, any free-form goal text (not checked against the catalog), or a Purpose object. `record` adds a gallery item's purpose record inline. Authoring metadata: the preview does not change. |
 
 A deck-level design switch cannot reach a slide that carries its own value for that key. The result lists those slides in `shadowed`; `clearSlideOverrides: true` removes the overrides in the same transaction. `record` adds a gallery item's catalog record inline in the same transaction when neither the document nor the bundled catalog defines its id (a gallery-only layout or font scheme). Every switch is validated: an unknown catalog id, an invalid value or an invalid resulting document throws before anything changes, and switching to the current value commits nothing. The editor session emits the usual `patch`, `undo` and `redo` events with `meta.source: "dimension-switch"` and `meta.dimension`, so the canvas and any host preview recompose from the switched document. `resolveSlideFonts(document, slideIndex)` returns the heading, body and code families the preview measures and the export names.
 
@@ -446,7 +448,7 @@ Run `npm run test:design-controls-browser` (after `npm run build:playground`) fo
 
 ### What a switch does not establish
 
-A switch changes the document; it does not change what the engines support. Language changes recompose fonts only as far as the installed core, renderer and PPTX packages implement the language and script model (FF-18, FF-19); the editor's own composition measures the Latin families. `image-treatments` previews only where the installed renderer draws `design.slideImage`. `test/switches.mjs` checks the patch, one undo step, undo/redo, and preview refresh for all 14 dimensions. `test/switches-export.mjs` exports after each switch, undo and redo and applies opf-pptx's FF-08 typeface check (`checkPptxTypefaces`) when the installed package has it; set `OPF_REQUIRE_FF08=1` to fail instead of skip when it does not. Published opf-pptx 0.9.1 does not include it.
+A switch changes the document; it does not change what the engines support. Language changes recompose fonts only as far as the installed core, renderer and PPTX packages implement the language and script model (FF-18, FF-19); the editor's own composition measures the Latin families. `image-treatments` previews only where the installed renderer draws `design.slideImage`. `test/switches.mjs` checks the patch, one undo step, undo/redo, and preview refresh for all 16 dimensions (the 14 gallery dimensions, slide sizes and purposes), and for every slide-size preset the composed canvas and the preview viewBox. `test/switches-export.mjs` exports after each switch, undo and redo, checks that every slide-size preset writes the matching `p:sldSz` and re-imports as that preset, and applies opf-pptx's FF-08 typeface check (`checkPptxTypefaces`) when the installed package has it; set `OPF_REQUIRE_FF08=1` to fail instead of skip when it does not. Published opf-pptx 0.9.1 does not include it.
 
 ## Autosave and restore (RR-22)
 

package/dist/design-controls.js

@@ -402,6 +402,17 @@ export function createDesignControls(container, options = {}) {
     catalogField("color-scheme", "Color scheme", "color-schemes");
     catalogField("font-scheme", "Font scheme", "font-schemes", { help: "Fonts the preview and export use. The preview shows an open look-alike where a font is not bundled." });
     catalogField("language", "Language", "languages", { perSlide: false, help: "Sets the language for the whole presentation, including its script fonts." });
+    // RR-41: one size for the whole presentation; the slides recompose and the export writes the matching slide size.
+    const slideSize = selectField("slide-size", "Slide size", {
+      help: "The size and shape of every slide. The preview recomposes at the new size.",
+      onChange: (value) => run(() => switchDimension(editor, "slide-sizes", value), `Slide size set to ${slideSize.select.selectedOptions[0]?.textContent ?? value}.`),
+    });
+    body.append(slideSize.wrap);
+    syncs.push(() => {
+      slideSize.setOptions(listSwitchOptions(editor.document, "slide-sizes").map((entry) => ({ value: entry.id, label: entry.label })));
+      const { value } = currentSwitchValue(editor.document, "slide-sizes");
+      slideSize.set(value && typeof value === "object" ? "Custom size" : value);
+    });
 
     const layout = selectField("layout", "Layout of this slide", {
       help: "Adds the blank placeholders the layout declares and keeps your content.",
@@ -827,6 +838,7 @@ export function createDesignControls(container, options = {}) {
     };
     single("narrative", "Narrative", "narratives", "The storyline the deck follows. Authoring metadata: the slides do not change.");
     single("tone", "Tone", "tones");
+    single("purpose", "Purpose", "purposes", "What the deck is for. Authoring metadata: the slides do not change. A goal written in the JSON source shows as custom.");
     const audience = selectField("audience", "Audience", {
       multiple: true,
       size: 6,

package/dist/persistence-ui.js

@@ -53,7 +53,7 @@ export function createPersistenceUi(options) {
       restore.addEventListener("click", async () => { restore.disabled = discard.disabled = true; const done = await actions.restore(); if (done) { hide(); say("Restored. Undo goes back to what you had."); } else { restore.disabled = discard.disabled = false; } });
       discard.addEventListener("click", async () => { await actions.discard(); hide(); say("Discarded the stored copy."); });
       earlier?.addEventListener("click", async () => { const done = await options.restoreEarlier?.(); if (done) { hide(); say("Restored the older copy. Undo goes back to what you had."); } });
-      banner.replaceChildren(el(doc, "p", { class: "restore-text", id: `${banner.id || "restore"}-text`, text: intro }), note, el(doc, "div", { class: "restore-actions" }, restore, discard, earlier));
+      banner.replaceChildren(el(doc, "p", { class: "restore-text", id: `${banner.id || "restore"}-text`, text: intro }), ...(note ? [note] : []), el(doc, "div", { class: "restore-actions" }, restore, discard, earlier));
       banner.setAttribute("role", "region");
       banner.setAttribute("aria-label", "Restore your work");
       banner.hidden = false;

package/dist/switches.d.ts

@@ -1,7 +1,11 @@
 import type { ConvertOptions } from "@openpresentation/opf/convert";
 import type { EditorChange, EditorSession, JsonPatchOperation } from "./index.js";
 
-/** The 14 pptx.gallery dimensions. */
+/** The schema's DimensionPreset values: the values of the slide-sizes switch. */
+export declare const SLIDE_SIZE_PRESETS: readonly ["16:9", "4:3", "16:10", "letter", "a4", "widescreen", "standard"];
+export type SlideSizePreset = (typeof SLIDE_SIZE_PRESETS)[number];
+
+/** Every switchable dimension: the 14 pptx.gallery dimensions, then `slide-sizes` and `purposes`. */
 export declare const SWITCH_DIMENSIONS: readonly [
   "layouts",
   "color-schemes",
@@ -17,6 +21,8 @@ export declare const SWITCH_DIMENSIONS: readonly [
   "headers-footers",
   "blocks",
   "image-treatments",
+  "slide-sizes",
+  "purposes",
 ];
 export type SwitchDimension = (typeof SWITCH_DIMENSIONS)[number];
 
@@ -32,7 +38,7 @@ export interface DimensionSwitchOptions {
   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. */
+  /** Deck-scope design switches (and slide-sizes): 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";
@@ -49,8 +55,8 @@ export interface DimensionSwitchOptions {
 
 export type DimensionSwitchValue =
   | null /* backgrounds: remove it */
-  | string
-  | string[]
+  | string /* slide-sizes: a SlideSizePreset. purposes: a catalog id or free-form goal text. */
+  | string[] /* audiences: catalog ids */
   | { platform: string; handle: string }
   | { header?: unknown; footer?: unknown }
   | { slideImage?: unknown; imageFill?: string | null }
@@ -94,10 +100,10 @@ export interface CompatibleChartType extends SwitchOption {
   /** True for the chart's present type, which is always listed. */
   current: boolean;
 }
-/** Values a picker can offer for a catalog-backed dimension (document inline records, caller catalogs, then the bundled catalog, without duplicates); `blocks` lists the content kinds. */
+/** Values a picker can offer for a catalog-backed dimension (document inline records, caller catalogs, then the bundled catalog, without duplicates); `blocks` lists the content kinds and `slide-sizes` the presets (labelled with their inches). `purposes` lists the catalog; any other goal text is also a valid switch value. */
 export declare function listSwitchOptions(document: unknown, dimension: SwitchDimension, options?: Pick<DimensionSwitchOptions, "catalogs" | "catalogSources">): SwitchOption[];
 /** Chart types the chart's inline data can use as it is (data-shape compatibility, not an engine-support claim). `path` or `slideIndex` picks the chart. */
 export declare function compatibleChartTypes(document: unknown, options?: Pick<DimensionSwitchOptions, "slideIndex" | "path" | "catalogs" | "catalogSources">): CompatibleChartType[];
-/** The value a dimension currently has: `{ value, scope }`, with the catalog id for catalog dimensions. */
+/** The value a dimension currently has: `{ value, scope }`, with the catalog id for catalog dimensions. `slide-sizes` reads the deck's design.dimensions, else its theme's (a preset string, or the object for a custom size); `purposes` reads the goal text or Purpose id. */
 export declare function currentSwitchValue(document: unknown, dimension: SwitchDimension, options?: Pick<DimensionSwitchOptions, "slideIndex" | "path" | "owner" | "index">): { value: unknown; scope: "deck" | "slide" | "block" };
 export { blockConversionTargets } from "./block-convert.js";

package/dist/switches.js

@@ -17,7 +17,25 @@ import { checkedDocument, designPatches, fail, same } from "./edit-helpers.js";
 import { populateLayoutPlaceholders } from "./layout-placeholders.js";
 import { blockConversionTargets, prepareBlockConversion } from "./block-convert.js";
 
-/** The 14 pptx.gallery dimensions (gallery-support.md), in the gallery's order. */
+/** The schema's DimensionPreset values (RR-41), the values of the slide-sizes switch. */
+export const SLIDE_SIZE_PRESETS = Object.freeze(["16:9", "4:3", "16:10", "letter", "a4", "widescreen", "standard"]);
+
+// Slide size in inches per preset, as core's resolveCanvasDimensions composes it (for picker labels).
+const SLIDE_SIZE_LABELS = Object.freeze({
+  "16:9": "16:9 (13.33 x 7.5 in)",
+  "4:3": "4:3 (10 x 7.5 in)",
+  "16:10": "16:10 (10 x 6.25 in)",
+  letter: "Letter (11 x 8.5 in)",
+  a4: "A4 (11.69 x 8.27 in)",
+  widescreen: "Widescreen (13.33 x 7.5 in)",
+  standard: "Standard (10 x 7.5 in)",
+});
+
+/**
+ * Every switchable dimension, in the gallery's order: the 14 pptx.gallery dimensions (gallery-support.md), then the
+ * two document-level ones the gallery does not page yet (RR-41): `slide-sizes` (design.dimensions) and `purposes`
+ * (the document's purpose).
+ */
 export const SWITCH_DIMENSIONS = Object.freeze([
   "layouts",
   "color-schemes",
@@ -33,6 +51,8 @@ export const SWITCH_DIMENSIONS = Object.freeze([
   "headers-footers",
   "blocks",
   "image-treatments",
+  "slide-sizes",
+  "purposes",
 ]);
 
 // Catalog kind behind each catalog-backed dimension.
@@ -47,6 +67,7 @@ const CATALOG_KIND = Object.freeze({
   tones: "tones",
   socials: "socialPlatforms",
   charts: "chartTypes",
+  purposes: "purposes",
 });
 // Top-level document field for the simple metadata dimensions.
 const ROOT_FIELD = Object.freeze({ languages: "language", narratives: "narrative", tones: "tone", audiences: "audience" });
@@ -184,7 +205,26 @@ export function prepareDimensionSwitch(document, dimension, value, options = {})
   let slideIndex;
   let conversionLoss;
 
-  if (dimension === "layouts") {
+  if (dimension === "slide-sizes") {
+    // A preset string; a custom size (design.dimensions as an object with inches) is replaced by it.
+    if (!SLIDE_SIZE_PRESETS.includes(value)) throw fail("invalid-switch-value", `Switch slide-sizes to one of ${SLIDE_SIZE_PRESETS.join(", ")}.`, { value });
+    if (scopeIndex !== undefined) throw fail("deck-scope-only", "A presentation has one slide size: switch slide-sizes for the deck, without slideIndex.", { slideIndex: scopeIndex });
+    const own = document.design?.dimensions;
+    // {preset} alone is the same size as the bare preset string.
+    const sameSize = own && typeof own === "object" && !Array.isArray(own) && own.preset === value && Object.keys(own).length === 1;
+    patches = sameSize ? [] : designPatches(document, [], { dimensions: value });
+    shadowed = shadowedSlides(document, ["dimensions"]);
+    if (options.clearSlideOverrides) {
+      for (const index of shadowed) patches.push({ op: "remove", path: opfPathToJsonPointer(["slides", String(index), "design", "dimensions"]) });
+      shadowed = [];
+    }
+  } else if (dimension === "purposes") {
+    // A catalog id, free-form goal text (no id check: any goal is valid) or an inline Purpose object; the schema validates it.
+    if (typeof value !== "string" && !(value && typeof value === "object" && !Array.isArray(value)))
+      throw fail("invalid-switch-value", "Switch purposes to a catalog id, a goal string or a purpose object.", { value });
+    if (typeof value === "string" && value.length === 0) throw fail("invalid-switch-value", "Switch purposes to a non-empty goal.", { value });
+    patches = [...catalogRecordPatches(document, dimension, options), ...rootPatch(document, "purpose", value)];
+  } else if (dimension === "layouts") {
     slideIndex = scopeIndex;
     slideAt(document, slideIndex, "a layout switch");
     scope = "slide";
@@ -336,6 +376,7 @@ const labelOf = (record) => record.label ?? record.name ?? record.id;
  */
 export function listSwitchOptions(document, dimension, options = {}) {
   if (dimension === "blocks") return BLOCK_KINDS.map((kind) => ({ id: kind, label: kind[0].toUpperCase() + kind.slice(1) }));
+  if (dimension === "slide-sizes") return SLIDE_SIZE_PRESETS.map((preset) => ({ id: preset, label: SLIDE_SIZE_LABELS[preset] }));
   const kind = CATALOG_KIND[dimension];
   if (!kind) return [];
   const seen = new Set();
@@ -407,6 +448,24 @@ export function currentSwitchValue(document, dimension, options = {}) {
     return { value: owner ? getValueAtPath(document, [...owner, "chart", "type"]) : undefined, scope: "slide" };
   }
   if (dimension === "blocks") return { value: undefined, scope: "block" };
+  if (dimension === "slide-sizes") {
+    // The size the deck composes at: its own design.dimensions, else the theme's; a {preset} object reads as its preset.
+    // A custom size (inches without a preset) reads as the object itself. Unset reads as undefined (composed as widescreen).
+    const own = design("dimensions");
+    let size = own.value;
+    let scope = own.scope;
+    if (size === undefined) {
+      const themeId = idOf(design("theme").value);
+      size = themeId ? findCatalogRecord(document, "themes", themeId, {})?.dimensions : undefined;
+      scope = "deck";
+    }
+    return { value: size && typeof size === "object" && !Array.isArray(size) && Object.keys(size).length === 1 && size.preset ? size.preset : size, scope };
+  }
+  if (dimension === "purposes") {
+    // A catalog id or goal text reads as itself, a Purpose object as its id (else the object).
+    const purpose = document.purpose;
+    return { value: purpose && typeof purpose === "object" && !Array.isArray(purpose) ? (purpose.id ?? purpose) : purpose, scope: "deck" };
+  }
   if (dimension === "socials") {
     const host = document[options.owner ?? "speaker"];
     const target = Array.isArray(host) ? host[options.index ?? 0] : host;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openpresentation/opf-editor",
-  "version": "0.11.0",
+  "version": "0.11.2",
   "description": "Embeddable local OPF editor primitives built on the deterministic renderer.",
   "license": "MIT",
   "type": "module",