feat: improve Image preview accessibility

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;

src/Image.tsx

@@ -203,6 +203,31 @@ const ImageInternal: CompoundedComponent<ImageProps> = props => {
     onClick?.(e);
   };
 
+  // ======================= Keyboard Preview =====================
+  const onPreviewKeyDown: React.KeyboardEventHandler<HTMLDivElement> = 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 +237,15 @@ 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 ?? 'Preview image') : otherProps['aria-label']
+        }
+        onKeyDown={event => {
+          onPreviewKeyDown(event);
+          (otherProps as any).onKeyDown?.(event);
+        }}
         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

@@ -23,22 +23,28 @@ export default function PrevNext(props: PrevNextProps) {
 
   return (
     <>
-      <div
+      <button
+        type="button"
         className={clsx(switchCls, `${switchCls}-prev`, {
           [`${switchCls}-disabled`]: current === 0,
         })}
         onClick={() => onActive(-1)}
+        disabled={current === 0}
+        aria-label="Previous image"
       >
         {prev ?? left}
-      </div>
-      <div
+      </button>
+      <button
+        type="button"
         className={clsx(switchCls, `${switchCls}-next`, {
           [`${switchCls}-disabled`]: current === count - 1,
         })}
         onClick={() => onActive(1)}
+        disabled={current === count - 1}
+        aria-label="Next image"
       >
         {next ?? right}
-      </div>
+      </button>
     </>
   );
 }

src/Preview/index.tsx

@@ -195,6 +195,8 @@ const Preview: React.FC<PreviewProps> = props => {
   } = props;
 
   const imgRef = useRef<HTMLImageElement>();
+  const wrapperRef = useRef<HTMLDivElement>(null);
+  const lastActiveRef = useRef<HTMLElement | null>(null);
   const groupContext = useContext(PreviewGroupContext);
   const showLeftOrRightSwitches = groupContext && count > 1;
   const showOperationsProgress = groupContext && count >= 1;
@@ -382,6 +384,22 @@ const Preview: React.FC<PreviewProps> = props => {
     }
   };
 
+  // =========================== Focus ============================
+  useEffect(() => {
+    if (open) {
+      lastActiveRef.current = (document.activeElement as HTMLElement) || null;
+
+      // When `open` is initially true, the portal content is rendered in a later effect.
+      // Depend on `portalRender` so we can focus once the wrapper is actually mounted.
+      if (wrapperRef.current && portalRender) {
+        wrapperRef.current.focus();
+      }
+    } else if (!open && lastActiveRef.current) {
+      lastActiveRef.current.focus();
+      lastActiveRef.current = null;
+    }
+  }, [open, portalRender]);
+
   // ========================== Render ==========================
   const bodyStyle: React.CSSProperties = {
     ...styles.body,
@@ -418,10 +436,15 @@ const Preview: React.FC<PreviewProps> = props => {
 
           return (
             <div
+              ref={wrapperRef}
               className={clsx(prefixCls, rootClassName, classNames.root, motionClassName, {
                 [`${prefixCls}-moving`]: isMoving,
               })}
               style={mergedStyle}
+              role="dialog"
+              aria-modal="true"
+              aria-label={alt || 'Image preview'}
+              tabIndex={-1}
             >
               {/* Mask */}
               <div

tests/__snapshots__/basic.test.tsx.snap

@@ -2,8 +2,11 @@
 
 exports[`Basic snapshot 1`] = `
 <div
+  aria-label="Preview image"
   class="rc-image"
+  role="button"
   style="width: 200px;"
+  tabindex="0"
 >
   <img
     class="rc-image-img"

tests/preview.test.tsx

@@ -1144,4 +1144,83 @@ 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 should focus wrapper after portal renders', () => {
+    const focusSpy = jest.spyOn(HTMLElement.prototype, 'focus');
+
+    render(<Image src="src" alt="focus portal" preview={{ open: true }} />);
+
+    act(() => {
+      jest.runAllTimers();
+    });
+
+    expect(focusSpy).toHaveBeenCalled();
+    focusSpy.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