@openpresentation/opf-editor 0.25.0 → 0.25.1

package/README.md

@@ -40,7 +40,8 @@ The release after 0.14.2 moves the editor onto core 0.15 (a breaking, clean spec
 - **Save and export embed.** `prepareSave`/`saveDocument`, `serializeOpfTransfer` (presentation and slide scope) and `convert` (`/export`) call core's `embed`; the playground's OPF download and PPTX export do too.
 - **Paste** (`prepareOpfImport`, insert mode) uses core's `copySlides`: groups match by `source`, identical records are reused, and the result's `renamed` (`custom-conflict`, `catalog-revision`, `group-name`) and `addedGroups` tell the user what changed.
 - **Update from catalog** is an explicit action: `checkCatalogUpdates(presentation, { catalogs })` lists the embedded records whose catalog record differs, and `applyCatalogUpdate(editor, { refs })` applies only the approved ones as one undoable step. The design panel's `catalog` section runs both and lists the `opf/unresolved-reference` and `opf/undeclared-catalog` findings (`referenceFindings(editor.validation)`).
-- **Editing a catalog's record forks it.** An edit of a layout, theme, colour scheme or font scheme embedded under `catalogs.default` or a named group (from a panel, Properties, Source or any `applyPatch`) moves it into `catalogs.custom` as `<id>-custom` (or the id in `meta.forkIds["<group>:<kind>:<id>"]`), rewrites every reference to it and drops the original, in the same undo step. The change and the session event carry `forked` and a `notice` ("… is now this presentation's own; it no longer receives catalog updates"); approved catalog updates and `moveToCustom` change records in place (`meta.catalogRecordEdit: "in-place"`). `moveToCustom(editor, { group, kind, id }, { id })` is the explicit form, offered for `opf/catalog-record-not-in-source`.
+- **Editing a catalog's record forks it.** An edit of a layout, theme, colour scheme or font scheme embedded under `catalogs.default` or a named group (from a panel, Properties, Source or any `applyPatch`) moves it into `catalogs.custom` as `<id>-custom` (or the id in `meta.forkIds["<group>:<kind>:<id>"]`), rewrites every reference to it and drops the original, in the same undo step. The change and the session event carry `forked` and a `notice` ("… is now this presentation's own; it no longer receives catalog updates"); approved catalog updates and `moveToCustom` change records in place (`meta.catalogRecordEdit: "in-place"`). `moveToCustom(editor, { group, kind, id }, { id })` is the explicit form, offered for `opf/catalog-record-not-in-source`. Opening a document is not an edit: use `replaceDocument` (next bullet).
+- **Opening a document: `replaceDocument`.** `editor.replaceDocument(input, meta?)` puts exactly `input` (a parsed document, JSON text or bytes) in the session as ONE undoable change: Undo restores the previous document, Redo the new one, and nothing under `catalogs.default` or a named group is forked into `catalogs.custom`, even when the two documents embed the same record ids with different content (two examples published at different times). Use it for a host's example menu, File > Open, "start over" and restoring a stored copy; keep `applyPatch` for edits, because an `applyPatch` that replaces the root IS read as an edit of the records the documents share and forks them. It validates like any edit (`meta.rejectInvalid` or the session option refuses an invalid document and changes nothing), accepts the usual `meta` (`source` defaults to `"replace-document"`; the `patch` event carries `meta.replaceDocument: true`) and returns the change; it always records one undo step, also for an equal document. The editor's own File > Open (the playground's Import dialog, "Open as a presentation"), the gallery handoff and `createPersistence`'s `restore()` use it.
 - **Backgrounds** take the flat image form `{ type: "image", src, alt, fit, focus, opacity, recolor, overlay }` (fits `cover`, `contain`, `stretch`, `tile`) and the image-source shorthand, on the deck and on a slide. **Image blocks** carry their own fit, focus, treatments and placement (`/image-options`, the panel's `image` section): a full-bleed photo is a background, a picture beside the content is a placed image block. `design.imageFit` is the default fit of image blocks.
 
 Editor 0.15.0 uses core `^0.15.1` and the optional renderer peer `^0.15.0`. Install renderer and PPTX 0.15 together for the coordinated canvas and export workflow. The shared APIs are core's `validate`, `Finding`, `resolveSlideContext` and the catalog helpers above, and the renderer's `loadFonts()` handle passed as `fonts` to the canvas, export, composition and pagination. Historical version changes are recorded in `CHANGELOG.md`.
@@ -109,8 +110,9 @@ const pane = createSourcePane(container, {
 pane.setFormat('yaml'); pane.focusPath('/slides/1/title'); pane.getText(); pane.destroy();
 ```
 
-Methods: `setFindings(list | null)`, `setFormat(format)`, `focusPath(pointer)` (moves the cursor to the line of a JSON Pointer in any format; exact for JSON, best effort for YAML and Markdown), `getText()`, `refresh()`, `setName`, `setDensity`, `setReadOnly` and `destroy()`. A finding is `{ path, message, severity, line? }` (core `Finding` objects fit). Rows show the path in mono and the line at the right; a click moves the cursor and calls `onFindingSelect`.
+Methods: `replaceDocument(document, { source?, name?, meta? })` (below), `setFindings(list | null)`, `setFormat(format)`, `focusPath(pointer)` (moves the cursor to the line of a JSON Pointer in any format; exact for JSON, best effort for YAML and Markdown), `getText()`, `refresh()`, `setName`, `setDensity`, `setReadOnly` and `destroy()`. A finding is `{ path, message, severity, line? }` (core `Finding` objects fit). Rows show the path in mono and the line at the right; a click moves the cursor and calls `onFindingSelect`.
 
+- **Opening a document: `pane.replaceDocument(document, { source, name })`.** Loading an example or a file into the pane (never by writing its text into the code editor, which the pane applies as a typed edit and forks the catalog records the two documents share) calls `editor.replaceDocument`: one undoable change, no catalog record forked. `document` is a parsed document or JSON text; `source` is the JSON text it was read from (shown byte for byte; `document` itself when that is text) and `name` the file name. In YAML or Markdown the pane shows the document written in that format. Undo and Redo bring back each document's text exactly in the format shown (the opened JSON as written, the replaced document's text as it was, including YAML comments), so one Undo returns to the document and the text the visitor had. The pane keeps the last 8 such texts. A refused document throws (`invalid-opf-edit`, with `issues`) and changes nothing, and works in a read-only pane. A diff typed or pasted into the pane is still an edit, and editing a catalog record in it forks the record.
 - **JSON is canonical** and keeps the author's bytes: a YAML or Markdown edit rewrites only the changed JSON tokens (`exact-source`), and Undo restores the exact spelling.
 - **YAML and Markdown** are core's browser-safe converters, `@openpresentation/opf/yaml` and `/markdown`. Switching format writes the session's document in the new format. An edit parses back to the document and reaches the session as one `replace` patch, after a short delay (`applyDelay`, default 250 ms) so one burst of typing is one undo step. A syntax error, or an OPF rule the session refuses, is listed with its line and never reaches the document; Undo, Redo and outside edits replace a draft that did not parse.
 - **Nothing is lost silently.** Markdown writes what its dialect has no syntax for (a `design`, region keys, nested groups) as YAML in `opf-slide` and `opf-block` fences; each such part is a warning finding with its JSON Pointer and reason. Comments in YAML cannot survive a rewrite from the document: Format and outside edits drop them and say how many. A document that is not valid OPF cannot be written as YAML or Markdown; the pane stays in JSON and says so.
@@ -951,7 +953,7 @@ input.onchange = async () => {
 - **Findings.** The conversion's findings for YAML and Markdown, in core's `Finding` shape: `path` (a JSON Pointer such as `/slides/1/bogus`), `message`, `severity` and `location` (line and column in the file). A deck that reads but has OPF errors is returned with them, so a host can show them; JSON gives none (the editor session validates it).
 - **Errors.** Text that cannot be read at all throws `DeckFileError` with a `code` and a clear message: `unreadable`, `file-too-large` (over 20 MB), `empty-file`, `unsupported-file` (a .pptx or other binary file), `invalid-json`, `invalid-yaml`, `invalid-markdown` (with the syntax `findings` and the line) and `not-a-deck` (JSON without a `slides` list, such as one slide or a block, which a host can send to its paste path as the playground does).
 
-The source pane has no file-opening path of its own, so it keeps no second copy of this. The playground's Import dialog uses `readDeckFile` and `DECK_FILE_ACCEPT` for its file tab and for dropped files (`examples/transfer-controls.js`). Icons in the presenter button are inlined [Lucide](https://lucide.dev) paths (ISC license).
+Put the opened document in the session with `editor.replaceDocument(document)` (or `pane.replaceDocument(document, { source })` when a source pane is mounted), not `applyPatch`: opening is one undoable change that forks no catalog record. The source pane has no file-opening path of its own, so it keeps no second copy of this. The playground's Import dialog uses `readDeckFile` and `DECK_FILE_ACCEPT` for its file tab and for dropped files (`examples/transfer-controls.js`). Icons in the presenter button are inlined [Lucide](https://lucide.dev) paths (ISC license).
 
 ## Optional React Bindings
 

package/dist/index.d.ts

@@ -91,6 +91,14 @@ export interface EditorSession {
   setGroupComposition(path: string, composition: Composition, meta?: Record<string, unknown>): EditorChange;
   setCatalog(path: string | string[], catalogKind: string, id: string, meta?: Record<string, unknown>): EditorChange;
   applyPatch(operations: JsonPatchOperation[], meta?: Record<string, unknown>): EditorChange;
+  /**
+   * Open a different document in the session: the whole document is replaced as one undoable change, and the replacement is never
+   * read as an edit of the catalog records the two documents share, so nothing under `catalogs.default` or a named group is forked
+   * into `catalogs.custom`. `input` is a parsed document, JSON text or bytes. It is validated like any edit (`meta.rejectInvalid` or
+   * the session option refuses an invalid document and changes nothing). It always records its one change, also for an equal document.
+   * `meta.source` defaults to `"replace-document"`; the `patch` event carries `meta.replaceDocument: true`.
+   */
+  replaceDocument(input: unknown, meta?: Record<string, unknown>): EditorChange;
   /** The undo and redo stacks as plain data (oldest entry first), for hosts that persist work. */
   exportHistory(): EditorHistory;
   /** Replace the document and, optionally, the history in one step (one `restore` event). A history that does not replay against the document throws `invalid-history` before anything changes. */

package/dist/index.js

@@ -314,6 +314,23 @@ export function createEditorSession(input, options = {}) {
       return setCatalogId(editor, path, catalogKind, id, meta);
     },
     applyPatch: commitPatch,
+    /**
+     * Open a different document in the session (a host's example menu, File > Open, "start over"): the whole document is replaced as ONE
+     * undoable change (Undo restores the previous document, Redo the new one). Unlike an `applyPatch` that replaces the root, this is
+     * never read as the user editing the catalog records the two documents share: records under `catalogs.default` or a named group
+     * keep the ids and content the new document carries, and nothing is forked into `catalogs.custom`. `input` is a parsed document,
+     * JSON text or bytes. The document is validated like any edit (`meta.rejectInvalid` or the session option refuses an invalid one
+     * and changes nothing). It always records its one change, also when the new document equals the open one (Undo then returns to the
+     * same document, as for any other replace). `meta.source` defaults to `"replace-document"`; the event is a `patch` whose `meta.replaceDocument` is true.
+     */
+    replaceDocument(input, meta = {}) {
+      return commitPatch([{ op: "replace", path: "", value: parseInput(input) }], {
+        ...meta,
+        source: meta.source ?? "replace-document",
+        replaceDocument: true,
+        catalogRecordEdit: "in-place"
+      });
+    },
     /**
      * The undo and redo stacks as plain data (oldest entry first): `{ undo: [{ patches, inversePatches, meta }], redo: [...] }`.
      * Together with `presentation` this is everything `restoreState` needs to bring a session back, for hosts that persist work.

package/dist/persistence.js

@@ -268,7 +268,7 @@ export function createPersistence(editor, options = {}) {
       }
     } else {
       // The user already worked in this session: bring the copy back as one undoable change instead of replacing their history.
-      editor.applyPatch([{ op: "replace", path: "", value: structuredClone(record.presentation) }], { source: "restore" });
+      editor.replaceDocument(structuredClone(record.presentation), { source: "restore" });
     }
     touched = true;
     baseline = record.dirty === false ? jsonOf(editor.presentation) : null;
@@ -315,7 +315,7 @@ export function createPersistence(editor, options = {}) {
     let record;
     try { record = await adapter.get(earlierKey); } catch { return false; }
     if (!validRecord(record)) return false;
-    try { editor.applyPatch([{ op: "replace", path: "", value: structuredClone(record.presentation) }], { source: "restore" }); }
+    try { editor.replaceDocument(structuredClone(record.presentation), { source: "restore" }); }
     catch { return false; }
     pending = undefined;
     touched = true;

package/dist/source-pane.d.ts

@@ -1,4 +1,4 @@
-import type { EditorSession } from "./index.js";
+import type { EditorChange, EditorSession } from "./index.js";
 import type { JsonCatalogContext } from "./json-options.js";
 import type { JsonCodeEditor } from "./json-editor.js";
 
@@ -64,8 +64,26 @@ export interface SourcePaneOptions {
   onError?(error: unknown): void;
 }
 
+export interface ReplaceDocumentOptions {
+  /** The JSON text the document was read from. Used when it parses to the document, so its spelling is kept. */
+  source?: string;
+  /** The file name without extension, as `setName` (the document's own name is not used). */
+  name?: string;
+  /** Extra `meta` for the session change (`source` defaults to `"replace-document"`). */
+  meta?: Record<string, unknown>;
+}
+
 export interface SourcePane {
   element: HTMLElement;
+  /**
+   * Open a different document in the session and the pane (a host's example menu, File > Open): `editor.replaceDocument`, so it is one
+   * undoable change and no catalog record is forked into `catalogs.custom` (a diff typed or pasted into the pane is an edit; this is not).
+   * `document` is a parsed document or JSON text. The pane shows `options.source` (the JSON text the document was read from, kept byte for
+   * byte; `document` itself when it is text) in JSON and the document written in YAML or Markdown. Undo and Redo bring back each
+   * document's text exactly, in the format that is shown. A document the session refuses throws (`invalid-opf-edit` with `issues`) and
+   * changes nothing. Works in a read-only pane.
+   */
+  replaceDocument(document: unknown, options?: ReplaceDocumentOptions): EditorChange;
   /** Re-read the document from the session. */
   refresh(): void;
   /** Replace the host findings; `null` returns to the session's own validation. */

package/dist/source-pane.js

@@ -2,7 +2,7 @@ import { parse as parseJsonc, printParseErrorCode } from "jsonc-parser";
 import { fromYaml, scanYamlComments, toYaml } from "@openpresentation/opf/yaml";
 import { fromMarkdown, toMarkdown } from "@openpresentation/opf/markdown";
 import { mountJsonCodeEditor } from "./json-editor.js";
-import { createSourceMemory, findDuplicateKey, updateJsonSource } from "./exact-source.js";
+import { MAX_EXACT_SOURCE_LENGTH, createSourceMemory, findDuplicateKey, updateJsonSource } from "./exact-source.js";
 import { lineForPath, lineOfOffset, offsetOfLine } from "./source-lines.js";
 import { errorText, normalizeFinding, rejectionFindings as findingsOfError } from "./source-findings.js";
 
@@ -127,6 +127,17 @@ export function createSourcePane(container, options = {}) {
   // Whether the findings include an error, and what the editor's `aria-invalid` currently says (null: not yet set).
   let invalid = false, shownInvalid = null;
   const lineCache = { key: "", values: new Map() };
+  // The exact text of the documents `replaceDocument` replaced and opened, per format, so Undo and Redo show it again byte for byte
+  // (a YAML comment, the author's JSON spelling). Keyed by format and document; the oldest entries go first.
+  const exactTexts = new Map();
+  const rememberText = (target, value, text) => {
+    if (typeof text !== "string" || text.length > MAX_EXACT_SOURCE_LENGTH) return;
+    const key = `${target}|${JSON.stringify(value)}`;
+    exactTexts.delete(key);
+    exactTexts.set(key, text);
+    while (exactTexts.size > 8) exactTexts.delete(exactTexts.keys().next().value);
+  };
+  const exactText = (target, value) => exactTexts.get(`${target}|${JSON.stringify(value)}`);
 
   // ---- DOM ----------------------------------------------------------------------------------------------------------
   const root = el("div", "opf-source opf-ui", { "data-density": density });
@@ -315,6 +326,12 @@ export function createSourcePane(container, options = {}) {
       const before = control.api.getValue(), comments = scanYamlComments(before).count;
       if (comments > 0 && written.text !== before) transientNotes = [normalizeFinding({ message: `${plural(comments, "comment")} in the YAML ${comments === 1 ? "was" : "were"} dropped when the document changed outside the source.`, severity: "warning" }, "format")];
     }
+    // A document `replaceDocument` opened or replaced comes back with the exact text it had.
+    const exact = exactText(format, deck());
+    if (exact !== undefined && exact !== written.text) {
+      try { if (same(readText(format, exact, catalogs()).deck, deck())) { written = { ...written, text: exact }; if (format === "json") jsonText = exact; } }
+      catch { /* The remembered text no longer reads as this document: use the generated one. */ }
+    }
     noteFindings = written.notes;
     if (format !== "json") syncJsonSafe();
     if (written.text !== control.api.getValue()) show(written.text);
@@ -332,6 +349,60 @@ export function createSourcePane(container, options = {}) {
     fromSession();
   });
 
+  // ---- Replacing the whole document ----------------------------------------------------------------------------------
+  /**
+   * Open `input` (a document, or JSON text) as the whole document with `editor.replaceDocument`: one undoable change, no catalog record
+   * forked. The text shown is `options.source` (or `input` when it is text) in JSON, the document written in YAML or Markdown, and Undo
+   * and Redo bring each document's text back exactly.
+   */
+  function replaceDocument(input, replaceOptions = {}) {
+    if (destroyed) throw new Error("The source pane was destroyed.");
+    flush();
+    const before = deck();
+    const beforeText = dirty ? undefined : control.api.getValue();
+    const authored = typeof input === "string" ? input : replaceOptions.source;
+    transientNotes = [];
+    let change;
+    applying = true;
+    try {
+      // Remember the spelling of the document being replaced, then open the new one.
+      syncJson(before);
+      change = editor.replaceDocument(input, { format, ...replaceOptions.meta });
+    } catch (error) {
+      rejectionFindings = error?.issues?.length ? findingsOfError(error) : [normalizeFinding({ message: errorText(error), kind: "rejected" })];
+      renderFindings();
+      throw error;
+    } finally { applying = false; }
+    clearTimeout(timer);
+    timer = null;
+    for (const key of Object.keys(drafts)) delete drafts[key];
+    syntaxFindings = [];
+    rejectionFindings = [];
+    dirty = false;
+    version++;
+    const opened = deck();
+    let written;
+    let authoredJson = null;
+    if (typeof authored === "string") { try { if (same(JSON.parse(authored), opened) && !findDuplicateKey(authored)) authoredJson = authored; } catch { /* Not the document's JSON: write it. */ } }
+    if (replaceOptions.name !== undefined) { name = sanitizeName(replaceOptions.name) || "deck"; updateBar(); }
+    try { written = format === "json" && authoredJson !== null ? { text: authoredJson, notes: [] } : write(format, opened); }
+    catch (error) {
+      syncJsonSafe();
+      rejectionFindings = [normalizeFinding({ message: `The document cannot be written as ${formatOf(format).label}: ${errorText(error)}. The text below is the last version that could be.`, kind: "rejected" })];
+      renderFindings();
+      return change;
+    }
+    if (authoredJson !== null) jsonText = authoredJson; else syncJsonSafe();
+    rememberText(format, opened, written.text);
+    rememberText(format, before, beforeText);
+    noteFindings = written.notes;
+    if (written.text !== control.api.getValue()) show(written.text); else baseline = written.text;
+    renderedKey = "";
+    renderFindings();
+    syncAttributes();
+    return change;
+  }
+
   // ---- Format -------------------------------------------------------------------------------------------------------
   function setFormatInternal(next, notify) {
     const target = formatOf(next);
@@ -627,6 +698,11 @@ export function createSourcePane(container, options = {}) {
 
   return {
     element: root,
+    /**
+     * Open a different document: `editor.replaceDocument` as one undoable change that forks no catalog record, with the text shown in
+     * the current format. `options.source` is the JSON text the document was read from (kept byte for byte); `options.name` renames the file.
+     */
+    replaceDocument,
     /** Re-read the document from the session (for example after the host changed it without events). */
     refresh() { version++; fromSession(false); },
     /** Replace the host findings; `setFindings(null)` returns to the session's own validation. */

package/package.json

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