main.DeltaUpdates: use initAsync(), and also update the JSDoc comments #6887

tobiu · tobiu · commit e7f0953092fa · 2025-06-28T01:20:23.000+02:00
diff --git a/src/main/DeltaUpdates.mjs b/src/main/DeltaUpdates.mjs
@@ -5,7 +5,13 @@ import {voidAttributes} from '../vdom/domConstants.mjs';
 const NeoConfig = Neo.config;
 
 /**
- * Logic to apply the deltas generated by vdom.Helper to the real DOM
+ * Manages and applies the Virtual DOM (VDom) delta updates generated by `Neo.vdom.Helper` to the real browser DOM.
+ * This class acts as the bridge between the VDom worker's calculated changes and the actual rendering on the main thread.
+ * It orchestrates various DOM manipulation operations such as node insertions, removals, moves, attribute updates,
+ * and handles dynamic renderer switching based on `Neo.config.useDomApiRenderer`.
+ *
+ * As a singleton per browser window, it provides a centralized and efficient mechanism for synchronized DOM updates,
+ * ensuring the UI accurately reflects the application state.
  * @class Neo.main.DeltaUpdates
  * @extends Neo.core.Base
  * @singleton
@@ -48,56 +54,24 @@ class DeltaUpdates extends Base {
      * @protected
      */
     logDeltasIntervalId = 0
