@astryxdesign/core 0.7.1-canary.e199fa4 → 0.7.1-canary.e71c4e9

package/dist/CommandPalette/CommandPalette.d.ts

@@ -1,6 +1,7 @@
 /**
  * @file CommandPalette.tsx
- * @input Uses React, Dialog, Layout, CommandPaletteContext, SearchSource, useCombobox, useAnnounce
+ * @input Uses React, Dialog, Layout, CommandPaletteContext, SearchSource,
+ *   useCombobox, useAnnounce, useAnnounceRenderedText
  * @output Exports CommandPalette root component and props
  * @position Core root component; dialog shell with searchSource-driven items
  *
@@ -84,9 +85,10 @@ export interface CommandPaletteProps<T extends SearchableItem = SearchableItem>
  * Uses `searchSource` for all search logic — same interface as Typeahead.
  * For static lists, use `createStaticSource` from `@astryxdesign/core/Typeahead`.
  *
- * Keyboard navigation is handled by `useCombobox` from Selector,
- * ensuring consistent arrow key, Home/End, Enter, and Escape behavior
- * across all combobox-pattern components.
+ * Keyboard navigation is handled by `useCombobox` from Selector for arrows,
+ * PageUp/PageDown, and Enter. Home/End remain native caret keys. Modal Escape
+ * dismissal delegates to Dialog's shared layer stack so nested surfaces handle
+ * the first press.
  *
  * Input and footer are rendered by default — only pass them to replace the defaults.
  *

package/dist/CommandPalette/CommandPalette.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CommandPalette.d.ts","sourceRoot":"","sources":["../../src/CommandPalette/CommandPalette.tsx"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AAEH,OAAO,EASL,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAGf,OAAO,KAAK,EAAC,YAAY,EAAE,cAAc,EAAC,MAAM,cAAc,CAAC;AAU/D,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAI5C,MAAM,WAAW,mBAAmB,CAClC,CAAC,SAAS,cAAc,GAAG,cAAc,CACzC,SAAQ,IAAI,CAAC,SAAS,CAAC,iBAAiB,CAAC,EAAE,UAAU,CAAC;IACtD,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;IACnC,2CAA2C;IAC3C,MAAM,EAAE,OAAO,CAAC;IAEhB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB,0DAA0D;IAC1D,YAAY,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IAExC;;;;OAIG;IACH,YAAY,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC;IAE9B;;;OAGG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC;IAElB;;;OAGG;IACH,MAAM,CAAC,EAAE,SAAS,CAAC;IAEnB;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,UAAU,EAAE,OAAO,KAAK,SAAS,CAAC;IAEzD;;;OAGG;IACH,eAAe,CAAC,EAAE,SAAS,CAAC;IAE5B;;;OAGG;IACH,kBAAkB,CAAC,EAAE,SAAS,CAAC;IAE/B,mDAAmD;IACnD,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,8CAA8C;IAC9C,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAExC;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAExB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAC7B;AAiID;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,cAAc,GAAG,cAAc,EAAE,EACxE,GAAG,EACH,MAAM,EACN,QAAQ,EACR,YAAY,EACZ,YAAY,EACZ,KAAK,EACL,MAAM,EACN,UAAU,EACV,eAAe,EAAE,wBAAwB,EACzC,kBAAkB,EAAE,2BAA2B,EAC/C,KAAK,EAAE,eAAe,EACtB,aAAa,EACb,KAAK,EAAE,cAAc,EACrB,KAAW,EACX,SAAe,EACf,GAAG,IAAI,EACR,EAAE,mBAAmB,CAAC,CAAC,CAAC,+BAsXxB;yBAvYe,cAAc"}
+{"version":3,"file":"CommandPalette.d.ts","sourceRoot":"","sources":["../../src/CommandPalette/CommandPalette.tsx"],"names":[],"mappings":"AAGA;;;;;;;;;;GAUG;AAEH,OAAO,EASL,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAGf,OAAO,KAAK,EAAC,YAAY,EAAE,cAAc,EAAC,MAAM,cAAc,CAAC;AAU/D,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAK5C,MAAM,WAAW,mBAAmB,CAClC,CAAC,SAAS,cAAc,GAAG,cAAc,CACzC,SAAQ,IAAI,CAAC,SAAS,CAAC,iBAAiB,CAAC,EAAE,UAAU,CAAC;IACtD,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;IACnC,2CAA2C;IAC3C,MAAM,EAAE,OAAO,CAAC;IAEhB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB,0DAA0D;IAC1D,YAAY,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IAExC;;;;OAIG;IACH,YAAY,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC;IAE9B;;;OAGG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC;IAElB;;;OAGG;IACH,MAAM,CAAC,EAAE,SAAS,CAAC;IAEnB;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,UAAU,EAAE,OAAO,KAAK,SAAS,CAAC;IAEzD;;;OAGG;IACH,eAAe,CAAC,EAAE,SAAS,CAAC;IAE5B;;;OAGG;IACH,kBAAkB,CAAC,EAAE,SAAS,CAAC;IAE/B,mDAAmD;IACnD,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,8CAA8C;IAC9C,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAExC;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAExB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAC7B;AAiID;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,cAAc,GAAG,cAAc,EAAE,EACxE,GAAG,EACH,MAAM,EACN,QAAQ,EACR,YAAY,EACZ,YAAY,EACZ,KAAK,EACL,MAAM,EACN,UAAU,EACV,eAAe,EAAE,wBAAwB,EACzC,kBAAkB,EAAE,2BAA2B,EAC/C,KAAK,EAAE,eAAe,EACtB,aAAa,EACb,KAAK,EAAE,cAAc,EACrB,KAAW,EACX,SAAe,EACf,GAAG,IAAI,EACR,EAAE,mBAAmB,CAAC,CAAC,CAAC,+BA2YxB;yBA5Ze,cAAc"}

package/dist/CommandPalette/CommandPalette.js

@@ -4,7 +4,8 @@
 
 /**
  * @file CommandPalette.tsx
- * @input Uses React, Dialog, Layout, CommandPaletteContext, SearchSource, useCombobox, useAnnounce
+ * @input Uses React, Dialog, Layout, CommandPaletteContext, SearchSource,
+ *   useCombobox, useAnnounce, useAnnounceRenderedText
  * @output Exports CommandPalette root component and props
  * @position Core root component; dialog shell with searchSource-driven items
  *
@@ -24,6 +25,7 @@ import { CommandPaletteInput } from "./CommandPaletteInput.js";
 import { CommandPaletteFooter } from "./CommandPaletteFooter.js";
 import { CommandPaletteEmpty } from "./CommandPaletteEmpty.js";
 import { useAnnounce } from "../hooks/useAnnounce.js";
+import { useAnnounceRenderedText } from "../hooks/useAnnounceRenderedText.js";
 import { useTranslator } from "../i18n/index.js";
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 function getGroup(item) {
@@ -145,9 +147,10 @@ function ItemRenderer({
  * Uses `searchSource` for all search logic — same interface as Typeahead.
  * For static lists, use `createStaticSource` from `@astryxdesign/core/Typeahead`.
  *
- * Keyboard navigation is handled by `useCombobox` from Selector,
- * ensuring consistent arrow key, Home/End, Enter, and Escape behavior
- * across all combobox-pattern components.
+ * Keyboard navigation is handled by `useCombobox` from Selector for arrows,
+ * PageUp/PageDown, and Enter. Home/End remain native caret keys. Modal Escape
+ * dismissal delegates to Dialog's shared layer stack so nested surfaces handle
+ * the first press.
  *
  * Input and footer are rendered by default — only pass them to replace the defaults.
  *
@@ -200,6 +203,7 @@ export function CommandPalette({
   const [optimisticResults, setOptimisticResults] = useOptimistic(searchResults);
   const isBusy = isPending;
   const searchVersionRef = useRef(0);
+  const emptyStateRef = useRef(null);
 
   // Announce search status to screen readers through the shared polite live
   // region (comboboxes-7 announce path, mirroring Selector / BaseTypeahead).
@@ -267,6 +271,10 @@ export function CommandPalette({
   const runSearch = useCallback(query => {
     searchSource.cancel?.();
     const version = ++searchVersionRef.current;
+    // A highlight belongs to the query that created it. Clear it before any
+    // optimistic narrowing so aria-activedescendant never shifts to a
+    // different command at the same index while the next result set loads.
+    combobox.setHighlightedIndex(-1);
     startTransition(async () => {
       const isBootstrap = query === '';
 
@@ -293,18 +301,12 @@ export function CommandPalette({
 
         // Announce the outcome from the search commit (not a reactive
         // effect), matching Selector / BaseTypeahead: exactly one
-        // announcement per committed query, and the version check above
-        // already discards stale keystrokes. Bootstrap stays silent — the
-        // same role PowerSearch's mount guard plays — so opening the
-        // palette announces nothing; clearing the query only clears any
-        // lingering status text.
+        // announcement per committed non-empty query. Empty results are
+        // announced from their rendered content below so a caller-supplied
+        // ReactNode reaches assistive technology as written.
         if (isBootstrap) {
           announce('');
-        } else if (items.length === 0) {
-          announce(t('@astryx.commandPalette.noResultsFor', {
-            query
-          }));
-        } else {
+        } else if (items.length > 0) {
           announce(t('@astryx.commandPalette.resultCount', {
             count: items.length
           }));
@@ -346,13 +348,18 @@ export function CommandPalette({
     }
   }, [isOpen]);
 
-  // Wrap combobox's onKeyDown to intercept Escape (close palette) and
-  // Enter on highlight (select + close), since we're not using combobox's
-  // built-in open/close lifecycle.
+  // Wrap combobox's onKeyDown to preserve inline-preview Escape handling and
+  // select + close on Enter. Modal Escape stays unclaimed here so Dialog's
+  // shared dismissal stack can route it to the topmost surface.
   const handleKeyDown = useCallback(e => {
     if (e.key === 'Escape') {
-      e.preventDefault();
-      handleClose();
+      // Modal CommandPalette delegates Escape to Dialog's shared dismissal
+      // stack so a nested layer handles the first press. Inline previews do
+      // not join that stack, so preserve their local close behavior.
+      if (isInline) {
+        e.preventDefault();
+        handleClose();
+      }
       return;
     }
     if (e.key === 'Enter') {
@@ -366,12 +373,17 @@ export function CommandPalette({
       }
       return;
     }
+    // Home and End remain native caret-movement keys for this editable
+    // combobox. PageUp/PageDown provide first/last result navigation.
+    if (e.key === 'Home' || e.key === 'End') {
+      return;
+    }
     // Space should type in the input, not trigger selection
     if (e.key === ' ') {
       return;
     }
     combobox.onKeyDown(e);
-  }, [combobox, handleClose, selectableItems, selectItem]);
+  }, [combobox, handleClose, isInline, selectableItems, selectItem]);
 
   // Hover highlight is owned here by a single delegated handler on the list
   // container: it routes to useCombobox's hover-aware path, which moves the
@@ -427,13 +439,19 @@ export function CommandPalette({
   // the empty state is never unmounted and re-added mid-search (which flashed).
   const showEmptyBootstrap = search === '' && optimisticResults.length === 0;
   const showEmptySearch = search !== '' && optimisticResults.length === 0;
+  // Announce only once the search settles: while it is pending, optimistic
+  // narrowing can empty the list before the source answers, which would
+  // speak "No results" early or wrongly.
+  useAnnounceRenderedText(emptyStateRef, showEmptySearch && !isPending, search);
   let listContent;
   if (showEmptyBootstrap) {
     listContent = /*#__PURE__*/_jsx(CommandPaletteEmpty, {
+      ref: emptyStateRef,
       children: emptyBootstrapText
     });
   } else if (showEmptySearch) {
     listContent = /*#__PURE__*/_jsx(CommandPaletteEmpty, {
+      ref: emptyStateRef,
       children: emptySearchText
     });
   } else {

package/dist/CommandPalette/CommandPaletteEmpty.d.ts

@@ -12,13 +12,14 @@ export interface CommandPaletteEmptyProps extends BaseProps<HTMLDivElement> {
  * - `emptyBootstrapText`: no search term and bootstrap() returns nothing
  * - `emptySearchText`: a search query returned no results
  *
- * Can also be composed manually inside a custom render function.
+ * Can also be composed as a standalone empty result surface. Render actionable
+ * empty content outside listbox and option semantics.
  *
  * @example
  * ```
  * <CommandPalette
- *   emptyBootstrapText={<CommandPaletteEmpty>Start typing to search</CommandPaletteEmpty>}
- *   emptySearchText={<CommandPaletteEmpty>No results found</CommandPaletteEmpty>}
+ *   emptyBootstrapText="Start typing to search"
+ *   emptySearchText="No results found"
  *   searchSource={source}
  * />
  * ```

package/dist/CommandPalette/CommandPaletteEmpty.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CommandPaletteEmpty.d.ts","sourceRoot":"","sources":["../../src/CommandPalette/CommandPaletteEmpty.tsx"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,EAAC,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAS5C,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAkB5C,MAAM,WAAW,wBAAyB,SAAQ,SAAS,CAAC,cAAc,CAAC;IACzE,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC,yCAAyC;IACzC,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,mBAAmB,CAAC,EAClC,GAAG,EACH,QAAQ,EACR,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,KAAK,EACT,EAAE,wBAAwB,qBAc1B;yBArBe,mBAAmB"}
+{"version":3,"file":"CommandPaletteEmpty.d.ts","sourceRoot":"","sources":["../../src/CommandPalette/CommandPaletteEmpty.tsx"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,EAAC,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAS5C,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAkB5C,MAAM,WAAW,wBAAyB,SAAQ,SAAS,CAAC,cAAc,CAAC;IACzE,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC,yCAAyC;IACzC,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,mBAAmB,CAAC,EAClC,GAAG,EACH,QAAQ,EACR,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,KAAK,EACT,EAAE,wBAAwB,qBAc1B;yBArBe,mBAAmB"}

package/dist/CommandPalette/CommandPaletteEmpty.js

@@ -41,13 +41,14 @@ const styles = {
  * - `emptyBootstrapText`: no search term and bootstrap() returns nothing
  * - `emptySearchText`: a search query returned no results
  *
- * Can also be composed manually inside a custom render function.
+ * Can also be composed as a standalone empty result surface. Render actionable
+ * empty content outside listbox and option semantics.
  *
  * @example
  * ```
  * <CommandPalette
- *   emptyBootstrapText={<CommandPaletteEmpty>Start typing to search</CommandPaletteEmpty>}
- *   emptySearchText={<CommandPaletteEmpty>No results found</CommandPaletteEmpty>}
+ *   emptyBootstrapText="Start typing to search"
+ *   emptySearchText="No results found"
  *   searchSource={source}
  * />
  * ```

package/dist/CommandPalette/CommandPaletteInput.d.ts

@@ -6,6 +6,7 @@
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /apps/storybook/stories/CommandPalette.stories.tsx
+ * - /apps/storybook/stories/CommandPaletteInput.stories.tsx
  * - /packages/cli/assets/templates/blocks/components/CommandPalette/ (showcase blocks)
  */
 import { type ReactNode } from 'react';
@@ -25,13 +26,13 @@ export interface CommandPaletteInputProps extends Omit<BaseProps<HTMLInputElemen
     onValueChange?: (value: string) => void;
     /**
      * Placeholder text for the input.
-     * @default 'Search...'
+     * @default 'Search…'
      */
     placeholder?: string;
     /**
-     * Accessible label for the combobox input, announced by screen readers.
-     * Falls back to the placeholder text (`'Search…'` by default), since a
-     * placeholder alone is not a reliable accessible name.
+     * Accessible label for the query field, announced by screen readers. The
+     * placeholder is never the field's name.
+     * @default 'Search commands'
      */
     label?: string;
     /**

package/dist/CommandPalette/CommandPaletteInput.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CommandPaletteInput.d.ts","sourceRoot":"","sources":["../../src/CommandPalette/CommandPaletteInput.tsx"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AAEH,OAAO,EAAiC,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAarE,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAkE5C,MAAM,WAAW,wBAAyB,SAAQ,IAAI,CACpD,SAAS,CAAC,gBAAgB,CAAC,EAC3B,UAAU,CACX;IACC,iEAAiE;IACjE,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;IAElC;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAExC;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IAEvB;;;;OAIG;IACH,UAAU,CAAC,EAAE,SAAS,CAAC;IAEvB,qDAAqD;IACrD,QAAQ,CAAC,EAAE,KAAK,CAAC,kBAAkB,CAAC,gBAAgB,CAAC,CAAC;CACvD;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,mBAAmB,CAAC,EAClC,KAAK,EAAE,eAAe,EACtB,aAAa,EACb,WAAW,EAAE,oBAAoB,EACjC,KAAK,EACL,YAAmB,EACnB,UAAU,EACV,QAAQ,EACR,SAAS,EACT,GAAG,EACH,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,KAAK,EACT,EAAE,wBAAwB,+BAuF1B;yBArGe,mBAAmB"}
+{"version":3,"file":"CommandPaletteInput.d.ts","sourceRoot":"","sources":["../../src/CommandPalette/CommandPaletteInput.tsx"],"names":[],"mappings":"AAGA;;;;;;;;;;GAUG;AAEH,OAAO,EAAiC,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAarE,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAkE5C,MAAM,WAAW,wBAAyB,SAAQ,IAAI,CACpD,SAAS,CAAC,gBAAgB,CAAC,EAC3B,UAAU,CACX;IACC,iEAAiE;IACjE,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;IAElC;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAExC;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IAEvB;;;;OAIG;IACH,UAAU,CAAC,EAAE,SAAS,CAAC;IAEvB,qDAAqD;IACrD,QAAQ,CAAC,EAAE,KAAK,CAAC,kBAAkB,CAAC,gBAAgB,CAAC,CAAC;CACvD;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,mBAAmB,CAAC,EAClC,KAAK,EAAE,eAAe,EACtB,aAAa,EACb,WAAW,EAAE,oBAAoB,EACjC,KAAK,EACL,YAAmB,EACnB,UAAU,EACV,QAAQ,EACR,SAAS,EACT,GAAG,EACH,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,KAAK,EACT,EAAE,wBAAwB,+BA2I1B;yBAzJe,mBAAmB"}

package/dist/CommandPalette/CommandPaletteInput.js

@@ -10,13 +10,14 @@
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /apps/storybook/stories/CommandPalette.stories.tsx
+ * - /apps/storybook/stories/CommandPaletteInput.stories.tsx
  * - /packages/cli/assets/templates/blocks/components/CommandPalette/ (showcase blocks)
  */
 import { useCallback, useEffect, useRef } from 'react';
 import * as stylex from '@stylexjs/stylex';
 import { Icon } from "../Icon/index.js";
 import { Spinner } from "../Spinner/index.js";
-import { mergeProps } from "../utils/index.js";
+import { isImeKeyEvent, isRenderable, mergeProps } from "../utils/index.js";
 import "../theme/tokens.stylex.js";
 import { colorVars, typeScaleVars, spacingVars, typographyVars } from "../theme/tokens.stylex.js";
 import { useCommandPaletteContext } from "./CommandPaletteContext.js";
@@ -73,12 +74,26 @@ export function CommandPaletteInput({
   const t = useTranslator();
   const placeholder = placeholderFromProps ?? t('@astryx.commandPalette.input.placeholder');
   const ctx = useCommandPaletteContext();
+  // Inside CommandPalette the results surface is a listbox only while it holds
+  // selectable results; empty and pending states expose no popup.
+  const hasListbox = ctx ? ctx.selectableItems.length > 0 : true;
   const dialogContext = useDialogContext();
   const inputRef = useRef(null);
 
   // Use context values as fallback
   const value = controlledValue ?? ctx?.search;
   const handleValueChange = onValueChange ?? ctx?.setSearch;
+  const accessibleLabel = props['aria-label'] ?? label ?? t('@astryx.commandPalette.input.label');
+  const hasEndContent = isRenderable(endContent);
+  // A popup attribute the caller passes is caller-owned even while its value
+  // is undefined (`aria-expanded={open || undefined}`), so the role stays
+  // stable as the caller's popup opens and closes, and a present value is
+  // passed through unchanged.
+  // `aria-haspopup` counts unless it says there is no popup.
+  const callerSets = key => Object.hasOwn(props, key);
+  const callerDeclaresPopup = callerSets('aria-haspopup') && props['aria-haspopup'] !== false && props['aria-haspopup'] !== 'false';
+  const callerOwnsPopup = !ctx && (props.role === 'combobox' || callerSets('aria-expanded') || callerSets('aria-autocomplete') || callerSets('aria-controls') || callerSets('aria-owns') || callerSets('aria-activedescendant') || callerDeclaresPopup);
+  const standaloneRole = callerSets('role') ? props.role : callerOwnsPopup ? 'combobox' : 'searchbox';
 
   // When rendered inside an inline dialog, disable auto-focus by default
   // to avoid stealing focus from the surrounding page.
@@ -96,7 +111,10 @@ export function CommandPaletteInput({
   // Keyboard navigation — delegates to useCombobox via context
   const handleKeyDown = useCallback(e => {
     onKeyDown?.(e);
-    if (e.defaultPrevented) {
+    if (e.defaultPrevented || isImeKeyEvent(e.nativeEvent)) {
+      // An in-progress IME composition owns Enter, Escape, and arrows. Let
+      // the input method finish or cancel composition without selecting or
+      // dismissing palette content.
       return;
     }
     // Delegate to useCombobox's keyboard handler from context
@@ -114,17 +132,20 @@ export function CommandPaletteInput({
         color: "inherit"
       })
     }), /*#__PURE__*/_jsx("input", {
+      ...props,
       ref: useMergedRefs(ref, inputRef),
+      ...{
+        className: "x98rzlu xeuugli xc342km xng3xce x1a2a7pz xjbqb8w x1tgivj0 x9ynric xjm74w1 xf9zqsd xw6l6zx x1717udv xeyghm5"
+      },
       type: "text",
-      role: "combobox",
-      "aria-expanded": ctx?.isOpen ?? true,
-      "aria-autocomplete": "list",
-      "aria-controls": ctx?.listId,
-      "aria-activedescendant": ctx && ctx.highlightedIndex >= 0 ? ctx.getItemId(ctx.highlightedIndex) : undefined
-      // A placeholder alone is not a reliable accessible name; give the
-      // combobox an explicit one (consumer aria-label via rest props wins).
+      role: ctx ? 'combobox' : standaloneRole,
+      "aria-expanded": ctx ? ctx.isOpen && hasListbox : callerSets('aria-expanded') ? props['aria-expanded'] : callerOwnsPopup || undefined,
+      "aria-autocomplete": ctx ? 'list' : callerSets('aria-autocomplete') ? props['aria-autocomplete'] : callerOwnsPopup ? 'list' : undefined,
+      "aria-controls": ctx ? hasListbox ? ctx.listId : undefined : props['aria-controls'],
+      "aria-activedescendant": ctx ? hasListbox && ctx.highlightedIndex >= 0 && ctx.highlightedIndex < ctx.selectableItems.length ? ctx.getItemId(ctx.highlightedIndex) : undefined : props['aria-activedescendant']
+      // Placeholder text is never the field's name (AST-056 AR2).
       ,
-      "aria-label": label ?? placeholder,
+      "aria-label": accessibleLabel,
       placeholder: placeholder,
       value: value,
       "data-autofocus": effectiveAutoFocus || undefined,
@@ -132,12 +153,8 @@ export function CommandPaletteInput({
         handleValueChange?.(e.target.value);
         onChange?.(e);
       },
-      onKeyDown: handleKeyDown,
-      ...{
-        className: "x98rzlu xeuugli xc342km xng3xce x1a2a7pz xjbqb8w x1tgivj0 x9ynric xjm74w1 xf9zqsd xw6l6zx x1717udv xeyghm5"
-      },
-      ...props
-    }), (ctx?.isBusy || endContent) && /*#__PURE__*/_jsxs("span", {
+      onKeyDown: handleKeyDown
+    }), (ctx?.isBusy || hasEndContent) && /*#__PURE__*/_jsxs("span", {
       ...{
         className: "x78zum5 x6s0dn4 xzye2dw x2lah0s"
       },
@@ -148,8 +165,8 @@ export function CommandPaletteInput({
         children: /*#__PURE__*/_jsx(Spinner, {
           size: "sm"
         })
-      }), endContent]
-    }), ' ']
+      }), hasEndContent && endContent]
+    })]
   });
 }
 CommandPaletteInput.displayName = 'CommandPaletteInput';

