field value
field touched/dirty
client validation
server validation
step validity
step navigation
branching path
draft persistence
autosave
submission
permission/precondition
async lookup
optimistic feedback
error recovery
resume after refresh

Step 3 bisa dibuka padahal Step 2 belum valid.
Error server hilang ketika field lain berubah.
Back button mereset field yang tidak seharusnya reset.
Autosave menimpa draft baru dengan response lama.
Submit double-click membuat request ganda.
Conditional field masih terkirim walaupun cabangnya tidak aktif.
User refresh browser dan draft corrupt.
Validation async selesai setelah user pindah step.
Permission berubah ketika form sedang pending.

Field UI:
  ephemeral visual state, focus, local formatting

Draft state:
  user-entered values, possibly persisted

Validation state:
  derived/client/server errors, field/step/global

Navigation state:
  active step, completed steps, allowed transitions

Submission state:
  pending/succeeded/failed, request identity, duplicate prevention

Persistence state:
  draft version, hydration, migration, cleanup

const [step, setStep] = useState(0);

Apakah step ini legal untuk dibuka?
Apakah user datang dari forward navigation atau back navigation?
Apakah step ini valid?
Apakah ada async validation pending?
Apakah step berikutnya conditional?
Apakah draft sudah disimpan?
Apakah step ini bisa dilewati?

type StepId =
  | 'applicant'
  | 'employment'
  | 'documents'
  | 'review'
  | 'submit';

type StepStatus =
  | 'locked'
  | 'available'
  | 'active'
  | 'completed'
  | 'invalid'
  | 'pending';

type FormPhase =
  | 'hydrating'
  | 'editing'
  | 'validatingStep'
  | 'autosaving'
  | 'submitting'
  | 'submitted'
  | 'failed';

field value = source state
step validity = derived state
server error = external feedback state
step completion = workflow state

type FormEvent =
  | { type: 'form.hydrated'; draft: Draft; version: number }
  | { type: 'field.changed'; field: FieldPath; value: unknown }
  | { type: 'field.blurred'; field: FieldPath }
  | { type: 'step.next.requested' }
  | { type: 'step.previous.requested' }
  | { type: 'step.goto.requested'; step: StepId }
  | { type: 'step.validation.succeeded'; step: StepId }
  | { type: 'step.validation.failed'; step: StepId; errors: ValidationError[] }
  | { type: 'draft.save.requested' }
  | { type: 'draft.save.succeeded'; version: number }
  | { type: 'draft.save.failed'; reason: string }
  | { type: 'form.submit.requested' }
  | { type: 'form.submit.succeeded'; applicationId: string }
  | { type: 'form.submit.failed'; errors: ValidationError[] }
  | { type: 'form.abandon.requested' }
  | { type: 'form.reset.requested' };

type WizardState = {
  phase: FormPhase;
  activeStep: StepId;
  draft: Draft;
  touched: Partial<Record<FieldPath, boolean>>;
  clientErrors: ValidationError[];
  serverErrors: ValidationError[];
  completedSteps: StepId[];
  requestId: string | null;
};

function wizardReducer(state: WizardState, event: FormEvent): WizardState {
  switch (event.type) {
    case 'field.changed': {
      return {
        ...state,
        draft: setDraftValue(state.draft, event.field, event.value),
        serverErrors: clearServerErrorsForField(state.serverErrors, event.field),
      };
    }

    case 'field.blurred': {
      return {
        ...state,
        touched: { ...state.touched, [event.field]: true },
      };
    }

    case 'step.validation.failed': {
      return {
        ...state,
        phase: 'editing',
        clientErrors: event.errors,
      };
    }

    case 'step.validation.succeeded': {
      const nextStep = getNextStep(state.activeStep, state.draft);
      return {
        ...state,
        phase: 'editing',
        activeStep: nextStep,
        completedSteps: addUnique(state.completedSteps, state.activeStep),
        clientErrors: [],
      };
    }

    default:
      return state;
  }
}

type FieldMeta = {
  path: FieldPath;
  step: StepId;
  label: string;
  required: boolean;
  activeWhen?: (draft: Draft) => boolean;
  validate?: (value: unknown, draft: Draft) => ValidationError[];
  normalize?: (value: unknown) => unknown;
  serialize?: (value: unknown) => unknown;
};

type FieldRegistry = Record<FieldPath, FieldMeta>;

validation can iterate active fields
review screen can render summary consistently
inactive branch fields can be excluded from payload
field errors can map to labels
step validity can be derived
accessibility IDs can be generated consistently

