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

package/src/core/Effect.mjs

@@ -0,0 +1,193 @@
+import Config             from './Config.mjs';
+import EffectManager      from './EffectManager.mjs';
+import EffectBatchManager from './EffectBatchManager.mjs';
+import IdGenerator        from './IdGenerator.mjs';
+
+/**
+ * Creates a reactive effect that automatically tracks its dependencies and re-runs when any of them change.
+ * This is a lightweight, plain JavaScript class for performance.
+ * It serves as a core reactive primitive, enabling automatic and dynamic dependency tracking.
+ * @class Neo.core.Effect
+ */
+class Effect {
+    /**
+     * The optional component id this effect belongs to.
+     * @member {String|null} componentId=null
+     */
+    componentId = null
+    /**
+     * A Map containing Config instances as keys and their cleanup functions as values.
+     * @member {Map} dependencies=new Map()
+     * @protected
+     */
+    dependencies = new Map()
+    /**
+     * The function to execute.
+     * @member {Function|null} _fn=null
+     */
+    _fn = null
+    /**
+     * The unique identifier for this effect instance.
+     * @member {String|null}
+     */
+    id = IdGenerator.getId('effect')
+    /**
+     * @member {Boolean}
+     * @protected
+     */
+    isDestroyed = false
+    /**
+     * @member {Neo.core.Config}
+     * @protected
+     */
+    isRunning = null
+
+    /**
+     * @member fn
+     */
+    get fn() {
+        return this._fn
+    }
+    set fn(value) {
+        this._fn = value;
+        // Assigning a new function to `fn` automatically triggers a re-run.
+        // This ensures that the effect immediately re-evaluates its dependencies
+        // based on the new function's logic, clearing old dependencies and establishing new ones.
+        this.run()
+    }
+
+    /**
+     * @param {Function|Object}  fn              - The function to execute, or a config object for the effect.
+     * @param {Function}        [fn.fn]          - The function to execute for the effect (if the first argument is an object).
+     * @param {String}          [fn.componentId] - The component id this effect belongs to.
+     * @param {Boolean}         [fn.lazy=false]  - If true, the effect will not run immediately upon creation.
+     * @param {Object|Object[]} [fn.subscriber]  - A single subscriber or an array of subscribers for the isRunning config.
+     * @param {Object}          [options={}]     - Optional. Used if the first argument is a function, this object contains the options.
+     * @example
+     * // Signature 1: Function and Options
+     * const myEffect = new Effect(() => console.log('Run'), {lazy: true});
+     * @example
+     * // Signature 2: Single Config Object
+     * const myEffect = new Effect({fn: () => console.log('Run'), lazy: true});
+     */
+    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,
+              lazy = false,
+              subscriber
+        } = (typeof fn === 'function') ? { ...options, fn } : (fn || {});
+
+        if (componentId) {
+            me.componentId = componentId
+        }
+
+        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 {
+            me.fn = effectFn
+        }
+    }
+
+    /**
+     * Cleans up all subscriptions and destroys the effect.
+     */
+    destroy() {
+        const me = this;
+
+        me.dependencies.forEach(cleanup => cleanup());
+        me.dependencies.clear();
+        me.isDestroyed = true
+    }
+
+    /**
+     * 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.
+     * @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
+            return
+        }
+
+        if (EffectBatchManager.isBatchActive()) {
+            EffectBatchManager.queueEffect(me);
+            return
+        }
+
+        me.isRunning.set(true);
+
+        me.dependencies.forEach(cleanup => cleanup());
+        me.dependencies.clear();
+
+        EffectManager.push(me);
+        EffectManager.resume();
+
+        try {
+            me.fn()
+        } finally {
+            EffectManager.pop();
+            EffectManager.pause(); // Pause dependency tracking for isRunning.set(false)
+            me.isRunning.set(false);
+            EffectManager.resume() // Resume after isRunning.set(false)
+        }
+    }
+
+    /**
+     * Adds a `Neo.core.Config` instance as a dependency for this effect.
+     * @param {Neo.core.Config} config The config instance to subscribe to.
+     * @protected
+     */
+    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,
+                fn: me.run.bind(me)
+            });
+
+            me.dependencies.set(config, cleanup)
+        }
+    }
+}
+
+Neo.core ??= {};
+
+if (!Neo.core.Effect) {
+    Neo.core.Effect = Effect;
+
+    /**
+     * Factory shortcut to create a new Neo.core.Effect instance.
+     * @function Neo.effect
+     * @param {Function|Object} fn - The function to execute, or a config object for the effect.
+     * @param {Object} [options] - Optional. Used if the first argument is a function.
+     * @returns {Neo.core.Effect}
+     */
+    Neo.effect = (fn, options) => new Effect(fn, options)
+}
+
+export default Neo.core.Effect;

