@miy2/xml-api 0.9.0

package/dist/model/xml-schema.d.ts

@@ -0,0 +1,9 @@
+export interface ElementDefinition {
+    name: string;
+    isVoid?: boolean;
+}
+export declare class XMLSchema {
+    private elements;
+    constructor(definitions?: ElementDefinition[]);
+    isVoid(tagName: string): boolean;
+}

package/dist/model/xml-schema.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.XMLSchema = void 0;
+class XMLSchema {
+    constructor(definitions = []) {
+        this.elements = new Map();
+        for (const def of definitions) {
+            this.elements.set(def.name, def);
+        }
+    }
+    isVoid(tagName) {
+        var _a, _b;
+        return (_b = (_a = this.elements.get(tagName)) === null || _a === void 0 ? void 0 : _a.isVoid) !== null && _b !== void 0 ? _b : false;
+    }
+}
+exports.XMLSchema = XMLSchema;

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

@@ -0,0 +1,43 @@
+import type { Transaction } from "./engine/transaction";
+import type { ModelNode } from "./model/xml-api-model";
+/**
+ * Event object emitted when the XML model changes.
+ */
+export type ChangeEvent = {
+    type: "full";
+    target?: ModelNode;
+    transaction?: Transaction;
+} | {
+    type: "structure";
+    target: ModelNode;
+    transaction?: Transaction;
+} | {
+    type: "attribute";
+    target: ModelNode;
+    key: string;
+    newValue: string | null;
+    transaction?: Transaction;
+} | {
+    type: "text";
+    target: ModelNode;
+    newValue?: string;
+    transaction?: Transaction;
+};
+/**
+ * Callback function for handling change events.
+ */
+export type EventHandler = (event: ChangeEvent) => void;
+/**
+ * Internal event emitter for managing listeners.
+ */
+export declare class EventEmitter {
+    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;
+}

package/dist/xml-api-events.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EventEmitter = void 0;
+/**
+ * Internal event emitter for managing listeners.
+ */
+class EventEmitter {
+    constructor() {
+        this.listeners = [];
+    }
+    /**
+     * Registers an event handler.
+     * @param handler The callback function.
+     * @returns A function to unsubscribe the handler.
+     */
+    on(handler) {
+        this.listeners.push(handler);
+        return () => this.off(handler);
+    }
+    off(handler) {
+        this.listeners = this.listeners.filter((h) => h !== handler);
+    }
+    emit(event) {
+        for (const handler of this.listeners) {
+            handler(event);
+        }
+    }
+}
+exports.EventEmitter = EventEmitter;

package/dist/xml-api.d.ts

@@ -0,0 +1,62 @@
+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";
+/**
+ * The primary entry point for the XML API.
+ * Orchestrates the synchronization between source code (CST) and the logical Model.
+ */
+export declare class XMLAPI {
+    private engine;
+    private document;
+    /**
+     * Initializes the API with the source XML string.
+     * @param source The initial XML source code.
+     * @param grammar (Optional) Custom grammar definition.
+     */
+    constructor(source: string, grammar?: Grammar);
+    /** 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;
+    /**
+     * 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.
+     */
+    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;
+    /**
+     * Returns a DOM-compatible Document object linked to this API.
+     * Changes made to the returned Document are automatically reflected in the source code.
+     */
+    getDocument(): Document;
+    /**
+     * Registers an event handler to listen for model changes.
+     */
+    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;
+}

package/dist/xml-api.js

