@sjolystinnovation/app-kit 0.2.0 → 0.4.0

package/README.md

@@ -64,14 +64,14 @@ const secret = resolveJwtSecret(sessionConfig, process.env);
 | --- | --- | --- |
 | `jwtSecretEnvVar` | `string` | Name of the environment variable holding the API JWT secret, such as `API_JWT_SECRET`. |
 | `loginRoute` | `string` | Where an expired session sends the browser, such as `/en/login` or `/login`. |
-| `draftStoragePrefix` | `string` | Prefix for the `localStorage` keys holding form drafts. |
+| `draftStoragePrefix` | `string` | Bare name for the `localStorage` keys holding form drafts, such as `example`. Drafts are stored under `example:draft:<owner>:<scope>`. |
 
 ### `defineSessionConfig(config)`
 
 `(config: SessionConfig) => SessionConfig`
 
 Returns the config unchanged, so TypeScript checks its shape where it is declared rather than at
-every call site.
+every call site. Throws when `draftStoragePrefix` is empty or contains a colon.
 
 ### `resolveJwtSecret(config, env)`
 
@@ -91,23 +91,184 @@ resolveJwtSecret(sessionConfig, {});
 The environment is a parameter rather than a read of `process.env`, which keeps Node types out of a
 package that also runs in the browser.
 
-### `formatApiError(error, fallback)`
+### `formatApiError(error, fallback, statusMessages?)`
 
-`(error: unknown, fallback: string) => string`
+`(error: unknown, fallback: string, statusMessages?: StatusMessages) => string`
 
-Turns a failed request into one line a user can read. For an axios error it takes the first of
-`message`, the first validation error, `detail` and `title` from the response body, which covers
-plain JSON errors and ASP.NET Core problem details alike. Otherwise it uses the error's own message,
-then `fallback`.
+Turns a failed request into one line a user can read.
+
+On a 4xx response it uses the first of:
+
+1. The body's own message: a text body, such as the one `BadRequest("...")` sends from ASP.NET Core,
+   or `message`, the first validation error or `detail` from a JSON body.
+2. The entry in `statusMessages` for the status.
+3. `fallback`.
+
+On a 5xx response the entry in `statusMessages` comes first, then the body, then `fallback`. A 5xx
+body can come from a proxy, such as "Bad Gateway", so the caller's own words win when it has them.
+
+A problem details `title` is never shown. ASP.NET Core fills it with generic text, such as "Bad
+Request" or "An error occurred while processing your request.", which says less than `fallback`.
+
+Key `0` in `statusMessages` covers a request that got no response, because of a dropped connection
+or a timeout. Only text on a single line counts as a message. Axios's own message, such as "Request
+failed with status code 500", is never shown, and a cancelled request gives `fallback`. Any other
+`Error` gives its own message. A body requested as an `arraybuffer` or a `blob`, as for a file
+download, is not read, so a failed download gets `statusMessages` or `fallback`.
 
 ```ts
 try {
   await api.post("/users", form);
 } catch (error) {
-  setError(formatApiError(error, "Could not create the user."));
+  setError(formatApiError(error, "Could not create the user.", { 409: "That email is taken." }));
+}
+```
+
+### `@sjolystinnovation/app-kit/session`
+
+Decides when a user has to sign in again. Safe to import from server code, such as the next-auth
+callbacks.
+
+The gate reads `session.error`. The app's `jwt` callback sets `token.error`, and its `session`
+callback copies it across:
+
+```ts
+callbacks: {
+  session({ session, token }) {
+    session.error = token.error;
+    return session;
+  },
+},
+```
+
+For that to compile, `error` has to be on next-auth's `Session` and `JWT` types. Add it to
+the app's existing next-auth type declarations, or create them:
+
+```ts
+// src/types/next-auth.d.ts
+import "next-auth";
+import "next-auth/jwt";
+
+declare module "next-auth" {
+  interface Session {
+    error?: string | undefined;
+  }
+}
+
+declare module "next-auth/jwt" {
+  interface JWT {
+    error?: string | undefined;
+  }
+}
+```
+
+`SESSION_ERRORS` holds the values the jwt callback puts in `token.error` when the session cannot be
+recovered: `AbsoluteSessionExpired`, `RefreshTokenRejected` and `NoRefreshToken`. `SessionError`
+is their union type. `isTerminalSessionError(error)` is true for those three only, so a transient
+refresh failure keeps the session.
+
+The re-sign-in prompt is a flag outside React, so an axios interceptor can raise it:
+
+| Function | Description |
+| --- | --- |
+| `openSessionPrompt()` | Asks the user to sign in again without leaving the page. |
+| `closeSessionPrompt()` | Hides the prompt. Call it when the component showing the prompt unmounts, or the flag stays open and the gate never redirects. |
+| `subscribeSessionPrompt(listener)` | Calls `listener` when the prompt opens or closes. Returns an unsubscribe function. |
+| `getSessionPromptOpen()` | Whether the prompt is showing. |
+
+Copies of the package installed side by side share the one flag, as long as their releases use the
+same prompt state format. A release that changes the format says so in its changelog. An app's own
+copy of these functions does not, so an app moving to them moves every import at once: the
+interceptor, the prompt and every gate.
+
+### `useSessionGate()`
+
+From `@sjolystinnovation/app-kit/session/react`. Tells a protected page whether it may render. It
+reads `useSession`, so it needs a `SessionProvider` above it.
+
+A page that rendered on a healthy session stays rendered when the session gets a terminal error,
+while the session is re-read and while the prompt recovers it, so an open form keeps its values. A
+session that turns signed out with no prompt open blanks the page. A page the user opens
+on a dead session does not render. Use `mayRender` in every gate and layout on the way down, so
+none of them blanks a page that another one kept.
+
+The hook does not navigate. The gate sends the user to the login page itself, and never while the
+prompt is open. The app passes the login URL in, so an app with a locale in the path can build it
+for the current locale:
+
+```tsx
+"use client";
+
+import { useSessionGate } from "@sjolystinnovation/app-kit/session/react";
+import { useRouter } from "next/navigation";
+import { useEffect } from "react";
+
+export function ProtectedGate({
+  loginHref,
+  children,
+}: {
+  loginHref: string;
+  children: React.ReactNode;
+}) {
+  const router = useRouter();
+  const { status, promptOpen, usable, wasUsable, mayRender } = useSessionGate();
+
+  useEffect(() => {
+    if (promptOpen) return;
+    if (status === "unauthenticated" || (status === "authenticated" && !usable && !wasUsable)) {
+      router.push(loginHref);
+    }
+  }, [status, usable, wasUsable, promptOpen, router, loginHref]);
+
+  return mayRender ? children : <p>Loading…</p>;
 }
 ```
 
