@miy2/xml-api 0.9.0 → 0.9.1

package/dist/view/schema-view.d.ts

@@ -0,0 +1,80 @@
+import { Document, Element, type Node } from "../dom";
+import type { SyncEngine } from "../engine/sync-engine";
+import type { Transaction } from "../engine/transaction";
+import { ModelElement, type ModelNode } from "../model/xml-api-model";
+import { type ExternalNode } from "./view-binder";
+export interface SchemaViewConfig {
+    filter?: (node: ModelNode) => boolean;
+}
+export type ViewChangeEvent = {
+    type: "full";
+    target?: Node;
+    transaction?: Transaction;
+} | {
+    type: "structure";
+    target: Node;
+    transaction?: Transaction;
+    addedNodes?: Node[];
+    removedNodes?: Node[];
+} | {
+    type: "attribute";
+    target: Node;
+    key: string;
+    newValue: string | null;
+    transaction?: Transaction;
+} | {
+    type: "text";
+    target: Node;
+    newValue?: string;
+    transaction?: Transaction;
+};
+/**
+ * A filtered, schema-specific projection of the document.
+ *
+ * The SchemaView provides a "view" of the underlying Model that only contains nodes relevant
+ * to a specific schema (e.g., XHTML). It hides "invisible" nodes (like comments, processing instructions,
+ * or tags not in the allowed list) but preserves them in the Model during updates.
+ *
+ * This enables applications (like WYSIWYG editors) to work with a simplified DOM structure
+ * without destroying the full fidelity of the original source code.
+ */
+export declare class SchemaView {
+    private model;
+    private engine;
+    private config;
+    private document;
+    private events;
+    private currentMeta;
+    constructor(model: ModelElement, engine: SyncEngine, config?: SchemaViewConfig);
+    private initDocument;
+    /**
+     * Subscribes to changes in the view.
+     *
+     * Events emitted here are "projected" events:
+     * - They only fire for nodes visible in this view.
+     * - `target` nodes are View nodes (wrappers), not raw Model nodes.
+     * - Structure events (`addedNodes`/`removedNodes`) are filtered to exclude invisible nodes.
+     *
+     * @param handler Function to handle the events.
+     * @returns Unsubscribe function.
+     */
+    on(handler: (event: ViewChangeEvent) => void): () => void;
+    private handleEngineEvent;
+    getDocument(): Document;
+    getRoot(): Element;
+    getNodeByModelId(id: string): Node | null;
+    getModelNode(viewNode: Node): ModelNode;
+    /**
+     * Reconciles an external DOM tree (e.g., from a browser's contentEditable) with this view.
+     *
+     * This method calculates the differences between the external tree and the current view,
+     * then applies minimal updates to the underlying Model. Crucially, it respects the
+     * "Invisible Node Preservation" rule: if the external tree is missing a node that is hidden
+     * in this view (like a comment), that node is preserved in the Model.
+     *
+     * @param externalDomNode The root of the external DOM tree to sync from.
+     * @param meta Optional metadata to attach to the generated transaction.
+     * @param target Optional specific element to reconcile (defaults to view root).
+     */
+    reconcile(externalDomNode: ExternalNode, meta?: Record<string, any>, target?: Element): void;
+}

package/dist/view/schema-view.js

