@eocrm/design-system 0.0.0-stage → 0.6.17

package/src/components/Radio/Radio.module.scss

@@ -0,0 +1,175 @@
+@use '../../styles/mixins' as *;
+@use './Radio.tokens';
+
+.radio {
+  // Anchors the visually-hidden input so a scrolling ancestor clips it (#670).
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  gap: var(--radio-gap);
+  cursor: pointer;
+  user-select: none;
+
+  // Pin baseline contribution so the surrounding line-box stays stable
+  // when the dot appears/disappears. Same rationale as Checkbox.
+  vertical-align: middle;
+
+  &.disabled {
+    cursor: not-allowed;
+  }
+}
+
+// Visually-hidden native input — stays in tab order + AT tree + native
+// arrow-key navigation between same-name radios.
+// stylelint-disable property-disallowed-list -- visually-hidden recipe needs `margin: -1px`; internal-implementation detail, not a public layout property. Same precedent as Checkbox + Avatar visually-hidden inputs.
+.input {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+  border: 0;
+}
+// stylelint-enable property-disallowed-list
+
+// The painted ring (outer circle).
+.ring {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  box-sizing: border-box;
+
+  // Constant line-box height across checked/unchecked states.
+  line-height: 1;
+  border: var(--border-width) solid var(--radio-ring-border-color);
+  border-radius: var(--radio-ring-radius);
+  background: var(--radio-ring-bg);
+  transition:
+    border-color var(--transition-fast),
+    box-shadow var(--transition-fast);
+}
+
+// The painted inner dot — hidden (transparent bg) until checked. Diameter
+// is set per-size below to whole-pixel values so the dot always sits on
+// the pixel grid (no asymmetric sub-pixel snapping at md / lg).
+.dot {
+  border-radius: var(--radio-dot-radius);
+  background: transparent;
+  transition: background var(--transition-fast);
+}
+
+// Size modifiers — ring diameter + dot diameter + label font.
+.size-sm .ring {
+  width: var(--radio-ring-size-sm);
+  height: var(--radio-ring-size-sm);
+}
+
+.size-sm .dot {
+  width: var(--radio-dot-size-sm);
+  height: var(--radio-dot-size-sm);
+}
+
+.size-md .ring {
+  width: var(--radio-ring-size-md);
+  height: var(--radio-ring-size-md);
+}
+
+.size-md .dot {
+  width: var(--radio-dot-size-md);
+  height: var(--radio-dot-size-md);
+}
+
+.size-lg .ring {
+  width: var(--radio-ring-size-lg);
+  height: var(--radio-ring-size-lg);
+}
+
+.size-lg .dot {
+  width: var(--radio-dot-size-lg);
+  height: var(--radio-dot-size-lg);
+}
+
+.size-sm .labelText {
+  font-size: var(--radio-label-font-size-sm);
+}
+
+.size-md .labelText {
+  font-size: var(--radio-label-font-size-md);
+}
+
+.size-lg .labelText {
+  font-size: var(--radio-label-font-size-lg);
+}
+
+// Hover preview — border-only shift to accent. Excludes .disabled AND
+// .invalid so the danger border stays visible on hover (same fix as
+// Checkbox cycle-1).
+.radio:not(.disabled, .invalid):hover .ring {
+  border-color: var(--radio-ring-border-color-hover);
+}
+
+// Checked — accent border + filled accent dot.
+.input:checked + .ring {
+  border-color: var(--radio-ring-border-color-checked);
+}
+
+.input:checked + .ring .dot {
+  background: var(--radio-dot-bg-checked);
+}
+
+// Focus ring on the ring (sibling selector picks up native input focus).
+.input:focus-visible + .ring {
+  @include focus-ring(var(--radio-ring-focus));
+}
+
+// Disabled — muted bg + border + dot.
+// Specificity note: `.input:checked + .ring` is 3 classes (0,3,0); the
+// plain `.disabled .ring` rule is only (0,2,0) and loses on checked
+// radios. The `.disabled .input:checked + .ring` rule below is (0,4,0)
+// and wins so a disabled+checked radio keeps the gray border instead of
+// reverting to accent blue.
+.disabled .ring {
+  background: var(--radio-ring-bg-disabled);
+  border-color: var(--radio-ring-border-color-disabled);
+}
+
+.disabled .input:checked + .ring {
+  border-color: var(--radio-ring-border-color-disabled);
+}
+
+.disabled .input:checked + .ring .dot {
+  background: var(--radio-dot-bg-checked-disabled);
+}
+
+.disabled .labelText {
+  color: var(--radio-label-fg-disabled);
+}
+
+// Invalid — danger border + danger dot + danger focus ring.
+// Same specificity dance as .disabled: the plain `.invalid .ring` rule
+// (0,2,0) loses to `.input:checked + .ring` (0,3,0), so an invalid +
+// checked radio would render with an accent-blue border instead of red.
+// The explicit `.invalid .input:checked + .ring` rule (0,4,0) wins.
+.invalid .ring {
+  border-color: var(--radio-ring-border-color-invalid);
+}
+
+.invalid .input:checked + .ring {
+  border-color: var(--radio-ring-border-color-invalid);
+}
+
+.invalid .input:checked + .ring .dot {
+  background: var(--radio-dot-bg-checked-invalid);
+}
+
+.invalid .input:focus-visible + .ring {
+  @include focus-ring(var(--radio-ring-focus-invalid));
+}
+
+.labelText {
+  line-height: var(--radio-label-line-height);
+}

