@adaas/are-html 0.0.2

package/dist/node/engine/AreHTML.context.d.mts

@@ -0,0 +1,108 @@
+import { AreContext, AreNode, AreInstruction } from '@adaas/are';
+import { AreHTMLContextConstructor } from './AreHTML.types.mjs';
+
+declare class AreHTMLEngineContext extends AreContext {
+    /**
+     * Index structure mapping:
+     *
+     *        Node                ->       Group ID        ->  Element
+     * -----------------------------------------------------------------------------------
+     *  | - Attribute             |   group: string       |   Node
+     *  | - Directive (e.g. for)  |                       |   Node
+     */
+    protected index: {
+        /**
+         * 1 AreNode = 1 Dom Node
+         *
+         * uses ASEID
+         */
+        nodeToHostElements: Map<string, Node>;
+        /**
+         * 1 Group Instruction = MANY Dom Nodes (e.g. for loop)
+         *
+         * uses ASEID
+         */
+        groupToElements: Map<string, Set<Node>>;
+        /**
+         * 1 Dom Node = 1 Instruction
+         *
+         * uses ASEID
+         */
+        elementToInstruction: WeakMap<Node, string>;
+        /**
+         * 1 Instruction = 1 Dom Node (for CreateElement instructions, for example)
+         *
+         * uses ASEID
+         */
+        instructionToElement: Map<string, Node>;
+        /**
+         * Event listeners attached to elements, used for proper cleanup when reverting instructions. Maps a DOM element to a map of event names and their corresponding listeners, allowing the engine to track which listeners are attached to which elements and remove them when necessary (e.g., when an instruction is reverted).
+         */
+        elementListeners: WeakMap<Node, Map<string, EventListenerOrEventListenerObject>>;
+    };
+    /**
+     * The root container for the HTML engine, which can be either a Document or a ShadowRoot. This is where the engine will mount the generated DOM elements. The context uses this container to manage the relationship between AreNodes, instructions, and their corresponding DOM elements, allowing for efficient updates and cleanups as the application state changes.
+     */
+    protected _container: Document;
+    constructor(props: Partial<AreHTMLContextConstructor>);
+    get container(): Document;
+    /**
+     * Retrieves the DOM element associated with a given AreNode. This method looks up the node's ASEID in the nodeToHostElements map to find the corresponding DOM element. If the node is not found, it returns undefined. This allows the engine to efficiently access and manipulate the DOM elements that correspond to specific nodes in the AreNode tree, enabling dynamic updates and interactions based on the application state.
+     *
+     * @param nodeASEID
+     */
+    getNodeElement(nodeASEID: string): Node | undefined;
+    getNodeElement(node: AreNode): Node | undefined;
+    /**
+     * Associates a DOM element with a given instruction and its owner node. This method updates the context's index to map the instruction's ASEID to the provided DOM element, and also maps the element back to the instruction's ASEID for reverse lookup. If the instruction has an owner node, it also maps the node's ASEID to the element. Additionally, if the instruction belongs to a group, it adds the element to the set of elements associated with that group. This indexing allows the engine to efficiently manage and update DOM elements based on instructions and their corresponding nodes, enabling dynamic rendering and interaction in response to application state changes.
+     *
+     * @param instruction
+     * @param element
+     */
+    setInstructionElement(instruction: AreInstruction, element: Node): void;
+    /**
+     * Retrieves the DOM element associated with a given instruction. This method looks up the instruction's ASEID in the instructionToElement map to find the corresponding DOM element. If the instruction is not found, it returns undefined. This allows the engine to efficiently access and manipulate the DOM elements that correspond to specific instructions, enabling dynamic updates and interactions based on the application state.
+     *
+     * @param instructionASEID
+     */
+    getElementByInstruction(instructionASEID: string): Node | undefined;
+    getElementByInstruction(instruction: AreInstruction): Node | undefined;
+    /**
+     * Removes the association between a given instruction and its corresponding DOM element. This method looks up the instruction's ASEID to find the associated DOM element, and if found, it deletes the mapping from both instructionToElement and elementToInstruction. If the instruction has an owner node, it also removes the mapping from nodeToHostElements. Additionally, if the instruction belongs to a group, it removes the element from the set of elements associated with that group, and if the group has no more elements, it deletes the group from the index. This cleanup is essential for maintaining an accurate and efficient mapping of instructions to DOM elements, especially when instructions are reverted or when nodes are removed from the DOM.
+     *
+     * @param instruction
+     */
+    removeInstructionElement(instruction: AreInstruction): void;
+    /**
+     * Retrieves the set of DOM elements associated with a given group. This method looks up the group name or instruction's ASEID in the groupToElements map to find the corresponding set of DOM elements. If the group is not found, it returns undefined. This allows the engine to efficiently access and manipulate all DOM elements that belong to a specific group (e.g., all elements generated by a particular loop instruction), enabling dynamic updates and interactions based on the application state.
+     *
+     * @param groupName
+     */
+    getElementsByGroup(groupName: string): Set<Node> | undefined;
+    getElementsByGroup(instruction: AreInstruction): Set<Node> | undefined;
+    /**
+     * Adds an event listener to a specific DOM element and keeps track of it in the context's index for proper cleanup later. This method takes a DOM element, an event name, and a listener function or object, and stores this information in the elementListeners map. This allows the engine to efficiently manage event listeners attached to dynamically created elements, ensuring that they can be removed when the associated instructions are reverted or when nodes are removed from the DOM, preventing memory leaks and unintended behavior.
+     *
+     * @param element
+     * @param eventName
+     * @param listener
+     */
+    addListener(element: Node, eventName: string, listener: EventListenerOrEventListenerObject): void;
+    /**
+     * Retrieves the event listener associated with a specific DOM element and event name from the context's index. This method looks up the element in the elementListeners map and then retrieves the listener for the specified event name. If no listener is found for the given element and event, it returns undefined. This allows the engine to efficiently access and manage event listeners that have been attached to dynamically created elements, enabling proper cleanup when instructions are reverted or when nodes are removed from the DOM.
+     *
+     * @param element
+     * @param eventName
+     * @returns
+     */
+    getListener(element: Node, eventName: string): EventListenerOrEventListenerObject | undefined;
+    /**
+     * Removes an event listener from a specific DOM element and updates the context's index accordingly. This method looks up the element in the elementListeners map and deletes the listener for the specified event name. This is typically called when an instruction is reverted or when a node is removed from the DOM, ensuring that any attached event listeners are properly cleaned up to prevent memory leaks and unintended behavior.
+     *
+     * @param element
+     * @param eventName
+     */
+    removeListener(element: Node, eventName: string): void;
+}
+
+export { AreHTMLEngineContext };

