@12-apps/ui 1.0.0 → 1.3.1

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

@@ -1,5 +1,11 @@
 import type { ReactNode } from 'react';
 
+/** A modal's position in the stack: the top panel, the one behind it, or hidden. */
+export type ModalPanelRole = 'primary' | 'secondary' | 'background';
+
+/** The breakpoint the panel's width is capped at, or `false` for uncapped. */
+export type PanelMaxWidth = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | false;
+
 export interface StackedModalProps {
   /** Controls the visibility of the modal */
   open: boolean;
@@ -9,6 +15,14 @@ export interface StackedModalProps {
   glass?: boolean;
   /** Title displayed in the modal navigation bar */
   navigationTitle?: string | ReactNode;
+  /**
+   * Drops the header's ✕ so the navigation bar is a breadcrumb only. For panels
+   * whose CONTENT owns the dismiss (a sticky action bar with its own close):
+   * two ✕ a few pixels apart are the same action twice with nothing to tell
+   * them apart. Never hides the BACK arrow of a stacked panel — that one is a
+   * different action, and it is the only way out of depth ≥2.
+   */
+  hideClose?: boolean;
   /** Modal content */
   children?: ReactNode;
   /** Actions to display in the modal header (desktop) or footer (mobile) */
@@ -26,7 +40,7 @@ export interface StackedModalProps {
   /** Make modal full screen */
   fullScreen?: boolean;
   /** Maximum width of the modal */
-  maxWidth?: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | false;
+  maxWidth?: PanelMaxWidth;
   /** Disable the backdrop click behavior */
   disableBackdrop?: boolean;
   /** Disable focus trap functionality */
@@ -49,7 +63,7 @@ export interface ModalInfo {
   /** Z-index value for stacking */
   zIndex: number;
   /** Role in the modal stack */
-  role: 'primary' | 'secondary' | 'background';
+  role: ModalPanelRole;
 }
 
 export interface ModalStackContextValue {
@@ -66,5 +80,5 @@ export interface ModalStackContextValue {
   /** Check if a modal is in the stack */
   isModalInStack: (modalId: string) => boolean;
   /** Get the role of a modal in the stack */
-  getModalRole: (modalId: string) => 'primary' | 'secondary' | 'background' | null;
+  getModalRole: (modalId: string) => ModalPanelRole | null;
 }

package/src/components/feedback/StackedModal/__tests__/stacked-modal-viewport.test.tsx

@@ -0,0 +1,104 @@
+/**
+ * StackedModal on iOS: the slide-over panel is `position: fixed` and full-height,
+ * so it must be sized against the DYNAMIC viewport. With `100vh` the panel runs
+ * underneath the mobile browser toolbar, which leaves the tail of the scroll area
+ * — the "Criar produto" submit row — permanently out of reach: overscrolling to
+ * it rubber-bands and springs straight back.
+ */
+import { cleanup, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { StackedModal, StackedModalProvider } from "../index";
+
+/**
+ * Answers `max-width` media queries with `true` so `useMediaQuery` reports a
+ * phone — jsdom otherwise matches nothing and the modal always renders in its
+ * desktop shape (actions in the header, no bottom action bar).
+ */
+function stubPhoneViewport(): void {
+  vi.stubGlobal(
+    "matchMedia",
+    (query: string): MediaQueryList =>
+      ({
+        matches: query.includes("max-width"),
+        media: query,
+        onchange: null,
+        addListener: () => undefined,
+        removeListener: () => undefined,
+        addEventListener: () => undefined,
+        removeEventListener: () => undefined,
+        dispatchEvent: () => false,
+      }) as MediaQueryList,
+  );
+}
+
+/** All CSS emotion has injected into the document, as one searchable string. */
+function injectedCss(): string {
+  return Array.from(document.querySelectorAll("style"))
+    .map((tag) => {
+      // Emotion writes rules through the CSSOM in "speedy" mode, leaving the
+      // tag's text empty — read both shapes so this holds either way.
+      const fromRules = Array.from(tag.sheet?.cssRules ?? [])
+        .map((rule) => rule.cssText)
+        .join("");
+      return `${tag.textContent ?? ""}${fromRules}`;
+    })
+    .join("");
+}
+
+function renderModal(actions?: React.ReactNode): void {
+  render(
+    <StackedModalProvider>
+      <StackedModal
+        open
+        onClose={() => undefined}
+        navigationTitle="Novo produto"
+        modalId="viewport-spec"
+        dataTestId="viewport-modal"
+        actions={actions}
+      >
+        <div>corpo</div>
+      </StackedModal>
+    </StackedModalProvider>,
+  );
+}
+
+afterEach(() => {
+  cleanup();
+  vi.unstubAllGlobals();
+});
+
+describe("StackedModal viewport sizing", () => {
+  it("pins the panel to the dynamic viewport instead of a bare 100vh", async () => {
+    renderModal();
+    await screen.findByTestId("viewport-modal-header");
+
+    const css = injectedCss();
+    expect(css).toContain("100dvh");
+    // The dvh sizing must be guarded so browsers without dynamic viewport units
+    // still get the 100vh fallback rather than no height at all.
+    expect(css).toContain("@supports (height: 100dvh)");
+    expect(css).toContain("100vh");
+  });
+
+  it("lets the scroll area own its overscroll so it can't rubber-band the panel", async () => {
+    renderModal();
+    const content = await screen.findByTestId("viewport-modal-content");
+
+    expect(injectedCss()).toContain("overscroll-behavior:contain");
+    expect(content).toBeInTheDocument();
+  });
+
+  it("clears the home indicator under the mobile action bar", async () => {
+    stubPhoneViewport();
+    renderModal(<button type="button">Criar</button>);
+
+    // On a phone the actions move out of the header into a pinned bottom bar…
+    const footer = await screen.findByTestId("viewport-modal-footer");
+    expect(footer).toHaveTextContent("Criar");
+    // …which pads past its own 16px by the home-indicator inset.
+    expect(injectedCss()).toContain(
+      "max(16px, calc(16px + env(safe-area-inset-bottom)))",
+    );
+  });
+});

package/src/components/feedback/StackedModal/modal-stack.tsx

@@ -0,0 +1,119 @@
+import type { FC, ReactNode } from 'react';
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState } from 'react';
+import type { ModalInfo, ModalPanelRole, ModalStackContextValue } from './StackedModal.types';
+
+/** MUI Dialog default z-index; each panel in the stack sits 10 above the last. */
+const BASE_Z_INDEX = 1300;
+const Z_INDEX_STEP = 10;
+
+const noop = (): void => {
+  /** do nothing */
+};
+
+const ModalStackContext = createContext<ModalStackContextValue>({
+  stack: [],
+  pushModal: noop,
+  popModal: noop,
+  clearStack: noop,
+  currentDepth: 0,
+  isModalInStack: () => false,
+  getModalRole: () => null,
+});
+
+export const useModalStack = (): ModalStackContextValue => {
+  const context = useContext(ModalStackContext);
+  if (!context) {
+    throw new Error('useModalStack must be used within a ModalStackProvider');
+  }
+  return context;
+};
+
+/** Top of the stack drives the view; the one behind it recedes; the rest are hidden. */
+const roleAt = (index: number, depth: number): ModalPanelRole => {
+  if (index === depth - 1) return 'primary';
+  if (index === depth - 2) return 'secondary';
+  return 'background';
+};
+
+/** Re-derive every role from stack position — the one place roles are assigned. */
+const withRoles = (stack: ModalInfo[]): ModalInfo[] =>
+  stack.map((modal, index) => ({ ...modal, role: roleAt(index, stack.length) }));
+
+/**
+ * Locks body scroll while any modal is open, restoring whatever the page had
+ * before. Owned by the provider rather than each modal, so nested panels can't
+ * fight over the same style.
+ */
+const useBodyScrollLock = (locked: boolean): void => {
+  const originalOverflow = useRef<string>('');
+
+  useEffect(() => {
+    const restore = (): void => {
+      if (!originalOverflow.current) return;
+      document.body.style.overflow = originalOverflow.current;
+      originalOverflow.current = '';
+    };
+
+    if (locked) {
+      if (!originalOverflow.current) {
+        originalOverflow.current = document.body.style.overflow || '';
+      }
+      document.body.style.overflow = 'hidden';
+    } else {
+      restore();
+    }
+
+    return restore;
+  }, [locked]);
+};
+
+export const ModalStackProvider: FC<{ children: ReactNode }> = ({ children }) => {
+  const [stack, setStack] = useState<ModalInfo[]>([]);
+
+  useBodyScrollLock(stack.length > 0);
+
+  const pushModal = useCallback((modalId: string) => {
+    setStack((prev) => {
+      if (prev.some((m) => m.id === modalId)) return prev;
+      const entry: ModalInfo = {
+        id: modalId,
+        zIndex: BASE_Z_INDEX + prev.length * Z_INDEX_STEP,
+        role: 'primary',
+      };
+      return withRoles([...prev, entry]);
+    });
+  }, []);
+
+  const popModal = useCallback((modalId?: string) => {
+    setStack((prev) =>
+      withRoles(modalId ? prev.filter((m) => m.id !== modalId) : prev.slice(0, -1)),
+    );
+  }, []);
+
+  const clearStack = useCallback(() => setStack([]), []);
+
+  const isModalInStack = useCallback(
+    (modalId: string) => stack.some((m) => m.id === modalId),
+    [stack],
+  );
+
+  const getModalRole = useCallback(
+    (modalId: string) => stack.find((m) => m.id === modalId)?.role ?? null,
+    [stack],
+  );
+
+  const value = useMemo(
+    () => ({
+      stack,
+      pushModal,
+      popModal,
+      clearStack,
+      currentDepth: stack.length,
+      isModalInStack,
+      getModalRole,
+    }),
+    [stack, pushModal, popModal, clearStack, isModalInStack, getModalRole],
+  );
+
+  return <ModalStackContext.Provider value={value}>{children}</ModalStackContext.Provider>;
+};

package/src/components/feedback/Toast/Toast.tsx

@@ -1,10 +1,9 @@
-import {
-  CheckCircle as SuccessIcon,
-  Close as CloseIcon,
-  Error as ErrorIcon,
-  Info as InfoIcon,
-  Warning as WarningIcon,
-} from '@mui/icons-material';
+import SuccessIcon from '@mui/icons-material/CheckCircle';
+import CloseIcon from '@mui/icons-material/Close';
+import ErrorIcon from '@mui/icons-material/Error';
+import InfoIcon from '@mui/icons-material/Info';
+import WarningIcon from '@mui/icons-material/Warning';
+import type { Theme } from '@mui/material';
 import {
   Alert,
   alpha,
@@ -23,6 +22,46 @@ import type { ToastContainerProps, ToastContextType, ToastItem,ToastProps } from
 
 const ToastContext = createContext<ToastContextType | null>(null);
 
+type PromiseToastOptions<T> = {
+  loading: string;
+  success: string | ((data: T) => string);
+  error: string | ((error: unknown) => string);
+};
+
+// success/error may be a literal or a formatter over the settled value.
+const resolveToastMessage = <T,>(message: string | ((value: T) => string), value: T): string =>
+  typeof message === 'function' ? message(value) : message;
+
+// Shows a persistent "loading" toast for the life of a promise, then swaps it
+// for a success or error one. Lives outside the provider so the provider body
+// stays readable; it takes add/remove rather than reaching for context.
+const trackPromiseWithToasts = async <T,>(
+  promiseToResolve: Promise<T>,
+  options: PromiseToastOptions<T>,
+  addToast: (toast: Omit<ToastProps, 'id'>) => string,
+  removeToast: (id: string) => void,
+): Promise<T> => {
+  const toastId = addToast({
+    message: options.loading,
+    variant: 'promise',
+    persistent: true,
+  });
+
+  try {
+    const data = await promiseToResolve;
+
+    removeToast(toastId);
+    addToast({ message: resolveToastMessage(options.success, data), variant: 'success' });
+
+    return data;
+  } catch (error) {
+    removeToast(toastId);
+    addToast({ message: resolveToastMessage(options.error, error), variant: 'error' });
+
+    throw error;
+  }
+};
+
 export const ToastProvider: React.FC<{ children: React.ReactNode }> = ({ children }) => {
   const [toasts, setToasts] = useState<ToastItem[]>([]);
 
@@ -58,40 +97,8 @@ export const ToastProvider: React.FC<{ children: React.ReactNode }> = ({ childre
   }, []);
 
   const promise = useCallback(
-    async <T,>(
-      promiseToResolve: Promise<T>,
-      options: {
-        loading: string;
-        success: string | ((data: T) => string);
-        error: string | ((error: unknown) => string);
-      },
-    ): Promise<T> => {
-      const toastId = addToast({
-        message: options.loading,
-        variant: 'promise',
-        persistent: true,
-      });
-
-      try {
-        const data = await promiseToResolve;
-
-        removeToast(toastId);
-        addToast({
-          message: typeof options.success === 'function' ? options.success(data) : options.success,
-          variant: 'success',
-        });
-
-        return data;
-      } catch (error) {
-        removeToast(toastId);
-        addToast({
-          message: typeof options.error === 'function' ? options.error(error) : options.error,
-          variant: 'error',
-        });
-
-        throw error;
-      }
-    },
+    <T,>(promiseToResolve: Promise<T>, options: PromiseToastOptions<T>): Promise<T> =>
+      trackPromiseWithToasts(promiseToResolve, options, addToast, removeToast),
     [addToast, removeToast],
   );
 
@@ -114,6 +121,47 @@ export const useToast = (): ToastContextType => {
   return context;
 };
 
+const renderVariantIcon = (variant: ToastProps['variant']) => {
+  switch (variant) {
+    case 'success':
+      return <SuccessIcon />;
+    case 'error':
+      return <ErrorIcon />;
+    case 'warning':
+      return <WarningIcon />;
+    case 'info':
+      return <InfoIcon />;
+    case 'promise':
+      return <CircularProgress size={20} />;
+    default:
+      return null;
+  }
+};
+
+// 'default' and 'promise' have no MUI severity of their own; both read as info.
+const toAlertSeverity = (variant: ToastProps['variant']) =>
+  variant === 'default' || variant === 'promise' ? 'info' : variant;
+
+const buildToastStyles = (theme: Theme, glass: boolean) => {
+  const baseStyles = {
+    borderRadius: theme.spacing(1.5),
+    transition: theme.transitions.create(['background-color', 'backdrop-filter'], {
+      duration: theme.transitions.duration.standard,
+    }),
+  };
+
+  if (glass) {
+    return {
+      ...baseStyles,
+      backgroundColor: alpha(theme.palette.background.paper, 0.1),
+      backdropFilter: 'blur(20px)',
+      border: `1px solid ${alpha(theme.palette.primary.main, 0.2)}`,
+    };
+  }
+
+  return baseStyles;
+};
+
 export const Toast: React.FC<ToastProps> = ({
   id = '',
   message,
@@ -126,43 +174,6 @@ export const Toast: React.FC<ToastProps> = ({
 }) => {
   const theme = useTheme();
 
-  const getIcon = () => {
-    switch (variant) {
-      case 'success':
-        return <SuccessIcon />;
-      case 'error':
-        return <ErrorIcon />;
-      case 'warning':
-        return <WarningIcon />;
-      case 'info':
-        return <InfoIcon />;
-      case 'promise':
-        return <CircularProgress size={20} />;
-      default:
-        return null;
-    }
-  };
-
-  const getVariantStyles = () => {
-    const baseStyles = {
-      borderRadius: theme.spacing(1.5),
-      transition: theme.transitions.create(['background-color', 'backdrop-filter'], {
-        duration: theme.transitions.duration.standard,
-      }),
-    };
-
-    if (glass) {
-      return {
-        ...baseStyles,
-        backgroundColor: alpha(theme.palette.background.paper, 0.1),
-        backdropFilter: 'blur(20px)',
-        border: `1px solid ${alpha(theme.palette.primary.main, 0.2)}`,
-      };
-    }
-
-    return baseStyles;
-  };
-
   const handleClose = () => {
     if (onClose && id) {
       onClose(id);
@@ -172,8 +183,8 @@ export const Toast: React.FC<ToastProps> = ({
   return (
     <Alert
       data-testid={dataTestId}
-      icon={getIcon()}
-      severity={variant === 'default' || variant === 'promise' ? 'info' : variant}
+      icon={renderVariantIcon(variant)}
+      severity={toAlertSeverity(variant)}
       onClose={closable ? handleClose : undefined}
       action={
         <Box sx={{ display: 'flex', alignItems: 'center', gap: 1 }}>
@@ -200,7 +211,7 @@ export const Toast: React.FC<ToastProps> = ({
           )}
         </Box>
       }
-      sx={getVariantStyles()}
+      sx={buildToastStyles(theme, glass)}
     >
       <Typography data-testid={`${dataTestId}-message`} variant="body2">{message}</Typography>
     </Alert>

package/src/components/feedback/TutorialOverlay/TutorialOverlay.geometry.ts

@@ -0,0 +1,65 @@
+const DEFAULT_PADDING = 16;
+
+export const getElementBounds = (selector: string): globalThis.DOMRect | null =>
+  document.querySelector(selector)?.getBoundingClientRect() ?? null;
+
+// With placement 'auto', the side with the most free space around the target
+// wins.
+const pickPlacement = (targetBounds: globalThis.DOMRect): string => {
+  const spaces = {
+    top: targetBounds.top,
+    bottom: window.innerHeight - targetBounds.bottom,
+    left: targetBounds.left,
+    right: window.innerWidth - targetBounds.right,
+  };
+
+  return Object.entries(spaces).reduce((a, b) => (b[1] > a[1] ? b : a))[0];
+};
+
+const offsetFor = (
+  placement: string,
+  targetBounds: globalThis.DOMRect,
+  tooltipBounds: globalThis.DOMRect,
+  padding: number,
+): { top: number; left: number } => {
+  const centredLeft = targetBounds.left + targetBounds.width / 2 - tooltipBounds.width / 2;
+  const centredTop = targetBounds.top + targetBounds.height / 2 - tooltipBounds.height / 2;
+
+  switch (placement) {
+    case 'top':
+      return { top: targetBounds.top - tooltipBounds.height - padding, left: centredLeft };
+    case 'bottom':
+      return { top: targetBounds.bottom + padding, left: centredLeft };
+    case 'left':
+      return { top: centredTop, left: targetBounds.left - tooltipBounds.width - padding };
+    case 'right':
+      return { top: centredTop, left: targetBounds.right + padding };
+    default:
+      return { top: 0, left: 0 };
+  }
+};
+
+// Keeps the tooltip fully on screen, whatever the chosen side works out to.
+const clampToViewport = (
+  position: { top: number; left: number },
+  tooltipBounds: globalThis.DOMRect,
+  padding: number,
+) => ({
+  top: Math.max(padding, Math.min(position.top, window.innerHeight - tooltipBounds.height - padding)),
+  left: Math.max(padding, Math.min(position.left, window.innerWidth - tooltipBounds.width - padding)),
+});
+
+export const calculateTooltipPosition = (
+  targetBounds: globalThis.DOMRect,
+  tooltipBounds: globalThis.DOMRect,
+  placement: string,
+  padding = DEFAULT_PADDING,
+) => {
+  const finalPlacement = placement === 'auto' ? pickPlacement(targetBounds) : placement;
+  const offset = offsetFor(finalPlacement, targetBounds, tooltipBounds, padding);
+
+  return {
+    position: clampToViewport(offset, tooltipBounds, padding),
+    placement: finalPlacement,
+  };
+};