field-level validation:
  email format
  required field
  min/max length

cross-field validation:
  start date <= end date
  country determines postal code rules
  applicant type determines required documents

step-level validation:
  all required fields in step valid
  at least one contact method present

workflow-level validation:
  all steps complete
  user has accepted declarations
  terms version current

server validation:
  uniqueness
  permission
  policy/rule engine
  stale entity version

type ValidationError = {
  scope: 'field' | 'step' | 'form' | 'server';
  field?: FieldPath;
  step?: StepId;
  code: string;
  message: string;
  blocking: boolean;
};

Which field owns this error?
Which step should show badge?
Is it blocking submit?
Should it clear when field changes?
Is it client or server error?

authorization
uniqueness
business rules
cross-entity constraints
stale version/conflict
regulatory policy
backend-only invariants

fast feedback
obvious format checks
required visible fields
step gating UX
reducing unnecessary server calls

type SubmitResult =
  | { ok: true; applicationId: string }
  | { ok: false; errors: ValidationError[]; serverVersion?: number };

async function submitApplication(draft: Draft): Promise<SubmitResult> {
  const response = await fetch('/api/applications', {
    method: 'POST',
    body: JSON.stringify(toSubmissionPayload(draft)),
    headers: { 'content-type': 'application/json' },
  });

  const body = await response.json();

  if (!response.ok) {
    return { ok: false, errors: normalizeServerErrors(body) };
  }

  return { ok: true, applicationId: body.id };
}

Applicant type:
  individual -> personal details + employment
  company -> company profile + authorized representative

What happens to inactive branch data?

function toSubmissionPayload(draft: Draft): SubmissionPayload {
  if (draft.applicantType === 'individual') {
    return {
      applicantType: 'individual',
      personal: draft.personal,
      employment: draft.employment,
    };
  }

  return {
    applicantType: 'company',
    company: draft.company,
    representative: draft.representative,
  };
}

schema version
migration
validation on read
TTL/retention
user/session scope
encryption/security policy if sensitive
logout cleanup
multi-tab behavior
server sync or local-only policy
conflict handling

type DraftRecord = {
  schemaVersion: 3;
  userId: string;
  formId: string;
  draft: Draft;
  savedAt: string;
  expiresAt: string;
  serverDraftVersion?: number;
};

function readDraft(key: string): DraftRecord | null {
  const raw = localStorage.getItem(key);
  if (!raw) return null;

  try {
    const parsed = JSON.parse(raw);
    return validateAndMigrateDraft(parsed);
  } catch {
    return null;
  }
}

function writeDraft(key: string, record: DraftRecord) {
  localStorage.setItem(key, JSON.stringify(record));
}

useEffect(() => {
  saveDraft(draft);
}, [draft]);

field.changed -> draft becomes dirty
wait debounce interval
save latest draft with requestId/version
if response older than current version, ignore
if save fails, expose recoverable error

type AutosaveState = {
  status: 'idle' | 'dirty' | 'saving' | 'saved' | 'failed';
  localVersion: number;
  lastSavedVersion: number;
  lastSavedAt: string | null;
  error: string | null;
};

type AutosaveEvent =
  | { type: 'draft.changed'; localVersion: number }
  | { type: 'save.started'; requestVersion: number }
  | { type: 'save.succeeded'; requestVersion: number; savedAt: string }
  | { type: 'save.failed'; requestVersion: number; reason: string };

function autosaveReducer(state: AutosaveState, event: AutosaveEvent): AutosaveState {
  switch (event.type) {
    case 'save.succeeded': {
      if (event.requestVersion < state.localVersion) {
        return {
          ...state,
          status: 'dirty',
          lastSavedVersion: event.requestVersion,
          lastSavedAt: event.savedAt,
        };
      }

      return {
        ...state,
        status: 'saved',
        lastSavedVersion: event.requestVersion,
        lastSavedAt: event.savedAt,
        error: null,
      };
    }

    case 'save.failed': {
      if (event.requestVersion < state.localVersion) {
        return state;
      }

      return {
        ...state,
        status: 'failed',
        error: event.reason,
      };
    }

    default:
      return state;
  }
}

type NavigationPolicy = {
  canGoNext(state: WizardState): boolean;
  canGoPrevious(state: WizardState): boolean;
  canGoTo(step: StepId, state: WizardState): boolean;
  getNextStep(current: StepId, draft: Draft): StepId;
  getPreviousStep(current: StepId, draft: Draft): StepId;
};

