feat: better a11y

package.json

@@ -48,6 +48,7 @@
   "devDependencies": {
     "@rc-component/father-plugin": "^2.0.1",
     "@rc-component/np": "^1.0.3",
+    "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.0",
     "@types/jest": "^29.4.0",
     "@types/node": "^22.15.18",

src/Tooltip.tsx

@@ -60,7 +60,7 @@ export interface TooltipRef extends TriggerRef {}
 
 const Tooltip = React.forwardRef<TooltipRef, TooltipProps>((props, ref) => {
   const {
-    trigger = ['hover'],
+    trigger = ['hover','focus'],
     mouseEnterDelay = 0,
     mouseLeaveDelay = 0.1,
     prefixCls = 'rc-tooltip',
@@ -79,6 +79,7 @@ const Tooltip = React.forwardRef<TooltipRef, TooltipProps>((props, ref) => {
     showArrow = true,
     classNames,
     styles,
+    forceRender,
     ...restProps
   } = props;
 
@@ -93,6 +94,51 @@ const Tooltip = React.forwardRef<TooltipRef, TooltipProps>((props, ref) => {
     extraProps.popupVisible = props.visible;
   }
 
+  const isControlled = 'visible' in props;
+  const mergedVisible = props.visible;
+  const [popupMounted, setPopupMounted] = React.useState(() => {
+    if (forceRender) {
+      return true;
+    }
+    if (isControlled) {
+      return mergedVisible;
+    }
+    return defaultVisible;
+  });
+
+  const updatePopupMounted = React.useCallback(
+    (nextVisible: boolean) => {
+      setPopupMounted((prev) => {
+        if (nextVisible) {
+          return true;
+        }
+
+        if (destroyOnHidden) {
+          return false;
+        }
+
+        return prev;
+      });
+    },
+    [forceRender, destroyOnHidden],
+  );
+
+  const handleVisibleChange = (nextVisible: boolean) => {
+    updatePopupMounted(nextVisible);
+    onVisibleChange?.(nextVisible);
+  };
+
+  React.useEffect(() => {
+    if (forceRender) {
+      setPopupMounted(true);
+      return;
+    }
+
+    if (isControlled) {
+      setPopupMounted(mergedVisible);
+    }
+  }, [forceRender, isControlled, mergedVisible]);
+
   // ========================= Arrow ==========================
   // Process arrow configuration
   const mergedArrow = React.useMemo(() => {
@@ -118,7 +164,7 @@ const Tooltip = React.forwardRef<TooltipRef, TooltipProps>((props, ref) => {
     const originalProps = child?.props || {};
     const childProps = {
       ...originalProps,
-      'aria-describedby': overlay ? mergedId : null,
+      'aria-describedby': overlay && popupMounted ? mergedId : null,
     };
     return React.cloneElement<any>(children, childProps) as any;
   };
@@ -145,10 +191,11 @@ const Tooltip = React.forwardRef<TooltipRef, TooltipProps>((props, ref) => {
       ref={triggerRef}
       popupAlign={align}
       getPopupContainer={getTooltipContainer}
-      onOpenChange={onVisibleChange}
+      onOpenChange={handleVisibleChange}
       afterOpenChange={afterVisibleChange}
       popupMotion={motion}
       defaultPopupVisible={defaultVisible}
+      forceRender={forceRender}
       autoDestroy={destroyOnHidden}
       mouseLeaveDelay={mouseLeaveDelay}
       popupStyle={styles?.root}

tests/index.test.tsx

@@ -502,14 +502,24 @@ describe('rc-tooltip', () => {
   });
 
   describe('children handling', () => {
-    it('should pass aria-describedby to child element when overlay exists', () => {
+    it('should only set aria-describedby once popup is mounted', async () => {
       const { container } = render(
-        <Tooltip id="test-id" overlay="tooltip content">
+        <Tooltip trigger={['click']} overlay="tooltip content">
           <button>Click me</button>
         </Tooltip>,
       );
 
-      expect(container.querySelector('button')).toHaveAttribute('aria-describedby', 'test-id');
+      const btn = container.querySelector('button');
+      expect(btn).not.toHaveAttribute('aria-describedby');
+
+      fireEvent.click(btn);
+      await waitFakeTimers();
+      const describedby = btn.getAttribute('aria-describedby');
+      expect(describedby).toBeTruthy();
+
+      fireEvent.click(btn);
+      await waitFakeTimers();
+      expect(btn).toHaveAttribute('aria-describedby', describedby);
     });
 
     it('should not pass aria-describedby when overlay is empty', () => {
@@ -522,6 +532,45 @@ describe('rc-tooltip', () => {
       expect(container.querySelector('button')).not.toHaveAttribute('aria-describedby');
     });
 
+    it('should set aria-describedby immediately when defaultVisible is true', () => {
+      const { container } = render(
+        <Tooltip defaultVisible overlay="tooltip content">
+          <button>Click me</button>
+        </Tooltip>,
+      );
+
+      expect(container.querySelector('button')).toHaveAttribute('aria-describedby');
+    });
+
+    it('should set aria-describedby immediately when forceRender is true', () => {
+      const { container } = render(
+        <Tooltip forceRender overlay="tooltip content">
+          <button>Click me</button>
+        </Tooltip>,
+      );
+
+      expect(container.querySelector('button')).toHaveAttribute('aria-describedby');
+    });
+
+    it('should remove aria-describedby when popup is destroyed on hide', async () => {
+      const { container } = render(
+        <Tooltip destroyOnHidden trigger={['click']} overlay="tooltip content">
+          <button>Click me</button>
+        </Tooltip>,
+      );
+
+      const btn = container.querySelector('button');
+      expect(btn).not.toHaveAttribute('aria-describedby');
+
+      fireEvent.click(btn);
+      await waitFakeTimers();
+      expect(btn).toHaveAttribute('aria-describedby');
+
+      fireEvent.click(btn);
+      await waitFakeTimers();
+      expect(btn).not.toHaveAttribute('aria-describedby');
+    });
+
     it('should preserve original props of children', () => {
       const onMouseEnter = jest.fn();
 

tsconfig.json

@@ -7,6 +7,7 @@
     "declaration": true,
     "skipLibCheck": true,
     "esModuleInterop": true,
+    "types": ["@testing-library/jest-dom"],
     "paths": {
       "@/*": [
         "src/*"