Freshness

"use client";

import { useEffect, useMemo, useRef, useState, type ComponentProps } from "react";
import "./freshness.css";

export type FreshnessProps = Omit<ComponentProps<"time">, "dateTime" | "children"> & {
  /** When the data was fetched: a Date, an ISO string or epoch milliseconds. */
  at: Date | string | number;
  /** Seconds after which the data counts as stale. */
  staleAfter?: number;
  /** Seconds after which the data counts as out of date. Leave unset for no expired state. */
  expiredAfter?: number;
  /** Word before the age, such as "Synced" or "Checked". */
  prefix?: string;
  /** Called once when the data turns stale (or expired) while shown, and on mount if it already is. */
  onStale?: () => void;
};

type State = "fresh" | "stale" | "expired";

const DAY = 86_400;

function toMs(at: Date | string | number) {
  if (at instanceof Date) return at.getTime();
  if (typeof at === "number") return at;
  return Date.parse(at);
}

const two = (n: number) => String(n).padStart(2, "0");

/** The same string on the server and in the first client render, so hydration matches. */
function utcLabel(ms: number) {
  const d = new Date(ms);
  return `${d.getUTCFullYear()}-${two(d.getUTCMonth() + 1)}-${two(d.getUTCDate())} ${two(d.getUTCHours())}:${two(d.getUTCMinutes())} UTC`;
}

/** Relative wording for an age in seconds, and the age at which that wording next changes. */
function relative(age: number, format: Intl.RelativeTimeFormat) {
  if (age < 10) return { text: "just now", next: 10 };
  if (age < 60) {
    const s = Math.floor(age / 10) * 10;
    return { text: format.format(-s, "second"), next: s + 10 };
  }
  if (age < 3600) {
    const m = Math.floor(age / 60);
    return { text: format.format(-m, "minute"), next: (m + 1) * 60 };
  }
  if (age < DAY) {
    const h = Math.floor(age / 3600);
    return { text: format.format(-h, "hour"), next: (h + 1) * 3600 };
  }
  const d = Math.floor(age / DAY);
  return { text: format.format(-d, "day"), next: (d + 1) * DAY };
}

function stateAt(age: number, staleAfter: number, expiredAfter: number | undefined): State {
  if (expiredAfter != null && age >= expiredAfter) return "expired";
  return age >= staleAfter ? "stale" : "fresh";
}

export function Freshness({
  at,
  staleAfter = 300,
  expiredAfter,
  prefix = "Updated",
  onStale,
  className,
  title,
  ...rest
}: FreshnessProps) {
  const ms = toMs(at);
  const valid = Number.isFinite(ms);
  // null until mounted: the server and the first client frame show the absolute UTC time.
  const [now, setNow] = useState<number | null>(null);
  const [announcement, setAnnouncement] = useState("");
  const format = useMemo(() => new Intl.RelativeTimeFormat(undefined, { numeric: "always", style: "short" }), []);

  const onStaleRef = useRef(onStale);
  useEffect(() => {
    onStaleRef.current = onStale;
  });

  // Wake exactly when the wording or the state would change; never tick while the tab is hidden.
  useEffect(() => {
    if (!valid) return;
    let timer: number | undefined;
    const tick = () => {
      window.clearTimeout(timer);
      const t = Date.now();
      setNow(t);
      if (document.hidden) return;
      const age = (t - ms) / 1000;
      const ahead = [relative(age, format).next, staleAfter, expiredAfter].filter(
        (b): b is number => b != null && b > age,
      );
      const delay = (Math.min(...ahead) - age) * 1000;
      // Long waits are capped at a day; waking early only recomputes the same text.
      timer = window.setTimeout(tick, Math.min(Math.max(delay, 0) + 25, DAY * 1000));
    };
    tick();
    document.addEventListener("visibilitychange", tick);
    return () => {
      window.clearTimeout(timer);
      document.removeEventListener("visibilitychange", tick);
    };
  }, [ms, valid, staleAfter, expiredAfter, format]);

  const age = now == null || !valid ? null : (now - ms) / 1000;
  const state = age == null ? undefined : stateAt(age, staleAfter, expiredAfter);

  // Announce only a live change into stale or expired, once, then clear the region.
  const seen = useRef<{ ms: number; state: State | undefined }>({ ms, state: undefined });
  useEffect(() => {
    if (!state) return;
    const last = seen.current;
    const sameData = last.ms === ms;
    seen.current = { ms, state };
    if (sameData && last.state === state) return;
    if (state === "fresh") {
      setAnnouncement("");
      return;
    }
    // Stale to expired is not a second onStale.
    if (!sameData || last.state === undefined || last.state === "fresh") onStaleRef.current?.();
    if (sameData && last.state !== undefined) {
      setAnnouncement(state === "stale" ? "Data may be out of date" : "Data is out of date");
    } else {
      setAnnouncement("");
    }
  }, [ms, state]);

  useEffect(() => {
    if (!announcement) return;
    const timer = window.setTimeout(() => setAnnouncement(""), 5000);
    return () => window.clearTimeout(timer);
  }, [announcement]);

  let text: string;
  if (!valid) text = `${prefix} at an unknown time`;
  else if (age == null) text = `${prefix} ${utcLabel(ms)}`;
  else {
    text = `${prefix} ${relative(age, format).text}`;
    if (state === "stale") text += ", may be out of date";
    if (state === "expired") text += ", out of date";
  }

  return (
    <time
      {...rest}
      className={["eq-freshness", className].filter(Boolean).join(" ")}
      dateTime={valid ? new Date(ms).toISOString() : undefined}
      data-state={state}
      title={title ?? (now != null && valid ? new Date(ms).toLocaleString() : undefined)}
    >
      <span className="eq-freshness-dot" aria-hidden="true" />
      <span className="eq-freshness-text">{text}</span>
      <span className="eq-freshness-status" role="status">
        {announcement}
      </span>
    </time>
  );
}