Back navigation usually allowed unless submitting.
Forward navigation usually requires current step validity.
Direct jump to completed step allowed.
Direct jump to locked future step denied.
Branch changes may invalidate future steps.
Submit allowed only from review/submit phase and valid full form.

steps are shareable/bookmarkable
refresh should preserve current step
browser Back/Forward should navigate steps
route guards are needed
support user needs resumability

step contains sensitive branching
step is purely local/modal sub-flow
step cannot be legally opened without hidden session state

/application/new?step=documents

function resolveRequestedStep(requested: StepId, state: WizardState): StepId {
  if (canGoTo(requested, state)) return requested;
  return firstInvalidOrAvailableStep(state);
}

type WizardApi = {
  snapshot: WizardSnapshot;
  fields: {
    getValue(path: FieldPath): unknown;
    setValue(path: FieldPath, value: unknown): void;
    blur(path: FieldPath): void;
    getError(path: FieldPath): ValidationError | null;
  };
  navigation: {
    next(): void;
    previous(): void;
    goTo(step: StepId): void;
  };
  submit(): void;
  reset(): void;
};

type WizardSnapshot = {
  phase: FormPhase;
  activeStep: StepId;
  steps: Array<{
    id: StepId;
    label: string;
    status: StepStatus;
    errorCount: number;
  }>;
  canGoNext: boolean;
  canGoPrevious: boolean;
  canSubmit: boolean;
  isBusy: boolean;
  submitError: string | null;
  autosave: AutosaveState;
};

<WizardProvider actor={applicationWizardActor}>
  <WizardLayout>
    <WizardSidebar />
    <WizardStep id="applicant">
      <ApplicantStep />
    </WizardStep>
    <WizardStep id="employment">
      <EmploymentStep />
    </WizardStep>
    <WizardStep id="documents">
      <DocumentsStep />
    </WizardStep>
    <WizardStep id="review">
      <ReviewStep />
    </WizardStep>
    <WizardFooter />
  </WizardLayout>
</WizardProvider>

function ApplicantStep() {
  const name = useWizardField<string>('applicant.name');
  const email = useWizardField<string>('applicant.email');

  return (
    <section aria-labelledby="applicant-title">
      <h2 id="applicant-title">Applicant</h2>

      <TextField
        label="Name"
        value={name.value ?? ''}
        onChange={name.setValue}
        onBlur={name.blur}
        error={name.error?.message}
      />

      <TextField
        label="Email"
        value={email.value ?? ''}
        onChange={email.setValue}
        onBlur={email.blur}
        error={email.error?.message}
      />
    </section>
  );
}

type FieldApi<T> = {
  value: T;
  setValue(value: T): void;
  blur(): void;
  error: ValidationError | null;
  touched: boolean;
  dirty: boolean;
  required: boolean;
  describedBy: string | undefined;
  invalid: boolean;
};

small forms:
  useContext + reducer state

medium forms:
  context + selector external store

complex forms:
  actor/store per wizard + field selector subscription

very dynamic forms:
  registry + selector subscription + validation graph

Changing one field should not rerender the entire form tree unless the screen is small enough that it does not matter.

Every input has a label.
Field error is associated with input.
Invalid fields expose invalid state.
Step changes manage focus intentionally.
Errors are summarized after failed submit/step validation.
Keyboard navigation is predictable.
Progress indicator is understandable.
Required fields are communicated.

function TextField(props: {
  id: string;
  label: string;
  value: string;
  onChange(value: string): void;
  onBlur(): void;
  error?: string;
  required?: boolean;
}) {
  const errorId = props.error ? `${props.id}-error` : undefined;

  return (
    <div>
      <label htmlFor={props.id}>{props.label}</label>
      <input
        id={props.id}
        value={props.value}
        required={props.required}
        aria-invalid={props.error ? 'true' : 'false'}
        aria-describedby={errorId}
        onChange={(event) => props.onChange(event.target.value)}
        onBlur={props.onBlur}
      />
      {props.error ? (
        <p id={errorId} role="alert">
          {props.error}
        </p>
      ) : null}
    </div>
  );
}

function ErrorSummary({ errors }: { errors: ValidationError[] }) {
  if (errors.length === 0) return null;

  return (
    <section role="alert" aria-labelledby="error-summary-title" tabIndex={-1}>
      <h2 id="error-summary-title">Please fix the following issues</h2>
      <ul>
        {errors.map((error) => (
          <li key={`${error.field}-${error.code}`}>
            {error.message}
          </li>
        ))}
      </ul>
    </section>
  );
}

submission command
server validation result
pending state
progressive enhancement depending on framework/runtime
form-level result state

