@uniflowed/hooks 0.0.0-alpha.2

package/index.js

@@ -0,0 +1,60 @@
+// @flow
+//
+// `@uniflowed/hooks`: the hooks a React application writes anyway.
+//
+// Not a large collection. Every hook here is one that people write by hand in
+// every project and get subtly wrong in the same way each time — a timer that
+// calls a stale closure, a subscription re-established on every keystroke, a
+// slow request overwriting a fast one, persisted state that differs between the
+// server render and the first paint.
+//
+// # Prerendering is the constraint that shapes the surface
+//
+// uf prerenders every static route, so each of these runs once where there is
+// no `window`. The browser hooks are built on `useSyncExternalStore`, which
+// takes the server's value as a separate argument — so what a prerender sees is
+// *stated* rather than being whatever a `typeof window` check fell through to,
+// and React reads the value when it commits rather than when it renders, which
+// is what stops a media query that changes mid-render from tearing.
+//
+// Where there is no honest default, the caller supplies one: a page that hides
+// its sidebar under 48rem wants `false` on the server and one that renders a
+// mobile menu wants `true`, and a library cannot know which.
+
+export type { Async } from "./internal/async.js";
+
+export { useAsync } from "./internal/async.js";
+export {
+  useIsomorphicLayoutEffect,
+  useMount,
+  useMounted,
+  usePrevious,
+  useRerender,
+  useStableCallback,
+  useUnmount,
+} from "./internal/lifecycle.js";
+export {
+  useDebouncedCallback,
+  useDebouncedValue,
+  useInterval,
+  useThrottledCallback,
+  useTimeout,
+} from "./internal/timing.js";
+export {
+  useDocumentVisible,
+  useMediaQuery,
+  useOnline,
+  usePrefersReducedMotion,
+  usePreferredColorScheme,
+  useWindowSize,
+} from "./internal/browser.js";
+export {
+  useClickOutside,
+  useElementRef,
+  useElementSize,
+  useEventListener,
+  useFocusWithin,
+  useHover,
+  useIntersecting,
+} from "./internal/element.js";
+export { useCounter, useStorage, useToggle } from "./internal/state.js";

package/internal/async.js

@@ -0,0 +1,77 @@
+// @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

@@ -0,0 +1,145 @@
+// @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) };
+}

package/internal/element.js

