- Disclaimer: This is only guaranteed to work with React-based projects. Other frameworks may introduce unintended errors.
- Typescript only Project. We don't have a plan to support Javascript
- NOW WE SUPPORT STORYBOOK 8
This project is an addon that provides additional functionality to Storybook. In a separate panel, you can see the various aspects of the component as a table.
This project was highly inspired by Datadog's design system, DRUIDS, and we wanted to use the Component Permutation feature from DRUIDS in Storybook.
🆘 Help us make sb-addon-permutation-table
even more awesome! 🆘
After the v1.0.0 release, we tried making sb-addon-permutation-table
work with Vue and Svelte too, but we hit a tiny roadblock. Our Addon is head over heels for a React hook, and it just can't get enough! As of now, it is still deeply in love with React and hasn't quite opened its heart to other frameworks.
If we can get rid of React hooks in Panel and Preview, this marvalous addon will be shine regardless of what framework you are working on.
Can you lend a helping hand? 🥺
-The Mighty Quest-
1. Take a peek at our GitHub - the code is all there, waiting for your brilliance.
2. Got any bright ideas? Quirky solutions? Magical spells 🧙♂️? Share them with us, and we'll be forever grateful!
3. Spread the word! Let your fellow developers know about "sb-addon-permutation-table"'s quest for multi-framework love.
4. Together, we can make "sb-addon-permutation-table" truly awesome for all frameworks out there! 🌟
Table of contents
Feature
-
Argument Control
: Manipulate the properties of your component directly. You can see what your component looks like in context. -
Permutation
: Provide a table of different views with combinations of properties. Compare and analyze the results of combinations at a glance.
Installation
yarn add sb-addon-permutation-table
Requirements
Storybook >= 8.x
node > 16.x
For users under SB 7.x
- try version 1.0.21
yarn add sb-addon-permutation-table@1.0.21
Why should I use it?
sb-addon-permutation
provides a quick glance of complex, multi-property component views. Developers will be able to debug and test components efficiently through the showcase provided.
Usage
Add addon code in .stories/main.ts
like below.
import type { StorybookConfig } from "@storybook/react-vite";
const config: StorybookConfig = {
stories: ["../src/**/*.mdx", "../src/**/*.stories.@(js|jsx|ts|tsx)"],
addons: ["sb-addon-permutation-table"],
framework: {
name: "@storybook/react-vite",
options: {},
},
docs: {
autodocs: "tag",
},
};
export default config;
Unlike version 0.x, starting with version 1, no configuration is required to use the add-on. The add-on automatically pulls in the elements from each Story, but you can be more granular by passing in a parameter. The values accepted as parameter are shown below. The values used as parameter are not related to Preview, but are specified for use in the Panel.
name | description | type | default Value |
---|---|---|---|
componentName | The name of the component that appears in the Panel | string? |
name of Story |
importPath | The path of the component that is copied when the Copy import path button is clicked. |
string? |
"" |
children | children in the Story Component | string? |
{{children}} |
deactivate | Property Name for which you do not want to use the Permutation feature | string[] |
[] |
autoload | When the Story is loaded, you can create a property that will be automatically activated without any clicks. | "all" string[] |
[] |
More about the parameter children
The children parameter refers to the shape of the children's code that will be displayed in the CodeEditor area of the Panel when children is passed as an argument to the Story. Passing children as an argument will display correctly in Preview, but in the Panel, children will be displayed as {{children}}
unless you pass a separate parameter. Use this parameter when you want to show the geometry of children in the Panel.
See also: How to use children as an arg in Storybook
Example
The addon will automatically use your component's type and make it available in the Permutation Panel.
// stories/Component.stories.(ts|tsx)
import React from "react";
import { PermutationMeta } from "sb-addon-permutation-table";
import YourComponent from "YourComponent";
const meta: PermutationMeta<typeof YourComponent> = {
//...
parameters: {
permutation: {
componentName: "Takahashi", // "Takahashi" in the panel, regardless of the name of the component.
importPath: "@yourLib/yourComponent", // the value copied when clicked "Copy import" button
children: "<div>Chef of the diamond city</div>", // a value passed to children
deactivate: ["foo", "bar"], // deactviate property foo,bar
autoload: "all", // activate all property except deactivated
},
},
};
You can also apply parameters individually on a story by story basis.
export const Primary: Story = {
args: {
primary: true,
label:'Hello World'
},
};
export const PermutationDeactivate: Story = {
args:{
label:'Hello World'
}
parameters: {
permutation: {
deactivate: ["primary", "size"],
},
},
};
Advance
Activate autoload
when autoload is enabled, permutation table is automatically be activated when the story is loaded.
export const Primary: Story = {
args: {
primary: true,
},
parameters: {
permutation: {
// Now all element that can be permuted are now active when story is loaded
autoload: "all",
},
},
};
You can also enable only some attribute
export const Primary: Story = {
args: {
primary: true,
},
parameters: {
permuations: {
// only 'foo' and 'bar' attribute will be activated
autoload: ["foo", "bar"],
},
},
};
If both autoload and deactivate are allowed, deactivate takes precedence.
export const Primary: Story = {
args: {
primary: true,
},
parameters: {
permuations: {
// only 'bar' attribute is permuted
autoload: ["foo", "bar"],
deactivate: ["foo"],
},
},
};
Demos
FAQ
I enabled permutation on the story, but it only shows components with the same arguments 🥲
Are you using a decorator as a form of JSX? If so, make sure that check context is provided to StoryFn properly. Permutation table doesn't work if context isn't provided
Change this
// .storybook/decorator.tsx
export const decorators = [
(Story, context) => {
return (
<RandomWrapper>
<ThemeProvider>
<Story />
</ThemeProvider>
</RandomWrapper>
);
},
];
to this 👍
export const decorators = [
(Story, context) => {
return (
<RandomWrapper>
<ThemeProvider>{Story(context)}</ThemeProvider>
</RandomWrapper>
);
},
];
If you got another problem, make a issue to let us know
License
MIT