neo.mjs 10.0.0-alpha.3 → 10.0.0-alpha.5

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()
             ]
         },
         /**
@@ -45,11 +46,6 @@ class App extends Base {
         singleton: true
     }
 
-    /**
-     * @member {Object|null} data=null
-     * @protected
-     */
-    data = null
     /**
      * @member {Boolean} isUsingStateProviders=false
      * @protected
@@ -387,23 +383,16 @@ class App extends Base {
      * @param {Object} data
      */
     onLoadApplication(data) {
-        let me       = this,
-            {config} = Neo,
-            app, path;
-
-        if (data) {
-            me.data = data;
-            config.resourcesPath = data.resourcesPath
-        }
-
-        path = me.data.path;
+        let me        = this,
+            {config}  = Neo,
+            {appPath} = config;
 
         if (config.environment !== 'development') {
-            path = path.startsWith('/') ? path.substring(1) : path
+            appPath = appPath.startsWith('/') ? appPath.substring(1) : appPath
         }
 
-        me.importApp(path).then(module => {
-            app = module.onStart();
+        me.importApp(appPath).then(module => {
+            module.onStart();
 
             // short delay to ensure Component Controllers are ready
             config.hash && me.timeout(5).then(() => {

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);