custom column re-layout callback

* fix for #1332
* in addition to some pre-built method, you can now have your own callback that is geven the column count and nodes for you to modify
* rest of the code will validate and place those items accordingly. you only need to focus on x,y,w,h locations.
* column.html was updated to show usage

Author: adumesny

demo/column.html

@@ -16,11 +16,12 @@ <h1>column() grid demo</h1>
     <div><span>Number of Columns:</span> <span id="column-text">12</span></div>
     <div>
       <label>Choose re-layout:</label>
-      <select onchange="layout = this.value">
+      <select onchange="setLayout(this.value)">
         <option value="moveScale">move + scale</option>
         <option value="move">move</option>
         <option value="scale">scale</option>
         <option value="none">none</option>
+        <option value="custom">custom</option>
       </select>
     </div>
     <div>
@@ -91,6 +92,17 @@ <h1>column() grid demo</h1>
       grid.column(1, layout);
       text.innerHTML = dom ? '1 DOM' : '1';
     }
+    // dummy test method that moves items to the right each new layout... grid engine will validate those values (can't be neg or out of bounds) anyway...
+    function columnLayout(column, oldColumn, nodes, oldNodes) {
+      oldNodes.forEach(n => {
+        n.x = n.x + 1;
+        nodes.push(n);
+      });
+      oldNodes.length = 0;
+    }
+    function setLayout(name) {
+      layout = name === 'custom' ? this.columnLayout : name;
+    }
 
   </script>
 </body>

doc/CHANGES.md

