@eocrm/design-system 0.0.0-stage → 0.6.17

package/src/components/Switch/Switch.tsx

@@ -0,0 +1,214 @@
+import {
+  useEffect,
+  forwardRef,
+  useState,
+  type ChangeEvent,
+  type InputHTMLAttributes,
+  type ReactNode,
+} from 'react';
+import { Loader2 } from 'lucide-react';
+import clsx from 'clsx';
+import { useTranslation } from '../../i18n/useTranslation';
+import styles from './Switch.module.scss';
+
+/**
+ * Track + thumb scale + label font. Pairs with Checkbox/Radio sizes.
+ */
+export type SwitchSize = 'sm' | 'md' | 'lg';
+
+/**
+ * Color of the track when checked. Unchecked track is always
+ * `--color-bg-muted` regardless of tone.
+ */
+export type SwitchTone = 'accent' | 'success' | 'danger';
+
+export interface SwitchProps extends Omit<
+  InputHTMLAttributes<HTMLInputElement>,
+  'size' | 'type' | 'checked' | 'defaultChecked' | 'onChange'
+> {
+  /**
+   * Visual scale. Defaults to `'md'`.
+   * - `'sm'` — 28×16 track, 12px thumb, `--font-size-sm` label.
+   * - `'md'` — 36×20 track, 16px thumb, `--font-size-md` label (default).
+   * - `'lg'` — 44×24 track, 20px thumb, `--font-size-lg` label.
+   *
+   * Note: shadows the native HTML `<input size>` attribute (meaningless on checkboxes).
+   */
+  size?: SwitchSize;
+
+  /**
+   * Track color when checked (the unchecked track is always neutral muted). Defaults to `'accent'`.
+   * - `'accent'` — blue (default).
+   * - `'success'` — green. Use for affirmative toggles ("Enable notifications").
+   * - `'danger'` — red. Use for destructive toggles ("Allow root access").
+   */
+  tone?: SwitchTone;
+
+  /**
+   * 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;
+
+  /**
+   * Fires when the user toggles the switch. The first arg is the next
+   * boolean (convenience); the original change event is the second arg.
+   * Matches `<Checkbox>`'s signature.
+   */
+  onChange?: (checked: boolean, e: ChangeEvent<HTMLInputElement>) => void;
+
+  /**
+   * Toggles `aria-invalid="true"` and adds a danger-tone border to the
+   * track. Use when the switch's state has caused a validation error.
+   */
+  invalid?: boolean;
+
+  /**
+   * Shows a spinner inside the thumb and suppresses changes while a toggle
+   * persists to a server, keeping the native input focusable so keyboard users
+   * retain their place in the form.
+   *
+   * Announced from a polite live region the Switch owns. `aria-busy` is set
+   * too, but nothing reads it — no mainstream screen reader conveys `busy` on
+   * a non-live element. The region sits OUTSIDE the `<label>` so it does not
+   * join the input's accessible name: the name stays stable while loading, and
+   * `getByRole('switch', { name })` keeps matching.
+   *
+   * The consumer is responsible for managing the optimistic-update flow:
+   *
+   * ```tsx
+   * const [enabled, setEnabled] = useState(initial);
+   * const [saving, setSaving] = useState(false);
+   *
+   * const handleToggle = async (next: boolean) => {
+   *   setSaving(true);
+   *   setEnabled(next);            // optimistic
+   *   try { await api.save(next); }
+   *   catch { setEnabled(!next); } // rollback
+   *   finally { setSaving(false); }
+   * };
+   *
+   * <Switch checked={enabled} loading={saving} onChange={handleToggle} />
+   * ```
+   */
+  loading?: boolean;
+
+  /**
+   * Label rendered next to the track. The whole `<label>` is the click
+   * target — clicking anywhere toggles. Omit for icon-only switches +
+   * pair with `aria-label`.
+   */
+  children?: ReactNode;
+}
+
+const SIZE_CLASS: Record<SwitchSize, string> = {
+  sm: styles.sizeSm,
+  md: styles.sizeMd,
+  lg: styles.sizeLg,
+};
+
+const LABEL_CLASS: Record<SwitchSize, string> = {
+  sm: styles.labelSm,
+  md: styles.labelMd,
+  lg: styles.labelLg,
+};
+
+const SPIN_SIZE: Record<SwitchSize, number> = {
+  sm: 8,
+  md: 10,
+  lg: 12,
+};
+
+/**
+ * Binary on/off toggle on a native `<input type="checkbox" role="switch">`.
+ * @see docs/components/Switch.md
+ */
+export const Switch = forwardRef<HTMLInputElement, SwitchProps>(function Switch(
+  {
+    size = 'md',
+    tone = 'accent',
+    checked,
+    defaultChecked,
+    onChange,
+    invalid,
+    loading,
+    disabled,
+    children,
+    className,
+    ...props
+  },
+  ref,
+) {
+  const t = useTranslation();
+  // One tick behind on purpose. Computing the text during render means a
+  // component that MOUNTS already-loading mounts region and text together —
+  // the case Hard rule 10 forbids, because most screen readers do not announce
+  // content that was already there. Deferring to an effect makes the first
+  // paint empty, so the word always arrives as a change. DataTable does the
+  // same via its loadPhase effect; these two shipped without it.
+  const [busyText, setBusyText] = useState('');
+  useEffect(() => {
+    setBusyText(loading ? t('switch.busy') : '');
+  }, [loading, t]);
+  const [internalChecked, setInternalChecked] = useState<boolean>(defaultChecked ?? false);
+  const isControlled = checked !== undefined;
+  const currentChecked = isControlled ? checked : internalChecked;
+
+  const isVisuallyUnavailable = disabled || loading;
+
+  const handleChange = (e: ChangeEvent<HTMLInputElement>) => {
+    if (loading) return;
+    if (!isControlled) setInternalChecked(e.target.checked);
+    onChange?.(e.target.checked, e);
+  };
+
+  return (
+    <>
+      <label
+        className={clsx(styles.wrapper, className)}
+        data-disabled={isVisuallyUnavailable || undefined}
+      >
+        {/* Pattern B — {...props} first so component-owned attrs (type, role, checked, disabled, aria-*, onChange, className) win. */}
+        <input
+          {...props}
+          ref={ref}
+          type="checkbox"
+          role="switch"
+          checked={currentChecked}
+          disabled={disabled}
+          aria-invalid={invalid || undefined}
+          aria-busy={loading || undefined}
+          onChange={handleChange}
+          className={styles.input}
+        />
+        <span
+          className={clsx(styles.track, SIZE_CLASS[size])}
+          data-checked={currentChecked ? 'true' : 'false'}
+          data-tone={tone}
+          data-invalid={invalid ? 'true' : undefined}
+          aria-hidden="true"
+        >
+          <span className={styles.thumb}>
+            {loading && (
+              <Loader2 size={SPIN_SIZE[size]} className={styles.spin} aria-hidden="true" />
+            )}
+          </span>
+        </span>
+        {children && <span className={clsx(styles.label, LABEL_CLASS[size])}>{children}</span>}
+      </label>
+      {/* OUTSIDE the <label> on purpose. Inside it, this span joined the
+          input's accessible name via name-from-content — `Mute` became
+          `MuteSaving…` in dom-accessibility-api and Playwright, so
+          `getByRole('switch', { name: 'Mute' })` stopped matching mid-flight.
+          Chrome's own AX tree excluded it, but consumer tests do not run in
+          Chrome's AX tree. Renaming a focused control is what Hard rule 10
+          tells everyone else not to do. */}
+      <span role="status" aria-live="polite" className={styles.srOnly}>
+        {busyText}
+      </span>
+    </>
+  );
+});

