feat: add form and page platform

src/features/reference-feature/README.md

@@ -6,11 +6,11 @@ reference implementation이다.
 ## 소유 경계
 
 - `domain`: 외부 DTO와 React를 모르는 불변 model
-- `application`: UI가 호출하는 list/create input과 gateway 계약
+- `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/mutation controller로 연결하는 inbound
-  adapter와 page
+- `presentation`: route input을 query/form controller로 연결하는 inbound
+  adapter, 독립 form schema/command mapper와 list/detail/form/status page
 
 generic application은 `features.get(featureId)` catalog만 제공한다. feature hook이
 자신의 input shape를 확인하며 page는 HTTP client, storage, auth owner, output
@@ -33,7 +33,7 @@ corepack pnpm test:sample-removal
 ```
 
 첫 명령은 URL filter와 query key/HTTP request의 동일성, schema/mapper, 모든
-query/mutation 상태와 production composition을 검증한다. 두 번째 명령은 임시
+query/mutation/form 상태와 production composition을 검증한다. 두 번째 명령은 임시
 복제본에서 이 source/test 디렉터리를 제거하고 installed catalog를 빈 목록으로
 재생성한 뒤 typecheck, architecture, registry, unit/integration, home smoke,
-production build와 fixture ID 잔여 0개를 검사한다.
+production build와 source/built fixture ID 잔여 0개를 검사한다.

src/features/reference-feature/adapters/reference-http-gateway.ts

@@ -14,6 +14,7 @@ type HttpExecutor = Readonly<{
     request: Readonly<{
       operationId: string;
       routeId: string;
+      pathParams?: Record<string, string | number>;
       searchParams?: unknown;
       body?: unknown;
       signal?: AbortSignal;
@@ -42,7 +43,7 @@ export function createReferenceHttpGateway(
           }
         : result;
     },
-    async create(command: Readonly<{ name: string }>) {
+    async create(command: Readonly<{ name: string; note?: string }>) {
       const result = await http.execute({
         operationId: "CREATE_REFERENCE_RESOURCE",
         routeId: "REFERENCE_RESOURCE_LIST",
@@ -52,5 +53,19 @@ export function createReferenceHttpGateway(
         ? { ok: true as const, value: result.value as ReferenceResource }
         : result;
     },
+    async get(
+      resourceId: string,
+      context?: Readonly<{ signal?: AbortSignal }>,
+    ) {
+      const result = await http.execute({
+        operationId: "GET_REFERENCE_RESOURCE",
+        routeId: "REFERENCE_RESOURCE_DETAIL",
+        pathParams: { resourceId },
+        signal: context?.signal,
+      });
+      return result.ok
+        ? { ok: true as const, value: result.value as ReferenceResource }
+        : result;
+    },
   });
 }

src/features/reference-feature/application/reference-feature-api.ts

@@ -21,7 +21,11 @@ export type ReferenceFeatureInput = Readonly<{
     context?: Readonly<{ signal?: AbortSignal }>,
   ): Promise<ReferenceResult<readonly ReferenceResourceView[]>>;
   createResource(
-    command: Readonly<{ name: string }>,
+    command: Readonly<{ name: string; note?: string }>,
+  ): Promise<ReferenceResult<ReferenceResourceView>>;
+  getResource(
+    resourceId: string,
+    context?: Readonly<{ signal?: AbortSignal }>,
   ): Promise<ReferenceResult<ReferenceResourceView>>;
 }>;
 
@@ -31,7 +35,11 @@ export type ReferenceGateway = Readonly<{
     context?: Readonly<{ signal?: AbortSignal }>,
   ): Promise<ReferenceResult<readonly ReferenceResource[]>>;
   create(
-    command: Readonly<{ name: string }>,
+    command: Readonly<{ name: string; note?: string }>,
+  ): Promise<ReferenceResult<ReferenceResource>>;
+  get(
+    resourceId: string,
+    context?: Readonly<{ signal?: AbortSignal }>,
   ): Promise<ReferenceResult<ReferenceResource>>;
 }>;
 
@@ -54,5 +62,11 @@ export function createReferenceFeatureInput(
         ? { ok: true as const, value: toReferenceView(result.value) }
         : result;
     },