@@ -0,0 +1,152 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.XMLAPI = void 0;
+const dom_1 = require("./dom");
+const sync_engine_1 = require("./engine/sync-engine");
+const xml_api_model_1 = require("./model/xml-api-model");
+/**
+ * The primary entry point for the XML API.
+ * Orchestrates the synchronization between source code (CST) and the logical Model.
+ */
+class XMLAPI {
+    /**
+     * Initializes the API with the source XML string.
+     * @param source The initial XML source code.
+     * @param grammar (Optional) Custom grammar definition.
+     */
+    constructor(source, grammar) {
+        this.document = null;
+        this.engine = new sync_engine_1.SyncEngine(source, grammar);
+    }
+    // --- Read-only State Access ---
+    /** The current source code string. */
+    get source() {
+        return this.engine.source;
+    }
+    /**
+     * Alias for `source` to maintain compatibility with existing tests/demos temporarily.
+     * @deprecated Use `source` instead.
+     */
+    get input() {
+        return this.engine.source;
+    }
+    /** The authoritative logical model. */
+    get model() {
+        return this.engine.model;
+    }
+    /** The Concrete Syntax Tree (Physical layer). */
+    get cst() {
+        return this.engine.cst;
+    }
+    /** The grammar used for parsing. */
+    get grammar() {
+        return this.engine.grammar;
+    }
+    // --- Operations ---
+    /**
+     * 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.
+     */
+    updateSource(from, to, text) {
+        this.engine.updateSource(from, to, text);
+    }
+    /**
+     * Alias for `updateSource` to maintain compatibility.
+     * @deprecated Use `updateSource` instead.
+     */
+    updateInput(from, to, text) {
+        this.updateSource(from, to, text);
+    }
+    /**
+     * Returns a DOM-compatible Document object linked to this API.
+     * Changes made to the returned Document are automatically reflected in the source code.
+     */
+    getDocument() {
+        if (this.document)
+            return this.document;
+        const doc = new dom_1.Document();
+        this.document = doc;
+        if (this.model) {
+            const rootWrapper = (0, dom_1.createWrapper)(this.model, doc);
+            if (rootWrapper instanceof dom_1.Element) {
+                doc.documentElement = rootWrapper;
+            }
+        }
+        // Set up observer to sync DOM changes back to Source via Engine
+        doc.setObserver({
+            onAttributeChange: (element, name, value) => {
+                const model = element.getModel();
+                if (model instanceof xml_api_model_1.ModelElement) {
+                    if (value === null) {
+                        // Attribute removal support needed in Engine/Binder
+                        console.warn("Attribute removal not fully supported yet");
+                    }
+                    else {
+                        this.engine.setAttribute(model, name, value);
+                    }
+                }
+            },
+            onTextChange: (node, text) => {
+                // Direct text update on CharacterData
+                // Need to find parent element to update properly or support direct node replacement
+                // For now, simple text node update via parent if available
+                // But Engine expects ModelElement for updateText.
+                // Actually, replacing the node is better.
+                // Or implement updateTextNode in Engine.
+                console.warn("Direct CharacterData update not yet supported via Observer");
+            },
+            onElementTextChange: (element, text) => {
+                const model = element.getModel();
+                if (model instanceof xml_api_model_1.ModelElement) {
+                    this.engine.updateText(model, text);
+                }
+            },
+            onChildAdded: (parent, child, index) => {
+                const parentModel = parent.getModel();
+                const childModel = child.getModel();
+                if (parentModel instanceof xml_api_model_1.ModelElement) {
+                    this.engine.insertNode(parentModel, childModel, index);
+                }
+            },
+            onChildRemoved: (parent, child, index) => {
+                const parentModel = parent.getModel();
+                const childModel = child.getModel();
+                if (parentModel instanceof xml_api_model_1.ModelElement) {
+                    this.engine.removeNode(parentModel, childModel);
+                }
+            },
+        });
+        return doc;
+    }
+    // --- Subscriptions ---
+    /**
+     * Registers an event handler to listen for model changes.
+     */
+    on(handler) {
+        return this.engine.on(handler);
+    }
+    // --- History ---
+    undo() {
+        this.engine.undo();
+    }
+    redo() {
+        this.engine.redo();
+    }
+    // --- Advanced/Legacy Operation Shortcuts (Proxy to Engine) ---
+    /** @deprecated Use DOM interface or Engine directly if needed. */
+    setAttribute(modelNode, key, value) {
+        this.engine.setAttribute(modelNode, key, value);
+    }
+    /** @deprecated Use DOM interface or Engine directly if needed. */
+    updateText(modelNode, text) {
+        this.engine.updateText(modelNode, text);
+    }
+    /** @deprecated Use DOM interface or Engine directly if needed. */
+    replaceNode(target, content) {
+        this.engine.replaceNode(target, content);
+    }
+}
+exports.XMLAPI = XMLAPI;

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@miy2/xml-api",
+  "version": "0.9.0",
+  "description": "An XML library that faithfully synchronizes documents and AST.",
+  "main": "dist/xml-api.js",
+  "exports": {
+    ".": {
+      "types": "./dist/xml-api.d.ts",
+      "default": "./dist/xml-api.js"
+    },
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "default": "./dist/*.js"
+    }
+  },
+  "types": "dist/xml-api.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "typecheck": "tsc --noEmit",
+    "docs:typecheck": "vue-tsc --noEmit -p docs/tsconfig.json",
+    "test": "jest",
+    "test:all": "jest",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:gen-api": "typedoc && ts-node scripts/generate-sidebar.ts",
+    "docs:preview": "vitepress preview docs",
+    "format": "biome format --write ."
+  },
+  "keywords": [
+    "xml",
+    "ast",
+    "code",
+    "parser"
+  ],
+  "author": "Kazuya Miyashita <miy1924@gmail.com> (https://miy2.com/)",
+  "license": "MIT",
+  "packageManager": "pnpm@10.23.0",
+  "devDependencies": {
+    "@biomejs/biome": "2.3.13",
+    "@types/jest": "^30.0.0",
+    "@types/jsdom": "^27.0.0",
+    "@types/node": "^25.0.10",
+    "esbuild": "^0.27.2",
+    "jest": "^30.2.0",
+    "jsdom": "^27.4.0",
+    "mermaid": "^11.12.2",
+    "ts-jest": "^29.4.6",
+    "ts-node": "^10.9.2",
+    "typedoc": "^0.28.16",
+    "typedoc-plugin-markdown": "^4.9.0",
+    "typescript": "^5.9.3",
+    "vitepress": "^1.6.4",
+    "vitepress-plugin-mermaid": "^2.0.17",
+    "vue": "^3.5.27",
+    "vue-tsc": "^3.2.4"
+  }
+}