@alxia/react-router 0.19.0 → 0.20.0

package/README.md

@@ -92,7 +92,7 @@ Vite's preview server, as `bun run start` would: the pages, `/api`, the
 client's files and the app's middlewares. So does React Router's prerendering.
 
 `@alxia/core` and `react-router` 8 are peers, and `vite` 7 or 8 is an
-optional peer, for `/vite`; `react` 19 is an optional peer, for `/pwa/react`. The six `workbox-*`
+optional peer, for `/vite`; `react` 19 is an optional peer, for `/pwa/react` and `/lists`. The six `workbox-*`
 packages (`workbox-core`, `workbox-expiration`, `workbox-navigation-preload`,
 `workbox-precaching`, `workbox-routing`, `workbox-strategies`) are optional
 peers too, for `/pwa/worker` (the [PWA section](#installable-and-offline-pwa) has the install line). `/errors` imports `react-router`, a required peer that is already installed. The package declares no dependency.
@@ -1019,6 +1019,58 @@ export const action = events.action; // POST
 See the [subscription guide](https://github.com/softistx/alxia/blob/develop/packages/react-router/docs/guide/subscriptions.md)
 for the rules, the options and the errors.
 
+## A list whose state is the URL
+
+`@alxia/react-router/lists` (`react` and `react-router` are its only imports; every hook renders on the server)
+holds the three hooks a search, filters and a "load more" button need.
+
+```tsx
+// app/routes/users.tsx
+import { usePagedRows, useSameRouteLoading, useSearchChange } from '@alxia/react-router/lists';
+import type { Route } from './+types/users';
+
+const USERS = Array.from({ length: 45 }, (_, i) => `user ${i + 1}`);
+
+// ?q=<search>&after=<cursor>: 20 rows a page, `next` is null on the last one
+export function loader({ request }: Route.LoaderArgs) {
+	const url = new URL(request.url);
+	const q = url.searchParams.get('q') ?? '';
+	const start = Number(url.searchParams.get('after') ?? 0);
+	const found = USERS.filter((name) => name.includes(q));
+	const rows = found.slice(start, start + 20);
+	return { rows, next: start + 20 < found.length ? String(start + 20) : null };
+}
+
+export default function Users({ loaderData }: Route.ComponentProps) {
+	const change = useSearchChange(); // drops ?after on every change
+	const reloading = useSameRouteLoading(); // another search of this page: show the skeleton
+	const { rows, next, loading, error, loadMore } = usePagedRows(loaderData, (page) => page.rows);
+	return (
+		<main>
+			<input type="search" placeholder="Search" onChange={(event) => change({ q: event.target.value || null })} />
+			{reloading ? (
+				<p>Loading…</p>
+			) : (
+				<ul>
+					{rows.map((name) => (
+						<li key={name}>{name}</li>
+					))}
+				</ul>
+			)}
+			{error ? <p role="alert">The next rows could not be loaded.</p> : null}
+			{next ? (
+				<button type="button" disabled={loading} onClick={loadMore}>
+					{error ? 'Retry' : 'Load more'}
+				</button>
+			) : null}
+		</main>
+	);
+}
+```
+
+The loader answers `?after=<cursor>` with the next page. A loader that throws on a cursor request lands on the route's `ErrorBoundary`: see [troubleshooting](https://github.com/softistx/alxia/blob/develop/packages/react-router/docs/troubleshooting.md). See the
+[lists guide](https://github.com/softistx/alxia/blob/develop/packages/react-router/docs/guide/lists.md).
+
 ## Traps
 
 - **A context key made in `app/` reaches the loaders only through the
@@ -1223,6 +1275,14 @@ From `@alxia/react-router/entry`:
 | `createEntry({ streamTimeout?, nonce?, isBot?, onError? })`, `EntryOptions`, `Entry` | `/entry`: `{ handleRequest, streamTimeout }` (`Entry`), `entry.server.tsx` for Bun on the web stream renderer |
 | `handleRequest`, `streamTimeout`, `HandleRequest` | `/entry`: the default entry (`createEntry()`), its `5_000` and the type of `handleRequest` (assignable to React Router's `ServerEntryModule['default']`) |
 
+From `@alxia/react-router/lists` (`react` and `react-router` are its only imports; every hook renders on the server):
+
+| export | |
+| --- | --- |
+| `useSearchChange({ resetKeys? })`, `SearchChangeOptions` | `(changes) => void`: sets a parameter given a string, deletes one given `null` or `undefined`, and deletes `resetKeys` (default `['after']`); the history entry is replaced and the scroll position kept |
+| `useSameRouteLoading()` | `true` while a navigation is loading and its pathname is the current one (another search of the list), `false` for any other page |
+| `usePagedRows(firstPage, rowsOf, { cursorParam?, nextOf? }?)`, `PagedRows`, `PagedRowsOptions` | `{ rows, next, loading, error, loadMore }`: appends the pages the same route answers to `?<cursorParam>=<next>` (default `after`, `nextOf` default `page.next`) through `useFetcher`; starts over when `firstPage` is another object; a failure keeps the rows and sets `error` (an answer that is not a page), and data that is not a page is ignored |
+
 From `@alxia/react-router/subscription` (no import, no peer):
 
 | export | |
@@ -1247,6 +1307,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.
+- [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.
 - [Roadmap](https://github.com/softistx/alxia/blob/develop/packages/react-router/docs/roadmap.md): what is coming, and what is not planned.

package/dist/lists/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `@alxia/react-router/lists`: the hooks of a list screen whose state is the
+ * URL (a search, filters, a cursor). `react` and `react-router` are its only
+ * imports, and every hook renders on the server.
+ */
+export { DEFAULT_CURSOR_PARAM, type PagedRows, type PagedRowsOptions, usePagedRows, } from './use-paged-rows';
+export { useSameRouteLoading } from './use-same-route-loading';
+export { type SearchChangeOptions, useSearchChange } from './use-search-change';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/lists/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACN,oBAAoB,EACpB,KAAK,SAAS,EACd,KAAK,gBAAgB,EACrB,YAAY,GACZ,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,EAAE,KAAK,mBAAmB,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/lists/index.js

@@ -0,0 +1,126 @@
+// src/lists/use-paged-rows.ts
+import { useCallback, useEffect, useRef, useState } from "react";
+import { useFetcher, useLocation } from "react-router";
+var DEFAULT_CURSOR_PARAM = "after";
+function restart(first, nextOf) {
+  return { first, extra: [], next: nextOf(first) ?? null, error: false };
+}
+function readPage(value, rowsOf, nextOf) {
+  if (typeof value !== "object" || value === null)
+    return;
+  try {
+    const rows = rowsOf(value);
+    const next = nextOf(value);
+    if (!Array.isArray(rows))
+      return;
+    if (next !== null && typeof next !== "string")
+      return;
+    return { rows, next };
+  } catch {
+    return;
+  }
+}
+function settle(previous, first, more, nextOf) {
+  const base = previous.first === first ? previous : restart(first, nextOf);
+  if (more === undefined)
+    return { ...base, error: true };
+  return {
+    ...base,
+    extra: [...base.extra, ...more.rows],
+    next: more.next,
+    error: false
+  };
+}
+function usePagedRows(firstPage, rowsOf, options = {}) {
+  const cursorParam = options.cursorParam ?? DEFAULT_CURSOR_PARAM;
+  const nextOf = options.nextOf ?? ((page) => page.next);
+  const fetcher = useFetcher();
+  const { pathname, search } = useLocation();
+  const [loaded, setLoaded] = useState(() => restart(firstPage, nextOf));
+  const asked = useRef(null);
+  const current = loaded.first === firstPage ? loaded : restart(firstPage, nextOf);
+  useEffect(() => {
+    const request = asked.current;
+    if (request === null)
+      return;
+    if (fetcher.state !== "idle") {
+      request.started = true;
+      return;
+    }
+    if (!request.started && fetcher.data === request.seen)
+      return;
+    asked.current = null;
+    if (request.first !== firstPage)
+      return;
+    const more = fetcher.data === request.seen ? undefined : readPage(fetcher.data, rowsOf, nextOf);
+    setLoaded((previous) => settle(previous, firstPage, more, nextOf));
+  }, [fetcher.state, fetcher.data, firstPage]);
+  const next = current.next;
+  const busy = fetcher.state !== "idle";
+  const { load } = fetcher;
+  const loadMore = useCallback(() => {
+    if (next === null || busy)
+      return;
+    const params = new URLSearchParams(search);
+    params.set(cursorParam, next);
+    asked.current = { first: firstPage, seen: fetcher.data, started: false };
+    setLoaded({ ...current, error: false });
+    load(`${pathname}?${params}`);
+  }, [
+    next,
+    busy,
+    search,
+    cursorParam,
+    firstPage,
+    fetcher.data,
+    current,
+    pathname,
+    load
+  ]);
+  return {
+    rows: [...rowsOf(firstPage), ...current.extra],
+    next,
+    loading: busy,
+    error: current.error,
+    loadMore
+  };
+}
+// src/lists/use-same-route-loading.ts
+import { useLocation as useLocation2, useNavigation } from "react-router";
+function useSameRouteLoading() {
+  const navigation = useNavigation();
+  const { pathname } = useLocation2();
+  return navigation.state === "loading" && navigation.location.pathname === pathname;
+}
+// src/lists/use-search-change.ts
+import { useCallback as useCallback2 } from "react";
+import { useSearchParams } from "react-router";
+var RESET_KEYS = [DEFAULT_CURSOR_PARAM];
+function useSearchChange(options = {}) {
+  const [, setSearchParams] = useSearchParams();
+  const resetKeys = options.resetKeys ?? RESET_KEYS;
+  const joined = resetKeys.join("\x00");
+  return useCallback2((changes) => {
+    setSearchParams((current) => {
+      const next = new URLSearchParams(current);
+      for (const [key, value] of Object.entries(changes)) {
+        if (value === null || value === undefined)
+          next.delete(key);
+        else
+          next.set(key, value);
+      }
+      for (const key of joined === "" ? [] : joined.split("\x00"))
+        next.delete(key);
+      return next;
+    }, { replace: true, preventScrollReset: true });
+  }, [setSearchParams, joined]);
+}
+export {
+  DEFAULT_CURSOR_PARAM,
+  usePagedRows,
+  useSameRouteLoading,
+  useSearchChange
+};
+
+//# debugId=D936887B843025CD64756E2164756E21
+//# sourceMappingURL=index.js.map

package/dist/lists/index.js.map

@@ -0,0 +1,12 @@
+{
+  "version": 3,
+  "sources": ["../src/lists/use-paged-rows.ts", "../src/lists/use-same-route-loading.ts", "../src/lists/use-search-change.ts"],
+  "sourcesContent": [
+    "import { useCallback, useEffect, useRef, useState } from 'react';\nimport { useFetcher, useLocation } from 'react-router';\n\nexport interface PagedRowsOptions<Page> {\n\t/** The search parameter that carries the cursor (default `after`). */\n\treadonly cursorParam?: string;\n\t/** The cursor of the page after this one, `null` at the end (default `page.next`). */\n\treadonly nextOf?: (page: Page) => string | null;\n}\n\nexport interface PagedRows<Row> {\n\t/** The first page's rows, then the rows of each page loaded after it. */\n\treadonly rows: readonly Row[];\n\t/** The cursor of the next page, `null` when there is none. */\n\treadonly next: string | null;\n\t/** A page is being fetched. */\n\treadonly loading: boolean;\n\t/**\n\t * The last `loadMore` ended with nothing usable (the route answered something\n\t * that is not a page). The rows stay; call `loadMore` again to retry. The\n\t * next `loadMore` clears it.\n\t */\n\treadonly error: boolean;\n\t/** Fetches the page after the last one; nothing when there is none or one is on its way. */\n\treadonly loadMore: () => void;\n}\n\n/** The default cursor parameter, shared with `useSearchChange`'s default `resetKeys`. */\nexport const DEFAULT_CURSOR_PARAM = 'after';\n\ninterface Loaded<Page, Row> {\n\treadonly first: Page;\n\treadonly extra: readonly Row[];\n\treadonly next: string | null;\n\treadonly error: boolean;\n}\n\ntype NextOf<Page> = (page: Page) => string | null;\n\n/** The state for a first page: nothing loaded after it yet. */\nfunction restart<Page, Row>(\n\tfirst: Page,\n\tnextOf: NextOf<Page>,\n): Loaded<Page, Row> {\n\treturn { first, extra: [], next: nextOf(first) ?? null, error: false };\n}\n\n/**\n * The rows and cursor of `value` when it is a page (an object whose rows are\n * an array and whose cursor is a string or `null`), else `undefined`.\n */\nfunction readPage<Page, Row>(\n\tvalue: unknown,\n\trowsOf: (page: Page) => readonly Row[],\n\tnextOf: NextOf<Page>,\n): { rows: readonly Row[]; next: string | null } | undefined {\n\tif (typeof value !== 'object' || value === null) return undefined;\n\ttry {\n\t\tconst rows = rowsOf(value as Page);\n\t\tconst next = nextOf(value as Page);\n\t\tif (!Array.isArray(rows)) return undefined;\n\t\tif (next !== null && typeof next !== 'string') return undefined;\n\t\treturn { rows, next };\n\t} catch {\n\t\treturn undefined;\n\t}\n}\n\n/** The state after an answer: its rows appended, or `error` when it was not a page. */\nfunction settle<Page, Row>(\n\tprevious: Loaded<Page, Row>,\n\tfirst: Page,\n\tmore: { rows: readonly Row[]; next: string | null } | undefined,\n\tnextOf: NextOf<Page>,\n): Loaded<Page, Row> {\n\tconst base =\n\t\tprevious.first === first ? previous : restart<Page, Row>(first, nextOf);\n\tif (more === undefined) return { ...base, error: true };\n\treturn {\n\t\t...base,\n\t\textra: [...base.extra, ...more.rows],\n\t\tnext: more.next,\n\t\terror: false,\n\t};\n}\n\n/**\n * Appends the pages a \"load more\" asks of the route the page is on. The\n * route's loader answers `?<cursorParam>=<next>` with the next page, through\n * `useFetcher`, so the address bar and the page's own data stay as they are.\n *\n * - It starts over whenever `firstPage` is another object (a new search, a\n *   revalidation): the rows are the new first page's alone, in that very\n *   render. A page still on its way for the old one is dropped.\n * - A failed load keeps the rows and sets `error`. A thrown loader error goes\n *   to the route's `ErrorBoundary` as React Router always does; `error` covers\n *   an answer that is not a page, such as `data({ message }, { status: 503 })`\n *   or `null`.\n * - Data of the fetcher that is not a page (no rows, or no cursor) is ignored.\n */\nexport function usePagedRows<Page, Row>(\n\tfirstPage: Page,\n\trowsOf: (page: Page) => readonly Row[],\n\toptions: PagedRowsOptions<Page> = {},\n): PagedRows<Row> {\n\tconst cursorParam = options.cursorParam ?? DEFAULT_CURSOR_PARAM;\n\tconst nextOf: NextOf<Page> =\n\t\toptions.nextOf ??\n\t\t((page) => (page as { next?: string | null }).next as string | null);\n\tconst fetcher = useFetcher();\n\tconst { pathname, search } = useLocation();\n\tconst [loaded, setLoaded] = useState(() =>\n\t\trestart<Page, Row>(firstPage, nextOf),\n\t);\n\t// What was asked, and for which first page, so an answer that comes after a restart is dropped.\n\tconst asked = useRef<{ first: Page; seen: unknown; started: boolean } | null>(\n\t\tnull,\n\t);\n\tconst current =\n\t\tloaded.first === firstPage ? loaded : restart<Page, Row>(firstPage, nextOf);\n\n\t// Deliberate deps: rowsOf and nextOf are usually inline functions, new on\n\t// every render, and are read at the time of the answer; the effect must run\n\t// on the fetcher's settling, not on each render.\n\tuseEffect(() => {\n\t\tconst request = asked.current;\n\t\tif (request === null) return;\n\t\tif (fetcher.state !== 'idle') {\n\t\t\trequest.started = true;\n\t\t\treturn;\n\t\t}\n\t\t// Idle: the answer is in when the fetcher was seen busy, or when its data\n\t\t// is no longer the one it had at the call (an answer within one batch).\n\t\tif (!request.started && fetcher.data === request.seen) return;\n\t\tasked.current = null;\n\t\tif (request.first !== firstPage) return;\n\t\tconst more =\n\t\t\tfetcher.data === request.seen\n\t\t\t\t? undefined\n\t\t\t\t: readPage(fetcher.data, rowsOf, nextOf);\n\t\tsetLoaded((previous) => settle(previous, firstPage, more, nextOf));\n\t}, [fetcher.state, fetcher.data, firstPage]);\n\n\tconst next = current.next;\n\tconst busy = fetcher.state !== 'idle';\n\tconst { load } = fetcher;\n\tconst loadMore = useCallback(() => {\n\t\tif (next === null || busy) return;\n\t\tconst params = new URLSearchParams(search);\n\t\tparams.set(cursorParam, next);\n\t\tasked.current = { first: firstPage, seen: fetcher.data, started: false };\n\t\tsetLoaded({ ...current, error: false });\n\t\tvoid load(`${pathname}?${params}`);\n\t}, [\n\t\tnext,\n\t\tbusy,\n\t\tsearch,\n\t\tcursorParam,\n\t\tfirstPage,\n\t\tfetcher.data,\n\t\tcurrent,\n\t\tpathname,\n\t\tload,\n\t]);\n\n\treturn {\n\t\trows: [...rowsOf(firstPage), ...current.extra],\n\t\tnext,\n\t\tloading: busy,\n\t\terror: current.error,\n\t\tloadMore,\n\t};\n}\n",
+    "import { useLocation, useNavigation } from 'react-router';\n\n/**\n * `true` while a navigation is loading and goes to the pathname the page is\n * on: another search of this list, not another page. It stays `false` for a\n * navigation elsewhere (and when idle), so a list can show its skeleton\n * without flashing on a click that leaves it.\n */\nexport function useSameRouteLoading(): boolean {\n\tconst navigation = useNavigation();\n\tconst { pathname } = useLocation();\n\treturn (\n\t\tnavigation.state === 'loading' && navigation.location.pathname === pathname\n\t);\n}\n",
+    "import { useCallback } from 'react';\nimport { useSearchParams } from 'react-router';\nimport { DEFAULT_CURSOR_PARAM } from './use-paged-rows';\n\nexport interface SearchChangeOptions {\n\t/**\n\t * The parameters dropped by every change, because they only mean something\n\t * for the search they were read from (default `['after']`, a cursor).\n\t */\n\treadonly resetKeys?: readonly string[];\n}\n\nconst RESET_KEYS: readonly string[] = [DEFAULT_CURSOR_PARAM];\n\n/**\n * Returns `(changes) => void`: sets the parameters it is given a value for,\n * deletes the ones given `null` or `undefined` (an empty string is a value,\n * so it is set), and deletes `resetKeys` in\n * the same step. It replaces the history entry and keeps the scroll position.\n */\nexport function useSearchChange(\n\toptions: SearchChangeOptions = {},\n): (changes: Record<string, string | null | undefined>) => void {\n\tconst [, setSearchParams] = useSearchParams();\n\tconst resetKeys = options.resetKeys ?? RESET_KEYS;\n\tconst joined = resetKeys.join('\\u0000');\n\treturn useCallback(\n\t\t(changes) => {\n\t\t\tsetSearchParams(\n\t\t\t\t(current) => {\n\t\t\t\t\tconst next = new URLSearchParams(current);\n\t\t\t\t\tfor (const [key, value] of Object.entries(changes)) {\n\t\t\t\t\t\tif (value === null || value === undefined) next.delete(key);\n\t\t\t\t\t\telse next.set(key, value);\n\t\t\t\t\t}\n\t\t\t\t\tfor (const key of joined === '' ? [] : joined.split('\\u0000'))\n\t\t\t\t\t\tnext.delete(key);\n\t\t\t\t\treturn next;\n\t\t\t\t},\n\t\t\t\t{ replace: true, preventScrollReset: true },\n\t\t\t);\n\t\t},\n\t\t[setSearchParams, joined],\n\t);\n}\n"
+  ],
+  "mappings": "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",
+  "debugId": "D936887B843025CD64756E2164756E21",
+  "names": []
+}

package/dist/lists/use-paged-rows.d.ts

@@ -0,0 +1,40 @@
+export interface PagedRowsOptions<Page> {
+    /** The search parameter that carries the cursor (default `after`). */
+    readonly cursorParam?: string;
+    /** The cursor of the page after this one, `null` at the end (default `page.next`). */
+    readonly nextOf?: (page: Page) => string | null;
+}
+export interface PagedRows<Row> {
+    /** The first page's rows, then the rows of each page loaded after it. */
+    readonly rows: readonly Row[];
+    /** The cursor of the next page, `null` when there is none. */
+    readonly next: string | null;
+    /** A page is being fetched. */
+    readonly loading: boolean;
+    /**
+     * The last `loadMore` ended with nothing usable (the route answered something
+     * that is not a page). The rows stay; call `loadMore` again to retry. The
+     * next `loadMore` clears it.
+     */
+    readonly error: boolean;
+    /** Fetches the page after the last one; nothing when there is none or one is on its way. */
+    readonly loadMore: () => void;
+}
+/** The default cursor parameter, shared with `useSearchChange`'s default `resetKeys`. */
+export declare const DEFAULT_CURSOR_PARAM = "after";
+/**
+ * Appends the pages a "load more" asks of the route the page is on. The
+ * route's loader answers `?<cursorParam>=<next>` with the next page, through
+ * `useFetcher`, so the address bar and the page's own data stay as they are.
+ *
+ * - It starts over whenever `firstPage` is another object (a new search, a
+ *   revalidation): the rows are the new first page's alone, in that very
+ *   render. A page still on its way for the old one is dropped.
+ * - A failed load keeps the rows and sets `error`. A thrown loader error goes
+ *   to the route's `ErrorBoundary` as React Router always does; `error` covers
+ *   an answer that is not a page, such as `data({ message }, { status: 503 })`
+ *   or `null`.
+ * - Data of the fetcher that is not a page (no rows, or no cursor) is ignored.
+ */
+export declare function usePagedRows<Page, Row>(firstPage: Page, rowsOf: (page: Page) => readonly Row[], options?: PagedRowsOptions<Page>): PagedRows<Row>;
+//# sourceMappingURL=use-paged-rows.d.ts.map

package/dist/lists/use-paged-rows.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-paged-rows.d.ts","sourceRoot":"","sources":["../../src/lists/use-paged-rows.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,gBAAgB,CAAC,IAAI;IACrC,sEAAsE;IACtE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,sFAAsF;IACtF,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,MAAM,GAAG,IAAI,CAAC;CAChD;AAED,MAAM,WAAW,SAAS,CAAC,GAAG;IAC7B,yEAAyE;IACzE,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,EAAE,CAAC;IAC9B,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,+BAA+B;IAC/B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,4FAA4F;IAC5F,QAAQ,CAAC,QAAQ,EAAE,MAAM,IAAI,CAAC;CAC9B;AAED,yFAAyF;AACzF,eAAO,MAAM,oBAAoB,UAAU,CAAC;AA0D5C;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,GAAG,EACrC,SAAS,EAAE,IAAI,EACf,MAAM,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,SAAS,GAAG,EAAE,EACtC,OAAO,GAAE,gBAAgB,CAAC,IAAI,CAAM,GAClC,SAAS,CAAC,GAAG,CAAC,CAoEhB"}

package/dist/lists/use-same-route-loading.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `true` while a navigation is loading and goes to the pathname the page is
+ * on: another search of this list, not another page. It stays `false` for a
+ * navigation elsewhere (and when idle), so a list can show its skeleton
+ * without flashing on a click that leaves it.
+ */
+export declare function useSameRouteLoading(): boolean;
+//# sourceMappingURL=use-same-route-loading.d.ts.map

package/dist/lists/use-same-route-loading.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-same-route-loading.d.ts","sourceRoot":"","sources":["../../src/lists/use-same-route-loading.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,wBAAgB,mBAAmB,IAAI,OAAO,CAM7C"}

package/dist/lists/use-search-change.d.ts

@@ -0,0 +1,15 @@
+export interface SearchChangeOptions {
+    /**
+     * The parameters dropped by every change, because they only mean something
+     * for the search they were read from (default `['after']`, a cursor).
+     */
+    readonly resetKeys?: readonly string[];
+}
+/**
+ * Returns `(changes) => void`: sets the parameters it is given a value for,
+ * deletes the ones given `null` or `undefined` (an empty string is a value,
+ * so it is set), and deletes `resetKeys` in
+ * the same step. It replaces the history entry and keeps the scroll position.
+ */
+export declare function useSearchChange(options?: SearchChangeOptions): (changes: Record<string, string | null | undefined>) => void;
+//# sourceMappingURL=use-search-change.d.ts.map

package/dist/lists/use-search-change.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-search-change.d.ts","sourceRoot":"","sources":["../../src/lists/use-search-change.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,mBAAmB;IACnC;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC;AAID;;;;;GAKG;AACH,wBAAgB,eAAe,CAC9B,OAAO,GAAE,mBAAwB,GAC/B,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,KAAK,IAAI,CAsB9D"}

package/docs/README.md

@@ -20,6 +20,7 @@ installable and usable offline, wording an API's refusals, the BFF session, a Gr
 | [Installable and offline](guide/pwa.md) | making the app installable and usable offline: the subpaths of `@alxia/react-router/pwa`, the service worker (`startWorker`, `/pwa/worker`), its build by `alxia()` or `buildWorker` (`/pwa/build`), its contract and cache names, which requests the worker caches and which responses it stores, the precache list read from a build, or clearing the caches at sign-out |
 | [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`), and the step-up's state and the props it gives the UI (`@alxia/react-router/session/model`) |
+| [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 |
 | [Roadmap](roadmap.md) | wondering what is coming, and what is not planned |

package/docs/guide/lists.md

@@ -0,0 +1,111 @@
+# Lists whose state is the URL
+
+A list screen of a BFF keeps its state in the address bar: `?q=ana&status=open`
+for a search and filters, `?after=<cursor>` for the page. The loader reads it;
+the screen changes it. `@alxia/react-router/lists` holds the three hooks every
+such screen needs. `react` and `react-router` are its only imports, so it adds
+no peer beyond those, and every hook renders on the server.
+
+```tsx
+import {
+	usePagedRows,
+	useSameRouteLoading,
+	useSearchChange,
+} from '@alxia/react-router/lists';
+```
+
+## The loader
+
+One loader serves the first page and the next ones. It reads the cursor and
+answers `{ items, next }`, `next` being `null` on the last page:
+
+```ts
+export async function loader({ request }: Route.LoaderArgs) {
+	const url = new URL(request.url);
+	return {
+		page: await listUsers({
+			q: url.searchParams.get('q') ?? '',
+			after: url.searchParams.get('after'),
+		}),
+	};
+}
+```
+
+## `useSearchChange`
+
+```tsx
+const change = useSearchChange(); // resetKeys: ['after']
+
+<input onChange={(event) => change({ q: event.target.value || null })} />;
+<Select onChange={(status) => change({ status })} />;
+```
+
+`change(changes)` sets each parameter given a string, deletes each given
+`null` or `undefined` (an empty string is a value, so it is kept as `?q=`),
+and deletes `resetKeys` in the same step: a new search makes the old cursor
+meaningless. It navigates with `replace: true` and `preventScrollReset: true`,
+so typing does not fill the history nor jump the page. Pass
+`{ resetKeys: ['after', 'page'] }` to drop more.
+
+## `useSameRouteLoading`
+
+```tsx
+const reloading = useSameRouteLoading();
+return reloading ? <Skeleton /> : <Table rows={rows} />;
+```
+
+`true` while a navigation is loading **and** its pathname is the page's own: a
+new search of this list. A click on a link to another page stays `false`, so
+the list does not flash a skeleton on the way out.
+
+## `usePagedRows`
+
+```tsx
+const { rows, next, loading, error, loadMore } = usePagedRows(
+	loaderData.page,
+	(page) => page.items,
+);
+
+<Button disabled={!next || loading} onClick={loadMore}>
+	{error ? 'Retry' : 'Load more'}
+</Button>;
+```
+
+| option | default | |
+| --- | --- | --- |
+| `cursorParam` | `'after'` | the search parameter carrying the cursor |
+| `nextOf` | `page.next` | the cursor after a page, `null` at the end |
+
+- `loadMore()` asks the **same route** for `?<cursorParam>=<next>`, keeping the
+  rest of the search, through `useFetcher`: the address bar and the page's
+  data do not change. It does nothing at the end or while a page is on its way.
+- `rows` is the first page's rows followed by every page loaded after it.
+- **It starts over** when `firstPage` is another object, which is what the
+  loader gives after a new search or a revalidation. The new first page's rows
+  are the ones rendered, with no frame of stale rows, and a page still on its
+  way for the old search is dropped.
+- **A failure keeps the rows.** When the route answers something that is not a
+  page (`null`, or `data({ message }, { status: 503 })`), `error` is `true` and
+  `next` is unchanged, so the same button retries. The next `loadMore` clears
+  it. Fetcher data that is not a page (no rows, or a `next` that is neither a string nor `null`) sets `error`, like a failed page.
+
+### Another cursor parameter
+
+```ts
+// the loader answers { items, cursor } for ?q=&page=<cursor>
+const { rows, next, loadMore } = usePagedRows(
+	loaderData.page,
+	(page) => page.items,
+	{ cursorParam: 'page', nextOf: (page) => page.cursor },
+);
+const change = useSearchChange({ resetKeys: ['page'] });
+```
+
+`cursorParam` and `useSearchChange`'s `resetKeys` must name the same
+parameter: with the defaults both are `after` (`DEFAULT_CURSOR_PARAM`), and
+with another one a search that keeps the old cursor shows the wrong page.
+
+A loader that **throws** on a cursor request is not an `error` here: React
+Router sends a fetcher's thrown error to the route's `ErrorBoundary`. To offer
+a retry instead, catch in the loader for a request that has the cursor and
+answer a value that is not a page.

package/docs/roadmap.md

@@ -22,6 +22,13 @@ number on it. Every release, with each change it made, is in
   upstream with the client and passes a 429 on with `retryAfter`. See the
   [subscriptions guide](guide/subscriptions.md).
 
+- **`@alxia/react-router/lists`: hooks for lists whose state is the URL.**
+  `useSearchChange` (set or delete search parameters and drop the cursor),
+  `useSameRouteLoading` (another search of the same page is loading) and
+  `usePagedRows` (append the pages a load-more asks of the same loader, start
+  over on a new first page, keep the rows when a page fails). See the
+  [lists guide](guide/lists.md).
+
 ## Next
 
 Nothing planned.

package/docs/troubleshooting.md

@@ -533,6 +533,28 @@ them.
 inside a folder is served by that folder's `static` route, whatever its
 name.
 
+### A "load more" lands on the route's `ErrorBoundary`
+
+**When:** the loader throws (or throws a `Response`) for a request that has the cursor, and the page used `usePagedRows`: the whole route is replaced by its `ErrorBoundary` instead of showing the rows with a retry button.
+
+**Why:** React Router sends the error of a fetcher's load to the route's boundary. `usePagedRows` only sees what the fetcher answers, so its `error` is `true` for an answer that is not a page, not for a throw.
+
+**Fix:** catch in the loader for a request that has the cursor and answer a value that is not a page:
+
+```ts
+export async function loader({ request }: Route.LoaderArgs) {
+	const url = new URL(request.url);
+	try {
+		return await listUsers(url.searchParams);
+	} catch (error) {
+		if (url.searchParams.has('after')) return { message: 'unavailable' };
+		throw error;
+	}
+}
+```
+
+The rows stay, `error` is `true`, and `loadMore` retries.
+
 ### `Refused to execute inline script because it violates the following Content Security Policy directive: "default-src 'none'"`
 
 The browser's console prints it; the page renders on the server, then

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@alxia/react-router",
-	"version": "0.19.0",
+	"version": "0.20.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",
@@ -82,6 +82,11 @@
 			"import": "./dist/session/model/index.js",
 			"default": "./dist/session/model/index.js"
 		},
+		"./lists": {
+			"types": "./dist/lists/index.d.ts",
+			"import": "./dist/lists/index.js",
+			"default": "./dist/lists/index.js"
+		},
 		"./subscription": {
 			"types": "./dist/subscription/index.d.ts",
 			"import": "./dist/subscription/index.js",
@@ -115,6 +120,7 @@
 			"src/session/index.ts",
 			"src/session/react/index.ts",
 			"src/subscription/index.ts",
+			"src/lists/index.ts",
 			"src/document/index.ts",
 			"src/entry/index.ts",
 			"src/pwa/worker/index.ts",