@eocrm/design-system 0.0.0-stage → 0.6.18

package/src/components/Checkbox/Checkbox.tokens.scss

@@ -0,0 +1,44 @@
+// Checkbox.tokens.scss — component-scoped tokens for <Checkbox>. NOTE: --checkbox-color is a consumer-injection variable set by the React layer (palette `color` prop) — DO NOT shadow it here.
+:root {
+  // Box — shape + base surface
+  --checkbox-radius: var(--radius-sm);
+  --checkbox-bg: var(--color-bg);
+  --checkbox-fg: var(--color-accent-fg);
+  --checkbox-border-color: var(--color-border-strong);
+
+  // Default fill (used as fallback when --checkbox-color isn't set)
+  --checkbox-bg-checked: var(--color-accent);
+
+  // Hover preview (border-only, no fill)
+  --checkbox-border-color-hover: var(--color-accent);
+
+  // Focus ring
+  --checkbox-ring: var(--ring-accent);
+
+  // Disabled
+  --checkbox-bg-disabled: var(--color-bg-subtle);
+  --checkbox-border-color-disabled: var(--color-border);
+  --checkbox-fg-disabled: var(--color-fg-disabled);
+  --checkbox-bg-checked-disabled: var(--color-border);
+  --checkbox-border-color-checked-disabled: var(--color-border);
+
+  // Invalid
+  --checkbox-border-color-invalid: var(--color-danger);
+  --checkbox-bg-checked-invalid: var(--color-danger);
+  --checkbox-border-color-checked-invalid: var(--color-danger);
+  --checkbox-ring-invalid: var(--ring-danger);
+
+  // Size — box diameter per size
+  --checkbox-box-size-sm: var(--size-checkbox-sm);
+  --checkbox-box-size-md: var(--size-checkbox-md);
+  --checkbox-box-size-lg: var(--size-checkbox-lg);
+
+  // Size — label font-size per size
+  --checkbox-label-font-size-sm: var(--font-size-sm);
+  --checkbox-label-font-size-md: var(--font-size-md);
+  --checkbox-label-font-size-lg: var(--font-size-lg);
+
+  // Label
+  --checkbox-label-line-height: var(--line-height-normal);
+  --checkbox-gap: var(--space-2);
+}

package/src/components/Checkbox/Checkbox.tsx

