@eocrm/design-system 0.0.0-stage → 0.6.17

package/src/components/Modal/Close.tsx

@@ -0,0 +1,45 @@
+import {
+  cloneElement,
+  isValidElement,
+  useCallback,
+  type MouseEvent as ReactMouseEvent,
+  type ReactElement,
+} from 'react';
+import { useModalContext } from './context';
+import { chain } from '../_internal/refs';
+
+export interface ModalCloseProps {
+  /**
+   * Exactly one React element. Close clones this element to inject an
+   * `onClick` that closes the modal, chained with the child's existing
+   * `onClick` (consumer runs first).
+   */
+  children: ReactElement;
+}
+
+/**
+ * Wraps a single clickable element so activating it closes the modal (`Modal.Close`).
+ * @see docs/components/Modal.md
+ */
+export function Close({ children }: ModalCloseProps) {
+  const ctx = useModalContext('Close');
+
+  if (!isValidElement(children)) {
+    throw new Error('<Modal.Close> requires exactly one React element child.');
+  }
+
+  const childProps = children.props as {
+    onClick?: (e: ReactMouseEvent<HTMLElement>) => void;
+  };
+
+  const handleClick = useCallback(
+    (_e: ReactMouseEvent<HTMLElement>) => {
+      ctx.setOpen(false);
+    },
+    [ctx],
+  );
+
+  return cloneElement(children, {
+    onClick: chain(childProps.onClick, handleClick),
+  } as object);
+}

package/src/components/Modal/Content.tsx

@@ -0,0 +1,98 @@
+import { useEffect, useLayoutEffect, useRef, type CSSProperties, type ReactNode } from 'react';
+import clsx from 'clsx';
+import { useModalContext } from './context';
+import { useFocusTrap } from '../_internal/overlay/useFocusTrap';
+import { isFocusLost, overlayStack as modalStack } from '../_internal/overlay';
+import styles from './Modal.module.scss';
+
+export interface ContentProps {
+  children?: ReactNode;
+  className?: string;
+  style?: CSSProperties;
+}
+
+/**
+ * Dialog container. `role="dialog"`, `aria-modal="true"`, tabIndex=-1 so
+ * the focus trap can take over. Owns:
+ * - Initial focus on open (either initialFocusRef or the container itself).
+ * - Focus trap (active only when this modal is top of the stack).
+ * - Escape capture-phase listener (also gated by isTop).
+ * - Renders the compound children (Header/Body/Footer/Close) inside the dialog.
+ */
+export function Content({ children, className, style }: ContentProps) {
+  const ctx = useModalContext('Content');
+  const { setOpen } = ctx;
+
+  // Initial focus on open. Try the ref first; if it points to a non-focusable
+  // node, the browser .focus() no-ops and the focusin recapture in
+  // useFocusTrap will bring focus back to the container.
+  //
+  // Initial focus belongs to the OPEN transition only. isTop also flips
+  // false → true when a nested overlay (e.g. a stacked Modal) closes;
+  // re-running here would queue a focus that lands AFTER the nested overlay
+  // restored focus to its opener / returnFocusRef (#551).
+  const initialFocusPendingRef = useRef(true);
+  useLayoutEffect(() => {
+    if (!ctx.open) {
+      initialFocusPendingRef.current = true;
+      return;
+    }
+    if (!ctx.isTop) return; // lower modals are display:none — focusing them would scroll
+    if (!initialFocusPendingRef.current) {
+      // Regained the top after a nested overlay closed. Its restore (and that
+      // restore's own retry, queued earlier) wins; only if focus is still
+      // lost — nothing to restore to — take it into this container (#551).
+      queueMicrotask(() => {
+        if (isFocusLost()) ctx.contentRef.current?.focus({ preventScroll: true });
+      });
+      return;
+    }
+    initialFocusPendingRef.current = false;
+    queueMicrotask(() => {
+      const target = ctx.initialFocusRef?.current ?? ctx.contentRef.current;
+      target?.focus({ preventScroll: true });
+    });
+  }, [ctx.open, ctx.isTop, ctx.initialFocusRef, ctx.contentRef]);
+
+  // Escape closes the topmost modal only. Capture-phase to beat focused
+  // widgets that stopPropagation on Esc (matches Popover).
+  useEffect(() => {
+    if (!ctx.open) return;
+    function onKeyDown(e: KeyboardEvent) {
+      if (e.key !== 'Escape') return;
+      if (!modalStack.isTop(ctx.modalId)) return;
+      // #274: an open floating surface (Select/Popover/menu/date-time popover/
+      // Rail flyout) wins this press — its own Escape handling (a capture
+      // listener or an element-scoped handler) closes it on this same press;
+      // wasEscapeConsumed covers a surface whose listener already ran. The
+      // next press reaches us.
+      if (modalStack.hasOpenFloating() || modalStack.wasEscapeConsumed(e)) return;
+      if (ctx.disableEscapeClose) return;
+      e.preventDefault();
+      setOpen(false);
+    }
+    document.addEventListener('keydown', onKeyDown, true);
+    return () => document.removeEventListener('keydown', onKeyDown, true);
+  }, [ctx.open, ctx.modalId, ctx.disableEscapeClose, setOpen]);
+
+  // Focus trap — active only when this modal is on top of the stack.
+  useFocusTrap(ctx.contentRef, ctx.open && ctx.isTop);
+
+  return (
+    <div
+      ref={ctx.contentRef}
+      role="dialog"
+      aria-modal="true"
+      aria-labelledby={ctx.headingId ?? undefined}
+      aria-label={!ctx.headingId ? ctx.ariaLabel : undefined}
+      aria-describedby={ctx.ariaDescribedBy}
+      tabIndex={-1}
+      data-state={ctx.open ? 'open' : 'closed'}
+      data-size={ctx.size}
+      className={clsx(styles.content, styles[`size-${ctx.size}`], className)}
+      style={style}
+    >
+      {children}
+    </div>
+  );
+}

