@astryxdesign/core 0.4.6 → 0.4.7-canary.019ae5a

package/dist/Layer/LayerDepthContext.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @file LayerDepthContext.tsx
+ * @input React context
+ * @output Exports LayerDepthContext, useLayerDepth, LayerDepthProvider
+ * @position Layer system; how the dismissal stack learns which layer is nested
+ *   inside which.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/Layer/index.ts
+ * - /packages/core/src/Layer/useLayerDismissal.ts
+ *
+ * Nesting is read from the React tree rather than the DOM. Two reasons:
+ *
+ * - **Portals.** A nested overlay routinely renders into `document.body` or the
+ *   native top layer, so DOM containment reports it as a sibling of the layer
+ *   it is logically inside. React context flows through `createPortal`, so the
+ *   tree keeps the relationship the DOM loses.
+ * - **Same-commit mounts.** Depth is fixed during render. Effect order is not
+ *   available then and is misleading anyway: React runs child effects before
+ *   parent effects, so an inner layer registers first and looks "older" than
+ *   the outer layer that contains it.
+ *
+ * There is nothing to mount at the app root: the context defaults to 0, and
+ * each layer provides depth for its OWN content, so nesting composes on its own.
+ */
+import { type ReactNode } from 'react';
+/**
+ * How many layers deep the current subtree is. 0 at the app root; each layer
+ * increments it for its own content.
+ */
+export declare const LayerDepthContext: import("react").Context<number>;
+/**
+ * Read the current nesting depth. A layer calls this to learn its OWN depth —
+ * the depth of the subtree it is rendered into, before it pushes its content
+ * one level deeper.
+ */
+export declare function useLayerDepth(): number;
+/**
+ * Wrap a layer's content so any layer opened from inside it registers as
+ * nested. Takes no depth prop on purpose: it reads the ambient depth and adds
+ * one, so nesting composes without anyone tracking absolute numbers.
+ *
+ * Renders no DOM element — it is a context boundary only, which is why it takes
+ * no `xstyle`/`ref` and exposes no props interface.
+ */
+export declare function LayerDepthProvider({ children }: {
+    children: ReactNode;
+}): import("react").JSX.Element;
+export declare namespace LayerDepthProvider {
+    var displayName: string;
+}
+//# sourceMappingURL=LayerDepthContext.d.ts.map

package/dist/Layer/LayerDepthContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LayerDepthContext.d.ts","sourceRoot":"","sources":["../../src/Layer/LayerDepthContext.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAqB,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAEzD;;;GAGG;AACH,eAAO,MAAM,iBAAiB,iCAAmB,CAAC;AAGlD;;;;GAIG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,EAAC,QAAQ,EAAC,EAAE;IAAC,QAAQ,EAAE,SAAS,CAAA;CAAC,+BAGnE;yBAHe,kBAAkB"}

package/dist/Layer/LayerDepthContext.js

@@ -0,0 +1,66 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file LayerDepthContext.tsx
+ * @input React context
+ * @output Exports LayerDepthContext, useLayerDepth, LayerDepthProvider
+ * @position Layer system; how the dismissal stack learns which layer is nested
+ *   inside which.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/Layer/index.ts
+ * - /packages/core/src/Layer/useLayerDismissal.ts
+ *
+ * Nesting is read from the React tree rather than the DOM. Two reasons:
+ *
+ * - **Portals.** A nested overlay routinely renders into `document.body` or the
+ *   native top layer, so DOM containment reports it as a sibling of the layer
+ *   it is logically inside. React context flows through `createPortal`, so the
+ *   tree keeps the relationship the DOM loses.
+ * - **Same-commit mounts.** Depth is fixed during render. Effect order is not
+ *   available then and is misleading anyway: React runs child effects before
+ *   parent effects, so an inner layer registers first and looks "older" than
+ *   the outer layer that contains it.
+ *
+ * There is nothing to mount at the app root: the context defaults to 0, and
+ * each layer provides depth for its OWN content, so nesting composes on its own.
+ */
+import { createContext, use } from 'react';
+
+/**
+ * How many layers deep the current subtree is. 0 at the app root; each layer
+ * increments it for its own content.
+ */
+import { jsx as _jsx } from "react/jsx-runtime";
+export const LayerDepthContext = /*#__PURE__*/createContext(0);
+LayerDepthContext.displayName = 'LayerDepthContext';
+
+/**
+ * Read the current nesting depth. A layer calls this to learn its OWN depth —
+ * the depth of the subtree it is rendered into, before it pushes its content
+ * one level deeper.
+ */
+export function useLayerDepth() {
+  return use(LayerDepthContext);
+}
+
+/**
+ * Wrap a layer's content so any layer opened from inside it registers as
+ * nested. Takes no depth prop on purpose: it reads the ambient depth and adds
+ * one, so nesting composes without anyone tracking absolute numbers.
+ *
+ * Renders no DOM element — it is a context boundary only, which is why it takes
+ * no `xstyle`/`ref` and exposes no props interface.
+ */
+export function LayerDepthProvider({
+  children
+}) {
+  const depth = use(LayerDepthContext);
+  return /*#__PURE__*/_jsx(LayerDepthContext, {
+    value: depth + 1,
+    children: children
+  });
+}
+LayerDepthProvider.displayName = 'LayerDepthProvider';