@@ -0,0 +1,188 @@
+import {
+  forwardRef,
+  useEffect,
+  useRef,
+  useState,
+  type ChangeEvent,
+  type CSSProperties,
+  type InputHTMLAttributes,
+  type ReactNode,
+} from 'react';
+import clsx from 'clsx';
+import { Check, Minus } from 'lucide-react';
+import { mergeRefs } from '../_internal/refs';
+import { type PaletteColor } from '../../palette';
+import styles from './Checkbox.module.scss';
+
+/** Box diameter + label type scale. */
+export type CheckboxSize = 'sm' | 'md' | 'lg';
+
+export interface CheckboxProps extends Omit<
+  InputHTMLAttributes<HTMLInputElement>,
+  'size' | 'type' | 'checked' | 'defaultChecked' | 'onChange'
+> {
+  /**
+   * Box diameter + label type scale. Defaults to `'md'`.
+   * - `'sm'` — 14px box, font-size-sm label. Dense tables, inline filters.
+   * - `'md'` — 16px box, font-size-md label. Default.
+   * - `'lg'` — 20px box, font-size-lg label. Hero forms, mobile-friendly.
+   *
+   * Note: shadows the native HTML `<input size>` attribute (which on
+   * checkboxes is meaningless anyway).
+   */
+  size?: CheckboxSize;
+
+  /**
+   * Controlled checked state. Pair with `onChange`. Omit (with optional
+   * `defaultChecked`) for uncontrolled use.
+   */
+  checked?: boolean;
+
+  /** Initial checked state for uncontrolled use. Defaults to `false`. */
+  defaultChecked?: boolean;
+
+  /**
+   * Indeterminate (mixed) visual + a11y state. Independent of `checked` —
+   * the box paints with a dash icon and `input.indeterminate = true` so AT
+   * announces "mixed". Consumer drives this based on partial selection
+   * (e.g., a "select all" header where some-but-not-all rows are selected).
+   *
+   * When the user clicks an indeterminate checkbox, the native change event
+   * fires with the next `checked` value (`true` if it was `false`). The
+   * consumer typically responds by clearing `indeterminate`.
+   */
+  indeterminate?: boolean;
+
+  /**
+   * Optional label rendered next to the box. The whole `<label>` is the
+   * click target. Omit for icon-only checkboxes (e.g., a DataTable row
+   * selector) — pass `aria-label` instead.
+   */
+  label?: ReactNode;
+
+  /** Toggles the error visual + sets `aria-invalid="true"`. Pair with a visible error message and `aria-describedby`. */
+  invalid?: boolean;
+
+  /**
+   * Optional palette color for the checked / indeterminate fill. When
+   * set, the filled state uses the palette color's fg token instead
+   * of `--color-accent`. Use to color-tag checkbox groups (per-team,
+   * per-status, per-category). Default unchanged (accent blue).
+   *
+   * The focus ring, hover border, and unchecked state remain
+   * accent-colored regardless of `color` — only the checked /
+   * indeterminate fill is affected.
+   */
+  color?: PaletteColor;
+
+  /**
+   * Fires on every change. Receives the next checked state AND the native
+   * event so consumers can do `event.preventDefault()`, read modifier keys,
+   * etc.
+   */
+  onChange?: (checked: boolean, event: ChangeEvent<HTMLInputElement>) => void;
+}
+
+const iconSize: Record<CheckboxSize, number> = {
+  sm: 10,
+  md: 12,
+  lg: 14,
+};
+
+/**
+ * Checkbox: a visually hidden native input plus a custom-painted box.
+ * @see docs/components/Checkbox.md
+ */
+export const Checkbox = forwardRef<HTMLInputElement, CheckboxProps>(function Checkbox(
+  {
+    size = 'md',
+    checked,
+    defaultChecked,
+    indeterminate,
+    label,
+    invalid,
+    onChange,
+    className,
+    disabled,
+    color,
+    ...props
+  },
+  ref,
+) {
+  const isControlled = checked !== undefined;
+  const [internalChecked, setInternalChecked] = useState(defaultChecked ?? false);
+  const currentChecked = isControlled ? checked : internalChecked;
+
+  // Native `indeterminate` is a DOM property, not an attribute. React doesn't
+  // surface it as a prop, so we set it via ref in an effect that fires after
+  // each render — covers both initial mount and prop changes.
+  const inputRef = useRef<HTMLInputElement>(null);
+  const mergedRef = mergeRefs(ref, inputRef);
+
+  useEffect(() => {
+    if (inputRef.current) {
+      inputRef.current.indeterminate = indeterminate ?? false;
+    }
+  }, [indeterminate]);
+
+  // `aria-disabled="true"` (#724): looks and behaves disabled but keeps focus,
+  // for a busy state where real `disabled` would drop it. The input is always
+  // React-controlled (`checked={currentChecked}`), so skipping the state update
+  // and onChange is enough: React puts the DOM back after a click or Space.
+  const ariaDisabled = props['aria-disabled'] === true || props['aria-disabled'] === 'true';
+
+  const handleChange = (event: ChangeEvent<HTMLInputElement>) => {
+    if (ariaDisabled) {
+      // The click already cleared the native `indeterminate`, and React's
+      // controlled restore only puts `checked` back: re-assert the dash.
+      event.target.indeterminate = indeterminate ?? false;
+      return;
+    }
+    const next = event.target.checked;
+    if (!isControlled) setInternalChecked(next);
+    onChange?.(next, event);
+  };
+
+  // When a palette color is set, expose it as a CSS variable scoped to
+  // this checkbox. The SCSS reads `var(--checkbox-color, var(--color-accent))`
+  // so undef = default accent.
+  const colorStyle = color
+    ? ({ '--checkbox-color': `var(--color-palette-${color}-fg)` } as CSSProperties)
+    : undefined;
+
+  return (
+    <label
+      className={clsx(
+        styles.checkbox,
+        styles[`size-${size}`],
+        (disabled || ariaDisabled) && styles.disabled,
+        invalid && styles.invalid,
+        className,
+      )}
+      style={colorStyle}
+    >
+      {/* Pattern B — props first so the component-owned attrs below
+          (type, checked, disabled, aria-invalid, onChange, className) win.
+          The semantic contract is that a Checkbox is always type=checkbox,
+          uses our checked/onChange machinery, and styles via styles.input. */}
+      <input
+        {...props}
+        ref={mergedRef}
+        type="checkbox"
+        checked={currentChecked}
+        disabled={disabled}
+        aria-invalid={invalid || undefined}
+        onChange={handleChange}
+        className={styles.input}
+      />
+      <span aria-hidden="true" className={styles.box}>
+        {indeterminate ? (
+          <Minus size={iconSize[size]} strokeWidth={3} />
+        ) : currentChecked ? (
+          <Check size={iconSize[size]} strokeWidth={3} />
+        ) : null}
+      </span>
+      {label != null && <span className={styles.labelText}>{label}</span>}
+    </label>
+  );
+});

