Standardize MDX structure

[jamesfan]

In an effort to standardize how our MDX docs are structured, I'm proposing the following format for organizing our docs. I examined a few different approaches to how we've organized our docs so far...

• The MDX docs I wrote for the canvas-site (the Input components have been migrated to canvas-kit in this PR)
• @anicholls' Button MDX PR
• The MDX docs which have already been authored in canvas-kit (e.g., Pagination, Tabs, Popup, Modal, Box, Flex, etc.)

... and tried to come up with a format that incorporates the best parts of each of these approaches.

I've broken the overall Component.stories.mdx file into three sections to make this document easier to digest:

1. Introduction
2. Usage
3. Specifications

A complete Component.stories.mdx file would be the simple sequence of these sections:

Introduction

Usage

Specifications

Introduction

Every MDX should begin the same way with imports, the <Meta /> tag, the name and description of the component, and installation instructions.

import {Meta} from '@storybook/addon-docs/blocks';
import {Specifications} from '@workday/canvas-kit-docs';

// Import CK component
import {Component} from '@workday/canvas-kit-[preview-|labs-]react/component';

// Import examples
import {Basic} from './examples/Basic';
...

<Meta title="storybook/path/..." component={Component} />

# Canvas Kit Component

Short description of Component.

[> Workday Design Reference](https://design.workday.com/link/to/component)

## Installation

```sh
yarn add @workday/canvas-kit-[preview-|labs-]react
```

All instances of Component should be replaced with the component name.

In some cases, it may be helpful to add content at the beginning of the component documentation to provide extra information or high-level context. These sections may be added as additional level two headings below Installation. For example, it would make sense for the What's the difference between Flex and Box? section in the Flex docs to appear here.

Usage

The format of the Usage section will vary based on the type of component. I've classified components into three types:

1. Simple Component (e.g., Text Input)
2. Component Family with Multiple Components (e.g., Button)
3. Compound Component (e.g., Popup)

As a general rule of thumb, there should be an example for each prop supported by the component (but use your judgment; some components may have too many props to have an example for each one). Props that are simply forwarded to the underlying HTML element via elemProps as HTML attributes (e.g., placeholder in <TextInput placeholder="Placeholder text">) do not need to have examples, though you may include them if you wish.

Usage: Simple Component

Examples: Text Input (MDX)

## Usage

### Basic Example

Explain Basic example for Text Input.

<ExampleCodeBlock code={Basic} />

### Disabled

Explain Disabled example for Text Input.

<ExampleCodeBlock code={Disabled} />

[...more Text Input examples...]

## Props

Undocumented props are spread to the underlying `<input type="text">` element.

<ArgsTable of={TextInput} />

Note the mention of how elemProps are handled in the Props section.

Technically, Box would be considered a Simple Component, but given the sheer number of props it supports, we may need to handle it as a special case with its own format.

Usage: Component Family with Multiple Components

Examples: Button (MDX), Icon Button (MDX) (note: Icon and Icon Button docs don't stick to the exact format below yet)

Some modules contain multiple related components that should be documented together in a single page. Buttons and Icon Buttons are the clearest example of this.

## Usage

Button consists of multiple components, yadda yadda yadda.

Undocumented props are spread to the underlying `<button>` element.

### Primary Button

#### Basic Example

Explain Basic example for Primary Button.

<ExampleCodeBlock code={Primary} />

[...more Primary Button examples...]

#### Props

<ArgsTable of={PrimaryButton} />

### Secondary Button

#### Basic Example

Explain Basic example for Secondary Button.

<ExampleCodeBlock code={Secondary} />

[...more Secondary Button examples...]

#### Props

<ArgsTable of={SecondaryButton} />

[...more Button components...]

Usage: Compound Component

Examples: Skeleton (MDX) (note: we have a number of Compound Components with MDXes that don't that yet follow the format below such as Popup and Pagination).

Compound Components are the most complex type of component and thus require the most documentation out of the three types. In addition to Usage, they contain a required level two heading for Components (i.e., Subcomponents), as well as optional level two headings for Model, Behavior Hooks + Other Hooks or just Hooks (if there are no Behavior Hooks), and Utilities.

## Usage

### Basic Example

Explain Basic example for Popup.

<ExampleCodeBlock code={Basic} />

[...more Popup examples...]

## Components

### Popup

#### Usage

Explain `Popup` component.

```tsx
// using Popup
<Popup model={model}>
  <Popup.Target /> // no model here
</Popup>

// using models on subcomponents
<>
  <Popup.Target model={model} />
</>
```

#### Props

<ArgsTable of={Popup} />

### Popup.Target

#### Usage

Explain `Popup.Target` component.

```tsx
const model = usePopupModel();

// using this component
<Popup.Target>Show Popup</PopupTarget>

// using props instead
const popupTargetButtonProps = usePopupTarget(model);
<SecondaryButton {...popupTargetButtonProps}>Show Popup</SecondaryButton>
```

#### Props

Undocumented props are spread to the underlying `<button>` element (or whatever element was rendered
using the `as` prop).

<ArgsTable of={Popup.Target} />

[...more Popup subcomponents...]

## Model

Explain `Popup` model, including hoisting the model example (which is required in `Popup`'s case).

```tsx
// example of hoisting the model with `usePopupModel`
```

### Config

`usePopupModel` accepts a configuration object with the following properties and returns a
`PopupModel` with `state` and `events` properties.

<ArgsTable of={PopupConfigComponent} />

### State

The `PopupModel` `state` is an object with the following properties.

<ArgsTable of={PopupStateComponent} />

### Events

The `PopupModel` `events` is an object with the following properties.

<ArgsTable of={PopupEventsComponent} />

## Behavior Hooks

### useAssistiveHideSiblings

Explain `useAssistiveHideSiblings`

```tsx
// example of using `useAssistiveHideSiblings`
```

[...more Popup Behavior Hooks (hooks which accept a PopupModel and optionally return an object meant to be spread onto a subcomponent)...]

## Other Hooks

### usePopupStack

Explain `usePopupStack`.

```tsx
// example of using `usePopupStack`
```

[...more Popup Other Hooks (hooks which don't match the signature of a Behavior Hook)...]

## Utilities

### somePopupUtility

Explain `somePopupUtility`.

```tsx
// example of using somePopupUtility
```

[...more Popup utilities...]

Note that code in the Components, Behavior Hooks/Other Hooks/Hooks, and Utilities sections don't necessarily use ExampleCodeBlock, instead opting for regular code blocks since they may not be self-contained examples. This should help keep the number of stories listed in the Storybook navigation in check given the many code snippets likely to be present in Compound Component documentation.

See Popup.stories.mdx for an example of how to display ArgsTables for the model state, events, and config.

Specifications

If the component has integration tests, add a Specifications section to the end to display the tests in a readable format.

## Specifications

<Specifications file="Component.spec.ts" name="Component" />

[jamesfan]

As a general rule of thumb, there should be an example for each prop supported by the Component.

Thoughts on this? This makes the most sense to me, though I'm trying to find cases where this might backfire (components with too many props, etc.).

[anicholls]

I was trying to decide what to do for the "component family with multiple components" type (with buttons) in regard to this. If the majority of the props are the same between the family of components it seems redundant to have a story/example for every type of component using the same prop (e.g. grow, icon, iconPosition and dataLabel). Maybe I just provide examples for the first and say the same props apply to the others?

[jamesfan]

Maybe I just provide examples for the first and say the same props apply to the others?

Works for me. 👍

[jamesfan]

What do folks think about using Basic Example instead of Default Example? I stuck with Default for now since it's a convention we've established for our stories (at least for Input components), but Basic feels like a more accurate descriptor of the example.

[alanbsmith]

I think “basic” is better. I think I used that on compound component docs.

[jamesfan]

Sounds good, I'll update the doc.

[NicholasBoll]

We ran into an issue with "Default" that was defined in MDX mode in Storybook. If defined via CSF, Default was fine. If defined via MDX, Storybook renamed the ID to Default_story. This was unintuitive and very difficult to reason about why the name changed. Basic doesn't have this problem.

[alanbsmith]

Are we wanting to drop the labs and preview badges from the docs? I’m fine either way, I just noticed they were absent from the Introduction section.

[jamesfan]

Oversight on my part. I do like a having a noticeable visual cue that a component is in Labs or Preview -- if we add the badge back in, we'll need to figure out how handle it on the canvas-site since we may want a different visual treatment there.