@oxyhq/bloom 0.44.1 → 0.46.0

package/src/__tests__/surfaceStore.test.ts

@@ -0,0 +1,219 @@
+import {
+  __resetSurfacesForTests,
+  dismissAll,
+  dismissToRoot,
+  dismissTop,
+  finalizeClose,
+  getSnapshot,
+  present,
+  requestDismiss,
+  resetSurfaces,
+  subscribe,
+} from '../surfaces/surfaceStore';
+import { confirm, prompt, surfaces } from '../surfaces/api';
+
+const noop = () => null;
+
+/** Id of the current top surface (guarded so strict tsc is satisfied). */
+function topId(): string {
+  const stack = getSnapshot();
+  const top = stack[stack.length - 1];
+  if (!top) throw new Error('expected a surface on the stack');
+  return top.id;
+}
+
+afterEach(() => {
+  // Resolve any lingering promises so awaiting tests never hang, then reset the
+  // module store + id counter for isolation.
+  resetSurfaces();
+  __resetSurfacesForTests();
+});
+
+describe('surfaceStore', () => {
+  it('present pushes an entry and resolves its promise on dismiss', async () => {
+    const p = present(noop);
+    const stack = getSnapshot();
+    expect(stack).toHaveLength(1);
+    expect(stack[0]?.status).toBe('open');
+    requestDismiss(topId(), 'hello');
+    await expect(p).resolves.toBe('hello');
+  });
+
+  it('stacks bottom→top; the last entry is the top', () => {
+    void present(noop);
+    void present(noop);
+    void present(noop);
+    expect(getSnapshot().map((e) => e.id)).toEqual([
+      'bloom-surface-1',
+      'bloom-surface-2',
+      'bloom-surface-3',
+    ]);
+  });
+
+  it('resolves ONCE — a second dismiss with a different result is ignored', async () => {
+    const p = present(noop);
+    const id = topId();
+    requestDismiss(id, 'first');
+    requestDismiss(id, 'second');
+    await expect(p).resolves.toBe('first');
+  });
+
+  it('requestDismiss flips the entry to closing but does not splice it', () => {
+    void present(noop);
+    const id = topId();
+    requestDismiss(id, 1);
+    const stack = getSnapshot();
+    expect(stack).toHaveLength(1);
+    expect(stack[0]?.status).toBe('closing');
+    expect(stack[0]?.generation).toBe(1);
+  });
+
+  it('finalizeClose removes a CLOSING entry; is a no-op for an OPEN entry', async () => {
+    const p = present(noop);
+    const id = topId();
+    // Open → no-op.
+    finalizeClose(id);
+    expect(getSnapshot()).toHaveLength(1);
+    // Closing → removed.
+    requestDismiss(id, 'x');
+    finalizeClose(id);
+    expect(getSnapshot()).toHaveLength(0);
+    await expect(p).resolves.toBe('x');
+  });
+
+  it('dismissTop dismisses only the top surface', async () => {
+    const a = present(noop);
+    const b = present(noop);
+    dismissTop('B');
+    await expect(b).resolves.toBe('B');
+    const stack = getSnapshot();
+    expect(stack.find((e) => e.id === 'bloom-surface-1')?.status).toBe('open');
+    expect(stack.find((e) => e.id === 'bloom-surface-2')?.status).toBe('closing');
+    // Clean up the still-open root.
+    void a;
+  });
+
+  it('dismissToRoot resolves everything above the root with undefined, keeps the root', async () => {
+    const root = present(noop);
+    const mid = present(noop);
+    const top = present(noop);
+    dismissToRoot();
+    await expect(mid).resolves.toBeUndefined();
+    await expect(top).resolves.toBeUndefined();
+    const stack = getSnapshot();
+    expect(stack.find((e) => e.id === 'bloom-surface-1')?.status).toBe('open');
+    void root;
+  });
+
+  it('dismissToRoot is a no-op with 0 or 1 surfaces', async () => {
+    dismissToRoot();
+    expect(getSnapshot()).toHaveLength(0);
+    const only = present(noop);
+    dismissToRoot();
+    expect(getSnapshot()[0]?.status).toBe('open');
+    void only;
+  });
+
+  it('dismissAll resolves ALL pending awaiters with undefined', async () => {
+    const a = present(noop);
+    const b = present(noop);
+    const c = present(noop);
+    dismissAll();
+    await expect(a).resolves.toBeUndefined();
+    await expect(b).resolves.toBeUndefined();
+    await expect(c).resolves.toBeUndefined();
+  });
+
+  it('resetSurfaces resolves pending awaiters and clears the stack', async () => {
+    const a = present(noop);
+    const b = present(noop);
+    resetSurfaces();
+    await expect(a).resolves.toBeUndefined();
+    await expect(b).resolves.toBeUndefined();
+    expect(getSnapshot()).toHaveLength(0);
+  });
+
+  it('requestDismiss / finalizeClose ignore an unknown id', () => {
+    expect(() => requestDismiss('does-not-exist', 1)).not.toThrow();
+    expect(() => finalizeClose('does-not-exist')).not.toThrow();
+  });
+
+  it('getSnapshot returns a STABLE reference while unchanged', () => {
+    const s1 = getSnapshot();
+    expect(getSnapshot()).toBe(s1);
+    void present(noop);
+    const s2 = getSnapshot();
+    expect(s2).not.toBe(s1);
+    expect(getSnapshot()).toBe(s2);
+  });
+
+  it('notifies subscribers on each stack mutation', () => {
+    let calls = 0;
+    const unsub = subscribe(() => {
+      calls += 1;
+    });
+    void present(noop); // +1
+    dismissTop(); // requestDismiss emits +1
+    expect(calls).toBe(2);
+    unsub();
+  });
+});
+
+describe('surfaces imperative API', () => {
+  it('surfaces.present + surfaces.dismiss resolve with the top result', async () => {
+    const p = surfaces.present(noop);
+    surfaces.dismiss('done');
+    await expect(p).resolves.toBe('done');
+  });
+
+  it('surfaces.dismissById targets a specific surface', async () => {
+    const a = surfaces.present(noop);
+    const b = surfaces.present(noop);
+    const bottom = getSnapshot()[0];
+    if (!bottom) throw new Error('expected a surface on the stack');
+    surfaces.dismissById(bottom.id, 'A');
+    await expect(a).resolves.toBe('A');
+    void b;
+  });
+
+  it('surfaces.dismissAll clears the stack and resolves pending', async () => {
+    const a = surfaces.present(noop);
+    const b = surfaces.present(noop);
+    surfaces.dismissAll();
+    await expect(a).resolves.toBeUndefined();
+    await expect(b).resolves.toBeUndefined();
+  });
+});
+
+describe('confirm / prompt surfaces', () => {
+  it('confirm resolves true when dismissed with true, false otherwise', async () => {
+    const yes = confirm({ title: 'Delete?' });
+    requestDismiss(topId(), true);
+    await expect(yes).resolves.toBe(true);
+
+    const no = confirm({ title: 'Delete?' });
+    requestDismiss(topId(), false);
+    await expect(no).resolves.toBe(false);
+  });
+
+  it('confirm resolves false when dismissed without a result (backdrop/Escape)', async () => {
+    const c = confirm({ title: 'Proceed?' });
+    dismissTop(); // undefined → coerced to false
+    await expect(c).resolves.toBe(false);
+  });
+
+  it('confirm presents a centered surface', () => {
+    void confirm({ title: 'Hi' });
+    expect(getSnapshot()[0]?.presentation.placement).toBe('center');
+  });
+
+  it('prompt resolves the entered string, or null when dismissed without one', async () => {
+    const p = prompt({ title: 'Name?' });
+    requestDismiss(topId(), 'Ada');
+    await expect(p).resolves.toBe('Ada');
+
+    const cancelled = prompt({ title: 'Name?' });
+    dismissTop(); // undefined → coerced to null
+    await expect(cancelled).resolves.toBeNull();
+  });
+});

