@awsmbiz/create-inbis-app 0.0.0-stage → 0.1.0

package/template/src/v1.ts

@@ -0,0 +1,24 @@
+import { createRoute, z } from "@hono/zod-openapi";
+import { createRouter } from "@awsmbiz/inbis-api";
+// inbis:wire v1.imports
+
+const HelloQuery = z.object({ name: z.string().min(1).max(100) });
+const HelloSchema = z.object({ message: z.string() }).openapi("Hello");
+
+const hello = createRoute({
+  method: "get",
+  path: "/hello",
+  tags: ["app"],
+  summary: "Greet someone (an example route: replace it with your own)",
+  request: { query: HelloQuery },
+  responses: {
+    200: { description: "The greeting", content: { "application/json": { schema: HelloSchema } } },
+  },
+});
+
+/** Version 1 API routes, mounted under `/v1`. Each route is documented in `/openapi.json`. */
+export function createV1() {
+  const v1 = createRouter<Env>();
+  // inbis:wire v1.routes
+  return v1.openapi(hello, (c) => c.json({ message: `Hello, ${c.req.valid("query").name}` }, 200));
+}

package/template/standalone/.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+# The platform's app CI: install, typecheck, lint, unit + Workers
+# integration tests, build, Playwright + axe. `ci-v1` moves with compatible changes only.
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  ci:
+    permissions:
+      contents: read
+    uses: awsmbiz/inbis-platform/.github/workflows/app-ci.yml@ci-v1

package/template/standalone/.github/workflows/deploy.yml

@@ -0,0 +1,32 @@
+# The platform's deploy pipeline. A push to main deploys staging. A v* tag whose commit is on
+# main, pushed by someone in production-actors, deploys staging and then production (after
+# a D1 Time Travel bookmark). Each run: secrets check, migrations (platform sources, then
+# the app), deploy, smoke test. `ci-v1` moves with compatible changes only.
+name: Deploy
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  deploy:
+    permissions:
+      contents: read
+    uses: awsmbiz/inbis-platform/.github/workflows/app-deploy.yml@ci-v1
+    with:
+      # GitHub logins allowed to release to production by pushing a v* tag. Keep it short.
+      production-actors: ""
+      staging-url: https://staging.react-hono-app.example.com
+      production-url: https://react-hono-app.example.com
+    secrets:
+      CLOUDFLARE_API_TOKEN_STAGING: ${{ secrets.CLOUDFLARE_API_TOKEN_STAGING }}
+      CLOUDFLARE_API_TOKEN_PRODUCTION: ${{ secrets.CLOUDFLARE_API_TOKEN_PRODUCTION }}
+      CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+      SMOKE_EMAIL_STAGING: ${{ secrets.SMOKE_EMAIL_STAGING }}
+      SMOKE_PASSWORD_STAGING: ${{ secrets.SMOKE_PASSWORD_STAGING }}
+      SMOKE_EMAIL_PRODUCTION: ${{ secrets.SMOKE_EMAIL_PRODUCTION }}
+      SMOKE_PASSWORD_PRODUCTION: ${{ secrets.SMOKE_PASSWORD_PRODUCTION }}

package/template/standalone/.nvmrc

@@ -0,0 +1 @@
+24

package/template/standalone/_gitignore

@@ -0,0 +1,9 @@
+node_modules/
+dist/
+web/dist/
+.wrangler/
+.dev.vars
+*.log
+coverage/
+test-results/
+playwright-report/

package/template/standalone/pnpm-workspace.yaml

@@ -0,0 +1,11 @@
+# pnpm settings for this app (a single-package repository).
+
+# Dependencies allowed to run install scripts (pnpm blocks all others).
+allowBuilds:
+  esbuild: true
+  workerd: true
+
+# pnpm holds back releases younger than a day by default. Platform releases
+# (exact pins from npm) are installed as soon as they are published.
+minimumReleaseAgeExclude:
+  - "@awsmbiz/*"

package/template/template.json