package/dist/node/engine/AreHTML.context.d.ts

@@ -0,0 +1,108 @@
+import { AreContext, AreNode, AreInstruction } from '@adaas/are';
+import { AreHTMLContextConstructor } from './AreHTML.types.js';
+
+declare class AreHTMLEngineContext extends AreContext {
+    /**
+     * Index structure mapping:
+     *
+     *        Node                ->       Group ID        ->  Element
+     * -----------------------------------------------------------------------------------
+     *  | - Attribute             |   group: string       |   Node
+     *  | - Directive (e.g. for)  |                       |   Node
+     */
+    protected index: {
+        /**
+         * 1 AreNode = 1 Dom Node
+         *
+         * uses ASEID
+         */
+        nodeToHostElements: Map<string, Node>;
+        /**
+         * 1 Group Instruction = MANY Dom Nodes (e.g. for loop)
+         *
+         * uses ASEID
+         */
+        groupToElements: Map<string, Set<Node>>;
+        /**
+         * 1 Dom Node = 1 Instruction
+         *
+         * uses ASEID
+         */
+        elementToInstruction: WeakMap<Node, string>;
+        /**
+         * 1 Instruction = 1 Dom Node (for CreateElement instructions, for example)
+         *
+         * uses ASEID
+         */
+        instructionToElement: Map<string, Node>;
+        /**
+         * Event listeners attached to elements, used for proper cleanup when reverting instructions. Maps a DOM element to a map of event names and their corresponding listeners, allowing the engine to track which listeners are attached to which elements and remove them when necessary (e.g., when an instruction is reverted).
+         */
+        elementListeners: WeakMap<Node, Map<string, EventListenerOrEventListenerObject>>;
+    };
+    /**
+     * The root container for the HTML engine, which can be either a Document or a ShadowRoot. This is where the engine will mount the generated DOM elements. The context uses this container to manage the relationship between AreNodes, instructions, and their corresponding DOM elements, allowing for efficient updates and cleanups as the application state changes.
+     */
+    protected _container: Document;
+    constructor(props: Partial<AreHTMLContextConstructor>);
+    get container(): Document;
+    /**
+     * Retrieves the DOM element associated with a given AreNode. This method looks up the node's ASEID in the nodeToHostElements map to find the corresponding DOM element. If the node is not found, it returns undefined. This allows the engine to efficiently access and manipulate the DOM elements that correspond to specific nodes in the AreNode tree, enabling dynamic updates and interactions based on the application state.
+     *
+     * @param nodeASEID
+     */
+    getNodeElement(nodeASEID: string): Node | undefined;
+    getNodeElement(node: AreNode): Node | undefined;
+    /**
+     * Associates a DOM element with a given instruction and its owner node. This method updates the context's index to map the instruction's ASEID to the provided DOM element, and also maps the element back to the instruction's ASEID for reverse lookup. If the instruction has an owner node, it also maps the node's ASEID to the element. Additionally, if the instruction belongs to a group, it adds the element to the set of elements associated with that group. This indexing allows the engine to efficiently manage and update DOM elements based on instructions and their corresponding nodes, enabling dynamic rendering and interaction in response to application state changes.
+     *
+     * @param instruction
+     * @param element
+     */
+    setInstructionElement(instruction: AreInstruction, element: Node): void;
+    /**
+     * Retrieves the DOM element associated with a given instruction. This method looks up the instruction's ASEID in the instructionToElement map to find the corresponding DOM element. If the instruction is not found, it returns undefined. This allows the engine to efficiently access and manipulate the DOM elements that correspond to specific instructions, enabling dynamic updates and interactions based on the application state.
+     *
+     * @param instructionASEID
+     */
+    getElementByInstruction(instructionASEID: string): Node | undefined;
+    getElementByInstruction(instruction: AreInstruction): Node | undefined;
+    /**
+     * Removes the association between a given instruction and its corresponding DOM element. This method looks up the instruction's ASEID to find the associated DOM element, and if found, it deletes the mapping from both instructionToElement and elementToInstruction. If the instruction has an owner node, it also removes the mapping from nodeToHostElements. Additionally, if the instruction belongs to a group, it removes the element from the set of elements associated with that group, and if the group has no more elements, it deletes the group from the index. This cleanup is essential for maintaining an accurate and efficient mapping of instructions to DOM elements, especially when instructions are reverted or when nodes are removed from the DOM.
+     *
+     * @param instruction
+     */
+    removeInstructionElement(instruction: AreInstruction): void;
+    /**
+     * Retrieves the set of DOM elements associated with a given group. This method looks up the group name or instruction's ASEID in the groupToElements map to find the corresponding set of DOM elements. If the group is not found, it returns undefined. This allows the engine to efficiently access and manipulate all DOM elements that belong to a specific group (e.g., all elements generated by a particular loop instruction), enabling dynamic updates and interactions based on the application state.
+     *
+     * @param groupName
+     */
+    getElementsByGroup(groupName: string): Set<Node> | undefined;
+    getElementsByGroup(instruction: AreInstruction): Set<Node> | undefined;
+    /**
+     * Adds an event listener to a specific DOM element and keeps track of it in the context's index for proper cleanup later. This method takes a DOM element, an event name, and a listener function or object, and stores this information in the elementListeners map. This allows the engine to efficiently manage event listeners attached to dynamically created elements, ensuring that they can be removed when the associated instructions are reverted or when nodes are removed from the DOM, preventing memory leaks and unintended behavior.
+     *
+     * @param element
+     * @param eventName
+     * @param listener
+     */
+    addListener(element: Node, eventName: string, listener: EventListenerOrEventListenerObject): void;
+    /**
+     * Retrieves the event listener associated with a specific DOM element and event name from the context's index. This method looks up the element in the elementListeners map and then retrieves the listener for the specified event name. If no listener is found for the given element and event, it returns undefined. This allows the engine to efficiently access and manage event listeners that have been attached to dynamically created elements, enabling proper cleanup when instructions are reverted or when nodes are removed from the DOM.
+     *
+     * @param element
+     * @param eventName
+     * @returns
+     */
+    getListener(element: Node, eventName: string): EventListenerOrEventListenerObject | undefined;
+    /**
+     * Removes an event listener from a specific DOM element and updates the context's index accordingly. This method looks up the element in the elementListeners map and deletes the listener for the specified event name. This is typically called when an instruction is reverted or when a node is removed from the DOM, ensuring that any attached event listeners are properly cleaned up to prevent memory leaks and unintended behavior.
+     *
+     * @param element
+     * @param eventName
+     */
+    removeListener(element: Node, eventName: string): void;
+}
+
+export { AreHTMLEngineContext };

