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

package/test/siesta/tests/state/createHierarchicalDataProxy.mjs

@@ -0,0 +1,217 @@
+import Neo                           from '../../../../src/Neo.mjs';
+import * as core                     from '../../../../src/core/_export.mjs';
+import {createHierarchicalDataProxy} from '../../../../src/state/createHierarchicalDataProxy.mjs';
+import Effect                        from '../../../../src/core/Effect.mjs';
+import EffectManager                 from '../../../../src/core/EffectManager.mjs';
+import Config                        from '../../../../src/core/Config.mjs';
+import Base                          from '../../../../src/core/Base.mjs';
+
+// Mock StateProvider for testing purposes
+class MockStateProvider extends Base {
+    static config = {
+        className: 'Mock.State.Provider',
+        data_: null
+    }
+
+    #dataConfigs = {};
+
+    construct(config) {
+        super.construct(config);
+    }
+
+    afterSetData(value, oldValue) {
+        console.log(value);
+        if (value) {
+            this.processDataObject(value);
+        }
+    }
+
+    processDataObject(obj, path = '') {
+        Object.entries(obj).forEach(([key, value]) => {
+            const fullPath = path ? `${path}.${key}` : key;
+            if (Neo.typeOf(value) === 'Object') {
+                this.processDataObject(value, fullPath);
+            } else {
+                const clonedValue = Neo.isObject(value) ? Neo.clone(value, true) : value; // Deep clone objects
+                this.#dataConfigs[fullPath] = new Config(clonedValue);
+            }
+        });
+    }
+
+    getDataConfig(path) {
+        return this.#dataConfigs[path] || null;
+    }
+
+    getOwnerOfDataProperty(path) {
+        if (this.#dataConfigs[path]) {
+            return {owner: this, propertyName: path};
+        }
+        const parent = this.getParent();
+        if (parent) {
+            return parent.getOwnerOfDataProperty(path);
+        }
+        return null;
+    }
+
+    hasNestedDataStartingWith(path) {
+        const pathWithDot = `${path}.`;
+        if (Object.keys(this.#dataConfigs).some(key => key.startsWith(pathWithDot))) {
+            return true;
+        }
+        const parent = this.getParent();
+        return parent ? parent.hasNestedDataStartingWith(path) : false;
+    }
+
+    getParent() {
+        // For testing, we'll manually set a parent
+        return this._parent || null;
+    }
+}
+Neo.setupClass(MockStateProvider);
+
+StartTest(t => {
+    t.it('should resolve data from a single provider', t => {
+        const provider = Neo.create(MockStateProvider, {data: {name: 'Neo', version: 10}});
+        let effectRunCount = 0;
+
+        const effect = new Effect({
+            fn: () => {
+                effectRunCount++;
+                const proxy = createHierarchicalDataProxy(provider);
+                if (effectRunCount === 1) {
+                    t.is(proxy.name, 'Neo', 'Should get name from proxy (initial)');
+                    t.is(proxy.version, 10, 'Should get version from proxy (initial)');
+                } else if (effectRunCount === 2) {
+                    t.is(proxy.name, 'Neo.mjs', 'Should get name from proxy (updated)');
+                    t.is(proxy.version, 10, 'Should get version from proxy (unchanged)');
+                }
+            }
+        });
+
+        t.is(effectRunCount, 1, 'Effect should run once initially');
+        t.is(effect.dependencies.size, 2, 'Effect should track 2 dependencies');
+
+        provider.getDataConfig('name').set('Neo.mjs');
+        t.is(effectRunCount, 2, 'Effect should re-run when dependency changes');
+
+        effect.destroy();
+        provider.destroy();
+    });
+
+    t.it('should resolve nested data from a single provider', t => {
+        const provider = Neo.create(MockStateProvider, {data: {user: {firstName: 'John', lastName: 'Doe'}}});
+        let effectRunCount = 0;
+
+        const effect = new Effect({
+            fn: () => {
+                effectRunCount++;
+                const proxy = createHierarchicalDataProxy(provider);
+                if (effectRunCount === 1) {
+                    t.is(proxy.user.firstName, 'John', 'Should get nested firstName (initial)');
+                    t.is(proxy.user.lastName, 'Doe', 'Should get nested lastName (initial)');
+                } else if (effectRunCount === 2) {
+                    t.is(proxy.user.firstName, 'Jane', 'Should get nested firstName (updated)');
+                    t.is(proxy.user.lastName, 'Doe', 'Should get nested lastName (unchanged)');
+                }
+            }
+        });
+
+        t.is(effectRunCount, 1, 'Effect should run once initially');
+        t.is(effect.dependencies.size, 2, 'Effect should track 2 nested dependencies');
+
+        provider.getDataConfig('user.firstName').set('Jane');
+        t.is(effectRunCount, 2, 'Effect should re-run when nested dependency changes');
+
+        effect.destroy();
+        provider.destroy();
+    });
+
+    t.it('should resolve data from parent providers', t => {
+        const parentProvider = Neo.create(MockStateProvider, {data: {appTitle: 'My App', user: {firstName: 'Parent'}}});
+        const childProvider = Neo.create(MockStateProvider, {data: {user: {lastName: 'Child'}}});
+        childProvider._parent = parentProvider; // Manually set parent
+
+        let effectRunCount = 0;
+
+        const effect = new Effect({
+            fn: () => {
+                effectRunCount++;
+                const proxy = createHierarchicalDataProxy(childProvider);
+                if (effectRunCount === 1) {
+                    t.is(proxy.appTitle, 'My App', 'Should get appTitle from parent (initial)');
+                    t.is(proxy.user.firstName, 'Parent', 'Should get firstName from parent (initial)');
+                    t.is(proxy.user.lastName, 'Child', 'Should get lastName from child (initial)');
+                } else if (effectRunCount === 2) {
+                    t.is(proxy.appTitle, 'New App Title', 'Should get appTitle from parent (updated)');
+                    t.is(proxy.user.firstName, 'Parent', 'Should get firstName from parent (unchanged)');
+                    t.is(proxy.user.lastName, 'Child', 'Should get lastName from child (unchanged)');
+                } else if (effectRunCount === 3) {
+                    t.is(proxy.appTitle, 'New App Title', 'Should get appTitle from parent (unchanged)');
+                    t.is(proxy.user.firstName, 'Parent', 'Should get firstName from parent (unchanged)');
+                    t.is(proxy.user.lastName, 'New Child', 'Should get lastName from child (updated)');
+                } else if (effectRunCount === 4) {
+                    t.is(proxy.appTitle, 'New App Title', 'Should get appTitle from parent (unchanged)');
+                    t.is(proxy.user.firstName, 'New Parent', 'Should get firstName from parent (updated)');
+                    t.is(proxy.user.lastName, 'New Child', 'Should get lastName from child (unchanged)');
+                }
+            }
+        });
+
+        t.is(effectRunCount, 1, 'Effect should run once initially');
+        t.is(effect.dependencies.size, 3, 'Effect should track 3 dependencies across hierarchy');
+
+        parentProvider.getDataConfig('appTitle').set('New App Title');
+        t.is(effectRunCount, 2, 'Effect should re-run when parent dependency changes');
+
+        childProvider.getDataConfig('user.lastName').set('New Child');
+        t.is(effectRunCount, 3, 'Effect should re-run when child dependency changes');
+
+        parentProvider.getDataConfig('user.firstName').set('New Parent');
+        t.is(effectRunCount, 4, 'Effect should re-run when parent nested dependency changes');
+
+        effect.destroy();
+        parentProvider.destroy();
+        childProvider.destroy();
+    });
+
+    t.it('should handle properties that are not data or nested paths', t => {
+        const provider = Neo.create(MockStateProvider, {data: {foo: 'bar'}});
+        let effectRunCount = 0;
+
+        const effect = new Effect({
+            fn: () => {
+                effectRunCount++;
+                const proxy = createHierarchicalDataProxy(provider);
+                t.is(proxy.nonExistent, null, 'Should return null for non-existent property');
+                t.is(proxy.foo, 'bar', 'Should still get existing data');
+            }
+        });
+
+        t.is(effectRunCount, 1, 'Effect should run once initially');
+        t.is(effect.dependencies.size, 1, 'Effect should only track existing data dependencies');
+
+        effect.destroy();
+        provider.destroy();
+    });
+
+    t.it('should not track dependencies when no effect is active', t => {
+        const provider = Neo.create(MockStateProvider, {data: {test: 123}});
+        const proxy = createHierarchicalDataProxy(provider);
+
+        // No active effect
+        t.is(EffectManager.getActiveEffect(), null, 'No active effect');
+
+        // Access property without active effect
+        const value = proxy.test;
+        t.is(value, 123, 'Should get value correctly');
+
+        // Verify no dependencies were added to a non-existent effect
+        const mockEffect = { addDependency: t.fail }; // If this is called, test fails
+        EffectManager.push(mockEffect); // Temporarily push a mock effect
+        EffectManager.pop(); // Immediately pop it
+
+        t.pass('No error when accessing proxy without active effect');
+
+        provider.destroy();
+    });
+});

package/learn/guides/ExtendingNeoClasses.md

@@ -1,331 +0,0 @@
-# Extending Neo Classes
-
-Neo.mjs is built upon a robust and consistent class system. Understanding how to extend framework classes is fundamental to building custom functionality, whether you're creating new UI components, defining data structures, or implementing application logic.
-
-This guide covers the universal principles of class extension in Neo.mjs, which apply across all class types, not just UI components.
-
-## 1. The `static config` Block: Defining Properties
-
-Every Neo.mjs class utilizes a `static config` block. This is where you define the properties that instances of your class will possess. These properties can be simple values, objects, or even other Neo.mjs class configurations.
-
-```javascript readonly
-class MyBaseClass extends Neo.core.Base {
-    static config = {
-        className: 'My.Base.Class', // Unique identifier for the class
-        myString : 'Hello',
-        myNumber : 123
-    }
-}
-
-export default Neo.setupClass(MyBaseClass);
-```
-
-Common configs you'll encounter include `className` (a unique string identifier for your class) and `ntype` (a shorthand alias for component creation).
-
-## 2. Reactive Configs: The Trailing Underscore (`_`)
-
-A cornerstone of Neo.mjs's reactivity is the trailing underscore (`_`) convention for configs defined in `static config`. When you append an underscore to a config name (e.g., `myConfig_`), the framework automatically generates a reactive getter and setter for it.
-
-```javascript readonly
-class MyReactiveClass extends Neo.core.Base {
-    static config = {
-        className        : 'My.Reactive.Class',
-        myReactiveConfig_: 'initial value' // This config is reactive
-    }
-
-    onConstructed() {
-        super.onConstructed();
-        console.log(this.myReactiveConfig);  // Accesses the getter
-        this.myReactiveConfig = 'new value'; // Triggers the setter
-    }
-}
-
-export default Neo.setupClass(MyReactiveClass);
-```
-
-Assigning a new value to a reactive property (e.g., `this.myReactiveProp = 'new value'`) triggers its setter, which in turn can invoke lifecycle hooks, enabling automatic updates and side effects. Properties without the underscore are static and do not trigger this reactive behavior.
-
-## 3. Configuration Lifecycle Hooks (`beforeSet`, `afterSet`, `beforeGet`)
-
-For every reactive config (`myConfig_`), Neo.mjs provides three optional lifecycle hooks that you can implement in your class. These methods are automatically called by the framework during the config's lifecycle, offering powerful interception points:
-
-*   **`beforeSetMyConfig(value, oldValue)`**:
-    *   **Purpose**: Intercepts the value *before* it is set. Ideal for validation, type coercion, or transforming the incoming value.
-    *   **Return Value**: Return the (potentially modified) `value` that should be set. Returning `undefined` or `null` will prevent the value from being set.
-
-*   **`afterSetMyConfig(value, oldValue)`**:
-    *   **Purpose**: Executed *after* the value has been successfully set. Ideal for triggering side effects, updating the UI (e.g., calling `this.update()` for components), or firing events.
-    *   **Return Value**: None.
-
-*   **`beforeGetMyConfig(value)`**:
-    *   **Purpose**: Intercepts the value *before* it is returned by the getter. Useful for lazy initialization, computing values on demand, or returning a transformed version of the stored value.
-    *   **Return Value**: Return the `value` that should be returned by the getter.
-
-### Overriding Lifecycle Hooks: `super` vs. Full Override
-
-When extending a Neo.mjs class, you often need to customize the behavior of inherited lifecycle hooks (like `afterSet*`, `onConstructed`, etc.). You have two primary approaches:
-
-#### 1. Extending Parent Behavior (Calling `super`)
-
-This is the most common and recommended approach. By calling `super.methodName(...)`, you ensure that the parent class's implementation of the hook is executed. You can then add your custom logic either before or after the `super` call.
-
-This approach is crucial for maintaining the framework's intended behavior and ensuring that inherited features continue to function correctly.
-
-```javascript readonly
-import Button from '../../src/button/Base.mjs';
-
-class MyExtendedButton extends Button {
-    static config = {
-        className: 'My.Extended.Component',
-        // text_ config is inherited from Button.Base
-        // We can set a default value here if needed, or rely on button.Base's default
-        text: 'New Default Text'
-    }
-
-    // Example: Adding logic after the parent's afterSetText
-    afterSetText(value, oldValue) {
-        //  Add your custom pre-processing logic here
-        super.afterSetText(value, oldValue);
-        console.log(`Custom logic: Button text changed to "${value}"`);
-        // Add your custom post-processing logic here
-    }
-}
-
-export default Neo.setupClass(MyExtendedButton);
-```
-
-#### 2. Completely Overriding Parent Behavior (No `super` Call)
-
-In rare cases, you might want to completely replace the parent class's implementation of a hook. This is achieved by simply omitting the `super` call within your overridden method.
-
-**Caution**: Use this approach with extreme care. You must fully understand the parent's implementation and ensure that your override does not break essential framework functionality or inherited features. This is generally reserved for advanced scenarios where you need full control over the hook's execution.
-
-```javascript readonly
-import Button from '../../src/button/Base.mjs';
-
-class MyFullyOverriddenButton extends Button {
-    static config = {
-        className: 'My.Fully.Overridden.Component',
-        text     : 'New Default Text'
-    }
-
-    // Example: Completely overriding afterSetText
-    afterSetText(value, oldValue) {
-        // No super.afterSetText(value, oldValue); call
-        console.log(`Fully custom logic: Button text changed to "${value}"`);
-        // The parent's afterSetText will NOT be executed
-        // This means that in this case you need to take care on your own to map the text value to the vdom.
-    }
-}
-
-export default Neo.setupClass(MyFullyOverriddenButton);
-```
-
-
-
-```javascript readonly
-class MyHookedClass extends Neo.core.Base {
-    static config = {
-        className: 'My.Hooked.Class',
-        myValue_ : 0
-    }
-
-    beforeSetMyValue(value, oldValue) {
-        if (typeof value !== 'number' || value < 0) {
-            console.warn('myValue must be a non-negative number!');
-            return 0; // Default to 0 if invalid
-        }
-        return value;
-    }
-
-    afterSetMyValue(value, oldValue) {
-        console.log(`myValue changed from ${oldValue} to ${value}`);
-        // In a component, you might call this.update() here
-    }
-
-    beforeGetMyValue(value) {
-        // Example: lazy initialization or computed value
-        if (value === 0 && !this._initialized) {
-            console.log('Initializing myValue on first access');
-            this._initialized = true;
-            return 10; // Return a default initial value
-        }
-        return value;
-    }
-}
-
-export default Neo.setupClass(MyHookedClass);
-```
-
-## 4. The Role of `Neo.setupClass()` and the Global `Neo` Namespace
-
-When you define a class in Neo.mjs and pass it to `Neo.setupClass()`, the framework performs several crucial operations. One of the most significant is to **enhance the global `Neo` namespace** with a reference to your newly defined class.
-
-This means that after `Neo.setupClass(MyClass)` is executed, your class becomes accessible globally via `Neo.[your.class.name]`, where `[your.class.name]` corresponds to the `className` config you defined (e.g., `Neo.button.Base`, `Neo.form.field.Text`, or your custom `My.Custom.Class`).
-
-**Implications for Class Extension and Usage:**
-
-*   **Global Accessibility**: You can refer to any framework class (or your own custom classes after they've been set up) using their full `Neo` namespace path (e.g., `Neo.button.Base`, `Neo.container.Base`) anywhere in your application code, even without an explicit ES module import for that specific class.
-*   **Convenience vs. Best Practice**: While `extends Neo.button.Base` might technically work without an `import Button from '...'`, it is generally **not recommended** for application code. Explicit ES module imports (e.g., `import Button from '../button/Base.mjs';`) are preferred because they:
-    *   **Improve Readability**: Clearly show the dependencies of your module.
-    *   **Enhance Tooling**: Enable better static analysis, auto-completion, and refactoring support in modern IDEs.
-    *   **Ensure Consistency**: Promote a consistent and predictable coding style.
-*   **Framework Internal Use**: The global `Neo` namespace is heavily utilized internally by the framework itself for its class registry, dependency resolution, and dynamic instantiation (e.g., when using `ntype` or `module` configs).
-
-Understanding this mechanism clarifies how Neo.mjs manages its class system and provides the underlying flexibility for its configuration-driven approach.
-
-## 5. Practical Examples: Models, Stores, and Controllers
-
-The principles of class extension apply universally across all Neo.mjs class types.
-
-### Extending `Neo.data.Model`
-
-Models define the structure and behavior of individual data records. While reactive configs can be used for class-level properties of a Model (e.g., a global setting for all products), properties that vary per record (like `price` or `discount`) should be defined as fields within the `fields` array. Neo.mjs provides `convert` and `calculate` functions directly on field definitions for per-record logic.
-
-```javascript readonly
-import Model from '../../src/data/Model.mjs';
-
-class ProductModel extends Model {
-    static config = {
-        className: 'App.model.Product',
-        fields: [
-            {name: 'id',    type: 'Number'},
-            {name: 'name',  type: 'String'},
-            {name: 'price', type: 'Number', defaultValue: 0,
-                // Use a convert function for field-level validation or transformation
-                convert: value => {
-                    if (typeof value !== 'number' || value < 0) {
-                        console.warn('Price field must be a non-negative number!');
-                        return 0;
-                    }
-                    return value;
-                }
-            },
-            {name: 'discount', type: 'Number', defaultValue: 0,
-                // Use a convert function for field-level validation or transformation
-                convert: value => {
-                    if (typeof value !== 'number' || value < 0 || value > 1) {
-                        console.warn('Discount field must be a number between 0 and 1!');
-                        return 0;
-                    }
-                    return value;
-                }
-            },
-            {name: 'discountedPrice', type: 'Number',
-                // Use a calculate function for derived values based on other fields in the record
-                calculate: (data) => {
-                    // 'data' contains the raw field values of the current record
-                    return data.price * (1 - data.discount);
-                }
-            }
-        ]
-    }
-}
-
-Neo.setupClass(ProductModel);
-```
-
-### Extending `Neo.data.Store`
-
-Stores manage collections of data records, often using a defined `Model`.
-
-```javascript readonly
-import Store        from '../../src/data/Store.mjs';
-import ProductModel from './ProductModel.mjs'; // Assuming ProductModel is in the same directory
-
-class ProductsStore extends Store {
-    static config = {
-        className: 'App.store.Products',
-        model    : ProductModel, // Use our custom ProductModel
-        autoLoad : true,
-        url      : '/api/products', // Example API endpoint
-        sorters  : [{
-            property : 'name',
-            direction: 'ASC'
-        }]
-    }
-
-    // Custom method to filter by price range
-    filterByPriceRange(min, max) {
-        // The idiomatic way to apply filters is by setting the 'filters' config.
-        // This replaces any existing filters.
-        this.filters = [{
-            property: 'price',
-            operator: '>=',
-            value   : min
-        }, {
-            property: 'price',
-            operator: '<=',
-            value   : max
-        }];
-    }
-
-    // To add filters without replacing existing ones, you would typically
-    // read the current filters, add new ones, and then set the filters config.
-    // Example (conceptual, not part of the class):
-    /*
-    addPriceRangeFilter(min, max) {
-        const currentFilters = this.filters ? [...this.filters] : [];
-        currentFilters.push({
-            property: 'price',
-            operator: '>=',
-            value   : min
-        }, {
-            property: 'price',
-            operator: '<=',
-            value   : max
-        });
-        this.filters = currentFilters;
-    }
-    */
-}
-
-Neo.setupClass(ProductsStore);
-```
-
-### Extending `Neo.controller.Component`
-
-Controllers encapsulate logic related to components, often handling events or managing state.
-
-```javascript readonly
-import ComponentController from '../../src/controller/Component.mjs';
-
-class MyCustomController extends ComponentController {
-    static config = {
-        className: 'App.controller.MyCustom',
-        // A reactive property to manage a piece of controller-specific state
-        isActive_: false
-    }
-
-    onConstructed() {
-        super.onConstructed();
-        console.log('MyCustomController constructed!');
-    }
-
-    afterSetIsActive(value, oldValue) {
-        console.log(`Controller active state changed from ${oldValue} to ${value}`);
-        // Perform actions based on active state change
-        if (value) {
-            this.doSomethingActive();
-        } else {
-            this.doSomethingInactive();
-        }
-    }
-
-    doSomethingActive() {
-        console.log('Controller is now active!');
-        // Example: enable a feature, start a timer
-    }
-
-    doSomethingInactive() {
-        console.log('Controller is now inactive!');
-        // Example: disable a feature, clear a timer
-    }
-}
-
-Neo.setupClass(MyCustomController);
-```
-
-## Conclusion
-
-The class extension mechanism, coupled with the reactive config system and `Neo.setupClass()`, forms the backbone of development in Neo.mjs. By mastering these principles, you can create highly modular, maintainable, and powerful applications that seamlessly integrate with the framework's core.