Merge pull request #1308 from adumesny/typescript

TS: #723 #726 `margin` to replace `verticalMargin`

Author: adumesny

README.md

@@ -334,14 +334,15 @@ make sure to read v1.0.0 migration first!
 
 v2.x is a Typescript rewrite of 1.x, removing all jquery events, using classes and overall code cleanup. Your code might need to change from 1.x
 
-1. In general methods that used no args (getter) vs setter are not used in Typescript. 
-Also legacy methods that used to take tons of parameters will now take a single object (typically `GridstackOptions` or `GridStackWidget`).
+1. In general methods that used no args (getter) vs setter are not used in Typescript when the arguments differ.
+Also legacy methods that used to take many parameters will now take a single object (typically `GridstackOptions` or `GridStackWidget`).
 
 ```
 removed `addWidget(el, x, y, width, ...)` --> use the widget options version instead `addWidget(el, {with, ...})`
 `float()` to get value --> `getFloat()`
 'cellHeight()` to get value --> `getCellHeight()`
-'verticalMargin()` to get value --> `getVerticalMargin()`
+'verticalMargin' is now 'margin' grid options and applies to all 4 sides.
+'verticalMargin()` to get value --> `getMargin()`
 ```
 
 2. event signatures are generic and not jquery-ui dependent anymore. `gsresizestop` has been removed as `resizestop|dragstop` are now called **after** the DOm attributes have been updated.

demo/nested.html

@@ -57,7 +57,8 @@ <h1>Nested grids demo</h1>
     let nestOptions = {
       acceptWidgets: '.grid-stack-item.sub', // only pink sub items can be inserted, otherwise grid-items causes all sort of issues
       dragOut: true, // let us drag them out!
-      disableOneColumnMode: true // nested are small, but still want N columns
+      disableOneColumnMode: true, // nested are small, but still want N columns
+      margin: 1
     };
     GridStack.init(null, '.grid-stack.top');
     let grid1 = GridStack.init(nestOptions, '.grid-stack.nested1');

doc/CHANGES.md

@@ -40,6 +40,8 @@ Change log
 - add `getGridItems()` to return list of HTML grid items
 - add `{dragIn | dragInOptions}` grid attributes to handle external drag&drop items
 - add `save()` and `restore()` to serialize grids from JSON, saving all attributes (not just w,h,x,y) [1286](https://github.com/gridstack/gridstack.js/issues/1286)
+- add `margin` to replace `verticalMargin` which affects both dimensions in code, rather than one in code the other in CSS.
+You can now have perfect square cells (default) [723](https://github.com/gridstack/gridstack.js/issues/723)
 - fix [1299](https://github.com/gridstack/gridstack.js/pull/1299) many columns round-off error
 
 ## 1.1.2 (2020-05-17)
@@ -210,7 +212,7 @@ thanks [@ermcgrat](https://github.com/ermcgrat) and others for pointing out code
 ## v0.2.5 (2016-03-02)
 
 - update names to respect js naming convention.
-- `cellHeight` and `verticalMargin` can now be string (e.g. '3em', '20px') (Thanks to @jlowcs).
+- `cellHeight` and `margin` can now be string (e.g. '3em', '20px') (Thanks to @jlowcs).
 - add `maxWidth`/`maxHeight` methods.
 - add `enableMove`/`enableResize` methods.
 - fix window resize issue [#331](https://github.com/gridstack/gridstack.js/issues/331)).

doc/README.md

@@ -24,7 +24,7 @@ gridstack.js API
   - [addWidget(el, [options])](#addwidgetel-options)
   - [batchUpdate()](#batchupdate)
   - [compact()](#compact)
-  - [cellHeight(val, noUpdate)](#cellheightval-noupdate)
+  - [cellHeight(val: number, update = true)](#cellheightval-number-update--true)
   - [cellWidth()](#cellwidth)
   - [commit()](#commit)
   - [column(column, doNotPropagate)](#columncolumn-donotpropagate)
@@ -37,9 +37,11 @@ gridstack.js API
   - [getCellHeight()](#getcellheight)
   - [getCellFromPixel(position[, useOffset])](#getcellfrompixelposition-useoffset)
   - [getGridItems(): GridItemHTMLElement[]](#getgriditems-griditemhtmlelement)
+  - [getMargin()](#getmargin)
   - [isAreaEmpty(x, y, width, height)](#isareaemptyx-y-width-height)
   - [locked(el, val)](#lockedel-val)
   - [makeWidget(el)](#makewidgetel)
+  - [margin(value: numberOrString)](#marginvalue-numberorstring)
   - [maxHeight(el, val)](#maxheightel-val)
   - [minHeight(el, val)](#minheightel-val)
   - [maxWidth(el, val)](#maxwidthel-val)
@@ -55,8 +57,6 @@ gridstack.js API
   - [setAnimation(doAnimate)](#setanimationdoanimate)
   - [setStatic(staticValue)](#setstaticstaticvalue)
   - [update(el, x, y, width, height)](#updateel-x-y-width-height)
-  - [getVerticalMargin()](#getverticalmargin)
-  - [verticalMargin(value, noUpdate)](#verticalmarginvalue-noupdate)
   - [willItFit(x, y, width, height, autoPosition)](#willitfitx-y-width-height-autoposition)
 - [Utils](#utils)
   - [GridStack.Utils.sort(nodes[, dir[, width]])](#gridstackutilssortnodes-dir-width)
@@ -76,11 +76,11 @@ gridstack.js API
    See [example](http://gridstack.github.io/gridstack.js/demo/advance.html)
 - `animate` - turns animation on (default: `false`)
 - `auto` - if `false` gridstack will not initialize existing items (default: `true`)
-- `cellHeight` - one cell height (default: `60`). Can be:
+- `cellHeight` - one cell height (default: `auto`). Can be:
   * an integer (px)
-  * a string (ex: '100px', '10em', '10rem', '10%')
+  * a string (ex: '100px', '10em', '10rem', '10%', `10vh')
   * 0 or null, in which case the library will not generate styles for rows. Everything must be defined in CSS files.