@@ -0,0 +1,56 @@
+{
+  "$comment": "The template's base manifest (docs/template-modules.md). Not copied into apps.",
+  "exclude": [
+    "template.json",
+    "modules",
+    "standalone",
+    "node_modules",
+    "dist",
+    "web/dist",
+    ".wrangler",
+    ".turbo",
+    ".dev.vars",
+    "test-results",
+    "playwright-report"
+  ],
+  "standalone": "standalone",
+  "bindings": {
+    "DB": "the app's own D1 database (migrations/)"
+  },
+  "wiring": {
+    "worker.imports": { "file": "src/app.ts", "description": "Imports for the Worker composition." },
+    "worker.deps": { "file": "src/app.ts", "description": "Fields of AppDeps: what src/index.ts injects (senders, configs)." },
+    "worker.routes": { "file": "src/app.ts", "description": "Inside createApp, after createApi: middleware and mount* calls on `app`." },
+    "index.imports": { "file": "src/index.ts", "description": "Imports for the Worker entry." },
+    "index.setup": { "file": "src/index.ts", "description": "Module-load setup from `env` (config validation; fails startup)." },
+    "index.deps": { "file": "src/index.ts", "description": "Properties of the AppDeps object built from `env`." },
+    "index.handlers": { "file": "src/index.ts", "description": "Extra Worker handlers (e.g. `scheduled`)." },
+    "v1.imports": { "file": "src/v1.ts", "description": "Imports for the /v1 router." },
+    "v1.routes": { "file": "src/v1.ts", "description": "Statements on the `v1` router before the base routes (middleware, `v1.route(...)`)." },
+    "audit.imports": { "file": "src/audit-sink.ts", "description": "Imports for the audit sink hook (the audit log)." },
+    "audit.catalogues.imports": { "file": "src/audit-catalogues.ts", "description": "Imports of platform packages' audit action catalogues." },
+    "audit.catalogues": { "file": "src/audit-catalogues.ts", "description": "Platform audit action catalogues the app's audit trail registers (e.g. AUTH_AUDIT_ACTIONS), comma-terminated." },
+    "audit.sink": { "file": "src/audit-sink.ts", "description": "The audit sink factory `(env, options) => AuditSink` platform packages record to (the audit module's). At most one." },
+    "env.bindings": { "file": "src/env.d.ts", "description": "Env members: bindings, vars and secrets the module adds to wrangler.jsonc." },
+    "wrangler.vars": { "file": "wrangler.jsonc", "description": "Vars, per env (dev, staging, production). Entries end with a comma." },
+    "wrangler.secrets": { "file": "wrangler.jsonc", "description": "Required secret names, per env. Entries end with a comma." },
+    "wrangler.bindings": { "file": "wrangler.jsonc", "description": "Top-level keys of an env (services, triggers, kv_namespaces...), per env. Entries end with a comma." },
+    "wrangler.d1": { "file": "wrangler.jsonc", "description": "D1 bindings to the app's database, per env, before DB (platform sources apply first, in module order). Args: env, database_name, database_id." },
+    "devvars": { "file": ".dev.vars.example", "description": "Local secrets for .dev.vars, with a comment each." },
+    "test.env": { "file": "test/env.d.ts", "description": "Test-only Env members (migration lists read by vitest.config.ts)." },
+    "test.migrate": { "file": "test/migrate.ts", "description": "applyD1Migrations calls for platform sources, before the app's own." },
+    "vitest.bindings": { "file": "vitest.config.ts", "description": "Miniflare bindings for tests (migration lists, test-only secrets)." },
+    "playwright.imports": { "file": "playwright.config.ts", "description": "Imports for the Playwright config (values the setup commands, vars and servers use)." },
+    "playwright.setup": { "file": "playwright.config.ts", "description": "Shell commands (strings, comma-terminated) run after migrations, before wrangler dev (e.g. seeding)." },
+    "playwright.vars": { "file": "playwright.config.ts", "description": "`--var NAME:value` strings (comma-terminated) for the e2e wrangler dev." },
+    "playwright.servers": { "file": "playwright.config.ts", "description": "Extra webServer entries (comma-terminated objects), started after the main one (the SPA is built). PORT, BASE_URL and STATE are in scope; take ports after PORT." },
+    "web.routes.imports": { "file": "web/src/routes.tsx", "description": "Imports for page components." },
+    "web.routes": { "file": "web/src/routes.tsx", "description": "AppRoute entries (path, title message key, nav, bare, render). Order = nav order." },
+    "web.layout.imports": { "file": "web/src/layout.tsx", "description": "Imports for the header slot." },
+    "web.header": { "file": "web/src/layout.tsx", "description": "JSX at the end of the header (e.g. an account menu); receives `path` and `navigate`." },
+    "web.messages": { "file": "web/src/messages.ts", "description": "Message keys and English strings for the module's own screens." },
+    "web.styles": { "file": "web/src/styles.css", "description": "@import lines for UI packages' stylesheets." },
+    "readme.modules": { "file": "README.md", "description": "One section per module: what it adds and how to use it." },
+    "readme.provisioning": { "file": "README.md", "description": "Extra provisioning steps (secrets to set, services to bind), inside step 3 of the provisioning list: indent the snippet 3 spaces." }
+  }
+}

