@alxia/react-router 0.40.0 → 0.41.0

package/README.md

@@ -1175,6 +1175,25 @@ const { data, stale, state, retry } = useDebouncedFetcher<Found>(
 );
 ```
 
+A screen with no real-time channel reads its data again every N ms, **only while the page is visible**, and at once when a hidden page comes back after more than N ms:
+
+```tsx
+import { useFetcher } from 'react-router';
+import {
+	useVisibleInterval,
+	useVisibleRevalidation,
+} from '@alxia/react-router/fetcher';
+
+// inside a component: the route's loaders, every minute
+useVisibleRevalidation(60_000);
+
+// any callback, such as a fetcher's load; `enabled: false` pauses it
+const fetcher = useFetcher<Counts>();
+useVisibleInterval(() => void fetcher.load('/counts'), 300_000, {
+	enabled: !menuOpen,
+});
+```
+
 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
@@ -1475,6 +1494,8 @@ From `@alxia/react-router/fetcher` (`react` and `react-router` are its imports;
 | `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 |
 | `useFetcherPromise(fetcher, { refusal? }?)`, `FetcherPromiseOptions`, `FetcherPromiseAborted` | returns a stable `run(submit)` that calls `submit` (`() => fetcher.submit(...)`) and returns a Promise settled by the fetcher's next new answer: resolved with it, or rejected with an `Error` when `refusal(answer)` returns a message (or your own `Error`); an answer held before the call never settles it; a second `run` while one is pending rejects the older with `FetcherPromiseAborted` (`reason: 'superseded'`); an unmount rejects the pending one (`'unmounted'`); a `submit` that throws rejects with its error |
 | `useFormRefusal(result)`, `FormRefusalResult` | `useFormRefusal(fetcher.data)` returns the `FormErrors` of a fetcher answer that carries `fieldErrors` (`apiErrors.formRefusal`'s), `undefined` for no answer, a done step or a refusal without them; stable for one answer |
+| `useVisibleInterval(callback, ms, { enabled?, runOnVisible? }?)`, `VisibleIntervalOptions` | runs `callback` every `ms` only while `document.visibilityState` is `'visible'` (a tick while hidden is skipped); when a hidden page becomes visible after at least `ms` since the last run it runs at once (`runOnVisible`, default `true`); `enabled: false` stops it; the callback is read from a ref, so a new function never restarts the timer; the timer and listener are cleared on unmount; nothing starts on the server |
+| `useVisibleRevalidation(ms, { enabled? }?)` | `useVisibleInterval` over `useRevalidator`: revalidates the route's loaders every `ms` while the page is visible, skipping a tick while a revalidation is in flight |
 | `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):
@@ -1501,7 +1522,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; `useFetcherPromise`: one submission's answer as a Promise; `useDebouncedFetcher`: a resource route loaded for what is typed.
+- [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; `useFetcherPromise`: one submission's answer as a Promise; `useDebouncedFetcher`: a resource route loaded for what is typed; `useVisibleInterval` and `useVisibleRevalidation`: a callback or a revalidation on an interval while the page is visible.
 - [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,10 +1,13 @@
 /**
  * `@alxia/react-router/fetcher`: the hooks around a React Router fetcher's
- * answers. `react` and `react-router` are its imports, and every hook renders
- * on the server (a load starts in the browser only).
+ * answers, and the ones that keep a screen fresh while its page is visible.
+ * `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';
 export { FetcherPromiseAborted, type FetcherPromiseOptions, useFetcherPromise, } from './use-fetcher-promise';
 export { type FormRefusalResult, useFormRefusal } from './use-form-refusal';
+export { useVisibleInterval, type VisibleIntervalOptions, } from './use-visible-interval';
+export { useVisibleRevalidation } from './use-visible-revalidation';
 //# 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,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;AAC3E,OAAO,EACN,qBAAqB,EACrB,KAAK,qBAAqB,EAC1B,iBAAiB,GACjB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,KAAK,iBAAiB,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/fetcher/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;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;AAC3E,OAAO,EACN,qBAAqB,EACrB,KAAK,qBAAqB,EAC1B,iBAAiB,GACjB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,KAAK,iBAAiB,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAC5E,OAAO,EACN,kBAAkB,EAClB,KAAK,sBAAsB,GAC3B,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC"}

package/dist/fetcher/index.js

@@ -154,13 +154,52 @@ function useFormRefusal(result) {
     formError: result.error || undefined
   } : undefined, [result]);
 }
