Allow icon column to be configured as fixed width

change/@ni-nimble-components-248b2e34-5be4-492b-8512-1e5226e10ca4.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "Add configuration to make the icon column fixed width",
+  "packageName": "@ni/nimble-components",
+  "email": "20542556+mollykreis@users.noreply.github.com",
+  "dependentChangeType": "patch"
+}

packages/nimble-components/src/table-column/base/models/column-internals.ts

@@ -140,6 +140,19 @@ export class ColumnInternals<
     @observable
     public minPixelWidth = defaultMinPixelWidth;
 
+    /**
+     * Whether or not resizing the column has been disabled.
+     */
+    @observable
+    public resizingDisabled = false;
+
+    /**
+     * Whether or not the grouping and sorting indicators should be hidden in the column header
+     * when the column is grouped or sorted.
+     */
+    @observable
+    public hideHeaderIndicators = false;
+
     /**
      * @internal Do not write to this value directly. It is used by the Table in order to store
      * the resolved value of the fractionalWidth after updates programmatic or interactive updates.

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

@@ -44,19 +44,18 @@ export type TableColumnSortOperation =
 // eslint-disable-next-line @typescript-eslint/no-empty-interface
 export interface TableColumnValidity extends ValidityObject {}
 
-const groupIconSize = 16;
-const sortIconSize = 16;
-const spacing = 8;
-const menuDropdownSize = 24;
+export const columnIconSize = 16; // `iconSize` token
+export const columnSpacing = 8; // `mediumPadding` token
+const menuDropdownSize = 24; // `controlSlimHeight` token
 const oneCharPlusEllipsisSize = 21;
-export const defaultMinPixelWidth = spacing
+export const defaultMinPixelWidth = columnSpacing
     + oneCharPlusEllipsisSize
-    + spacing
-    + sortIconSize
-    + spacing
-    + groupIconSize
-    + spacing
+    + columnSpacing
+    + columnIconSize // sort icon
+    + columnSpacing
+    + columnIconSize // group icon
+    + columnSpacing
     + menuDropdownSize
-    + spacing;
+    + columnSpacing;
 
 export const defaultFractionalWidth = 1;

packages/nimble-components/src/table-column/icon/index.ts

@@ -1,12 +1,18 @@
 import { DesignSystem } from '@microsoft/fast-foundation';
+import { attr } from '@microsoft/fast-element';
 import {
     MappingConfigs,
     TableColumnEnumBase,
     TableColumnEnumColumnConfig
 } from '../enum-base';
 import { styles } from '../enum-base/styles';
 import { template } from '../enum-base/template';
-import { TableColumnSortOperation } from '../base/types';
+import {
+    TableColumnSortOperation,
+    columnIconSize,
+    columnSpacing,
+    defaultMinPixelWidth
+} from '../base/types';
 import { mixinGroupableColumnAPI } from '../mixins/groupable-column';
 import { mixinFractionalWidthColumnAPI } from '../mixins/fractional-width-column';
 import { MappingSpinner } from '../../mapping/spinner';
@@ -21,6 +27,9 @@ import { MappingIconConfig } from '../enum-base/models/mapping-icon-config';
 import { MappingSpinnerConfig } from '../enum-base/models/mapping-spinner-config';
 import { MappingText } from '../../mapping/text';
 import { MappingTextConfig } from '../enum-base/models/mapping-text-config';
+import { TableColumnMappingWidthMode } from './types';
+
+const iconSizeWidth = columnIconSize + 2 * columnSpacing;
 
 declare global {
     interface HTMLElementTagNameMap {
@@ -39,6 +48,15 @@ export class TableColumnIcon extends mixinGroupableColumnAPI(
         >
     )
 ) {
+    @attr({ attribute: 'width-mode' })
+    public widthMode: TableColumnMappingWidthMode;
+
+    public override minPixelWidthChanged(): void {
+        if (this.widthMode !== TableColumnMappingWidthMode.iconSize) {
+            this.columnInternals.minPixelWidth = this.getConfiguredMinPixelWidth();
+        }
+    }
+
     protected override getColumnInternalsOptions(): ColumnInternalsOptions<TableColumnIconValidator> {
         return {
             cellRecordFieldNames: ['value'],
@@ -77,6 +95,27 @@ export class TableColumnIcon extends mixinGroupableColumnAPI(
         // this function from running when there is an unsupported mapping.
         throw new Error('Unsupported mapping');
     }
+
+    private widthModeChanged(): void {
+        if (this.widthMode === TableColumnMappingWidthMode.iconSize) {
+            this.columnInternals.resizingDisabled = true;
+            this.columnInternals.hideHeaderIndicators = true;
+            this.columnInternals.pixelWidth = iconSizeWidth;
+            this.columnInternals.minPixelWidth = iconSizeWidth;
+        } else {
+            this.columnInternals.resizingDisabled = false;
+            this.columnInternals.hideHeaderIndicators = false;
+            this.columnInternals.pixelWidth = undefined;
+            this.columnInternals.minPixelWidth = this.getConfiguredMinPixelWidth();
+        }
+    }
+
+    private getConfiguredMinPixelWidth(): number {
+        if (typeof this.minPixelWidth === 'number') {
+            return this.minPixelWidth;
+        }
+        return defaultMinPixelWidth;
+    }
 }
 
 const nimbleTableColumnIcon = TableColumnIcon.compose({

packages/nimble-components/src/table-column/icon/tests/table-column-icon-matrix.stories.ts

@@ -12,6 +12,8 @@ import { mappingSpinnerTag } from '../../../mapping/spinner';
 import { isChromatic } from '../../../utilities/tests/isChromatic';
 import { iconXmarkTag } from '../../../icons/xmark';
 import { mappingTextTag } from '../../../mapping/text';
+import { TableColumnMappingWidthMode } from '../types';
+import { iconQuestionTag } from '../../../icons/question';
 
 const data = [
     {
@@ -80,6 +82,19 @@ const component = (): ViewTemplate => html`
             <${mappingIconTag} key="1" text="One" icon="${iconCheckTag}" severity="warning"></${mappingIconTag}>
             <${mappingIconTag} key="2" text="Two" icon="${iconCheckTag}" severity="error"></${mappingIconTag}>
         </${tableColumnIconTag}>
+        <${tableColumnIconTag}
+            field-name="code"
+            key-type="number"
+            width-mode="${_ => TableColumnMappingWidthMode.iconSize}"
+        >
+            <${iconQuestionTag} title="Icon-only column"></${iconQuestionTag}>
+            <${mappingIconTag} key="-1" text="Unknown value"></${mappingIconTag}>
+            <${mappingIconTag} key="0" text="Zero" icon="${iconCheckTag}" severity="success" text-hidden></${mappingIconTag}>
+            <${mappingIconTag} key="1" text="One" icon="${iconCheckTag}" severity="warning" text-hidden></${mappingIconTag}>
+            <${mappingIconTag} key="2" text="Two" icon="${iconCheckTag}" severity="error" text-hidden></${mappingIconTag}>
+            <${mappingIconTag} key="3" text="Three" icon="${iconCheckTag}" severity="information" text-hidden></${mappingIconTag}>
+            <${mappingIconTag} key="4" text="Four" icon="${iconCheckTag}" text-hidden></${mappingIconTag}>
+        </${tableColumnIconTag}>
         <${tableColumnIconTag}
             field-name="code"
             key-type="number"

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

@@ -19,6 +19,8 @@ import { spinnerTag } from '../../../spinner';
 import { themeProviderTag } from '../../../theme-provider';
 import { TableColumnIconPageObject } from '../testing/table-column-icon.pageobject';
 import { mappingUserTag } from '../../../mapping/user';
+import { TableColumnMappingWidthMode } from '../types';
+import { defaultMinPixelWidth } from '../../base/types';
 
 interface SimpleTableRecord extends TableRecord {
     field1?: MappingKey | null;
@@ -890,4 +892,99 @@ describe('TableColumnIcon', () => {
             });
         }
     });
+
+    describe('width-mode', () => {
+        beforeEach(async () => {
+            ({ connect, disconnect, model } = await setup({
+                keyType: MappingKeyType.string
+            }));
+        });
+
+        it('defaults to `default`', () => {
+            expect(model.col1.widthMode).toBe(
+                TableColumnMappingWidthMode.default
+            );
+            expect(model.col1.columnInternals.resizingDisabled).toBeFalse();
+        });
+
+        it('column configuration is updated when set to `iconSize`', async () => {
+            model.col1.widthMode = TableColumnMappingWidthMode.iconSize;
+            await waitForUpdatesAsync();
+
+            expect(model.col1.columnInternals.resizingDisabled).toBeTrue();
+            expect(model.col1.columnInternals.pixelWidth).toBe(32);
+            expect(model.col1.columnInternals.minPixelWidth).toBe(32);
+        });
+
+        it('column changes back to fractionally sized when changing from `iconSize` to `default`', async () => {
+            model.col1.widthMode = TableColumnMappingWidthMode.iconSize;
+            await waitForUpdatesAsync();
+            model.col1.widthMode = TableColumnMappingWidthMode.default;
+            await waitForUpdatesAsync();
+
+            expect(model.col1.columnInternals.resizingDisabled).toBeFalse();
+            expect(model.col1.columnInternals.pixelWidth).toBe(undefined);
+            expect(model.col1.columnInternals.minPixelWidth).toBe(
+                defaultMinPixelWidth
+            );
+        });
+
+        it('changing min-pixel-width with mode of `iconSize` does not change minimum width of column', async () => {
+            model.col1.widthMode = TableColumnMappingWidthMode.iconSize;
+            await waitForUpdatesAsync();
+            expect(model.col1.columnInternals.minPixelWidth).toBe(32);
+
+            model.col1.minPixelWidth = 500;
+            await waitForUpdatesAsync();
+            expect(model.col1.columnInternals.minPixelWidth).toBe(32);
+        });
+
+        it('previously configured min-pixel-width is retained when switching from `default` to `iconSize` and back to `default`', async () => {
+            model.col1.widthMode = TableColumnMappingWidthMode.default;
+            model.col1.minPixelWidth = 500;
+            await waitForUpdatesAsync();
+            expect(model.col1.columnInternals.minPixelWidth).toBe(500);
+
+            model.col1.widthMode = TableColumnMappingWidthMode.iconSize;
+            await waitForUpdatesAsync();
+            expect(model.col1.columnInternals.minPixelWidth).toBe(32);
+
+            model.col1.widthMode = TableColumnMappingWidthMode.default;
+            await waitForUpdatesAsync();
+            expect(model.col1.columnInternals.minPixelWidth).toBe(500);
+        });
+
+        it('min-pixel-width applied with mode of `iconSize` is used when width-mode changes to `default`', async () => {
+            model.col1.widthMode = TableColumnMappingWidthMode.iconSize;
+            await waitForUpdatesAsync();
+            expect(model.col1.columnInternals.minPixelWidth).toBe(32);
+
+            model.col1.minPixelWidth = 500;
+            await waitForUpdatesAsync();
+            expect(model.col1.columnInternals.minPixelWidth).toBe(32);
+
+            model.col1.widthMode = TableColumnMappingWidthMode.default;
+            await waitForUpdatesAsync();
+            expect(model.col1.columnInternals.minPixelWidth).toBe(500);
+        });
+
+        it('clearing min-pixel-width while in `iconSize` mode resets the minimum width to default', async () => {
+            model.col1.widthMode = TableColumnMappingWidthMode.default;
+            model.col1.minPixelWidth = 500;
+            await waitForUpdatesAsync();
+            expect(model.col1.columnInternals.minPixelWidth).toBe(500);
+
+            model.col1.widthMode = TableColumnMappingWidthMode.iconSize;
+            await waitForUpdatesAsync();
+            model.col1.minPixelWidth = undefined;
+            await waitForUpdatesAsync();
+            expect(model.col1.columnInternals.minPixelWidth).toBe(32);
+
+            model.col1.widthMode = TableColumnMappingWidthMode.default;
+            await waitForUpdatesAsync();
+            expect(model.col1.columnInternals.minPixelWidth).toBe(
+                defaultMinPixelWidth
+            );
+        });
+    });
 });

packages/nimble-components/src/table-column/icon/tests/table-column-icon.stories.ts

@@ -16,6 +16,8 @@ import { mappingSpinnerTag } from '../../../mapping/spinner';
 import { sharedMappingValidityDescription } from '../../enum-base/tests/shared-storybook-docs';
 import { isChromatic } from '../../../utilities/tests/isChromatic';
 import { mappingTextTag } from '../../../mapping/text';
+import { TableColumnMappingWidthMode } from '../types';
+import { iconChartDiagramChildFocusTag } from '../../../icons/chart-diagram-child-focus';
 
 const simpleData = [
     {
@@ -65,10 +67,16 @@ export default metadata;
 interface IconColumnTableArgs extends SharedTableArgs {
     fieldName: string;
     keyType: string;
+    widthMode: keyof typeof TableColumnMappingWidthMode;
     checkValidity: () => void;
     validity: () => void;
 }
 
+const widthModeDescription = `When set to \`iconSize\`, the column will have a fixed width that makes the column the appropriate width to render only a single icon in the cell.
+This should only be set when the header contains a single icon (no text) and none of the child mapping elements will result in text being rendered in a cell. When unset or set
+to \`default\`, the column will be resizable and be sized based on its fractional-width and min-pixel-width values. A column with its \`width-mode\` set to \`iconSize\` should
+should not be the right-most column in the table.`;
+
 const validityDescription = `${sharedMappingValidityDescription}
 -   \`invalidIconName\`: \`true\` when a mapping's \`icon\` value is not the tag name of a valid, loaded Nimble icon (e.g. \`nimble-icon-check\`)
 `;
@@ -91,10 +99,11 @@ export const iconColumn: StoryObj<IconColumnTableArgs> = {
                 <${mappingSpinnerTag} key="calculating" text="Calculating" text-hidden></${mappingSpinnerTag}>
                 <${mappingIconTag} key="unknown" text="Unknown" text-hidden></${mappingIconTag}>
             </${tableColumnIconTag}>
-            <${tableColumnIconTag} field-name="isChild" key-type="boolean">
-                Is Child
-                <${mappingIconTag} key="false" icon="${iconXmarkTag}" severity="error" text="Not a child"></${mappingIconTag}>
-                <${mappingIconTag} key="true" icon="${iconCheckLargeTag}" severity="success" text="Is a child"></${mappingIconTag}>
+            <${tableColumnIconTag} field-name="isChild" key-type="boolean" width-mode="${x => TableColumnMappingWidthMode[x.widthMode]}">
+                <${iconChartDiagramChildFocusTag} title="Is child"></${iconChartDiagramChildFocusTag}> 
+
+                <${mappingIconTag} key="false" icon="${iconXmarkTag}" severity="error" text="Not a child" text-hidden></${mappingIconTag}>
+                <${mappingIconTag} key="true" icon="${iconCheckLargeTag}" severity="success" text="Is a child" text-hidden></${mappingIconTag}>
             </${tableColumnIconTag}>
             <${tableColumnIconTag} field-name="gender" key-type="string">
                 Gender
@@ -123,6 +132,12 @@ export const iconColumn: StoryObj<IconColumnTableArgs> = {
             description:
                 'The data type of the key values used for this column. Must be one of `"string"`, `"number"`, or `"boolean"`. Defaults to `"string"` if unspecified.'
         },
+        widthMode: {
+            name: 'width-mode',
+            options: Object.keys(TableColumnMappingWidthMode),
+            control: { type: 'radio' },
+            description: widthModeDescription
+        },
         checkValidity: {
             name: 'checkValidity()',
             description:
@@ -136,6 +151,7 @@ export const iconColumn: StoryObj<IconColumnTableArgs> = {
         ...sharedTableArgs(simpleData),
         fieldName: 'firstName',
         keyType: 'string',
+        widthMode: 'iconSize',
         checkValidity: () => {},
         validity: () => {}
     }

packages/nimble-components/src/table-column/icon/tests/types.spec.ts

@@ -0,0 +1,9 @@
+import type { TableColumnMappingWidthMode } from '../types';
+
+describe('Icon column type', () => {
+    it('TableColumnMappingWidthMode fails compile if assigning arbitrary string values', () => {
+        // @ts-expect-error This expect will fail if the enum-like type is missing "as const"
+        const widthMode: TableColumnMappingWidthMode = 'hello';
+        expect(widthMode!).toEqual('hello');
+    });
+});

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

@@ -0,0 +1,9 @@
+/**
+ * Width mode for the icon column
+ */
+export const TableColumnMappingWidthMode = {
+    default: undefined,
+    iconSize: 'icon-size'
+} as const;
+export type TableColumnMappingWidthMode =
+    (typeof TableColumnMappingWidthMode)[keyof typeof TableColumnMappingWidthMode];

packages/nimble-components/src/table/components/header/index.ts

@@ -21,6 +21,9 @@ export class TableHeader extends FoundationElement {
     @attr({ attribute: 'first-sorted-column', mode: 'boolean' })
     public firstSortedColumn = false;
 
+    @attr({ attribute: 'indicators-hidden', mode: 'boolean' })
+    public indicatorsHidden = false;
+
     @observable
     public isGrouped = false;