Skip to content

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

TypeScript

fix(Tooltip): attach sibling-mode anchors rendered inside their own anchor (#7833)

Pushpak Siva Saicbe384c1462d
diff --git a/.changeset/tooltip-sibling-anchor-attaches-when-rendered-inside.md b/.changeset/tooltip-sibling-anchor-attaches-when-rendered-inside.md
new file mode 100644
index 0000000000..41d7389d3d
--- /dev/null
+++ b/.changeset/tooltip-sibling-anchor-attaches-when-rendered-inside.md
@@ -0,0 +1,11 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] Tooltip: attach sibling-mode anchors that render inside their own anchor (#7692)
+
+A `Tooltip` with an `anchorRef` that renders inside the very element the ref points at (how `SideNavItem` anchors its collapsed rail tooltip) never attached: React attaches an ancestor's ref after its descendants' layout effects, so the sibling-mode effect read `anchorRef.current` as `null` on mount, and its dependencies never changed to re-run it. An item that mounted inside an already-collapsed `SideNav` — the common case for persisted collapse state — showed no tooltip on hover and never got `aria-describedby`, while an item that collapsed after mounting worked because the anchor ref was already set by then.
+
+The effect now re-checks the anchor once the commit has finished attaching refs, so the tooltip attaches however it mounted. The attach/detach bookkeeping (event listeners, `aria-describedby` merge and restore) is unchanged.
+
+@Pushpak731
diff --git a/packages/core/src/SideNav/SideNav.test.tsx b/packages/core/src/SideNav/SideNav.test.tsx
index 5acfcaecf4..045e6cd30b 100644
--- a/packages/core/src/SideNav/SideNav.test.tsx
+++ b/packages/core/src/SideNav/SideNav.test.tsx
@@ -3691,3 +3691,38 @@ describe('SideNav collapse conflict warning', () => {
expect(warn).not.toHaveBeenCalled();
});
});
+
+// =============================================================================
+// SideNavItem — collapsed-from-mount rail tooltip
+// =============================================================================
+
+describe('SideNavItem collapsed-from-mount rail tooltip', () => {
+ // #7692: a childless item that mounts inside an already-collapsed SideNav
+ // renders its Tooltip inside the very element anchorRef points at. React
+ // attaches that ref only after the tooltip's layout effect has run, so the
+ // tooltip never attached and a persisted collapsed rail lost all tooltips
+ // on page load.
+ it('anchors the rail tooltip when the nav is collapsed at mount', async () => {
+ render(
+ <SideNav
+ aria-label="Main"
+ collapsible={{isCollapsed: true, hasButton: false}}>
+ <SideNavItem label="Dashboard" icon={StubIcon} href="/dashboard" />
+ </SideNav>,
+ );
+ const link = screen.getByRole('link', {name: 'Dashboard'});
+ const anchor = link.parentElement as HTMLElement;
+
+ // The tooltip attaches despite mounting inside its own anchor: the item
+ // row is described by the tooltip layer.
+ await waitFor(() => {
+ expect(anchor.getAttribute('aria-describedby')).not.toBe('');
+ });
+ const layer = document.getElementById(
+ anchor.getAttribute('aria-describedby') as string,
+ );
+ expect(layer).not.toBeNull();
+ expect(layer).toHaveAttribute('role', 'tooltip');
+ expect(layer).toHaveTextContent('Dashboard');
+ });
+});
diff --git a/packages/core/src/Tooltip/Tooltip.test.tsx b/packages/core/src/Tooltip/Tooltip.test.tsx
index 8eeef43b50..c5470cdb79 100644
--- a/packages/core/src/Tooltip/Tooltip.test.tsx
+++ b/packages/core/src/Tooltip/Tooltip.test.tsx
@@ -25,6 +25,7 @@ import {
fireEvent,
waitFor,
} from '@testing-library/react';
+import {useRef} from 'react';
import {Tooltip} from './Tooltip';
import {useTooltip} from './useTooltip';
import {__resetInteractionModalityForTest} from '../utils/interactionModality';
@@ -602,3 +603,49 @@ describe('Tooltip', () => {
});
});
});
+
+describe('Tooltip sibling mode (anchorRef)', () => {
+ // SideNavItem's collapsed rail tooltip renders the Tooltip inside the very
+ // element anchorRef points at. React attaches an ancestor's ref after its
+ // descendants' layout effects, so on mount the tooltip's effect used to see
+ // a null anchor and never retried (#7692).
+ it('attaches to an anchor it is rendered inside of', async () => {
+ const onOpenChange = vi.fn();
+ function AnchorInside() {
+ const anchorRef = useRef<HTMLDivElement>(null);
+ return (
+ <div ref={anchorRef}>
+ <button type="button">Inner</button>
+ <Tooltip
+ content="Sibling tooltip"
+ anchorRef={anchorRef}
+ delay={0}
+ onOpenChange={onOpenChange}
+ />
+ </div>
+ );
+ }
+
+ const {unmount} = render(<AnchorInside />);
+ const anchor = screen.getByRole('button', {name: 'Inner'})
+ .parentElement as HTMLElement;
+
+ // The anchor is described by the tooltip once the commit has attached refs.
+ await waitFor(() => {
+ expect(anchor.getAttribute('aria-describedby')).not.toBe('');
+ });
+ const layer = screen.getByRole('tooltip', {hidden: true});
+ expect(anchor.getAttribute('aria-describedby')).toBe(layer.id);
+
+ // Hovering the anchor opens the tooltip: the interaction listeners were
+ // attached to the late anchor too.
+ fireEvent.mouseEnter(anchor);
+ await waitFor(() => {
+ expect(onOpenChange).toHaveBeenCalledWith(true);
+ });
+
+ // Unmounting detaches: the aria-describedby the tooltip added is removed.
+ unmount();
+ expect(anchor.getAttribute('aria-describedby')).toBe(null);
+ });
+});
diff --git a/packages/core/src/Tooltip/Tooltip.tsx b/packages/core/src/Tooltip/Tooltip.tsx
index 5956864acf..867772d02a 100644
--- a/packages/core/src/Tooltip/Tooltip.tsx
+++ b/packages/core/src/Tooltip/Tooltip.tsx
@@ -242,28 +242,51 @@ export function Tooltip({
return;
}
+ const attach = (el: HTMLElement) => {
+ // Use combined ref for position + interaction
+ tooltip.ref(el);
+
+ // Set aria-describedby, merging with existing
+ const existingDescribedBy = el.getAttribute('aria-describedby');
+ el.setAttribute(
+ 'aria-describedby',
+ mergeIds(existingDescribedBy, tooltip.describedBy) ?? '',
+ );
+
+ return () => {
+ tooltip.ref(null);
+ if (existingDescribedBy) {
+ el.setAttribute('aria-describedby', existingDescribedBy);
+ } else {
+ el.removeAttribute('aria-describedby');
+ }
+ };
+ };
+
const el = anchorRef.current;
- if (!el) {
- return;
+ if (el) {
+ return attach(el);
}
- // Use combined ref for position + interaction
- tooltip.ref(el);
-
- // Set aria-describedby, merging with existing
- const existingDescribedBy = el.getAttribute('aria-describedby');
- el.setAttribute(
- 'aria-describedby',
- mergeIds(existingDescribedBy, tooltip.describedBy) ?? '',
- );
-
- return () => {
- tooltip.ref(null);
- if (existingDescribedBy) {
- el.setAttribute('aria-describedby', existingDescribedBy);
- } else {
- el.removeAttribute('aria-describedby');
+ // React attaches an ancestor's ref after its descendants' layout effects,
+ // so a tooltip rendered inside its own anchor (SideNavItem's collapsed
+ // rail tooltip) still sees null here on mount, and this effect's deps
+ // never change to re-run it. Re-check once the commit has attached all
+ // refs; if the anchor is still gone, this tooltip has no anchor, as before.
+ let detach: (() => void) | undefined;
+ let cancelled = false;
+ queueMicrotask(() => {
+ if (cancelled) {
+ return;
}
+ const el = anchorRef.current;
+ if (el) {
+ detach = attach(el);
+ }
+ });
+ return () => {
+ cancelled = true;
+ detach?.();
};
}, [anchorRef, tooltip.ref, tooltip.describedBy]);