Skip to content

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

TypeScript

DropdownMenuItem, CheckboxItem, RadioItem: forward a ref to the row root (agentcloud gap kt-d4wr) (#6687)

Christopher Chedeau0641893d0d47
diff --git a/.changeset/dropdown-menu-item-ref.md b/.changeset/dropdown-menu-item-ref.md
new file mode 100644
index 0000000000..5f599b980a
--- /dev/null
+++ b/.changeset/dropdown-menu-item-ref.md
@@ -0,0 +1,13 @@
+---
+'@astryxdesign/core': patch
+---
+
+[feat] `DropdownMenuItem`, `DropdownMenuCheckboxItem` and `DropdownMenuRadioItem` forward a `ref` to the row root.
+
+The ref reaches the element carrying `role="menuitem"` (or `menuitemcheckbox`
+/ `menuitemradio`), the way `Item` and `DropdownMenuDivider` already forward
+one, so a menu row can be registered with an element-keyed observer or
+overlay — an IntersectionObserver for an impression, a measurement, a debug
+outline — without a wrapper between `role="menu"` and the row.
+
+@vjeux
diff --git a/packages/core/src/DropdownMenu/DropdownMenu.test.tsx b/packages/core/src/DropdownMenu/DropdownMenu.test.tsx
index 73ab3d60f4..64bffcacc4 100644
--- a/packages/core/src/DropdownMenu/DropdownMenu.test.tsx
+++ b/packages/core/src/DropdownMenu/DropdownMenu.test.tsx
@@ -1361,6 +1361,34 @@ describe('DropdownMenu sections', () => {
});
});
+describe('DropdownMenuItem ref', () => {
+ it('a ref reaches the menuitem element', () => {
+ const ref = vi.fn();
+ render(
+ <DropdownMenu button={{label: 'Actions'}}>
+ <DropdownMenuItem label="Edit" onClick={() => {}} ref={ref} />
+ </DropdownMenu>,
+ );
+ const row = screen.getByRole('menuitem', {name: 'Edit', hidden: true});
+ expect(ref).toHaveBeenCalledWith(row);
+ // The row root, not a child of it: what the ref sees is the element the
+ // menu's roving focus and role structure are built on.
+ expect(ref.mock.calls[0][0]).toBe(row);
+ });
+
+ it('a ref object holds the menuitem element', () => {
+ const ref = {current: null as HTMLElement | null};
+ render(
+ <DropdownMenu button={{label: 'Actions'}}>
+ <DropdownMenuItem label="Edit" onClick={() => {}} ref={ref} />
+ </DropdownMenu>,
+ );
+ expect(ref.current).toBe(
+ screen.getByRole('menuitem', {name: 'Edit', hidden: true}),
+ );
+ });
+});
+
describe('DropdownMenu dividers', () => {
it('renders dividers between items', () => {
render(
diff --git a/packages/core/src/DropdownMenu/DropdownMenuCheckboxItem.doc.mjs b/packages/core/src/DropdownMenu/DropdownMenuCheckboxItem.doc.mjs
index 354b251434..b0d389588f 100644
--- a/packages/core/src/DropdownMenu/DropdownMenuCheckboxItem.doc.mjs
+++ b/packages/core/src/DropdownMenu/DropdownMenuCheckboxItem.doc.mjs
@@ -50,6 +50,12 @@ export const docs = {
description:
'Whether toggling the item closes the menu. Checkbox items default to staying open so several can be toggled in a single session.',
},
+ {
+ name: 'ref',
+ type: 'React.Ref<HTMLElement>',
+ description:
+ 'Ref forwarded to the row root, the element carrying role="menuitemcheckbox". Register the row with an element-keyed observer or overlay.',
+ },
{
name: 'endContent',
type: 'ReactNode',
@@ -73,6 +79,7 @@ export const docsZh = {
onChange: '切换该项时以下一个勾选状态触发的回调。',
isDisabled: '该项是否禁用。',
hasCloseOnSelect: '切换该项是否关闭菜单。默认保持打开。',
+ ref: '转发到行根元素(带 role="menuitemcheckbox" 的元素)的 ref。',
endContent: '在标签和描述之后渲染的内容。',
},
};
@@ -90,6 +97,7 @@ export const docsDense = {
onChange: 'fired w/ next checked state on toggle',
isDisabled: 'disabled; stays focusable via aria-disabled',
hasCloseOnSelect: 'close menu on toggle (default false, stays open)',
+ ref: 'forwarded to the row root (the role="menuitemcheckbox" element)',
endContent: 'content after label+description',
},
};
diff --git a/packages/core/src/DropdownMenu/DropdownMenuCheckboxItem.tsx b/packages/core/src/DropdownMenu/DropdownMenuCheckboxItem.tsx
index 9292b2a8fc..aa6793adf5 100644
--- a/packages/core/src/DropdownMenu/DropdownMenuCheckboxItem.tsx
+++ b/packages/core/src/DropdownMenu/DropdownMenuCheckboxItem.tsx
@@ -118,6 +118,8 @@ export interface DropdownMenuCheckboxItemProps extends Omit<
* @default false
*/
hasCloseOnSelect?: boolean;
+ /** Ref forwarded to the row root — the element carrying `role="menuitemcheckbox"`. */
+ ref?: React.Ref<HTMLElement>;
/**
* Content to render after the label and description, such as a keyboard
* shortcut hint or badge.
diff --git a/packages/core/src/DropdownMenu/DropdownMenuItem.doc.mjs b/packages/core/src/DropdownMenu/DropdownMenuItem.doc.mjs
index b039864a8d..d956e01eee 100644
--- a/packages/core/src/DropdownMenu/DropdownMenuItem.doc.mjs
+++ b/packages/core/src/DropdownMenu/DropdownMenuItem.doc.mjs
@@ -58,6 +58,12 @@ export const docs = {
description:
'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value: not an inline style object like style={{}}.',
},
+ {
+ name: 'ref',
+ type: 'React.Ref<HTMLElement>',
+ description:
+ 'Ref forwarded to the row root, the element carrying role="menuitem". Register the row with an element-keyed observer or overlay.',
+ },
],
};
@@ -105,6 +111,11 @@ export const docsZh = {
type: 'StyleXStyles',
description: '根容器的 StyleX 样式。',
},
+ {
+ name: 'ref',
+ type: 'React.Ref<HTMLElement>',
+ description: '转发到行根元素(带 role="menuitem" 的元素)的 ref。',
+ },
],
};
@@ -123,5 +134,6 @@ export const docsDense = {
variant:
"'destructive' renders the item in the error color for dangerous actions",
xstyle: 'StyleX styles for root container',
+ ref: 'forwarded to the row root (the role="menuitem" element)',
},
};
diff --git a/packages/core/src/DropdownMenu/DropdownMenuItem.tsx b/packages/core/src/DropdownMenu/DropdownMenuItem.tsx
index 3fad1b4afb..e73677295a 100644
--- a/packages/core/src/DropdownMenu/DropdownMenuItem.tsx
+++ b/packages/core/src/DropdownMenu/DropdownMenuItem.tsx
@@ -118,6 +118,13 @@ export interface DropdownMenuItemProps extends Pick<
* the error color for dangerous actions (e.g. Delete). @default 'default'
*/
variant?: 'default' | 'destructive';
+ /**
+ * Ref forwarded to the row root — the element carrying `role="menuitem"`.
+ * Lets a caller register the row with an element-keyed observer (an
+ * IntersectionObserver for an impression, a measurement, a debug overlay)
+ * the way `Item` and `DropdownMenuDivider` already allow.
+ */
+ ref?: React.Ref<HTMLElement>;
}
/**
@@ -146,6 +153,7 @@ export function DropdownMenuItem({
xstyle,
className,
style,
+ ref,
}: DropdownMenuItemProps) {
const ctx = useDropdownMenuContext();
const menuSize = ctx?.menuSize ?? 'md';
@@ -169,6 +177,7 @@ export function DropdownMenuItem({
return (
<Item
+ ref={ref}
role="menuitem"
tabIndex={isDisabled ? undefined : -1}
onPointerMove={handlePointerMove}
diff --git a/packages/core/src/DropdownMenu/DropdownMenuRadioItem.doc.mjs b/packages/core/src/DropdownMenu/DropdownMenuRadioItem.doc.mjs
index c3bb9251e9..d663848762 100644
--- a/packages/core/src/DropdownMenu/DropdownMenuRadioItem.doc.mjs
+++ b/packages/core/src/DropdownMenu/DropdownMenuRadioItem.doc.mjs
@@ -58,6 +58,12 @@ export const docs = {
description:
'Content to render after the label and description, such as a badge or metadata.',
},
+ {
+ name: 'ref',
+ type: 'React.Ref<HTMLElement>',
+ description:
+ 'Ref forwarded to the row root, the element carrying role="menuitemradio". Register the row with an element-keyed observer or overlay.',
+ },
],
};
@@ -74,6 +80,7 @@ export const docsZh = {
icon: '显示在标签前的图标。',
isDisabled: '该单选项是否禁用。',
endContent: '在标签和描述之后渲染的内容。',
+ ref: '转发到行根元素(带 role="menuitemradio" 的元素)的 ref。',
},
};
@@ -89,5 +96,6 @@ export const docsDense = {
icon: 'icon before label',
isDisabled: 'disabled; stays focusable via aria-disabled',
endContent: 'content after label+description',
+ ref: 'forwarded to the row root (the role="menuitemradio" element)',
},
};
diff --git a/packages/core/src/DropdownMenu/DropdownMenuRadioItem.tsx b/packages/core/src/DropdownMenu/DropdownMenuRadioItem.tsx
index 68c94c1573..8e6c2dad1a 100644
--- a/packages/core/src/DropdownMenu/DropdownMenuRadioItem.tsx
+++ b/packages/core/src/DropdownMenu/DropdownMenuRadioItem.tsx
@@ -108,6 +108,8 @@ export interface DropdownMenuRadioItemProps extends Omit<
* metadata.
*/
endContent?: ReactNode;
+ /** Ref forwarded to the row root — the element carrying `role="menuitemradio"`. */
+ ref?: React.Ref<HTMLElement>;
}
/**
diff --git a/packages/core/src/DropdownMenu/DropdownMenuSelectable.test.tsx b/packages/core/src/DropdownMenu/DropdownMenuSelectable.test.tsx
index 56b01167f2..5c0369084f 100644
--- a/packages/core/src/DropdownMenu/DropdownMenuSelectable.test.tsx
+++ b/packages/core/src/DropdownMenu/DropdownMenuSelectable.test.tsx
@@ -193,3 +193,43 @@ describe('DropdownMenuRadioGroup / RadioItem', () => {
spy.mockRestore();
});
});
+
+describe('selectable item refs', () => {
+ it('a ref reaches the menuitemcheckbox element', () => {
+ const ref = vi.fn();
+ render(
+ <DropdownMenu button={{label: 'View'}}>
+ <DropdownMenuCheckboxItem
+ label="Show archived"
+ value={false}
+ onChange={() => {}}
+ ref={ref}
+ />
+ </DropdownMenu>,
+ );
+ expect(ref).toHaveBeenCalledWith(
+ screen.getByRole('menuitemcheckbox', {
+ name: 'Show archived',
+ hidden: true,
+ }),
+ );
+ });
+
+ it('a ref reaches the menuitemradio element', () => {
+ const ref = vi.fn();
+ render(
+ <DropdownMenu button={{label: 'Sort'}}>
+ <DropdownMenuRadioGroup
+ label="Sort by"
+ value="newest"
+ onChange={() => {}}>
+ <DropdownMenuRadioItem value="newest" label="Newest" ref={ref} />
+ <DropdownMenuRadioItem value="oldest" label="Oldest" />
+ </DropdownMenuRadioGroup>
+ </DropdownMenu>,
+ );
+ expect(ref).toHaveBeenCalledWith(
+ screen.getByRole('menuitemradio', {name: 'Newest', hidden: true}),
+ );
+ });
+});