Addon-docs: support interactions with existing addons

[shilman]

From @trevoreyre :

Any thoughts on how addon-docs would interact with other addons? I notice right now when you switch to the docs tab, the addons panel goes away, as well as any other tabs you have enabled through other addons. I think it would be useful to still be able to interact with other addons, like seeing actions as you're clicking through things in the docs, like you would in a story, or changing themes or context variables and seeing all of the stories in the docs update.

It's tricky because all the addons assume that there is only one story currently visible, and in docs there are potentially many. We have a proposal for "knobs v2" to address this for knobs, but nothing planned to address it in general. How we deal with it generally is open for discussion!

[github-actions]

Automention: Hey @elevatebart @JeroenReumkens, you've been tagged! Can you give a hand here?

[rwieruch]

Just set up Docs today. Wonderful work that you have done there!

I would love if the old "Canvas" Tab would disappear and the new "Docs" Tab would be the one and only. Then the Tabbar could be removed and would declutter the UI. However, then it would need to be possible to integrate all the other addons (Knobs etc.) in the "Docs" Tab.

Since it wouldn't be possible anymore to open a single story via the left hand-side navigation, browsing between stories of one component should scroll you up and down in the "Docs" Tab to the related story.

Hope my input helps here. Thanks again for all your hard work!

[shilman]

Thanks @rwieruch! 🙏

You can get part of the behavior you're looking for by running start-storybook or build-storybook with the --docs flag. This is still WIP, and will be getting some improvements in the next few days, but should give you a picture of what's to come.

Supporting all the addons is a longer-term project though. So until we figure that out, it's an either/or situation. 😺

[leoyli]

Agreed. From what I've seen, there are isn't good agreement on how to structural an addon at first place, and potentially multi-framework support will makes the situation more challenging...

[techieshark]

I wonder how people handle knobs + docs addons.

Specifically I'm wondering what folks do about the fact that all the "knobbed" component properties show up in the "show code" part of addon-docs. Presumably, doc-readers aren't interested in the knob functions (boolean('disabled', true) etc).

[shilman]

@techieshark There's a wonderful proof of concept from @JeroenReumkens that adds knobs to the prop table in docs mode. I'm not sure how it would relate to Storybook's existing knobs setup. :(

[techieshark]

@shilman that would be amazing - that's pretty much how I use knobs right now (one story for all the knobs, then specific stories to doc particular use cases). @JeroenReumkens I'd be keen to check that out.

[mmartinsky]

This would be really helpful for using addons like https://github.com/ticketmaster/storybook-styled-components for swapping library S-C/Emotion themes (not global Storybook theme).

[shilman]

@mmartinsky check out https://www.npmjs.com/package/@storybook/addon-contexts

[fabiradi]

Canvas and Docs both deserve their space and both have their own use cases. I wouldn't generally try to mangle them together.

Docs: Before Docs, I used the first Story to give an overview, explain a little bit about the component. The following stories give examples and show specific situations. The last story has interactions (knobs) to tweak the component in various ways. Docs now combines these views in a very nice and clean way (but without any addons).

Canvas: There are plenty of addons that work in canvas mode on a deeper, sometimes technical, level. I wouldn't want them to appear in Docs mode.

🤔 Just an idea ...

I still find it a little confusing, to switch between Docs/Canvas in the tab bar. It is not very obvious to new readers. I had to explain it to a good number of people. On top, selecting a story in the navigation does not always have an effect (story already scrolled into view, etc.)

Maybe the navigation could work this way:

• The story kind (CSF default export) opens Docs view. Currently, it opens the first story – which is still better than before, when it did not open anything.
• Each story opens the story in Canvas mode. This seems to be a more obvious target, if the user clicks on a specific story.

This would enable:

• 🎉 Contexts in Docs mode applied to each story panel (themes, i18n, backgrounds ...). Addon-context is a great add-on that works much better than many panel-based addons.
• 🖼️ Viewports for each story panel could actually work quite well.
• 💨 Getting rid of the switcher Canvas/Docs in the tab bar would create cleaner, consistent look.

I'm really missing Contexts in Docs mode. At least with React, it should be possible to set a context and have it applied to each story panel (Themes, i18n, ...)

🤷‍♂️ I'm not sure if any of this makes sense. These are just my experiences and thoughts.

[shilman]

@fabiradi great feedback. still chewing on this -- i think it's going to take some time to resolve

[sanchez]

Knobs and Actions could be added on a per story basis, so on the docs page you have a "Controls" and "Actions" button the bottom left (similar to the code button on the bottom right). Triggering this buttons unfolds a small section where the user can use Knobs and Actions as they would in the past (similar again to how the code snippet folds out)

[shilman]

Nice @sanchez 😂

[khantopa]

I wonder how people handle knobs + docs addons.

Specifically I'm wondering what folks do about the fact that all the "knobbed" component properties show up in the "show code" part of addon-docs. Presumably, doc-readers aren't interested in the knob functions (boolean('disabled', true) etc).

Looking for the same question

[rblock-aw]

Knobs and Actions could be added on a per story basis, so on the docs page you have a "Controls" and "Actions" button the bottom left (similar to the code button on the bottom right). Triggering this buttons unfolds a small section where the user can use Knobs and Actions as they would in the past (similar again to how the code snippet folds out)

I was thinking exactly the same. There are two alternatives imho.