@@ -0,0 +1,222 @@
+import { createWrapper, Document, Element, } from "../dom";
+import { ModelCDATA, ModelComment, ModelElement, ModelText, } from "../model/xml-api-model";
+import { EventEmitter } from "../xml-api-events";
+import { ViewBinder } from "./view-binder";
+/**
+ * A filtered, schema-specific projection of the document.
+ *
+ * The SchemaView provides a "view" of the underlying Model that only contains nodes relevant
+ * to a specific schema (e.g., XHTML). It hides "invisible" nodes (like comments, processing instructions,
+ * or tags not in the allowed list) but preserves them in the Model during updates.
+ *
+ * This enables applications (like WYSIWYG editors) to work with a simplified DOM structure
+ * without destroying the full fidelity of the original source code.
+ */
+export class SchemaView {
+    constructor(model, engine, config = {}) {
+        this.model = model;
+        this.engine = engine;
+        this.config = config;
+        this.events = new EventEmitter();
+        // biome-ignore lint/suspicious/noExplicitAny: Metadata can store any type
+        this.currentMeta = { origin: "schema-view" };
+        this.initDocument();
+        this.engine.on(this.handleEngineEvent.bind(this));
+    }
+    initDocument() {
+        this.document = new Document();
+        if (this.config.filter) {
+            this.document.nodeFilter = this.config.filter;
+        }
+        const rootWrapper = createWrapper(this.model, this.document);
+        if (rootWrapper instanceof Element) {
+            this.document.documentElement = rootWrapper;
+        }
+        this.document.setObserver({
+            onAttributeChange: (element, name, value) => {
+                const model = element.getModel();
+                if (model instanceof ModelElement && model.cst) {
+                    if (value !== null) {
+                        this.engine.setAttribute(model, name, value, this.currentMeta);
+                    }
+                }
+            },
+            onChildAdded: (parent, child, index) => {
+                const parentModel = parent.getModel();
+                const childModel = child.getModel();
+                if (parentModel instanceof ModelElement && parentModel.cst) {
+                    this.engine.insertNode(parentModel, childModel, index, this.currentMeta);
+                }
+            },
+            onChildRemoved: (parent, child, _index) => {
+                const parentModel = parent.getModel();
+                const childModel = child.getModel();
+                if (parentModel instanceof ModelElement && parentModel.cst) {
+                    if (childModel.cst) {
+                        this.engine.removeNode(parentModel, childModel, this.currentMeta);
+                    }
+                }
+            },
+            onChildReplaced: (_parent, newChild, oldChild) => {
+                const newModel = newChild.getModel();
+                const oldModel = oldChild.getModel();
+                if (oldModel.cst) {
+                    this.engine.replaceNode(oldModel, newModel, this.currentMeta);
+                }
+            },
+            onTextChange: (node, text) => {
+                const modelNode = node.getModel();
+                if (modelNode instanceof ModelText && modelNode.cst) {
+                    const newTextNode = new ModelText(text);
+                    this.engine.replaceNode(modelNode, newTextNode, this.currentMeta);
+                }
+                else if (modelNode instanceof ModelComment && modelNode.cst) {
+                    const newComment = new ModelComment(text);
+                    this.engine.replaceNode(modelNode, newComment, this.currentMeta);
+                }
+                else if (modelNode instanceof ModelCDATA && modelNode.cst) {
+                    const newCDATA = new ModelCDATA(text);
+                    this.engine.replaceNode(modelNode, newCDATA, this.currentMeta);
+                }
+                else {
+                    console.warn("Direct text node update not supported for this node or missing CST");
+                }
+            },
+            onElementTextChange: (element, text) => {
+                const model = element.getModel();
+                if (model instanceof ModelElement && model.cst) {
+                    this.engine.updateText(model, text, this.currentMeta);
+                }
+            },
+        });
+    }
+    /**
+     * Subscribes to changes in the view.
+     *
+     * Events emitted here are "projected" events:
+     * - They only fire for nodes visible in this view.
+     * - `target` nodes are View nodes (wrappers), not raw Model nodes.
+     * - Structure events (`addedNodes`/`removedNodes`) are filtered to exclude invisible nodes.
+     *
+     * @param handler Function to handle the events.
+     * @returns Unsubscribe function.
+     */
+    on(handler) {
+        return this.events.on(handler);
+    }
+    handleEngineEvent(event) {
+        // Ignore events that originated from this view (or any SchemaView)
+        // Ideally we should check if it's *this specific* view, but for now 'schema-view' covers self-cycles.
+        if (event.transaction &&
+            event.transaction.getMeta("origin") === "schema-view") {
+            return;
+        }
+        if (event.type === "full") {
+            // Update local model reference from engine if root changed
+            if (this.engine.model) {
+                this.model = this.engine.model;
+                this.initDocument();
+            }
+            this.events.emit({ type: "full", transaction: event.transaction });
+            return;
+        }
+        if (!event.target)
+            return;
+        // Check if target is visible in view
+        // getNodeByModelId does the filtering check
+        const viewNode = this.getNodeByModelId(event.target.id);
+        if (viewNode) {
+            // Map event
+            if (event.type === "structure") {
+                const addedViewNodes = [];
+                if (event.addedNodes) {
+                    for (const mNode of event.addedNodes) {
+                        if (this.document.accepts(mNode)) {
+                            addedViewNodes.push(createWrapper(mNode, this.document));
+                        }
+                    }
+                }
+                const removedViewNodes = [];
+                if (event.removedNodes) {
+                    for (const mNode of event.removedNodes) {
+                        if (this.document.accepts(mNode)) {
+                            removedViewNodes.push(createWrapper(mNode, this.document));
+                        }
+                    }
+                }
+                this.events.emit({
+                    type: "structure",
+                    target: viewNode,
+                    transaction: event.transaction,
+                    addedNodes: addedViewNodes,
+                    removedNodes: removedViewNodes,
+                });
+            }
+            else if (event.type === "attribute") {
+                this.events.emit({
+                    type: "attribute",
+                    target: viewNode,
+                    key: event.key,
+                    newValue: event.newValue,
+                    transaction: event.transaction,
+                });
+            }
+            else if (event.type === "text") {
+                this.events.emit({
+                    type: "text",
+                    target: viewNode,
+                    newValue: event.newValue,
+                    transaction: event.transaction,
+                });
+            }
+        }
+    }
+    getDocument() {
+        return this.document;
+    }
+    getRoot() {
+        if (!this.document.documentElement) {
+            throw new Error("No root element in view");
+        }
+        return this.document.documentElement;
+    }
+    getNodeByModelId(id) {
+        const modelNode = this.model.findNodeById(id);
+        if (!modelNode)
+            return null;
+        if (!this.document.accepts(modelNode))
+            return null;
+        return createWrapper(modelNode, this.document);
+    }
+    getModelNode(viewNode) {
+        return viewNode.getModel();
+    }
+    /**
+     * Reconciles an external DOM tree (e.g., from a browser's contentEditable) with this view.
+     *
+     * This method calculates the differences between the external tree and the current view,
+     * then applies minimal updates to the underlying Model. Crucially, it respects the
+     * "Invisible Node Preservation" rule: if the external tree is missing a node that is hidden
+     * in this view (like a comment), that node is preserved in the Model.
+     *
+     * @param externalDomNode The root of the external DOM tree to sync from.
+     * @param meta Optional metadata to attach to the generated transaction.
+     * @param target Optional specific element to reconcile (defaults to view root).
+     */
+    reconcile(externalDomNode, 
+    // biome-ignore lint/suspicious/noExplicitAny: Metadata can store any type
+    meta, target) {
+        const previousMeta = this.currentMeta;
+        if (meta) {
+            this.currentMeta = { ...this.currentMeta, ...meta };
+        }
+        try {
+            const binder = new ViewBinder(this.document);
+            // The external node corresponds to the root of the view (or the provided target)
+            binder.reconcile(externalDomNode, target || this.getRoot());
+        }
+        finally {
+            this.currentMeta = previousMeta;
+        }
+    }
+}