+// src/fetcher/use-visible-interval.ts
+import { useEffect as useEffect4, useRef as useRef4 } from "react";
+function useVisibleInterval(callback, ms, options = {}) {
+  const { enabled = true, runOnVisible = true } = options;
+  const latest = useRef4(callback);
+  latest.current = callback;
+  useEffect4(() => {
+    if (!enabled || ms <= 0)
+      return;
+    let last = Date.now();
+    const run = () => {
+      if (document.visibilityState !== "visible")
+        return;
+      last = Date.now();
+      latest.current();
+    };
+    const timer = setInterval(run, ms);
+    const back = () => {
+      if (runOnVisible && Date.now() - last >= ms)
+        run();
+    };
+    document.addEventListener("visibilitychange", back);
+    return () => {
+      clearInterval(timer);
+      document.removeEventListener("visibilitychange", back);
+    };
+  }, [ms, enabled, runOnVisible]);
+}
+// src/fetcher/use-visible-revalidation.ts
+import { useRevalidator } from "react-router";
+function useVisibleRevalidation(ms, options) {
+  const revalidator = useRevalidator();
+  useVisibleInterval(() => {
+    if (revalidator.state === "idle")
+      revalidator.revalidate();
+  }, ms, options);
+}
 export {
   FetcherPromiseAborted,
   useDebouncedFetcher,
   useFetcherAnswer,
   useFetcherPromise,
-  useFormRefusal
+  useFormRefusal,
+  useVisibleInterval,
+  useVisibleRevalidation
 };
 
-//# debugId=6FFF1F15C0AB3E6F64756E2164756E21
+//# debugId=70FA37428A43B8C264756E2164756E21
 //# sourceMappingURL=index.js.map

package/dist/fetcher/index.js.map

