@eocrm/design-system 0.0.0-stage → 0.6.17

package/src/components/List/List.tsx

@@ -0,0 +1,124 @@
+import { createContext, forwardRef, useContext, type HTMLAttributes, type ReactNode } from 'react';
+import clsx from 'clsx';
+import styles from './List.module.scss';
+
+/**
+ * Marker style.
+ * - `'bullet'` (default) — a dot per item, rendered in a `<ul>`.
+ * - `'number'` — 1, 2, 3 per item, rendered in an `<ol>`.
+ */
+export type ListVariant = 'bullet' | 'number';
+
+/**
+ * Space between items.
+ * - `'xs'` — `var(--space-1)`; dense reference lists.
+ * - `'sm'` — `var(--space-2)` (default); prose rhythm.
+ * - `'md'` — `var(--space-3)`; items that wrap to several lines.
+ */
+export type ListGap = 'xs' | 'sm' | 'md';
+
+/**
+ * How `variant="number"` draws its numbers.
+ * - `'plain'` (default) — a muted figure.
+ * - `'badge'` — an accent badge for numbered steps: circular at body size, a rounded square at `size="heading"`. Ignored for bullets.
+ */
+export type ListNumberStyle = 'plain' | 'badge';
+
+/**
+ * Marker scale.
+ * - `'body'` (default) — marker sized to body text.
+ * - `'heading'` — marker sized and centred on the first line of a `Title size="xl"`; a badge becomes a rounded square.
+ */
+export type ListSize = 'body' | 'heading';
+
+export interface ListProps extends HTMLAttributes<HTMLElement> {
+  /** Marker style. See `ListVariant`. Default `'bullet'`. */
+  variant?: ListVariant;
+  /** Space between items. See `ListGap`. Default `'sm'`. */
+  gap?: ListGap;
+  /** Marker scale; use `'heading'` when each item starts with a `Title size="xl"`. See `ListSize`. Default `'body'`. */
+  size?: ListSize;
+  /** Number look; only applies to `variant="number"`. See `ListNumberStyle`. Default `'plain'`. */
+  numberStyle?: ListNumberStyle;
+  /** `List.Item` elements. A nested `List` goes inside a `List.Item`. */
+  children?: ReactNode;
+}
+
+export interface ListItemProps extends HTMLAttributes<HTMLLIElement> {
+  /** Item content. Text, inline elements, or a nested `List`. */
+  children?: ReactNode;
+}
+
+interface ListContext {
+  variant: ListVariant;
+  numberStyle: ListNumberStyle;
+}
+
+const Ctx = createContext<ListContext>({ variant: 'bullet', numberStyle: 'plain' });
+const DepthCtx = createContext(0);
+
+/**
+ * Semantic bulleted or numbered list of prose items (`<ul>` / `<ol>` with `List.Item`).
+ * @see docs/components/List.md
+ */
+const ListRoot = forwardRef<HTMLElement, ListProps>(function ListRoot(
+  {
+    variant = 'bullet',
+    gap = 'sm',
+    size = 'body',
+    numberStyle = 'plain',
+    className,
+    children,
+    ...rest
+  },
+  ref,
+) {
+  const depth = useContext(DepthCtx);
+  const Tag = variant === 'number' ? 'ol' : 'ul';
+  return (
+    <DepthCtx.Provider value={depth + 1}>
+      <Ctx.Provider value={{ variant, numberStyle }}>
+        <Tag
+          ref={ref as never}
+          // Explicit role: Safari/VoiceOver drops list semantics under `list-style: none`.
+          role="list"
+          data-gap={gap}
+          data-variant={variant}
+          data-size={size}
+          data-nested={depth > 0 ? 'true' : undefined}
+          className={clsx(styles.list, className)}
+          // {...rest} last so consumer overrides win (Pattern A).
+          {...rest}
+        >
+          {children}
+        </Tag>
+      </Ctx.Provider>
+    </DepthCtx.Provider>
+  );
+});
+
+/** One list entry; the marker is drawn here and hidden from assistive tech. */
+export const ListItem = forwardRef<HTMLLIElement, ListItemProps>(function ListItem(
+  { className, children, ...rest },
+  ref,
+) {
+  const { variant, numberStyle } = useContext(Ctx);
+  const inner =
+    variant === 'bullet' ? (
+      <span className={styles.bullet} />
+    ) : (
+      // Number comes from a CSS counter on ::before, so it survives wrappers that render 0 or 2 items.
+      <span className={numberStyle === 'badge' ? styles.badge : styles.number} />
+    );
+  return (
+    <li ref={ref} className={clsx(styles.item, className)} {...rest}>
+      <span aria-hidden="true" className={styles.marker}>
+        {inner}
+      </span>
+      <div className={styles.content}>{children}</div>
+    </li>
+  );
+});
+ListItem.displayName = 'ListItem';
+
+export const List = Object.assign(ListRoot, { Item: ListItem });