package/dist/CommandPalette/CommandPaletteList.d.ts

@@ -16,8 +16,10 @@ export interface CommandPaletteListProps extends BaseProps<HTMLDivElement> {
     label?: string;
 }
 /**
- * Scrollable results container for the command palette.
- * Renders as a listbox for ARIA compliance.
+ * Scrollable results container for the command palette. Standalone composition
+ * renders as a listbox. Inside CommandPalette, listbox semantics are present
+ * only while selectable results exist; empty and pending states retain the same
+ * styled container without exposing an empty interactive popup.
  *
  * When used inside CommandPalette, automatically gets the correct
  * ID for aria-controls linking with the input.

package/dist/CommandPalette/CommandPaletteList.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CommandPaletteList.d.ts","sourceRoot":"","sources":["../../src/CommandPalette/CommandPaletteList.tsx"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,OAAO,CAAC;AAErC,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAmB5C,MAAM,WAAW,uBAAwB,SAAQ,SAAS,CAAC,cAAc,CAAC;IACxE;;OAEG;IACH,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAEhC;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAC;IAEpB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,kBAAkB,CAAC,EACjC,QAAQ,EACR,KAAK,EAAE,cAAc,EACrB,GAAG,EACH,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,KAAK,EACT,EAAE,uBAAuB,+BAqBzB;yBA7Be,kBAAkB"}
+{"version":3,"file":"CommandPaletteList.d.ts","sourceRoot":"","sources":["../../src/CommandPalette/CommandPaletteList.tsx"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,OAAO,CAAC;AAErC,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAmB5C,MAAM,WAAW,uBAAwB,SAAQ,SAAS,CAAC,cAAc,CAAC;IACxE;;OAEG;IACH,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAEhC;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAC;IAEpB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,kBAAkB,CAAC,EACjC,QAAQ,EACR,KAAK,EAAE,cAAc,EACrB,GAAG,EACH,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,KAAK,EACT,EAAE,uBAAuB,+BAwBzB;yBAhCe,kBAAkB"}

package/dist/CommandPalette/CommandPaletteList.js

@@ -34,8 +34,10 @@ const styles = {
   }
 };
 /**
- * Scrollable results container for the command palette.
- * Renders as a listbox for ARIA compliance.
+ * Scrollable results container for the command palette. Standalone composition
+ * renders as a listbox. Inside CommandPalette, listbox semantics are present
+ * only while selectable results exist; empty and pending states retain the same
+ * styled container without exposing an empty interactive popup.
  *
  * When used inside CommandPalette, automatically gets the correct
  * ID for aria-controls linking with the input.
@@ -65,12 +67,15 @@ export function CommandPaletteList({
   const t = useTranslator();
   const label = labelFromProps ?? t('@astryx.commandPalette.list.label');
   const ctx = useCommandPaletteContext();
+  // Inside CommandPalette the list is a listbox only while it holds selectable
+  // results; standalone composition is always a listbox.
+  const hasListbox = ctx ? ctx.selectableItems.length > 0 : true;
   return /*#__PURE__*/_jsx("div", {
     ref: ref,
     ...props,
     id: ctx?.listId ?? props.id,
-    role: "listbox",
-    "aria-label": label,
+    role: hasListbox ? 'listbox' : undefined,
+    "aria-label": hasListbox ? label : undefined,
     ...mergeProps(themeProps('command-palette-list'), stylex.props(styles.list, xstyle), className, style),
     children: children
   });

