gridstack 12.2.2 → 12.3.0

package/dist/gridstack-engine.d.ts

@@ -1,6 +1,6 @@
 /**
- * gridstack-engine.ts 12.2.2
- * 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 { GridStackNode, GridStackPosition, GridStackMoveOpts, SaveFcn, CompactOptions } from './types';
 /** callback to update the DOM attributes since this class is generic (no HTML or other info) for items that changed - see _notify() */
@@ -14,10 +14,17 @@ export interface GridStackEngineOptions {
     onChange?: OnChangeCB;
 }
 /**
- * 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.
  */
 export declare class GridStackEngine {
     column: number;
@@ -30,49 +37,251 @@ export declare class GridStackEngine {
     /** true when grid.load() already cached the layout and can skip out of bound caching info */
     skipCacheUpdate?: boolean;
     constructor(opts?: GridStackEngineOptions);
+    /**
+     * 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?: boolean, doPack?: boolean): GridStackEngine;
     protected _useEntireRowArea(node: GridStackNode, nn: GridStackPosition): boolean;
-    /** 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: GridStackNode, area?: GridStackNode, skip2?: GridStackNode): GridStackNode | undefined;
+    /**
+     * 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: GridStackNode, area?: GridStackNode, skip2?: GridStackNode): GridStackNode[];
     /** does a pixel coverage collision based on where we started, returning the node that has the most coverage that is >50% mid line */
     protected directionCollideCoverage(node: GridStackNode, o: GridStackMoveOpts, collides: GridStackNode[]): GridStackNode | undefined;
-    /** does a pixel coverage returning the node that has the most coverage by area */
-    /** called to cache the nodes pixel rectangles used for collision detection during drag */
-    cacheRects(w: number, h: number, top: number, right: number, bottom: number, left: number): GridStackEngine;
-    /** 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: GridStackNode, b: GridStackNode): boolean | undefined;
+    /**
+     * 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: number, y: number, w: number, h: number): boolean;
-    /** 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?: CompactOptions, doSort?: boolean): GridStackEngine;
-    /** 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: boolean);
-    /** 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(): boolean;
-    /** 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 | -1): GridStackEngine;
     /**
-     * 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: GridStackNode, resizing?: boolean): GridStackNode;
-    /** 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: GridStackNode, resizing?: boolean): GridStackEngine;
-    /** 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?: boolean): GridStackNode[];
-    /** 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: GridStackNode, nodeList?: GridStackNode[], column?: number, after?: GridStackNode): boolean;
-    /** 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: GridStackNode, triggerAddEvent?: boolean, after?: GridStackNode): GridStackNode;
+    /**
+     * 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: GridStackNode, removeDOM?: boolean, triggerEvent?: boolean): GridStackEngine;
+    /**
+     * 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?: boolean, triggerEvent?: boolean): GridStackEngine;
-    /** 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: GridStackNode, o: GridStackMoveOpts): boolean;
     /** return true if can fit in grid height constrain only (always true if no maxRow) */
     willItFit(node: GridStackNode): boolean;