+    async getResource(resourceId, context) {
+      const result = await gateway.get(resourceId, context);
+      return result.ok
+        ? { ok: true as const, value: toReferenceView(result.value) }
+        : result;
+    },
   });
 }

src/features/reference-feature/contracts/reference-feature-contract.js

@@ -7,6 +7,9 @@ export const referenceQueryKeys = Object.freeze({
   all: () => REFERENCE_NAMESPACE,
   list: (filters = {}) =>
     Object.freeze([...REFERENCE_NAMESPACE, "list", canonicalize(filters)]),
+  /** @param {string} resourceId */
+  detail: (resourceId) =>
+    Object.freeze([...REFERENCE_NAMESPACE, "detail", String(resourceId)]),
 });
 
 export const REFERENCE_FEATURE_CONTRACT = Object.freeze({
@@ -25,6 +28,45 @@ export const REFERENCE_FEATURE_CONTRACT = Object.freeze({
       navigationLabel: "Reference feature",
       navigationOrder: 50,
     }),
+    REFERENCE_RESOURCE_DETAIL: Object.freeze({
+      routeId: "REFERENCE_RESOURCE_DETAIL",
+      path: "/examples/reference-resources/:resourceId",
+      paramsSchema: "ReferenceResourceParams",
+      searchSchema: null,
+      access: "integration-defined",
+      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: "integration-defined",
+      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: "integration-defined",
+      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({
@@ -33,6 +75,24 @@ export const REFERENCE_FEATURE_CONTRACT = Object.freeze({
       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",
+    }),
   }),
   apiOperations: Object.freeze({
     LIST_REFERENCE_RESOURCES: Object.freeze({
@@ -61,6 +121,19 @@ export const REFERENCE_FEATURE_CONTRACT = Object.freeze({
       responseSchema: "ReferenceResourcePayload",
       owner: "feature-frontend-reference-feature-vertical-slice",
     }),
+    GET_REFERENCE_RESOURCE: Object.freeze({
+      method: "GET",
+      path: "/api/reference-resources/{resourceId}",
+      operationId: "GET_REFERENCE_RESOURCE",
+      auth: "external-session",
+      timeoutMs: null,
+      idempotency: "safe",
+      retry: "runtime",
+      requestSource: "none",
+      requestSchema: "NoRequest",
+      responseSchema: "ReferenceResourcePayload",
+      owner: "feature-frontend-form-page-platform",
+    }),
   }),
   queryRegistry: Object.freeze({
     REFERENCE_RESOURCE: Object.freeze({

src/features/reference-feature/contracts/reference-mapper.ts

@@ -33,7 +33,10 @@ export function mapReferenceOperation(
     if (!Array.isArray(payload)) throw new TypeError("Expected a reference list");
     return payload.map(mapReferenceDto);
   }
-  if (operationId === "CREATE_REFERENCE_RESOURCE") {
+  if (
+    operationId === "CREATE_REFERENCE_RESOURCE" ||
+    operationId === "GET_REFERENCE_RESOURCE"
+  ) {
     return mapReferenceDto(payload);
   }
   throw new TypeError(`No reference mapper registered for ${operationId}`);

src/features/reference-feature/contracts/reference-schemas.ts

@@ -18,6 +18,12 @@ export const referenceResourceListQuerySchema = z
   })
   .strict();
 
+export const referenceResourceParamsSchema = z
+  .object({
+    resourceId: z.string().trim().min(1).max(120),
+  })
+  .strict();
+
 const referenceResourceDtoSchema = z
   .object({
     id: z.string().min(1),
@@ -36,6 +42,7 @@ const requestSchemas = {
   CreateReferenceResourceCommand: z
     .object({
       name: z.string().trim().min(1).max(120),
+      note: z.string().trim().max(500).optional(),
     })
     .strict(),
 } satisfies Record<string, z.ZodType>;

src/features/reference-feature/presentation/reference-feature-runtime.tsx

@@ -1,9 +1,13 @@
 import { lazy } from "react";
 
-import { referenceResourceListQuerySchema } from "../contracts/reference-schemas.js";
+import {
+  referenceResourceListQuerySchema,
+  referenceResourceParamsSchema,
+} from "../contracts/reference-schemas.js";
 
 export const REFERENCE_FEATURE_ROUTE_CODECS = {
   ReferenceResourceListQuery: referenceResourceListQuerySchema,
+  ReferenceResourceParams: referenceResourceParamsSchema,
 } as const;
 
 export const REFERENCE_FEATURE_ROUTE_RUNTIME = {
@@ -11,4 +15,16 @@ export const REFERENCE_FEATURE_ROUTE_RUNTIME = {
     moduleId: "reference-resource-page",
     Component: lazy(() => import("./reference-resource-page.js")),
   }),
+  REFERENCE_RESOURCE_DETAIL: Object.freeze({
+    moduleId: "reference-resource-detail-page",
+    Component: lazy(() => import("./reference-resource-detail-page.js")),
+  }),
+  REFERENCE_RESOURCE_FORM: Object.freeze({
+    moduleId: "reference-resource-form-page",
+    Component: lazy(() => import("./reference-resource-form-page.js")),
+  }),
+  REFERENCE_RESOURCE_STATUS: Object.freeze({
+    moduleId: "reference-resource-status-page",
+    Component: lazy(() => import("./reference-resource-status-page.js")),
+  }),
 } as const;

src/features/reference-feature/presentation/reference-resource-detail-page.tsx

@@ -0,0 +1,47 @@
+import { Link } from "react-router-dom";
+
+import { AsyncSurface } from "../../../presentation/components/async-surface.jsx";
+import { DetailPage } from "../../../presentation/templates/index.js";
+import { useRouteInput } from "../../../presentation/routes/app-router.js";
+import { useReferenceDetail } from "./use-reference-feature.js";
+
+export default function ReferenceResourceDetailPage() {
+  const route = useRouteInput();
+  const resourceId = String(route.params.resourceId);
+  const { query } = useReferenceDetail(resourceId);
+  const resource = query.data;
+
+  return (
+    <DetailPage
+      key={resourceId}
+      breadcrumb={
+        <Link to="/examples/reference-resources">Reference resources</Link>
+      }
+      heading={{
+        eyebrow: "DetailPage",
+        title: resource?.title ?? "Reference detail",
+        description: "route param과 detail query의 reset 경계를 확인합니다.",
+      }}
+      metadata={
+        resource ? (
+          <dl>
+            <dt>Resource ID</dt>
+            <dd>{resource.resourceId}</dd>
+            <dt>Created</dt>
+            <dd>{resource.createdAtLabel ?? "표시 정보 없음"}</dd>
+          </dl>
+        ) : (
+          <p>요약 정보를 준비하고 있습니다.</p>
+        )
+      }
+      feedback={
+        <AsyncSurface state={query.state} onRetry={query.retry}>
+          {resource ? (
+            <p>이 영역에는 제품별 상세 section을 조립할 수 있습니다.</p>
+          ) : null}
+        </AsyncSurface>
+      }
+      aside={<p>상세 페이지의 관련 정보 slot입니다.</p>}
+    />
+  );
+}

src/features/reference-feature/presentation/reference-resource-form-page.tsx

@@ -0,0 +1,131 @@
+import { useCallback } from "react";
+import { useNavigate } from "react-router-dom";
+
+import { Button } from "../../../presentation/components/ui/button.jsx";
+import {
+  DirtyNavigationDialog,
+  ErrorSummary,
+  Form,
+  FormActions,
+  FormField,
+  useAppForm,
+  useDirtyNavigationGuard,
+} from "../../../presentation/forms/index.js";
+import { FormPage } from "../../../presentation/templates/index.js";
+import {
+  REFERENCE_FORM_DEFAULTS,
+  referenceResourceFormSchema,
+  toCreateReferenceCommand,
+  type ReferenceResourceFormValues,
+} from "./reference-resource-form.js";
+import { useReferenceCreate } from "./use-reference-feature.js";
+
+const FIELD_LABELS = Object.freeze({
+  name: "새 항목 이름",
+  note: "설명",
+}) satisfies Record<keyof ReferenceResourceFormValues, string>;
+
+export default function ReferenceResourceFormPage() {
+  const navigate = useNavigate();
+  const mutation = useReferenceCreate();
+  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 guard = useDirtyNavigationGuard(form.dirty && !form.pending);
+
+  return (
+    <Form
+      id={form.formId}
+      pending={form.pending}
+      onSubmit={(event) => void form.submitForm(event)}
+    >
+      <FormPage
+        breadcrumb={
+          <button
+            className="ui-button ui-button--ghost"
+            type="button"
+            onClick={() => navigate("/examples/reference-resources")}
+          >
+            목록으로 돌아가기
+          </button>
+        }
+        heading={{
+          eyebrow: "FormPage",
+          title: "Reference resource 만들기",
+          description:
+            "presentation schema, command mapper, 422/conflict와 dirty navigation 정책을 실행합니다.",
+        }}
+        errorSummary={
+          <ErrorSummary
+            fieldErrors={form.fieldErrors}
+            formErrors={form.formErrors}
+            fieldLabels={FIELD_LABELS}
+            fieldId={form.fieldId}
+            onFocusField={form.focusField}
+          />
+        }
+        fields={
+          <>
+            <FormField
+              {...form.field("name")}
+              label={FIELD_LABELS.name}
+              description="앞뒤 공백은 command mapper 전에 제거됩니다."
+              autoComplete="off"
+              required
+            />
+            <FormField
+              {...form.field("note")}
+              label={FIELD_LABELS.note}
+              description="선택 입력이며 비어 있으면 command에 포함되지 않습니다."
+              autoComplete="off"
+            />
+          </>
+        }
+        formActions={
+          <FormActions sticky>
+            <Button
+              variant="secondary"
+              onClick={() => navigate("/examples/reference-resources")}
+              disabled={form.pending}
+            >
+              취소
+            </Button>
+            <Button type="submit" disabled={form.pending}>
+              {form.pending ? "저장 중…" : "저장"}
+            </Button>
+            <Button
+              variant="ghost"
+              onClick={() => form.reset()}
+              disabled={!form.dirty || form.pending}
+            >
+              초기화
+            </Button>
+          </FormActions>
+        }
+        feedback={
+          form.result === "success" ? (
+            <p role="status">저장했습니다.</p>
+          ) : form.result === "conflict" ? (
+            <p role="status">충돌을 해결한 뒤 다시 제출할 수 있습니다.</p>
+          ) : null
+        }
+        aside={
+          <p>
+            form value는 URL, storage, telemetry에 저장되지 않고 submit 시에만
+            application command로 변환됩니다.
+          </p>
+        }
+        guard={<DirtyNavigationDialog guard={guard} />}
+      />
+    </Form>
+  );
+}

src/features/reference-feature/presentation/reference-resource-form.ts

@@ -0,0 +1,29 @@
+import { z } from "zod";
+
+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 } : {}),
+  });
+}

src/features/reference-feature/presentation/reference-resource-page.tsx

@@ -1,60 +1,53 @@
-import { useState, type FormEvent } from "react";
+import { Link, useNavigate } from "react-router-dom";
 
 import { AsyncSurface } from "../../../presentation/components/async-surface.jsx";
 import { Button } from "../../../presentation/components/ui/button.jsx";
-import { PageHeader } from "../../../presentation/components/page-header.jsx";
+import { CollectionPage } from "../../../presentation/templates/index.js";
 import { useReferenceFeature } from "./use-reference-feature.js";
 
 export default function ReferenceResourcePage() {
-  const { filters, query, mutation } = useReferenceFeature();
-  const [name, setName] = useState("");
-
-  async function submit(event: FormEvent<HTMLFormElement>) {
-    event.preventDefault();
-    const result = await mutation.submit({ name });
-    if (result.ok) setName("");
-  }
+  const navigate = useNavigate();
+  const { filters, query } = useReferenceFeature();
 
   return (
-    <section className="ui-page">
-      <PageHeader
-        eyebrow="제거 가능한 수직 슬라이스"
-        title="Reference feature"
-        description="URL codec, application input, HTTP/schema/mapper와 query/mutation 상태를 한 경로로 검증합니다."
-      />
-      <p data-testid="reference-filter">
-        limit {filters.limit}
-        {filters.tags?.length ? ` · tags ${filters.tags.join(", ")}` : ""}
-      </p>
+    <CollectionPage
+      heading={{
+        eyebrow: "제거 가능한 수직 슬라이스",
+        title: "Reference feature",
+        description:
+          "URL codec, application input, HTTP/schema/mapper와 query 상태를 한 경로로 검증합니다.",
+      }}
+      actions={[
+        {
+          kind: "button",
+          label: "새 항목 만들기",
+          onAction: () => navigate("/examples/reference-resources/new"),
+        },
+      ]}
+      activeFilters={
+        <p data-testid="reference-filter">
+          limit {filters.limit}
+          {filters.tags?.length ? ` · tags ${filters.tags.join(", ")}` : ""}
+        </p>
+      }
+      toolbar={<Button onClick={() => void query.retry()}>새로고침</Button>}
+      resultCount={
+        query.data ? `총 ${query.data.length}개 항목` : "결과 확인 중"
+      }
+    >
       <AsyncSurface state={query.state} onRetry={query.retry}>
         <ul aria-label="Reference resources">
           {(query.data ?? []).map((resource) => (
-            <li
-              key={resource.resourceId}
-              data-optimistic={resource.optimistic || undefined}
-            >
-              {resource.title}
+            <li key={resource.resourceId}>
+              <Link
+                to={`/examples/reference-resources/${encodeURIComponent(resource.resourceId)}`}
+              >
+                {resource.title}
+              </Link>
             </li>
           ))}
         </ul>
       </AsyncSurface>
-      <AsyncSurface
-        state={mutation.state}
-        onResolveConflict={mutation.resolveConflict}
-      >
-        <form onSubmit={(event) => void submit(event)}>
-          <label htmlFor="reference-resource-name">새 항목 이름</label>
-          <input
-            id="reference-resource-name"
-            value={name}
-            onChange={(event) => setName(event.currentTarget.value)}
-            required
-          />
-          <Button type="submit" disabled={mutation.state.overlay.mutationPending}>
-            추가
-          </Button>
-        </form>
-      </AsyncSurface>
-    </section>
+    </CollectionPage>
   );
 }

src/features/reference-feature/presentation/reference-resource-status-page.tsx

@@ -0,0 +1,25 @@
+import { useNavigate } from "react-router-dom";
+
+import { StatusPage } from "../../../presentation/templates/index.js";
+
+export default function ReferenceResourceStatusPage() {
+  const navigate = useNavigate();
+
+  return (
+    <StatusPage
+      variant="maintenance"
+      heading={{
+        eyebrow: "StatusPage · maintenance",
+        title: "잠시 사용할 수 없습니다.",
+        description:
+          "도메인 데이터나 raw 오류를 노출하지 않는 중립적인 상태 페이지 예시입니다.",
+      }}
+      primaryAction={{
+        kind: "button",
+        label: "목록으로 이동",
+        onAction: () => navigate("/examples/reference-resources"),
+      }}
+      supportReference="REFERENCE-STATUS-DEMO"
+    />
+  );
+}

src/features/reference-feature/presentation/use-reference-feature.ts

@@ -14,19 +14,38 @@ import type {
   ReferenceListFilters,
 } from "../application/reference-feature-api.js";
 
-function useReferenceFeatureInput(): ReferenceFeatureInput {
+export function useReferenceFeatureInput(): ReferenceFeatureInput {
   const candidate = useApplication().features.get(REFERENCE_FEATURE_ID);
   if (
     !candidate ||
     typeof candidate !== "object" ||
     typeof (candidate as ReferenceFeatureInput).listResources !== "function" ||
-    typeof (candidate as ReferenceFeatureInput).createResource !== "function"
+    typeof (candidate as ReferenceFeatureInput).createResource !== "function" ||
+    typeof (candidate as ReferenceFeatureInput).getResource !== "function"
   ) {
     throw new Error("Reference feature application input is invalid");
   }
   return candidate as ReferenceFeatureInput;
 }
 
+export function useReferenceDetail(resourceId: string) {
+  const input = useReferenceFeatureInput();
+  const query = useApplicationQuery({
+    queryKey: referenceQueryKeys.detail(resourceId),
+    execute: ({ signal }) => input.getResource(resourceId, { signal }),
+  });
+  return Object.freeze({ query });
+}
+
+export function useReferenceCreate() {
+  const input = useReferenceFeatureInput();
+  return useApplicationMutation({
+    execute: input.createResource,
+    invalidate: [referenceQueryKeys.all()],
+    currentData: true,
+  });
+}
+
 export function useReferenceFeature() {
   const input = useReferenceFeatureInput();
   const routeInput = useRouteInput();