From dda153b25ed13eb84b3ab564e6dd6608a36127d7 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sun, 1 Nov 2026 22:49:15 +0900 Subject: [PATCH] =?UTF-8?q?feat(presentation):=20=EC=83=81=ED=83=9C=20?= =?UTF-8?q?=ED=99=94=EB=A9=B4=EA=B3=BC=20=EC=98=A4=EB=A5=98=20=EC=9A=94?= =?UTF-8?q?=EC=95=BD=EC=9D=B4=20=EC=A0=9C=EB=AA=A9=20=EC=88=98=EC=A4=80?= =?UTF-8?q?=EC=9D=84=20=EB=B0=9B=EB=8A=94=EB=8B=A4=20(08-05)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: EmptySurface, TerminalErrorSurface, 접근 상태 화면, ErrorSummary의 제목이 h2로 고정돼 있다. Card(h3)나 상세 구획(h2) 안에 넣으면 그 안의 상태 문구가 카드 제목보다 상위 제목이 된다. /examples/states에서 h3 카드 안에 h2가 있었고, 섹션 h2 아래 접근 상태 화면도 h2였다. 상태 화면 제목을

로 바꾸는 변이(M5)를 잡는 테스트도 없었다. 고른 방법: Card에 이미 있는 계약을 그대로 옮겼다. 위 네 컴포넌트에 headingLevel?: 2 | 3 | 4(기본 2)를 더하고, 이들을 그리는 AsyncSurface와 AccessSurface가 같은 prop을 넘긴다(그러지 않으면 가장 흔한 진입점에서 뒤집힘이 남는다). 타입은 state-surfaces.tsx의 HeadingLevel 하나에 둔다. 갤러리는 카드 안 상태에 4, 섹션 바로 아래 접근 상태에 3을 준다. 상태·오류 요약 CSS 선택자는 :is(h2, h3, h4)로 넓혔다. 공개 prop은 추가만 했고 기본값이 그대로라 기존 화면은 바뀌지 않는다. 버린 대안: 제목 수준 context(R7) — 모든 컨테이너가 제공자를 둬야 하고 Card의 prop 계약과 갈린다. Card의 인라인 2 | 3 | 4와 HeadingLevel을 합치는 것은 VD-05 재수출 경로를 건드려 이번 범위에서 뺐다. 위험·한계: 갤러리 화면이 바뀐다(카드 안 상태 제목 h4 16px, 접근 상태 h3 20px). 시각 골든은 오케스트레이터가 갱신한다. 실제 스크린 리더 제목 목록은 확인하지 않았다(접근성 트리 대신 component 단언). 검증: - RED: async-surface.test.tsx 새 테스트 7건이 수정 전 실패(예: "expected [

] to have a length of +0 but got 1"). - GREEN: async-surface.test.tsx 31/31, tests/component 220/220(4회 반복 통과, 부하 32에서 첫 실행 1건 실패 뒤 재현 안 됨). tsc app·test 통과, eslint 통과. e2e accessibility·typography·reference-form·reference-save chromium 27/27. Refs: docs/reviews/2026-11-01-maturity-review/08-presentation.md 08-05 --- src/presentation/components/async-surface.tsx | 40 +++++++-- .../components/state-surfaces.tsx | 24 +++++- .../patterns/common-patterns.tsx | 15 ++-- .../examples/state-gallery-page.tsx | 7 +- src/presentation/forms/form-components.tsx | 7 +- src/presentation/styles/theme/pages.css | 2 +- src/presentation/styles/theme/templates.css | 2 +- tests/component/async-surface.test.tsx | 81 ++++++++++++++++++- 8 files changed, 156 insertions(+), 22 deletions(-) diff --git a/src/presentation/components/async-surface.tsx b/src/presentation/components/async-surface.tsx index 834fd8a9..ca2cde83 100644 --- a/src/presentation/components/async-surface.tsx +++ b/src/presentation/components/async-surface.tsx @@ -7,6 +7,7 @@ import { errorMessage } from "./error-copy.ts"; import { AuthRequiredSurface, ForbiddenSurface, + type HeadingLevel, NotFoundSurface, } from "./state-surfaces.tsx"; import { Button } from "./ui/button.ts"; @@ -39,17 +40,21 @@ export type EmptySurfaceProps = Readonly<{ title?: string; description?: string; action?: ReactNode; + /** 08-05. Below the heading of the card or section that holds it. */ + headingLevel?: HeadingLevel | undefined; }>; export function EmptySurface({ title, description, action, + headingLevel = 2, }: EmptySurfaceProps) { const { message } = useLocale(); + const Heading = `h${headingLevel}` as const; return (
-