package/dist/view/view-binder.d.ts

@@ -0,0 +1,47 @@
+import type { Document as ApiDocument, Element as ApiElement } from "../dom";
+export interface ExternalNode {
+    nodeType: number;
+    nodeName: string;
+    textContent: string | null;
+    childNodes: ArrayLike<ExternalNode>;
+    attributes?: ArrayLike<{
+        name: string;
+        value: string;
+    }>;
+}
+/**
+ * Interface for logic that reconciles an external DOM tree with the internal document.
+ */
+export interface Reconciler {
+    /**
+     * Reconciles the internal element's children to match the external node's children.
+     */
+    reconcile(externalNode: ExternalNode, internalElement: ApiElement): void;
+}
+/**
+ * Handles the logic of reconciling a SchemaView (filtered DOM) with an external source
+ * (like a browser DOM in a contentEditable editor).
+ *
+ * Its primary responsibility is to apply changes from the external source to the internal
+ * SchemaView DOM without destroying data that the external source doesn't know about.
+ *
+ * Key Feature: Preservation of "Invisible" Nodes.
+ * If the Model contains "formatting whitespace" or other nodes that are present in the
+ * internal view but "invisible" or collapsed in the external view, the ViewBinder
+ * detects this and skips/preserves them instead of treating their absence as a deletion.
+ */
+export declare class ViewBinder implements Reconciler {
+    private document;
+    constructor(document: ApiDocument);
+    reconcile(externalNode: ExternalNode, internalElement: ApiElement): void;
+    private isSameType;
+    private updateNode;
+    private createFromExternal;
+    /**
+     * Checks if a node is "formatting whitespace" that should be preserved during sync,
+     * even if it is missing from the external view.
+     *
+     * This relies on the Model's classification of text nodes (e.g. `kind: 'whitespace'`).
+     */
+    private isPreservableWhitespace;
+}

