@sjolystinnovation/app-kit 0.17.0 → 0.19.0

package/README.md

@@ -264,6 +264,10 @@ export const getRecipe = (id: number) =>
 `target`, so an edit shows at once. It posts to `/api/revalidate` unless `endpoint` says otherwise.
 It never throws. On failure the pages' own revalidate window is the fallback.
 
+`apiFieldErrors(error)` reads the per-field messages of an ASP.NET validation problem from a failed
+call or its body, keyed in camelCase to match the form: `{ errors: { OrgNumber: ["..."] } }` becomes
+`{ orgNumber: ["..."] }`. It answers null when there are none, so the form falls back to one message.
+
 `createPublicClient(baseURL)` is the same without the session, for the API's anonymous endpoints. An
 empty `baseURL` throws, and requests only go to `baseURL`.
 
@@ -835,6 +839,39 @@ 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`.
 
+### `ResetPasswordFlow`
+
+From `@sjolystinnovation/app-kit/ui`. The password reset page in two steps: the email asks for a
+code, then the code and a new password set it. The password is checked against the same rules as
+`passwordSchema` before it is sent, without loading zod. An emailed link with the email and code,
+such as an invite, opens it on the second step. Its colours and title size come from the `auth` and
+`button` theme variables, see [Theming](#theming).
+
+```tsx
+const params = useSearchParams();
+
+<ResetPasswordFlow
+  requestReset={UserService.requestPasswordReset}
+  reset={UserService.resetPassword}
+  loginHref="/login"
+  initialEmail={params.get("email") ?? ""}
+  initialCode={params.get("code") ?? ""}
+  strings={{ title: "Tilbakestill passord", signInPrompt: null }}
+/>
+```
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `requestReset` | `(data: { email }) => Promise<unknown>` | Asks the API to email a code. |
+| `reset` | `(data: { email, code, newPassword }) => Promise<unknown>` | Sets the password. A `message` in its answer is shown when it succeeds. |
+| `loginHref` | `string` | Where the sign-in links go. |
+| `initialEmail`, `initialCode` | `string` | From the emailed link. A code opens the second step. |
+| `className` | `string` | Replaces the outer `max-w-md mx-auto px-4 py-16`, such as to sit in the app's own card. |
+| `strings` | `TextOverrides<ResetPasswordFlowStrings>` | The page's text. `signInPrompt`, `intro`, `codeSent` and `passwordHint` set to null are left out. `done` set to null shows the API's message, or only the sign-in link when it sends none. `passwordInvalid` set to null lists every broken rule. |
+| `passwordStrings` | `TextOverrides<PasswordStrings>` | The rule messages, in the app's language. |
+
+A failure shows the error's message, or `somethingWentWrong` when it has none.
+
 `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.
 
