gridstack 12.2.1 → 12.3.0

package/dist/gridstack-engine.js

@@ -1,13 +1,20 @@
 /**
- * gridstack-engine.ts 12.2.1
- * Copyright (c) 2021-2024  Alain Dumesny - see GridStack root license
+ * gridstack-engine.ts 12.3.0
+ * Copyright (c) 2021-2025  Alain Dumesny - see GridStack root license
  */
 import { Utils } from './utils';
 /**
- * Defines the GridStack engine that does most no DOM grid manipulation.
- * See GridStack methods and vars for descriptions.
+ * Defines the GridStack engine that handles all grid layout calculations and node positioning.
+ * This is the core engine that performs grid manipulation without any DOM operations.
  *
- * NOTE: values should not be modified directly - call the main GridStack API instead
+ * The engine manages:
+ * - Node positioning and collision detection
+ * - Layout algorithms (compact, float, etc.)
+ * - Grid resizing and column changes
+ * - Widget movement and resizing logic
+ *
+ * NOTE: Values should not be modified directly - use the main GridStack API instead
+ * to ensure proper DOM updates and event triggers.
  */
 class GridStackEngine {
     constructor(opts = {}) {
@@ -22,6 +29,21 @@ class GridStackEngine {
         this.nodes = opts.nodes || [];
         this.onChange = opts.onChange;
     }
+    /**
+     * Enable/disable batch mode for multiple operations to optimize performance.
+     * When enabled, layout updates are deferred until batch mode is disabled.
+     *
+     * @param flag true to enable batch mode, false to disable and apply changes
+     * @param doPack if true (default), pack/compact nodes when disabling batch mode
+     * @returns the engine instance for chaining
+     *
+     * @example
+     * // Start batch mode for multiple operations
+     * engine.batchUpdate(true);
+     * engine.addNode(node1);
+     * engine.addNode(node2);
+     * engine.batchUpdate(false); // Apply all changes at once
+     */
     batchUpdate(flag = true, doPack = true) {
         if (!!this.batchMode === flag)
             return this;
@@ -101,12 +123,39 @@ class GridStackEngine {
         }
         return didMove;
     }
-    /** return the nodes that intercept the given node. Optionally a different area can be used, as well as a second node to skip */
+    /**
+     * Return the first node that intercepts/collides with the given node or area.
+     * Used for collision detection during drag and drop operations.
+     *
+     * @param skip the node to skip in collision detection (usually the node being moved)
+     * @param area the area to check for collisions (defaults to skip node's area)
+     * @param skip2 optional second node to skip in collision detection
+     * @returns the first colliding node, or undefined if no collision
+     *
+     * @example
+     * const colliding = engine.collide(draggedNode, {x: 2, y: 1, w: 2, h: 1});
+     * if (colliding) {
+     *   console.log('Would collide with:', colliding.id);
+     * }
+     */
     collide(skip, area = skip, skip2) {
         const skipId = skip._id;
         const skip2Id = skip2?._id;
         return this.nodes.find(n => n._id !== skipId && n._id !== skip2Id && Utils.isIntercepted(n, area));
     }
+    /**
+     * Return all nodes that intercept/collide with the given node or area.
+     * Similar to collide() but returns all colliding nodes instead of just the first.
+     *
+     * @param skip the node to skip in collision detection
+     * @param area the area to check for collisions (defaults to skip node's area)
+     * @param skip2 optional second node to skip in collision detection
+     * @returns array of all colliding nodes
+     *
+     * @example
+     * const allCollisions = engine.collideAll(draggedNode);
+     * console.log('Colliding with', allCollisions.length, 'nodes');
+     */
     collideAll(skip, area = skip, skip2) {
         const skipId = skip._id;
         const skip2Id = skip2?._id;
@@ -180,7 +229,20 @@ class GridStackEngine {
       return {collide, over: overMax};
     }
     */
-    /** called to cache the nodes pixel rectangles used for collision detection during drag */
+    /**
+     * Cache the pixel rectangles for all nodes used for collision detection during drag operations.
+     * This optimization converts grid coordinates to pixel coordinates for faster collision detection.
+     *
+     * @param w width of a single grid cell in pixels
+     * @param h height of a single grid cell in pixels
+     * @param top top margin/padding in pixels
+     * @param right right margin/padding in pixels
+     * @param bottom bottom margin/padding in pixels
+     * @param left left margin/padding in pixels
+     * @returns the engine instance for chaining
+     *
+     * @internal This is typically called by GridStack during resize events
+     */
     cacheRects(w, h, top, right, bottom, left) {
         this.nodes.forEach(n => n._rect = {
             y: n.y * h + top,
@@ -190,7 +252,20 @@ class GridStackEngine {
         });
         return this;
     }
-    /** called to possibly swap between 2 nodes (same size or column, not locked, touching), returning true if successful */
+    /**
+     * Attempt to swap the positions of two nodes if they meet swapping criteria.
+     * Nodes can swap if they are the same size or in the same column/row, not locked, and touching.
+     *
+     * @param a first node to swap
+     * @param b second node to swap
+     * @returns true if swap was successful, false if not possible, undefined if not applicable
+     *
+     * @example
+     * const swapped = engine.swap(nodeA, nodeB);
+     * if (swapped) {
+     *   console.log('Nodes swapped successfully');
+     * }
+     */
     swap(a, b) {
         if (!b || b.locked || !a || a.locked)
             return false;
@@ -241,11 +316,41 @@ class GridStackEngine {
         }
         return false;
     }
+    /**
+     * Check if the specified rectangular area is empty (no nodes occupy any part of it).
+     *
+     * @param x the x coordinate (column) of the area to check
+     * @param y the y coordinate (row) of the area to check
+     * @param w the width in columns of the area to check
+     * @param h the height in rows of the area to check
+     * @returns true if the area is completely empty, false if any node overlaps
+     *
+     * @example
+     * if (engine.isAreaEmpty(2, 1, 3, 2)) {
+     *   console.log('Area is available for placement');
+     * }
+     */
     isAreaEmpty(x, y, w, h) {
         const nn = { x: x || 0, y: y || 0, w: w || 1, h: h || 1 };
         return !this.collide(nn);
     }
-    /** re-layout grid items to reclaim any empty space - optionally keeping the sort order exactly the same ('list' mode) vs truly finding an empty spaces */
+    /**
+     * Re-layout grid items to reclaim any empty space.
+     * This optimizes the grid layout by moving items to fill gaps.
+     *
+     * @param layout layout algorithm to use:
+     *   - 'compact' (default): find truly empty spaces, may reorder items
+     *   - 'list': keep the sort order exactly the same, move items up sequentially
+     * @param doSort if true (default), sort nodes by position before compacting
+     * @returns the engine instance for chaining
+     *
+     * @example
+     * // Compact to fill empty spaces
+     * engine.compact();
+     *
+     * // Compact preserving item order
+     * engine.compact('list');
+     */
     compact(layout = 'compact', doSort = true) {
         if (this.nodes.length === 0)
             return this;
@@ -274,7 +379,17 @@ class GridStackEngine {
             this.batchUpdate(false);
         return this;
     }
-    /** enable/disable floating widgets (default: `false`) See [example](http://gridstackjs.com/demo/float.html) */
+    /**
+     * Enable/disable floating widgets (default: `false`).
+     * When floating is enabled, widgets can move up to fill empty spaces.
+     * See [example](http://gridstackjs.com/demo/float.html)
+     *
+     * @param val true to enable floating, false to disable
+     *
+     * @example
+     * engine.float = true;  // Enable floating
+     * engine.float = false; // Disable floating (default)
+     */
     set float(val) {
         if (this._float === val)
             return;
@@ -283,9 +398,27 @@ class GridStackEngine {
             this._packNodes()._notify();
         }
     }
-    /** float getter method */
+    /**
+     * Get the current floating mode setting.
+     *
+     * @returns true if floating is enabled, false otherwise
+     *
+     * @example
+     * const isFloating = engine.float;
+     * console.log('Floating enabled:', isFloating);
+     */
     get float() { return this._float || false; }
-    /** sort the nodes array from first to last, or reverse. Called during collision/placement to force an order */
+    /**
+     * Sort the nodes array from first to last, or reverse.
+     * This is called during collision/placement operations to enforce a specific order.
+     *
+     * @param dir sort direction: 1 for ascending (first to last), -1 for descending (last to first)
+     * @returns the engine instance for chaining
+     *
+     * @example
+     * engine.sortNodes();    // Sort ascending (default)
+     * engine.sortNodes(-1);  // Sort descending
+     */
     sortNodes(dir = 1) {
         this.nodes = Utils.sort(this.nodes, dir);
         return this;
@@ -333,9 +466,17 @@ class GridStackEngine {
         return this;
     }
     /**
-     * given a random node, makes sure it's coordinates/values are valid in the current grid
-     * @param node to adjust
-     * @param resizing if out of bound, resize down or move into the grid to fit ?
+     * Prepare and validate a node's coordinates and values for the current grid.
+     * This ensures the node has valid position, size, and properties before being added to the grid.
+     *
+     * @param node the node to prepare and validate
+     * @param resizing if true, resize the node down if it's out of bounds; if false, move it to fit
+     * @returns the prepared node with valid coordinates
+     *
+     * @example
+     * const node = { w: 3, h: 2, content: 'Hello' };
+     * const prepared = engine.prepareNode(node);
+     * console.log('Node prepared at:', prepared.x, prepared.y);
      */
     prepareNode(node, resizing) {
         node._id = node._id ?? GridStackEngine._idSeq++;
@@ -394,7 +535,19 @@ class GridStackEngine {
         this.nodeBoundFix(node, resizing);
         return node;
     }
-    /** part2 of preparing a node to fit inside our grid - checks for x,y,w from grid dimensions */
+    /**
+     * Part 2 of preparing a node to fit inside the grid - validates and fixes coordinates and dimensions.
+     * This ensures the node fits within grid boundaries and respects min/max constraints.
+     *
+     * @param node the node to validate and fix
+     * @param resizing if true, resize the node to fit; if false, move the node to fit
+     * @returns the engine instance for chaining
+     *
+     * @example
+     * // Fix a node that might be out of bounds
+     * engine.nodeBoundFix(node, true); // Resize to fit
+     * engine.nodeBoundFix(node, false); // Move to fit
+     */
     nodeBoundFix(node, resizing) {
         const before = node._orig || Utils.copyPos({}, node);
         if (node.maxW) {
@@ -413,7 +566,7 @@ class GridStackEngine {
         // remember it's position & width so we can restore back (1 -> 12 column) #1655 #1985
         // IFF we're not in the middle of column resizing!
         const saveOrig = (node.x || 0) + (node.w || 1) > this.column;
-        if (saveOrig && this.column < this.defaultColumn && !this._inColumnResize && !this.skipCacheUpdate && node._id && this.findCacheLayout(node, this.defaultColumn) === -1) {
+        if (saveOrig && this.column < this.defaultColumn && !this._inColumnResize && !this.skipCacheUpdate && node._id != null && this.findCacheLayout(node, this.defaultColumn) === -1) {
             const copy = { ...node }; // need _id + positions
             if (copy.autoPosition || copy.x === undefined) {
                 delete copy.x;
@@ -463,7 +616,20 @@ class GridStackEngine {
         }
         return this;
     }
-    /** returns a list of modified nodes from their original values */
+    /**
+     * Returns a list of nodes that have been modified from their original values.
+     * This is used to track which nodes need DOM updates.
+     *
+     * @param verify if true, performs additional verification by comparing current vs original positions
+     * @returns array of nodes that have been modified
+     *
+     * @example
+     * const changed = engine.getDirtyNodes();
+     * console.log('Modified nodes:', changed.length);
+     *
+     * // Get verified dirty nodes
+     * const verified = engine.getDirtyNodes(true);
+     */
     getDirtyNodes(verify) {
         // compare original x,y,w,h instead as _dirty can be a temporary state
         if (verify) {
@@ -479,7 +645,14 @@ class GridStackEngine {
         this.onChange(dirtyNodes);
         return this;
     }
-    /** @internal remove dirty and last tried info */
+    /**
+     * Clean all dirty and last tried information from nodes.
+     * This resets the dirty state tracking for all nodes.
+     *
+     * @returns the engine instance for chaining
+     *
+     * @internal
+     */
     cleanNodes() {
         if (this.batchMode)
             return this;
@@ -489,9 +662,16 @@ class GridStackEngine {
         });
         return this;
     }
-    /** @internal called to save initial position/size to track real dirty state.
-     * Note: should be called right after we call change event (so next API is can detect changes)
-     * as well as right before we start move/resize/enter (so we can restore items to prev values) */
+    /**
+     * Save the initial position/size of all nodes to track real dirty state.
+     * This creates a snapshot of current positions that can be restored later.
+     *
+     * Note: Should be called right after change events and before move/resize operations.
+     *
+     * @returns the engine instance for chaining
+     *
+     * @internal
+     */
     saveInitial() {
         this.nodes.forEach(n => {
             n._orig = Utils.copyPos({}, n);
@@ -500,7 +680,14 @@ class GridStackEngine {
         this._hasLocked = this.nodes.some(n => n.locked);
         return this;
     }
-    /** @internal restore all the nodes back to initial values (called when we leave) */
+    /**
+     * Restore all nodes back to their initial values.
+     * This is typically called when canceling an operation (e.g., Esc key during drag).
+     *
+     * @returns the engine instance for chaining
+     *
+     * @internal
+     */
     restoreInitial() {
         this.nodes.forEach(n => {
             if (!n._orig || Utils.samePos(n, n._orig))
@@ -511,9 +698,21 @@ class GridStackEngine {
         this._notify();
         return this;
     }
-    /** find the first available empty spot for the given node width/height, updating the x,y attributes. return true if found.
-     * optionally you can pass your own existing node list and column count, otherwise defaults to that engine data.
-     * Optionally pass a widget to start search AFTER, meaning the order will remain the same but possibly have empty slots we skipped
+    /**
+     * Find the first available empty spot for the given node dimensions.
+     * Updates the node's x,y attributes with the found position.
+     *
+     * @param node the node to find a position for (w,h must be set)
+     * @param nodeList optional list of nodes to check against (defaults to engine nodes)
+     * @param column optional column count (defaults to engine column count)
+     * @param after optional node to start search after (maintains order)
+     * @returns true if an empty position was found and node was updated
+     *
+     * @example
+     * const node = { w: 2, h: 1 };
+     * if (engine.findEmptyPosition(node)) {
+     *   console.log('Found position at:', node.x, node.y);
+     * }
      */
     findEmptyPosition(node, nodeList = this.nodes, column = this.column, after) {
         const start = after ? after.y * column + (after.x + after.w) : 0;
@@ -536,7 +735,19 @@ class GridStackEngine {
         }
         return found;
     }
-    /** call to add the given node to our list, fixing collision and re-packing */
+    /**
+     * Add the given node to the grid, handling collision detection and re-packing.
+     * This is the main method for adding new widgets to the engine.
+     *
+     * @param node the node to add to the grid
+     * @param triggerAddEvent if true, adds node to addedNodes list for event triggering
+     * @param after optional node to place this node after (for ordering)
+     * @returns the added node (or existing node if duplicate)
+     *
+     * @example
+     * const node = { x: 0, y: 0, w: 2, h: 1, content: 'Hello' };
+     * const added = engine.addNode(node, true);
+     */
     addNode(node, triggerAddEvent = false, after) {
         const dup = this.nodes.find(n => n._id === node._id);
         if (dup)
@@ -561,6 +772,17 @@ class GridStackEngine {
         }
         return node;
     }
+    /**
+     * Remove the given node from the grid.
+     *
+     * @param node the node to remove
+     * @param removeDOM if true (default), marks node for DOM removal
+     * @param triggerEvent if true, adds node to removedNodes list for event triggering
+     * @returns the engine instance for chaining
+     *
+     * @example
+     * engine.removeNode(node, true, true);
+     */
     removeNode(node, removeDOM = true, triggerEvent = false) {
         if (!this.nodes.find(n => n._id === node._id)) {
             // TEST console.log(`Error: GridStackEngine.removeNode() node._id=${node._id} not found!`)
@@ -578,6 +800,16 @@ class GridStackEngine {
         this._notify([node]);
         return this;
     }
+    /**
+     * Remove all nodes from the grid.
+     *
+     * @param removeDOM if true (default), marks all nodes for DOM removal
+     * @param triggerEvent if true (default), triggers removal events
+     * @returns the engine instance for chaining
+     *
+     * @example
+     * engine.removeAll(); // Remove all nodes
+     */
     removeAll(removeDOM = true, triggerEvent = true) {
         delete this._layouts;
         if (!this.nodes.length)
@@ -588,9 +820,23 @@ class GridStackEngine {
         this.nodes = [];
         return this._notify(removedNodes);
     }
-    /** checks if item can be moved (layout constrain) vs moveNode(), returning true if was able to move.
-     * In more complicated cases (maxRow) it will attempt at moving the item and fixing
-     * others in a clone first, then apply those changes if still within specs. */
+    /**
+     * Check if a node can be moved to a new position, considering layout constraints.
+     * This is a safer version of moveNode() that validates the move first.
+     *
+     * For complex cases (like maxRow constraints), it simulates the move in a clone first,
+     * then applies the changes only if they meet all specifications.
+     *
+     * @param node the node to move
+     * @param o move options including target position
+     * @returns true if the node was successfully moved
+     *
+     * @example
+     * const canMove = engine.moveNodeCheck(node, { x: 2, y: 1 });
+     * if (canMove) {
+     *   console.log('Node moved successfully');
+     * }
+     */
     moveNodeCheck(node, o) {
         // if (node.locked) return false;
         if (!this.changedPosConstrain(node, o))