@eocrm/design-system 0.0.0-stage → 0.6.18

package/src/components/OptionsPicker/index.ts

@@ -0,0 +1,9 @@
+export { OptionsPicker } from './OptionsPicker';
+export type {
+  OptionsPickerProps,
+  OptionsPickerContentProps,
+  OptionsPickerTriggerProps,
+  OptionsPickerMode,
+  OptionsPickerOption,
+  OptionsPickerGroup,
+} from './OptionsPicker';

package/src/components/OtpInput/OtpInput.module.scss

@@ -0,0 +1,69 @@
+@use '../../styles/mixins' as *;
+@use './OtpInput.tokens';
+
+.root {
+  display: inline-flex;
+  flex-wrap: wrap;
+  gap: var(--otp-input-gap);
+}
+
+.cell {
+  padding: 0;
+  border: var(--border-width) solid var(--otp-input-border-color);
+  border-radius: var(--otp-input-radius);
+  background: var(--otp-input-bg);
+  color: var(--otp-input-fg);
+  font-family: inherit;
+  font-variant-numeric: tabular-nums;
+  text-align: center;
+  transition:
+    border-color var(--transition-fast),
+    outline-color var(--transition-fast);
+
+  &:focus-visible {
+    border-color: var(--otp-input-border-color-focus);
+
+    @include focus-ring(var(--otp-input-ring-focus));
+  }
+
+  &:disabled {
+    background: var(--otp-input-bg-disabled);
+    border-color: var(--otp-input-border-color-disabled);
+    color: var(--otp-input-fg-disabled);
+    cursor: not-allowed;
+  }
+}
+
+.size-sm {
+  width: var(--otp-input-cell-size-sm);
+  height: var(--otp-input-cell-size-sm);
+  font-size: var(--otp-input-font-size-sm);
+}
+
+.size-md {
+  width: var(--otp-input-cell-size-md);
+  height: var(--otp-input-cell-size-md);
+  font-size: var(--otp-input-font-size-md);
+}
+
+.size-lg {
+  width: var(--otp-input-cell-size-lg);
+  height: var(--otp-input-cell-size-lg);
+  font-size: var(--otp-input-font-size-lg);
+}
+
+.size-xl {
+  width: var(--otp-input-cell-size-xl);
+  height: var(--otp-input-cell-size-xl);
+  font-size: var(--otp-input-font-size-xl);
+}
+
+.invalid {
+  border-color: var(--otp-input-border-color-invalid);
+
+  &:focus-visible {
+    border-color: var(--otp-input-border-color-invalid);
+
+    @include focus-ring(var(--otp-input-ring-invalid));
+  }
+}

package/src/components/OtpInput/OtpInput.tokens.scss

@@ -0,0 +1,45 @@
+// OtpInput.tokens.scss — component-scoped tokens for <OtpInput>. Every value
+// aliases the <Input> family or a primitive, so a code field sits flush with a
+// same-size Input or Button without visual drift.
+@use '../Input/Input.tokens';
+
+:root {
+  // Group
+  --otp-input-gap: var(--space-2);
+
+  // Cell surface
+  --otp-input-bg: var(--input-bg);
+  --otp-input-fg: var(--input-fg);
+  --otp-input-border-color: var(--input-border-color);
+  --otp-input-radius: var(--input-radius);
+
+  // Focus
+  --otp-input-border-color-focus: var(--input-border-color-focus);
+  --otp-input-ring-focus: var(--input-ring-focus);
+
+  // Disabled
+  --otp-input-bg-disabled: var(--input-bg-disabled);
+  --otp-input-border-color-disabled: var(--input-border-color-disabled);
+  --otp-input-fg-disabled: var(--input-fg-disabled);
+
+  // Invalid
+  --otp-input-border-color-invalid: var(--input-border-color-invalid);
+  --otp-input-ring-invalid: var(--input-ring-invalid);
+
+  // Size — square cell, matching the <Input> height scale so an OtpInput
+  // lines up with the fields around it.
+  --otp-input-cell-size-sm: var(--size-sm);
+  --otp-input-cell-size-md: var(--size-md);
+  --otp-input-cell-size-lg: var(--size-lg);
+
+  // No <Input> step this big: --size-xl (80px) would overflow a phone at six
+  // cells, so xl has its own 48px primitive.
+  --otp-input-cell-size-xl: var(--size-otp-cell-xl);
+
+  // Size — a code is read back character by character, so the glyph runs one
+  // step larger than the equivalent <Input>.
+  --otp-input-font-size-sm: var(--font-size-md);
+  --otp-input-font-size-md: var(--font-size-lg);
+  --otp-input-font-size-lg: var(--font-size-xl);
+  --otp-input-font-size-xl: var(--font-size-2xl);
+}