package/src/components/Modal/Footer.tsx

@@ -0,0 +1,28 @@
+import { forwardRef, type HTMLAttributes } from 'react';
+import clsx from 'clsx';
+import styles from './Modal.module.scss';
+
+export interface ModalFooterProps extends HTMLAttributes<HTMLDivElement> {
+  /** Horizontal action alignment. Default 'end'. */
+  align?: 'start' | 'end' | 'space-between';
+}
+
+/**
+ * Pinned action bar at the bottom of the modal, announced as a `role="group"`.
+ * @see docs/components/Modal.md
+ */
+export const Footer = forwardRef<HTMLDivElement, ModalFooterProps>(function Footer(
+  { align = 'end', className, children, ...rest },
+  ref,
+) {
+  return (
+    <div
+      ref={ref}
+      role="group"
+      className={clsx(styles.footer, styles[`footerAlign-${align}`], className)}
+      {...rest}
+    >
+      {children}
+    </div>
+  );
+});

package/src/components/Modal/Header.tsx

@@ -0,0 +1,51 @@
+import { forwardRef, useEffect, useId, type HTMLAttributes } from 'react';
+import clsx from 'clsx';
+import { X } from 'lucide-react';
+import { Button } from '../Button';
+import { useTranslation } from '../../i18n/useTranslation';
+import { useModalContext } from './context';
+import { sanitizeId } from '../_internal/refs';
+import styles from './Modal.module.scss';
+
+export interface ModalHeaderProps extends HTMLAttributes<HTMLDivElement> {
+  /** Show the built-in × close button on the right edge. Default true. */
+  closeButton?: boolean;
+}
+
+/**
+ * Title bar at the top of the modal: names the dialog and shows a close button unless `closeButton={false}`.
+ * @see docs/components/Modal.md
+ */
+export const Header = forwardRef<HTMLDivElement, ModalHeaderProps>(function Header(
+  { closeButton = true, className, children, ...rest },
+  ref,
+) {
+  const t = useTranslation();
+  const ctx = useModalContext('Header');
+  const rawId = useId();
+  const headingId = `modal-heading-${sanitizeId(rawId)}`;
+
+  useEffect(() => {
+    ctx.setHeadingId(headingId);
+    return () => ctx.setHeadingId(null);
+  }, [ctx, headingId]);
+
+  return (
+    <div ref={ref} className={clsx(styles.header, className)} {...rest}>
+      <h2 id={headingId} className={styles.headerTitle}>
+        {children}
+      </h2>
+      {closeButton && (
+        <Button
+          variant="ghost"
+          size="xs"
+          iconOnly
+          aria-label={t('modal.close')}
+          onClick={() => ctx.setOpen(false)}
+        >
+          <X size={16} aria-hidden="true" />
+        </Button>
+      )}
+    </div>
+  );
+});

