@sjolystinnovation/app-kit 0.21.0 → 0.22.0

package/src/branding/server.ts

@@ -2,22 +2,23 @@ import { createHash } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import type { Branding } from "./types";
 
+/** Options for `brandingIcon`. */
 export interface BrandingIconOptions {
-  /** Loads the branding, such as a cached GET of `/branding`. Throws when the API cannot be reached. */
+  /** A function that loads the branding, such as a cached GET of `/branding`. It throws when the API cannot be reached. */
   load: () => Promise<Branding | null | undefined>;
   /** The bundled icon for when none is set, such as `public/icon.png`. */
   fallbackPath: string;
-  /** Its content type, such as `image/png` or `image/svg+xml`. */
+  /** The bundled icon's content type, such as `image/png` or `image/svg+xml`. */
   fallbackType: string;
 }
 
 /**
- * The response for an `app/icon.ts` route: the favicon set in admin settings when it is a PNG,
- * JPEG, WebP, GIF or ICO, or the bundled one otherwise. Both carry `nosniff`, and a sandbox CSP
- * that a CSP header from the app's `next.config` replaces.
- * When the branding cannot be loaded it answers 503 with `no-store`, not the
- * bundled icon, since a browser would cache that in place of the one set in settings. The route
- * needs `dynamic = "force-dynamic"`, or the build bakes in the icon of the moment.
+ * Builds the response for an `app/icon.ts` route: the favicon set in admin settings when it is a
+ * PNG, JPEG, WebP, GIF, or ICO, or the bundled one otherwise. Both carry `nosniff`, and a sandbox
+ * CSP that a CSP header from the app's `next.config` replaces. When the branding cannot be loaded,
+ * it answers 503 with `no-store` instead of the bundled icon, since a browser would cache that in
+ * place of the one set in settings. The route needs `dynamic = "force-dynamic"`, or the build bakes
+ * in the icon of the moment.
  */
 export async function brandingIcon({ load, fallbackPath, fallbackType }: BrandingIconOptions): Promise<Response> {
   let branding: Branding | null | undefined;
@@ -47,7 +48,7 @@ const RASTER_TYPES = new Set(["image/png", "image/jpeg", "image/webp", "image/gi
 const HARDENING = { "X-Content-Type-Options": "nosniff", "Content-Security-Policy": "default-src 'none'; sandbox" };
 
 /**
- * A short digest of icon bytes, for a URL that changes when the icon does, such as
+ * Computes a short digest of icon bytes, for a URL that changes when the icon does, such as
  * `/icon?v=<digest>` in the web app manifest. Android refreshes a home screen icon only when the
  * manifest changes.
  */

package/src/branding/types.ts

@@ -1,13 +1,13 @@
 /** The logo and favicon set in admin settings, as the API's `/branding` endpoint returns them. */
 export interface Branding {
-  /** Base64 image bytes. */
+  /** The logo's image bytes, in base64. */
   logoData?: string | null | undefined;
   logoContentType?: string | null | undefined;
-  /** Base64 image bytes. */
+  /** The favicon's image bytes, in base64. */
   iconData?: string | null | undefined;
   iconContentType?: string | null | undefined;
 }
 
-/** A `data:` URL for base64 image bytes, or null when either part is missing. */
+/** Builds a `data:` URL for base64 image bytes. Returns null when either part is missing. */
 export const toDataUrl = (data?: string | null, contentType?: string | null): string | null =>
   data && contentType ? `data:${contentType};base64,${data}` : null;

package/src/config.ts

@@ -4,18 +4,18 @@
  */
 export interface SessionConfig {
   /**
-   * Name of the environment variable holding the API JWT secret, such as API_JWT_SECRET. Apps that
-   * talk to more than one API, or that deploy several apps side by side, need distinct names.
+   * The name of the environment variable holding the API JWT secret, such as `API_JWT_SECRET`. Apps
+   * that talk to more than one API, or that deploy several apps side by side, need distinct names.
    */
   jwtSecretEnvVar: string;
   /**
-   * Where an expired or rejected session sends the browser. An app with a locale prefix uses
-   * something like "/en/login". An app without one uses "/login".
+   * The path an expired or rejected session sends the browser to. An app with a locale prefix uses
+   * something like `"/en/login"`. An app without one uses `"/login"`.
    */
   loginRoute: string;
   /**
-   * Prefix for the localStorage keys holding form drafts, usually the app's name, such as
-   * "example". Drafts are stored under `<prefix>:draft:<owner>:<scope>`, so the prefix itself
+   * The prefix for the localStorage keys holding form drafts, usually the app's name, such as
+   * `"example"`. Drafts are stored under `<prefix>:draft:<owner>:<scope>`, so the prefix itself
    * has no trailing colon.
    */
   draftStoragePrefix: string;
@@ -31,8 +31,8 @@ export function defineSessionConfig(config: SessionConfig): SessionConfig {
 }
 
 /**
- * The key prefix for form drafts. Throws on a colon or an empty name. Those build keys such as
- * "app:draft::draft:", which match no draft saved under "app:draft:".
+ * Gets the key prefix for form drafts. Throws on a colon or an empty name. Those build keys such as
+ * `"app:draft::draft:"`, which match no draft saved under `"app:draft:"`.
  */
 export function draftPrefix(config: Pick<SessionConfig, "draftStoragePrefix">): string {
   const name = config.draftStoragePrefix;
@@ -57,8 +57,8 @@ export function requireEnv(name: string, value: string | undefined): string {
  * Reads the API JWT secret named by the config. Throws when it is missing, with a message that names
  * the variable.
  *
- * The caller passes the environment, usually `process.env`, so this entry point needs no Node
- * types and stays safe to import in browser code.
+ * The caller passes the environment, usually `process.env`, so this module needs no Node types and
+ * stays safe to import in browser code. `createAuthOptions` uses it. It is not part of the public API.
  */
 export function resolveJwtSecret(
   config: SessionConfig,

package/src/forms/useFormDraft.ts

@@ -32,6 +32,7 @@ function read<T>(storageKey: string): T | null {
   }
 }
 
+/** Options for `useFormDraft`. */
 export interface FormDraftOptions<T> {
   /**
    * The signed-in user's id. A browser profile can be shared, so drafts are stored per user. That
@@ -40,27 +41,28 @@ export interface FormDraftOptions<T> {
    * known.
    */
   owner: string | undefined;
-  /** Identifies the form and the entity it edits, for example `recipe:new` or `recipe:42`. */
+  /** The key for the form and the entity it edits, for example `recipe:new` or `recipe:42`. */
   scope: string;
   /** The form's current values. They must survive `JSON.stringify`. */
   value: T;
 }
 
+/** What `useFormDraft` returns. */
 export interface FormDraft<T> {
   /**
-   * The stored draft, while it is still waiting to be restored or dismissed. Read once the owner is
-   * known and again whenever the owner or scope changes, so it can appear after mount.
+   * The stored draft, while it is still waiting to be restored or dismissed. The hook reads it once
+   * the owner is known and again whenever the owner or scope changes, so it can appear after mount.
    */
   pending: T | null;
-  /** Stop offering the draft. The caller applies the values it wants. */
+  /** Stops offering the draft. The caller applies the values it wants. */
   dismiss: () => void;
-  /** Drop the stored draft after a successful save. */
+  /** Drops the stored draft. Call it after a successful save. */
   clear: () => void;
 }
 
 /**
- * Keeps a form's values in localStorage so a sign-out, reload or closed tab does not lose them.
- * Values are written half a second after the last change, so only that last half second is at risk.
+ * Keeps a form's values in localStorage so a sign-out, reload, or closed tab does not lose them. The
+ * hook writes them half a second after the last change, so only that last half second is at risk.
  *
  * A draft found at mount is offered for restore, not applied. So an edit form never silently
  * overwrites what the API returned. Saving starts at once, whether or not the offer is answered.

package/src/index.ts

@@ -1,4 +1,2 @@
-export { defineSessionConfig, requireEnv, resolveJwtSecret } from "./config";
+export { defineSessionConfig, requireEnv } from "./config";
 export type { SessionConfig } from "./config";
-export { formatApiError } from "./errors";
-export type { StatusMessages } from "./errors";

package/src/legal/LegalPageView.tsx

@@ -6,11 +6,11 @@ import { withDefaults, type TextOverrides } from "../ui/withDefaults";
 
 /** The legal page's text around the content. Pass the app's own language. The defaults are English. */
 export interface LegalPageViewStrings {
-  /** Before the date the page last changed. */
+  /** The text before the date the page last changed. */
   updated: string;
-  /** Shown in place of the content when nobody has written the page yet. */
+  /** The text shown in place of the content when nobody has written the page yet. */
   missing: string;
-  /** The link back to the front page. */
+  /** The text of the link back to the front page. */
   toFrontPage: string;
 }
 
@@ -20,19 +20,20 @@ export const defaultLegalPageViewStrings: LegalPageViewStrings = {
   toFrontPage: "Back to the front page",
 };
 
+/** Props for `LegalPageView`. */
 export interface LegalPageViewProps {
   /** The page from the API, or null when nobody has written it yet. */
   page: LegalPage | null;
   /** The heading while there is no page. */
   title: string;
-  /** The front page, for the link at the bottom. */
+  /** The front page's path, for the link at the bottom. */
   homeHref: string;
   /** The BCP 47 tag the date is written in, such as `nb-NO`. */
   dateLocale: string;
   strings?: TextOverrides<LegalPageViewStrings> | undefined;
 }
 
-/** A terms, privacy or cookies page as an admin wrote it: the title, when it last changed and the Markdown body. */
+/** Renders a terms, privacy, or cookies page as an admin wrote it: the title, when it last changed, and the Markdown body. */
 export function LegalPageView({ page, title, homeHref, dateLocale, strings }: LegalPageViewProps) {
   const text = withDefaults(defaultLegalPageViewStrings, strings);
   // A malformed timestamp leaves the date out rather than failing the page.

package/src/markdown/Markdown.tsx

@@ -5,20 +5,20 @@ import remarkGfm from "remark-gfm";
 
 type Tag = keyof React.JSX.IntrinsicElements;
 
-/** The props without the `node` react-markdown passes, which is no DOM attribute. */
+/** Copies the props without the `node` that react-markdown passes, since `node` is no DOM attribute. */
 function domProps<P extends ExtraProps>(props: P): Omit<P, "node"> {
   const rest = { ...props };
   delete rest.node;
   return rest;
 }
 
-/** An app's element, given the props without `node`, so it can spread them onto a DOM element. */
+/** Wraps an app's element so it gets the props without `node` and can spread them onto a DOM element. */
 function withoutNode(Element: ElementType) {
   const Wrapped = (props: ExtraProps) => <Element {...domProps(props)} />;
   return Wrapped;
 }
 
-/** An element with fixed classes. */
+/** Creates an element with fixed classes. */
 function styled<T extends Tag>(Element: T, className: string) {
   const Styled = (props: ComponentPropsWithoutRef<T> & ExtraProps) => {
     const Component = Element as ElementType;
@@ -27,7 +27,7 @@ function styled<T extends Tag>(Element: T, className: string) {
   return Styled;
 }
 
-/** The default look. A heading level one becomes a level two, since the page has its own `h1`. */
+/** The default elements. A level one heading becomes a level two heading, since the page has its own `h1`. */
 export const markdownComponents: Components = {
   h1: styled("h2", "text-lg font-semibold text-markdown-heading"),
   h2: styled("h2", "text-base font-semibold text-markdown-heading pt-2"),
@@ -54,20 +54,22 @@ export const markdownComponents: Components = {
 
 const isExternal = (href: string | undefined) => href != null && /^https?:\/\//i.test(href);
 
+/** Props for `Markdown`. */
 export interface MarkdownProps {
-  /** Markdown text. Empty, null or undefined renders nothing. */
+  /** The Markdown text. An empty string, null, or undefined renders nothing. */
   children: string | null | undefined;
-  /** Replaces the default element for a tag, such as `{ p: MyParagraph }`. It gets the props without `node`. */
+  /** The elements that replace the default element for a tag, such as `{ p: MyParagraph }`. Each gets the props without `node`. */
   components?: Components | undefined;
-  /** Opens links to other sites in a new tab, without passing the opener or referrer. */
+  /** Whether links to other sites open in a new tab, without passing the opener or referrer. Defaults to `false`. */
   externalLinks?: boolean | undefined;
-  /** Wraps the output in a `div` with these classes. Without it the elements render bare, so a parent's `space-y-*` spaces them. */
+  /** The classes for a `div` around the output. Without it, the elements render bare, so a parent's `space-y-*` spaces them. */
   className?: string | undefined;
 }
 
 /**
- * Markdown from an editor or the API, with GitHub tables, lists and links. Raw HTML is never
- * rendered, and the output is sanitized, so the text cannot inject scripts, styles or event handlers.
+ * Renders Markdown from an editor or the API, with GitHub tables, lists, and links. Raw HTML is
+ * never rendered, and the output is sanitized, so the text cannot inject scripts, styles, or event
+ * handlers.
  */
 export function Markdown({ children, components, externalLinks = false, className }: MarkdownProps) {
   if (!children) return null;

package/src/markdown/index.ts

@@ -1 +1 @@
-export { Markdown, markdownComponents, type MarkdownProps } from "./Markdown";
+export { Markdown, type MarkdownProps } from "./Markdown";

package/src/next-auth.d.ts

@@ -2,23 +2,25 @@
 // them with `import "@sjolystinnovation/app-kit/next-auth";` in one of its own .d.ts files.
 import "next-auth";
 import "next-auth/jwt";
+import type { SessionUser } from "./auth/createAuthOptions";
+import type { SessionError } from "./session/expiry";
 
 declare module "next-auth" {
   interface Session {
-    user: { id: string; name: string; email: string; roles: string[] };
+    user: SessionUser;
     accessToken: string;
-    error?: string | undefined;
-    absoluteExpiresAt?: number;
+    error?: SessionError | undefined;
+    absoluteExpiresAt?: number | undefined;
   }
 }
 
 declare module "next-auth/jwt" {
   interface JWT {
-    accessToken?: string;
-    refreshToken?: string;
-    refreshAt?: number;
-    loginAt?: number;
-    user?: { id: string; name: string; email: string; roles: string[] };
-    error?: string | undefined;
+    accessToken?: string | undefined;
+    refreshToken?: string | undefined;
+    refreshAt?: number | undefined;
+    loginAt?: number | undefined;
+    user?: SessionUser | undefined;
+    error?: SessionError | undefined;
   }
 }

package/src/next-config/headers.ts

@@ -0,0 +1,96 @@
+/** A response header, as `next.config.ts` lists them. */
+export interface Header {
+  key: string;
+  value: string;
+}
+
+/** Gets the API's origin, such as `https://api.example.com`. Returns `""` when the URL is missing or invalid. */
+export function apiOrigin(apiUrl: string | undefined): string {
+  if (!apiUrl) return "";
+  try {
+    return new URL(apiUrl).origin;
+  } catch {
+    return "";
+  }
+}
+
+/** Gets the API's base URL with its path, such as `https://api.example.com/api`, without a trailing slash. Returns `""` when the URL is missing or invalid. */
+export function apiBaseUrl(apiUrl: string | undefined): string {
+  if (!apiUrl) return "";
+  try {
+    return new URL(apiUrl).toString().replace(/\/$/, "");
+  } catch {
+    return "";
+  }
+}
+
+/** The Content-Security-Policy options for `defineAppConfig`. */
+export interface CspOptions {
+  /** The app's API URL, usually `process.env.NEXT_PUBLIC_API_URL`. The policy allows fetches to its origin. */
+  apiUrl: string | undefined;
+  /** Whether this is a development build. A development build also allows `'unsafe-eval'`, which hot reload needs. */
+  dev: boolean;
+  /** Whether to also allow `ws:` and `wss:` to the API, for a WebSocket such as SignalR. */
+  websocket?: boolean | undefined;
+  /** Whether to also allow images from the API origin. You do not need it when images go through the content images rewrite. */
+  imgFromApi?: boolean | undefined;
+  /** The extra sources for `connect-src`. */
+  connectSrc?: readonly string[] | undefined;
+  /** The extra sources for `img-src`. */
+  imgSrc?: readonly string[] | undefined;
+  /** The sources for `frame-src`. Defaults to `'none'`, since no page embeds a frame. */
+  frameSrc?: readonly string[] | undefined;
+  /** The sources for `object-src`. Defaults to `'none'`, since no page embeds an object. */
+  objectSrc?: readonly string[] | undefined;
+}
+
+const sources = (list: readonly (string | false | undefined)[]) => list.filter(Boolean).join(" ");
+
+/**
+ * Builds the Content-Security-Policy for an app's pages. Scripts allow `'unsafe-inline'`, because a
+ * nonce would make every statically rendered page dynamic.
+ */
+export function contentSecurityPolicy(o: CspOptions): string {
+  const origin = apiOrigin(o.apiUrl);
+  const wsOrigin = o.websocket ? origin.replace(/^https:/, "wss:").replace(/^http:/, "ws:") : "";
+  return [
+    "default-src 'self'",
+    o.dev ? "script-src 'self' 'unsafe-eval' 'unsafe-inline'" : "script-src 'self' 'unsafe-inline'",
+    "style-src 'self' 'unsafe-inline'",
+    `img-src ${sources(["'self'", o.imgFromApi && origin, "data:", "blob:", ...(o.imgSrc ?? [])])}`,
+    `connect-src ${sources(["'self'", origin, wsOrigin, ...(o.connectSrc ?? [])])}`,
+    `frame-src ${sources(o.frameSrc ?? ["'none'"])}`,
+    `object-src ${sources(o.objectSrc ?? ["'none'"])}`,
+    "font-src 'self'",
+    "base-uri 'self'",
+    "form-action 'self'",
+    "frame-ancestors 'none'",
+    "upgrade-insecure-requests",
+  ].join("; ");
+}
+
+/** Builds the security headers for an app's pages, including the Content-Security-Policy. */
+export function securityHeaders(o: CspOptions & { permissionsPolicy?: string | undefined }): Header[] {
+  return [
+    { key: "X-Content-Type-Options", value: "nosniff" },
+    { key: "X-Frame-Options", value: "DENY" },
+    { key: "Referrer-Policy", value: "strict-origin-when-cross-origin" },
+    { key: "X-DNS-Prefetch-Control", value: "on" },
+    { key: "Permissions-Policy", value: o.permissionsPolicy ?? "camera=(), microphone=(), geolocation=()" },
+    { key: "Strict-Transport-Security", value: "max-age=31536000; includeSubDomains" },
+    { key: "Content-Security-Policy", value: contentSecurityPolicy(o) },
+  ];
+}
+
+/**
+ * Builds the rewrite that proxies content images, so the browser never contacts the API host. It is
+ * a rewrite rather than a route handler, so the query string and the Accept header, which webp
+ * needs, pass through. Returns no rewrite when the API URL is missing or invalid.
+ */
+export function contentImagesRewrite(apiUrl: string | undefined, o: { source?: string | undefined; upstreamPath?: string | undefined } = {}) {
+  const base = apiBaseUrl(apiUrl);
+  if (!base) return [];
+  const source = o.source ?? "/content-images";
+  const upstream = o.upstreamPath ?? "/content-images";
+  return [{ source: `${source}/:path*`, destination: `${base}${upstream}/:path*` }];
+}

package/src/next-config/index.ts

@@ -1,128 +1,39 @@
 import type { NextConfig } from "next";
+import { contentImagesRewrite, securityHeaders, type CspOptions, type Header } from "./headers";
 
-/** A response header, as `next.config.ts` lists them. */
-export interface Header {
-  key: string;
-  value: string;
-}
-
-/** The API's origin, such as `https://api.example.com`. Empty when the URL is missing or invalid. */
-export function apiOrigin(apiUrl: string | undefined): string {
-  if (!apiUrl) return "";
-  try {
-    return new URL(apiUrl).origin;
-  } catch {
-    return "";
-  }
-}
-
-/** The API's base URL with its path, such as `https://api.example.com/api`, without a trailing slash. Empty when missing or invalid. */
-export function apiBaseUrl(apiUrl: string | undefined): string {
-  if (!apiUrl) return "";
-  try {
-    return new URL(apiUrl).toString().replace(/\/$/, "");
-  } catch {
-    return "";
-  }
-}
-
-export interface CspOptions {
-  /** The app's API URL, usually `process.env.NEXT_PUBLIC_API_URL`. Its origin may be fetched from. */
-  apiUrl: string | undefined;
-  /** Development builds also allow `'unsafe-eval'`, which hot reload needs. */
-  dev: boolean;
-  /** Also allow `ws:` and `wss:` to the API, for a WebSocket such as SignalR. */
-  websocket?: boolean | undefined;
-  /** Also allow images from the API origin. Not needed when images go through the content images rewrite. */
-  imgFromApi?: boolean | undefined;
-  /** Extra sources for `connect-src`. */
-  connectSrc?: readonly string[] | undefined;
-  /** Extra sources for `img-src`. */
-  imgSrc?: readonly string[] | undefined;
-  /** Sources for `frame-src`. Defaults to `'none'`, since no page embeds a frame. */
-  frameSrc?: readonly string[] | undefined;
-  /** Sources for `object-src`. Defaults to `'none'`, since no page embeds an object. */
-  objectSrc?: readonly string[] | undefined;
-}
-
-const sources = (list: readonly (string | false | undefined)[]) => list.filter(Boolean).join(" ");
-
-/**
- * The Content-Security-Policy for an app's pages. Scripts allow `'unsafe-inline'`, because a nonce
- * would make every statically rendered page dynamic.
- */
-export function contentSecurityPolicy(o: CspOptions): string {
-  const origin = apiOrigin(o.apiUrl);
-  const wsOrigin = o.websocket ? origin.replace(/^https:/, "wss:").replace(/^http:/, "ws:") : "";
-  return [
-    "default-src 'self'",
-    o.dev ? "script-src 'self' 'unsafe-eval' 'unsafe-inline'" : "script-src 'self' 'unsafe-inline'",
-    "style-src 'self' 'unsafe-inline'",
-    `img-src ${sources(["'self'", o.imgFromApi && origin, "data:", "blob:", ...(o.imgSrc ?? [])])}`,
-    `connect-src ${sources(["'self'", origin, wsOrigin, ...(o.connectSrc ?? [])])}`,
-    `frame-src ${sources(o.frameSrc ?? ["'none'"])}`,
-    `object-src ${sources(o.objectSrc ?? ["'none'"])}`,
-    "font-src 'self'",
-    "base-uri 'self'",
-    "form-action 'self'",
-    "frame-ancestors 'none'",
-    "upgrade-insecure-requests",
-  ].join("; ");
-}
-
-/** The security headers for an app's pages, including the Content-Security-Policy. */
-export function securityHeaders(o: CspOptions & { permissionsPolicy?: string | undefined }): Header[] {
-  return [
-    { key: "X-Content-Type-Options", value: "nosniff" },
-    { key: "X-Frame-Options", value: "DENY" },
-    { key: "Referrer-Policy", value: "strict-origin-when-cross-origin" },
-    { key: "X-DNS-Prefetch-Control", value: "on" },
-    { key: "Permissions-Policy", value: o.permissionsPolicy ?? "camera=(), microphone=(), geolocation=()" },
-    { key: "Strict-Transport-Security", value: "max-age=31536000; includeSubDomains" },
-    { key: "Content-Security-Policy", value: contentSecurityPolicy(o) },
-  ];
-}
-
-/**
- * Content images, proxied so the browser never contacts the API host. A rewrite rather than a route
- * handler, so the query string and the Accept header, which webp needs, pass through. No rewrite
- * when the API URL is missing or invalid.
- */
-export function contentImagesRewrite(apiUrl: string | undefined, o: { source?: string | undefined; upstreamPath?: string | undefined } = {}) {
-  const base = apiBaseUrl(apiUrl);
-  if (!base) return [];
-  const source = o.source ?? "/content-images";
-  const upstream = o.upstreamPath ?? "/content-images";
-  return [{ source: `${source}/:path*`, destination: `${base}${upstream}/:path*` }];
-}
+export type { CspOptions } from "./headers";
 
+/** Options for `defineAppConfig`. */
 export interface AppConfigOptions extends CspOptions {
-  /** Proxy `/content-images/*` to the API. See `contentImagesRewrite`. */
+  /**
+   * Whether to proxy `/content-images/*` to the API. The rewrite keeps the browser off the API host
+   * and passes the query string and the Accept header through.
+   */
   contentImages?: boolean | undefined;
   /**
-   * Headers for particular paths. Every path gets the page headers, and these come after them, so
-   * they replace a page header of the same name.
+   * The headers for particular paths. Every path gets the page headers, and these come after them,
+   * so they replace a page header of the same name.
    */
   pathHeaders?: readonly { source: string; headers: Header[] }[] | undefined;
-  /** Replaces the default Permissions-Policy. */
+  /** A Permissions-Policy that replaces the default one. */
   permissionsPolicy?: string | undefined;
   /**
-   * Seconds a cache may go on serving a page after it goes stale. Next's default is a year, long
-   * enough for a browser to hand back an old page and fetch the current one behind it. Defaults to
-   * 300, matching the client router cache's stale time.
+   * The number of seconds a cache may go on serving a page after it goes stale. Next's default is a
+   * year, long enough for a browser to hand back an old page and fetch the current one behind it.
+   * Defaults to `300`, matching the client router cache's stale time.
    */
   expireTime?: number | undefined;
   /**
-   * Write revalidated pages to disk. Off by default: with a read-only root filesystem Next cannot
-   * write to `.next/server/app`, so the incremental cache stays in memory.
+   * Whether to write revalidated pages to disk. Defaults to `false`. With a read-only root
+   * filesystem, Next cannot write to `.next/server/app`, so the incremental cache stays in memory.
    */
   isrFlushToDisk?: boolean | undefined;
 }
 
 /**
- * The shared Next config for an app: the standalone build, app-kit transpiled, no `X-Powered-By`,
- * the security headers on every page, and optionally the content images rewrite. `extra` is merged
- * over it, with `transpilePackages` and `images` combined.
+ * Builds the shared Next config for an app: the standalone build, app-kit transpiled, no
+ * `X-Powered-By`, the security headers on every page, and optionally the content images rewrite.
+ * `extra` is merged over it, with `transpilePackages` and `images` combined.
  */
 export function defineAppConfig(o: AppConfigOptions, extra: NextConfig = {}): NextConfig {
   const pageHeaders = securityHeaders(o);

package/src/payments/PaymentReturn.tsx

@@ -5,32 +5,34 @@ import Link from "next/link";
 import type { ReactNode } from "react";
 import { cx } from "../ui/cx";
 
+/** The outcome of a payment, as `PaymentReturn` shows it. */
 export type PaymentReturnState = "success" | "pending" | "failed";
 
-/** The text and the way on for one state. */
+/** The text and the next step for one state. */
 export interface PaymentReturnContent {
   title: string;
   body: string;
-  /** Where the button goes. */
+  /** The button's link target. */
   href: string;
   /** The button's text. */
   cta: string;
   /** A smaller line under the body. */
   note?: string | undefined;
-  /** Anything more under the body, such as a receipt link. */
+  /** Any more content under the body, such as a receipt link. */
   extra?: ReactNode;
 }
 
+/** Props for `PaymentReturn`. */
 export interface PaymentReturnProps {
   state: PaymentReturnState;
   success: PaymentReturnContent;
   pending: PaymentReturnContent;
   failed: PaymentReturnContent;
-  /** Checks the status again. Shows a button for it while pending. */
+  /** A function that checks the status again. While the state is pending, a button runs it. */
   onRefresh?: (() => void) | undefined;
   /** The refresh button's text. Defaults to `Check again`. */
   refreshLabel?: string | undefined;
-  /** Classes for placing it, on the outer element. */
+  /** The classes for placing the component, on its outer element. */
   className?: string | undefined;
 }
 
@@ -42,8 +44,8 @@ const refresh = "px-4 py-2.5 rounded-payment-button bg-button-primary-bg/80 text
 const secondary = "py-2.5 rounded-payment-button bg-payment-secondary-bg hover:bg-payment-secondary-hover-bg text-payment-secondary-text text-sm transition-colors";
 
 /**
- * What a user sees on coming back from a payment provider: confirmed, still pending, or failed.
- * The app decides the state, such as with `usePollUntilFinal`.
+ * Renders what a user sees on coming back from a payment provider: confirmed, still pending, or
+ * failed. The app decides the state, such as with `usePollUntilFinal`.
  */
 export function PaymentReturn({ state, success, pending, failed, onRefresh, refreshLabel = "Check again", className }: PaymentReturnProps) {
   const content = { success, pending, failed }[state];

package/src/payments/formatNok.ts

@@ -1,4 +1,4 @@
-/** An amount in øre as Norwegian kroner, such as `NOK 373,75`. */
+/** Formats an amount in øre as Norwegian kroner, such as `NOK 373,75`. */
 export function formatNok(ore: number): string {
   return `NOK ${(ore / 100).toFixed(2).replace(".", ",")}`;
 }

package/src/payments/usePollUntilFinal.ts

@@ -2,26 +2,28 @@
 
 import { useCallback, useEffect, useRef, useState } from "react";
 
+/** What `usePollUntilFinal` returns. */
 export interface PollResult<T> {
   /** The latest value, or null before the first answer. */
   data: T | null;
-  /** True until a final value, the last retry or a failed fetch. */
+  /** True until a final value, the last retry, or a failed fetch. */
   loading: boolean;
   /** Polls again from the start, with the spinner showing. */
   refresh: () => void;
 }
 
+/** Options for `usePollUntilFinal`. */
 export interface PollOptions {
-  /** How many more times to fetch after the first. Defaults to 8. */
+  /** The number of fetches after the first. Defaults to `8`. */
   retries?: number | undefined;
-  /** Milliseconds between fetches. Defaults to 4000. */
+  /** The milliseconds between fetches. Defaults to `4000`. */
   delayMs?: number | undefined;
 }
 
 /**
  * Fetches until the value is final, such as an order a payment provider has not confirmed yet when
- * the user comes back from it. Stops after the retries, on a failed fetch and on unmount. Each fetch
- * uses the latest `fetcher` and `isFinal` given.
+ * the user comes back from it. Stops after the retries, on a failed fetch, and on unmount. Each
+ * fetch uses the latest `fetcher` and `isFinal` given.
  */
 export function usePollUntilFinal<T>(
   fetcher: () => Promise<T | null>,

package/src/seo/JsonLd.tsx

@@ -1,6 +1,6 @@
 import { serializeGraph, type SchemaNode } from "./schema";
 
-/** One JSON-LD block. Search engines merge every block on a page into one graph. */
+/** Renders one JSON-LD block. Search engines merge every block on a page into one graph. */
 export function JsonLd({ nodes }: { nodes: SchemaNode[] }) {
   if (nodes.length === 0) return null;