neo.mjs 10.3.4 → 10.4.0

package/.github/RELEASE_NOTES/v10.3.5md

@@ -0,0 +1,4 @@
+# Neo.mjs v10.3.4 Release Notes
+
+This patch release enhances the build-all script to only copy generated docs output into dist envs, in case the
+docs app does exist (might not be the case inside custom workspaces).

package/.github/RELEASE_NOTES/v10.4.0.md

@@ -0,0 +1,24 @@
+# Neo.mjs v10.4.0 Release Notes
+
+## Highlights
+
+This release focuses heavily on performance and robustness, especially when dealing with very large datasets in collections, stores, and grids. Key improvements include non-blocking chunked data loading for stores, a fix for stack overflow errors when adding large arrays to collections, and significant optimizations for grid scrolling and data clearing.
+
+## Enhancements
+
+### 1. High-Performance Chunking for `Store.add()`
+To prevent the UI from freezing when adding massive datasets (e.g., 1M+ records), `Store.add()` now uses a two-chunk loading strategy. It first adds a small "interactive" batch of records to make the UI responsive almost instantly. It then silently adds the remaining data in the background by leveraging the `suspendEvents` flag, and fires a final `load` event to update the UI (e.g., grid scrollbars) once complete. This ensures a non-blocking, highly responsive user experience.
+
+### 2. Refactored Grid ScrollManager for Smoother Scrolling
+The `grid.ScrollManager` has been refactored to use the framework's built-in `delayable` system instead of manual `setTimeout` logic. Both vertical and horizontal scroll event handlers are now throttled to align with a 60fps refresh rate, and a debounced `onBodyScrollEnd` handler efficiently manages the `isScrolling` state. This results in smoother scrolling, more consistent behavior, and cleaner, more maintainable code.
+
+### 3. Grid `onStoreLoad` Fast Path for Instant Clearing
+A performance "fast path" has been added to the `grid.Body` for scenarios where a store is cleared. Instead of performing a full VDOM diff between the existing rows and an empty dataset, the grid now detects this specific case and directly clears the VDOM and the real DOM. This reduces the time to clear a large grid from ~13ms to a near-instantaneous operation.
+
+## Bug Fixes
+
+### 1. Fixed `collection.Base#splice` Stack Overflow
+A `RangeError: Maximum call stack size exceeded` would occur when adding a very large number of items (e.g., >100k) to an already populated collection at runtime. This was caused by using the spread operator (`...`) on a massive array. The `splice` method now intelligently switches to a safer `concat()`-based approach for large arrays, preventing the crash while retaining the high performance of native `splice` for smaller arrays.
+
+### 2. Fixed `collection.Base#construct` Race Condition
+A race condition was fixed where methods on a collection could be called during instantiation before the collection's internal properties were initialized. The `construct` method's logic was reordered to ensure all internal properties are defined *before* the parent constructor is called, making the class more robust and preventing subtle bugs during component initialization.

package/ServiceWorker.mjs

