Wait UX

import { useSpinDelay, Spinner } from "@/components/ui";

function Orders({ query }: { query: Query }) {
  const { data, isFetching } = useOrders(query);
  // < 300ms: never shown · once shown: kept for ≥ 500ms
  const showSpinner = useSpinDelay(isFetching, { delay: 300, minDuration: 500 });

  return (
    <section aria-busy={isFetching}>
      {showSpinner && <Spinner size="tiny" label="Updating…" />}
      <OrderTable rows={data} />
    </section>
  );
}

import { useOptimisticList } from "@/components/ui";

const { items, mutate, pending } = useOptimisticList<Photo>(initialPhotos);

// 1. update is applied to the UI at once; write it by id, not by position
// 2. commit runs in the background; on error only this change is rolled back and a toast with a retry button appears
const ok = await mutate(
  (list) => list.map((p) => (p.id === id ? { ...p, starred: !p.starred } : p)),
  () => api.photos.star(id),
  { errorTitle: "Couldn't star the photo" },
);

useEffect(() => {
  const controller = new AbortController();
  // Cancel when the user leaves the screen or changes the filter, and stop on its own after 10 seconds.
  const signal = AbortSignal.any([controller.signal, AbortSignal.timeout(10_000)]);

  fetch(`/api/orders?q=${query}`, { signal })
    .then((res) => res.json())
    .then(setOrders)
    .catch((error) => {
      if (error.name === "AbortError") return;            // cancelled on purpose: stay silent
      if (error.name === "TimeoutError") setStatus("timeout"); // say that it took too long
      else setStatus("error");
    });

  return () => controller.abort();
}, [query]);

// Automatic retry for transient errors (network, 5xx, 429), with backoff and a limit.
async function withRetry<T>(task: () => Promise<T>, { retries = 3, base = 500 } = {}) {
  for (let attempt = 0; ; attempt++) {
    try {
      return await task();
    } catch (error) {
      if (attempt >= retries || !isTransient(error)) throw error;
      const wait = base * 2 ** attempt * (0.5 + Math.random()); // 500 → 1000 → 2000ms, with jitter
      await new Promise((r) => setTimeout(r, wait));
    }
  }
}

// Automatic retries used up → hand control to the user
<AsyncContent status={status} onRetry={reload} skeleton={<SkeletonList rows={5} />}>
  {() => <MemberList members={data!} />}
</AsyncContent>

{/* 1. Loading region: aria-busy so assistive technology waits for the update before reading */}
<section aria-busy={isLoading}>…</section>

{/* 2. Announce in words when the wait is long enough to show a loader (LoadingOverlay and AsyncContent do this) */}
const { announce } = useAnnounce();
announce("Loading orders…");
announce(`Loaded ${count} orders`, { batchId: "orders" });

{/* 3. A busy button keeps focus: aria-busy + aria-disabled, not disabled */}
<Button appearance="primary" loading={saving} loadingText="Saving…">Save</Button>

{/* 4. An error after an action the user is waiting on: role="alert" */}
<ErrorState variant="alert" onRetry={retry} />