step navigation
draft state
client validation
branching
field registry
autosave
resume
conditional submit enablement

function ApplicationSubmitForm({ wizard }: { wizard: WizardApi }) {
  const [result, submitAction, isPending] = useActionState(
    async (_previous: SubmitResult | null, formData: FormData) => {
      const payload = wizardToPayload(wizard.snapshot, formData);
      return submitApplication(payload);
    },
    null,
  );

  return (
    <form action={submitAction}>
      <ReviewStep />
      <button type="submit" disabled={!wizard.snapshot.canSubmit || isPending}>
        {isPending ? 'Submitting...' : 'Submit'}
      </button>
      {result?.ok === false ? <ErrorSummary errors={result.errors} /> : null}
    </form>
  );
}

wizard owns draft/workflow
mutation owns server command/cache invalidation
wizard receives mutation result/error as event

submit -> pending -> server validates -> success/failure

autosave saved indicator
local draft progress
temporary attachment preview
mark step completed locally before server sync, if reversible

type Draft = {
  documents: Array<{
    type: 'identity' | 'employment' | 'supporting';
    assetId: string;
    fileName: string;
  }>;
};

{ type: 'document.attached'; assetId: string; fileName: string; documentType: DocumentType }
{ type: 'document.removed'; assetId: string }

refresh page
browser crashes
autosave failed
server draft is newer than local draft
schema changed since draft created
user opens form in two tabs
user loses permission halfway
entity submitted from another session

hydrating -> editing
hydrating -> recoveryNeeded
hydrating -> blocked
editing -> blocked
submitting -> submittedElsewhere

field.changed updates draft
inactive branch is excluded from payload
next is denied when current step invalid
server field error maps to correct field
stale autosave result is ignored
submit denied when required document missing

field rules
cross-field rules
branch rules
step validity
server error normalization

field displays label/error
click next validates step
invalid submit focuses summary
back keeps draft
branch toggle changes visible steps

complete happy path
server validation failure path
autosave recovery path
refresh and resume path
file upload failure/retry path
permission lost path

labels connected
aria-invalid set only when invalid
error text associated with field
focus lands on meaningful target after validation failure
keyboard-only navigation works

User can open step 4 by changing URL or clicking progress indicator.

Model legal navigation.
Resolve requested step through workflow guard.

Back/forward loses data.
Review screen cannot reliably read full draft.
Validation duplicated per step.

Centralize draft ownership in form hook/actor.
Use field hooks for local access.

Changing unrelated field clears all server errors.

Clear field-specific server error only when that field changes.
Keep form-level server error until next submit or explicit dismiss.

Company-only data is submitted when applicant type is individual.

Serialize payload from active branch rules.
Do not submit raw draft blindly.

Older save response marks newer draft as saved.

Use localVersion/requestVersion.
Ignore stale response.

Every field change triggers full server validation.

Use client validation locally.
Debounce async checks.
Run full server validation on step transition or submit.

Step badge says valid but field has error.

Derive step validity from active field errors when possible.
Store only history that cannot be derived.

Double click creates two applications.

Disable submit during pending.
Use idempotency key on server command.
Guard in workflow state.

Errors visible but not announced or associated.

Use labels, aria-invalid, aria-describedby, summary, focus management.

features/application-form/
  model/
    draft.ts
    events.ts
    validation.ts
    navigation.ts
    machine.ts
    selectors.ts
    persistence.ts
    payload.ts
  ui/
    ApplicationWizard.tsx
    WizardProvider.tsx
    WizardLayout.tsx
    WizardSidebar.tsx
    WizardFooter.tsx
    fields/
      TextField.tsx
      SelectField.tsx
      DateField.tsx
    steps/
      ApplicantStep.tsx
      EmploymentStep.tsx
      DocumentsStep.tsx
      ReviewStep.tsx
  api/
    submitApplication.ts
    saveDraft.ts
    validateStep.ts
  tests/
    validation.test.ts
    machine.test.ts
    payload.test.ts
    application-wizard.test.tsx

model knows workflow rules
ui knows rendering/composition
api knows transport
payload knows serialization boundary
validation knows rule evaluation
persistence knows draft storage policy

Who owns the draft?
Who owns step legality?
Who owns validation authority?
Who owns persistence?
Who owns submission lifecycle?
Who owns uploaded file lifecycle?
Who owns recovery after refresh/failure?

events are explicit
state topology is clear
validation has structure
navigation is guarded
server errors map deterministically
persistence has versioning
submission is idempotent
accessibility is built into field contracts