@eocrm/design-system 0.0.0-stage → 0.6.17

package/src/components/Screen/Screen.tokens.scss

@@ -0,0 +1,20 @@
+// Screen.tokens.scss — Component-scoped tokens for <Screen>. Padding, the
+// block-fill min-height, and the three backdrops. Backdrop gradients reference
+// color primitives for their stops (geometry percentages are not tokenized
+// values); custom-property declarations are exempt from declaration-strict-value.
+:root {
+  --screen-padding: var(--space-6);
+  --screen-block-min-height: 60vh;
+
+  --screen-backdrop-plain: var(--color-bg-subtle);
+  --screen-backdrop-accent: radial-gradient(
+    120% 90% at 50% -8%,
+    var(--color-accent-subtle-bg) 0%,
+    var(--color-bg-subtle) 52%
+  );
+  --screen-backdrop-danger: radial-gradient(
+    120% 90% at 50% -8%,
+    var(--color-danger-bg-subtle) 0%,
+    var(--color-bg-subtle) 55%
+  );
+}

package/src/components/Screen/Screen.tsx

@@ -0,0 +1,97 @@
+import { forwardRef, type HTMLAttributes, type ReactNode } from 'react';
+import clsx from 'clsx';
+import styles from './Screen.module.scss';
+
+/** How tall the screen is. */
+export type ScreenFill = 'viewport' | 'block';
+
+/** Backdrop treatment behind the centered content. */
+export type ScreenBackdrop = 'none' | 'plain' | 'accent' | 'danger';
+
+/** Vertical placement of the main content. */
+export type ScreenAlign = 'center' | 'start';
+
+export interface ScreenProps extends HTMLAttributes<HTMLDivElement> {
+  /** The centered main content. */
+  children: ReactNode;
+
+  /** Pinned-top slot — a back link, wordmark, etc. Omit for none. */
+  header?: ReactNode;
+
+  /** Pinned-bottom slot — legal / footer links. Omit for none. */
+  footer?: ReactNode;
+
+  /**
+   * Screen height. Defaults to `'viewport'`.
+   * - `'viewport'` — `min-height: 100vh`; a true standalone page (login,
+   *   standalone 404 / error).
+   * - `'block'` — fills its container instead of the viewport; use when the
+   *   Screen is embedded inside the app shell's content area (the in-app
+   *   404 / error variants).
+   */
+  fill?: ScreenFill;
+
+  /**
+   * Backdrop behind the content. Defaults to `'none'` (transparent — inherits
+   * the surface; use with `fill="block"` inside the shell).
+   * - `'plain'` — solid subtle surface.
+   * - `'accent'` — accent-tinted radial (the login backdrop).
+   * - `'danger'` — danger-tinted radial (standalone error screen).
+   */
+  backdrop?: ScreenBackdrop;
+
+  /** Vertical placement of the main content. Defaults to `'center'`. */
+  align?: ScreenAlign;
+}
+
+const fillClass: Record<ScreenFill, string> = {
+  viewport: styles.fillViewport,
+  block: styles.fillBlock,
+};
+
+const backdropClass: Record<ScreenBackdrop, string | undefined> = {
+  none: undefined,
+  plain: styles.backdropPlain,
+  accent: styles.backdropAccent,
+  danger: styles.backdropDanger,
+};
+
+const alignClass: Record<ScreenAlign, string> = {
+  center: styles.alignCenter,
+  start: styles.alignStart,
+};
+
+/**
+ * Full-bleed / centered page-root layout for chromeless screens outside the app shell (sign-in, 404, error, onboarding).
+ * @see docs/components/Screen.md
+ */
+export const Screen = forwardRef<HTMLDivElement, ScreenProps>(function Screen(
+  {
+    children,
+    header,
+    footer,
+    fill = 'viewport',
+    backdrop = 'none',
+    align = 'center',
+    className,
+    ...rest
+  },
+  ref,
+) {
+  // {...rest} last so consumer overrides win (Pattern A).
+  return (
+    <div
+      ref={ref}
+      className={clsx(styles.root, fillClass[fill], backdropClass[backdrop], className)}
+      {...rest}
+    >
+      {/* `styles.header` / `styles.footer` are intentionally NOT declared in the
+          SCSS — the flex column pins them top/bottom. Accessing an absent CSS-module
+          key returns undefined at runtime → no class attribute (and avoids an empty
+          ruleset that would trip stylelint's block-no-empty). */}
+      {header != null && <div className={styles.header}>{header}</div>}
+      <div className={clsx(styles.main, alignClass[align])}>{children}</div>
+      {footer != null && <div className={styles.footer}>{footer}</div>}
+    </div>
+  );
+});

