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

package/{internal/async.js → async.js}

@@ -1,6 +1,6 @@
 // @flow
 //
-// Running a promise from a component.
+// `@uniflowed/hooks/async`: 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
@@ -12,6 +12,19 @@
 // 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.
+//
+// # What belongs in this module
+//
+// A hook that starts one call and holds its pending, resolved and failed
+// states. One file for one hook, because the subject is neither the
+// component's life nor a timer nor a DOM node, and hiding it inside one of
+// those would make all three harder to name.
+//
+// Deliberately not here, and not in this package at all: caching, retries,
+// deduplication between components, invalidation. Those are
+// `@uniflowed/query`'s, and the boundary is what keeps `useAsync` small enough
+// to read in one sitting. When a caller needs a cache they should change
+// packages, not discover that this hook grew one.
 
 import { useCallback, useEffect, useState } from "@uniflowed/react";
 

package/{internal/browser.js → browser.js}

@@ -1,6 +1,6 @@
 // @flow
 //
-// Reading the browser, safely on a server.
+// `@uniflowed/hooks/browser`: reading the environment, 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
@@ -9,6 +9,20 @@
 // 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.
+//
+// # What belongs in this module
+//
+// A reading of the one browser the page is in: its size, its connection, its
+// visibility, the preferences the reader set. 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, and why every one of them is a
+// `useSyncExternalStore` rather than an effect that sets state.
+//
+// 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.
 
 import { useCallback, useSyncExternalStore } from "@uniflowed/react";
 

package/{internal/element.js → dom.js}

@@ -1,12 +1,29 @@
 // @flow
 //
-// Watching a node.
+// `@uniflowed/hooks/dom`: watching one 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.
+//
+// # What belongs in this module
+//
+// A hook whose subject is a particular element the caller is holding: listen
+// to it, measure it, notice a pointer over it, notice it entering the
+// viewport. The signature is the giveaway — if it takes a ref, it is here.
+//
+// The neighbour it is most often confused with is `browser.js`, which reads
+// the ambient environment: the window's size, whether the document is visible,
+// what the reader's media queries say. Those need no ref because there is only
+// one of the thing they read, and they are built on `useSyncExternalStore`
+// with a stated server value. These need a ref because there are as many
+// answers as there are elements, and they are built on effects because there
+// is nothing to read until one is mounted.
+//
+// The file was called `element.js`, which named the argument rather than the
+// job and left `browser.js` looking like its opposite when it is its sibling.
 
 import { useEffect, useRef, useState } from "@uniflowed/react";
 

package/index.js

@@ -20,10 +20,39 @@
 // 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.
+//
+// # How the package is laid out
+//
+// Six modules beside this one, split by what a hook's subject is — because
+// that is the question a reader looking for one actually asks:
+//
+// - `lifecycle.js` — the component itself: mounted, previous, run once.
+// - `state.js` — a value the component owns, with the operations that suit it.
+// - `timing.js` — when something runs: intervals, timeouts, debounce,
+//   throttle.
+// - `async.js` — one promise, and the stale-response bug.
+// - `browser.js` — the ambient environment: viewport, connection, preferences.
+// - `dom.js` — one element the caller holds a ref to: listen, measure,
+//   observe.
+//
+// The two that are easiest to confuse are the last two, so each says so in its
+// own header: `browser.js` needs no ref because there is one browser, and
+// `dom.js` needs one because there are as many answers as there are elements.
+//
+// They sit here rather than under an `internal/`, and each has its own
+// subpath. Every name in them is exported from this file, so calling them
+// internal would have described nothing true, and it cost a reader a directory
+// hop to reach the first line of code. `internal/` is for a module consumers
+// must not reach; this package has none.
+//
+// `lifecycle.js` is the one the others import — `timing.js`, `state.js` and
+// `dom.js` all want `useStableCallback` — and it is still a subject rather
+// than a bag of shared helpers. A hook goes there because it is about the
+// component's life, not because more than one file wanted it.
 
-export type { Async } from "./internal/async.js";
+export type { Async } from "./async.js";
 
