Storybook: Move `addon-info` into addons panel

[shilman]

Why

Currently addon-info shows component info in the preview pane alongside each story. This behavior differs from typical addons, that display their info in the addons panel.

Modifying the behavior to use the addons panel would make the addon available for react-native. It also means that addon-info can benefit from addon panel UI improvements in future versions of storybook-ui.

EDIT: It would also make the addon compatible with storyshots

What

• [ ] modify the info addon to use the addons panel
• [ ] update docs

[mthuret]

Maybe it would be better to split the addon-info features to be displayed in different panel? One for the description, one for the source, one for the propTypes? What do you think?

[Gongreg]

If you are thinking about splitting it into separate panels it starts to sound like separate addons which already exist.
There are propTypes addon, description addon, source addon.

[bigassdragon]

@shilman is this a new addon?

[shilman]

@bigassdragon i'm proposing modifying the existing addon, but it could also be a separate addon. it seems like there are a bunch of addons that do similar things in this space, so it would be nice (i think!?) to consolidate and remove duplication of work...

[bigassdragon]

@shilman is there a link to the existing addon we are talking about?

I tried looking for it but I have never seen or heard of addon-panel, I would not mind having any kind of merge just need to know what it would look like and if we can make and even more awesome addon that could incorporate a lot of slick things to make documentation better.

[shilman]

@bigassdragon sorry for the confusion. hopefully this clarifies?

[bigassdragon]

@shilman OOOOHHHHHHH. I definitely get it now. yeah I use those.

However I thought there was an addon that already does a panel view of the documentation.

I think you might be trying to do something like this: https://github.com/mihalik/storybook-addon-markdown

However the difference is it would use the addon-info plugin so you do not need to create a bunch of markdown files.

Is that correct?

[shilman]

@bigassdragon AFAIK:

• addon-info looks at proptypes etc. to create an API description semi-automatically
• addon-markdown accepts generalized markdown?

I think this should all be simpler, cleaner, and compatible with the rest of the plugins.

[bigassdragon]

@shilman correct, I was just making the comparison that you want the docs to show up in one of the panels in your picture above.

[bigassdragon]

@shilman I think this idea would be awesome. I kind of thought it would be cool to have the option to have it in the panel and if we put it in the panel let's provide the user the chance to remove the blue button that shows up where you switch between documentation and example.

I think it would be really slick if we can have the ability to show the docs in a panel and also the configuration to hide the blue button because that could be redundant to show.

[Gongreg]

@shilman:

Right now there are:

Plugin for documentation: https://github.com/Gongreg/react-storybook-addon-docgen
Plugin for usage: https://github.com/Kilix/storybook-addon-jsx , https://github.com/Gongreg/storybook-usage

As far as I understand the info addon is kinda like a wrapper for these two.

I think it would be good to have simply two separate addons inside monorepo, so users could choose to op out from using one of the addons if they want to.

And then the info addon wouldn't be necessary at all.

[shilman]

Thanks @Gongreg that makes a lot of sense. I think part of the problem is that addon-info came first and is mentioned all over the place in the docs, so lots of people use it and don't necessarily even know about the replacements. It's a little messy/confusing right now, but I'm sure we can come up with a clean solution here.

[shilman]

Here's another reason this should happen:

https://github.com/storybooks/storybook-addon-a11y/issues/11

[ranneyd]

+1 really wish it worked this way

[shilman]

Furthermore, we should get rid of the addWithInfo(title, description, story) API because it makes it impossible for addons to interoperate. Instead, we can use the pattern used in other addons (e.g. notes).

Either:

storiesOf('MyComponent', module)
  .addDecorator(withInfo(title, description))
  .add('foo', () => <MyComponent />)
  ...

Or something like:

storiesOf('MyComponent', module)
  .add('foo', () => <WithInfo title='my title' description='my desc'><MyComponent /></WithInfo>)

[thearegee]

+1 for the first option

[tmeasday]

@shilman yes this seems like a very easy thing to change and a good practice to establish. A lot of addons out there follow the addWithX approach probably because they are just imitating the canonical info addon.

[tmeasday]

I looked briefly into replacing addon-info with the docgen and jsx addons that @Gongreg mentioned above. The issues I ran into (which are probably why he forked them) are:

1. The docgen plugin doesn't seem to have been updated for 3.0 yet, and doesn't quite work.
2. The JSX plugin requires the use of .addWithJSX() (strictly speaking this isn't a step backwards). Still it would be good to allow the decorator pattern @shilman mentioned above.

However these issues are probably easily solved. I am happy to help with updating these packages and bringing them into core alongside deprecating the info addon if the respective authors would like that to happen (@wcastand, @mihalik?)

[wcastand]

Hi, I wouldn't mind putting jsx into the monorepo but i'm not okay with the WithNotes pattern.
Addon for panels shouldn't be in my stories.
We know this is a issue right now and we discussing on how to change the addon API to allow this kind of patterns and avoid the overwrite of .add()

i use the addWithJSX because i need access to the storyFn() to create the JSX and i'm not okay with the WithNotes pattern :)

[tmeasday]

@wcastand -- do you mean you don't like the fact that the story gets "polluted" with the decorator?

Is there a specific reason you don't like it (i.e. does it stop you doing something?), or is it more a matter of style? (I don't really like it either)

