checkfront/react-storybook-addon-chapters

📒 Showcase multiple React components within a story

⛔ [DEPRECATED] This addon is no longer maintained and is now considered deprecated in favour of Storybook's native nesting and component hierarchy. We recommend Storybook version 6 be used instead.

React Storybook Chapters Addon

React Storybook Chapters addon allows showcasing of multiple components within a story by breaking it down into smaller categories (chapters) and subcategories (sections) for more organizational goodness.

Using the addon, a story can consist of multiple chapters and a chapter consists of multiple sections. Each section can render a block of code, which typically used to showcase one component or a particular state of a component.

Chapters can be used to group related components together, or show varying states of a component. Each chapter comes with a Chapter Title, Chapter Subtitle, Chapter Info and a list of Sections. Simply omit any of them to hide them from rendering.

Each section comes with a Section Title, Section Subtitle, Section Info.

This addon was modified from react-storybook-addon-info and uses some of the component code from there.

Usage

Install the following npm module:

npm install --save-dev react-storybook-addon-chapters

Then set the addon in the place you configure storybook like this:

import React from 'react';
import { configure, setAddon } from '@storybook/react';
import chaptersAddon from 'react-storybook-addon-chapters';

setAddon(chaptersAddon);

configure(function () {
  ...
}, module);

To turn off the default styles add:

setDefaults({ sectionOptions: { useTheme: false } });

All rendered components have a specified class. With the 'useTheme' set to false you should have no problem styling your chapters.

Then create your stories with the .addWithChapters API.

import React from 'react';
import Button from './Button';
import { storiesOf } from '@storybook/react';

storiesOf('Addon Chapters')
  .addWithChapters(
    'Story With Chapters',
    {
      subtitle: <Optional story subtitle>,
      info: <Optional story info>,
      chapters: [
        // List of chapters. Refer to Configuration Format section.
        {
          title: <Optional chapter title>,
          subtitle: <Optional chapter subtitle>,
          info: <Optional chapter info>,
          sections: [
            // List of sections.
            {
              title: <Optional section title>,
              subtitle: <Optional section subtitle>,
              info: <Optional section info>,
              sectionFn: () => (<Button label="My Button" onClick={() => { alert('Hello World!'); }}/>),
              options: {
                showSource: true,
                allowSourceToggling: true,
                showPropTables: true,
                allowPropTablesToggling: true,
              },
            },
            ...
          ],
        },
        ...
      ]
    }
  );

Have a look at this example stories to learn more about the addWithChapters API.

Global options

To configure default options for all chapter sections (section.options), use setDefaults in .storybook/config.js .

import React from 'react';
import { configure, setAddon } from '@storybook/react';
import chaptersAddon, { setDefaults } from 'react-storybook-addon-chapters';

// optionally override defaults
setDefaults({
  sectionOptions: {
    showSource: true,
    allowSourceToggling: true,
    showPropTables: false,
    allowPropTablesToggling: true,
    decorator: story => (<div>{story()}</div>),
  }
});
setAddon(chaptersAddon);

configure(function () {
  ...
}, module);

Configuration Format

Story

Key	Description	Type	Default
subtitle	Story subtitle	String	-
info	Additional information for the story	String (markdown)	-
chapters	An array of Chapter objects	Array	-

Chapter

Key	Description	Type	Default
title	Chapter title	String	-
subtitle	Chapter subtitle	String	-
info	Additional information for the chapter	String (markdown)	-
sections	An array of Section objects	Array	-

Section

Key	Description	Type	Default
title	Section title	String	-
subtitle	Section subtitle	String	-
info	Additional information for the section	String (markdown)	-
sectionFn	A function that returns a React component to be displayed	Function	-
options	A configuration object for this section. Refer to the next few rows for the keys	Object	-
options.showSource	Display the component's source	Boolean	True
options.allowSourceToggling	Allow showing/hiding of the component's source	Boolean	True
options.showPropTables	Display the component's propTypes	Boolean	False
options.allowPropTablesToggling	Allow showing/hiding of the component's propTypes	Boolean	True
options.decorator	An optional decorator function that will be used for rendering the component in section	Function	-

The FAQ

Components lose their names on static build

Component names also get minified with other javascript code when building for production. When creating components, set the displayName static property to show the correct component name on static builds.

react-storybook-addon-chapters's Issues

Allow toggling of source for individual sections

It's something that react-storybook-addon-info has but we yet to support:

How do I keep markdown's default theme

help me,please.
How do I keep markdown's default theme.
i use info:markdown,but it show not default theme

React v16 still not supported?