+| Field | Description |
+| --- | --- |
+| `mayRender` | Whether the page may render. |
+| `session`, `status` | As `useSession` returns them. |
+| `usable` | The session is signed in and has no terminal error. |
+| `wasUsable` | This page has rendered on a usable session. |
+| `promptOpen` | The re-sign-in prompt is showing. |
+| `recovering` | The prompt is showing over a page that was usable. |
+
+`SessionGate` is the type of the result.
+
+### `useFormDraft(config, options)`
+
+From `@sjolystinnovation/app-kit/forms`. Keeps a form's values in `localStorage`, so a sign-out,
+reload or closed tab does not lose them. Values are written half a second after the last change, so
+only that last half second is at risk.
+
+```tsx
+// userId is the signed-in user's id, from wherever the app's session keeps it.
+const draft = useFormDraft(sessionConfig, {
+  owner: userId,
+  scope: recipe ? `recipe:${recipe.id}` : "recipe:new",
+  value: form,
+});
+```
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `owner` | `string \| undefined` | The signed-in user's id. Drafts are stored per user, and nothing is stored until it is known. The last known owner is kept when the session stops reporting one. |
+| `scope` | `string` | The form and the entity it edits, such as `recipe:42`. |
+| `value` | `T` | The form's current values. They must survive `JSON.stringify`. |
+
+Mount an edit form once the entity has loaded, with its values already in `value`. The hook treats
+the values it first sees under a key as the untouched form, so values that arrive later count as an
+edit and are written over the draft being offered.
+
+It returns `pending`, the stored draft, which the page offers instead of applying. It is read when the
+owner is first known and again whenever the owner or `scope` changes, so it can appear after the form mounts. It
+also returns `dismiss()` to stop offering it, and `clear()` to drop the stored draft after a
+successful save.
+
+Drafts are stored under `<draftStoragePrefix>:draft:<owner>:<scope>`. The hook throws when
+`draftStoragePrefix` is empty or contains a colon. A draft older than 7 days is not offered, and is
+removed when its form next reads it.
+
 ### `Alert`
 
 ```tsx
@@ -120,12 +281,14 @@ import { Alert } from "@sjolystinnovation/app-kit/ui";
 | --- | --- | --- | --- |
 | `variant` | `"error" \| "success" \| "info" \| "warning"` | `"info"` | Colour of the box. |
 | `role` | `"alert" \| "status"` | `"alert"` | Use `status` for text that keeps changing, such as a countdown, so a screen reader does not announce every change. |
+| `className` | `string` | | Classes for placing the alert, such as a margin. Restyle it through the theme variables instead, since whether a clashing class wins depends on the order Tailwind emits them in. |
 | `children` | `ReactNode` | | Content. |
 
 ### `PasswordInput`
 
-A labelled password field with a button that shows and hides the value. Accepts every `<input>`
-attribute as well.
+A labelled password field with a button that shows and hides the value. It also takes the other
+`<input>` attributes, apart from `type`, which the component switches itself. `className` goes on
+the outer element, see below.
 
 ```tsx
 import { PasswordInput } from "@sjolystinnovation/app-kit/ui";
@@ -136,17 +299,69 @@ import { PasswordInput } from "@sjolystinnovation/app-kit/ui";
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
 | `label` | `string` | | Visible label, tied to the input. |
