diff --git a/docs/api/index.md b/docs/api/index.md index d71a080e9..6c192fc73 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -90,7 +90,7 @@ Note: your grid elements MUST have the following classes for the CSS layout to w new GridStack(el, opts): GridStack; ``` -Defined in: [gridstack.ts:263](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L263) +Defined in: [gridstack.ts:266](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L266) Construct a grid item from the given element and options @@ -113,7 +113,7 @@ Construct a grid item from the given element and options protected _updateResizeEvent(forceRemove): GridStack; ``` -Defined in: [gridstack.ts:1829](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L1829) +Defined in: [gridstack.ts:2034](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L2034) add or remove the grid element size event handler @@ -133,7 +133,7 @@ add or remove the grid element size event handler protected _widthOrContainer(forBreakpoint): number; ``` -Defined in: [gridstack.ts:887](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L887) +Defined in: [gridstack.ts:924](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L924) return our expected width (or parent) , and optionally of window for dynamic column check @@ -176,7 +176,7 @@ JSON serialized data, including options. addWidget(w): GridItemHTMLElement; ``` -Defined in: [gridstack.ts:429](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L429) +Defined in: [gridstack.ts:432](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L432) add a new widget and returns it. @@ -207,7 +207,7 @@ grid.addWidget({w: 3, content: 'hello'}); batchUpdate(flag): GridStack; ``` -Defined in: [gridstack.ts:792](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L792) +Defined in: [gridstack.ts:803](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L803) use before calling a bunch of `addWidget()` to prevent un-necessary relayouts in between (more efficient) and get a single event callback. You will see no changes until `batchUpdate(false)` is called. @@ -228,28 +228,30 @@ and get a single event callback. You will see no changes until `batchUpdate(fals cellHeight(val?): GridStack; ``` -Defined in: [gridstack.ts:849](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L849) +Defined in: [gridstack.ts:874](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L874) -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. ###### Parameters | Parameter | Type | Description | | ------ | ------ | ------ | -| `val?` | [`numberOrString`](#numberorstring) | 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. | +| `val?` | [`numberOrString`](#numberorstring) | 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 [`GridStack`](#gridstack-1) +the grid instance for chaining + ###### Example ```ts -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 ``` ##### cellWidth() @@ -258,21 +260,33 @@ grid.cellHeight(grid.cellWidth() * 1.2); cellWidth(): number; ``` -Defined in: [gridstack.ts:883](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L883) +Defined in: [gridstack.ts:920](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L920) -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 `number` +the cell width in pixels + +###### Example + +```ts +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 +``` + ##### checkDynamicColumn() ```ts protected checkDynamicColumn(): boolean; ``` -Defined in: [gridstack.ts:893](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L893) +Defined in: [gridstack.ts:930](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L930) checks for dynamic column count for our current size, returning true if changed @@ -286,29 +300,48 @@ checks for dynamic column count for our current size, returning true if changed column(column, layout): GridStack; ``` -Defined in: [gridstack.ts:937](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L937) +Defined in: [gridstack.ts:1009](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L1009) -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. +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 + ###### Parameters | Parameter | Type | Default value | Description | | ------ | ------ | ------ | ------ | -| `column` | `number` | `undefined` | Integer > 0 (default 12). | -| `layout` | [`ColumnOptions`](#columnoptions) | `'moveScale'` | 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 | +| `column` | `number` | `undefined` | Integer > 0 (default 12) | +| `layout` | [`ColumnOptions`](#columnoptions) | `'moveScale'` | 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 [`GridStack`](#gridstack-1) +the grid instance for chaining + +###### Example + +```ts +// 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); +``` + ##### commit() ```ts commit(): GridStack; ``` -Defined in: [gridstack.ts:2676](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L2676) +Defined in: [gridstack.ts:2963](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L2963) ###### Returns @@ -320,52 +353,73 @@ Defined in: [gridstack.ts:2676](https://github.com/adumesny/gridstack.js/blob/ma compact(layout, doSort): GridStack; ``` -Defined in: [gridstack.ts:924](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L924) - -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 +Defined in: [gridstack.ts:975](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L975) -doSort - 'false' to let you do your own sorting ahead in case you need to control a different order. (default to sort) +Re-layout grid items to reclaim any empty space. This is useful after removing widgets +or when you want to optimize the layout. ###### Parameters -| Parameter | Type | Default value | -| ------ | ------ | ------ | -| `layout` | [`CompactOptions`](#compactoptions) | `'compact'` | -| `doSort` | `boolean` | `true` | +| Parameter | Type | Default value | Description | +| ------ | ------ | ------ | ------ | +| `layout` | [`CompactOptions`](#compactoptions) | `'compact'` | 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 | +| `doSort` | `boolean` | `true` | re-sort items first based on x,y position. Set to false to do your own sorting ahead (default: true) | ###### Returns [`GridStack`](#gridstack-1) +the grid instance for chaining + +###### Example + +```ts +// Compact layout after removing widgets +grid.removeWidget('.widget-to-remove'); +grid.compact(); + +// Use list layout (preserve order) +grid.compact('list'); + +// Compact without sorting first +grid.compact('compact', false); +``` + ##### createWidgetDivs() ```ts createWidgetDivs(n): HTMLElement; ``` -Defined in: [gridstack.ts:467](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L467) +Defined in: [gridstack.ts:478](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L478) -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(). ###### Parameters -| Parameter | Type | -| ------ | ------ | -| `n` | [`GridStackNode`](#gridstacknode-2) | +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `n` | [`GridStackNode`](#gridstacknode-2) | GridStackNode definition containing widget configuration | ###### Returns `HTMLElement` +the created HTML element with proper grid item structure + +###### Example + +```ts +const element = grid.createWidgetDivs({ w: 2, h: 1, content: 'Hello World' }); +``` + ##### destroy() ```ts destroy(removeDOM): GridStack; ``` -Defined in: [gridstack.ts:984](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L984) +Defined in: [gridstack.ts:1083](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L1083) Destroys a grid instance. DO NOT CALL any methods or access any vars after this as it will free up members. @@ -385,28 +439,39 @@ Destroys a grid instance. DO NOT CALL any methods or access any vars after this disable(recurse): GridStack; ``` -Defined in: [gridstack.ts:1987](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L1987) +Defined in: [gridstack.ts:2235](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L2235) 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 -This is a shortcut for: +If you want a more permanent way (which freezes up resources) use `setStatic(true)` instead. + +Note: This is a no-op for static grids. + +This is a shortcut for: +```typescript +grid.enableMove(false); +grid.enableResize(false); +``` ###### Parameters | Parameter | Type | Default value | Description | | ------ | ------ | ------ | ------ | -| `recurse` | `boolean` | `true` | true (default) if sub-grids also get updated | +| `recurse` | `boolean` | `true` | if true (default), sub-grids also get updated | ###### Returns [`GridStack`](#gridstack-1) +the grid instance for chaining + ###### Example ```ts -grid.enableMove(false); - grid.enableResize(false); +// Disable all interactions +grid.disable(); + +// Disable only this grid, not sub-grids +grid.disable(false); ``` ##### enable() @@ -415,27 +480,37 @@ grid.enableMove(false); enable(recurse): GridStack; ``` -Defined in: [gridstack.ts:2003](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L2003) +Defined in: [gridstack.ts:2262](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L2262) Re-enables widgets moving/resizing - see disable(). -Note: no-op for static grid. -This is a shortcut for: +Note: This is a no-op for static grids. + +This is a shortcut for: +```typescript +grid.enableMove(true); +grid.enableResize(true); +``` ###### Parameters | Parameter | Type | Default value | Description | | ------ | ------ | ------ | ------ | -| `recurse` | `boolean` | `true` | true (default) if sub-grids also get updated | +| `recurse` | `boolean` | `true` | if true (default), sub-grids also get updated | ###### Returns [`GridStack`](#gridstack-1) +the grid instance for chaining + ###### Example ```ts -grid.enableMove(true); - grid.enableResize(true); +// Re-enable all interactions +grid.enable(); + +// Enable only this grid, not sub-grids +grid.enable(false); ``` ##### enableMove() @@ -444,69 +519,111 @@ grid.enableMove(true); enableMove(doEnable, recurse): GridStack; ``` -Defined in: [gridstack.ts:2015](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L2015) +Defined in: [gridstack.ts:2288](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L2288) -Enables/disables widget moving. No-op for static grids, and locally defined items still overrule +Enables/disables widget moving for all widgets. No-op for static grids. +Note: locally defined items (with noMove property) still override this setting. ###### Parameters | Parameter | Type | Default value | Description | | ------ | ------ | ------ | ------ | -| `doEnable` | `boolean` | `undefined` | - | -| `recurse` | `boolean` | `true` | true (default) if sub-grids also get updated | +| `doEnable` | `boolean` | `undefined` | if true widgets will be movable, if false moving is disabled | +| `recurse` | `boolean` | `true` | if true (default), sub-grids also get updated | ###### Returns [`GridStack`](#gridstack-1) +the grid instance for chaining + +###### Example + +```ts +// 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); +``` + ##### enableResize() ```ts enableResize(doEnable, recurse): GridStack; ``` -Defined in: [gridstack.ts:2029](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L2029) +Defined in: [gridstack.ts:2316](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L2316) -Enables/disables widget resizing. No-op for static grids. +Enables/disables widget resizing for all widgets. No-op for static grids. +Note: locally defined items (with noResize property) still override this setting. ###### Parameters | Parameter | Type | Default value | Description | | ------ | ------ | ------ | ------ | -| `doEnable` | `boolean` | `undefined` | - | -| `recurse` | `boolean` | `true` | true (default) if sub-grids also get updated | +| `doEnable` | `boolean` | `undefined` | if true widgets will be resizable, if false resizing is disabled | +| `recurse` | `boolean` | `true` | if true (default), sub-grids also get updated | ###### Returns [`GridStack`](#gridstack-1) +the grid instance for chaining + +###### Example + +```ts +// 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); +``` + ##### float() ```ts float(val): GridStack; ``` -Defined in: [gridstack.ts:1010](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L1010) +Defined in: [gridstack.ts:1117](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L1117) -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) ###### Parameters -| Parameter | Type | -| ------ | ------ | -| `val` | `boolean` | +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `val` | `boolean` | true to enable floating, false to disable | ###### Returns [`GridStack`](#gridstack-1) +the grid instance for chaining + +###### Example + +```ts +grid.float(true); // Enable floating +grid.float(false); // Disable floating (default) +``` + ##### getCellFromPixel() ```ts getCellFromPixel(position, useDocRelative): CellPosition; ``` -Defined in: [gridstack.ts:1034](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L1034) +Defined in: [gridstack.ts:1147](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L1147) Get the position of the cell under a pixel on screen. @@ -527,104 +644,179 @@ Get the position of the cell under a pixel on screen. getCellHeight(forcePixel): number; ``` -Defined in: [gridstack.ts:806](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L806) +Defined in: [gridstack.ts:827](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L827) -Gets current cell height. +Gets the current cell height in pixels. This takes into account the unit type and converts to pixels if necessary. ###### Parameters -| Parameter | Type | Default value | -| ------ | ------ | ------ | -| `forcePixel` | `boolean` | `false` | +| Parameter | Type | Default value | Description | +| ------ | ------ | ------ | ------ | +| `forcePixel` | `boolean` | `false` | if true, forces conversion to pixels even when cellHeight is specified in other units | ###### Returns `number` +the cell height in pixels + +###### Example + +```ts +const height = grid.getCellHeight(); +console.log('Cell height:', height, 'px'); + +// Force pixel conversion +const pixelHeight = grid.getCellHeight(true); +``` + ##### getColumn() ```ts getColumn(): number; ``` -Defined in: [gridstack.ts:969](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L969) +Defined in: [gridstack.ts:1046](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L1046) -get the number of columns in the grid (default 12) +Get the number of columns in the grid (default 12). ###### Returns `number` +the current number of columns in the grid + +###### Example + +```ts +const columnCount = grid.getColumn(); // returns 12 by default +``` + ##### getDD() ```ts static getDD(): DDGridStack; ``` -Defined in: [gridstack.ts:1918](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L1918) +Defined in: [gridstack.ts:2132](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L2132) -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 [`DDGridStack`](#ddgridstack) +the DDGridStack instance used for drag & drop operations + +###### Example + +```ts +const dd = GridStack.getDD(); +// Access drag & drop functionality +``` + ##### getFloat() ```ts getFloat(): boolean; ``` -Defined in: [gridstack.ts:1021](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L1021) +Defined in: [gridstack.ts:1134](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L1134) -get the current float mode +Get the current float mode setting. ###### Returns `boolean` +true if floating is enabled, false otherwise + +###### Example + +```ts +const isFloating = grid.getFloat(); +console.log('Floating enabled:', isFloating); +``` + ##### getGridItems() ```ts getGridItems(): GridItemHTMLElement[]; ``` -Defined in: [gridstack.ts:972](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L972) +Defined in: [gridstack.ts:1060](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L1060) -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 [`GridItemHTMLElement`](#griditemhtmlelement)[] +array of GridItemHTMLElement instances representing all grid items + +###### Example + +```ts +const items = grid.getGridItems(); +items.forEach(item => { + console.log('Item ID:', item.gridstackNode.id); +}); +``` + ##### getMargin() ```ts getMargin(): number; ``` -Defined in: [gridstack.ts:1526](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L1526) +Defined in: [gridstack.ts:1731](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L1731) -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 `number` +the margin value in pixels, or undefined if sides have different values + +###### Example + +```ts +const margin = grid.getMargin(); +if (margin !== undefined) { + console.log('Uniform margin:', margin, 'px'); +} else { + console.log('Margins are different on different sides'); +} +``` + ##### getRow() ```ts getRow(): number; ``` -Defined in: [gridstack.ts:1055](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L1055) +Defined in: [gridstack.ts:1177](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L1177) -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 `number` +the current number of rows in the grid + +###### Example + +```ts +const rowCount = grid.getRow(); +console.log('Grid has', rowCount, 'rows'); +``` + ##### init() ```ts @@ -695,44 +887,67 @@ isAreaEmpty( h): boolean; ``` -Defined in: [gridstack.ts:1066](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L1066) +Defined in: [gridstack.ts:1196](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L1196) -Checks if specified area is empty. +Checks if the specified rectangular area is empty (no widgets occupy any part of it). ###### Parameters | Parameter | Type | Description | | ------ | ------ | ------ | -| `x` | `number` | the position x. | -| `y` | `number` | the position y. | -| `w` | `number` | the width of to check | -| `h` | `number` | the height of to check | +| `x` | `number` | the x coordinate (column) of the area to check | +| `y` | `number` | the y coordinate (row) of the area to check | +| `w` | `number` | the width in columns of the area to check | +| `h` | `number` | the height in rows of the area to check | ###### Returns `boolean` +true if the area is completely empty, false if any widget overlaps + +###### Example + +```ts +// 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'); +} +``` + ##### isIgnoreChangeCB() ```ts isIgnoreChangeCB(): boolean; ``` -Defined in: [gridstack.ts:978](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L978) +Defined in: [gridstack.ts:1077](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L1077) -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 `boolean` +true if change callbacks are currently being ignored + +###### Example + +```ts +if (!grid.isIgnoreChangeCB()) { + // Process the change event + console.log('Grid layout changed'); +} +``` + ##### load() ```ts load(items, addRemove): GridStack; ``` -Defined in: [gridstack.ts:681](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L681) +Defined in: [gridstack.ts:692](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L692) load the widgets from a list. This will call update() on each (matching by id) or add/remove widgets that are not there. @@ -763,7 +978,7 @@ makeSubGrid( saveContent?): GridStack; ``` -Defined in: [gridstack.ts:495](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L495) +Defined in: [gridstack.ts:506](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L506) Convert an existing gridItem element into a sub-grid with the given (optional) options, else inherit them from the parent's subGrid options. @@ -789,7 +1004,7 @@ newly created grid makeWidget(els, options?): GridItemHTMLElement; ``` -Defined in: [gridstack.ts:1083](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L1083) +Defined in: [gridstack.ts:1213](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L1213) 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. @@ -821,49 +1036,75 @@ grid.makeWidget('2', {w:2, content: 'hello'}); margin(value): GridStack; ``` -Defined in: [gridstack.ts:1510](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L1510) +Defined in: [gridstack.ts:1702](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L1702) -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). +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. ###### Parameters | Parameter | Type | Description | | ------ | ------ | ------ | -| `value` | [`numberOrString`](#numberorstring) | margin value | +| `value` | [`numberOrString`](#numberorstring) | 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 [`GridStack`](#gridstack-1) +the grid instance for chaining + +###### Example + +```ts +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 +``` + ##### movable() ```ts movable(els, val): GridStack; ``` -Defined in: [gridstack.ts:1950](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L1950) +Defined in: [gridstack.ts:2176](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L2176) + +Enables/Disables dragging by the user for specific grid elements. +For all items and future items, use enableMove() instead. No-op for static grids. -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. +Note: If you want to prevent an item from moving due to being pushed around by another +during collision, use the 'locked' property instead. ###### Parameters | Parameter | Type | Description | | ------ | ------ | ------ | -| `els` | [`GridStackElement`](#gridstackelement) | widget or selector to modify. | -| `val` | `boolean` | if true widget will be draggable, assuming the parent grid isn't noMove or static. | +| `els` | [`GridStackElement`](#gridstackelement) | widget element(s) or selector to modify | +| `val` | `boolean` | if true widget will be draggable, assuming the parent grid isn't noMove or static | ###### Returns [`GridStack`](#gridstack-1) +the grid instance for chaining + +###### Example + +```ts +// Make specific widgets draggable +grid.movable('.my-widget', true); + +// Disable dragging for specific widgets +grid.movable('#fixed-widget', false); +``` + ##### off() ```ts off(name): GridStack; ``` -Defined in: [gridstack.ts:1163](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L1163) +Defined in: [gridstack.ts:1293](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L1293) unsubscribe from the 'on' event GridStackEvent @@ -883,14 +1124,22 @@ unsubscribe from the 'on' event GridStackEvent offAll(): GridStack; ``` -Defined in: [gridstack.ts:1183](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L1183) +Defined in: [gridstack.ts:1320](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L1320) -remove all event handlers +Remove all event handlers from the grid. This is useful for cleanup when destroying a grid. ###### Returns [`GridStack`](#gridstack-1) +the grid instance for chaining + +###### Example + +```ts +grid.offAll(); // Remove all event listeners +``` + ##### on() ###### Call Signature @@ -899,7 +1148,7 @@ remove all event handlers on(name, callback): GridStack; ``` -Defined in: [gridstack.ts:1126](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L1126) +Defined in: [gridstack.ts:1256](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L1256) Event handler that extracts our CustomEvent data out automatically for receiving custom notifications (see doc for supported events) @@ -932,7 +1181,7 @@ grid.el.addEventListener('added', function(event) { log('added ', event.detail)} on(name, callback): GridStack; ``` -Defined in: [gridstack.ts:1127](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L1127) +Defined in: [gridstack.ts:1257](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L1257) Event handler that extracts our CustomEvent data out automatically for receiving custom notifications (see doc for supported events) @@ -965,7 +1214,7 @@ grid.el.addEventListener('added', function(event) { log('added ', event.detail)} on(name, callback): GridStack; ``` -Defined in: [gridstack.ts:1128](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L1128) +Defined in: [gridstack.ts:1258](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L1258) Event handler that extracts our CustomEvent data out automatically for receiving custom notifications (see doc for supported events) @@ -998,7 +1247,7 @@ grid.el.addEventListener('added', function(event) { log('added ', event.detail)} on(name, callback): GridStack; ``` -Defined in: [gridstack.ts:1129](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L1129) +Defined in: [gridstack.ts:1259](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L1259) Event handler that extracts our CustomEvent data out automatically for receiving custom notifications (see doc for supported events) @@ -1031,7 +1280,7 @@ grid.el.addEventListener('added', function(event) { log('added ', event.detail)} on(name, callback): GridStack; ``` -Defined in: [gridstack.ts:1130](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L1130) +Defined in: [gridstack.ts:1260](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L1260) Event handler that extracts our CustomEvent data out automatically for receiving custom notifications (see doc for supported events) @@ -1064,7 +1313,7 @@ grid.el.addEventListener('added', function(event) { log('added ', event.detail)} onResize(clientWidth): GridStack; ``` -Defined in: [gridstack.ts:1768](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L1768) +Defined in: [gridstack.ts:1973](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L1973) called when we are being resized - check if the one Column Mode needs to be turned on/off and remember the prev columns we used, or get our count from parent, as well as check for cellHeight==='auto' (square) @@ -1086,7 +1335,7 @@ or `sizeToContent` gridItem options. prepareDragDrop(el, force?): GridStack; ``` -Defined in: [gridstack.ts:2372](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L2372) +Defined in: [gridstack.ts:2659](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L2659) prepares the element for drag&drop - this is normally called by makeWidget() unless are are delay loading @@ -1129,7 +1378,7 @@ replace just one instance. removeAll(removeDOM, triggerEvent): GridStack; ``` -Defined in: [gridstack.ts:1232](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L1232) +Defined in: [gridstack.ts:1369](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L1369) Removes all widgets from the grid. @@ -1150,7 +1399,7 @@ Removes all widgets from the grid. removeAsSubGrid(nodeThatRemoved?): void; ``` -Defined in: [gridstack.ts:588](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L588) +Defined in: [gridstack.ts:599](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L599) called when an item was converted into a nested grid to accommodate a dragged over item, but then item leaves - return back to the original grid-item. Also called to remove empty sub-grids when last item is dragged out (since re-creating is simple) @@ -1174,7 +1423,7 @@ removeWidget( triggerEvent): GridStack; ``` -Defined in: [gridstack.ts:1194](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L1194) +Defined in: [gridstack.ts:1331](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L1331) Removes widget from the grid. @@ -1196,63 +1445,104 @@ Removes widget from the grid. resizable(els, val): GridStack; ``` -Defined in: [gridstack.ts:1966](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L1966) +Defined in: [gridstack.ts:2202](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L2202) -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. +Enables/Disables user resizing for specific grid elements. +For all items and future items, use enableResize() instead. No-op for static grids. ###### Parameters | Parameter | Type | Description | | ------ | ------ | ------ | -| `els` | [`GridStackElement`](#gridstackelement) | widget or selector to modify | -| `val` | `boolean` | if true widget will be resizable, assuming the parent grid isn't noResize or static. | +| `els` | [`GridStackElement`](#gridstackelement) | widget element(s) or selector to modify | +| `val` | `boolean` | if true widget will be resizable, assuming the parent grid isn't noResize or static | ###### Returns [`GridStack`](#gridstack-1) +the grid instance for chaining + +###### Example + +```ts +// Make specific widgets resizable +grid.resizable('.my-widget', true); + +// Disable resizing for specific widgets +grid.resizable('#fixed-size-widget', false); +``` + ##### resizeToContent() ```ts resizeToContent(el): void; ``` -Defined in: [gridstack.ts:1422](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L1422) +Defined in: [gridstack.ts:1592](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L1592) -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. +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. ###### Parameters | Parameter | Type | Description | | ------ | ------ | ------ | -| `el` | [`GridItemHTMLElement`](#griditemhtmlelement) | grid item element | +| `el` | [`GridItemHTMLElement`](#griditemhtmlelement) | the grid item element to resize | ###### Returns `void` +###### Example + +```ts +// 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); +``` + ##### rotate() ```ts rotate(els, relative?): GridStack; ``` -Defined in: [gridstack.ts:1486](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L1486) +Defined in: [gridstack.ts:1667](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L1667) -rotate (by swapping w & h) the passed in node - called when user press 'r' during dragging +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. ###### Parameters | Parameter | Type | Description | | ------ | ------ | ------ | -| `els` | [`GridStackElement`](#gridstackelement) | widget or selector of objects to modify | -| `relative?` | [`Position`](#position-1) | optional pixel coord relative to upper/left corner to rotate around (will keep that cell under cursor) | +| `els` | [`GridStackElement`](#gridstackelement) | widget element(s) or selector to rotate | +| `relative?` | [`Position`](#position-1) | optional pixel coordinate relative to upper/left corner to rotate around (keeps that cell under cursor) | ###### Returns [`GridStack`](#gridstack-1) +the grid instance for chaining + +###### Example + +```ts +// Rotate a specific widget +grid.rotate('.my-widget'); + +// Rotate with relative positioning during drag +grid.rotate(widget, { left: 50, top: 30 }); +``` + ##### save() ```ts @@ -1264,7 +1554,7 @@ save( | GridStackWidget[]; ``` -Defined in: [gridstack.ts:619](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L619) +Defined in: [gridstack.ts:630](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L630) saves the current layout returning a list of widgets for serialization which might include any nested grids. @@ -1289,7 +1579,7 @@ list of widgets or full grid option, including .children list of widgets setAnimation(doAnimate, delay?): GridStack; ``` -Defined in: [gridstack.ts:1251](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L1251) +Defined in: [gridstack.ts:1388](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L1388) Toggle the grid animation state. Toggles the `grid-stack-animate` class. @@ -1313,7 +1603,7 @@ setStatic( recurse): GridStack; ``` -Defined in: [gridstack.ts:1274](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L1274) +Defined in: [gridstack.ts:1411](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L1411) Toggle the grid static state, which permanently removes/add Drag&Drop support, unlike disable()/enable() that just turns it off/on. Also toggle the grid-stack-static class. @@ -1340,7 +1630,7 @@ static setupDragIn( root?): void; ``` -Defined in: [gridstack.ts:1931](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L1931) +Defined in: [gridstack.ts:2145](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L2145) call to setup dragging in from the outside (say toolbar), by specifying the class selection and options. Called during GridStack.init() as options, but can also be called directly (last param are used) in case the toolbar @@ -1365,7 +1655,7 @@ is dynamically create and needs to be set later. protected triggerEvent(event, target): void; ``` -Defined in: [gridstack.ts:2626](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L2626) +Defined in: [gridstack.ts:2913](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L2913) call given event callback on our main top-most grid (if we're nested) @@ -1386,28 +1676,52 @@ call given event callback on our main top-most grid (if we're nested) update(els, opt): GridStack; ``` -Defined in: [gridstack.ts:1330](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L1330) +Defined in: [gridstack.ts:1488](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L1488) -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. +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. ###### Parameters | Parameter | Type | Description | | ------ | ------ | ------ | -| `els` | [`GridStackElement`](#gridstackelement) | widget or selector of objects to modify (note: setting the same x,y for multiple items will be indeterministic and likely unwanted) | -| `opt` | [`GridStackWidget`](#gridstackwidget) | new widget options (x,y,w,h, etc..). Only those set will be updated. | +| `els` | [`GridStackElement`](#gridstackelement) | widget element(s) or selector to modify | +| `opt` | [`GridStackWidget`](#gridstackwidget) | new widget options (x,y,w,h, etc.). Only those set will be updated. | ###### Returns [`GridStack`](#gridstack-1) +the grid instance for chaining + +###### Example + +```ts +// Update widget size and position +grid.update('.my-widget', { x: 2, y: 1, w: 3, h: 2 }); + +// Update widget content +grid.update(widget, { content: '

New content

' }); + +// Update multiple properties +grid.update('#my-widget', { + w: 4, + h: 3, + noResize: true, + locked: true +}); +``` + ##### updateOptions() ```ts updateOptions(o): GridStack; ``` -Defined in: [gridstack.ts:1292](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L1292) +Defined in: [gridstack.ts:1429](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L1429) Updates the passed in options on the grid (similar to update(widget) for for the grid options). @@ -1427,7 +1741,7 @@ Updates the passed in options on the grid (similar to update(widget) for for the willItFit(node): boolean; ``` -Defined in: [gridstack.ts:1540](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L1540) +Defined in: [gridstack.ts:1745](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L1745) Returns true if the height of the grid will be less than the vertical constraint. Always returns true if grid doesn't have height constraint. @@ -1458,17 +1772,17 @@ if (grid.willItFit(newWidget)) { | ------ | ------ | ------ | ------ | ------ | ------ | | `addRemoveCB?` | `static` | [`AddRemoveFcn`](#addremovefcn) | `undefined` | callback method use when new items|grids needs to be created or deleted, instead of the default item:
w.content
grid:
grid content...
add = true: the returned DOM element will then be converted to a GridItemHTMLElement using makeWidget()|GridStack:init(). add = false: the item will be removed from DOM (if not already done) grid = true|false for grid vs grid-items | [gridstack.ts:184](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L184) | | `animationDelay` | `public` | `number` | `undefined` | time to wait for animation (if enabled) to be done so content sizing can happen | [gridstack.ts:218](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L218) | -| `el` | `public` | [`GridHTMLElement`](#gridhtmlelement) | `undefined` | the HTML element tied to this grid after it's been initialized | [gridstack.ts:263](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L263) | +| `el` | `public` | [`GridHTMLElement`](#gridhtmlelement) | `undefined` | the HTML element tied to this grid after it's been initialized | [gridstack.ts:266](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L266) | | `engine` | `public` | [`GridStackEngine`](#gridstackengine-2) | `undefined` | engine used to implement non DOM grid functionality | [gridstack.ts:212](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L212) | | `Engine` | `static` | *typeof* [`GridStackEngine`](#gridstackengine-2) | `GridStackEngine` | scoping so users can call new GridStack.Engine(12) for example | [gridstack.ts:209](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L209) | | `engineClass` | `static` | *typeof* [`GridStackEngine`](#gridstackengine-2) | `undefined` | - | [gridstack.ts:220](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L220) | -| `opts` | `public` | [`GridStackOptions`](#gridstackoptions) | `{}` | grid options - public for classes to access, but use methods to modify! | [gridstack.ts:263](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L263) | +| `opts` | `public` | [`GridStackOptions`](#gridstackoptions) | `{}` | grid options - public for classes to access, but use methods to modify! | [gridstack.ts:266](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L266) | | `parentGridNode?` | `public` | [`GridStackNode`](#gridstacknode-2) | `undefined` | point to a parent grid item if we're nested (inside a grid-item in between 2 Grids) | [gridstack.ts:215](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L215) | | `renderCB?` | `static` | [`RenderFcn`](#renderfcn) | `undefined` | callback to create the content of widgets so the app can control how to store and restore it By default this lib will do 'el.textContent = w.content' forcing text only support for avoiding potential XSS issues. | [gridstack.ts:195](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L195) | | `resizeObserver` | `protected` | `ResizeObserver` | `undefined` | - | [gridstack.ts:221](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L221) | | `resizeToContentCB?` | `static` | [`ResizeToContentFcn`](#resizetocontentfcn) | `undefined` | callback to use for resizeToContent instead of the built in one | [gridstack.ts:201](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L201) | | `resizeToContentParent` | `static` | `string` | `'.grid-stack-item-content'` | parent class for sizing content. defaults to '.grid-stack-item-content' | [gridstack.ts:203](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L203) | -| `responseLayout` | `protected` | [`ColumnOptions`](#columnoptions) | `undefined` | - | [gridstack.ts:255](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L255) | +| `responseLayout` | `protected` | [`ColumnOptions`](#columnoptions) | `undefined` | - | [gridstack.ts:258](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L258) | | `saveCB?` | `static` | [`SaveFcn`](#savefcn) | `undefined` | callback during saving to application can inject extra data for each widget, on top of the grid layout properties | [gridstack.ts:189](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L189) | | `updateCB?` | `static` | (`w`) => `void` | `undefined` | called after a widget has been updated (eg: load() into an existing list of children) so application can do extra work | [gridstack.ts:198](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L198) | | `Utils` | `static` | *typeof* [`Utils`](#utils-1) | `Utils` | scoping so users can call GridStack.Utils.sort() for example | [gridstack.ts:206](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L206) | @@ -1478,12 +1792,19 @@ if (grid.willItFit(newWidget)) { ### GridStackEngine -Defined in: [gridstack-engine.ts:27](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L27) +Defined in: [gridstack-engine.ts:34](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L34) + +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. -Defines the GridStack engine that does most no DOM grid manipulation. -See GridStack methods and vars for descriptions. +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 - call the main GridStack API instead +NOTE: Values should not be modified directly - use the main GridStack API instead +to ensure proper DOM updates and event triggers. #### Accessors @@ -1495,29 +1816,47 @@ NOTE: values should not be modified directly - call the main GridStack API inste get float(): boolean; ``` -Defined in: [gridstack-engine.ts:315](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L315) +Defined in: [gridstack-engine.ts:438](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L438) + +Get the current floating mode setting. + +###### Example -float getter method +```ts +const isFloating = engine.float; +console.log('Floating enabled:', isFloating); +``` ###### Returns `boolean` +true if floating is enabled, false otherwise + ###### Set Signature ```ts set float(val): void; ``` -Defined in: [gridstack-engine.ts:306](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L306) +Defined in: [gridstack-engine.ts:421](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L421) -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) + +###### Example + +```ts +engine.float = true; // Enable floating +engine.float = false; // Disable floating (default) +``` ###### Parameters -| Parameter | Type | -| ------ | ------ | -| `val` | `boolean` | +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `val` | `boolean` | true to enable floating, false to disable | ###### Returns @@ -1531,7 +1870,7 @@ enable/disable floating widgets (default: `false`) See [example](http://gridstac new GridStackEngine(opts): GridStackEngine; ``` -Defined in: [gridstack-engine.ts:54](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L54) +Defined in: [gridstack-engine.ts:61](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L61) ###### Parameters @@ -1551,7 +1890,7 @@ Defined in: [gridstack-engine.ts:54](https://github.com/adumesny/gridstack.js/bl protected _useEntireRowArea(node, nn): boolean; ``` -Defined in: [gridstack-engine.ts:81](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L81) +Defined in: [gridstack-engine.ts:103](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L103) ###### Parameters @@ -1573,48 +1912,73 @@ addNode( after?): GridStackNode; ``` -Defined in: [gridstack-engine.ts:545](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L545) +Defined in: [gridstack-engine.ts:756](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L756) -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. ###### Parameters -| Parameter | Type | Default value | -| ------ | ------ | ------ | -| `node` | [`GridStackNode`](#gridstacknode-2) | `undefined` | -| `triggerAddEvent` | `boolean` | `false` | -| `after?` | [`GridStackNode`](#gridstacknode-2) | `undefined` | +| Parameter | Type | Default value | Description | +| ------ | ------ | ------ | ------ | +| `node` | [`GridStackNode`](#gridstacknode-2) | `undefined` | the node to add to the grid | +| `triggerAddEvent` | `boolean` | `false` | if true, adds node to addedNodes list for event triggering | +| `after?` | [`GridStackNode`](#gridstacknode-2) | `undefined` | optional node to place this node after (for ordering) | ###### Returns [`GridStackNode`](#gridstacknode-2) +the added node (or existing node if duplicate) + +###### Example + +```ts +const node = { x: 0, y: 0, w: 2, h: 1, content: 'Hello' }; +const added = engine.addNode(node, true); +``` + ##### batchUpdate() ```ts batchUpdate(flag, doPack): GridStackEngine; ``` -Defined in: [gridstack-engine.ts:63](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L63) +Defined in: [gridstack-engine.ts:85](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L85) + +Enable/disable batch mode for multiple operations to optimize performance. +When enabled, layout updates are deferred until batch mode is disabled. ###### Parameters -| Parameter | Type | Default value | -| ------ | ------ | ------ | -| `flag` | `boolean` | `true` | -| `doPack` | `boolean` | `true` | +| Parameter | Type | Default value | Description | +| ------ | ------ | ------ | ------ | +| `flag` | `boolean` | `true` | true to enable batch mode, false to disable and apply changes | +| `doPack` | `boolean` | `true` | if true (default), pack/compact nodes when disabling batch mode | ###### Returns [`GridStackEngine`](#gridstackengine-2) +the engine instance for chaining + +###### Example + +```ts +// Start batch mode for multiple operations +engine.batchUpdate(true); +engine.addNode(node1); +engine.addNode(node2); +engine.batchUpdate(false); // Apply all changes at once +``` + ##### beginUpdate() ```ts beginUpdate(node): GridStackEngine; ``` -Defined in: [gridstack-engine.ts:747](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L747) +Defined in: [gridstack-engine.ts:993](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L993) ###### Parameters @@ -1635,7 +1999,7 @@ cacheLayout( clear): GridStackEngine; ``` -Defined in: [gridstack-engine.ts:937](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L937) +Defined in: [gridstack-engine.ts:1183](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L1183) call to cache the given layout internally to the given location so we can restore back when column changes size @@ -1657,7 +2021,7 @@ call to cache the given layout internally to the given location so we can restor cacheOneLayout(n, column): GridStackEngine; ``` -Defined in: [gridstack-engine.ts:957](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L957) +Defined in: [gridstack-engine.ts:1203](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L1203) call to cache the given node layout internally to the given location so we can restore back when column changes size @@ -1672,44 +2036,13 @@ call to cache the given node layout internally to the given location so we can r [`GridStackEngine`](#gridstackengine-2) -##### cacheRects() - -```ts -cacheRects( - w, - h, - top, - right, - bottom, - left): GridStackEngine; -``` - -Defined in: [gridstack-engine.ts:225](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L225) - -called to cache the nodes pixel rectangles used for collision detection during drag - -###### Parameters - -| Parameter | Type | -| ------ | ------ | -| `w` | `number` | -| `h` | `number` | -| `top` | `number` | -| `right` | `number` | -| `bottom` | `number` | -| `left` | `number` | - -###### Returns - -[`GridStackEngine`](#gridstackengine-2) - ##### changedPosConstrain() ```ts changedPosConstrain(node, p): boolean; ``` -Defined in: [gridstack-engine.ts:669](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L669) +Defined in: [gridstack-engine.ts:915](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L915) true if x,y or w,h are different after clamping to min/max @@ -1730,7 +2063,7 @@ true if x,y or w,h are different after clamping to min/max cleanupNode(node): GridStackEngine; ``` -Defined in: [gridstack-engine.ts:988](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L988) +Defined in: [gridstack-engine.ts:1234](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L1234) called to remove all internal values but the _id @@ -1753,22 +2086,34 @@ collide( skip2?): GridStackNode; ``` -Defined in: [gridstack-engine.ts:146](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L146) +Defined in: [gridstack-engine.ts:182](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L182) -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. ###### Parameters -| Parameter | Type | Default value | -| ------ | ------ | ------ | -| `skip` | [`GridStackNode`](#gridstacknode-2) | `undefined` | -| `area` | [`GridStackNode`](#gridstacknode-2) | `skip` | -| `skip2?` | [`GridStackNode`](#gridstacknode-2) | `undefined` | +| Parameter | Type | Default value | Description | +| ------ | ------ | ------ | ------ | +| `skip` | [`GridStackNode`](#gridstacknode-2) | `undefined` | the node to skip in collision detection (usually the node being moved) | +| `area` | [`GridStackNode`](#gridstacknode-2) | `skip` | the area to check for collisions (defaults to skip node's area) | +| `skip2?` | [`GridStackNode`](#gridstacknode-2) | `undefined` | optional second node to skip in collision detection | ###### Returns [`GridStackNode`](#gridstacknode-2) +the first colliding node, or undefined if no collision + +###### Example + +```ts +const colliding = engine.collide(draggedNode, {x: 2, y: 1, w: 2, h: 1}); +if (colliding) { + console.log('Would collide with:', colliding.id); +} +``` + ##### collideAll() ```ts @@ -1778,41 +2123,66 @@ collideAll( skip2?): GridStackNode[]; ``` -Defined in: [gridstack-engine.ts:151](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L151) +Defined in: [gridstack-engine.ts:200](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L200) + +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. ###### Parameters -| Parameter | Type | Default value | -| ------ | ------ | ------ | -| `skip` | [`GridStackNode`](#gridstacknode-2) | `undefined` | -| `area` | [`GridStackNode`](#gridstacknode-2) | `skip` | -| `skip2?` | [`GridStackNode`](#gridstacknode-2) | `undefined` | +| Parameter | Type | Default value | Description | +| ------ | ------ | ------ | ------ | +| `skip` | [`GridStackNode`](#gridstacknode-2) | `undefined` | the node to skip in collision detection | +| `area` | [`GridStackNode`](#gridstacknode-2) | `skip` | the area to check for collisions (defaults to skip node's area) | +| `skip2?` | [`GridStackNode`](#gridstacknode-2) | `undefined` | optional second node to skip in collision detection | ###### Returns [`GridStackNode`](#gridstacknode-2)[] +array of all colliding nodes + +###### Example + +```ts +const allCollisions = engine.collideAll(draggedNode); +console.log('Colliding with', allCollisions.length, 'nodes'); +``` + ##### compact() ```ts compact(layout, doSort): GridStackEngine; ``` -Defined in: [gridstack-engine.ts:283](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L283) +Defined in: [gridstack-engine.ts:388](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L388) -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. ###### Parameters -| Parameter | Type | Default value | -| ------ | ------ | ------ | -| `layout` | [`CompactOptions`](#compactoptions) | `'compact'` | -| `doSort` | `boolean` | `true` | +| Parameter | Type | Default value | Description | +| ------ | ------ | ------ | ------ | +| `layout` | [`CompactOptions`](#compactoptions) | `'compact'` | 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 | +| `doSort` | `boolean` | `true` | if true (default), sort nodes by position before compacting | ###### Returns [`GridStackEngine`](#gridstackengine-2) +the engine instance for chaining + +###### Example + +```ts +// Compact to fill empty spaces +engine.compact(); + +// Compact preserving item order +engine.compact('list'); +``` + ##### directionCollideCoverage() ```ts @@ -1822,7 +2192,7 @@ protected directionCollideCoverage( collides): GridStackNode; ``` -Defined in: [gridstack-engine.ts:158](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L158) +Defined in: [gridstack-engine.ts:207](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L207) does a pixel coverage collision based on where we started, returning the node that has the most coverage that is >50% mid line @@ -1844,7 +2214,7 @@ does a pixel coverage collision based on where we started, returning the node th endUpdate(): GridStackEngine; ``` -Defined in: [gridstack-engine.ts:756](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L756) +Defined in: [gridstack-engine.ts:1002](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L1002) ###### Returns @@ -1856,7 +2226,7 @@ Defined in: [gridstack-engine.ts:756](https://github.com/adumesny/gridstack.js/b protected findCacheLayout(n, column): number; ``` -Defined in: [gridstack-engine.ts:971](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L971) +Defined in: [gridstack-engine.ts:1217](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L1217) ###### Parameters @@ -1879,52 +2249,75 @@ findEmptyPosition( after?): boolean; ``` -Defined in: [gridstack-engine.ts:523](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L523) +Defined in: [gridstack-engine.ts:722](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L722) -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. ###### Parameters -| Parameter | Type | -| ------ | ------ | -| `node` | [`GridStackNode`](#gridstacknode-2) | -| `nodeList` | [`GridStackNode`](#gridstacknode-2)[] | -| `column` | `number` | -| `after?` | [`GridStackNode`](#gridstacknode-2) | +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `node` | [`GridStackNode`](#gridstacknode-2) | the node to find a position for (w,h must be set) | +| `nodeList` | [`GridStackNode`](#gridstacknode-2)[] | optional list of nodes to check against (defaults to engine nodes) | +| `column` | `number` | optional column count (defaults to engine column count) | +| `after?` | [`GridStackNode`](#gridstacknode-2) | optional node to start search after (maintains order) | ###### Returns `boolean` +true if an empty position was found and node was updated + +###### Example + +```ts +const node = { w: 2, h: 1 }; +if (engine.findEmptyPosition(node)) { + console.log('Found position at:', node.x, node.y); +} +``` + ##### getDirtyNodes() ```ts getDirtyNodes(verify?): GridStackNode[]; ``` -Defined in: [gridstack-engine.ts:470](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L470) +Defined in: [gridstack-engine.ts:636](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L636) -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. ###### Parameters -| Parameter | Type | -| ------ | ------ | -| `verify?` | `boolean` | +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `verify?` | `boolean` | if true, performs additional verification by comparing current vs original positions | ###### Returns [`GridStackNode`](#gridstacknode-2)[] +array of nodes that have been modified + +###### Example + +```ts +const changed = engine.getDirtyNodes(); +console.log('Modified nodes:', changed.length); + +// Get verified dirty nodes +const verified = engine.getDirtyNodes(true); +``` + ##### getRow() ```ts getRow(): number; ``` -Defined in: [gridstack-engine.ts:743](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L743) +Defined in: [gridstack-engine.ts:989](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L989) ###### Returns @@ -1940,28 +2333,40 @@ isAreaEmpty( h): boolean; ``` -Defined in: [gridstack-engine.ts:277](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L277) +Defined in: [gridstack-engine.ts:366](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L366) + +Check if the specified rectangular area is empty (no nodes occupy any part of it). ###### Parameters -| Parameter | Type | -| ------ | ------ | -| `x` | `number` | -| `y` | `number` | -| `w` | `number` | -| `h` | `number` | +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `x` | `number` | the x coordinate (column) of the area to check | +| `y` | `number` | the y coordinate (row) of the area to check | +| `w` | `number` | the width in columns of the area to check | +| `h` | `number` | the height in rows of the area to check | ###### Returns `boolean` +true if the area is completely empty, false if any node overlaps + +###### Example + +```ts +if (engine.isAreaEmpty(2, 1, 3, 2)) { + console.log('Area is available for placement'); +} +``` + ##### moveNode() ```ts moveNode(node, o): boolean; ``` -Defined in: [gridstack-engine.ts:683](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L683) +Defined in: [gridstack-engine.ts:929](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L929) return true if the passed in node was actually moved (checks for no-op and locked) @@ -1982,84 +2387,129 @@ return true if the passed in node was actually moved (checks for no-op and locke moveNodeCheck(node, o): boolean; ``` -Defined in: [gridstack-engine.ts:597](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L597) +Defined in: [gridstack-engine.ts:843](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L843) + +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. -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. +For complex cases (like maxRow constraints), it simulates the move in a clone first, +then applies the changes only if they meet all specifications. ###### Parameters -| Parameter | Type | -| ------ | ------ | -| `node` | [`GridStackNode`](#gridstacknode-2) | -| `o` | [`GridStackMoveOpts`](#gridstackmoveopts) | +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `node` | [`GridStackNode`](#gridstacknode-2) | the node to move | +| `o` | [`GridStackMoveOpts`](#gridstackmoveopts) | move options including target position | ###### Returns `boolean` +true if the node was successfully moved + +###### Example + +```ts +const canMove = engine.moveNodeCheck(node, { x: 2, y: 1 }); +if (canMove) { + console.log('Node moved successfully'); +} +``` + ##### nodeBoundFix() ```ts nodeBoundFix(node, resizing?): GridStackEngine; ``` -Defined in: [gridstack-engine.ts:407](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L407) +Defined in: [gridstack-engine.ts:560](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L560) -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. ###### Parameters -| Parameter | Type | -| ------ | ------ | -| `node` | [`GridStackNode`](#gridstacknode-2) | -| `resizing?` | `boolean` | +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `node` | [`GridStackNode`](#gridstacknode-2) | the node to validate and fix | +| `resizing?` | `boolean` | if true, resize the node to fit; if false, move the node to fit | ###### Returns [`GridStackEngine`](#gridstackengine-2) +the engine instance for chaining + +###### Example + +```ts +// Fix a node that might be out of bounds +engine.nodeBoundFix(node, true); // Resize to fit +engine.nodeBoundFix(node, false); // Move to fit +``` + ##### prepareNode() ```ts prepareNode(node, resizing?): GridStackNode; ``` -Defined in: [gridstack-engine.ts:366](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L366) +Defined in: [gridstack-engine.ts:507](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L507) -given a random node, makes sure it's coordinates/values are valid in the current grid +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. ###### Parameters | Parameter | Type | Description | | ------ | ------ | ------ | -| `node` | [`GridStackNode`](#gridstacknode-2) | to adjust | -| `resizing?` | `boolean` | if out of bound, resize down or move into the grid to fit ? | +| `node` | [`GridStackNode`](#gridstacknode-2) | the node to prepare and validate | +| `resizing?` | `boolean` | if true, resize the node down if it's out of bounds; if false, move it to fit | ###### Returns [`GridStackNode`](#gridstacknode-2) +the prepared node with valid coordinates + +###### Example + +```ts +const node = { w: 3, h: 2, content: 'Hello' }; +const prepared = engine.prepareNode(node); +console.log('Node prepared at:', prepared.x, prepared.y); +``` + ##### removeAll() ```ts removeAll(removeDOM, triggerEvent): GridStackEngine; ``` -Defined in: [gridstack-engine.ts:584](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L584) +Defined in: [gridstack-engine.ts:816](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L816) + +Remove all nodes from the grid. ###### Parameters -| Parameter | Type | Default value | -| ------ | ------ | ------ | -| `removeDOM` | `boolean` | `true` | -| `triggerEvent` | `boolean` | `true` | +| Parameter | Type | Default value | Description | +| ------ | ------ | ------ | ------ | +| `removeDOM` | `boolean` | `true` | if true (default), marks all nodes for DOM removal | +| `triggerEvent` | `boolean` | `true` | if true (default), triggers removal events | ###### Returns [`GridStackEngine`](#gridstackengine-2) +the engine instance for chaining + +###### Example + +```ts +engine.removeAll(); // Remove all nodes +``` + ##### removeNode() ```ts @@ -2069,27 +2519,37 @@ removeNode( triggerEvent): GridStackEngine; ``` -Defined in: [gridstack-engine.ts:568](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L568) +Defined in: [gridstack-engine.ts:790](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L790) + +Remove the given node from the grid. ###### Parameters -| Parameter | Type | Default value | -| ------ | ------ | ------ | -| `node` | [`GridStackNode`](#gridstacknode-2) | `undefined` | -| `removeDOM` | `boolean` | `true` | -| `triggerEvent` | `boolean` | `false` | +| Parameter | Type | Default value | Description | +| ------ | ------ | ------ | ------ | +| `node` | [`GridStackNode`](#gridstacknode-2) | `undefined` | the node to remove | +| `removeDOM` | `boolean` | `true` | if true (default), marks node for DOM removal | +| `triggerEvent` | `boolean` | `false` | if true, adds node to removedNodes list for event triggering | ###### Returns [`GridStackEngine`](#gridstackengine-2) +the engine instance for chaining + +###### Example + +```ts +engine.removeNode(node, true, true); +``` + ##### removeNodeFromLayoutCache() ```ts removeNodeFromLayoutCache(n): void; ``` -Defined in: [gridstack-engine.ts:975](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L975) +Defined in: [gridstack-engine.ts:1221](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L1221) ###### Parameters @@ -2107,7 +2567,7 @@ Defined in: [gridstack-engine.ts:975](https://github.com/adumesny/gridstack.js/b save(saveElement, saveCB?): GridStackNode[]; ``` -Defined in: [gridstack-engine.ts:767](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L767) +Defined in: [gridstack-engine.ts:1013](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L1013) saves a copy of the largest column layout (eg 12 even when rendering oneColumnMode) so we don't loose orig layout, returning a list of widgets for serialization @@ -2129,48 +2589,70 @@ returning a list of widgets for serialization sortNodes(dir): GridStackEngine; ``` -Defined in: [gridstack-engine.ts:318](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L318) +Defined in: [gridstack-engine.ts:451](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L451) -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. ###### Parameters -| Parameter | Type | Default value | -| ------ | ------ | ------ | -| `dir` | `-1` \| `1` | `1` | +| Parameter | Type | Default value | Description | +| ------ | ------ | ------ | ------ | +| `dir` | `-1` \| `1` | `1` | sort direction: 1 for ascending (first to last), -1 for descending (last to first) | ###### Returns [`GridStackEngine`](#gridstackengine-2) +the engine instance for chaining + +###### Example + +```ts +engine.sortNodes(); // Sort ascending (default) +engine.sortNodes(-1); // Sort descending +``` + ##### swap() ```ts swap(a, b): boolean; ``` -Defined in: [gridstack-engine.ts:239](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L239) +Defined in: [gridstack-engine.ts:314](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L314) -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. ###### Parameters -| Parameter | Type | -| ------ | ------ | -| `a` | [`GridStackNode`](#gridstacknode-2) | -| `b` | [`GridStackNode`](#gridstacknode-2) | +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `a` | [`GridStackNode`](#gridstacknode-2) | first node to swap | +| `b` | [`GridStackNode`](#gridstacknode-2) | second node to swap | ###### Returns `boolean` +true if swap was successful, false if not possible, undefined if not applicable + +###### Example + +```ts +const swapped = engine.swap(nodeA, nodeB); +if (swapped) { + console.log('Nodes swapped successfully'); +} +``` + ##### willItFit() ```ts willItFit(node): boolean; ``` -Defined in: [gridstack-engine.ts:648](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L648) +Defined in: [gridstack-engine.ts:894](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L894) return true if can fit in grid height constrain only (always true if no maxRow) @@ -2188,23 +2670,25 @@ return true if can fit in grid height constrain only (always true if no maxRow) | Property | Modifier | Type | Default value | Description | Defined in | | ------ | ------ | ------ | ------ | ------ | ------ | -| `addedNodes` | `public` | [`GridStackNode`](#gridstacknode-2)[] | `[]` | - | [gridstack-engine.ts:31](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L31) | -| `batchMode` | `public` | `boolean` | `undefined` | - | [gridstack-engine.ts:33](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L33) | -| `column` | `public` | `number` | `undefined` | - | [gridstack-engine.ts:28](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L28) | -| `defaultColumn` | `public` | `number` | `12` | - | [gridstack-engine.ts:34](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L34) | -| `maxRow` | `public` | `number` | `undefined` | - | [gridstack-engine.ts:29](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L29) | -| `nodes` | `public` | [`GridStackNode`](#gridstacknode-2)[] | `undefined` | - | [gridstack-engine.ts:30](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L30) | -| `removedNodes` | `public` | [`GridStackNode`](#gridstacknode-2)[] | `[]` | - | [gridstack-engine.ts:32](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L32) | -| `skipCacheUpdate?` | `public` | `boolean` | `undefined` | true when grid.load() already cached the layout and can skip out of bound caching info | [gridstack-engine.ts:48](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L48) | +| `addedNodes` | `public` | [`GridStackNode`](#gridstacknode-2)[] | `[]` | - | [gridstack-engine.ts:38](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L38) | +| `batchMode` | `public` | `boolean` | `undefined` | - | [gridstack-engine.ts:40](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L40) | +| `column` | `public` | `number` | `undefined` | - | [gridstack-engine.ts:35](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L35) | +| `defaultColumn` | `public` | `number` | `12` | - | [gridstack-engine.ts:41](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L41) | +| `maxRow` | `public` | `number` | `undefined` | - | [gridstack-engine.ts:36](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L36) | +| `nodes` | `public` | [`GridStackNode`](#gridstacknode-2)[] | `undefined` | - | [gridstack-engine.ts:37](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L37) | +| `removedNodes` | `public` | [`GridStackNode`](#gridstacknode-2)[] | `[]` | - | [gridstack-engine.ts:39](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L39) | +| `skipCacheUpdate?` | `public` | `boolean` | `undefined` | true when grid.load() already cached the layout and can skip out of bound caching info | [gridstack-engine.ts:55](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack-engine.ts#L55) | *** ### Utils -Defined in: [utils.ts:61](https://github.com/adumesny/gridstack.js/blob/master/src/utils.ts#L61) +Defined in: [utils.ts:97](https://github.com/adumesny/gridstack.js/blob/master/src/utils.ts#L97) -Utility methods +Collection of utility methods used throughout GridStack. +These are general-purpose helper functions for DOM manipulation, +positioning calculations, object operations, and more. #### Constructors @@ -2226,7 +2710,7 @@ new Utils(): Utils; static addElStyles(el, styles): void; ``` -Defined in: [utils.ts:469](https://github.com/adumesny/gridstack.js/blob/master/src/utils.ts#L469) +Defined in: [utils.ts:690](https://github.com/adumesny/gridstack.js/blob/master/src/utils.ts#L690) ###### Parameters @@ -2245,7 +2729,7 @@ Defined in: [utils.ts:469](https://github.com/adumesny/gridstack.js/blob/master/ static appendTo(el, parent): void; ``` -Defined in: [utils.ts:451](https://github.com/adumesny/gridstack.js/blob/master/src/utils.ts#L451) +Defined in: [utils.ts:672](https://github.com/adumesny/gridstack.js/blob/master/src/utils.ts#L672) ###### Parameters @@ -2264,48 +2748,67 @@ Defined in: [utils.ts:451](https://github.com/adumesny/gridstack.js/blob/master/ static area(a): number; ``` -Defined in: [utils.ts:154](https://github.com/adumesny/gridstack.js/blob/master/src/utils.ts#L154) +Defined in: [utils.ts:288](https://github.com/adumesny/gridstack.js/blob/master/src/utils.ts#L288) -returns the area +Calculate the total area of a grid position. ###### Parameters -| Parameter | Type | -| ------ | ------ | -| `a` | [`GridStackPosition`](#gridstackposition) | +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `a` | [`GridStackPosition`](#gridstackposition) | position with width and height | ###### Returns `number` +the total area (width * height) + +###### Example + +```ts +const area = Utils.area({x: 0, y: 0, w: 3, h: 2}); // returns 6 +``` + ##### areaIntercept() ```ts static areaIntercept(a, b): number; ``` -Defined in: [utils.ts:143](https://github.com/adumesny/gridstack.js/blob/master/src/utils.ts#L143) +Defined in: [utils.ts:269](https://github.com/adumesny/gridstack.js/blob/master/src/utils.ts#L269) -returns the area a and b overlap +Calculate the overlapping area between two grid positions. ###### Parameters -| Parameter | Type | -| ------ | ------ | -| `a` | [`GridStackPosition`](#gridstackposition) | -| `b` | [`GridStackPosition`](#gridstackposition) | +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `a` | [`GridStackPosition`](#gridstackposition) | first position | +| `b` | [`GridStackPosition`](#gridstackposition) | second position | ###### Returns `number` +the area of overlap (0 if no overlap) + +###### Example + +```ts +const overlap = Utils.areaIntercept( + {x: 0, y: 0, w: 3, h: 2}, + {x: 1, y: 0, w: 3, h: 2} +); // returns 4 (2x2 overlap) +``` + ##### canBeRotated() ```ts static canBeRotated(n): boolean; ``` -Defined in: [utils.ts:572](https://github.com/adumesny/gridstack.js/blob/master/src/utils.ts#L572) +Defined in: [utils.ts:793](https://github.com/adumesny/gridstack.js/blob/master/src/utils.ts#L793) true if the item can be rotated (checking for prop, not space available) @@ -2325,7 +2828,7 @@ true if the item can be rotated (checking for prop, not space available) static clone(obj): T; ``` -Defined in: [utils.ts:414](https://github.com/adumesny/gridstack.js/blob/master/src/utils.ts#L414) +Defined in: [utils.ts:635](https://github.com/adumesny/gridstack.js/blob/master/src/utils.ts#L635) single level clone, returning a new object with same top fields. This will share sub objects and arrays @@ -2351,7 +2854,7 @@ single level clone, returning a new object with same top fields. This will share static cloneDeep(obj): T; ``` -Defined in: [utils.ts:430](https://github.com/adumesny/gridstack.js/blob/master/src/utils.ts#L430) +Defined in: [utils.ts:651](https://github.com/adumesny/gridstack.js/blob/master/src/utils.ts#L651) Recursive clone version that returns a full copy, checking for nested objects and arrays ONLY. Note: this will use as-is any key starting with double __ (and not copy inside) some lib have circular dependencies. @@ -2378,7 +2881,7 @@ Note: this will use as-is any key starting with double __ (and not copy inside) static cloneNode(el): HTMLElement; ``` -Defined in: [utils.ts:445](https://github.com/adumesny/gridstack.js/blob/master/src/utils.ts#L445) +Defined in: [utils.ts:666](https://github.com/adumesny/gridstack.js/blob/master/src/utils.ts#L666) deep clone the given HTML node, removing teh unique id field @@ -2401,134 +2904,194 @@ static copyPos( doMinMax): GridStackWidget; ``` -Defined in: [utils.ts:244](https://github.com/adumesny/gridstack.js/blob/master/src/utils.ts#L244) +Defined in: [utils.ts:465](https://github.com/adumesny/gridstack.js/blob/master/src/utils.ts#L465) -copies over b size & position (GridStackPosition), and optionally min/max as well +Copy position and size properties from one widget to another. +Copies x, y, w, h and optionally min/max constraints. ###### Parameters -| Parameter | Type | Default value | -| ------ | ------ | ------ | -| `a` | [`GridStackWidget`](#gridstackwidget) | `undefined` | -| `b` | [`GridStackWidget`](#gridstackwidget) | `undefined` | -| `doMinMax` | `boolean` | `false` | +| Parameter | Type | Default value | Description | +| ------ | ------ | ------ | ------ | +| `a` | [`GridStackWidget`](#gridstackwidget) | `undefined` | target widget to copy to | +| `b` | [`GridStackWidget`](#gridstackwidget) | `undefined` | source widget to copy from | +| `doMinMax` | `boolean` | `false` | if true, also copy min/max width/height constraints | ###### Returns [`GridStackWidget`](#gridstackwidget) +the target widget (a) + +###### Example + +```ts +Utils.copyPos(widget1, widget2); // Copy position/size +Utils.copyPos(widget1, widget2, true); // Also copy constraints +``` + ##### createDiv() ```ts static createDiv(classes, parent?): HTMLElement; ``` -Defined in: [utils.ts:118](https://github.com/adumesny/gridstack.js/blob/master/src/utils.ts#L118) +Defined in: [utils.ts:197](https://github.com/adumesny/gridstack.js/blob/master/src/utils.ts#L197) -create a div with the given classes +Create a div element with the specified CSS classes. ###### Parameters -| Parameter | Type | -| ------ | ------ | -| `classes` | `string`[] | -| `parent?` | `HTMLElement` | +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `classes` | `string`[] | array of CSS class names to add | +| `parent?` | `HTMLElement` | optional parent element to append the div to | ###### Returns `HTMLElement` +the created div element + +###### Example + +```ts +const div = Utils.createDiv(['grid-item', 'draggable']); +const nested = Utils.createDiv(['content'], parentDiv); +``` + ##### defaults() ```ts static defaults(target, ...sources): object; ``` -Defined in: [utils.ts:214](https://github.com/adumesny/gridstack.js/blob/master/src/utils.ts#L214) +Defined in: [utils.ts:412](https://github.com/adumesny/gridstack.js/blob/master/src/utils.ts#L412) -copies unset fields in target to use the given default sources values +Copy unset fields from source objects to target object (shallow merge with defaults). +Similar to Object.assign but only sets undefined/null fields. ###### Parameters -| Parameter | Type | -| ------ | ------ | -| `target` | `any` | -| ...`sources` | `any`[] | +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `target` | `any` | the object to copy defaults into | +| ...`sources` | `any`[] | one or more source objects to copy defaults from | ###### Returns `object` +the modified target object + +###### Example + +```ts +const config = { width: 100 }; +Utils.defaults(config, { width: 200, height: 50 }); +// config is now { width: 100, height: 50 } +``` + ##### find() ```ts static find(nodes, id): GridStackNode; ``` -Defined in: [utils.ts:173](https://github.com/adumesny/gridstack.js/blob/master/src/utils.ts#L173) +Defined in: [utils.ts:323](https://github.com/adumesny/gridstack.js/blob/master/src/utils.ts#L323) -find an item by id +Find a grid node by its ID. ###### Parameters -| Parameter | Type | -| ------ | ------ | -| `nodes` | [`GridStackNode`](#gridstacknode-2)[] | -| `id` | `string` | +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `nodes` | [`GridStackNode`](#gridstacknode-2)[] | array of nodes to search | +| `id` | `string` | the ID to search for | ###### Returns [`GridStackNode`](#gridstacknode-2) +the node with matching ID, or undefined if not found + +###### Example + +```ts +const node = Utils.find(nodes, 'widget-1'); +if (node) console.log('Found node at:', node.x, node.y); +``` + ##### getElement() ```ts static getElement(els, root): HTMLElement; ``` -Defined in: [utils.ts:87](https://github.com/adumesny/gridstack.js/blob/master/src/utils.ts#L87) +Defined in: [utils.ts:146](https://github.com/adumesny/gridstack.js/blob/master/src/utils.ts#L146) -convert a potential selector into actual single element. optional root which defaults to document (for shadow dom) +Convert a potential selector into a single HTML element. +Similar to getElements() but returns only the first match. ###### Parameters -| Parameter | Type | Default value | -| ------ | ------ | ------ | -| `els` | [`GridStackElement`](#gridstackelement) | `undefined` | -| `root` | `Document` \| `HTMLElement` | `document` | +| Parameter | Type | Default value | Description | +| ------ | ------ | ------ | ------ | +| `els` | [`GridStackElement`](#gridstackelement) | `undefined` | selector string or HTMLElement | +| `root` | `Document` \| `HTMLElement` | `document` | optional root element to search within (defaults to document) | ###### Returns `HTMLElement` +the first HTML element matching the selector, or null if not found + +###### Example + +```ts +const element = Utils.getElement('#myWidget'); +const first = Utils.getElement('.grid-item'); +``` + ##### getElements() ```ts static getElements(els, root): HTMLElement[]; ``` -Defined in: [utils.ts:64](https://github.com/adumesny/gridstack.js/blob/master/src/utils.ts#L64) +Defined in: [utils.ts:112](https://github.com/adumesny/gridstack.js/blob/master/src/utils.ts#L112) -convert a potential selector into actual list of html elements. optional root which defaults to document (for shadow dom) +Convert a potential selector into an actual list of HTML elements. +Supports CSS selectors, element references, and special ID handling. ###### Parameters -| Parameter | Type | Default value | -| ------ | ------ | ------ | -| `els` | [`GridStackElement`](#gridstackelement) | `undefined` | -| `root` | `Document` \| `HTMLElement` | `document` | +| Parameter | Type | Default value | Description | +| ------ | ------ | ------ | ------ | +| `els` | [`GridStackElement`](#gridstackelement) | `undefined` | selector string, HTMLElement, or array of elements | +| `root` | `Document` \| `HTMLElement` | `document` | optional root element to search within (defaults to document, useful for shadow DOM) | ###### Returns `HTMLElement`[] +array of HTML elements matching the selector + +###### Example + +```ts +const elements = Utils.getElements('.grid-item'); +const byId = Utils.getElements('#myWidget'); +const fromShadow = Utils.getElements('.item', shadowRoot); +``` + ##### getValuesFromTransformedElement() ```ts static getValuesFromTransformedElement(parent): DragTransform; ``` -Defined in: [utils.ts:529](https://github.com/adumesny/gridstack.js/blob/master/src/utils.ts#L529) +Defined in: [utils.ts:750](https://github.com/adumesny/gridstack.js/blob/master/src/utils.ts#L750) defines an element that is used to get the offset and scale from grid transforms returns the scale and offsets from said element @@ -2549,7 +3112,7 @@ returns the scale and offsets from said element static initEvent(e, info): T; ``` -Defined in: [utils.ts:486](https://github.com/adumesny/gridstack.js/blob/master/src/utils.ts#L486) +Defined in: [utils.ts:707](https://github.com/adumesny/gridstack.js/blob/master/src/utils.ts#L707) ###### Type Parameters @@ -2576,87 +3139,132 @@ Defined in: [utils.ts:486](https://github.com/adumesny/gridstack.js/blob/master/ static isIntercepted(a, b): boolean; ``` -Defined in: [utils.ts:133](https://github.com/adumesny/gridstack.js/blob/master/src/utils.ts#L133) +Defined in: [utils.ts:235](https://github.com/adumesny/gridstack.js/blob/master/src/utils.ts#L235) -returns true if a and b overlap +Check if two grid positions overlap/intersect. ###### Parameters -| Parameter | Type | -| ------ | ------ | -| `a` | [`GridStackPosition`](#gridstackposition) | -| `b` | [`GridStackPosition`](#gridstackposition) | +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `a` | [`GridStackPosition`](#gridstackposition) | first position with x, y, w, h properties | +| `b` | [`GridStackPosition`](#gridstackposition) | second position with x, y, w, h properties | ###### Returns `boolean` +true if the positions overlap + +###### Example + +```ts +const overlaps = Utils.isIntercepted( + {x: 0, y: 0, w: 2, h: 1}, + {x: 1, y: 0, w: 2, h: 1} +); // true - they overlap +``` + ##### isTouching() ```ts static isTouching(a, b): boolean; ``` -Defined in: [utils.ts:138](https://github.com/adumesny/gridstack.js/blob/master/src/utils.ts#L138) +Defined in: [utils.ts:252](https://github.com/adumesny/gridstack.js/blob/master/src/utils.ts#L252) -returns true if a and b touch edges or corners +Check if two grid positions are touching (edges or corners). ###### Parameters -| Parameter | Type | -| ------ | ------ | -| `a` | [`GridStackPosition`](#gridstackposition) | -| `b` | [`GridStackPosition`](#gridstackposition) | +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `a` | [`GridStackPosition`](#gridstackposition) | first position | +| `b` | [`GridStackPosition`](#gridstackposition) | second position | ###### Returns `boolean` +true if the positions are touching + +###### Example + +```ts +const touching = Utils.isTouching( + {x: 0, y: 0, w: 2, h: 1}, + {x: 2, y: 0, w: 1, h: 1} +); // true - they share an edge +``` + ##### lazyLoad() ```ts static lazyLoad(n): boolean; ``` -Defined in: [utils.ts:113](https://github.com/adumesny/gridstack.js/blob/master/src/utils.ts#L113) +Defined in: [utils.ts:182](https://github.com/adumesny/gridstack.js/blob/master/src/utils.ts#L182) -true if widget (or grid) makes this item lazyLoad +Check if a widget should be lazy loaded based on node or grid settings. ###### Parameters -| Parameter | Type | -| ------ | ------ | -| `n` | [`GridStackNode`](#gridstacknode-2) | +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `n` | [`GridStackNode`](#gridstacknode-2) | the grid node to check | ###### Returns `boolean` +true if the item should be lazy loaded + +###### Example + +```ts +if (Utils.lazyLoad(node)) { + // Set up intersection observer for lazy loading +} +``` + ##### parseHeight() ```ts static parseHeight(val): HeightData; ``` -Defined in: [utils.ts:193](https://github.com/adumesny/gridstack.js/blob/master/src/utils.ts#L193) +Defined in: [utils.ts:379](https://github.com/adumesny/gridstack.js/blob/master/src/utils.ts#L379) + +Parse a height value with units into numeric value and unit string. +Supports px, em, rem, vh, vw, %, cm, mm units. ###### Parameters -| Parameter | Type | -| ------ | ------ | -| `val` | [`numberOrString`](#numberorstring) | +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `val` | [`numberOrString`](#numberorstring) | height value as number or string with units | ###### Returns [`HeightData`](#heightdata) +object with h (height) and unit properties + +###### Example + +```ts +Utils.parseHeight('100px'); // {h: 100, unit: 'px'} +Utils.parseHeight('2rem'); // {h: 2, unit: 'rem'} +Utils.parseHeight(50); // {h: 50, unit: 'px'} +``` + ##### removeInternalAndSame() ```ts static removeInternalAndSame(a, b): void; ``` -Defined in: [utils.ts:273](https://github.com/adumesny/gridstack.js/blob/master/src/utils.ts#L273) +Defined in: [utils.ts:494](https://github.com/adumesny/gridstack.js/blob/master/src/utils.ts#L494) removes field from the first object if same as the second objects (like diffing) and internal '_' for saving @@ -2677,7 +3285,7 @@ removes field from the first object if same as the second objects (like diffing) static removeInternalForSave(n, removeEl): void; ``` -Defined in: [utils.ts:288](https://github.com/adumesny/gridstack.js/blob/master/src/utils.ts#L288) +Defined in: [utils.ts:509](https://github.com/adumesny/gridstack.js/blob/master/src/utils.ts#L509) removes internal fields '_' and default values for saving @@ -2698,7 +3306,7 @@ removes internal fields '_' and default values for saving static removePositioningStyles(el): void; ``` -Defined in: [utils.ts:321](https://github.com/adumesny/gridstack.js/blob/master/src/utils.ts#L321) +Defined in: [utils.ts:542](https://github.com/adumesny/gridstack.js/blob/master/src/utils.ts#L542) ###### Parameters @@ -2716,28 +3324,38 @@ Defined in: [utils.ts:321](https://github.com/adumesny/gridstack.js/blob/master/ static same(a, b): boolean; ``` -Defined in: [utils.ts:232](https://github.com/adumesny/gridstack.js/blob/master/src/utils.ts#L232) +Defined in: [utils.ts:441](https://github.com/adumesny/gridstack.js/blob/master/src/utils.ts#L441) -given 2 objects return true if they have the same values. Checks for Object {} having same fields and values (just 1 level down) +Compare two objects for equality (shallow comparison). +Checks if objects have the same fields and values at one level deep. ###### Parameters -| Parameter | Type | -| ------ | ------ | -| `a` | `unknown` | -| `b` | `unknown` | +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `a` | `unknown` | first object to compare | +| `b` | `unknown` | second object to compare | ###### Returns `boolean` +true if objects have the same values + +###### Example + +```ts +Utils.same({x: 1, y: 2}, {x: 1, y: 2}); // true +Utils.same({x: 1}, {x: 1, y: 2}); // false +``` + ##### samePos() ```ts static samePos(a, b): boolean; ``` -Defined in: [utils.ts:259](https://github.com/adumesny/gridstack.js/blob/master/src/utils.ts#L259) +Defined in: [utils.ts:480](https://github.com/adumesny/gridstack.js/blob/master/src/utils.ts#L480) true if a and b has same size & position @@ -2758,7 +3376,7 @@ true if a and b has same size & position static sanitizeMinMax(node): void; ``` -Defined in: [utils.ts:264](https://github.com/adumesny/gridstack.js/blob/master/src/utils.ts#L264) +Defined in: [utils.ts:485](https://github.com/adumesny/gridstack.js/blob/master/src/utils.ts#L485) given a node, makes sure it's min/max are valid @@ -2778,21 +3396,31 @@ given a node, makes sure it's min/max are valid static shouldSizeToContent(n, strict): boolean; ``` -Defined in: [utils.ts:126](https://github.com/adumesny/gridstack.js/blob/master/src/utils.ts#L126) +Defined in: [utils.ts:216](https://github.com/adumesny/gridstack.js/blob/master/src/utils.ts#L216) -true if we should resize to content. strict=true when only 'sizeToContent:true' and not a number which lets user adjust +Check if a widget should resize to fit its content. ###### Parameters -| Parameter | Type | Default value | -| ------ | ------ | ------ | -| `n` | [`GridStackNode`](#gridstacknode-2) | `undefined` | -| `strict` | `boolean` | `false` | +| Parameter | Type | Default value | Description | +| ------ | ------ | ------ | ------ | +| `n` | [`GridStackNode`](#gridstacknode-2) | `undefined` | the grid node to check (can be undefined) | +| `strict` | `boolean` | `false` | if true, only returns true for explicit sizeToContent:true (not numbers) | ###### Returns `boolean` +true if the widget should resize to content + +###### Example + +```ts +if (Utils.shouldSizeToContent(node)) { + // Trigger content-based resizing +} +``` + ##### simulateMouseEvent() ```ts @@ -2802,7 +3430,7 @@ static simulateMouseEvent( target?): void; ``` -Defined in: [utils.ts:502](https://github.com/adumesny/gridstack.js/blob/master/src/utils.ts#L502) +Defined in: [utils.ts:723](https://github.com/adumesny/gridstack.js/blob/master/src/utils.ts#L723) copies the MouseEvent (or convert Touch) properties and sends it as another event to the given target @@ -2824,21 +3452,30 @@ copies the MouseEvent (or convert Touch) properties and sends it as another even static sort(nodes, dir): GridStackNode[]; ``` -Defined in: [utils.ts:163](https://github.com/adumesny/gridstack.js/blob/master/src/utils.ts#L163) +Defined in: [utils.ts:303](https://github.com/adumesny/gridstack.js/blob/master/src/utils.ts#L303) -Sorts array of nodes +Sort an array of grid nodes by position (y first, then x). ###### Parameters | Parameter | Type | Default value | Description | | ------ | ------ | ------ | ------ | -| `nodes` | [`GridStackNode`](#gridstacknode-2)[] | `undefined` | array to sort | -| `dir` | `-1` \| `1` | `1` | 1 for ascending, -1 for descending (optional) | +| `nodes` | [`GridStackNode`](#gridstacknode-2)[] | `undefined` | array of nodes to sort | +| `dir` | `-1` \| `1` | `1` | sort direction: 1 for ascending (top-left first), -1 for descending | ###### Returns [`GridStackNode`](#gridstacknode-2)[] +the sorted array (modifies original) + +###### Example + +```ts +const sorted = Utils.sort(nodes); // Sort top-left to bottom-right +const reverse = Utils.sort(nodes, -1); // Sort bottom-right to top-left +``` + ##### swap() ```ts @@ -2848,7 +3485,7 @@ static swap( b): void; ``` -Defined in: [utils.ts:553](https://github.com/adumesny/gridstack.js/blob/master/src/utils.ts#L553) +Defined in: [utils.ts:774](https://github.com/adumesny/gridstack.js/blob/master/src/utils.ts#L774) swap the given object 2 field values @@ -2870,7 +3507,7 @@ swap the given object 2 field values static throttle(func, delay): () => void; ``` -Defined in: [utils.ts:311](https://github.com/adumesny/gridstack.js/blob/master/src/utils.ts#L311) +Defined in: [utils.ts:532](https://github.com/adumesny/gridstack.js/blob/master/src/utils.ts#L532) delay calling the given function for given delay, preventing new calls from happening while waiting @@ -2897,42 +3534,68 @@ delay calling the given function for given delay, preventing new calls from happ static toBool(v): boolean; ``` -Defined in: [utils.ts:178](https://github.com/adumesny/gridstack.js/blob/master/src/utils.ts#L178) +Defined in: [utils.ts:341](https://github.com/adumesny/gridstack.js/blob/master/src/utils.ts#L341) + +Convert various value types to boolean. +Handles strings like 'false', 'no', '0' as false. ###### Parameters -| Parameter | Type | -| ------ | ------ | -| `v` | `unknown` | +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `v` | `unknown` | value to convert | ###### Returns `boolean` +boolean representation + +###### Example + +```ts +Utils.toBool('true'); // true +Utils.toBool('false'); // false +Utils.toBool('no'); // false +Utils.toBool('1'); // true +``` + ##### toNumber() ```ts static toNumber(value): number; ``` -Defined in: [utils.ts:189](https://github.com/adumesny/gridstack.js/blob/master/src/utils.ts#L189) +Defined in: [utils.ts:363](https://github.com/adumesny/gridstack.js/blob/master/src/utils.ts#L363) + +Convert a string value to a number, handling null and empty strings. ###### Parameters -| Parameter | Type | -| ------ | ------ | -| `value` | `string` | +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `value` | `string` | string or null value to convert | ###### Returns `number` +number value, or undefined for null/empty strings + +###### Example + +```ts +Utils.toNumber('42'); // 42 +Utils.toNumber(''); // undefined +Utils.toNumber(null); // undefined +``` + ## Interfaces ### GridStackOptions -Defined in: [types.ts:110](https://github.com/adumesny/gridstack.js/blob/master/src/types.ts#L110) +Defined in: [types.ts:184](https://github.com/adumesny/gridstack.js/blob/master/src/types.ts#L184) Defines the options for a Grid @@ -2940,55 +3603,59 @@ Defines the options for a Grid | Property | Type | Description | Defined in | | ------ | ------ | ------ | ------ | -| `acceptWidgets?` | `string` \| `boolean` \| (`element`) => `boolean` | accept widgets dragged from other grids or from outside (default: `false`). Can be: `true` (uses `'.grid-stack-item'` class filter) or `false`, string for explicit class name, function returning a boolean. See [example](http://gridstack.github.io/gridstack.js/demo/two.html) | [types.ts:117](https://github.com/adumesny/gridstack.js/blob/master/src/types.ts#L117) | -| `alwaysShowResizeHandle?` | `boolean` \| `"mobile"` | possible values (default: `mobile`) - does not apply to non-resizable widgets `false` the resizing handles are only shown while hovering over a widget `true` the resizing handles are always shown 'mobile' if running on a mobile device, default to `true` (since there is no hovering per say), else `false`. See [example](http://gridstack.github.io/gridstack.js/demo/mobile.html) | [types.ts:124](https://github.com/adumesny/gridstack.js/blob/master/src/types.ts#L124) | -| `animate?` | `boolean` | turns animation on (default?: true) | [types.ts:127](https://github.com/adumesny/gridstack.js/blob/master/src/types.ts#L127) | -| `auto?` | `boolean` | if false gridstack will not initialize existing items (default?: true) | [types.ts:130](https://github.com/adumesny/gridstack.js/blob/master/src/types.ts#L130) | -| `cellHeight?` | [`numberOrString`](#numberorstring) | one cell height (default?: 'auto'). Can be: an integer (px) a string (ex: '100px', '10em', '10rem'). Note: % doesn't work right - see demo/cell-height.html 0, in which case the library will not generate styles for rows. Everything must be defined in your own CSS files. 'auto' - height will be calculated for square cells (width / column) and updated live as you resize the window - also see `cellHeightThrottle` 'initial' - similar to 'auto' (start at square cells) but stay that size during window resizing. | [types.ts:140](https://github.com/adumesny/gridstack.js/blob/master/src/types.ts#L140) | -| `cellHeightThrottle?` | `number` | throttle time delay (in ms) used when cellHeight='auto' to improve performance vs usability (default?: 100). A value of 0 will make it instant at a cost of re-creating the CSS file at ever window resize event! | [types.ts:145](https://github.com/adumesny/gridstack.js/blob/master/src/types.ts#L145) | -| `cellHeightUnit?` | `string` | (internal) unit for cellHeight (default? 'px') which is set when a string cellHeight with a unit is passed (ex: '10rem') | [types.ts:148](https://github.com/adumesny/gridstack.js/blob/master/src/types.ts#L148) | -| `children?` | [`GridStackWidget`](#gridstackwidget)[] | list of children item to create when calling load() or addGrid() | [types.ts:151](https://github.com/adumesny/gridstack.js/blob/master/src/types.ts#L151) | -| `class?` | `string` | additional class on top of '.grid-stack' (which is required for our CSS) to differentiate this instance. Note: only used by addGrid(), else your element should have the needed class | [types.ts:164](https://github.com/adumesny/gridstack.js/blob/master/src/types.ts#L164) | -| `column?` | `number` \| `"auto"` | number of columns (default?: 12). Note: IF you change this, CSS also have to change. See https://github.com/gridstack/gridstack.js#change-grid-columns. Note: for nested grids, it is recommended to use 'auto' which will always match the container grid-item current width (in column) to keep inside and outside items always the same. flag is NOT supported for regular non-nested grids. | [types.ts:157](https://github.com/adumesny/gridstack.js/blob/master/src/types.ts#L157) | -| `columnOpts?` | [`Responsive`](#responsive) | responsive column layout for width:column behavior | [types.ts:160](https://github.com/adumesny/gridstack.js/blob/master/src/types.ts#L160) | -| `disableDrag?` | `boolean` | disallows dragging of widgets (default?: false) | [types.ts:167](https://github.com/adumesny/gridstack.js/blob/master/src/types.ts#L167) | -| `disableResize?` | `boolean` | disallows resizing of widgets (default?: false). | [types.ts:170](https://github.com/adumesny/gridstack.js/blob/master/src/types.ts#L170) | -| `draggable?` | [`DDDragOpt`](#dddragopt) | allows to override UI draggable options. (default?: { handle?: '.grid-stack-item-content', appendTo?: 'body' }) | [types.ts:173](https://github.com/adumesny/gridstack.js/blob/master/src/types.ts#L173) | -| `engineClass?` | *typeof* [`GridStackEngine`](#gridstackengine-2) | the type of engine to create (so you can subclass) default to GridStackEngine | [types.ts:179](https://github.com/adumesny/gridstack.js/blob/master/src/types.ts#L179) | -| `float?` | `boolean` | enable floating widgets (default?: false) See example (http://gridstack.github.io/gridstack.js/demo/float.html) | [types.ts:182](https://github.com/adumesny/gridstack.js/blob/master/src/types.ts#L182) | -| `handle?` | `string` | draggable handle selector (default?: '.grid-stack-item-content') | [types.ts:185](https://github.com/adumesny/gridstack.js/blob/master/src/types.ts#L185) | -| `handleClass?` | `string` | draggable handle class (e.g. 'grid-stack-item-content'). If set 'handle' is ignored (default?: null) | [types.ts:188](https://github.com/adumesny/gridstack.js/blob/master/src/types.ts#L188) | -| `itemClass?` | `string` | additional widget class (default?: 'grid-stack-item') | [types.ts:191](https://github.com/adumesny/gridstack.js/blob/master/src/types.ts#L191) | -| `layout?` | [`ColumnOptions`](#columnoptions) | re-layout mode when we're a subgrid and we are being resized. default to 'list' | [types.ts:194](https://github.com/adumesny/gridstack.js/blob/master/src/types.ts#L194) | -| `lazyLoad?` | `boolean` | true when widgets are only created when they scroll into view (visible) | [types.ts:197](https://github.com/adumesny/gridstack.js/blob/master/src/types.ts#L197) | -| `margin?` | [`numberOrString`](#numberorstring) | gap between grid item and content (default?: 10). This will set all 4 sides and support the CSS formats below an integer (px) a string with possible units (ex: '2em', '20px', '2rem') string with space separated values (ex: '5px 10px 0 20px' for all 4 sides, or '5em 10em' for top/bottom and left/right pairs like CSS). Note: all sides must have same units (last one wins, default px) | [types.ts:206](https://github.com/adumesny/gridstack.js/blob/master/src/types.ts#L206) | -| `marginBottom?` | [`numberOrString`](#numberorstring) | - | [types.ts:211](https://github.com/adumesny/gridstack.js/blob/master/src/types.ts#L211) | -| `marginLeft?` | [`numberOrString`](#numberorstring) | - | [types.ts:212](https://github.com/adumesny/gridstack.js/blob/master/src/types.ts#L212) | -| `marginRight?` | [`numberOrString`](#numberorstring) | - | [types.ts:210](https://github.com/adumesny/gridstack.js/blob/master/src/types.ts#L210) | -| `marginTop?` | [`numberOrString`](#numberorstring) | OLD way to optionally set each side - use margin: '5px 10px 0 20px' instead. Used internally to store each side. | [types.ts:209](https://github.com/adumesny/gridstack.js/blob/master/src/types.ts#L209) | -| `marginUnit?` | `string` | (internal) unit for margin (default? 'px') set when `margin` is set as string with unit (ex: 2rem') | [types.ts:215](https://github.com/adumesny/gridstack.js/blob/master/src/types.ts#L215) | -| `maxRow?` | `number` | maximum rows amount. Default? is 0 which means no maximum rows | [types.ts:218](https://github.com/adumesny/gridstack.js/blob/master/src/types.ts#L218) | -| `minRow?` | `number` | minimum rows amount which is handy to prevent grid from collapsing when empty. Default is `0`. When no set the `min-height` CSS attribute on the grid div (in pixels) can be used, which will round to the closest row. | [types.ts:223](https://github.com/adumesny/gridstack.js/blob/master/src/types.ts#L223) | -| `nonce?` | `string` | If you are using a nonce-based Content Security Policy, pass your nonce here and GridStack will add it to the