@alxia/react-router 0.16.0 → 0.17.0

package/README.md

@@ -937,8 +937,9 @@ has the rest.
 An app that renders its pages and calls a GraphQL API that signs users in
 with `@nxgt/janus` keeps the API's token in its own HttpOnly cookie.
 `@alxia/react-router/session` holds that session's server side, built on
-`/errors`; `/session/model` imports nothing and is safe in a component.
-Neither adds a peer.
+`/errors`; `/session/react` holds the page's hooks around it (`useSignOut`, `useLinkParam`,
+`useCodeField`); `/session/model` imports nothing and is safe in a component.
+`/session` and `/session/model` add no peer; `/session/react` needs `react`, an optional peer.
 
 ```ts
 // app/session.server.ts
@@ -1137,6 +1138,23 @@ From `@alxia/react-router/session` (`react-router` and `/errors`' files are its
 | `Spent`, `SpendOptions`, `LinkStayed`, `RequestLinkAnswer` | their types |
 | `TOKEN_PAGE_HEADERS` | `Referrer-Policy: no-referrer` and `X-Robots-Tag: noindex, nofollow`, for a page whose URL carries a token |
 
+From `@alxia/react-router/session/react` (`react` and `react-router` are its only imports; every hook renders on the server):
+
+| export | |
+| --- | --- |
+| `useSignOut({ action?, before? })` | `{ signOut, busy }`: posts `{}` as JSON to `action` (default `/sign-out`) after `before()`, whose failure never keeps the user signed in; `busy` until the navigation ends |
+| `SIGN_OUT_PATH`, `SignOutOptions`, `signOutAfter(before, submit)` | `/sign-out`, the options, and the step `useSignOut` is built on |
+| `useLinkParam(name, { drop? }?)`, `LinkParamOptions` | a mail link's query parameter, read once (`null` when absent or empty); `drop: true` removes it from the address bar with `history.replaceState` |
+| `useCodeField(schema, refusal)`, `CodeField`, `CodeSchema` | a one-code field with no form library: `{ code, setCode, ref, error, check() }` over a synchronous Standard Schema; each new `refusal` object clears the refused code and focuses the input |
+| `useOnRefusal(refusal, handler)` | the core under it, for any form library: `handler` runs once per new refusal, not for one present at mount |
+
+```tsx
+import { useLinkParam, useSignOut } from '@alxia/react-router/session/react';
+
+const token = useLinkParam('token', { drop: true });
+const { signOut, busy } = useSignOut();
+```
+
 From `@alxia/react-router/session/model` (no import at all):
 
 | export | |

package/dist/session/react/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `@alxia/react-router/session/react`: the hooks of a page around the
+ * session flows `/session` serves: signing out, a mail link's parameter and
+ * a one-code field. `react` and `react-router` are its only imports; it
+ * shares nothing with the server side of `/session`.
+ */
+export { type CodeField, type CodeSchema, useCodeField, useOnRefusal, } from './use-code-field';
+export { type LinkParamOptions, useLinkParam } from './use-link-param';
+export { SIGN_OUT_PATH, type SignOutOptions, signOutAfter, useSignOut, } from './use-sign-out';
+//# sourceMappingURL=index.d.ts.map

package/dist/session/react/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/session/react/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EACN,KAAK,SAAS,EACd,KAAK,UAAU,EACf,YAAY,EACZ,YAAY,GACZ,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,KAAK,gBAAgB,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACvE,OAAO,EACN,aAAa,EACb,KAAK,cAAc,EACnB,YAAY,EACZ,UAAU,GACV,MAAM,gBAAgB,CAAC"}

package/dist/session/react/index.js

@@ -0,0 +1,94 @@
+// src/session/react/use-code-field.ts
+import {
+  useCallback,
+  useEffect,
+  useRef,
+  useState
+} from "react";
+function useOnRefusal(refusal, handler) {
+  const handled = useRef(refusal);
+  const latest = useRef(handler);
+  latest.current = handler;
+  useEffect(() => {
+    if (!refusal || handled.current === refusal)
+      return;
+    handled.current = refusal;
+    latest.current();
+  }, [refusal]);
+}
+function useCodeField(schema, refusal) {
+  const [code, setCodeState] = useState("");
+  const [error, setError] = useState();
+  const ref = useRef(null);
+  const setCode = useCallback((next) => {
+    setCodeState(next);
+    setError(undefined);
+  }, []);
+  useOnRefusal(refusal, () => {
+    setCode("");
+    ref.current?.focus();
+  });
+  const check = () => {
+    const result = schema["~standard"].validate(code);
+    if (result instanceof Promise) {
+      throw new TypeError("useCodeField takes a synchronous schema");
+    }
+    const { issues, value } = result;
+    if (issues?.length) {
+      setError(issues[0]?.message);
+      return;
+    }
+    setError(undefined);
+    return value;
+  };
+  return { code, setCode, ref, error, check };
+}
+// src/session/react/use-link-param.ts
+import { useEffect as useEffect2, useState as useState2 } from "react";
+import { useSearchParams } from "react-router";
+function useLinkParam(name, { drop = false } = {}) {
+  const [params] = useSearchParams();
+  const [value] = useState2(() => params.get(name) || null);
+  useEffect2(() => {
+    if (!drop)
+      return;
+    const url = new URL(window.location.href);
+    if (!url.searchParams.has(name))
+      return;
+    url.searchParams.delete(name);
+    window.history.replaceState(window.history.state, "", `${url.pathname}${url.search}${url.hash}`);
+  }, [drop, name]);
+  return value;
+}
+// src/session/react/use-sign-out.ts
+import { useCallback as useCallback2, useState as useState3 } from "react";
+import { useNavigation, useSubmit } from "react-router";
+var SIGN_OUT_PATH = "/sign-out";
+async function signOutAfter(before, submit) {
+  try {
+    await before?.();
+  } catch {}
+  await submit();
+}
+function useSignOut(options = {}) {
+  const { action = SIGN_OUT_PATH, before } = options;
+  const submit = useSubmit();
+  const [preparing, setPreparing] = useState3(false);
+  const submitting = useNavigation().formAction === action;
+  const signOut = useCallback2(() => {
+    setPreparing(true);
+    signOutAfter(before, () => submit({}, { method: "post", action, encType: "application/json" })).finally(() => setPreparing(false));
+  }, [submit, action, before]);
+  return { signOut, busy: preparing || submitting };
+}
+export {
+  SIGN_OUT_PATH,
+  signOutAfter,
+  useCodeField,
+  useLinkParam,
+  useOnRefusal,
+  useSignOut
+};
+
+//# debugId=26E2FEF9A38E677964756E2164756E21
+//# sourceMappingURL=index.js.map

package/dist/session/react/index.js.map

@@ -0,0 +1,12 @@
+{
+  "version": 3,
+  "sources": ["../src/session/react/use-code-field.ts", "../src/session/react/use-link-param.ts", "../src/session/react/use-sign-out.ts"],
+  "sourcesContent": [
+    "import {\n\ttype RefObject,\n\tuseCallback,\n\tuseEffect,\n\tuseRef,\n\tuseState,\n} from 'react';\n\n/** The part of a Standard Schema (`~standard`) this hook reads; Zod, Valibot and ArkType satisfy it. */\nexport interface CodeSchema {\n\treadonly '~standard': {\n\t\tvalidate(value: unknown): unknown;\n\t};\n}\n\n/**\n * Calls `handler` once for each new `refusal` (a new object each time,\n * `undefined` when there is none). A refusal already there when the\n * component mounted is not new: it is the page's own, seen again.\n * Library-agnostic: pair it with any form library's `reset` and `focus`.\n */\nexport function useOnRefusal(\n\trefusal: object | undefined,\n\thandler: () => void,\n): void {\n\tconst handled = useRef(refusal);\n\tconst latest = useRef(handler);\n\tlatest.current = handler;\n\tuseEffect(() => {\n\t\tif (!refusal || handled.current === refusal) return;\n\t\thandled.current = refusal;\n\t\tlatest.current();\n\t}, [refusal]);\n}\n\nexport interface CodeField {\n\t/** The code typed so far. */\n\treadonly code: string;\n\treadonly setCode: (code: string) => void;\n\t/** On the input, so a refusal can focus it. */\n\treadonly ref: RefObject<HTMLInputElement | null>;\n\t/** The first issue's message of the last `check`, cleared by typing. */\n\treadonly error: string | undefined;\n\t/**\n\t * Validates the code against the schema: the parsed value, or\n\t * `undefined` and `error` set. Synchronous schemas only.\n\t */\n\treadonly check: () => unknown;\n}\n\n/**\n * A one-code field (an authenticator app's code, a recovery code) with no\n * form library: it holds the code, checks it against `schema`, and on each\n * new `refusal` clears the refused code and focuses the input for the next\n * try. With react-hook-form, use `useOnRefusal` and its `setValue` and\n * `setFocus` instead.\n */\nexport function useCodeField(\n\tschema: CodeSchema,\n\trefusal: object | undefined,\n): CodeField {\n\tconst [code, setCodeState] = useState('');\n\tconst [error, setError] = useState<string | undefined>();\n\tconst ref = useRef<HTMLInputElement | null>(null);\n\tconst setCode = useCallback((next: string) => {\n\t\tsetCodeState(next);\n\t\tsetError(undefined);\n\t}, []);\n\tuseOnRefusal(refusal, () => {\n\t\tsetCode('');\n\t\tref.current?.focus();\n\t});\n\tconst check = () => {\n\t\tconst result = schema['~standard'].validate(code);\n\t\tif (result instanceof Promise) {\n\t\t\tthrow new TypeError('useCodeField takes a synchronous schema');\n\t\t}\n\t\tconst { issues, value } = result as {\n\t\t\tissues?: ReadonlyArray<{ message: string }>;\n\t\t\tvalue?: unknown;\n\t\t};\n\t\tif (issues?.length) {\n\t\t\tsetError(issues[0]?.message);\n\t\t\treturn undefined;\n\t\t}\n\t\tsetError(undefined);\n\t\treturn value;\n\t};\n\treturn { code, setCode, ref, error, check };\n}\n",
+    "import { useEffect, useState } from 'react';\nimport { useSearchParams } from 'react-router';\n\nexport interface LinkParamOptions {\n\t/**\n\t * Remove the parameter from the address bar once read\n\t * (`history.replaceState`), so a token is not left in the history, a\n\t * bookmark or a shared screen. Default `false`.\n\t */\n\treadonly drop?: boolean;\n}\n\n/**\n * The query parameter a mail's link carries (`token`, `code`, `state`),\n * read once: the value of the first render is kept for the page's life, so\n * dropping it from the address bar never loses it. `null` when absent or\n * empty. Safe to render on the server, where nothing is dropped.\n */\nexport function useLinkParam(\n\tname: string,\n\t{ drop = false }: LinkParamOptions = {},\n): string | null {\n\tconst [params] = useSearchParams();\n\tconst [value] = useState(() => params.get(name) || null);\n\tuseEffect(() => {\n\t\tif (!drop) return;\n\t\tconst url = new URL(window.location.href);\n\t\tif (!url.searchParams.has(name)) return;\n\t\turl.searchParams.delete(name);\n\t\twindow.history.replaceState(\n\t\t\twindow.history.state,\n\t\t\t'',\n\t\t\t`${url.pathname}${url.search}${url.hash}`,\n\t\t);\n\t}, [drop, name]);\n\treturn value;\n}\n",
+    "import { useCallback, useState } from 'react';\nimport { useNavigation, useSubmit } from 'react-router';\n\n/** Where `signInFlow`'s sign-out action is mounted unless the app says otherwise. */\nexport const SIGN_OUT_PATH = '/sign-out';\n\nexport interface SignOutOptions {\n\t/** The sign-out route (default `/sign-out`). */\n\treadonly action?: string;\n\t/**\n\t * Runs before the post: clear the worker's caches, a local store. A\n\t * rejection never keeps the user signed in: the sign-out goes on.\n\t */\n\treadonly before?: () => Promise<unknown> | unknown;\n}\n\n/**\n * Runs `before`, then `submit`. A `before` that throws or rejects is\n * ignored, so a failed cleanup cannot keep a session alive.\n */\nexport async function signOutAfter(\n\tbefore: (() => Promise<unknown> | unknown) | undefined,\n\tsubmit: () => Promise<void> | void,\n): Promise<void> {\n\ttry {\n\t\tawait before?.();\n\t} catch {\n\t\t// Signing out matters more than the cleanup.\n\t}\n\tawait submit();\n}\n\n/**\n * The one way a page signs out, wherever the control is: posts `{}` as JSON\n * to the sign-out route (same-origin and JSON only, as `signInFlow`'s action\n * requires). `busy` from the call until the navigation it starts has ended.\n */\nexport function useSignOut(options: SignOutOptions = {}): {\n\tsignOut: () => void;\n\tbusy: boolean;\n} {\n\tconst { action = SIGN_OUT_PATH, before } = options;\n\tconst submit = useSubmit();\n\tconst [preparing, setPreparing] = useState(false);\n\tconst submitting = useNavigation().formAction === action;\n\tconst signOut = useCallback(() => {\n\t\tsetPreparing(true);\n\t\tvoid signOutAfter(before, () =>\n\t\t\tsubmit({}, { method: 'post', action, encType: 'application/json' }),\n\t\t).finally(() => setPreparing(false));\n\t}, [submit, action, before]);\n\treturn { signOut, busy: preparing || submitting };\n}\n"
+  ],
+  "mappings": ";AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAqBO,SAAS,YAAY,CAC3B,SACA,SACO;AAAA,EACP,MAAM,UAAU,OAAO,OAAO;AAAA,EAC9B,MAAM,SAAS,OAAO,OAAO;AAAA,EAC7B,OAAO,UAAU;AAAA,EACjB,UAAU,MAAM;AAAA,IACf,IAAI,CAAC,WAAW,QAAQ,YAAY;AAAA,MAAS;AAAA,IAC7C,QAAQ,UAAU;AAAA,IAClB,OAAO,QAAQ;AAAA,KACb,CAAC,OAAO,CAAC;AAAA;AAyBN,SAAS,YAAY,CAC3B,QACA,SACY;AAAA,EACZ,OAAO,MAAM,gBAAgB,SAAS,EAAE;AAAA,EACxC,OAAO,OAAO,YAAY,SAA6B;AAAA,EACvD,MAAM,MAAM,OAAgC,IAAI;AAAA,EAChD,MAAM,UAAU,YAAY,CAAC,SAAiB;AAAA,IAC7C,aAAa,IAAI;AAAA,IACjB,SAAS,SAAS;AAAA,KAChB,CAAC,CAAC;AAAA,EACL,aAAa,SAAS,MAAM;AAAA,IAC3B,QAAQ,EAAE;AAAA,IACV,IAAI,SAAS,MAAM;AAAA,GACnB;AAAA,EACD,MAAM,QAAQ,MAAM;AAAA,IACnB,MAAM,SAAS,OAAO,aAAa,SAAS,IAAI;AAAA,IAChD,IAAI,kBAAkB,SAAS;AAAA,MAC9B,MAAM,IAAI,UAAU,yCAAyC;AAAA,IAC9D;AAAA,IACA,QAAQ,QAAQ,UAAU;AAAA,IAI1B,IAAI,QAAQ,QAAQ;AAAA,MACnB,SAAS,OAAO,IAAI,OAAO;AAAA,MAC3B;AAAA,IACD;AAAA,IACA,SAAS,SAAS;AAAA,IAClB,OAAO;AAAA;AAAA,EAER,OAAO,EAAE,MAAM,SAAS,KAAK,OAAO,MAAM;AAAA;;ACxF3C,sBAAS,wBAAW;AACpB;AAiBO,SAAS,YAAY,CAC3B,QACE,OAAO,UAA4B,CAAC,GACtB;AAAA,EAChB,OAAO,UAAU,gBAAgB;AAAA,EACjC,OAAO,SAAS,UAAS,MAAM,OAAO,IAAI,IAAI,KAAK,IAAI;AAAA,EACvD,WAAU,MAAM;AAAA,IACf,IAAI,CAAC;AAAA,MAAM;AAAA,IACX,MAAM,MAAM,IAAI,IAAI,OAAO,SAAS,IAAI;AAAA,IACxC,IAAI,CAAC,IAAI,aAAa,IAAI,IAAI;AAAA,MAAG;AAAA,IACjC,IAAI,aAAa,OAAO,IAAI;AAAA,IAC5B,OAAO,QAAQ,aACd,OAAO,QAAQ,OACf,IACA,GAAG,IAAI,WAAW,IAAI,SAAS,IAAI,MACpC;AAAA,KACE,CAAC,MAAM,IAAI,CAAC;AAAA,EACf,OAAO;AAAA;;ACnCR,wBAAS,0BAAa;AACtB;AAGO,IAAM,gBAAgB;AAgB7B,eAAsB,YAAY,CACjC,QACA,QACgB;AAAA,EAChB,IAAI;AAAA,IACH,MAAM,SAAS;AAAA,IACd,MAAM;AAAA,EAGR,MAAM,OAAO;AAAA;AAQP,SAAS,UAAU,CAAC,UAA0B,CAAC,GAGpD;AAAA,EACD,QAAQ,SAAS,eAAe,WAAW;AAAA,EAC3C,MAAM,SAAS,UAAU;AAAA,EACzB,OAAO,WAAW,gBAAgB,UAAS,KAAK;AAAA,EAChD,MAAM,aAAa,cAAc,EAAE,eAAe;AAAA,EAClD,MAAM,UAAU,aAAY,MAAM;AAAA,IACjC,aAAa,IAAI;AAAA,IACZ,aAAa,QAAQ,MACzB,OAAO,CAAC,GAAG,EAAE,QAAQ,QAAQ,QAAQ,SAAS,mBAAmB,CAAC,CACnE,EAAE,QAAQ,MAAM,aAAa,KAAK,CAAC;AAAA,KACjC,CAAC,QAAQ,QAAQ,MAAM,CAAC;AAAA,EAC3B,OAAO,EAAE,SAAS,MAAM,aAAa,WAAW;AAAA;",
+  "debugId": "26E2FEF9A38E677964756E2164756E21",
+  "names": []
+}

package/dist/session/react/use-code-field.d.ts

@@ -0,0 +1,37 @@
+import { type RefObject } from 'react';
+/** The part of a Standard Schema (`~standard`) this hook reads; Zod, Valibot and ArkType satisfy it. */
+export interface CodeSchema {
+    readonly '~standard': {
+        validate(value: unknown): unknown;
+    };
+}
+/**
+ * Calls `handler` once for each new `refusal` (a new object each time,
+ * `undefined` when there is none). A refusal already there when the
+ * component mounted is not new: it is the page's own, seen again.
+ * Library-agnostic: pair it with any form library's `reset` and `focus`.
+ */
+export declare function useOnRefusal(refusal: object | undefined, handler: () => void): void;
+export interface CodeField {
+    /** The code typed so far. */
+    readonly code: string;
+    readonly setCode: (code: string) => void;
+    /** On the input, so a refusal can focus it. */
+    readonly ref: RefObject<HTMLInputElement | null>;
+    /** The first issue's message of the last `check`, cleared by typing. */
+    readonly error: string | undefined;
+    /**
+     * Validates the code against the schema: the parsed value, or
+     * `undefined` and `error` set. Synchronous schemas only.
+     */
+    readonly check: () => unknown;
+}
+/**
+ * A one-code field (an authenticator app's code, a recovery code) with no
+ * form library: it holds the code, checks it against `schema`, and on each
+ * new `refusal` clears the refused code and focuses the input for the next
+ * try. With react-hook-form, use `useOnRefusal` and its `setValue` and
+ * `setFocus` instead.
+ */
+export declare function useCodeField(schema: CodeSchema, refusal: object | undefined): CodeField;
+//# sourceMappingURL=use-code-field.d.ts.map

package/dist/session/react/use-code-field.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-code-field.d.ts","sourceRoot":"","sources":["../../../src/session/react/use-code-field.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,KAAK,SAAS,EAKd,MAAM,OAAO,CAAC;AAEf,wGAAwG;AACxG,MAAM,WAAW,UAAU;IAC1B,QAAQ,CAAC,WAAW,EAAE;QACrB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC;KAClC,CAAC;CACF;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAC3B,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,OAAO,EAAE,MAAM,IAAI,GACjB,IAAI,CASN;AAED,MAAM,WAAW,SAAS;IACzB,6BAA6B;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACzC,+CAA+C;IAC/C,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAC;IACjD,wEAAwE;IACxE,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,OAAO,CAAC;CAC9B;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC3B,MAAM,EAAE,UAAU,EAClB,OAAO,EAAE,MAAM,GAAG,SAAS,GACzB,SAAS,CA6BX"}

package/dist/session/react/use-link-param.d.ts

@@ -0,0 +1,16 @@
+export interface LinkParamOptions {
+    /**
+     * Remove the parameter from the address bar once read
+     * (`history.replaceState`), so a token is not left in the history, a
+     * bookmark or a shared screen. Default `false`.
+     */
+    readonly drop?: boolean;
+}
+/**
+ * The query parameter a mail's link carries (`token`, `code`, `state`),
+ * read once: the value of the first render is kept for the page's life, so
+ * dropping it from the address bar never loses it. `null` when absent or
+ * empty. Safe to render on the server, where nothing is dropped.
+ */
+export declare function useLinkParam(name: string, { drop }?: LinkParamOptions): string | null;
+//# sourceMappingURL=use-link-param.d.ts.map

package/dist/session/react/use-link-param.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-link-param.d.ts","sourceRoot":"","sources":["../../../src/session/react/use-link-param.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,gBAAgB;IAChC;;;;OAIG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAC3B,IAAI,EAAE,MAAM,EACZ,EAAE,IAAY,EAAE,GAAE,gBAAqB,GACrC,MAAM,GAAG,IAAI,CAef"}

package/dist/session/react/use-sign-out.d.ts

@@ -0,0 +1,26 @@
+/** Where `signInFlow`'s sign-out action is mounted unless the app says otherwise. */
+export declare const SIGN_OUT_PATH = "/sign-out";
+export interface SignOutOptions {
+    /** The sign-out route (default `/sign-out`). */
+    readonly action?: string;
+    /**
+     * Runs before the post: clear the worker's caches, a local store. A
+     * rejection never keeps the user signed in: the sign-out goes on.
+     */
+    readonly before?: () => Promise<unknown> | unknown;
+}
+/**
+ * Runs `before`, then `submit`. A `before` that throws or rejects is
+ * ignored, so a failed cleanup cannot keep a session alive.
+ */
+export declare function signOutAfter(before: (() => Promise<unknown> | unknown) | undefined, submit: () => Promise<void> | void): Promise<void>;
+/**
+ * The one way a page signs out, wherever the control is: posts `{}` as JSON
+ * to the sign-out route (same-origin and JSON only, as `signInFlow`'s action
+ * requires). `busy` from the call until the navigation it starts has ended.
+ */
+export declare function useSignOut(options?: SignOutOptions): {
+    signOut: () => void;
+    busy: boolean;
+};
+//# sourceMappingURL=use-sign-out.d.ts.map

package/dist/session/react/use-sign-out.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-sign-out.d.ts","sourceRoot":"","sources":["../../../src/session/react/use-sign-out.ts"],"names":[],"mappings":"AAGA,qFAAqF;AACrF,eAAO,MAAM,aAAa,cAAc,CAAC;AAEzC,MAAM,WAAW,cAAc;IAC9B,gDAAgD;IAChD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;CACnD;AAED;;;GAGG;AACH,wBAAsB,YAAY,CACjC,MAAM,EAAE,CAAC,MAAM,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,GAAG,SAAS,EACtD,MAAM,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,GAChC,OAAO,CAAC,IAAI,CAAC,CAOf;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,OAAO,GAAE,cAAmB,GAAG;IACzD,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,IAAI,EAAE,OAAO,CAAC;CACd,CAYA"}

package/docs/README.md

@@ -19,7 +19,7 @@ installable and usable offline, wording an API's refusals, and what to do with e
 | [Deploying](guide/deploying.md) | running the build with `bun build/server/index.js`, and the Docker image |
 | [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`), and the step-up's state and the props it gives the UI (`@alxia/react-router/session/model`) |
