feat: add grouped TechLog route contracts

2026-08-15 20:30:32 +09:00
parent 27dda3e0e3
commit adb8613cb9
15 changed files with 887 additions and 67 deletions
@@ -1,4 +1,5 @@
 import {
+  type ComponentType,
  type ReactNode,
  Suspense,
  useEffect,
@@ -8,6 +9,7 @@ import {
 } from "react";
 import {
  createBrowserRouter,
+  Outlet,
  RouterProvider,
  type RouteObject,
  useLocation,
@@ -16,11 +18,11 @@ import {
  useSearchParams,
 } from "react-router-dom";

-import {
-  getRoute,
-  ROUTE_REGISTRY,
-} from "../../features/installed-feature-contracts.ts";
-import type { RouteDefinition } from "../../contracts/routes.ts";
+import { ROUTE_REGISTRY } from "../../features/installed-feature-contracts.ts";
+import type {
+  RouteDefinition,
+  RouteLayoutGroup,
+} from "../../contracts/routes.ts";
 import {
  FeatureBoundary,
  RouteBoundary,
@@ -34,14 +36,18 @@ import { SessionProvider, useSession } from "../providers/session-provider.tsx";
 import { ThemeProvider } from "../providers/theme-provider.tsx";
 import {
  createRedirectLoopGuard,
-  decideRouteAccess,
+  decideRouteAccessForDefinition,
 } from "./navigation-policy.ts";
 import {
-  buildRouteUrl,
-  parseRouteInput,
+  buildRouteUrlFromDefinition,
+  parseRouteInputFromContract,
+  type RouteCodecRegistry,
  type RouteId,
 } from "./route-codecs.ts";
-import { ROUTE_RUNTIME } from "../../features/installed-feature-runtimes.tsx";
+import {
+  ROUTE_CODECS,
+  ROUTE_RUNTIME,
+} from "../../features/installed-feature-runtimes.tsx";
 import type { ParsedRouteInput } from "./route-contract.ts";
 import { RouteInputProvider } from "./route-input.tsx";

@@ -138,33 +144,41 @@ function RouteLifecycle({

 function CanonicalRouteRedirect({
  input,
+  definition,
+  codecs,
 }: {
  input: ParsedRouteInput;
+  definition: RouteDefinition;
+  codecs: RouteCodecRegistry;
 }) {
  const location = useLocation();
  const navigate = useNavigate();
  const guard = useRef(createRedirectLoopGuard(3));
  useEffect(() => {
-    if (input.routeId === "NOT_FOUND") return;
+    if (definition.path.includes("*")) return;
    const source = `${location.pathname}${location.search}`;
-    const target = buildRouteUrl(input.routeId, {
-      params: input.params,
-      search: input.search,
-    });
+    const target = buildRouteUrlFromDefinition(
+      definition,
+      codecs,
+      {
+        params: input.params,
+        search: input.search,
+      },
+    );
    if (source === target) {
      guard.current.reset();
    } else if (guard.current.allow(source, target)) {
      void navigate(target, { replace: true });
    }
-  }, [input, location.pathname, location.search, navigate]);
+  }, [codecs, definition, input, location.pathname, location.search, navigate]);
  return null;
 }

 function ProtectedRoute({
-  routeId,
+  definition,
  children,
 }: {
-  routeId: RouteId;
+  definition: RouteDefinition;
  children: ReactNode;
 }) {
  const location = useLocation();
@@ -172,7 +186,7 @@ function ProtectedRoute({
  const { message } = useLocale();
  const [pending, setPending] = useState(false);
  const [failed, setFailed] = useState(false);
-  const decision = decideRouteAccess(routeId, sessionState);
+  const decision = decideRouteAccessForDefinition(definition, sessionState);

  async function continueSession() {
    setPending(true);
@@ -240,29 +254,45 @@ function ProtectedRoute({
 function RegisteredRoute({
  routeId,
  buildId,
+  definition,
+  runtime,
+  codecs,
 }: {
  routeId: RouteId;
  buildId: string;
+  definition: RouteDefinition;
+  runtime: GroupedRouteRuntimeDefinition;
+  codecs: RouteCodecRegistry;
 }) {
-  const definition = getRoute(routeId);
-  const runtime = ROUTE_RUNTIME[routeId];
  const params = useParams();
  const [search] = useSearchParams();
  const location = useLocation();
  const { diagnostics, recovery } = useApplication();
-  const parsed = parseRouteInput(routeId, params, search);
+  const parsed = parseRouteInputFromContract(
+    routeId,
+    definition,
+    codecs,
+    params,
+    search,
+  );
  if (!parsed.success) return <InvalidRouteSurface code={parsed.code} />;
+  const routeInput = parsed.data as ParsedRouteInput;
+  const RuntimeComponent = runtime.Component;

  const content = (
-    <RouteInputProvider input={parsed.data}>
-      <CanonicalRouteRedirect input={parsed.data} />
+    <RouteInputProvider input={routeInput}>
+      <CanonicalRouteRedirect
+        input={routeInput}
+        definition={definition}
+        codecs={codecs}
+      />
      <RouteLifecycle definition={definition} buildId={buildId} />
      <Suspense fallback={<RouteLoadingSurface definition={definition} />}>
        <ChunkRecoveryBoundary
          chunkId={definition.chunkId}
          recover={recovery.recoverChunk}
        >
-          <runtime.Component />
+          <RuntimeComponent />
        </ChunkRecoveryBoundary>
      </Suspense>
    </RouteInputProvider>
@@ -271,7 +301,7 @@ function RegisteredRoute({
    definition.access === "public" ? (
      content
    ) : (
-      <ProtectedRoute routeId={routeId}>{content}</ProtectedRoute>
+      <ProtectedRoute definition={definition}>{content}</ProtectedRoute>
    );
  const boundaryProps = {
    routeId,
@@ -288,34 +318,82 @@ function RegisteredRoute({
  );
 }

-function createRegisteredRoutes(buildId: string): RouteObject[] {
-  const children = Object.values(ROUTE_REGISTRY).map((definition) => {
+type GroupedRouteRuntimeDefinition = Readonly<{
+  moduleId: string;
+  Component: ComponentType;
+}>;
+
+type GroupedRouteRegistry = Readonly<Record<string, RouteDefinition>>;
+type GroupedRouteRuntime = Readonly<
+  Record<string, GroupedRouteRuntimeDefinition>
+>;
+type GroupedRouteLayouts = Readonly<Record<RouteLayoutGroup, ReactNode>>;
+
+export function createGroupedRouteObjects(
+  registry: GroupedRouteRegistry,
+  runtime: GroupedRouteRuntime,
+  layouts: GroupedRouteLayouts,
+  buildId: string,
+  codecs: RouteCodecRegistry = ROUTE_CODECS,
+): RouteObject[] {
+  for (const routeId of Object.keys(runtime)) {
+    if (!registry[routeId]) {
+      throw new TypeError(`Missing route definition: ${routeId}`);
+    }
+  }
+
+  const children: Record<RouteLayoutGroup, RouteObject[]> = {
+    PUBLIC: [],
+    STUDIO: [],
+  };
+  for (const definition of Object.values(registry)) {
    const routeId = definition.routeId as RouteId;
+    const routeRuntime = runtime[definition.routeId];
+    if (!routeRuntime) {
+      throw new TypeError(`Missing route runtime: ${definition.routeId}`);
+    }
+    const element = (
+      <RegisteredRoute
+        routeId={routeId}
+        buildId={buildId}
+        definition={definition}
+        runtime={routeRuntime}
+        codecs={codecs}
+      />
+    );
    if (definition.path === "/") {
-      return {
+      children[definition.layoutGroup].push({
        id: routeId,
        index: true,
-        element: <RegisteredRoute routeId={routeId} buildId={buildId} />,
-      };
+        element,
+      });
+      continue;
    }
-    return {
+    children[definition.layoutGroup].push({
      id: routeId,
      path:
        definition.path === "*"
          ? "*"
          : definition.path.replace(/^\//, ""),
-      element: <RegisteredRoute routeId={routeId} buildId={buildId} />,
-    };
-  });
-  return [
-    {
-      id: "APP_SHELL",
-      path: "/",
-      element: <AppShell />,
-      errorElement: <RouteFailureSurface />,
-      children,
-    },
-  ];
+      element,
+    });
+  }
+
+  for (const layoutGroup of ["PUBLIC", "STUDIO"] as const) {
+    children[layoutGroup].sort(
+      (left, right) =>
+        Number(Boolean(left.path?.endsWith("*"))) -
+        Number(Boolean(right.path?.endsWith("*"))),
+    );
+  }
+
+  return (["STUDIO", "PUBLIC"] as const).map((layoutGroup) => ({
+    id: `${layoutGroup}_LAYOUT`,
+    path: "/",
+    element: layouts[layoutGroup],
+    errorElement: <RouteFailureSurface />,
+    children: children[layoutGroup],
+  }));
 }

 export function AppRouter({
@@ -324,9 +402,18 @@ export function AppRouter({
 }: Readonly<{ basename?: string; buildId?: string }>) {
  const router = useMemo(
    () =>
-      createBrowserRouter(createRegisteredRoutes(buildId), {
-        basename,
-      }),
+      createBrowserRouter(
+        createGroupedRouteObjects(
+          ROUTE_REGISTRY,
+          ROUTE_RUNTIME,
+          {
+            PUBLIC: <AppShell />,
+            STUDIO: <Outlet />,
+          },
+          buildId,
+        ),
+        { basename },
+      ),
    [basename, buildId],
  );
  return (
@@ -1,4 +1,5 @@
 import type { SessionState } from "../../application/ports/in/application-api.ts";
+import type { RouteDefinition } from "../../contracts/routes.ts";
 import { getRoute } from "../../features/installed-feature-contracts.ts";

 export type RouteAccessDecision =
@@ -12,8 +13,14 @@ export function decideRouteAccess(
  routeId: string,
  sessionState: SessionState,
 ): RouteAccessDecision {
-  const route = getRoute(routeId);
-  if (route.access === "public") return { allowed: true, action: "none" };
+  return decideRouteAccessForDefinition(getRoute(routeId), sessionState);
+}
+
+export function decideRouteAccessForDefinition(
+  definition: Pick<RouteDefinition, "access">,
+  sessionState: SessionState,
+): RouteAccessDecision {
+  if (definition.access === "public") return { allowed: true, action: "none" };
  if (sessionState === "authenticated") {
    return { allowed: true, action: "none" };
  }
@@ -2,5 +2,5 @@ import { z } from "zod";

 export const PLATFORM_ROUTE_CODECS = {
  none: z.object({}).strict(),
-  NotFoundSplat: z.object({ "*": z.string().optional() }).strict(),
+  NotFoundSplat: z.object({ "*": z.string().min(1).optional() }).strict(),
 } as const;
@@ -1,5 +1,10 @@
-import { getRoute, ROUTE_RUNTIME_CONTRACT } from "../../features/installed-feature-contracts.ts";
+import {
+  getRoute,
+  ROUTE_RUNTIME_CONTRACT,
+} from "../../features/installed-feature-contracts.ts";
 import { ROUTE_CODECS } from "../../features/installed-feature-runtimes.tsx";
+import type { RouteDefinition } from "../../contracts/routes.ts";
+import type { RouteRuntimeDefinition } from "../../contracts/route-runtime-contract.ts";
 import type {
  ParsedRouteInput,
  RouteId,
@@ -8,8 +13,33 @@ import type {

 export type { ParsedRouteInput, RouteId, RouteInputResult };

-function codecById(codecId: string) {
-  const codec = ROUTE_CODECS[codecId as keyof typeof ROUTE_CODECS];
+type RouteCodec = Readonly<{
+  parse(value: unknown): Readonly<Record<string, unknown>>;
+  safeParse(value: unknown):
+    | Readonly<{
+        success: true;
+        data: Readonly<Record<string, unknown>>;
+      }>
+    | Readonly<{ success: false }>;
+}>;
+
+export type RouteCodecRegistry = Readonly<Record<string, RouteCodec>>;
+export type ContractRouteInputResult =
+  | Readonly<{
+      success: true;
+      data: Readonly<{
+        routeId: string;
+        params: Readonly<Record<string, unknown>>;
+        search: Readonly<Record<string, unknown>>;
+      }>;
+    }>
+  | Readonly<{
+      success: false;
+      code: "ROUTE_PARAMS_INVALID" | "ROUTE_SEARCH_INVALID";
+    }>;
+
+function codecById(codecId: string, codecs: RouteCodecRegistry = ROUTE_CODECS) {
+  const codec = codecs[codecId];
  if (!codec) throw new TypeError(`Unregistered route codec: ${codecId}`);
  return codec;
 }
@@ -19,12 +49,33 @@ export function parseRouteInput(
  rawParams: Readonly<Record<string, string | undefined>>,
  rawSearch: URLSearchParams,
 ): RouteInputResult {
-  const runtime = ROUTE_RUNTIME_CONTRACT[routeId];
-  const params = codecById(runtime.paramsCodec).safeParse(rawParams);
+  return parseRouteInputFromContract(
+    routeId,
+    getRoute(routeId),
+    ROUTE_CODECS,
+    rawParams,
+    rawSearch,
+  ) as RouteInputResult;
+}
+
+export function parseRouteInputFromContract(
+  routeId: string,
+  definition: Pick<RouteDefinition, "paramsSchema" | "searchSchema">,
+  codecs: RouteCodecRegistry,
+  rawParams: Readonly<Record<string, string | undefined>>,
+  rawSearch: URLSearchParams,
+): ContractRouteInputResult {
+  const params = codecById(
+    definition.paramsSchema ?? "none",
+    codecs,
+  ).safeParse(rawParams);
  if (!params.success) {
    return { success: false, code: "ROUTE_PARAMS_INVALID" };
  }
-  const search = codecById(runtime.searchCodec).safeParse(
+  const search = codecById(
+    definition.searchSchema ?? "none",
+    codecs,
+  ).safeParse(
    searchRecord(rawSearch),
  );
  if (!search.success) {
@@ -50,15 +101,71 @@ export function buildRouteUrl(
  }> = {},
 ): string {
  const definition = getRoute(routeId);
-  if (definition.path === "*") {
-    throw new TypeError("The not-found route cannot build a canonical URL");
-  }
  const runtime = ROUTE_RUNTIME_CONTRACT[routeId];
-  const params = codecById(runtime.paramsCodec).parse(input.params ?? {});
-  const search = codecById(runtime.searchCodec).parse(input.search ?? {});
+  return buildRouteUrlFromContract(
+    definition,
+    runtime,
+    ROUTE_CODECS,
+    input,
+  );
+}
+
+export function buildRouteUrlFromContract(
+  definition: Pick<RouteDefinition, "path">,
+  runtime: Pick<RouteRuntimeDefinition, "paramsCodec" | "searchCodec">,
+  codecs: RouteCodecRegistry,
+  input: Readonly<{
+    params?: Readonly<Record<string, unknown>>;
+    search?: Readonly<Record<string, unknown>>;
+  }> = {},
+): string {
+  return buildRouteUrlWithCodecs(
+    definition.path,
+    runtime.paramsCodec,
+    runtime.searchCodec,
+    codecs,
+    input,
+  );
+}
+
+export function buildRouteUrlFromDefinition(
+  definition: Pick<
+    RouteDefinition,
+    "path" | "paramsSchema" | "searchSchema"
+  >,
+  codecs: RouteCodecRegistry,
+  input: Readonly<{
+    params?: Readonly<Record<string, unknown>>;
+    search?: Readonly<Record<string, unknown>>;
+  }> = {},
+): string {
+  return buildRouteUrlWithCodecs(
+    definition.path,
+    definition.paramsSchema ?? "none",
+    definition.searchSchema ?? "none",
+    codecs,
+    input,
+  );
+}
+
+function buildRouteUrlWithCodecs(
+  pathTemplate: string,
+  paramsCodec: string,
+  searchCodec: string,
+  codecs: RouteCodecRegistry,
+  input: Readonly<{
+    params?: Readonly<Record<string, unknown>>;
+    search?: Readonly<Record<string, unknown>>;
+  }>,
+): string {
+  if (pathTemplate.includes("*")) {
+    throw new TypeError("A wildcard route cannot build a canonical URL");
+  }
+  const params = codecById(paramsCodec, codecs).parse(input.params ?? {});
+  const search = codecById(searchCodec, codecs).parse(input.search ?? {});
  const parsedParams: Record<string, unknown> = { ...params };
  const parsedSearch: Record<string, unknown> = { ...search };
-  let path = definition.path;
+  let path = pathTemplate;
  path = path.replace(
    /:([A-Za-z][A-Za-z0-9_]*)|\{([A-Za-z][A-Za-z0-9_]*)\}/g,
    (