npm - @ni/nimble-components - Versions diffs - 19.4.5 → 19.5.0 - Mend

@ni/nimble-components 19.4.5 → 19.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (54) hide show

package/README.md CHANGED Viewed

@@ -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

package/dist/all-components-bundle.js CHANGED Viewed

@@ -16232,7 +16232,7 @@
     /**
      * Do not edit directly
-     * Generated on Thu, 13 Jul 2023 16:36:04 GMT
+     * Generated on Thu, 13 Jul 2023 23:25:35 GMT
      */
     const Information100DarkUi = "#a46eff";
     const Information100LightUi = "#804ad9";
@@ -16668,7 +16668,7 @@
     DesignSystem.getOrCreate()
         .withPrefix('nimble')
         .register(nimbleDesignSystemProvider());
-    DesignSystem.tagFor(ThemeProvider);
+    const themeProviderTag = DesignSystem.tagFor(ThemeProvider);
     /* eslint-disable @typescript-eslint/naming-convention */
     const Headline1FallbackFontFamily = 'Noto Serif Fallback';
@@ -19438,6 +19438,25 @@
         information: 'information'
     };
+    const coreLabelDefaults = {
+        popupDismissLabel: 'Close',
+        numericIncrementLabel: 'Increment',
+        numericDecrementLabel: 'Decrement'
+    };
+    const popupDismissLabel = DesignToken.create({
+        name: 'popup-dismiss-label',
+        cssCustomPropertyName: null
+    }).withDefault(coreLabelDefaults.popupDismissLabel);
+    const numericDecrementLabel = DesignToken.create({
+        name: 'numeric-decrement-label',
+        cssCustomPropertyName: null
+    }).withDefault(coreLabelDefaults.numericDecrementLabel);
+    const numericIncrementLabel = DesignToken.create({
+        name: 'numeric-increment-label',
+        cssCustomPropertyName: null
+    }).withDefault(coreLabelDefaults.numericIncrementLabel);
     // prettier-ignore
     const template$n = html `
     <div class="container"
@@ -19484,7 +19503,7 @@
                 ${when(x => !x.preventDismiss, html `
                     <${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>
@@ -23175,6 +23194,157 @@
     registerIcon('icon-xmark-check', IconXmarkCheck);
     DesignSystem.tagFor(IconXmarkCheck);
+    /**
+     * Base class for label providers
+     */
+    class LabelProviderBase extends FoundationElement {
+        constructor() {
+            super(...arguments);
+            this.propertyNotifier = Observable.getNotifier(this);
+        }
+        connectedCallback() {
+            super.connectedCallback();
+            this.initializeThemeProvider();
+            this.propertyNotifier.subscribe(this);
+        }
+        disconnectedCallback() {
+            this.propertyNotifier.unsubscribe(this);
+            if (this.themeProvider) {
+                for (const token of Object.values(this.supportedLabels)) {
+                    token.deleteValueFor(this.themeProvider);
+                }
+                this.themeProvider = undefined;
+            }
+        }
+        handleChange(_element, property) {
+            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);
+                    }
+                }
+            }
+        }
+        initializeThemeProvider() {
+            this.themeProvider = this.closest(themeProviderTag) ?? undefined;
+            if (this.themeProvider) {
+                for (const [property, token] of Object.entries(this.supportedLabels)) {
+                    const value = this[property];
+                    if (value === null || value === undefined) {
+                        token.deleteValueFor(this.themeProvider);
+                    }
+                    else {
+                        token.setValueFor(this.themeProvider, value);
+                    }
+                }
+            }
+        }
+    }
+    const supportedLabels$1 = {
+        popupDismiss: popupDismissLabel,
+        numericDecrement: numericDecrementLabel,
+        numericIncrement: numericIncrementLabel
+    };
+    /**
+     * Core label provider for Nimble
+     */
+    class LabelProviderCore extends LabelProviderBase {
+        constructor() {
+            super(...arguments);
+            this.supportedLabels = supportedLabels$1;
+        }
+    }
+    __decorate$1([
+        attr({ attribute: 'popup-dismiss' })
+    ], LabelProviderCore.prototype, "popupDismiss", void 0);
+    __decorate$1([
+        attr({ attribute: 'numeric-decrement' })
+    ], LabelProviderCore.prototype, "numericDecrement", void 0);
+    __decorate$1([
+        attr({ attribute: 'numeric-increment' })
+    ], LabelProviderCore.prototype, "numericIncrement", void 0);
+    const nimbleLabelProviderCore = LabelProviderCore.compose({
+        baseName: 'label-provider-core'
+    });
+    DesignSystem.getOrCreate()
+        .withPrefix('nimble')
+        .register(nimbleLabelProviderCore());
+    DesignSystem.tagFor(LabelProviderCore);
+    const tableLabelDefaults = {
+        tableGroupCollapseLabel: 'Collapse group',
+        tableGroupExpandLabel: 'Expand group',
+        tableGroupsCollapseAllLabel: 'Collapse all groups',
+        tableCellActionMenuLabel: 'Options',
+        tableColumnHeaderGroupedIndicatorLabel: 'Grouped'
+    };
+    const tableGroupCollapseLabel = DesignToken.create({
+        name: 'table-group-collapse-label',
+        cssCustomPropertyName: null
+    }).withDefault(tableLabelDefaults.tableGroupCollapseLabel);
+    const tableGroupExpandLabel = DesignToken.create({
+        name: 'table-group-expand-label',
+        cssCustomPropertyName: null
+    }).withDefault(tableLabelDefaults.tableGroupExpandLabel);
+    const tableGroupsCollapseAllLabel = DesignToken.create({
+        name: 'table-groups-collapse-all-label',
+        cssCustomPropertyName: null
+    }).withDefault(tableLabelDefaults.tableGroupsCollapseAllLabel);
+    const tableCellActionMenuLabel = DesignToken.create({
+        name: 'table-cell-action-menu-label',
+        cssCustomPropertyName: null
+    }).withDefault(tableLabelDefaults.tableCellActionMenuLabel);
+    const tableColumnHeaderGroupedIndicatorLabel = DesignToken.create({
+        name: 'table-column-header-grouped-indicator-label',
+        cssCustomPropertyName: null
+    }).withDefault(tableLabelDefaults.tableColumnHeaderGroupedIndicatorLabel);
+    const supportedLabels = {
+        groupCollapse: tableGroupCollapseLabel,
+        groupExpand: tableGroupExpandLabel,
+        groupsCollapseAll: tableGroupsCollapseAllLabel,
+        cellActionMenu: tableCellActionMenuLabel,
+        columnHeaderGroupedIndicator: tableColumnHeaderGroupedIndicatorLabel
+    };
+    /**
+     * Label provider for the Nimble table (and its sub-components and columns)
+     */
+    class LabelProviderTable extends LabelProviderBase {
+        constructor() {
+            super(...arguments);
+            this.supportedLabels = supportedLabels;
+        }
+    }
+    __decorate$1([
+        attr({ attribute: 'group-collapse' })
+    ], LabelProviderTable.prototype, "groupCollapse", void 0);
+    __decorate$1([
+        attr({ attribute: 'group-expand' })
+    ], LabelProviderTable.prototype, "groupExpand", void 0);
+    __decorate$1([
+        attr({ attribute: 'groups-collapse-all' })
+    ], LabelProviderTable.prototype, "groupsCollapseAll", void 0);
+    __decorate$1([
+        attr({ attribute: 'cell-action-menu' })
+    ], LabelProviderTable.prototype, "cellActionMenu", void 0);
+    __decorate$1([
+        attr({ attribute: 'column-header-grouped-indicator' })
+    ], LabelProviderTable.prototype, "columnHeaderGroupedIndicator", void 0);
+    const nimbleLabelProviderTable = LabelProviderTable.compose({
+        baseName: 'label-provider-table'
+    });
+    DesignSystem.getOrCreate()
+        .withPrefix('nimble')
+        .register(nimbleLabelProviderTable());
+    DesignSystem.tagFor(LabelProviderTable);
     const styles$t = css `
     ${display('flex')}
@@ -23955,7 +24125,7 @@
             content-hidden
             tabindex="-1"
         >
-            "Decrement"
+            ${x => numericDecrementLabel.getValueFor(x)}
             <${iconMinusWideTag}
                 slot="start"
             >
@@ -23969,7 +24139,7 @@
             content-hidden
             tabindex="-1"
         >
-            "Increment"
+            ${x => numericIncrementLabel.getValueFor(x)}
             <${iconAddTag}
                 slot="start">
             </${iconAddTag}>
@@ -28575,7 +28745,7 @@
         @mousedown="${(_x, c) => !(c.event.detail > 1)}"
     >
         <slot></slot>
+        ${'' /* Omit title attribute for sort indicators because aria-sort is set on the 1st sorted column */}
         ${when(x => x.sortDirection === TableColumnSortDirection.ascending, html `
             <${iconArrowUpTag} class="sort-indicator" aria-hidden="true"></${iconArrowUpTag}>
         `)}
@@ -28583,7 +28753,7 @@
             <${iconArrowDownTag} class="sort-indicator" aria-hidden="true"></${iconArrowDownTag}>
         `)}
         ${when(x => x.isGrouped, html `
-            <${iconTwoSquaresInBracketsTag} class="grouped-indicator"></${iconTwoSquaresInBracketsTag}>
+            <${iconTwoSquaresInBracketsTag} class="grouped-indicator" title="${x => tableColumnHeaderGroupedIndicatorLabel.getValueFor(x)}"></${iconTwoSquaresInBracketsTag}>
         `)}
     </template>
 `;
@@ -28770,7 +28940,7 @@
                 class="action-menu"
             >
                 <${iconThreeDotsLineTag} slot="start"></${iconThreeDotsLineTag}>
-                ${x => x.actionMenuLabel}
+                ${x => x.actionMenuLabel ?? tableCellActionMenuLabel.getValueFor(x)}
                 <slot name="cellActionMenu" slot="menu"></slot>
             </${menuButtonTag}>
         `)}
@@ -29156,6 +29326,7 @@
                 tabindex="-1"
             >
                 <${iconArrowExpanderRightTag} ${ref('expandIcon')} slot="start" class="expander-icon ${x => x.animationClass}"></${iconArrowExpanderRightTag}>
+                ${x => (x.expanded ? tableGroupCollapseLabel.getValueFor(x) : tableGroupExpandLabel.getValueFor(x))}
             </${buttonTag}>
         </span>
@@ -29301,9 +29472,11 @@
                             class="collapse-all-button ${x => `${x.showCollapseAll ? 'visible' : ''}`}"
                             content-hidden
                             appearance="${ButtonAppearance.ghost}"
+                            title="${x => tableGroupsCollapseAllLabel.getValueFor(x)}"
                             @click="${x => x.handleCollapseAllGroupRows()}"
                         >
                             <${iconTriangleTwoLinesHorizontalTag} slot="start"></${iconTriangleTwoLinesHorizontalTag}>
+                            ${x => tableGroupsCollapseAllLabel.getValueFor(x)}
                         </${buttonTag}>
                     </span>
                     <span class="column-header-container">