package/src/components/Radio/Radio.tokens.scss

@@ -0,0 +1,59 @@
+// Radio.tokens.scss — component-scoped tokens for <Radio> and <RadioGroup>. Mirrors Checkbox structure: visually-hidden native input + painted ring + painted dot.
+:root {
+  // Layout
+  --radio-gap: var(--space-2);
+
+  // Ring (outer circle)
+  --radio-ring-bg: var(--color-bg);
+  --radio-ring-border-color: var(--color-border-strong);
+  --radio-ring-border-color-hover: var(--color-accent);
+  --radio-ring-border-color-checked: var(--color-accent);
+  --radio-ring-radius: var(--radius-full);
+
+  // Focus ring
+  --radio-ring-focus: var(--ring-accent);
+
+  // Dot (inner painted circle)
+  --radio-dot-bg-checked: var(--color-accent);
+  --radio-dot-radius: var(--radius-full);
+
+  // Disabled
+  --radio-ring-bg-disabled: var(--color-bg-subtle);
+  --radio-ring-border-color-disabled: var(--color-border);
+  --radio-dot-bg-checked-disabled: var(--color-fg-disabled);
+  --radio-label-fg-disabled: var(--color-fg-disabled);
+
+  // Invalid
+  --radio-ring-border-color-invalid: var(--color-danger);
+  --radio-dot-bg-checked-invalid: var(--color-danger);
+  --radio-ring-focus-invalid: var(--ring-danger);
+
+  // Size — ring diameter per size
+  --radio-ring-size-sm: var(--size-radio-sm);
+  --radio-ring-size-md: var(--size-radio-md);
+  --radio-ring-size-lg: var(--size-radio-lg);
+
+  // Size — dot diameter per size
+  --radio-dot-size-sm: var(--size-radio-dot-sm);
+  --radio-dot-size-md: var(--size-radio-dot-md);
+  --radio-dot-size-lg: var(--size-radio-dot-lg);
+
+  // Size — label font-size per size
+  --radio-label-font-size-sm: var(--font-size-sm);
+  --radio-label-font-size-md: var(--font-size-md);
+  --radio-label-font-size-lg: var(--font-size-lg);
+
+  // Label
+  --radio-label-line-height: var(--line-height-normal);
+
+  // RadioGroup — legend
+  --radio-group-legend-fg: var(--color-fg);
+  --radio-group-legend-font-size: var(--font-size-md);
+  --radio-group-legend-font-weight: var(--font-weight-semibold);
+  --radio-group-legend-margin-bottom: var(--space-2);
+  --radio-group-legend-fg-invalid: var(--color-danger);
+
+  // RadioGroup — items
+  --radio-group-gap-vertical: var(--space-2);
+  --radio-group-gap-horizontal: var(--space-4);
+}

