@sjolystinnovation/app-kit 0.22.0 → 1.0.0

package/src/session/index.ts

@@ -5,6 +5,5 @@ export {
   getSessionPromptOpen,
   isTerminalSessionError,
   openSessionPrompt,
-  subscribeSessionPrompt,
 } from "./expiry";
 export type { SessionError } from "./expiry";

package/src/session/react/CredentialsForm.tsx

@@ -17,7 +17,7 @@ import { withDefaults, type TextOverrides } from "../../ui/withDefaults";
 /** Props for `CredentialsForm`. */
 export interface CredentialsFormProps {
   initialEmail?: string | undefined;
-  /** A function that runs after next-auth accepts the credentials. Throw `SignInRejected` from it to refuse with a reason. */
+  /** A function that runs after next-auth accepts the credentials. If it throws, the form shows its generic error. */
   onSignedIn: () => void | Promise<void>;
   /** The extra buttons next to the submit button, such as a close button. */
   children?: ReactNode;
@@ -26,6 +26,12 @@ export interface CredentialsFormProps {
   onPendingChange?: ((pending: boolean) => void) | undefined;
 }
 
+// The form's text for each sign-in error. Any other error reads as wrong credentials.
+function signInErrorText(error: string, text: CredentialsFormStrings): string {
+  if (error === SIGN_IN_ERRORS.unavailable) return text.signInUnavailable;
+  return error === SIGN_IN_ERRORS.lockedOut ? text.lockedOut : text.invalidCredentials;
+}
+
 // 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;
@@ -58,7 +64,7 @@ export function CredentialsForm({
     try {
       const result = await signIn("credentials", { email, password, redirect: false });
       if (result?.error) {
-        setError(result.error === SIGN_IN_ERRORS.unavailable ? text.signInUnavailable : text.invalidCredentials);
+        setError(signInErrorText(result.error, text));
         return;
       }
       // next-auth reports a stale CSRF token as a success, see refusedForCsrf.

package/src/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. The form shows its message. */
+/** 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

@@ -10,7 +10,7 @@ export { RoleGate } from "./RoleGate";
 export type { RoleGateProps } from "./RoleGate";
 export { CredentialsForm } from "./CredentialsForm";
 export type { CredentialsFormProps } from "./CredentialsForm";
-export { SignInRejected, defaultCredentialsFormStrings } from "./credentialsFormStrings";
+export { defaultCredentialsFormStrings } from "./credentialsFormStrings";
 export type { CredentialsFormStrings } from "./credentialsFormStrings";
 export { LoginPage } from "./LoginPage";
 export type { LoginPageProps } from "./LoginPage";

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

@@ -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() };
-
-/** Builds 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/ErrorState.tsx

@@ -2,23 +2,9 @@
 
 import Link from "next/link";
 import { cx } from "./cx";
+import { defaultErrorStateStrings, type ErrorStateStrings } from "./errorStateStrings";
 import { withDefaults, type TextOverrides } from "./withDefaults";
 
-/** The error page's text. Pass the app's own language. The defaults are English. */
-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. */

package/src/ui/NotFoundState.tsx

@@ -1,20 +1,8 @@
 import Link from "next/link";
 import { cx } from "./cx";
+import { defaultNotFoundStateStrings, type NotFoundStateStrings } from "./notFoundStateStrings";
 import { withDefaults, type TextOverrides } from "./withDefaults";
 
-/** The not-found page's text. Pass the app's own language. The defaults are English. */
-export interface NotFoundStateStrings {
-  code: string;
-  body: string;
-  home: string;
-}
-
-export const defaultNotFoundStateStrings: NotFoundStateStrings = {
-  code: "404",
-  body: "This page does not exist.",
-  home: "Go home",
-};
-
 /** Props for `NotFoundState`. */
 export interface NotFoundStateProps {
   /** The home link's target, such as `/` or `/en`. */

package/src/ui/ResetPasswordFlow.tsx

@@ -2,11 +2,17 @@
 
 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";
 
@@ -22,20 +28,30 @@ export interface ResetPasswordFlowProps {
   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;
+  /** 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";
 
 /**
  * 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 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,
@@ -47,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);
     }
@@ -75,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);
@@ -86,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);
     }
@@ -109,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>
@@ -118,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/errorStateStrings.ts

@@ -0,0 +1,16 @@
+// Plain values, with no "use client", so a server component can import them.
+
+/** The error page's text. Pass the app's own language. The defaults are English. */
+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",
+};

package/src/ui/index.ts

@@ -1,17 +1,21 @@
 export { Alert } from "./Alert";
 export type { AlertProps } from "./Alert";
-export { ContentImage, CONTENT_IMAGE_WIDTHS, contentImagePath, contentImageSrcSet } from "./ContentImage";
+export { ContentImage, contentImagePath, contentImageSrcSet } from "./ContentImage";
 export type { ContentImageProps } from "./ContentImage";
-export { ErrorState, defaultErrorStateStrings } from "./ErrorState";
-export type { ErrorStateProps, ErrorStateStrings } from "./ErrorState";
-export { NotFoundState, defaultNotFoundStateStrings } from "./NotFoundState";
-export type { NotFoundStateProps, NotFoundStateStrings } from "./NotFoundState";
+export { ErrorState } from "./ErrorState";
+export type { ErrorStateProps } from "./ErrorState";
+export { defaultErrorStateStrings } from "./errorStateStrings";
+export type { ErrorStateStrings } from "./errorStateStrings";
+export { NotFoundState } from "./NotFoundState";
+export type { NotFoundStateProps } from "./NotFoundState";
+export { defaultNotFoundStateStrings } from "./notFoundStateStrings";
+export type { NotFoundStateStrings } from "./notFoundStateStrings";
 export { PasswordInput } from "./PasswordInput";
 export type { PasswordInputProps } from "./PasswordInput";
 export { ResetPasswordFlow } from "./ResetPasswordFlow";
 export type { ResetPasswordFlowProps } from "./ResetPasswordFlow";
 export { defaultResetPasswordFlowStrings } from "./resetPasswordFlowStrings";
-export type { ResetPasswordFlowStrings } from "./resetPasswordFlowStrings";
+export type { ResetPasswordErrorStrings, ResetPasswordFlowStrings, ResetPasswordValidationStrings } from "./resetPasswordFlowStrings";
 export { TextArea } from "./TextArea";
 export type { TextAreaProps } from "./TextArea";
 export { TextInput } from "./TextInput";

package/src/ui/notFoundStateStrings.ts

@@ -0,0 +1,14 @@
+// Plain values, with no "use client", so a server component can import them.
+
+/** The not-found page's text. Pass the app's own language. The defaults are English. */
+export interface NotFoundStateStrings {
+  code: string;
+  body: string;
+  home: string;
+}
+
+export const defaultNotFoundStateStrings: NotFoundStateStrings = {
+  code: "404",
+  body: "This page does not exist.",
+  home: "Go home",
+};

package/src/ui/resetPasswordFlowStrings.ts

@@ -1,5 +1,32 @@
 // Plain values, with no "use client", so a server component can import them.
 
+/**
+ * The flow's text for each field error code of SjolystInnovation.AppKit.Auth's reset endpoints,
+ * shown under the email, code or new password field. `{max}` in `passwordTooShort` becomes the
+ * API's least number of characters. The flow shows the API's own message for a code that is not
+ * here, such as `weakPassword` from a password rule the app adds.
+ */
+export interface ResetPasswordValidationStrings {
+  required: string;
+  invalidEmail: string;
+  passwordTooShort: string;
+  passwordRequiresDigit: string;
+  passwordRequiresLower: string;
+  passwordRequiresUpper: string;
+  passwordRequiresNonAlphanumeric: string;
+}
+
+/**
+ * The flow's text for each code of SjolystInnovation.AppKit.Auth's reset endpoints that is not
+ * about one field. The flow shows the API's own message for a code that is not here.
+ */
+export interface ResetPasswordErrorStrings {
+  /** The code is wrong or expired, or the email has no active account. */
+  invalidResetCode: string;
+  /** Five wrong codes in a row. The user has to ask for a new code. */
+  tooManyResetAttempts: string;
+}
+
 /**
  * The reset flow's text. Pass the app's own language. The defaults are English. A text that is null
  * is left out of the page.
@@ -29,6 +56,10 @@ export interface ResetPasswordFlowStrings {
   /** The text shown for a password the rules refuse. Null lists each rule it breaks. */
   passwordInvalid: string | null;
   somethingWentWrong: string;
+  /** The field error texts, by code. Any code left out keeps its default. */
+  validation: ResetPasswordValidationStrings;
+  /** The texts for the other refusals, by code. Any code left out keeps its default. */
+  errors: ResetPasswordErrorStrings;
 }
 
 export const defaultResetPasswordFlowStrings: ResetPasswordFlowStrings = {
@@ -49,4 +80,17 @@ export const defaultResetPasswordFlowStrings: ResetPasswordFlowStrings = {
   done: null,
   passwordInvalid: null,
   somethingWentWrong: "Something went wrong",
+  validation: {
+    required: "Required.",
+    invalidEmail: "Not a valid email address.",
+    passwordTooShort: "Passwords must be at least {max} characters.",
+    passwordRequiresDigit: "Passwords must have at least one digit ('0'-'9').",
+    passwordRequiresLower: "Passwords must have at least one lowercase ('a'-'z').",
+    passwordRequiresUpper: "Passwords must have at least one uppercase ('A'-'Z').",
+    passwordRequiresNonAlphanumeric: "Passwords must have at least one non alphanumeric character.",
+  },
+  errors: {
+    invalidResetCode: "Invalid or expired reset code.",
+    tooManyResetAttempts: "Too many attempts. Request a new reset code.",
+  },
 };