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

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;

package/src/core/Config.mjs

@@ -0,0 +1,139 @@
+import {isDescriptor} from './ConfigSymbols.mjs';
+
+/**
+ * @src/util/ClassSystem.mjs Neo.core.Config
+ * @private
+ * @internal
+ *
+ * Represents an observable container for a config property.
+ * This class manages the value of a config, its subscribers, and custom behaviors
+ * like merge strategies and equality checks defined via a descriptor object.
+ *
+ * The primary purpose of this class is to enable fine-grained reactivity and
+ * decoupled cross-instance state sharing within the Neo.mjs framework.
+ */
+class Config {
+    /**
+     * The internal value of the config property.
+     * @private
+     * @apps/portal/view/about/MemberContainer.mjs {any} #value
+     */
+    #value;
+
+    /**
+     * A Set to store callback functions that subscribe to changes in this config's value.
+     * @private
+     * @apps/portal/view/about/MemberContainer.mjs {Set<Function>} #subscribers
+     */
+    #subscribers = new Set();
+
+    /**
+     * The strategy to use when merging new values into this config.
+     * Defaults to 'deep'. Can be overridden via a descriptor.
+     * @apps/portal/view/about/MemberContainer.mjs {string} mergeStrategy
+     */
+    mergeStrategy = 'deep';
+
+    /**
+     * The function used to compare new and old values for equality.
+     * Defaults to `Neo.isEqual`. Can be overridden via a descriptor.
+     * @apps/portal/view/about/MemberContainer.mjs {Function} isEqual
+     */
+    isEqual = Neo.isEqual;
+
+    /**
+     * Creates an instance of Config.
+     * @param {any|Object} configObject - The initial value for the config.
+     */
+    constructor(configObject) {
+        if (Neo.isObject(configObject) && configObject[isDescriptor] === true) {
+            this.initDescriptor(configObject)
+        } else {
+            this.#value = configObject
+        }
+    }
+
+    /**
+     * Gets the current value of the config property.
+     * @returns {any} The current value.
+     */
+    get() {
+        return this.#value;
+    }
+
+    /**
+     * Initializes the `Config` instance using a descriptor object.
+     * Extracts `mergeStrategy` and `isEqual` from the descriptor.
+     * The internal `#value` is NOT set by this method.
+     * @param {Object} descriptor - The descriptor object for the config.
+     * @param {any} descriptor.value - The default value for the config (not set by this method).
+     * @param {string} [descriptor.merge='deep'] - The merge strategy.
+     * @param {Function} [descriptor.isEqual=Neo.isEqual] - The equality comparison function.
+     */
+    initDescriptor({isEqual, merge, value}) {
+        let me = this;
+
+        me.#value        = value
+        me.mergeStrategy = merge   || me.mergeStrategy;
+        me.isEqual       = isEqual || me.isEqual;
+    }
+
+    /**
+     * Notifies all subscribed callbacks about a change in the config's value.
+     * @param {any} newValue - The new value of the config.
+     * @param {any} oldValue - The old value of the config.
+     */
+    notify(newValue, oldValue) {
+        for (const callback of this.#subscribers) {
+            callback(newValue, oldValue);
+        }
+    }
+
+    /**
+     * Sets a new value for the config property.
+     * This method performs an equality check using `this.isEqual` before updating the value.
+     * If the value has changed, it updates `#value` and notifies all subscribers.
+     * @param {any} newValue - The new value to set.
+     * @returns {Boolean} True if the value changed, false otherwise.
+     */
+    set(newValue) {
+        if (newValue === undefined) return false; // Preserve original behavior for undefined
+
+        const
+            me       = this,
+            oldValue = me.#value;
+
+        // The setter automatically uses the configured equality check
+        if (!me.isEqual(newValue, oldValue)) {
+            me.#value = newValue;
+            me.notify(newValue, oldValue);
+            return true
+        }
+
+        return false
+    }
+
+    /**
+     * Sets the internal value of the config property directly, without performing
+     * an equality check or notifying subscribers.
+     * This method is intended for internal framework use where direct assignment
+     * is necessary (e.g., during initial setup or specific internal optimizations).
+     * @param {any} newValue - The new value to set directly.
+     */
+    setRaw(newValue) {
+        this.#value = newValue
+    }
+
+    /**
+     * Subscribes a callback function to changes in this config's value.
+     * The callback will be invoked with `(newValue, oldValue)` whenever the config changes.
+     * @param {Function} callback - The function to call when the config value changes.
+     * @returns {Function} A cleanup function to unsubscribe the callback.
+     */
+    subscribe(callback) {
+        this.#subscribers.add(callback);
+        return () => this.#subscribers.delete(callback)
+    }
+}
+
+export default Config;

