feat!: pure SVG icons, Moment to Tempo, Flatpickr to Vanilla-Calendar (…

…#1518)

* feat!: pure SVG icons, Moment to Tempo, Flatpickr to Vanilla-Calendar

.vscode/settings.json

@@ -3,5 +3,6 @@
     "javascript",
     "typescript"
   ],
-  "typescript.format.semicolons": "insert"
+  "typescript.format.semicolons": "insert",
+  "typescript.tsdk": "node_modules\\typescript\\lib"
 }

docs/TOC.md

@@ -6,6 +6,7 @@
 
 * [Quick start](getting-started/quick-start.md)
 * [Salesforce (LWC)](getting-started/installation-salesforce.md)
+* [Vanilla Installation](getting-started/installation-vanilla.md)
 
 ## Styling
 
@@ -18,6 +19,7 @@
 * [Editors](column-functionalities/Editors.md)
   * [new Autocomplete (Kraaden-lib)](column-functionalities/editors/Autocomplete-Editor-(Kraaden-lib).md)
   * [Date Picker (flatpickr)](column-functionalities/editors/Date-Editor-(flatpickr).md)
+  * [Date Picker (vanilla-calendar)](column-functionalities/editors/date-editor-(vanilla-calendar).md)
   * [LongText (textarea)](column-functionalities/editors/LongText-Editor-(textarea).md)
   * [Select Dropdown Editor (single/multiple)](column-functionalities/editors/Select-Dropdown-Editor-(single,multiple).md)
 * [Filters](column-functionalities/filters/README.md)
@@ -76,3 +78,4 @@
 * [Migration Guide to 2.x](migrations/migration-to-2.x.md)
 * [Migration Guide to 3.x](migrations/migration-to-3.x.md)
 * [Migration Guide to 4.x](migrations/migration-to-4.x.md)
+* [Migration Guide to 5.x](migrations/migration-to-5.x.md)

docs/column-functionalities/Cell-Menu.md

@@ -38,7 +38,7 @@ this.columnDefinitions = [
             console.log(args.dataContext, args.column); // action callback.. do something
           }
         },
