user submits form
→ React starts an Action
→ pending state becomes observable
→ Action validates/mutates
→ Action returns result or throws
→ UI reconciles with result
→ uncontrolled fields may reset
→ cache/navigation/optimistic layer may update

function ProfileForm() {
  const [name, setName] = useState("");
  const [status, setStatus] = useState<"idle" | "submitting" | "success" | "error">("idle");
  const [error, setError] = useState<string | null>(null);

  async function onSubmit(event: React.FormEvent<HTMLFormElement>) {
    event.preventDefault();

    setStatus("submitting");
    setError(null);

    try {
      await updateProfile({ name });
      setStatus("success");
    } catch (error) {
      setStatus("error");
      setError("Failed to update profile");
    }
  }

  return (
    <form onSubmit={onSubmit}>
      <input value={name} onChange={(event) => setName(event.target.value)} />
      <button disabled={status === "submitting"}>Save</button>
      {error && <p role="alert">{error}</p>}
    </form>
  );
}

manual preventDefault
manual pending state
manual error state
manual reset
manual duplicate-submit guard
manual race guard
manual server validation mapping
manual optimistic update
manual navigation after success
manual cache invalidation
manual accessibility status
manual retry policy

Command = intent user yang boleh mengubah state eksternal

CreateInvoice
ApproveCase
UpdateProfile
AssignInvestigator
SubmitEvidence
ArchiveNotification

async function updateName(formData: FormData) {
  const name = String(formData.get("name") ?? "");
  await saveName(name);
}

export function NameForm() {
  return (
    <form action={updateName}>
      <input name="name" />
      <button>Save</button>
    </form>
  );
}

<form action={fn}>

const [state, formAction, isPending] = useActionState(action, initialState);

type ProfileActionState =
  | {
      status: "idle";
      message: null;
      fieldErrors: {};
    }
  | {
      status: "invalid";
      message: string;
      fieldErrors: {
        name?: string;
        email?: string;
      };
    }
  | {
      status: "success";
      message: string;
      fieldErrors: {};
    };

const initialState: ProfileActionState = {
  status: "idle",
  message: null,
  fieldErrors: {},
};

async function updateProfileAction(
  previousState: ProfileActionState,
  formData: FormData
): Promise<ProfileActionState> {
  const name = String(formData.get("name") ?? "").trim();
  const email = String(formData.get("email") ?? "").trim();

  const fieldErrors: ProfileActionState["fieldErrors"] = {};

  if (name.length < 2) {
    fieldErrors.name = "Name must contain at least 2 characters.";
  }

  if (!email.includes("@")) {
    fieldErrors.email = "Email must be valid.";
  }

  if (Object.keys(fieldErrors).length > 0) {
    return {
      status: "invalid",
      message: "Please fix the highlighted fields.",
      fieldErrors,
    };
  }

  await updateProfile({ name, email });

  return {
    status: "success",
    message: "Profile updated.",
    fieldErrors: {},
  };
}

export function ProfileForm() {
  const [state, formAction, isPending] = useActionState(
    updateProfileAction,
    initialState
  );

  return (
    <form action={formAction}>
      <label>
        Name
        <input name="name" aria-invalid={Boolean(state.fieldErrors.name)} />
      </label>
      {state.fieldErrors.name && (
        <p role="alert">{state.fieldErrors.name}</p>
      )}

      <label>
        Email
        <input name="email" aria-invalid={Boolean(state.fieldErrors.email)} />
      </label>
      {state.fieldErrors.email && (
        <p role="alert">{state.fieldErrors.email}</p>
      )}

      <button disabled={isPending}>
        {isPending ? "Saving..." : "Save"}
      </button>

      {state.message && <p role="status">{state.message}</p>}
    </form>
  );
}

Action returns renderable state.
Component renders that state.

async function action(previousState: AnyHugeState, formData: FormData) {
  return {
    ...previousState,
    deeplyMutatedStuff: "...",
    cachedList: "...",
    modalState: "...",
    filters: "...",
  };
}

type ActionState =
  | { status: "idle"; fieldErrors: {}; formError: null }
  | { status: "invalid"; fieldErrors: FieldErrors; formError: string }
  | { status: "success"; fieldErrors: {}; formError: null; savedId: string };

pending
last result
validation error
form-level error
success payload

server-state cache
normalized client store
workflow engine
large form model
global notification bus
audit/event pipeline

