@sjolystinnovation/app-kit 0.21.0 → 0.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjolystinnovation/app-kit",
-  "version": "0.21.0",
+  "version": "0.22.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/admin/AdminShell.tsx

@@ -13,6 +13,7 @@ export interface AdminTab {
 
 type GateProps = RoleGateProps extends infer P ? (P extends unknown ? Omit<P, "children"> : never) : never;
 
+/** Props for `AdminShell`. The gate props are `RoleGate`'s, without `children`. */
 export type AdminShellProps = GateProps & {
   title: ReactNode;
   tabs: readonly AdminTab[];
@@ -48,6 +49,6 @@ export function AdminShell({ title, tabs, children, ...gate }: AdminShellProps)
       {children}
     </div>
   );
-  // The gate props came in as one of RoleGate's two shapes, so they go back as that shape.
+  // The gate props arrive as one of RoleGate's two shapes, so they go back as that shape.
   return <RoleGate {...({ ...gate, children: page } as RoleGateProps)} />;
 }

package/src/admin/AdminUsersPanel.tsx

@@ -9,12 +9,13 @@ import { Toggle } from "../ui/Toggle";
 import { withDefaults, type TextOverrides } from "../ui/withDefaults";
 import { defaultAdminUsersPanelStrings, type AdminUsersPanelStrings } from "./adminUsersPanelStrings";
 
+/** Props for `AdminUsersPanel`. */
 export interface AdminUsersPanelProps {
   /** The user admin calls, such as `createAdminUsersService(api)`. */
   service: ReturnType<typeof createAdminUsersService>;
   /** The roles an admin may give, from the app's own endpoint. */
   getRoles: () => Promise<string[]>;
-  /** The role a new invite starts with. `Admin` by default. */
+  /** The role a new invite starts with. Defaults to `Admin`. */
   defaultInviteRole?: string | undefined;
   strings?: TextOverrides<AdminUsersPanelStrings> | undefined;
 }
