@astryxdesign/core 0.7.1-canary.ff40b78 → 0.7.1

package/src/ComplexSelector/ComplexSelector.test.tsx

@@ -262,6 +262,51 @@ describe('ComplexSelector', () => {
     ).toHaveLength(2);
   });
 
+  it('applies distinct trigger chrome to the secondary variant', () => {
+    // data-testid reaches the native control; the variant is on the trigger root.
+    const triggerRoot = () =>
+      screen
+        .getByTestId('view-options')
+        .closest('.astryx-complex-selector') as HTMLElement;
+    const {rerender} = render(
+      <ComplexSelector
+        label="View options"
+        value={['name']}
+        variant="input"
+        data-testid="view-options">
+        {() => <div>Columns</div>}
+      </ComplexSelector>,
+    );
+    const inputClasses = triggerRoot().className;
+
+    rerender(
+      <ComplexSelector
+        label="View options"
+        value={['name']}
+        variant="secondary"
+        data-testid="view-options">
+        {() => <div>Columns</div>}
+      </ComplexSelector>,
+    );
+    const secondary = triggerRoot();
+    const secondaryClasses = secondary.className;
+    expect(secondary).toHaveAttribute('data-variant', 'secondary');
+
+    rerender(
+      <ComplexSelector
+        label="View options"
+        value={['name']}
+        variant="ghost"
+        data-testid="view-options">
+        {() => <div>Columns</div>}
+      </ComplexSelector>,
+    );
+    const ghostClasses = triggerRoot().className;
+
+    expect(secondaryClasses).not.toBe(inputClasses);
+    expect(secondaryClasses).not.toBe(ghostClasses);
+  });
+
   it('supports end-aligned popup positioning', () => {
     render(
       <ComplexSelector label="View options" value={[]} alignment="end">
@@ -721,22 +766,25 @@ describe('ComplexSelector onOpenChange', () => {
       );
     });
 
-    it('forces detached when variant="ghost" even if statusVariant="attached"', () => {
-      const {container} = render(
-        <ComplexSelector
-          label="Filter"
-          value={[]}
-          variant="ghost"
-          status={{type: 'error', message: 'Required'}}
-          statusVariant="attached">
-          {() => <button type="button">Apply</button>}
-        </ComplexSelector>,
-      );
-      expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
-        'data-variant',
-        'detached',
-      );
-    });
+    it.each(['secondary', 'ghost'] as const)(
+      'forces detached when variant="%s" even if statusVariant="attached"',
+      variant => {
+        const {container} = render(
+          <ComplexSelector
+            label="Filter"
+            value={[]}
+            variant={variant}
+            status={{type: 'error', message: 'Required'}}
+            statusVariant="attached">
+            {() => <button type="button">Apply</button>}
+          </ComplexSelector>,
+        );
+        expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
+          'data-variant',
+          'detached',
+        );
+      },
+    );
 
     it('renders no message box for statusVariant="tooltip"', () => {
       const {container} = render(

package/src/ComplexSelector/ComplexSelector.tsx

@@ -5,7 +5,7 @@
 /**
  * @file ComplexSelector.tsx
  * @input Uses React, StyleX, Field, Icon slots, Layer positioning, and usePopover
- * @output Exports a rich-selector shell with exact token-sized input and ghost triggers, plus an imperative open/close handle
+ * @output Exports a rich-selector shell with exact token-sized input, secondary, and ghost triggers, plus an imperative open/close handle
  * @position Core implementation; consumed by index.ts
  *
  * SYNC: When modified, update:
@@ -151,6 +151,31 @@ const styles = stylex.create({
       '[data-astryx-press="on"]': 'scale(0.98)',
     },
   },
+  // Keep the input-family width contract while reusing ghost's borderless paint
+  // and the neutral resting fill used by secondary buttons.
+  triggerSecondary: {
+    borderWidth: 0,
+    backgroundColor: colorVars['--color-neutral'],
+    boxShadow: {
+      default: 'none',
+      ':hover:not(:focus-within):where(:not(:disabled,[aria-disabled="true"]))':
+        {
+          '@media (hover: hover)': 'none',
+        },
+      ':focus-within': 'none',
+    },
+    fontWeight: fontWeightVars['--font-weight-medium'],
+    transitionProperty:
+      'background-image, background-color, color, opacity, transform',
+    transform: {
+      default: 'scale(1)',
+      ':active': {
+        default: 'scale(0.98)',
+        '@media (pointer: coarse)': 'scale(1)',
+      },
+      '[data-astryx-press="on"]': 'scale(0.98)',
+    },
+  },
   triggerGhostDisabled: {
     backgroundImage: 'none',
     transform: {
@@ -202,7 +227,7 @@ const styles = stylex.create({
   },
 });
 
-export type ComplexSelectorVariant = 'input' | 'ghost';
+export type ComplexSelectorVariant = 'input' | 'secondary' | 'ghost';
 
 export type ComplexSelectorSize = 'sm' | 'md' | 'lg';
 
@@ -338,17 +363,20 @@ export interface ComplexSelectorProps<Value> extends Omit<
   status?: ComplexSelectorStatus;
   /**
    * How the status message is placed relative to the input.
-   * - 'attached': message overlaps directly below the input (bordered treatment; detached when variant is ghost)
+   * - 'attached': message overlaps directly below the input (bordered treatment; detached when variant is secondary or ghost)
    * - 'detached': message floats below as a separate element with spacing
    * - 'tooltip': no message box; the status icon becomes a focusable info-tip button that reveals the message on hover, keyboard focus, or tap
-   * @default 'attached'
+   * @default 'attached' for input selectors; 'detached' for secondary and ghost selectors
    */
   statusVariant?: FieldStatusVariant;
   /** Tooltip text displayed next to the label. */
   labelTooltip?: string;
   /** Trigger and field size. */
   size?: ComplexSelectorSize;
-  /** Visual trigger style. Ghost matches toolbar buttons. */
+  /**
+   * Visual trigger style. Secondary matches secondary buttons; ghost matches
+   * ghost buttons.
+   */
   variant?: ComplexSelectorVariant;
   /** Icon displayed at the start of the trigger. */
   startIcon?: ReactNode | IconType;
@@ -494,7 +522,7 @@ export function ComplexSelector<Value>({
   const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
   const placeholder = placeholderFromProps ?? t('@astryx.selector.placeholder');
   const effectiveStatusVariant =
-    variant === 'ghost' && statusVariant === 'attached'
+    variant !== 'input' && statusVariant === 'attached'
       ? 'detached'
       : statusVariant;
 
@@ -709,10 +737,11 @@ export function ComplexSelector<Value>({
             // matched a mouse click on the trigger and drew the outline for
             // pointer users too. `focusWithin` here is `:has(:focus-visible)`.
             focusOutlineStyles.focusWithin,
+            variant === 'secondary' && styles.triggerSecondary,
             variant === 'ghost' && styles.triggerGhost,
-            variant === 'ghost' && interactionOverlayStyles.backgroundImage,
+            variant !== 'input' && interactionOverlayStyles.backgroundImage,
             isDisabled && inputWrapperStyles.disabled,
-            variant === 'ghost' && isDisabled && styles.triggerGhostDisabled,
+            variant !== 'input' && isDisabled && styles.triggerGhostDisabled,
             isDisabled && styles.disabled,
             triggerLabel == null && styles.placeholder,
             controlXstyle,

package/src/ContextMenu/ContextMenu.doc.mjs

@@ -143,6 +143,12 @@ export const docs = {
         'When true, right-click shows the native browser context menu instead.',
       default: 'false',
     },
+    {
+      name: 'triggerXstyle',
+      type: 'StyleXStyles | StyleXStyles[]',
+      description:
+        'Styles applied to the trigger wrapper. Accepts `stylex.create()` values, not inline style objects.',
+    },
     {
       name: 'triggerAs',
       type: "'div' | 'span'",

package/src/ContextMenu/ContextMenu.spec.md

@@ -26,6 +26,7 @@ architecture:
     architecture:component-theming-surface,
     architecture:interaction-modality,
     architecture:layer-runtime,
+    architecture:public-component-api,
   ]
 contributing: []
 system_specs: []
@@ -36,17 +37,16 @@ system_specs: []
 ## Intent
 
 ContextMenu presents actions for a caller-provided region in either a
-cursor-positioned pointer menu or a BottomSheet-hosted touch action list. This
-draft records current consumer anatomy, presentation-specific ownership, and
-theming reachability without changing runtime behavior, styling, targets, or
-public API.
+cursor-positioned pointer menu or a BottomSheet-hosted touch action list. The
+record describes current consumer anatomy, presentation-specific ownership, and
+theming reachability.
 
 ## Compatibility and migration
 
-- Released default preserved: `yes`
-- Compatibility class: additive documentation only; runtime, DOM, styling,
-  targets, and public API remain unchanged
-- Controlled/uncontrolled behavior: unchanged
+- Released default: `popover`
+- Compatibility class: compatible behavior correction; public API, defaults,
+  DOM shape, styling, and targets are preserved
+- Controlled/uncontrolled behavior: internally managed open state
 - Migration decision: none
 
 Consumer migration instructions belong in consumer docs and release notes.
@@ -81,16 +81,17 @@ 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                                                                                | Verified current behavior; no new behavior decided |
-| 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                                                                                | Verified current inventory; no target change       |
-| 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                                                                                  | Verified current delegation; no ownership change   |
-| 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                                                                                       | Verified current branches; no behavior change      |
-| 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. Right-click, Shift+F10, long-press invocation and keyboard navigation are unchanged. | `module:DropdownMenu/useMenuPress`; `ContextMenu.test.tsx` press model suite                                   | Proposed; 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. Every invocation path (right-click, Shift+F10, long-press) and the `context-menu` target's placement are unchanged.                                                                                                                      | `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                        |
-| 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.                                                                                                                                                     | Proposed in this change; `ContextMenu.test.tsx` keyboard case; shared `useListFocus` and `useTypeahead` suites | Proposed; verified in jsdom, pending owner review  |
+| 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. 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        |
 
 ### Allowed variation
 
@@ -115,19 +116,21 @@ Consumer props, content modes, and presentation policy remain documented in
 
 ### Transformation and precedence order
 
-- No new presentation-resolution, cursor-position, long-press, item-rendering,
-  or styling precedence rule is introduced.
+- Presentation resolution, cursor positioning, long-press handling, item
+  rendering, and styling keep their current precedence.
 
 ### Performance and resources
 
-- No new loading, listener, measurement, or render constraint is introduced.
+- The component introduces no separate loading, listener, measurement, or render
+  constraint beyond the owners named above.
 
 ## Accessibility contract
 
-This draft does not change ContextMenu's menu and dialog naming, keyboard
-invocation, long-press path, keyboard navigation, item semantics, focus
-return, or dismissal ordering. While a pointer is held in the pointer menu,
-the highlight is DOM focus per `module:DropdownMenu/useMenuPress` AR1.
+ContextMenu keeps its menu and dialog naming, keyboard invocation, long-press
+path, keyboard navigation, item semantics, focus return, and presentation-specific
+dismissal behavior. Pointer-menu Escape requests participate in the shared layer
+stack; while a pointer is held in the pointer menu, the highlight is DOM focus per
+`module:DropdownMenu/useMenuPress` AR1.
 
 - **AR1 — An inline trigger keeps its semantics.** `triggerAs` changes the
   Trigger area's element and box only; it carries no role or `aria-haspopup`
@@ -185,27 +188,28 @@ anchor is positioning infrastructure rather than consumer anatomy.
 - `architecture:component-theming-surface` owns anatomy qualification, local
   target mapping, presentation-specific rows, and delegation rules.
 - `architecture:interaction-modality` owns the shared right-click, keyboard,
-  long-press, pointer, touch, and adaptive-presentation boundaries; this draft
-  changes none of them.
+  long-press, pointer, touch, and adaptive-presentation boundaries.
 - `architecture:layer-runtime` owns the current context-mode `useLayer` host and
-  cursor-anchor positioning. ContextMenu currently retains local outside-click
-  and Escape listeners; touch hosting delegates to BottomSheet.
-- `family:overlay-dismissal` owns shared Escape and platform-close ordering and
-  records ContextMenu and BottomSheet as current local-only adoption gaps. This
-  anatomy backfill does not migrate either path.
+  cursor-anchor positioning. ContextMenu retains local outside-click handling and
+  joins shared Escape ordering through `useLayerDismissal`; touch hosting delegates
+  to BottomSheet.
+- `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
+  owner.
 
 ## 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` and current layer/dismissal architecture records                           | Outside click, Escape, context anchor, sheet  | Documentation claims shared dismissal where current source retains local behavior.                 | `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` |
-| 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` 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` |
+| 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` |
 
 ## Decision log
 
@@ -222,17 +226,11 @@ doors of a context menu without becoming a block that breaks the paragraph.
 `triggerAs` renders the Trigger area as a `span`. The default `div` and its
 `position: relative` are unchanged.
 
-Rejected: a `triggerXstyle` recipe — cannot change the element, and a
-`display: inline` div inside a `<p>` is invalid HTML.
-
-Rejected: a third `contents` value, a span with `display: contents`. A
-box-less wrapper has no rect to measure the cursor anchor from, so the anchor
-falls back to the nearest positioned ancestor — which in running prose is
-usually the page. A mouse user gets the menu at the pointer and a keyboard
-user pressing Shift+F10 gets it at the page corner, and the keyboard path is
-the one with no way around it. A `span` is inline, owns a box, measures
-correctly, and is invisible to layout in every way the prose case cares
-about.
+Rejected: styling a block `div` as inline because it remains invalid inside a
+`<p>`.
+
+Rejected: `display: contents` because a box-less wrapper has no rect for pointer
+or keyboard anchoring.
 
 ## Open questions
 

package/src/ContextMenu/ContextMenu.test.tsx

@@ -8,6 +8,8 @@
  * SYNC: When ContextMenu.tsx changes, update tests to match new behavior
  */
 
+import {useRef, useState} from 'react';
+import {createPortal} from 'react-dom';
 import {describe, it, expect, vi, beforeEach} from 'vitest';
 import {render, screen, fireEvent, act, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
@@ -23,6 +25,32 @@ import {
 } from './index';
 import {DropdownMenuItem} from '../DropdownMenu/DropdownMenuItem';
 import {Divider} from '../Divider';
+import {useLayerDismissal} from '../Layer/useLayerDismissal';
+
+function NestedDismissibleLayer({onDismiss}: {onDismiss: () => void}) {
+  const [isOpen, setIsOpen] = useState(true);
+  const containerRef = useRef<HTMLButtonElement>(null);
+
+  useLayerDismissal({
+    isActive: isOpen,
+    onDismiss: () => {
+      setIsOpen(false);
+      onDismiss();
+    },
+    getContainer: () => containerRef.current,
+  });
+
+  // Portaled outside the menu's DOM, so only the layer depth ContextMenu
+  // provides can rank it above the menu.
+  return isOpen
+    ? createPortal(
+        <button ref={containerRef} type="button">
+          Nested layer
+        </button>,
+        document.body,
+      )
+    : null;
+}
 
 beforeEach(() => {
   HTMLDialogElement.prototype.showModal = vi.fn(function (
@@ -149,6 +177,56 @@ describe('ContextMenu', () => {
     expect(HTMLElement.prototype.showPopover).toHaveBeenCalled();
   });
 
+  it('composes the consumer context-menu handler with menu opening', () => {
+    const onContextMenu = vi.fn();
+    render(
+      <ContextMenu items={[{label: 'Item 1'}]} onContextMenu={onContextMenu}>
+        <div>Right-click me</div>
+      </ContextMenu>,
+    );
+
+    fireEvent.contextMenu(screen.getByText('Right-click me'));
+    expect(onContextMenu).toHaveBeenCalledOnce();
+    expect(HTMLElement.prototype.showPopover).toHaveBeenCalledOnce();
+  });
+
+  it('keeps component-owned opening when a consumer prevents default', () => {
+    render(
+      <ContextMenu
+        items={[{label: 'Item 1'}]}
+        onContextMenu={event => event.preventDefault()}>
+        <div>Right-click me</div>
+      </ContextMenu>,
+    );
+
+    fireEvent.contextMenu(screen.getByText('Right-click me'));
+    expect(HTMLElement.prototype.showPopover).toHaveBeenCalledOnce();
+  });
+
+  it('lets a nested layer consume Escape before the context menu', () => {
+    const onNestedDismiss = vi.fn();
+    render(
+      <ContextMenu
+        menuContent={<NestedDismissibleLayer onDismiss={onNestedDismiss} />}>
+        <div>Right-click me</div>
+      </ContextMenu>,
+    );
+
+    fireEvent.contextMenu(screen.getByText('Right-click me'));
+    const nestedLayer = screen.getByRole('button', {
+      name: 'Nested layer',
+      hidden: true,
+    });
+    nestedLayer.focus();
+    fireEvent.keyDown(nestedLayer, {key: 'Escape'});
+
+    expect(onNestedDismiss).toHaveBeenCalledOnce();
+    expect(HTMLElement.prototype.hidePopover).not.toHaveBeenCalled();
+
+    fireEvent.keyDown(document, {key: 'Escape'});
+    expect(HTMLElement.prototype.hidePopover).toHaveBeenCalledOnce();
+  });
+
   it('opens the real menu content in a BottomSheet when requested', async () => {
     render(
       <ContextMenu
@@ -393,6 +471,60 @@ describe('ContextMenu', () => {
     }
   });
 
+  it('composes consumer touch handlers with long-press detection', () => {
+    vi.useFakeTimers();
+    try {
+      const onTouchStart = vi.fn();
+      render(
+        <ContextMenu
+          items={[{label: 'Item 1'}]}
+          data-testid="ctx"
+          onTouchStart={onTouchStart}>
+          <div>Long-press me</div>
+        </ContextMenu>,
+      );
+
+      fireEvent.touchStart(screen.getByTestId('ctx'), {
+        touches: [{clientX: 20, clientY: 20}],
+      });
+      expect(onTouchStart).toHaveBeenCalledOnce();
+
+      act(() => {
+        vi.advanceTimersByTime(500);
+      });
+      expect(HTMLElement.prototype.showPopover).toHaveBeenCalledOnce();
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it('clears a pending long-press when a consumer prevents default on touch end', () => {
+    vi.useFakeTimers();
+    try {
+      render(
+        <ContextMenu
+          items={[{label: 'Item 1'}]}
+          data-testid="ctx"
+          onTouchEnd={event => event.preventDefault()}>
+          <div>Long-press me</div>
+        </ContextMenu>,
+      );
+
+      const trigger = screen.getByTestId('ctx');
+      fireEvent.touchStart(trigger, {
+        touches: [{clientX: 20, clientY: 20}],
+      });
+      fireEvent.touchEnd(trigger);
+
+      act(() => {
+        vi.advanceTimersByTime(500);
+      });
+      expect(HTMLElement.prototype.showPopover).not.toHaveBeenCalled();
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
   it('suppresses native text selection on the long-press trigger', () => {
     const source = readFileSync(
       'packages/core/src/ContextMenu/ContextMenu.tsx',
@@ -1103,7 +1235,6 @@ describe('ContextMenuGroup', () => {
     // Three public surfaces alias this component at once. An alias that
     // re-exports without the semantics would pass a render test and fail a
     // screen reader.
-    const user = userEvent.setup();
     render(
       <ContextMenu
         menuContent={