From f9b837e3131b879c440ff1d7ca32157ef5a8f2e7 Mon Sep 17 00:00:00 2001
From: jonniebigodes <joaocontadesenvolvimento@gmail.com>
Date: Tue, 13 Jul 2021 20:14:31 +0100
Subject: [PATCH] fix toolbar docs with better examples and minor polish

---
 docs/essentials/toolbars-and-globals.md       | 37 ++++++++++++-------
 ...ory-use-globaltype-backwards-compat.ts.mdx | 10 +++++
 .../my-component-story-use-globaltype.mdx.mdx | 23 ++++++++++++
 .../my-component-story-use-globaltype.ts.mdx  | 25 +++++++++++++
 ...ory-use-globaltype-backwards-compat.js.mdx |  0
 .../my-component-story-use-globaltype.js.mdx  |  2 +-
 .../my-component-story-use-globaltype.mdx.mdx |  2 +-
 ...ory-use-globaltype-backwards-compat.js.mdx | 13 +++++++
 .../my-component-story-use-globaltype.js.mdx  | 28 ++++++++++++++
 .../my-component-story-use-globaltype.mdx.mdx | 26 +++++++++++++
 ...ory-use-globaltype-backwards-compat.js.mdx | 10 +++++
 .../my-component-story-use-globaltype.js.mdx  | 25 +++++++++++++
 .../my-component-story-use-globaltype.mdx.mdx | 23 ++++++++++++
 ...ory-use-globaltype-backwards-compat.js.mdx | 10 +++++
 .../my-component-story-use-globaltype.js.mdx  | 25 +++++++++++++
 15 files changed, 244 insertions(+), 15 deletions(-)
 create mode 100644 docs/snippets/angular/my-component-story-use-globaltype-backwards-compat.ts.mdx
 create mode 100644 docs/snippets/angular/my-component-story-use-globaltype.mdx.mdx
 create mode 100644 docs/snippets/angular/my-component-story-use-globaltype.ts.mdx
 rename docs/snippets/{common => react}/my-component-story-use-globaltype-backwards-compat.js.mdx (100%)
 rename docs/snippets/{common => react}/my-component-story-use-globaltype.js.mdx (99%)
 rename docs/snippets/{common => react}/my-component-story-use-globaltype.mdx.mdx (99%)
 create mode 100644 docs/snippets/svelte/my-component-story-use-globaltype-backwards-compat.js.mdx
 create mode 100644 docs/snippets/svelte/my-component-story-use-globaltype.js.mdx
 create mode 100644 docs/snippets/svelte/my-component-story-use-globaltype.mdx.mdx
 create mode 100644 docs/snippets/vue/my-component-story-use-globaltype-backwards-compat.js.mdx
 create mode 100644 docs/snippets/vue/my-component-story-use-globaltype.js.mdx
 create mode 100644 docs/snippets/vue/my-component-story-use-globaltype.mdx.mdx
 create mode 100644 docs/snippets/web-components/my-component-story-use-globaltype-backwards-compat.js.mdx
 create mode 100644 docs/snippets/web-components/my-component-story-use-globaltype.js.mdx

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 <code>icon</code> element used in the examples loads the icons from the <cod
   The <code>@storybook/addon-toolbars</code> addon is required to use toolbars. The toolbars addon is included by default in <code>@storybook/addon-essentials</code>.
 </div>
 
-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
 
 <CodeSnippets
   paths={[
-    'common/my-component-story-use-globaltype.js.mdx',
-    'common/my-component-story-use-globaltype.mdx.mdx',
+    'react/my-component-story-use-globaltype.js.mdx',
+    'react/my-component-story-use-globaltype.mdx.mdx',
+    'vue/my-component-story-use-globaltype.js.mdx',
+    'vue/my-component-story-use-globaltype.mdx.mdx',
+    'angular/my-component-story-use-globaltype.ts.mdx',
+    'angular/my-component-story-use-globaltype.mdx.mdx',
+    'svelte/my-component-story-use-globaltype.js.mdx',
+    'svelte/my-component-story-use-globaltype.mdx.mdx',
+    'web-components/my-component-story-use-globaltype.js.mdx',
   ]}
 />
 
@@ -115,7 +122,11 @@ In Storybook 6.0, if you set the global option `passArgsFirst: false` for backwa
 
 <CodeSnippets
   paths={[
-    'common/my-component-story-use-globaltype-backwards-compat.js.mdx',
+    'react/my-component-story-use-globaltype-backwards-compat.js.mdx',
+    'vue/my-component-story-use-globaltype-backwards-compat.js.mdx',
+    'angular/my-component-story-use-globaltype-backwards-compat.ts.mdx',
+    'svelte/my-component-story-use-globaltype-backwards-compat.js.mdx',
+    'web-components/my-component-story-use-globaltype-backwards-compat.js.mdx',
   ]}
 />
 
@@ -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
   ]}
 />
 
-<!-- prettier-ignore-end -->
+<!-- prettier-ignore-end -->
\ 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: `<p>${caption}</p>`,
+  };
+};
+```
\ 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
+<!-- MyComponent.stories.mdx -->
+
+export const getCaptionForLocale = (locale) => {
+  switch(locale) {
+    case 'es': return 'Hola!';
+    case 'fr': return 'Bonjour!';
+    case 'kr': return '안녕하세요!';
+    case 'zh': return '你好!';
+    default:
+      return 'Hello!';
+  }
+};
+
+<Story name="StoryWithLocale">
+  {(args, { globals: { locale } }) => {
+    const caption = getCaptionForLocale(locale);
+    return {
+      template: `<p>${caption}</p>`,
+    };
+  }}
+</Story>
+```
\ 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: `<p>${caption}</p>`,
+  };
+};
+```
\ 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!';
   }
-}
+};
 
 <Story name="StoryWithLocale">
   {(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
+<!-- MyComponent.stories.mdx -->
+
+export const getCaptionForLocale = (locale) => {
+  switch(locale) {
+    case 'es': return 'Hola!';
+    case 'fr': return 'Bonjour!';
+    case 'kr': return '안녕하세요!';
+    case 'zh': return '你好!';
+    default:
+      return 'Hello!';
+  }
+};
+
+<Story name="StoryWithLocale">
+  {(args, { globals: { locale } }) => {
+    const caption = getCaptionForLocale(locale);
+    return {
+      component: MyComponent,
+      props: {
+        locale: caption,
+      },
+    };
+  }}
+</Story>
+```
\ 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: `<p>${caption}</p>`,
+  };
+};
+```
\ 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: `<p>${caption}</p>`,
+  };
+};
+```
\ 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
+<!-- MyComponent.stories.mdx -->
+
+export const getCaptionForLocale = (locale) => {
+  switch(locale) {
+    case 'es': return 'Hola!';
+    case 'fr': return 'Bonjour!';
+    case 'kr': return '안녕하세요!';
+    case 'zh': return '你好!';
+    default:
+      return 'Hello!';
+  }
+};
+
+<Story name="StoryWithLocale">
+  {(args, { globals: { locale } }) => {
+    const caption = getCaptionForLocale(locale);
+    return {
+      template: `<p>${caption}</p>`,
+    };
+  }}
+</Story>
+```
\ 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`<p>${caption}</p>`;
+};
+```
\ 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`<p>${caption}</p>`;
+};
+```
\ No newline at end of file