-        { command: 'help', title: 'HELP', iconCssClass: 'fa fa-question-circle', positionOrder: 62 },
+        { command: 'help', title: 'HELP', iconCssClass: 'mdi mdi-help-circle', positionOrder: 62 },
         // you can add sub-menus by adding nested `commandItems`
         {
          // we can also have multiple nested sub-menus
@@ -74,8 +74,8 @@ this.columnDefinitions = [
     cellMenu: {
       optionTitle: 'Change Effort Driven Flag', // optional, add title
       optionItems: [
-        { option: true, title: 'True', iconCssClass: 'fa fa-check-square-o' },
-        { option: false, title: 'False', iconCssClass: 'fa fa-square-o' },
+        { option: true, title: 'True', iconCssClass: 'mdi mdi-check-box-outline' },
+        { option: false, title: 'False', iconCssClass: 'mdi mdi-checkbox-blank-outline' },
         { divider: true, command: '', positionOrder: 60 },
       ],
       // subscribe to Context Menu onOptionSelected event (or use the "action" callback on each option)
@@ -153,7 +153,7 @@ this.columnDefinitions = [
   { id: 'action', field: 'action', name: 'Action',
     cellMenu: {
       menuUsabilityOverride: (args) => {
-        const dataContext = args && args.dataContext;
+        const dataContext = args?.dataContext;
         return (dataContext.id < 21); // say we want to display the menu only from Task 0 to 20
       },
     }
@@ -163,24 +163,22 @@ this.columnDefinitions = [
 
 To give another example, with Options this time, we could say that we enable the `n/a` option only when the row is Completed. So we could do it this way
 ```ts
-this.columnDefinitions = [
-  { id: 'action', field: 'action', name: 'Action',
-    cellMenu: {
-      optionItems: [
-      {
-        option: 0, title: 'n/a', textCssClass: 'italic',
-        // only enable this option when the task is Not Completed
-        itemUsabilityOverride: (args) => {
-          const dataContext = args && args.dataContext;
-          return !dataContext.completed;
-        },
-        { option: 1, iconCssClass: 'fa fa-star-o yellow', title: 'Low' },
-        { option: 2, iconCssClass: 'fa fa-star-half-o orange', title: 'Medium' },
-        { option: 3, iconCssClass: 'fa fa-star red', title: 'High' },
-      ]
-    }
+this.columnDefinitions = [{ 
+  id: 'action', field: 'action', name: 'Action',
+  cellMenu: {
+    optionItems: [{
+      option: 0, title: 'n/a', textCssClass: 'italic',
+      // only enable this option when the task is Not Completed
+      itemUsabilityOverride: (args) => {
+        const dataContext = args?.dataContext;
+        return !dataContext.completed;
+      },
+      { option: 1, iconCssClass: 'mdi mdi-star-outline yellow', title: 'Low' },
+      { option: 2, iconCssClass: 'mdi mdi-star orange', title: 'Medium' },
+      { option: 3, iconCssClass: 'mdi mdi-star red', title: 'High' },
+    }]
   }
-];
+}];
 ```
 
 ### How to add Translations?
@@ -191,9 +189,9 @@ this.columnDefinitions = [
     cellMenu: {
       optionTitleKey: 'COMMANDS', // optionally pass a title to show over the Options
       optionItems: [
-        { option: 1, titleKey: 'LOW', iconCssClass: 'fa fa-star-o yellow' },
-        { option: 2, titleKey: 'MEDIUM', iconCssClass: 'fa fa-star-half-o orange' },
-        { option: 3, titleKey: 'HIGH', iconCssClass: 'fa fa-star red' },
+        { option: 1, titleKey: 'LOW', iconCssClass: 'mdi mdi-star-outline yellow' },
+        { option: 2, titleKey: 'MEDIUM', iconCssClass: 'mdi mdi-star orange' },
+        { option: 3, titleKey: 'HIGH', iconCssClass: 'mdi mdi-star red' },
       ]
     }
   }

docs/column-functionalities/Editors.md

@@ -108,7 +108,7 @@ this.columnDefinitions = [
 ];
 ```
 
-So to make it more clear, the `saveOutputType` is the format that will be sent to the `onCellChange` event, then the `outputType` is how the date will show up in the date picker (Flatpickr) and finally the `type` is basically the input format (coming from your dataset). Note however that each property are cascading, if 1 property is missing it will go to the next one until 1 is found... for example, on the `onCellChange` if you aren't defining `saveOutputType`, it will try to use `outputType`, if again none is provided it will try to use `type` and finally if none is provided it will use `FieldType.dateIso` as the default.
+So to make it more clear, the `saveOutputType` is the format that will be sent to the `onCellChange` event, then the `outputType` is how the date will show up in the date picker (Vanilla-Calendar) and finally the `type` is basically the input format (coming from your dataset). Note however that each property are cascading, if 1 property is missing it will go to the next one until 1 is found... for example, on the `onCellChange` if you aren't defining `saveOutputType`, it will try to use `outputType`, if again none is provided it will try to use `type` and finally if none is provided it will use `FieldType.dateIso` as the default.
 
 ## Perform an action After Inline Edit
 #### Recommended way
@@ -201,9 +201,9 @@ Some of the Editors could receive extra options, which is mostly the case for Ed
 ```ts
 this.columnDefinitions = [{
   id: 'start', name: 'Start Date', field: 'start',
-  editor: { 
+  editor: {
     model: Editors.date,
-    editorOptions: { minDate: 'today' }
+    editorOptions: { range: { min: 'today' } } as VanillaCalendarOption
   }
 }];
 ```
@@ -213,10 +213,10 @@ You could also define certain options as a global level (for the entire grid or
 
 ```ts
 this.gridOptions = {
-  defaultEditorOptions: { 
+  defaultEditorOptions: {
     autocompleter: { debounceWaitMs: 150 }, // typed as AutocompleterOption
-    date: { minDate: 'today' },
-    longText: { cols: 50, rows: 5 } 
+    date: { range: { min: 'today' } },
+    longText: { cols: 50, rows: 5 }
   }
 }
 ```

docs/column-functionalities/Formatters.md

@@ -13,19 +13,18 @@
 ### Definition
 `Formatters` are functions that can be used to change and format certain column(s) in the grid. Please note that it does not alter the input data, it simply changes the styling by formatting the data differently to the screen (what the user visually see).
 
-A good example of a `Formatter` could be a column name `isActive` which is a `boolean` field with input data as `True` or `False`. User would prefer to simply see a checkbox as a visual indication representing the `True` flag, for this behavior you can use `Formatters.checkmark` which will use [Font-Awesome](http://fontawesome.io/icons/) icon of `fa-check` when `True` or an empty string when `False`.
+A good example of a `Formatter` could be a column name `isActive` which is a `boolean` field with input data as `True` or `False`. User would prefer to simply see a checkbox as a visual indication representing the `True` flag, for this behavior you can use `Formatters.checkmarkMaterial` which will use optional SVG icons of `mdi-check` when `True` or an empty string when `False`.
 
 For a [UI sample](#ui-sample), scroll down below.
 
 ### Provided Formatters
 `Slickgrid-Universal` ships with a few `Formatters` by default which helps with common fields, you can see the [entire list here](https://github.com/ghiscoding/slickgrid-universal/blob/master/packages/common/src/formatters/index.ts#L37).
 
-> **Note** you might not need a Formatter when a simple CSS style is needed, think about using `cssClass` column property instead.
+> **Note** you might not need a Formatter when a simple CSS style and class might be enough, think about using `cssClass` column property as much as possible since it has much better perf.
 
 #### List of provided `Formatters`
 - `arrayObjectToCsv`: Takes an array of complex objects converts it to a comma delimited string.
 - `arrayToCsv` : takes an array of text and returns it as CSV string
-- `checkmark` : uses Font-Awesome [(fa-check)](http://fontawesome.io/icon/check/)
 - `checkmarkMaterial` use Material Design to display a checkmark icon
 - `collection`: Looks up values from the columnDefinition.params.collection property and displays the label in CSV or string format
 - `complexObject`: takes a complex object (with a `field` that has a `.` notation) and pull correct value, there are multiple ways to use it
@@ -47,6 +46,7 @@ For a [UI sample](#ui-sample), scroll down below.
 - `dateTimeUs` : Takes a Date object and displays it as an US Date+Time format (MM/DD/YYYY HH:mm:ss)
 - `dateTimeShortUs`: Takes a Date object and displays it as an US Date+Time (without seconds) format (MM/DD/YYYY HH:mm:ss)
 - `dateTimeUsAmPm` : Takes a Date object and displays it as an US Date+Time+(am/pm) format (MM/DD/YYYY hh:mm:ss a)
+- `dateUtc` : Takes a Date object and displays it as a TZ format (YYYY-MM-DDThh:mm:ssZ)
 - `decimal`: Display the value as x decimals formatted, defaults to 2 decimals. You can pass "minDecimal" and/or "maxDecimal" to the "params" property.
 - `dollar`: Display the value as 2 decimals formatted with dollar sign '$' at the end of of the value.
 - `dollarColored`: Display the value as 2 decimals formatted with dollar sign '$' at the end of of the value, change color of text to red/green on negative/positive value
@@ -71,10 +71,12 @@ For a [UI sample](#ui-sample), scroll down below.
 - `translateBoolean`: Takes a boolean value, cast it to upperCase string and finally translates it (i18n).
 - `tree`: Formatter that must be used when the column is a Tree Data column
 
-**Note:** The list might not always be up to date, you can refer to the [Formatters export](https://github.com/ghiscoding/slickgrid-universal/blob/master/packages/common/src/formatters/index.ts#L37) to know exactly which ones are available.
+> **Note:** The list is certainly not up to date (especially for Dates), please refer to the [Formatters export](https://github.com/ghiscoding/slickgrid-universal/blob/master/packages/common/src/formatters/index.ts#L37) to know exactly which formatters are available.
+
+> **Note** all Date formatters are formatted using [Tempo](https://tempo.formkit.com/#format-tokens). There are also many more Date formats not shown above, simply visit the [formatters.index](https://github.com/ghiscoding/slickgrid-universal/blob/master/packages/common/src/formatters/formatters.index.ts#L101) to see all available Date/Time formats.
 
 ### Usage
-To use any of them, you need to import `Formatters` from `Slickgrid-Universal` and add a `formatter: ...` in your column definitions as shown below:
+To use any of them, you simply need to import `Formatters` from `Slickgrid-Universal` and add a `formatter: Formatters.xyz` (where `xyx` is the name of the built-in formatter) in your column definitions as shown below:
 
 #### TypeSript
 ```ts
@@ -97,39 +99,7 @@ export class Example {
       { id: '%', name: '% Complete', field: 'percentComplete', formatter: Formatters.percentComplete },
       { id: 'start', name: 'Start', field: 'start', formatter: Formatters.dateIso },
       { id: 'finish', name: 'Finish', field: 'finish', formatter: Formatters.dateIso },
-      { id: 'effort-driven', name: 'Effort Driven', field: 'effortDriven', formatter: Formatters.checkmark }
-    ];
-  }
-}
-```
-
-#### SalesForce (ES6)
-For SalesForce the code is nearly the same, the only difference is to add the `Slicker` prefix, so instead of `Formatters.abc` we need to use `Slicker.Formatters.abc`
-
-```ts
-// ... SF_Slickgrid import
-
-
-export class Example {
-  const Slicker = window.Slicker;
-
-  columnDefinitions: Column[];
-  gridOptions: GridOption;
-  dataset: any[];
-
-  constructor() {
-    // define the grid options & columns and then create the grid itself
-    this.defineGrid();
-  }
-
-  defineGrid() {
-    this.columnDefinitions = [
-      { id: 'title', name: 'Title', field: 'title' },
-      { id: 'duration', name: 'Duration (days)', field: 'duration' },
-      { id: '%', name: '% Complete', field: 'percentComplete', formatter: Slicker.Formatters.percentComplete },
-      { id: 'start', name: 'Start', field: 'start', formatter: Slicker.Formatters.dateIso },
-      { id: 'finish', name: 'Finish', field: 'finish', formatter: Slicker.Formatters.dateIso },
-      { id: 'effort-driven', name: 'Effort Driven', field: 'effortDriven', formatter: Slicker.Formatters.checkmark }
+      { id: 'effort-driven', name: 'Effort Driven', field: 'effortDriven', formatter: Formatters.checkmarkMaterial }
     ];
   }
 }
@@ -191,19 +161,21 @@ export interface FormatterResultObject {
 ```
 
 ### Example of a Custom Formatter with HTML string
-For example, we will use `Font-Awesome` with a `boolean` as input data, and display a (fire) icon when `True` or a (snowflake) when `False`. This custom formatter is actually display in the [UI sample](#ui-sample) shown below.
+
+For example, we will use our optional SVG icons `.mdi` with a `boolean` as input data, and display a (fire) icon when `True` or a (snowflake) when `False`. This custom formatter is actually display in the [UI sample](#ui-sample) shown below.
+
 ```ts
 // create a custom Formatter with the Formatter type
 const myCustomCheckboxFormatter: Formatter = (row: number, cell: number, value: any, columnDef: Column, dataContext: any) =>
-  value ? `<i class="fa fa-fire" aria-hidden="true"></i>` : '<i class="fa fa-snowflake-o" aria-hidden="true"></i>';
+  value ? `<i class="mdi mdi-fire" aria-hidden="true"></i>` : '<i class="mdi mdi-snowflake" aria-hidden="true"></i>';
 ```
 
 #### Example with `FormatterResultObject` instead of a string
 Using this object return type will provide the user the same look and feel, it will actually be quite different. The major difference is that all of the options (`addClasses`, `tooltip`, ...) will be added the CSS container of the cell instead of the content of that container. For example a typically cell looks like the following `<div class="slick-cell l4 r4">Task 4</div>` and if use `addClasses: 'red'`, it will end up being `<div class="slick-cell l4 r4 red">Task 4</div>` while if we use a string output of let say `<span class="red">${value></span>`, then our final result of the cell will be `<div class="slick-cell l4 r4"><span class="red">Task 4</span></div>`. This can be useful if you plan to use multiple Formatters and don't want to lose or overwrite the previous Formatter result (we do that in our project).
 ```ts
 // create a custom Formatter and returning a string and/or an object of type FormatterResultObject
 const myCustomCheckboxFormatter: Formatter = (row: number, cell: number, value: any, columnDef: Column, dataContext: any, grid?: any) =>
-  value ? { addClasses: 'fa fa-fire', text: '', tooltip: 'burning fire' } : '<i class="fa fa-snowflake-o" aria-hidden="true"></i>';
+  value ? { addClasses: 'mdi mdi-fire', text: '', tooltip: 'burning fire' } : '<i class="mdi mdi-snowflake" aria-hidden="true"></i>';
 ```
 
 ### Example of Custom Formatter with Native DOM Element
@@ -212,7 +184,7 @@ Since version 4.x, you can now also return native DOM element instead of an HTML
 2. Performance (the reasons are similar to point 1.)
    - since it's native it can be appended directly to the grid cell
    - when it's an HTML string, it has to do 2 extra steps (which is an overhead process)
-      i. sanitize the string (we use [DOMPurify](https://github.com/cure53/DOMPurify) by default)
+      i. sanitize the string (when a sanitizer, for example [DOMPurify](https://github.com/cure53/DOMPurify))
       ii. SlickGrid then has to convert it to native element by using `innerHTML` on the grid cell
 
 Demo

docs/column-functionalities/editors/Autocomplete-Editor-(Kraaden-lib).md

@@ -276,11 +276,6 @@ export class GridBasicComponent {
           editorOptions: {
             showOnFocus: true,
             minLength: 1,
-            classes: {
-              // choose a custom style layout
-              // 'ui-autocomplete': 'autocomplete-custom-two-rows',
-              'ui-autocomplete': 'autocomplete-custom-four-corners',
-            },
             fetch: (searchText, updateCallback) => {
               yourAsyncApiCall(searchText) // typically you'll want to return no more than 10 results
                  .then(result => updateCallback((results.length > 0) ? results : [{ label: 'No match found.', value: '' }]); })

docs/column-functionalities/editors/Date-Editor-(flatpickr).md

@@ -41,8 +41,8 @@ You could also define certain options as a global level (for the entire grid or
 
 ```ts
 this.gridOptions = {
-  defaultEditorOptions: { 
-    date: { minDate: 'today' }, // typed as FlatpickrOption
+  defaultEditorOptions: {
+    date: { range: { min: 'today' } }, // typed as FlatpickrOption
   }
 }
 ```