Add/uptake label providers in nimble-components

change/@ni-nimble-components-6eb6eef1-eec2-4f6d-a98f-f7182ecdad50.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "Add nimble-label-provider-core and -table, along with localizable DesignTokens for labels/strings declared by Nimble components. Add docs for Localization.",
+  "packageName": "@ni/nimble-components",
+  "email": "[email protected]",
+  "dependentChangeType": "patch"
+}

packages/nimble-components/CONTRIBUTING.md

@@ -428,6 +428,28 @@ Nimble includes three NI-brand aligned themes (i.e. `light`, `dark`, & `color`).
 
 When creating a new component, create a `*-matrix.stories.ts` Storybook file to confirm that the component reflects the design intent across all themes and states.
 
+## Localization
+
+Most user-visible strings displayed by Nimble components are provided by the client application and are expected to be localized by the application if necessary. However, some strings are built into Nimble components and are provided only in English. An application can provide localized versions of these strings by using design tokens set on label provider elements.
+
+There are currently 2 label providers:
+
+-   `nimble-label-provider-core`: Used for labels for all components besides the table
+-   `nimble-label-provider-table`: Used for labels for the table (and table sub-components / column types)
+
+The expected format for label token names is:
+
+-   element/type(s) to which the token applies, e.g. `number-field` or `table`
+    -   This may not be an exact element name, if this label applies to multiple elements or will be used in multiple contexts
+-   component part/category (optional), e.g. `column-header`
+-   specific functionality or sub-part, e.g. `decrement`
+-   the suffix `label` (will be omitted from the label-provider properties/attributes)
+
+Components using localized labels should document them in Storybook. To add a "Localizable Labels" section:
+
+-   Their story `Args` should extend `LabelUserArgs`
+-   Call `addLabelUseMetadata()` and pass their declared metadata object, the applicable label provider tag, and the label tokens that they're using
+
 ## Component naming
 
 Component custom element names are specified in `index.ts` when registering the element. Use the following structure when naming components.

packages/nimble-components/README.md