package/src/core/ConfigSymbols.mjs

@@ -0,0 +1,3 @@
+
+// e.g., in a new file src/core/ConfigSymbols.mjs
+export const isDescriptor = Symbol.for('Neo.Config.isDescriptor');

package/src/core/Util.mjs

@@ -1,10 +1,7 @@
-import Base from './Base.mjs';
-
 /**
  * @class Neo.core.Util
- * @extends Neo.core.Base
  */
-class Util extends Base {
+class Util {
     /**
      * A regex to remove camel case syntax
      * @member {RegExp} decamelRegEx=/([a-z])([A-Z])/g
@@ -13,19 +10,6 @@ class Util extends Base {
      */
     static decamelRegEx = /([a-z])([A-Z])/g
 
-    static config = {
-        /**
-         * @member {String} className='Neo.core.Util'
-         * @protected
-         */
-        className: 'Neo.core.Util',
-        /**
-         * @member {String} ntype='core-util'
-         * @protected
-         */
-        ntype: 'core-util'
-    }
-
     /**
      * @param {Object} scope
      * @param {String[]} values
@@ -229,7 +213,8 @@ class Util extends Base {
     }
 }
 
-Util = Neo.setupClass(Util);
+const ns = Neo.ns('Neo.core', true);
+ns.Util = Util;
 
 // aliases
 Neo.applyFromNs(Neo, Util, {

package/src/data/RecordFactory.mjs

@@ -81,7 +81,7 @@ class RecordFactory extends Base {
                         return this[dataSymbol][fieldName]
                     },
                     set(value) {
-                        instance.setRecordFields({
+                        this.notifyChange({
                             fields: {[fieldPath]: instance.parseRecordValue({record: this, field, value})},
                             model,
                             record: this
@@ -193,6 +193,25 @@ class RecordFactory extends Base {
                         return null
                     }
 
+                    /**
+                     * The single source of truth for record field changes.
+                     * Executes instance.setRecordFields(), and can get used via:
+                     * - Neo.util.Function:createSequence()
+                     * - Neo.util.Function:intercept(),
+                     * to "listen" to field changes
+                     * @param {Object}         data
+                     * @param {Object}         data.fields
+                     * @param {Neo.data.Model} data.model
+                     * @param {Object}         data.record
+                     * @param {Boolean}        silent=false
+                     * @returns {Object}
+                     */
+                    notifyChange(data, silent=false) {
+                        const param = {...data, silent}
+                        instance.setRecordFields(param);
+                        return param
+                    }
+
                     /**
                      * Bulk-update multiple record fields at once
                      * @param {Object} fields
@@ -207,7 +226,7 @@ class RecordFactory extends Base {
                      * @param {Object} fields
                      */
                     set(fields) {
-                        instance.setRecordFields({fields, model, record: this})
+                        this.notifyChange({fields, model, record: this})
                     }
 
                     /**
@@ -225,7 +244,7 @@ class RecordFactory extends Base {
                      * @param {Object} fields
                      */
                     setSilent(fields) {
-                        instance.setRecordFields({fields, model, record: this, silent: true})
+                        this.notifyChange({fields, model, record: this}, true)
                     }
 
                     /**