Core: Draw highlights on top of canvas and add various new features

code/.storybook/main.ts

@@ -31,6 +31,10 @@ const config = defineMain({
       directory: '../core/src/components/components',
       titlePrefix: 'components',
     },
+    {
+      directory: '../core/src/highlight',
+      titlePrefix: 'highlight',
+    },
     {
       directory: '../lib/blocks/src',
       titlePrefix: 'blocks',

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

@@ -224,6 +224,20 @@ export const A11yContextProvider: FC<PropsWithChildren> = (props) => {
     [setResults, status, storyId]
   );
 
+  const handleSelect = useCallback(
+    (item: { id: string }, target: { selectors: string[] }) => {
+      const [type, id] = item.id.split('.');
+      const index =
+        results[type as RuleType]
+          .find((r) => r.id === id)
+          ?.nodes.findIndex((n) => target.selectors.some((s) => s === String(n.target))) ?? -1;
+      if (index !== -1) {
+        setSelectedItems(new Map([[`${type}.${id}`, `${type}.${id}.${index + 1}`]]));
+      }
+    },
+    [results]
+  );
+
   const handleReport = useCallback(
     ({ reporters }: StoryFinishedPayload) => {
       const a11yReport = reporters.find((r) => r.type === 'a11y') as Report<A11YReport> | undefined;
@@ -257,10 +271,11 @@ export const A11yContextProvider: FC<PropsWithChildren> = (props) => {
     {
       [EVENTS.RESULT]: handleResult,
       [EVENTS.ERROR]: handleError,
+      [EVENTS.SELECT]: handleSelect,
       [STORY_RENDER_PHASE_CHANGED]: handleReset,
       [STORY_FINISHED]: handleReport,
     },
-    [handleReset, handleReport, handleReset, handleError, handleResult]
+    [handleReset, handleReport, handleSelect, handleError, handleResult]
   );
 
   const handleManual = useCallback(() => {
@@ -293,24 +308,58 @@ export const A11yContextProvider: FC<PropsWithChildren> = (props) => {
       const [type, id, number] = key.split('.');
       const result = results[type as RuleType].find((r) => r.id === id);
       const target = result?.nodes[Number(number) - 1]?.target;
-      return target ? [target] : [];
+      return target ? [String(target)] : [];
     });
     emit(HIGHLIGHT, {
-      elements: selected,
-      color: colorsByType[tab],
-      width: '2px',
-      offset: '0px',
+      priority: 1,
+      selectors: selected,
+      styles: {
+        outline: `2px solid color-mix(in srgb, ${colorsByType[tab]}, transparent 30%)`,
+        outlineOffset: '2px',
+        backgroundColor: 'transparent',
+      },
+      selectedStyles: {
+        outline: `2px solid ${colorsByType[tab]}`,
+        outlineOffset: '2px',
+        backgroundColor: 'transparent',
+      },
+      menuListItems: results[tab as RuleType].map((result) => ({
+        id: `${tab}.${result.id}`,
+        title: result.help,
+        description: result.description,
+        clickEvent: EVENTS.SELECT,
+        selectors: result.nodes
+          .flatMap((n) => n.target)
+          .map(String)
+          .filter((e) => selected.includes(e)),
+      })),
     });
 
     const others = results[tab as RuleType]
-      .flatMap((r) => r.nodes.map((n) => n.target))
+      .flatMap((r) => r.nodes.flatMap((n) => n.target).map(String))
       .filter((e) => !selected.includes(e));
     emit(HIGHLIGHT, {
-      elements: others,
-      color: `${colorsByType[tab]}99`,
-      style: 'dashed',
-      width: '1px',
-      offset: '1px',
+      selectors: others,
+      styles: {
+        outline: `1px dashed color-mix(in srgb, ${colorsByType[tab]}, transparent 30%)`,
+        outlineOffset: '1px',
+        backgroundColor: `color-mix(in srgb, ${colorsByType[tab]}, transparent 60%)`,
+      },
+      selectedStyles: {
+        outline: `1px solid ${colorsByType[tab]}`,
+        outlineOffset: '1px',
+        backgroundColor: 'transparent',
+      },
+      menuListItems: results[tab as RuleType].map((result) => ({
+        id: `${tab}.${result.id}`,
+        title: result.help,
+        description: result.description,
+        clickEvent: EVENTS.SELECT,
+        selectors: result.nodes
+          .flatMap((n) => n.target)
+          .map(String)
+          .filter((e) => !selected.includes(e)),
+      })),
     });
   }, [emit, highlighted, results, tab, selectedItems]);
 

code/addons/a11y/src/constants.ts

@@ -6,13 +6,14 @@ const REQUEST = `${ADDON_ID}/request`;
 const RUNNING = `${ADDON_ID}/running`;
 const ERROR = `${ADDON_ID}/error`;
 const MANUAL = `${ADDON_ID}/manual`;
+const SELECT = `${ADDON_ID}/select`;
 
 export const DOCUMENTATION_LINK = 'writing-tests/accessibility-testing';
 export const DOCUMENTATION_DISCREPANCY_LINK = `${DOCUMENTATION_LINK}#why-are-my-tests-failing-in-different-environments`;
 
 export const TEST_PROVIDER_ID = 'storybook/addon-a11y/test-provider';
 
-export const EVENTS = { RESULT, REQUEST, RUNNING, ERROR, MANUAL };
+export const EVENTS = { RESULT, REQUEST, RUNNING, ERROR, MANUAL, SELECT };
 
 export const STATUS_TYPE_ID_COMPONENT_TEST = 'storybook/component-test';
 export const STATUS_TYPE_ID_A11Y = 'storybook/a11y';

code/core/src/highlight/constants.ts

@@ -1,5 +1,6 @@
 export const ADDON_ID = 'storybook/highlight';
 
 export const HIGHLIGHT = `${ADDON_ID}/add`;
+export const REMOVE_HIGHLIGHT = `${ADDON_ID}/remove`;
 export const RESET_HIGHLIGHT = `${ADDON_ID}/reset`;
 export const SCROLL_INTO_VIEW = `${ADDON_ID}/scroll-into-view`;

code/core/src/highlight/preview.ts

@@ -1,119 +1,13 @@
 /* eslint-env browser */
-import { STORY_CHANGED } from 'storybook/internal/core-events';
-
-import { global } from '@storybook/global';
-
 import { addons, definePreview } from 'storybook/preview-api';
 
-import { HIGHLIGHT, RESET_HIGHLIGHT, SCROLL_INTO_VIEW } from './constants';
-
-const { document } = global;
-
-interface HighlightOptions {
-  /** HTML selectors of the elements */
-  elements: string[];
-  /** Color of the outline */
-  color?: string;
-  /** Style of the outline */
-  style?: 'dotted' | 'dashed' | 'solid' | 'double';
-  /** Width of the outline */
-  width?: string;
-  /** Offset of the outline */
-  offset?: string;
-  /**
-   * Duration in milliseconds of the fade out animation. Note you must use a 6-character hex color
-   * to use this option.
-   */
-  fadeOut?: number;
-  /**
-   * Duration in milliseconds of the pulse out animation. Note you must use a 6-character hex color
-   * to use this option.
-   */
-  pulseOut?: number;
-}
-
-const highlightStyle = (
-  selectors: string[],
-  {
-    color = '#FF4785',
-    style = 'solid',
-    width = '1px',
-    offset = '2px',
-    fadeOut = 0,
-    pulseOut = 0,
-  }: HighlightOptions
-) => {
-  const animationName = Math.random().toString(36).substring(2, 15);
-  let keyframes = '';
-  if (pulseOut) {
-    keyframes = `@keyframes ${animationName} {
-      0% { outline: ${width} ${style} ${color}; }
-      20% { outline: ${width} ${style} ${color}00; }
-      40% { outline: ${width} ${style} ${color}; }
-      60% { outline: ${width} ${style} ${color}00; }
-      80% { outline: ${width} ${style} ${color}; }
-      100% { outline: ${width} ${style} ${color}00; }
-    }\n`;
-  } else if (fadeOut) {
-    keyframes = `@keyframes ${animationName} {
-      0% { outline: ${width} ${style} ${color}; }
-      100% { outline: ${width} ${style} ${color}00; }
-    }\n`;
-  }
-
-  return `${keyframes}${selectors.join(', ')} {
-    outline: ${width} ${style} ${color};
-    outline-offset: ${offset};
-    ${pulseOut || fadeOut ? `animation: ${animationName} ${pulseOut || fadeOut}ms linear forwards;` : ''}
-  }`;
-};
+import { useHighlights } from './useHighlights';
 
 if (addons && addons.ready) {
   addons.ready().then(() => {
     const channel = addons.getChannel();
-    const sheetIds = new Set<string>();
-
-    const highlight = (options: HighlightOptions) => {
-      const sheetId = Math.random().toString(36).substring(2, 15);
-      sheetIds.add(sheetId);
-
-      const sheet = document.createElement('style');
-      sheet.innerHTML = highlightStyle(Array.from(new Set(options.elements)), options);
-      sheet.setAttribute('id', sheetId);
-      document.head.appendChild(sheet);
-
-      const timeout = options.pulseOut || options.fadeOut;
-      if (timeout) {
-        setTimeout(() => removeHighlight(sheetId), timeout + 500);
-      }
-    };
-
-    const removeHighlight = (id: string) => {
-      const sheetElement = document.getElementById(id);
-      sheetElement?.parentNode?.removeChild(sheetElement);
-      sheetIds.delete(id);
-    };
-
-    const resetHighlight = () => {
-      sheetIds.forEach(removeHighlight);
-    };
-
-    const scrollIntoView = (target: string, options?: ScrollIntoViewOptions) => {
-      const element = document.querySelector(target);
-      element?.scrollIntoView({ behavior: 'smooth', block: 'center', ...options });
-      highlight({
-        elements: [target],
-        color: '#1EA7FD',
-        width: '2px',
-        offset: '2px',
-        pulseOut: 3000,
-      });
-    };
-
-    channel.on(STORY_CHANGED, resetHighlight);
-    channel.on(SCROLL_INTO_VIEW, scrollIntoView);
-    channel.on(RESET_HIGHLIGHT, resetHighlight);
-    channel.on(HIGHLIGHT, highlight);
+    useHighlights({ channel });
   });
 }
+
 export default () => definePreview({});

code/core/src/highlight/types.ts

@@ -9,3 +9,65 @@ export interface HighlightParameters {
     disable?: boolean;
   };
 }
+
+export interface HighlightInfo {
+  /** Unique identifier for the highlight, required if you want to remove the highlight later */
+  id?: string;
+  /** HTML selectors of the elements */
+  selectors: string[];
+  /** CSS styles to apply to the highlight */
+  styles: Record<string, string>;
+  /** Priority of the highlight, higher takes precedence, defaults to 0 */
+  priority?: number;
+  /** Whether the highlight is selectable / hoverable */
+  selectable?: boolean;
+  /** CSS styles to apply to the highlight when it is selected or hovered */
+  selectedStyles?: Record<string, string>;
+  /** Keyframes required for animations */
+  keyframes?: string;
+  /** Menu items to show when the highlight is selected, or true to show the element's HTML */
+  menuListItems?: {
+    id: string;
+    title: string;
+    description?: string;
+    right?: string;
+    href?: string;
+    clickEvent?: string;
+    selectors?: string[];
+  }[];
+}
+
+// Legacy format
+export interface LegacyHighlightInfo {
+  /** @deprecated Use selectors instead */
+  elements: string[];
+  /** @deprecated Use styles instead */
+  color: string;
+  /** @deprecated Use styles instead */
+  style: 'dotted' | 'dashed' | 'solid' | 'double';
+}
+
+export type RawHighlightInfo = HighlightInfo | LegacyHighlightInfo;
+
+export type Highlight = {
+  id: string;
+  priority: number;
+  selectors: string[];
+  styles: Record<string, string>;
+  selectable: boolean;
+  selectedStyles?: Record<string, string>;
+  menuListItems?: HighlightInfo['menuListItems'];
+};
+
+export type Box = {
+  element: HTMLElement;
+  selectors: Highlight['selectors'];
+  styles: Highlight['styles'];
+  selectable?: Highlight['selectable'];
+  selectedStyles?: Highlight['selectedStyles'];
+  menuListItems?: Highlight['menuListItems'];
+  top: number;
+  left: number;
+  width: number;
+  height: number;
+};