package/src/components/Radio/Radio.tsx

@@ -0,0 +1,127 @@
+import { forwardRef, type ChangeEvent, type InputHTMLAttributes, type ReactNode } from 'react';
+import clsx from 'clsx';
+import { useRadioGroup } from './RadioGroupContext';
+import styles from './Radio.module.scss';
+
+/** Ring diameter + label type scale. Same scale as `<Checkbox>` / `<Input>`. */
+export type RadioSize = 'sm' | 'md' | 'lg';
+
+export interface RadioProps extends Omit<
+  InputHTMLAttributes<HTMLInputElement>,
+  'size' | 'type' | 'checked' | 'defaultChecked' | 'onChange'
+> {
+  /** The value submitted when this radio is selected. */
+  value: string;
+
+  /**
+   * Ring diameter + label type scale. Defaults to `'md'`.
+   * - `'sm'` — 14px ring, font-size-sm label.
+   * - `'md'` — 16px ring, font-size-md label.
+   * - `'lg'` — 20px ring, font-size-lg label.
+   *
+   * Inside `<RadioGroup>`, the group's `size` becomes the default; explicit
+   * per-radio `size` still wins.
+   */
+  size?: RadioSize;
+
+  /**
+   * Controlled checked state. Inside `<RadioGroup>`, leave this unset —
+   * the group computes `checked` from its `value`. If you explicitly set
+   * `checked` on a Radio inside a group, your prop wins and the group's
+   * controlled invariant breaks (don't do this).
+   */
+  checked?: boolean;
+
+  /** Initial checked state for uncontrolled standalone use. */
+  defaultChecked?: boolean;
+
+  /**
+   * Label rendered next to the ring. The whole `<label>` is the click
+   * target. Omit for icon-only radios + pass `aria-label`.
+   */
+  label?: ReactNode;
+
+  /**
+   * Toggles the error visual + `aria-invalid='true'`. Inside a
+   * `<RadioGroup>`, the group's `invalid` becomes the default for this
+   * radio — explicit per-child `invalid` (including `false`) still wins.
+   */
+  invalid?: boolean;
+
+  /**
+   * Fires when the radio is selected. Receives the radio's `value` AND
+   * the native event. Inside a group, this runs FIRST, then the group's
+   * `onChange` fires.
+   */
+  onChange?: (value: string, event: ChangeEvent<HTMLInputElement>) => void;
+}
+
+/**
+ * Single radio button: a visually-hidden native `<input type="radio">` with a custom ring and dot; standalone or in a `<RadioGroup>`.
+ * @see docs/components/Radio.md
+ */
+export const Radio = forwardRef<HTMLInputElement, RadioProps>(function Radio(
+  {
+    value,
+    size,
+    checked,
+    defaultChecked,
+    label,
+    invalid,
+    onChange,
+    className,
+    disabled,
+    name,
+    required,
+    ...props
+  },
+  ref,
+) {
+  const group = useRadioGroup();
+
+  // Group props win as defaults; per-radio explicit props win over group.
+  const resolvedSize: RadioSize = size ?? group?.size ?? 'md';
+  const resolvedDisabled = disabled ?? group?.disabled ?? false;
+  const resolvedInvalid = invalid ?? group?.invalid ?? false;
+  const resolvedRequired = required ?? group?.required ?? false;
+  const resolvedName = name ?? group?.name;
+  const resolvedChecked = checked ?? (group != null ? group.value === value : undefined);
+
+  const handleChange = (event: ChangeEvent<HTMLInputElement>) => {
+    onChange?.(value, event);
+    group?.onChange(value, event);
+  };
+
+  return (
+    <label
+      className={clsx(
+        styles.radio,
+        styles[`size-${resolvedSize}`],
+        resolvedDisabled && styles.disabled,
+        resolvedInvalid && styles.invalid,
+        className,
+      )}
+    >
+      {/* Pattern B — props first so component-owned attrs (type, value, name,
+          checked, disabled, required, onChange, className) win. */}
+      <input
+        {...props}
+        ref={ref}
+        type="radio"
+        name={resolvedName}
+        value={value}
+        checked={resolvedChecked}
+        defaultChecked={resolvedChecked === undefined ? defaultChecked : undefined}
+        disabled={resolvedDisabled}
+        required={resolvedRequired}
+        aria-invalid={resolvedInvalid || undefined}
+        onChange={handleChange}
+        className={styles.input}
+      />
+      <span aria-hidden="true" className={styles.ring}>
+        <span className={styles.dot} />
+      </span>
+      {label != null && <span className={styles.labelText}>{label}</span>}
+    </label>
+  );
+});

