@sjolystinnovation/app-kit 0.12.0 → 0.14.0

package/README.md

@@ -28,7 +28,7 @@ const nextConfig: NextConfig = {
 };
 ```
 
-The components in `@sjolystinnovation/app-kit/ui`, `markdown` and `session/react` are styled with Tailwind CSS.
+The components in `@sjolystinnovation/app-kit/ui`, `markdown`, `branding` and `session/react` are styled with Tailwind CSS.
 Import the package's stylesheet after Tailwind:
 
 ```css
@@ -378,6 +378,151 @@ The text takes its colour and size from the parent. A level one heading becomes
 the page has its own `h1`. `markdownComponents` holds the default elements, for an app that builds
 on them.
 
+### `@sjolystinnovation/app-kit/seo`
+
+Search engine helpers for one site: canonical URLs with hreflang, page metadata with Open Graph,
+sitemap entries, robots.txt and schema.org structured data. It works in a server component.
+`defineSite` binds them to the site's name, canonical origin and locales:
+
+```ts
+// src/lib/seo/site.ts
+import { defineSite } from "@sjolystinnovation/app-kit/seo";
+
+export const site = defineSite({
+  name: "Altinnendata",
+  url: "https://www.altinnendata.no",
+  titleSeparator: " | ",
+  locales: ["no", "en"],
+  defaultLocale: "no",
+  localeTags: { no: "no", en: "en" },
+  tagline: locale => getDictionary(locale).meta.tagline,
+});
+```
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `name` | `string` | The site's name, in titles, Open Graph and structured data. |
+| `url` | `string` | The canonical origin, without a trailing slash. |
+| `titleSeparator` | `string` | Between a page title and the site name. |
+| `locales` | `string[]` | The locale segments every page is under. A site without them leaves it out, and its paths have no segment. |
+| `defaultLocale` | `string` | The locale `x-default` points at. Defaults to the first. |
+| `localeTags` | `Record<locale, string>` | The BCP 47 tag per locale. Defaults to the locale. |
+| `tagline` | `(locale) => string` | The line after the name in the default title and the share image's alt text. |
+| `shareImagePath` | `string` | The share image route below each locale. Defaults to `/og`. |
+
+The site gives:
+
+- `localePath(locale, path)`, `absoluteUrl(path)`, `absoluteLocaleUrl(locale, path)` and
+  `languageAlternates(path)`. Paths get a leading slash and no trailing slash.
+- `siteMetadata({ locale, description, manifest })` for the locale root layout: the title
+  template, `metadataBase`, the index directive and the front page's canonical.
+- `pageMetadata({ locale, path, title, description, images })` for a page: the canonical URL,
+  hreflang, and Open Graph with the locale's share image unless `images` is given.
+- `localeEntries(path, { locales, lastModified })` for `sitemap.ts`: one entry per locale, each
+  listing the others. `lastModified` is left out when unknown.
+- `robots({ privatePaths, privateRootPaths, indexable })` for `robots.ts`. The private paths are
+  disallowed under every locale segment. A deployment that is not production disallows everything.
+- `organizationNode(company, { type, country, image, logo })`, `webSiteNode(locale)`,
+  `breadcrumbNode(crumbs, pageUrl)`, `itemListNode(paths, pageUrl)`, `siteId(fragment)` and `ids`
+  for structured data.
+
+```tsx
+// src/app/robots.ts
+export const dynamic = "force-dynamic";
+export default () => site.robots({ privatePaths: ["/admin", "/login"], privateRootPaths: ["/api/"] });
+
+// in a page
+<JsonLd nodes={[site.organizationNode(company), site.webSiteNode(locale)]} />
+```
+
+`isIndexableEnvironment()` reads `SITE_ENV`. `prod`, `production` and unset or blank count as
+production, so a missing variable never deindexes the live site. `robots.ts` needs
+`dynamic = "force-dynamic"`, so it reads the variable per request. The package also exports
+`JsonLd`, `serializeGraph`, `ref`, `NOINDEX`, `SHARE_IMAGE_SIZE`, `normalizePath`, `latest` and
+`parseTimestamp`.
+
+### `@sjolystinnovation/app-kit/seo/og`
+
+`shareImage({ name, tagline, colors })` renders the default share preview, a PNG at
+`SHARE_IMAGE_SIZE`: the name, a bar in `colors.primary` and the tagline. The colours are literals,
+since the image renders outside the browser. Return it from the route `pageMetadata` points at:
+
+```tsx
+// src/app/[locale]/og/route.tsx
+import { shareImage } from "@sjolystinnovation/app-kit/seo/og";
+
+export async function GET(_request: Request, { params }: { params: Promise<{ locale: string }> }) {
+  const { locale } = await params;
+  return shareImage({ name: site.name, tagline: getDictionary(locale).meta.tagline, colors: BRAND });
+}
+```
+
+It is a route rather than the `opengraph-image` file convention, since a page's own `openGraph`
+block replaces that image.
+
+### `@sjolystinnovation/app-kit/branding`
+
+The logo and favicon an admin uploads, as the API's `/branding` endpoint returns them.
+
+`BrandingProvider` holds them for the components below it. It takes the branding the server
+rendered with, loads it on mount when there is none, and loads it again every five minutes, so an
+open tab picks up a change. A failed load keeps what it has. `useBranding()` gives `branding`,
+`logoUrl` as a `data:` URL or null, and `refresh()`.
+
+```tsx
+"use client";
+import { BrandingProvider, useBranding } from "@sjolystinnovation/app-kit/branding";
+
+<BrandingProvider load={BrandingService.get} initial={initialBranding}>{children}</BrandingProvider>;
+
+const { logoUrl } = useBranding();
+<img src={logoUrl ?? "/logo.png"} alt="" />;
+```
+
+`BrandingManager` is the admin form for uploading or removing them. It needs a `BrandingProvider`
+above it, and refreshes it after a save.
+
+```tsx
+<BrandingManager save={form => BrandingService.update(form)} />
+```
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `save` | `(form: FormData) => Promise<unknown>` | Sends `logo` and `icon` files, and `removeLogo` and `removeIcon` set to `true`. Throw to show the error's message. |
+| `strings` | `TextOverrides<BrandingManagerStrings>` | The form's text. |
+
+`toDataUrl(data, contentType)` turns base64 bytes into a `data:` URL.
+
+### `@sjolystinnovation/app-kit/branding/server`
+
+`brandingIcon({ load, fallbackPath, fallbackType })` is 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 file
+otherwise, since an SVG or HTML upload could run script on the site's origin. Both carry `nosniff`
+and a sandbox CSP, which a CSP header from the app's `next.config` replaces. When the branding cannot be
+loaded it answers 503 with `no-store`, since a browser would cache the bundled icon in place of the
+one set in settings.
+
+```ts
+// src/app/icon.ts
+import { join } from "node:path";
+import { brandingIcon } from "@sjolystinnovation/app-kit/branding/server";
+
+export const dynamic = "force-dynamic";
+
+export default function Icon() {
+  return brandingIcon({
+    load: () => publicGet<Branding>("/branding", { tags: ["branding"] }),
+    fallbackPath: join(process.cwd(), "public", "icon.png"),
+    fallbackType: "image/png",
+  });
+}
+```
+
+The route needs `dynamic = "force-dynamic"`, or the build bakes in the icon of the moment. Tag the
+fetch and revalidate the tag after a save, so a new icon shows at once. `iconVersion(data)` is a
+short digest of the icon bytes, for a manifest icon URL such as `/icon?v=<digest>`, since Android
+refreshes a home screen icon only when the manifest changes.
+
 ### `@sjolystinnovation/app-kit/session`
 
 Decides when a user has to sign in again. Safe to import from server code, such as the next-auth

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjolystinnovation/app-kit",
-  "version": "0.12.0",
+  "version": "0.14.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",
@@ -27,6 +27,10 @@
     "./validation": "./src/validation/index.ts",
     "./next-config": "./src/next-config/index.ts",
     "./markdown": "./src/markdown/index.ts",