import { useFormStatus } from "react-dom";

function SubmitButton() {
  const status = useFormStatus();

  return (
    <button type="submit" disabled={status.pending}>
      {status.pending ? "Saving..." : "Save"}
    </button>
  );
}

export function SettingsForm({ action }: { action: (formData: FormData) => void }) {
  return (
    <form action={action}>
      <input name="displayName" />
      <SubmitButton />
    </form>
  );
}

function BadForm() {
  const status = useFormStatus();

  return (
    <form action={someAction}>
      <button disabled={status.pending}>Save</button>
    </form>
  );
}

- banyak submit button ingin tahu pending state form
- design system punya <Button intent="submit" />
- field ingin disabled saat parent form submit
- UI ingin menampilkan data/method/action submission terakhir

field-level pending
form-level pending
section-level pending
page-level pending
navigation-level pending
global command pending

function SaveButton() {
  const { pending } = useFormStatus();

  return (
    <button type="submit" disabled={pending}>
      {pending ? "Saving invoice..." : "Save invoice"}
    </button>
  );
}

loading = true

type State = {
  error?: string;
  success?: boolean;
  data?: unknown;
};

success=true dan error terisi?
success=false dan data terisi?
tidak ada error tapi success undefined?

type SubmitCaseState =
  | {
      tag: "idle";
    }
  | {
      tag: "invalid";
      fieldErrors: Record<string, string>;
      formError: string;
    }
  | {
      tag: "rejected";
      reason: "permission_denied" | "stale_case" | "invalid_transition";
      message: string;
    }
  | {
      tag: "submitted";
      caseId: string;
      version: number;
      message: string;
    };

async function submitCase(
  previous: SubmitCaseState,
  formData: FormData
): Promise<SubmitCaseState> {
  const input = parseSubmitCaseForm(formData);

  if (!input.ok) {
    return {
      tag: "invalid",
      fieldErrors: input.fieldErrors,
      formError: "Please fix the form.",
    };
  }

  const result = await submitCaseCommand(input.value);

  if (result.type === "permission_denied") {
    return {
      tag: "rejected",
      reason: "permission_denied",
      message: "You are not allowed to submit this case.",
    };
  }

  if (result.type === "invalid_transition") {
    return {
      tag: "rejected",
      reason: "invalid_transition",
      message: "This case can no longer be submitted.",
    };
  }

  return {
    tag: "submitted",
    caseId: result.caseId,
    version: result.version,
    message: "Case submitted.",
  };
}

function SubmitCaseResult({ state }: { state: SubmitCaseState }) {
  switch (state.tag) {
    case "idle":
      return null;

    case "invalid":
      return <p role="alert">{state.formError}</p>;

    case "rejected":
      return <p role="alert">{state.message}</p>;

    case "submitted":
      return <p role="status">{state.message}</p>;
  }
}

await approveCase(formData);

type ApproveCaseInput = {
  caseId: string;
  comment: string;
  expectedVersion: number;
};

function parseApproveCaseForm(formData: FormData):
  | { ok: true; value: ApproveCaseInput }
  | { ok: false; fieldErrors: Record<string, string> } {
  const caseId = String(formData.get("caseId") ?? "");
  const comment = String(formData.get("comment") ?? "").trim();
  const expectedVersionRaw = String(formData.get("expectedVersion") ?? "");

  const fieldErrors: Record<string, string> = {};

  if (!caseId) {
    fieldErrors.caseId = "Missing case id.";
  }

  if (comment.length < 10) {
    fieldErrors.comment = "Comment must explain the approval decision.";
  }

  const expectedVersion = Number(expectedVersionRaw);

  if (!Number.isInteger(expectedVersion)) {
    fieldErrors.expectedVersion = "Invalid case version.";
  }

  if (Object.keys(fieldErrors).length > 0) {
    return { ok: false, fieldErrors };
  }

  return {
    ok: true,
    value: {
      caseId,
      comment,
      expectedVersion,
    },
  };
}

React FormData
→ parser
→ typed command input
→ domain/application command

React primitive:
- form action
- useActionState
- useFormStatus
- useOptimistic
- transition integration

Framework/server runtime:
- where server function executes
- how request is transported
- how security boundary is enforced
- how cookies/session/database are accessed
- how route/cache revalidation works