package/src/components/Radio/RadioGroup.module.scss

@@ -0,0 +1,42 @@
+@use './Radio.tokens';
+
+// stylelint-disable property-disallowed-list -- fieldset/legend reset + internal layout gap; not a layout property on the public component box.
+.group {
+  // Reset the user-agent fieldset chrome — we paint our own.
+  margin: 0;
+  padding: 0;
+  border: 0;
+  min-width: 0;
+}
+
+.legend {
+  // Reset the user-agent legend margin/padding.
+  padding: 0;
+  margin: 0 0 var(--radio-group-legend-margin-bottom) 0;
+  color: var(--radio-group-legend-fg);
+  font-size: var(--radio-group-legend-font-size);
+  font-weight: var(--radio-group-legend-font-weight);
+}
+// stylelint-enable property-disallowed-list
+
+.items {
+  display: flex;
+}
+
+.orientation-vertical .items {
+  flex-direction: column;
+  gap: var(--radio-group-gap-vertical);
+}
+
+.orientation-horizontal .items {
+  flex-direction: row;
+  flex-wrap: wrap;
+  gap: var(--radio-group-gap-horizontal);
+}
+
+// Invalid state on the group — the per-radio invalid styling is handled
+// inside Radio.module.scss via the context-propagated `invalid` prop. We
+// add the danger color to the legend so the group label also signals error.
+.invalid .legend {
+  color: var(--radio-group-legend-fg-invalid);
+}

package/src/components/Radio/RadioGroup.tsx