package/dist/ContextMenu/ContextMenu.d.ts

@@ -1,7 +1,7 @@
 /**
  * @file ContextMenu.tsx
- * @input Uses React, StyleX, useLayer, BottomSheet, useListFocus, and the
- *   shared menu-presentation resolver
+ * @input Uses React, StyleX, useLayer, shared layer dismissal, BottomSheet,
+ *   useListFocus, and the shared menu-presentation resolver
  * @output Exports ContextMenu with cursor-popover and touch-sheet presentations
  * @position Core implementation; consumed by index.ts
  *
@@ -117,7 +117,7 @@ export type ContextMenuProps = ContextMenuDataProps | ContextMenuCompoundProps;
  * </ContextMenu>
  * ```
  */
-export declare function ContextMenu({ children, menuWidth, size, label: labelFromProps, isDisabled, onOpenChange, presentation, triggerAs, ref, className, style, xstyle, triggerXstyle, 'data-testid': testId, ...rest }: ContextMenuProps): React.JSX.Element;
+export declare function ContextMenu({ children, menuWidth, size, label: labelFromProps, isDisabled, onOpenChange, presentation, triggerAs, ref, className, style, xstyle, triggerXstyle, onContextMenu: onContextMenuProp, onTouchStart: onTouchStartProp, onTouchMove: onTouchMoveProp, onTouchEnd: onTouchEndProp, onTouchCancel: onTouchCancelProp, 'data-testid': testId, ...rest }: ContextMenuProps): React.JSX.Element;
 export declare namespace ContextMenu {
     var displayName: string;
 }

