@alxia/react-router 0.31.1 → 0.32.0

package/README.md

@@ -1057,8 +1057,8 @@ import { RouterLink } from '@alxia/react-router/link';
 ## A fetcher's fresh answer
 
 A keyed fetcher outlives its page, so a `useEffect` on its data replays an
-earlier visit's answer on remount. `@alxia/react-router/fetcher` (`react` is
-its only import) calls your handler once per new answer:
+earlier visit's answer on remount. `@alxia/react-router/fetcher` (`react` and
+`react-router` are its imports) calls your handler once per new answer:
 
 ```tsx
 import { useJsonFetcher } from '@alxia/react-router/errors';
@@ -1068,6 +1068,20 @@ const { fetcher } = useJsonFetcher<typeof action>('save');
 const answer = useFetcherAnswer(fetcher, (result) => toast(result.message));
 ```
 
+A resource route loaded for what is typed (a typeahead, a preview): one load
+after a pause, from a minimum length, the previous answer kept (`stale`) until
+the new one lands, and a retry:
+
+```tsx
+import { useDebouncedFetcher } from '@alxia/react-router/fetcher';
+
+const { data, stale, state, retry } = useDebouncedFetcher<Found>(
+	typed,
+	(q) => `/suggest?${new URLSearchParams({ q })}`,
+	{ minLength: 2, delayMs: 250 },
+);
+```
+
 See the [fetcher guide](https://github.com/softistx/alxia/blob/develop/packages/react-router/docs/guide/fetcher.md).
 
 ## A list whose state is the URL
@@ -1359,11 +1373,12 @@ From `@alxia/react-router/link` (`react` and `react-router` are its only imports
 | --- | --- |
 | `RouterLink`, `RouterLinkProps` | React Router's `Link` as a UI library's link component: takes `href` (or `to`), spreads `className`, `children`, `ref` and every anchor prop onto the `<a>`, keeps `Link`'s own props (`replace`, `prefetch`, `reloadDocument`, ...) |
 
-From `@alxia/react-router/fetcher` (`react` is its only import; it renders on the server):
+From `@alxia/react-router/fetcher` (`react` and `react-router` are its imports; it renders on the server):
 
 | export | |
 | --- | --- |
 | `useFetcherAnswer(fetcher, onAnswer?)`, `AnswerSource` | `onAnswer(answer)` once per answer that arrives while the fetcher is idle and differs from the last one seen (the data present at mount counts as seen); the handler is read from a ref; returns the latest answer handed over, `undefined` before the first |
+| `useDebouncedFetcher(value, to, { delayMs?, minLength?, enabled?, key?, keep? }?)`, `DebouncedFetcher`, `DebouncedFetcherOptions`, `DebouncedFetcherState` | a resource route loaded for what is typed: one `fetcher.load` after `delayMs` (250) without a change and from `minLength` (1) trimmed characters; `to` is a URL or `(value) => url`; returns `{ data, stale, state, retry }`: `data` is the answer for the value as it stands, else the previous one with `stale` set; `state` is `'idle' \| 'waiting' \| 'loading' \| 'done'`; `keep(answer)` filters what may stay as the stale answer; `retry()` (stable) asks again at once |
 
 From `@alxia/react-router/subscription` (no import, no peer):
 
@@ -1389,7 +1404,7 @@ The `alxia-react-router` bin, run with `bunx`:
 - [Installable and offline](https://github.com/softistx/alxia/blob/develop/packages/react-router/docs/guide/pwa.md): what the subpaths hold, the worker's contract, the worker, what it caches, the offline page, building the worker with `alxia()` or `buildWorker`, the hooks in React, registering the worker and offering an update, serving the worker's script, the web app manifest, and clearing at sign-out.
 - [An API's refusals](https://github.com/softistx/alxia/blob/develop/packages/react-router/docs/guide/errors.md): what `/errors` holds, recognising an API error, the request id, the page a request is for, the catalogue store, the form checks in the API's words, the provider, wording a refusal, loaders and the error page, actions, JSON actions and CSRF, and keeping the catalogue fresh.
 - [A BFF session](https://github.com/softistx/alxia/blob/develop/packages/react-router/docs/guide/session.md): redirects that stay on the site, the cookies, the sign-in route, the second factor, the viewer and sign-out, the step-up, and the pages a mail's link opens.
-- [A fetcher's fresh answer](https://github.com/softistx/alxia/blob/develop/packages/react-router/docs/guide/fetcher.md): `useFetcherAnswer`: a handler called once per new answer of a keyed fetcher, not for the data it held at mount.
+- [A fetcher's fresh answer](https://github.com/softistx/alxia/blob/develop/packages/react-router/docs/guide/fetcher.md): `useFetcherAnswer`: a handler called once per new answer of a keyed fetcher, not for the data it held at mount; `useDebouncedFetcher`: a resource route loaded for what is typed.
 - [Lists whose state is the URL](https://github.com/softistx/alxia/blob/develop/packages/react-router/docs/guide/lists.md): `useSearchChange`, `useSameRouteLoading`, `usePagedRows`: a search that drops the cursor, a skeleton for the same page reloading, a load-more button.
 - [Subscriptions for a BFF](https://github.com/softistx/alxia/blob/develop/packages/react-router/docs/guide/subscriptions.md): exposing a GraphQL subscription to the browser through a resource route: the allow-list, the session's bearer, the headers, the heartbeat, abort and rate limits.
 - [Troubleshooting](https://github.com/softistx/alxia/blob/develop/packages/react-router/docs/troubleshooting.md): each message, and the traps that print none.

package/dist/fetcher/index.d.ts

@@ -1,7 +1,8 @@
 /**
  * `@alxia/react-router/fetcher`: the hooks around a React Router fetcher's
- * answers. `react` is its only import (a fetcher is read structurally), and
- * every hook renders on the server.
+ * answers. `react` and `react-router` are its imports, and every hook renders
+ * on the server (a load starts in the browser only).
  */
+export { type DebouncedFetcher, type DebouncedFetcherOptions, type DebouncedFetcherState, useDebouncedFetcher, } from './use-debounced-fetcher';
 export { type AnswerSource, useFetcherAnswer } from './use-fetcher-answer';
 //# sourceMappingURL=index.d.ts.map

package/dist/fetcher/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/fetcher/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,KAAK,YAAY,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/fetcher/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACN,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,EAC5B,KAAK,qBAAqB,EAC1B,mBAAmB,GACnB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,KAAK,YAAY,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/fetcher/index.js

@@ -1,12 +1,65 @@
+// src/fetcher/use-debounced-fetcher.ts
+import { useCallback, useEffect, useRef, useState } from "react";
+import { useFetcher } from "react-router";
+function useDebouncedFetcher(value, to, options = {}) {
+  const { delayMs = 250, minLength = 1, enabled = true, key, keep } = options;
+  const keepRef = useRef(keep);
+  keepRef.current = keep;
+  const fetcher = useFetcher(key === undefined ? undefined : { key });
+  const load = useRef(fetcher.load);
+  load.current = fetcher.load;
+  const text = value.trim();
+  const url = enabled && text.length >= minLength ? typeof to === "function" ? to(text) : to : null;
+  const [loaded, setLoaded] = useState(null);
+  const previous = useRef(undefined);
+  useEffect(() => {
+    if (url === null) {
+      previous.current = undefined;
+      setLoaded(null);
+      return;
+    }
+    const timer = setTimeout(() => {
+      setLoaded(url);
+      load.current(url);
+    }, delayMs);
+    return () => clearTimeout(timer);
+  }, [url, text, delayMs]);
+  const current = url !== null && loaded === url && fetcher.state === "idle" && fetcher.data !== undefined;
+  const answer = current ? fetcher.data : undefined;
+  useEffect(() => {
+    if (answer === undefined || answer === null)
+      return;
+    if (keepRef.current?.(answer) ?? true)
+      previous.current = answer;
+  }, [answer]);
+  const data = current ? answer : url === null ? undefined : previous.current;
+  let state;
+  if (url === null)
+    state = "idle";
+  else if (loaded !== url)
+    state = "waiting";
+  else
+    state = fetcher.state === "idle" ? "done" : "loading";
+  const urlRef = useRef(url);
+  urlRef.current = url;
+  const retry = useCallback(() => {
+    const now = urlRef.current;
+    if (now === null)
+      return;
+    setLoaded(now);
+    load.current(now);
+  }, []);
+  return { data, stale: state !== "done" && data !== undefined, state, retry };
+}
 // src/fetcher/use-fetcher-answer.ts
-import { useEffect, useRef, useState } from "react";
+import { useEffect as useEffect2, useRef as useRef2, useState as useState2 } from "react";
 function useFetcherAnswer(fetcher, onAnswer) {
-  const seen = useRef(fetcher.data);
-  const handler = useRef(onAnswer);
+  const seen = useRef2(fetcher.data);
+  const handler = useRef2(onAnswer);
   handler.current = onAnswer;
-  const [latest, setLatest] = useState(undefined);
+  const [latest, setLatest] = useState2(undefined);
   const answer = fetcher.state === "idle" ? fetcher.data : undefined;
-  useEffect(() => {
+  useEffect2(() => {
     if (answer === undefined || answer === null || answer === seen.current) {
       return;
     }
@@ -17,8 +70,9 @@ function useFetcherAnswer(fetcher, onAnswer) {
   return latest;
 }
 export {
+  useDebouncedFetcher,
   useFetcherAnswer
 };
 
-//# debugId=16BED3793BD03C8664756E2164756E21
+//# debugId=FE85A7EF01A4F72B64756E2164756E21
 //# sourceMappingURL=index.js.map

package/dist/fetcher/index.js.map

@@ -1,10 +1,11 @@
 {
   "version": 3,
-  "sources": ["../src/fetcher/use-fetcher-answer.ts"],
+  "sources": ["../src/fetcher/use-debounced-fetcher.ts", "../src/fetcher/use-fetcher-answer.ts"],
   "sourcesContent": [
+    "import { useCallback, useEffect, useRef, useState } from 'react';\nimport { useFetcher } from 'react-router';\n\n/** What `useFetcher<Data>` hands back as `data` (`Data` may be `typeof loader`). */\ntype FetcherData<Data> = ReturnType<typeof useFetcher<Data>>['data'];\n\n/** What `useDebouncedFetcher` is doing for the value typed. */\nexport type DebouncedFetcherState =\n\t/** Nothing to ask: disabled, or the value is shorter than `minLength`. */\n\t| 'idle'\n\t/** The value changed and the pause after the last change is running. */\n\t| 'waiting'\n\t/** The resource route is loading. */\n\t| 'loading'\n\t/** The route answered for the value as it stands. */\n\t| 'done';\n\nexport interface DebouncedFetcherOptions<Data = unknown> {\n\t/** Pause after the last change before the route is asked. Default 250. */\n\treadonly delayMs?: number;\n\t/** The trimmed value must have this many characters. Default 1. */\n\treadonly minLength?: number;\n\t/** `false` asks nothing and forgets the previous answer. Default `true`. */\n\treadonly enabled?: boolean;\n\t/** The fetcher's key, to share it with another component. */\n\treadonly key?: string;\n\t/**\n\t * Which answers may be kept as the stale `data` while the next value waits\n\t * or loads. Default: all. An answer it refuses (a failure) is still `data`\n\t * while it is the current one, but is never shown as the previous one: after a refused answer, the stale\n\t * data is the last *kept* answer, not the refused one.\n\t */\n\treadonly keep?: (data: NonNullable<FetcherData<Data>>) => boolean;\n}\n\nexport interface DebouncedFetcher<Data> {\n\t/**\n\t * The route's answer for the value as it stands, else (`stale`) the last\n\t * answer for an earlier value, kept until the new one lands. `undefined`\n\t * before any answer, and again once the hook goes `idle`.\n\t */\n\treadonly data: FetcherData<Data>;\n\t/** `data` answers an earlier value (or none is current yet). */\n\treadonly stale: boolean;\n\treadonly state: DebouncedFetcherState;\n\t/** Asks the route again for the value as it stands, without waiting. */\n\treadonly retry: () => void;\n}\n\n/**\n * A resource route loaded through a fetcher for a value that changes as the\n * user types. After `delayMs` without a change, and from `minLength`\n * characters, it calls `fetcher.load` once (a newer load cancels the\n * previous one). An answer only counts for the value it was asked for: while\n * a newer value waits or loads, `data` is the previous answer with `stale`\n * set, and an answer for an older value is never returned as current.\n * `to` is the route's URL, or a function of the trimmed value that builds it\n * (a string without a function is loaded as it is, the value being only the\n * trigger). A refusal the route answers as data is `data` like any answer.\n */\nexport function useDebouncedFetcher<Data>(\n\tvalue: string,\n\tto: string | ((value: string) => string),\n\toptions: DebouncedFetcherOptions<Data> = {},\n): DebouncedFetcher<Data> {\n\tconst { delayMs = 250, minLength = 1, enabled = true, key, keep } = options;\n\tconst keepRef = useRef(keep);\n\tkeepRef.current = keep;\n\tconst fetcher = useFetcher<Data>(key === undefined ? undefined : { key });\n\tconst load = useRef(fetcher.load);\n\tload.current = fetcher.load;\n\tconst text = value.trim();\n\tconst url =\n\t\tenabled && text.length >= minLength\n\t\t\t? typeof to === 'function'\n\t\t\t\t? to(text)\n\t\t\t\t: to\n\t\t\t: null;\n\t// The URL the fetcher was last told to load.\n\tconst [loaded, setLoaded] = useState<string | null>(null);\n\tconst previous = useRef<FetcherData<Data>>(undefined);\n\n\t// biome-ignore lint/correctness/useExhaustiveDependencies: the URL and the value are the trigger; `load` is read from a ref\n\tuseEffect(() => {\n\t\tif (url === null) {\n\t\t\tprevious.current = undefined;\n\t\t\tsetLoaded(null);\n\t\t\treturn;\n\t\t}\n\t\tconst timer = setTimeout(() => {\n\t\t\tsetLoaded(url);\n\t\t\tvoid load.current(url);\n\t\t}, delayMs);\n\t\treturn () => clearTimeout(timer);\n\t}, [url, text, delayMs]);\n\n\tconst current =\n\t\turl !== null &&\n\t\tloaded === url &&\n\t\tfetcher.state === 'idle' &&\n\t\tfetcher.data !== undefined;\n\tconst answer = current ? fetcher.data : undefined;\n\tuseEffect(() => {\n\t\tif (answer === undefined || answer === null) return;\n\t\tif (keepRef.current?.(answer) ?? true) previous.current = answer;\n\t}, [answer]);\n\n\tconst data = current ? answer : url === null ? undefined : previous.current;\n\tlet state: DebouncedFetcherState;\n\tif (url === null) state = 'idle';\n\telse if (loaded !== url) state = 'waiting';\n\telse state = fetcher.state === 'idle' ? 'done' : 'loading';\n\n\tconst urlRef = useRef(url);\n\turlRef.current = url;\n\tconst retry = useCallback(() => {\n\t\tconst now = urlRef.current;\n\t\tif (now === null) return;\n\t\tsetLoaded(now);\n\t\tvoid load.current(now);\n\t}, []);\n\treturn { data, stale: state !== 'done' && data !== undefined, state, retry };\n}\n",
     "import { useEffect, useRef, useState } from 'react';\n\n/** What the hook reads of a React Router fetcher. */\nexport interface AnswerSource<Data> {\n\treadonly state: string;\n\treadonly data: Data | undefined;\n}\n\n/**\n * The answers a fetcher gives, one at a time. A keyed fetcher outlives its\n * component, so the data it holds when the component mounts is an earlier\n * visit's, not this one's. `onAnswer` is called once for each answer that\n * arrives while the fetcher is idle and is another object than the last one\n * seen (the data present at mount counts as seen). The handler is read from\n * a ref, so a new function each render never re-fires it. Returns the latest\n * answer handed over, `undefined` until one arrives.\n */\nexport function useFetcherAnswer<Data>(\n\tfetcher: AnswerSource<Data>,\n\tonAnswer?: (answer: Data) => void,\n): Data | undefined {\n\tconst seen = useRef(fetcher.data);\n\tconst handler = useRef(onAnswer);\n\thandler.current = onAnswer;\n\tconst [latest, setLatest] = useState<Data | undefined>(undefined);\n\tconst answer = fetcher.state === 'idle' ? fetcher.data : undefined;\n\tuseEffect(() => {\n\t\tif (answer === undefined || answer === null || answer === seen.current) {\n\t\t\treturn;\n\t\t}\n\t\tseen.current = answer;\n\t\tsetLatest(answer);\n\t\thandler.current?.(answer);\n\t}, [answer]);\n\treturn latest;\n}\n"
   ],
-  "mappings": ";AAAA;AAiBO,SAAS,gBAAsB,CACrC,SACA,UACmB;AAAA,EACnB,MAAM,OAAO,OAAO,QAAQ,IAAI;AAAA,EAChC,MAAM,UAAU,OAAO,QAAQ;AAAA,EAC/B,QAAQ,UAAU;AAAA,EAClB,OAAO,QAAQ,aAAa,SAA2B,SAAS;AAAA,EAChE,MAAM,SAAS,QAAQ,UAAU,SAAS,QAAQ,OAAO;AAAA,EACzD,UAAU,MAAM;AAAA,IACf,IAAI,WAAW,aAAa,WAAW,QAAQ,WAAW,KAAK,SAAS;AAAA,MACvE;AAAA,IACD;AAAA,IACA,KAAK,UAAU;AAAA,IACf,UAAU,MAAM;AAAA,IAChB,QAAQ,UAAU,MAAM;AAAA,KACtB,CAAC,MAAM,CAAC;AAAA,EACX,OAAO;AAAA;",
-  "debugId": "16BED3793BD03C8664756E2164756E21",
+  "mappings": ";AAAA;AACA;AA2DO,SAAS,mBAAyB,CACxC,OACA,IACA,UAAyC,CAAC,GACjB;AAAA,EACzB,QAAQ,UAAU,KAAK,YAAY,GAAG,UAAU,MAAM,KAAK,SAAS;AAAA,EACpE,MAAM,UAAU,OAAO,IAAI;AAAA,EAC3B,QAAQ,UAAU;AAAA,EAClB,MAAM,UAAU,WAAiB,QAAQ,YAAY,YAAY,EAAE,IAAI,CAAC;AAAA,EACxE,MAAM,OAAO,OAAO,QAAQ,IAAI;AAAA,EAChC,KAAK,UAAU,QAAQ;AAAA,EACvB,MAAM,OAAO,MAAM,KAAK;AAAA,EACxB,MAAM,MACL,WAAW,KAAK,UAAU,YACvB,OAAO,OAAO,aACb,GAAG,IAAI,IACP,KACD;AAAA,EAEJ,OAAO,QAAQ,aAAa,SAAwB,IAAI;AAAA,EACxD,MAAM,WAAW,OAA0B,SAAS;AAAA,EAGpD,UAAU,MAAM;AAAA,IACf,IAAI,QAAQ,MAAM;AAAA,MACjB,SAAS,UAAU;AAAA,MACnB,UAAU,IAAI;AAAA,MACd;AAAA,IACD;AAAA,IACA,MAAM,QAAQ,WAAW,MAAM;AAAA,MAC9B,UAAU,GAAG;AAAA,MACR,KAAK,QAAQ,GAAG;AAAA,OACnB,OAAO;AAAA,IACV,OAAO,MAAM,aAAa,KAAK;AAAA,KAC7B,CAAC,KAAK,MAAM,OAAO,CAAC;AAAA,EAEvB,MAAM,UACL,QAAQ,QACR,WAAW,OACX,QAAQ,UAAU,UAClB,QAAQ,SAAS;AAAA,EAClB,MAAM,SAAS,UAAU,QAAQ,OAAO;AAAA,EACxC,UAAU,MAAM;AAAA,IACf,IAAI,WAAW,aAAa,WAAW;AAAA,MAAM;AAAA,IAC7C,IAAI,QAAQ,UAAU,MAAM,KAAK;AAAA,MAAM,SAAS,UAAU;AAAA,KACxD,CAAC,MAAM,CAAC;AAAA,EAEX,MAAM,OAAO,UAAU,SAAS,QAAQ,OAAO,YAAY,SAAS;AAAA,EACpE,IAAI;AAAA,EACJ,IAAI,QAAQ;AAAA,IAAM,QAAQ;AAAA,EAC1B,KAAK,IAAI,WAAW;AAAA,IAAK,QAAQ;AAAA,EACjC;AAAA,IAAK,QAAQ,QAAQ,UAAU,SAAS,SAAS;AAAA,EAEjD,MAAM,SAAS,OAAO,GAAG;AAAA,EACzB,OAAO,UAAU;AAAA,EACjB,MAAM,QAAQ,YAAY,MAAM;AAAA,IAC/B,MAAM,MAAM,OAAO;AAAA,IACnB,IAAI,QAAQ;AAAA,MAAM;AAAA,IAClB,UAAU,GAAG;AAAA,IACR,KAAK,QAAQ,GAAG;AAAA,KACnB,CAAC,CAAC;AAAA,EACL,OAAO,EAAE,MAAM,OAAO,UAAU,UAAU,SAAS,WAAW,OAAO,MAAM;AAAA;;ACzH5E,sBAAS,sBAAW,qBAAQ;AAiBrB,SAAS,gBAAsB,CACrC,SACA,UACmB;AAAA,EACnB,MAAM,OAAO,QAAO,QAAQ,IAAI;AAAA,EAChC,MAAM,UAAU,QAAO,QAAQ;AAAA,EAC/B,QAAQ,UAAU;AAAA,EAClB,OAAO,QAAQ,aAAa,UAA2B,SAAS;AAAA,EAChE,MAAM,SAAS,QAAQ,UAAU,SAAS,QAAQ,OAAO;AAAA,EACzD,WAAU,MAAM;AAAA,IACf,IAAI,WAAW,aAAa,WAAW,QAAQ,WAAW,KAAK,SAAS;AAAA,MACvE;AAAA,IACD;AAAA,IACA,KAAK,UAAU;AAAA,IACf,UAAU,MAAM;AAAA,IAChB,QAAQ,UAAU,MAAM;AAAA,KACtB,CAAC,MAAM,CAAC;AAAA,EACX,OAAO;AAAA;",
+  "debugId": "FE85A7EF01A4F72B64756E2164756E21",
   "names": []
 }

package/dist/fetcher/use-debounced-fetcher.d.ts

@@ -0,0 +1,57 @@
+import { useFetcher } from 'react-router';
+/** What `useFetcher<Data>` hands back as `data` (`Data` may be `typeof loader`). */
+type FetcherData<Data> = ReturnType<typeof useFetcher<Data>>['data'];
+/** What `useDebouncedFetcher` is doing for the value typed. */
+export type DebouncedFetcherState = 
+/** Nothing to ask: disabled, or the value is shorter than `minLength`. */
+'idle'
+/** The value changed and the pause after the last change is running. */
+ | 'waiting'
+/** The resource route is loading. */
+ | 'loading'
+/** The route answered for the value as it stands. */
+ | 'done';
+export interface DebouncedFetcherOptions<Data = unknown> {
+    /** Pause after the last change before the route is asked. Default 250. */
+    readonly delayMs?: number;
+    /** The trimmed value must have this many characters. Default 1. */
+    readonly minLength?: number;
+    /** `false` asks nothing and forgets the previous answer. Default `true`. */
+    readonly enabled?: boolean;
+    /** The fetcher's key, to share it with another component. */
+    readonly key?: string;
+    /**
+     * Which answers may be kept as the stale `data` while the next value waits
+     * or loads. Default: all. An answer it refuses (a failure) is still `data`
+     * while it is the current one, but is never shown as the previous one: after a refused answer, the stale
+     * data is the last *kept* answer, not the refused one.
+     */
+    readonly keep?: (data: NonNullable<FetcherData<Data>>) => boolean;
+}
+export interface DebouncedFetcher<Data> {
+    /**
+     * The route's answer for the value as it stands, else (`stale`) the last
+     * answer for an earlier value, kept until the new one lands. `undefined`
+     * before any answer, and again once the hook goes `idle`.
+     */
+    readonly data: FetcherData<Data>;
+    /** `data` answers an earlier value (or none is current yet). */
+    readonly stale: boolean;
+    readonly state: DebouncedFetcherState;
+    /** Asks the route again for the value as it stands, without waiting. */
+    readonly retry: () => void;
+}
+/**
+ * A resource route loaded through a fetcher for a value that changes as the
+ * user types. After `delayMs` without a change, and from `minLength`
+ * characters, it calls `fetcher.load` once (a newer load cancels the
+ * previous one). An answer only counts for the value it was asked for: while
+ * a newer value waits or loads, `data` is the previous answer with `stale`
+ * set, and an answer for an older value is never returned as current.
+ * `to` is the route's URL, or a function of the trimmed value that builds it
+ * (a string without a function is loaded as it is, the value being only the
+ * trigger). A refusal the route answers as data is `data` like any answer.
+ */
+export declare function useDebouncedFetcher<Data>(value: string, to: string | ((value: string) => string), options?: DebouncedFetcherOptions<Data>): DebouncedFetcher<Data>;
+export {};
+//# sourceMappingURL=use-debounced-fetcher.d.ts.map

package/dist/fetcher/use-debounced-fetcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-debounced-fetcher.d.ts","sourceRoot":"","sources":["../../src/fetcher/use-debounced-fetcher.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE1C,oFAAoF;AACpF,KAAK,WAAW,CAAC,IAAI,IAAI,UAAU,CAAC,OAAO,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;AAErE,+DAA+D;AAC/D,MAAM,MAAM,qBAAqB;AAChC,0EAA0E;AACxE,MAAM;AACR,wEAAwE;GACtE,SAAS;AACX,qCAAqC;GACnC,SAAS;AACX,qDAAqD;GACnD,MAAM,CAAC;AAEV,MAAM,WAAW,uBAAuB,CAAC,IAAI,GAAG,OAAO;IACtD,0EAA0E;IAC1E,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,mEAAmE;IACnE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,6DAA6D;IAC7D,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,KAAK,OAAO,CAAC;CAClE;AAED,MAAM,WAAW,gBAAgB,CAAC,IAAI;IACrC;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC,IAAI,CAAC,CAAC;IACjC,gEAAgE;IAChE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,qBAAqB,CAAC;IACtC,wEAAwE;IACxE,QAAQ,CAAC,KAAK,EAAE,MAAM,IAAI,CAAC;CAC3B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EACvC,KAAK,EAAE,MAAM,EACb,EAAE,EAAE,MAAM,GAAG,CAAC,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC,EACxC,OAAO,GAAE,uBAAuB,CAAC,IAAI,CAAM,GACzC,gBAAgB,CAAC,IAAI,CAAC,CA0DxB"}

package/docs/README.md

@@ -21,7 +21,7 @@ installable and usable offline, wording an API's refusals, the BFF session, a Gr
 | [An API's refusals](guide/errors.md) | wording a GraphQL API's refusals for the pages: recognising an `ApiError`, the request id, the page a request is for, the catalogue store, the form checks in the API's words, the provider, and the loaders, the error page and the actions that answer with it, the JSON actions with their CSRF check and fetcher hook, calling the API from a loader (`apiCallFailure`), and keeping the catalogue fresh (`@alxia/react-router/errors`) |
 | [A BFF session](guide/session.md) | redirecting after sign-in to a page of the site and nowhere else, the sign-in pages' paths, the session's cookies, the sign-in flow (where an answer lands, a refused code, the viewer, sign-out; `@alxia/react-router/session`), the pages a mail's link opens (a magic link, a password reset: `authLinks`), the page's hooks (sign-out, a mail link's parameter, a one-code field; `@alxia/react-router/session/react`), the step-up route's signed-out handling (`onSignedOut`), and the step-up's state and the props it gives the UI (`@alxia/react-router/session/model`) |
 | [Links through React Router](guide/link.md) | `RouterLink`, React Router's `Link` as the link component of a UI library that hands `href` and spreads anchor props; `@alxia/react-router/link` |
-| [A fetcher's fresh answer](guide/fetcher.md) | `useFetcherAnswer`, a handler called once per new answer of a keyed fetcher, not for the data it held at mount; `@alxia/react-router/fetcher` |
+| [A fetcher's fresh answer](guide/fetcher.md) | `useFetcherAnswer`, a handler called once per new answer of a keyed fetcher, not for the data it held at mount; `useDebouncedFetcher`, a resource route loaded for what is typed (pause, minimum length, stale answer kept, retry); `@alxia/react-router/fetcher` |
 | [Lists whose state is the URL](guide/lists.md) | a search and filters in the address bar that drop the cursor (`useSearchChange`), a skeleton while the same page reloads (`useSameRouteLoading`), and a load-more button that appends pages by cursor and keeps the rows when one fails (`usePagedRows`); `@alxia/react-router/lists` |
 | [Subscriptions for a BFF](guide/subscriptions.md) | showing a GraphQL subscription in the browser without giving it the API's token or a way to write a document: a resource route with a map of operation names to the server's documents, the same-site check, the bearer from the session, extra upstream headers, a heartbeat, abort propagation, size limits and a 429 passed through with `retryAfter` (`@alxia/react-router/subscription`) |
 | [Troubleshooting](troubleshooting.md) | something went wrong and you have the message, or a page streams, hydrates or reads its context unlike you expected |

package/docs/guide/fetcher.md

@@ -4,9 +4,11 @@ A page that posts JSON through a keyed fetcher (`useJsonFetcher('save')`) often
 reacts to each answer once: a toast, a form error. A keyed fetcher outlives its
 component, so its data from an earlier visit is still there when the component
 mounts again, and a plain `useEffect` on `fetcher.data` reacts to it as if it
-were new. `@alxia/react-router/fetcher` holds the hook that tells them apart.
-`react` is its only import (the fetcher is read structurally), and it renders
-on the server.
+were new. `@alxia/react-router/fetcher` holds the hook that tells them apart
+(`useFetcherAnswer`, which reads the fetcher structurally) and the one that
+loads a resource route for what the user types (`useDebouncedFetcher`, below).
+`react` is its only import, plus `react-router` for `useDebouncedFetcher`, and
+both render on the server.
 
 ```tsx
 import { useJsonFetcher } from '@alxia/react-router/errors';
@@ -38,3 +40,59 @@ export function SaveForm() {
   two objects are two answers, and so is a reloading `fetcher.load`, which
   hands a new object each time. An answer that comes back as the object seen
   before (A, B, then A again) is a new answer once B was seen.
+
+## Typeahead: `useDebouncedFetcher(value, to, options?)`
+
+A search box, a suggestion list or a preview loads a resource route for what
+the user types. The pattern is always the same: wait for a pause after the last
+keystroke, ask from a minimum length, never act on an answer for older words,
+keep the previous answer on screen while the next one loads, offer a retry.
+
+```tsx
+import { useDebouncedFetcher } from '@alxia/react-router/fetcher';
+
+type SuggestAnswer = { items: string[] } | { failed: true };
+
+export function Suggestions({ typed }: { typed: string }) {
+	const { data, stale, state, retry } = useDebouncedFetcher<SuggestAnswer>(
+		typed,
+		(q) => `/suggest?${new URLSearchParams({ q })}`,
+		{ minLength: 2, delayMs: 250, keep: (answer) => !('failed' in answer) },
+	);
+	if (state === 'idle') return null;
+	return (
+		<div aria-busy={state !== 'done'} style={{ opacity: stale ? 0.5 : 1 }}>
+			{data && 'items' in data ? <List items={data.items} /> : <Spinner />}
+			{data && 'failed' in data ? <button onClick={retry}>Try again</button> : null}
+		</div>
+	);
+}
+```
+
+- `value` is the text typed; it is trimmed, and nothing is asked below
+  `minLength` (default 1). `to` is the route's URL, or a function of the
+  trimmed value that builds it (a plain string is loaded as it is, the value
+  only triggering it).
+- After `delayMs` (default 250) without a change, one `fetcher.load` is made;
+  a newer load cancels the previous one.
+- `data` is the route's answer for the value as it stands. While a newer value
+  waits or loads it is the previous answer and `stale` is `true`; an answer
+  for an older value is never returned as current. It is `undefined` before
+  the first answer and again once the hook is `idle`.
+- `state` is `'idle'` (disabled or too short), `'waiting'` (the pause is
+  running), `'loading'` or `'done'`.
+- `retry()` asks again for the value as it stands, without the pause; it is
+  the same function on every render. The route answers `{ failed: true }` on a
+  failure (for example with `orFailed` from `/lists`) rather than throwing,
+  which is what gives the retry button something to show (see
+  [troubleshooting](../troubleshooting.md)).
+- `keep(answer)` (default: keep all) decides which answers may stay as the
+  stale `data` while the next value waits or loads; refuse the failed ones so
+  a failure is shown once, as the current answer, never dimmed as a previous
+  one. After a refused answer, the stale data is the last *kept* answer, not
+  the refused one.
+- A refusal the route answers as data (`{ failed: true }`) is `data` like any
+  answer. A route that throws goes to the route's error boundary, as with any
+  fetcher.
+- `enabled: false` asks nothing and forgets the previous answer (a closed
+  dialog); `key` shares the fetcher with another component.

package/docs/troubleshooting.md

@@ -584,6 +584,25 @@ export async function loader({ request }: Route.LoaderArgs) {
 
 The rows stay, `error` is `true`, and `loadMore` retries.
 
+### A debounced load lands on the route's `ErrorBoundary`
+
+**When:** the resource route behind `useDebouncedFetcher` throws (or throws a `Response`) and the whole page is replaced by its `ErrorBoundary` instead of showing the previous suggestions with a retry.
+
+**Why:** React Router sends the error of a fetcher's load to the route's boundary. `useDebouncedFetcher` only sees what the fetcher answers, so a failure it can show with `retry` has to be an answer.
+
+**Fix:** answer `{ failed: true }` instead of throwing, for example with `orFailed(q, run)` from `@alxia/react-router/lists` (any non-empty value as its first argument makes it answer `{ failed: true }` on an error), and pass `keep` so a failure is never shown as the previous answer:
+
+```ts
+export function loader({ request }: Route.LoaderArgs) {
+	const q = new URL(request.url).searchParams.get('q');
+	return orFailed(q, () => suggest(q));
+}
+// in the component
+const { data, retry } = useDebouncedFetcher<typeof loader>(typed, toUrl, {
+	keep: (answer) => !('failed' in answer),
+});
+```
+
 ### The client's files are served uncompressed
 
 A response for a script, a stylesheet or an SVG has no `Content-Encoding`,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@alxia/react-router",
-	"version": "0.31.1",
+	"version": "0.32.0",
 	"description": "alxia as the server of a React Router framework app: server rendering behind the app's hooks, loaders reading its typed context, the client's assets served; the code with no UI an installable app shares (`/pwa`), its hooks (`/pwa/react`), `noCache` for the worker's script (`/pwa/server`), the service worker on Workbox (`/pwa/worker`) and its build (`/pwa/build`), an API's refusals worded for the page (`/errors`), the BFF session: cookies, sign-in, step-up and mail links (`/session`), its page hooks (`/session/react`) and what it shares with the page (`/session/model`), a GraphQL subscription relayed to the browser over SSE (`/subscription`), the page's CSP nonce and inline boot scripts (`/document`) and a streaming `entry.server` (`/entry`)",
 	"license": "MIT",
 	"type": "module",