@oxyhq/bloom 0.45.0 → 0.46.0

package/lib/typescript/module/surfaces/types.d.ts

@@ -0,0 +1,145 @@
+import type { ReactNode } from 'react';
+import type { StyleProp, ViewStyle } from 'react-native';
+import type { DialogInset, ResponsiveDialogPlacement } from '../dialog/types';
+/**
+ * How a surface renders — the placement + the `Dialog` sizing/chrome options a
+ * surface needs. This is the CONTENT-AGNOSTIC presentation config: it never
+ * references a route or screen name (Bloom's stack knows nothing about routes;
+ * the SDK layers its route registry on top).
+ *
+ * The values map 1:1 onto the shared {@link ../dialog/types#DialogProps}, so a
+ * surface reads/behaves identically to a hand-mounted `<Dialog>` with the same
+ * props — only stacked/coordinated by {@link SurfaceHost}.
+ */
+export interface SurfacePresentation {
+    /**
+     * Surface anchor. Defaults to `{ base: 'bottom', md: 'center' }` — a bottom
+     * sheet on narrow viewports that becomes a centered modal on wide ones (the
+     * ecosystem's canonical responsive "sheet"). Pass `'center'` for a plain
+     * modal, `'left'`/`'right'` for a drawer, or any responsive placement map.
+     */
+    placement?: ResponsiveDialogPlacement;
+    /** Side-sheet width (px) on wide screens. Forwarded to `Dialog`. */
+    width?: number;
+    /** Centered-card max width (px). Forwarded to `Dialog`. */
+    maxWidth?: number;
+    /** Bottom-sheet max height as a fraction of the viewport height. */
+    maxHeightRatio?: number;
+    /** Side-sheet inset (px) from the root overlay's edges. */
+    inset?: DialogInset;
+    /** Whether to render the drag handle in bottom-sheet mode. */
+    showHandle?: boolean;
+    /**
+     * Whether tapping the backdrop / pressing Escape / Android-back dismisses the
+     * surface. Defaults to `true`. Set `false` for a blocking surface that must be
+     * dismissed programmatically (e.g. an unanswered required prompt).
+     */
+    dismissOnBackdrop?: boolean;
+    /** Inner padding (px) of the surface content container. Forwarded to `Dialog`. */
+    contentPadding?: number;
+    /** Style overrides applied to the inner content container. */
+    style?: StyleProp<ViewStyle>;
+    /** Style overrides for the side/bottom placement panel surface. */
+    panelStyle?: StyleProp<ViewStyle>;
+    /** NativeWind classes for the side/bottom placement panel surface. */
+    panelClassName?: string;
+    /** Style for the root overlay (theme-var scope, rail offset, etc.). */
+    containerStyle?: StyleProp<ViewStyle>;
+    /** NativeWind classes for the root overlay. */
+    containerClassName?: string;
+    /** Accessibility label applied to the surface's dialog role. */
+    label?: string;
+    /** Stable testID forwarded to the underlying `Dialog`. */
+    testID?: string;
+}
+/** Options accepted by `present` / `SurfaceControls.present`. */
+export type PresentOptions = SurfacePresentation;
+/**
+ * Controls handed to a presented surface — both as the argument to its render
+ * function AND via {@link ../surfaces/useSurface#useSurface}. This is the DEPTH
+ * axis only: a surface can dismiss ITSELF (resolving its own `present()`
+ * promise) or `present` a CHILD surface stacked above it. Navigation WITHIN a
+ * surface (route history / drill-in) is deliberately NOT here — that is the
+ * SDK's route layer, which composes on top of this stack.
+ */
+export interface SurfaceControls {
+    /**
+     * Dismiss THIS surface, resolving the promise returned by the `present` call
+     * that created it with `result` (or `undefined`). Resolves immediately; the
+     * exit animation is cosmetic.
+     */
+    dismiss: (result?: unknown) => void;
+    /**
+     * Stack a CHILD surface directly above this one. Resolves with the child's
+     * dismissal result. The child paints above (higher layer) and captures
+     * backdrop/Escape/back until it is dismissed.
+     */
+    present: <Result = unknown>(render: SurfaceRenderFn, opts?: PresentOptions) => Promise<Result>;
+}
+/** A surface's content factory — receives its own {@link SurfaceControls}. */
+export type SurfaceRenderFn = (surface: SurfaceControls) => ReactNode;
+/** Lifecycle status of a stacked surface. */
+export type SurfaceStatus = 'open' | 'closing';
+/**
+ * One entry in the surface stack. `resolve` fulfils the `present()` promise; the
+ * `settled` guard makes resolution idempotent (resolve-once); `generation` is
+ * the per-entry stale-callback guard (carried from `BottomSheetBase`'s
+ * `closeGenerationRef`, keyed per entry id) so a completion callback from a
+ * superseded close cycle can never tear down the wrong state.
+ */
+export interface SurfaceEntry {
+    id: string;
+    render: SurfaceRenderFn;
+    presentation: SurfacePresentation;
+    status: SurfaceStatus;
+    resolve: (result: unknown) => void;
+    settled: boolean;
+    generation: number;
+}
+/** Options for the built-in {@link ../surfaces/prompts#confirm} surface. */
+export interface SurfaceConfirmOptions {
+    /** Headline. */
+    title: string;
+    /** Supporting copy. */
+    message?: string;
+    /** Confirm button label. Defaults to `'Confirm'`. */
+    confirmLabel?: string;
+    /** Cancel button label. Defaults to `'Cancel'`. */
+    cancelLabel?: string;
+    /** Style the confirm button as destructive (negative color). */
+    destructive?: boolean;
+    /** Hide the cancel button (a single-action acknowledgement). */
+    hideCancel?: boolean;
+    /**
+     * Backdrop / Escape / back dismiss (resolving `false`). Defaults to `true`;
+     * pass `false` for a blocking confirm that must be answered by a button.
+     */
+    dismissible?: boolean;
+    /** Placement override. Defaults to `'center'`. */
+    placement?: ResponsiveDialogPlacement;
+}
+/** Options for the built-in {@link ../surfaces/prompts#prompt} surface. */
+export interface SurfacePromptOptions {
+    /** Headline. */
+    title: string;
+    /** Supporting copy. */
+    message?: string;
+    /** Input placeholder. */
+    placeholder?: string;
+    /** Initial input value. */
+    defaultValue?: string;
+    /** Accessibility label for the input. Defaults to the `title`. */
+    inputLabel?: string;
+    /** Submit button label. Defaults to `'OK'`. */
+    confirmLabel?: string;
+    /** Cancel button label. Defaults to `'Cancel'`. */
+    cancelLabel?: string;
+    /**
+     * Backdrop / Escape / back dismiss (resolving `null`). Defaults to `true`;
+     * pass `false` for a blocking prompt.
+     */
+    dismissible?: boolean;
+    /** Placement override. Defaults to `'center'`. */
+    placement?: ResponsiveDialogPlacement;
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/typescript/module/surfaces/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/surfaces/types.ts"],"names":[],"mappings":"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"}

package/lib/typescript/module/surfaces/useSurface.d.ts

@@ -0,0 +1,21 @@
+import type { SurfaceControls } from './types';
+/**
+ * Context carrying the CURRENT surface's controls. The host wraps each presented
+ * surface's content in a provider bound to that entry's id, so a nested surface
+ * reads its OWN controls — `dismiss` targets this surface, `present` stacks a
+ * child above it.
+ */
+export declare const SurfaceContext: import("react").Context<SurfaceControls | null>;
+/**
+ * Read the current surface's {@link SurfaceControls} from inside a presented
+ * surface. Equivalent to the `surface` argument the render function receives —
+ * use whichever is convenient (props vs. context).
+ *
+ * DEPTH only: `dismiss` (resolve this surface's promise + close) and `present`
+ * (stack a child). Navigation within a surface is the SDK's route layer, not
+ * this hook.
+ *
+ * @throws if called outside a presented surface.
+ */
+export declare function useSurface(): SurfaceControls;
+//# sourceMappingURL=useSurface.d.ts.map

package/lib/typescript/module/surfaces/useSurface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSurface.d.ts","sourceRoot":"","sources":["../../../../src/surfaces/useSurface.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C;;;;;GAKG;AACH,eAAO,MAAM,cAAc,iDAA8C,CAAC;AAG1E;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,IAAI,eAAe,CAQ5C"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/bloom",
-  "version": "0.45.0",
+  "version": "0.46.0",
   "description": "Bloom UI — Oxy ecosystem component library for React Native + Expo + Web",
   "main": "lib/commonjs/index.js",
   "module": "lib/module/index.js",
@@ -28,6 +28,22 @@
         "default": "./lib/commonjs/index.js"
       }
     },
+    "./surfaces": {
+      "react-native": "./src/surfaces/index.ts",
+      "browser": {
+        "types": "./lib/typescript/module/surfaces/index.web.d.ts",
+        "import": "./lib/module/surfaces/index.web.js",
+        "require": "./lib/commonjs/surfaces/index.web.js"
+      },
+      "import": {
+        "types": "./lib/typescript/module/surfaces/index.d.ts",
+        "default": "./lib/module/surfaces/index.js"
+      },
+      "require": {
+        "types": "./lib/typescript/commonjs/surfaces/index.d.ts",
+        "default": "./lib/commonjs/surfaces/index.js"
+      }
+    },
     "./image-resolver": {
       "react-native": "./src/image-resolver/index.ts",
       "import": {

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';