package/template/test/env.d.ts

@@ -0,0 +1,11 @@
+import type { D1Migration } from "cloudflare:test";
+
+declare global {
+  namespace Cloudflare {
+    interface Env {
+      /** Test-only: migration files read in Node by vitest.config.ts. */
+      // inbis:wire test.env
+      APP_MIGRATIONS: D1Migration[];
+    }
+  }
+}

package/template/test/migrate.ts

@@ -0,0 +1,11 @@
+import { applyD1Migrations } from "cloudflare:test";
+import { env } from "cloudflare:workers";
+
+/**
+ * Applies every migration source in the same order as `pnpm db:migrate`
+ * (wrangler.jsonc declaration order): platform sources first, the app's own last.
+ */
+export async function migrate(): Promise<void> {
+  // inbis:wire test.migrate
+  await applyD1Migrations(env.DB, env.APP_MIGRATIONS, "d1_migrations");
+}

package/template/test/migrations.test.ts

@@ -0,0 +1,22 @@
+import { env } from "cloudflare:workers";
+import { describe, expect, it } from "vitest";
+import { migrate } from "./migrate.js";
+
+// The app's own migrations (migrations/): 0001 first, then any the app or a module adds.
+const appMigrations = () => env.APP_MIGRATIONS.map((migration) => migration.name);
+
+describe("D1 migrations", () => {
+  it("apply in order and record the app's history in d1_migrations", async () => {
+    await migrate();
+    const { results } = await env.DB.prepare("SELECT name FROM d1_migrations ORDER BY id").all<{ name: string }>();
+    expect(results[0]?.name).toBe("0001_app_initial.sql");
+    expect(results.map((row) => row.name)).toEqual(appMigrations());
+  });
+
+  it("are idempotent", async () => {
+    await migrate();
+    await migrate();
+    const count = await env.DB.prepare("SELECT count(*) AS n FROM d1_migrations").first<number>("n");
+    expect(count).toBe(appMigrations().length);
+  });
+});

package/template/test/worker.test.ts

