Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

perf(HoverCard): keep trigger refs stable across rerenders (#6606)

Manohar Paturi9b386faf7ef5
diff --git a/.changeset/keep-hovercard-refs-stable-across-rerenders.md b/.changeset/keep-hovercard-refs-stable-across-rerenders.md
new file mode 100644
index 0000000000..0e0feb684b
--- /dev/null
+++ b/.changeset/keep-hovercard-refs-stable-across-rerenders.md
@@ -0,0 +1,6 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] Keep `useHoverCard()` trigger refs stable across unchanged rerenders. The hook returned a fresh `ref`/`interactionRef` on every render because its callbacks depended on the whole `layer` and `touch` objects, which are rebuilt each render — React detached and re-attached every trigger listener and rewrote the trigger's inline `anchor-name` on each rerender. Hooks now depend on the stable layer and touch members instead, mirroring the Tooltip fix in #5951. (#6472)
+@ManoharPaturi
diff --git a/packages/core/src/HoverCard/HoverCard.test.tsx b/packages/core/src/HoverCard/HoverCard.test.tsx
index 12a0e80d7a..a6ce67b1ab 100644
--- a/packages/core/src/HoverCard/HoverCard.test.tsx
+++ b/packages/core/src/HoverCard/HoverCard.test.tsx
@@ -18,13 +18,21 @@ import {
beforeEach,
afterAll,
} from 'vitest';
-import {render, screen, fireEvent, waitFor, act} from '@testing-library/react';
+import {
+ render,
+ renderHook,
+ screen,
+ fireEvent,
+ waitFor,
+ act,
+} from '@testing-library/react';
import {renderToString} from 'react-dom/server';
import {hydrateRoot} from 'react-dom/client';
import {StrictMode} from 'react';
import {Button} from '../Button/Button';
import {Theme, defineTheme} from '../theme';
import {HoverCard} from './HoverCard';
+import {useHoverCard} from './useHoverCard';
import {__resetInteractionModalityForTest} from '../utils/interactionModality';
// Store original matches to restore later
@@ -64,6 +72,43 @@ beforeEach(() => {
vi.mocked(HTMLElement.prototype.hidePopover).mockClear();
});
+describe('useHoverCard identity', () => {
+ it('keeps callback refs stable across unchanged rerenders', () => {
+ const {result, rerender} = renderHook(() => useHoverCard());
+ const firstRef = result.current.ref;
+ const firstInteractionRef = result.current.interactionRef;
+
+ rerender();
+
+ expect(result.current.ref).toBe(firstRef);
+ expect(result.current.interactionRef).toBe(firstInteractionRef);
+ });
+
+ it('does not rebind trigger listeners on rerender', () => {
+ function Harness() {
+ const card = useHoverCard();
+ return (
+ <div>
+ <span ref={card.ref}>Trigger</span>
+ {card.renderHoverCard(<div>Card</div>)}
+ </div>
+ );
+ }
+ const {getByText, rerender} = render(<Harness />);
+ const trigger = getByText('Trigger');
+ const added: string[] = [];
+ const add = trigger.addEventListener.bind(trigger);
+ trigger.addEventListener = ((type: string, ...rest: unknown[]) => {
+ added.push(type);
+ return (add as (...args: unknown[]) => void)(type, ...rest);
+ }) as typeof trigger.addEventListener;
+
+ rerender(<Harness />);
+
+ expect(added).toEqual([]);
+ });
+});
+
describe('HoverCard', () => {
it('renders trigger element', () => {
render(
diff --git a/packages/core/src/HoverCard/useHoverCard.tsx b/packages/core/src/HoverCard/useHoverCard.tsx
index b8c6929fa9..64f256591e 100644
--- a/packages/core/src/HoverCard/useHoverCard.tsx
+++ b/packages/core/src/HoverCard/useHoverCard.tsx
@@ -5,7 +5,7 @@
/**
* @file useHoverCard.ts
* @input Uses useLayer, useTouchTrigger, React hooks
- * @output Exports useHoverCard hook for hover/focus/tap triggered layers
+ * @output Exports useHoverCard hook with stable trigger refs for hover/focus/tap layers
* @position Layer hook; builds on useLayer for hover card behavior
*
* SYNC: When modified, update:
@@ -295,6 +295,21 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
onShow,
onHide,
});
+ // Destructure the layer and touch objects once: both are rebuilt every
+ // render, but their members are stable. Depending on the members instead of
+ // the enclosing objects keeps the refs below identity-stable across
+ // unchanged rerenders, so React never detaches and re-attaches the trigger
+ // (and never rewrites the trigger's `anchor-name`) while the card streams
+ // alongside it.
+ const {
+ ref: layerRef,
+ anchorId: layerAnchorId,
+ show: showLayer,
+ hide: hideLayer,
+ isOpen: isLayerOpen,
+ id: layerId,
+ render: renderLayer,
+ } = layer;
const popoverXstyle = styles.container;
@@ -321,21 +336,27 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
// passing across the trigger, and a tap is never that.
const showNow = useCallback(() => {
clearTimeouts();
- layer.show();
- }, [clearTimeouts, layer]);
+ showLayer();
+ }, [clearTimeouts, showLayer]);
const hideNow = useCallback(() => {
clearTimeouts();
isHoveringContentRef.current = false;
- layer.hide();
- }, [clearTimeouts, layer]);
+ hideLayer();
+ }, [clearTimeouts, hideLayer]);
- const touch = useTouchTrigger({
+ const {
+ isTouchPointerRef,
+ isTouchInteraction,
+ handlePointerEnter,
+ handlePointerDown: handleTouchPointerDown,
+ clearTapOpen,
+ } = useTouchTrigger({
touchTrigger,
isEnabled,
isControlled: isOpen !== undefined,
- isOpen: layer.isOpen,
- layerId: layer.id,
+ isOpen: isLayerOpen,
+ layerId: layerId,
triggerRef,
show: showNow,
hide: hideNow,
@@ -348,9 +369,9 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
}
clearTimeouts();
showTimeoutRef.current = setTimeout(() => {
- layer.show();
+ showLayer();
}, delay);
- }, [isEnabled, isOpen, clearTimeouts, layer, delay]);
+ }, [isEnabled, isOpen, clearTimeouts, showLayer, delay]);
// Schedule hide with delay (suppressed when isOpen is true)
const scheduleHide = useCallback(() => {
@@ -361,37 +382,37 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
hideTimeoutRef.current = setTimeout(() => {
// Don't hide if hovering content
if (!isHoveringContentRef.current) {
- layer.hide();
+ hideLayer();
}
}, hideDelay);
- }, [isOpen, clearTimeouts, layer, hideDelay]);
+ }, [isOpen, clearTimeouts, hideLayer, hideDelay]);
// Event handlers
const handleMouseEnter = useCallback(() => {
// A tap synthesizes mouseenter. On touch the tap path owns the decision,
// so hover must not also fire — without this a hover card opens on every
// tap of its trigger and has nothing to close it.
- if (touch.isTouchPointerRef.current) {
+ if (isTouchPointerRef.current) {
return;
}
scheduleShow();
- }, [touch, scheduleShow]);
+ }, [isTouchPointerRef, scheduleShow]);
const handleMouseLeave = useCallback(() => {
// On touch the synthesized mouseleave arrives with the next tap elsewhere,
// which the outside-tap dismissal already handles.
- if (touch.isTouchPointerRef.current) {
+ if (isTouchPointerRef.current) {
return;
}
scheduleHide();
- }, [touch, scheduleHide]);
+ }, [isTouchPointerRef, scheduleHide]);
// Tap-to-open on touch; on a mouse this does nothing and hover still rules.
const handlePointerDown = useCallback(
(event: PointerEvent) => {
- touch.handlePointerDown(event);
+ handleTouchPointerDown(event);
},
- [touch],
+ [handleTouchPointerDown],
);
const handleFocusIn = useCallback(() => {
@@ -401,7 +422,7 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
// A tap focuses the trigger it activates. Opening on that focus would
// reinstate exactly the behavior the touch path just decided against —
// and on an action trigger it covers the thing the user tapped.
- if (touch.isTouchInteraction()) {
+ if (isTouchInteraction()) {
return;
}
// Skip showing if we're in the middle of an Escape dismiss
@@ -410,14 +431,14 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
return;
}
clearTimeouts();
- layer.show();
- }, [isEnabled, touch, clearTimeouts, layer]);
+ showLayer();
+ }, [isEnabled, isTouchInteraction, clearTimeouts, showLayer]);
const handleFocusOut = useCallback(
(e: FocusEvent) => {
// Check if focus is moving to the hover card content
const relatedTarget = e.relatedTarget as HTMLElement | null;
- const popoverElement = document.getElementById(layer.id);
+ const popoverElement = document.getElementById(layerId);
if (popoverElement?.contains(relatedTarget)) {
// Focus moving into hover card, keep it open
@@ -426,7 +447,7 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
scheduleHide();
},
- [layer.id, scheduleHide],
+ [layerId, scheduleHide],
);
// Escape dismissal (WCAG 1.4.13) goes through the shared layer stack: a
@@ -453,7 +474,7 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
const el =
typeof document === 'undefined'
? null
- : document.getElementById(layer.id);
+ : document.getElementById(layerId);
if (el == null) {
return false;
}
@@ -462,12 +483,12 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
} catch {
// Browsers without the Popover API (and some test environments) cannot
// answer the selector; fall back to the hook's own state.
- return layer.isOpen;
+ return isLayerOpen;
}
},
onDismiss: () => {
clearTimeouts();
- touch.clearTapOpen();
+ clearTapOpen();
// Controlled: report and stop. The close — and the focus restore that
// goes with it — happens in the controlled effect if and when the
// consumer flips `isOpen`.
@@ -485,9 +506,9 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
const card =
typeof document === 'undefined'
? null
- : document.getElementById(layer.id);
+ : document.getElementById(layerId);
const hadFocus = card?.contains(document.activeElement) ?? false;
- layer.hide();
+ hideLayer();
if (hadFocus) {
isEscapeDismissingRef.current = true;
triggerRef.current?.focus();
@@ -496,7 +517,6 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
});
// Interaction ref that handles event listeners only
- const {handlePointerEnter} = touch;
const interactionRef: RefCallback<HTMLElement> = useCallback(
(el: HTMLElement | null) => {
// Cleanup previous element
@@ -554,10 +574,10 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
// Combined ref - shorthand for calling both positionRef and interactionRef
const ref: RefCallback<HTMLElement> = useCallback(
(el: HTMLElement | null) => {
- layer.ref(el);
+ layerRef(el);
interactionRef(el);
},
- [layer, interactionRef],
+ [layerRef, interactionRef],
);
// Cleanup on unmount
@@ -570,7 +590,7 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
// Show on mount when isDefaultOpen is true
useEffect(() => {
if (isDefaultOpen) {
- layer.show();
+ showLayer();
}
// eslint-disable-next-line @eslint-react/exhaustive-deps -- intentionally only on mount
}, []);
@@ -582,7 +602,7 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
}
if (isOpen) {
clearTimeouts();
- layer.show();
+ showLayer();
} else {
clearTimeouts();
// A consumer closing the card while it holds focus would strand focus on
@@ -591,15 +611,15 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
const card =
typeof document === 'undefined'
? null
- : document.getElementById(layer.id);
+ : document.getElementById(layerId);
const hadFocus = card?.contains(document.activeElement) ?? false;
- layer.hide();
+ hideLayer();
if (hadFocus) {
isEscapeDismissingRef.current = true;
triggerRef.current?.focus();
}
}
- }, [isOpen, clearTimeouts, layer]);
+ }, [isOpen, clearTimeouts, showLayer, hideLayer, layerId]);
// Render function that wraps layer.render with hover card behavior
const renderHoverCard = useCallback(
@@ -636,20 +656,20 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
as: 'div' as const,
};
- return layer.render(
+ return renderLayer(
<div
{...stylex.props(styles.content)}
onMouseEnter={() => {
// Touch synthesizes these over the card too; letting a tap inside
// register as "hovering content" would block every later hide.
- if (touch.isTouchPointerRef.current) {
+ if (isTouchPointerRef.current) {
return;
}
isHoveringContentRef.current = true;
clearTimeouts();
}}
onMouseLeave={() => {
- if (touch.isTouchPointerRef.current) {
+ if (isTouchPointerRef.current) {
return;
}
isHoveringContentRef.current = false;
@@ -679,27 +699,27 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
);
},
[
- layer,
+ renderLayer,
placement,
alignment,
label,
clearTimeouts,
scheduleHide,
popoverXstyle,
- touch,
+ isTouchPointerRef,
],
);
return {
ref,
- positionRef: layer.ref,
+ positionRef: layerRef,
interactionRef,
- anchorId: layer.anchorId,
- id: layer.id,
- describedBy: layer.id,
- isOpen: layer.isOpen,
+ anchorId: layerAnchorId,
+ id: layerId,
+ describedBy: layerId,
+ isOpen: isLayerOpen,
renderHoverCard,
- show: layer.show,
- hide: layer.hide,
+ show: showLayer,
+ hide: hideLayer,
};
}