@eocrm/design-system 0.0.0-stage → 0.6.18

package/src/components/Modal/ModalRoot.tsx

@@ -0,0 +1,299 @@
+import {
+  useCallback,
+  useEffect,
+  useId,
+  useLayoutEffect,
+  useRef,
+  useState,
+  type CSSProperties,
+  type ReactNode,
+  type RefObject,
+} from 'react';
+import {
+  ModalContext,
+  type ModalContextValue,
+  type ModalOverlayVariant,
+  type ModalSize,
+} from './context';
+import {
+  isFocusLost,
+  restoreFocusTo,
+  useOverlayStack as useModalStack,
+  type OverlayStackMode as ModalStackMode,
+} from '../_internal/overlay';
+import { useScrollLock } from '../_internal/overlay/useScrollLock';
+import { Overlay } from './Overlay';
+import { Content } from './Content';
+import { sanitizeId } from '../_internal/refs';
+
+export interface ModalProps {
+  /** Controlled open state. Required. */
+  open: boolean;
+  /** Fired when Modal wants to change open state — Esc, overlay click, Close button, programmatic. */
+  onOpenChange: (open: boolean) => void;
+
+  /**
+   * Size preset. Defaults to `'md'`.
+   * - `'sm'` (400px) — confirms and short prompts.
+   * - `'md'` (560px) — the default; typical forms.
+   * - `'lg'` (800px) — wide forms, tables, previews.
+   * - `'full'` (95vw × 90dvh, fixed height) — long documents, e.g. an HTML email.
+   * See {@link ModalSize}.
+   * @default 'md'
+   */
+  size?: ModalSize;
+
+  /**
+   * Overlay variant. 'solid' (default) paints a dark dimming layer.
+   * 'blur' uses a light tinted background plus `backdrop-filter: blur(4px)`
+   * for a frosted-glass effect. 'blur' costs an extra compositor layer —
+   * fine for normal use; avoid stacking three blurred modals at once.
+   */
+  overlay?: ModalOverlayVariant;
+
+  /**
+   * How this modal relates to existing modals in the stack when it opens.
+   *
+   * - `'overlay'` (default): if there's a modal below this one, it stays
+   *   visible underneath. This modal's own overlay paints transparent so
+   *   the parent's dim shows through. Only the bottom modal (depth 0)
+   *   paints the actual dim/blur. The user sees the parent's context behind
+   *   the active modal.
+   * - `'replace'`: any modals below this one are hidden via `display: none`
+   *   (React state preserved). This modal paints its own overlay normally.
+   *   Best for forced-step modals where the parent context is irrelevant.
+   *
+   * Has no effect when this is the only open modal.
+   */
+  stackMode?: ModalStackMode;
+
+  /**
+   * Disable Escape-to-close. Default false. Combined with `dismissOnOverlayClick: false`
+   * and omitting `<Modal.Close>` produces a fully forced step.
+   */
+  disableEscapeClose?: boolean;
+  /**
+   * When false, clicking the overlay backdrop does NOT close the modal. Default true.
+   */
+  dismissOnOverlayClick?: boolean;
+
+  /**
+   * Initial focus target on open. Default: the dialog container itself.
+   * Pass a ref to override (e.g. focus the first input in a form).
+   */
+  initialFocusRef?: RefObject<HTMLElement | null>;
+
+  /**
+   * Where focus goes when the modal closes. Default: back to whatever was
+   * focused when it opened.
+   *
+   * That default breaks whenever the opener is gone by close time — a row's
+   * "⋯" trigger whose row was just deleted, or a button that unmounts in the
+   * same commit that opens the modal (the capture then snapshots `<body>`).
+   * Focus lands on `<body>` and a keyboard user loses their place.
+   *
+   * The ref is read **at close time**, not at open time, so it may be pointed
+   * at whatever still exists once the work is done — the next row's trigger,
+   * the empty state's first button. If it is empty or its element has also
+   * left the document, Modal falls back to the captured opener, and then to
+   * doing nothing, exactly as before this prop existed.
+   *
+   * The target is scrolled into view (`block: 'nearest'`) after focus; the
+   * captured opener is not.
+   *
+   * @example
+   * // The deleted row's trigger is gone on close; aim at the next one.
+   * const returnFocusRef = useRef<HTMLElement | null>(null);
+   * <Modal open={open} onOpenChange={setOpen} returnFocusRef={returnFocusRef}>
+   *   <Modal.Header>Delete mailbox?</Modal.Header>
+   *   <Modal.Footer>
+   *     <Button
+   *       variant="danger"
+   *       onClick={async () => {
+   *         await deleteMailbox(id);
+   *         returnFocusRef.current = nextRowTriggerRef.current ?? connectButtonRef.current;
+   *         setOpen(false);
+   *       }}
+   *     >
+   *       Delete
+   *     </Button>
+   *   </Modal.Footer>
+   * </Modal>
+   */
+  returnFocusRef?: RefObject<HTMLElement | null>;
+
+  /** Compound children: Header / Body / Footer / Close + any consumer JSX. */
+  children: ReactNode;
+
+  /** className passes through to the dialog container. */
+  className?: string;
+  /** style passes through to the dialog container. */
+  style?: CSSProperties;
+
+  /**
+   * Required for a11y when no Modal.Header is rendered. When Header IS rendered,
+   * aria-labelledby auto-binds to the heading id; this prop is then ignored.
+   */
+  'aria-label'?: string;
+  /** Optional id of an external descriptor element; sets aria-describedby on the dialog. */
+  'aria-describedby'?: string;
+}
+
+/**
+ * Modal dialog: focus-locked, scroll-locked, ARIA-correct overlay panel with stack-aware overlays; controlled `open`.
+ * @see docs/components/Modal.md
+ */
+export function ModalRoot({
+  open,
+  onOpenChange,
+  size = 'md',
+  overlay = 'solid',
+  stackMode = 'overlay',
+  disableEscapeClose = false,
+  dismissOnOverlayClick = true,
+  initialFocusRef,
+  returnFocusRef,
+  children,
+  className,
+  style,
+  'aria-label': ariaLabel,
+  'aria-describedby': ariaDescribedBy,
+}: ModalProps) {
+  const rawId = useId();
+  const modalId = `modal-${sanitizeId(rawId)}`;
+
+  const contentRef = useRef<HTMLDivElement | null>(null);
+  const [headingId, setHeadingId] = useState<string | null>(null);
+
+  // previouslyFocused: capture the trigger element when transitioning false → true,
+  // then restore focus to it on close.
+  //
+  // useLayoutEffect is required here (not useEffect) for two reasons:
+  //
+  // 1. Capture timing: Content.tsx uses queueMicrotask inside its useLayoutEffect
+  //    to move focus to the dialog. This layout effect runs in the same commit
+  //    before that queued work, so it captures the trigger while it still has focus.
+  //
+  // 2. Close timing: on an open → closed update, React completes layout-effect
+  //    cleanup (including useScrollLock's unlock) before running the closed-state
+  //    layout effects that restore focus. preventScroll then avoids disturbing the
+  //    restored position.
+  const previouslyFocusedRef = useRef<HTMLElement | null>(null);
+  const prevOpenRef = useRef(false);
+  const focusEffectGenerationRef = useRef(0);
+  // A consumer-named target wins over the captured opener, and is read HERE —
+  // at close time — so the consumer can aim it at whatever survived the work
+  // the modal did (#529). Both are checked against the document: the opener is
+  // commonly gone (deleted row, unmounted button), and the named target can be
+  // too, in which case the captured opener is still the better answer than
+  // nothing.
+  const restoreFocus = useCallback(() => {
+    const captured = previouslyFocusedRef.current;
+    previouslyFocusedRef.current = null;
+    const requested = returnFocusRef?.current ?? null;
+    if (requested && document.contains(requested)) {
+      restoreFocusTo(requested);
+      // #553: a named target is usually NOT where the user was (the opener
+      // unmounted), so bring it into view. 'nearest' is a no-op when visible.
+      // The captured opener is not scrolled — the user was already there.
+      requested.scrollIntoView?.({ block: 'nearest' });
+      return;
+    }
+    if (captured && document.contains(captured)) {
+      restoreFocusTo(captured);
+    }
+  }, [returnFocusRef]);
+  useLayoutEffect(() => {
+    const generation = ++focusEffectGenerationRef.current;
+    if (open && !prevOpenRef.current) {
+      // Modal is opening: snapshot the currently focused element before the
+      // dialog's queueMicrotask fires and steals focus.
+      previouslyFocusedRef.current = (document.activeElement as HTMLElement | null) ?? null;
+    }
+    if (!open && prevOpenRef.current) {
+      // Modal is closing: restore focus to the element that triggered it.
+      // preventScroll keeps the browser from scrollIntoView-ing the trigger,
+      // which would fight the scroll restoration in useScrollLock's cleanup.
+      restoreFocus();
+    }
+    prevOpenRef.current = open;
+    // Also restore if the Modal root itself is removed while still open. Defer
+    // until React finishes tearing down the dialog and its focus trap.
+    //
+    // This cleanup and the closing branch can run for the same transition;
+    // a later effect generation cancels this queued fallback, while restoreFocus
+    // clears its ref first so the target is focused only once.
+    // Only when focus was actually lost — a consumer that focused something
+    // after the unmount (e.g. the next row) keeps it.
+    if (open) {
+      return () => {
+        queueMicrotask(() => {
+          // eslint-disable-next-line react-hooks/exhaustive-deps -- the generation counter must be read at cleanup time
+          if (focusEffectGenerationRef.current === generation && isFocusLost()) restoreFocus();
+        });
+      };
+    }
+  }, [open, restoreFocus]);
+
+  // Stack registration + scroll lock are driven by `open`.
+  const { depth, isTop, topMode } = useModalStack(modalId, open, stackMode);
+  useScrollLock(open);
+
+  const setOpen = useCallback(
+    (next: boolean) => {
+      onOpenChange(next);
+    },
+    [onOpenChange],
+  );
+
+  // Dev warning: must have either a Header (sets headingId in context) OR aria-label.
+  // Deferred via microtask so <Modal.Header>'s registration effect has a chance to run.
+  useEffect(() => {
+    if (!open) return;
+    if (process.env.NODE_ENV === 'production') return;
+    let cancelled = false;
+    queueMicrotask(() => {
+      if (cancelled) return;
+      if (!headingId && !ariaLabel) {
+        console.warn(
+          '<Modal> must be labelled. Either render <Modal.Header> or pass an `aria-label` prop. Screen-reader users get no announcement otherwise.',
+        );
+      }
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [open, headingId, ariaLabel]);
+
+  const value: ModalContextValue = {
+    open,
+    setOpen,
+    modalId,
+    contentRef,
+    headingId,
+    setHeadingId,
+    size,
+    overlay,
+    disableEscapeClose,
+    dismissOnOverlayClick,
+    initialFocusRef,
+    ariaLabel,
+    ariaDescribedBy,
+    depth: depth ?? 0,
+    isTop,
+    stackMode,
+    topMode,
+  };
+
+  return (
+    <ModalContext.Provider value={value}>
+      {open && (
+        <Overlay>
+          <Content className={className} style={style}>
+            {children}
+          </Content>
+        </Overlay>
+      )}
+    </ModalContext.Provider>
+  );
+}

package/src/components/Modal/Overlay.tsx

@@ -0,0 +1,101 @@
+import {
+  useEffect,
+  type CSSProperties,
+  type MouseEvent as ReactMouseEvent,
+  type ReactNode,
+} from 'react';
+import { createPortal } from 'react-dom';
+import { useModalContext } from './context';
+import styles from './Modal.module.scss';
+
+const PORTAL_EXEMPT_SELECTOR =
+  '[data-modal-portal-root], [data-drawer-portal-root], [data-tour-portal-root]';
+
+export interface OverlayProps {
+  children: ReactNode;
+}
+
+/**
+ * Portaled dimming/blurred backdrop rendered behind the dialog. Owns the
+ * inert-background attribute on body children + the overlay-click
+ * dismissal (only fires when the click target is the overlay itself,
+ * not bubbled from content).
+ *
+ * Carries three data-attributes consumed by SCSS:
+ * - `data-variant`        : 'solid' | 'blur' — visual variant
+ * - `data-stack-position` : 'top' | 'underneath' | 'hidden'
+ *     - 'top'       — this is the topmost open modal
+ *     - 'underneath' — lower modal in overlay-stack mode (stays visible)
+ *     - 'hidden'    — lower modal in replace-stack mode (display: none)
+ * - `data-overlay-paint`  : 'yes' | 'no'
+ *     - 'yes' — this overlay paints its dim/blur background
+ *     - 'no'  — transparent (upper modal in overlay-stack mode)
+ */
+export function Overlay({ children }: OverlayProps) {
+  const ctx = useModalContext('Overlay');
+
+  // Inert background — applied to all body children EXCEPT any modal portal
+  // root. Skipping ALL modal portals (not just the first) is critical for
+  // stacked modals: the inner modal's portal is also a body child, and it
+  // must remain interactive even though it was added after the outer's.
+  useEffect(() => {
+    if (!ctx.isTop) return;
+    const bodyChildren = Array.from(document.body.children) as HTMLElement[];
+    const toRestore: Array<{ el: HTMLElement; had: boolean }> = [];
+    for (const el of bodyChildren) {
+      if (el.matches(PORTAL_EXEMPT_SELECTOR)) continue;
+      const had = el.hasAttribute('inert');
+      if (!had) el.setAttribute('inert', '');
+      toRestore.push({ el, had });
+    }
+    return () => {
+      for (const { el, had } of toRestore) {
+        if (!had) el.removeAttribute('inert');
+      }
+    };
+  }, [ctx.isTop]);
+
+  const onClick = (e: ReactMouseEvent<HTMLDivElement>) => {
+    // Only dismiss when the click is on the backdrop itself.
+    if (e.target !== e.currentTarget) return;
+    if (!ctx.dismissOnOverlayClick) return;
+    if (!ctx.isTop) return; // safety: lower overlays are display:none, but guard anyway
+    ctx.setOpen(false);
+  };
+
+  // Visibility classification
+  let stackPosition: 'top' | 'hidden' | 'underneath';
+  if (ctx.isTop) {
+    stackPosition = 'top';
+  } else if (ctx.topMode === 'replace') {
+    stackPosition = 'hidden';
+  } else {
+    // topMode === 'overlay' && !isTop
+    stackPosition = 'underneath';
+  }
+
+  // Paint classification: only paint dim/blur if this is the visible "ground
+  // level". In replace mode the top modal paints; in overlay mode only the
+  // bottom of the stack (depth 0) paints so upper overlays are transparent.
+  const paint =
+    (ctx.topMode === 'replace' && ctx.isTop) || (ctx.topMode === 'overlay' && ctx.depth === 0);
+
+  // Custom prop carries depth to SCSS for any per-depth styling.
+  const style = { ['--modal-depth' as string]: String(ctx.depth) } as CSSProperties;
+
+  return createPortal(
+    <div
+      data-modal-portal-root=""
+      data-state={ctx.open ? 'open' : 'closed'}
+      data-variant={ctx.overlay}
+      data-stack-position={stackPosition}
+      data-overlay-paint={paint ? 'yes' : 'no'}
+      className={styles.overlay}
+      style={style}
+      onClick={onClick}
+    >
+      {children}
+    </div>,
+    document.body,
+  );
+}

package/src/components/Modal/context.ts

@@ -0,0 +1,60 @@
+import { createContext, useContext, type RefObject } from 'react';
+import type { OverlayStackMode } from '../_internal/overlay';
+
+/** @deprecated alias of {@link OverlayStackMode}. Kept for backward compatibility. */
+export type ModalStackMode = OverlayStackMode;
+
+/**
+ * Size preset. `'sm'` / `'md'` / `'lg'` are fixed widths (400 / 560 / 800px)
+ * whose height grows with content. `'full'` is near-full-screen — 95vw × 90dvh
+ * unless `--modal-content-width-full` / `--modal-content-height-full` are
+ * overridden — a FIXED height whatever the content, with Body scrolling between a pinned
+ * Header and Footer — for reading long documents (an HTML email, a report).
+ * Every size goes full-screen below a 640px viewport.
+ */
+export type ModalSize = 'sm' | 'md' | 'lg' | 'full';
+export type ModalOverlayVariant = 'solid' | 'blur';
+
+export interface ModalContextValue {
+  open: boolean;
+  setOpen: (next: boolean) => void;
+  /** Stable modal id, used by the stack registry + aria-controls bindings. */
+  modalId: string;
+  /** Ref to the dialog container, populated by <Content>. Used for focus trap + outside-click. */
+  contentRef: RefObject<HTMLDivElement | null>;
+  /** Stable id for the heading registered by <Header>, used for aria-labelledby. */
+  headingId: string | null;
+  /** Called by <Header> to register its heading id. */
+  setHeadingId: (id: string | null) => void;
+  /** Size preset; drives the content's --modal-size CSS class. */
+  size: ModalSize;
+  /** Overlay variant; drives data-variant on the portal root. */
+  overlay: ModalOverlayVariant;
+  /** Forwarded from props for the Esc handler in Content. */
+  disableEscapeClose: boolean;
+  /** Forwarded for the overlay click handler. */
+  dismissOnOverlayClick: boolean;
+  /** Forwarded so Content can override initial focus. */
+  initialFocusRef: RefObject<HTMLElement | null> | undefined;
+  /** From Modal props; used by Content for aria-label when no heading is registered. */
+  ariaLabel: string | undefined;
+  ariaDescribedBy: string | undefined;
+  /** Current stack depth (for the --modal-depth custom prop on the overlay). */
+  depth: number;
+  /** Whether this modal is currently the topmost open modal. Drives Escape/focus-trap activity. */
+  isTop: boolean;
+  /** This modal's own stackMode prop. */
+  stackMode: ModalStackMode;
+  /** Mode of the current top modal (null if stack is empty). */
+  topMode: ModalStackMode | null;
+}
+
+export const ModalContext = createContext<ModalContextValue | null>(null);
+
+export function useModalContext(componentName: string): ModalContextValue {
+  const ctx = useContext(ModalContext);
+  if (!ctx) {
+    throw new Error(`<Modal.${componentName}> must be used inside <Modal>.`);
+  }
+  return ctx;
+}

package/src/components/Modal/index.ts

@@ -0,0 +1,11 @@
+export { Modal } from './Modal';
+export type {
+  ModalProps,
+  ModalSize,
+  ModalOverlayVariant,
+  ModalStackMode,
+  ModalHeaderProps,
+  ModalBodyProps,
+  ModalFooterProps,
+  ModalCloseProps,
+} from './Modal';

package/src/components/MoneyInput/MoneyInput.module.scss

@@ -0,0 +1,57 @@
+@use '../Input/Input.tokens';
+
+.root {
+  display: grid;
+  grid-template-columns: max-content minmax(0, 1fr);
+  gap: var(--space-1);
+  align-items: center;
+}
+
+.currency {
+  // keep the picker compact so the amount gets the room
+  max-width: var(--size-control-currency);
+}
+
+.amount {
+  width: 100%;
+  text-align: end;
+  font-variant-numeric: tabular-nums;
+}
+
+// Static currency prefix (single-currency mode): mirrors Input's chrome per size.
+.prefix {
+  display: inline-flex;
+  align-items: center;
+  border: var(--border-width) solid var(--input-border-color);
+  border-radius: var(--input-radius);
+  background: var(--input-bg-disabled);
+  color: var(--input-fg);
+  line-height: var(--input-line-height);
+}
+
+.prefix-sm {
+  height: var(--input-height-sm);
+  padding: 0 var(--input-padding-x-sm);
+  font-size: var(--input-font-size-sm);
+}
+
+.prefix-md {
+  height: var(--input-height-md);
+  padding: 0 var(--input-padding-x-md);
+  font-size: var(--input-font-size-md);
+}
+
+.prefix-lg {
+  height: var(--input-height-lg);
+  padding: 0 var(--input-padding-x-lg);
+  font-size: var(--input-font-size-lg);
+}
+
+.prefix-invalid {
+  border-color: var(--input-border-color-invalid);
+}
+
+.prefix-disabled {
+  border-color: var(--input-border-color-disabled);
+  color: var(--input-fg-disabled);
+}