[WEB-4980] dev: propel modal portal component

packages/propel/package.json

@@ -35,6 +35,7 @@
     "./menu": "./dist/menu/index.js",
     "./pill": "./dist/pill/index.js",
     "./popover": "./dist/popover/index.js",
+    "./portal": "./dist/portal/index.js",
     "./scrollarea": "./dist/scrollarea/index.js",
     "./skeleton": "./dist/skeleton/index.js",
     "./styles/fonts": "./dist/styles/fonts/index.css",

packages/propel/src/portal/constants.ts

@@ -0,0 +1,28 @@
+export enum EPortalWidth {
+  QUARTER = "quarter",
+  HALF = "half",
+  THREE_QUARTER = "three-quarter",
+  FULL = "full",
+}
+
+export enum EPortalPosition {
+  LEFT = "left",
+  RIGHT = "right",
+  CENTER = "center",
+}
+
+export const PORTAL_WIDTH_CLASSES = {
+  [EPortalWidth.QUARTER]: "w-1/4 min-w-80 max-w-96",
+  [EPortalWidth.HALF]: "w-1/2 min-w-96 max-w-2xl",
+  [EPortalWidth.THREE_QUARTER]: "w-3/4 min-w-96 max-w-5xl",
+  [EPortalWidth.FULL]: "w-full",
+} as const;
+
+export const PORTAL_POSITION_CLASSES = {
+  [EPortalPosition.LEFT]: "left-0",
+  [EPortalPosition.RIGHT]: "right-0",
+  [EPortalPosition.CENTER]: "left-1/2 -translate-x-1/2",
+} as const;
+
+export const DEFAULT_PORTAL_ID = "full-screen-portal";
+export const MODAL_Z_INDEX = 25;

packages/propel/src/portal/index.ts

@@ -0,0 +1,4 @@
+export * from "./modal-portal";
+export * from "./portal-wrapper";
+export * from "./constants";
+export * from "./types";

packages/propel/src/portal/modal-portal.tsx

@@ -0,0 +1,110 @@
+import React, { useCallback, useMemo, useRef, useEffect } from "react";
+import { cn } from "../utils";
+import {
+  EPortalWidth,
+  EPortalPosition,
+  PORTAL_WIDTH_CLASSES,
+  PORTAL_POSITION_CLASSES,
+  DEFAULT_PORTAL_ID,
+  MODAL_Z_INDEX,
+} from "./constants";
+import { PortalWrapper } from "./portal-wrapper";
+import { ModalPortalProps } from "./types";
+
+/**
+ * @param children - The modal content to render
+ * @param isOpen - Whether the modal is open
+ * @param onClose - Function to call when modal should close
+ * @param portalId - The ID of the DOM element to render into
+ * @param className - Custom className for the modal container
+ * @param overlayClassName - Custom className for the overlay
+ * @param contentClassName - Custom className for the content area
+ * @param width - Predefined width options using EPortalWidth enum
+ * @param position - Position of the modal using EPortalPosition enum
+ * @param fullScreen - Whether to render in fullscreen mode
+ * @param showOverlay - Whether to show background overlay
+ * @param closeOnOverlayClick - Whether clicking overlay closes modal
+ * @param closeOnEscape - Whether pressing Escape closes modal
+ */
+export const ModalPortal: React.FC<ModalPortalProps> = ({
+  children,
+  isOpen,
+  onClose,
+  portalId = DEFAULT_PORTAL_ID,
+  className,
+  overlayClassName,
+  contentClassName,
+  width = EPortalWidth.HALF,
+  position = EPortalPosition.RIGHT,
+  fullScreen = false,
+  showOverlay = true,
+  closeOnOverlayClick = true,
+  closeOnEscape = true,
+}) => {
+  const contentRef = useRef<HTMLDivElement>(null);
+
+  // Memoized overlay click handler
+  const handleOverlayClick = useCallback(
+    (e: React.MouseEvent) => {
+      if (closeOnOverlayClick && onClose && e.target === e.currentTarget) {
+        onClose();
+      }
+    },
+    [closeOnOverlayClick, onClose]
+  );
+
+  // close on escape
+  const handleEscape = useCallback(
+    (e: KeyboardEvent) => {
+      if (closeOnEscape && onClose && e.key === "Escape") {
+        onClose();
+      }
+    },
+    [closeOnEscape, onClose]
+  );
+
+  // add event listener for escape
+  useEffect(() => {
+    if (!isOpen) return;
+    document.addEventListener("keydown", handleEscape);
+    return () => {
+      document.removeEventListener("keydown", handleEscape);
+    };
+  }, [isOpen, handleEscape]);
+
+  // Memoized style classes
+  const modalClasses = useMemo(() => {
+    const widthClass = fullScreen ? "w-full h-full" : PORTAL_WIDTH_CLASSES[width];
+    const positionClass = fullScreen ? "" : PORTAL_POSITION_CLASSES[position];
+
+    return cn(
+      "top-0 h-full bg-white shadow-lg absolute transition-transform duration-300 ease-out",
+      widthClass,
+      positionClass,
+      contentClassName
+    );
+  }, [fullScreen, width, position, contentClassName]);
+
+  if (!isOpen) return null;
+
+  const content = (
+    <div
+      className={cn("fixed inset-0 h-full w-full overflow-y-auto", className)}
+      style={{ zIndex: MODAL_Z_INDEX }}
+      role="dialog"
+    >
+      {showOverlay && (
+        <div
+          className={cn("absolute inset-0 bg-black bg-opacity-50 transition-opacity duration-300", overlayClassName)}
+          onClick={handleOverlayClick}
+          aria-hidden="true"
+        />
+      )}
+      <div ref={contentRef} className={cn(modalClasses)} style={{ zIndex: MODAL_Z_INDEX + 1 }} role="document">
+        {children}
+      </div>
+    </div>
+  );
+
+  return <PortalWrapper portalId={portalId}>{content}</PortalWrapper>;
+};