async function updateProfileAction(previous: State, formData: FormData): Promise<State> {
  const input = parseProfileForm(formData);

  if (!input.ok) {
    return {
      tag: "invalid",
      fieldErrors: input.fieldErrors,
    };
  }

  const response = await fetch("/api/profile", {
    method: "PUT",
    headers: {
      "Content-Type": "application/json",
      "Idempotency-Key": crypto.randomUUID(),
    },
    body: JSON.stringify(input.value),
  });

  if (!response.ok) {
    return {
      tag: "failed",
      message: "Could not save profile.",
    };
  }

  return {
    tag: "saved",
  };
}

async function saveDraftAction(formData: FormData) {
  await saveArticleDraft(parseArticle(formData));
}

async function publishAction(formData: FormData) {
  await publishArticle(parseArticle(formData));
}

function ArticleForm() {
  return (
    <form action={saveDraftAction}>
      <input name="title" />
      <textarea name="body" />

      <button type="submit">Save draft</button>
      <button type="submit" formAction={publishAction}>
        Publish
      </button>
    </form>
  );
}

SaveDraftArticle
PublishArticle
RequestReview
ArchiveArticle

permalink = canonical URL untuk form action result

- form berada di feed/list dinamis
- page bisa berubah karena pagination/filter
- action perlu tetap bekerja sebelum JS siap
- server-rendered result perlu disambungkan kembali ke form yang sama

function CommentForm({ addComment }: { addComment: (formData: FormData) => Promise<void> }) {
  return (
    <form action={addComment}>
      <textarea name="comment" />
      <button>Post</button>
    </form>
  );
}

Data mana yang sekarang stale?

function UpdateProfileForm() {
  const queryClient = useQueryClient();

  const [state, formAction, isPending] = useActionState(
    async (previous: State, formData: FormData): Promise<State> => {
      const input = parseProfileForm(formData);

      if (!input.ok) {
        return { tag: "invalid", fieldErrors: input.fieldErrors };
      }

      await updateProfile(input.value);

      await queryClient.invalidateQueries({
        queryKey: ["profile", "me"],
      });

      return { tag: "saved" };
    },
    { tag: "idle" }
  );

  return (
    <form action={formAction}>
      {/* fields */}
      <button disabled={isPending}>Save</button>
    </form>
  );
}

async function updateProfileCommand(input: ProfileInput) {
  await api.updateProfile(input);
}

CreateInvoice success → go to invoice detail
ApproveCase success → stay and show updated status
SubmitApplication success → go to confirmation page
SaveDraft success → stay in editor
DeleteRecord success → go back to list

type CreateInvoiceState =
  | { tag: "idle" }
  | { tag: "invalid"; fieldErrors: FieldErrors }
  | { tag: "created"; invoiceId: string; next: { type: "redirect"; to: string } };

function CreateInvoicePage() {
  const navigate = useNavigate();
  const [state, formAction, isPending] = useActionState(createInvoiceAction, {
    tag: "idle",
  });

  useEffect(() => {
    if (state.tag === "created") {
      navigate(state.next.to);
    }
  }, [state, navigate]);

  return (
    <form action={formAction}>
      {/* fields */}
      <button disabled={isPending}>Create</button>
    </form>
  );
}

double-click sangat cepat
refresh/resubmit
membuka dua tab
mengirim request manual
kehilangan koneksi lalu retry

function InvoiceCreateForm() {
  const idempotencyKey = useMemo(() => crypto.randomUUID(), []);

  async function createInvoiceAction(previous: State, formData: FormData): Promise<State> {
    const input = parseInvoiceForm(formData);

    if (!input.ok) {
      return { tag: "invalid", fieldErrors: input.fieldErrors };
    }

    const result = await createInvoice({
      ...input.value,
      idempotencyKey,
    });

    return {
      tag: "created",
      invoiceId: result.invoiceId,
    };
  }

  const [state, formAction, isPending] = useActionState(createInvoiceAction, {
    tag: "idle",
  });

  return (
    <form action={formAction}>
      <input type="hidden" name="idempotencyKey" value={idempotencyKey} />
      <button disabled={isPending}>Create invoice</button>
    </form>
  );
}

{canApprove && <button>Approve</button>}

type ApproveState =
  | { tag: "idle" }
  | { tag: "invalid"; fieldErrors: FieldErrors }
  | { tag: "rejected"; reason: "permission_denied" | "stale_version"; message: string }
  | { tag: "approved"; caseId: string; version: number };

