From 71e848b3a9dc725478752c26271fbe2becd7c44a Mon Sep 17 00:00:00 2001 From: Jesse Attas Date: Fri, 17 May 2024 15:21:31 -0500 Subject: [PATCH] Improve API docs for buttons and improve overall doc consistency (#2117) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit # Pull Request ## ๐Ÿคจ Rationale As part of #824 we want to improve the accuracy and comprehensiveness of our storybook API documentation. ## ๐Ÿ‘ฉโ€๐Ÿ’ป Implementation 1. Update `button`, `toggle-button`, and `card-button` to follow new API doc pattern. (I'll do `anchor-button` along with other anchors). 2. Add and tweak wording on shared documentation strings and utilities 3. Tweak organization of MDX headings in all stories to put Appearance and Sizing under Styling 4. Add CONTRIBUTING guidance about referring to sections within docs (in previous PRs we gave up on trying to link to sections and started using bolded text instead). ## ๐Ÿงช Testing Local storybook exploration ## โœ… Checklist - [ ] I have updated the project documentation to reflect my changes or determined no changes are needed. --------- Co-authored-by: Milan Raj --- packages/storybook/CONTRIBUTING.md | 12 +++-- .../nimble/anchor-button/anchor-button.mdx | 2 + .../anchor-button/anchor-button.stories.ts | 4 +- .../src/nimble/anchor-tabs/anchor-tabs.mdx | 4 +- .../storybook/src/nimble/anchor/anchor.mdx | 4 +- .../anchored-region/anchored-region.mdx | 4 +- .../storybook/src/nimble/banner/banner.mdx | 4 +- .../src/nimble/breadcrumb/breadcrumb.mdx | 4 +- .../storybook/src/nimble/button/button.mdx | 19 ++++++-- .../src/nimble/button/button.stories.ts | 39 ++++++++++++--- .../src/nimble/card-button/card-button.mdx | 10 ++-- .../nimble/card-button/card-button.stories.ts | 26 +++++++++- packages/storybook/src/nimble/card/card.mdx | 4 +- .../src/nimble/checkbox/checkbox.mdx | 4 +- .../src/nimble/combobox/combobox.mdx | 4 +- .../storybook/src/nimble/dialog/dialog.mdx | 6 +-- .../src/nimble/dialog/dialog.stories.ts | 2 +- .../storybook/src/nimble/drawer/drawer.mdx | 4 +- .../storybook/src/nimble/icon-base/icons.mdx | 4 +- .../src/nimble/menu-button/menu-button.mdx | 2 + .../nimble/menu-button/menu-button.stories.ts | 15 +++--- .../storybook/src/nimble/menu/menu.stories.ts | 2 +- .../src/nimble/number-field/number-field.mdx | 4 +- .../src/nimble/patterns/button/doc-strings.ts | 8 ++-- .../nimble/patterns/button/styling-docs.mdx | 2 - .../src/nimble/radio-group/radio-group.mdx | 4 +- .../storybook/src/nimble/select/select.mdx | 4 +- .../storybook/src/nimble/switch/switch.mdx | 4 +- .../date-text/table-column-date-text.mdx | 4 +- .../number-text/table-column-number-text.mdx | 4 +- .../table-column/text/table-column-text.mdx | 4 +- packages/storybook/src/nimble/table/table.mdx | 6 +-- packages/storybook/src/nimble/tabs/tabs.mdx | 4 +- .../src/nimble/text-area/text-area.mdx | 4 +- .../src/nimble/text-field/text-field.mdx | 4 +- .../nimble/toggle-button/toggle-button.mdx | 9 ++-- .../toggle-button/toggle-button.stories.ts | 47 +++++++++++++++---- .../storybook/src/nimble/toolbar/toolbar.mdx | 4 +- .../storybook/src/nimble/tooltip/tooltip.mdx | 4 +- .../src/nimble/tree-view/tree-view.mdx | 4 +- .../src/nimble/wafer-map/wafer-map.mdx | 4 +- packages/storybook/src/utilities/storybook.ts | 2 +- 42 files changed, 184 insertions(+), 125 deletions(-) diff --git a/packages/storybook/CONTRIBUTING.md b/packages/storybook/CONTRIBUTING.md index 9086c8dff5..d7ec756aa8 100644 --- a/packages/storybook/CONTRIBUTING.md +++ b/packages/storybook/CONTRIBUTING.md @@ -46,11 +46,15 @@ import * as componentNameStories from './component-name.stories'; -## Appearances +## Usage -## Appearance Variants +## Styling -## Usage +### Appearances + +### Appearance Variants + +### Sizing ## Examples @@ -79,6 +83,8 @@ Note: if linking in a story via a native or Nimble anchor component, use the fol Link ``` +Linking to headings within a document doesn't work very well, i.e. `./page#some-heading`; avoid using links to specific headings and instead link to the page and refer to the section using **Bold**, i.e. `See **Some Heading** on [Page](./page)`. + All other Markdown formatting is supported. See any [Markdown Cheatsheet](https://www.markdownguide.org/cheat-sheet/) for more information. ### Testing diff --git a/packages/storybook/src/nimble/anchor-button/anchor-button.mdx b/packages/storybook/src/nimble/anchor-button/anchor-button.mdx index ef99e23ba3..0658b77bea 100644 --- a/packages/storybook/src/nimble/anchor-button/anchor-button.mdx +++ b/packages/storybook/src/nimble/anchor-button/anchor-button.mdx @@ -20,6 +20,8 @@ An anchor button is a component with the visual appearance of a button, but it n +## Styling + {/* ## Usage */} diff --git a/packages/storybook/src/nimble/anchor-button/anchor-button.stories.ts b/packages/storybook/src/nimble/anchor-button/anchor-button.stories.ts index 5892314b4f..66d8266908 100644 --- a/packages/storybook/src/nimble/anchor-button/anchor-button.stories.ts +++ b/packages/storybook/src/nimble/anchor-button/anchor-button.stories.ts @@ -8,6 +8,7 @@ import { ButtonAppearanceVariant } from '@ni/nimble-components/dist/esm/patterns/button/types'; import { + appearanceDescription, appearanceVariantDescription, contentHiddenDescription, endIconDescription, @@ -56,7 +57,8 @@ const metadata: Meta = { }, appearance: { options: Object.keys(ButtonAppearance), - control: { type: 'radio' } + control: { type: 'radio' }, + description: appearanceDescription }, appearanceVariant: { name: 'appearance-variant', diff --git a/packages/storybook/src/nimble/anchor-tabs/anchor-tabs.mdx b/packages/storybook/src/nimble/anchor-tabs/anchor-tabs.mdx index 0a343ce09d..50bfd9f5ae 100644 --- a/packages/storybook/src/nimble/anchor-tabs/anchor-tabs.mdx +++ b/packages/storybook/src/nimble/anchor-tabs/anchor-tabs.mdx @@ -14,9 +14,7 @@ tab panels hosted on the same page. -{/* ## Appearances */} - -{/* ## Appearance Variants */} +{/* ## Styling */} {/* ## Usage */} diff --git a/packages/storybook/src/nimble/anchor/anchor.mdx b/packages/storybook/src/nimble/anchor/anchor.mdx index 5c9218105c..2deb5598d5 100644 --- a/packages/storybook/src/nimble/anchor/anchor.mdx +++ b/packages/storybook/src/nimble/anchor/anchor.mdx @@ -10,9 +10,7 @@ Per [W3C](https://www.w3.org/WAI/ARIA/apg/patterns/link/), an anchor/link widget -{/* ## Appearances */} - -{/* ## Appearance Variants */} +{/* ## Styling */} {/* ## Usage */} diff --git a/packages/storybook/src/nimble/anchored-region/anchored-region.mdx b/packages/storybook/src/nimble/anchored-region/anchored-region.mdx index f83c1237d8..409b585dd3 100644 --- a/packages/storybook/src/nimble/anchored-region/anchored-region.mdx +++ b/packages/storybook/src/nimble/anchored-region/anchored-region.mdx @@ -17,9 +17,7 @@ available space, or even resize itself based on that space. -{/* ## Appearances */} - -{/* ## Appearance Variants */} +{/* ## Styling */} {/* ## Usage */} diff --git a/packages/storybook/src/nimble/banner/banner.mdx b/packages/storybook/src/nimble/banner/banner.mdx index d91cdf1ff5..a86d1ad469 100644 --- a/packages/storybook/src/nimble/banner/banner.mdx +++ b/packages/storybook/src/nimble/banner/banner.mdx @@ -16,9 +16,7 @@ should be spaced apart using the {bannerGapSize.cssCustomProperty} -{/* ## Appearances */} - -{/* ## Appearance Variants */} +{/* ## Styling */} {/* ## Usage */} diff --git a/packages/storybook/src/nimble/breadcrumb/breadcrumb.mdx b/packages/storybook/src/nimble/breadcrumb/breadcrumb.mdx index c685b8efd5..e4be7375c9 100644 --- a/packages/storybook/src/nimble/breadcrumb/breadcrumb.mdx +++ b/packages/storybook/src/nimble/breadcrumb/breadcrumb.mdx @@ -15,9 +15,7 @@ for information on using this component in Angular with RouterLink directives. -{/* ## Appearances */} - -{/* ## Appearance Variants */} +{/* ## Styling */} {/* ## Usage */} diff --git a/packages/storybook/src/nimble/button/button.mdx b/packages/storybook/src/nimble/button/button.mdx index bff8d0996d..637f641421 100644 --- a/packages/storybook/src/nimble/button/button.mdx +++ b/packages/storybook/src/nimble/button/button.mdx @@ -1,6 +1,7 @@ import { Canvas, Meta, Controls, Title } from '@storybook/blocks'; import ContentHiddenDocs from '../patterns/button/content-hidden-docs.mdx'; import StylingDocs from '../patterns/button/styling-docs.mdx'; +import ComponentApisLink from '../../docs/component-apis-link.mdx'; import { buttonTag } from '@ni/nimble-components/dist/esm/button'; import { anchorButtonTag } from '@ni/nimble-components/dist/esm/anchor-button'; import * as buttonStories from './button.stories'; @@ -15,17 +16,27 @@ action, or performing a delete operation. If you want a button that triggers navigation to a URL, use the instead. + +## API + + + +## Styling + -## Sizing +### Sizing Nimble Buttons are currently always 32px tall. Designs exist for other sizes; if you need these in an application, please comment on [Configurable height for nimble controls (#610)](https://github.com/ni/nimble/issues/610). -## Accessibility +{/* ## Usage */} + +{/* ## Examples */} -Please work with your designer and ensure you have a 4.5:1 -contrast ratio text to background. +## Accessibility + +{/* ## Resources */} diff --git a/packages/storybook/src/nimble/button/button.stories.ts b/packages/storybook/src/nimble/button/button.stories.ts index dd30654a08..517695c513 100644 --- a/packages/storybook/src/nimble/button/button.stories.ts +++ b/packages/storybook/src/nimble/button/button.stories.ts @@ -10,9 +10,10 @@ import { appearanceVariantDescription, contentHiddenDescription, endIconDescription, - iconDescription + iconDescription, + textContentDescription } from '../patterns/button/doc-strings'; -import { createUserSelectedThemeStory } from '../../utilities/storybook'; +import { apiCategory, createUserSelectedThemeStory, disabledDescription } from '../../utilities/storybook'; interface ButtonArgs { label: string; @@ -22,6 +23,7 @@ interface ButtonArgs { icon: boolean; contentHidden: boolean; endIcon: boolean; + click: undefined; } const metadata: Meta = { @@ -36,22 +38,45 @@ const metadata: Meta = { 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 } }, contentHidden: { - description: contentHiddenDescription + name: 'content-hidden', + description: contentHiddenDescription, + table: { category: apiCategory.attributes } + }, + disabled: { + description: disabledDescription({ componentName: 'button' }), + table: { category: apiCategory.attributes } + }, + label: { + name: 'default', + description: textContentDescription({ componentName: 'button' }), + table: { category: apiCategory.slots } }, icon: { - description: iconDescription + name: 'start', + description: iconDescription, + table: { category: apiCategory.slots } }, endIcon: { - description: endIconDescription + name: 'end', + description: endIconDescription, + table: { category: apiCategory.slots } + }, + click: { + description: + 'Fires when the button is activated by either keyboard or mouse.', + table: { category: apiCategory.events }, + control: false } }, // prettier-ignore diff --git a/packages/storybook/src/nimble/card-button/card-button.mdx b/packages/storybook/src/nimble/card-button/card-button.mdx index 444da47f97..9c4b43ae3f 100644 --- a/packages/storybook/src/nimble/card-button/card-button.mdx +++ b/packages/storybook/src/nimble/card-button/card-button.mdx @@ -1,5 +1,6 @@ import { Canvas, Meta, Controls, Title } from '@storybook/blocks'; import { NimbleCardButton } from './card-button.react'; +import { anchorButtonTag } from '@ni/nimble-components/dist/esm/anchor-button'; import { cardButtonTag } from '@ni/nimble-components/dist/esm/card-button'; import { buttonTag } from '@ni/nimble-components/dist/esm/button'; import * as cardButtonStories from './card-button.stories'; @@ -10,14 +11,17 @@ import * as cardButtonStories from './card-button.stories'; The is a button that is designed to contain arbitrary content that is specified by a client application. The is intended to be larger and more prominent on a page than the standard . +If you want a button that triggers navigation to a URL, use the instead. + Note: The styling for the "Color" theme is not complete. - -{/* ## Appearances */} +## API + + -{/* ## Appearance Variants */} +{/* ## Styling */} {/* ## Usage */} diff --git a/packages/storybook/src/nimble/card-button/card-button.stories.ts b/packages/storybook/src/nimble/card-button/card-button.stories.ts index 969e1db76e..9eaac9e7b9 100644 --- a/packages/storybook/src/nimble/card-button/card-button.stories.ts +++ b/packages/storybook/src/nimble/card-button/card-button.stories.ts @@ -3,11 +3,13 @@ import { withActions } from '@storybook/addon-actions/decorator'; import type { HtmlRenderer, Meta, StoryObj } from '@storybook/html'; import { bodyFont } from '@ni/nimble-components/dist/esm/theme-provider/design-tokens'; import { cardButtonTag } from '@ni/nimble-components/dist/esm/card-button'; -import { createUserSelectedThemeStory } from '../../utilities/storybook'; +import { apiCategory, createUserSelectedThemeStory, disabledDescription } from '../../utilities/storybook'; interface CardButtonArgs { disabled: boolean; selected: boolean; + content: string; + click: undefined; } const metadata: Meta = { @@ -52,6 +54,28 @@ const metadata: Meta = { args: { disabled: false, selected: false + }, + argTypes: { + disabled: { + description: disabledDescription({ componentName: 'card button' }), + table: { category: apiCategory.attributes } + }, + selected: { + description: 'Styles the card button to indicate it is selected.', + table: { category: apiCategory.attributes } + }, + content: { + name: 'default', + description: 'The card button allows arbitrary HTML child content in its default slot.', + table: { category: apiCategory.slots }, + control: false + }, + click: { + description: + 'Fires when the card button is activated by either keyboard or mouse.', + table: { category: apiCategory.events }, + control: false + } } }; diff --git a/packages/storybook/src/nimble/card/card.mdx b/packages/storybook/src/nimble/card/card.mdx index ba31748dc1..2e853a035b 100644 --- a/packages/storybook/src/nimble/card/card.mdx +++ b/packages/storybook/src/nimble/card/card.mdx @@ -12,9 +12,7 @@ application. The is intended for grouping related content -{/* ## Appearances */} - -{/* ## Appearance Variants */} +{/* ## Styling */} {/* ## Usage */} diff --git a/packages/storybook/src/nimble/checkbox/checkbox.mdx b/packages/storybook/src/nimble/checkbox/checkbox.mdx index 42e970a5e5..51ebc12fe1 100644 --- a/packages/storybook/src/nimble/checkbox/checkbox.mdx +++ b/packages/storybook/src/nimble/checkbox/checkbox.mdx @@ -10,9 +10,7 @@ Per [W3C](https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/) - The dual-state c -{/* ## Appearances */} - -{/* ## Appearance Variants */} +{/* ## Styling */} {/* ## Usage */} diff --git a/packages/storybook/src/nimble/combobox/combobox.mdx b/packages/storybook/src/nimble/combobox/combobox.mdx index f348f7e44c..671bbfe789 100644 --- a/packages/storybook/src/nimble/combobox/combobox.mdx +++ b/packages/storybook/src/nimble/combobox/combobox.mdx @@ -9,9 +9,7 @@ import { listOptionTag } from '@ni/nimble-components/dist/esm/list-option/'; -{/* ## Appearances */} - -{/* ## Appearance Variants */} +{/* ## Styling */} {/* ## Usage */} diff --git a/packages/storybook/src/nimble/dialog/dialog.mdx b/packages/storybook/src/nimble/dialog/dialog.mdx index ced58cc43e..aa90633baa 100644 --- a/packages/storybook/src/nimble/dialog/dialog.mdx +++ b/packages/storybook/src/nimble/dialog/dialog.mdx @@ -11,11 +11,9 @@ By default, the first focusable control gets focus when the dialog is opened. To -{/* ## Appearances */} +## Styling -{/* ## Appearance Variants */} - -## Sizing +### Sizing The dialog size can be customized by modyfing the width, height and max-height properties of `nimble-dialog::part(control)`. diff --git a/packages/storybook/src/nimble/dialog/dialog.stories.ts b/packages/storybook/src/nimble/dialog/dialog.stories.ts index d2e49248ee..014120e1d7 100644 --- a/packages/storybook/src/nimble/dialog/dialog.stories.ts +++ b/packages/storybook/src/nimble/dialog/dialog.stories.ts @@ -61,7 +61,7 @@ const content = { const sizeDescription = ` Size of a nimble dialog. -See the Sizing section of the Usage Docs for information on controlling the size of the dialog. +See the **Sizing** section for information on controlling the size of the dialog. `; const widths = { diff --git a/packages/storybook/src/nimble/drawer/drawer.mdx b/packages/storybook/src/nimble/drawer/drawer.mdx index cd8e8ce1f7..47694b8bda 100644 --- a/packages/storybook/src/nimble/drawer/drawer.mdx +++ b/packages/storybook/src/nimble/drawer/drawer.mdx @@ -9,9 +9,7 @@ Specialized dialog designed to slide in from either side of the page. Typically -{/* ## Appearances */} - -{/* ## Appearance Variants */} +{/* ## Styling */} {/* ## Usage */} diff --git a/packages/storybook/src/nimble/icon-base/icons.mdx b/packages/storybook/src/nimble/icon-base/icons.mdx index 9d28224419..4bde23a753 100644 --- a/packages/storybook/src/nimble/icon-base/icons.mdx +++ b/packages/storybook/src/nimble/icon-base/icons.mdx @@ -10,9 +10,7 @@ Nimble icons can be slotted into other components or used independently. Each ic -{/* ## Appearances */} - -{/* ## Appearance Variants */} +{/* ## Styling */} {/* ## Usage */} diff --git a/packages/storybook/src/nimble/menu-button/menu-button.mdx b/packages/storybook/src/nimble/menu-button/menu-button.mdx index 08cf0a8795..4c6bd38af4 100644 --- a/packages/storybook/src/nimble/menu-button/menu-button.mdx +++ b/packages/storybook/src/nimble/menu-button/menu-button.mdx @@ -19,6 +19,8 @@ often styled as a typical push button with a downward pointing arrow or triangle +## Styling + {/* ## Usage */} diff --git a/packages/storybook/src/nimble/menu-button/menu-button.stories.ts b/packages/storybook/src/nimble/menu-button/menu-button.stories.ts index 9fb157afb4..ab8f172717 100644 --- a/packages/storybook/src/nimble/menu-button/menu-button.stories.ts +++ b/packages/storybook/src/nimble/menu-button/menu-button.stories.ts @@ -17,12 +17,14 @@ import { appearanceVariantDescription, contentHiddenDescription, endIconDescription, - iconDescription + iconDescription, + textContentDescription } from '../patterns/button/doc-strings'; import { apiCategory, createUserSelectedThemeStory, - disableStorybookZoomTransform + disableStorybookZoomTransform, + disabledDescription } from '../../utilities/storybook'; interface MenuButtonArgs { @@ -36,8 +38,8 @@ interface MenuButtonArgs { disabled: boolean; contentHidden: boolean; menuPosition: string; - toggle: () => void; - beforetoggle: () => void; + toggle: undefined; + beforetoggle: undefined; } const metadata: Meta = { @@ -54,8 +56,7 @@ const metadata: Meta = { 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.', + description: textContentDescription({ componentName: 'menu button' }), table: { category: apiCategory.slots } }, icon: { @@ -94,7 +95,7 @@ const metadata: Meta = { }, disabled: { control: { type: 'boolean' }, - description: 'Disables the button.', + description: disabledDescription({ componentName: 'menu button' }), table: { category: apiCategory.attributes } }, contentHidden: { diff --git a/packages/storybook/src/nimble/menu/menu.stories.ts b/packages/storybook/src/nimble/menu/menu.stories.ts index 648e45d320..1f647052b2 100644 --- a/packages/storybook/src/nimble/menu/menu.stories.ts +++ b/packages/storybook/src/nimble/menu/menu.stories.ts @@ -27,7 +27,7 @@ interface MenuItemArgsBase { } interface MenuItemArgs extends MenuItemArgsBase { - change: () => void; + change: undefined; } interface AnchorMenuItemArgs { diff --git a/packages/storybook/src/nimble/number-field/number-field.mdx b/packages/storybook/src/nimble/number-field/number-field.mdx index 4090916277..36afea60a9 100644 --- a/packages/storybook/src/nimble/number-field/number-field.mdx +++ b/packages/storybook/src/nimble/number-field/number-field.mdx @@ -10,9 +10,7 @@ Similar to a single line text box but only used for numeric data. The controls a -{/* ## Appearances */} - -{/* ## Appearance Variants */} +{/* ## Styling */} {/* ## Usage */} diff --git a/packages/storybook/src/nimble/patterns/button/doc-strings.ts b/packages/storybook/src/nimble/patterns/button/doc-strings.ts index e57b09b90a..80975f0332 100644 --- a/packages/storybook/src/nimble/patterns/button/doc-strings.ts +++ b/packages/storybook/src/nimble/patterns/button/doc-strings.ts @@ -1,8 +1,10 @@ -import { iconDescription as baseIconDescription } from '../../../utilities/storybook'; +import { textContentDescription as baseTextContentDescription, iconDescription as baseIconDescription } from '../../../utilities/storybook'; -export const appearanceDescription = 'This attribute affects the appearance of the button.'; +export const textContentDescription = (options: { componentName: string }): string => `${baseTextContentDescription(options)} This will be hidden when \`content-hidden\` is set but should always be provided; see the **Accessibility** section for more info.`; -export const appearanceVariantDescription = 'This attribute has no effect on buttons with a `ghost` appearance. There is no `accent` appearance-variant for the `color` UI.'; +export const appearanceDescription = 'This attribute affects the appearance of the button. See the **Styling** section for more information.'; + +export const appearanceVariantDescription = 'This attribute configures additional variations of the button appearance. It has no effect on buttons with a `ghost` appearance. There is no `accent` appearance-variant for the `color` UI. See the **Styling** section for more information.'; export const contentHiddenDescription = 'When set, this attribute hides the text and end icon, leaving only the start icon visible.'; diff --git a/packages/storybook/src/nimble/patterns/button/styling-docs.mdx b/packages/storybook/src/nimble/patterns/button/styling-docs.mdx index c031de3688..ba64a4b374 100644 --- a/packages/storybook/src/nimble/patterns/button/styling-docs.mdx +++ b/packages/storybook/src/nimble/patterns/button/styling-docs.mdx @@ -1,7 +1,5 @@ import { NimbleIconKey } from '../../icons/key.react'; -## Styling - ### Appearances These are the standard styling options for the button. Each should be considered for use before employing an appearance variant. diff --git a/packages/storybook/src/nimble/radio-group/radio-group.mdx b/packages/storybook/src/nimble/radio-group/radio-group.mdx index 31341c0112..544a458456 100644 --- a/packages/storybook/src/nimble/radio-group/radio-group.mdx +++ b/packages/storybook/src/nimble/radio-group/radio-group.mdx @@ -9,9 +9,7 @@ Per [W3C](https://www.w3.org/WAI/ARIA/apg/patterns/radio/) - A radio group is a -{/* ## Appearances */} - -{/* ## Appearance Variants */} +{/* ## Styling */} {/* ## Usage */} diff --git a/packages/storybook/src/nimble/select/select.mdx b/packages/storybook/src/nimble/select/select.mdx index 92fcac0987..1c2287f794 100644 --- a/packages/storybook/src/nimble/select/select.mdx +++ b/packages/storybook/src/nimble/select/select.mdx @@ -11,9 +11,7 @@ Select is a control for selecting amongst a set of options. Its value comes from -{/* ## Appearances */} - -{/* ## Appearance Variants */} +{/* ## Styling */} {/* ## Usage */} diff --git a/packages/storybook/src/nimble/switch/switch.mdx b/packages/storybook/src/nimble/switch/switch.mdx index 6af17a85a0..4a7c671fe0 100644 --- a/packages/storybook/src/nimble/switch/switch.mdx +++ b/packages/storybook/src/nimble/switch/switch.mdx @@ -15,9 +15,7 @@ pressed or not pressed and can optionally allow for a partially pressed state. -{/* ## Appearances */} - -{/* ## Appearance Variants */} +{/* ## Styling */} {/* ## Usage */} diff --git a/packages/storybook/src/nimble/table-column/date-text/table-column-date-text.mdx b/packages/storybook/src/nimble/table-column/date-text/table-column-date-text.mdx index e89f003143..9c51364f77 100644 --- a/packages/storybook/src/nimble/table-column/date-text/table-column-date-text.mdx +++ b/packages/storybook/src/nimble/table-column/date-text/table-column-date-text.mdx @@ -13,9 +13,7 @@ The column is used to display date-time fie -{/* ## Appearances */} - -{/* ## Appearance Variants */} +{/* ## Styling */} ## Usage 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 76c67644cb..a19b40e98f 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 @@ -20,9 +20,7 @@ based on the value of the `lang` token, which can be set via the [nimble-theme-p -{/* ## Appearances */} - -{/* ## Appearance Variants */} +{/* ## Styling */} ## Usage 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 cd7e9d7e63..e7e2dc5eca 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 @@ -13,9 +13,7 @@ The column is used to display string fields as -{/* ## Appearances */} - -{/* ## Appearance Variants */} +{/* ## Styling */} ## Usage diff --git a/packages/storybook/src/nimble/table/table.mdx b/packages/storybook/src/nimble/table/table.mdx index b27bb4acc6..8d9ffd430d 100644 --- a/packages/storybook/src/nimble/table/table.mdx +++ b/packages/storybook/src/nimble/table/table.mdx @@ -49,12 +49,10 @@ 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 -{/* ## Appearances */} - -{/* ## Appearance Variants */} - ## 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 */} diff --git a/packages/storybook/src/nimble/tabs/tabs.mdx b/packages/storybook/src/nimble/tabs/tabs.mdx index 25c6d23dc6..7d56916cbd 100644 --- a/packages/storybook/src/nimble/tabs/tabs.mdx +++ b/packages/storybook/src/nimble/tabs/tabs.mdx @@ -18,9 +18,7 @@ If you want a sequence of tabs that navigate to different URLs, use the Anchor T -{/* ## Appearances */} - -{/* ## Appearance Variants */} +{/* ## Styling */} {/* ## Usage */} diff --git a/packages/storybook/src/nimble/text-area/text-area.mdx b/packages/storybook/src/nimble/text-area/text-area.mdx index c2be0e2104..5dff1d0092 100644 --- a/packages/storybook/src/nimble/text-area/text-area.mdx +++ b/packages/storybook/src/nimble/text-area/text-area.mdx @@ -12,9 +12,7 @@ If you configure your text area to be resizable (with the `resize` attribute) in -{/* ## Appearances */} - -{/* ## Appearance Variants */} +{/* ## Styling */} {/* ## Usage */} diff --git a/packages/storybook/src/nimble/text-field/text-field.mdx b/packages/storybook/src/nimble/text-field/text-field.mdx index 961d6bd800..3a0ca2a25c 100644 --- a/packages/storybook/src/nimble/text-field/text-field.mdx +++ b/packages/storybook/src/nimble/text-field/text-field.mdx @@ -10,9 +10,7 @@ A single-line text field. -{/* ## Appearances */} - -{/* ## Appearance Variants */} +{/* ## Styling */} {/* ## Usage */} diff --git a/packages/storybook/src/nimble/toggle-button/toggle-button.mdx b/packages/storybook/src/nimble/toggle-button/toggle-button.mdx index d2d731a7b7..391718a8c7 100644 --- a/packages/storybook/src/nimble/toggle-button/toggle-button.mdx +++ b/packages/storybook/src/nimble/toggle-button/toggle-button.mdx @@ -9,13 +9,16 @@ import * as toggleButtonStories from './toggle-button.stories'; Per [W3C](https://www.w3.org/WAI/ARIA/apg/patterns/button/) - A toggle button is a two-state button that can be either off (not pressed) or on (pressed). For example, a button labeled mute in an audio player could -indicate that sound is muted by setting the pressed state true. Important: it is critical the label on a toggle does -not change when its state changes. In this example, when the pressed state is true, the label remains "Mute" so a -screen reader would say something like "Mute toggle button pressed". +indicate that sound is muted by setting the pressed state true. + +## API + +## Styling + {/* ## Usage */} diff --git a/packages/storybook/src/nimble/toggle-button/toggle-button.stories.ts b/packages/storybook/src/nimble/toggle-button/toggle-button.stories.ts index 5f59da141f..abe63e6893 100644 --- a/packages/storybook/src/nimble/toggle-button/toggle-button.stories.ts +++ b/packages/storybook/src/nimble/toggle-button/toggle-button.stories.ts @@ -10,9 +10,10 @@ import { appearanceVariantDescription, contentHiddenDescription, endIconDescription, - iconDescription + iconDescription, + textContentDescription } from '../patterns/button/doc-strings'; -import { createUserSelectedThemeStory } from '../../utilities/storybook'; +import { apiCategory, createUserSelectedThemeStory, disabledDescription } from '../../utilities/storybook'; interface ToggleButtonArgs { label: string; @@ -23,8 +24,13 @@ interface ToggleButtonArgs { icon: boolean; contentHidden: boolean; endIcon: boolean; + change: undefined; } +const contentDescription = textContentDescription({ componentName: 'toggle button' }); + +const defaultSlotDescription = `${contentDescription} The content should remain the same whether the toggle button is pressed or not.`; + const metadata: Meta = { title: 'Components/Toggle Button', decorators: [withActions], @@ -35,24 +41,49 @@ const metadata: Meta = { }, argTypes: { appearance: { - options: Object.values(ButtonAppearance), + 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 } }, contentHidden: { - description: contentHiddenDescription + name: 'content-hidden', + description: contentHiddenDescription, + table: { category: apiCategory.attributes } + }, + disabled: { + description: disabledDescription({ componentName: 'toggle button' }), + table: { category: apiCategory.attributes } + }, + checked: { + description: 'Whether the toggle button is pressed (on) or not pressed (off).', + table: { category: apiCategory.attributes } + }, + label: { + name: 'default', + description: defaultSlotDescription, + table: { category: apiCategory.slots } }, icon: { - description: iconDescription + name: 'start', + description: iconDescription, + table: { category: apiCategory.slots } }, endIcon: { - description: endIconDescription + name: 'end', + description: endIconDescription, + table: { category: apiCategory.slots } + }, + change: { + description: 'Fires when the toggle button is pressed via mouse or keyboard.', + table: { category: apiCategory.events } } }, // prettier-ignore diff --git a/packages/storybook/src/nimble/toolbar/toolbar.mdx b/packages/storybook/src/nimble/toolbar/toolbar.mdx index 98c58c23c6..b42fa79ccc 100644 --- a/packages/storybook/src/nimble/toolbar/toolbar.mdx +++ b/packages/storybook/src/nimble/toolbar/toolbar.mdx @@ -22,9 +22,7 @@ nimble-toolbar::part(positioning-region) { -{/* ## Appearances */} - -{/* ## Appearance Variants */} +{/* ## Styling */} {/* ## Usage */} diff --git a/packages/storybook/src/nimble/tooltip/tooltip.mdx b/packages/storybook/src/nimble/tooltip/tooltip.mdx index 0572f2e2ad..dc7f08ad19 100644 --- a/packages/storybook/src/nimble/tooltip/tooltip.mdx +++ b/packages/storybook/src/nimble/tooltip/tooltip.mdx @@ -11,9 +11,7 @@ It is recommended to set up aria-describedby, an accessibility feature that sets -{/* ## Appearances */} - -{/* ## Appearance Variants */} +{/* ## Styling */} {/* ## Usage */} diff --git a/packages/storybook/src/nimble/tree-view/tree-view.mdx b/packages/storybook/src/nimble/tree-view/tree-view.mdx index 385c00a6fa..453b36ef63 100644 --- a/packages/storybook/src/nimble/tree-view/tree-view.mdx +++ b/packages/storybook/src/nimble/tree-view/tree-view.mdx @@ -20,9 +20,7 @@ which navigate to a url upon activation. Both types of tree items support icons -{/* ## Appearances */} - -{/* ## Appearance Variants */} +{/* ## Styling */} {/* ## Usage */} diff --git a/packages/storybook/src/nimble/wafer-map/wafer-map.mdx b/packages/storybook/src/nimble/wafer-map/wafer-map.mdx index 222df68921..d182259ef2 100644 --- a/packages/storybook/src/nimble/wafer-map/wafer-map.mdx +++ b/packages/storybook/src/nimble/wafer-map/wafer-map.mdx @@ -10,9 +10,7 @@ A wafer map is a component for visualizing data from the manufacture of semicond -{/* ## Appearances */} - -{/* ## Appearance Variants */} +{/* ## Styling */} {/* ## Usage */} diff --git a/packages/storybook/src/utilities/storybook.ts b/packages/storybook/src/utilities/storybook.ts index 439fc977db..bec10d629e 100644 --- a/packages/storybook/src/utilities/storybook.ts +++ b/packages/storybook/src/utilities/storybook.ts @@ -170,5 +170,5 @@ export const apiCategory = { } as const; export const iconDescription = 'Set `slot="start"` to include an icon before the text content.'; -export const disabledDescription = (options: { componentName: string }): string => `Disables the ${options.componentName}.`; +export const disabledDescription = (options: { componentName: string }): string => `Styles the ${options.componentName} as disabled and prevents focus and user interaction.`; export const textContentDescription = (options: { componentName: string }): string => `The text content of the ${options.componentName}.`;