package/dist/Layer/index.d.ts

@@ -13,6 +13,9 @@
  */
 export { useLayer } from './useLayer';
 export type { LayerAlignment, LayerPlacement, ContextRenderProps, FixedRenderProps, ContextLayerOptions, FixedLayerOptions, ContextLayerReturn, FixedLayerReturn, } from './useLayer';
+export { useLayerDismissal } from './useLayerDismissal';
+export type { LayerEscapeBehavior, UseLayerDismissalOptions, UseLayerDismissalReturn, } from './useLayerDismissal';
+export { LayerDepthProvider } from './LayerDepthContext';
 export { useTouchTrigger, isActionTrigger } from './useTouchTrigger';
 export type { LayerTouchTrigger, UseTouchTriggerOptions, UseTouchTriggerReturn, } from './useTouchTrigger';
 export { LayerProvider } from './LayerProvider';

package/dist/Layer/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/Layer/index.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAC,QAAQ,EAAC,MAAM,YAAY,CAAC;AACpC,YAAY,EACV,cAAc,EACd,cAAc,EACd,kBAAkB,EAClB,gBAAgB,EAChB,mBAAmB,EACnB,iBAAiB,EACjB,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAC,eAAe,EAAE,eAAe,EAAC,MAAM,mBAAmB,CAAC;AACnE,YAAY,EACV,iBAAiB,EACjB,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EAAC,aAAa,EAAC,MAAM,iBAAiB,CAAC;AAC9C,YAAY,EAAC,kBAAkB,EAAC,MAAM,iBAAiB,CAAC;AACxD,OAAO,EAAC,YAAY,EAAE,eAAe,EAAC,MAAM,gBAAgB,CAAC;AAC7D,YAAY,EAAC,iBAAiB,EAAE,gBAAgB,EAAC,MAAM,gBAAgB,CAAC;AAGxE,OAAO,EAAC,eAAe,EAAC,MAAM,0BAA0B,CAAC;AAGzD,OAAO,EAAC,UAAU,EAAE,OAAO,EAAC,MAAM,YAAY,CAAC;AAC/C,YAAY,EACV,iBAAiB,EACjB,gBAAgB,EAChB,YAAY,GACb,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAC,YAAY,EAAE,SAAS,EAAC,MAAM,cAAc,CAAC;AACrD,YAAY,EACV,qBAAqB,EACrB,qBAAqB,EACrB,gBAAgB,EAChB,eAAe,EACf,cAAc,GACf,MAAM,cAAc,CAAC;AAGtB,OAAO,EAAC,UAAU,EAAE,OAAO,EAAC,MAAM,YAAY,CAAC;AAC/C,YAAY,EACV,mBAAmB,EACnB,mBAAmB,EACnB,cAAc,EACd,aAAa,EACb,YAAY,GACb,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/Layer/index.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAC,QAAQ,EAAC,MAAM,YAAY,CAAC;AACpC,YAAY,EACV,cAAc,EACd,cAAc,EACd,kBAAkB,EAClB,gBAAgB,EAChB,mBAAmB,EACnB,iBAAiB,EACjB,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAC,iBAAiB,EAAC,MAAM,qBAAqB,CAAC;AACtD,YAAY,EACV,mBAAmB,EACnB,wBAAwB,EACxB,uBAAuB,GACxB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAC,kBAAkB,EAAC,MAAM,qBAAqB,CAAC;AAGvD,OAAO,EAAC,eAAe,EAAE,eAAe,EAAC,MAAM,mBAAmB,CAAC;AACnE,YAAY,EACV,iBAAiB,EACjB,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EAAC,aAAa,EAAC,MAAM,iBAAiB,CAAC;AAC9C,YAAY,EAAC,kBAAkB,EAAC,MAAM,iBAAiB,CAAC;AACxD,OAAO,EAAC,YAAY,EAAE,eAAe,EAAC,MAAM,gBAAgB,CAAC;AAC7D,YAAY,EAAC,iBAAiB,EAAE,gBAAgB,EAAC,MAAM,gBAAgB,CAAC;AAGxE,OAAO,EAAC,eAAe,EAAC,MAAM,0BAA0B,CAAC;AAGzD,OAAO,EAAC,UAAU,EAAE,OAAO,EAAC,MAAM,YAAY,CAAC;AAC/C,YAAY,EACV,iBAAiB,EACjB,gBAAgB,EAChB,YAAY,GACb,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAC,YAAY,EAAE,SAAS,EAAC,MAAM,cAAc,CAAC;AACrD,YAAY,EACV,qBAAqB,EACrB,qBAAqB,EACrB,gBAAgB,EAChB,eAAe,EACf,cAAc,GACf,MAAM,cAAc,CAAC;AAGtB,OAAO,EAAC,UAAU,EAAE,OAAO,EAAC,MAAM,YAAY,CAAC;AAC/C,YAAY,EACV,mBAAmB,EACnB,mBAAmB,EACnB,cAAc,EACd,aAAa,EACb,YAAY,GACb,MAAM,YAAY,CAAC"}