package/src/components/Switch/index.ts

@@ -0,0 +1,2 @@
+export { Switch } from './Switch';
+export type { SwitchProps, SwitchSize, SwitchTone } from './Switch';

package/src/components/Table/Table.module.scss

@@ -0,0 +1,308 @@
+@use '../../styles/mixins' as *;
+@use './Table.tokens';
+
+// Scroll wrapper — horizontal overflow context for wide tables AND the
+// scroll container for sticky headers.
+.scrollWrap {
+  width: 100%;
+  overflow-x: auto;
+}
+
+.table {
+  // min-width instead of width: 100% so the table is at least the parent's
+  // width for narrow content (looks identical to width:100% in that case) but
+  // is free to grow to its intrinsic column-sum width when wider. Combined
+  // with .scrollWrap's overflow-x:auto, a wide table scrolls internally and
+  // each column's declared <col> width is honored — important for sticky
+  // pinning math (DataTable's pin offsets assume widths aren't squeezed).
+  min-width: 100%;
+  border-collapse: collapse;
+  font-family: inherit;
+  color: var(--table-fg);
+  background: var(--table-bg);
+}
+
+// Fixed layout only engages with a definite width; 100% is Rule 4's allowed value.
+.layoutFixed {
+  table-layout: fixed;
+  width: 100%;
+}
+
+// ─── Density ───────────────────────────────────────────────────────────────
+
+.density-comfortable .td,
+.density-comfortable .th {
+  padding: var(--table-density-comfortable-padding-y) var(--table-density-comfortable-padding-x);
+  font-size: var(--table-density-comfortable-font-size);
+}
+
+.density-dense .td,
+.density-dense .th {
+  padding: var(--table-density-dense-padding-y) var(--table-density-dense-padding-x);
+  font-size: var(--table-density-dense-font-size);
+}
+
+// Table.CellLink takes over its cell's padding so the whole cell is the hit
+// area — the cell drops its own via :has(), no negative margins. Declared
+// after the density rules so it wins on equal specificity.
+.td:has(> .cellLink) {
+  padding: 0;
+}
+
+.density-comfortable .cellLink {
+  padding: var(--table-density-comfortable-padding-y) var(--table-density-comfortable-padding-x);
+}
+
+.density-dense .cellLink {
+  padding: var(--table-density-dense-padding-y) var(--table-density-dense-padding-x);
+}
+
+// ─── Sections ──────────────────────────────────────────────────────────────
+
+.caption {
+  padding: var(--table-caption-padding-y) var(--table-caption-padding-x);
+  color: var(--table-caption-fg);
+  font-size: var(--table-caption-font-size);
+  text-align: start;
+}
+
+// Four distinct row background tones, in increasing visual weight:
+//   body row      → --table-bg                  (white)
+//   striped even  → --table-row-bg-striped      (faintest gray)
+//   header/footer → --table-header-bg           (muted gray, chrome)
+//   hover         → --table-row-bg-hover        (light info blue)
+//   selected      → --table-row-bg-selected     (stronger info blue)
+.thead .tr {
+  background: var(--table-header-bg);
+}
+
+.tbody .tr {
+  // Body row bg + bottom-border divider. The last body row's bottom
+  // border also serves as the divider between body and footer via
+  // `border-collapse: collapse`.
+  background: var(--table-bg);
+  border-bottom: var(--border-width) solid var(--table-border-color);
+}
+
+.tfoot .tr {
+  background: var(--table-footer-bg);
+}
+
+// ─── Rows ──────────────────────────────────────────────────────────────────
+
+// The header's bottom border lives on the .th itself (NOT on a generic
+// `.tr { border-bottom }`) so it stays pinned with sticky headers — a
+// border on `<tr>` scrolls away because only the inner `<th>`s are sticky.
+.thead .th {
+  border-bottom: var(--border-width) solid var(--table-border-color);
+}
+
+// Background cascade (all four rules same-ish specificity — source order
+// resolves ties):
+//   .striped .tbody .tr:nth-of-type(even)  (0,4,0)
+//   .hover   .tbody .tr:hover              (0,4,0)  — must be declared AFTER
+//                                                    striped so hover wins on
+//                                                    striped+even rows
+//   Selected variants below — declared even later AND higher specificity.
+.striped .tbody .tr:nth-of-type(even) {
+  background: var(--table-row-bg-striped);
+}
+
+.hover .tbody .tr:hover {
+  background: var(--table-row-bg-hover);
+}
+
+// Bordered — full grid. With `border-collapse: collapse` already on the
+// .table, putting a 1px border on every cell collapses adjacent cell
+// borders into a single line AND produces the outer table border
+// automatically. The existing row-divider `tr { border-bottom }` stays
+// fine — it collapses against the cell borders without doubling.
+.bordered .th,
+.bordered .td {
+  border: var(--border-width) solid var(--table-border-color);
+}
+
+// Selected wins over striped + hover.
+//   .tbody .tr.selected               (0,3,0) — base, beats .tbody .tr (0,2,1)
+//   .striped .tbody .tr.selected      (0,4,0) — beats .striped+nth-of-type
+//                                                via source order
+//   .hover .tbody .tr.selected:hover  (0,5,0) — beats .hover .tr:hover (0,4,0)
+//                                                via specificity, covers both
+//                                                striped and non-striped tables
+.tbody .tr.selected,
+.striped .tbody .tr.selected,
+.hover .tbody .tr.selected:hover {
+  background: var(--table-row-bg-selected);
+  color: var(--table-row-fg-selected);
+}
+
+// ─── Cells ─────────────────────────────────────────────────────────────────
+
+.th {
+  color: var(--table-header-fg);
+  font-weight: var(--table-header-font-weight);
+  text-transform: none;
+  vertical-align: middle;
+}
+
+.td {
+  vertical-align: middle;
+}
+
+// Inner flex container for header cells so sort chevron sits beside text.
+.thInner {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--table-th-inner-gap);
+}
+
+// Alignment — applied via CSS logical properties (RTL-friendly).
+.align-start {
+  text-align: start;
+}
+
+.align-center {
+  text-align: center;
+}
+
+.align-end {
+  text-align: end;
+}
+
+// Right-aligned headers need the chevron on the start side of the label,
+// not the end — flip the inner flex direction.
+.align-end .thInner {
+  flex-direction: row-reverse;
+}
+
+// ─── Sortable header ───────────────────────────────────────────────────────
+
+.sortable {
+  cursor: pointer;
+  user-select: none;
+
+  &:hover {
+    background: var(--table-header-bg-hover);
+    color: var(--table-header-fg-hover);
+  }
+
+  // Inset: the ring sits inside the cell box rather than overlapping its
+  // neighbour.
+  &:focus-visible {
+    @include focus-ring(var(--table-sortable-ring), $offset: calc(-1 * var(--ring-offset)));
+  }
+}
+
+.sortIcon {
+  flex-shrink: 0;
+  color: var(--table-sort-icon-fg);
+}
+
+.sortable:not(.sortableInactive) .sortIcon {
+  color: var(--table-sort-icon-fg-active);
+}
+
+// ─── Cell tone ─────────────────────────────────────────────────────────────
+
+// Declared after .sortable so the tint survives a sortable header's hover, and
+// at (0,2,0) so it beats the sticky header's (0,1,0) background repeat.
+.td[data-tone='danger'],
+.th[data-tone='danger'] {
+  background: var(--table-cell-bg-danger);
+  color: var(--table-cell-fg-danger);
+}
+
+.td[data-tone='accent'],
+.th[data-tone='accent'] {
+  background: var(--table-cell-bg-accent);
+  color: var(--table-cell-fg-accent);
+}
+
+// Rounded top corners so the header and its toned body cells read as one band.
+.th[data-tone] {
+  border-start-start-radius: var(--table-cell-tone-header-radius);
+  border-start-end-radius: var(--table-cell-tone-header-radius);
+}
+
+// Full-grid borders meet square at every corner; a rounded toned header would
+// break the grid lines (#664).
+.bordered .th[data-tone] {
+  border-radius: 0;
+}
+
+// ─── Cell link ─────────────────────────────────────────────────────────────
+
+// Inherits the cell's text-align (block) and colour (tone). Padding comes from
+// the density rules above.
+.cellLink {
+  display: block;
+  color: inherit;
+  font-weight: var(--table-cell-link-font-weight);
+  text-decoration: none;
+
+  // Muted (and deprecated subtle) Text inside — e.g. a zero dash — takes the
+  // link's own colour: muted on the overlay falls under AA in light, even on
+  // an untoned hovered or striped row. currentColor in a custom property
+  // resolves where it is used, so Text's `color:` inherits the link colour
+  // (the cell fg, or the tone -hover colour below). Subtle is set too: it
+  // aliases muted at :root, so overriding muted alone would not reach it.
+  &:hover {
+    --text-fg-muted: currentColor;
+    --text-fg-subtle: currentColor;
+
+    background: var(--table-cell-link-bg-hover);
+  }
+
+  // Inset ring so neighbouring cells don't paint over it.
+  &:focus-visible {
+    @include focus-ring(var(--table-cell-link-ring), $offset: calc(-1 * var(--ring-offset)));
+  }
+}
+
+// The overlay pulls the base tone under AA in light, so hovered toned text
+// steps to the tone's -hover colour.
+[data-tone='danger'] > .cellLink:hover {
+  color: var(--table-cell-fg-danger-hover);
+}
+
+[data-tone='accent'] > .cellLink:hover {
+  color: var(--table-cell-fg-accent-hover);
+}
+
+// ─── Sticky header ─────────────────────────────────────────────────────────
+
+// stylelint-disable property-disallowed-list -- Rule 4 escape hatch: position:sticky here is internal layout (anchors the header to the .scrollWrap scroll context), not a public-component layout property. Same precedent as AvatarGroup .item z-index.
+// :where() on the ancestor chain drops specificity to 0,1,0 (only .th contributes).
+// This allows DataTable's pinning rules (.pinnedLeft/.pinnedRight, z-index:3) to
+// override this z-index:1 via cascade order — DataTable's CSS module is imported
+// later and wins on equal specificity. Without :where() this selector is 0,3,0 and
+// would beat DataTable's 0,1,0 pinning rules regardless of import order.
+:where(.stickyHeader .thead) .th {
+  position: sticky;
+  top: 0;
+  z-index: 1;
+
+  // Repeat the header bg here — `tr` bg paints below the th's sticky
+  // layer in some browsers, leaving body rows visible through it. Must
+  // match the .thead .tr background above.
+  background: var(--table-header-bg);
+}
+// stylelint-enable property-disallowed-list
+
+// ─── Cell modifiers ────────────────────────────────────────────────────────
+
+// stylelint-disable property-disallowed-list -- max-width: 0 is the standard flex/table-cell ellipsis trick (forces the cell to honour text-overflow). This is an internal-child modifier, not a public layout constraint on the component boundary.
+.truncate {
+  max-width: 0;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+// The link is the block that holds the text, so it needs its own ellipsis.
+.truncate > .cellLink {
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+// stylelint-enable property-disallowed-list

package/src/components/Table/Table.tokens.scss

@@ -0,0 +1,79 @@
+// Table.tokens.scss — Component-scoped tokens for <Table>. Surface
+// backgrounds per row state (body / header / footer / striped / hover /
+// selected), the cell border, the header text + sort icon, density padding
+// per mode, caption typography, and the sticky-header focus ring. DataTable
+// sits on top of this primitive and overrides --color-table-* via its own
+// surface tokens — keeping Table's tokens semantic ensures a Table theme
+// override propagates to DataTable.
+:root {
+  // Table surface
+  --table-fg: var(--color-table-fg);
+  --table-bg: var(--color-table-bg);
+  --table-border-color: var(--color-table-border);
+
+  // Header / footer chrome
+  --table-header-bg: var(--color-table-header-bg);
+  --table-header-bg-hover: var(--color-table-header-bg-hover);
+  --table-header-fg: var(--color-table-header-fg);
+
+  // The hovered header strengthens its text, mirroring what
+  // --avatar-overflow-fg-hover already does on the same surface. Not cosmetic:
+  // #504 moved the hover surface from --color-bg-sunken to
+  // --color-bg-muted-hover, and the muted foreground falls under AA there while
+  // --color-fg clears it comfortably.
+  // @contrast --color-fg-muted on --color-bg-muted-hover = 4.45:1 light
+  // @contrast --color-fg on --color-bg-muted-hover = 11.29:1 light
+  --table-header-fg-hover: var(--color-fg);
+  --table-header-font-weight: var(--font-weight-semibold);
+  --table-footer-bg: var(--color-table-header-bg);
+
+  // Row states
+  --table-row-bg-striped: var(--color-table-row-bg-striped);
+  --table-row-bg-hover: var(--color-table-row-bg-hover);
+  --table-row-bg-selected: var(--color-table-row-bg-selected);
+  --table-row-fg-selected: var(--color-table-row-fg-selected);
+
+  // Caption
+  --table-caption-fg: var(--color-table-caption-fg);
+  --table-caption-font-size: var(--font-size-sm);
+  --table-caption-padding-y: var(--space-2);
+  --table-caption-padding-x: var(--space-3);
+
+  // Density
+  --table-density-comfortable-padding-y: var(--space-2);
+  --table-density-comfortable-padding-x: var(--space-3);
+  --table-density-comfortable-font-size: var(--font-size-md);
+  --table-density-dense-padding-y: var(--space-1);
+  --table-density-dense-padding-x: var(--space-2);
+  --table-density-dense-font-size: var(--font-size-sm);
+
+  // Header inner cluster (label + sort chevron)
+  --table-th-inner-gap: var(--space-1);
+
+  // Sort icon
+  --table-sort-icon-fg: var(--color-table-header-fg);
+  --table-sort-icon-fg-active: var(--color-table-fg);
+
+  // Sortable focus ring
+  --table-sortable-ring: var(--ring-accent);
+
+  // Cell tones (Table.Cell / Table.HeaderCell `tone`). Text-on-tint pairs are
+  // pinned in src/styles/contrast.test.ts for both themes.
+  --table-cell-bg-danger: var(--color-danger-bg-subtle);
+  --table-cell-fg-danger: var(--color-danger);
+  --table-cell-bg-accent: var(--color-accent-bg-subtle);
+  --table-cell-fg-accent: var(--color-accent);
+  --table-cell-tone-header-radius: var(--radius-md);
+
+  // Table.CellLink. The hover overlay darkens whatever the cell paints (plain,
+  // striped, hovered row or a tone tint). On a toned cell that pulls the base
+  // tone under AA in light, so hovered text steps to the tone's -hover colour
+  // (pairs also pinned in contrast.test.ts).
+  --table-cell-link-bg-hover: color-mix(in srgb, var(--color-bg-overlay) 25%, transparent);
+  --table-cell-fg-danger-hover: var(--color-danger-hover);
+  --table-cell-fg-accent-hover: var(--color-accent-hover);
+  --table-cell-link-ring: var(--ring-accent);
+
+  // Semibold marks a whole-cell link as actionable without link-blue text.
+  --table-cell-link-font-weight: var(--font-weight-semibold);
+}