Add locale support to theme provider and use in date-text column

change/@ni-nimble-components-df093e6a-7cba-46ed-8d5d-07670af90719.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "Add locale support to theme provider and use in date-text column",
+  "packageName": "@ni/nimble-components",
+  "email": "[email protected]",
+  "dependentChangeType": "patch"
+}

packages/nimble-components/src/table-column/base/types.ts

@@ -1,4 +1,5 @@
-import type { TableRecord, ValidityObject } from '../../table/types';
+import type { TableRecord } from '../../table/types';
+import type { ValidityObject } from '../../utilities/models/validator';
 
 /**
  * An object whose fields are defined by a particular TableColumn, which is used by the column's

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

@@ -1,4 +1,7 @@
-import { DesignSystem } from '@microsoft/fast-foundation';
+import {
+    DesignSystem,
+    DesignTokenSubscriber
+} from '@microsoft/fast-foundation';
 import { attr } from '@microsoft/fast-element';
 import { styles } from '../base/styles';
 import { template } from '../base/template';
@@ -27,6 +30,7 @@ import type {
     WeekdayFormat
 } from './types';
 import { TableColumnDateTextValidator } from './models/table-column-date-text-validator';
+import { lang } from '../../theme-provider';
 
 export type TableColumnDateTextCellRecord = TableNumberField<'value'>;
 export interface TableColumnDateTextColumnConfig {
@@ -106,11 +110,22 @@ export class TableColumnDateText extends TableColumnTextBase {
     @attr({ attribute: 'custom-hour-cycle' })
     public customHourCycle: HourCycleFormat;
 
+    private readonly langSubscriber: DesignTokenSubscriber<typeof lang> = {
+        handleChange: () => {
+            this.updateColumnConfig();
+        }
+    };
+
     public override connectedCallback(): void {
         super.connectedCallback();
+        lang.subscribe(this.langSubscriber, this);
         this.updateColumnConfig();
     }
 
+    public override disconnectedCallback(): void {
+        lang.unsubscribe(this.langSubscriber, this);
+    }
+
     public override get validity(): TableColumnValidity {
         return this.validator.getValidity();
     }
@@ -226,7 +241,7 @@ export class TableColumnDateText extends TableColumnTextBase {
             options = this.getCustomFormattingOptions();
         }
         try {
-            return new Intl.DateTimeFormat(undefined, options);
+            return new Intl.DateTimeFormat(lang.getValueFor(this), options);
         } catch (e) {
             return undefined;
         }

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

@@ -7,6 +7,7 @@ import type { TableRecord } from '../../../table/types';
 import { TablePageObject } from '../../../table/testing/table.pageobject';
 import { TableColumnDateTextPageObject } from '../testing/table-column-date-text.pageobject';
 import { getSpecTypeByNamedList } from '../../../utilities/tests/parameterized';
+import { lang, themeProviderTag } from '../../../theme-provider';
 
 interface SimpleTableRecord extends TableRecord {
     field?: number | null;
@@ -15,6 +16,8 @@ interface SimpleTableRecord extends TableRecord {
 
 // prettier-ignore
 async function setup(): Promise<Fixture<Table<SimpleTableRecord>>> {
+    const themeProvider = document.createElement(themeProviderTag);
+    themeProvider.lang = 'en-US';
     return fixture<Table<SimpleTableRecord>>(
         html`<nimble-table style="width: 700px">
                 <${tableColumnDateTextTag} field-name="field" group-index="0">
@@ -23,7 +26,10 @@ async function setup(): Promise<Fixture<Table<SimpleTableRecord>>> {
                 <${tableColumnDateTextTag} field-name="anotherField">
                     Squeeze Column 1
                 </${tableColumnDateTextTag}>
-            </nimble-table>`
+            </nimble-table>`,
+        {
+            parent: themeProvider
+        }
     );
 }
 
@@ -269,6 +275,21 @@ describe('TableColumnDateText', () => {
             expect(pageObject.getRenderedCellContent(0, 0)).toBe('12/10/2012');
         });
 
+        it('updates displayed date when lang token changes', async () => {
+            await element.setData([
+                { field: new Date('Dec 10, 2012, 10:35:05 PM').valueOf() }
+            ]);
+            await waitForUpdatesAsync();
+            expect(pageObject.getRenderedCellContent(0, 0)).toBe(
+                'Dec 10, 2012, 10:35:05 PM'
+            );
+            lang.setValueFor(element, 'fr');
+            await waitForUpdatesAsync();
+            expect(pageObject.getRenderedCellContent(0, 0)).toBe(
+                '10 déc. 2012, 22:35:05'
+            );
+        });
+
         it('honors customDateStyle property', async () => {
             await element.setData([
                 { field: new Date('Dec 10, 2012, 10:35:05 PM').valueOf() }
@@ -470,7 +491,7 @@ describe('TableColumnDateText', () => {
             expect(column.validity.invalidCustomOptionsCombination).toBeFalse();
         });
 
-        it('sets invalid flag on column when custom options are incompatible', async () => {
+        it('sets invalidCustomOptionsCombination flag on column when custom options are incompatible', async () => {
             await element.setData([
                 { field: new Date('Dec 10, 2012, 10:35:05 PM').valueOf() }
             ]);
@@ -482,7 +503,7 @@ describe('TableColumnDateText', () => {
             expect(column.validity.invalidCustomOptionsCombination).toBeTrue();
         });
 
-        it('clears invalid flag on column after fixing custom option incompatibility', async () => {
+        it('clears invalidCustomOptionsCombination flag on column after fixing custom option incompatibility', async () => {
             await element.setData([
                 { field: new Date('Dec 10, 2012, 10:35:05 PM').valueOf() }
             ]);

packages/nimble-components/src/table/types.ts

@@ -1,4 +1,5 @@
 import type { TableColumn } from '../table-column/base';
+import type { ValidityObject } from '../utilities/models/validator';
 
 /**
  * TableFieldName describes the type associated with keys within
@@ -51,10 +52,6 @@ export type TableNumberField<FieldName extends TableFieldName> = {
     [name in FieldName]: TableNumberFieldValue;
 };
 
-export interface ValidityObject {
-    [key: string]: boolean;
-}
-
 export interface TableValidity extends ValidityObject {
     readonly duplicateRecordId: boolean;
     readonly missingRecordId: boolean;

packages/nimble-components/src/theme-provider/index.ts

@@ -8,13 +8,34 @@ import { Direction } from '@microsoft/fast-web-utilities';
 import { template } from './template';
 import { styles } from './styles';
 import { Theme } from './types';
+import { pageLocale } from '../utilities/models/page-locale';
+import type { ValidityObject } from '../utilities/models/validator';
 
 declare global {
     interface HTMLElementTagNameMap {
         'nimble-theme-provider': ThemeProvider;
     }
 }
 
+function isInvalidLang(value: string): boolean {
+    try {
+        // eslint-disable-next-line no-new
+        new Intl.DateTimeFormat(value);
+        return false;
+    } catch (e) {
+        return true;
+    }
+}
+
+function getSystemLocale(): string {
+    return new Intl.DateTimeFormat(undefined).resolvedOptions().locale;
+}
+
+export const lang = DesignToken.create<string>({
+    name: 'lang',
+    cssCustomPropertyName: null
+}).withDefault((): string => (isInvalidLang(pageLocale.lang) ? getSystemLocale() : pageLocale.lang));
+
 // Not represented as a CSS Custom Property, instead available
 // as an attribute of theme provider.
 export const direction = DesignToken.create<Direction>({
@@ -33,19 +54,44 @@ export const theme = DesignToken.create<Theme>({
  * @internal
  */
 export class ThemeProvider extends FoundationElement {
-    @attr({
-        attribute: 'direction'
-    })
+    @attr()
+    public override lang = '';
+
+    @attr()
     public direction: Direction = Direction.ltr;
 
-    @attr({
-        attribute: 'theme'
-    })
+    @attr()
     public theme: Theme = Theme.light;
 
+    public get validity(): ValidityObject {
+        return {
+            invalidLang: this.langIsInvalid
+        };
+    }
+
+    private langIsInvalid = false;
+
+    public langChanged(
+        _prev: string | undefined | null,
+        next: string | undefined | null
+    ): void {
+        this.langIsInvalid = false;
+        if (
+            next !== undefined
+            && next !== null
+            && next !== ''
+            // eslint-disable-next-line no-cond-assign
+            && !(this.langIsInvalid = isInvalidLang(next))
+        ) {
+            lang.setValueFor(this, next);
+        } else {
+            lang.deleteValueFor(this);
+        }
+    }
+
     public directionChanged(
-        _prev: Direction | undefined,
-        next: Direction | undefined
+        _prev: Direction | undefined | null,
+        next: Direction | undefined | null
     ): void {
         if (next !== undefined && next !== null) {
             direction.setValueFor(this, next);
@@ -55,8 +101,8 @@ export class ThemeProvider extends FoundationElement {
     }
 
     public themeChanged(
-        _prev: Theme | undefined,
-        next: Theme | undefined
+        _prev: Theme | undefined | null,
+        next: Theme | undefined | null
     ): void {
         if (next !== undefined && next !== null) {
             theme.setValueFor(this, next);

packages/nimble-components/src/theme-provider/tests/theme-provider.spec.ts

@@ -1,8 +1,11 @@
+import { html } from '@microsoft/fast-element';
 import { spinalCase } from '@microsoft/fast-web-utilities';
 import * as designTokensNamespace from '../design-tokens';
 import { tokenNames, suffixFromTokenName } from '../design-token-names';
 import { getSpecTypeByNamedList } from '../../utilities/tests/parameterized';
-import { ThemeProvider } from '..';
+import { ThemeProvider, lang, themeProviderTag } from '..';
+import { waitForUpdatesAsync } from '../../testing/async-helpers';
+import { fixture, type Fixture } from '../../utilities/tests/fixture';
 
 type DesignTokenPropertyName = keyof typeof designTokensNamespace;
 const designTokenPropertyNames = Object.keys(
@@ -16,6 +19,79 @@ describe('Theme Provider', () => {
         );
     });
 
+    describe('lang token', () => {
+        async function setup(
+            langValue = 'foo'
+        ): Promise<Fixture<ThemeProvider>> {
+            return fixture<ThemeProvider>(
+                html`<${themeProviderTag} lang="${langValue}">
+                    </${themeProviderTag}>`
+            );
+        }
+
+        let element: ThemeProvider;
+        let connect: () => Promise<void>;
+        let disconnect: () => Promise<void>;
+
+        afterEach(async () => {
+            await disconnect();
+        });
+
+        it('value is set to "foo" when theme provider lang attribute is assigned value "foo"', async () => {
+            ({ element, connect, disconnect } = await setup());
+            await connect();
+            await waitForUpdatesAsync();
+            expect(lang.getValueFor(element)).toBe('foo');
+        });
+
+        it('value defaults to page lang when theme provider lang attribute is removed', async () => {
+            document.documentElement.lang = 'bar';
+            ({ element, connect, disconnect } = await setup());
+            await connect();
+            element.removeAttribute('lang');
+            await waitForUpdatesAsync();
+            expect(lang.getValueFor(element)).toBe('bar');
+        });
+
+        it('value defaults to page lang when theme provider lang attribute is empty string', async () => {
+            document.documentElement.lang = 'bar';
+            ({ element, connect, disconnect } = await setup(''));
+            await connect();
+            await waitForUpdatesAsync();
+            expect(lang.getValueFor(element)).toBe('bar');
+            expect(element.validity.invalidLang).toBeFalse();
+        });
+
+        it('value defaults to page lang when theme provider lang attribute is malformed', async () => {
+            document.documentElement.lang = 'bar';
+            ({ element, connect, disconnect } = await setup('123'));
+            await connect();
+            await waitForUpdatesAsync();
+            expect(lang.getValueFor(element)).toBe('bar');
+            expect(element.validity.invalidLang).toBeTrue();
+        });
+
+        it('value updates when theme provider lang attribute goes from bad to good', async () => {
+            document.documentElement.lang = 'bar';
+            ({ element, connect, disconnect } = await setup('123'));
+            await connect();
+            await waitForUpdatesAsync();
+            element.setAttribute('lang', 'fr-CA');
+            await waitForUpdatesAsync();
+            expect(lang.getValueFor(element)).toBe('fr-CA');
+            expect(element.validity.invalidLang).toBeFalse();
+        });
+
+        it('value defaults to system default (en-US) when page lang is malformed and theme provider lang is malformed', async () => {
+            document.documentElement.lang = '123';
+            ({ element, connect, disconnect } = await setup('456'));
+            await connect();
+            await waitForUpdatesAsync();
+            // our karma config and GitHub actions config set the lang to en-US
+            expect(lang.getValueFor(element)).toBe('en-US');
+        });
+    });
+
     describe('design token should match CSSDesignToken', () => {
         const tokenEntries = designTokenPropertyNames.map(
             (name: DesignTokenPropertyName) => ({

packages/nimble-components/src/utilities/models/page-locale.ts

@@ -0,0 +1,27 @@
+import { observable } from '@microsoft/fast-element';
+
+/**
+ * Observable class to subscribe to changes in the page's lang attribute
+ */
+class PageLocale {
+    @observable
+    public lang: string = document.documentElement.lang;
+
+    public constructor() {
+        const observer = new MutationObserver(mutations => {
+            for (const mutation of mutations) {
+                if (
+                    mutation.type === 'attributes'
+                    && mutation.attributeName === 'lang'
+                ) {
+                    this.lang = (mutation.target as HTMLElement).lang;
+                }
+            }
+        });
+        observer.observe(document.documentElement, {
+            attributeFilter: ['lang']
+        });
+    }
+}
+
+export const pageLocale = new PageLocale();

packages/nimble-components/src/utilities/models/validator.ts

@@ -1,6 +1,9 @@
-import type { ValidityObject } from '../../table/types';
 import { Tracker } from './tracker';
 
+export interface ValidityObject {
+    [key: string]: boolean;
+}
+
 /**
  * Generic Validator Utility extends Tracker Utility for validation purposes
  */