package/src/core/EffectBatchManager.mjs

@@ -0,0 +1,67 @@
+/**
+ * A singleton manager responsible for batching `Neo.core.Effect` executions.
+ * This ensures that effects triggered by multiple config changes within a single
+ * synchronous operation (e.g., `Neo.core.Base#set()`) are executed only once
+ * per batch, after all changes have been applied.
+ * @class Neo.core.EffectBatchManager
+ * @singleton
+ */
+const EffectBatchManager = {
+    /**
+     * The current count of active batch operations.
+     * Incremented by `startBatch()`, decremented by `endBatch()`.
+     * @member {Number} batchCount=0
+     */
+    batchCount: 0,
+    /**
+     * A Set of `Neo.core.Effect` instances that are pending execution within the current batch.
+     * @member {Set<Neo.core.Effect>} pendingEffects=new Set()
+     */
+    pendingEffects: new Set(),
+
+    /**
+     * Decrements the batch counter. If `batchCount` reaches 0, all queued effects
+     * are executed and the `pendingEffects` Set is cleared.
+     */
+    endBatch() {
+        const me = this;
+
+        me.batchCount--;
+
+        if (me.batchCount === 0) {
+            const effectsToRun = [...me.pendingEffects]; // Create a snapshot
+            me.pendingEffects.clear();
+
+            effectsToRun.forEach(effect => {
+                effect.run()
+            })
+        }
+    },
+
+    /**
+     * Checks if there is an active batch operation.
+     * @returns {Boolean}
+     */
+    isBatchActive() {
+        return this.batchCount > 0
+    },
+
+    /**
+     * Queues an effect for execution at the end of the current batch.
+     * If the effect is already queued, it will not be added again.
+     * @param {Neo.core.Effect} effect The effect to queue.
+     */
+    queueEffect(effect) {
+        this.pendingEffects.add(effect)
+    },
+
+    /**
+     * Increments the batch counter. When `batchCount` is greater than 0,
+     * effects will be queued instead of running immediately.
+     */
+    startBatch() {
+        this.batchCount++
+    }
+};
+
+export default Neo.gatekeep(EffectBatchManager, 'Neo.core.EffectBatchManager');

package/src/core/EffectManager.mjs

@@ -0,0 +1,60 @@
+/**
+ * A singleton manager to track the currently running effect.
+ * This allows reactive properties to know which effect to subscribe to.
+ * @class Neo.core.EffectManager
+ * @singleton
+ */
+const EffectManager = {
+    effectStack: [],
+    isPaused   : false,
+
+    /**
+     * 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.
+     * @param {Neo.core.Config} config The config instance to add as a dependency.
+     */
+    addDependency(config) {
+        !this.isPaused && this.getActiveEffect()?.addDependency(config)
+    },
+
+    /**
+     * Returns the effect currently at the top of the stack (i.e., the one currently running).
+     * @returns {Neo.core.Effect|null}
+     */
+    getActiveEffect() {
+        return this.effectStack[this.effectStack.length - 1]
+    },
+
+    /**
+     * Pauses dependency tracking for effects. While paused, calls to `addDependency` will be ignored.
+     */
+    pause() {
+        this.isPaused = true;
+    },
+
+    /**
+     * Pops the current effect from the stack, returning to the previous effect (if any).
+     * @returns {Neo.core.Effect|null}
+     */
+    pop() {
+        return this.effectStack.pop()
+    },
+
+    /**
+     * Pushes an effect onto the stack, marking it as the currently running effect.
+     * @param {Neo.core.Effect} effect The effect to push.
+     */
+    push(effect) {
+        this.effectStack.push(effect)
+    },
+
+    /**
+     * Resumes dependency tracking for effects.
+     */
+    resume() {
+        this.isPaused = false;
+    }
+};
+
+export default Neo.gatekeep(EffectManager, 'Neo.core.EffectManager');
+

