@miy2/xml-api 0.9.0

package/dist/dom.d.ts

@@ -0,0 +1,172 @@
+import { ModelElement, type ModelNode } from "./model/xml-api-model";
+/**
+ * Observer interface to listen for changes in the DOM-like structure.
+ * This is crucial for synchronizing the visual representation or application model
+ * back to the source code via the XMLAPI.
+ *
+ * @example
+ * ```typescript
+ * const doc = new Document();
+ * doc.setObserver({
+ *   onAttributeChange: (element, name, value) => {
+ *     console.log(`Attribute ${name} changed to ${value}`);
+ *     // Sync with XMLAPI...
+ *   },
+ *   // ...
+ * });
+ * ```
+ */
+export interface DOMObserver {
+    /**
+     * Called when an attribute is added, changed, or removed.
+     * @param element The target element.
+     * @param name Attribute name.
+     * @param value New value, or null if removed.
+     */
+    onAttributeChange(element: Element, name: string, value: string | null): void;
+    /**
+     * Called when the text content of a node changes.
+     * @param node The target CharacterData node (Text, Comment, CDATA).
+     * @param text The new text content.
+     */
+    onTextChange(node: CharacterData, text: string): void;
+    /**
+     * Called when the text content of an Element changes (replacing all children).
+     * @param element The target Element.
+     * @param text The new text content.
+     */
+    onElementTextChange(element: Element, text: string): void;
+    /**
+     * Called when a child node is added.
+     * @param parent The parent node.
+     * @param child The added child node.
+     * @param index The index at which the child was added.
+     */
+    onChildAdded(parent: Node, child: Node, index: number): void;
+    /**
+     * Called when a child node is removed.
+     * @param parent The parent node.
+     * @param child The removed child node.
+     * @param index The index from which the child was removed.
+     */
+    onChildRemoved(parent: Node, child: Node, index: number): void;
+}
+/**
+ * Base class for all DOM nodes.
+ * Implements a subset of the W3C Node interface to allow applications
+ * to interact with the XML model using familiar methods.
+ */
+export declare abstract class Node {
+    protected model: ModelNode;
+    ownerDocument: Document | null;
+    readonly ELEMENT_NODE = 1;
+    readonly TEXT_NODE = 3;
+    readonly CDATA_SECTION_NODE = 4;
+    readonly COMMENT_NODE = 8;
+    readonly DOCUMENT_NODE = 9;
+    constructor(model: ModelNode, ownerDocument: Document | null);
+    abstract get nodeType(): number;
+    abstract get nodeName(): string;
+    /**
+     * Returns the parent of this node.
+     */
+    get parentNode(): Node | null;
+    /**
+     * Returns a NodeList containing all children of this node.
+     */
+    get childNodes(): NodeList;
+    get firstChild(): Node | null;
+    get lastChild(): Node | null;
+    get nextSibling(): Node | null;
+    get previousSibling(): Node | null;
+    get textContent(): string | null;
+    set textContent(value: string | null);
+    /**
+     * Adds a node to the end of the list of children of a specified parent node.
+     * @param newChild The node to append.
+     */
+    appendChild<T extends Node>(newChild: T): T;
+    /**
+     * Inserts a node before a reference node as a child of this node.
+     * @param newChild The node to insert.
+     * @param refChild The reference node (must be a child of this node).
+     */
+    insertBefore<T extends Node>(newChild: T, refChild: Node | null): T;
+    /**
+     * Removes a child node from the DOM and returns the removed node.
+     * @param child The child node to remove.
+     */
+    removeChild<T extends Node>(child: T): T;
+    getModel(): ModelNode;
+}
+export declare class NodeList extends Array<Node> {
+    constructor(items: Node[]);
+    item(index: number): Node | null;
+}
+/**
+ * Base class for Text, Comment, and CDATASection nodes.
+ */
+export declare abstract class CharacterData extends Node {
+    get data(): string;
+    set data(value: string);
+    get length(): number;
+}
+export declare class Text extends CharacterData {
+    get nodeType(): number;
+    get nodeName(): string;
+}
+export declare class Comment extends CharacterData {
+    get nodeType(): number;
+    get nodeName(): string;
+}
+export declare class CDATASection extends CharacterData {
+    get nodeType(): number;
+    get nodeName(): string;
+}
+/**
+ * Represents an element in the XML document.
+ */
+export declare class Element extends Node {
+    protected model: ModelElement;
+    constructor(model: ModelElement, ownerDocument: Document | null);
+    get nodeType(): number;
+    get nodeName(): string;
+    get tagName(): string;
+    get prefix(): string | null;
+    get localName(): string;
+    get namespaceURI(): string | null;
+    getAttribute(name: string): string | null;
+    setAttribute(name: string, value: string): void;
+    removeAttribute(name: string): void;
+    hasAttribute(name: string): boolean;
+    querySelector(selector: string): Element | null;
+    querySelectorAll(selector: string): NodeList;
+}
+/**
+ * Represents the entire XML document.
+ */
+export declare class Document extends Node {
+    private _documentElement;
+    private observer;
+    constructor();
+    /**
+     * Sets the observer to listen for DOM changes.
+     */
+    setObserver(observer: DOMObserver): void;
+    notifyAttributeChange(element: Element, name: string, value: string | null): void;
+    notifyTextChange(node: CharacterData, text: string): void;
+    notifyElementTextChange(element: Element, text: string): void;
+    notifyChildAdded(parent: Node, child: Node, index: number): void;
+    notifyChildRemoved(parent: Node, child: Node, index: number): void;
+    get nodeType(): number;
+    get nodeName(): string;
+    get documentElement(): Element | null;
+    set documentElement(element: Element | null);
+    createElement(tagName: string): Element;
+    createTextNode(data: string): Text;
+    createComment(data: string): Comment;
+    createCDATASection(data: string): CDATASection;
+    querySelector(selector: string): Element | null;
+    querySelectorAll(selector: string): NodeList;
+}
+export declare function createWrapper(model: ModelNode, doc: Document | null): Node;

