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:
DongHyeonka
2026-11-01 23:20:31 +09:00
parent 8ed5beb8fd
commit dda153b25e
8 changed files with 156 additions and 22 deletions
+32 -8
View File
@@ -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} />
),
});
+20 -4
View File
@@ -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}
/>
);
}