@@ -0,0 +1,186 @@
+// @flow
+//
+// Watching a node.
+//
+// Each of these takes a ref rather than returning one, so a component can put
+// several on the same element and can hand the ref to something else as well.
+// The listener is attached in a layout effect, so it is in place before the
+// browser paints — a click that lands in the same frame as the mount is a real
+// case on a touch screen.
+
+import { useEffect, useRef, useState } from "@uniflowed/react";
+
+import { useIsomorphicLayoutEffect, useStableCallback } from "./lifecycle.js";
+
+type Ref<T> = { current: T | null };
+
+/**
+ * The window these hooks read constructors from.
+ *
+ * In a browser `globalThis` is the window; anywhere a document was installed
+ * onto another host's global it is not, and `globalThis.ResizeObserver` is
+ * undefined while `window.ResizeObserver` is there.
+ */
+function windowOf(): any {
+  return globalThis.window ?? globalThis;
+}
+
+/**
+ * Listen to an event on a target, cleaning up after itself.
+ *
+ * `target` may be a ref, an element, or a function returning either, so this
+ * covers the window, the document, and a node that does not exist yet at the
+ * time the hook is called.
+ */
+export function useEventListener<TEvent extends Event>(
+  target: Ref<EventTarget> | EventTarget | (() => EventTarget | null) | null,
+  name: string,
+  handler: (event: TEvent) => mixed,
+  options?: AddEventListenerOptions,
+): void {
+  const stable = useStableCallback(handler);
+  const capture = options?.capture ?? false;
+  const passive = options?.passive;
+  const once = options?.once ?? false;
+
+  useIsomorphicLayoutEffect(() => {
+    const node = resolve(target);
+    if (node == null) {
+      return;
+    }
+    const listener = (event: Event) => stable(event as any);
+    node.addEventListener(name, listener, { capture, passive, once });
+    return () => node.removeEventListener(name, listener, { capture });
+  }, [target, name, stable, capture, passive, once]);
+}
+
+/**
+ * Call `handler` when a press lands outside `ref`.
+ *
+ * `pointerdown` rather than `click`, because a menu that closes on click stays
+ * open for the whole press — and because a click whose press started inside
+ * the menu and ended outside it should not close it.
+ */
+export function useClickOutside(ref: Ref<HTMLElement>, handler: (event: Event) => mixed): void {
+  const stable = useStableCallback(handler);
+
+  useEffect(() => {
+    if (typeof globalThis.document === "undefined") {
+      return;
+    }
+    const listener = (event: Event) => {
+      const node = ref.current;
+      const target: any = event.target;
+      if (node != null && target != null && !node.contains(target)) {
+        stable(event);
+      }
+    };
+    globalThis.document.addEventListener("pointerdown", listener);
+    return () => globalThis.document.removeEventListener("pointerdown", listener);
+  }, [ref, stable]);
+}
+
+/** Whether the pointer is over the element. */
+export function useHover(ref: Ref<HTMLElement>): boolean {
+  const [hovered, setHovered] = useState(false);
+  useEventListener(ref, "pointerenter", () => setHovered(true));
+  useEventListener(ref, "pointerleave", () => setHovered(false));
+  return hovered;
+}
+
+/** Whether focus is inside the element. */
+export function useFocusWithin(ref: Ref<HTMLElement>): boolean {
+  const [within, setWithin] = useState(false);
+  useEventListener(ref, "focusin", () => setWithin(true));
+  useEventListener(ref, "focusout", () => setWithin(false));
+  return within;
+}
+
+/**
+ * The element's size, as the browser measures it.
+ *
+ * A `ResizeObserver` rather than a window resize listener, because an element
+ * changes size when its content changes, when a sibling grows, and when a
+ * container query fires — none of which resizes the window.
+ */
+export function useElementSize(ref: Ref<HTMLElement>): {|
+  readonly width: number,
+  readonly height: number,
+|} {
+  const [size, setSize] = useState({ width: 0, height: 0 });
+
+  useIsomorphicLayoutEffect(() => {
+    const node = ref.current;
+    if (node == null || typeof windowOf().ResizeObserver !== "function") {
+      return;
+    }
+    const observer = new (windowOf().ResizeObserver)((entries) => {
+      const entry = entries[0];
+      if (entry == null) {
+        return;
+      }
+      const box = entry.contentRect;
+      // Only on a real change: an observer that fires with the same numbers
+      // would re-render forever.
+      setSize((current) =>
+        current.width === box.width && current.height === box.height
+          ? current
+          : { width: box.width, height: box.height },
+      );
+    });
+    observer.observe(node);
+    return () => observer.disconnect();
+  }, [ref]);
+
+  return size;
+}
+
+/** Whether the element is in the viewport. */
+export function useIntersecting(
+  ref: Ref<HTMLElement>,
+  options?: {| readonly rootMargin?: string, readonly threshold?: number |},
+): boolean {
+  const [intersecting, setIntersecting] = useState(false);
+  const rootMargin = options?.rootMargin;
+  const threshold = options?.threshold;
+
+  useEffect(() => {
+    const node = ref.current;
+    if (node == null || typeof windowOf().IntersectionObserver !== "function") {
+      return;
+    }
+    const observer = new (windowOf().IntersectionObserver)(
+      (entries) => {
+        const entry = entries[0];
+        if (entry != null) {
+          setIntersecting(entry.isIntersecting);
+        }
+      },
+      { rootMargin, threshold },
+    );
+    observer.observe(node);
+    return () => observer.disconnect();
+  }, [ref, rootMargin, threshold]);
+
+  return intersecting;
+}
+
+function resolve(
+  target: Ref<EventTarget> | EventTarget | (() => EventTarget | null) | null,
+): EventTarget | null {
+  if (target == null) {
+    return null;
+  }
+  if (typeof target === "function") {
+    return target();
+  }
+  if (typeof (target as any).addEventListener === "function") {
+    return target as any;
+  }
+  return (target as any).current ?? null;
+}
+
+/** A ref for one of the hooks above, typed for the element you will attach it to. */
+export function useElementRef<T extends HTMLElement>(): Ref<T> {
+  return useRef<T | null>(null);
+}

package/internal/lifecycle.js

