@sjolystinnovation/app-kit 0.21.0 → 1.0.0

package/src/session/react/ProtectedGate.tsx

@@ -4,10 +4,11 @@ import { useRouter } from "next/navigation";
 import { useEffect, type ReactNode } from "react";
 import { useSessionGate } from "./useSessionGate";
 
+/** Props for `ProtectedGate`. */
 export interface ProtectedGateProps {
-  /** Where a signed-out visitor, or a session dead on arrival, is sent. */
+  /** The path a signed-out visitor, or a session dead on arrival, is sent to. */
   loginHref: string;
-  /** What shows while the page may not render yet. */
+  /** The content shown while the page may not render yet. */
   fallback?: ReactNode | undefined;
   children: ReactNode;
 }

package/src/session/react/RoleGate.tsx

@@ -7,23 +7,24 @@ import { useSessionGate } from "./useSessionGate";
 interface RoleGateBase {
   /** The role the page needs, as it appears in `session.user.roles`. */
   role: string;
-  /** What shows while the session or its roles are not known yet. */
+  /** The content shown while the session or its roles are not known yet. */
   fallback?: ReactNode | undefined;
   children: ReactNode;
 }
 
-/** Shows `denied` to a signed-in user without the role. */
+/** The props that show `denied` to a signed-in user without the role. */
 interface RoleGateWithDenied extends RoleGateBase {
   denied: ReactNode;
   deniedHref?: never;
 }
 
-/** Sends a signed-in user without the role to `deniedHref`. */
+/** The props that send a signed-in user without the role to `deniedHref`. */
 interface RoleGateWithDeniedHref extends RoleGateBase {
   deniedHref: string;
   denied?: never;
 }
 
