Follow new guidance for incubating components and add sections to Sto…

…rybook (#1292)

# Pull Request

## 🤨 Rationale

Following the guidance agreed upon in #1249, we want to promote the
"Incubating" terminology to describe components that aren't ready for
general use.

## 👩‍💻 Implementation

1. Add sections to Storybook for **Incubating** and **Components**. The
latter was proposed in #1230 so it seems like a good direction for
multiple reasons.
2. Add MDX docs for the Incubating section.
3. Add a link to the corresponding component issue from incubating
stories. Update tooltip to use standard incubating header.
4. Rename WaferMap stories to "Wafer Map" to match other components
which English naming not code naming (and since this change was already
going to cause a Chromatic diff)

## 🧪 Testing

<!---
Detail the testing done to ensure this submission meets requirements. 

Include automated/manual test additions or modifications, testing done
on a local build, private CI run results, and additional testing not
covered by automatic pull request validation.
-->

## ✅ 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.

---------

Co-authored-by: Milan Raj <rajsite@users.noreply.github.com>

change/@ni-nimble-components-581ba49b-79b9-4fea-97b9-6f67054df19c.json

@@ -0,0 +1,7 @@
+{
+  "type": "none",
+  "comment": "Reorganize Storybook to support Incubating components",
+  "packageName": "@ni/nimble-components",
+  "email": "jattasNI@users.noreply.github.com",
+  "dependentChangeType": "none"
+}

packages/nimble-components/.storybook/preview.js

@@ -15,7 +15,13 @@ export const parameters = {
     options: {
         storySort: {
             method: 'alphabetical',
-            order: ['Getting Started']
+            order: [
+                'Getting Started',
+                'Components',
+                'Incubating',
+                'Tokens',
+                'Tests'
+            ]
         }
     },
     controls: {

packages/nimble-components/docs/incubating.mdx

@@ -0,0 +1,19 @@
+import { Story, Meta } from '@storybook/addon-docs';
+
+<Meta title="Incubating/Docs" />
+
+# Incubating components
+
+Components are marked as **Incubating** when they're not yet ready for general use.
+A component could be in this state if any of the following are true:
+
+-   It is still in development.
+-   It is currently experimental or application-specific and hasn't yet been generalized for broader use.
+-   It is missing important features like interaction design, visual design, accessibility, or framework integration.
+
+See the issue linked from each component's documentation for more information about what it's missing.
+
+## Using incubating components
+
+Please talk to the Nimble team before using incubating components in production.
+Note that incubating components may make breaking changes without a corresponding `major` version bump.

packages/nimble-components/src/anchor-button/tests/anchor-button.stories.ts

@@ -31,7 +31,7 @@ interface AnchorButtonArgs {
 }
 
 const metadata: Meta<AnchorButtonArgs> = {
-    title: 'Anchor Button',
+    title: 'Components/Anchor Button',
     tags: ['autodocs'],
     parameters: {
         docs: {

packages/nimble-components/src/anchor-tabs/tests/anchor-tabs.stories.ts

@@ -19,7 +19,7 @@ represents a different URL to navigate to. Use the standard tabs component when
 tab panels hosted on the same page.`;
 
 const metadata: Meta<TabsArgs> = {
-    title: 'Anchor Tabs',
+    title: 'Components/Anchor Tabs',
     tags: ['autodocs'],
     parameters: {
         docs: {

packages/nimble-components/src/anchor/tests/anchor.stories.ts

@@ -19,7 +19,7 @@ interface AnchorArgs {
 }
 
 const metadata: Meta<AnchorArgs> = {
-    title: 'Anchor',
+    title: 'Components/Anchor',
     tags: ['autodocs'],
     parameters: {
         docs: {

packages/nimble-components/src/banner/tests/banner.stories.ts

@@ -41,7 +41,7 @@ should be spaced apart using the \`${bannerGapSize.cssCustomProperty}\` design t
 `;
 
 const metadata: Meta<BannerArgs> = {
-    title: 'Banner',
+    title: 'Components/Banner',
     tags: ['autodocs'],
     decorators: [withActions],
     parameters: {

packages/nimble-components/src/breadcrumb/tests/breadcrumb.stories.ts

@@ -28,7 +28,7 @@ See the [nimble-angular Readme](https://github.com/ni/nimble/blob/main/angular-w
 for information on using this component in Angular with RouterLink directives.`;
 
 const metadata: Meta<BreadcrumbArgs> = {
-    title: 'Breadcrumb',
+    title: 'Components/Breadcrumb',
     tags: ['autodocs'],
     parameters: {
         docs: {

packages/nimble-components/src/button/tests/button.stories.ts

@@ -31,7 +31,7 @@ a dialog is to append "…" (ellipsis) to the button label, e.g., "Save as…".
 If you want a button that triggers navigation to a URL, use the \`nimble-anchor-button\` instead.`;
 
 const metadata: Meta<ButtonArgs> = {
-    title: 'Button',
+    title: 'Components/Button',
     decorators: [withActions],
     parameters: {
         docs: {

packages/nimble-components/src/card-button/tests/card-button.stories.ts

@@ -17,7 +17,7 @@ application. The \`nimble-card-button\` is intended to be larger and more promin
 Note: The styling for the "Color" theme is not complete.`;
 
 const metadata: Meta<CardButtonArgs> = {
-    title: 'Card Button',
+    title: 'Components/Card Button',
     tags: ['autodocs'],
     decorators: [withActions],
     parameters: {

packages/nimble-components/src/checkbox/tests/checkbox.stories.ts

@@ -12,7 +12,7 @@ interface CheckboxArgs {
 }
 
 const metadata: Meta<CheckboxArgs> = {
-    title: 'Checkbox',
+    title: 'Components/Checkbox',
     tags: ['autodocs'],
     decorators: [withActions],
     parameters: {

packages/nimble-components/src/combobox/tests/combobox.stories.ts

@@ -31,7 +31,7 @@ interface OptionArgs {
 }
 
 const metadata: Meta<ComboboxArgs> = {
-    title: 'Combobox',
+    title: 'Components/Combobox',
     tags: ['autodocs'],
     decorators: [withActions],
     parameters: {

packages/nimble-components/src/dialog/tests/dialog.stories.ts

@@ -50,7 +50,7 @@ const content = {
 } as const;
 
 const metadata: Meta<DialogArgs> = {
-    title: 'Dialog',
+    title: 'Components/Dialog',
     tags: ['autodocs'],
     parameters: {
         docs: {

packages/nimble-components/src/drawer/tests/drawer.stories.ts

@@ -114,7 +114,7 @@ ${overrideWarning('Drawer Width', widthDescriptionOverride)}
 `;
 
 const metadata: Meta<DrawerArgs> = {
-    title: 'Drawer',
+    title: 'Components/Drawer',
     tags: ['autodocs'],
     decorators: [withActions],
     parameters: {

packages/nimble-components/src/icon-base/tests/icons.stories.ts

@@ -20,7 +20,7 @@ interface IconArgs {
 }
 
 const metadata: Meta<IconArgs> = {
-    title: 'Icons',
+    title: 'Components/Icons',
     tags: ['autodocs']
 };
 

packages/nimble-components/src/menu-button/tests/menu-button.stories.ts

@@ -32,7 +32,7 @@ This icon will be hidden when \`contentHidden\` is set to \`true\`
 .`;
 
 const metadata: Meta<MenuButtonArgs> = {
-    title: 'Menu Button',
+    title: 'Components/Menu Button',
     tags: ['autodocs'],
     decorators: [withActions],
     parameters: {

packages/nimble-components/src/menu/tests/menu.stories.ts

@@ -39,7 +39,7 @@ The \`nimble-menu\` supports several child elements including \`<header>\`, \`<h
 and will format them and any Nimble icons added as children of \`<nimble-menu-item>\` or \`<nimble-anchor-menu-item>\`.`;
 
 const metadata: Meta<MenuArgs> = {
-    title: 'Menu',
+    title: 'Components/Menu',
     tags: ['autodocs'],
     decorators: [withActions],
     parameters: {

packages/nimble-components/src/number-field/tests/number-field.stories.ts

@@ -18,7 +18,7 @@ interface NumberFieldArgs {
 }
 
 const metadata: Meta<NumberFieldArgs> = {
-    title: 'Number Field',
+    title: 'Components/Number Field',
     tags: ['autodocs'],
     decorators: [withActions],
     parameters: {

packages/nimble-components/src/radio-group/tests/radio-group.stories.ts

@@ -15,7 +15,7 @@ interface RadioGroupArgs {
 }
 
 const metadata: Meta<RadioGroupArgs> = {
-    title: 'Radio Group',
+    title: 'Components/Radio Group',
     tags: ['autodocs'],
     decorators: [withActions],
     parameters: {

packages/nimble-components/src/select/tests/select.stories.ts

@@ -25,7 +25,7 @@ interface OptionArgs {
 }
 
 const metadata: Meta<SelectArgs> = {
-    title: 'Select',
+    title: 'Components/Select',
     tags: ['autodocs'],
     decorators: [withActions],
     parameters: {

packages/nimble-components/src/spinner/tests/spinner.stories.ts

@@ -29,7 +29,7 @@ const overviewText = '<p>The `nimble-spinner` is an animating indicator that can
     + '<p>See the `size` argument details for information on customizing the spinner size.</p>';
 
 const metadata: Meta<SpinnerArgs> = {
-    title: 'Spinner',
+    title: 'Components/Spinner',
     tags: ['autodocs'],
     parameters: {
         docs: {

packages/nimble-components/src/switch/tests/switch.stories.ts

@@ -20,7 +20,7 @@ be checked or not checked and can optionally also allow for a partially checked
 pressed or not pressed and can optionally allow for a partially pressed state.`;
 
 const metadata: Meta<SwitchArgs> = {
-    title: 'Switch',
+    title: 'Components/Switch',
     tags: ['autodocs'],
     decorators: [withActions],
     parameters: {

packages/nimble-components/src/table-column/anchor/tests/table-column-anchor.stories.ts

@@ -3,7 +3,7 @@ import type { Meta, StoryObj } from '@storybook/html';
 import { withActions } from '@storybook/addon-actions/decorator';
 import {
     createUserSelectedThemeStory,
-    usageWarning
+    incubatingWarning
 } from '../../../utilities/tests/storybook';
 import { tableTag } from '../../../table';
 import { tableColumnAnchorTag } from '..';
@@ -21,7 +21,7 @@ See the **Table** page for information about configuring the table itself and th
 information about common column configuration.`;
 
 const metadata: Meta<SharedTableArgs> = {
-    title: 'Table Column Types',
+    title: 'Incubating/Table Column Types',
     decorators: [withActions],
     tags: ['autodocs'],
     parameters: {
@@ -106,7 +106,7 @@ export const anchorColumn: StoryObj<AnchorColumnTableArgs> = {
     },
     // prettier-ignore
     render: createUserSelectedThemeStory(html<AnchorColumnTableArgs>`
-        ${usageWarning('table')}
+        ${incubatingWarning({ componentName: 'table', statusLink: 'https://github.com/orgs/ni/projects/7/views/21' })}
         <${tableTag}
             ${ref('tableRef')}
             data-unused="${x => x.updateData(x)}"

packages/nimble-components/src/table-column/base/tests/table-column.stories.ts

@@ -3,7 +3,7 @@ import type { Meta, StoryObj } from '@storybook/html';
 import { withActions } from '@storybook/addon-actions/decorator';
 import {
     createUserSelectedThemeStory,
-    usageWarning
+    incubatingWarning
 } from '../../../utilities/tests/storybook';
 import {
     ExampleColumnFractionalWidthType,
@@ -81,7 +81,7 @@ See **Table** for information about configuring the table itself and **Table Col
 information about specific types of column.`;
 
 const metadata: Meta<SharedTableArgs> = {
-    title: 'Table Column Configuration',
+    title: 'Incubating/Table Column Configuration',
     decorators: [withActions],
     parameters: {
         docs: {
@@ -95,7 +95,7 @@ const metadata: Meta<SharedTableArgs> = {
     },
     // prettier-ignore
     render: createUserSelectedThemeStory(html<SharedTableArgs>`
-    ${usageWarning('table')}
+    ${incubatingWarning({ componentName: 'table', statusLink: 'https://github.com/orgs/ni/projects/7/views/21' })}
     <${tableTag}
         ${ref('tableRef')}
         data-unused="${x => x.updateData(x)}"
@@ -169,7 +169,7 @@ export const columnOrder: StoryObj<ColumnOrderTableArgs> = {
     },
     // prettier-ignore
     render: createUserSelectedThemeStory(html<ColumnOrderTableArgs>`
-        ${usageWarning('table')}
+        ${incubatingWarning({ componentName: 'table', statusLink: 'https://github.com/orgs/ni/projects/7/views/21' })}
         <${tableTag}
             ${ref('tableRef')}
             data-unused="${x => x.updateData(x)}"
@@ -242,7 +242,7 @@ export const headerContent: StoryObj<HeaderContentTableArgs> = {
     },
     // prettier-ignore
     render: createUserSelectedThemeStory(html<HeaderContentTableArgs>`
-        ${usageWarning('table')}
+        ${incubatingWarning({ componentName: 'table', statusLink: 'https://github.com/orgs/ni/projects/7/views/21' })}
         <${tableTag}
             ${ref('tableRef')}
             data-unused="${x => x.updateData(x)}"
@@ -301,7 +301,7 @@ export const commonAttributes: StoryObj<CommonAttributesTableArgs> = {
     },
     // prettier-ignore
     render: createUserSelectedThemeStory(html<CommonAttributesTableArgs>`
-        ${usageWarning('table')}
+        ${incubatingWarning({ componentName: 'table', statusLink: 'https://github.com/orgs/ni/projects/7/views/21' })}
         <${tableTag}
             ${ref('tableRef')}
             data-unused="${x => x.updateData(x)}"
@@ -417,7 +417,7 @@ export const sorting: StoryObj<SortingTableArgs> = {
     },
     // prettier-ignore
     render: createUserSelectedThemeStory(html<SortingTableArgs>`
-        ${usageWarning('table')}
+        ${incubatingWarning({ componentName: 'table', statusLink: 'https://github.com/orgs/ni/projects/7/views/21' })}
         <${tableTag}
             ${ref('tableRef')}
             data-unused="${x => x.updateData(x)}"
@@ -604,7 +604,7 @@ export const grouping: StoryObj<GroupingTableArgs> = {
     },
     // prettier-ignore
     render: createUserSelectedThemeStory(html<GroupingTableArgs>`
-        ${usageWarning('table')}
+        ${incubatingWarning({ componentName: 'table', statusLink: 'https://github.com/orgs/ni/projects/7/views/21' })}
         <${tableTag}
             ${ref('tableRef')}
             data-unused="${x => x.updateData(x)}"
@@ -728,7 +728,7 @@ export const fractionalWidthColumn: StoryObj<ColumnWidthTableArgs> = {
     },
     // prettier-ignore
     render: createUserSelectedThemeStory(html<ColumnWidthTableArgs>`
-        ${usageWarning('table')}
+        ${incubatingWarning({ componentName: 'table', statusLink: 'https://github.com/orgs/ni/projects/7/views/21' })}
         <${tableTag}
             ${ref('tableRef')}
             data-unused="${x => x.updateData(x)}"

packages/nimble-components/src/table-column/text/tests/table-column-text.stories.ts

@@ -3,7 +3,7 @@ import type { Meta, StoryObj } from '@storybook/html';
 import { withActions } from '@storybook/addon-actions/decorator';
 import {
     createUserSelectedThemeStory,
-    usageWarning
+    incubatingWarning
 } from '../../../utilities/tests/storybook';
 import { tableTag } from '../../../table';
 import { tableColumnTextTag } from '..';
@@ -45,7 +45,7 @@ See the **Table** page for information about configuring the table itself and th
 information about common column configuration.`;
 
 const metadata: Meta<SharedTableArgs> = {
-    title: 'Table Column Types',
+    title: 'Incubating/Table Column Types',
     decorators: [withActions],
     parameters: {
         docs: {
@@ -92,7 +92,10 @@ export const textColumn: StoryObj<TextColumnTableArgs> = {
     },
     // prettier-ignore
     render: createUserSelectedThemeStory(html<TextColumnTableArgs>`
-        ${usageWarning('table')}
+        ${incubatingWarning({
+        componentName: 'table',
+        statusLink: 'https://github.com/orgs/ni/projects/7/views/21'
+    })}
         <${tableTag}
             ${ref('tableRef')}
             data-unused="${x => x.updateData(x)}"

packages/nimble-components/src/table/tests/table.stories.ts

@@ -3,7 +3,7 @@ import { withActions } from '@storybook/addon-actions/decorator';
 import type { Meta, StoryObj } from '@storybook/html';
 import {
     createUserSelectedThemeStory,
-    usageWarning
+    incubatingWarning
 } from '../../utilities/tests/storybook';
 import { ExampleDataType } from './types';
 import { Table, tableTag } from '..';
@@ -120,7 +120,7 @@ If a record does not exist in the table's data, it will not be selected. If mult
 mode is \`single\`, only the first record that exists in the table's data will become selected.`;
 
 const metadata: Meta<TableArgs> = {
-    title: 'Table',
+    title: 'Incubating/Table',
     tags: ['autodocs'],
     decorators: [withActions],
     parameters: {
@@ -140,7 +140,7 @@ const metadata: Meta<TableArgs> = {
     },
     // prettier-ignore
     render: createUserSelectedThemeStory(html<TableArgs>`
-        ${usageWarning('table')}
+        ${incubatingWarning({ componentName: 'table', statusLink: 'https://github.com/orgs/ni/projects/7/views/21' })}
         <${tableTag}
             ${ref('tableRef')}
             selection-mode="${x => TableRowSelectionMode[x.selectionMode]}"

packages/nimble-components/src/tabs/tests/tabs.stories.ts

@@ -25,7 +25,7 @@ horizontal scrolling. Content may be any height; the tab panel will display a ve
 If you want a sequence of tabs that navigate to different URLs, use the Anchor Tabs component instead.`;
 
 const metadata: Meta<TabsArgs> = {
-    title: 'Tabs',
+    title: 'Components/Tabs',
     tags: ['autodocs'],
     decorators: [withActions],
     parameters: {

packages/nimble-components/src/text-area/tests/text-area.stories.ts

@@ -29,7 +29,7 @@ If you configure your text area to be resizable (with the \`resize\` attribute)
 `;
 
 const metadata: Meta<TextAreaArgs> = {
-    title: 'Text Area',
+    title: 'Components/Text Area',
     tags: ['autodocs'],
     decorators: [withActions],
     parameters: {