@eocrm/design-system 0.0.0-stage → 0.6.17

package/src/components/Lightbox/Lightbox.tsx

@@ -0,0 +1,506 @@
+import {
+  useCallback,
+  useEffect,
+  useId,
+  useLayoutEffect,
+  useRef,
+  useState,
+  type CSSProperties,
+  type MouseEvent as ReactMouseEvent,
+  type ReactNode,
+} from 'react';
+import { createPortal } from 'react-dom';
+import clsx from 'clsx';
+import { ChevronLeft, ChevronRight, Download, FileText, X } from 'lucide-react';
+import { Image } from '../Image';
+import { Skeleton } from '../Skeleton';
+import { useFocusTrap } from '../_internal/overlay/useFocusTrap';
+import { useScrollLock } from '../_internal/overlay/useScrollLock';
+import { overlayStack, restoreFocusTo, useOverlayStack } from '../_internal/overlay';
+import { useTranslation } from '../../i18n/useTranslation';
+import styles from './Lightbox.module.scss';
+
+/** One item (image or document) in a `<Lightbox>`. */
+export interface LightboxItem {
+  /** Full-size source URL (an image, or a PDF/document when `kind: 'pdf'`). */
+  src: string;
+  /** Alt text / document name (required — the accessible stage + thumbnail name). */
+  alt: string;
+  /** Item kind. Defaults to `'image'`, or `'pdf'` when `src` ends in `.pdf`. A
+   *  `pdf` item renders in an `<iframe>` (the browser's PDF viewer) with a download
+   *  action instead of an `<img>`. Security: the PDF iframe is NOT sandboxed (Chrome
+   *  blocks its PDF viewer in any sandboxed frame), so a `pdf` `src` MUST be a trusted
+   *  URL — the scheme is restricted to http(s)/relative, but a URL that returns HTML
+   *  instead of a PDF would run with its own origin's privileges. */
+  kind?: 'image' | 'pdf';
+  /** Optional caption shown below the stage. */
+  caption?: ReactNode;
+  /** Optional thumbnail URL for the strip. Images default to `src`; a `pdf` item
+   *  without a thumbnail shows a document-icon placeholder. */
+  thumbnail?: string;
+}
+
+const isPdfSrc = (src: string) => /\.pdf($|[?#])/i.test(src);
+const itemKind = (it: LightboxItem): 'image' | 'pdf' =>
+  it.kind ?? (isPdfSrc(it.src) ? 'pdf' : 'image');
+
+/** Allow only http(s) + relative URLs as an iframe/document src (block
+ *  javascript:/data: etc). Returns the original src when safe, else undefined. */
+function safeDocSrc(src: string): string | undefined {
+  try {
+    const u = new URL(src, 'https://_'); // dummy base resolves relative URLs
+    return u.protocol === 'http:' || u.protocol === 'https:' ? src : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export interface LightboxProps {
+  /** Controlled open state. */
+  open: boolean;
+  /** Fired when the Lightbox wants to close — Esc, backdrop click, the × button. */
+  onOpenChange: (open: boolean) => void;
+  /**
+   * The images and documents (mixed galleries are supported; see `kind` on
+   * `LightboxItem` for PDFs). A PDF without a `thumbnail` shows a document-icon
+   * placeholder in the strip; an unsafe (non-http(s)) document `src` shows a
+   * "Preview unavailable" message. An empty array renders nothing and behaves as
+   * closed (no inert page, scroll lock or focus trap) even while `open`.
+   */
+  items: LightboxItem[];
+  /** Initial image index (uncontrolled). Defaults to `0`. Clamped to range. */
+  defaultIndex?: number;
+  /** Controlled current index. When set, pair with `onIndexChange`. */
+  index?: number;
+  /** Fired on navigation (chevron / arrow key / thumbnail click). */
+  onIndexChange?: (index: number) => void;
+  /** Wrap past the first/last image. Defaults to `true`. */
+  loop?: boolean;
+  /**
+   * Extra header actions for the current item (e.g. a Download `<Button>`, a
+   * `<DropdownMenu>` "more" menu). Called with the current item and its index on
+   * every render, so it follows navigation. Rendered in the top-right toolbar
+   * BEFORE the close button. Use `<Button iconOnly variant="ghost" size="sm">`
+   * (or a DropdownMenu trigger built from one) — the toolbar re-themes ghost
+   * Buttons for the dark scrim (ghost tokens, full radius, `sm` height = the
+   * toolbar control size), so text Buttons render pill-shaped — keep actions
+   * icon-only. While an action's menu or popover is open, Esc closes it first, and
+   * ←/→ stay with it (not the gallery) while focus is in it — likewise while focus
+   * is on a text field, combobox (Select), radio (ButtonGroup), slider, tab or
+   * expanded trigger; a Tooltip on an action doesn't block navigation. Returning `null`/`undefined` renders nothing.
+   * REPLACES the built-in PDF download link: when `actions` is set, the
+   * Lightbox renders no download action of its own — include your own
+   * Download for PDF items if you want one.
+   */
+  actions?: (item: LightboxItem, index: number) => ReactNode;
+  /** className for the dialog container. */
+  className?: string;
+  /**
+   * Accessible label for the dialog. Defaults to the i18n "Image gallery" when
+   * omitted OR empty — an empty string is not an explicit name, so it takes
+   * the default too.
+   */
+  'aria-label'?: string;
+}
+
+// In-dialog elements that own ←/→ while focused: text entry, a Select-style
+// combobox (focus stays on it while its listbox is open), arrow-driven widgets
+// (ButtonGroup radios, Slider, Tabs) and any expanded trigger.
+const ARROW_OWNING_CONTROL = [
+  'input:not([type="checkbox"], [type="button"], [type="submit"], [type="reset"], [type="file"], [type="image"])',
+  'textarea',
+  'select',
+  '[contenteditable]:not([contenteditable="false"])',
+  '[role="combobox"]',
+  '[role="radio"]',
+  '[role="slider"]',
+  '[role="tab"]',
+  '[aria-expanded="true"]',
+].join(', ');
+
+const clampIndex = (i: number, n: number) => Math.min(Math.max(i, 0), Math.max(n - 1, 0));
+const wrapIndex = (i: number, n: number) => ((i % n) + n) % n;
+
+// Body children matching these are NOT made inert when the Lightbox is on top —
+// other overlay portals stay interactive (stacked overlays), mirroring Modal.
+const PORTAL_EXEMPT =
+  '[data-lightbox-portal-root], [data-modal-portal-root], [data-drawer-portal-root]';
+
+/**
+ * Full-screen image and PDF gallery overlay with prev/next, thumbnail strip and optional captions; controlled `open`.
+ * @see docs/components/Lightbox.md
+ */
+export function Lightbox({
+  open: openProp,
+  onOpenChange,
+  items,
+  defaultIndex = 0,
+  index,
+  onIndexChange,
+  loop = true,
+  actions,
+  className,
+  'aria-label': ariaLabel,
+}: LightboxProps) {
+  const t = useTranslation();
+  const id = useId();
+  const n = items.length;
+  // An open Lightbox with nothing to show behaves as closed: no overlay-stack
+  // entry, inert background, scroll lock or focus trap (#612).
+  const open = openProp && n > 0;
+  const isControlled = index !== undefined;
+
+  const [internalIndex, setInternalIndex] = useState(() => clampIndex(defaultIndex, n));
+  const current = clampIndex(isControlled ? (index as number) : internalIndex, n);
+
+  const { depth, isTop } = useOverlayStack(id, open, 'replace');
+
+  // Focus restoration (WCAG 2.4.3, like Modal/Drawer). Split into two effects:
+  //  - CAPTURE is a layout effect so it snapshots the trigger BEFORE focus moves
+  //    into the dialog (the focus-into-dialog effect below is also layout).
+  //  - RESTORE is a PASSIVE effect so it runs AFTER the inert-background cleanup
+  //    (also passive) has removed `inert` from the trigger's subtree — otherwise
+  //    `.focus()` would silently fail on a still-inert element (→ falls to <body>).
+  const previouslyFocusedRef = useRef<HTMLElement | null>(null);
+  const prevOpenRef = useRef<boolean>(open);
+  useLayoutEffect(() => {
+    if (open) previouslyFocusedRef.current = (document.activeElement as HTMLElement | null) ?? null;
+  }, [open]);
+  useEffect(() => {
+    if (!open && prevOpenRef.current) {
+      const target = previouslyFocusedRef.current;
+      if (target && document.contains(target)) restoreFocusTo(target);
+      previouslyFocusedRef.current = null;
+    }
+    prevOpenRef.current = open;
+  }, [open]);
+
+  useScrollLock(open);
+  const dialogRef = useRef<HTMLDivElement | null>(null);
+  useFocusTrap(dialogRef, open && isTop);
+
+  // Reseed the uncontrolled index whenever the Lightbox (re)opens.
+  useEffect(() => {
+    if (open && !isControlled) setInternalIndex(clampIndex(defaultIndex, n));
+    // Only on open transition — defaultIndex/n changes mid-open shouldn't yank the user.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [open]);
+
+  const goTo = useCallback(
+    (nextIndex: number) => {
+      if (n === 0) return;
+      const target = loop ? wrapIndex(nextIndex, n) : clampIndex(nextIndex, n);
+      if (target === current) return; // no-op move (e.g. an arrow key at a non-looping end)
+      if (!isControlled) setInternalIndex(target);
+      onIndexChange?.(target);
+    },
+    [n, loop, isControlled, onIndexChange, current],
+  );
+  const goNext = useCallback(() => goTo(current + 1), [goTo, current]);
+  const goPrev = useCallback(() => goTo(current - 1), [goTo, current]);
+  const close = useCallback(() => onOpenChange(false), [onOpenChange]);
+
+  // Per-image stage load/error state, reset when the source changes.
+  const currentItem: LightboxItem | undefined = items[current];
+  const currentSrc = currentItem?.src;
+  // Reset during render, not in an effect: a mount-time effect ran after a
+  // cached image's `load` and left the skeleton up for good (#574).
+  const [stageState, setStageState] = useState<'loading' | 'loaded' | 'error'>('loading');
+  const [prevSrc, setPrevSrc] = useState(currentSrc);
+  if (currentSrc !== prevSrc) {
+    setPrevSrc(currentSrc);
+    setStageState('loading');
+  }
+
+  // Inert the rest of the page while we're the top overlay (mirrors Modal.Overlay).
+  useEffect(() => {
+    if (!open || !isTop) return;
+    const kids = Array.from(document.body.children) as HTMLElement[];
+    const restore: Array<{ el: HTMLElement; had: boolean }> = [];
+    for (const el of kids) {
+      if (el.matches(PORTAL_EXEMPT)) continue;
+      const had = el.hasAttribute('inert');
+      if (!had) el.setAttribute('inert', '');
+      restore.push({ el, had });
+    }
+    return () => {
+      for (const { el, had } of restore) if (!had) el.removeAttribute('inert');
+    };
+  }, [open, isTop]);
+
+  // Keyboard: Esc closes, ← → navigate (capture-phase + gated to top, like Modal.Content).
+  useEffect(() => {
+    if (!open || !isTop) return;
+    function onKeyDown(e: KeyboardEvent) {
+      // #274: yield Escape to an open floating surface — see Modal/Content.tsx.
+      if (
+        e.key === 'Escape' &&
+        (overlayStack.hasOpenFloating() || overlayStack.wasEscapeConsumed(e))
+      )
+        return;
+      // Arrows navigate only while focus is in the gallery itself. Focus outside the
+      // dialog means a portaled surface from an action has it (DropdownMenu,
+      // Popover/ConfirmationPopover, …) — navigating would retarget its still-open
+      // "Delete" at a different file. Not hasOpenFloating(): a Tooltip on a focused
+      // action is floating too, and must not kill navigation. Focus dropped to
+      // <body> (a focused action unmounted) still counts as the gallery.
+      if (e.key === 'ArrowRight' || e.key === 'ArrowLeft') {
+        const active = document.activeElement as HTMLElement | null;
+        const inGallery =
+          !active || active === document.body || !!dialogRef.current?.contains(active);
+        if (!inGallery || active?.matches(ARROW_OWNING_CONTROL)) return;
+      }
+      if (e.key === 'Escape') {
+        e.stopPropagation();
+        close();
+      } else if (e.key === 'ArrowRight' && n > 1) {
+        e.preventDefault();
+        goNext();
+      } else if (e.key === 'ArrowLeft' && n > 1) {
+        e.preventDefault();
+        goPrev();
+      }
+    }
+    document.addEventListener('keydown', onKeyDown, true);
+    return () => document.removeEventListener('keydown', onKeyDown, true);
+  }, [open, isTop, n, close, goNext, goPrev]);
+
+  // Move focus into the overlay on open. Gated to the OPEN transition only
+  // (like Modal/Drawer, #551): isTop also flips false -> true when a nested
+  // overlay (e.g. a Modal opened above the Lightbox) closes, and re-running
+  // unconditionally here would steal focus back from wherever that overlay
+  // restored it.
+  const initialFocusPendingRef = useRef(true);
+  useLayoutEffect(() => {
+    if (!open) {
+      initialFocusPendingRef.current = true;
+      return;
+    }
+    if (!isTop || !initialFocusPendingRef.current) return;
+    initialFocusPendingRef.current = false;
+    dialogRef.current?.focus();
+  }, [open, isTop]);
+
+  // Keep the active thumbnail in view (guarded — jsdom has no scrollIntoView).
+  const thumbRefs = useRef<Array<HTMLDivElement | null>>([]);
+  useEffect(() => {
+    if (!open) return;
+    thumbRefs.current[current]?.scrollIntoView?.({ block: 'nearest', inline: 'center' });
+  }, [open, current]);
+
+  if (!open || n === 0 || !currentItem) return null;
+
+  const currentKind = itemKind(currentItem);
+  // Sanitized document URL (http(s)/relative only) for the current PDF item, or
+  // undefined when the item isn't a PDF or its src is unsafe. Computed once and
+  // reused by the download link, the stage iframe, and the unavailable fallback.
+  const docSrc = currentKind === 'pdf' ? safeDocSrc(currentItem.src) : undefined;
+  const multi = n > 1;
+  const atStart = current === 0;
+  const atEnd = current === n - 1;
+
+  const closeIfBackdrop = (e: ReactMouseEvent<HTMLDivElement>) => {
+    if (e.target === e.currentTarget) close();
+  };
+
+  const style = { ['--lightbox-depth' as string]: String(depth ?? 0) } as CSSProperties;
+
+  return createPortal(
+    <div
+      data-lightbox-portal-root=""
+      ref={dialogRef}
+      role="dialog"
+      aria-modal="true"
+      aria-label={ariaLabel || t('lightbox.label')}
+      tabIndex={-1}
+      className={clsx(styles.root, className)}
+      style={style}
+      onClick={closeIfBackdrop}
+    >
+      {/* Top-right chrome: [consumer actions | built-in PDF download][close]. */}
+      <div className={styles.toolbar}>
+        {actions ? (
+          actions(currentItem, current)
+        ) : docSrc ? (
+          <a
+            className={styles.download}
+            href={docSrc}
+            download
+            // Open/save in a new tab: a cross-origin `download` is ignored by the
+            // browser, so without target the click would navigate the whole app
+            // away from the gallery. noopener/noreferrer guard the opened context.
+            target="_blank"
+            rel="noopener noreferrer"
+            aria-label={t('lightbox.download')}
+          >
+            <Download size={20} aria-hidden="true" />
+          </a>
+        ) : null}
+
+        <button
+          type="button"
+          className={styles.close}
+          aria-label={t('lightbox.close')}
+          onClick={close}
+        >
+          <X size={20} aria-hidden="true" />
+        </button>
+      </div>
+
+      <div className={styles.stage} onClick={closeIfBackdrop}>
+        {multi && (
+          <button
+            type="button"
+            className={clsx(styles.chev, styles.chevPrev)}
+            aria-label={t('lightbox.previous')}
+            onClick={goPrev}
+            disabled={!loop && atStart}
+          >
+            <ChevronLeft size={28} aria-hidden="true" />
+          </button>
+        )}
+
+        <div className={styles.imageWrap}>
+          {currentKind === 'pdf' ? (
+            docSrc ? (
+              <iframe
+                key={docSrc}
+                src={docSrc}
+                title={currentItem.alt}
+                className={styles.doc}
+                referrerPolicy="no-referrer"
+                // No `sandbox`: a PDF is rendered by the browser's own PDF engine
+                // (PDFium / pdf.js), which already isolates the PDF's JS from the
+                // page — so a sandbox adds nothing for PDF content while BLOCKING
+                // Chrome's PDF viewer entirely ("This page has been blocked by
+                // Chrome"; Chrome refuses to render PDFs in ANY sandboxed iframe,
+                // regardless of allow-* tokens). `referrerPolicy="no-referrer"` and the
+                // http(s)/relative-only `safeDocSrc` check (blocks javascript:/data:/
+                // blob:) defend against SCHEME attacks; a URL that returns HTML instead
+                // of a PDF would run unsandboxed, so this path relies on the documented
+                // contract that the consumer frames its own trusted file URLs.
+              />
+            ) : (
+              <div
+                className={styles.stageError}
+                role="img"
+                /* Guarded, unlike before: an item with an empty `alt` produced
+                   a name of ": Preview unavailable", leading with punctuation.
+                   `role="img"` is safe HERE — the only child is text the label
+                   already repeats, so children-presentational prunes nothing a
+                   user needed. Do NOT copy this shape onto a tile containing a
+                   control: that is what broke Image's Retry button (#496). */
+                aria-label={
+                  currentItem.alt
+                    ? `${currentItem.alt}: ${t('lightbox.previewUnavailable')}`
+                    : t('lightbox.previewUnavailable')
+                }
+              >
+                {t('lightbox.previewUnavailable')}
+              </div>
+            )
+          ) : (
+            <>
+              <img
+                key={currentItem.src}
+                src={currentItem.src}
+                alt={currentItem.alt}
+                className={styles.image}
+                data-state={stageState}
+                onLoad={() => setStageState('loaded')}
+                onError={() => setStageState('error')}
+              />
+              {stageState === 'loading' && (
+                <Skeleton variant="rectangular" className={styles.stageOverlay} />
+              )}
+              {stageState === 'error' && (
+                <div
+                  className={styles.stageError}
+                  role="img"
+                  /* Concatenated, where Image's tile deliberately is NOT —
+                     the difference is markup, not policy. Here the text is a
+                     CHILD of `role="img"`, so children-presentational prunes
+                     it and the name is the only thing left to say it. In Image
+                     the text is a SIBLING that survives, so concatenating made
+                     a reader hear the failure twice. `role="img"` stays on the
+                     container here because the only child is that text; Image
+                     had to move it onto the icon, whose Retry button the role
+                     pruned outright. */
+                  aria-label={
+                    currentItem.alt
+                      ? `${currentItem.alt}: ${t('image.loadError')}`
+                      : t('image.loadError')
+                  }
+                >
+                  {t('image.loadError')}
+                </div>
+              )}
+            </>
+          )}
+        </div>
+
+        {multi && (
+          <button
+            type="button"
+            className={clsx(styles.chev, styles.chevNext)}
+            aria-label={t('lightbox.next')}
+            onClick={goNext}
+            disabled={!loop && atEnd}
+          >
+            <ChevronRight size={28} aria-hidden="true" />
+          </button>
+        )}
+      </div>
+
+      {(currentItem.caption != null || multi) && (
+        <div className={styles.meta}>
+          {currentItem.caption != null && (
+            <div className={styles.caption}>{currentItem.caption}</div>
+          )}
+          {multi && (
+            <div className={styles.counter}>
+              {current + 1} / {n}
+            </div>
+          )}
+        </div>
+      )}
+
+      {multi && (
+        <div className={styles.thumbs}>
+          {items.map((it, i) => (
+            <div
+              key={i}
+              ref={(el) => {
+                thumbRefs.current[i] = el;
+              }}
+              className={clsx(styles.thumb, i === current && styles.thumbActive)}
+            >
+              {itemKind(it) === 'pdf' && !it.thumbnail ? (
+                <button
+                  type="button"
+                  className={styles.thumbDoc}
+                  aria-label={it.alt}
+                  onClick={() => goTo(i)}
+                >
+                  <FileText size={20} aria-hidden="true" />
+                </button>
+              ) : (
+                <Image
+                  src={it.thumbnail ?? it.src}
+                  alt=""
+                  aspectRatio={1}
+                  objectFit="cover"
+                  interactive
+                  onClick={() => goTo(i)}
+                  ariaLabel={it.alt}
+                />
+              )}
+            </div>
+          ))}
+        </div>
+      )}
+    </div>,
+    document.body,
+  );
+}
+Lightbox.displayName = 'Lightbox';

package/src/components/Lightbox/index.ts

@@ -0,0 +1,2 @@
+export { Lightbox } from './Lightbox';
+export type { LightboxProps, LightboxItem } from './Lightbox';

package/src/components/Link/Link.module.scss

@@ -0,0 +1,78 @@
+@use '../../styles/mixins' as *;
+@use './Link.tokens';
+
+.link {
+  // A link-styled control rendered via `as` on a non-anchor (e.g. `as="button"`)
+  // gets no pointer cursor from the UA — only `<a>` does — so set it explicitly.
+  // Makes the affordance element-agnostic (like how Button owns its own cursor).
+  cursor: pointer;
+  font-family: inherit;
+  font-size: inherit;
+  color: inherit;
+  text-decoration: none;
+  border-radius: var(--link-radius);
+  transition:
+    color var(--transition-fast),
+    text-decoration-color var(--transition-fast);
+
+  &:focus-visible {
+    @include focus-ring;
+  }
+
+  // When the Link contains an icon (SVG), switch to inline-flex so the icon
+  // aligns vertically with the text and a default gap separates them. Pure
+  // text Links stay as native inline anchors so multi-word link text wraps
+  // naturally inside body copy.
+  &:has(svg) {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--link-icon-gap);
+  }
+}
+
+.default {
+  color: var(--link-fg-default);
+  font-weight: var(--link-font-weight-default);
+
+  &:hover {
+    color: var(--link-fg-default-hover);
+    text-decoration: underline;
+  }
+}
+
+// Already-bold text (headings, <strong>, table headers) keeps its own weight:
+// an accent's link weight would otherwise render the link LIGHTER than its
+// context. A semibold <Text> span isn't a bold element; see Link.md.
+:is(strong, b, th, h1, h2, h3, h4, h5, h6) .default {
+  font-weight: inherit;
+}
+
+.muted {
+  color: var(--link-fg-muted);
+
+  &:hover {
+    color: var(--link-fg-muted-hover);
+  }
+}
+
+.subtle {
+  color: var(--link-fg-subtle);
+
+  &:hover {
+    color: var(--link-fg-subtle-hover);
+    text-decoration: underline;
+  }
+}
+
+// `underline` prop overrides. Combined with `.link` (always present on every
+// Link element) each becomes a 2-class compound selector — 3 classes for the
+// `:hover` override — so it reliably outranks a bare single-class variant
+// rule (`.default`, `.muted`, `.subtle`) regardless of source order, without
+// `!important`.
+.link.underlineAlways {
+  text-decoration: underline;
+}
+
+.link.underlineNone:hover {
+  text-decoration: none;
+}

package/src/components/Link/Link.tokens.scss

@@ -0,0 +1,28 @@
+// Link.tokens.scss — Component-scoped tokens for <Link>. Three variants:
+// default (accent), muted (fg-muted -> accent on hover), subtle (fg -> accent
+// on hover). Each variant has its own fg + fg-hover pair. Icon gap is shared.
+:root {
+  // Shape + icon gap
+  --link-radius: var(--radius-sm);
+  --link-icon-gap: var(--space-1);
+
+  // Variant: default. --color-link-fg defaults to the accent; an accent set may
+  // override it when its accent is too close to body text to read as a link.
+  --link-fg-default: var(--color-link-fg);
+  --link-fg-default-hover: var(--color-link-fg-hover);
+  --link-font-weight-default: inherit;
+
+  // Variant: muted
+  --link-fg-muted: var(--color-fg-muted);
+  --link-fg-muted-hover: var(--color-accent);
+
+  // Variant: subtle
+  --link-fg-subtle: var(--color-fg);
+  --link-fg-subtle-hover: var(--color-accent);
+}
+
+// Teal pine's accent sits close to the navy body text, so its default links
+// also step up in weight (the colour alone can't carry the difference).
+:root[data-accent='tealpine'] {
+  --link-font-weight-default: var(--font-weight-medium);
+}