Live Edit or enabling Controls in MDX format

[dannykoshy]

Hi All,

Is there a way to make Live edit or enable Control addon in the MDX format?

I have noticed that in DocsPage it is possible but not in MDX.

This would be a cool feature to have!

What do you guys think?

[shilman]

Controls works in MDX using <ArgsTable story="story--id" />

https://storybook.js.org/docs/react/writing-docs/doc-blocks#argstable

[shilman]

@KenACollins I took the sample code here: https://raw.githubusercontent.com/chromaui/learnstorybook-design-system/master/src/Avatar.stories.mdx

And added this line to the bottom (separated by an empty line):

<ArgsTable story="Controls" />

And it worked as expected. cc @jonniebigodes

[KenACollins]

Hi Mike @shilman,

Oh wow, I hadn't thought of Controls as a story ID but I see what you mean when I add it to the bottom, it enables the previously broken playground to come alive! That line of code is definitely missing from the source code used in the tutorial.

Okay, so having the controls work on the Docs tab is a decent solution. But the Controls panel still appears on the Canvas tab with that annoying message that the story has not been configured for controls. I guess with the MDX approach to stories, we don't need the Controls panel. Can it be removed or hidden? What dictates its appearance?

And by the way, I really appreciate all your and @jonniebigodes help. I am the sole developer in a 9,000 employee company trying to build our first design system and I like what Storybook offers. I just need some help working through the quirks so thank you very much! I am staying on the 6.2.0-BETA version for now, not reverting to stable 6.1 just yet.

[jonniebigodes]

@KenACollins an update should be up soon in the documentation. That specific tutorial is currently under some work and I can factor it in. It should be up shortly. No need to thank whatsoever, more than glad to answer your questions as best as possible.

[shilman]

To disable the controls tab, simply disable the controls addon if you're using addon-essentials. The controls will still show up on the docs page (due to a quirk in how this is all implemented).

// .storybook/main.js

module.exports = {
  addons: [{
    name: '@storybook/addon-essentials',
    options: {
      controls: false,
    }
  }]
};

https://storybook.js.org/docs/react/essentials/introduction

[KenACollins]

Oh, interesting, Mike* @shilman. I had not seen that syntax before. I have just seen the controls listed directly within the addons array. The tutorial code has other add-ons listed in .storybook/main.js besides essentials. I modified my code as follows:

  "addons": [
    "@storybook/addon-links",
    {
      name: "@storybook/addon-essentials",
      options: { controls: false, },
    }, 
    "@storybook/preset-create-react-app",
    "@storybook/addon-a11y",
  ]

It worked! The Controls panel disappeared after I stopped and restarted the app. Thanks for the tip.

*I have been assuming the whole time that you might go by 'Mike' but maybe you prefer 'Michael'.

[jonniebigodes]

@KenACollins just wanted to give some context towards that particular piece of Documentation and @shilman feel free to correct me at any point. Following the tutorial, you start off with the following set of CSF stories contained within the Avatar.stories.js file:

import React from "react";

import { Avatar } from "./Avatar";

export default {
  title: "Design System/Avatar",
  component: Avatar,
  parameters: {
    componentSubtitle:
      "Displays an image that represents a user or organization",
  },
};

export const Standard = (args) => <Avatar {...args} />;
Standard.args = {
  size: "large",
  username: "Tom Coleman",
  src: "https://avatars2.githubusercontent.com/u/132554",
};

A standard story using args that you can manipulate at will with Storybook Controls.
When you reach the Document section you as any other reader transition to MDX based stories. And there's one change in the way you write your stories and how you can document your components using MDX.

You now are introduced to :

import {
  Meta,
  Story,
  Canvas,
  ArgsTable,
  Preview,
} from "@storybook/addon-docs/blocks";

import { Avatar } from "./Avatar";

<Meta title="Design System/Avatar" component={Avatar} />

# Avatar

## Displays an image that represents a user or organization

Use an avatar for attributing actions or content to specific users.

The user's name should _always_ be present when using Avatar – either printed beside the avatar or in a tooltip.

<Preview withToolbar>
  <Story name="standard">
    <Avatar
      size="large"
      username="Tom Coleman"
      src="https://avatars2.githubusercontent.com/u/132554"
    />
  </Story>
</Preview>

## Usage

