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

package/src/core/Config.mjs

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

package/src/core/ConfigSymbols.mjs

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

package/src/core/Util.mjs

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

package/src/data/RecordFactory.mjs

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

package/src/form/field/ComboBox.mjs

@@ -118,7 +118,12 @@ class ComboBox extends Picker {
          * which you want to submit instead
          * @member {Number|String} valueField='id'
          */
-        valueField: 'id'
+        valueField: 'id',
+        /**
+         * Default width to prevent rendering issues.
+         * @member {Number} width=150
+         */
+        width: 150
     }
 
     /**

package/src/util/Function.mjs

@@ -1,3 +1,6 @@
+const originalMethodSymbol = Symbol('originalMethod');
+const sequencedFnsSymbol   = Symbol('sequencedFns');
+
 /**
  * Append args instead of prepending them
  * @param {Function} fn
@@ -67,12 +70,30 @@ export function createInterceptor(target, targetMethodName, interceptFunction, s
  * @returns {Function}
  */
 export function createSequence(target, methodName, fn, scope) {
-    let method = target[methodName] || Neo.emptyFn;
+    let currentMethod = target[methodName],
+        wrapper;
+
+    if (currentMethod && currentMethod[sequencedFnsSymbol]) {
+        // Already a sequenced method, add to its list
+        wrapper = currentMethod;
+        wrapper[sequencedFnsSymbol].push({fn, scope})
+    } else {
+        // First time sequencing this method
+        let originalMethod = currentMethod || Neo.emptyFn;
+
+        wrapper = function() {
+            originalMethod.apply(this, arguments); // Call the original method
+
+            // Call all sequenced functions
+            wrapper[sequencedFnsSymbol].forEach(seqFn => {
+                seqFn.fn.apply(seqFn.scope || this, arguments);
+            });
+        };
+        wrapper[sequencedFnsSymbol] = [{fn, scope}];
+        wrapper[originalMethodSymbol] = originalMethod; // Store original method
+    }
 
-    return (target[methodName] = function() {
-        method.apply(this, arguments);
-        return fn.apply(scope || this, arguments)
-    })
+    return (target[methodName] = wrapper);
 }
 
 /**
@@ -178,3 +199,29 @@ export function throttle(callback, scope, delay=300) {
         }
     }
 }
+
+/**
+ * @param {Neo.core.Base} target
+ * @param {String} methodName
+ * @param {Function} fn
+ * @param {Object} scope
+ */
+export function unSequence(target, methodName, fn, scope) {
+    let currentMethod = target[methodName];
+
+    if (!currentMethod || !currentMethod[sequencedFnsSymbol]) {
+        return // Not a sequenced method
+    }
+
+    const sequencedFunctions = currentMethod[sequencedFnsSymbol];
+
+    // Filter out the function to unsequence
+    currentMethod[sequencedFnsSymbol] = sequencedFunctions.filter(seqFn =>
+        !(seqFn.fn === fn && seqFn.scope === scope)
+    );
+
+    if (currentMethod[sequencedFnsSymbol].length === 0) {
+        // If no functions left, restore the original method
+        target[methodName] = currentMethod[originalMethodSymbol]
+    }
+}

package/src/vdom/Helper.mjs

@@ -508,11 +508,13 @@ class Helper extends Base {
 
         let me = this;
 
-        // Subscribe to global Neo.config changes for dynamic renderer switching.
-        Neo.currentWorker.on({
-            neoConfigChange: me.onNeoConfigChange,
-            scope          : me
-        });
+        if (!NeoConfig.unitTestMode) {
+            // Subscribe to global Neo.config changes for dynamic renderer switching.
+            Neo.currentWorker.on({
+                neoConfigChange: me.onNeoConfigChange,
+                scope          : me
+            })
+        }
 
         await me.importUtil()
     }

package/test/siesta/tests/ReactiveConfigs.mjs

