feat: add escape event handling for better a11y

.gitignore

@@ -28,6 +28,7 @@ yarn.lock
 package-lock.json
 pnpm-lock.yaml
 .doc
+.vscode
 
 # dumi
 .dumi/tmp

docs/examples/basic.tsx

@@ -41,11 +41,17 @@ export default () => {
           />
         </div>
 
-        <Portal open={show} getContainer={getContainer} autoLock={lock}>
+        <Portal open={show} getContainer={getContainer} autoLock={lock} onEsc={({ top, event }) => {
+          console.log('root onEsc', { top, event });
+        }}>
           <p className={clsx(contentCls, 'root')}>Hello Root</p>
-          <Portal open={show} getContainer={getContainer} autoLock={lock}>
+          <Portal open={show} getContainer={getContainer} autoLock={lock} onEsc={({ top, event }) => {
+            console.log('parent onEsc', { top, event });
+          }}>
             <p className={clsx(contentCls, 'parent')}>Hello Parent</p>
-            <Portal open={show} getContainer={getContainer} autoLock={lock}>
+            <Portal open={show} getContainer={getContainer} autoLock={lock} onEsc={({ top, event }) => {
+              console.log('children onEsc', { top, event });
+            }}>
               <p className={clsx(contentCls, 'children')}>Hello Children</p>
             </Portal>
           </Portal>

package.json

@@ -50,7 +50,7 @@
   "devDependencies": {
     "@rc-component/father-plugin": "^2.0.2",
     "@rc-component/np": "^1.0.3",
-    "@testing-library/jest-dom": "^5.16.4",
+    "@testing-library/jest-dom": "^6.9.0",
     "@testing-library/react": "^13.0.0",
     "@types/jest": "^26.0.20",
     "@types/node": "^20.9.0",

src/Portal.tsx

@@ -11,6 +11,7 @@ import OrderContext from './Context';
 import { inlineMock } from './mock';
 import useDom from './useDom';
 import useScrollLocker from './useScrollLocker';
+import useEscKeyDown from './useEscKeyDown';
 
 export type ContainerType = Element | DocumentFragment;
 
@@ -20,6 +21,14 @@ export type GetContainer =
   | (() => ContainerType)
   | false;
 
+export type EscCallback = ({
+  top,
+  event,
+}: {
+  top: boolean;
+  event: KeyboardEvent;
+}) => void;
+
 export interface PortalProps {
   /** Customize container element. Default will create a div in document.body when `open` */
   getContainer?: GetContainer;
@@ -30,6 +39,7 @@ export interface PortalProps {
   autoDestroy?: boolean;
   /** Lock screen scroll when open */
   autoLock?: boolean;
+  onEsc?: EscCallback;
 
   /** @private debug name. Do not use in prod */
   debug?: string;
@@ -61,6 +71,7 @@ const Portal = React.forwardRef<any, PortalProps>((props, ref) => {
     debug,
     autoDestroy = true,
     children,
+    onEsc,
   } = props;
 
   const [shouldRender, setShouldRender] = React.useState(open);
@@ -109,6 +120,9 @@ const Portal = React.forwardRef<any, PortalProps>((props, ref) => {
         mergedContainer === document.body),
   );
 
+  // ========================= Esc Keydown ==========================
+  useEscKeyDown(open, onEsc);
+
   // =========================== Ref ===========================
   let childRef: React.Ref<any> = null;
 

src/useEscKeyDown.ts

@@ -0,0 +1,37 @@
+import { useEffect, useMemo } from 'react';
+import { type EscCallback } from './Portal';
+import useId from '@rc-component/util/lib/hooks/useId';
+import { useEvent } from '@rc-component/util';
+
+let stack: string[] = [];
+
+export default function useEscKeyDown(open: boolean, onEsc?: EscCallback) {
+  const id = useId();
+
+  const handleEscKeyDown = useEvent((event: KeyboardEvent) => {
+    if (event.key === 'Escape') {
+      const top = stack[stack.length - 1] === id;
+      onEsc?.({ top, event });
+    }
+  });
+
+  useMemo(() => {
+    if (open && !stack.includes(id)) {
+      stack.push(id);
+    } else if (!open) {
+      stack = stack.filter(item => item !== id);
+    }
+  }, [open, id]);
+
+  useEffect(() => {
+    if (!open) {
+      return;
+    }
+
+    window.addEventListener('keydown', handleEscKeyDown);
+
+    return () => {
+      window.removeEventListener('keydown', handleEscKeyDown);
+    };
+  }, [open, id]);
+}

tests/index.test.tsx

@@ -1,4 +1,4 @@
-import { render } from '@testing-library/react';
+import { render, fireEvent } from '@testing-library/react';
 import React from 'react';
 import Portal from '../src';
 
@@ -18,6 +18,11 @@ jest.mock('@rc-component/util/lib/hooks/useLayoutEffect', () => {
   return origin.useLayoutEffect;
 });
 
+jest.mock('@rc-component/util/lib/hooks/useId', () => {
+  const origin = jest.requireActual('react');
+  return origin.useId;
+});
+
 describe('Portal', () => {
   beforeEach(() => {
     global.isOverflow = true;
@@ -290,4 +295,65 @@ describe('Portal', () => {
 
     expect(document.querySelector('.checker').textContent).toEqual('true');
   });
+
+  describe('onEsc', () => {
+    it('only last opened portal is top', () => {
+      const onEscA = jest.fn();
+      const onEscB = jest.fn();
+
+      render(
+        <>
+          <Portal open onEsc={onEscA}>
+            <div />
+          </Portal>
+          <Portal open onEsc={onEscB}>
+            <div />
+          </Portal>
+        </>,
+      );
+
+      fireEvent.keyDown(window, { key: 'Escape' });
+
+      expect(onEscA).toHaveBeenCalledWith(
+        expect.objectContaining({ top: false }),
+      );
+      expect(onEscB).toHaveBeenCalledWith(
+        expect.objectContaining({ top: true }),
+      );
+    });
+
+    it('top changes after portal closes', () => {
+      const onEscA = jest.fn();
+      const onEscB = jest.fn();
+
+      const { rerender } = render(
+        <>
+          <Portal open onEsc={onEscA}>
+            <div />
+          </Portal>
+          <Portal open onEsc={onEscB}>
+            <div />
+          </Portal>
+        </>,
+      );
+
+      rerender(
+        <>
+          <Portal open onEsc={onEscA}>
+            <div />
+          </Portal>
+          <Portal open={false} onEsc={onEscB}>
+            <div />
+          </Portal>
+        </>,
+      );
+
+      fireEvent.keyDown(window, { key: 'Escape' });
+
+      expect(onEscA).toHaveBeenCalledWith(
+        expect.objectContaining({ top: true }),
+      );
+      expect(onEscB).not.toHaveBeenCalled();
+    });
+  });
 });