package/src/components/List/index.ts

@@ -0,0 +1,9 @@
+export {
+  List,
+  type ListProps,
+  type ListItemProps,
+  type ListVariant,
+  type ListGap,
+  type ListSize,
+  type ListNumberStyle,
+} from './List';

package/src/components/LiveRegion/LiveRegion.module.scss

@@ -0,0 +1,3 @@
+// LiveRegion delegates all styling to <VisuallyHidden> — no additional
+// styles needed. This file exists to satisfy the repo's four-file rule
+// (structure.test.ts).

package/src/components/LiveRegion/LiveRegion.tsx

@@ -0,0 +1,116 @@
+import { forwardRef, useEffect, useState, type HTMLAttributes, type ReactNode } from 'react';
+import { VisuallyHidden } from '../VisuallyHidden';
+
+/** How urgently the region interrupts the screen reader. See {@link LiveRegionProps.politeness}. */
+export type LiveRegionPoliteness = 'polite' | 'assertive';
+
+export interface LiveRegionProps extends Omit<
+  HTMLAttributes<HTMLSpanElement>,
+  'children' | 'role' | 'aria-live' | 'aria-atomic' | 'hidden' | 'aria-hidden'
+> {
+  /**
+   * The message. Pass a string, a number, or an array of only strings/
+   * numbers (e.g. `[count, ' files uploaded']`) — these compare by value, so
+   * an unchanged value does not re-announce and a changed one does. Anything
+   * else (JSX elements) compares by identity and re-announces on every
+   * parent render, even when the rendered text is unchanged. Empty, `null`,
+   * or `false` clears the region and announces nothing.
+   */
+  children?: ReactNode;
+  /**
+   * How urgently the region interrupts.
+   * - `'polite'` (default) — `role="status"` + `aria-live="polite"`. Waits
+   *   for the screen reader to finish its current utterance. Use for routine
+   *   outcomes: saves, copy confirmations, background updates.
+   * - `'assertive'` — `role="alert"` + `aria-live="assertive"`. Interrupts
+   *   immediately. Reserve for errors that need immediate attention.
+   *
+   * Change politeness in the SAME render as the message
+   * (`politeness={error ? 'assertive' : 'polite'}` next to `{error ?? status}`):
+   * the role only flips while the region is empty, so the old text is never
+   * announced at the new urgency. A politeness-only change re-announces the
+   * current text at the new urgency.
+   * @default 'polite'
+   */
+  politeness?: LiveRegionPoliteness;
+  /**
+   * Change this (e.g. a counter) to announce the same message again. Without
+   * it, re-rendering with identical text is a no-op — screen readers only
+   * announce a live region on a text change.
+   */
+  announceKey?: string | number;
+}
+
+const ANNOUNCE_DELAY_MS = 50;
+
+/** `true` if every element of `arr` is a string or number, so it can be joined into one comparison value. */
+function isPrimitiveArray(arr: unknown[]): arr is Array<string | number> {
+  return arr.every((item) => typeof item === 'string' || typeof item === 'number');
+}
+
+/**
+ * The value used both as the effect dependency (change detection) and as
+ * the content written to the region. Strings/numbers compare by value.
+ * Arrays of only strings/numbers (e.g. `[count, ' files uploaded']`) are
+ * joined into one string so identical content doesn't re-announce merely
+ * because a new array literal was passed. Anything else (elements, mixed
+ * arrays) is returned as-is and compared by identity.
+ */
+function toMessage(children: ReactNode): ReactNode {
+  if (typeof children === 'string' || typeof children === 'number') {
+    return String(children);
+  }
+  if (Array.isArray(children) && isPrimitiveArray(children)) {
+    return children.join('');
+  }
+  return children;
+}
+
+/**
+ * A visually-hidden, always-mounted `role="status"`/`role="alert"` announcement region for consumer-level outcomes with no visible text.
+ * @see docs/components/LiveRegion.md
+ */
+export const LiveRegion = forwardRef<HTMLSpanElement, LiveRegionProps>(function LiveRegion(
+  { children, politeness = 'polite', announceKey, ...props },
+  ref,
+) {
+  const [shown, setShown] = useState<ReactNode>(null);
+  // The politeness actually on the DOM. It only changes in the same state
+  // update that empties the region, so role / aria-live never flip on a region
+  // still holding the OLD text (`politeness={error ? 'assertive' : 'polite'}`
+  // would otherwise re-announce the stale message as an alert).
+  const [applied, setApplied] = useState<LiveRegionPoliteness>(politeness);
+  const message = toMessage(children);
+
+  useEffect(() => {
+    // Clear, then write in a later tick: the region goes empty → text, which
+    // screen readers treat as a fresh change — that is what makes a mount-
+    // with-message and an identical re-announce (announceKey) both fire.
+    // `message` is captured from this effect's own render closure, not a
+    // ref written during render, so a discarded/re-run render (StrictMode,
+    // concurrent features) can never write stale content.
+    setShown(null);
+    setApplied(politeness);
+    const id = setTimeout(() => setShown(message), ANNOUNCE_DELAY_MS);
+    return () => clearTimeout(id);
+  }, [message, announceKey, politeness]);
+
+  // {...props} first so role / aria-live / aria-atomic always win (Pattern
+  // B) — including against `hidden` / `aria-hidden` arriving through an
+  // untyped spread (the props type omits them, but a caller can still
+  // forward them via `{...someUntypedRest}`; either would silence the
+  // region, so both are force-cleared here too).
+  return (
+    <VisuallyHidden
+      {...props}
+      ref={ref}
+      role={applied === 'assertive' ? 'alert' : 'status'}
+      aria-live={applied}
+      aria-atomic="true"
+      hidden={undefined}
+      aria-hidden={undefined}
+    >
+      {shown}
+    </VisuallyHidden>
+  );
+});