package/dist/Layer/index.js

@@ -18,6 +18,10 @@
 
 // Core layer hook (remains in Layer)
 export { useLayer } from "./useLayer.js";
+// Layer dismissal stack — one Escape owner for every overlay family
+export { useLayerDismissal } from "./useLayerDismissal.js";
+export { LayerDepthProvider } from "./LayerDepthContext.js";
+
 // Shared touch behavior for the hover layers
 export { useTouchTrigger, isActionTrigger } from "./useTouchTrigger.js";
 // Layer provider

package/dist/Layer/layerStack.d.ts

@@ -0,0 +1,98 @@
+/**
+ * What a layer does with an Escape press that reaches it.
+ *
+ * - `'close'` — dismiss this layer and consume the press. One Escape closes
+ *   exactly this layer. The default, and correct for every dismissible layer:
+ *   modals, popovers, menus, comboboxes, and hover layers alike.
+ * - `'block'` — consume the press WITHOUT dismissing. For a layer that requires
+ *   an explicit choice (`Dialog purpose="required"`): Escape must not dismiss
+ *   it, and must not fall through and dismiss something behind it either.
+ *
+ * There is deliberately no "dismiss but let the press continue" variant. Escape
+ * affects exactly one layer, always — a rule with no per-component exceptions
+ * is one users can predict. Hover layers were the tempting exception (the user
+ * never opened the tip, so why should it eat their press?), but guessing wrong
+ * that way is destructive: someone dismissing a stray tooltip over a form would
+ * lose the whole dialog. Guessing wrong the other way costs one keystroke.
+ */
+export type LayerEscapeBehavior = 'close' | 'block';
+export interface LayerStackEntry {
+    /**
+     * Identity for removal; also the equality check for top-most, and the key
+     * `seq` is assigned against so a layer keeps its place across re-registration.
+     */
+    token: object;
+    /**
+     * Nesting depth from the React tree (see LayerDepthContext), NOT the DOM.
+     * Context flows through portals and is known during render, so it is correct
+     * for layers that portal out and for an inner + outer layer that open in the
+     * same commit — the case where effect order lies, because React runs child
+     * effects before parent effects.
+     */
+    depth: number;
+    /**
+     * Monotonic registration order; breaks ties between unrelated layers. For a
+     * layer that registers when it opens this is open order; a hover layer
+     * registers at mount and answers `isPresent` instead, so for two of those it
+     * is mount order rather than which one appeared first.
+     *
+     * Keyed to `token`, not to the registration, because a layer re-registers
+     * whenever its behavior or depth changes and must not overtake the layers
+     * above it.
+     */
+    seq: number;
+    behavior: LayerEscapeBehavior;
+    /**
+     * The layer's container element, read lazily at press time. Used only to
+     * break ties between layers the React tree reports at the same depth — a raw
+     * `useFocusTrap` cannot wrap its content in a depth provider (it renders
+     * nothing), so DOM containment is the only nesting signal those have.
+     */
+    getContainer?: () => HTMLElement | null;
+    /**
+     * Whether the layer is really on screen right now, asked at press time.
+     *
+     * Registration alone is not proof: a layer whose open state lives in React
+     * state can lag a frame behind the DOM, so gating registration on that state
+     * drops presses that arrive in the gap. Such layers register for their whole
+     * lifetime and answer this from the DOM instead. Omit it to mean "registered
+     * means present", which is true for layers that register on open.
+     */
+    isPresent?: () => boolean;
+    dismiss: () => void;
+}
+/**
+ * Whether the user is part-way through composing text with an IME.
+ *
+ * The stack reads this to decide what an Escape means, and layers read it
+ * through `useLayerDismissal`'s `shouldDismissOnCloseRequest` for the close
+ * requests that arrive without a keydown to inspect — the Android back
+ * gesture, the platform close watcher, or a composing Escape whose keydown
+ * never reached this listener because content stopped it. Mid-composition,
+ * those are far more likely to be the user backing out of a half-formed
+ * character than a request to dismiss a layer, and guessing wrong that way
+ * costs them everything they have typed into it.
+ *
+ * Scope, deliberately page-wide: a composition in a field behind a non-modal
+ * layer also suppresses that layer's close requests. It is one keypress to
+ * recover from, and the alternative — matching the composing element against
+ * a layer's container — cannot work for the layers that do not have one.
+ *
+ * A composition already running when the first layer registers is invisible
+ * here: the listeners go on with the stack's own.
+ */
+export declare function isTextComposing(): boolean;
+/**
+ * Whether `token` identifies the top-most layer. Overlays that still own a
+ * dismissal channel the stack does not model yet (outside-press, swipe) can
+ * gate on this so every channel agrees on who is on top.
+ */
+export declare function isTopmostLayer(token: object): boolean;
+/**
+ * Add a layer to the stack for as long as it is active. Returns the unregister
+ * function; callers own calling it.
+ */
+export declare function registerLayer(entry: Omit<LayerStackEntry, 'seq'>): () => void;
+/** Test-only: drop all entries and detach the listener. */
+export declare function resetLayerStackForTests(): void;
+//# sourceMappingURL=layerStack.d.ts.map