-  * `'auto'` - height will be calculated cell square initially.
+  * `'auto'` - height will be square cells initially.
 - `column` - number of columns (default: `12`) which can change on the fly with `column(N)` as well. See [example](http://gridstackjs.com/demo/column.html)
 - `ddPlugin` - class that implement drag'n'drop functionality for gridstack. If `false` grid will be static. (default: `null` - first available plugin will be used)
 - `disableDrag` - disallows dragging of widgets (default: `false`).
@@ -94,6 +94,13 @@ gridstack.js API
 - `handle` - draggable handle selector (default: `'.grid-stack-item-content'`)
 - `handleClass` - draggable handle class (e.g. `'grid-stack-item-content'`). If set `handle` is ignored (default: `null`)
 - `itemClass` - widget class (default: `'grid-stack-item'`)
+- `margin` - gap size around grid item and content (default: `10`). Can be:
+  * an integer (px)
+  * a string (ex: '2em', '20px', '2rem')
+- `marginTop`: numberOrString - can set individual settings (defaults to `margin`)
+- `marginRight`: numberOrString
+- `marginBottom`: numberOrString
+- `marginLeft`: numberOrString
 - `maxRow` - maximum rows amount. Default is `0` which means no max.
 - `minRow` - minimum rows amount which is handy to prevent grid from collapsing when empty. Default is `0`. You can also do this with `min-height` CSS attribute on the grid div in pixels, which will round to the closest row.
 - `minWidth` - minimal width. If grid width is less than or equal to, grid will be shown in one-column mode (default: `768`)
@@ -106,9 +113,6 @@ gridstack.js API
 - `row` - fix grid number of rows. This is a shortcut of writing `minRow:N, maxRow:N`. (default `0` no constrain)
 - `rtl` - if `true` turns grid to RTL. Possible values are `true`, `false`, `'auto'` (default: `'auto'`) See [example](http://gridstackjs.com/demo/rtl.html)
 - `staticGrid` - removes drag&drop&resize (default `false`). If `true` widgets are not movable/resizable by the user, but code can still move and oneColumnMode will still work. You don't even need jQueryUI draggable/resizable.  A CSS class `grid-stack-static` is also added to the container.
-- `verticalMargin` - vertical gap size (default: `20`). Can be:
-  * an integer (px)
-  * a string (ex: '2em', '20px', '2rem')
 
 ## Grid attributes
 
@@ -273,9 +277,9 @@ starts batch updates. You will see no changes until `commit()` method is called.
 
 re-layout grid items to reclaim any empty space.
 
-### cellHeight(val, noUpdate)
+### cellHeight(val: number, update = true)
 
-Update current cell height. This method rebuilds an internal CSS stylesheet (unless optional noUpdate=true). Note: You can expect performance issues if
+Update current cell height. This method rebuilds an internal CSS stylesheet (unless optional update=false). Note: You can expect performance issues if
 call this method too often.
 
 ```js
@@ -284,7 +288,7 @@ grid.cellHeight(grid.cellWidth() * 1.2);
 
 ### cellWidth()
 
-Gets current cell width.
+Gets current cell width (grid width / # of columns).
 
 ### commit()
 
@@ -370,6 +374,10 @@ Returns an object with properties `x` and `y` i.e. the column and row in the gri
 
 Return list of GridItem HTML dom elements (excluding temporary placeholder)
 
+### getMargin()
+
+returns current margin value.
+
 ### isAreaEmpty(x, y, width, height)
 
 Checks if specified area is empty.
@@ -396,6 +404,12 @@ grid.el.appendChild('<div id="gsi-1" data-gs-x="0" data-gs-y="0" data-gs-width="
 grid.makeWidget('gsi-1');
 ```
 
+### margin(value: numberOrString)
+
+set the top/right/bottom/left margin between grid item and content. Parameters:
+- `value` - new margin value. see `cellHeight` for possible value formats.
+Note: you can instead use `marginTop | marginBottom | marginLeft | marginRight` so set the sides separately.
+
 ### maxHeight(el, val)
 
 Set the `maxHeight` for a widget.
@@ -506,17 +520,6 @@ Parameters:
 
 Updates widget position/size.
 
-### getVerticalMargin()
-
-returns current vertical margin value.
-
-### verticalMargin(value, noUpdate)
-
-Parameters:
-
-- `value` - new vertical margin value.
-- `noUpdate` - if true, styles will not be updated.
-
 ### willItFit(x, y, width, height, autoPosition)
 
 Returns `true` if the `height` of the grid will be less the vertical constraint. Always returns `true` if grid doesn't

spec/e2e/html/1017-items-no-x-y-for-autoPosition.html

@@ -47,7 +47,7 @@
   <script type="text/javascript">
     let options = {
       cellHeight: 80,
-      verticalMargin: 10,
+      margin: 5,
       float: true
     };
     GridStack.init(options);