package/src/dialog/Dialog.tsx

@@ -25,7 +25,7 @@ import Animated, {
 } from 'react-native-reanimated';
 
 import { BottomSheet, type BottomSheetRef } from '../bottom-sheet';
-import { Z_INDEX } from '../styles/z-index';
+import { Z_INDEX, Z_INDEX_LAYER_STEP } from '../styles/z-index';
 import { useTheme } from '../theme/use-theme';
 import { Context, useDialogControl } from './context';
 import { DialogBody } from './DialogContent';
@@ -104,6 +104,7 @@ function CenteredOrSideDialog({
   description,
   actions,
   placement,
+  layer,
   width = DEFAULT_SIDE_WIDTH,
   inset,
   dismissOnBackdrop = true,
@@ -241,6 +242,7 @@ function CenteredOrSideDialog({
           open={sideOpen}
           onDismiss={handleDismiss}
           side={placement}
+          layer={layer}
           width={width}
           inset={inset}
           dismissOnBackdrop={dismissOnBackdrop}
@@ -311,6 +313,7 @@ function SideSheet({
   open,
   onDismiss,
   side,
+  layer,
   width,
   inset,
   dismissOnBackdrop,
@@ -331,6 +334,7 @@ function SideSheet({
   open: boolean;
   onDismiss: () => void;
   side: 'left' | 'right';
+  layer?: number;
   width: number;
   inset?: DialogInset;
   dismissOnBackdrop: boolean;
@@ -433,7 +437,13 @@ function SideSheet({
 
   return (
     <View
-      style={[sideStyles.root, containerStyle]}
+      style={[
+        sideStyles.root,
+        // Per-layer offset so a side dialog stacked on top of another (surface
+        // stack) paints above it. Layer 0 → offset 0 → unchanged.
+        { zIndex: Z_INDEX.fullscreen + Z_INDEX_LAYER_STEP * (layer ?? 0) },
+        containerStyle,
+      ]}
       {...(containerClassName ? ({ className: containerClassName } as Record<string, string>) : {})}
       pointerEvents="box-none"
     >
@@ -473,9 +483,10 @@ function SideSheet({
 }
 
 const sideStyles = StyleSheet.create({
+  // `zIndex` is applied inline (`Z_INDEX.fullscreen + layer offset`) so a side
+  // dialog stacked on top of another paints above it in the surface stack.
   root: {
     ...StyleSheet.absoluteFill,
-    zIndex: Z_INDEX.fullscreen,
   },
   backdrop: {
     ...StyleSheet.absoluteFill,

package/src/dialog/Dialog.web.tsx

@@ -44,7 +44,6 @@ import type {
 } from './types';
 
 const FADE_OUT_DURATION = CENTER_FADE_OUT_DURATION;
-const dialogZIndex = createOverlayZIndex();
 
 const stopPropagation = (e: { stopPropagation: () => void }) => e.stopPropagation();
 
@@ -132,6 +131,7 @@ function CenterOrSideDialog({
   description,
   actions,
   placement,
+  layer,
   width = DEFAULT_SIDE_WIDTH,
   maxWidth = DEFAULT_CENTER_MAX_WIDTH,
   inset,
@@ -150,6 +150,11 @@ function CenterOrSideDialog({
   // stylesheet is present by the time the animated surface mounts).
   useDialogCss();
 
+  // Per-layer overlay z-indices, so a dialog presented on top of another (via
+  // the surface stack) paints above it. Defaults to layer 0 — the offset is 0,
+  // so a lone dialog's z is byte-for-byte unchanged.
+  const dialogZIndex = useMemo(() => createOverlayZIndex(layer ?? 0), [layer]);
+
   // Controlled mode is opt-in: when `open` is a boolean the host owns the
   // visible state; otherwise the legacy imperative `control` path drives it.
   const isControlled = controlledOpen !== undefined;
@@ -297,6 +302,7 @@ function CenterOrSideDialog({
                 style={style}
                 maxWidth={maxWidth}
                 contentPadding={contentPadding}
+                surfaceZIndex={dialogZIndex.surface}
                 isClosing={isClosing}
               >
                 {children}
@@ -325,6 +331,8 @@ function CenterOrSideDialog({
             inset={inset}
             dismissOnBackdrop={dismissOnBackdrop}
             contentPadding={contentPadding}
+            backdropZIndex={dialogZIndex.backdrop}
+            surfaceZIndex={dialogZIndex.surface}
             onDismiss={close}
             panelStyle={panelStyle}
             panelClassName={panelClassName}
@@ -349,6 +357,7 @@ function DialogPanel({
   style,
   maxWidth,
   contentPadding,
+  surfaceZIndex,
   isClosing,
   children,
 }: {
@@ -360,6 +369,7 @@ function DialogPanel({
   style?: DialogProps['style'];
   maxWidth: number;
   contentPadding: number;
+  surfaceZIndex: number;
   isClosing: boolean;
   children?: React.ReactNode;
 }) {
@@ -391,7 +401,7 @@ function DialogPanel({
           shadowRadius: 30,
           shadowOffset: { width: 0, height: 4 },
           padding: contentPadding,
-          zIndex: dialogZIndex.surface,
+          zIndex: surfaceZIndex,
         },
         isClosing
           ? ({ animation: `bloomDialogZoomFadeOut ease-in ${FADE_OUT_DURATION}ms forwards` } as ViewStyle)
@@ -435,6 +445,8 @@ function SheetSurface({
   inset,
   dismissOnBackdrop,
   contentPadding,
+  backdropZIndex,
+  surfaceZIndex,
   onDismiss,
   panelStyle,
   panelClassName,
@@ -454,6 +466,8 @@ function SheetSurface({
   inset?: DialogInset;
   dismissOnBackdrop: boolean;
   contentPadding: number;
+  backdropZIndex: number;
+  surfaceZIndex: number;
   onDismiss: () => void;
   panelStyle?: StyleProp<ViewStyle>;
   panelClassName?: string;
@@ -532,7 +546,7 @@ function SheetSurface({
 
   return (
     <View
-      style={[sheetStyles.root, containerStyle]}
+      style={[sheetStyles.root, { zIndex: backdropZIndex }, containerStyle]}
       {...(containerClassName ? ({ className: containerClassName } as Record<string, string>) : {})}
       pointerEvents="box-none"
     >
@@ -562,7 +576,11 @@ function SheetSurface({
         {...(panelClassName ? ({ className: panelClassName } as Record<string, string>) : {})}
         style={[
           sheetStyles.panel,
-          { backgroundColor: theme.colors.background, shadowColor: theme.colors.shadow },
+          {
+            backgroundColor: theme.colors.background,
+            shadowColor: theme.colors.shadow,
+            zIndex: surfaceZIndex,
+          },
           panelGeometry,
           panelTransition,
           panelStyle,
@@ -659,13 +677,15 @@ export function AutoMountedDialog({
 }
 
 const sheetStyles = {
+  // `zIndex` for the root (backdrop) and panel (surface) is applied inline from
+  // the per-layer `createOverlayZIndex(layer)` in `SheetSurface`, so a side
+  // dialog stacked on top of another (surface stack) paints above it.
   root: {
     position: 'fixed' as 'absolute',
     top: 0,
     left: 0,
     right: 0,
     bottom: 0,
-    zIndex: dialogZIndex.backdrop,
   } as ViewStyle,
   backdrop: {
     position: 'absolute',
@@ -681,7 +701,6 @@ const sheetStyles = {
     shadowOpacity: 0.18,
     shadowRadius: 24,
     shadowOffset: { width: 0, height: 8 },
-    zIndex: dialogZIndex.surface,
   } as ViewStyle,
 };
 

package/src/dialog/types.ts

@@ -163,6 +163,16 @@ export type DialogProps = React.PropsWithChildren<{
   containerClassName?: string;
   /** Accessibility label, applied to the dialog role on web. */
   label?: string;
+  /**
+   * Stacking layer index within a coordinated surface stack. Multiplies
+   * `Z_INDEX_LAYER_STEP` onto this dialog's overlay z-indices (backdrop +
+   * panel) so a dialog presented on top of another paints above it. Defaults to
+   * `0` — the single-dialog case, byte-for-byte unchanged. Set by the shared
+   * surface stack (`src/surfaces`); direct consumers rarely need it. No-op for
+   * the `bottom` placement, which already stacks in mount order (native RN
+   * `<Modal>` / the web portal), so `layer` is harmless there.
+   */
+  layer?: number;
 }>;
 
 /**

package/src/index.ts

@@ -72,6 +72,21 @@ export type {
   DialogProps,
   ResponsiveDialogPlacement,
 } from './dialog';
+// Surface stack — the shared, coordinated overlay system. The imperative API is
+// the `surfaces` object (its members would otherwise clash with alert-dialog's
+// `confirm`); the individual functions are also named exports of
+// `@oxyhq/bloom/surfaces`.
+export { surfaces, SurfaceProvider, SurfaceHost, useSurface } from './surfaces';
+export type {
+  SurfacePresentation,
+  PresentOptions,
+  SurfaceControls,
+  SurfaceRenderFn,
+  SurfaceStatus,
+  SurfaceEntry,
+  SurfaceConfirmOptions,
+  SurfacePromptOptions,
+} from './surfaces';
 export * from './button';
 export { Fab } from './fab';
 export type { FabProps, FabVariant, FabSize, FabPlacement } from './fab';

package/src/index.web.ts

@@ -77,6 +77,21 @@ export type {
   DialogProps,
   ResponsiveDialogPlacement,
 } from './dialog/index.web';
+// Surface stack — the shared, coordinated overlay system. The imperative API is
+// the `surfaces` object (its members would otherwise clash with alert-dialog's
+// `confirm`); the individual functions are also named exports of
+// `@oxyhq/bloom/surfaces`.
+export { surfaces, SurfaceProvider, SurfaceHost, useSurface } from './surfaces/index.web';
+export type {
+  SurfacePresentation,
+  PresentOptions,
+  SurfaceControls,
+  SurfaceRenderFn,
+  SurfaceStatus,
+  SurfaceEntry,
+  SurfaceConfirmOptions,
+  SurfacePromptOptions,
+} from './surfaces/index.web';
 export * from './button/index.web';
 export { Fab } from './fab/index.web';
 export type { FabProps, FabVariant, FabSize, FabPlacement } from './fab/index.web';

package/src/surfaces/SurfaceHost.tsx

@@ -0,0 +1,207 @@
+import React, {
+  useCallback,
+  useEffect,
+  useMemo,
+  useSyncExternalStore,
+} from 'react';
+import { BackHandler, Platform } from 'react-native';
+
+import { useDialogControl } from '../dialog/context';
+import type { DialogProps } from '../dialog/types';
+import {
+  finalizeClose,
+  getSnapshot,
+  present,
+  requestDismiss,
+  resetSurfaces,
+  subscribe,
+} from './surfaceStore';
+import { SurfaceContext } from './useSurface';
+import type { SurfaceControls, SurfaceEntry, SurfacePresentation } from './types';
+
+type DialogComponent = React.ComponentType<DialogProps>;
+
+/** Default placement — the ecosystem's responsive "sheet" (bottom → centered). */
+const DEFAULT_PLACEMENT: SurfacePresentation['placement'] = {
+  base: 'bottom',
+  md: 'center',
+};
+
+/** Map a surface's presentation config onto the shared `Dialog` props. */
+function placementFor(p: SurfacePresentation): Partial<DialogProps> {
+  return {
+    placement: p.placement ?? DEFAULT_PLACEMENT,
+    width: p.width,
+    maxWidth: p.maxWidth,
+    maxHeightRatio: p.maxHeightRatio,
+    inset: p.inset,
+    showHandle: p.showHandle,
+    dismissOnBackdrop: p.dismissOnBackdrop,
+    contentPadding: p.contentPadding,
+    style: p.style,
+    panelStyle: p.panelStyle,
+    panelClassName: p.panelClassName,
+    containerStyle: p.containerStyle,
+    containerClassName: p.containerClassName,
+    label: p.label,
+    testID: p.testID,
+  };
+}
+
+/**
+ * Build the `<SurfaceHost>` + `<SurfaceProvider>` bound to a platform `Dialog`.
+ *
+ * `Dialog` is platform-forked (native `BottomSheet`-backed vs. pure-DOM web
+ * overlay), so — like `createAlertDialog` — the platform entry files
+ * (`index.ts` / `index.web.ts`) inject the correct one. The stack logic below is
+ * single-source, no duplication.
+ */
+export function createSurfaceHost(Dialog: DialogComponent) {
+  /**
+   * One stacked surface. Bridges a store entry onto an IMPERATIVE `Dialog`
+   * (`useDialogControl()` + `open()`/`close()`) — never the controlled
+   * `open`/`onClose` boolean path, which fires `onClose` synchronously as the
+   * dismiss REQUEST and has no post-exit callback, so it could never tell the
+   * store WHEN to splice the entry after the exit animation.
+   */
+  function SurfaceLayer({
+    entry,
+    index,
+  }: {
+    entry: SurfaceEntry;
+    index: number;
+  }) {
+    const control = useDialogControl();
+    const { id, status } = entry;
+
+    const controls = useMemo<SurfaceControls>(
+      () => ({
+        dismiss: (result?: unknown) => requestDismiss(id, result),
+        present: (render, opts) => present(render, opts),
+      }),
+      [id],
+    );
+
+    // Open imperatively on mount (mirrors `AlertDialog`'s canonical
+    // fresh-mount open-from-effect; `control` is stable for the layer's life).
+    useEffect(() => {
+      control.open();
+    }, [control]);
+
+    // When the store flips this entry to 'closing' (a programmatic dismiss,
+    // dismissAll, dismissToRoot, Escape, or Android-back), run the exit
+    // animation. A user backdrop/Escape handled by the Dialog itself instead
+    // drives its own internal close; either way `onClose` fires post-exit.
+    useEffect(() => {
+      if (status === 'closing') control.close();
+    }, [status, control]);
+
+    // Fires AFTER the exit animation settles (imperative mode), for ANY
+    // dismissal path — user backdrop/Escape/back OR a programmatic dismiss.
+    // `requestDismiss` resolves-once (a programmatic dismiss already resolved
+    // with its result; this is a no-op then), then `finalizeClose` splices the
+    // entry out. Guarded by unique ids + `'closing'` status in the store.
+    const handleClose = useCallback(() => {
+      requestDismiss(id);
+      finalizeClose(id);
+    }, [id]);
+
+    const placement = useMemo(
+      () => placementFor(entry.presentation),
+      [entry.presentation],
+    );
+
+    return (
+      <Dialog control={control} onClose={handleClose} layer={index} {...placement}>
+        <SurfaceContext.Provider value={controls}>
+          {entry.render(controls)}
+        </SurfaceContext.Provider>
+      </Dialog>
+    );
+  }
+
+  function SurfaceHost() {
+    const stack = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+
+    useAndroidBackDismissesTop();
+    useEscapeDismissesTop();
+
+    return (
+      <>
+        {stack.map((entry, index) => (
+          <SurfaceLayer key={entry.id} entry={entry} index={index} />
+        ))}
+      </>
+    );
+  }
+  SurfaceHost.displayName = 'SurfaceHost';
+
+  /**
+   * Mount ONCE near your app root — renders `children` plus the stack host.
+   * Requires the Bloom Portal provider to be mounted too (same as any `<Dialog>`
+   * usage): on web the Portal auto-creates `#bloom-portal-root`; on native mount
+   * `<Provider>`/`<Outlet>` from `@oxyhq/bloom/portal`. Can equally be folded
+   * next to that Portal provider — `<SurfaceHost>` used directly does the same
+   * job without wrapping `children`.
+   */
+  function SurfaceProvider({ children }: { children: React.ReactNode }) {
+    // Resolve any pending awaiters if the provider unmounts so no `present()`
+    // promise is stranded.
+    useEffect(() => () => resetSurfaces(), []);
+    return (
+      <>
+        {children}
+        <SurfaceHost />
+      </>
+    );
+  }
+  SurfaceProvider.displayName = 'SurfaceProvider';
+
+  return { SurfaceHost, SurfaceProvider };
+}
+
+/**
+ * ONE Android hardware-back handler for the whole stack → dismiss the TOP
+ * surface. Reads the live top from the store so a single registration always
+ * targets the current top. Returns `false` when the stack is empty so app-level
+ * back navigation is untouched.
+ */
+function useAndroidBackDismissesTop(): void {
+  useEffect(() => {
+    if (Platform.OS !== 'android') return;
+    const sub = BackHandler.addEventListener('hardwareBackPress', () => {
+      const stack = getSnapshot();
+      const top = stack[stack.length - 1];
+      if (!top) return false;
+      if (top.presentation.dismissOnBackdrop === false) return true;
+      requestDismiss(top.id);
+      return true;
+    });
+    return () => sub.remove();
+  }, []);
+}
+
+/**
+ * Web-only: route Escape to the TOP surface only. A window-CAPTURE listener runs
+ * before each `Dialog`'s own document-level keydown, so `stopImmediatePropagation`
+ * prevents the lower stacked dialogs from ALSO handling Escape (they each add a
+ * document listener) — Escape dismisses strictly the top, LIFO. No-op on native.
+ */
+function useEscapeDismissesTop(): void {
+  useEffect(() => {
+    if (Platform.OS !== 'web') return;
+    if (typeof window === 'undefined' || typeof document === 'undefined') return;
+    const handler = (e: KeyboardEvent) => {
+      if (e.key !== 'Escape') return;
+      const stack = getSnapshot();
+      const top = stack[stack.length - 1];
+      if (!top) return;
+      if (top.presentation.dismissOnBackdrop === false) return;
+      e.stopImmediatePropagation();
+      e.preventDefault();
+      requestDismiss(top.id);
+    };
+    window.addEventListener('keydown', handler, true);
+    return () => window.removeEventListener('keydown', handler, true);
+  }, []);
+}