diff --git a/docs/essentials/toolbars-and-globals.md b/docs/essentials/toolbars-and-globals.md index 04cb76024e21..901a23a758ad 100644 --- a/docs/essentials/toolbars-and-globals.md +++ b/docs/essentials/toolbars-and-globals.md @@ -6,9 +6,9 @@ Storybook ships with toolbar items to control the [viewport](./viewport.md) and ## Globals -Globals in Storybook represent “global” (as in not story-specific) inputs to the rendering of the story. As they aren’t specific to the story, they aren’t passed in the `args` argument to the story function (although they are accessible as `context.globals`), but typically you use them in decorators which apply to all stories. +Globals in Storybook represent “global” (as in not story-specific) inputs to the rendering of the story. As they aren’t specific to the story, they aren’t passed in the `args` argument to the story function (although they are accessible as `context.globals`), but typically you use them in decorators, which apply to all stories. -When the globals change, the story re-renders and the decorators rerun with the new values. The easiest way to change globals is to create a toolbar item for them. +When the globals change, the story re-renders, and the decorators rerun with the new values. The easiest way to change globals is to create a toolbar item for them. ## Global types and the toolbar annotation @@ -34,7 +34,7 @@ When you start your Storybook, you should see a new dropdown in your toolbar wit ## Create a decorator -We have a `global` defined, let's wire it up! We can consume our new `theme` global in a decorator using the `context.globals.theme` value. +We have a `global` implemented. Let's wire it up! We can consume our new `theme` global in a decorator using the `context.globals.theme` value. For example, suppose you are using `styled-components`. You can add a theme provider decorator to your [`.storybook/preview.js`](../configure/overview.md#configure-story-rendering) config: @@ -76,7 +76,7 @@ The icon element used in the examples loads the icons from the @storybook/addon-toolbars addon is required to use toolbars. The toolbars addon is included by default in @storybook/addon-essentials. -By adding the configuration element `right`, the text will be displayed on the right side in the toolbar menu, once you connect it to a decorator. +By adding the configuration element `right`, the text will be displayed on the right side in the toolbar menu once you connect it to a decorator. Here's a list of the configuration options available. @@ -84,15 +84,15 @@ Here's a list of the configuration options available. | --------- | :----: | :-------------------------------------------------------------: | :------: | | **value** | String | The string value of the menu that gets set in the globals | Yes | | **title** | String | The main text of the title | Yes | -| **left** | String | A string that gets shown in left side of the menu | No | -| **right** | String | A string that gets shown in right side of the menu | No | +| **left** | String | A string that gets shown on the left side of the menu | No | +| **right** | String | A string that gets displayed on the right side of the menu | No | | **icon** | String | An icon that gets shown in the toolbar if this item is selected | No | ## Consuming globals from within a story We recommend consuming globals from within a decorator and define a global setting for all stories. -But we're aware that sometimes it's more useful to use toolbar options in a per-story basis. +But we're aware that sometimes it's more beneficial to use toolbar options on a per-story basis. Using the example above, you can modify any story to retrieve the **Locale** `global` from the story context: @@ -100,8 +100,15 @@ Using the example above, you can modify any story to retrieve the **Locale** `gl @@ -115,7 +122,11 @@ In Storybook 6.0, if you set the global option `passArgsFirst: false` for backwa @@ -125,7 +136,7 @@ In Storybook 6.0, if you set the global option `passArgsFirst: false` for backwa ## Consuming globals from within an addon -If you're working on a Storybook addon and you need to retrieve globals. You can do so, the `@storybook/api` package provides a hook for this scenario, you can use the [`useGlobals()`](../addons/addons-api.md#useglobals) hook to retrieve any globals you want. +If you're working on a Storybook addon and you need to retrieve globals, you can do so. The `@storybook/api` package provides a hook for this scenario. You can use the [`useGlobals()`](../addons/addons-api.md#useglobals) hook to retrieve any globals you want. Using the ThemeProvider example above, you could expand it to display which current theme is being shown inside a panel like so: @@ -141,7 +152,7 @@ Using the ThemeProvider example above, you could expand it to display which curr ## Updating globals from within an addon -If you're working on a Storybook addon that needs to update the global and refreshes the UI, you can do so. As mentioned previously, the `@storybook/api` package provides the necessary hook for this scenario. You can use the `updateGlobals` function to update any global values you want. +If you're working on a Storybook addon that needs to update the global and refreshes the UI, you can do so. As mentioned previously, the `@storybook/api` package provides the necessary hook for this scenario. You can use the `updateGlobals` function to update any global values you want. Also, you can use the `@storybook/addons` and `@storybook/core-events` packages together to trigger the refresh. @@ -155,4 +166,4 @@ For example, if you were working on a [toolbar addon](../addons/addon-types.md#t ]} /> - + \ No newline at end of file diff --git a/docs/snippets/angular/my-component-story-use-globaltype-backwards-compat.ts.mdx b/docs/snippets/angular/my-component-story-use-globaltype-backwards-compat.ts.mdx new file mode 100644 index 000000000000..d2fe8932164c --- /dev/null +++ b/docs/snippets/angular/my-component-story-use-globaltype-backwards-compat.ts.mdx @@ -0,0 +1,10 @@ +```ts +// MyComponent.stories.ts + +export const StoryWithLocale = ({ globals: { locale } }) => { + const caption = getCaptionForLocale(locale); + return { + template: `