package/dist/Layer/layerStack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layerStack.d.ts","sourceRoot":"","sources":["../../src/Layer/layerStack.ts"],"names":[],"mappings":"AAoEA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,mBAAmB,GAAG,OAAO,GAAG,OAAO,CAAC;AAEpD,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;;;;;;;OASG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,mBAAmB,CAAC;IAC9B;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,WAAW,GAAG,IAAI,CAAC;IACxC;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,MAAM,OAAO,CAAC;IAC1B,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AA2ED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,eAAe,IAAI,OAAO,CAEzC;AA2BD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAErD;AAwED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,IAAI,CAAC,eAAe,EAAE,KAAK,CAAC,GAAG,MAAM,IAAI,CAc7E;AAED,2DAA2D;AAC3D,wBAAgB,uBAAuB,IAAI,IAAI,CAM9C"}

package/dist/Layer/layerStack.js

@@ -0,0 +1,306 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file layerStack.ts
+ * @input Uses the isImeKeyEvent predicate from utils/ime
+ * @output Exports the shared layer dismissal stack: registration, top-most
+ *   ordering, and the single document-level Escape listener
+ * @position Internal to the Layer system; consumed by useLayerDismissal, which
+ *   is what overlays actually call. Not exported from the package root.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/Layer/useLayerDismissal.ts
+ * - /packages/core/src/Layer/useLayerDismissal.test.tsx
+ *
+ * ## Why one stack
+ *
+ * Every overlay used to own its own Escape listener, so one press dismissed
+ * every open layer (a popover inside a Dialog closed both; a Modal opened from
+ * inside another Modal closed both). Patching this per primitive produced
+ * parallel registries — the focus-trap Escape stack, Drawer's LIFO registry,
+ * useScrollLock's counter. This module is the single registry those collapse
+ * into. One press dismisses exactly one layer.
+ *
+ * ## Only the top layer acts
+ *
+ * The stack owns ONE `keydown` listener on `document` and routes the press to
+ * the top-most layer itself. Overlays do not listen; they register and say what
+ * they want done. The alternative — every layer listens and filters itself out
+ * — is what forces `stopPropagation()` choreography between element-level and
+ * document-level listeners, and it silently breaks whenever a layer forgets.
+ *
+ * ## Bubble phase, not capture
+ *
+ * The listener is on the BUBBLE phase so content inside a layer can claim the
+ * press first, either by `stopPropagation()` (the press never reaches us) or by
+ * `preventDefault()` (we see it and stand down). Editors are the motivating
+ * case: Monaco and the rich-text editor use Escape to close their own find
+ * widget or autocomplete, and that must win over dismissing the Dialog they sit
+ * in. A capture-phase listener would take the press away from them.
+ *
+ * ## The stack, not the browser, decides
+ *
+ * When the stack handles a press it calls `preventDefault()`, which suppresses
+ * the browser's own close-watcher behavior — both `<dialog>`'s `cancel` event
+ * and `popover="auto"` light-dismiss (verified in Chromium; the default action
+ * runs after propagation, so a bubble-phase `preventDefault` still beats it).
+ * That is deliberate: the native top layer only covers `showModal()` and
+ * `popover="auto"`, so relying on it would leave non-modal `show()` drawers,
+ * `popover="manual"` layers, and older browsers on a second, differently-behaved
+ * code path. One code path, one ordering, everywhere.
+ *
+ * ## An Escape that cancels an IME composition
+ *
+ * That press is not a dismissal, so no layer acts on it — but the stack still
+ * claims it, because an unclaimed Escape is exactly what makes the browser
+ * raise a close request, and that request dismisses the layer through its
+ * `cancel` handler on the same keypress. Claiming is the whole fix; the guard
+ * that only returns measures identically to no guard at all.
+ *
+ * Close requests that arrive with no keydown to read — the Android back
+ * gesture, the platform close watcher — are answered by the hosts, which ask
+ * `isTextComposing()` through `useLayerDismissal`.
+ */
+import { isImeKeyEvent } from "../utils/ime.js";
+
+/**
+ * What a layer does with an Escape press that reaches it.
+ *
+ * - `'close'` — dismiss this layer and consume the press. One Escape closes
+ *   exactly this layer. The default, and correct for every dismissible layer:
+ *   modals, popovers, menus, comboboxes, and hover layers alike.
+ * - `'block'` — consume the press WITHOUT dismissing. For a layer that requires
+ *   an explicit choice (`Dialog purpose="required"`): Escape must not dismiss
+ *   it, and must not fall through and dismiss something behind it either.
+ *
+ * There is deliberately no "dismiss but let the press continue" variant. Escape
+ * affects exactly one layer, always — a rule with no per-component exceptions
+ * is one users can predict. Hover layers were the tempting exception (the user
+ * never opened the tip, so why should it eat their press?), but guessing wrong
+ * that way is destructive: someone dismissing a stray tooltip over a form would
+ * lose the whole dialog. Guessing wrong the other way costs one keystroke.
+ */
+
+const entries = [];
+// Registration order per layer identity. A layer re-registers whenever its
+// depth or behavior changes — a Dialog whose `purpose` flips while open, a focus trap
+// that moves — and StrictMode remounts every effect once more on top of that.
+// Counting registrations instead would hand the layer a fresh, higher seq each
+// time and promote it above the layers opened over it.
+let seqByToken = new WeakMap();
+let nextSeq = 0;
+let isListening = false;
+function seqFor(token) {
+  const existing = seqByToken.get(token);
+  if (existing !== undefined) {
+    return existing;
+  }
+  const seq = nextSeq++;
+  seqByToken.set(token, seq);
+  return seq;
+}
+
+/**
+ * Order two entries: positive when `a` is above `b`, negative when below.
+ * Three keys, each earning its place:
+ *
+ * 1. **Depth.** The layer nested inside the other is on top. This is what makes
+ *    an inner-and-outer pair that mount in the SAME commit come out right;
+ *    registration order alone gets it backwards, because React runs child
+ *    effects before parent effects.
+ * 2. **DOM containment.** Depth only moves when a layer wraps its content in a
+ *    `LayerDepthProvider`, which a bare `useFocusTrap` cannot do — it renders
+ *    nothing. For those, containment recovers the nesting the tree did not
+ *    report.
+ * 3. **Registration order.** For unrelated layers, the one that registered
+ *    later is on top, matching how the browser's own top layer stacks. A layer
+ *    keeps its first place for as long as its identity lives, so one that
+ *    closes and reopens does not move to the top — see the known edge in the
+ *    pull request.
+ *
+ * Modality is deliberately NOT a key. Ranking modals above everything sounds
+ * right and is not: a hover tip shown inside a modal renders on top of it, so
+ * a modal-first rule would hand the press to the dialog and strand the tip.
+ * Nesting already covers the case modality was meant to catch — a layer opened
+ * from inside another is deeper, modal or not.
+ *
+ * Note this is a PARTIAL order: containment relates only nested pairs. Callers
+ * must resolve the top with a pairwise max scan, never `Array.sort`, whose
+ * result is undefined for a non-transitive comparator.
+ */
+function compareEntries(a, b) {
+  if (a.depth !== b.depth) {
+    return a.depth - b.depth;
+  }
+  const aEl = a.getContainer?.() ?? null;
+  const bEl = b.getContainer?.() ?? null;
+  if (aEl != null && bEl != null && aEl !== bEl) {
+    if (bEl.contains(aEl)) {
+      return 1;
+    }
+    if (aEl.contains(bEl)) {
+      return -1;
+    }
+  }
+  return a.seq - b.seq;
+}
+function isPresentEntry(entry) {
+  return entry.isPresent?.() ?? true;
+}
+
+// Whether a text composition is running anywhere on the page. Tracked from
+// composition events because the DOM offers no way to ask.
+let isComposing = false;
+
+/**
+ * Whether the user is part-way through composing text with an IME.
+ *
+ * The stack reads this to decide what an Escape means, and layers read it
+ * through `useLayerDismissal`'s `shouldDismissOnCloseRequest` for the close
+ * requests that arrive without a keydown to inspect — the Android back
+ * gesture, the platform close watcher, or a composing Escape whose keydown
+ * never reached this listener because content stopped it. Mid-composition,
+ * those are far more likely to be the user backing out of a half-formed
+ * character than a request to dismiss a layer, and guessing wrong that way
+ * costs them everything they have typed into it.
+ *
+ * Scope, deliberately page-wide: a composition in a field behind a non-modal
+ * layer also suppresses that layer's close requests. It is one keypress to
+ * recover from, and the alternative — matching the composing element against
+ * a layer's container — cannot work for the layers that do not have one.
+ *
+ * A composition already running when the first layer registers is invisible
+ * here: the listeners go on with the stack's own.
+ */
+export function isTextComposing() {
+  return isComposing;
+}
+function handleCompositionStart() {
+  isComposing = true;
+}
+
+// Focus leaving the field ends the composition too. Clearing on blur as well
+// means a compositionend this listener never sees cannot leave the flag stuck
+// on, swallowing every later close request.
+function handleCompositionEnd() {
+  isComposing = false;
+}
+
+/** The top-most present layer, or null when nothing is on screen. */
+function topPresentEntry() {
+  let top = null;
+  for (const entry of entries) {
+    if (!isPresentEntry(entry)) {
+      continue;
+    }
+    if (top == null || compareEntries(entry, top) > 0) {
+      top = entry;
+    }
+  }
+  return top;
+}
+
+/**
+ * Whether `token` identifies the top-most layer. Overlays that still own a
+ * dismissal channel the stack does not model yet (outside-press, swipe) can
+ * gate on this so every channel agrees on who is on top.
+ */
+export function isTopmostLayer(token) {
+  return topPresentEntry()?.token === token;
+}
+
+/** Resolve an Escape press against the stack. Returns whether it was handled. */
+function dispatchEscape() {
+  const top = topPresentEntry();
+  if (top == null) {
+    return false;
+  }
+  if (top.behavior === 'block') {
+    return true;
+  }
+  top.dismiss();
+  return true;
+}
+function handleKeyDown(event) {
+  if (event.key !== 'Escape') {
+    return;
+  }
+  // An IME user pressing Escape is cancelling a composition, not dismissing a
+  // layer. Claim the press anyway, then stand down: left unclaimed, the browser
+  // raises its own close request, which arrives at a layer's `cancel` handler
+  // and dismisses it on this very keypress — measured in Chromium, where a
+  // guard that only returns behaves exactly like no guard at all. Claim it only
+  // while a layer is on screen; with nothing to protect, the press is not ours.
+  if (isImeKeyEvent(event)) {
+    if (topPresentEntry() != null) {
+      event.preventDefault();
+    }
+    return;
+  }
+  // Content inside a layer already claimed this press (see the bubble-phase
+  // note in the file header). Honor it and leave the default action alone.
+  if (event.defaultPrevented) {
+    return;
+  }
+  if (dispatchEscape()) {
+    // Suppress the browser's own close-watcher so it cannot dismiss a second
+    // layer behind our back. Propagation is left alone: consumers may
+    // legitimately listen for Escape on window, and the stack's decision is
+    // already recorded in defaultPrevented.
+    event.preventDefault();
+  }
+}
+function startListening() {
+  if (isListening || typeof document === 'undefined') {
+    return;
+  }
+  document.addEventListener('keydown', handleKeyDown);
+  document.addEventListener('compositionstart', handleCompositionStart, true);
+  document.addEventListener('compositionend', handleCompositionEnd, true);
+  document.addEventListener('blur', handleCompositionEnd, true);
+  isListening = true;
+}
+function stopListening() {
+  if (!isListening || typeof document === 'undefined') {
+    return;
+  }
+  document.removeEventListener('keydown', handleKeyDown);
+  document.removeEventListener('compositionstart', handleCompositionStart, true);
+  document.removeEventListener('compositionend', handleCompositionEnd, true);
+  document.removeEventListener('blur', handleCompositionEnd, true);
+  isComposing = false;
+  isListening = false;
+}
+
+/**
+ * Add a layer to the stack for as long as it is active. Returns the unregister
+ * function; callers own calling it.
+ */
+export function registerLayer(entry) {
+  const full = {
+    ...entry,
+    seq: seqFor(entry.token)
+  };
+  entries.push(full);
+  startListening();
+  return () => {
+    const index = entries.indexOf(full);
+    if (index !== -1) {
+      entries.splice(index, 1);
+    }
+    if (entries.length === 0) {
+      stopListening();
+    }
+  };
+}
+
+/** Test-only: drop all entries and detach the listener. */
+export function resetLayerStackForTests() {
+  entries.length = 0;
+  seqByToken = new WeakMap();
+  nextSeq = 0;
+  isComposing = false;
+  stopListening();
+}

