@sjolystinnovation/app-kit 0.19.0 → 0.21.0

package/src/admin/adminUsersPanelStrings.ts

@@ -0,0 +1,73 @@
+// Plain values, with no "use client", so a server component can import them.
+
+/**
+ * The users panel's text. Pass the app's own language. The defaults are English. `{name}` and `{role}`
+ * are filled in where a text names them.
+ */
+export interface AdminUsersPanelStrings {
+  users: string;
+  showDeleted: string;
+  inviteUser: string;
+  firstName: string;
+  lastName: string;
+  email: string;
+  role: string;
+  sendInvite: string;
+  sending: string;
+  inviteHint: string;
+  loading: string;
+  /** The tag after a deleted user's name. */
+  deleted: string;
+  delete: string;
+  /** Before the role name on the button that takes a role away. */
+  remove: string;
+  noRoles: string;
+  addRole: string;
+  add: string;
+  cancel: string;
+  usersLoadFailed: string;
+  rolesLoadFailed: string;
+  roleAssigned: string;
+  roleAssignFailed: string;
+  roleRemoved: string;
+  roleRemoveFailed: string;
+  confirmDelete: string;
+  userDeleted: string;
+  userDeleteFailed: string;
+  inviteIncomplete: string;
+  inviteSent: string;
+  inviteFailed: string;
+}
+
+export const defaultAdminUsersPanelStrings: AdminUsersPanelStrings = {
+  users: "Users",
+  showDeleted: "Show deleted",
+  inviteUser: "Invite user",
+  firstName: "First name",
+  lastName: "Last name",
+  email: "Email",
+  role: "Role",
+  sendInvite: "Send invitation",
+  sending: "Sending…",
+  inviteHint: "The user gets an email with a code and sets a password on the forgotten password page.",
+  loading: "Loading…",
+  deleted: "deleted",
+  delete: "Delete",
+  remove: "Remove",
+  noRoles: "No roles",
+  addRole: "Add role",
+  add: "Add",
+  cancel: "Cancel",
+  usersLoadFailed: "Failed to load users",
+  rolesLoadFailed: "Failed to load roles",
+  roleAssigned: "Added {role} to {name}",
+  roleAssignFailed: "Failed to assign role",
+  roleRemoved: "Removed {role} from {name}",
+  roleRemoveFailed: "Failed to remove role",
+  confirmDelete: "Delete {name}? Their name, email and password are removed, and they cannot sign in again.",
+  userDeleted: "User deleted",
+  userDeleteFailed: "Failed to delete user",
+  inviteIncomplete: "Fill in the name and email",
+  inviteSent: "Invitation sent. The user gets a code to set a password.",
+  inviteFailed: "Failed to send the invitation",
+};

package/src/admin/companySettingsFormStrings.ts

@@ -0,0 +1,50 @@
+// Plain values, with no "use client", so a server component can import them.
+
+/** The company settings form's text. Pass the app's own language. The defaults are English. */
+export interface CompanySettingsFormStrings {
+  contactRecipient: string;
+  contactRecipientHint: string;
+  companyName: string;
+  legalName: string;
+  legalNameHint: string;
+  orgNumber: string;
+  vatRegistered: string;
+  vatHint: string;
+  streetAddress: string;
+  postalCode: string;
+  addressLocality: string;
+  addressRegion: string;
+  addressHint: string;
+  publicEmail: string;
+  publicPhone: string;
+  loading: string;
+  save: string;
+  saving: string;
+  loadFailed: string;
+  saved: string;
+  saveFailed: string;
+}
+
+export const defaultCompanySettingsFormStrings: CompanySettingsFormStrings = {
+  contactRecipient: "Contact enquiry recipient",
+  contactRecipientHint: "Contact form enquiries are emailed to this address.",
+  companyName: "Company name",
+  legalName: "Legal name",
+  legalNameHint: "The registered name. Leave blank to use the company name.",
+  orgNumber: "Organisation number",
+  vatRegistered: "VAT (MVA) registered",
+  vatHint: "When on, the org number is shown with the “MVA” suffix.",
+  streetAddress: "Street address",
+  postalCode: "Postal code",
+  addressLocality: "Place",
+  addressRegion: "County",
+  addressHint: "The county is optional.",
+  publicEmail: "Public email",
+  publicPhone: "Public phone",
+  loading: "Loading…",
+  save: "Save",
+  saving: "Saving…",
+  loadFailed: "Failed to load settings",
+  saved: "Settings saved",
+  saveFailed: "Failed to save",
+};