@@ -39,7 +40,7 @@ export function AdminUsersPanel({ service, getRoles, defaultInviteRole = "Admin"
   const [roleLoading, setRoleLoading] = useState(false);
   const [invite, setInvite] = useState({ email: "", firstName: "", lastName: "", role: defaultInviteRole });
   const [inviting, setInviting] = useState(false);
-  // Bumped to fetch the list again after a change, through the same effect as every other load.
+  // Bumping it fetches the list again after a change, through the same effect as every other load.
   const [reloads, setReloads] = useState(0);
   // The latest service, so an inline one does not fetch the list again on every render. The roles
   // load once, so the first getRoles is enough.
@@ -134,7 +135,12 @@ export function AdminUsersPanel({ service, getRoles, defaultInviteRole = "Admin"
     }
     setInviting(true);
     try {
-      await serviceRef.current.invite(invite.email.trim(), invite.firstName.trim(), invite.lastName.trim(), invite.role);
+      await serviceRef.current.invite({
+        email: invite.email.trim(),
+        firstName: invite.firstName.trim(),
+        lastName: invite.lastName.trim(),
+        role: invite.role,
+      });
       toast.success(text.inviteSent);
       setInvite({ email: "", firstName: "", lastName: "", role: invite.role });
       reload();

package/src/admin/CompanySettingsForm.tsx

@@ -8,11 +8,12 @@ import { Toggle } from "../ui/Toggle";
 import { withDefaults, type TextOverrides } from "../ui/withDefaults";
 import { defaultCompanySettingsFormStrings, type CompanySettingsFormStrings } from "./companySettingsFormStrings";
 
+/** Props for `CompanySettingsForm`. */
 export interface CompanySettingsFormProps {
   /** The settings calls, such as `createSettingsService(api)`. */
   service: { get: () => Promise<SiteSettings>; update: (settings: SiteSettings) => Promise<SiteSettings> };
   strings?: TextOverrides<CompanySettingsFormStrings> | undefined;
-  /** Shown below the form once the settings have loaded, such as the `BrandingManager`. */
+  /** The content shown below the form once the settings have loaded, such as the `BrandingManager`. */
   children?: ReactNode;
 }
 

package/src/admin/LegalPagesEditor.tsx

@@ -8,17 +8,18 @@ import { withDefaults, type TextOverrides } from "../ui/withDefaults";
 import { defaultLegalPagesEditorStrings, type LegalPagesEditorStrings } from "./legalPagesEditorStrings";
 import { LocaleTabs } from "./LocaleTabs";
 
+/** Props for `LegalPagesEditor`. */
 export interface LegalPagesEditorProps<K extends string, L extends string> {
   /** The legal page calls, such as `createLegalService(api, publicApi)`. */
   service: {
     listAll: () => Promise<LegalPage<K>[]>;
-    save: (key: K, locale: L, title: string, bodyMarkdown: string) => Promise<unknown>;
+    save: (page: { key: K; locale: L; title: string; bodyMarkdown: string }) => Promise<unknown>;
   };
-  /** The pages, in tab order. The first opens. */
+  /** The pages, in tab order. The editor opens on the first. */
   keys: readonly K[];
   /** Each page's tab label, such as `Terms`. */
   keyLabels: Record<K, string>;
-  /** The locales each page is written in. The first opens. */
+  /** The locales each page is written in. The editor opens on the first. */
   locales: readonly L[];
   /** Each locale's tab label, such as `Norsk`. */
   localeLabels: Record<L, string>;
@@ -70,7 +71,7 @@ export function LegalPagesEditor<K extends string, L extends string>({ service,
     }
     setSaving(true);
     try {
-      await serviceRef.current.save(activeKey, activeLocale, draft.title.trim(), draft.bodyMarkdown);
+      await serviceRef.current.save({ key: activeKey, locale: activeLocale, title: draft.title.trim(), bodyMarkdown: draft.bodyMarkdown });
       toast.success(text.saved);
     } catch (err) {
       toast.error(err instanceof Error && err.message ? err.message : text.saveFailed);

package/src/admin/LocaleTabs.tsx

@@ -1,18 +1,19 @@
 "use client";
 
+/** Props for `LocaleTabs`. */
 export interface LocaleTabsProps<L extends string> {
   locales: readonly L[];
   /** Each locale's tab label, such as `Norsk`. */
   labels: Record<L, string>;
   active: L;
   onChange: (locale: L) => void;
-  /** Which locales have content. A locale marked false gets a dot titled `notFilled`. */
+  /** The locales that have content. A locale set to `false` gets a dot titled `notFilled`. */
   filled?: Partial<Record<L, boolean>> | undefined;
-  /** The dot's title, such as "Not filled in". */
+  /** The dot's title. Defaults to "Not filled in". */
   notFilled?: string | undefined;
 }
 
-/** Tabs for editing one translation at a time. */
+/** Renders tabs for editing one translation at a time. */
 export function LocaleTabs<L extends string>({ locales, labels, active, onChange, filled, notFilled = "Not filled in" }: LocaleTabsProps<L>) {
   return (
     <div className="flex items-center gap-1 border-b border-gray-200">

package/src/admin/StatHistoryChart.tsx

@@ -9,10 +9,11 @@ export interface StatSeries<T> {
   /** The field of each day's row the line plots. A missing or non-numeric value counts as zero. */
   key: keyof T & string;
   label: string;
-  /** The line's colour. Defaults to the next colour in `STAT_SERIES_COLORS`. */
+  /** The line's color. Defaults to the next color in `STAT_SERIES_COLORS`. */
   color?: string | undefined;
 }
 
+/** Props for `StatHistoryChart`. */
 export interface StatHistoryChartProps<T extends { date: string }> {
   /** One row per day, oldest first, with `date` as `YYYY-MM-DD`. */
   data: readonly T[];
@@ -25,8 +26,8 @@ const H = 240;
 const PAD = { top: 16, right: 16, bottom: 28, left: 32 };
 
 /**
- * A line per series over the days, with the scale from zero to the highest shown value. The legend
- * buttons hide and show a line, and the scale follows the lines that are shown.
+ * Renders a line per series over the days, with the scale from zero to the highest shown value. The
+ * legend buttons hide and show a line, and the scale follows the lines that are shown.
  */
 export function StatHistoryChart<T extends { date: string }>({ data, series, strings }: StatHistoryChartProps<T>) {
   const text = withDefaults(defaultStatHistoryChartStrings, strings);

package/src/admin/adminUsersPanelStrings.ts

@@ -1,8 +1,8 @@
 // Plain values, with no "use client", so a server component can import them.
 
 /**
- * The users panel's text. Pass the app's own language. The defaults are English. `{name}` and `{role}`
- * are filled in where a text names them.
+ * The users panel's text. Pass the app's own language. The defaults are English. The panel fills in
+ * `{name}` and `{role}` where a text names them.
  */
 export interface AdminUsersPanelStrings {
   users: string;
@@ -19,7 +19,7 @@ export interface AdminUsersPanelStrings {
   /** The tag after a deleted user's name. */
   deleted: string;
   delete: string;
-  /** Before the role name on the button that takes a role away. */
+  /** The text before the role name on the button that takes a role away. */
   remove: string;
   noRoles: string;
   addRole: string;

package/src/admin/legalPagesEditorStrings.ts

@@ -11,7 +11,7 @@ export interface LegalPagesEditorStrings {
   save: string;
   saving: string;
   loadFailed: string;
-  /** When the title or the content is blank. */
+  /** The message shown when the title or the content is blank. */
   required: string;
   saved: string;
   saveFailed: string;

package/src/admin/statHistoryChartStrings.ts

@@ -1,7 +1,8 @@
 // Plain values, with no "use client", so a server component can import them.
 
+/** The chart's text. Pass the app's own language. The defaults are English. */
 export interface StatHistoryChartStrings {
-  /** Shown instead of the chart when there are no days yet. */
+  /** The text shown instead of the chart when there are no days yet. */
   empty: string;
   /** The chart's accessible name. */
   chart: string;
@@ -12,5 +13,5 @@ export const defaultStatHistoryChartStrings: StatHistoryChartStrings = {
   chart: "Stats over time",
 };
 
-/** The default line colours, in order: blue, green, amber, teal and purple. */
+/** The default line colors, in order: blue, green, amber, teal, and purple. */
 export const STAT_SERIES_COLORS = ["#2563eb", "#16a34a", "#d97706", "#0d9488", "#9333ea"] as const;

package/src/api/apiFieldErrors.ts

@@ -1,10 +1,10 @@
 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.
+ * Gets 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. Returns 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;

package/src/api/company.ts

@@ -18,8 +18,9 @@ export interface CompanyInfo {
 export type CompanyFallback = Partial<CompanyInfo> & { name: string };
 
 /**
- * The company details for public pages: the API's answer, with the app's own values for any field
- * it left blank or could not give. The legal name falls back to the name, and VAT to not registered.
+ * Builds the company details for public pages from the API's answer, with the app's own values for
+ * any field it left blank or could not give. The legal name falls back to the name, and VAT to not
+ * registered.
  */
 export function mergeCompanyInfo(data: Partial<CompanyInfo> | null | undefined, fallback: CompanyFallback): CompanyInfo {
   const name = data?.name || fallback.name;
@@ -39,7 +40,7 @@ export function mergeCompanyInfo(data: Partial<CompanyInfo> | null | undefined,
   };
 }
 
-/** The org number with the Norwegian ` MVA` suffix once the business is VAT registered. Empty without a number. */
+/** Formats the org number with the Norwegian ` MVA` suffix once the business is VAT registered. Returns `""` without a number. */
 export function formatOrgNumber({ orgNumber, vatRegistered }: { orgNumber?: string | null | undefined; vatRegistered?: boolean | null | undefined }): string {
   if (!orgNumber) return "";
   return vatRegistered ? `${orgNumber} MVA` : orgNumber;

package/src/api/createApiClient.ts

@@ -3,8 +3,9 @@ import { getSession } from "next-auth/react";
 import { isTerminalSessionError, openSessionPrompt } from "../session/expiry";
 
 /**
- * An axios instance for the signed-in API, for browser code. Each request carries the session's
- * access token. A 401 on a dead session opens the re-sign-in prompt, so the page keeps its state.
+ * Creates an axios instance for the signed-in API, for browser code. Each request carries the
+ * session's access token. A 401 on a dead session opens the re-sign-in prompt, so the page keeps
+ * its state.
  */
 export function createApiClient(baseURL: string): AxiosInstance {
   if (!baseURL) {

package/src/{errors.ts → api/formatApiError.ts}

@@ -1,14 +1,14 @@
 import axios, { type AxiosResponse } from "axios";
 
 /**
- * Messages to show for a status code. On a 4xx they are used when the response carries no specific
- * message of its own. On a 5xx they win over the body. Key 0 covers a request that got no response,
- * because of a dropped connection or a timeout.
+ * The messages to show for a status code. On a 4xx, `formatApiError` uses them when the response
+ * carries no specific message of its own. On a 5xx, they win over the body. Key 0 covers a request
+ * that got no response, because of a dropped connection or a timeout.
  */
 export type StatusMessages = Partial<Record<number, string>>;
 
 /**
- * Axios codes for a request that never got a response from the network. A browser reports every
+ * The axios codes for a request that never got a response from the network. A browser reports every
  * network failure as ERR_NETWORK. On the server, Node reports the specific cause.
  */
 const NO_RESPONSE_CODES = new Set([
@@ -36,8 +36,8 @@ const NO_RESPONSE_CODES = new Set([
  * as "Bad Gateway". A problem details `title` is never used. ASP.NET Core fills it with generic text
  * such as "Bad Request", which says less than `fallback`.
  *
- * Only single line text counts as a message. Axios's own message, such as "Request failed with
- * status code 500", is never shown. A cancelled request gives `fallback`. Any other `Error` gives
+ * Only single-line text counts as a message. Axios's own message, such as "Request failed with
+ * status code 500", is never shown. A canceled request gives `fallback`. Any other `Error` gives
  * its message.
  */
 export function formatApiError(
@@ -60,18 +60,18 @@ export function formatApiError(
   return fallback;
 }
 
-/** The message the body carries for this failure, if it carries one. */
+/** Gets the message the body carries for this failure, if it carries one. */
 function readBody(response: AxiosResponse): string | undefined {
   const data = parseIfJson(response.data);
   if (typeof data === "string") return singleLine(data);
-  // Only a parsed JSON object has fields to read. A Document, Blob or ArrayBuffer does not.
+  // Only a parsed JSON object has fields to read. A Document, Blob, or ArrayBuffer does not.
   if (!isPlainObject(data)) return undefined;
   return firstText(data.message) ?? firstValidationError(data.errors) ?? singleLine(data.detail);
 }
 
 /**
- * Axios leaves a JSON body as a string when the request asked for text, so parse it here. Plain text
- * such as "Invalid email or password." is not valid JSON and stays as it is.
+ * Parses a JSON body that axios left as a string because the request asked for text. Plain text such
+ * as "Invalid email or password." is not valid JSON and stays as it is.
  */
 function parseIfJson(data: unknown): unknown {
   if (typeof data !== "string") return data;
@@ -98,12 +98,12 @@ function firstValidationError(errors: unknown): string | undefined {
   return undefined;
 }
 
-/** A single line of text, or the first entry when the value is a list of them. */
+/** Gets a single line of text, or the first entry when the value is a list of them. */
 function firstText(value: unknown): string | undefined {
   return singleLine(Array.isArray(value) ? value[0] : value);
 }
 
-/** The trimmed text, when it is one line of text and not HTML. */
+/** Gets the trimmed text, when it is one line of text and not HTML. */
 function singleLine(value: unknown): string | undefined {
   if (typeof value !== "string") return undefined;
   const text = value.trim();

package/src/api/index.ts

@@ -2,8 +2,9 @@ export { apiFieldErrors } from "./apiFieldErrors";
 export { formatOrgNumber, mergeCompanyInfo } from "./company";
 export type { CompanyFallback, CompanyInfo } from "./company";
 export { createApiClient } from "./createApiClient";
+export { formatApiError } from "./formatApiError";
+export type { StatusMessages } from "./formatApiError";
 export { request } from "./request";
-export { requestRevalidate } from "./requestRevalidate";
 export { defineRevalidateTargets } from "./revalidateTargets";
 export type { RevalidateTargetPaths, RevalidateTargetsConfig } from "./revalidateTargets";
 export {

package/src/api/request.ts

@@ -1,9 +1,9 @@
 import axios from "axios";
-import { formatApiError, type StatusMessages } from "../errors";
+import { formatApiError, type StatusMessages } from "./formatApiError";
 
 /**
  * Runs an API call and returns its data. A failure throws an `Error` with a message for the user,
- * from `formatApiError`. A cancelled call rethrows the cancel as it is, so the caller can ignore it.
+ * from `formatApiError`. A canceled call rethrows the cancel as it is, so the caller can ignore it.
  */
 export async function request<T>(
   call: () => Promise<{ data: T }>,

package/src/api/revalidateTargets.ts

@@ -3,12 +3,13 @@ import { requestRevalidate } from "./requestRevalidate";
 
 /** The pages one admin edit changes. */
 export interface RevalidateTargetPaths {
-  /** Paths below each locale segment, such as `/builds/[slug]`. `""` is the locale's front page. */
+  /** The paths below each locale segment, such as `/builds/[slug]`. `""` is the locale's front page. */
   pages?: readonly string[] | undefined;
-  /** Paths outside the locale segments, such as `/sitemap.xml`. */
+  /** The paths outside the locale segments, such as `/sitemap.xml`. */
   root?: readonly string[] | undefined;
 }
 
+/** Options for `defineRevalidateTargets`. */
 export interface RevalidateTargetsConfig<T extends string> {
   /** The locale segments every page is under. A site without them omits this. */
   locales?: readonly string[] | undefined;
@@ -16,9 +17,10 @@ export interface RevalidateTargetsConfig<T extends string> {
 }
 
 /**
- * The cache targets an app's admin edits purge, in one place for both sides: `targets` names them
- * for fetch tags, `paths` is what `createRevalidateRoute` purges for each, and `revalidate` asks the
- * route to purge one after an edit. A target with no paths is purged by its tag alone.
+ * Defines the cache targets an app's admin edits purge, in one place for the client and the server.
+ * `targets` names them for fetch tags, `paths` lists what `createRevalidateRoute` purges for each,
+ * and `revalidate` asks the route to purge one after an edit. A target with no paths is purged by
+ * its tag alone.
  */
 export function defineRevalidateTargets<T extends string>({ locales = [], targets }: RevalidateTargetsConfig<T>) {
   const names = Object.keys(targets) as T[];

package/src/api/services.ts

@@ -4,7 +4,7 @@ import type { Branding } from "../branding/types";
 import { request } from "./request";
 
 /**
- * An axios instance for the API's anonymous endpoints, without the session's token. Like
+ * Creates an axios instance for the API's anonymous endpoints, without the session's token. Like
  * `createApiClient`, it only sends requests to `baseURL`.
  */
 export function createPublicClient(baseURL: string): AxiosInstance {
@@ -14,7 +14,7 @@ export function createPublicClient(baseURL: string): AxiosInstance {
   return axios.create({ baseURL, allowAbsoluteUrls: false });
 }
 
-/** Runs after an admin change saves, such as to purge the pages that show it. */
+/** A callback that runs after an admin change saves, such as to purge the pages that show it. */
 export type OnSaved = () => Promise<void> | void;
 
 async function currentUserId(): Promise<string> {
@@ -35,8 +35,8 @@ export interface UserProfile {
 }
 
 /**
- * Password reset and the signed-in user's account, on the auth and account endpoints of
- * SjolystInnovation.AppKit.Auth. `api` carries the session, `publicApi` does not.
+ * Creates the calls for password reset and the signed-in user's account, on the auth and account
+ * endpoints of SjolystInnovation.AppKit.Auth. `api` carries the session, and `publicApi` does not.
  */
 export function createUserService(api: AxiosInstance, publicApi: AxiosInstance) {
   return {
@@ -88,7 +88,7 @@ export interface SiteSettings {
   publicPhone: string;
 }
 
-/** The admin's company settings on SjolystInnovation.AppKit.SiteSettings. */
+/** Creates the admin calls for the company settings on SjolystInnovation.AppKit.SiteSettings. */
 export function createSettingsService(api: AxiosInstance, options: { onSaved?: OnSaved } = {}) {
   return {
     get: () => request(() => api.get<SiteSettings>("/settings"), "Failed to load settings"),
@@ -102,8 +102,8 @@ export function createSettingsService(api: AxiosInstance, options: { onSaved?: O
 }
 
 /**
- * The logo and favicon on SjolystInnovation.AppKit.SiteSettings. Reading is anonymous and answers
- * no branding when the API cannot be reached, so a page still renders.
+ * Creates the calls for the logo and favicon on SjolystInnovation.AppKit.SiteSettings. Reading is
+ * anonymous and returns no branding when the API cannot be reached, so a page still renders.
  */
 export function createBrandingService(api: AxiosInstance, publicApi: AxiosInstance, options: { onSaved?: OnSaved } = {}) {
   return {
@@ -115,7 +115,7 @@ export function createBrandingService(api: AxiosInstance, publicApi: AxiosInstan
       }
     },
 
-    /** Sends the form `BrandingManager` builds: `logo`, `icon`, `removeLogo` and `removeIcon`. */
+    /** Sends the form `BrandingManager` builds: `logo`, `icon`, `removeLogo`, and `removeIcon`. */
     async update(form: FormData): Promise<Branding> {
       const saved = await request(() => api.put<Branding>("/branding", form), "Failed to save branding");
       await options.onSaved?.();
@@ -134,8 +134,9 @@ export interface LegalPage<Key extends string = string> {
 }
 
 /**
- * The terms, privacy and cookie pages on SjolystInnovation.AppKit.SiteSettings. Reading is anonymous
- * and answers null for a page that is missing or cannot be read, so a page shows its fallback.
+ * Creates the calls for the terms, privacy, and cookie pages on
+ * SjolystInnovation.AppKit.SiteSettings. Reading is anonymous and returns null for a page that is
+ * missing or cannot be read, so a page shows its fallback.
  */
 export function createLegalService<Key extends string = "terms" | "privacy" | "cookies">(
   api: AxiosInstance,
@@ -153,7 +154,7 @@ export function createLegalService<Key extends string = "terms" | "privacy" | "c
 
     listAll: () => request(() => api.get<LegalPage<Key>[]>("/content/legal"), "Failed to load legal pages"),
 
-    async save(key: Key, locale: string, title: string, bodyMarkdown: string) {
+    async save({ key, locale, title, bodyMarkdown }: { key: Key; locale: string; title: string; bodyMarkdown: string }) {
       const page = await request(
         () => api.put<LegalPage<Key>>(`/content/legal/${encodeURIComponent(key)}/${encodeURIComponent(locale)}`, { title, bodyMarkdown }),
         "Failed to save legal page",
@@ -176,7 +177,7 @@ export interface AdminUser {
   roles: string[];
 }
 
-/** User administration on SjolystInnovation.AppKit.Auth: the list, roles, invites and deletion. */
+/** Creates the user administration calls on SjolystInnovation.AppKit.Auth: the list, roles, invites, and deletion. */
 export function createAdminUsersService(api: AxiosInstance) {
   return {
     getUsers: (includeDeleted = false) =>
@@ -191,7 +192,7 @@ export function createAdminUsersService(api: AxiosInstance) {
     deleteUser: (userId: string) =>
       request(() => api.delete(`/users/${encodeURIComponent(userId)}/account`), "Failed to delete user"),
 
-    invite: (email: string, firstName: string, lastName: string, role: string) =>
+    invite: ({ email, firstName, lastName, role }: { email: string; firstName: string; lastName: string; role: string }) =>
       request(() => api.post("/users/invite", { email, firstName, lastName, role }), "Failed to send invitation"),
   };
 }

package/src/auth/createAuthOptions.ts

@@ -44,12 +44,13 @@ interface AuthorizedUser extends User {
   refreshToken: string;
 }
 
+/** Settings for `createAuthOptions`. Pass either `apiUrl` or `http`. */
 export type AuthOptionsSettings = {
   /** The server environment, usually `process.env`. It holds the API JWT secret. */
   env: Record<string, string | undefined>;
 } & (
   | {
-      /** Base URL of the API, such as `https://api.example.com/api`. */
+      /** The base URL of the API, such as `https://api.example.com/api`. */
       apiUrl: string;
       http?: never;
     }
@@ -60,7 +61,8 @@ export type AuthOptionsSettings = {
     }
 );
 
-// Refresh ahead of expiry, so the token is still fresh when the user saves.
+// How far ahead of expiry a refresh falls due, at most, so the token is still fresh when the user
+// saves.
 const MAX_REFRESH_SKEW_MS = 5 * 60 * 1000;
 
 // The soonest a refresh can be due. The floor stops a short-lived token from refreshing on every
@@ -111,9 +113,9 @@ function failureShape(error: unknown) {
 }
 
 /**
- * next-auth options for email and password sign-in against the API. The API issues a short-lived
- * access token and a refresh token that changes on every refresh. The session refreshes ahead of
- * expiry, rides out temporary API failures, and ends seven days after sign-in.
+ * Creates the next-auth options for email and password sign-in against the API. The API issues a
+ * short-lived access token and a refresh token that changes on every refresh. The session refreshes
+ * ahead of expiry, rides out temporary API failures, and ends seven days after sign-in.
  */
 export function createAuthOptions(config: SessionConfig, settings: AuthOptionsSettings): NextAuthOptions {
   const { env } = settings;

package/src/branding/BrandingManager.tsx

@@ -7,6 +7,7 @@ import { withDefaults, type TextOverrides } from "../ui/withDefaults";
 import { useBranding } from "./BrandingProvider";
 import { toDataUrl } from "./types";
 
+/** The branding form's text. Pass the app's own language. The defaults are English. */
 export interface BrandingManagerStrings {
   title: string;
   logo: string;
@@ -22,12 +23,14 @@ export interface BrandingManagerStrings {
   saveFailed: string;
 }
 
+const IMAGE_TYPES = "image/png,image/jpeg,image/webp,image/gif,image/x-icon,.ico";
+
 export const defaultBrandingManagerStrings: BrandingManagerStrings = {
   title: "Branding",
   logo: "Logo",
-  logoHint: "Shown in the navbar and footer. PNG/SVG, max 2 MB.",
+  logoHint: "Shown in the navbar and footer. PNG, JPEG, WebP, or GIF, max 2 MB.",
   icon: "Icon (favicon)",
-  iconHint: "Browser tab icon. Square PNG/ICO, max 2 MB.",
+  iconHint: "Browser tab icon. Square PNG or ICO, max 2 MB.",
   none: "none",
   choose: "Choose",
   remove: "Remove",
@@ -37,10 +40,11 @@ export const defaultBrandingManagerStrings: BrandingManagerStrings = {
   saveFailed: "Failed to save branding",
 };
 
+/** Props for `BrandingManager`. */
 export interface BrandingManagerProps {
   /**
-   * Sends the form: `logo` and `icon` files, and `removeLogo` and `removeIcon` set to `true`. Throw
-   * to show the error's message, such as one from `formatApiError`.
+   * A function that sends the form: `logo` and `icon` files, and `removeLogo` and `removeIcon` set
+   * to `true`. Throw from it to show the error's message, such as one from `formatApiError`.
    */
   save: (form: FormData) => Promise<unknown>;
   strings?: TextOverrides<BrandingManagerStrings> | undefined;
@@ -93,7 +97,8 @@ function Slot({ label, hint, currentUrl, file, onPick, onClear, text }: SlotProp
         <input
           ref={inputRef}
           type="file"
-          accept="image/*"
+          // The types the API accepts, so the picker does not offer an SVG it would refuse.
+          accept={IMAGE_TYPES}
           aria-label={label}
           className="hidden"
           onChange={e => onPick(e.target.files?.[0] ?? null)}

package/src/branding/BrandingProvider.tsx

@@ -3,6 +3,7 @@
 import { createContext, useCallback, useContext, useEffect, useRef, useState, type ReactNode } from "react";
 import { toDataUrl, type Branding } from "./types";
 
+/** What `useBranding` returns. */
 export interface BrandingContextValue {
   branding: Branding;
   /** The logo as a `data:` URL, or null when none is set. */
@@ -13,21 +14,22 @@ export interface BrandingContextValue {
 
 const BrandingContext = createContext<BrandingContextValue>({ branding: {}, logoUrl: null, refresh: () => {} });
 
-/** The branding from the nearest `BrandingProvider`. Empty outside one. */
+/** Gets the branding from the nearest `BrandingProvider`. Returns empty branding outside one. */
 export const useBranding = () => useContext(BrandingContext);
 
 /** How often the provider loads the branding again, so an open tab picks up a change. */
 export const BRANDING_REFRESH_MS = 5 * 60 * 1000;
 
+/** Props for `BrandingProvider`. */
 export interface BrandingProviderProps {
   children: ReactNode;
-  /** Loads the branding, such as a GET of `/branding`. A failure keeps the branding it has. */
+  /** A function that loads the branding, such as a GET of `/branding`. On a failure the provider keeps the branding it has. */
   load: () => Promise<Branding>;
   /** The branding the server rendered with. Without it, the provider loads it on mount. */
   initial?: Branding | undefined;
 }
 
-/** Holds the logo and favicon for the components below it, and loads them again every five minutes. */
+/** Provides the logo and favicon to the components below it, and loads them again every five minutes. */
 export function BrandingProvider({ children, load, initial }: BrandingProviderProps) {
   const [branding, setBranding] = useState<Branding>(initial ?? {});
   // The latest load, so an inline function does not restart the refresh timer on every render.

package/src/branding/index.ts

@@ -5,10 +5,9 @@ export {
   type BrandingManagerStrings,
 } from "./BrandingManager";
 export {
-  BRANDING_REFRESH_MS,
   BrandingProvider,
   useBranding,
   type BrandingContextValue,
   type BrandingProviderProps,
 } from "./BrandingProvider";
-export { toDataUrl, type Branding } from "./types";
+export type { Branding } from "./types";