Merge pull request #411 from chromaui/highlight-ignored-elements

Add tool to highlight ignored elements

Author: ghengeveld

.storybook/preview.tsx

@@ -1,18 +1,18 @@
-import { ManagerContext } from 'storybook/manager-api';
 import type { Decorator, Loader, Preview } from '@storybook/react-vite';
+import { graphql, HttpResponse } from 'msw';
+import { initialize, mswLoader } from 'msw-storybook-addon';
+import React from 'react';
+import { ManagerContext } from 'storybook/manager-api';
 import { fn } from 'storybook/test';
 import {
-  Global,
-  ThemeProvider,
   convert,
   createReset,
+  Global,
   styled,
+  ThemeProvider,
   themes,
   useTheme,
 } from 'storybook/theming';
-import { HttpResponse, graphql } from 'msw';
-import { initialize, mswLoader } from 'msw-storybook-addon';
-import React from 'react';
 
 import { AuthProvider } from '../src/AuthContext';
 import { baseModes } from '../src/modes';
@@ -234,6 +234,7 @@ const preview: Preview = {
     },
     chromatic: {
       modes: baseModes,
+      ignoreSelectors: ['video'],
     },
     controls: {
       matchers: {

package.json

@@ -22,9 +22,13 @@
       "require": "./dist/index.js",
       "import": "./dist/index.mjs"
     },
-    "./manager": "./dist/manager.js",
+    "./manager": "./dist/manager.mjs",
+    "./package.json": "./package.json",
     "./preset": "./dist/preset.js",
-    "./package.json": "./package.json"
+    "./preview": {
+      "types": "./dist/preview.d.ts",
+      "default": "./dist/preview.mjs"
+    }
   },
   "main": "dist/index.js",
   "files": [
@@ -153,6 +157,9 @@
     ],
     "nodeEntries": [
       "./src/preset.ts"
+    ],
+    "previewEntries": [
+      "./src/preview.ts"
     ]
   },
   "msw": {

src/components/GlobalIgnoreToggle.stories.tsx

@@ -0,0 +1,62 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import React from 'react';
+import { fn } from 'storybook/test';
+
+import { GlobalIgnoreToggleButton } from './GlobalIgnoreToggle';
+
+type StoryArgs = React.ComponentProps<typeof GlobalIgnoreToggleButton>;
+
+const StatefulButton = (args: StoryArgs) => {
+  const [enabled, setEnabled] = React.useState(args.enabled);
+
+  React.useEffect(() => {
+    setEnabled(args.enabled);
+  }, [args.enabled]);
+
+  return (
+    <GlobalIgnoreToggleButton
+      {...args}
+      enabled={enabled}
+      onToggle={() => {
+        args.onToggle();
+        setEnabled((current) => !current);
+      }}
+    />
+  );
+};
+
+const meta = {
+  title: 'components/GlobalIgnoreToggle',
+  component: GlobalIgnoreToggleButton,
+  render: (args) => <StatefulButton {...args} />,
+  args: {
+    enabled: false,
+    ignoreCount: 3,
+    locked: false,
+    onToggle: fn(),
+  },
+} satisfies Meta<typeof GlobalIgnoreToggleButton>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Hidden: Story = {
+  args: {
+    ignoreCount: 0,
+  },
+};
+
+export const Inactive: Story = {};
+
+export const Active: Story = {
+  args: {
+    enabled: true,
+  },
+};
+
+export const LockedByStoryGlobals: Story = {
+  args: {
+    enabled: true,
+    locked: true,
+  },
+};

src/components/GlobalIgnoreToggle.tsx

@@ -0,0 +1,59 @@
+import { ContrastIgnoredIcon } from '@storybook/icons';
+import React, { useState } from 'react';
+import { IconButton } from 'storybook/internal/components';
+import { useChannel, useGlobals } from 'storybook/manager-api';
+
+import { HIGHLIGHT_IGNORED_COUNT, HIGHLIGHT_IGNORED_PARAM } from '../constants';
+
+type GlobalIgnoreToggleButtonProps = {
+  enabled: boolean;
+  ignoreCount: number;
+  locked: boolean;
+  onToggle: () => void;
+};
+
+export const GlobalIgnoreToggleButton = ({
+  enabled,
+  ignoreCount,
+  locked,
+  onToggle,
+}: GlobalIgnoreToggleButtonProps) => {
+  return ignoreCount === 0 ? null : (
+    <IconButton
+      key={HIGHLIGHT_IGNORED_PARAM}
+      active={enabled}
+      ariaLabel={
+        locked
+          ? `Highlights ${enabled ? 'enabled' : 'disabled'} by story globals`
+          : `${enabled ? 'Hide' : 'Show'} ignored areas`
+      }
+      padding="small"
+      variant="ghost"
+      disabled={locked}
+      onClick={onToggle}
+    >
+      <ContrastIgnoredIcon />
+      {ignoreCount}
+    </IconButton>
+  );
+};
+
+export const GlobalIgnoreToggle = () => {
+  const [globals, updateGlobals, storyGlobals] = useGlobals();
+  const [ignoreCount, setIgnoreCount] = useState(0);
+  const enabled = !!globals[HIGHLIGHT_IGNORED_PARAM];
+  const locked = HIGHLIGHT_IGNORED_PARAM in storyGlobals;
+
+  useChannel({ [HIGHLIGHT_IGNORED_COUNT]: setIgnoreCount }, []);
+
+  return (
+    <GlobalIgnoreToggleButton
+      enabled={enabled}
+      ignoreCount={ignoreCount}
+      locked={locked}
+      onToggle={() =>
+        updateGlobals({ [HIGHLIGHT_IGNORED_PARAM]: !globals[HIGHLIGHT_IGNORED_PARAM] })
+      }
+    />
+  );
+};

src/constants.ts

@@ -27,6 +27,14 @@ export const TELEMETRY = `${ADDON_ID}/telemetry`;
 export const ENABLE_FILTER = `${ADDON_ID}/enableFilter`;
 export const REMOVE_ADDON = `${ADDON_ID}/removeAddon`;
 export const PARAM_KEY = 'chromatic';
+export const HIGHLIGHT_IGNORED_PARAM = 'highlightIgnored';
+export const HIGHLIGHT_IGNORED_ID = `${ADDON_ID}/highlightIgnored`;
+export const HIGHLIGHT_IGNORED_COUNT = `${ADDON_ID}/highlightIgnored/count`;
+export const HIGHLIGHT_IGNORED_SELECT = `${ADDON_ID}/highlightIgnored/select`;
+export const HIGHLIGHT_IGNORED_DEFAULT_SELECTORS = [
+  '[data-chromatic="ignore"]',
+  '[class~="chromatic-ignore"]',
+];
 
 export const FETCH_ABORTED = `${ADDON_ID}/ChannelFetch/aborted`;
 export const FETCH_REQUEST = `${ADDON_ID}ChannelFetch/request`;

src/dev.ts

@@ -5,4 +5,5 @@ import config from './preset.ts';
 export default {
   ...config,
   managerEntries: [fileURLToPath(import.meta.resolve('./manager.tsx'))],
+  previewAnnotations: [fileURLToPath(import.meta.resolve('./preview.ts'))],
 };

src/index.ts

@@ -1,5 +1,6 @@
 import { definePreviewAddon } from 'storybook/internal/csf';
 
+import * as addonAnnotations from './preview.ts';
 import type { ChromaticTypes } from './types';
 
-export default () => definePreviewAddon<ChromaticTypes>({});
+export default () => definePreviewAddon<ChromaticTypes>(addonAnnotations);

src/manager.tsx

@@ -1,12 +1,38 @@
 import React from 'react';
+import { type ClickEventDetails } from 'storybook/highlight';
 import { type Addon_TestProviderType, Addon_TypesEnum } from 'storybook/internal/types';
 import { addons, experimental_getStatusStore } from 'storybook/manager-api';
 
-import { ADDON_ID, PANEL_ID, PARAM_KEY, TEST_PROVIDER_ID } from './constants.ts';
+import { GlobalIgnoreToggle } from './components/GlobalIgnoreToggle.tsx';
+import {
+  ADDON_ID,
+  HIGHLIGHT_IGNORED_DEFAULT_SELECTORS,
+  HIGHLIGHT_IGNORED_SELECT,
+  PANEL_ID,
+  PARAM_KEY,
+  TEST_PROVIDER_ID,
+} from './constants.ts';
 import { Panel } from './Panel';
 import { TestProviderRender } from './TestProviderRender';
 
 addons.register(ADDON_ID, (api) => {
+  api.on(HIGHLIGHT_IGNORED_SELECT, (itemId: string, details: ClickEventDetails) => {
+    const isDefaultSelector = HIGHLIGHT_IGNORED_DEFAULT_SELECTORS.includes(details.selectors[0]);
+    window.open(
+      isDefaultSelector
+        ? 'https://www.chromatic.com/docs/ignoring-elements/#ignoring-elements-inline'
+        : 'https://www.chromatic.com/docs/ignoring-elements/#ignoring-elements-via-test-configuration',
+      '_blank'
+    );
+  });
+
+  addons.add(`${ADDON_ID}/ignore-highlight-tool`, {
+    type: Addon_TypesEnum.TOOL,
+    title: 'Highlight ignored areas',
+    match: ({ viewMode }) => viewMode === 'story',
+    render: () => <GlobalIgnoreToggle />,
+  });
+
   addons.add(PANEL_ID, {
     type: Addon_TypesEnum.PANEL,
     title: 'Visual tests',

src/preset.ts

@@ -53,6 +53,9 @@ const chromaticLogger = createLogger(undefined, CONFIG_OVERRIDES);
 function managerEntries(entry: string[] = []) {
   return [...entry, require.resolve('./manager.mjs')];
 }
+function previewAnnotations(entry: string[] = []) {
+  return [...entry, require.resolve('./preview.mjs')];
+}
 
 // Load the addon version from the package.json file, once.
 let getAddonVersion = async (): Promise<string | null> => {
@@ -281,6 +284,7 @@ async function serverChannel(channel: Channel, options: Options & { configFile?:
 
 const config = {
   managerEntries,
+  previewAnnotations,
   experimental_serverChannel: serverChannel,
   staticDirs: async (inputDirs: string[]) => [
     ...inputDirs,

src/preview.ts

@@ -0,0 +1,54 @@
+import { HIGHLIGHT, REMOVE_HIGHLIGHT } from 'storybook/highlight';
+import { useChannel, useEffect } from 'storybook/preview-api';
+
+import {
+  HIGHLIGHT_IGNORED_COUNT,
+  HIGHLIGHT_IGNORED_ID,
+  HIGHLIGHT_IGNORED_PARAM,
+} from './constants';
+import { getIgnoreHighlightOptions } from './utils/ignoreHighlight';
+
+const WithIgnoreHighlight = (Story: any, { globals, parameters, id }: any) => {
+  const enabled = !!globals[HIGHLIGHT_IGNORED_PARAM];
+  const emit = useChannel({});
+  const highlightOptions = getIgnoreHighlightOptions(parameters.chromatic);
+  const selectorKey = highlightOptions?.selectors.join('\n') ?? '';
+
+  useEffect(() => {
+    emit(REMOVE_HIGHLIGHT, HIGHLIGHT_IGNORED_ID);
+    if (!highlightOptions?.selectors.length) {
+      emit(HIGHLIGHT_IGNORED_COUNT, 0);
+      return;
+    }
+    if (enabled) {
+      emit(HIGHLIGHT, highlightOptions);
+    }
+
+    const root = document.getElementById('storybook-root');
+    const elements = highlightOptions.selectors.reduce((acc, selector) => {
+      // Elements matching the selector, excluding storybook elements and their descendants.
+      // Necessary to find portaled elements (e.g. children of `body`).
+      document
+        .querySelectorAll(
+          `:is(${selector}):not([id^="storybook-"], [id^="storybook-"] *, [class^="sb-"], [class^="sb-"] *)`
+        )
+        .forEach((element) => acc.add(element));
+
+      // Elements matching the selector inside the storybook root, as these were excluded above.
+      (root?.querySelectorAll(selector) ?? []).forEach((element) => acc.add(element));
+
+      return acc;
+    }, new Set());
+    emit(HIGHLIGHT_IGNORED_COUNT, elements.size);
+
+    return () => emit(REMOVE_HIGHLIGHT, HIGHLIGHT_IGNORED_ID);
+  }, [emit, highlightOptions, id, selectorKey, enabled]);
+
+  return Story();
+};
+
+export const decorators = [WithIgnoreHighlight];
+
+export const initialGlobals = {
+  [HIGHLIGHT_IGNORED_PARAM]: false,
+};