package/src/admin/index.ts

@@ -0,0 +1,20 @@
+export { CompanySettingsForm } from "./CompanySettingsForm";
+export type { CompanySettingsFormProps } from "./CompanySettingsForm";
+export { defaultCompanySettingsFormStrings } from "./companySettingsFormStrings";
+export type { CompanySettingsFormStrings } from "./companySettingsFormStrings";
+export { AdminShell } from "./AdminShell";
+export type { AdminShellProps, AdminTab } from "./AdminShell";
+export { StatHistoryChart } from "./StatHistoryChart";
+export { STAT_SERIES_COLORS, defaultStatHistoryChartStrings } from "./statHistoryChartStrings";
+export type { StatHistoryChartProps, StatSeries } from "./StatHistoryChart";
+export type { StatHistoryChartStrings } from "./statHistoryChartStrings";
+export { AdminUsersPanel } from "./AdminUsersPanel";
+export type { AdminUsersPanelProps } from "./AdminUsersPanel";
+export { defaultAdminUsersPanelStrings } from "./adminUsersPanelStrings";
+export type { AdminUsersPanelStrings } from "./adminUsersPanelStrings";
+export { LegalPagesEditor } from "./LegalPagesEditor";
+export type { LegalPagesEditorProps } from "./LegalPagesEditor";
+export { defaultLegalPagesEditorStrings } from "./legalPagesEditorStrings";
+export type { LegalPagesEditorStrings } from "./legalPagesEditorStrings";
+export { LocaleTabs } from "./LocaleTabs";
+export type { LocaleTabsProps } from "./LocaleTabs";

package/src/admin/legalPagesEditorStrings.ts

@@ -0,0 +1,32 @@
+// Plain values, with no "use client", so a server component can import them.
+
+/** The legal pages editor's text. Pass the app's own language. The defaults are English. */
+export interface LegalPagesEditorStrings {
+  heading: string;
+  title: string;
+  bodyMarkdown: string;
+  /** The title of the dot on a locale with no content yet. */
+  notFilled: string;
+  loading: string;
+  save: string;
+  saving: string;
+  loadFailed: string;
+  /** When the title or the content is blank. */
+  required: string;
+  saved: string;
+  saveFailed: string;
+}
+
+export const defaultLegalPagesEditorStrings: LegalPagesEditorStrings = {
+  heading: "Legal pages",
+  title: "Title",
+  bodyMarkdown: "Content (Markdown)",
+  notFilled: "Not filled in",
+  loading: "Loading…",
+  save: "Save",
+  saving: "Saving…",
+  loadFailed: "Failed to load the legal pages",
+  required: "Fill in the title and the content",
+  saved: "Page saved",
+  saveFailed: "Failed to save the page",
+};

package/src/admin/statHistoryChartStrings.ts

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

package/src/api/company.ts