@@ -20,9 +20,9 @@ class ServiceWorker extends ServiceBase {
          */
         singleton: true,
         /**
-         * @member {String} version='10.3.4'
+         * @member {String} version='10.4.0'
          */
-        version: '10.3.4'
+        version: '10.4.0'
     }
 
     /**

package/apps/portal/index.html

@@ -16,7 +16,7 @@
         "@type": "Organization",
         "name": "Neo.mjs"
       },
-      "datePublished": "2025-08-09",
+      "datePublished": "2025-08-11",
       "publisher": {
         "@type": "Organization",
         "name": "Neo.mjs"

package/apps/portal/view/home/FooterContainer.mjs

@@ -108,7 +108,7 @@ class FooterContainer extends Container {
             }, {
                 module: Component,
                 cls   : ['neo-version'],
-                text  : 'v10.3.4'
+                text  : 'v10.4.0'
             }]
         }],
         /**

package/buildScripts/buildAll.mjs

@@ -150,23 +150,25 @@ if (programOpts.info) {
             }
         }
 
-        if (parsedocs === 'yes' && fs.existsSync(path.join(cwd, 'docs/app'))) {
-            childProcess = spawnSync(npmCmd, ['run', 'generate-docs-json'], cpOpts);
-            childProcess.status && process.exit(childProcess.status);
-        }
+        if (fs.existsSync(path.join(cwd, 'docs/app'))) {
+            if (parsedocs === 'yes') {
+                childProcess = spawnSync(npmCmd, ['run', 'generate-docs-json'], cpOpts);
+                childProcess.status && process.exit(childProcess.status);
+            }
 
-        if (parsedocs === 'yes' && (env === 'all' || env === 'dev')) {
-            childProcess = spawnSync('node', [`${neoPath}/buildScripts/copyFolder.mjs -s ${path.resolve(cwd, 'docs/output')   } -t ${path.resolve(cwd, 'dist/development/docs/output')}`],    cpOpts);
-            childProcess.status && process.exit(childProcess.status);
-            childProcess = spawnSync('node', [`${neoPath}/buildScripts/copyFolder.mjs -s ${path.resolve(cwd, 'docs/resources')} -t ${path.resolve(cwd, 'dist/development/docs/resources')}`], cpOpts);
-            childProcess.status && process.exit(childProcess.status);
-        }
+            if (parsedocs === 'yes' && (env === 'all' || env === 'dev')) {
+                childProcess = spawnSync('node', [`${neoPath}/buildScripts/copyFolder.mjs -s ${path.resolve(cwd, 'docs/output')   } -t ${path.resolve(cwd, 'dist/development/docs/output')}`],    cpOpts);
+                childProcess.status && process.exit(childProcess.status);
+                childProcess = spawnSync('node', [`${neoPath}/buildScripts/copyFolder.mjs -s ${path.resolve(cwd, 'docs/resources')} -t ${path.resolve(cwd, 'dist/development/docs/resources')}`], cpOpts);
+                childProcess.status && process.exit(childProcess.status);
+            }
 
-        if (parsedocs === 'yes' && (env === 'all' || env === 'prod')) {
-            childProcess = spawnSync('node', [`${neoPath}/buildScripts/copyFolder.mjs -s ${path.resolve(cwd, 'docs/output')   } -t ${path.resolve(cwd, 'dist/production/docs/output')}`],    cpOpts);
-            childProcess.status && process.exit(childProcess.status);
-            childProcess = spawnSync('node', [`${neoPath}/buildScripts/copyFolder.mjs -s ${path.resolve(cwd, 'docs/resources')} -t ${path.resolve(cwd, 'dist/production/docs/resources')}`], cpOpts);
-            childProcess.status && process.exit(childProcess.status);
+            if (parsedocs === 'yes' && (env === 'all' || env === 'prod')) {
+                childProcess = spawnSync('node', [`${neoPath}/buildScripts/copyFolder.mjs -s ${path.resolve(cwd, 'docs/output')   } -t ${path.resolve(cwd, 'dist/production/docs/output')}`],    cpOpts);
+                childProcess.status && process.exit(childProcess.status);
+                childProcess = spawnSync('node', [`${neoPath}/buildScripts/copyFolder.mjs -s ${path.resolve(cwd, 'docs/resources')} -t ${path.resolve(cwd, 'dist/production/docs/resources')}`], cpOpts);
+                childProcess.status && process.exit(childProcess.status);
+            }
         }
 
         const processTime = (Math.round((new Date - startDate) * 100) / 100000).toFixed(2);

package/examples/grid/bigData/ControlsContainer.mjs

@@ -264,9 +264,7 @@ class ControlsContainer extends Container {
             filter: me.updateRowsLabel,
             load  : me.updateRowsLabel,
             scope : me
-        });
-
-        store.getCount() > 0 && me.updateRowsLabel()
+        })
     }
 
     /**

package/examples/grid/bigData/MainStore.mjs

@@ -24,6 +24,7 @@ class MainStore extends Store {
         amountRows_: 1000,
         /**
          * @member {Object[]} filters
+         * @reactive
          */
         filters: [{
             property: 'firstname',
@@ -75,7 +76,11 @@ class MainStore extends Store {
 
             console.log('Start creating records');
 
-            me.data = data;
+            if (me.items?.length > 0) {
+                me.clear()
+            }
+
+            me.add(data);
 
             console.log(`Record creation total time: ${Math.round(performance.now() - start)}ms`)
         }
@@ -94,7 +99,11 @@ class MainStore extends Store {
 
         console.log('Start creating records');
 
-        me.data = data;
+        if (me.items?.length > 0) {
+            me.clear()
+        }
+
+        me.add(data);
 
         console.log(`Record creation total time: ${Math.round(performance.now() - start)}ms`)
     }

package/learn/guides/datahandling/Grids.md

@@ -53,7 +53,7 @@ MainView = Neo.setupClass(MainView);
 
 In this example, we create a simple grid with two columns. The `dataField` in each column configuration maps to a
 field in the store's model. You can further customize the grid's behavior and appearance
-by providing `bodyConfig` and `headerToolbarConfig`.
+by providing `body` and `headerToolbarConfig`.
 
 ## Integrating with Stores
 
@@ -556,11 +556,11 @@ const myGrid = Neo.create(GridContainer, {
 
 ### Animated Row Sorting
 
-To animate row sorting, set the `animatedRowSorting` config to `true` on the `Neo.grid.Body` (via `bodyConfig`).
+To animate row sorting, set the `animatedRowSorting` config to `true` on the `Neo.grid.Body` (via `body`).
 
 ```javascript readonly
 const myGrid = Neo.create(GridContainer, {
-    bodyConfig: {
+    body: {
         animatedRowSorting: true
     },
     // ...
@@ -569,7 +569,7 @@ const myGrid = Neo.create(GridContainer, {
 
 ## Selection Models
 
-The grid's selection behavior is controlled by a selection model, which you can configure on the `bodyConfig`.
+The grid's selection behavior is controlled by a selection model, which you can configure on the `body`.
 
 Available selection models in `Neo.selection.grid`:
 - `RowModel`: Selects entire rows.
@@ -582,7 +582,7 @@ import {RowModel} from '../../../src/selection/grid/_export.mjs';
 
 const myGrid = Neo.create(GridContainer, {
     // ...
-    bodyConfig: {
+    body: {
         selectionModel: RowModel
     }
 });
@@ -597,12 +597,12 @@ reducing memory consumption and improving rendering speed.
 You### Optimizing Virtual Rendering
 
 You can fine-tune the virtual rendering behavior with the `bufferRowRange` and `bufferColumnRange` configs in the
-`bodyConfig`. These settings define how many extra rows and columns to render outside the visible area to provide a
+`body`. These settings define how many extra rows and columns to render outside the visible area to provide a
 smoother scrolling experience.
 
 ```javascript readonly
 const myGrid = Neo.create(GridContainer, {
-    bodyConfig: {
+    body: {
         bufferRowRange   : 5, // Render 5 extra rows above and below the visible area
         bufferColumnRange: 2  // Render 2 extra columns to the left and right of the visible area
     },

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "neo.mjs",
-    "version": "10.3.4",
+    "version": "10.4.0",
     "description": "Neo.mjs: The multi-threaded UI framework for building ultra-fast, desktop-like web applications with uncompromised responsiveness, inherent security, and a transpilation-free dev mode.",
     "type": "module",
     "repository": {
@@ -89,17 +89,17 @@
         "cssnano": "^7.1.0",
         "envinfo": "^7.14.0",
         "esbuild": "^0.25.8",
-        "fs-extra": "^11.3.0",
+        "fs-extra": "^11.3.1",
         "highlightjs-line-numbers.js": "^2.9.0",
         "html-minifier-terser": "^7.2.0",
-        "inquirer": "^12.9.0",
+        "inquirer": "^12.9.1",
         "marked": "^16.1.2",
         "monaco-editor": "0.50.0",
         "neo-jsdoc": "1.0.1",
         "neo-jsdoc-x": "1.0.5",
         "parse5": "^8.0.0",
         "postcss": "^8.5.6",
-        "sass": "^1.89.2",
+        "sass": "^1.90.0",
         "siesta-lite": "5.5.2",
         "terser": "^5.43.1",
         "url": "^0.11.4",

package/src/DefaultConfig.mjs

@@ -299,12 +299,12 @@ const DefaultConfig = {
     useVdomWorker: true,
     /**
      * buildScripts/injectPackageVersion.mjs will update this value
-     * @default '10.3.4'
+     * @default '10.4.0'
      * @memberOf! module:Neo
      * @name config.version
      * @type String
      */
-    version: '10.3.4'
+    version: '10.4.0'
 };
 
 Object.assign(DefaultConfig, {

package/src/collection/Base.mjs

@@ -120,13 +120,9 @@ class Collection extends Base {
      * @param config
      */
     construct(config) {
-        super.construct(config);
-
         let me           = this,
             symbolConfig = {enumerable: false, writable: true};
 
-        me.items = me.items || [];
-
         Object.defineProperties(me, {
             [countMutations]  : {...symbolConfig, value: false},
             [isFiltered]      : {...symbolConfig, value: false},
@@ -137,6 +133,10 @@ class Collection extends Base {
             [updatingIndex]   : {...symbolConfig, value: 0}
         });
 
+        super.construct(config);
+
+        me.items = me.items || [];
+
         if (me.autoSort && me._sorters.length > 0) {
             me.doSort()
         }
@@ -1237,11 +1237,20 @@ class Collection extends Base {
             }
 
             if (addedItems.length > 0) {
-                if (items.length === 0) {
+                if (!items || items.length === 0) {
                     // Performance improvement for Safari, see: https://github.com/neomjs/neo/issues/6228
                     me._items = addedItems
                 } else {
-                    items.splice(Neo.isNumber(index) ? index : items.length, 0, ...addedItems)
+                    const finalIndex = Neo.isNumber(index) ? index : items.length;
+
+                    if (addedItems.length > 5000) {
+                        // Manually splice for large arrays to avoid a stack overflow
+                        const beginning = items.slice(0, finalIndex);
+                        const end       = items.slice(finalIndex);
+                        me._items       = beginning.concat(addedItems, end);
+                    } else {
+                        items.splice(finalIndex, 0, ...addedItems)
+                    }
                 }
 
                 if (me.autoSort && me._sorters.length > 0) {

package/src/data/Store.mjs

@@ -139,6 +139,31 @@ class Store extends Base {
      * @returns {Number} the collection count
      */
     add(item) {
+        let items = Array.isArray(item) ? item : [item];
+        const threshold = 1000;
+
+        if (items.length > threshold) {
+            const me    = this,
+                  chunk = items.splice(0, threshold);
+
+            // 1. Add the first chunk. This fires 'mutate' -> 'load' and triggers the initial grid render.
+            super.add(me.createRecord(chunk));
+
+            // 2. Suspend events to prevent the next 'add' from firing 'load'.
+            me.suspendEvents = true;
+
+            // 3. Add the rest of the items silently.
+            super.add(me.createRecord(items));
+
+            // 4. Resume events.
+            me.suspendEvents = false;
+
+            // 5. Manually fire a final 'load' event to update the grid's scrollbar.
+            me.fire('load', me.items);
+
+            return me.count
+        }
+
         return super.add(this.createRecord(item))
     }
 

package/src/grid/Body.mjs

@@ -938,6 +938,31 @@ class GridBody extends Component {
     onStoreLoad(data) {
         let me = this;
 
+        /*
+         * Fast path to handle clearing all rows (e.g., store.removeAll()).
+         * A full vdom diff against all existing rows is a performance bottleneck.
+         * This logic bypasses the standard update() cycle by directly clearing the vdom,
+         * vnode cache and the real DOM via textContent.
+         */
+        if (data?.length < 1) {
+            const vdomRoot = me.getVdomRoot();
+
+            // No change, opt out
+            if (vdomRoot.cn.length < 1) {
+                return
+            }
+
+            vdomRoot.cn = [];
+            me.getVnodeRoot().childNodes = [];
+
+            Neo.applyDeltas(me.appName, {
+                id         : vdomRoot.id,
+                textContent: ''
+            });
+
+            return
+        }
+
         me.createViewData();
 
         if (me.mounted) {

package/src/grid/ScrollManager.mjs

@@ -5,6 +5,17 @@ import Base from '../core/Base.mjs';
  * @extends Neo.core.Base
  */
 class ScrollManager extends Base {
+    /**
+     * @member {Object} delayable
+     * @protected
+     * @static
+     */
+    static delayable = {
+        onBodyScroll     : {type: 'throttle', timer:  16},
+        onBodyScrollEnd  : {type: 'buffer',   timer: 150},
+        onContainerScroll: {type: 'throttle', timer:  16}
+    }
+
     static config = {
         /**
          * @member {String} className='Neo.grid.ScrollManager'
@@ -47,11 +58,6 @@ class ScrollManager extends Base {
      * @protected
      */
     lastTouchY = 0
-    /**
-     * @member {Number|null}} scrollTimeoutId=null
-     * @protected
-     */
-    scrollTimeoutId = null
     /**
      * Flag for identifying the ownership of a touchmove operation
      * @member {'body'|'container'|null} touchMoveOwner=null
@@ -92,14 +98,10 @@ class ScrollManager extends Base {
 
         me.scrollTop = scrollTop;
 
-        me.scrollTimeoutId && clearTimeout(me.scrollTimeoutId);
-
-        me.scrollTimeoutId = setTimeout(() => {
-            body.isScrolling = false
-        }, 100);
-
         body.set({isScrolling: true, scrollTop});
 
+        me.onBodyScrollEnd();
+
         if (touches) {
             if (me.touchMoveOwner !== 'container') {
                 me.touchMoveOwner = 'body'
@@ -120,6 +122,13 @@ class ScrollManager extends Base {
         }
     }
 
+    /**
+     * @protected
+     */
+    onBodyScrollEnd() {
+        this.gridBody.isScrolling = false
+    }
+
     /**
      * @param {Object} data
      * @param {Number} data.scrollLeft
@@ -133,6 +142,9 @@ class ScrollManager extends Base {
 
         // We must ignore events for grid-scrollbar
         if (target.id.includes('grid-container')) {
+            body.isScrolling = true;
+            me.onBodyScrollEnd();
+
             me  .scrollLeft = scrollLeft;
             body.scrollLeft = scrollLeft;