package/src/components/OtpInput/OtpInput.tsx

@@ -0,0 +1,368 @@
+import {
+  forwardRef,
+  useCallback,
+  useLayoutEffect,
+  useRef,
+  useState,
+  type ChangeEvent,
+  type FocusEvent as ReactFocusEvent,
+  type HTMLAttributes,
+  type KeyboardEvent as ReactKeyboardEvent,
+  type MouseEvent as ReactMouseEvent,
+} from 'react';
+import clsx from 'clsx';
+import { useControllableState } from '../_internal/useControllableState';
+import { useTranslation } from '../../i18n';
+import styles from './OtpInput.module.scss';
+
+/** Cell height. Matches the `<Input>` / `<Button>` size scale. */
+export type OtpInputSize = 'sm' | 'md' | 'lg' | 'xl';
+
+/**
+ * Which characters the code is made of.
+ * - `'numeric'` — digits only (default). What SMS and email one-time codes
+ *   almost always are, and what the numeric mobile keypad is for.
+ * - `'alphanumeric'` — digits plus Latin letters, normalized to uppercase.
+ */
+export type OtpInputType = 'numeric' | 'alphanumeric';
+
+const SANITIZE: Record<OtpInputType, (raw: string) => string> = {
+  numeric: (raw) => raw.replace(/[^0-9]/g, ''),
+  alphanumeric: (raw) => raw.replace(/[^0-9a-z]/gi, '').toUpperCase(),
+};
+
+/**
+ * Props for {@link OtpInput}. Extends `HTMLAttributes<HTMLDivElement>` (minus
+ * `onChange` and `defaultValue`, which are redeclared below with
+ * component-specific signatures) since the group `<div>` is the element a
+ * consumer ultimately controls.
+ */
+export interface OtpInputProps extends Omit<
+  HTMLAttributes<HTMLDivElement>,
+  'onChange' | 'defaultValue'
+> {
+  /** How many boxes to render. Default `6`. */
+  length?: number;
+  /**
+   * Controlled code. Sanitized and truncated to `length` on render, so a
+   * consumer echoing back a dirty string sees it cleaned rather than
+   * mis-sliced. Pair with `onChange`.
+   */
+  value?: string;
+  /** Uncontrolled seed. Ignored when `value` is supplied. */
+  defaultValue?: string;
+  /**
+   * Fires on every edit with the whole code so far — always sanitized, never
+   * longer than `length`, and never with a gap in the middle.
+   */
+  onChange?: (value: string) => void;
+  /**
+   * Fires whenever the code becomes full with a value different from the
+   * last one — not on every keystroke while it is full. Use it to submit.
+   * Correcting a wrong character inside an already-full code re-fires with
+   * the corrected value; retyping the same character does not, since
+   * nothing changed.
+   */
+  onComplete?: (value: string) => void;
+  /** Character set. Default `'numeric'`. See `OtpInputType`. */
+  type?: OtpInputType;
+  /**
+   * Cell size. Default `'md'`.
+   * - `'sm'` — 24px cells; dense admin screens.
+   * - `'md'` — 32px cells (default); most forms.
+   * - `'lg'` — 40px cells; a dedicated verification screen.
+   * - `'xl'` — 48px cells; a code field that IS the screen (IdP login
+   *   challenge, touch-first). Six cells still fit a 360px phone. No
+   *   `<Input>` counterpart at this height — don't line it up with fields.
+   */
+  size?: OtpInputSize;
+  /**
+   * Error visual on every cell plus `aria-invalid="true"`. Pair with a visible
+   * message and point `aria-describedby` at it (or wrap in `<Field error>`).
+   */
+  invalid?: boolean;
+  /** Disable every cell. */
+  disabled?: boolean;
+  /**
+   * Marks the field required. There is no single native input to attach the
+   * native `required` attribute to — a per-cell `required` would let the
+   * browser block submit on an empty first cell while accepting a
+   * 1-of-`length` code as complete, which is worse than no native gate at
+   * all. Sets `aria-required="true"` on every cell instead (the group's
+   * `role="group"` does not support `aria-required` per ARIA 1.2 — only
+   * `textbox` and a handful of other roles do), the same way `aria-invalid`
+   * and `aria-describedby` are already repeated on every cell. Validating
+   * completeness is the consumer's job (pair with `invalid` + `onComplete`).
+   */
+  required?: boolean;
+  /** Focus the first cell on mount. */
+  autoFocus?: boolean;
+  /** Id for the first cell, so an external `<label htmlFor>` focuses the field. */
+  id?: string;
+  /**
+   * Accessible name for the group. Defaults to the localized
+   * `otpInput.groupLabel` ("Verification code") when omitted OR empty — an
+   * empty string is not an explicit name — so a standalone OtpInput is never
+   * an unnamed group.
+   */
+  'aria-label'?: string;
+  /** Ids of elements naming the group. Injected by `<Field>`; wins over `aria-label`. */
+  'aria-labelledby'?: string;
+  /** Ids of description / error elements. Set on EVERY cell — see the remarks. */
+  'aria-describedby'?: string;
+}
+
+/**
+ * One-time-code field: `length` single-character boxes behaving as one control, with `autocomplete="one-time-code"` and auto-advance.
+ * @see docs/components/OtpInput.md
+ */
+export const OtpInput = forwardRef<HTMLDivElement, OtpInputProps>(function OtpInput(
+  {
+    length = 6,
+    value,
+    defaultValue,
+    onChange,
+    onComplete,
+    type = 'numeric',
+    size = 'md',
+    invalid,
+    disabled,
+    required,
+    autoFocus,
+    id,
+    'aria-label': ariaLabel,
+    'aria-labelledby': ariaLabelledby,
+    'aria-describedby': ariaDescribedby,
+    className,
+    ...rest
+  },
+  ref,
+) {
+  const t = useTranslation();
+  const sanitize = SANITIZE[type];
+
+  const [rawValue, setRawValue] = useControllableState<string>({
+    value,
+    defaultValue: defaultValue ?? '',
+    onChange,
+  });
+  const code = sanitize(rawValue ?? '').slice(0, length);
+
+  // The code is always contiguous, so the only reachable cells are the filled
+  // ones plus the first empty one.
+  const lastReachable = Math.min(code.length, length - 1);
+
+  const cellsRef = useRef<(HTMLInputElement | null)[]>([]);
+  const [focusedIndex, setFocusedIndex] = useState<number | null>(null);
+  // Standard roving tabindex: the group remembers where focus left it.
+  const activeIndex = Math.min(focusedIndex ?? lastReachable, lastReachable);
+
+  // The select() calls in focusCell/onClick/handleFocus run BEFORE the
+  // commit they're reacting to has rendered. That's durable only when React's
+  // controlled-input diff then skips writing `node.value` — true when the
+  // sanitized commit equals the raw keystroke, but false the moment
+  // sanitizing actually transforms the character (alphanumeric mode
+  // uppercasing a lowercase letter, for instance): React DOES write
+  // node.value on that render and collapses whatever was selected before it,
+  // so a second overtype keystroke right behind the first gets appended
+  // instead of replacing, and is silently sliced back off. Re-select after
+  // every commit, once React has actually written the DOM, so the selection
+  // this render leaves behind is the one the NEXT keystroke will see —
+  // regardless of whether sanitizing changed anything. A no-op on an empty
+  // cell, and skipped entirely when focus isn't on the active cell (Tab,
+  // Arrow, Home/End, and click already select correctly on their own).
+  useLayoutEffect(() => {
+    const cell = cellsRef.current[activeIndex];
+    if (cell && document.activeElement === cell) cell.select();
+  }, [code, activeIndex]);
+
+  const focusCell = useCallback((index: number) => {
+    const cell = cellsRef.current[index];
+    // `focus()` on an already-focused cell fires no focus event, so
+    // `handleFocus`'s select() below never runs — select here too, so
+    // overtyping the cell the user is already sitting in (fixing the last
+    // digit typed) replaces it instead of silently appending and truncating
+    // back to the same value.
+    cell?.focus();
+    cell?.select();
+  }, []);
+
+  const commit = useCallback(
+    (next: string) => {
+      setRawValue(next);
+      // Fire on any transition INTO a full-and-different code, not just the
+      // empty→full one: a corrected digit inside an already-full code (mistype,
+      // then fix the last character) is a real completion the consumer must
+      // hear about. Guarding on the value rather than just the length also
+      // means a same-value overtype (retyping the digit already there) does
+      // NOT re-fire — nothing about the code actually changed.
+      if (next.length === length && next !== code) onComplete?.(next);
+    },
+    [setRawValue, length, code, onComplete],
+  );
+
+  const handleChange = (rawIndex: number) => (event: ChangeEvent<HTMLInputElement>) => {
+    // A controlled `value` can shrink out from under a focused cell — the
+    // standard "clear the code after a failed check" reset — leaving DOM
+    // focus on a cell past the contiguous range while `lastReachable` has
+    // already moved. At an out-of-range rawIndex this clamp doesn't change
+    // what the splice below commits: `code.slice(0, rawIndex) === code`
+    // (slicing past the end returns the whole string) AND the tail slice
+    // `code.slice(rawIndex + chars.length)` is also `''`, so the splice
+    // computes the same value whether or not the index is clamped. The
+    // clamp's only observable effect is the `focusCell` target a few lines
+    // down, which is what pulls focus back into range.
+    const index = Math.min(rawIndex, code.length);
+    const chars = sanitize(event.target.value);
+    if (chars.length === 0) {
+      // "Sanitizes to empty" also happens when the sanitizer REJECTS a
+      // character (a letter in numeric mode) typed over a filled, selected
+      // cell — that must be a no-op, not a truncation. Only a genuinely
+      // emptied cell (raw value itself is '') truncates the code from here
+      // on, so `value` stays a contiguous string that maps 1:1 onto the
+      // cells. React restores the cell's committed character on its own.
+      if (event.target.value === '') commit(code.slice(0, index));
+      return;
+    }
+    // A delivery of exactly `length` characters IS the whole code — the
+    // platform dumps it into whichever cell happens to be focused, not
+    // necessarily the first — so it replaces the value outright rather than
+    // splicing in at that position, which would scatter it across two spots.
+    // A shorter (or over-long, uncommon) delivery keeps the splice-and-slice
+    // behavior, unchanged.
+    const next =
+      chars.length === length
+        ? chars
+        : (code.slice(0, index) + chars + code.slice(index + chars.length)).slice(0, length);
+    commit(next);
+    focusCell(Math.min(index + chars.length, length - 1));
+  };
+
+  const handleKeyDown = (rawIndex: number) => (event: ReactKeyboardEvent<HTMLInputElement>) => {
+    // Same stranding as handleChange's clamp: a controlled `value` shrink can
+    // leave DOM focus past the code's contiguous end. Unlike that clamp, which
+    // only ever redirects focus (see its comment), this one changes what gets
+    // committed. Backspace is the only case that reads `code`, and at an
+    // out-of-range index `code.slice(0, index - 1)` returns the whole string
+    // (`'1'.slice(0, 4) === '1'`), so the commit is a no-op and Backspace
+    // silently deletes nothing. Backspace and ArrowLeft are also the only
+    // cases that step focus from this index — Home and End ignore it, and
+    // ArrowRight is already bounded by lastReachable.
+    const index = Math.min(rawIndex, code.length);
+    switch (event.key) {
+      case 'Backspace':
+        // A filled cell is handled natively: focus selected its content, so
+        // Backspace deletes it and fires `change`. An empty cell has nothing
+        // to delete, so step back and clear the previous one instead.
+        if (!code[index] && index > 0) {
+          event.preventDefault();
+          commit(code.slice(0, index - 1));
+          focusCell(index - 1);
+        }
+        break;
+      case 'ArrowLeft':
+        event.preventDefault();
+        focusCell(Math.max(0, index - 1));
+        break;
+      case 'ArrowRight':
+        event.preventDefault();
+        focusCell(Math.min(lastReachable, index + 1));
+        break;
+      case 'Home':
+        event.preventDefault();
+        focusCell(0);
+        break;
+      case 'End':
+        event.preventDefault();
+        focusCell(lastReachable);
+        break;
+      default:
+        // A keystroke that reproduces the character already in the cell
+        // leaves the DOM value byte-identical, so React's value tracker
+        // fires no change event at all — `handleChange` never runs, nothing
+        // re-selects, and the caret is left collapsed. Every keystroke after
+        // that would then append instead of replace and get sliced back off
+        // by the length cap, bricking the cell. Select on the keystroke
+        // itself so the next character always lands on a selected cell
+        // regardless of whether this one produced a change event.
+        if (event.key.length === 1 && !event.ctrlKey && !event.metaKey && !event.altKey) {
+          event.currentTarget.select();
+        }
+        break;
+    }
+  };
+
+  // Clicking a cell beyond the first empty one would otherwise drop the
+  // character somewhere other than where it was aimed, because the code is
+  // contiguous. Redirect on mousedown, where `code` is still the rendered
+  // value — doing it in `onFocus` would race our own programmatic focus.
+  const handleMouseDown = (index: number) => (event: ReactMouseEvent<HTMLInputElement>) => {
+    if (index > lastReachable) {
+      event.preventDefault();
+      focusCell(lastReachable);
+    }
+  };
+
+  const handleFocus = (index: number) => (event: ReactFocusEvent<HTMLInputElement>) => {
+    setFocusedIndex(index);
+    // Select-on-focus is what makes typing into a filled cell a replacement
+    // rather than an append, so a multi-character `change` can only mean a
+    // paste or an autofill.
+    event.target.select();
+  };
+
+  // Re-clicking a cell that already has focus moves the caret but fires no
+  // focus event, so it needs its own select — same reasoning as `focusCell`.
+  // Only when it really has focus: Chromium's select() also FOCUSES, so on a
+  // click that `handleMouseDown` redirected it would pull focus back to the
+  // clicked cell and undo the redirect (#597).
+  const handleClick = (event: ReactMouseEvent<HTMLInputElement>) => {
+    if (document.activeElement === event.currentTarget) event.currentTarget.select();
+  };
+
+  const cellLabel = type === 'numeric' ? 'otpInput.digit' : 'otpInput.character';
+
+  return (
+    <div
+      // {...rest} first so the structural ARIA contract — role=group and the
+      // resolved group name — cannot be clobbered by a consumer.
+      {...rest}
+      ref={ref}
+      role="group"
+      aria-label={ariaLabelledby ? undefined : ariaLabel || t('otpInput.groupLabel')}
+      aria-labelledby={ariaLabelledby}
+      className={clsx(styles.root, className)}
+    >
+      {Array.from({ length }, (_unused, index) => (
+        <input
+          key={index}
+          ref={(node) => {
+            cellsRef.current[index] = node;
+          }}
+          type="text"
+          value={code[index] ?? ''}
+          onChange={handleChange(index)}
+          onKeyDown={handleKeyDown(index)}
+          onMouseDown={handleMouseDown(index)}
+          onFocus={handleFocus(index)}
+          onClick={handleClick}
+          id={index === 0 ? id : undefined}
+          autoFocus={autoFocus && index === 0}
+          disabled={disabled}
+          tabIndex={index === activeIndex ? 0 : -1}
+          inputMode={type === 'numeric' ? 'numeric' : 'text'}
+          pattern={type === 'numeric' ? '[0-9]*' : undefined}
+          autoComplete="one-time-code"
+          autoCorrect="off"
+          autoCapitalize="off"
+          spellCheck={false}
+          aria-label={t(cellLabel, { index: index + 1, total: length })}
+          aria-invalid={invalid || undefined}
+          aria-required={required || undefined}
+          aria-describedby={ariaDescribedby}
+          className={clsx(styles.cell, styles[`size-${size}`], invalid && styles.invalid)}
+        />
+      ))}
+    </div>
+  );
+});

