chore(features): 참조 기능과 예제 화면을 지우고 레지스트리를 다시 승인한다

소유자 결정(2026-11-07, design-docs repo-structure/README.md 3.4절)으로
템플릿 샘플을 지운다. 샘플이 맡던 시험 대상은 앞 커밋들이 옮겼다.

참조 기능과 예제 화면, 두 context, 그 시험, e2e 3개, 수동 접근성 기록
7개, 런타임 프로필 키, test:reference-feature(명령, 산출물, 게이트
참조), 커버리지 정책 행을 지웠다. removable-template-features 목록은
비우고 장치는 남겼다: test:sample-removal은 인자가 없으면 목록을
하나씩 지우고, 비면 SKIP을 출력하고 보고서에 건너뛴 사례를 남긴다.
기능 스위치 시험과 홈 시작 링크 스위치 시험은 시험 전용 fixture 기능으로
옮겼다. browser soak은 생성 기능을 넣은 빌드에서 돈다. 문서의 샘플
경로를 고쳤다. 날짜가 붙은 설계·리뷰 기록의 본문은 그대로 두었다.
레지스트리 기준선(update:registry-baseline, OWNER DongHyeonka), CI 계약
기준선과 workflow, 초기 JS 기록(194,354B, 17파일, 첫 기능 6,327B, 기능
539B, context 4B)을 다시 받았다.

위험: 레지스트리 행 삭제는 breaking이다. 샘플을 고쳐 쓰는 다운스트림은
수정/삭제 충돌을 만난다. 성능 lab의 기능 라우트 측정은 템플릿에
공개 기능 라우트가 없어 measured:false다. TEMPLATE_FIXTURE 출처는
플랫폼 코드에 남았다.