Based on the closed issue, #16, I thought React v16 was supported, but I just received the following exception when trying to start storybook after installing react-storybook-addon-chapters v2.0.0 from npm:

ERROR in ./node_modules/markdown-to-react-components/src/CodeComponent.js
Module not found: Error: Can't resolve 'create-react-class' in 'D:\dev\H-D\revival-tis\te-revival\node_modules\markdown-to-react-components\src'
 @ ./node_modules/markdown-to-react-components/src/CodeComponent.js 2:23-52
 @ ./node_modules/markdown-to-react-components/src/index.js
 @ ./node_modules/react-storybook-addon-chapters/dist/utils/info-content.js
 @ ./node_modules/react-storybook-addon-chapters/dist/components/Story.js
 @ ./node_modules/react-storybook-addon-chapters/dist/index.js
 @ ./.storybook/config.js
 @ multi ./node_modules/@storybook/react/dist/server/config/polyfills.js ./node_modules/@storybook/react/dist/server/config/globals.js (webpack)-hot-middleware/client.js?reload=true ./.storybook/config.js

It appears that markdown-to-react-components hasn't been supporting React since 15.6.1 and Marksy is the replacement.

@storybook/react is v3.2.14.

Specify default config for sections

It will be nice to allow users to override the default config of the sections, which is currently: { showSource: true, showPropTables: false }

useTheme doesn't work for storyTitle and ChapterTitles

useTheme for story titles has no effect at all.

My Problem : I want to customize the styles of one of the story's title. So I expected that

storiesOf('with chapters', module).addWithChapters('with chapters', {
  useTheme: false,    // this has no effect at all
  subtitle: 'Snackbars are a great way to notify users',
  ...
});

would work, i.e. setting useTheme as false. However, this doesn't work at all. I can't set my custom styles on the title and subtitle.
A possible workaround is to set useTheme:false in the setDefaults in my config.js. But this will remove the default styles in all stories, which I don't want. I want the default styles to be removed in a selected stories only.

Another workaround is to force the custom styles that we want to apply like :

.story-title {
    color: 'red'; !important
}

On going through the code, I found this,

export default class Story extends Component {
  render() {
    const {
      context, subtitle, title, info, chapters, addonInfo, sectionOptions,
    } = this.props;
    const { useTheme } = sectionOptions;     // this extracts useTheme from section options and not the one defined for the title and subtitle
    ....
    }
}

The code is picking up useTheme defined in section options only, and thus the useTheme property for title and subtitle, the way I intend is not picked up by the code at all.

So If I need to alter the styles of a story title or subtitle, I have to set useTheme: false in the setDefaults option which will switch off the default styles in all stories.

Am I missing something here ? Is there any solution ?

I know there are workarounds to this, but just wanted to highlight this, coz I think others might be facing this issue as well.

Add right panel for quick navigation of chapters sections

If a story has many chapters and sections, the page can get too long. It will be nice to have a navigation panel to jump to these chapters and sections very fast.

return the actual pattern in an Iframe

Hi,
I have problems with styling and customizing chapters.
I think I'm not alone, reading the other issues

• 1 / global styles required for patterns apply to chapter UI
• 2 / can't override chapter UI styles
• 3 / decorators apply to chapters instead of actual patterns

I think the best way to handle that would be to wrap the sectionsFn into an Iframe, so the Add-on UI is completely decoupled from the actual Patterns UI.
It would make it easier to style either add-on UI and pattern.

Tell me if you think this would be a plausible option, I could help if necessary, but I figured you could easily tell me if it's viable or not.

Storybook 5 support?

Hi,

Storybook released a new major version (5.0) and there are a few breaking changes. I am not sure if this add-on would work out of the box but it requires Storybook 4 currently, which conflicts with Storybook 5 (it compiles but there are errors due to different versions of Storybook installed).

Is there any plan to support Storybook 5 by chance? Thanks!

Remove story title from preview

The behavior is not the same as the default .add from storybook, I would prefer to choose my own preview and not being forced to use the story tab name as title. Will it be possible to remove this behavior in the futur ?

options.createElement is not a function

I'm getting an error when using the info configuration:

options.createElement is not a function Please report this to https://github.com/markedjs/marked.

Any ideas?

storiesOf("Colours", module).addWithChapters("Colours", {
  useTheme: false,
  chapters: [
    {
      sections: [
        {
          title: "This is a Section's Title",
          subtitle: "Each section can be used to render a component",
          info: `hello`,
          sectionFn: () => (
            <div>
              {Object.entries(colours).map((key, index) => {
                return (
                  <div key={index} className={styles.colour}>
                    <Colour background={key[1]} />
                    <div>{key[0]}</div>
                    <div>{key[1]}</div>
                  </div>
                );
              })}
            </div>
          ),
          options: {
            showSource: false,
            allowSourceToggling: false,
            showPropTables: false,
            allowPropTablesToggling: false
          }
        }
      ]
    }
  ]
});