package/src/components/OtpInput/index.ts

@@ -0,0 +1,2 @@
+export { OtpInput } from './OtpInput';
+export type { OtpInputProps, OtpInputSize, OtpInputType } from './OtpInput';

package/src/components/Page/Page.module.scss

@@ -0,0 +1,30 @@
+@use './Page.tokens';
+
+.root {
+  display: flex;
+  flex-direction: column;
+}
+
+.gapXs {
+  gap: var(--page-gap-xs);
+}
+
+.gapSm {
+  gap: var(--page-gap-sm);
+}
+
+.gapMd {
+  gap: var(--page-gap-md);
+}
+
+.gapLg {
+  gap: var(--page-gap-lg);
+}
+
+.gapXl {
+  gap: var(--page-gap-xl);
+}
+
+.gap2xl {
+  gap: var(--page-gap-2xl);
+}

package/src/components/Page/Page.tokens.scss

@@ -0,0 +1,11 @@
+// Page.tokens.scss — Component-scoped tokens for <Page>. Each token
+// defaults to the primitive the SCSS used before this migration.
+:root {
+  // Gap per size variant (vertical rhythm between page sections)
+  --page-gap-xs: var(--space-1);
+  --page-gap-sm: var(--space-2);
+  --page-gap-md: var(--space-3);
+  --page-gap-lg: var(--space-4);
+  --page-gap-xl: var(--space-6);
+  --page-gap-2xl: var(--space-8);
+}

