neo.mjs 10.0.0-beta.5 → 10.0.0

package/src/Neo.mjs

@@ -293,11 +293,197 @@ Neo = globalThis.Neo = Object.assign({
         return instance
     },
 
+    /**
+     * Defines a reactive configuration property on a target object (prototype or instance).
+     * This method creates getters and setters that fully participate in Neo.mjs's reactive config system,
+     * including lifecycle hooks.
+     *
+     * @param {Neo.core.Base}  target        - The instance or prototype on which to define the config.
+     * @param {String}         key           - The name of the config property (without the '_' suffix).
+     * @param {*}             [initialValue] - The initial value for the config.
+     */
+    createConfig(target, key, initialValue) {
+        if (Neo.hasPropertySetter(target, key)) {
+            throw(
+`Invalid config in ${target.className}: '${key}_'. The config '${key}' is already defined as reactive by a parent class.
+To override the default value, use '${key}' (without the underscore) in your static config.
+If you intended to create custom logic, use the 'beforeGet${Neo.capitalize(key)}()', 'beforeSet${Neo.capitalize(key)}()', and 'afterSet${Neo.capitalize(key)}()' hooks instead of redefining the config.`
+            )
+        }
+
+        const
+            _key      = '_' + key,
+            uKey      = key[0].toUpperCase() + key.slice(1),
+            beforeGet = 'beforeGet' + uKey,
+            beforeSet = 'beforeSet' + uKey,
+            afterSet  = 'afterSet'  + uKey;
+
+        Neo[getSetCache] ??= {};
+
+        if (!Neo[getSetCache][key]) {
+            // Public Descriptor
+            Neo[getSetCache][key] = {
+                get() {
+                    let me        = this,
+                        config    = me.getConfig(key),
+                        hasNewKey = Object.hasOwn(me[configSymbol], key),
+                        newKey    = me[configSymbol][key],
+                        value     = hasNewKey ? newKey : me[_key];
+
+                    if (value instanceof Date) {
+                        value = new Date(value.valueOf());
+                    }
+                    // new, explicit opt-in path
+                    else if (config.cloneOnGet) {
+                        const {cloneOnGet} = config;
+
+                        if (cloneOnGet === 'deep') {
+                            value = Neo.clone(value, true, true);
+                        } else if (cloneOnGet === 'shallow') {
+                            const type = Neo.typeOf(value);
+
+                            if (type === 'Array') {
+                                value = [...value];
+                            } else if (type === 'Object') {
+                                value = {...value};
+                            }
+                        }
+                    }
+                    // legacy behavior
+                    else if (Array.isArray(value)) {
+                        value = [...value];
+                    }
+
+                    if (hasNewKey) {
+                        me[key] = value;  // We do want to trigger the setter => beforeSet, afterSet
+                        value = me[_key]; // Return the value parsed by the setter
+                        delete me[configSymbol][key]
+                    }
+
+                    if (typeof me[beforeGet] === 'function') {
+                        value = me[beforeGet](value)
+                    }
+
+                    return value
+                },
+                set(value) {
+                    if (value === undefined) return;
+
+                    const config = this.getConfig(key);
+                    if (!config) return;
+
+                    let me              = this,
+                        oldValue        = config.get(), // Get the old value from the Config instance
+                        {EffectManager} = Neo.core,
+                        isNewBatch      = !EffectManager?.isPaused();
+
+                    // If a config change is not triggered via `core.Base#set()`, honor changes inside hooks.
+                    isNewBatch && EffectManager?.pause();
+
+                    try {
+                        // 1. Prevent infinite loops:
+                        // Immediately remove the pending value from the configSymbol to prevent a getter from
+                        // recursively re-triggering this setter.
+                        delete me[configSymbol][key];
+
+                        switch (config.clone) {
+                            case 'deep':
+                                value = Neo.clone(value, true, true);
+                                break;
+                            case 'shallow':
+                                value = Neo.clone(value, false, true);
+                                break;
+                        }
+
+                        // 2. Create a temporary state for beforeSet hooks:
+                        // Set the new value directly on the private backing property. This allows any beforeSet
+                        // hook to access the new value of this and other configs within the same `set()` call.
+                        me[_key] = value;
+
+                        if (typeof me[beforeSet] === 'function') {
+                            value = me[beforeSet](value, oldValue);
+
+                            // If they don't return a value, that means no change
+                            if (value === undefined) {
+                                // Restore the original value if the update is canceled.
+                                me[_key] = oldValue;
+                                return
+                            }
+                        }
+
+                        // 3. Restore state for change detection:
+                        // Revert the private backing property to its original value. This is crucial for the
+                        // `config.set()` method to correctly detect if the value has actually changed.
+                        me[_key] = oldValue;
+
+                        // 4. Finalize the change:
+                        // The config.set() method performs the final check and, if the value changed,
+                        // triggers afterSet hooks and notifies subscribers.
+                        if (config.set(value)) {
+                            me[afterSet]?.(value, oldValue);
+                            me.afterSetConfig?.(key, value, oldValue)
+                        }
+                    } finally {
+                        // End the batch only if this setter started it.
+                        isNewBatch && EffectManager?.resume()
+                    }
+                }
+            };
+
+            // Private Descriptor
+            Neo[getSetCache][_key] = {
+                get() {
+                    return this.getConfig(key)?.get()
+                },
+                set(value) {
+                    this.getConfig(key)?.setRaw(value)
+                }
+            }
+        }
+
+        Object.defineProperty(target, key,  Neo[getSetCache][key]);
+        Object.defineProperty(target, _key, Neo[getSetCache][_key]);
+
+        if (initialValue !== undefined) {
+            target[key] = initialValue
+        }
+    },
+
     /**
      *
      */
     emptyFn() {},
 
+    /**
+     * Ensures a class is assigned to the Neo namespace only once, preventing duplicates.
+     * This is a lightweight version of `Neo.setupClass` for simple classes
+     * that do not extend `Neo.core.Base`.
+     * It follows a "first one wins" strategy.
+     *
+     * @param {Function|Object} module    - The class constructor or singleton object to register.
+     * @param {String}          classPath - The fully qualified name (e.g., 'Neo.core.Config').
+     * @param {Function}       [onFirst]  - An optional callback that runs only the first time the class is registered.
+     * @returns {Function|Object} The class or singleton from the Neo namespace (either the existing one or the newly set one).
+     */
+    gatekeep(module, classPath, onFirst) {
+        const existingClass = Neo.ns(classPath, false);
+
+        if (existingClass) {
+            return existingClass
+        }
+
+        const
+            nsArray   = classPath.split('.'),
+            className = nsArray.pop(),
+            parentNs  = Neo.ns(nsArray, true);
+
+        parentNs[className] = module;
+
+        onFirst?.(module);
+
+        return parentNs[className]
+    },
+
     /**
      * Checks if there is a set method for a given property key inside the prototype chain
      * @memberOf module:Neo
@@ -480,27 +666,39 @@ Neo = globalThis.Neo = Object.assign({
     },
 
     /**
-     * Updates the global Neo.config object across all active workers and connected browser windows.
-     *
-     * This is the unified entry point for changing global framework configurations.
-     * The framework automatically handles the complex multi-threaded and multi-window
-     * synchronization (via App Workers and Shared Workers, if active), ensuring
-     * consistency across the entire application without boilerplate.
+     * This is the final and most critical step in the Neo.mjs class creation process.
+     * It is called at the end of every class module definition.
      *
-     * You can pass a partial config object to update specific keys.
-     * For nested objects, Neo.mjs performs a deep merge to preserve existing properties.
+     * `setupClass` performs several key operations:
+     * 1.  **Mixed-Environment Gatekeeper:** It first checks if the class's namespace already exists.
+     *     If it does, it immediately returns the existing class. This is the crucial "first comes wins"
+     *     strategy that enables Neo.mjs to safely combine environments. For example, a bundled
+     *     `dist/production` app can dynamically load an unbundled module from `dist/esm` at runtime.
+     *     If that module imports a class already present in the main bundle, this check ensures the
+     *     original, bundled class is used, preventing conflicts and maintaining application integrity.
+     * 1.  **Configuration Merging:** It traverses the prototype chain to merge `static config`
+     *     objects from parent classes into the current class, creating a unified `config`.
+     * 2.  **Applying Overwrites:** It calls the static `applyOverwrites()` method on the class,
+     *     allowing the global `Neo.overwrites` object to modify the class's default prototype
+     *     configs. This is a key mechanism for external theming and configuration.
+     * 3.  **Reactive Getter/Setter Generation:** For any config ending with an underscore (e.g., `myConfig_`),
+     *     it automatically generates the corresponding public getter and setter. This enables optional
+     *     lifecycle hooks that are called automatically if implemented on the class:
+     *     - `beforeGetMyConfig(value)`
+     *     - `beforeSetMyConfig(newValue, oldValue)`
+     *     - `afterSetMyConfig(newValue, oldValue)`
+     * 4.  **Prototype-based Configs:** Non-reactive configs (without an underscore) are set
+     *     directly on the prototype for memory efficiency.
+     * 5.  **Mixin Application:** It processes the `mixins` config to blend in functionality from
+     *     other classes.
+     * 6.  **Namespace Registration:** It registers the class in the global `Neo` namespace.
+     * 7.  **Singleton Instantiation:** If the class is configured as a singleton, it creates the
+     *     single instance.
      *
      * @memberOf module:Neo
-     * @function setGlobalConfig
-     * @param {Object} config The partial or full Neo.config object with changes to apply.
-     */
-
-    /**
-     * Internally used at the end of each class / module definition
-     * @memberOf module:Neo
      * @template T
-     * @param {T} cls
-     * @returns {T}
+     * @param {T} cls The class constructor to process.
+     * @returns {T} The processed and finalized class constructor or singleton instance.
      */
     setupClass(cls) {
         let baseConfig            = null,
@@ -574,7 +772,7 @@ Neo = globalThis.Neo = Object.assign({
                 if (isReactive) {
                     delete cfg[key];      // Remove original key with underscore
                     cfg[baseKey] = value; // Use the potentially modified value
-                    autoGenerateGetSet(element, baseKey)
+                    Neo.createConfig(element, baseKey)
                 }
                 // This part handles non-reactive configs (including those that were descriptors)
                 // If no property setter exists, define it directly on the prototype.
@@ -695,7 +893,8 @@ Neo = globalThis.Neo = Object.assign({
      * @returns {String|null}
      */
     typeOf(item) {
-        if (item === null || item === undefined) {
+        // Return null for null or undefined
+        if (item == null) {
             return null
         }
 
@@ -762,152 +961,6 @@ function applyMixins(cls, mixins, classConfig) {
     cls.prototype.mixins = mixinClasses // todo: we should do a deep merge
 }
 
-/**
- * Creates get / set methods for class configs ending with an underscore
- * @param {Neo.core.Base} proto
- * @param {String}        key
- * @private
- * @tutorial 02_ClassSystem
- */
-function autoGenerateGetSet(proto, key) {
-    if (Neo.hasPropertySetter(proto, key)) {
-        throw('Config ' + key + '_ (' + proto.className + ') already has a set method, use beforeGet, beforeSet & afterSet instead')
-    }
-
-    const
-        _key      = '_' + key,
-        uKey      = key[0].toUpperCase() + key.slice(1),
-        beforeGet = 'beforeGet' + uKey,
-        beforeSet = 'beforeSet' + uKey,
-        afterSet  = 'afterSet'  + uKey;
-
-    if (!Neo[getSetCache]) {
-        Neo[getSetCache] = {}
-    }
-
-    if (!Neo[getSetCache][key]) {
-        // Public Descriptor
-        Neo[getSetCache][key] = {
-            get() {
-                let me        = this,
-                    config    = me.getConfig(key),
-                    hasNewKey = Object.hasOwn(me[configSymbol], key),
-                    newKey    = me[configSymbol][key],
-                    value     = hasNewKey ? newKey : me[_key];
-
-                if (value instanceof Date) {
-                    value = new Date(value.valueOf());
-                }
-                // new, explicit opt-in path
-                else if (config.cloneOnGet) {
-                    const {cloneOnGet} = config;
-
-                    if (cloneOnGet === 'deep') {
-                        value = Neo.clone(value, true, true);
-                    } else if (cloneOnGet === 'shallow') {
-                        const type = Neo.typeOf(value);
-
-                        if (type === 'Array') {
-                            value = [...value];
-                        } else if (type === 'Object') {
-                            value = {...value};
-                        }
-                    }
-                }
-                // legacy behavior
-                else if (Array.isArray(value)) {
-                    value = [...value];
-                }
-
-                if (hasNewKey) {
-                    me[key] = value;  // We do want to trigger the setter => beforeSet, afterSet
-                    value = me[_key]; // Return the value parsed by the setter
-                    delete me[configSymbol][key]
-                }
-
-                if (typeof me[beforeGet] === 'function') {
-                    value = me[beforeGet](value)
-                }
-
-                return value
-            },
-            set(value) {
-                if (value === undefined) return;
-
-                const config = this.getConfig(key);
-                if (!config) return;
-
-                let me                   = this,
-                    oldValue             = config.get(), // Get the old value from the Config instance
-                    {EffectBatchManager} = Neo.core,
-                    isNewBatch           = !EffectBatchManager?.isBatchActive();
-
-                // If a config change is not triggered via `core.Base#set()`, honor changes inside hooks.
-                isNewBatch && EffectBatchManager?.startBatch();
-
-                // 1. Prevent infinite loops:
-                // Immediately remove the pending value from the configSymbol to prevent a getter from
-                // recursively re-triggering this setter.
-                delete me[configSymbol][key];
-
-                switch (config.clone) {
-                    case 'deep':
-                        value = Neo.clone(value, true, true);
-                        break;
-                    case 'shallow':
-                        value = Neo.clone(value, false, true);
-                        break;
-                }
-
-                // 2. Create a temporary state for beforeSet hooks:
-                // Set the new value directly on the private backing property. This allows any beforeSet
-                // hook to access the new value of this and other configs within the same `set()` call.
-                me[_key] = value;
-
-                if (typeof me[beforeSet] === 'function') {
-                    value = me[beforeSet](value, oldValue);
-
-                    // If they don't return a value, that means no change
-                    if (value === undefined) {
-                        // Restore the original value if the update is canceled.
-                        me[_key] = oldValue;
-                        isNewBatch && EffectBatchManager?.endBatch();
-                        return
-                    }
-                }
-
-                // 3. Restore state for change detection:
-                // Revert the private backing property to its original value. This is crucial for the
-                // `config.set()` method to correctly detect if the value has actually changed.
-                me[_key] = oldValue;
-
-                // 4. Finalize the change:
-                // The config.set() method performs the final check and, if the value changed,
-                // triggers afterSet hooks and notifies subscribers.
-                if (config.set(value)) {
-                    me[afterSet]?.(value, oldValue);
-                    me.afterSetConfig?.(key, value, oldValue)
-                }
-
-                isNewBatch && EffectBatchManager?.endBatch()
-            }
-        };
-
-        // Private Descriptor
-        Neo[getSetCache][_key] = {
-            get() {
-                return this.getConfig(key)?.get()
-            },
-            set(value) {
-                this.getConfig(key)?.setRaw(value)
-            }
-        }
-    }
-
-    Object.defineProperty(proto, key,  Neo[getSetCache][key]);
-    Object.defineProperty(proto, _key, Neo[getSetCache][_key])
-}
-
 /**
  * @param {Boolean} create
  * @param {Object}  current
@@ -973,7 +1026,7 @@ function mixinProperty(proto, mixinProto, classConfig) {
 
         // Reactive neo configs, or public class fields defined via get() AND set()
         if (descriptor.get && descriptor.set) {
-            autoGenerateGetSet(proto, key);
+            Neo.createConfig(proto, key);
 
             const mixinClassConfig = mixinProto.constructor.config;
 

package/src/Xhr.mjs

@@ -20,6 +20,7 @@ class Xhr extends XhrConnection {
         /**
          * @member {Object} remote={app:['promiseRequest','promiseJson','setDefaultHeaders']}
          * @protected
+         * @reactive
          */
         remote: {
             app: [

package/src/button/Base.mjs

@@ -34,10 +34,12 @@ class Button extends Component {
         ntype: 'button',
         /**
          * @member {String} badgePosition_='top-right'
+         * @reactive
          */
         badgePosition_: 'top-right',
         /**
          * @member {String|null} badgeText_=null
+         * @reactive
          */
         badgeText_: null,
         /**
@@ -53,6 +55,7 @@ class Button extends Component {
          * Shortcut for domListeners={click:handler}
          * A string based value assumes that the handlerFn lives inside a controller.Component
          * @member {Function|String|null} handler_=null
+         * @reactive
          */
         handler_: null,
         /**
@@ -65,17 +68,20 @@ class Button extends Component {
         /**
          * The CSS class to use for an icon, e.g. 'fa fa-home'
          * @member {String|null} [iconCls_=null]
+         * @reactive
          */
         iconCls_: null,
         /**
          * The color to use for an icon, e.g. '#ff0000' [optional]
          * @member {String|null} iconColor_=null
+         * @reactive
          */
         iconColor_: null,
         /**
          * The position of the icon in case iconCls has a value.
          * Valid values are: 'top', 'right', 'bottom', 'left'
          * @member {String} iconPosition_='left'
+         * @reactive
          */
         iconPosition_: 'left',
         /**
@@ -84,11 +90,13 @@ class Button extends Component {
          * Or a configuration object which adds custom configuration to the menu to be
          * created and includes an `items` property to define the menu items.
          * @member {Object|Object[]|null} menu_=null
+         * @reactive
          */
         menu_: null,
         /**
          * The pressed state of the Button
          * @member {Boolean} pressed_=false
+         * @reactive
          */
         pressed_: false,
         /**
@@ -96,26 +104,31 @@ class Button extends Component {
          * Use route for internal navigation and url for external links. Do not use both on the same instance.
          * Transforms the button tag into an a tag [optional]
          * @member {String|null} route_=null
+         * @reactive
          */
         route_: null,
         /**
          * The text displayed on the button [optional]
          * @member {String|null} text=null
+         * @reactive
          */
         text: null,
         /**
          * Transforms the button tag into an a tag [optional]
          * @member {String|null} url_=null
+         * @reactive
          */
         url_: null,
         /**
          * If url is set, applies the target attribute on the top level vdom node [optional]
          * @member {String} urlTarget_='_blank'
+         * @reactive
          */
         urlTarget_: '_blank',
         /**
          * True adds an expanding circle on click
          * @member {Boolean} useRippleEffect_=true
+         * @reactive
          */
         useRippleEffect_: true,
         /**

package/src/button/Effect.mjs

@@ -35,10 +35,12 @@ class EffectButton extends Component {
         ntype: 'effect-button',
         /**
          * @member {String} badgePosition_='top-right'
+         * @reactive
          */
         badgePosition_: 'top-right',
         /**
          * @member {String|null} badgeText_=null
+         * @reactive
          */
         badgeText_: null,
         /**
@@ -47,6 +49,7 @@ class EffectButton extends Component {
         baseCls: ['neo-button'],
         /**
          * @member {String[]} cls=[]
+         * @reactive
          */
         cls: [],
         /**
@@ -58,6 +61,7 @@ class EffectButton extends Component {
          * Shortcut for domListeners={click:handler}
          * A string based value assumes that the handlerFn lives inside a controller.Component
          * @member {Function|String|null} handler_=null
+         * @reactive
          */
         handler_: null,
         /**
@@ -70,17 +74,20 @@ class EffectButton extends Component {
         /**
          * The CSS class to use for an icon, e.g. 'fa fa-home'
          * @member {String|null} [iconCls_=null]
+         * @reactive
          */
         iconCls_: null,
         /**
          * The color to use for an icon, e.g. '#ff0000' [optional]
          * @member {String|null} iconColor_=null
+         * @reactive
          */
         iconColor_: null,
         /**
          * The position of the icon in case iconCls has a value.
          * Valid values are: 'top', 'right', 'bottom', 'left'
          * @member {String} iconPosition_='left'
+         * @reactive
          */
         iconPosition_: 'left',
         /**
@@ -89,11 +96,13 @@ class EffectButton extends Component {
          * Or a configuration object which adds custom configuration to the menu to be
          * created and includes an `items` property to define the menu items.
          * @member {Object|Object[]|null} menu_=null
+         * @reactive
          */
         menu_: null,
         /**
          * The pressed state of the Button
          * @member {Boolean} pressed_=false
+         * @reactive
          */
         pressed_: false,
         /**
@@ -101,25 +110,30 @@ class EffectButton extends Component {
          * Use route for internal navigation and url for external links. Do not use both on the same instance.
          * Transforms the button tag into an a tag [optional]
          * @member {String|null} route_=null
+         * @reactive
          */
         route_: null,
         /**
          * @member {String} tag='button'
+         * @reactive
          */
         tag: 'button',
         /**
          * Transforms the button tag into an a tag [optional]
          * @member {String|null} url_=null
+         * @reactive
          */
         url_: null,
         /**
          * If url is set, applies the target attribute on the top level vdom node [optional]
          * @member {String} urlTarget_='_blank'
+         * @reactive
          */
         urlTarget_: '_blank',
         /**
          * True adds an expanding circle on click
          * @member {Boolean} useRippleEffect_=true
+         * @reactive
          */
         useRippleEffect_: true
     }
@@ -160,11 +174,11 @@ class EffectButton extends Component {
      * @protected
      */
     createVdomEffect() {
-        return new Effect({fn: () => {
+        return new Effect(() => {
             // The effect's only job is to get the config and trigger an update.
             this._vdom = this.getVdomConfig();
             this.update();
-        }});
+        })
     }
 
     /**

package/src/button/Split.mjs

@@ -20,6 +20,7 @@ class Split extends Button {
         ntype: 'split-button',
         /**
          * @member {Boolean} hideTriggerButton_=false
+         * @reactive
          */
         hideTriggerButton_: false,
         /**
@@ -38,6 +39,7 @@ class Split extends Button {
         /**
          * The CSS class to use for the SplitButton icon, e.g. 'fa fa-home'
          * @member {String} triggerButtonCls_='fa fa-caret-down'
+         * @reactive
          */
         triggerButtonIconCls_: 'fa fa-caret-down',
         /**

package/src/calendar/store/Calendars.mjs

@@ -18,6 +18,7 @@ class Calendars extends Store {
         keyProperty: 'id',
         /**
          * @member {Neo.data.Model} model=Calendar
+         * @reactive
          */
         model: Calendar,
         /**

package/src/calendar/store/Colors.mjs

@@ -29,6 +29,7 @@ class Colors extends Store {
         keyProperty: 'id',
         /**
          * @member {Neo.data.Model} model=Color
+         * @reactive
          */
         model: Color
     }

package/src/calendar/store/Events.mjs

@@ -19,6 +19,7 @@ class Events extends Store {
         keyProperty: 'id',
         /**
          * @member {Neo.data.Model} model=Event
+         * @reactive
          */
         model: Event,
         /**