@uniflowed/hooks 0.0.0-alpha.4 → 0.0.0-alpha.41

package/timing.js

@@ -11,18 +11,48 @@
 // # What belongs in this module
 //
 // A hook whose subject is *when* something runs: on a schedule, after a wait,
-// no more often than some rate. Every one of them owns a handle that has to be
-// cleared, and the cleanup is the reason the hook exists rather than a detail
-// of it.
+// no more often than some rate, on the next frame, once the reader has stopped
+// touching anything. Every one of them owns a handle that has to be cleared,
+// and the cleanup is the reason the hook exists rather than a detail of it.
+//
+// `useNow` and `useTimeAgo` belong here for the same reason, which is easy to
+// miss: what is difficult about "3 minutes ago" is not the words, it is
+// deciding how often the words have to be worked out again. A label a minute
+// old must be redrawn every second and one a week old must not be redrawn at
+// all, and getting that wrong is either a wrong label or a component that
+// re-renders sixty times a second forever.
 //
 // Not here: `useMount` and `useUnmount`, which are about the component's life
 // rather than a clock, and live in `lifecycle.js`; and rendering a time, which
-// is `@uniflowed/web`'s `Time` and is a formatting problem, not a scheduling
-// one.
+// is `@uniflowed/web`'s `Time`. The split between that component and
+// `useTimeAgo` is the split between markup and schedule — `Time` decides what
+// a `<time>` element contains and how it survives hydration, and works out its
+// relative text exactly once; `useTimeAgo` is for a label that has to stay
+// true while the reader looks at it. This package does not depend on
+// `@uniflowed/web` to get there, because a hook library that pulled in a
+// component library would be the wrong direction for the one arrow between
+// them.
+//
+// # Where the time comes from
+//
+// Not from `Date.now()`. Every read in this module goes through
+// `@uniflowed/core/clock`, which is a seam a test, a server or a runtime can
+// put its own clock behind — so "3 minutes ago" is a value a test can assert
+// rather than a value it has to wait three minutes for, and a server render is
+// reproducible rather than being stamped with whenever it happened to run.
+//
+// A throttle measured against an installed clock is a throttle that does not
+// elapse while that clock is stopped. That is not a defect to work around: a
+// fixed clock means time is not passing, and a rate limit that fired anyway
+// would be measuring something other than the time the caller said it was.
+// `manualClock` is the one to install when a test wants the window to close.
 
-import { useEffect, useRef, useState } from "@uniflowed/react";
+import { useEffect, useMemo, useRef, useState } from "@uniflowed/react";
+import { currentClock } from "@uniflowed/core/clock";
 
-import { useStableCallback } from "./lifecycle.js";
+import { browserWindow } from "./browser.js";
+import { useMounted, useStableCallback } from "./lifecycle.js";
+import { useRenderEnvelope } from "./render.js";
 
 /**
  * Call `body` every `millis`, or not at all when `millis` is null.
@@ -31,7 +61,7 @@ import { useStableCallback } from "./lifecycle.js";
  * interval of nothing" are the same thing, and one argument cannot disagree
  * with itself.
  */
