sailfork / t3code-github / packages/ client-runtime/ src/ delayedStatus.ts

const STATUS_SHOW_DELAY_MS = 400;
const STATUS_MIN_VISIBLE_MS = 400;

/**
 * A status shows only after it has stayed set for a moment, then stays shown
 * for a minimum time so a quick flicker never flashes on screen.
 * `deadlinePassed` tells whether `delayedStatusDeadline(state)` has been reached.
 */
export type DelayedStatusState<A> =
  | { readonly phase: "idle"; readonly key: string }
  | { readonly phase: "pending"; readonly key: string; readonly showAt: number }
  | {
      readonly phase: "shown";
      readonly key: string;
      readonly value: A;
      readonly holdUntil: number;
    };

export interface DelayedStatusInput<A> {
  readonly key: string;
  /** Compared by identity, so use strings or other stable values. */
  readonly value: A | null;
  readonly deadlinePassed: boolean;
  readonly showDelayMs?: number | undefined;
}

/**
 * Returns `state` itself when nothing changes, so it can run on every render.
 * `now` is read only to stamp a new deadline; it is a function so a memoizing
 * caller (the React Compiler) cannot cache a stale clock reading.
 */
export function stepDelayedStatus<A>(
  state: DelayedStatusState<A> | null,
  { key, value, deadlinePassed, showDelayMs = STATUS_SHOW_DELAY_MS }: DelayedStatusInput<A>,
  now: () => number,
): DelayedStatusState<A> {
  const idle = (): DelayedStatusState<A> => ({ phase: "idle", key });
  const pending = (): DelayedStatusState<A> => ({
    phase: "pending",
    key,
    showAt: now() + showDelayMs,
  });
  const shown = (shownValue: A): DelayedStatusState<A> => ({
    phase: "shown",
    key,
    value: shownValue,
    holdUntil: now() + STATUS_MIN_VISIBLE_MS,
  });

  if (state === null || state.key !== key) return value === null ? idle() : pending();
  switch (state.phase) {
    case "idle":
      return value === null ? state : pending();
    case "pending":
      if (value === null) return idle();
      return deadlinePassed ? shown(value) : state;
    case "shown":
      if (value === null) return deadlinePassed ? idle() : state;
      return value === state.value ? state : shown(value);
  }
}

export function delayedStatusDeadline<A>(state: DelayedStatusState<A>): number | null {
  switch (state.phase) {
    case "idle":
      return null;
    case "pending":
      return state.showAt;
    case "shown":
      return state.holdUntil;
  }
}

export function shownDelayedStatus<A>(state: DelayedStatusState<A>, key: string): A | null {
  return state.phase === "shown" && state.key === key ? state.value : null;
}