@uniflowed/hooks 0.0.0-alpha.9 → 0.2.0

package/async.js

@@ -118,6 +118,9 @@ export hook useAsync<T>(
     // Guarded rather than unconditional: a reload that arrives while a call is
     // already in flight would otherwise build a new state object, and a new
     // object is a re-render that changes nothing anyone can see.
+    // This effect owns the request lifecycle; the synchronous write marks that
+    // external request as pending before its callbacks settle it.
+    // uf-lint-disable-next-line react-compiler/set-state-in-effect
     setState((current) => (current.pending ? current : { ...current, pending: true }));
 
     const run = (tries: number) => {

package/browser.js

@@ -13,17 +13,52 @@
 // # What belongs in this module
 //
 // A reading of the one browser the page is in: its size, its scroll offset,
-// its connection, its visibility, its position on the earth, the preferences
-// the reader set, the permissions the reader granted. There is exactly one
-// answer at a time, nobody has to pass anything in to ask, and a server has no
-// answer at all — which is why every hook here either takes a server value
-// from the caller or states an honest default.
+// its connection, its visibility, its position on the earth, the fragment in
+// its address bar, the preferences the reader set, the permissions the reader
+// granted. There is exactly one answer at a time, nobody has to pass anything
+// in to ask, and a server has no answer at all — which is why every hook here
+// either takes a server value from the caller or states an honest default.
 //
 // Not here: anything about a specific element, which needs a ref and lives in
 // `dom.js`. `useDocumentVisible` is the closest call in the package and stays
 // here, because the document is the environment rather than a node a caller
 // chose.
 //
+// The path and the query are not here either, and that one is a boundary rather
+// than a filing decision: they are on the request, so `@uniflowed/router` has
+// already resolved them and `useRoute` is where a page reads them. What is here
+// is the fragment, which the browser strips before the request goes out and
+// which therefore nothing on the server has ever seen. See `useHash`.
+//
+// # What the first render produces
+//
+// Every hook below answers twice with the same value — once during the
+// prerender, once during the client's hydrating render — and only then with
+// what the browser actually says. That second column is not a detail: it is the
+// value React compares the two trees at, so a hook whose first client render
+// disagreed with the server's would report a mismatch on a page that did
+// nothing wrong.
+//
+// | Hook | Prerender, and the first client render | Afterwards |
+// | --- | --- | --- |
+// | `useSupported` | `false` | what `probe` says |
+// | `useMediaQuery` | `serverValue`, default `false` | whether it matches |
+// | `usePreferredColorScheme` | `serverValue`, default `"light"` | the reader's setting |
+// | `usePrefersReducedMotion` | `serverValue`, default `false` | the reader's setting |
+// | `useOnline` | `serverValue`, default `true` | `navigator.onLine` |
+// | `useDocumentVisible` | `serverValue`, default `true` | the visibility state |
+// | `useHash` | `""`, and no way to say otherwise | the fragment |
+// | `useWindowSize` | `serverValue`, default `0x0` | the viewport |
+// | `useWindowScroll` | `serverValue`, default `0,0` | the offset |
+// | `useNetwork` | `{ online: serverValue, measured: null }` | what Chromium measured |
+// | `useGeolocation` | `"unsupported"` | `"pending"`, then a fix or a failure |
+// | `usePermission` | `"unknown"` | what the browser answers |
+// | `useScrollLock` | nothing at all — effects do not run in a prerender | the page is held |
+//
+// `packages/hooks/hooks-ssr.test.js` renders every one of them in a process with
+// no document and asserts the markup, so a row of this table that stopped being
+// true would fail there rather than in somebody's browser.
+//
 // # The one that writes
 //
 // `useScrollLock` is the exception to "reading", and it is here rather than in
@@ -41,6 +76,15 @@
 // subscriptions whose *first* value only arrives asynchronously, so there is
 // nothing for a snapshot to return until it does, and `useScrollLock` writes.
 // Each says so where it is defined.
+//
+// `useHash` is a store with three subscriptions instead of one, because no
+// single event covers the fragment. `hashchange` and `popstate` cover what a
+// reader does; `history.pushState` fires neither, so a registry of its own
+// subscribers covers what the hook itself writes; and `currententrychange`,
+// where the Navigation API exists, covers the case neither of those reaches —
+// a `pushState` made by other code, the router's own included. That is a store
+// whose gap has shrunk to the browsers without the Navigation API, not a
+// fourth kind of hook.
 
 import { useCallback, useEffect, useMemo, useState, useSyncExternalStore } from "@uniflowed/react";
 
@@ -76,6 +120,58 @@ export type BrowserNavigator = {
   ...
 };
 
+/**
+ * The part of `location` this module reads.
+ *
+ * `href` and the fragment, and nothing else. The path and the query are on the
+ * request, so `@uniflowed/router` has already resolved them and a second
+ * reading of them here would be a second answer to a settled question — see
+ * `useHash`.
+ */
+export type BrowserLocation = {
+  readonly href: string,
+  readonly hash: string,
+  ...
+};
+
+/**
+ * The part of `history` this module writes through.
+ *
+ * `state` is read so that a fragment written from here hands back whatever a
+ * router put there, rather than clearing it. The second parameter of both
+ * methods has been ignored by every browser since the API shipped, and is
+ * typed rather than omitted because it is positional.
+ */
+export type BrowserHistory = {
+  readonly state: mixed,
+  readonly pushState: (state: mixed, unused: string, url: string) => void,
+  readonly replaceState: (state: mixed, unused: string, url: string) => void,
+  ...
+};
+
+/**
+ * The part of the Navigation API this module listens to.
+ *
+ * One event, and deliberately only one. `currententrychange` fires after the
+ * current history entry has changed *for any reason* — a link, the back
+ * button, and the two calls that fire nothing else, `history.pushState` and
+ * `history.replaceState`. It is the only thing the platform offers that hears
+ * a fragment written by code other than the writer, which is what makes
+ * `useHash` able to see `@uniflowed/router`'s own navigation.
+ *
+ * `navigate` and `navigateerror` are not here: intercepting a navigation is
+ * the router's business, and a hook that reads the fragment has no opinion
+ * about whether one should happen.
+ *
+ * Optional on [`BrowserWindow`], because this is an addition rather than the
+ * base — see `useHash` for which browsers have it and what the others get.
+ */
+export type BrowserNavigation = {
+  readonly addEventListener: (type: "currententrychange", listener: () => mixed) => void,
+  readonly removeEventListener: (type: "currententrychange", listener: () => mixed) => void,
+  ...
+};
+
 /** The Network Information object, which only Chromium has. */
 export type NetworkConnection = {
   readonly downlink?: number,
@@ -98,6 +194,9 @@ export type NetworkConnection = {
 export type BrowserWindow = {
   readonly document: Document,
   readonly navigator: BrowserNavigator,
+  readonly location?: ?BrowserLocation,
+  readonly history?: ?BrowserHistory,
+  readonly navigation?: ?BrowserNavigation,
   readonly localStorage?: ?Storage,
   readonly sessionStorage?: ?Storage,
   readonly innerWidth: number,
@@ -269,6 +368,176 @@ export hook useDocumentVisible(serverValue: boolean = true): boolean {
   return useSyncExternalStore(subscribe, snapshot, () => serverValue);
 }
 
+/**
+ * Everybody watching the fragment in this tab.
+ *
+ * Module-level, because neither `history.pushState` nor `history.replaceState`
+ * fires anything: a component that writes the fragment has to tell the others
+ * itself, and in a browser without the Navigation API there is nothing in the
+ * platform that will do it. The same registry shape as `useStorage`'s, and
+ * balanced under Strict Mode for the same reason — `subscribe` adds and the
+ * cleanup it returns removes.
+ *
+ * It is kept where `currententrychange` exists rather than being switched off
+ * there. The two overlap — a write through this hook is heard twice — and that
+ * costs nothing, because `useSyncExternalStore` compares the snapshot and the
+ * fragment is a string that has not changed between the two notifications.
+ * Switching it off, on the other hand, would make the hook's own writes depend
+ * on a feature detection, so a browser that reported a `navigation` object it
+ * did not fire events from would silently lose the guarantee that has held
+ * since this hook existed.
+ */
+const fragmentListeners: Set<() => void> = new Set();
+
+/** Listen for every change to the fragment this tab can hear about. */
+function subscribeToFragment(notify: () => void): () => void {
+  const win = browserWindow();
+  // Read once and closed over, so the cleanup removes the listener from the
+  // object it was added to. A `navigation` that appeared or vanished between
+  // the two would otherwise leave a listener behind on a hook that unmounted.
+  const navigation = win?.navigation;
+  fragmentListeners.add(notify);
+  // `hashchange` covers an anchor the reader clicked and an address bar they
+  // edited; `popstate` covers back and forward, which fires only the second of
+  // the two when the entry it lands on differs by more than the fragment.
+  win?.addEventListener("hashchange", notify);
+  win?.addEventListener("popstate", notify);
+  // And `currententrychange` covers the case the other two and the registry
+  // between them still miss: a `pushState` or `replaceState` made by code that
+  // is not this hook. `@uniflowed/router` makes exactly that call on every
+  // client navigation, which is why the gap was never hypothetical.
+  navigation?.addEventListener("currententrychange", notify);
+  return () => {
+    fragmentListeners.delete(notify);
+    win?.removeEventListener("hashchange", notify);
+    win?.removeEventListener("popstate", notify);
+    navigation?.removeEventListener("currententrychange", notify);
+  };
+}
+
+/** The fragment, without its `#`, decoded where the escapes are valid. */
+function readFragment(): string {
+  const raw = browserWindow()?.location?.hash ?? "";
+  const text = raw.startsWith("#") ? raw.slice(1) : raw;
+  try {
+    return decodeURIComponent(text);
+  } catch {
+    // A fragment is whatever somebody typed into the address bar, and a lone
+    // `%` is not a reason to fail a render. The text as written is closer to
+    // what the reader meant than a throw is. `@uniflowed/web`'s cookie parser
+    // makes the same trade at the same kind of boundary.
+    return text;
+  }
+}
+
+/** What a server render, and the client's hydrating render, both report. */
+function noFragment(): string {
+  return "";
+}
+
+/**
+ * Write the fragment, without moving the page.
+ *
+ * Through `URL` rather than by concatenation, which is the whole safety
+ * argument: the setter percent-escapes what it is handed and can only put it
+ * after the `#`, so a caller who passes `?admin=1`, `//elsewhere.example` or a
+ * whole second URL writes a fragment that says so rather than a query, an
+ * origin or a path. `history.pushState` refuses a cross-origin URL, but that is
+ * the second line of defence and not one worth relying on for a same-origin
+ * path rewrite, which it permits.
+ *
+ * Module-level, so it is the same function on every render and nothing has to
+ * memoize it.
+ */
+function writeFragment(next: string, options?: {| readonly replace?: boolean |}): void {
+  const win = browserWindow();
+  const location = win?.location;
+  const history = win?.history;
+  if (location == null || history == null) {
+    return;
+  }
+  const url = new URL(location.href);
+  url.hash = next;
+  // `history.state` is handed back rather than cleared: a router put it there,
+  // and changing which tab is showing is not a reason to lose it.
+  if (options?.replace === true) {
+    history.replaceState(history.state, "", url.href);
+  } else {
+    history.pushState(history.state, "", url.href);
+  }
+  notifyFragment();
+}
+
+function notifyFragment(): void {
+  for (const listener of fragmentListeners) {
+    listener();
+  }
+}
+
+/**
+ * The fragment in the address bar, and a way to change it.
+ *
+ * The one part of the URL that needs a hook. A request carries the path and the
+ * query, so a server render already knows both and `@uniflowed/router`'s
+ * `useRoute` has resolved them; the fragment is never sent — the browser strips
+ * it before the request goes out — so there is no value for a server to know
+ * and no caller who could supply a better one. That is why this takes no
+ * `serverValue` where `useMediaQuery` and `useOnline` do: `""` is not a default
+ * chosen for want of a better one, it is the only honest answer, and the
+ * client's hydrating render reports it too before re-rendering with the truth.
+ *
+ * Returned without the `#`, and percent-decoded, so it compares directly
+ * against the `id` a section was given.
+ *
+ * Writing does not scroll, and that is deliberate. Moving to a section and
+ * recording which tab is open are two intentions, and the platform couples them
+ * only because assigning `location.hash` is the old way to do both at once — so
+ * a tab strip that writes `billing` would jump the page. Call
+ * `element.scrollIntoView()` where scrolling is what was wanted.
+ *
+ * `replace` overwrites the current history entry instead of adding one, which
+ * is what a tab strip wants: eleven tab clicks should not be eleven presses of
+ * the back button.
+ *
+ * # What it hears, and where
+ *
+ * `history.pushState` and `history.replaceState` fire no event of any kind —
+ * not `hashchange`, not `popstate` — so what a hook can see depends on where
+ * the write came from and on what the browser has:
+ *
+ * | The write | Everywhere | Without the Navigation API |
+ * | --- | --- | --- |
+ * | the reader: an anchor, the address bar, back and forward | seen | seen |
+ * | this hook's own setter | seen | seen |
+ * | `pushState` from other code — `@uniflowed/router`'s navigation | seen | **not seen** |
+ *
+ * The first two are `hashchange`, `popstate` and the module's own registry.
+ * The third is `currententrychange`, which fires after the current history
+ * entry changes for any reason at all, and which is the only thing the
+ * platform offers that hears a write the writer did not announce.
+ *
+ * "Without the Navigation API" is now a narrow set: Chrome and Edge have had
+ * it since 102 (2022), Safari since 26.2 and Firefox since 147 — but a reader
+ * on an older Safari or Firefox is a reader this column describes, and there
+ * the registry is still the whole answer. A router navigation that changes
+ * only the fragment leaves such a page showing the section it was on.
+ *
+ * The fragment is deliberately not on `RouteInfo` — `useRoute()` cannot answer
+ * this question and should not learn to. A `RouteInfo` is what a *request*
+ * resolved to, and the browser strips the fragment before the request goes
+ * out, so a field for it would be one the server could never fill and the two
+ * renders would disagree about. This hook is the one answer, and
+ * `currententrychange` is what makes it a complete one on the browsers that
+ * have it rather than a second reading of a value the router also holds.
+ */
+export hook useHash(): [
+  string,
+  (next: string, options?: {| readonly replace?: boolean |}) => void,
+] {
+  const fragment = useSyncExternalStore(subscribeToFragment, readFragment, noFragment);
+  return [fragment, writeFragment];
+}
+
 /**
  * How far something has been scrolled.
  *
@@ -429,16 +698,35 @@ export hook useScrollLock(locked: boolean): void {
 /** How good the connection is, as the browser grades it. */
 export type EffectiveConnectionType = "slow-2g" | "2g" | "3g" | "4g";
 
-/** What the browser will say about the connection. */
-export type Network = {|
-  readonly online: boolean,
+/**
+ * What Network Information measured, where there is such a thing.
+ *
+ * Its own type rather than three more fields on [`Network`], because the three
+ * of them arrive together or not at all: they come from `navigator.connection`,
+ * which is Chromium's alone. A server, and every other browser, has no object
+ * to read them off.
+ */
+export type NetworkMeasurement = {|
   /** Estimated bandwidth in megabits per second, where the browser reports it. */
   readonly downlink: number | null,
   readonly effectiveType: EffectiveConnectionType | null,
   /** Whether the reader has asked for less data to be used. */
   readonly saveData: boolean,
-  /** Whether anything beyond `online` was actually measured. */
-  readonly supported: boolean,
+|};
+
+/**
+ * What the browser will say about the connection.
+ *
+ * `measured` used to be three flat fields and a `supported` boolean beside
+ * them, which is the shape this package now refuses: a caller had to read one
+ * field to learn whether three others meant anything, and `downlink: null` said
+ * both "this browser does not measure bandwidth" and "it does, and has not
+ * decided yet". A null here says one thing — nothing on this side can answer —
+ * and the fields that would have been guesses are not reachable to be read.
+ */
+export type Network = {|
+  readonly online: boolean,
+  readonly measured: NetworkMeasurement | null,
 |};
 
 const EFFECTIVE_TYPES: $ReadOnlyArray<EffectiveConnectionType> = ["slow-2g", "2g", "3g", "4g"];
@@ -455,10 +743,11 @@ function asEffectiveType(value: string): EffectiveConnectionType | null {
 /**
  * What the browser will say about the connection.
  *
- * Only Chromium implements Network Information, so `supported` is part of the
- * answer rather than something a caller has to find out by seeing nulls. The
- * `online` half is everywhere, and stays true even where the rest is unknown —
- * which is the field almost every caller wants.
+ * Only Chromium implements Network Information, so a browser that does not
+ * reports `measured: null` rather than three fields that are indistinguishable
+ * from a slow connection. `online` stays flat and is answered everywhere — it
+ * is the field almost every caller wants, and burying it behind a narrowing
+ * would have made the common case pay for the rare one.
  *
  * The snapshot is a packed string for the reason `useWindowSize` gives: an
  * object rebuilt on every check never compares equal, and `useSyncExternalStore`
@@ -481,39 +770,49 @@ export hook useNetwork(serverValue: boolean = true): Network {
     };
   }, []);
 
-  const server = useCallback(() => `${serverValue ? "1" : "0"}|||0`, [serverValue]);
+  // Whether there was a connection object to read is its own field, because
+  // "this browser does not measure" and "it measures and reported nothing yet"
+  // pack to the same three empty values and are not the same answer.
+  // `effectiveType` is last so that it is the only field a `|` in browser text
+  // could run into.
+  const server = useCallback(() => `${serverValue ? "1" : "0"}|0|0||`, [serverValue]);
 
   const packed = useSyncExternalStore(
     subscribe,
     useCallback(() => {
       const navigator = browserWindow()?.navigator;
       if (navigator == null) {
-        return `${serverValue ? "1" : "0"}|||0`;
+        return `${serverValue ? "1" : "0"}|0|0||`;
       }
       const connection = navigator.connection;
       const online = navigator.onLine ?? serverValue;
       if (connection == null) {
-        return `${online ? "1" : "0"}|||0`;
+        return `${online ? "1" : "0"}|0|0||`;
       }
       const downlink = connection.downlink;
       return [
         online ? "1" : "0",
+        "1",
+        connection.saveData === true ? "1" : "0",
         downlink == null ? "" : String(downlink),
         connection.effectiveType ?? "",
-        connection.saveData === true ? "1" : "0",
       ].join("|");
     }, [serverValue]),
     server,
   );
 
   return useMemo(() => {
-    const [online, downlink, effectiveType, saveData] = packed.split("|");
+    const [online, measured, saveData, downlink, effectiveType] = packed.split("|");
     return {
       online: online === "1",
-      downlink: downlink === "" ? null : Number(downlink),
-      effectiveType: asEffectiveType(effectiveType),
-      saveData: saveData === "1",
-      supported: downlink !== "" || effectiveType !== "",
+      measured:
+        measured === "1"
+          ? {
+              downlink: downlink === "" ? null : Number(downlink),
+              effectiveType: asEffectiveType(effectiveType),
+              saveData: saveData === "1",
+            }
+          : null,
     };
   }, [packed]);
 }
@@ -527,12 +826,47 @@ export type Geoposition = {|
   readonly timestamp: number,
 |};
 
-/** What `useGeolocation` knows so far. */
-export type GeolocationReading = {|
-  readonly position: Geoposition | null,
-  readonly error: Error | null,
-  readonly supported: boolean,
-|};
+/**
+ * What `useGeolocation` knows so far.
+ *
+ * A union rather than a record of nullable fields, and the difference is the
+ * whole point of the type. The record it replaced —
+ * `{| position: Geoposition | null, error: Error | null, supported: boolean |}`
+ * — could represent eight states, of which four could never happen, and it
+ * asked every caller to work out from three fields which of the four real ones
+ * they were in. `position == null` meant "no browser", "not asked", "asked and
+ * refused" and "waiting for the reader to decide", and a page that wanted to
+ * say something different for each had to reconstruct the distinction the hook
+ * had thrown away.
+ *
+ * Five states, each of which a page does something different about, and Flow
+ * refuses to read a field the state does not have.
+ */
+export type GeolocationReading =
+  /**
+   * Not watching, because the caller passed `enabled: false`. Reported before
+   * `"unsupported"` is even considered, so it is the same on both sides of a
+   * hydration.
+   */
+  | {| readonly status: "idle" |}
+  /** No geolocation object here at all: a server render, or a browser without one. */
+  | {| readonly status: "unsupported" |}
+  /** Watching. The reader has been asked and has not answered yet. */
+  | {| readonly status: "pending" |}
+  /**
+   * A fix. `error` is the failure of a *later* reading, and its presence means
+   * the position beside it is the last good one rather than the current one.
+   */
+  | {| readonly status: "located", readonly position: Geoposition, readonly error: Error | null |}
+  /** Refused, unavailable or timed out, with no earlier fix to fall back on. */
+  | {| readonly status: "failed", readonly error: Error |};
+
+// The three states with nothing in them, allocated once. A hook that returns a
+// fresh object for "nothing has happened" makes every caller's dependency array
+// change on every render.
+const UNSUPPORTED: GeolocationReading = { status: "unsupported" };
+const IDLE: GeolocationReading = { status: "idle" };
+const PENDING: GeolocationReading = { status: "pending" };
 
 /**
  * Watch where the reader is.
@@ -541,8 +875,14 @@ export type GeolocationReading = {|
  * stylistic: there is no snapshot to read. The browser has no "current
  * position" property to ask — the first value arrives in a callback, after a
  * permission prompt the reader may take a minute to answer or never answer at
- * all. So `position` is `null` until one arrives, on a server and in a browser
- * alike, which is also what makes it hydration-safe.
+ * all. So there is nothing but `"unsupported"` to report during a prerender and
+ * in the client's first render, which is also what makes it hydration-safe: the
+ * server writes the markup for a page that does not know where anybody is, and
+ * the hydrating render agrees with it.
+ *
+ * Turning `enabled` off after a fix reports `"idle"` rather than keeping the
+ * position, because a reading nobody is watching is a reading nobody should be
+ * shown. A caller who wants the last one to stay on screen holds it.
  *
  * Mounting this asks the reader for permission. Mount it on the page that
  * needs a position, not at the top of an application.
@@ -591,10 +931,28 @@ export hook useGeolocation(options?: {|
     return () => geolocation.clearWatch(watch);
   }, [enabled, highAccuracy, maximumAge, timeout]);
 
-  return useMemo(
-    () => ({ position: reading.position, error: reading.error, supported }),
-    [reading, supported],
-  );
+  // Derived during the render from what the effect has recorded, rather than
+  // kept as a second copy of it in state: a status that had to be written by
+  // the same `setReading` call would be a second thing to keep in step with
+  // `enabled` and with `supported`, neither of which the effect can see.
+  return useMemo(() => {
+    // `enabled` is asked about before `supported`, because it is the caller's
+    // own decision and is therefore the same on both sides of a hydration: a
+    // watch nobody asked for is idle on a server and idle in a browser, where
+    // "unsupported" would have been true on the server and false a moment
+    // later.
+    if (!enabled) {
+      return IDLE;
+    }
+    if (!supported) {
+      return UNSUPPORTED;
+    }
+    const { position, error } = reading;
+    if (position != null) {
+      return { status: "located", position, error };
+    }
+    return error == null ? PENDING : { status: "failed", error };
+  }, [supported, enabled, reading]);
 }
 
 /** A permission this hook knows how to ask about. */