package/dist/node/engine/AreHTML.context.js

@@ -0,0 +1,155 @@
+'use strict';
+
+var are = require('@adaas/are');
+
+class AreHTMLEngineContext extends are.AreContext {
+  constructor(props) {
+    super(props.container?.body.innerHTML || props.source || "");
+    /**
+     * Index structure mapping:
+     * 
+     *        Node                ->       Group ID        ->  Element
+     * -----------------------------------------------------------------------------------
+     *  | - Attribute             |   group: string       |   Node
+     *  | - Directive (e.g. for)  |                       |   Node
+     */
+    this.index = {
+      /**
+       * 1 AreNode = 1 Dom Node
+       * 
+       * uses ASEID
+       */
+      nodeToHostElements: /* @__PURE__ */ new Map(),
+      /**
+       * 1 Group Instruction = MANY Dom Nodes (e.g. for loop)
+       * 
+       * uses ASEID
+       */
+      groupToElements: /* @__PURE__ */ new Map(),
+      /**
+       * 1 Dom Node = 1 Instruction 
+       * 
+       * uses ASEID
+       */
+      elementToInstruction: /* @__PURE__ */ new WeakMap(),
+      /**
+       * 1 Instruction = 1 Dom Node (for CreateElement instructions, for example)
+       * 
+       * uses ASEID
+       */
+      instructionToElement: /* @__PURE__ */ new Map(),
+      /**
+       * Event listeners attached to elements, used for proper cleanup when reverting instructions. Maps a DOM element to a map of event names and their corresponding listeners, allowing the engine to track which listeners are attached to which elements and remove them when necessary (e.g., when an instruction is reverted).
+       */
+      elementListeners: /* @__PURE__ */ new WeakMap()
+    };
+    this._container = props.container;
+  }
+  get container() {
+    return this._container;
+  }
+  getNodeElement(node) {
+    if (typeof node === "string") {
+      return this.index.nodeToHostElements.get(node);
+    } else {
+      return this.index.nodeToHostElements.get(node.aseid.toString());
+    }
+  }
+  /**
+   * Associates a DOM element with a given instruction and its owner node. This method updates the context's index to map the instruction's ASEID to the provided DOM element, and also maps the element back to the instruction's ASEID for reverse lookup. If the instruction has an owner node, it also maps the node's ASEID to the element. Additionally, if the instruction belongs to a group, it adds the element to the set of elements associated with that group. This indexing allows the engine to efficiently manage and update DOM elements based on instructions and their corresponding nodes, enabling dynamic rendering and interaction in response to application state changes.
+   * 
+   * @param instruction 
+   * @param element 
+   */
+  setInstructionElement(instruction, element) {
+    const node = instruction.owner;
+    this.index.instructionToElement.set(instruction.aseid.toString(), element);
+    this.index.elementToInstruction.set(element, instruction.aseid.toString());
+    if (node) {
+      this.index.nodeToHostElements.set(node.aseid.toString(), element);
+    }
+    if (instruction.group) {
+      const groupId = instruction.group;
+      if (!this.index.groupToElements.has(groupId)) {
+        this.index.groupToElements.set(groupId, /* @__PURE__ */ new Set());
+      }
+      this.index.groupToElements.get(groupId).add(element);
+    }
+  }
+  getElementByInstruction(instruction) {
+    if (typeof instruction === "string") {
+      return this.index.instructionToElement.get(instruction);
+    } else {
+      return this.index.instructionToElement.get(instruction.aseid.toString());
+    }
+  }
+  /**
+   * Removes the association between a given instruction and its corresponding DOM element. This method looks up the instruction's ASEID to find the associated DOM element, and if found, it deletes the mapping from both instructionToElement and elementToInstruction. If the instruction has an owner node, it also removes the mapping from nodeToHostElements. Additionally, if the instruction belongs to a group, it removes the element from the set of elements associated with that group, and if the group has no more elements, it deletes the group from the index. This cleanup is essential for maintaining an accurate and efficient mapping of instructions to DOM elements, especially when instructions are reverted or when nodes are removed from the DOM.
+   * 
+   * @param instruction 
+   */
+  removeInstructionElement(instruction) {
+    const element = this.index.instructionToElement.get(instruction.aseid.toString());
+    if (element) {
+      this.index.instructionToElement.delete(instruction.aseid.toString());
+      this.index.elementToInstruction.delete(element);
+      const node = instruction.owner;
+      if (node) {
+        this.index.nodeToHostElements.delete(node.aseid.toString());
+      }
+      if (instruction.group) {
+        const groupId = instruction.group;
+        const groupElements = this.index.groupToElements.get(groupId);
+        if (groupElements) {
+          groupElements.delete(element);
+          if (groupElements.size === 0) {
+            this.index.groupToElements.delete(groupId);
+          }
+        }
+      }
+    }
+  }
+  getElementsByGroup(instruction) {
+    if (typeof instruction === "string") {
+      return this.index.groupToElements.get(instruction);
+    } else {
+      return this.index.groupToElements.get(instruction.aseid.toString());
+    }
+  }
+  /**
+   * Adds an event listener to a specific DOM element and keeps track of it in the context's index for proper cleanup later. This method takes a DOM element, an event name, and a listener function or object, and stores this information in the elementListeners map. This allows the engine to efficiently manage event listeners attached to dynamically created elements, ensuring that they can be removed when the associated instructions are reverted or when nodes are removed from the DOM, preventing memory leaks and unintended behavior.
+   * 
+   * @param element 
+   * @param eventName 
+   * @param listener 
+   */
+  addListener(element, eventName, listener) {
+    if (!this.index.elementListeners.has(element)) {
+      this.index.elementListeners.set(element, /* @__PURE__ */ new Map());
+    }
+    this.index.elementListeners.get(element).set(eventName, listener);
+  }
+  /**
+   * Retrieves the event listener associated with a specific DOM element and event name from the context's index. This method looks up the element in the elementListeners map and then retrieves the listener for the specified event name. If no listener is found for the given element and event, it returns undefined. This allows the engine to efficiently access and manage event listeners that have been attached to dynamically created elements, enabling proper cleanup when instructions are reverted or when nodes are removed from the DOM.
+   * 
+   * @param element 
+   * @param eventName 
+   * @returns 
+   */
+  getListener(element, eventName) {
+    return this.index.elementListeners.get(element)?.get(eventName);
+  }
+  /**
+   * Removes an event listener from a specific DOM element and updates the context's index accordingly. This method looks up the element in the elementListeners map and deletes the listener for the specified event name. This is typically called when an instruction is reverted or when a node is removed from the DOM, ensuring that any attached event listeners are properly cleaned up to prevent memory leaks and unintended behavior.
+   * 
+   * @param element 
+   * @param eventName 
+   */
+  removeListener(element, eventName) {
+    this.index.elementListeners.get(element)?.delete(eventName);
+  }
+}
+
+exports.AreHTMLEngineContext = AreHTMLEngineContext;
+//# sourceMappingURL=AreHTML.context.js.map
+//# sourceMappingURL=AreHTML.context.js.map