@@ -0,0 +1,65 @@
+import { exports } from "cloudflare:workers";
+import { describe, expect, it } from "vitest";
+import { migrate } from "./migrate.js";
+
+const ORIGIN = "https://app.example.test";
+const TRUSTED = "http://localhost:5173"; // TRUSTED_ORIGINS in wrangler.jsonc
+
+function call(path: string, init?: RequestInit) {
+  return exports.default.fetch(new Request(`${ORIGIN}${path}`, init));
+}
+
+interface ErrorBody {
+  error: { code: string; message: string; requestId: string; details?: unknown };
+}
+
+describe("the app Worker over HTTP", () => {
+  it("GET /health reports liveness", async () => {
+    const response = await call("/health");
+    expect(response.status).toBe(200);
+    expect(await response.json()).toEqual({ status: "ok" });
+    expect(response.headers.get("x-request-id")).toBeTruthy();
+  });
+
+  it("GET /health/ready checks the D1 database", async () => {
+    await migrate();
+    const response = await call("/health/ready");
+    expect(response.status).toBe(200);
+    expect(await response.json()).toEqual({ status: "ok", checks: { database: "ok" } });
+  });
+
+  it("GET /openapi.json documents health and the /v1 routes", async () => {
+    const response = await call("/openapi.json");
+    const doc = await response.json<{ openapi: string; info: { title: string }; paths: object }>();
+    expect(response.status).toBe(200);
+    expect(doc.openapi).toBe("3.1.0");
+    expect(doc.info.title).toBe("React Hono App");
+    expect(Object.keys(doc.paths)).toEqual(expect.arrayContaining(["/health", "/health/ready", "/v1/hello"]));
+  });
+
+  it("GET /v1/hello greets by name", async () => {
+    const response = await call("/v1/hello?name=Ada");
+    expect(response.status).toBe(200);
+    expect(await response.json()).toEqual({ message: "Hello, Ada" });
+  });
+
+  it("rejects invalid input with 422 VALIDATION_FAILED", async () => {
+    const response = await call("/v1/hello?name=");
+    const body = await response.json<ErrorBody>();
+    expect(response.status).toBe(422);
+    expect(body.error.code).toBe("VALIDATION_FAILED");
+  });
+
+  it("renders unknown API routes as 404 NOT_FOUND", async () => {
+    const response = await call("/v1/does-not-exist");
+    expect(response.status).toBe(404);
+    expect((await response.json<ErrorBody>()).error.code).toBe("NOT_FOUND");
+  });
+
+  it("allows credentialed CORS for trusted origins only", async () => {
+    const trusted = await call("/health", { headers: { origin: TRUSTED } });
+    expect(trusted.headers.get("access-control-allow-origin")).toBe(TRUSTED);
+    const untrusted = await call("/health", { headers: { origin: "https://evil.example" } });
+    expect(untrusted.headers.get("access-control-allow-origin")).toBeNull();
+  });
+});

package/template/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "@awsmbiz/inbis-tsconfig/workers.json",
+  "compilerOptions": {
+    "types": ["@cloudflare/workers-types", "@cloudflare/vitest-plugin/types"]
+  },
+  "include": ["src", "test", "*.ts"]
+}

package/template/vitest.config.ts

@@ -0,0 +1,24 @@
+import { cloudflareTest, readD1Migrations } from "@cloudflare/vitest-plugin";
+import { defineConfig } from "vitest/config";
+
+// Runs the Worker exactly as `wrangler dev` would (same wrangler.jsonc, bindings and
+// compatibility flags); tests call it over HTTP. Migration files are read here, in Node,
+// and handed to tests, which apply them (test/migrate.ts).
+export default defineConfig(async () => ({
+  plugins: [
+    cloudflareTest({
+      wrangler: { configPath: "./wrangler.jsonc" },
+      miniflare: {
+        bindings: {
+          // inbis:wire vitest.bindings
+          APP_MIGRATIONS: await readD1Migrations("./migrations"),
+        },
+      },
+    }),
+  ],
+  test: {
+    // e2e/ holds the Playwright suite (`pnpm test:e2e`).
+    include: ["test/**/*.test.ts"],
+    testTimeout: 30_000,
+  },
+}));

package/template/web/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>React Hono App</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/template/web/src/app.tsx

