clean-architecture-frontend-template/src/presentation/routes/app-router.tsx

import {
  createContext,
  type ReactNode,
  Suspense,
  useContext,
  useEffect,
  useMemo,
  useRef,
  useState,
} from "react";
import {
  createBrowserRouter,
  RouterProvider,
  type RouteObject,
  useLocation,
  useNavigate,
  useParams,
  useSearchParams,
} from "react-router-dom";

import {
  getRoute,
  ROUTE_REGISTRY,
} from "../../features/installed-feature-contracts.js";
import type { RouteDefinition } from "../../contracts/routes.js";
import {
  FeatureBoundary,
  RouteBoundary,
} from "../boundaries/render-error-boundary.jsx";
import { ChunkRecoveryBoundary } from "../boundaries/chunk-recovery-boundary.js";
import { Button, PageHeader } from "../design-system/index.js";
import { LocaleProvider, useLocale } from "../i18n/index.js";
import { AppShell } from "../layouts/app-shell.jsx";
import { useApplication } from "../providers/application-provider.js";
import { SessionProvider, useSession } from "../providers/session-provider.jsx";
import { ThemeProvider } from "../providers/theme-provider.jsx";
import {
  createRedirectLoopGuard,
  decideRouteAccess,
} from "./navigation-policy.js";
import {
  buildRouteUrl,
  parseRouteInput,
  type ParsedRouteInput,
  type RouteId,
} from "./route-codecs.js";
import { ROUTE_RUNTIME } from "../../features/installed-feature-runtimes.js";

const RouteInputContext = createContext<ParsedRouteInput | null>(null);

export function useRouteInput(): ParsedRouteInput {
  const input = useContext(RouteInputContext);
  if (!input) throw new Error("Registered route input is required");
  return input;
}

function RouteLoadingSurface({ definition }: { definition: RouteDefinition }) {
  const { message, resolve } = useLocale();
  const title = resolve(`route.${definition.routeId}.title`);
  return (
    <section
      className="ui-page route-loading"
      aria-live="polite"
      aria-busy="true"
      data-surface={definition.loadingSurface}
    >
      <div className="ui-skeleton" aria-hidden="true" />
      <p>{message("route.loading")}</p>
      <span className="visually-hidden">
        {message("route.loadingNamed", { title })}
      </span>
    </section>
  );
}

function RouteFailureSurface({
  definition,
}: {
  definition?: RouteDefinition;
}) {
  const { message } = useLocale();
  return (
    <section
      className="ui-page"
      data-surface={definition?.errorSurface ?? "route-boundary"}
    >
      <PageHeader
        title={message("route.failure.title")}
        description={message("route.failure.description")}
      />
    </section>
  );
}

function InvalidRouteSurface({ code }: { code: string }) {
  const { message } = useLocale();
  return (
    <section className="ui-page" data-surface="invalid-route">
      <PageHeader
        title={message("route.invalid.title")}
        description={message("route.invalid.description")}
      />
      <p data-route-error={code}>{message("route.invalid.action")}</p>
    </section>
  );
}

function RouteLifecycle({
  definition,
  buildId,
}: {
  definition: RouteDefinition;
  buildId: string;
}) {
  const location = useLocation();
  const { message, resolve } = useLocale();
  const { diagnostics } = useApplication();
  useEffect(() => {
    document.title = message("route.documentTitle", {
      title: resolve(`route.${definition.routeId}.title`),
      appName: message("common.appName"),
    });
    const main = document.getElementById("main-content");
    main?.focus({ preventScroll: true });
    try {
      if (!navigator.userAgent.toLowerCase().includes("jsdom")) {
        window.scrollTo({ top: 0, left: 0, behavior: "auto" });
      }
    } catch {
      // Non-browser test hosts may not implement scrolling.
    }
    diagnostics.reportRouteChanged({
      routeId: definition.routeId,
      buildId,
    });
  }, [
    buildId,
    definition,
    diagnostics,
    location.key,
    location.pathname,
    message,
    resolve,
  ]);
  return null;
}

function CanonicalRouteRedirect({
  input,
}: {
  input: ParsedRouteInput;
}) {
  const location = useLocation();
  const navigate = useNavigate();
  const guard = useRef(createRedirectLoopGuard(3));
  useEffect(() => {
    if (input.routeId === "NOT_FOUND") return;
    const source = `${location.pathname}${location.search}`;
    const target = buildRouteUrl(input.routeId, {
      params: input.params,
      search: input.search,
    });
    if (source !== target && guard.current.allow(source, target)) {
      void navigate(target, { replace: true });
    }
  }, [input, location.pathname, location.search, navigate]);
  return null;
}