package/dist/node/engine/AreHTML.context.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/engine/AreHTML.context.ts"],"names":["AreContext"],"mappings":"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","file":"AreHTML.context.js","sourcesContent":["import { AreContext, AreInstruction, AreNode } from \"@adaas/are\";\nimport { AreHTMLContextConstructor } from \"./AreHTML.types\";\n\n\nexport class AreHTMLEngineContext extends AreContext {\n\n    /**\n     * Index structure mapping:\n     * \n     *        Node                ->       Group ID        ->  Element\n     * -----------------------------------------------------------------------------------\n     *  | - Attribute             |   group: string       |   Node\n     *  | - Directive (e.g. for)  |                       |   Node\n     */\n\n    protected index = {\n        /**\n         * 1 AreNode = 1 Dom Node\n         * \n         * uses ASEID\n         */\n        nodeToHostElements: new Map<string, Node>(),\n        /**\n         * 1 Group Instruction = MANY Dom Nodes (e.g. for loop)\n         * \n         * uses ASEID\n         */\n        groupToElements: new Map<string, Set<Node>>(),\n        /**\n         * 1 Dom Node = 1 Instruction \n         * \n         * uses ASEID\n         */\n        elementToInstruction: new WeakMap<Node, string>(),\n        /**\n         * 1 Instruction = 1 Dom Node (for CreateElement instructions, for example)\n         * \n         * uses ASEID\n         */\n        instructionToElement: new Map<string, Node>(),\n        /**\n         * Event listeners attached to elements, used for proper cleanup when reverting instructions. Maps a DOM element to a map of event names and their corresponding listeners, allowing the engine to track which listeners are attached to which elements and remove them when necessary (e.g., when an instruction is reverted).\n         */\n        elementListeners: new WeakMap<Node, Map<string, EventListenerOrEventListenerObject>>()\n    }\n\n    /**\n     * The root container for the HTML engine, which can be either a Document or a ShadowRoot. This is where the engine will mount the generated DOM elements. The context uses this container to manage the relationship between AreNodes, instructions, and their corresponding DOM elements, allowing for efficient updates and cleanups as the application state changes.\n     */\n    protected _container: Document;\n\n\n    constructor(props: Partial<AreHTMLContextConstructor>) {\n        super(props.container?.body.innerHTML || props.source || '');\n        this._container = props.container!;\n    }\n\n    get container(): Document {\n        return this._container;\n    }\n\n\n    /**\n     * Retrieves the DOM element associated with a given AreNode. This method looks up the node's ASEID in the nodeToHostElements map to find the corresponding DOM element. If the node is not found, it returns undefined. This allows the engine to efficiently access and manipulate the DOM elements that correspond to specific nodes in the AreNode tree, enabling dynamic updates and interactions based on the application state.\n     * \n     * @param nodeASEID \n     */\n    getNodeElement(nodeASEID: string): Node | undefined\n    getNodeElement(node: AreNode): Node | undefined\n    getNodeElement(node: AreNode | string): Node | undefined {\n        if (typeof node === 'string') {\n            return this.index.nodeToHostElements.get(node);\n        } else {\n            return this.index.nodeToHostElements.get(node.aseid.toString());\n        }\n    }\n\n    /**\n     * Associates a DOM element with a given instruction and its owner node. This method updates the context's index to map the instruction's ASEID to the provided DOM element, and also maps the element back to the instruction's ASEID for reverse lookup. If the instruction has an owner node, it also maps the node's ASEID to the element. Additionally, if the instruction belongs to a group, it adds the element to the set of elements associated with that group. This indexing allows the engine to efficiently manage and update DOM elements based on instructions and their corresponding nodes, enabling dynamic rendering and interaction in response to application state changes.\n     * \n     * @param instruction \n     * @param element \n     */\n    setInstructionElement(instruction: AreInstruction, element: Node): void {\n        const node = instruction.owner;\n\n        this.index.instructionToElement.set(instruction.aseid.toString(), element);\n        this.index.elementToInstruction.set(element, instruction.aseid.toString());\n\n        if (node) {\n            this.index.nodeToHostElements.set(node.aseid.toString(), element);\n        }\n\n        if (instruction.group) {\n            const groupId = instruction.group;\n            if (!this.index.groupToElements.has(groupId)) {\n                this.index.groupToElements.set(groupId, new Set());\n            }\n            this.index.groupToElements.get(groupId)!.add(element);\n        }\n    }\n\n\n    /**\n     * Retrieves the DOM element associated with a given instruction. This method looks up the instruction's ASEID in the instructionToElement map to find the corresponding DOM element. If the instruction is not found, it returns undefined. This allows the engine to efficiently access and manipulate the DOM elements that correspond to specific instructions, enabling dynamic updates and interactions based on the application state.\n     * \n     * @param instructionASEID \n     */\n    getElementByInstruction(instructionASEID: string): Node | undefined\n    getElementByInstruction(instruction: AreInstruction): Node | undefined\n    getElementByInstruction(instruction: AreInstruction | string): Node | undefined {\n        if (typeof instruction === 'string') {\n            return this.index.instructionToElement.get(instruction);\n        } else {\n            return this.index.instructionToElement.get(instruction.aseid.toString());\n        }\n    }\n\n\n    /**\n     * Removes the association between a given instruction and its corresponding DOM element. This method looks up the instruction's ASEID to find the associated DOM element, and if found, it deletes the mapping from both instructionToElement and elementToInstruction. If the instruction has an owner node, it also removes the mapping from nodeToHostElements. Additionally, if the instruction belongs to a group, it removes the element from the set of elements associated with that group, and if the group has no more elements, it deletes the group from the index. This cleanup is essential for maintaining an accurate and efficient mapping of instructions to DOM elements, especially when instructions are reverted or when nodes are removed from the DOM.\n     * \n     * @param instruction \n     */\n    removeInstructionElement(instruction: AreInstruction): void {\n        const element = this.index.instructionToElement.get(instruction.aseid.toString());\n        if (element) {\n            this.index.instructionToElement.delete(instruction.aseid.toString());\n            this.index.elementToInstruction.delete(element);\n\n            const node = instruction.owner;\n            if (node) {\n                this.index.nodeToHostElements.delete(node.aseid.toString());\n            }\n\n            if (instruction.group) {\n                const groupId = instruction.group;\n                const groupElements = this.index.groupToElements.get(groupId);\n                if (groupElements) {\n                    groupElements.delete(element);\n                    if (groupElements.size === 0) {\n                        this.index.groupToElements.delete(groupId);\n                    }\n                }\n            }\n        }\n    }\n\n    /**\n     * Retrieves the set of DOM elements associated with a given group. This method looks up the group name or instruction's ASEID in the groupToElements map to find the corresponding set of DOM elements. If the group is not found, it returns undefined. This allows the engine to efficiently access and manipulate all DOM elements that belong to a specific group (e.g., all elements generated by a particular loop instruction), enabling dynamic updates and interactions based on the application state.\n     * \n     * @param groupName \n     */\n    getElementsByGroup(groupName: string): Set<Node> | undefined\n    getElementsByGroup(instruction: AreInstruction): Set<Node> | undefined\n    getElementsByGroup(instruction: AreInstruction | string): Set<Node> | undefined {\n        if (typeof instruction === 'string') {\n            return this.index.groupToElements.get(instruction);\n        } else {\n            return this.index.groupToElements.get(instruction.aseid.toString());\n        }\n    }\n\n    /**\n     * Adds an event listener to a specific DOM element and keeps track of it in the context's index for proper cleanup later. This method takes a DOM element, an event name, and a listener function or object, and stores this information in the elementListeners map. This allows the engine to efficiently manage event listeners attached to dynamically created elements, ensuring that they can be removed when the associated instructions are reverted or when nodes are removed from the DOM, preventing memory leaks and unintended behavior.\n     * \n     * @param element \n     * @param eventName \n     * @param listener \n     */\n    addListener(element: Node, eventName: string, listener: EventListenerOrEventListenerObject): void {\n        if (!this.index.elementListeners.has(element)) {\n            this.index.elementListeners.set(element, new Map());\n        }\n        this.index.elementListeners.get(element)!.set(eventName, listener);\n    }\n    /**\n     * Retrieves the event listener associated with a specific DOM element and event name from the context's index. This method looks up the element in the elementListeners map and then retrieves the listener for the specified event name. If no listener is found for the given element and event, it returns undefined. This allows the engine to efficiently access and manage event listeners that have been attached to dynamically created elements, enabling proper cleanup when instructions are reverted or when nodes are removed from the DOM.\n     * \n     * @param element \n     * @param eventName \n     * @returns \n     */\n    getListener(element: Node, eventName: string): EventListenerOrEventListenerObject | undefined {\n        return this.index.elementListeners.get(element)?.get(eventName);\n    }\n    /**\n     * Removes an event listener from a specific DOM element and updates the context's index accordingly. This method looks up the element in the elementListeners map and deletes the listener for the specified event name. This is typically called when an instruction is reverted or when a node is removed from the DOM, ensuring that any attached event listeners are properly cleaned up to prevent memory leaks and unintended behavior.\n     * \n     * @param element \n     * @param eventName \n     */\n    removeListener(element: Node, eventName: string): void {\n        this.index.elementListeners.get(element)?.delete(eventName);\n    }\n}\n"]}