@@ -1,13 +1,15 @@
 {
   "version": 3,
-  "sources": ["../src/fetcher/use-debounced-fetcher.ts", "../src/fetcher/use-fetcher-answer.ts", "../src/fetcher/use-fetcher-promise.ts", "../src/fetcher/use-form-refusal.ts"],
+  "sources": ["../src/fetcher/use-debounced-fetcher.ts", "../src/fetcher/use-fetcher-answer.ts", "../src/fetcher/use-fetcher-promise.ts", "../src/fetcher/use-form-refusal.ts", "../src/fetcher/use-visible-interval.ts", "../src/fetcher/use-visible-revalidation.ts"],
   "sourcesContent": [
     "import {\n\tstartTransition,\n\tuseCallback,\n\tuseEffect,\n\tuseLayoutEffect,\n\tuseRef,\n\tuseState,\n} 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\t// React Router applies the fetcher's `loading` state in a transition, so\n\t// right after `load()` a render can still show `idle` and the previous\n\t// answer. A load has landed only once the fetcher was seen busy for that very load (the load number is kept, so a busy render of a superseded load does not count), or\n\t// its `load()` promise settled and a transition queued after it committed\n\t// (a fast load whose busy state was never rendered, or a route answering\n\t// the very same object twice). `seq` numbers the loads, so a superseded\n\t// one never counts.\n\tconst seq = useRef(0);\n\tconst [settled, setSettled] = useState(0);\n\tconst busySeq = useRef(0);\n\tuseLayoutEffect(() => {\n\t\tif (fetcher.state !== 'idle') busySeq.current = seq.current;\n\t}, [fetcher.state]);\n\tconst ask = (target: string) => {\n\t\tconst mine = ++seq.current;\n\t\tsetLoaded(target);\n\t\tvoid Promise.resolve(load.current(target)).then(() => {\n\t\t\tif (mine === seq.current) startTransition(() => setSettled(mine));\n\t\t});\n\t};\n\tconst askRef = useRef(ask);\n\taskRef.current = ask;\n\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\taskRef.current(url);\n\t\t}, delayMs);\n\t\treturn () => clearTimeout(timer);\n\t}, [url, text, delayMs]);\n\n\tconst landed =\n\t\tfetcher.state === 'idle' &&\n\t\t(busySeq.current === seq.current || settled === seq.current);\n\tconst current =\n\t\turl !== null && loaded === url && landed && fetcher.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 = landed ? '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\taskRef.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",
     "import { useCallback, useEffect, useRef } from 'react';\nimport { type AnswerSource, useFetcherAnswer } from './use-fetcher-answer';\n\n/** What `useFetcherPromise` accepts. */\nexport interface FetcherPromiseOptions<Data> {\n\t/**\n\t * Decides whether an answer is a refusal: the message (or the `Error`) the\n\t * promise rejects with, `undefined` to resolve with the answer. Read from a\n\t * ref, so a new function each render is fine. Without it every answer\n\t * resolves.\n\t */\n\trefusal?: (answer: Data) => string | Error | undefined;\n}\n\n/** The rejection of a call replaced by a newer one, or cut off by an unmount. */\nexport class FetcherPromiseAborted extends Error {\n\toverride readonly name = 'FetcherPromiseAborted';\n\treadonly reason: 'superseded' | 'unmounted';\n\tconstructor(reason: 'superseded' | 'unmounted') {\n\t\tsuper(\n\t\t\treason === 'superseded'\n\t\t\t\t? 'useFetcherPromise: a newer call replaced this one before the fetcher answered'\n\t\t\t\t: 'useFetcherPromise: the component unmounted before the fetcher answered',\n\t\t);\n\t\tthis.reason = reason;\n\t}\n}\n\ninterface Waiting<Data> {\n\tresolve(answer: Data): void;\n\treject(error: unknown): void;\n}\n\n/**\n * Ties one submission to its answer. `run(submit)` calls `submit` (usually\n * `() => fetcher.submit(...)`) and returns a Promise settled by the fetcher's\n * next new answer (see `useFetcherAnswer`): it resolves with the answer, or\n * rejects with an `Error` when `options.refusal` returns a message for it. An\n * answer the fetcher already held when `run` was called never settles it.\n *\n * A second `run` while one is pending rejects the older promise with a\n * `FetcherPromiseAborted` (`'superseded'`) and waits for the answer to the\n * newer one. An unmount rejects the pending promise with a\n * `FetcherPromiseAborted` (`'unmounted'`). A `submit` that throws (or whose\n * promise rejects) rejects the promise with that error, and so does a\n * `refusal` that throws. `run` is stable.\n *\n * Catch every promise `run` returns: an abort rejects it, and one nobody\n * handles is an unhandled rejection. Ignore the aborts with\n * `.catch((e) => { if (!(e instanceof FetcherPromiseAborted)) throw e; })`.\n */\nexport function useFetcherPromise<Data>(\n\tfetcher: AnswerSource<Data>,\n\toptions: FetcherPromiseOptions<Data> = {},\n): (submit: () => void | Promise<unknown>) => Promise<Data> {\n\tconst waiting = useRef<Waiting<Data> | null>(null);\n\tconst refusal = useRef(options.refusal);\n\trefusal.current = options.refusal;\n\n\tuseFetcherAnswer(fetcher, (answer) => {\n\t\tconst pending = waiting.current;\n\t\tif (!pending) return;\n\t\twaiting.current = null;\n\t\tlet refused: string | Error | undefined;\n\t\ttry {\n\t\t\trefused = refusal.current?.(answer);\n\t\t} catch (error) {\n\t\t\tpending.reject(error);\n\t\t\treturn;\n\t\t}\n\t\tif (refused === undefined) pending.resolve(answer);\n\t\telse\n\t\t\tpending.reject(\n\t\t\t\ttypeof refused === 'string' ? new Error(refused) : refused,\n\t\t\t);\n\t});\n\n\tuseEffect(\n\t\t() => () => {\n\t\t\tconst pending = waiting.current;\n\t\t\twaiting.current = null;\n\t\t\tpending?.reject(new FetcherPromiseAborted('unmounted'));\n\t\t},\n\t\t[],\n\t);\n\n\treturn useCallback((submit) => {\n\t\twaiting.current?.reject(new FetcherPromiseAborted('superseded'));\n\t\treturn new Promise<Data>((resolve, reject) => {\n\t\t\tconst mine: Waiting<Data> = { resolve, reject };\n\t\t\twaiting.current = mine;\n\t\t\tconst fail = (error: unknown) => {\n\t\t\t\tif (waiting.current === mine) waiting.current = null;\n\t\t\t\treject(error);\n\t\t\t};\n\t\t\ttry {\n\t\t\t\tPromise.resolve(submit()).catch(fail);\n\t\t\t} catch (error) {\n\t\t\t\tfail(error);\n\t\t\t}\n\t\t});\n\t}, []);\n}\n",
-    "import { useMemo } from 'react';\nimport type { FormErrors } from '../errors/form-errors';\n\n/**\n * What a form's fetcher answers: a done step (`ok: true`), or a refusal\n * (`formRefusal`, or `fetcherResult` with its `error`) that may carry the\n * form's field errors.\n */\nexport type FormRefusalResult =\n\t| { ok: true }\n\t| { ok?: false; fieldErrors?: Record<string, string>; error?: string };\n\n/**\n * The refusal of a form's last answer as its `FormErrors`: `undefined` for\n * no answer, a done step, or a refusal with no `fieldErrors` (a toast's\n * message, not the form's). Stable for one answer.\n */\nexport function useFormRefusal(\n\tresult: FormRefusalResult | undefined,\n): FormErrors | undefined {\n\treturn useMemo(\n\t\t() =>\n\t\t\tresult && !result.ok && result.fieldErrors\n\t\t\t\t? {\n\t\t\t\t\t\tfieldErrors: result.fieldErrors,\n\t\t\t\t\t\tformError: result.error || undefined,\n\t\t\t\t\t}\n\t\t\t\t: undefined,\n\t\t[result],\n\t);\n}\n"
+    "import { useMemo } from 'react';\nimport type { FormErrors } from '../errors/form-errors';\n\n/**\n * What a form's fetcher answers: a done step (`ok: true`), or a refusal\n * (`formRefusal`, or `fetcherResult` with its `error`) that may carry the\n * form's field errors.\n */\nexport type FormRefusalResult =\n\t| { ok: true }\n\t| { ok?: false; fieldErrors?: Record<string, string>; error?: string };\n\n/**\n * The refusal of a form's last answer as its `FormErrors`: `undefined` for\n * no answer, a done step, or a refusal with no `fieldErrors` (a toast's\n * message, not the form's). Stable for one answer.\n */\nexport function useFormRefusal(\n\tresult: FormRefusalResult | undefined,\n): FormErrors | undefined {\n\treturn useMemo(\n\t\t() =>\n\t\t\tresult && !result.ok && result.fieldErrors\n\t\t\t\t? {\n\t\t\t\t\t\tfieldErrors: result.fieldErrors,\n\t\t\t\t\t\tformError: result.error || undefined,\n\t\t\t\t\t}\n\t\t\t\t: undefined,\n\t\t[result],\n\t);\n}\n",
+    "import { useEffect, useRef } from 'react';\n\nexport interface VisibleIntervalOptions {\n\t/** `false` stops the timer. Default `true`. */\n\treadonly enabled?: boolean;\n\t/**\n\t * Run the callback as soon as a hidden page becomes visible again, when at\n\t * least the interval has passed since its last run. Default `true`.\n\t */\n\treadonly runOnVisible?: boolean;\n}\n\n/**\n * Runs `callback` every `ms` **only while the page is visible**\n * (`document.visibilityState`), for a screen that has no real-time channel\n * (a revalidation, a fetcher's `load`). A tick that fires while the page is\n * hidden is skipped; when the page becomes visible again after at least `ms`\n * since the last run, the callback runs at once (`runOnVisible`); a page that\n * comes back sooner waits for the next tick. The timer and the listener are\n * cleared on unmount and while `enabled` is false. `ms` must be positive.\n *\n * The callback is read from a ref: a new function each render never restarts\n * the timer, and the latest one runs. Skipping a read already in flight is the\n * callback's to decide. On the server nothing starts (effects do not run).\n */\nexport function useVisibleInterval(\n\tcallback: () => void,\n\tms: number,\n\toptions: VisibleIntervalOptions = {},\n): void {\n\tconst { enabled = true, runOnVisible = true } = options;\n\tconst latest = useRef(callback);\n\tlatest.current = callback;\n\n\tuseEffect(() => {\n\t\tif (!enabled || ms <= 0) return;\n\t\tlet last = Date.now();\n\t\tconst run = () => {\n\t\t\tif (document.visibilityState !== 'visible') return;\n\t\t\tlast = Date.now();\n\t\t\tlatest.current();\n\t\t};\n\t\tconst timer = setInterval(run, ms);\n\t\tconst back = () => {\n\t\t\tif (runOnVisible && Date.now() - last >= ms) run();\n\t\t};\n\t\tdocument.addEventListener('visibilitychange', back);\n\t\treturn () => {\n\t\t\tclearInterval(timer);\n\t\t\tdocument.removeEventListener('visibilitychange', back);\n\t\t};\n\t}, [ms, enabled, runOnVisible]);\n}\n",
+    "import { useRevalidator } from 'react-router';\nimport {\n\tuseVisibleInterval,\n\ttype VisibleIntervalOptions,\n} from './use-visible-interval';\n\n/**\n * Runs the current route's loaders again every `ms`, **only while the page is\n * visible**, and at once when a hidden page comes back after more than `ms`\n * (`useVisibleInterval` over React Router's `useRevalidator`). A revalidation\n * already in flight is not doubled. `enabled: false` stops it (a menu is open,\n * a change is in flight).\n */\nexport function useVisibleRevalidation(\n\tms: number,\n\toptions?: Pick<VisibleIntervalOptions, 'enabled'>,\n): void {\n\tconst revalidator = useRevalidator();\n\tuseVisibleInterval(\n\t\t() => {\n\t\t\tif (revalidator.state === 'idle') void revalidator.revalidate();\n\t\t},\n\t\tms,\n\t\toptions,\n\t);\n}\n"
   ],
-  "mappings": "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",
-  "debugId": "6FFF1F15C0AB3E6F64756E2164756E21",
+  "mappings": "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",
+  "debugId": "70FA37428A43B8C264756E2164756E21",
   "names": []
 }

