@xsolla/xui-core 0.185.5 → 0.186.0

package/index.d.mts

@@ -8132,6 +8132,7 @@ declare const themeConfig: (mode?: ThemeMode, productContext?: ProductContext) =
             maxWidth: number;
             overlayColor: string;
             portalPadding: number;
+            /** @deprecated Layering is contextual now; see OVERLAY_LAYER_BASE / useOverlayLayer. */
             zIndex: number;
         };
         drawer: () => {
@@ -8154,6 +8155,7 @@ declare const themeConfig: (mode?: ThemeMode, productContext?: ProductContext) =
             stepperContentGap: number;
             scrimColor: string;
             animationDuration: number;
+            /** @deprecated Layering is contextual now; see MODAL_LAYER_STEP / useOverlayLayer. */
             zIndex: number;
         };
         sidebar: () => {
@@ -8177,6 +8179,7 @@ declare const themeConfig: (mode?: ThemeMode, productContext?: ProductContext) =
             popoverMinWidth: number;
             popoverMaxWidth: number;
             popoverShadow: string;
+            /** @deprecated Layering is contextual now; see useOverlayLayer / LAYER_OFFSET. */
             popoverZIndex: number;
             transitionWidth: string;
             transitionFadeIn: string;
@@ -8407,5 +8410,72 @@ declare const ModalIdContext: React.Context<string | null>;
  * Returns null if not inside a modal.
  */
 declare const useModalId: () => string | null;
+/**
+ * Shared layering contract for every overlay primitive (modal, drawer,
+ * dropdown, select, context-menu, status-dropdown, tooltip, toggletip, …).
+ *
+ * The problem this solves: each overlay used to hardcode its own z-index and
+ * portal to `document.body`, so a transient overlay (tooltip at 2000) could
+ * render on top of a modal (1000) that opened over it, while an overlay opened
+ * *inside* a modal had no reliable way to sit above it. A single global scale
+ * cannot satisfy both — so layering is **contextual**.
+ *
+ * How it works:
+ *  - Overlays compute their z-index as `useOverlayLayer() + LAYER_OFFSET.<band>`.
+ *  - The default (root) base is {@link OVERLAY_LAYER_BASE}; stray overlays sit
+ *    just above app chrome but below any modal.
+ *  - A modal/drawer raises the base by {@link MODAL_LAYER_STEP} for its whole
+ *    subtree via {@link OverlayLayerProvider}. React context flows through
+ *    portals, so a tooltip declared inside a modal reads the raised base even
+ *    though it portals to `document.body`, and therefore renders above the modal
+ *    — while a tooltip opened elsewhere keeps the low base and is covered by it.
+ *
+ * Resulting order (low → high): app content < popover/menu/tooltip (stray) <
+ * modal/drawer < popover/menu/tooltip (in-modal) < … < toasts.
+ */
+declare const OVERLAY_LAYER_BASE = 1000;
+/**
+ * Rank of each overlay kind *within a single layer* (a stray context, or one
+ * modal's subtree). Values are small relative to {@link MODAL_LAYER_STEP} so a
+ * modal always clears every transient overlay of the layer beneath it.
+ *
+ * `popover` (dropdown/select) sits above `menu` (context-menu) — matching the
+ * intended order and keeping a Select opened inside a ContextMenu above it.
+ * `tooltip` is highest so it annotates whatever is currently on top.
+ */
+declare const LAYER_OFFSET: {
+    /** Trigger-anchored value lists: dropdown, select, multi-select, autocomplete. */
+    readonly popover: 200;
+    /** context-menu and its consumers (status-dropdown). */
+    readonly menu: 100;
+    /** tooltip, toggletip. */
+    readonly tooltip: 300;
+};
+/**
+ * Amount a modal/drawer raises the layer base for everything in its subtree.
+ * Must exceed every {@link LAYER_OFFSET} so a modal covers stray transients yet
+ * stays below overlays opened within it.
+ */
+declare const MODAL_LAYER_STEP = 1000;
+/**
+ * Fixed, non-contextual top-most layer for toasts / notifications — always above
+ * modals regardless of nesting depth.
+ */
+declare const TOAST_LAYER = 9999;
+/**
+ * Raises the overlay layer base for a subtree. Applied by modal/drawer roots so
+ * overlays opened within them stack above them. Consumers rarely need this
+ * directly.
+ */
+declare const OverlayLayerProvider: React.Provider<number>;
+/**
+ * Returns the current overlay layer base. Add a {@link LAYER_OFFSET} band to get
+ * an overlay's z-index, e.g. `useOverlayLayer() + LAYER_OFFSET.tooltip`.
+ */
+declare const useOverlayLayer: () => number;
+/** Publishes the open-modal count. Applied by `ModalProvider`. */
+declare const ModalStackProvider: React.Provider<number>;
+/** Returns the number of currently-open modals. */
+declare const useModalStackDepth: () => number;
 
-export { type BreakpointKey, type ComponentSize, DISPLAY_SCALE_STEPS, type DesignSystemContextType, type DisplayScaleStep, FontLoader, MOBILE_MAX_WIDTH, ModalIdContext, type ProductContext, type ResponsiveValue, SCALE_STEPS, type ScaleStep, type Theme, type ThemeColorScheme, type ThemeColors, type ThemeFonts, type ThemeMode, type ThemeOverrideProps, type ThemeShadow, type ThemeShape, type ThemeSizing, type ThemeSpacing, type ThemeTypographyRoles, type TypographyBodyVariant, TypographyStyleLoader, type TypographyTokens, type TypographyVariant, XUIProvider, breakpoints, colors, cssVar, defaultProductContext, fontFacesCSS, fontSize, fonts, generateTypographyCSS, getFonts, getTypographyTokens, getTypographyVariant, isAndroid, isIOS, isNative, isWeb, lineHeightCompact, lineHeightDisplay, lineHeightText, radius, radiusScale, responsiveTypographyScale, shadow, shape, spacing, stroke, themeConfig, typography, typographyTokens, useDesignSystem, useId, useModalId, useResolvedTheme };
+export { type BreakpointKey, type ComponentSize, DISPLAY_SCALE_STEPS, type DesignSystemContextType, type DisplayScaleStep, FontLoader, LAYER_OFFSET, MOBILE_MAX_WIDTH, MODAL_LAYER_STEP, ModalIdContext, ModalStackProvider, OVERLAY_LAYER_BASE, OverlayLayerProvider, type ProductContext, type ResponsiveValue, SCALE_STEPS, type ScaleStep, TOAST_LAYER, type Theme, type ThemeColorScheme, type ThemeColors, type ThemeFonts, type ThemeMode, type ThemeOverrideProps, type ThemeShadow, type ThemeShape, type ThemeSizing, type ThemeSpacing, type ThemeTypographyRoles, type TypographyBodyVariant, TypographyStyleLoader, type TypographyTokens, type TypographyVariant, XUIProvider, breakpoints, colors, cssVar, defaultProductContext, fontFacesCSS, fontSize, fonts, generateTypographyCSS, getFonts, getTypographyTokens, getTypographyVariant, isAndroid, isIOS, isNative, isWeb, lineHeightCompact, lineHeightDisplay, lineHeightText, radius, radiusScale, responsiveTypographyScale, shadow, shape, spacing, stroke, themeConfig, typography, typographyTokens, useDesignSystem, useId, useModalId, useModalStackDepth, useOverlayLayer, useResolvedTheme };

package/index.d.ts

@@ -8132,6 +8132,7 @@ declare const themeConfig: (mode?: ThemeMode, productContext?: ProductContext) =
             maxWidth: number;
             overlayColor: string;
             portalPadding: number;
+            /** @deprecated Layering is contextual now; see OVERLAY_LAYER_BASE / useOverlayLayer. */
             zIndex: number;
         };
         drawer: () => {
@@ -8154,6 +8155,7 @@ declare const themeConfig: (mode?: ThemeMode, productContext?: ProductContext) =
             stepperContentGap: number;
             scrimColor: string;
             animationDuration: number;
+            /** @deprecated Layering is contextual now; see MODAL_LAYER_STEP / useOverlayLayer. */
             zIndex: number;
         };
         sidebar: () => {
@@ -8177,6 +8179,7 @@ declare const themeConfig: (mode?: ThemeMode, productContext?: ProductContext) =
             popoverMinWidth: number;
             popoverMaxWidth: number;
             popoverShadow: string;
+            /** @deprecated Layering is contextual now; see useOverlayLayer / LAYER_OFFSET. */
             popoverZIndex: number;
             transitionWidth: string;
             transitionFadeIn: string;
@@ -8407,5 +8410,72 @@ declare const ModalIdContext: React.Context<string | null>;
  * Returns null if not inside a modal.
  */
 declare const useModalId: () => string | null;
+/**
+ * Shared layering contract for every overlay primitive (modal, drawer,
+ * dropdown, select, context-menu, status-dropdown, tooltip, toggletip, …).
+ *
+ * The problem this solves: each overlay used to hardcode its own z-index and
+ * portal to `document.body`, so a transient overlay (tooltip at 2000) could
+ * render on top of a modal (1000) that opened over it, while an overlay opened
+ * *inside* a modal had no reliable way to sit above it. A single global scale
+ * cannot satisfy both — so layering is **contextual**.
+ *
+ * How it works:
+ *  - Overlays compute their z-index as `useOverlayLayer() + LAYER_OFFSET.<band>`.
+ *  - The default (root) base is {@link OVERLAY_LAYER_BASE}; stray overlays sit
+ *    just above app chrome but below any modal.
+ *  - A modal/drawer raises the base by {@link MODAL_LAYER_STEP} for its whole
+ *    subtree via {@link OverlayLayerProvider}. React context flows through
+ *    portals, so a tooltip declared inside a modal reads the raised base even
+ *    though it portals to `document.body`, and therefore renders above the modal
+ *    — while a tooltip opened elsewhere keeps the low base and is covered by it.
+ *
+ * Resulting order (low → high): app content < popover/menu/tooltip (stray) <
+ * modal/drawer < popover/menu/tooltip (in-modal) < … < toasts.
+ */
+declare const OVERLAY_LAYER_BASE = 1000;
+/**
+ * Rank of each overlay kind *within a single layer* (a stray context, or one
+ * modal's subtree). Values are small relative to {@link MODAL_LAYER_STEP} so a
+ * modal always clears every transient overlay of the layer beneath it.
+ *
+ * `popover` (dropdown/select) sits above `menu` (context-menu) — matching the
+ * intended order and keeping a Select opened inside a ContextMenu above it.
+ * `tooltip` is highest so it annotates whatever is currently on top.
+ */
+declare const LAYER_OFFSET: {
+    /** Trigger-anchored value lists: dropdown, select, multi-select, autocomplete. */
+    readonly popover: 200;
+    /** context-menu and its consumers (status-dropdown). */
+    readonly menu: 100;
+    /** tooltip, toggletip. */
+    readonly tooltip: 300;
+};
+/**
+ * Amount a modal/drawer raises the layer base for everything in its subtree.
+ * Must exceed every {@link LAYER_OFFSET} so a modal covers stray transients yet
+ * stays below overlays opened within it.
+ */
+declare const MODAL_LAYER_STEP = 1000;
+/**
+ * Fixed, non-contextual top-most layer for toasts / notifications — always above
+ * modals regardless of nesting depth.
+ */
+declare const TOAST_LAYER = 9999;
+/**
+ * Raises the overlay layer base for a subtree. Applied by modal/drawer roots so
+ * overlays opened within them stack above them. Consumers rarely need this
+ * directly.
+ */
+declare const OverlayLayerProvider: React.Provider<number>;
+/**
+ * Returns the current overlay layer base. Add a {@link LAYER_OFFSET} band to get
+ * an overlay's z-index, e.g. `useOverlayLayer() + LAYER_OFFSET.tooltip`.
+ */
+declare const useOverlayLayer: () => number;
+/** Publishes the open-modal count. Applied by `ModalProvider`. */
+declare const ModalStackProvider: React.Provider<number>;
+/** Returns the number of currently-open modals. */
+declare const useModalStackDepth: () => number;
 
-export { type BreakpointKey, type ComponentSize, DISPLAY_SCALE_STEPS, type DesignSystemContextType, type DisplayScaleStep, FontLoader, MOBILE_MAX_WIDTH, ModalIdContext, type ProductContext, type ResponsiveValue, SCALE_STEPS, type ScaleStep, type Theme, type ThemeColorScheme, type ThemeColors, type ThemeFonts, type ThemeMode, type ThemeOverrideProps, type ThemeShadow, type ThemeShape, type ThemeSizing, type ThemeSpacing, type ThemeTypographyRoles, type TypographyBodyVariant, TypographyStyleLoader, type TypographyTokens, type TypographyVariant, XUIProvider, breakpoints, colors, cssVar, defaultProductContext, fontFacesCSS, fontSize, fonts, generateTypographyCSS, getFonts, getTypographyTokens, getTypographyVariant, isAndroid, isIOS, isNative, isWeb, lineHeightCompact, lineHeightDisplay, lineHeightText, radius, radiusScale, responsiveTypographyScale, shadow, shape, spacing, stroke, themeConfig, typography, typographyTokens, useDesignSystem, useId, useModalId, useResolvedTheme };
+export { type BreakpointKey, type ComponentSize, DISPLAY_SCALE_STEPS, type DesignSystemContextType, type DisplayScaleStep, FontLoader, LAYER_OFFSET, MOBILE_MAX_WIDTH, MODAL_LAYER_STEP, ModalIdContext, ModalStackProvider, OVERLAY_LAYER_BASE, OverlayLayerProvider, type ProductContext, type ResponsiveValue, SCALE_STEPS, type ScaleStep, TOAST_LAYER, type Theme, type ThemeColorScheme, type ThemeColors, type ThemeFonts, type ThemeMode, type ThemeOverrideProps, type ThemeShadow, type ThemeShape, type ThemeSizing, type ThemeSpacing, type ThemeTypographyRoles, type TypographyBodyVariant, TypographyStyleLoader, type TypographyTokens, type TypographyVariant, XUIProvider, breakpoints, colors, cssVar, defaultProductContext, fontFacesCSS, fontSize, fonts, generateTypographyCSS, getFonts, getTypographyTokens, getTypographyVariant, isAndroid, isIOS, isNative, isWeb, lineHeightCompact, lineHeightDisplay, lineHeightText, radius, radiusScale, responsiveTypographyScale, shadow, shape, spacing, stroke, themeConfig, typography, typographyTokens, useDesignSystem, useId, useModalId, useModalStackDepth, useOverlayLayer, useResolvedTheme };

package/index.js

@@ -32,9 +32,15 @@ var index_exports = {};
 __export(index_exports, {
   DISPLAY_SCALE_STEPS: () => DISPLAY_SCALE_STEPS,
   FontLoader: () => FontLoader,
+  LAYER_OFFSET: () => LAYER_OFFSET,
   MOBILE_MAX_WIDTH: () => MOBILE_MAX_WIDTH,
+  MODAL_LAYER_STEP: () => MODAL_LAYER_STEP,
   ModalIdContext: () => ModalIdContext,
+  ModalStackProvider: () => ModalStackProvider,
+  OVERLAY_LAYER_BASE: () => OVERLAY_LAYER_BASE,
+  OverlayLayerProvider: () => OverlayLayerProvider,
   SCALE_STEPS: () => SCALE_STEPS,
+  TOAST_LAYER: () => TOAST_LAYER,
   TypographyStyleLoader: () => TypographyStyleLoader,
   XUIProvider: () => XUIProvider,
   breakpoints: () => breakpoints,
@@ -68,6 +74,8 @@ __export(index_exports, {
   useDesignSystem: () => useDesignSystem,
   useId: () => useId,
   useModalId: () => useModalId,
+  useModalStackDepth: () => useModalStackDepth,
+  useOverlayLayer: () => useOverlayLayer,
   useResolvedTheme: () => useResolvedTheme
 });
 module.exports = __toCommonJS(index_exports);
@@ -4651,6 +4659,7 @@ var themeConfig = (mode = "dark", productContext = defaultProductContext) => {
           maxWidth: 680,
           overlayColor: "rgba(0, 0, 0, 0.75)",
           portalPadding: 20,
+          /** @deprecated Layering is contextual now; see OVERLAY_LAYER_BASE / useOverlayLayer. */
           zIndex: 1e3
         };
       },
@@ -4675,6 +4684,7 @@ var themeConfig = (mode = "dark", productContext = defaultProductContext) => {
         stepperContentGap: 8,
         scrimColor: "rgba(0, 0, 0, 0.75)",
         animationDuration: 300,
+        /** @deprecated Layering is contextual now; see MODAL_LAYER_STEP / useOverlayLayer. */
         zIndex: 1e3
       }),
       sidebar: () => ({
@@ -4701,6 +4711,7 @@ var themeConfig = (mode = "dark", productContext = defaultProductContext) => {
         popoverMinWidth: 180,
         popoverMaxWidth: 240,
         popoverShadow: "0 2px 25px rgba(7, 7, 8, 0.15)",
+        /** @deprecated Layering is contextual now; see useOverlayLayer / LAYER_OFFSET. */
         popoverZIndex: 1e3,
         transitionWidth: "0.25s ease-in-out",
         transitionFadeIn: "opacity 0.15s ease-in-out 0.1s",
@@ -4952,13 +4963,36 @@ var useIdFallback = () => {
 var useId = hasReactUseId ? import_react3.default.useId : useIdFallback;
 var ModalIdContext = (0, import_react3.createContext)(null);
 var useModalId = () => (0, import_react3.useContext)(ModalIdContext);
+var OVERLAY_LAYER_BASE = 1e3;
+var LAYER_OFFSET = {
+  /** Trigger-anchored value lists: dropdown, select, multi-select, autocomplete. */
+  popover: 200,
+  /** context-menu and its consumers (status-dropdown). */
+  menu: 100,
+  /** tooltip, toggletip. */
+  tooltip: 300
+};
+var MODAL_LAYER_STEP = 1e3;
+var TOAST_LAYER = 9999;
+var OverlayLayerContext = (0, import_react3.createContext)(OVERLAY_LAYER_BASE);
+var OverlayLayerProvider = OverlayLayerContext.Provider;
+var useOverlayLayer = () => (0, import_react3.useContext)(OverlayLayerContext);
+var ModalStackContext = (0, import_react3.createContext)(0);
+var ModalStackProvider = ModalStackContext.Provider;
+var useModalStackDepth = () => (0, import_react3.useContext)(ModalStackContext);
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   DISPLAY_SCALE_STEPS,
   FontLoader,
+  LAYER_OFFSET,
   MOBILE_MAX_WIDTH,
+  MODAL_LAYER_STEP,
   ModalIdContext,
+  ModalStackProvider,
+  OVERLAY_LAYER_BASE,
+  OverlayLayerProvider,
   SCALE_STEPS,
+  TOAST_LAYER,
   TypographyStyleLoader,
   XUIProvider,
   breakpoints,
@@ -4992,6 +5026,8 @@ var useModalId = () => (0, import_react3.useContext)(ModalIdContext);
   useDesignSystem,
   useId,
   useModalId,
+  useModalStackDepth,
+  useOverlayLayer,
   useResolvedTheme
 });
 //# sourceMappingURL=index.js.map