neo.mjs 10.0.0-alpha.2 → 10.0.0-alpha.4

package/src/vdom/Helper.mjs

@@ -37,6 +37,26 @@ class Helper extends Base {
         singleton: true
     }
 
+    /**
+     * @param {Object} config
+     */
+    construct(config) {
+        super.construct(config);
+
+        let me = this;
+
+        // Ensure Neo.currentWorker is defined before attaching listeners
+        Promise.resolve().then(async () => {
+            // Subscribe to global Neo.config changes for dynamic renderer switching.
+            Neo.currentWorker.on({
+                neoConfigChange: me.onNeoConfigChange,
+                scope          : me
+            });
+
+            await me.importUtil()
+        })
+    }
+
     /**
      * @param {Object}         config
      * @param {Object}         config.deltas
@@ -65,11 +85,11 @@ class Helper extends Base {
             keys = Object.keys(vnode);
 
             Object.keys(oldVnode).forEach(prop => {
-                if (!vnode.hasOwnProperty(prop)) {
+                if (!Object.hasOwn(vnode, prop)) {
                     keys.push(prop)
-                } else if (prop === 'attributes') { // find removed attributes
+                } else if (prop === 'attributes') { // Find removed attributes
                     Object.keys(oldVnode[prop]).forEach(attr => {
-                        if (!vnode[prop].hasOwnProperty(attr)) {
+                        if (!Object.hasOwn(vnode[prop], attr)) {
                             vnode[prop][attr] = null
                         }
                     })
@@ -85,13 +105,22 @@ class Helper extends Base {
                         attributes = {};
 
                         Object.entries(value).forEach(([key, value]) => {
-                            if (!(oldVnode.attributes.hasOwnProperty(key) && oldVnode.attributes[key] === value)) {
-                                if (value !== null && !Neo.isString(value) && Neo.isEmpty(value)) {
-                                    // ignore empty arrays & objects
-                                } else {
-                                    attributes[key] = value
-                                }
+                            const
+                                oldValue    = oldVnode.attributes[key],
+                                hasOldValue = Object.hasOwn(oldVnode.attributes, 'key');
+
+                            // If the attribute has an old value AND the value hasn't changed, skip.
+                            if (hasOldValue && oldValue === value) {
+                                return
+                            }
+
+                            // If the current value is null, or it's a non-string empty value (e.g., [], {}), skip.
+                            // Note: An empty string ('') is a valid value and should NOT be skipped here.
+                            if (value !== null && !Neo.isString(value) && Neo.isEmpty(value)) {
+                                return
                             }
+
+                            attributes[key] = value
                         });
 
                         if (Object.keys(attributes).length > 0) {
@@ -148,7 +177,7 @@ class Helper extends Base {
     /**
      * Creates a Neo.vdom.VNode tree for the given vdom template.
      * The top level vnode contains the outerHTML as a string,
-     * in case Neo.config.useStringBasedMounting === true
+     * in case Neo.config.useDomApiRenderer === false
      * @param {Object} opts
      * @param {String} opts.appName
      * @param {Boolean} [opts.autoMount]
@@ -156,22 +185,24 @@ class Helper extends Base {
      * @param {Number} opts.parentIndex
      * @param {Object} opts.vdom
      * @param {Number} opts.windowId
-     * @returns {Promise<Object>}
+     * @returns {Object}
      */
