diff --git a/addons/addon-contexts/README.md b/addons/addon-contexts/README.md index 7cb496cd2453..9e77f641244f 100644 --- a/addons/addon-contexts/README.md +++ b/addons/addon-contexts/README.md @@ -3,25 +3,26 @@ **Storybook Addon Contexts** is an addon for driving your components under dynamic contexts in Storybook. -## Why you need this? +## 💡 Why you need this? Real world users expects your application being customizable, that is why often your components are **polymorphic**: they simply need to adapt themselves under different contextual environments. Imagine your components can speak Chinese, English, or even French, and they change their skin tone under dark or light theme. Yeah, you want to make sure a component look great in all scenario. -A good practice to write maintainable components is separate the presentation and its business logic. Often enough, -you will find it become very tedious to wrap each component deeply with its contextual environments before you can -really write the main story. You even start to write extra components or factory functions just to make your life -easier. How about changing the context of your story dynamically?! There were simply having no good way so you -ended up writing stories like an accountant. +A good practice to write maintainable components is separate the presentation and its business logic. Storybook is +a great place for exercising the visualization and interaction of your components, which may depended on a context. +Often enough, you will find it become very tedious to wrap each component deeply with its contextual environments +before you can really write the main story. You even start to write extra components or factory functions just to +make your life easier. How about changing the context of your story dynamically?! There were simply having no good +way so you ended up writing stories like an accountant. That is why you need this. An elegant way to wrap your component stories and change their contextual environment directly and dynamically in Storybook UI! Kind of like a dependency injection, eh! The best bit is **you define it once then apply it everywhere**. -## Features +## ✅ Features 1. Define a single global file for managing contextual environments (a.k.a. containers) for all of your stories declaratively. No more repetitive setups or noisy wrapping, making your stories more focused and readable. @@ -32,13 +33,13 @@ once then apply it everywhere**. 4. Offer chainable and granular configurations. It is even possible to customized at per story level. -## Supported Environments +## 🧰 Supported Environments Make sure the version of your Storybook is above v5. Currently, only React is being supported. However, this addon is aiming to expend its framework supports in the near future. -## Getting started +## 🎬 Getting started To get it started, add this package into your project: @@ -80,7 +81,7 @@ stories.addDecorator(withContexts(contexts)); ... ``` -## Configurations (APIs) +## ⚙️ Configurations (APIs) It is recommended to have a separate file for managing your contextual setups. Let's add a file named `context.js` first. To use this addon to inject your theming contexts, let's take the following example: @@ -92,23 +93,23 @@ const light = {/* your light theme */}; export const contexts = [ { - icon: 'box', // <- icon used in the Storybook toolbar - title: 'Themes', - components: [ // <- an array contains a chain of component wrappers + icon: 'box', // a icon displayed in the Storybook toolbar to control contextual props + title: 'Themes', // an unique name of a contextual environment + components: [ // an array of components that is going to be injected to wrap stories /* SCThemeProvider, */ /* MuiThemeProvider, */ ], - params: [ // <- params is an array of list to allow switching contextual props dynamically + params: [ // an array of params contains a set of predefined `props` for `components` { name: 'Light Theme', props: { theme: light } }, { name: 'Dark Theme', props: { theme: dark }, default: true }, ], options: { - deep: false, // <- true to inject props to all components; false to only the first - disable: false, // <- true to ignore the whole context; - cancelable: false, // <- true to give an option to opt-out (unwrap) temporarily in toolbar menu + deep: false, // pass the `props` deeply into all wrapping components + disable: false, // disable this contextual environment completely + cancelable: false, // allow this contextual environment to be opt-out optionally in toolbar }, }, - /* ... */ // <- multiple contexts setups are supported + /* ... */ // multiple contexts setups are supported ]; ``` @@ -122,10 +123,11 @@ The `contexts` is an array of object that should has the following properties: ### `icon : string?` (default `undefined`) -This addon allows you to define an icon for each contextual environment individually. Take a look from what are -currently supported [icon lists](https://storybooks-official.netlify.com/?path=/story/basics-icon--labels) from the -official Storybook story. You must define an icon first if you want to take advantage on switching props dynamically -in your Storybook toolbar. +A icon displayed in the Storybook toolbar to control contextual props. This addon allows you to define an icon for +each contextual environment individually. Take a look from what are currently supported +[icon lists](https://storybooks-official.netlify.com/?path=/story/basics-icon--labels) from the official Storybook +story. You must define an icon first if you want to take advantage on switching props dynamically in your Storybook +toolbar. ### `title : string` (required) @@ -133,17 +135,17 @@ An unique name of a contextual environment. Note, if you have duplicated name, ### `components : React.ComponentType[]` (required) -An array of components that is going to be injected to wrap your stories. This means this addon allow multiple -wrapping components coexisted. The wrapping sequence is from the left to right (parent -> children -> story). This -nested wrapping behaviour can be useful in some cases; for instance, in the above example, we are wrapping stories -under `styled-componnets` and `material-ui` theme providers. +An array of components that is going to be injected to wrap stories. This means this addon allow multiple wrapping +components coexisted. The wrapping sequence is from the left to right (parent -> children -> story). This nested +wrapping behaviour can be useful in some cases; for instance, in the above example, we are wrapping stories under +`styled-componnets` and `material-ui` theme providers. -Typically, components are `Providers` from [React Context API](https://reactjs.org/docs/context.html). However, it -is really up to your use cases. +Note, typically, components are `Providers` from [React Context API](https://reactjs.org/docs/context.html). However, +it is really up to your use cases. ### `params : object[]` (required) -An array of params contains information on a set of predefined `props` for `components`. +An array of params contains a set of predefined `props` for `components`. Note: 1. additional params can be appended at the story level later; however, they are never be able to overridden the @@ -172,7 +174,7 @@ at the story level. ### `options.deep : boolean?` (default: `false`) -Pass the `props` deeply into all components. Useful when you have multiple wrappers that take the same props. +Pass the `props` deeply into all wrapping components. Useful when you want them all taking the same props. ### `options.disable : boolean?` (default: `false`) @@ -180,5 +182,5 @@ Disable this contextual environment completely. Useful when you want to opt-out ### `options.cancelable : boolean?` (default: `false`) -Allow this contextual environment to be disabled temporarily. When set to `true`, an **Off** option will be shown -at first in the toolbar menu in your Storybook. +Allow this contextual environment to be opt-out optionally in toolbar. When set to `true`, an **Off** option will +be shown at first in the toolbar menu in your Storybook.