@sjolystinnovation/app-kit 0.20.0 → 0.22.0

package/src/legal/LegalPageView.tsx

@@ -0,0 +1,62 @@
+import Link from "next/link";
+import type { LegalPage } from "../api/services";
+import { Markdown } from "../markdown";
+import { parseTimestamp } from "../seo/sitemap";
+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 {
+  /** The text before the date the page last changed. */
+  updated: string;
+  /** The text shown in place of the content when nobody has written the page yet. */
+  missing: string;
+  /** The text of the link back to the front page. */
+  toFrontPage: string;
+}
+
+export const defaultLegalPageViewStrings: LegalPageViewStrings = {
+  updated: "Last updated",
+  missing: "This content has not been written yet.",
+  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'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;
+}
+
+/** 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.
+  const updatedAt = parseTimestamp(page?.updatedAt);
+
+  return (
+    <div className="max-w-2xl mx-auto px-4 sm:px-6 py-12 space-y-6">
+      <h1 className="text-3xl font-black text-gray-900">{page?.title ?? title}</h1>
+      {updatedAt && (
+        <p className="text-xs text-gray-500">
+          {text.updated}: {new Intl.DateTimeFormat(dateLocale, { dateStyle: "long" }).format(updatedAt)}
+        </p>
+      )}
+
+      <div className="bg-white border border-gray-200 rounded-2xl p-6 shadow-sm space-y-4 text-sm text-gray-600">
+        {page ? <Markdown>{page.bodyMarkdown}</Markdown> : <p>{text.missing}</p>}
+      </div>
+
+      <p className="text-xs text-gray-500">
+        <Link href={homeHref} className="hover:text-gray-900 transition-colors">
+          ← {text.toFrontPage}
+        </Link>
+      </p>
+    </div>
+  );
+}

package/src/legal/index.ts

@@ -0,0 +1 @@
+export { LegalPageView, defaultLegalPageViewStrings, type LegalPageViewProps, type LegalPageViewStrings } from "./LegalPageView";

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;
 

package/src/seo/environment.ts

@@ -1,9 +1,9 @@
-/** Values of `SITE_ENV` that name the live site. `prod` is what the deploy workflows pass. */
+/** The values of `SITE_ENV` that name the live site. The deploy workflows pass `prod`. */
 const PRODUCTION = new Set(["production", "prod", ""]);
 
 /**
- * Whether this deployment is the one search engines should index. An unset `SITE_ENV` counts as
- * production, so a missing variable is never what deindexes the live site.
+ * Checks whether this deployment is the one search engines should index. An unset `SITE_ENV` counts
+ * as production, so a missing variable is never what deindexes the live site.
  */
 export function isIndexableEnvironment(siteEnv: string | undefined = process.env.SITE_ENV): boolean {
   return PRODUCTION.has(siteEnv?.trim().toLowerCase() ?? "");

package/src/seo/index.ts

@@ -3,10 +3,11 @@ export { JsonLd } from "./JsonLd";
 export { ref, serializeGraph, type OrganizationInfo, type SchemaNode, type SchemaRef } from "./schema";
 export {
   defineSite,
-  normalizePath,
+  LEGAL_PAGE_KEYS,
   NOINDEX,
   SHARE_IMAGE_SIZE,
   type Crumb,
+  type LegalEntriesInput,
   type LocaleEntryOptions,
   type OrganizationOptions,
   type PageMetadataInput,

package/src/seo/og/index.tsx

@@ -3,20 +3,21 @@ import { SHARE_IMAGE_SIZE } from "../site";
 
 export { SHARE_IMAGE_SIZE };
 
+/** Options for `shareImage`. */
 export interface ShareImageInput {
   name: string;
   tagline: string;
   /**
-   * Colours as literals. The image renders outside the browser, so it cannot read CSS custom
+   * The colors as literals. The image renders outside the browser, so it cannot read CSS custom
    * properties. `primary` is the bar above the name.
    */
   colors: { background: string; foreground: string; primary: string };
 }
 
 /**
- * The default share preview: the name, a bar in the brand colour and the tagline. Return it from a
- * route such as `[locale]/og/route.tsx`, which `pageMetadata` points at. A route, not the
- * `opengraph-image` file convention, since a page's own `openGraph` block replaces that image.
+ * Renders the default share preview: the name, a bar in the brand color, and the tagline. Return it
+ * from a route such as `[locale]/og/route.tsx`, which `pageMetadata` points at. It is a route, not
+ * the `opengraph-image` file convention, since a page's own `openGraph` block replaces that image.
  */
 export function shareImage({ name, tagline, colors }: ShareImageInput): ImageResponse {
   return new ImageResponse(

package/src/seo/schema.ts

@@ -10,9 +10,10 @@ export interface SchemaRef {
   "@id": string;
 }
 
+/** Creates a reference to the node with this `@id`. */
 export const ref = (id: string): SchemaRef => ({ "@id": id });
 
-/** The JSON-LD document for one page. `<` is escaped, so the payload cannot close the script tag. */
+/** Serializes the JSON-LD document for one page. `<` is escaped, so the payload cannot close the script tag. */
 export function serializeGraph(nodes: SchemaNode[]): string {
   return JSON.stringify({
     "@context": "https://schema.org",
@@ -20,7 +21,10 @@ export function serializeGraph(nodes: SchemaNode[]): string {
   }).replace(/</g, "\\u003c");
 }
 
-/** The business as the API describes it. Blank fields are left out of the structured data. */
+/**
+ * The business as the API describes it. The structured data leaves out blank fields, except the
+ * street address, which falls back to the one-line address.
+ */
 export interface OrganizationInfo {
   name: string;
   legalName?: string | undefined;