-export { useAsync } from "./internal/async.js";
+export { useAsync } from "./async.js";
 export {
   useIsomorphicLayoutEffect,
   useMount,
@@ -32,14 +61,14 @@ export {
   useRerender,
   useStableCallback,
   useUnmount,
-} from "./internal/lifecycle.js";
+} from "./lifecycle.js";
 export {
   useDebouncedCallback,
   useDebouncedValue,
   useInterval,
   useThrottledCallback,
   useTimeout,
-} from "./internal/timing.js";
+} from "./timing.js";
 export {
   useDocumentVisible,
   useMediaQuery,
@@ -47,7 +76,7 @@ export {
   usePrefersReducedMotion,
   usePreferredColorScheme,
   useWindowSize,
-} from "./internal/browser.js";
+} from "./browser.js";
 export {
   useClickOutside,
   useElementRef,
@@ -56,5 +85,5 @@ export {
   useFocusWithin,
   useHover,
   useIntersecting,
-} from "./internal/element.js";
-export { useCounter, useStorage, useToggle } from "./internal/state.js";
+} from "./dom.js";
+export { useCounter, useStorage, useToggle } from "./state.js";

package/{internal/lifecycle.js → lifecycle.js}

@@ -1,6 +1,6 @@
 // @flow
 //
-// The hooks everything else is built out of.
+// `@uniflowed/hooks/lifecycle`: where a component is in its life.
 //
 // 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
@@ -8,6 +8,20 @@
 // 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.
+//
+// # What belongs in this module
+//
+// A hook whose subject is the component itself: has it mounted, is it still
+// mounted, what did it render last time, run this once, run this on the way
+// out, and the two effect-shaped primitives the rest of the package needs
+// (`useIsomorphicLayoutEffect`, `useStableCallback`). None of them reads
+// anything outside React.
+//
+// It is also the one module here the others import, which is a consequence and
+// not the reason: `timing.js`, `state.js` and `dom.js` all need a stable
+// callback. That does not make this a "utils" or a "common" — it has a subject
+// of its own, and a hook lands here because it is about the component's life,
+// never because two other files happened to want it.
 
 import {
   useCallback,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniflowed/hooks",
-  "version": "0.0.0-alpha.2",
+  "version": "0.0.0-alpha.4",
   "description": "The React hooks an application writes anyway, prerender-safe, part of the Unified Toolchain for Flow.",
   "type": "module",
   "license": "MIT",
@@ -11,14 +11,19 @@
     "directory": "packages/hooks"
   },
   "exports": {
-    ".": "./index.js"
+    ".": "./index.js",
+    "./async": "./async.js",
+    "./browser": "./browser.js",
+    "./dom": "./dom.js",
+    "./lifecycle": "./lifecycle.js",
+    "./state": "./state.js",
+    "./timing": "./timing.js"
   },
   "files": [
-    "index.js",
-    "internal"
+    "*.js"
   ],
   "dependencies": {
-    "@uniflowed/react": "0.0.0-alpha.2"
+    "@uniflowed/react": "0.0.0-alpha.4"
   },
   "peerDependencies": {
     "react": ">=19"

package/{internal/state.js → state.js}

@@ -1,12 +1,26 @@
 // @flow
 //
-// State with a shape.
+// `@uniflowed/hooks/state`: 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.
+//
+// # What belongs in this module
+//
+// A `useState` a component would otherwise write out by hand, returned as the
+// operations that make sense on it rather than as a setter: a boolean with
+// `toggle`, a number with `increment` and a clamp, a value that survives a
+// reload. The test is that the hook owns the value and hands back a small API
+// over it.
+//
+// Not here: shared application state. An atom two routes both read is
+// `@uniflowed/state`'s, and a value derived from a server response is
+// `@uniflowed/query`'s. Everything in this file is local to one component —
+// `useStorage` reaches outside only to persist, and only under a key the
+// caller named.
 
 import { useCallback, useMemo, useState, useSyncExternalStore } from "@uniflowed/react";
 

package/{internal/timing.js → timing.js}

@@ -1,12 +1,24 @@
 // @flow
 //
-// Timers that stop when the component does.
+// `@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. 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.
+//
+// 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.
 
 import { useEffect, useRef, useState } from "@uniflowed/react";