-    async create(opts) {
-        let me = this,
+    create(opts) {
+        let me     = this,
+            {util} = Neo.vdom,
             returnValue, vnode;
 
-        await me.importDomApiVnodeCreator();
-        await me.importStringFromVnode();
-
         vnode       = me.createVnode(opts.vdom);
         returnValue = {...opts, vnode};
 
         delete returnValue.vdom;
 
-        if (NeoConfig.useStringBasedMounting) {
-            returnValue.outerHTML = Neo.vdom.util.StringFromVnode.create(vnode)
+        if (!NeoConfig.useDomApiRenderer) {
+            if (!util.StringFromVnode) {
+                throw new Error('VDom Helper render utilities are not loaded yet!')
+            }
+
+            returnValue.outerHTML = util.StringFromVnode.create(vnode)
         }
 
         return returnValue
@@ -303,10 +334,13 @@ class Helper extends Base {
             if (value !== undefined && value !== null && key !== 'flag' && key !== 'removeDom') {
                 let hasUnit, newValue, style;
 
-                switch(key) {
+                switch (key) {
                     case 'tag':
                         node.nodeName = value;
                         break
+                    case 'cls':
+                        node.className = value;
+                        break
                     case 'html':
                         node.innerHTML = value.toString(); // support for numbers
                         break
@@ -333,13 +367,7 @@ class Helper extends Base {
 
                         node.childNodes = newValue;
                         break
-                    case 'cls':
-                        if (value && !Array.isArray(value)) {
-                            node.className = [value]
-                        } else if (!(Array.isArray(value) && value.length < 1)) {
-                            node.className = value
-                        }
-                        break
+
                     case 'data':
                         if (value && Neo.typeOf(value) === 'Object') {
                             Object.entries(value).forEach(([key, val]) => {
@@ -472,24 +500,23 @@ class Helper extends Base {
     }
 
     /**
-     * Only import for the DOM API based mount adapter.
+     * Imports either (if not already imported):
+     * `Neo.vdom.util.DomApiVnodeCreator` if Neo.config.useDomApiRenderer === true
+     * `Neo.vdom.util.StringFromVnode`    if Neo.config.useDomApiRenderer === false
      * @returns {Promise<void>}
      * @protected
      */
-    async importDomApiVnodeCreator() {
-        if (!NeoConfig.useStringBasedMounting && !Neo.vdom.util?.DomApiVnodeCreator) {
-            await import('./util/DomApiVnodeCreator.mjs')
-        }
-    }
+    async importUtil() {
+        const {util} = Neo.vdom;
 
-    /**
-     * Only import for the string based mount adapter.
-     * @returns {Promise<void>}
-     * @protected
-     */
-    async importStringFromVnode() {
-        if (NeoConfig.useStringBasedMounting && !Neo.vdom.util?.StringFromVnode) {
-            await import('./util/StringFromVnode.mjs')
+        if (NeoConfig.useDomApiRenderer) {
+            if (!util?.DomApiVnodeCreator) {
+                await import('./util/DomApiVnodeCreator.mjs')
+            }
+        } else {
+            if (!util?.StringFromVnode) {
+                await import('./util/StringFromVnode.mjs')
+            }
         }
     }
 
@@ -514,12 +541,12 @@ class Helper extends Base {
 
         Object.assign(delta, {hasLeadingTextChildren, index: physicalIndex});
 
-        if (NeoConfig.useStringBasedMounting) {
-            // For string-based mounting, pass a string excluding moved nodes
-            delta.outerHTML = Neo.vdom.util.StringFromVnode.create(vnode, movedNodes)
-        } else {
+        if (NeoConfig.useDomApiRenderer) {
             // For direct DOM API mounting, pass the pruned VNode tree
             delta.vnode = Neo.vdom.util.DomApiVnodeCreator.create(vnode, movedNodes)
+        } else {
+            // For string-based mounting, pass a string excluding moved nodes
+            delta.outerHTML = Neo.vdom.util.StringFromVnode.create(vnode, movedNodes)
         }
 
         deltas.default.push(delta);
@@ -603,6 +630,18 @@ class Helper extends Base {
         this.createDeltas({deltas, oldVnode: movedNode.vnode, oldVnodeMap, vnode, vnodeMap})
     }
 
+    /**
+     * Handler for global Neo.config changes.
+     * If 'useDomApiRenderer' property changes, this method dynamically loads/clears the renderer utilities.
+     * @param {Object} config
+     * @return {Promise<void>}
+     */
+    async onNeoConfigChange(config) {
+        if(Object.hasOwn(config, 'useDomApiRenderer')) {
+            await this.importUtil()
+        }
+    }
+
     /**
      * @param {Object}         config
      * @param {Object}         config.deltas
@@ -633,14 +672,22 @@ class Helper extends Base {
      * @param {Object} opts
      * @param {Object} opts.vdom
      * @param {Object} opts.vnode
-     * @returns {Promise<Object>}
+     * @returns {Object}
      */
-    async update(opts) {
-        let me = this,
+    update(opts) {
+        let me     = this,
+            {util} = Neo.vdom,
             deltas, vnode;
 
-        await me.importDomApiVnodeCreator();
-        await me.importStringFromVnode();
+        if (NeoConfig.useDomApiRenderer) {
+            if (!util.DomApiVnodeCreator) {
+                throw new Error('Neo.vdom.Helper: DomApiVnodeCreator is not loaded yet for updates!')
+            }
+        } else {
+            if (!util.StringFromVnode) {
+                throw new Error('Neo.vdom.Helper: StringFromVnode is not loaded yet for updates!');
+            }
+        }
 
         vnode  = me.createVnode(opts.vdom);
         deltas = me.createDeltas({oldVnode: opts.vnode, vnode});

package/src/vdom/VNode.mjs

@@ -76,7 +76,7 @@ class VNode {
         } else {
             Object.assign(me, {
                 attributes: config.attributes || {},
-                className : config.className  || [],
+                className : normalizeClassName(config.className),
                 nodeName  : config.nodeName   || 'div',
                 style     : config.style
             });
@@ -88,7 +88,7 @@ class VNode {
 
             // We only apply textContent, in case it has content
             else if (Object.hasOwn(config, 'textContent')) {
-                me.textContent = Neo.config.useStringBasedMounting ? StringUtil.escapeHtml(textContent) : textContent
+                me.textContent = Neo.config.useDomApiRenderer ? textContent : StringUtil.escapeHtml(textContent)
             }
         }
 
@@ -99,6 +99,42 @@ class VNode {
     }
 }
 
+/**
+ * vdom cls definitions might contain spaces, especially when it comes to iconCls.
+ * @example: myVdom = {cls: ['my-button', 'fa fa-user']}
+ *
+ * On DOM level, classList.add() will throw, in case it gets an input containing a space.
+ *
+ * This is a module-scoped utility function, not a method of the VNode class.
+ * VNodes are transferred via structured cloning (e.g., in postMessage()), which strips methods.
+ * Keeping this logic separate from the VNode class itself ensures conceptual purity and a cleaner data model,
+ * as methods defined on the VNode instance would be lost during transfer anyway.
+ *
+ * @param {String|String[]} classNameInput
+ * @returns {String[]}
+ * @private
+ */
+function normalizeClassName(classNameInput) {
+    let normalizedClasses = [];
+
+    if (Neo.isString(classNameInput)) {
+        normalizedClasses = classNameInput.split(' ').filter(Boolean)
+    } else if (Array.isArray(classNameInput)) {
+        classNameInput.forEach(cls => {
+            if (Neo.isString(cls)) {
+                if (cls.includes(' ')) {
+                    normalizedClasses.push(...cls.split(' ').filter(Boolean))
+                } else if (cls !== '') {
+                    normalizedClasses.push(cls)
+                }
+            }
+        })
+    }
+
+    // Remove duplicates if necessary
+    return [...new Set(normalizedClasses)]
+}
+
 const ns = Neo.ns('Neo.vdom', true);
 ns.VNode = VNode;
 

package/src/worker/App.mjs

@@ -35,7 +35,8 @@ class App extends Base {
                 'destroyNeoInstance',
                 'fireEvent',
                 'getConfigs',
-                'setConfigs'
+                'setConfigs',
+                'setGlobalConfig' // points to worker.Base: setGlobalConfig()
             ]
         },
         /**

package/src/worker/Base.mjs

@@ -71,8 +71,9 @@ class Worker extends Base {
             gt.onmessage = me.onMessage.bind(me)
         }
 
-        Neo.currentWorker = me;
-        Neo.workerId      = me.workerId
+        Neo.currentWorker   = me;
+        Neo.setGlobalConfig = me.setGlobalConfig.bind(me);
+        Neo.workerId        = me.workerId
     }
 
     /**
@@ -220,10 +221,17 @@ class Worker extends Base {
     }
 
     /**
-     * @param {Object} msg
+     * Handles the initial registration of the `Neo.config` for this worker's realm.
+     * Triggered when receiving a worker message with `{action: 'registerNeoConfig'}` from the Main Thread's `Neo.worker.Manager`.
+     * This method is primarily responsible for setting the initial global `Neo.config` object in this worker's scope
+     * upon its creation. It also handles associating `windowId` with `MessagePort`s for Shared Workers.
+     *
+     * @param {Object} msg The incoming message object.
+     * @param {Object} msg.data The initial global Neo.config data object.
+     * @param {Number} msg.data.windowId The unique ID of the window/tab (relevant for SharedWorkers).
      */
     onRegisterNeoConfig(msg) {
-        Neo.config = Neo.config || {};
+        Neo.ns('Neo.config', true);
 
         let me         = this,
             {windowId} = msg.data,
@@ -236,7 +244,29 @@ class Worker extends Base {
             }
         }
 
-        Object.assign(Neo.config, msg.data)
+        Neo.merge(Neo.config, msg.data)
+    }
+
+    /**
+     * Handles runtime updates to the global `Neo.config` for this worker's realm.
+     * This method is triggered when receiving a worker message with `{action: 'setNeoConfig'}`
+     * from the Main Thread's `Neo.worker.Manager`. This message signifies a global config change
+     * that originated either from this worker's Main Thread or was broadcast from another
+     * connected browser window via a Shared Worker.
+     *
+     * It merges the incoming configuration changes into this worker's local `Neo.config`
+     * and fires a local `neoConfigChange` event, allowing other instances within this worker
+     * to react to the updated configuration.
+     *
+     * @param {Object} msg The destructured arguments from the message payload.
+     * @param {Object} msg.config The partial or full `Neo.config` object to merge.
+     */
+    onSetNeoConfig({config}) {
+        let me = this;
+
+        Neo.merge(Neo.config, config);
+
+        me.fire('neoConfigChange', config)
     }
 
     /**
@@ -307,6 +337,58 @@ class Worker extends Base {
 
         return message
     }
+
+    /**
+     * Initiates a global Neo.config change from a worker's context.
+     * This method is exposed globally as `Neo.setGlobalConfig` within each worker realm.
+     *
+     * It orchestrates the propagation of the config change to the Main Thread
+     * and, if a Shared Worker is active, across all connected browser windows,
+     * ensuring a single, consistent Neo.config state everywhere.
+     *
+     * You can pass a partial config object to update specific keys.
+     * For nested objects, Neo.mjs performs a deep merge.
+     *
+     * @param {Object} config The partial or full Neo.config object with changes to apply.
+     */
+    setGlobalConfig(config) {
+        const
+            me        = this,
+            {Manager} = Neo.worker; // Remote access proxy object
+
+        // Apply the config change locally to this worker's Neo.config and
+        // trigger its local change events immediately. This ensures immediate
+        // feedback and an updated state for the worker that initiated the change.
+        me.onSetNeoConfig({config});
+
+        if (me.isSharedWorker) {
+            // This block executes when the calling worker instance is a Shared Worker.
+            // This happens if `Neo.config.useSharedWorkers` is true, meaning App, VDom,
+            // Data, Canvas, and Task workers are all SharedWorker instances.
+            // This Shared Worker (the one where setGlobalConfig was called) acts as the
+            // central point to inform all connected Main Threads (browser windows).
+            me.ports.forEach((port, index) => {
+                // Send the config change to each connected Main Thread.
+                // The `broadcast` flag is crucial here for the *receiving* Main Thread:
+                // - `broadcast: true` (for the first port/Main Thread in the list): This Main Thread
+                //   will apply the config locally and is then responsible for propagating it to *all*
+                //   its own associated Shared Workers connected to that Main Thread),
+                //   **excluding the worker that originated this change**.
+                // - `broadcast: false` (for all other ports/Main Threads): These Main Threads
+                //   will simply apply the config locally and stop. They are passive recipients
+                //   of the broadcast, synchronizing their state without initiating further actions back.
+                // The `excludeOrigin` parameter ensures the originating worker doesn't receive a redundant broadcast.
+                Manager.setNeoConfig({broadcast: index < 1, config, excludeOrigin: me.workerId, windowId: port.windowId})
+            })
+        } else {
+            // This Dedicated Worker (the one where setGlobalConfig was called) informs
+            // its single, connected Main Thread. The Main Thread will then:
+            // 1. Apply the config locally.
+            // 2. Broadcast this change to *all* other Dedicated Workers connected to
+            //    *that same Main Thread*, **excluding the sender worker itself**.
+            Manager.setNeoConfig({broadcast: true, config, excludeOrigin: me.workerId})
+        }
+    }
 }
 
 export default Neo.setupClass(Worker);

package/src/worker/Manager.mjs

@@ -27,11 +27,6 @@ class Manager extends Base {
          * @protected
          */
         className: 'Neo.worker.Manager',
-        /**
-         * @member {Boolean} singleton=true
-         * @protected
-         */
-        singleton: true,
         /**
          * @member {Number} activeWorkers=0
          * @protected
@@ -51,12 +46,29 @@ class Manager extends Base {
          * @member {String[]|Neo.core.Base[]|null} mixins=[Observable, RemoteMethodAccess]
          */
         mixins: [Observable, RemoteMethodAccess],
+        /**
+         * Remote method access for other workers
+         * @member {Object} remote
+         * @protected
+         */
+        remote: {
+            app   : ['setNeoConfig'],
+            canvas: ['setNeoConfig'],
+            data  : ['setNeoConfig'],
+            task  : ['setNeoConfig'],
+            vdom  : ['setNeoConfig']
+        },
         /**
          * True in case the current browser supports window.SharedWorker.
          * @member {Boolean} sharedWorkersEnabled=false
          * @protected
          */
         sharedWorkersEnabled: false,
+        /**
+         * @member {Boolean} singleton=true
+         * @protected
+         */
+        singleton: true,
         /**
          * Internal flag to stop the worker communication in case their creation fails
          * @member {Boolean} stopCommunication=false
@@ -71,7 +83,7 @@ class Manager extends Base {
          */
         webWorkersEnabled: false,
         /**
-         * Using the current timestamp as an unique window identifier
+         * Using the current timestamp as a unique window identifier
          * @member {Number} windowId=new Date().getTime()
          * @protected
          */
@@ -121,7 +133,8 @@ class Manager extends Base {
 
         !Neo.insideWorker && me.createWorkers();
 
-        Neo.workerId = 'main';
+        Neo.setGlobalConfig = me.setGlobalConfig.bind(me);
+        Neo.workerId        = 'main';
 
         me.promises = {};
 
@@ -136,18 +149,18 @@ class Manager extends Base {
 
     /**
      * Sends a message to each worker defined inside the this.workers config.
-     * @param {Object} msg
+     * Only sends to workers that are currently active and available.
+     * @param {Object} msg             The message payload to broadcast.
+     * @param {Object} [excludeOrigin] Optionally pass the origin realm name to exclude from the broadcast.
      */
-    broadcast(msg) {
-        Object.keys(this.workers).forEach(name => {
-            if (!(
-                name === 'canvas' && !NeoConfig.useCanvasWorker ||
-                name === 'task'   && !NeoConfig.useTaskWorker   ||
-                name === 'vdom'   && !NeoConfig.useVdomWorker
-            )) {
-                this.sendMessage(name, msg)
+    broadcast(msg, excludeOrigin) {
+        let me = this;
+
+        Object.keys(me.workers).forEach(name => {
+            if (name !== excludeOrigin && me.getWorker(name)) {
+                me.sendMessage(name, msg)
             }
-        });
+        })
     }
 
     /**
@@ -325,8 +338,10 @@ class Manager extends Base {
                     data = data.data
                 }
 
-                promise[data.reject ? 'reject' : 'resolve'](data);
-                delete me.promises[replyId]
+                if (data) {
+                    promise[data.reject ? 'reject' : 'resolve'](data);
+                    delete me.promises[replyId]
+                }
             }
         }
 
@@ -385,7 +400,14 @@ class Manager extends Base {
 
         return new Promise((resolve, reject) => {
             let message = me.sendMessage(dest, opts, transfer),
-                msgId   = message.id;
+                msgId;
+
+            if (!message) {
+                reject(new Error(me.stopCommunication ? 'Communication is stopped.' : `Target worker '${dest}' does not exist.`));
+                return
+            }
+
+            msgId = message.id;
 
             me.promises[msgId] = {reject, resolve}
         })
@@ -412,7 +434,7 @@ class Manager extends Base {
      * @param {Array} [transfer] An optional array of Transferable objects to transfer ownership of.
      * If the ownership of an object is transferred, it becomes unusable (neutered) in the context it was sent from
      * and becomes available only to the worker it was sent to.
-     * @returns {Neo.worker.Message}
+     * @returns {Neo.worker.Message|null}
      * @protected
      */
     sendMessage(dest, opts, transfer) {
@@ -427,17 +449,53 @@ class Manager extends Base {
                 worker = me.getWorker(dest)
             }
 
-            if (!worker) {
-                throw new Error('Called sendMessage for a worker that does not exist: ' + dest)
+            if (worker) {
+                opts.destination = dest;
+
+                message = new Message(opts);
+
+                (worker.port ? worker.port : worker).postMessage(message, transfer);
+                return message
             }
+        }
+
+        return null
+    }
+
+    /**
+     * Initiates a global Neo.config change from the Main Thread.
+     *
+     * This method acts as a proxy, routing the config change request to the App Worker.
+     * This design centralizes the complex multi-threaded and multi-window synchronization
+     * logic within the App Worker's `setGlobalConfig` method.
+     *
+     * Developers should typically use `Neo.setGlobalConfig(config)` directly,
+     * which will correctly resolve to this proxy when called from the Main Thread.
+     *
+     * @param {Object} config The partial or full Neo.config object with changes to apply.
+     */
+    setGlobalConfig(config) {
+        // Remotely calls the App Worker's setGlobalConfig method.
+        // This ensures all global config changes are processed through the App Worker
+        // which contains the centralized multi-window synchronization logic.
+        Neo.worker.App.setGlobalConfig(config)
+    }
 
-            opts.destination = dest;
+    /**
+     * Change Neo.config globally from a worker
+     * @param {Object}  data
+     * @param {Boolean} data.broadcast
+     * @param {Object}  data.config
+     * @param {String}  [data.excludeOrigin]
+     */
+    setNeoConfig({broadcast, config, excludeOrigin}) {
+        let me = this;
 
-            message = new Message(opts);
+        Neo.merge(Neo.config, config);
 
-            (worker.port ? worker.port : worker).postMessage(message, transfer);
-            return message
-        }
+        me.fire('neoConfigChange', config);
+
+        broadcast && me.broadcast({action: 'setNeoConfig', config}, excludeOrigin)
     }
 }