Improve API docs for menu button component (#2027)

# Pull Request ## 🤨 Rationale As part of #824 we want to improve the accuracy and comprehensiveness of our storybook API documentation. ## 👩‍💻 Implementation Apply the following patterns to the menu button docs: 1. create sections in the args table for attributes, slots, and events. (We'd also add methods for components that expose interesting ones) 2. Ensure the title and description are accurate for each member 3. link to shared docs about component APIs. Other minor bug fixes: 1. hide the "patterns" page from public storybook 2. hide text from ✅ icon mapping in component status table ### Possible follow up work 1. update doc templates and the docs for other existing components similarly 1. more detailed API overview docs - explanation of event patterns in web components and how they map to frameworks - using forms instead of change events 1. see if we can remove the type annotation from control descriptions 2. [wait for further feedback] more curated examples and highlight most important APIs for each component 1. [out of scope] I wish I could hide the Default column since we don't bother populating it but that doesn't seem to be possible storybookjs/storybook#15780 ## 🧪 Testing Manual storybook interaction ## ✅ Checklist  - [x] I have updated the project documentation to reflect my changes or determined no changes are needed.
ni · Apr 24, 2024 · 1b7dd15 · 1b7dd15
1 parent 97d92f6
commit 1b7dd15
Show file tree

Hide file tree

Showing 10 changed files with 196 additions and 29 deletions.
diff --git a/change/@ni-nimble-components-7b65608b-da35-44f3-bff4-d787fac390c5.json b/change/@ni-nimble-components-7b65608b-da35-44f3-bff4-d787fac390c5.json
@@ -0,0 +1,7 @@
+{
+  "type": "none",
+  "comment": "Storybook documentation improvements",
+  "packageName": "@ni/nimble-components",
+  "email": "[email protected]",
+  "dependentChangeType": "none"
+}
diff --git a/packages/nimble-components/.storybook/manager.js b/packages/nimble-components/.storybook/manager.js
@@ -7,9 +7,10 @@ addons.setConfig({
         filters: {
             patterns: item => {
                 const isPublicSite = window.location.hostname === 'nimble.ni.dev';
-                const isItemInternal = item.title.startsWith('Tests/')
-                    || item.title.startsWith('Internal/')
-                    || item.title.startsWith('Patterns/');
+                const title = item.title.toLowerCase();
+                const isItemInternal = title.startsWith('tests/')
+                    || title.startsWith('internal/')
+                    || title.startsWith('patterns/');
                 const shouldHideInSidebar = isPublicSite && isItemInternal;
                 return !shouldHideInSidebar;
             }

diff --git a/packages/nimble-components/.storybook/preview.js b/packages/nimble-components/.storybook/preview.js
@@ -47,6 +47,7 @@ export const parameters = {
         expanded: true
     },
     docs: {
+        controls: { sort: 'alpha' },
         source: {
             transform: transformSource
         },

diff --git a/packages/nimble-components/src/menu-button/tests/menu-button.mdx b/packages/nimble-components/src/menu-button/tests/menu-button.mdx
@@ -1,6 +1,7 @@
 import { Controls, Canvas, Meta, Title } from '@storybook/blocks';
 import ContentHiddenDocs from '../../patterns/button/tests/content-hidden-docs.mdx';
 import StylingDocs from '../../patterns/button/tests/styling-docs.mdx';
+import ComponentApisLink from '../../patterns/docs/component-apis-link.mdx';
 import { menuButtonTag } from '..';
 import * as menuButtonStories from './menu-button.stories';
 
@@ -11,8 +12,13 @@ Per [W3C](https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/), a menu button
 often styled as a typical push button with a downward pointing arrow or triangle to hint that activating the button will display a menu.
 
 <Canvas of={menuButtonStories.outlineButton} />
+
+## API
+
 <Controls of={menuButtonStories.outlineButton} />
 
+<ComponentApisLink />
+
 <StylingDocs components={{ Button: menuButtonTag }} />
 
 {/* ## Usage */}

diff --git a/packages/nimble-components/src/menu-button/tests/menu-button.stories.ts b/packages/nimble-components/src/menu-button/tests/menu-button.stories.ts
@@ -2,6 +2,7 @@ import { html, when } from '@microsoft/fast-element';
 import { withActions } from '@storybook/addon-actions/decorator';
 import type { HtmlRenderer, Meta, StoryObj } from '@storybook/html';
 import {
+    apiCategory,
     createUserSelectedThemeStory,
     disableStorybookZoomTransform
 } from '../../utilities/tests/storybook';
@@ -17,26 +18,27 @@ import { menuTag } from '../../menu';
 import { menuItemTag } from '../../menu-item';
 import {
     appearanceDescription,
-    appearanceVariantDescription
+    appearanceVariantDescription,
+    contentHiddenDescription,
+    endIconDescription,
+    iconDescription
 } from '../../patterns/button/tests/doc-strings';
 
 interface MenuButtonArgs {
     label: string;
+    icon: boolean;
+    endIcon: boolean;
+    menu: () => void;
     appearance: keyof typeof ButtonAppearance;
     appearanceVariant: keyof typeof ButtonAppearanceVariant;
     open: boolean;
     disabled: boolean;
-    icon: boolean;
     contentHidden: boolean;
-    endIcon: boolean;
     menuPosition: string;
+    toggle: () => void;
+    beforetoggle: () => void;
 }
 
-const endIconDescription = `When including an icon after the text content, set \`slot="end"\` on the icon to ensure proper styling.
-
-This icon will be hidden when \`contentHidden\` is set to \`true\`
-.`;
-
 const metadata: Meta<MenuButtonArgs> = {
     title: 'Components/Menu Button',
     decorators: [withActions<HtmlRenderer>],
@@ -49,27 +51,73 @@ const metadata: Meta<MenuButtonArgs> = {
         }
     },
     argTypes: {
+        label: {
+            name: 'default',
+            description:
+                'The text content of the button. This will be hidden when `content-hidden` is set but should always be provided; see the `Accessibility` section for more info.',
+            table: { category: apiCategory.slots }
+        },
+        icon: {
+            name: 'start',
+            description: iconDescription,
+            table: { category: apiCategory.slots }
+        },
+        endIcon: {
+            name: 'end',
+            description: endIconDescription,
+            table: { category: apiCategory.slots }
+        },
+        menu: {
+            description:
+                'The [nimble-menu](./?path=/docs/components-menu--docs) to be displayed when the button is toggled.',
+            table: { category: apiCategory.slots },
+            control: false
+        },
         appearance: {
             options: Object.keys(ButtonAppearance),
             control: { type: 'radio' },
-            description: appearanceDescription
+            description: appearanceDescription,
+            table: { category: apiCategory.attributes }
         },
         appearanceVariant: {
             name: 'appearance-variant',
             options: Object.keys(ButtonAppearanceVariant),
             control: { type: 'radio' },
-            description: appearanceVariantDescription
+            description: appearanceVariantDescription,
+            table: { category: apiCategory.attributes }
         },
-        icon: {
-            description:
-                'When including an icon, set `slot="start"` on the icon to ensure proper styling.'
+        open: {
+            control: { type: 'boolean' },
+            description: 'Opens the menu.',
+            table: { category: apiCategory.attributes }
         },
-        endIcon: {
-            description: endIconDescription
+        disabled: {
+            control: { type: 'boolean' },
+            description: 'Disables the button.',
+            table: { category: apiCategory.attributes }
+        },
+        contentHidden: {
+            name: 'content-hidden',
+            description: contentHiddenDescription,
+            table: { category: apiCategory.attributes }
         },
         menuPosition: {
+            name: 'menu-position',
+            description: 'The position of the menu relative to the button.',
             options: Object.values(MenuButtonPosition),
-            control: { type: 'radio' }
+            control: { type: 'radio' },
+            table: { category: apiCategory.attributes }
+        },
+        toggle: {
+            description: 'Fires after the menu button is toggled.',
+            table: { category: apiCategory.events },
+            control: false
+        },
+        beforetoggle: {
+            description:
+                'Fires before the menu button is toggled. This can be used to populate the menu before it is opened.',
+            table: { category: apiCategory.events },
+            control: false
         }
     },
     // prettier-ignore
@@ -105,8 +153,6 @@ const metadata: Meta<MenuButtonArgs> = {
         </${menuButtonTag}>
     `),
     args: {
-        label: 'Menu Button',
-        appearance: 'outline',
         appearanceVariant: 'default',
         open: false,
         disabled: false,
@@ -125,12 +171,21 @@ export const outlineButton: StoryObj<MenuButtonArgs> = {
         appearance: ButtonAppearance.outline
     }
 };
+
 export const ghostButton: StoryObj<MenuButtonArgs> = {
-    args: { label: 'Ghost Menu Button', appearance: ButtonAppearance.ghost }
+    args: {
+        label: 'Ghost Menu Button',
+        appearance: ButtonAppearance.ghost
+    }
 };
+
 export const blockButton: StoryObj<MenuButtonArgs> = {
-    args: { label: 'Block Menu Button', appearance: ButtonAppearance.block }
+    args: {
+        label: 'Block Menu Button',
+        appearance: ButtonAppearance.block
+    }
 };
+
 export const iconButton: StoryObj<MenuButtonArgs> = {
     args: {
         label: 'Icon Menu Button',

diff --git a/packages/nimble-components/src/patterns/button/tests/doc-strings.ts b/packages/nimble-components/src/patterns/button/tests/doc-strings.ts
@@ -4,7 +4,7 @@ export const appearanceVariantDescription = 'This attribute has no effect on but
 
 export const contentHiddenDescription = 'When set, this attribute hides the text and end icon, leaving only the start icon visible.';
 
-export const iconDescription = `When including an icon, set \`slot="start"\` on the icon to ensure proper styling.
+export const iconDescription = `Set \`slot="start"\` to include an icon before the text content (or instead of the content when \`content-hidden\` is set).
 
 <details>
     <summary>Icon Usage</summary>
@@ -29,7 +29,5 @@ export const iconDescription = `When including an icon, set \`slot="start"\` on
     </ul>
 </details>`;
 
-export const endIconDescription = `When including an icon after the text content, set \`slot="end"\` on the icon to ensure proper styling.
-
-This icon will be hidden when \`contentHidden\` is set to \`true\`
-.`;
+// 'Set `slot="end"` to include an icon after the text content.'
+export const endIconDescription = 'Set `slot="end"` to include an icon after the text content. This icon will be hidden when `content-hidden` is set to `true`.';
diff --git a/packages/nimble-components/src/patterns/docs/component-apis-link.mdx b/packages/nimble-components/src/patterns/docs/component-apis-link.mdx
@@ -0,0 +1 @@
+For more information about the structure of Nimble APIs, see [Component APIs](?path=/docs/component-apis--docs).
diff --git a/packages/nimble-components/src/tests/component-apis.mdx b/packages/nimble-components/src/tests/component-apis.mdx
@@ -0,0 +1,91 @@
+import { Meta } from '@storybook/addon-docs';
+
+<Meta title="Component APIs" />
+
+# Component APIs
+
+This page describes common patterns for programmatically configuring Nimble components.
+
+## Elements
+
+Nimble components are [web component custom elements](https://developer.mozilla.org/en-US/docs/Web/API/Web_components).
+Applications can use custom elements directly or use framework-specific APIs for [Angular](https://angular.io/)
+or [Blazor](https://dotnet.microsoft.com/en-us/apps/aspnet/web-apps/blazor).
+
+Components follow a standard naming convention:
+
+| Name                   | Purpose                                                   | Example                 |
+| ---------------------- | --------------------------------------------------------- | ----------------------- |
+| Custom element name    | Add the component to HTML                                 | `nimble-button`         |
+| JavaScript class name  | Interact with the component from JavaScript or TypeScript | `NimbleButton`          |
+| Angular module name    | Import the component in Angular                           | `NimbleButtonModule`    |
+| Angular directive name | Interact with the component from Angular                  | `NimbleButtonDirective` |
+| Blazor component name  | Use the component in Blazor template or C# class          | `NimbleButton`          |
+
+## Slots
+
+Component content can be configured by inserting it as a child of the component via
+[slots](https://developer.mozilla.org/en-US/docs/Web/API/Element/slot).
+
+Content can be inserted in the default slot:
+
+```html
+<nimble-button>Click me</nimble-button>
+```
+
+Or in a named slot:
+
+```html
+<nimble-button>
+    <nimble-icon-key slot="start"></nimble-icon-key>
+    Click me
+</nimble-button>
+```
+
+## Attributes and Properties
+
+Configure components from HTML using attributes or from code using properties. Attributes and properties typically
+correspond to each other one-to-one; Nimble documentation refers to the attribute name.
+
+### Attributes
+
+Attributes have `kebab-case` names in HTML and Angular templates.
+
+```html
+<nimble-button appearance="outline">...</nimble-button>
+```
+
+### Boolean attributes
+
+Boolean attributes don't need a value; they are `true` when present and `false` when absent.
+
+```html
+<nimble-button content-hidden>...</nimble-button>
+```
+
+### Properties
+
+Properties have `camelCase` names in JavaScript, TypeScript, and Angular.
+
+```ts
+const button = document.querySelector('nimble-button');
+button.appearance = ButtonAppearance.outline;
+```
+
+### Blazor
+
+In Blazor, properties and attributes have `PascalCase` names. For values that are enumerations of strings, the type is a C# enum.
+
+```
+<NimbleButton Appearance="ButtonAppearance.Outline">...</NimbleButton>
+```
+
+## Methods
+
+Some components expose methods for providing complex data or invoking operations. Methods are only available in code, not in HTML.
+
+## Events
+
+Components raise events to notify the application of changes or user interactions.
+Prefer to use documented Nimble events when available rather than native DOM events as they cover more user interactions
+(for example, `change` will be raised for both click and keyboard interactions).
diff --git a/packages/nimble-components/src/tests/component-status.stories.ts b/packages/nimble-components/src/tests/component-status.stories.ts
@@ -539,7 +539,7 @@ const components = [
 ] as const;
 
 const iconMappings = html`
-    <${mappingIconTag} key="${ComponentFrameworkStatus.ready}" text="Ready" icon="${iconCheckTag}" severity="success"></${mappingIconTag}>
+    <${mappingIconTag} key="${ComponentFrameworkStatus.ready}" text="Ready" icon="${iconCheckTag}" severity="success" text-hidden></${mappingIconTag}>
     <${mappingIconTag} key="${ComponentFrameworkStatus.incubating}" text="Incubating" icon="${iconTriangleTag}" severity="warning"></${mappingIconTag}>
     <${mappingIconTag} key="${ComponentFrameworkStatus.doesNotExist}" text="Does not exist" icon="${iconXmarkTag}" severity="error"></${mappingIconTag}>
 `;

diff --git a/packages/nimble-components/src/utilities/tests/storybook.ts b/packages/nimble-components/src/utilities/tests/storybook.ts
@@ -161,3 +161,10 @@ export const disableStorybookZoomTransform = `
     }
 </style>
 `;
+
+export const apiCategory = {
+    attributes: 'Attributes',
+    events: 'Events',
+    methods: 'Methods',
+    slots: 'Slots'
+} as const;