Loading States

1// 1. Delay in, minimum out — the two rules that remove flicker2function useLoadingIndicator(active: boolean, delay = 200, min = 400) {3  const [show, setShow] = useState(false)4  const shownAt = useRef(0)56  useEffect(() => {7    if (active) {8      const t = setTimeout(() => {9        shownAt.current = Date.now()10        setShow(true)11      }, delay)12      return () => clearTimeout(t)13    }14    if (!show) return15    const held = Date.now() - shownAt.current16    const t = setTimeout(() => setShow(false), Math.max(0, min - held))17    return () => clearTimeout(t)18  }, [active, delay, min, show])1920  return show21}2223// 2. Stale while revalidating — keep the content, mark it stale24const { data, isFetching, dataUpdatedAt } = useQuery({25  queryKey: ['metrics'],26  queryFn: fetchMetrics,27  staleTime: 30_000,28  placeholderData: (prev) => prev,      // never blank on refetch29})3031<Stat value={data.requests} />32<p className="text-caption text-fg-muted">33  Updated {formatRelative(dataUpdatedAt)}{isFetching && ' · refreshing'}34</p>3536// 3. Optimistic — show it now, reconcile after37async function addTag(tag: string) {38  const optimistic = { id: 'tmp-' + tag, name: tag, pending: true }39  setTags((t) => [...t, optimistic])40  try {41    const saved = await api.addTag(tag)42    setTags((t) => t.map((x) => (x.id === optimistic.id ? saved : x)))43  } catch {44    setTags((t) => t.filter((x) => x.id !== optimistic.id))45    toast({ tone: 'danger', title: 'Could not add ' + tag })46  }47}4849// 4. Prefetch on intent — the wait disappears entirely50<Link onMouseEnter={() => prefetch(href)} onFocus={() => prefetch(href)} />

/* Stale content stays readable. 55% is the floor. */
.is-refetching { opacity: 0.55; transition: opacity 160ms var(--ease-standard); }

/* A 2px bar at the top of the region being refreshed. Least
   intrusive indicator there is — it changes nothing below it. */
.region { position: relative; }
.region__loading-bar {
  position: absolute;
  inset-inline: 0;
  inset-block-start: 0;
  block-size: 2px;
  overflow: hidden;
}

/* A pending button keeps its width — the label stays in the DOM */
.ds-btn[aria-busy='true'] .ds-btn__label { visibility: hidden; }
.ds-btn[aria-busy='true'] .ds-btn__spinner {
  position: absolute;
  inset: 0;
  display: grid;
  place-items: center;
}

/* Do not block the page. If you must overlay, keep it scoped
   to the region and keep the scrim light. */
.region--blocking::after {
  content: '';
  position: absolute;
  inset: 0;
  background: color-mix(in oklab, var(--ds-canvas) 60%, transparent);
}

@media (prefers-reduced-motion: reduce) {
  .ds-spinner { animation-duration: 2s; }
}