fix: lock focus inside preview when opened via keyboard (#505)

* fix: ensure focus is properly locked inside preview when opened via keyboard

The preview wrapper DOM element is not immediately available due to
CSSMotion's deferred rendering (styleReady='NONE' on first render).
Using useRef meant useLockFocus could never re-evaluate after the DOM
appeared. Switch to useState callback ref so the component re-renders
once the wrapper mounts, allowing useLockFocus to activate correctly.

Also restores focus to the trigger element after the preview closes.

* fix: update focus lock implementation in Preview component

Author: aojunhao123

package.json

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

src/Preview/index.tsx

@@ -197,6 +197,8 @@ const Preview: React.FC<PreviewProps> = props => {
 
   const imgRef = useRef<HTMLImageElement>();
   const wrapperRef = useRef<HTMLDivElement>(null);
+  const triggerRef = useRef<HTMLElement>(null);
+
   const groupContext = useContext(PreviewGroupContext);
   const showLeftOrRightSwitches = groupContext && count > 1;
   const showOperationsProgress = groupContext && count >= 1;
@@ -366,6 +368,10 @@ const Preview: React.FC<PreviewProps> = props => {
   const onVisibleChanged = (nextVisible: boolean) => {
     if (!nextVisible) {
       setLockScroll(false);
+
+      // Restore focus to the trigger element after leave animation
+      triggerRef.current?.focus?.();
+      triggerRef.current = null;
     }
     afterOpenChange?.(nextVisible);
   };
@@ -385,6 +391,12 @@ const Preview: React.FC<PreviewProps> = props => {
   };
 
   // =========================== Focus ============================
+  useLayoutEffect(() => {
+    if (open) {
+      triggerRef.current = document.activeElement as HTMLElement;
+    }
+  }, [open]);
+
   useLockFocus(open && portalRender, () => wrapperRef.current);
 
   // ========================== Render ==========================

tests/preview.test.tsx

@@ -1256,4 +1256,44 @@ describe('Preview', () => {
 
     expect(document.querySelector('.rc-image-preview')).toBeFalsy();
   });
+
+  it('Focus should be trapped inside preview after keyboard open and restored on close', () => {
+    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);
+
+    const { container } = render(<Image src="src" alt="focus trap" />);
+    const wrapper = container.querySelector('.rc-image') as HTMLElement;
+
+    // Open preview via keyboard
+    wrapper.focus();
+    expect(document.activeElement).toBe(wrapper);
+
+    fireEvent.keyDown(wrapper, { key: 'Enter' });
+    act(() => {
+      jest.runAllTimers();
+    });
+
+    // Focus should be inside the preview
+    const preview = document.querySelector('.rc-image-preview') as HTMLElement;
+    expect(preview).toBeTruthy();
+    expect(preview.contains(document.activeElement)).toBeTruthy();
+
+    // Focus should not escape when trying to focus outside
+    wrapper.focus();
+    expect(preview.contains(document.activeElement)).toBeTruthy();
+
+    // Close preview via Escape
+    fireEvent.keyDown(window, { key: 'Escape' });
+    act(() => {
+      jest.runAllTimers();
+    });
+
+    // Focus should return to the trigger element
+    expect(document.activeElement).toBe(wrapper);
+
+    rectSpy.mockRestore();
+  });
 });