Add token representing the height of the table with all rows visible

change/@ni-nimble-components-a5fd15e6-373b-4e3c-b562-fc2e440df26c.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "Add token to allow the table's height to be configured to the height of all table rows",
+  "packageName": "@ni/nimble-components",
+  "email": "[email protected]",
+  "dependentChangeType": "patch"
+}

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

@@ -10,7 +10,10 @@ import {
     mediumPadding,
     standardPadding,
     tableRowBorderColor,
-    borderHoverColor
+    borderHoverColor,
+    controlHeight,
+    tableFitRowsHeight,
+    borderWidth
 } from '../theme-provider/design-tokens';
 import { Theme } from '../theme-provider/types';
 import { hexToRgbaCssColor } from '../utilities/style/colors';
@@ -25,6 +28,16 @@ export const styles = css`
 
     :host {
         height: 480px;
+        ${tableFitRowsHeight.cssCustomProperty}: calc(var(--ni-private-table-scroll-height) + ${controlHeight});
+        ${
+            /**
+             * Set a default maximum height for the table of 40.5 rows plus the header row so
+             * that clients don't accidentally create a table that tries to render too many rows at once.
+             * If needed, the max-height can be overridden by the client, but setting a default ensures
+             * that the max-height is considered if a larger one is needed rather than being overlooked.
+             */ ''
+        }
+        max-height: calc(${controlHeight} + (40.5 * (2 * ${borderWidth} + ${controlHeight})));
         --ni-private-column-divider-width: 2px;
         --ni-private-column-divider-padding: 3px;
     }

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

@@ -41,11 +41,11 @@ export const template = html<Table>`
         aria-multiselectable="${x => x.ariaMultiSelectable}"
         ${children({ property: 'childItems', filter: elements() })}
     >
+        <style>:host{ --ni-private-table-scroll-height: ${x => x.virtualizer.scrollHeight}px; }</style>
         <div class="table-container ${x => (x.windowShiftKeyDown ? 'disable-select' : '')}"
             style="
             --ni-private-table-scroll-x: -${x => x.scrollX}px;
             --ni-private-table-header-container-margin-right: ${x => x.virtualizer.headerContainerMarginRight}px;
-            --ni-private-table-scroll-height: ${x => x.virtualizer.scrollHeight}px;
             --ni-private-table-row-container-top: ${x => x.virtualizer.rowContainerYOffset}px;
             --ni-private-table-row-grid-columns: ${x => (x.rowGridColumns ? x.rowGridColumns : '')};
             --ni-private-table-cursor-override: ${x => (x.layoutManager.isColumnBeingSized ? 'col-resize' : 'default')};

packages/nimble-components/src/theme-provider/design-token-comments.ts

