Files
DongHyeonka b96d61d8f7 feat(examples)!: 예제 화면 3개를 끌 수 있는 기능으로 옮긴다
문제
/examples/ui, /examples/states, /examples/auth(와 /examples/platform)는
플랫폼 라우트 레지스트리에 고정이었다. VITE_PRODUCT_FEATURES와
FEATURE_OVERRIDES는 기능만 빼므로 제품은 이 화면을 끌 수 없었다.
릴리스 게이트 FE-GATE-028은 ROUTE_REGISTRY의 모든 라우트에 서명된
수동 접근성 기록을 요구해서, 제품은 템플릿 갤러리를 운영 메뉴에 두고
서명하거나 템플릿 파일 5개와 src/presentation/examples/를 지워야 했다.

고른 방법
- UI 갤러리·화면 상태·인증 연동을 platform-examples-feature로 옮겼다.
  자기 context platform-examples-context(루트 examples/*)에 산다.
  reference-context의 examples/reference-resources/*와 플랫폼 라우트
  /examples/platform이 더 구체적이라 그 URL은 그대로 간다.
- 라우트 ID·경로·청크 ID·표면은 바꾸지 않았다. 시각·e2e 테스트와 a11y
  기록(artifacts/tests/a11y-manual/EXAMPLES_*.md)이 그대로 이 이름을
  쓴다. 기능을 빼면 a11y 목록은 ROUTE_REGISTRY에서 오므로 같이 빠진다.
- 실행부는 비어 있다(스키마·adapter·계약 기여 없음). 페이지는 context
  routes에서 페이지마다 lazy로 받는다.
- 플랫폼 구성 화면(EXAMPLES_PLATFORM)은 플랫폼 라우트로 남겼다. 처음에는
  같이 옮겼다. 같은 호스트·같은 부하(15~19)에서 d99301b와 번갈아 잰
  lab이 기능 라우트로는 443·432 ms FAIL이었다(d99301b 133·183 ms
  PASS). 기능 라우트의 첫 진입은 context routes 모듈을 받은 뒤에 페이지
  청크를 받는다(요청 추적: 939 B + 177 B 다음에 5,183 B + 3개). 페이지를
  routes 모듈에 정적으로 넣으면 릴리스 매니페스트의 routeChunks 계약
  (페이지마다 dynamic entry)이 깨진다. 15-01의 "예산을 올리지 않는다"를
  지키려고 이 한 화면은 남겼다.
- 홈 화면은 예제 라우트 ID를 적지 않는다. 내비게이션의 처음 세 화면을
  "{title} 보기"로 보여 준다. 템플릿에서는 예전과 같은 세 링크(플랫폼
  구성·UI 구성요소·화면 상태)가 나오고, 예제를 뺀 제품에서는 그 제품의
  화면이 나온다. home.starter.platform·ui·states 키를 home.starter.open
  하나로 바꿨다. VITE_PRODUCT_FEATURES=none 빌드 검사
  (product-feature-selection-build)가 홈 청크의 예제 라우트 ID를 잡았다.
- 예제 화면 component 테스트는 tests/features/platform-examples-feature/로
  옮겼다. 제거 드릴이 같이 지운다. runtime-adapters 테스트는 API가 있는
  기능만 센다(예제 기능은 API가 없다). context-route-roots 테스트의
  "플랫폼 라우트와 같은 경로" 예는 /examples/platform으로 바꿨다.
- old-tab-chunk-recovery e2e는 페이지 소스를 빌드 A의 Vite manifest에서
  찾는다(기능 폴더 이름을 적지 않음). UI 갤러리가 기능 라우트라 B 탭이
  잃는 청크는 그 context routes 모듈이다. 허용 패턴에 넣었다.
- 예제 화면 문구는 08-07대로 한국어 고정이다. 화면 문구 ESLint 규칙의
  예외에 새 폴더를 넣었다.
- 버린 대안: 빌드 변수로 숨김(선택 장치가 하나 더 생김), 예제 화면만
  제품이 지우게 둠(동기화 충돌 자리가 남음).

위험·한계
- 공개 경로가 바뀌었다. src/presentation/examples/{ui-gallery,
  state-gallery,auth-example}-page.tsx, PLATFORM_ROUTE_REGISTRY·
  PLATFORM_ROUTE_RUNTIME(_CONTRACT)의 EXAMPLES_UI·STATES·AUTH,
  home.starter.platform/ui/states 키를 쓰던 다운스트림은 깨진다.
- 플랫폼 구성 화면은 여전히 끌 수 없고 FE-GATE-028 서명 대상이다.
- tests/e2e와 tests/visual의 여러 spec이 예제 화면을 자기 페이지로 쓴다.
  예제를 뺀 제품은 그 spec을 자기 화면으로 바꾸거나 지워야 한다
  (starter-experience.md에 적음). 제거 드릴은 브라우저 테스트를 돌리지
  않아 이것을 보지 않는다.
- 예제 기능 제거 드릴은 16-02(빈 ciScripts로 CI 기준선 사유가 공백)
  때문에 그대로는 시작하자마자 실패한다. 아래 드릴 결과는 그 한 줄을
  임시로 고친 상태에서 낸 것이다(커밋하지 않음).
- 기능 라우트 첫 진입이 이 lab 조건에서 약 430 ms라는 것은 어느 게이트도
  재지 않는다.

검증
- product-feature-selection-build(VITE_PRODUCT_FEATURES=none 빌드):
  홈 청크의 예제 라우트 ID 3건으로 실패한 것을 확인하고 홈 화면을 고친
  뒤 통과.
- test:sample-removal -- --feature=platform-examples-feature(heavy lock,
  16-02 한 줄 임시 패치): PASS, 13 checks(typecheck, architecture,
  registries, test:all, coverage, test-evidence, ci, home-smoke, build,
  route-absent, 잔여 ID 0). 첫 시도에서는 lab-performance 단위 테스트가
  측정 라우트 조회가 포트 검사보다 먼저여서 실패했다(그 뒤 이 변경에서
  측정 라우트를 플랫폼에 남겨 조회 변경 자체를 뺐다).
- test:unit 2,587, test:component 253, tests/features·platform·
  architecture 383 통과. check:types, lint, check:architecture,
  check:i18n, check:registries(additive), verify:documentation 통과.
- test:e2e 세 엔진 187 passed, 3 skipped(Firefox SW quarantine).
  old-tab-chunk-recovery 포함. test:a11y 60 passed.
- build + check:bundle: 초기 JS 201,940 / 204,800 B(+92 B).
- lab(측정 라우트를 기능으로 옮긴 시도): 443·432 ms FAIL, 같은 묶음
  d99301b 133·183 ms PASS(부하 15~19). 남긴 뒤 136·134 ms PASS.

Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-04
BREAKING CHANGE: 예제 라우트 EXAMPLES_UI·EXAMPLES_STATES·EXAMPLES_AUTH가
플랫폼 레지스트리에서 platform-examples-feature로 옮겨졌다. 페이지 파일은
src/features/platform-examples-feature/presentation/으로 갔고,
PLATFORM_ROUTE_REGISTRY·PLATFORM_ROUTE_RUNTIME_CONTRACT·
PLATFORM_ROUTE_RUNTIME에 이 키들이 없다. 홈 문구 키
home.starter.platform·ui·states는 home.starter.open({title})로 바뀌었다.
예제를 지운 다운스트림은 이 기능 폴더와 context를 지우면 된다.
2026-11-04 22:59:03 +09:00

228 lines
9.1 KiB
TypeScript

// @vitest-environment jsdom
import { render, screen, waitFor, within } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import { describe, expect, it } from "vitest";
import UiGalleryPage from "../../../src/features/platform-examples-feature/presentation/ui-gallery-page.tsx";
import { LocaleProvider } from "../../../src/presentation/i18n/index.ts";
/**
* A starter screen (0929/10-02): `/examples/ui` is template content
* (`platform-examples-feature`, 1103/09-04), and this file goes with it. The primitives have
* their own suites; this one checks what the page wires them to — the
* validation rule, the shared notice line and the show/hide state.
*/
function renderPage() {
const user = userEvent.setup();
const view = render(
<LocaleProvider>
<UiGalleryPage />
</LocaleProvider>,
);
// The Alert is a status too; the page's notice line is the `<output>`.
const notice = view.container.querySelector("output.gallery-notice");
if (!(notice instanceof HTMLOutputElement)) {
throw new Error("The gallery notice output is missing");
}
return { user, notice };
}
describe("starter UI gallery page", () => {
it("renders every gallery section and the colour token swatches", () => {
const { notice } = renderPage();
expect(
screen.getByRole("heading", { level: 1, name: "UI 구성요소" }),
).toBeVisible();
for (const section of [
"버튼과 입력",
"폼과 선택 컨트롤",
"피드백과 모달",
"탐색 패턴",
"디자인 토큰",
]) {
expect(screen.getByRole("region", { name: section })).toBeVisible();
}
const tokens = screen.getByRole("region", { name: "디자인 토큰" });
expect(within(tokens).getAllByRole("article")).toHaveLength(7);
expect(within(tokens).getByText("--color-focus")).toBeVisible();
expect(notice).toHaveAttribute("aria-live", "polite");
expect(notice).toHaveTextContent(
"구성요소를 조작하면 결과가 여기에 표시됩니다.",
);
});
it("reports each button action on the notice line", async () => {
const { user, notice } = renderPage();
await user.click(screen.getByRole("button", { name: "기본 작업" }));
expect(notice).toHaveTextContent("기본 작업을 실행했습니다.");
await user.click(screen.getByRole("button", { name: "보조 작업" }));
expect(notice).toHaveTextContent("보조 작업을 실행했습니다.");
await user.click(screen.getByRole("button", { name: "위험 작업" }));
expect(notice).toHaveTextContent("위험 작업 예제를 선택했습니다.");
expect(screen.getByRole("button", { name: "사용 불가" })).toBeDisabled();
});
it("rejects a blank project name and accepts a trimmed one", async () => {
const { user, notice } = renderPage();
const field = screen.getByRole("textbox", { name: "프로젝트 이름" });
const submit = screen.getByRole("button", { name: "입력 확인" });
// Untouched: no error yet, even though the field is empty.
expect(field).not.toHaveAttribute("aria-invalid", "true");
await user.click(submit);
expect(field).toHaveAttribute("aria-invalid", "true");
expect(field).toHaveAccessibleDescription(
/프로젝트 이름을 입력해 주세요\./u,
);
expect(notice).toHaveTextContent("입력값을 확인해 주세요.");
// Whitespace is still blank.
await user.type(field, " ");
await user.click(submit);
expect(field).toHaveAttribute("aria-invalid", "true");
await user.type(field, "Starter ");
expect(field).not.toHaveAttribute("aria-invalid", "true");
await user.click(submit);
expect(notice).toHaveTextContent("“Starter” 입력을 확인했습니다.");
});
it("keeps the form and choice controls controlled by page state", async () => {
const { user } = renderPage();
const description = screen.getByRole("textbox", { name: "설명" });
await user.type(description, "공통 예제");
expect(description).toHaveValue("공통 예제");
const template = screen.getByRole("combobox", { name: "시작 템플릿" });
expect(template).toHaveValue("application");
await user.selectOptions(template, "library");
expect(template).toHaveValue("library");
const reviewed = screen.getByRole("checkbox", {
name: "접근성 계약을 확인했습니다.",
});
expect(reviewed).not.toBeChecked();
await user.click(reviewed);
expect(reviewed).toBeChecked();
expect(screen.getByRole("radio", { name: "여유롭게" })).toBeChecked();
await user.click(screen.getByRole("radio", { name: "조밀하게" }));
expect(screen.getByRole("radio", { name: "조밀하게" })).toBeChecked();
expect(screen.getByRole("radio", { name: "여유롭게" })).not.toBeChecked();
const notifications = screen.getByRole("switch", { name: "알림 사용" });
expect(notifications).toBeChecked();
await user.click(notifications);
expect(notifications).not.toBeChecked();
// Native <progress value={3} max={4}>; the label shows the rounded share.
const readiness = screen.getByRole("progressbar", { name: "설정 준비도" });
expect(readiness).toHaveAttribute("value", "3");
expect(readiness).toHaveAttribute("max", "4");
expect(screen.getByText("75%")).toBeVisible();
});
it("dismisses the alert and shows it again", async () => {
const { user } = renderPage();
await user.click(
screen.getByRole("button", { name: "설정이 저장되었습니다. 알림 닫기" }),
);
expect(
screen.queryByText("설정이 저장되었습니다."),
).not.toBeInTheDocument();
await user.click(screen.getByRole("button", { name: "알림 다시 표시" }));
expect(screen.getByText("설정이 저장되었습니다.")).toBeVisible();
expect(
screen.queryByRole("button", { name: "알림 다시 표시" }),
).not.toBeInTheDocument();
});
it("closes the dialog by cancel, close and confirm, and only confirm reports", async () => {
const { user, notice } = renderPage();
const trigger = screen.getByRole("button", { name: "모달 열기" });
const initial = notice.textContent;
await user.click(trigger);
let dialog = screen.getByRole("dialog", { name: "연동 확인" });
expect(dialog).toHaveAttribute("open");
await user.click(within(dialog).getByRole("button", { name: "취소" }));
expect(screen.getByRole("dialog", { hidden: true })).not.toHaveAttribute(
"open",
);
expect(notice).toHaveTextContent(initial ?? "");
await waitFor(() => expect(trigger).toHaveFocus());
await user.click(trigger);
dialog = screen.getByRole("dialog", { name: "연동 확인" });
await user.click(
within(dialog).getByRole("button", { name: "연동 확인 닫기" }),
);
expect(screen.getByRole("dialog", { hidden: true })).not.toHaveAttribute(
"open",
);
expect(notice).toHaveTextContent(initial ?? "");
await user.click(trigger);
dialog = screen.getByRole("dialog", { name: "연동 확인" });
await user.click(within(dialog).getByRole("button", { name: "확인" }));
expect(screen.getByRole("dialog", { hidden: true })).not.toHaveAttribute(
"open",
);
expect(notice).toHaveTextContent("모달의 확인 작업을 실행했습니다.");
});
it("runs the menu actions: one reports on the notice, one pushes a toast", async () => {
const { user, notice } = renderPage();
const trigger = screen.getByRole("button", { name: "작업 메뉴" });
await user.click(trigger);
await user.click(screen.getByRole("menuitem", { name: "상태 확인" }));
expect(notice).toHaveTextContent("메뉴 작업을 실행했습니다.");
expect(screen.queryByRole("menu")).not.toBeInTheDocument();
await user.click(trigger);
await user.click(screen.getByRole("menuitem", { name: "Toast 표시" }));
const region = screen.getByRole("region", { name: "알림" });
expect(
within(region).getByText("예제가 저장되었습니다."),
).toBeVisible();
});
it("switches tab panels only on explicit activation", async () => {
const { user } = renderPage();
const tokens = screen.getByRole("tab", { name: "토큰" });
expect(tokens).toHaveAttribute("aria-selected", "true");
tokens.focus();
await user.keyboard("{ArrowRight}");
const primitives = screen.getByRole("tab", { name: "프리미티브" });
expect(primitives).toHaveFocus();
expect(primitives).toHaveAttribute("aria-selected", "false");
await user.keyboard("{Enter}");
expect(primitives).toHaveAttribute("aria-selected", "true");
expect(
screen.getByRole("tabpanel", { name: "프리미티브" }),
).toHaveTextContent("native semantics와 interaction을 닫습니다.");
});
it("describes the help button with its tooltip", async () => {
const { user } = renderPage();
const help = screen.getByRole("button", { name: "도움말" });
await user.hover(help);
expect(screen.getByRole("tooltip")).toHaveTextContent(
"이 설명은 필수 정보가 아닙니다.",
);
expect(help).toHaveAccessibleDescription("이 설명은 필수 정보가 아닙니다.");
});
});