package/src/components/Modal/Modal.module.scss

@@ -0,0 +1,262 @@
+@use '../../styles/mixins' as *;
+@use './Modal.tokens';
+
+// ─── Overlay ────────────────────────────────────────────────────────────
+// Dimming / blurred backdrop. Portaled directly inside <body>. Fills the
+// viewport, centers the content via flex. The --modal-depth custom prop
+// (set by Overlay.tsx) is available for any per-depth styling — but with
+// the display-toggle stacking model, at most one overlay is visible at a
+// time, so depth-aware z-index ordering is largely a no-op.
+
+// stylelint-disable property-disallowed-list -- internal positioning, not consumer layout
+.overlay {
+  // stylelint-disable-next-line declaration-property-value-disallowed-list -- overlay must be fixed to fill viewport
+  position: fixed;
+
+  // Explicit top/left/width/height instead of `inset: 0` so that the dvw/dvh
+  // fallback pair can be written for width and height independently. On iOS
+  // Safari, `inset: 0` anchors to the layout viewport; using dvw/dvh tracks
+  // the *dynamic* viewport (accounts for collapsing address bar) and prevents
+  // the overlay from being smaller than the visible area.
+  top: 0;
+  left: 0;
+
+  // vw/vh first as a fallback for browsers without dvw/dvh support (Safari < 15.4).
+  width: 100vw;
+  width: 100dvw;
+  height: 100vh;
+  height: 100dvh;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: var(--modal-overlay-bg);
+  z-index: calc(var(--modal-overlay-z) + var(--modal-depth, 0) * 2);
+  opacity: var(--modal-overlay-opacity-visible);
+  transition: opacity var(--modal-overlay-transition);
+
+  // Prevent touch-scroll chaining from modal body scrolling to the document.
+  overscroll-behavior: contain;
+
+  // Hint the browser to put this on its own compositor layer before the
+  // animation starts — opacity fades become smooth from frame 1.
+  will-change: opacity;
+
+  // Isolate paint + layout so opening doesn't invalidate sibling trees.
+  contain: layout paint;
+
+  @starting-style {
+    opacity: var(--modal-overlay-opacity-hidden);
+  }
+}
+
+.overlay[data-state='closed'] {
+  opacity: var(--modal-overlay-opacity-hidden);
+}
+
+// Stacked-modal display model: lower overlays are hidden via display:none
+// while a deeper modal is open in replace mode. React state stays intact.
+.overlay[data-stack-position='hidden'] {
+  display: none;
+}
+
+// Frosted-glass variant. Light tinted background + backdrop-filter for the
+// glass effect. -webkit prefix for Safari < 18.
+.overlay[data-variant='blur'] {
+  background: var(--modal-overlay-bg-blur);
+  // stylelint-disable-next-line scale-unlimited/declaration-strict-value
+  backdrop-filter: blur(4px);
+  // stylelint-disable-next-line property-no-vendor-prefix, scale-unlimited/declaration-strict-value -- Safari < 18 requires the prefix
+  -webkit-backdrop-filter: blur(4px);
+}
+
+// In overlay-stack mode, only the bottom of the stack paints the dim/blur.
+// Upper modals' overlays are transparent so the parent's dim shows through.
+// This rule intentionally appears AFTER the blur variant so source order
+// makes it win on background and backdrop-filter.
+.overlay[data-overlay-paint='no'] {
+  background: transparent;
+  backdrop-filter: none;
+  // stylelint-disable-next-line property-no-vendor-prefix -- Safari < 18 mirror
+  -webkit-backdrop-filter: none;
+}
+// stylelint-enable property-disallowed-list
+
+// ─── Content (dialog) ───────────────────────────────────────────────────
+// The dialog box itself. Flex column so Header/Body/Footer stack with the
+// Body taking remaining height (scrollable when overflowing).
+
+// stylelint-disable property-disallowed-list -- internal positioning, not consumer layout
+.content {
+  // position: relative establishes a containing block for any
+  // absolutely-positioned descendants consumers render inside the modal
+  // (e.g., a floating tag inside Modal.Body). Without this, those
+  // descendants would position relative to the overlay (position:fixed).
+  position: relative;
+
+  // Size-variant tokens consumed by sub-component rules below. .size-sm
+  // overrides these to tighter values. Routing through custom props keeps
+  // each sub-component rule at single-class specificity (0,1,0), so a
+  // consumer-supplied className on e.g. <Modal.Header> can always win.
+  --modal-pad: var(--modal-content-padding-default);
+  --modal-title-size: var(--modal-title-size-default);
+
+  display: flex;
+  flex-direction: column;
+  background: var(--modal-bg);
+  border-radius: var(--modal-radius);
+  box-shadow: var(--modal-shadow);
+  z-index: calc(var(--modal-overlay-z) + var(--modal-depth, 0) * 2 + 1);
+  max-height: calc(100vh - 64px);
+  max-height: calc(100dvh - 64px);
+  width: min(100% - 32px, var(--modal-width, var(--modal-content-width-md)));
+  opacity: var(--modal-opacity-visible);
+  transform: translateY(0) scale(1);
+  transition:
+    opacity var(--modal-transition),
+    transform var(--modal-transition);
+
+  // Promote to its own compositor layer so opacity + transform animate
+  // on the GPU from the first frame, not after a paint upgrade.
+  will-change: opacity, transform;
+
+  // Isolate paint + layout — the modal doesn't affect parent layout.
+  contain: layout paint;
+
+  @starting-style {
+    opacity: var(--modal-opacity-hidden);
+    transform: translateY(8px) scale(0.96);
+  }
+}
+
+.content[data-state='closed'] {
+  opacity: var(--modal-opacity-hidden);
+  transform: translateY(8px) scale(0.96);
+}
+// stylelint-enable property-disallowed-list
+
+// Size presets — each one sets --modal-width which `.content` consumes via
+// the `min(100% - 32px, var(--modal-width, ...))` clamp above. Using a custom
+// prop keeps the size logic in one place.
+.size-sm {
+  --modal-width: var(--modal-content-width-sm);
+  --modal-pad: var(--modal-content-padding-sm);
+  --modal-title-size: var(--modal-title-size-sm);
+}
+
+.size-md {
+  --modal-width: var(--modal-content-width-md);
+}
+
+.size-lg {
+  --modal-width: var(--modal-content-width-lg);
+}
+
+// Fixed height so Header/Footer stay put and Body (flex: 1 1 auto,
+// overflow-y: auto) scrolls. Same 0,1,0 specificity as `.content`, so the
+// mobile rule below (later in source) still takes it to 100dvh.
+.size-full {
+  --modal-width: var(--modal-content-width-full);
+
+  height: var(--modal-content-height-full);
+}
+
+// ─── Header ─────────────────────────────────────────────────────────────
+
+.header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--modal-header-gap);
+  padding: var(--modal-pad);
+  border-bottom: var(--border-width) solid var(--modal-header-border-color);
+}
+
+.headerTitle {
+  // stylelint-disable-next-line property-disallowed-list -- reset browser default h2 margin; internal to component
+  margin: 0;
+  font-size: var(--modal-title-size);
+  font-weight: var(--modal-header-title-font-weight);
+  color: var(--modal-header-title-fg);
+}
+
+// ─── Body ───────────────────────────────────────────────────────────────
+
+.body {
+  padding: var(--modal-pad);
+  overflow-y: auto;
+  flex: 1 1 auto;
+
+  // Stop scroll chaining: when modal body content reaches its scroll bounds,
+  // do not propagate the scroll gesture to the overlay or the document.
+  overscroll-behavior: contain;
+}
+
+.bodyPaddingNone {
+  padding: 0;
+}
+
+// ─── Footer ─────────────────────────────────────────────────────────────
+
+.footer {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--modal-footer-gap);
+  padding: var(--modal-pad);
+  border-top: var(--border-width) solid var(--modal-footer-border-color);
+}
+
+.footerAlign-start {
+  justify-content: flex-start;
+}
+
+.footerAlign-end {
+  justify-content: flex-end;
+}
+
+.footerAlign-space-between {
+  justify-content: space-between;
+}
+
+// ─── Mobile fullscreen breakpoint ───────────────────────────────────────
+
+// stylelint-disable property-disallowed-list -- internal layout for narrow viewports
+@media (max-width: 640px) {
+  // Anchor content to the top of the overlay so iOS Safari's collapsing address
+  // bar can't push it off-screen. Centering is meaningless when content fills
+  // the full viewport anyway.
+  .overlay {
+    align-items: flex-start;
+  }
+
+  .content {
+    // vw/vh fallbacks for browsers that don't support dvw/dvh (Safari < 15.4).
+    // dvw/dvh track the *actual* visible viewport; on iOS Safari, 100vh is the
+    // "large viewport" (address bar hidden) which is taller than what's visible
+    // when the address bar is shown — causing the modal to overflow.
+    width: 100vw;
+    width: 100dvw;
+    height: 100vh;
+    height: 100dvh;
+    max-width: 100vw;
+    max-width: 100dvw;
+    max-height: 100vh;
+    max-height: 100dvh;
+    border-radius: 0;
+  }
+}
+// stylelint-enable property-disallowed-list
+
+// ─── Reduced motion ─────────────────────────────────────────────────────
+
+@media (prefers-reduced-motion: reduce) {
+  .overlay,
+  .content {
+    transition: none;
+
+    @starting-style {
+      opacity: var(--modal-opacity-visible);
+      transform: none;
+    }
+  }
+}