package/src/components/Page/Page.tsx

@@ -0,0 +1,53 @@
+import { forwardRef, type HTMLAttributes, type ReactNode } from 'react';
+import clsx from 'clsx';
+import { type StackGap } from '../Stack';
+import styles from './Page.module.scss';
+
+/**
+ * Gap union for `<Page>`. Reuses `StackGap` so the scale stays
+ * synchronized across layout primitives — when Stack gains a size,
+ * Page gains it automatically.
+ */
+export type PageGap = StackGap;
+
+export interface PageProps extends HTMLAttributes<HTMLDivElement> {
+  /**
+   * Vertical rhythm between top-level page sections.
+   * - `xs` (4) / `sm` (8) / `md` (12) — tighter than canonical; rare.
+   * - `lg` (16, **default**) — the canonical CRM page rhythm; matches
+   *   every shipped mockup.
+   * - `xl` (24) / `2xl` (32) — looser; for spacious overview / hero pages.
+   */
+  gap?: PageGap;
+  children: ReactNode;
+}
+
+const gapClass: Record<PageGap, string> = {
+  xs: styles.gapXs,
+  sm: styles.gapSm,
+  md: styles.gapMd,
+  lg: styles.gapLg,
+  xl: styles.gapXl,
+  '2xl': styles.gap2xl,
+};
+
+/**
+ * Page-root layout primitive: a thin Stack with the canonical `gap="lg"` rhythm between top-level sections.
+ * @see docs/components/Page.md
+ */
+export const Page = forwardRef<HTMLDivElement, PageProps>(function Page(
+  { gap = 'lg', className, children, ...rest },
+  ref,
+) {
+  return (
+    <div
+      ref={ref}
+      className={clsx(styles.root, gapClass[gap], className)}
+      // {...rest} last so consumer overrides win (Pattern A — Page has no
+      // locked-in attributes; even data-* and aria-* can be overridden).
+      {...rest}
+    >
+      {children}
+    </div>
+  );
+});

package/src/components/Page/index.ts

@@ -0,0 +1,2 @@
+export { Page } from './Page';
+export type { PageProps, PageGap } from './Page';