@12-apps/ui 1.0.0 → 1.3.1

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

@@ -0,0 +1,311 @@
+import ChevronLeftIcon from '@mui/icons-material/ChevronLeft';
+import CloseIcon from '@mui/icons-material/Close';
+import {
+  Box,
+  CircularProgress,
+  DialogActions,
+  DialogContent,
+  DialogTitle,
+  IconButton,
+  Skeleton,
+  styled,
+  Typography,
+} from '@mui/material';
+import type { FC, ReactNode } from 'react';
+import React from 'react';
+import { safeAreaBottom } from '../../../utils/viewport';
+import {
+  loadingOverlayStyles,
+  modalContentStyles,
+  titleLeftStyles,
+  titleRightStyles,
+  titleStyles,
+} from './StackedModal.styles';
+
+const StyledDialogTitle = styled(DialogTitle, {
+  shouldForwardProp: (prop) => prop !== 'rtl',
+})<{ rtl?: boolean }>(({ theme, rtl }) => titleStyles(theme, rtl));
+
+const DialogTitleLeft = styled(Box)(({ theme }) => titleLeftStyles(theme));
+const DialogTitleRight = styled(Box)(({ theme }) => titleRightStyles(theme));
+const LoadingOverlay = styled(Box)(({ theme }) => loadingOverlayStyles(theme));
+
+/**
+ * The padded content wrapper callers put inside a StackedModal. The explicit
+ * `typeof DialogContent` annotation keeps its type nameable across package
+ * boundaries (TS2742) now that it is re-exported from the barrel.
+ */
+export const StackedModalContent: typeof DialogContent = styled(DialogContent)(({ theme }) =>
+  modalContentStyles(theme),
+) as typeof DialogContent;
+
+/** Sub-element test IDs derive from the modal's own, or stay off when it has none. */
+export const testId = (base: string | undefined, suffix: string): string | undefined =>
+  base ? `${base}-${suffix}` : undefined;
+
+/**
+ * A wrapper marking the subtree that should render as modal actions — the
+ * StackedModal pulls it out of `children` and places it by device.
+ */
+export const StackedModalActions: FC<{ children?: ReactNode }> = ({ children }) => <>{children}</>;
+
+/** Separates the `StackedModalActions` subtree from the rest of the content. */
+const splitModalChildren = (children: ReactNode): { content: ReactNode; actions: ReactNode } => {
+  let actions: ReactNode = null;
+
+  React.Children.forEach(children, (child) => {
+    if (React.isValidElement<{ children?: ReactNode }>(child) && child.type === StackedModalActions) {
+      actions = child.props.children;
+    }
+  });
+
+  const content = React.Children.toArray(children).filter(
+    (child) => !(React.isValidElement(child) && child.type === StackedModalActions),
+  );
+
+  return { content, actions };
+};
+
+/**
+ * Works out what renders where: a `StackedModalActions` child wins over the
+ * `actions` prop, and on phones those actions move out of the header into a
+ * pinned bottom bar.
+ */
+export const resolveModalContent = (
+  children: ReactNode,
+  actions: ReactNode,
+  isMobile: boolean,
+): {
+  content: ReactNode;
+  modalActions: ReactNode;
+  headerActions: ReactNode;
+  hasMobileActions: boolean;
+} => {
+  const { content, actions: childActions } = splitModalChildren(children);
+  const modalActions = childActions ?? actions;
+  return {
+    content,
+    modalActions,
+    headerActions: isMobile ? null : modalActions,
+    hasMobileActions: Boolean(isMobile && modalActions),
+  };
+};
+
+/** The panel's own ARIA ids, unless the caller wired it to its own labels. */
+export const modalAriaIds = (
+  modalId: string,
+  ariaLabelledBy?: string,
+  ariaDescribedBy?: string,
+): { titleId: string; descId: string } => ({
+  titleId: ariaLabelledBy || `modal-title-${modalId}`,
+  descId: ariaDescribedBy || `modal-desc-${modalId}`,
+});
+
+export const ModalLoadingOverlay: FC<{ loadingText?: string; dataTestId?: string }> = ({
+  loadingText,
+  dataTestId,
+}) => (
+  <LoadingOverlay data-testid={testId(dataTestId, 'loading-overlay')}>
+    <CircularProgress size={40} data-testid={testId(dataTestId, 'loading-spinner')} />
+    {loadingText && (
+      <Typography variant="body2" sx={{ mt: 2 }} data-testid={testId(dataTestId, 'loading-text')}>
+        {loadingText}
+      </Typography>
+    )}
+  </LoadingOverlay>
+);
+
+interface ModalHeaderProps {
+  titleId: string;
+  navigationTitle?: ReactNode;
+  /** Deeper than the first panel, so the leading button goes back instead of closing. */
+  canGoBack: boolean;
+  onBack: () => void;
+  onClose: () => void;
+  /** Renders the bar without its ✕ — the panel's content owns the dismiss. */
+  hideClose?: boolean;
+  /** Header actions — desktop only; on phones they move to the footer. */
+  headerActions?: ReactNode;
+  rtl?: boolean;
+  dataTestId?: string;
+}
+
+/**
+ * The bar's leading control: back at depth ≥2, otherwise close — and nothing at
+ * all when the panel's content carries its own ✕ (`hideClose`).
+ */
+const HeaderLeadingButton: FC<
+  Pick<ModalHeaderProps, 'canGoBack' | 'onBack' | 'onClose' | 'hideClose' | 'rtl' | 'dataTestId'>
+> = ({ canGoBack, onBack, onClose, hideClose, rtl, dataTestId }) => {
+  if (canGoBack) {
+    return (
+      <IconButton
+        edge="start"
+        color="inherit"
+        onClick={onBack}
+        aria-label="go back"
+        size="small"
+        sx={{ transform: rtl ? 'rotate(180deg)' : 'none' }}
+        data-testid={testId(dataTestId, 'back-button')}
+      >
+        <ChevronLeftIcon />
+      </IconButton>
+    );
+  }
+  if (hideClose) return null;
+  return (
+    <IconButton
+      edge="start"
+      color="inherit"
+      onClick={onClose}
+      aria-label="close"
+      size="small"
+      data-testid={testId(dataTestId, 'close-button')}
+    >
+      <CloseIcon />
+    </IconButton>
+  );
+};
+
+export const ModalHeader: FC<ModalHeaderProps> = ({
+  titleId,
+  navigationTitle,
+  canGoBack,
+  onBack,
+  onClose,
+  hideClose,
+  headerActions,
+  rtl,
+  dataTestId,
+}) => (
+  <StyledDialogTitle id={titleId} rtl={rtl} data-testid={testId(dataTestId, 'header')}>
+    <DialogTitleLeft>
+      <HeaderLeadingButton
+        canGoBack={canGoBack}
+        onBack={onBack}
+        onClose={onClose}
+        hideClose={hideClose}
+        rtl={rtl}
+        dataTestId={dataTestId}
+      />
+      {navigationTitle && (
+        <Typography
+          variant="h6"
+          component="h2"
+          noWrap
+          sx={{ ml: canGoBack || !hideClose ? 1 : 0 }}
+          data-testid={testId(dataTestId, 'title')}
+        >
+          {navigationTitle}
+        </Typography>
+      )}
+    </DialogTitleLeft>
+    <DialogTitleRight data-testid={testId(dataTestId, 'header-actions')}>
+      {headerActions}
+    </DialogTitleRight>
+  </StyledDialogTitle>
+);
+
+const ContentSkeleton: FC = () => (
+  <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>
+);
+
+interface ModalBodyProps {
+  descId: string;
+  showSkeleton: boolean;
+  /** When there is no action bar, the body is what reaches the bottom of the panel. */
+  endsPanel: boolean;
+  dataTestId?: string;
+  children?: ReactNode;
+}
+
+export const ModalBody: FC<ModalBodyProps> = ({
+  descId,
+  showSkeleton,
+  endsPanel,
+  dataTestId,
+  children,
+}) => (
+  <Box
+    id={descId}
+    sx={{
+      position: 'relative',
+      flex: 1,
+      overflow: 'auto',
+      // iOS momentum scrolling, and no scroll-chaining to the page behind —
+      // without `contain`, an overscroll at the end of the list rubber-bands the
+      // whole panel and springs back before the last row can be tapped.
+      WebkitOverflowScrolling: 'touch',
+      overscrollBehavior: 'contain',
+      // The content itself ends the panel when there is no action bar, so it has
+      // to clear the home indicator on its own.
+      ...(endsPanel ? safeAreaBottom(0) : {}),
+    }}
+    data-testid={testId(dataTestId, 'content')}
+  >
+    {showSkeleton ? <ContentSkeleton /> : children}
+  </Box>
+);
+
+/** The phone-only pinned action bar; on desktop the actions live in the header. */
+export const ModalFooter: FC<{ dataTestId?: string; children?: ReactNode }> = ({
+  dataTestId,
+  children,
+}) => (
+  <DialogActions
+    sx={{
+      borderTop: (theme) => `1px solid ${theme.palette.divider}`,
+      padding: 2,
+      // Never let the action row sit under the iOS home indicator.
+      flexShrink: 0,
+      ...safeAreaBottom(16),
+    }}
+    data-testid={testId(dataTestId, 'footer')}
+  >
+    {children}
+  </DialogActions>
+);
+
+interface PanelContentsProps extends ModalHeaderProps {
+  showSkeleton: boolean;
+  loadingText?: string;
+  descId: string;
+  content: ReactNode;
+  /** The resolved actions, already placed in the header or destined for the footer. */
+  modalActions: ReactNode;
+  hasMobileActions: boolean;
+}
+
+/** Everything inside the sliding panel: the loading veil, header, body and action bar. */
+export const ModalPanelContents: FC<PanelContentsProps> = ({
+  showSkeleton,
+  loadingText,
+  descId,
+  content,
+  modalActions,
+  hasMobileActions,
+  ...header
+}) => (
+  <>
+    {showSkeleton && (
+      <ModalLoadingOverlay loadingText={loadingText} dataTestId={header.dataTestId} />
+    )}
+    <ModalHeader {...header} />
+    <ModalBody
+      descId={descId}
+      showSkeleton={showSkeleton}
+      endsPanel={!hasMobileActions}
+      dataTestId={header.dataTestId}
+    >
+      {content}
+    </ModalBody>
+    {hasMobileActions && (
+      <ModalFooter dataTestId={header.dataTestId}>{modalActions}</ModalFooter>
+    )}
+  </>
+);

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