function ProtectedRoute({
  routeId,
  children,
}: {
  routeId: RouteId;
  children: ReactNode;
}) {
  const location = useLocation();
  const { sessionState, beginSignIn, recover } = useSession();
  const { message } = useLocale();
  const [pending, setPending] = useState(false);
  const [failed, setFailed] = useState(false);
  const decision = decideRouteAccess(routeId, sessionState);

  async function continueSession() {
    setPending(true);
    setFailed(false);
    try {
      if (decision.action === "wait-for-session") {
        await recover();
      } else {
        await beginSignIn(
          `${location.pathname}${location.search}${location.hash}`,
        );
      }
    } catch {
      setFailed(true);
    } finally {
      setPending(false);
    }
  }

  if (decision.allowed) return children;
  if (sessionState === "integration-failed") {
    return (
      <section className="ui-page" data-surface="auth-integration-required">
        <PageHeader
          title={message("route.auth.integration.title")}
          description={message("route.auth.integration.description")}
        />
      </section>
    );
  }
  const recovering = decision.action === "wait-for-session";
  return (
    <section className="ui-page" data-surface="authentication-required">
      <PageHeader
        title={
          recovering
            ? message("route.auth.recovering.title")
            : message("route.auth.required.title")
        }
        description={
          recovering
            ? message("route.auth.recovering.description")
            : message("route.auth.required.description")
        }
      />
      <Button
        disabled={pending}
        onClick={() => void continueSession()}
      >
        {pending
          ? message("common.processing")
          : recovering
            ? message("action.recoverSession")
            : message("action.signIn")}
      </Button>
      {failed ? (
        <p className="ui-terminal-error" role="alert">
          {message("shell.session.actionFailed")}
        </p>
      ) : null}
    </section>
  );
}

function RegisteredRoute({
  routeId,
  buildId,
}: {
  routeId: RouteId;
  buildId: string;
}) {
  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);
  if (!parsed.success) return <InvalidRouteSurface code={parsed.code} />;

  const content = (
    <RouteInputContext.Provider value={parsed.data}>
      <CanonicalRouteRedirect input={parsed.data} />
      <RouteLifecycle definition={definition} buildId={buildId} />
      <Suspense fallback={<RouteLoadingSurface definition={definition} />}>
        <ChunkRecoveryBoundary
          chunkId={definition.chunkId}
          recover={recovery.recoverChunk}
        >
          <runtime.Component />
        </ChunkRecoveryBoundary>
      </Suspense>
    </RouteInputContext.Provider>
  );
  const protectedContent =
    definition.access === "public" ? (
      content
    ) : (
      <ProtectedRoute routeId={routeId}>{content}</ProtectedRoute>
    );
  const boundaryProps = {
    routeId,
    buildId,
    resetKey: `${location.pathname}${location.search}`,
    onRenderFailure: diagnostics.reportRenderFailure,
    fallback: <RouteFailureSurface definition={definition} />,
    children: protectedContent,
  };
  return definition.errorSurface === "feature-boundary" ? (
    <FeatureBoundary {...boundaryProps} />
  ) : (
    <RouteBoundary {...boundaryProps} />
  );
}

function createRegisteredRoutes(buildId: string): RouteObject[] {
  const children = Object.values(ROUTE_REGISTRY).map((definition) => {
    const routeId = definition.routeId as RouteId;
    if (definition.path === "/") {
      return {
        id: routeId,
        index: true,
        element: <RegisteredRoute routeId={routeId} buildId={buildId} />,
      };
    }
    return {
      id: routeId,
      path:
        definition.path === "*"
          ? "*"
          : definition.path.replace(/^\//, ""),
      element: <RegisteredRoute routeId={routeId} buildId={buildId} />,
    };
  });
  return [
    {
      id: "APP_SHELL",
      path: "/",
      element: <AppShell />,
      errorElement: <RouteFailureSurface />,
      children,
    },
  ];
}

export function AppRouter({
  basename = "/",
  buildId = "local-build",
}: Readonly<{ basename?: string; buildId?: string }>) {
  const router = useMemo(
    () =>
      createBrowserRouter(createRegisteredRoutes(buildId), {
        basename,
      }),
    [basename, buildId],
  );
  return (
    <LocaleProvider>
      <ThemeProvider>
        <SessionProvider>
          <RouterProvider router={router} />
        </SessionProvider>
      </ThemeProvider>
    </LocaleProvider>
  );
}