@astryxdesign/core 0.5.2-canary.c9c8564 → 0.5.2-canary.e03511b

package/src/ComplexSelector/ComplexSelector.spec.md

@@ -0,0 +1,189 @@
+---
+schema_version: 1
+template_version: 3
+kind: component
+id: component:ComplexSelector
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+owners: [cixzhang]
+review_triggers: [theming]
+verified_by:
+  [
+    packages/core/src/ComplexSelector/ComplexSelector.test.tsx,
+    packages/core/src/Field/Field.test.tsx,
+    packages/core/src/Icon/Icon.test.tsx,
+    scripts/check-knowledge.mjs,
+  ]
+families: [family:overlay-dismissal]
+design_specs: []
+architecture:
+  [architecture:component-theming-surface, architecture:layer-runtime]
+contributing: []
+system_specs: []
+---
+
+# ComplexSelector component contract
+
+## Intent
+
+ComplexSelector renders a field-owned shell, an owned trigger, and a dialog
+popup for caller-provided rich selection content. This draft records current
+consumer anatomy and theming ownership without changing runtime behavior,
+styling, targets, or public API.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`
+- Compatibility class: additive documentation only; runtime, DOM, styling,
+  targets, and public API remain unchanged
+- Controlled/uncontrolled behavior: unchanged
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- The trigger and its current `complex-selector` target.
+- The trailing indicator icon and its current
+  `complex-selector-indicator-icon` target.
+- The painted popup surface and its current `complex-selector-popup` target.
+
+**Does not own / non-goals**
+
+- Field-shell presentation — rendered by Field and themed through Field's
+  current `field` target.
+- General Icon presentation — rendered by Icon for semantic icon names and icon
+  component types and themed through Icon's current `icon` target.
+- Arbitrary ReactNode content supplied through `startIcon` — rendered directly
+  and owned by the product callsite.
+- The selector-specific structure supplied through `children` — owned by the
+  product callsite.
+- Shared layer lifecycle, positioning, and dismissal behavior.
+
+## Public concepts
+
+No new public concept is introduced. Consumer props and usage remain documented
+in `ComplexSelector.doc.mjs`.
+
+## Behavioral and layout contract
+
+| ID  | Candidate invariant                                                                                                                                                                       | Basis                           | Draft review state                                 |
+| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | -------------------------------------------------- |
+| FR1 | The current render contains a Field, Trigger, Indicator icon, and mounted Popup; one optional start slot may contain either an Icon-rendered start icon or caller-rendered start content. | Current source, docs, and tests | Verified current behavior; no new behavior decided |
+| FR2 | Trigger, Indicator icon, and Popup carry `complex-selector`, `complex-selector-indicator-icon`, and `complex-selector-popup`, respectively.                                               | Current source, docs, and tests | Verified current behavior; no target change        |
+| FR3 | Field delegates to Field's `field` target, and a semantic name or icon component in the start slot delegates to Icon's `icon` target.                                                     | Current source and owner tests  | Verified current behavior; no target change        |
+| FR4 | Arbitrary ReactNode start content renders directly and carries no ComplexSelector-owned target.                                                                                           | Current source                  | Verified current behavior; no target change        |
+
+### Allowed variation
+
+- Caller-provided popup content may vary without becoming a new
+  ComplexSelector-owned anatomy part or target.
+- The optional start slot has two factual branches: semantic names and icon
+  component types render through Icon, while arbitrary ReactNode content renders
+  directly under caller ownership.
+
+### Representative states
+
+- Input and ghost variants use the same six-part anatomy and current targets.
+- The start slot is absent when `startIcon` is omitted. When present, exactly
+  one of Icon-rendered start icon or Caller-rendered start content applies.
+- The Popup remains mounted in both states: it is hidden while closed and shown
+  while open. The Indicator icon remains present and reflects collapsed or
+  expanded state on its current target.
+
+### Transformation and precedence order
+
+- No new value, open-state, positioning, or style precedence rule is introduced.
+
+### Performance and resources
+
+- No new performance or resource rule is introduced.
+
+## Accessibility contract
+
+This draft does not change or extend ComplexSelector's existing field, trigger,
+dialog, focus, or keyboard behavior.
+
+## Design relationships
+
+| Anatomy or state              | Design requirement                                                               | Representation authority       | Hierarchy role    | Component contract |
+| ----------------------------- | -------------------------------------------------------------------------------- | ------------------------------ | ----------------- | ------------------ |
+| Field                         | Provides the field shell around the owned trigger.                               | Field component                | Supporting        | FR1, FR3           |
+| Trigger                       | Displays the current value or placeholder and opens the popup.                   | Current source and public docs | Prominent         | FR1, FR2           |
+| Icon-rendered start icon      | Optionally presents a semantic or component icon through Icon.                   | Icon component                 | Supporting        | FR1, FR3           |
+| Caller-rendered start content | Optionally presents arbitrary React content directly in the start slot.          | Caller-supplied content        | Context-dependent | FR1, FR4           |
+| Indicator icon                | Presents the trailing disclosure glyph and reflects collapsed or expanded state. | Current source and public docs | Supporting        | FR1, FR2           |
+| Popup                         | Keeps the dialog surface mounted, hidden while closed and painted while open.    | Current source and public docs | Prominent         | FR1, FR2           |
+
+The Field and Icon delegations preserve their existing owners. Arbitrary
+ReactNode start content remains caller-owned and receives no local target. The
+local Indicator icon target remains distinct because it carries the selector's
+expanded/collapsed state and rotation on the glyph itself. Caller-provided popup
+content remains outside the owned anatomy inventory.
+
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+  "Field": {"delegatesTo": {"owner": "component:Field", "target": "field"}},
+  "Trigger": {"target": "complex-selector"},
+  "Icon-rendered start icon": {
+    "delegatesTo": {"owner": "component:Icon", "target": "icon"}
+  },
+  "Caller-rendered start content": {
+    "none": {
+      "reason": "intentional: Arbitrary ReactNode content is caller-owned and receives no ComplexSelector target."
+    }
+  },
+  "Indicator icon": {"target": "complex-selector-indicator-icon"},
+  "Popup": {"target": "complex-selector-popup"}
+}
+```
+
+## Family and system relationships
+
+- `architecture:component-theming-surface` owns anatomy qualification, local
+  target mapping, and delegation rules.
+- `architecture:layer-runtime` owns the current `usePopover` host, positioning,
+  native light-dismiss, and visibility reconciliation used by the Popup.
+- `family:overlay-dismissal` owns shared Escape and platform-close ordering;
+  ComplexSelector participates through its composed Popover owner.
+- Field and Icon retain ownership of their delegated targets and presentation.
+
+## Verification map
+
+| Contract            | Verification                                                               | Representative states                            | Mutation or failure expectation                                                               | Audit section                   |
+| ------------------- | -------------------------------------------------------------------------- | ------------------------------------------------ | --------------------------------------------------------------------------------------------- | ------------------------------- |
+| FR1                 | `ComplexSelector.test.tsx` render, ghost-trigger, and popup suites         | Default closed, ghost start branches, open Popup | Removing a documented part fails existing role, content, or structure assertions.             | `audit:ComplexSelector/anatomy` |
+| FR2                 | Component target suites, source inspection, and theming target inventories | Closed/open Popup; expanded Indicator icon       | Removing or renaming a current local target fails component assertions or target inventories. | `audit:ComplexSelector/theming` |
+| FR3, FR4            | Icon owner tests and `renderIconSlot` source inspection                    | Semantic/component icon; arbitrary ReactNode     | A branch gains the wrong owner, loses its target, or receives an invented local target.       | `audit:ComplexSelector/theming` |
+| Theming anatomy map | `scripts/check-knowledge.mjs`                                              | Canonical anatomy and current local targets      | Missing, extra, prefixed, stale, or multiply assigned mappings fail repository validation.    | `audit:ComplexSelector/theming` |
+
+Current component tests directly assert the Trigger and Popup targets. Source
+inspection confirms that non-lazy `useLayer` keeps the Popup mounted while
+closed. The Indicator icon target is covered by source inspection and shared
+target inventories rather than a dedicated component assertion. `renderIconSlot`
+and Icon owner tests distinguish the Icon-rendered branch from arbitrary
+caller-owned ReactNode content.
+
+## Decision log
+
+None. This draft records current facts and introduces no component-local design,
+API, theming, or layer-system decision.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables, examples, caller-provided
+popup structure, implementation steps, or shared layer and theming rules. It
+links to their owners.

