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

package/src/collection/Base.mjs

@@ -48,6 +48,11 @@ class Collection extends Base {
          * @member {Boolean} autoSort=true
          */
         autoSort: true,
+        /**
+         * Stores the items.length of the items array in use
+         * @member {Number} count_=0
+         */
+        count_: 0,
         /**
          * Use 'primitive' for default filters, use 'advanced' for filters using a filterBy method
          * which need to iterate over other collection items
@@ -140,6 +145,17 @@ class Collection extends Base {
     }
 
     /**
+     * Triggered after the badgePosition config got changed
+     * @param {Number} value
+     * @param {Number} oldValue
+     * @protected
+     */
+    afterSetCount(value, oldValue) {
+        this.fire('countChange', {oldValue, value})
+    }
+
+    /**
+     * Triggered after the filters config got changed
      * @param {Array} value
      * @param {Array} oldValue
      * @protected
@@ -158,6 +174,7 @@ class Collection extends Base {
     }
 
     /**
+     * Triggered after the items config got changed
      * @param {Array} value
      * @param {Array} oldValue
      * @protected
@@ -174,10 +191,13 @@ class Collection extends Base {
                 item = value[i];
                 me.map.set(item[keyProperty], item)
             }
+
+            me.count = len
         }
     }
 
     /**
+     * Triggered after the sorters config got changed
      * @param {Array} value
      * @param {Array} oldValue
      * @protected
@@ -198,6 +218,7 @@ class Collection extends Base {
     }
 
     /**
+     * Triggered after the sourceId config got changed
      * @param {Number|String} value
      * @param {Number|String} oldValue
      * @protected
@@ -673,6 +694,7 @@ class Collection extends Base {
 
                 me.allItems = Neo.create(Collection, {
                     ...Neo.clone(config, true, true),
+                    id          : me.id + '-all',
                     keyProperty: me.keyProperty,
                     sourceId   : me.id
                 })
@@ -727,6 +749,8 @@ class Collection extends Base {
             me.doSort(me.items, true)
         }
 
+        me.count = me.items.length;
+
         me.fire('filter', {
             isFiltered: me[isFiltered],
             items     : me.items,
@@ -845,11 +869,12 @@ class Collection extends Base {
     }
 
     /**
-     * Returns the length of the internal items array
+     * Returns the config value of this.count
      * @returns {Number}
+     * @deprecated Use `this.count` directly instead.
      */
     getCount() {
-        return this._items.length
+        return this._count || 0 // skipping beforeGetCount() on purpose
     }
 
     /**
@@ -1238,6 +1263,8 @@ class Collection extends Base {
         }
 
         if (me[updatingIndex] === 0) {
+            me.count = me._items.length;
+
             me.fire('mutate', {
                 addedItems     : toAddArray,
                 preventBubbleUp: me.preventBubbleUp,

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`,
@@ -378,7 +379,11 @@ class Component extends Base {
          * @member {Object} vnode_=null
          * @protected
          */
-        vnode_: null,
+        vnode_: {
+            [isDescriptor]: true,
+            value         : null,
+            isEqual       : (a, b) => a === b // vnode trees can be huge, and will get compared by the vdom worker.
+        },
         /**
          * Shortcut for style.width, defaults to px
          * @member {Number|String|null} width_=null
@@ -646,21 +651,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

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
     }
 }
 

package/src/core/Base.mjs

@@ -1,4 +1,8 @@
 import {buffer, debounce, intercept, resolveCallback, throttle} from '../util/Function.mjs';
+import Compare                                                  from '../core/Compare.mjs';
+import Util                                                     from '../core/Util.mjs';
+import Config                                                   from './Config.mjs';
+import {isDescriptor}                                           from './ConfigSymbols.mjs';
 import IdGenerator                                              from './IdGenerator.mjs'
 
 const configSymbol       = Symbol.for('configSymbol'),
@@ -125,6 +129,12 @@ class Base {
         remote_: null
     }
 
+    /**
+     * A private field to store the Config controller instances.
+     * @member {Object} #configs={}
+     * @private
+     */
+    #configs = {};
     /**
      * Internal cache for all timeout ids when using this.timeout()
      * @member {Number[]} timeoutIds=[]
@@ -133,8 +143,39 @@ class Base {
     #timeoutIds = []
 
     /**
-     * Applies the observable mixin if needed, grants remote access if needed.
-     * @param {Object} config={}
+     * The main initializer for all Neo.mjs classes, invoked by `Neo.create()`.
+     * NOTE: This is not the native `constructor()`, which is called without arguments by `Neo.create()` first.
+     *
+     * This method orchestrates the entire instance initialization process, including
+     * the setup of the powerful and flexible config system.
+     *
+     * The `config` parameter is a single object that can contain different types of properties,
+     * which are processed in a specific order to ensure consistency and predictability:
+     *
+     * 1.  **Public Class Fields & Other Properties:** Any key in the `config` object that is NOT
+     *     defined in the class's `static config` hierarchy is considered a public field or a
+     *     dynamic property. These are assigned directly to the instance (`this.myField = value`)
+     *     at the very beginning. This is crucial so that subsequent config hooks (like `afterSet*`)
+     *     can access their latest values.
+     *
+     * 2.  **Reactive Configs:** A property is considered reactive if it is defined with a trailing
+     *     underscore (e.g., `myValue_`) in the `static config` of **any class in the inheritance
+     *     chain**. Subclasses can provide new default values for these configs without the
+     *     underscore, and they will still be reactive. Their values are applied via generated
+     *     setters, triggering `beforeSet*` and `afterSet*` hooks, and they are wrapped in a
+     *     `Neo.core.Config` instance to enable subscription-based reactivity.
+     *
+     * 3.  **Non-Reactive Configs:** Properties defined in `static config` without a trailing
+     *     underscore in their entire inheritance chain. Their default values are applied directly
+     *     to the class **prototype**, making them shared across all instances and allowing for
+     *     run-time modifications (prototypal inheritance). When a new value is passed to this
+     *     method, it creates an instance-specific property that shadows the prototype value.
+     *
+     * This method also initializes the observable mixin (if applicable) and schedules asynchronous
+     * logic like `initAsync()` (which handles remote method access) to run after the synchronous
+     * construction chain is complete.
+     *
+     * @param {Object} config={} The initial configuration object for the instance.
      */
     construct(config={}) {
         let me = this;
@@ -152,13 +193,9 @@ class Base {
             }
         });
 