package/dist/fetcher/use-visible-interval.d.ts

@@ -0,0 +1,24 @@
+export interface VisibleIntervalOptions {
+    /** `false` stops the timer. Default `true`. */
+    readonly enabled?: boolean;
+    /**
+     * Run the callback as soon as a hidden page becomes visible again, when at
+     * least the interval has passed since its last run. Default `true`.
+     */
+    readonly runOnVisible?: boolean;
+}
+/**
+ * Runs `callback` every `ms` **only while the page is visible**
+ * (`document.visibilityState`), for a screen that has no real-time channel
+ * (a revalidation, a fetcher's `load`). A tick that fires while the page is
+ * hidden is skipped; when the page becomes visible again after at least `ms`
+ * since the last run, the callback runs at once (`runOnVisible`); a page that
+ * comes back sooner waits for the next tick. The timer and the listener are
+ * cleared on unmount and while `enabled` is false. `ms` must be positive.
+ *
+ * The callback is read from a ref: a new function each render never restarts
+ * the timer, and the latest one runs. Skipping a read already in flight is the
+ * callback's to decide. On the server nothing starts (effects do not run).
+ */
+export declare function useVisibleInterval(callback: () => void, ms: number, options?: VisibleIntervalOptions): void;
+//# sourceMappingURL=use-visible-interval.d.ts.map