+/** Props for `RoleGate`. Pass either `denied` or `deniedHref`. */
 export type RoleGateProps = RoleGateWithDenied | RoleGateWithDeniedHref;
 
 /**

package/src/session/react/SessionExpiryGuard.tsx

@@ -3,8 +3,8 @@
 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 { CredentialsForm } from "./CredentialsForm";
+import { SignInRejected, type CredentialsFormStrings } from "./credentialsFormStrings";
 import { withDefaults, type TextOverrides } from "../../ui/withDefaults";
 import {
   closeSessionPrompt,
@@ -34,10 +34,11 @@ function msUntilNextChange(remaining: number): number | null {
 }
 
 
+/** Props for `SessionExpiryGuard`. */
 export interface SessionExpiryGuardProps {
-  /** Where a sign-in as a different user is sent after it is signed out. */
+  /** The path a sign-in as a different user is sent to after it is signed out. */
   loginHref: string;
-  /** Runs after the prompt signs the user back in, such as to show a toast. */
+  /** A function that 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;

package/src/{ui → session/react}/credentialsFormStrings.ts

@@ -1,6 +1,6 @@
 // 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. */
+/** Thrown inside app-kit from `onSignedIn` to refuse a sign-in. The form shows its message. Not exported. */
 export class SignInRejected extends Error {}
 
 /** The form's text. Pass the app's own language. The defaults are English. */
@@ -10,6 +10,8 @@ export interface CredentialsFormStrings {
   signIn: string;
   signingIn: string;
   invalidCredentials: string;
+  /** The text for a login the API has locked after too many failed sign-ins. */
+  lockedOut: string;
   signInUnavailable: string;
   somethingWentWrong: string;
   showPassword: string;
@@ -22,6 +24,7 @@ export const defaultCredentialsFormStrings: CredentialsFormStrings = {
   signIn: "Sign in",
   signingIn: "Signing in…",
   invalidCredentials: "Invalid email or password.",
+  lockedOut: "Too many failed attempts. This login is temporarily locked, try again later.",
   signInUnavailable: "Sign-in is unavailable right now. Try again shortly.",
   somethingWentWrong: "Something went wrong",
   showPassword: "Show password",

package/src/session/react/index.ts

@@ -4,9 +4,15 @@ 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";
 export { AppSessionProvider } from "./AppSessionProvider";
 export type { AppSessionProviderProps } from "./AppSessionProvider";
 export { RoleGate } from "./RoleGate";
 export type { RoleGateProps } from "./RoleGate";
+export { CredentialsForm } from "./CredentialsForm";
+export type { CredentialsFormProps } from "./CredentialsForm";
+export { defaultCredentialsFormStrings } from "./credentialsFormStrings";
+export type { CredentialsFormStrings } from "./credentialsFormStrings";
+export { LoginPage } from "./LoginPage";
+export type { LoginPageProps } from "./LoginPage";
+export { defaultLoginPageStrings } from "./loginPageStrings";
+export type { LoginPageStrings } from "./loginPageStrings";

package/src/{ui → session/react}/loginPageStrings.ts

@@ -4,7 +4,7 @@
 export interface LoginPageStrings {
   title: string;
   forgotPassword: string;
-  /** Shown before the register link, such as "No account?". Null leaves it out. */
+  /** The text shown before the register link, such as "No account?". Null leaves it out. */
   registerPrompt: string | null;
   register: string;
 }

package/src/session/react/sessionExpiryGuardStrings.ts

@@ -7,7 +7,7 @@
 export interface SessionExpiryGuardStrings {
   expiredTitle: string;
   expiredBody: string;
-  /** Every `{minutes}` is replaced with the minutes left. */
+  /** The warning before expiry. Every `{minutes}` is replaced with the minutes left. */
   expiringSoon: string;
   reSignIn: string;
   notRestored: string;

package/src/session/react/useSessionGate.ts

@@ -6,7 +6,7 @@ import { useState, useSyncExternalStore } from "react";
 import { getSessionPromptOpen, isTerminalSessionError, subscribeSessionPrompt } from "../expiry";
 
 /**
- * Whether a protected page may render, and whether it must stay rendered.
+ * Checks whether a protected page may render, and whether it must stay rendered.
  *
  * Every gate on the way down should use this, so they all agree. A nested layout that decides on
  * its own can blank the page. That undoes the in-place recovery the re-sign-in prompt exists for.
@@ -44,8 +44,8 @@ export function useSessionGate() {
     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.
+     * Whether the page may render. Every gate on the way down uses this one answer. A layout that
+     * decides it again can blank the page that the gate above it chose to keep.
      */
     mayRender:
       recovering ||

package/src/styles.css

@@ -90,6 +90,8 @@
   --color-admin-tab-indicator: var(--color-primary);
   --color-chart-grid: var(--color-gray-200);
   --color-chart-label: var(--color-gray-400);
+  --color-admin-stat-label: var(--color-gray-500);
+  --color-admin-stat-value: var(--color-gray-700);
 
   --radius-button: var(--radius-lg);
   --color-button-primary-bg: var(--color-primary);

package/src/testing/index.ts

@@ -20,7 +20,7 @@ export const auth = {
   update: vi.fn(),
 };
 
-/** A signed-in session with `roles`. Defaults to an admin. */
+/** Builds a signed-in session with `roles`. Defaults to an admin. */
 export function makeSession({ roles = ["Admin"], ...overrides }: Partial<Session> & { roles?: string[] } = {}): Session {
   return {
     user: { id: "1", name: "admin", email: "a@b.no", roles },
@@ -40,7 +40,7 @@ export function setSession(session: Session | null | "loading"): void {
         : { data: session, status: "authenticated" };
 }
 
-/** The `next-auth/react` module, reading `auth`. */
+/** Builds the `next-auth/react` module, reading `auth`. */
 export function nextAuthMock() {
   return {
     useSession: () => ({ ...auth.state, update: (...args: unknown[]) => auth.update(...args) }),
@@ -58,7 +58,7 @@ export const navigation = {
   router: { push: vi.fn(), replace: vi.fn(), refresh: vi.fn(), back: vi.fn(), forward: vi.fn(), prefetch: vi.fn() },
 };
 
-/** The `next/navigation` hooks, reading `navigation`. */
+/** Builds the `next/navigation` hooks, reading `navigation`. */
 export function nextNavigationMock() {
   return {
     useRouter: () => navigation.router,
@@ -79,7 +79,7 @@ export const toastSpies = {
   dismiss: vi.fn(),
 };
 
-/** The `sonner` module, or `@sjolystinnovation/app-kit/toast`. A bare `toast(text)` goes to `toastSpies.message`. */
+/** Builds the `sonner` module, or `@sjolystinnovation/app-kit/toast`. A bare `toast(text)` goes to `toastSpies.message`. */
 export function toastMock() {
   const toast = Object.assign((...args: unknown[]) => toastSpies.message(...args), {
     success: (...args: unknown[]) => toastSpies.success(...args),
@@ -94,20 +94,12 @@ export function toastMock() {
   return { toast, Toaster: () => null };
 }
 
-/** The HTTP calls of an app's axios instance as spies. */
-export const axiosSpies = { get: vi.fn(), post: vi.fn(), put: vi.fn(), patch: vi.fn(), delete: vi.fn() };
-
-/** A module whose default export is an axios instance, such as the app's `services/axiosInstance`. */
-export function axiosInstanceMock() {
-  return { default: axiosSpies };
-}
-
 /** Signs out, goes back to `/`, and clears every spy's calls and answers. */
 export function resetTestMocks(): void {
   setSession(null);
   navigation.pathname = "/";
   navigation.searchParams = new URLSearchParams();
-  for (const spy of [auth.signIn, auth.signOut, auth.getSession, auth.update, ...Object.values(navigation.router), ...Object.values(toastSpies), ...Object.values(axiosSpies)]) {
+  for (const spy of [auth.signIn, auth.signOut, auth.getSession, auth.update, ...Object.values(navigation.router), ...Object.values(toastSpies)]) {
     spy.mockReset();
   }
 }

package/src/ui/Alert.tsx

@@ -1,16 +1,17 @@
 import type { ReactNode } from "react";
 import { cx } from "./cx";
 
+/** Props for `Alert`. */
 export interface AlertProps {
   variant?: "error" | "success" | "info" | "warning";
   /**
-   * 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.
+   * The ARIA role. A screen reader interrupts for `alert`. It announces `status` without
+   * interrupting, on every change of its text. Use `none` when a separate live region announces the
+   * text. Defaults to `alert`.
    */
   role?: "alert" | "status" | "none";
   /**
-   * Classes for placing the alert, such as a margin. Restyle it through the theme variables. A
+   * The 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.
    */
   className?: string;
@@ -24,6 +25,7 @@ const styles: Record<NonNullable<AlertProps["variant"]>, string> = {
   warning: "bg-alert-warning-bg border-alert-warning-border text-alert-warning-text",
 };
 
+/** Renders a message in an error, success, info, or warning box. */
 export function Alert({ variant = "info", role = "alert", className, children }: AlertProps) {
   return (
     <div className={cx("rounded-alert border px-3 py-2 text-sm", styles[variant], className)} role={role}>

package/src/ui/ContentImage.tsx

@@ -1,42 +1,43 @@
 /** The widths the API serves an uploaded image at, as webp. */
 export const CONTENT_IMAGE_WIDTHS: readonly number[] = [384, 640, 768, 1024, 1366, 1600];
 
-/** Where the browser fetches an uploaded image. Site-relative, through the app's content images rewrite. */
+/** Builds the site-relative path where the browser fetches an uploaded image, through the app's content images rewrite. */
 export function contentImagePath(id: string, base = "/content-images"): string {
   return `${base}/${encodeURIComponent(id)}`;
 }
 
 /**
- * The `srcset` for an uploaded image. The API serves the nearest webp at or above the requested
- * width, or the original when the browser does not accept webp.
+ * Builds the `srcset` for an uploaded image. The API serves the nearest webp at or above the
+ * requested width, or the original when the browser does not accept webp.
  */
 export function contentImageSrcSet(id: string, widths: readonly number[] = CONTENT_IMAGE_WIDTHS, base?: string): string {
   return widths.map(w => `${contentImagePath(id, base)}?w=${w} ${w}w`).join(", ");
 }
 
+/** Props for `ContentImage`. */
 export interface ContentImageProps {
-  /** Uploaded image id. Null falls back to `fallbackSrc`, which is served as it is. */
+  /** The uploaded image's id. Null falls back to `fallbackSrc`, which is served as it is. */
   imageId: string | null;
-  /** Empty for an image that carries no meaning of its own, such as a decorative backdrop. */
+  /** The alt text. Leave it empty for an image that carries no meaning of its own, such as a decorative backdrop. */
   alt: string;
-  /** Widths the image is shown at. Required, since a browser assumes 100vw without it. */
+  /** The widths the image is shown at. It is required, since a browser assumes 100vw without it. */
   sizes: string;
   /** A static path for when there is no uploaded image. */
   fallbackSrc?: string | undefined;
   className?: string | undefined;
-  /** Intrinsic size, to reserve space. Only needed where the layout fixes no ratio. */
+  /** The intrinsic size, to reserve space. You only need it where the layout fixes no ratio. */
   width?: number | undefined;
   height?: number | undefined;
-  /** Set on the one image visible without scrolling. It loads eagerly, at high priority. */
+  /** Whether this is the one image visible without scrolling. That image loads eagerly, at high priority. */
   priority?: boolean | undefined;
   "aria-hidden"?: boolean | undefined;
-  /** Path the content images rewrite serves, `/content-images` by default. */
+  /** The path the content images rewrite serves. Defaults to `/content-images`. */
   base?: string | undefined;
-  /** Widths in the `srcset`. Defaults to the widths the API serves. */
+  /** The widths in the `srcset`. Defaults to the widths the API serves. */
   widths?: readonly number[] | undefined;
 }
 
-/** An image from the content API, served responsively from the `sizes` a call site declares. */
+/** Renders an image from the content API, served responsively from the `sizes` a call site declares. */
 export function ContentImage({
   imageId,
   alt,

package/src/ui/ErrorState.tsx

@@ -2,33 +2,21 @@
 
 import Link from "next/link";
 import { cx } from "./cx";
+import { defaultErrorStateStrings, type ErrorStateStrings } from "./errorStateStrings";
 import { withDefaults, type TextOverrides } from "./withDefaults";
 
-export interface ErrorStateStrings {
-  title: string;
-  body: string;
-  tryAgain: string;
-  home: string;
-}
-
-export const defaultErrorStateStrings: ErrorStateStrings = {
-  title: "Temporarily unavailable",
-  body: "We can't reach the service right now. Please try again shortly.",
-  tryAgain: "Try again",
-  home: "Go to the front page",
-};
-
+/** Props for `ErrorState`. */
 export interface ErrorStateProps {
   /** The `reset` Next passes to an `error.tsx`. It renders the page again. */
   reset: () => void;
-  /** Where the front page link goes, such as `/` or `/en`. */
+  /** The front page link's target, such as `/` or `/en`. */
   homeHref: string;
   strings?: TextOverrides<ErrorStateStrings> | undefined;
-  /** Classes for placing it, on the outer element. */
+  /** The classes for placing the component, on its outer element. */
   className?: string | undefined;
 }
 
-/** What an `error.tsx` shows when a page cannot be rendered. The response is still a 500. */
+/** Renders the content of an `error.tsx` when a page cannot be rendered. The response is still a 500. */
 export function ErrorState({ reset, homeHref, strings, className }: ErrorStateProps) {
   const text = withDefaults(defaultErrorStateStrings, strings);
   return (

package/src/ui/NotFoundState.tsx

@@ -1,30 +1,20 @@
 import Link from "next/link";
 import { cx } from "./cx";
+import { defaultNotFoundStateStrings, type NotFoundStateStrings } from "./notFoundStateStrings";
 import { withDefaults, type TextOverrides } from "./withDefaults";
 
-export interface NotFoundStrings {
-  code: string;
-  body: string;
-  home: string;
-}
-
-export const defaultNotFoundStrings: NotFoundStrings = {
-  code: "404",
-  body: "This page does not exist.",
-  home: "Go home",
-};
-
+/** Props for `NotFoundState`. */
 export interface NotFoundStateProps {
-  /** Where the home link goes, such as `/` or `/en`. */
+  /** The home link's target, such as `/` or `/en`. */
   homeHref: string;
-  strings?: TextOverrides<NotFoundStrings> | undefined;
-  /** Classes for placing it, on the outer element. */
+  strings?: TextOverrides<NotFoundStateStrings> | undefined;
+  /** The classes for placing the component, on its outer element. */
   className?: string | undefined;
 }
 
-/** What a `not-found.tsx` shows. The message is the page's heading. */
+/** Renders the content of a `not-found.tsx`. The message is the page's heading. */
 export function NotFoundState({ homeHref, strings, className }: NotFoundStateProps) {
-  const text = withDefaults(defaultNotFoundStrings, strings);
+  const text = withDefaults(defaultNotFoundStateStrings, strings);
   return (
     <div className={cx("min-h-[60vh] flex flex-col items-center justify-center gap-4 px-4 text-center", className)}>
       <span className="text-6xl font-black font-state-code text-state-code">{text.code}</span>

package/src/ui/PasswordInput.tsx

@@ -4,21 +4,22 @@ import { EyeIcon, EyeSlashIcon } from "@heroicons/react/24/outline";
 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. */
+/** Props for `PasswordInput`. They leave out the input's `type`, since the component switches it to show and hide the value. */
 export interface PasswordInputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "type"> {
   label: string;
   error?: string | undefined;
-  /** Accessible name of the toggle while the password is hidden. */
+  /** The accessible name of the toggle while the password is hidden. */
   showPasswordLabel?: string | undefined;
-  /** Accessible name of the toggle while the password is visible. */
+  /** The accessible name of the toggle while the password is visible. */
   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.
+   * The 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;
 }
 
+/** Renders a labeled password field with a button that shows and hides the value. */
 export function PasswordInput({
   label,
   error,

package/src/ui/ResetPasswordFlow.tsx

@@ -2,38 +2,56 @@
 
 import Link from "next/link";
 import { useState, type FormEvent } from "react";
+import { errorText, fieldErrorTexts } from "../api/fieldErrorText";
 import { passwordProblems, type PasswordStrings } from "../validation/passwordRules";
 import { Alert } from "./Alert";
 import { authLinkClassName, authPageClassName, authTitleClassName } from "./authClasses";
 import { PasswordInput } from "./PasswordInput";
-import { defaultResetPasswordFlowStrings, type ResetPasswordFlowStrings } from "./resetPasswordFlowStrings";
+import {
+  defaultResetPasswordFlowStrings,
+  type ResetPasswordErrorStrings,
+  type ResetPasswordFlowStrings,
+  type ResetPasswordValidationStrings,
+} from "./resetPasswordFlowStrings";
 import { TextInput } from "./TextInput";
 import { withDefaults, type TextOverrides } from "./withDefaults";
 
+/** Props for `ResetPasswordFlow`. */
 export interface ResetPasswordFlowProps {
-  /** Asks the API to email a reset code, such as `createUserService`'s `requestPasswordReset`. */
+  /** A function that asks the API to email a reset code, such as `createUserService`'s `requestPasswordReset`. */
   requestReset: (data: { email: string }) => Promise<unknown>;
-  /** Sets the new password with the code, such as `createUserService`'s `resetPassword`. */
+  /** A function that sets the new password with the code, such as `createUserService`'s `resetPassword`. */
   reset: (data: { email: string; code: string; newPassword: string }) => Promise<{ message?: string } | unknown>;
-  /** Where the sign-in links go. */
+  /** The path the sign-in links go to. */
   loginHref: string;
-  /** From the emailed link. A code opens the flow on its last step. */
+  /** The email from the emailed link. */
   initialEmail?: string | undefined;
+  /** The code from the emailed link. A code opens the flow on its last step. */
   initialCode?: string | undefined;
-  strings?: TextOverrides<ResetPasswordFlowStrings> | undefined;
-  /** Replaces the page's outer spacing, such as when the flow sits inside the app's own card. */
+  /** The flow's text. `validation` and `errors` may name only some codes, the rest keep their defaults. */
+  strings?:
+    | (TextOverrides<Omit<ResetPasswordFlowStrings, "validation" | "errors">> & {
+        validation?: TextOverrides<ResetPasswordValidationStrings> | undefined;
+        errors?: TextOverrides<ResetPasswordErrorStrings> | undefined;
+      })
+    | undefined;
+  /** The classes that replace the page's outer spacing, such as when the flow sits inside the app's own card. */
   className?: string | undefined;
   /** The password rule messages, for the app's own language. */
   passwordStrings?: TextOverrides<PasswordStrings> | undefined;
 }
 
+// The fields each step shows. A field error for any other field goes in the message above the form.
+const STEP_FIELDS = { 1: ["email"], 2: ["email", "code", "newPassword"] } as const;
+
 const button =
   "w-full rounded-button bg-button-primary-bg text-button-primary-text font-semibold py-2.5 hover:brightness-95 disabled:opacity-60 transition";
 
 /**
- * Password reset in two steps: the email asks for a code, then the code and a new password set it. The
- * new password is checked against the API's rules before it is sent. A link with the email and code,
- * such as an invite, opens on the second step.
+ * Renders password reset in two steps: the email asks for a code, then the code and a new password
+ * set it. The flow checks the new password against the API's rules before it sends it. A link with
+ * the email and code, such as an invite, opens on the second step. The API's refusals show in the
+ * app's language through `validation` and `errors`, each field's under its field.
  */
 export function ResetPasswordFlow({
   requestReset,
@@ -45,26 +63,45 @@ export function ResetPasswordFlow({
   className = authPageClassName,
   passwordStrings,
 }: ResetPasswordFlowProps) {
-  const text = withDefaults(defaultResetPasswordFlowStrings, strings);
+  const { validation: validationOverrides, errors: errorOverrides, ...textOverrides } = strings ?? {};
+  const text = withDefaults(defaultResetPasswordFlowStrings, textOverrides);
+  const validation = withDefaults(defaultResetPasswordFlowStrings.validation, validationOverrides);
+  const errors = withDefaults(defaultResetPasswordFlowStrings.errors, errorOverrides);
   const [step, setStep] = useState<1 | 2>(initialCode ? 2 : 1);
   const [email, setEmail] = useState(initialEmail);
   const [code, setCode] = useState(initialCode);
   const [newPassword, setNewPassword] = useState("");
   const [error, setError] = useState<string | null>(null);
+  // The texts for the fields the last attempt got wrong, keyed by field name.
+  const [fieldErrors, setFieldErrors] = useState<Record<string, string[]>>({});
   const [done, setDone] = useState<string | null>(null);
   const [loading, setLoading] = useState(false);
 
-  const failure = (err: unknown) => (err instanceof Error && err.message ? err.message : text.somethingWentWrong);
+  // Field errors go under the fields this step shows, and the message holds the rest.
+  const fail = (err: unknown, shown: readonly string[]) => {
+    const texts = Object.entries(fieldErrorTexts(err, validation));
+    if (texts.length === 0) {
+      setError(errorText(err, errors, text.somethingWentWrong));
+      return;
+    }
+    // Only the fields this step shows render their errors.
+    setFieldErrors(Object.fromEntries(texts));
+    // Empty when every field error has its field, which shows no message.
+    setError(texts.filter(([field]) => !shown.includes(field)).flatMap(([, list]) => list).join(" "));
+  };
+
+  const fieldError = (field: string) => fieldErrors[field]?.join(" ");
 
   const sendCode = async (event: FormEvent) => {
     event.preventDefault();
     setError(null);
+    setFieldErrors({});
     setLoading(true);
     try {
       await requestReset({ email });
       setStep(2);
     } catch (err) {
-      setError(failure(err));
+      fail(err, STEP_FIELDS[1]);
     } finally {
       setLoading(false);
     }
@@ -73,9 +110,10 @@ export function ResetPasswordFlow({
   const setPassword = async (event: FormEvent) => {
     event.preventDefault();
     setError(null);
+    setFieldErrors({});
     const problems = passwordProblems(newPassword, passwordStrings);
     if (problems.length > 0) {
-      setError(text.passwordInvalid ?? problems.join(" "));
+      setFieldErrors({ newPassword: text.passwordInvalid === null ? problems : [text.passwordInvalid] });
       return;
     }
     setLoading(true);
@@ -84,7 +122,7 @@ export function ResetPasswordFlow({
       const message = (result as { message?: unknown } | null | undefined)?.message;
       setDone(text.done ?? (typeof message === "string" ? message : ""));
     } catch (err) {
-      setError(failure(err));
+      fail(err, STEP_FIELDS[2]);
     } finally {
       setLoading(false);
     }
@@ -107,7 +145,7 @@ export function ResetPasswordFlow({
         <form onSubmit={sendCode} className="space-y-4">
           {error && <Alert variant="error">{error}</Alert>}
           {text.intro && <p className="text-sm text-auth-text">{text.intro}</p>}
-          <TextInput label={text.email} name="email" type="email" value={email} onChange={(e) => setEmail(e.target.value)} required />
+          <TextInput label={text.email} name="email" type="email" error={fieldError("email")} value={email} onChange={(e) => setEmail(e.target.value)} required />
           <button type="submit" disabled={loading} className={button}>
             {loading ? text.requestingCode : text.requestCode}
           </button>
@@ -116,9 +154,16 @@ export function ResetPasswordFlow({
         <form onSubmit={setPassword} className="space-y-4">
           {text.codeSent && <p className="text-sm text-auth-note">{text.codeSent}</p>}
           {error && <Alert variant="error">{error}</Alert>}
-          <TextInput label={text.email} name="email" type="email" value={email} onChange={(e) => setEmail(e.target.value)} required />
-          <TextInput label={text.code} name="code" value={code} onChange={(e) => setCode(e.target.value)} required />
-          <PasswordInput label={text.newPassword} name="newPassword" value={newPassword} onChange={(e) => setNewPassword(e.target.value)} required />
+          <TextInput label={text.email} name="email" type="email" error={fieldError("email")} value={email} onChange={(e) => setEmail(e.target.value)} required />
+          <TextInput label={text.code} name="code" error={fieldError("code")} value={code} onChange={(e) => setCode(e.target.value)} required />
+          <PasswordInput
+            label={text.newPassword}
+            name="newPassword"
+            error={fieldError("newPassword")}
+            value={newPassword}
+            onChange={(e) => setNewPassword(e.target.value)}
+            required
+          />
           {text.passwordHint && <p className="text-xs text-auth-hint">{text.passwordHint}</p>}
           <button type="submit" disabled={loading} className={button}>
             {loading ? text.settingPassword : text.setPassword}

package/src/ui/TextArea.tsx

@@ -3,20 +3,22 @@
 import { useCallback, useEffect, useRef, type TextareaHTMLAttributes } from "react";
 import { FieldError, FieldLabel, inputClass, useField } from "./field";
 
+/** Props for `TextArea`. */
 export interface TextAreaProps extends TextareaHTMLAttributes<HTMLTextAreaElement> {
   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 text area and the error. Restyle the field through the theme variables.
+   * The classes for placing the field, such as a margin. They go on the outer element, which holds
+   * the label, the text area, and the error. Restyle the field through the theme variables.
    */
   className?: string | undefined;
-  /** Grows with its text, from `rows` lines up to `maxRows` lines. On by default. */
+  /** Whether the box grows with its text, from `rows` lines up to `maxRows` lines. Defaults to `true`. */
   autoGrow?: boolean | undefined;
-  /** The most lines an auto-growing box shows before it scrolls. Defaults to 12. */
+  /** The most lines an auto-growing box shows before it scrolls. Defaults to `12`. */
   maxRows?: number | undefined;
 }
 
+/** Renders a labeled text area that can grow with its text. */
 export function TextArea({ label, error, className, autoGrow = true, maxRows = 12, rows = 3, onInput, ...props }: TextAreaProps) {
   const field = useField(props, error);
   const ref = useRef<HTMLTextAreaElement>(null);

package/src/ui/TextInput.tsx

@@ -3,16 +3,18 @@
 import type { InputHTMLAttributes } from "react";
 import { FieldError, FieldLabel, inputClass, useField } from "./field";
 
+/** Props for `TextInput`. */
 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.
+   * The 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;
 }
 
+/** Renders a labeled text input with an optional error message. */
 export function TextInput({ label, error, className, ...props }: TextInputProps) {
   const field = useField(props, error);