-| `error` | `string` | | Message shown under the field, which also turns the border red. |
+| `error` | `string` | | Message shown under the field. It turns the border red, marks the input invalid and is read out with it by screen readers. |
 | `showPasswordLabel` | `string` | `"Show password"` | Accessible name of the toggle while the value is hidden. |
 | `hidePasswordLabel` | `string` | `"Hide password"` | Accessible name of the toggle while the value is visible. |
+| `className` | `string` | | Classes for placing the field, such as a margin. They go on the outer element around the label, input and error. Restyle the field through the theme variables instead. |
 
 Pass the two toggle labels in the app's language. The defaults are English.
 
+## Theming
+
+The components draw every colour, corner radius and label size from theme variables with a light
+default. Set any of them in the app's own `@theme` to restyle every component at once, or in a
+selector such as `.dark` for a scoped theme:
+
+```css
+/* src/app/globals.css */
+@import "tailwindcss";
+@import "@sjolystinnovation/app-kit/styles.css";
+
+@theme {
+  --color-alert-error-bg: color-mix(in oklab, var(--color-red-500) 10%, transparent);
+  --color-alert-error-text: var(--color-red-400);
+  --radius-alert: var(--radius-xl);
+  --color-input-focus-ring: var(--color-sky-500);
+}
+```
+
+| Variable | Default |
+| --- | --- |
+| `--radius-alert` | `var(--radius-lg)` |
+| `--color-alert-error-bg`, `-border`, `-text` | red 50, 200, 700 |
+| `--color-alert-success-bg`, `-border`, `-text` | green 50, 200, 700 |
+| `--color-alert-info-bg`, `-border`, `-text` | gray 50, 200, 700 |
+| `--color-alert-warning-bg`, `-border`, `-text` | amber 50, 200, 900 |
+| `--text-field-label`, `--text-field-label--line-height` | `var(--text-sm)` and its line height. Set both together. |
+| `--color-field-label-text` | gray 700 |
+| `--spacing-field-label` | gap under the label, `calc(var(--spacing) * 1)` |
+| `--color-field-required` | red 600, the asterisk on a required field |
+| `--color-field-error` | red 600, the message under a field |
+| `--radius-input` | `var(--radius-lg)` |
+| `--spacing-input-y` | `calc(var(--spacing) * 2)` |
+| `--color-input-bg` | `transparent` |
+| `--color-input-border` | gray 300 |
+| `--color-input-border-error` | red 400 |
+| `--color-input-focus-border` | gray 300 |
+| `--color-input-text` | gray 900 |
+| `--color-input-placeholder` | gray 400 |
+| `--color-input-focus-ring` | `var(--color-primary)` |
+| `--input-focus-ring-width` | `2px` |
+| `--color-input-toggle` | gray 400, the show password icon |
+| `--color-input-toggle-hover` | gray 600 |
+
+A default that points at another variable, such as `--color-input-focus-ring` at `--color-primary`,
+is read once for the whole page. A scoped theme that changes `--color-primary` should set
+`--color-input-focus-ring` in the same selector.
+
+An app that clears a whole Tailwind namespace, such as `--color-*: initial`, clears these variables
+with it and has to set the ones it uses itself.
+
 ## Requirements
 
 - Next.js 16, React 19, next-auth 4 and axios 1, as peer dependencies the app installs itself.
-- For `@sjolystinnovation/app-kit/ui`: Tailwind CSS 4 with a `primary` colour in the theme, which the
-  focus ring uses, and `@heroicons/react` 2.
+- For `@sjolystinnovation/app-kit/ui`: Tailwind CSS 4 and `@heroicons/react` 2. The focus ring uses
+  the theme's `primary` colour unless `--color-input-focus-ring` is set.
 - TypeScript with `"moduleResolution": "bundler"`. Relative imports here are extensionless, which
   `node16` and `nodenext` reject.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjolystinnovation/app-kit",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Building blocks for Next.js apps that sign in against a JWT API through next-auth",
   "license": "Apache-2.0",
   "author": "Sjølyst Innovation AS",
@@ -16,6 +16,9 @@
   ],
   "exports": {
     ".": "./src/index.ts",
+    "./session": "./src/session/index.ts",
+    "./session/react": "./src/session/react/index.ts",
+    "./forms": "./src/forms/index.ts",
     "./ui": "./src/ui/index.ts",
     "./styles.css": "./src/styles.css"
   },

package/src/config.ts

@@ -13,15 +13,35 @@ export interface SessionConfig {
    * something like "/en/login", one without uses "/login".
    */
   loginRoute: string;
-  /** Prefix for the localStorage keys holding form drafts. */
+  /**
+   * Prefix for the localStorage keys holding form drafts, usually the app's name, such as
+   * "example". Drafts are stored under `<prefix>:draft:<owner>:<scope>`, so the prefix itself
+   * has no trailing colon.
+   */
   draftStoragePrefix: string;
 }
 