package/src/ContextMenu/ContextMenu.doc.mjs

@@ -1,4 +1,50 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */
+const anatomy = [
+  {
+    name: 'Trigger area',
+    required: true,
+    description:
+      'Caller-provided region that accepts right-click, keyboard context-menu, and long-press input.',
+  },
+  {
+    name: 'Pointer menu surface',
+    required: false,
+    description:
+      'Cursor-positioned menu panel used by the pointer presentation.',
+  },
+  {
+    name: 'Pointer action row',
+    required: false,
+    description:
+      'DropdownMenu-owned action, selectable option, or submenu row in the pointer presentation.',
+  },
+  {
+    name: 'Touch sheet frame',
+    required: false,
+    description:
+      'BottomSheet panel, content area, handle, and optional scrim that host touch actions.',
+  },
+  {
+    name: 'Touch menu surface',
+    required: false,
+    description:
+      'ContextMenu-owned content panel rendered inside the touch sheet frame.',
+  },
+  {
+    name: 'Touch action list',
+    required: false,
+    description: 'Spacious List that groups data-driven touch actions.',
+  },
+  {
+    name: 'Touch action row',
+    required: false,
+    description:
+      'ListItem button used for a data-driven action or drill-in entry in the touch presentation.',
+  },
+];
+
 /** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
@@ -32,7 +78,7 @@ export const docs = {
     {
       name: 'items',
       type: 'ContextMenuOption[]',
-      description: 'Array of menu entries. Each entry is one of: an action item `{label, onClick?, icon?, isDisabled?, variant?}` (variant `"destructive"` renders it in the error color), a divider `{type: "divider"}`, or a section `{type: "section", title?, items: [...action items]}`.',
+      description: 'Array of menu entries. Each entry is one of: an action item `{label, onClick?, icon?, isDisabled?, variant?, items?}` (nested `items` open a flyout in popover presentation and drill into a new view in bottom-sheet presentation; variant `"destructive"` renders it in the error color), a divider `{type: "divider"}`, or a section `{type: "section", title?, items: [...action items]}`.',
       required: true,
     },
     {
@@ -63,6 +109,12 @@ export const docs = {
       type: '(isOpen: boolean) => void',
       description: 'Callback fired when the menu opens or closes.',
     },
+    {
+      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.',
+      default: "'popover'",
+    },
     {
       name: 'isDisabled',
       type: 'boolean',
@@ -74,11 +126,14 @@ export const docs = {
     {name: 'ContextMenuItem'},
   ],
   usage: {
+    anatomy,
     description: 'A right-click context menu that appears at the cursor position. Use to provide contextual actions for specific elements or regions without cluttering the UI with visible buttons.',
     bestPractices: [
       { guidance: true, description: 'Keep menu items concise and action-oriented; users expect quick access to contextual actions.' },
       { guidance: true, description: 'Use sections and dividers to group related actions when the menu has many items.' },
+      { guidance: true, description: 'Use `presentation="adaptive"` when right-click should remain cursor-positioned on desktop while long-press opens a reachable BottomSheet on compact touch devices.' },
       { guidance: true, description: 'Ensure all context menu actions are also accessible via other UI elements for keyboard-only users.' },
+      { guidance: true, description: 'Keep a visible MoreMenu or equivalent trigger for important mobile actions; long-press must not be the only route.' },
       { guidance: false, description: 'Use a ContextMenu as the only way to access important actions; not all users know to right-click.' },
       { guidance: false, description: 'Place more than 10–12 items in a single menu without grouping them into sections.' },
     ],
@@ -107,7 +162,9 @@ export const docsZh = {
     bestPractices: [
       { guidance: true, description: '保持菜单项简洁和面向操作。' },
       { guidance: true, description: '有很多项时使用分组和分隔线。' },
+      { guidance: true, description: '在桌面端需要光标定位、紧凑触控设备上需要 BottomSheet 时，使用 `presentation="adaptive"`。' },
       { guidance: true, description: '确保所有上下文菜单操作也可通过其他 UI 元素访问。' },
+      { guidance: true, description: '重要的移动端操作还应提供可见的 MoreMenu 或同等入口，不要只依赖长按。' },
       { guidance: false, description: '将上下文菜单作为访问重要操作的唯一方式。' },
       { guidance: false, description: '在单个菜单中放置超过 10-12 个项而不分组。' },
     ],
@@ -118,11 +175,14 @@ export const docsZh = {
 export const docsDense = {
   description: 'right-click context menu at cursor position',
   usage: {
+    anatomy,
     description: 'A right-click context menu that appears at the cursor position. Use to provide contextual actions for specific elements or regions.',
     bestPractices: [
       { guidance: true, description: 'Keep items concise and action-oriented.' },
       { guidance: true, description: 'Group related actions with sections and dividers.' },
+      { guidance: true, description: 'Use adaptive presentation for cursor popover on desktop and BottomSheet on compact touch.' },
       { guidance: true, description: 'Ensure actions are also accessible via other UI elements.' },
+      { guidance: true, description: 'Keep a visible mobile entry point for important actions.' },
       { guidance: false, description: 'Use as the only way to access important actions.' },
       { guidance: false, description: 'Place more than 10–12 items without grouping.' },
     ],

package/src/ContextMenu/ContextMenu.spec.md

@@ -0,0 +1,206 @@
+---
+schema_version: 1
+template_version: 3
+kind: component
+id: component:ContextMenu
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+owners: [cixzhang]
+review_triggers: [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,
+    scripts/check-knowledge.mjs,
+  ]
+families: [family:overlay-dismissal]
+design_specs: []
+architecture:
+  [
+    architecture:component-theming-surface,
+    architecture:interaction-modality,
+    architecture:layer-runtime,
+  ]
+contributing: []
+system_specs: []
+---
+
+# ContextMenu component contract
+
+## Intent
+
+ContextMenu presents actions for a caller-provided region in either a
+cursor-positioned pointer menu or a BottomSheet-hosted touch action list. This
+draft records current consumer anatomy, presentation-specific ownership, and
+theming reachability without changing runtime behavior, styling, targets, or
+public API.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`
+- Compatibility class: additive documentation only; runtime, DOM, styling,
+  targets, and public API remain unchanged
+- Controlled/uncontrolled behavior: unchanged
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- The Trigger area's context-menu invocation wiring.
+- 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.
+
+**Does not own / non-goals**
+
+- Caller-provided Trigger area content.
+- Pointer action-row presentation — delegated to `component:DropdownMenu`.
+- The Touch sheet frame — delegated to `component:BottomSheet`.
+- Data-driven Touch action-list and row presentation — delegated to
+  `component:List`.
+- Shared layer lifecycle or dismissal policy.
+
+## Public concepts
+
+No new public concept is introduced. Consumer props, content modes, and
+presentation policy remain documented in `ContextMenu.doc.mjs`.
+
+## Behavioral and layout contract
+
+| ID  | Candidate invariant                                                                                                                                                                                                                                                                     | Basis                           | Draft review state                                 |
+| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | -------------------------------------------------- |
+| FR1 | Every render contains a caller-provided Trigger area. Pointer presentation opens a Pointer menu surface at the current local cursor anchor; touch presentation opens a Touch sheet frame containing a Touch menu surface and, for data mode, a Touch action list and Touch action rows. | Current source, docs, and tests | Verified current behavior; no new behavior decided |
+| FR2 | The current `context-menu` target remains on the painted Pointer menu surface and alternative Touch menu surface, not on the Trigger area or cursor anchor.                                                                                                                             | Current source, docs, and tests | Verified current inventory; no target change       |
+| FR3 | Pointer action rows retain DropdownMenu ownership. The touch frame retains BottomSheet ownership, while data-driven touch lists and rows retain List ownership.                                                                                                                         | Current source and owner docs   | Verified current delegation; no ownership change   |
+| FR4 | Compound `menuContent` remains a caller-supplied pointer-menu interior and may also render inside the touch frame; the data-driven touch path instead converts the same item data to List and ListItem presentation.                                                                    | Current source and tests        | Verified current branches; no behavior change      |
+
+### Allowed variation
+
+- **AV1 — Invocation.** Right-click, keyboard context-menu invocation, and
+  long-press may open the current resolved presentation without changing
+  anatomy ownership.
+- **AV2 — Presentation.** `popover`, `bottom-sheet`, and resolved `adaptive`
+  presentation may select the current pointer or touch anatomy.
+- **AV3 — Content mode.** Data-driven pointer content renders through
+  DropdownMenu helpers; compound content remains caller-composed. Data-driven
+  touch content renders through List.
+
+### Representative states
+
+| State                 | Required invariant                                                                                  | Allowed variation                                                  |
+| --------------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
+| Pointer data menu     | Trigger area opens Pointer menu surface with DropdownMenu-owned rows.                               | Cursor position, row content, width, and nested flyouts may vary.  |
+| Pointer compound menu | Trigger area opens the same surface around caller-supplied menu content.                            | Caller chooses supported DropdownMenu interior components.         |
+| Touch data menu       | Trigger area opens Touch sheet frame and Touch menu surface containing List-owned actions.          | Heading, sections, dividers, icons, and drill-in depth may vary.   |
+| Touch compound menu   | Trigger area opens Touch sheet frame around the ContextMenu surface and caller-supplied interior.   | Caller-supplied content remains responsible for its own structure. |
+| Disabled trigger      | Trigger area remains rendered and the native browser context menu is not suppressed by ContextMenu. | Caller-provided content remains unchanged.                         |
+
+### Transformation and precedence order
+
+- No new presentation-resolution, cursor-position, long-press, item-rendering,
+  or styling precedence rule is introduced.
+
+### Performance and resources
+
+- No new loading, listener, measurement, or render constraint is introduced.
+
+## Accessibility contract
+
+This draft does not change or extend ContextMenu's existing menu and dialog
+naming, keyboard invocation, long-press path, focus movement, item semantics, or
+dismissal behavior.
+
+## Design relationships
+
+| Anatomy or state     | Design requirement                                                                | Representation authority       | Hierarchy role    | Component contract |
+| -------------------- | --------------------------------------------------------------------------------- | ------------------------------ | ----------------- | ------------------ |
+| Trigger area         | Defines the caller-owned region that accepts context-menu input.                  | Caller-supplied content        | Context-dependent | FR1, FR2           |
+| Pointer menu surface | Paints the menu at the current cursor anchor.                                     | Current source and public docs | Prominent         | FR1, FR2           |
+| Pointer action row   | Presents an action, selectable option, or nested-menu entry through DropdownMenu. | `component:DropdownMenu`       | Prominent         | FR1, FR3, FR4      |
+| Touch sheet frame    | Supplies the touch panel, scrolling area, handle, and optional scrim.             | `component:BottomSheet`        | Prominent         | FR1, FR3           |
+| Touch menu surface   | Arranges ContextMenu-owned heading and content inside the sheet.                  | Current source and public docs | Prominent         | FR1, FR2           |
+| Touch action list    | Groups data-driven touch actions using the spacious List presentation.            | `component:List`               | Prominent         | FR1, FR3, FR4      |
+| Touch action row     | Presents one data-driven touch action or drill-in entry using ListItem.           | `component:List`               | Prominent         | FR1, FR3, FR4      |
+
+The `context-menu` target intentionally appears on both alternative painted
+menu surfaces. Trigger area content stays caller-owned and the zero-size cursor
+anchor is positioning infrastructure rather than consumer anatomy.
+
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+  "Trigger area": {
+    "none": {
+      "reason": "intentional: Caller-provided trigger content remains caller-owned and the ContextMenu wrapper has no public target."
+    }
+  },
+  "Pointer menu surface": {"target": "context-menu"},
+  "Pointer action row": {
+    "delegatesTo": {
+      "owner": "component:DropdownMenu",
+      "target": "dropdown-menu-item"
+    }
+  },
+  "Touch sheet frame": {
+    "delegatesTo": {"owner": "component:BottomSheet", "target": "bottom-sheet"}
+  },
+  "Touch menu surface": {"target": "context-menu"},
+  "Touch action list": {
+    "delegatesTo": {"owner": "component:List", "target": "list"}
+  },
+  "Touch action row": {
+    "delegatesTo": {"owner": "component:List", "target": "list-item"}
+  }
+}
+```
+
+## Family and system relationships
+
+- `architecture:component-theming-surface` owns anatomy qualification, local
+  target mapping, presentation-specific rows, and delegation rules.
+- `architecture:interaction-modality` owns the shared right-click, keyboard,
+  long-press, pointer, touch, and adaptive-presentation boundaries; this draft
+  changes none of them.
+- `architecture:layer-runtime` owns the current context-mode `useLayer` host and
+  cursor-anchor positioning. ContextMenu currently retains local outside-click
+  and Escape listeners; touch hosting delegates to BottomSheet.
+- `family:overlay-dismissal` owns shared Escape and platform-close ordering and
+  records ContextMenu and BottomSheet as current local-only adoption gaps. This
+  anatomy backfill does not migrate either path.
+
+## Verification map
+
+| Contract            | Verification                                                                                      | Representative states                         | Mutation or failure expectation                                                                    | Audit section                |
+| ------------------- | ------------------------------------------------------------------------------------------------- | --------------------------------------------- | -------------------------------------------------------------------------------------------------- | ---------------------------- |
+| FR1, FR4            | `ContextMenu.test.tsx` pointer, long-press, bottom-sheet, adaptive, compound, and drill-in suites | Pointer data/compound and touch data/compound | Collapsing presentation-specific parts or content owners fails structure, role, or behavior tests. | `audit:ContextMenu/anatomy`  |
+| FR2                 | ContextMenu target tests, source inspection, and theming target inventories                       | Pointer and touch menu surfaces               | Moving `context-menu` to the trigger or removing it from a painted branch fails evidence.          | `audit:ContextMenu/theming`  |
+| FR3                 | ContextMenu, DropdownMenu, BottomSheet, and List owner tests                                      | Pointer rows, touch frame, touch list/rows    | A composed part loses its owner target or is documented as a new ContextMenu target.               | `audit:ContextMenu/theming`  |
+| Layer relationships | `ContextMenu.test.tsx` and current layer/dismissal architecture records                           | Outside click, Escape, context anchor, sheet  | Documentation claims shared dismissal where current source retains local behavior.                 | `audit:ContextMenu/behavior` |
+| 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`  |
+
+## Decision log
+
+None. This draft records current facts and introduces no component-local design,
+API, theming, modality, or layer-system decision.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables, menu examples, cursor and
+long-press algorithms, implementation steps, or shared modality, layer,
+dismissal, and theming rules. It links to their owners.

package/src/ContextMenu/ContextMenu.test.tsx

@@ -9,8 +9,9 @@
  */
 
 import {describe, it, expect, vi, beforeEach} from 'vitest';
