Merge pull request storybookjs#31432 from storybookjs/fix-various-a11y-issues

Addon A11y: Fix various issues and inconsistencies

Author: ghengeveld

code/addons/a11y/src/components/A11YPanel.stories.tsx

@@ -54,6 +54,7 @@ const meta = preview.meta({
 });
 
 const context = {
+  parameters: {},
   handleManual: fn(),
   highlighted: false,
   toggleHighlight: fn(),
@@ -70,7 +71,8 @@ const context = {
 };
 
 const Template = (
-  args: Pick<A11yContextStore, 'results' | 'error' | 'status' | 'discrepancy' | 'selectedItems'>
+  args: Pick<A11yContextStore, 'results' | 'error' | 'status' | 'discrepancy' | 'selectedItems'> &
+    Pick<Partial<A11yContextStore>, 'parameters'>
 ) => (
   <A11yContext.Provider value={{ ...context, ...args }}>
     <ManagerContext.Provider value={managerContext}>
@@ -95,6 +97,21 @@ export const Initializing = meta.story({
   },
 });
 
+export const Disabled = meta.story({
+  render: () => {
+    return (
+      <Template
+        results={emptyResults}
+        status="initial"
+        error={null}
+        discrepancy={null}
+        selectedItems={new Map()}
+        parameters={{ disable: true }}
+      />
+    );
+  },
+});
+
 export const Manual = meta.story({
   render: () => {
     return (

code/addons/a11y/src/components/A11YPanel.test.tsx

@@ -37,6 +37,7 @@ const emptyResults: EnhancedResults = {
 describe('A11YPanel', () => {
   it('should render initializing state', () => {
     mockedUseA11yContext.mockReturnValue({
+      parameters: {},
       results: emptyResults,
       status: 'initial',
       handleManual: vi.fn(),
@@ -55,6 +56,7 @@ describe('A11YPanel', () => {
   it('should render manual state', () => {
     const handleManual = vi.fn();
     mockedUseA11yContext.mockReturnValue({
+      parameters: {},
       results: emptyResults,
       status: 'manual',
       handleManual,
@@ -76,6 +78,7 @@ describe('A11YPanel', () => {
 
   it('should render running state', () => {
     mockedUseA11yContext.mockReturnValue({
+      parameters: {},
       results: emptyResults,
       status: 'running',
       handleManual: vi.fn(),
@@ -95,6 +98,7 @@ describe('A11YPanel', () => {
 
   it('should render error state', () => {
     mockedUseA11yContext.mockReturnValue({
+      parameters: {},
       results: emptyResults,
       status: 'error',
       handleManual: vi.fn(),
@@ -113,6 +117,7 @@ describe('A11YPanel', () => {
 
   it('should render error state with object error', () => {
     mockedUseA11yContext.mockReturnValue({
+      parameters: {},
       results: emptyResults,
       status: 'error',
       handleManual: vi.fn(),

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

@@ -55,6 +55,7 @@ const Centered = styled.span(({ theme }) => ({
 
 export const A11YPanel: React.FC = () => {
   const {
+    parameters,
     tab,
     results,
     status,
@@ -142,6 +143,21 @@ export const A11YPanel: React.FC = () => {
     ];
   }, [tab, results, handleSelectionChange, selectedItems, toggleOpen]);
 
+  if (parameters.disable || parameters.test === 'off') {
+    return (
+      <Centered>
+        <div>
+          <strong>Accessibility tests are disabled for this story</strong>
+          <p>
+            Update{' '}
+            <code>{parameters.disable ? 'parameters.a11y.disable' : 'parameters.a11y.test'}</code>{' '}
+            to enable accessibility tests.
+          </p>
+        </div>
+      </Centered>
+    );
+  }
+
   return (
     <>
       {discrepancy && <TestDiscrepancyMessage discrepancy={discrepancy} />}

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

@@ -36,6 +36,7 @@ import type { TestDiscrepancy } from './TestDiscrepancyMessage';
 const unhighlightedSelectors = ['html', 'body', 'main'];
 
 export interface A11yContextStore {
+  parameters: A11yParameters;
   results: EnhancedResults | undefined;
   highlighted: boolean;
   toggleHighlight: () => void;
@@ -64,6 +65,7 @@ const colorsByType = {
 };
 
 export const A11yContext = createContext<A11yContextStore>({
+  parameters: {},
   results: undefined,
   highlighted: false,
   toggleHighlight: () => {},
@@ -386,6 +388,7 @@ export const A11yContextProvider: FC<PropsWithChildren> = (props) => {
   return (
     <A11yContext.Provider
       value={{
+        parameters,
         results,
         highlighted,
         toggleHighlight: handleToggleHighlight,

code/addons/a11y/src/components/Report/Details.tsx

@@ -34,8 +34,10 @@ const Info = styled.div({
 const RuleId = styled.div(({ theme }) => ({
   display: 'block',
   color: theme.textMutedColor,
-  marginTop: -10,
-  marginBottom: 10,
+  fontFamily: theme.typography.fonts.mono,
+  fontSize: theme.typography.size.s1,
+  marginTop: -8,
+  marginBottom: 12,
 
   '@container (min-width: 800px)': {
     display: 'none',
@@ -142,7 +144,7 @@ export const Details = ({ id, item, type, selection, handleSelectionChange }: De
       <Description>
         {getFriendlySummaryForAxeResult(item)}{' '}
         <Link href={item.helpUrl} target="_blank" withArrow>
-          How to resolve this
+          Learn how to resolve this violation
         </Link>
       </Description>
     </Info>

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

@@ -1,22 +1,38 @@
-import type { FC } from 'react';
+import type { ComponentProps, FC } from 'react';
 import React from 'react';
 
-import { EmptyTabContent, IconButton } from 'storybook/internal/components';
+import { Badge, EmptyTabContent, IconButton } from 'storybook/internal/components';
 
 import { ChevronSmallDownIcon } from '@storybook/icons';
 
+import type { ImpactValue } from 'axe-core';
 import { styled } from 'storybook/theming';
 
 import { getTitleForAxeResult } from '../../axeRuleMappingHelper';
-import type { EnhancedResult, RuleType } from '../../types';
+import { type EnhancedResult, RuleType } from '../../types';
 import { Details } from './Details';
 
+const impactStatus: Record<NonNullable<ImpactValue>, ComponentProps<typeof Badge>['status']> = {
+  minor: 'neutral',
+  moderate: 'warning',
+  serious: 'negative',
+  critical: 'critical',
+};
+
+const impactLabels: Record<NonNullable<ImpactValue>, string> = {
+  minor: 'Minor',
+  moderate: 'Moderate',
+  serious: 'Serious',
+  critical: 'Critical',
+};
+
 const Wrapper = styled.div(({ theme }) => ({
   display: 'flex',
   flexDirection: 'column',
   width: '100%',
   borderBottom: `1px solid ${theme.appBorderColor}`,
   containerType: 'inline-size',
+  fontSize: theme.typography.size.s2,
 }));
 
 const Icon = styled(ChevronSmallDownIcon)({
@@ -40,11 +56,24 @@ const HeaderBar = styled.div(({ theme }) => ({
   },
 }));
 
-const Title = styled.div({
+const Title = styled.div(({ theme }) => ({
   display: 'flex',
+  alignItems: 'baseline',
   flexGrow: 1,
-  gap: 6,
-});
+  fontSize: theme.typography.size.s2,
+  gap: 8,
+}));
+
+const RuleId = styled.div(({ theme }) => ({
+  display: 'none',
+  color: theme.textMutedColor,
+  fontFamily: theme.typography.fonts.mono,
+  fontSize: theme.typography.size.s1,
+
+  '@container (min-width: 800px)': {
+    display: 'block',
+  },
+}));
 
 const Count = styled.div(({ theme }) => ({
   display: 'flex',
@@ -84,7 +113,13 @@ export const Report: FC<ReportProps> = ({
             <HeaderBar onClick={(event) => toggleOpen(event, type, item)} data-active={!!selection}>
               <Title>
                 <strong>{title}</strong>
+                <RuleId>{item.id}</RuleId>
               </Title>
+              {item.impact && (
+                <Badge status={type === RuleType.PASS ? 'neutral' : impactStatus[item.impact]}>
+                  {impactLabels[item.impact]}
+                </Badge>
+              )}
               <Count>{item.nodes.length}</Count>
               <IconButton
                 onClick={(event) => toggleOpen(event, type, item)}

code/addons/a11y/src/types.ts

@@ -1,4 +1,6 @@
-import type { AxeResults, ElementContext, NodeResult, Result, RunOptions, Spec } from 'axe-core';
+import type { AxeResults, NodeResult, Result } from 'axe-core';
+
+import type { A11yParameters as A11yParams } from './params';
 
 export type A11YReport = EnhancedResults | { error: Error };
 
@@ -8,27 +10,7 @@ export interface A11yParameters {
    *
    * @see https://storybook.js.org/docs/writing-tests/accessibility-testing
    */
-  a11y?: {
-    /** Manual configuration for specific elements */
-    element?: ElementContext;
-
-    /**
-     * Configuration for the accessibility rules
-     *
-     * @see https://github.com/dequelabs/axe-core/blob/develop/doc/API.md#api-name-axeconfigure
-     */
-    config?: Spec;
-
-    /**
-     * Options for the accessibility checks To learn more about the available options,
-     *
-     * @see https://github.com/dequelabs/axe-core/blob/develop/doc/API.md#options-parameter
-     */
-    options?: RunOptions;
-
-    /** Remove the addon panel and disable the addon's behavior */
-    disable?: boolean;
-  };
+  a11y?: A11yParams;
 }
 
 export interface A11yGlobals {