package/dist/Layer/useLayerDismissal.d.ts

@@ -0,0 +1,93 @@
+import { type LayerEscapeBehavior } from './layerStack';
+export type { LayerEscapeBehavior };
+export interface UseLayerDismissalOptions {
+    /**
+     * Whether this layer is participating right now. Usually the layer's open
+     * state. A layer whose open state lags the DOM should pass `true` for its
+     * lifetime and answer `isPresent` from the DOM instead.
+     */
+    isActive: boolean;
+    /**
+     * Dismiss this layer. Called by the stack when this layer is the one that
+     * should respond to an Escape press. Not called for `escapeBehavior: 'block'`.
+     */
+    onDismiss: () => void;
+    /**
+     * What this layer does with an Escape press that reaches it.
+     * @default 'close'
+     */
+    escapeBehavior?: LayerEscapeBehavior;
+    /**
+     * This layer's container element, read lazily. Optional: supply it when the
+     * layer cannot wrap its content in `LayerDepthProvider` (a bare focus trap
+     * renders nothing), so nesting can still be recovered from the DOM.
+     */
+    getContainer?: () => HTMLElement | null;
+    /**
+     * Whether the layer is really on screen, asked at press time. Supply it when
+     * `isActive` is `true` for the layer's lifetime because its open state lags
+     * the DOM by a frame; the stack skips layers that answer `false`.
+     */
+    isPresent?: () => boolean;
+    /**
+     * Whether this layer takes part in the shared stack at all. When `false` the
+     * layer is invisible to dismissal: a press flows past it to the layer below,
+     * exactly as if it were not open.
+     *
+     * Deliberately separate from `escapeBehavior: 'block'` — `'block'` is a layer
+     * that is present and swallows the press; this is a layer that is not there
+     * at all. One case uses it: `Dialog`'s inline rendering mode, where content
+     * sits in normal flow with nothing layered over anything.
+     *
+     * A controlled layer is NOT one of these. It stays registered and takes the
+     * press like any other, answering it by calling the consumer's change
+     * handler; whether it then closes is the consumer's decision.
+     *
+     * Layers that are never Escape-dismissible (toasts) should simply not call
+     * this hook.
+     *
+     * @default true
+     */
+    isEnabled?: boolean;
+}
+export interface UseLayerDismissalReturn {
+    /**
+     * Whether a close request the browser started on its own — a `<dialog>`'s
+     * `cancel`, the Android back gesture, the platform close watcher — should
+     * dismiss this layer. As well as the top-most rule the stack applies to an
+     * Escape press, it declines a request that arrives while an IME composition
+     * is running, which no `cancel` handler can tell on its own because the
+     * event carries no composition state.
+     */
+    shouldDismissOnCloseRequest: () => boolean;
+}
+/**
+ * Join the shared layer dismissal stack for as long as this layer is active.
+ *
+ * The layer does NOT attach a key listener — the stack owns one listener and
+ * routes each Escape press to the top-most REGISTERED layer, so one press
+ * dismisses exactly one of them. Dialog (and what is built on it), Popover and
+ * the menus built on it, Tooltip, HoverCard, Lightbox and MobileNav register
+ * today; `BottomSheetSwitcher` registers through its focus trap when modal and
+ * still handles its own press when not.
+ *
+ * `BottomSheet`, `CommandPalette`, `ContextMenu`, `DropdownMenuSubMenu`,
+ * `PowerSearchEditPopover` and lab's `Drawer` still run their own Escape
+ * listener. They stay safe next to the stack only because each claims the press
+ * at element level, and the stack stands down on an already-`defaultPrevented`
+ * press — but a registered layer opened INSIDE one of them does not get the
+ * press: the host takes it and closes instead. Migrating them is the fix.
+ *
+ * Wrap the layer's own content in `LayerDepthProvider` so anything opened from
+ * inside it registers as nested.
+ *
+ * @example
+ * ```tsx
+ * useLayerDismissal({
+ *   isActive: isOpen,
+ *   onDismiss: () => onOpenChange(false),
+ * });
+ * ```
+ */
+export declare function useLayerDismissal(options: UseLayerDismissalOptions): UseLayerDismissalReturn;
+//# sourceMappingURL=useLayerDismissal.d.ts.map

package/dist/Layer/useLayerDismissal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useLayerDismissal.d.ts","sourceRoot":"","sources":["../../src/Layer/useLayerDismissal.ts"],"names":[],"mappings":"AAqBA,OAAO,EAIL,KAAK,mBAAmB,EACzB,MAAM,cAAc,CAAC;AAEtB,YAAY,EAAC,mBAAmB,EAAC,CAAC;AAElC,MAAM,WAAW,wBAAwB;IACvC;;;;OAIG;IACH,QAAQ,EAAE,OAAO,CAAC;IAClB;;;OAGG;IACH,SAAS,EAAE,MAAM,IAAI,CAAC;IACtB;;;OAGG;IACH,cAAc,CAAC,EAAE,mBAAmB,CAAC;IACrC;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,WAAW,GAAG,IAAI,CAAC;IACxC;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,OAAO,CAAC;IAC1B;;;;;;;;;;;;;;;;;;OAkBG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,uBAAuB;IACtC;;;;;;;OAOG;IACH,2BAA2B,EAAE,MAAM,OAAO,CAAC;CAC5C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,wBAAwB,GAChC,uBAAuB,CAiDzB"}