package/src/components/LiveRegion/index.ts

@@ -0,0 +1,2 @@
+export { LiveRegion } from './LiveRegion';
+export type { LiveRegionProps, LiveRegionPoliteness } from './LiveRegion';

package/src/components/Logo/Logo.module.scss

@@ -0,0 +1,139 @@
+@use './Logo.tokens';
+
+.logo {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--logo-gap);
+}
+
+.bottom {
+  flex-direction: column;
+}
+
+.mark {
+  flex-shrink: 0;
+  object-fit: contain;
+}
+
+.text {
+  color: var(--color-fg);
+
+  // Wordmark font/weight — overridable via --logo-text-font / --logo-text-font-weight.
+  // Read with fallbacks (NOT declared as a :root default) so a consumer's :root
+  // override always wins, regardless of when this component CSS is injected.
+  font-family: var(--logo-text-font, inherit);
+  font-weight: var(--logo-text-font-weight, var(--font-weight-bold));
+  line-height: 1.1;
+}
+
+.textBlock {
+  display: flex;
+  flex-direction: column;
+}
+
+.subtext {
+  color: var(--color-fg-muted);
+  font-size: var(--font-size-xs);
+  line-height: 1.2;
+}
+
+// Optical alignment. Half-leading makes a wordmark's *box* taller than its
+// glyphs, so a lockup centered on the box reads as sitting low next to the mark.
+// text-box-trim removes that leading and aligns to the real cap/x-height edges,
+// which lets the block collapse to line-height: 1 and the mark↔wordmark gap
+// become an exact token value.
+// Gated because Firefox ships neither property (as of 2026-08). Ungated, the
+// declarations would drop but `line-height: 1` would stick, collapsing the line
+// box to exactly the font size — ascenders and descenders would then overflow
+// and get clipped by Rail.Header's `overflow: hidden`. Keeping the whole block
+// behind @supports means non-supporting browsers render byte-identically to the
+// pre-trim lockup: looser, never clipped.
+@supports (text-box-trim: trim-both) {
+  .text {
+    line-height: 1;
+    text-box-trim: trim-both;
+  }
+
+  // Trim to the cap edge by default, to the x-height edge for a wordmark whose
+  // glyphs all top out at x-height — see getTextMetric() in Logo.tsx for which
+  // is which, and why neither edge is an ink-tight guarantee.
+  .textCap {
+    text-box-edge: cap alphabetic;
+  }
+
+  .textEx {
+    text-box-edge: ex alphabetic;
+  }
+
+  // Trimmed edges leave the wordmark and subtext touching, so the gap that was
+  // previously supplied by leading now has to be declared.
+  .textBlock {
+    gap: var(--logo-text-gap);
+  }
+
+  // A wordmark with a subtext under it needs its descenders inside its own box.
+  // The `alphabetic` under-edge stops at the baseline, so descender ink hangs
+  // outside the box and eats into the gap below it — `paygo` in Outfit measures
+  // 3.5 / 4.4 / 5.25px of overhang at sm/md/lg against a flat 4px gap, so the
+  // tails already cross into the subtext at md, not just at lg. `text` puts the
+  // under-edge at the font's descent instead, so --logo-text-gap is real
+  // whitespace at every size.
+  // Scoped to the subtext case: on its own the wordmark should still sit on its
+  // baseline so it optically centers against the mark.
+  .textCap:has(+ .subtext) {
+    text-box-edge: cap text;
+  }
+
+  .textEx:has(+ .subtext) {
+    text-box-edge: ex text;
+  }
+
+  // Always cap, never ex: a subtext is sentence-case far more often than not
+  // ("Free trial", "Pro (yearly)"), and trimming those to the x-height edge
+  // would put the capital's ink outside the box and pull the line up into the
+  // wordmark's descenders.
+  // The under-edge stays `alphabetic` (not `text` like the wordmark's): the
+  // subtext is the last line, so nothing below needs clearing, and a descent-
+  // deep box would just pad the lockup. The trade is that a subtext WITH
+  // descenders puts ~2px of ink below the lockup's own bottom edge at sm (its
+  // worst case — at md/lg the taller mark absorbs it). That sits inside
+  // Rail.Header's bottom padding, but a consumer clipping a box sized exactly to
+  // the lockup would shave those tails.
+  .subtext {
+    line-height: 1;
+    text-box-trim: trim-both;
+    text-box-edge: cap alphabetic;
+  }
+}
+
+.bottom .textBlock {
+  align-items: center;
+  text-align: center;
+}
+
+.sizeSm .mark {
+  width: var(--size-sm);
+  height: var(--size-sm);
+}
+
+.sizeSm .text {
+  font-size: var(--font-size-lg);
+}
+
+.sizeMd .mark {
+  width: var(--size-md);
+  height: var(--size-md);
+}
+
+.sizeMd .text {
+  font-size: var(--font-size-xl);
+}
+
+.sizeLg .mark {
+  width: var(--size-lg);
+  height: var(--size-lg);
+}
+
+.sizeLg .text {
+  font-size: var(--font-size-2xl);
+}