-    /**
-     * Private property to store the dynamically loaded renderer module.
-     * @member {Neo.main.render.DomApiRenderer|Neo.main.render.DomApiRenderer|null} #renderer=null
-     * @private
-     */
-    #renderer = null
-    /**
-     * Private property to signal that the renderer module has been loaded.
-     * This will be a Promise that resolves when the module is ready.
-     * @private
-     * @member {Promise<void>|null} #_readyPromise
-     */
-    #_readyPromise = null
 
     /**
      * @param {Object} config
      */
     construct(config) {
         super.construct(config);
 
-        let me            = this,
-            {environment} = NeoConfig;
+        let {environment} = NeoConfig;
 
         if (NeoConfig.renderCountDeltas) {
-            me.renderCountDeltas = true
+            this.renderCountDeltas = true
         }
 
         // We need different publicPath values for the main thread inside the webpack based dist envs,
         // depending on the hierarchy level of the app entry point
         if (environment === 'dist/development' || environment === 'dist/production') {
             __webpack_require__.p = NeoConfig.basePath.substring(6)
         }
-
-        // Initiate the asynchronous loading of the renderer here.
-        me.#_readyPromise = (async () => {
-            try {
-                let module;
-
-                if (NeoConfig.useDomApiRenderer) {
-                    module = await import('./render/DomApiRenderer.mjs')
-                } else {
-                    module = await import('./render/StringBasedRenderer.mjs')
-                }
-
-                me.#renderer = module.default
-            } catch (err) {
-                console.error('DeltaUpdates: Failed to load renderer module:', err);
-                throw err // Re-throw to propagate initialization failures
-            }
-        })()
     }
 
     /**
@@ -130,8 +104,13 @@ class DeltaUpdates extends Base {
     }
 
     /**
-     * @param {HTMLElement} node
-     * @param {String}      nodeName
+     * Changes the tag name (nodeName) of an existing HTMLElement in the DOM.
+     * This operation is performed by creating a new HTML element with the desired `nodeName`,
+     * meticulously copying all attributes and the `innerHTML` from the original `node` to the new one,
+     * and then seamlessly replacing the original `node` with the newly created element within its parent.
+     *
+     * @param {HTMLElement} node     The existing DOM HTMLElement whose tag name needs to be changed.
+     * @param {String}      nodeName The new tag name (e.g., 'div', 'span', 'p') for the element.
      */
     changeNodeName(node, nodeName) {
         let {attributes} = node,
@@ -160,21 +139,49 @@ class DeltaUpdates extends Base {
         DomAccess.getElement(id)?.focus()
     }
 
+    /**
+     * Imports either (if not already imported):
+     * `Neo.main.render.DomApiRenderer`      if Neo.config.useDomApiRenderer === true
+     * `Neo.main.render.StringBasedRenderer` if Neo.config.useDomApiRenderer === false
+     * @returns {Promise<void>}
+     * @protected
+     */
+    async importRenderer() {
+        const {render} = Neo.main;
+
+        if (NeoConfig.useDomApiRenderer) {
+            if (!render?.DomApiRenderer) {
+                await import('./render/DomApiRenderer.mjs')
+            }
+        } else {
+            if (!render?.StringBasedRenderer) {
+                await import('./render/StringBasedRenderer.mjs')
+            }
+        }
+    }
+
+    /**
+     * @returns {Promise<void>}
+     */
+    async initAsync() {
+        super.initAsync();
+
+        let me = this;
+
+        // Subscribe to global Neo.config changes for dynamic renderer switching.
+        Neo.worker.Manager.on({
+            neoConfigChange: me.onNeoConfigChange,
+            scope          : me
+        });
+
+        await me.importRenderer()
+    }
+
     /**
      * Inserts a new node into the DOM tree based on delta updates.
      * This method handles both string-based (outerHTML) and direct DOM API (vnode) mounting.
      * It ensures the node is inserted at the correct index within the parent.
-     *
-     * Implementation Details & Considerations:
-     * - `parentNode.children` contains only element nodes (tags).
-     * - `parentNode.childNodes` contains all nodes, including text and comment nodes.
-     * - Since every `vtype:'text'` is wrapped inside a comment block (as an ID),
-     *   calculating a "realIndex" is necessary for string-based insertions to
-     *   correctly account for non-element nodes.
-     * - `insertAdjacentHTML()` is generally faster than creating a node via template,
-     *   but it's only available for manipulating children (elements), not `childNodes` (all nodes).
-     * - For performance, in cases where there are no comment nodes (i.e., no wrapped text nodes),
-     *   the method prioritizes `insertAdjacentHTML()` when `useDomApiRenderer` is false.
+     * This method is synchronous and *expects* the appropriate renderer (DomApiRenderer or StringBasedRenderer) to be already loaded.
      *
      * @param {Object}         delta
      * @param {Boolean}        delta.hasLeadingTextChildren Flag to honor leading comments, which require special treatment.
@@ -184,33 +191,47 @@ class DeltaUpdates extends Base {
      * @param {Neo.vdom.VNode} [delta.vnode]                The VNode representation of the new node (for direct DOM API mounting).
      */
     insertNode({hasLeadingTextChildren, index, outerHTML, parentId, vnode}) {
-        let me = this;
-
-        // This method is synchronous and *expects* the renderer to be loaded
-        if (!me.#renderer) {
-            console.error('DeltaUpdates renderer not ready during insertNode!');
-            return
-        }
+        this.checkRendererAvailability();
 
-        const parentNode = DomAccess.getElementOrBody(parentId);
+        let {render}   = Neo.main,
+            parentNode = DomAccess.getElementOrBody(parentId);
 
         if (parentNode) {
             if (NeoConfig.useDomApiRenderer) {
-                me.#renderer.createDomTree({index, isRoot: true, parentNode, vnode})
+                render.DomApiRenderer.createDomTree({index, isRoot: true, parentNode, vnode})
             } else {
-                me.#renderer.insertNodeAsString({hasLeadingTextChildren, index, outerHTML, parentNode})
+                render.StringBasedRenderer.insertNodeAsString({hasLeadingTextChildren, index, outerHTML, parentNode})
+            }
+        }
+    }
+
+    /**
+     *
+     */
+    checkRendererAvailability() {
+        const {render} = Neo.main;
+
+        if (NeoConfig.useDomApiRenderer) {
+            if (!render?.DomApiRenderer) {
+                throw new Error('Neo.main.DeltaUpdates: DomApiRenderer is not loaded yet!')
+            }
+        } else {
+            if (!render?.StringBasedRenderer) {
+                throw new Error('Neo.main.DeltaUpdates: StringBasedRenderer is not loaded yet!')
             }
         }
     }
 
     /**
-     * Moves an existing DOM node to a new position within its parent
-     * or to a new parent.
-     * This method directly manipulates the DOM using the pre-calculated physical index.
+     * Moves an existing DOM node to a new position within its parent or to a new parent.
+     * This method directly manipulates the DOM using the pre-calculated physical index,
+     * accounting for potential text nodes wrapped in comments.
+     * It performs a direct sibling swap when an element is immediately followed by its target position,
+     * which is necessary to prevent attempting to replace a node with itself.
      *
      * @param {Object} delta
      * @param {String} delta.id       The ID of the DOM node to move.
-     * @param {Number} delta.index    The physical index at which to insert the node
+     * @param {Number} delta.index    The physical index at which to insert the node within the target parent's childNodes.
      * @param {String} delta.parentId The ID of the target parent DOM node.
      */
     moveNode({id, index, parentId}) {
@@ -239,8 +260,25 @@ class DeltaUpdates extends Base {
     }
 
     /**
+     * Handler for global Neo.config changes.
+     * If the `Neo.config.useDomApiRenderer` value changes, this method dynamically loads the renderer.
+     * @param {Object} config
+     * @return {Promise<void>}
+     */
+    async onNeoConfigChange(config) {
+        if (Object.hasOwn(config, 'useDomApiRenderer')) {
+            await this.importRenderer()
+        }
+    }
+
+    /**
+     * Clears all child nodes of a given parent DOM node.
+     * This is achieved by setting its `innerHTML` property to an empty string,
+     * which is generally considered the fastest and most efficient way to remove
+     * all children from a DOM element in modern browsers.
+     *
      * @param {Object} delta
-     * @param {String} delta.parentId
+     * @param {String} delta.parentId The ID of the parent DOM node whose children will be removed.
      */
     removeAll({parentId}) {
         let node = DomAccess.getElement(parentId);
@@ -251,9 +289,13 @@ class DeltaUpdates extends Base {
     }
 
     /**
+     * Removes a DOM node from its parent.
+     * This method handles both standard HTML elements and virtual text nodes,
+     * which are typically wrapped within comment nodes in the DOM.
+     *
      * @param {Object} delta
-     * @param {String} delta.id
-     * @param {String} delta.parentId
+     * @param {String} delta.id       The ID of the DOM node to remove.
+     * @param {String} delta.parentId The ID of the parent DOM node (required for text node removal).
      */
     removeNode({id, parentId}) {
         const node = DomAccess.getElement(id);
@@ -289,10 +331,17 @@ class DeltaUpdates extends Base {
     }
 
     /**
+     * Replaces an existing child DOM node (`fromId`) with a new DOM node (`toId`)
+     * within a specified parent DOM node (`parentId`).
+     * This operation directly invokes the native `Node.replaceChild()` API,
+     * performing an atomic swap of the elements in the DOM tree.
+     * It is typically used when a specific DOM element needs to be completely
+     * exchanged for a different one at the same position.
+     *
      * @param {Object} delta
-     * @param {String} delta.fromId
-     * @param {String} delta.parentId
-     * @param {String} delta.toId
+     * @param {String} delta.fromId   The ID of the existing child DOM node to be replaced.
+     * @param {String} delta.parentId The ID of the parent DOM node containing the child to be replaced.
+     * @param {String} delta.toId     The ID of the new DOM node that will replace the old one.
      */
     replaceChild({fromId, parentId, toId}) {
         let node = DomAccess.getElement(parentId);
@@ -301,13 +350,20 @@ class DeltaUpdates extends Base {
     }
 
     /**
+     * Updates various properties of an existing DOM node based on the provided delta.
+     * This includes updating attributes, class names, inner HTML, node name, and inline styles.
+     * It handles specific cases for attribute types (e.g., boolean attributes, 'value')
+     * and style properties (e.g., '!important').
+     *
      * @param {Object} delta
-     * @param {Object} [delta.attributes]
-     * @param {String} [delta.cls]
-     * @param {String} [delta.id]
-     * @param {String} [delta.innerHTML]
-     * @param {String} [delta.outerHTML]
-     * @param {Object} [delta.style]
+     * @param {String} delta.id            The ID of the DOM node to update.
+     * @param {Object} [delta.attributes]  An object containing attribute key-value pairs to update or remove (if value is null/empty).
+     * @param {Object} [delta.cls]         An object containing 'add' and/or 'remove' arrays for CSS classes.
+     * @param {String} [delta.innerHTML]   The new inner HTML content for the node.
+     * @param {String} [delta.nodeName]    The new tag name for the node (will trigger a node replacement).
+     * @param {String} [delta.outerHTML]   The new outer HTML content for the node (will trigger a node replacement).
+     * @param {Object} [delta.style]       An object containing CSS style properties to update. Values can include '!important'.
+     * @param {String} [delta.textContent] The new text content for the node (replaces innerHTML if present).
      */
     updateNode(delta) {
         let me   = this,
@@ -380,10 +436,16 @@ class DeltaUpdates extends Base {
     }
 
     /**
+     * Updates the text content of a virtual text node within the DOM.
+     * Virtual text nodes are rendered within the DOM as a pair of HTML comments,
+     * with their content embedded between them. This method locates the specific
+     * text node by its ID (embedded in the start comment tag) within its parent's
+     * innerHTML and replaces its content using a regular expression.
+     *
      * @param {Object} delta
-     * @param {String} delta.id
-     * @param {String} delta.parentId
-     * @param {String} delta.value
+     * @param {String} delta.id       The unique ID of the virtual text node, which is embedded in its opening comment tag.
+     * @param {String} delta.parentId The ID of the parent DOM node whose `innerHTML` contains the virtual text node.
+     * @param {String} delta.value    The new text content to be applied to the virtual text node.
      */
     updateVtext({id, parentId, value}) {
         let node      = DomAccess.getElement(parentId),
@@ -395,17 +457,24 @@ class DeltaUpdates extends Base {
     }
 
     /**
+     * Applies a set of VDom delta updates to the real DOM.
+     * This method is the core entry point for rendering changes initiated from the VDom worker.
+     * It iterates through the provided deltas and dispatches them to specific DOM manipulation
+     * methods (e.g., insertNode, removeNode, updateNode) based on their `action` property.
+     * This method expects the appropriate renderer (DomApiRenderer or StringBasedRenderer)
+     * to be loaded based on `Neo.config.useDomApiRenderer`.
+     *
      * @param {Object} data
-     * @param {Object|Object[]} data.deltas
-     * @param {String} data.id
-     * @param {String} [data.origin='app']
+     * @param {Object|Object[]} data.deltas An array of delta objects, or a single delta object,
+     * representing changes to be applied to the DOM.
+     * Each delta object contains an `action` property
+     * (e.g., 'insertNode', 'removeNode', 'updateNode', 'moveNode')
+     * and additional properties relevant to the specific action.
+     * @param {String} data.id             The unique ID of the request, used for sending a reply back to the origin.
+     * @param {String} [data.origin='app'] The origin of the message (e.g., 'app'), used for sending replies.
      */
     update(data) {
-        // This method is synchronous and *expects* the renderer to be loaded
-        if (!this.#renderer) {
-            console.error('DeltaUpdates renderer not ready during insertNode!');
-            return
-        }
+        this.checkRendererAvailability();
 
         let me       = this,
             {deltas} = data,
