neo.mjs 10.0.0-beta.1 → 10.0.0-beta.2

package/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,19 +54,6 @@ 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
@@ -68,11 +61,10 @@ class DeltaUpdates extends Base {
     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,
@@ -80,24 +72,6 @@ class DeltaUpdates extends Base {
         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,26 +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 {String} [delta.id]
-     * @param {String} [delta.value
-     */
-    setTextContent({id, value}) {
-        let node = DomAccess.getElement(id);
-
-        if (node) {
-            node.textContent = value
-        }
-    }
-
-    /**
-     * @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,
@@ -384,16 +427,25 @@ class DeltaUpdates extends Base {
                             })
                         }
                         break
+                    case 'textContent':
+                        node.textContent = value;
+                        break
                 }
             })
         }
     }
 
     /**
+     * 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),
@@ -405,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,

package/src/main/addon/AmCharts.mjs

@@ -37,6 +37,18 @@ class AmCharts extends Base {
          * @protected
          */
         fallbackPath: 'https://raw.githubusercontent.com/neomjs/pages/main/resources_pub/amCharts/',
+        /**
+         * List methods which must get cached until the addon reaches its `isReady` state
+         * @member {String[]} interceptRemotes
+         */
+        interceptRemotes: [
+            'callMethod',
+            'create',
+            'destroy',
+            'setProperties',
+            'setProperty',
+            'updateData'
+        ],
         /**
          * Remote method access for other workers
          * @member {Object} remote
@@ -91,19 +103,15 @@ class AmCharts extends Base {
     callMethod(data) {
         let me = this;
 
-        if (!me.isReady) {
-            return me.cacheMethodCall({fn: 'callMethod', data})
-        } else {
-            if (me.hasChart(data.id)) {
-                let chart      = me.charts[data.id],
-                    pathArray  = data.path.split('.'),
-                    methodName = pathArray.pop(),
-                    scope      = pathArray.length < 1 ? chart:  Neo.ns(pathArray.join('.'), false, chart);
+        if (me.hasChart(data.id)) {
+            let chart      = me.charts[data.id],
+                pathArray  = data.path.split('.'),
+                methodName = pathArray.pop(),
+                scope      = pathArray.length < 1 ? chart:  Neo.ns(pathArray.join('.'), false, chart);
 
-                scope[methodName].call(scope, ...data.params || [])
-            } else {
-                // todo
-            }
+            scope[methodName].call(scope, ...data.params || [])
+        } else {
+            // todo
         }
     }
 
@@ -137,29 +145,25 @@ class AmCharts extends Base {
     create(data) {
         let me = this;
 
-        if (!me.isReady) {
-            return me.cacheMethodCall({fn: 'create', data})
-        } else {
-            // todo: check if globalThis[data.package] exists, if not load it and call create afterwards
-            am4core.useTheme(am4themes_dark);
+        // todo: check if globalThis[data.package] exists, if not load it and call create afterwards
+        am4core.useTheme(am4themes_dark);
 
-            me.charts[data.id] = am4core.createFromConfig(data.config, data.id, globalThis[data.package][data.type || 'XYChart']);
+        me.charts[data.id] = am4core.createFromConfig(data.config, data.id, globalThis[data.package][data.type || 'XYChart']);
 
-            if (data.combineSeriesTooltip) {
-                me.combineSeriesTooltip(me.charts[data.id])
-            }
+        if (data.combineSeriesTooltip) {
+            me.combineSeriesTooltip(me.charts[data.id])
+        }
 
-            // in case data has arrived before the chart got created, apply it now
-            if (data.data) {
-                me.updateData({
-                    data    : data.data,
-                    dataPath: data.dataPath,
-                    id      : data.id
-                })
-            } else if (me.dataMap[data.id]) {
-                me.updateData(me.dataMap[data.id]);
-                delete me.dataMap[data.id]
-            }
+        // in case data has arrived before the chart got created, apply it now
+        if (data.data) {
+            me.updateData({
+                data    : data.data,
+                dataPath: data.dataPath,
+                id      : data.id
+            })
+        } else if (me.dataMap[data.id]) {
+            me.updateData(me.dataMap[data.id]);
+            delete me.dataMap[data.id]
         }
     }
 
@@ -167,15 +171,9 @@ class AmCharts extends Base {
      * @param {Object} data
      * @param {String} data.id
      */
-    destroy(data) {
-        let me = this;
-
-        if (!me.isReady) {
-            return me.cacheMethodCall({fn: 'destroy', data})
-        } else {
-            me.charts[data.id]?.dispose?.();
-            delete me.charts[data.id]
-        }
+    destroy({id}) {
+        this.charts[id]?.dispose?.();
+        delete this.charts[id]
     }
 
     /**
@@ -229,20 +227,10 @@ class AmCharts extends Base {
      * @param {String} data.id
      * @param {Object} data.properties
      */
-    setProperties(data) {
-        let me = this;
-
-        if (!me.isReady) {
-            return me.cacheMethodCall({fn: 'setProperties', data})
-        } else {
-            Object.entries(data.properties).forEach(([key, value]) => {
-                me.setProperty({
-                    id   : data.id,
-                    path : key,
-                    value
-                })
-            })
-        }
+    setProperties({id, properties}) {
+        Object.entries(properties).forEach(([key, value]) => {
+            this.setProperty({id, path: key, value})
+        })
     }
 
     /**
@@ -252,22 +240,16 @@ class AmCharts extends Base {
      * @param {String} data.path
      * @param {*} data.value
      */
-    setProperty(data) {
-        let me = this;
-
-        if (!me.isReady) {
-            return me.cacheMethodCall({fn: 'setProperty', data})
+    setProperty({id, isColor=false, path, value}) {
+        if (this.hasChart(id)) {
+            let chart        = this.charts[id],
+                pathArray    = path.split('.'),
+                propertyName = pathArray.pop(),
+                scope        = Neo.ns(pathArray.join('.'), false, chart);
+
+            scope[propertyName] = isColor ? am4core.color(value) : value
         } else {
-            if (this.hasChart(data.id)) {
-                let chart        = this.charts[data.id],
-                    pathArray    = data.path.split('.'),
-                    propertyName = pathArray.pop(),
-                    scope        = Neo.ns(pathArray.join('.'), false, chart);
-
-                scope[propertyName] = data.isColor ? am4core.color(data.value) : data.value
-            } else {
-                // todo
-            }
+            // todo
         }
     }
 
@@ -280,9 +262,7 @@ class AmCharts extends Base {
     updateData(data) {
         let me = this;
 
-        if (!me.isReady) {
-            return me.cacheMethodCall({fn: 'updateData', data})
-        } else if (!me.hasChart(data.id)) {
+        if (!me.hasChart(data.id)) {
             me.dataMap[data.id] = data
         } else {
             let chart = me.charts[data.id];

package/src/main/addon/Base.mjs

@@ -179,6 +179,17 @@ class Base extends CoreBase {
      */
     async loadFiles() {}
 
+    /**
+     * Handles intercepted remote method calls.
+     * If the addon is not ready, the call is cached using `cacheMethodCall()`.
+     * Otherwise, the original method is executed.
+     * @param {Object} msg The remote message object.
+     * @returns {Promise<any>} A promise that resolves with the method's return value.
+     */
+    onInterceptRemotes(msg) {
+        return this.cacheMethodCall({fn: msg.remoteMethod, data: msg.data})
+    }
+
     /**
      * Sequentially processes any method calls that were cached while the addon was not ready.
      * This method is asynchronous to allow awaiting the execution of individual cached methods.