@12-apps/ui 1.0.0

package/src/components/feedback/StackedModal/StackedModal.tsx

@@ -0,0 +1,664 @@
+import { ChevronLeft as ChevronLeftIcon, Close as CloseIcon } from '@mui/icons-material';
+import {
+  alpha,
+  Box,
+  CircularProgress,
+  Dialog,
+  DialogActions,
+  DialogContent,
+  DialogTitle,
+  IconButton,
+  Skeleton,
+  Slide,
+  styled,
+  Typography,
+  useMediaQuery,
+  useTheme,
+} from '@mui/material';
+import type { TransitionProps } from '@mui/material/transitions';
+import type {
+  FC,
+  ReactNode} from 'react';
+import React, {
+  createContext,
+  forwardRef,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+import { ModalInfo, ModalStackContextValue, StackedModalProps } from './StackedModal.types';
+
+// Modal Stack Context
+const ModalStackContext = createContext<ModalStackContextValue>({
+  stack: [],
+  pushModal: () => {
+    /** do nothing */
+  },
+  popModal: () => {
+    /** do nothing */
+  },
+  clearStack: () => {
+    /** do nothing */
+  },
+  currentDepth: 0,
+  isModalInStack: () => false,
+  getModalRole: () => null,
+});
+
+// Hook to use modal stack
+export const useModalStack = () => {
+  const context = useContext(ModalStackContext);
+  if (!context) {
+    throw new Error('useModalStack must be used within a ModalStackProvider');
+  }
+  return context;
+};
+
+// Modal Stack Provider
+export const ModalStackProvider: FC<{ children: ReactNode }> = ({ children }) => {
+  const [stack, setStack] = useState<ModalInfo[]>([]);
+  const baseZIndex = 1300; // MUI Dialog default z-index
+  const originalBodyOverflow = useRef<string>('');
+
+  // Manage body scroll lock at provider level
+  useEffect(() => {
+    if (stack.length > 0) {
+      // Lock scroll when any modal is open
+      if (!originalBodyOverflow.current) {
+        originalBodyOverflow.current = document.body.style.overflow || '';
+      }
+      document.body.style.overflow = 'hidden';
+    } else {
+      // Restore scroll when all modals are closed
+      if (originalBodyOverflow.current !== null) {
+        document.body.style.overflow = originalBodyOverflow.current;
+        originalBodyOverflow.current = '';
+      }
+    }
+
+    // Cleanup on unmount
+    return () => {
+      if (originalBodyOverflow.current) {
+        document.body.style.overflow = originalBodyOverflow.current;
+        originalBodyOverflow.current = '';
+      }
+    };
+  }, [stack.length]);
+
+  const pushModal = useCallback(
+    (modalId: string) => {
+      setStack((prev) => {
+        // Check if modal already exists
+        if (prev.some((m) => m.id === modalId)) return prev;
+
+        // Update roles for existing modals
+        const updatedStack = prev.map((modal, index) => ({
+          ...modal,
+          role:
+            index === prev.length - 1 ? 'secondary' : ('background' as 'secondary' | 'background'),
+        }));
+
+        // Add new modal as primary
+        return [
+          ...updatedStack,
+          {
+            id: modalId,
+            zIndex: baseZIndex + prev.length * 10,
+            role: 'primary' as const,
+          },
+        ];
+      });
+    },
+    [baseZIndex],
+  );
+
+  const popModal = useCallback((modalId?: string) => {
+    setStack((prev) => {
+      if (modalId) {
+        // Remove specific modal
+        const newStack = prev.filter((m) => m.id !== modalId);
+        // Update roles
+        return newStack.map(
+          (modal, index) =>
+            ({
+              ...modal,
+              role:
+                index === newStack.length - 1
+                  ? 'primary'
+                  : index === newStack.length - 2
+                    ? 'secondary'
+                    : 'background',
+            }) as ModalInfo,
+        );
+      } else {
+        // Remove top modal
+        const newStack = prev.slice(0, -1);
+        // Update roles
+        return newStack.map(
+          (modal, index) =>
+            ({
+              ...modal,
+              role:
+                index === newStack.length - 1
+                  ? 'primary'
+                  : index === newStack.length - 2
+                    ? 'secondary'
+                    : 'background',
+            }) as ModalInfo,
+        );
+      }
+    });
+  }, []);
+
+  const clearStack = useCallback(() => {
+    setStack([]);
+  }, []);
+
+  const isModalInStack = useCallback(
+    (modalId: string) => stack.some((m) => m.id === modalId),
+    [stack],
+  );
+
+  const _getModalRole = useCallback(
+    (modalId: string) => {
+      const modal = stack.find((m) => m.id === modalId);
+      return modal?.role || null;
+    },
+    [stack],
+  );
+
+  const value = useMemo(
+    () => ({
+      stack,
+      pushModal,
+      popModal,
+      clearStack,
+      currentDepth: stack.length,
+      isModalInStack,
+      getModalRole: _getModalRole,
+    }),
+    [stack, pushModal, popModal, clearStack, isModalInStack, _getModalRole],
+  );
+
+  return <ModalStackContext.Provider value={value}>{children}</ModalStackContext.Provider>;
+};
+
+// Focus trap helper
+const useFocusTrap = (ref: React.RefObject<HTMLElement | null>, isActive: boolean, disabled?: boolean) => {
+  useEffect(() => {
+    if (!isActive || disabled || !ref.current) return;
+
+    const element = ref.current;
+    const focusableElements = element.querySelectorAll(
+      'a[href], button, textarea, input, select, [tabindex]:not([tabindex="-1"])',
+    );
+
+    const firstElement = focusableElements[0] as HTMLElement;
+    const lastElement = focusableElements[focusableElements.length - 1] as HTMLElement;
+
+    // Focus first element
+    window.setTimeout(() => firstElement?.focus(), 100);
+
+    const handleTabKey = (e: globalThis.KeyboardEvent) => {
+      if (e.key !== 'Tab') return;
+
+      if (e.shiftKey) {
+        if (document.activeElement === firstElement) {
+          e.preventDefault();
+          lastElement?.focus();
+        }
+      } else {
+        if (document.activeElement === lastElement) {
+          e.preventDefault();
+          firstElement?.focus();
+        }
+      }
+    };
+
+    element.addEventListener('keydown', handleTabKey);
+    return () => element.removeEventListener('keydown', handleTabKey);
+  }, [ref, isActive, disabled]);
+};
+
+// Styled Components
+const StyledDialog = styled(Dialog, {
+  shouldForwardProp: (prop) =>
+    !['modalRole', 'isAnimating', 'glass', 'rtl', 'customMaxWidth'].includes(prop as string),
+})<{ modalRole?: string; isAnimating?: boolean; glass?: boolean; rtl?: boolean; customMaxWidth?: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | false }>(
+  ({ theme, modalRole, isAnimating, glass, rtl, customMaxWidth }) => {
+    // Map MUI breakpoint values to pixel widths
+    const maxWidthMap = {
+      xs: 444,
+      sm: 600,
+      md: 960,
+      lg: 1280,
+      xl: 1920,
+    };
+
+    const maxWidthPx = customMaxWidth !== false && customMaxWidth ? maxWidthMap[customMaxWidth as keyof typeof maxWidthMap] : null;
+
+    return ({
+      direction: rtl ? 'rtl' : 'ltr',
+      '& .MuiBackdrop-root': {
+        backgroundColor:
+          modalRole === 'secondary'
+            ? 'rgba(0, 0, 0, 0.3)'
+            : modalRole === 'background'
+              ? 'rgba(0, 0, 0, 0.1)'
+              : 'rgba(0, 0, 0, 0.5)',
+        backdropFilter: modalRole === 'primary' ? 'blur(4px)' : 'none',
+      },
+      '& .MuiDialog-container': {
+        alignItems: 'flex-start',
+        justifyContent: 'flex-end',
+      },
+      '& .MuiDialog-paper': {
+        margin: 0,
+        position: 'fixed',
+        right: 0,
+        top: 0,
+        height: '100vh',
+        maxHeight: '100vh',
+        borderRadius: 0,
+        willChange: 'transform, width, border-radius',
+        transition: theme.transitions.create(
+          ['width', 'max-width', 'border-radius', 'transform', 'opacity'],
+          {
+            duration: 300,
+            easing: theme.transitions.easing.easeInOut,
+          },
+        ),
+        ...(modalRole === 'primary' && {
+          // The top panel is viewport-aware and narrows as the screen grows: full
+          // width on mobile, 80vw on tablet/small desktop, 60vw on regular desktops
+          // (lg up — including ~1080p/1440p/1080-wide), and 40vw only on ultra-wide
+          // screens (≥2200px) so the receding panel stays visible on huge monitors.
+          // A `maxWidth` prop, when given, caps it further. Panels below expand to
+          // full width (the `secondary` role), producing the GTM stacking effect.
+          [theme.breakpoints.down('sm')]: {
+            width: maxWidthPx ? `min(100%, ${maxWidthPx}px)` : '100%',
+            maxWidth: maxWidthPx ? `${maxWidthPx}px` : '100%',
+          },
+          [theme.breakpoints.between('sm', 'lg')]: {
+            width: maxWidthPx ? `min(80vw, ${maxWidthPx}px)` : '80vw',
+            maxWidth: maxWidthPx ? `${maxWidthPx}px` : '80vw',
+          },
+          [theme.breakpoints.up('lg')]: {
+            width: maxWidthPx ? `min(60vw, ${maxWidthPx}px)` : '60vw',
+            maxWidth: maxWidthPx ? `${maxWidthPx}px` : '60vw',
+          },
+          '@media (min-width:2200px)': {
+            width: maxWidthPx ? `min(40vw, ${maxWidthPx}px)` : '40vw',
+            maxWidth: maxWidthPx ? `${maxWidthPx}px` : '40vw',
+          },
+        }),
+        ...(modalRole === 'secondary' && {
+          width: '100vw !important',
+          maxWidth: '100vw !important',
+          right: '0 !important',
+          top: '0 !important',
+          height: '100vh',
+          maxHeight: '100vh',
+          borderRadius: '0 !important',
+          opacity: 0.95,
+          transform: 'scale(1)',
+        }),
+        ...(modalRole === 'background' && {
+          display: 'none', // Hide background modals for performance
+        }),
+        ...(glass &&
+          modalRole === 'primary' && {
+            backgroundColor: alpha(theme.palette.background.paper, 0.85),
+            backdropFilter: 'blur(10px)',
+            WebkitBackdropFilter: 'blur(10px)',
+            border: `1px solid ${alpha(theme.palette.divider, 0.18)}`,
+          }),
+        ...(isAnimating && {
+          animation:
+            modalRole === 'secondary'
+              ? 'expandModal 300ms ease-in-out forwards'
+              : modalRole === 'primary'
+                ? 'contractModal 300ms ease-in-out forwards'
+                : 'none',
+        }),
+      },
+      // Animation endpoints use the common lg width (60vw); the role styles set the
+      // exact per-breakpoint width once the animation settles.
+      '@keyframes expandModal': {
+        from: {
+          width: '60vw',
+          transform: 'translateX(0)',
+        },
+        to: {
+          width: '100vw',
+          transform: 'translateX(0)',
+        },
+      },
+      '@keyframes contractModal': {
+        from: {
+          width: '100vw',
+          transform: 'translateX(0)',
+        },
+        to: {
+          width: '60vw',
+          transform: 'translateX(0)',
+        },
+      },
+    });
+  },
+);
+
+const StyledDialogTitle = styled(DialogTitle, {
+  shouldForwardProp: (prop) => !['rtl'].includes(prop as string),
+})<{ rtl?: boolean }>(({ theme, rtl }) => ({
+  display: 'flex',
+  alignItems: 'center',
+  justifyContent: 'space-between',
+  padding: theme.spacing(2, 2.5),
+  borderBottom: `1px solid ${theme.palette.divider}`,
+  direction: rtl ? 'rtl' : 'ltr',
+}));
+
+const DialogTitleLeft = styled(Box)(({ theme }) => ({
+  display: 'flex',
+  alignItems: 'center',
+  gap: theme.spacing(1.5),
+  flex: 1,
+}));
+
+const DialogTitleRight = styled(Box)(({ theme }) => ({
+  display: 'flex',
+  alignItems: 'center',
+  gap: theme.spacing(1),
+}));
+
+const LoadingOverlay = styled(Box)(({ theme }) => ({
+  position: 'absolute',
+  top: 0,
+  left: 0,
+  right: 0,
+  bottom: 0,
+  display: 'flex',
+  flexDirection: 'column',
+  alignItems: 'center',
+  justifyContent: 'center',
+  backgroundColor: alpha(theme.palette.background.paper, 0.8),
+  zIndex: 9999,
+}));
+
+// Modal subcomponents
+export const StackedModalContent: typeof DialogContent = styled(DialogContent)(({ theme }) => ({
+  padding: theme.spacing(3),
+})) as typeof DialogContent;
+
+// ModalActions component that will be rendered differently based on device
+export const StackedModalActions: FC<{ children?: ReactNode }> = ({ children }) =>
+  // This component is just a wrapper, actual placement is handled in StackedModal
+   <>{children}</>
+;
+
+// Custom transition for slide from right
+const SlideTransition = forwardRef<HTMLDivElement, TransitionProps>(
+  function SlideTransition(props, ref) {
+    return (
+      <Slide direction="left" ref={ref} {...props}>
+        {props.children as React.ReactElement}
+      </Slide>
+    );
+  },
+);
+
+// StackedModal Component
+export const StackedModal: FC<StackedModalProps> = ({
+  open = false,
+  onClose,
+  glass = false,
+  navigationTitle = '',
+  children,
+  actions,
+  modalId = Math.random().toString(36).substring(2, 11),
+  closeOnClickOutside = true,
+  closeOnEsc = true,
+  loading = false,
+  loadingText = 'Loading...',
+  fullScreen,
+  maxWidth = false,
+  disableBackdrop = false,
+  disableFocusTrap = false,
+  keepMounted = false,
+  rtl = false,
+  dataTestId,
+  'aria-labelledby': ariaLabelledBy,
+  'aria-describedby': ariaDescribedBy,
+  ...otherProps
+}) => {
+  // Extract ModalActions from children
+  let modalContent = children;
+  let modalActions = null;
+
+  React.Children.forEach(children, (child) => {
+    if (React.isValidElement<{ children?: ReactNode }>(child) && child.type === StackedModalActions) {
+      modalActions = child.props.children;
+    }
+  });
+
+  // Filter out ModalActions from children for content
+  modalContent = React.Children.toArray(children).filter(
+    (child) => !(React.isValidElement(child) && child.type === StackedModalActions),
+  );
+  const [modalRole, setModalRole] = useState<'primary' | 'secondary' | 'background'>('primary');
+  const [isAnimating, setIsAnimating] = useState(false);
+  const [showSkeleton, setShowSkeleton] = useState(loading);
+  const dialogRef = useRef<HTMLDivElement>(null);
+  const previousRoleRef = useRef(modalRole);
+  const hasRegisteredRef = useRef(false);
+  const { stack, pushModal, popModal, getModalRole: _getModalRole, isModalInStack } = useModalStack();
+
+  const theme = useTheme();
+  const isMobile = useMediaQuery(theme.breakpoints.down('sm'));
+  // const isTablet = useMediaQuery(theme.breakpoints.between('sm', 'md')); // Reserved for future use
+
+  // Use focus trap
+  useFocusTrap(dialogRef, open && modalRole === 'primary', disableFocusTrap);
+
+  // Lock body scroll - NOW MANAGED BY MODALSTACKPROVIDER
+  // useBodyScrollLock(open && modalRole === 'primary');
+
+  // Handle ESC key press
+  useEffect(() => {
+    if (!open || !closeOnEsc || modalRole !== 'primary') return;
+
+    const handleEsc = (e: globalThis.KeyboardEvent) => {
+      if (e.key === 'Escape') {
+        e.preventDefault();
+        onClose();
+      }
+    };
+
+    window.addEventListener('keydown', handleEsc);
+    return () => window.removeEventListener('keydown', handleEsc);
+  }, [open, closeOnEsc, onClose, modalRole]);
+
+  // Handle loading state
+  useEffect(() => {
+    if (loading) {
+      setShowSkeleton(true);
+    } else {
+      // Delay hiding skeleton for smooth transition
+      const timer = window.setTimeout(() => setShowSkeleton(false), 200);
+      return () => window.clearTimeout(timer);
+    }
+  }, [loading]);
+
+  // Register modal when it opens
+  useEffect(() => {
+    if (open && !hasRegisteredRef.current) {
+      pushModal(modalId);
+      hasRegisteredRef.current = true;
+    } else if (!open) {
+      hasRegisteredRef.current = false;
+    }
+  }, [open, modalId, pushModal]);
+
+  // Update modal role when stack changes
+  useEffect(() => {
+    if (!open) return;
+
+    const currentModal = stack.find((m) => m.id === modalId);
+    if (!currentModal) return;
+
+    const newRole = currentModal.role;
+
+    if (newRole !== modalRole) {
+      setIsAnimating(true);
+      previousRoleRef.current = modalRole;
+      setModalRole(newRole);
+
+      window.setTimeout(() => setIsAnimating(false), 300);
+    }
+  }, [stack, modalId, open, modalRole]);
+
+  // Clean up on close
+  useEffect(() => {
+    if (!open && isModalInStack(modalId)) {
+      const timer = window.setTimeout(() => {
+        popModal(modalId);
+      }, 300);
+      return () => window.clearTimeout(timer);
+    }
+  }, [open, modalId, popModal, isModalInStack]);
+
+  // Don't render if in background (performance optimization)
+  if (modalRole === 'background' && !keepMounted) return null;
+
+  const handleBackClick = () => {
+    if (stack.length > 1) {
+      onClose();
+    }
+  };
+
+  const handleClose = (_event: object, reason: 'backdropClick' | 'escapeKeyDown') => {
+    if (modalRole !== 'primary') return;
+
+    if (reason === 'backdropClick' && !closeOnClickOutside) return;
+    if (reason === 'escapeKeyDown' && !closeOnEsc) return;
+
+    onClose();
+  };
+
+  // Use slide transition for all devices
+  const Transition = SlideTransition;
+
+  // Generate unique IDs for accessibility
+  const titleId = ariaLabelledBy || `modal-title-${modalId}`;
+  const descId = ariaDescribedBy || `modal-desc-${modalId}`;
+
+  return (
+    <StyledDialog
+      ref={dialogRef}
+      open={open}
+      onClose={handleClose}
+      fullScreen={fullScreen ?? isMobile}
+      modalRole={modalRole}
+      isAnimating={isAnimating}
+      glass={glass}
+      rtl={rtl}
+      customMaxWidth={maxWidth}
+      TransitionComponent={Transition}
+      maxWidth={maxWidth}
+      disableEscapeKeyDown={!closeOnEsc}
+      hideBackdrop={disableBackdrop}
+      keepMounted={keepMounted}
+      aria-labelledby={titleId}
+      aria-describedby={descId}
+      data-testid={dataTestId}
+      sx={{
+        zIndex: stack.find((m) => m.id === modalId)?.zIndex || 1300,
+      }}
+      {...otherProps}
+    >
+      {/* Loading Overlay */}
+      {showSkeleton && (
+        <LoadingOverlay data-testid={dataTestId ? `${dataTestId}-loading-overlay` : undefined}>
+          <CircularProgress size={40} data-testid={dataTestId ? `${dataTestId}-loading-spinner` : undefined} />
+          {loadingText && (
+            <Typography variant="body2" sx={{ mt: 2 }} data-testid={dataTestId ? `${dataTestId}-loading-text` : undefined}>
+              {loadingText}
+            </Typography>
+          )}
+        </LoadingOverlay>
+      )}
+
+      <StyledDialogTitle id={titleId} rtl={rtl} data-testid={dataTestId ? `${dataTestId}-header` : undefined}>
+        <DialogTitleLeft>
+          {stack.length > 1 ? (
+            <IconButton
+              edge="start"
+              color="inherit"
+              onClick={handleBackClick}
+              aria-label="go back"
+              size="small"
+              sx={{ transform: rtl ? 'rotate(180deg)' : 'none' }}
+              data-testid={dataTestId ? `${dataTestId}-back-button` : undefined}
+            >
+              <ChevronLeftIcon />
+            </IconButton>
+          ) : (
+            <IconButton
+              edge="start"
+              color="inherit"
+              onClick={onClose}
+              aria-label="close"
+              size="small"
+              data-testid={dataTestId ? `${dataTestId}-close-button` : undefined}
+            >
+              <CloseIcon />
+            </IconButton>
+          )}
+          {navigationTitle && (
+            <Typography variant="h6" component="h2" noWrap sx={{ ml: 1 }} data-testid={dataTestId ? `${dataTestId}-title` : undefined}>
+              {navigationTitle}
+            </Typography>
+          )}
+        </DialogTitleLeft>
+        <DialogTitleRight data-testid={dataTestId ? `${dataTestId}-header-actions` : undefined}>
+          {/* On desktop, show modalActions or actions prop in header */}
+          {!isMobile && (modalActions || actions)}
+        </DialogTitleRight>
+      </StyledDialogTitle>
+
+      <Box id={descId} sx={{ position: 'relative', flex: 1, overflow: 'auto' }} data-testid={dataTestId ? `${dataTestId}-content` : undefined}>
+        {showSkeleton ? (
+          <Box sx={{ p: 3 }}>
+            <Skeleton variant="text" width="60%" height={32} />
+            <Skeleton variant="text" width="100%" />
+            <Skeleton variant="text" width="100%" />
+            <Skeleton variant="rectangular" height={200} sx={{ mt: 2 }} />
+          </Box>
+        ) : (
+          modalContent
+        )}
+      </Box>
+
+      {/* On mobile, show modalActions at the bottom */}
+      {isMobile && (modalActions || actions) && (
+        <DialogActions
+          sx={{
+            borderTop: (theme) => `1px solid ${theme.palette.divider}`,
+            padding: 2,
+          }}
+          data-testid={dataTestId ? `${dataTestId}-footer` : undefined}
+        >
+          {modalActions || actions}
+        </DialogActions>
+      )}
+    </StyledDialog>
+  );
+};
+
+// Create aliases for convenience
+export { ModalStackProvider as StackedModalProvider };
+export { useModalStack as useStackedModal };