package/src/components/Screen/index.ts

@@ -0,0 +1,2 @@
+export { Screen } from './Screen';
+export type { ScreenProps, ScreenFill, ScreenBackdrop, ScreenAlign } from './Screen';

package/src/components/ScrollArea/ScrollArea.module.scss

@@ -0,0 +1,39 @@
+@use './ScrollArea.tokens';
+@use '../../styles/mixins' as *;
+
+// Scrolling, not layout: overflow + a shrinkable min-height so the area can
+// be the one flexible child of a bounded flex parent (e.g. a Popover capped at
+// the viewport). `overscroll-behavior: contain` keeps a feed scrolled to its
+// end from scrolling the page behind the popover.
+.root {
+  overflow-y: auto;
+
+  // Vertical only: `overflow-y: auto` alone computes `overflow-x: auto`, a
+  // horizontal scroller with no keyboard tab stop. Wide content is clipped.
+  overflow-x: hidden;
+  min-height: 0;
+  overscroll-behavior: contain;
+
+  // The overflow clips at the padding edge, so a link flush against it lost
+  // its outset focus ring (focus-ring geometry sweep). Pad by the ring's
+  // extent, and scroll-pad the same so a keyboard-focused child scrolls into
+  // view with its ring.
+  padding: var(--scroll-area-padding);
+  scroll-padding: var(--scroll-area-padding);
+
+  &:focus-visible {
+    @include focus-ring(var(--scroll-area-ring));
+  }
+}
+
+.max-height-sm {
+  max-height: var(--scroll-area-max-height-sm);
+}
+
+.max-height-md {
+  max-height: var(--scroll-area-max-height-md);
+}
+
+.max-height-lg {
+  max-height: var(--scroll-area-max-height-lg);
+}

package/src/components/ScrollArea/ScrollArea.tokens.scss

@@ -0,0 +1,15 @@
+// ScrollArea.tokens.scss — component-scoped tokens for <ScrollArea>.
+:root {
+  // Height cap scale (`maxHeight="sm" | "md" | "lg"`).
+  --scroll-area-max-height-sm: var(--size-scroll-area-sm);
+  --scroll-area-max-height-md: var(--size-scroll-area-md);
+  --scroll-area-max-height-lg: var(--size-scroll-area-lg);
+
+  // Content inset = the focus-ring extent (offset + width, 4px): room for a
+  // focused child's outset ring at the area's clip edge (same approach as
+  // DropdownMenu's --dropdown-menu-padding).
+  --scroll-area-padding: calc(var(--ring-offset) + var(--ring-width));
+
+  // Focus ring — shown only while the area is itself a tab stop.
+  --scroll-area-ring: var(--ring-accent);
+}

package/src/components/ScrollArea/ScrollArea.tsx