package/src/components/Logo/Logo.tokens.scss

@@ -0,0 +1,14 @@
+:root {
+  // Gap between the mark and the wordmark.
+  --logo-gap: var(--space-2);
+
+  // Gap between the wordmark and the subtext. Only applies where text-box-trim
+  // is supported — without it the leading already supplies the separation.
+  --logo-text-gap: var(--space-1);
+}
+
+// Wordmark typography is overridable via --logo-text-font / --logo-text-font-weight
+// to set a brand font/weight for the wordmark `text` (the mark is an image; the
+// `subtext` is NOT affected). These are intentionally read with fallbacks in
+// Logo.module.scss rather than declared at :root here — so a consumer's :root
+// override wins regardless of CSS injection order. Defaults: inherited font, bold.

package/src/components/Logo/Logo.tsx

@@ -0,0 +1,126 @@
+import { forwardRef, type HTMLAttributes, type ReactNode } from 'react';
+import clsx from 'clsx';
+import styles from './Logo.module.scss';
+
+/** Mark size — `sm` (24) / `md` (32, default) / `lg` (40); the shared `--size-*` scale. */
+export type LogoSize = 'sm' | 'md' | 'lg';
+
+/** Where the wordmark sits relative to the mark. */
+export type LogoTextPlacement = 'end' | 'bottom';
+
+export interface LogoProps extends HTMLAttributes<HTMLDivElement> {
+  /**
+   * The brand mark image URL — typically an imported SVG/PNG asset. The mark is
+   * a **consumer-owned asset**; the design system ships no logo of its own.
+   * Rendered as an `<img>` (`object-fit: contain`) with no CSS recolor — the
+   * asset carries its own color. For third-party SSO marks use `<BrandIcon>`.
+   */
+  src: string;
+  /**
+   * Wordmark rendered beside (or below) the mark — consumers pass `"eocrm"`.
+   * Omit for a mark-only logo.
+   */
+  text?: ReactNode;
+  /**
+   * Where the wordmark sits relative to the mark. Defaults to `'end'` (beside);
+   * `'bottom'` stacks it under the mark, centered.
+   */
+  textPlacement?: LogoTextPlacement;
+  /** Mark size — `'sm'` (24) / `'md'` (32, default) / `'lg'` (40). */
+  size?: LogoSize;
+  /**
+   * Accessible name for the mark when there's no `text` (used as the image
+   * `alt`). Omit for a decorative mark (`alt=""`), or when `text` is present
+   * (the wordmark is the name). Never pass both `text` and `label`.
+   */
+  label?: string;
+  /**
+   * Small, muted secondary line rendered under `text` — e.g. a plan or tagline
+   * (`subtext="Free trial"`). Only shown when `text` is present.
+   */
+  subtext?: ReactNode;
+}
+
+const sizeClass: Record<LogoSize, string> = {
+  sm: styles.sizeSm,
+  md: styles.sizeMd,
+  lg: styles.sizeLg,
+};
+
+/**
+ * Latin lowercase letters that top out at x-height, plus separators that never
+ * rise above it (`.` sits on the baseline, `,` hangs below it, `-` is
+ * mid-x-height, space has no ink). Deliberately an allowlist rather than "no
+ * uppercase": the ascenders
+ * (`b d f h k l t`), the dotted `i`/`j`, digits, and every non-Latin script
+ * reach well above x-height. Descenders (`g p q y`) are in the set — the
+ * under-edge is the same in both branches, so they're unaffected by the choice.
+ *
+ * "Tops out at x-height" is the type designer's line, not a pixel guarantee: the
+ * round letters (`a c e o s`) overshoot it by ~1% of em in most faces, `eocrm`
+ * included. That overshoot is inherent to `ex` and far too small to read as
+ * misalignment; it's the ascender-sized differences this list exists to catch.
+ *
+ * The lookahead requires at least one letter, so a whitespace- or
+ * punctuation-only wordmark doesn't qualify on a technicality.
+ */
+const X_HEIGHT_ONLY = /^(?=.*[acemnopqrsuvwxyzg])[acemnopqrsuvwxyzg\s\-.,]+$/;
+
+/**
+ * Which edge the wordmark's text box should be trimmed to. `ex` pulls the box
+ * down to the x-height so an all-lowercase wordmark optically centers against
+ * the mark; `cap` is the conservative choice everywhere else.
+ *
+ * Note `cap` is not an ink-tight guarantee either — in most text faces the
+ * ascender sits slightly above cap height, and diacritics (`É`, `Å`, `Й`) sit
+ * above both. Neither clips: `text-box-trim` resizes the box, it does not crop
+ * what overflows it. The choice is about where the lockup's optical centre
+ * lands, and `cap` errs toward leaving headroom rather than removing too much.
+ */
+function getTextMetric(text: ReactNode): 'cap' | 'ex' {
+  // A non-string wordmark (an element, a fragment) has no inspectable glyphs,
+  // so fall back to the conservative edge.
+  if (typeof text !== 'string') {
+    return 'cap';
+  }
+
+  return X_HEIGHT_ONLY.test(text) ? 'ex' : 'cap';
+}
+
+/**
+ * Brand logo lockup: a consumer-supplied mark image, optionally with a wordmark beside or below and a muted subline.
+ * @see docs/components/Logo.md
+ */
+export const Logo = forwardRef<HTMLDivElement, LogoProps>(function Logo(
+  { src, text, subtext, textPlacement = 'end', size = 'md', label, className, ...props },
+  ref,
+) {
+  // With `text`, the wordmark conveys the name → the mark is decorative (alt="").
+  // Mark-only → `label` is the accessible name; absent → decorative.
+  const alt = text == null && label ? label : '';
+  const textMetric = getTextMetric(text);
+
+  return (
+    // Pattern A — props last: Logo is consumer-overridable brand chrome.
+    <div
+      ref={ref}
+      className={clsx(
+        styles.logo,
+        sizeClass[size],
+        textPlacement === 'bottom' && styles.bottom,
+        className,
+      )}
+      {...props}
+    >
+      <img className={styles.mark} src={src} alt={alt} />
+      {text != null && (
+        <span className={styles.textBlock}>
+          <span className={clsx(styles.text, textMetric === 'ex' ? styles.textEx : styles.textCap)}>
+            {text}
+          </span>
+          {subtext != null && <span className={styles.subtext}>{subtext}</span>}
+        </span>
+      )}
+    </div>
+  );
+});