@@ -0,0 +1,112 @@
+import Neo       from '../../../src/Neo.mjs';
+import * as core from '../../../src/core/_export.mjs';
+import {isDescriptor} from '../../../src/core/ConfigSymbols.mjs';
+
+class MyComponent extends core.Base {
+    static config = {
+        className: 'Neo.TestComponent',
+        myConfig_ : 'initialValue',
+        arrayConfig_: {
+            [isDescriptor]: true,
+            value: [],
+            merge: 'replace'
+        },
+        objectConfig_: {
+            [isDescriptor]: true,
+            value: {},
+            merge: 'deep'
+        }
+    }
+
+    afterSetMyConfig(value, oldValue) {
+        // This will be called by the framework
+    }
+}
+
+MyComponent = Neo.setupClass(MyComponent);
+
+StartTest(t => {
+    t.it('Basic reactivity with subscribe', t => {
+        const instance = Neo.create(MyComponent);
+        const configController = instance.getConfig('myConfig');
+
+        let subscriberCalled = false;
+        let receivedNewValue, receivedOldValue;
+
+        const cleanup = configController.subscribe((newValue, oldValue) => {
+            subscriberCalled = true;
+            receivedNewValue = newValue;
+            receivedOldValue = oldValue;
+        });
+
+        instance.myConfig = 'newValue';
+
+        t.ok(subscriberCalled, 'Subscriber callback should be called');
+        t.is(receivedNewValue, 'newValue', 'New value should be passed to subscriber');
+        t.is(receivedOldValue, 'initialValue', 'Old value should be passed to subscriber');
+
+        // Test cleanup
+        subscriberCalled = false;
+        cleanup();
+        instance.myConfig = 'anotherValue';
+        t.notOk(subscriberCalled, 'Subscriber callback should not be called after cleanup');
+    });
+
+    t.it('Descriptor: arrayConfig_ with merge: replace', t => {
+        const instance = Neo.create(MyComponent);
+        const configController = instance.getConfig('arrayConfig');
+
+        let subscriberCalled = 0;
+        configController.subscribe((newValue, oldValue) => {
+            subscriberCalled++;
+        });
+
+        const arr1 = [1, 2, 3];
+        instance.arrayConfig = arr1;
+        t.is(instance.arrayConfig, arr1, 'Array should be replaced');
+        t.is(subscriberCalled, 1, 'Subscriber called once for array replacement');
+
+        const arr2 = [4, 5, 6];
+        instance.arrayConfig = arr2;
+        t.is(instance.arrayConfig, arr2, 'Array should be replaced again');
+        t.is(subscriberCalled, 2, 'Subscriber called twice for array replacement');
+
+        // Setting the same array should not trigger a change by default isEqual
+        instance.arrayConfig = arr2;
+        t.is(subscriberCalled, 2, 'Subscriber not called when setting the same array reference');
+    });
+
+    t.it('Descriptor: objectConfig_ with merge: deep', t => {
+        const instance = Neo.create(MyComponent);
+        const configController = instance.getConfig('objectConfig');
+
+        let subscriberCalled = 0;
+        configController.subscribe((newValue, oldValue) => {
+            subscriberCalled++;
+        });
+
+        const obj1 = {a: 1, b: {c: 2}};
+        instance.objectConfig = obj1;
+        t.is(instance.objectConfig, obj1, 'Object should be set');
+        t.is(subscriberCalled, 1, 'Subscriber called once for object set');
+
+        // Deep merge should happen, but default isEqual will still compare references
+        const obj2 = {a: 1, b: {c: 3}};
+        instance.objectConfig = obj2;
+        t.is(instance.objectConfig.a, 1, 'Object property a should be 1');
+        t.is(instance.objectConfig.b.c, 3, 'Object property b.c should be 3');
+        t.is(subscriberCalled, 2, 'Subscriber called twice for object change');
+
+        // Setting the same object reference should not trigger a change
+        instance.objectConfig = obj2;
+        t.is(subscriberCalled, 2, 'Subscriber not called when setting the same object reference');
+
+        // Modifying a nested property should trigger a change if isEqual is deep
+        // NOTE: The current Config.mjs uses Neo.isEqual which is a deep comparison.
+        // If the object reference changes, it will trigger. If the object reference stays the same, but content changes, it will not trigger unless isEqual is customized.
+        // For now, this test relies on the fact that setting a new object reference triggers the change.
+        const obj3 = {a: 1, b: {c: 2}};
+        instance.objectConfig = obj3;
+        t.is(subscriberCalled, 3, 'Subscriber called for new object reference');
+    });
+});

package/learn/guides/CustomComponents.md

@@ -1,45 +0,0 @@
-## Introduction
-
-Neo.mjs is class-based, which means you're free to extend any component (or any other Neo.mjs class).
-
-
-## Overriding ancestor configs
-
-## Introducing new configs
-
-## Lifecycle config properties
-
-```javascript live-preview
-import Button from '../button/Base.mjs';
-// In practice this would be some handy reusable component
-class MySpecialButton extends Button {
-    static config = {
-        className: 'Example.view.MySpecialButton',
-        iconCls  : 'far fa-face-grin-wide',
-        ui       : 'ghost'
-    }
-}
-
-MySpecialButton = Neo.setupClass(MySpecialButton);
-
-
-import Container from '../container/Base.mjs';
-
-class MainView extends Container {
-    static config = {
-        className: 'Example.view.MainView',
-        layout   : {ntype:'vbox', align:'start'},
-        items    : [{
-            module : Button,
-            iconCls: 'fa fa-home',
-            text   : 'A framework button'
-        }, {
-            module : MySpecialButton,
-            text   : 'My special button'
-        }]
-    }
-}
-
-Neo.setupClass(MainView);
-```
-

package/learn/guides/Forms.md

@@ -1 +0,0 @@
-## todo

package/learn/guides/Layouts.md

@@ -1 +0,0 @@
-## todo