package/dist/fetcher/use-visible-interval.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-visible-interval.d.ts","sourceRoot":"","sources":["../../src/fetcher/use-visible-interval.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,sBAAsB;IACtC,+CAA+C;IAC/C,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;CAChC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CACjC,QAAQ,EAAE,MAAM,IAAI,EACpB,EAAE,EAAE,MAAM,EACV,OAAO,GAAE,sBAA2B,GAClC,IAAI,CAuBN"}

package/dist/fetcher/use-visible-revalidation.d.ts

@@ -0,0 +1,10 @@
+import { type VisibleIntervalOptions } from './use-visible-interval';
+/**
+ * Runs the current route's loaders again every `ms`, **only while the page is
+ * visible**, and at once when a hidden page comes back after more than `ms`
+ * (`useVisibleInterval` over React Router's `useRevalidator`). A revalidation
+ * already in flight is not doubled. `enabled: false` stops it (a menu is open,
+ * a change is in flight).
+ */
+export declare function useVisibleRevalidation(ms: number, options?: Pick<VisibleIntervalOptions, 'enabled'>): void;
+//# sourceMappingURL=use-visible-revalidation.d.ts.map

package/dist/fetcher/use-visible-revalidation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-visible-revalidation.d.ts","sourceRoot":"","sources":["../../src/fetcher/use-visible-revalidation.ts"],"names":[],"mappings":"AACA,OAAO,EAEN,KAAK,sBAAsB,EAC3B,MAAM,wBAAwB,CAAC;AAEhC;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACrC,EAAE,EAAE,MAAM,EACV,OAAO,CAAC,EAAE,IAAI,CAAC,sBAAsB,EAAE,SAAS,CAAC,GAC/C,IAAI,CASN"}

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` or a REST API's `problemError`, 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, a signed session and a sign-in throttle (`signedSession`, `createSignInThrottle`), 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`, `useFetcherPromise` (one submission's answer as a Promise), 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` |
+| [A fetcher's fresh answer](guide/fetcher.md) | `useFetcherAnswer`, `useFetcherPromise` (one submission's answer as a Promise), 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); `useVisibleInterval` and `useVisibleRevalidation`, a callback or a revalidation on an interval while the page is visible; `@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

@@ -6,9 +6,11 @@ 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
 (`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.
