@multiplatform.one/forms 7.48.0 → 7.49.0

package/src/FloatingPanel/index.native.tsx

@@ -83,6 +83,8 @@ import {
   motionDurationMs,
 } from "@multiplatform.one/theme";
 import { View, YStack } from "tamagui";
+import { useOverlayZIndex } from "../shared/overlayStack";
+import { OverlayWindow } from "../shared/OverlayWindow";
 import { t } from "../shared/t";
 import { useKeyboardInset } from "../shared/useKeyboardInset";
 import type { FloatingPanelProps } from "./index";
@@ -143,6 +145,7 @@ export function FloatingPanel({
 }: FloatingPanelProps) {
   // The panel floats over the page: it never inherits a painted ancestor.
   const { knobProps } = useResolvedKnobs({ painted: false });
+  const windowZIndex = useOverlayZIndex("sheet");
   const children = <Surface painted={false}>{panelChildren}</Surface>;
   const slideTransition = knobProps.motion.slide.transition;
   const enterDuration = motionDurationMs(slideTransition);
@@ -522,118 +525,120 @@ export function FloatingPanel({
           onNativeShow?.();
         }}
       >
-        {atPoint && pressPoint ? (
-          <PointPanel
-            key={`${pressPoint.x},${pressPoint.y}`}
-            point={pressPoint}
-            bounds={{
-              top: topInset + panelViewportPadding,
-              left: (safeArea?.left ?? 0) + panelViewportPadding,
-              right: windowWidth - (safeArea?.right ?? 0) - panelViewportPadding,
-              bottom:
-                windowHeight -
-                Math.max(safeArea?.bottom ?? 0, keyboardInset) -
-                panelViewportPadding,
-            }}
-            framePadding={framePadding}
-            frameGap={frameGap}
-            onBackdropPress={handleBackdropPress}
-            onEscape={close}
-          >
-            {header}
-            {children}
-          </PointPanel>
-        ) : (
-          /*
+        <OverlayWindow zIndex={windowZIndex}>
+          {atPoint && pressPoint ? (
+            <PointPanel
+              key={`${pressPoint.x},${pressPoint.y}`}
+              point={pressPoint}
+              bounds={{
+                top: topInset + panelViewportPadding,
+                left: (safeArea?.left ?? 0) + panelViewportPadding,
+                right: windowWidth - (safeArea?.right ?? 0) - panelViewportPadding,
+                bottom:
+                  windowHeight -
+                  Math.max(safeArea?.bottom ?? 0, keyboardInset) -
+                  panelViewportPadding,
+              }}
+              framePadding={framePadding}
+              frameGap={frameGap}
+              onBackdropPress={handleBackdropPress}
+              onEscape={close}
+            >
+              {header}
+              {children}
+            </PointPanel>
+          ) : (
+            /*
           A plain padded column, not KeyboardAvoidingView: inside a Modal the
           latter pads the container while the sheet keeps its own fixed height,
           so the sheet overflows off the TOP instead of shrinking (MPO-64).
         */
-          <RNView style={{ flex: 1, justifyContent: "flex-end", paddingBottom: keyboardInset }}>
-            <Pressable
-              style={StyleSheet.absoluteFill}
-              onPress={handleBackdropPress}
-              accessibilityRole="button"
-              accessibilityLabel={t("Close")}
-            >
-              <View flex={1} backgroundColor="$shadow6" />
-            </Pressable>
-            {/*
+            <RNView style={{ flex: 1, justifyContent: "flex-end", paddingBottom: keyboardInset }}>
+              <Pressable
+                style={StyleSheet.absoluteFill}
+                onPress={handleBackdropPress}
+                accessibilityRole="button"
+                accessibilityLabel={t("Close")}
+              >
+                <View flex={1} backgroundColor="$shadow6" />
+              </Pressable>
+              {/*
             Sheet sits above the absoluteFill backdrop in z-order (later sibling).
             Do NOT claim the responder on a wrapper here — that steals presses
             from option rows / calendar days and blocks commit.
           */}
-            <Animated.View
-              testID="floating-panel-sheet"
-              onLayout={(e) => {
-                // Travel distance for a dismiss, and the basis for the detents.
-                // A content-sized picker is shorter than maxHeight, and sliding
-                // it by maxHeight would overshoot into a visible lag.
-                if (restHeightRef.current !== null) return;
-                const h = Math.round(e.nativeEvent.layout.height);
-                if (h <= 0) return;
-                naturalRef.current = h;
-                filledRef.current = h >= maxHeightRef.current - 1;
-                if (h !== measuredHeight) setMeasuredHeight(h);
-              }}
-              style={{
-                // MPO-64: a flex child defaults to flexShrink 0, so without this
-                // the sheet cannot give way to the keyboard at all.
-                flexShrink: 1,
-                minHeight: 0,
-                maxHeight: frameCap,
-                transform: [{ translateY }],
-              }}
-            >
-              <YStack
-                {...knobProps.elevatedSurface}
-                borderBottomLeftRadius={0}
-                borderBottomRightRadius={0}
-                maxHeight={maxHeight}
-                flexShrink={1}
-                minHeight={0}
-                // sheetFill opens at full sheet height (flexShrink keeps the
-                // keyboard from pushing the top of the sheet off-screen).
-                {...(sheetFill ? { height: maxHeight } : undefined)}
-                paddingTop="$2"
-                paddingBottom={sheetBottomPadding}
-                // VoiceOver escape gesture (two-finger Z) dismisses the sheet.
-                onAccessibilityEscape={close}
+              <Animated.View
+                testID="floating-panel-sheet"
+                onLayout={(e) => {
+                  // Travel distance for a dismiss, and the basis for the detents.
+                  // A content-sized picker is shorter than maxHeight, and sliding
+                  // it by maxHeight would overshoot into a visible lag.
+                  if (restHeightRef.current !== null) return;
+                  const h = Math.round(e.nativeEvent.layout.height);
+                  if (h <= 0) return;
+                  naturalRef.current = h;
+                  filledRef.current = h >= maxHeightRef.current - 1;
+                  if (h !== measuredHeight) setMeasuredHeight(h);
+                }}
+                style={{
+                  // MPO-64: a flex child defaults to flexShrink 0, so without this
+                  // the sheet cannot give way to the keyboard at all.
+                  flexShrink: 1,
+                  minHeight: 0,
+                  maxHeight: frameCap,
+                  transform: [{ translateY }],
+                }}
               >
-                {/*
+                <YStack
+                  {...knobProps.elevatedSurface}
+                  borderBottomLeftRadius={0}
+                  borderBottomRightRadius={0}
+                  maxHeight={maxHeight}
+                  flexShrink={1}
+                  minHeight={0}
+                  // sheetFill opens at full sheet height (flexShrink keeps the
+                  // keyboard from pushing the top of the sheet off-screen).
+                  {...(sheetFill ? { height: maxHeight } : undefined)}
+                  paddingTop="$2"
+                  paddingBottom={sheetBottomPadding}
+                  // VoiceOver escape gesture (two-finger Z) dismisses the sheet.
+                  onAccessibilityEscape={close}
+                >
+                  {/*
                 The grab ZONE, not just the 4pt pill: a 4pt tall target is
                 unhittable. The gesture lives here rather than on the whole
                 sheet so it never fights the ScrollView inside it, which is the
                 same division iOS uses.
               */}
-                <RNView
-                  {...panResponder.panHandlers}
-                  accessibilityRole="adjustable"
-                  accessibilityLabel={t("Drag to resize")}
-                  style={{
-                    alignSelf: "stretch",
-                    alignItems: "center",
-                    paddingTop: 4,
-                    paddingBottom: 12,
-                  }}
-                >
-                  <View width={40} height={4} borderRadius={2} backgroundColor="$color8" />
-                </RNView>
-                <YStack
-                  padding={framePadding}
-                  gap={frameGap}
-                  flexShrink={1}
-                  {...(sheetFill ? { flex: 1, minHeight: 0 } : undefined)}
-                >
-                  <Surface size="$true">
-                    {header}
-                    {content}
-                  </Surface>
+                  <RNView
+                    {...panResponder.panHandlers}
+                    accessibilityRole="adjustable"
+                    accessibilityLabel={t("Drag to resize")}
+                    style={{
+                      alignSelf: "stretch",
+                      alignItems: "center",
+                      paddingTop: 4,
+                      paddingBottom: 12,
+                    }}
+                  >
+                    <View width={40} height={4} borderRadius={2} backgroundColor="$color8" />
+                  </RNView>
+                  <YStack
+                    padding={framePadding}
+                    gap={frameGap}
+                    flexShrink={1}
+                    {...(sheetFill ? { flex: 1, minHeight: 0 } : undefined)}
+                  >
+                    <Surface size="$true">
+                      {header}
+                      {content}
+                    </Surface>
+                  </YStack>
                 </YStack>
-              </YStack>
-            </Animated.View>
-          </RNView>
-        )}
+              </Animated.View>
+            </RNView>
+          )}
+        </OverlayWindow>
       </Modal>
     </>
   );

