column(n) re-layout options to not scale/move

* fix for #1338 and likely #1332
* add `LayoutOptions` to `column()` for multiple re-layout options, including 'none' that will preserve the x and width, until out of bound/overlap
* Possible values: 'moveScale' | 'move' | 'scale' | 'none'
* update demos to have dropdown choices, and test cases

Author: adumesny

README.md

@@ -344,12 +344,13 @@ grid.on('added', function(e, items) {/* items contains info */});
 var grid = el.gridstack; // where el = document.querySelector('.grid-stack') or other ways...
 ```
 Other changes
-```
+
+```js
 `GridStackUI` --> `GridStack`
 `GridStackUI.GridStackEngine` --> `GridStack.Engine`
-`grid.container` (jquery grid wrapper) --> `grid.el` (grid DOM element)
+`grid.container` (jquery grid wrapper) --> `grid.el` // (grid DOM element)
 `grid.grid` (GridStackEngine) --> `grid.engine`
-`grid.setColumn(N)` --> `grid.column(N)` and new `grid.column()` to get value, old API still supported though
+`grid.setColumn(N)` --> `grid.column(N)` and `grid.column()` // to get value, old API still supported though
 ```
 
 Recommend looking at the [many samples](./demo) for more code examples.

demo/column.html

@@ -14,6 +14,15 @@
   <div class="container-fluid">
     <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">
+        <option value="moveScale">move + scale</option>
+        <option value="move">move</option>
+        <option value="scale">scale</option>
+        <option value="none">none</option>
+      </select>
+    </div>
     <div>
       <a onClick="addWidget()" class="btn btn-primary" href="#">Add Widget</a>
       <a onClick="setOneColumn(false)" class="btn btn-primary" href="#">1 Column</a>
@@ -33,6 +42,7 @@ <h1>column() grid demo</h1>
   <script type="text/javascript">
     let grid = GridStack.init({float: true});
     let text = document.querySelector('#column-text');
+    let layout = 'moveScale';
 
     grid.on('added removed change', function(e, items) {
       let str = '';
@@ -73,12 +83,12 @@ <h1>column() grid demo</h1>
     };
 
     function column(n) {
-      grid.column(n);
+      grid.column(n, layout);
       text.innerHTML = n;
     }
     function setOneColumn(dom) {
       grid.opts.oneColumnModeDomSort = dom;
-      grid.column(1);
+      grid.column(1, layout);
       text.innerHTML = dom ? '1 DOM' : '1';
     }
 

demo/responsive.html

@@ -13,6 +13,15 @@ <h1>Responsive grid demo</h1>
     <div>
       <span>Number of Columns:</span> <span id="column-text"></span>
     </div>
+    <div>
+      <label>Choose re-layout:</label>
+      <select onchange="layout = this.value">
+        <option value="moveScale">move + scale</option>
+        <option value="move">move</option>
+        <option value="scale">scale</option>
+        <option value="none">none</option>
+      </select>
+    </div>
     <br/>
     <div class="grid-stack">
     </div>
@@ -23,23 +32,24 @@ <h1>Responsive grid demo</h1>
       disableOneColumnMode: true, // will manually do 1 column
       float: true });
     let text = document.querySelector('#column-text');
+    let layout = 'moveScale';
 
     function resizeGrid() {
       let width = document.body.clientWidth;
       if (width < 700) {
-        grid.column(1);
+        grid.column(1, layout);
         text.innerHTML = 1;
       } else if (width < 850) {
-        grid.column(3);
+        grid.column(3, layout);
         text.innerHTML = 3;
       } else if (width < 950) {
-        grid.column(6);
+        grid.column(6, layout);
         text.innerHTML = 6;
       } else if (width < 1100) {
-        grid.column(8);
+        grid.column(8, layout);
         text.innerHTML = 8;
       } else {
-        grid.column(12);
+        grid.column(12, layout);
         text.innerHTML = 12;
       }
     };

doc/CHANGES.md

@@ -46,6 +46,7 @@ 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)
 
 ## 2.0.2 (2020-10-05)
 

doc/README.md

