jspreadsheet 10.9.6 → 11.0.0-beta.10

package/dist/index.d.ts

@@ -1,12 +1,14 @@
 /**
- * Official Type definitions for Jspreadsheet Pro v10
- * https://jspreadsheet.com/v10
+ * Official Type definitions for Jspreadsheet Pro v11
+ * https://jspreadsheet.com/docs
  */
 
-declare function jspreadsheet(element: HTMLElement, options: jspreadsheet.Spreadsheet) : Array<jspreadsheet.worksheetInstance>;
+declare function jspreadsheet(element: HTMLElement|HTMLDivElement|null, options: jspreadsheet.Spreadsheet) : Array<jspreadsheet.worksheetInstance>;
 
 declare namespace jspreadsheet {
 
+    /** ClientID */
+    let clientId: string;
     /** License string. Use setLicense to define the license */
     let license: string;
     /** Default row height for a table */
@@ -21,12 +23,16 @@ declare namespace jspreadsheet {
     let helpers: Helpers;
     /** Native editors. You can have extra entries not defined here when working with custom editors */
     let editors: Editors;
-    /** Internal method */
-    let picker: Function;
     /** History tracker controllers */
     let history: History;
     /** Clipboard controller */
     let clipboard: ClipBoard;
+    /** Get the worksheet instance by its name */
+    function getWorksheetInstanceByName(worksheetName: string, namespace?: string) : worksheetInstance;
+
+    /** Picker */
+    function picker(el: HTMLElement, options: PickerOptions) :  void;
+
     /** Pause calculations */
     function calculations(state: boolean) : void;
 
@@ -34,14 +40,17 @@ declare namespace jspreadsheet {
     function setDictionary(dictionary: object) : void;
 
     /** Set the license */
-    function setLicense(license: string) : void;
+    function setLicense(license: string|object) : void;
 
-    /** Set extensions to the JSS spreadsheet. Example { formula, parser, render } */
-    function setExtensions(extensions: object) : void;
+    /** Set extensions to the JSS spreadsheet or null to disable all extensions. Example { formula, parser, render } */
+    function setExtensions(extensions: object | null) : void;
 
     /** Destroy the spreadsheet. Full destroy will clear all JSS controllers and is not possible to re-create a new spreadsheet if true is used, until refresh the page. */
     function destroy(element: HTMLElement | spreadsheetInstance, fullDestroy?: boolean) : void;
 
+    /** Destroy all the spreadsheets in all namespaces **/
+    function destroyAll() : void;
+
     /** Jspreadsheet parser extension. More info at: https://jspreadsheet.com/products */
     function parser(options: any) : void;
 
@@ -69,6 +78,15 @@ declare namespace jspreadsheet {
     /** Get the current version */
     function version(): object;
 
+    interface PickerOptions {
+        // picker creates a range selection component. formula expect to be a formula starting with '='
+        type?: 'formula' | 'picker';
+        // When the value is changed
+        onchange?: (element: HTMLElement, mouseEvent: object) => void;
+        // Each time the selection is updated
+        onupdate?: (element: HTMLElement, mouseEvent: object) => void;
+    }
+
     interface ClipBoard {
         worksheet: worksheetInstance,
         value: string,
@@ -245,14 +263,16 @@ declare namespace jspreadsheet {
         getTokensFromRange: (range: string) => string[];
         // Get the range from an array of tokens
         getRangeFromTokens: (tokens: string[]) => string;
-        // Get the coordinates as a number from a range string
-        getCoordsFromRange: (range: string) => [number,number,number,number];
+        // Get the coordinates as a number from a range string. Adjust helps to define the height dynamically when you have A:A ranges for example. Works in the same way for 1:1 ranges.
+        getCoordsFromRange: (range: string, adjust?: boolean) => [number,number,number,number];
         // Get range string from [x1,y1,x2,y2]
         getRangeFromCoords: (coords: [number,number,number,number]) => string;
         // Extract the configuration from JSS from a static HTML table
         createFromTable: (element: HTMLElement, options?: Worksheet) => Worksheet;
         // CSV string to JS array. delimiter default ','
         parseCSV: (str: string, delimiter?: string) => string[];
+        // Get all token names inside an range
+        getTokensFromCoords: (x1: number, y1: number, x2: number, y2: number, worksheetName?: string) => []
     }
 
     interface Tabs {
@@ -519,6 +539,45 @@ declare namespace jspreadsheet {
         state?: boolean;
     }
 
+    interface Cell {
+        /** Define the type of editor to use for the column. Can be a string to define a native editor, or a method to define a custom editor plugin. */
+        type?: Editor | 'text' | 'number' | 'numeric' | 'percent' | 'notes' | 'dropdown' | 'autocomplete' | 'calendar' | 'color' | 'checkbox' | 'radio' | 'autonumber' | 'progressbar' | 'rating' | 'email' | 'url' | 'image' | 'html' | 'hidden' | 'tags' | 'record';
+        /** The title of the column. */
+        title?: string;
+        /** Define the tooltip text to display on mouseover for the column header. */
+        tooltip?: string;
+        /** The alignment of the column content. Default: center. */
+        align?: 'center' | 'left' | 'right' | 'justify';
+        /** The items to show in the dropdown or autocomplete. */
+        source?: Array<DropdownItem> | Array<string> | Array<number>;
+        /** Whether the column is an autocomplete field. */
+        autocomplete?: boolean;
+        /** Whether the dropdown or autocomplete can accept multiple options. */
+        multiple?: boolean;
+        /** The delimiter to use for separating multiple dropdown options. Default: ";". */
+        delimiter?: string;
+        /** The input mask to apply to the data cell. @see https://jsuites.net/v4/javascript-mask */
+        mask?: string;
+        /** The character to use as the decimal separator. */
+        decimal?: '.' | ',';
+        /** The maximum number of characters to display in the cell before truncating. */
+        truncate?: number,
+        /** Whether to disable the mask when editing. */
+        disabledMaskOnEdition?: boolean;
+        /** A renderer method or rule for the cell content. */
+        render?: string | ((td: HTMLElement, value: number|string, x: number, y: number, worksheet: worksheetInstance, options: Column) => void);
+        /** The format of the date or numbers in the cell. Default for the calendar: "DD/MM/YYYY". */
+        format?: string;
+        /** Locale for Intl.NumberFormat */
+        locale?: string,
+        /** Extended configuration for the column. */
+        options?: Calendar | Dropdown | object;
+        /** Whether the column is read-only. */
+        readOnly?: boolean;
+        /** The rotation angle for the text value, between -90 and 90. Default: null. */
+        rotate?: number;
+    }
+
     interface Border {
         /** HTML Element for the border */
         element: HTMLElement;
@@ -700,8 +759,8 @@ declare namespace jspreadsheet {
         onbeforechange?: (worksheet: worksheetInstance, cell: HTMLElement, x: number, y: number, value: any) => boolean | any;
         /** After a column value is changed. */
         onchange?: (worksheet: worksheetInstance, cell: HTMLElement, x: number, y: number, newValue: any, oldValue: any) => void;
-        /** Event: onafterchanges(jspreadsheetHTMLElement, jspreadsheetInstance) */
-        onafterchanges?: (worksheet: worksheetInstance, records: Array<any>) => void;
+        /** When all data have been updated. Origin: 'paste', 'handle-fill' or undefined */
+        onafterchanges?: (worksheet: worksheetInstance, records: Array<any>, origin: string) => void;
         /** When a copy is performed in the spreadsheet. Any string returned will overwrite the user data or return null to progress with the default behavior. */
         oncopy?: (worksheet: worksheetInstance, selectedCells: Array<number>, data: string, cut: boolean) => boolean | string;
         /** Before the paste action is performed. Can return parsed or filtered data. It is possible to cancel the action when the return is false. */
@@ -838,10 +897,12 @@ declare namespace jspreadsheet {
         onopencolumngroup?: (worksheet: object, column: number) => void
         /** When close a column group */
         onclosecolumngroup?: (worksheet: object, column: number) => void
-        /** Onchangemedia brings the new values and the affected objects */
+        /** When a media object is added, removed or updated. */
         onchangemedia?: (worksheet: object, newValue: object[], oldValue: object, affectedRecords: object[]) => void
+        /** Before loading an image */
+        onbeforeloadimage?: (worksheet: object, img: HTMLElement, options: object) => undefined | string | boolean;
         /** Update references. When a table structure changes */
-        onchangereferences?: (worksheet: object, affected: object, deletedTokens: string[], deletedColumns: string[]) => void;
+        onchangereferences?: (worksheet: object, affected: object, deletedTokens: string[], deletedColumns: string[], deletedRows: string[]) => void;
         /** General event handler */
         onevent?: (worksheet: worksheetInstance, method: string, a?: any, b?: any, c?: any, d?: any, e?: any, f?: any) => any
         /** Return false to cancel the contextMenu event, or return custom elements for the contextmenu. */
@@ -872,6 +933,8 @@ declare namespace jspreadsheet {
         preCalculation?: boolean;
         /** Consider the use of column name in formulas. Default: true [ For example: =Countries*10 ] */
         columnNamesInFormulas?: boolean;
+        /** Namespace help with cross-calculations conflict names */
+        namespace?: string;
     }
 
     interface Worksheet {
@@ -885,8 +948,6 @@ declare namespace jspreadsheet {
         sequence?: boolean;
         /** Load the data into a new spreadsheet from an array of rows or objects */
         data?: Array<Array<any>> | Array<Record<string, any>>;
-        /** Deprecated. Please use the data property. */
-        json?: Array<Record<string, any>>;
         /** Array with the rows properties definitions such as title, height. */
         rows?: Row[] | Record<number, Row>;
         /** The column properties define the behavior of a column and the associated editor */
@@ -950,7 +1011,7 @@ declare namespace jspreadsheet {
         /** Allow users to add comments to the cells. Default: false */
         allowComments?: boolean;
         /** Corner selection and corner data cloning. Default: true */
-        selectionCopy?: boolean;
+        fillHandle?: boolean;
         /** Merged cells. Default: null */
         mergeCells?: Record<string, any[]>;
         /** Allow search on the spreadsheet */
@@ -1017,6 +1078,8 @@ declare namespace jspreadsheet {
         media?: Media[];
         /** Cached values. This can be used to skip calculations during onload */
         cache?: Record<string, string|number>;
+        /** Zoom value. Default 1 */
+        zoom?: number;
     }
 
     interface spreadsheetInstance {
@@ -1070,8 +1133,8 @@ declare namespace jspreadsheet {
         dispatch: (...args: string[]) => void;
         /** Get the spreadsheet configuration */
         getConfig: () => Spreadsheet;
-        /** Get the worksheet index by instance  */
-        getWorksheet: (worksheetIdent: worksheetInstance) => number;
+        /** Get the worksheet index by instance or worksheetId */
+        getWorksheet: (worksheetIdent: worksheetInstance|string) => number;
         /** Get the worksheet name */
         getWorksheetName: (position: number) => string;
         /** Open a worksheet */
@@ -1100,11 +1163,13 @@ declare namespace jspreadsheet {
         refreshToolbar: () => void;
         /** Internal validations cache */
         validations: () => void;
+        /** Destroy the spreadsheet */
+        destroy: () => void;
     }
 
     interface worksheetInstance {
         /** Array with the borders information */
-        borders: Border[];
+        borders: Border[] | Border;
         /** Close the edition for one cell */
         closeEditor: (cell: HTMLElement, save: boolean) => void;
         /** Close the filters */
@@ -1203,8 +1268,8 @@ declare namespace jspreadsheet {
         getHeaders: (asArray: boolean) => Array<any>;
         /** Get the height of one row by its position when height is defined. */
         getHeight: (row?: number) => Array<number> | number;
-        /** Get the highlighted coordinates */
-        getHighlighted: () => null | Array<number>;
+        /** Bring an array of selection coordinates [x1,y1,x2,y2][]. */
+        getHighlighted: () => null | number[][];
         /** Get the data as JSON. */
         getJson: (h?: boolean, processed?: boolean, delimiter?: boolean, asJson?: boolean) => any;
         /** Get the processed data cell shown to the user by the cell name or coordinates. */
@@ -1242,15 +1307,15 @@ declare namespace jspreadsheet {
         /**
          * Get the selected cells
          * @param {boolean?} columnNameOnly - Return an array of cell names or cell DOM elements
-         * @param {boolean?} ignoreHidden - Ignore hidden cells
          */
-        getSelected: (columnNameOnly?: boolean, ignoreHidden?: boolean) => any[];
+        getSelected: (columnNameOnly?: boolean) => any[];
         /** Get the coordinates of the main selection */
-        getSelection: () => null | Array<number>;
+        getSelection: (preserveOrder?: boolean) => null | Array<number>;
         /** Get the selected columns indexes */
         getSelectedColumns: (visibleOnly?: boolean) => number[];
         /** Get the selected rows indexes. */
         getSelectedRows: (visibleOnly?: boolean) => number[];
+
         /** Get the style from a cell or all cells. getStyle() or getStyle('A1') */
         getStyle: (cellName?: string|null, onlyIndexes?: boolean) => string|object;
         /** Get value by the cell name or object. The value can be the raw or processed value. */
@@ -1293,8 +1358,8 @@ declare namespace jspreadsheet {
         isAttached: (x: number, y: number) => boolean;
         /** The worksheet is editable */
         isEditable: () => boolean;
-        /** Check if cell is readonly or not. State used to set the state */
-        isReadOnly: (cellName: string, state?: boolean) => boolean;
+        /** Check if cell is readonly or not by cellName or Coordinates. isReadonly('A1') or isReadonly(x, y) */
+        isReadOnly: (cellNameOrX: string|number, y?: number) => boolean;
         /** Verify if this coordinates is within a selection or blank for the current selection */
         isSelected: (x: number, y: number, selection?: number[]) => boolean;
         /** Navigation last */
@@ -1416,9 +1481,9 @@ declare namespace jspreadsheet {
         /** Deprecated. Alias for parent.setPlugins */
         setPlugins: (plugins: Record<string, Function>) => void;
         /** Set the properties for a column or cell */
-        setProperties: (columnNumber: number, rowNumberOrColumnSettings: number|Column, settings?: Column) => void;
+        setProperties: (columnNumber: number, rowNumberOrColumnSettings: number|Column, cellSettings?: Cell) => void;
         /** Set or reset the cell as readonly */
-        setReadOnly: (cellName: string, state: boolean) => void;
+        setReadOnly: (cellName: string|HTMLElement, state: boolean) => void;
         /** Set the data from one row */
         setRowData: (row: number, data: any[], force: boolean) => void;
         /** Set the row id from its position */
@@ -1480,8 +1545,6 @@ declare namespace jspreadsheet {
         updateCell: (x: number, y: number, value: string, force?: boolean) => void;
         /** Internal method: update cells in a batch */
         updateCells: (o: Array<Record<string, object>>) => void;
-        /** Update the selection based on two DOM cell elements */
-        updateSelection: (el1: HTMLElement, el2?: HTMLElement, origin?: boolean) => void;
         /** Update the selection based on coordinates */
         updateSelectionFromCoords: (x1: number, y1: number, x2?: number, y2?: number, origin?: boolean, type?: string, color?: string) => void;
         /** Getter/setter the value by coordinates */
@@ -1562,10 +1625,8 @@ declare namespace jspreadsheet {
         hideHeaders: () => void;
         /** Refresh the search on the viewport */
         updateSearch: () => void;
-        /** Get the worksheet index by instance or worksheetId  */
-        getWorksheet: (worksheetIdent: worksheetInstance | string) => number;
-        /** Get the worksheet name */
-        getWorksheetName: (position?: number) => string;
+        /** Get the worksheet index by instance or worksheetId */
+        getWorksheet: (worksheetIdent: worksheetInstance|string) => number;
         /** Open a worksheet */
         openWorksheet: (position?: number) => void;
         /** Create a new worksheet */
@@ -1578,10 +1639,14 @@ declare namespace jspreadsheet {
         moveWorksheet: (from: number, to: number, ignoreDomUpdates?: boolean) => void;
         /** Get the active worksheet when applicable */
         getWorksheetActive: () => number;
-        /** Get the worksheet instance by its position */
-        getWorksheetInstance: (position: number) => worksheetInstance;
+        /** Get the worksheet name */
+        getWorksheetName: (position?: number) => string;
+        /** Get the worksheet instance by its name */
+        getWorksheetInstanceByName: (worksheetName: string, namespace?: string) => worksheetInstance;
+        /** Set a worksheet state visibility */
+        setWorksheetState: (worksheetIndex: number, state: boolean) => void;
         /** Parse the toolbar definitions with defaults */
-        getToolbar: (toolbar: Toolbar) => object,
+        getToolbar: (toolbar: Toolbar) => object;
         /** Set the toolbar */
         setToolbar: (toolbar: Toolbar) => void;
         /** Show the toolbar */
@@ -1598,6 +1663,10 @@ declare namespace jspreadsheet {
         setTracking: () => void;
         /** Internal column names */
         names: object;
+        /** Set a worksheet zoom value > 0 and <= 1. */
+        setZoom: (value: number) => void;
+        /** Get the current zoom value. Default 1 */
+        getZoom: () => number;
     }
 }