@@ -1014,7 +1051,22 @@ const result = passwordSchema({ uppercase: "Ta med en stor bokstav fra A til Z."
 const gargeRule = passwordSchema().max(128, "Be at most 128 characters long.");
 ```
 
-`PASSWORD_MIN_LENGTH` holds the minimum, for hint text.
+`PASSWORD_MIN_LENGTH` holds the minimum, for hint text. `passwordProblems(password, strings?)` gives the
+message of every rule a password breaks, in the same order, without zod.
+
+### `zodFieldErrors(error, options?)`
+
+From `@sjolystinnovation/app-kit/validation`. A failed parse's issues by the top-level field they
+belong to, for showing beside each input. Each field gets its first issue's message, or every message
+in order with `all: true`. `message` replaces zod's text, such as with the app's own translations.
+Issues that belong to no field are left out.
+
+```ts
+import { zodFieldErrors } from "@sjolystinnovation/app-kit/validation";
+
+const parsed = contactSchema.safeParse(form);
+if (!parsed.success) setErrors(zodFieldErrors(parsed.error, { message: (issue) => issueMessage(issue, dict) }));
+```
 
 ## Theming
 
@@ -1062,6 +1114,14 @@ selector such as `.dark` for a scoped theme:
 | `--color-toggle-on` | `var(--color-primary)`, the track of a `Toggle` that is on |
 | `--color-toggle-off` | gray 200, the track of a `Toggle` that is off |
 | `--color-toggle-thumb` | white |
+| `--text-auth-title`, `--text-auth-title--line-height` | `var(--text-2xl)` and its line height, the title of `ResetPasswordFlow` |
+| `--font-weight-auth-title` | black |
+| `--color-auth-heading` | gray 900 |
+| `--color-auth-text` | gray 600, the line under the title and the intro |
+| `--color-auth-note` | gray 600, the note that a code was sent |
+| `--color-auth-hint` | gray 500, the hint under the password |
+| `--color-auth-link`, `-hover` | gray 900, the sign-in links |
+| `--font-weight-auth-link` | semibold |
 | `--radius-button` | `var(--radius-lg)` |
 | `--color-button-primary-bg` | `var(--color-primary)` |
 | `--color-button-primary-text` | `var(--color-primary-foreground)` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjolystinnovation/app-kit",
-  "version": "0.17.0",
+  "version": "0.19.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/api/apiFieldErrors.ts

@@ -0,0 +1,23 @@
+import axios from "axios";
+
+/**
+ * The per-field messages of an ASP.NET validation problem, keyed by the field's name in camelCase so
+ * they match the form's own names: `{ errors: { OrgNumber: ["..."] } }` becomes
+ * `{ orgNumber: ["..."] }`. Takes the failed axios call or the response body. Answers null when there
+ * are no field errors, so the caller falls back to one message for the whole form.
+ */
+export function apiFieldErrors(error: unknown): Record<string, string[]> | null {
+  const data = axios.isAxiosError(error) ? error.response?.data : error;
+  const errors = data && typeof data === "object" ? (data as { errors?: unknown }).errors : undefined;
+  if (!errors || typeof errors !== "object" || Array.isArray(errors)) return null;
+
+  // A Map, so a field named like an Object property such as "constructor" is still just a field.
+  const fields = new Map<string, string[]>();
+  for (const [key, value] of Object.entries(errors as Record<string, unknown>)) {
+    const messages = (Array.isArray(value) ? value : [value]).filter((m): m is string => typeof m === "string" && m !== "");
+    if (messages.length === 0) continue;
+    const field = key.charAt(0).toLowerCase() + key.slice(1);
+    fields.set(field, [...(fields.get(field) ?? []), ...messages]);
+  }
+  return fields.size > 0 ? Object.fromEntries(fields) : null;
+}

package/src/api/index.ts

@@ -1,3 +1,4 @@
+export { apiFieldErrors } from "./apiFieldErrors";
 export { createApiClient } from "./createApiClient";
 export { request } from "./request";
 export { requestRevalidate } from "./requestRevalidate";

package/src/styles.css

@@ -71,6 +71,17 @@
   --color-payment-secondary-hover-bg: var(--color-gray-200);
   --color-payment-secondary-text: var(--color-gray-700);
 
+  --text-auth-title: var(--text-2xl);
+  --text-auth-title--line-height: var(--text-2xl--line-height);
+  --font-weight-auth-title: var(--font-weight-black);
+  --color-auth-heading: var(--color-gray-900);
+  --color-auth-text: var(--color-gray-600);
+  --color-auth-note: var(--color-gray-600);
+  --color-auth-hint: var(--color-gray-500);
+  --color-auth-link: var(--color-gray-900);
+  --color-auth-link-hover: var(--color-gray-900);
+  --font-weight-auth-link: var(--font-weight-semibold);
+
   --radius-button: var(--radius-lg);
   --color-button-primary-bg: var(--color-primary);
   --color-button-primary-text: var(--color-primary-foreground);

package/src/ui/ResetPasswordFlow.tsx

@@ -0,0 +1,130 @@
+"use client";
+
+import Link from "next/link";
+import { useState, type FormEvent } from "react";
+import { passwordProblems, type PasswordStrings } from "../validation/passwordRules";
+import { Alert } from "./Alert";
+import { PasswordInput } from "./PasswordInput";
+import { defaultResetPasswordFlowStrings, type ResetPasswordFlowStrings } from "./resetPasswordFlowStrings";
+import { TextInput } from "./TextInput";
+import { withDefaults, type TextOverrides } from "./withDefaults";
+
+export interface ResetPasswordFlowProps {
+  /** 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`. */
+  reset: (data: { email: string; code: string; newPassword: string }) => Promise<{ message?: string } | unknown>;
+  /** Where the sign-in links go. */
+  loginHref: string;
+  /** From the emailed link. A code opens the flow on its last step. */
+  initialEmail?: string | undefined;
+  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. */
+  className?: string | undefined;
+  /** The password rule messages, for the app's own language. */
+  passwordStrings?: TextOverrides<PasswordStrings> | undefined;
+}
+
+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";
+const link = "font-auth-link text-auth-link hover:text-auth-link-hover transition-colors";
+
+/**
+ * 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.
+ */
+export function ResetPasswordFlow({
+  requestReset,
+  reset,
+  loginHref,
+  initialEmail = "",
+  initialCode = "",
+  strings,
+  className = "max-w-md mx-auto px-4 py-16",
+  passwordStrings,
+}: ResetPasswordFlowProps) {
+  const text = withDefaults(defaultResetPasswordFlowStrings, strings);
+  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);
+  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);
+
+  const sendCode = async (event: FormEvent) => {
+    event.preventDefault();
+    setError(null);
+    setLoading(true);
+    try {
+      await requestReset({ email });
+      setStep(2);
+    } catch (err) {
+      setError(failure(err));
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  const setPassword = async (event: FormEvent) => {
+    event.preventDefault();
+    setError(null);
+    const problems = passwordProblems(newPassword, passwordStrings);
+    if (problems.length > 0) {
+      setError(text.passwordInvalid ?? problems.join(" "));
+      return;
+    }
+    setLoading(true);
+    try {
+      const result = await reset({ email, code, newPassword });
+      const message = (result as { message?: unknown } | null | undefined)?.message;
+      setDone(text.done ?? (typeof message === "string" ? message : ""));
+    } catch (err) {
+      setError(failure(err));
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  return (
+    <div className={className}>
+      <h1 className="text-auth-title font-auth-title text-auth-heading mb-1">{text.title}</h1>
+      <p className="text-sm text-auth-text mb-6">
+        {text.signInPrompt && <>{text.signInPrompt} </>}
+        <Link href={loginHref} className={link}>{text.signIn}</Link>
+      </p>
+
+      {done !== null ? (
+        <Alert variant="success">
+          {done}
+          <Link href={loginHref} className={`block mt-3 ${link}`}>{text.backToSignIn}</Link>
+        </Alert>
+      ) : step === 1 ? (
+        <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 />
+          <button type="submit" disabled={loading} className={button}>
+            {loading ? text.requestingCode : text.requestCode}
+          </button>
+        </form>
+      ) : (
+        <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 />
+          {text.passwordHint && <p className="text-xs text-auth-hint">{text.passwordHint}</p>}
+          <button type="submit" disabled={loading} className={button}>
+            {loading ? text.settingPassword : text.setPassword}
+          </button>
+        </form>
+      )}
+    </div>
+  );
+}

package/src/ui/index.ts

@@ -12,6 +12,10 @@ export { NotFoundState, defaultNotFoundStrings } from "./NotFoundState";
 export type { NotFoundStateProps, NotFoundStrings } from "./NotFoundState";
 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 { TextArea } from "./TextArea";
 export type { TextAreaProps } from "./TextArea";
 export { TextInput } from "./TextInput";

package/src/ui/resetPasswordFlowStrings.ts

@@ -0,0 +1,52 @@
+// Plain values, with no "use client", so a server component can import them.
+
+/**
+ * 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.
+ */
+export interface ResetPasswordFlowStrings {
+  title: string;
+  /** Shown before the sign-in link under the title, such as "Remembered it?". */
+  signInPrompt: string | null;
+  signIn: string;
+  /** The link back to sign-in once the password is set. */
+  backToSignIn: string;
+  /** Shown above the email field on the first step. */
+  intro: string | null;
+  /** Shown at the top of the second step, once a code is on its way. */
+  codeSent: string | null;
+  email: string;
+  code: string;
+  newPassword: string;
+  /** Shown under the new password field. */
+  passwordHint: string | null;
+  requestCode: string;
+  requestingCode: string;
+  setPassword: string;
+  settingPassword: string;
+  /** Shown when the password is set. Null shows the API's own message, or only the link when it sends none. */
+  done: string | null;
+  /** Shown for a password the rules refuse. Null lists each rule it breaks. */
+  passwordInvalid: string | null;
+  somethingWentWrong: string;
+}
+
+export const defaultResetPasswordFlowStrings: ResetPasswordFlowStrings = {
+  title: "Reset password",
+  signInPrompt: "Remembered it?",
+  signIn: "Sign in",
+  backToSignIn: "Back to sign in →",
+  intro: null,
+  codeSent: "Check your email for the reset code.",
+  email: "Email",
+  code: "Reset code",
+  newPassword: "New password",
+  passwordHint: null,
+  requestCode: "Send reset code",
+  requestingCode: "Sending…",
+  setPassword: "Reset password",
+  settingPassword: "Resetting…",
+  done: null,
+  passwordInvalid: null,
+  somethingWentWrong: "Something went wrong",
+};

package/src/validation/fieldErrors.ts

@@ -0,0 +1,34 @@
+import type { z } from "zod";
+
+/** Picks the text shown for an issue, such as a translated message by the issue's code. */
+export type IssueMessage = (issue: z.core.$ZodIssue) => string;
+
+/**
+ * A failed parse's issues by the top-level field they belong to, for showing beside each input. By
+ * default each field gets its first issue's message. With `all: true` it gets every message, in order.
+ * `message` replaces zod's text, such as with the app's own translations. Issues without a field,
+ * from a refinement of the whole object, are left out.
+ */
+export function zodFieldErrors<T>(
+  error: z.ZodError<T>,
+  options?: { all?: false; message?: IssueMessage },
+): Partial<Record<Extract<keyof T, string>, string>>;
+export function zodFieldErrors<T>(
+  error: z.ZodError<T>,
+  options: { all: true; message?: IssueMessage },
+): Partial<Record<Extract<keyof T, string>, string[]>>;
+export function zodFieldErrors<T>(
+  error: z.ZodError<T>,
+  options: { all?: boolean; message?: IssueMessage } = {},
+): object {
+  // A Map, so a field named like an Object property such as "constructor" is still just a field.
+  const errors = new Map<string, string[]>();
+  for (const issue of error.issues) {
+    const field = issue.path[0];
+    if (typeof field !== "string") continue;
+    const messages = errors.get(field) ?? [];
+    messages.push(options.message ? options.message(issue) : issue.message);
+    errors.set(field, messages);
+  }
+  return Object.fromEntries([...errors].map(([field, messages]) => [field, options.all ? messages : messages[0]]));
+}

package/src/validation/index.ts

@@ -1,2 +1,4 @@
-export { PASSWORD_MIN_LENGTH, defaultPasswordStrings, passwordSchema } from "./password";
+export { PASSWORD_MIN_LENGTH, defaultPasswordStrings, passwordProblems, passwordSchema } from "./password";
 export type { PasswordStrings } from "./password";
+export { zodFieldErrors } from "./fieldErrors";
+export type { IssueMessage } from "./fieldErrors";

package/src/validation/password.ts

@@ -1,23 +1,9 @@
 import { z } from "zod";
 import { withDefaults, type TextOverrides } from "../ui/withDefaults";
+import { PASSWORD_MIN_LENGTH, defaultPasswordStrings, type PasswordStrings } from "./passwordRules";
 
-/** The fewest characters a password may have. */
-export const PASSWORD_MIN_LENGTH = 8;
-
-/** The message for each password rule that fails. */
-export interface PasswordStrings {
-  tooShort: string;
-  lowercase: string;
-  uppercase: string;
-  digit: string;
-}
-
-export const defaultPasswordStrings: PasswordStrings = {
-  tooShort: `Use at least ${PASSWORD_MIN_LENGTH} characters.`,
-  lowercase: "Include a lowercase letter from a to z.",
-  uppercase: "Include an uppercase letter from A to Z.",
-  digit: "Include a digit from 0 to 9.",
-};
+export { PASSWORD_MIN_LENGTH, defaultPasswordStrings, passwordProblems } from "./passwordRules";
+export type { PasswordStrings } from "./passwordRules";
 
 /**
  * A zod schema for a new password, with the rules the APIs enforce through ASP.NET Identity. Identity

package/src/validation/passwordRules.ts

@@ -0,0 +1,35 @@
+import { withDefaults, type TextOverrides } from "../ui/withDefaults";
+
+// No zod here, so the reset form in /ui can check a password without the optional zod peer.
+
+/** The fewest characters a password may have. */
+export const PASSWORD_MIN_LENGTH = 8;
+
+/** The message for each password rule that fails. */
+export interface PasswordStrings {
+  tooShort: string;
+  lowercase: string;
+  uppercase: string;
+  digit: string;
+}
+
+export const defaultPasswordStrings: PasswordStrings = {
+  tooShort: `Use at least ${PASSWORD_MIN_LENGTH} characters.`,
+  lowercase: "Include a lowercase letter from a to z.",
+  uppercase: "Include an uppercase letter from A to Z.",
+  digit: "Include a digit from 0 to 9.",
+};
+
+/**
+ * The message of every password rule the password breaks, in the order `passwordSchema` checks them.
+ * An empty list means the APIs accept it.
+ */
+export function passwordProblems(password: string, strings?: TextOverrides<PasswordStrings>): string[] {
+  const text = withDefaults(defaultPasswordStrings, strings);
+  const problems: string[] = [];
+  if (password.length < PASSWORD_MIN_LENGTH) problems.push(text.tooShort);
+  if (!/[a-z]/.test(password)) problems.push(text.lowercase);
+  if (!/[A-Z]/.test(password)) problems.push(text.uppercase);
+  if (!/[0-9]/.test(password)) problems.push(text.digit);
+  return problems;
+}