Skip to content

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

TypeScript

fix(useKeyboardHint): focus inside portaled children neither shows nor spends the arrow-key hint (#9362)

Cindy Zhangdd6ac74ea4e7
diff --git a/.changeset/keyboard-hint-portaled-focus.md b/.changeset/keyboard-hint-portaled-focus.md
new file mode 100644
index 0000000000..95f953a23c
--- /dev/null
+++ b/.changeset/keyboard-hint-portaled-focus.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] The arrow-key hint of TabList, Toolbar and SegmentedControl no longer appears, or gets used up, when focus lands in content a tab or toolbar button opens through a portal, such as a sheet, dialog or popover. It still shows the first time keyboard focus enters the row itself.
+
+@duytbp
diff --git a/packages/core/src/hooks/useKeyboardHint.test.tsx b/packages/core/src/hooks/useKeyboardHint.test.tsx
index 5ae0a6cc9a..4789c93f4c 100644
--- a/packages/core/src/hooks/useKeyboardHint.test.tsx
+++ b/packages/core/src/hooks/useKeyboardHint.test.tsx
@@ -6,8 +6,9 @@
* @output Unit tests for keyboard hint rendering
*/
-import {render} from '@testing-library/react';
-import {describe, expect, it} from 'vitest';
+import {fireEvent, render, screen} from '@testing-library/react';
+import {createPortal} from 'react-dom';
+import {afterEach, describe, expect, it, vi} from 'vitest';
import {useKeyboardHint, type KeyboardHintOrientation} from './useKeyboardHint';
import {InternationalizationProvider} from '../i18n';
@@ -90,3 +91,47 @@ describe('useKeyboardHint', () => {
expect(hint.textContent).not.toContain('to navigate');
});
});
+
+// component:Toolbar FR6: the hint follows keyboard focus entering the row.
+describe('useKeyboardHint focus inside portaled children', () => {
+ const originalShowPopover = HTMLElement.prototype.showPopover;
+
+ afterEach(() => {
+ vi.restoreAllMocks();
+ HTMLElement.prototype.showPopover = originalShowPopover;
+ });
+
+ function Row() {
+ const {hintElement, onFocus, onBlur} = useKeyboardHint({});
+ return (
+ <div onFocus={onFocus} onBlur={onBlur}>
+ <button type="button">First</button>
+ {createPortal(<input aria-label="Sheet field" />, document.body)}
+ {hintElement}
+ </div>
+ );
+ }
+
+ it('neither shows nor spends the hint for focus in a portaled child', () => {
+ // jsdom has neither :focus-visible for synthetic focus nor the Popover API.
+ const matches = HTMLElement.prototype.matches;
+ vi.spyOn(HTMLElement.prototype, 'matches').mockImplementation(function (
+ this: HTMLElement,
+ selector: string,
+ ) {
+ return selector === ':focus-visible'
+ ? true
+ : matches.call(this, selector);
+ });
+ const showPopover = vi.fn();
+ HTMLElement.prototype.showPopover = showPopover;
+ render(<Row />);
+
+ fireEvent.focus(screen.getByRole('textbox', {name: 'Sheet field'}));
+ expect(showPopover).not.toHaveBeenCalled();
+
+ // The one-time hint is still there for the row itself.
+ fireEvent.focus(screen.getByRole('button', {name: 'First'}));
+ expect(showPopover).toHaveBeenCalledTimes(1);
+ });
+});
diff --git a/packages/core/src/hooks/useKeyboardHint.tsx b/packages/core/src/hooks/useKeyboardHint.tsx
index 035491251e..ac83cfaf5e 100644
--- a/packages/core/src/hooks/useKeyboardHint.tsx
+++ b/packages/core/src/hooks/useKeyboardHint.tsx
@@ -259,8 +259,14 @@ export function useKeyboardHint(
if (!target.matches(':focus-visible')) {
return;
}
- // Only show when focus enters from outside the container
const container = e.currentTarget as HTMLElement;
+ // React bubbles focus from portaled children (a sheet or popover opened
+ // from the row) to the container; that focus is not in the row, where
+ // the arrow keys work, so it neither shows nor spends the hint.
+ if (!container.contains(target)) {
+ return;
+ }
+ // Only show when focus enters from outside the container
if (
e.relatedTarget instanceof Node &&
container.contains(e.relatedTarget)