fix(presentation): 검색값만 바뀌면 포커스·스크롤·진단을 건드리지 않는다 (08-02)

문제: RouteLifecycle이 pathname·search·navigationType을 effect 의존값으로
썼다. 그래서 URL에 묶은 필터를 바꾸면 포커스가 컨트롤에서 <main>으로
튀고, 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건이 수정 전 실패. 포커스가
  <main id="main-content">에 있었고 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
This commit is contained in:
DongHyeonka
2026-11-01 23:20:31 +09:00
parent 37e5f9d682
commit d0f3993b60
4 changed files with 83 additions and 8 deletions
@@ -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`의
+12 -3
View File
@@ -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;
}
+49 -3
View File
@@ -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(
<ApplicationProvider
application={createTestApplication({
session: createAnonymousSessionAdapter(),
session,
diagnostics,
...(productFeatures ? { productFeatures } : {}),
})}
@@ -202,6 +206,48 @@ describe("generic application router", () => {
},
);
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.
+18 -2
View File
@@ -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 <p>Fixture page</p>;
const [search, setSearch] = useSearchParams();
return (
<>
<p>Fixture page</p>
<label>
Fixture limit
<select
value={search.get("limit") ?? "20"}
onChange={(event) => setSearch({ limit: event.target.value })}
>
<option value="20">20</option>
<option value="50">50</option>
</select>
</label>
</>
);
}
export const FIXTURE_CONTEXT_ROUTES: readonly RouteObject[] = Object.freeze(