package/dist/node/engine/AreHTML.context.mjs

@@ -0,0 +1,154 @@
+import '../chunk-EQQGB2QZ.mjs';
+import { AreContext } from '@adaas/are';
+
+class AreHTMLEngineContext extends AreContext {
+  constructor(props) {
+    super(props.container?.body.innerHTML || props.source || "");
+    /**
+     * Index structure mapping:
+     * 
+     *        Node                ->       Group ID        ->  Element
+     * -----------------------------------------------------------------------------------
+     *  | - Attribute             |   group: string       |   Node
+     *  | - Directive (e.g. for)  |                       |   Node
+     */
+    this.index = {
+      /**
+       * 1 AreNode = 1 Dom Node
+       * 
+       * uses ASEID
+       */
+      nodeToHostElements: /* @__PURE__ */ new Map(),
+      /**
+       * 1 Group Instruction = MANY Dom Nodes (e.g. for loop)
+       * 
+       * uses ASEID
+       */
+      groupToElements: /* @__PURE__ */ new Map(),
+      /**
+       * 1 Dom Node = 1 Instruction 
+       * 
+       * uses ASEID
+       */
+      elementToInstruction: /* @__PURE__ */ new WeakMap(),
+      /**
+       * 1 Instruction = 1 Dom Node (for CreateElement instructions, for example)
+       * 
+       * uses ASEID
+       */
+      instructionToElement: /* @__PURE__ */ new Map(),
+      /**
+       * Event listeners attached to elements, used for proper cleanup when reverting instructions. Maps a DOM element to a map of event names and their corresponding listeners, allowing the engine to track which listeners are attached to which elements and remove them when necessary (e.g., when an instruction is reverted).
+       */
+      elementListeners: /* @__PURE__ */ new WeakMap()
+    };
+    this._container = props.container;
+  }
+  get container() {
+    return this._container;
+  }
+  getNodeElement(node) {
+    if (typeof node === "string") {
+      return this.index.nodeToHostElements.get(node);
+    } else {
+      return this.index.nodeToHostElements.get(node.aseid.toString());
+    }
+  }
+  /**
+   * Associates a DOM element with a given instruction and its owner node. This method updates the context's index to map the instruction's ASEID to the provided DOM element, and also maps the element back to the instruction's ASEID for reverse lookup. If the instruction has an owner node, it also maps the node's ASEID to the element. Additionally, if the instruction belongs to a group, it adds the element to the set of elements associated with that group. This indexing allows the engine to efficiently manage and update DOM elements based on instructions and their corresponding nodes, enabling dynamic rendering and interaction in response to application state changes.
+   * 
+   * @param instruction 
+   * @param element 
+   */
+  setInstructionElement(instruction, element) {
+    const node = instruction.owner;
+    this.index.instructionToElement.set(instruction.aseid.toString(), element);
+    this.index.elementToInstruction.set(element, instruction.aseid.toString());
+    if (node) {
+      this.index.nodeToHostElements.set(node.aseid.toString(), element);
+    }
+    if (instruction.group) {
+      const groupId = instruction.group;
+      if (!this.index.groupToElements.has(groupId)) {
+        this.index.groupToElements.set(groupId, /* @__PURE__ */ new Set());
+      }
+      this.index.groupToElements.get(groupId).add(element);
+    }
+  }
+  getElementByInstruction(instruction) {
+    if (typeof instruction === "string") {
+      return this.index.instructionToElement.get(instruction);
+    } else {
+      return this.index.instructionToElement.get(instruction.aseid.toString());
+    }
+  }
+  /**
+   * Removes the association between a given instruction and its corresponding DOM element. This method looks up the instruction's ASEID to find the associated DOM element, and if found, it deletes the mapping from both instructionToElement and elementToInstruction. If the instruction has an owner node, it also removes the mapping from nodeToHostElements. Additionally, if the instruction belongs to a group, it removes the element from the set of elements associated with that group, and if the group has no more elements, it deletes the group from the index. This cleanup is essential for maintaining an accurate and efficient mapping of instructions to DOM elements, especially when instructions are reverted or when nodes are removed from the DOM.
+   * 
+   * @param instruction 
+   */
+  removeInstructionElement(instruction) {
+    const element = this.index.instructionToElement.get(instruction.aseid.toString());
+    if (element) {
+      this.index.instructionToElement.delete(instruction.aseid.toString());
+      this.index.elementToInstruction.delete(element);
+      const node = instruction.owner;
+      if (node) {
+        this.index.nodeToHostElements.delete(node.aseid.toString());
+      }
+      if (instruction.group) {
+        const groupId = instruction.group;
+        const groupElements = this.index.groupToElements.get(groupId);
+        if (groupElements) {
+          groupElements.delete(element);
+          if (groupElements.size === 0) {
+            this.index.groupToElements.delete(groupId);
+          }
+        }
+      }
+    }
+  }
+  getElementsByGroup(instruction) {
+    if (typeof instruction === "string") {
+      return this.index.groupToElements.get(instruction);
+    } else {
+      return this.index.groupToElements.get(instruction.aseid.toString());
+    }
+  }
+  /**
+   * Adds an event listener to a specific DOM element and keeps track of it in the context's index for proper cleanup later. This method takes a DOM element, an event name, and a listener function or object, and stores this information in the elementListeners map. This allows the engine to efficiently manage event listeners attached to dynamically created elements, ensuring that they can be removed when the associated instructions are reverted or when nodes are removed from the DOM, preventing memory leaks and unintended behavior.
+   * 
+   * @param element 
+   * @param eventName 
+   * @param listener 
+   */
+  addListener(element, eventName, listener) {
+    if (!this.index.elementListeners.has(element)) {
+      this.index.elementListeners.set(element, /* @__PURE__ */ new Map());
+    }
+    this.index.elementListeners.get(element).set(eventName, listener);
+  }
+  /**
+   * Retrieves the event listener associated with a specific DOM element and event name from the context's index. This method looks up the element in the elementListeners map and then retrieves the listener for the specified event name. If no listener is found for the given element and event, it returns undefined. This allows the engine to efficiently access and manage event listeners that have been attached to dynamically created elements, enabling proper cleanup when instructions are reverted or when nodes are removed from the DOM.
+   * 
+   * @param element 
+   * @param eventName 
+   * @returns 
+   */
+  getListener(element, eventName) {
+    return this.index.elementListeners.get(element)?.get(eventName);
+  }
+  /**
+   * Removes an event listener from a specific DOM element and updates the context's index accordingly. This method looks up the element in the elementListeners map and deletes the listener for the specified event name. This is typically called when an instruction is reverted or when a node is removed from the DOM, ensuring that any attached event listeners are properly cleaned up to prevent memory leaks and unintended behavior.
+   * 
+   * @param element 
+   * @param eventName 
+   */
+  removeListener(element, eventName) {
+    this.index.elementListeners.get(element)?.delete(eventName);
+  }
+}
+
+export { AreHTMLEngineContext };
+//# sourceMappingURL=AreHTML.context.mjs.map
+//# sourceMappingURL=AreHTML.context.mjs.map

