Add formatting API to date column

change/@ni-nimble-components-8fdb7efd-10a8-4e79-9dd7-079527db6644.json

@@ -0,0 +1,7 @@
+{
+  "type": "patch",
+  "comment": "Add formatting API to date column",
+  "packageName": "@ni/nimble-components",
+  "email": "[email protected]",
+  "dependentChangeType": "patch"
+}

packages/nimble-components/karma.conf.js

@@ -28,7 +28,8 @@ const commonChromeFlags = [
     '--disable-extensions',
     '--disable-infobars',
     '--disable-translate',
-    '--force-prefers-reduced-motion'
+    '--force-prefers-reduced-motion',
+    '--lang=en'
 ];
 
 // Create a webpack environment plugin to use while running tests so that

packages/nimble-components/src/table-column/date-text/cell-view/index.ts

@@ -6,6 +6,7 @@ import type {
 } from '..';
 import { styles } from '../../text-base/cell-view/styles';
 import { TableColumnTextCellViewBase } from '../../text-base/cell-view';
+import { formatNumericDate } from '../models/format-helper';
 
 declare global {
     interface HTMLElementTagNameMap {
@@ -20,20 +21,20 @@ export class TableColumnDateTextCellView extends TableColumnTextCellViewBase<
 TableColumnDateTextCellRecord,
 TableColumnDateTextColumnConfig
 > {
-    private static readonly formatter = new Intl.DateTimeFormat(undefined, {
-        dateStyle: 'medium',
-        timeStyle: 'medium'
-    });
+    private columnConfigChanged(): void {
+        this.updateText();
+    }
 
     private cellRecordChanged(): void {
-        if (typeof this.cellRecord.value === 'number') {
-            try {
-                this.text = TableColumnDateTextCellView.formatter.format(
-                    this.cellRecord.value
-                );
-            } catch (e) {
-                this.text = '';
-            }
+        this.updateText();
+    }
+
+    private updateText(): void {
+        if (this.columnConfig?.formatter) {
+            this.text = formatNumericDate(
+                this.columnConfig.formatter,
+                this.cellRecord.value
+            );
         } else {
             this.text = '';
         }

packages/nimble-components/src/table-column/date-text/group-header-view/index.ts

@@ -4,6 +4,7 @@ import { TableColumnTextGroupHeaderViewBase } from '../../text-base/group-header
 import { template } from '../../text-base/group-header-view/template';
 import { styles } from '../../text-base/group-header-view/styles';
 import type { TableColumnDateTextColumnConfig } from '..';
+import { formatNumericDate } from '../models/format-helper';
 
 declare global {
     interface HTMLElementTagNameMap {
@@ -17,20 +18,20 @@ export class TableColumnDateTextGroupHeaderView extends TableColumnTextGroupHead
 TableNumberFieldValue,
 TableColumnDateTextColumnConfig
 > {
-    private static readonly formatter = new Intl.DateTimeFormat(undefined, {
-        dateStyle: 'medium',
-        timeStyle: 'medium'
-    });
+    private columnConfigChanged(): void {
+        this.updateText();
+    }
 
     private groupHeaderValueChanged(): void {
-        if (typeof this.groupHeaderValue === 'number') {
-            try {
-                this.text = TableColumnDateTextGroupHeaderView.formatter.format(
-                    this.groupHeaderValue
-                );
-            } catch (e) {
-                this.text = '';
-            }
+        this.updateText();
+    }
+
+    private updateText(): void {
+        if (this.columnConfig?.formatter) {
+            this.text = formatNumericDate(
+                this.columnConfig.formatter,
+                this.groupHeaderValue
+            );
         } else {
             this.text = '';
         }

packages/nimble-components/src/table-column/date-text/index.ts

@@ -1,16 +1,37 @@
 import { DesignSystem } from '@microsoft/fast-foundation';
+import { attr } from '@microsoft/fast-element';
 import { styles } from '../base/styles';
 import { template } from '../base/template';
 import type { TableNumberField } from '../../table/types';
 import { TableColumnTextBase } from '../text-base';
-import { TableColumnSortOperation } from '../base/types';
+import { TableColumnSortOperation, TableColumnValidity } from '../base/types';
 import { tableColumnDateTextGroupHeaderTag } from './group-header-view';
 import { tableColumnDateTextCellViewTag } from './cell-view';
 import type { ColumnInternalsOptions } from '../base/models/column-internals';
+import type {
+    DateTextFormat,
+    LocaleMatcherAlgorithm,
+    EraFormat,
+    YearFormat,
+    DayFormat,
+    HourFormat,
+    MinuteFormat,
+    SecondFormat,
+    TimeZoneNameFormat,
+    FormatMatcherAlgorithm,
+    DayPeriodFormat,
+    DateStyle,
+    TimeStyle,
+    HourCycleFormat,
+    MonthFormat,
+    WeekdayFormat
+} from './types';
+import { TableColumnDateTextValidator } from './models/table-column-date-text-validator';
 
 export type TableColumnDateTextCellRecord = TableNumberField<'value'>;
-// eslint-disable-next-line @typescript-eslint/no-empty-interface
-export interface TableColumnDateTextColumnConfig {}
+export interface TableColumnDateTextColumnConfig {
+    formatter?: Intl.DateTimeFormat;
+}
 
 declare global {
     interface HTMLElementTagNameMap {
@@ -22,6 +43,78 @@ declare global {
  * The table column for displaying dates/times as text.
  */
 export class TableColumnDateText extends TableColumnTextBase {
+    /** @internal */
+    public validator = new TableColumnDateTextValidator(this.columnInternals);
+
+    @attr
+    public format: DateTextFormat;
+
+    @attr({ attribute: 'custom-locale-matcher' })
+    public customLocaleMatcher: LocaleMatcherAlgorithm;
+
+    @attr({ attribute: 'custom-weekday' })
+    public customWeekday: WeekdayFormat;
+
+    @attr({ attribute: 'custom-era' })
+    public customEra: EraFormat;
+
+    @attr({ attribute: 'custom-year' })
+    public customYear: YearFormat;
+
+    @attr({ attribute: 'custom-month' })
+    public customMonth: MonthFormat;
+
+    @attr({ attribute: 'custom-day' })
+    public customDay: DayFormat;
+
+    @attr({ attribute: 'custom-hour' })
+    public customHour: HourFormat;
+
+    @attr({ attribute: 'custom-minute' })
+    public customMinute: MinuteFormat;
+
+    @attr({ attribute: 'custom-second' })
+    public customSecond: SecondFormat;
+
+    @attr({ attribute: 'custom-time-zone-name' })
+    public customTimeZoneName: TimeZoneNameFormat;
+
+    @attr({ attribute: 'custom-format-matcher' })
+    public customFormatMatcher: FormatMatcherAlgorithm;
+
+    @attr({ attribute: 'custom-hour12', mode: 'boolean' })
+    public customHour12?: boolean;
+
+    @attr({ attribute: 'custom-time-zone' })
+    public customTimeZone?: string;
+
+    @attr({ attribute: 'custom-calendar' })
+    public customCalendar?: string;
+
+    @attr({ attribute: 'custom-day-period' })
+    public customDayPeriod: DayPeriodFormat;
+
+    @attr({ attribute: 'custom-numbering-system' })
+    public customNumberingSystem?: string;
+
+    @attr({ attribute: 'custom-date-style' })
+    public customDateStyle: DateStyle;
+
+    @attr({ attribute: 'custom-time-style' })
+    public customTimeStyle: TimeStyle;
+
+    @attr({ attribute: 'custom-hour-cycle' })
+    public customHourCycle: HourCycleFormat;
+
+    public override connectedCallback(): void {
+        super.connectedCallback();
+        this.updateColumnConfig();
+    }
+
+    public override get validity(): TableColumnValidity {
+        return this.validator.getValidity();
+    }
+
     protected override getColumnInternalsOptions(): ColumnInternalsOptions {
         return {
             cellRecordFieldNames: ['value'],
@@ -31,6 +124,141 @@ export class TableColumnDateText extends TableColumnTextBase {
             sortOperation: TableColumnSortOperation.basic
         };
     }
+
+    protected formatChanged(): void {
+        this.updateColumnConfig();
+    }
+
+    protected customLocaleMatcherChanged(): void {
+        this.updateColumnConfig();
+    }
+
+    protected customWeekdayChanged(): void {
+        this.updateColumnConfig();
+    }
+
+    protected customEraChanged(): void {
+        this.updateColumnConfig();
+    }
+
+    protected customYearChanged(): void {
+        this.updateColumnConfig();
+    }
+
+    protected customMonthChanged(): void {
+        this.updateColumnConfig();
+    }
+
+    protected customDayChanged(): void {
+        this.updateColumnConfig();
+    }
+
+    protected customHourChanged(): void {
+        this.updateColumnConfig();
+    }
+
+    protected customMinuteChanged(): void {
+        this.updateColumnConfig();
+    }
+
+    protected customSecondChanged(): void {
+        this.updateColumnConfig();
+    }
+
+    protected customTimeZoneNameChanged(): void {
+        this.updateColumnConfig();
+    }
+
+    protected customFormatMatcherChanged(): void {
+        this.updateColumnConfig();
+    }
+
+    protected customHour12Changed(): void {
+        this.updateColumnConfig();
+    }
+
+    protected customTimeZoneChanged(): void {
+        this.updateColumnConfig();
+    }
+
+    protected customCalendarChanged(): void {
+        this.updateColumnConfig();
+    }
+
+    protected customDayPeriodChanged(): void {
+        this.updateColumnConfig();
+    }
+
+    protected customNumberingSystemChanged(): void {
+        this.updateColumnConfig();
+    }
+
+    protected customDateStyleChanged(): void {
+        this.updateColumnConfig();
+    }
+
+    protected customTimeStyleChanged(): void {
+        this.updateColumnConfig();
+    }
+
+    protected customHourCycleChanged(): void {
+        this.updateColumnConfig();
+    }
+
+    private updateColumnConfig(): void {
+        const columnConfig: TableColumnDateTextColumnConfig = {
+            formatter: this.createFormatter()
+        };
+        this.columnInternals.columnConfig = columnConfig;
+        this.validator.setCustomOptionsValidity(
+            columnConfig.formatter !== undefined
+        );
+    }
+
+    private createFormatter(): Intl.DateTimeFormat | undefined {
+        let options: Intl.DateTimeFormatOptions;
+        if (!this.format) {
+            options = {
+                dateStyle: 'medium',
+                timeStyle: 'medium'
+            };
+        } else {
+            options = this.getCustomFormattingOptions();
+        }
+        try {
+            return new Intl.DateTimeFormat(undefined, options);
+        } catch (e) {
+            return undefined;
+        }
+    }
+
+    private getCustomFormattingOptions(): Intl.DateTimeFormatOptions {
+        // There's a FAST bug (https://github.com/microsoft/fast/issues/6630) where removing
+        // attributes sets their values to null instead of undefined. To work around this,
+        // translate null values to undefined.
+        const options: Intl.DateTimeFormatOptions = {
+            localeMatcher: this.customLocaleMatcher ?? undefined,
+            weekday: this.customWeekday ?? undefined,
+            era: this.customEra ?? undefined,
+            year: this.customYear ?? undefined,
+            month: this.customMonth ?? undefined,
+            day: this.customDay ?? undefined,
+            hour: this.customHour ?? undefined,
+            minute: this.customMinute ?? undefined,
+            second: this.customSecond ?? undefined,
+            timeZoneName: this.customTimeZoneName ?? undefined,
+            formatMatcher: this.customFormatMatcher ?? undefined,
+            hour12: this.customHour12 ?? undefined,
+            timeZone: this.customTimeZone ?? undefined,
+            calendar: this.customCalendar ?? undefined,
+            dayPeriod: this.customDayPeriod ?? undefined,
+            numberingSystem: this.customNumberingSystem ?? undefined,
+            dateStyle: this.customDateStyle ?? undefined,
+            timeStyle: this.customTimeStyle ?? undefined,
+            hourCycle: this.customHourCycle ?? undefined
+        };
+        return options;
+    }
 }
 
 const nimbleTableColumnDateText = TableColumnDateText.compose({

packages/nimble-components/src/table-column/date-text/models/format-helper.ts

@@ -0,0 +1,16 @@
+import type { TableNumberFieldValue } from '../../../table/types';
+
+export function formatNumericDate(
+    formatter: Intl.DateTimeFormat,
+    date: TableNumberFieldValue
+): string {
+    if (typeof date === 'number') {
+        try {
+            return formatter.format(date);
+        } catch (e) {
+            return '';
+        }
+    } else {
+        return '';
+    }
+}

packages/nimble-components/src/table-column/date-text/models/table-column-date-text-validator.ts

@@ -0,0 +1,19 @@
+import type { ColumnInternals } from '../../base/models/column-internals';
+import { ColumnValidator } from '../../base/models/column-validator';
+
+const dateTextValidityFlagNames = ['invalidCustomOptionsCombination'] as const;
+
+/**
+ * Validator for TableColumnDateText.
+ */
+export class TableColumnDateTextValidator extends ColumnValidator<
+    typeof dateTextValidityFlagNames
+> {
+    public constructor(columnInternals: ColumnInternals<unknown>) {
+        super(columnInternals, dateTextValidityFlagNames);
+    }
+
+    public setCustomOptionsValidity(valid: boolean): void {
+        this.setConditionValue('invalidCustomOptionsCombination', !valid);
+    }
+}