Essentials: Add highlight addon

addons/a11y/package.json

@@ -45,6 +45,7 @@
     "prepare": "node ../../scripts/prepare.js"
   },
   "dependencies": {
+    "@storybook/addon-highlight": "6.5.0-alpha.50",
     "@storybook/addons": "6.5.0-alpha.50",
     "@storybook/api": "6.5.0-alpha.50",
     "@storybook/channels": "6.5.0-alpha.50",

addons/a11y/preset.js

@@ -3,11 +3,7 @@ function managerEntries(entry = []) {
 }
 
 function config(entry = []) {
-  return [
-    ...entry,
-    require.resolve('./dist/esm/a11yRunner'),
-    require.resolve('./dist/esm/a11yHighlight'),
-  ];
+  return [...entry, require.resolve('./dist/esm/a11yRunner')];
 }
 
 module.exports = { managerEntries, config };

addons/a11y/src/components/A11yContext.test.tsx

@@ -3,6 +3,7 @@ import { AxeResults } from 'axe-core';
 import { render, act } from '@testing-library/react';
 import * as api from '@storybook/api';
 import { STORY_CHANGED } from '@storybook/core-events';
+import { HIGHLIGHT } from '@storybook/addon-highlight';
 
 import { A11yContextProvider, useA11yContext } from './A11yContext';
 import { EVENTS } from '../constants';
@@ -95,7 +96,7 @@ describe('A11YPanel', () => {
     const { rerender } = render(<A11yContextProvider active />);
     rerender(<A11yContextProvider active={false} />);
     expect(emit).toHaveBeenLastCalledWith(
-      EVENTS.HIGHLIGHT,
+      HIGHLIGHT,
       expect.objectContaining({
         color: expect.any(String),
         elements: [],

addons/a11y/src/components/A11yContext.tsx

@@ -3,6 +3,7 @@ import { themes, convert } from '@storybook/theming';
 import { Result } from 'axe-core';
 import { useChannel, useStorybookState } from '@storybook/api';
 import { STORY_CHANGED, STORY_RENDERED } from '@storybook/core-events';
+import { HIGHLIGHT } from '@storybook/addon-highlight';
 import { EVENTS } from '../constants';
 
 interface Results {
@@ -76,7 +77,7 @@ export const A11yContextProvider: React.FC<A11yContextProviderProps> = ({ active
   const handleReset = React.useCallback(() => {
     setTab(0);
     setResults(defaultResult);
-    // Highlights is cleared by a11yHighlights.ts
+    // Highlights is cleared by addon-highlight
   }, []);
 
   const emit = useChannel({
@@ -85,7 +86,7 @@ export const A11yContextProvider: React.FC<A11yContextProviderProps> = ({ active
   });
 
   React.useEffect(() => {
-    emit(EVENTS.HIGHLIGHT, { elements: highlighted, color: colorsByType[tab] });
+    emit(HIGHLIGHT, { elements: highlighted, color: colorsByType[tab] });
   }, [highlighted, tab]);
 
   React.useEffect(() => {

addons/a11y/src/constants.ts

@@ -1,12 +1,10 @@
 export const ADDON_ID = 'storybook/a11y';
 export const PANEL_ID = `${ADDON_ID}/panel`;
 export const PARAM_KEY = `a11y`;
-export const HIGHLIGHT_STYLE_ID = 'a11yHighlight';
 const RESULT = `${ADDON_ID}/result`;
 const REQUEST = `${ADDON_ID}/request`;
 const RUNNING = `${ADDON_ID}/running`;
 const ERROR = `${ADDON_ID}/error`;
 const MANUAL = `${ADDON_ID}/manual`;
-const HIGHLIGHT = `${ADDON_ID}/highlight`;
 
-export const EVENTS = { RESULT, REQUEST, RUNNING, ERROR, MANUAL, HIGHLIGHT };
+export const EVENTS = { RESULT, REQUEST, RUNNING, ERROR, MANUAL };

addons/essentials/package.json

@@ -43,6 +43,7 @@
     "@storybook/addon-backgrounds": "6.5.0-alpha.50",
     "@storybook/addon-controls": "6.5.0-alpha.50",
     "@storybook/addon-docs": "6.5.0-alpha.50",
+    "@storybook/addon-highlight": "6.5.0-alpha.50",
     "@storybook/addon-measure": "6.5.0-alpha.50",
     "@storybook/addon-outline": "6.5.0-alpha.50",
     "@storybook/addon-toolbars": "6.5.0-alpha.50",

addons/essentials/src/index.ts

@@ -37,7 +37,17 @@ export function addons(options: PresetOptions = {}) {
 
   const main = requireMain(options.configDir);
   return (
-    ['docs', 'controls', 'actions', 'backgrounds', 'viewport', 'toolbars', 'measure', 'outline']
+    [
+      'docs',
+      'controls',
+      'actions',
+      'backgrounds',
+      'viewport',
+      'toolbars',
+      'measure',
+      'outline',
+      'highlight',
+    ]
       .filter((key) => (options as any)[key] !== false)
       .map((key) => `@storybook/addon-${key}`)
       .filter((addon) => !checkInstalled(addon, main))

addons/highlight/README.md

@@ -0,0 +1,64 @@
+# Storybook Addon Highlight
+
+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)
+
+## 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:
+
+```sh
+npm i -D @storybook/addon-highlight
+```
+
+Add `"@storybook/addon-highlight"` to the addons array in your `.storybook/main.js`:
+
+```js
+module.exports = {
+  addons: ['@storybook/addon-highlight'],
+};
+```
+
+### 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.
+
+```js
+import React, { useEffect } from 'react';
+import { useChannel } from '@storybook/addons';
+import { HIGHLIGHT, RESET_HIGHLIGHT } from '@storybook/addon-highlight';
+import { MyComponent } form './MyComponent';
+
+export default { component: MyComponent };
+
+export const MyStory = () => {
+  const emit = useChannel({});
+
+  useEffect(() => {
+    emit(HIGHLIGHT, {
+      elements: ['.title', '.subtitle'],
+    });
+  }, []);
+
+  return <MyComponent />;
+};
+```
+
+Highlights are automatically cleared when the story changes. You can also manually clear them by emitting the `RESET_HIGHLIGHT` event.
+
+```js
+emit(RESET_HIGHLIGHT);
+```
+
+### Customize style
+
+```js
+emit(HIGHLIGHT, {
+  elements: ['.title', '.subtitle'],
+  color: 'red',
+  style: 'solid', // 'dotted' | 'dashed' | 'solid' | 'double'
+});
+```

addons/highlight/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "@storybook/addon-highlight",
+  "version": "6.5.0-alpha.50",
+  "description": "Highlight DOM nodes within your stories",
+  "keywords": [
+    "storybook-addons",
+    "essentials",
+    "style",
+    "appearance"
+  ],
+  "homepage": "https://github.com/storybookjs/storybook/tree/main/addons/highlight",
+  "bugs": {
+    "url": "https://github.com/storybookjs/storybook/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/storybookjs/storybook.git",
+    "directory": "addons/highlight"
+  },
+  "funding": {
+    "type": "opencollective",
+    "url": "https://opencollective.com/storybook"
+  },
+  "license": "MIT",
+  "author": "winkerVSbecks",
+  "main": "dist/cjs/index.js",
+  "module": "dist/esm/index.js",
+  "types": "dist/ts3.9/index.d.ts",
+  "typesVersions": {
+    "<3.8": {
+      "dist/ts3.9/*": [
+        "dist/ts3.4/*"
+      ]
+    }
+  },
+  "files": [
+    "dist/**/*",
+    "README.md",
+    "*.js",
+    "*.d.ts"
+  ],
+  "scripts": {
+    "prepare": "node ../../scripts/prepare.js"
+  },
+  "dependencies": {
+    "@storybook/addons": "6.5.0-alpha.50",
+    "@storybook/api": "6.5.0-alpha.50",
+    "@storybook/client-logger": "6.5.0-alpha.50",
+    "@storybook/components": "6.5.0-alpha.50",
+    "@storybook/core-events": "6.5.0-alpha.50",
+    "@storybook/csf": "0.0.2--canary.507502b.0",
+    "core-js": "^3.8.2",
+    "global": "^4.4.0"
+  },
+  "devDependencies": {
+    "@types/webpack-env": "^1.16.0"
+  },
+  "peerDependencies": {
+    "react": "^16.8.0 || ^17.0.0",
+    "react-dom": "^16.8.0 || ^17.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "gitHead": "6cf4571e5a1200613de94aa066fe93f75aec6ad1",
+  "sbmodern": "dist/modern/index.js",
+  "storybook": {
+    "displayName": "Highlight",
+    "unsupportedFrameworks": [
+      "react-native"
+    ],
+    "icon": "https://user-images.githubusercontent.com/42671/119589951-dbcd9600-bda1-11eb-9227-078f3cfc1e74.png"
+  }
+}

addons/highlight/preset.js

@@ -0,0 +1,12 @@
+function config(entry = []) {
+  return [...entry, require.resolve('./dist/esm/highlight')];
+}
+
+function managerEntries(entry = []) {
+  return entry;
+}
+
+module.exports = {
+  managerEntries,
+  config,
+};

addons/highlight/register.js

@@ -0,0 +1 @@
+require('./dist/esm/register');

addons/highlight/src/constants.ts

@@ -0,0 +1,5 @@
+export const ADDON_ID = 'storybook/highlight';
+export const HIGHLIGHT_STYLE_ID = 'storybookHighlight';
+
+export const HIGHLIGHT = `${ADDON_ID}/add`;
+export const RESET_HIGHLIGHT = `${ADDON_ID}/reset`;

addons/a11y/src/a11yHighlight.ts → addons/highlight/src/highlight.ts

@@ -1,12 +1,19 @@
+/* eslint-env browser */
 import global from 'global';
 import { addons } from '@storybook/addons';
 import { STORY_CHANGED } from '@storybook/core-events';
-import { EVENTS, HIGHLIGHT_STYLE_ID } from './constants';
-
-import { highlightStyle } from './highlight';
+import { HIGHLIGHT, RESET_HIGHLIGHT, HIGHLIGHT_STYLE_ID } from './constants';
 
 const { document } = global;
 
+type OutlineStyle = 'dotted' | 'dashed' | 'solid' | 'double';
+
+export const highlightStyle = (color = '#FF4785', style: OutlineStyle = 'dashed') => `
+  outline: 2px ${style} ${color};
+  outline-offset: 2px;
+  box-shadow: 0 0 0 6px rgba(255,255,255,0.6);
+`;
+
 if (module && module.hot && module.hot.decline) {
   module.hot.decline();
 }
@@ -15,6 +22,7 @@ interface HighlightInfo {
   /** html selector of the element */
   elements: string[];
   color: string;
+  style: OutlineStyle;
 }
 
 const channel = addons.getChannel();
@@ -32,7 +40,7 @@ const highlight = (infos: HighlightInfo) => {
     .map(
       (target) =>
         `${target}{
-          ${highlightStyle(infos.color)}
+          ${highlightStyle(infos.color, infos.style)}
          }`
     )
     .join(' ');
@@ -48,4 +56,5 @@ const resetHighlight = () => {
 };
 
 channel.on(STORY_CHANGED, resetHighlight);
-channel.on(EVENTS.HIGHLIGHT, highlight);
+channel.on(RESET_HIGHLIGHT, resetHighlight);
+channel.on(HIGHLIGHT, highlight);

addons/highlight/src/index.ts

@@ -0,0 +1,8 @@
+export { HIGHLIGHT, RESET_HIGHLIGHT } from './constants';
+
+if (module && module.hot && module.hot.decline) {
+  module.hot.decline();
+}
+
+// make it work with --isolatedModules
+export default {};

addons/highlight/src/typings.d.ts

@@ -0,0 +1,51 @@
+declare module 'global';
+
+interface Margin {
+  top: number;
+  bottom: number;
+  left: number;
+  right: number;
+}
+
+interface Padding {
+  top: number;
+  bottom: number;
+  left: number;
+  right: number;
+}
+
+interface Border {
+  top: number;
+  bottom: number;
+  left: number;
+  right: number;
+}
+
+interface Dimensions {
+  margin: Margin;
+  padding: Padding;
+  border: Border;
+  width: number;
+  height: number;
+  top: number;
+  left: number;
+  bottom: number;
+  right: number;
+}
+
+interface Extremities {
+  top: number;
+  bottom: number;
+  left: number;
+  right: number;
+}
+
+interface FloatingAlignment {
+  x: 'left' | 'right';
+  y: 'top' | 'bottom';
+}
+
+interface ElementMeasurements extends Dimensions {
+  extremities: Extremities;
+  floatingAlignment: FloatingAlignment;
+}