-        me.createId(config.id || me.id);
+        me.id = config.id || IdGenerator.getId(this.getIdKey());
         delete config.id;
 
-        if (me.constructor.config) {
-            delete me.constructor.config.id
-        }
-
         me.getStaticConfig('observable') && me.initObservable(config);
 
         // assign class field values prior to configs
@@ -342,16 +379,6 @@ class Base {
         this.__proto__.constructor.overwrittenMethods[methodName].call(this, ...args)
     }
 
-    /**
-     * Uses the IdGenerator to create an id if a static one is not explicitly set.
-     * Registers the instance to manager.Instance if this one is already created,
-     * otherwise stores it inside a tmp map.
-     * @param {String} id
-     */
-    createId(id) {
-        this.id = id || IdGenerator.getId(this.getIdKey())
-    }
-
     /**
      * Unregisters this instance from Neo.manager.Instance
      * and removes all object entries from this instance
@@ -386,6 +413,22 @@ class Base {
         me.isDestroyed = true
     }
 
+    /**
+     * A public method to access the underlying Config controller.
+     * This enables advanced interactions like subscriptions.
+     * @param {String} key The name of the config property (e.g., 'items').
+     * @returns {Config|undefined} The Config instance, or undefined if not found.
+     */
+    getConfig(key) {
+        let me = this;
+
+        if (!me.#configs[key] && me.isConfig(key)) {
+            me.#configs[key] = new Config()
+        }
+
+        return me.#configs[key]
+    }
+
     /**
      * Used inside createId() as the default value passed to the IdGenerator.
      * Override this method as needed.
@@ -443,6 +486,7 @@ class Base {
 
         me.isConfiguring = true;
         Object.assign(me[configSymbol], me.mergeConfig(config, preventOriginalConfig));
+        delete me[configSymbol].id;
         me.processConfigs();
         me.isConfiguring = false;
     }
@@ -475,6 +519,17 @@ class Base {
         return !this.isDestroyed
     }
 
+    /**
+     * @param {String} key
+     * @returns {Boolean}
+     */
+    isConfig(key) {
+        // A config is considered "reactive" if it has a generated property setter
+        // AND it is present as a defined config in the merged static config hierarchy.
+        // Neo.setupClass() removes the underscore from the static config keys.
+        return Neo.hasPropertySetter(this, key) && (key in this.constructor.config);
+    }
+
     /**
      * Override this method to change the order configs are applied to this instance.
      * @param {Object} config

package/src/core/Compare.mjs

@@ -1,18 +1,7 @@
-import Base from '../core/Base.mjs';
-
 /**
  * @class Neo.core.Compare
- * @extends Neo.core.Base
  */
-class Compare extends Base {
-    static config = {
-        /**
-         * @member {String} className='Neo.core.Compare'
-         * @protected
-         */
-        className: 'Neo.core.Compare'
-    }
-
+class Compare {
     /**
      * Storing the comparison method names by data type
      * @member {Object} map
@@ -174,7 +163,8 @@ class Compare extends Base {
     }
 }
 
-Compare = Neo.setupClass(Compare);
+const ns = Neo.ns('Neo.core', true);
+ns.Compare = Compare;
 
 // alias
 Neo.isEqual = Compare.isEqual;