+| [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`) |
 | [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/session.md

@@ -6,12 +6,15 @@ holds the API's session token in an HttpOnly cookie of its own. The browser
 never sees the token; the app sends it to the API as a bearer, on the user's
 behalf.
 
-It covers two subpaths:
+It covers three subpaths:
 
 - `@alxia/react-router/session`, the server side: the cookies, the sign-in
   flow, the step-up and the pages a mail's link opens. It imports
   `react-router` and `/errors`' files, nothing else, knows no API client and
   adds no peer.
+- `@alxia/react-router/session/react`, the page's hooks around those flows:
+  signing out, a mail link's parameter and a one-code field. They import
+  `react` and `react-router`, both already peers.
 - `@alxia/react-router/session/model`, the part that imports nothing and is
   safe in a component as well as in a loader: redirects that stay on the
   site, the sign-in pages' paths, and the step-up's state.
@@ -31,6 +34,7 @@ instead.
 - [Signing out](#signing-out)
 - [Step-up](#step-up)
 - [Pages a mail's link opens](#pages-a-mails-link-opens)
+- [The page's hooks](#the-pages-hooks)
 - [The types and the rest of `/session/model`](#the-types-and-the-rest-of-sessionmodel)
 
 ## A complete sign-in
@@ -949,6 +953,131 @@ site, as a GET that spends nothing; the token is no further from the user than
 it was in the address bar, and the page's `TOKEN_PAGE_HEADERS` still keep it
 out of any `Referer`.
 
+## The page's hooks
+
+`@alxia/react-router/session/react` holds the three client pieces every app
+writes around the flows above. It imports `react` and `react-router` (peers
+the package already has) and nothing else; every hook renders on the server.
+
+### `useSignOut`
+
+Posts `{}` as JSON to the sign-out route (the one `signIn.signOut` serves; JSON
+and same-origin only), wherever the control is. `busy` is true from the call
+until the navigation it starts has ended, so the button can show it.
+
+```tsx
+import { useSignOut } from '@alxia/react-router/session/react';
+
+export function SignOutButton() {
+	const { signOut, busy } = useSignOut();
+	return (
+		<button type="button" onClick={signOut} disabled={busy}>
+			{busy ? 'Signing out…' : 'Sign out'}
+		</button>
+	);
+}
+```
+
+Options: `action` (the route, default `/sign-out`) and `before`, run before the
+post, for what must be gone from a shared device first. A `before` that throws
+or rejects never keeps the user signed in: the sign-out goes on.
+
+```tsx
+const { signOut } = useSignOut({
+	action: '/account/sign-out',
+	before: () => caches.keys().then((keys) => Promise.all(keys.map((k) => caches.delete(k)))),
+});
+```
+
+### `useLinkParam`
+
+Reads the query parameter a mail's link carries, once: the first render's value
+is kept for the page's life. With `drop: true` the parameter is then removed
+from the address bar (`history.replaceState`, keeping the history state and the
+hash), so a token is not left in the history, a bookmark or a screenshot. It is
+`null` when the parameter is absent or empty.
+
+```tsx
+import { useLinkParam } from '@alxia/react-router/session/react';
+
+export default function ResetPassword() {
+	const token = useLinkParam('token', { drop: true });
+	if (!token) return <p>This link is not valid. Ask for a new one.</p>;
+	return (
+		<form method="post">
+			<input type="hidden" name="token" value={token} />
+			<input type="password" name="password" autoComplete="new-password" />
+			<button type="submit">Choose a new password</button>
+		</form>
+	);
+}
+```
+
+The router's own location is not updated by `replaceState`: a loader or
+`useSearchParams` elsewhere still sees the token until the next navigation.
+Read it with the hook once, and pass it down.
+
+### `useCodeField` and `useOnRefusal`
+
+A form that asks for one code (an authenticator app's, a recovery code) and
+whose action answers a refusal object when the code is wrong: on each new
+refusal the refused code goes and the field takes focus, for the next try. A
+refusal already there when the component mounted is the page's own and is
+ignored.
+
+`useCodeField(schema, refusal)` needs no form library. `schema` is any
+[Standard Schema](https://standardschema.dev) (Zod, Valibot, ArkType; a
+synchronous one). It returns `code`, `setCode`, `ref` (put it on the input),
+`error` (the first message of the last `check()`, cleared by typing) and
+`check()` (the parsed value, or `undefined` with `error` set).
+
+```tsx
+import { useCodeField } from '@alxia/react-router/session/react';
+import { TOTP_CODE } from '@alxia/react-router/session/model';
+import { Form, useActionData } from 'react-router';
+import { z } from 'zod';
+
+const schema = z.string().regex(TOTP_CODE, 'Six digits');
+
+export function CodeForm() {
+	const refusal = useActionData<object>(); // a new object on each refusal
+	const field = useCodeField(schema, refusal);
+	return (
+		<Form method="post" onSubmit={(event) => { if (field.check() === undefined) event.preventDefault(); }}>
+			<input
+				ref={field.ref}
+				name="code"
+				inputMode="numeric"
+				autoComplete="one-time-code"
+				value={field.code}
+				onChange={(event) => field.setCode(event.target.value)}
+			/>
+			{field.error ? <p role="alert">{field.error}</p> : null}
+			<button type="submit">Confirm</button>
+		</Form>
+	);
+}
+```
+
+An app on react-hook-form keeps its form and its resolver and uses the part
+underneath, `useOnRefusal(refusal, handler)`, which calls `handler` once per
+new refusal:
+
+```tsx
+import { useOnRefusal } from '@alxia/react-router/session/react';
+import { useForm } from 'react-hook-form';
+
+const form = useForm({ defaultValues: { code: '' } /* , resolver */ });
+useOnRefusal(refusal, () => {
+	form.setValue('code', '');
+	form.setFocus('code');
+});
+```
+
+The package takes no form library as a peer: react-hook-form would also need
+its resolver for the schema, and a library-agnostic core serves every form
+library at the price of three lines.
+
 ## The types and the rest of `/session/model`
 
 The rest of `@alxia/react-router/session/model`, beside `safeNext`,

package/docs/roadmap.md

@@ -7,7 +7,12 @@ number on it. Every release, with each change it made, is in
 
 ## Now
 
-Nothing planned.
+- **`@alxia/react-router/session/react`: the page's hooks around the session
+  flows.** `useSignOut`, `useLinkParam` (a mail link's parameter, read once and
+  optionally dropped from the address bar) and `useCodeField` /
+  `useOnRefusal` (a one-code field that clears and refocuses on each refusal),
+  so an app stops carrying its own copies. See the
+  [session guide](guide/session.md#the-pages-hooks).
 
 ## Next
 

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@alxia/react-router",
-	"version": "0.16.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`) and what it shares with the page (`/session/model`), the page's CSP nonce and inline boot scripts (`/document`) and a streaming `entry.server` (`/entry`)",
+	"version": "0.17.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`), the page's CSP nonce and inline boot scripts (`/document`) and a streaming `entry.server` (`/entry`)",
 	"license": "MIT",
 	"type": "module",
 	"main": "./dist/index.js",
@@ -72,6 +72,11 @@
 			"import": "./dist/pwa/worker/index.js",
 			"default": "./dist/pwa/worker/index.js"
 		},
+		"./session/react": {
+			"types": "./dist/session/react/index.d.ts",
+			"import": "./dist/session/react/index.js",
+			"default": "./dist/session/react/index.js"
+		},
 		"./session/model": {
 			"types": "./dist/session/model/index.d.ts",
 			"import": "./dist/session/model/index.js",
@@ -103,6 +108,7 @@
 			"src/errors/index.ts",
 			"src/session/model/index.ts",
 			"src/session/index.ts",
+			"src/session/react/index.ts",
 			"src/document/index.ts",
 			"src/entry/index.ts",
 			"src/pwa/worker/index.ts",
@@ -121,6 +127,7 @@
 		"@types/react": "^19.3.0",
 		"@types/react-dom": "^19.3.0",
 		"graphql": "^17.0.2",
+		"happy-dom": "^20",
 		"intl-messageformat": "^12.1.4",
 		"isbot": "^5.2.2",
 		"react": "^19.3.1",