diff --git a/config/contracts/registry-change-evidence.json b/config/contracts/registry-change-evidence.json
index 5aa12b9c..3c90d861 100644
--- a/config/contracts/registry-change-evidence.json
+++ b/config/contracts/registry-change-evidence.json
@@ -112,6 +112,14 @@
"compatibilityWindow": "No runtime document or wire format changes: BUILD_ID was already local-build whenever VITE_BUILD_ID was unset.",
"rollback": "Restore defaultValue null on VITE_BUILD_ID in src/contracts/env.ts and drop the public-target check in scripts/generate-runtime-config.ts.",
"owner": "frontend-platform"
+ },
+ {
+ "changeId": "FE-REG-ROUTE:REFERENCE_RESOURCE_DETAIL:path:field-changed",
+ "versionBump": "The reference detail route moves from /examples/reference-resources/:resourceId to /examples/reference-resources/items/:resourceId (maturity review 08-13), so a server id equal to the static segments new or status opens its detail instead of the form or status screen.",
+ "migration": "The only in-app link (reference-resource-page.tsx) builds the new path from the contract route. The reference feature is a sample; downstream features that copied it keep their own paths.",
+ "compatibilityWindow": "None for bookmarked sample detail URLs: an old /examples/reference-resources/ URL no longer matches the detail route; new and status keep opening the form and status screens.",
+ "rollback": "Restore the previous path in src/features/reference-feature/contracts/reference-feature-contract.ts and the link in reference-resource-page.tsx, then drop this entry.",
+ "owner": "frontend-platform"
}
]
}
diff --git a/docs/accessibility/manual-checklist.md b/docs/accessibility/manual-checklist.md
index 7e556367..77b804f7 100644
--- a/docs/accessibility/manual-checklist.md
+++ b/docs/accessibility/manual-checklist.md
@@ -63,3 +63,16 @@ The reviewer must verify:
not be marked not-applicable on that route. Passing automated evidence means
only that tested pages had no critical or serious axe findings under the
recorded Chromium, Firefox, and WebKit runs.
+
+What the automated run scans:
+
+- Every registered route, after the route's own `h1` is on screen, so the scan
+ never lands on the app shell's loading surface
+ (`tests/e2e/accessibility.spec.ts`). A public route's `h1` must equal its
+ catalog title.
+- Protected routes after the demo sign-in, never the sign-in prompt. Their API
+ calls answer an empty list there.
+- The reference sample's list in its success, empty and error states, its
+ detail, its form with submit errors and its status page, each after that
+ state is on screen (`tests/e2e/reference-form.spec.ts`, removed with the
+ sample).
diff --git a/docs/architecture/decisions/VD-04-native-form-facade.md b/docs/architecture/decisions/VD-04-native-form-facade.md
index 958581c6..a27fa86e 100644
--- a/docs/architecture/decisions/VD-04-native-form-facade.md
+++ b/docs/architecture/decisions/VD-04-native-form-facade.md
@@ -30,7 +30,8 @@ field orchestration까지 플랫폼 기본값으로 고정하게 된다.
layout과 state slot만 소유하며 application/query/HTTP를 import하지 않는다.
8. (2026-09-25, 08-01) 입력 오류가 아닌 저장 실패는 ErrorSummary에 넣지 않는다.
`useAppForm`은 `action: "reauth"`를 `reauth-required`, `FORBIDDEN`을 `forbidden`,
- `action: "retry"`를 `retry-later`로 구분하고 그 실패를 `failure`로 낸다. 화면은
+ `action: "retry"`를 `retry-later`로, 나머지 입력 외 실패를 `unavailable`로 구분하고
+ 그 실패를 `failure`로 낸다(F-10). 화면은
`FormFailureStatus`로 문구와 행동(로그인·이동·다시 시도)을 보여 준다. 재로그인은
입력을 지운다는 안내를 버튼 앞에 둔다(`src/presentation/forms/use-app-form.ts`,
`form-components.tsx`).
diff --git a/docs/architecture/decisions/VD-06-intl-typed-message-catalog.md b/docs/architecture/decisions/VD-06-intl-typed-message-catalog.md
index 0204c94c..2b994271 100644
--- a/docs/architecture/decisions/VD-06-intl-typed-message-catalog.md
+++ b/docs/architecture/decisions/VD-06-intl-typed-message-catalog.md
@@ -66,9 +66,15 @@ route/form/failure 의미 값
## 검증
-- `check:i18n`은 catalog key와 placeholder parity, common UI의 한국어 literal,
- backend message JSX 렌더링과 raw HTML 사용을 검사한다.
-- `check:i18n:fixture`는 세 금지 사례를 실제로 거절해야 성공으로 인정된다.
+- `check:i18n`은 catalog key와 placeholder parity, 화면 코드의 한국어 literal,
+ backend message JSX 렌더링과 raw HTML 사용을 검사한다. 검사 범위는 공통 UI
+ 디렉터리, `src/presentation/pages`, 모든 `src/features/*/presentation`이다.
+ 컴포넌트 갤러리 `src/presentation/examples`는 일부러 뺐다
+ (`scripts/check-i18n.ts`의 `commonDirectories`, `featurePresentationDirectories`).
+- `check:i18n:fixture`는 같은 탐색 규칙을 `tests/fixtures/i18n/forbidden` 트리에
+ 돌린다. fixture 파일 하나라도 거절되지 않으면 종료 코드 2로 실패한다.
+- `tests/unit/i18n-contract.test.ts`는 `ERROR_REGISTRY`의 모든 `userMessageKey`가
+ ko-KR·en-US catalog에 있는지 확인한다.
- type negative fixture는 unknown key와 잘못된 parameter shape를 거절한다.
- unit test는 fallback, alias, pseudo 확장, direction과 timezone/number/relative/
list/plural/select의 결정성을 검증한다.
diff --git a/docs/architecture/routing-pages-and-patterns.md b/docs/architecture/routing-pages-and-patterns.md
index 98d214c4..89515500 100644
--- a/docs/architecture/routing-pages-and-patterns.md
+++ b/docs/architecture/routing-pages-and-patterns.md
@@ -280,6 +280,18 @@ chunk recovery 순서:
4. 안전한 support surface와 trace/build ID를 표시한다.
5. recovery 결과를 redacted diagnostics에 기록한다.
+지원 참조는 사용자가 문의할 때 말하는 값이고, 진단 이벤트에서 같은 값을 찾을
+수 있다.
+
+- 라우트 렌더 실패: `buildId:incidentId`. 같은 incident ID가 `ui.render.failed`
+ 진단의 `correlation_id`에 남는다(`render-error-boundary.tsx`의
+ `newIncidentId`, `create-application.ts`의 `reportRenderFailure`). 화면에는
+ "한 번 새로고침" 버튼이 있다(`app-router.tsx`의 `RouteFailureSurface`).
+- 복구하지 못한 청크 실패: 같은 형식이다. `ChunkRecoveryBoundary`의
+ `onUnrecovered`가 같은 ID로 `ui.render.failed`를 기록한다.
+- 조회 실패: `AppFailure.requestId`. HTTP 진단의 `correlation_id`와 같은 값이다
+ (`async-surface.tsx`의 `TerminalErrorSurface`).
+
custom fallback을 넘겨 retry/reset 기능을 잃지 않게 한다. boundary는
`location.key` 또는 route ID가 바뀌면 적절히 reset된다.
@@ -289,9 +301,15 @@ custom fallback을 넘겨 retry/reset 기능을 잃지 않게 한다. boundary
- mouse 사용자가 불필요한 focus ring을 보지 않게 할 수는 있지만 keyboard focus
indication을 전역으로 제거하지 않음
- modal/drawer가 닫히면 opener에 focus 복원
-- backward/forward navigation은 저장한 scroll 복원
+- backward/forward navigation은 저장한 scroll 복원. 복원은 브라우저가 하고,
+ `RouteLifecycle`은 POP이 아닐 때만 top으로 보낸다(`app-router.tsx`).
+ `PageHeader`의 heading focus는 `preventScroll`이라 복원된 위치를 옮기지 않는다
- 새 primary route는 top으로 이동
-- hash target은 fixed header offset과 focus 가능 여부를 처리
+- hash target은 fixed header offset과 focus 가능 여부를 처리. 페이지가 그려진 뒤
+ `PageHeader`가 대상으로 스크롤하고, 대상이 focus 가능하면 대상에, 아니면
+ heading에 focus한다(`page-header.tsx`). header 높이는 `html`의
+ `scroll-padding-top`으로 뺀다(`shell.css`). 브라우저 검증은
+ `tests/e2e/scroll-restoration.spec.ts`
- screen reader용 route title/live announcement는 중복 발표를 피함
### 6.4 취소와 dirty form
diff --git a/docs/architecture/typescript-state-and-data-flow.md b/docs/architecture/typescript-state-and-data-flow.md
index 3c60cddf..9e77d838 100644
--- a/docs/architecture/typescript-state-and-data-flow.md
+++ b/docs/architecture/typescript-state-and-data-flow.md
@@ -599,7 +599,7 @@ Form 또는 TanStack Form adapter를 평가한다.
- `Description`
- `FieldError`
- `ErrorSummary`
-- `FormFailureStatus` (재로그인·권한 없음·잠시 후 재시도 저장 실패)
+- `FormFailureStatus` (재로그인·권한 없음·잠시 후 재시도·그 밖의 저장 불가 실패)
- `useAppForm`
- `mapValidationFailureToFields`
- `useDirtyNavigationGuard`
@@ -623,7 +623,7 @@ backend message와 알 수 없는 path는 field copy로 사용하지 않는다.
3. submitting 중 중복 제출 방지
4. 422 응답의 알려진 field만 표시하고 나머지는 form-level failure로 처리
5. 409 conflict는 validation error로 위장하지 않음
-5a. 401·403·429 같은 입력 외 실패는 ErrorSummary가 아니라 `FormFailureStatus`로 표시
+5a. 401·403·429와 404 같은 입력 외 실패는 ErrorSummary가 아니라 `FormFailureStatus`로 표시(`use-app-form.ts`의 `STATUS_RESULTS`)
6. 취소와 route 이탈 시 dirty policy 적용
7. form value → application command mapper를 별도 함수로 둠
8. browser autofill, IME composition, paste, password manager를 방해하지 않음
diff --git a/docs/styling/design-system-platform.md b/docs/styling/design-system-platform.md
index 48f16cfd..0f25b452 100644
--- a/docs/styling/design-system-platform.md
+++ b/docs/styling/design-system-platform.md
@@ -306,8 +306,8 @@ Pattern은 여러 primitive를 조합해 반복되는 사용자 문제를 해결
| Pattern | 필수 내용 |
| --- | --- |
-| `AsyncSurface` | loading, success, empty, terminal error, stale, refresh |
-| `AccessSurface` | auth required, forbidden, not found |
+| `AsyncSurface` | loading, success, empty, terminal error, stale, refresh. 조회 실패가 `AUTH_REQUIRED`·`FORBIDDEN`·`NOT_FOUND`이면 `AccessSurface`와 같은 화면(`state-surfaces.tsx`)을 그린다(`async-surface.tsx`의 `ACCESS_SURFACES`) |
+| `AccessSurface` | auth required, forbidden, not found. 조회 실패와 갤러리가 이 한 벌을 쓴다 |
| `Form` | submit, error summary, first-invalid focus, pending |
| `ConfirmationDialog` | destructive action 설명과 명시적 확인 |
| `ToastRegion` | queue, announcement, dismiss, focus policy |
diff --git a/scripts/check-i18n.ts b/scripts/check-i18n.ts
index ae62611e..e1a58c88 100644
--- a/scripts/check-i18n.ts
+++ b/scripts/check-i18n.ts
@@ -52,20 +52,45 @@ if (!fixtureMode) {
}
}
+// 08-04. Screen code under these directories must take its words from the
+// catalog. `src/presentation/examples` is the component gallery and stays out
+// of scope on purpose. Fixture mode runs the same discovery on a fixture tree.
+const sourceRoot = fixtureMode ? "tests/fixtures/i18n/forbidden" : ".";
const commonDirectories = [
"src/presentation/boundaries",
"src/presentation/components",
"src/presentation/design-system",
"src/presentation/forms",
"src/presentation/layouts",
+ "src/presentation/pages",
"src/presentation/routes",
"src/presentation/templates",
];
-const sources = fixtureMode
- ? await listSourceFiles("tests/fixtures/i18n/forbidden")
- : (
- await Promise.all(commonDirectories.map((directory) => listSourceFiles(directory)))
- ).flat();
+
+async function featurePresentationDirectories(root: string): Promise {
+ const features = path.join(root, "src/features");
+ const entries = await readdir(features, { withFileTypes: true }).catch(
+ () => [],
+ );
+ return entries
+ .filter((entry) => entry.isDirectory())
+ .map((entry) => path.join("src/features", entry.name, "presentation"));
+}
+
+async function existingSourceFiles(directory: string): Promise {
+ return listSourceFiles(directory).catch((error: NodeJS.ErrnoException) => {
+ if (error.code === "ENOENT") return [];
+ throw error;
+ });
+}
+
+const sourceDirectories = [
+ ...commonDirectories,
+ ...(await featurePresentationDirectories(sourceRoot)),
+].map((directory) => path.join(sourceRoot, directory));
+const sources = (
+ await Promise.all(sourceDirectories.map(existingSourceFiles))
+).flat();
for (const file of sources) {
const source = await readFile(file, "utf8");
@@ -98,6 +123,19 @@ await writeValidatedJsonArtifact({
value: report,
});
+// Every fixture file must be rejected on its own; one rejected file must not
+// hide a directory the discovery above stopped reaching.
+const fixtureFiles = fixtureMode ? await listSourceFiles(sourceRoot) : [];
+const unrejectedFixtures = fixtureFiles.filter(
+ (file) => !failures.some((failure) => failure.endsWith(file)),
+);
+if (fixtureMode && (fixtureFiles.length === 0 || unrejectedFixtures.length > 0)) {
+ process.stderr.write(
+ `I18n fixture was not rejected:\n${unrejectedFixtures.join("\n") || "(no fixture files found)"}\n`,
+ );
+ process.exit(2);
+}
+
if (failures.length > 0) {
process.stderr.write(`I18n contract failed:\n${failures.join("\n")}\n`);
process.exit(1);
diff --git a/src/application/create-application.ts b/src/application/create-application.ts
index fccb38da..5625e5de 100644
--- a/src/application/create-application.ts
+++ b/src/application/create-application.ts
@@ -62,6 +62,11 @@ export function createApplication(
route_id: report.routeId,
build_id: report.buildId,
component_boundary: report.boundaryName,
+ // Incident-scoped like a request id: diagnostics only, never
+ // telemetry.
+ ...(report.incidentId === undefined
+ ? {}
+ : { correlation_id: report.incidentId }),
},
});
} catch {
diff --git a/src/application/ports/in/application-api.ts b/src/application/ports/in/application-api.ts
index f4f7f2bb..fbf7564c 100644
--- a/src/application/ports/in/application-api.ts
+++ b/src/application/ports/in/application-api.ts
@@ -24,6 +24,8 @@ export type RenderFailureReport = Readonly<{
routeId: string;
buildId: string;
boundaryName: "route" | "feature";
+ /** 08-07. The id the failure page shows as its support reference. */
+ incidentId?: string;
}>;
export type RouteChangedReport = Readonly<{
diff --git a/src/features/reference-feature/contracts/reference-feature-contract.ts b/src/features/reference-feature/contracts/reference-feature-contract.ts
index 3bac006e..fb06ea59 100644
--- a/src/features/reference-feature/contracts/reference-feature-contract.ts
+++ b/src/features/reference-feature/contracts/reference-feature-contract.ts
@@ -88,7 +88,8 @@ export const REFERENCE_FEATURE_CONTRACT = Object.freeze({
}),
REFERENCE_RESOURCE_DETAIL: Object.freeze({
routeId: "REFERENCE_RESOURCE_DETAIL",
- path: "/examples/reference-resources/:resourceId",
+ // 08-13. `items/` keeps an id such as `new` or `status` off the static routes.
+ path: "/examples/reference-resources/items/:resourceId",
paramsSchema: "ReferenceResourceParams",
searchSchema: null,
access: "session-required",
diff --git a/src/features/reference-feature/contracts/reference-message-catalog.ts b/src/features/reference-feature/contracts/reference-message-catalog.ts
index a7880c98..e080dcb1 100644
--- a/src/features/reference-feature/contracts/reference-message-catalog.ts
+++ b/src/features/reference-feature/contracts/reference-message-catalog.ts
@@ -8,6 +8,41 @@ export const REFERENCE_MESSAGE_CATALOGS = Object.freeze({
"route.REFERENCE_RESOURCE_FORM.title": "Create reference resource",
"route.REFERENCE_RESOURCE_STATUS.navigation": "Reference status",
"route.REFERENCE_RESOURCE_STATUS.title": "Reference resource status",
+ "reference.list.eyebrow": "제거 가능한 수직 슬라이스",
+ "reference.list.description":
+ "URL codec, application input, HTTP/schema/mapper와 query 상태를 한 경로로 검증합니다.",
+ "reference.list.create": "새 항목 만들기",
+ "reference.list.refresh": "새로고침",
+ "reference.list.resultCount": "총 {count}개 항목",
+ "reference.form.back": "목록으로 돌아가기",
+ "reference.form.title": "Reference resource 만들기",
+ "reference.form.description":
+ "presentation schema, command mapper, 422/conflict와 dirty navigation 정책을 실행합니다.",
+ "reference.form.name": "새 항목 이름",
+ "reference.form.nameDescription":
+ "앞뒤 공백은 command mapper 전에 제거됩니다.",
+ "reference.form.note": "설명",
+ "reference.form.noteDescription":
+ "선택 입력이며 비어 있으면 command에 포함되지 않습니다.",
+ "reference.form.cancel": "취소",
+ "reference.form.save": "저장",
+ "reference.form.saving": "저장 중…",
+ "reference.form.reset": "초기화",
+ "reference.form.reloadList": "목록을 새로 불러와 확인",
+ "reference.form.saved": "저장했습니다.",
+ "reference.form.conflict": "충돌을 해결한 뒤 다시 제출할 수 있습니다.",
+ "reference.form.privacy":
+ "form value는 URL, storage, telemetry에 저장되지 않고 submit 시에만 application command로 변환됩니다.",
+ "reference.detail.description":
+ "route param과 detail query의 reset 경계를 확인합니다.",
+ "reference.detail.summaryPending": "요약 정보를 준비하고 있습니다.",
+ "reference.detail.sectionSlot":
+ "이 영역에는 제품별 상세 section을 조립할 수 있습니다.",
+ "reference.detail.aside": "상세 페이지의 관련 정보 slot입니다.",
+ "reference.status.title": "잠시 사용할 수 없습니다.",
+ "reference.status.description":
+ "도메인 데이터나 raw 오류를 노출하지 않는 중립적인 상태 페이지 예시입니다.",
+ "reference.status.back": "목록으로 이동",
}),
"en-US": Object.freeze({
"route.REFERENCE_RESOURCE_LIST.navigation": "Reference feature",
@@ -18,5 +53,40 @@ export const REFERENCE_MESSAGE_CATALOGS = Object.freeze({
"route.REFERENCE_RESOURCE_FORM.title": "Create reference resource",
"route.REFERENCE_RESOURCE_STATUS.navigation": "Reference status",
"route.REFERENCE_RESOURCE_STATUS.title": "Reference resource status",
+ "reference.list.eyebrow": "Removable vertical slice",
+ "reference.list.description":
+ "Checks the URL codec, application input, HTTP/schema/mapper and query state along one path.",
+ "reference.list.create": "Create item",
+ "reference.list.refresh": "Refresh",
+ "reference.list.resultCount": "Total items: {count}",
+ "reference.form.back": "Back to the list",
+ "reference.form.title": "Create a reference resource",
+ "reference.form.description":
+ "Runs the presentation schema, command mapper, 422/conflict and dirty navigation policies.",
+ "reference.form.name": "New item name",
+ "reference.form.nameDescription":
+ "Leading and trailing spaces are removed before the command mapper.",
+ "reference.form.note": "Description",
+ "reference.form.noteDescription":
+ "Optional. An empty value is left out of the command.",
+ "reference.form.cancel": "Cancel",
+ "reference.form.save": "Save",
+ "reference.form.saving": "Saving…",
+ "reference.form.reset": "Reset",
+ "reference.form.reloadList": "Reload the list to check",
+ "reference.form.saved": "Saved.",
+ "reference.form.conflict": "Resolve the conflict, then submit again.",
+ "reference.form.privacy":
+ "Form values are never written to the URL, storage or telemetry; they become an application command only on submit.",
+ "reference.detail.description":
+ "Checks the reset boundary between the route parameter and the detail query.",
+ "reference.detail.summaryPending": "Preparing the summary.",
+ "reference.detail.sectionSlot":
+ "Product-specific detail sections can be assembled here.",
+ "reference.detail.aside": "Related information slot of the detail page.",
+ "reference.status.title": "Temporarily unavailable.",
+ "reference.status.description":
+ "An example of a neutral status page that exposes no domain data or raw errors.",
+ "reference.status.back": "Go to the list",
}),
} as const);
diff --git a/src/features/reference-feature/presentation/reference-resource-detail-page.tsx b/src/features/reference-feature/presentation/reference-resource-detail-page.tsx
index 008bd259..447a091a 100644
--- a/src/features/reference-feature/presentation/reference-resource-detail-page.tsx
+++ b/src/features/reference-feature/presentation/reference-resource-detail-page.tsx
@@ -26,7 +26,7 @@ export default function ReferenceResourceDetailPage() {
heading={{
eyebrow: "DetailPage",
title: resource?.title ?? "Reference detail",
- description: "route param과 detail query의 reset 경계를 확인합니다.",
+ description: message("reference.detail.description"),
}}
metadata={
resource ? (
@@ -41,7 +41,7 @@ export default function ReferenceResourceDetailPage() {
) : (
-
+ ) : null}
);
}
@@ -121,6 +136,23 @@ export function AsyncSurface({
if (state.base === "initial-loading") return ;
if (state.base === "empty") return ;
if (state.base === "terminal-error" && state.failure) {
+ const AccessState = ACCESS_SURFACES[state.failure.kind];
+ if (AccessState) {
+ // 08-11. Access failures use the same surfaces as the design system's
+ // AccessSurface, so a query and the gallery show one copy.
+ return (
+
+ );
+ }
return (
);
}
@@ -177,3 +210,16 @@ export function AsyncSurface({
);
}
+
+const ACCESS_SURFACES: Readonly<
+ Partial<
+ Record<
+ AppFailure["kind"],
+ (props: Readonly<{ onAction?: () => void }>) => ReactNode
+ >
+ >
+> = Object.freeze({
+ AUTH_REQUIRED: ({ onAction }) => ,
+ FORBIDDEN: ({ onAction }) => ,
+ NOT_FOUND: ({ onAction }) => ,
+});
diff --git a/src/presentation/components/page-header.tsx b/src/presentation/components/page-header.tsx
index 1eb3addd..870d02de 100644
--- a/src/presentation/components/page-header.tsx
+++ b/src/presentation/components/page-header.tsx
@@ -6,6 +6,15 @@ export type PageHeaderProps = Readonly<{
eyebrow?: string;
}>;
+function hashTarget(): HTMLElement | null {
+ try {
+ const id = decodeURIComponent(window.location.hash.slice(1));
+ return id ? document.getElementById(id) : null;
+ } catch {
+ return null;
+ }
+}
+
export function PageHeader({
title,
description,
@@ -21,9 +30,15 @@ export function PageHeader({
activeElement === document.body ||
activeElement === document.documentElement ||
activeElement === main;
- if (routeOwnsFocus) {
- headingRef.current?.focus();
- }
+ if (!routeOwnsFocus) return;
+ // 08-08. A hash names a target in this page, which exists only once the
+ // page has rendered. Focus never scrolls: back navigation keeps the
+ // position the browser restored.
+ const target = hashTarget();
+ target?.scrollIntoView?.();
+ (target && target.tabIndex >= 0 ? target : headingRef.current)?.focus({
+ preventScroll: true,
+ });
}, [title]);
return (
diff --git a/src/presentation/components/state-surfaces.tsx b/src/presentation/components/state-surfaces.tsx
index d48c546a..c7400d5d 100644
--- a/src/presentation/components/state-surfaces.tsx
+++ b/src/presentation/components/state-surfaces.tsx
@@ -23,7 +23,9 @@ function StateSurface({
{eyebrow}
{title}
{description}
- {actionLabel ? : null}
+ {actionLabel && onAction ? (
+
+ ) : null}
);
}
diff --git a/src/presentation/design-system/primitives/navigation.tsx b/src/presentation/design-system/primitives/navigation.tsx
index d19b6074..1fac75dc 100644
--- a/src/presentation/design-system/primitives/navigation.tsx
+++ b/src/presentation/design-system/primitives/navigation.tsx
@@ -267,7 +267,17 @@ function PageLinks({
key={candidate}
onClick={(event) => {
// The owner decides how a page change is applied; the href is for
- // open-in-new-tab and copy-link.
+ // open-in-new-tab and copy-link, so a modified or non-primary
+ // click stays with the browser (08-12).
+ if (
+ event.button !== 0 ||
+ event.metaKey ||
+ event.altKey ||
+ event.ctrlKey ||
+ event.shiftKey
+ ) {
+ return;
+ }
event.preventDefault();
onChange(candidate);
}}
diff --git a/src/presentation/forms/form-components.tsx b/src/presentation/forms/form-components.tsx
index f87d771f..4b91fc2f 100644
--- a/src/presentation/forms/form-components.tsx
+++ b/src/presentation/forms/form-components.tsx
@@ -82,7 +82,7 @@ export function ErrorSummary(props: Readonly<{
/**
* 08-01. A save that failed for a reason other than the input (sign-in,
- * permission, retry later) is announced here with its own action, not in
+ * permission, retry later, unavailable) is announced here with its own action, not in
* ErrorSummary. Pass `useAppForm().failure`.
*/
export function FormFailureStatus(props: Readonly<{
diff --git a/src/presentation/forms/use-app-form.ts b/src/presentation/forms/use-app-form.ts
index 80556329..e39d3877 100644
--- a/src/presentation/forms/use-app-form.ts
+++ b/src/presentation/forms/use-app-form.ts
@@ -43,7 +43,7 @@ export function useAppForm<
Command,
Output,
>(options: AppFormOptions) {
- const { message } = useLocale();
+ const { resolve } = useLocale();
const {
schema,
defaultValues,
@@ -59,10 +59,28 @@ export function useAppForm<
const [touched, setTouched] = useState>>(
() => new Set(),
);
- const [fieldErrors, setFieldErrors] = useState>(
+ // 08-10. Errors are held as message keys and translated on render, so a
+ // locale change re-translates the ones already on screen.
+ const [fieldErrorKeys, setFieldErrors] = useState>(
() => ({} as FieldErrors),
);
- const [formErrors, setFormErrors] = useState([]);
+ const [formErrorKeys, setFormErrors] = useState([]);
+ const fieldErrors = useMemo(
+ () =>
+ Object.freeze(
+ Object.fromEntries(
+ Object.entries(fieldErrorKeys).map(([name, key]) => [
+ name,
+ resolve(String(key)),
+ ]),
+ ),
+ ) as FieldErrors,
+ [fieldErrorKeys, resolve],
+ );
+ const formErrors = useMemo(
+ () => formErrorKeys.map((key) => resolve(key)),
+ [formErrorKeys, resolve],
+ );
const [pending, setPending] = useState(false);
const [result, setResult] = useState("idle");
const [statusFailure, setStatusFailure] = useState(null);
@@ -188,7 +206,7 @@ export function useAppForm<
const mapped = mapValidationFailureToFields(
outcome.error,
allowedServerFields,
- message,
+ messageKey,
);
setFieldErrors(mapped.fieldErrors);
setFormErrors(mapped.formErrors);
@@ -208,9 +226,7 @@ export function useAppForm<
settleSuccessfulValues(submittedValues);
} else if (outcome.error.kind === "CONFLICT") {
unknownSubmissionRef.current = null;
- setFormErrors([
- message("form.conflict"),
- ]);
+ setFormErrors(["form.conflict"]);
setResult("conflict");
} else if (
outcome.error.kind === "FORBIDDEN" ||
@@ -223,12 +239,14 @@ export function useAppForm<
outcome.error.kind === "FORBIDDEN" ? "forbidden" : "retry-later",
);
} else {
+ // F-10. Not an input error either: shown by FormFailureStatus.
unknownSubmissionRef.current = null;
- setFormErrors([message("form.unavailable")]);
+ setFormErrors([]);
+ setStatusFailure(outcome.error);
setResult("unavailable");
}
},
- [allowedServerFields, focusFirstError, message, settleSuccessfulValues],
+ [allowedServerFields, focusFirstError, settleSuccessfulValues],
);
const validateAndSubmit = useCallback(
@@ -241,14 +259,14 @@ export function useAppForm<
const errors = issuesToFieldErrors(
parsed.error.issues,
allowedServerFields,
- message,
+ messageKey,
);
setFieldErrors(errors);
setFormErrors(
parsed.error.issues.some(
(issue) => !allowedServerFields.includes(issue.path[0] as FieldName),
)
- ? [message("form.validation.configuration")]
+ ? ["form.validation.configuration"]
: [],
);
setTouched(new Set(allowedServerFields));
@@ -272,7 +290,6 @@ export function useAppForm<
applyOutcome,
focusFirstError,
mapToCommand,
- message,
schema,
submit,
values,
@@ -335,7 +352,10 @@ export function useAppForm<
formErrors,
pending,
result,
- /** The save failure behind `reauth-required`, `forbidden` or `retry-later`. */
+ /**
+ * The save failure behind `reauth-required`, `forbidden`, `retry-later`
+ * or `unavailable`.
+ */
failure: STATUS_RESULTS.has(result) ? statusFailure : null,
field,
fieldId,
@@ -349,10 +369,14 @@ export function useAppForm<
});
}
+/** Keeps the key: the form translates at render time. */
+const messageKey = (key: ParameterlessMessageKey): string => key;
+
const STATUS_RESULTS: ReadonlySet = new Set([
"reauth-required",
"forbidden",
"retry-later",
+ "unavailable",
]);
function issuesToFieldErrors(
diff --git a/src/presentation/i18n/catalog.ts b/src/presentation/i18n/catalog.ts
index f5276223..03a0f202 100644
--- a/src/presentation/i18n/catalog.ts
+++ b/src/presentation/i18n/catalog.ts
@@ -99,6 +99,28 @@ const PLATFORM_KO_MESSAGES = {
"chunk.failure.title": "화면 자산을 복구하지 못했습니다.",
"chunk.failure.description":
"문제가 계속되면 배포 상태와 지원 참조 정보를 확인해 주세요.",
+ "home.eyebrow": "프로젝트 시작점",
+ "home.description":
+ "도메인을 추가하기 전에 실행 구조와 범용 사용자 경험을 확인할 수 있는 중립적인 스켈레톤입니다.",
+ "home.readiness": "구현 준비 상태",
+ "home.readiness.contract.title": "실행 계약",
+ "home.readiness.contract.description":
+ "런타임 설정, 릴리스 정합성, 오류 경계가 마운트 전에 검증됩니다.",
+ "home.readiness.adapters.title": "교체 가능한 연동",
+ "home.readiness.adapters.description":
+ "인증, HTTP, 캐시, 저장소, 텔레메트리가 포트 뒤에 분리되어 있습니다.",
+ "home.readiness.accessibility.title": "접근 가능한 화면",
+ "home.readiness.accessibility.description":
+ "키보드 탐색, 포커스 이동, 반응형 앱 셸의 기본 동작이 준비되어 있습니다.",
+ "home.runtime.checking": "검증된 런타임 정보를 확인하고 있습니다.",
+ "home.runtime.failed": "런타임 정보를 확인하지 못했습니다.",
+ "home.runtime.summary": "빌드 {buildId} · 릴리스 {releaseId}",
+ "home.starter.title": "준비된 화면 살펴보기",
+ "home.starter.description":
+ "설치된 라우트와 계약, 런타임 능력은 플랫폼 구성 화면에서, 공통 구성요소와 비동기 화면 상태는 예제 라우트에서 확인하세요.",
+ "home.starter.platform": "플랫폼 구성 보기",
+ "home.starter.ui": "UI 구성요소 보기",
+ "home.starter.states": "화면 상태 보기",
"page.notFound.title": "페이지를 찾을 수 없습니다.",
"page.notFound.description":
"주소를 확인하거나 준비된 시작 화면으로 돌아가세요.",
@@ -125,7 +147,6 @@ const PLATFORM_KO_MESSAGES = {
"form.validation.configuration": "입력 구성을 다시 확인해 주세요.",
"form.conflict":
"다른 변경과 충돌했습니다. 입력은 유지되었으니 최신 상태를 확인해 주세요.",
- "form.unavailable": "저장하지 못했습니다. 잠시 후 다시 시도해 주세요.",
"form.reauthLosesInput":
"다시 로그인하면 이 화면에 입력한 내용은 사라집니다. 필요하면 먼저 복사해 두세요.",
"form.remaining": "{count}자 남음",
@@ -146,6 +167,30 @@ const PLATFORM_KO_MESSAGES = {
"error.asset_mismatch": "화면 자산 구성이 현재 릴리스와 일치하지 않습니다.",
"error.render_failure": "화면을 표시하지 못했습니다.",
"error.unknown_failure": "예상하지 못한 문제가 발생했습니다.",
+ "error.request_aborted": "요청이 취소되었습니다.",
+ "error.content_type_mismatch": "서버 응답 형식을 해석할 수 없습니다.",
+ "error.malformed_json": "서버 응답을 읽을 수 없습니다.",
+ "error.response_body_limit": "서버 응답이 허용된 크기를 넘었습니다.",
+ "error.envelope_mismatch": "서버 응답 구조가 예상과 다릅니다.",
+ "error.schema_mismatch": "서버 응답 데이터가 현재 화면과 맞지 않습니다.",
+ "error.mapping_contract_violation":
+ "서버 응답을 화면 데이터로 바꾸지 못했습니다.",
+ "error.result_limit_exceeded": "결과가 너무 많아 표시할 수 없습니다.",
+ "error.scope_generation_changed": "세션이 바뀌어 이전 요청을 중단했습니다.",
+ "error.identity_intern_limit_exceeded":
+ "처리할 항목이 너무 많습니다. 잠시 후 다시 시도해 주세요.",
+ "error.duplicate_in_flight": "같은 요청을 이미 처리하고 있습니다.",
+ "error.pagination_contract_violation": "페이지 정보를 확인할 수 없습니다.",
+ "error.conflict": "다른 변경과 충돌했습니다.",
+ "error.validation_rejected": "서버가 입력값을 받아들이지 않았습니다.",
+ "error.unknown_client_failure": "요청을 처리할 수 없습니다.",
+ "error.boot_config_failure": "실행 설정을 불러오지 못했습니다.",
+ "error.release_manifest_failure": "릴리스 정보를 불러오지 못했습니다.",
+ "error.deploy_mismatch": "배포 구성이 현재 화면과 일치하지 않습니다.",
+ "error.storage_unavailable": "브라우저 저장소를 사용할 수 없습니다.",
+ "error.storage_quota_exceeded": "브라우저 저장 공간이 부족합니다.",
+ "error.telemetry_failure": "진단 정보를 보내지 못했습니다.",
+ "error.query_cache_failure": "저장된 조회 결과를 사용할 수 없습니다.",
...BOOT_MESSAGES["ko-KR"],
} as const;
@@ -253,6 +298,28 @@ const PLATFORM_EN_MESSAGES = {
"chunk.failure.title": "The page assets could not be recovered.",
"chunk.failure.description":
"If the problem continues, check deployment status and support information.",
+ "home.eyebrow": "Project starting point",
+ "home.description":
+ "A neutral skeleton for checking the runtime structure and common user experience before adding a domain.",
+ "home.readiness": "Implementation readiness",
+ "home.readiness.contract.title": "Runtime contract",
+ "home.readiness.contract.description":
+ "Runtime configuration, release consistency and error boundaries are checked before mounting.",
+ "home.readiness.adapters.title": "Replaceable integrations",
+ "home.readiness.adapters.description":
+ "Authentication, HTTP, cache, storage and telemetry sit behind ports.",
+ "home.readiness.accessibility.title": "Accessible screens",
+ "home.readiness.accessibility.description":
+ "Keyboard navigation, focus movement and the responsive app shell work out of the box.",
+ "home.runtime.checking": "Checking the verified runtime information.",
+ "home.runtime.failed": "The runtime information could not be checked.",
+ "home.runtime.summary": "Build {buildId} · Release {releaseId}",
+ "home.starter.title": "Explore the prepared screens",
+ "home.starter.description":
+ "See installed routes, contracts and runtime capabilities on the platform composition page, and common components and async screen states on the example routes.",
+ "home.starter.platform": "View platform composition",
+ "home.starter.ui": "View UI components",
+ "home.starter.states": "View screen states",
"page.notFound.title": "Page not found.",
"page.notFound.description": "Check the address or return to the start page.",
"template.breadcrumb": "Current location",
@@ -279,7 +346,6 @@ const PLATFORM_EN_MESSAGES = {
"form.validation.configuration": "Review the input configuration.",
"form.conflict":
"Another update conflicts with this change. Your input has been preserved.",
- "form.unavailable": "The change could not be saved. Try again shortly.",
"form.reauthLosesInput":
"Signing in again clears what you entered on this page. Copy it first if you need it.",
"form.remaining": "{count} characters remaining",
@@ -300,6 +366,32 @@ const PLATFORM_EN_MESSAGES = {
"error.asset_mismatch": "The page assets do not match this release.",
"error.render_failure": "The page could not be displayed.",
"error.unknown_failure": "An unexpected problem occurred.",
+ "error.request_aborted": "The request was cancelled.",
+ "error.content_type_mismatch": "The server response format is not supported.",
+ "error.malformed_json": "The server response could not be read.",
+ "error.response_body_limit": "The server response exceeded the allowed size.",
+ "error.envelope_mismatch": "The server response structure is unexpected.",
+ "error.schema_mismatch": "The server response data does not match this page.",
+ "error.mapping_contract_violation":
+ "The server response could not be converted for this page.",
+ "error.result_limit_exceeded": "There are too many results to display.",
+ "error.scope_generation_changed":
+ "The session changed, so the earlier request was stopped.",
+ "error.identity_intern_limit_exceeded":
+ "There are too many items to process. Try again shortly.",
+ "error.duplicate_in_flight": "The same request is already in progress.",
+ "error.pagination_contract_violation":
+ "The page information could not be verified.",
+ "error.conflict": "The change conflicts with another update.",
+ "error.validation_rejected": "The server did not accept the entered values.",
+ "error.unknown_client_failure": "The request could not be processed.",
+ "error.boot_config_failure": "The runtime configuration could not be loaded.",
+ "error.release_manifest_failure": "The release information could not be loaded.",
+ "error.deploy_mismatch": "The deployment does not match this page.",
+ "error.storage_unavailable": "Browser storage is unavailable.",
+ "error.storage_quota_exceeded": "Browser storage is full.",
+ "error.telemetry_failure": "The diagnostic information could not be sent.",
+ "error.query_cache_failure": "The stored query results are unavailable.",
...BOOT_MESSAGES["en-US"],
} as const satisfies Record;
diff --git a/src/presentation/i18n/message-contract.ts b/src/presentation/i18n/message-contract.ts
index ac193b51..fe0b9c18 100644
--- a/src/presentation/i18n/message-contract.ts
+++ b/src/presentation/i18n/message-contract.ts
@@ -21,6 +21,7 @@ export type MessageParameters = Readonly<{
"route.documentTitle": { title: string; appName: string };
"template.supportReference": { reference: string };
"form.remaining": { count: number };
+ "home.runtime.summary": { buildId: string; releaseId: string };
"boot.supportReference": { reference: string };
}>;
export type ParameterlessMessageKey = Exclude<
diff --git a/src/presentation/pages/home-page.tsx b/src/presentation/pages/home-page.tsx
index 3412ffa2..b773916e 100644
--- a/src/presentation/pages/home-page.tsx
+++ b/src/presentation/pages/home-page.tsx
@@ -3,25 +3,18 @@ import { Link } from "react-router-dom";
import { routePath } from "../../features/installed-feature-contracts.ts";
import { PageHeader } from "../design-system/index.ts";
+import { useLocale } from "../i18n/index.ts";
import { useApplicationRuntime } from "../providers/application-provider.tsx";
const READINESS_ITEMS = Object.freeze([
- {
- title: "실행 계약",
- description: "런타임 설정, 릴리스 정합성, 오류 경계가 마운트 전에 검증됩니다.",
- },
- {
- title: "교체 가능한 연동",
- description: "인증, HTTP, 캐시, 저장소, 텔레메트리가 포트 뒤에 분리되어 있습니다.",
- },
- {
- title: "접근 가능한 화면",
- description: "키보드 탐색, 포커스 이동, 반응형 앱 셸의 기본 동작이 준비되어 있습니다.",
- },
-]);
+ "contract",
+ "adapters",
+ "accessibility",
+] as const);
export default function HomePage() {
const runtime = useApplicationRuntime();
+ const { message } = useLocale();
const [release, setRelease] = useState<
Awaited> | "failed" | null
>(null);
@@ -44,48 +37,48 @@ export default function HomePage() {
return (
-