package/src/components/Checkbox/index.ts

@@ -0,0 +1,2 @@
+export { Checkbox } from './Checkbox';
+export type { CheckboxProps, CheckboxSize } from './Checkbox';

package/src/components/CircularProgress/CircularProgress.module.scss

@@ -0,0 +1,133 @@
+@use './CircularProgress.tokens';
+
+.circular {
+  // position: relative anchors the absolutely-positioned .label below.
+  // This is internal-child layout (centered text inside a donut), NOT layout
+  // at the component boundary. Same precedent as Avatar's .presence dot.
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.svg {
+  // Rotate -90deg so the 0% mark sits at 12 o'clock instead of 3 o'clock.
+  transform: rotate(-90deg);
+  overflow: visible;
+}
+
+.sizeSm {
+  width: 16px;
+  height: 16px;
+}
+
+.sizeMd {
+  width: 32px;
+  height: 32px;
+}
+
+.sizeLg {
+  width: 56px;
+  height: 56px;
+}
+
+.sizeSm .track,
+.sizeSm .fill {
+  stroke-width: 2;
+}
+
+.sizeMd .track,
+.sizeMd .fill {
+  stroke-width: 3;
+}
+
+.sizeLg .track,
+.sizeLg .fill {
+  stroke-width: 4;
+}
+
+.track {
+  // stylelint-disable-next-line scale-unlimited/declaration-strict-value -- SVG attribute, not a tokenizable design value
+  fill: none;
+  stroke: var(--circular-progress-track-color);
+}
+
+.fill {
+  // stylelint-disable-next-line scale-unlimited/declaration-strict-value -- SVG attribute, not a tokenizable design value
+  fill: none;
+  stroke: var(--circular-progress-fill-color);
+  // stylelint-disable-next-line scale-unlimited/declaration-strict-value -- SVG attribute, not a tokenizable design value
+  stroke-linecap: round;
+  transition: stroke-dashoffset var(--circular-progress-fill-transition);
+}
+
+.toneDefault .fill {
+  stroke: var(--circular-progress-fill-color-default);
+}
+
+.toneSuccess .fill {
+  stroke: var(--circular-progress-fill-color-success);
+}
+
+.toneWarning .fill {
+  stroke: var(--circular-progress-fill-color-warning);
+}
+
+.toneDanger .fill {
+  stroke: var(--circular-progress-fill-color-danger);
+}
+
+.indeterminate {
+  // Partial arc (~30% of circumference) that spins continuously — the
+  // canonical loading-spinner shape. (Exact: 30/100.53 ≈ 29.84%; the visual
+  // difference at any rendered diameter is imperceptible.)
+  // stylelint-disable-next-line scale-unlimited/declaration-strict-value -- SVG attribute, not a tokenizable design value
+  stroke-dasharray: 30 100 !important;
+  animation: circular-spin 1.2s linear infinite;
+
+  // Anchor the spin to the SVG center.
+  transform-origin: center;
+
+  // Indeterminate always uses the accent color — tone semantics don't apply
+  // to an unknown total. Override any .tone-* rule that would otherwise
+  // win via specificity.
+  stroke: var(--circular-progress-indeterminate-color) !important;
+
+  // Disable the stroke-dashoffset transition so determinate→indeterminate
+  // switches don't animate the arc before the spin fires.
+  transition: none;
+}
+
+@keyframes circular-spin {
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+.label {
+  // Centered text inside the donut. position: absolute is internal-child
+  // layout for the centered-text-in-circle pattern (Avatar's .presence dot
+  // uses the same exception).
+  position: absolute;
+  font-size: var(--circular-progress-label-font-size);
+  font-weight: var(--circular-progress-label-font-weight);
+  color: var(--circular-progress-label-fg);
+  font-variant-numeric: tabular-nums;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .indeterminate {
+    animation: none;
+
+    // Replace the spinning arc with a full static circle so the user still
+    // sees an "in progress" cue without motion.
+    // stylelint-disable-next-line scale-unlimited/declaration-strict-value -- SVG attribute, not a tokenizable design value
+    stroke-dasharray: none !important;
+    // stylelint-disable-next-line scale-unlimited/declaration-strict-value -- SVG attribute, not a tokenizable design value
+    stroke-dashoffset: 0 !important;
+  }
+
+  .fill {
+    transition: none;
+  }
+}

package/src/components/CircularProgress/CircularProgress.tokens.scss

@@ -0,0 +1,40 @@
+// CircularProgress.tokens.scss — Component-scoped tokens for <CircularProgress>. Covers the donut track + per-tone fill stroke, the centered label, and the determinate-fill transition. SVG attribute literals (fill: none, stroke-linecap, exact size pixels per size variant) stay as-is.
+:root {
+  // Track + base fill stroke
+  --circular-progress-track-color: var(--color-border);
+  --circular-progress-fill-color: var(--color-accent);
+
+  // Per-tone fill stroke
+  --circular-progress-fill-color-default: var(--color-accent);
+  --circular-progress-fill-color-success: var(--color-success);
+
+  // @contrast --color-warning on --color-border = 1.63:1 light
+  // @contrast --color-warning-strong on --color-border = 4.55:1 light
+  // @contrast --color-success on --color-border = 3.90:1 light
+  // @contrast --color-danger on --color-border = 4.13:1 light
+  // @contrast --color-accent on --color-border = 5.21:1 light
+  // @contrast --color-warning on --color-border = 6.77:1 dark
+  // @contrast --color-success on --color-border = 5.23:1 dark
+  // @contrast --color-danger on --color-border = 3.73:1 dark
+  // @contrast --color-accent on --color-border = 4.23:1 dark
+  // The track is --color-border, not --color-bg-muted (#647): a bg-muted track
+  // vanished on every bg-muted surface (StatTile, table headers, muted panels).
+  // warning uses --color-warning-strong: the bare amber measures 1.63:1 against
+  // the track, below 1.4.11's 3:1 — the ONLY tone that fails there (light success
+  // 3.90:1, danger 4.13:1, accent 5.21:1), so the fill is wrong, not the track.
+  // In dark nothing fails (amber 6.77:1, success 5.23:1, danger 3.73:1, accent
+  // 4.23:1). See #481.
+  --circular-progress-fill-color-warning: var(--color-warning-strong);
+  --circular-progress-fill-color-danger: var(--color-danger);
+
+  // Indeterminate spinner — always accent (matches existing override)
+  --circular-progress-indeterminate-color: var(--color-accent);
+
+  // Determinate sweep transition
+  --circular-progress-fill-transition: var(--transition-base);
+
+  // Centered label
+  --circular-progress-label-font-size: var(--font-size-sm);
+  --circular-progress-label-font-weight: var(--font-weight-medium);
+  --circular-progress-label-fg: var(--color-fg);
+}

package/src/components/CircularProgress/CircularProgress.tsx

@@ -0,0 +1,139 @@
+import { forwardRef, type HTMLAttributes, type ReactNode } from 'react';
+import clsx from 'clsx';
+import { useTranslation } from '../../i18n/useTranslation';
+import styles from './CircularProgress.module.scss';
+
+/** Diameter + stroke pairing. */
+export type CircularProgressSize = 'sm' | 'md' | 'lg';
+
+/** Color tone for the fill stroke. Default `'default'` uses the accent color. */
+export type CircularProgressTone = 'default' | 'success' | 'warning' | 'danger';
+
+/** Label render mode. */
+export type CircularProgressLabel = boolean | ReactNode;
+
+export interface CircularProgressProps extends Omit<HTMLAttributes<HTMLDivElement>, 'role'> {
+  /**
+   * Current progress value. Omit (or pass `undefined`) to render the
+   * indeterminate spinning animation.
+   *
+   * Two-channel behavior for out-of-range and degenerate values:
+   * - **Visual arc** is clamped to [0%, 100%]. Values outside [0, max]
+   *   render at the nearest valid bound.
+   * - **ARIA `aria-valuenow`** reports the raw number so consumer bugs
+   *   (a value drifting past max) surface in audits and SR announcements.
+   *
+   * Degenerate inputs fall back to the indeterminate spinner: `NaN`,
+   * `Infinity`, `-Infinity`, and the case where `max <= 0`. This is the
+   * common file-upload race condition (`bytes_uploaded / total_bytes`
+   * before `total_bytes` is known produces NaN).
+   */
+  value?: number;
+  /**
+   * Upper bound. Defaults to `100`. Consumers using fraction values
+   * (0.0–1.0) pass `max={1}`. Consumers tracking a count ("3 of 10")
+   * pass `max={10}`.
+   */
+  max?: number;
+  /**
+   * Diameter + stroke pairing.
+   * - `sm` — 16px diameter, 2px stroke (inline next to a button — also the
+   *   shape to use for "Saving…" loading affordances; pass no `value` for
+   *   the indeterminate spinner.)
+   * - `md` — 32px diameter, 3px stroke (default — near a heading)
+   * - `lg` — 56px diameter, 4px stroke (page-level loader)
+   */
+  size?: CircularProgressSize;
+  /**
+   * Stroke color tone. Defaults to `'default'` (accent blue). Same vocab
+   * as `<Progress>`. Indeterminate ignores tone — always accent.
+   */
+  tone?: CircularProgressTone;
+  /**
+   * Optional centered label.
+   * - `false` (default) — no label
+   * - `true` — render `{Math.round(percent)}%` centered. Auto-suppressed
+   *   at `size='sm'` (16px circle has no room for text) AND when
+   *   indeterminate.
+   * - `ReactNode` — render the node centered in BOTH modes. Still
+   *   auto-suppressed at `size='sm'` regardless — the geometry doesn't
+   *   change.
+   */
+  label?: CircularProgressLabel;
+}
+
+const SIZE_CLASS: Record<CircularProgressSize, string> = {
+  sm: styles.sizeSm,
+  md: styles.sizeMd,
+  lg: styles.sizeLg,
+};
+
+const TONE_CLASS: Record<CircularProgressTone, string> = {
+  default: styles.toneDefault,
+  success: styles.toneSuccess,
+  warning: styles.toneWarning,
+  danger: styles.toneDanger,
+};
+
+// SVG geometry constants:
+// - viewBox is 36x36, the circle is centered at (18, 18) with radius 16.
+// - circumference = 2 * π * 16 ≈ 100.531. The SVG fits the conventional
+//   "use 100 as the magic circumference" pattern that makes percentages
+//   trivial: strokeDashoffset = (1 - value/max) * circumference.
+// - The outer SVG carries `transform: rotate(-90deg)` (in SCSS) so the
+//   0% mark sits at 12 o'clock instead of 3 o'clock.
+const RADIUS = 16;
+const CIRCUMFERENCE = 2 * Math.PI * RADIUS;
+
+/**
+ * Circular progress primitive (donut shape); indeterminate mode is a spinner.
+ * @see docs/components/CircularProgress.md
+ */
+export const CircularProgress = forwardRef<HTMLDivElement, CircularProgressProps>(
+  function CircularProgress(
+    { value, max = 100, size = 'md', tone = 'default', label = false, className, ...rest },
+    ref,
+  ) {
+    // Determinate requires a finite numeric value AND a positive max — same
+    // defensive guard as <Progress>. NaN / Infinity / max<=0 fall back to the
+    // indeterminate spinner (file-upload race: bytes_uploaded / total_bytes
+    // before total_bytes is known → NaN).
+    const determinate = typeof value === 'number' && Number.isFinite(value) && max > 0;
+    const indeterminate = !determinate;
+    // VISUAL clamp only — ARIA reports the raw `value`.
+    const percent = determinate ? Math.max(0, Math.min(100, (value / max) * 100)) : 0;
+    const strokeDashoffset = determinate ? CIRCUMFERENCE * (1 - percent / 100) : undefined;
+    const t = useTranslation();
+    const ariaLabel = rest['aria-label'];
+    const valuetext = indeterminate ? ariaLabel || t('progress.indeterminate') : undefined;
+
+    // {...rest} last so consumer overrides win (Pattern A).
+    return (
+      <div
+        ref={ref}
+        role="progressbar"
+        className={clsx(styles.circular, SIZE_CLASS[size], TONE_CLASS[tone], className)}
+        aria-valuemin={0}
+        aria-valuemax={max}
+        aria-valuenow={determinate ? value : undefined}
+        aria-valuetext={valuetext}
+        {...rest}
+      >
+        <svg viewBox="0 0 36 36" className={styles.svg}>
+          <circle className={styles.track} cx="18" cy="18" r={RADIUS} />
+          <circle
+            className={clsx(styles.fill, indeterminate && styles.indeterminate)}
+            cx="18"
+            cy="18"
+            r={RADIUS}
+            strokeDasharray={CIRCUMFERENCE}
+            strokeDashoffset={strokeDashoffset}
+          />
+        </svg>
+        {label !== false && size !== 'sm' && !(label === true && indeterminate) && (
+          <span className={styles.label}>{label === true ? `${Math.round(percent)}%` : label}</span>
+        )}
+      </div>
+    );
+  },
+);

package/src/components/CircularProgress/index.ts

@@ -0,0 +1,7 @@
+export { CircularProgress } from './CircularProgress';
+export type {
+  CircularProgressProps,
+  CircularProgressSize,
+  CircularProgressTone,
+  CircularProgressLabel,
+} from './CircularProgress';