feat(examples)!: 예제 화면 3개를 끌 수 있는 기능으로 옮긴다

문제
/examples/ui, /examples/states, /examples/auth(와 /examples/platform)는
플랫폼 라우트 레지스트리에 고정이었다. VITE_PRODUCT_FEATURES와
FEATURE_OVERRIDES는 기능만 빼므로 제품은 이 화면을 끌 수 없었다.
릴리스 게이트 FE-GATE-028은 ROUTE_REGISTRY의 모든 라우트에 서명된
수동 접근성 기록을 요구해서, 제품은 템플릿 갤러리를 운영 메뉴에 두고
서명하거나 템플릿 파일 5개와 src/presentation/examples/를 지워야 했다.

고른 방법
- UI 갤러리·화면 상태·인증 연동을 platform-examples-feature로 옮겼다.
  자기 context platform-examples-context(루트 examples/*)에 산다.
  reference-context의 examples/reference-resources/*와 플랫폼 라우트
  /examples/platform이 더 구체적이라 그 URL은 그대로 간다.
- 라우트 ID·경로·청크 ID·표면은 바꾸지 않았다. 시각·e2e 테스트와 a11y
  기록(artifacts/tests/a11y-manual/EXAMPLES_*.md)이 그대로 이 이름을
  쓴다. 기능을 빼면 a11y 목록은 ROUTE_REGISTRY에서 오므로 같이 빠진다.
- 실행부는 비어 있다(스키마·adapter·계약 기여 없음). 페이지는 context
  routes에서 페이지마다 lazy로 받는다.
- 플랫폼 구성 화면(EXAMPLES_PLATFORM)은 플랫폼 라우트로 남겼다. 처음에는
  같이 옮겼다. 같은 호스트·같은 부하(15~19)에서 d99301b와 번갈아 잰
  lab이 기능 라우트로는 443·432 ms FAIL이었다(d99301b 133·183 ms
  PASS). 기능 라우트의 첫 진입은 context routes 모듈을 받은 뒤에 페이지
  청크를 받는다(요청 추적: 939 B + 177 B 다음에 5,183 B + 3개). 페이지를
  routes 모듈에 정적으로 넣으면 릴리스 매니페스트의 routeChunks 계약
  (페이지마다 dynamic entry)이 깨진다. 15-01의 "예산을 올리지 않는다"를
  지키려고 이 한 화면은 남겼다.
- 홈 화면은 예제 라우트 ID를 적지 않는다. 내비게이션의 처음 세 화면을
  "{title} 보기"로 보여 준다. 템플릿에서는 예전과 같은 세 링크(플랫폼
  구성·UI 구성요소·화면 상태)가 나오고, 예제를 뺀 제품에서는 그 제품의
  화면이 나온다. home.starter.platform·ui·states 키를 home.starter.open
  하나로 바꿨다. VITE_PRODUCT_FEATURES=none 빌드 검사
  (product-feature-selection-build)가 홈 청크의 예제 라우트 ID를 잡았다.
- 예제 화면 component 테스트는 tests/features/platform-examples-feature/로
  옮겼다. 제거 드릴이 같이 지운다. runtime-adapters 테스트는 API가 있는
  기능만 센다(예제 기능은 API가 없다). context-route-roots 테스트의
  "플랫폼 라우트와 같은 경로" 예는 /examples/platform으로 바꿨다.
- old-tab-chunk-recovery e2e는 페이지 소스를 빌드 A의 Vite manifest에서
  찾는다(기능 폴더 이름을 적지 않음). UI 갤러리가 기능 라우트라 B 탭이
  잃는 청크는 그 context routes 모듈이다. 허용 패턴에 넣었다.
- 예제 화면 문구는 08-07대로 한국어 고정이다. 화면 문구 ESLint 규칙의
  예외에 새 폴더를 넣었다.
- 버린 대안: 빌드 변수로 숨김(선택 장치가 하나 더 생김), 예제 화면만
  제품이 지우게 둠(동기화 충돌 자리가 남음).

위험·한계
- 공개 경로가 바뀌었다. src/presentation/examples/{ui-gallery,
  state-gallery,auth-example}-page.tsx, PLATFORM_ROUTE_REGISTRY·
  PLATFORM_ROUTE_RUNTIME(_CONTRACT)의 EXAMPLES_UI·STATES·AUTH,
  home.starter.platform/ui/states 키를 쓰던 다운스트림은 깨진다.
- 플랫폼 구성 화면은 여전히 끌 수 없고 FE-GATE-028 서명 대상이다.
- tests/e2e와 tests/visual의 여러 spec이 예제 화면을 자기 페이지로 쓴다.
  예제를 뺀 제품은 그 spec을 자기 화면으로 바꾸거나 지워야 한다
  (starter-experience.md에 적음). 제거 드릴은 브라우저 테스트를 돌리지
  않아 이것을 보지 않는다.
- 예제 기능 제거 드릴은 16-02(빈 ciScripts로 CI 기준선 사유가 공백)
  때문에 그대로는 시작하자마자 실패한다. 아래 드릴 결과는 그 한 줄을
  임시로 고친 상태에서 낸 것이다(커밋하지 않음).
- 기능 라우트 첫 진입이 이 lab 조건에서 약 430 ms라는 것은 어느 게이트도
  재지 않는다.

검증
- product-feature-selection-build(VITE_PRODUCT_FEATURES=none 빌드):
  홈 청크의 예제 라우트 ID 3건으로 실패한 것을 확인하고 홈 화면을 고친
  뒤 통과.
- test:sample-removal -- --feature=platform-examples-feature(heavy lock,
  16-02 한 줄 임시 패치): PASS, 13 checks(typecheck, architecture,
  registries, test:all, coverage, test-evidence, ci, home-smoke, build,
  route-absent, 잔여 ID 0). 첫 시도에서는 lab-performance 단위 테스트가
  측정 라우트 조회가 포트 검사보다 먼저여서 실패했다(그 뒤 이 변경에서
  측정 라우트를 플랫폼에 남겨 조회 변경 자체를 뺐다).
- test:unit 2,587, test:component 253, tests/features·platform·
  architecture 383 통과. check:types, lint, check:architecture,
  check:i18n, check:registries(additive), verify:documentation 통과.
- test:e2e 세 엔진 187 passed, 3 skipped(Firefox SW quarantine).
  old-tab-chunk-recovery 포함. test:a11y 60 passed.
- build + check:bundle: 초기 JS 201,940 / 204,800 B(+92 B).
- lab(측정 라우트를 기능으로 옮긴 시도): 443·432 ms FAIL, 같은 묶음
  d99301b 133·183 ms PASS(부하 15~19). 남긴 뒤 136·134 ms PASS.

Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-04
BREAKING CHANGE: 예제 라우트 EXAMPLES_UI·EXAMPLES_STATES·EXAMPLES_AUTH가
플랫폼 레지스트리에서 platform-examples-feature로 옮겨졌다. 페이지 파일은
src/features/platform-examples-feature/presentation/으로 갔고,
PLATFORM_ROUTE_REGISTRY·PLATFORM_ROUTE_RUNTIME_CONTRACT·
PLATFORM_ROUTE_RUNTIME에 이 키들이 없다. 홈 문구 키
home.starter.platform·ui·states는 home.starter.open({title})로 바뀌었다.
예제를 지운 다운스트림은 이 기능 폴더와 context를 지우면 된다.
This commit is contained in:
DongHyeonka
2026-11-04 22:59:03 +09:00
parent 7f633106bb
commit b96d61d8f7
26 changed files with 473 additions and 209 deletions
@@ -70,9 +70,10 @@ route/form/failure 의미 값
- `check:i18n`은 catalog key와 placeholder parity, backend message JSX 렌더링을
검사한다. 검사 범위는 공통 UI 디렉터리, `src/presentation/pages`, 모든
`src/features/*/presentation`이다. 컴포넌트 갤러리 `src/presentation/examples`는
일부러 뺐다(`scripts/check-i18n.ts`의 `commonDirectories`,
`featurePresentationDirectories`).
`src/features/*/presentation`이다. 플랫폼 구성 화면
`src/presentation/examples`와 예제 화면
`src/features/platform-examples-feature/presentation`(1103/09-04)은 화면
문구 ESLint 규칙에서 일부러 뺐다(`eslint.config.ts`).
- 화면 문구가 catalog에서 오는지는 ESLint `no-restricted-syntax`가 본다
(`eslint.config.ts`의 `screenTextSelectors`, 0929/08-02). 대상은 글자가 든
`JSXText`와 표시·접근성 속성(`aria-label`, `title`, `placeholder`, `alt`,
+26 -8
View File
@@ -85,14 +85,32 @@ rather than adding another independent route or data-loading convention.
### Replacing the starter screens
`/` (`src/presentation/pages/home-page.tsx`) and `/examples/*`
(`src/presentation/examples/`) are template content. Their own tests are the
`tests/component/starter-*.test.tsx` files; delete them together with the
screens. The platform's component tests (router, boundaries, shell, runtime
tree) run on the pages of the test-only feature in
`tests/helpers/fixture-feature.tsx` and keep passing when the starter screens
change. Browser-level checks of the starter screens stay in `tests/e2e` and
`tests/visual`.
`/` (`src/presentation/pages/home-page.tsx`) is the platform's `APP_HOME`; a
feature takes it over by declaring that route id (see "Product home and
layouts"). Its starter links are the first three screens of the navigation.
The example screens `/examples/ui`, `/examples/states` and `/examples/auth`
are one feature, `src/features/platform-examples-feature/`, in its own context
`src/contexts/platform-examples-context/` (1103/09-04). A product turns them
off like any feature: leave the id out of `VITE_PRODUCT_FEATURES`, or remove
it with `corepack pnpm test:sample-removal -- --feature=platform-examples-feature`
as the drill. Their routes then leave the registry, the navigation, the
bundle and the manual accessibility list (FE-GATE-028). Their component tests
are in `tests/features/platform-examples-feature/` and go with them.
The platform overview (`/examples/platform`,
`src/presentation/examples/platform-overview-page.tsx`) stays a platform
route. It describes the installed registries, and the lab gate (FE-GATE-026)
times entering it: a feature route's first entry also loads its context's
routes module before the page, a second request round the 200 ms budget does
not fit. Its tests are the `tests/component/starter-*.test.tsx` files.
The platform's component tests (router, boundaries, shell, runtime tree) run
on the pages of the test-only feature in `tests/helpers/fixture-feature.tsx`
and keep passing without the examples. The browser-level checks in
`tests/e2e` and `tests/visual` use the example screens as their pages and run
where the examples are installed: a product that leaves them out points those
specs at its own screens or deletes them.
### Ownership declarations
+10 -3
View File
@@ -458,8 +458,9 @@ const hookRules = {
// template literal, a ternary, an object prop such as `heading.title`) is not
// seen; review catches those. A product replaces these selectors in its own
// config, for example to allow a brand name or to drop the rule for a
// one-locale product. The component gallery (src/presentation/examples) and
// stories are workshop code and stay out; tests are outside these folders.
// one-locale product. The platform overview (src/presentation/examples),
// the example screens (src/features/platform-examples-feature/presentation)
// and stories are workshop code and stay out; tests are outside these folders.
const screenTextDirectories = [
"src/presentation/boundaries",
"src/presentation/components",
@@ -911,7 +912,13 @@ export default [
`${directory}/**/*.tsx`,
`tests/fixtures/i18n/*/${directory}/**/*.tsx`,
]),
ignores: ["**/*.stories.tsx"],
// 1103/09-04. The example screens moved from src/presentation/examples
// into this feature and stay workshop code: their copy is Korean in every
// locale on purpose (08-07).
ignores: [
"**/*.stories.tsx",
"src/features/platform-examples-feature/presentation/**",
],
rules: {
"no-restricted-syntax": [
...commonSecurityRules["no-restricted-syntax"],
+3 -3
View File
@@ -10,9 +10,9 @@
"routeChunks": {
"route-home": "src/presentation/pages/home-page.tsx",
"route-examples-platform": "src/presentation/examples/platform-overview-page.tsx",
"route-examples-ui": "src/presentation/examples/ui-gallery-page.tsx",
"route-examples-states": "src/presentation/examples/state-gallery-page.tsx",
"route-examples-auth": "src/presentation/examples/auth-example-page.tsx",
"route-examples-ui": "src/features/platform-examples-feature/presentation/ui-gallery-page.tsx",
"route-examples-states": "src/features/platform-examples-feature/presentation/state-gallery-page.tsx",
"route-examples-auth": "src/features/platform-examples-feature/presentation/auth-example-page.tsx",
"route-reference-resources": "src/features/reference-feature/presentation/reference-resource-page.tsx",
"route-reference-resource-detail": "src/features/reference-feature/presentation/reference-resource-detail-page.tsx",
"route-reference-resource-form": "src/features/reference-feature/presentation/reference-resource-form-page.tsx",
+3 -2
View File
@@ -59,8 +59,9 @@ if (!fixtureMode) {
// from an ordinary `.message` read. Fixture mode runs the ESLint rule on the
// fixture trees too, so this one gate shows the whole i18n contract rejecting
// every forbidden file and passing the allowed one.
// `src/presentation/examples` is the component gallery and stays out of scope
// on purpose.
// `src/presentation/examples` (the platform overview) and the example
// screens (`src/features/platform-examples-feature/presentation`, 1103/09-04)
// are workshop code and stay out of the ESLint rule's scope on purpose.
const forbiddenFixtureRoot = "tests/fixtures/i18n/forbidden";
const allowedFixtureRoot = "tests/fixtures/i18n/allowed";
const sourceRoot = fixtureMode ? forbiddenFixtureRoot : ".";
@@ -0,0 +1,12 @@
/**
* 1103/09-04. The template's example screens (UI gallery, screen states,
* auth integration) as one removable bounded context. A product leaves
* `platform-examples-feature` out of `VITE_PRODUCT_FEATURES`, or deletes it,
* and the three routes leave the registry, the navigation, the bundle and the
* manual accessibility list together. The root is `examples/*`;
* `reference-context` keeps the more specific `examples/reference-resources/*`.
*/
export const CONTEXT_MODULE_ID = "platform-examples-context";
export const CONTEXT_APP_ID = "template-app";
export const CONTEXT_ROUTE_PATH = "examples/*";
export const CONTEXT_MAX_FEATURES = 1;
-18
View File
@@ -23,24 +23,6 @@ export const PLATFORM_ROUTE_RUNTIME_CONTRACT = Object.freeze({
paramsCodec: "none",
searchCodec: "none",
}),
EXAMPLES_UI: runtime({
routeId: "EXAMPLES_UI",
moduleId: "ui-gallery-page",
paramsCodec: "none",
searchCodec: "none",
}),
EXAMPLES_STATES: runtime({
routeId: "EXAMPLES_STATES",
moduleId: "state-gallery-page",
paramsCodec: "none",
searchCodec: "none",
}),
EXAMPLES_AUTH: runtime({
routeId: "EXAMPLES_AUTH",
moduleId: "auth-example-page",
paramsCodec: "none",
searchCodec: "none",
}),
NOT_FOUND: runtime({
routeId: "NOT_FOUND",
moduleId: "not-found-page",
-39
View File
@@ -43,45 +43,6 @@ export const PLATFORM_ROUTE_REGISTRY = Object.freeze({
navigationLabel: "플랫폼 구성",
navigationOrder: 15,
}),
EXAMPLES_UI: route({
routeId: "EXAMPLES_UI",
path: "/examples/ui",
paramsSchema: null,
searchSchema: null,
access: "public",
loadingSurface: "example-page",
errorSurface: "route-boundary",
chunkId: "route-examples-ui",
title: "UI 구성요소",
navigationLabel: "UI 구성요소",
navigationOrder: 20,
}),
EXAMPLES_STATES: route({
routeId: "EXAMPLES_STATES",
path: "/examples/states",
paramsSchema: null,
searchSchema: null,
access: "public",
loadingSurface: "example-page",
errorSurface: "route-boundary",
chunkId: "route-examples-states",
title: "화면 상태",
navigationLabel: "화면 상태",
navigationOrder: 30,
}),
EXAMPLES_AUTH: route({
routeId: "EXAMPLES_AUTH",
path: "/examples/auth",
paramsSchema: null,
searchSchema: null,
access: "public",
loadingSurface: "example-page",
errorSurface: "route-boundary",
chunkId: "route-examples-auth",
title: "인증 연동",
navigationLabel: "인증 연동",
navigationOrder: 40,
}),
NOT_FOUND: route({
routeId: "NOT_FOUND",
path: "*",
@@ -0,0 +1,17 @@
import type { RouteObject } from "react-router-dom";
import { PLATFORM_EXAMPLES_CONTRACT } from "./contracts/platform-examples-contract.ts";
import { PLATFORM_EXAMPLES_ROUTE_RUNTIME } from "./presentation/platform-examples-runtime.ts";
export const FEATURE_CONTEXT_ROUTES: readonly RouteObject[] = Object.freeze(
Object.values(PLATFORM_EXAMPLES_CONTRACT.routes).map((definition) =>
Object.freeze({
id: definition.routeId,
path: definition.path,
handle: Object.freeze({
routeId: definition.routeId,
runtime: PLATFORM_EXAMPLES_ROUTE_RUNTIME[definition.routeId],
}),
}),
),
);
@@ -0,0 +1,82 @@
export const PLATFORM_EXAMPLES_FEATURE_ID = "platform-examples-feature";
/**
* 1103/09-04. Three of the template's example screens, formerly fixed
* platform routes. The platform overview (`EXAMPLES_PLATFORM`) stays a
* platform route: the lab gate (FE-GATE-026) times entering it, and a feature
* route's first entry costs a second request round (its context's routes
* module, then the page). Paths, chunk ids and surfaces are unchanged: the
* visual and e2e tests and the manual accessibility records still name them.
* Declaration only, so it holds data; the pages load with `context-routes.ts`.
*/
export const PLATFORM_EXAMPLES_CONTRACT = Object.freeze({
featureId: PLATFORM_EXAMPLES_FEATURE_ID,
routes: Object.freeze({
EXAMPLES_UI: Object.freeze({
routeId: "EXAMPLES_UI",
path: "/examples/ui",
paramsSchema: null,
searchSchema: null,
access: "public",
loadingSurface: "example-page",
errorSurface: "route-boundary",
chunkId: "route-examples-ui",
title: "UI 구성요소",
navigationLabel: "UI 구성요소",
navigationOrder: 20,
}),
EXAMPLES_STATES: Object.freeze({
routeId: "EXAMPLES_STATES",
path: "/examples/states",
paramsSchema: null,
searchSchema: null,
access: "public",
loadingSurface: "example-page",
errorSurface: "route-boundary",
chunkId: "route-examples-states",
title: "화면 상태",
navigationLabel: "화면 상태",
navigationOrder: 30,
}),
EXAMPLES_AUTH: Object.freeze({
routeId: "EXAMPLES_AUTH",
path: "/examples/auth",
paramsSchema: null,
searchSchema: null,
access: "public",
loadingSurface: "example-page",
errorSurface: "route-boundary",
chunkId: "route-examples-auth",
title: "인증 연동",
navigationLabel: "인증 연동",
navigationOrder: 40,
}),
}),
routeRuntimeContracts: Object.freeze({
EXAMPLES_UI: Object.freeze({
routeId: "EXAMPLES_UI",
moduleId: "ui-gallery-page",
paramsCodec: "none",
searchCodec: "none",
}),
EXAMPLES_STATES: Object.freeze({
routeId: "EXAMPLES_STATES",
moduleId: "state-gallery-page",
paramsCodec: "none",
searchCodec: "none",
}),
EXAMPLES_AUTH: Object.freeze({
routeId: "EXAMPLES_AUTH",
moduleId: "auth-example-page",
paramsCodec: "none",
searchCodec: "none",
}),
}),
invalidation: Object.freeze({
topics: Object.freeze([]),
namespaces: Object.freeze([]),
edges: Object.freeze([]),
}),
topicVersions: Object.freeze([]),
contractPackages: Object.freeze([]),
} as const);
@@ -0,0 +1,23 @@
/**
* 1103/09-04. The route titles and navigation labels the shell reads; they
* moved here from the platform catalog with the routes. The pages' own copy
* stays Korean in every locale (08-07).
*/
export const PLATFORM_EXAMPLES_MESSAGE_CATALOGS = Object.freeze({
"ko-KR": Object.freeze({
"route.EXAMPLES_UI.navigation": "UI 구성요소",
"route.EXAMPLES_UI.title": "UI 구성요소",
"route.EXAMPLES_STATES.navigation": "화면 상태",
"route.EXAMPLES_STATES.title": "화면 상태",
"route.EXAMPLES_AUTH.navigation": "인증 연동",
"route.EXAMPLES_AUTH.title": "인증 연동",
}),
"en-US": Object.freeze({
"route.EXAMPLES_UI.navigation": "UI components",
"route.EXAMPLES_UI.title": "UI components",
"route.EXAMPLES_STATES.navigation": "Screen states",
"route.EXAMPLES_STATES.title": "Screen states",
"route.EXAMPLES_AUTH.navigation": "Authentication",
"route.EXAMPLES_AUTH.title": "Authentication",
}),
} as const);
@@ -0,0 +1,27 @@
import { defineFeatureModule } from "../feature-module.ts";
import {
PLATFORM_EXAMPLES_CONTRACT,
PLATFORM_EXAMPLES_FEATURE_ID,
} from "./contracts/platform-examples-contract.ts";
import { PLATFORM_EXAMPLES_MESSAGE_CATALOGS } from "./contracts/platform-examples-message-catalog.ts";
export const FEATURE_MODULE_ID =
"platform-examples-feature" satisfies typeof PLATFORM_EXAMPLES_FEATURE_ID;
/** Owning bounded context (route root and budget live in its declaration). */
export const FEATURE_CONTEXT_ID = "platform-examples-context";
/**
* 1103/09-04. The template's example screens as a feature, so the product's
* feature selection, `FEATURE_OVERRIDES`, the removal drill and the manual
* accessibility list apply to them like to any feature. Declaration only:
* the pages load with the context routes, and the runtime half is empty.
*/
export const PLATFORM_EXAMPLES_FEATURE_MODULE = defineFeatureModule({
id: FEATURE_MODULE_ID,
contracts: PLATFORM_EXAMPLES_CONTRACT,
routes: PLATFORM_EXAMPLES_CONTRACT.routes,
messages: PLATFORM_EXAMPLES_MESSAGE_CATALOGS,
loadRuntime: async () => (await import("./feature-runtime.ts")).FEATURE_RUNTIME,
} as const);
export const FEATURE_MODULE = PLATFORM_EXAMPLES_FEATURE_MODULE;
@@ -0,0 +1,13 @@
import { defineFeatureRuntime } from "../feature-module.ts";
import { PLATFORM_EXAMPLES_FEATURE_ID } from "./contracts/platform-examples-contract.ts";
/**
* 1103/09-04. The example screens call no feature API: they show the
* design system and the shell's session. The runtime half is empty.
*/
export const FEATURE_RUNTIME = defineFeatureRuntime({
featureId: PLATFORM_EXAMPLES_FEATURE_ID,
schemas: Object.freeze({}),
adapters: [],
contractContributions: [],
} as const);
@@ -1,8 +1,8 @@
import { PageHeader } from "../design-system/index.ts";
import { PageHeader } from "../../../presentation/design-system/index.ts";
import {
useSession,
useSessionAction,
} from "../providers/session-provider.tsx";
} from "../../../presentation/providers/session-provider.tsx";
export default function AuthExamplePage() {
const { sessionState } = useSession();
@@ -0,0 +1,17 @@
import { lazy } from "react";
/** One lazy chunk per example page, as when they were platform routes. */
export const PLATFORM_EXAMPLES_ROUTE_RUNTIME = {
EXAMPLES_UI: Object.freeze({
moduleId: "ui-gallery-page",
Component: lazy(() => import("./ui-gallery-page.tsx")),
}),
EXAMPLES_STATES: Object.freeze({
moduleId: "state-gallery-page",
Component: lazy(() => import("./state-gallery-page.tsx")),
}),
EXAMPLES_AUTH: Object.freeze({
moduleId: "auth-example-page",
Component: lazy(() => import("./auth-example-page.tsx")),
}),
} as const;
@@ -1,7 +1,7 @@
import { useState } from "react";
import { deriveAsyncState } from "../../application/view-models/async-state.ts";
import { createFailure } from "../../contracts/errors.ts";
import { deriveAsyncState } from "../../../application/view-models/async-state.ts";
import { createFailure } from "../../../contracts/errors.ts";
import {
AsyncSurface,
EmptySurface,
@@ -13,7 +13,7 @@ import {
Button,
Card,
PageHeader,
} from "../design-system/index.ts";
} from "../../../presentation/design-system/index.ts";
export default function StateGalleryPage() {
const [lastAction, setLastAction] = useState(
@@ -19,7 +19,7 @@ import {
ToastProvider,
Tooltip,
useToast,
} from "../design-system/index.ts";
} from "../../../presentation/design-system/index.ts";
const COLOR_TOKENS = Object.freeze([
["Surface", "--color-surface"],
+4 -20
View File
@@ -45,12 +45,6 @@ const PLATFORM_KO_MESSAGES = {
"route.APP_HOME.title": "Clean Architecture Frontend",
"route.EXAMPLES_PLATFORM.navigation": "플랫폼 구성",
"route.EXAMPLES_PLATFORM.title": "플랫폼 구성",
"route.EXAMPLES_UI.navigation": "UI 구성요소",
"route.EXAMPLES_UI.title": "UI 구성요소",
"route.EXAMPLES_STATES.navigation": "화면 상태",
"route.EXAMPLES_STATES.title": "화면 상태",
"route.EXAMPLES_AUTH.navigation": "인증 연동",
"route.EXAMPLES_AUTH.title": "인증 연동",
"route.NOT_FOUND.navigation": "찾을 수 없음",
"route.NOT_FOUND.title": "페이지를 찾을 수 없습니다.",
"async.loading": "불러오는 중",
@@ -117,10 +111,8 @@ const PLATFORM_KO_MESSAGES = {
"home.runtime.summary": "빌드 {buildId} · 릴리스 {releaseId}",
"home.starter.title": "준비된 화면 살펴보기",
"home.starter.description":
"설치된 라우트와 계약, 런타임 능력은 플랫폼 구성 화면에서, 공통 구성요소와 비동기 화면 상태는 예제 라우트에서 확인하세요.",
"home.starter.platform": "플랫폼 구성 보기",
"home.starter.ui": "UI 구성요소 보기",
"home.starter.states": "화면 상태 보기",
"내비게이션의 첫 화면을 바로 엽니다. 템플릿에서는 설치된 라우트·계약·런타임 능력, 공통 구성요소, 비동기 화면 상태를 보여 주는 예제 화면입니다.",
"home.starter.open": "{title} 보기",
"page.notFound.title": "페이지를 찾을 수 없습니다.",
"page.notFound.description":
"주소를 확인하거나 준비된 시작 화면으로 돌아가세요.",
@@ -258,12 +250,6 @@ const PLATFORM_EN_MESSAGES = {
"route.APP_HOME.title": "Clean Architecture Frontend",
"route.EXAMPLES_PLATFORM.navigation": "Platform composition",
"route.EXAMPLES_PLATFORM.title": "Platform composition",
"route.EXAMPLES_UI.navigation": "UI components",
"route.EXAMPLES_UI.title": "UI components",
"route.EXAMPLES_STATES.navigation": "Screen states",
"route.EXAMPLES_STATES.title": "Screen states",
"route.EXAMPLES_AUTH.navigation": "Authentication",
"route.EXAMPLES_AUTH.title": "Authentication",
"route.NOT_FOUND.navigation": "Not found",
"route.NOT_FOUND.title": "Page not found",
"async.loading": "Loading",
@@ -329,10 +315,8 @@ const PLATFORM_EN_MESSAGES = {
"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",
"Open the first screens of the navigation. In the template these are the example screens for installed routes, contracts and runtime capabilities, common components and async screen states.",
"home.starter.open": "View {title}",
"page.notFound.title": "Page not found.",
"page.notFound.description": "Check the address or return to the start page.",
"template.breadcrumb": "Current location",
+35 -25
View File
@@ -1,7 +1,7 @@
import { useEffect, useState } from "react";
import { Link } from "react-router-dom";
import { routePath } from "../../features/installed-feature-contracts.ts";
import { NAVIGATION_ROUTES } 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";
@@ -12,9 +12,19 @@ const READINESS_ITEMS = Object.freeze([
"accessibility",
] as const);
/**
* 1103/09-04. The first screens of the navigation after this page. In the
* template those are its example screens, a removable feature; a
* product that leaves them out gets its own screens here, and the page names
* no feature's route.
*/
const STARTER_ROUTES = Object.freeze(
NAVIGATION_ROUTES.filter((route) => route.routeId !== "APP_HOME").slice(0, 3),
);
export default function HomePage() {
const runtime = useApplicationRuntime();
const { message } = useLocale();
const { message, resolve } = useLocale();
const [release, setRelease] = useState<
Awaited<ReturnType<typeof runtime.getReleaseSummary>> | "failed" | null
>(null);
@@ -59,29 +69,29 @@ export default function HomePage() {
})
: message("home.runtime.checking")}
</p>
<section className="ui-panel starter-actions" aria-labelledby="starter-title">
<div>
<h2 id="starter-title">{message("home.starter.title")}</h2>
<p>{message("home.starter.description")}</p>
</div>
<div className="button-row">
<Link className="ui-button" to={routePath("EXAMPLES_PLATFORM")}>
{message("home.starter.platform")}
</Link>
<Link
className="ui-button ui-button--secondary"
to={routePath("EXAMPLES_UI")}
>
{message("home.starter.ui")}
</Link>
<Link
className="ui-button ui-button--secondary"
to={routePath("EXAMPLES_STATES")}
>
{message("home.starter.states")}
</Link>
</div>
</section>
{STARTER_ROUTES.length > 0 ? (
<section className="ui-panel starter-actions" aria-labelledby="starter-title">
<div>
<h2 id="starter-title">{message("home.starter.title")}</h2>
<p>{message("home.starter.description")}</p>
</div>
<div className="button-row">
{STARTER_ROUTES.map((route, index) => (
<Link
key={route.routeId}
className={
index === 0 ? "ui-button" : "ui-button ui-button--secondary"
}
to={route.path}
>
{message("home.starter.open", {
title: resolve(`route.${route.routeId}.navigation`),
})}
</Link>
))}
</div>
</section>
) : null}
</section>
);
}
-12
View File
@@ -28,18 +28,6 @@ export const PLATFORM_ROUTE_RUNTIME = {
"EXAMPLES_PLATFORM",
() => import("../examples/platform-overview-page.tsx"),
),
EXAMPLES_UI: runtime(
"EXAMPLES_UI",
() => import("../examples/ui-gallery-page.tsx"),
),
EXAMPLES_STATES: runtime(
"EXAMPLES_STATES",
() => import("../examples/state-gallery-page.tsx"),
),
EXAMPLES_AUTH: runtime(
"EXAMPLES_AUTH",
() => import("../examples/auth-example-page.tsx"),
),
NOT_FOUND: runtime(
"NOT_FOUND",
() => import("../pages/not-found-page.tsx"),
@@ -193,10 +193,10 @@ describe("feature routes and platform routes", () => {
expect(() =>
app(
context("examples", "examples/*", [
feature("examples-feature", { EXAMPLES_UI_COPY: "/examples/ui" }),
feature("examples-feature", { EXAMPLES_PLATFORM_COPY: "/examples/platform" }),
]),
),
).toThrow(/EXAMPLES_UI_COPY.*\/examples\/ui.*examples-feature.*examples.*EXAMPLES_UI/);
).toThrow(/EXAMPLES_PLATFORM_COPY.*\/examples\/platform.*examples-feature.*examples.*EXAMPLES_PLATFORM/);
});
it("rejects the same path under a layout of its own", () => {
@@ -204,10 +204,10 @@ describe("feature routes and platform routes", () => {
expect(() =>
app(
context("examples", "examples/*", [
feature("examples-feature", { EXAMPLES_UI_COPY: "/examples/ui" }),
feature("examples-feature", { EXAMPLES_PLATFORM_COPY: "/examples/platform" }),
], layout),
),
).toThrow(/EXAMPLES_UI_COPY.*EXAMPLES_UI/);
).toThrow(/EXAMPLES_PLATFORM_COPY.*EXAMPLES_PLATFORM/);
});
it("rejects two feature routes with the same path, naming both", () => {
+6 -39
View File
@@ -3,10 +3,8 @@
import { render, screen, waitFor } 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 { describe, expect, it } from "vitest";
import { createAnonymousSessionAdapter } from "../../src/adapters/auth/external-session-adapter.ts";
import StateGalleryPage from "../../src/presentation/examples/state-gallery-page.tsx";
import { LocaleProvider } from "../../src/presentation/i18n/index.ts";
import HomePage from "../../src/presentation/pages/home-page.tsx";
import { ApplicationProvider } from "../../src/presentation/providers/application-provider.tsx";
@@ -15,10 +13,11 @@ import { AppRouter } from "../../src/presentation/routes/app-router.tsx";
import { createTestApplication } from "../helpers/create-test-application.ts";
/**
* The starter screens (`/` and `/examples/*`) are the template's content, not
* the platform (0929/10-02). A product that replaces them deletes the
* `starter-*.test.tsx` files with them; the platform tests run on the
* test-only feature's pages and keep passing.
* The starter screens (`/` and `/examples/platform`) are the template's
* content, not the platform (0929/10-02). A product that replaces them deletes
* the `starter-*.test.tsx` files with them; the platform tests run on the
* test-only feature's pages and keep passing. 1103/09-04: the other example
* screens are a removable feature, tested in its own test folder.
*/
function renderApp(
@@ -83,35 +82,3 @@ describe("starter home page", () => {
).not.toBeInTheDocument();
});
});
describe("starter example pages", () => {
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",
createTestApplication({
session: { ...createAnonymousSessionAdapter(), beginSignIn },
}),
);
await user.click(
await screen.findByRole("button", { name: "로그인 시작" }),
);
expect(beginSignIn).toHaveBeenCalledWith("/examples/auth#session");
});
it("nests the state gallery's titles under the card and section around them (08-05)", () => {
render(<StateGalleryPage />);
expect(
screen.getByRole("heading", { name: "아직 표시할 항목이 없습니다.", level: 4 }),
).toBeVisible();
expect(screen.getAllByRole("heading", { level: 3 }).map((h) => h.textContent))
.toEqual(expect.arrayContaining(["빈 화면", "복구 가능한 오류"]));
// Access states sit directly under the section's h2.
expect(
screen.queryAllByRole("heading", { level: 2 }).map((h) => h.textContent),
).toEqual(["비동기 데이터 상태", "접근과 탐색 상태"]);
});
});
+79 -20
View File
@@ -1,7 +1,11 @@
import { appendFile, readFile } from "node:fs/promises";
import path from "node:path";
import { ROUTE_REGISTRY } from "../../src/features/installed-feature-contracts.ts";
import type { RouteDefinition } from "../../src/contracts/routes.ts";
import {
ROUTE_REGISTRY,
ROUTE_RUNTIME_CONTRACT,
} from "../../src/features/installed-feature-contracts.ts";
import { expect, test } from "../support/browser/strict-browser-test.ts";
import {
prepareFixtureBuilds,
@@ -19,11 +23,60 @@ import { startBuildServer } from "./support/service-worker-builds.ts";
* recovery failure instead.
*/
const PLATFORM = ROUTE_REGISTRY.EXAMPLES_PLATFORM;
const UI = ROUTE_REGISTRY.EXAMPLES_UI;
const PLATFORM_PAGE = "src/presentation/examples/platform-overview-page.tsx";
const UI_PAGE = "src/presentation/examples/ui-gallery-page.tsx";
const PAGES = [PLATFORM_PAGE, UI_PAGE] as const;
// 1103/09-04. The platform overview is a platform route; the UI gallery is
// a feature route now, reached through its context gateway. Route ids only:
// the page sources are read from build A's Vite manifest, so this spec names
// no feature folder.
const installedRoutes: Readonly<Record<string, RouteDefinition>> = ROUTE_REGISTRY;
const runtimeContracts: Readonly<Record<string, { moduleId: string }>> =
ROUTE_RUNTIME_CONTRACT;
function installedRoute(routeId: string): RouteDefinition {
const definition = installedRoutes[routeId];
if (!definition) throw new Error(`${routeId} is not installed.`);
return definition;
}
const PLATFORM = installedRoute("EXAMPLES_PLATFORM");
const UI = installedRoute("EXAMPLES_UI");
type ViteManifest = Record<
string,
{
file: string;
name?: string;
isDynamicEntry?: boolean;
imports?: string[];
dynamicImports?: string[];
}
>;
async function viteManifest(dist: string): Promise<ViteManifest> {
return JSON.parse(
await readFile(path.join(dist, ".vite/manifest.json"), "utf8"),
) as ViteManifest;
}
/** The source of a route's page: the dynamic entry named by its module id. */
function pageSource(manifest: ViteManifest, route: RouteDefinition): string {
const moduleId = runtimeContracts[route.routeId]?.moduleId;
const sources = Object.entries(manifest)
.filter(([, entry]) => entry.isDynamicEntry && entry.name === moduleId)
.map(([source]) => source);
if (sources.length !== 1) {
throw new Error(`Expected one page chunk for ${route.routeId}: ${sources.join(", ")}`);
}
return sources[0]!;
}
/** The context routes module that lazy-loads `page`. */
function routesSource(manifest: ViteManifest, page: string): string {
const sources = Object.entries(manifest)
.filter(([, entry]) => entry.isDynamicEntry && entry.dynamicImports?.includes(page))
.map(([source]) => source);
if (sources.length !== 1) {
throw new Error(`Expected one routes module for ${page}: ${sources.join(", ")}`);
}
return sources[0]!;
}
let builds: FixtureBuilds<"a" | "b"> | undefined;
@@ -34,9 +87,10 @@ test.beforeAll(async () => {
{
name: "b",
edit: async (root) => {
for (const page of PAGES) {
const manifest = await viteManifest(path.join(root, "dist-a"));
for (const route of [PLATFORM, UI]) {
await appendFile(
path.join(root, page),
path.join(root, pageSource(manifest, route)),
'\n(globalThis as Record<string, unknown>).__caFixtureBuild = "b";\n',
);
}
@@ -56,11 +110,13 @@ async function routeChunk(dist: string, chunkId: string): Promise<string> {
return `/${manifest.routeChunks[chunkId]}`;
}
// Each missing page chunk fails its request and the dynamic import. Chromium
// may also log the 404 itself (without its URL), Firefox logs the error
// object React caught, and WebKit logs its own import error without the URL.
// Nothing else is allowed, but for the WebKit warning below.
const MISSING_PAGE = String.raw`/assets/(?:platform-overview|ui-gallery)-page-[\w-]+\.js`;
// Each missing chunk fails its request and the dynamic import. Chromium may
// also log the 404 itself (without its URL), Firefox logs the error object
// React caught, and WebKit logs its own import error without the URL. Nothing
// else is allowed, but for the WebKit warning below. 1103/09-04: the B tab
// misses the UI gallery's context routes module before its page: that module
// names B's new page chunk, so its hash changed too.
const MISSING_PAGE = String.raw`/assets/(?:platform-overview-page|ui-gallery-page|context-routes)-[\w-]+\.js`;
const MISSING_PAGE_FAILURES = [
String.raw`^requestfailed:GET:${MISSING_PAGE}:`,
String.raw`^console:error:TypeError: Failed to fetch dynamically imported module: http://127\.0\.0\.1:\d+${MISSING_PAGE}$`,
@@ -72,9 +128,7 @@ const MISSING_PAGE_FAILURES = [
/** The chunks Vite preloads with `page`: its static imports in `dist`. */
async function preloadedWith(dist: string, page: string): Promise<string[]> {
const manifest = JSON.parse(
await readFile(path.join(dist, ".vite/manifest.json"), "utf8"),
) as Record<string, { file: string; imports?: string[] }>;
const manifest = await viteManifest(dist);
if (!manifest[page]) throw new Error(`${page} is not in ${dist}'s manifest.`);
const files = new Set<string>();
const pending = [...(manifest[page].imports ?? [])];
@@ -89,10 +143,10 @@ async function preloadedWith(dist: string, page: string): Promise<string[]> {
// WebKit only. Three seconds after a document's load event, WebKit warns once
// for each link-preloaded resource the document has not used yet. Vite
// preloads a page chunk together with the chunks it imports, so a missing page
// preloads a chunk together with the chunks it imports, so a missing chunk
// leaves the chunks preloaded with it unused: in the A tab those of A's
// platform page (the tab is still on A while recovery reads the release
// manifest), in the B tab those of B's UI page. Whether that check runs before
// manifest), in the B tab those of B's context routes module for the UI page. Whether that check runs before
// the reload, or before the test ends, is timing, so the warnings come and go.
// They are the provoked failure's own effect; only those chunks are allowed.
test.use({
@@ -100,9 +154,14 @@ test.use({
const patterns = [...MISSING_PAGE_FAILURES];
if (browserName === "webkit") {
if (!builds) throw new Error("Fixture builds were not prepared.");
const aManifest = await viteManifest(builds.dist.a);
const bManifest = await viteManifest(builds.dist.b);
const files = [
...(await preloadedWith(builds.dist.a, PLATFORM_PAGE)),
...(await preloadedWith(builds.dist.b, UI_PAGE)),
...(await preloadedWith(builds.dist.a, pageSource(aManifest, PLATFORM))),
...(await preloadedWith(
builds.dist.b,
routesSource(bManifest, pageSource(bManifest, UI)),
)),
].map((file) => file.replaceAll(".", String.raw`\.`));
patterns.push(
String.raw`^console:warning:The resource http://127\.0\.0\.1:\d+/(?:${files.join("|")}) was preloaded using link preload but not used within a few seconds from the window's load event\. Please make sure it wasn't preloaded for nothing\.$`,
@@ -0,0 +1,80 @@
// @vitest-environment jsdom
import { render, screen, waitFor } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import { describe, expect, it, vi } from "vitest";
import { createAnonymousSessionAdapter } from "../../../src/adapters/auth/external-session-adapter.ts";
import StateGalleryPage from "../../../src/features/platform-examples-feature/presentation/state-gallery-page.tsx";
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";
/**
* The example screens (`/examples/ui`, `/examples/states`, `/examples/auth`)
* are the template's content, not the platform (0929/10-02). 1103/09-04:
* they are `platform-examples-feature`, and this folder goes with it; the
* platform tests run on the test-only feature's pages and keep passing.
*/
function renderApp(
url: string,
application = createTestApplication(),
) {
window.history.pushState({}, "", url);
return render(
<ApplicationProvider application={application}>
<PreferenceProviders>
<AppRouter />
</PreferenceProviders>
</ApplicationProvider>,
);
}
describe("example pages", () => {
it("reaches the UI gallery from the home page's starter actions", async () => {
const user = userEvent.setup();
renderApp("/");
await user.click(
await screen.findByRole("link", { name: "UI 구성요소 보기" }),
);
await waitFor(() =>
expect(
screen.getByRole("heading", { name: "UI 구성요소", level: 1 }),
).toHaveFocus(),
);
});
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",
createTestApplication({
session: { ...createAnonymousSessionAdapter(), beginSignIn },
}),
);
await user.click(
await screen.findByRole("button", { name: "로그인 시작" }),
);
expect(beginSignIn).toHaveBeenCalledWith("/examples/auth#session");
});
it("nests the state gallery's titles under the card and section around them (08-05)", () => {
render(<StateGalleryPage />);
expect(
screen.getByRole("heading", { name: "아직 표시할 항목이 없습니다.", level: 4 }),
).toBeVisible();
expect(screen.getAllByRole("heading", { level: 3 }).map((h) => h.textContent))
.toEqual(expect.arrayContaining(["빈 화면", "복구 가능한 오류"]));
// Access states sit directly under the section's h2.
expect(
screen.queryAllByRole("heading", { level: 2 }).map((h) => h.textContent),
).toEqual(["비동기 데이터 상태", "접근과 탐색 상태"]);
});
});
@@ -4,12 +4,12 @@ import { render, screen, waitFor, within } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import { describe, expect, it } from "vitest";
import UiGalleryPage from "../../src/presentation/examples/ui-gallery-page.tsx";
import { LocaleProvider } from "../../src/presentation/i18n/index.ts";
import UiGalleryPage from "../../../src/features/platform-examples-feature/presentation/ui-gallery-page.tsx";
import { LocaleProvider } from "../../../src/presentation/i18n/index.ts";
/**
* A starter screen (0929/10-02): `/examples/ui` is template content, so a
* product that replaces it deletes this file with it. The primitives have
* A starter screen (0929/10-02): `/examples/ui` is template content
* (`platform-examples-feature`, 1103/09-04), and this file goes with it. The primitives have
* their own suites; this one checks what the page wires them to — the
* validation rule, the shared notice line and the show/hide state.
*/
+18 -3
View File
@@ -4,7 +4,8 @@ import { createRuntimeAdapters } from "../../src/bootstrap/runtime-adapters.ts";
import { createBrowserMutationIntentFactory } from "../../src/adapters/platform/browser-mutation-intent-factory.ts";
import { createApplication } from "../../src/application/create-application.ts";
import type { ApplicationFeatureId } from "../../src/application/ports/in/application-api.ts";
import { INSTALLED_PRODUCT_FEATURE_IDS } from "../../src/features/installed-product-manifest.ts";
import { loadFeatureRuntime } from "../../src/features/feature-module.ts";
import { INSTALLED_PRODUCT_FEATURE_MODULES } from "../../src/features/installed-product-manifest.ts";
type Runtime = Parameters<typeof createRuntimeAdapters>[0]["runtime"];
type Release = Parameters<typeof createRuntimeAdapters>[0]["release"];
@@ -53,6 +54,20 @@ const release: Release = {
routeChunks: { "route-home": "assets/home.js" },
};
/**
* 1103/09-04. The installed features that contribute an application API. The
* template's example screens call none: loading them
* installs no input.
*/
const API_FEATURE_IDS: readonly string[] = (
await Promise.all(
INSTALLED_PRODUCT_FEATURE_MODULES.map(async (module) =>
(await loadFeatureRuntime(module)).adapters.length > 0 ? [module.id] : [],
),
)
).flat();
describe("runtime adapter composition", () => {
it("creates validated intent and idempotency identities with independent UUID calls", () => {
const randomUUID = vi
@@ -361,7 +376,7 @@ describe("runtime adapter composition", () => {
});
it("gives a feature switched off by FEATURE_OVERRIDES no application API (Q-6.9-5)", async () => {
const [disabledId, ...activeIds] = INSTALLED_PRODUCT_FEATURE_IDS;
const [disabledId, ...activeIds] = API_FEATURE_IDS;
const adapters = await createRuntimeAdapters({
runtime: {
...runtime,
@@ -401,7 +416,7 @@ describe("runtime adapter composition", () => {
adapters.featureLoaders,
);
for (const featureId of INSTALLED_PRODUCT_FEATURE_IDS) {
for (const featureId of API_FEATURE_IDS) {
// 15-01. Not loaded until the router asks for the feature's routes.
expect(() =>
application.features.get(featureId as ApplicationFeatureId),