Skip to content

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

TypeScript

docs(spec): ContextMenu records its shipped contract as current (#9125)

Cindy Zhang6b63e75d56a1
diff --git a/packages/core/src/ContextMenu/ContextMenu.spec.md b/packages/core/src/ContextMenu/ContextMenu.spec.md
index 4c4bbfc5d8..4eaaf3274f 100644
--- a/packages/core/src/ContextMenu/ContextMenu.spec.md
+++ b/packages/core/src/ContextMenu/ContextMenu.spec.md
@@ -1,21 +1,20 @@
---
schema_version: 3
-template_version: 3
+template_version: 7
kind: component
id: component:ContextMenu
-authority: draft
+authority: current
archive_reason: null
superseded_by: null
-approved_by: null
-approved_at: null
+approved_by: cixzhang
+approved_at: 2026-10-31
owners: [cixzhang]
review_triggers: [accessibility, behavior, public-api, theming]
verified_by:
[
packages/core/src/ContextMenu/ContextMenu.test.tsx,
- packages/core/src/DropdownMenu/DropdownMenu.test.tsx,
- packages/core/src/BottomSheet/BottomSheet.test.tsx,
- packages/core/src/List/List.test.tsx,
+ packages/core/src/ContextMenu/ContextMenu.triggerProps.test.tsx,
+ packages/core/src/theme/themingTargets.test.ts,
scripts/check-knowledge.mjs,
]
modules: []
@@ -29,29 +28,39 @@ architecture:
architecture:public-component-api,
]
contributing: []
-system_specs: []
+system_specs: [spec:AST-094, spec:AST-107]
---
# ContextMenu component contract
+## Contract at a glance
+
+| Area | Contract |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract | None changes. ContextMenu takes caller `children` as the Trigger area, data-driven `items` or compound `menuContent`, `label`, `presentation`, `isDisabled`, and `triggerAs`. |
+| Behavior | Right-click, Shift+F10 or the Menu key, and a touch long press open a menu at the cursor (or the trigger's bottom-left from the keyboard), or a bottom sheet; rows follow DropdownMenu's rows and press model. |
+| End-user impact | People reach a region's actions by mouse, keyboard, or a held finger; a sub-menu drills in on a phone. Under a finger the menu does not grow from where it was opened or lift its trigger, and a scroll that starts outside leaves it open. |
+| Builder impact | Builders wrap any region, including an inline reference in prose (`triggerAs="span"`). |
+| Compatibility/readiness | Records shipped behavior; no API or DOM change; the released default under a finger moves as `spec:AST-094` FR25 lists, with `presentation="popover"` keeping it. The touch grow, pan dismissal, and trigger lift (FR5) are listed under Current-state impact. |
+| Review checks | Reject a trigger that gains a role or `aria-haspopup`, a menu that bypasses the shared Escape stack, a `context-menu` target moved off the painted surface, or a second open-state owner. |
+| Governing rules | `spec:AST-107` FR8; `spec:AST-094` FR26–FR35; `module:DropdownMenu/useMenuPress`; `family:overlay-dismissal`; `architecture:component-theming-surface`; `architecture:layer-runtime`. |
+
+This table is a review projection; the body below is authoritative.
+
## Intent
ContextMenu presents actions for a caller-provided region in either a
-cursor-positioned pointer menu or a BottomSheet-hosted touch action list. The
-record describes current consumer anatomy, presentation-specific ownership, and
-theming reachability.
+cursor-positioned pointer menu or a BottomSheet-hosted touch action list.
## Compatibility and migration
-- Released default: `popover`. Under a finger, `spec:AST-094` FR33's lift
- becomes the default, and `presentation="popover"` keeps the released menu
- (`spec:AST-094` FR25).
-- Compatibility class: compatible behavior correction; public API, DOM shape,
- styling, and targets are preserved; the default under a finger changes as
- above
+- Released default preserved: `no` under a finger: the omitted `presentation`
+ follows `spec:AST-094` FR31–FR33 (FR5); `presentation="popover"` keeps the
+ released menu (`spec:AST-094` FR25)
+- Compatibility class: records shipped behavior; no public prop, export, or
+ DOM change
- Controlled/uncontrolled behavior: internally managed open state
-- Migration decision: `spec:AST-094` FR25 (a caller that needs the released
- menu under a finger passes `presentation="popover"`)
+- Migration decision: `spec:AST-094` FR25
Consumer migration instructions belong in consumer docs and release notes.
@@ -59,17 +68,18 @@ Consumer migration instructions belong in consumer docs and release notes.
**Owns**
-- The Trigger area's context-menu invocation wiring, through the public
- headless context menu (FR10).
+- The Trigger area's context-menu invocation wiring (FR10).
- The alternative Pointer menu surface and Touch menu surface and their shared
- current `context-menu` target.
-- Cursor-anchor placement across the two presentation paths; open state is the
- factory's (FR10).
+ `context-menu` target.
+- Cursor-anchor placement across the two presentation paths, and open state
+ (FR10).
**Does not own / non-goals**
- Caller-provided Trigger area content.
-- Pointer action-row presentation — delegated to `component:DropdownMenu`.
+- Pointer action-row presentation — delegated to `component:DropdownMenu`; the
+ `ContextMenuItem`, `ContextMenuDivider`, and `ContextMenuGroup` exports are
+ DropdownMenu's components under these names (`component:ContextMenuItem`).
- The Touch sheet frame — delegated to `component:BottomSheet`.
- Data-driven Touch action-list and row presentation — delegated to
`component:List`.
@@ -78,7 +88,7 @@ Consumer migration instructions belong in consumer docs and release notes.
## Public concepts
Consumer props, content modes, and presentation policy remain documented in
-`ContextMenu.doc.mjs`. One component-local concept is added by DEC-1:
+`ContextMenu.doc.mjs`. DEC-1 adds one component-local concept:
| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
| --------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | ------- | ----------------------- | --------- | -------------------------------- |
@@ -86,18 +96,18 @@ Consumer props, content modes, and presentation policy remain documented in
## Behavioral and layout contract
-| ID | Candidate invariant | Basis | Draft review state |
-| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | --------------------------------------------------- |
-| FR1 | Every render contains a caller-provided Trigger area. Pointer presentation opens a Pointer menu surface at the current local cursor anchor; touch presentation opens a Touch sheet frame containing a Touch menu surface and, for data mode, a Touch action list and Touch action rows. | Current source, docs, and tests | Current behavior; verified |
-| FR2 | The current `context-menu` target remains on the painted Pointer menu surface and alternative Touch menu surface, not on the Trigger area or cursor anchor. | Current source, docs, and tests | Current inventory; verified |
-| FR3 | Pointer action rows retain DropdownMenu ownership. The touch frame retains BottomSheet ownership, while data-driven touch lists and rows retain List ownership. | Current source and owner docs | Current delegation; verified |
-| FR4 | Compound `menuContent` remains a caller-supplied pointer-menu interior and may also render inside the touch frame; the data-driven touch path instead converts the same item data to List and ListItem presentation. | Current source and tests | Current branches; verified |
-| FR5 | The Pointer menu surface carries `data-astryx-menu-press` and follows `module:DropdownMenu/useMenuPress` FR1–FR7: the row under the release acts, the highlight follows a held pointer, a mouse released outside closes and a finger leaves the menu open, the stray click never acts, and `touch-action` follows overflow. Under a finger the press follows `spec:AST-094` FR26–FR28 and FR30, and the menu's grow, dismissal, long-press lift and outside press follow FR31–FR33 and FR35 (pending implementation); a mouse press outside is unchanged. Right-click, Shift+F10, long-press invocation and keyboard navigation keep their existing behavior. | `module:DropdownMenu/useMenuPress`; `ContextMenu.test.tsx` press model suite | Current module projection; verified in jsdom |
-| FR6 | With `triggerAs="span"` the Trigger area MUST be an inline element that owns a box, so the cursor anchor measures from the trigger's own rect on every invocation path. Right-click, Shift+F10, long-press, and `context-menu` target placement all use that box. | `component:ContextMenu/DEC-1` | Accepted; verified in jsdom |
-| FR7 | Sub-menu rows follow `component:DropdownMenu` FR12 inside the pointer menu: ContextMenu mounts the same drill-in view stack, named after its `label`, so a sub-menu drills in on a phone here too. | `component:DropdownMenu/DEC-2` | Proposed; verified in jsdom; owner decision pending |
-| FR8 | In the pointer menu ArrowDown on the last enabled row wraps to the first and ArrowUp on the first to the last; PageDown and PageUp page as in DropdownMenu FR6; a held key's auto-repeat does not activate; typeahead matches the row's label element alone. | Current source and tests; shared `useListFocus` and `useTypeahead` suites | Proposed; verified in jsdom; owner decision pending |
-| FR9 | While the Pointer menu surface is open, it participates in `family:overlay-dismissal` through the shared stack and provides descendant depth. One Escape press affects only the top-most present nested surface; ContextMenu closes only when it is that surface. | `family:overlay-dismissal` FR1–FR6; `ContextMenu.test.tsx` nested-layer case | Current family projection; verified in jsdom |
-| FR10 | ContextMenu is built on the public headless context menu (`spec:AST-107` FR8): its invocation, open state, and cleanup are the factory's, with no behavior of its own beside the factory's. | Owner decision, 2026-10-26; `spec:AST-107` FR8 | Decided |
+| ID | Invariant | Basis |
+| ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| FR1 | Every render contains a caller-provided Trigger area; with `isDisabled` no invocation opens a menu and the native context menu is left alone. Pointer presentation opens a Pointer menu surface at the current local cursor anchor; touch presentation opens a Touch sheet frame containing a Touch menu surface and, for data mode, a Touch action list and Touch action rows. | Current source, docs, and tests |
+| FR2 | The `context-menu` target stays on the painted Pointer menu surface and alternative Touch menu surface, not on the Trigger area or cursor anchor. | `architecture:component-theming-surface`; current source |
+| FR3 | Pointer action rows retain DropdownMenu ownership. The touch frame retains BottomSheet ownership, while data-driven touch lists and rows retain List ownership. | Current source and owner docs |
+| FR4 | Compound `menuContent` remains a caller-supplied pointer-menu interior and may also render inside the touch frame; the data-driven touch path instead converts the same item data to List and ListItem presentation. | Current source and tests |
+| FR5 | The Pointer menu surface carries `data-astryx-menu-press` and follows `module:DropdownMenu/useMenuPress` FR1–FR7: the row under the release acts, the highlight follows a held pointer, a mouse released outside closes and a finger leaves the menu open, the stray click never acts, and `touch-action` follows overflow. The long press that opened the menu does not close it as it lifts; a tap outside closes it, and a mouse press outside closes it at the press. Under a finger the menu MUST grow out of where it was opened and shrink back (`spec:AST-094` FR31), MUST close as a pan that starts outside it begins (FR32), MUST hand the held finger that opened it to the menu as the opening press and, on a block trigger, lift the trigger above the page with the menu beside it, and MUST treat a pen's press outside as FR32 does (FR33). Implementation gap: it keeps the layer's own entrance and exit, a scroll that starts outside leaves it open, the opening finger is not handed to the menu so it cannot slide to a row, no trigger lift exists, and a pen press outside closes it at the press. Right-click, Shift+F10, long-press invocation, and keyboard navigation are as FR1 and FR8 state. | `module:DropdownMenu/useMenuPress`; `spec:AST-094` FR26–FR33 |
+| FR6 | With `triggerAs="span"` the Trigger area is an inline element that owns a box, so the cursor anchor measures from the trigger's own rect on every invocation path. Right-click, Shift+F10, long-press, and `context-menu` target placement all use that box. | DEC-1 |
+| FR7 | Sub-menu rows follow `component:DropdownMenu` FR11 inside the pointer menu: ContextMenu mounts the same drill-in view stack, named after its `label`, so a sub-menu drills in on a phone here too. A sub-menu with a header or footer shows its rows alone here (`component:DropdownMenu` FR20). | `component:DropdownMenu/DEC-4` |
+| FR8 | In the pointer menu ArrowDown on the last enabled row wraps to the first and ArrowUp on the first to the last; PageDown and PageUp page as in `component:DropdownMenu` FR12; a held key's auto-repeat does not activate; typeahead matches the row's label element alone. Arrow keys and typeahead skip disabled rows, shipped behavior that is not a requirement until `component:DropdownMenu` OQ1 is ruled. | Current source and tests |
+| FR9 | While the Pointer menu surface is open, it participates in `family:overlay-dismissal` through the shared stack and provides descendant depth. One Escape press affects only the top-most present nested surface; ContextMenu closes only when it is that surface. | `family:overlay-dismissal` FR1–FR6; `ContextMenu.test.tsx` nested-layer case |
+| FR10 | ContextMenu MUST be built on the public headless context menu (`spec:AST-107` FR8), with its invocation, open state, and cleanup the factory's and no behavior of its own beside the factory's. Implementation gap: no headless context menu ships; ContextMenu owns its invocation, open state, outside-press listener, and cleanup itself. | `spec:AST-107` FR8 |
### Allowed variation
@@ -122,13 +132,18 @@ Consumer props, content modes, and presentation policy remain documented in
### Transformation and precedence order
-- Presentation resolution, cursor positioning, long-press handling, item
- rendering, and styling keep their current precedence.
+- **ORD1 — Cursor anchor.** A pointer invocation anchors at the pointer,
+ kept inside the trigger at its end edges; a keyboard invocation anchors at
+ the trigger's bottom-left.
### Performance and resources
-- The component introduces no separate loading, listener, measurement, or render
- constraint beyond the owners named above.
+- **PR1 — Bounded resources.** While open, ContextMenu adds a document (and
+ shadow-root) mousedown listener for outside dismissal and removes it on
+ close, and the
+ pointer menu observes its size and content to decide whether it scrolls. With
+ `presentation="adaptive"` it subscribes to the compact-touch query while
+ mounted.
## Accessibility contract
@@ -140,7 +155,7 @@ stack; while a pointer is held in the pointer menu, the highlight is DOM focus p
- **AR1 — An inline trigger keeps its semantics.** `triggerAs` changes the
Trigger area's element and box only; it carries no role or `aria-haspopup`
- (menus-15) in any form, and the menu keeps its own name (`label`).
+ in any form, and the menu keeps its own name (`label`).
## Design relationships
@@ -196,10 +211,10 @@ anchor is positioning infrastructure rather than consumer anatomy.
- `architecture:interaction-modality` owns the shared right-click, keyboard,
long-press, pointer, touch, and adaptive-presentation boundaries.
- `architecture:layer-runtime` owns the current context-mode `useLayer` host and
- cursor-anchor positioning. The factory closes the menu on an outside press
- (`spec:AST-107` FR8; FR10), and ContextMenu joins shared Escape ordering through
+ cursor-anchor positioning. ContextMenu closes the menu on an outside press itself (FR10), and joins shared Escape ordering through
`useLayerDismissal`; touch hosting delegates
to BottomSheet.
+- `spec:AST-094` owns the touch press, lift, grow, and dismissal rules (FR5).
- `family:overlay-dismissal` owns shared Escape and platform-close ordering.
ContextMenu's pointer presentation is a shared-stack adopter; the touch
presentation delegates dismissal to BottomSheet, which is also a shared-stack
@@ -207,17 +222,30 @@ anchor is positioning infrastructure rather than consumer anatomy.
## Verification map
-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
-| ------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ---------------------------- |
-| FR1, FR4 | `ContextMenu.test.tsx` pointer, long-press, bottom-sheet, adaptive, compound, and drill-in suites | Pointer data/compound and touch data/compound | Collapsing presentation-specific parts or content owners fails structure, role, or behavior tests. | `audit:ContextMenu/anatomy` |
-| FR2 | ContextMenu target tests, source inspection, and theming target inventories | Pointer and touch menu surfaces | Moving `context-menu` to the trigger or removing it from a painted branch fails evidence. | `audit:ContextMenu/theming` |
-| FR3 | ContextMenu, DropdownMenu, BottomSheet, and List owner tests | Pointer rows, touch frame, touch list/rows | A composed part loses its owner target or is documented as a new ContextMenu target. | `audit:ContextMenu/theming` |
-| Layer relationships | `ContextMenu.test.tsx` nested-layer case and current layer/dismissal architecture records | Outside click, Escape, nested context layers, sheet | A Pointer menu bypassing the shared stack or dismissing with its nested child fails. | `audit:ContextMenu/behavior` |
-| FR5 | `ContextMenu.test.tsx` press model case; `module:DropdownMenu/useMenuPress` map | Finger slide across rows, stray click | A row acting on the press row or the stray click fails. | `audit:ContextMenu/behavior` |
-| FR6 | `ContextMenu.test.tsx` keyboard case; shared `useListFocus` and `useTypeahead` suites | wrap at both ends | Clamping arrows fail. | `audit:ContextMenu/behavior` |
-| FR10 | ContextMenu tests over `createContextMenu` and a source check | a right click, a long press, Shift+F10; open, close, unmount while open | A context request that bypasses the factory, open state ContextMenu keeps on its own, or a listener left after unmount fails | `audit:ContextMenu/behavior` |
-| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and current target | Missing, extra, prefixed, stale, or unclassified mappings fail repository validation. | `audit:ContextMenu/theming` |
-| FR6, AR1 | `ContextMenu.test.tsx` "inline trigger (triggerAs)" suite | `span` in a paragraph, default `div` | A block trigger inside prose, or a lost invocation path, fails. | `audit:ContextMenu/behavior` |
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- |
+| FR1, FR4 | `ContextMenu.test.tsx` rendering, invocation, bottom-sheet, adaptive, compound, and disabled cases ("renders menu with role=\"menu\"", "opens menu on right-click", "opens from a keyboard-invoked contextmenu (Shift+F10 / Menu key)", "opens on touch long-press", "opens the real menu content in a BottomSheet when requested", "uses the BottomSheet for adaptive presentation on compact touch", "renders menuContent as menu items", "does not open when isDisabled is true") | Right-click, keyboard, long press; pointer and sheet; data and compound; disabled | A missing invocation path, menu role, sheet, or compound interior, or a disabled trigger that opens, fails. Evidence gap: no test asserts that a disabled trigger leaves the native context menu alone. | `audit:ContextMenu/anatomy` |
+| FR2 | `themingTargets.test.ts` | Rendered targets | A rendered class absent from the documented targets fails. Evidence gap: no test asserts `context-menu` on either painted surface or its absence from the trigger. | `audit:ContextMenu/theming` |
+| FR3 | `ContextMenu.test.tsx` destructive-variant, section, divider, selectable, and alias cases | Shared rows through ContextMenu | A row that loses DropdownMenu's semantics or variant fails. Evidence gap: no test asserts the BottomSheet and List delegation beyond rendering. | `audit:ContextMenu/theming` |
+| FR5 | `ContextMenu.test.tsx` "acts on the row under a finger release, once, and swallows the stray click" and outside-dismissal cases; `ContextMenuLongPress.a11y.chromium.spec.ts` | Finger release; long press lift; tap, mouse, pen, and scroll outside | A row acting on the press row, a stray click that acts, a long press that closes its own menu, or a tap or mouse press outside that leaves it open fails. Evidence gap: no test asserts the FR31 grow, the opening-finger handoff, or the FR33 lift; the scroll-outside and pen cases assert the current gaps. | `audit:ContextMenu/behavior` |
+| FR6, AR1, ORD1 | `ContextMenu.test.tsx` "inline trigger (triggerAs)" and cursor-anchor cases; "does not put aria-haspopup on the role-less trigger wrapper (menus-15)"; `ContextMenu.triggerProps.test.tsx`; `ContextMenuCursorAnchor.a11y.browser.spec.ts` | `span` in a paragraph; default `div`; pointer and keyboard anchors | A block trigger in prose, a trigger with a role or `aria-haspopup`, or an anchor outside the trigger fails. | `audit:ContextMenu/behavior` |
+| FR7 | `ContextMenu.test.tsx` "drills into nested data items inside the BottomSheet", "renders a submenu from a nested items array and keyboard-reaches an item after it", and "shows a sub-menu with a header or footer as its rows alone, and says why in development" | Sheet drill-in; pointer sub-menu; regions under ContextMenu | A missing sub-menu, an unreachable row after it, or a sub-menu dialog under ContextMenu fails. Evidence gap: no test here asserts the pointer drill-in on a phone. | `audit:ContextMenu/behavior` |
+| FR8 | `ContextMenu.test.tsx` "wraps arrow navigation at the ends", typeahead cases, and "skips aria-disabled menuitemradio and menuitemcheckbox items during arrow navigation" | Wrap; typeahead; disabled rows | A clamped arrow, a missing typeahead match, or a disabled row landed on fails. Evidence gap: no test asserts Page keys or auto-repeat. | `audit:ContextMenu/behavior` |
+| FR9 | `ContextMenu.test.tsx` "lets a nested layer consume Escape before the context menu", "closes on Escape even when opened without auto-focus", and "ignores Escape during IME composition" | Nested layer; Escape; composition | A context menu that closes with its nested child, or on a composition Escape, fails. | `audit:ContextMenu/behavior` |
+| FR10, PR1 | `ContextMenu.test.tsx` invocation and handler-composition cases ("composes the consumer context-menu handler with menu opening", "keeps component-owned opening when a consumer prevents default", "composes consumer touch handlers with long-press detection") | Right click, long press, keyboard | A context request that does not open the menu, or a dropped consumer handler, fails. Evidence gap: no test asserts listener cleanup on unmount; nothing tests a headless factory, which does not ship (the FR10 gap). | `audit:ContextMenu/behavior` |
+| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and target | Missing, extra, prefixed, stale, or unclassified mappings fail repository validation. | `audit:ContextMenu/theming` |
+
+## Current-state impact
+
+- **No headless factory (FR10).** No headless context menu ships, so ContextMenu
+ owns its invocation, open state, and outside-press listener itself, against
+ `spec:AST-107` FR8.
+- **Touch grow, pan dismissal, handoff, and lift (FR5).** Under a finger the
+ menu keeps the layer's own entrance and exit instead of growing from where it
+ was opened, a scroll that starts outside leaves it open, the held finger that
+ opened it cannot slide to a row, and a block trigger is not lifted; a pen
+ press outside closes it at the press. All are against `spec:AST-094` FR31,
+ FR32, and FR33.
## Decision log
diff --git a/packages/core/src/ContextMenu/ContextMenuItem.spec.md b/packages/core/src/ContextMenu/ContextMenuItem.spec.md
new file mode 100644
index 0000000000..9066e4a78c
--- /dev/null
+++ b/packages/core/src/ContextMenu/ContextMenuItem.spec.md
@@ -0,0 +1,132 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:ContextMenuItem
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-10-31
+owners: [cixzhang]
+review_triggers: [public-api]
+verified_by: [packages/core/src/ContextMenu/ContextMenu.test.tsx]
+modules: []
+families: []
+design_specs: []
+architecture: [architecture:public-component-api]
+contributing: []
+system_specs: []
+---
+
+# ContextMenuItem component contract
+
+## Contract at a glance
+
+| Area | Contract |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| Public contract | `ContextMenuItem` is `DropdownMenuItem` exported from the ContextMenu entry point under this name, with its props type. |
+| Behavior | Identical to `component:DropdownMenuItem` inside a ContextMenu's compound `menuContent`. |
+| End-user impact | A context-menu row looks and behaves exactly like a dropdown-menu row. |
+| Builder impact | Builders compose ContextMenu rows without importing from DropdownMenu. |
+| Compatibility/readiness | Records shipped behavior; no API, default, or DOM change. |
+| Review checks | Reject a ContextMenuItem that diverges from DropdownMenuItem, or a separate implementation behind the name. |
+| Governing rules | `component:DropdownMenuItem`; `architecture:public-component-api`. |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+Give ContextMenu callers a row under the ContextMenu name without a second row
+implementation.
+
+## Compatibility and migration
+
+- Released default preserved: yes.
+- Compatibility class: records shipped behavior; no public prop, default,
+ export, or DOM change.
+- Controlled/uncontrolled behavior: not applicable.
+- Migration decision: none.
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- The `ContextMenuItem` export name and its `ContextMenuItemProps` type name.
+
+**Does not own / non-goals**
+
+- Every row behavior, semantic, and target — owned by
+ `component:DropdownMenuItem`.
+- The menu around it — owned by `component:ContextMenu`.
+
+## Public concepts
+
+| Concept | Closed values or states | Meaning | Availability | Default | Owner | Stability | Invalid-value behavior |
+| ---------- | ----------------------- | -------------------------------------------- | ------------- | ------- | --------------------------- | --------- | ---------------------- |
+| Alias name | `ContextMenuItem` | DropdownMenuItem under the ContextMenu name. | Compound mode | — | `component:ContextMenuItem` | stable | Not applicable. |
+
+## Behavioral and layout contract
+
+| ID | Invariant | Basis |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
+| FR1 | `ContextMenuItem` is the same component as `DropdownMenuItem`, and `ContextMenuItemProps` is `DropdownMenuItemProps`; the row follows `component:DropdownMenuItem`. | Current source |
+
+### Allowed variation
+
+- **AV1 — None.** The alias adds nothing of its own.
+
+### Representative states
+
+| State | Required invariant | Allowed variation |
+| ------------ | ----------------------------------------------------- | ----------------- |
+| Compound row | Renders as a DropdownMenuItem row inside ContextMenu. | Row content. |
+
+### Transformation and precedence order
+
+- **ORD1 — None.** The alias has no precedence of its own.
+
+### Performance and resources
+
+- **PR1 — None of its own.** Resources are DropdownMenuItem's.
+
+## Accessibility contract
+
+- **AR1 — Same row.** Semantics and keyboard behavior are
+ `component:DropdownMenuItem`'s.
+
+## Design relationships
+
+| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
+| ---------------- | ---------------------------- | ---------------------------- | -------------- | ------------------ |
+| Row | Same as a dropdown-menu row. | `component:DropdownMenuItem` | Prominent | FR1 |
+
+`component:DropdownMenuItem` owns the row's targets and `component:ContextMenu`
+maps the pointer action row in its theming anatomy, so this record carries no
+anatomy-theming map.
+
+## Family and system relationships
+
+- `component:DropdownMenuItem` owns the row contract.
+- `component:ContextMenu` owns the menu.
+
+## Verification map
+
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- |
+| FR1, AR1 | `ContextMenu.test.tsx` compound cases ("renders menuContent as menu items", "renders ContextMenuItem endContent", "calls onClick when compound item is clicked") | Compound rows | A ContextMenuItem that does not render or act as a menu row fails. Evidence gap: no test asserts that the export is the same component as DropdownMenuItem. | `audit:ContextMenuItem/api` |
+
+## Decision log
+
+No component-local decision.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables/examples or the row contract.
+It links to their owners.