package/src/components/Modal/Modal.tokens.scss

@@ -0,0 +1,50 @@
+// Modal.tokens.scss — Component-scoped tokens for <Modal>. Each token defaults to the primitive the SCSS used before this migration. Note: Modal.module.scss also declares internal routing vars (--modal-pad, --modal-title-size, --modal-width, --modal-depth) that are set/consumed within the SCSS; those are NOT consumer-facing tokens and stay in the module.
+:root {
+  // Overlay (scrim)
+  --modal-overlay-bg: var(--color-bg-overlay);
+  --modal-overlay-bg-blur: var(--color-bg-overlay-blur);
+  --modal-overlay-z: var(--z-modal);
+  --modal-overlay-opacity-hidden: var(--opacity-hidden);
+  --modal-overlay-opacity-visible: var(--opacity-visible);
+  --modal-overlay-transition: var(--transition-base);
+
+  // Content (dialog box)
+  --modal-bg: var(--color-bg);
+  --modal-radius: var(--radius-lg);
+  --modal-shadow: var(--shadow-lg);
+  --modal-opacity-hidden: var(--opacity-hidden);
+  --modal-opacity-visible: var(--opacity-visible);
+  --modal-transition: var(--transition-base);
+
+  // Size variants — width per size
+  --modal-content-width-sm: var(--size-modal-sm);
+  --modal-content-width-md: var(--size-modal-md);
+  --modal-content-width-lg: var(--size-modal-lg);
+
+  // `full` — near-full-screen, viewport-relative rather than a step on the
+  // width scale. A FIXED height, not a max: a document reader shouldn't resize
+  // itself to each document, and the Body scrolls inside it (#545).
+  // Component-local, not a `--size-modal-*` entry in tokens.json: the value
+  // is viewport-relative and web-only, with no dp counterpart for the
+  // Kotlin/Compose contract.
+  --modal-content-width-full: 95vw;
+  --modal-content-height-full: 90dvh;
+
+  // Size variants — internal padding per size (sm tightens to space-3)
+  --modal-content-padding-default: var(--space-4);
+  --modal-content-padding-sm: var(--space-3);
+
+  // Size variants — title font-size per size (sm tightens to font-size-md)
+  --modal-title-size-default: var(--font-size-lg);
+  --modal-title-size-sm: var(--font-size-md);
+
+  // Header
+  --modal-header-gap: var(--space-3);
+  --modal-header-border-color: var(--color-border);
+  --modal-header-title-font-weight: var(--font-weight-semibold);
+  --modal-header-title-fg: var(--color-fg);
+
+  // Footer
+  --modal-footer-gap: var(--space-2);
+  --modal-footer-border-color: var(--color-border);
+}

package/src/components/Modal/Modal.tsx

@@ -0,0 +1,23 @@
+import { ModalRoot } from './ModalRoot';
+import { Header } from './Header';
+import { Body } from './Body';
+import { Footer } from './Footer';
+import { Close } from './Close';
+
+/**
+ * Compound `<Modal>` family: `Modal.Header`, `Body`, `Footer` and `Close` attached via `Object.assign`.
+ * @see docs/components/Modal.md
+ */
+export const Modal = Object.assign(ModalRoot, {
+  Header,
+  Body,
+  Footer,
+  Close,
+});
+
+export type { ModalProps } from './ModalRoot';
+export type { ModalSize, ModalOverlayVariant, ModalStackMode } from './context';
+export type { ModalHeaderProps } from './Header';
+export type { ModalBodyProps } from './Body';
+export type { ModalFooterProps } from './Footer';
+export type { ModalCloseProps } from './Close';