@@ -0,0 +1,44 @@
+import { useEffect } from "react";
+import { Layout } from "./layout.js";
+import { t } from "./messages.js";
+import { Link, useLocation, type Navigate } from "./navigation.js";
+import { useRouteFocus } from "./route-focus.js";
+import { matchRoute } from "./routes.js";
+
+function NotFound({ navigate }: { navigate: Navigate }) {
+  return (
+    <div className="flex flex-col gap-2">
+      <h1 className="text-2xl font-semibold tracking-tight">{t("notFound.title")}</h1>
+      <p className="text-muted-foreground">{t("notFound.description")}</p>
+      <p>
+        <Link href="/" navigate={navigate} className="font-medium text-primary underline underline-offset-4">
+          {t("notFound.home")}
+        </Link>
+      </p>
+    </div>
+  );
+}
+
+export function App() {
+  const { path, search, navigate } = useLocation();
+  const route = matchRoute(path);
+  useRouteFocus(path);
+  useEffect(() => {
+    document.title = `${t(route?.title ?? "notFound.title")} · ${t("app.name")}`;
+  }, [route]);
+
+  if (route === undefined) {
+    return (
+      <Layout path={path} navigate={navigate}>
+        <NotFound navigate={navigate} />
+      </Layout>
+    );
+  }
+  const page = route.render({ path, search, navigate });
+  if (route.bare === true) return page;
+  return (
+    <Layout path={path} navigate={navigate}>
+      {page}
+    </Layout>
+  );
+}

package/template/web/src/home.tsx

@@ -0,0 +1,51 @@
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@awsmbiz/inbis-ui";
+import { useEffect, useState } from "react";
+import { t } from "./messages.js";
+
+type ApiState = "checking" | "ready" | "unavailable";
+
+/** Asks `GET /health/ready` whether the Worker and its dependencies are ready. */
+function useApiState(): ApiState {
+  const [state, setState] = useState<ApiState>("checking");
+  useEffect(() => {
+    let active = true;
+    fetch("/health/ready")
+      .then((response) => {
+        if (active) setState(response.ok ? "ready" : "unavailable");
+      })
+      .catch(() => {
+        if (active) setState("unavailable");
+      });
+    return () => {
+      active = false;
+    };
+  }, []);
+  return state;
+}
+
+const STATUS = { checking: "home.apiChecking", ready: "home.apiReady", unavailable: "home.apiUnavailable" } as const;
+
+export function Home() {
+  const api = useApiState();
+  return (
+    <div className="flex flex-col gap-6">
+      <div className="flex flex-col gap-2">
+        <h1 className="text-2xl font-semibold tracking-tight">{t("home.heading")}</h1>
+        <p className="text-muted-foreground">{t("home.intro")}</p>
+      </div>
+      <Card>
+        <CardHeader>
+          <CardTitle>
+            <h2>{t("home.apiStatus")}</h2>
+          </CardTitle>
+          <CardDescription role="status">{t(STATUS[api])}</CardDescription>
+        </CardHeader>
+        <CardContent>
+          <a className="text-sm font-medium text-primary underline underline-offset-4" href="/openapi.json">
+            {t("home.apiDocs")}
+          </a>
+        </CardContent>
+      </Card>
+    </div>
+  );
+}

package/template/web/src/layout.tsx

