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

package/src/component/Base.mjs

@@ -10,6 +10,7 @@ import Rectangle        from '../util/Rectangle.mjs';
 import Style            from '../util/Style.mjs';
 import VDomUtil         from '../util/VDom.mjs';
 import VNodeUtil        from '../util/VNode.mjs';
+import {isDescriptor}   from '../core/ConfigSymbols.mjs';
 
 const
     addUnits            = value => value == null ? value : isNaN(value) ? value : `${value}px`,
@@ -53,11 +54,15 @@ class Component extends Base {
         /**
          * The default alignment specification to position this Component relative to some other
          * Component, or Element or Rectangle. Only applies in case floating = true.
-         * @member {Object|String} align_={edgeAlign:'t-b',constrainTo:'document.body'}
+         * @member {Object|String} align_={[isDescriptor]: true, merge: 'deep', value: {edgeAlign: 't-b',constrainTo: 'document.body'}}
          */
         align_: {
-            edgeAlign  : 't-b',
-            constrainTo: 'document.body'
+            [isDescriptor]: true,
+            merge         : 'deep',
+            value: {
+                edgeAlign  : 't-b',
+                constrainTo: 'document.body'
+            }
         },
         /**
          * The name of the App this component belongs to
@@ -326,9 +331,13 @@ class Component extends Base {
         stateProvider_: null,
         /**
          * Style attributes added to this vdom root. see: getVdomRoot()
-         * @member {Object} style_=null
+         * @member {Object} style={[isDescriptor]: true, merge: 'shallow', value: null}
          */
-        style_: null,
+        style_: {
+            [isDescriptor]: true,
+            merge         : 'shallow',
+            value         : null
+        },
         /**
          * You can pass a used theme directly to any component,
          * to style specific component trees differently from your main view.
@@ -375,10 +384,16 @@ class Component extends Base {
         updateDepth_: 1,
         /**
          * The component vnode tree. Available after the component got rendered.
-         * @member {Object} vnode_=null
+         * @member {Object} vnode_=={[isDescriptor]: true, value: null, isEqual: (a, b) => a === b,}
          * @protected
          */
-        vnode_: null,
+        vnode_: {
+            [isDescriptor]: true,
+            clone         : 'none',
+            cloneOnGet    : 'none',
+            isEqual       : (a, b) => a === b, // vnode trees can be huge, and will get compared by the vdom worker.
+            value         : null,
+        },
         /**
          * Shortcut for style.width, defaults to px
          * @member {Number|String|null} width_=null
@@ -395,9 +410,13 @@ class Component extends Base {
         wrapperCls_: null,
         /**
          * Top level style attributes. Useful in case getVdomRoot() does not point to the top level DOM node.
-         * @member {Object|null} wrapperStyle_=null
+         * @member {Object|null} wrapperStyle_={[isDescriptor]: true, merge: 'shallow', value: null}
          */
-        wrapperStyle_: null,
+        wrapperStyle_: {
+            [isDescriptor]: true,
+            merge         : 'shallow',
+            value         : null
+        },
         /**
          * The vdom markup for this component.
          * @member {Object} _vdom={}
@@ -588,7 +607,12 @@ class Component extends Base {
     afterSetConfig(key, value, oldValue) {
         let me = this;
 
-        if (currentWorker.isUsingStateProviders && me[twoWayBindingSymbol] && oldValue !== undefined) {
+        if (Neo.isUsingStateProviders && me[twoWayBindingSymbol]) {
+            // When a component config is updated by its state provider, this flag is set to the config's key.
+            // This prevents circular updates in two-way data bindings by skipping the push back to the state provider.
+            if (me._skipTwoWayPush === key) {
+                return;
+            }
             let binding = me.bind?.[key];
 
             if (binding?.twoWay) {
@@ -646,21 +670,6 @@ class Component extends Base {
         }
     }
 
-    /**
-     * Triggered after the flex config got changed
-     * @param {Number|String|null} value
-     * @param {Number|String|null} oldValue
-     * @protected
-     */
-    afterSetFlex(value, oldValue) {
-        if (!isNaN(value)) {
-            value = `${value} ${value} 0%`
-        }
-
-        this.configuredFlex = value;
-        this.changeVdomRootKey('flex', value)
-    }
-
     /**
      * Triggered after the hasUnmountedVdomChanges config got changed
      * @param {Boolean} value
@@ -949,6 +958,16 @@ class Component extends Base {
         }
     }
 
+    /**
+     * Triggered after the stateProvider config got changed
+     * @param {Neo.state.Provider} value
+     * @param {Object|Neo.state.Provider|null} oldValue
+     * @protected
+     */
+    afterSetStateProvider(value, oldValue) {
+        value?.createBindings(this)
+    }
+
     /**
      * Triggered after the style config got changed
      * @param {Object} value
@@ -1242,8 +1261,7 @@ class Component extends Base {
             }
         }
 
-        // merge the incoming alignment specification into the configured default
-        return Neo.merge({}, value, me.constructor.config.align)
+        return value
     }
 
     /**
@@ -1803,7 +1821,7 @@ class Component extends Base {
      * @returns {Neo.state.Provider|null}
      */
     getStateProvider(ntype) {
-        if (!currentWorker.isUsingStateProviders) {
+        if (!Neo.isUsingStateProviders) {
             return null
         }
 
@@ -1940,16 +1958,11 @@ class Component extends Base {
     }
 
     /**
-     * We are using this method as a ctor hook here to add the initial state.Provider & controller.Component parsing
-     * @param {Object} config
-     * @param {Boolean} [preventOriginalConfig] True prevents the instance from getting an originalConfig property
+     * @param args
      */
-    initConfig(config, preventOriginalConfig) {
-        super.initConfig(config, preventOriginalConfig);
-
-        let me = this;
-
-        me.getStateProvider()?.parseConfig(me)
+    initConfig(...args) {
+        super.initConfig(...args);
+        this.getStateProvider()?.createBindings(this)
     }
 
     /**
@@ -2035,28 +2048,15 @@ class Component extends Base {
      * @returns {Object} config
      */
     mergeConfig(...args) {
-        let me     = this,
-            config = super.mergeConfig(...args),
-
-            // it should be possible to set custom configs for the vdom on instance level,
-            // however there will be already added attributes (e.g. id), so a merge seems to be the best strategy.
-            vdom = {...me._vdom || {}, ...config.vdom || {}};
+        let config = super.mergeConfig(...args),
+            vdom   = config.vdom || config._vdom || {};
 
-        // avoid any interference on prototype level
-        // does not clone existing Neo instances
-        me._vdom = Neo.clone(vdom, true, true);
-
-        if (config.style) {
-            // If we are passed an object, merge it with the class's own style
-            me.style = Neo.typeOf(config.style) === 'Object' ? {...config.style, ...me.constructor.config.style} : config.style
-        }
+        // It should be possible to modify root level vdom attributes on instance level.
+        // Note that vdom is not a real config, but implemented via get() & set().
+        this._vdom = Neo.clone({...vdom, ...this._vdom || {}}, true);
 
-        me.wrapperStyle = Neo.clone(config.wrapperStyle, false);
-
-        delete config.style;
         delete config._vdom;
         delete config.vdom;
-        delete config.wrapperStyle;
 
         return config
     }
@@ -2141,8 +2141,12 @@ class Component extends Base {
      *
      */
     onConstructed() {
-        super.onConstructed();
-        this.keys?.register(this)
+        super.onConstructed()
+
+        let me = this;
+
+        me.keys?.register(me);
+        me.getStateProvider()?.createBindings(me)
     }
 
     /**
@@ -2315,10 +2319,12 @@ class Component extends Base {
      * @param {Boolean} [mount] Mount the DOM after the vnode got created
      */
     async render(mount) {
-        let me              = this,
-            autoMount       = mount || me.autoMount,
-            {app}           = me,
-            {useVdomWorker} = Neo.config;
+        let me                            = this,
+            autoMount                     = mount || me.autoMount,
+            {app}                         = me,
+            {unitTestMode, useVdomWorker} = Neo.config;
+
+        if (unitTestMode) return;
 
         // Verify that the critical rendering path => CSS files for the new tree is in place
         if (autoMount && currentWorker.countLoadingThemeFiles !== 0) {
@@ -2632,6 +2638,11 @@ class Component extends Base {
      * @protected
      */
     updateVdom(resolve, reject) {
+        if (Neo.config.unitTestMode) {
+            reject?.();
+            return
+        }
+
         let me                              = this,
             {app, mounted, parentId, vnode} = me;
 

package/src/container/Base.mjs

@@ -1,12 +1,13 @@
-import Component  from '../component/Base.mjs';
-import LayoutBase from '../layout/Base.mjs';
-import LayoutCard from '../layout/Card.mjs';
-import LayoutFit  from '../layout/Fit.mjs';
-import LayoutGrid from '../layout/Grid.mjs';
-import LayoutHbox from '../layout/HBox.mjs';
-import LayoutVBox from '../layout/VBox.mjs';
-import Logger     from '../util/Logger.mjs';
-import NeoArray   from '../util/Array.mjs';
+import Component      from '../component/Base.mjs';
+import LayoutBase     from '../layout/Base.mjs';
+import LayoutCard     from '../layout/Card.mjs';
+import LayoutFit      from '../layout/Fit.mjs';
+import LayoutGrid     from '../layout/Grid.mjs';
+import LayoutHbox     from '../layout/HBox.mjs';
+import LayoutVBox     from '../layout/VBox.mjs';
+import Logger         from '../util/Logger.mjs';
+import NeoArray       from '../util/Array.mjs';
+import {isDescriptor} from '../core/ConfigSymbols.mjs';
 
 const byWeight = ({ weight : lhs = 0 }, { weight : rhs = 0 }) => lhs - rhs;
 
@@ -31,9 +32,15 @@ class Container extends Component {
          */
         baseCls: ['neo-container'],
         /**
-         * @member {Object} itemDefaults_=null
+         * Default configuration for child items within this container.
+         * This config uses a descriptor to enable deep merging with instance based itemDefaults.
+         * @member {Object} itemDefaults_={[isDescriptor]: true, merge: 'deep', value: null}
          */
-        itemDefaults_: null,
+        itemDefaults_: {
+            [isDescriptor]: true,
+            merge         : 'deep',
+            value         : null
+        },
         /**
          * An array or an object of config objects|instances|modules for each child component
          * @member {Object[]} items_=[]
@@ -85,7 +92,13 @@ class Container extends Component {
          *     ]
          * });
          */
-        items_: [],
+        items_: {
+            [isDescriptor]: true,
+            clone         : 'shallow',
+            cloneOnGet    : 'none',
+            isEqual       : () => false,
+            value         : []
+        },
         /**
          * It is crucial to define a layout before the container does get rendered.
          * Meaning: onConstructed() is the latest life-cycle point.
@@ -342,10 +355,7 @@ class Container extends Component {
                 }
 
                 item.set(config);
-
-                // In case an item got created outside a stateProvider based hierarchy, there might be bindings or string
-                // based listeners which still need to get resolved.
-                item.getStateProvider()?.parseConfig(item);
+                item.getStateProvider()?.createBindings(item);
                 break
             }
 
@@ -617,14 +627,8 @@ class Container extends Component {
             config = super.mergeConfig(...args),
             ctorItems;
 
-        // avoid any interference on prototype level
-        // does not clone existing Neo instances
-
-        if (config.itemDefaults) {
-            me._itemDefaults = Neo.clone(config.itemDefaults, true, true);
-            delete config.itemDefaults
-        }
-
+        // Avoid any interference on prototype level
+        // Does not clone existing Neo instances
         if (config.items) {
             ctorItems = me.constructor.config.items;
 

package/src/controller/Base.mjs

@@ -2,8 +2,11 @@ import Base        from '../core/Base.mjs';
 import HashHistory from '../util/HashHistory.mjs';
 
 const
-    amountSlashesRegex = /\//g,
-    routeParamRegex    = /{[^\s/]+}/g
+    regexAmountSlashes       = /\//g,
+    // Regex to extract the parameter name from a single route segment (e.g., {*itemId} -> itemId)
+    regexParamNameExtraction = /{(\*|\.\.\.)?([^}]+)}/,
+    // Regex to match route parameters like {paramName}, {*paramName}, or {...paramName}
+    regexRouteParam          = /{(\*|\.\.\.)?([^}]+)}/g;
 
 /**
  * @class Neo.controller.Base
@@ -22,25 +25,33 @@ class Controller extends Base {
          */
         ntype: 'controller',
         /**
-         * If the URL does not contain a hash value when creating this controller instance,
-         * neo will set this hash value for us.
+         * If the URL does not contain a hash value when this controller instance is created,
+         * Neo.mjs will automatically set this hash value, ensuring a default route is active.
          * @member {String|null} defaultHash=null
          */
         defaultHash: null,
         /**
+         * Specifies the handler method to be invoked when no other defined route matches the URL hash.
+         * This acts as a fallback for unhandled routes.
          * @member {String|null} defaultRoute=null
          */
         defaultRoute: null,
         /**
+         * Internal map of compiled regular expressions for each route, used for efficient hash matching.
+         * @protected
          * @member {Object} handleRoutes={}
          */
         handleRoutes: {},
         /**
+         * Defines the routing rules for the controller. Keys are route patterns, and values are either
+         * handler method names (String) or objects containing `handler` and optional `preHandler` method names.
+         * Route patterns can include parameters like `{paramName}` and wildcards like `{*paramName}` for nested paths.
          * @example
          * routes: {
          *     '/home'                         : 'handleHomeRoute',
          *     '/users/{userId}'               : {handler: 'handleUserRoute', preHandler: 'preHandleUserRoute'},
          *     '/users/{userId}/posts/{postId}': 'handlePostRoute',
+         *     '/learn/{*itemId}'              : 'onLearnRoute', // Captures nested paths like /learn/gettingstarted/Workspaces
          *     'default'                       : 'handleOtherRoutes'
          * }
          * @member {Object} routes_={}
@@ -49,16 +60,18 @@ class Controller extends Base {
     }
 
     /**
+     * Creates a new Controller instance and registers its `onHashChange` method
+     * to listen for changes in the browser's URL hash.
      * @param {Object} config
      */
     construct(config) {
         super.construct(config);
-
         HashHistory.on('change', this.onHashChange, this)
     }
 
     /**
-     * Triggered after the routes config got changed
+     * Processes the defined routes configuration, compiling route patterns into regular expressions
+     * for efficient matching and sorting them by specificity (more slashes first).
      * @param {Object} value
      * @param {Object} oldValue
      * @protected
@@ -78,7 +91,13 @@ class Controller extends Base {
             if (key.toLowerCase() === 'default'){
                 me.defaultRoute = value[key]
             } else {
-                me.handleRoutes[key] = new RegExp(key.replace(routeParamRegex, '([\\w-.]+)')+'$')
+                me.handleRoutes[key] = new RegExp(key.replace(regexRouteParam, (match, isWildcard, paramName) => {
+                    if (isWildcard || paramName.startsWith('*')) {
+                        return '(.*)'
+                    } else {
+                        return '([\\w-.]+)'
+                    }
+                }))
             }
         })
     }
@@ -88,21 +107,19 @@ class Controller extends Base {
      */
     destroy(...args) {
         HashHistory.un('change', this.onHashChange, this);
-
         super.destroy(...args)
     }
 
     /**
-     *
+     * @returns {Promise<void>}
      */
-    async onConstructed() {
+    async initAsync() {
+        await super.initAsync();
+
         let me                      = this,
             {defaultHash, windowId} = me,
             currentHash             = HashHistory.first(windowId);
 
-        // get outside the construction chain => a related cmp & vm has to be constructed too
-        await me.timeout(1);
-
         if (currentHash) {
             if (currentHash.windowId === windowId) {
                 await me.onHashChange(currentHash, null)
@@ -118,9 +135,10 @@ class Controller extends Base {
     }
 
     /**
-     * Placeholder method which gets triggered when the hash inside the browser url changes
-     * @param {Object} value
-     * @param {Object} oldValue
+     * Handles changes in the browser's URL hash. It identifies the most specific matching route
+     * and dispatches the corresponding handler, optionally executing a preHandler first.
+     * @param {Object} value - The new hash history entry.
+     * @param {Object} oldValue - The previous hash history entry.
      */
     async onHashChange(value, oldValue) {
         // We only want to trigger hash changes for the same browser window (SharedWorker context)
@@ -129,63 +147,67 @@ class Controller extends Base {
         }
 
         let me                     = this,
-            counter                = 0,
-            hasRouteBeenFound      = false,
             {handleRoutes, routes} = me,
             routeKeys              = Object.keys(handleRoutes),
-            routeKeysLength        = routeKeys.length,
-            arrayParamIds, arrayParamValues, handler, key, paramObject, preHandler, responsePreHandler, result, route;
+            bestMatch              = null,
+            bestMatchKey           = null,
+            bestMatchParams        = null;
 
-        while (routeKeysLength > 0 && counter < routeKeysLength && !hasRouteBeenFound) {
-            key                = routeKeys[counter];
-            handler            = null;
-            preHandler         = null;
-            responsePreHandler = null;
-            paramObject        = {};
-            result             = value.hashString.match(handleRoutes[key]);
+        for (let i = 0; i < routeKeys.length; i++) {
+            const key = routeKeys[i];
+            const result = value.hashString.match(handleRoutes[key]);
 
             if (result) {
-                arrayParamIds    = key.match(routeParamRegex);
-                arrayParamValues = result.splice(1, result.length - 1);
-
-                if (arrayParamIds && arrayParamIds.length !== arrayParamValues.length) {
-                    throw 'Number of IDs and number of Values do not match'
+                const
+                    arrayParamIds    = key.match(regexRouteParam),
+                    arrayParamValues = result.splice(1, result.length - 1),
+                    paramObject      = {};
+
+                if (arrayParamIds) {
+                    for (let j = 0; j < arrayParamIds.length; j++) {
+                        const paramMatch = arrayParamIds[j].match(regexParamNameExtraction);
+
+                        if (paramMatch) {
+                            const paramName = paramMatch[2];
+                            paramObject[paramName] = arrayParamValues[j];
+                        }
+                    }
                 }
 
-                for (let i = 0; arrayParamIds && i < arrayParamIds.length; i++) {
-                    paramObject[arrayParamIds[i].substring(1, arrayParamIds[i].length - 1)] = arrayParamValues[i]
+                // Logic to determine the best matching route:
+                // 1. Prioritize routes that match a longer string (more specific match).
+                // 2. If lengths are equal, prioritize routes with more slashes (deeper nesting).
+                if (!bestMatch || (result[0].length > bestMatch[0].length) ||
+                    (result[0].length === bestMatch[0].length && (key.match(regexAmountSlashes) || []).length > (bestMatchKey.match(regexAmountSlashes) || []).length)) {
+                    bestMatch = result;
+                    bestMatchKey = key;
+                    bestMatchParams = paramObject;
                 }
+            }
+        }
 
-                route = routes[key];
-
-                if (Neo.isString(route)) {
-                    handler            = route;
-                    responsePreHandler = true
-                } else if (Neo.isObject(route)) {
-                    handler    = route.handler;
-                    preHandler = route.preHandler
-                }
+        if (bestMatch) {
+            const route = routes[bestMatchKey];
+            let handler    = null,
+                preHandler = null;
 
-                hasRouteBeenFound = true
+            if (Neo.isString(route)) {
+                handler = route
+            } else if (Neo.isObject(route)) {
+                handler    = route.handler;
+                preHandler = route.preHandler
             }
 
-            counter++
-        }
+            let responsePreHandler = true;
 
-        // execute
-        if (hasRouteBeenFound) {
             if (preHandler) {
-                responsePreHandler = await me[preHandler]?.call(me, paramObject, value, oldValue)
-            } else {
-                responsePreHandler = true
+                responsePreHandler = await me[preHandler]?.call(me, bestMatchParams, value, oldValue)
             }
 
             if (responsePreHandler) {
-                await me[handler]?.call(me, paramObject, value, oldValue)
+                await me[handler]?.call(me, bestMatchParams, value, oldValue)
             }
-        }
-
-        if (routeKeys.length > 0 && !hasRouteBeenFound) {
+        } else {
             if (me.defaultRoute) {
                 me[me.defaultRoute]?.(value, oldValue)
             } else {
@@ -195,22 +217,24 @@ class Controller extends Base {
     }
 
     /**
-     * Placeholder method which gets triggered when an invalid route is called
-     * @param {Object} value
-     * @param {Object} oldValue
+     * Placeholder method invoked when no matching route is found for the current URL hash.
+     * Controllers can override this to implement custom behavior for unhandled routes.
+     * @param {Object} value - The current hash history entry.
+     * @param {Object} oldValue - The previous hash history entry.
      */
     onNoRouteFound(value, oldValue) {
 
     }
 
     /**
-     * Internal helper method to sort routes by their amount of slashes
-     * @param {String} route1
-     * @param {String} route2
-     * @returns {Number}
+     * Internal helper method to sort routes by their specificity.
+     * Routes with more slashes are considered more specific and are prioritized.
+     * @param {String} route1 - The first route string to compare.
+     * @param {String} route2 - The second route string to compare.
+     * @returns {Number} A negative value if route1 is more specific, a positive value if route2 is more specific, or 0 if they have equal specificity.
      */
     #sortRoutes(route1, route2) {
-        return (route1.match(amountSlashesRegex) || []).length - (route2.match(amountSlashesRegex)|| []).length
+        return (route1.match(regexAmountSlashes) || []).length - (route2.match(regexAmountSlashes)|| []).length
     }
 }