neo.mjs 10.0.0-beta.5 → 10.0.0

package/src/layout/VBox.mjs

@@ -19,6 +19,7 @@ class VBox extends Flexbox {
         /**
          * @member {String} direction='column'
          * @protected
+         * @reactive
          */
         direction: 'column'
     }

package/src/list/Base.mjs

@@ -22,6 +22,7 @@ class List extends Component {
         ntype: 'list',
         /**
          * @member {Boolean} animate_=false
+         * @reactive
          */
         animate_: false,
         /**
@@ -41,6 +42,7 @@ class List extends Component {
         disabledField: 'disabled',
         /**
          * @member {Boolean} disableSelection_=false
+         * @reactive
          */
         disableSelection_: false,
         /**
@@ -49,6 +51,7 @@ class List extends Component {
         displayField: 'name',
         /**
          * @member {Boolean} draggable_=false
+         * @reactive
          */
         draggable_: false,
         /**
@@ -63,12 +66,14 @@ class List extends Component {
          * Keeps track of the focussed item index and allows bindings and programmatic changes.
          * You can either pass the index or the related record
          * @member {Number|Object|null} focusIndex_=null
+         * @reactive
          */
         focusIndex_: null,
         /**
          * In case we are using list item headers and want to bind list item indexes to e.g. a card layout
          * for e.g. a sidenav, this config comes in handy.
          * @member {Number|null} headerlessSelectedIndex_=null
+         * @reactive
          */
         headerlessSelectedIndex_: null,
         /**
@@ -82,6 +87,7 @@ class List extends Component {
         /**
          * Defaults to px
          * @member {Number|null} itemHeight_=null
+         * @reactive
          */
         itemHeight_: null,
         /**
@@ -92,6 +98,7 @@ class List extends Component {
         /**
          * Defaults to px
          * @member {Number|null} itemWidth_=null
+         * @reactive
          */
         itemWidth_: null,
         /**
@@ -117,11 +124,13 @@ class List extends Component {
         /**
          * Keeps track of the selected item index and allows bindings and programmatic changes
          * @member {Number|null} selectedIndex_=null
+         * @reactive
          */
         selectedIndex_: null,
         /**
          * Either pass a selection.Model module, an instance or a config object
          * @member {Object|Neo.selection.Model} selectionModel_=null
+         * @reactive
          */
         selectionModel_: null,
         /**
@@ -136,21 +145,25 @@ class List extends Component {
         silentSelect: false,
         /**
          * @member {Neo.data.Store|null} store_=null
+         * @reactive
          */
         store_: null,
         /**
          * True will add a checkbox in front of each list item
          * @member {Boolean} stacked_=true
+         * @reactive
          */
         useCheckBoxes_: false,
         /**
          * Setting this config to true will switch to dl, dt & dd tags instead of using ul & li.
          * Use the {Boolean} model field isHeader.
          * @member {Boolean} useHeaders_=false
+         * @reactive
          */
         useHeaders_: false,
         /**
          * @member {Boolean} useWrapperNode_=false
+         * @reactive
          */
         useWrapperNode_: false,
         /**

package/src/list/Chip.mjs

@@ -41,6 +41,7 @@ class Chip extends ComponentList {
         /**
          * True will flex each list item horizontally
          * @member {Boolean} stacked_=true
+         * @reactive
          */
         stacked_: true,
         /**

package/src/list/Circle.mjs

@@ -30,11 +30,13 @@ class Circle extends ComponentList {
         /**
          * Defaults to px
          * @member {Number|null} itemHeight=300
+         * @reactive
          */
         itemHeight: 300,
         /**
          * Defaults to px
          * @member {Number|null} itemWidth=300
+         * @reactive
          */
         itemWidth: 300,
         /**

package/src/list/Color.mjs

@@ -23,6 +23,7 @@ class Color extends List {
         /**
          * The data.Model field which contains the color value
          * @member {String} colorField_='name'
+         * @reactive
          */
         colorField_: 'name',
         /**

package/src/list/plugin/Animate.mjs

@@ -47,12 +47,14 @@ class Animate extends Base {
         /**
          * Time in ms. Please ensure to match the CSS based value, in case you change the default.
          * @member {Number} transitionDuration_=500
+         * @reactive
          */
         transitionDuration_: 500,
         /**
          * The easing used for fadeIn, fadeOut and position changes.
          * Valid values: 'ease','ease-in','ease-out','ease-in-out','linear'
          * @member {String} transitionEasing_='ease-in-out'
+         * @reactive
          */
         transitionEasing_: 'ease-in-out',
         /**

package/src/main/DeltaUpdates.mjs

@@ -41,6 +41,7 @@ class DeltaUpdates extends Base {
         /**
          * @member {Boolean} renderCountDeltas_=false
          * @protected
+         * @reactive
          */
         renderCountDeltas_: false,
         /**

package/src/main/DomEvents.mjs

@@ -70,6 +70,8 @@ const
 /**
  * @class Neo.main.DomEvents
  * @extends Neo.core.Base
+ * @mixes Neo.core.Observable
+ * @mixes Neo.main.mixin.TouchDomEvents
  * @singleton
  */
 class DomEvents extends Base {

package/src/main/addon/CloneNode.mjs

@@ -23,6 +23,7 @@ class CloneNode extends Base {
          * Remote method access for other workers
          * @member {Object} remote={app: [//...]}
          * @protected
+         * @reactive
          */
         remote: {
             app: [

package/src/main/addon/Cookie.mjs

@@ -16,6 +16,7 @@ class Cookie extends Base {
          * Remote method access for other workers
          * @member {Object} remote={app: [//...]}
          * @protected
+         * @reactive
          */
         remote: {
             app: [

package/src/main/addon/GoogleMaps.mjs

@@ -6,6 +6,7 @@ import Observable from '../../core/Observable.mjs';
 /**
  * @class Neo.main.addon.GoogleMaps
  * @extends Neo.main.addon.Base
+ * @mixes Neo.core.Observable
  */
 class GoogleMaps extends Base {
     /**

package/src/main/addon/LocalStorage.mjs

@@ -16,6 +16,7 @@ class LocalStorage extends Base {
          * Remote method access for other workers
          * @member {Object} remote={app: [//...]}
          * @protected
+         * @reactive
          */
         remote: {
             app: [

package/src/main/addon/MapboxGL.mjs

@@ -71,6 +71,7 @@ class MapboxGL extends Base {
         /**
          * @member {Boolean} scriptsLoaded_=true
          * @protected
+         * @reactive
          */
         scriptsLoaded_: false,
         /**

package/src/main/addon/Markdown.mjs

@@ -20,6 +20,7 @@ class Markdown extends Base {
          * Remote method access for other workers
          * @member {Object} remote={app: [//...]}
          * @protected
+         * @reactive
          */
         remote: {
             app: [

package/src/main/addon/Navigator.mjs

@@ -26,6 +26,7 @@ class Navigator extends Base {
          * Remote method access for other workers
          * @member {Object} remote={app: [//...]}
          * @protected
+         * @reactive
          */
         remote: {
             app: [

package/src/main/addon/Popover.mjs

@@ -17,6 +17,7 @@ class Popover extends Base {
          * Remote method access for other workers
          * @member {Object} remote={app: [//...]}
          * @protected
+         * @reactive
          */
         remote: {
             app: [

package/src/main/addon/Stylesheet.mjs

@@ -23,6 +23,7 @@ class Stylesheet extends Base {
          * Remote method access for other workers
          * @member {Object} remote={app: [//...]}
          * @protected
+         * @reactive
          */
         remote: {
             app: [

package/src/main/addon/WindowPosition.mjs

@@ -25,6 +25,7 @@ class WindowPosition extends Base {
         intervalTime: 20,
         /**
          * @member {Boolean} observeResize_=false
+         * @reactive
          */
         observeResize_: false,
         /**

package/src/manager/Component.mjs

@@ -394,77 +394,6 @@ class Component extends Manager {
         return parents
     }
 
-    /**
-     * Copies a given vdom tree and replaces child component references with the vdom of their matching components
-     * @param {Object} vdom
-     * @param {Number} depth=-1
-     *     The component replacement depth.
-     *     -1 will parse the full tree, 1 top level only, 2 include children, 3 include grandchildren
-     * @returns {Object}
-     */
-    getVdomTree(vdom, depth=-1) {
-        let output = {...vdom}, // shallow copy
-            childDepth;
-
-        if (vdom.cn) {
-            output.cn = [];
-
-            vdom.cn.forEach(item => {
-                childDepth = depth;
-
-                if (item.componentId) {
-                    childDepth = depth === -1 ? -1 : depth > 1 ? depth-1 : 1;
-
-                    if (depth === -1 || depth > 1) {
-                        item = this.get(item.componentId).vdom
-                    }
-                }
-
-                output.cn.push(this.getVdomTree(item, childDepth))
-            })
-        }
-
-        return output
-    }
-
-    /**
-     * Copies a given vnode tree and replaces child component references with the vnode of their matching components
-     * @param {Object} vnode
-     * @param {Number} depth=-1
-     *     The component replacement depth.
-     *     -1 will parse the full tree, 1 top level only, 2 include children, 3 include grandchildren
-     * @returns {Object}
-     */
-    getVnodeTree(vnode, depth=-1) {
-        let output = {...vnode}, // shallow copy
-            childDepth, component;
-
-        if (vnode.childNodes) {
-            output.childNodes = [];
-
-            vnode.childNodes.forEach(item => {
-                childDepth = depth;
-
-                if (item.componentId) {
-                    childDepth = depth === -1 ? -1 : depth > 1 ? depth-1 : 1;
-
-                    if (depth === -1 || depth > 1) {
-                        component = this.get(item.componentId);
-
-                        // keep references in case there is no vnode (cmp not mounted)
-                        if (component?.vnode) {
-                            item = component.vnode
-                        }
-                    }
-                }
-
-                output.childNodes.push(this.getVnodeTree(item, childDepth))
-            })
-        }
-
-        return output
-    }
-
     /**
      * Check if the component had a property of any value somewhere in the Prototype chain
      *

package/src/manager/VDomUpdate.mjs

@@ -0,0 +1,320 @@
+import Collection from '../collection/Base.mjs';
+
+/**
+ * The VDomUpdate manager is a singleton responsible for orchestrating and optimizing
+ * component VDOM updates within the Neo.mjs framework. It acts as a central coordinator
+ * to optimize the VDOM update process. Its primary goal is to reduce the amount of
+ * message roundtrips between the application and VDOM workers by aggregating multiple
+ * component updates into a single, optimized VDOM tree.
+ *
+ * Key Responsibilities:
+ * 1. **Update Merging & Aggregation:** Allows a parent component to absorb the update
+ *    requests of its children. Instead of each child triggering a separate VDOM update
+ *    message to the VDOM worker, the parent sends a single, aggregated VDOM tree. This
+ *    significantly reduces the overhead of worker communication and can result in smaller,
+ *    more focused data for the VDOM worker to process. While the amount of final DOM
+ *    modifications remains the same, this aggregation is key to performance.
+ *
+ * 2. **Asynchronous Flow Control:** Manages the asynchronous nature of VDOM updates, which
+ *    are often processed in a worker thread. It ensures that code awaiting an update
+ *    (e.g., via a returned Promise) is correctly notified upon completion.
+ *
+ * 3. **Dependency Chaining:** Provides a "post-update" queue, allowing one component's
+ *    update to be declaratively chained to another's, ensuring a predictable order of
+ *    operations.
+ *
+ * 4. **State Tracking:** Keeps track of updates that are "in-flight" (i.e., currently
+ *    being processed), which helps to avoid race conditions and redundant work.
+ *
+ * By centralizing these concerns, VDomUpdate plays a critical role in the framework's
+ * performance and rendering efficiency.
+ *
+ * @class Neo.manager.VDomUpdate
+ * @extends Neo.collection.Base
+ * @singleton
+ */
+class VDomUpdate extends Collection {
+    static config = {
+        /**
+         * @member {String} className='Neo.manager.VDomUpdate'
+         * @protected
+         */
+        className: 'Neo.manager.VDomUpdate',
+        /**
+         * A collection that maps a parent component's ID (`ownerId`) to the set of child
+         * components whose VDOM updates have been merged into that parent's update cycle.
+         *
+         * The structure for each entry is:
+         * `{ ownerId: 'parent-id', children: Map<'child-id', {childUpdateDepth, distance}> }`
+         *
+         * - `ownerId`: The `id` of the parent component taking responsibility for the update.
+         * - `children`: A Map where keys are the `id`s of the merged children and values
+         *   are objects containing metadata needed to calculate the total update scope.
+         *
+         * @member {Neo.collection.Base|null} mergedCallbackMap=null
+         * @protected
+         */
+        mergedCallbackMap: null,
+        /**
+         * A collection that queues components that need to be updated immediately after
+         * another component's update cycle completes. This is used to handle rendering
+         * dependencies.
+         *
+         * The structure for each entry is:
+         * `{ ownerId: 'component-id', children: [{childId, resolve}] }`
+         *
+         * - `ownerId`: The `id` of the component whose update completion will trigger the queued updates.
+         * - `children`: An array of objects, where `childId` is the component to update and
+         *   `resolve` is the Promise resolver to call after that subsequent update is done.
+         *
+         * @member {Neo.collection.Base|null} postUpdateQueueMap=null
+         * @protected
+         */
+        postUpdateQueueMap: null,
+        /**
+         * @member {Boolean} singleton=true
+         * @protected
+         */
+        singleton: true
+    }
+
+    /**
+     * A Map that tracks VDOM updates that have been dispatched to the VDOM worker but
+     * have not yet completed. This prevents redundant updates for the same component.
+     *
+     * The structure is: `Map<'component-id', updateDepth>`
+     *
+     * @member {Map|null} inFlightUpdateMap=null
+     * @protected
+     */
+    inFlightUpdateMap = null;
+    /**
+     * A Map that stores Promise `resolve` functions associated with a component's update.
+     * When a component's VDOM update is finalized, the callbacks for its ID are executed,
+     * resolving the Promise returned by the component's `update()` method.
+     *
+     * The structure is: `Map<'component-id', [callback1, callback2, ...]>`
+     *
+     * @member {Map|null} promiseCallbackMap=null
+     * @protected
+     */
+    promiseCallbackMap = null;
+
+    /**
+     * Initializes the manager's internal collections and maps.
+     * This is called automatically when the singleton instance is created.
+     * @param {Object} config
+     */
+    construct(config) {
+        super.construct(config);
+
+        const me = this;
+
+        me.inFlightUpdateMap  = new Map();
+        me.mergedCallbackMap  = Neo.create(Collection, {keyProperty: 'ownerId'});
+        me.postUpdateQueueMap = Neo.create(Collection, {keyProperty: 'ownerId'});
+        me.promiseCallbackMap = new Map();
+    }
+
+    /**
+     * Registers a callback function to be executed when a specific component's
+     * VDOM update completes. This is the mechanism that resolves the Promise
+     * returned by `Component#update()`.
+     * @param {String}   ownerId  The `id` of the component owning the update.
+     * @param {Function} callback The function to execute upon completion.
+     */
+    addPromiseCallback(ownerId, callback) {
+        let me = this;
+
+        if (!me.promiseCallbackMap.has(ownerId)) {
+            me.promiseCallbackMap.set(ownerId, [])
+        }
+
+        me.promiseCallbackMap.get(ownerId).push(callback)
+    }
+
+    /**
+     * Executes all callbacks associated with a completed VDOM update for a given `ownerId`.
+     * This method first processes callbacks for any children that were merged into this
+     * update cycle, then executes the callbacks for the `ownerId` itself.
+     * @param {String} ownerId The `id` of the component whose update has just completed.
+     * @param {Object} [data]  Optional data to pass to the callbacks.
+     */
+    executeCallbacks(ownerId, data) {
+        let me           = this,
+            item         = me.mergedCallbackMap.get(ownerId),
+            callbackData = data ? [data] : [];
+
+        if (item) {
+            item.children.forEach((value, key) => {
+                me.executePromiseCallbacks(key, ...callbackData)
+            });
+            me.mergedCallbackMap.remove(item);
+        }
+
+        me.executePromiseCallbacks(ownerId, ...callbackData)
+    }
+
+    /**
+     * A helper method that invokes all registered promise callbacks for a given
+     * component ID and then clears them from the queue.
+     * @param {String} ownerId The `id` of the component.
+     * @param {Object} [data]  Optional data to pass to the callbacks.
+     */
+    executePromiseCallbacks(ownerId, data) {
+        let me        = this,
+            callbacks = me.promiseCallbackMap.get(ownerId);
+
+        callbacks?.forEach(callback => callback(data));
+        me.promiseCallbackMap.delete(ownerId);
+    }
+
+    /**
+     * Calculates the required `updateDepth` for a parent component based on its own
+     * needs and the needs of all child components whose updates have been merged into it.
+     * The final depth is the maximum required depth to ensure all changes are rendered.
+     *
+     * For example, if a parent needs to update its direct content (`updateDepth: 1`) but
+     * a merged child 3 levels down needs a full subtree update (`childUpdateDepth: -1`),
+     * this method will return -1, signaling a full recursive update from the parent.
+     *
+     * This method is called by the parent component right before it dispatches its VDOM update.
+     * @param {String} ownerId The `id` of the parent component.
+     * @returns {Number|null} The adjusted update depth, or `null` if no merged children exist.
+     */
+    getAdjustedUpdateDepth(ownerId) {
+        let me       = this,
+            owner    = Neo.getComponent(ownerId),
+            item     = me.mergedCallbackMap.get(ownerId),
+            maxDepth = owner?.updateDepth ?? 1,
+            newDepth;
+
+        if (item) {
+            item.children.forEach(value => {
+                if (value.childUpdateDepth === -1) {
+                    newDepth = -1
+                } else {
+                    // The new depth is the distance to the child plus the child's own required update depth.
+                    newDepth = value.distance + value.childUpdateDepth
+                }
+
+                if (newDepth === -1) {
+                    maxDepth = -1
+                } else if (maxDepth !== -1) {
+                    maxDepth = Math.max(maxDepth, newDepth)
+                }
+            });
+
+            return maxDepth
+        }
+
+        return null
+    }
+
+    /**
+     * Retrieves the `updateDepth` for a component's update that is currently in-flight.
+     * @param {String} ownerId The `id` of the component owning the update.
+     * @returns {Number|undefined} The update depth, or `undefined` if no update is in-flight.
+     */
+    getInFlightUpdateDepth(ownerId) {
+        return this.inFlightUpdateMap.get(ownerId)
+    }
+
+    /**
+     * Returns a Set of child component IDs that have been merged into a parent's update cycle.
+     * This is used by the parent to know which children it is responsible for updating.
+     * @param {String} ownerId The `id` of the parent component.
+     * @returns {Set<String>|null} A Set containing the IDs of the merged children, or `null`.
+     */
+    getMergedChildIds(ownerId) {
+        const item = this.mergedCallbackMap.get(ownerId);
+        if (item) {
+            return new Set(item.children.keys())
+        }
+        return null
+    }
+
+    /**
+     * Marks a component's VDOM update as "in-flight," meaning it has been sent to the
+     * worker for processing.
+     * @param {String} ownerId     The `id` of the component owning the update.
+     * @param {Number} updateDepth The depth of the in-flight update.
+     */
+    registerInFlightUpdate(ownerId, updateDepth) {
+        this.inFlightUpdateMap.set(ownerId, updateDepth)
+    }
+
+    /**
+     * Registers a child's update request to be merged into its parent's update cycle.
+     * This is called by a child component when it determines it can delegate its update
+     * to an ancestor.
+     * @param {String} ownerId          The `id` of the parent component that will own the merged update.
+     * @param {String} childId          The `id` of the child component requesting the merge.
+     * @param {Number} childUpdateDepth The update depth required by the child.
+     * @param {Number} distance         The component tree distance (number of levels) between the parent and child.
+     */
+    registerMerged(ownerId, childId, childUpdateDepth, distance) {
+        let me   = this,
+            item = me.mergedCallbackMap.get(ownerId);
+
+        if (!item) {
+            item = {ownerId, children: new Map()};
+            me.mergedCallbackMap.add(item)
+        }
+
+        item.children.set(childId, {childUpdateDepth, distance})
+    }
+
+    /**
+     * Queues a component update to be executed after another component's update is complete.
+     * @param {String} ownerId     The `id` of the component to wait for.
+     * @param {String} childId     The `id` of the component to update afterward.
+     * @param {Function} [resolve] The Promise resolver to be called when the `childId`'s subsequent update finishes.
+     */
+    registerPostUpdate(ownerId, childId, resolve) {
+        let me   = this,
+            item = me.postUpdateQueueMap.get(ownerId);
+
+        if (!item) {
+            item = {ownerId, children: []};
+            me.postUpdateQueueMap.add(item)
+        }
+
+        item.children.push({childId, resolve})
+    }
+
+    /**
+     * Triggers all pending updates that were queued to run after the specified `ownerId`'s
+     * update has completed.
+     * @param {String} ownerId The `id` of the component whose update has just finished.
+     */
+    triggerPostUpdates(ownerId) {
+        let me   = this,
+            item = me.postUpdateQueueMap.get(ownerId),
+            component;
+
+        if (item) {
+            item.children.forEach(entry => {
+                component = Neo.getComponent(entry.childId);
+
+                if (component) {
+                    entry.resolve && me.addPromiseCallback(component.id, entry.resolve);
+                    component.update()
+                }
+            });
+
+            me.postUpdateQueueMap.remove(item)
+        }
+    }
+
+    /**
+     * Removes a component's update from the "in-flight" registry. This is called after
+     * the VDOM worker confirms the update has been processed.
+     * @param {String} ownerId The `id` of the component owning the update.
+     */
+    unregisterInFlightUpdate(ownerId) {
+        this.inFlightUpdateMap.delete(ownerId)
+    }
+}
+
+export default Neo.setupClass(VDomUpdate);