@@ -0,0 +1,100 @@
+// @flow
+//
+// The hooks everything else is built out of.
+//
+// The one that matters most is `useStableCallback`. A callback recreated every
+// render is the single most common cause of a React performance problem and of
+// a subscription that tears itself down and sets itself up on every keystroke —
+// and the usual fix, listing the callback in a dependency array, spreads the
+// problem to every hook that takes it. A stable identity that always calls the
+// latest closure fixes it once.
+
+import {
+  useCallback,
+  useEffect,
+  useInsertionEffect,
+  useLayoutEffect,
+  useRef,
+  useState,
+} from "@uniflowed/react";
+
+/**
+ * `useLayoutEffect` in the browser, `useEffect` on the server.
+ *
+ * uf prerenders every static route, and React warns that `useLayoutEffect`
+ * does nothing during a server render — correctly, because there is no layout
+ * to read. Every hook here that measures or subscribes uses this, so a hook is
+ * not a reason a page cannot be prerendered.
+ */
+export const useIsomorphicLayoutEffect: typeof useLayoutEffect =
+  typeof globalThis.document === "undefined" ? useEffect : useLayoutEffect;
+
+/**
+ * A callback whose identity never changes and whose body is always the latest.
+ *
+ * This is the `useEvent` shape from React's own RFC. The ref is written in an
+ * insertion effect rather than in the render, because writing it during render
+ * makes the callback's behaviour depend on whether that render was thrown away
+ * — and it is written before any layout effect runs, so a subscription set up
+ * in one already sees the current body.
+ */
+export function useStableCallback<TArgs extends $ReadOnlyArray<mixed>, TReturn>(
+  callback: (...args: TArgs) => TReturn,
+): (...args: TArgs) => TReturn {
+  const latest = useRef(callback);
+
+  useInsertionEffect(() => {
+    latest.current = callback;
+  }, [callback]);
+
+  return useCallback((...args: TArgs) => latest.current(...args), []);
+}
+
+/** The value from the previous render, or `undefined` on the first. */
+export function usePrevious<T>(value: T): T | void {
+  const previous = useRef<T | void>(undefined);
+  useEffect(() => {
+    previous.current = value;
+  }, [value]);
+  return previous.current;
+}
+
+/**
+ * Whether the component has mounted.
+ *
+ * For the case where a value differs between server and client and rendering
+ * the client's on the first pass would be a hydration mismatch: render the
+ * server's, then switch.
+ */
+export function useMounted(): boolean {
+  const [mounted, setMounted] = useState(false);
+  useEffect(() => {
+    setMounted(true);
+  }, []);
+  return mounted;
+}
+
+/** Run `body` once, after mount. */
+export function useMount(body: () => mixed): void {
+  const stable = useStableCallback(body);
+  useEffect(() => {
+    stable();
+  }, [stable]);
+}
+
+/** Run `body` once, at unmount. */
+export function useUnmount(body: () => mixed): void {
+  const stable = useStableCallback(body);
+  useEffect(() => () => void stable(), [stable]);
+}
+
+/**
+ * Force a re-render.
+ *
+ * A counter rather than a boolean, because two renders in a row must both
+ * change the state or React drops the second.
+ */
+export function useRerender(): () => void {
+  const [, setTick] = useState(0);
+  return useCallback(() => setTick((tick) => tick + 1), []);
+}

package/internal/state.js

