feat: add focusTrap prop to preview config (#507)

Add `focusTrap` option to `InternalPreviewConfig` (default `true`).
When set to `false`, the preview will not trap focus via `useLockFocus`.

This aligns with rc-dialog and rc-drawer which both support controlling
focus trapping behavior. The main use case is rendering an always-open
preview inline (e.g. for documentation semantic demos), where the global
focus lock incorrectly prevents keyboard interaction with the rest of
the page.

Author: aojunhao123

src/Preview/index.tsx

@@ -90,6 +90,10 @@ export interface InternalPreviewConfig {
   maskClosable?: boolean;
   afterOpenChange?: (open: boolean) => void;
 
+  // Focus
+  /** Whether to trap focus within the preview when open. Default is true. */
+  focusTrap?: boolean;
+
   // Operation
   movable?: boolean;
   icons?: OperationIcons;
@@ -195,6 +199,7 @@ const Preview: React.FC<PreviewProps> = props => {
     styles = {},
     mousePosition,
     zIndex,
+    focusTrap = true,
   } = props;
 
   const imgRef = useRef<HTMLImageElement>();
@@ -399,7 +404,7 @@ const Preview: React.FC<PreviewProps> = props => {
     }
   }, [open]);
 
-  useLockFocus(open && portalRender, () => wrapperRef.current);
+  useLockFocus(focusTrap && open && portalRender, () => wrapperRef.current);
 
   // ========================== Render ==========================
   const bodyStyle: React.CSSProperties = {

tests/preview.test.tsx

@@ -1323,4 +1323,28 @@ describe('Preview', () => {
 
     rectSpy.mockRestore();
   });
+
+  it('Focus should not be trapped when focusTrap is false', () => {
+    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="no trap" preview={{ open: true, focusTrap: false }} />);
+
+    act(() => {
+      jest.runAllTimers();
+    });
+
+    const preview = document.querySelector('.rc-image-preview') as HTMLElement;
+    expect(preview).toBeTruthy();
+
+    // Focus outside the preview should not be redirected back
+    const wrapper = container.querySelector('.rc-image') as HTMLElement;
+    wrapper.focus();
+    expect(document.activeElement).toBe(wrapper);
+
+    rectSpy.mockRestore();
+  });
 });