@@ -0,0 +1,46 @@
+/** The business as SjolystInnovation.AppKit.SiteSettings's public `/company` endpoint describes it. */
+export interface CompanyInfo {
+  name: string;
+  legalName: string;
+  orgNumber: string;
+  vatRegistered: boolean;
+  /** The address on one line, for display. The API derives it from the parts below. */
+  address: string;
+  streetAddress: string;
+  postalCode: string;
+  addressLocality: string;
+  addressRegion: string;
+  email: string;
+  phone: string;
+}
+
+/** What the app knows about the business without the API. Only the name is required. */
+export type CompanyFallback = Partial<CompanyInfo> & { name: string };
+
+/**
+ * The company details for public pages: the API's answer, with the app's own values for any field
+ * it left blank or could not give. The legal name falls back to the name, and VAT to not registered.
+ */
+export function mergeCompanyInfo(data: Partial<CompanyInfo> | null | undefined, fallback: CompanyFallback): CompanyInfo {
+  const name = data?.name || fallback.name;
+  const pick = (key: Exclude<keyof CompanyInfo, "name" | "legalName" | "vatRegistered">) => data?.[key] || fallback[key] || "";
+  return {
+    name,
+    legalName: data?.legalName || fallback.legalName || name,
+    orgNumber: pick("orgNumber"),
+    vatRegistered: data?.vatRegistered ?? fallback.vatRegistered ?? false,
+    address: pick("address"),
+    streetAddress: pick("streetAddress"),
+    postalCode: pick("postalCode"),
+    addressLocality: pick("addressLocality"),
+    addressRegion: pick("addressRegion"),
+    email: pick("email"),
+    phone: pick("phone"),
+  };
+}
+
+/** The org number with the Norwegian ` MVA` suffix once the business is VAT registered. Empty without a number. */
+export function formatOrgNumber({ orgNumber, vatRegistered }: { orgNumber?: string | null | undefined; vatRegistered?: boolean | null | undefined }): string {
+  if (!orgNumber) return "";
+  return vatRegistered ? `${orgNumber} MVA` : orgNumber;
+}

package/src/api/index.ts

@@ -1,7 +1,11 @@
 export { apiFieldErrors } from "./apiFieldErrors";
+export { formatOrgNumber, mergeCompanyInfo } from "./company";
+export type { CompanyFallback, CompanyInfo } from "./company";
 export { createApiClient } from "./createApiClient";
 export { request } from "./request";
 export { requestRevalidate } from "./requestRevalidate";
+export { defineRevalidateTargets } from "./revalidateTargets";
+export type { RevalidateTargetPaths, RevalidateTargetsConfig } from "./revalidateTargets";
 export {
   createPublicClient,
   createUserService,

package/src/api/revalidateTargets.ts

@@ -0,0 +1,40 @@
+import { normalizePath } from "../seo/site";
+import { requestRevalidate } from "./requestRevalidate";
+
+/** The pages one admin edit changes. */
+export interface RevalidateTargetPaths {
+  /** Paths below each locale segment, such as `/builds/[slug]`. `""` is the locale's front page. */
+  pages?: readonly string[] | undefined;
+  /** Paths outside the locale segments, such as `/sitemap.xml`. */
+  root?: readonly string[] | undefined;
+}
+
+export interface RevalidateTargetsConfig<T extends string> {
+  /** The locale segments every page is under. A site without them omits this. */
+  locales?: readonly string[] | undefined;
+  targets: Record<T, RevalidateTargetPaths>;
+}
+
+/**
+ * The cache targets an app's admin edits purge, in one place for both sides: `targets` names them
+ * for fetch tags, `paths` is what `createRevalidateRoute` purges for each, and `revalidate` asks the
+ * route to purge one after an edit. A target with no paths is purged by its tag alone.
+ */
+export function defineRevalidateTargets<T extends string>({ locales = [], targets }: RevalidateTargetsConfig<T>) {
+  const names = Object.keys(targets) as T[];
+
+  return {
+    targets: Object.fromEntries(names.map(name => [name, name])) as { readonly [K in T]: K },
+    paths: Object.fromEntries(
+      names.map(name => {
+        const { pages = [], root = [] } = targets[name];
+        const localized =
+          locales.length > 0
+            ? locales.flatMap(locale => pages.map(page => `/${locale}${normalizePath(page)}`))
+            : pages.map(page => normalizePath(page) || "/");
+        return [name, [...localized, ...root]];
+      }),
+    ) as Record<T, string[]>,
+    revalidate: (target: T): Promise<void> => requestRevalidate(target),
+  };
+}

package/src/legal/LegalPageView.tsx

@@ -0,0 +1,61 @@
+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 {
+  /** Before the date the page last changed. */
+  updated: string;
+  /** Shown in place of the content when nobody has written the page yet. */
+  missing: string;
+  /** 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",
+};
+
+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. */
+  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. */
+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/next-auth.d.ts

@@ -0,0 +1,24 @@
+// The session fields this package's auth options put on next-auth's session and token. An app loads
+// them with `import "@sjolystinnovation/app-kit/next-auth";` in one of its own .d.ts files.
+import "next-auth";
+import "next-auth/jwt";
+
+declare module "next-auth" {
+  interface Session {
+    user: { id: string; name: string; email: string; roles: string[] };
+    accessToken: string;
+    error?: string | undefined;
+    absoluteExpiresAt?: number;
+  }
+}
+
+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;
+  }
+}

