@astryxdesign/core 0.7.5 → 0.7.6-canary.0d71e8d

package/src/ComplexSelector/ComplexSelector.test.tsx

@@ -14,6 +14,8 @@ import {beforeEach, describe, expect, it, vi} from 'vitest';
 import {act, fireEvent, render, screen, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {Button} from '../Button/Button';
+import * as stylex from '@stylexjs/stylex';
+import {focusVars} from '../theme/tokens.stylex';
 import {ComplexSelector, type ComplexSelectorHandle} from './ComplexSelector';
 
 const originalMatches = HTMLElement.prototype.matches;
@@ -755,6 +757,43 @@ describe('ComplexSelector trigger semantics', () => {
     expect(trigger).toHaveAttribute('aria-labelledby', 'trip-heading');
   });
 
+  // WCAG 2.5.3 Label in Name (axe `label-content-name-mismatch`) applies to
+  // controls named from their content. A button named by `aria-labelledby`
+  // while showing the chosen value failed it, and hid the value from the
+  // accessibility tree. As a combobox the label is the name and the text it
+  // shows is the value, as on `Selector`.
+  it('names the trigger by its label and shows the chosen value as its content', () => {
+    render(
+      <ComplexSelector
+        label="Supplier"
+        value="1"
+        onChange={() => {}}
+        triggerLabel="Acme Ltd">
+        {() => <p>Choose a supplier</p>}
+      </ComplexSelector>,
+    );
+    // A combobox takes no name from its content, so the value is not in the
+    // name and Label in Name has nothing to compare it with.
+    expect(screen.queryByRole('button', {name: /Supplier/})).toBeNull();
+    const trigger = screen.getByRole('combobox', {name: 'Supplier'});
+    expect(trigger).toHaveTextContent('Acme Ltd');
+    expect(trigger).toHaveAccessibleName('Supplier');
+  });
+
+  it('keeps the field label as the name when the trigger shows the placeholder', () => {
+    render(
+      <ComplexSelector
+        label="Supplier"
+        value=""
+        onChange={() => {}}
+        placeholder="Choose a supplier">
+        {() => <p>Pick one</p>}
+      </ComplexSelector>,
+    );
+    const trigger = screen.getByRole('combobox', {name: 'Supplier'});
+    expect(trigger).toHaveTextContent('Choose a supplier');
+  });
+
   it('spreads the combobox role, required, and disabled state onto a caller control', async () => {
     const user = userEvent.setup();
     const onClick = vi.fn();
@@ -1019,5 +1058,114 @@ describe('ComplexSelector onOpenChange', () => {
         container.querySelector('.astryx-field-status'),
       ).not.toBeInTheDocument();
     });
+
+    // family:input-fields FR8: tooltip placement keeps the message reachable.
+    it('puts the tooltip-placement message in a focusable info-tip that describes the trigger', async () => {
+      const user = userEvent.setup();
+      render(
+        <ComplexSelector
+          label="Filter"
+          value={[]}
+          status={{type: 'error', message: 'Required'}}
+          statusVariant="tooltip">
+          {() => <button type="button">Apply</button>}
+        </ComplexSelector>,
+      );
+      const trigger = screen.getByRole('combobox', {name: 'Filter'});
+      const tip = screen.getByRole('button', {name: 'Error details'});
+      // Every id the trigger points at exists, and the status message is
+      // among them.
+      const ids = trigger.getAttribute('aria-describedby')?.split(' ') ?? [];
+      expect(ids.length).toBeGreaterThan(0);
+      for (const id of ids) {
+        expect(document.getElementById(id)).not.toBeNull();
+      }
+      expect(trigger).toHaveAccessibleDescription('Required');
+
+      // Focusing the info-tip reveals the message without opening the popup.
+      await user.tab();
+      await user.tab();
+      expect(tip).toHaveFocus();
+      expect(tip).toHaveAccessibleDescription('Required');
+      await user.click(tip);
+      expect(trigger).toHaveAttribute('aria-expanded', 'false');
+    });
+
+    // architecture:interaction-modality INV3: the info-tip rings itself, so
+    // the control box rings only for the trigger, not for any focused child.
+    it('rings the control box for the trigger only, not for the info-tip', () => {
+      render(
+        <ComplexSelector
+          label="Filter"
+          value={[]}
+          status={{type: 'error', message: 'Required'}}
+          statusVariant="tooltip">
+          {() => <button type="button">Apply</button>}
+        </ComplexSelector>,
+      );
+      const box = screen.getByRole('combobox', {name: 'Filter'}).parentElement!;
+      // The same declarations as the shared any-descendant ring, with null
+      // defaults so only its `:has(:focus-visible)` atoms are compared (the
+      // default atoms are shared with the combobox-only ring).
+      /* eslint-disable @astryx/focus-outline-shared -- a test oracle that
+         mirrors the shared ring's conditional atoms; it paints nothing. */
+      const anyDescendantRing = stylex.create({
+        ring: {
+          outlineWidth: {
+            default: null,
+            ':has(:focus-visible)': focusVars['--focus-outline-width'],
+          },
+          outlineStyle: {
+            default: null,
+            ':has(:focus-visible)': focusVars['--focus-outline-style'],
+          },
+        },
+      });
+      /* eslint-enable @astryx/focus-outline-shared */
+      const anyFocusAtoms = stylex
+        .props(anyDescendantRing.ring)
+        .className!.split(' ')
+        .filter(name => name.includes('x') && !name.includes('__'));
+      expect(anyFocusAtoms.length).toBeGreaterThan(0);
+      for (const name of anyFocusAtoms) {
+        expect(box).not.toHaveClass(name);
+      }
+    });
+
+    it('opens no popup when the info-tip message bubble is pressed', async () => {
+      const user = userEvent.setup();
+      render(
+        <ComplexSelector
+          label="Filter"
+          value={[]}
+          status={{type: 'error', message: 'Required'}}
+          statusVariant="tooltip">
+          {() => <button type="button">Apply</button>}
+        </ComplexSelector>,
+      );
+      const trigger = screen.getByRole('combobox', {name: 'Filter'});
+      const tip = screen.getByRole('button', {name: 'Error details'});
+      act(() => {
+        tip.focus();
+      });
+      const bubble = await screen.findByRole('tooltip', {hidden: true});
+      await user.click(bubble);
+      expect(trigger).toHaveAttribute('aria-expanded', 'false');
+    });
+
+    it('keeps the attached message box and adds no info-tip', () => {
+      render(
+        <ComplexSelector
+          label="Filter"
+          value={[]}
+          status={{type: 'error', message: 'Required'}}>
+          {() => <button type="button">Apply</button>}
+        </ComplexSelector>,
+      );
+      expect(screen.queryByRole('button', {name: 'Error details'})).toBeNull();
+      expect(
+        screen.getByRole('combobox', {name: 'Filter'}),
+      ).toHaveAccessibleDescription('Required');
+    });
   });
 });

