feat: improve Image preview accessibility (#496)

* feat: improve Image preview accessibility

* fix: test

* fix: test

* fix: update

* fix: test

* fix: codecov

* fix: update

* fix: update

* fix: test

* chore: checkpoint local changes

* test: fix preview focus assertion in jsdom

* chore: remove unused preview focus ref

---------

Co-authored-by: 二货机器人 <smith3816@gmail.com>

Author: claytonlin1110

assets/preview.less

@@ -58,9 +58,12 @@
     height: 40px;
     color: #fff;
     background: rgba(0, 0, 0, 0.3);
+    border: 0;
+    padding: 0;
     border-radius: 9999px;
     transform: translateY(-50%);
     cursor: pointer;
+    font: inherit;
 
     &-disabled {
       cursor: default;
@@ -104,6 +107,10 @@
     &-action {
       color: #fff;
       cursor: pointer;
+      border: 0;
+      padding: 0;
+      background: transparent;
+      font: inherit;
 
       &-disabled {
         cursor: default;

package.json

@@ -42,7 +42,7 @@
   "dependencies": {
     "@rc-component/motion": "^1.0.0",
     "@rc-component/portal": "^2.1.2",
-    "@rc-component/util": "^1.3.0",
+    "@rc-component/util": "^1.10.0",
     "clsx": "^2.1.1"
   },
   "devDependencies": {

src/Image.tsx

@@ -44,7 +44,7 @@ export interface PreviewConfig extends Omit<InternalPreviewConfig, 'countRender'
 export type SemanticName = 'root' | 'image' | 'cover';
 
 export interface ImageProps
-  extends Omit<React.ImgHTMLAttributes<HTMLImageElement>, 'placeholder' | 'onClick'> {
+  extends Omit<React.ImgHTMLAttributes<HTMLImageElement>, 'placeholder' | 'onClick' | 'onKeyDown'> {
   // Misc
   prefixCls?: string;
   previewPrefixCls?: string;
@@ -73,6 +73,7 @@ export interface ImageProps
   // Events
   onClick?: (e: React.MouseEvent<HTMLDivElement>) => void;
   onError?: (e: React.SyntheticEvent<HTMLImageElement, Event>) => void;
+  onKeyDown?: (e: React.KeyboardEvent<HTMLDivElement>) => void;
 }
 
 interface CompoundedComponent<P> extends React.FC<P> {
@@ -108,6 +109,7 @@ const ImageInternal: CompoundedComponent<ImageProps> = props => {
     // Events
     onClick,
     onError,
+    onKeyDown,
     ...otherProps
   } = props;
 
@@ -203,6 +205,33 @@ const ImageInternal: CompoundedComponent<ImageProps> = props => {
     onClick?.(e);
   };
 
+  // ======================= Keyboard Preview =====================
+  const onPreviewKeyDown: React.KeyboardEventHandler<HTMLDivElement> = event => {
+    onKeyDown?.(event);
+
+    if (!canPreview) {
+      return;
+    }
+
+    if (event.key === 'Enter' || event.key === ' ') {
+      event.preventDefault();
+
+      const rect = (event.target as HTMLDivElement).getBoundingClientRect();
+      const left = rect.x + rect.width / 2;
+      const top = rect.y + rect.height / 2;
+
+      if (groupContext) {
+        groupContext.onPreview(imageId, src, left, top);
+      } else {
+        setMousePosition({
+          x: left,
+          y: top,
+        });
+        triggerPreviewOpen(true);
+      }
+    }
+  };
+
   // =========================== Render ===========================
   return (
     <>
@@ -212,6 +241,10 @@ const ImageInternal: CompoundedComponent<ImageProps> = props => {
           [`${prefixCls}-error`]: status === 'error',
         })}
         onClick={canPreview ? onPreview : onClick}
+        role={canPreview ? 'button' : otherProps.role}
+        tabIndex={canPreview && otherProps.tabIndex == null ? 0 : otherProps.tabIndex}
+        aria-label={canPreview ? otherProps['aria-label'] ?? alt : otherProps['aria-label']}
+        onKeyDown={onPreviewKeyDown}
         style={{
           width,
           height,

src/Preview/Footer.tsx

@@ -20,7 +20,7 @@ interface RenderOperationParams {
   icon: React.ReactNode;
   type: OperationType;
   disabled?: boolean;
-  onClick: (e: React.MouseEvent<HTMLDivElement, MouseEvent>) => void;
+  onClick: React.MouseEventHandler<HTMLButtonElement>;
 }
 
 export interface FooterProps extends Actions {
@@ -95,15 +95,18 @@ export default function Footer(props: FooterProps) {
 
   const renderOperation = ({ type, disabled, onClick, icon }: RenderOperationParams) => {
     return (
-      <div
+      <button
+        type="button"
         key={type}
         className={clsx(actionCls, `${actionCls}-${type}`, {
           [`${actionCls}-disabled`]: !!disabled,
         })}
         onClick={onClick}
+        disabled={!!disabled}
+        aria-label={type}
       >
         {icon}
-      </div>
+      </button>
     );
   };
 

src/Preview/PrevNext.tsx

@@ -21,24 +21,30 @@ export default function PrevNext(props: PrevNextProps) {
 
   const switchCls = `${prefixCls}-switch`;
 
+  const prevDisabled = current === 0;
+  const nextDisabled = current === count - 1;
+
   return (
     <>
-      <div
+      <button
         className={clsx(switchCls, `${switchCls}-prev`, {
-          [`${switchCls}-disabled`]: current === 0,
+          [`${switchCls}-disabled`]: prevDisabled,
         })}
         onClick={() => onActive(-1)}
+        disabled={prevDisabled}
       >
         {prev ?? left}
-      </div>
-      <div
+      </button>
+      <button
+        type="button"
         className={clsx(switchCls, `${switchCls}-next`, {
-          [`${switchCls}-disabled`]: current === count - 1,
+          [`${switchCls}-disabled`]: nextDisabled,
         })}
         onClick={() => onActive(1)}
+        disabled={nextDisabled}
       >
         {next ?? right}
-      </div>
+      </button>
     </>
   );
 }

src/Preview/index.tsx

@@ -1,6 +1,7 @@
 import CSSMotion from '@rc-component/motion';
 import Portal, { type PortalProps } from '@rc-component/portal';
 import { useEvent } from '@rc-component/util';
+import { useLockFocus } from '@rc-component/util/lib/Dom/focus';
 import useLayoutEffect from '@rc-component/util/lib/hooks/useLayoutEffect';
 import KeyCode from '@rc-component/util/lib/KeyCode';
 import { clsx } from 'clsx';
@@ -195,6 +196,7 @@ const Preview: React.FC<PreviewProps> = props => {
   } = props;
 
   const imgRef = useRef<HTMLImageElement>();
+  const wrapperRef = useRef<HTMLDivElement>(null);
   const groupContext = useContext(PreviewGroupContext);
   const showLeftOrRightSwitches = groupContext && count > 1;
   const showOperationsProgress = groupContext && count >= 1;
@@ -382,6 +384,9 @@ const Preview: React.FC<PreviewProps> = props => {
     }
   };
 
+  // =========================== Focus ============================
+  useLockFocus(open && portalRender, () => wrapperRef.current);
+
   // ========================== Render ==========================
   const bodyStyle: React.CSSProperties = {
     ...styles.body,
@@ -418,11 +423,16 @@ const Preview: React.FC<PreviewProps> = props => {
 
           return (
             <div
+              ref={wrapperRef}
               className={clsx(prefixCls, rootClassName, classNames.root, motionClassName, {
                 [`${prefixCls}-movable`]: movable,
                 [`${prefixCls}-moving`]: isMoving,
               })}
               style={mergedStyle}
+              role="dialog"
+              aria-modal="true"
+              aria-label={alt}
+              tabIndex={-1}
             >
               {/* Mask */}
               <div

tests/__snapshots__/basic.test.tsx.snap

@@ -3,7 +3,9 @@
 exports[`Basic snapshot 1`] = `
 <div
   class="rc-image"
+  role="button"
   style="width: 200px;"
+  tabindex="0"
 >
   <img
     class="rc-image-img"

tests/preview.test.tsx

@@ -1164,4 +1164,96 @@ describe('Preview', () => {
     expect(baseElement.querySelector('.rc-image-preview')).toHaveClass(customClassnames.popup.root);
     expect(baseElement.querySelector('.rc-image-preview')).toHaveStyle(customStyles.popup.root);
   });
+
+  it('Image wrapper should be keyboard focusable when preview enabled', () => {
+    const { container } = render(<Image src="src" alt="keyboard test" />);
+
+    const wrapper = container.querySelector('.rc-image') as HTMLElement;
+    expect(wrapper).toHaveAttribute('role', 'button');
+    expect(wrapper).toHaveAttribute('tabindex', '0');
+  });
+
+  it('Pressing Enter on image wrapper should open preview', () => {
+    const { container } = render(<Image src="src" alt="keyboard open" />);
+
+    const wrapper = container.querySelector('.rc-image') as HTMLElement;
+    wrapper.focus();
+    fireEvent.keyDown(wrapper, { key: 'Enter' });
+
+    act(() => {
+      jest.runAllTimers();
+    });
+
+    expect(document.querySelector('.rc-image-preview')).toBeTruthy();
+  });
+
+  it('Pressing Space on image wrapper should open preview', () => {
+    const { container } = render(<Image src="src" alt="keyboard open space" />);
+
+    const wrapper = container.querySelector('.rc-image') as HTMLElement;
+    wrapper.focus();
+    fireEvent.keyDown(wrapper, { key: ' ' });
+
+    act(() => {
+      jest.runAllTimers();
+    });
+
+    expect(document.querySelector('.rc-image-preview')).toBeTruthy();
+  });
+
+  it('Preview dialog should have role dialog and receive focus', () => {
+    render(<Image src="src" alt="dialog a11y" preview={{ open: true }} />);
+
+    const preview = document.querySelector('.rc-image-preview') as HTMLElement;
+    expect(preview).toHaveAttribute('role', 'dialog');
+    expect(preview).toHaveAttribute('aria-modal', 'true');
+    expect(preview).toHaveAttribute('aria-label', 'dialog a11y');
+  });
+
+  it('Preview wrapper should be focusable after portal renders', () => {
+    const rectSpy = jest.spyOn(HTMLElement.prototype, 'getBoundingClientRect').mockReturnValue({
+      x: 0,
+      y: 0,
+      width: 100,
+      height: 100,
+      top: 0,
+      right: 100,
+      bottom: 100,
+      left: 0,
+      toJSON: () => undefined,
+    } as DOMRect);
+
+    render(<Image src="src" alt="focus portal" preview={{ open: true }} />);
+
+    act(() => {
+      jest.runAllTimers();
+    });
+
+    const preview = document.querySelector('.rc-image-preview') as HTMLElement;
+
+    expect(preview.contains(document.activeElement)).toBeTruthy();
+
+    rectSpy.mockRestore();
+  });
+
+  it('Preview open should render focusable wrapper', () => {
+    render(<Image src="src" alt="focus test" preview={{ open: true }} />);
+
+    const preview = document.querySelector('.rc-image-preview') as HTMLElement;
+    expect(preview).toHaveAttribute('tabindex', '-1');
+  });
+
+  it('Pressing Enter should not open preview when preview is disabled', () => {
+    const { container } = render(<Image src="src" alt="disabled preview" preview={false} />);
+
+    const wrapper = container.querySelector('.rc-image') as HTMLElement;
+    wrapper.focus();
+    fireEvent.keyDown(wrapper, { key: 'Enter' });
+
+    act(() => {
+      jest.runAllTimers();
+    });
+
+    expect(document.querySelector('.rc-image-preview')).toBeFalsy();
+  });
 });

tests/previewGroup.test.tsx

@@ -108,6 +108,25 @@ describe('PreviewGroup', () => {
     expect(document.querySelector('.rc-image-preview')).toBeFalsy();
   });
 
+  it('Keyboard Enter should open preview from group image', () => {
+    const { container } = render(
+      <Image.PreviewGroup>
+        <Image src="src1" alt="first" />
+        <Image src="src2" alt="second" />
+      </Image.PreviewGroup>,
+    );
+
+    const first = container.querySelector('.rc-image') as HTMLElement;
+    first.focus();
+    fireEvent.keyDown(first, { key: 'Enter' });
+
+    act(() => {
+      jest.runAllTimers();
+    });
+
+    expect(document.querySelector('.rc-image-preview')).toBeTruthy();
+  });
+
   it('Preview with Custom Preview Property', () => {
     const { container } = render(
       <Image.PreviewGroup