Avatar is used to represent a person or an organization. By default the avatar shows an image and gracefully falls back to the first initial of the username. While hydrating the component you may find it useful to render a skeleton template to indicate that Avatar is awaiting data. Avatars can be grouped with the AvatarList component.


### Sizes

4 sizes are supported.

<Story name="sizes">
  <div>
    <Avatar
      size="large"
      username="Tom Coleman"
      src="https://avatars2.githubusercontent.com/u/132554"
    />
    <Avatar
      size="medium"
      username="Tom Coleman"
      src="https://avatars2.githubusercontent.com/u/132554"
    />
    <Avatar
      size="small"
      username="Tom Coleman"
      src="https://avatars2.githubusercontent.com/u/132554"
    />
    <Avatar
      size="tiny"
      username="Tom Coleman"
      src="https://avatars2.githubusercontent.com/u/132554"
    />
  </div>
</Story>

### Default Values

When no image is supplied to the `src` prop, Avatar displays initials.

Avatar should be used sparingly in situations without access to images.

<Story name="initials">
  <div>
    <Avatar username="Tom Coleman" />
    <Avatar username="Dominic Nguyen" />
    <Avatar username="Kyle Suss" />
    <Avatar username="Michael Shilman" />
  </div>
</Story>

### Loading

The loading state is used when the image or username is, well, loading.

<Story name="loading">
  <div>
    <Avatar size="large" loading />
    <Avatar size="medium" loading />
    <Avatar size="small" loading />
    <Avatar size="tiny" loading />
  </div>
</Story>

<ArgsTable story="loading" />

### Playground

Experiment with this story with the Controls addon in the Canvas tab.

export const Template = (args) => <Avatar {...args} />;

<Canvas>
  <Story
    name="controls"
    args={{
      loading: false,
      size: "tiny",
      username: "Dominic Nguyen",
      src: "https://avatars2.githubusercontent.com/u/263385",
    }}
  >
    {Template.bind({})}
  </Story>
</Canvas>

And if you check your Docs tab you'll get this:

If you check your Storybook you'll see that you can still see your Stories being shown with the added bonus that in the Docs tab you get a richer experience and so on. You're then told to introduce the following:

<ArgsTable of={Avatar} />

Which yields this:

This change will allow you to expand the documentation (Docs tab) with the information you get from the props. Allowing you to further document for anyone that consumes the Design System being built.
But here's the thing if you check the Canvas tab you run into the issue, almost all your stories show this:

design-systems-avatar-mdx.mp4

See the controls story? You get your controls working as they were when you're using JS with Args. A sui generis way of seeing this is the following:

• When Storybook loads the standard story, it will see that is a Story but it's not using args, just a component with the prop's values being injected directly and Storybook treats that Story as it was written as such in JS:

export const standard = () => (
  <Avatar
    size="large"
    username="Tom Coleman"
    src="https://avatars2.githubusercontent.com/u/132554"
  />
);
)

• But when it reaches the controls story it will treat that story the same way as the Standard story I've mentioned initially. Allowing you to manipulate your story as you would do as if it was a JS based story. But there's one thing missing in that story and that's what @shilman mentioned in his comment. You have Controls but a story that is not well documented.

Adding this change to that you get the "best of both worlds" ( pardon the bad pun).

<ArgsTable story="controls" />

You can use Controls in the Canvas and you get a richer experience and better documentation in the Docs Tab. Which you can expand to your needs.

All in all the scope of that particular section is the following:

• You can use MDX based stories and get the same experience as if you were writing them in JS.
• You can customize and structure your documentation/stories as you see fit as the example is mentioning a couple of ways you can do that.

Sorry for the long description but it seems that was in order and I hope I was able to shed some light on the subject and give you a bit more context. Let us know of any further issues you encounter.

[KenACollins]

Hi @jonniebigodes,

Thanks for the video you inserted into your explanation as you navigated through the stories from the left navigation while having the Controls panel up.

At first, I was wondering where you were going with this when you were showing the "This story is not configured to handle controls" message over and over, but then you clicked on a Controls story in the left nav bar. I had not noticed that before! Sure enough, I get the same results as you.

Edit: I thought there can be only one controllable story in a *.stories.mdx file and it had to be named "Controls". I now realize I was mistaken. Although it doesn't make any sense to have two controllable stories for the same component, I found it can be done by adding another one within the <Canvas> ... </Canvas> tags as shown below.

