Automatically generate stories for all of your component variants.
See more about this example in examples/app.
Install:
$ yarn add --dev storybook-cartesian
To integrate in your own project, add to your stories:
import cartesian from 'storybook-cartesian'
cartesian(storiesOf('Button/Cartesian', module))
.add(() => ({
colors: [
{ bg: '#FF5630', fg: '#FFBDAD' },
{ bg: '#4C9AFF', fg: '#B3D4FF' }
],
text: ['Click Me', '', '你好']
}),
props => <Button
style={{
padding: '1em 3em',
border: 'none',
backgroundColor: props.colors.bg,
color: props.colors.fg
}}>
{props.text}
</Button>
)The general structure for cartesian is this:
cartesian(<stories>)
.add(
<seed function>,
<component renderer>,
{
renderTitle: <title renderer>,
valid: <valid combination filter (optional)>,
apply: <story apply function (optional)>
}
)
Which gets you this kind of story layout generated automatically (for now the last "All/all variants" is a story discussed in Advanced):
Your seed function is responsible to generate content in the form of:
// if this is a sample of your props:
const props = {
one: "hello",
two: "foobar"
check: true
}
// then this is your seed function:
const seedfn = ()=>({
one: ["hello", "another"],
two: ["foobar"]
check: [true, false]
})If you want to have just a selection of props be cartesian you can use the special choice function:
import cartesian, { choice } from 'cartesian'
const seedfn = ()=>({
one: "rabbit",
two: "rabbit, rabbit",
check: choice(true, false)
})This will create a special data strucure which tells cartesian to create these combinations:
[{
one: "rabbit",
two: "rabbit, rabbit",
check: true
},{
one: "rabbit",
two: "rabbit, rabbit",
check: false
}]Your titleRender function gets an instance of your props and returns a string:
const renderTitle = props => `${props.one} / ${props.check}`Your storyRender function gets an instance of your props and returns a component:
const componentRender = props => <Button {...props} />And to compose all of these with cartesian we can now do:
cartesian(storiesOf('Button/Cartesian'))
.add(
seedfn,
componentRender,
{ renderTitle }
)You can showcase all variants in two ways with one of the premade components:
Tiles- showcase variants as tiles which fill up the screen (many components on rows and columns).Rows- same thing, just one component per row.
And you have a helper function applyWith(title, component) that takes a title and one of these components, and generates your stories apply function.
import { Tiles, applyWith } from 'storybook-cartesian/react'
cartesian(storiesOf('Button/Cartesian/applyWith(Tiles)', module))
.add(() => ({
colors: [{ bg: '#FF5630', fg: '#FFBDAD' }, { bg: '#4C9AFF', fg: '#B3D4FF' }],
text: ['Click Me', '', '你好']
}),
props => <Button style={{ padding: '1em 3em', border: 'none', backgroundColor: props.colors.bg, color: props.colors.fg }}>{props.text}</Button>,
{
renderTitle: titles.renderPropNames(),
apply: applyWith("everything!", Tiles)
}
)And the result:
You can also use any of the individual components on their own:
import { Rows } from 'storybook-cartesian/react'
cartesian(storiesOf('Button/Cartesian/Tiles', module))
.add(() => ({
colors: [{ bg: '#FF5630', fg: '#FFBDAD' }, { bg: '#4C9AFF', fg: '#B3D4FF' }],
text: ['Click Me', '', '你好']
}),
props => <Button style={{ padding: '1em 3em', border: 'none', backgroundColor: props.colors.bg, color: props.colors.fg }}>{props.text}</Button>,
{
renderTitle: titles.renderPropNames(),
apply: (stories, candidates) => {
stories.add('all variants', () => <Rows items={candidates}/>)
}
}
)You can pick a title renderer from a premade collection:
renderCheckSignIfExists- renders the prop name and a 'check' sign if it exists, 'x' if missingrenderPropNames- renders just the prop names givenrenderProps- render aprop=valueformat
You can use one of these like so:
import cartesian, { titles } from 'cartesian'
cartesian(storiesOf('Button/Cartesian'))
.add(
seedfn,
componentRender,
{ renderTitle: titles.renderCheckSignsIfExists() }
)Which produces the following title with props = { oneProp: null, twoProp: 2}:
x oneProp | ✓ twoProp
There are more renderers that you can explore (also - happy to get PRs with more!).
If you'd like prop values to have logical names, try renderWithLegend:
import cartesian, { renderWithLegend } from 'cartesian'
const complex = { foo:1, bar: 2 }
complex.toString = () => 'complex-1'
const titleWithLegend = renderWithLegend({
'#FF5630': 'primary',
'#FFBDAD': 'secondary',
'#4C9AFF': 'primary-opt',
'#B3D4FF': 'secondary-opt',
'Click Me': 'english',
[complex]: 'complex object',
'': 'empty',
'你好': 'chinese'
})
cartesian(storiesOf('Button/Cartesian (legend)', module))
.add(() => ({
colors: [{ bg: '#FF5630', fg: '#FFBDAD' }, { bg: '#4C9AFF', fg: '#B3D4FF' }],
text: ['Click Me', '', '你好']
}),
props => <Button style={{ padding: '1em 3em', border: 'none', backgroundColor: props.colors.bg, color: props.colors.fg }}>{props.text}</Button>,
{
renderTitle: titleWithLegend(props => `"${props.text}" ${props.colors.bg + '/' + props.colors.fg}`),
}
)renderWithLegend takes a legend dict, that maps actual prop values to the ones you give in the legend.
Then, it takes a normal renderTitle function that you supply, and it will make sure prop values will be legend values.
If you want just a top level legend translation (not going into all values in a data structure) use renderWithLegendFlat.
Some times, not all prop combinations make sense. For example if you have an isLoading and a results props it doesn't make
sense to have both true and results populated:
// doesn't make sense
<SearchResults isLoading={true} results={['hello', 'world']}>For this, we have an valid function that we can add, and the following will filter out this invalid combination:
cartesian(storiesOf('Button/Cartesian'))
.add(
seedfn,
componentRender,
{
renderTitle,
valid: props => !(props.isLoading && props.results)
}
)Some other times you might want to customize how you add stories. For example, let's say you want just one story to contain all cartesian product items.
For this, we have another optional function:
const allVariantsInOne = (stories, variants)=>{
const story = variants.map(c=>(
<div>
<div>{c.title}</div>
<div>{c.story}</div>
</div>))
stories.add('all variants', ()=> story)
}
cartesian(storiesOf('Button/Cartesian'))
.add(
seedfn,
componentRender,
{ apply: allVariantsInOne }
)Fork, implement, add tests, pull request, get my everlasting thanks and a respectable place here :).
To all Contributors - you make this happen, thanks!
Copyright (c) 2018 Dotan Nahum @jondot. See LICENSE for further details.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent