diff --git a/src/presentation/pages/not-found-page.tsx b/src/presentation/pages/not-found-page.tsx
index b59836ca..c75a8a3c 100644
--- a/src/presentation/pages/not-found-page.tsx
+++ b/src/presentation/pages/not-found-page.tsx
@@ -1,22 +1,21 @@
-import { Link } from "react-router-dom";
-
import { routePath } from "../../features/installed-feature-contracts.ts";
-import { PageHeader } from "../design-system/index.ts";
+import { StatusPage } from "../design-system/index.ts";
import { useLocale } from "../i18n/index.ts";
export default function NotFoundPage() {
const { message } = useLocale();
return (
-
-
-
-
- {message("action.goHome")}
-
-
-
+
);
}
diff --git a/src/presentation/providers/session-provider.tsx b/src/presentation/providers/session-provider.tsx
index b87129e6..8fafa3d8 100644
--- a/src/presentation/providers/session-provider.tsx
+++ b/src/presentation/providers/session-provider.tsx
@@ -2,9 +2,11 @@ import {
createContext,
useContext,
useMemo,
+ useState,
useSyncExternalStore,
type ReactNode,
} from "react";
+import { useLocation } from "react-router-dom";
import type {
ApplicationApi,
@@ -53,3 +55,36 @@ export function useSession(): SessionContextValue {
}
return session;
}
+
+export type SessionAction = "sign-in" | "sign-out" | "recover";
+
+/**
+ * One session action at a time, with the pending and failed state every
+ * session button shows. Sign-in returns to the current URL, hash included.
+ */
+export function useSessionAction(): Readonly<{
+ pending: boolean;
+ failed: boolean;
+ run(action: SessionAction): void;
+}> {
+ const { pathname, search, hash } = useLocation();
+ const { beginSignIn, signOut, recover } = useSession();
+ const [pending, setPending] = useState(false);
+ const [failed, setFailed] = useState(false);
+
+ async function execute(action: SessionAction): Promise
{
+ setPending(true);
+ setFailed(false);
+ try {
+ if (action === "sign-out") await signOut();
+ else if (action === "recover") await recover();
+ else await beginSignIn(`${pathname}${search}${hash}`);
+ } catch {
+ setFailed(true);
+ } finally {
+ setPending(false);
+ }
+ }
+
+ return { pending, failed, run: (action) => void execute(action) };
+}
diff --git a/src/presentation/routes/app-router.tsx b/src/presentation/routes/app-router.tsx
index c21fa07d..f0960f8d 100644
--- a/src/presentation/routes/app-router.tsx
+++ b/src/presentation/routes/app-router.tsx
@@ -41,7 +41,7 @@ import {
} from "../boundaries/chunk-recovery-boundary.tsx";
import { ContextErrorBoundary } from "../../platform/errors/context-error-boundary.tsx";
import { FeatureErrorBoundary } from "../../platform/errors/feature-error-boundary.tsx";
-import { Button, PageHeader } from "../design-system/index.ts";
+import { LoadingSurface, StatusPage } from "../design-system/index.ts";
import { useLocale } from "../i18n/index.ts";
import { AppShell } from "../layouts/app-shell.tsx";
import {
@@ -49,7 +49,11 @@ import {
useApplicationRecovery,
useApplicationRuntime,
} from "../providers/application-provider.tsx";
-import { SessionProvider, useSession } from "../providers/session-provider.tsx";
+import {
+ SessionProvider,
+ useSession,
+ useSessionAction,
+} from "../providers/session-provider.tsx";
import {
createRedirectLoopGuard,
decideRouteAccess,
@@ -63,22 +67,24 @@ import { ROUTE_RUNTIME } from "../../features/installed-feature-runtimes.tsx";
import type { ParsedRouteInput } from "./route-contract.ts";
import { RouteInputProvider } from "./route-input.tsx";
-function RouteLoadingSurface({ definition }: { definition: RouteDefinition }) {
+/** Route-level loading: the shared LoadingSurface inside the page frame. */
+function RouteLoadingSurface({
+ definition,
+}: Readonly<{ definition?: RouteDefinition }>) {
const { message, resolve } = useLocale();
- const title = resolve(`route.${definition.routeId}.title`);
return (
-
-
- {message("route.loading")}
-
- {message("route.loadingNamed", { title })}
-
-
+
+
+
);
}
@@ -89,28 +95,30 @@ function RouteFailureSurface({
}) {
const { message } = useLocale();
return (
-
+
);
}
function InvalidRouteSurface({ code }: { code: string }) {
const { message } = useLocale();
return (
-
-
+
{message("route.invalid.action")}
-
+
);
}
@@ -122,15 +130,18 @@ function InvalidRouteSurface({ code }: { code: string }) {
function DisabledFeatureSurface({ featureId }: { featureId: string }) {
const { message } = useLocale();
return (
-
-
+
{message("route.disabledFeature.action")}
-
+
);
}
@@ -200,73 +211,57 @@ function ProtectedRoute({
routeId: RouteId;
children: ReactNode;
}) {
- const location = useLocation();
- const { sessionState, beginSignIn, recover } = useSession();
+ const { sessionState } = useSession();
const { message } = useLocale();
- const [pending, setPending] = useState(false);
- const [failed, setFailed] = useState(false);
+ const { pending, failed, run } = useSessionAction();
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 (
-
+
);
}
const recovering = decision.action === "wait-for-session";
return (
-
-
- void continueSession()}
- >
- {pending
+
+ : message("action.signIn"),
+ disabled: pending,
+ onAction: () => run(recovering ? "recover" : "sign-in"),
+ }}
+ surface="authentication-required"
+ variant="unauthenticated"
+ >
{failed ? (
{message("shell.session.actionFailed")}
) : null}
-
+
);
}
@@ -402,7 +397,6 @@ function ContextRouteGateway({
buildId,
}: Readonly<{ routeModule: ContextRouteModule; buildId: string }>) {
const location = useLocation();
- const { message } = useLocale();
const recovery = useApplicationRecovery();
const [routes, setRoutes] = useState(null);
const [failure, setFailure] = useState | null>(
@@ -451,14 +445,7 @@ function ContextRouteGateway({
);
}
- if (routes === null) {
- return (
-
-
- {message("route.loading")}
-
- );
- }
+ if (routes === null) return ;
const selectedMatch = matchRoutes([...routes], location.pathname)?.at(-1);
if (!isContextRouteHandle(selectedMatch?.route.handle)) {
diff --git a/src/presentation/templates/page-templates.tsx b/src/presentation/templates/page-templates.tsx
index 56f459d1..f9908e9e 100644
--- a/src/presentation/templates/page-templates.tsx
+++ b/src/presentation/templates/page-templates.tsx
@@ -211,6 +211,10 @@ export function StatusPage(
primaryAction?: PageActionDefinition;
secondaryAction?: PageActionDefinition;
supportReference?: string;
+ /** Names the answer for tests and telemetry, e.g. `invalid-route`. */
+ surface?: string;
+ /** Extra content under the actions, such as a failure alert. */
+ children?: ReactNode;
}>,
) {
const { message } = useLocale();
@@ -218,6 +222,7 @@ export function StatusPage(
{props.primaryAction || props.secondaryAction ? (
@@ -230,6 +235,7 @@ export function StatusPage(
}
/>
) : null}
+ {props.children}
{props.supportReference ? (
{message("template.supportReference", {
@@ -247,13 +253,15 @@ function PageActionBar(props: Readonly<{
}>) {
return (
- {props.actions.map((action) =>
+ {/* Keyed by position: a label that changes while pending must not
+ remount the button the user just pressed. */}
+ {props.actions.map((action, index) =>
action.kind === "link" ? (
{action.label}
@@ -261,7 +269,7 @@ function PageActionBar(props: Readonly<{
) : (
diff --git a/tests/component/route-status-surfaces.test.tsx b/tests/component/route-status-surfaces.test.tsx
new file mode 100644
index 00000000..0812572c
--- /dev/null
+++ b/tests/component/route-status-surfaces.test.tsx
@@ -0,0 +1,205 @@
+// @vitest-environment jsdom
+
+import { render, screen, waitFor, within } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { MemoryRouter } from "react-router-dom";
+import { describe, expect, it, vi } from "vitest";
+
+import { createAnonymousSessionAdapter } from "../../src/adapters/auth/external-session-adapter.ts";
+import type { ApplicationOutputPorts } from "../../src/application/create-application.ts";
+import HomePage from "../../src/presentation/pages/home-page.tsx";
+import PlatformOverviewPage from "../../src/presentation/examples/platform-overview-page.tsx";
+import { LocaleProvider } from "../../src/presentation/i18n/index.ts";
+import { ApplicationProvider } from "../../src/presentation/providers/application-provider.tsx";
+import { PreferenceProviders } from "../../src/presentation/providers/preference-providers.tsx";
+import { AppRouter } from "../../src/presentation/routes/app-router.tsx";
+import { createTestApplication } from "../helpers/create-test-application.ts";
+
+function deferred() {
+ let reject: (error: unknown) => void = () => {};
+ const promise = new Promise((_, fail) => {
+ reject = fail;
+ });
+ return { promise, reject };
+}
+
+function renderApp(
+ url: string,
+ overrides: Partial = {},
+ basename?: string,
+) {
+ window.history.pushState({}, "", url);
+ return render(
+
+
+
+
+ ,
+ );
+}
+
+function sessionWithSignIn(beginSignIn: (returnTo?: string) => Promise) {
+ return { ...createAnonymousSessionAdapter(), beginSignIn };
+}
+
+describe("route-level status surfaces", () => {
+ // First in the file: the home chunk has not been loaded yet, so the route
+ // suspends and shows its loading surface.
+ it("shows the busy route loading surface while a page chunk loads", async () => {
+ renderApp("/");
+
+ const copy = screen.getByText("화면을 준비하고 있습니다.");
+ expect(copy.closest('[aria-busy="true"]')).not.toBeNull();
+ expect(
+ await screen.findByRole(
+ "heading",
+ { name: "Clean Architecture Frontend", level: 1 },
+ { timeout: 5000 },
+ ),
+ ).toBeVisible();
+ });
+
+ it("keeps the auth-required surface, its pending label and its failure alert", async () => {
+ const user = userEvent.setup();
+ const pending = deferred();
+ const beginSignIn = vi.fn(() => pending.promise);
+ const { container } = renderApp("/examples/reference-resources#results", {
+ session: sessionWithSignIn(beginSignIn),
+ });
+
+ const heading = await screen.findByRole(
+ "heading",
+ { name: "세션이 필요합니다.", level: 1 },
+ { timeout: 5000 },
+ );
+ const surface = container.querySelector(
+ '[data-surface="authentication-required"]',
+ );
+ expect(surface).not.toBeNull();
+ expect(surface).toContainElement(heading);
+
+ await user.click(screen.getByRole("button", { name: "로그인 시작" }));
+ expect(beginSignIn).toHaveBeenCalledWith(
+ "/examples/reference-resources#results",
+ );
+ expect(screen.getByRole("button", { name: "처리 중…" })).toBeDisabled();
+
+ pending.reject(new Error("identity provider unavailable"));
+ expect(await screen.findByRole("alert")).toHaveTextContent(
+ "세션 작업을 완료하지 못했습니다.",
+ );
+ expect(screen.getByRole("button", { name: "로그인 시작" })).toBeEnabled();
+ });
+
+ it("returns to the current URL with its hash from the shell session action", async () => {
+ const user = userEvent.setup();
+ const pending = deferred();
+ const beginSignIn = vi.fn(() => pending.promise);
+ renderApp("/examples/ui#buttons", { session: sessionWithSignIn(beginSignIn) });
+
+ const banner = screen.getByRole("banner");
+ await user.click(
+ await within(banner).findByRole("button", { name: "로그인" }),
+ );
+ expect(beginSignIn).toHaveBeenCalledWith("/examples/ui#buttons");
+ expect(within(banner).getByRole("button", { name: "처리 중…" })).toBeDisabled();
+
+ pending.reject(new Error("identity provider unavailable"));
+ expect(await within(banner).findByRole("alert")).toHaveTextContent(
+ "세션 작업을 완료하지 못했습니다.",
+ );
+ });
+
+ it("returns to the current URL with its hash from the auth example page", async () => {
+ const user = userEvent.setup();
+ const beginSignIn = vi.fn(async () => {});
+ renderApp("/examples/auth#session", {
+ session: sessionWithSignIn(beginSignIn),
+ });
+
+ await user.click(
+ await screen.findByRole(
+ "button",
+ { name: "로그인 시작" },
+ { timeout: 5000 },
+ ),
+ );
+ expect(beginSignIn).toHaveBeenCalledWith("/examples/auth#session");
+ });
+
+ it("answers an unknown address with a home link that keeps the basename", async () => {
+ renderApp("/app/missing", {}, "/app");
+
+ const heading = await screen.findByRole(
+ "heading",
+ { name: "페이지를 찾을 수 없습니다.", level: 1 },
+ { timeout: 5000 },
+ );
+ const page = heading.closest("section");
+ expect(page).not.toBeNull();
+ expect(
+ within(page!).getByRole("link", { name: "홈으로 이동" }),
+ ).toHaveAttribute("href", "/app");
+ });
+});
+
+describe("temporary release loaders", () => {
+ function failingReleaseApplication() {
+ return createTestApplication({
+ releaseInfo: {
+ getCurrent: async () => {
+ throw new Error("manifest unavailable");
+ },
+ refresh: async () => {
+ throw new Error("manifest unavailable");
+ },
+ },
+ });
+ }
+
+ it("stops the home page release summary from loading forever", async () => {
+ window.history.pushState({}, "", "/");
+ render(
+
+
+
+
+ ,
+ );
+ await waitFor(() =>
+ expect(
+ screen.getByText("런타임 정보를 확인하지 못했습니다."),
+ ).toBeVisible(),
+ );
+ expect(
+ screen.queryByText("검증된 런타임 정보를 확인하고 있습니다."),
+ ).not.toBeInTheDocument();
+ });
+
+ it("stops the platform overview release metrics from loading forever", async () => {
+ render(
+
+
+
+
+ ,
+ );
+ await waitFor(() =>
+ expect(
+ screen.getByText("런타임 정보를 확인하지 못했습니다."),
+ ).toBeVisible(),
+ );
+ expect(
+ screen.queryByText("런타임 정보를 확인하고 있습니다."),
+ ).not.toBeInTheDocument();
+ });
+});
+
+/** HomePage renders router links, so it needs a router but not the app one. */
+function AppRouterlessHome() {
+ return (
+
+
+
+ );
+}