@@ -0,0 +1,48 @@
+import type { ReactNode } from "react";
+import { t } from "./messages.js";
+import { Link, type Navigate } from "./navigation.js";
+import { routes } from "./routes.js";
+// inbis:wire web.layout.imports
+
+/** The app shell: skip link, header with the main navigation, and the page in <main>. */
+export function Layout({ path, navigate, children }: { path: string; navigate: Navigate; children: ReactNode }) {
+  return (
+    <div className="flex min-h-svh flex-col bg-background text-foreground">
+      <a
+        href="#main"
+        className="sr-only focus:not-sr-only focus:absolute focus:top-2 focus:left-2 focus:z-50 focus:rounded-md focus:bg-background focus:px-3 focus:py-2 focus:ring-2 focus:ring-ring"
+      >
+        {t("app.skipToContent")}
+      </a>
+      <header className="border-b">
+        <div className="mx-auto flex max-w-4xl flex-wrap items-center gap-x-6 gap-y-2 px-4 py-3">
+          <Link href="/" navigate={navigate} className="font-semibold">
+            {t("app.name")}
+          </Link>
+          <nav aria-label={t("app.navLabel")} className="flex-1">
+            <ul className="flex flex-wrap gap-4 text-sm">
+              {routes
+                .filter((route) => route.nav === true)
+                .map((route) => (
+                  <li key={route.path}>
+                    <Link
+                      href={route.path}
+                      navigate={navigate}
+                      aria-current={route.path === path ? "page" : undefined}
+                      className="text-muted-foreground underline-offset-4 hover:text-foreground hover:underline aria-[current=page]:font-medium aria-[current=page]:text-foreground"
+                    >
+                      {t(route.title)}
+                    </Link>
+                  </li>
+                ))}
+            </ul>
+          </nav>
+          {/* inbis:wire web.header */}
+        </div>
+      </header>
+      <main id="main" className="mx-auto w-full max-w-4xl flex-1 px-4 py-8">
+        {children}
+      </main>
+    </div>
+  );
+}

package/template/web/src/main.tsx

@@ -0,0 +1,16 @@
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import { App } from "./app.js";
+import "./styles.css";
+import { followSystemTheme } from "./system-theme.js";
+
+followSystemTheme();
+
+const root = document.getElementById("root");
+if (root === null) throw new Error("Missing #root element.");
+
+createRoot(root).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+);

package/template/web/src/messages.ts

@@ -0,0 +1,38 @@
+/**
+ * Every user-facing string of the app's own screens, by message key. Platform UI
+ * packages bring their own. English only for now; keys keep a later translation a
+ * data change.
+ */
+export const messages = {
+  "app.name": "React Hono App",
+  "app.skipToContent": "Skip to content",
+  "app.navLabel": "Main",
+  "common.loading": "Loading…",
+
+  "home.title": "Home",
+  "home.heading": "Welcome to React Hono App",
+  "home.intro": "Your Hono API and React app run on one Cloudflare Worker. Edit web/src/home.tsx to change this page.",
+  "home.apiStatus": "API status",
+  "home.apiChecking": "Checking the API…",
+  "home.apiReady": "The API and database are ready.",
+  "home.apiUnavailable": "The API is not ready. Check the Worker logs.",
+  "home.apiDocs": "API description (OpenAPI)",
+
+  "notFound.title": "Page not found",
+  "notFound.description": "There is no page at this address.",
+  "notFound.home": "Go to the home page",
+
+  // inbis:wire web.messages
+} as const;
+
+export type MessageKey = keyof typeof messages;
+
+/** Whether `key` names a message: for keys built from data. */
+export function isMessageKey(key: string): key is MessageKey {
+  return Object.hasOwn(messages, key);
+}
+
+/** Looks up a message and fills `{name}` placeholders. */
+export function t(key: MessageKey, values: Record<string, string> = {}): string {
+  return messages[key].replace(/\{(\w+)\}/g, (match, name: string) => values[name] ?? match);
+}

package/template/web/src/navigation.tsx