package/src/FloatingPanel/index.tsx

@@ -28,7 +28,7 @@ import { useReturnFocusOnClose, useSheetModalFocus } from "../shared/focusManage
 import { useSheetEscapeDismiss } from "../shared/useSheetEscapeDismiss";
 import { useFloatingPanel, panelViewportPadding } from "./useFloatingPanel";
 import type { PanelWidthMode } from "./useFloatingPanel";
-import { zIndex } from "../shared/zIndex";
+import { OverlayStackProvider, useOverlayZIndex } from "../shared/overlayStack";
 import { isNestedPanelAction, type PanelActionEvent } from "./nestedAction";
 import { PanelPortal } from "./PanelPortal";
 import {
@@ -490,6 +490,7 @@ function FloatingPanelSheet({
   escapeTarget = "window",
 }: FloatingPanelProps & { escapeTarget?: "window" | "document" }) {
   const { knobProps } = useResolvedKnobs({ painted: false });
+  const sheetZIndex = useOverlayZIndex("sheet");
   // LC-24 / A-ENTEREXIT: honor animation=none (undefined) — do not hardcode "medium".
   const slideMotion = {
     ...knobProps.motion.slide,
@@ -585,7 +586,8 @@ function FloatingPanelSheet({
         dismissOnSnapToBottom
         position={position}
         onPositionChange={setPosition}
-        zIndex={zIndex.sheet}
+        zIndex={sheetZIndex}
+        portalProps={{ zIndex: sheetZIndex }}
         {...transitionProps(slideMotion)}
       >
         <Sheet.Overlay
@@ -608,14 +610,16 @@ function FloatingPanelSheet({
           padding={framePadding}
           gap={frameGap}
         >
-          {header}
-          {scrollable ? (
-            <Sheet.ScrollView flex={header ? 1 : undefined} {...scrollViewProps}>
-              {children}
-            </Sheet.ScrollView>
-          ) : (
-            children
-          )}
+          <OverlayStackProvider zIndex={sheetZIndex}>
+            {header}
+            {scrollable ? (
+              <Sheet.ScrollView flex={header ? 1 : undefined} {...scrollViewProps}>
+                {children}
+              </Sheet.ScrollView>
+            ) : (
+              children
+            )}
+          </OverlayStackProvider>
         </Sheet.Frame>
       </Sheet>
     </>
@@ -642,6 +646,7 @@ function FloatingPanelWeb({
   anchorRect,
   ...sheetProps
 }: FloatingPanelProps) {
+  const panelZIndex = useOverlayZIndex("dropdown");
   const [collisionSheet, setCollisionSheet] = useState(false);
   const isFill = sizing === "fill";
   const isContextMenu = openOn === "contextmenu";
@@ -1193,7 +1198,7 @@ function FloatingPanelWeb({
                 top: overlayStyleRef.current?.top ?? panel.y ?? 0,
                 left: overlayStyleRef.current?.left ?? panel.x ?? 0,
                 scrollbarWidth: "none" as any,
-                zIndex: zIndex.dropdown,
+                zIndex: panelZIndex,
                 overflow: "auto",
                 ...(cover && !isContextMenu ? { overflowX: "hidden" as const } : {}),
                 ...panel.floatingStyleRef.current,
@@ -1261,7 +1266,7 @@ function FloatingPanelWeb({
               {...(contentPadding !== "none" ? panel.knobProps.panelPadding : undefined)}
               {...(contentPadding !== "none" ? panel.knobProps.gapLg : undefined)}
             >
-              {children}
+              <OverlayStackProvider zIndex={panelZIndex}>{children}</OverlayStackProvider>
             </View>
             <ScrollArrow
               direction="down"

package/src/fields/Combobox/index.tsx

@@ -67,7 +67,7 @@ import {
   useViewportGtSm,
 } from "../../FloatingPanel";
 import { PanelPortal } from "../../FloatingPanel/PanelPortal";
-import { zIndex } from "../../shared/zIndex";
+import { useOverlayZIndex } from "../../shared/overlayStack";
 import { useDragScroll } from "../../shared/useDragScroll";
 import { useIsInTableCell } from "../../shared/tableCellContext";
 import { orderOptionsBySelected, type SelectedOrder } from "../selectedOrder";
@@ -518,6 +518,7 @@ function FloatingComboboxCore({
   open: openProp,
   onOpenChange,
 }: FloatingComboboxCoreProps) {
+  const overlayZIndex = useOverlayZIndex("dropdown");
   const { style: elevatedSurfaceStyle, ...elevatedSurfaceProps } = knobProps.elevatedSurface;
   const hydrationTouch = useTouchSurface();
   if (isWeb) ensureKeyboardModalityTracking();
@@ -1498,7 +1499,7 @@ function FloatingComboboxCore({
                   position: "fixed",
                   top: 0,
                   left: 0,
-                  zIndex: zIndex.dropdown,
+                  zIndex: overlayZIndex,
                   overflow: "hidden",
                   display: "flex",
                   flexDirection: "column",

package/src/fields/Geolocation/index.tsx

@@ -32,7 +32,7 @@ import { formCommonColors, formInputColors } from "../../shared/colorRamps";
 import { t } from "../../shared/t";
 import { pressSlopProps } from "../../shared/pressSlopProps";
 import { useIsInTableCell } from "../../shared/tableCellContext";
-import { zIndex } from "../../shared/zIndex";
+import { useOverlayZIndex } from "../../shared/overlayStack";
 import {
   clampRadiusForLargeComponent,
   getFieldError,
@@ -878,6 +878,7 @@ export function Geolocation({
   reverseGeocode: reverseGeocodeProp,
   geocoder,
 }: GeolocationProps) {
+  const overlayZIndex = useOverlayZIndex("dropdown");
   const hydrationTouch = useTouchSurface();
   const { resolvedForm, knobProps, id } = useFormField({ form: formProp, id: idProp });
   const resolvedValidators = useResolvedValidators(required, validators, label, name);
@@ -1432,7 +1433,7 @@ export function Geolocation({
             top="100%"
             left={0}
             right={0}
-            zIndex={zIndex.dropdown}
+            zIndex={overlayZIndex}
             {...knobProps.elevatedSurface}
             overflow="hidden"
           >

package/src/fields/MentionInput/index.tsx

@@ -23,7 +23,7 @@ import {
 import { formCommonColors, formInputColors } from "../../shared/colorRamps";
 import { ScrollArrow } from "../../shared/floatingList";
 import { Skeleton } from "../../Skeleton";
-import { zIndex } from "../../shared/zIndex";
+import { useOverlayZIndex } from "../../shared/overlayStack";
 import { useFloatingPanel } from "../../FloatingPanel";
 import { PanelPortal } from "../../FloatingPanel/PanelPortal";
 import { Field, FieldLayout } from "../../fieldLayout";
@@ -240,6 +240,7 @@ export function MentionInput<
   TFormValidator extends Validator<TParentData, unknown> | undefined = undefined,
   TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>,
 >(props: MentionInputProps<TParentData, TName, TFieldValidator, TFormValidator, TData>) {
+  const overlayZIndex = useOverlayZIndex("dropdown");
   const hydrationTouch = useTouchSurface();
   const {
     defaultValue,
@@ -807,7 +808,7 @@ export function MentionInput<
             top: panel.y ?? 0,
             left: panel.x ?? 0,
             scrollbarWidth: "none" as any,
-            zIndex: zIndex.dropdown,
+            zIndex: overlayZIndex,
             overflow: "auto",
             opacity: panel.visible ? 1 : 0,
             transform: panel.visible ? "scale(1)" : "scale(0.96)",

package/src/fields/Select/index.tsx

@@ -55,7 +55,7 @@ import {
   useViewportGtSm,
 } from "../../FloatingPanel";
 import { PanelPortal } from "../../FloatingPanel/PanelPortal";
-import { zIndex } from "../../shared/zIndex";
+import { useOverlayZIndex } from "../../shared/overlayStack";
 import { useDragScroll } from "../../shared/useDragScroll";
 import { useIsInTableCell } from "../../shared/tableCellContext";
 import { t } from "../../shared/t";
@@ -512,6 +512,7 @@ function FloatingSelectCore({
   selectedOrder,
   dismissible,
 }: FloatingSelectCoreProps) {
+  const overlayZIndex = useOverlayZIndex("dropdown");
   const { style: elevatedSurfaceStyle, ...elevatedSurfaceProps } = knobProps.elevatedSurface;
   const hydrationTouch = useTouchSurface();
   const inTableCell = useIsInTableCell();
@@ -1113,7 +1114,7 @@ function FloatingSelectCore({
                   top: overlayStyle.current?.top ?? panel.y ?? 0,
                   left: panel.x ?? 0,
                   scrollbarWidth: "none" as any,
-                  zIndex: zIndex.dropdown,
+                  zIndex: overlayZIndex,
                   overflow: "auto",
                   ...panel.floatingStyleRef.current,
                   ...(overlayStyle.current ? { maxHeight: overlayStyle.current.maxHeight } : {}),

package/src/index.ts

@@ -416,6 +416,17 @@ export type {
 // ── Z-Index Scale ─────────────────────────────────────────────
 export { zIndex } from "./shared/zIndex";
 export type { ZIndexKey } from "./shared/zIndex";
+export {
+  OverlayStackProvider,
+  overlayStackStep,
+  stackedOverlayZIndex,
+  useOverlayParentZIndex,
+  useOverlayZIndex,
+  withOverlayStack,
+} from "./shared/overlayStack";
+export type { OverlayTier } from "./shared/overlayStack";
+export { OverlayWindow } from "./shared/OverlayWindow";
+export type { OverlayWindowProps } from "./shared/OverlayWindow";
 
 // ── TanStack Form re-exports ─────────────────────────────────
 export {

package/src/shared/OverlayWindow.native.tsx

@@ -0,0 +1,28 @@
+import { StyleSheet, View as RNView } from "react-native";
+import { PortalHost, PortalProvider } from "tamagui";
+import { OverlayStackProvider } from "./overlayStack";
+import type { OverlayWindowProps } from "./OverlayWindow";
+
+export type { OverlayWindowProps } from "./OverlayWindow";
+
+/**
+ * The content of an overlay that is its own native window (a core RN
+ * `Modal`: native SheetModal and FloatingPanel).
+ *
+ * A tamagui Dialog, modal Sheet or Popover opened in here portals to the
+ * `root` host, which tamagui mounts in the app's window, under this one, so
+ * it opened invisibly (FZ-7869). The nearest PortalProvider owns `root`, so
+ * this window gets its own provider and its own `root` host, laid over its
+ * content, and those overlays open inside it. A PortalItem in here aimed at
+ * any other app-level host finds no host, since this provider owns none.
+ */
+export function OverlayWindow({ zIndex, children }: OverlayWindowProps) {
+  return (
+    <PortalProvider shouldAddRootHost={false}>
+      <OverlayStackProvider zIndex={zIndex}>{children}</OverlayStackProvider>
+      <RNView pointerEvents="box-none" style={StyleSheet.absoluteFill} testID="overlay-window-host">
+        <PortalHost name="root" />
+      </RNView>
+    </PortalProvider>
+  );
+}

package/src/shared/OverlayWindow.tsx

@@ -0,0 +1,17 @@
+import type { ReactNode } from "react";
+import { OverlayStackProvider } from "./overlayStack";
+
+export interface OverlayWindowProps {
+  /** The z the window's own overlay binds; nested overlays stack above it. */
+  zIndex: number;
+  children?: ReactNode;
+}
+
+/**
+ * The content of an overlay that is its own native window (a core RN
+ * `Modal`). On web there is no such window: the overlay's subtree just
+ * carries its z for the overlays it opens.
+ */
+export function OverlayWindow({ zIndex, children }: OverlayWindowProps) {
+  return <OverlayStackProvider zIndex={zIndex}>{children}</OverlayStackProvider>;
+}

package/src/shared/overlayStack.spec.tsx

@@ -0,0 +1,59 @@
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { cleanup, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  OverlayStackProvider,
+  overlayStackStep,
+  stackedOverlayZIndex,
+  useOverlayZIndex,
+  type OverlayTier,
+} from "./overlayStack";
+import { zIndex } from "./zIndex";
+
+afterEach(cleanup);
+
+function Probe({ tier, id }: { tier: OverlayTier; id: string }) {
+  return <span data-testid={id}>{useOverlayZIndex(tier)}</span>;
+}
+
+const z = (id: string) => Number(screen.getByTestId(id).textContent);
+
+describe("overlay stack (FZ-7869)", () => {
+  it("steps by the theme's $zIndex $1 token", () => {
+    renderWithProviders(<span />);
+    expect(overlayStackStep()).toBe(100);
+  });
+
+  it("keeps the ladder tier at page level, so a dialog covers any sheet", () => {
+    renderWithProviders(
+      <>
+        <Probe tier="sheet" id="sheet" />
+        <Probe tier="dropdown" id="dialog" />
+      </>,
+    );
+    expect(z("sheet")).toBe(zIndex.sheet);
+    expect(z("dialog")).toBe(zIndex.dropdown);
+    expect(z("dialog")).toBeGreaterThan(z("sheet"));
+  });
+
+  it("puts an overlay opened from another one step above its opener, never below its tier", () => {
+    const step = 100;
+    expect(stackedOverlayZIndex("dropdown", zIndex.sheet, step)).toBe(zIndex.dropdown);
+    expect(stackedOverlayZIndex("dropdown", zIndex.dropdown, step)).toBe(zIndex.dropdown + step);
+    expect(stackedOverlayZIndex("sheet", zIndex.dropdown, step)).toBe(zIndex.dropdown + step);
+    expect(stackedOverlayZIndex("sheet", zIndex.sheet, step)).toBe(zIndex.sheet + step);
+  });
+
+  it("reads the nearest opener through nested providers", () => {
+    renderWithProviders(
+      <OverlayStackProvider zIndex={zIndex.dropdown}>
+        <Probe tier="sheet" id="sheet-in-dialog" />
+        <OverlayStackProvider zIndex={zIndex.dropdown + 100}>
+          <Probe tier="dropdown" id="menu-in-sheet-in-dialog" />
+        </OverlayStackProvider>
+      </OverlayStackProvider>,
+    );
+    expect(z("sheet-in-dialog")).toBe(zIndex.dropdown + 100);
+    expect(z("menu-in-sheet-in-dialog")).toBe(zIndex.dropdown + 200);
+  });
+});

package/src/shared/overlayStack.tsx

@@ -0,0 +1,102 @@
+/**
+ * Overlay stack: an overlay opened from inside another overlay stacks above
+ * its opener (Axiom 14, FZ-7869).
+ *
+ * Every house overlay reads the z of the overlay it was opened from and binds
+ * `max(own tier, parent + one $zIndex step)`, then hands its own z to what it
+ * contains. A top-level overlay keeps its ladder tier (`zIndex.sheet`,
+ * `zIndex.dropdown`), so a dialog still covers any sheet, and a dialog opened
+ * from a dialog, or a sheet from a dialog, lands one step above it.
+ *
+ * Tamagui 2.7.6 cannot do this on its own on native: a modal Sheet teleports
+ * through `Portal` with a stacked zIndex, while `Dialog.Portal` goes through
+ * `PortalItem` to the same root host with none, so a dialog opened in a sheet
+ * mounts under it. Both accept an explicit zIndex (`Dialog.Portal zIndex`,
+ * `Sheet portalProps.zIndex`), which is what the house overlays pass.
+ *
+ * The provider has to sit INSIDE the portaled subtree. The gorhom portal host
+ * renders portaled nodes at the root, under the host's context, not the
+ * opener's, so a provider wrapped around a portal is lost on native.
+ */
+import { createContext, useContext, type ComponentType, type ReactNode } from "react";
+import { getTokenValue } from "tamagui";
+import { zIndex } from "./zIndex";
+
+export type OverlayTier = "sheet" | "dropdown";
+
+const OverlayStackContext = createContext<number | undefined>(undefined);
+
+/** One rung of the theme's `$zIndex` scale: how far an overlay sits above its opener. */
+export function overlayStackStep(): number {
+  let step: unknown;
+  try {
+    step = getTokenValue("$1" as never, "zIndex");
+  } catch {
+    step = undefined;
+  }
+  return typeof step === "number" && step > 0 ? step : 1;
+}
+
+export function stackedOverlayZIndex(
+  tier: OverlayTier,
+  parent: number | undefined,
+  step: number,
+): number {
+  const base = zIndex[tier];
+  return parent === undefined ? base : Math.max(base, parent + step);
+}
+
+/** The z of the overlay this subtree was opened from, or undefined at page level. */
+export function useOverlayParentZIndex(): number | undefined {
+  return useContext(OverlayStackContext);
+}
+
+/** The z an overlay of `tier` binds here: its tier, or one step above the overlay that opened it. */
+export function useOverlayZIndex(tier: OverlayTier): number {
+  return stackedOverlayZIndex(tier, useContext(OverlayStackContext), overlayStackStep());
+}
+
+/** Marks everything inside as opened from an overlay at `zIndex`. */
+export function OverlayStackProvider({
+  zIndex: value,
+  children,
+}: {
+  zIndex: number;
+  children?: ReactNode;
+}) {
+  return <OverlayStackContext.Provider value={value}>{children}</OverlayStackContext.Provider>;
+}
+
+function resolveZIndex(value: unknown): number | undefined {
+  if (typeof value === "number") return value;
+  if (typeof value !== "string") return undefined;
+  const token = getTokenValue(value as never, "zIndex");
+  return typeof token === "number" ? token : undefined;
+}
+
+/**
+ * A portal part that takes `zIndex` (Dialog.Portal, AlertDialog.Portal,
+ * Popover.Content), bound to the stack: it renders at the tier's stacked z
+ * unless the caller passes its own, and its content opens further overlays
+ * above it.
+ */
+export function withOverlayStack<P extends ComponentType<any>>(
+  Part: P,
+  tier: OverlayTier,
+  displayName: string,
+): P {
+  const Raw = Part as ComponentType<any>;
+  function Stacked(props: { zIndex?: unknown; children?: ReactNode }) {
+    const stacked = useOverlayZIndex(tier);
+    const { children, zIndex: own, ...rest } = props;
+    return (
+      <Raw {...rest} zIndex={own ?? stacked}>
+        <OverlayStackProvider zIndex={resolveZIndex(own) ?? stacked}>
+          {children}
+        </OverlayStackProvider>
+      </Raw>
+    );
+  }
+  Stacked.displayName = displayName;
+  return Stacked as unknown as P;
+}

package/types/AdaptivePopup/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/AdaptivePopup/index.tsx"],"names":[],"mappings":"AAEA,OAAO,EAAuB,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAyB5D,MAAM,WAAW,kBAAkB;IACjC,4BAA4B;IAC5B,IAAI,EAAE,OAAO,CAAC;IACd,uCAAuC;IACvC,YAAY,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC;IACtC,gFAAgF;IAChF,OAAO,CAAC,EAAE,SAAS,CAAC;IACpB,gCAAgC;IAChC,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,wCAAwC;IACxC,WAAW,CAAC,EAAE,SAAS,CAAC;IACxB,mBAAmB;IACnB,QAAQ,EAAE,SAAS,CAAC;IACpB;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,YAAY,CAAC;IAChD;;;;;OAKG;IACH,IAAI,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC3B,sDAAsD;IACtD,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,kDAAkD;IAClD,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,qCAAqC;IACrC,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAkBD,MAAM,MAAM,yBAAyB,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEtE;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE;IAC7C,IAAI,CAAC,EAAE,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAClC,IAAI,CAAC,EAAE,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAClC,aAAa,EAAE,MAAM,CAAC;CACvB,GAAG,yBAAyB,CAK5B;AA6ED,wBAAgB,aAAa,CAAC,EAC5B,IAAI,EACJ,YAAY,EACZ,OAAO,EACP,KAAK,EACL,WAAW,EACX,QAAQ,EACR,IAAW,EACX,IAAe,EACf,eAAsB,EACtB,MAAM,EACN,QAAQ,GACT,EAAE,kBAAkB,2CAmRpB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/AdaptivePopup/index.tsx"],"names":[],"mappings":"AAEA,OAAO,EAAuB,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAyB5D,MAAM,WAAW,kBAAkB;IACjC,4BAA4B;IAC5B,IAAI,EAAE,OAAO,CAAC;IACd,uCAAuC;IACvC,YAAY,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC;IACtC,gFAAgF;IAChF,OAAO,CAAC,EAAE,SAAS,CAAC;IACpB,gCAAgC;IAChC,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,wCAAwC;IACxC,WAAW,CAAC,EAAE,SAAS,CAAC;IACxB,mBAAmB;IACnB,QAAQ,EAAE,SAAS,CAAC;IACpB;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,YAAY,CAAC;IAChD;;;;;OAKG;IACH,IAAI,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC3B,sDAAsD;IACtD,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,kDAAkD;IAClD,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,qCAAqC;IACrC,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAoBD,MAAM,MAAM,yBAAyB,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEtE;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE;IAC7C,IAAI,CAAC,EAAE,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAClC,IAAI,CAAC,EAAE,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAClC,aAAa,EAAE,MAAM,CAAC;CACvB,GAAG,yBAAyB,CAK5B;AA6ED,wBAAgB,aAAa,CAAC,EAC5B,IAAI,EACJ,YAAY,EACZ,OAAO,EACP,KAAK,EACL,WAAW,EACX,QAAQ,EACR,IAAW,EACX,IAAe,EACf,eAAsB,EACtB,MAAM,EACN,QAAQ,GACT,EAAE,kBAAkB,2CAqRpB"}