검증(desktop): check:types, lint, check:architecture, check:registries,
check:ci, verify:documentation, test:unit, test:component,
test:contract, test:integration, test:recipes, test:coverage(Risk
coverage PASS 378/378, 문턱 68개), test:e2e 183, test:a11y, test:visual,
test:storybook, test:browser-capabilities, test:feature-scaffold PASS(76
checks), test:sample-removal SKIP, build, check:bundle.
This commit is contained in:
DongHyeonka
2026-11-08 14:07:58 +09:00
parent b2042de9be
commit e3c8db48ae
126 changed files with 630 additions and 7607 deletions
@@ -1,12 +0,0 @@
/**
* 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/*`; the sample
* feature's own context keeps a more specific path below it.
*/
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;
@@ -1,10 +0,0 @@
/**
* Ownership declaration of the reference bounded context (the rules are in
* docs/architecture/starter-experience.md, "Ownership declarations"): the app
* that owns it, its route root, and its direct-feature budget. Features name
* this id as their owner.
*/
export const CONTEXT_MODULE_ID = "reference-context";
export const CONTEXT_APP_ID = "template-app";
export const CONTEXT_ROUTE_PATH = "examples/reference-resources/*";
export const CONTEXT_MAX_FEATURES = 200;
@@ -1,17 +0,0 @@
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],
}),
}),
),
);
@@ -1,82 +0,0 @@
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);
@@ -1,23 +0,0 @@
/**
* 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);
@@ -1,27 +0,0 @@
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;
@@ -1,13 +0,0 @@
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,61 +0,0 @@
import { PageHeader } from "../../../presentation/design-system/index.ts";
import {
useSession,
useSessionAction,
} from "../../../presentation/providers/session-provider.tsx";
export default function AuthExamplePage() {
const { sessionState } = useSession();
const { pending, failed, run } = useSessionAction();
return (
// 08-07. Example copy is Korean in every locale (outside the catalog).
<section className="ui-page" lang="ko-KR">
<PageHeader
title="인증 연동"
description="스켈레톤은 자격 증명을 소유하지 않고 외부 인증 구현이 연결될 포트와 화면 상태만 제공합니다."
/>
<section className="ui-panel auth-example" aria-labelledby="auth-state-title">
<div>
<h2 id="auth-state-title">현재 세션 상태</h2>
<output className="session-status" data-state={sessionState}>
{sessionState}
</output>
</div>
<div className="button-row">
<button
className="ui-button"
type="button"
disabled={pending || sessionState === "integration-failed"}
onClick={() => run("sign-in")}
>
로그인 시작
</button>
<button
className="ui-button ui-button--secondary"
type="button"
disabled={pending || sessionState !== "authenticated"}
onClick={() => run("sign-out")}
>
로그아웃
</button>
<button
className="ui-button ui-button--secondary"
type="button"
disabled={pending || sessionState !== "recovery-pending"}
onClick={() => run("recover")}
>
세션 복구
</button>
</div>
{sessionState === "integration-failed" ? (
<p role="status">
외부 인증 소유자가 연결되지 않았습니다. 런타임 호스트의 인증
계약을 연결하세요.
</p>
) : null}
{failed ? <p role="alert">인증 작업을 완료하지 못했습니다.</p> : null}
</section>
</section>
);
}
@@ -1,17 +0,0 @@
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,101 +0,0 @@
import { useState } from "react";
import { deriveAsyncState } from "../../../application/view-models/async-state.ts";
import { createFailure } from "../../../contracts/errors.ts";
import {
AsyncSurface,
EmptySurface,
LoadingSurface,
TerminalErrorSurface,
AuthRequiredSurface,
ForbiddenSurface,
NotFoundSurface,
Button,
Card,
PageHeader,
} from "../../../presentation/design-system/index.ts";
export default function StateGalleryPage() {
const [lastAction, setLastAction] = useState(
"상태 화면의 작업을 선택하면 결과가 여기에 표시됩니다.",
);
const refreshingState = deriveAsyncState({
data: ["기존 데이터"],
isFetching: true,
});
return (
// 08-07. Example copy is Korean in every locale (outside the catalog).
<section className="ui-page" lang="ko-KR">
<PageHeader
title="화면 상태"
description="로딩, 빈 화면, 오류, 인증 필요와 권한 없음 상태가 다음 행동까지 일관되게 안내합니다."
/>
<section className="gallery-section" aria-labelledby="async-states-title">
<header className="gallery-section__header">
<h2 id="async-states-title">비동기 데이터 상태</h2>
<p>초기 로딩과 백그라운드 갱신을 구분해 기존 콘텐츠를 보존합니다.</p>
</header>
<div className="component-grid component-grid--two">
<Card title="초기 로딩">
<LoadingSurface label="예제 데이터를 불러오는 중" />
</Card>
<Card title="백그라운드 갱신">
<AsyncSurface headingLevel={4} state={refreshingState}>
<div className="state-preview-content">기존 콘텐츠는 계속 표시됩니다.</div>
</AsyncSurface>
</Card>
<Card title="빈 화면">
<EmptySurface
headingLevel={4}
title="아직 표시할 항목이 없습니다."
description="첫 항목을 추가하거나 필터를 초기화할 수 있습니다."
action={
<Button onClick={() => setLastAction("빈 화면 작업을 실행했습니다.")}>
첫 작업 시작
</Button>
}
/>
</Card>
<Card title="복구 가능한 오류">
<TerminalErrorSurface
headingLevel={4}
userMessageKey={
createFailure("NETWORK_UNREACHABLE", "EXAMPLE", 0)
.userMessageKey
}
action="retry"
onAction={() => setLastAction("오류 요청을 다시 시도했습니다.")}
/>
</Card>
</div>
</section>
<section className="gallery-section" aria-labelledby="access-states-title">
<header className="gallery-section__header">
<h2 id="access-states-title">접근과 탐색 상태</h2>
<p>인증 여부와 서버 권한 결과를 서로 다른 상태로 전달합니다.</p>
</header>
<div className="component-grid component-grid--three">
<AuthRequiredSurface
headingLevel={3}
onSignIn={() => setLastAction("로그인 연동 작업을 시작했습니다.")}
/>
<ForbiddenSurface
headingLevel={3}
onNavigate={() => setLastAction("접근 가능한 화면으로 이동합니다.")}
/>
<NotFoundSurface
headingLevel={3}
onNavigate={() => setLastAction("시작 화면으로 이동합니다.")}
/>
</div>
</section>
<output className="gallery-notice" aria-live="polite">
{lastAction}
</output>
</section>
);
}
@@ -1,318 +0,0 @@
import { useState, type FormEvent } from "react";
import {
Alert,
Badge,
Button,
Card,
Checkbox,
Dialog,
Menu,
PageHeader,
ProgressBar,
RadioGroup,
Select,
Switch,
Tabs,
TextArea,
TextField,
ToastProvider,
Tooltip,
useToast,
} from "../../../presentation/design-system/index.ts";
const COLOR_TOKENS = Object.freeze([
["Surface", "--color-surface"],
["Muted surface", "--color-surface-muted"],
["Content", "--color-content"],
["Muted content", "--color-content-muted"],
["Action", "--color-action"],
["Danger", "--color-danger"],
["Focus", "--color-focus"],
]);
export default function UiGalleryPage() {
return (
<ToastProvider>
<UiGalleryContent />
</ToastProvider>
);
}
function UiGalleryContent() {
const toast = useToast();
const [projectName, setProjectName] = useState("");
const [description, setDescription] = useState("");
const [template, setTemplate] = useState("application");
const [reviewed, setReviewed] = useState(false);
const [notifications, setNotifications] = useState(true);
const [density, setDensity] = useState("comfortable");
const [fieldTouched, setFieldTouched] = useState(false);
const [dialogOpen, setDialogOpen] = useState(false);
const [notice, setNotice] = useState(
"구성요소를 조작하면 결과가 여기에 표시됩니다.",
);
const [alertVisible, setAlertVisible] = useState(true);
const fieldError =
fieldTouched && projectName.trim().length === 0
? "프로젝트 이름을 입력해 주세요."
: undefined;
function submitExample(event: FormEvent<HTMLFormElement>): void {
event.preventDefault();
setFieldTouched(true);
if (projectName.trim().length === 0) {
setNotice("입력값을 확인해 주세요.");
return;
}
setNotice(`“${projectName.trim()}” 입력을 확인했습니다.`);
}
return (
// 08-07. Example copy is Korean in every locale (outside the catalog).
<section className="ui-page" lang="ko-KR">
<PageHeader
title="UI 구성요소"
description="제품 도메인과 독립적인 공통 컨트롤, 피드백, 표면과 디자인 토큰을 직접 조작할 수 있습니다."
/>
<section className="gallery-section" aria-labelledby="controls-title">
<header className="gallery-section__header">
<h2 id="controls-title">버튼과 입력</h2>
<p>키보드, 비활성 상태, 오류 설명을 포함한 기본 상호작용입니다.</p>
</header>
<div className="component-grid component-grid--two">
<Card title="버튼" description="의미와 위험도에 따라 변형을 선택합니다.">
<div className="button-row">
<Button onClick={() => setNotice("기본 작업을 실행했습니다.")}>
기본 작업
</Button>
<Button
variant="secondary"
onClick={() => setNotice("보조 작업을 실행했습니다.")}
>
보조 작업
</Button>
<Button
variant="danger"
onClick={() => setNotice("위험 작업 예제를 선택했습니다.")}
>
위험 작업
</Button>
<Button disabled>사용 불가</Button>
</div>
</Card>
<Card title="입력창" description="레이블과 도움말, 오류가 입력에 연결됩니다.">
<form className="example-form" noValidate onSubmit={submitExample}>
<TextField
label="프로젝트 이름"
description="새 도메인을 연결할 때 사용할 중립적인 예제입니다."
error={fieldError}
value={projectName}
required
onChange={(event) => setProjectName(event.currentTarget.value)}
/>
<Button type="submit">입력 확인</Button>
</form>
</Card>
</div>
</section>
<section className="gallery-section" aria-labelledby="form-controls-title">
<header className="gallery-section__header">
<h2 id="form-controls-title">폼과 선택 컨트롤</h2>
<p>native semantics, 설명·오류 연결과 controlled 상태를 제공합니다.</p>
</header>
<div className="component-grid component-grid--two">
<Card title="긴 입력과 선택">
<div className="component-stack">
<TextArea
label="설명"
maxLength={120}
value={description}
onChange={(event) => setDescription(event.currentTarget.value)}
/>
<Select
label="시작 템플릿"
options={[
{ value: "application", label: "Application" },
{ value: "library", label: "Library" },
]}
value={template}
onChange={(event) => setTemplate(event.currentTarget.value)}
/>
<Checkbox
checked={reviewed}
label="접근성 계약을 확인했습니다."
onChange={(event) => setReviewed(event.currentTarget.checked)}
/>
</div>
</Card>
<Card title="단일 선택과 설정">
<div className="component-stack">
<RadioGroup
label="화면 밀도"
name="density"
onChange={setDensity}
options={[
{ value: "comfortable", label: "여유롭게" },
{ value: "compact", label: "조밀하게" },
]}
value={density}
/>
<Switch
checked={notifications}
description="boolean 설정에만 switch를 사용합니다."
label="알림 사용"
onChange={setNotifications}
/>
<ProgressBar label="설정 준비도" max={4} value={3} />
</div>
</Card>
</div>
</section>
<section className="gallery-section" aria-labelledby="feedback-title">
<header className="gallery-section__header">
<h2 id="feedback-title">피드백과 모달</h2>
<p>상태 전달은 색에만 의존하지 않으며, 모든 제어에는 이름이 있습니다.</p>
</header>
<div className="component-grid component-grid--two">
<Card title="알림과 배지" description="짧은 상태와 문맥형 피드백입니다.">
<div className="component-stack">
{alertVisible ? (
<Alert
title="설정이 저장되었습니다."
variant="success"
onDismiss={() => setAlertVisible(false)}
>
<p>운영 환경에는 실제 저장 포트를 연결하세요.</p>
</Alert>
) : (
<Button
variant="secondary"
onClick={() => setAlertVisible(true)}
>
알림 다시 표시
</Button>
)}
<div className="badge-row" aria-label="배지 변형">
<Badge>중립</Badge>
<Badge variant="info">정보</Badge>
<Badge variant="success">준비됨</Badge>
<Badge variant="warning">확인 필요</Badge>
<Badge variant="danger">실패</Badge>
</div>
</div>
</Card>
<Card title="모달" description="배경과 키보드 Esc로 닫고 포커스를 복원합니다.">
<div className="button-row">
<Button onClick={() => setDialogOpen(true)}>모달 열기</Button>
<Menu
items={[
{
id: "inspect",
label: "상태 확인",
onSelect: () => setNotice("메뉴 작업을 실행했습니다."),
},
{
id: "notify",
label: "Toast 표시",
onSelect: () =>
toast.push({
id: "gallery-saved",
title: "예제가 저장되었습니다.",
tone: "success",
}),
},
]}
triggerLabel="작업 메뉴"
/>
<Tooltip content="이 설명은 필수 정보가 아닙니다.">
<Button variant="ghost">도움말</Button>
</Tooltip>
</div>
<Dialog
open={dialogOpen}
onClose={() => setDialogOpen(false)}
title="연동 확인"
description="도메인 작업을 실행하기 전 확인 화면의 기본 구조입니다."
actions={
<>
<Button
variant="secondary"
onClick={() => setDialogOpen(false)}
>
취소
</Button>
<Button
onClick={() => {
setNotice("모달의 확인 작업을 실행했습니다.");
setDialogOpen(false);
}}
>
확인
</Button>
</>
}
>
<p>민감한 값이나 구현 세부정보는 확인 문구에 포함하지 않습니다.</p>
</Dialog>
</Card>
</div>
</section>
<section className="gallery-section" aria-labelledby="navigation-title">
<header className="gallery-section__header">
<h2 id="navigation-title">탐색 패턴</h2>
<p>화살표 키와 명시적인 활성화 정책을 갖는 탭 예제입니다.</p>
</header>
<Tabs
activation="manual"
label="디자인 시스템 계층"
tabs={[
{
id: "tokens",
label: "토큰",
panel: <p>원시 값에서 의미와 컴포넌트 토큰을 파생합니다.</p>,
},
{
id: "primitives",
label: "프리미티브",
panel: <p>native semantics와 interaction을 닫습니다.</p>,
},
{
id: "patterns",
label: "패턴",
panel: <p>반복되는 사용자 문제를 조합으로 해결합니다.</p>,
},
]}
/>
</section>
<section className="gallery-section" aria-labelledby="tokens-title">
<header className="gallery-section__header">
<h2 id="tokens-title">디자인 토큰</h2>
<p>구성요소가 사용하는 의미 기반 색상과 형태 토큰입니다.</p>
</header>
<div className="token-grid">
{COLOR_TOKENS.map(([label, token]) => (
<article className="token-swatch" key={token}>
<span
className="token-swatch__color"
style={{ backgroundColor: `var(${token})` }}
aria-hidden="true"
/>
<strong>{label}</strong>
<code>{token}</code>
</article>
))}
</div>
</section>
<output className="gallery-notice" aria-live="polite">
{notice}
</output>
</section>
);
}
-92
View File
@@ -1,92 +0,0 @@
# Reference feature ownership and removal
이 모듈은 제품 도메인이 아니라 새 기능의 수직 경계를 검증하는 제거 가능한
reference implementation이다.
## 소유 경계
- `domain`: 외부 DTO와 React를 모르는 불변 model
- `application`: UI가 호출하는 list/get/create input과 gateway 계약
- `adapters`: HTTP executor를 gateway로 투영하는 outbound adapter
- `contracts`: route/API/query contribution, Zod DTO와 request schema, mapper
- `presentation`: route input을 query/form controller로 연결하는 inbound
adapter, 독립 form schema/command mapper와 list/detail/form/status page
generic application은 비어 있는 `ApplicationFeatureInputs`와 typed
`features.has/get/load` registry만 소유한다. input은 reference route에 처음
들어갈 때 router가 `features.load`로 실행부를 적재한 뒤에 생긴다. 이 feature의 application API가 module
augmentation으로 `"reference-feature": ReferenceFeatureInput`을 기여하므로
등록되지 않은 ID와 잘못된 input shape는 typecheck에서 거절된다. feature hook은
별도 cast나 runtime shape 확인 없이 정확한 input type을 받는다. 다만 동적 호출로
설치되지 않은 ID가 들어오는 경우를 위해 `get`의 runtime guard도 유지한다.
예측 가능한 실패는 canonical shared contract인
`src/contracts/result.ts`의 `Result<Value, Failure = AppFailure>`로 반환한다.
`src/application/result.ts`는 기존 호출자를 위한 deprecated migration shim일
뿐 새 코드의 import 경로가 아니다. `AppFailure.kind`는
`ERROR_REGISTRY` key에서 파생된 닫힌 vocabulary다. 폐기된 별칭 `ApiFailure`
대신 `AppFailure`를 import한다(lint가 막는다). mapper는 `boundary-mapper.ts`의
`BoundaryMappingResult`를 반환한다.
HTTP adapter는 `src/adapters/http/feature-http-binding.ts`의 capability-specific
typed binding을 사용한다. feature는 operation ID, route ID, request type, 성공
value type, mapper만 소유한다. timeout/cancellation/auth/transport/contract
violation을 `AppFailure`로 정규화하는 책임은 reusable HTTP capability가 소유한다.
따라서 gateway 메서드는 transport outcome이나 runtime result guard를 반복 구현하지
않고도 정확한 결과 타입을 반환한다.
route codec과 URL builder는 `src/presentation/routes/route-codecs.ts`, route type은
`route-contract.ts`, React context/provider/hook은 `route-input.tsx`가 각각
소유한다. reference page는 `app-router.tsx`를 역참조하지 않고 좁은
`useRouteInput` 경계만 사용하므로 lazy route와 router 사이의 순환 의존을 만들지
않는다. page는 HTTP client, storage, auth owner, output port나 TanStack API를
직접 import하지 않는다.
page는 경로 문자열을 적지 않는다. 경로는 계약의 `path` 한 곳에만 있다.
`presentation/reference-routes.ts`가 다음 helper를 둔다. 이 기능의 route codec은
`presentation/reference-route-codecs.ts`에 있다.
- 링크: `referenceRouteUrl(routeId, { params, search })`. 위 `buildRouteUrl`에
이 기능의 codec을 넘긴다.
- route 입력: `useReferenceListFilters()`, `useReferenceResourceId()`. 이미
통과한 codec으로 다시 읽어 cast 없이 타입을 얻는다.
## 설치 지점
feature가 실제 contribution을 소유한다.
- 선언(초기 청크, `feature-module.ts`): route 표와 invalidation은
`reference-feature-contract.ts`, 문구는 `reference-message-catalog.ts`
- 실행부(`feature-runtime.ts`, reference route에 들어갈 때 적재): 스키마 메타데이터
`reference-schema-metadata.ts`, bootstrap input
`REFERENCE_FEATURE_ADAPTER_CONTRIBUTION`, HTTP contract contribution
- route codec과 page component: `REFERENCE_FEATURE_ROUTE_CODECS`,
`REFERENCE_FEATURE_ROUTE_RUNTIME` (`context-routes.ts`가 route handle에 실어
lazy로 적재)
`feature-module.ts`는 `feature-runtime.ts`를 동적 import로만 가리킨다. 정적
import로 바꾸면 실행부 전체가 다시 초기 청크에 들어간다(15-01). 중앙 파일인
`installed-feature-contracts.ts`, `installed-feature-adapters.ts`,
`installed-contract-contributions.ts`는 선택된 contribution을 합치는 역할만
한다. 새 기능의 내부 조립 규칙을 중앙 catalog에 추가하지 않는다.
## 검증과 제거
```sh
corepack pnpm test:reference-feature
corepack pnpm test:sample-removal
```
첫 명령은 URL filter와 query key/HTTP request의 동일성, schema/mapper, 모든
query/mutation/form 상태와 production composition을 검증한다. 두 번째 명령은 임시
복제본에서 이 source/test 디렉터리를 제거하고 installed catalog를 빈 목록으로
재생성한다. feature 소유 coverage include, risk-policy 행과 test-evidence
contribution도 제거한 뒤 typecheck, architecture, registry, unit/integration,
coverage, source evidence, home smoke, production build와 source/built fixture ID
잔여 0개를 검사한다. generic feature registry의 성공 경로는 reference와 무관한
unit test가 소유하므로 feature 삭제 후에도 공통 boundary coverage가 유지된다.
CI의 negative type fixture는 잘못된 feature ID/input shape, registry에 없는
failure kind, operation과 route ID의 불일치가 실제로 컴파일 실패하는지도
검증한다. Architecture fixture는 허용 edge뿐 아니라 unresolved import, 금지 계층
edge와 TypeScript 순환 의존을 각각 거절해야 통과한다.
@@ -1,50 +0,0 @@
import {
createFeatureHttpBinding,
type InstalledHttpOperationExecutor,
} from "../../../adapters/http/index.ts";
import {
defineFeatureAdapterContribution,
} from "../../feature-adapter-contribution.ts";
import { createReferenceFeatureInput } from "../application/reference-feature-api.ts";
import type { TelemetryPort } from "../../../platform/telemetry/telemetry-port.ts";
import {
REFERENCE_FEATURE_ID,
} from "../contracts/reference-feature-contract.ts";
import {
createReferenceHttpGateway,
REFERENCE_HTTP_OPERATIONS,
} from "./reference-http-gateway.ts";
export type InstalledContractOperationExecutor =
InstalledHttpOperationExecutor;
/**
* Feature-owned composition seam.
*
* The feature receives only the HTTP capability it declares in `needs`.
* HTTP lifecycle/error normalization stays in the reusable capability binding.
*/
export function createReferenceFeatureInstalledInput(context: Readonly<{
http: InstalledHttpOperationExecutor;
telemetry?: TelemetryPort;
}>) {
const http = createFeatureHttpBinding(
context.http,
REFERENCE_HTTP_OPERATIONS,
);
return Object.freeze({
featureId: REFERENCE_FEATURE_ID,
input: createReferenceFeatureInput(
createReferenceHttpGateway(http),
context.telemetry === undefined ? {} : { telemetry: context.telemetry },
),
});
}
export const REFERENCE_FEATURE_ADAPTER_CONTRIBUTION =
defineFeatureAdapterContribution({
featureId: REFERENCE_FEATURE_ID,
needs: ["http", "telemetry"] as const,
createInput: createReferenceFeatureInstalledInput,
});
@@ -1,92 +0,0 @@
import {
defineFeatureHttpOperationForRoutes,
type FeatureHttpBinding,
} from "../../../adapters/http/index.ts";
import {
CREATE_REFERENCE_RESOURCE_CONTRACT,
GET_REFERENCE_RESOURCE_CONTRACT,
LIST_REFERENCE_RESOURCES_CONTRACT,
} from "../contracts/reference-feature-contract-contribution.ts";
import {
REFERENCE_FEATURE_CONTRACT,
} from "../contracts/reference-feature-contract.ts";
import {
mapReferenceResourceListPayload,
mapReferenceResourcePayload,
} from "../contracts/reference-mapper.ts";
import type {
ReferenceGateway,
} from "../application/reference-feature-api.ts";
export type ReferenceFeatureRouteId =
keyof typeof REFERENCE_FEATURE_CONTRACT.routes;
const defineReferenceHttpOperation =
defineFeatureHttpOperationForRoutes<ReferenceFeatureRouteId>();
export const REFERENCE_HTTP_OPERATIONS = Object.freeze({
LIST_REFERENCE_RESOURCES: defineReferenceHttpOperation({
contract: LIST_REFERENCE_RESOURCES_CONTRACT,
routeId: "REFERENCE_RESOURCE_LIST",
mapSuccess: mapReferenceResourceListPayload,
}),
CREATE_REFERENCE_RESOURCE: defineReferenceHttpOperation({
contract: CREATE_REFERENCE_RESOURCE_CONTRACT,
routeId: "REFERENCE_RESOURCE_LIST",
mapSuccess: mapReferenceResourcePayload,
mapProblem(problem, metadata) {
if (metadata.status === 409) {
return Object.freeze({
kind: "CONFLICT" as const,
code: problem.code ?? "REFERENCE_RESOURCE_CONFLICT",
});
}
// 백엔드 1101/02-01. The paired backend's answer to a key outside its
// rule. The executor checked the key before sending, so this names a
// rule mismatch between the two sides: keep the code for diagnostics.
if (metadata.status === 400 && problem.code === "IDEMPOTENCY_KEY_INVALID") {
return Object.freeze({
kind: "UNKNOWN_CLIENT_FAILURE" as const,
code: problem.code,
});
}
if (metadata.status === 422) {
return Object.freeze({
kind: "VALIDATION_REJECTED" as const,
code: problem.code ?? "REFERENCE_RESOURCE_REJECTED",
validationIssues: problem.issues ?? [],
});
}
return undefined;
},
}),
GET_REFERENCE_RESOURCE: defineReferenceHttpOperation({
contract: GET_REFERENCE_RESOURCE_CONTRACT,
routeId: "REFERENCE_RESOURCE_DETAIL",
mapSuccess: mapReferenceResourcePayload,
}),
} as const);
export type ReferenceHttpBinding = FeatureHttpBinding<
typeof REFERENCE_HTTP_OPERATIONS
>;
export function createReferenceHttpGateway(
http: ReferenceHttpBinding,
): ReferenceGateway {
return Object.freeze({
list(filters, context) {
return http.execute("LIST_REFERENCE_RESOURCES", filters, context);
},
create(command, context) {
return http.execute("CREATE_REFERENCE_RESOURCE", command, context);
},
get(resourceId, context) {
return http.execute(
"GET_REFERENCE_RESOURCE",
Object.freeze({ resourceId }),
context,
);
},
});
}
@@ -1,71 +0,0 @@
import {
defineAppError,
type AppError,
} from "../../../platform/errors/app-error.ts";
import type { AppFailure } from "../../../contracts/errors.ts";
/**
* scale-architecture.md §17–§19. The reference feature's own domain errors.
*
* This union is local to the feature. It satisfies the platform `AppError`
* envelope structurally; nothing central enumerates it, so adding or removing
* this feature never edits a shared error type.
*/
export type ReferenceError =
| (AppError & {
readonly kind: "reference.not-found";
readonly category: "domain";
readonly severity: "warning";
readonly retryability: "never";
})
| (AppError & {
readonly kind: "reference.conflict";
readonly category: "domain";
readonly severity: "warning";
readonly retryability: "never";
})
| (AppError & {
readonly kind: "reference.rejected";
readonly category: "validation";
readonly severity: "warning";
readonly retryability: "never";
});
export const REFERENCE_ERRORS = Object.freeze({
NOT_FOUND: defineAppError({
kind: "reference.not-found",
category: "domain",
severity: "warning",
retryability: "never",
}),
CONFLICT: defineAppError({
kind: "reference.conflict",
category: "domain",
severity: "warning",
retryability: "never",
}),
REJECTED: defineAppError({
kind: "reference.rejected",
category: "validation",
severity: "warning",
retryability: "never",
}),
} satisfies Record<string, ReferenceError>);
/**
* Interprets a transport-normalized failure in this feature's own vocabulary.
* Anything that is not a reference domain outcome stays `null`: the platform
* error mapping, not this feature, owns transport/contract failures.
*/
export function toReferenceError(failure: AppFailure): ReferenceError | null {
switch (failure.kind) {
case "NOT_FOUND":
return REFERENCE_ERRORS.NOT_FOUND;
case "CONFLICT":
return REFERENCE_ERRORS.CONFLICT;
case "VALIDATION_REJECTED":
return REFERENCE_ERRORS.REJECTED;
default:
return null;
}
}
@@ -1,137 +0,0 @@
import type { Result } from "../../../contracts/result.ts";
import type {} from "../../../application/ports/in/application-api.ts";
import {
toReferenceView,
type ReferenceResourceView,
} from "../contracts/reference-mapper.ts";
import type { ReferenceResource } from "../domain/reference-resource.ts";
import type { MutationIntent } from "../../../contracts/mutation-intent.ts";
import type { ExecutionContext } from "../../../platform/execution/execution-context.ts";
import type { TelemetryPort } from "../../../platform/telemetry/telemetry-port.ts";
import type { AppFailure } from "../../../contracts/errors.ts";
import { REFERENCE_FEATURE_ID } from "../contracts/reference-feature-contract.ts";
/**
* scale-architecture.md §10. Every call may join a caller-owned interaction so several
* operations share one request/retry/concurrency budget and one deadline.
*/
export type ReferenceCallContext = Readonly<{
signal?: AbortSignal;
execution?: ExecutionContext;
}>;
export type ReferenceListFilters = Readonly<{
cursor?: string;
limit: number;
tags?: readonly string[];
}>;
export type ReferenceResult<Value> = Result<Value>;
export type ReferenceCreateCommand = Readonly<{
name: string;
note?: string;
}>;
export type ReferenceFeatureInput = Readonly<{
listResources(
filters: ReferenceListFilters,
context?: ReferenceCallContext,
): Promise<ReferenceResult<readonly ReferenceResourceView[]>>;
createResource(
command: ReferenceCreateCommand,
context?: ReferenceCallContext & Readonly<{ intent?: MutationIntent }>,
): Promise<ReferenceResult<ReferenceResourceView>>;
getResource(
resourceId: string,
context?: ReferenceCallContext,
): Promise<ReferenceResult<ReferenceResourceView>>;
}>;
declare module "../../../application/ports/in/application-api.ts" {
interface ApplicationFeatureInputs {
"reference-feature": ReferenceFeatureInput;
}
}
export type ReferenceGateway = Readonly<{
list(
filters: ReferenceListFilters,
context?: ReferenceCallContext,
): Promise<ReferenceResult<readonly ReferenceResource[]>>;
create(
command: ReferenceCreateCommand,
context?: ReferenceCallContext & Readonly<{ intent?: MutationIntent }>,
): Promise<ReferenceResult<ReferenceResource>>;
get(
resourceId: string,
context?: ReferenceCallContext,
): Promise<ReferenceResult<ReferenceResource>>;
}>;
/**
* scale-architecture.md §24. Feature-owned telemetry payload. The platform envelope carries it;
* no central union lists it. Only the bounded failure kind leaves the feature.
*/
export type ReferenceLoadFailedPayload = Readonly<{
operation: "list" | "detail";
reason: AppFailure["kind"];
}>;
function reportLoadFailure(
telemetry: TelemetryPort | undefined,
operation: ReferenceLoadFailedPayload["operation"],
failure: AppFailure,
context: ReferenceCallContext | undefined,
): void {
if (!telemetry || failure.kind === "REQUEST_ABORTED") return;
const payload: ReferenceLoadFailedPayload = { operation, reason: failure.kind };
try {
// Fire-and-forget: telemetry never changes the business result.
void Promise.resolve(
telemetry.emit({
kind: "reference.load.failed",
severity: "warning",
featureId: REFERENCE_FEATURE_ID,
...(context?.execution === undefined
? {}
: { interactionId: context.execution.interaction.id }),
payload,
}),
).catch(() => undefined);
} catch {
// A throwing port is contained at the call site (scale-architecture.md §26).
}
}
export function createReferenceFeatureInput(
gateway: ReferenceGateway,
observability: Readonly<{ telemetry?: TelemetryPort }> = {},
): ReferenceFeatureInput {
const { telemetry } = observability;
return Object.freeze({
async listResources(filters, context) {
const result = await gateway.list(filters, context);
if (!result.ok) reportLoadFailure(telemetry, "list", result.error, context);
return result.ok
? {
ok: true as const,
value: result.value.map((resource) => toReferenceView(resource)),
}
: result;
},
async createResource(command, context) {
const result = await gateway.create(command, context);
return result.ok
? { ok: true as const, value: toReferenceView(result.value) }
: result;
},
async getResource(resourceId, context) {
const result = await gateway.get(resourceId, context);
if (!result.ok) reportLoadFailure(telemetry, "detail", result.error, context);
return result.ok
? { ok: true as const, value: toReferenceView(result.value) }
: result;
},
});
}
@@ -1,23 +0,0 @@
import type { RouteObject } from "react-router-dom";
import { REFERENCE_FEATURE_CONTRACT } from "./contracts/reference-feature-contract.ts";
import { REFERENCE_FEATURE_ROUTE_RUNTIME } from "./presentation/reference-feature-runtime.ts";
import { REFERENCE_FEATURE_ROUTE_CODECS } from "./presentation/reference-route-codecs.ts";
export const FEATURE_CONTEXT_ROUTES: readonly RouteObject[] = Object.freeze(
Object.values(REFERENCE_FEATURE_CONTRACT.routes).map((definition) => {
const runtime = REFERENCE_FEATURE_ROUTE_RUNTIME[
definition.routeId as keyof typeof REFERENCE_FEATURE_ROUTE_RUNTIME
];
return Object.freeze({
id: definition.routeId,
path: definition.path,
handle: Object.freeze({
routeId: definition.routeId,
runtime,
// 15-01. The route's params/search codecs load with its routes.
codecs: REFERENCE_FEATURE_ROUTE_CODECS,
}),
});
}),
);
@@ -1,252 +0,0 @@
import { z } from "../../../contracts/zod.ts";
import type {
CommandEffectDescriptor,
InstalledContractContribution,
InstalledHttpContract,
} from "../../../contracts/external-contract-runtime.ts";
import { zodValidator } from "../../../contracts/zod-validator.ts";
import { REFERENCE_FEATURE_ID } from "./reference-feature-contract.ts";
import {
createReferenceResourceCommandSchema,
referenceProblemSchema,
referenceResourceDtoSchema,
referenceResourceListQuerySchema,
referenceResourceParamsSchema,
type ReferenceProblem,
} from "./reference-schemas.ts";
export type { ReferenceProblem } from "./reference-schemas.ts";
/**
* §4.8. The single `TEMPLATE_FIXTURE` contribution. It keeps the reference
* HTTP vertical executable as deterministic template data and is excluded from
* `contractSet`. A product feature MUST instead pin an external package and
* import it from its own `contracts/<service>-contract-contribution.ts`.
*/
const PROBLEM_VALIDATOR = zodValidator(
"ReferenceProblem",
referenceProblemSchema,
);
/**
* 0929/03-01. A 409 does not by itself mean "refused": a resend with the same
* key can meet the first attempt still running (the paired backend answers
* `409 IDEMPOTENT_IN_FLIGHT`). Only the conflict codes this fixture declares
* are `NOT_APPLIED`; any other 409 stays `MAYBE_APPLIED`, so the coordinator
* keeps the intent and the next send reuses the key. Answering `NOT_APPLIED`
* there would let the next save mint a new key and create the resource twice.
*/
const CREATE_NOT_APPLIED_CONFLICT_CODES: ReadonlySet<string> = new Set([
"CONFLICT",
]);
/**
* Fixture-side classifier standing in for the package-provided pure bounded
* classifier. A status the fixture does not describe stays `MAYBE_APPLIED`.
*/
const CREATE_EFFECT: CommandEffectDescriptor<ReferenceProblem> = Object.freeze({
successEffect: "APPLIED_CONFIRMED" as const,
classifyProblem({
status,
problem,
}: Readonly<{ status: number; problem: ReferenceProblem }>) {
if (status === 400 || status === 422) return "NOT_APPLIED";
if (
status === 409 &&
problem.code !== undefined &&
CREATE_NOT_APPLIED_CONFLICT_CODES.has(problem.code)
) {
return "NOT_APPLIED";
}
return "MAYBE_APPLIED";
},
/**
* D-2. The reference backend rejects an unauthenticated, forbidden or
* rate-limited create before touching state.
*/
classifyStatus: () => "NOT_APPLIED" as const,
});
export const LIST_REFERENCE_RESOURCES_CONTRACT = Object.freeze({
contract: Object.freeze({
operationId: "LIST_REFERENCE_RESOURCES",
method: "GET" as const,
pathTemplate: "/api/reference-resources",
inputValidator: zodValidator(
"ReferenceResourceListQuery",
referenceResourceListQuerySchema,
),
outputValidator: zodValidator(
"ReferenceResourceListPayload",
z.array(referenceResourceDtoSchema).max(100),
),
problemValidator: PROBLEM_VALIDATOR,
acceptedStatuses: Object.freeze([200]),
emptyBodyStatuses: Object.freeze([]),
retrySemantics: "SAFE" as const,
requestBody: "NONE" as const,
responseBody: "REQUIRED_JSON" as const,
responseEnvelope: "NONE" as const,
commandRecovery: null,
commandEffect: null,
projectRequest(input: z.output<typeof referenceResourceListQuerySchema>) {
const entries: (readonly [string, string])[] = [];
if (input.cursor !== undefined) entries.push(["cursor", input.cursor]);
entries.push(["limit", String(input.limit)]);
for (const tag of input.tags ?? []) entries.push(["tags", tag]);
return Object.freeze({
pathValues: Object.freeze({}),
queryEntries: Object.freeze(entries),
body: null,
});
},
}),
frontend: Object.freeze({
policyId: "REFERENCE_LIST_V1",
requestByteLimit: 0,
responseByteLimit: 262_144,
totalDeadlineMs: 10_000,
retryBudget: 2 as const,
authProfileId: "EXTERNAL_BEARER",
diagnosticsOperation: "reference.list",
traffic: Object.freeze({
maxPhysicalRequests: 3,
maxRetries: 2,
maxConcurrentRequests: 1,
maxQueuedRequests: 0,
}),
}),
}) satisfies InstalledHttpContract<
z.output<typeof referenceResourceListQuerySchema>,
readonly z.output<typeof referenceResourceDtoSchema>[],
ReferenceProblem
>;
export const GET_REFERENCE_RESOURCE_CONTRACT = Object.freeze({
contract: Object.freeze({
operationId: "GET_REFERENCE_RESOURCE",
method: "GET" as const,
pathTemplate: "/api/reference-resources/{resourceId}",
inputValidator: zodValidator(
"ReferenceResourceParams",
referenceResourceParamsSchema,
),
outputValidator: zodValidator(
"ReferenceResourcePayload",
referenceResourceDtoSchema,
),
problemValidator: PROBLEM_VALIDATOR,
acceptedStatuses: Object.freeze([200]),
emptyBodyStatuses: Object.freeze([]),
retrySemantics: "SAFE" as const,
requestBody: "NONE" as const,
responseBody: "REQUIRED_JSON" as const,
responseEnvelope: "NONE" as const,
commandRecovery: null,
commandEffect: null,
projectRequest(input: z.output<typeof referenceResourceParamsSchema>) {
return Object.freeze({
pathValues: Object.freeze({ resourceId: input.resourceId }),
queryEntries: Object.freeze([]),
body: null,
});
},
}),
frontend: Object.freeze({
policyId: "REFERENCE_DETAIL_V1",
requestByteLimit: 0,
responseByteLimit: 32_768,
totalDeadlineMs: 10_000,
retryBudget: 2 as const,
authProfileId: "EXTERNAL_BEARER",
diagnosticsOperation: "reference.detail",
traffic: Object.freeze({
maxPhysicalRequests: 3,
maxRetries: 2,
maxConcurrentRequests: 1,
maxQueuedRequests: 0,
}),
}),
}) satisfies InstalledHttpContract<
z.output<typeof referenceResourceParamsSchema>,
z.output<typeof referenceResourceDtoSchema>,
ReferenceProblem
>;
export const CREATE_REFERENCE_RESOURCE_CONTRACT = Object.freeze({
contract: Object.freeze({
operationId: "CREATE_REFERENCE_RESOURCE",
method: "POST" as const,
pathTemplate: "/api/reference-resources",
inputValidator: zodValidator(
"CreateReferenceResourceCommand",
createReferenceResourceCommandSchema,
),
outputValidator: zodValidator(
"ReferenceResourcePayload",
referenceResourceDtoSchema,
),
problemValidator: PROBLEM_VALIDATOR,
acceptedStatuses: Object.freeze([200, 201]),
emptyBodyStatuses: Object.freeze([]),
retrySemantics: "KEYED" as const,
requestBody: "JSON" as const,
responseBody: "REQUIRED_JSON" as const,
responseEnvelope: "NONE" as const,
commandRecovery: Object.freeze({
mode: "IDEMPOTENCY_REPLAY" as const,
operationIdentityField: "idempotencyKey",
}),
commandEffect: CREATE_EFFECT,
projectRequest(input: z.output<typeof createReferenceResourceCommandSchema>) {
return Object.freeze({
pathValues: Object.freeze({}),
queryEntries: Object.freeze([]),
body: Object.freeze({ ...input }),
});
},
}),
frontend: Object.freeze({
policyId: "REFERENCE_CREATE_V1",
requestByteLimit: 32_768,
responseByteLimit: 32_768,
totalDeadlineMs: 10_000,
/**
* §8.3. A KEYED command has no automatic retry after a dispatched attempt
* lost its response; the fixture therefore declares a zero budget rather
* than relying on a runtime special case.
*/
retryBudget: 0 as const,
authProfileId: "EXTERNAL_BEARER",
diagnosticsOperation: "reference.create",
traffic: Object.freeze({
maxPhysicalRequests: 1,
maxRetries: 0,
maxConcurrentRequests: 1,
maxQueuedRequests: 0,
}),
}),
}) satisfies InstalledHttpContract<
z.output<typeof createReferenceResourceCommandSchema>,
z.output<typeof referenceResourceDtoSchema>,
ReferenceProblem
>;
export const REFERENCE_FEATURE_TEMPLATE_CONTRIBUTION: InstalledContractContribution =
Object.freeze({
contributionId: "reference-feature-http-v1",
featureId: REFERENCE_FEATURE_ID,
source: Object.freeze({
kind: "TEMPLATE_FIXTURE" as const,
fixtureId: "REFERENCE_FEATURE_V1" as const,
revision: 1 as const,
}),
http: Object.freeze([
LIST_REFERENCE_RESOURCES_CONTRACT,
GET_REFERENCE_RESOURCE_CONTRACT,
CREATE_REFERENCE_RESOURCE_CONTRACT,
]) as readonly InstalledHttpContract<unknown, unknown, unknown>[],
events: Object.freeze([]),
});
@@ -1,120 +0,0 @@
import { defineQueryNamespaceIdentity } from "../../../contracts/query-keys.ts";
import { defineQueryInvalidationTopic } from "../../../contracts/query-invalidation.ts";
export const REFERENCE_FEATURE_ID = "reference-feature";
export const REFERENCE_RESOURCE_QUERY_NAMESPACE = defineQueryNamespaceIdentity(
"reference-resource",
1,
);
export const REFERENCE_RESOURCE_INVALIDATION_TOPIC =
defineQueryInvalidationTopic("qinv.01k10f7m3w9p6r2c8v5n4x");
/**
* 15-01. The declaration half: what the shell reads before a reference route
* is entered. It is in the initial chunk, so it holds data only. The schema
* metadata is `reference-schema-metadata.ts` and the HTTP operations are
* `reference-feature-contract-contribution.ts`, both loaded with
* `feature-runtime.ts`.
*/
export const REFERENCE_FEATURE_CONTRACT = Object.freeze({
featureId: REFERENCE_FEATURE_ID,
routes: Object.freeze({
REFERENCE_RESOURCE_LIST: Object.freeze({
routeId: "REFERENCE_RESOURCE_LIST",
path: "/examples/reference-resources",
paramsSchema: null,
searchSchema: "ReferenceResourceListQuery",
access: "session-required",
loadingSurface: "reference-resource-list",
errorSurface: "feature-boundary",
chunkId: "route-reference-resources",
title: "Reference feature",
navigationLabel: "Reference feature",
navigationOrder: 50,
}),
REFERENCE_RESOURCE_DETAIL: Object.freeze({
routeId: "REFERENCE_RESOURCE_DETAIL",
// 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",
loadingSurface: "reference-resource-detail",
errorSurface: "feature-boundary",
chunkId: "route-reference-resource-detail",
title: "Reference detail",
navigationLabel: null,
navigationOrder: null,
}),
REFERENCE_RESOURCE_FORM: Object.freeze({
routeId: "REFERENCE_RESOURCE_FORM",
path: "/examples/reference-resources/new",
paramsSchema: null,
searchSchema: null,
access: "session-required",
loadingSurface: "reference-resource-form",
errorSurface: "feature-boundary",
chunkId: "route-reference-resource-form",
title: "Reference form",
navigationLabel: null,
navigationOrder: null,
}),
REFERENCE_RESOURCE_STATUS: Object.freeze({
routeId: "REFERENCE_RESOURCE_STATUS",
path: "/examples/reference-resources/status",
paramsSchema: null,
searchSchema: null,
access: "session-required",
loadingSurface: "reference-resource-status",
errorSurface: "feature-boundary",
chunkId: "route-reference-resource-status",
title: "Reference status",
navigationLabel: null,
navigationOrder: null,
}),
}),
routeRuntimeContracts: Object.freeze({
REFERENCE_RESOURCE_LIST: Object.freeze({
routeId: "REFERENCE_RESOURCE_LIST",
moduleId: "reference-resource-page",
paramsCodec: "none",
searchCodec: "ReferenceResourceListQuery",
}),
REFERENCE_RESOURCE_DETAIL: Object.freeze({
routeId: "REFERENCE_RESOURCE_DETAIL",
moduleId: "reference-resource-detail-page",
paramsCodec: "ReferenceResourceParams",
searchCodec: "none",
}),
REFERENCE_RESOURCE_FORM: Object.freeze({
routeId: "REFERENCE_RESOURCE_FORM",
moduleId: "reference-resource-form-page",
paramsCodec: "none",
searchCodec: "none",
}),
REFERENCE_RESOURCE_STATUS: Object.freeze({
routeId: "REFERENCE_RESOURCE_STATUS",
moduleId: "reference-resource-status-page",
paramsCodec: "none",
searchCodec: "none",
}),
}),
invalidation: Object.freeze({
topics: Object.freeze([REFERENCE_RESOURCE_INVALIDATION_TOPIC]),
namespaces: Object.freeze([REFERENCE_RESOURCE_QUERY_NAMESPACE]),
edges: Object.freeze([
Object.freeze({
topicId: REFERENCE_RESOURCE_INVALIDATION_TOPIC,
namespace: REFERENCE_RESOURCE_QUERY_NAMESPACE,
}),
]),
}),
topicVersions: Object.freeze([
Object.freeze({
topicId: REFERENCE_RESOURCE_INVALIDATION_TOPIC,
topicVersion: 1,
}),
]),
// TEMPLATE_FIXTURE contributions are not part of the contract set.
contractPackages: Object.freeze([]),
} as const);
@@ -1,59 +0,0 @@
import {
createReferenceResource,
type ReferenceResource,
} from "../domain/reference-resource.ts";
import {
mappingFailure,
mappingSuccess,
type BoundaryMappingResult,
} from "../../../contracts/boundary-mapper.ts";
import type { ReferenceResourceDto } from "./reference-schemas.ts";
export type ReferenceResourceView = Readonly<{
resourceId: string;
title: string;
createdAt: string | null;
optimistic?: boolean;
}>;
/**
* Operation-specific mapper. The HTTP contract has already validated the wire
* shape, so this mapper owns only wire -> domain construction.
*/
export function mapReferenceResourcePayload(
dto: ReferenceResourceDto,
): BoundaryMappingResult<ReferenceResource> {
try {
return mappingSuccess(
createReferenceResource({
id: dto.id,
displayName: dto.name,
createdAt: dto.createdAt ?? null,
}),
);
} catch {
return mappingFailure("MAPPING_INVARIANT_REJECTED");
}
}
export function mapReferenceResourceListPayload(
payload: readonly ReferenceResourceDto[],
): BoundaryMappingResult<readonly ReferenceResource[]> {
const output: ReferenceResource[] = [];
for (const item of payload) {
const mapped = mapReferenceResourcePayload(item);
if (!mapped.ok) return mapped;
output.push(mapped.value);
}
return mappingSuccess(Object.freeze(output));
}
export function toReferenceView(
resource: ReferenceResource,
): ReferenceResourceView {
return Object.freeze({
resourceId: resource.id,
title: resource.displayName,
createdAt: resource.createdAt,
});
}
@@ -1,112 +0,0 @@
export const REFERENCE_MESSAGE_CATALOGS = Object.freeze({
"ko-KR": Object.freeze({
"route.REFERENCE_RESOURCE_LIST.navigation": "Reference feature",
"route.REFERENCE_RESOURCE_LIST.title": "Reference resources",
"route.REFERENCE_RESOURCE_DETAIL.navigation": "Reference detail",
"route.REFERENCE_RESOURCE_DETAIL.title": "Reference resource detail",
"route.REFERENCE_RESOURCE_FORM.navigation": "Reference form",
"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.list.title": "참조 기능",
"reference.list.filterLimit": "최대 {limit}개",
"reference.list.filterTags": "태그 {tags}",
"reference.list.resources": "참조 리소스 목록",
"reference.form.back": "목록으로 돌아가기",
"reference.form.eyebrow": "폼 페이지",
"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.eyebrow": "상세 페이지",
"reference.detail.titlePending": "참조 상세",
"reference.detail.resourceId": "리소스 ID",
"reference.detail.createdAt": "생성 시각",
"reference.detail.description":
"route param과 detail query의 reset 경계를 확인합니다.",
"reference.detail.summaryPending": "요약 정보를 준비하고 있습니다.",
"reference.detail.sectionSlot":
"이 영역에는 제품별 상세 section을 조립할 수 있습니다.",
"reference.detail.aside": "상세 페이지의 관련 정보 slot입니다.",
"reference.status.eyebrow": "상태 페이지 · 점검",
"reference.status.title": "잠시 사용할 수 없습니다.",
"reference.status.description":
"도메인 데이터나 raw 오류를 노출하지 않는 중립적인 상태 페이지 예시입니다.",
"reference.status.back": "목록으로 이동",
}),
"en-US": Object.freeze({
"route.REFERENCE_RESOURCE_LIST.navigation": "Reference feature",
"route.REFERENCE_RESOURCE_LIST.title": "Reference resources",
"route.REFERENCE_RESOURCE_DETAIL.navigation": "Reference detail",
"route.REFERENCE_RESOURCE_DETAIL.title": "Reference resource detail",
"route.REFERENCE_RESOURCE_FORM.navigation": "Reference form",
"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.list.title": "Reference feature",
"reference.list.filterLimit": "limit {limit}",
"reference.list.filterTags": "tags {tags}",
"reference.list.resources": "Reference resources",
"reference.form.back": "Back to the list",
"reference.form.eyebrow": "FormPage",
"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.eyebrow": "DetailPage",
"reference.detail.titlePending": "Reference detail",
"reference.detail.resourceId": "Resource ID",
"reference.detail.createdAt": "Created",
"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.eyebrow": "StatusPage · maintenance",
"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);
@@ -1,63 +0,0 @@
/**
* FE-REG-SCHEMA rows of the reference feature's route and API schemas.
* Runtime half only (`feature-runtime.ts`); the app boot never imports it.
* The HTTP operations are the V3 descriptors in
* `reference-feature-contract-contribution.ts`; FE-REG-API reads them.
*/
export const REFERENCE_SCHEMA_METADATA = Object.freeze({
ReferenceResourceParams: Object.freeze({
schemaId: "ReferenceResourceParams",
boundary: "route-params",
owner: "feature-frontend-reference-feature-vertical-slice",
runtime: "zod",
schemaVersion: 1,
direction: "REQUEST",
unknownFieldPolicy: "REJECT_UNKNOWN",
}),
ReferenceResourceListQuery: Object.freeze({
schemaId: "ReferenceResourceListQuery",
boundary: "route-search-api-request",
owner: "feature-frontend-reference-feature-vertical-slice",
runtime: "zod",
schemaVersion: 1,
direction: "REQUEST",
unknownFieldPolicy: "REJECT_UNKNOWN",
}),
CreateReferenceResourceCommand: Object.freeze({
schemaId: "CreateReferenceResourceCommand",
boundary: "api-request",
owner: "feature-frontend-reference-feature-vertical-slice",
runtime: "zod",
schemaVersion: 1,
direction: "REQUEST",
unknownFieldPolicy: "REJECT_UNKNOWN",
}),
ReferenceResourceListPayload: Object.freeze({
schemaId: "ReferenceResourceListPayload",
boundary: "api-response",
owner: "feature-frontend-reference-feature-vertical-slice",
runtime: "zod",
schemaVersion: 1,
direction: "RESPONSE",
unknownFieldPolicy: "STRIP_UNKNOWN",
}),
ReferenceResourcePayload: Object.freeze({
schemaId: "ReferenceResourcePayload",
boundary: "api-response",
owner: "feature-frontend-reference-feature-vertical-slice",
runtime: "zod",
schemaVersion: 1,
direction: "RESPONSE",
unknownFieldPolicy: "STRIP_UNKNOWN",
}),
// 1103/16-04. FE-REG-API's problemSchema references this row.
ReferenceProblem: Object.freeze({
schemaId: "ReferenceProblem",
boundary: "api-problem",
owner: "feature-frontend-reference-feature-vertical-slice",
runtime: "zod",
schemaVersion: 1,
direction: "RESPONSE",
unknownFieldPolicy: "STRIP_UNKNOWN",
}),
});
@@ -1,67 +0,0 @@
import { z } from "../../../contracts/zod.ts";
export const referenceResourceListQuerySchema = z
.object({
cursor: z.string().min(1).optional(),
limit: z.coerce.number().int().min(1).max(100).default(20),
tags: z
.preprocess(
(value) =>
value === undefined
? undefined
: Array.isArray(value)
? value
: [value],
z.array(z.string().trim().min(1)).readonly(),
)
.optional(),
})
.strict();
export const referenceResourceParamsSchema = z
.object({
resourceId: z.string().trim().min(1).max(120),
})
.strict();
export const referenceResourceDtoSchema = z
.object({
id: z.string().min(1).max(120),
name: z.string().min(1).max(240),
createdAt: z.string().datetime().optional(),
})
.strip();
export type ReferenceResourceDto = z.output<
typeof referenceResourceDtoSchema
>;
export const referenceProblemSchema = z
.object({
type: z.string().min(1).max(512),
title: z.string().min(1).max(240),
status: z.int().min(100).max(599),
code: z.string().min(1).max(120).optional(),
/** 03-04. 422 field issues; backend messages are stripped. */
issues: z
.array(
z
.object({
path: z.string().min(1).max(120),
code: z.string().min(1).max(80),
})
.strip(),
)
.max(50)
.optional(),
})
.strip();
export type ReferenceProblem = z.output<typeof referenceProblemSchema>;
export const createReferenceResourceCommandSchema = z
.object({
name: z.string().trim().min(1).max(120),
note: z.string().trim().max(500).optional(),
})
.strict();
@@ -1,14 +0,0 @@
export type ReferenceResource = Readonly<{
id: string;
displayName: string;
createdAt: string | null;
}>;
export function createReferenceResource(
values: ReferenceResource,
): ReferenceResource {
if (!values.id || !values.displayName) {
throw new TypeError("Reference resource invariants require id and displayName");
}
return Object.freeze({ ...values });
}
@@ -1,26 +0,0 @@
import { defineFeatureModule } from "../feature-module.ts";
import {
REFERENCE_FEATURE_CONTRACT,
REFERENCE_FEATURE_ID,
} from "./contracts/reference-feature-contract.ts";
import { REFERENCE_MESSAGE_CATALOGS } from "./contracts/reference-message-catalog.ts";
export const FEATURE_MODULE_ID =
"reference-feature" satisfies typeof REFERENCE_FEATURE_ID;
/** Owning bounded context (route root and budget live in its declaration). */
export const FEATURE_CONTEXT_ID = "reference-context";
/**
* 15-01. Declaration only: this file and what it imports statically are in the
* initial chunk. The executable half is `feature-runtime.ts`, imported here
* dynamically and loaded when a reference route is entered.
*/
export const REFERENCE_FEATURE_MODULE = defineFeatureModule({
id: FEATURE_MODULE_ID,
contracts: REFERENCE_FEATURE_CONTRACT,
routes: REFERENCE_FEATURE_CONTRACT.routes,
messages: REFERENCE_MESSAGE_CATALOGS,
loadRuntime: async () => (await import("./feature-runtime.ts")).FEATURE_RUNTIME,
} as const);
export const FEATURE_MODULE = REFERENCE_FEATURE_MODULE;
@@ -1,18 +0,0 @@
import { defineFeatureRuntime } from "../feature-module.ts";
import { REFERENCE_FEATURE_ADAPTER_CONTRIBUTION } from "./adapters/create-reference-feature-input.ts";
import { REFERENCE_FEATURE_TEMPLATE_CONTRIBUTION } from "./contracts/reference-feature-contract-contribution.ts";
import { REFERENCE_FEATURE_ID } from "./contracts/reference-feature-contract.ts";
import { REFERENCE_SCHEMA_METADATA } from "./contracts/reference-schema-metadata.ts";
/**
* 15-01. The executable half of the reference feature. `feature-module.ts`
* imports this file dynamically; the router loads it when a reference route
* is entered (`application.features.load`), so none of it is in the initial
* chunk.
*/
export const FEATURE_RUNTIME = defineFeatureRuntime({
featureId: REFERENCE_FEATURE_ID,
schemas: REFERENCE_SCHEMA_METADATA,
adapters: [REFERENCE_FEATURE_ADAPTER_CONTRIBUTION],
contractContributions: [REFERENCE_FEATURE_TEMPLATE_CONTRIBUTION],
} as const);
@@ -1,32 +0,0 @@
import { lazy } from "react";
import { REFERENCE_FEATURE_ID } from "../contracts/reference-feature-contract.ts";
// 16-04. The codecs have their own file: the pages' link helpers need them and
// this file lazy-loads the pages, so a page importing it would close a cycle.
import { REFERENCE_FEATURE_ROUTE_CODECS } from "./reference-route-codecs.ts";
export const REFERENCE_FEATURE_ROUTE_RUNTIME = {
REFERENCE_RESOURCE_LIST: Object.freeze({
moduleId: "reference-resource-page",
Component: lazy(() => import("./reference-resource-page.tsx")),
}),
REFERENCE_RESOURCE_DETAIL: Object.freeze({
moduleId: "reference-resource-detail-page",
Component: lazy(() => import("./reference-resource-detail-page.tsx")),
}),
REFERENCE_RESOURCE_FORM: Object.freeze({
moduleId: "reference-resource-form-page",
Component: lazy(() => import("./reference-resource-form-page.tsx")),
}),
REFERENCE_RESOURCE_STATUS: Object.freeze({
moduleId: "reference-resource-status-page",
Component: lazy(() => import("./reference-resource-status-page.tsx")),
}),
} as const;
/** Context-owned lazy route modules consume this executable contribution. */
export const REFERENCE_FEATURE_RUNTIME_CONTRIBUTION = Object.freeze({
featureId: REFERENCE_FEATURE_ID,
routeCodecs: REFERENCE_FEATURE_ROUTE_CODECS,
routeRuntime: REFERENCE_FEATURE_ROUTE_RUNTIME,
});
@@ -1,65 +0,0 @@
import { Link } from "react-router-dom";
import {
AsyncSurface,
DetailPage,
} from "../../../presentation/design-system/index.ts";
import { useLocale } from "../../../presentation/i18n/index.ts";
import {
referenceRouteUrl,
useReferenceResourceId,
} from "./reference-routes.ts";
import { useReferenceFailureAction } from "./use-reference-failure-action.ts";
import { useReferenceDetail } from "./use-reference-feature.ts";
export default function ReferenceResourceDetailPage() {
const { date, message } = useLocale();
const resourceId = useReferenceResourceId();
const { query } = useReferenceDetail(resourceId);
const resource = query.data;
const failureAction = useReferenceFailureAction(query.state.failure);
return (
<DetailPage
key={resourceId}
breadcrumb={
<Link to={referenceRouteUrl("REFERENCE_RESOURCE_LIST")}>
{message("reference.list.resources")}
</Link>
}
heading={{
eyebrow: message("reference.detail.eyebrow"),
title: resource?.title ?? message("reference.detail.titlePending"),
description: message("reference.detail.description"),
}}
metadata={
resource ? (
<dl>
<dt>{message("reference.detail.resourceId")}</dt>
<dd>{resource.resourceId}</dd>
<dt>{message("reference.detail.createdAt")}</dt>
<dd>
{resource.createdAt
? date(new Date(resource.createdAt))
: message("common.noDisplayValue")}
</dd>
</dl>
) : (
<p>{message("reference.detail.summaryPending")}</p>
)
}
feedback={
<AsyncSurface
state={query.state}
onAction={failureAction}
onRetry={query.retry}
>
{resource ? (
<p>{message("reference.detail.sectionSlot")}</p>
) : null}
</AsyncSurface>
}
aside={<p>{message("reference.detail.aside")}</p>}
/>
);
}
@@ -1,215 +0,0 @@
import { useCallback, useState } from "react";
import { Link, useNavigate } from "react-router-dom";
import {
Button,
AsyncSurface,
DirtyNavigationDialog,
ErrorSummary,
Form,
FormActions,
FormFailureStatus,
FormPage,
FormField,
useAppForm,
useDirtyNavigationGuard,
} from "../../../presentation/design-system/index.ts";
import { useLocale } from "../../../presentation/i18n/index.ts";
import { useQueryInvalidationCoordinator } from "../../../presentation/adapters/query/query-invalidation-provider.tsx";
import { REFERENCE_RESOURCE_INVALIDATION_TOPIC } from "../contracts/reference-feature-contract.ts";
import {
REFERENCE_FORM_DEFAULTS,
referenceResourceFormSchema,
toCreateReferenceCommand,
type ReferenceResourceFormValues,
} from "./reference-resource-form.ts";
import { referenceRouteUrl } from "./reference-routes.ts";
import { useReferenceFailureAction } from "./use-reference-failure-action.ts";
import { useReferenceCreate } from "./use-reference-feature.ts";
export default function ReferenceResourceFormPage() {
const navigate = useNavigate();
const { message } = useLocale();
const fieldLabels = {
name: message("reference.form.name"),
note: message("reference.form.note"),
} satisfies Record<keyof ReferenceResourceFormValues, string>;
const mutation = useReferenceCreate();
const invalidation = useQueryInvalidationCoordinator();
const submit = useCallback(
(command: ReturnType<typeof toCreateReferenceCommand>) =>
mutation.submit(command),
[mutation],
);
const form = useAppForm({
schema: referenceResourceFormSchema,
defaultValues: REFERENCE_FORM_DEFAULTS,
allowedServerFields: ["name", "note"],
mapToCommand: toCreateReferenceCommand,
submit,
});
const failureAction = useReferenceFailureAction(form.failure ?? undefined);
const mutationEffectUnknown =
mutation.state.indicator === "mutation-effect-unknown";
const mutationBlocked =
mutationEffectUnknown || mutation.state.indicator === "mutation-pending";
// 1105/08-04. A save this form did not start holds the coordinator: one
// left running when the user came back to the form, or the check behind
// "confirm applied". The save button is off and, for the first, the
// feedback says a save is running, instead of a click that does nothing.
const otherSaveRunning =
mutation.state.indicator === "mutation-pending" && !form.pending;
// 1106/08-01. The result of that save belongs to the form that started
// it, not to this one. Once it ends, the feedback points to the list,
// which shows whether the item is there, until this form saves itself.
const [otherSaveSeen, setOtherSaveSeen] = useState(false);
if (!otherSaveSeen && otherSaveRunning && form.result === "idle") {
setOtherSaveSeen(true);
} else if (otherSaveSeen && (form.pending || form.result !== "idle")) {
setOtherSaveSeen(false);
}
const guard = useDirtyNavigationGuard(form.dirty && !form.pending);
const reloadList = (
<p>
<Link
to={referenceRouteUrl("REFERENCE_RESOURCE_LIST")}
onClick={() => {
void invalidation
?.invalidate([REFERENCE_RESOURCE_INVALIDATION_TOPIC])
.catch(() => {});
}}
>
{message("reference.form.reloadList")}
</Link>
</p>
);
return (
<Form
id={form.formId}
pending={form.pending}
onSubmit={(event) => {
if (mutationBlocked) {
event.preventDefault();
return;
}
void form.submitForm(event);
}}
>
<FormPage
feedbackId={form.feedbackId}
breadcrumb={
<button
className="ui-button ui-button--ghost"
type="button"
onClick={() => navigate(referenceRouteUrl("REFERENCE_RESOURCE_LIST"))}
>
{message("reference.form.back")}
</button>
}
heading={{
eyebrow: message("reference.form.eyebrow"),
title: message("reference.form.title"),
description: message("reference.form.description"),
}}
errorSummary={
<ErrorSummary
fieldErrors={form.fieldErrors}
formErrors={form.formErrors}
fieldLabels={fieldLabels}
fieldId={form.fieldId}
onFocusField={form.focusField}
/>
}
fields={
<>
<FormField
{...form.field("name")}
label={fieldLabels.name}
description={message("reference.form.nameDescription")}
autoComplete="off"
required
/>
<FormField
{...form.field("note")}
label={fieldLabels.note}
description={message("reference.form.noteDescription")}
autoComplete="off"
/>
</>
}
formActions={
<FormActions sticky>
<Button
variant="secondary"
onClick={() => navigate(referenceRouteUrl("REFERENCE_RESOURCE_LIST"))}
disabled={form.pending || mutationBlocked}
>
{message("reference.form.cancel")}
</Button>
{/* 1103/08-02. Busy, not disabled, while saving: a disabled
button drops keyboard focus. The form refuses a second
submit itself. */}
<Button
type="submit"
pending={form.pending}
pendingLabel={message("reference.form.saving")}
disabled={mutationEffectUnknown || otherSaveRunning}
>
{message("reference.form.save")}
</Button>
<Button
variant="ghost"
onClick={() => form.reset()}
disabled={!form.dirty || form.pending || mutationBlocked}
>
{message("reference.form.reset")}
</Button>
</FormActions>
}
feedback={
form.failure ? (
<FormFailureStatus
failure={form.failure}
onAction={
form.result === "retry-later"
? () => void form.submitForm()
: failureAction
}
/>
) : mutationEffectUnknown ? (
<>
<AsyncSurface
state={mutation.state}
supportReference={form.supportReference}
onReconcileUnknownEffect={(resolution) => {
void mutation
.reconcileUnknownEffect(resolution)
.then(form.settleApplied);
}}
onResendUnknownEffect={() => {
void form.resendUnknown(mutation.resendUnknownEffect);
}}
/>
{reloadList}
</>
) : form.result === "success" ? (
<p role="status">{message("reference.form.saved")}</p>
) : form.result === "conflict" ? (
<p role="status">{message("reference.form.conflict")}</p>
) : otherSaveRunning && form.result !== "effect-unknown" ? (
// 1105/08-04. While this form's own unknown result is being
// checked, the result that follows is shown instead.
<AsyncSurface state={mutation.state} />
) : otherSaveSeen ? (
reloadList
) : null
}
aside={
<p>{message("reference.form.privacy")}</p>
}
guard={<DirtyNavigationDialog guard={guard} />}
/>
</Form>
);
}
@@ -1,29 +0,0 @@
import { z } from "../../../contracts/zod.ts";
export const referenceResourceFormSchema = z
.object({
name: z
.string()
.trim()
.min(2)
.max(120),
note: z.string().trim().max(500).default(""),
})
.strict();
export type ReferenceResourceFormValues = z.infer<
typeof referenceResourceFormSchema
>;
export const REFERENCE_FORM_DEFAULTS: ReferenceResourceFormValues =
Object.freeze({
name: "",
note: "",
});
export function toCreateReferenceCommand(values: ReferenceResourceFormValues) {
return Object.freeze({
name: values.name,
...(values.note ? { note: values.note } : {}),
});
}
@@ -1,79 +0,0 @@
import { Link, useNavigate } from "react-router-dom";
import {
AsyncSurface,
Button,
CollectionPage,
} from "../../../presentation/design-system/index.ts";
import { useLocale } from "../../../presentation/i18n/index.ts";
import { referenceRouteUrl } from "./reference-routes.ts";
import { useReferenceFailureAction } from "./use-reference-failure-action.ts";
import { useReferenceFeature } from "./use-reference-feature.ts";
export default function ReferenceResourcePage() {
const navigate = useNavigate();
const { message } = useLocale();
const { filters, query } = useReferenceFeature();
const failureAction = useReferenceFailureAction(query.state.failure);
return (
<CollectionPage
heading={{
eyebrow: message("reference.list.eyebrow"),
title: message("reference.list.title"),
description: message("reference.list.description"),
}}
actions={[
{
kind: "button",
label: message("reference.list.create"),
onAction: () => navigate(referenceRouteUrl("REFERENCE_RESOURCE_FORM")),
},
]}
activeFilters={
<p data-testid="reference-filter">
{message("reference.list.filterLimit", { limit: filters.limit })}
{filters.tags?.length
? ` · ${message("reference.list.filterTags", {
tags: filters.tags.join(", "),
})}`
: ""}
</p>
}
toolbar={
<Button onClick={() => void query.retry()}>
{message("reference.list.refresh")}
</Button>
}
resultCount={
// 08-09. Counted only from a settled result: a loading, idle or
// failed list has nothing to count.
query.state.base === "success" || query.state.base === "empty"
? message("reference.list.resultCount", {
count: query.data?.length ?? 0,
})
: null
}
>
<AsyncSurface
state={query.state}
onAction={failureAction}
onRetry={query.retry}
>
<ul aria-label={message("reference.list.resources")}>
{(query.data ?? []).map((resource) => (
<li key={resource.resourceId}>
<Link
to={referenceRouteUrl("REFERENCE_RESOURCE_DETAIL", {
params: { resourceId: resource.resourceId },
})}
>
{resource.title}
</Link>
</li>
))}
</ul>
</AsyncSurface>
</CollectionPage>
);
}
@@ -1,40 +0,0 @@
import { useLocation, useNavigate } from "react-router-dom";
import { StatusPage } from "../../../presentation/design-system/index.ts";
import { useLocale } from "../../../presentation/i18n/index.ts";
import { referenceRouteUrl } from "./reference-routes.ts";
import type { ReferenceSupportState } from "./use-reference-failure-action.ts";
/** History state is untrusted input: only a string reference is shown. */
function receivedSupportReference(state: unknown): string | undefined {
const reference =
state && typeof state === "object"
? (state as ReferenceSupportState).supportReference
: undefined;
return typeof reference === "string" && reference !== "" ? reference : undefined;
}
export default function ReferenceResourceStatusPage() {
const navigate = useNavigate();
const location = useLocation();
const { message } = useLocale();
// 0929/08-04. Only the id the failed request carried; none when opened directly.
const supportReference = receivedSupportReference(location.state);
return (
<StatusPage
variant="maintenance"
heading={{
eyebrow: message("reference.status.eyebrow"),
title: message("reference.status.title"),
description: message("reference.status.description"),
}}
primaryAction={{
kind: "button",
label: message("reference.status.back"),
onAction: () => navigate(referenceRouteUrl("REFERENCE_RESOURCE_LIST")),
}}
supportReference={supportReference}
/>
);
}
@@ -1,17 +0,0 @@
import {
referenceResourceListQuerySchema,
referenceResourceParamsSchema,
} from "../contracts/reference-schemas.ts";
/**
* 15-01. Route codecs travel with the context routes (`context-routes.ts` puts
* them on each route handle), not with the boot-time feature module: zod
* schemas are executable and the shell needs none of them before a reference
* route is entered. 16-04: the pages' link helpers (`reference-routes.ts`) use
* them too; this file imports no router code, so loading the context routes
* does not pull in the link builder.
*/
export const REFERENCE_FEATURE_ROUTE_CODECS = {
ReferenceResourceListQuery: referenceResourceListQuerySchema,
ReferenceResourceParams: referenceResourceParamsSchema,
} as const;
@@ -1,37 +0,0 @@
import { useMemo } from "react";
import { buildRouteUrl } from "../../../presentation/routes/route-codecs.ts";
import { useRouteInput } from "../../../presentation/routes/route-input.tsx";
import type { ReferenceListFilters } from "../application/reference-feature-api.ts";
import type { REFERENCE_FEATURE_CONTRACT } from "../contracts/reference-feature-contract.ts";
import { REFERENCE_FEATURE_ROUTE_CODECS } from "./reference-route-codecs.ts";
/**
* 16-04. A reference link names its route ID. The router's own builder fills
* in the contract's `path` through the codecs that parse it, so the contract
* stays the one place a path is written.
*/
export function referenceRouteUrl(
routeId: keyof typeof REFERENCE_FEATURE_CONTRACT.routes,
input?: Parameters<typeof buildRouteUrl>[1],
): string {
return buildRouteUrl(routeId, input, REFERENCE_FEATURE_ROUTE_CODECS);
}
/**
* 16-04. The router hands pages untyped route input. Reading it back through
* the codec that already accepted it gives the codec's type without a cast.
*/
export function useReferenceListFilters(): ReferenceListFilters {
const { search } = useRouteInput();
return useMemo(
() => REFERENCE_FEATURE_ROUTE_CODECS.ReferenceResourceListQuery.parse(search),
[search],
);
}
export function useReferenceResourceId(): string {
return REFERENCE_FEATURE_ROUTE_CODECS.ReferenceResourceParams.parse(
useRouteInput().params,
).resourceId;
}
@@ -1,57 +0,0 @@
import { useCallback } from "react";
import { useLocation, useNavigate } from "react-router-dom";
import type { AppFailure } from "../../../contracts/errors.ts";
import { useSession } from "../../../presentation/providers/session-provider.tsx";
import { referenceRouteUrl } from "./reference-routes.ts";
/** 0929/08-04. What the support status page receives as navigation state. */
export type ReferenceSupportState = Readonly<{ supportReference?: string }>;
/**
* Reference queries own concrete destinations for generic application failure
* actions. Retry remains query-owned; guarded release reloads remain in the
* chunk recovery boundary.
*/
export function useReferenceFailureAction(
failure: AppFailure | undefined,
): (() => void) | undefined {
const location = useLocation();
const navigate = useNavigate();
const { beginSignIn } = useSession();
const action = failure?.action;
const requestId = failure?.requestId;
const handleAction = useCallback(() => {
if (action === "reauth") {
const returnTo = `${location.pathname}${location.search}${location.hash}`;
void beginSignIn(returnTo).catch(() => {
void navigate("/");
});
return;
}
if (action === "navigate") {
void navigate("/");
return;
}
if (action === "contact-support") {
// The id stays in history state, never in the URL.
const state: ReferenceSupportState =
requestId === undefined ? {} : { supportReference: requestId };
void navigate(referenceRouteUrl("REFERENCE_RESOURCE_STATUS"), { state });
}
}, [
action,
requestId,
beginSignIn,
location.hash,
location.pathname,
location.search,
navigate,
]);
return action === "reauth" ||
action === "navigate" ||
action === "contact-support"
? handleAction
: undefined;
}
@@ -1,140 +0,0 @@
import { useApplicationFeature } from "../../../presentation/providers/application-provider.tsx";
import {
useApplicationMutation,
useApplicationQuery,
} from "../../../presentation/adapters/query/application-query.ts";
import {
REFERENCE_FEATURE_ID,
REFERENCE_RESOURCE_INVALIDATION_TOPIC,
REFERENCE_RESOURCE_QUERY_NAMESPACE,
} from "../contracts/reference-feature-contract.ts";
import type {
ReferenceCreateCommand,
ReferenceFeatureInput,
ReferenceListFilters,
} from "../application/reference-feature-api.ts";
import type { ReferenceResourceView } from "../contracts/reference-mapper.ts";
import { CREATE_REFERENCE_RESOURCE_CONTRACT } from "../contracts/reference-feature-contract-contribution.ts";
import {
bindQuery,
commandMutationIdentity,
type BoundMutation,
type QueryResultMeasure,
} from "../../../contracts/server-state.ts";
import { useServerStateScope } from "../../../presentation/adapters/query/server-state-scope-provider.tsx";
import { useReferenceListFilters } from "./reference-routes.ts";
const UTF8 = new TextEncoder();
/**
* §10.4. Feature-owned measurement over the mapped application value. There is
* no generic fallback: bounded string bytes plus fixed primitive width plus a
* small per-item overhead, never `JSON.stringify` or a recursive walker.
*/
function measureResourceView(view: ReferenceResourceView): QueryResultMeasure {
return {
itemCount: 1,
estimatedBytes:
UTF8.encode(view.resourceId).byteLength +
UTF8.encode(view.title).byteLength +
UTF8.encode(view.createdAt ?? "").byteLength +
32,
};
}
function measureResourceList(
views: readonly ReferenceResourceView[],
): QueryResultMeasure {
let estimatedBytes = 16;
for (const view of views) {
estimatedBytes += measureResourceView(view).estimatedBytes;
}
return { itemCount: views.length, estimatedBytes };
}
const REFERENCE_CREATE_MUTATION_POLICY = Object.freeze({
definitionId: "reference-resource-create-v1",
definitionVersion: 1,
// 1103/16-05. The operation id and the key requirement are the
// descriptor's, so a misspelt id cannot pass the type check.
...commandMutationIdentity(CREATE_REFERENCE_RESOURCE_CONTRACT),
duplicatePolicy: "REJECT_WHILE_ACTIVE" as const,
invalidate: Object.freeze([REFERENCE_RESOURCE_INVALIDATION_TOPIC]),
});
type ReferenceCreateMutationBinding = Pick<
BoundMutation<ReferenceCreateCommand, ReferenceResourceView>,
"scope" | "execute"
>;
function bindReferenceCreateMutation(
binding: ReferenceCreateMutationBinding,
): BoundMutation<ReferenceCreateCommand, ReferenceResourceView> {
return Object.freeze({
...REFERENCE_CREATE_MUTATION_POLICY,
...binding,
});
}
export function useReferenceFeatureInput(): ReferenceFeatureInput {
return useApplicationFeature(REFERENCE_FEATURE_ID);
}
export function useReferenceDetail(resourceId: string) {
const input = useReferenceFeatureInput();
const scope = useServerStateScope();
const query = useApplicationQuery(
bindQuery(
{
definitionId: "reference-resource-detail-v1",
definitionVersion: 1,
namespace: REFERENCE_RESOURCE_QUERY_NAMESPACE,
profileId: "DETAIL_STANDARD",
measureResult: measureResourceView,
execute: (selectedResourceId: string, { signal }) =>
input.getResource(selectedResourceId, { signal }),
},
resourceId,
scope,
),
);
return Object.freeze({ query });
}
export function useReferenceCreate() {
const input = useReferenceFeatureInput();
const scope = useServerStateScope();
const mutation = bindReferenceCreateMutation({
scope,
execute: input.createResource,
});
return useApplicationMutation(mutation);
}
export function useReferenceFeature() {
const input = useReferenceFeatureInput();
const scope = useServerStateScope();
const filters = useReferenceListFilters();
const query = useApplicationQuery(
bindQuery(
{
definitionId: "reference-resource-list-v1",
definitionVersion: 1,
namespace: REFERENCE_RESOURCE_QUERY_NAMESPACE,
profileId: "LIST_STANDARD",
measureResult: measureResourceList,
execute: (selectedFilters: ReferenceListFilters, { signal }) =>
input.listResources(selectedFilters, { signal }),
},
filters,
scope,
),
);
const mutation = useApplicationMutation(
bindReferenceCreateMutation({
scope,
execute: input.createResource,
}),
);
return Object.freeze({ filters, query, mutation });
}
+1 -2
View File
@@ -12,8 +12,7 @@
line-height: 1.65;
}
.starter-actions,
.auth-example {
.starter-actions {
display: flex;
flex-wrap: wrap;
align-items: center;