package/dist/view/view-binder.js

@@ -0,0 +1,163 @@
+import { ModelText } from "../model/xml-api-model";
+const IGNORED_ATTRIBUTES = new Set(["data-model-id"]);
+/**
+ * Handles the logic of reconciling a SchemaView (filtered DOM) with an external source
+ * (like a browser DOM in a contentEditable editor).
+ *
+ * Its primary responsibility is to apply changes from the external source to the internal
+ * SchemaView DOM without destroying data that the external source doesn't know about.
+ *
+ * Key Feature: Preservation of "Invisible" Nodes.
+ * If the Model contains "formatting whitespace" or other nodes that are present in the
+ * internal view but "invisible" or collapsed in the external view, the ViewBinder
+ * detects this and skips/preserves them instead of treating their absence as a deletion.
+ */
+export class ViewBinder {
+    constructor(document) {
+        this.document = document;
+    }
+    reconcile(externalNode, internalElement) {
+        const bChildren = Array.from(externalNode.childNodes);
+        const vChildrenSnapshot = Array.from(internalElement.childNodes);
+        let bI = 0;
+        let vI = 0;
+        while (bI < bChildren.length || vI < vChildrenSnapshot.length) {
+            const bNode = bChildren[bI];
+            const vNode = vChildrenSnapshot[vI];
+            // Case 1: External exhausted
+            if (!bNode && vNode) {
+                // If vNode is formatting whitespace, preserve it.
+                if (this.isPreservableWhitespace(vNode)) {
+                    vI++;
+                    continue;
+                }
+                // Otherwise, it was removed externally.
+                internalElement.removeChild(vNode);
+                vI++;
+                continue;
+            }
+            // Case 2: Internal exhausted
+            if (bNode && !vNode) {
+                const newNode = this.createFromExternal(bNode);
+                if (newNode)
+                    internalElement.appendChild(newNode);
+                bI++;
+                continue;
+            }
+            // Case 3: Both exist
+            if (this.isPreservableWhitespace(vNode)) {
+                // If vNode is formatting whitespace, and bNode is an Element,
+                // we skip the whitespace to find the matching Element.
+                if (bNode.nodeType === 1) {
+                    vI++;
+                    continue;
+                }
+            }
+            if (this.isSameType(bNode, vNode)) {
+                this.updateNode(vNode, bNode);
+                if (bNode.nodeType === 1) {
+                    // Element: recurse
+                    this.reconcile(bNode, vNode);
+                }
+                bI++;
+                vI++;
+            }
+            else {
+                // Type mismatch
+                // If vNode was whitespace, we already handled it above.
+                // So this is a real mismatch (e.g. p vs div, or text vs element).
+                // Remove vNode (unless preservable - already checked)
+                // Check again just in case (redundant but safe)
+                if (this.isPreservableWhitespace(vNode)) {
+                    vI++;
+                    continue;
+                }
+                internalElement.removeChild(vNode);
+                vI++;
+                // Retry bNode against next vNode
+            }
+        }
+    }
+    isSameType(bNode, vNode) {
+        if (bNode.nodeType === 3 && vNode.nodeType === 3)
+            return true; // Text
+        if (bNode.nodeType === 1 && vNode.nodeType === 1) {
+            // Element
+            return (bNode.nodeName.toLowerCase() ===
+                vNode.tagName.toLowerCase());
+        }
+        return false;
+    }
+    updateNode(vNode, bNode) {
+        if (vNode.nodeType === 3) {
+            // Text
+            const newVal = bNode.textContent || "";
+            if (vNode.textContent !== newVal) {
+                vNode.textContent = newVal;
+            }
+        }
+        else if (vNode.nodeType === 1) {
+            // Element
+            const vEl = vNode;
+            // Attributes
+            if (bNode.attributes) {
+                // 1. Update/Add
+                for (let j = 0; j < bNode.attributes.length; j++) {
+                    const attr = bNode.attributes[j];
+                    if (IGNORED_ATTRIBUTES.has(attr.name))
+                        continue;
+                    if (vEl.getAttribute(attr.name) !== attr.value) {
+                        vEl.setAttribute(attr.name, attr.value);
+                    }
+                }
+                // 2. Remove missing (optional, might want to preserve attributes not in external view?
+                // But if external view is authoritative for the allowed schema, maybe we should remove?
+                // WYSIWYGEditor implementation didn't explicitly remove attributes.
+                // But it synced attributes one way.
+                // Let's stick to update/add for now to be safe, or check TODO.
+                // TODO doesn't specify attribute removal policy.
+                // But standard reconciliation usually implies full sync.
+                // I will assume strictly what is in bNode is what we want, BUT we must be careful about "invisible" attributes?
+                // SchemaView might filter attributes? No, SchemaView filter is on Nodes.
+                // So I'll stick to what WYSIWYGEditor did: only setAttribute.
+            }
+        }
+    }
+    createFromExternal(bNode) {
+        if (bNode.nodeType === 3) {
+            return this.document.createTextNode(bNode.textContent || "");
+        }
+        else if (bNode.nodeType === 1) {
+            const vNew = this.document.createElement(bNode.nodeName.toLowerCase());
+            if (bNode.attributes) {
+                for (let j = 0; j < bNode.attributes.length; j++) {
+                    const attrName = bNode.attributes[j].name;
+                    if (IGNORED_ATTRIBUTES.has(attrName))
+                        continue;
+                    vNew.setAttribute(attrName, bNode.attributes[j].value);
+                }
+            }
+            const children = bNode.childNodes;
+            for (let k = 0; k < children.length; k++) {
+                const child = this.createFromExternal(children[k]);
+                if (child)
+                    vNew.appendChild(child);
+            }
+            return vNew;
+        }
+        return null;
+    }
+    /**
+     * Checks if a node is "formatting whitespace" that should be preserved during sync,
+     * even if it is missing from the external view.
+     *
+     * This relies on the Model's classification of text nodes (e.g. `kind: 'whitespace'`).
+     */
+    isPreservableWhitespace(node) {
+        const model = node.getModel();
+        if (model instanceof ModelText) {
+            return model.kind === "whitespace";
+        }
+        return false;
+    }
+}