expectedVersion
currentStatus
actorRole
requiredComment
attachmentCompleteness
deadlineWindow

- submit button disabled saat pending bila command tidak boleh double submit
- pending label spesifik: "Saving profile..." bukan hanya "Loading..."
- validation error terhubung ke field
- form-level error memakai role="alert" bila immediate attention
- success message memakai role="status" bila non-blocking
- aria-invalid pada field invalid
- aria-describedby mengarah ke pesan error/help
- focus management setelah submit gagal untuk form besar

<label htmlFor="email">Email</label>
<input
  id="email"
  name="email"
  aria-invalid={Boolean(state.fieldErrors.email)}
  aria-describedby={state.fieldErrors.email ? "email-error" : undefined}
/>
{state.fieldErrors.email && (
  <p id="email-error" role="alert">
    {state.fieldErrors.email}
  </p>
)}

type UseUpdateProfileFormOptions = {
  onSaved?: () => void;
};

function useUpdateProfileForm(options: UseUpdateProfileFormOptions = {}) {
  const queryClient = useQueryClient();

  return useActionState(
    async (previous: ProfileState, formData: FormData): Promise<ProfileState> => {
      const input = parseProfileForm(formData);

      if (!input.ok) {
        return {
          tag: "invalid",
          fieldErrors: input.fieldErrors,
        };
      }

      const result = await updateProfileCommand(input.value);

      await queryClient.invalidateQueries({
        queryKey: ["profile", result.profileId],
      });

      options.onSaved?.();

      return {
        tag: "saved",
        profileId: result.profileId,
      };
    },
    { tag: "idle" } satisfies ProfileState
  );
}

function ProfilePage() {
  const [state, action, isPending] = useUpdateProfileForm();

  return (
    <form action={action}>
      <ProfileFields errors={state.tag === "invalid" ? state.fieldErrors : {}} />
      <SubmitButton pending={isPending} />
    </form>
  );
}

type CommandState =
  | { tag: "idle" }
  | { tag: "invalid"; fieldErrors: FieldErrors }
  | { tag: "submitting" }
  | { tag: "rejected"; reason: string }
  | { tag: "succeeded"; resultId: string };

isPending = action sedang berjalan sekarang
state.tag = hasil committed terakhir

- form besar dengan banyak field
- field array
- schema validation kompleks
- controlled/uncontrolled hybrid optimization
- touched/dirty tracking
- dependent validation
- wizard
- integration dengan design system

form library:
- local field model
- touched/dirty
- client validation
- field array
- controlled/uncontrolled optimization

React action:
- submit lifecycle
- pending/result
- server validation result
- progressive enhancement when possible

it("rejects missing name", () => {
  const formData = new FormData();

  const result = parseProfileForm(formData);

  expect(result).toEqual({
    ok: false,
    fieldErrors: {
      name: "Name is required.",
    },
  });
});

it("returns invalid state for invalid input", async () => {
  const formData = new FormData();
  formData.set("email", "not-email");

  const result = await updateProfileAction({ tag: "idle" }, formData);

  expect(result.tag).toBe("invalid");
});

it("disables submit while pending", async () => {
  render(<ProfileForm />);

  await user.click(screen.getByRole("button", { name: /save/i }));

  expect(screen.getByRole("button", { name: /saving/i })).toBeDisabled();
});

submit invalid form
→ field errors appear
→ focus moves or error is announced
→ valid submit calls command
→ query cache invalidated
→ success message or navigation happens

[ ] Action result shape eksplisit
[ ] Expected validation/domain errors direturn, bukan throw
[ ] Unexpected errors masuk logging/error boundary
[ ] FormData diparse ke typed command input
[ ] Pending state scoped dengan benar
[ ] Submit button accessible dan tidak misleading
[ ] Field errors memakai aria-invalid/aria-describedby
[ ] Duplicate submit policy jelas
[ ] Idempotency ditangani di backend untuk command penting
[ ] Cache invalidation/update jelas
[ ] Navigation after success eksplisit
[ ] Auto reset behavior sesuai UX
[ ] Permission/precondition dicek server-side
[ ] Test parser, action, component, dan integration flow

React 19 Actions memberi primitive untuk command lifecycle.

input parsing
validation
permission
idempotency
pending scope
result shape
cache effect
navigation
accessibility
testing