@@ -0,0 +1,34 @@
+import { useCallback, useEffect, useState, type AnchorHTMLAttributes, type MouseEvent } from "react";
+
+export type Navigate = (path: string, options?: { replace?: boolean }) => void;
+
+/** The current path and query string, and a function to move to another path (History API). */
+export function useLocation(): { path: string; search: string; navigate: Navigate } {
+  const [location, setLocation] = useState({ path: window.location.pathname, search: window.location.search });
+  useEffect(() => {
+    const onPop = () => {
+      setLocation({ path: window.location.pathname, search: window.location.search });
+    };
+    window.addEventListener("popstate", onPop);
+    return () => {
+      window.removeEventListener("popstate", onPop);
+    };
+  }, []);
+  const navigate = useCallback<Navigate>((next, options = {}) => {
+    if (options.replace === true) window.history.replaceState(null, "", next);
+    else window.history.pushState(null, "", next);
+    setLocation({ path: window.location.pathname, search: window.location.search });
+  }, []);
+  return { ...location, navigate };
+}
+
+/** A link that navigates inside the app (modified clicks still open a new tab). */
+export function Link({ href, navigate, onClick, ...props }: AnchorHTMLAttributes<HTMLAnchorElement> & { href: string; navigate: Navigate }) {
+  const follow = (event: MouseEvent<HTMLAnchorElement>) => {
+    onClick?.(event);
+    if (event.defaultPrevented || event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
+    event.preventDefault();
+    navigate(href);
+  };
+  return <a href={href} onClick={follow} {...props} />;
+}

package/template/web/src/route-focus.ts

@@ -0,0 +1,49 @@
+import { useEffect, useRef } from "react";
+
+// After a client-side route change the link that was followed is usually gone and focus
+// falls back to <body>: keyboard users would start over from the top and screen readers
+// would not announce the new page. So focus moves to the new page's <h1> (WCAG 2.4.3).
+// Pages may render asynchronously, so this watches the document for a short while and
+// focuses the heading once it is there. Focus a page gave itself (an autofocused field)
+// is left alone, and so is everything once the user acts.
+
+const WATCH_MS = 10_000;
+
+function focusIsLost(): boolean {
+  const active = document.activeElement;
+  return active === null || active === document.body || !active.isConnected;
+}
+
+function focusHeading(): void {
+  const heading = document.querySelector("main h1") ?? document.querySelector("h1");
+  if (!(heading instanceof HTMLElement) || heading.closest("[hidden]") !== null) return;
+  if (!heading.hasAttribute("tabindex")) heading.setAttribute("tabindex", "-1");
+  heading.focus();
+}
+
+export function useRouteFocus(path: string): void {
+  const previous = useRef(path);
+
+  useEffect(() => {
+    const from = previous.current;
+    previous.current = path;
+    if (from === path) return;
+
+    const check = () => {
+      if (focusIsLost()) focusHeading();
+    };
+    const observer = new MutationObserver(check);
+    const stop = () => {
+      observer.disconnect();
+      clearTimeout(timer);
+      window.removeEventListener("keydown", stop, true);
+      window.removeEventListener("pointerdown", stop, true);
+    };
+    const timer = setTimeout(stop, WATCH_MS);
+    observer.observe(document.body, { childList: true, subtree: true });
+    window.addEventListener("keydown", stop, true);
+    window.addEventListener("pointerdown", stop, true);
+    check();
+    return stop;
+  }, [path]);
+}

package/template/web/src/routes.tsx

@@ -0,0 +1,38 @@
+import type { ReactNode } from "react";
+import { Home } from "./home.js";
+import type { MessageKey } from "./messages.js";
+import type { Navigate } from "./navigation.js";
+// inbis:wire web.routes.imports
+
+export interface RouteContext {
+  path: string;
+  search: string;
+  navigate: Navigate;
+}
+
+export interface AppRoute {
+  /** An exact path, or a prefix when it ends in `/*` (`/admin/*` matches `/admin` and below). */
+  path: string;
+  /** The page title (document title), also the label of its navigation link. */
+  title: MessageKey;
+  /** Listed in the main navigation. */
+  nav?: boolean;
+  /** Rendered without the app layout (a screen with its own shell, e.g. full-page sign-in or an admin area). */
+  bare?: boolean;
+  render: (context: RouteContext) => ReactNode;
+}
+
+/** The app's pages, in navigation order. The first route that matches the path wins. */
+export const routes: AppRoute[] = [
+  { path: "/", title: "home.title", nav: true, render: () => <Home /> },
+  // inbis:wire web.routes
+];
+
+/** The route for `path`, if any. */
+export function matchRoute(path: string): AppRoute | undefined {
+  return routes.find((route) =>
+    route.path.endsWith("/*")
+      ? path === route.path.slice(0, -2) || path.startsWith(route.path.slice(0, -1))
+      : path === route.path,
+  );
+}