{title ?? message("async.empty")}

+ {title ?? message("async.empty")} {description ?

{description}

: null} {action}
@@ -64,6 +69,8 @@ export type TerminalErrorSurfaceProps = Readonly<{ description?: string; /** 08-07. The id a user quotes to support, e.g. `AppFailure.requestId`. */ supportReference?: string; + /** 08-05. Below the heading of the card or section that holds it. */ + headingLevel?: HeadingLevel | undefined; }>; export function TerminalErrorSurface({ @@ -72,9 +79,11 @@ export function TerminalErrorSurface({ onAction, description, supportReference, + headingLevel = 2, }: TerminalErrorSurfaceProps) { const { locale, message } = useLocale(); const messageId = useId(); + const Heading = `h${headingLevel}` as const; const actionLabels: Readonly< Record, string> > = Object.freeze({ @@ -91,7 +100,7 @@ export function TerminalErrorSurface({ aria-labelledby={messageId} data-message-key={userMessageKey} > -

{errorMessage(userMessageKey, locale)}

+ {errorMessage(userMessageKey, locale)} {description ?

{description}

: null} {action !== "none" && onAction && ( @@ -119,6 +128,8 @@ export type AsyncSurfaceProps = Readonly<{ onReconcileUnknownEffect?: (resolution: "APPLIED") => void; /** D-1. Resends the unknown request with its original intent and key. */ onResendUnknownEffect?: () => void; + /** 08-05. Title level of the empty and failure surfaces it renders. */ + headingLevel?: HeadingLevel | undefined; }>; export function AsyncSurface({ @@ -130,11 +141,12 @@ export function AsyncSurface({ onResolveConflict, onReconcileUnknownEffect, onResendUnknownEffect, + headingLevel, }: AsyncSurfaceProps) { const { message } = useLocale(); if (state.base === "idle") return idle ?? null; if (state.base === "initial-loading") return ; - if (state.base === "empty") return ; + if (state.base === "empty") return ; if (state.base === "terminal-error" && state.failure) { const AccessState = ACCESS_SURFACES[state.failure.kind]; if (AccessState) { @@ -142,7 +154,7 @@ export function AsyncSurface({ // AccessSurface, so a query and the gallery show one copy. return (
- + {state.failure.requestId ? (

{message("template.supportReference", { @@ -163,6 +175,7 @@ export function AsyncSurface({ : onAction } supportReference={state.failure.requestId} + headingLevel={headingLevel} /> ); } @@ -215,11 +228,22 @@ const ACCESS_SURFACES: Readonly< Partial< Record< AppFailure["kind"], - (props: Readonly<{ onAction?: () => void }>) => ReactNode + ( + props: Readonly<{ + onAction?: () => void; + headingLevel?: HeadingLevel | undefined; + }>, + ) => ReactNode > > > = Object.freeze({ - AUTH_REQUIRED: ({ onAction }) => , - FORBIDDEN: ({ onAction }) => , - NOT_FOUND: ({ onAction }) => , + AUTH_REQUIRED: ({ onAction, headingLevel }) => ( + + ), + FORBIDDEN: ({ onAction, headingLevel }) => ( + + ), + NOT_FOUND: ({ onAction, headingLevel }) => ( + + ), }); diff --git a/src/presentation/components/state-surfaces.tsx b/src/presentation/components/state-surfaces.tsx index c7400d5d..d090a99a 100644 --- a/src/presentation/components/state-surfaces.tsx +++ b/src/presentation/components/state-surfaces.tsx @@ -1,6 +1,13 @@ import { useLocale } from "../i18n/index.ts"; import { Button } from "./ui/button.ts"; +/** + * 08-05. The level of a state surface's title. A surface placed inside a card + * or a page section passes the level below that container's heading, so the + * heading outline stays in order. Card has the same contract. + */ +export type HeadingLevel = 2 | 3 | 4; + type StateSurfaceProps = Readonly<{ eyebrow: string; title: string; @@ -8,6 +15,7 @@ type StateSurfaceProps = Readonly<{ actionLabel?: string; onAction?: () => void; tone?: "neutral" | "danger" | "warning"; + headingLevel?: HeadingLevel | undefined; }>; function StateSurface({ @@ -17,11 +25,13 @@ function StateSurface({ actionLabel, onAction, tone = "neutral", + headingLevel = 2, }: StateSurfaceProps) { + const Heading = `h${headingLevel}` as const; return (

{eyebrow}

-

{title}

+ {title}

{description}

{actionLabel && onAction ? ( @@ -32,7 +42,8 @@ function StateSurface({ export function AuthRequiredSurface({ onSignIn, -}: Readonly<{ onSignIn?: () => void }>) { + headingLevel, +}: Readonly<{ onSignIn?: () => void; headingLevel?: HeadingLevel | undefined }>) { const { message } = useLocale(); return ( ); } export function ForbiddenSurface({ onNavigate, -}: Readonly<{ onNavigate?: () => void }>) { + headingLevel, +}: Readonly<{ onNavigate?: () => void; headingLevel?: HeadingLevel | undefined }>) { const { message } = useLocale(); return ( ); } export function NotFoundSurface({ onNavigate, -}: Readonly<{ onNavigate?: () => void }>) { + headingLevel, +}: Readonly<{ onNavigate?: () => void; headingLevel?: HeadingLevel | undefined }>) { const { message } = useLocale(); return ( ); } diff --git a/src/presentation/design-system/patterns/common-patterns.tsx b/src/presentation/design-system/patterns/common-patterns.tsx index c9843dce..f8a2beb5 100644 --- a/src/presentation/design-system/patterns/common-patterns.tsx +++ b/src/presentation/design-system/patterns/common-patterns.tsx @@ -3,6 +3,7 @@ import { useId } from "react"; import { AuthRequiredSurface, ForbiddenSurface, + type HeadingLevel, NotFoundSurface, } from "../../components/state-surfaces.tsx"; import { Button } from "../primitives/core.tsx"; @@ -129,17 +130,21 @@ export function DisclosureGroup({ ); } -export type AccessSurfaceProps = +export type AccessSurfaceProps = ( | Readonly<{ kind: "auth-required"; onAction(): void }> | Readonly<{ kind: "forbidden"; onAction(): void }> - | Readonly<{ kind: "not-found"; onAction(): void }>; + | Readonly<{ kind: "not-found"; onAction(): void }> +) & + /** 08-05. Below the heading of the card or section that holds it. */ + Readonly<{ headingLevel?: HeadingLevel | undefined }>; export function AccessSurface(props: AccessSurfaceProps) { + const { headingLevel } = props; if (props.kind === "auth-required") { - return ; + return ; } if (props.kind === "forbidden") { - return ; + return ; } - return ; + return ; } diff --git a/src/presentation/examples/state-gallery-page.tsx b/src/presentation/examples/state-gallery-page.tsx index f0ed3646..7c808fa3 100644 --- a/src/presentation/examples/state-gallery-page.tsx +++ b/src/presentation/examples/state-gallery-page.tsx @@ -41,12 +41,13 @@ export default function StateGalleryPage() { - +
기존 콘텐츠는 계속 표시됩니다.
setLastAction("로그인 연동 작업을 시작했습니다.")} /> setLastAction("접근 가능한 화면으로 이동합니다.")} /> setLastAction("시작 화면으로 이동합니다.")} />
diff --git a/src/presentation/forms/form-components.tsx b/src/presentation/forms/form-components.tsx index 4b91fc2f..2da44361 100644 --- a/src/presentation/forms/form-components.tsx +++ b/src/presentation/forms/form-components.tsx @@ -2,6 +2,7 @@ import { useId, type FormHTMLAttributes, type ReactNode } from "react"; import type { AppFailure } from "../../contracts/errors.ts"; import { TerminalErrorSurface } from "../components/async-surface.tsx"; +import type { HeadingLevel } from "../components/state-surfaces.tsx"; import { TextField } from "../components/ui/text-field.ts"; import { useLocale } from "../i18n/index.ts"; import type { @@ -33,6 +34,8 @@ export function ErrorSummary(props: Readonly<{ fieldLabels: Readonly, string>>; fieldId(name: FieldName): string; onFocusField?(name: FieldName): void; + /** 08-05. Below the heading of the card or section that holds it. */ + headingLevel?: HeadingLevel | undefined; }>) { const { message } = useLocale(); const { @@ -41,8 +44,10 @@ export function ErrorSummary(props: Readonly<{ fieldLabels, fieldId, onFocusField, + headingLevel = 2, } = props; const headingId = useId(); + const Heading = `h${headingLevel}` as const; const entries = Object.entries(fieldErrors) as [ FieldName, string, @@ -54,7 +59,7 @@ export function ErrorSummary(props: Readonly<{ role="alert" aria-labelledby={headingId} > -

{message("form.errorSummary")}

+ {message("form.errorSummary")} {entries.length > 0 ? (
    {entries.map(([name, message]) => ( diff --git a/src/presentation/styles/theme/pages.css b/src/presentation/styles/theme/pages.css index dc8c79c4..511d5b61 100644 --- a/src/presentation/styles/theme/pages.css +++ b/src/presentation/styles/theme/pages.css @@ -175,7 +175,7 @@ background: var(--color-surface); } - .state-surface h2, + .state-surface :is(h2, h3, h4), .state-surface p { margin-block-end: 0.75rem; } diff --git a/src/presentation/styles/theme/templates.css b/src/presentation/styles/theme/templates.css index 98141de3..a8cc1da2 100644 --- a/src/presentation/styles/theme/templates.css +++ b/src/presentation/styles/theme/templates.css @@ -124,7 +124,7 @@ background: var(--color-danger-surface); } - .form-error-summary h2 { + .form-error-summary :is(h2, h3, h4) { font-size: 1.1rem; } diff --git a/tests/component/async-surface.test.tsx b/tests/component/async-surface.test.tsx index 558cb74c..17cf151c 100644 --- a/tests/component/async-surface.test.tsx +++ b/tests/component/async-surface.test.tsx @@ -7,7 +7,13 @@ import { describe, expect, it, vi } from "vitest"; import { deriveAsyncState } from "../../src/application/view-models/async-state.ts"; import { AsyncSurface } from "../../src/presentation/components/async-surface.tsx"; import { createFailure } from "../../src/contracts/errors.ts"; -import { AccessSurface } from "../../src/presentation/design-system/index.ts"; +import { + AccessSurface, + EmptySurface, + ErrorSummary, + TerminalErrorSurface, +} from "../../src/presentation/design-system/index.ts"; +import StateGalleryPage from "../../src/presentation/examples/state-gallery-page.tsx"; describe("async UI state matrix", () => { it.each([ @@ -279,3 +285,76 @@ describe("async UI state matrix", () => { expect(recovered.failure).toBeUndefined(); }); }); + +describe("state surface titles (08-05)", () => { + const forbidden = createFailure("FORBIDDEN", "LIST", 0); + const unreachable = createFailure("NETWORK_UNREACHABLE", "LIST", 0); + + it.each([ + ["empty", (level?: 2 | 3 | 4) => ], + [ + "terminal error", + (level?: 2 | 3 | 4) => ( + + ), + ], + [ + "access", + (level?: 2 | 3 | 4) => ( + {}} headingLevel={level} /> + ), + ], + [ + "async empty", + (level?: 2 | 3 | 4) => ( + + ), + ], + [ + "async access failure", + (level?: 2 | 3 | 4) => ( + + ), + ], + [ + "form error summary", + (level?: 2 | 3 | 4) => ( + name} + headingLevel={level} + /> + ), + ], + ])("titles the %s surface as h2 unless placed deeper", (_, surface) => { + const { unmount } = render(surface()); + expect(screen.getAllByRole("heading", { level: 2 })).toHaveLength(1); + unmount(); + + render(surface(4)); + expect(screen.queryAllByRole("heading", { level: 2 })).toHaveLength(0); + expect(screen.getAllByRole("heading", { level: 4 })).toHaveLength(1); + }); + + it("nests the gallery's state titles under the card and section around them", () => { + render(); + + expect( + screen.getByRole("heading", { name: "아직 표시할 항목이 없습니다.", level: 4 }), + ).toBeVisible(); + expect(screen.getAllByRole("heading", { level: 3 }).map((h) => h.textContent)) + .toEqual(expect.arrayContaining(["빈 화면", "복구 가능한 오류"])); + // Access states sit directly under the section's h2. + expect( + screen.queryAllByRole("heading", { level: 2 }).map((h) => h.textContent), + ).toEqual(["비동기 데이터 상태", "접근과 탐색 상태"]); + }); +});