Improve API documentation of table components (#2140)

# Pull Request ## 🤨 Rationale Ongoing efforts towards #824. This PR covers the table and its columns. ## 👩‍💻 Implementation Mostly following established patterns. Some interesting notes: 1. For the Table Column Configuration doc, we had divided the documentation into separate targeted stories. I decided these were useful but we also should have a single table describing the whole API of a column. I created the latter under the API section and moved the targeted stories to an Examples section. Let me know if it feels right! 2. The above resulted in a renamed story which appears as a Chromatic diff. ## 🧪 Testing Interacting with the built Storybook. ## ✅ Checklist  - [x] I have updated the project documentation to reflect my changes or determined no changes are needed.
ni · May 30, 2024 · aca764d · aca764d
1 parent 4557120
commit aca764d
Show file tree

Hide file tree

Showing 23 changed files with 405 additions and 152 deletions.
diff --git a/packages/storybook/.storybook/preview.js b/packages/storybook/.storybook/preview.js
@@ -105,5 +105,5 @@ configureActions({
     depth: 1
 });
 
-// Update the GUID on this line to trigger a turbosnap full rebuild: 354fdf0e-bdb4-4dd9-a6e5-21bf71c6efe6
+// Update the GUID on this line to trigger a turbosnap full rebuild: 354fdf0f-bdb4-4dd9-a6e5-21bf71c6efe6
 // See https://www.chromatic.com/docs/turbosnap/#full-rebuilds
diff --git a/packages/storybook/src/nimble/mapping/empty/mapping-empty.stories.ts b/packages/storybook/src/nimble/mapping/empty/mapping-empty.stories.ts
@@ -1,7 +1,7 @@
 import { html } from '@microsoft/fast-element';
 import type { Meta, StoryObj } from '@storybook/html';
 import { mappingKeyDescription } from '../base/story-helpers';
-import { createUserSelectedThemeStory } from '../../../utilities/storybook';
+import { apiCategory, createUserSelectedThemeStory } from '../../../utilities/storybook';
 import { hiddenWrapper } from '../../../utilities/hidden';
 
 const metadata: Meta = {
@@ -25,11 +25,13 @@ export const emptyMapping: StoryObj = {
     argTypes: {
         key: {
             control: false,
-            description: mappingKeyDescription('nothing')
+            description: mappingKeyDescription('nothing'),
+            table: { category: apiCategory.attributes },
         },
         text: {
             control: false,
-            description: 'A textual description of the value. This value will be displayed in group rows, but table cells will be empty. This attribute is required.'
+            description: 'A textual description of the value. This value will be displayed in group rows, but table cells will be empty. This attribute is required.',
+            table: { category: apiCategory.attributes },
         }
     },
     args: {}

diff --git a/packages/storybook/src/nimble/mapping/icon/mapping-icon.stories.ts b/packages/storybook/src/nimble/mapping/icon/mapping-icon.stories.ts
@@ -1,7 +1,7 @@
 import { html } from '@microsoft/fast-element';
 import type { Meta, StoryObj } from '@storybook/html';
 import { mappingKeyDescription } from '../base/story-helpers';
-import { createUserSelectedThemeStory } from '../../../utilities/storybook';
+import { apiCategory, createUserSelectedThemeStory } from '../../../utilities/storybook';
 import { hiddenWrapper } from '../../../utilities/hidden';
 
 const metadata: Meta = {
@@ -23,28 +23,33 @@ export const iconMapping: StoryObj = {
     argTypes: {
         key: {
             description: mappingKeyDescription('the mapped icon'),
-            control: false
+            control: false,
+            table: { category: apiCategory.attributes },
         },
         icon: {
             control: false,
-            description: 'The tag name of the Nimble icon to render, e.g. `nimble-icon-check`.'
+            description: 'The tag name of the Nimble icon to render, e.g. `nimble-icon-check`.',
+            table: { category: apiCategory.attributes },
         },
         severity: {
             control: false,
             description:
-                'Must be one of the values in the `IconSeverity` enum. Controls the color of the icon.'
+                'Must be one of the values in the `IconSeverity` enum. Controls the color of the icon.',
+            table: { category: apiCategory.attributes },
         },
         text: {
             control: false,
             description: `A textual description of the value. The text will be displayed next to the icon in a cell if \`text-hidden\` is not set,
             or as the tooltip and accessible  name of the icon if \`text-hidden\` is set. The text is also displayed next to the icon
-            in a group header. This attribute is required.`
+            in a group header. This attribute is required.`,
+            table: { category: apiCategory.attributes },
         },
         textHidden: {
             control: false,
             name: 'text-hidden',
             description:
-                "When set, the text is hidden within the table's cells. When unset, the text is rendered next to the icon within the cell."
+                "When set, the text is hidden within the table's cells. When unset, the text is rendered next to the icon within the cell.",
+            table: { category: apiCategory.attributes },
         }
     },
     args: {}

diff --git a/packages/storybook/src/nimble/mapping/spinner/mapping-spinner.stories.ts b/packages/storybook/src/nimble/mapping/spinner/mapping-spinner.stories.ts
@@ -1,7 +1,7 @@
 import { html } from '@microsoft/fast-element';
 import type { Meta, StoryObj } from '@storybook/html';
 import { mappingKeyDescription } from '../base/story-helpers';
-import { createUserSelectedThemeStory } from '../../../utilities/storybook';
+import { apiCategory, createUserSelectedThemeStory } from '../../../utilities/storybook';
 import { hiddenWrapper } from '../../../utilities/hidden';
 
 const metadata: Meta = {
@@ -23,19 +23,22 @@ export const spinnerMapping: StoryObj = {
     argTypes: {
         key: {
             description: mappingKeyDescription('a spinner'),
-            control: false
+            control: false,
+            table: { category: apiCategory.attributes },
         },
         text: {
             control: false,
             description: `A textual description of the value. The text will be displayed next to the spinner in a cell if \`text-hidden\` is not set,
                 or as the tooltip and accessible  name of the spinner if \`text-hidden\` is set. The text is also displayed next to the spinner
-                in a group header. This attribute is required.`
+                in a group header. This attribute is required.`,
+            table: { category: apiCategory.attributes },
         },
         textHidden: {
             control: false,
             name: 'text-hidden',
             description:
-                "When set, the text is hidden within the table's cells. When unset, the text is rendered next to the spinner within the cell."
+                "When set, the text is hidden within the table's cells. When unset, the text is rendered next to the spinner within the cell.",
+            table: { category: apiCategory.attributes },
         }
     },
     args: {}

diff --git a/packages/storybook/src/nimble/mapping/text/mapping-text.stories.ts b/packages/storybook/src/nimble/mapping/text/mapping-text.stories.ts
@@ -1,7 +1,7 @@
 import { html } from '@microsoft/fast-element';
 import type { Meta, StoryObj } from '@storybook/html';
 import { mappingKeyDescription } from '../base/story-helpers';
-import { createUserSelectedThemeStory } from '../../../utilities/storybook';
+import { apiCategory, createUserSelectedThemeStory } from '../../../utilities/storybook';
 import { hiddenWrapper } from '../../../utilities/hidden';
 
 const metadata: Meta = {
@@ -23,10 +23,12 @@ export const textMapping: StoryObj = {
     argTypes: {
         key: {
             description: mappingKeyDescription('the mapped display text'),
-            control: false
+            control: false,
+            table: { category: apiCategory.attributes },
         },
         text: {
-            description: 'The display text.'
+            description: 'The display text.',
+            table: { category: apiCategory.attributes },
         }
     },
     args: {}

diff --git a/packages/storybook/src/nimble/mapping/user/mapping-user.stories.ts b/packages/storybook/src/nimble/mapping/user/mapping-user.stories.ts
@@ -1,6 +1,6 @@
 import { html } from '@microsoft/fast-element';
 import type { Meta, StoryObj } from '@storybook/html';
-import { createUserSelectedThemeStory } from '../../../utilities/storybook';
+import { apiCategory, createUserSelectedThemeStory } from '../../../utilities/storybook';
 import { hiddenWrapper } from '../../../utilities/hidden';
 
 const metadata: Meta = {
@@ -21,13 +21,15 @@ export const userMapping: StoryObj = {
     render: createUserSelectedThemeStory(hiddenWrapper(html`<style></style>`)),
     argTypes: {
         key: {
-            description: 'A key (url) for each user that maps to a user',
-            control: false
+            description: 'A URL that uniquely identifies the user, e.g. `user:1234`.',
+            control: false,
+            table: { category: apiCategory.attributes },
         },
         displayName: {
             name: 'display-name',
             description:
-                'A string which renders the textual representation of user name'
+                'The display name to render for the user, e.g. `Oscar Meyer 🌭`.',
+            table: { category: apiCategory.attributes },
         }
     },
     args: {}

diff --git a/packages/storybook/src/nimble/table-column/anchor/table-column-anchor.mdx b/packages/storybook/src/nimble/table-column/anchor/table-column-anchor.mdx
@@ -1,6 +1,7 @@
 import { Controls, Canvas, Meta, Title } from '@storybook/blocks';
 import TargetDocs from '../../patterns/anchor/target-docs.mdx';
 import * as tableColumnAnchorStories from './table-column-anchor.stories';
+import ComponentApisLink from '../../../docs/component-apis-link.mdx';
 import { tableColumnAnchorTag } from '../../../../../nimble-components/src/table-column/anchor';
 import { tableTag } from '../../../../../nimble-components/src/table';
 
@@ -14,6 +15,7 @@ The <Tag name={tableColumnAnchorTag}/> column is used to display string fields a
 ## API
 
 <Controls of={tableColumnAnchorStories.anchorColumn} />
+<ComponentApisLink />
 
 ### Target Configuration
 

diff --git a/packages/storybook/src/nimble/table-column/anchor/table-column-anchor.stories.ts b/packages/storybook/src/nimble/table-column/anchor/table-column-anchor.stories.ts
@@ -11,7 +11,7 @@ import {
     sharedTableArgs,
     sharedTableArgTypes
 } from '../base/table-column-stories-utils';
-import { createUserSelectedThemeStory } from '../../../utilities/storybook';
+import { apiCategory, createUserSelectedThemeStory } from '../../../utilities/storybook';
 
 const metadata: Meta<SharedTableArgs> = {
     title: 'Components/Table Column: Anchor',
@@ -102,28 +102,33 @@ export const anchorColumn: StoryObj<AnchorColumnTableArgs> = {
             description:
                 'Set this attribute to identify which field in the data record contains the visible text value for each cell in the column. The field values must be of type `string`. If a given row does not define a property with this name, that row will use the url as the label.',
             options: ['firstName', 'lastName'],
-            control: { type: 'radio' }
+            control: { type: 'radio' },
+            table: { category: apiCategory.attributes },
         },
         hrefFieldName: {
             name: 'href-field-name',
             description:
                 'Set this attribute to identify which field in the data record contains the link url for each cell in the column. If the field is not defined in a particular record, that cell will be displayed as plain text instead of a link. The field values must be of type `string`.',
-            control: false
+            control: false,
+            table: { category: apiCategory.attributes },
         },
         appearance: {
             options: Object.keys(AnchorAppearance),
             control: { type: 'radio' },
             description:
-                'Set to `prominent` to make the anchor appear in a different color than normal text. This has no effect under the Color theme.'
+                'Set to `prominent` to make the anchor appear in a different color than normal text. This has no effect under the Color theme.',
+            table: { category: apiCategory.attributes },
         },
         underlineHidden: {
             name: 'underline-hidden',
             defaultValue: { summary: 'false' },
-            description: 'Causes the underline to be hidden except on hover.'
+            description: 'Causes the underline to be hidden except on hover.',
+            table: { category: apiCategory.attributes },
         },
         placeholder: {
             description:
-                'The placeholder text to display when the label and href are both `undefined` or `null` for a record.'
+                'The placeholder text to display when the label and href are both `undefined` or `null` for a record.',
+            table: { category: apiCategory.attributes },
         }
     },
     args: {

diff --git a/packages/storybook/src/nimble/table-column/base/table-column.mdx b/packages/storybook/src/nimble/table-column/base/table-column.mdx
@@ -1,41 +1,49 @@
 import { Controls, Canvas, Meta, Title, Description } from '@storybook/blocks';
 import * as tableColumnStories from './table-column.stories';
+import ComponentApisLink from '../../../docs/component-apis-link.mdx';
 
 <Meta of={tableColumnStories} />
 <Title of={tableColumnStories} />
 <Description of={tableColumnStories} />
 
-## Adding columns
+## API
+
+<Controls of={tableColumnStories.api} />
+<ComponentApisLink />
+
+## Examples
+
+### Adding columns
 
 <Description of={tableColumnStories.addingColumns} />
 <Canvas of={tableColumnStories.addingColumns} />
 <Controls of={tableColumnStories.addingColumns} />
 
-## Setting header content
+### Setting header content
 
 <Description of={tableColumnStories.headerContent} />
 <Canvas of={tableColumnStories.headerContent} />
 <Controls of={tableColumnStories.headerContent} />
 
-## Configuring common attributes
+### Hiding
 
-<Description of={tableColumnStories.commonAttributes} />
-<Canvas of={tableColumnStories.commonAttributes} />
-<Controls of={tableColumnStories.commonAttributes} />
+<Description of={tableColumnStories.columnHidden} />
+<Canvas of={tableColumnStories.columnHidden} />
+<Controls of={tableColumnStories.columnHidden} />
 
-## Sorting
+### Sorting
 
 <Description of={tableColumnStories.sorting} />
 <Canvas of={tableColumnStories.sorting} />
 <Controls of={tableColumnStories.sorting} />
 
-## Grouping
+### Grouping
 
 <Description of={tableColumnStories.grouping} />
 <Canvas of={tableColumnStories.grouping} />
 <Controls of={tableColumnStories.grouping} />
 
-## Column Width
+### Column width
 
 <Description of={tableColumnStories.width} />
 <Canvas of={tableColumnStories.width} />