gridstack 12.2.2 → 12.3.1

package/dist/gridstack.js

@@ -1,8 +1,8 @@
 /*!
- * GridStack 12.2.2
+ * GridStack 12.3.1
  * https://gridstackjs.com/
  *
- * Copyright (c) 2021-2024  Alain Dumesny
+ * Copyright (c) 2021-2025  Alain Dumesny
  * see root license https://github.com/gridstack/gridstack.js/tree/master/LICENSE
  */
 import { GridStackEngine } from './gridstack-engine';
@@ -23,6 +23,13 @@ export * from './types';
 export * from './utils';
 export * from './gridstack-engine';
 export * from './dd-gridstack';
+export * from './dd-manager';
+export * from './dd-element';
+export * from './dd-draggable';
+export * from './dd-droppable';
+export * from './dd-resizable';
+export * from './dd-resizable-handle';
+export * from './dd-base-impl';
 /**
  * Main gridstack class - you will need to call `GridStack.init()` first to initialize your grid.
  * Note: your grid elements MUST have the following classes for the CSS layout to work:
@@ -132,7 +139,10 @@ class GridStack {
     static registerEngine(engineClass) {
         GridStack.engineClass = engineClass;
     }
-    /** @internal create placeholder DIV as needed */
+    /**
+     * @internal create placeholder DIV as needed
+     * @returns the placeholder element for indicating drop zones during drag operations
+     */
     get placeholder() {
         if (!this._placeholder) {
             this._placeholder = Utils.createDiv([this.opts.placeholderClass, gridDefaults.itemClass, this.opts.itemClass]);
@@ -315,6 +325,8 @@ class GridStack {
      * @param w GridStackWidget definition. used MakeWidget(el) if you have dom element instead.
      */
     addWidget(w) {
+        if (!w)
+            return;
         if (typeof w === 'string') {
             console.error('V11: GridStack.addWidget() does not support string anymore. see #2736');
             return;
@@ -326,7 +338,7 @@ class GridStack {
         let el;
         let node = w;
         node.grid = this;
-        if (node?.el) {
+        if (node.el) {
             el = node.el; // re-use element stored in the node
         }
         else if (GridStack.addRemoveCB) {
@@ -352,7 +364,15 @@ class GridStack {
         this.makeWidget(el, w);
         return el;
     }
-    /** create the default grid item divs, and content (possibly lazy loaded) by using GridStack.renderCB() */
+    /**
+     * Create the default grid item divs and content (possibly lazy loaded) by using GridStack.renderCB().
+     *
+     * @param n GridStackNode definition containing widget configuration
+     * @returns the created HTML element with proper grid item structure
+     *
+     * @example
+     * const element = grid.createWidgetDivs({ w: 2, h: 1, content: 'Hello World' });
+     */
     createWidgetDivs(n) {
         const el = Utils.createDiv(['grid-stack-item', this.opts.itemClass]);
         const cont = Utils.createDiv(['grid-stack-item-content'], el);
@@ -448,7 +468,7 @@ class GridStack {
             subGrid._isTemp = true; // prevent re-nesting as we add over
         if (autoColumn)
             subGrid._autoColumn = true;
-        // add the original content back as a child of hte newly created grid
+        // add the original content back as a child of the newly created grid
         if (saveContent) {
             subGrid.makeWidget(newItem, newItemOpt);
         }
@@ -498,11 +518,14 @@ class GridStack {
      * @param saveGridOpt if true (default false), save the grid options itself, so you can call the new GridStack.addGrid()
      * to recreate everything from scratch. GridStackOptions.children would then contain the widget list instead.
      * @param saveCB callback for each node -> widget, so application can insert additional data to be saved into the widget data structure.
+     * @param columnSize if provided, the grid will be saved for the given column size (IFF we have matching internal saved layout, or current layout).
+     * Otherwise it will use the largest possible layout (say 12 even if rendering at 1 column) so we can restore to all layouts.
+     * Note: nested grids will ALWAYS save the container size to match overall layouts (parent + child) to be consistent.
      * @returns list of widgets or full grid option, including .children list of widgets
      */
-    save(saveContent = true, saveGridOpt = false, saveCB = GridStack.saveCB) {
+    save(saveContent = true, saveGridOpt = false, saveCB = GridStack.saveCB, columnSize) {
         // return copied GridStackWidget (with optionally .el) we can modify at will...
-        const list = this.engine.save(saveContent, saveCB);
+        const list = this.engine.save(saveContent, saveCB, columnSize);
         // check for HTML content and nested grids
         list.forEach(n => {
             if (saveContent && n.el && !n.subGrid && !saveCB) { // sub-grid are saved differently, not plain content
@@ -515,9 +538,9 @@ class GridStack {
                 if (!saveContent && !saveCB) {
                     delete n.content;
                 }
-                // check for nested grid
+                // check for nested grid - make sure it saves to the given container size to be consistent
                 if (n.subGrid?.el) {
-                    const listOrOpt = n.subGrid.save(saveContent, saveGridOpt, saveCB);
+                    const listOrOpt = n.subGrid.save(saveContent, saveGridOpt, saveCB, n.w);
                     n.subGridOpts = (saveGridOpt ? listOrOpt : { children: listOrOpt });
                     delete n.subGrid;
                 }
@@ -559,20 +582,45 @@ class GridStack {
         return list;
     }
     /**
-     * load the widgets from a list. This will call update() on each (matching by id) or add/remove widgets that are not there.
+     * Load widgets from a list. This will call update() on each (matching by id) or add/remove widgets that are not there.
+     * Used to restore a grid layout for a saved layout list (see `save()`).
      *
      * @param items list of widgets definition to update/create
      * @param addRemove boolean (default true) or callback method can be passed to control if and how missing widgets can be added/removed, giving
      * the user control of insertion.
+     * @returns the grid instance for chaining
      *
      * @example
-     * see http://gridstackjs.com/demo/serialization.html
+     * // Basic usage with saved layout
+     * const savedLayout = grid.save(); // Save current layout
+     * // ... later restore it
+     * grid.load(savedLayout);
+     *
+     * // Load with custom add/remove callback
+     * grid.load(layout, (items, grid, add) => {
+     *   if (add) {
+     *     // Custom logic for adding new widgets
+     *     items.forEach(item => {
+     *       const el = document.createElement('div');
+     *       el.innerHTML = item.content || '';
+     *       grid.addWidget(el, item);
+     *     });
+     *   } else {
+     *     // Custom logic for removing widgets
+     *     items.forEach(item => grid.removeWidget(item.el));
+     *   }
+     * });
+     *
+     * // Load without adding/removing missing widgets
+     * grid.load(layout, false);
+     *
+     * @see {@link http://gridstackjs.com/demo/serialization.html} for complete example
      */
     load(items, addRemove = GridStack.addRemoveCB || true) {
         items = Utils.cloneDeep(items); // so we can mod
         const column = this.getColumn();
         // make sure size 1x1 (default) is present as it may need to override current sizes
-        items.forEach(n => { n.w = n.w || 1; n.h = n.h || 1; });
+        items.forEach(n => { n.w = n.w || n.minW || 1; n.h = n.h || n.minH || 1; });
         // sort items. those without coord will be appended last
         items = Utils.sort(items);
         this.engine.skipCacheUpdate = this._ignoreLayoutsNodeChange = true; // skip layout update
@@ -688,7 +736,17 @@ class GridStack {
         return this;
     }
     /**
-     * Gets current cell height.
+     * Gets the current cell height in pixels. This takes into account the unit type and converts to pixels if necessary.
+     *
+     * @param forcePixel if true, forces conversion to pixels even when cellHeight is specified in other units
+     * @returns the cell height in pixels
+     *
+     * @example
+     * const height = grid.getCellHeight();
+     * console.log('Cell height:', height, 'px');
+     *
+     * // Force pixel conversion
+     * const pixelHeight = grid.getCellHeight(true);
      */
     getCellHeight(forcePixel = false) {
         if (this.opts.cellHeight && this.opts.cellHeight !== 'auto' &&
@@ -720,17 +778,21 @@ class GridStack {
         return rows ? Math.round(this.el.getBoundingClientRect().height / rows) : this.opts.cellHeight;
     }
     /**
-     * Update current cell height - see `GridStackOptions.cellHeight` for format.
-     * This method rebuilds an internal CSS style sheet.
-     * Note: You can expect performance issues if call this method too often.
+     * Update current cell height - see `GridStackOptions.cellHeight` for format by updating eh Browser CSS variable.
      *
-     * @param val the cell height. If not passed (undefined), cells content will be made square (match width minus margin),
-     * if pass 0 the CSS will be generated by the application instead.
+     * @param val the cell height. Options:
+     *   - `undefined`: cells content will be made square (match width minus margin)
+     *   - `0`: the CSS will be generated by the application instead
+     *   - number: height in pixels
+     *   - string: height with units (e.g., '70px', '5rem', '2em')
+     * @returns the grid instance for chaining
      *
      * @example
-     * grid.cellHeight(100); // same as 100px
-     * grid.cellHeight('70px');
-     * grid.cellHeight(grid.cellWidth() * 1.2);
+     * grid.cellHeight(100);     // 100px height
+     * grid.cellHeight('70px');  // explicit pixel height
+     * grid.cellHeight('5rem');  // relative to root font size
+     * grid.cellHeight(grid.cellWidth() * 1.2); // aspect ratio
+     * grid.cellHeight('auto');  // auto-size based on content
      */
     cellHeight(val) {
         // if not called internally, check if we're changing mode
@@ -762,6 +824,18 @@ class GridStack {
         return this;
     }
     /** Gets current cell width. */
+    /**
+     * Gets the current cell width in pixels. This is calculated based on the grid container width divided by the number of columns.
+     *
+     * @returns the cell width in pixels
+     *
+     * @example
+     * const width = grid.cellWidth();
+     * console.log('Cell width:', width, 'px');
+     *
+     * // Use cell width to calculate widget dimensions
+     * const widgetWidth = width * 3; // For a 3-column wide widget
+     */
     cellWidth() {
         return this._widthOrContainer() / this.getColumn();
     }
@@ -798,11 +872,25 @@ class GridStack {
         return false;
     }
     /**
-     * re-layout grid items to reclaim any empty space. Options are:
-     * 'list' keep the widget left->right order the same, even if that means leaving an empty slot if things don't fit
-     * 'compact' might re-order items to fill any empty space
+     * Re-layout grid items to reclaim any empty space. This is useful after removing widgets
+     * or when you want to optimize the layout.
+     *
+     * @param layout layout type. Options:
+     *   - 'compact' (default): might re-order items to fill any empty space
+     *   - 'list': keep the widget left->right order the same, even if that means leaving an empty slot if things don't fit
+     * @param doSort re-sort items first based on x,y position. Set to false to do your own sorting ahead (default: true)
+     * @returns the grid instance for chaining
+     *
+     * @example
+     * // Compact layout after removing widgets
+     * grid.removeWidget('.widget-to-remove');
+     * grid.compact();
+     *
+     * // Use list layout (preserve order)
+     * grid.compact('list');
      *
-     * doSort - 'false' to let you do your own sorting ahead in case you need to control a different order. (default to sort)
+     * // Compact without sorting first
+     * grid.compact('compact', false);
      */
     compact(layout = 'compact', doSort = true) {
         this.engine.compact(layout, doSort);
@@ -810,11 +898,32 @@ class GridStack {
         return this;
     }
     /**
-     * set the number of columns in the grid. Will update existing widgets to conform to new number of columns,
+     * Set the number of columns in the grid. Will update existing widgets to conform to new number of columns,
      * as well as cache the original layout so you can revert back to previous positions without loss.
-     * @param column - Integer > 0 (default 12).
-     * @param layout specify the type of re-layout that will happen (position, size, etc...).
-     * Note: items will never be outside of the current column boundaries. default ('moveScale'). Ignored for 1 column
+     *
+     * Requires `gridstack-extra.css` or `gridstack-extra.min.css` for [2-11] columns,
+     * else you will need to generate correct CSS.
+     * See: https://github.com/gridstack/gridstack.js#change-grid-columns
+     *
+     * @param column Integer > 0 (default 12)
+     * @param layout specify the type of re-layout that will happen. Options:
+     *   - 'moveScale' (default): scale widget positions and sizes
+     *   - 'move': keep widget sizes, only move positions
+     *   - 'scale': keep widget positions, only scale sizes
+     *   - 'none': don't change widget positions or sizes
+     *   Note: items will never be outside of the current column boundaries.
+     *   Ignored for `column=1` as we always want to vertically stack.
+     * @returns the grid instance for chaining
+     *
+     * @example
+     * // Change to 6 columns with default scaling
+     * grid.column(6);
+     *
+     * // Change to 4 columns, only move positions
+     * grid.column(4, 'move');
+     *
+     * // Single column layout (vertical stack)
+     * grid.column(1);
      */
     column(column, layout = 'moveScale') {
         if (!column || column < 1 || this.opts.column === column)
@@ -841,15 +950,42 @@ class GridStack {
         return this;
     }
     /**
-     * get the number of columns in the grid (default 12)
+     * Get the number of columns in the grid (default 12).
+     *
+     * @returns the current number of columns in the grid
+     *
+     * @example
+     * const columnCount = grid.getColumn(); // returns 12 by default
      */
     getColumn() { return this.opts.column; }
-    /** returns an array of grid HTML elements (no placeholder) - used to iterate through our children in DOM order */
+    /**
+     * Returns an array of grid HTML elements (no placeholder) - used to iterate through our children in DOM order.
+     * This method excludes placeholder elements and returns only actual grid items.
+     *
+     * @returns array of GridItemHTMLElement instances representing all grid items
+     *
+     * @example
+     * const items = grid.getGridItems();
+     * items.forEach(item => {
+     *   console.log('Item ID:', item.gridstackNode.id);
+     * });
+     */
     getGridItems() {
         return Array.from(this.el.children)
             .filter((el) => el.matches('.' + this.opts.itemClass) && !el.matches('.' + this.opts.placeholderClass));
     }
-    /** true if changeCB should be ignored due to column change, sizeToContent, loading, etc... which caller can ignore for dirty flag case */
+    /**
+     * Returns true if change callbacks should be ignored due to column change, sizeToContent, loading, etc.
+     * This is useful for callers who want to implement dirty flag functionality.
+     *
+     * @returns true if change callbacks are currently being ignored
+     *
+     * @example
+     * if (!grid.isIgnoreChangeCB()) {
+     *   // Process the change event
+     *   console.log('Grid layout changed');
+     * }
+     */
     isIgnoreChangeCB() { return this._ignoreLayoutsNodeChange; }
     /**
      * Destroys a grid instance. DO NOT CALL any methods or access any vars after this as it will free up members.
@@ -881,7 +1017,15 @@ class GridStack {
         return this;
     }
     /**
-     * enable/disable floating widgets (default: `false`) See [example](http://gridstackjs.com/demo/float.html)
+     * Enable/disable floating widgets (default: `false`). When enabled, widgets can float up to fill empty spaces.
+     * See [example](http://gridstackjs.com/demo/float.html)
+     *
+     * @param val true to enable floating, false to disable
+     * @returns the grid instance for chaining
+     *
+     * @example
+     * grid.float(true);  // Enable floating
+     * grid.float(false); // Disable floating (default)
      */
     float(val) {
         if (this.opts.float !== val) {
@@ -891,7 +1035,13 @@ class GridStack {
         return this;
     }
     /**
-     * get the current float mode
+     * Get the current float mode setting.
+     *
+     * @returns true if floating is enabled, false otherwise
+     *
+     * @example
+     * const isFloating = grid.getFloat();
+     * console.log('Floating enabled:', isFloating);
      */
     getFloat() {
         return this.engine.float;
@@ -923,16 +1073,33 @@ class GridStack {
         const rowHeight = (box.height / parseInt(this.el.getAttribute('gs-current-row')));
         return { x: Math.floor(relativeLeft / columnWidth), y: Math.floor(relativeTop / rowHeight) };
     }
-    /** returns the current number of rows, which will be at least `minRow` if set */
+    /**
+     * Returns the current number of rows, which will be at least `minRow` if set.
+     * The row count is based on the highest positioned widget in the grid.
+     *
+     * @returns the current number of rows in the grid
+     *
+     * @example
+     * const rowCount = grid.getRow();
+     * console.log('Grid has', rowCount, 'rows');
+     */
     getRow() {
         return Math.max(this.engine.getRow(), this.opts.minRow || 0);
     }
     /**
-     * Checks if specified area is empty.
-     * @param x the position x.
-     * @param y the position y.
-     * @param w the width of to check
-     * @param h the height of to check
+     * Checks if the specified rectangular area is empty (no widgets 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 widget overlaps
+     *
+     * @example
+     * // Check if a 2x2 area at position (1,1) is empty
+     * if (grid.isAreaEmpty(1, 1, 2, 2)) {
+     *   console.log('Area is available for placement');
+     * }
      */
     isAreaEmpty(x, y, w, h) {
         return this.engine.isAreaEmpty(x, y, w, h);
@@ -941,14 +1108,25 @@ class GridStack {
      * If you add elements to your grid by hand (or have some framework creating DOM), you have to tell gridstack afterwards to make them widgets.
      * If you want gridstack to add the elements for you, use `addWidget()` instead.
      * Makes the given element a widget and returns it.
+     *
      * @param els widget or single selector to convert.
      * @param options widget definition to use instead of reading attributes or using default sizing values
+     * @returns the converted GridItemHTMLElement
      *
      * @example
      * const grid = GridStack.init();
-     * grid.el.innerHtml = '<div id="1" gs-w="3"></div><div id="2"></div>';
-     * grid.makeWidget('1');
-     * grid.makeWidget('2', {w:2, content: 'hello'});
+     *
+     * // Create HTML content manually, possibly looking like:
+     * // <div id="item-1" gs-x="0" gs-y="0" gs-w="3" gs-h="2"></div>
+     * grid.el.innerHTML = '<div id="item-1" gs-w="3"></div><div id="item-2"></div>';
+     *
+     * // Convert existing elements to widgets
+     * grid.makeWidget('#item-1'); // Uses gs-* attributes from DOM
+     * grid.makeWidget('#item-2', {w: 2, h: 1, content: 'Hello World'});
+     *
+     * // Or pass DOM element directly
+     * const element = document.getElementById('item-3');
+     * grid.makeWidget(element, {x: 0, y: 1, w: 4, h: 2});
      */
     makeWidget(els, options) {
         const el = GridStack.getElement(els);
@@ -1025,7 +1203,14 @@ class GridStack {
         delete this._gsEventHandler[name];
         return this;
     }
-    /** remove all event handlers */
+    /**
+     * Remove all event handlers from the grid. This is useful for cleanup when destroying a grid.
+     *
+     * @returns the grid instance for chaining
+     *
+     * @example
+     * grid.offAll(); // Remove all event listeners
+     */
     offAll() {
         Object.keys(this._gsEventHandler).forEach((key) => this.off(key));
         return this;
@@ -1196,9 +1381,30 @@ class GridStack {
         return this;
     }
     /**
-     * Updates widget position/size and other info. Note: if you need to call this on all nodes, use load() instead which will update what changed.
-     * @param els  widget or selector of objects to modify (note: setting the same x,y for multiple items will be indeterministic and likely unwanted)
-     * @param opt new widget options (x,y,w,h, etc..). Only those set will be updated.
+     * Updates widget position/size and other info. This is used to change widget properties after creation.
+     * Can update position, size, content, and other widget properties.
+     *
+     * Note: If you need to call this on all nodes, use load() instead which will update what changed.
+     * Setting the same x,y for multiple items will be indeterministic and likely unwanted.
+     *
+     * @param els widget element(s) or selector to modify
+     * @param opt new widget options (x,y,w,h, etc.). Only those set will be updated.
+     * @returns the grid instance for chaining
+     *
+     * @example
+     * // Update widget size and position
+     * grid.update('.my-widget', { x: 2, y: 1, w: 3, h: 2 });
+     *
+     * // Update widget content
+     * grid.update(widget, { content: '<p>New content</p>' });
+     *
+     * // Update multiple properties
+     * grid.update('#my-widget', {
+     *   w: 4,
+     *   h: 3,
+     *   noResize: true,
+     *   locked: true
+     * });
      */
     update(els, opt) {
         GridStack.getElements(els).forEach(el => {
@@ -1283,10 +1489,22 @@ class GridStack {
         }
     }
     /**
-     * Updates widget height to match the content height to avoid v-scrollbar or dead space.
-     * Note: this assumes only 1 child under resizeToContentParent='.grid-stack-item-content' (sized to gridItem minus padding) that is at the entire content size wanted.
-     * @param el grid item element
-     * @param useNodeH set to true if GridStackNode.h should be used instead of actual container height when we don't need to wait for animation to finish to get actual DOM heights
+     * Updates widget height to match the content height to avoid vertical scrollbars or dead space.
+     * This automatically adjusts the widget height based on its content size.
+     *
+     * Note: This assumes only 1 child under resizeToContentParent='.grid-stack-item-content'
+     * (sized to gridItem minus padding) that represents the entire content size.
+     *
+     * @param el the grid item element to resize
+     *
+     * @example
+     * // Resize a widget to fit its content
+     * const widget = document.querySelector('.grid-stack-item');
+     * grid.resizeToContent(widget);
+     *
+     * // This is commonly used with dynamic content:
+     * widget.querySelector('.content').innerHTML = 'New longer content...';
+     * grid.resizeToContent(widget);
      */
     resizeToContent(el) {
         if (!el)
@@ -1361,9 +1579,20 @@ class GridStack {
         else
             this.resizeToContent(el);
     }
-    /** rotate (by swapping w & h) the passed in node - called when user press 'r' during dragging
-     * @param els  widget or selector of objects to modify
-     * @param relative optional pixel coord relative to upper/left corner to rotate around (will keep that cell under cursor)
+    /**
+     * Rotate widgets by swapping their width and height. This is typically called when the user presses 'r' during dragging.
+     * The rotation swaps the w/h dimensions and adjusts min/max constraints accordingly.
+     *
+     * @param els widget element(s) or selector to rotate
+     * @param relative optional pixel coordinate relative to upper/left corner to rotate around (keeps that cell under cursor)
+     * @returns the grid instance for chaining
+     *
+     * @example
+     * // Rotate a specific widget
+     * grid.rotate('.my-widget');
+     *
+     * // Rotate with relative positioning during drag
+     * grid.rotate(widget, { left: 50, top: 30 });
      */
     rotate(els, relative) {
         GridStack.getElements(els).forEach(el => {
@@ -1387,8 +1616,19 @@ class GridStack {
         return this;
     }
     /**
-     * Updates the margins which will set all 4 sides at once - see `GridStackOptions.margin` for format options (CSS string format of 1,2,4 values or single number).
-     * @param value margin value
+     * Updates the margins which will set all 4 sides at once - see `GridStackOptions.margin` for format options.
+     * Supports CSS string format of 1, 2, or 4 values or a single number.
+     *
+     * @param value margin value - can be:
+     *   - Single number: `10` (applies to all sides)
+     *   - Two values: `'10px 20px'` (top/bottom, left/right)
+     *   - Four values: `'10px 20px 5px 15px'` (top, right, bottom, left)
+     * @returns the grid instance for chaining
+     *
+     * @example
+     * grid.margin(10);           // 10px all sides
+     * grid.margin('10px 20px');  // 10px top/bottom, 20px left/right
+     * grid.margin('5px 10px 15px 20px'); // Different for each side
      */
     margin(value) {
         const isMultiValue = (typeof value === 'string' && value.split(' ').length > 1);
@@ -1404,7 +1644,20 @@ class GridStack {
         this._initMargin();
         return this;
     }
-    /** returns current margin number value (undefined if 4 sides don't match) */
+    /**
+     * Returns the current margin value as a number (undefined if the 4 sides don't match).
+     * This only returns a number if all sides have the same margin value.
+     *
+     * @returns the margin value in pixels, or undefined if sides have different values
+     *
+     * @example
+     * const margin = grid.getMargin();
+     * if (margin !== undefined) {
+     *   console.log('Uniform margin:', margin, 'px');
+     * } else {
+     *   console.log('Margins are different on different sides');
+     * }
+     */
     getMargin() { return this.opts.margin; }
     /**
      * Returns true if the height of the grid will be less than the vertical
@@ -1782,7 +2035,16 @@ class GridStack {
      * but caused loading issues in prod - see https://github.com/gridstack/gridstack.js/issues/2039
      * ===========================================================================================
      */
-    /** get the global (but static to this code) DD implementation */
+    /**
+     * Get the global drag & drop implementation instance.
+     * This provides access to the underlying drag & drop functionality.
+     *
+     * @returns the DDGridStack instance used for drag & drop operations
+     *
+     * @example
+     * const dd = GridStack.getDD();
+     * // Access drag & drop functionality
+     */
     static getDD() {
         return dd;
     }
@@ -1809,10 +2071,22 @@ class GridStack {
         });
     }
     /**
-     * Enables/Disables dragging by the user of specific grid element. If you want all items, and have it affect future items, use enableMove() instead. No-op for static grids.
-     * IF you are looking to prevent an item from moving (due to being pushed around by another during collision) use locked property instead.
-     * @param els widget or selector to modify.
-     * @param val if true widget will be draggable, assuming the parent grid isn't noMove or static.
+     * Enables/Disables dragging by the user for specific grid elements.
+     * For all items and future items, use enableMove() instead. No-op for static grids.
+     *
+     * Note: If you want to prevent an item from moving due to being pushed around by another
+     * during collision, use the 'locked' property instead.
+     *
+     * @param els widget element(s) or selector to modify
+     * @param val if true widget will be draggable, assuming the parent grid isn't noMove or static
+     * @returns the grid instance for chaining
+     *
+     * @example
+     * // Make specific widgets draggable
+     * grid.movable('.my-widget', true);
+     *
+     * // Disable dragging for specific widgets
+     * grid.movable('#fixed-widget', false);
      */
     movable(els, val) {
         if (this.opts.staticGrid)
@@ -1827,9 +2101,19 @@ class GridStack {
         return this;
     }
     /**
-     * Enables/Disables user resizing of specific grid element. If you want all items, and have it affect future items, use enableResize() instead. No-op for static grids.
-     * @param els  widget or selector to modify
-     * @param val  if true widget will be resizable, assuming the parent grid isn't noResize or static.
+     * Enables/Disables user resizing for specific grid elements.
+     * For all items and future items, use enableResize() instead. No-op for static grids.
+     *
+     * @param els widget element(s) or selector to modify
+     * @param val if true widget will be resizable, assuming the parent grid isn't noResize or static
+     * @returns the grid instance for chaining
+     *
+     * @example
+     * // Make specific widgets resizable
+     * grid.resizable('.my-widget', true);
+     *
+     * // Disable resizing for specific widgets
+     * grid.resizable('#fixed-size-widget', false);
      */
     resizable(els, val) {
         if (this.opts.staticGrid)
@@ -1846,12 +2130,24 @@ class GridStack {
     /**
      * Temporarily disables widgets moving/resizing.
      * If you want a more permanent way (which freezes up resources) use `setStatic(true)` instead.
-     * Note: no-op for static grid
+     *
+     * Note: This is a no-op for static grids.
+     *
      * This is a shortcut for:
+     * ```typescript
+     * grid.enableMove(false);
+     * grid.enableResize(false);
+     * ```
+     *
+     * @param recurse if true (default), sub-grids also get updated
+     * @returns the grid instance for chaining
+     *
      * @example
-     *  grid.enableMove(false);
-     *  grid.enableResize(false);
-     * @param recurse true (default) if sub-grids also get updated
+     * // Disable all interactions
+     * grid.disable();
+     *
+     * // Disable only this grid, not sub-grids
+     * grid.disable(false);
      */
     disable(recurse = true) {
         if (this.opts.staticGrid)
@@ -1863,12 +2159,23 @@ class GridStack {
     }
     /**
      * Re-enables widgets moving/resizing - see disable().
-     * Note: no-op for static grid.
+     * Note: This is a no-op for static grids.
+     *
      * This is a shortcut for:
+     * ```typescript
+     * grid.enableMove(true);
+     * grid.enableResize(true);
+     * ```
+     *
+     * @param recurse if true (default), sub-grids also get updated
+     * @returns the grid instance for chaining
+     *
      * @example
-     *  grid.enableMove(true);
-     *  grid.enableResize(true);
-     * @param recurse true (default) if sub-grids also get updated
+     * // Re-enable all interactions
+     * grid.enable();
+     *
+     * // Enable only this grid, not sub-grids
+     * grid.enable(false);
      */
     enable(recurse = true) {
         if (this.opts.staticGrid)
@@ -1879,8 +2186,22 @@ class GridStack {
         return this;
     }
     /**
-     * Enables/disables widget moving. No-op for static grids, and locally defined items still overrule
-     * @param recurse true (default) if sub-grids also get updated
+     * Enables/disables widget moving for all widgets. No-op for static grids.
+     * Note: locally defined items (with noMove property) still override this setting.
+     *
+     * @param doEnable if true widgets will be movable, if false moving is disabled
+     * @param recurse if true (default), sub-grids also get updated
+     * @returns the grid instance for chaining
+     *
+     * @example
+     * // Enable moving for all widgets
+     * grid.enableMove(true);
+     *
+     * // Disable moving for all widgets
+     * grid.enableMove(false);
+     *
+     * // Enable only this grid, not sub-grids
+     * grid.enableMove(true, false);
      */
     enableMove(doEnable, recurse = true) {
         if (this.opts.staticGrid)
@@ -1894,8 +2215,22 @@ class GridStack {
         return this;
     }
     /**
-     * Enables/disables widget resizing. No-op for static grids.
-     * @param recurse true (default) if sub-grids also get updated
+     * Enables/disables widget resizing for all widgets. No-op for static grids.
+     * Note: locally defined items (with noResize property) still override this setting.
+     *
+     * @param doEnable if true widgets will be resizable, if false resizing is disabled
+     * @param recurse if true (default), sub-grids also get updated
+     * @returns the grid instance for chaining
+     *
+     * @example
+     * // Enable resizing for all widgets
+     * grid.enableResize(true);
+     *
+     * // Disable resizing for all widgets
+     * grid.enableResize(false);
+     *
+     * // Enable only this grid, not sub-grids
+     * grid.enableResize(true, false);
      */
     enableResize(doEnable, recurse = true) {
         if (this.opts.staticGrid)
@@ -2290,8 +2625,7 @@ class GridStack {
                 else {
                     Utils.removePositioningStyles(target);
                     if (node._temporaryRemoved) {
-                        // got removed - restore item back to before dragging position
-                        Utils.copyPos(node, node._orig); // @ts-ignore
+                        // use last position we were at (not _orig as we may have pushed others and moved) and add it back
                         this._writePosAttr(target, node);
                         this.engine.addNode(node);
                     }
@@ -2530,6 +2864,7 @@ GridStack.resizeToContentParent = '.grid-stack-item-content';
 GridStack.Utils = Utils;
 /** scoping so users can call new GridStack.Engine(12) for example */
 GridStack.Engine = GridStackEngine;
-GridStack.GDRev = '12.2.2';
+/** @internal current version compiled in code */
+GridStack.GDRev = '12.3.1';
 export { GridStack };
 //# sourceMappingURL=gridstack.js.map