+    "./seo": "./src/seo/index.ts",
+    "./seo/og": "./src/seo/og/index.tsx",
+    "./branding": "./src/branding/index.ts",
+    "./branding/server": "./src/branding/server.ts",
     "./styles.css": "./src/styles.css"
   },
   "files": [

package/src/branding/BrandingManager.tsx

@@ -0,0 +1,185 @@
+"use client";
+
+import { ArrowUpTrayIcon, TrashIcon } from "@heroicons/react/24/outline";
+import { useEffect, useRef, useState } from "react";
+import { toast } from "../toast";
+import { withDefaults, type TextOverrides } from "../ui/withDefaults";
+import { useBranding } from "./BrandingProvider";
+import { toDataUrl } from "./types";
+
+export interface BrandingManagerStrings {
+  title: string;
+  logo: string;
+  logoHint: string;
+  icon: string;
+  iconHint: string;
+  none: string;
+  choose: string;
+  remove: string;
+  save: string;
+  saving: string;
+  saved: string;
+  saveFailed: string;
+}
+
+export const defaultBrandingManagerStrings: BrandingManagerStrings = {
+  title: "Branding",
+  logo: "Logo",
+  logoHint: "Shown in the navbar and footer. PNG/SVG, max 2 MB.",
+  icon: "Icon (favicon)",
+  iconHint: "Browser tab icon. Square PNG/ICO, max 2 MB.",
+  none: "none",
+  choose: "Choose",
+  remove: "Remove",
+  save: "Save branding",
+  saving: "Saving…",
+  saved: "Branding saved",
+  saveFailed: "Failed to save branding",
+};
+
+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`.
+   */
+  save: (form: FormData) => Promise<unknown>;
+  strings?: TextOverrides<BrandingManagerStrings> | undefined;
+}
+
+/** A preview is an object URL for the chosen file or a data URL of a raster image. Anything else shows none. */
+const PREVIEW_URL = /^(blob:|data:image\/(png|jpeg|webp|gif|x-icon|vnd\.microsoft\.icon);base64,)/i;
+const previewUrl = (url: string | null): string | null => (url !== null && PREVIEW_URL.test(url) ? url : null);
+
+interface SlotProps {
+  label: string;
+  hint: string;
+  currentUrl: string | null;
+  file: File | null;
+  onPick: (file: File | null) => void;
+  onClear: () => void;
+  text: BrandingManagerStrings;
+}
+
+function Slot({ label, hint, currentUrl, file, onPick, onClear, text }: SlotProps) {
+  const inputRef = useRef<HTMLInputElement>(null);
+  const [objectUrl, setObjectUrl] = useState<string | null>(null);
+
+  // An object URL is an outside resource with a lifetime, which is what an effect is for. Creating
+  // it during render instead leaks the second URL that StrictMode builds when it renders twice.
+  /* eslint-disable react-hooks/set-state-in-effect */
+  useEffect(() => {
+    if (!file) {
+      setObjectUrl(null);
+      return;
+    }
+    const url = URL.createObjectURL(file);
+    setObjectUrl(url);
+    return () => URL.revokeObjectURL(url);
+  }, [file]);
+  /* eslint-enable react-hooks/set-state-in-effect */
+
+  const preview = previewUrl(objectUrl ?? currentUrl);
+  return (
+    <div>
+      <label className="block text-sm font-medium text-gray-700 mb-1">{label}</label>
+      <div className="flex items-center gap-3">
+        <div className="h-14 w-14 rounded-lg border border-gray-200 bg-gray-50 flex items-center justify-center overflow-hidden">
+          {preview ? (
+            <img src={preview} alt={label} className="max-h-full max-w-full object-contain" />
+          ) : (
+            <span className="text-xs text-gray-400">{text.none}</span>
+          )}
+        </div>
+        <input
+          ref={inputRef}
+          type="file"
+          accept="image/*"
+          aria-label={label}
+          className="hidden"
+          onChange={e => onPick(e.target.files?.[0] ?? null)}
+        />
+        <button
+          type="button"
+          onClick={() => inputRef.current?.click()}
+          className="inline-flex items-center gap-1.5 rounded-lg bg-gray-100 text-gray-700 font-medium px-3 py-2 text-sm hover:bg-gray-200"
+        >
+          <ArrowUpTrayIcon className="h-4 w-4" /> {text.choose}
+        </button>
+        {(currentUrl || file) && (
+          <button type="button" onClick={onClear} className="p-2 rounded-lg text-red-500 hover:bg-red-50" title={text.remove} aria-label={`${text.remove} ${label}`}>
+            <TrashIcon className="h-4 w-4" />
+          </button>
+        )}
+      </div>
+      <p className="mt-1 text-xs text-gray-500">{hint}</p>
+    </div>
+  );
+}
+
+/** The admin form for uploading or removing the logo and the favicon. Needs a `BrandingProvider` above it. */
+export function BrandingManager({ save, strings }: BrandingManagerProps) {
+  const text = withDefaults(defaultBrandingManagerStrings, strings);
+  const { branding, refresh } = useBranding();
+  const [logo, setLogo] = useState<File | null>(null);
+  const [icon, setIcon] = useState<File | null>(null);
+  const [removeLogo, setRemoveLogo] = useState(false);
+  const [removeIcon, setRemoveIcon] = useState(false);
+  const [saving, setSaving] = useState(false);
+
+  const currentLogo = removeLogo ? null : toDataUrl(branding.logoData, branding.logoContentType);
+  const currentIcon = removeIcon ? null : toDataUrl(branding.iconData, branding.iconContentType);
+
+  const submit = async () => {
+    setSaving(true);
+    try {
+      const form = new FormData();
+      if (logo) form.append("logo", logo);
+      if (icon) form.append("icon", icon);
+      if (removeLogo) form.append("removeLogo", "true");
+      if (removeIcon) form.append("removeIcon", "true");
+      await save(form);
+      setLogo(null);
+      setIcon(null);
+      setRemoveLogo(false);
+      setRemoveIcon(false);
+      refresh();
+      toast.success(text.saved);
+    } catch (err) {
+      toast.error(err instanceof Error && err.message ? err.message : text.saveFailed);
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  return (
+    <div className="max-w-md space-y-5 border-t border-gray-200 pt-6">
+      <h2 className="font-bold text-gray-900">{text.title}</h2>
+      <Slot
+        label={text.logo}
+        hint={text.logoHint}
+        currentUrl={currentLogo}
+        file={logo}
+        onPick={f => { setLogo(f); setRemoveLogo(false); }}
+        onClear={() => { setLogo(null); setRemoveLogo(true); }}
+        text={text}
+      />
+      <Slot
+        label={text.icon}
+        hint={text.iconHint}
+        currentUrl={currentIcon}
+        file={icon}
+        onPick={f => { setIcon(f); setRemoveIcon(false); }}
+        onClear={() => { setIcon(null); setRemoveIcon(true); }}
+        text={text}
+      />
+      <button
+        type="button"
+        onClick={submit}
+        disabled={saving || (!logo && !icon && !removeLogo && !removeIcon)}
+        className="rounded-button bg-button-primary-bg text-button-primary-text font-semibold px-5 py-2.5 hover:brightness-95 disabled:opacity-60 transition"
+      >
+        {saving ? text.saving : text.save}
+      </button>
+    </div>
+  );
+}

package/src/branding/BrandingProvider.tsx

@@ -0,0 +1,53 @@
+"use client";
+
+import { createContext, useCallback, useContext, useEffect, useRef, useState, type ReactNode } from "react";
+import { toDataUrl, type Branding } from "./types";
+
+export interface BrandingContextValue {
+  branding: Branding;
+  /** The logo as a `data:` URL, or null when none is set. */
+  logoUrl: string | null;
+  /** Loads the branding again, such as after saving it. */
+  refresh: () => void;
+}
+
+const BrandingContext = createContext<BrandingContextValue>({ branding: {}, logoUrl: null, refresh: () => {} });
+
+/** The branding from the nearest `BrandingProvider`. Empty 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;
+
+export interface BrandingProviderProps {
+  children: ReactNode;
+  /** Loads the branding, such as a GET of `/branding`. A failure 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. */
+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.
+  const loadRef = useRef(load);
+  useEffect(() => {
+    loadRef.current = load;
+  }, [load]);
+  const hasInitial = initial !== undefined;
+
+  const refresh = useCallback(() => {
+    loadRef.current().then(setBranding).catch(() => {});
+  }, []);
+
+  useEffect(() => {
+    if (!hasInitial) refresh();
+    const id = setInterval(refresh, BRANDING_REFRESH_MS);
+    return () => clearInterval(id);
+  }, [refresh, hasInitial]);
+
+  const logoUrl = toDataUrl(branding.logoData, branding.logoContentType);
+
+  return <BrandingContext.Provider value={{ branding, logoUrl, refresh }}>{children}</BrandingContext.Provider>;
+}

package/src/branding/index.ts

@@ -0,0 +1,14 @@
+export {
+  BrandingManager,
+  defaultBrandingManagerStrings,
+  type BrandingManagerProps,
+  type BrandingManagerStrings,
+} from "./BrandingManager";
+export {
+  BRANDING_REFRESH_MS,
+  BrandingProvider,
+  useBranding,
+  type BrandingContextValue,
+  type BrandingProviderProps,
+} from "./BrandingProvider";
+export { toDataUrl, type Branding } from "./types";

package/src/branding/server.ts

@@ -0,0 +1,54 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import type { Branding } from "./types";
+
+export interface BrandingIconOptions {
+  /** Loads the branding, such as a cached GET of `/branding`. 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`. */
+  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.
+ */
+export async function brandingIcon({ load, fallbackPath, fallbackType }: BrandingIconOptions): Promise<Response> {
+  let branding: Branding | null | undefined;
+  try {
+    branding = await load();
+  } catch {
+    return new Response(null, { status: 503, headers: { "Cache-Control": "no-store" } });
+  }
+
+  const type = branding?.iconContentType?.trim().toLowerCase();
+  if (branding?.iconData && type && RASTER_TYPES.has(type)) {
+    return new Response(new Uint8Array(Buffer.from(branding.iconData, "base64")), {
+      headers: { "Content-Type": type, ...HARDENING },
+    });
+  }
+
+  return new Response(new Uint8Array(await readFile(fallbackPath)), { headers: { "Content-Type": fallbackType, ...HARDENING } });
+}
+
+/**
+ * The uploaded types the icon route serves. An SVG or HTML upload could carry script and would run
+ * on the site's origin, so anything else gives the bundled icon instead.
+ */
+const RASTER_TYPES = new Set(["image/png", "image/jpeg", "image/webp", "image/gif", "image/x-icon", "image/vnd.microsoft.icon"]);
+
+/** Keeps a browser from sniffing the bytes as another type, and from running anything in them where the app sets no CSP. */
+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
+ * `/icon?v=<digest>` in the web app manifest. Android refreshes a home screen icon only when the
+ * manifest changes.
+ */
+export const iconVersion = (data: string | Buffer): string => createHash("sha256").update(data).digest("hex").slice(0, 12);

package/src/branding/types.ts

@@ -0,0 +1,13 @@
+/** The logo and favicon set in admin settings, as the API's `/branding` endpoint returns them. */
+export interface Branding {
+  /** Base64 image bytes. */
+  logoData?: string | null | undefined;
+  logoContentType?: string | null | undefined;
+  /** Base64 image bytes. */
+  iconData?: string | null | undefined;
+  iconContentType?: string | null | undefined;
+}
+
+/** A `data:` URL for base64 image bytes, or 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/seo/JsonLd.tsx

@@ -0,0 +1,8 @@
+import { serializeGraph, type SchemaNode } from "./schema";
+
+/** 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;
+
+  return <script type="application/ld+json" dangerouslySetInnerHTML={{ __html: serializeGraph(nodes) }} />;
+}

package/src/seo/environment.ts

@@ -0,0 +1,10 @@
+/** Values of `SITE_ENV` that name the live site. `prod` is what the deploy workflows pass. */
+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.
+ */
+export function isIndexableEnvironment(siteEnv: string | undefined = process.env.SITE_ENV): boolean {
+  return PRODUCTION.has(siteEnv?.trim().toLowerCase() ?? "");
+}

package/src/seo/index.ts

@@ -0,0 +1,18 @@
+export { isIndexableEnvironment } from "./environment";
+export { JsonLd } from "./JsonLd";
+export { ref, serializeGraph, type OrganizationInfo, type SchemaNode, type SchemaRef } from "./schema";
+export {
+  defineSite,
+  normalizePath,
+  NOINDEX,
+  SHARE_IMAGE_SIZE,
+  type Crumb,
+  type LocaleEntryOptions,
+  type OrganizationOptions,
+  type PageMetadataInput,
+  type RobotsInput,
+  type Site,
+  type SiteConfig,
+  type SiteMetadataInput,
+} from "./site";
+export { latest, parseTimestamp } from "./sitemap";

package/src/seo/og/index.tsx

@@ -0,0 +1,43 @@
+import { ImageResponse } from "next/og";
+import { SHARE_IMAGE_SIZE } from "../site";
+
+export { SHARE_IMAGE_SIZE };
+
+export interface ShareImageInput {
+  name: string;
+  tagline: string;
+  /**
+   * Colours 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.
+ */
+export function shareImage({ name, tagline, colors }: ShareImageInput): ImageResponse {
+  return new ImageResponse(
+    (
+      <div
+        style={{
+          width: "100%",
+          height: "100%",
+          display: "flex",
+          flexDirection: "column",
+          justifyContent: "center",
+          padding: "80px",
+          background: colors.background,
+          color: colors.foreground,
+        }}
+      >
+        <div style={{ display: "flex", width: 120, height: 12, background: colors.primary }} />
+        <div style={{ marginTop: 48, fontSize: 96, fontWeight: 800, letterSpacing: "-0.03em" }}>{name}</div>
+        <div style={{ marginTop: 24, fontSize: 34, lineHeight: 1.3, color: "rgba(255,255,255,0.75)" }}>{tagline}</div>
+      </div>
+    ),
+    SHARE_IMAGE_SIZE,
+  );
+}

package/src/seo/schema.ts

@@ -0,0 +1,37 @@
+/** One schema.org node. Nodes share a `@graph` and refer to each other by `@id`. */
+export interface SchemaNode {
+  "@type": string | string[];
+  "@id"?: string;
+  [key: string]: unknown;
+}
+
+/** A reference to another node in the same graph. */
+export interface SchemaRef {
+  "@id": string;
+}
+
+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. */
+export function serializeGraph(nodes: SchemaNode[]): string {
+  return JSON.stringify({
+    "@context": "https://schema.org",
+    "@graph": nodes,
+  }).replace(/</g, "\\u003c");
+}
+
+/** The business as the API describes it. Blank fields are left out of the structured data. */
+export interface OrganizationInfo {
+  name: string;
+  legalName?: string | undefined;
+  orgNumber?: string | undefined;
+  vatRegistered?: boolean | undefined;
+  /** The address on one line. Used for the street when `streetAddress` is blank. */
+  address?: string | undefined;
+  streetAddress?: string | undefined;
+  postalCode?: string | undefined;
+  addressLocality?: string | undefined;
+  addressRegion?: string | undefined;
+  email?: string | undefined;
+  phone?: string | undefined;
+}

package/src/seo/site.ts

@@ -0,0 +1,281 @@
+import type { Metadata, MetadataRoute } from "next";
+import { isIndexableEnvironment } from "./environment";
+import { ref, type OrganizationInfo, type SchemaNode } from "./schema";
+
+/** The size of the share image. */
+export const SHARE_IMAGE_SIZE = { width: 1200, height: 630 } as const;
+
+/** The robots directive for pages that exist for signed-in users only. */
+export const NOINDEX: Metadata["robots"] = { index: false, follow: false };
+
+export interface SiteConfig<L extends string> {
+  /** The site's name, as in titles, Open Graph and structured data. */
+  name: string;
+  /** The canonical origin, such as `https://www.example.no`, without a trailing slash. */
+  url: string;
+  /** Between a page title and the site name, such as `" | "`. */
+  titleSeparator: string;
+  /** The locale segments every page is under, such as `["no", "en"]`. A site without them omits this. */
+  locales?: readonly L[] | undefined;
+  /** The locale `x-default` points at. Defaults to the first locale. */
+  defaultLocale?: L | undefined;
+  /** The BCP 47 tag for each locale, for hreflang and Open Graph. Defaults to the locale itself. */
+  localeTags?: Partial<Record<L, string>> | undefined;
+  /** The short line under the name, per locale. Used in the default title and the share image's alt text. */
+  tagline?: ((locale: L) => string) | undefined;
+  /** The share image route below each locale. Defaults to `/og`. */
+  shareImagePath?: string | undefined;
+}
+
+export interface PageMetadataInput<L extends string> {
+  locale: L;
+  /** The path below the locale segment, such as `/builds/my-pc`. Omit for the front page. */
+  path?: string | undefined;
+  /** The page title, without the site name. The root layout's template adds it. */
+  title?: string | undefined;
+  description?: string | undefined;
+  /** Image URLs for the share preview. Defaults to the share image for the locale. */
+  images?: string[] | undefined;
+}
+
+export interface SiteMetadataInput<L extends string> {
+  locale: L;
+  description?: string | undefined;
+  /** The web app manifest's path, such as `/manifest.json`. */
+  manifest?: string | undefined;
+}
+
+export interface Crumb {
+  name: string;
+  /** A site-relative path, such as `/no/builds`. The last crumb is the current page and has none. */
+  path?: string | undefined;
+}
+
+export interface LocaleEntryOptions<L extends string> {
+  /** The locales the page exists in. Defaults to all of them. */
+  locales?: readonly L[] | undefined;
+  /** When the page last changed, per locale. Left out when unknown. */
+  lastModified?: ((locale: L) => Date | undefined) | undefined;
+}
+
+export interface RobotsInput {
+  /** Paths below each locale segment that must not be crawled, such as `/admin`. */
+  privatePaths?: readonly string[] | undefined;
+  /** Paths outside the locale segments that must not be crawled, such as `/api/`. */
+  privateRootPaths?: readonly string[] | undefined;
+  /** Whether search engines may index this deployment. Defaults to `isIndexableEnvironment()`. */
+  indexable?: boolean | undefined;
+}
+
+export interface OrganizationOptions {
+  /** The schema.org type, such as `Organization` or `ComputerStore`. Defaults to `Organization`. */
+  type?: string | undefined;
+  /** The ISO country code for the address and the area served. Defaults to `NO`. */
+  country?: string | undefined;
+  /** Site-relative paths of the square image and the logo. Default to `/icon.png` and `/logo.png`. */
+  image?: string | undefined;
+  logo?: string | undefined;
+}
+
+/**
+ * One leading slash, no trailing slash. `""` and `"/"` both mean the front page. Tabs and line
+ * breaks are removed, as a URL parser removes them, and leading slashes and backslashes collapse
+ * to one, so a path always stays on the site's own host.
+ */
+export function normalizePath(path: string): string {
+  const clean = path.replace(/[\t\n\r]/g, "");
+  if (clean === "") return "";
+  const withSlash = `/${clean.replace(/^[/\\]+/, "")}`;
+  return withSlash.endsWith("/") ? withSlash.slice(0, -1) : withSlash;
+}
+
+/**
+ * The URL, metadata, sitemap, robots and structured data helpers for one site, bound to its name,
+ * canonical origin and locales.
+ */
+export function defineSite<L extends string = string>(config: SiteConfig<L>) {
+  const locales = config.locales ?? [];
+  const defaultLocale = config.defaultLocale ?? locales[0];
+  const tag = (locale: L) => config.localeTags?.[locale] ?? locale;
+  const shareImagePath = config.shareImagePath ?? "/og";
+  const origin = new URL(config.url).origin;
+
+  /** A site-relative URL for a page in one locale, such as `/no/builds`. A site without locales has no segment. */
+  const localePath = (locale: L | undefined, path = ""): string =>
+    locale === undefined || locales.length === 0 ? normalizePath(path) || "/" : `/${locale}${normalizePath(path)}`;
+
+  /** An absolute URL on the canonical origin, without a trailing slash. */
+  const absoluteUrl = (path = ""): string => {
+    const url = new URL(normalizePath(path) || "/", config.url);
+    // A path that would leave the site's origin gives the front page instead.
+    if (url.origin !== origin) return config.url;
+    return url.toString().replace(/\/$/, "") || config.url;
+  };
+
+  const absoluteLocaleUrl = (locale: L, path = ""): string => absoluteUrl(localePath(locale, path));
+
+  /** Language alternates by BCP 47 tag. `x-default` points at the default locale. */
+  const languageAlternates = (path: string): Record<string, string> => ({
+    ...Object.fromEntries(locales.map(l => [tag(l), localePath(l, path)])),
+    ...(defaultLocale !== undefined ? { "x-default": localePath(defaultLocale, path) } : {}),
+  });
+
+  const fullTitle = (locale: L) => {
+    const tagline = config.tagline?.(locale);
+    return tagline ? `${config.name}${config.titleSeparator}${tagline}` : config.name;
+  };
+
+  const defaultShareImage = (locale: L) => ({
+    url: localePath(locale, shareImagePath),
+    ...SHARE_IMAGE_SIZE,
+    type: "image/png",
+    alt: fullTitle(locale),
+  });
+
+  /** The canonical URL, hreflang set and Open Graph for one public page. */
+  const pageMetadata = ({ locale, path = "", title, description, images }: PageMetadataInput<L>): Metadata => {
+    const canonical = localePath(locale, path);
+    return {
+      ...(title ? { title } : {}),
+      ...(description ? { description } : {}),
+      alternates: {
+        canonical,
+        ...(locales.length > 0 ? { languages: languageAlternates(path) } : {}),
+      },
+      openGraph: {
+        type: "website",
+        siteName: config.name,
+        locale: tag(locale),
+        url: canonical,
+        ...(title ? { title } : {}),
+        ...(description ? { description } : {}),
+        images: images ?? [defaultShareImage(locale)],
+      },
+    };
+  };
+
+  /** The metadata for the locale root layout: the title template, the index directive and the front page's canonical. */
+  const siteMetadata = ({ locale, description, manifest }: SiteMetadataInput<L>): Metadata => {
+    const title = fullTitle(locale);
+    return {
+      ...pageMetadata({ locale, title, description }),
+      metadataBase: new URL(config.url),
+      title: { default: title, template: `%s${config.titleSeparator}${config.name}` },
+      ...(manifest ? { manifest } : {}),
+      robots: { index: true, follow: true },
+    };
+  };
+
+  /** One sitemap entry per locale a page is served in, each listing the others as alternates. */
+  const localeEntries = (path: string, options: LocaleEntryOptions<L> = {}): MetadataRoute.Sitemap => {
+    const served = options.locales ?? locales;
+
+    const languages: Record<string, string> = Object.fromEntries(served.map(l => [tag(l), absoluteLocaleUrl(l, path)]));
+    if (defaultLocale !== undefined && served.includes(defaultLocale)) {
+      languages["x-default"] = absoluteLocaleUrl(defaultLocale, path);
+    }
+
+    return served.map(locale => {
+      const lastModified = options.lastModified?.(locale);
+      return { url: absoluteLocaleUrl(locale, path), ...(lastModified ? { lastModified } : {}), alternates: { languages } };
+    });
+  };
+
+  /**
+   * robots.txt. A deployment that is not production disallows everything. Otherwise the private
+   * paths are disallowed under every locale segment, since a bare `/admin` matches nothing there.
+   */
+  const robots = ({ privatePaths = [], privateRootPaths = [], indexable = isIndexableEnvironment() }: RobotsInput = {}): MetadataRoute.Robots => {
+    if (!indexable) return { rules: { userAgent: "*", disallow: "/" } };
+
+    const below = locales.length > 0 ? locales.flatMap(l => privatePaths.map(p => localePath(l, p))) : [...privatePaths];
+    return {
+      rules: { userAgent: "*", allow: "/", disallow: [...below, ...privateRootPaths] },
+      sitemap: absoluteUrl("/sitemap.xml"),
+      host: config.url,
+    };
+  };
+
+  /** An `@id` for an entity that is the same on every page. Page-scoped nodes use the page URL. */
+  const siteId = (fragment: string): string => `${config.url}/#${fragment}`;
+  const ids = { organization: siteId("organization"), website: siteId("website") } as const;
+
+  /** The business, under a stable `@id` that page-scoped nodes point at. */
+  const organizationNode = (company: OrganizationInfo, options: OrganizationOptions = {}): SchemaNode => {
+    const country = options.country ?? "NO";
+    return {
+      "@type": options.type ?? "Organization",
+      "@id": ids.organization,
+      name: company.name,
+      ...(company.legalName && company.legalName !== company.name ? { legalName: company.legalName } : {}),
+      url: absoluteUrl(),
+      image: absoluteUrl(options.image ?? "/icon.png"),
+      logo: absoluteUrl(options.logo ?? "/logo.png"),
+      telephone: company.phone,
+      email: company.email,
+      address: {
+        "@type": "PostalAddress",
+        streetAddress: company.streetAddress || company.address,
+        ...(company.postalCode ? { postalCode: company.postalCode } : {}),
+        ...(company.addressLocality ? { addressLocality: company.addressLocality } : {}),
+        ...(company.addressRegion ? { addressRegion: company.addressRegion } : {}),
+        addressCountry: country,
+      },
+      areaServed: country,
+      ...(company.vatRegistered && company.orgNumber ? { vatID: `NO${company.orgNumber.replace(/\s/g, "")}MVA` } : {}),
+      ...(company.orgNumber ? { taxID: company.orgNumber } : {}),
+    };
+  };
+
+  /** The site as an entity, so search engines attribute its pages to it and to the business. */
+  const webSiteNode = (locale: L): SchemaNode => ({
+    "@type": "WebSite",
+    "@id": ids.website,
+    url: absoluteUrl(),
+    name: config.name,
+    inLanguage: tag(locale),
+    publisher: ref(ids.organization),
+  });
+
+  /** The trail search results show in place of the raw URL. The last crumb has no `item`. */
+  const breadcrumbNode = (crumbs: Crumb[], pageUrl: string): SchemaNode => ({
+    "@type": "BreadcrumbList",
+    "@id": `${pageUrl}#breadcrumb`,
+    itemListElement: crumbs.map((crumb, index) => ({
+      "@type": "ListItem",
+      position: index + 1,
+      name: crumb.name,
+      ...(crumb.path ? { item: absoluteUrl(crumb.path) } : {}),
+    })),
+  });
+
+  /** Marks a listing page as an ordered set of pages. */
+  const itemListNode = (paths: string[], pageUrl: string): SchemaNode => ({
+    "@type": "ItemList",
+    "@id": `${pageUrl}#itemlist`,
+    numberOfItems: paths.length,
+    itemListElement: paths.map((path, index) => ({ "@type": "ListItem", position: index + 1, url: absoluteUrl(path) })),
+  });
+
+  return {
+    name: config.name,
+    url: config.url,
+    normalizePath,
+    localePath,
+    absoluteUrl,
+    absoluteLocaleUrl,
+    languageAlternates,
+    pageMetadata,
+    siteMetadata,
+    localeEntries,
+    robots,
+    siteId,
+    ids,
+    organizationNode,
+    webSiteNode,
+    breadcrumbNode,
+    itemListNode,
+  };
+}
+
+export type Site<L extends string = string> = ReturnType<typeof defineSite<L>>;

package/src/seo/sitemap.ts

@@ -0,0 +1,13 @@
+/** The latest of a set of timestamps, or undefined when there are none. */
+export function latest(dates: readonly (Date | undefined)[]): Date | undefined {
+  const known = dates.filter((date): date is Date => date != null);
+  if (known.length === 0) return undefined;
+  return known.reduce((newest, date) => (date > newest ? date : newest));
+}
+
+/** Parses an API timestamp. A missing or malformed value gives undefined. */
+export function parseTimestamp(value: string | null | undefined): Date | undefined {
+  if (!value) return undefined;
+  const date = new Date(value);
+  return Number.isNaN(date.getTime()) ? undefined : date;
+}