@gfazioli/mantine-window 3.0.0 → 3.1.0

package/dist/types/WindowGroup.context.d.ts

@@ -5,6 +5,18 @@ export type SingleWindowLayout = 'snap-left' | 'snap-right' | 'snap-top' | 'snap
 export type GroupLayout = 'arrange-columns' | 'arrange-rows' | 'tile';
 /** All layout types */
 export type WindowLayout = SingleWindowLayout | GroupLayout;
+/**
+ * Strategy for assigning z-index when a window is brought to front.
+ *
+ * - `'increment'` (legacy): monotonically increase a counter. Simple and preserves
+ *   history of activation order across mounts, but the counter can grow unbounded
+ *   and eventually exceed modal/menu z-indexes. A `maxZIndex` cap is recommended
+ *   when using this strategy.
+ * - `'normalize'`: derive z-indexes from an ordered stack of window ids. The
+ *   active window always gets the highest z-index and values stay compact
+ *   (`initialZIndex .. initialZIndex + N - 1`). Recommended for long-running apps.
+ */
+export type ZIndexStrategy = 'increment' | 'normalize';
 export interface WindowGroupWindowState {
     id: string;
     x: number;
@@ -50,6 +62,8 @@ export interface WindowGroupContextValue {
     expandAll: () => void;
     /** Get all registered window IDs */
     getWindowIds: () => string[];
+    /** Current stacking order (bottom to top). Read-only snapshot exposed for introspection. */
+    stackOrder: string[];
     /** Whether the tools button should be shown (true when inside a group) */
     showToolsButton: boolean;
 }

package/dist/types/WindowGroup.d.ts

@@ -1,6 +1,6 @@
 import React from 'react';
 import { Factory, type BoxProps } from '@mantine/core';
-import { type WindowGroupContextValue, type WindowLayout } from './WindowGroup.context';
+import { type WindowGroupContextValue, type WindowLayout, type ZIndexStrategy } from './WindowGroup.context';
 export interface WindowGroupProps extends BoxProps {
     /** Unique group identifier */
     id?: string;
@@ -10,6 +10,28 @@ export interface WindowGroupProps extends BoxProps {
     showToolsButton?: boolean;
     /** Initial layout to apply after windows have registered. Applied once on mount. */
     defaultLayout?: WindowLayout;
+    /**
+     * Starting z-index for the stacking context of this group. Defaults to 200 when
+     * `withinPortal` is true, 1 otherwise — matching the previous hardcoded values.
+     */
+    initialZIndex?: number;
+    /**
+     * Upper bound for z-index values. When the `'increment'` strategy would exceed this
+     * value, the counter wraps back to `initialZIndex`. Ignored when `'normalize'` is in
+     * use, since z-indexes are derived directly from the stacking order and already stay
+     * compact. Recommended when the group coexists with Mantine modals/menus.
+     */
+    maxZIndex?: number;
+    /**
+     * How z-indexes are assigned when a window is focused or registered.
+     *
+     * - `'increment'` (default): a counter monotonically increases. Preserves legacy
+     *   behavior. Can exceed modal z-indexes unless `maxZIndex` is set.
+     * - `'normalize'`: z-indexes are derived from the stacking order. Values always
+     *   stay within `initialZIndex .. initialZIndex + N - 1`. Recommended for
+     *   long-running applications or when Mantine modals/menus are used alongside.
+     */
+    zIndexStrategy?: ZIndexStrategy;
     /** Ref to access group API imperatively (applyLayout, closeAll, etc.) */
     groupRef?: React.Ref<WindowGroupContextValue>;
     /** Called when a layout is applied */

package/dist/types/hooks/use-window-state.d.ts

@@ -1,4 +1,6 @@
 import type { WindowPosition, WindowSize } from '../Window';
+/** @internal — test-only reset helper so counters don't leak across tests */
+export declare function __resetStandaloneZIndexCounters(): void;
 export interface UseWindowStateOptions {
     id?: string;
     title?: string;
@@ -14,6 +16,8 @@ export interface UseWindowStateOptions {
     defaultY?: number | string;
     defaultWidth?: number | string;
     defaultHeight?: number | string;
+    initialZIndex?: number;
+    maxZIndex?: number;
     onClose?: () => void;
     onPositionChange?: (position: {
         x: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gfazioli/mantine-window",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "A Mantine extension component that renders draggable, resizable floating windows with persistent state, customizable boundaries, collapsible content, z-index management, and flexible control over position, size, and interaction modes. Includes a WindowGroup compound component for coordinated multi-window management with layout presets.",
   "homepage": "https://gfazioli.github.io/mantine-window/",
   "packageManager": "yarn@4.0.1",