renders specific number, boolean, or str
{columnOperationBehavior}
-
-
-## Usage
-### Best Practices
+## API
-- Provide a mapping for every expected record value. Because grouping is performed on the record value, non-mapped record values can result in multiple groups without group labels.
- - To improve grouping behavior of a value that shouldn't be rendered in table cells, use a element to provide text for that value's group row.
-- Avoid having multiple values that map to the same text because grouping and sorting is done on the record value rather than the mapped text.
-
-### Blazor Usage
-
-When setting a child mapping element's `Key` value to a string, you must wrap it in `@()` so that the compiler treats it as a string, e.g.
-``
+
+
-## Icon Mapping
+### Icon Mapping
-## Spinner Mapping
+### Spinner Mapping
-## Text Mapping
+### Text Mapping
-## Empty Mapping
+### Empty Mapping
+
+## Usage
+
+### Best Practices
+
+- Provide a mapping for every expected record value. Because grouping is performed on the record value, non-mapped record values can result in multiple groups without group labels.
+ - To improve grouping behavior of a value that shouldn't be rendered in table cells, use a element to provide text for that value's group row.
+- Avoid having multiple values that map to the same text because grouping and sorting is done on the record value rather than the mapped text.
+
+### Blazor Usage
+
+When setting a child mapping element's `Key` value to a string, you must wrap it in `@()` so that the compiler treats it as a string, e.g.
+``
diff --git a/packages/storybook/src/nimble/table-column/mapping/table-column-mapping.stories.ts b/packages/storybook/src/nimble/table-column/mapping/table-column-mapping.stories.ts
index 861c13fa45..ea3d3534b2 100644
--- a/packages/storybook/src/nimble/table-column/mapping/table-column-mapping.stories.ts
+++ b/packages/storybook/src/nimble/table-column/mapping/table-column-mapping.stories.ts
@@ -18,7 +18,7 @@ import {
sharedTableArgs
} from '../base/table-column-stories-utils';
import { isChromatic } from '../../../utilities/isChromatic';
-import { createUserSelectedThemeStory } from '../../../utilities/storybook';
+import { apiCategory, checkValidityDescription, createUserSelectedThemeStory } from '../../../utilities/storybook';
const simpleData = [
{
@@ -71,6 +71,7 @@ interface MappingColumnTableArgs extends SharedTableArgs {
widthMode: keyof typeof TableColumnMappingWidthMode;
checkValidity: () => void;
validity: () => void;
+ content: undefined;
}
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.
@@ -124,6 +125,7 @@ export const mappingColumn: StoryObj = {
name: 'field-name',
description:
"Set this attribute to identify which field in the data record contains the value for each cell in the column. The field values' type must match the type specified by the `key-type` attribute.",
+ table: { category: apiCategory.attributes },
control: false
},
keyType: {
@@ -131,21 +133,32 @@ export const mappingColumn: StoryObj = {
control: false,
defaultValue: { summary: '"string"' },
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.'
+ 'The data type of the key values used for this column. Must be one of `"string"`, `"number"`, or `"boolean"`. Defaults to `"string"` if unspecified.',
+ table: { category: apiCategory.attributes },
},
widthMode: {
name: 'width-mode',
options: Object.keys(TableColumnMappingWidthMode),
control: { type: 'radio' },
- description: widthModeDescription
+ description: widthModeDescription,
+ table: { category: apiCategory.attributes },
},
checkValidity: {
name: 'checkValidity()',
- description:
- 'Returns `true` if the column configuration is valid, otherwise `false`.'
+ description: checkValidityDescription({ componentName: 'mapping column' }),
+ table: { category: apiCategory.methods },
+ control: false
},
validity: {
- description: validityDescription
+ description: validityDescription,
+ table: { category: apiCategory.nonAttributeProperties },
+ control: false
+ },
+ content: {
+ name: 'default',
+ description: 'One or more mapping elements which specify how to render each possible data value.',
+ table: { category: apiCategory.slots },
+ control: false
}
},
args: {
diff --git a/packages/storybook/src/nimble/table-column/number-text/table-column-number-text.mdx b/packages/storybook/src/nimble/table-column/number-text/table-column-number-text.mdx
index 8891609932..f33eddf679 100644
--- a/packages/storybook/src/nimble/table-column/number-text/table-column-number-text.mdx
+++ b/packages/storybook/src/nimble/table-column/number-text/table-column-number-text.mdx
@@ -5,6 +5,7 @@ import {
noNullAndUndefinedBestPractice
} from '../base/table-column-stories-utils';
import * as tableColumnNumberTextStories from './table-column-number-text.stories';
+import ComponentApisLink from '../../../docs/component-apis-link.mdx';
import { tableColumnNumberTextTag } from '../../../../../nimble-components/src/table-column/number-text';
import { tableTag } from '../../../../../nimble-components/src/table';
import NoNullAndUndefinedBestPractice from '../../patterns/table-column/no-null-and-undefined-best-practice-docs.mdx';
@@ -18,7 +19,11 @@ based on the value of the `lang` token, which can be set via the [nimble-theme-p
{columnOperationBehavior}
+
+## API
+
+
{/* ## Styling */}
diff --git a/packages/storybook/src/nimble/table-column/number-text/table-column-number-text.stories.ts b/packages/storybook/src/nimble/table-column/number-text/table-column-number-text.stories.ts
index f19898ff3e..1d49175f92 100644
--- a/packages/storybook/src/nimble/table-column/number-text/table-column-number-text.stories.ts
+++ b/packages/storybook/src/nimble/table-column/number-text/table-column-number-text.stories.ts
@@ -15,7 +15,7 @@ import {
sharedTableArgTypes,
sharedTableArgs
} from '../base/table-column-stories-utils';
-import { createUserSelectedThemeStory } from '../../../utilities/storybook';
+import { apiCategory, checkValidityDescription, createUserSelectedThemeStory } from '../../../utilities/storybook';
const simpleData = [
{
@@ -186,48 +186,58 @@ export const numberTextColumn: StoryObj = {
name: 'field-name',
description:
'Set this attribute to identify which field in the data record should be displayed in each column. The field values must be of type `number`.',
- control: false
+ control: false,
+ table: { category: apiCategory.attributes },
},
placeholder: {
description:
- 'The placeholder text to display when the field value is `undefined` or `null` for a record.'
+ 'The placeholder text to display when the field value is `undefined` or `null` for a record.',
+ table: { category: apiCategory.attributes },
},
format: {
description: formatDescription,
options: Object.keys(NumberTextFormat),
- control: { type: 'radio' }
+ control: { type: 'radio' },
+ table: { category: apiCategory.attributes },
},
alignment: {
description: alignmentDescription,
options: Object.keys(NumberTextAlignment),
- control: { type: 'radio' }
+ control: { type: 'radio' },
+ table: { category: apiCategory.attributes },
},
decimalDigits: {
name: 'decimal-digits',
description:
"The number of decimal places to format values to when the column's `format` is configured to be `decimal`. If neither `decimal-digits` or `decimal-maximum-digits` are set, a default value of `2` is used. `decimal-digits` and `decimal-maximum-digits` cannot both be set at the same time. The value must be in the range 0 - 20 (inclusive).",
options: [undefined, 0, 1, 2, 3],
- control: { type: 'select' }
+ control: { type: 'select' },
+ table: { category: apiCategory.attributes },
},
decimalMaximumDigits: {
name: 'decimal-maximum-digits',
description:
"The maximum number of decimal places to format values to when the column's `format` is configured to be `decimal`. This differs from `decimal-digits` in that trailing zeros are omitted. `decimal-digits` and `decimal-maximum-digits` cannot both be set at the same time. The value must be in the range 0 - 20 (inclusive).",
options: [undefined, 0, 1, 2, 3, 20],
- control: { type: 'select' }
+ control: { type: 'select' },
+ table: { category: apiCategory.attributes },
},
unit: {
description: unitDescription,
options: ['default', 'byte', 'byte (1024)', 'degrees Celsius', 'degrees Fahrenheit', 'volt'],
- control: { type: 'radio' }
+ control: { type: 'radio' },
+ table: { category: apiCategory.attributes },
},
checkValidity: {
name: 'checkValidity()',
- description:
- 'Returns `true` if the column configuration is valid, otherwise `false`.'
+ description: checkValidityDescription({ componentName: 'number text column' }),
+ control: false,
+ table: { category: apiCategory.methods },
},
validity: {
- description: validityDescription
+ description: validityDescription,
+ control: false,
+ table: { category: apiCategory.nonAttributeProperties },
}
},
args: {
diff --git a/packages/storybook/src/nimble/table-column/text/table-column-text.mdx b/packages/storybook/src/nimble/table-column/text/table-column-text.mdx
index def6b24236..9b778f2c5a 100644
--- a/packages/storybook/src/nimble/table-column/text/table-column-text.mdx
+++ b/packages/storybook/src/nimble/table-column/text/table-column-text.mdx
@@ -1,6 +1,7 @@
import { Canvas, Meta, Controls, Title } from '@storybook/blocks';
import { NimbleTableColumnText } from './table-column-text.react';
import * as tableColumnTextStories from './table-column-text.stories';
+import ComponentApisLink from '../../../docs/component-apis-link.mdx';
import { tableColumnTextTag } from '../../../../../nimble-components/src/table-column/text';
import { tableTag } from '../../../../../nimble-components/src/table';
import NoNullAndUndefinedBestPractice from '../../patterns/table-column/no-null-and-undefined-best-practice-docs.mdx';
@@ -11,7 +12,11 @@ import NoNullAndUndefinedBestPractice from '../../patterns/table-column/no-null-
The column is used to display string fields as text in the .
+
+## API
+
+
{/* ## Styling */}
diff --git a/packages/storybook/src/nimble/table-column/text/table-column-text.stories.ts b/packages/storybook/src/nimble/table-column/text/table-column-text.stories.ts
index 6af7db88cf..fee7759fe6 100644
--- a/packages/storybook/src/nimble/table-column/text/table-column-text.stories.ts
+++ b/packages/storybook/src/nimble/table-column/text/table-column-text.stories.ts
@@ -9,7 +9,7 @@ import {
sharedTableArgTypes,
sharedTableArgs
} from '../base/table-column-stories-utils';
-import { createUserSelectedThemeStory } from '../../../utilities/storybook';
+import { apiCategory, createUserSelectedThemeStory } from '../../../utilities/storybook';
const simpleData = [
{
@@ -95,11 +95,13 @@ export const textColumn: StoryObj = {
description:
'Set this attribute to identify which field in the data record should be displayed in each column. The field values must be of type `string`.',
options: ['firstName', 'lastName'],
- control: { type: 'radio' }
+ control: { type: 'radio' },
+ table: { category: apiCategory.attributes },
},
placeholder: {
description:
- 'The placeholder text to display when the field value is `undefined` or `null` for a record.'
+ 'The placeholder text to display when the field value is `undefined` or `null` for a record.',
+ table: { category: apiCategory.attributes },
}
},
args: {
diff --git a/packages/storybook/src/nimble/table/table.mdx b/packages/storybook/src/nimble/table/table.mdx
index f2fe197fea..73aab1501a 100644
--- a/packages/storybook/src/nimble/table/table.mdx
+++ b/packages/storybook/src/nimble/table/table.mdx
@@ -1,17 +1,33 @@
import { Controls, Canvas, Meta, Title } from '@storybook/blocks';
import * as tableStories from './table.stories';
+import ComponentApisLink from '../../docs/component-apis-link.mdx';
import { tableTag } from '../../../../nimble-components/src/table';
The is a component that offers a way to render tabular data in a variety of ways in each column.
-For information about configuring table columns, see **Table Column Configuration** and **Table Column Types**.
+For information about configuring table columns, see [Table Column Configuration](?path=/docs/components-table-column-configuration--docs)
+and the **Table Column** pages for individual table column types.
+
+## API
+
+
+
+## Styling
+
+### Sizing
+
+The should be sized explicitly or sized to fill the space of a parent container. The 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).
+
+{/* ## Usage */}
-## Delay-loaded Hierarchy
+## Examples
+
+### Delay-loaded hierarchy
In some cases, it may be known that a record has children, but the records for those children are not known. For performance reasons, it may be preferred to load
the children on demand when a user expands the parent row. To accomplish this, use the `setRecordHierarchyOptions()` function on the table to set the hierarchy
@@ -20,7 +36,7 @@ options associated with records in the data.
-### Delay-loaded Hierarchy Usage
+#### Using delay-loaded hierarchy
The expected usage of the dynamically loaded hierarchy is as follows:
@@ -39,7 +55,7 @@ The expected usage of the dynamically loaded hierarchy is as follows:
- If loading the data determines that the row doesn't actually have children:
1. Call `setRecordHierarchyOptions` to change the row state to `{ delayedHierarchyState: TableRecordDelayedHierarchyState.none }`. This call must include the current state of any records not in the default state.
-### setRecordHierarchyOptions Behavior
+#### Behavior of setRecordHierarchyOptions
`setRecordHierarchyOptions()` has the following behavior:
@@ -49,16 +65,6 @@ The expected usage of the dynamically loaded hierarchy is as follows:
- the table will not render delayed hierarchy state (loading or expandable) if the table's `parentIdFieldName` is not configured; however, the options will remain cached within the table if the `parentIdFieldName` becomes `undefined`, and that cached configuration will render in the table if the table's `parentIdFieldName` is changed back to a non-`undefined` value
- calling `setData` will clear options associated with IDs that are no longer present in the data
-## Styling
-
-### Sizing
-
-The should be sized explicitly or sized to fill the space of a parent container. The 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).
-
-{/* ## Usage */}
-
-{/* ## Examples */}
-
{/* ## Accessibility */}
{/* ## Resources */}
diff --git a/packages/storybook/src/nimble/table/table.stories.ts b/packages/storybook/src/nimble/table/table.stories.ts
index 0bee5c0971..a663b57b92 100644
--- a/packages/storybook/src/nimble/table/table.stories.ts
+++ b/packages/storybook/src/nimble/table/table.stories.ts
@@ -14,7 +14,7 @@ import {
addLabelUseMetadata,
type LabelUserArgs
} from '../label-provider/base/label-user-stories-utils';
-import { createUserSelectedThemeStory } from '../../utilities/storybook';
+import { apiCategory, checkValidityDescription, createUserSelectedThemeStory } from '../../utilities/storybook';
import { isChromatic } from '../../utilities/isChromatic';
interface BaseTableArgs extends LabelUserArgs {
@@ -62,6 +62,14 @@ interface TableArgs extends BaseTableArgs {
setSelectedRecordIds: undefined;
getSelectedRecordIds: undefined;
data: ExampleDataType;
+ setRecordHierarchyOptions: undefined;
+ defaultSlot: undefined;
+ actionMenuSlot: undefined;
+ actionMenuBeforetoggle: undefined;
+ actionMenuToggle: undefined;
+ selectionChange: undefined;
+ columnConfigurationChange: undefined;
+ rowExpandToggle: undefined;
}
const simpleData = [
@@ -205,7 +213,7 @@ const dataSets = {
[ExampleDataType.hierarchicalDataSet]: hierarchicalData
} as const;
-const dataDescription = `To set the data on the table, call \`setData()\` with an array data records. Each record is made up of fields,
+const dataDescription = `To set the data on the table, call \`setData()\` with an array of data records. Each record is made up of fields,
which are key/value pairs. The key in each pair must be of type \`string\`, which is defined by the type \`TableFieldName\`. The value
in each pair must be of type \`string\`, \`number\`, \`boolean\`, \`null\`, or \`undefined\`, which is defined by the type \`TableFieldValue\`.
@@ -236,7 +244,7 @@ The attribute is invalid in the following conditions:
const parentIdFieldNameDescription = `An optional string attribute that specifies the field name within a row's record to use as a row's parent ID, which,
when used in combination with the \`id-field-name\` attribute, will display the table data in a hierarchical fashion. If the attribute is not specified, the
-data in the table will always be presented without hierarchy.
+data in the table will be presented without hierarchy. To configure hierarchy dynamically instead, see \`setRecordHierarchyOptions()\`.
The attribute is invalid in the following conditions:
- When this attribute is set, but \`id-field-name\` is unset. This will cause \`validity.idFieldNameNotConfigured\` to be \`true\`.
@@ -326,54 +334,101 @@ export const table: StoryObj = {
[ExampleDataType.largeDataSet]: 'Large data set (10k rows)',
[ExampleDataType.hierarchicalDataSet]: 'Hierarchical data'
}
- }
+ },
+ table: { category: apiCategory.methods },
},
selectionMode: {
- table: {
- defaultValue: { summary: 'none' }
- },
+ name: 'selection-mode',
options: Object.keys(TableRowSelectionMode),
description:
'Controls whether the table supports selecting a single row at a time, multiple rows at a time, or no rows. When selection is enabled, `id-field-name` must be specified.',
- control: { type: 'radio' }
+ control: { type: 'radio' },
+ table: { category: apiCategory.attributes },
},
getSelectedRecordIds: {
name: 'getSelectedRecordIds()',
description:
'A function that returns an array of record IDs that represent the selected row(s) in the table.',
- control: false
+ control: false,
+ table: { category: apiCategory.methods },
},
setSelectedRecordIds: {
name: 'setSelectedRecordIds()',
description: setSelectedRecordIdsDescription,
- control: false
+ control: false,
+ table: { category: apiCategory.methods },
},
idFieldName: {
name: 'id-field-name',
- table: {
- defaultValue: { summary: 'undefined' }
- },
description: idFieldNameDescription,
- control: false
+ control: false,
+ table: { category: apiCategory.attributes },
},
parentIdFieldName: {
name: 'parent-id-field-name',
- table: {
- defaultValue: { summary: 'undefined' }
- },
description: parentIdFieldNameDescription,
- control: false
+ control: false,
+ table: { category: apiCategory.attributes },
},
validity: {
description: validityDescription,
- control: false
+ control: false,
+ table: { category: apiCategory.nonAttributeProperties },
},
checkValidity: {
name: 'checkValidity()',
- description:
- 'A function that returns `true` if the configuration of the table is valid and `false` if the configuration of the table is not valid.',
- control: false
- }
+ description: checkValidityDescription({ componentName: 'table' }),
+ control: false,
+ table: { category: apiCategory.methods },
+ },
+ setRecordHierarchyOptions: {
+ name: 'setRecordHierarchyOptions()',
+ description: 'Used to configure the hierarchy state of rows dynamically. To set static hierarchy, use `parent-id-field-name` instead. See the **Delay-loaded Hierarchy** section for more information.',
+ control: false,
+ table: { category: apiCategory.methods },
+ },
+ defaultSlot: {
+ name: 'default',
+ description: 'Configure table columns by adding them as child elements in the default slot. See **Table Column Configuration** for more information.',
+ control: false,
+ table: { category: apiCategory.slots },
+ },
+ actionMenuSlot: {
+ name: 'Action menus',
+ description: `To add an action menu to a column, add a \`${menuTag}\` element as a child of the table and set its slot attribute to a custom value. Then configure the column's \`action-menu-slot\` attribute to the same value. You can configure different action menus for multiple columns by giving them unique slot names.`,
+ control: false,
+ table: { category: apiCategory.slots },
+ },
+ actionMenuBeforetoggle: {
+ name: 'action-menu-beforetoggle',
+ description: 'Event emitted before an action menu opens or closes. This can be used to populate the menu before it is visible.',
+ control: false,
+ table: { category: apiCategory.events },
+ },
+ actionMenuToggle: {
+ name: 'action-menu-toggle',
+ description: 'Event emitted after an action menu opens or closes.',
+ control: false,
+ table: { category: apiCategory.events },
+ },
+ selectionChange: {
+ name: 'selection-change',
+ description: 'Event emitted when the user changes which rows are selected.',
+ control: false,
+ table: { category: apiCategory.events },
+ },
+ columnConfigurationChange: {
+ name: 'column-configuration-change',
+ description: 'Event emitted when the user changes a column\'s width or sort order.',
+ control: false,
+ table: { category: apiCategory.events },
+ },
+ rowExpandToggle: {
+ name: 'row-expand-toggle',
+ description: '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 },
+ },
},
args: {
data: ExampleDataType.simpleData,
diff --git a/packages/storybook/src/utilities/storybook.ts b/packages/storybook/src/utilities/storybook.ts
index 733b14a251..84cbc80a15 100644
--- a/packages/storybook/src/utilities/storybook.ts
+++ b/packages/storybook/src/utilities/storybook.ts
@@ -187,3 +187,5 @@ export const dropdownPositionDescription = (options: { componentName: string }):
export const optionsDescription = `The \`${listOptionTag}\` items for the user to select from.`;
export const preventDismissDescription = (options: { componentName: string }): string => `Prevents the \`Esc\` key from closing the ${options.componentName}.`;
+
+export const checkValidityDescription = (options: { componentName: string }): string => `Returns \`true\` if the configuration of the ${options.componentName} is valid, otherwise \`false\`.`;