I am looking at this from a short-term perspective. The issue with .addWithX() is you can only use one addon that uses it! This is a problem for adoption of addons.

Also the nice thing about the decorator pattern is you can apply it to a whole chapter or even all stories in a natural way using an API that users are familiar with.

My slightly longer term suggestion is to solve #993 and pass options in the .add() call. This avoids the decorator problem.

A new addons API would be good! But it seems a bit further off.

[tmeasday]

(It is of course possible to offer both APIs from the package)

[Gongreg]

@tmeasday You are totally right, I forked them because they were not updated.

@wcastand Why can't you reach storyFn() while using addDecorator() pattern?

The addon-usage plugin works this way.

The problem with addDecorator is that the order is important.
That allows to use intersting combinations of addons, but problem is that addons pollute storyfn().

So if user adds addDecorator(WithJSX) as a first addon, you will get same storyFN() as using addWithJsx().

[wcastand]

It's mostly a matter of style. separation of my stories and storybook's helpers(addons, etc)
I don't mind decorators at all, i use them for thing like Redux, Fela. But decorators are for app related needs.

In my opinion, they shouldn't be used for storybook's panels.
I won't change the api of the addon JSX for a temporary fix that breaks the plugin for older version.

For solutions, like i said, i made a proposition with decorators and middleware.

@Gongreg i can access storyFn from decorators but storybook's addons are not their use in my opinion. It's what confuse people about addon in storybook. They shouldn't be in the stories at all.

[tmeasday]

I won't change the api of the addon JSX for a temporary fix that breaks the plugin for older version.

Well, like I said it is possible to offer both APIs, so it's not a breaking change.

[Gongreg]

@wcastand , so ok, we can both agree that there are problems with current addons implementation.
But having to explicitly tell in every story that you have to use your addon (addWithJsx) while limiting other addon usage is not a solution too :) Also your api doesn't allow me to say "use this addon in all the stories and I don't care about it at all anymore".

At least having as an option, to add it as a decorator would be a nice step forward.
Then you could definitely add it to monorepo, since it would be compactible with other plugins.

[wcastand]

English is not my native langage so i'm sorry if i sound "bad", it's not the case and i don't mind discussing it (just in case :)).

@tmeasday right now, i don't think it's a good idea but if someone want to make that happen and do a PR i don't mind helping him and publish it :)

@Gongreg It's not a solution right now. That's why i started to bring the need to rework the addon API in the first place.
the API proposal that i made allow storybook wide decorators and middleware (so you can configure a redux decorator and a JSX middleware for all of your stories) Draft

Why i think it's a bad idea to make my addon and all the addon using the decorator pattern as a temporary fix for storybook ?
Because the temporary fix will probably become the permanent solution if everything work even if it means blending decorator specific to your app et decorator specific to storybook panels(middleware).

I prefer to have a none perfect solution for a while and work on a rework so we go on good basis instead of making something work right now and never change it because it works.

it's only my opinion and i get it if people doesn't agree but i work like this:

• make it work
• make it right
• make it fast

For me storybook is 'make it work' (it works really well :D). Putting storybook in a monorepo, using a proper namespace is a way forward the make it right and a rewrite ( at least partial ) is for me the next step.

The rework of the Addon API is needed (in my opinion) because the addon API doesn't fit the use and like everyone here said : it's not clear and well defined what is a decorator or how do i make a storybook panels without polluting my stories or overwrite.add (not possible if you want to access storyFn).

I think we can agree on the api and make it quite quickly, it probably won't be perfect but we can iterate.

In short, if someone wants to make JSX works with decorators i'll help him and i'll add it to the package as a 'temporary solution' but i won't do it myself because i think it's not a good idea until we figure it out the new addon API.

i'm on storybook's slack if you want to discuss with me and avoid pollute this issue with not so related content.

[tmeasday]

I'm happy to contribute a PR. I'll send it through in the next couple of days.

I think generally I agree with you @wcastand except on one point; I would argue that .addWithX doesn't "work" (IMO) and we need to resolve that problem before we make it right :)

[lucasmotta]

What about having an official addWith API, that allows you to compose different addons together:

Single Addon

story.addWith(info('Description of this component for the info addon'))(
  () => <Component />
)

Composes Multiple Addons

story.addWith(
  info('Description of this component for the info addon'),
  jsx('This is for the JSX addon')
)(() =>
  <Component />
)

Or even having that logic implemented on the existing add method.

[tmeasday]

@lucasmotta it's interesting because this is very nearly possible with the current API, you could have

story.add('name',
  info('Description of this component for the info addon')(
    jsx('This is for the JSX addon')(
      () => <Component />)));

In the current API. The only thing I would propose is to enable moving the decorators together (which ends up being similar to your idea):

story.add('name', () => <Component />, {
  decorators: [
    info('Description of this component for the info addon'),
    jsx('This is for the JSX addon'),
  ],
});

(This way treats the decorators a little less specially and allows room to grow and add other options later).

