added batchUpdate(false) to replace commit()

* also updated doc

Author: adumesny

demo/react-hooks.html

@@ -71,7 +71,7 @@ <h2>Uncontrolled stack</h2>
       grid.batchUpdate()
       grid.removeAll(false)
       items.forEach(({ id }) => grid.makeWidget(refs.current[id].current))
-      grid.commit()
+      grid.batchUpdate(false)
     }, [items])
 
     return (

doc/CHANGES.md

@@ -5,6 +5,7 @@ Change log
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 **Table of Contents**  *generated with [DocToc](http://doctoc.herokuapp.com/)*
 
+- [TBD](#tbd)
 - [5.1.1 (2022-06-16)](#511-2022-06-16)
 - [5.1.0 (2022-05-21)](#510-2022-05-21)
 - [5.0.0 (2022-01-10)](#500-2022-01-10)
@@ -68,6 +69,9 @@ Change log
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
+## TBD
+* changed `commit()` to be `batchUpdate(false)` to make it easier to turn batch on/off. updated doc. old API remains for now
+
 ## 5.1.1 (2022-06-16)
 * fix v5.1.0 regression [#1973](https://github.com/gridstack/gridstack.js/issues/1973) DnD Snap to Animation
 

doc/README.md

@@ -30,11 +30,10 @@ gridstack.js API
   - [`GridStack.registerEngine(engineClass: typeof GridStackEngine)`](#gridstackregisterengineengineclass-typeof-gridstackengine)
 - [API](#api)
   - [`addWidget(el?: GridStackWidget | GridStackElement, options?: GridStackWidget)`](#addwidgetel-gridstackwidget--gridstackelement-options-gridstackwidget)
-  - [`batchUpdate()`](#batchupdate)
+  - [`batchUpdate(flag = true)`](#batchupdateflag--true)
   - [`compact()`](#compact)
   - [`cellHeight(val: number, update = true)`](#cellheightval-number-update--true)
   - [`cellWidth()`](#cellwidth)
-  - [`commit()`](#commit)
   - [`column(column: number, layout: ColumnOptions = 'moveScale')`](#columncolumn-number-layout-columnoptions--movescale)
   - [`destroy([removeDOM])`](#destroyremovedom)
   - [`disable()`](#disable)
@@ -348,9 +347,9 @@ grid.addWidget({w: 3, content: 'hello'});
 grid.addWidget('<div class="grid-stack-item"><div class="grid-stack-item-content">hello</div></div>', {w: 3});
 ```
 
-### `batchUpdate()`
+### `batchUpdate(flag = true)`
 
-starts batch updates. You will see no changes until `commit()` method is called.
+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.
 
 ### `compact()`
 
@@ -368,10 +367,6 @@ grid.cellHeight(grid.cellWidth() * 1.2);
 
 Gets current cell width (grid width / # of columns).
 
-### `commit()`
-
-Ends batch updates. Updates DOM nodes. You must call it after `batchUpdate()`.
-
 ### `column(column: number, layout: ColumnOptions = 'moveScale')`
 
 set the number of columns in the grid. Will update existing widgets to conform to new number of columns,

spec/e2e/html/810-many-columns.html

@@ -38,7 +38,7 @@ <h1>Many Columns demo</h1>
     for (; count <= COLUMNS;) {
       this.addNewWidget(); 
     }
-    grid.commit();
+    grid.batchUpdate(false);
   </script>
 </body>
 </html>

spec/gridstack-engine-spec.ts

@@ -186,8 +186,8 @@ describe('gridstack engine', function() {
       engine.batchUpdate(); // double for code coverage
       expect(engine.batchMode).toBeTrue();
       expect(engine.float).toEqual(true);
-      engine.commit();
-      engine.commit();
+      engine.batchUpdate(false);
+      engine.batchUpdate(false);
       expect(engine.batchMode).not.toBeTrue();
       expect(engine.float).not.toBeTrue;
     });
@@ -197,7 +197,7 @@ describe('gridstack engine', function() {
       engine.batchUpdate();
       expect(engine.batchMode).toBeTrue();
       expect(engine.float).toEqual(true);
-      engine.commit();
+      engine.batchUpdate(false);
       expect(engine.batchMode).not.toBeTrue();
       expect(engine.float).toEqual(true);
     });
@@ -214,7 +214,7 @@ describe('gridstack engine', function() {
       engine.batchUpdate();
       expect(engine.batchMode).toBeTrue();
       expect(engine.float).toEqual(true);
-      engine.commit();
+      engine.batchUpdate(false);
       expect(engine.batchMode).not.toBeTrue();
       expect(engine.float).toEqual(true);
     });

spec/gridstack-spec.ts

@@ -433,8 +433,8 @@ describe('gridstack', function() {
       let el1 = grid.addWidget({w:1, h:1});
       let el2 = grid.addWidget({x:2, y:0, w:2, h:1});
       let el3 = grid.addWidget({x:1, y:0, w:1, h:2});
-      grid.commit();
-      grid.commit();
+      grid.batchUpdate(false);
+      grid.batchUpdate(false);
 
       // items are item1[1x1], item3[1x1], item2[2x1]
       expect(parseInt(el1.getAttribute('gs-x'))).toBe(0);
@@ -1848,6 +1848,15 @@ describe('gridstack', function() {
       expect((grid as any).willItFit(0, 0, 1, 3, false)).toBe(true);
       expect((grid as any).willItFit(0, 0, 1, 4, false)).toBe(false);
     });
+    it('warning if OLD commit() is called', function() {
+      let grid = GridStack.init();
+      grid.batchUpdate(true);
+      expect(grid.engine.batchMode).toBe(true);
+      grid.commit(); // old API
+      expect(grid.engine.batchMode).toBe(false);
+      // expect(console.warn).toHaveBeenCalledWith('gridstack.js: Function `setGridWidth` is deprecated in v0.5.3 and has been replaced with `column`. It will be **completely** removed in v1.0');
+    });
+
     /* saving as example
     it('warning if OLD setGridWidth is called', function() {
       let grid: any = GridStack.init();

src/gridstack-engine.ts

@@ -54,21 +54,19 @@ export class GridStackEngine {
     this.onChange = opts.onChange;
   }
 
-  public batchUpdate(): GridStackEngine {
-    if (this.batchMode) return this;
-    this.batchMode = true;
-    this._prevFloat = this._float;
-    this._float = true; // let things go anywhere for now... commit() will restore and possibly reposition
-    return this.saveInitial(); // since begin update (which is called multiple times) won't do this
-  }
-
-  public commit(): GridStackEngine {
-    if (!this.batchMode) return this;
-    this.batchMode = false;
-    this._float = this._prevFloat;
-    delete this._prevFloat;
-    return this._packNodes()
-      ._notify();
+  public batchUpdate(flag = true): GridStackEngine {
+    if (!!this.batchMode === flag) return this;
+    this.batchMode = flag;
+    if (flag) {
+      this._prevFloat = this._float;
+      this._float = true; // let things go anywhere for now... will restore and possibly reposition later
+      this.saveInitial(); // since begin update (which is called multiple times) won't do this
+    } else {
+      this._float = this._prevFloat;
+      delete this._prevFloat;
+      this._packNodes()._notify();
+    }
+    return this;
   }
 
   // use entire row for hitting area (will use bottom reverse sorted first) if we not actively moving DOWN and didn't already skip
@@ -252,7 +250,7 @@ export class GridStackEngine {
       this.addNode(node, false); // 'false' for add event trigger
       node._dirty = true; // will force attr update
     });
-    return this.commit();
+    return this.batchUpdate(false);
   }
 
   /** enable/disable floating widgets (default: `false`) See [example](http://gridstackjs.com/demo/float.html) */
@@ -829,7 +827,7 @@ export class GridStackEngine {
       this.addNode(node, false); // 'false' for add event trigger
       delete node._orig; // make sure the commit doesn't try to restore things back to original
     });
-    this.commit();
+    this.batchUpdate(false);
     delete this._inColumnResize;
     return this;
   }

src/gridstack-h5.ts

@@ -1,6 +1,6 @@
-/**
- * index-h5.ts 5.1.1 - everything you need for a Grid that uses HTML5 native drag&drop
- * Copyright (c) 2021 Alain Dumesny - see GridStack root license
+/*!
+ * gridstack-h5.ts 5.1.1 - everything you need for a Grid that uses HTML5 native drag&drop
+ * Copyright (c) 2021 Alain Dumesny - see root license https://github.com/gridstack/gridstack.js/tree/master/LICENSE
  */
 
 export * from './types';

src/gridstack-jq.ts

@@ -1,5 +1,5 @@
-/**
- * index-jq.ts 5.1.1 - everything you need for a Grid that uses Jquery-ui drag&drop (original, full feature)
+/*!
+ * gridstack-jq.ts 5.1.1 - everything you need for a Grid that uses Jquery-ui drag&drop (original, full feature)
  * Copyright (c) 2021 Alain Dumesny - see GridStack root license
  */
 

src/gridstack-static.ts

@@ -1,5 +1,5 @@
-/**
- * index-static.ts 5.1.1 - much smaller, everything you need for a static Grid (non draggable, API driven)
+/*!
+ * gridstack-static.ts 5.1.1 - much smaller, everything you need for a static Grid (non draggable, API driven)
  * Copyright (c) 2021 Alain Dumesny - see GridStack root license
  */