-/** Identity helper, so an app can declare its config as a typed constant. */
+/**
+ * Declares an app's config as a typed constant. Throws when `draftStoragePrefix` is not a bare name,
+ * so a bad value fails when the app starts rather than when a form first opens.
+ */
 export function defineSessionConfig(config: SessionConfig): SessionConfig {
+  draftPrefix(config);
   return config;
 }
 
+/**
+ * The key prefix for form drafts. A colon or an empty name builds keys such as "app:draft::draft:",
+ * which match none of the drafts already saved under "app:draft:".
+ */
+export function draftPrefix(config: Pick<SessionConfig, "draftStoragePrefix">): string {
+  const name = config.draftStoragePrefix;
+  if (!name || name.includes(":")) {
+    throw new Error(`draftStoragePrefix must be a bare name such as "example", not "${name}".`);
+  }
+  return `${name}:draft:`;
+}
+
 /**
  * Reads the API JWT secret named by the config. Throws rather than returning undefined, because a
  * missing secret silently breaks token verification at runtime instead of at boot.

package/src/errors.ts

@@ -1,29 +1,108 @@
-import axios from "axios";
+import axios, { type AxiosResponse } from "axios";
 
-interface ApiErrorBody {
-  message?: string;
-  detail?: string;
-  title?: string;
-  errors?: Record<string, string[]>;
-}
+/**
+ * Messages to show for a status code. On a 4xx they are used when the response carries no specific
+ * message of its own. On a 5xx they win over the body. Key 0 covers a request that got no response,
+ * because of a dropped connection or a timeout.
+ */
+export type StatusMessages = Partial<Record<number, string>>;
+
+/**
+ * Axios codes for a request that never got a response from the network. A browser reports every
+ * network failure as ERR_NETWORK. On the server, Node reports the cause instead.
+ */
+const NO_RESPONSE_CODES = new Set([
+  "ERR_NETWORK",
+  "ECONNABORTED",
+  "ETIMEDOUT",
+  "ECONNREFUSED",
+  "ECONNRESET",
+  "ENOTFOUND",
+  "EAI_AGAIN",
+  "EHOSTUNREACH",
+  "ENETUNREACH",
+]);
 
 /**
- * Turns a failed request into one line a user can read. Takes the first of `message`, the first
- * validation error, `detail` and `title` from the response body, so it reads both plain JSON
- * errors and ASP.NET Core problem details. Falls back to the error's own message, then to
- * `fallback`.
+ * Turns a failed request into one line a user can read.
+ *
+ * On a 4xx response the body's own message comes first: a text body, then `message`, the first
+ * validation error and `detail` from a JSON body. After that come `statusMessages` for the status
+ * and `fallback`. On a 5xx the caller's status message comes first, because the body may be a
+ * proxy's "Bad Gateway" rather than the API's own words. A problem details `title` is never used:
+ * ASP.NET Core fills it with generic text such as "Bad Request", which says less than `fallback`.
+ *
+ * Only single line text counts as a message. Axios's own message, such as "Request failed with
+ * status code 500", is never shown, and a cancelled request gives `fallback`. Any other `Error`
+ * gives its message.
  */
