@storybook/addon-highlight 7.3.2 → 7.4.0-alpha.1

package/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();
+    },
+  ],
+};
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@storybook/addon-highlight",
-  "version": "7.3.2",
+  "version": "7.4.0-alpha.1",
   "description": "Highlight DOM nodes within your stories",
   "keywords": [
     "storybook-addons",
@@ -54,16 +54,17 @@
     "dist/**/*",
     "README.md",
     "*.js",
-    "*.d.ts"
+    "*.d.ts",
+    "!src/**/*"
   ],
   "scripts": {
     "check": "../../../scripts/prepare/check.ts",
     "prep": "../../../scripts/prepare/bundle.ts"
   },
   "dependencies": {
-    "@storybook/core-events": "7.3.2",
+    "@storybook/core-events": "7.4.0-alpha.1",
     "@storybook/global": "^5.0.0",
-    "@storybook/preview-api": "7.3.2"
+    "@storybook/preview-api": "7.4.0-alpha.1"
   },
   "devDependencies": {
     "@types/webpack-env": "^1.16.0",