Is it supported for React Native Storybook?

any plans to support the same for rn storybook, if yes what are the timeline for the same?

Markdown code block

Hi!

I'm trying to add a code block in markdown format as part of my info string. I've managed to format the string in such a way that it outputs the desired <code /> and <pre /> elements. The <code /> element has the class attribute hljs javascript.
<code class="hljs javascript" >

My only problem now is the color formatting of the code block. I noticed your using marksy to compile the string from markdown to html, so I followed their instructions under Code highlighting and managed to get part of the styling working by loading some additional CSS (basically just the container for the code block).

Can you recommend a way to get this working?

Thank you,
/John

Compatible with latest storybook?

Is this plugin compatible with the latest version of storybook?

'setDefaults' is not a function

I'm getting the following error with the latest version from npm (2.1.0):

Uncaught TypeError: (0 , _reactStorybookAddonChapters.setDefaults) is not a function

Double-checking in RunKit:

Could you publish your latest release? Thanks!

Bug: Maximum callstack exceeded

There's an infinite loop because extract does not accept the next level's children as argument but uses the ones from the upper scope.

How to Integrate Knobs with Chapters

Markdown misinterpreted

I'm having a hard time wrapping my head around exactly how markdown is parsed inside of chapters. Sometime the output is exactly what you'd expect, but more often than not html is outputted in plain text.
Adding examples in code blocks behave very unreliably as well. Especially describing React elements, (both inside and out side a code blocks) a lot of times will be rendered as html element or not visible at all.

Usually I get the best result by having my markdown in separate files, importing them and adding those inside of chapters. But even this doesn't seam to guarantee the resulting markup end up the way it's suppose to.

Support additional line breaks or paragraphs in markdown

How can I add paragraphs or additional line breaks to the info sections? I can't reproduce what's in the demo, even when I clone the project and run it locally:

Issue with Source Block styles

Not sure if I'm missing something, but comparing what I have to your example I can't see any differences.

My source blocks look like this:

And I am getting the console warnings related to glamorous like this one:

glamorous.esm.js:439 glamorous warning: Expected component called "Pre" which uses withTheme to be within a ThemeProvider but none was found.

Insert images as info for sections

Hello!

I'd like to insert image in "info" for section while using "Chapters" add-on. However no success as images don't display. Can you suggest something?

Thanks!

Add option to disable default section styles

I'm having a bit of a hard time overriding the section styles that are injected by this addon (e.g. margins, font family, font sizes,...).

Is there currently a way to disable those or could this be added in a future version?

Default Props Value Not Showing Up

Using chapters the default prop values supplied to my component do not show up.

The first image is when a simple story is added to the story book, and the second with the same component is rendered within a section

For some reason, the default value fields are not populated.

Dynamically loading multiple components while adding stories

Is there a way to add the components dynamically rather than manually importing one each ? I am looking to create a single story for all the components

For eg rather than having

import Button from '/components/Button/'
import Link from '/components/Link/'
import Panel from '/components/Panel/'
import Header from '/components/Header/'
import Footer from '/components/Footer/'

storiesOf('Addon Chapters')
.addWithChapters(
 'All Stories', {
  subtitle: 'All Organisms',
  chapters: [
    {
      sections: [
        {
          sectionFn: () => (<Button  />)
        },
        {
          sectionFn: () => (<Link  />)
        },
        {
          sectionFn: () => (<Panel  />)
        },
        {
          sectionFn: () => (<Header />)
        },
        {
          sectionFn: () => (<Footer />)
        }
        // .. and so on
      ]
    }
  ]
}
)

so that something like below could be written

const getSections = (comps) => comps.map(comp => { sectionFn: () => (<Comp />) })

storiesOf('Addon Chapters')
.addWithChapters(
 'All Stories', {
  subtitle: 'All Organisms',
  chapters: [
    {
      sections: getSections(dynamicallyLoadedComponents)
    }
  ]
}
)

Is it possible to dynamically import all components in sub directories and set it to dynamicallyLoadedComponents ?

Give user ability to not render components

Trying to split up sections of components and the source code for those components. Ideally, it would be nice to not actually render the sectionFn, but still have the ability to pull the source code from it as some kind of option.

There's always the ability to hack around it and just target it with css to hide it, but that's obviously not the cleanest solution.

Shift to alternative CSS approach

