@sjolystinnovation/app-kit 0.5.0 → 0.6.0

package/README.md

@@ -28,8 +28,8 @@ const nextConfig: NextConfig = {
 };
 ```
 
-The components in `@sjolystinnovation/app-kit/ui` are styled with Tailwind CSS. Import the
-package's stylesheet after Tailwind:
+The components in `@sjolystinnovation/app-kit/ui` and `session/react` are styled with Tailwind CSS.
+Import the package's stylesheet after Tailwind:
 
 ```css
 /* src/app/globals.css */
@@ -265,35 +265,54 @@ export const getRecipe = (id: number) =>
 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`. `createAuthOptions` sets it already. An app with its own next-auth
-options sets `token.error` in its `jwt` callback and copies it across in its `session` callback:
+The gate reads `session.error`. `SessionExpiryGuard` also reads `session.absoluteExpiresAt` for its
+countdown, `session.user.id` to keep the page with the user who opened it, and `session.user.email`
+to fill in the prompt. `createAuthOptions` sets all of these. An app with its own next-auth options sets them in its
+callbacks:
 
 ```ts
+const SESSION_LIFETIME_MS = 7 * 24 * 60 * 60 * 1000;
+
 callbacks: {
+  jwt({ token, user }) {
+    if (user) token.loginAt = Date.now();
+    // A token without a sign-in time counts as expired.
+    if (!token.loginAt || Date.now() - token.loginAt > SESSION_LIFETIME_MS) {
+      token.error = SESSION_ERRORS.absoluteExpiry;
+    }
+    // Also set token.error when a refresh is refused.
+    return token;
+  },
   session({ session, token }) {
+    session.user.id = token.sub ?? "";
     session.error = token.error;
+    session.absoluteExpiresAt = token.loginAt ? token.loginAt + SESSION_LIFETIME_MS : undefined;
     return session;
   },
 },
 ```
 
-For that to compile, `error` has to be on next-auth's `Session` and `JWT` types. Add it to
+For that to compile, these fields have to be on next-auth's `Session` and `JWT` types. Add them 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";
+import type { DefaultSession } from "next-auth";
 
 declare module "next-auth" {
   interface Session {
+    user: { id: string } & DefaultSession["user"];
     error?: string | undefined;
+    absoluteExpiresAt?: number | undefined;
   }
 }
 
 declare module "next-auth/jwt" {
   interface JWT {
     error?: string | undefined;
+    loginAt?: number | undefined;
   }
 }
 ```
@@ -335,37 +354,8 @@ A session that turns signed out with no prompt open blanks the page. A page the
 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>;
-}
-```
+The hook does not navigate. `ProtectedGate` below adds the redirect. Use the hook directly in a
+layout that needs its own decision, such as a role check, so it agrees with the gate.
 
 | Field | Description |
 | --- | --- |
@@ -378,6 +368,50 @@ export function ProtectedGate({
 
 `SessionGate` is the type of the result.
 
+### `ProtectedGate`
+
+From `@sjolystinnovation/app-kit/session/react`. Wraps the protected part of the app. It renders the
+page only when `useSessionGate` allows it, and sends a signed-out visitor or a session dead on
+arrival to `loginHref`. It never redirects while the re-sign-in prompt is open.
+
+```tsx
+<ProtectedGate loginHref="/login" fallback={<p>Loading…</p>}>
+  {children}
+</ProtectedGate>
+```
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `loginHref` | `string` | Where the redirect goes. An app with a locale in the path builds it for the current locale. |
+| `fallback` | `ReactNode` | What shows while the page may not render yet. Defaults to nothing. |
+
+### `SessionExpiryGuard`
+
+From `@sjolystinnovation/app-kit/session/react`. Render it once, inside the `SessionProvider`. It
+shows:
+
+- a banner in the last 30 minutes before `session.absoluteExpiresAt`, with the minutes left. That is
+  seven days after sign-in with `createAuthOptions`.
+- a banner when the session is dead
+- the re-sign-in prompt, a dialog with `CredentialsForm`, when a request or the banner opens it
+
+A sign-in in the prompt keeps the page and its form. A sign-in in the prompt as a different user is
+signed out and sent to `loginHref`, so the prompt never hands the page to another user.
+
+```tsx
+<SessionExpiryGuard
+  loginHref="/login"
+  onRestored={() => toast.success("You are signed in again.")}
+/>
+```
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `loginHref` | `string` | Where a sign-in as a different user is sent after it is signed out. |
+| `onRestored` | `() => void` | Runs after the prompt signs the user back in, such as to show a toast. |
+| `strings` | `TextOverrides<SessionExpiryGuardStrings>` | The guard's text. `{minutes}` in `expiringSoon` becomes the minutes left. The defaults are English. |
+| `formStrings` | `TextOverrides<CredentialsFormStrings>` | The text of the form in the prompt. |
+
 ### `useFormDraft(config, options)`
 
 From `@sjolystinnovation/app-kit/forms`. Keeps a form's values in `localStorage`, so a sign-out,
@@ -415,6 +449,40 @@ Drafts are stored under `<draftStoragePrefix>:draft:<owner>:<scope>`. The hook t
 `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.
 