@@ -21,13 +21,13 @@ gridstack.js API
   - [resizestart(event, el)](#resizestartevent-el)
   - [resizestop(event, el)](#resizestopevent-el)
 - [API](#api)
-  - [addWidget(el, [options])](#addwidgetel-options)
+  - [addWidget(el?: GridStackWidget | GridStackElement, options?: GridStackWidget)](#addwidgetel-gridstackwidget--gridstackelement-options-gridstackwidget)
   - [batchUpdate()](#batchupdate)
   - [compact()](#compact)
   - [cellHeight(val: number, update = true)](#cellheightval-number-update--true)
   - [cellWidth()](#cellwidth)
   - [commit()](#commit)
-  - [column(column, doNotPropagate)](#columncolumn-donotpropagate)
+  - [column(column: number, layout: LayoutOptions = 'moveScale')](#columncolumn-number-layout-layoutoptions--movescale)
   - [destroy([removeDOM])](#destroyremovedom)
   - [disable()](#disable)
   - [enable()](#enable)
@@ -53,7 +53,7 @@ gridstack.js API
   - [removeAll(removeDOM = true)](#removeallremovedom--true)
   - [resize(el, width, height)](#resizeel-width-height)
   - [resizable(el, val)](#resizableel-val)
-  - [save(): GridStackWidget[]](#save-gridstackwidget)
+  - [save(saveContent = true): GridStackWidget[]](#savesavecontent--true-gridstackwidget)
   - [setAnimation(doAnimate)](#setanimationdoanimate)
   - [setStatic(staticValue)](#setstaticstaticvalue)
   - [update(el, x, y, width, height)](#updateel-x-y-width-height)
@@ -298,15 +298,17 @@ Gets current cell width (grid width / # of columns).
 
 Ends batch updates. Updates DOM nodes. You must call it after `batchUpdate()`.
 
-### column(column, doNotPropagate)
+### column(column: number, layout: LayoutOptions = '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.
 Requires `gridstack-extra.css` or `gridstack-extra.min.css` for [2-11],
 else you will need to generate correct CSS (see https://github.com/gridstack/gridstack.js#change-grid-columns)
 
 - `column` - Integer > 0 (default 12), if missing it will return the current count instead.
-- `doNotPropagate` - if true existing widgets will not be updated during a set.
+- `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'
 
 ### destroy([removeDOM])
 

spec/gridstack-spec.ts

@@ -252,12 +252,7 @@ describe('gridstack', function() {
       };
       let grid = GridStack.init(options);
       let items = $('.grid-stack-item');
-      grid.column(10, false);
-      expect(grid.getColumn()).toBe(10);
-      for (let j = 0; j < items.length; j++) {
-        expect(parseInt($(items[j]).attr('data-gs-y'), 10)).toBe(0);
-      }
-      grid.column(9, true);
+      grid.column(9);
       expect(grid.getColumn()).toBe(9);
       for (let j = 0; j < items.length; j++) {
         expect(parseInt($(items[j]).attr('data-gs-y'), 10)).toBe(0);
@@ -268,7 +263,28 @@ describe('gridstack', function() {
         expect(parseInt($(items[j]).attr('data-gs-y'), 10)).toBe(0);
       }
     });
-    it('should change column number and relayout items', function() {
+    it('no sizing, no moving', function() {
+      let grid = GridStack.init({column: 12});
+      let items = $('.grid-stack-item');
+      grid.column(8, 'none');
+      expect(grid.getColumn()).toBe(8);
+      for (let j = 0; j < items.length; j++) {
+        expect(parseInt($(items[j]).attr('data-gs-width'), 10)).toBe(4);
+        expect(parseInt($(items[j]).attr('data-gs-y'), 10)).toBe(0);
+      }
+    });
+    it('no sizing, but moving down', function() {
+      let grid = GridStack.init({column: 12});
+      let items = $('.grid-stack-item');
+      grid.column(7, 'none');
+      expect(grid.getColumn()).toBe(7);
+      for (let j = 0; j < items.length; j++) {
+        expect(parseInt($(items[j]).attr('data-gs-width'), 10)).toBe(4);
+      }
+      expect(parseInt($(items[0]).attr('data-gs-y'), 10)).toBe(0);
+      expect(parseInt($(items[1]).attr('data-gs-y'), 10)).toBe(2);
+    });
+    it('should change column number and re-layout items', function() {
       let options = {
         column: 12,
         float: true

src/gridstack-engine.ts

@@ -7,7 +7,7 @@
 */
 
 import { Utils, obsolete } from './utils';
-import { GridStackNode, GridStackWidget } from './types';
+import { GridStackNode, LayoutOptions } from './types';
 
 export type onChangeCB = (nodes: GridStackNode[], removeDOM?: boolean) => void;
 
@@ -534,8 +534,10 @@ export class GridStackEngine {
    * @param oldColumn previous number of columns
    * @param column  new column number
    * @param nodes different sorted list (ex: DOM order) instead of current list
+   * @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[]): GridStackEngine {
+  public updateNodeWidths(oldColumn: number, column: number, nodes: GridStackNode[], layout: LayoutOptions = '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
@@ -594,10 +596,13 @@ export class GridStackEngine {
     });
     // ...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 : Math.round(node.x * ratio));
-      node.width = ((column === 1 || oldColumn === 1) ? 1 : (Math.round(node.width * ratio) || 1));
+      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);
     });
 

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 } from './types';
+import { GridItemHTMLElement, GridStackWidget, GridStackNode, GridStackOptions, numberOrString, LayoutOptions } 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
@@ -510,12 +510,13 @@ export class GridStack {
   /**
    * 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 [1-11],
+   * Requires `gridstack-extra.css` or `gridstack-extra.min.css` for [2-11],
    * else you will need to generate correct CSS (see https://github.com/gridstack/gridstack.js#change-grid-columns)
    * @param column - Integer > 0 (default 12).
-   * @param doNotPropagate if true existing widgets will not be updated (optional)
+   * @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, doNotPropagate?: boolean): GridStack {
+  public column(column: number, layout: LayoutOptions = 'moveScale'): GridStack {
     if (this.opts.column === column) { return this; }
     let oldColumn = this.opts.column;
 
@@ -531,8 +532,6 @@ export class GridStack {
     this.el.classList.add('grid-stack-' + column);
     this.opts.column = this.engine.column = column;
 
-    if (doNotPropagate === true) { return this; }
-
     // update the items now - see if the dom order nodes should be passed instead (else default to current list)
     let domNodes: GridStackNode[] = undefined; // explicitly leave not defined
     if (column === 1 && this.opts.oneColumnModeDomSort) {
@@ -542,7 +541,7 @@ export class GridStack {
       });
       if (!domNodes.length) { domNodes = undefined; }
     }
-    this.engine.updateNodeWidths(oldColumn, column, domNodes);
+    this.engine.updateNodeWidths(oldColumn, column, domNodes, layout);
 
     // and trigger our event last...
     this._triggerChangeEvent(true); // skip layout update

src/types.ts

@@ -9,6 +9,10 @@
 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';
+
 export type numberOrString = number | string;
 export interface GridItemHTMLElement extends HTMLElement {
   /** pointer to grid node instance */