@@ -1,18 +1,16 @@
-import {
-  Add as AddIcon,
-  CheckCircle as CheckCircleIcon,
-  CloudUpload as CloudUploadIcon,
-  Delete as DeleteIcon,
-  Download as DownloadIcon,
-  Edit as EditIcon,
-  FilterList as FilterListIcon,
-  Info as InfoIcon,
-  MoreVert as MoreVertIcon,
-  Save as SaveIcon,
-  Search as SearchIcon,
-  Settings as SettingsIcon,
-  Share as ShareIcon,
-} from '@mui/icons-material';
+import AddIcon from '@mui/icons-material/Add';
+import CheckCircleIcon from '@mui/icons-material/CheckCircle';
+import CloudUploadIcon from '@mui/icons-material/CloudUpload';
+import DeleteIcon from '@mui/icons-material/Delete';
+import DownloadIcon from '@mui/icons-material/Download';
+import EditIcon from '@mui/icons-material/Edit';
+import FilterListIcon from '@mui/icons-material/FilterList';
+import InfoIcon from '@mui/icons-material/Info';
+import MoreVertIcon from '@mui/icons-material/MoreVert';
+import SaveIcon from '@mui/icons-material/Save';
+import SearchIcon from '@mui/icons-material/Search';
+import SettingsIcon from '@mui/icons-material/Settings';
+import ShareIcon from '@mui/icons-material/Share';
 import {
   Alert,
   Avatar,

package/src/components/feedback/StackedModal/StackedModal.styles.ts

@@ -0,0 +1,193 @@
+import { alpha } from '@mui/material';
+import type { CSSObject, Theme } from '@mui/material/styles';
+import { dynamicViewportHeight } from '../../../utils/viewport';
+import type { ModalPanelRole, PanelMaxWidth } from './StackedModal.types';
+
+/** Props that drive the panel's look but must not reach the DOM. */
+export interface PanelStyleProps {
+  modalRole?: ModalPanelRole;
+  isAnimating?: boolean;
+  glass?: boolean;
+  rtl?: boolean;
+  customMaxWidth?: PanelMaxWidth;
+}
+
+/** Style-only props, filtered out before they can land on a DOM node. */
+export const STYLE_ONLY_PROPS = ['modalRole', 'isAnimating', 'glass', 'rtl', 'customMaxWidth'];
+
+/** MUI breakpoint names mapped to the pixel width they cap the panel at. */
+const MAX_WIDTH_PX: Record<Exclude<PanelMaxWidth, false>, number> = {
+  xs: 444,
+  sm: 600,
+  md: 960,
+  lg: 1280,
+  xl: 1920,
+};
+
+const BACKDROP_BY_ROLE: Partial<Record<ModalPanelRole, string>> = {
+  secondary: 'rgba(0, 0, 0, 0.3)',
+  background: 'rgba(0, 0, 0, 0.1)',
+};
+
+const ANIMATION_BY_ROLE: Partial<Record<ModalPanelRole, string>> = {
+  secondary: 'expandModal 300ms ease-in-out forwards',
+  primary: 'contractModal 300ms ease-in-out forwards',
+};
+
+// Animation endpoints use the common lg width (60vw); the role styles set the
+// exact per-breakpoint width once the animation settles.
+const KEYFRAMES: CSSObject = {
+  '@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 cap = (customMaxWidth?: PanelMaxWidth): number | null =>
+  customMaxWidth ? MAX_WIDTH_PX[customMaxWidth] : null;
+
+/** One breakpoint's width: the viewport share, held under the optional px cap. */
+const panelWidth = (share: string, capPx: number | null): CSSObject =>
+  capPx
+    ? { width: `min(${share}, ${capPx}px)`, maxWidth: `${capPx}px` }
+    : { width: share, maxWidth: share };
+
+const backdropStyles = (modalRole?: ModalPanelRole): CSSObject => ({
+  backgroundColor: (modalRole && BACKDROP_BY_ROLE[modalRole]) ?? 'rgba(0, 0, 0, 0.5)',
+  backdropFilter: modalRole === 'primary' ? 'blur(4px)' : 'none',
+});
+
+/**
+ * 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.
+ */
+const primaryPanelStyles = (theme: Theme, capPx: number | null): CSSObject => ({
+  [theme.breakpoints.down('sm')]: panelWidth('100%', capPx),
+  [theme.breakpoints.between('sm', 'lg')]: panelWidth('80vw', capPx),
+  [theme.breakpoints.up('lg')]: panelWidth('60vw', capPx),
+  '@media (min-width:2200px)': panelWidth('40vw', capPx),
+});
+
+/** Panels below the top one expand to full width, producing the GTM stacking effect. */
+const secondaryPanelStyles = (): CSSObject => ({
+  width: '100vw !important',
+  maxWidth: '100vw !important',
+  right: '0 !important',
+  top: '0 !important',
+  ...dynamicViewportHeight('height', 'maxHeight'),
+  borderRadius: '0 !important',
+  opacity: 0.95,
+  transform: 'scale(1)',
+});
+
+const rolePanelStyles = (theme: Theme, role: ModalPanelRole | undefined, capPx: number | null): CSSObject => {
+  if (role === 'primary') return primaryPanelStyles(theme, capPx);
+  if (role === 'secondary') return secondaryPanelStyles();
+  // Background modals stay mounted but hidden, for performance.
+  if (role === 'background') return { display: 'none' };
+  return {};
+};
+
+const glassStyles = (theme: Theme, glass?: boolean, role?: ModalPanelRole): CSSObject =>
+  glass && role === 'primary'
+    ? {
+        backgroundColor: alpha(theme.palette.background.paper, 0.85),
+        backdropFilter: 'blur(10px)',
+        WebkitBackdropFilter: 'blur(10px)',
+        border: `1px solid ${alpha(theme.palette.divider, 0.18)}`,
+      }
+    : {};
+
+const animationStyles = (isAnimating?: boolean, role?: ModalPanelRole): CSSObject =>
+  isAnimating ? { animation: (role && ANIMATION_BY_ROLE[role]) ?? 'none' } : {};
+
+const panelBaseStyles = (theme: Theme): CSSObject => ({
+  margin: 0,
+  position: 'fixed',
+  right: 0,
+  top: 0,
+  // Pinned to the DYNAMIC viewport: on iOS a `100vh` panel runs underneath the
+  // browser toolbar, which parks the tail of the scroll area (the submit row)
+  // out of reach. See `dynamicViewportHeight`.
+  ...dynamicViewportHeight('height', 'maxHeight'),
+  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 },
+  ),
+});
+
+const panelStyles = (theme: Theme, props: PanelStyleProps): CSSObject => {
+  const capPx = cap(props.customMaxWidth);
+  return {
+    ...panelBaseStyles(theme),
+    ...rolePanelStyles(theme, props.modalRole, capPx),
+    ...glassStyles(theme, props.glass, props.modalRole),
+    ...animationStyles(props.isAnimating, props.modalRole),
+  };
+};
+
+/** The full rule set for the sliding panel's Dialog root. */
+export const dialogRootStyles = (theme: Theme, props: PanelStyleProps): CSSObject => ({
+  direction: props.rtl ? 'rtl' : 'ltr',
+  '& .MuiBackdrop-root': backdropStyles(props.modalRole),
+  '& .MuiDialog-container': { alignItems: 'flex-start', justifyContent: 'flex-end' },
+  '& .MuiDialog-paper': panelStyles(theme, props),
+  ...KEYFRAMES,
+});
+
+export const titleStyles = (theme: Theme, rtl?: boolean): CSSObject => ({
+  display: 'flex',
+  alignItems: 'center',
+  justifyContent: 'space-between',
+  padding: theme.spacing(2, 2.5),
+  borderBottom: `1px solid ${theme.palette.divider}`,
+  direction: rtl ? 'rtl' : 'ltr',
+});
+
+export const titleLeftStyles = (theme: Theme): CSSObject => ({
+  display: 'flex',
+  alignItems: 'center',
+  gap: theme.spacing(1.5),
+  flex: 1,
+});
+
+export const titleRightStyles = (theme: Theme): CSSObject => ({
+  display: 'flex',
+  alignItems: 'center',
+  gap: theme.spacing(1),
+});
+
+export const loadingOverlayStyles = (theme: Theme): CSSObject => ({
+  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,
+});
+
+export const modalContentStyles = (theme: Theme): CSSObject => ({
+  padding: theme.spacing(3),
+  // MUI's DialogContent defaults to `overflow-y: auto`, but inside a panel it is
+  // NOT the element that scrolls — ModalBody above it is, and this box always
+  // ends up exactly as tall as its own content. A scroll container that never
+  // scrolls is still the containing block for every `position: sticky`
+  // descendant, so a sticky header anchored here gets zero travel and rides the
+  // content out of view: sticky, and pinned to nothing. Handing the overflow
+  // back to ModalBody makes the panel's own scroller the anchor.
+  overflowY: 'visible',
+});