mirror of
https://github.com/storybookjs/storybook.git
synced 2025-04-03 05:04:51 +08:00
Merge pull request #14837 from storybookjs/chore_minor_tweaks_to_addon_api_theming_docs
Chore:(Docs) Adds minor tweaks to the theming and Addons API
This commit is contained in:
Michael Shilman
GitHub
commit
b3e8a5e063
@ -18,7 +18,7 @@ This is the core addon API. This is how to get the addon API:
|
||||
|
||||
### addons.getChannel()
|
||||
|
||||
Get an instance to the channel where you can communicate with the manager and the preview. You can find this in both the addon register code and in your addon’s wrapper component (where used inside a story).
|
||||
Get an instance to the channel where you can communicate with the manager and the preview. You can find this in both the addon register code and your addon’s wrapper component (where used inside a story).
|
||||
|
||||
It has a NodeJS [EventEmitter](https://nodejs.org/api/events.html) compatible API. So, you can use it to emit events and listen for events.
|
||||
|
||||
@ -58,11 +58,12 @@ The render function is called with `active` and `key`.
|
||||
|
||||
When the panel is in focus in the UI, the `active` will be true.
|
||||
|
||||
As you can see, you can set any React Component as the panel. Currently, it's one line of text. But you can do anything you want. You should specify the panel title. It could be a plain text.
|
||||
As you can see, you can set any React Component as the panel. Currently, it's one line of text. But you can do anything you want.
|
||||
It's a good practice to specify the panel title with the `title` key. You can use any plain text with it.
|
||||
|
||||
## makeDecorator API
|
||||
|
||||
The `makeDecorator` API can be used to create decorators in the style of the official addons. Use it like so:
|
||||
Use the `makeDecorator` API to create decorators in the style of the official addons. Like so:
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
@ -84,7 +85,7 @@ The options to `makeDecorator` are:
|
||||
|
||||
<div class="aside">
|
||||
|
||||
Note if the parameters to a story include `{ foo: { disable: true } }` (where `foo` is the `parameterName` of your addon), your decorator will not be called.
|
||||
💡 <strong>Note:</strong>If the story's parameters include `{ foo: { disable: true } }` (where `foo` is the `parameterName` of your addon), your decorator will not be called.
|
||||
|
||||
</div>
|
||||
|
||||
@ -106,10 +107,10 @@ Writing addons can be simplified a lot by using these Storybook hooks:
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
Allows full access to the entire storybook state.
|
||||
It allows full access to the entire storybook state.
|
||||
Your component will re-render whenever the storybook state changes.
|
||||
|
||||
If you use this, remember your component wil be re-rendered a lot, and you may need to optimize for that using [`React.memo`](https://reactjs.org/docs/react-api.html#reactmemo) or [`useMemo`](https://reactjs.org/docs/hooks-reference.html#usememo) or [`PureComponent`](https://reactjs.org/docs/react-api.html#reactpurecomponent).
|
||||
If you use this, remember your component will be re-rendered a lot, and you may need to optimize for that using [`React.memo`](https://reactjs.org/docs/react-api.html#reactmemo) or [`useMemo`](https://reactjs.org/docs/hooks-reference.html#usememo) or [`PureComponent`](https://reactjs.org/docs/react-api.html#reactpurecomponent).
|
||||
|
||||
### useStorybookApi
|
||||
|
||||
@ -123,9 +124,9 @@ If you use this, remember your component wil be re-rendered a lot, and you may n
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
Allows full access to the storybook API.
|
||||
It allows full access to the storybook API.
|
||||
|
||||
Detail on the storybook api are further down.
|
||||
Details on the Storybook API are further down.
|
||||
|
||||
### useChannel
|
||||
|
||||
@ -139,9 +140,9 @@ Detail on the storybook api are further down.
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
Allows for both setting subscriptions to events and getting the emitter for emitting custom event unto the channel.
|
||||
Allows for both setting subscriptions to events and getting the emitter for emitting custom events unto the channel.
|
||||
|
||||
The messages can be listened for on both the iframe and the manager side.
|
||||
The messages can be listened to on both the iframe and the manager side.
|
||||
|
||||
### useAddonState
|
||||
|
||||
@ -155,13 +156,13 @@ The messages can be listened for on both the iframe and the manager side.
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
Extremely useful for addons that need to persist some state.
|
||||
Extremely useful for addons that need to persist in some form of state.
|
||||
|
||||
Storybook may unmount your addon component, and so keeping local state, might not work really well.
|
||||
Storybook may unmount your addon component, and so keeping local state might not work well.
|
||||
|
||||
Also some addons consist of multiple parts, some part being in a panel, some in the toolbar etc.
|
||||
Also, some addons consist of multiple parts, some parts being in a panel, some in the toolbar, etc.
|
||||
|
||||
With this hook they can all get access to the same bit of state which is persisted even if the components are unmounted.
|
||||
With this hook, addons can get access to the same portion of the state, persisted even if the components are unmounted.
|
||||
|
||||
### useParameter
|
||||
|
||||
@ -197,6 +198,21 @@ It allows you to retrieve and update any Storybook Globals you want.
|
||||
|
||||
If you use this hook, remember that your component will render a lot, and you may need to optimize for that using [`React.memo`](https://reactjs.org/docs/react-api.html#reactmemo) or [`useMemo`](https://reactjs.org/docs/hooks-reference.html#usememo) or [`useCallback`](https://reactjs.org/docs/hooks-reference.html#usecallback).
|
||||
|
||||
|
||||
### useArgs
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
<CodeSnippets
|
||||
paths={[
|
||||
'common/args-usage-with-addons.js.mdx'
|
||||
]}
|
||||
/>
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
A handy Storybook hook that you can use in your addon if you need to read or update [`args`](../writing-stories/args.md).
|
||||
|
||||
---
|
||||
|
||||
## Storybook API
|
||||
@ -221,6 +237,8 @@ Let's say you've got a story like this:
|
||||
'react/button-story-with-addon-example.js.mdx',
|
||||
'vue/button-story-with-addon-example.js.mdx',
|
||||
'angular/button-story-with-addon-example.ts.mdx',
|
||||
'svelte/button-story-with-addon-example.js.mdx',
|
||||
'svelte/button-story-with-addon-example.native-format.mdx',
|
||||
]}
|
||||
/>
|
||||
|
||||
@ -254,7 +272,7 @@ Same as `selectStory`, but accepts a story inside current kind as the only param
|
||||
|
||||
### api.setQueryParams()
|
||||
|
||||
This method allows you to set query string parameters. You can use that as temporary storage for addons. Here's how you set query params.
|
||||
This method allows you to set query string parameters. You can use that as temporary storage for addons. Here's how you define query params:
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
@ -268,7 +286,7 @@ This method allows you to set query string parameters. You can use that as tempo
|
||||
|
||||
<div class="aside">
|
||||
|
||||
If you need to remove a query param, use `null` for that. For an example, let's say we need to remove bbc query param. This is how we do it:
|
||||
💡 <strong>Note:</strong> If you need to remove a query param, use `null` for that. For example, let's say we need to remove the `bbc` query param. See below how to do it:
|
||||
|
||||
</div>
|
||||
|
||||
@ -284,7 +302,7 @@ If you need to remove a query param, use `null` for that. For an example, let's
|
||||
|
||||
### api.getQueryParam()
|
||||
|
||||
This method allows you to get a query param set by above API `setQueryParams`. For example, let's say we need to get the bbc query param. Then this how we do it:
|
||||
This method allows you to get a query param set by the above API `setQueryParams`. For example, let's say we need to get the `bbc` query param. Then this how we do it:
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
@ -298,7 +316,7 @@ This method allows you to get a query param set by above API `setQueryParams`. F
|
||||
|
||||
### api.getUrlState(overrideParams)
|
||||
|
||||
This method allows you to get application url state with some changed params. For example, if you want to get a link to a particular story:
|
||||
This method allows you to get the application URL state with some changed params. For example, if you want to get a link to a particular story:
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
@ -312,7 +330,7 @@ This method allows you to get application url state with some changed params. Fo
|
||||
|
||||
### api.on(eventName, fn)
|
||||
|
||||
This method allows you to register a handler function which will be called whenever the user navigates between stories.
|
||||
This method allows you to register a handler function called whenever the user navigates between stories.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
@ -322,4 +340,4 @@ This method allows you to register a handler function which will be called whene
|
||||
]}
|
||||
/>
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
<!-- prettier-ignore-end -->
|
||||
@ -28,11 +28,11 @@ As an example, you can tell Storybook to use the "dark" theme by modifying [`.st
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
When setting a theme, set a full theme object. The theme is replaced, not combined.
|
||||
When setting a theme, set a complete theme object. The theme is replaced, not combined.
|
||||
|
||||
## Theming docs
|
||||
|
||||
[Storybook Docs](../writing-docs/introduction) uses the same theme system as Storybook’s UI, but is themed independently from the main UI.
|
||||
[Storybook Docs](../writing-docs/introduction) uses the same theme system as Storybook’s UI but is themed independently from the main UI.
|
||||
|
||||
Supposing you have a Storybook theme defined for the main UI in [`.storybook/manager.js`](./overview.md#configure-story-rendering):
|
||||
|
||||
@ -77,16 +77,16 @@ Inside your `.storybook` directory, create a new file called `YourTheme.js` and
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
<div class="aside">
|
||||
If you're using <code>brandImage</code> to add your own custom logo, you can use any of the most common image formats.
|
||||
💡 If you're using <code>brandImage</code> to add your custom logo, you can use any of the most common image formats.
|
||||
</div>
|
||||
|
||||
Above we're creating a new theme that will:
|
||||
Above, we're creating a new theme that will:
|
||||
|
||||
- Use Storybook's `light` theme as a baseline.
|
||||
- Replace Storybook's logo in the sidebar with our own (defined in the brandImage variable).
|
||||
- Add custom branding information.
|
||||
|
||||
Finally we'll need to import the theme into Storybook. Create a new file called `manager.js` in your `.storybook` directory and add the following:
|
||||
Finally, we'll need to import the theme into Storybook. Create a new file called `manager.js` in your `.storybook` directory and add the following:
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
@ -108,14 +108,15 @@ Adjust your `storybook` script in your package.json and include the [`--no-manag
|
||||
},
|
||||
}
|
||||
```
|
||||
<div class="aside">
|
||||
💡 <strong>Note:</strong> Once you've finished configuring your theme, you can remove the <code>--no-manager-cache</code>flag from the <code>storybook</code> script at will. Leaving it in can severely impact loading times.
|
||||
</div>
|
||||
|
||||
Now your custom theme will replace Storybook's default theme and you'll see a similar set of changes in the UI.
|
||||
Now your custom theme will replace Storybook's default theme, and you'll see a similar set of changes in the UI.
|
||||
|
||||
|
||||
|
||||
**Note:** Once you're finished configuring the theme, remove the flag `--no-manager-cache` from the `storybook` script, otherwise loading times can be severely impacted.
|
||||
|
||||
Let's take a look at more complex example. Copy the code below and paste it in `.storybook/YourTheme.js`.
|
||||
Let's take a look at a more complex example. Copy the code below and paste it in `.storybook/YourTheme.js`.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
@ -127,7 +128,7 @@ Let's take a look at more complex example. Copy the code below and paste it in `
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
Above we're updating the theme with the following changes:
|
||||
Above, we're updating the theme with the following changes:
|
||||
|
||||
- A custom color palette (defined in the `app` and `color` variables).
|
||||
- Custom fonts (defined in the `font` and `text` variables).
|
||||
@ -137,14 +138,14 @@ With the new changes introduced, the custom theme should yield a similar result.
|
||||
|
||||
|
||||
<div class="aside">
|
||||
Many theme variables are optional, the <code>base</code> property is <strong>NOT</strong>.
|
||||
💡 Many theme variables are optional, the <code>base</code> property is <strong>NOT</strong>.
|
||||
</div>
|
||||
|
||||
The `@storybook/theming` package is built using TypeScript, so this should help create a valid theme for TypeScript users. The types are part of the package itself.
|
||||
The `@storybook/theming` package is built using TypeScript, which should help create a valid theme for TypeScript users. The types are part of the package itself.
|
||||
|
||||
## CSS escape hatches
|
||||
|
||||
The Storybook theme API is narrow by design. If you want to have fine-grained control over the CSS, all of the UI and Docs components are tagged with class names to make this possible. This is advanced usage: **use at your own risk**.
|
||||
The Storybook theme API is narrow by design. If you want to have fine-grained control over the CSS, all UI and Docs components are tagged with class names to make this possible. This is advanced usage: **use at your own risk**.
|
||||
|
||||
To style these elements, insert style tags into:
|
||||
|
||||
@ -153,15 +154,13 @@ To style these elements, insert style tags into:
|
||||
|
||||
<div class="aside">
|
||||
|
||||
Similar to changing the preview’s head tag, `.storybook/manager-head.html` allows you to inject code into the manager side, which can be useful to adding styles for your theme that target Storybook’s HTML.
|
||||
|
||||
WARNING: we don’t make any guarantees about the structure of Storybook’s HTML and it could change at any time. Consider yourself warned!
|
||||
💡 <strong>Caution:</strong> The same way as you can adjust your [preview’s head tag](../configure/story-rendering.md#adding-to-head), Storybook allows you to modify the code on the manager's side, through <code>.storybook/manager-head.html</code>. It can be helpful when adding theme styles that target Storybook's HTML, but it comes with a cost as Storybook's inner HTML can change at any time through the release cycle.
|
||||
|
||||
</div>
|
||||
|
||||
## MDX component overrides
|
||||
|
||||
If you're using MDX for docs, there's one more level of themability. MDX allows you to completely override the components that are rendered from Markdown using a components parameter. This is an advanced usage that we don't officially support in Storybook, but it's a powerful mechanism if you need it.
|
||||
If you're using MDX for docs, there's one more level of "themability". MDX allows you to completely override the components that are rendered from Markdown using a components parameter. It's an advanced usage that we don't officially support in Storybook, but it's a powerful mechanism if you need it.
|
||||
|
||||
Here's how you might insert a custom code renderer for `code` blocks on the page, in [`.storybook/preview.js`](./overview.md#configure-story-rendering):
|
||||
|
||||
@ -191,9 +190,9 @@ Here's how you might insert a custom `<Canvas />` block:
|
||||
|
||||
## Addons and theme creation
|
||||
|
||||
Some addons require specific theme variables that a Storybook user must add. If you share your theme with the community, make sure to support the official API and other popular addons so your users have a consistent experience.
|
||||
Some addons require specific theme variables that a Storybook user must add. If you share your theme with the community, make sure to support the official API and other popular addons, so your users have a consistent experience.
|
||||
|
||||
For example, the popular Actions addon uses [react-inspector](https://github.com/xyc/react-inspector/blob/master/src/styles/themes/chromeLight.js) which has themes of its own. Supply additional theme variables to style it like so:
|
||||
For example, the popular Actions addon uses [react-inspector](https://github.com/xyc/react-inspector/blob/master/src/styles/themes/chromeLight.js), which has themes of its own. Supply additional theme variables to style it like so:
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
@ -241,4 +240,4 @@ Or with template literals:
|
||||
]}
|
||||
/>
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
<!-- prettier-ignore-end -->
|
||||
Loading…
x
Reference in New Issue
Block a user