-
+
{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(["비동기 데이터 상태", "접근과 탐색 상태"]);
+ });
+});