@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/src/ContextMenu/ContextMenu.doc.mjs

@@ -132,7 +132,7 @@ export const docs = {
       name: 'presentation',
       type: "'popover' | 'bottom-sheet' | 'adaptive'",
       description:
-        'Presentation policy. `popover` opens at the pointer position, `bottom-sheet` always uses an action sheet, and `adaptive` uses the BottomSheet at 768px and below when the primary pointer is coarse.',
+        'Presentation policy. `popover` opens at the pointer position, `bottom-sheet` always uses an action sheet, and `adaptive` uses the BottomSheet on a compact touch screen: a coarse primary pointer, and a viewport narrower than the theme `md` breakpoint (768px by default) or shorter than 500px.',
       default: "'popover'",
     },
     {

package/src/ContextMenu/ContextMenu.spec.md

@@ -43,11 +43,15 @@ theming reachability.
 
 ## Compatibility and migration
 
-- Released default: `popover`
-- Compatibility class: compatible behavior correction; public API, defaults,
-  DOM shape, styling, and targets are preserved
+- 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
 - Controlled/uncontrolled behavior: internally managed open state
-- Migration decision: none
+- Migration decision: `spec:AST-094` FR25 (a caller that needs the released
+  menu under a finger passes `presentation="popover"`)
 
 Consumer migration instructions belong in consumer docs and release notes.
 
@@ -55,11 +59,12 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 **Owns**
 
-- The Trigger area's context-menu invocation wiring.
+- The Trigger area's context-menu invocation wiring, through the public
+  headless context menu (FR10).
 - The alternative Pointer menu surface and Touch menu surface and their shared
   current `context-menu` target.
-- Cursor-anchor placement and current open-state coordination across the two
-  presentation paths.
+- Cursor-anchor placement across the two presentation paths; open state is the
+  factory's (FR10).
 
 **Does not own / non-goals**
 
@@ -81,17 +86,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. 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        |
+| 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                                             |
 
 ### Allowed variation
 
@@ -190,8 +196,9 @@ 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. ContextMenu retains local outside-click handling and
-  joins shared Escape ordering through `useLayerDismissal`; touch hosting delegates
+  cursor-anchor positioning. The factory closes the menu on an outside press
+  (`spec:AST-107` FR8; FR10), and ContextMenu 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
@@ -200,16 +207,17 @@ 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` |
-| 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` |
+| 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` |
 
 ## Decision log
 

package/src/ContextMenu/ContextMenu.test.tsx

@@ -11,7 +11,15 @@
 import {useRef, useState} from 'react';
 import {createPortal} from 'react-dom';
 import {describe, it, expect, vi, beforeAll, beforeEach} from 'vitest';
-import {render, screen, fireEvent, act, waitFor} from '@testing-library/react';
+import {
+  render,
+  screen,
+  fireEvent,
+  act,
+  waitFor,
+  cleanup,
+  createEvent,
+} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {readFileSync} from 'node:fs';
 import {ContextMenu} from './ContextMenu';
@@ -28,6 +36,7 @@ import {DropdownMenuSubMenu} from '../DropdownMenu/DropdownMenuSubMenu';
 import {Divider} from '../Divider';
 import {useLayerDismissal} from '../Layer/useLayerDismissal';
 import {warmMenuBottomSheet} from '../DropdownMenu/__tests__/warmMenuBottomSheet';
+import {COMPACT_TOUCH_PRESENTATION_QUERY} from '../hooks/useAdaptivePresentation';
 
 // The touch sheet is loaded lazily; resolve its modules once up front, so
 // ContextMenu's own lazy sheet renders within the cases' waitFor.
@@ -295,21 +304,48 @@ describe('ContextMenu', () => {
     );
   });
 
-  it('keeps only the top content padding in a menu BottomSheet', () => {
-    const source = readFileSync(
-      'packages/core/src/DropdownMenu/MenuBottomSheet.tsx',
-      'utf8',
-    );
-
-    expect(source).toContain('paddingBlockStart={4}');
-    expect(source).toContain('paddingBlockEnd={0}');
-  });
+  for (const mode of ['items', 'compound'] as const) {
+    it(`insets a ${mode} menu sheet itself and publishes the inset to its rows`, async () => {
+      render(
+        mode === 'items' ? (
+          <ContextMenu presentation="bottom-sheet" items={[{label: 'Edit'}]}>
+            <div>Right-click me</div>
+          </ContextMenu>
+        ) : (
+          <ContextMenu
+            presentation="bottom-sheet"
+            menuContent={<DropdownMenuItem label="Edit" />}>
+            <div>Right-click me</div>
+          </ContextMenu>
+        ),
+      );
+      fireEvent.contextMenu(screen.getByText('Right-click me'));
+      const content = await waitFor(() => {
+        const element = document.querySelector<HTMLElement>(
+          'dialog .astryx-context-menu',
+        );
+        expect(element).not.toBeNull();
+        return element as HTMLElement;
+      });
+      // No Section wrapper: the menu element keeps the sheet's 16px top and
+      // 4px side inset plus its own 4px, and publishes the padding it applies.
+      expect(content.parentElement?.closest('.astryx-section')).toBeNull();
+      expect(content).toHaveStyle({
+        paddingTop: 'calc(var(--spacing-4) + var(--spacing-1))',
+        paddingInline: 'calc(var(--spacing-1) + var(--spacing-1))',
+        '--container-padding-block-start':
+          'calc(var(--spacing-4) + var(--spacing-1))',
+        '--container-padding-inline-start':
+          'calc(var(--spacing-1) + var(--spacing-1))',
+      });
+    });
+  }
 
   it('uses the BottomSheet for adaptive presentation on compact touch', async () => {
     vi.stubGlobal(
       'matchMedia',
       vi.fn().mockImplementation((query: string) => ({
-        matches: query === '(max-width: 768px) and (pointer: coarse)',
+        matches: query === COMPACT_TOUCH_PRESENTATION_QUERY,
         media: query,
         onchange: null,
         addEventListener: vi.fn(),
@@ -1402,3 +1438,145 @@ describe('ContextMenu inline trigger (triggerAs)', () => {
     expect(screen.getByTestId('area').tagName).toBe('DIV');
   });
 });
+
+describe('ContextMenu outside dismissal', () => {
+  const finger = (pointerId: number) => ({pointerType: 'touch', pointerId});
+
+  // Holds a finger on the trigger until the long-press opens the menu. Only
+  // the long-press delay is faked.
+  function longPress(trigger: HTMLElement, pointerId: number) {
+    vi.useFakeTimers({toFake: ['setTimeout', 'clearTimeout']});
+    try {
+      fireEvent.pointerDown(trigger, finger(pointerId));
+      fireEvent.touchStart(trigger, {touches: [{clientX: 20, clientY: 20}]});
+      act(() => {
+        vi.advanceTimersByTime(500);
+      });
+    } finally {
+      vi.useRealTimers();
+    }
+  }
+
+  // What a browser sends after a touch: the lift, then compatibility mouse
+  // events aimed at the element the finger held.
+  function lift(target: HTMLElement, pointerId: number) {
+    fireEvent.pointerUp(target, finger(pointerId));
+    fireEvent.touchEnd(target);
+    fireEvent.mouseDown(target);
+    fireEvent.mouseUp(target);
+    fireEvent.click(target);
+  }
+
+  function renderMenu(onOpenChange: (isOpen: boolean) => void) {
+    render(
+      <>
+        <ContextMenu
+          items={[{label: 'Cut'}, {label: 'Copy'}]}
+          data-testid="ctx"
+          onOpenChange={onOpenChange}>
+          <div>Long-press me</div>
+        </ContextMenu>
+        <button type="button">Outside</button>
+      </>,
+    );
+    return {
+      trigger: screen.getByTestId('ctx'),
+      outside: screen.getByRole('button', {name: 'Outside'}),
+    };
+  }
+
+  it('the long press that opened the menu does not close it, mid-hold or as it lifts; the next press outside does', () => {
+    const onOpenChange = vi.fn<(isOpen: boolean) => void>();
+    const {trigger, outside} = renderMenu(onOpenChange);
+    longPress(trigger, 1);
+    expect(onOpenChange).toHaveBeenLastCalledWith(true);
+    // iOS: a compatibility mousedown while the finger is still down.
+    fireEvent.mouseDown(trigger);
+    expect(onOpenChange).toHaveBeenLastCalledWith(true);
+    // Chromium: the compatibility events that follow the lift.
+    lift(trigger, 1);
+    expect(onOpenChange).not.toHaveBeenCalledWith(false);
+    // A new press is a new gesture: a mouse press outside closes the menu.
+    fireEvent.pointerDown(outside, {pointerType: 'mouse', pointerId: 9});
+    fireEvent.mouseDown(outside);
+    expect(onOpenChange).toHaveBeenLastCalledWith(false);
+  });
+
+  it('a finger long press that opens the menu through a pointer contextmenu (Chromium) does not close it as it lifts', () => {
+    const onOpenChange = vi.fn<(isOpen: boolean) => void>();
+    const {trigger, outside} = renderMenu(onOpenChange);
+    fireEvent.pointerDown(trigger, finger(8));
+    const contextmenu = createEvent.contextMenu(trigger, {
+      clientX: 20,
+      clientY: 15,
+      detail: 1,
+    });
+    Object.defineProperty(contextmenu, 'pointerType', {value: 'touch'});
+    fireEvent(trigger, contextmenu);
+    expect(onOpenChange).toHaveBeenLastCalledWith(true);
+    lift(trigger, 8);
+    expect(onOpenChange).not.toHaveBeenCalledWith(false);
+    // A right-click is not a finger: its gesture's next mousedown, outside,
+    // closes the menu.
+    fireEvent.pointerDown(trigger, {pointerType: 'mouse', pointerId: 1});
+    fireEvent.contextMenu(trigger, {clientX: 20, clientY: 15, detail: 1});
+    fireEvent.mouseDown(outside);
+    expect(onOpenChange).toHaveBeenLastCalledWith(false);
+  });
+
+  it('a long press that moves the open menu keeps it open as it lifts', () => {
+    const onOpenChange = vi.fn<(isOpen: boolean) => void>();
+    const {trigger} = renderMenu(onOpenChange);
+    fireEvent.contextMenu(trigger, {clientX: 50, clientY: 15, detail: 1});
+    expect(onOpenChange).toHaveBeenLastCalledWith(true);
+    longPress(trigger, 2);
+    lift(trigger, 2);
+    expect(onOpenChange).not.toHaveBeenCalledWith(false);
+  });
+
+  it('a tap outside closes the menu through its compatibility mousedown; a scroll that starts outside leaves it open', () => {
+    const onOpenChange = vi.fn<(isOpen: boolean) => void>();
+    const {trigger, outside} = renderMenu(onOpenChange);
+    fireEvent.contextMenu(trigger, {clientX: 50, clientY: 15, detail: 1});
+    // The browser takes this finger for a scroll: no compatibility events.
+    fireEvent.pointerDown(outside, finger(3));
+    fireEvent.pointerCancel(outside, finger(3));
+    expect(onOpenChange).toHaveBeenLastCalledWith(true);
+    fireEvent.pointerDown(outside, finger(4));
+    lift(outside, 4);
+    expect(onOpenChange).toHaveBeenLastCalledWith(false);
+  });
+
+  it('a mouse press or a pen press outside closes the menu at the press', () => {
+    for (const pointerType of ['mouse', 'pen']) {
+      const onOpenChange = vi.fn<(isOpen: boolean) => void>();
+      const {trigger, outside} = renderMenu(onOpenChange);
+      fireEvent.contextMenu(trigger, {clientX: 50, clientY: 15, detail: 1});
+      fireEvent.pointerDown(outside, {pointerType, pointerId: 7});
+      fireEvent.mouseDown(outside);
+      expect(onOpenChange).toHaveBeenLastCalledWith(false);
+      cleanup();
+    }
+  });
+
+  it('presses that send no mousedown leave the menu open, as before: a cancelled pointerdown, a finger drag, a second finger', () => {
+    const onOpenChange = vi.fn<(isOpen: boolean) => void>();
+    const {trigger, outside} = renderMenu(onOpenChange);
+    fireEvent.contextMenu(trigger, {clientX: 50, clientY: 15, detail: 1});
+    // A control that cancels its pointerdown (a NumberInput stepper, a
+    // resize handle): the browser sends no mousedown.
+    fireEvent.pointerDown(outside, {pointerType: 'mouse', pointerId: 1});
+    fireEvent.pointerUp(outside, {pointerType: 'mouse', pointerId: 1});
+    // A finger drag on a surface that does not pan (a Slider), lifted.
+    fireEvent.pointerDown(outside, finger(5));
+    fireEvent.pointerMove(outside, finger(5));
+    fireEvent.pointerUp(outside, finger(5));
+    // A second finger's tap.
+    fireEvent.pointerDown(outside, finger(6));
+    fireEvent.pointerDown(outside, finger(7));
+    fireEvent.pointerUp(outside, finger(7));
+    fireEvent.pointerCancel(outside, finger(6));
+    expect(onOpenChange).toHaveBeenLastCalledWith(true);
+    expect(onOpenChange).not.toHaveBeenCalledWith(false);
+  });
+});

package/src/ContextMenu/ContextMenu.tsx

@@ -52,7 +52,9 @@ import {Icon} from '../Icon';
 import {useLayer} from '../Layer/useLayer';
 import {LayerDepthProvider} from '../Layer/LayerDepthContext';
 import {useLayerDismissal} from '../Layer/useLayerDismissal';
+import {currentGesture} from '../Layer/gestureCounter';
 import {MenuBottomSheetActionList} from '../DropdownMenu/MenuBottomSheetActionList';
+import {menuBottomSheetStyles} from '../DropdownMenu/menuBottomSheet.stylex';
 import {renderDropdownItems} from '../DropdownMenu/renderDropdownItems';
 import {
   DropdownMenuContext,
@@ -175,6 +177,18 @@ const styles = stylex.create({
     outline: 'none',
     userSelect: 'none',
   },
+  // The menu's own inset inside the sheet content box (menuBottomSheetStyles
+  // .content): the 16px / 4px the sheet keeps plus the menu's 4px padding.
+  sheetMenuInset: {
+    paddingBlockStart: `calc(${spacingVars['--spacing-4']} + ${spacingVars['--spacing-1']})`,
+    paddingBlockEnd: spacingVars['--spacing-1'],
+    paddingInline: `calc(${spacingVars['--spacing-1']} + ${spacingVars['--spacing-1']})`,
+    // Bleeding rows read the padding this element applies.
+    '--container-padding-block-start': `calc(${spacingVars['--spacing-4']} + ${spacingVars['--spacing-1']})`,
+    '--container-padding-block-end': spacingVars['--spacing-1'],
+    '--container-padding-inline-start': `calc(${spacingVars['--spacing-1']} + ${spacingVars['--spacing-1']})`,
+    '--container-padding-inline-end': `calc(${spacingVars['--spacing-1']} + ${spacingVars['--spacing-1']})`,
+  },
   sheetHeader: {
     display: 'flex',
     flexDirection: 'row',
@@ -354,6 +368,11 @@ export function ContextMenu({
   // Element focused before the menu opened, restored when it closes so focus
   // does not fall to <body> after Escape or outside-click dismissal.
   const triggerFocusRef = useRef<HTMLElement | null>(null);
+  // The gesture of the finger press that opened the menu (`Layer/
+  // gestureCounter`), null when a mouse or the keyboard opened it: the
+  // browser's compatibility mouse events for that same press are not presses
+  // outside.
+  const openingGestureRef = useRef<number | null>(null);
 
   const [isOpen, setIsOpen] = useState(false);
   const [submenuPath, setSubmenuPath] = useState<ContextMenuItemData[]>([]);
@@ -461,7 +480,10 @@ export function ContextMenu({
   // Dismiss on any click outside the menu. We use popover="manual" (not
   // "auto") because the native light-dismiss treats the mouseup from the
   // opening right-click as a dismiss event. Handling it ourselves via
-  // mousedown avoids that race.
+  // mousedown avoids that race. A touch's compatibility mousedown for the
+  // press that opened the menu (sent mid-hold by iOS, or as a long press
+  // lifts by Chromium) belongs to that press's gesture, so it is not read as
+  // a press outside; any later press is a new gesture and closes as before.
   useEffect(() => {
     if (!isOpen || usesBottomSheet) {
       return;
@@ -478,6 +500,9 @@ export function ContextMenu({
         return;
       }
       judged.add(e);
+      if (currentGesture() === openingGestureRef.current) {
+        return;
+      }
       if (menu && !menu.contains(e.target as Node)) {
         closeMenu();
       }
@@ -589,6 +614,14 @@ export function ContextMenu({
       const localX = isKeyboardInvoked || !rect ? 0 : e.clientX - rect.left;
       const localY =
         isKeyboardInvoked || !rect ? (rect?.height ?? 0) : e.clientY - rect.top;
+      // A finger's long press reaches here as a pointer `contextmenu` where
+      // the browser sends one (Chromium); its compatibility mousedown then
+      // belongs to the opening press. A mouse or the keyboard opens without
+      // one, so every later mousedown is a press outside.
+      openingGestureRef.current =
+        (e.nativeEvent as Partial<PointerEvent>).pointerType === 'touch'
+          ? currentGesture()
+          : null;
       openAtLocalPoint(localX, localY, e.currentTarget as HTMLElement);
     },
     [isDisabled, openAtLocalPoint, getAnchorBaseRect],
@@ -610,6 +643,9 @@ export function ContextMenu({
     onLongPress: useCallback(
       (point: {x: number; y: number}) => {
         const rect = getAnchorBaseRect();
+        // The finger is still down: the compatibility mousedown iOS sends
+        // mid-hold, or Chromium as it lifts, belongs to this press.
+        openingGestureRef.current = currentGesture();
         openAtLocalPoint(
           rect ? point.x - rect.left : point.x,
           rect ? point.y - rect.top : point.y,
@@ -705,7 +741,13 @@ export function ContextMenu({
       {...mergeProps(
         themeProps('context-menu'),
         stylex.props(
-          usesBottomSheet ? styles.sheetMenu : styles.menu,
+          usesBottomSheet
+            ? [
+                styles.sheetMenu,
+                menuBottomSheetStyles.content,
+                styles.sheetMenuInset,
+              ]
+            : styles.menu,
           !usesBottomSheet &&
             (hasOverflow ? styles.touchPanYPinchZoom : styles.touchPinchZoom),
           xstyle,
@@ -721,6 +763,24 @@ export function ContextMenu({
     </div>
   );
 
+  // The root view's heading stands alone; a sub-menu's sits in a row with its
+  // back button.
+  const sheetViewHeading = (
+    <Heading
+      ref={setSheetHeadingRef}
+      level={3}
+      tabIndex={-1}
+      xstyle={[
+        styles.sheetViewHeading,
+        submenuPath.length === 0 && [
+          styles.sheetRootHeading,
+          menuBottomSheetStyles.headingAlone,
+        ],
+      ]}>
+      {currentTitle}
+    </Heading>
+  );
+
   const renderedBottomSheetContent =
     itemsProp !== undefined ? (
       <div
@@ -729,12 +789,17 @@ export function ContextMenu({
         tabIndex={0}
         {...mergeProps(
           themeProps('context-menu'),
-          stylex.props(styles.sheetMenu, xstyle),
+          stylex.props(
+            styles.sheetMenu,
+            menuBottomSheetStyles.content,
+            styles.sheetMenuInset,
+            xstyle,
+          ),
           className,
           style,
         )}>
-        <div {...stylex.props(styles.sheetHeader)}>
-          {submenuPath.length > 0 && (
+        {submenuPath.length > 0 ? (
+          <div {...stylex.props(styles.sheetHeader)}>
             <Button
               label={backLabel}
               variant="ghost"
@@ -745,18 +810,11 @@ export function ContextMenu({
               isIconOnly
               onClick={() => setSubmenuPath(path => path.slice(0, -1))}
             />
-          )}
-          <Heading
-            ref={setSheetHeadingRef}
-            level={3}
-            tabIndex={-1}
-            xstyle={[
-              styles.sheetViewHeading,
-              submenuPath.length === 0 && styles.sheetRootHeading,
-            ]}>
-            {currentTitle}
-          </Heading>
-        </div>
+            {sheetViewHeading}
+          </div>
+        ) : (
+          sheetViewHeading
+        )}
         <MenuBottomSheetActionList
           items={currentItems}
           onSelect={handleBottomSheetSelect}

package/src/ContextMenu/__tests__/ContextMenuAudit.a11y.chromium.spec.ts

@@ -1,4 +1,5 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
+// @pr-a11y audit ContextMenu
 
 /**
  * @file ContextMenuAudit.a11y.chromium.spec.ts

package/src/ContextMenu/__tests__/ContextMenuCursorAnchor.a11y.browser.spec.ts

@@ -1,4 +1,5 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
+// @pr-a11y release-only
 
 /**
  * @file ContextMenuCursorAnchor.a11y.browser.spec.ts