Skip to content

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

TypeScript

feat(menu): remove hasAutoFocus, always focus first item on open (APG) (#3438)

Cindy Zhange0724f37adc5
diff --git a/.changeset/menu-always-autofocus.md b/.changeset/menu-always-autofocus.md
new file mode 100644
index 0000000000..04fcf91f4b
--- /dev/null
+++ b/.changeset/menu-always-autofocus.md
@@ -0,0 +1,6 @@
+---
+'@astryxdesign/core': patch
+---
+
+[breaking] DropdownMenu, ContextMenu, MoreMenu: removed the `hasAutoFocus` prop. Menus now always focus their first item on open (the correct APG menu-button behavior). Previously `hasAutoFocus={false}` left the menu keyboard-unreachable and undismissable — the prop existed only as an escape hatch for documentation previews, which no longer need it.
+@cixzhang
diff --git a/packages/cli/templates/blocks/components/DropdownMenu/DropdownMenuShowcase.tsx b/packages/cli/templates/blocks/components/DropdownMenu/DropdownMenuShowcase.tsx
index 5b91eee1a3..495e1aed5c 100644
--- a/packages/cli/templates/blocks/components/DropdownMenu/DropdownMenuShowcase.tsx
+++ b/packages/cli/templates/blocks/components/DropdownMenu/DropdownMenuShowcase.tsx
@@ -12,7 +12,6 @@ export default function DropdownMenuShowcase() {
<DropdownMenu
isMenuOpen={isMenuOpen}
onOpenChange={setIsMenuOpen}
- hasAutoFocus={false}
button={{label: 'Actions'}}
items={[
{label: 'Edit', onClick: () => {}},
diff --git a/packages/cli/templates/blocks/components/DropdownMenuItem/DropdownMenuItemShowcase.tsx b/packages/cli/templates/blocks/components/DropdownMenuItem/DropdownMenuItemShowcase.tsx
index bb862e7b68..f7b74dc490 100644
--- a/packages/cli/templates/blocks/components/DropdownMenuItem/DropdownMenuItemShowcase.tsx
+++ b/packages/cli/templates/blocks/components/DropdownMenuItem/DropdownMenuItemShowcase.tsx
@@ -68,7 +68,6 @@ export default function DropdownMenuItemShowcase() {
<DropdownMenu
button={{label: 'Actions'}}
isMenuOpen
- hasAutoFocus={false}
onOpenChange={() => {}}>
<DropdownMenuItem
icon={PencilIcon}
diff --git a/packages/cli/templates/blocks/components/MoreMenu/MoreMenuShowcase.tsx b/packages/cli/templates/blocks/components/MoreMenu/MoreMenuShowcase.tsx
index a8b01295f1..ddce624920 100644
--- a/packages/cli/templates/blocks/components/MoreMenu/MoreMenuShowcase.tsx
+++ b/packages/cli/templates/blocks/components/MoreMenu/MoreMenuShowcase.tsx
@@ -12,7 +12,6 @@ export default function MoreMenuShowcase() {
<MoreMenu
isMenuOpen={isMenuOpen}
onOpenChange={setIsMenuOpen}
- hasAutoFocus={false}
items={[
{label: 'Edit', onClick: () => {}},
{label: 'Duplicate', onClick: () => {}},
diff --git a/packages/cli/templates/pages/shell-side-nav/page.tsx b/packages/cli/templates/pages/shell-side-nav/page.tsx
index cc7574a096..fee51d921d 100644
--- a/packages/cli/templates/pages/shell-side-nav/page.tsx
+++ b/packages/cli/templates/pages/shell-side-nav/page.tsx
@@ -142,7 +142,6 @@ function ConversationItem({
<MoreMenu
size="sm"
label="Conversation options"
- hasAutoFocus={false}
onOpenChange={setIsMenuOpen}
items={[
{label: 'Pin', onClick: () => {}},
diff --git a/packages/core/src/ContextMenu/ContextMenu.doc.mjs b/packages/core/src/ContextMenu/ContextMenu.doc.mjs
index 52d10cf7df..022d030676 100644
--- a/packages/core/src/ContextMenu/ContextMenu.doc.mjs
+++ b/packages/core/src/ContextMenu/ContextMenu.doc.mjs
@@ -58,12 +58,6 @@ export const docs = {
description: 'Accessible name for the menu surface, announced when it opens.',
default: "'Context menu'",
},
- {
- name: 'hasAutoFocus',
- type: 'boolean',
- description: 'Whether to auto-focus the first menu item when the menu opens. Set to false for inline showcases.',
- default: 'true',
- },
{
name: 'isDisabled',
type: 'boolean',
diff --git a/packages/core/src/ContextMenu/ContextMenu.test.tsx b/packages/core/src/ContextMenu/ContextMenu.test.tsx
index 2e91d488ff..6f755c856a 100644
--- a/packages/core/src/ContextMenu/ContextMenu.test.tsx
+++ b/packages/core/src/ContextMenu/ContextMenu.test.tsx
@@ -62,9 +62,7 @@ describe('ContextMenu', () => {
it('typeahead focuses the matching menu item (menus-11)', () => {
render(
- <ContextMenu
- items={[{label: 'Cut'}, {label: 'Copy'}, {label: 'Paste'}]}
- hasAutoFocus={false}>
+ <ContextMenu items={[{label: 'Cut'}, {label: 'Copy'}, {label: 'Paste'}]}>
<div>Right-click me</div>
</ContextMenu>,
);
@@ -121,7 +119,7 @@ describe('ContextMenu', () => {
it('closes on Escape even when opened without auto-focus', () => {
render(
- <ContextMenu items={[{label: 'Item 1'}]} hasAutoFocus={false}>
+ <ContextMenu items={[{label: 'Item 1'}]}>
<div>Right-click me</div>
</ContextMenu>,
);
@@ -135,7 +133,7 @@ describe('ContextMenu', () => {
it('ignores Escape during IME composition', () => {
render(
- <ContextMenu items={[{label: 'Item 1'}]} hasAutoFocus={false}>
+ <ContextMenu items={[{label: 'Item 1'}]}>
<div>Right-click me</div>
</ContextMenu>,
);
@@ -147,7 +145,7 @@ describe('ContextMenu', () => {
it('restores focus to the trigger on close', () => {
render(
- <ContextMenu items={[{label: 'Item 1'}]} hasAutoFocus={false}>
+ <ContextMenu items={[{label: 'Item 1'}]}>
<button type="button">Right-click me</button>
</ContextMenu>,
);
diff --git a/packages/core/src/ContextMenu/ContextMenu.tsx b/packages/core/src/ContextMenu/ContextMenu.tsx
index 621519fe9b..0d2f9fb33e 100644
--- a/packages/core/src/ContextMenu/ContextMenu.tsx
+++ b/packages/core/src/ContextMenu/ContextMenu.tsx
@@ -125,12 +125,6 @@ interface ContextMenuBaseProps extends BaseProps {
* @default 'Context menu'
*/
label?: string;
- /**
- * Whether to auto-focus the first menu item when the menu opens.
- * Set to `false` for inline showcases or documentation previews.
- * @default true
- */
- hasAutoFocus?: boolean;
/** When true, right-click shows the native browser context menu instead. */
isDisabled?: boolean;
/** Called when the menu opens or closes. */
@@ -184,7 +178,6 @@ export function ContextMenu({
menuWidth,
size = 'md',
label = 'Context menu',
- hasAutoFocus = true,
isDisabled = false,
onOpenChange,
ref,
@@ -282,10 +275,9 @@ export function ContextMenu({
}, [isOpen, closeMenu, listRef]);
// Dismiss on Escape from anywhere while open. The menu div's own onKeyDown
- // only fires when focus is inside the menu, which never happens when the
- // menu is opened with hasAutoFocus={false} (e.g. table context menus), so a
- // document-level listener is required for a reliable Escape path. Guards
- // against IME composition-cancel.
+ // only fires when focus is inside the menu; a document-level listener is
+ // kept as a reliable fallback Escape path (e.g. if focus has moved out of
+ // the menu). Guards against IME composition-cancel.
useEffect(() => {
if (!isOpen) {
return;
@@ -350,11 +342,9 @@ export function ContextMenu({
? document.activeElement
: (e.currentTarget as HTMLElement);
layer.show();
- if (hasAutoFocus) {
- requestAnimationFrame(() => focusFirst());
- }
+ requestAnimationFrame(() => focusFirst());
},
- [isDisabled, layer, hasAutoFocus, focusFirst],
+ [isDisabled, layer, focusFirst],
);
// Touch long-press invocation (menus-8). iOS Safari never synthesizes a
@@ -367,11 +357,9 @@ export function ContextMenu({
(point: {x: number; y: number}) => {
positionRef.current = {x: point.x, y: point.y};
layer.show();
- if (hasAutoFocus) {
- requestAnimationFrame(() => focusFirst());
- }
+ requestAnimationFrame(() => focusFirst());
},
- [layer, hasAutoFocus, focusFirst],
+ [layer, focusFirst],
),
});
diff --git a/packages/core/src/DropdownMenu/DropdownMenu.doc.mjs b/packages/core/src/DropdownMenu/DropdownMenu.doc.mjs
index dab6d01711..5e352157d6 100644
--- a/packages/core/src/DropdownMenu/DropdownMenu.doc.mjs
+++ b/packages/core/src/DropdownMenu/DropdownMenu.doc.mjs
@@ -61,14 +61,7 @@ export const docs = {
type: 'boolean',
description: 'Whether to show a chevron icon on the trigger button. Set to false for icon-only triggers.',
default: 'true',
- },
- {
- name: 'hasAutoFocus',
- type: 'boolean',
- description: 'Whether to auto-focus the first menu item when the menu opens. Set to false for inline showcases or documentation previews.',
- default: 'true',
- },
- {
+ }, {
name: 'children',
type: '(item: DropdownMenuItemData) => ReactNode',
description: 'Custom render function for each item in the list.',
diff --git a/packages/core/src/DropdownMenu/DropdownMenu.test.tsx b/packages/core/src/DropdownMenu/DropdownMenu.test.tsx
index 3f8de54dbf..6029c159fd 100644
--- a/packages/core/src/DropdownMenu/DropdownMenu.test.tsx
+++ b/packages/core/src/DropdownMenu/DropdownMenu.test.tsx
@@ -249,29 +249,6 @@ describe('DropdownMenu controlled mode', () => {
});
});
-describe('DropdownMenu hasAutoFocus', () => {
- it('does not focus menu items when hasAutoFocus is false and isMenuOpen is true', () => {
- const focusSpy = vi.spyOn(HTMLElement.prototype, 'focus');
- render(
- <DropdownMenu
- button={{label: 'Actions'}}
- items={[{label: 'Edit'}, {label: 'Delete'}]}
- isMenuOpen={true}
- hasAutoFocus={false}
- onOpenChange={() => {}}
- />,
- );
-
- const menuItems = screen.getAllByRole('menuitem', {hidden: true});
- const menuItemFocusCalls = focusSpy.mock.calls.filter((_, i) => {
- const ctx = focusSpy.mock.contexts[i];
- return menuItems.includes(ctx as HTMLElement);
- });
- expect(menuItemFocusCalls).toHaveLength(0);
- focusSpy.mockRestore();
- });
-});
-
describe('DropdownMenu items', () => {
it('renders items with labels', () => {
render(
diff --git a/packages/core/src/DropdownMenu/DropdownMenu.tsx b/packages/core/src/DropdownMenu/DropdownMenu.tsx
index 25f9b08b4c..fc9f0e28b3 100644
--- a/packages/core/src/DropdownMenu/DropdownMenu.tsx
+++ b/packages/core/src/DropdownMenu/DropdownMenu.tsx
@@ -135,13 +135,6 @@ interface DropdownMenuBaseProps extends BaseProps {
*/
placement?: LayerPlacement;
- /**
- * Whether to auto-focus the first menu item when the menu opens.
- * Set to `false` for inline showcases or documentation previews
- * where stealing focus is undesirable.
- * @default true
- */
- hasAutoFocus?: boolean;
'data-testid'?: string;
}
@@ -193,7 +186,6 @@ export function DropdownMenu({
onClick,
hasChevron = true,
placement = 'below',
- hasAutoFocus = true,
className,
style,
xstyle,
@@ -299,14 +291,12 @@ export function DropdownMenu({
if (isControlled) {
if (controlledIsOpen && !popover.isOpen) {
popover.show();
- if (hasAutoFocus) {
- requestAnimationFrame(() => focusFirst());
- }
+ requestAnimationFrame(() => focusFirst());
} else if (!controlledIsOpen && popover.isOpen) {
popover.hide();
}
}
- }, [controlledIsOpen, isControlled, popover, hasAutoFocus, focusFirst]);
+ }, [controlledIsOpen, isControlled, popover, focusFirst]);
// Extend useListFocus with Enter/Space activation + typeahead
const listKeyDown = useCallback(
@@ -340,10 +330,8 @@ export function DropdownMenu({
const openAndFocus = useCallback(() => {
popover.show();
- if (hasAutoFocus) {
- requestAnimationFrame(() => focusFirst());
- }
- }, [popover, hasAutoFocus, focusFirst]);
+ requestAnimationFrame(() => focusFirst());
+ }, [popover, focusFirst]);
const handleButtonClick = useCallback(() => {
// If the menu was just closed by light dismiss (e.g. iOS Safari fires
diff --git a/packages/core/src/MoreMenu/MoreMenu.doc.mjs b/packages/core/src/MoreMenu/MoreMenu.doc.mjs
index a36b0a2a15..3925c10c74 100644
--- a/packages/core/src/MoreMenu/MoreMenu.doc.mjs
+++ b/packages/core/src/MoreMenu/MoreMenu.doc.mjs
@@ -46,14 +46,7 @@ export const docs = {
type: 'boolean',
description: 'Whether the menu trigger is disabled.',
default: 'false',
- },
- {
- name: 'hasAutoFocus',
- type: 'boolean',
- description: 'Whether to auto-focus the first menu item when the menu opens. Set to false for inline showcases or documentation previews.',
- default: 'true',
- },
- {
+ }, {
name: 'xstyle',
type: 'StyleXStyles',
description:
@@ -126,14 +119,7 @@ export const docsZh = {
type: 'boolean',
description: '菜单触发器是否禁用。',
default: 'false',
- },
- {
- name: 'hasAutoFocus',
- type: 'boolean',
- description: '菜单打开时是否自动聚焦第一个菜单项。内联展示或文档预览设为 false。',
- default: 'true',
- },
- {
+ }, {
name: 'xstyle',
type: 'StyleXStyles',
description:
@@ -176,7 +162,6 @@ export const docsDense = {
size: 'Trigger button size.',
icon: 'Override default three-dot icon. Accepts any ReactNode.',
isDisabled: 'Whether menu trigger disabled.',
- hasAutoFocus: 'Auto-focus first item on open; false for showcases.',
xstyle:
'StyleX styles for layout customization (margins, positioning, sizing). Must be stylex.create() value.',
},
diff --git a/packages/core/src/MoreMenu/MoreMenu.tsx b/packages/core/src/MoreMenu/MoreMenu.tsx
index f0428e674a..1d50abd976 100644
--- a/packages/core/src/MoreMenu/MoreMenu.tsx
+++ b/packages/core/src/MoreMenu/MoreMenu.tsx
@@ -81,13 +81,6 @@ export interface MoreMenuProps extends Pick<
*/
onOpenChange?: (isOpen: boolean) => void;
- /**
- * Whether to auto-focus the first menu item when the menu opens.
- * Set to `false` for inline showcases or documentation previews.
- * @default true
- */
- hasAutoFocus?: boolean;
-
/** Test ID for testing frameworks. */
'data-testid'?: string;
}
@@ -116,7 +109,6 @@ export function MoreMenu({
isDisabled = false,
isMenuOpen,
onOpenChange,
- hasAutoFocus,
xstyle,
className: classNameProp,
style,
@@ -149,7 +141,6 @@ export function MoreMenu({
}}
items={items}
hasChevron={false}
- hasAutoFocus={hasAutoFocus}
data-testid={testId}
/>
);
diff --git a/packages/core/src/Table/tableContextMenu.tsx b/packages/core/src/Table/tableContextMenu.tsx
index 45f5634866..529c7cafba 100644
--- a/packages/core/src/Table/tableContextMenu.tsx
+++ b/packages/core/src/Table/tableContextMenu.tsx
@@ -107,7 +107,6 @@ function LazyTableContextMenu({
return (
<ContextMenu
items={options ?? []}
- hasAutoFocus={false}
onOpenChange={open => {
// Resolve actions when opening; clear on close so state derived later
// (e.g. current sort direction) is always fresh next open.
@@ -135,12 +134,9 @@ export function wrapInTableContextMenu(
if (!actions || actions.length === 0) {
return element;
}
- // hasAutoFocus={false}: a right-click menu shouldn't pre-highlight the first
// item (it looked like "ascending" was always selected). Focus moves only
// when the user arrow-keys into the menu.
return (
- <ContextMenu items={toContextMenuOptions(actions)} hasAutoFocus={false}>
- {element}
- </ContextMenu>
+ <ContextMenu items={toContextMenuOptions(actions)}>{element}</ContextMenu>
);
}