package/dist/dom.js

@@ -0,0 +1,415 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Document = exports.Element = exports.CDATASection = exports.Comment = exports.Text = exports.CharacterData = exports.NodeList = exports.Node = void 0;
+exports.createWrapper = createWrapper;
+const xml_api_model_1 = require("./model/xml-api-model");
+/**
+ * Base class for all DOM nodes.
+ * Implements a subset of the W3C Node interface to allow applications
+ * to interact with the XML model using familiar methods.
+ */
+class Node {
+    constructor(model, ownerDocument) {
+        this.model = model;
+        this.ownerDocument = ownerDocument;
+        this.ELEMENT_NODE = 1;
+        this.TEXT_NODE = 3;
+        this.CDATA_SECTION_NODE = 4;
+        this.COMMENT_NODE = 8;
+        this.DOCUMENT_NODE = 9;
+    }
+    /**
+     * Returns the parent of this node.
+     */
+    get parentNode() {
+        if (!this.model.parent)
+            return null;
+        return createWrapper(this.model.parent, this.ownerDocument);
+    }
+    /**
+     * Returns a NodeList containing all children of this node.
+     */
+    get childNodes() {
+        if (this.model instanceof xml_api_model_1.ModelElement) {
+            return new NodeList(this.model.children.map((c) => createWrapper(c, this.ownerDocument)));
+        }
+        return new NodeList([]);
+    }
+    get firstChild() {
+        const nodes = this.childNodes;
+        return nodes.length > 0 ? nodes.item(0) : null;
+    }
+    get lastChild() {
+        const nodes = this.childNodes;
+        return nodes.length > 0 ? nodes.item(nodes.length - 1) : null;
+    }
+    get nextSibling() {
+        const parent = this.model.parent;
+        if (!parent)
+            return null;
+        const index = parent.children.indexOf(this.model);
+        if (index >= 0 && index < parent.children.length - 1) {
+            return createWrapper(parent.children[index + 1], this.ownerDocument);
+        }
+        return null;
+    }
+    get previousSibling() {
+        const parent = this.model.parent;
+        if (!parent)
+            return null;
+        const index = parent.children.indexOf(this.model);
+        if (index > 0) {
+            return createWrapper(parent.children[index - 1], this.ownerDocument);
+        }
+        return null;
+    }
+    get textContent() {
+        if (this.model instanceof xml_api_model_1.ModelText)
+            return this.model.text;
+        if (this.model instanceof xml_api_model_1.ModelComment)
+            return this.model.content;
+        if (this.model instanceof xml_api_model_1.ModelCDATA)
+            return this.model.content;
+        if (this.model instanceof xml_api_model_1.ModelElement) {
+            return this.model.children
+                .map((c) => createWrapper(c, this.ownerDocument).textContent)
+                .join("");
+        }
+        return null;
+    }
+    set textContent(value) {
+        var _a, _b, _c, _d;
+        const val = value || "";
+        if (this.model instanceof xml_api_model_1.ModelText) {
+            this.model.text = val;
+            (_a = this.ownerDocument) === null || _a === void 0 ? void 0 : _a.notifyTextChange(this, val);
+        }
+        else if (this.model instanceof xml_api_model_1.ModelComment) {
+            this.model.content = val;
+            (_b = this.ownerDocument) === null || _b === void 0 ? void 0 : _b.notifyTextChange(this, val);
+        }
+        else if (this.model instanceof xml_api_model_1.ModelCDATA) {
+            this.model.content = val;
+            (_c = this.ownerDocument) === null || _c === void 0 ? void 0 : _c.notifyTextChange(this, val);
+        }
+        else if (this.model instanceof xml_api_model_1.ModelElement) {
+            this.model.children = [];
+            if (val) {
+                const textNode = new xml_api_model_1.ModelText(val);
+                this.model.addChild(textNode);
+            }
+            (_d = this.ownerDocument) === null || _d === void 0 ? void 0 : _d.notifyElementTextChange(this, val);
+        }
+    }
+    /**
+     * Adds a node to the end of the list of children of a specified parent node.
+     * @param newChild The node to append.
+     */
+    appendChild(newChild) {
+        var _a;
+        if (this.model instanceof xml_api_model_1.ModelElement) {
+            this.model.addChild(newChild.getModel());
+            // @ts-ignore
+            newChild.ownerDocument = this.ownerDocument;
+            (_a = this.ownerDocument) === null || _a === void 0 ? void 0 : _a.notifyChildAdded(this, newChild, this.model.children.length - 1);
+            return newChild;
+        }
+        throw new Error("HierarchyRequestError");
+    }
+    /**
+     * Inserts a node before a reference node as a child of this node.
+     * @param newChild The node to insert.
+     * @param refChild The reference node (must be a child of this node).
+     */
+    insertBefore(newChild, refChild) {
+        var _a;
+        if (this.model instanceof xml_api_model_1.ModelElement) {
+            if (!refChild) {
+                return this.appendChild(newChild);
+            }
+            const refModel = refChild.getModel();
+            const index = this.model.children.indexOf(refModel);
+            if (index === -1)
+                throw new Error("NotFoundError");
+            // Update Model
+            this.model.children.splice(index, 0, newChild.getModel());
+            newChild.getModel().parent = this.model;
+            // @ts-ignore
+            newChild.ownerDocument = this.ownerDocument;
+            (_a = this.ownerDocument) === null || _a === void 0 ? void 0 : _a.notifyChildAdded(this, newChild, index);
+            return newChild;
+        }
+        throw new Error("HierarchyRequestError");
+    }
+    /**
+     * Removes a child node from the DOM and returns the removed node.
+     * @param child The child node to remove.
+     */
+    removeChild(child) {
+        var _a;
+        if (this.model instanceof xml_api_model_1.ModelElement) {
+            const childModel = child.getModel();
+            const index = this.model.children.indexOf(childModel);
+            if (index === -1)
+                throw new Error("NotFoundError");
+            // Update Model
+            this.model.children.splice(index, 1);
+            childModel.parent = null;
+            (_a = this.ownerDocument) === null || _a === void 0 ? void 0 : _a.notifyChildRemoved(this, child, index);
+            return child;
+        }
+        throw new Error("HierarchyRequestError");
+    }
+    // Internal access
+    getModel() {
+        return this.model;
+    }
+}
+exports.Node = Node;
+class NodeList extends Array {
+    constructor(items) {
+        super(...items);
+        Object.setPrototypeOf(this, NodeList.prototype);
+    }
+    item(index) {
+        return this[index] || null;
+    }
+}
+exports.NodeList = NodeList;
+/**
+ * Base class for Text, Comment, and CDATASection nodes.
+ */
+class CharacterData extends Node {
+    get data() {
+        return this.textContent || "";
+    }
+    set data(value) {
+        this.textContent = value;
+    }
+    get length() {
+        return this.data.length;
+    }
+}
+exports.CharacterData = CharacterData;
+class Text extends CharacterData {
+    get nodeType() {
+        return this.TEXT_NODE;
+    }
+    get nodeName() {
+        return "#text";
+    }
+}
+exports.Text = Text;
+class Comment extends CharacterData {
+    get nodeType() {
+        return this.COMMENT_NODE;
+    }
+    get nodeName() {
+        return "#comment";
+    }
+}
+exports.Comment = Comment;
+class CDATASection extends CharacterData {
+    get nodeType() {
+        return this.CDATA_SECTION_NODE;
+    }
+    get nodeName() {
+        return "#cdata-section";
+    }
+}
+exports.CDATASection = CDATASection;
+/**
+ * Represents an element in the XML document.
+ */
+class Element extends Node {
+    constructor(model, ownerDocument) {
+        super(model, ownerDocument);
+        this.model = model;
+    }
+    get nodeType() {
+        return this.ELEMENT_NODE;
+    }
+    get nodeName() {
+        return this.model.tagName;
+    }
+    get tagName() {
+        return this.model.tagName;
+    }
+    get prefix() {
+        const parts = this.model.tagName.split(":");
+        return parts.length > 1 ? parts[0] : null;
+    }
+    get localName() {
+        const parts = this.model.tagName.split(":");
+        return parts.length > 1 ? parts[1] : parts[0];
+    }
+    get namespaceURI() {
+        const prefix = this.prefix;
+        const xmlnsKey = prefix ? `xmlns:${prefix}` : "xmlns";
+        let current = this.model;
+        while (current) {
+            if (current.attributes.has(xmlnsKey)) {
+                return current.attributes.get(xmlnsKey) || null;
+            }
+            current = current.parent;
+        }
+        return null;
+    }
+    getAttribute(name) {
+        var _a;
+        return (_a = this.model.attributes.get(name)) !== null && _a !== void 0 ? _a : null;
+    }
+    setAttribute(name, value) {
+        var _a;
+        this.model.attributes.set(name, value);
+        (_a = this.ownerDocument) === null || _a === void 0 ? void 0 : _a.notifyAttributeChange(this, name, value);
+    }
+    removeAttribute(name) {
+        var _a;
+        this.model.attributes.delete(name);
+        (_a = this.ownerDocument) === null || _a === void 0 ? void 0 : _a.notifyAttributeChange(this, name, null);
+    }
+    hasAttribute(name) {
+        return this.model.attributes.has(name);
+    }
+    querySelector(selector) {
+        const results = [];
+        querySelectorAllRecursive(this, selector, results);
+        return results.length > 0 ? results[0] : null;
+    }
+    querySelectorAll(selector) {
+        const results = [];
+        querySelectorAllRecursive(this, selector, results);
+        return new NodeList(results);
+    }
+}
+exports.Element = Element;
+/**
+ * Represents the entire XML document.
+ */
+class Document extends Node {
+    constructor() {
+        // Document doesn't strictly have a ModelNode parent in this simplified architecture
+        // Or it could wrap a "root" ModelElement
+        // For now, we'll create a dummy root model or handle it differently
+        super(new xml_api_model_1.ModelElement("#document"), null);
+        this._documentElement = null;
+        this.observer = null;
+        this.ownerDocument = this; // Document owns itself
+    }
+    /**
+     * Sets the observer to listen for DOM changes.
+     */
+    setObserver(observer) {
+        this.observer = observer;
+    }
+    notifyAttributeChange(element, name, value) {
+        var _a;
+        (_a = this.observer) === null || _a === void 0 ? void 0 : _a.onAttributeChange(element, name, value);
+    }
+    notifyTextChange(node, text) {
+        var _a;
+        (_a = this.observer) === null || _a === void 0 ? void 0 : _a.onTextChange(node, text);
+    }
+    notifyElementTextChange(element, text) {
+        var _a;
+        (_a = this.observer) === null || _a === void 0 ? void 0 : _a.onElementTextChange(element, text);
+    }
+    notifyChildAdded(parent, child, index) {
+        var _a;
+        (_a = this.observer) === null || _a === void 0 ? void 0 : _a.onChildAdded(parent, child, index);
+    }
+    notifyChildRemoved(parent, child, index) {
+        var _a;
+        (_a = this.observer) === null || _a === void 0 ? void 0 : _a.onChildRemoved(parent, child, index);
+    }
+    get nodeType() {
+        return this.DOCUMENT_NODE;
+    }
+    get nodeName() {
+        return "#document";
+    }
+    get documentElement() {
+        return this._documentElement;
+    }
+    // Not standard, but needed for initialization
+    set documentElement(element) {
+        this._documentElement = element;
+        if (element) {
+            // Ensure the element is part of the document structure
+            // In a real DOM, documentElement is a child of Document
+            // Here, we just link them logically
+            // @ts-ignore
+            element.ownerDocument = this;
+        }
+    }
+    createElement(tagName) {
+        return new Element(new xml_api_model_1.ModelElement(tagName), this);
+    }
+    createTextNode(data) {
+        return new Text(new xml_api_model_1.ModelText(data), this);
+    }
+    createComment(data) {
+        return new Comment(new xml_api_model_1.ModelComment(data), this);
+    }
+    createCDATASection(data) {
+        return new CDATASection(new xml_api_model_1.ModelCDATA(data), this);
+    }
+    querySelector(selector) {
+        if (!this.documentElement)
+            return null;
+        return this.documentElement.querySelector(selector);
+    }
+    querySelectorAll(selector) {
+        if (!this.documentElement)
+            return new NodeList([]);
+        return this.documentElement.querySelectorAll(selector);
+    }
+}
+exports.Document = Document;
+// Helper factory
+function createWrapper(model, doc) {
+    if (model instanceof xml_api_model_1.ModelElement)
+        return new Element(model, doc);
+    if (model instanceof xml_api_model_1.ModelText)
+        return new Text(model, doc);
+    if (model instanceof xml_api_model_1.ModelComment)
+        return new Comment(model, doc);
+    if (model instanceof xml_api_model_1.ModelCDATA)
+        return new CDATASection(model, doc);
+    throw new Error(`Unknown model type: ${model.getType()}`);
+}
+function matchSelector(el, selector) {
+    // Very basic selector engine
+    if (selector.startsWith("#")) {
+        return el.getAttribute("id") === selector.slice(1);
+    }
+    if (selector.startsWith(".")) {
+        const className = el.getAttribute("class");
+        return className
+            ? className.split(/\s+/).includes(selector.slice(1))
+            : false;
+    }
+    if (selector.startsWith("[") && selector.endsWith("]")) {
+        const parts = selector.slice(1, -1).split("=");
+        const key = parts[0];
+        const val = parts[1] ? parts[1].replace(/['"]/g, "") : null;
+        const attr = el.getAttribute(key);
+        return val ? attr === val : attr !== null;
+    }
+    // Tag name
+    return el.tagName === selector || selector === "*";
+}
+function querySelectorAllRecursive(root, selector, results) {
+    // Check self (if not root of query? Standard querySelectorAll doesn't match root usually, but here we traverse children)
+    // Actually querySelectorAll searches *descendants*.
+    const children = root.childNodes;
+    for (const child of children) {
+        if (child instanceof Element) {
+            if (matchSelector(child, selector)) {
+                results.push(child);
+            }
+            querySelectorAllRecursive(child, selector, results);
+        }
+    }
+}

package/dist/engine/editor-state.d.ts

@@ -0,0 +1,22 @@
+import type { CST } from "../cst/xml-cst";
+import type { ModelElement } from "../model/xml-api-model";
+export interface EditorStateConfig {
+    source: string;
+    model: ModelElement | null;
+    cst: CST | null;
+}
+/**
+ * Represents a snapshot of the editor state at a specific point in time.
+ * Includes the source code, the logical model, and the physical CST.
+ */
+export declare class EditorState {
+    readonly source: string;
+    readonly model: ModelElement | null;
+    readonly cst: CST | null;
+    constructor(config: EditorStateConfig);
+    /**
+     * Creates a new state with updated properties.
+     */
+    update(changes: Partial<EditorStateConfig>): EditorState;
+    static create(source: string): EditorState;
+}

package/dist/engine/editor-state.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EditorState = void 0;
+/**
+ * Represents a snapshot of the editor state at a specific point in time.
+ * Includes the source code, the logical model, and the physical CST.
+ */
+class EditorState {
+    constructor(config) {
+        this.source = config.source;
+        this.model = config.model;
+        this.cst = config.cst;
+    }
+    /**
+     * Creates a new state with updated properties.
+     */
+    update(changes) {
+        return new EditorState({
+            source: changes.source !== undefined ? changes.source : this.source,
+            model: changes.model !== undefined ? changes.model : this.model,
+            cst: changes.cst !== undefined ? changes.cst : this.cst,
+        });
+    }
+    static create(source) {
+        return new EditorState({
+            source,
+            model: null,
+            cst: null,
+        });
+    }
+}
+exports.EditorState = EditorState;

package/dist/engine/sync-engine.d.ts

@@ -0,0 +1,55 @@
+import type { Grammar } from "../cst/grammar";
+import type { CST } from "../cst/xml-cst";
+import { ModelElement, type ModelNode } from "../model/xml-api-model";
+import { type EventHandler } from "../xml-api-events";
+import type { CollabBridge } from "../collab/bridge";
+import { EditorState } from "./editor-state";
+import { Transaction } from "./transaction";
+export declare class SyncEngine {
+    private _state;
+    private parser;
+    private binder;
+    private history;
+    private events;
+    private isTransacting;
+    private collabBridge;
+    constructor(source: string, grammar?: Grammar);
+    get state(): EditorState;
+    get source(): string;
+    get model(): ModelElement | null;
+    get cst(): CST | null;
+    get grammar(): Grammar;
+    setCollabBridge(bridge: CollabBridge): void;
+    /**
+     * Subscribe to model changes.
+     */
+    on(handler: EventHandler): () => void;
+    /**
+     * Applies a transaction to the engine, updating the state and notifying listeners.
+     */
+    dispatch(tr: Transaction): void;
+    /**
+     * Update the source code (e.g. from text editor).
+     * Handles history recording and incremental parsing.
+     */
+    updateSource(from: number, to: number, text: string): void;
+    /**
+     * Apply a programmatic change derived from Model operations.
+     * This is the "Application -> Source" flow.
+     */
+    applyPatch(start: number, end: number, text: string): void;
+    undo(): void;
+    redo(): void;
+    setAttribute(modelNode: ModelElement, key: string, value: string): void;
+    updateText(modelNode: ModelElement, text: string): void;
+    replaceNode(target: ModelNode, content: ModelNode): void;
+    insertNode(parent: ModelElement, child: ModelNode, index: number): void;
+    removeNode(parent: ModelElement, child: ModelNode): void;
+    private fullParse;
+    private tryIncrementalUpdate;
+    private updateModelIncremental;
+    private findNodeAt;
+    private findModelNodePath;
+    private updateAncestorsWellFormed;
+    private detectIndent;
+}