${caption}

`, + }; +}; +``` \ No newline at end of file diff --git a/docs/snippets/angular/my-component-story-use-globaltype.mdx.mdx b/docs/snippets/angular/my-component-story-use-globaltype.mdx.mdx new file mode 100644 index 000000000000..eb1fd520ddc1 --- /dev/null +++ b/docs/snippets/angular/my-component-story-use-globaltype.mdx.mdx @@ -0,0 +1,23 @@ +```md + + +export const getCaptionForLocale = (locale) => { + switch(locale) { + case 'es': return 'Hola!'; + case 'fr': return 'Bonjour!'; + case 'kr': return '안녕하세요!'; + case 'zh': return '你好!'; + default: + return 'Hello!'; + } +}; + + + {(args, { globals: { locale } }) => { + const caption = getCaptionForLocale(locale); + return { + template: `

${caption}

`, + }; + }} +
+``` \ No newline at end of file diff --git a/docs/snippets/angular/my-component-story-use-globaltype.ts.mdx b/docs/snippets/angular/my-component-story-use-globaltype.ts.mdx new file mode 100644 index 000000000000..505764d13be0 --- /dev/null +++ b/docs/snippets/angular/my-component-story-use-globaltype.ts.mdx @@ -0,0 +1,25 @@ +```ts +// MyComponent.stories.ts + +const getCaptionForLocale = (locale) => { + switch (locale) { + case 'es': + return 'Hola!'; + case 'fr': + return 'Bonjour!'; + case 'kr': + return '안녕하세요!'; + case 'zh': + return '你好!'; + default: + return 'Hello!'; + } +}; + +export const StoryWithLocale = (args, { globals: { locale } }) => { + const caption = getCaptionForLocale(locale); + return { + template: `

${caption}

