Docs: Updates documentation and examples for Highlight

code/addons/highlight/README.md

@@ -4,61 +4,143 @@ Storybook addon allows for highlighting specific DOM nodes within your story.
 
 Use it to call attention to particular parts of the story. Or use it to enhance other addons that you might be building. For example, [Accessibility](https://storybook.js.org/addons/@storybook/addon-a11y/) addon uses it to highlight DOM nodes that are failing accessibility checks.
 
-![](https://user-images.githubusercontent.com/42671/160146801-179eaa79-fff8-4bff-b17c-9262fdc94918.png)
+![Story with highlight](./docs/highlight.png)
 
 ## Usage
 
-This addon requires Storybook 6.5 or later. Highlight is part of [essentials](https://storybook.js.org/docs/react/essentials/introduction) and so is installed in all new Storybooks by default. If you need to add it to your Storybook, you can run:
+This addon requires Storybook 6.5 or later. Highlight is part of [essentials](https://storybook.js.org/docs/react/essentials/introduction) and so is installed in all new Storybooks by default. If you need to add it to your Storybook, you can run the following command:
+
+yarn:
+
+```sh
+yarn add --dev @storybook/addon-highlight
+```
+
+npm:
 
 ```sh
-npm i -D @storybook/addon-highlight
+npm install @storybook/addon-highlight --save-dev
 ```
 
-Add `"@storybook/addon-highlight"` to the addons array in your `.storybook/main.js`:
+pnpm:
+
+```sh
+pnpm add --save-dev @storybook/addon-highlight
+```
+
+Add `"@storybook/addon-highlight"` to the addons array in your `.storybook/main.js|ts`:
+
+```ts
+// .storybook/main.ts
 
-```js
-export default {
+// Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite)
+import type { StorybookConfig } from '@storybook/your-framework';
+
+const config: StorybookConfig = {
   addons: ['@storybook/addon-highlight'],
 };
+
+export default config;
 ```
 
-### Apply or clear highlights
+### Highlighting DOM Elements
 
-Highlight DOM nodes by emitting the `HIGHLIGHT` event from within a story or an addon. The event payload must contain a list of selectors you want to highlight.
+Highlight DOM nodes by emitting the `HIGHLIGHT` event from within a story or an addon. The event payload must contain an `elements` property assigned to an array of selectors matching the elements you want to highlight.
 
-```js
-import React, { useEffect } from 'react';
-import { useChannel } from '@storybook/preview-api';
-import { HIGHLIGHT, RESET_HIGHLIGHT } from '@storybook/addon-highlight';
-import { MyComponent } from './MyComponent';
+```ts
+// MyComponent.stories.ts
 
-export default { component: MyComponent };
+import type { Meta, StoryObj } from '@storybook/react';
+import { useChannel } from '@storybook/preview-api';
+import { HIGHLIGHT } from '@storybook/addon-highlight';
 
-export const MyStory = () => {
-  const emit = useChannel({});
+import { MyComponent } from './MyComponent';
 
-  useEffect(() => {
-    emit(HIGHLIGHT, {
-      elements: ['.title', '.subtitle'],
-    });
-  }, []);
+const meta: Meta<typeof MyComponent> = {
+  component: MyComponent,
+};
 
-  return <MyComponent />;
+export default meta;
+type Story = StoryObj<typeof MyComponent>;
+
+export const Highlighted: Story = {
+  decorators: [
+    (storyFn) => {
+      const emit = useChannel({});
+      emit(HIGHLIGHT, {
+        elements: ['.title', '.subtitle'],
+      });
+      return storyFn();
+    },
+  ],
 };
 ```
 
+### Reset highlighted elements
+
 Highlights are automatically cleared when the story changes. You can also manually clear them by emitting the `RESET_HIGHLIGHT` event.
 
-```js
-emit(RESET_HIGHLIGHT);
+```ts
+// MyComponent.stories.ts|tsx
+
+import type { Meta, StoryObj } from '@storybook/react';
+import { useChannel } from '@storybook/preview-api';
+import { HIGHLIGHT, RESET_HIGHLIGHT } from '@storybook/addon-highlight';
+
+import { MyComponent } from './MyComponent';
+
+const meta: Meta<typeof MyComponent> = {
+  component: MyComponent,
+};
+
+export default meta;
+type Story = StoryObj<typeof MyComponent>;
+
+export const ResetHighlight: Story = {
+  decorators: [
+    (storyFn) => {
+      const emit = useChannel({});
+      emit(RESET_HIGHLIGHT); //👈 Remove previously highlighted elements
+      emit(HIGHLIGHT, {
+        elements: ['header', 'section', 'footer'],
+      });
+      return storyFn();
+    },
+  ],
+};
 ```
 
 ### Customize style
 
-```js
-emit(HIGHLIGHT, {
-  elements: ['.title', '.subtitle'],
-  color: 'red',
-  style: 'solid', // 'dotted' | 'dashed' | 'solid' | 'double'
-});
+The addon applies a standard style to the highlighted elements you've enabled for the story. However, you can enable your custom style by extending the payload object and providing a `color` and/or `style` properties. For example:
+
+```ts
+// MyComponent.stories.ts
+
+import type { Meta, StoryObj } from '@storybook/react';
+import { useChannel } from '@storybook/preview-api';
+import { HIGHLIGHT } from '@storybook/addon-highlight';
+
+import { MyComponent } from './MyComponent';
+
+const meta: Meta<typeof MyComponent> = {
+  component: MyComponent,
+};
+
+export default meta;
+type Story = StoryObj<typeof MyComponent>;
+
+export const StyledHighlight: Story = {
+  decorators: [
+    (storyFn) => {
+      const emit = useChannel({});
+      emit(HIGHLIGHT, {
+        elements: ['.title', '.subtitle'],
+        color: 'red',
+        style: 'solid', // 'dotted' | 'dashed' | 'solid' | 'double'
+      });
+      return storyFn();
+    },
+  ],
+};
 ```

docs/essentials/highlight.md

@@ -2,48 +2,71 @@
 title: 'Highlight'
 ---
 
-Storybook's [Highlight](https://storybook.js.org/addons/@storybook/addon-highlight/) addon allows you to highlight specific DOM nodes within your story. You can use it to call attention to particular parts of the story.
+Storybook's [Highlight](https://storybook.js.org/addons/@storybook/addon-highlight/) addon is a helpful tool for visually debugging your components, allowing you to highlight specific DOM nodes within your story when used as a standalone addon or enhancing other addons such as the [Accessibility addon](https://storybook.js.org/addons/@storybook/addon-a11y/) to inform you of accessibility issues within your components.
 
-![](highlight.png)
+![Story with highlighted elements](./highlight.png)
 
-This addon can be used to enhance other addons. For example, [Accessibility](https://storybook.js.org/addons/@storybook/addon-a11y/) addon uses it to highlight DOM nodes that are failing accessibility checks.
+## Highlighting DOM Elements
 
-## Apply or clear highlights
-
-Highlight DOM nodes by emitting the `HIGHLIGHT` event from within a story or an addon. The event payload must contain a list of selectors you want to highlight.
+To highlight DOM elements with the addon, you'll need to emit the `HIGHLIGHT` event from within a story or an addon. The event payload must contain an `elements` property assigned to an array of selectors matching the elements you want to highlight. For example:
 
 <!-- prettier-ignore-start -->
 
 <CodeSnippets
   paths={[
     'react/component-story-highlight-addon.js.mdx',
+    'react/component-story-highlight-addon.ts.mdx',
     'angular/component-story-highlight-addon.ts.mdx',
     'vue/component-story-highlight-addon.js.mdx',
+    'vue/component-story-highlight-addon.ts.mdx',
     'web-components/component-story-highlight-addon.js.mdx',
+    'web-components/component-story-highlight-addon.ts.mdx',
   ]}
 />
 
 <!-- prettier-ignore-end -->
 
-Highlights are automatically cleared when the story changes. You can also manually clear them by emitting the `RESET_HIGHLIGHT` event.
+<div class="aside">
+
+💡 We recommend choosing the most specific selector possible to avoid highlighting elements other addons use. This is because the addon tries to match selectors against the entire DOM tree.
+
+</div>
+
+### Reset highlighted elements
+
+Out of the box, Storybook automatically removes highlighted elements when transitioning between stories. However, if you need to clear them manually, you can emit the `RESET_HIGHLIGHT` event from within a story or an addon. For example:
 
 <!-- prettier-ignore-start -->
 
 <CodeSnippets
   paths={[
-    'common/addon-highlight-reset.js.mdx',
+    'react/addon-highlight-reset.js.mdx',
+    'react/addon-highlight-reset.ts.mdx',
+    'angular/addon-highlight-reset.ts.mdx',
+    'vue/addon-highlight-reset.js.mdx',
+    'vue/addon-highlight-reset.ts.mdx',
+    'web-components/addon-highlight-reset.js.mdx',
+    'web-components/addon-highlight-reset.ts.mdx',
   ]}
 />
 
 <!-- prettier-ignore-end -->
 
 ## Customize style
 
+By default, the addon applies a standard style to the highlighted elements you've enabled for the story. However, you can enable your custom style by extending the payload object and providing a `color` and/or `style` properties. For example:
+
 <!-- prettier-ignore-start -->
 
 <CodeSnippets
   paths={[
-    'common/addon-highlight-customize.js.mdx',
+    'react/highlight-addon-custom-style.js.mdx',
+    'react/highlight-addon-custom-style.ts.mdx',
+    'angular/highlight-addon-custom-style.ts.mdx',
+    'vue/highlight-addon-custom-style.js.mdx',
+    'vue/highlight-addon-custom-style.ts.mdx',
+    'web-components/highlight-addon-custom-style.js.mdx',
+    'web-components/highlight-addon-custom-style.ts.mdx',
   ]}
 />
 

docs/snippets/angular/addon-highlight-reset.ts.mdx

@@ -0,0 +1,30 @@
+```ts
+// MyComponent.stories.ts
+
+import type { Meta, StoryObj } from '@storybook/angular';
+import { componentWrapperDecorator } from '@storybook/angular';
+import { useChannel } from '@storybook/preview-api';
+import { HIGHLIGHT, RESET_HIGHLIGHT } from '@storybook/addon-highlight';
+
+import { MyComponent } from './MyComponent.component';
+
+const meta: Meta<MyComponent> = {
+  component: MyComponent,
+};
+
+export default meta;
+type Story = StoryObj<MyComponent>;
+
+export const ResetHighlight: Story = {
+  decorators: [
+    componentWrapperDecorator((story) => {
+      const emit = useChannel({});
+      emit(RESET_HIGHLIGHT); //👈 Remove previously highlighted elements
+      emit(HIGHLIGHT, {
+        elements: ['header', 'section', 'footer'],
+      });
+      return story;
+    }),
+  ],
+};
+```

docs/snippets/angular/component-story-highlight-addon.ts.mdx

@@ -1,34 +1,29 @@
 ```ts
-// Card.stories.ts
+// MyComponent.stories.ts
 
-import { componentWrapperDecorator } from '@storybook/angular';
 import type { Meta, StoryObj } from '@storybook/angular';
+import { componentWrapperDecorator } from '@storybook/angular';
 import { useChannel } from '@storybook/preview-api';
-import { HIGHLIGHT, RESET_HIGHLIGHT } from '@storybook/addon-highlight';
-import { Card } from './card.component';
+import { HIGHLIGHT } from '@storybook/addon-highlight';
 
-const meta: Meta<Card> = {
-  /* 👇 The title prop is optional.
-   * See https://storybook.js.org/docs/angular/configure/overview#configure-story-loading
-   * to learn how to generate automatic titles
-   */
-  title: 'Card',
-  component: Card,
+import { MyComponent } from './MyComponent.component';
+
+const meta: Meta<MyComponent> = {
+  component: MyComponent,
 };
 
 export default meta;
-type Story = StoryObj<Card>;
+type Story = StoryObj<MyComponent>;
 
-export const Default: Story = (args) => ({
-  template: '<app-card></app-card>',
+export const Highlighted: Story = {
   decorators: [
     componentWrapperDecorator((story) => {
       const emit = useChannel({});
       emit(HIGHLIGHT, {
-        elements: ['.title', '.subtitle'],
+        elements: ['h2', 'a', '.storybook-button'],
       });
       return story;
     }),
   ],
-});
+};
 ```

docs/snippets/angular/highlight-addon-custom-style.ts.mdx

@@ -0,0 +1,31 @@
+```ts
+// MyComponent.stories.ts
+
+import type { Meta, StoryObj } from '@storybook/angular';
+import { componentWrapperDecorator } from '@storybook/angular';
+import { useChannel } from '@storybook/preview-api';
+import { HIGHLIGHT } from '@storybook/addon-highlight';
+
+import { MyComponent } from './MyComponent.component';
+
+const meta: Meta<MyComponent> = {
+  component: MyComponent,
+};
+
+export default meta;
+type Story = StoryObj<MyComponent>;
+
+export const StyledHighlight: Story = {
+  decorators: [
+    componentWrapperDecorator((story) => {
+      const emit = useChannel({});
+      emit(HIGHLIGHT, {
+        elements: ['h2', 'a', '.storybook-button'],
+        color: 'blue',
+        style: 'double', // 'dotted' | 'dashed' | 'solid' | 'double'
+      });
+      return story;
+    }),
+  ],
+};
+```