package/src/ComplexSelector/ComplexSelector.tsx

@@ -45,6 +45,7 @@ import {layerAnimations} from '../Layer/layerAnimations.stylex';
 import type {LayerAlignment, LayerPlacement} from '../Layer/useLayer';
 import {usePopover} from '../Popover/usePopover';
 import {useResolvedRequired} from '../hooks/useResolvedRequired';
+import {useInputStatusIcon} from '../hooks/useInputStatusIcon';
 import {
   colorVars,
   durationVars,
@@ -56,15 +57,22 @@ import {
   typographyVars,
   typeScaleVars,
 } from '../theme/tokens.stylex';
+import {focusOutlineStyles} from '../utils/focusOutline.stylex';
 import {isRenderable, mergeProps} from '../utils';
 import {composeEventHandlers} from '../utils/composeEventHandlers';
-import {focusOutlineStyles} from '../utils/focusOutline.stylex';
 import {interactionOverlayStyles} from '../utils/interactionOverlay.stylex';
 import {usePressFeedback} from '../hooks/usePressFeedback';
 import type {SizeValue} from '../utils/types';
 import {themeProps} from '../utils/themeProps';
 
 const styles = stylex.create({
+  // The tooltip-placement status info-tip sits beside the chevron and keeps
+  // its size when the trigger text is long.
+  statusTip: {
+    display: 'inline-flex',
+    alignItems: 'center',
+    flexShrink: 0,
+  },
   triggerContainer: {
     position: 'relative',
     display: 'flex',
@@ -458,6 +466,11 @@ export interface ComplexSelectorProps<Value> extends Omit<
   'data-testid'?: string;
 }
 
+/** Keeps a click from reaching the control box's open-the-popup handler. */
+function stopPropagation(event: React.MouseEvent) {
+  event.stopPropagation();
+}
+
 /**
  * A selector shell for rich, custom selection surfaces.
  *
@@ -557,10 +570,24 @@ export function ComplexSelector<Value>({
   const contentId = useId();
   const descriptionId = useId();
   const statusMessageId = useId();
+  // With `tooltip` placement Field renders no message box, so the status
+  // lives in an info-tip button on the trigger row (family:input-fields FR8).
+  // Only that placement renders an on-field status affordance here.
+  const isTooltipStatus = effectiveStatusVariant === 'tooltip';
+  const {statusIcon: statusTip, describedBy: statusTipDescribedBy} =
+    useInputStatusIcon({
+      status: isTooltipStatus ? status : undefined,
+      statusVariant: effectiveStatusVariant,
+      size: 'sm',
+    });
   const ariaDescribedBy =
     [
       description ? descriptionId : null,
-      status?.message ? statusMessageId : null,
+      isTooltipStatus
+        ? statusTipDescribedBy
+        : status?.message
+          ? statusMessageId
+          : null,
     ]
       .filter((id): id is string => id != null)
       .join(' ') || undefined;
@@ -809,8 +836,10 @@ export function ComplexSelector<Value>({
             // The ring belongs to the wrapper (the focusable `<button>` sits
             // inside it), but it must still be a KEYBOARD ring: `:focus-within`
             // matched a mouse click on the trigger and drew the outline for
-            // pointer users too. `focusWithin` here is `:has(:focus-visible)`.
-            focusOutlineStyles.focusWithin,
+            // pointer users too. It keys off the trigger alone, so the status
+            // info-tip beside it rings itself and the box does not ring too
+            // (architecture:interaction-modality INV3).
+            focusOutlineStyles.focusWithinCombobox,
             variant === 'secondary' && styles.triggerSecondary,
             variant === 'ghost' && styles.triggerGhost,
             variant !== 'input' && interactionOverlayStyles.backgroundImage,
@@ -859,6 +888,14 @@ export function ComplexSelector<Value>({
           {...stylex.props(styles.trigger)}>
           <span {...stylex.props(styles.triggerText)}>{triggerContent}</span>
         </button>
+        {isRenderable(statusTip) && (
+          // The info-tip is its own control: a press on it, or on its message
+          // bubble (portaled, so outside this span in the DOM but inside it in
+          // React), shows the message without opening the popup.
+          <span onClick={stopPropagation} {...stylex.props(styles.statusTip)}>
+            {statusTip}
+          </span>
+        )}
         {isBusy && <Spinner size="sm" aria-hidden="true" />}
         <Icon
           icon="chevronDown"

package/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
 

package/src/ContextMenu/ContextMenu.test.tsx

@@ -1320,6 +1320,41 @@ describe('ContextMenu keyboard access for menuitemradio/menuitemcheckbox (#3829)
   });
 });
 
+describe('ContextMenu data-driven submenu inside a section', () => {
+  it('renders a submenu row for an item with nested items inside a section', () => {
+    render(
+      <ContextMenu
+        items={[
+          {
+            type: 'section',
+            title: 'Organize',
+            items: [
+              {label: 'Rename', onClick: () => {}},
+              {
+                label: 'Move to',
+                items: [
+                  {label: 'Folder A', onClick: () => {}},
+                  {label: 'Folder B', onClick: () => {}},
+                ],
+              },
+            ],
+          },
+        ]}>
+        <div>Right-click me</div>
+      </ContextMenu>,
+    );
+    fireEvent.contextMenu(screen.getByText('Right-click me'));
+    const trigger = screen.getByRole('menuitem', {
+      name: /Move to/,
+      hidden: true,
+    });
+    expect(trigger).toHaveAttribute('aria-haspopup', 'menu');
+    expect(
+      screen.getByRole('menuitem', {name: 'Folder A', hidden: true}),
+    ).toBeInTheDocument();
+  });
+});
+
 describe('ContextMenu press model', () => {
   const touch = {pointerType: 'touch', pointerId: 1};
   const item = (name: string) =>