@openpresentation/opf-editor 0.25.2 → 0.25.3

package/README.md

@@ -110,9 +110,10 @@ const pane = createSourcePane(container, {
 pane.setFormat('yaml'); pane.focusPath('/slides/1/title'); pane.getText(); pane.destroy();
 ```
 
-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`.
+Methods: `replaceDocument(document, { source?, format?, 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.
+- **Opening a document: `pane.replaceDocument(document, { source, format, 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; `name` is the file name. `source` is the text the document was read from, in any of the three formats: the pane shows it as written (the JSON's formatting, the YAML's comments, the Markdown's layout) when the pane is in that format, and core's rewrite of the document otherwise. `format` (`"json"`, `"yaml"` or `"md"`) says which format `source` is; left out, it is inferred as the first of JSON, the pane's format, YAML and Markdown that reads as exactly this document (a `source` that reads as no format, or as another document, is ignored; an unknown `format` throws a `TypeError` before anything changes). The original text of a format other than the one shown is kept too: switching the pane to it shows those bytes, not a rewrite. Undo and Redo bring back each document's text exactly in the format shown (the opened text 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, which are also what a later load of the same document shows. 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.
+- **Keyboard Undo and Redo in the pane (one model).** Cmd/Ctrl+Z and Cmd/Ctrl+Shift+Z (Ctrl+Y) work in two layers, in this order. First CodeMirror's history, which holds only the text typed in the pane since its last whole-document change (a `replaceDocument`, or a session Undo, Redo or restore, each of which clears it because the typed edits no longer fit the text). When that has nothing left, the key steps the session over a whole-document replace, exactly as its Undo and Redo do, so the text comes back byte for byte: Undo steps back over the nearest `replaceDocument` together with the pane's own edits typed on it (the typing was already undone, step by step, by CodeMirror's history); Redo steps forward over the replace. The key never reaches over an edit made elsewhere (the canvas, a panel): Undo stops at it, and the host's Undo button (or `editor.undo()`) undoes that edit, after which the key reaches the load again. A read-only pane takes neither key. `mountJsonCodeEditor` exposes the same seam as `historyFallback: { undo(), redo() }` (answer `true` when you did something) plus `resetHistory()` and `undoDepth()` on the control.
 - **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.

package/dist/json-editor.d.ts

@@ -28,6 +28,12 @@ export interface JsonCodeEditorOptions {
   catalogs?: JsonCatalogContext;
   /** Overrides the built-in menu, allowing an existing host UI to keep its appearance. */
   onOptions?(left?: number, top?: number): void;
+  /**
+   * Cmd/Ctrl+Z and Cmd/Ctrl+Shift+Z (Ctrl+Y) run CodeMirror's history first. When it has nothing left to undo or redo, the fallback runs
+   * and answers true when it did something (false lets the key pass on). The source pane uses it to step the session back over a
+   * whole-document replace.
+   */
+  historyFallback?: { undo?(): boolean; redo?(): boolean };
   onFocus?(): void;
   onHoverField?(path: string | null): void;
   onError?(error: unknown): void;
@@ -39,6 +45,10 @@ export interface JsonCodeEditor {
   setCatalogs(catalogs: JsonCatalogContext): void;
   setLanguage(language: "json" | "yaml" | "markdown"): void;
   setReadOnly(readOnly: boolean): void;
+  /** Forget the typed edits CodeMirror can undo, for when the text they were typed against was replaced. The text is unchanged. */
+  resetHistory(): void;
+  /** How many typed edit groups CodeMirror can still undo. */
+  undoDepth(): number;
   /** The CodeMirror `EditorView`. */
   readonly view: import("@codemirror/view").EditorView;
   openOptions(left?: number, top?: number): Promise<void>;

package/dist/json-editor.js

@@ -1,6 +1,6 @@
 import { Annotation, Compartment, EditorSelection, EditorState, Prec, StateEffect, StateField, Transaction } from "@codemirror/state";
 import { Decoration, EditorView, drawSelection, keymap, lineNumbers } from "@codemirror/view";
-import { defaultKeymap, history, historyKeymap, indentWithTab, isolateHistory, redo } from "@codemirror/commands";
+import { defaultKeymap, history, historyKeymap, indentWithTab, isolateHistory, redo, undo, undoDepth } from "@codemirror/commands";
 import { HighlightStyle, StreamLanguage, bracketMatching, codeFolding, foldKeymap, indentOnInput, indentUnit, syntaxHighlighting } from "@codemirror/language";
 import { json, jsonParseLinter } from "@codemirror/lang-json";
 import { yaml } from "@codemirror/lang-yaml";
@@ -167,7 +167,7 @@ function skipDelimiter(view, delimiter) {
   return true;
 }
 function mountJsonCodeEditor(parent, options) {
-  const attributes = new Compartment(), indent = new Compartment(), language = new Compartment(), editable = new Compartment();
+  const attributes = new Compartment(), indent = new Compartment(), language = new Compartment(), editable = new Compartment(), historyField = new Compartment();
   const editableExtension = (readOnly) => [EditorState.readOnly.of(Boolean(readOnly)), EditorView.editable.of(!readOnly)];
   let languageName = options.language ?? "json";
   let disposed=false, menu=null, catalogs=options.catalogs??[], generation=0;
@@ -196,6 +196,11 @@ function mountJsonCodeEditor(parent, options) {
       label: option.label, detail: option.detail, info: option.info, boost: option.boost, type: found.kind === "key" ? "property" : "enum", apply: completionApply(found, option),
     })) };
   }
+  // Undo and Redo run CodeMirror's history first. When it has nothing left, the host's fallback may step further (the source pane
+  // routes a whole-document replace to the session); a fallback answers true when it did something.
+  const undoCommand = (target) => undo(target) || Boolean(options.historyFallback?.undo?.());
+  const redoCommand = (target) => redo(target) || Boolean(options.historyFallback?.redo?.());
+  const historyBindings = historyKeymap.map((binding) => binding.run === undo ? { ...binding, run: undoCommand } : binding.run === redo ? { ...binding, run: redoCommand } : binding);
   const completionExtension = options.completions ? [autocompletion({ override: [completionSource], defaultKeymap: false, icons: false, maxRenderedOptions: 60 }), completionKeys] : null;
   let currentIndent = indentation(options.code);
   const contentAttributes = (invalid = options.invalid, describedBy = options.describedBy) => EditorView.contentAttributes.of({
@@ -213,7 +218,7 @@ function mountJsonCodeEditor(parent, options) {
     jsonSource.init(()=>options.code),jsonSourceHistory,
     indent.of(indentUnit.of(currentIndent)),
     indentOnInput(),
-    history(),
+    historyField.of(history()),
     drawSelection(),
     bracketMatching(),
     closeBrackets(),
@@ -233,7 +238,7 @@ function mountJsonCodeEditor(parent, options) {
       // undo steps still available (otherwise it silently performs undo).
       if ((event.metaKey || event.ctrlKey) && event.shiftKey && !event.altKey && event.key.toLowerCase() === "z") {
         event.preventDefault();
-        redo(view);
+        redoCommand(view);
         return true;
       }
       if ((event.metaKey || event.ctrlKey) && event.shiftKey && !event.altKey && event.key.toLowerCase() === "f") {
@@ -262,7 +267,7 @@ function mountJsonCodeEditor(parent, options) {
       indentWithTab,
       ...closeBracketsKeymap,
       ...defaultKeymap,
-      ...historyKeymap,
+      ...historyBindings,
       ...searchKeymap,
       ...foldKeymap
     ]),
@@ -331,6 +336,13 @@ function mountJsonCodeEditor(parent, options) {
       languageName=name;closeOptions();
       view.dispatch({ effects: language.reconfigure(languageExtension(name, completionExtension)) });
     },
+    /** Forget the typed edits CodeMirror can undo (the text they were typed against is gone). Returns nothing; the document is unchanged. */
+    resetHistory(){
+      view.dispatch({ effects: historyField.reconfigure([]) });
+      view.dispatch({ effects: historyField.reconfigure(history()) });
+    },
+    /** How many typed edit groups CodeMirror can still undo. */
+    undoDepth: () => undoDepth(view.state),
     setReadOnly(value){view.dispatch({ effects: editable.reconfigure(editableExtension(value)) });},
     /** The CodeMirror view, for hosts that scroll or measure it. */
     view,

package/dist/source-pane.d.ts

@@ -65,8 +65,14 @@ export interface SourcePaneOptions {
 }
 
 export interface ReplaceDocumentOptions {
-  /** The JSON text the document was read from. Used when it parses to the document, so its spelling is kept. */
+  /**
+   * The text the document was read from: JSON, YAML or Markdown. When it reads as exactly the document, the pane keeps its spelling (JSON
+   * formatting, YAML comments, Markdown prose layout), shows it while the pane is in that format and brings it back on Undo, Redo and
+   * when the format is switched to it. Text that does not read as the document is ignored.
+   */
   source?: string;
+  /** The format of `source`. Default: inferred, the first of JSON, the pane's format, YAML and Markdown that reads as the document. */
+  format?: SourceFormat;
   /** 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"`). */
@@ -78,10 +84,11 @@ export interface SourcePane {
   /**
    * 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.
+   * `document` is a parsed document or JSON text. The pane shows `options.source` (the text the document was read from in JSON, YAML or
+   * Markdown, kept byte for byte, comments included; `document` itself when it is JSON text) in the format it is in, and the document
+   * written by core's converter when no original text fits. Undo and Redo bring back each document's text exactly, in the format that is
+   * shown, and so do Cmd/Ctrl+Z and Cmd/Ctrl+Shift+Z once the text typed since the load is undone. 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. */

package/dist/source-pane.js

@@ -236,6 +236,7 @@ export function createSourcePane(container, options = {}) {
     catalogs: options.catalogs ?? editor.catalogs,
     describedBy: `${id}-findings`,
     onChange: () => schedule(),
+    historyFallback: { undo: () => stepReplace("undo"), redo: () => stepReplace("redo") },
     onError: (error) => options.onError?.(error),
   });
 
@@ -327,11 +328,7 @@ export function createSourcePane(container, options = {}) {
       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. */ }
-    }
+    written = preferExact(format, deck(), written);
     noteFindings = written.notes;
     if (format !== "json") syncJsonSafe();
     if (written.text !== control.api.getValue()) show(written.text);
@@ -339,6 +336,16 @@ export function createSourcePane(container, options = {}) {
     renderFindings();
     syncAttributes();
   }
+  /** The remembered text of `value` in `target` (what `replaceDocument` was given or replaced) when it still reads as `value`; else `written`. */
+  function preferExact(target, value, written) {
+    const exact = exactText(target, value);
+    if (exact === undefined || exact === written.text) return written;
+    try {
+      if (!same(readText(target, exact, catalogs()).deck, value)) return written;
+    } catch { return written; }
+    if (target === "json") jsonText = exact;
+    return { ...written, text: exact };
+  }
   function syncJsonSafe() { try { syncJson(deck()); } catch { /* Keep the last JSON. */ } }
 
   const unsubscribe = editor.subscribe((event) => {
@@ -346,21 +353,39 @@ export function createSourcePane(container, options = {}) {
     if (event.type === "catalogs") { control.setCatalogs(options.catalogs ?? editor.catalogs); renderFindings(); return; }
     if (applying) return;
     version++;
+    // Undo, Redo, a restore and a whole-document replace by the host move the text under the typed edits CodeMirror remembers; they
+    // would no longer fit it.
+    if (event.type === "undo" || event.type === "redo" || event.type === "restore" || event.meta?.replaceDocument) control.resetHistory();
     fromSession();
   });
 
   // ---- Replacing the whole document ----------------------------------------------------------------------------------
+  /**
+   * Which format the text is, among those that read as exactly `opened`: the declared `format` (which must read so), else JSON first
+   * (the form `replaceDocument` always took), then the pane's own format, then the others. Null when none reads as the document.
+   */
+  function sourceFormatOf(text, opened, declared) {
+    const order = declared ? [declared] : [...new Set(["json", format, "yaml", "md"])];
+    for (const candidate of order) {
+      try {
+        const read = readText(candidate, text, catalogs());
+        if (read.deck && same(read.deck, opened)) return candidate;
+      } catch { /* Not this format. */ }
+    }
+    return null;
+  }
   /**
    * 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.
+   * forked. The text shown is the original text of the document when `source` (or `input`, when it is JSON text) is that text in the
+   * pane's format, and the document written by core's converter otherwise. The original text of any format is kept for the pane's other
+   * formats and for Undo and Redo, which bring each document's text back exactly.
    */
   function replaceDocument(input, replaceOptions = {}) {
     if (destroyed) throw new Error("The source pane was destroyed.");
+    if (replaceOptions.format !== undefined && !FORMATS.some((entry) => entry.id === replaceOptions.format)) throw new TypeError(`replaceDocument: format must be "json", "yaml" or "md", not ${JSON.stringify(replaceOptions.format)}.`);
     flush();
     const before = deck();
     const beforeText = dirty ? undefined : control.api.getValue();
-    const authored = typeof input === "string" ? input : replaceOptions.source;
     transientNotes = [];
     let change;
     applying = true;
@@ -380,11 +405,21 @@ export function createSourcePane(container, options = {}) {
     rejectionFindings = [];
     dirty = false;
     version++;
+    // The typed edits CodeMirror remembers belong to the document that was replaced.
+    control.resetHistory();
     const opened = deck();
-    let written;
+    // The original text: JSON text given as `input` is that document's JSON; `source` is its text in `format` (inferred when not given).
     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. */ } }
+    const originals = [];
+    if (typeof input === "string") originals.push({ text: input, format: "json" });
+    if (typeof replaceOptions.source === "string" && (typeof input !== "string" || replaceOptions.format)) originals.push({ text: replaceOptions.source, format: replaceOptions.format });
+    for (const original of originals) {
+      const kind = sourceFormatOf(original.text, opened, original.format);
+      if (kind === "json") authoredJson ??= original.text;
+      else if (kind) rememberText(kind, opened, original.text);
+    }
     if (replaceOptions.name !== undefined) { name = sanitizeName(replaceOptions.name) || "deck"; updateBar(); }
+    let written;
     try { written = format === "json" && authoredJson !== null ? { text: authoredJson, notes: [] } : write(format, opened); }
     catch (error) {
       syncJsonSafe();
@@ -393,6 +428,8 @@ export function createSourcePane(container, options = {}) {
       return change;
     }
     if (authoredJson !== null) jsonText = authoredJson; else syncJsonSafe();
+    // The text shown now is what Undo and Redo bring back for this document, in the format shown.
+    if (!(format === "json" && authoredJson !== null)) written = preferExact(format, opened, written);
     rememberText(format, opened, written.text);
     rememberText(format, before, beforeText);
     noteFindings = written.notes;
@@ -403,6 +440,29 @@ export function createSourcePane(container, options = {}) {
     return change;
   }
 
+  /**
+   * Cmd/Ctrl+Z and Cmd/Ctrl+Shift+Z (Ctrl+Y) after CodeMirror's own history has nothing left: step the session over a whole-document
+   * replace, as its Undo and Redo buttons do, so the text comes back exactly. Undo steps back over the nearest `replaceDocument` together
+   * with the pane's own edits typed on it (CodeMirror already undid the typing); an edit made elsewhere (the canvas, a panel) stops it.
+   * Redo steps forward over a replace only. Returns whether it did something.
+   */
+  function stepReplace(direction) {
+    if (destroyed || readOnly || typeof editor.exportHistory !== "function") return false;
+    flush();
+    if (dirty || !(direction === "undo" ? editor.canUndo : editor.canRedo)) return false;
+    const history = editor.exportHistory();
+    if (direction === "redo") {
+      if (!history.redo.at(-1)?.meta?.replaceDocument) return false;
+      editor.redo({ source: "source-pane" });
+      return true;
+    }
+    let index = history.undo.length - 1;
+    while (index >= 0 && !history.undo[index].meta?.replaceDocument && history.undo[index].meta?.source === "source-pane") index -= 1;
+    if (index < 0 || !history.undo[index].meta?.replaceDocument) return false;
+    for (let steps = history.undo.length - index; steps > 0; steps -= 1) editor.undo({ source: "source-pane" });
+    return true;
+  }
+
   // ---- Format -------------------------------------------------------------------------------------------------------
   function setFormatInternal(next, notify) {
     const target = formatOf(next);
@@ -413,7 +473,7 @@ export function createSourcePane(container, options = {}) {
     const draft = drafts[target.id];
     if (draft && draft.version === version) written = { text: draft.text, notes: [], draft: true };
     else {
-      try { written = write(target.id, deck()); }
+      try { written = preferExact(target.id, deck(), write(target.id, deck())); }
       catch (error) {
         rejectionFindings = [normalizeFinding({ message: `The document cannot be written as ${target.label}: ${errorText(error)} Fix the findings first.`, kind: "rejected" })];
         renderFindings();

package/package.json

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