package/dist/xml-api-events.d.ts

@@ -11,6 +11,10 @@ export type ChangeEvent = {
     type: "structure";
     target: ModelNode;
     transaction?: Transaction;
+    addedNodes?: ModelNode[];
+    removedNodes?: ModelNode[];
+    previousSibling?: ModelNode | null;
+    nextSibling?: ModelNode | null;
 } | {
     type: "attribute";
     target: ModelNode;
@@ -30,14 +34,14 @@ export type EventHandler = (event: ChangeEvent) => void;
 /**
  * Internal event emitter for managing listeners.
  */
-export declare class EventEmitter {
+export declare class EventEmitter<E = ChangeEvent> {
     private listeners;
     /**
      * Registers an event handler.
      * @param handler The callback function.
      * @returns A function to unsubscribe the handler.
      */
-    on(handler: EventHandler): () => void;
-    off(handler: EventHandler): void;
-    emit(event: ChangeEvent): void;
+    on(handler: (event: E) => void): () => void;
+    off(handler: (event: E) => void): void;
+    emit(event: E): void;
 }

package/dist/xml-api-events.js

@@ -1,10 +1,7 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.EventEmitter = void 0;
 /**
  * Internal event emitter for managing listeners.
  */
-class EventEmitter {
+export class EventEmitter {
     constructor() {
         this.listeners = [];
     }
@@ -26,4 +23,3 @@ class EventEmitter {
         }
     }
 }
-exports.EventEmitter = EventEmitter;

package/dist/xml-api.d.ts

@@ -1,14 +1,21 @@
-import { Document } from "./dom";
 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 { Document } from "./dom";
+import { SyncEngine } from "./engine/sync-engine";
+import { ModelElement } from "./model/xml-api-model";
+import { SchemaView, type SchemaViewConfig } from "./view/schema-view";
+import type { EventHandler } from "./xml-api-events";
 /**
  * The primary entry point for the XML API.
- * Orchestrates the synchronization between source code (CST) and the logical Model.
+ * Orchestrates the synchronization between source code (CST), the logical Model, and Schema Views.
+ *
+ * This class serves as the central hub for the "Three-Level Reconciliation" architecture:
+ * 1. Source <-> CST: Incremental parsing.
+ * 2. CST <-> Model: Logical binding and identity preservation.
+ * 3. Model <-> View: Schema projection and filtering (via `createView`).
  */
 export declare class XMLAPI {
-    private engine;
+    private _engine;
     private document;
     /**
      * Initializes the API with the source XML string.
@@ -16,32 +23,36 @@ export declare class XMLAPI {
      * @param grammar (Optional) Custom grammar definition.
      */
     constructor(source: string, grammar?: Grammar);
+    /** The underlying synchronization engine. */
+    get engine(): SyncEngine;
     /** The current source code string. */
     get source(): string;
-    /**
-     * Alias for `source` to maintain compatibility with existing tests/demos temporarily.
-     * @deprecated Use `source` instead.
-     */
-    get input(): string;
     /** The authoritative logical model. */
     get model(): ModelElement | null;
     /** The Concrete Syntax Tree (Physical layer). */
     get cst(): CST | null;
     /** The grammar used for parsing. */
     get grammar(): Grammar;
+    /**
+     * Creates a projected view of the document.
+     *
+     * A SchemaView allows you to work with a filtered subset of the document (e.g., only XHTML tags)
+     * while the underlying system maintains full fidelity of the original source (including comments,
+     * custom tags, and formatting) in the background.
+     *
+     * @param config Configuration for the view, including filter logic.
+     * @returns A `SchemaView` instance providing a DOM-like interface for the projected content.
+     */
+    createView(config?: SchemaViewConfig): SchemaView;
     /**
      * Updates the source code directly (e.g. from a text editor).
      * Attempts an optimized incremental update, falling back to full re-parse if needed.
      * @param from Start index of the range to replace.
      * @param to End index of the range.
      * @param text The new text to insert.
+     * @param meta (Optional) Metadata for the transaction.
      */
-    updateSource(from: number, to: number, text: string): void;
-    /**
-     * Alias for `updateSource` to maintain compatibility.
-     * @deprecated Use `updateSource` instead.
-     */
-    updateInput(from: number, to: number, text: string): void;
+    updateSource(from: number, to: number, text: string, meta?: Record<string, any>): void;
     /**
      * Returns a DOM-compatible Document object linked to this API.
      * Changes made to the returned Document are automatically reflected in the source code.
@@ -53,10 +64,13 @@ export declare class XMLAPI {
     on(handler: EventHandler): () => void;
     undo(): void;
     redo(): void;
-    /** @deprecated Use DOM interface or Engine directly if needed. */
-    setAttribute(modelNode: ModelElement, key: string, value: string): void;
-    /** @deprecated Use DOM interface or Engine directly if needed. */
-    updateText(modelNode: ModelElement, text: string): void;
-    /** @deprecated Use DOM interface or Engine directly if needed. */
-    replaceNode(target: ModelNode, content: ModelNode): void;
 }
+export { CST } from "./cst/xml-cst";
+export { CDATASection, Comment, Document, Element, Node, NodeList, Text, } from "./dom";
+export { EditorState } from "./engine/editor-state";
+export { type TextPatch, Transaction } from "./engine/transaction";
+export { ModelCDATA, ModelComment, ModelElement, ModelNode, ModelNodeType, ModelText, } from "./model/xml-api-model";
+export { XMLBinder } from "./model/xml-binder";
+export { SchemaView, type SchemaViewConfig } from "./view/schema-view";
+export { type ExternalNode, ViewBinder } from "./view/view-binder";
+export { type ChangeEvent, EventEmitter, type EventHandler, } from "./xml-api-events";