@uniflowed/hooks 0.0.0-alpha.2 → 0.0.0-alpha.20

package/timing.js

@@ -0,0 +1,437 @@
+// @flow
+//
+// `@uniflowed/hooks/timing`: timers that stop when the component does.
+//
+// Every one of these exists because the hand-written version leaks: a
+// `setInterval` in a `useEffect` whose dependency array includes the callback
+// is torn down and restarted on every render, and one without the callback in
+// the array calls a stale closure forever. `useStableCallback` removes the
+// choice — the timer is set once and always calls the current body.
+//
+// # 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, 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`. 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, useMemo, useRef, useState } from "@uniflowed/react";
+import { currentClock } from "@uniflowed/core/clock";
+
+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.
+ *
+ * Null rather than a separate `enabled` flag because "no interval" and "an
+ * interval of nothing" are the same thing, and one argument cannot disagree
+ * with itself.
+ */
+export hook useInterval(body: () => mixed, millis: number | null): void {
+  const stable = useStableCallback(body);
+  useEffect(() => {
+    if (millis == null) {
+      return;
+    }
+    const id = setInterval(stable, millis);
+    return () => clearInterval(id);
+  }, [stable, millis]);
+}
+
+/** Call `body` once after `millis`, or not at all when `millis` is null. */
+export hook useTimeout(body: () => mixed, millis: number | null): void {
+  const stable = useStableCallback(body);
+  useEffect(() => {
+    if (millis == null) {
+      return;
+    }
+    const id = setTimeout(stable, millis);
+    return () => clearTimeout(id);
+  }, [stable, millis]);
+}
+
+/**
+ * `value`, but only after it has stopped changing for `millis`.
+ *
+ * The classic use is a search box: the query updates on every keystroke and
+ * the request should not.
+ */
+export hook useDebouncedValue<T>(value: T, millis: number): T {
+  const [settled, setSettled] = useState(value);
+
+  useEffect(() => {
+    const id = setTimeout(() => setSettled(value), millis);
+    return () => clearTimeout(id);
+  }, [value, millis]);
+
+  return settled;
+}
+
+/**
+ * A callback that runs at most once per `millis`.
+ *
+ * Leading edge: the first call goes through immediately and later ones inside
+ * the window are dropped, which is what a scroll or resize handler wants —
+ * the trailing-edge version would make the first paint late.
+ */
+export hook useThrottledCallback<TArgs extends $ReadOnlyArray<mixed>>(
+  body: (...args: TArgs) => mixed,
+  millis: number,
+): (...args: TArgs) => void {
+  // 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<TArgs, void>((...args: TArgs) => {
+    const now = currentClock().now();
+    if (now - last.current >= millis) {
+      last.current = now;
+      stable(...args);
+    }
+  });
+}
+
+/**
+ * A callback that runs `millis` after the last time it was asked to.
+ *
+ * Trailing edge, and it cancels itself at unmount — the version people write
+ * calls `setState` on a component that is gone.
+ */
+export hook useDebouncedCallback<TArgs extends $ReadOnlyArray<mixed>>(
+  body: (...args: TArgs) => mixed,
+  millis: number,
+): (...args: TArgs) => void {
+  const stable = useStableCallback<TArgs, mixed>(body);
+  const timer = useRef<TimeoutID | null>(null);
+
+  useEffect(
+    () => () => {
+      if (timer.current != null) {
+        clearTimeout(timer.current);
+      }
+    },
+    [],
+  );
+
+  return useStableCallback<TArgs, void>((...args: TArgs) => {
+    if (timer.current != null) {
+      clearTimeout(timer.current);
+    }
+    timer.current = setTimeout(() => {
+      timer.current = null;
+      stable(...args);
+    }, 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) {
+      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(() => {
+    setSchedule(wanted);
+  }, [wanted]);
+
+  if (!mounted) {
+    return serverValue ?? at.toISOString();
+  }
+  return ago(at, now, locale);
+}

package/internal/async.js

@@ -1,77 +0,0 @@
-// @flow
-//
-// Running a promise from a component.
-//
-// Two bugs a hand-written version has, and only one of them is a warning:
-// setting state after the component has gone, and a slow first request
-// overwriting a fast second one. The second is the dangerous one — it puts a
-// wrong answer on screen and nothing says so.
-//
-// Both are fixed by the effect's own cleanup rather than by a ref: the effect
-// that started a request is the thing that knows it has been superseded,
-// because React runs its cleanup before running it again. That is the shape
-// React's own documentation uses, and it means there is no "latest" anything
-// to keep in a ref and no generation counter to keep in step.
-
-import { useCallback, useEffect, useState } from "@uniflowed/react";
-
-/** What an in-flight, settled or failed call looks like. */
-export type Async<T> = {|
-  readonly value: T | null,
-  readonly error: Error | null,
-  readonly pending: boolean,
-  /** Run it again, keeping whatever is on screen until the new value lands. */
-  readonly reload: () => void,
-|};
-
-/**
- * Call `body` when `deps` change, and report what happened.
- *
- * The previous value stays on screen while a reload is in flight, because
- * blanking the page to show a spinner every time a filter changes is worse
- * than showing slightly stale data for a moment. `pending` says which it is.
- */
-export function useAsync<T>(body: () => Promise<T>, deps: $ReadOnlyArray<mixed>): Async<T> {
-  const [state, setState] = useState<{|
-    value: T | null,
-    error: Error | null,
-    pending: boolean,
-  |}>({ value: null, error: null, pending: true });
-
-  // Changing this is what re-runs the effect, so `reload` is a state change
-  // rather than a function the effect has to be told about.
-  const [attempt, setAttempt] = useState(0);
-  const reload = useCallback(() => setAttempt((current) => current + 1), []);
-
-  useEffect(() => {
-    // Set when this effect is superseded — by a dependency change, a reload,
-    // or an unmount. React runs the cleanup before the next run, so the
-    // request that is no longer wanted knows not to write.
-    let ignore = false;
-    setState((current) => ({ ...current, pending: true }));
-
-    body().then(
-      (value) => {
-        if (!ignore) {
-          setState({ value, error: null, pending: false });
-        }
-      },
-      (thrown) => {
-        if (!ignore) {
-          setState({
-            value: null,
-            error: thrown instanceof Error ? thrown : new Error(String(thrown)),
-            pending: false,
-          });
-        }
-      },
-    );
-
-    return () => {
-      ignore = true;
-    };
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [...deps, attempt]);
-
-  return { ...state, reload };
-}

package/internal/browser.js

@@ -1,145 +0,0 @@
-// @flow
-//
-// Reading the browser, safely on a server.
-//
-// uf prerenders every static route, so each of these runs once where there is
-// no `window`. `useSyncExternalStore` is what makes that correct rather than
-// guarded: it takes a server snapshot as a separate argument, so the value
-// used during prerender is stated rather than being whatever a `typeof window`
-// check happened to fall through to. It also means React reads the value at
-// the moment it commits, which is what stops a media query changing between
-// render and paint from tearing.
-
-import { useCallback, useSyncExternalStore } from "@uniflowed/react";
-
-/** Whether there is a document to read at all. */
-function inBrowser(): boolean {
-  return typeof globalThis.document !== "undefined";
-}
-
-/**
- * The window these hooks listen to.
- *
- * In a browser `globalThis` *is* the window, so `globalThis.addEventListener`
- * looks correct. It is not correct anywhere a document has been installed onto
- * another host's global — which is every uf test process, where `globalThis` is
- * Node's and has no `addEventListener` at all. Ask the window for its own
- * methods and both cases work.
- */
-function windowOf(): any {
-  return globalThis.window ?? globalThis;
-}
-
-/**
- * Whether a media query matches.
- *
- * `serverValue` is what a prerender should assume, and it has no honest
- * default — a page that hides a sidebar under 48rem wants `false` on the
- * server, and one that renders a mobile menu wants `true`. So the caller says.
- */
-export function useMediaQuery(query: string, serverValue: boolean = false): boolean {
-  const subscribe = useCallback(
-    (notify: () => void) => {
-      if (!inBrowser() || typeof windowOf().matchMedia !== "function") {
-        return () => {};
-      }
-      const list = windowOf().matchMedia(query);
-      list.addEventListener("change", notify);
-      return () => list.removeEventListener("change", notify);
-    },
-    [query],
-  );
-
-  return useSyncExternalStore(
-    subscribe,
-    () =>
-      inBrowser() && typeof windowOf().matchMedia === "function"
-        ? windowOf().matchMedia(query).matches
-        : serverValue,
-    () => serverValue,
-  );
-}
-
-/** The reader's colour-scheme preference. */
-export function usePreferredColorScheme(serverValue: "light" | "dark" = "light"): "light" | "dark" {
-  return useMediaQuery("(prefers-color-scheme: dark)", serverValue === "dark") ? "dark" : "light";
-}
-
-/** Whether the reader has asked for less motion. */
-export function usePrefersReducedMotion(serverValue: boolean = false): boolean {
-  return useMediaQuery("(prefers-reduced-motion: reduce)", serverValue);
-}
-
-/** Whether the browser thinks it is online. */
-export function useOnline(serverValue: boolean = true): boolean {
-  const subscribe = useCallback((notify: () => void) => {
-    if (!inBrowser()) {
-      return () => {};
-    }
-    const win = windowOf();
-    win.addEventListener("online", notify);
-    win.addEventListener("offline", notify);
-    return () => {
-      win.removeEventListener("online", notify);
-      win.removeEventListener("offline", notify);
-    };
-  }, []);
-
-  return useSyncExternalStore(
-    subscribe,
-    () => (inBrowser() ? (windowOf().navigator?.onLine ?? true) : serverValue),
-    () => serverValue,
-  );
-}
-
-/** Whether the document is the one the reader is looking at. */
-export function useDocumentVisible(serverValue: boolean = true): boolean {
-  const subscribe = useCallback((notify: () => void) => {
-    if (!inBrowser()) {
-      return () => {};
-    }
-    globalThis.document.addEventListener("visibilitychange", notify);
-    return () => globalThis.document.removeEventListener("visibilitychange", notify);
-  }, []);
-
-  return useSyncExternalStore(
-    subscribe,
-    () => (inBrowser() ? globalThis.document.visibilityState !== "hidden" : serverValue),
-    () => serverValue,
-  );
-}
-
-/** The size of the viewport. */
-export function useWindowSize(serverValue?: {|
-  readonly width: number,
-  readonly height: number,
-|}): {|
-  readonly width: number,
-  readonly height: number,
-|} {
-  const fallback = serverValue ?? { width: 0, height: 0 };
-
-  const subscribe = useCallback((notify: () => void) => {
-    if (!inBrowser()) {
-      return () => {};
-    }
-    const win = windowOf();
-    win.addEventListener("resize", notify);
-    return () => win.removeEventListener("resize", notify);
-  }, []);
-
-  // A string snapshot, because `useSyncExternalStore` compares snapshots by
-  // identity: returning a fresh object every time would re-render on every
-  // check, which is an infinite loop React reports rather than tolerates.
-  const packed = useSyncExternalStore(
-    subscribe,
-    () =>
-      inBrowser()
-        ? `${windowOf().innerWidth}x${windowOf().innerHeight}`
-        : `${fallback.width}x${fallback.height}`,
-    () => `${fallback.width}x${fallback.height}`,
-  );
-
-  const [width, height] = packed.split("x");
-  return { width: Number(width), height: Number(height) };
-}