Synchronous Validation Patterns

// ─── Types ───────────────────────────────────────────────────────────────────

export type SyncState = 'IDLE' | 'VALID' | 'INVALID';

export interface FieldState<T> {
  value: T;
  validationState: SyncState;
  error: string | null;
  /** true once the user has interacted with the field at least once */
  isDirty: boolean;
}

/**
 * A validation rule is a pure function: value in, error string or null out.
 * Returning null means the rule passes.
 */
export type ValidationRule<T> = (value: T) => string | null;

// ─── Adapter ─────────────────────────────────────────────────────────────────

/**
 * createSyncValidator returns a reducer that maps a FieldState to a new
 * FieldState by running each rule in order (fail-fast on first violation).
 *
 * No side effects, no I/O — safe to call inside any framework event handler
 * or inside a useMemo/computed without triggering re-renders from within.
 */
export function createSyncValidator<T>(rules: ValidationRule<T>[]) {
  return function validate(state: FieldState<T>): FieldState<T> {
    // Pristine fields remain IDLE; only evaluate after the first interaction.
    if (!state.isDirty) return state;

    let error: string | null = null;

    for (const rule of rules) {
      const result = rule(state.value);
      if (result !== null) {
        error = result;
        break; // fail-fast: surface the first violated rule, not all of them
      }
    }

    return {
      ...state,
      error,
      validationState: error === null ? 'VALID' : 'INVALID',
    };
  };
}

// ─── Event reducer ───────────────────────────────────────────────────────────

type FormEvent =
  | { type: 'CHANGE'; field: string; payload: unknown }
  | { type: 'BLUR';   field: string }
  | { type: 'SUBMIT' }
  | { type: 'RESET' };

type FormState = Record<string, FieldState<unknown>>;

/**
 * Pure reducer: handles all four event types and returns the next FormState.
 * The SUBMIT case force-validates every field regardless of dirty status so
 * that users who never touched a required field still see the error.
 */
export function formReducer(
  state: FormState,
  event: FormEvent,
  validate: (s: FieldState<unknown>) => FieldState<unknown>
): FormState {
  switch (event.type) {
    case 'CHANGE':
      return {
        ...state,
        [event.field]: validate({
          ...state[event.field],
          value: event.payload,
          isDirty: true,
        }),
      };

    case 'BLUR':
      // Re-run rules on blur even if value hasn't changed; handles the case
      // where the user focuses and immediately leaves a required field.
      return {
        ...state,
        [event.field]: validate({
          ...state[event.field],
          isDirty: true,
        }),
      };

    case 'SUBMIT':
      // Force isDirty=true on every field to surface errors on untouched fields.
      return Object.fromEntries(
        Object.entries(state).map(([key, fieldState]) => [
          key,
          validate({ ...fieldState, isDirty: true }),
        ])
      );

    case 'RESET':
      return Object.fromEntries(
        Object.entries(state).map(([key, fieldState]) => [
          key,
          { ...fieldState, isDirty: false, error: null, validationState: 'IDLE' as const },
        ])
      );

    default:
      return state;
  }
}

// Rules are portable: the same function works across every field of the same type.

export const required: ValidationRule<string> = (v) =>
  v.trim().length === 0 ? 'This field is required.' : null;

export const minLength =
  (min: number): ValidationRule<string> =>
  (v) =>
    v.length < min ? `Must be at least ${min} characters.` : null;

export const maxLength =
  (max: number): ValidationRule<string> =>
  (v) =>
    v.length > max ? `Cannot exceed ${max} characters.` : null;

/**
 * Email format check. Deliberately lenient — only rejects obvious non-emails.
 * Do NOT use a 254-character RFC-5321 mega-regex; it backtracks catastrophically
 * on inputs like "aaaaaaaaaaaaaaaaaaaaa@" fed through a stress test.
 */
export const emailFormat: ValidationRule<string> = (v) =>
  /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(v) ? null : 'Enter a valid email address.';

/**
 * Range check for numeric inputs. Note: input.value is always a string,
 * so parse before comparison — never compare a string to a number directly.
 */
export const numericRange =
  (min: number, max: number): ValidationRule<string> =>
  (v) => {
    const n = Number(v); // Number('') returns 0; handle empty separately
    if (v === '' || Number.isNaN(n)) return 'Enter a valid number.';
    if (n < min || n > max) return `Must be between ${min} and ${max}.`;
    return null;
  };

// Wrong — string comparison; "9" > "10" is true because "9" > "1" lexicographically
if (state.value > '10') { ... }

// Correct
const n = Number(state.value);
if (Number.isNaN(n) || n > 10) { ... }

export const validDate: ValidationRule<string> = (v) => {
  if (!v) return 'Date is required.';
  const d = new Date(v);
  // new Date('invalid') returns a Date object, but getTime() returns NaN
  return Number.isNaN(d.getTime()) ? 'Enter a valid date.' : null;
};

function normalizeDecimal(v: string, locale: string): number {
  // Detect whether this locale uses comma as decimal separator
  const sample = (1.1).toLocaleString(locale);
  const decimalSep = sample.includes(',') ? ',' : '.';
  const normalized = decimalSep === ',' ? v.replace(',', '.') : v;
  return parseFloat(normalized);
}

function getCheckedValues(name: string, form: HTMLFormElement): string[] {
  const inputs = form.querySelectorAll<HTMLInputElement>(
    `input[type="checkbox"][name="${name}"]`
  );
  return Array.from(inputs)
    .filter((el) => el.checked)
    .map((el) => el.value);
}

<!-- Attach these in your rendering layer, keyed to FieldState.validationState -->
<input
  name="email"
  data-field="email"
  data-validation-state="INVALID"
  aria-invalid="true"
  aria-describedby="email-error"
/>
<p id="email-error" role="alert" data-error-for="email">
  Enter a valid email address.
</p>

// Playwright selector pattern — survives CSS refactors and copy changes
await expect(page.locator('[data-error-for="email"]')).toBeVisible();
await expect(page.locator('[data-field="email"]')).toHaveAttribute(
  'data-validation-state',
  'INVALID'
);
await expect(page.locator('[data-field="email"]')).toHaveAttribute(
  'aria-invalid',
  'true'
);

import AxeBuilder from '@axe-core/playwright';

test('email field error is accessible', async ({ page }) => {
  await page.fill('[name="email"]', 'not-an-email');
  await page.locator('[name="email"]').blur();
  const results = await new AxeBuilder({ page })
    .include('[data-field="email"]')
    .analyze();
  expect(results.violations).toHaveLength(0);
});