+### `CredentialsForm`
+
+From `@sjolystinnovation/app-kit/ui`. Email and password sign-in through next-auth's credentials
+provider, with `redirect: false`, so the page stays where it is. Use it on the login page and in
+the prompt.
+
+```tsx
+<CredentialsForm onSignedIn={() => router.push("/")} strings={{ signIn: "Logg inn" }} />
+```
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `onSignedIn` | `() => void \| Promise<void>` | Runs after next-auth accepts the credentials. Throw `SignInRejected` with a message to refuse the sign-in. |
+| `initialEmail` | `string` | The email the field starts with. |
+| `children` | `ReactNode` | Extra buttons next to the submit button. |
+| `strings` | `TextOverrides<CredentialsFormStrings>` | The form's text. The defaults are English. |
+| `onPendingChange` | `(pending: boolean) => void` | Runs when a sign-in starts and ends, such as to keep a dialog open until it finishes. |
+
+A failed sign-in shows `signInUnavailable` for `SIGN_IN_ERRORS.unavailable` and
+`invalidCredentials` for any other error code. A request next-auth refuses without an error code,
+or one that throws, shows `somethingWentWrong`.
+
+`TextOverrides<T>`, from `@sjolystinnovation/app-kit/ui`, is the type of every `strings` prop. Each
+key is optional and may be `undefined`, and a missing or undefined key shows the English default.
+
+### `TextInput`
+
+From `@sjolystinnovation/app-kit/ui`. A labelled text field with the same look and props as
+`PasswordInput`, apart from the show and hide toggle. It takes the other `<input>` attributes too.
+
+```tsx
+<TextInput label="Email" name="email" type="email" required error={errors.email} />
+```
+
 ### `Alert`
 
 ```tsx
@@ -426,7 +494,7 @@ import { Alert } from "@sjolystinnovation/app-kit/ui";
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
 | `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. |
+| `role` | `"alert" \| "status" \| "none"` | `"alert"` | A screen reader announces `status` without interrupting, on every change of its text. Use `none` when a separate live region announces the text. |
 | `className` | `string` | | Classes for placing the alert, such as a margin. Restyle it through the theme variables. A clashing class wins or loses by the order Tailwind emits them in. |
 | `children` | `ReactNode` | | Content. |
 