@@ -74,6 +74,7 @@ export const comments: { readonly [key in TokenName]: string } = {
     spinnerSmallHeight: 'Small height (16px) for a spinner component',
     spinnerMediumHeight: 'Medium height (32px) for a spinner component',
     spinnerLargeHeight: 'Large height (64px) for a spinner component',
+    tableFitRowsHeight: 'The height of the table when all rows are visible',
     smallDelay:
         'Elements with small transition areas, such as icons and selection controls, have short durations.',
     mediumDelay:

packages/nimble-components/src/theme-provider/design-token-names.ts

@@ -59,6 +59,7 @@ export const tokenNames: { readonly [key in TokenName]: string } = {
     spinnerSmallHeight: 'spinner-small-height',
     spinnerMediumHeight: 'spinner-medium-height',
     spinnerLargeHeight: 'spinner-large-height',
+    tableFitRowsHeight: 'table-fit-rows-height',
     smallDelay: 'small-delay',
     mediumDelay: 'medium-delay',
     largeDelay: 'large-delay',

packages/nimble-components/src/theme-provider/design-tokens.ts

@@ -503,6 +503,12 @@ export const spinnerLargeHeight = DesignToken.create<string>(
     styleNameFromTokenName(tokenNames.spinnerLargeHeight)
 ).withDefault('64px');
 
+// The token gets a default value of the table's default height (480px)
+// but is given a calculated value in the table styles.
+export const tableFitRowsHeight = DesignToken.create<string>(
+    styleNameFromTokenName(tokenNames.tableFitRowsHeight)
+).withDefault('480px');
+
 // Drop Shadow Tokens
 export const elevation1BoxShadow = DesignToken.create<string>(
     styleNameFromTokenName(tokenNames.elevation1BoxShadow)

packages/storybook/src/nimble/table/table-fit-rows-height-matrix.stories.ts

@@ -0,0 +1,86 @@
+import type { Meta, StoryFn } from '@storybook/html';
+import { html, ViewTemplate } from '@microsoft/fast-element';
+import { tableColumnTextTag } from '../../../../nimble-components/src/table-column/text';
+import { Table, tableTag } from '../../../../nimble-components/src/table';
+import type { TableRecord } from '../../../../nimble-components/src/table/types';
+import { tableFitRowsHeight } from '../../../../nimble-components/src/theme-provider/design-tokens';
+import { createFixedThemeStory } from '../../utilities/storybook';
+import { createMatrix, sharedMatrixParameters } from '../../utilities/matrix';
+import { backgroundStates } from '../../utilities/states';
+
+interface SimpleData extends TableRecord {
+    firstName: string;
+    lastName: string;
+    favoriteColor: string;
+}
+
+const data: SimpleData[] = [];
+for (let i = 0; i < 50; i++) {
+    data.push({
+        firstName: `First Name ${i}`,
+        lastName: `Last Name ${i}`,
+        favoriteColor: `Favorite Color ${i}`
+    });
+}
+
+const groupingStates = [
+    ['Not Grouped', undefined],
+    ['Grouped', 0]
+] as const;
+type GroupingState = (typeof groupingStates)[number];
+
+const metadata: Meta = {
+    title: 'Tests/Table',
+    parameters: {
+        ...sharedMatrixParameters()
+    }
+};
+
+export default metadata;
+
+// prettier-ignore
+const component = (
+    [_groupingName, groupIndex]: GroupingState
+): ViewTemplate => html`
+    <style>
+        ${tableTag} {
+            height: var(${tableFitRowsHeight.cssCustomProperty});
+            margin-bottom: 20px;
+        }
+    </style>
+    <${tableTag}>
+        <${tableColumnTextTag} field-name="firstName" group-index="${() => groupIndex}">First Name</${tableColumnTextTag}>
+        <${tableColumnTextTag} field-name="lastName">Last Name</${tableColumnTextTag}>
+        <${tableColumnTextTag} field-name="favoriteColor">Favorite Color</${tableColumnTextTag}>
+    </${tableTag}>
+`;
+
+const playFunction = async (rowCount: number): Promise<void> => {
+    const tableData = data.slice(0, rowCount);
+    await Promise.all(
+        Array.from(document.querySelectorAll<Table>(tableTag)).map(
+            async table => {
+                await table.setData(tableData);
+            }
+        )
+    );
+};
+
+export const tableFitRowsHeightWith5Rows: StoryFn = createFixedThemeStory(
+    createMatrix(component, [groupingStates]),
+    backgroundStates[0]
+);
+
+tableFitRowsHeightWith5Rows.play = async () => playFunction(5);
+
+export const tableFitRowsHeightWith10Rows: StoryFn = createFixedThemeStory(
+    createMatrix(component, [groupingStates]),
+    backgroundStates[0]
+);
+tableFitRowsHeightWith10Rows.play = async () => playFunction(10);
+
+export const tableFitRowsHeightWith50Rows: StoryFn = createFixedThemeStory(
+    createMatrix(component, [groupingStates]),
+    backgroundStates[0]
+);
+tableFitRowsHeightWith50Rows.play = async () => playFunction(50);

packages/storybook/src/nimble/table/table.mdx

@@ -21,13 +21,6 @@ and the **Table Column** pages for individual table column types.
 
 ## Styling
 
-### Sizing
-
-The <Tag name={tableTag}/> should be sized explicitly or sized to fill the space
-of a parent container. The <Tag name={tableTag}/> does not currently support
-being styled with `height: auto`. The ability to auto size the table is tracked
-with [issue 1624](https://github.com/ni/nimble/issues/1624).
-
 ### Full bleed
 
 The table will reserve space for expand/collapse row buttons and the collapse

packages/storybook/src/nimble/table/table.stories.ts

@@ -1,6 +1,7 @@
 import { html, ref } from '@microsoft/fast-element';
 import { withActions } from '@storybook/addon-actions/decorator';
 import type { HtmlRenderer, Meta, StoryObj } from '@storybook/html';
+import { tableFitRowsHeight } from '../../../../nimble-components/src/theme-provider/design-tokens';
 import { iconUserTag } from '../../../../nimble-components/src/icons/user';
 import { menuTag } from '../../../../nimble-components/src/menu';
 import { menuItemTag } from '../../../../nimble-components/src/menu-item';
@@ -78,6 +79,7 @@ interface TableArgs extends BaseTableArgs {
     selectionChange: undefined;
     columnConfigurationChange: undefined;
     rowExpandToggle: undefined;
+    fitRowsHeight: boolean;
 }
 
 const simpleData = [
@@ -263,9 +265,19 @@ const setSelectedRecordIdsDescription = `A function that makes the rows associat
 If a record does not exist in the table's data, it will not be selected. If multiple record IDs are specified when the table's selection
 mode is \`single\`, only the first record that exists in the table's data will become selected.`;
 
+const fitRowsHeightDescription = `Style the table's with \`height: $${tableFitRowsHeight.name};\` to make the table's height grow to fit all rows.
+
+Note: The table has a default maximum height that will render approximately 40 rows to avoid performance problems. Use caution when overriding the maximum height
+of the table because this may lead to performance issues.`;
+
 export const table: StoryObj<TableArgs> = {
     // prettier-ignore
     render: createUserSelectedThemeStory(html<TableArgs>`
+        <style>
+            nimble-table {
+                ${x => (x.fitRowsHeight ? `height: var(${tableFitRowsHeight.cssCustomProperty})` : '')}
+            }
+        </style>
         <${tableTag}
             ${ref('tableRef')}
             selection-mode="${x => TableRowSelectionMode[x.selectionMode]}"
@@ -485,6 +497,11 @@ export const table: StoryObj<TableArgs> = {
                 'Event emitted when the user expands or collapses a row in a table with hierarchy. This does not emit when group rows are expanded or collapsed.',
             control: false,
             table: { category: apiCategory.events }
+        },
+        fitRowsHeight: {
+            name: 'Fit rows height',
+            description: fitRowsHeightDescription,
+            table: { category: apiCategory.styles }
         }
     },
     args: {
@@ -494,6 +511,7 @@ export const table: StoryObj<TableArgs> = {
         validity: undefined,
         checkValidity: undefined,
         tableRef: undefined,
+        fitRowsHeight: true,
         updateData: x => {
             void (async () => {
                 // Safari workaround: the table element instance is made at this point