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

package/src/component/mwc/Button.mjs

@@ -20,32 +20,39 @@ class Button extends Component {
         ntype: 'mwc-button',
         /**
          * @member {Boolean} dense_=false
+         * @reactive
          */
         dense_: false,
         /**
          * Shortcut for domListeners={click:handler}
          * A string based value assumes that the handlerFn lives inside a ComponentController
          * @member {Function|String|null} handler_=null
+         * @reactive
          */
         handler_: null,
         /**
          * @member {String} icon_=''
+         * @reactive
          */
         icon_: '',
         /**
          * @member {String} label_=''
+         * @reactive
          */
         label_: '',
         /**
          * @member {Boolean} outlined_=false
+         * @reactive
          */
         outlined_: false,
         /**
          * @member {Boolean} raised_=false
+         * @reactive
          */
         raised_: false,
         /**
          * @member {Boolean} unelevated_=false
+         * @reactive
          */
         unelevated_: false,
         /**

package/src/component/mwc/TextField.mjs

@@ -21,38 +21,47 @@ class TextField extends Component {
         /**
          * Displays a helper text below the field
          * @member {String} helper_=''
+         * @reactive
          */
         helper_: '',
         /**
          * @member {String} icon_=''
+         * @reactive
          */
         icon_: '',
         /**
          * @member {String} iconTrailing_=''
+         * @reactive
          */
         iconTrailing_: '',
         /**
          * @member {String} label_=''
+         * @reactive
          */
         label_: '',
         /**
          * @member {String} name_=''
+         * @reactive
          */
         name_: '',
         /**
          * @member {Boolean} outlined_=false
+         * @reactive
          */
         outlined_: false,
         /**
          * @member {String} placeholder_=''
+         * @reactive
          */
         placeholder_: '',
         /**
          * @member {Boolean} required_=false
+         * @reactive
          */
         required_: false,
         /**
          * @member {String} value_=''
+         * @reactive
          */
         value_: '',
         /**

package/src/component/wrapper/AmChart.mjs

@@ -21,11 +21,13 @@ class AmChart extends Component {
         /**
          * See: https://www.amcharts.com/docs/v4/
          * @member {Object} chartConfig_=null
+         * @reactive
          */
         chartConfig_: null,
         /**
          * Stores the chart data
          * @member {Array|null} chartData_=null
+         * @reactive
          */
         chartData_: null,
         /**

package/src/component/wrapper/GoogleMaps.mjs

@@ -21,12 +21,14 @@ class GoogleMaps extends Base {
         /**
          * Specify lat & lng for the current focus position
          * @member {Object} center_={lat: -34.397, lng: 150.644}
+         * @reactive
          */
         center_: {lat: -34.397, lng: 150.644},
         /**
          * Prefer to use markerStoreConfig instead.
          * @member {Neo.data.Store|Object} markerStore_
          * @protected
+         * @reactive
          */
         markerStore_: {
             model: {
@@ -52,6 +54,7 @@ class GoogleMaps extends Base {
         },
         /**
          * @member {Number} zoom_=8
+         * @reactive
          */
         zoom_: 8
     }

package/src/component/wrapper/MapboxGL.mjs

@@ -25,10 +25,12 @@ class MapboxGL extends Component {
         accessToken: null,
         /**
          * @member {Array|null} chartData_=null
+         * @reactive
          */
         chartData_: null,
         /**
          * @member {Object} center_={lat: 0, lng: 0}
+         * @reactive
          */
         center_: {lat: 0, lng: 0},
         /**
@@ -47,6 +49,7 @@ class MapboxGL extends Component {
          * beforeId is a custom property which will get passed as the second param for:
          * https://docs.mapbox.com/mapbox-gl-js/api/#map#addlayer
          * @member {Object[]|null} layers_=null
+         * @reactive
          */
         layers_: null,
         /**
@@ -59,6 +62,7 @@ class MapboxGL extends Component {
          * id is a custom property which will get passed as the first param for:
          * https://docs.mapbox.com/mapbox-gl-js/api/#map#addsource
          * @member {Object[]|null} sources_=null
+         * @reactive
          */
         sources_: null,
         /**
@@ -73,6 +77,7 @@ class MapboxGL extends Component {
         /**
          *
          * @member {Number} zoom_=3
+         * @reactive
          */
         zoom_: 3
     }

package/src/component/wrapper/MonacoEditor.mjs

@@ -47,34 +47,41 @@ class MonacoEditor extends Base {
         baseCls: ['neo-monaco-editor'],
         /**
          * @member {Boolean} contextmenu_=false
+         * @reactive
          */
         contextmenu_: false,
         /**
          * Options are: 'blink', 'expand', 'phase', 'smooth', 'solid'
          * @member {String} cursorBlinking_='blink'
+         * @reactive
          */
         cursorBlinking_: 'blink',
         /**
          * additional property to only use in combination with readOnly === true.
          * domReadOnly additionally sets the readonly attribute to the underlying textarea.
          * @member {Boolean} domReadOnly_=false
+         * @reactive
          */
         domReadOnly_: false,
         /**
          * Options are: 'vs', 'vs-dark', 'hc-black', 'hc-light'
          * @member {String} editorTheme_='vs'
+         * @reactive
          */
         editorTheme_: 'vs',
         /**
          * @member {Number} fontSize_=14
+         * @reactive
          */
         fontSize_: 14,
         /**
          * @member {String} language_='javascript'
+         * @reactive
          */
         language_: 'javascript',
         /**
          * @member {Object} minimap_={enabled: false}
+         * @reactive
          */
         minimap_: {enabled: false},
         /**
@@ -85,22 +92,27 @@ class MonacoEditor extends Base {
          * For initial options this config will win over related class configs.
          * However, run-time changes of related class configs will dynamically change their option values.
          * @member {Object} options_={}
+         * @reactive
          */
         options_: {},
         /**
          * @member {Boolean} readOnly_=false
+         * @reactive
          */
         readOnly_: false,
         /**
          * @member {Boolean} scrollBeyondLastLine_=false
+         * @reactive
          */
         scrollBeyondLastLine_: false,
         /**
          * @member {Boolean} showLineNumbers_=true
+         * @reactive
          */
         showLineNumbers_: true,
         /**
          * @member {String|String[]} value_=''
+         * @reactive
          */
         value_: ''
     }

package/src/container/Accordion.mjs

@@ -29,10 +29,12 @@ class Accordion extends Panel {
         initialOpen_: [],
         /**
          * @member {Object} itemDefaults={ntype:'accordionitem'}
+         * @reactive
          */
         itemDefaults: {ntype: 'accordionitem'},
         /**
          * @member {Object[]} items=[]
+         * @reactive
          */
         items: [],
         /**

package/src/container/Base.mjs

@@ -35,6 +35,7 @@ class Container extends Component {
          * 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}
+         * @reactive
          */
         itemDefaults_: {
             [isDescriptor]: true,
@@ -91,6 +92,7 @@ class Container extends Component {
          *         MyRedButton            // you can drop imported modules directly into the items array
          *     ]
          * });
+         * @reactive
          */
         items_: {
             [isDescriptor]: true,
@@ -104,6 +106,7 @@ class Container extends Component {
          * Meaning: onConstructed() is the latest life-cycle point.
          * You can use layout: 'base', in case you do not need a layout at all.
          * @member {Object|String|null} layout_={ntype: 'vbox', align: 'stretch'}
+         * @reactive
          */
         layout_: {
             ntype: 'vbox',
@@ -349,13 +352,14 @@ class Container extends Component {
 
                     // Convenience logic, especially for moving components into different browser windows:
                     // A component might rely on references & handler methods inside the previous controller realm
-                    if (!item.controller && !me.getController() && parent.getController()) {
+                    // todo: We need ?. until functional.component.Base supports controllers
+                    if (!item.controller && !me.getController() && parent.getController?.()) {
                         item.controller = {parent: parent.getController()}
                     }
                 }
 
                 item.set(config);
-                item.getStateProvider()?.createBindings(item);
+                item.getStateProvider?.()?.createBindings(item);
                 break
             }
 
@@ -437,7 +441,7 @@ class Container extends Component {
 
         // We need to add items into the vdom
         me.updateDepth = -1;
-        me.update();
+        me.isConstructed && me.update();
 
         me.fire('itemsCreated', {id: me.id, items})
     }

package/src/container/Panel.mjs

@@ -36,6 +36,7 @@ class Panel extends Container {
         headers: null,
         /**
          * @member {Object} items={ntype: 'vbox', align: 'stretch'}
+         * @reactive
          */
         _layout: {
             ntype: 'vbox',

package/src/container/Viewport.mjs

@@ -35,6 +35,7 @@ class Viewport extends Container {
          * true applies a main.addon.ResizeObserver and fires a custom resize event
          * which other instances can subscribe to.
          * @member {Boolean} monitorSize_=false
+         * @reactive
          */
         monitorSize_: false
     }

package/src/controller/Application.mjs

@@ -30,6 +30,7 @@ class Application extends Base {
         appThemeFolder: null,
         /**
          * @member {Neo.component.Base} mainView_=null
+         * @reactive
          */
         mainView_: null,
         /**

package/src/controller/Base.mjs

@@ -55,6 +55,7 @@ class Controller extends Base {
          *     'default'                       : 'handleOtherRoutes'
          * }
          * @member {Object} routes_={}
+         * @reactive
          */
         routes_: {}
     }

package/src/controller/Component.mjs

@@ -24,6 +24,7 @@ class Component extends Base {
         component: null,
         /**
          * @member {Neo.controller.Component|null} parent_=null
+         * @reactive
          */
         parent_: null,
         /**

package/src/core/Base.mjs

@@ -58,7 +58,26 @@ class Base {
      */
     static overwrittenMethods = {}
     /**
-     * Configs will get merged throughout the class hierarchy
+     * Defines the default configuration properties for the class. These configurations are
+     * merged throughout the class hierarchy and can be overridden at the instance level.
+     *
+     * There are two main types of configs:
+     *
+     * 1.  **Reactive Configs:** Property names ending with a trailing underscore (e.g., `myConfig_`).
+     *     The framework automatically generates a public getter and setter, removing the underscore
+     *     from the property name (e.g., `this.myConfig`). This system enables powerful, optional
+     *     lifecycle hooks that are called automatically if they are implemented on the class:
+     *     - `beforeGetMyConfig(value)`: Executed before the getter returns. Can be used to dynamically modify the returned value.
+     *     - `beforeSetMyConfig(newValue, oldValue)`: Executed before a new value is set. Can be used for validation or transformation. Returning `undefined` from this hook will cancel the update.
+     *     - `afterSetMyConfig(newValue, oldValue)`: Executed after a new value has been successfully set. Ideal for triggering side effects.
+     *
+     * 2.  **Non-Reactive (Prototype-based) Configs:** Property names without a trailing underscore.
+     *     These are applied directly to the class's **prototype** during the `Neo.setupClass`
+     *     process. This is highly memory-efficient as the value is shared across all instances.
+     *     It also allows for powerful, application-wide modifications of default behaviors
+     *     by using the `Neo.overwrites` mechanism, which modifies these prototype values at
+     *     load time.
+     *
      * @returns {Object} config
      */
     static config = {
@@ -83,6 +102,7 @@ class Base {
         /**
          * The unique component id
          * @member {String|null} id_=null
+         * @reactive
          */
         id_: null,
         /**
@@ -104,6 +124,7 @@ class Base {
          * Effects can observe this config to clean themselves up.
          * @member {Boolean} isDestroying_=false
          * @protected
+         * @reactive
          */
         isDestroying_: false,
         /**
@@ -112,6 +133,7 @@ class Base {
          * Since not all classes use the Observable mixin, Neo will not fire an event.
          * method body.
          * @member {Boolean} isReady_=false
+         * @reactive
          */
         isReady_: false,
         /**
@@ -133,6 +155,7 @@ class Base {
          *
          * @member {Object|null} remote_=null
          * @protected
+         * @reactive
          */
         remote_: null
     }
@@ -290,9 +313,38 @@ class Base {
     }
 
     /**
-     * Applying overwrites and adding overwrittenMethods to the class constructors
-     * @param {Object} cfg
+     * This static method is called by `Neo.setupClass()` during the class creation process.
+     * It allows for modifying a class's default prototype-based configs from outside the
+     * class hierarchy, which is a powerful way to avoid boilerplate code.
+     *
+     * It looks for a matching entry in the global `Neo.overwrites` object based on the
+     * class's `className`. If found, it merges the properties from the overwrite object
+     * into the class's static `config`. This provides a powerful mechanism for theming
+     * or applying application-wide customizations to framework or library classes without
+     * needing to extend them.
+     *
+     * @example
+     * // Imagine you have hundreds of buttons in your app, and you want all of them
+     * // to have `labelPosition: 'top'` instead of the default `'left'`. 
+     * // Instead of configuring each instance, you can define an overwrite.
+     * 
+     * // inside an Overwrites.mjs file loaded by your app:
+     * Neo.overwrites = {
+     *     Neo: {
+     *         button: {
+     *             Base: {
+     *                 labelPosition: 'top'
+     *             }
+     *         }
+     *     }
+     * };
+     * 
+     * // Now, every `Neo.button.Base` (and any class that extends it) will have this
+     * // new default value on its prototype.
+     *
+     * @param {Object} cfg The static `config` object of the class being processed.
      * @protected
+     * @static
      */
     static applyOverwrites(cfg) {
         let overwrites = Neo.ns(cfg.className, false, Neo.overwrites),

package/src/core/Compare.mjs

@@ -163,10 +163,7 @@ class Compare {
     }
 }
 
-const ns = Neo.ns('Neo.core', true);
-ns.Compare = Compare;
-
-// alias
-Neo.isEqual = Compare.isEqual;
-
-export default Compare;
+export default Neo.gatekeep(Compare, 'Neo.core.Compare', () => {
+    // alias
+    Neo.isEqual = Compare.isEqual
+});

package/src/core/Config.mjs

@@ -14,13 +14,26 @@ import {isDescriptor} from './ConfigSymbols.mjs';
  */
 class Config {
     /**
-     * A Set to store callback functions that subscribe to changes in this config's value.
+     * Stores all subscriptions for this Config instance.
+     * The data structure is a Map where:
+     * - The key is the ID of the subscription owner (e.g., a component's `id`).
+     * - The value is another Map (the subscriberMap).
+     *
+     * The nested subscriberMap is structured as:
+     * - The key is the callback function (`fn`).
+     * - The value is a Set of scopes (`scopeSet`).
+     *
+     * This nested structure `Map<string, Map<function, Set<scope>>>` is intentionally chosen
+     * to robustly handle the edge case where the same function is subscribed multiple times
+     * with different scopes, all under the same owner ID. It ensures that each
+     * `fn`-`scope` combination is unique and that cleanup is precise.
+     * @member {Object} #subscribers={}
      * @private
      */
     #subscribers = {}
     /**
      * The internal value of the config property.
-     * @member #value
+     * @member {*} #value
      * @private
      */
     #value
@@ -67,7 +80,7 @@ class Config {
     get() {
         // Registers this Config instance as a dependency with the currently active Effect,
         // enabling automatic re-execution when this Config's value changes.
-        EffectManager.getActiveEffect()?.addDependency(this);
+        EffectManager.addDependency(this);
         return this.#value
     }
 
@@ -75,52 +88,56 @@ class Config {
      * Initializes the `Config` instance using a descriptor object.
      * Extracts `clone`, `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 {Object}    descriptor                      - The descriptor object for the config.
      * @param {string}   [descriptor.clone='deep']        - The clone strategy for set.
      * @param {string}   [descriptor.cloneOnGet]          - The clone strategy for get. Defaults to 'shallow' if clone is 'deep' or 'shallow', and 'none' if clone is 'none'.
-     * @param {string}   [descriptor.merge='deep']        - The merge strategy.
      * @param {Function} [descriptor.isEqual=Neo.isEqual] - The equality comparison function.
+     * @param {string}   [descriptor.merge='deep']        - The merge strategy.
+     * @param {any}       descriptor.value                - The default value for the config (not set by this method).
      */
     initDescriptor({clone, cloneOnGet, isEqual, merge}) {
         let me = this;
 
         if (clone && clone !== me.clone) {
             Object.defineProperty(me, 'clone', {
-                value: clone, writable: true, configurable: true, enumerable: true
+                configurable: true, enumerable: true, value: clone, writable: true
             })
         }
 
         if (cloneOnGet && cloneOnGet !== me.cloneOnGet) {
             Object.defineProperty(me, 'cloneOnGet', {
-                value: cloneOnGet, writable: true, configurable: true, enumerable: true
+                configurable: true, enumerable: true, value: cloneOnGet, writable: true
             })
         }
 
         if (isEqual && isEqual !== me.isEqual) {
             Object.defineProperty(me, 'isEqual', {
-                value: isEqual, writable: true, configurable: true, enumerable: true
+                configurable: true, enumerable: true, value: isEqual, writable: true
             })
         }
 
         if (merge && merge !== me.mergeStrategy) {
             Object.defineProperty(me, 'mergeStrategy', {
-                value: merge, writable: true, configurable: true, enumerable: true
+                configurable: true, enumerable: true, value: merge, writable: true
             })
         }
     }
 
     /**
      * Notifies all subscribed callbacks about a change in the config's value.
+     * It iterates through the nested subscriber structure to ensure each callback
+     * is executed with its intended scope.
      * @param {any} newValue - The new value of the config.
      * @param {any} oldValue - The old value of the config.
      */
     notify(newValue, oldValue) {
         for (const id in this.#subscribers) {
             if (this.#subscribers.hasOwnProperty(id)) {
-                const subscriberSet = this.#subscribers[id];
-                for (const callback of subscriberSet) {
-                    callback(newValue, oldValue)
+                const subscriberMap = this.#subscribers[id];
+                for (const [fn, scopeSet] of subscriberMap) {
+                    for (const scope of scopeSet) {
+                        fn.call(scope || null, newValue, oldValue)
+                    }
                 }
             }
         }
@@ -164,12 +181,13 @@ class Config {
     /**
      * Subscribes a callback function to changes in this config's value.
      * The callback will be invoked with `(newValue, oldValue)` whenever the config changes.
-     * @param {Object} options      - An object containing the subscription details.
-     * @param {String} options.id   - The ID of the subscription owner (e.g., a Neo.core.Base instance's id).
-     * @param {Function} options.fn - The callback function.
+     * @param {Object}   options        - An object containing the subscription details.
+     * @param {String}   options.id     - The ID of the subscription owner (e.g., a Neo.core.Base instance's id).
+     * @param {Function} options.fn     - The callback function.
+     * @param {Object}  [options.scope] - The scope to execute the callback in.
      * @returns {Function} A cleanup function to unsubscribe the callback.
      */
-    subscribe({id, fn}) {
+    subscribe({id, fn, scope}) {
         if (typeof id !== 'string' || id.length === 0 || typeof fn !== 'function') {
             throw new Error([
                 'Config.subscribe: options must be an object with a non-empty string `id` ',
@@ -179,18 +197,36 @@ class Config {
 
         const me = this;
 
+        // Get or create the top-level Map for the subscription owner.
         if (!me.#subscribers[id]) {
-            me.#subscribers[id] = new Set()
+            me.#subscribers[id] = new Map()
         }
 
-        me.#subscribers[id].add(fn);
+        const subscriberMap = me.#subscribers[id];
+
+        // Get or create the Set of scopes for the specific callback function.
+        if (!subscriberMap.has(fn)) {
+            subscriberMap.set(fn, new Set())
+        }
 
+        const scopeSet = subscriberMap.get(fn);
+        scopeSet.add(scope);
+
+        // The returned cleanup function is precise. It removes only the specific
+        // scope for the function, and cleans up the parent data structures
+        // (the Set and the Maps) only if they become empty.
         return () => {
-            const subscriberSet = me.#subscribers[id];
-            if (subscriberSet) {
-                subscriberSet.delete(fn);
-                if (subscriberSet.size === 0) {
-                    delete me.#subscribers[id]
+            const currentSubscriberMap = me.#subscribers[id];
+            if (currentSubscriberMap) {
+                const currentScopeSet = currentSubscriberMap.get(fn);
+                if (currentScopeSet) {
+                    currentScopeSet.delete(scope);
+                    if (currentScopeSet.size === 0) {
+                        currentSubscriberMap.delete(fn);
+                        if (currentSubscriberMap.size === 0) {
+                            delete me.#subscribers[id]
+                        }
+                    }
                 }
             }
         }
@@ -198,33 +234,10 @@ class Config {
 }
 
 Object.defineProperties(Config.prototype, {
-    clone: {
-        value: 'deep',
-        writable: false,
-        configurable: true,
-        enumerable: false
-    },
-    cloneOnGet: {
-        value: null,
-        writable: false,
-        configurable: true,
-        enumerable: false
-    },
-    isEqual: {
-        value: Neo.isEqual,
-        writable: false,
-        configurable: true,
-        enumerable: false
-    },
-    mergeStrategy: {
-        value: 'replace',
-        writable: false,
-        configurable: true,
-        enumerable: false
-    }
+    clone        : {configurable: true, enumerable: false, value: 'deep',      writable: false},
+    cloneOnGet   : {configurable: true, enumerable: false, value: null,        writable: false},
+    isEqual      : {configurable: true, enumerable: false, value: Neo.isEqual, writable: false},
+    mergeStrategy: {configurable: true, enumerable: false, value: 'replace',   writable: false}
 });
 
-const ns = Neo.ns('Neo.core', true);
-ns.Config = Config;
-
-export default Config;
+export default Neo.gatekeep(Config, 'Neo.core.Config');