package/dist/node/engine/AreHTML.context.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/engine/AreHTML.context.ts"],"names":[],"mappings":"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","file":"AreHTML.context.mjs","sourcesContent":["import { AreContext, AreInstruction, AreNode } from \"@adaas/are\";\nimport { AreHTMLContextConstructor } from \"./AreHTML.types\";\n\n\nexport class AreHTMLEngineContext extends AreContext {\n\n    /**\n     * Index structure mapping:\n     * \n     *        Node                ->       Group ID        ->  Element\n     * -----------------------------------------------------------------------------------\n     *  | - Attribute             |   group: string       |   Node\n     *  | - Directive (e.g. for)  |                       |   Node\n     */\n\n    protected index = {\n        /**\n         * 1 AreNode = 1 Dom Node\n         * \n         * uses ASEID\n         */\n        nodeToHostElements: new Map<string, Node>(),\n        /**\n         * 1 Group Instruction = MANY Dom Nodes (e.g. for loop)\n         * \n         * uses ASEID\n         */\n        groupToElements: new Map<string, Set<Node>>(),\n        /**\n         * 1 Dom Node = 1 Instruction \n         * \n         * uses ASEID\n         */\n        elementToInstruction: new WeakMap<Node, string>(),\n        /**\n         * 1 Instruction = 1 Dom Node (for CreateElement instructions, for example)\n         * \n         * uses ASEID\n         */\n        instructionToElement: new Map<string, Node>(),\n        /**\n         * Event listeners attached to elements, used for proper cleanup when reverting instructions. Maps a DOM element to a map of event names and their corresponding listeners, allowing the engine to track which listeners are attached to which elements and remove them when necessary (e.g., when an instruction is reverted).\n         */\n        elementListeners: new WeakMap<Node, Map<string, EventListenerOrEventListenerObject>>()\n    }\n\n    /**\n     * The root container for the HTML engine, which can be either a Document or a ShadowRoot. This is where the engine will mount the generated DOM elements. The context uses this container to manage the relationship between AreNodes, instructions, and their corresponding DOM elements, allowing for efficient updates and cleanups as the application state changes.\n     */\n    protected _container: Document;\n\n\n    constructor(props: Partial<AreHTMLContextConstructor>) {\n        super(props.container?.body.innerHTML || props.source || '');\n        this._container = props.container!;\n    }\n\n    get container(): Document {\n        return this._container;\n    }\n\n\n    /**\n     * Retrieves the DOM element associated with a given AreNode. This method looks up the node's ASEID in the nodeToHostElements map to find the corresponding DOM element. If the node is not found, it returns undefined. This allows the engine to efficiently access and manipulate the DOM elements that correspond to specific nodes in the AreNode tree, enabling dynamic updates and interactions based on the application state.\n     * \n     * @param nodeASEID \n     */\n    getNodeElement(nodeASEID: string): Node | undefined\n    getNodeElement(node: AreNode): Node | undefined\n    getNodeElement(node: AreNode | string): Node | undefined {\n        if (typeof node === 'string') {\n            return this.index.nodeToHostElements.get(node);\n        } else {\n            return this.index.nodeToHostElements.get(node.aseid.toString());\n        }\n    }\n\n    /**\n     * Associates a DOM element with a given instruction and its owner node. This method updates the context's index to map the instruction's ASEID to the provided DOM element, and also maps the element back to the instruction's ASEID for reverse lookup. If the instruction has an owner node, it also maps the node's ASEID to the element. Additionally, if the instruction belongs to a group, it adds the element to the set of elements associated with that group. This indexing allows the engine to efficiently manage and update DOM elements based on instructions and their corresponding nodes, enabling dynamic rendering and interaction in response to application state changes.\n     * \n     * @param instruction \n     * @param element \n     */\n    setInstructionElement(instruction: AreInstruction, element: Node): void {\n        const node = instruction.owner;\n\n        this.index.instructionToElement.set(instruction.aseid.toString(), element);\n        this.index.elementToInstruction.set(element, instruction.aseid.toString());\n\n        if (node) {\n            this.index.nodeToHostElements.set(node.aseid.toString(), element);\n        }\n\n        if (instruction.group) {\n            const groupId = instruction.group;\n            if (!this.index.groupToElements.has(groupId)) {\n                this.index.groupToElements.set(groupId, new Set());\n            }\n            this.index.groupToElements.get(groupId)!.add(element);\n        }\n    }\n\n\n    /**\n     * Retrieves the DOM element associated with a given instruction. This method looks up the instruction's ASEID in the instructionToElement map to find the corresponding DOM element. If the instruction is not found, it returns undefined. This allows the engine to efficiently access and manipulate the DOM elements that correspond to specific instructions, enabling dynamic updates and interactions based on the application state.\n     * \n     * @param instructionASEID \n     */\n    getElementByInstruction(instructionASEID: string): Node | undefined\n    getElementByInstruction(instruction: AreInstruction): Node | undefined\n    getElementByInstruction(instruction: AreInstruction | string): Node | undefined {\n        if (typeof instruction === 'string') {\n            return this.index.instructionToElement.get(instruction);\n        } else {\n            return this.index.instructionToElement.get(instruction.aseid.toString());\n        }\n    }\n\n\n    /**\n     * Removes the association between a given instruction and its corresponding DOM element. This method looks up the instruction's ASEID to find the associated DOM element, and if found, it deletes the mapping from both instructionToElement and elementToInstruction. If the instruction has an owner node, it also removes the mapping from nodeToHostElements. Additionally, if the instruction belongs to a group, it removes the element from the set of elements associated with that group, and if the group has no more elements, it deletes the group from the index. This cleanup is essential for maintaining an accurate and efficient mapping of instructions to DOM elements, especially when instructions are reverted or when nodes are removed from the DOM.\n     * \n     * @param instruction \n     */\n    removeInstructionElement(instruction: AreInstruction): void {\n        const element = this.index.instructionToElement.get(instruction.aseid.toString());\n        if (element) {\n            this.index.instructionToElement.delete(instruction.aseid.toString());\n            this.index.elementToInstruction.delete(element);\n\n            const node = instruction.owner;\n            if (node) {\n                this.index.nodeToHostElements.delete(node.aseid.toString());\n            }\n\n            if (instruction.group) {\n                const groupId = instruction.group;\n                const groupElements = this.index.groupToElements.get(groupId);\n                if (groupElements) {\n                    groupElements.delete(element);\n                    if (groupElements.size === 0) {\n                        this.index.groupToElements.delete(groupId);\n                    }\n                }\n            }\n        }\n    }\n\n    /**\n     * Retrieves the set of DOM elements associated with a given group. This method looks up the group name or instruction's ASEID in the groupToElements map to find the corresponding set of DOM elements. If the group is not found, it returns undefined. This allows the engine to efficiently access and manipulate all DOM elements that belong to a specific group (e.g., all elements generated by a particular loop instruction), enabling dynamic updates and interactions based on the application state.\n     * \n     * @param groupName \n     */\n    getElementsByGroup(groupName: string): Set<Node> | undefined\n    getElementsByGroup(instruction: AreInstruction): Set<Node> | undefined\n    getElementsByGroup(instruction: AreInstruction | string): Set<Node> | undefined {\n        if (typeof instruction === 'string') {\n            return this.index.groupToElements.get(instruction);\n        } else {\n            return this.index.groupToElements.get(instruction.aseid.toString());\n        }\n    }\n\n    /**\n     * Adds an event listener to a specific DOM element and keeps track of it in the context's index for proper cleanup later. This method takes a DOM element, an event name, and a listener function or object, and stores this information in the elementListeners map. This allows the engine to efficiently manage event listeners attached to dynamically created elements, ensuring that they can be removed when the associated instructions are reverted or when nodes are removed from the DOM, preventing memory leaks and unintended behavior.\n     * \n     * @param element \n     * @param eventName \n     * @param listener \n     */\n    addListener(element: Node, eventName: string, listener: EventListenerOrEventListenerObject): void {\n        if (!this.index.elementListeners.has(element)) {\n            this.index.elementListeners.set(element, new Map());\n        }\n        this.index.elementListeners.get(element)!.set(eventName, listener);\n    }\n    /**\n     * Retrieves the event listener associated with a specific DOM element and event name from the context's index. This method looks up the element in the elementListeners map and then retrieves the listener for the specified event name. If no listener is found for the given element and event, it returns undefined. This allows the engine to efficiently access and manage event listeners that have been attached to dynamically created elements, enabling proper cleanup when instructions are reverted or when nodes are removed from the DOM.\n     * \n     * @param element \n     * @param eventName \n     * @returns \n     */\n    getListener(element: Node, eventName: string): EventListenerOrEventListenerObject | undefined {\n        return this.index.elementListeners.get(element)?.get(eventName);\n    }\n    /**\n     * Removes an event listener from a specific DOM element and updates the context's index accordingly. This method looks up the element in the elementListeners map and deletes the listener for the specified event name. This is typically called when an instruction is reverted or when a node is removed from the DOM, ensuring that any attached event listeners are properly cleaned up to prevent memory leaks and unintended behavior.\n     * \n     * @param element \n     * @param eventName \n     */\n    removeListener(element: Node, eventName: string): void {\n        this.index.elementListeners.get(element)?.delete(eventName);\n    }\n}\n"]}

