Build a favorite toggle that updates immediately and recovers when the API rejects it.

Build an accessible Favorite button for one drill. Activating it must update the icon and aria-pressed immediately, send the desired final boolean to the API, and allow only one mutation at a time. A validation rejection must restore the captured previous value and announce a recoverable error. If the request outcome is uncertain, reconcile with the server before presenting the final state as confirmed.

The drill starts not favorited. One activation immediately changes the command to Remove favorite and begins PUT /drills/42/favorite with { favorite: true }. A second activation during that request does nothing. On success, the server-returned value becomes canonical. On a rejected mutation, the UI returns to Add favorite, announces Favorite was not saved, and becomes actionable again.

• Send the desired value through an idempotent-style set operation; do not depend on a blind server-side toggle.
• Use a synchronous guard as well as disabled UI because two events can occur before React commits pending.
• Capture the rollback value before the optimistic update.
• Accept the returned server value as canonical because authorization or business rules may normalize it.
• Distinguish a known rejection from an uncertain network outcome; re-read server truth when the write may have committed.
• Keep the button name, aria-pressed, pending state, and error announcement understandable to assistive technology.

1. Read the desired next value from the currently displayed state and capture the confirmed previous value.
2. Acquire a synchronous in-flight guard before scheduling React state updates.
3. Optimistically render the desired value, clear the old error, and expose pending state.
4. Send the explicit target value to the server rather than an ambiguous toggle command.
5. On success, commit the value returned by the server.
6. On a known rejection, restore the captured value. On a timeout or network failure, restore temporarily and attempt a read to reconcile an uncertain write.
7. Release the guard in finally and verify that duplicate activation, normalization, rollback, and reconciliation are all observable.

import { useRef, useState } from "react";

type FavoriteApi = {
  setFavorite: (drillId: string, favorite: boolean) => Promise<{ favorite: boolean }>;
  getFavorite: (drillId: string) => Promise<{ favorite: boolean }>;
};

type ApiError = Error & { status?: number };

export function FavoriteButton({
  drillId,
  initialFavorite,
  api,
}: {
  drillId: string;
  initialFavorite: boolean;
  api: FavoriteApi;
}) {
  const [favorite, setFavorite] = useState(initialFavorite);
  const [pending, setPending] = useState(false);
  const [message, setMessage] = useState<string | null>(null);
  const mutationInFlight = useRef(false);

  async function changeFavorite(desired: boolean) {
    if (mutationInFlight.current) return;

    mutationInFlight.current = true;
    const previous = favorite;
    setFavorite(desired);
    setMessage(null);
    setPending(true);

    try {
      const saved = await api.setFavorite(drillId, desired);
      setFavorite(saved.favorite);
    } catch (caught) {
      setFavorite(previous);
      const error = caught as ApiError;
      const knownRejection = error.status !== undefined && error.status < 500;

      if (knownRejection) {
        setMessage("Favorite was not saved. Try again.");
      } else {
        setMessage("Connection was lost. Checking the saved value...");
        try {
          const current = await api.getFavorite(drillId);
          setFavorite(current.favorite);
          setMessage("Favorite status was refreshed.");
        } catch {
          setMessage("Favorite status is uncertain. Refresh and try again.");
        }
      }
    } finally {
      mutationInFlight.current = false;
      setPending(false);
    }
  }

  return (
    <div>
      <button
        type="button"
        aria-pressed={favorite}
        disabled={pending}
        onClick={() => void changeFavorite(!favorite)}
      >
        {pending ? "Saving favorite..." : favorite ? "Remove favorite" : "Add favorite"}
      </button>
      <p role="status" aria-live="polite">{message}</p>
    </div>
  );
}

This deliberately serializes writes. Supporting rapid toggles is a different contract: queue or coalesce desired state, attach mutation versions, and define how late responses are rejected or reconciled.

The local mutation path is constant time and space. The important cost is semantic: optimistic UI improves perceived latency, but rollback and uncertain outcomes add state transitions that must be designed and tested. It fits fast, reversible, low-conflict actions such as favorites. Payments, destructive operations, scarce inventory, and permission changes usually need server confirmation or a much stronger conflict protocol. Serializing one write is simple and predictable; allowing rapid toggles requires versioning or coalescing rather than merely removing disabled.

• Two activation events occur before React renders the disabled button.
• The server succeeds but returns a normalized value different from the requested value.
• A 401 or validation response is a known rejection and should roll back without pretending to retry.
• A timeout occurs after the server may already have committed the write.
• Reconciliation also fails, leaving the UI explicitly uncertain rather than falsely confirmed.
• The component receives a new canonical favorite value while a mutation is pending.
• The user navigates away during the request.
• The API exposes only a non-idempotent toggle endpoint, making retries dangerous.

• Activate once and assert aria-pressed changes before the controlled API promise resolves.
• Dispatch two activations in the same tick and verify only one write is sent.
• Resolve with a different server value and verify that value becomes canonical.
• Reject with a 400 response and verify rollback, error announcement, and re-enabled command.
• Reject with an uncertain network error, then resolve getFavorite; verify reconciliation controls the final UI.
• Fail both mutation and reconciliation and assert the UI says the state is uncertain.
• Verify the request body contains the explicit desired boolean rather than an unversioned toggle command.

• Two writes are sent: relying only on rendered pending leaves a same-tick window; acquire a ref guard synchronously.
• Rollback lands on the wrong value: the previous state was read after the optimistic update or from a stale closure.
• A late response flips the UI unexpectedly: overlapping writes were allowed without request versions.
• Retry toggles the server twice: the API command describes an operation, not the desired final state.
• The UI claims rollback after a timeout: the server outcome was uncertain and no reconciliation read occurred.
• Screen readers cannot tell what happened: only the icon changed; aria-pressed, button text, and status feedback were omitted.