Styling for each chapter and section is using React inline styles and if a story has many many chapters and sections it may cause a performance hit. React inline styles are not the best way to handling styling anyways.

Not working with react v16

I am trying to update my project to react v16 but I am getting an JS error at

https://github.com/yangshun/react-storybook-addon-chapters/blob/master/src/components/PropTable.jsx#L105

PropTable.propTypes = {
  type: React.PropTypes.func,
};

React.PropTypes is undefined, sound line https://facebook.github.io/react/docs/typechecking-with-proptypes.html

Upgrade to Storybook 3.0

Allow Use Of Decorators

Hi!
For some of my components I need a dark background. Is it possible to use decorators or anything else, that doesn’t show up in the source area?

Support functions to create configuration objects

It would be useful to have a function instead of a static object when configuring addWithChapters.

eg.

.addWithChapters('as a function', () => ({
   chapters: {...}
}))

Are you open to a PR adding this functionality?

Vue.js support?

Any plans for supporting chapters with vue storybooks?

Invalid PropTypes definitions

Hello,

After migrating our Storybook to v5, we started to get Warnings in the Web Browser's console looking like this:

Warning: Invalid argument supplied to oneOfType, expected an instance of array.

After debugging it seems the Warnings are coming from this package, more especially the PropType definitions of Story, Chapter and Section.

In all 3 of these Components, the following PropTypes are defined:

  title: PropTypes.oneOfType(PropTypes.string, PropTypes.object),
  subtitle: PropTypes.oneOfType(PropTypes.string, PropTypes.object),

According to React PropType documentation, oneOfType takes an array as Parameter. Therefore, the above PropTypes should be updated to the following in all 3 Components:

  title: PropTypes.oneOfType([PropTypes.string, PropTypes.object]),
  subtitle: PropTypes.oneOfType([PropTypes.string, PropTypes.object]),

Call for maintainers

I don't really use storybook anymore and don't have much interest or motivation in maintaining it. If anyone would like to be a maintainer please comment below!

Support for flow types

When I use flow in a component, instead of a props table, the output displays the following:

PropTypes
Component
No propTypes defined!

Here are some of storybook packages that I have set up:

"@storybook/addon-info": "^3.4.11",
"@storybook/addon-options": "^3.4.10",
"@storybook/addons": "^3.4.10",
"@storybook/react": "^3.4.10",
"react-storybook-addon-chapters": "^2.1.7",

I don't see any docs about this so I assume it's not supported but wanted to double check this and/or see if this is something that you will be adding in the future?

TypeError when rendering the source of a section with a Fragment as a prop

Running the following example:

const SomeComponent = ({someProp}) => (
  <div>
    {someProp}
  </div>
);

storiesOf('Components', module)
  .addWithChapters(
    'Fragment',
    {
      chapters: [
        {
          sections: [
            {
              title: 'I will error',
              sectionFn: () => (
                <SomeComponent someProp={
                  <React.Fragment>
                    <div>Hi</div>
                    <div>Hello</div>
                  </React.Fragment>
                }/>
              )
            }
          ]
        }
      ]
    }
  );

Renders this error:

Other info:

• If the Fragment is passed in as children, it renders the source fine except the fragment shows up as <Unknown>
• If showSource is false, there is no error

Bug: Rendering of `PropTable`

I found 2 issues:

• Shouldn't this be PropVal instead of Node?

• And this newPropTables instead of propTables?

When I change both names the prop table renders but I'm not sure if I miss sth here.

Let's chat?

Hello Storybook maintainer here,

I was hoping to have a chat you about storybook, and your addon.
Would you be interested? @brandonellis

Error with @storybook/addons-info 5.2.0

A lockfile maintenance patch has revealed an incompatibility with @storybook/addons-info version 5.2.0 and react-storybook-addons-chapters latest version:

ERROR in ./node_modules/react-storybook-addon-chapters/dist/components/Section.js
Module not found: Error: Can't resolve '@storybook/addon-info/dist/components/Node' in '/Users/williamdurand/projects/mozilla/addons-frontend/node_modules/react-storybook-addon-chapters/dist/components'
 @ ./node_modules/react-storybook-addon-chapters/dist/components/Section.js 30:35-88
 @ ./node_modules/react-storybook-addon-chapters/dist/index.js
 @ ./stories/setup/config.js
 @ multi ./node_modules/@storybook/core/dist/server/common/polyfills.js ./node_modules/@storybook/core/dist/server/preview/globals.js ./stories/setup/config.js (webpack)-hot-middleware/client.js?reload=true&quiet=true
^C

Edit: I can't find a good workaround for now..