package/src/core/IdGenerator.mjs

@@ -1,44 +1,17 @@
 /**
- * This class gets used by core.Base, so it can not extend it.
- * It could get simplified to just being an object (needs to manually get put into the Neo namespace in this case).
- * @class Neo.core.IdGenerator
- * @singleton
+ * Provides a singleton utility for generating unique IDs.
+ * @namespace Neo.core.IdGenerator
  */
-class IdGenerator {
-    static config = {
-        /**
-         * @member {String} className='Neo.core.IdGenerator'
-         * @protected
-         */
-        className: 'Neo.core.IdGenerator',
-        /**
-         * @member {String} ntype='id-generator'
-         * @protected
-         */
-        ntype: 'id-generator',
-        /**
-         * The default prefix for neo instance ids
-         * @member {String} base='neo-'
-         */
-        base: 'neo-',
-        /**
-         * @member {Boolean} singleton='true
-         * @protected
-         */
-        singleton: true
-    }
-
+const IdGenerator = {
     /**
-     * @param config
+     * The default prefix for neo instance ids
+     * @member {String} base='neo-'
      */
-    construct(config) {
-        let me = this;
-
-        me.idCounter = {};
-
-        // alias
-        Neo.getId = me.getId.bind(me);
-    }
+    base: 'neo-',
+    /**
+     * @member {Object} idCounter={}
+     */
+    idCounter: {},
 
     /**
      * @param name
@@ -55,12 +28,8 @@ class IdGenerator {
 
         return me.base + (name === 'neo' ? '' : name + '-') + count;
     }
-
-    init() {}
-
-    onAfterConstructed() {}
-
-    onConstructed() {}
 }
 
-export default Neo.setupClass(IdGenerator);
+export default Neo.gatekeep(IdGenerator, 'Neo.core.IdGenerator', () => {
+    Neo.getId = IdGenerator.getId.bind(IdGenerator);
+});

package/src/data/Model.mjs

@@ -19,10 +19,12 @@ class Model extends Base {
         ntype: 'model',
         /**
          * @member {Object[]|null} fields_=null
+         * @reactive
          */
         fields_: null,
         /**
          * @member {String} keyProperty_='id'
+         * @reactive
          */
         keyProperty_: 'id',
         /**

package/src/data/Store.mjs

@@ -7,6 +7,7 @@ import RecordFactory   from './RecordFactory.mjs';
 /**
  * @class Neo.data.Store
  * @extends Neo.collection.Base
+ * @mixes Neo.core.Observable
  */
 class Store extends Base {
     /**
@@ -42,6 +43,7 @@ class Store extends Base {
          * @example
          * api: 'MyApp.backend.UserService'
          * @member {Object|String|null} api_=null
+         * @reactive
          */
         api_: null,
         /**
@@ -50,14 +52,17 @@ class Store extends Base {
         autoLoad: false,
         /**
          * @member {Number} currentPage_=1
+         * @reactive
          */
         currentPage_: 1,
         /**
          * @member {Array|null} data_=null
+         * @reactive
          */
         data_: null,
         /**
          * @member {Array|null} initialData_=null
+         * @reactive
          */
         initialData_: null,
         /**
@@ -74,11 +79,13 @@ class Store extends Base {
         isLoading: false,
         /**
          * @member {Neo.data.Model} model_=null
+         * @reactive
          */
         model_: null,
         /**
          * Use a value of 0 to not limit the pageSize
          * @member {Number} pageSize_=0
+         * @reactive
          */
         pageSize_: 0,
         /**

package/src/data/connection/WebSocket.mjs

@@ -5,6 +5,7 @@ import Observable          from '../../core/Observable.mjs';
 /**
  * @class Neo.data.connection.WebSocket
  * @extends Neo.core.Base
+ * @mixes Neo.core.Observable
  */
 class Socket extends Base {
     /**
@@ -28,6 +29,7 @@ class Socket extends Base {
         /**
          * @member {WebSocket|null} socket_=null
          * @protected
+         * @reactive
          */
         socket_: null
     }

package/src/date/DayViewComponent.mjs

@@ -41,6 +41,7 @@ class DayViewComponent extends Base {
         /**
          * @member {Date|null} currentDate_=null
          * @protected
+         * @reactive
          */
         currentDate_: null,
         /**
@@ -51,6 +52,7 @@ class DayViewComponent extends Base {
         /**
          * 0-6 => Sun-Sat
          * @member {Number} weekStartDay_=0
+         * @reactive
          */
         weekStartDay_: 0,
         /**

package/src/date/SelectorContainer.mjs

@@ -40,6 +40,7 @@ class SelectorContainer extends Container {
          * Date object created on the value config
          * @member {Date|null} currentDate_=null
          * @protected
+         * @reactive
          */
         currentDate_: null,
         /**
@@ -50,17 +51,20 @@ class SelectorContainer extends Container {
          * The format of the column headers.
          * Valid values are: narrow, short & long
          * @member {String} dayNameFormat_='short'
+         * @reactive
          */
         dayNameFormat_: 'short',
         /**
          * @member {Intl.DateTimeFormat|null} intlFormatDay_=null
          * @protected
+         * @reactive
          */
         intlFormatDay_: null,
         /**
          * Internal flag to prevent changing the date while change animations are still running
          * @member {Boolean} isUpdating_=false
          * @protected
+         * @reactive
          */
         isUpdating_: false,
         /**
@@ -104,14 +108,17 @@ class SelectorContainer extends Container {
         keys: {},
         /**
          * @member {String} locale_=Neo.config.locale
+         * @reactive
          */
         locale_: Neo.config.locale,
         /**
          * @member {String|null} maxValue_=null
+         * @reactive
          */
         maxValue_: null,
         /**
          * @member {String|null} minValue_=null
+         * @reactive
          */
         minValue_: null,
         /**
@@ -129,24 +136,29 @@ class SelectorContainer extends Container {
         /**
          * Either pass a selection.Model module, an instance or a config object
          * @member {Object|Neo.selection.Model} selectionModel_=null
+         * @reactive
          */
         selectionModel_: null,
         /**
          * True to show inner cell & header cell borders
          * @member {Boolean} showCellBorders_=true
+         * @reactive
          */
         showCellBorders_: false,
         /**
          * True to show the days of the previous or next month (not selectable)
          * @member {Boolean} showDisabledDays_=true
+         * @reactive
          */
         showDisabledDays_: true,
         /**
          * @member {Boolean} showWeekends_=true
+         * @reactive
          */
         showWeekends_: true,
         /**
          * @member {Neo.state.Provider} stateProvider=SelectorContainerStateProvider
+         * @reactive
          */
         stateProvider: SelectorContainerStateProvider,
         /**
@@ -156,11 +168,13 @@ class SelectorContainer extends Container {
         useAnimations: true,
         /**
          * @member {String} value_=DateUtil.convertToyyyymmdd(new Date())
+         * @reactive
          */
         value_: DateUtil.convertToyyyymmdd(todayDate),
         /**
          * 0-6 => Sun-Sat
          * @member {Number} weekStartDay_=0
+         * @reactive
          */
         weekStartDay_: 0
     }

package/src/dialog/Base.mjs

@@ -35,6 +35,7 @@ class Dialog extends Panel {
         animateOnDragEnd: false,
         /**
          * @member {String|null} animateTargetId_=null
+         * @reactive
          */
         animateTargetId_: null,
         /**
@@ -68,6 +69,7 @@ class Dialog extends Panel {
         closeAction: 'close',
         /**
          * @member {Boolean} draggable_=true
+         * @reactive
          */
         draggable_: true,
         /**
@@ -102,6 +104,7 @@ class Dialog extends Panel {
         isDragging: false,
         /**
          * @member {Object} keys={Escape:'onKeyDownEscape'}
+         * @reactive
          */
         keys: {
             Escape: 'onKeyDownEscape'
@@ -112,6 +115,7 @@ class Dialog extends Panel {
         maximizeCls: 'far fa-window-maximize',
         /**
          * @member {Boolean} maximized_=false
+         * @reactive
          */
         maximized_: false,
         /**
@@ -120,10 +124,12 @@ class Dialog extends Panel {
         minimizeCls: 'far fa-window-minimize',
         /**
          * @member {Boolean} modal_=false
+         * @reactive
          */
         modal_: false,
         /**
          * @member {Boolean} resizable_=true
+         * @reactive
          */
         resizable_: true,
         /**
@@ -132,12 +138,14 @@ class Dialog extends Panel {
         resizablePluginConfig: null,
         /**
          * @member {String|null} title_=null
+         * @reactive
          */
         title_: null,
         /**
          * Set to `true` to have tabbing wrap within this Dialog.
          * Should be used with `modal`.
          * @member {Boolean} trapFocus_=false
+         * @reactive
          */
         trapFocus_: false
     }

package/src/draggable/DragZone.mjs

@@ -7,6 +7,7 @@ import VDomUtil           from '../util/VDom.mjs';
 /**
  * @class Neo.draggable.DragZone
  * @extends Neo.core.Base
+ * @mixes Neo.core.Observable
  */
 class DragZone extends Base {
     /**
@@ -42,6 +43,7 @@ class DragZone extends Base {
         /**
          * The name of the App this instance belongs to
          * @member {String|null} appName_=null
+         * @reactive
          */
         appName_: null,
         /**
@@ -85,6 +87,7 @@ class DragZone extends Base {
         dragProxy: null,
         /**
          * @member {Object|null} dragProxyConfig_=null
+         * @reactive
          */
         dragProxyConfig_: null,
         /**
@@ -135,6 +138,7 @@ class DragZone extends Base {
         owner: null,
         /**
          * @member {String} proxyParentId_='document.body'
+         * @reactive
          */
         proxyParentId_: 'document.body',
         /**
@@ -156,6 +160,7 @@ class DragZone extends Base {
         useProxyWrapper: true,
         /**
          * @member {Number|null} windowId_=null
+         * @reactive
          */
         windowId_: null
     }

package/src/draggable/tree/DragZone.mjs

@@ -27,6 +27,7 @@ class DragZone extends BaseDragZone {
         /**
          * Limit drag&drop to leaf nodes => excluding folders
          * @member {Boolean} leafNodesOnly_=true
+         * @reactive
          */
         leafNodesOnly_: false
     }

package/src/filter/BooleanContainer.mjs

@@ -23,6 +23,7 @@ class BooleanContainer extends Container {
         baseCls: ['neo-filter-booleancontainer'],
         /**
          * @member {Object} layout={ntype: 'hbox', align: 'center'}
+         * @reactive
          */
         layout: {ntype: 'hbox', align: 'center'},
         /**
@@ -32,6 +33,7 @@ class BooleanContainer extends Container {
         radioConfig: null,
         /**
          * @member {Boolean|null} value_=null
+         * @reactive
          */
         value_: null
     }