API docs for additional components (#2135)

# Pull Request

## 🤨 Rationale

Ongoing efforts towards #824. This PR builds on #2132 and covers these
components:
- tree
- toolbar
- icon
- dialog
- drawer
- spinner
- breadcrumb
- theme provider

## 👩‍💻 Implementation

Mostly following established patterns. Interesting bits:
- moved a `nimble-components/src/dialog/tests/types.ts` to the
`storybook` package since it iss only used by storybook
- collapsed 2 controls into 1 in the dialog story
- added a new table section called Styles for controls that impact CSS
- removed "allowNavigation" capability from breadcrumb story because it
was just showing native event behavior (i.e. how to cancel an event) and
didn't have any documentation
- moved "Target Configuration" section under the relevant component API
section for several components.

## 🧪 Testing

Storybook inspection

## ✅ Checklist

<!--- Review the list and put an x in the boxes that apply or ~~strike
through~~ around items that don't (along with an explanation). -->

- [x] I have updated the project documentation to reflect my changes or
determined no changes are needed.

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-a6e4-21bf71c6efe6
+// Update the GUID on this line to trigger a turbosnap full rebuild: 354fdf0e-bdb4-4dd9-a6e5-21bf71c6efe6
 // See https://www.chromatic.com/docs/turbosnap/#full-rebuilds

packages/storybook/src/nimble/anchor-button/anchor-button.mdx

@@ -29,6 +29,10 @@ If you want a button that triggers an action or event, use the <Tag name={button
 
 <ComponentApisLink />
 
+### Target Configuration
+
+<TargetDocs />
+
 ## Styling
 
 <StylingDocs components={{ Button: anchorButtonTag }} />
@@ -37,10 +41,6 @@ If you want a button that triggers an action or event, use the <Tag name={button
 
 {/* ## Examples */}
 
-## Target Configuration
-
-<TargetDocs />
-
 ## Accessibility
 
 <ContentHiddenDocs buttonElement="nimble-anchor-button" />

packages/storybook/src/nimble/anchor-tabs/anchor-tabs.mdx

@@ -31,6 +31,10 @@ Use the <Tag name={anchorTabTag} /> child element to add new tabs to the <Tag na
 <Canvas of={anchorTabsStories.anchorTab} />
 <Controls of={anchorTabsStories.anchorTab} />
 
+#### Target Configuration
+
+<TargetDocs />
+
 ### Tabs Toolbar
 
 Use the <Tag name={tabsToolbarTag} /> child element to add a toolbar next to the tabs.
@@ -44,10 +48,6 @@ Use the <Tag name={tabsToolbarTag} /> child element to add a toolbar next to the
 
 {/* ## Examples */}
 
-## Target Configuration
-
-<TargetDocs />
-
 ## Angular Usage
 
 In an Angular application, it is common to integrate with the router by setting `nimbleRouterLink` (rather than `href`)

packages/storybook/src/nimble/anchor/anchor.mdx

@@ -16,6 +16,10 @@ Per [W3C](https://www.w3.org/WAI/ARIA/apg/patterns/link/), an anchor/link widget
 
 <ComponentApisLink />
 
+### Target Configuration
+
+<TargetDocs />
+
 {/* ## Styling */}
 
 {/* ## Usage */}
@@ -25,7 +29,3 @@ Per [W3C](https://www.w3.org/WAI/ARIA/apg/patterns/link/), an anchor/link widget
 {/* ## Accessibility */}
 
 {/* ## Resources */}
-
-## Target Configuration
-
-<TargetDocs />

packages/storybook/src/nimble/banner/banner.mdx

@@ -1,5 +1,6 @@
 import { Canvas, Meta, Controls, Title } from '@storybook/blocks';
 import { NimbleBanner } from './banner.react';
+import ComponentApisLink from '../../docs/component-apis-link.mdx';
 import { bannerGapSize } from '../../../../nimble-components/src/theme-provider/design-tokens';
 import * as bannerStories from './banner.stories';
 
@@ -14,7 +15,11 @@ location. Multiple banners may be stacked vertically in order of age, with the n
 should be spaced apart using the <code>{bannerGapSize.cssCustomProperty}</code> design token.
 
 <Canvas of={bannerStories._banner} />
+
+## API
+
 <Controls of={bannerStories._banner} />
+<ComponentApisLink />
 
 {/* ## Styling */}
 

packages/storybook/src/nimble/breadcrumb/breadcrumb.mdx

@@ -1,6 +1,8 @@
 import { Canvas, Meta, Stories, Controls, Title } from '@storybook/blocks';
 import { NimbleBreadcrumb } from './breadcrumb.react';
 import * as breadcrumbStories from './breadcrumb.stories';
+import ComponentApisLink from '../../docs/component-apis-link.mdx';
+import TargetDocs from '../patterns/anchor/target-docs.mdx';
 
 <Meta of={breadcrumbStories} />
 <Title of={breadcrumbStories} />
@@ -12,8 +14,20 @@ See the [nimble-angular Readme](https://github.com/ni/nimble/blob/main/packages/
 for information on using this component in Angular with RouterLink directives.
 
 <Canvas of={breadcrumbStories._standardBreadcrumb} />
+
+## API
+
 <Controls of={breadcrumbStories._standardBreadcrumb} />
-<Stories of={breadcrumbStories} />
+<ComponentApisLink />
+
+### Breadcrumb Item
+
+<Canvas of={breadcrumbStories.breadcrumbItem} />
+<Controls of={breadcrumbStories.breadcrumbItem} />
+
+#### Target Configuration
+
+<TargetDocs />
 
 {/* ## Styling */}
 

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

@@ -1,35 +1,41 @@
-import type { Meta, StoryObj } from '@storybook/html';
+import type { HtmlRenderer, Meta, StoryObj } from '@storybook/html';
+import { withActions } from '@storybook/addon-actions/decorator';
 import { html, repeat } from '@microsoft/fast-element';
 import { breadcrumbItemTag } from '../../../../nimble-components/src/breadcrumb-item';
 import { breadcrumbTag } from '../../../../nimble-components/src/breadcrumb';
 import { BreadcrumbAppearance } from '../../../../nimble-components/src/breadcrumb/types';
-import { createUserSelectedThemeStory } from '../../utilities/storybook';
+import { apiCategory, appearanceDescription, createUserSelectedThemeStory } from '../../utilities/storybook';
+import { hrefDescription } from '../patterns/anchor/anchor-docs';
 
 interface BreadcrumbArgs {
     options: ItemArgs[];
     appearance: keyof typeof BreadcrumbAppearance;
-    allowNavigation: boolean;
 }
 
 interface ItemArgs {
     href?: string;
-    target?: string;
     label: string;
 }
 
 interface BreadcrumbItemArgs extends ItemArgs {
-    allowNavigation: boolean;
+    click: undefined;
 }
 
 const metadata: Meta<BreadcrumbArgs> = {
     title: 'Components/Breadcrumb',
+    decorators: [withActions<HtmlRenderer>],
     parameters: {
-        actions: {}
+        actions: {
+            handles: ['click']
+        }
     }
 };
 
 export default metadata;
 
+const defaultHrefDescription = hrefDescription({ componentName: 'breadcrumb item', includeDisable: false });
+const itemHrefDescription = `${defaultHrefDescription} If the last breadcrumb item represents the current page it should have no \`href\` set.`;
+
 export const _standardBreadcrumb: StoryObj<BreadcrumbArgs> = {
     // prettier-ignore
     render: createUserSelectedThemeStory(html`
@@ -39,8 +45,6 @@ export const _standardBreadcrumb: StoryObj<BreadcrumbArgs> = {
             ${repeat(x => x.options, html<ItemArgs, BreadcrumbArgs>`
                 <${breadcrumbItemTag}
                     href="${x => x.href}"
-                    target="${x => x.target}"
-                    @click="${(_x, c) => c.parent.allowNavigation}"
                 >
                     ${x => x.label}
                 </${breadcrumbItemTag}>
@@ -51,14 +55,18 @@ export const _standardBreadcrumb: StoryObj<BreadcrumbArgs> = {
     name: 'Standard Breadcrumb',
     argTypes: {
         options: {
+            name: 'default',
             description:
-                'Nest one or more `<nimble-breadcrumb-item />`s inside `<nimble-breadcrumb />`. Each can optionally set `href`, `target`, etc. '
-                + 'With a standard breadcrumb containing multiple items, the last breadcrumb represents the current page (with no `href` specified, '
-                + 'rendering with a bold font).'
+                `The \`${breadcrumbItemTag}\` elements that populate this breadcrumb. 
+
+With a standard breadcrumb containing multiple items, the last breadcrumb represents the current page.`,
+            table: { category: apiCategory.slots }
         },
         appearance: {
             options: Object.keys(BreadcrumbAppearance),
-            control: { type: 'radio' }
+            description: appearanceDescription({ componentName: 'breadcrumb' }),
+            control: { type: 'radio' },
+            table: { category: apiCategory.attributes }
         }
     },
     args: {
@@ -75,8 +83,7 @@ export const _standardBreadcrumb: StoryObj<BreadcrumbArgs> = {
                 label: 'Current (No Link)'
             }
         ],
-        appearance: 'default',
-        allowNavigation: false
+        appearance: 'default'
     }
 };
 
@@ -85,28 +92,30 @@ export const breadcrumbItem: StoryObj<BreadcrumbItemArgs> = {
         <${breadcrumbTag}>
             <${breadcrumbItemTag}
                 href="${x => x.href}"
-                target="${x => x.target}"
-                @click="${x => x.allowNavigation}"
             >
-                Breadcrumb Item
+                ${x => x.label}
             </${breadcrumbItemTag}>
         </${breadcrumbTag}>
     `),
     argTypes: {
         href: {
-            description:
-                '(Optional) The URL that this breadcrumb item/ link points to. Generally, the last breadcrumb item '
-                + 'representing the current page has no `href` set.'
+            description: itemHrefDescription,
+            table: { category: apiCategory.attributes }
         },
-        target: {
-            description:
-                '(Optional) Where to display the linked URL (destination browsing context): `_self`, `_blank`, etc.',
-            type: 'string'
+        label: {
+            name: 'default',
+            description: 'The text content of the breadcrumb item.',
+            type: 'string',
+            table: { category: apiCategory.slots }
+        },
+        click: {
+            description: 'Event emitted when the user activates the breadcrumb item link, for example by clicking on it or pressing Enter while focused.',
+            control: false,
+            table: { category: apiCategory.events }
         }
     },
     args: {
         href: 'http://www.ni.com',
         label: 'Breadcrumb Item',
-        allowNavigation: false
     }
 };

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

@@ -74,7 +74,7 @@ const metadata: Meta<ButtonArgs> = {
         },
         click: {
             description:
-                'Fires when the button is activated by either keyboard or mouse.',
+                'Event emitted when the button is activated by either keyboard or mouse.',
             table: { category: apiCategory.events },
             control: false
         }

packages/storybook/src/nimble/card-button/card-button.stories.ts

@@ -72,7 +72,7 @@ const metadata: Meta<CardButtonArgs> = {
         },
         click: {
             description:
-                'Fires when the card button is activated by either keyboard or mouse.',
+                'Event emitted when the card button is activated by either keyboard or mouse.',
             table: { category: apiCategory.events },
             control: false
         }

packages/storybook/src/nimble/dialog/dialog.mdx

@@ -1,15 +1,18 @@
 import { Canvas, Meta, Controls, Title } from '@storybook/blocks';
 import * as dialogStories from './dialog.stories';
+import ComponentApisLink from '../../docs/component-apis-link.mdx';
 
 <Meta of={dialogStories} />
 <Title of={dialogStories} />
 
 A modal dialog that appears centered on top of all other windows, blocking other interaction until dismissed.
 
-By default, the first focusable control gets focus when the dialog is opened. To focus a specific element instead, set the `autofocus` attribute on that element.
-
 <Canvas of={dialogStories.dialog} />
+
+## API
+
 <Controls of={dialogStories.dialog} />
+<ComponentApisLink />
 
 ## Styling
 
@@ -38,7 +41,9 @@ nimble-dialog::part(control) {
 }
 ```
 
-{/* ## Usage */}
+## Usage
+
+By default, the first focusable control gets focus when the dialog is opened. To focus a specific element instead, set the `autofocus` attribute on that element.
 
 {/* ## Examples */}