Proof of concept / strategy decision: MDX stories?

[damontgomery]

Do we want to use MDX to write our stories?

What are the trade-offs?

[damontgomery]

I did a POC which you can try with the branch here: https://github.com/phase2/outline/tree/poc/mdx-stories

Key file: https://github.com/phase2/outline/blob/poc/mdx-stories/src/components/base/outline-alert/outline-alert.stories.mdx

I'm not sure what to make of it yet, but here are some thoughts.

Benefits

• Can more easily customize the docs page with descriptions, etc. This is nicer than a string of markdown in the parameters.docs object.

Challenges

• Not as much official or community documentation
  • Have to guess and piece together different bits of documentation for similar things, lots of trial and error
• Lack of intellisense, autocomplete like features in VSCode
  • May be extensions I can install. Installed MDX and set the type of file to Markdown React.
• Need to use React / JSX which we aren't using elsewhere
  • One more potential thing to learn, but not too much.
• Syntax errors aren't clearly spelled out in the console
• Don't think it supports TypeScript

Example using MDX (similar to above link, but trimmed)

import { Meta, Story, Canvas, ArgsTable } from '@storybook/addon-docs';
import { html } from 'lit';
import { OutlineAlert, alertStatusTypes } from './outline-alert'

<Meta
  title="Molecules/Alert"
  component="outline-alert"
  argTypes={{
    statusType: {
      name: 'Status Type',
      description:
        'The status type of the alert. Such as `information` or `warning`.',
      options: alertStatusTypes,
      control: { type: 'select' },
    },
  }}
  args={{
    statusType: 'warning',
  }}
/>

export const Template = ({
  statusType,
  defaultSlot,
}) => html`
  <outline-alert
    statusType="${statusType}"
  >
    ${defaultSlot}
  </outline-alert>
`;

## Error

We set our `statusType` attribute to `error` here.

<Canvas>
  <Story
    name="Error"
    args={{
      statusType: 'error',
      defaultSlot: html`<p>Example message.</p>`,
    }}
  >
    {Template.bind({})}
  </Story>
</Canvas>

## Story without template

This is potentially simpler, but doesn't support controls.

<Canvas>
  <Story
    name="No Template"
  >
    {html`
      <outline-alert>
        Hello world
      </outline-alert>
    `}
  </Story>
</Canvas>

[damontgomery]

After getting used to TypeScript the try to compile -> wait for error loop when using MDX is :(. I'll probably get used to it, but I miss the immediate feedback when for example I accidentally use a = instead of a :.

[damontgomery]

2 issues.

It looks like Storybook really wants to style P tags and other things. Encountered this with font family.

storybookjs/storybook#10054

And, if you put a space in the template literal in MDX, I think Storybook crashes. This is inconsistent with watch, but seems consistent if you run yarn start and kill the process.

Removing the space in the middle of the elements doesn't crash, space crashes.

<Canvas>
  <Story name="Sample">
    {html`
      <outline-heading level="h2" level-size="4xl">
        Example heading
      </outline-heading>
      
      <p>Example paragraph text.</p>
    `}
  </Story>
</Canvas>

[damontgomery]

After working with this for a while, I use MDX for demo pages that aggregate other components. These aren't meant for controls and the MDX doesn't break too frequently.

For components, I use ts. MDX really seems like more hassle than it's worth. The main issues are the lack of intellisense / feedback and the crashing. Don't have these issues with ts.