generated from storybookjs/addon-kit
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #72 from tetarchus/next
Merge changes for V2
- Loading branch information
Showing
68 changed files
with
11,912 additions
and
15,542 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1 +1 @@ | ||
| 20.17.0 | ||
| 20.18.0 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
File renamed without changes.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,65 @@ | ||
| --- | ||
| sidebar_position: 4 | ||
| title: Badge Locations | ||
| --- | ||
|
|
||
| Badges can appear in multiple locations within the Storybook UI. Current available locations are: | ||
|
|
||
| - `toolbar` - Display badges in the standard toolbar next to other controls. | ||
| - `toolbar-end` - Display badges at the end of the toolbar, to the right of the full-screen control. | ||
| - `sidebar` - Display badges in the sidebar next to the stories they apply to. | ||
|
|
||
| A badge definition can define multiple locations for a badge, and the default locations for all badges to inherit can also be defined in the addon configuration. | ||
|
|
||
| ## Default locations configuration | ||
|
|
||
| To set the locations that apply to all badges, define them in the addon configuration parameter (`badgesConfig`) under `locations`. If a badge definition doesn't define its own `locations`, these will be used instead. | ||
| By default, all badges will show in the `toolbar` area only. | ||
|
|
||
| ```ts title=".storybook/preview.ts" | ||
| import type { Preview } from '@storybook/[your-framework]'; | ||
| import type { NewBadgesConfig } from 'storybook-addon-badges'; | ||
|
|
||
| const preview: Preview = { | ||
| //...other preview config | ||
| parameters: { | ||
| //...other parameters | ||
| badgesConfig: { | ||
| locations: ['toolbar'], | ||
| // ...other addon config parameters | ||
| } satisfies NewBadgesConfig | ||
| } | ||
| } | ||
|
|
||
| export default preview; | ||
| ``` | ||
|
|
||
| If a specific badge needs to override the defaults, you can define `locations` in its configuration object. Note that for badges with no explicit config object, they will use the `default` value. | ||
|
|
||
| ## Badge-specific locations configuration | ||
|
|
||
| To set a specific badge's location, define it under the `locations` key of its config. | ||
|
|
||
| ```ts title=".storybook/preview.ts" | ||
| import type { Preview } from '@storybook/[your-framework]'; | ||
| import type { NewBadgesConfig } from 'storybook-addon-badges'; | ||
|
|
||
| const preview: Preview = { | ||
| //...other preview config | ||
| parameters: { | ||
| //...other parameters | ||
| badgesConfig: { | ||
| badgeMap: { | ||
| MyCustomBadge: { | ||
| locations: ['sidebar'], | ||
| title: "Custom" | ||
| } | ||
| }, | ||
| locations: ['toolbar'], | ||
| // ...other addon config parameters | ||
| } satisfies NewBadgesConfig | ||
| } | ||
| } | ||
|
|
||
| export default preview; | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,67 @@ | ||
| --- | ||
| sidebar_position: 1 | ||
| title: Configuration | ||
| --- | ||
|
|
||
| # Configuration | ||
|
|
||
| To configure `storybook-addon-badges`, you will use storybook's [parameters](https://storybook.js.org/docs/writing-stories/parameters). Badges uses 2 parameter keys: | ||
|
|
||
| - `badges` - Contains a simple string array of the badges to display. | ||
| - `badgesConfig` - Contains configuration for the badge styles, and options for the plugin | ||
|
|
||
| ## BadgesConfig | ||
|
|
||
| The `badgesConfig` parameter contains configuration options for the addon. It is recommended that you define this once in the [global parameters](https://storybook.js.org/docs/writing-stories/parameters#global-parameters), however this can be applied at the component and story level as well, to override the global values. | ||
|
|
||
| :::warning | ||
| Due to how Storybook's [inheritance](https://storybook.js.org/docs/writing-stories/parameters#rules-of-parameter-inheritance) works (objects are merged, array/boolean/number/string values are overridden): | ||
|
|
||
| - The values of `excludeTags`, `locations` and `useTags` will be completely overridden for that component/story, so you will need to define the complete value. | ||
| - The values for `badgeMap` and `baseStyle` will be merged (keys will only be added/overridden, not dropped), if you need to remove a value, you will need to explicitly set it to `undefined`. | ||
| ::: | ||
|
|
||
| The `badgesConfig` offers the following options: | ||
|
|
||
| | Option | Description | Docs | | ||
| | ------------- | -------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | | ||
| | `badgeMap` | A mapping object for providing custom badge configs. | [Create Custom Badges](./create-custom-badges.mdx) | | ||
| | `baseStyle` | The default style to use for badges | [Adding Styles](./adding-styles.mdx) | | ||
| | `excludeTags` | The storybook tags to prevent from creating badges. | [Using Tags](./using-tags.mdx) | | ||
| | `locations` | Default locations for badges to display | [Badge Locations](./badge-locations.mdx) | | ||
| | `useTags` | Whether to use storybook's [tags](https://storybook.js.org/docs/writing-stories/tags) to generate badges | [Using Tags](./using-tags.mdx) | | ||
|
|
||
|
|
||
| :::tip Using Typescript? | ||
| You can get type completion/validation in parameters by using the `BadgesConfig` type for the `badgesConfig` parameter. | ||
|
|
||
| ```ts title=".storybook/preview.ts" | ||
| import type { Preview } from '@storybook/[your-framework]'; | ||
| import type { BadgesConfig } from 'storybook-addon-badges'; | ||
|
|
||
| const preview: Preview = { | ||
| //...other preview config | ||
| parameters: { | ||
| //...other parameters | ||
| badges: ["wip"] as string[], | ||
| badgesConfig: { | ||
| badgeMap: { | ||
| MyCustomBadge: { | ||
| title: 'My Custom Badge', | ||
| } | ||
| } | ||
| } satisfies BadgesConfig; | ||
| } | ||
| } | ||
|
|
||
| export default preview; | ||
| ``` | ||
| ::: | ||
|
|
||
| ## Badges | ||
|
|
||
| The `badges` key is a simple array of badge names to apply. Due to how Storybook's parameters work, these will be overwritten by `badges` parameters at a higher specificity. For example: | ||
|
|
||
| - `badges` defined in [global parameters](https://storybook.js.org/docs/writing-stories/parameters#global-parameters) will apply to any component/story that does not define its own badges at the component/story level. | ||
| - `badges` defined in [component parameters]](https://storybook.js.org/docs/writing-stories/parameters#component-parameters) will override global values, and apply to any story for that component that does not define its own `badges`. | ||
| - `badges` defined in [story parameters](https://storybook.js.org/docs/writing-stories/parameters#story-parameters) will override any global or story `badges`. |
Oops, something went wrong.