<Canvas>
  <Story name="Thing" args={{
    loading: false,
    size: "tiny",
    username: "Dominic Nguyen",
    src: "https://avatars2.githubusercontent.com/u/263385"
  }}>
    {Template.bind({})}
  </Story>
  <Story name="Thing2" args={{
    loading: true,
    size: "large",
    username: "Ken Collins",
  }}>
    {Template.bind({})}
  </Story>
</Canvas>

<ArgsTable story="Thing" />
<ArgsTable story="Thing2" />

But for stories I don't set up this way I will still see the not configured to handle controls warning. So I have the option -- hide the Controls panel and only let the developer play with the controls of one story from the Docs tab, or show the Controls panel knowing that many of the stories will show a warning. Okay, I understand.

One last comment. I don't see a difference between the args table being loaded as...

<ArgsTable story="loading" />

...versus:

<ArgsTable of={Avatar} />

But I am not too concerned about it so don't feel like you need to respond.

[KenACollins]

@jonniebigodes or @shilman -

I think this is the final question I have regarding controls! Bear with me. New topic. If this is not possible now, maybe it can be a feature of a future release.

I know that the ability to add or exclude arguments within controls has been recently added to the 6.2.0-BETA release through pull request 13898 which you, @shilman, informed me of and helped get that beta release installed.

Has any thought gone into making it possible to show all prop types defined in a component in the args table on the Docs tab but a lesser, filtered list within the args table that is used for controls?

Here is my conundrum. I have components, as I am sure every developer has, that accept a bunch of arguments that are not capable of being manipulated within the Storybook UI. There could be the function I pass for the onClick event or an image file local to the file structure. From a documentation perspective, on the Docs tab I must explain all the possible arguments that can be passed to the component but the user cannot alter all of them in the controls story. Ideally, I would like to just show the arguments in the controls args table that can be manipulated on the screen.

For example, I have a Button component that has 14 arguments but some are functions (onClick, onMouseEnter, etc.), there is an icon file parameter, a QA testing parameter, etc. But things like changing the button label and setting the state from enabled to disabled or from a primary button to a secondary button can be done in the Storybook UI. Rather than overwhelm the user by listing 14 arguments, most of which are not applicable to controls, it would be nice to only show the properties that can be altered to achieve a new button state while at the same time being able to document all possible arguments up above in the MDX file.

[shilman]

If you use MDX or a custom DocsPage you can pass a custom filter as a prop into the <ArgsTable> component. The controls addon panel will use the controls.{include,exclude}. We might need to fix the code to make these two things work together smoothly on the MDX side, but I'm open to that.

[KenACollins]

Hi @shilman,

Isn't DocsPage something that refers to *.stories.js files? Given that I am moving on to *.stories.mdx files it would not be something I would be concerned with, right?

I have to say that the Doc Blocks documentation gets confusing. It keeps floating in and out of teaching MDX. It teaches a concept, then it is followed by a section with a MDX heading and I conclude I just wasted time reading the previous section. Then it teaches some other concept and then it has another MDX section after that.

It would be better if the documentation was split across two pages, one for the *.stories.js holdouts and another for us adventurous *.stories.mdx pioneers. Since I am starting fresh with Storybook, I have no legacy code to support so I just want to use version 6, not 5, and I don't want to learn about storiesOf() syntax or *.stories.js if there is a better way with *.stories.mdx.

Anyway, you got me thinking that there is a way to accomplish my goal of listing every prop type in the Docs tab args table but show only a filtered list of props for the controls story and you are right. I was able to do this as shown below. I just had to figure out the double curly braces approach to adding parameters to the controls story.

export const Template = (args) => <Button {...args} />

<Canvas>
  <Story name="CheckMeOut" args={{
    color: COLORS.PRIMARY,
    children: "Change This Text",
  }}
  parameters={{
        controls: { 
            exclude: [
                'className',
                'onClick',
                'onMouseEnter',
                'onMouseLeave', 
                'dataSelenium',
                'type',
                'tabIndex',
                'icon',
                'hoverIcon',
            ]
        },
    }}
  >
    {Template.bind({})}
  </Story>
</Canvas>

Thanks!