@oxyhq/bloom 0.72.2 → 0.73.1

package/src/button/Button.tsx

@@ -1,4 +1,4 @@
-import React, { useMemo, memo } from 'react';
+import React, { useMemo, memo, type ComponentType } from 'react';
 import {
   ActivityIndicator,
   Animated,
@@ -7,9 +7,12 @@ import {
   StyleSheet,
   Text,
   View,
+  type PressableProps,
+  type StyleProp,
   type TextStyle,
   type ViewStyle,
 } from 'react-native';
+import { styled } from 'react-native-css';
 
 import { useTheme } from '../theme/use-theme';
 import { usePressAnimation } from '../hooks/usePressAnimation';
@@ -69,6 +72,73 @@ const PILL_RADIUS = 999;
 const PRESS_SCALE = 0.97;
 const SCALE_VARIANTS = new Set<string>(['primary', 'secondary', 'inverse']);
 
+// ---------------------------------------------------------------------------
+//  The button renders ONE node — the same shape the web fork renders (one
+//  `<button>`).
+//
+//  It used to be two: an unstyled `Animated.View` holding the press-scale
+//  transform, wrapping the `Pressable` that carried `className`, `style` and
+//  every visual. That wrapper — not the pressable — was the flex child of
+//  whatever laid the button out, and it hugged its content, so a caller's
+//  `className="flex-1"` (and `style={{ alignSelf }}`, and every other layout
+//  declaration) applied INSIDE a box that never grew. Nothing errored; the same
+//  call site behaved on web and did nothing on native, and consumers worked
+//  around it by wrapping every Bloom `Button` in their own `<View>`.
+//
+//  Collapsing the two nodes settles "which node does a class belong on?" by
+//  removing the choice: layout and visuals are one box here exactly as they are
+//  in the DOM, so a layout class and a visual class cannot land in different
+//  places. The touch target now scales with the press (0.97 — ~1px on a 40dp
+//  button, and the press is registered before it starts), the same trade
+//  `PressableScale` made when it dropped its own two-node structure.
+//
+//  `styled()` comes from Bloom's own `react-native-css` dependency rather than
+//  passing `className` as a bare prop and hoping the consumer's NativeWind
+//  interop recognises a component Bloom built at module scope. Same reasoning,
+//  and the same silent failure if skipped, as `typography/styled-text.ts`.
+//
+//  Both wrappers are built ONCE at module scope so the element type is stable
+//  across renders — one built during render remounts the subtree every time.
+// ---------------------------------------------------------------------------
+
+/**
+ * Exactly the prop surface `Button` hands to the pressable, and no wider.
+ * `Animated.createAnimatedComponent` maps `WithAnimatedValue` over every prop of
+ * the component it wraps, and doing that to the whole of `PressableProps`
+ * overflows the checker (`TS2590: union type that is too complex to represent`).
+ * Narrowing is also honest: the function form of `style` is deliberately
+ * excluded — see the `useInteractionState` comment in the component body for why
+ * Bloom never uses it.
+ */
+type ButtonPressableProps = Pick<
+  PressableProps,
+  | 'accessibilityHint'
+  | 'accessibilityLabel'
+  | 'accessibilityRole'
+  | 'accessibilityState'
+  | 'children'
+  | 'className'
+  | 'disabled'
+  | 'hitSlop'
+  | 'onPress'
+  | 'onPressIn'
+  | 'onPressOut'
+  | 'testID'
+> & { style?: StyleProp<ViewStyle> };
+
+/**
+ * The same `Pressable` object, typed down to {@link ButtonPressableProps}.
+ * `styled()` derives its mapping type from a dot-path union over the wrapped
+ * component's ENTIRE prop type, and the one over `PressableProps` also overflows
+ * the checker. Nothing changes at runtime — this is the identical component.
+ */
+const ButtonPressable: ComponentType<ButtonPressableProps> = Pressable;
+
+const StyledPressable: ComponentType<ButtonPressableProps> = styled(ButtonPressable, {
+  className: 'style',
+});
+const AnimatedPressable = Animated.createAnimatedComponent(StyledPressable);
+
 const ButtonComponent: React.FC<ButtonProps> = ({
   onPress,
   children,
@@ -170,6 +240,16 @@ const ButtonComponent: React.FC<ButtonProps> = ({
         styles.borderRadius = PILL_RADIUS;
         break;
       case 'icon':
+        // Resolved tokens, not `className="bg-background border border-border"`.
+        // The class form made the caller's `className` and the icon's own chrome
+        // compete for one slot — `<IconButton className="flex-1" />` replaced the
+        // default and shipped a transparent, borderless icon button — and it left
+        // the chrome dependent on the consumer's Tailwind pipeline resolving
+        // Bloom's color names. These are the SAME tokens `Button.web.tsx`'s
+        // `resolveVariantStyle('icon')` already writes inline.
+        styles.backgroundColor = theme.colors.background;
+        styles.borderWidth = 1;
+        styles.borderColor = theme.colors.border;
         styles.borderRadius = PILL_RADIUS;
         styles.padding = 8;
         styles.width = sizeConfig.minHeight;
@@ -220,7 +300,6 @@ const ButtonComponent: React.FC<ButtonProps> = ({
 
   const defaultHitSlop = variant === 'icon' ? ICON_HIT_SLOP : undefined;
   const resolvedActiveOpacity = activeOpacity ?? (variant === 'icon' ? 0.7 : 0.8);
-  const resolvedClassName = className ?? (variant === 'icon' ? 'bg-background border border-border' : undefined);
 
   const content = (
     <>
@@ -233,44 +312,48 @@ const ButtonComponent: React.FC<ButtonProps> = ({
   );
 
   return (
-    <Animated.View style={hasScaleFeedback ? { transform: [{ scale: scaleAnim }] } : undefined}>
-      <Pressable
-        {...(resolvedClassName ? { className: resolvedClassName } as Record<string, string> : {})}
-        style={[
-          baseStyles,
-          disabled && !loading && { opacity: 0.5 },
-          pressed && !hasScaleFeedback && !isInteractionBlocked && { opacity: resolvedActiveOpacity },
-          style,
-        ]}
-        onPress={isInteractionBlocked ? undefined : onPress}
-        onPressIn={handlePressIn}
-        onPressOut={handlePressOut}
-        disabled={isInteractionBlocked}
-        hitSlop={hitSlop ?? defaultHitSlop}
-        accessibilityLabel={accessibilityLabel}
-        accessibilityHint={accessibilityHint}
-        accessibilityRole="button"
-        accessibilityState={loading ? { disabled: isInteractionBlocked, busy: true } : { disabled: isInteractionBlocked }}
-        testID={testID}
-      >
-        {loading ? (
-          <>
-            <View
-              style={styles.loadingHiddenContent}
-              importantForAccessibility="no-hide-descendants"
-              accessibilityElementsHidden
-            >
-              {content}
-            </View>
-            <View style={styles.loadingOverlay}>
-              <ActivityIndicator size="small" color={loadingColor ?? resolvedTextColor} />
-            </View>
-          </>
-        ) : (
-          content
-        )}
-      </Pressable>
-    </Animated.View>
+    <AnimatedPressable
+      className={className}
+      style={[
+        baseStyles,
+        disabled && !loading && { opacity: 0.5 },
+        pressed && !hasScaleFeedback && !isInteractionBlocked && { opacity: resolvedActiveOpacity },
+        // Before the caller's `style`, so `style` keeps winning the whole array
+        // the way it always has (and the way the web fork spreads it last). The
+        // cost is that a caller who sets `transform` on a scale variant replaces
+        // the press scale instead of composing with it — when the transform sat
+        // on a separate wrapper node the two multiplied.
+        hasScaleFeedback ? { transform: [{ scale: scaleAnim }] } : null,
+        style,
+      ]}
+      onPress={isInteractionBlocked ? undefined : onPress}
+      onPressIn={handlePressIn}
+      onPressOut={handlePressOut}
+      disabled={isInteractionBlocked}
+      hitSlop={hitSlop ?? defaultHitSlop}
+      accessibilityLabel={accessibilityLabel}
+      accessibilityHint={accessibilityHint}
+      accessibilityRole="button"
+      accessibilityState={loading ? { disabled: isInteractionBlocked, busy: true } : { disabled: isInteractionBlocked }}
+      testID={testID}
+    >
+      {loading ? (
+        <>
+          <View
+            style={styles.loadingHiddenContent}
+            importantForAccessibility="no-hide-descendants"
+            accessibilityElementsHidden
+          >
+            {content}
+          </View>
+          <View style={styles.loadingOverlay}>
+            <ActivityIndicator size="small" color={loadingColor ?? resolvedTextColor} />
+          </View>
+        </>
+      ) : (
+        content
+      )}
+    </AnimatedPressable>
   );
 };
 

package/src/button/Button.web.tsx

@@ -18,9 +18,17 @@ import type { ButtonProps, ButtonSize, ButtonVariant } from './types';
 export type { ButtonProps, ButtonVariant, ButtonSize } from './types';
 
 // ---------------------------------------------------------------------------
-//  Geometry — mirrors the native (`Button.tsx`) impl exactly so the web button
-//  is pixel-consistent with native. Sizes below are the resolved primitives;
-//  the shadcn-style aliases (`sm | md | lg | icon`) are normalized first.
+//  Geometry — mirrors the native (`Button.tsx`) impl so the web button is
+//  pixel-consistent with native. Sizes below are the resolved primitives; the
+//  shadcn-style aliases (`sm | md | lg | icon`) are normalized first.
+//
+//  ONE deliberate exception, in `containerStyle`: `text`/`link` clear
+//  `minHeight` here so the control hugs its label and sits inline (which is what
+//  makes `asChild` anchors work), while native keeps the size config's value to
+//  preserve the touch target. The 4/8 padding override those variants get is NOT
+//  an exception — native applies exactly the same one, so `text` is a compact
+//  affordance and `ghost` a full-size button without a background on both
+//  platforms. Only the variant COLOR table below is shared between them.
 // ---------------------------------------------------------------------------
 
 type NativeSize = 'small' | 'medium' | 'large';

package/src/button/types.ts

@@ -11,6 +11,14 @@ import type { StyleProp, ViewStyle, TextStyle } from 'react-native';
  *     the set. On native they fall back to a sensible equivalent
  *     (`outline → secondary`, `link → text`, `destructive → primary` tinted with
  *     the negative token) so passing them never crashes a native consumer.
+ *
+ * `text` (and its web alias `link`) is DELIBERATELY not a transparent `ghost`:
+ * it is the compact inline affordance, so it overrides the size config's padding
+ * down to 4/8 on BOTH platforms. `ghost` keeps the full padding — it is a
+ * regular button that happens to have no background. The one geometry that does
+ * differ by platform is `minHeight`: web clears it for `text`/`link` so the
+ * control hugs its label and sits inline, native keeps the size config's value
+ * because a finger needs the target and a cursor does not.
  */
 export type ButtonVariant =
   | 'primary'

package/src/context-menu/index.web.tsx

@@ -18,10 +18,9 @@ import { Pressable, StyleSheet, View } from 'react-native';
 
 import { useTheme } from '../theme/use-theme';
 import { Text } from '../typography';
-import { Backdrop } from '../overlay';
+import { Backdrop, OverlayRoot } from '../overlay';
 import { Portal } from '../portal/index.web';
 import { useInteractionState } from '../hooks/useInteractionState';
-import { createOverlayZIndex } from '../styles/z-index';
 import { WEB_POSITION_FIXED } from '../styles/web-view-style';
 import {
   resolveDropdownPlacement,
@@ -40,7 +39,6 @@ import type {
   ItemContextValue,
 } from './types';
 
-const contextMenuZIndex = createOverlayZIndex();
 const VIEWPORT_GUTTER = 8;
 
 // ---------------------------------------------------------------------------
@@ -211,31 +209,38 @@ export function ContextMenuContent({ children, style }: ContextMenuContentProps)
 
   return (
     <Portal>
-      <Backdrop
-        style={styles.backdrop}
-        onPress={close}
-        accessibilityLabel="Close context menu"
-      />
-      <View
-        ref={attachMenu}
-        style={[
-          styles.dropdown,
-          {
-            // The raw click point is the pre-measurement anchor; the layout
-            // effect above replaces it before the browser paints.
-            top: placement?.top ?? position.y,
-            left: placement?.left ?? position.x,
-            backgroundColor: theme.isDark
-              ? theme.colors.backgroundSecondary
-              : theme.colors.background,
-            borderColor: theme.colors.borderLight,
-            ...bloomShadowStyle('m'),
-          },
-          style,
-        ]}
-      >
-        {children}
-      </View>
+      {/* `OverlayRoot` takes this surface's place in the open-order overlay
+          stack, so it paints above anything opened before it (see
+          `src/overlay/stack.ts`). It is `box-none`, so the area outside the
+          panel stays click-through and the backdrop below still takes its own
+          presses. */}
+      <OverlayRoot>
+        <Backdrop
+          style={styles.backdrop}
+          onPress={close}
+          accessibilityLabel="Close context menu"
+        />
+        <View
+          ref={attachMenu}
+          style={[
+            styles.dropdown,
+            {
+              // The raw click point is the pre-measurement anchor; the layout
+              // effect above replaces it before the browser paints.
+              top: placement?.top ?? position.y,
+              left: placement?.left ?? position.x,
+              backgroundColor: theme.isDark
+                ? theme.colors.backgroundSecondary
+                : theme.colors.background,
+              borderColor: theme.colors.borderLight,
+              ...bloomShadowStyle('m'),
+            },
+            style,
+          ]}
+        >
+          {children}
+        </View>
+      </OverlayRoot>
     </Portal>
   );
 }
@@ -374,13 +379,11 @@ const styles = StyleSheet.create({
     left: 0,
     right: 0,
     bottom: 0,
-    zIndex: contextMenuZIndex.backdrop,
     // Opt back in from the Portal root's `pointer-events: none`.
     pointerEvents: 'auto',
   },
   dropdown: {
     position: WEB_POSITION_FIXED,
-    zIndex: contextMenuZIndex.surface,
     borderRadius: 8,
     padding: 4,
     borderWidth: 1,

package/src/dialog/Dialog.tsx

@@ -26,8 +26,7 @@ import Animated, {
 } from 'react-native-reanimated';
 
 import { BottomSheet, type BottomSheetRef } from '../bottom-sheet';
-import { Backdrop } from '../overlay';
-import { Z_INDEX, Z_INDEX_LAYER_STEP } from '../styles/z-index';
+import { Backdrop, OverlayRoot } from '../overlay';
 import { useTheme } from '../theme/use-theme';
 import { Context, useDialogControl } from './context';
 import { DialogBody } from './DialogContent';
@@ -117,7 +116,6 @@ function CenteredOrSideDialog({
   scrollable,
   morph,
   placement,
-  layer,
   width = DEFAULT_SIDE_WIDTH,
   inset,
   dismissOnBackdrop = true,
@@ -297,7 +295,6 @@ function CenteredOrSideDialog({
           open={sideOpen}
           onDismiss={handleDismiss}
           side={placement}
-          layer={layer}
           width={width}
           inset={inset}
           dismissOnBackdrop={dismissOnBackdrop}
@@ -393,7 +390,6 @@ function SideSheet({
   open,
   onDismiss,
   side,
-  layer,
   width,
   inset,
   dismissOnBackdrop,
@@ -417,7 +413,6 @@ function SideSheet({
   open: boolean;
   onDismiss: () => void;
   side: 'left' | 'right';
-  layer?: number;
   width: number;
   inset?: DialogInset;
   dismissOnBackdrop: boolean;
@@ -518,15 +513,10 @@ function SideSheet({
   if (!mounted) return null;
 
   return (
-    <View
-      pointerEvents="box-none"
-      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,
-      ]}
+    // `OverlayRoot` takes this drawer's place in the open-order overlay stack.
+    // It mounts here, past the `mounted` guard, so the rank tracks OPENING.
+    <OverlayRoot
+      style={[sideStyles.root, containerStyle]}
       {...(containerClassName ? ({ className: containerClassName } as Record<string, string>) : {})}
     >
       <Backdrop
@@ -575,13 +565,14 @@ function SideSheet({
           <View style={{ padding: contentPadding }}>{children}</View>
         )}
       </Animated.View>
-    </View>
+    </OverlayRoot>
   );
 }
 
 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.
+  // No `zIndex` here: the drawer's depth relative to other surfaces is the
+  // overlay stack's decision, applied by `OverlayRoot` (see
+  // `src/overlay/stack.ts`).
   root: {
     ...StyleSheet.absoluteFill,
   },

package/src/dialog/Dialog.web.tsx

@@ -25,7 +25,7 @@ import { RemoveScrollBar } from 'react-remove-scroll-bar';
 
 import { Backdrop, OverlayRoot } from '../overlay';
 import { Portal } from '../portal/index.web';
-import { createOverlayZIndex } from '../styles/z-index';
+import { Z_INDEX } from '../styles/z-index';
 import { WEB_POSITION_FIXED, type WebCssStyle } from '../styles/web-view-style';
 import { bloomShadowStyle } from '../design-tokens/shadows';
 import { useTheme } from '../theme/use-theme';
@@ -170,7 +170,6 @@ function CenterOrSideDialog({
   actions,
   header,
   placement,
-  layer,
   width = DEFAULT_SIDE_WIDTH,
   maxWidth = DEFAULT_CENTER_MAX_WIDTH,
   inset,
@@ -192,11 +191,6 @@ 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;
@@ -342,46 +336,51 @@ function CenterOrSideDialog({
         <Context.Provider value={context}>
           <ClosingContext.Provider value={isClosing}>
             <RemoveScrollBar />
-            {/* The press target IS the full-viewport box, so it uses
-                `Backdrop` (which opts back in from the Portal root's
-                `pointer-events: none` via the `pointerEvents` PROP — the style
-                form is dropped before it reaches the DOM, see `src/overlay`)
-                and lays the panel out inside itself. */}
-            <Backdrop
-              onPress={() => close()}
-              disabled={!dismissOnBackdrop}
-              accessibilityLabel={label ? `Dismiss ${label}` : 'Dismiss dialog'}
-              // The fade rides on the LAYERS, never on the press target: an
-              // opacity animation on the blur's ancestor composites the group in
-              // isolation and leaves `backdrop-filter` nothing to sample.
-              progress={backdropFade}
-              style={{
-                position: WEB_POSITION_FIXED,
-                zIndex: dialogZIndex.backdrop,
-                alignItems: 'center',
-                justifyContent: 'center',
-                paddingHorizontal: 20,
-              }}
-            >
-              <DialogPanel
-                testID={testID}
-                label={label}
-                title={title}
-                description={description}
-                actions={actions}
-                header={header}
-                style={style}
-                maxWidth={maxWidth}
-                contentPadding={contentPadding}
-                maxHeightRatio={maxHeightRatio}
-                scrollable={scrollable}
-                morph={morph}
-                surfaceZIndex={dialogZIndex.surface}
-                isClosing={isClosing}
+            {/* `OverlayRoot` takes this dialog's place in the open-order
+                overlay stack. It mounts here, inside the `isOpen` guard, which
+                is what makes the rank track OPENING rather than mounting — the
+                dialog is declared once at the app root and stays mounted for
+                the app's lifetime. */}
+            <OverlayRoot>
+              {/* The press target IS the full-viewport box, so it uses
+                  `Backdrop` (which opts back in from the Portal root's
+                  `pointer-events: none` via the `pointerEvents` PROP — the style
+                  form is dropped before it reaches the DOM, see `src/overlay`)
+                  and lays the panel out inside itself. */}
+              <Backdrop
+                onPress={() => close()}
+                disabled={!dismissOnBackdrop}
+                accessibilityLabel={label ? `Dismiss ${label}` : 'Dismiss dialog'}
+                // The fade rides on the LAYERS, never on the press target: an
+                // opacity animation on the blur's ancestor composites the group in
+                // isolation and leaves `backdrop-filter` nothing to sample.
+                progress={backdropFade}
+                style={{
+                  position: WEB_POSITION_FIXED,
+                  alignItems: 'center',
+                  justifyContent: 'center',
+                  paddingHorizontal: 20,
+                }}
               >
-                {children}
-              </DialogPanel>
-            </Backdrop>
+                <DialogPanel
+                  testID={testID}
+                  label={label}
+                  title={title}
+                  description={description}
+                  actions={actions}
+                  header={header}
+                  style={style}
+                  maxWidth={maxWidth}
+                  contentPadding={contentPadding}
+                  maxHeightRatio={maxHeightRatio}
+                  scrollable={scrollable}
+                  morph={morph}
+                  isClosing={isClosing}
+                >
+                  {children}
+                </DialogPanel>
+              </Backdrop>
+            </OverlayRoot>
           </ClosingContext.Provider>
         </Context.Provider>
       </Portal>
@@ -407,8 +406,6 @@ function CenterOrSideDialog({
             inset={inset}
             dismissOnBackdrop={dismissOnBackdrop}
             contentPadding={contentPadding}
-            backdropZIndex={dialogZIndex.backdrop}
-            surfaceZIndex={dialogZIndex.surface}
             onDismiss={close}
             panelStyle={panelStyle}
             panelClassName={panelClassName}
@@ -437,7 +434,6 @@ function DialogPanel({
   maxHeightRatio,
   scrollable,
   morph,
-  surfaceZIndex,
   isClosing,
   children,
 }: {
@@ -453,7 +449,6 @@ function DialogPanel({
   maxHeightRatio?: number;
   scrollable?: boolean;
   morph?: boolean;
-  surfaceZIndex: number;
   isClosing: boolean;
   children?: React.ReactNode;
 }) {
@@ -518,7 +513,12 @@ function DialogPanel({
           // Design-system overlay elevation (`shadow-m`) as a `boxShadow` — RN-Web
           // deprecated the `shadow*` style props.
           ...bloomShadowStyle('m'),
-          zIndex: surfaceZIndex,
+          // Above this surface's OWN backdrop, and nothing more: `OverlayRoot`
+          // sets a z-index and a fixed position, so it is a stacking context and
+          // this value is scoped inside it. Where this dialog sits relative to
+          // OTHER surfaces is the overlay stack's decision, made once on
+          // `OverlayRoot` (see `src/overlay/stack.ts`) — never a number here.
+          zIndex: Z_INDEX.raised,
         },
         isClosing ? ZOOM_FADE_OUT : ZOOM_FADE_IN,
         // Drives `height` (and `maxWidth`) only while a morph is in flight; at
@@ -612,8 +612,6 @@ function SheetSurface({
   inset,
   dismissOnBackdrop,
   contentPadding,
-  backdropZIndex,
-  surfaceZIndex,
   onDismiss,
   panelStyle,
   panelClassName,
@@ -635,8 +633,6 @@ function SheetSurface({
   inset?: DialogInset;
   dismissOnBackdrop: boolean;
   contentPadding: number;
-  backdropZIndex: number;
-  surfaceZIndex: number;
   onDismiss: () => void;
   panelStyle?: StyleProp<ViewStyle>;
   panelClassName?: string;
@@ -714,7 +710,7 @@ function SheetSurface({
 
   return (
     <OverlayRoot
-      style={[sheetStyles.root, { zIndex: backdropZIndex }, containerStyle]}
+      style={[sheetStyles.root, containerStyle]}
       {...(containerClassName ? ({ className: containerClassName } as Record<string, string>) : {})}
     >
       <Backdrop
@@ -744,7 +740,12 @@ function SheetSurface({
           sheetStyles.panel,
           {
             backgroundColor: theme.colors.background,
-            zIndex: surfaceZIndex,
+            // Above this surface's OWN backdrop, and nothing more: `OverlayRoot`
+            // sets a z-index and a fixed position, so it is a stacking context and
+            // this value is scoped inside it. Where this dialog sits relative to
+            // OTHER surfaces is the overlay stack's decision, made once on
+            // `OverlayRoot` (see `src/overlay/stack.ts`) — never a number here.
+            zIndex: Z_INDEX.raised,
             pointerEvents: 'auto',
             // Design-system overlay elevation (`shadow-m`) as a `boxShadow`.
             ...bloomShadowStyle('m'),
@@ -866,9 +867,10 @@ export function AutoMountedDialog({
 // The annotation supplies the contextual type instead, so the literals narrow and
 // a genuine mistake still fails.
 const sheetStyles: Record<'root' | 'backdrop' | 'panel', ViewStyle> = {
-  // `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.
+  // No overlay `zIndex` here: `SheetSurface` renders an `OverlayRoot`, which
+  // assigns this drawer's depth from the open-order overlay stack, so a drawer
+  // opened on top of another surface paints above it (see
+  // `src/overlay/stack.ts`).
   root: {
     position: WEB_POSITION_FIXED,
     top: 0,

package/src/dialog/types.ts

@@ -350,16 +350,6 @@ 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;
 }>;
 
 /**