`, + }; +}; +``` \ No newline at end of file diff --git a/docs/snippets/common/my-component-story-use-globaltype-backwards-compat.js.mdx b/docs/snippets/react/my-component-story-use-globaltype-backwards-compat.js.mdx similarity index 100% rename from docs/snippets/common/my-component-story-use-globaltype-backwards-compat.js.mdx rename to docs/snippets/react/my-component-story-use-globaltype-backwards-compat.js.mdx diff --git a/docs/snippets/common/my-component-story-use-globaltype.js.mdx b/docs/snippets/react/my-component-story-use-globaltype.js.mdx similarity index 99% rename from docs/snippets/common/my-component-story-use-globaltype.js.mdx rename to docs/snippets/react/my-component-story-use-globaltype.js.mdx index d6aaff1e96dc..3964c64d7179 100644 --- a/docs/snippets/common/my-component-story-use-globaltype.js.mdx +++ b/docs/snippets/react/my-component-story-use-globaltype.js.mdx @@ -10,7 +10,7 @@ const getCaptionForLocale = (locale) => { default: return 'Hello!'; } -} +}; export const StoryWithLocale = (args, { globals: { locale } }) => { const caption = getCaptionForLocale(locale); diff --git a/docs/snippets/common/my-component-story-use-globaltype.mdx.mdx b/docs/snippets/react/my-component-story-use-globaltype.mdx.mdx similarity index 99% rename from docs/snippets/common/my-component-story-use-globaltype.mdx.mdx rename to docs/snippets/react/my-component-story-use-globaltype.mdx.mdx index e175189af543..9b4b2a5e9ea9 100644 --- a/docs/snippets/common/my-component-story-use-globaltype.mdx.mdx +++ b/docs/snippets/react/my-component-story-use-globaltype.mdx.mdx @@ -10,7 +10,7 @@ export const getCaptionForLocale = (locale) => { default: return 'Hello!'; } -} +}; {(args, { globals: { locale } }) => { diff --git a/docs/snippets/svelte/my-component-story-use-globaltype-backwards-compat.js.mdx b/docs/snippets/svelte/my-component-story-use-globaltype-backwards-compat.js.mdx new file mode 100644 index 000000000000..af44200a17fa --- /dev/null +++ b/docs/snippets/svelte/my-component-story-use-globaltype-backwards-compat.js.mdx @@ -0,0 +1,13 @@ +```js +// MyComponent.stories.js + +export const StoryWithLocale = ({ globals: { locale } }) => { + const caption = getCaptionForLocale(locale); + return { + component: SampleComponent, + props: { + locale: caption, + }, + }; +}; +``` \ No newline at end of file diff --git a/docs/snippets/svelte/my-component-story-use-globaltype.js.mdx b/docs/snippets/svelte/my-component-story-use-globaltype.js.mdx new file mode 100644 index 000000000000..8ba057256fd4 --- /dev/null +++ b/docs/snippets/svelte/my-component-story-use-globaltype.js.mdx @@ -0,0 +1,28 @@ +```js +// MyComponent.stories.js + +const getCaptionForLocale = (locale) => { + switch (locale) { + case 'es': + return 'Hola!'; + case 'fr': + return 'Bonjour!'; + case 'kr': + return '안녕하세요!'; + case 'zh': + return '你好!'; + default: + return 'Hello!'; + } +}; + +export const StoryWithLocale = (args, { globals: { locale } }) => { + const caption = getCaptionForLocale(locale); + return { + component: SampleComponent, + props: { + locale: caption, + }, + }; +}; +``` \ No newline at end of file diff --git a/docs/snippets/svelte/my-component-story-use-globaltype.mdx.mdx b/docs/snippets/svelte/my-component-story-use-globaltype.mdx.mdx new file mode 100644 index 000000000000..7c204d32ceb2 --- /dev/null +++ b/docs/snippets/svelte/my-component-story-use-globaltype.mdx.mdx @@ -0,0 +1,26 @@ +```md + + +export const getCaptionForLocale = (locale) => { + switch(locale) { + case 'es': return 'Hola!'; + case 'fr': return 'Bonjour!'; + case 'kr': return '안녕하세요!'; + case 'zh': return '你好!'; + default: + return 'Hello!'; + } +}; + + + {(args, { globals: { locale } }) => { + const caption = getCaptionForLocale(locale); + return { + component: MyComponent, + props: { + locale: caption, + }, + }; + }} + +``` \ No newline at end of file diff --git a/docs/snippets/vue/my-component-story-use-globaltype-backwards-compat.js.mdx b/docs/snippets/vue/my-component-story-use-globaltype-backwards-compat.js.mdx new file mode 100644 index 000000000000..5c880243841a --- /dev/null +++ b/docs/snippets/vue/my-component-story-use-globaltype-backwards-compat.js.mdx @@ -0,0 +1,10 @@ +```js +// MyComponent.stories.js + +export const StoryWithLocale = ({ globals: { locale } }) => { + const caption = getCaptionForLocale(locale); + return { + template: `

${caption}

`, + }; +}; +``` \ No newline at end of file diff --git a/docs/snippets/vue/my-component-story-use-globaltype.js.mdx b/docs/snippets/vue/my-component-story-use-globaltype.js.mdx new file mode 100644 index 000000000000..555575034acf --- /dev/null +++ b/docs/snippets/vue/my-component-story-use-globaltype.js.mdx @@ -0,0 +1,25 @@ +```js +// MyComponent.stories.js + +const getCaptionForLocale = (locale) => { + switch (locale) { + case 'es': + return 'Hola!'; + case 'fr': + return 'Bonjour!'; + case 'kr': + return '안녕하세요!'; + case 'zh': + return '你好!'; + default: + return 'Hello!'; + } +}; + +export const StoryWithLocale = (args, { globals: { locale } }) => { + const caption = getCaptionForLocale(locale); + return { + template: `

${caption}

`, + }; +}; +``` \ No newline at end of file diff --git a/docs/snippets/vue/my-component-story-use-globaltype.mdx.mdx b/docs/snippets/vue/my-component-story-use-globaltype.mdx.mdx new file mode 100644 index 000000000000..eb1fd520ddc1 --- /dev/null +++ b/docs/snippets/vue/my-component-story-use-globaltype.mdx.mdx @@ -0,0 +1,23 @@ +```md + + +export const getCaptionForLocale = (locale) => { + switch(locale) { + case 'es': return 'Hola!'; + case 'fr': return 'Bonjour!'; + case 'kr': return '안녕하세요!'; + case 'zh': return '你好!'; + default: + return 'Hello!'; + } +}; + + + {(args, { globals: { locale } }) => { + const caption = getCaptionForLocale(locale); + return { + template: `

${caption}

`, + }; + }} +
+``` \ No newline at end of file diff --git a/docs/snippets/web-components/my-component-story-use-globaltype-backwards-compat.js.mdx b/docs/snippets/web-components/my-component-story-use-globaltype-backwards-compat.js.mdx new file mode 100644 index 000000000000..00291479a6b4 --- /dev/null +++ b/docs/snippets/web-components/my-component-story-use-globaltype-backwards-compat.js.mdx @@ -0,0 +1,10 @@ +```js +// MyComponent.stories.js + +import { html } from 'lit-html'; + +export const StoryWithLocale = ({ globals: { locale } }) => { + const caption = getCaptionForLocale(locale); + return html`

${caption}

`; +}; +``` \ No newline at end of file diff --git a/docs/snippets/web-components/my-component-story-use-globaltype.js.mdx b/docs/snippets/web-components/my-component-story-use-globaltype.js.mdx new file mode 100644 index 000000000000..63873a57924b --- /dev/null +++ b/docs/snippets/web-components/my-component-story-use-globaltype.js.mdx @@ -0,0 +1,25 @@ +```js +// MyComponent.stories.js + +import { html } from 'lit-html'; + +const getCaptionForLocale = (locale) => { + switch (locale) { + case 'es': + return 'Hola!'; + case 'fr': + return 'Bonjour!'; + case 'kr': + return '안녕하세요!'; + case 'zh': + return '你好!'; + default: + return 'Hello!'; + } +}; + +export const StoryWithLocale = ({ propA, propB }, { globals: { locale } }) => { + const caption = getCaptionForLocale(locale); + return html`

${caption}

`; +}; +``` \ No newline at end of file