neo.mjs 10.0.0-beta.5 → 10.0.0

package/src/selection/Model.mjs

@@ -1,10 +1,12 @@
-import Base       from '../core/Base.mjs';
-import NeoArray   from '../util/Array.mjs';
-import Observable from '../core/Observable.mjs';
+import Base           from '../core/Base.mjs';
+import NeoArray       from '../util/Array.mjs';
+import Observable     from '../core/Observable.mjs';
+import {isDescriptor} from '../core/ConfigSymbols.mjs';
 
 /**
  * @class Neo.selection.Model
  * @extends Neo.core.Base
+ * @mixes Neo.core.Observable
  */
 class Model extends Base {
     /**
@@ -32,10 +34,17 @@ class Model extends Base {
          */
         cls: null,
         /**
-         * @member {Array} items_=null
+         * @member {Array} items_
          * @protected
+         * @reactive
          */
-        items_: null,
+        items_: {
+            [isDescriptor]: true,
+            clone         : 'shallow',
+            cloneOnGet    : 'none',
+            isEqual       : () => false,
+            value         : []
+        },
         /**
          * @member {String} selectedCls='selected'
          */
@@ -48,23 +57,11 @@ class Model extends Base {
          * Internally saves the view id, but the getter will return the matching instance
          * @member {Object} view_=null
          * @protected
+         * @reactive
          */
         view_: null
     }
 
-    /**
-     * Gets triggered before getting the value of the items config
-     * @param {Array|null} value
-     * @returns {Array}
-     */
-    beforeGetItems(value) {
-        if (!value) {
-            this._items = value = []
-        }
-
-        return value
-    }
-
     /**
      * Gets triggered before getting the value of the view config
      * @param {String} value

package/src/selection/grid/BaseModel.mjs

@@ -53,6 +53,7 @@ class BaseModel extends Model {
             }
 
             me.fire('selectionChange', {
+                records  : me.selectedRows.map(id => view.store.get(id)),
                 selection: me.selectedRows
             })
         } else if (!silent) {

package/src/sitemap/Component.mjs

@@ -34,6 +34,7 @@ class Component extends Base {
          * Valid values: removeDom, visibility
          * Defines if the component items should use css visibility:'hidden' or vdom:removeDom
          * @member {String} hideMode_='removeDom'
+         * @reactive
          */
         itemHideMode_: 'removeDom',
         /*

package/src/state/Provider.mjs

@@ -2,6 +2,7 @@ import Base                          from '../core/Base.mjs';
 import ClassSystemUtil               from '../util/ClassSystem.mjs';
 import Config                        from '../core/Config.mjs';
 import Effect                        from '../core/Effect.mjs';
+import EffectManager                 from '../core/EffectManager.mjs';
 import Observable                    from '../core/Observable.mjs';
 import {createHierarchicalDataProxy} from './createHierarchicalDataProxy.mjs';
 import {isDescriptor}                from '../core/ConfigSymbols.mjs';
@@ -12,6 +13,7 @@ const twoWayBindingSymbol = Symbol.for('twoWayBinding');
  * An optional component state provider for adding bindings to configs
  * @class Neo.state.Provider
  * @extends Neo.core.Base
+ * @mixes Neo.core.Observable
  */
 class Provider extends Base {
     /**
@@ -55,6 +57,7 @@ class Provider extends Base {
          *             theme: 'dark'
          *         }
          *     }
+         * @reactive
          */
         data_: {
             [isDescriptor]: true,
@@ -79,10 +82,12 @@ class Provider extends Base {
          *         // Accessing parent data (assuming a parent provider has a 'taxRate' property)
          *         totalWithTax: (data) => data.total * (1 + data.taxRate)
          *     }
+         * @reactive
          */
         formulas_: null,
         /**
          * @member {Neo.state.Provider|null} parent_=null
+         * @reactive
          */
         parent_: null,
         /**
@@ -104,6 +109,7 @@ class Provider extends Base {
          *             autoLoad: true
          *         }
          *     }
+         * @reactive
          */
         stores_: null
     }
@@ -161,21 +167,16 @@ class Provider extends Base {
 
         if (value) {
             Object.entries(value).forEach(([formulaKey, formulaFn]) => {
-                // Create a new Effect for each formula. The Effect's fn will re-run whenever its dependencies change.
+                // Create a new lazy Effect. It will not run until explicitly told to.
                 const effect = new Effect({
                     fn: () => {
                         const
-                            hierarchicalData = me.getHierarchyData(), // Get the reactive data proxy
-                            result           = formulaFn(hierarchicalData); // Execute the formula with the data
-
-                        // Assign the result back to the state provider's data.
-                        // This makes the formula's output available as a data property.
-                        if (isNaN(result)) {
-                            me.setData(formulaKey, null)
-                        } else {
-                            me.setData(formulaKey, result)
-                        }
-                    }
+                            hierarchicalData = me.getHierarchyData(),
+                            result           = formulaFn(hierarchicalData);
+
+                        me.setData(formulaKey, result);
+                    },
+                    lazy: true
                 });
 
                 me.#formulaEffects.set(formulaKey, effect)
@@ -223,24 +224,22 @@ class Provider extends Base {
      * @param {String} configKey The component config to bind (e.g., 'text').
      * @param {String|Function} formatter The function that computes the value.
      */
-    createBinding(componentId, configKey, key, isTwoWay) {
+    createBinding(componentId, configKey, formatter) {
         const
             me     = this,
-            effect = new Effect({
-            fn: () => {
+            effect = new Effect(() => {
                 const component = Neo.get(componentId);
 
                 if (component && !component.isDestroyed) {
                     const
                         hierarchicalData = me.getHierarchyData(),
-                        newValue         = Neo.isFunction(key) ? key.call(me, hierarchicalData) : hierarchicalData[key];
+                        newValue         = Neo.isFunction(formatter) ? formatter.call(me, hierarchicalData) : hierarchicalData[formatter];
 
                     component._skipTwoWayPush = configKey;
                     component[configKey] = newValue;
                     delete component._skipTwoWayPush
                 }
-            }
-        });
+            });
 
         me.#bindingEffects.set(componentId, effect);
 
@@ -262,7 +261,8 @@ class Provider extends Base {
      * @param {Neo.component.Base} component The component instance whose bindings are to be created.
      */
     createBindings(component) {
-        let hasTwoWayBinding = false;
+        let me               = this,
+            hasTwoWayBinding = false;
 
         Object.entries(component.bind || {}).forEach(([configKey, value]) => {
             let key = value;
@@ -276,12 +276,12 @@ class Provider extends Base {
             }
 
             // Determine if it's a store binding or a data binding.
-            if (this.isStoreValue(key)) {
+            if (me.isStoreValue(key)) {
                 // For store bindings, resolve the store and assign it to the component config.
-                this.resolveStore(component, configKey, key.substring(7)) // remove the "stores." prefix
+                me.resolveStore(component, configKey, key.substring(7)) // remove the "stores." prefix
             } else {
                 // For data bindings, create an Effect to keep the component config in sync with the data.
-                this.createBinding(component.id, configKey, key, value.twoWay)
+                me.createBinding(component.id, configKey, key, value.twoWay)
             }
         });
 
@@ -435,52 +435,45 @@ class Provider extends Base {
      * @returns {String[]}
      */
     getTopLevelDataKeys(path) {
-        const keys = new Set();
-        const pathPrefix = path ? `${path}.` : '';
+        const
+            keys       = new Set(),
+            pathPrefix = path ? `${path}.` : '';
 
         for (const fullPath in this.#dataConfigs) {
             if (fullPath.startsWith(pathPrefix)) {
-                const relativePath = fullPath.substring(pathPrefix.length);
-                const topLevelKey = relativePath.split('.')[0];
+                const
+                    relativePath = fullPath.substring(pathPrefix.length),
+                    topLevelKey  = relativePath.split('.')[0];
+
                 if (topLevelKey) {
-                    keys.add(topLevelKey);
+                    keys.add(topLevelKey)
                 }
             }
         }
-        return Array.from(keys);
+
+        return Array.from(keys)
     }
 
     /**
-     * Internal method to avoid code redundancy.
-     * Use setData() or setDataAtSameLevel() instead.
+     * This is the core method for setting data, providing a single entry point for all data modifications.
+     * It handles multiple scenarios:
+     * 1.  **Object-based updates:** If `key` is an object, it recursively calls itself for each key-value pair.
+     * 2.  **Data Records:** If `value` is a `Neo.data.Record`, it is treated as an atomic value and set directly.
+     * 3.  **Bubbling Reactivity:** For a given key (e.g., 'user.name'), it sets the leaf value and then "bubbles up"
+     *     the change, creating new parent objects (e.g., 'user') to ensure that effects depending on any part
+     *     of the path are triggered.
      *
-     * This method handles setting data properties, including nested paths and Neo.data.Record instances.
-     * It determines the owning StateProvider in the hierarchy and delegates to #setConfigValue.
+     * All updates are batched by the public `setData` methods to ensure effects run only once.
+     * Use `setData()` or `setDataAtSameLevel()` instead of calling this method directly.
      *
-     * Passing an originStateProvider param will try to set each key on the closest property match
-     * inside the parent stateProvider chain => setData()
-     * Not passing it will set all values on the stateProvider where the method gets called => setDataAtSameLevel()
-     * @param {Object|String} key
-     * @param {*} value
-     * @param {Neo.state.Provider} [originStateProvider]
+     * @param {Object|String} key The property to set, or an object of key-value pairs.
+     * @param {*} value The new value.
+     * @param {Neo.state.Provider} [originStateProvider] The provider to start the search from for hierarchical updates.
      * @protected
      */
     internalSetData(key, value, originStateProvider) {
         const me = this;
 
-        // If the value is a Neo.data.Record, treat it as an atomic value
-        // and set it directly without further recursive processing of its properties.
-        if (Neo.isObject(value) && value.isRecord) {
-            const
-                ownerDetails   = me.getOwnerOfDataProperty(key),
-                targetProvider = ownerDetails ? ownerDetails.owner : (originStateProvider || me);
-
-            me.#setConfigValue(targetProvider, key, value, null);
-            return
-        }
-
-        // If the key is an object, iterate over its entries and recursively call internalSetData.
-        // This handles setting multiple properties at once (e.g., setData({prop1: val1, prop2: val2})).
         if (Neo.isObject(key)) {
             Object.entries(key).forEach(([dataKey, dataValue]) => {
                 me.internalSetData(dataKey, dataValue, originStateProvider)
@@ -488,33 +481,52 @@ class Provider extends Base {
             return
         }
 
-        // Handle single key/value pairs, including nested paths (e.g., 'user.firstName').
+        // Now 'key' is a string path.
+        // If 'value' is a plain object, we need to drill down further.
+        // If the value is a Neo.data.Record, treat it as an atomic value => it will not enter this block.
+        if (Neo.typeOf(value) === 'Object') {
+            Object.entries(value).forEach(([nestedKey, nestedValue]) => {
+                const fullPath = `${key}.${nestedKey}`;
+                me.internalSetData(fullPath, nestedValue, originStateProvider);
+            });
+            return // We've delegated the setting to deeper paths.
+        }
+
         const
             ownerDetails   = me.getOwnerOfDataProperty(key),
-            targetProvider = ownerDetails ? ownerDetails.owner : (originStateProvider || me),
-            pathParts      = key.split('.');
-
-        let currentPath     = '',
-            currentConfig   = null,
-            currentProvider = targetProvider;
-
-        for (let i = 0; i < pathParts.length; i++) {
-            const part = pathParts[i];
-            currentPath = currentPath ? `${currentPath}.${part}` : part;
-            currentConfig = currentProvider.getDataConfig(currentPath);
-
-            if (i === pathParts.length - 1) { // Last part of the path
-                // Set the value for the final property in the path.
-                me.#setConfigValue(currentProvider, currentPath, value, null)
-            } else { // Intermediate part of the path
-                // Ensure intermediate paths exist as objects. If not, create them.
-                // If an intermediate path exists but is not an object, overwrite it with an empty object.
-                if (!currentConfig) {
-                    currentConfig = new Config({}); // Create an empty object config
-                    currentProvider.#dataConfigs[currentPath] = currentConfig
-                } else if (!Neo.isObject(currentConfig.get())) {
-                    currentConfig.set({})
+            targetProvider = ownerDetails ? ownerDetails.owner : (originStateProvider || me);
+
+        me.#setConfigValue(targetProvider, key, value, null);
+
+        // This is the "reactivity bubbling" logic. When a leaf property like 'user.name' changes,
+        // we must also trigger effects that depend on the parent object 'user'. We do this by
+        // creating a new object reference for each parent in the path. The spread syntax
+        // `{ ...oldParentValue, [leafKey]: latestValue }` is key, as it creates a new
+        // object, which the reactivity system detects as a change.
+        let path        = key,
+            latestValue = value;
+
+        while (path.includes('.')) {
+            const leafKey = path.split('.').pop();
+            path = path.substring(0, path.lastIndexOf('.'));
+
+            const parentConfig = targetProvider.getDataConfig(path);
+
+            if (parentConfig) {
+                const oldParentValue = parentConfig.get();
+                if (Neo.isObject(oldParentValue)) {
+                    const newParentValue = { ...oldParentValue, [leafKey]: latestValue };
+                    parentConfig.set(newParentValue);
+                    latestValue = newParentValue;
+                } else {
+                    break // Stop if parent is not an object
                 }
+            } else {
+                // If the parent config doesn't exist, we need to create it to support bubbling.
+                // This is crucial for creating new nested data structures at runtime.
+                const newParentValue = {[leafKey]: latestValue};
+                me.#setConfigValue(targetProvider, path, newParentValue);
+                latestValue = newParentValue
             }
         }
     }
@@ -528,6 +540,18 @@ class Provider extends Base {
         return Neo.isString(value) && value.startsWith('stores.')
     }
 
+    /**
+     * Gets called after all constructors & configs are applied.
+     * @protected
+     */
+    onConstructed() {
+        super.onConstructed();
+
+        // After the provider is fully constructed and initial data is set,
+        // run the formula effects for the first time to compute their initial values.
+        this.#formulaEffects.forEach(effect => effect.run())
+    }
+
     /**
      * @param {String} key
      * @param {*} value
@@ -552,22 +576,22 @@ class Provider extends Base {
 
             // Ensure a Config instance exists for the current fullPath
             if (me.#dataConfigs[fullPath]) {
-                me.#dataConfigs[fullPath].set(value);
+                me.#dataConfigs[fullPath].set(value)
             } else {
-                me.#dataConfigs[fullPath] = new Config(value);
+                me.#dataConfigs[fullPath] = new Config(value)
             }
 
             // If the value is a plain object, recursively process its properties
             if (Neo.typeOf(value) === 'Object') {
-                me.processDataObject(value, fullPath);
+                me.processDataObject(value, fullPath)
             }
         });
     }
 
     /**
      * @param {Neo.component.Base} component
-     * @param {String} configName
-     * @param {String} storeName
+     * @param {String}             configName
+     * @param {String}             storeName
      */
     resolveStore(component, configName, storeName) {
         let store = this.getStore(storeName);
@@ -582,9 +606,9 @@ class Provider extends Base {
      * This method creates a new Config instance if one doesn't exist for the given path,
      * or updates an existing one. It also triggers binding effects and calls onDataPropertyChange.
      * @param {Neo.state.Provider} provider The StateProvider instance owning the config.
-     * @param {String} path The full path of the data property (e.g., 'user.firstname').
-     * @param {*} newValue The new value to set.
-     * @param {*} oldVal The old value (optional, used for initial setup).
+     * @param {String}             path     The full path of the data property (e.g., 'user.firstname').
+     * @param {*}                  newValue The new value to set.
+     * @param {*}                 [oldVal]  The old value (optional, used for initial setup).
      * @private
      */
     #setConfigValue(provider, path, newValue, oldVal) {
@@ -608,21 +632,39 @@ class Provider extends Base {
     /**
      * The method will assign all values to the closest stateProvider where it finds an existing key.
      * In case no match is found inside the parent chain, a new data property will get generated.
+     *
+     * All updates within a single call are batched to ensure that reactive effects (bindings and formulas)
+     * are run only once.
+     *
      * @param {Object|String} key
-     * @param {*} value
+     * @param {*}             value
      */
     setData(key, value) {
-        this.internalSetData(key, value, this)
+        EffectManager.pause();
+        try {
+            this.internalSetData(key, value, this)
+        } finally {
+            EffectManager.resume()
+        }
     }
 
     /**
      * Use this method instead of setData() in case you want to enforce
      * setting all keys on this instance instead of looking for matches inside parent stateProviders.
+     *
+     * All updates within a single call are batched to ensure that reactive effects (bindings and formulas)
+     * are run only once.
+     *
      * @param {Object|String} key
-     * @param {*} value
+     * @param {*}             value
      */
     setDataAtSameLevel(key, value) {
-        this.internalSetData(key, value)
+        EffectManager.pause();
+        try {
+            this.internalSetData(key, value)
+        } finally {
+            EffectManager.resume()
+        }
     }
 }
 

package/src/state/createHierarchicalDataProxy.mjs

@@ -22,7 +22,7 @@ function createNestedProxy(rootProvider, path) {
             // Handle internal properties that might be set directly on the proxy's target
             // or are expected by the environment (like Siesta's __REFADR__).
             if (typeof property === 'symbol' || property === '__REFADR__' || property === 'inspect' || property === 'then') {
-                return Reflect.get(currentTarget, property);
+                return Reflect.get(currentTarget, property)
             }
 
             // Only allow string or number properties to proceed as data paths.
@@ -30,6 +30,20 @@ function createNestedProxy(rootProvider, path) {
                 return undefined; // For other non-string/non-number properties, return undefined.
             }
 
+            // Special handling for the 'stores' property at the root level
+            if (path === '' && property === 'stores') {
+                return new Proxy({}, {
+                    get(target, storeName) {
+                        if (typeof storeName === 'symbol' || storeName === '__REFADR__') {
+                            return Reflect.get(target, storeName)
+                        }
+                        // Delegate to the StateProvider's getStore method for hierarchical resolution
+                        // Accessing store.count later will register the dependency via the Config system
+                        return rootProvider.getStore(storeName)
+                    }
+                })
+            }
+
             const fullPath = path ? `${path}.${property}` : property;
 
             // 1. Check if the full path corresponds to an actual data property.
@@ -41,17 +55,15 @@ function createNestedProxy(rootProvider, path) {
                     config                = owner.getDataConfig(propertyName);
 
                 if (config) {
-                    const activeEffect = EffectManager.getActiveEffect();
-                    if (activeEffect) {
-                        activeEffect.addDependency(config);
-                    }
+                    EffectManager.getActiveEffect()?.addDependency(config);
 
                     const value = config.get();
                     // If the value is an object, return a new proxy for it to ensure nested accesses are also proxied.
-                    if (Neo.typeOf(value) === 'Object') {
+                    if (Neo.isObject(value)) {
                         return createNestedProxy(rootProvider, fullPath)
                     }
-                    return value;
+
+                    return value
                 }
             }
 
@@ -62,52 +74,54 @@ function createNestedProxy(rootProvider, path) {
                 return createNestedProxy(rootProvider, fullPath)
             }
 
-            // 3. If it's neither a data property nor a path to one, it doesn't exist in the state.
-            return null
+            // 3. If it's neither a data property nor a path to one, it doesn't exist.
+            //    Returning undefined ensures that chained accesses (e.g., data.nonexistent.property) fail gracefully.
         },
 
         set(currentTarget, property, value) {
             // Allow internal properties (like Symbols or specific strings) to be set directly on the target.
             if (typeof property === 'symbol' || property === '__REFADR__') {
-                return Reflect.set(currentTarget, property, value);
+                return Reflect.set(currentTarget, property, value)
             }
 
-            const fullPath = path ? `${path}.${property}` : property;
-            const ownerDetails = rootProvider.getOwnerOfDataProperty(fullPath);
-
+            const
+                fullPath     = path ? `${path}.${property}` : property,
+                ownerDetails = rootProvider.getOwnerOfDataProperty(fullPath);
             let targetProvider;
+
             if (ownerDetails) {
-                targetProvider = ownerDetails.owner;
+                targetProvider = ownerDetails.owner
             } else {
                 // If no owner is found, set it on the rootProvider (the one that created this proxy)
-                targetProvider = rootProvider;
+                targetProvider = rootProvider
             }
 
             targetProvider.setData(fullPath, value);
-            return true; // Indicate that the assignment was successful
+            return true // Indicate that the assignment was successful
         },
 
         ownKeys(currentTarget) {
-            return rootProvider.getTopLevelDataKeys(path);
+            return rootProvider.getTopLevelDataKeys(path)
         },
 
         getOwnPropertyDescriptor(currentTarget, property) {
-            const fullPath = path ? `${path}.${property}` : property;
-            const ownerDetails = rootProvider.getOwnerOfDataProperty(fullPath);
+            const
+                fullPath     = path ? `${path}.${property}` : property,
+                ownerDetails = rootProvider.getOwnerOfDataProperty(fullPath);
 
             if (ownerDetails) {
                 const config = ownerDetails.owner.getDataConfig(ownerDetails.propertyName);
+
                 if (config) {
                     const value = config.get();
                     return {
-                        value: Neo.isObject(value) ? createNestedProxy(rootProvider, fullPath) : value,
-                        writable: true,
-                        enumerable: true,
-                        configurable: true,
-                    };
+                        value       : Neo.isObject(value) ? createNestedProxy(rootProvider, fullPath) : value,
+                        writable    : true,
+                        enumerable  : true,
+                        configurable: true
+                    }
                 }
             }
-            return undefined; // Property not found
         }
     })
 }

package/src/tab/Container.mjs

@@ -32,6 +32,7 @@ class Container extends BaseContainer {
         /**
          * You can use null to not render any items initially
          * @member {Number|null} activeIndex_=0
+         * @reactive
          */
         activeIndex_: 0,
         /**
@@ -60,11 +61,13 @@ class Container extends BaseContainer {
         headerToolbar: null,
         /**
          * @member {Object|null} layout=null
+         * @reactive
          */
         layout: null,
         /**
          * True to not apply a background effect to the tab header container
          * @member {Boolean} plain_=true
+         * @reactive
          */
         plain_: true,
         /*
@@ -77,6 +80,7 @@ class Container extends BaseContainer {
          * true enables sorting tabs via drag&drop.
          * The config gets passed to the header toolbar
          * @member {Boolean} sortable_=false
+         * @reactive
          */
         sortable_: false,
         /**
@@ -96,6 +100,7 @@ class Container extends BaseContainer {
          * The position of the tab header toolbar.
          * Valid values are top, right, bottom, left.
          * @member {String} tabBarPosition_='top'
+         * @reactive
          */
         tabBarPosition_: 'top',
         /**
@@ -105,6 +110,7 @@ class Container extends BaseContainer {
         tabContainerCls: 'neo-tab-container',
         /**
          * @member {Boolean} useActiveTabIndicator_=true
+         * @reactive
          */
         useActiveTabIndicator_: true
     }

package/src/tab/Strip.mjs

@@ -26,6 +26,7 @@ class Strip extends Component {
         tabContainerId: null,
         /**
          * @member {Boolean} useActiveTabIndicator_=true
+         * @reactive
          */
         useActiveTabIndicator_: true,
         /**

package/src/tab/header/Button.mjs

@@ -23,10 +23,12 @@ class Button extends BaseButton {
         /**
          * Specify a role tag attribute for the vdom root.
          * @member {String|null} role='tab'
+         * @reactive
          */
         role: 'tab',
         /**
          * @member {Boolean} useActiveTabIndicator_=true
+         * @reactive
          */
         useActiveTabIndicator_: true,
         /**

package/src/tab/header/EffectButton.mjs

@@ -23,10 +23,12 @@ class EffectTabButton extends EffectButton {
         /**
          * Specify a role tag attribute for the vdom root.
          * @member {String|null} role='tab'
+         * @reactive
          */
         role: 'tab',
         /**
          * @member {Boolean} useActiveTabIndicator_=true
+         * @reactive
          */
         useActiveTabIndicator_: true
     }