Merge pull request #1324 from adumesny/typescript

TS v2.0 release candidate

Author: adumesny

Gruntfile.js

@@ -1,6 +1,6 @@
 module.exports = function(grunt) {
   grunt.loadNpmTasks('grunt-sass');
-  // grunt.loadNpmTasks('grunt-contrib-cssmin');
+  grunt.loadNpmTasks('grunt-contrib-cssmin');
   grunt.loadNpmTasks('grunt-contrib-copy');
   grunt.loadNpmTasks('grunt-contrib-uglify');
   grunt.loadNpmTasks('grunt-eslint');
@@ -24,7 +24,6 @@ module.exports = function(grunt) {
         }
       }
     },
-    /* very little gain
     cssmin: {
       dist: {
         options: {
@@ -37,7 +36,6 @@ module.exports = function(grunt) {
         }
       }
     },
-    */
     copy: {
       dist: {
         files: {
@@ -58,8 +56,8 @@ module.exports = function(grunt) {
       },
       dist: {
         files: {
-          'dist/jq/jquery.min.js': 'src/jq/jquery.js',
-          'dist/jq/jquery-ui.min.js': 'src/jq/jquery-ui.js',
+          'dist/jq/jquery.js': 'src/jq/jquery.js',
+          'dist/jq/jquery-ui.js': 'src/jq/jquery-ui.js',
           /*
           'dist/jq/gridstack-dd-jqueryui.min.js': 'dist/jq/gridstack-dd-jqueryui.js',
           'dist/gridstack-dd.min.js': 'dist/gridstack-dd.js',
@@ -84,7 +82,7 @@ module.exports = function(grunt) {
       },
       styles: {
         files: ['src/*.scss'],
-        tasks: ['sass'/*, 'cssmin'*/],
+        tasks: ['sass', 'cssmin'],
         options: {
         },
       }
@@ -118,6 +116,6 @@ module.exports = function(grunt) {
   });
 
   grunt.registerTask('lint', ['eslint']);
-  grunt.registerTask('default', ['sass', /*'cssmin', 'eslint',*/ 'copy', 'uglify']);
+  grunt.registerTask('default', ['sass', 'cssmin', /*'eslint',*/ 'copy', 'uglify']);
   grunt.registerTask('e2e-test', ['connect', 'protractor_webdriver', 'protractor']);
 };

README.md

@@ -37,10 +37,10 @@ Join us on Slack: https://gridstackjs.troolee.com
   - [Custom columns CSS](#custom-columns-css)
   - [Override resizable/draggable options](#override-resizabledraggable-options)
   - [Touch devices support](#touch-devices-support)
-  - [Migrating to v0.6.x](#migrating-to-v06x)
-  - [Migrating to v1.0.0](#migrating-to-v100)
+  - [Migrating to v0.6](#migrating-to-v06)
+  - [Migrating to v1](#migrating-to-v1)
     - [jQuery Application](#jquery-application)
-  - [Migrating to v2.0.0](#migrating-to-v200)
+  - [Migrating to v2](#migrating-to-v2)
 - [Changes](#changes)
 - [The Team](#the-team)
 
@@ -70,44 +70,66 @@ npm install --save gridstack
 
 ## Include
 
-after you install:
+ES6 or Typescript
+
+```js
+import { GridStack } from 'gridstack';
+import 'gridstack/dist/gridstack.css';
+```
+
+legacy javascript
 
 ```js
 import 'gridstack/dist/gridstack.all.js';
 import 'gridstack/dist/gridstack.css';
 ```
-* alternatively in html
+
+alternatively in html
 
 ```html
 <link rel="stylesheet" href="node_modules/gridstack/dist/gridstack.min.css" />
 <script src="node_modules/gridstack/dist/gridstack.all.js"></script>
 ```
 
-* or using CDN (minimized):
+or using CDN (minimized):
 
 ```html
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/gridstack@1.2.0/dist/gridstack.min.css" />
-<script src="https://cdn.jsdelivr.net/npm/gridstack@1.2.0/dist/gridstack.all.js"></script>
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected].0-rc/dist/gridstack.min.css" />
+<script src="https://cdn.jsdelivr.net/npm/[email protected].0-rc/dist/gridstack.all.js"></script>
 ```
 
-if you need to debug, look at the git demo/ examples for non min includes.
+.map files are included for debugging purposes.
 
 ## Basic usage
 
 creating items dynamically...
 
-```html
+```js
+// ...in your HTML
 <div class="grid-stack"></div>
 
-<script type="text/javascript">
-  let grid = GridStack.init();
-  grid.addWidget('<div><div class="grid-stack-item-content">Item 1</div></div>', {width: 2});
-</script>
+// ...in your script
+var grid = GridStack.init();
+grid.addWidget('<div><div class="grid-stack-item-content">Item 1</div></div>', {width: 2});
+```
+
+... or creating from list
+
+```js
+// using serialize data instead of .addWidget()
+const serializedData = [
+  {x: 0, y: 0, width: 2, height: 2},
+  {x: 2, y: 3, width: 3, height: 1},
+  {x: 1, y: 3, width: 1, height: 1}
+];
+
+grid.load(serializedData);
 ```
 
 ... or DOM created items
 
-```html
+```js
+// ...in your HTML
 <div class="grid-stack">
   <div class="grid-stack-item">
     <div class="grid-stack-item-content">Item 1</div>
@@ -117,9 +139,8 @@ creating items dynamically...
   </div>
 </div>
 
-<script type="text/javascript">
-  GridStack.init();
-</script>
+// ...in your script
+GridStack.init();
 ```
 
 see [jsfiddle sample](https://jsfiddle.net/adumesny/jqhkry7g) as running example too.
@@ -276,24 +297,24 @@ GridStack.init(options);
 If you're still experiencing issues on touch devices please check [#444](https://github.com/gridstack/gridstack.js/issues/444)
 
 
-## Migrating to v0.6.x
+## Migrating to v0.6
 
 starting in 0.6.x `change` event are no longer sent (for pretty much most nodes!) when an item is just added/deleted unless it also changes other nodes (was incorrect and causing inefficiencies). You may need to track `added|removed` [events](https://github.com/gridstack/gridstack.js/tree/develop/doc#events) if you didn't and relied on the old broken behavior.
 
-## Migrating to v1.0.0
+## Migrating to v1
 
 v1.0.0 removed Jquery from the API and external dependencies, which will require some code changes. Here is a list of the changes:
 
-1. see [Migrating to v0.6.x](#migrating-to-v06x) if you didn't already
+1. see [Migrating to v0.6](#migrating-to-v06) if you didn't already
 
-2. your code only needs to include `gridstack.all.js` and `gristack.css` (don't include other JS) and is recommended you do that as internal dependencies will change over time. If you are jquery based, also see note below.
+2. your code only needs to include `gridstack.all.js` and `gristack.css` (don't include other JS) and is recommended you do that as internal dependencies will change over time. If you are jquery based, see [jquery app](#jquery-application) below.
 
 3. code change:
 
 **OLD** initializing code + adding a widget + adding an event:
 ```js
 // initialization returned Jquery element, requiring second call to get GridStack var
-let grid = $('.grid-stack').gridstack(opts?).data('gridstack');
+var grid = $('.grid-stack').gridstack(opts?).data('gridstack');
 
 // returned Jquery element
 grid.addWidget($('<div><div class="grid-stack-item-content"> test </div></div>'), undefined, undefined, 2, undefined, true);
@@ -302,13 +323,13 @@ grid.addWidget($('<div><div class="grid-stack-item-content"> test </div></div>')
 $('.grid-stack').on('added', function(e, items) {/* items contains info */});
 
 // grid access after init
-let grid = $('.grid-stack').data('gridstack');
+var grid = $('.grid-stack').data('gridstack');
 ```
 **NEW**
 ```js
 // element identifier defaults to '.grid-stack', returns the grid
-// Note: for Typescript use window.GridStack.init() until next native TS version
-let grid = GridStack.init(opts?, element?);
+// Note: for Typescript use window.GridStack.init() until next native 2.x TS version
+var grid = GridStack.init(opts?, element?);
 
 // returns DOM element
 grid.addWidget('<div><div class="grid-stack-item-content"> test </div></div>', {width: 2});
@@ -317,9 +338,9 @@ grid.addWidget('<div><div class="grid-stack-item-content"> test </div></div>', {
 grid.on('added', function(e, items) {/* items contains info */});
 
 // grid access after init
-let grid = el.gridstack; // where el = document.querySelector('.grid-stack') or other ways...
+var grid = el.gridstack; // where el = document.querySelector('.grid-stack') or other ways...
 ```
-Other vars/global changes
+Other changes
 ```
 `GridStackUI` --> `GridStack`
 `GridStackUI.GridStackEngine` --> `GridStack.Engine`
@@ -332,22 +353,23 @@ Recommend looking at the [many samples](./demo) for more code examples.
 
 ### jQuery Application
 
-We're working on implementing HTML5 drag'n'drop through the plugin system. Right now it is still jquery-ui based. Because of that we are still bundling `jquery` (3.5.1) + `jquery-ui` (1.12.1 minimal drag|drop|resize) internally in `gridstack.all.js`. IFF your app needs to bring your own version instead, you should **instead** include `gridstack-poly.min.js` (optional IE support) + `gridstack.min.js` + `gridstack.jQueryUI.min.js` after you import your JQ libs. But note that there are issue with jQuery and ES6 import (see [1306](https://github.com/gridstack/gridstack.js/issues/1306))
+We're working on implementing HTML5 drag'n'drop through the plugin system. Right now it is still jquery-ui based. Because of that we are still bundling `jquery` (3.5.1) + `jquery-ui` (1.12.1 minimal drag|drop|resize) internally in `gridstack.all.js`. IFF your app needs to bring your own version instead, you should **instead** include `gridstack-poly.min.js` (optional IE support) + `gridstack.min.js` + `gridstack.jQueryUI.min.js` after you import your JQ libs. But note that there are issue with jQuery and ES6 import (see [1306](https://github.com/gridstack/gridstack.js/issues/1306)).
+
+Note: v2.0.-rc does not currently support importing GridStack Drag&Drop without also including our jquery + jqueryui. Still trying to figure how to make that bundle possible.
 
-## Migrating to v2.0.0
+## Migrating to v2
 
-make sure to read v1.0.0 migration first!
+make sure to read v1 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
+v2.x is a Typescript rewrite of 1.x, removing all jquery events, using classes and overall code cleanup to support ES6 modules. 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 when the arguments differ.
-Also legacy methods that used to take many parameters will now take a single object (typically `GridstackOptions` or `GridStackWidget`).
+1. In general methods that used no args (getter) vs setter can't be used in TS when the arguments differ (set/get are also not function calls so API would have changed). Instead we decided to have <b>all set methods return</b> `GridStack` to they can be chain-able (ex: `grid.float(true).cellHeight(10).column(6)`). 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, ...})`
+`addWidget(el, x, y, width, height)` --> `addWidget(el, {with: 2})`
 `float()` to get value --> `getFloat()`
 'cellHeight()` to get value --> `getCellHeight()`
-'verticalMargin' is now 'margin' grid options and applies to all 4 sides.
+'verticalMargin' is now 'margin' grid options and API that applies to all 4 sides.
 'verticalMargin()` to get value --> `getMargin()`
 ```
 

demo/two.html

@@ -11,12 +11,6 @@
   <link rel="stylesheet" href="../dist/gridstack-extra.css"/>
 
   <script src="../dist/gridstack.all.js"></script>
-  <!--
-  <script src="../dist/jq/jquery.min.js"></script>
-  <script src="../dist/jq/jquery-ui.min.js"></script>
-  <script src="../dist/gridstack.js"></script>
-  <script src="../dist/jq/gridstack-dd-jqueryui.js"></script>
-  -->
 
   <style type="text/css">
     .grid-stack {
@@ -100,6 +94,7 @@ <h1>Two grids demo</h1>
   <script type="text/javascript">
     let options = {
       column: 6,
+      cellHeight: 70,
       disableOneColumnMode: true,
       float: false,
       removable: '.trash',

doc/CHANGES.md

@@ -37,7 +37,7 @@ Change log
 
 ## 2.0.0-dev (upcoming)
 
-- re-write to native Typescript, removing all JQuery from main code and API (drag&drop plugin still using for now which use latest v3.5.1)
+- re-write to native Typescript, removing all JQuery from main code and API (drag&drop plugin still using jqueryui for now)
 - add `getGridItems()` to return list of HTML grid items
 - add `{dragIn | dragInOptions}` grid attributes to handle external drag&drop items
 - add `save()` and `load()` to serialize grids from JSON, saving all attributes (not just w,h,x,y) [1286](https://github.com/gridstack/gridstack.js/issues/1286)

package.json

@@ -9,9 +9,9 @@
     "url": "git+https://github.com/gridstack/gridstack.js.git"
   },
   "scripts": {
-    "build": "yarn --no-progress && rm -rf dist/* && grunt && webpack && doctoc ./README.md && doctoc ./doc/README.md && doctoc ./doc/CHANGES.md",
+    "build": "yarn --no-progress && rm -rf dist/* && grunt && webpack && tsc --stripInternal && doctoc ./README.md && doctoc ./doc/README.md && doctoc ./doc/CHANGES.md",
     "w": "rm -rf dist/* && grunt && webpack",
-    "t": "rm -rf dist/* && tsc --stripInternal",
+    "t": "rm -rf dist/* && grunt && tsc --stripInternal",
     "test": "yarn lint && karma start karma.conf.js",
     "lint": "tsc --noEmit && eslint src/*.ts",
     "reset": "rm -rf dist node_modules",
@@ -43,9 +43,11 @@
   },
   "homepage": "http://gridstack.github.io/gridstack.js/",
   "dependencies": {
+  },
+  "devDependencies": {
     "@types/jasmine": "^3.5.9",
-    "@types/jquery": "^3.3.33",
-    "@types/jqueryui": "^1.12.10",
+    "@types/jquery": "^3.5.1",
+    "@types/jqueryui": "^1.12.13",
     "@typescript-eslint/eslint-plugin": "^2.23.0",
     "@typescript-eslint/parser": "^2.23.0",
     "connect": "^3.7.0",

src/gridstack.ts

@@ -5,12 +5,23 @@
  * (c) 2014-2020 Alain Dumesny, Dylan Weiss, Pavel Reznikov
  * gridstack.js may be freely distributed under the MIT license.
 */
+import './gridstack-poly.js';
 
 import { GridStackEngine } from './gridstack-engine';
 import { obsoleteOpts, obsoleteOptsDel, obsoleteAttr, obsolete, Utils } from './utils';
 import { GridItemHTMLElement, GridStackWidget, GridStackNode, GridstackOptions, numberOrString } 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
+export * from './types';
+export * from './utils';
+export * from './gridstack-engine';
+export * from './gridstack-dd';
+
+// TEMPORARY import the jquery-ui drag&drop since we don't have alternative yet and don't expect users to create their own yet
+import './jq/gridstack-dd-jqueryui';
+export * from './jq/gridstack-dd-jqueryui';
+
 export type GridStackElement = string | HTMLElement | GridItemHTMLElement;
 
 export interface GridHTMLElement extends HTMLElement {

src/index.ts

@@ -12,8 +12,9 @@ import { GridItemHTMLElement, DDDragInOpt } from '../types';
 
 // TODO: TEMPORARY until can remove jquery-ui drag&drop and this class and use HTML5 instead !
 // see https://stackoverflow.com/questions/35345760/importing-jqueryui-with-typescript-and-requirejs
-import * as $ from './jquery.js';
-import './jquery-ui.js';
+import * as $ from './jquery';
+export { $ };
+export * from './jquery-ui';
 
 /**
  * Jquery-ui based drag'n'drop plugin.
@@ -67,7 +68,7 @@ export class GridStackDDJQueryUI extends GridStackDD {
   }
 
   public dragIn(el: GridStackElement, opts: DDDragInOpt): GridStackDD {
-    let $el: JQuery = $(el);
+    let $el: JQuery = $(el as any); // workaround Type 'string' is not assignable to type 'PlainObject<any>' - see https://github.com/DefinitelyTyped/DefinitelyTyped/issues/29312
     $el.draggable(opts);
     return this;
   }
@@ -89,7 +90,7 @@ export class GridStackDDJQueryUI extends GridStackDD {
   }
 
   public isDraggable(el: GridStackElement): boolean {
-    let $el: JQuery = $(el);
+    let $el: JQuery = $(el as any); // workaround Type 'string' is not assignable to type 'PlainObject<any>' - see https://github.com/DefinitelyTyped/DefinitelyTyped/issues/29312
     return Boolean($el.data('ui-draggable'));
   }
 

src/jq/gridstack-dd-jqueryui.ts

@@ -10,15 +10,17 @@
     "experimentalDecorators": true,
     "inlineSources": true,
     "lib": [ "es6", "es2015", "dom" ],
-    "module": "commonjs",
+    "module": "CommonJS",
     "noImplicitAny": false,
     "outDir": "./dist",
     "sourceMap": true,
     "strict": false,
-    "target": "es5"
+    "target": "ES6"
   }, 
   "exclude": [
-    "./src/**/*.spec.ts"
+    "./src/**/*.spec.ts",
+    "./src/index.ts" // used for webpack all.js
+
   ],
   "include": [
     "./src/**/*.ts"