@@ -23,8 +23,8 @@ If you have an existing application that incorporates a module bundler like [Web
 
 1. Install the package from [the public NPM registry](https://www.npmjs.com/package/@ni/nimble-components) by running `npm install @ni/nimble-components`.
 2. Import the component you want to use from the file you want to use it in. For example: `import '@ni/nimble-components/dist/esm/icons/succeeded';`
-3. Add the HTML for the component to your page. You can see sample code for each component in the [Nimble Storybook](https://ni.github.io/nimble/storybook/) by going to the **Docs** tab for the component and clicking **Show code**. For example: `<nimble-icon-succeeded></nimble-icon-succeeded>`.
-4. Nimble components are [standard web components (custom elements)](https://developer.mozilla.org/en-US/docs/Web/Web_Components) so you can configure them via normal DOM APIs like attributes, properties, events, and methods. The [Storybook documentation](https://ni.github.io/nimble/storybook/) for each component describes its custom API.
+3. Add the HTML for the component to your page. You can see sample code for each component in the [Nimble Storybook](https://nimble.ni.dev/storybook/) by going to the **Docs** page for the component and clicking **Show code**. For example: `<nimble-icon-succeeded></nimble-icon-succeeded>`.
+4. Nimble components are [standard web components (custom elements)](https://developer.mozilla.org/en-US/docs/Web/Web_Components) so you can configure them via normal DOM APIs like attributes, properties, events, and methods. The [Storybook documentation](https://nimble.ni.dev/storybook/) for each component describes its custom API.
 
 ### Prototyping in a static webpage
 
@@ -96,9 +96,33 @@ The theming system is composed of:
 
 The goal of the Nimble design system is to provide a consistent style for applications. If you find that Nimble does not expose colors, fonts, sizes, etc. that you need in an application get in touch with the Nimble squad.
 
+## Localization
+
+Most user-visible strings displayed by Nimble components are provided by the client application and are expected to be localized by the application if necessary. However, some strings are built into Nimble components and are provided only in English. An application can provide localized versions of these strings by using design tokens set on label provider elements.
+
+There are currently 2 label providers:
+
+-   `nimble-label-provider-core`: Used for labels for all components besides the table
+-   `nimble-label-provider-table`: Used for labels for the table (and table sub-components / column types)
+
+If a client is localized, it should:
+
+-   Add the `label-provider` element(s) as children of their root theme provider:
+    ```html
+    <body>
+        <nimble-theme-provider theme="light">
+            <nimble-label-provider-core></nimble-label-provider-core>
+            <!-- if using nimble-table, include nimble-label-provider-table: -->
+            <nimble-label-provider-table></nimble-label-provider-table>
+            <!-- everything else -->
+        </nimble-theme-provider>
+    </body>
+    ```
+-   For each label token on the label provider API, localize the English string, and set the corresponding HTML attribute or JS property on the label provider to the localized values. A list of all label tokens for each label provider (and their corresponding attribute/property names and English strings) can be found in the [Tokens/Label Providers section of Storybook](http://nimble.ni.dev/storybook/?path=/docs/tokens-label-providers--docs).
+
 ## Accessibility
 
-For accessibility information related to nimble components, see [ACCESSIBILITY.md](docs/ACCESSIBILITY.md).
+For accessibility information related to nimble components, see [accessibility.md](/packages/nimble-components/docs/accessibility.md).
 
 ## Contributing
 

packages/nimble-components/src/all-components.ts

@@ -21,6 +21,8 @@ import './combobox';
 import './dialog';
 import './drawer';
 import './icons/all-icons';
+import './label-provider/core';
+import './label-provider/table';
 import './list-option';
 import './menu';
 import './menu-button';

packages/nimble-components/src/banner/template.ts

@@ -6,6 +6,7 @@ import { iconInfoTag } from '../icons/info';
 import { iconTriangleFilledTag } from '../icons/triangle-filled';
 import { iconXmarkTag } from '../icons/xmark';
 import { BannerSeverity } from './types';
+import { popupDismissLabel } from '../label-provider/core/label-tokens';
 
 // prettier-ignore
 export const template = html<Banner>`
@@ -53,7 +54,7 @@ export const template = html<Banner>`
                 ${when(x => !x.preventDismiss, html<Banner>`
                     <${buttonTag} appearance="ghost" content-hidden @click="${x => x.dismissBanner()}">
                         <${iconXmarkTag} slot="start"></${iconXmarkTag}>
-                        ${x => x.dismissButtonLabel ?? 'Close'}
+                        ${x => x.dismissButtonLabel ?? popupDismissLabel.getValueFor(x)}
                     </${buttonTag}>
                 `)}
             </div>

packages/nimble-components/src/banner/tests/banner.spec.ts

@@ -1,9 +1,15 @@
 import { html } from '@microsoft/fast-element';
 import { fixture, Fixture } from '../../utilities/tests/fixture';
-import { Banner } from '..';
+import { Banner, bannerTag } from '..';
 import { BannerSeverity } from '../types';
 import { waitForUpdatesAsync } from '../../testing/async-helpers';
 import { createEventListener } from '../../utilities/tests/component';
+import { themeProviderTag, type ThemeProvider } from '../../theme-provider';
+import {
+    LabelProviderCore,
+    labelProviderCoreTag
+} from '../../label-provider/core';
+import { buttonTag } from '../../button';
 
 async function setup(): Promise<Fixture<Banner>> {
     return fixture<Banner>(html`
@@ -14,6 +20,18 @@ async function setup(): Promise<Fixture<Banner>> {
     `);
 }
 
+async function setupWithLabelProvider(): Promise<Fixture<ThemeProvider>> {
+    return fixture<ThemeProvider>(html`
+        <${themeProviderTag}>
+            <${labelProviderCoreTag}></${labelProviderCoreTag}>
+            <nimble-banner>
+                <span slot="title">Title</span>
+                Message text
+            </nimble-banner>
+        </${themeProviderTag}>
+    `);
+}
+
 describe('Banner', () => {
     let element: Banner;
     let connect: () => Promise<void>;
@@ -102,3 +120,37 @@ describe('Banner', () => {
         ).toBe('status');
     });
 });
+
+describe('Banner with LabelProviderCore', () => {
+    let element: Banner;
+    let labelProvider: LabelProviderCore;
+    let connect: () => Promise<void>;
+    let disconnect: () => Promise<void>;
+
+    beforeEach(async () => {
+        let themeProvider: ThemeProvider;
+        ({
+            element: themeProvider,
+            connect,
+            disconnect
+        } = await setupWithLabelProvider());
+        await connect();
+        element = themeProvider.querySelector(bannerTag)!;
+        labelProvider = themeProvider.querySelector(labelProviderCoreTag)!;
+    });
+
+    afterEach(async () => {
+        await disconnect();
+    });
+
+    it('uses CoreLabelProvider popupDismissLabel for the close button label when dismissButtonLabel is unset', async () => {
+        labelProvider.popupDismiss = 'Customized Close';
+        await waitForUpdatesAsync();
+
+        const actualCloseButtonText = element
+            .shadowRoot!.querySelector('.dismiss')!
+            .querySelector(buttonTag)!
+            .textContent!.trim();
+        expect(actualCloseButtonText).toBe('Customized Close');
+    });
+});

packages/nimble-components/src/banner/tests/banner.stories.ts

@@ -8,6 +8,12 @@ import { bannerTag } from '..';
 import { iconKeyTag } from '../../icons/key';
 import { buttonTag } from '../../button';
 import { anchorTag } from '../../anchor';
+import { labelProviderCoreTag } from '../../label-provider/core';
+import {
+    LabelUserArgs,
+    addLabelUseMetadata
+} from '../../label-provider/base/tests/label-user-stories-utils';
+import { popupDismissLabel } from '../../label-provider/core/label-tokens';
 
 // eslint-disable-next-line @typescript-eslint/naming-convention
 const ActionType = {
@@ -20,7 +26,7 @@ const ActionType = {
 // eslint-disable-next-line @typescript-eslint/no-redeclare
 type ActionType = (typeof ActionType)[keyof typeof ActionType];
 
-interface BannerArgs {
+interface BannerArgs extends LabelUserArgs {
     open: boolean;
     title: string;
     text: string;
@@ -55,6 +61,7 @@ const metadata: Meta<BannerArgs> = {
         }
     }
 };
+addLabelUseMetadata(metadata, labelProviderCoreTag, popupDismissLabel);
 
 export default metadata;
 
@@ -121,11 +128,13 @@ export const _banner: StoryObj<BannerArgs> = {
         dismissButtonLabel: {
             name: 'dismiss-button-label',
             description:
-                'Set to a localized label (e.g. `"Close"`) for the dismiss button. This provides an accessible name for assistive technologies.'
+                'Set to a localized label (e.g. `"Close"`) for the dismiss button. This provides an accessible name for assistive technologies. <br>(Equivalent to setting `popup-dismiss` on `nimble-label-provider-core`)',
+            control: { type: 'none' }
         },
         toggle: {
             description:
-                'Event emitted by the banner when the `open` state changes. The event details include the booleans `oldState` and `newState`.'
+                'Event emitted by the banner when the `open` state changes. The event details include the booleans `oldState` and `newState`.',
+            control: { type: 'none' }
         }
     },
     args: {
@@ -135,6 +144,8 @@ export const _banner: StoryObj<BannerArgs> = {
         severity: BannerSeverity.error,
         action: 'none',
         preventDismiss: false,
-        titleHidden: false
+        titleHidden: false,
+        dismissButtonLabel: undefined,
+        toggle: undefined
     }
 };

packages/nimble-components/src/label-provider/base/index.ts

@@ -0,0 +1,70 @@
+import { DesignToken, FoundationElement } from '@microsoft/fast-foundation';
+import { Notifier, Observable, type Subscriber } from '@microsoft/fast-element';
+import { themeProviderTag } from '../../theme-provider';
+
+/**
+ * Base class for label providers
+ */
+export abstract class LabelProviderBase
+    extends FoundationElement
+    implements Subscriber {
+    protected abstract readonly supportedLabels: {
+        [P in keyof LabelProviderBase]?: DesignToken<string>;
+    };
+
+    private propertyNotifier?: Notifier;
+    private themeProvider?: HTMLElement;
+
+    public override connectedCallback(): void {
+        super.connectedCallback();
+        this.initializeThemeProvider();
+        this.propertyNotifier = Observable.getNotifier(this);
+        this.propertyNotifier.subscribe(this);
+    }
+
+    public override disconnectedCallback(): void {
+        if (this.propertyNotifier) {
+            this.propertyNotifier.unsubscribe(this);
+            this.propertyNotifier = undefined;
+        }
+        if (this.themeProvider) {
+            for (const token of Object.values(this.supportedLabels)) {
+                token.deleteValueFor(this.themeProvider);
+            }
+            this.themeProvider = undefined;
+        }
+    }
+
+    public handleChange(
+        _element: LabelProviderBase,
+        property: keyof LabelProviderBase
+    ): void {
+        if (this.supportedLabels[property]) {
+            const token = this.supportedLabels[property]!;
+            const value = this[property];
+            if (this.themeProvider) {
+                if (value === null || value === undefined) {
+                    token.deleteValueFor(this.themeProvider);
+                } else {
+                    token.setValueFor(this.themeProvider, value as string);
+                }
+            }
+        }
+    }
+
+    private initializeThemeProvider(): void {
+        this.themeProvider = this.closest(themeProviderTag) ?? undefined;
+        if (this.themeProvider) {
+            for (const [property, token] of Object.entries(
+                this.supportedLabels
+            )) {
+                const value = this[property as keyof LabelProviderBase];
+                if (value === null || value === undefined) {
+                    token.deleteValueFor(this.themeProvider);
+                } else {
+                    token.setValueFor(this.themeProvider, value as string);
+                }
+            }
+        }
+    }
+}

packages/nimble-components/src/label-provider/base/tests/label-name-utils.ts

@@ -0,0 +1,9 @@
+import { spinalCase } from '@microsoft/fast-web-utilities';
+
+export function getPropertyName(jsKey: string): string {
+    return jsKey.replace(/Label$/, '');
+}
+
+export function getAttributeName(jsKey: string): string {
+    return spinalCase(getPropertyName(jsKey));
+}