+loads a resource route for what the user types (`useDebouncedFetcher`, below),
+and the ones that read data again while the page is visible
+(`useVisibleInterval`, `useVisibleRevalidation`, below). `react` is its only
+import, plus `react-router` for the hooks that use a fetcher or the
+revalidator, and all render on the server.
 
 ```tsx
 import { useJsonFetcher } from '@alxia/react-router/errors';
@@ -140,3 +142,43 @@ export function Suggestions({ typed }: { typed: string }) {
   fetcher.
 - `enabled: false` asks nothing and forgets the previous answer (a closed
   dialog); `key` shares the fetcher with another component.
+
+## Fresh data while the page is visible: `useVisibleInterval(callback, ms, options?)`
+
+A screen with no real-time channel reads its data again on a timer. The timer
+should run only while the user can see the page, and a page that was hidden
+for a while should not show old data when it comes back.
+
+```tsx
+import { useFetcher } from 'react-router';
+import {
+	useVisibleInterval,
+	useVisibleRevalidation,
+} from '@alxia/react-router/fetcher';
+
+export function Board({ menuOpen }: { menuOpen: boolean }) {
+	// the route's loaders, every minute, never while a menu is open
+	useVisibleRevalidation(60_000, { enabled: !menuOpen });
+
+	// any callback, here a fetcher's load, every five minutes
+	const counts = useFetcher<Counts>();
+	useVisibleInterval(() => void counts.load('/counts'), 300_000);
+	return <Tiles counts={counts.data} />;
+}
+```
+
+- The callback runs every `ms` while `document.visibilityState` is
+  `'visible'`. A tick that fires while the page is hidden is skipped.
+- When a hidden page becomes visible and at least `ms` has passed since the
+  last run, the callback runs at once (`runOnVisible`, default `true`; pass
+  `false` to wait for the next tick). A page that comes back sooner waits for
+  the tick.
+- `enabled: false` stops the timer and removes the listener; `true` again
+  starts a fresh interval.
+- The callback is read from a ref: a new function each render does not
+  restart the timer, and the latest one runs. It decides whether to skip a
+  read already in flight (`fetcher.state`); `useVisibleRevalidation` does so
+  for `useRevalidator`.
+- The timer and the listener are cleared on unmount. On the server nothing
+  starts, since effects do not run there.
+- Changing `ms` restarts the interval. `ms` must be positive.

package/docs/roadmap.md

@@ -88,6 +88,12 @@ Nothing planned.
 
 ### Unreleased
 
+- **`useVisibleInterval` and `useVisibleRevalidation` on `/fetcher`.** A
+  callback, or a revalidation of the route's loaders, runs every N ms only
+  while the page is visible, and at once when a hidden page comes back after
+  more than N ms. See [Fresh data while the page is
+  visible](guide/fetcher.md#fresh-data-while-the-page-is-visible-usevisibleintervalcallback-ms-options).
+
 - **A delay-only global bucket for `createSignInThrottle`.** With
   `globalMode: 'delay'`, `wait` answers per key only and `globalDelay()` gives
   a bounded delay (capped at `maxDelayMs`) that grows with the failures past

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@alxia/react-router",
-	"version": "0.40.0",
+	"version": "0.41.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",