-import {render, screen, fireEvent, act} from '@testing-library/react';
+import {render, screen, fireEvent, act, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
+import {readFileSync} from 'node:fs';
 import {ContextMenu} from './ContextMenu';
 import {
   ContextMenuItem,
@@ -23,6 +24,30 @@ import {DropdownMenuItem} from '../DropdownMenu/DropdownMenuItem';
 import {Divider} from '../Divider';
 
 beforeEach(() => {
+  HTMLDialogElement.prototype.showModal = vi.fn(function (
+    this: HTMLDialogElement,
+  ) {
+    this.setAttribute('open', '');
+  });
+  HTMLDialogElement.prototype.show = vi.fn(function (this: HTMLDialogElement) {
+    this.setAttribute('open', '');
+  });
+  HTMLDialogElement.prototype.close = vi.fn(function (this: HTMLDialogElement) {
+    this.removeAttribute('open');
+  });
+  vi.stubGlobal(
+    'matchMedia',
+    vi.fn().mockImplementation((query: string) => ({
+      matches: false,
+      media: query,
+      onchange: null,
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+      addListener: vi.fn(),
+      removeListener: vi.fn(),
+      dispatchEvent: vi.fn(),
+    })),
+  );
   HTMLElement.prototype.showPopover = vi.fn(function (this: HTMLElement) {
     this.setAttribute('popover-open', '');
     const event = new Event('toggle', {bubbles: false});
@@ -123,6 +148,100 @@ describe('ContextMenu', () => {
     expect(HTMLElement.prototype.showPopover).toHaveBeenCalled();
   });
 
+  it('opens the real menu content in a BottomSheet when requested', async () => {
+    render(
+      <ContextMenu
+        presentation="bottom-sheet"
+        label="Row actions"
+        items={[{label: 'Edit'}]}>
+        <div>Right-click me</div>
+      </ContextMenu>,
+    );
+
+    fireEvent.contextMenu(screen.getByText('Right-click me'));
+    await waitFor(() =>
+      expect(HTMLDialogElement.prototype.showModal).toHaveBeenCalledOnce(),
+    );
+    const dialog = screen.getByRole('dialog', {name: 'Row actions'});
+    const actionList = dialog.querySelector('[data-autofocus]');
+    expect(actionList).not.toBeNull();
+    await waitFor(() => expect(actionList).toHaveFocus());
+    expect(screen.getByRole('button', {name: 'Edit'})).not.toHaveFocus();
+    expect(HTMLElement.prototype.showPopover).not.toHaveBeenCalled();
+  });
+
+  it('drills into nested data items inside the BottomSheet', async () => {
+    const user = userEvent.setup();
+    const onMove = vi.fn();
+
+    render(
+      <ContextMenu
+        presentation="bottom-sheet"
+        label="Row actions"
+        items={[
+          {
+            label: 'Move to project',
+            items: [{label: 'Apollo launch', onClick: onMove}],
+          },
+        ]}>
+        <div>Right-click me</div>
+      </ContextMenu>,
+    );
+
+    fireEvent.contextMenu(screen.getByText('Right-click me'));
+    await user.click(screen.getByRole('button', {name: 'Move to project'}));
+
+    const submenuHeading = screen.getByRole('heading', {
+      name: 'Move to project',
+    });
+    expect(submenuHeading).toBeInTheDocument();
+    await waitFor(() => expect(submenuHeading).toHaveFocus());
+    expect(HTMLElement.prototype.showPopover).not.toHaveBeenCalled();
+
+    await user.click(screen.getByRole('button', {name: 'Apollo launch'}));
+    expect(onMove).toHaveBeenCalledOnce();
+    await waitFor(() =>
+      expect(screen.queryByRole('dialog')).not.toBeInTheDocument(),
+    );
+  });
+
+  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}');
+  });
+
+  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)',
+        media: query,
+        onchange: null,
+        addEventListener: vi.fn(),
+        removeEventListener: vi.fn(),
+        addListener: vi.fn(),
+        removeListener: vi.fn(),
+        dispatchEvent: vi.fn(),
+      })),
+    );
+    render(
+      <ContextMenu presentation="adaptive" items={[{label: 'Edit'}]}>
+        <div>Right-click me</div>
+      </ContextMenu>,
+    );
+
+    fireEvent.contextMenu(screen.getByText('Right-click me'));
+    await waitFor(() =>
+      expect(HTMLDialogElement.prototype.showModal).toHaveBeenCalledOnce(),
+    );
+    expect(HTMLElement.prototype.showPopover).not.toHaveBeenCalled();
+  });
+
   it('closes on Escape even when opened without auto-focus', () => {
     render(
       <ContextMenu items={[{label: 'Item 1'}]}>
@@ -273,6 +392,17 @@ describe('ContextMenu', () => {
     }
   });
 
+  it('suppresses native text selection on the long-press trigger', () => {
+    const source = readFileSync(
+      'packages/core/src/ContextMenu/ContextMenu.tsx',
+      'utf8',
+    );
+
+    expect(source).toMatch(
+      /trigger:[\s\S]*?WebkitTouchCallout: 'none',[\s\S]*?WebkitUserSelect: 'none',[\s\S]*?userSelect: 'none'/,
+    );
+  });
+
   it('cancels the long-press when the finger moves past the threshold', () => {
     vi.useFakeTimers();
     try {