@@ -0,0 +1,154 @@
+import {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  useState,
+  type HTMLAttributes,
+} from 'react';
+import clsx from 'clsx';
+import { chain, mergeRefs } from '../_internal/refs';
+import { FOCUSABLE_SELECTOR } from '../_internal/overlay/useFocusTrap';
+import styles from './ScrollArea.module.scss';
+
+/**
+ * Height cap for `<ScrollArea>`. A scale value (`'sm' | 'md' | 'lg'`) or an
+ * escape-hatch length. Details on `ScrollAreaProps#maxHeight`.
+ */
+// `string & {}` keeps editor autocomplete for the scale values.
+export type ScrollAreaMaxHeight = 'sm' | 'md' | 'lg' | number | (string & {});
+
+const SCALE: ReadonlySet<string> = new Set(['sm', 'md', 'lg']);
+
+export interface ScrollAreaProps extends HTMLAttributes<HTMLDivElement> {
+  /**
+   * Caps the area's height; past it, the content scrolls vertically.
+   * - `'sm'` — 240px. A short list inside a form or a card.
+   * - `'md'` — 400px. A popover feed (notifications, activity).
+   * - `'lg'` — 560px. A tall panel body.
+   * - `number` — px, for a one-off (`maxHeight={320}`). Prefer the scale.
+   * - `string` — any CSS length (`'50vh'`).
+   *
+   * Omitted: no cap of its own. The area fills the height its parent gives
+   * it, which is right as the flexible child of a bounded flex column.
+   */
+  maxHeight?: ScrollAreaMaxHeight;
+}
+
+/**
+ * A region that scrolls only its own content vertically, padded by the focus-ring extent so focused rings are not clipped.
+ * @see docs/components/ScrollArea.md
+ */
+export const ScrollArea = forwardRef<HTMLDivElement, ScrollAreaProps>(function ScrollArea(
+  { maxHeight, className, style, children, onBlur, ...rest },
+  ref,
+) {
+  const innerRef = useRef<HTMLDivElement>(null);
+  const [focusable, setFocusable] = useState(false);
+  const warnedRef = useRef(false);
+
+  // A scroller the keyboard can't reach is WCAG 2.1.1's failure (axe
+  // `scrollable-region-focusable`). Focusable content already reaches it,
+  // since tabbing to a child scrolls it into view, so the area only becomes a
+  // tab stop when it overflows AND holds nothing focusable. This is what
+  // Chrome 130+ and Firefox do natively; Safari doesn't.
+  const measure = useCallback(() => {
+    const el = innerRef.current;
+    if (!el) return;
+    const next = el.scrollHeight > el.clientHeight && el.querySelector(FOCUSABLE_SELECTOR) === null;
+    // Removing tabIndex from the focused element drops focus to <body>. Keep
+    // the tab stop while the area holds focus; the onBlur re-measure drops it.
+    setFocusable((prev) => next || (prev && document.activeElement === el));
+  }, []);
+
+  useLayoutEffect(measure, [measure]);
+
+  useEffect(() => {
+    const el = innerRef.current;
+    if (!el) return;
+    const ro = typeof ResizeObserver === 'undefined' ? null : new ResizeObserver(measure);
+    // The area's own box changes when its cap or its parent does; its
+    // content's height changes when a direct child resizes (images loading,
+    // rows expanding). Observe direct children as they're added; drop the
+    // ones removed so detached rows aren't held until unmount.
+    if (ro) {
+      ro.observe(el);
+      for (const child of Array.from(el.children)) ro.observe(child);
+    }
+    const mo =
+      typeof MutationObserver === 'undefined'
+        ? null
+        : new MutationObserver((records) => {
+            if (ro) {
+              for (const record of records) {
+                for (const node of Array.from(record.addedNodes)) {
+                  if (node instanceof Element && node.parentNode === el) ro.observe(node);
+                }
+                if (record.target === el) {
+                  for (const node of Array.from(record.removedNodes)) {
+                    if (node instanceof Element) ro.unobserve(node);
+                  }
+                }
+              }
+            }
+            measure();
+          });
+    mo?.observe(el, {
+      childList: true,
+      subtree: true,
+      // A bare text-node child (e.g. a plain-text log) updates via
+      // `nodeValue` in place — no childList mutation, so without this the
+      // area never re-measures as that text grows.
+      characterData: true,
+      attributes: true,
+      // FOCUSABLE_SELECTOR ignores visibility, so a link inside a `hidden`
+      // wrapper still counts as focusable and suppresses the tab stop — a
+      // known limit shared with useFocusTrap. `hidden` stays in the filter
+      // anyway: the re-measure it triggers is harmless.
+      attributeFilter: ['tabindex', 'disabled', 'href', 'hidden'],
+    });
+    return () => {
+      ro?.disconnect();
+      mo?.disconnect();
+    };
+  }, [measure]);
+
+  const named = Boolean(rest['aria-label'] || rest['aria-labelledby']);
+  useEffect(() => {
+    if (process.env.NODE_ENV === 'production') return;
+    if (focusable && !named && !warnedRef.current) {
+      warnedRef.current = true;
+      console.warn(
+        '[ScrollArea] It overflows with no focusable content, so it is a keyboard tab stop — ' +
+          'give it an accessible name with aria-label or aria-labelledby.',
+      );
+    }
+  }, [focusable, named]);
+
+  const scale = typeof maxHeight === 'string' && SCALE.has(maxHeight);
+  const inlineMaxHeight =
+    maxHeight === undefined || scale
+      ? undefined
+      : typeof maxHeight === 'number'
+        ? `${maxHeight}px`
+        : maxHeight;
+
+  return (
+    // {...rest} last so a consumer tabIndex / role overrides the computed ones.
+    <div
+      ref={mergeRefs<HTMLDivElement>(innerRef, ref)}
+      data-scroll-area=""
+      tabIndex={focusable ? 0 : undefined}
+      // Named ⇒ always a region: a named generic div is prohibited (ARIA 1.2).
+      role={named || focusable ? 'region' : undefined}
+      className={clsx(styles.root, scale && styles[`max-height-${maxHeight}`], className)}
+      style={inlineMaxHeight !== undefined ? { maxHeight: inlineMaxHeight, ...style } : style}
+      onBlur={chain(onBlur, measure)}
+      {...rest}
+    >
+      {children}
+    </div>
+  );
+});
+ScrollArea.displayName = 'ScrollArea';