[IanVS]

This is an old issue, and I'm not sure exactly where it stands or if it's still planned to be changed. But as a new storybook user, I have to say that I find the current behavior very useful. I am implementing storybook as a kind of "styleguide", and this addon allows me to easily create a "page" for each component with some vital information like a generic description, example code, and prop types.

I only bring this up to provide a voice in support of keeping this in the preview area. I love being able to tweak knobs and see how the example component updates, while also seeing the rest of the info that this add-on provides (without having to toggle between add-on tabs).

[waynebrantley]

Perhaps it should be optionally in a tab.
As it is, if you use storyshot with or without images, this addon has to be disabled.
If not, any change to your docs causes a 'change' as the snapshot has all the info in it.

[ndelangen]

@IanVS On my roadmap is to implement a docs-view for component for your styleguide needs, that is out of the preview iframe and uses the stories you write to show examples.

This merger will make everyone happy I hope because:

• component stories will be pure, and screenshotting / diffing them becomes easier and more meaningful
• users can choose between "reading how to use a component" and "working on a component in isolation".

I'm currently working on a navBar for storybook, after that's done, we will release 4.0.0, and then the docs-view is top priority. I'm already 'recruiting collaborators and talking to users so I know how the feature should be shaped'. I plan to use mdx and some auto-generation combined.

Because it will be out of the preview/iframe, this solution will be framework-agnostic whereas the info addon is react-specific.

I think this move will pretty much deprecate the info addon. Let me know if you have questions.

[charrondev]

Has there been any additional movement on this? I'd be interested in helping out, but I'd want to get some clear acceptance criteria before sinking time into it.

Edit: It seems there is an issue open. I'll cross-link it. https://github.com/storybooks/storybook/issues/4341

[hipstersmoothie]

Definitely needs some docs for using the pure docgen plugin. The only one i could find for typescript I could not get to work. Whereas the info plugin works fine

[hipstersmoothie]

I've published storybook-addon-react-docgen. It uses the docgen information just like the info addon but places the information in a Props tab in the the addons panel. It works quite well with the notes notes-addon

https://www.npmjs.com/package/storybook-addon-react-docgen

[JamesIves]

@shilman I know this is an old issue, but is there plans to implement this? I'm running into this problem where the addon info button is blocking parts of my component preview and would love for this data to appear in the addons panel.

[shilman]

@jamesives Yeah it's been on the back burner for a long time but I have a prototype running and plan to release it in 5.1. we're putting a focus on component documentation now that 5.0 has been successfully released.

Note: it may be a new add-on that supercedes addon-info

[JamesIves]

Excellent! Is there an ETA for that release?

[shilman]

Hopefully we can get that feature available in prerelease by mid-April and a solid first cut by May

[avrilpearl]

@JamesIves --> you can define this in the configuration of the info addon as well: e.g:

addDecorator(
    withInfo({
      styles: {
        button: {
          base: {
            fontFamily: 'sans-serif',
            fontSize: '14px',
            fontWeight: '500',
            display: 'block',
            position: 'fixed',
            border: 'none',
            background: '#14558f',
            color: '#fff',
            padding: '5px 15px',
            cursor: 'pointer',
          },
          topRight: {
            bottom: 0,
            right: 0,
            top: 'unset',
            borderRadius: '5px 0 0 0',
          }
        }
      }
    })
  );

[JamesIves]

Thanks @avrilpearl ! This is a great workaround.

[inspiratweb]

Do we have any news about this @shilman?

[shilman]

@inspiratweb Addon-docs has been in alpha for over a month and is nearing beta. It solves a ton of problems with addon-info and adds a bunch of new features as well.

Read about it here: https://medium.com/storybookjs/storybook-docs-sneak-peak-5be78445094a

And get started here: https://docs.google.com/document/d/1un6YX7xDKEKl5-MVb-egnOYN8dynb5Hf7mq0hipk8JE/edit?usp=sharing

[shilman]

FYI addon-info is being superceded by addon-docs, which fixes a bunch of bugs and is easier to maintain. It’s reached release candidate (RC) status and will be properly released soon. Please give it a try! https://medium.com/storybookjs/storybook-docspage-e185bc3622bf

[shilman]

This is the most up-voted issue in the Storybook repo and I'm closing it. If anybody wants to pick this up, feel free to create a PR.

For those who care, here's the full explanation:

• addon-docs is the successor to addon-info. For the past few months, I've been redirecting all addon-info-related issues to addon-docs.
• addon-docs contains a superset of addon-info's features, and also contains many bugfixes.
• addon-docs should be better than addon-info in every way. If you disagree, please feel to file an issue, and we'll do our best to fix it. It should be an attractive, painless upgrade, and if it's not it means that we're doing something wrong.

Thanks for using addon-info; please upgrade to addon-docs today!

[DiegoBM]

It would be wise to redirect from the _Info_ addon to the _Docs_ addon in the _Info_ page on Github, or warn about the deprecation in some sort of way there, just so that people know that the _Info_ addon is not being supported anymore and that they should use _Docs_ instead, and avoid wasting time trying to make it work.

[shilman]

@DiegoBM done. thanks!