diff --git a/types/gridstack/gridstack-tests.ts b/types/gridstack/gridstack-tests.ts index 4020bc6fad..229a835396 100644 --- a/types/gridstack/gridstack-tests.ts +++ b/types/gridstack/gridstack-tests.ts @@ -1,6 +1,6 @@ /// -var options: IGridstackOptions = { +var options: GridstackOptions = { float: true }; var element: JQuery = $(document).gridstack(options); diff --git a/types/gridstack/index.d.ts b/types/gridstack/index.d.ts index 4b81c639ea..ac83ba6c3c 100644 --- a/types/gridstack/index.d.ts +++ b/types/gridstack/index.d.ts @@ -1,90 +1,144 @@ -// Type definitions for Gridstack 0.4 -// Project: http://troolee.github.io/gridstack.js/ +// Type definitions for Gridstack 0.5 +// Project: http://gridstack.github.io/gridstack.js/ // Definitions by: Pascal Senn // Ricky Blankenaufulland // Sl1MBoy // John Archer +// Alain Dumesny // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped // TypeScript Version: 2.3 interface JQuery { - gridstack(options: IGridstackOptions): JQuery; - data(key: "gridstack"): GridStack; + gridstack(options: GridstackOptions): JQuery; + data(key: 'gridstack'): GridStack; } +/* Other items in https://github.com/gridstack/gridstack.js/blob/develop/doc/README.md +* Grid attributes +* Item attributes +* Events +*/ + +type GridStackElement = string | HTMLElement | JQuery; + interface GridStack { /** - * Creates new widget and returns it. - * - * Widget will be always placed even if result height is more than actual grid height. You need to use willItFit method before calling addWidget for additional check. - * - * @param {string | HTMLElement | JQuery} el widget to add - * @param {number} x widget position x (optional) - * @param {number} y widget position y (optional) - * @param {number} width widget dimension width (optional) - * @param {number} height widget dimension height (optional) - * @param {boolean} autoPosition if true then x, y parameters will be ignored and widget will be places on the first available position (optional) - * @param {number} minWidth minimum width allowed during resize/creation (optional) - * @param {number} maxWidth maximum width allowed during resize/creation (optional) - * @param {number} minHeight minimum height allowed during resize/creation (optional) - * @param {number} maxHeight maximum height allowed during resize/creation (optional) - * @param {number | string} id value for data-gs-id (optional) - */ - addWidget(el: string | HTMLElement | JQuery, x?: number, y?: number, width?: number, height?: number, autoPosition?: boolean, minWidth?: number, maxWidth?: number, minHeight?: number, maxHeight?: number, id?: number | string): JQuery + * Creates new widget and returns it. + * + * Widget will be always placed even if result height is more than actual grid height. + * You need to use willItFit method before calling addWidget for additional check. + * See also makeWidget. + * + * @example + * $('.grid-stack').gridstack(); + * var grid = $('.grid-stack').data('gridstack'); + * grid.addWidget(el, 0, 0, 3, 2, true); + * + * @param {GridStackElement} el widget to add + * @param {number} x widget position x (optional) + * @param {number} y widget position y (optional) + * @param {number} width widget dimension width (optional) + * @param {number} height widget dimension height (optional) + * @param {boolean} autoPosition if true then x, y parameters will be ignored and widget will be places on the first available position (optional) + * @param {number} minWidth minimum width allowed during resize/creation (optional) + * @param {number} maxWidth maximum width allowed during resize/creation (optional) + * @param {number} minHeight minimum height allowed during resize/creation (optional) + * @param {number} maxHeight maximum height allowed during resize/creation (optional) + * @param {number | string} id value for `data-gs-id` (optional) + */ + addWidget(el: GridStackElement, x?: number, y?: number, width?: number, height?: number, autoPosition?: boolean, + minWidth?: number, maxWidth?: number, minHeight?: number, maxHeight?: number, id?: number | string): JQuery; + /** * Initializes batch updates. You will see no changes until commit method is called. */ - batchUpdate(): void + batchUpdate(): void; + /** * Gets current cell height. */ - cellHeight(): number + cellHeight(): number; + /** - * Update current cell height. This method rebuilds an internal CSS style sheet. Note: You can expect performance issues if call this method too often. - * @param {number} val the cell height + * Update current cell height - see `GridstackOptions.cellHeight` for format. + * This method rebuilds an internal CSS style sheet. + * Note: You can expect performance issues if call this method too often. + * + * @param {number | string} val the cell height + * @param {boolean} noUpdate (Optional) if true, styles will not be updated + * + * @example + * grid.cellHeight(grid.cellWidth() * 1.2); */ - cellHeight(val: number): void + cellHeight(val: number | string, noUpdate?: boolean): void; + /** * Gets current cell width. */ - cellWidth(): number + cellWidth(): number; + /** * Finishes batch updates. Updates DOM nodes. You must call it after batchUpdate. */ - commit(): void + commit(): void; + /** * Destroys a grid instance. * @param {boolean} detachGrid if false nodes and grid will not be removed from the DOM (Optional. Default true). */ - destroy(detachGrid?: boolean): void - /* - * Disables widgets moving/resizing. + destroy(detachGrid?: boolean): void; + + /** + * Disables widgets moving/resizing. This is a shortcut for: + * @example + * grid.movable('.grid-stack-item', false); + * grid.resizable('.grid-stack-item', false); */ - disable(): void - /* - * Enables widgets moving/resizing. + disable(): void; + + /** + * Enables widgets moving/resizing. This is a shortcut for: + * @example + * grid.movable('.grid-stack-item', true); + * grid.resizable('.grid-stack-item', true); */ - enable(): void + enable(): void; + /** * Enables/disables widget moving. * This is a shortcut for: + * @example * grid.movable(this.container.children('.' + this.opts.itemClass), doEnable); + * * @param {boolean} doEnable - * @param {boolean} includeNewWidgets will force new widgets to be draggable + * @param {boolean} includeNewWidgets will force new widgets to be draggable as per + * doEnable`s value by changing the disableDrag grid option. */ - enableMove(doEnable: boolean, includeNewWidgets: boolean): void + enableMove(doEnable: boolean, includeNewWidgets: boolean): void; + /** - * Enables/disables widget resizing. - * @param {boolean} doEnable - * @param {boolean} includeNewWidgets will force new widgets to be resizable - */ - enableResize(doEnable: boolean, includeNewWidgets: boolean): void + * Enables/disables widget resizing + * @param {boolean} doEnable + * @param {boolean} includeNewWidgets will force new widgets to be draggable as per + * doEnable`s value by changing the disableResize grid option. + * + * This is a shortcut for: + * @example + * grid.resizable(this.container.children('.' + this.opts.itemClass), doEnable); + */ + enableResize(doEnable: boolean, includeNewWidgets: boolean): void; + /** * Get the position of the cell under a pixel on screen. - * @param {MousePosition} position the position of the pixel to resolve in absolute coordinates, as an object with top and leftproperties - * @param {boolean} useOffset if true, value will be based on offset vs position (Optional. Default false). Useful when grid is within position: relative element. + * @param {MousePosition} position the position of the pixel to resolve in + * absolute coordinates, as an object with top and left properties + * @param {boolean} useOffset if true, value will be based on offset vs position (Optional. Default false). + * Useful when grid is within `position: relative` element + * + * Returns an object with properties `x` and `y` i.e. the column and row in the grid. */ - getCellFromPixel(position: MousePosition, useOffset?: boolean): CellPosition, + getCellFromPixel(position: MousePosition, useOffset?: boolean): CellPosition; + /** * Checks if specified area is empty. * @param {number} x the position x. @@ -92,262 +146,336 @@ interface GridStack { * @param {number} width the width of to check * @param {number} height the height of to check */ - isAreaEmpty(x: number, y: number, width: number, height: number): void + isAreaEmpty(x: number, y: number, width: number, height: number): void; + /** * Locks/unlocks widget. - * @param {HTMLElement} el widget to modify. + * @param {GridStackElement} el widget to modify. * @param {boolean} val if true widget will be locked. */ - locked(el: HTMLElement, val: boolean): void + locked(el: GridStackElement, val: boolean): void; + /** - * If you add elements to your gridstack container by hand, you have to tell gridstack afterwards to make them widgets. - * - * If you want gridstack to add the elements for you, use addWidget instead. Makes the given element a widget and returns it. - * - * @param {string | HTMLElement | JQuery} el widget to add - */ - makeWidget(el: string | HTMLElement | JQuery): JQuery + * If you add elements to your gridstack container by hand, you have to tell gridstack afterwards to make them widgets. + * If you want gridstack to add the elements for you, use addWidget instead. + * Makes the given element a widget and returns it. + * @param {GridStackElement} el widget to convert. + * + * @example + * $('.grid-stack').gridstack(); + * $('.grid-stack').append('
') + * var grid = $('.grid-stack').data('gridstack'); + * grid.makeWidget('gsi-1'); + */ + makeWidget(el: GridStackElement): JQuery; + /** - * Set the maxWidth for a widget. - * @param {HTMLElement} el widget to modify. + * Set the maxWidth for a widget. + * @param {GridStackElement} el widget to modify. * @param {number} val A numeric value of the number of columns - */ - maxWidth(el: HTMLElement, val: number): void + */ + maxWidth(el: GridStackElement, val: number): void; + /** * Set the minWidth for a widget. - * @param {HTMLElement} el widget to modify. + * @param {GridStackElement} el widget to modify. * @param {number} val A numeric value of the number of columns */ - minWidth(el: HTMLElement, val: number): void + minWidth(el: GridStackElement, val: number): void; + /** * Set the maxHeight for a widget. - * @param {HTMLElement} el widget to modify. + * @param {GridStackElement} el widget to modify. * @param {number} val A numeric value of the number of rows */ - maxHeight(el: HTMLElement, val: number): void + maxHeight(el: GridStackElement, val: number): void; + /** * Set the minHeight for a widget. - * @param {HTMLElement} el widget to modify. + * @param {GridStackElement} el widget to modify. * @param {number} val A numeric value of the number of rows */ - minHeight(el: HTMLElement, val: number): void + minHeight(el: GridStackElement, val: number): void; + /** - * Enables/Disables moving. - * @param {HTMLElement} el widget to modify. - * @param {number} val if true widget will be draggable. - */ - movable(el: HTMLElement, val: boolean): void + * Enables/Disables moving. + * @param {GridStackElement} el widget to modify. + * @param {number} val if true widget will be draggable. + */ + movable(el: GridStackElement, val: boolean): void; + /** * Changes widget position - * @param {HTMLElement} el widget to modify + * @param {GridStackElement} el widget to modify * @param {number} x new position x. If value is null or undefined it will be ignored. * @param {number} y new position y. If value is null or undefined it will be ignored. - * */ - move(el: HTMLElement, x: number, y: number): void + move(el: GridStackElement, x: number, y: number): void; + /** * Removes widget from the grid. - * @param {HTMLElement} el widget to modify - * @param {boolean} detachNode if false DOM node won't be removed from the tree (Optional. Default true). + * @param {GridStackElement} el widget to modify + * @param {boolean} detachNode if false DOM node won't be removed from the tree (Default? true). */ - removeWidget(el: HTMLElement, detachNode?: boolean): void + removeWidget(el: GridStackElement, detachNode?: boolean): void; + /** * Removes all widgets from the grid. - * @param {boolean} detachNode if false DOM node won't be removed from the tree (Optional. Default true). + * @param {boolean} detachNode if false DOM nodes won't be removed from the tree (Default? true). */ - removeAll(detachNode?: boolean): void + removeAll(detachNode?: boolean): void; + /** * Changes widget size - * @param {HTMLElement} el widget to modify + * @param {GridStackElement} el widget to modify * @param {number} width new dimensions width. If value is null or undefined it will be ignored. * @param {number} height new dimensions height. If value is null or undefined it will be ignored. */ - resize(el: HTMLElement, width: number, height: number): void + resize(el: GridStackElement, width: number, height: number): void; + /** * Enables/Disables resizing. - * @param {HTMLElement} el widget to modify + * @param {GridStackElement} el widget to modify * @param {boolean} val if true widget will be resizable. */ - resizable(el: HTMLElement, val: boolean): void + resizable(el: GridStackElement, val: boolean): void; + /** - * Toggle the grid animation state. Toggles the grid-stack-animate class. - * @param {boolean} doAnimate if true the grid will animate. - */ - setAnimation(doAnimate: boolean): void + * Toggle the grid animation state. Toggles the `grid-stack-animate` class. + * @param {boolean} doAnimate if true the grid will animate. + */ + setAnimation(doAnimate: boolean): void; + /** - * (Experimental) Modify number of columns in the grid. - * Will attempt to update existing widgets to conform to new number of columns. - * Requires gridstack-extra.css or gridstack-extra.min.css. - * @param {number} gridWidth Integer between 1 and 12. - * @param {boolean} doNotPropagate if true existing widgets will not be updated. - */ - setGridWidth(gridWidth: number, doNotPropagate: boolean): void + * (Experimental) Modify number of columns in the grid. Will attempt to update existing widgets + * to conform to new number of columns. Requires `gridstack-extra.css` or `gridstack-extra.min.css`. + * @param {number} gridWidth - Integer between 1 and 12. + * @param {boolean} doNotPropagate if true existing widgets will not be updated. + */ + setGridWidth(gridWidth: number, doNotPropagate: boolean): void; + /** * Toggle the grid static state. Also toggle the grid-stack-static class. * @param {boolean} staticValue if true the grid become static. */ - setStatic(staticValue: boolean): void + setStatic(staticValue: boolean): void; + /** * Updates widget position/size. - * @param {HTMLElement} el widget to modify + * @param {GridStackElement} el widget to modify * @param {number} x new position x. If value is null or undefined it will be ignored. * @param {number} y new position y. If value is null or undefined it will be ignored. * @param {number} width new dimensions width. If value is null or undefined it will be ignored. * @param {number} height new dimensions height. If value is null or undefined it will be ignored. */ - update(el: HTMLElement, x: number, y: number, width: number, height: number): void + update(el: GridStackElement, x: number, y: number, width: number, height: number): void; + /** - * Sets the vertial margin - * @param {number} value new vertical margin value. - * @param {boolean} noUpdate if true, styles will not be updated. - */ - verticalMargin(value: number, noUpdate: boolean): void + * returns current vertical margin value + */ + verticalMargin(): number; + /** - * Returns true if the height of the grid will be less the vertical constraint. Always returns true if grid doesn't have height constraint. + * Updates the vertical margin - see `GridstackOptions.verticalMargin` for format options. + * + * @param {number | string} value new vertical margin value + * @param {boolean} noUpdate (optional) if true, styles will not be updated + */ + verticalMargin(value: number | string, noUpdate?: boolean): void; + + /** + * Returns true if the height of the grid will be less the vertical + * constraint. Always returns true if grid doesn't have height constraint. * @param {number} x new position x. If value is null or undefined it will be ignored. * @param {number} y new position y. If value is null or undefined it will be ignored. * @param {number} width new dimensions width. If value is null or undefined it will be ignored. - * @param {number} height new dimensions height. If value is null or undefined it will be ignored. - * @param {boolean} autoPosition if true then x, y parameters will be ignored and widget will be places on the first available position + * @param {number} height new dimensions height. If value is null or undefined it will be ignored. + * @param {boolean} autoPosition if true then x, y parameters will be ignored and widget + * will be places on the first available position + * + * @example + * if (grid.willItFit(newNode.x, newNode.y, newNode.width, newNode.height, true)) { + * grid.addWidget(newNode.el, newNode.x, newNode.y, newNode.width, newNode.height, true); + * } else { + * alert('Not enough free space to place the widget'); + * } */ - willItFit(x: number, y: number, width: number, height: number, autoPosition: boolean): boolean - - - + willItFit(x: number, y: number, width: number, height: number, autoPosition: boolean): boolean; } + /** -* Defines the coordiantes of a object -*/ + * Defines the coordinates of an object + */ interface MousePosition { - top: number, - left: number, + top: number; + left: number; } + /** -* Defines the position of a cell inside the grid -*/ + * Defines the position of a cell inside the grid + */ interface CellPosition { - x: number, - y: number + x: number; + y: number; } + declare namespace GridStackUI { interface Utils { /** * Sorts array of nodes - *@param nodes array to sort - *@param dir 1 for asc, -1 for desc (optional) - *@param width width of the grid. If undefined the width will be calculated automatically (optional). + * @param nodes array to sort + * @param dir 1 for asc, -1 for desc (optional) + * @param width width of the grid. If undefined the width will be calculated automatically (optional). **/ - sort(nodes: HTMLElement[], dir?: number, width?: number): void + sort(nodes: HTMLElement[], dir?: number, width?: number): void; } } + /** -* Gridstack Options -* Defines the options for a Gridstack -*/ -interface IGridstackOptions { + * Gridstack Options + * Defines the options for a Gridstack + */ +interface GridstackOptions { /** - * if true of jquery selector the grid will accept widgets dragged from other grids or from outside (default: false) - */ - acceptWidgets?: boolean; + * if true of jquery selector the grid will accept widgets dragged from other grids or from + * outside (default: false) See [example](http://gridstack.github.io/gridstack.js/demo/two.html) + */ + acceptWidgets?: boolean | string | ((i: number, element: Element) => boolean | string); + /** - * if true the resizing handles are shown even if the user is not hovering over the widget (default: false) - */ + * if true the resizing handles are shown even if the user is not hovering over the widget (default?: false) + */ alwaysShowResizeHandle?: boolean; + /** - * turns animation on (default: true) - */ + * turns animation on (default?: true) + */ animate?: boolean; + /** - * if false gridstack will not initialize existing items (default: true) - */ + * if false gridstack will not initialize existing items (default?: true) + */ auto?: boolean; + /** - * one cell height (default: 60) - */ - cellHeight?: number; + * one cell height (default?: 60). Can be: + * an integer (px) + * a string (ex: '10em', '100px', '10rem') + * 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 from cell width. + */ + cellHeight?: number | string; + /** - * class that implement drag'n'drop functionallity for gridstack. - * If false grid will be static. (default: null - first available plugin will be used) - */ - ddPlugin?: any; - /** - * disallows dragging of widgets (default: false). - */ + * (internal?) unit for cellHeight (default? 'px') + */ + cellHeightUnit?: string; + + /** class that implement drag'n'drop functionality for gridstack. If false grid will be static. + * (default?: null - first available plugin will be used) + */ + ddPlugin?: boolean | null | any; + + /** disallows dragging of widgets (default?: false) */ disableDrag?: boolean; - /** - * disallows resizing of widgets (default: false). - */ + + /** disallows resizing of widgets (default?: false). */ disableResize?: boolean; + /** - * allows to override jQuery UI draggable options. (default: { handle: '.grid-stack-item-content', scroll: true, appendTo: 'body' }) - */ + * allows to override jQuery UI draggable options. (default?: { handle?: '.grid-stack-item-content', scroll?: true, appendTo?: 'body' }) + */ draggable?: {}; + /** - * draggable handle selector (default: '.grid-stack-item-content') + * draggable handle selector (default?: '.grid-stack-item-content') */ handle?: string; - /** - * draggable handle class (e.g. 'grid-stack-item-content'). If set handle is ignored (default: null) - */ + + /** draggable handle class (e.g. 'grid-stack-item-content'). If set 'handle' is ignored (default?: null) */ handleClass?: string; + /** - * maximum rows amount.Default is 0 which means no maximum rows + * maximum rows amount. Default? is 0 which means no maximum rows */ height?: number; + /** - * enable floating widgets (default: false) See example + * enable floating widgets (default?: false) See example (http://gridstack.github.io/gridstack.js/demo/float.html) */ float?: boolean; + /** - * widget class (default: 'grid-stack-item') + * widget class (default?: 'grid-stack-item') */ itemClass?: string; + /** - * minimal width.If window width is less, grid will be shown in one - column mode (default: 768) + * minimal width. If window width is less, grid will be shown in one - column mode (default?: 768) */ minWidth?: number; - /** - * disables the onColumnMode when the window width is less than minWidth (default: 'false') - */ + + /** disables the onColumnMode when the window width is less than minWidth (default?: false) */ disableOneColumnMode?: boolean; + /** - * class set on grid when in one column mode (default: 'grid-stack-one-column-mode') - */ + * class set on grid when in one column mode (default?: 'grid-stack-one-column-mode') + */ oneColumnModeClass?: string; + /** - * class for placeholder (default: 'grid-stack-placeholder') + * class for placeholder (default?: 'grid-stack-placeholder') */ placeholderClass?: string; - /** - * placeholder default content (default: '') - */ + + /** placeholder default content (default?: '') */ placeholderText?: string; + /** - * allows to override jQuery UI resizable options. (default: { autoHide: true, handles: 'se' }) + * allows to override jQuery UI resizable options. (default?: { autoHide?: true, handles?: 'se' }) */ resizable?: {}; + /** - * if true widgets could be removed by dragging outside of the grid. It could also be a jQuery selector string, - */ + * if true widgets could be removed by dragging outside of the grid. It could also be a jQuery selector string, + * in this case widgets will be removed by dropping them there (default?: false) + * See example (http://gridstack.github.io/gridstack.js/demo/two.html) + */ removable?: boolean | string; + /** - * time in milliseconds before widget is being removed while dragging outside of the grid. (default: 2000) - */ + * time in milliseconds before widget is being removed while dragging outside of the grid. (default?: 2000) + */ removeTimeout?: number; + /** - * if true turns grid to RTL. Possible values are true, false, 'auto' (default: 'auto') - */ + * if true turns grid to RTL. Possible values are true, false, 'auto' (default?: 'auto') + * See [example](http://gridstack.github.io/gridstack.js/demo/rtl.html) + */ rtl?: boolean | 'auto'; + /** - * makes grid static (default false).If true widgets are not movable/ resizable.You don't even need jQueryUI draggable/resizable. A CSS class grid-stack-static is also added to the container. + * makes grid static (default?: false).If true widgets are not movable/resizable. + * You don't even need jQueryUI draggable/resizable. A CSS class + * 'grid-stack-static' is also added to the container. */ staticGrid?: boolean; + /** - * vertical gap size (default: 20) + * vertical gap size (default?: 20). Can be: + * an integer (px) + * a string (ex: '2em', '20px', '2rem') */ - verticalMargin?: number; + verticalMargin?: number | string; + /** - * amount of columns (default: 12) + * (internal?) unit for verticalMargin (default? 'px') + */ + verticalMarginUnit?: string; + + /** + * number of columns (default?: 12) */ width?: number; }