@@ -0,0 +1,120 @@
+import {
+  forwardRef,
+  useMemo,
+  useState,
+  type ChangeEvent,
+  type HTMLAttributes,
+  type ReactNode,
+} from 'react';
+import clsx from 'clsx';
+import { RadioGroupContext, type RadioGroupContextValue } from './RadioGroupContext';
+import type { RadioSize } from './Radio';
+import styles from './RadioGroup.module.scss';
+
+export type RadioGroupOrientation = 'vertical' | 'horizontal';
+
+export interface RadioGroupProps extends Omit<HTMLAttributes<HTMLFieldSetElement>, 'onChange'> {
+  /** Form `name` shared by all radio children. Required. */
+  name: string;
+
+  /** Controlled selected value. Pair with `onChange`. */
+  value?: string;
+
+  /** Initial selected value for uncontrolled use. */
+  defaultValue?: string;
+
+  /**
+   * Fires when the user selects a different radio. Receives the new value
+   * AND the native event so consumers can read modifier keys, etc.
+   */
+  onChange?: (value: string, event: ChangeEvent<HTMLInputElement>) => void;
+
+  /** Optional group label, rendered as `<legend>`. */
+  label?: ReactNode;
+
+  /** Default size for child radios. Per-child explicit `size` wins. Defaults to `'md'`. */
+  size?: RadioSize;
+
+  /** Layout direction. `'vertical'` (default) / `'horizontal'`. */
+  orientation?: RadioGroupOrientation;
+
+  /** Disable every child. Per-child explicit `disabled` wins. */
+  disabled?: boolean;
+
+  /** Apply the invalid visual to every child + set `aria-invalid` on the fieldset. */
+  invalid?: boolean;
+
+  /** Mark every child as required (HTML form validation). */
+  required?: boolean;
+
+  children: ReactNode;
+}
+
+/**
+ * Group wrapper for `<Radio>` children: a `<fieldset>` + optional `<legend>` that propagates name, value and shared props via context.
+ * @see docs/components/RadioGroup.md
+ */
+export const RadioGroup = forwardRef<HTMLFieldSetElement, RadioGroupProps>(function RadioGroup(
+  {
+    name,
+    value,
+    defaultValue,
+    onChange,
+    label,
+    size = 'md',
+    orientation = 'vertical',
+    disabled = false,
+    invalid = false,
+    required = false,
+    className,
+    children,
+    ...props
+  },
+  ref,
+) {
+  const isControlled = value !== undefined;
+  const [internalValue, setInternalValue] = useState<string | null>(defaultValue ?? null);
+  const currentValue = isControlled ? (value ?? null) : internalValue;
+
+  const handleChange = (next: string, event: ChangeEvent<HTMLInputElement>) => {
+    if (!isControlled) setInternalValue(next);
+    onChange?.(next, event);
+  };
+
+  const ctx: RadioGroupContextValue = useMemo(
+    () => ({
+      name,
+      value: currentValue,
+      onChange: handleChange,
+      size,
+      disabled,
+      invalid,
+      required,
+    }),
+    // handleChange is stable enough — it reads isControlled / onChange via
+    // closure, which both update only when the parent re-renders. The Radio
+    // children read context on every render anyway.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [name, currentValue, size, disabled, invalid, required, onChange],
+  );
+
+  return (
+    // Pattern A — props last so consumer overrides win.
+    <fieldset
+      ref={ref}
+      aria-invalid={invalid || undefined}
+      className={clsx(
+        styles.group,
+        styles[`orientation-${orientation}`],
+        invalid && styles.invalid,
+        className,
+      )}
+      {...props}
+    >
+      {label != null && <legend className={styles.legend}>{label}</legend>}
+      <RadioGroupContext.Provider value={ctx}>
+        <div className={styles.items}>{children}</div>
+      </RadioGroupContext.Provider>
+    </fieldset>
+  );
+});

package/src/components/Radio/RadioGroupContext.tsx

@@ -0,0 +1,30 @@
+import { createContext, useContext, type ChangeEvent } from 'react';
+import type { RadioSize } from './Radio';
+
+export interface RadioGroupContextValue {
+  /** Form name shared by every radio in the group. */
+  name: string;
+  /** Currently-selected value (or `null` if none). */
+  value: string | null;
+  /** Called when any child radio is selected. */
+  onChange: (value: string, event: ChangeEvent<HTMLInputElement>) => void;
+  /** Default size for child radios. Per-child explicit `size` wins. */
+  size: RadioSize;
+  /** When true, every child radio is disabled (per-child explicit override still wins). */
+  disabled: boolean;
+  /** When true, every child radio shows the invalid visual. */
+  invalid: boolean;
+  /** When true, every child radio carries the native `required` attribute. */
+  required: boolean;
+}
+
+/**
+ * Internal context — `<RadioGroup>` sets it, descendant `<Radio>`s read it.
+ * `null` means the radio is standalone.
+ */
+export const RadioGroupContext = createContext<RadioGroupContextValue | null>(null);
+
+/** Read the surrounding RadioGroup context; `null` when standalone. */
+export function useRadioGroup(): RadioGroupContextValue | null {
+  return useContext(RadioGroupContext);
+}

package/src/components/Radio/index.ts

@@ -0,0 +1,4 @@
+export { Radio } from './Radio';
+export type { RadioProps, RadioSize } from './Radio';
+export { RadioGroup } from './RadioGroup';
+export type { RadioGroupProps, RadioGroupOrientation } from './RadioGroup';