@@ -0,0 +1,159 @@
+// @flow
+//
+// State with a shape.
+//
+// `useStorage` is the one worth reading. Persisted state has three problems a
+// `useState` plus a `useEffect` does not solve: the first render on a
+// prerendered page has no storage to read, two components using the same key
+// must agree, and another tab writing the key should be seen. All three are
+// what `useSyncExternalStore` is for.
+
+import { useCallback, useMemo, useState, useSyncExternalStore } from "@uniflowed/react";
+
+import { useStableCallback } from "./lifecycle.js";
+
+/** A boolean with the three things a caller ever does to one. */
+export function useToggle(initial: boolean = false): {|
+  readonly on: boolean,
+  readonly toggle: () => void,
+  readonly set: (value: boolean) => void,
+|} {
+  const [on, setOn] = useState(initial);
+  const toggle = useCallback(() => setOn((value) => !value), []);
+  return useMemo(() => ({ on, toggle, set: setOn }), [on, toggle]);
+}
+
+/** A number, optionally clamped. */
+export function useCounter(
+  initial: number = 0,
+  bounds?: {| readonly min?: number, readonly max?: number |},
+): {|
+  readonly count: number,
+  readonly increment: (by?: number) => void,
+  readonly decrement: (by?: number) => void,
+  readonly set: (value: number) => void,
+  readonly reset: () => void,
+|} {
+  const min = bounds?.min;
+  const max = bounds?.max;
+
+  const clamp = useCallback(
+    (value: number) => {
+      const lower = min == null ? value : Math.max(min, value);
+      return max == null ? lower : Math.min(max, lower);
+    },
+    [min, max],
+  );
+
+  const [count, setCount] = useState(() => clamp(initial));
+  const move = useCallback((delta: number) => setCount((value) => clamp(value + delta)), [clamp]);
+
+  return useMemo(
+    () => ({
+      count,
+      increment: (by?: number) => move(by ?? 1),
+      decrement: (by?: number) => move(-(by ?? 1)),
+      set: (value: number) => setCount(clamp(value)),
+      reset: () => setCount(clamp(initial)),
+    }),
+    [count, move, clamp, initial],
+  );
+}
+
+/**
+ * Every subscriber of a storage key, so a write is seen by all of them.
+ *
+ * A `storage` event does not fire in the tab that made the change, so without
+ * this two components sharing a key drift apart until one of them re-renders
+ * for an unrelated reason.
+ */
+const listeners: Map<string, Set<() => void>> = new Map();
+
+function announce(key: string): void {
+  for (const listener of listeners.get(key) ?? []) {
+    listener();
+  }
+}
+
+function area(session: boolean): mixed {
+  try {
+    return session ? globalThis.sessionStorage : globalThis.localStorage;
+  } catch {
+    // A browser with site data blocked throws on the property itself.
+    return null;
+  }
+}
+
+/**
+ * State kept in `localStorage`, or in `sessionStorage`.
+ *
+ * `initial` is what a prerender uses and what an unset or unreadable key falls
+ * back to, so the first paint is stated rather than accidental. A value that
+ * will not parse is treated as absent rather than thrown: storage is shared
+ * with older versions of the same application, and refusing to start because
+ * of a stale key would be worse than starting fresh.
+ */
+export function useStorage<T>(
+  key: string,
+  initial: T,
+  options?: {| readonly session?: boolean |},
+): [T, (value: T) => void] {
+  const session = options?.session ?? false;
+
+  const subscribe = useCallback(
+    (notify: () => void) => {
+      const set = listeners.get(key) ?? new Set();
+      set.add(notify);
+      listeners.set(key, set);
+      const onStorage = (event: mixed) => {
+        if ((event as any)?.key === key) {
+          notify();
+        }
+      };
+      const win: any = globalThis.window ?? globalThis;
+      win.addEventListener?.("storage", onStorage);
+      return () => {
+        set.delete(notify);
+        win.removeEventListener?.("storage", onStorage);
+      };
+    },
+    [key],
+  );
+
+  const raw = useSyncExternalStore(
+    subscribe,
+    () => {
+      const store: any = area(session);
+      try {
+        return store?.getItem(key) ?? null;
+      } catch {
+        return null;
+      }
+    },
+    () => null,
+  );
+
+  const value = useMemo(() => {
+    if (raw == null) {
+      return initial;
+    }
+    try {
+      return JSON.parse(raw);
+    } catch {
+      return initial;
+    }
+  }, [raw, initial]);
+
+  const write = useStableCallback((next: T) => {
+    const store: any = area(session);
+    try {
+      store?.setItem(key, JSON.stringify(next));
+    } catch {
+      // Full, or blocked. The announcement still happens so the components
+      // sharing this key agree with each other for this session.
+    }
+    announce(key);
+  });
+
+  return [value, write];
+}

package/internal/timing.js

@@ -0,0 +1,116 @@
+// @flow
+//
+// 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.
+
+import { useEffect, useRef, useState } from "@uniflowed/react";
+
+import { useStableCallback } from "./lifecycle.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 function 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 function 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 function 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 function useThrottledCallback<TArgs extends $ReadOnlyArray<mixed>>(
+  body: (...args: TArgs) => mixed,
+  millis: number,
+): (...args: TArgs) => void {
+  const stable = useStableCallback(body);
+  const last = useRef(0);
+
+  return useStableCallback((...args: TArgs) => {
+    const now = Date.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 function useDebouncedCallback<TArgs extends $ReadOnlyArray<mixed>>(
+  body: (...args: TArgs) => mixed,
+  millis: number,
+): (...args: TArgs) => void {
+  const stable = useStableCallback(body);
+  const timer = useRef<TimeoutID | null>(null);
+
+  useEffect(
+    () => () => {
+      if (timer.current != null) {
+        clearTimeout(timer.current);
+      }
+    },
+    [],
+  );
+
+  return useStableCallback((...args: TArgs) => {
+    if (timer.current != null) {
+      clearTimeout(timer.current);
+    }
+    timer.current = setTimeout(() => {
+      timer.current = null;
+      stable(...args);
+    }, millis);
+  });
+}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@uniflowed/hooks",
+  "version": "0.0.0-alpha.2",
+  "description": "The React hooks an application writes anyway, prerender-safe, part of the Unified Toolchain for Flow.",
+  "type": "module",
+  "license": "MIT",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ubugeeei-prod/uf.git",
+    "directory": "packages/hooks"
+  },
+  "exports": {
+    ".": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "internal"
+  ],
+  "dependencies": {
+    "@uniflowed/react": "0.0.0-alpha.2"
+  },
+  "peerDependencies": {
+    "react": ">=19"
+  }
+}