-export function formatApiError(error: unknown, fallback: string): string {
+export function formatApiError(
+  error: unknown,
+  fallback: string,
+  statusMessages: StatusMessages = {},
+): string {
+  if (axios.isCancel(error)) return fallback;
   if (axios.isAxiosError(error)) {
-    const data = error.response?.data as ApiErrorBody | undefined;
-    if (data?.message) return data.message;
-    if (data?.errors) {
-      const first = Object.values(data.errors)[0];
-      if (first && first.length) return first[0];
+    const response = error.response;
+    if (!response) {
+      return NO_RESPONSE_CODES.has(error.code ?? "") ? (statusMessages[0] ?? fallback) : fallback;
     }
-    if (data?.detail) return data.detail;
-    if (data?.title) return data.title;
+    const message = readBody(response);
+    const forStatus = statusMessages[response.status];
+    if (response.status >= 500) return forStatus ?? message ?? fallback;
+    return message ?? forStatus ?? fallback;
   }
-  if (error instanceof Error) return error.message;
+  if (error instanceof Error) return singleLine(error.message) ?? fallback;
   return fallback;
 }
+
+/** The message the body carries for this failure, if it carries one. */
+function readBody(response: AxiosResponse): string | undefined {
+  const data = parseIfJson(response.data);
+  if (typeof data === "string") return singleLine(data);
+  // Only a parsed JSON object has fields to read. A Document, Blob or ArrayBuffer does not.
+  if (!isPlainObject(data)) return undefined;
+  return firstText(data.message) ?? firstValidationError(data.errors) ?? singleLine(data.detail);
+}
+
+/**
+ * Axios leaves a JSON body as a string when the request asked for text, so parse it here. Plain text
+ * such as "Invalid email or password." is not valid JSON and stays as it is.
+ */
+function parseIfJson(data: unknown): unknown {
+  if (typeof data !== "string") return data;
+  try {
+    return JSON.parse(data);
+  } catch {
+    return data;
+  }
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (!value || typeof value !== "object") return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+/** Reads the first message from `errors`, whether its values are string arrays or strings. */
+function firstValidationError(errors: unknown): string | undefined {
+  if (!errors || typeof errors !== "object") return undefined;
+  for (const value of Object.values(errors)) {
+    const message = firstText(value);
+    if (message) return message;
+  }
+  return undefined;
+}
+
+/** A single line of text, or the first entry when the value is a list of them. */
+function firstText(value: unknown): string | undefined {
+  return singleLine(Array.isArray(value) ? value[0] : value);
+}
+
+/** The trimmed text, when it is one line of text and not HTML. */
+function singleLine(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const text = value.trim();
+  if (!text || /[\r\n\u2028\u2029]/.test(text) || text.startsWith("<")) return undefined;
+  return text;
+}

package/src/forms/index.ts

@@ -0,0 +1,2 @@
+export { useFormDraft } from "./useFormDraft";
+export type { FormDraft, FormDraftOptions } from "./useFormDraft";

package/src/forms/useFormDraft.ts

@@ -0,0 +1,133 @@
+"use client";
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import { draftPrefix, type SessionConfig } from "../config";
+
+const WRITE_DELAY_MS = 500;
+
+// How long a draft is offered. Long enough to outlive an expired session or a closed tab, short
+// enough that week-old work is not offered as if it were current. An expired draft is removed when
+// its form next reads it.
+const MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
+
+interface Envelope<T> {
+  savedAt: number;
+  value: T;
+}
+
+function read<T>(storageKey: string): T | null {
+  try {
+    const raw = window.localStorage.getItem(storageKey);
+    if (raw == null) return null;
+
+    const envelope = JSON.parse(raw) as Envelope<T> | null;
+    const fresh =
+      typeof envelope?.savedAt === "number" && Date.now() - envelope.savedAt <= MAX_AGE_MS;
+    if (!fresh || envelope?.value === undefined) {
+      window.localStorage.removeItem(storageKey);
+      return null;
+    }
+    return envelope.value;
+  } catch {
+    return null;
+  }
+}
+
+export interface FormDraftOptions<T> {
+  /**
+   * The signed-in user's id. A browser profile can be shared, so the draft is stored per user.
+   * Without that, the next person to sign in is offered the previous one's work. The last known
+   * owner is kept, because a lost cookie reports nobody and that is the moment the draft matters
+   * most. Nothing is stored until an owner is known.
+   */
+  owner: string | undefined;
+  /** Identifies the form and the entity it edits, for example `recipe:new` or `recipe:42`. */
+  scope: string;
+  /** The form's current values. They must survive `JSON.stringify`. */
+  value: T;
+}
+
+export interface FormDraft<T> {
+  /**
+   * The stored draft, while it is still waiting to be restored or dismissed. Read once the owner is
+   * known and again whenever the owner or scope changes, so it can appear after mount.
+   */
+  pending: T | null;
+  /** Stop offering the draft. The caller applies the values it wants. */
+  dismiss: () => void;
+  /** Drop the stored draft after a successful save. */
+  clear: () => void;
+}
+
+/**
+ * Keeps a form's values in localStorage so a sign-out, reload or closed tab does not lose them.
+ * Values are written half a second after the last change, so only that last half second is at risk.
+ *
+ * A draft found at mount is offered for restore rather than applied, so an edit form never silently
+ * overwrites what the API returned. Saving starts immediately either way. The offer is held in
+ * memory, so the newest work is always the thing in storage.
+ */
+export function useFormDraft<T>(
+  config: Pick<SessionConfig, "draftStoragePrefix">,
+  { owner, scope, value }: FormDraftOptions<T>,
+): FormDraft<T> {
+  // Adjusted during render rather than in an effect, which is the supported way to derive state
+  // from changing inputs.
+  const [lastOwner, setLastOwner] = useState<string | undefined>(undefined);
+  if (owner && owner !== lastOwner) setLastOwner(owner);
+
+  // Checked before the owner is known, so a bad prefix fails on the first render, signed in or not.
+  const prefix = draftPrefix(config);
+  const key = lastOwner ? `${prefix}${lastOwner}:${scope}` : null;
+
+  const [pending, setPending] = useState<T | null>(null);
+  const json = JSON.stringify(value);
+  const untouched = useRef(json);
+  const writeTimer = useRef<number | null>(null);
+
+  useEffect(() => {
+    // Re-base on a key change too. The values on screen belong to the old key, and writing them
+    // under the new one would put this form's work in another form's draft.
+    untouched.current = json;
+    // Reading the store is an external-system read, which is what an effect is for.
+    // eslint-disable-next-line react-hooks/set-state-in-effect
+    setPending(key == null ? null : read<T>(key));
+    // Keyed on the draft key alone on purpose. Re-reading whenever the values change would
+    // re-offer a draft the user has already answered.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [key]);
+
+  useEffect(() => {
+    if (key == null) return;
+    // Write only once the form differs from how it opened. Writing the pristine form would
+    // overwrite the draft being offered before the user has answered.
+    if (json === untouched.current) return;
+    const timer = window.setTimeout(() => {
+      try {
+        window.localStorage.setItem(key, JSON.stringify({ savedAt: Date.now(), value }));
+      } catch {
+        // A full or blocked store must not break the form.
+      }
+    }, WRITE_DELAY_MS);
+    writeTimer.current = timer;
+    return () => window.clearTimeout(timer);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [key, json]);
+
+  const clear = useCallback(() => {
+    if (key == null) return;
+    // Cancel a write that is already scheduled, and treat the current values as the new baseline.
+    // Otherwise a save is followed by the draft being written back.
+    if (writeTimer.current != null) window.clearTimeout(writeTimer.current);
+    untouched.current = json;
+    try {
+      window.localStorage.removeItem(key);
+    } catch {
+      // The draft is a convenience, not state anything depends on.
+    }
+  }, [key, json]);
+
+  const dismiss = useCallback(() => setPending(null), []);
+
+  return { pending, dismiss, clear };
+}

package/src/index.ts

@@ -1,3 +1,4 @@
 export { defineSessionConfig, resolveJwtSecret } from "./config";
 export type { SessionConfig } from "./config";
 export { formatApiError } from "./errors";
+export type { StatusMessages } from "./errors";

package/src/session/expiry.ts

@@ -0,0 +1,66 @@
+/**
+ * Errors the jwt callback sets when the session cannot be recovered without a new sign-in. A
+ * transient refresh failure, such as a network error or an API restart, sets no error, so the
+ * session keeps working and a later session read retries the refresh.
+ */
+export const SESSION_ERRORS = {
+  absoluteExpiry: "AbsoluteSessionExpired",
+  refreshRejected: "RefreshTokenRejected",
+  noRefreshToken: "NoRefreshToken",
+} as const;
+
+/** One of the values in `SESSION_ERRORS`. */
+export type SessionError = (typeof SESSION_ERRORS)[keyof typeof SESSION_ERRORS];
+
+const TERMINAL: ReadonlySet<string> = new Set(Object.values(SESSION_ERRORS));
+
+/** Whether a session error means the user has to sign in again. */
+export function isTerminalSessionError(error: string | undefined): boolean {
+  return error != null && TERMINAL.has(error);
+}
+
+// Whether the re-sign-in prompt is showing. It lives outside React because the axios interceptor
+// that raises it is a plain module, and because the page gate has to know: it must not redirect to
+// the login page while the prompt is recovering the session in place.
+//
+// Kept on globalThis under a registered symbol, so two copies of this module, such as two installed
+// versions of the package, still share one prompt. Separate state would let a prompt raised through
+// one copy go unseen by a gate reading the other, and the gate would redirect away from the form.
+interface PromptState {
+  open: boolean;
+  listeners: Set<() => void>;
+}
+
+// The shape of PromptState is a contract between releases. A release that changes it must also
+// change this key, so it never reads state in a shape it does not expect.
+const STATE_KEY = Symbol.for("@sjolystinnovation/app-kit/session-prompt/v1");
+const shared = globalThis as typeof globalThis & { [STATE_KEY]?: PromptState };
+const state: PromptState = (shared[STATE_KEY] ??= { open: false, listeners: new Set() });
+
+function emit(): void {
+  for (const listener of [...state.listeners]) listener();
+}
+
+/** Ask the user to sign in again without leaving the page. */
+export function openSessionPrompt(): void {
+  if (state.open) return;
+  state.open = true;
+  emit();
+}
+
+export function closeSessionPrompt(): void {
+  if (!state.open) return;
+  state.open = false;
+  emit();
+}
+
+export function subscribeSessionPrompt(listener: () => void): () => void {
+  state.listeners.add(listener);
+  return () => {
+    state.listeners.delete(listener);
+  };
+}
+
+export function getSessionPromptOpen(): boolean {
+  return state.open;
+}

package/src/session/index.ts

@@ -0,0 +1,9 @@
+export {
+  SESSION_ERRORS,
+  closeSessionPrompt,
+  getSessionPromptOpen,
+  isTerminalSessionError,
+  openSessionPrompt,
+  subscribeSessionPrompt,
+} from "./expiry";
+export type { SessionError } from "./expiry";

package/src/session/react/index.ts

@@ -0,0 +1,2 @@
+export { useSessionGate } from "./useSessionGate";
+export type { SessionGate } from "./useSessionGate";

package/src/session/react/useSessionGate.ts

@@ -0,0 +1,63 @@
+"use client";
+
+import { useSession } from "next-auth/react";
+import { usePathname } from "next/navigation";
+import { useState, useSyncExternalStore } from "react";
+import { getSessionPromptOpen, isTerminalSessionError, subscribeSessionPrompt } from "../expiry";
+
+/**
+ * Whether a protected page may render, and whether it must stay rendered.
+ *
+ * Every gate on the way down should use this, so they agree. A nested layout that decides on its
+ * own to blank the page undoes the in-place recovery the re-sign-in prompt exists for, and the user
+ * loses the form anyway.
+ */
+export function useSessionGate() {
+  const { data: session, status } = useSession();
+  const pathname = usePathname();
+  const promptOpen = useSyncExternalStore(
+    subscribeSessionPrompt,
+    getSessionPromptOpen,
+    () => false,
+  );
+
+  // The jwt callback copies its error onto the session. Read it without requiring the app to have
+  // added `error` to next-auth's Session type.
+  const error = (session as { error?: string } | null)?.error;
+  const usable = status === "authenticated" && !isTerminalSessionError(error);
+
+  // Which page last rendered on a healthy session. Keyed by path, so each page starts the check
+  // again and a session that died on the previous page cannot carry a stale pass into a fresh form.
+  // Adjusted during render rather than in an effect, which is the supported way to derive state
+  // from changing inputs.
+  // Undefined until then rather than null, because usePathname can itself return null.
+  const [usableAt, setUsableAt] = useState<string | null | undefined>(undefined);
+  if (usable && usableAt !== pathname) setUsableAt(pathname);
+  const wasUsable = usableAt === pathname;
+
+  // The page is already open and the prompt is recovering the session in place.
+  const recovering = promptOpen && wasUsable;
+
+  return {
+    session,
+    status,
+    promptOpen,
+    usable,
+    wasUsable,
+    recovering,
+    /**
+     * The one answer every gate on the way down uses. A layout that decides this again can blank
+     * the page that the gate above it chose to keep.
+     */
+    mayRender:
+      recovering ||
+      !(
+        (status === "loading" && !wasUsable) ||
+        status === "unauthenticated" ||
+        (!usable && !wasUsable)
+      ),
+  };
+}
+
+/** What `useSessionGate` returns. */
+export type SessionGate = ReturnType<typeof useSessionGate>;

package/src/styles.css

@@ -1,2 +1,43 @@
 /* Adds this package's components to the files Tailwind scans for class names. */
 @source ".";
+
+/*
+ * Design tokens for the components. Each default matches a stock Tailwind value, so an app that
+ * sets none of them gets the look below. Set any of them in the app's own @theme to restyle, or in
+ * a selector such as .dark for a scoped theme.
+ */
+@theme default {
+  --radius-alert: var(--radius-lg);
+  --color-alert-error-bg: var(--color-red-50);
+  --color-alert-error-border: var(--color-red-200);
+  --color-alert-error-text: var(--color-red-700);
+  --color-alert-success-bg: var(--color-green-50);
+  --color-alert-success-border: var(--color-green-200);
+  --color-alert-success-text: var(--color-green-700);
+  --color-alert-info-bg: var(--color-gray-50);
+  --color-alert-info-border: var(--color-gray-200);
+  --color-alert-info-text: var(--color-gray-700);
+  --color-alert-warning-bg: var(--color-amber-50);
+  --color-alert-warning-border: var(--color-amber-200);
+  --color-alert-warning-text: var(--color-amber-900);
+
+  --text-field-label: var(--text-sm);
+  --text-field-label--line-height: var(--text-sm--line-height);
+  --color-field-label-text: var(--color-gray-700);
+  --spacing-field-label: calc(var(--spacing) * 1);
+  --color-field-required: var(--color-red-600);
+  --color-field-error: var(--color-red-600);
+
+  --radius-input: var(--radius-lg);
+  --spacing-input-y: calc(var(--spacing) * 2);
+  --color-input-bg: transparent;
+  --color-input-border: var(--color-gray-300);
+  --color-input-border-error: var(--color-red-400);
+  --color-input-focus-border: var(--color-gray-300);
+  --color-input-text: var(--color-gray-900);
+  --color-input-placeholder: var(--color-gray-400);
+  --color-input-focus-ring: var(--color-primary);
+  --input-focus-ring-width: 2px;
+  --color-input-toggle: var(--color-gray-400);
+  --color-input-toggle-hover: var(--color-gray-600);
+}

package/src/ui/Alert.tsx

@@ -1,4 +1,5 @@
 import type { ReactNode } from "react";
+import { cx } from "./cx";
 
 export interface AlertProps {
   variant?: "error" | "success" | "info" | "warning";
@@ -7,19 +8,25 @@ export interface AlertProps {
    * changing, such as a countdown, so it is not announced on every tick.
    */
   role?: "alert" | "status";
+  /**
+   * Classes for placing the alert, such as a margin. Restyle it through the theme variables
+   * instead: whether a class that clashes with the alert's own wins depends on the order Tailwind
+   * emits them in.
+   */
+  className?: string;
   children: ReactNode;
 }
 
 const styles: Record<NonNullable<AlertProps["variant"]>, string> = {
-  error: "bg-red-50 border-red-200 text-red-700",
-  success: "bg-green-50 border-green-200 text-green-700",
-  info: "bg-gray-50 border-gray-200 text-gray-700",
-  warning: "bg-amber-50 border-amber-200 text-amber-900",
+  error: "bg-alert-error-bg border-alert-error-border text-alert-error-text",
+  success: "bg-alert-success-bg border-alert-success-border text-alert-success-text",
+  info: "bg-alert-info-bg border-alert-info-border text-alert-info-text",
+  warning: "bg-alert-warning-bg border-alert-warning-border text-alert-warning-text",
 };
 
-export function Alert({ variant = "info", role = "alert", children }: AlertProps) {
+export function Alert({ variant = "info", role = "alert", className, children }: AlertProps) {
   return (
-    <div className={`rounded-lg border px-3 py-2 text-sm ${styles[variant]}`} role={role}>
+    <div className={cx("rounded-alert border px-3 py-2 text-sm", styles[variant], className)} role={role}>
       {children}
     </div>
   );

package/src/ui/PasswordInput.tsx

@@ -2,14 +2,21 @@
 
 import { EyeIcon, EyeSlashIcon } from "@heroicons/react/24/outline";
 import { useId, useState, type InputHTMLAttributes } from "react";
+import { cx } from "./cx";
 
-export interface PasswordInputProps extends InputHTMLAttributes<HTMLInputElement> {
+/** The input's type is left out: the component switches it to show and hide the value. */
+export interface PasswordInputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "type"> {
   label: string;
   error?: string;
   /** Accessible name of the toggle while the password is hidden. */
   showPasswordLabel?: string;
   /** Accessible name of the toggle while the password is visible. */
   hidePasswordLabel?: string;
+  /**
+   * Classes for placing the field, such as a margin. They go on the outer element, which holds the
+   * label, the input and the error. Restyle the field through the theme variables instead.
+   */
+  className?: string;
 }
 
 export function PasswordInput({
@@ -17,44 +24,53 @@ export function PasswordInput({
   error,
   id,
   required,
+  className,
   showPasswordLabel = "Show password",
   hidePasswordLabel = "Hide password",
   ...props
 }: PasswordInputProps) {
   const [visible, setVisible] = useState(false);
-  // Fall back to a generated id so the label is always tied to its control. Without it, a call
-  // site that passes neither id nor name renders a label pointing at nothing, which leaves
-  // screen reader users with an unidentified field.
+  // Fall back to a generated id so the label is always tied to its own control. Not the name: two
+  // fields named "password" on one page, such as sign in next to sign up, would share an id.
   const generated = useId();
-  const inputId = id ?? props.name ?? generated;
+  const inputId = id ?? generated;
+  // Built from useId rather than the name, since an id list in aria-describedby splits on spaces.
+  const errorId = `${generated}-error`;
 
   return (
-    <div>
-      <label htmlFor={inputId} className="block text-sm font-medium text-gray-700 mb-1">
+    <div className={className}>
+      <label htmlFor={inputId} className="block text-field-label font-medium text-field-label-text mb-field-label">
         {label}
-        {required && <span className="text-red-600"> *</span>}
+        {required && <span className="text-field-required"> *</span>}
       </label>
       <div className="relative">
         <input
+          {...props}
           id={inputId}
           type={visible ? "text" : "password"}
           required={required}
-          aria-required={required || undefined}
-          className={`w-full rounded-lg border px-3 py-2 pr-10 text-sm text-gray-900 placeholder-gray-400 focus:outline-none focus:ring-2 focus:ring-primary ${
-            error ? "border-red-400" : "border-gray-300"
-          }`}
-          {...props}
+          aria-required={required ? true : props["aria-required"]}
+          aria-invalid={error ? true : props["aria-invalid"]}
+          aria-describedby={cx(props["aria-describedby"], error && errorId) || undefined}
+          className={cx(
+            "w-full rounded-input border px-3 py-input-y pr-10 text-sm bg-input-bg text-input-text placeholder-input-placeholder focus:outline-hidden focus:ring-(length:--input-focus-ring-width) focus:ring-input-focus-ring",
+            error ? "border-input-border-error" : "border-input-border focus:border-input-focus-border",
+          )}
         />
         <button
           type="button"
           onClick={() => setVisible((v) => !v)}
-          className="absolute inset-y-0 right-0 px-3 text-gray-400 hover:text-gray-600"
+          className="absolute inset-y-0 right-0 px-3 text-input-toggle hover:text-input-toggle-hover"
           aria-label={visible ? hidePasswordLabel : showPasswordLabel}
         >
           {visible ? <EyeSlashIcon className="h-4 w-4" /> : <EyeIcon className="h-4 w-4" />}
         </button>
       </div>
-      {error && <p className="mt-1 text-xs text-red-600">{error}</p>}
+      {error && (
+        <p id={errorId} className="mt-1 text-xs text-field-error">
+          {error}
+        </p>
+      )}
     </div>
   );
 }

package/src/ui/cx.ts

@@ -0,0 +1,4 @@
+/** Joins class names, skipping empty ones. */
+export function cx(...classes: Array<string | false | null | undefined>): string {
+  return classes.filter(Boolean).join(" ");
+}