package/src/seo/index.ts

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

package/src/seo/site.ts

@@ -1,6 +1,7 @@
 import type { Metadata, MetadataRoute } from "next";
 import { isIndexableEnvironment } from "./environment";
 import { ref, type OrganizationInfo, type SchemaNode } from "./schema";
+import { parseTimestamp } from "./sitemap";
 
 /** The size of the share image. */
 export const SHARE_IMAGE_SIZE = { width: 1200, height: 630 } as const;
@@ -52,12 +53,22 @@ export interface Crumb {
 }
 
 export interface LocaleEntryOptions<L extends string> {
-  /** The locales the page exists in. Defaults to all of them. */
+  /** The locales the page exists in. Defaults to all of them. A site without locales ignores it. */
   locales?: readonly L[] | undefined;
-  /** When the page last changed, per locale. Left out when unknown. */
+  /** When the page last changed, per locale. Left out when unknown. A site without locales calls it once, with no locale. */
   lastModified?: ((locale: L) => Date | undefined) | undefined;
 }
 
+/** The legal pages every site has, as `createLegalService` names them. */
+export const LEGAL_PAGE_KEYS = ["terms", "privacy", "cookies"] as const;
+
+export interface LegalEntriesInput<K extends string, L extends string> {
+  /** The legal pages, each at `/<key>` below the locale. Defaults to `LEGAL_PAGE_KEYS`. */
+  keys?: readonly K[] | undefined;
+  /** When a page last changed, as the API's timestamp. A site without locales gets no locale. */
+  updatedAt: (key: K, locale: L | undefined) => Promise<string | null | undefined>;
+}
+
 export interface RobotsInput {
   /** Paths below each locale segment that must not be crawled, such as `/admin`. */
   privatePaths?: readonly string[] | undefined;
@@ -68,8 +79,10 @@ export interface RobotsInput {
 }
 
 export interface OrganizationOptions {
-  /** The schema.org type, such as `Organization` or `ComputerStore`. Defaults to `Organization`. */
-  type?: string | undefined;
+  /** The schema.org type, such as `ComputerStore`, or several, such as `["Organization", "LocalBusiness"]`. Defaults to `Organization`. */
+  type?: string | readonly string[] | undefined;
+  /** Pages about the same business elsewhere, such as its entry in Brønnøysundregistrene. */
+  sameAs?: readonly 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`. */
@@ -166,8 +179,16 @@ export function defineSite<L extends string = string>(config: SiteConfig<L>) {
     };
   };
 
-  /** One sitemap entry per locale a page is served in, each listing the others as alternates. */
+  /**
+   * One sitemap entry per locale a page is served in, each listing the others as alternates. A site
+   * without locales has one URL per page, so it gets one entry with no alternates.
+   */
   const localeEntries = (path: string, options: LocaleEntryOptions<L> = {}): MetadataRoute.Sitemap => {
+    if (locales.length === 0) {
+      // There is no locale to pass, and the callback's type cannot say so without making every caller's simpler.
+      const lastModified = options.lastModified?.(undefined as never);
+      return [{ url: absoluteUrl(path), ...(lastModified ? { lastModified } : {}) }];
+    }
     const served = options.locales ?? locales;
 
     const languages: Record<string, string> = Object.fromEntries(served.map(l => [tag(l), absoluteLocaleUrl(l, path)]));
@@ -181,6 +202,27 @@ export function defineSite<L extends string = string>(config: SiteConfig<L>) {
     });
   };
 
+  /** Runs `load` for every locale at once and keys the results by locale. A site without locales gets `{}`. */
+  const forEachLocale = async <T>(load: (locale: L) => Promise<T>): Promise<Partial<Record<L, T>>> =>
+    Object.fromEntries(await Promise.all(locales.map(async locale => [locale, await load(locale)] as const))) as Partial<Record<L, T>>;
+
+  /**
+   * The legal pages' sitemap entries, each dated by when it last changed in that locale. The
+   * timestamps are fetched at once. An error from `updatedAt` fails the sitemap, so a stale one is
+   * served rather than one without dates.
+   */
+  const legalEntries = async <K extends string = (typeof LEGAL_PAGE_KEYS)[number]>({
+    keys,
+    updatedAt,
+  }: LegalEntriesInput<K, L>): Promise<MetadataRoute.Sitemap> => {
+    const pages = keys ?? (LEGAL_PAGE_KEYS as unknown as readonly K[]);
+    const served: (L | undefined)[] = locales.length > 0 ? [...locales] : [undefined];
+    const stamps = await Promise.all(
+      pages.map(key => Promise.all(served.map(async locale => parseTimestamp(await updatedAt(key, locale))))),
+    );
+    return pages.flatMap((key, k) => localeEntries(`/${key}`, { lastModified: locale => stamps[k]?.[served.indexOf(locale)] }));
+  };
+
   /**
    * 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.
@@ -203,16 +245,19 @@ export function defineSite<L extends string = string>(config: SiteConfig<L>) {
   /** The business, under a stable `@id` that page-scoped nodes point at. */
   const organizationNode = (company: OrganizationInfo, options: OrganizationOptions = {}): SchemaNode => {
     const country = options.country ?? "NO";
+    const type = typeof options.type === "string" ? options.type || undefined : options.type?.length ? [...options.type] : undefined;
+    const phone = company.phone?.trim();
+    const email = company.email?.trim();
     return {
-      "@type": options.type ?? "Organization",
+      "@type": 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,
+      ...(phone ? { telephone: phone } : {}),
+      ...(email ? { email } : {}),
       address: {
         "@type": "PostalAddress",
         streetAddress: company.streetAddress || company.address,
@@ -224,6 +269,7 @@ export function defineSite<L extends string = string>(config: SiteConfig<L>) {
       areaServed: country,
       ...(company.vatRegistered && company.orgNumber ? { vatID: `NO${company.orgNumber.replace(/\s/g, "")}MVA` } : {}),
       ...(company.orgNumber ? { taxID: company.orgNumber } : {}),
+      ...(options.sameAs?.length ? { sameAs: [...options.sameAs] } : {}),
     };
   };
 
@@ -268,6 +314,8 @@ export function defineSite<L extends string = string>(config: SiteConfig<L>) {
     pageMetadata,
     siteMetadata,
     localeEntries,
+    forEachLocale,
+    legalEntries,
     robots,
     siteId,
     ids,

package/src/styles.css

@@ -82,6 +82,15 @@
   --color-auth-link-hover: var(--color-gray-900);
   --font-weight-auth-link: var(--font-weight-semibold);
 
+  --color-admin-title: var(--color-gray-900);
+  --color-admin-border: var(--color-gray-200);
+  --color-admin-tab: var(--color-gray-500);
+  --color-admin-tab-hover: var(--color-gray-900);
+  --color-admin-tab-active: var(--color-gray-900);
+  --color-admin-tab-indicator: var(--color-primary);
+  --color-chart-grid: var(--color-gray-200);
+  --color-chart-label: var(--color-gray-400);
+
   --radius-button: var(--radius-lg);
   --color-button-primary-bg: var(--color-primary);
   --color-button-primary-text: var(--color-primary-foreground);

package/src/testing/index.ts

@@ -0,0 +1,113 @@
+// Test doubles for the modules every app's tests mock. Import them inside the vi.mock factory, which
+// vitest hoists above the file's own imports:
+//
+//   vi.mock("next-auth/react", async () => (await import("@sjolystinnovation/app-kit/testing")).nextAuthMock());
+//
+// The test then imports the same module instance to set the state and read the spies, and calls
+// resetTestMocks before each test, since the state lives for the whole file.
+import type { ReactNode } from "react";
+import type { Session } from "next-auth";
+import { vi } from "vitest";
+
+type SessionStatus = "loading" | "authenticated" | "unauthenticated";
+
+/** What `useSession` returns, and the next-auth calls as spies. `update` is the one `useSession` returns. */
+export const auth = {
+  state: { data: null, status: "unauthenticated" } as { data: Session | null; status: SessionStatus },
+  signIn: vi.fn(),
+  signOut: vi.fn(),
+  getSession: vi.fn(),
+  update: vi.fn(),
+};
+
+/** A signed-in session with `roles`. Defaults to an admin. */
+export function makeSession({ roles = ["Admin"], ...overrides }: Partial<Session> & { roles?: string[] } = {}): Session {
+  return {
+    user: { id: "1", name: "admin", email: "a@b.no", roles },
+    accessToken: "token",
+    expires: "",
+    ...overrides,
+  };
+}
+
+/** Signs in with `session`, signs out with null, or leaves the session loading. */
+export function setSession(session: Session | null | "loading"): void {
+  auth.state =
+    session === "loading"
+      ? { data: null, status: "loading" }
+      : session === null
+        ? { data: null, status: "unauthenticated" }
+        : { data: session, status: "authenticated" };
+}
+
+/** The `next-auth/react` module, reading `auth`. */
+export function nextAuthMock() {
+  return {
+    useSession: () => ({ ...auth.state, update: (...args: unknown[]) => auth.update(...args) }),
+    signIn: (...args: unknown[]) => auth.signIn(...args),
+    signOut: (...args: unknown[]) => auth.signOut(...args),
+    getSession: (...args: unknown[]) => auth.getSession(...args),
+    SessionProvider: ({ children }: { children?: ReactNode }) => children,
+  };
+}
+
+/** The current URL and the router's calls as spies. */
+export const navigation = {
+  pathname: "/",
+  searchParams: new URLSearchParams(),
+  router: { push: vi.fn(), replace: vi.fn(), refresh: vi.fn(), back: vi.fn(), forward: vi.fn(), prefetch: vi.fn() },
+};
+
+/** The `next/navigation` hooks, reading `navigation`. */
+export function nextNavigationMock() {
+  return {
+    useRouter: () => navigation.router,
+    usePathname: () => navigation.pathname,
+    useSearchParams: () => navigation.searchParams,
+  };
+}
+
+/** The toast calls as spies. */
+export const toastSpies = {
+  success: vi.fn(),
+  error: vi.fn(),
+  info: vi.fn(),
+  warning: vi.fn(),
+  message: vi.fn(),
+  loading: vi.fn(),
+  promise: vi.fn(),
+  dismiss: vi.fn(),
+};
+
+/** The `sonner` module, or `@sjolystinnovation/app-kit/toast`. A bare `toast(text)` goes to `toastSpies.message`. */
+export function toastMock() {
+  const toast = Object.assign((...args: unknown[]) => toastSpies.message(...args), {
+    success: (...args: unknown[]) => toastSpies.success(...args),
+    error: (...args: unknown[]) => toastSpies.error(...args),
+    info: (...args: unknown[]) => toastSpies.info(...args),
+    warning: (...args: unknown[]) => toastSpies.warning(...args),
+    message: (...args: unknown[]) => toastSpies.message(...args),
+    loading: (...args: unknown[]) => toastSpies.loading(...args),
+    promise: (...args: unknown[]) => toastSpies.promise(...args),
+    dismiss: (...args: unknown[]) => toastSpies.dismiss(...args),
+  });
+  return { toast, Toaster: () => null };
+}
+
+/** The HTTP calls of an app's axios instance as spies. */
+export const axiosSpies = { get: vi.fn(), post: vi.fn(), put: vi.fn(), patch: vi.fn(), delete: vi.fn() };
+
+/** A module whose default export is an axios instance, such as the app's `services/axiosInstance`. */
+export function axiosInstanceMock() {
+  return { default: axiosSpies };
+}
+
+/** Signs out, goes back to `/`, and clears every spy's calls and answers. */
+export function resetTestMocks(): void {
+  setSession(null);
+  navigation.pathname = "/";
+  navigation.searchParams = new URLSearchParams();
+  for (const spy of [auth.signIn, auth.signOut, auth.getSession, auth.update, ...Object.values(navigation.router), ...Object.values(toastSpies), ...Object.values(axiosSpies)]) {
+    spy.mockReset();
+  }
+}