packages/propel/src/portal/portal-wrapper.tsx

@@ -0,0 +1,76 @@
+import React, { useLayoutEffect, useState, useMemo } from "react";
+import { createPortal } from "react-dom";
+import { DEFAULT_PORTAL_ID } from "./constants";
+import { PortalWrapperProps } from "./types";
+
+/**
+ * PortalWrapper - A reusable portal component that renders children into a specific DOM element
+ * Optimized for SSR compatibility and performance
+ *
+ * @param children - The content to render inside the portal
+ * @param portalId - The ID of the DOM element to render into
+ * @param fallbackToDocument - Whether to render directly if portal container is not found
+ * @param className - Optional className to apply to the portal container div
+ * @param onMount - Callback fired when portal is mounted
+ * @param onUnmount - Callback fired when portal is unmounted
+ */
+export const PortalWrapper: React.FC<PortalWrapperProps> = ({
+  children,
+  portalId = DEFAULT_PORTAL_ID,
+  fallbackToDocument = true,
+  className,
+  onMount,
+  onUnmount,
+}) => {
+  const [portalContainer, setPortalContainer] = useState<HTMLElement | null>(null);
+  const [isMounted, setIsMounted] = useState(false);
+
+  useLayoutEffect(() => {
+    // Ensure we're in browser environment
+    if (typeof window === "undefined") return;
+
+    let container = document.getElementById(portalId);
+
+    // Create portal container if it doesn't exist
+    if (!container) {
+      container = document.createElement("div");
+      container.id = portalId;
+      container.setAttribute("data-portal", "true");
+      document.body.appendChild(container);
+    }
+
+    setPortalContainer(container);
+    setIsMounted(true);
+    onMount?.();
+
+    return () => {
+      onUnmount?.();
+      // Only remove if we created it and it's empty
+      if (container && container.children.length === 0 && container.hasAttribute("data-portal")) {
+        document.body.removeChild(container);
+      }
+    };
+  }, [portalId, onMount, onUnmount]);
+
+  const content = useMemo(() => {
+    if (!children) return null;
+    return className ? <div className={className}>{children}</div> : children;
+  }, [children, className]);
+
+  // SSR: render nothing on server
+  if (!isMounted) {
+    return null;
+  }
+
+  // If portal container exists, render into it
+  if (portalContainer) {
+    return createPortal(content, portalContainer);
+  }
+
+  // Fallback behavior for client-side rendering
+  if (fallbackToDocument) {
+    return content ? (content as React.ReactElement) : null;
+  }
+
+  return null;
+};