package/src/components/ScrollArea/index.ts

@@ -0,0 +1,2 @@
+export { ScrollArea } from './ScrollArea';
+export type { ScrollAreaProps, ScrollAreaMaxHeight } from './ScrollArea';

package/src/components/Select/Chip.tsx

@@ -0,0 +1,45 @@
+import clsx from 'clsx';
+import styles from './Select.module.scss';
+import { useTranslation } from '../../i18n/useTranslation';
+
+/**
+ * Internal subcomponent rendered inside chips-mode Select triggers
+ * (`multiple + triggerDisplay='chips'`). Each Chip represents one selected
+ * option: a label plus a ✕ button that removes it.
+ *
+ * The ✕ is a real `<button>` so keyboard / AT users can focus and activate
+ * it. `onPointerDown` is stopped so the click doesn't bubble to the chips
+ * trigger wrapper (which would toggle the popover open/closed); `onClick`
+ * is also stopped so the wrapper's click handler doesn't fire.
+ *
+ * Not exported from the package. The chips trigger is the only call site.
+ */
+export interface ChipProps {
+  label: string;
+  onRemove: () => void;
+  disabled?: boolean;
+}
+
+export function Chip({ label, onRemove, disabled }: ChipProps) {
+  const t = useTranslation();
+  return (
+    <span className={clsx(styles.chip, disabled && styles.chipDisabled)}>
+      <span className={styles.chipLabel}>{label}</span>
+      <button
+        type="button"
+        className={styles.chipRemove}
+        aria-label={t('select.removeChip', { label })}
+        disabled={disabled}
+        onClick={(e) => {
+          e.stopPropagation();
+          onRemove();
+        }}
+        onPointerDown={(e) => e.stopPropagation()}
+      >
+        <svg width="10" height="10" viewBox="0 0 10 10" aria-hidden="true">
+          <path d="M1 1 L9 9 M9 1 L1 9" stroke="currentColor" strokeWidth="1.5" />
+        </svg>
+      </button>
+    </span>
+  );
+}

package/src/components/Select/Empty.tsx

@@ -0,0 +1,39 @@
+import { useTranslation } from '../../i18n/useTranslation';
+import { emptyStateText } from './emptyStateText';
+import styles from './Select.module.scss';
+
+/**
+ * Props for the default empty-state row. `query` shapes the message
+ * ("No results for X." vs "No options.") so the user understands whether
+ * the listbox is empty because their filter matched nothing or because
+ * the source has no options at all.
+ */
+export interface EmptyProps {
+  /**
+   * Current search query, if any. Empty string / undefined renders the
+   * "no options at all" copy; a non-empty value renders the "no results
+   * for this query" copy.
+   */
+  query?: string;
+}
+
+/**
+ * Default empty-state row rendered inside the listbox when there are no
+ * options to show. Consumers can override via `renderEmpty` on `<Select>`.
+ *
+ * Rendered as a non-interactive `<li role="presentation">` so it occupies
+ * a row visually but isn't reachable by keyboard or counted in the option
+ * walk. No `aria-live` of its own — the Listbox's single status region
+ * announces this state, and the visible copy is hidden from AT so a reader
+ * does not meet the sentence twice.
+ */
+export function Empty({ query }: EmptyProps) {
+  const t = useTranslation();
+  return (
+    <li className={styles.stateRow} role="presentation">
+      {/* aria-hidden for the same reason as the error row: the Listbox status
+          region renders this same text, and both are in the tree at once. */}
+      <span aria-hidden="true">{emptyStateText(t, query)}</span>
+    </li>
+  );
+}

