@miy2/xml-api 0.9.0 → 0.9.1

package/dist/engine/sync-engine.js

@@ -1,24 +1,31 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.SyncEngine = void 0;
-const parser_1 = require("../cst/parser");
-const xml_grammar_1 = require("../cst/xml-grammar");
-const history_manager_1 = require("../history-manager");
-const formatter_1 = require("../model/formatter");
-const xml_api_model_1 = require("../model/xml-api-model");
-const xml_binder_1 = require("../model/xml-binder");
-const xml_api_events_1 = require("../xml-api-events");
-const editor_state_1 = require("./editor-state");
-const transaction_1 = require("./transaction");
-class SyncEngine {
-    constructor(source, grammar = xml_grammar_1.grammar) {
+import { Parser } from "../cst/parser";
+import { grammar as defaultGrammar } from "../cst/xml-grammar";
+import { HistoryManager } from "../history-manager";
+import { ModelElement } from "../model/xml-api-model";
+import { XMLBinder } from "../model/xml-binder";
+import { EventEmitter } from "../xml-api-events";
+import { EditorState } from "./editor-state";
+import { Transaction } from "./transaction";
+import { TransactionBuilder } from "./transaction-builder";
+/**
+ * The core engine that manages the editor state and coordinates synchronization.
+ *
+ * It implements a transaction-based update cycle:
+ * 1. Receives a `Transaction` describing changes.
+ * 2. Updates the `EditorState` (Source).
+ * 3. Triggers the `Parser` (Source -> CST).
+ * 4. Triggers the `XMLBinder` (CST -> Model).
+ * 5. Notifies listeners (including `SchemaView`s) of changes.
+ */
+export class SyncEngine {
+    constructor(source, grammar = defaultGrammar) {
         this.isTransacting = false;
         this.collabBridge = null;
-        this._state = editor_state_1.EditorState.create(source);
-        this.parser = new parser_1.Parser(grammar);
-        this.binder = new xml_binder_1.XMLBinder(source);
-        this.history = new history_manager_1.HistoryManager();
-        this.events = new xml_api_events_1.EventEmitter();
+        this._state = EditorState.create(source);
+        this.parser = new Parser(grammar);
+        this.binder = new XMLBinder(source);
+        this.history = new HistoryManager();
+        this.events = new EventEmitter();
         this.fullParse();
     }
     get state() {
@@ -47,6 +54,15 @@ class SyncEngine {
     }
     /**
      * Applies a transaction to the engine, updating the state and notifying listeners.
+     * This is the single point of truth for all state transitions in the system.
+     *
+     * It handles:
+     * - History recording (Undo/Redo)
+     * - Incremental Parsing and Reconciliation
+     * - Event Dispatching
+     * - Collaboration hooks
+     *
+     * @param tr The transaction to apply.
      */
     dispatch(tr) {
         if (!tr.docChanged)
@@ -66,6 +82,7 @@ class SyncEngine {
                 const oldText = oldState.source.slice(p.from, p.to);
                 const newEnd = p.from + p.text.length;
                 this.history.push({
+                    timestamp: Date.now(),
                     redo: { from: p.from, to: p.to, text: p.text },
                     undo: { from: p.from, to: newEnd, text: oldText },
                 });
@@ -78,7 +95,7 @@ class SyncEngine {
         }
         this._state = this._state.update({ source: newSource });
         // Core Update Logic (Parser / Binder)
-        this.binder = new xml_binder_1.XMLBinder(newSource);
+        this.binder = new XMLBinder(newSource);
         // Optimization: If single patch, try incremental. Else full parse.
         let handled = false;
         if (tr.patches.length === 1 && oldState.cst) {
@@ -86,17 +103,23 @@ class SyncEngine {
             const delta = p.text.length - (p.to - p.from);
             const incrementalResult = this.tryIncrementalUpdate(p.from, p.to, delta);
             if (incrementalResult) {
+                let success = true;
                 if (oldState.model) {
-                    this.updateModelIncremental(incrementalResult.oldNode, incrementalResult.newNode, tr);
+                    success = this.updateModelIncremental(incrementalResult.oldNode, incrementalResult.newNode, tr);
                 }
                 else {
                     this.events.emit({ type: "full", transaction: tr });
                 }
-                if (this._state.cst && !this._state.cst.wellFormed) {
-                    this._state = this._state.update({ model: null });
-                    this.events.emit({ type: "full", transaction: tr });
+                if (success) {
+                    if (this._state.cst && !this._state.cst.wellFormed) {
+                        this._state = this._state.update({ model: null });
+                        this.events.emit({ type: "full", transaction: tr });
+                    }
+                    handled = true;
+                }
+                else {
+                    handled = false;
                 }
-                handled = true;
             }
         }
         if (!handled) {
@@ -112,18 +135,33 @@ class SyncEngine {
      * Update the source code (e.g. from text editor).
      * Handles history recording and incremental parsing.
      */
-    updateSource(from, to, text) {
-        const tr = new transaction_1.Transaction(this._state);
+    updateSource(from, to, text, 
+    // biome-ignore lint/suspicious/noExplicitAny: Metadata can store any type
+    meta) {
+        const tr = new Transaction(this._state);
+        if (meta) {
+            for (const [key, value] of Object.entries(meta)) {
+                tr.setMeta(key, value);
+            }
+        }
         tr.replace(from, to, text);
         this.dispatch(tr);
     }
     /**
      * Apply a programmatic change derived from Model operations.
      * This is the "Application -> Source" flow.
+     * @deprecated Use `dispatch(new Transaction(state).replace(...))` instead.
      */
-    applyPatch(start, end, text) {
+    applyPatch(start, end, text, 
+    // biome-ignore lint/suspicious/noExplicitAny: Metadata can store any type
+    meta) {
         // Uses dispatch via updateSource logic, but conceptually distinct
-        const tr = new transaction_1.Transaction(this._state);
+        const tr = new Transaction(this._state);
+        if (meta) {
+            for (const [key, value] of Object.entries(meta)) {
+                tr.setMeta(key, value);
+            }
+        }
         tr.replace(start, end, text);
         this.dispatch(tr);
     }
@@ -153,78 +191,80 @@ class SyncEngine {
         }
     }
     // --- High-Level Model Operations (delegated to Binder) ---
-    setAttribute(modelNode, key, value) {
-        if (!modelNode.cst)
-            throw new Error("Model node not linked to CST");
-        const patch = this.binder.calcSetAttributePatch(modelNode, key, value);
-        if (patch) {
-            this.applyPatch(patch.start, patch.end, patch.text);
+    /**
+     * @deprecated Use `dispatch(new TransactionBuilder(engine.state, engine.binder).setAttribute(...))` instead.
+     */
+    setAttribute(modelNode, key, value, 
+    // biome-ignore lint/suspicious/noExplicitAny: Metadata can store any type
+    meta) {
+        const builder = new TransactionBuilder(this._state, this.binder);
+        const tr = builder.setAttribute(modelNode, key, value);
+        if (meta) {
+            for (const [k, v] of Object.entries(meta)) {
+                tr.setMeta(k, v);
+            }
         }
+        this.dispatch(tr);
     }
-    updateText(modelNode, text) {
-        if (!modelNode.cst)
-            throw new Error("Model node not linked to CST");
-        const patch = this.binder.calcUpdateTextPatch(modelNode, text);
-        if (patch) {
-            this.applyPatch(patch.start, patch.end, patch.text);
+    /**
+     * @deprecated Use `dispatch(new TransactionBuilder(engine.state, engine.binder).updateText(...))` instead.
+     */
+    updateText(modelNode, text, 
+    // biome-ignore lint/suspicious/noExplicitAny: Metadata can store any type
+    meta) {
+        const builder = new TransactionBuilder(this._state, this.binder);
+        const tr = builder.updateText(modelNode, text);
+        if (meta) {
+            for (const [k, v] of Object.entries(meta)) {
+                tr.setMeta(k, v);
+            }
         }
+        this.dispatch(tr);
     }
-    replaceNode(target, content) {
-        var _a;
-        if (!target.cst)
-            throw new Error("Model node not linked to CST");
-        // Formatting logic
-        let indentUnit = "  ";
-        let currentIndent = "";
-        if (target.cst) {
-            currentIndent = this.detectIndent(target.cst);
-            if ((_a = target.parent) === null || _a === void 0 ? void 0 : _a.cst) {
-                const parentIndent = this.detectIndent(target.parent.cst);
-                if (currentIndent.startsWith(parentIndent)) {
-                    const diff = currentIndent.slice(parentIndent.length);
-                    if (diff.length > 0 && !diff.includes("\n")) {
-                        indentUnit = diff;
-                    }
-                }
+    /**
+     * @deprecated Use `dispatch(new TransactionBuilder(engine.state, engine.binder).replaceNode(...))` instead.
+     */
+    replaceNode(target, content, 
+    // biome-ignore lint/suspicious/noExplicitAny: Metadata can store any type
+    meta) {
+        const builder = new TransactionBuilder(this._state, this.binder);
+        const tr = builder.replaceNode(target, content);
+        if (meta) {
+            for (const [k, v] of Object.entries(meta)) {
+                tr.setMeta(k, v);
             }
         }
-        const formatter = new formatter_1.Formatter({ indent: indentUnit });
-        let newXml = formatter.format(content);
-        if (currentIndent && newXml.includes("\n")) {
-            newXml = newXml
-                .split("\n")
-                .map((line, index) => (index === 0 ? line : currentIndent + line))
-                .join("\n");
-        }
-        const patch = this.binder.calcReplaceNodePatch(target, newXml);
-        if (patch) {
-            this.applyPatch(patch.start, patch.end, patch.text);
-        }
+        this.dispatch(tr);
     }
-    insertNode(parent, child, index) {
-        if (!parent.cst)
-            throw new Error("Parent node not linked to CST");
-        // Determine basic indentation (simplistic)
-        let indentUnit = "  ";
-        if (parent.cst) {
-            const parentIndent = this.detectIndent(parent.cst);
-            // Try to find a child to detect indent step
-            // ... skipping complex logic for now
-        }
-        const formatter = new formatter_1.Formatter({ indent: indentUnit });
-        const insertText = formatter.format(child);
-        const patch = this.binder.calcInsertNodePatch(parent, index, insertText);
-        if (patch) {
-            this.applyPatch(patch.start, patch.end, patch.text);
+    /**
+     * @deprecated Use `dispatch(new TransactionBuilder(engine.state, engine.binder).insertNode(...))` instead.
+     */
+    insertNode(parent, child, index, 
+    // biome-ignore lint/suspicious/noExplicitAny: Metadata can store any type
+    meta) {
+        const builder = new TransactionBuilder(this._state, this.binder);
+        const tr = builder.insertNode(parent, child, index);
+        if (meta) {
+            for (const [k, v] of Object.entries(meta)) {
+                tr.setMeta(k, v);
+            }
         }
+        this.dispatch(tr);
     }
-    removeNode(parent, child) {
-        if (!child.cst)
-            throw new Error("Target node not linked to CST");
-        const patch = this.binder.calcRemoveNodePatch(child);
-        if (patch) {
-            this.applyPatch(patch.start, patch.end, patch.text);
+    /**
+     * @deprecated Use `dispatch(new TransactionBuilder(engine.state, engine.binder).removeNode(...))` instead.
+     */
+    removeNode(parent, child, 
+    // biome-ignore lint/suspicious/noExplicitAny: Metadata can store any type
+    meta) {
+        const builder = new TransactionBuilder(this._state, this.binder);
+        const tr = builder.removeNode(parent, child);
+        if (meta) {
+            for (const [k, v] of Object.entries(meta)) {
+                tr.setMeta(k, v);
+            }
         }
+        this.dispatch(tr);
     }
     // --- Internal Logic ---
     fullParse() {
@@ -232,10 +272,19 @@ class SyncEngine {
             const cst = this.parser.parse(this._state.source);
             let model = null;
             if (cst === null || cst === void 0 ? void 0 : cst.wellFormed) {
-                // Hydrate full model
-                const newModel = this.binder.hydrate(cst);
-                if (newModel instanceof xml_api_model_1.ModelElement) {
-                    model = newModel;
+                if (this._state.model) {
+                    // Attempt to reconcile with existing model to preserve identity
+                    const result = this.binder.reconcile(this._state.model, cst);
+                    if (result.node instanceof ModelElement) {
+                        model = result.node;
+                    }
+                }
+                else {
+                    // Initial hydration
+                    const newModel = this.binder.hydrate(cst);
+                    if (newModel instanceof ModelElement) {
+                        model = newModel;
+                    }
                 }
             }
             this._state = this._state.update({ cst, model });
@@ -283,24 +332,28 @@ class SyncEngine {
         return null;
     }
     updateModelIncremental(oldNode, newNode, tr) {
+        var _a, _b;
         const currentModel = this._state.model;
         if (!currentModel)
-            return;
+            return false;
         if (currentModel.cst === oldNode) {
-            const newModelNode = this.binder.hydrate(newNode);
-            if (newModelNode instanceof xml_api_model_1.ModelElement) {
-                this._state = this._state.update({ model: newModelNode });
-                this.events.emit({
-                    type: "full",
-                    target: newModelNode,
-                    transaction: tr,
-                });
+            // Reconcile root to preserve identity
+            const result = this.binder.reconcile(currentModel, newNode);
+            const reconciled = result.node;
+            if (reconciled !== currentModel) {
+                this._state = this._state.update({ model: reconciled });
             }
-            return;
+            this.events.emit({
+                type: "full", // Or structure? Full implies root changed/updated
+                target: reconciled || undefined,
+                transaction: tr,
+            });
+            return true;
         }
         const modelPath = this.findModelNodePath(currentModel, oldNode);
         if (modelPath) {
-            const reconciledModel = this.binder.reconcile(modelPath.node, newNode);
+            const result = this.binder.reconcile(modelPath.node, newNode);
+            const reconciledModel = result.node;
             if (reconciledModel) {
                 if (reconciledModel !== modelPath.node) {
                     modelPath.parent.children[modelPath.index] = reconciledModel;
@@ -310,8 +363,14 @@ class SyncEngine {
                     type: "structure",
                     target: reconciledModel,
                     transaction: tr,
+                    addedNodes: (_a = result.diff) === null || _a === void 0 ? void 0 : _a.addedNodes,
+                    removedNodes: (_b = result.diff) === null || _b === void 0 ? void 0 : _b.removedNodes,
                 });
             }
+            return true;
+        }
+        else {
+            return false;
         }
     }
     // --- Helpers ---
@@ -354,7 +413,7 @@ class SyncEngine {
             if (child.cst === cstNode) {
                 return { parent: root, index: i, node: child };
             }
-            if (child instanceof xml_api_model_1.ModelElement) {
+            if (child instanceof ModelElement) {
                 const found = this.findModelNodePath(child, cstNode);
                 if (found)
                     return found;
@@ -383,19 +442,4 @@ class SyncEngine {
             current = current.parent;
         }
     }
-    detectIndent(node) {
-        const input = this._state.source;
-        let i = node.start - 1;
-        while (i >= 0) {
-            if (input[i] === "\n") {
-                return input.slice(i + 1, node.start);
-            }
-            if (input[i] !== " " && input[i] !== "\t") {
-                return "";
-            }
-            i--;
-        }
-        return "";
-    }
 }
-exports.SyncEngine = SyncEngine;

package/dist/engine/transaction-builder.d.ts

@@ -0,0 +1,14 @@
+import { type ModelElement, type ModelNode } from "../model/xml-api-model";
+import type { XMLBinder } from "../model/xml-binder";
+import type { EditorState } from "./editor-state";
+import { Transaction } from "./transaction";
+export declare class TransactionBuilder {
+    private state;
+    private binder;
+    constructor(state: EditorState, binder: XMLBinder);
+    setAttribute(modelNode: ModelElement, key: string, value: string): Transaction;
+    updateText(modelNode: ModelElement, text: string): Transaction;
+    removeNode(parent: ModelElement, child: ModelNode): Transaction;
+    replaceNode(target: ModelNode, content: ModelNode): Transaction;
+    insertNode(parent: ModelElement, child: ModelNode, index: number): Transaction;
+}

package/dist/engine/transaction-builder.js

@@ -0,0 +1,143 @@
+import { detectIndent } from "../cst/cst-utils";
+import { Formatter } from "../model/formatter";
+import { ModelText, } from "../model/xml-api-model";
+import { Transaction } from "./transaction";
+export class TransactionBuilder {
+    constructor(state, binder) {
+        this.state = state;
+        this.binder = binder;
+    }
+    setAttribute(modelNode, key, value) {
+        if (!modelNode.cst)
+            throw new Error("Model node not linked to CST");
+        const patch = this.binder.calcSetAttributePatch(modelNode, key, value);
+        const tr = new Transaction(this.state);
+        if (patch) {
+            tr.replace(patch.start, patch.end, patch.text);
+        }
+        return tr;
+    }
+    updateText(modelNode, text) {
+        if (!modelNode.cst)
+            throw new Error("Model node not linked to CST");
+        const patch = this.binder.calcUpdateTextPatch(modelNode, text);
+        const tr = new Transaction(this.state);
+        if (patch) {
+            tr.replace(patch.start, patch.end, patch.text);
+        }
+        return tr;
+    }
+    removeNode(parent, child) {
+        if (!parent.cst)
+            throw new Error("Parent node not linked to CST");
+        const patch = this.binder.calcRemoveNodePatch(child);
+        const tr = new Transaction(this.state);
+        if (patch) {
+            tr.replace(patch.start, patch.end, patch.text);
+        }
+        return tr;
+    }
+    replaceNode(target, content) {
+        var _a;
+        if (!target.cst)
+            throw new Error("Model node not linked to CST");
+        // Formatting logic
+        let indentUnit = "  ";
+        let currentIndent = "";
+        if (target.cst) {
+            currentIndent = detectIndent(target.cst, this.state.source) || "";
+            if ((_a = target.parent) === null || _a === void 0 ? void 0 : _a.cst) {
+                const parentIndent = detectIndent(target.parent.cst, this.state.source) || "";
+                if (currentIndent.startsWith(parentIndent)) {
+                    const diff = currentIndent.slice(parentIndent.length);
+                    if (diff.length > 0 && !diff.includes("\n")) {
+                        indentUnit = diff;
+                    }
+                }
+            }
+        }
+        const formatter = new Formatter({ indent: indentUnit });
+        let newXml = formatter.format(content);
+        if (currentIndent && newXml.includes("\n")) {
+            newXml = newXml
+                .split("\n")
+                .map((line, index) => (index === 0 ? line : currentIndent + line))
+                .join("\n");
+        }
+        const patch = this.binder.calcReplaceNodePatch(target, newXml);
+        const tr = new Transaction(this.state);
+        if (patch) {
+            tr.replace(patch.start, patch.end, patch.text);
+        }
+        return tr;
+    }
+    insertNode(parent, child, index) {
+        if (!parent.cst)
+            throw new Error("Parent node not linked to CST");
+        // Determine basic indentation
+        const indentUnit = "  ";
+        // Smart Formatting: Determine baseIndent and prefix/suffix
+        let baseIndent = "";
+        let prefix = "";
+        let suffix = "";
+        // Check if child is already in model (DOM usage)
+        const isAlreadyInModel = parent.children[index] === child;
+        // Scan backwards for significant node
+        let probe = isAlreadyInModel ? index - 1 : index - 1;
+        let refNode = null;
+        let newlineFound = false;
+        while (probe >= 0) {
+            const node = parent.children[probe];
+            if (node instanceof ModelText && node.text.trim().length === 0) {
+                if (node.text.includes("\n"))
+                    newlineFound = true;
+                probe--;
+            }
+            else {
+                refNode = node;
+                break;
+            }
+        }
+        if (refNode && refNode.formatting.indent !== null) {
+            baseIndent = refNode.formatting.indent;
+            prefix = newlineFound ? baseIndent : `\n${baseIndent}`;
+        }
+        else if (!refNode) {
+            // Empty or first significant child
+            // Check next sibling to decide mode
+            const nextNode = isAlreadyInModel
+                ? index + 1 < parent.children.length
+                    ? parent.children[index + 1]
+                    : null
+                : index < parent.children.length
+                    ? parent.children[index]
+                    : null;
+            if (nextNode && nextNode.formatting.indent === null) {
+                // Next is inline. Stay inline.
+            }
+            else {
+                // Next is block (or doesn't exist).
+                // If parent has indent, assume block.
+                if (parent.formatting.indent !== null) {
+                    baseIndent = parent.formatting.indent + indentUnit;
+                    prefix = `\n${baseIndent}`;
+                }
+            }
+        }
+        // Suffix logic: ensure closing tag is on new line if block mode
+        // If we are appending at the end, or next is end-tag
+        // Simple heuristic: if we added a newline prefix (block mode), add a newline suffix
+        if (prefix.includes("\n") || newlineFound) {
+            // Use parent's indent for the closing tag
+            suffix = `\n${parent.formatting.indent || ""}`;
+        }
+        const formatter = new Formatter({ indent: indentUnit, baseIndent });
+        const insertText = prefix + formatter.format(child) + suffix;
+        const patch = this.binder.calcInsertNodePatch(parent, index, insertText);
+        const tr = new Transaction(this.state);
+        if (patch) {
+            tr.replace(patch.start, patch.end, patch.text);
+        }
+        return tr;
+    }
+}

package/dist/engine/transaction.d.ts

@@ -14,7 +14,10 @@ export declare class Transaction {
     docChanged: boolean;
     /** Indicates if this transaction originated from a remote source (collaboration). */
     isRemote: boolean;
+    metadata: Map<string, any>;
     constructor(startState: EditorState);
+    setMeta(key: string, value: any): this;
+    getMeta(key: string): any;
     /**
      * Adds a text change to the transaction.
      * @param from Start index

package/dist/engine/transaction.js

@@ -1,20 +1,25 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Transaction = void 0;
 /**
  * Represents a unit of change to the editor state.
  * Currently focuses on text changes (patches).
  */
-class Transaction {
-    // Placeholder for future selection and metadata
-    // public selection: Selection | null = null;
-    // public meta: Map<string, any> = new Map();
+export class Transaction {
     constructor(startState) {
         this.startState = startState;
         this.patches = [];
         this.docChanged = false;
         /** Indicates if this transaction originated from a remote source (collaboration). */
         this.isRemote = false;
+        // biome-ignore lint/suspicious/noExplicitAny: Metadata can store any type
+        this.metadata = new Map();
+    }
+    // biome-ignore lint/suspicious/noExplicitAny: Metadata can store any type
+    setMeta(key, value) {
+        this.metadata.set(key, value);
+        return this;
+    }
+    // biome-ignore lint/suspicious/noExplicitAny: Metadata can store any type
+    getMeta(key) {
+        return this.metadata.get(key);
     }
     /**
      * Adds a text change to the transaction.
@@ -49,4 +54,3 @@ class Transaction {
         return source;
     }
 }
-exports.Transaction = Transaction;

package/dist/history-manager.d.ts

@@ -1,4 +1,5 @@
 export interface Transaction {
+    timestamp: number;
     redo: {
         from: number;
         to: number;
@@ -14,8 +15,11 @@ export declare class HistoryManager {
     private undoStack;
     private redoStack;
     private maxHistory;
+    private mergeThreshold;
     constructor(maxHistory?: number);
     push(transaction: Transaction): void;
+    private shouldMerge;
+    private merge;
     undo(): Transaction | null;
     redo(): Transaction | null;
     canUndo(): boolean;