@uxf/ui 11.100.1 → 11.102.0

package/modal/README.md

@@ -10,13 +10,13 @@
 
 ```tsx
 import {AppProps} from "next/app";
-import {getModalRef, ModalProvider} from "@uxf/ui/modal";
+import {getModalStackRef, ModalProvider} from "@uxf/ui/modal";
 
 function App(props: AppProps) {
     return (
         <UiContextProvider value={...}>
             {props.children}
-            <ModalProvider ref={getModalRef()}/>
+            <ModalProvider ref={getModalStackRef()}/>
         </UiContextProvider>
     );
 }
@@ -39,9 +39,6 @@ function Component(props: AppProps) {
         </div>
     );
 }
-
-
-
 ```
 
 ## Implementation Modal
@@ -49,7 +46,7 @@ function Component(props: AppProps) {
 ```tsx
 function Component(props: AppProps) {
     const [isOpen, setIsOpen] = useState(false);
-    
+
     return (
         <div>
             <Button onClick={() => setIsOpen(true)}>Click to open modal</Button>
@@ -59,4 +56,187 @@ function Component(props: AppProps) {
         </div>
     );
 }
-```
+```
+
+## Layered Modals
+
+The modal system supports opening multiple modals simultaneously in different layers. Each layer has its own z-index and stacking order.
+
+### Default Layer Configuration
+
+By default, four layers are available:
+
+```typescript
+{
+  layers: {
+    main: { name: "main", zIndex: 1000 },
+    confirmation: { name: "confirmation", zIndex: 1010 },
+    alert: { name: "alert", zIndex: 1020 },
+    critical: { name: "critical", zIndex: 1030 },
+  },
+  defaultLayer: "main"
+}
+```
+
+### Basic Usage with Layers
+
+```tsx
+import { openModal, closeModal, closeAllModals, closeModalsByLayer } from "@uxf/ui/modal";
+
+// Open modal in default "main" layer
+openModal({
+    children: <DialogPanel>Main content</DialogPanel>
+});
+
+// Open modal in specific layer (fully type-safe!)
+openModal({
+    children: <DialogPanel>Confirmation dialog</DialogPanel>
+}, {
+    layer: "confirmation" // TypeScript autocompletes: "main" | "confirmation" | "alert" | "critical"
+});
+
+// Close topmost modal
+closeModal();
+
+// Close modal in specific layer
+closeModal("confirmation");
+
+// Close all modals in a layer
+closeModalsByLayer("alert");
+
+// Close all modals across all layers
+closeAllModals();
+```
+
+### Stacking Behavior
+
+- Modals with higher z-index appear on top of modals with lower z-index
+- Only the topmost modal (highest z-index) responds to backdrop clicks and ESC key
+- Clicking inside a higher-layer modal will NOT close lower-layer modals
+- Each layer can have one modal by default (use `replace: false` option to allow multiple)
+
+## Custom Layer Configuration
+
+You can configure custom layers for your project using `ModalLayerConfigProvider`:
+
+```tsx
+import {
+    ModalProvider,
+    ModalLayerConfigProvider,
+    getModalStackRef,
+    ModalLayersConfiguration
+} from "@uxf/ui/modal";
+
+// Define custom layers
+const customModalLayers: ModalLayersConfiguration = {
+    layers: {
+        base: { name: "base", zIndex: 1000 },
+        form: { name: "form", zIndex: 1100 },
+        tooltip: { name: "tooltip", zIndex: 1200 },
+        notification: { name: "notification", zIndex: 9000 },
+    },
+    defaultLayer: "base"
+};
+
+// Wrap your app with the config provider
+function App({ children }: { children: React.ReactNode }) {
+    return (
+        <ModalLayerConfigProvider config={customModalLayers}>
+            <ModalProvider ref={getModalStackRef()} />
+            {children}
+        </ModalLayerConfigProvider>
+    );
+}
+
+// Use your custom layers
+function MyComponent() {
+    return (
+        <Button onClick={() =>
+            openModal({
+                children: <DialogPanel>Form modal</DialogPanel>
+            }, {
+                layer: "form"
+            })
+        }>
+            Open Form
+        </Button>
+    );
+}
+```
+
+### Custom Configuration Guidelines
+
+- **name**: Unique identifier for the layer
+- **zIndex**: CSS z-index value (higher = on top). This determines both the visual stacking and logical order.
+- **defaultLayer**: Layer name to use when no layer is specified
+
+### TypeScript Support - Custom Layer Names
+
+You can extend the available layer names using TypeScript declaration merging:
+
+**Step 1: Extend the interface**
+
+```typescript
+// types/modal.d.ts (in your project)
+import "@uxf/ui/modal";
+
+declare module "@uxf/ui/modal" {
+    interface ModalLayers {
+        // Add your custom layer names
+        base: true;
+        form: true;
+        notification: true;
+        tooltip: true;
+    }
+}
+```
+
+**Step 2: Configure layers at runtime**
+
+```tsx
+// app/layout.tsx or _app.tsx
+import { ModalLayerConfigProvider, ModalProvider, getModalStackRef } from "@uxf/ui/modal";
+
+const customModalLayers = {
+    layers: {
+        // Default layers (keep or override)
+        main: { name: "main", zIndex: 1000 },
+        confirmation: { name: "confirmation", zIndex: 1010 },
+        alert: { name: "alert", zIndex: 1020 },
+        critical: { name: "critical", zIndex: 1030 },
+        // Your custom layers
+        base: { name: "base", zIndex: 900 },
+        form: { name: "form", zIndex: 1100 },
+        notification: { name: "notification", zIndex: 9000 },
+        tooltip: { name: "tooltip", zIndex: 9999 },
+    },
+    defaultLayer: "main"
+};
+
+<ModalLayerConfigProvider config={customModalLayers}>
+    <ModalProvider ref={getModalStackRef()} />
+    <App />
+</ModalLayerConfigProvider>
+```
+
+**Step 3: Use with full type safety**
+
+```tsx
+import { openModal } from "@uxf/ui/modal";
+
+openModal({
+    children: <DialogPanel>Form content</DialogPanel>
+}, {
+    layer: "form" // ✅ TypeScript autocompletes and validates!
+    // Available: "main" | "confirmation" | "alert" | "critical" | "base" | "form" | "notification" | "tooltip"
+});
+```
+
+## Backwards Compatibility
+
+The layered modal system is fully backwards compatible:
+
+- Existing code using `openModal()` without options continues to work
+- `getModalRef()` is aliased to `getModalStackRef()`
+- Default "main" layer is used when no layer is specified
+- Single modal behavior is maintained when only one modal is open

package/modal/constants.d.ts

@@ -0,0 +1,2 @@
+import type { ModalLayersConfiguration } from "./types";
+export declare const DEFAULT_MODAL_LAYERS: ModalLayersConfiguration;

package/modal/constants.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_MODAL_LAYERS = void 0;
+const tw_z_index_1 = require("../tw-tokens/tw-z-index");
+exports.DEFAULT_MODAL_LAYERS = {
+    layers: {
+        main: { name: "main", zIndex: parseInt(tw_z_index_1.twZIndex.modal, 10) },
+        confirm: { name: "confirm", zIndex: parseInt(tw_z_index_1.twZIndex.confirm, 10) },
+    },
+    defaultLayer: "main",
+};

package/modal/index.d.ts

@@ -1,4 +1,8 @@
+export { DEFAULT_MODAL_LAYERS } from "./constants";
 export { Modal } from "./modal";
+export { ModalLayerConfigProvider, useModalLayerConfig } from "./modal-layer-config";
 export { ModalProvider } from "./modal-provider";
-export { closeModal, getModalRef, openModal } from "./modal-service";
-export type { ModalProps, ModalProviderProps, ModalRef, ModalVariant } from "./types";
+export { closeAllModals, closeModal, closeModalsByLayer, getModalStackRef, openModal } from "./modal-service";
+export type { ModalInstance, ModalLayerConfig, ModalLayerName, ModalLayersConfiguration, ModalProps, ModalProviderProps, ModalRef, ModalStackRef, ModalVariant, OpenModalOptions, } from "./types";
+/** @deprecated use getModalStackRef */
+export { getModalStackRef as getModalRef } from "./modal-service";

package/modal/index.js

@@ -1,11 +1,22 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.openModal = exports.getModalRef = exports.closeModal = exports.ModalProvider = exports.Modal = void 0;
+exports.getModalRef = exports.openModal = exports.getModalStackRef = exports.closeModalsByLayer = exports.closeModal = exports.closeAllModals = exports.ModalProvider = exports.useModalLayerConfig = exports.ModalLayerConfigProvider = exports.Modal = exports.DEFAULT_MODAL_LAYERS = void 0;
+var constants_1 = require("./constants");
+Object.defineProperty(exports, "DEFAULT_MODAL_LAYERS", { enumerable: true, get: function () { return constants_1.DEFAULT_MODAL_LAYERS; } });
 var modal_1 = require("./modal");
 Object.defineProperty(exports, "Modal", { enumerable: true, get: function () { return modal_1.Modal; } });
+var modal_layer_config_1 = require("./modal-layer-config");
+Object.defineProperty(exports, "ModalLayerConfigProvider", { enumerable: true, get: function () { return modal_layer_config_1.ModalLayerConfigProvider; } });
+Object.defineProperty(exports, "useModalLayerConfig", { enumerable: true, get: function () { return modal_layer_config_1.useModalLayerConfig; } });
 var modal_provider_1 = require("./modal-provider");
 Object.defineProperty(exports, "ModalProvider", { enumerable: true, get: function () { return modal_provider_1.ModalProvider; } });
 var modal_service_1 = require("./modal-service");
+Object.defineProperty(exports, "closeAllModals", { enumerable: true, get: function () { return modal_service_1.closeAllModals; } });
 Object.defineProperty(exports, "closeModal", { enumerable: true, get: function () { return modal_service_1.closeModal; } });
-Object.defineProperty(exports, "getModalRef", { enumerable: true, get: function () { return modal_service_1.getModalRef; } });
+Object.defineProperty(exports, "closeModalsByLayer", { enumerable: true, get: function () { return modal_service_1.closeModalsByLayer; } });
+Object.defineProperty(exports, "getModalStackRef", { enumerable: true, get: function () { return modal_service_1.getModalStackRef; } });
 Object.defineProperty(exports, "openModal", { enumerable: true, get: function () { return modal_service_1.openModal; } });
+// Backwards compatibility: getModalRef is now an alias for getModalStackRef
+/** @deprecated use getModalStackRef */
+var modal_service_2 = require("./modal-service");
+Object.defineProperty(exports, "getModalRef", { enumerable: true, get: function () { return modal_service_2.getModalStackRef; } });

package/modal/modal-layer-config.d.ts

@@ -0,0 +1,12 @@
+import React, { ReactNode } from "react";
+import { ModalLayersConfiguration } from "./types";
+interface ModalLayerConfigContextValue {
+    config: ModalLayersConfiguration;
+}
+export interface ModalLayerConfigProviderProps {
+    children: ReactNode;
+    config?: ModalLayersConfiguration;
+}
+export declare function ModalLayerConfigProvider(props: ModalLayerConfigProviderProps): React.JSX.Element;
+export declare function useModalLayerConfig(): ModalLayerConfigContextValue;
+export {};

package/modal/modal-layer-config.js

@@ -0,0 +1,60 @@
+"use strict";
+"use client";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ModalLayerConfigProvider = ModalLayerConfigProvider;
+exports.useModalLayerConfig = useModalLayerConfig;
+const react_1 = __importStar(require("react"));
+const constants_1 = require("./constants");
+const ModalLayerConfigContext = (0, react_1.createContext)({
+    config: constants_1.DEFAULT_MODAL_LAYERS,
+});
+function ModalLayerConfigProvider(props) {
+    const value = (0, react_1.useMemo)(() => {
+        var _a;
+        return ({
+            config: (_a = props.config) !== null && _a !== void 0 ? _a : constants_1.DEFAULT_MODAL_LAYERS,
+        });
+    }, [props.config]);
+    return react_1.default.createElement(ModalLayerConfigContext.Provider, { value: value }, props.children);
+}
+function useModalLayerConfig() {
+    const context = (0, react_1.useContext)(ModalLayerConfigContext);
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    if (!context) {
+        return { config: constants_1.DEFAULT_MODAL_LAYERS };
+    }
+    return context;
+}

package/modal/modal-provider.d.ts

@@ -1,3 +1,3 @@
 import React from "react";
-import { ModalRef } from "./types";
-export declare const ModalProvider: React.ForwardRefExoticComponent<React.RefAttributes<ModalRef>>;
+import { ModalStackRef } from "./types";
+export declare const ModalProvider: React.ForwardRefExoticComponent<React.RefAttributes<ModalStackRef>>;

package/modal/modal-provider.js

@@ -35,34 +35,76 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ModalProvider = void 0;
+const is_empty_1 = require("@uxf/core/utils/is-empty");
 const react_1 = __importStar(require("react"));
-const dialog_1 = require("../dialog/dialog");
+const modal_1 = require("./modal");
+const modal_layer_config_1 = require("./modal-layer-config");
+let modalIdCounter = 0;
+function generateModalId() {
+    return `modal-${++modalIdCounter}-${Date.now()}`;
+}
+function ModalDialogRenderer(props) {
+    var _a;
+    const onClose = props.onClose;
+    const onCloseInstance = props.instance.props.onClose;
+    const handleClose = (0, react_1.useCallback)(() => {
+        onCloseInstance === null || onCloseInstance === void 0 ? void 0 : onCloseInstance();
+        onClose();
+    }, [onCloseInstance, onClose]);
+    // Only the topmost modal can be closed by backdrop/escape
+    // This prevents clicking inside a top modal from closing modals underneath
+    const isBackdropCloseDisabled = !props.isTopmost || props.instance.props.isBackdropCloseDisabled;
+    const isEscKeyCloseDisabled = !props.isTopmost || props.instance.props.isEscapeKeyCloseDisabled;
+    return (react_1.default.createElement(modal_1.Modal, { className: `uxf-modal--layer-${props.instance.layer} ${(_a = props.instance.props.className) !== null && _a !== void 0 ? _a : ""}`, isBackdropCloseDisabled: isBackdropCloseDisabled, isEscKeyCloseDisabled: isEscKeyCloseDisabled, isOpen: true, onClose: handleClose, style: { zIndex: props.instance.zIndex }, variant: props.instance.props.variant }, props.instance.props.children));
+}
 exports.ModalProvider = (0, react_1.forwardRef)((props, ref) => {
-    var _a, _b;
-    const [content, setContent] = (0, react_1.useState)();
-    const { openDialog, DialogProvider, closeDialog } = (0, dialog_1.useDialog)({
-        isBackdropCloseDisabled: content === null || content === void 0 ? void 0 : content.isBackdropCloseDisabled,
-        isEscapeKeyCloseDisabled: content === null || content === void 0 ? void 0 : content.isEscapeKeyCloseDisabled,
-        onDialogClose: content === null || content === void 0 ? void 0 : content.onClose,
-    });
-    const openModalHandler = (modal) => {
-        openDialog(modal.children);
-        setContent(modal);
-    };
-    const closeModalHandler = () => {
-        if (content === null || content === void 0 ? void 0 : content.onClose) {
-            content.onClose();
-        }
-        closeDialog();
-    };
-    const innerRef = (0, react_1.useRef)({
-        close: closeModalHandler,
-        open: openModalHandler,
-    });
+    const { config } = (0, modal_layer_config_1.useModalLayerConfig)();
+    const [modalStack, setModalStack] = (0, react_1.useState)([]);
+    const openInLayer = (0, react_1.useCallback)((modal, options) => {
+        var _a;
+        const layerName = (_a = options === null || options === void 0 ? void 0 : options.layer) !== null && _a !== void 0 ? _a : config.defaultLayer;
+        const layer = config.layers[config.defaultLayer];
+        const modalId = generateModalId();
+        const shouldReplace = (options === null || options === void 0 ? void 0 : options.shouldReplace) !== false; // default true
+        setModalStack((prev) => {
+            let filtered = prev;
+            // Replace existing modal in same layer if shouldReplace=true
+            if (shouldReplace) {
+                filtered = prev.filter((m) => m.layer !== layerName);
+            }
+            const newModal = {
+                id: modalId,
+                layer: layerName,
+                props: modal,
+                zIndex: layer.zIndex,
+            };
+            // Add and sort by zIndex (lower zIndex first, higher on top)
+            return [...filtered, newModal].sort((a, b) => a.zIndex - b.zIndex);
+        });
+        return modalId;
+    }, [config]);
+    const closeLayer = (0, react_1.useCallback)((layer) => {
+        setModalStack((prev) => prev.filter((m) => m.layer !== layer));
+    }, []);
+    const closeTopmost = (0, react_1.useCallback)(() => {
+        setModalStack((prev) => {
+            if ((0, is_empty_1.isEmpty)(prev)) {
+                return prev;
+            }
+            // Remove the modal with highest zIndex
+            const maxZIndex = Math.max(...prev.map((m) => m.zIndex));
+            return prev.filter((m) => m.zIndex !== maxZIndex);
+        });
+    }, []);
+    const closeAll = (0, react_1.useCallback)(() => {
+        setModalStack([]);
+    }, []);
     (0, react_1.useImperativeHandle)(ref, () => ({
-        close: innerRef.current.close,
-        open: innerRef.current.open,
-    }), []);
-    return (react_1.default.createElement(DialogProvider, { className: `uxf-modal uxf-modal--variant-${(_a = content === null || content === void 0 ? void 0 : content.variant) !== null && _a !== void 0 ? _a : "default"} ${(_b = content === null || content === void 0 ? void 0 : content.className) !== null && _b !== void 0 ? _b : ""}`, variant: content === null || content === void 0 ? void 0 : content.variant }));
+        openInLayer,
+        closeLayer,
+        closeTopmost,
+        closeAll,
+    }), [openInLayer, closeLayer, closeTopmost, closeAll]);
+    return (react_1.default.createElement(react_1.default.Fragment, null, modalStack.map((modalInstance) => (react_1.default.createElement(ModalDialogRenderer, { instance: modalInstance, isTopmost: modalInstance.zIndex === Math.max(...modalStack.map((m) => m.zIndex)), key: modalInstance.id, onClose: () => closeLayer(modalInstance.layer) })))));
 });
 exports.ModalProvider.displayName = "UxfUiModalProvider";

package/modal/modal-service.d.ts

@@ -1,4 +1,19 @@
-import { ModalProviderProps, ModalRef } from "./types";
-export declare function getModalRef(): import("react").RefObject<ModalRef>;
-export declare function openModal(modal: ModalProviderProps): void;
-export declare function closeModal(): void;
+import { ModalLayerName, ModalProviderProps, ModalStackRef, OpenModalOptions } from "./types";
+export declare function getModalStackRef(): import("react").RefObject<ModalStackRef>;
+/**
+ * Opens a modal in the specified layer (or default layer if not specified)
+ * @returns Modal instance ID
+ */
+export declare function openModal(modal: ModalProviderProps, options?: OpenModalOptions): string;
+/**
+ * Closes the topmost modal or a modal in specific layer
+ */
+export declare function closeModal(layer?: ModalLayerName): void;
+/**
+ * Closes all modals in a specific layer
+ */
+export declare function closeModalsByLayer(layer: ModalLayerName): void;
+/**
+ * Closes all modals across all layers
+ */
+export declare function closeAllModals(): void;

package/modal/modal-service.js

@@ -1,20 +1,56 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getModalRef = getModalRef;
+exports.getModalStackRef = getModalStackRef;
 exports.openModal = openModal;
 exports.closeModal = closeModal;
+exports.closeModalsByLayer = closeModalsByLayer;
+exports.closeAllModals = closeAllModals;
 const react_1 = require("react");
-const modalRef = (0, react_1.createRef)();
-function getModalRef() {
-    return modalRef;
+const modalStackRef = (0, react_1.createRef)();
+function getModalStackRef() {
+    return modalStackRef;
 }
-function openModal(modal) {
-    if (modalRef.current) {
-        modalRef.current.open(modal);
+/**
+ * Opens a modal in the specified layer (or default layer if not specified)
+ * @returns Modal instance ID
+ */
+function openModal(modal, options) {
+    if (!modalStackRef.current) {
+        // eslint-disable-next-line no-console
+        console.warn("ModalProvider not initialized. Make sure ModalProvider is mounted with ref from getModalStackRef()");
+        return "";
     }
+    return modalStackRef.current.openInLayer(modal, options);
 }
-function closeModal() {
-    if (modalRef.current) {
-        modalRef.current.close();
+/**
+ * Closes the topmost modal or a modal in specific layer
+ */
+function closeModal(layer) {
+    if (!modalStackRef.current) {
+        return;
     }
+    if (layer) {
+        modalStackRef.current.closeLayer(layer);
+    }
+    else {
+        modalStackRef.current.closeTopmost();
+    }
+}
+/**
+ * Closes all modals in a specific layer
+ */
+function closeModalsByLayer(layer) {
+    if (!modalStackRef.current) {
+        return;
+    }
+    modalStackRef.current.closeLayer(layer);
+}
+/**
+ * Closes all modals across all layers
+ */
+function closeAllModals() {
+    if (!modalStackRef.current) {
+        return;
+    }
+    modalStackRef.current.closeAll();
 }

package/modal/modal.js

@@ -28,5 +28,5 @@ function Modal(props) {
     });
     const { getFloatingProps } = (0, react_1.useInteractions)([click, role, dismiss]);
     const latestContext = (0, use_latest_1.useLatest)(context);
-    return (react_2.default.createElement(dialog_1.Dialog, { className: `uxf-modal uxf-modal--variant-${(_a = props.variant) !== null && _a !== void 0 ? _a : "default"} ${(_b = props.className) !== null && _b !== void 0 ? _b : ""}`, context: latestContext.current, forwardedRef: refs.setFloating, getFloatingProps: getFloatingProps, isOpen: props.isOpen, variant: props.variant }, props.children));
+    return (react_2.default.createElement(dialog_1.Dialog, { className: `uxf-modal uxf-modal--variant-${(_a = props.variant) !== null && _a !== void 0 ? _a : "default"} ${(_b = props.className) !== null && _b !== void 0 ? _b : ""}`, context: latestContext.current, forwardedRef: refs.setFloating, getFloatingProps: getFloatingProps, isOpen: props.isOpen, style: props.style, variant: props.variant }, props.children));
 }

package/modal/modal.stories.d.ts

@@ -1,3 +1,4 @@
 import React from "react";
 export declare function Default(): React.JSX.Element;
 export declare function ModalProvider(): React.JSX.Element;
+export declare function ModalProviderWithLayers(): React.JSX.Element;