Skip to content

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

TypeScript

[Component Audit] DropdownMenuCheckboxItem: keep consumer handlers observable (#7573)

Cindy Zhang21fa6032b5d4
diff --git a/.changeset/dropdown-menu-checkbox-item-handlers.md b/.changeset/dropdown-menu-checkbox-item-handlers.md
new file mode 100644
index 0000000000..413260e010
--- /dev/null
+++ b/.changeset/dropdown-menu-checkbox-item-handlers.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] `DropdownMenuCheckboxItem` now preserves consumer click and pointer-move handlers while keeping its checked-state, disabled, hover-focus, and close-menu behavior.
+
+@cixzhang
diff --git a/apps/storybook/rtl-audit/targets.json b/apps/storybook/rtl-audit/targets.json
index 8e9166c5e6..3c3ef80e9a 100644
--- a/apps/storybook/rtl-audit/targets.json
+++ b/apps/storybook/rtl-audit/targets.json
@@ -220,6 +220,15 @@
"next": "[data-testid=\"context-menu-item-end-content\"]"
}
},
+ {
+ "component": "DropdownMenuCheckboxItem",
+ "storyId": "core-dropdownmenu--lab-checkbox-items",
+ "dims": ["D2"],
+ "selectors": {
+ "prev": ".astryx-dropdown-menu-item .astryx-icon",
+ "next": "[data-testid=\"dropdown-menu-checkbox-item-end-content\"]"
+ }
+ },
{
"component": "DropdownMenu",
"storyId": "core-dropdownmenu--alignment-end",
diff --git a/apps/storybook/stories/DropdownMenu.stories.tsx b/apps/storybook/stories/DropdownMenu.stories.tsx
index a4f32bb2d7..5126f0a85a 100644
--- a/apps/storybook/stories/DropdownMenu.stories.tsx
+++ b/apps/storybook/stories/DropdownMenu.stories.tsx
@@ -791,6 +791,7 @@ export const LabCheckboxItems: Story = {
render: function LabCheckboxItemsStory() {
const [showArchived, setShowArchived] = useState(false);
const [showDrafts, setShowDrafts] = useState(true);
+ const [syncFolders, setSyncFolders] = useState(true);
return (
<DropdownMenu button={{label: 'View'}}>
<DropdownMenuCheckboxItem
@@ -804,9 +805,32 @@ export const LabCheckboxItems: Story = {
value={showDrafts}
onChange={setShowDrafts}
/>
+ <DropdownMenuCheckboxItem
+ label="Sync folders"
+ icon={ArchiveBoxIcon}
+ endContent={
+ <span data-testid="dropdown-menu-checkbox-item-end-content">
+ <Badge label="Beta" />
+ </span>
+ }
+ value={syncFolders}
+ onChange={setSyncFolders}
+ />
+ <DropdownMenuCheckboxItem
+ label="Managed by your organization"
+ value={true}
+ isDisabled
+ />
</DropdownMenu>
);
},
+ tags: ['visual-theme-matrix'],
+ play: async ({canvasElement}) => {
+ const trigger = canvasElement.querySelector('button');
+ if (trigger instanceof HTMLElement) {
+ trigger.click();
+ }
+ },
parameters: {
docs: {
description: {
diff --git a/packages/core/src/DropdownMenu/DropdownMenu.spec.md b/packages/core/src/DropdownMenu/DropdownMenu.spec.md
index 2355e3db18..b44b795958 100644
--- a/packages/core/src/DropdownMenu/DropdownMenu.spec.md
+++ b/packages/core/src/DropdownMenu/DropdownMenu.spec.md
@@ -117,6 +117,8 @@ keeps its released default.
| FR13 | On a mouse, a nested flyout stays open while the pointer is inside the triangle from where it left its row to the flyout's near edge — including while the pointer is paused there — and closes after the existing delay once the pointer has left both the row and that triangle. The row's click toggle and its guard window are unchanged. | Proposed in this change; `DropdownMenuSubMenu.test.tsx` safe-triangle suite, `useMenuHover.test.tsx` | Proposed; verified in jsdom, pending owner review |
| FR14 | A compound `DropdownMenuGroup` is one `role="group"` named by its heading through `aria-labelledby`; the heading carries `dropdown-menu-section-heading`, is plain text rather than a menu item, and is skipped by roving focus and typeahead. An untitled group is an unnamed `role="group"`. | DEC-1, docs, and tests | Proposed; awaiting owner approval |
| FR15 | With `header` or `footer`, the pointer popover is a `role="dialog"` with `aria-modal="true"`, named like the menu, holding the header, then the `role="menu"` element, then the footer; the menu element holds only its rows. The trigger says `aria-haspopup="dialog"` and its `aria-controls` names the popover that holds the dialog. A region keeps its own keys and presses: neither the menu's key handling nor its press model claims an event that begins there. The menu is one Tab stop between the regions. Tab and Shift+Tab move through the header's controls, the menu, then the footer's controls, and wrap at either end; a control that is hidden, or under a hidden ancestor within its region, is not a stop. From a row, or a row of an open sub-menu, Tab and Shift+Tab close every open flyout and continue from the menu's stop. With no other stop, focus stays in the menu. Escape closes from anywhere in the popover, and focus returns to the trigger. The bottom sheet, already a dialog, shows the header above the actions and the footer below them. Without either prop, the menu renders and behaves exactly as it does without them: no dialog, `aria-haspopup="menu"`, and Tab closes the menu. | DEC-8, DEC-10, docs, and tests | Proposed; awaiting owner approval |
+| FR16 | `DropdownMenuCheckboxItem` MUST expose one `menuitemcheckbox` row whose `aria-checked` equals its controlled value; enabled activation reports `!value`, stays open by default, and composes consumer click and pointer-move handlers with owned activation and hover focus. Disabled activation calls no consumer activation handler. | Released subcomponent API; `architecture:public-component-api/INV5–INV8`; `DropdownMenuSelectable.test.tsx` | Verified current behavior; consumer handlers are preserved |
+| FR17 | Disabled menu rows SHOULD remain keyboard-discoverable while activation stays blocked. Current shared `useListFocus` deliberately skips every `aria-disabled` row, including checkbox items. | WAI-ARIA Menu pattern; current shared navigation source/tests | Objective mismatch; shared mechanism remains undecided in OQ1 |
### Allowed variation
@@ -199,6 +201,13 @@ visibility helper.
`aria-controls` names the popover that holds the dialog rather than the
menu, as Popover's own trigger does.
+- **AR6 — Checkbox rows remain one control.** The row owns
+ `menuitemcheckbox`, its accessible name, checked state, focus, and activation;
+ Indicator's checkbox marker is decorative. Disabled activation is inert.
+ Current shared navigation skips disabled rows instead of making them
+ discoverable as the WAI-ARIA Menu pattern recommends; FR17 and OQ1 retain that
+ gap without inventing a component-local focus path.
+
## Design relationships
| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
@@ -296,23 +305,25 @@ than adding a DropdownMenu-owned heading target.
## Verification map
-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
-| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
-| FR1, FR4 | `DropdownMenu.test.tsx` pointer, bottom-sheet, adaptive, section, divider, and drill-in suites | Root pointer, nested pointer, root touch, drill-in | Collapsing presentation-specific parts or owners fails structure, target, or role assertions. | `audit:DropdownMenu/anatomy` |
-| FR2 | DropdownMenu target suites, source inspection, and theming target inventories | All six local targets | Removing, renaming, or assigning a current target to the wrong part fails evidence or inventory. | `audit:DropdownMenu/theming` |
-| FR3 | `DropdownMenuSelectable.test.tsx` plus BottomSheet, List, Indicator, Icon, and Divider owner tests | Trigger, touch actions, icons, checkbox, radio | A composed part loses its owner target or is documented as a new local target. | `audit:DropdownMenu/theming` |
-| Layer relationships | `DropdownMenu.test.tsx`, `DropdownMenuSubMenu.test.tsx`, and current layer/dismissal architecture records | Light dismiss, nested flyout, sheet dismissal | Documentation claims a shared owner where current source retains local behavior, or the reverse. | `audit:DropdownMenu/behavior` |
-| FR5 | `DropdownMenu.test.tsx` press model suite; the module record's own map | Finger slide across rows, outside release by mouse and finger, `touch-action`, root marker | A row acting on the press or the stray click, a lost `touch-action`, or a finger release that closes fails. | `audit:DropdownMenu/behavior` |
-| FR6 | `DropdownMenu.test.tsx` dismissal, closing and press model suites; `__tests__/MenuPress.a11y.chromium.spec.ts` in real Chromium | keyboard/pointer dismissal, Escape after press-open, press outside on a control, pointer pick, closed menu | Focus left on the body after a pointer pick, on the control focused before a press-open, or a ring after pointer input, fails. | `audit:DropdownMenu/behavior` |
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
+| FR1, FR4 | `DropdownMenu.test.tsx` pointer, bottom-sheet, adaptive, section, divider, and drill-in suites | Root pointer, nested pointer, root touch, drill-in | Collapsing presentation-specific parts or owners fails structure, target, or role assertions. | `audit:DropdownMenu/anatomy` |
+| FR2 | DropdownMenu target suites, source inspection, and theming target inventories | All six local targets | Removing, renaming, or assigning a current target to the wrong part fails evidence or inventory. | `audit:DropdownMenu/theming` |
+| FR3 | `DropdownMenuSelectable.test.tsx` plus BottomSheet, List, Indicator, Icon, and Divider owner tests | Trigger, touch actions, icons, checkbox, radio | A composed part loses its owner target or is documented as a new local target. | `audit:DropdownMenu/theming` |
+| Layer relationships | `DropdownMenu.test.tsx`, `DropdownMenuSubMenu.test.tsx`, and current layer/dismissal architecture records | Light dismiss, nested flyout, sheet dismissal | Documentation claims a shared owner where current source retains local behavior, or the reverse. | `audit:DropdownMenu/behavior` |
+| FR5 | `DropdownMenu.test.tsx` press model suite; the module record's own map | Finger slide across rows, outside release by mouse and finger, `touch-action`, root marker | A row acting on the press or the stray click, a lost `touch-action`, or a finger release that closes fails. | `audit:DropdownMenu/behavior` |
+| FR6 | `DropdownMenu.test.tsx` dismissal, closing and press model suites; `__tests__/MenuPress.a11y.chromium.spec.ts` in real Chromium | keyboard/pointer dismissal, Escape after press-open, press outside on a control, pointer pick, closed menu | Focus left on the body after a pointer pick, on the control focused before a press-open, or a ring after pointer input, fails. | `audit:DropdownMenu/behavior` |
| FR7 | `menuMaxHeight` MUST replace the 300px term of the menu's and its popover viewport's block-size cap while the viewport gutters still bound both; the touch sheet ignores it. | `component:DropdownMenu/DEC-3` | Proposed; verified in jsdom; owner to confirm DEC-3 |
-| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and current target inventory | Missing, extra, prefixed, stale, or unclassified mappings fail repository validation. | `audit:DropdownMenu/theming` |
-| FR8 | `DropdownMenu.test.tsx` press model suite (trigger cases) | Press-open + drag-release, unsettled opening release, trigger toggle, held touch, tap | A menu that does not open on a mouse press, an unsettled release that acts, or a trigger that reopens in the same gesture fails. | `audit:DropdownMenu/behavior` |
-| FR9 | `DropdownMenu.test.tsx` custom trigger suite; `DropdownMenuSubMenu.test.tsx` custom-trigger Back row cases | Icon button, chip, list row; open, toggle, keyboard open, name; drill-in Back row | A rendered control missing `aria-haspopup`, `aria-expanded` or `aria-controls`, an unnamed menu, a lost keyboard open, or a "Back to Menu" row, fails. | `audit:DropdownMenu/anatomy` |
-| AR4 | `DropdownMenu.test.tsx` cases "has aria-haspopup and aria-expanded attributes", "keyboard open via Enter focuses the first enabled item", "walks into a mounted-open menu with ArrowDown from the focused trigger", "keyboard open via ArrowDown skips a disabled leading item", "ArrowUp on the trigger opens with the last row highlighted", and "a custom trigger opens from the keyboard and lands on the first row"; Space opening and `aria-controls` under the Menu Button accessibility contract (`internal/a11y-spec`, pending) bound to the anchored trigger | Button and `renderTrigger` controls; closed/open; Enter, Space, ArrowDown, ArrowUp open | The trigger loses its name, `aria-haspopup="menu"`, `aria-expanded` or `aria-controls`; a keyboard open lands focus somewhere other than the first (or, for ArrowUp, last) enabled row | `audit:DropdownMenu/accessibility` |
-| FR8, AR2 | `DropdownMenu.test.tsx` "DropdownMenuItem href" suite (pointer menu and bottom sheet) | Plain click, ⌘-click, Enter with modifiers, disabled link row | A row rendering an inner anchor, running `onClick` on a modified click, or a synthesized click dropping the modifiers fails. | `audit:DropdownMenu/behavior` |
-| FR12, AR3 | `DropdownMenuSubMenu.test.tsx` "drill-in on a phone" suite; `__tests__/DropdownMenuDrillIn.a11y.chromium.spec.ts` (real Chromium, coarse pointer) | Drill in, Back, Escape, ArrowLeft, nested level, scoped typeahead, forced presentations, close resets | A flyout opening on a coarse pointer, a missing Back row, sibling rows staying in the order, or focus not returning to the row fails. | `audit:DropdownMenu/behavior` |
-| FR10 | `DropdownMenuSubMenu.test.tsx` safe-triangle suite; `useMenuHover.test.tsx` `isPointInSafeTriangle` and click-guard suites | diagonal path toward the flyout, a pause inside it, path away, click-opened and hover-opened guard windows | A flyout that closes while the pointer is inside the triangle or paused in it, one that never closes after leaving it, or a changed guard-window rule, fails. | `audit:DropdownMenu/behavior` |
+| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and current target inventory | Missing, extra, prefixed, stale, or unclassified mappings fail repository validation. | `audit:DropdownMenu/theming` |
+| FR8 | `DropdownMenu.test.tsx` press model suite (trigger cases) | Press-open + drag-release, unsettled opening release, trigger toggle, held touch, tap | A menu that does not open on a mouse press, an unsettled release that acts, or a trigger that reopens in the same gesture fails. | `audit:DropdownMenu/behavior` |
+| FR9 | `DropdownMenu.test.tsx` custom trigger suite; `DropdownMenuSubMenu.test.tsx` custom-trigger Back row cases | Icon button, chip, list row; open, toggle, keyboard open, name; drill-in Back row | A rendered control missing `aria-haspopup`, `aria-expanded` or `aria-controls`, an unnamed menu, a lost keyboard open, or a "Back to Menu" row, fails. | `audit:DropdownMenu/anatomy` |
+| AR4 | `DropdownMenu.test.tsx` cases "has aria-haspopup and aria-expanded attributes", "keyboard open via Enter focuses the first enabled item", "walks into a mounted-open menu with ArrowDown from the focused trigger", "keyboard open via ArrowDown skips a disabled leading item", "ArrowUp on the trigger opens with the last row highlighted", and "a custom trigger opens from the keyboard and lands on the first row"; Space opening and `aria-controls` under the Menu Button accessibility contract (`internal/a11y-spec`, pending) bound to the anchored trigger | Button and `renderTrigger` controls; closed/open; Enter, Space, ArrowDown, ArrowUp open | The trigger loses its name, `aria-haspopup="menu"`, `aria-expanded` or `aria-controls`; a keyboard open lands focus somewhere other than the first (or, for ArrowUp, last) enabled row | `audit:DropdownMenu/accessibility` |
+| FR8, AR2 | `DropdownMenu.test.tsx` "DropdownMenuItem href" suite (pointer menu and bottom sheet) | Plain click, ⌘-click, Enter with modifiers, disabled link row | A row rendering an inner anchor, running `onClick` on a modified click, or a synthesized click dropping the modifiers fails. | `audit:DropdownMenu/behavior` |
+| FR12, AR3 | `DropdownMenuSubMenu.test.tsx` "drill-in on a phone" suite; `__tests__/DropdownMenuDrillIn.a11y.chromium.spec.ts` (real Chromium, coarse pointer) | Drill in, Back, Escape, ArrowLeft, nested level, scoped typeahead, forced presentations, close resets | A flyout opening on a coarse pointer, a missing Back row, sibling rows staying in the order, or focus not returning to the row fails. | `audit:DropdownMenu/behavior` |
+| FR10 | `DropdownMenuSubMenu.test.tsx` safe-triangle suite; `useMenuHover.test.tsx` `isPointInSafeTriangle` and click-guard suites | diagonal path toward the flyout, a pause inside it, path away, click-opened and hover-opened guard windows | A flyout that closes while the pointer is inside the triangle or paused in it, one that never closes after leaving it, or a changed guard-window rule, fails. | `audit:DropdownMenu/behavior` |
| FR15 | `DropdownMenu.test.tsx` header and footer suite; `__tests__/MenuHeaderFooter.a11y.chromium.spec.ts` in real Chromium | dialog role, modality, name and trigger wiring; regions outside the menu element; typing in a header field; Tab walk header → menu → footer with wrap at both ends; Tab and Shift+Tab from an open sub-menu; hidden and hidden-wrapper controls; Escape from the header; a finger tap on a footer button; bottom sheet order; no regions | A region rendered inside the menu element, a popover with regions that is not a named modal dialog, a trigger still saying `aria-haspopup="menu"` with regions, a header key taken by typeahead, a Tab that leaves the dialog or closes it, focus stranded outside the dialog, or a footer tap swallowed by the press model fails. |
+| FR16 | `DropdownMenuSelectable.test.tsx`, source inspection, scoped `pr-a11y` over the `a11y/Checkbox pattern` stories, and owned Storybook states | checked, unchecked, disabled, caller click/pointer handlers, marker size and ownership | A dropped consumer handler, wrong checked state, nested semantic checkbox, disabled activation, or menu that closes by default fails. | `audit:DropdownMenuCheckboxItem/behavior` |
+| FR17, AR6 | Shared navigation source and DropdownMenu keyboard tests | disabled checkbox row first, middle, and last | Current tests prove the shared hook skips the row; no keyboard-discoverability proof exists until OQ1 is settled. | `audit:DropdownMenuCheckboxItem/accessibility` |
## Decision log
@@ -398,7 +409,13 @@ breaks focus return.
## Open questions
-None.
+- **OQ1 — Which shared owner should make disabled menu rows keyboard-discoverable
+ without changing disabled behavior in non-menu composites?** (`human-api`)
+ WAI-ARIA's Menu pattern keeps disabled menu items focusable but inert. Current
+ `useListFocus` deliberately skips every `aria-disabled` item for all consumers,
+ and DropdownMenu's enabled-only focus-on-open and navigation tests depend on
+ that result. The requirement is objective; choosing a menu-specific hook policy
+ or a DropdownMenu-owned path changes a shared API and ownership boundary.
## Content boundary
@@ -424,7 +441,7 @@ and the router's prefetch; an inner anchor — two controls in one row.
## Open questions
-None.
+OQ1 above remains the only open question.
## Content boundary
diff --git a/packages/core/src/DropdownMenu/DropdownMenuCheckboxItem.doc.mjs b/packages/core/src/DropdownMenu/DropdownMenuCheckboxItem.doc.mjs
index b02ddfbaf1..f64eba5f68 100644
--- a/packages/core/src/DropdownMenu/DropdownMenuCheckboxItem.doc.mjs
+++ b/packages/core/src/DropdownMenu/DropdownMenuCheckboxItem.doc.mjs
@@ -1,5 +1,27 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
+/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */
+const anatomy = [
+ {
+ name: 'Checkable row',
+ required: true,
+ description:
+ 'The menuitemcheckbox root that owns the accessible name, checked state, focus, and activation.',
+ },
+ {
+ name: 'Label/content',
+ required: true,
+ description:
+ 'Caller content laid out by Item: the required label plus optional description, icon, and end content.',
+ },
+ {
+ name: 'Checkbox marker',
+ required: true,
+ description:
+ 'Decorative shared Indicator chrome that visualizes checked and disabled state without adding a second control.',
+ },
+];
+
/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
export const docs = {
@@ -9,6 +31,11 @@ export const docs = {
isHiddenFromOverview: true,
description:
'A checkable menu item (role="menuitemcheckbox") that toggles an independent boolean. Use for on/off options inside a DropdownMenu; for a one-of-N choice use DropdownMenuRadioGroup.',
+ usage: {
+ anatomy,
+ description:
+ 'An independently checkable option inside DropdownMenu. The row owns menuitemcheckbox semantics while the shared Indicator supplies decorative checkbox paint.',
+ },
props: [
{
name: 'label',
@@ -43,7 +70,7 @@ export const docs = {
type: 'boolean',
default: 'false',
description:
- 'Whether the item is disabled. Disabled items stay focusable (via aria-disabled) so they remain discoverable by keyboard and assistive technology, but activation is blocked.',
+ 'Whether the item is disabled. Disabled items expose aria-disabled, block activation, and are currently skipped by DropdownMenu arrow-key navigation.',
},
{
name: 'hasCloseOnSelect',
@@ -65,6 +92,14 @@ export const docs = {
'Content to render after the label and description, such as a keyboard shortcut hint or badge.',
},
],
+ theming: {
+ targets: [
+ {
+ className: 'astryx-dropdown-menu-item',
+ visualProps: ['size'],
+ },
+ ],
+ },
};
export const docsZh = {
@@ -98,7 +133,8 @@ export const docsDense = {
icon: 'icon before label',
value: 'checked state (controlled, w/ onChange)',
onChange: 'fired w/ next checked state on toggle',
- isDisabled: 'disabled; stays focusable via aria-disabled',
+ isDisabled:
+ 'disabled; aria-disabled, no activation; current menu focus skips the row',
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 56131df9ad..c3fa35e93c 100644
--- a/packages/core/src/DropdownMenu/DropdownMenuCheckboxItem.tsx
+++ b/packages/core/src/DropdownMenu/DropdownMenuCheckboxItem.tsx
@@ -4,7 +4,7 @@
/**
* @file DropdownMenuCheckboxItem.tsx
- * @input React, stylex, Item + CheckboxInput + DropdownMenu context + tokens from core
+ * @input React, stylex, Item + Indicator registry + DropdownMenu context + tokens from core
* @output DropdownMenuCheckboxItem — a standalone checkable menu item.
* @position Sub-component; used inside DropdownMenu.
*
@@ -26,7 +26,12 @@
* mobile.
*/
-import {useCallback, type PointerEvent, type ReactNode} from 'react';
+import {
+ useCallback,
+ type MouseEvent,
+ type PointerEvent,
+ type ReactNode,
+} from 'react';
import * as stylex from '@stylexjs/stylex';
import {renderIconSlot, type IconType} from '../Icon';
import {useIndicator} from '../Indicator';
@@ -34,7 +39,7 @@ import {Item} from '../Item';
import {useDropdownMenuContext} from './DropdownMenuContext';
import {focusMenuItemOnHover} from './menuItemHover';
import {colorVars, spacingVars} from '../theme/tokens.stylex';
-import {mergeProps, themeProps} from '../utils';
+import {composeEventHandlers, mergeProps, themeProps} from '../utils';
import type {BaseProps} from '../BaseProps';
const styles = stylex.create({
@@ -58,8 +63,8 @@ const styles = stylex.create({
},
// Rendered in Item's `marker` slot as a raw flex child, so `order` moves it
// relative to the label within the row. On touch it moves to the inline-end.
- // `aria-hidden` + `inert` + pointer-events:none keep the composed CheckboxInput
- // decorative: it adds no accessible name, and clicks fall through to the row,
+ // `aria-hidden` + `inert` + pointer-events:none keep the composed checkbox
+ // indicator decorative: it adds no accessible name, and clicks fall through to the row,
// which owns the role and activation.
// Placement of the marker within the row. The indicator draws its own box
// (size, fill, border) — these are only the rules the MENU owns: where the
@@ -105,9 +110,8 @@ export interface DropdownMenuCheckboxItemProps extends Omit<
*/
onChange?: (checked: boolean) => void;
/**
- * Whether the item is disabled. Disabled items stay focusable (via
- * `aria-disabled`) so they remain discoverable by keyboard and assistive
- * technology, but activation is blocked.
+ * Whether the item is disabled. Disabled items expose `aria-disabled`, block
+ * activation, and are currently skipped by DropdownMenu arrow-key navigation.
* @default false
*/
isDisabled?: boolean;
@@ -132,6 +136,9 @@ export interface DropdownMenuCheckboxItemProps extends Omit<
*
* Must be used inside a DropdownMenu. Toggles an independent boolean; for a
* one-of-N choice use DropdownMenuRadioGroup + DropdownMenuRadioItem instead.
+ * Consumer click and pointer-move handlers compose after the row's own
+ * activation and hover-focus behavior; disabled activation stops before the
+ * consumer click handler.
*
* @example
* ```
@@ -157,6 +164,8 @@ export function DropdownMenuCheckboxItem({
xstyle,
className,
style,
+ onClick,
+ onPointerMove,
...rest
}: DropdownMenuCheckboxItemProps) {
const ctx = useDropdownMenuContext();
@@ -164,15 +173,20 @@ export function DropdownMenuCheckboxItem({
const controlSize = menuSize === 'sm' ? 'sm' : 'md';
const CheckboxControl = useIndicator('checkbox');
- const handleClick = useCallback(() => {
- if (isDisabled) {
- return;
- }
- onChange?.(!value);
- if (hasCloseOnSelect) {
- ctx?.closeMenu();
- }
- }, [isDisabled, onChange, value, hasCloseOnSelect, ctx]);
+ const handleClick = useCallback(
+ (event: MouseEvent) => {
+ if (isDisabled) {
+ event.preventDefault();
+ return;
+ }
+ onChange?.(!value);
+ if (hasCloseOnSelect) {
+ ctx?.closeMenu();
+ }
+ onClick?.(event as MouseEvent<HTMLElement>);
+ },
+ [isDisabled, onChange, value, hasCloseOnSelect, ctx, onClick],
+ );
const handlePointerMove = useCallback(
(e: PointerEvent<HTMLElement>) => focusMenuItemOnHover(e, isDisabled),
@@ -185,7 +199,7 @@ export function DropdownMenuCheckboxItem({
role="menuitemcheckbox"
aria-checked={value}
tabIndex={isDisabled ? undefined : -1}
- onPointerMove={handlePointerMove}
+ onPointerMove={composeEventHandlers(handlePointerMove, onPointerMove)}
marker={
// No wrapper, and no menu-specific theme target: the shared
// `astryx-checkbox-indicator` target is already on this element (main
diff --git a/packages/core/src/DropdownMenu/DropdownMenuSelectable.test.tsx b/packages/core/src/DropdownMenu/DropdownMenuSelectable.test.tsx
index 9a7ccd3585..6bb4fbfef8 100644
--- a/packages/core/src/DropdownMenu/DropdownMenuSelectable.test.tsx
+++ b/packages/core/src/DropdownMenu/DropdownMenuSelectable.test.tsx
@@ -10,7 +10,7 @@
*/
import {describe, it, expect, vi, beforeEach} from 'vitest';
-import {render, screen} from '@testing-library/react';
+import {render, screen, fireEvent, waitFor} from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import {DropdownMenu} from './DropdownMenu';
import {DropdownMenuCheckboxItem} from './DropdownMenuCheckboxItem';
@@ -63,6 +63,151 @@ describe('DropdownMenuCheckboxItem', () => {
}),
);
expect(onChangeSpy).toHaveBeenCalledWith(true);
+ expect(HTMLElement.prototype.hidePopover).not.toHaveBeenCalled();
+ });
+
+ it('composes the caller click handler with the checked-state change', async () => {
+ const user = userEvent.setup();
+ const calls: string[] = [];
+ const onChange = vi.fn(() => calls.push('change'));
+ const onClick = vi.fn(() => calls.push('click'));
+ render(
+ <DropdownMenu button={{label: 'View'}}>
+ <DropdownMenuCheckboxItem
+ label="Show archived"
+ value={false}
+ onChange={onChange}
+ onClick={onClick}
+ />
+ </DropdownMenu>,
+ );
+ await user.click(screen.getByRole('button', {name: /View/}));
+ await user.click(
+ screen.getByRole('menuitemcheckbox', {
+ name: /Show archived/,
+ hidden: true,
+ }),
+ );
+ expect(onChange).toHaveBeenCalledWith(true);
+ expect(onClick).toHaveBeenCalledOnce();
+ expect(calls).toEqual(['change', 'click']);
+ });
+
+ it('composes the caller click handler on keyboard activation', async () => {
+ const user = userEvent.setup();
+ const onChange = vi.fn();
+ const onClick = vi.fn();
+ render(
+ <DropdownMenu button={{label: 'View'}}>
+ <DropdownMenuCheckboxItem
+ label="Show archived"
+ value={false}
+ onChange={onChange}
+ onClick={onClick}
+ />
+ </DropdownMenu>,
+ );
+ const trigger = screen.getByRole('button', {name: /View/});
+ trigger.focus();
+ await user.keyboard('{Enter}');
+ const item = screen.getByRole('menuitemcheckbox', {
+ name: /Show archived/,
+ hidden: true,
+ });
+ await waitFor(() => expect(item).toHaveFocus());
+ await user.keyboard('{Enter}');
+ expect(onChange).toHaveBeenCalledWith(true);
+ expect(onClick).toHaveBeenCalledOnce();
+ });
+
+ it('composes the caller pointer-move handler with menu hover focus', async () => {
+ const user = userEvent.setup();
+ const onPointerMove = vi.fn(() => document.activeElement);
+ render(
+ <DropdownMenu button={{label: 'View'}}>
+ <DropdownMenuCheckboxItem
+ label="Show archived"
+ value={false}
+ onPointerMove={onPointerMove}
+ />
+ </DropdownMenu>,
+ );
+ await user.click(screen.getByRole('button', {name: /View/}));
+ const item = screen.getByRole('menuitemcheckbox', {
+ name: /Show archived/,
+ hidden: true,
+ });
+ fireEvent.pointerMove(item, {pointerType: 'mouse'});
+ expect(item).toHaveFocus();
+ expect(onPointerMove).toHaveBeenCalledOnce();
+ expect(onPointerMove).toHaveReturnedWith(item);
+ });
+
+ it('does not call consumer activation handlers when disabled', async () => {
+ const user = userEvent.setup();
+ const onChange = vi.fn();
+ const onClick = vi.fn();
+ render(
+ <DropdownMenu button={{label: 'View'}}>
+ <DropdownMenuCheckboxItem
+ label="Show archived"
+ value={false}
+ onChange={onChange}
+ onClick={onClick}
+ isDisabled
+ />
+ </DropdownMenu>,
+ );
+ await user.click(screen.getByRole('button', {name: /View/}));
+ await user.click(
+ screen.getByRole('menuitemcheckbox', {
+ name: /Show archived/,
+ hidden: true,
+ }),
+ );
+ expect(onChange).not.toHaveBeenCalled();
+ expect(onClick).not.toHaveBeenCalled();
+ });
+
+ it('closes after a successful toggle only when requested', async () => {
+ const user = userEvent.setup();
+ render(
+ <DropdownMenu button={{label: 'View'}}>
+ <DropdownMenuCheckboxItem
+ label="Show archived"
+ value={false}
+ onChange={() => {}}
+ hasCloseOnSelect
+ />
+ </DropdownMenu>,
+ );
+ await user.click(screen.getByRole('button', {name: /View/}));
+ await user.click(
+ screen.getByRole('menuitemcheckbox', {
+ name: /Show archived/,
+ hidden: true,
+ }),
+ );
+ expect(HTMLElement.prototype.hidePopover).toHaveBeenCalledOnce();
+ });
+
+ it('maps a small menu to the small shared checkbox marker', async () => {
+ const user = userEvent.setup();
+ render(
+ <DropdownMenu button={{label: 'View', size: 'sm'}}>
+ <DropdownMenuCheckboxItem label="Show archived" value={true} />
+ </DropdownMenu>,
+ );
+ await user.click(screen.getByRole('button', {name: /View/}));
+ const row = screen.getByRole('menuitemcheckbox', {
+ name: /Show archived/,
+ hidden: true,
+ });
+ expect(row).toHaveAttribute('aria-checked', 'true');
+ expect(row.querySelector('.astryx-checkbox-indicator')).toHaveAttribute(
+ 'data-size',
+ 'sm',
+ );
});
it('keeps the checkbox indicator decorative (row is the only announced control)', async () => {