@sjolystinnovation/app-kit 0.4.0 → 0.6.0

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/session/react/useSessionGate.ts

@@ -8,9 +8,8 @@ import { getSessionPromptOpen, isTerminalSessionError, subscribeSessionPrompt }
 /**
  * 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.
+ * 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.
  */
 export function useSessionGate() {
   const { data: session, status } = useSession();
@@ -26,11 +25,10 @@ export function useSessionGate() {
   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.
+  // The path that last rendered on a healthy session. Keyed by path, so each page checks again. A
+  // session that died on the previous page cannot pass a fresh form.
+  // Set during render, which is React's supported way to derive state from changing inputs.
+  // It starts as undefined, not null, because usePathname can return null.
   const [usableAt, setUsableAt] = useState<string | null | undefined>(undefined);
   if (usable && usableAt !== pathname) setUsableAt(pathname);
   const wasUsable = usableAt === pathname;

package/src/styles.css

@@ -2,9 +2,9 @@
 @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.
+ * 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,14 +4,14 @@ 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
-   * instead: whether a class that clashes with the alert's own wins depends on the order Tailwind
-   * emits them in.
+   * 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;
   children: ReactNode;

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,20 +1,20 @@
 "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 instead.
+   * label, the input and the error. Restyle the field through the theme variables.
    */
   className?: string;
 }
@@ -22,40 +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);
-  // 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 ?? generated;
-  // Built from useId rather than the name, since an id list in aria-describedby splits 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"
@@ -66,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",
+};