From d0f3993b606fedee4a2e51675187552cf01fe815 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sun, 1 Nov 2026 21:58:58 +0900 Subject: [PATCH] =?UTF-8?q?fix(presentation):=20=EA=B2=80=EC=83=89?= =?UTF-8?q?=EA=B0=92=EB=A7=8C=20=EB=B0=94=EB=80=8C=EB=A9=B4=20=ED=8F=AC?= =?UTF-8?q?=EC=BB=A4=EC=8A=A4=C2=B7=EC=8A=A4=ED=81=AC=EB=A1=A4=C2=B7?= =?UTF-8?q?=EC=A7=84=EB=8B=A8=EC=9D=84=20=EA=B1=B4=EB=93=9C=EB=A6=AC?= =?UTF-8?q?=EC=A7=80=20=EC=95=8A=EB=8A=94=EB=8B=A4=20(08-02)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: RouteLifecycle이 pathname·search·navigationType을 effect 의존값으로 썼다. 그래서 URL에 묶은 필터를 바꾸면 포커스가 컨트롤에서
으로 튀고, POP이 아니면 맨 위로 스크롤하고, route.changed를 한 번 더 남겼다. 이미 보고 있는 화면의 링크를 눌러도(React Router가 REPLACE로 바꿈) navigationType만 바뀌어 같은 일이 났다. 템플릿은 필터를 URL에 두라고 권하므로 첫 목록 화면에서 바로 드러난다(WCAG 3.2.2). 고른 방법: 이동 판단을 route ID 또는 pathname 변경으로 좁혔다(리뷰 5.1 (B)). 포커스·스크롤·진단은 useEffectEvent로 옮겨 navigationType을 읽기만 하고 트리거로 쓰지 않는다. 검색값 변경에 맨 위가 필요한 화면(페이지 번호)은 그 화면이 직접 스크롤한다. routing 문서 6.3절에 규칙을 적었다. 버린 대안: (C) 라우트 계약에 searchChangeIsNavigation 선언 — 그런 라우트가 템플릿에 없고 생성기·문서까지 바뀐다. 필요해지면 (B) 위에 더할 수 있다. navigationType을 ref로 들고 있기 — 렌더 중 ref 쓰기라 React 19의 useEffectEvent보다 의도가 덜 드러난다. 위험·한계: 지금 검색값 변경을 이동으로 세던 대시보드가 있다면 수치가 준다. 실제 브라우저의 스크롤 유지는 jsdom이 스크롤을 건너뛰어 정적 확인만 했다. 테스트용 fixture 페이지에 URL에 묶은 select를 더했다. 검증: - RED: router.test.tsx 새 테스트 2건이 수정 전 실패. 포커스가
에 있었고 route.changed가 필터 테스트 1→3, 링크 테스트 1→2로 늘었다. - GREEN: router.test.tsx 11/11, tests/component 34 files 213 tests 통과. tsc(app, test) 통과, eslint(바꾼 파일) 통과, verify-documentation-readiness PASS_SCOPED. - check:architecture는 pnpm 실행을 요구해 이 worktree에서 미실행. Refs: docs/reviews/2026-11-01-maturity-review/08-presentation.md 08-02 --- .../routing-pages-and-patterns.md | 4 ++ src/presentation/routes/app-router.tsx | 15 ++++-- tests/component/router.test.tsx | 52 +++++++++++++++++-- tests/helpers/fixture-feature.tsx | 20 ++++++- 4 files changed, 83 insertions(+), 8 deletions(-) diff --git a/docs/architecture/routing-pages-and-patterns.md b/docs/architecture/routing-pages-and-patterns.md index 492db3b8..bb5cfe0c 100644 --- a/docs/architecture/routing-pages-and-patterns.md +++ b/docs/architecture/routing-pages-and-patterns.md @@ -306,6 +306,10 @@ custom fallback을 넘겨 retry/reset 기능을 잃지 않게 한다. boundary `RouteLifecycle`은 POP이 아닐 때만 top으로 보낸다(`app-router.tsx`). `PageHeader`의 heading focus는 `preventScroll`이라 복원된 위치를 옮기지 않는다 - 새 primary route는 top으로 이동 +- 라우트 이동은 route ID나 pathname이 바뀐 것만이다. 검색값만 바뀐 경우(URL에 묶은 + 필터)와 지금 주소를 가리키는 링크는 같은 화면의 입력이라 focus·scroll을 건드리지 + 않고 `route.changed`도 남기지 않는다(`RouteLifecycle`). 검색값 변경에 top이 + 필요한 화면(페이지 번호)은 그 화면이 직접 scroll한다 - hash target은 fixed header offset과 focus 가능 여부를 처리. 페이지가 그려진 뒤 `PageHeader`가 대상으로 스크롤하고, 대상이 focus 가능하면 대상에, 아니면 heading에 focus한다(`page-header.tsx`). header 높이는 `html`의 diff --git a/src/presentation/routes/app-router.tsx b/src/presentation/routes/app-router.tsx index 87691d33..1fbea994 100644 --- a/src/presentation/routes/app-router.tsx +++ b/src/presentation/routes/app-router.tsx @@ -3,6 +3,7 @@ import { type ReactNode, Suspense, useEffect, + useEffectEvent, useRef, useState, } from "react"; @@ -169,7 +170,7 @@ function RouteLifecycle({ definition: RouteDefinition; buildId: string; }) { - const { pathname, search } = useLocation(); + const { pathname } = useLocation(); const navigationType = useNavigationType(); const { message, resolve } = useLocale(); const diagnostics = useApplicationDiagnostics(); @@ -180,7 +181,7 @@ function RouteLifecycle({ appName: message("common.appName"), }); }, [definition, message, resolve]); - useEffect(() => { + const announceRoute = useEffectEvent(() => { const main = document.getElementById("main-content"); main?.focus({ preventScroll: true }); try { @@ -199,7 +200,15 @@ function RouteLifecycle({ routeId: definition.routeId, buildId, }); - }, [buildId, definition, diagnostics, navigationType, pathname, search]); + }); + // 08-02. Only a new route or path is a navigation. A query-only change + // (a filter bound to the URL) or a link to the current URL is input on the + // same screen: focus stays on the control, the scroll stays, and no + // route.changed is reported. A screen that wants the top on a query change + // (a page number) scrolls itself. + useEffect(() => { + announceRoute(); + }, [definition.routeId, pathname]); return null; } diff --git a/tests/component/router.test.tsx b/tests/component/router.test.tsx index 18026297..03cb000d 100644 --- a/tests/component/router.test.tsx +++ b/tests/component/router.test.tsx @@ -1,10 +1,13 @@ // @vitest-environment jsdom -import { act, render, screen, waitFor } from "@testing-library/react"; +import { act, render, screen, waitFor, within } from "@testing-library/react"; import userEvent from "@testing-library/user-event"; import { describe, expect, it, vi } from "vitest"; -import { createAnonymousSessionAdapter } from "../../src/adapters/auth/external-session-adapter.ts"; +import { + createAnonymousSessionAdapter, + createDemoSessionAdapter, +} from "../../src/adapters/auth/external-session-adapter.ts"; import type { ApplicationOutputPorts } from "../../src/application/create-application.ts"; import { INSTALLED_PRODUCT_FEATURE_IDS } from "../../src/features/installed-product-manifest.ts"; import { ApplicationProvider } from "../../src/presentation/providers/application-provider.tsx"; @@ -26,11 +29,12 @@ vi.mock("../../src/.generated/product-context-index.ts", async () => ({ function renderRouter( diagnostics: ApplicationOutputPorts["diagnostics"] = { record: () => {} }, productFeatures?: ApplicationOutputPorts["productFeatures"], + session: ApplicationOutputPorts["session"] = createAnonymousSessionAdapter(), ) { return render( { }, ); + it("keeps focus and scroll on a control that changes only the URL query", async () => { + // 08-02. A list filter bound to the query is input on the same screen + // (WCAG 3.2.2), not a route change: focus stays on the control and no + // second route.changed is reported. + const user = userEvent.setup(); + const record = vi.fn(); + window.history.pushState({}, "", "/fixture/items"); + renderRouter({ record }, undefined, createDemoSessionAdapter("authenticated")); + + const filter = await screen.findByLabelText("Fixture limit"); + await waitFor(() => expect(routeChangeReports(record)).toBe(1)); + await user.selectOptions(filter, "50"); + + await waitFor(() => expect(window.location.search).toBe("?limit=50")); + expect(filter).toHaveValue("50"); + expect(filter).toHaveFocus(); + expect(routeChangeReports(record)).toBe(1); + }); + + it("leaves focus on a link that names the page already shown", async () => { + // 08-02. React Router turns a link to the current URL into a REPLACE; the + // navigation type changes but the screen does not. + const user = userEvent.setup(); + const record = vi.fn(); + window.history.pushState({}, "", "/examples/ui"); + renderRouter({ record }); + + await waitFor(() => + expect( + screen.getByRole("heading", { name: "UI 구성요소", level: 1 }), + ).toHaveFocus(), + ); + const reportsBefore = routeChangeReports(record); + const link = within( + screen.getByRole("navigation", { name: "주요 탐색" }), + ).getByRole("link", { name: "UI 구성요소" }); + await user.click(link); + + expect(link).toHaveFocus(); + expect(routeChangeReports(record)).toBe(reportsBefore); + }); + it("ignores unknown query parameters on a platform route and keeps the URL", async () => { // D-16: `/?utm_source=x` or an OAuth callback parameter is not an invalid // address. The `none` codec drops it from the parsed input only. diff --git a/tests/helpers/fixture-feature.tsx b/tests/helpers/fixture-feature.tsx index 026bda41..8e5158ee 100644 --- a/tests/helpers/fixture-feature.tsx +++ b/tests/helpers/fixture-feature.tsx @@ -1,4 +1,4 @@ -import type { RouteObject } from "react-router-dom"; +import { type RouteObject, useSearchParams } from "react-router-dom"; import { z } from "zod"; import { defineBoundedContextModule } from "../../src/contexts/bounded-context-module.ts"; @@ -107,8 +107,24 @@ const FIXTURE_ROUTE_CODECS = Object.freeze({ }), }); +/** A filter bound to the URL query, the way a product list screen keeps it. */ function FixturePage() { - return

Fixture page

; + const [search, setSearch] = useSearchParams(); + return ( + <> +

Fixture page

+ + + ); } export const FIXTURE_CONTEXT_ROUTES: readonly RouteObject[] = Object.freeze(