package/src/components/Logo/index.ts

@@ -0,0 +1,2 @@
+export { Logo } from './Logo';
+export type { LogoProps, LogoSize, LogoTextPlacement } from './Logo';

package/src/components/Masonry/Masonry.module.scss

@@ -0,0 +1,42 @@
+@use './Masonry.tokens';
+
+.masonry {
+  display: flex;
+  align-items: flex-start;
+  width: 100%;
+}
+
+.column {
+  display: flex;
+  flex-direction: column;
+  flex: 1 1 0;
+  min-width: 0;
+}
+
+.cell {
+  width: 100%;
+}
+
+.gapXs {
+  gap: var(--masonry-gap-xs);
+}
+
+.gapSm {
+  gap: var(--masonry-gap-sm);
+}
+
+.gapMd {
+  gap: var(--masonry-gap-md);
+}
+
+.gapLg {
+  gap: var(--masonry-gap-lg);
+}
+
+.gapXl {
+  gap: var(--masonry-gap-xl);
+}
+
+.gap2xl {
+  gap: var(--masonry-gap-2xl);
+}

package/src/components/Masonry/Masonry.tokens.scss

@@ -0,0 +1,8 @@
+:root {
+  --masonry-gap-xs: var(--space-1);
+  --masonry-gap-sm: var(--space-2);
+  --masonry-gap-md: var(--space-3);
+  --masonry-gap-lg: var(--space-4);
+  --masonry-gap-xl: var(--space-6);
+  --masonry-gap-2xl: var(--space-8);
+}