package/src/components/Select/Error.tsx

@@ -0,0 +1,51 @@
+import { useTranslation } from '../../i18n/useTranslation';
+import styles from './Select.module.scss';
+
+/**
+ * Props for the default error-state row.
+ *
+ * `error` mirrors the consumer-facing `renderError(err, retry)` signature
+ * so a custom override can drop in without prop-name churn. It's not used
+ * in the default body, which prints a generic "Failed to load options."
+ * message — exposing the raw error message in the listbox would surface
+ * stack traces or HTTP detail strings to end users.
+ */
+export interface ErrorRowProps {
+  /** Original error, kept on the prop surface to match `renderError`. */
+  error: Error;
+  /** Re-fires `loadOptions` with the current query. */
+  onRetry: () => void;
+}
+
+/**
+ * Default error-state row, rendered inside the listbox when an async
+ * `loadOptions` request rejects. `role="presentation"` like its siblings —
+ * it used to carry `role="alert"`, a third mechanism for one concern (#495).
+ * The `aria-required-children` framing that used to be here is dropped: see
+ * `messages.ts` — Chromium ignores these rows inside a `role="listbox"`
+ * regardless, so the argument rests on the region-and-text mounting together,
+ * which is enough on its own. The Retry button calls back
+ * into the async hook's `retry()`, which bumps the retry token and
+ * re-enters the debounced effect, so the refetch waits `debounceMs` like any
+ * other query — the branch's own test has to advance timers after clicking it.
+ */
+export function ErrorRow({ error: _error, onRetry }: ErrorRowProps) {
+  // `error` stays on the prop surface so the props match `renderError(err,
+  // retry)`. The default body intentionally doesn't show the raw error.
+  void _error;
+  const t = useTranslation();
+  return (
+    <li className={styles.stateRow} role="presentation">
+      {/* aria-hidden because the Listbox status region renders this same key,
+          and both sit in the tree at once, so a reader met the sentence twice.
+          Naming the Retry button with it instead only MOVED that duplicate —
+          the region still said it and the button then said it again. The
+          region's text sits immediately before this list, so browse mode reads
+          "Failed to load options." and then "Retry, button": once each. */}
+      <span aria-hidden="true">{t('select.loadFailed')}</span>
+      <button type="button" className={styles.retryButton} onClick={onRetry}>
+        {t('select.retry')}
+      </button>
+    </li>
+  );
+}

package/src/components/Select/HiddenInputs.tsx

@@ -0,0 +1,44 @@
+export interface HiddenInputsProps {
+  name?: string;
+  value: string | string[];
+  multiple: boolean;
+  required: boolean;
+  form?: string;
+  disabled: boolean;
+}
+
+/**
+ * Renders the hidden `<input>`(s) so native `FormData` picks up the Select's
+ * value. Single mode renders one input. Multi mode renders one per selected
+ * value. Hidden inputs are barred from native constraint validation, so
+ * `required` is mirrored as form metadata only; consumers validate separately.
+ */
+export function HiddenInputs(props: HiddenInputsProps) {
+  if (!props.name) return null;
+  const { name, value, multiple, required, form, disabled } = props;
+
+  if (!multiple) {
+    const v = typeof value === 'string' ? value : '';
+    return (
+      <input
+        type="hidden"
+        name={name}
+        value={v}
+        required={required}
+        form={form}
+        disabled={disabled}
+      />
+    );
+  }
+  const arr = Array.isArray(value) ? value : [];
+  if (arr.length === 0 && required) {
+    return <input type="hidden" name={name} value="" required form={form} disabled={disabled} />;
+  }
+  return (
+    <>
+      {arr.map((v) => (
+        <input key={v} type="hidden" name={name} value={v} form={form} disabled={disabled} />
+      ))}
+    </>
+  );
+}