• A single knobs/action/... pane at the bottom of the window (just like in the canvas mode) and make the contents of those dependent on the selected story (if necessary), defaulting to the primary story if the user didn't select a particular story. The knobs need to be dependent on the story 'in focus', but I can imagine it is of lesser important for the action pane to do so (being able to scroll between the action history across the different stories in the current docs, but it would be nice to see what action events belonged to which story, which can be easily achieved by triggering a standardised action named 'switched to story XYZ' upon selecting a new story. I think the first suggestion is better than this one, but this alternative might be a little easier to integrate and maybe a little more performant as well (though this depends entirely on the implementation of course).
• Like mentioned in Addon-docs: Add Controls ("knobs") support to Props #6639: integrate the knobs with the property table and integrate this with the primary story. In a perfect world, this could even be defaulted by allowing every users to change 'default' value of the props / slots (I'm using Vue.js) according to the detected type. I realise that this perfect world scenario won't be achievable all of the time because (what if there are no sensible defaults etc.), but seems like a nice goal still.

[bolora]

I wonder how people handle knobs + docs addons.
Specifically I'm wondering what folks do about the fact that all the "knobbed" component properties show up in the "show code" part of addon-docs. Presumably, doc-readers aren't interested in the knob functions (boolean('disabled', true) etc).

Looking for the same question

I have yet to see a solution for this. It honestly makes copy code USELESS. Can someone please answer this question?

[josephfusco]

@bolora You can explicitly set the code that goes in the show code panel by using Preview's mdxSource prop.

I'm not sure what the code would look like for the CSF or storiesOf formats however this is what it would look like for the newer MDX stories format:

<Preview mdxSource={`
  <div class="form-group">
    <label for="input-1" class="sr-only">...</label>
    <input id="input-1" type="text" class="form-control" placeholder="...">
  </div>
`}>
  <Story name="Text Input" height="100px">
    {`
      <div class="form-group">
        <label for="input-1" class="sr-only">Label text</label>
        <input id="input-1" type="text" class="form-control" placeholder="placeholder text">
      </div>
    `}
  </Story>
</Preview>

[jack-bliss]

Sincerely hope this is still being worked on - the --docs option is kinda useless without support for other addons! I think for the knobs/actions case, what @sanchez suggested is perfect, just make them per-story! Also the same can be said for viewports, just let me declare a default viewport using the normal parameters prop and have the inline story render in that viewport. This would make --docs my default option! For now i have to add "click the canvas tab above" for all my mobile stories.

[shilman]

@jack-bliss if it's useless to you, don't use it

[shilman]

@fabiradi finally getting back to this issue. addon-contexts is being replaced by addon-toolbars, which is docs-compatible. please take a look and let me know what you think: https://github.com/storybookjs/storybook/tree/next/addons/toolbars

[gaurav5430]

I can see that this is being worked on, which is great :)

Just wanted to confirm if it is possible yet to show a story inside a particular viewport when in the Docs view ?

for example, I have set the default viewports for some of my stories, but that disappears when i switch to the docs page. In this particular case, i don't really need the viewport button in the docs page, i just need a way/workaround to show the story in a particular viewport when rendered inside the docs page

[shilman]

@gaurav5430 not currently. we've been making progress though and I think we can probably get it into 6.1

[gaurav5430]

@shilman that would be great :)

Meanwhile, do you think there is a convenient workaround to achieve this?

just thinking out loud, i can possibly render the story inside an iframe and set the size of the iframe to whatever viewport i want, so that it displays as expected in the docs page (but then i would have to forego using the actual viewports addon and default viewport on the canvas view as well)

[floustao]

@bolora You can explicitly set the code that goes in the show code panel by using Preview's mdxSource prop.

I'm not sure what the code would look like for the CSF or storiesOf formats however this is what it would look like for the newer MDX stories format:

<Preview mdxSource={`
  <div class="form-group">
    <label for="input-1" class="sr-only">...</label>
    <input id="input-1" type="text" class="form-control" placeholder="...">
  </div>
`}>
  <Story name="Text Input" height="100px">
    {`
      <div class="form-group">
        <label for="input-1" class="sr-only">Label text</label>
        <input id="input-1" type="text" class="form-control" placeholder="placeholder text">
      </div>
    `}
  </Story>
</Preview>

This is awesome, thanks for sharing @josephfusco, I could not find it in the documentation.

[electriccode]

@shilman that would be great :)

Meanwhile, do you think there is a convenient workaround to achieve this?

just thinking out loud, i can possibly render the story inside an iframe and set the size of the iframe to whatever viewport i want, so that it displays as expected in the docs page (but then i would have to forego using the actual viewports addon and default viewport on the canvas view as well)

I also have the same use case. Right now <Story /> from docs addon doesn't accept width attribute so this is not possible using <Story />. Though as a workaround, you can do this inside MDX document (MDX supports HTML as MD supports HTML as well).

<h2>Tablet</h2>
<iframe width="700" height="500" src="/iframe.html?id=story-id&viewMode=story"></iframe>
<h2>Mobile</h2>
<iframe width="400" height="500" src="/iframe.html?id=story-id&viewMode=story"></iframe>

As you can see you can specify any width and height in iframe.

To get the iframe url, go to the story panel and click share button (right after fullscreen button) on top right which will open it in a new tab. Copy URL from there and make it relative.

[florian-milky]

If you wrap it into <Preview> or <Canvas> you can apply width style there:

<Preview style={INITIAL_VIEWPORTS.iphone6.styles}>
  <Story
    name="iphone6"
    parameters={{
      docs: {
        inlineStories: false,
        iframeHeight: INITIAL_VIEWPORTS.iphone6.styles.height,
      },
      layout: 'fullscreen',
      viewport: {
        viewports: INITIAL_VIEWPORTS,
        defaultViewport: 'iphone6',
      },
    }}
  >
    {Template.bind({})}
  </Story>
</Preview>

[kremerd]

Is this topic still open for discussion?

I maintain an addon that does not depend on the currently visible stori(es) at all, but only interacts with global state (to switch themes). Other addons like the official "Actions" addon might be easily extendable to support a list of stories rather than a single story. It would be cool to add support for such usecases eventually.