@@ -46,7 +46,8 @@ Also fixed JQ draggable warning if not initialized first [858](https://github.co
 - add `addWidget(opt)` now handles just passing a `GridStackWidget` which creates the default divs, simplifying your code. Old API still supported.
 - add `save(saveContent = true)` now lets you optionally save the HTML content in the node property, with load() restoring it [1418](https://github.com/gridstack/gridstack.js/issues/1418)
 - add `GridStackWidget.content` now lets you add any HTML content when calling `load()/save()` or `addWidget()` [1418](https://github.com/gridstack/gridstack.js/issues/1418)
-- add `LayoutOptions` to `column()` for multiple re-layout options, including 'none' that will preserve the x and width, until out of bound/overlap [1338](https://github.com/gridstack/gridstack.js/issues/1338)
+- add `ColumnOptions` to `column(n, options)` for multiple re-layout options, including 'none' that will preserve the x and width, until out of bound/overlap [1338](https://github.com/gridstack/gridstack.js/issues/1338)
+including a custom function for you to create the new layout [1332](https://github.com/gridstack/gridstack.js/issues/1332)
 
 ## 2.0.2 (2020-10-05)
 

doc/README.md

@@ -27,7 +27,7 @@ gridstack.js API
   - [cellHeight(val: number, update = true)](#cellheightval-number-update--true)
   - [cellWidth()](#cellwidth)
   - [commit()](#commit)
-  - [column(column: number, layout: LayoutOptions = 'moveScale')](#columncolumn-number-layout-layoutoptions--movescale)
+  - [column(column: number, layout: ColumnOptions = 'moveScale')](#columncolumn-number-layout-columnoptions--movescale)
   - [destroy([removeDOM])](#destroyremovedom)
   - [disable()](#disable)
   - [enable()](#enable)
@@ -298,7 +298,7 @@ Gets current cell width (grid width / # of columns).
 
 Ends batch updates. Updates DOM nodes. You must call it after `batchUpdate()`.
 
-### column(column: number, layout: LayoutOptions = 'moveScale')
+### column(column: number, layout: ColumnOptions = 'moveScale')
 
 set/get 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.
@@ -308,7 +308,9 @@ else you will need to generate correct CSS (see https://github.com/gridstack/gri
 - `column` - Integer > 0 (default 12), if missing it will return the current count instead.
 - `layout` - specify the type of re-layout that will happen (position, size, etc...).
 Note: items will never be outside of the current column boundaries. default ('moveScale'). Ignored for 1 column.
-Possible values: 'moveScale' | 'move' | 'scale' | 'none'
+Possible values: 'moveScale' | 'move' | 'scale' | 'none' | (column: number, oldColumn: number, nodes: GridStackNode[], oldNodes: GridStackNode[]) => void.
+A custom function option takes new/old column count, and array of new/old positions.
+Note: new list may be partially already filled if we have a partial cache of the layout at that size (items were added later). If complete cache is present this won't get called at all.
 
 ### destroy([removeDOM])
 

src/gridstack-engine.ts

@@ -7,7 +7,7 @@
 */
 
 import { Utils, obsolete } from './utils';
-import { GridStackNode, LayoutOptions } from './types';
+import { GridStackNode, ColumnOptions } from './types';
 
 export type onChangeCB = (nodes: GridStackNode[], removeDOM?: boolean) => void;
 
@@ -537,7 +537,7 @@ export class GridStackEngine {
    * @param layout specify the type of re-layout that will happen (position, size, etc...).
    * Note: items will never be outside of the current column boundaries. default (moveScale). Ignored for 1 column
    */
-  public updateNodeWidths(oldColumn: number, column: number, nodes: GridStackNode[], layout: LayoutOptions = 'moveScale'): GridStackEngine {
+  public updateNodeWidths(oldColumn: number, column: number, nodes: GridStackNode[], layout: ColumnOptions = 'moveScale'): GridStackEngine {
     if (!this.nodes.length || oldColumn === column) { return this }
 
     // cache the current layout in case they want to go back (like 12 -> 1 -> 12) as it requires original data
@@ -584,27 +584,33 @@ export class GridStackEngine {
     // if we found cache re-use those nodes that are still current
     let newNodes: GridStackNode[] = [];
     cacheNodes.forEach(cacheNode => {
-      let j = nodes.findIndex(n => n && n._id === cacheNode._id);
+      let j = nodes.findIndex(n => n._id === cacheNode._id);
       if (j !== -1) {
         // still current, use cache info positions
         nodes[j].x = cacheNode.x;
         nodes[j].y = cacheNode.y;
         nodes[j].width = cacheNode.width;
         newNodes.push(nodes[j]);
-        nodes[j] = null; // erase it so we know what's left
+        nodes.splice(j, 1);
       }
     });
     // ...and add any extra non-cached ones
-    let ratio = column / oldColumn;
-    let move = layout === 'move' || layout === 'moveScale';
-    let scale = layout === 'scale' || layout === 'moveScale';
-    nodes.forEach(node => {
-      if (!node) return this;
-      node.x = (column === 1 ? 0 : (move ? Math.round(node.x * ratio) : Math.min(node.x, column - 1)));
-      node.width = ((column === 1 || oldColumn === 1) ? 1 :
-        scale ? (Math.round(node.width * ratio) || 1) : (Math.min(node.width, column)));
-      newNodes.push(node);
-    });
+    if (nodes.length) {
+      if (typeof layout === 'function') {
+        layout(column, oldColumn, newNodes, nodes);
+      } else {
+        let ratio = column / oldColumn;
+        let move = (layout === 'move' || layout === 'moveScale');
+        let scale = (layout === 'scale' || layout === 'moveScale');
+        nodes.forEach(node => {
+          node.x = (column === 1 ? 0 : (move ? Math.round(node.x * ratio) : Math.min(node.x, column - 1)));
+          node.width = ((column === 1 || oldColumn === 1) ? 1 :
+            scale ? (Math.round(node.width * ratio) || 1) : (Math.min(node.width, column)));
+          newNodes.push(node);
+        });
+        nodes = [];
+      }
+    }
 
     // finally re-layout them in reverse order (to get correct placement)
     newNodes = Utils.sort(newNodes, -1, column);

src/gridstack.ts

@@ -8,7 +8,7 @@
 
 import { GridStackEngine } from './gridstack-engine';
 import { obsoleteOpts, obsoleteOptsDel, obsoleteAttr, obsolete, Utils } from './utils';
-import { GridItemHTMLElement, GridStackWidget, GridStackNode, GridStackOptions, numberOrString, LayoutOptions } from './types';
+import { GridItemHTMLElement, GridStackWidget, GridStackNode, GridStackOptions, numberOrString, ColumnOptions } from './types';
 import { GridStackDD } from './gridstack-dd';
 
 // export all dependent file as well to make it easier for users to just import the main file
@@ -516,7 +516,7 @@ export class GridStack {
    * @param layout specify the type of re-layout that will happen (position, size, etc...).
    * Note: items will never be outside of the current column boundaries. default (moveScale). Ignored for 1 column
    */
-  public column(column: number, layout: LayoutOptions = 'moveScale'): GridStack {
+  public column(column: number, layout: ColumnOptions = 'moveScale'): GridStack {
     if (this.opts.column === column) { return this; }
     let oldColumn = this.opts.column;
 

src/types.ts

@@ -10,8 +10,12 @@ import { GridStack } from './gridstack';
 import { GridStackDD } from './gridstack-dd';
 
 
-/** different layout options when changing # of columns and other re-layouts */
-export type LayoutOptions = 'moveScale' | 'move' | 'scale' | 'none';
+/** different layout options when changing # of columns,
+ * including a custom function that takes new/old column count, and array of new/old positions
+ * Note: new list may be partially already filled if we have a cache of the layout at that size and new items were added later.
+ */
+export type ColumnOptions = 'moveScale' | 'move' | 'scale' | 'none' |
+  ((column: number, oldColumn: number, nodes: GridStackNode[], oldNodes: GridStackNode[]) => void);
 
 export type numberOrString = number | string;
 export interface GridItemHTMLElement extends HTMLElement {