feat(presentation): 상태 화면과 오류 요약이 제목 수준을 받는다 (08-05)
문제: EmptySurface, TerminalErrorSurface, 접근 상태 화면, ErrorSummary의 제목이 h2로 고정돼 있다. Card(h3)나 상세 구획(h2) 안에 넣으면 그 안의 상태 문구가 카드 제목보다 상위 제목이 된다. /examples/states에서 h3 카드 안에 h2가 있었고, 섹션 h2 아래 접근 상태 화면도 h2였다. 상태 화면 제목을 <p>로 바꾸는 변이(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 [ <h2></h2> ] 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
This commit is contained in:
@@ -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 (
|
||||
<section className="ui-empty state-surface" aria-live="polite">
|
||||
<h2>{title ?? message("async.empty")}</h2>
|
||||
<Heading>{title ?? message("async.empty")}</Heading>
|
||||
{description ? <p>{description}</p> : null}
|
||||
{action}
|
||||
</section>
|
||||
@@ -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<Exclude<AppFailure["action"], "none">, string>
|
||||
> = Object.freeze({
|
||||
@@ -91,7 +100,7 @@ export function TerminalErrorSurface({
|
||||
aria-labelledby={messageId}
|
||||
data-message-key={userMessageKey}
|
||||
>
|
||||
<h2 id={messageId}>{errorMessage(userMessageKey, locale)}</h2>
|
||||
<Heading id={messageId}>{errorMessage(userMessageKey, locale)}</Heading>
|
||||
{description ? <p>{description}</p> : null}
|
||||
{action !== "none" && onAction && (
|
||||
<Button onClick={onAction}>{actionLabels[action]}</Button>
|
||||
@@ -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 <LoadingSurface />;
|
||||
if (state.base === "empty") return <EmptySurface />;
|
||||
if (state.base === "empty") return <EmptySurface headingLevel={headingLevel} />;
|
||||
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 (
|
||||
<div role="alert" data-message-key={state.failure.userMessageKey}>
|
||||
<AccessState onAction={onAction} />
|
||||
<AccessState onAction={onAction} headingLevel={headingLevel} />
|
||||
{state.failure.requestId ? (
|
||||
<p>
|
||||
{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 }) => <AuthRequiredSurface onSignIn={onAction} />,
|
||||
FORBIDDEN: ({ onAction }) => <ForbiddenSurface onNavigate={onAction} />,
|
||||
NOT_FOUND: ({ onAction }) => <NotFoundSurface onNavigate={onAction} />,
|
||||
AUTH_REQUIRED: ({ onAction, headingLevel }) => (
|
||||
<AuthRequiredSurface onSignIn={onAction} headingLevel={headingLevel} />
|
||||
),
|
||||
FORBIDDEN: ({ onAction, headingLevel }) => (
|
||||
<ForbiddenSurface onNavigate={onAction} headingLevel={headingLevel} />
|
||||
),
|
||||
NOT_FOUND: ({ onAction, headingLevel }) => (
|
||||
<NotFoundSurface onNavigate={onAction} headingLevel={headingLevel} />
|
||||
),
|
||||
});
|
||||
|
||||
@@ -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 (
|
||||
<section className={`state-surface state-surface--${tone}`}>
|
||||
<p className="state-surface__eyebrow">{eyebrow}</p>
|
||||
<h2>{title}</h2>
|
||||
<Heading>{title}</Heading>
|
||||
<p>{description}</p>
|
||||
{actionLabel && onAction ? (
|
||||
<Button onClick={onAction}>{actionLabel}</Button>
|
||||
@@ -32,7 +42,8 @@ function StateSurface({
|
||||
|
||||
export function AuthRequiredSurface({
|
||||
onSignIn,
|
||||
}: Readonly<{ onSignIn?: () => void }>) {
|
||||
headingLevel,
|
||||
}: Readonly<{ onSignIn?: () => void; headingLevel?: HeadingLevel | undefined }>) {
|
||||
const { message } = useLocale();
|
||||
return (
|
||||
<StateSurface
|
||||
@@ -41,13 +52,15 @@ export function AuthRequiredSurface({
|
||||
description={message("access.auth.description")}
|
||||
actionLabel={message("action.signIn")}
|
||||
onAction={onSignIn}
|
||||
headingLevel={headingLevel}
|
||||
/>
|
||||
);
|
||||
}
|
||||
|
||||
export function ForbiddenSurface({
|
||||
onNavigate,
|
||||
}: Readonly<{ onNavigate?: () => void }>) {
|
||||
headingLevel,
|
||||
}: Readonly<{ onNavigate?: () => void; headingLevel?: HeadingLevel | undefined }>) {
|
||||
const { message } = useLocale();
|
||||
return (
|
||||
<StateSurface
|
||||
@@ -57,13 +70,15 @@ export function ForbiddenSurface({
|
||||
actionLabel={message("action.navigateSafe")}
|
||||
onAction={onNavigate}
|
||||
tone="warning"
|
||||
headingLevel={headingLevel}
|
||||
/>
|
||||
);
|
||||
}
|
||||
|
||||
export function NotFoundSurface({
|
||||
onNavigate,
|
||||
}: Readonly<{ onNavigate?: () => void }>) {
|
||||
headingLevel,
|
||||
}: Readonly<{ onNavigate?: () => void; headingLevel?: HeadingLevel | undefined }>) {
|
||||
const { message } = useLocale();
|
||||
return (
|
||||
<StateSurface
|
||||
@@ -72,6 +87,7 @@ export function NotFoundSurface({
|
||||
description={message("access.notFound.description")}
|
||||
actionLabel={message("action.goHome")}
|
||||
onAction={onNavigate}
|
||||
headingLevel={headingLevel}
|
||||
/>
|
||||
);
|
||||
}
|
||||
|
||||
@@ -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 <AuthRequiredSurface onSignIn={props.onAction} />;
|
||||
return <AuthRequiredSurface onSignIn={props.onAction} headingLevel={headingLevel} />;
|
||||
}
|
||||
if (props.kind === "forbidden") {
|
||||
return <ForbiddenSurface onNavigate={props.onAction} />;
|
||||
return <ForbiddenSurface onNavigate={props.onAction} headingLevel={headingLevel} />;
|
||||
}
|
||||
return <NotFoundSurface onNavigate={props.onAction} />;
|
||||
return <NotFoundSurface onNavigate={props.onAction} headingLevel={headingLevel} />;
|
||||
}
|
||||
|
||||
@@ -41,12 +41,13 @@ export default function StateGalleryPage() {
|
||||
<LoadingSurface label="예제 데이터를 불러오는 중" />
|
||||
</Card>
|
||||
<Card title="백그라운드 갱신">
|
||||
<AsyncSurface state={refreshingState}>
|
||||
<AsyncSurface headingLevel={4} state={refreshingState}>
|
||||
<div className="state-preview-content">기존 콘텐츠는 계속 표시됩니다.</div>
|
||||
</AsyncSurface>
|
||||
</Card>
|
||||
<Card title="빈 화면">
|
||||
<EmptySurface
|
||||
headingLevel={4}
|
||||
title="아직 표시할 항목이 없습니다."
|
||||
description="첫 항목을 추가하거나 필터를 초기화할 수 있습니다."
|
||||
action={
|
||||
@@ -58,6 +59,7 @@ export default function StateGalleryPage() {
|
||||
</Card>
|
||||
<Card title="복구 가능한 오류">
|
||||
<TerminalErrorSurface
|
||||
headingLevel={4}
|
||||
userMessageKey={
|
||||
createFailure("NETWORK_UNREACHABLE", "EXAMPLE", 0)
|
||||
.userMessageKey
|
||||
@@ -76,12 +78,15 @@ export default function StateGalleryPage() {
|
||||
</header>
|
||||
<div className="component-grid component-grid--three">
|
||||
<AuthRequiredSurface
|
||||
headingLevel={3}
|
||||
onSignIn={() => setLastAction("로그인 연동 작업을 시작했습니다.")}
|
||||
/>
|
||||
<ForbiddenSurface
|
||||
headingLevel={3}
|
||||
onNavigate={() => setLastAction("접근 가능한 화면으로 이동합니다.")}
|
||||
/>
|
||||
<NotFoundSurface
|
||||
headingLevel={3}
|
||||
onNavigate={() => setLastAction("시작 화면으로 이동합니다.")}
|
||||
/>
|
||||
</div>
|
||||
|
||||
@@ -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<Values extends FormValues>(props: Readonly<{
|
||||
fieldLabels: Readonly<Record<FieldName<Values>, string>>;
|
||||
fieldId(name: FieldName<Values>): string;
|
||||
onFocusField?(name: FieldName<Values>): 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<Values extends FormValues>(props: Readonly<{
|
||||
fieldLabels,
|
||||
fieldId,
|
||||
onFocusField,
|
||||
headingLevel = 2,
|
||||
} = props;
|
||||
const headingId = useId();
|
||||
const Heading = `h${headingLevel}` as const;
|
||||
const entries = Object.entries(fieldErrors) as [
|
||||
FieldName<Values>,
|
||||
string,
|
||||
@@ -54,7 +59,7 @@ export function ErrorSummary<Values extends FormValues>(props: Readonly<{
|
||||
role="alert"
|
||||
aria-labelledby={headingId}
|
||||
>
|
||||
<h2 id={headingId}>{message("form.errorSummary")}</h2>
|
||||
<Heading id={headingId}>{message("form.errorSummary")}</Heading>
|
||||
{entries.length > 0 ? (
|
||||
<ul>
|
||||
{entries.map(([name, message]) => (
|
||||
|
||||
@@ -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;
|
||||
}
|
||||
|
||||
@@ -124,7 +124,7 @@
|
||||
background: var(--color-danger-surface);
|
||||
}
|
||||
|
||||
.form-error-summary h2 {
|
||||
.form-error-summary :is(h2, h3, h4) {
|
||||
font-size: 1.1rem;
|
||||
}
|
||||
|
||||
|
||||
@@ -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) => <EmptySurface title="빈 목록" headingLevel={level} />],
|
||||
[
|
||||
"terminal error",
|
||||
(level?: 2 | 3 | 4) => (
|
||||
<TerminalErrorSurface
|
||||
userMessageKey={unreachable.userMessageKey}
|
||||
action="none"
|
||||
headingLevel={level}
|
||||
/>
|
||||
),
|
||||
],
|
||||
[
|
||||
"access",
|
||||
(level?: 2 | 3 | 4) => (
|
||||
<AccessSurface kind="forbidden" onAction={() => {}} headingLevel={level} />
|
||||
),
|
||||
],
|
||||
[
|
||||
"async empty",
|
||||
(level?: 2 | 3 | 4) => (
|
||||
<AsyncSurface state={deriveAsyncState({ data: [] })} headingLevel={level} />
|
||||
),
|
||||
],
|
||||
[
|
||||
"async access failure",
|
||||
(level?: 2 | 3 | 4) => (
|
||||
<AsyncSurface
|
||||
state={deriveAsyncState({ failure: forbidden })}
|
||||
headingLevel={level}
|
||||
/>
|
||||
),
|
||||
],
|
||||
[
|
||||
"form error summary",
|
||||
(level?: 2 | 3 | 4) => (
|
||||
<ErrorSummary
|
||||
fieldErrors={{ name: "이름을 입력해 주세요." }}
|
||||
fieldLabels={{ name: "이름" }}
|
||||
fieldId={(name) => 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(<StateGalleryPage />);
|
||||
|
||||
expect(
|
||||
screen.getByRole("heading", { name: "아직 표시할 항목이 없습니다.", level: 4 }),
|
||||
).toBeVisible();
|
||||
expect(screen.getAllByRole("heading", { level: 3 }).map((h) => h.textContent))
|
||||
.toEqual(expect.arrayContaining(["빈 화면", "복구 가능한 오류"]));
|
||||
// Access states sit directly under the section's h2.
|
||||
expect(
|
||||
screen.queryAllByRole("heading", { level: 2 }).map((h) => h.textContent),
|
||||
).toEqual(["비동기 데이터 상태", "접근과 탐색 상태"]);
|
||||
});
|
||||
});
|
||||
|
||||
Reference in New Issue
Block a user