package/dist/ContextMenu/ContextMenu.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ContextMenu.d.ts","sourceRoot":"","sources":["../../src/ContextMenu/ContextMenu.tsx"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KASN,MAAM,OAAO,CAAC;AACf,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,OAAO,CAAC;AAkCrC,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,gBAAgB,CAAC;AAGjD,OAAO,KAAK,EACV,kBAAkB,EAClB,oBAAoB,EACpB,uBAAuB,EACvB,mBAAmB,EACpB,MAAM,8BAA8B,CAAC;AAGtC,OAAO,EAEL,KAAK,oBAAoB,EAC1B,MAAM,kCAAkC,CAAC;AA6G1C,MAAM,MAAM,mBAAmB,GAAG,oBAAoB,CAAC;AAEvD,MAAM,MAAM,sBAAsB,GAAG,uBAAuB,CAAC;AAE7D,MAAM,MAAM,kBAAkB,GAAG,mBAAmB,CAAC;AAErD,MAAM,MAAM,iBAAiB,GAAG,kBAAkB,CAAC;AAMnD,UAAU,oBAAqB,SAAQ,SAAS;IAC9C,oDAAoD;IACpD,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAC7B;;;;;OAKG;IACH,SAAS,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;IAC3B;;;;;OAKG;IACH,aAAa,CAAC,EAAE,YAAY,GAAG,YAAY,EAAE,CAAC;IAC9C,+DAA+D;IAC/D,QAAQ,EAAE,SAAS,CAAC;IACpB,0CAA0C;IAC1C,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC5B,wCAAwC;IACxC,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;IAC1B;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4EAA4E;IAC5E,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,4CAA4C;IAC5C,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IACzC;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,oBAAoB,CAAC;IACpC,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,UAAU,oBAAqB,SAAQ,oBAAoB;IACzD,gDAAgD;IAChD,KAAK,EAAE,iBAAiB,EAAE,CAAC;IAC3B,WAAW,CAAC,EAAE,SAAS,CAAC;CACzB;AAED,UAAU,wBAAyB,SAAQ,oBAAoB;IAC7D,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,+CAA+C;IAC/C,WAAW,EAAE,SAAS,CAAC;CACxB;AAED,MAAM,MAAM,gBAAgB,GAAG,oBAAoB,GAAG,wBAAwB,CAAC;AAM/E;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,WAAW,CAAC,EAC1B,QAAQ,EACR,SAAS,EACT,IAAW,EACX,KAAK,EAAE,cAAc,EACrB,UAAkB,EAClB,YAAY,EACZ,YAAwB,EACxB,SAAiB,EACjB,GAAG,EACH,SAAS,EACT,KAAK,EACL,MAAM,EACN,aAAa,EACb,aAAa,EAAE,MAAM,EACrB,GAAG,IAAI,EACR,EAAE,gBAAgB,qBA6clB;yBA7de,WAAW"}
+{"version":3,"file":"ContextMenu.d.ts","sourceRoot":"","sources":["../../src/ContextMenu/ContextMenu.tsx"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KASN,MAAM,OAAO,CAAC;AACf,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,OAAO,CAAC;AAoCrC,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,gBAAgB,CAAC;AAGjD,OAAO,KAAK,EACV,kBAAkB,EAClB,oBAAoB,EACpB,uBAAuB,EACvB,mBAAmB,EACpB,MAAM,8BAA8B,CAAC;AAGtC,OAAO,EAEL,KAAK,oBAAoB,EAC1B,MAAM,kCAAkC,CAAC;AA6G1C,MAAM,MAAM,mBAAmB,GAAG,oBAAoB,CAAC;AAEvD,MAAM,MAAM,sBAAsB,GAAG,uBAAuB,CAAC;AAE7D,MAAM,MAAM,kBAAkB,GAAG,mBAAmB,CAAC;AAErD,MAAM,MAAM,iBAAiB,GAAG,kBAAkB,CAAC;AAMnD,UAAU,oBAAqB,SAAQ,SAAS;IAC9C,oDAAoD;IACpD,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAC7B;;;;;OAKG;IACH,SAAS,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;IAC3B;;;;;OAKG;IACH,aAAa,CAAC,EAAE,YAAY,GAAG,YAAY,EAAE,CAAC;IAC9C,+DAA+D;IAC/D,QAAQ,EAAE,SAAS,CAAC;IACpB,0CAA0C;IAC1C,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC5B,wCAAwC;IACxC,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;IAC1B;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4EAA4E;IAC5E,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,4CAA4C;IAC5C,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IACzC;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,oBAAoB,CAAC;IACpC,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,UAAU,oBAAqB,SAAQ,oBAAoB;IACzD,gDAAgD;IAChD,KAAK,EAAE,iBAAiB,EAAE,CAAC;IAC3B,WAAW,CAAC,EAAE,SAAS,CAAC;CACzB;AAED,UAAU,wBAAyB,SAAQ,oBAAoB;IAC7D,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,+CAA+C;IAC/C,WAAW,EAAE,SAAS,CAAC;CACxB;AAED,MAAM,MAAM,gBAAgB,GAAG,oBAAoB,GAAG,wBAAwB,CAAC;AAM/E;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,WAAW,CAAC,EAC1B,QAAQ,EACR,SAAS,EACT,IAAW,EACX,KAAK,EAAE,cAAc,EACrB,UAAkB,EAClB,YAAY,EACZ,YAAwB,EACxB,SAAiB,EACjB,GAAG,EACH,SAAS,EACT,KAAK,EACL,MAAM,EACN,aAAa,EACb,aAAa,EAAE,iBAAiB,EAChC,YAAY,EAAE,gBAAgB,EAC9B,WAAW,EAAE,eAAe,EAC5B,UAAU,EAAE,cAAc,EAC1B,aAAa,EAAE,iBAAiB,EAChC,aAAa,EAAE,MAAM,EACrB,GAAG,IAAI,EACR,EAAE,gBAAgB,qBAoelB;yBAzfe,WAAW"}

package/dist/ContextMenu/ContextMenu.js

@@ -3,8 +3,8 @@
 
 /**
  * @file ContextMenu.tsx
- * @input Uses React, StyleX, useLayer, BottomSheet, useListFocus, and the
- *   shared menu-presentation resolver
+ * @input Uses React, StyleX, useLayer, shared layer dismissal, BottomSheet,
+ *   useListFocus, and the shared menu-presentation resolver
  * @output Exports ContextMenu with cursor-popover and touch-sheet presentations
  * @position Core implementation; consumed by index.ts
  *
@@ -39,6 +39,8 @@ import { Button } from "../Button/index.js";
 import { Heading } from "../Heading/index.js";
 import { Icon } from "../Icon/index.js";
 import { useLayer } from "../Layer/useLayer.js";
+import { LayerDepthProvider } from "../Layer/LayerDepthContext.js";
+import { useLayerDismissal } from "../Layer/useLayerDismissal.js";
 import { MenuBottomSheetActionList } from "../DropdownMenu/MenuBottomSheetActionList.js";
 import { renderDropdownItems } from "../DropdownMenu/renderDropdownItems.js";
 import { DropdownMenuContext } from "../DropdownMenu/DropdownMenuContext.js";
@@ -52,7 +54,7 @@ import { useLongPress } from "../hooks/useLongPress.js";
 import { layerAnimations } from "../Layer/layerAnimations.stylex.js";
 import "../theme/tokens.stylex.js";
 import { colorVars, spacingVars, radiusVars, durationVars, easeVars, shadowVars } from "../theme/tokens.stylex.js";
-import { mergeProps, isImeKeyEvent, rtlStyles } from "../utils/index.js";
+import { mergeProps, rtlStyles } from "../utils/index.js";
 import { themeProps } from "../utils/themeProps.js";
 import { useTranslator } from "../i18n/index.js";
 import { useMergedRefs } from "../hooks/useMergedRefs.js";
@@ -194,6 +196,11 @@ export function ContextMenu({
   style,
   xstyle,
   triggerXstyle,
+  onContextMenu: onContextMenuProp,
+  onTouchStart: onTouchStartProp,
+  onTouchMove: onTouchMoveProp,
+  onTouchEnd: onTouchEndProp,
+  onTouchCancel: onTouchCancelProp,
   'data-testid': testId,
   ...rest
 }) {
@@ -226,7 +233,6 @@ export function ContextMenu({
   // Element focused before the menu opened, restored when it closes so focus
   // does not fall to <body> after Escape or outside-click dismissal.
   const triggerFocusRef = useRef(null);
-  const sheetHeadingRef = useRef(null);
   const [isOpen, setIsOpen] = useState(false);
   const [submenuPath, setSubmenuPath] = useState([]);
   const currentSubmenu = submenuPath.at(-1);
@@ -274,16 +280,12 @@ export function ContextMenu({
       closeMenu();
     }
   }, [closeMenu]);
-  useEffect(() => {
-    if (!isOpen || submenuPath.length === 0) {
-      return;
-    }
-    const frame = requestAnimationFrame(() => {
-      sheetHeadingRef.current?.focus({
+  const setSheetHeadingRef = useCallback(node => {
+    if (node && isOpen && submenuPath.length > 0) {
+      node.focus({
         preventScroll: true
       });
-    });
-    return () => cancelAnimationFrame(frame);
+    }
   }, [isOpen, submenuPath.length]);
   const {
     listRef,
@@ -297,8 +299,15 @@ export function ContextMenu({
     boundarySelector: MENU_BOUNDARY_SELECTOR,
     // Menus wrap from the last row to the first and back.
     wrap: true,
-    hasPaging: true,
-    onEscape: closeMenu
+    hasPaging: true
+  });
+
+  // Join the shared stack so an Escape press dismisses exactly one top-most
+  // surface. BottomSheet owns its own dismissal path.
+  useLayerDismissal({
+    isActive: isOpen && !usesBottomSheet,
+    onDismiss: closeMenu,
+    getContainer: () => listRef.current
   });
 
   // Typeahead over the enabled menu items, matched on each row's LABEL alone.
@@ -329,32 +338,6 @@ export function ContextMenu({
       document.removeEventListener('mousedown', handleClickOutside);
     };
   }, [isOpen, closeMenu, listRef, usesBottomSheet]);
-
-  // Dismiss on Escape from anywhere while open. The menu div's own onKeyDown
-  // only fires when focus is inside the menu; a document-level listener is
-  // kept as a reliable fallback Escape path (e.g. if focus has moved out of
-  // the menu). Guards against IME composition-cancel.
-  useEffect(() => {
-    if (!isOpen || usesBottomSheet) {
-      return;
-    }
-    const handleEscape = e => {
-      if (e.key !== 'Escape') {
-        return;
-      }
-      if (isImeKeyEvent(e)) {
-        // Ignore Escape that is committing/cancelling an IME composition;
-        // see utils/ime.ts for why.
-        return;
-      }
-      e.preventDefault();
-      closeMenu();
-    };
-    document.addEventListener('keydown', handleEscape);
-    return () => {
-      document.removeEventListener('keydown', handleEscape);
-    };
-  }, [isOpen, closeMenu, usesBottomSheet]);
   const listKeyDown = useCallback(e => {
     // A submenu flyout renders inline inside this menu; its key events bubble
     // up here. Let that level own them — only handle events from this level.
@@ -447,13 +430,42 @@ export function ContextMenu({
   // held long enough (see useLongPress for timer/move-cancel/cleanup logic).
   // The hook also returns the imperative start/moveTo/cancel API the menu press
   // model drives; only its four touch handlers belong on the trigger element.
-  const longPress = useLongPress({
+  const {
+    onTouchStart: handleLongPressTouchStart,
+    onTouchMove: handleLongPressTouchMove,
+    onTouchEnd: handleLongPressTouchEnd,
+    onTouchCancel: handleLongPressTouchCancel
+  } = useLongPress({
     disabled: isDisabled,
     onLongPress: useCallback(point => {
       const rect = getAnchorBaseRect();
       openAtLocalPoint(rect ? point.x - rect.left : point.x, rect ? point.y - rect.top : point.y, triggerRef.current);
     }, [openAtLocalPoint, getAnchorBaseRect])
   });
+
+  // ContextMenu owns invocation and long-press cleanup. Consumer handlers are
+  // notified too, but preventing their default does not cancel component-owned
+  // behavior that the public API does not promise as cancelable.
+  const handleTriggerContextMenu = useCallback(event => {
+    handleContextMenu(event);
+    onContextMenuProp?.(event);
+  }, [handleContextMenu, onContextMenuProp]);
+  const handleTriggerTouchStart = useCallback(event => {
+    handleLongPressTouchStart(event);
+    onTouchStartProp?.(event);
+  }, [handleLongPressTouchStart, onTouchStartProp]);
+  const handleTriggerTouchMove = useCallback(event => {
+    handleLongPressTouchMove(event);
+    onTouchMoveProp?.(event);
+  }, [handleLongPressTouchMove, onTouchMoveProp]);
+  const handleTriggerTouchEnd = useCallback(event => {
+    handleLongPressTouchEnd();
+    onTouchEndProp?.(event);
+  }, [handleLongPressTouchEnd, onTouchEndProp]);
+  const handleTriggerTouchCancel = useCallback(event => {
+    handleLongPressTouchCancel();
+    onTouchCancelProp?.(event);
+  }, [handleLongPressTouchCancel, onTouchCancelProp]);
   const popoverXstyle = menuWidth ? styles.popoverCustomWidth(menuWidth) : styles.popover;
 
   // The drill-in view stack for sub-menus on a phone; the bottom sheet has
@@ -517,7 +529,7 @@ export function ContextMenu({
         isIconOnly: true,
         onClick: () => setSubmenuPath(path => path.slice(0, -1))
       }), /*#__PURE__*/_jsx(Heading, {
-        ref: sheetHeadingRef,
+        ref: setSheetHeadingRef,
         level: 3,
         tabIndex: -1,
         xstyle: [styles.sheetViewHeading, submenuPath.length === 0 && styles.sheetRootHeading],
@@ -537,11 +549,11 @@ export function ContextMenu({
     children: [/*#__PURE__*/_jsxs(TriggerElement, {
       ref: useMergedRefs(ref, triggerRef),
       ...triggerProps,
-      onContextMenu: handleContextMenu,
-      onTouchStart: longPress.onTouchStart,
-      onTouchMove: longPress.onTouchMove,
-      onTouchEnd: longPress.onTouchEnd,
-      onTouchCancel: longPress.onTouchCancel,
+      onContextMenu: handleTriggerContextMenu,
+      onTouchStart: handleTriggerTouchStart,
+      onTouchMove: handleTriggerTouchMove,
+      onTouchEnd: handleTriggerTouchEnd,
+      onTouchCancel: handleTriggerTouchCancel,
       "data-testid": testId,
       ...stylex.props(styles.trigger, ...(triggerXstyle ? Array.isArray(triggerXstyle) ? triggerXstyle : [triggerXstyle] : [])),
       children: [children, /*#__PURE__*/_jsx("span", {
@@ -564,7 +576,9 @@ export function ContextMenu({
         label: sheetLabel,
         children: renderedBottomSheetContent
       })
-    }) : layer.render(renderedMenu, {
+    }) : layer.render(/*#__PURE__*/_jsx(LayerDepthProvider, {
+      children: renderedMenu
+    }), {
       placement: 'below',
       alignment: 'start',
       xstyle: [popoverXstyle, layerAnimations.below]