@@ -495,10 +563,22 @@ selector such as `.dark` for a scoped theme:
 | `--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.
+| `--radius-button` | `var(--radius-lg)` |
+| `--color-button-primary-bg` | `var(--color-primary)` |
+| `--color-button-primary-text` | `var(--color-primary-foreground)` |
+| `--color-button-secondary-border` | gray 300 |
+| `--color-button-secondary-text` | gray 700 |
+| `--color-button-secondary-hover-bg` | gray 50 |
+| `--radius-dialog` | `var(--radius-xl)` |
+| `--color-dialog-backdrop` | black at 40% |
+| `--color-dialog-bg` | white |
+| `--color-dialog-title` | gray 900 |
+| `--color-dialog-text` | gray 600 |
+
+A default that points at another variable is read once for the whole page. The focus ring and the
+primary button point at `--color-primary` and `--color-primary-foreground`. A scoped theme that
+changes those also sets `--color-input-focus-ring`, `--color-button-primary-bg` and
+`--color-button-primary-text` 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.
@@ -508,8 +588,9 @@ with it and has to set the ones it uses itself.
 - Next.js 16, React 19, next-auth 4.24 or later and axios 1.20 or later, as peer dependencies the
   app installs itself.
 - `jsonwebtoken` comes with the package. `@sjolystinnovation/app-kit/auth` uses it on the server.
-- 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.
+- For `@sjolystinnovation/app-kit/ui` and the components in `session/react`: Tailwind CSS 4 and
+  `@heroicons/react` 2. The focus ring and the primary button use the theme's `primary` and
+  `primary-foreground` colours, unless their own variables are 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.5.0",
+  "version": "0.6.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",

package/src/session/react/ProtectedGate.tsx

@@ -0,0 +1,34 @@
+"use client";
+
+import { useRouter } from "next/navigation";
+import { useEffect, type ReactNode } from "react";
+import { useSessionGate } from "./useSessionGate";
+
+export interface ProtectedGateProps {
+  /** Where a signed-out visitor, or a session dead on arrival, is sent. */
+  loginHref: string;
+  /** What shows while the page may not render yet. */
+  fallback?: ReactNode | undefined;
+  children: ReactNode;
+}
+
+/**
+ * Renders a protected page only on a usable session, and keeps it rendered while the re-sign-in
+ * prompt recovers the session. Never redirects while the prompt is open.
+ */
+export function ProtectedGate({ loginHref, fallback = null, children }: ProtectedGateProps) {
+  const router = useRouter();
+  const { status, promptOpen, usable, wasUsable, mayRender } = useSessionGate();
+
+  useEffect(() => {
+    // A page opened on a dead session must not render, or the user starts work they cannot save.
+    // A session that dies later keeps the page, and the prompt recovers it in place.
+    if (promptOpen) return;
+    if (status === "unauthenticated" || (status === "authenticated" && !usable && !wasUsable)) {
+      // replace, so Back does not return to a page that only redirects again.
+      router.replace(loginHref);
+    }
+  }, [status, usable, wasUsable, promptOpen, router, loginHref]);
+
+  return mayRender ? children : fallback;
+}

package/src/session/react/SessionExpiryGuard.tsx

@@ -0,0 +1,294 @@
+"use client";
+
+import { getSession, signOut, useSession } from "next-auth/react";
+import { useEffect, useId, useRef, useState, useSyncExternalStore } from "react";
+import { Alert } from "../../ui/Alert";
+import { CredentialsForm } from "../../ui/CredentialsForm";
+import { SignInRejected, type CredentialsFormStrings } from "../../ui/credentialsFormStrings";
+import { withDefaults, type TextOverrides } from "../../ui/withDefaults";
+import {
+  closeSessionPrompt,
+  getSessionPromptOpen,
+  isTerminalSessionError,
+  openSessionPrompt,
+  subscribeSessionPrompt,
+} from "../expiry";
+import { defaultSessionExpiryGuardStrings, type SessionExpiryGuardStrings } from "./sessionExpiryGuardStrings";
+
+// The absolute expiry cannot be refreshed away, so the banner warns while there is still time.
+const WARN_BEFORE_MS = 30 * 60 * 1000;
+const MINUTE_MS = 60 * 1000;
+// The minutes left at which a screen reader hears the countdown again, after it first appears.
+const ANNOUNCE_AT_MINUTES = [10, 5, 1];
+
+// Timers pause while a computer sleeps, so no wait runs longer than this. The banner is then at most
+// this late after a wake. It also keeps every wait far below the browser's 32-bit timer limit.
+const MAX_WAIT_MS = 5 * MINUTE_MS;
+
+// How long until the banner text can next change: the warning starts, the minute count drops, or
+// the session expires. Null when nothing more can change.
+function msUntilNextChange(remaining: number): number | null {
+  if (remaining <= 0) return null;
+  const wait = remaining > WARN_BEFORE_MS ? remaining - WARN_BEFORE_MS : remaining % MINUTE_MS || MINUTE_MS;
+  return Math.min(wait, MAX_WAIT_MS);
+}
+
+
+export interface SessionExpiryGuardProps {
+  /** Where a sign-in as a different user is sent after it is signed out. */
+  loginHref: string;
+  /** Runs after the prompt signs the user back in, such as to show a toast. */
+  onRestored?: (() => void) | undefined;
+  strings?: TextOverrides<SessionExpiryGuardStrings> | undefined;
+  formStrings?: TextOverrides<CredentialsFormStrings> | undefined;
+}
+
+type User = { id?: string; email?: string | null };
+type Owner = { id: string; email: string };
+
+/**
+ * Warns before the session's absolute expiry, and signs the user back in without leaving the page
+ * when a request finds a dead session. Render it once, inside the SessionProvider.
+ */
+export function SessionExpiryGuard({ loginHref, onRestored, strings, formStrings }: SessionExpiryGuardProps) {
+  const text = withDefaults(defaultSessionExpiryGuardStrings, strings);
+  const { data: session, status } = useSession();
+  const sessionInfo = session as { user?: User; error?: string; absoluteExpiresAt?: number } | null;
+
+  const open = useSyncExternalStore(subscribeSessionPrompt, getSessionPromptOpen, () => false);
+
+  // The signed-in user. Latched, because a re-read after a lost cookie reports nobody.
+  const [owner, setOwner] = useState<Owner | null>(null);
+  const current = sessionInfo?.user;
+  // Not while the prompt is open, unless no owner is known yet. A sign-in in the prompt must be
+  // checked against the owner, not become it.
+  if (current?.id && current.id !== owner?.id && (!open || !owner)) {
+    setOwner({ id: current.id, email: current.email ?? "" });
+  }
+  // The user the session reports now, for the sign-in check when the read-back finds nobody.
+  const liveUser = useRef<User | undefined>(undefined);
+  useEffect(() => {
+    liveUser.current = current;
+  });
+
+  // The minutes left when the countdown banner opened the prompt. Null when a failed request opened
+  // it. Kept while the prompt is open, so the wording does not change under the user mid sign-in.
+  const [bannerMinutes, setBannerMinutes] = useState<number | null>(null);
+  // Cleared when the prompt closes, so a later prompt from a failed request does not reuse it.
+  const [wasOpen, setWasOpen] = useState(open);
+  if (open !== wasOpen) {
+    setWasOpen(open);
+    if (!open) setBannerMinutes(null);
+  }
+  // A sign-in is in flight. Closing then would hide its outcome.
+  const [pending, setPending] = useState(false);
+
+  // The clock lives in state, so rendering stays pure. A timer reads it again when the banner can
+  // change, and at least every few minutes.
+  const [now, setNow] = useState(() => Date.now());
+  const remaining =
+    status === "authenticated" && sessionInfo?.absoluteExpiresAt != null
+      ? sessionInfo.absoluteExpiresAt - now
+      : null;
+  useEffect(() => {
+    const wait = remaining == null ? null : msUntilNextChange(remaining);
+    if (wait == null) return;
+    const timer = window.setTimeout(() => setNow(Date.now()), wait);
+    return () => window.clearTimeout(timer);
+  }, [remaining]);
+  // A tab coming back, often after the computer slept, reads the clock again at once.
+  useEffect(() => {
+    const onVisible = () => {
+      if (document.visibilityState === "visible") setNow(Date.now());
+    };
+    document.addEventListener("visibilitychange", onVisible);
+    return () => document.removeEventListener("visibilitychange", onVisible);
+  }, []);
+
+  // Rounded up, so the last half minute reads 1 min, not 0.
+  const minutesLeft =
+    remaining != null && remaining > 0 && remaining <= WARN_BEFORE_MS ? Math.ceil(remaining / MINUTE_MS) : null;
+  const expired =
+    status === "authenticated" &&
+    (isTerminalSessionError(sessionInfo?.error) || (remaining != null && remaining <= 0));
+
+  const countdown = (minutes: number | null) => text.expiringSoon.replaceAll("{minutes}", String(minutes));
+
+  // The minutes a screen reader last heard. Every change of a status region is announced, so it
+  // changes only when the countdown starts and when it passes one of ANNOUNCE_AT_MINUTES.
+  const [announcedMinutes, setAnnouncedMinutes] = useState<number | null>(null);
+  const announceNow =
+    minutesLeft == null
+      ? null
+      : announcedMinutes == null || ANNOUNCE_AT_MINUTES.some((at) => minutesLeft <= at && announcedMinutes > at)
+        ? minutesLeft
+        : announcedMinutes;
+  if (announceNow !== announcedMinutes) setAnnouncedMinutes(announceNow);
+
+  // An open prompt stops the gate from redirecting, so the prompt closes when the guard unmounts.
+  useEffect(() => closeSessionPrompt, []);
+
+  // Who the prompt opened for. signIn replaces the session before it resolves, so the live owner
+  // would already be the account that just signed in.
+  const promptOwner = useRef<Owner | null>(null);
+  useEffect(() => {
+    if (!open) {
+      promptOwner.current = null;
+      return;
+    }
+    // Only on the way open. Reassigning while open would adopt the new account.
+    promptOwner.current ??= owner;
+  }, [open, owner]);
+
+  const dialog = useRef<HTMLDivElement | null>(null);
+  // The keydown handler is bound once per opening, so it reads pending through a ref.
+  const pendingRef = useRef(false);
+  const onPendingChange = (next: boolean) => {
+    pendingRef.current = next;
+    setPending(next);
+  };
+  const titleId = useId();
+
+  // Escape closes the dialog, except while a sign-in is pending. Tab cycles inside the dialog, even
+  // when focus has left it. Focus starts on the password field and returns where it was afterwards.
+  useEffect(() => {
+    if (!open) return;
+    const previous = document.activeElement as HTMLElement | null;
+    const focusable = () =>
+      Array.from(dialog.current?.querySelectorAll<HTMLElement>("input, button:not([disabled])") ?? []);
+
+    focusable()
+      .find((element) => element instanceof HTMLInputElement && element.type === "password")
+      ?.focus();
+
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (event.key === "Escape") {
+        if (!pendingRef.current) closeSessionPrompt();
+        return;
+      }
+      if (event.key !== "Tab") return;
+      const elements = focusable();
+      const first = elements[0];
+      const last = elements[elements.length - 1];
+      if (!first || !last) return;
+      const edge = event.shiftKey ? first : last;
+      const outside = !dialog.current?.contains(document.activeElement);
+      if (outside || document.activeElement === edge) {
+        event.preventDefault();
+        (event.shiftKey ? last : first).focus();
+      }
+    };
+
+    document.addEventListener("keydown", onKeyDown);
+    return () => {
+      document.removeEventListener("keydown", onKeyDown);
+      // The control that opened the prompt may be gone by now, such as the banner's button.
+      if (previous?.isConnected) previous.focus();
+    };
+  }, [open]);
+
+  // A session read already in flight can answer after the sign-out and set the cookie again. So
+  // the session is checked and the sign-out repeated, and the page is left whatever happens.
+  const signOutFully = async () => {
+    for (let attempt = 0; attempt < 3; attempt++) {
+      try {
+        await signOut({ redirect: false });
+        if (!(await getSession({ broadcast: false }))) break;
+      } catch {
+        break;
+      }
+    }
+    window.location.assign(loginHref);
+  };
+
+  const signedIn = async () => {
+    // Read the session back, and only report success when it can save.
+    let next = (await getSession()) as { user?: User; error?: string } | null;
+    // A failed read-back with nobody known yet says nothing about who signed in, so read again.
+    for (let attempt = 0; attempt < 2 && !next && !liveUser.current?.id; attempt++) {
+      next = (await getSession({ broadcast: false })) as { user?: User; error?: string } | null;
+    }
+    // The form on the page belongs to whoever opened it. signIn has already replaced the session,
+    // so a different account is signed out, even when the read-back failed. The opener's draft
+    // stays stored under the opener's id, and comes back when they sign in.
+    const opener = promptOwner.current ?? owner;
+    // A session without an id counts as another account. When the read-back failed, only a known
+    // id counts.
+    const signedInId = next ? next.user?.id : liveUser.current?.id;
+    if (opener && (next || signedInId) && signedInId !== opener.id) {
+      await signOutFully();
+      throw new SignInRejected(text.wrongUser);
+    }
+    if (!next || isTerminalSessionError(next.error)) {
+      throw new SignInRejected(text.notRestored);
+    }
+    closeSessionPrompt();
+    onRestored?.();
+  };
+
+  return (
+    <>
+      {/* Mounted from the start, because a screen reader skips text that arrives with its region. */}
+      <div role="status" className="sr-only">
+        {!expired && announcedMinutes != null ? countdown(announcedMinutes) : ""}
+      </div>
+      <div role="alert" className="sr-only">
+        {expired ? text.expiredBody : ""}
+      </div>
+      {(expired || minutesLeft != null) && (
+        // At the bottom, because a sticky navbar usually holds the top at the same stacking level.
+        <div className="fixed inset-x-0 bottom-0 z-40">
+          <Alert variant="warning" role="none">
+            <div className="max-w-5xl mx-auto flex flex-wrap items-center justify-between gap-2">
+              <span>{expired ? text.expiredBody : countdown(minutesLeft)}</span>
+              <button
+                type="button"
+                onClick={() => {
+                  if (!expired) setBannerMinutes(minutesLeft);
+                  openSessionPrompt();
+                }}
+                className="font-semibold underline underline-offset-2"
+              >
+                {text.reSignIn}
+              </button>
+            </div>
+          </Alert>
+        </div>
+      )}
+
+      {open && (
+        <div className="fixed inset-0 z-50 flex items-center justify-center bg-dialog-backdrop px-4">
+          <div
+            ref={dialog}
+            role="dialog"
+            aria-modal="true"
+            aria-labelledby={titleId}
+            className="w-full max-w-sm rounded-dialog bg-dialog-bg p-6 shadow-xl"
+          >
+            <h2 id={titleId} className="text-lg font-bold text-dialog-title">
+              {bannerMinutes != null ? text.reSignIn : text.expiredTitle}
+            </h2>
+            <p className="mt-1 mb-4 text-sm text-dialog-text">
+              {bannerMinutes != null ? countdown(bannerMinutes) : text.expiredBody}
+            </p>
+            <CredentialsForm
+              initialEmail={owner?.email ?? ""}
+              onSignedIn={signedIn}
+              strings={formStrings}
+              onPendingChange={onPendingChange}
+            >
+              <button
+                type="button"
+                onClick={closeSessionPrompt}
+                disabled={pending}
+                className="rounded-button border border-button-secondary-border px-4 text-sm font-medium text-button-secondary-text hover:bg-button-secondary-hover-bg"
+              >
+                {text.close}
+              </button>
+            </CredentialsForm>
+          </div>
+        </div>
+      )}
+    </>
+  );
+}

package/src/session/react/index.ts

@@ -1,2 +1,8 @@
+export { ProtectedGate } from "./ProtectedGate";
+export type { ProtectedGateProps } from "./ProtectedGate";
+export { SessionExpiryGuard } from "./SessionExpiryGuard";
+export type { SessionExpiryGuardProps } from "./SessionExpiryGuard";
+export { defaultSessionExpiryGuardStrings } from "./sessionExpiryGuardStrings";
+export type { SessionExpiryGuardStrings } from "./sessionExpiryGuardStrings";
 export { useSessionGate } from "./useSessionGate";
 export type { SessionGate } from "./useSessionGate";

package/src/session/react/sessionExpiryGuardStrings.ts

@@ -0,0 +1,26 @@
+// Plain values, with no "use client", so a server component can import them.
+
+/**
+ * The guard's text. Pass the app's own language. The defaults are English. Plain strings, so a
+ * server component can pass them.
+ */
+export interface SessionExpiryGuardStrings {
+  expiredTitle: string;
+  expiredBody: string;
+  /** Every `{minutes}` is replaced with the minutes left. */
+  expiringSoon: string;
+  reSignIn: string;
+  notRestored: string;
+  wrongUser: string;
+  close: string;
+}
+
+export const defaultSessionExpiryGuardStrings: SessionExpiryGuardStrings = {
+  expiredTitle: "Session expired",
+  expiredBody: "Your session has expired. Sign in again to save.",
+  expiringSoon: "Your session expires in {minutes} min. Sign in again to continue without interruption.",
+  reSignIn: "Sign in again",
+  notRestored: "We could not renew the session. Try again.",
+  wrongUser: "This page belongs to a different user. Sign in with the same account.",
+  close: "Close",
+};

package/src/styles.css

@@ -2,9 +2,9 @@
 @source ".";
 
 /*
- * Design tokens for the components. The defaults are stock Tailwind values, except the focus ring,
- * which uses the theme's --color-primary. Set a token in the app's own @theme to restyle, or in a
- * selector such as .dark for a scoped theme.
+ * Design tokens for the components. The defaults are stock Tailwind values, except the focus ring
+ * and the primary button, which use the theme's --color-primary and --color-primary-foreground. Set
+ * a token 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);
@@ -40,4 +40,17 @@
   --input-focus-ring-width: 2px;
   --color-input-toggle: var(--color-gray-400);
   --color-input-toggle-hover: var(--color-gray-600);
+
+  --radius-button: var(--radius-lg);
+  --color-button-primary-bg: var(--color-primary);
+  --color-button-primary-text: var(--color-primary-foreground);
+  --color-button-secondary-border: var(--color-gray-300);
+  --color-button-secondary-text: var(--color-gray-700);
+  --color-button-secondary-hover-bg: var(--color-gray-50);
+
+  --radius-dialog: var(--radius-xl);
+  --color-dialog-backdrop: color-mix(in oklab, var(--color-black) 40%, transparent);
+  --color-dialog-bg: var(--color-white);
+  --color-dialog-title: var(--color-gray-900);
+  --color-dialog-text: var(--color-gray-600);
 }

package/src/ui/Alert.tsx

@@ -4,10 +4,11 @@ import { cx } from "./cx";
 export interface AlertProps {
   variant?: "error" | "success" | "info" | "warning";
   /**
-   * Defaults to alert, which a screen reader interrupts for. Use status for text that keeps
-   * changing, such as a countdown, so it is not announced on every tick.
+   * Defaults to alert, which a screen reader interrupts for. A screen reader announces status
+   * without interrupting, on every change of its text. Use none when a separate live region
+   * announces the text.
    */
-  role?: "alert" | "status";
+  role?: "alert" | "status" | "none";
   /**
    * Classes for placing the alert, such as a margin. Restyle it through the theme variables. A
    * class that clashes with the alert's own wins or loses by the order Tailwind emits them in.

package/src/ui/CredentialsForm.tsx

@@ -0,0 +1,113 @@
+"use client";
+
+import { signIn } from "next-auth/react";
+import { useState, type FormEvent, type ReactNode } from "react";
+import { SIGN_IN_ERRORS } from "../session/expiry";
+import { Alert } from "./Alert";
+import { PasswordInput } from "./PasswordInput";
+import {
+  SignInRejected,
+  defaultCredentialsFormStrings,
+  type CredentialsFormStrings,
+} from "./credentialsFormStrings";
+import { TextInput } from "./TextInput";
+import { withDefaults, type TextOverrides } from "./withDefaults";
+
+
+export interface CredentialsFormProps {
+  initialEmail?: string | undefined;
+  /** Runs after next-auth accepts the credentials. Throw `SignInRejected` to refuse with a reason. */
+  onSignedIn: () => void | Promise<void>;
+  /** Extra buttons next to the submit button, such as a close button. */
+  children?: ReactNode;
+  strings?: TextOverrides<CredentialsFormStrings> | undefined;
+  /** Runs when a sign-in starts and when it ends, such as to stop a dialog closing mid-request. */
+  onPendingChange?: ((pending: boolean) => void) | undefined;
+}
+
+// next-auth answers a stale CSRF token with its own sign-in page and ?csrf=true.
+function refusedForCsrf(url: string | null | undefined): boolean {
+  if (!url) return false;
+  const parsed = new URL(url, window.location.origin);
+  return parsed.pathname.endsWith("/signin") && parsed.searchParams.get("csrf") === "true";
+}
+
+/** Email and password sign-in through next-auth's credentials provider. */
+export function CredentialsForm({
+  initialEmail = "",
+  onSignedIn,
+  children,
+  strings,
+  onPendingChange,
+}: CredentialsFormProps) {
+  const text = withDefaults(defaultCredentialsFormStrings, strings);
+  const [email, setEmail] = useState(initialEmail);
+  // Follows initialEmail until the user types, so an email learned after mount still fills in.
+  const [emailTyped, setEmailTyped] = useState(false);
+  if (!emailTyped && email !== initialEmail) setEmail(initialEmail);
+  const [password, setPassword] = useState("");
+  const [error, setError] = useState<string | null>(null);
+  const [submitting, setSubmitting] = useState(false);
+
+  const handleSubmit = async (event: FormEvent) => {
+    event.preventDefault();
+    setError(null);
+    setSubmitting(true);
+    onPendingChange?.(true);
+    try {
+      const result = await signIn("credentials", { email, password, redirect: false });
+      if (result?.error) {
+        setError(result.error === SIGN_IN_ERRORS.unavailable ? text.signInUnavailable : text.invalidCredentials);
+        return;
+      }
+      // next-auth reports a stale CSRF token as a success, see refusedForCsrf.
+      if (!result?.ok || refusedForCsrf(result.url)) {
+        setError(text.somethingWentWrong);
+        return;
+      }
+      await onSignedIn();
+      setPassword("");
+    } catch (caught) {
+      setError(caught instanceof SignInRejected ? caught.message : text.somethingWentWrong);
+    } finally {
+      setSubmitting(false);
+      onPendingChange?.(false);
+    }
+  };
+
+  return (
+    <form onSubmit={handleSubmit} className="space-y-4">
+      {error && <Alert variant="error">{error}</Alert>}
+      <TextInput
+        label={text.email}
+        name="email"
+        type="email"
+        value={email}
+        onChange={(e) => {
+          setEmailTyped(true);
+          setEmail(e.target.value);
+        }}
+        required
+      />
+      <PasswordInput
+        label={text.password}
+        name="password"
+        value={password}
+        onChange={(e) => setPassword(e.target.value)}
+        required
+        showPasswordLabel={text.showPassword}
+        hidePasswordLabel={text.hidePassword}
+      />
+      <div className="flex gap-2">
+        <button
+          type="submit"
+          disabled={submitting}
+          className="flex-1 rounded-button bg-button-primary-bg text-button-primary-text font-semibold py-2.5 hover:brightness-95 disabled:opacity-60 transition"
+        >
+          {submitting ? text.signingIn : text.signIn}
+        </button>
+        {children}
+      </div>
+    </form>
+  );
+}

package/src/ui/PasswordInput.tsx

@@ -1,17 +1,17 @@
 "use client";
 
 import { EyeIcon, EyeSlashIcon } from "@heroicons/react/24/outline";
-import { useId, useState, type InputHTMLAttributes } from "react";
-import { cx } from "./cx";
+import { useState, type InputHTMLAttributes } from "react";
+import { FieldError, FieldLabel, inputClass, useField } from "./field";
 
 /** 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;
+  error?: string | undefined;
   /** Accessible name of the toggle while the password is hidden. */
-  showPasswordLabel?: string;
+  showPasswordLabel?: string | undefined;
   /** Accessible name of the toggle while the password is visible. */
-  hidePasswordLabel?: string;
+  hidePasswordLabel?: string | undefined;
   /**
    * 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.
@@ -22,39 +22,25 @@ export interface PasswordInputProps extends Omit<InputHTMLAttributes<HTMLInputEl
 export function PasswordInput({
   label,
   error,
-  id,
-  required,
   className,
   showPasswordLabel = "Show password",
   hidePasswordLabel = "Hide password",
   ...props
 }: PasswordInputProps) {
   const [visible, setVisible] = useState(false);
-  // A generated id ties the label to its own control, even when two fields on a page share a name.
-  const generated = useId();
-  const inputId = id ?? generated;
-  // From useId, which has no spaces. aria-describedby splits its ids on spaces.
-  const errorId = `${generated}-error`;
+  const field = useField(props, error);
 
   return (
     <div className={className}>
-      <label htmlFor={inputId} className="block text-field-label font-medium text-field-label-text mb-field-label">
+      <FieldLabel htmlFor={field.inputId} required={props.required}>
         {label}
-        {required && <span className="text-field-required"> *</span>}
-      </label>
+      </FieldLabel>
       <div className="relative">
         <input
           {...props}
-          id={inputId}
+          {...field.inputProps}
           type={visible ? "text" : "password"}
-          required={required}
-          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",
-          )}
+          className={inputClass(error, "pr-10")}
         />
         <button
           type="button"
@@ -65,11 +51,7 @@ export function PasswordInput({
           {visible ? <EyeSlashIcon className="h-4 w-4" /> : <EyeIcon className="h-4 w-4" />}
         </button>
       </div>
-      {error && (
-        <p id={errorId} className="mt-1 text-xs text-field-error">
-          {error}
-        </p>
-      )}
+      <FieldError id={field.errorId} error={error} />
     </div>
   );
 }

package/src/ui/TextInput.tsx

@@ -0,0 +1,28 @@
+"use client";
+
+import type { InputHTMLAttributes } from "react";
+import { FieldError, FieldLabel, inputClass, useField } from "./field";
+
+export interface TextInputProps extends InputHTMLAttributes<HTMLInputElement> {
+  label: string;
+  error?: string | undefined;
+  /**
+   * 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.
+   */
+  className?: string | undefined;
+}
+
+export function TextInput({ label, error, className, ...props }: TextInputProps) {
+  const field = useField(props, error);
+
+  return (
+    <div className={className}>
+      <FieldLabel htmlFor={field.inputId} required={props.required}>
+        {label}
+      </FieldLabel>
+      <input {...props} {...field.inputProps} className={inputClass(error)} />
+      <FieldError id={field.errorId} error={error} />
+    </div>
+  );
+}

package/src/ui/credentialsFormStrings.ts

@@ -0,0 +1,29 @@
+// Plain values, with no "use client", so a server component can import them.
+
+/** Thrown from `onSignedIn` to refuse a sign-in. Its message is shown in the form. */
+export class SignInRejected extends Error {}
+
+/** The form's text. Pass the app's own language. The defaults are English. */
+export interface CredentialsFormStrings {
+  email: string;
+  password: string;
+  signIn: string;
+  signingIn: string;
+  invalidCredentials: string;
+  signInUnavailable: string;
+  somethingWentWrong: string;
+  showPassword: string;
+  hidePassword: string;
+}
+
+export const defaultCredentialsFormStrings: CredentialsFormStrings = {
+  email: "Email",
+  password: "Password",
+  signIn: "Sign in",
+  signingIn: "Signing in…",
+  invalidCredentials: "Invalid email or password.",
+  signInUnavailable: "Sign-in is unavailable right now. Try again shortly.",
+  somethingWentWrong: "Something went wrong",
+  showPassword: "Show password",
+  hidePassword: "Hide password",
+};

package/src/ui/field.tsx

@@ -0,0 +1,51 @@
+"use client";
+
+import { useId, type InputHTMLAttributes, type ReactNode } from "react";
+import { cx } from "./cx";
+
+/** The ids and aria attributes a labelled input needs, from the caller's own props. */
+export function useField(props: Pick<InputHTMLAttributes<HTMLInputElement>, "id" | "required" | "aria-required" | "aria-invalid" | "aria-describedby">, error: string | undefined) {
+  // A generated id ties the label to its own control, even when two fields on a page share a name.
+  const generated = useId();
+  const inputId = props.id ?? generated;
+  // From useId, which has no spaces. aria-describedby splits its ids on spaces.
+  const errorId = `${generated}-error`;
+  return {
+    inputId,
+    errorId,
+    inputProps: {
+      id: inputId,
+      required: props.required,
+      "aria-required": props.required ? true : props["aria-required"],
+      "aria-invalid": error ? true : props["aria-invalid"],
+      "aria-describedby": cx(props["aria-describedby"], error && errorId) || undefined,
+    },
+  };
+}
+
+/** The input's look, with the error border when there is an error. */
+export function inputClass(error: string | undefined, extra?: string): string {
+  return cx(
+    "w-full rounded-input border px-3 py-input-y 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",
+    extra,
+    error ? "border-input-border-error" : "border-input-border focus:border-input-focus-border",
+  );
+}
+
+export function FieldLabel({ htmlFor, required, children }: { htmlFor: string; required: boolean | undefined; children: ReactNode }) {
+  return (
+    <label htmlFor={htmlFor} className="block text-field-label font-medium text-field-label-text mb-field-label">
+      {children}
+      {required && <span className="text-field-required" aria-hidden="true"> *</span>}
+    </label>
+  );
+}
+
+export function FieldError({ id, error }: { id: string; error: string | undefined }) {
+  if (!error) return null;
+  return (
+    <p id={id} className="mt-1 text-xs text-field-error">
+      {error}
+    </p>
+  );
+}

package/src/ui/index.ts

@@ -1,4 +1,11 @@
 export { Alert } from "./Alert";
 export type { AlertProps } from "./Alert";
+export { CredentialsForm } from "./CredentialsForm";
+export type { CredentialsFormProps } from "./CredentialsForm";
+export { SignInRejected, defaultCredentialsFormStrings } from "./credentialsFormStrings";
+export type { CredentialsFormStrings } from "./credentialsFormStrings";
 export { PasswordInput } from "./PasswordInput";
 export type { PasswordInputProps } from "./PasswordInput";
+export { TextInput } from "./TextInput";
+export type { TextInputProps } from "./TextInput";
+export type { TextOverrides } from "./withDefaults";

package/src/ui/withDefaults.ts

@@ -0,0 +1,14 @@
+/** Text overrides where any key may be missing or undefined. */
+export type TextOverrides<T> = { [K in keyof T]?: T[K] | undefined };
+
+/**
+ * Fills in defaults for any string that is missing or undefined, so a key missing from an app's
+ * dictionary still shows the default text.
+ */
+export function withDefaults<T extends object>(defaults: T, overrides: TextOverrides<T> | undefined): T {
+  const result = { ...defaults };
+  for (const [key, value] of Object.entries(overrides ?? {})) {
+    if (value !== undefined) (result as Record<string, unknown>)[key] = value;
+  }
+  return result;
+}