neo.mjs 10.0.0-beta.6 → 10.0.1

package/src/core/Effect.mjs

@@ -1,7 +1,6 @@
-import Config             from './Config.mjs';
-import EffectManager      from './EffectManager.mjs';
-import EffectBatchManager from './EffectBatchManager.mjs';
-import IdGenerator        from './IdGenerator.mjs';
+import Config        from './Config.mjs';
+import EffectManager from './EffectManager.mjs';
+import IdGenerator   from './IdGenerator.mjs';
 
 /**
  * Creates a reactive effect that automatically tracks its dependencies and re-runs when any of them change.
@@ -73,8 +72,6 @@ class Effect {
     constructor(fn, options={}) {
         const me = this;
 
-        // This single statement handles both (fn, options) and ({...}) signatures
-        // by normalizing them into a single object that we can destructure.
         const {
               fn: effectFn,
               componentId,
@@ -88,16 +85,10 @@ class Effect {
 
         me.isRunning = new Config(false);
 
-        // The subscriber(s) must be added *before* the first run is triggered.
-        // This is critical for consumers like functional components, which need to process
-        // the initial VDOM synchronously within the constructor lifecycle.
         if (subscriber) {
-            // A concise way to handle both single and array subscribers.
             [].concat(subscriber).forEach(sub => me.isRunning.subscribe(sub))
         }
 
-        // If lazy, just store the function without running it.
-        // Otherwise, use the setter to trigger the initial run.
         if (lazy) {
             me._fn = effectFn
         } else {
@@ -117,41 +108,53 @@ class Effect {
     }
 
     /**
-     * Executes the effect function, tracking its dependencies.
-     * This is called automatically on creation and whenever a dependency changes.
-     * The dynamic re-tracking ensures the effect always reflects its current dependencies,
-     * even if the logic within `fn` changes conditionally.
+     * Executes the effect function, re-evaluating its dependencies.
+     * If the EffectManager is paused (e.g., inside a batch), it queues itself to be run later.
      * @protected
      */
     run() {
         const me = this;
 
-        EffectManager.pause(); // Pause dependency tracking for isRunning.get()
-        if (me.isDestroyed || me.isRunning.get()) {
-            EffectManager.resume(); // Resume if we return early
+        if (me.isDestroyed) {
             return
         }
 
-        if (EffectBatchManager.isBatchActive()) {
-            EffectBatchManager.queueEffect(me);
+        // Check if already running without creating a dependency on `isRunning`.
+        EffectManager.pauseTracking();
+        const isRunning = me.isRunning.get();
+        EffectManager.resumeTracking();
+
+        if (isRunning) {
             return
         }
 
+        // If the manager is globally paused for batching, queue this effect and stop.
+        if (EffectManager.isPaused()) {
+            EffectManager.queue(me);
+            return
+        }
+
+        // Set `isRunning` to true without creating a dependency.
+        EffectManager.pauseTracking();
         me.isRunning.set(true);
+        EffectManager.resumeTracking();
 
+        // Clear old dependencies and set this as the active effect.
         me.dependencies.forEach(cleanup => cleanup());
         me.dependencies.clear();
-
         EffectManager.push(me);
-        EffectManager.resume();
 
         try {
+            // Execute the function, which will collect new dependencies.
             me.fn()
         } finally {
+            // Clean up after the run.
             EffectManager.pop();
-            EffectManager.pause(); // Pause dependency tracking for isRunning.set(false)
+
+            // Set `isRunning` to false without creating a dependency.
+            EffectManager.pauseTracking();
             me.isRunning.set(false);
-            EffectManager.resume() // Resume after isRunning.set(false)
+            EffectManager.resumeTracking()
         }
     }
 
@@ -163,7 +166,6 @@ class Effect {
     addDependency(config) {
         const me = this;
 
-        // Only add if not already a dependency. Map uses strict equality (===) for object keys.
         if (!me.dependencies.has(config)) {
             const cleanup = config.subscribe({
                 id: me.id,
@@ -175,11 +177,7 @@ class Effect {
     }
 }
 
-Neo.core ??= {};
-
-if (!Neo.core.Effect) {
-    Neo.core.Effect = Effect;
-
+export default Neo.gatekeep(Effect, 'Neo.core.Effect', () => {
     /**
      * Factory shortcut to create a new Neo.core.Effect instance.
      * @function Neo.effect
@@ -188,6 +186,4 @@ if (!Neo.core.Effect) {
      * @returns {Neo.core.Effect}
      */
     Neo.effect = (fn, options) => new Effect(fn, options)
-}
-
-export default Neo.core.Effect;
+});

package/src/core/EffectManager.mjs

@@ -1,20 +1,47 @@
 /**
- * A singleton manager to track the currently running effect.
- * This allows reactive properties to know which effect to subscribe to.
+ * A singleton manager to track the currently running effect and control global effect execution.
+ * It provides a centralized mechanism for pausing, resuming, and batching effect runs.
  * @class Neo.core.EffectManager
  * @singleton
  */
 const EffectManager = {
+    /**
+     * A stack to keep track of the currently active effect and its predecessors.
+     * @member {Neo.core.Effect[]} effectStack=[]
+     * @protected
+     */
     effectStack: [],
-    isPaused   : false,
+    /**
+     * A flag to temporarily disable dependency tracking for the active effect.
+     * This is used internally to prevent effects from depending on their own state, like `isRunning`.
+     * @member {Boolean} isTrackingPaused=false
+     * @protected
+     */
+    isTrackingPaused: false,
+    /**
+     * A counter to manage nested calls to pause() and resume(). Effect execution is
+     * paused or batched while this counter is greater than 0.
+     * @member {Number} pauseCounter=0
+     * @protected
+     */
+    pauseCounter: 0,
+    /**
+     * A Set to store unique effects that are triggered while the manager is paused.
+     * These effects will be run when resume() is called and the pauseCounter returns to 0.
+     * @member {Set<Neo.core.Effect>} queuedEffects=new Set()
+     * @protected
+     */
+    queuedEffects: new Set(),
 
     /**
-     * Adds a `Neo.core.Config` instance as a dependency for the currently active effect.
-     * This method checks if the EffectManager is paused before adding the dependency.
+     * Adds a `Neo.core.Config` instance as a dependency for the currently active effect,
+     * unless dependency tracking is explicitly paused.
      * @param {Neo.core.Config} config The config instance to add as a dependency.
      */
     addDependency(config) {
-        !this.isPaused && this.getActiveEffect()?.addDependency(config)
+        if (!this.isTrackingPaused) {
+            this.getActiveEffect()?.addDependency(config)
+        }
     },
 
     /**
@@ -26,14 +53,31 @@ const EffectManager = {
     },
 
     /**
-     * Pauses dependency tracking for effects. While paused, calls to `addDependency` will be ignored.
+     * Checks if effect execution is currently paused or batched.
+     * @returns {Boolean} True if the pauseCounter is greater than 0.
+     */
+    isPaused() {
+        return this.pauseCounter > 0
+    },
+
+    /**
+     * Pauses effect execution and begins batching.
+     * Each call to pause() increments a counter, allowing for nested control.
      */
     pause() {
-        this.isPaused = true;
+        this.pauseCounter++
+    },
+
+    /**
+     * Disables dependency tracking for the currently active effect.
+     * @protected
+     */
+    pauseTracking() {
+        this.isTrackingPaused = true
     },
 
     /**
-     * Pops the current effect from the stack, returning to the previous effect (if any).
+     * Pops the current effect from the stack.
      * @returns {Neo.core.Effect|null}
      */
     pop() {
@@ -41,7 +85,7 @@ const EffectManager = {
     },
 
     /**
-     * Pushes an effect onto the stack, marking it as the currently running effect.
+     * Pushes an effect onto the stack.
      * @param {Neo.core.Effect} effect The effect to push.
      */
     push(effect) {
@@ -49,12 +93,55 @@ const EffectManager = {
     },
 
     /**
-     * Resumes dependency tracking for effects.
+     * Queues a unique effect to be run later.
+     * @param {Neo.core.Effect} effect The effect to queue.
+     * @protected
+     */
+    queue(effect) {
+        this.queuedEffects.add(effect)
+    },
+
+    /**
+     * Resumes effect execution. If the pause counter returns to zero and effects
+     * have been queued, they will all be executed synchronously.
      */
     resume() {
-        this.isPaused = false;
+        let me = this;
+
+        if (me.pauseCounter > 0) {
+            me.pauseCounter--;
+
+            if (me.pauseCounter === 0 && me.queuedEffects.size > 0) {
+                const effectsToRun = [...me.queuedEffects];
+                me.queuedEffects.clear();
+                effectsToRun.forEach(effect => effect.run())
+            }
+        }
+    },
+
+    /**
+     * Re-enables dependency tracking for the currently active effect.
+     * @protected
+     */
+    resumeTracking() {
+        this.isTrackingPaused = false
     }
 };
 
-export default Neo.gatekeep(EffectManager, 'Neo.core.EffectManager');
-
+export default Neo.gatekeep(EffectManager, 'Neo.core.EffectManager', () => {
+    /**
+     * Wraps a function in a batch operation, ensuring that all effects triggered
+     * within it are run only once after the function completes.
+     * @function Neo.batch
+     * @param {Function} fn The function to execute.
+     */
+    Neo.batch = function(fn) {
+        EffectManager.pause();
+        try {
+            fn()
+        } finally {
+            // The public resume() method handles running queued effects.
+            EffectManager.resume()
+        }
+    }
+});

package/src/core/Observable.mjs

@@ -1,7 +1,16 @@
 import Base              from './Base.mjs';
 import NeoArray          from '../util/Array.mjs';
+import {isDescriptor}    from '../core/ConfigSymbols.mjs';
 import {resolveCallback} from '../util/Function.mjs';
 
+/**
+ * A unique, non-enumerable key for the internal event map.
+ * Using a Symbol prevents property name collisions on the consuming class instance,
+ * providing a robust way to manage private state within a mixin.
+ * @type {Symbol}
+ */
+const eventMapSymbol = Symbol('eventMap');
+
 /**
  * @class Neo.core.Observable
  * @extends Neo.core.Base
@@ -19,12 +28,35 @@ class Observable extends Base {
          */
         ntype: 'mixin-observable',
         /**
-         * @member {Boolean} mixin=true
-         * @protected
+         * A declarative way to assign event listeners to an instance upon creation.
+         * The framework processes this config and calls `on()` to populate the
+         * internal event registry. This config should not be manipulated directly after
+         * instantiation; use `on()` and `un()` instead.
+         * @member {Object|null} listeners_
+         * @example
+         * listeners: {
+         *     myEvent: 'onMyEvent',
+         *     otherEvent: {
+         *         fn: 'onOtherEvent',
+         *         delay: 100,
+         *         once: true
+         *     },
+         *     scope: this
+         * }
+         * @reactive
          */
-        mixin: true
+        listeners_: {
+            [isDescriptor]: true,
+            merge         : 'deep',
+            value         : {}
+        }
     }
 
+    /**
+     * @member {Object} [eventMapSymbol]
+     * @private
+     */
+
     /**
      * @param {Object|String} name
      * @param {Object} [opts]
@@ -101,6 +133,12 @@ class Observable extends Base {
         }
 
         if (!nameObject) {
+            // LAZY INITIALIZATION: The key to a robust mixin.
+            // This ensures the private internal listener store exists on the instance.
+            // `eventMapSymbol` is the *actual* registry of handler arrays, and is
+            // intentionally separate from the public `listeners_` config.
+            me[eventMapSymbol] ??= {};
+
             eventConfig = {fn: listener, id: eventId || Neo.getId('event')};
 
             if (data)      {eventConfig.data   = data}
@@ -108,7 +146,7 @@ class Observable extends Base {
             if (once)      {eventConfig.once   = once}
             if (scope)     {eventConfig.scope  = scope}
 
-            if (existing = me.listeners?.[name]) {
+            if ((existing = me[eventMapSymbol][name])) {
                 existing.forEach(cfg => {
                     if (cfg.id === eventId || (cfg.fn === listener && cfg.scope === scope)) {
                         console.error('Duplicate event handler attached:', name, me)
@@ -123,7 +161,7 @@ class Observable extends Base {
                     existing.push(eventConfig)
                 }
             } else {
-                me.listeners[name] = [eventConfig]
+                me[eventMapSymbol][name] = [eventConfig] // Use the private eventMapSymbol registry
             }
 
             return eventConfig.id
@@ -132,6 +170,25 @@ class Observable extends Base {
         return null
     }
 
+    /**
+     * This hook is the bridge between the declarative `listeners_` config and the
+     * imperative `on()`/`un()` methods. It's called automatically by the framework
+     * whenever the `listeners` config property is changed.
+     * @param {Object} value The new listeners object
+     * @param {Object} oldValue The old listeners object
+     * @protected
+     */
+    afterSetListeners(value, oldValue) {
+        // Unregister any listeners from the old config object
+        if (oldValue && Object.keys(oldValue).length > 0) {
+            this.un(oldValue)
+        }
+        // Register all listeners from the new config object
+        if (value && Object.keys(value).length > 0) {
+            this.on(value)
+        }
+    }
+
     /**
      * Call the passed function, or a function by *name* which exists in the passed scope's
      * or this component's ownership chain.
@@ -164,7 +221,7 @@ class Observable extends Base {
     fire(name) {
         let me        = this,
             args      = [].slice.call(arguments, 1),
-            listeners = me.listeners,
+            listeners = me[eventMapSymbol], // Always use the private, structured registry for firing events.
             delay, handler, handlers, i, len;
 
         if (listeners && listeners[name]) {
@@ -203,50 +260,6 @@ class Observable extends Base {
         }
     }
 
-    /**
-     * @param {Object} config
-     */
-    initObservable(config) {
-        let me = this,
-            proto = me.__proto__,
-            ctor  = proto.constructor,
-            listeners;
-
-        if (config.listeners) {
-            me.listeners = config.listeners;
-            delete config.listeners
-        }
-
-        listeners = me.listeners;
-
-        me.listeners = {};
-
-        if (listeners) {
-            if (Neo.isObject(listeners)) {
-                listeners = {...listeners}
-            }
-
-            me.addListener(listeners);
-        }
-
-        while (proto?.constructor.isClass) {
-            ctor = proto.constructor;
-
-            if (ctor.observable && !ctor.listeners) {
-                Object.assign(ctor, {
-                    addListener   : me.addListener,
-                    fire          : me.fire,
-                    listeners     : {},
-                    on            : me.on,
-                    removeListener: me.removeListener,
-                    un            : me.un
-                })
-            }
-
-            proto = proto.__proto__
-        }
-    }
-
     /**
      * Alias for addListener
      * @param {Object|String} name
@@ -287,6 +300,9 @@ class Observable extends Base {
         let me = this,
             i, len, listener, listeners, match;
 
+        // LAZY INITIALIZATION: Ensure the internal listener store exists.
+        me[eventMapSymbol] ??= {};
+
         if (Neo.isFunction(eventId)) {
             me.removeListener({[name]: eventId, scope});
             return
@@ -299,7 +315,7 @@ class Observable extends Base {
             }
 
             Object.entries(name).forEach(([key, value]) => {
-                listeners = me.listeners[key] || [];
+                listeners = me[eventMapSymbol][key] || [];
                 i         = 0;
                 len       = listeners.length;
 
@@ -314,9 +330,9 @@ class Observable extends Base {
                         break
                     }
                 }
-            });
+            })
         } else if (Neo.isString(eventId)) {
-            listeners = me.listeners[name];
+            listeners = me[eventMapSymbol][name];
             match     = false;
 
             listeners.forEach((eventConfig, idx) => {
@@ -331,18 +347,6 @@ class Observable extends Base {
         }
     }
 
-    // removeAllListeners: function(name) {
-
-    // },
-
-    // suspendListeners: function(queue) {
-
-    // },
-
-    // resumeListeners: function() {
-
-    // }
-
     /**
      * Alias for removeListener
      * @param {Object|String} name

package/src/form/field/Text.mjs

@@ -1391,13 +1391,19 @@ class Text extends Field {
     onInputValueChange(data) {
         let me         = this,
             oldValue   = me.value,
-            inputValue = data.value,
-            vnode      = VNodeUtil.find(me.vnode, {nodeName: 'input'});
+            inputValue = data.value;
 
-        if (vnode) {
-            // Update the current state (modified DOM by the user) to enable the delta-updates logic.
+        // Find the VNode for the real input element within the component's vnode tree.
+        const {vnode: inputVNode} = VNodeUtil.find(me.vnode, {nodeName: 'input'}) || {};
+
+        if (inputVNode) {
+            // This is the critical synchronization step. The user's input has changed the
+            // real DOM on the Main Thread. We must manually update our "last known state"
+            // (this.vnode) to match this reality *before* the next diffing cycle runs.
+            // This prevents the framework from sending a redundant delta update that could
+            // overwrite the user's input or cause cursor jumps.
             // Required e.g. for validation -> revert a wrong user input
-            vnode.vnode.attributes.value = inputValue
+            inputVNode.attributes.value = inputValue
         }
 
         if (Neo.isString(inputValue)) {