package/dist/node/engine/AreHTML.engine.d.mts

@@ -0,0 +1,21 @@
+import { A_Scope } from '@adaas/a-concept';
+import { AreEngine, AreSyntax, AreSyntaxTokenMatch } from '@adaas/are';
+
+declare class AreHTMLEngine extends AreEngine {
+    get DefaultSyntax(): AreSyntax;
+    /**
+     * Inject AreHTMLSyntax into the container scope before loading
+     *
+     * @param container
+     */
+    init(scope: A_Scope): Promise<void>;
+    protected rootElementMatcher(source: string, from: number, to: number, build: (raw: string, content: string, position: number, closing: string) => AreSyntaxTokenMatch): AreSyntaxTokenMatch | null;
+    protected htmlElementMatcher(source: string, from: number, to: number, build: (raw: string, content: string, position: number, closing: string) => AreSyntaxTokenMatch): AreSyntaxTokenMatch | null;
+    /**
+     * Find the index of the closing `>` of an opening tag, skipping over
+     * `>` characters that appear inside quoted attribute values.
+     */
+    private static findTagClose;
+}
+
+export { AreHTMLEngine };

package/dist/node/engine/AreHTML.engine.d.ts

@@ -0,0 +1,21 @@
+import { A_Scope } from '@adaas/a-concept';
+import { AreEngine, AreSyntax, AreSyntaxTokenMatch } from '@adaas/are';
+
+declare class AreHTMLEngine extends AreEngine {
+    get DefaultSyntax(): AreSyntax;
+    /**
+     * Inject AreHTMLSyntax into the container scope before loading
+     *
+     * @param container
+     */
+    init(scope: A_Scope): Promise<void>;
+    protected rootElementMatcher(source: string, from: number, to: number, build: (raw: string, content: string, position: number, closing: string) => AreSyntaxTokenMatch): AreSyntaxTokenMatch | null;
+    protected htmlElementMatcher(source: string, from: number, to: number, build: (raw: string, content: string, position: number, closing: string) => AreSyntaxTokenMatch): AreSyntaxTokenMatch | null;
+    /**
+     * Find the index of the closing `>` of an opening tag, skipping over
+     * `>` characters that appear inside quoted attribute values.
+     */
+    private static findTagClose;
+}
+
+export { AreHTMLEngine };