@astryxdesign/core 0.7.2-canary.fe2c655 → 0.7.2

package/src/DropdownMenu/DropdownMenuDivider.spec.md

@@ -0,0 +1,192 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:DropdownMenuDivider
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+owners: [cixzhang]
+review_triggers: [public-api, behavior, theming, accessibility, testing]
+verified_by:
+  [
+    packages/core/src/DropdownMenu/DropdownMenu.test.tsx,
+    packages/core/src/ContextMenu/ContextMenu.test.tsx,
+    packages/core/src/Breadcrumbs/Breadcrumbs.test.tsx,
+    packages/core/src/theme/themingTargets.test.ts,
+    apps/storybook/stories/DropdownMenuDivider.stories.tsx,
+    scripts/check-knowledge.mjs,
+  ]
+modules: []
+families: []
+design_specs: []
+architecture:
+  [
+    architecture:public-component-api,
+    architecture:component-theming-surface,
+    architecture:component-test-sufficiency,
+  ]
+contributing: []
+system_specs: [spec:AST-020, spec:AST-029]
+---
+
+# DropdownMenuDivider component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                                                                           |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | `DropdownMenuDivider` / `DropdownMenuDividerProps`, plus the `ContextMenuDivider` and `BreadcrumbMenuDivider` aliases and their props; `BaseProps<HTMLDivElement>` minus caller-owned `role` and `aria-orientation`; a root `ref`. |
+| Behavior                | One unlabelled horizontal separator divides pointer-menu rows and stays out of arrow-key order; data and compound pointer modes render the same component.                                                                         |
+| End-user impact         | Pointer-menu sections remain visually separated without adding a focus stop or changing row operation.                                                                                                                             |
+| Builder impact          | No new caller choice. Host attributes, handlers, and styling inputs continue to compose on the separator.                                                                                                                          |
+| Compatibility/readiness | Patch-compatible observational contract. Runtime behavior, exports, defaults, and target names remain unchanged; authority stays `draft` until exact-head owner approval.                                                          |
+| Review checks           | Reject a focusable separator, changed role/orientation, pointer data/compound divergence, dropped root inputs, or a target moved off the visible separator.                                                                        |
+| Governing rules         | `architecture:public-component-api/INV1,INV5–INV9`; `architecture:component-theming-surface/INV3–INV6`; WCAG 2.2 SC 1.3.1 and 4.1.2 through `spec:AST-020/FR1`.                                                                    |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+DropdownMenuDivider provides the visual and programmatic boundary between groups
+of rows in pointer-menu presentations. It ships directly under the DropdownMenu
+name and through ContextMenu and Breadcrumbs aliases. It owns the separator
+semantics, menu spacing, root input composition, and the
+`dropdown-menu-divider` theme target. The surrounding DropdownMenu, ContextMenu,
+or BreadcrumbItem owns menu lifecycle and row navigation; Divider supplies the
+base rule geometry and paint.
+
+Consumer syntax and examples belong in `DropdownMenuDivider.doc.mjs`.
+
+## Compatibility and migration
+
+- Released default preserved: yes — one horizontal, unlabelled separator.
+- Compatibility class: observational patch; no behavior or public surface changes.
+- Controlled/uncontrolled behavior: not applicable.
+- Migration decision: none.
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- One horizontal separator root and its public ref, DOM/data/ARIA, class, style,
+  event, and `xstyle` composition.
+- Menu-specific block-axis spacing.
+- The `dropdown-menu-divider` target on the same visible root.
+- Pointer-menu data/compound rendering parity for the divider row across
+  DropdownMenu, ContextMenu, and breadcrumb menus.
+
+**Does not own / non-goals**
+
+- Menu open state, focus entry, row activation, or arrow-key navigation — owned by
+  DropdownMenu, ContextMenu, BreadcrumbItem, and their shared hooks.
+- Touch and bottom-sheet data dividers — those presentations render Divider
+  directly and are owned by their parent menu surface.
+- Base separator rule geometry and token paint — delegated to Divider.
+- Caller-authored grouping meaning — owned by the product callsite.
+
+## Public concepts
+
+| Concept       | Closed values or states                       | Meaning                                                                        | Availability by variant/orientation/state | Default                | Owner                | Stability | Invalid-value behavior                                                          |
+| ------------- | --------------------------------------------- | ------------------------------------------------------------------------------ | ----------------------------------------- | ---------------------- | -------------------- | --------- | ------------------------------------------------------------------------------- |
+| Separator row | one horizontal unlabelled separator           | Divides adjacent pointer-menu row groups without becoming a row or focus stop. | Data and compound pointer-menu modes      | present where authored | component            | stable    | Role and orientation are excluded from caller props and remain component-owned. |
+| Root surface  | ref; DOM/data/ARIA; class/style/xstyle/events | Extends the separator root while preserving component semantics.               | Every separator row                       | omitted                | public component API | stable    | Accepted inputs compose; role and orientation remain authoritative.             |
+
+## Behavioral and layout contract
+
+Draft requirements identify their basis so observed code is not mistaken for an
+intentional decision.
+
+| ID  | Candidate invariant                                                                                                                                                                | Basis                                                            | Draft review state |
+| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | ------------------ |
+| FR1 | The component MUST render one unlabelled horizontal separator with pointer-menu-specific block spacing.                                                                            | Released source/docs and focused tests                           | verify             |
+| FR2 | The root MUST expose `role="separator"` and `aria-orientation="horizontal"`, remain outside menu-item collection and arrow-key order, and never become focusable.                  | WCAG 2.2 SC 1.3.1 and 4.1.2; focused tests                       | verify             |
+| FR3 | In pointer-menu presentation, `{type: "divider"}` in the data API and the compound divider component or alias MUST render the same component DOM, spacing, semantics, and targets. | Released docs/source; data/compound parity test                  | verify             |
+| FR4 | The visible root MUST carry both the delegated `divider` target and the menu-specific `dropdown-menu-divider` target; menu spacing applies before caller `xstyle`.                 | `architecture:component-theming-surface/INV3–INV6`; source/tests | verify             |
+| FR5 | Accepted ref, DOM/data/ARIA, class, style, events, and `xstyle` MUST reach or compose on the separator root without replacing component-owned role or orientation.                 | `architecture:public-component-api/INV5–INV8`                    | verify             |
+
+### Allowed variation
+
+- **AV1 — Theme paint.** The delegated Divider and menu-specific targets may restyle
+  their owned surface without changing separator semantics or focus behavior.
+- **AV2 — Caller root inputs.** Supported host attributes, handlers, and styling
+  inputs may vary while the owned role and orientation remain fixed.
+
+### Representative states
+
+| State                     | Required invariant                                                   | Allowed variation                                             |
+| ------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------- |
+| Pointer data-mode divider | One horizontal separator between data-driven rows.                   | Adjacent row content and active theme may vary.               |
+| Pointer compound divider  | DOM and behavior match the pointer data-mode divider.                | Host attributes and supported styling inputs may be supplied. |
+| Public aliases            | ContextMenuDivider and BreadcrumbMenuDivider render this component.  | The containing menu owns lifecycle and navigation.            |
+| Touch data divider        | Outside this component; the parent surface renders Divider directly. | Touch-menu layout follows the parent contract.                |
+| RTL                       | The horizontal, full-width rule remains direction-neutral.           | Surrounding text and menu alignment may mirror.               |
+| Narrow viewport           | The rule remains inside the menu without horizontal overflow.        | Menu width follows its owner.                                 |
+
+### Transformation and precedence order
+
+- **ORD1 — Root composition.** Apply menu spacing, then caller `xstyle`; combine the
+  menu-specific target class with caller `className`; preserve caller `style` and
+  host props; keep role and orientation component-owned.
+
+### Performance and resources
+
+- **PR1 — No external lifecycle.** DropdownMenuDivider installs no listener,
+  observer, timer, request, state machine, or Effect.
+
+## Accessibility contract
+
+- **AR1 — Separator semantics.** The root exposes a horizontal separator and no
+  interactive role or tab stop.
+- **AR2 — Navigation exclusion.** Menu navigation collects menu-item roles only, so
+  ArrowDown and ArrowUp pass across the separator without focusing it.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                                                              | Representation authority                                                              | Hierarchy role | Component contract |
+| ---------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | -------------- | ------------------ |
+| Menu separator   | Visually separates adjacent menu row groups without competing with row content. | Current source and delegated Divider tokens; no component-local visual decision added | supporting     | FR1–FR4            |
+
+No component-local visual decision is settled by this draft.
+
+## Family and system relationships
+
+- `architecture:public-component-api` owns exports and root input composition.
+- `architecture:component-theming-surface` owns target placement and composed target
+  ownership.
+- `architecture:component-test-sufficiency` owns proportionate, observable evidence.
+- DropdownMenu exports the implementation directly. ContextMenu and Breadcrumbs
+  re-export it as `ContextMenuDivider` and `BreadcrumbMenuDivider`, with matching
+  props aliases; their pointer presentations retain the same component contract.
+- Touch and bottom-sheet data dividers bypass this component and delegate directly
+  to Divider under the parent menu contract.
+- Divider provides the base separator implementation; its draft record is
+  observational context, not authority for this contract.
+- `spec:AST-029` keeps this observational draft separate from the audit receipt.
+
+## Verification map
+
+| Contract         | Verification                                                                                            | Representative states                                         | Mutation or failure expectation                                                                                     | Audit section                           |
+| ---------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
+| FR1–FR3, AR1–AR2 | `DropdownMenu.test.tsx`; ContextMenu and Breadcrumbs alias tests; dedicated Storybook state; scoped axe | pointer data/compound, aliases, open menu, keyboard traversal | Pointer DOM modes drift, an alias disappears, the role/orientation changes, or the separator enters arrow-key order | `audit:DropdownMenuDivider/§1,§3,§4,§6` |
+| FR4              | Focused root-composition test; exact-head Neutral/Butter browser frames                                 | light/dark themes; menu and delegated targets                 | A target leaves the visible root or caller `xstyle` stops composing after menu spacing                              | `audit:DropdownMenuDivider/§2,§5`       |
+| FR5              | Focused root-composition test; lint and typecheck                                                       | ref, host attributes, class/style/xstyle/events               | An accepted input is dropped or owned semantics are overwritten                                                     | `audit:DropdownMenuDivider/§3`          |
+| PR1              | Source review                                                                                           | every state                                                   | A lifecycle mechanism appears without a resource contract                                                           | `audit:DropdownMenuDivider/§7`          |
+
+## Decision log
+
+None. This draft records current facts and introduces no product decision.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables/examples, current audit scores,
+screenshot matrices, implementation steps, or system rules. The audit pull request
+owns the closed run evidence required by `spec:AST-029/FR5`.