-export function useInterval(body: () => mixed, millis: number | null): void {
+export hook useInterval(body: () => mixed, millis: number | null): void {
   const stable = useStableCallback(body);
   useEffect(() => {
     if (millis == null) {
@@ -43,7 +73,7 @@ export function useInterval(body: () => mixed, millis: number | null): void {
 }
 
 /** Call `body` once after `millis`, or not at all when `millis` is null. */
-export function useTimeout(body: () => mixed, millis: number | null): void {
+export hook useTimeout(body: () => mixed, millis: number | null): void {
   const stable = useStableCallback(body);
   useEffect(() => {
     if (millis == null) {
@@ -60,7 +90,7 @@ export function useTimeout(body: () => mixed, millis: number | null): void {
  * The classic use is a search box: the query updates on every keystroke and
  * the request should not.
  */
-export function useDebouncedValue<T>(value: T, millis: number): T {
+export hook useDebouncedValue<T>(value: T, millis: number): T {
   const [settled, setSettled] = useState(value);
 
   useEffect(() => {
@@ -78,15 +108,18 @@ export function useDebouncedValue<T>(value: T, millis: number): T {
  * the window are dropped, which is what a scroll or resize handler wants —
  * the trailing-edge version would make the first paint late.
  */
-export function useThrottledCallback<TArgs extends $ReadOnlyArray<mixed>>(
+export hook useThrottledCallback<TArgs extends $ReadOnlyArray<mixed>>(
   body: (...args: TArgs) => mixed,
   millis: number,
 ): (...args: TArgs) => void {
-  const stable = useStableCallback(body);
+  // Written out rather than inferred: Flow cannot instantiate one function's
+  // rest-parameter type variable from another's, so the type arguments are
+  // given here and at every other call in this file.
+  const stable = useStableCallback<TArgs, mixed>(body);
   const last = useRef(0);
 
-  return useStableCallback((...args: TArgs) => {
-    const now = Date.now();
+  return useStableCallback<TArgs, void>((...args: TArgs) => {
+    const now = currentClock().now();
     if (now - last.current >= millis) {
       last.current = now;
       stable(...args);
@@ -100,11 +133,11 @@ export function useThrottledCallback<TArgs extends $ReadOnlyArray<mixed>>(
  * Trailing edge, and it cancels itself at unmount — the version people write
  * calls `setState` on a component that is gone.
  */
-export function useDebouncedCallback<TArgs extends $ReadOnlyArray<mixed>>(
+export hook useDebouncedCallback<TArgs extends $ReadOnlyArray<mixed>>(
   body: (...args: TArgs) => mixed,
   millis: number,
 ): (...args: TArgs) => void {
-  const stable = useStableCallback(body);
+  const stable = useStableCallback<TArgs, mixed>(body);
   const timer = useRef<TimeoutID | null>(null);
 
   useEffect(
@@ -116,7 +149,7 @@ export function useDebouncedCallback<TArgs extends $ReadOnlyArray<mixed>>(
     [],
   );
 
-  return useStableCallback((...args: TArgs) => {
+  return useStableCallback<TArgs, void>((...args: TArgs) => {
     if (timer.current != null) {
       clearTimeout(timer.current);
     }
@@ -126,3 +159,285 @@ export function useDebouncedCallback<TArgs extends $ReadOnlyArray<mixed>>(
     }, millis);
   });
 }
+
+/**
+ * Run `body` before every frame the browser paints, while `active`.
+ *
+ * `delta` is the milliseconds since the previous frame and is zero on the
+ * first, which is what an animation integrates against: a frame that took 32ms
+ * because the tab was busy has to move twice as far as one that took 16ms, and
+ * a hand-written loop that assumes sixty a second runs at half speed on a
+ * hundred-and-twenty-hertz display.
+ *
+ * Nothing runs before hydration: there is no frame to paint during a prerender,
+ * and the effect that would ask for one does not run there.
+ */
+export hook useAnimationFrame(
+  body: (frame: {| readonly delta: number, readonly time: number |}) => mixed,
+  active: boolean = true,
+): void {
+  const stable = useStableCallback(body);
+
+  useEffect(() => {
+    const win = browserWindow();
+    if (!active || win == null || win.requestAnimationFrame == null) {
+      return;
+    }
+    let handle: AnimationFrameID | null = null;
+    let previous: number | null = null;
+
+    const step = (time: number) => {
+      const delta = previous == null ? 0 : time - previous;
+      previous = time;
+      // Asked for before the body runs, so a body that throws does not stop
+      // the loop silently — it stops it loudly, on the next frame, having
+      // already reported the throw to the browser.
+      handle = win.requestAnimationFrame?.(step) ?? null;
+      stable({ delta, time });
+    };
+
+    handle = win.requestAnimationFrame(step);
+    return () => {
+      if (handle != null) {
+        win.cancelAnimationFrame?.(handle);
+      }
+    };
+  }, [active, stable]);
+}
+
+/** What counts as the reader still being there. */
+const ACTIVITY: $ReadOnlyArray<string> = [
+  "pointermove",
+  "pointerdown",
+  "keydown",
+  "wheel",
+  "touchstart",
+  "scroll",
+  "visibilitychange",
+];
+
+/**
+ * Whether the reader has stopped doing anything for `millis`.
+ *
+ * `false` on a server and on the first client render, which is the answer that
+ * cannot be wrong: nobody is idle before the page exists, and starting at
+ * `true` would flash whatever the page shows an idle reader.
+ *
+ * The listeners are passive and on the window rather than on any element, so
+ * this costs nothing on a touch screen and sees activity anywhere on the page.
+ */
+export hook useIdle(
+  millis: number = 60_000,
+  options?: {| readonly events?: $ReadOnlyArray<string> |},
+): boolean {
+  const [idle, setIdle] = useState(false);
+  const events = options?.events ?? ACTIVITY;
+  // Compared by contents: an array written inline in the call is a new array
+  // every render, and depending on its identity would re-listen every render.
+  const key = events.join(",");
+
+  useEffect(() => {
+    const win = browserWindow();
+    if (win == null) {
+      return;
+    }
+    const names = key.split(",");
+    let timer: TimeoutID | null = null;
+
+    const wake = () => {
+      setIdle(false);
+      if (timer != null) {
+        clearTimeout(timer);
+      }
+      timer = setTimeout(() => setIdle(true), millis);
+    };
+
+    wake();
+    for (const name of names) {
+      win.addEventListener(name, wake, { passive: true });
+    }
+    return () => {
+      if (timer != null) {
+        clearTimeout(timer);
+      }
+      for (const name of names) {
+        win.removeEventListener(name, wake);
+      }
+    };
+  }, [millis, key]);
+
+  return idle;
+}
+
+/**
+ * The current time, re-read every `millis`.
+ *
+ * The clock is read in the initial state rather than in an effect, so a
+ * client-only page has the right time on its first paint instead of a frame of
+ * something else. That read is the one impure thing in this package, and it is
+ * bounded: it happens once, the value is never re-read during a render, and a
+ * render React throws away is replaced by another whose clock is just as valid.
+ *
+ * On a prerendered page the two renders are at two different instants, so the
+ * first one on each side has to be the *same* instant or React reports a
+ * mismatch. Under a `RenderProvider` that happens by itself — the anchor the
+ * server fixed travels in the markup, both sides start from it, and the real
+ * time arrives with the first effect. `serverValue` is the same choice made by
+ * hand, for a caller who has the instant from somewhere else and for a tree
+ * with no provider above it; it wins over the anchor when both are there,
+ * because an argument at the call site is a decision and a context is a
+ * default.
+ *
+ * A `Date` rather than a `Temporal.Instant`, and deliberately: this value's
+ * consumers subtract it from another one to decide when to run again, which is
+ * millisecond arithmetic on a number. The Temporal-shaped reading of the same
+ * anchor is `useRenderedAt` in `render.js`, and rendering an instant is
+ * `@uniflowed/web`'s `Time`.
+ */
+export hook useNow(millis: number | null = 1000, serverValue: Date | null = null): Date {
+  // The instant rather than the object: a caller writing `new Date(...)` in
+  // the call passes a different object every render, and a dependency on it
+  // would re-run the effect forever.
+  const anchored = useRenderEnvelope()?.at ?? null;
+  const since = serverValue == null ? anchored : serverValue.getTime();
+  const [now, setNow] = useState<Date>(
+    () => new Date(since == null ? currentClock().now() : since),
+  );
+
+  useEffect(() => {
+    if (since != null) {
+      // A prerender starts from the server's timestamp for hydration, then
+      // adopts the live clock once effects can run.
+      // uf-lint-disable-next-line react-compiler/set-state-in-effect
+      setNow(new Date(currentClock().now()));
+    }
+  }, [since]);
+
+  useInterval(() => setNow(new Date(currentClock().now())), millis);
+  return now;
+}
+
+/**
+ * `Intl.RelativeTimeFormat`, which Flow's own library definition does not have.
+ *
+ * The vendored `intl.js` declares `Collator`, `DateTimeFormat`, `Locale`,
+ * `NumberFormat`, `PluralRules` and `Segmenter` and stops there, so
+ * `Intl.RelativeTimeFormat` is a missing property and `Intl$RelativeTimeFormatUnit`
+ * is an unresolvable name. Declaring the shape here is how this file names a
+ * global its checker has not caught up with — narrow, exactly as wide as what
+ * is called, and optional so that a runtime without the constructor is a
+ * branch rather than a crash.
+ */
+declare class RelativeTimeFormat {
+  constructor(locale?: string, options?: { numeric?: "always" | "auto", ... }): void;
+  format(value: number, unit: RelativeUnit): string;
+}
+
+declare var Intl: {
+  RelativeTimeFormat?: Class<RelativeTimeFormat>,
+  ...
+};
+
+/** The units `ago` is willing to describe a gap in. */
+type RelativeUnit = "year" | "month" | "day" | "hour" | "minute" | "second";
+
+/** Milliseconds in each unit, largest first. */
+const UNITS: $ReadOnlyArray<[RelativeUnit, number]> = [
+  ["year", 31_536_000_000],
+  ["month", 2_592_000_000],
+  ["day", 86_400_000],
+  ["hour", 3_600_000],
+  ["minute", 60_000],
+  ["second", 1_000],
+];
+
+/** How often a label this far from now has to be worked out again. */
+function cadence(distance: number): number {
+  if (distance < 60_000) {
+    return 1_000;
+  }
+  if (distance < 3_600_000) {
+    return 30_000;
+  }
+  return 60_000;
+}
+
+/**
+ * "3 minutes ago", or "in 3 minutes".
+ *
+ * Falls back to the instant itself where the browser has no
+ * `Intl.RelativeTimeFormat`, because a wrong-language string invented here
+ * would be worse than the unambiguous one.
+ */
+function ago(at: Date, from: Date, locale: string | void): string {
+  const Formatter = Intl.RelativeTimeFormat;
+  if (Formatter == null) {
+    return at.toISOString();
+  }
+  const difference = at.getTime() - from.getTime();
+  const formatter = new Formatter(locale, { numeric: "auto" });
+  for (const [unit, span] of UNITS) {
+    if (Math.abs(difference) >= span) {
+      return formatter.format(Math.round(difference / span), unit);
+    }
+  }
+  // Under a second in either direction is "now", not "in 0 seconds".
+  return formatter.format(0, "second");
+}
+
+/**
+ * "3 minutes ago", kept true while the reader looks at it.
+ *
+ * Before hydration and on the first client render this is `serverValue`,
+ * defaulting to the instant's UTC ISO string — the same choice
+ * `@uniflowed/web`'s `Time` makes, and for the same reason: the relative form
+ * depends on a clock and a locale that the server does not have, so rendering
+ * it on both sides would be a hydration mismatch by construction. The text is
+ * in the markup for a crawler and for a reader with no JavaScript, and becomes
+ * relative once the page is alive.
+ *
+ * The update rate follows the distance rather than being fixed: a label from
+ * this minute is redrawn every second, one from this hour every thirty, and an
+ * older one every minute. That is why this is not "call `useNow` and format
+ * it" — a fixed one-second clock re-renders a week-old timestamp 604,800 times
+ * to no effect.
+ */
+export hook useTimeAgo(
+  value: Date | string | number,
+  options?: {|
+    readonly serverValue?: string,
+    /** Override the schedule. `null` works it out once and leaves it. */
+    readonly interval?: number | null,
+    readonly locale?: string,
+  |},
+): string {
+  const serverValue = options?.serverValue;
+  const override = options?.interval;
+  const locale = options?.locale;
+
+  const instant = value instanceof Date ? value.getTime() : new Date(value).getTime();
+  const at = useMemo(() => new Date(instant), [instant]);
+
+  const mounted = useMounted();
+  // The schedule itself is the state, not the gap it was chosen from. Holding
+  // the gap would mean a render every time the clock moved *and* a second one
+  // to record the new gap; holding the schedule means `setSchedule` is handed
+  // the same number on all but the few ticks that cross a threshold, and React
+  // bails out of those renders entirely.
+  const [schedule, setSchedule] = useState(1_000);
+  const tick = override === undefined ? schedule : override;
+  const now = useNow(mounted ? tick : null);
+
+  const wanted = cadence(Math.abs(now.getTime() - instant));
+  useEffect(() => {
+    // The schedule is derived from the ticking external clock. Storing it here
+    // lets the interval slow down without adding a second clock source.
+    // uf-lint-disable-next-line react-compiler/set-state-in-effect
+    setSchedule(wanted);
+  }, [wanted]);
+
+  if (!mounted) {
+    return serverValue ?? at.toISOString();
+  }
+  return ago(at, now, locale);
+}