feat: allow providing custom date format via base Date Formatter (#496)

Author: ghiscoding

docs/column-functionalities/formatters.md

@@ -55,6 +55,8 @@ A good example of a `Formatter` could be a timestamp or a `Date` object that we
 * `Formatters.dateTimeShortUs`: Takes a Date object and displays it as an US Date+Time (without seconds) format (MM/DD/YYYY HH:mm:ss)
 * `Formatters.dateTimeUsAmPm` : Takes a Date object and displays it as an US Date+Time+(am/pm) format (MM/DD/YYYY hh:mm:ss a)
 * `Formatters.dateUtc` : Takes a Date object and displays it as a TZ format (YYYY-MM-DDThh:mm:ssZ)
+* `Formatters.date`: Base Date Formatter, this formatter is a bit different compare to other date formatter since this one requires the user to provide a custom format in `params.dateFormat`
+  - for example: `{ type: 'date', formatter: Formatters.date, params: { dateFormat: 'MMM DD, YYYY' }}`
 * `Formatters.decimal`: Display the value as x decimals formatted, defaults to 2 decimals. You can pass "minDecimal" and/or "maxDecimal" to the "params" property.
 * `Formatters.dollar`: Display the value as 2 decimals formatted with dollar sign '$' at the end of of the value.
 * `Formatters.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

docs/column-functionalities/sorting.md

@@ -4,6 +4,7 @@
 - [Custom Sort Comparer](#custom-sort-comparer)
 - [Update Sorting Dynamically](#update-sorting-dynamically)
 - [Dynamic Query Field](#dynamic-query-field)
+- [Sorting Dates](#sorting-dates)
 - [Pre-Parse Date Columns for better perf](#pre-parse-date-columns-for-better-perf)
 
 ### Demo
@@ -139,6 +140,14 @@ queryFieldNameGetterFn: (dataContext) => {
 },
 ```
 
+### Sorting Dates
+
+Date sorting should work out of the box as long as you provide the correct column field type. Note that there are various field types that can be provided and they all do different things. For the Sorting to work properly, you need to make sure to use the correct type for Date parsing to work accordingly. Below is a list of column definition types that you can provide:
+
+- `type`: input/output of date fields, or in other words, parsing/formatting dates with the field `type` provided
+- `outputType`: when a `type` is provided for parsing (i.e. from your dataset), you could use a different `outputType` to format your date differently
+- `saveOutputType`: if you already have a `type` and an `outputType` but you wish to save your date (i.e. save to DB) in yet another format
+
 ### Pre-Parse Date Columns for better perf
 ##### requires v5.8.0 and higher
 
@@ -154,11 +163,11 @@ The summary, is that we get a 10x boost **but** not only that, we also get an ex
 
 #### Usage
 
-You can use the `preParseDateColumns` grid option, it can be either set as either `boolean` or a `string` but there's big distinction between the 2 approaches (both approaches will mutate the dataset).
+You can use the `preParseDateColumns` grid option, it can be set as either a `boolean` or a `string` but there's a big distinction between the 2 approaches as shown below (note that both approaches will mutate the dataset).
 1. `string` (i.e. set to `"__"`, it will parse a `"start"` date string and assign it as a `Date` object to a new `"__start"` prop)
 2. `boolean` (i.e. parse `"start"` date string and reassign it as a `Date` object on the same `"start"` prop)
 
-> **Note** this option **does not work** with Backend Services because it simply has no effect.
+> **Note** this option **does not work** with the Backend Service API because it simply has no effect.
 
 For example if our dataset has 2 columns named "start" and "finish", then pre-parse the dataset,
 
@@ -184,7 +193,7 @@ data = [
 ]
 ```
 
-Which approach to choose? Both have pros and cons, overwriting the same props might cause problems with the column `type` that you use, you will have to give it a try yoursel. On the other hand, with the other approach, it will duplicate all date properties and take a bit more memory usage and when changing cells we'll need to make sure to keep these props in sync, however you will likely have less `type` issues.
+Which approach to choose? Both have pros and cons, overwriting the same props might cause problems with the column `type` that you use, you will have to give it a try yourself. On the other hand, with the other approach, it will duplicate all date properties and take a bit more memory usage and when changing cells we'll need to make sure to keep these props in sync, however you will likely have less `type` issues.
 
 What happens when we do any cell changes (for our use case, it would be Create/Update), for any Editors we simply subscribe to the `onCellChange` change event and we re-parse the date strings when detected. We also subscribe to certain CRUD functions as long as they come from the `GridService` then all is fine... However, if you use the DataView functions directly then we have no way of knowing when to parse because these functions from the DataView don't have any events. Lastly, if we overwrite the entire dataset, we will also detect this (via an internal flag) and the next time you sort a date then the pre-parse kicks in again.
 

src/examples/slickgrid/Example40.tsx

@@ -1,9 +1,11 @@
 import { format as dateFormatter } from '@formkit/tempo';
+import { ExcelExportService } from '@slickgrid-universal/excel-export';
 import React, { useEffect, useRef, useState } from 'react';
 import {
   Aggregators,
   type Column,
   FieldType,
+  Filters,
   Formatters,
   type GridOption,
   type Grouping,
@@ -16,6 +18,7 @@ import {
 } from '../../slickgrid-react';
 
 import './example39.scss';
+import { randomNumber } from './utilities';
 
 const FETCH_SIZE = 50;
 
@@ -43,11 +46,63 @@ const Example40: React.FC = () => {
   function defineGrid() {
     const columnDefinitions: Column[] = [
       { id: 'title', name: 'Title', field: 'title', sortable: true, minWidth: 100, filterable: true },
-      { id: 'duration', name: 'Duration (days)', field: 'duration', sortable: true, minWidth: 100, filterable: true, type: FieldType.number },
-      { id: 'percentComplete', name: '% Complete', field: 'percentComplete', sortable: true, minWidth: 100, filterable: true, type: FieldType.number },
-      { id: 'start', name: 'Start', field: 'start', formatter: Formatters.dateIso, exportWithFormatter: true, filterable: true },
-      { id: 'finish', name: 'Finish', field: 'finish', formatter: Formatters.dateIso, exportWithFormatter: true, filterable: true },
-      { id: 'effort-driven', name: 'Effort Driven', field: 'effortDriven', sortable: true, minWidth: 100, filterable: true, formatter: Formatters.checkmarkMaterial }
+      {
+        id: 'duration',
+        name: 'Duration (days)',
+        field: 'duration',
+        sortable: true,
+        minWidth: 100,
+        filterable: true,
+        type: FieldType.number,
+      },
+      {
+        id: 'percentComplete',
+        name: '% Complete',
+        field: 'percentComplete',
+        sortable: true,
+        minWidth: 100,
+        filterable: true,
+        type: FieldType.number,
+      },
+      {
+        id: 'start',
+        name: 'Start',
+        field: 'start',
+        type: FieldType.date,
+        outputType: FieldType.dateIso, // for date picker format
+        formatter: Formatters.date,
+        exportWithFormatter: true,
+        params: { dateFormat: 'MMM DD, YYYY' },
+        sortable: true,
+        filterable: true,
+        filter: {
+          model: Filters.compoundDate,
+        },
+      },
+      {
+        id: 'finish',
+        name: 'Finish',
+        field: 'finish',
+        type: FieldType.date,
+        outputType: FieldType.dateIso, // for date picker format
+        formatter: Formatters.date,
+        exportWithFormatter: true,
+        params: { dateFormat: 'MMM DD, YYYY' },
+        sortable: true,
+        filterable: true,
+        filter: {
+          model: Filters.compoundDate,
+        },
+      },
+      {
+        id: 'effort-driven',
+        name: 'Effort Driven',
+        field: 'effortDriven',
+        sortable: true,
+        minWidth: 100,
+        filterable: true,
+        formatter: Formatters.checkmarkMaterial,
+      },
     ];
     const gridOptions: GridOption = {
       autoResize: {
@@ -59,6 +114,8 @@ const Example40: React.FC = () => {
       enableGrouping: true,
       editable: false,
       rowHeight: 33,
+      enableExcelExport: true,
+      externalResources: [new ExcelExportService()],
     };
 
     setColumnDefinitions(columnDefinitions);
@@ -126,38 +183,35 @@ const Example40: React.FC = () => {
   }
 
   function newItem(idx: number) {
-    const randomYear = 2000 + Math.floor(Math.random() * 10);
-    const randomMonth = Math.floor(Math.random() * 11);
-    const randomDay = Math.floor((Math.random() * 29));
-    const randomPercent = Math.round(Math.random() * 100);
-
     return {
       id: idx,
       title: 'Task ' + idx,
       duration: Math.round(Math.random() * 100) + '',
-      percentComplete: randomPercent,
-      start: new Date(randomYear, randomMonth + 1, randomDay),
-      finish: new Date(randomYear + 1, randomMonth + 1, randomDay),
-      effortDriven: (idx % 5 === 0)
+      percentComplete: randomNumber(1, 12),
+      start: new Date(2020, randomNumber(1, 11), randomNumber(1, 28)),
+      finish: new Date(2022, randomNumber(1, 11), randomNumber(1, 28)),
+      effortDriven: idx % 5 === 0,
     };
   }
 
   function onSortReset(shouldReset: boolean) {
     shouldResetOnSortRef.current = shouldReset;
   }
 
-  function refreshMetrics(args: OnRowCountChangedEventArgs) {
+  function handleOnRowCountChanged(args: OnRowCountChangedEventArgs) {
     if (reactGridRef.current && args?.current >= 0) {
+      // we probably want to re-sort the data when we get new items
+      reactGridRef.current?.dataView?.reSort();
+
+      // update metrics
       const itemCount = reactGridRef.current?.dataView?.getFilteredItemCount() || 0;
       setMetrics({ ...metrics, itemCount, totalItemCount: args.itemCount || 0 });
     }
   }
 
   function setFiltersDynamically() {
     // we can Set Filters Dynamically (or different filters) afterward through the FilterService
-    reactGridRef.current?.filterService.updateFilters([
-      { columnId: 'percentComplete', searchTerms: ['50'], operator: '>=' },
-    ]);
+    reactGridRef.current?.filterService.updateFilters([{ columnId: 'start', searchTerms: ['2020-08-25'], operator: '<=' }]);
   }
 
   function setSortingDynamically() {
@@ -242,7 +296,7 @@ const Example40: React.FC = () => {
           gridOptions={gridOptionsRef.current}
           dataset={dataset}
           onReactGridCreated={$event => reactGridReady($event.detail)}
-          onRowCountChanged={$event => refreshMetrics($event.detail.args)}
+          onRowCountChanged={$event => handleOnRowCountChanged($event.detail.args)}
           onSort={_ => handleOnSort()}
           onScroll={$event => handleOnScroll($event.detail.args)}
         />

src/examples/slickgrid/utilities.ts

@@ -0,0 +1,9 @@
+export function randomNumber(min: number, max: number, floor = true) {
+  const number = Math.random() * (max - min + 1) + min;
+  return floor ? Math.floor(number) : number;
+}
+
+export function zeroPadding(input: string | number) {
+  const number = parseInt(input as string, 10);
+  return number < 10 ? `0${number}` : number;
+}

test/cypress/e2e/example40.cy.ts

@@ -18,44 +18,37 @@ describe('Example 40 - Infinite Scroll from JSON data', () => {
     cy.get(`[style="top: ${GRID_ROW_HEIGHT * 0}px;"] > .slick-cell:nth(0)`).should('contain', 'Task 0');
     cy.get(`[style="top: ${GRID_ROW_HEIGHT * 0}px;"] > .slick-cell:nth(1)`).contains(/[0-9]/);
     cy.get(`[style="top: ${GRID_ROW_HEIGHT * 0}px;"] > .slick-cell:nth(2)`).contains(/[0-9]/);
-    cy.get(`[style="top: ${GRID_ROW_HEIGHT * 0}px;"] > .slick-cell:nth(3)`).contains(/20[0-9]{2}-[0-9]{2}-[0-9]{2}/);
-    cy.get(`[style="top: ${GRID_ROW_HEIGHT * 0}px;"] > .slick-cell:nth(4)`).contains(/20[0-9]{2}-[0-9]{2}-[0-9]{2}/);
-    cy.get(`[style="top: ${GRID_ROW_HEIGHT * 0}px;"] > .slick-cell:nth(5)`).find('.mdi.mdi-check').should('have.length', 1);
+    cy.get(`[style="top: ${GRID_ROW_HEIGHT * 0}px;"] > .slick-cell:nth(3)`).contains('2020');
+    cy.get(`[style="top: ${GRID_ROW_HEIGHT * 0}px;"] > .slick-cell:nth(4)`).contains('2022');
+    cy.get(`[style="top: ${GRID_ROW_HEIGHT * 0}px;"] > .slick-cell:nth(5)`)
+      .find('.mdi.mdi-check')
+      .should('have.length', 1);
   });
 
   it('should scroll to bottom of the grid and expect next batch of 50 items appended to current dataset for a total of 100 items', () => {
-    cy.get('[data-test="totalItemCount"]')
-      .should('have.text', '50');
+    cy.get('[data-test="totalItemCount"]').should('have.text', '50');
 
-    cy.get('.slick-viewport.slick-viewport-top.slick-viewport-left')
-      .scrollTo('bottom');
+    cy.get('.slick-viewport.slick-viewport-top.slick-viewport-left').scrollTo('bottom');
 
-    cy.get('[data-test="totalItemCount"]')
-      .should('have.text', '100');
+    cy.get('[data-test="totalItemCount"]').should('have.text', '100');
   });
 
   it('should scroll to bottom of the grid again and expect 50 more items for a total of now 150 items', () => {
-    cy.get('[data-test="totalItemCount"]')
-      .should('have.text', '100');
+    cy.get('[data-test="totalItemCount"]').should('have.text', '100');
 
-    cy.get('.slick-viewport.slick-viewport-top.slick-viewport-left')
-      .scrollTo('bottom');
+    cy.get('.slick-viewport.slick-viewport-top.slick-viewport-left').scrollTo('bottom');
 
-    cy.get('[data-test="totalItemCount"]')
-      .should('have.text', '150');
+    cy.get('[data-test="totalItemCount"]').should('have.text', '150');
   });
 
   it('should disable onSort for data reset and expect same dataset length of 150 items after sorting by Title', () => {
     cy.get('[data-test="onsort-off"]').click();
 
-    cy.get('[data-id="title"]')
-      .click();
+    cy.get('[data-id="title"]').click();
 
-    cy.get('[data-test="totalItemCount"]')
-      .should('have.text', '150');
+    cy.get('[data-test="totalItemCount"]').should('have.text', '150');
 
-    cy.get('.slick-viewport.slick-viewport-top.slick-viewport-left')
-      .scrollTo('top');
+    cy.get('.slick-viewport.slick-viewport-top.slick-viewport-left').scrollTo('top');
 
     cy.get(`[style="top: ${GRID_ROW_HEIGHT * 0}px;"] > .slick-cell:nth(0)`).should('contain', 'Task 0');
     cy.get(`[style="top: ${GRID_ROW_HEIGHT * 1}px;"] > .slick-cell:nth(0)`).should('contain', 'Task 1');
@@ -66,14 +59,11 @@ describe('Example 40 - Infinite Scroll from JSON data', () => {
   it('should enable onSort for data reset and expect dataset to be reset to 50 items after sorting by Title', () => {
     cy.get('[data-test="onsort-on"]').click();
 
-    cy.get('[data-id="title"]')
-      .click();
+    cy.get('[data-id="title"]').click();
 
-    cy.get('[data-test="totalItemCount"]')
-      .should('have.text', '50');
+    cy.get('[data-test="totalItemCount"]').should('have.text', '50');
 
-    cy.get('.slick-viewport.slick-viewport-top.slick-viewport-left')
-      .scrollTo('top');
+    cy.get('.slick-viewport.slick-viewport-top.slick-viewport-left').scrollTo('top');
 
     cy.get(`[style="top: ${GRID_ROW_HEIGHT * 0}px;"] > .slick-cell:nth(0)`).should('contain', 'Task 9');
     cy.get(`[style="top: ${GRID_ROW_HEIGHT * 1}px;"] > .slick-cell:nth(0)`).should('contain', 'Task 8');
@@ -84,27 +74,56 @@ describe('Example 40 - Infinite Scroll from JSON data', () => {
   it('should "Group by Duration" and expect 50 items grouped', () => {
     cy.get('[data-test="group-by-duration"]').click();
 
-    cy.get('[data-test="totalItemCount"]')
-      .should('have.text', '50');
+    cy.get('[data-test="totalItemCount"]').should('have.text', '50');
 
-    cy.get('.slick-viewport.slick-viewport-top.slick-viewport-left')
-      .scrollTo('top');
+    cy.get('.slick-viewport.slick-viewport-top.slick-viewport-left').scrollTo('top');
 
     cy.get(`[style="top: ${GRID_ROW_HEIGHT * 0}px;"] > .slick-cell:nth(0) .slick-group-toggle.expanded`).should('have.length', 1);
     cy.get(`[style="top: ${GRID_ROW_HEIGHT * 0}px;"] > .slick-cell:nth(0) .slick-group-title`).contains(/Duration: [0-9]/);
   });
 
   it('should scroll to the bottom "Group by Duration" and expect 50 more items for a total of 100 items grouped', () => {
-    cy.get('.slick-viewport.slick-viewport-top.slick-viewport-left')
-      .scrollTo('bottom');
+    cy.get('.slick-viewport.slick-viewport-top.slick-viewport-left').scrollTo('bottom');
 
-    cy.get('[data-test="totalItemCount"]')
-      .should('have.text', '100');
+    cy.get('[data-test="totalItemCount"]').should('have.text', '100');
 
-    cy.get('.slick-viewport.slick-viewport-top.slick-viewport-left')
-      .scrollTo('top');
+    cy.get('.slick-viewport.slick-viewport-top.slick-viewport-left').scrollTo('top');
 
     cy.get(`[style="top: ${GRID_ROW_HEIGHT * 0}px;"] > .slick-cell:nth(0) .slick-group-toggle.expanded`).should('have.length', 1);
     cy.get(`[style="top: ${GRID_ROW_HEIGHT * 0}px;"] > .slick-cell:nth(0) .slick-group-title`).contains(/Duration: [0-9]/);
   });
+
+  it('should clear all grouping', () => {
+    cy.get('#grid40').find('.slick-row .slick-cell:nth(1)').rightclick({ force: true });
+
+    cy.get('.slick-context-menu.dropright .slick-menu-command-list')
+      .find('.slick-menu-item')
+      .find('.slick-menu-content')
+      .contains('Clear all Grouping')
+      .click();
+  });
+
+  it('should hover over the "Start" column header menu of 1st grid and click on "Sort Descending" command', () => {
+    cy.get('[data-test="clear-filters-sorting"]').click();
+    cy.get('#grid40').find('.slick-header-column:nth(3)').trigger('mouseover').children('.slick-header-menu-button').invoke('show').click();
+
+    cy.get('.slick-header-menu .slick-menu-command-list').should('be.visible').should('contain', 'Sort Descending').click();
+
+    cy.get(`[style="top: ${GRID_ROW_HEIGHT * 0}px;"] > .slick-cell:nth(3)`).contains('2020');
+  });
+
+  it('should load 200 items and filter "Start" column with <=2020-08-25', () => {
+    cy.get('[data-test="set-dynamic-filter"]').click();
+    cy.get('.slick-viewport.slick-viewport-top.slick-viewport-left').scrollTo('bottom');
+    cy.wait(10);
+    cy.get('.slick-viewport.slick-viewport-top.slick-viewport-left').scrollTo('bottom');
+    cy.get('[data-test="totalItemCount"]').should('have.text', '200');
+
+    cy.get('.slick-viewport.slick-viewport-top.slick-viewport-left').scrollTo('top');
+
+    cy.get(`[data-row=0] > .slick-cell:nth(3)`).contains(/^Aug [0-9]{2}, 2020$/);
+    cy.get(`[data-row=1] > .slick-cell:nth(3)`).contains(/^Aug [0-9]{2}, 2020$/);
+    cy.get(`[data-row=2] > .slick-cell:nth(3)`).contains(/^Aug [0-9]{2}, 2020$/);
+    cy.get(`[data-row=3] > .slick-cell:nth(3)`).contains(/^Aug [0-9]{2}, 2020$/);
+  });
 });