package/src/DropdownMenu/DropdownMenuDivider.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file DropdownMenuDivider.tsx
- * @input Uses Divider, spacing tokens, themeProps
+ * @input Uses Divider, spacing tokens, themeProps; forwards host props to Divider
  * @output Exports DropdownMenuDivider component and DropdownMenuDividerProps
  * @position Sub-component; used inside DropdownMenu
  *
@@ -37,9 +37,9 @@ const styles = stylex.create({
 
 const THEME_CLASS_NAME = themeProps('dropdown-menu-divider').className;
 
-export interface DropdownMenuDividerProps extends Pick<
-  BaseProps,
-  'xstyle' | 'className' | 'style'
+export interface DropdownMenuDividerProps extends Omit<
+  BaseProps<HTMLDivElement>,
+  'role' | 'aria-orientation'
 > {
   /** Ref forwarded to the separator element. */
   ref?: React.Ref<HTMLDivElement>;
@@ -49,7 +49,9 @@ export interface DropdownMenuDividerProps extends Pick<
  * A horizontal rule separating groups of menu rows.
  *
  * Renders `role="separator"`, so it is never a stop in the menu's arrow-key
- * order. Equivalent to `{type: 'divider'}` in the `items` data API.
+ * order. Equivalent to `{type: 'divider'}` in the `items` data API. Host
+ * attributes (`id`, `data-*`, `aria-*`) and DOM handlers reach the separator;
+ * its role and orientation stay component-owned.
  *
  * @example
  * ```
@@ -65,9 +67,11 @@ export function DropdownMenuDivider({
   className,
   style,
   ref,
+  ...rest
 }: DropdownMenuDividerProps) {
   return (
     <Divider
+      {...rest}
       ref={ref}
       xstyle={[styles.divider, xstyle]}
       className={

package/src/DropdownMenu/DropdownMenuGroup.doc.mjs

@@ -13,25 +13,86 @@ export const docs = {
     defaults: {title: 'Version history'},
   },
   description:
-    'A titled group of rows in a compound menu. Renders role="group" named by its heading; the heading is plain text, not a menuitem, so arrow keys and typeahead skip it. The data-driven equivalent is the `{type: "section", title, items}` entry in `items`; the heading shares its typography and theme target.',
+    'A group of rows in a compound menu. A visible title names role="group" through aria-labelledby; an omitted title leaves the group unnamed. The heading is not a menuitem, so arrow keys and typeahead skip it. Keep title content non-interactive and place controls in DropdownMenu header or footer. The data-driven equivalent is the `{type: "section", title, items}` entry in `items`; both forms share the heading treatment and theme target.',
+  usage: {
+    description:
+      'Use DropdownMenuGroup to give related compound-menu rows one visible and programmatic name. Use an untitled group only when a separate name would not help people understand the rows.',
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          'Use short, descriptive title content that explains what the grouped rows have in common.',
+      },
+      {
+        guidance: true,
+        description:
+          'Keep the title non-interactive so every available action remains in the menu arrow-key order.',
+      },
+      {
+        guidance: false,
+        description:
+          'Place buttons, links, fields, or other controls in title. Put them in DropdownMenu header or footer instead.',
+      },
+      {
+        guidance: false,
+        description:
+          'Wrap rows that do not form a meaningful set; a group adds structure only when its relationship helps users.',
+      },
+    ],
+    anatomy: [
+      {
+        name: 'Group',
+        required: true,
+        description:
+          'The role="group" wrapper containing the heading and menu rows.',
+      },
+      {
+        name: 'Heading',
+        required: false,
+        description:
+          'Visible non-interactive title content that names the group and carries the dropdown-menu-section-heading theme target.',
+      },
+      {
+        name: 'Rows',
+        required: false,
+        description:
+          'Menu items, selectable items, radio groups, or submenus owned by DropdownMenu.',
+      },
+    ],
+  },
   props: [
     {
       name: 'title',
       type: 'ReactNode',
       description:
-        "Heading shown above the rows and used as the group's accessible name. Omit for an unnamed group.",
+        "Non-interactive heading content shown above the rows and used as the group's accessible name. Omit for an unnamed group; place controls in DropdownMenu header or footer.",
     },
     {
       name: 'children',
       type: 'ReactNode',
       description:
-        'The rows of the group: DropdownMenuItem, DropdownMenuCheckboxItem, DropdownMenuRadioGroup, DropdownMenuSubMenu.',
+        'The grouped rows: DropdownMenuItem, DropdownMenuCheckboxItem, DropdownMenuRadioGroup, or DropdownMenuSubMenu.',
     },
     {
       name: 'xstyle',
       type: 'StyleXStyles',
       description:
-        'StyleX styles applied to the group wrapper. Must be a stylex.create() value: not an inline style object like style={{}}.',
+        'StyleX styles applied to the role="group" wrapper. Must be a stylex.create() value, not an inline style object.',
+    },
+    {
+      name: 'className',
+      type: 'string',
+      description: 'CSS class name applied to the role="group" wrapper.',
+    },
+    {
+      name: 'style',
+      type: 'React.CSSProperties',
+      description: 'Inline styles applied to the role="group" wrapper.',
+    },
+    {
+      name: 'ref',
+      type: 'React.Ref<HTMLDivElement>',
+      description: 'Ref forwarded to the role="group" wrapper.',
     },
   ],
   theming: {
@@ -39,15 +100,113 @@ export const docs = {
   },
 };
 
-export const docsDense = {
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
+export const docsZh = {
   name: 'DropdownMenuGroup',
-  isHiddenFromOverview: true,
+  subComponentOf: 'DropdownMenu',
   displayName: 'Dropdown Menu Group',
+  isHiddenFromOverview: true,
+  description:
+    '复合菜单中的一组菜单行。可见标题通过 aria-labelledby 为 role="group" 命名；省略标题时该组没有名称。标题不是 menuitem，因此方向键和预输入会跳过它。标题内容应保持非交互；控件应放在 DropdownMenu 的 header 或 footer 中。',
+  usage: {
+    description:
+      '使用 DropdownMenuGroup 为相关的复合菜单行提供同一个可见名称和无障碍名称。只有当名称能帮助理解这些菜单行时才使用分组。',
+    bestPractices: [
+      {guidance: true, description: '使用简短且能说明菜单行关系的标题。'},
+      {
+        guidance: true,
+        description: '保持标题非交互，让所有操作都位于菜单的方向键顺序中。',
+      },
+      {
+        guidance: false,
+        description:
+          '在标题中放置按钮、链接或输入控件；应改用 DropdownMenu 的 header 或 footer。',
+      },
+      {guidance: false, description: '对没有共同含义的菜单行进行分组。'},
+    ],
+    anatomy: [
+      {
+        name: '组',
+        required: true,
+        description: '包含标题和菜单行的 role="group" 包装元素。',
+      },
+      {
+        name: '标题',
+        required: false,
+        description: '用于命名分组的可见非交互标题内容。',
+      },
+      {
+        name: '菜单行',
+        required: false,
+        description: '由 DropdownMenu 持有的菜单项、可选项、单选组或子菜单。',
+      },
+    ],
+  },
+  props: [
+    {
+      name: 'title',
+      type: 'ReactNode',
+      description:
+        '显示在菜单行上方并作为分组无障碍名称的非交互标题内容。省略时分组无名称；控件应放在 DropdownMenu 的 header 或 footer 中。',
+    },
+    {name: 'children', type: 'ReactNode', description: '该分组中的菜单行。'},
+    {
+      name: 'xstyle',
+      type: 'StyleXStyles',
+      description: '应用于 role="group" 包装元素的 StyleX 样式。',
+    },
+    {
+      name: 'className',
+      type: 'string',
+      description: '应用于 role="group" 包装元素的 CSS 类名。',
+    },
+    {
+      name: 'style',
+      type: 'React.CSSProperties',
+      description: '应用于 role="group" 包装元素的内联样式。',
+    },
+    {
+      name: 'ref',
+      type: 'React.Ref<HTMLDivElement>',
+      description: '转发到 role="group" 包装元素的 ref。',
+    },
+  ],
+  theming: {
+    targets: [{className: 'astryx-dropdown-menu-section-heading'}],
+  },
+};
+
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
+export const docsDense = {
   description:
-    'titled role="group" of rows for compound menus; compound peer of the data API\'s {type: "section"}',
+    'named role="group" of compound-menu rows; compound peer of the data API\'s {type: "section"}',
+  usage: {
+    description:
+      'Use to give related compound-menu rows one visible and programmatic name.',
+    bestPractices: [
+      {
+        guidance: true,
+        description: "Short title that explains the rows' relationship.",
+      },
+      {
+        guidance: true,
+        description:
+          'Non-interactive title keeps every action in menu arrow navigation.',
+      },
+      {
+        guidance: false,
+        description:
+          'Controls in title. Put them in DropdownMenu header or footer instead.',
+      },
+      {guidance: false, description: 'Group unrelated rows.'},
+    ],
+  },
   propDescriptions: {
-    title: 'heading above the rows; names the group',
-    children: 'the rows of the group',
-    xstyle: 'StyleX styles applied to the group wrapper',
+    title: 'non-interactive heading above the rows; names the group',
+    children: 'the grouped menu rows',
+    xstyle: 'StyleX styles on the role="group" wrapper',
+    className: 'CSS class on the role="group" wrapper',
+    style: 'inline styles on the role="group" wrapper',
+    ref: 'ref forwarded to the role="group" wrapper',
   },
 };

package/src/DropdownMenu/DropdownMenuGroup.tsx

@@ -53,7 +53,8 @@ export interface DropdownMenuGroupProps extends Pick<
 > {
   /**
    * Heading shown above the group's rows and used as the group's accessible
-   * name (`aria-labelledby`). Omit it for an unnamed group.
+   * name (`aria-labelledby`). Omit it for an unnamed group. Keep this content
+   * non-interactive; controls belong in DropdownMenu's `header` or `footer`.
    */
   title?: ReactNode;
   /** The rows of the group: menu items, selectable items, sub-menus. */
@@ -65,9 +66,10 @@ export interface DropdownMenuGroupProps extends Pick<
 /**
  * A titled group of menu rows.
  *
- * Renders `role="group"` named by its heading. The heading is plain text, not
- * a `menuitem`, so it is never a stop in the menu's arrow-key order and
- * typeahead never lands on it. The compound peer of
+ * Renders `role="group"` named by its heading. The heading is not a
+ * `menuitem`, so arrow-key navigation and typeahead skip it. Keep heading
+ * content non-interactive; place controls in DropdownMenu's `header` or
+ * `footer`. The compound peer of
  * `{type: 'section', title, items}` in the `items` data API.
  *
  * @example

package/src/DropdownMenu/DropdownMenuLazySheet.test.tsx

@@ -0,0 +1,126 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file DropdownMenuLazySheet.test.tsx
+ * @input Uses DropdownMenu, Testing Library, and a held module load
+ * @output Tests DropdownMenu while its on-demand touch sheet is still loading
+ * @position Test file for DropdownMenu
+ *
+ * This file never warms the sheet, and it checks that a popover menu never
+ * requests it: each test holds the sheet modules until it
+ * releases them, so it exercises the path a real page takes while the sheet's
+ * code is still downloading.
+ */
+
+import {describe, it, expect, vi, beforeAll, beforeEach} from 'vitest';
+import {render, screen, waitFor, act} from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import type {DropdownMenu as DropdownMenuComponent} from './DropdownMenu';
+
+const sheetLoad = vi.hoisted(() => {
+  let release: () => void = () => {};
+  const gate = new Promise<void>(resolve => {
+    release = resolve;
+  });
+  return {gate, release: () => release(), requested: [] as string[]};
+});
+
+vi.mock('./MenuBottomSheet', async importOriginal => {
+  sheetLoad.requested.push('MenuBottomSheet');
+  await sheetLoad.gate;
+  return importOriginal();
+});
+
+vi.mock('./MenuBottomSheetActionList', async importOriginal => {
+  sheetLoad.requested.push('MenuBottomSheetActionList');
+  await sheetLoad.gate;
+  return importOriginal();
+});
+
+let DropdownMenu: typeof DropdownMenuComponent;
+
+// If any module the dropdown loads imported the sheet eagerly, this import
+// would wait on the held sheet and the hook would time out.
+beforeAll(async () => {
+  ({DropdownMenu} = await import('./DropdownMenu'));
+}, 10000);
+
+beforeEach(() => {
+  HTMLDialogElement.prototype.showModal = 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(),
+    })),
+  );
+});
+
+describe('DropdownMenu touch sheet loaded on demand', () => {
+  // Runs first: nothing in this file has rendered a sheet yet.
+  it('never loads the sheet for a popover menu', async () => {
+    const user = userEvent.setup();
+    HTMLElement.prototype.showPopover = vi.fn();
+    HTMLElement.prototype.hidePopover = vi.fn();
+    render(
+      <DropdownMenu
+        button={{label: 'Actions'}}
+        items={[{label: 'Edit project'}, {label: 'Delete'}]}
+      />,
+    );
+
+    await user.click(screen.getByRole('button', {name: /Actions/}));
+    await act(async () => {
+      await new Promise(resolve => setTimeout(resolve, 50));
+    });
+
+    // Importing DropdownMenu and opening a popover menu requested neither
+    // sheet module, so no other module the dropdown loads imports it eagerly.
+    expect(sheetLoad.requested).toEqual([]);
+  });
+
+  it('focuses the first action when a keyboard open beats the sheet load', async () => {
+    const user = userEvent.setup();
+    render(
+      <DropdownMenu
+        button={{label: 'Actions'}}
+        presentation="bottom-sheet"
+        items={[{label: 'Edit project'}, {label: 'Delete'}]}
+      />,
+    );
+
+    const trigger = screen.getByRole('button', {name: /Actions/});
+    trigger.focus();
+    await user.keyboard('{Enter}');
+    // The open has committed, but the sheet's code has not arrived yet.
+    await act(async () => {
+      await new Promise(resolve => setTimeout(resolve, 50));
+    });
+    expect(screen.queryByRole('button', {name: 'Edit project'})).toBeNull();
+
+    await act(async () => {
+      sheetLoad.release();
+    });
+
+    await waitFor(
+      () =>
+        expect(
+          screen.getByRole('button', {name: 'Edit project'}),
+        ).toHaveFocus(),
+      {timeout: 15000},
+    );
+  }, 20000);
+});

package/src/DropdownMenu/DropdownMenuRadioItem.doc.mjs

@@ -43,7 +43,7 @@ export const docs = {
       name: 'icon',
       type: 'IconType',
       description:
-        'Icon to display before the label. See `npx @astryxdesign/cli docs icons` for valid semantic names.',
+        'Icon to display before the label. See `astryx docs icons` for valid semantic names.',
     },
     {
       name: 'isDisabled',

package/src/DropdownMenu/DropdownMenuRadioItem.tsx

@@ -93,7 +93,7 @@ export interface DropdownMenuRadioItemProps extends Omit<
   description?: ReactNode;
   /**
    * Icon to display before the label. Accepts a semantic icon name (see
-   * `npx @astryxdesign/cli docs icons`) or a rendered node.
+   * `astryx docs icons`) or a rendered node.
    */
   icon?: ReactNode | IconType;
   /**