Empty icon mapping (#1874)

# Pull Request ## 🤨 Rationale Grouping on an icon value isn't ideal if any of the cells don't have an icon. Specifically, the group row doesn't have a value associated with it and renders only a row count. It would be nice if we could allow a client to leave a cell blank for certain field values but still have the group rows have a value associated with them. For example, have a column that shows either a spinner or nothing based on whether a task is in progress. When grouping, it would be nice to show a string, such as "Idle", associated with the records that have nothing in progress without cluttering the table with extra icons in cells. This is the Future Work described in #1869 ## 👩‍💻 Implementation Updated the icon column to allow a `nimble-mapping-icon` to have an `undefined` icon. In that case, the cell renders nothing but the group row renders only the text associated with the mapping. ## 🧪 Testing Manually tested in storybook. Added new unit tests for having an `undefined` icon Updated storybook/matrix tests ## ✅ Checklist  - [ ] I have updated the project documentation to reflect my changes or determined no changes are needed. --------- Co-authored-by: Milan Raj <[email protected]>
ni · Feb 29, 2024 · d4ca92e · d4ca92e
1 parent 7a14257
commit d4ca92e
Show file tree

Hide file tree

Showing 8 changed files with 88 additions and 17 deletions.
diff --git a/change/@ni-nimble-components-106d0846-d742-466e-8fef-552c0a156055.json b/change/@ni-nimble-components-106d0846-d742-466e-8fef-552c0a156055.json
@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "Allow icon mappings to specify an undefined icon",
+  "packageName": "@ni/nimble-components",
+  "email": "[email protected]",
+  "dependentChangeType": "patch"
+}
diff --git a/packages/nimble-components/src/mapping/icon/tests/mapping-icon.stories.ts b/packages/nimble-components/src/mapping/icon/tests/mapping-icon.stories.ts
@@ -28,7 +28,7 @@ export const iconMapping: StoryObj = {
         icon: {
             control: { type: 'none' },
             description:
-                'The tag name of the Nimble icon to render, e.g. `nimble-icon-check`.'
+                'The tag name of the Nimble icon to render, e.g. `nimble-icon-check`. Alternatively, set `icon` to `undefined` to render no icon for the mapping while still providing a label to be used when grouping.'
         },
         severity: {
             description:

diff --git a/packages/nimble-components/src/table-column/enum-base/models/mapping-icon-config.ts b/packages/nimble-components/src/table-column/enum-base/models/mapping-icon-config.ts
@@ -6,23 +6,38 @@ export interface IconView {
     severity: IconSeverity;
     text?: string;
 }
-const createIconTemplate = (icon: string): ViewTemplate<IconView> => html`
-    <${icon}
-        title="${x => x.text}"
-        role="img"
-        aria-label="${x => x.text}"
-        severity="${x => x.severity}"
-        class="no-shrink"
-    >
-    </${icon}>`;
+
+// Create an empty template containing only a space because creating a ViewTemplate
+// with an empty string throws an exception at runtime.
+// prettier-ignore
+const emptyTemplate = html<IconView>` `;
+
+const createIconTemplate = (
+    icon: string | undefined
+): ViewTemplate<IconView> => {
+    if (icon === undefined) {
+        return emptyTemplate;
+    }
+
+    return html`
+        <${icon}
+            title="${x => x.text}"
+            role="img"
+            aria-label="${x => x.text}"
+            severity="${x => x.severity}"
+            class="no-shrink"
+        >
+        </${icon}>
+    `;
+};
 
 /**
  * Mapping configuration corresponding to a icon mapping
  */
 export class MappingIconConfig extends MappingConfig {
     public readonly iconTemplate: ViewTemplate<IconView>;
     public constructor(
-        resolvedIcon: string,
+        resolvedIcon: string | undefined,
         public readonly severity: IconSeverity,
         text: string | undefined
     ) {

diff --git a/packages/nimble-components/src/table-column/icon/index.ts b/packages/nimble-components/src/table-column/icon/index.ts
@@ -65,9 +65,6 @@ export class TableColumnIcon extends mixinGroupableColumnAPI(
 
     protected createMappingConfig(mapping: Mapping<unknown>): MappingConfig {
         if (mapping instanceof MappingIcon) {
-            if (!mapping.resolvedIcon) {
-                throw Error('Unresolved icon');
-            }
             return new MappingIconConfig(
                 mapping.resolvedIcon,
                 mapping.severity,

diff --git a/packages/nimble-components/src/table-column/icon/models/table-column-icon-validator.ts b/packages/nimble-components/src/table-column/icon/models/table-column-icon-validator.ts
@@ -39,6 +39,13 @@ export class TableColumnIconValidator extends TableColumnEnumBaseValidator<
         );
     }
 
+    private static hasUnresolvedIcon(mappingIcon: MappingIcon): boolean {
+        return (
+            typeof mappingIcon.icon === 'string'
+            && mappingIcon.resolvedIcon === undefined
+        );
+    }
+
     public override validate(
         mappings: Mapping<unknown>[],
         keyType: MappingKeyType
@@ -52,7 +59,7 @@ export class TableColumnIconValidator extends TableColumnEnumBaseValidator<
     private validateIconNames(mappings: Mapping<unknown>[]): void {
         const invalid = mappings
             .filter(TableColumnIconValidator.isIconMappingElement)
-            .some(mappingIcon => mappingIcon.resolvedIcon === undefined);
+            .some(TableColumnIconValidator.hasUnresolvedIcon);
         this.setConditionValue('invalidIconName', invalid);
     }
 

diff --git a/packages/nimble-components/src/table-column/icon/tests/table-column-icon-matrix.stories.ts b/packages/nimble-components/src/table-column/icon/tests/table-column-icon-matrix.stories.ts
@@ -32,18 +32,23 @@ const data = [
     {
         id: '2',
         code: 2
+    },
+    {
+        id: '3',
+        code: -1
     }
 ] as const;
 
 // prettier-ignore
 const component = (): ViewTemplate => html`
-    <${tableTag} id-field-name="id" style="height: 250px; ${isChromatic() ? '--ni-private-spinner-animation-play-state:paused' : ''}">
+    <${tableTag} id-field-name="id" style="height: 320px; ${isChromatic() ? '--ni-private-spinner-animation-play-state:paused' : ''}">
         <${tableColumnIconTag}
             field-name="code"
             key-type="number"
             group-index="0"
         >
             Column 1
+            <${mappingIconTag} key="-1" text="Unknown value"></${mappingIconTag}>
             <${mappingIconTag} key="0" text="Zero" icon="${iconCheckTag}"></${mappingIconTag}>
             <${mappingSpinnerTag} key="1" text="One"></${mappingSpinnerTag}>
         </${tableColumnIconTag}>
@@ -52,6 +57,7 @@ const component = (): ViewTemplate => html`
             key-type="number"
         >
             Column 2
+            <${mappingIconTag} key="-1" text="Unknown value"></${mappingIconTag}>
             <${mappingIconTag} key="0" text="Zero" icon="${iconCheckTag}" severity="success"></${mappingIconTag}>
             <${mappingIconTag} key="1" text="One" icon="${iconCheckTag}" severity="warning"></${mappingIconTag}>
             <${mappingIconTag} key="2" text="Two" icon="${iconCheckTag}" severity="error"></${mappingIconTag}>
@@ -61,6 +67,7 @@ const component = (): ViewTemplate => html`
             key-type="number"
         >
             Column 3
+            <${mappingIconTag} key="-1" text="Unknown value"></${mappingIconTag}>
             <${mappingIconTag} key="0" text="Zero" icon="${iconCheckTag}" severity="information"></${mappingIconTag}>
         </${tableColumnIconTag}>
     </${tableTag}>

diff --git a/packages/nimble-components/src/table-column/icon/tests/table-column-icon.spec.ts b/packages/nimble-components/src/table-column/icon/tests/table-column-icon.spec.ts
@@ -25,7 +25,7 @@ interface SimpleTableRecord extends TableRecord {
 interface BasicIconMapping {
     key?: MappingKey;
     text?: string;
-    icon: string;
+    icon?: string;
 }
 
 interface BasicSpinnerMapping {
@@ -154,6 +154,20 @@ describe('TableColumnIcon', () => {
         expect(() => pageObject.getRenderedIconColumnCellIconTagName(0, 0)).toThrowError();
     });
 
+    it('displays blank when no icon specified for mapping', async () => {
+        ({ element, connect, disconnect, model } = await setup({
+            keyType: MappingKeyType.string,
+            iconMappings: [{ key: 'a', text: 'alpha', icon: undefined }],
+            spinnerMappings: []
+        }));
+        pageObject = new TablePageObject<SimpleTableRecord>(element);
+        await element.setData([{ field1: 'a' }]);
+        await connect();
+        await waitForUpdatesAsync();
+
+        expect(() => pageObject.getRenderedIconColumnCellIconTagName(0, 0)).toThrowError();
+    });
+
     it('changing fieldName updates display', async () => {
         ({ element, connect, disconnect, model } = await setup({
             keyType: MappingKeyType.string,
@@ -308,6 +322,23 @@ describe('TableColumnIcon', () => {
         expect(pageObject.getRenderedGroupHeaderTextContent(0)).toBe('');
     });
 
+    it('sets group header text label and no icon when icon is undefined', async () => {
+        ({ element, connect, disconnect, model } = await setup({
+            keyType: MappingKeyType.string,
+            iconMappings: [{ key: 'b', text: 'bravo', icon: undefined }],
+            spinnerMappings: []
+        }));
+        pageObject = new TablePageObject<SimpleTableRecord>(element);
+        await element.setData([{ field1: 'b' }]);
+        await connect();
+        await waitForUpdatesAsync();
+        model.col1.groupIndex = 0;
+        await waitForUpdatesAsync();
+
+        expect(() => pageObject.getRenderedIconColumnGroupHeaderIconTagName(0)).toThrowError();
+        expect(pageObject.getRenderedGroupHeaderTextContent(0)).toBe('bravo');
+    });
+
     it('clears cell when mappings removed', async () => {
         ({ element, connect, disconnect, model } = await setup({
             keyType: MappingKeyType.string,

diff --git a/packages/nimble-components/src/table-column/icon/tests/table-column-icon.stories.ts b/packages/nimble-components/src/table-column/icon/tests/table-column-icon.stories.ts
@@ -40,6 +40,12 @@ const simpleData = [
         lastName: 'Simpson',
         status: 'success',
         isChild: true
+    },
+    {
+        firstName: 'Abbey',
+        lastName: '?',
+        status: 'unknown',
+        isChild: false
     }
 ] as const;
 
@@ -77,6 +83,7 @@ export const iconColumn: StoryObj<IconColumnTableArgs> = {
                 <${mappingIconTag} key="fail" icon="${iconXmarkTag}" severity="error" text="Not a Simpson"></${mappingIconTag}>
                 <${mappingIconTag} key="success" icon="${iconCheckLargeTag}" severity="success" text="Is a Simpson"></${mappingIconTag}>
                 <${mappingSpinnerTag} key="calculating" text="Calculating"></${mappingSpinnerTag}>
+                <${mappingIconTag} key="unknown" text="Unknown"></${mappingIconTag}>
             </${tableColumnIconTag}>
             <${tableColumnIconTag} field-name="isChild" key-type="boolean">
                 Is Child