@12-apps/ui 1.0.0 → 1.3.1

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

@@ -1,406 +1,18 @@
-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 { Dialog, Slide, styled } 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';
+import type { FC } from 'react';
+import React, { forwardRef, useId } from 'react';
+import { usePanelChrome } from './StackedModal.hooks';
+import { modalAriaIds, ModalPanelContents, resolveModalContent } from './StackedModal.parts';
+import type { PanelStyleProps } from './StackedModal.styles';
+import { dialogRootStyles, STYLE_ONLY_PROPS } from './StackedModal.styles';
+import type { 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,
-}));
+  shouldForwardProp: (prop) => !STYLE_ONLY_PROPS.includes(prop as string),
+})<PanelStyleProps>(({ theme, ...props }) => dialogRootStyles(theme, props));
 
-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
+/** Panels slide in from the right on every device. */
 const SlideTransition = forwardRef<HTMLDivElement, TransitionProps>(
   function SlideTransition(props, ref) {
     return (
@@ -411,155 +23,69 @@ const SlideTransition = forwardRef<HTMLDivElement, TransitionProps>(
   },
 );
 
-// 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);
+const DEFAULTS: Partial<StackedModalProps> = {
+  open: false,
+  glass: false,
+  navigationTitle: '',
+  closeOnClickOutside: true,
+  closeOnEsc: true,
+  loading: false,
+  loadingText: 'Loading...',
+  maxWidth: false,
+  disableBackdrop: false,
+  disableFocusTrap: false,
+  keepMounted: false,
+  rtl: false,
+};
 
-      window.setTimeout(() => setIsAnimating(false), 300);
+/**
+ * Fills in the defaults for props the caller left `undefined`. A table plus one
+ * loop, rather than a default per destructured prop — each of those is a branch,
+ * and fifteen of them put the component over the complexity bar on their own.
+ */
+const withDefaults = (props: StackedModalProps): StackedModalProps => {
+  const resolved = { ...props };
+  for (const [key, value] of Object.entries(DEFAULTS)) {
+    const prop = key as keyof StackedModalProps;
+    if (resolved[prop] === undefined) {
+      Object.assign(resolved, { [prop]: value });
     }
-  }, [stack, modalId, open, modalRole]);
+  }
+  return resolved;
+};
 
-  // Clean up on close
-  useEffect(() => {
-    if (!open && isModalInStack(modalId)) {
-      const timer = window.setTimeout(() => {
-        popModal(modalId);
-      }, 300);
-      return () => window.clearTimeout(timer);
-    }
-  }, [open, modalId, popModal, isModalInStack]);
+/** The modal's props once defaults are applied and its stack identity is settled. */
+type ResolvedProps = StackedModalProps & { modalId: string };
+
+const StackedModalPanel: FC<ResolvedProps> = (props) => {
+  const {
+    open, onClose, glass, navigationTitle, hideClose, children, actions, modalId,
+    closeOnClickOutside, closeOnEsc, loading, loadingText, fullScreen, maxWidth, disableBackdrop,
+    disableFocusTrap, keepMounted, rtl, dataTestId,
+    'aria-labelledby': ariaLabelledBy, 'aria-describedby': ariaDescribedBy, ...otherProps
+  } = props;
+
+  const {
+    dialogRef, modalRole, isAnimating, showSkeleton, zIndex, isMobile, canGoBack,
+    handleBack, handleClose,
+  } = usePanelChrome({
+    open, modalId, loading, closeOnEsc, closeOnClickOutside, disableFocusTrap, onClose,
+  });
 
   // 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}`;
+  const { content, modalActions, headerActions, hasMobileActions } = resolveModalContent(
+    children,
+    actions,
+    isMobile,
+  );
+  const { titleId, descId } = modalAriaIds(modalId, ariaLabelledBy, ariaDescribedBy);
 
   return (
     <StyledDialog
       ref={dialogRef}
-      open={open}
+      open={Boolean(open)}
       onClose={handleClose}
       fullScreen={fullScreen ?? isMobile}
       modalRole={modalRole}
@@ -567,7 +93,7 @@ export const StackedModal: FC<StackedModalProps> = ({
       glass={glass}
       rtl={rtl}
       customMaxWidth={maxWidth}
-      TransitionComponent={Transition}
+      TransitionComponent={SlideTransition}
       maxWidth={maxWidth}
       disableEscapeKeyDown={!closeOnEsc}
       hideBackdrop={disableBackdrop}
@@ -575,90 +101,45 @@ export const StackedModal: FC<StackedModalProps> = ({
       aria-labelledby={titleId}
       aria-describedby={descId}
       data-testid={dataTestId}
-      sx={{
-        zIndex: stack.find((m) => m.id === modalId)?.zIndex || 1300,
-      }}
+      sx={{ zIndex }}
       {...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>
-      )}
+      <ModalPanelContents
+        showSkeleton={showSkeleton}
+        loadingText={loadingText}
+        titleId={titleId}
+        descId={descId}
+        navigationTitle={navigationTitle}
+        hideClose={hideClose}
+        canGoBack={canGoBack}
+        onBack={handleBack}
+        onClose={onClose}
+        headerActions={headerActions}
+        content={content}
+        modalActions={modalActions}
+        hasMobileActions={hasMobileActions}
+        rtl={rtl}
+        dataTestId={dataTestId}
+      />
     </StyledDialog>
   );
 };
 
-// Create aliases for convenience
-export { ModalStackProvider as StackedModalProvider };
-export { useModalStack as useStackedModal };
+export const StackedModal: FC<StackedModalProps> = (props) => {
+  // A modal with no caller-supplied id still needs a STABLE one — it keys this
+  // panel's entry in the stack, so a value that changed per render (as a
+  // `Math.random()` default does) would re-register it on every pass.
+  const fallbackId = useId();
+  const resolved = withDefaults(props);
+  return <StackedModalPanel {...resolved} modalId={resolved.modalId ?? fallbackId} />;
+};
+
+// Re-exported so `./StackedModal` stays the single public entry point for the
+// component and its stack primitives, as the barrel and existing imports expect.
+export {
+  ModalStackProvider,
+  ModalStackProvider as StackedModalProvider,
+  useModalStack,
+  useModalStack as useStackedModal,
+} from './modal-stack';
+export { StackedModalActions, StackedModalContent } from './StackedModal.parts';