From 8bcecabc4016aa46d42524c5d3c3e6c7318d6548 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 13 Nov 2026 18:39:43 +0900 Subject: [PATCH] =?UTF-8?q?fix(a11y):=20=EC=B2=98=EB=A6=AC=20=EC=A4=91?= =?UTF-8?q?=EC=9D=B8=20=EC=84=B8=EC=85=98=C2=B7=EC=83=81=ED=83=9C=20?= =?UTF-8?q?=ED=99=94=EB=A9=B4=20=EB=B2=84=ED=8A=BC=EC=9D=B4=20=EA=BA=BC?= =?UTF-8?q?=EC=A7=80=EC=A7=80=20=EC=95=8A=EA=B3=A0=20=ED=8F=AC=EC=BB=A4?= =?UTF-8?q?=EC=8A=A4=EB=A5=BC=20=EC=A7=80=ED=82=A8=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 셸 헤더의 세션 버튼과 로그인 안내(StatusPage)의 로그인·복구 버튼이 처리 중에 `disabled`가 된다. 템플릿 action API(`PageActionDefinition`)에는 `pending`이 없어 상태 화면은 끄는 길밖에 없었다. 꺼진 버튼은 키보드 포커스를 잃는다. 키보드로 "로그인 시작"을 누르고 sign-in이 실패하면 실패 알림이 뜰 때 포커스는 이미 body에 있다(결함 패턴 C11). 모든 파생 서비스의 셸이 복제한다. 같은 모양으로 Pagination의 「이전」을 2쪽에서 누르면 1쪽이 되며 그 버튼이 꺼져 포커스가 떨어진다. 고른 방법: `PageActionDefinition` 버튼에 `pending`·`pendingLabel`을 더해 `Button`으로 넘긴다(추가만). 라우터 상태 화면과 셸 세션 버튼은 `disabled` 대신 `pending`을 쓴다. 버튼은 켜진 채 `aria-busy="true"`이고, 처리 중에 그 버튼이나 다른 세션 버튼(셸과 상태 화면)을 누르면 `useSessionAction().run`이 무시한다. `SessionProvider`가 세션 버튼 모두에 잠금 하나를 준다(중복 실행을 `disabled`에 기대지 않는다). Pagination 끝 버튼은 `aria-disabled`와 누름 무시로 바꾸고, 같은 모양(`.ui-button[aria-disabled="true"]`)으로 그린다. 버린 대안: `Button`의 `pending`이 클릭을 삼키게 하기(폼은 이미 자기 `pendingRef`로 막고, 공개 primitive의 동작이 바뀐다). 위험·한계: 다운스트림이 `PageActionDefinition`에 `disabled: pending`을 넘기고 있으면 그대로 동작하지만 포커스를 잃는다. `pending`으로 옮기면 된다. jsdom은 꺼진 버튼의 포커스를 떨어뜨리지 않아 component 시험은 `disabled`가 아님과 `aria-busy`, 실패 뒤 포커스를 본다. 검증: `tests/component/route-status-surfaces.test.tsx` 세 사례와 `tests/component/pagination.test.tsx` 끝 버튼 두 사례가 고치기 전 코드에서 실패하고 고친 뒤 통과한다(desktop, PR 본문). Refs: 1112/05-03, 1112/04-05 --- .../design-system/primitives/pagination.tsx | 15 +++-- src/presentation/layouts/app-shell.tsx | 7 +-- .../providers/session-provider.tsx | 26 ++++++++- src/presentation/routes/app-router.tsx | 11 ++-- src/presentation/styles/theme/primitives.css | 3 +- src/presentation/templates/page-templates.tsx | 11 ++++ tests/component/pagination.test.tsx | 56 +++++++++++++++++++ .../component/route-status-surfaces.test.tsx | 39 ++++++++++++- 8 files changed, 147 insertions(+), 21 deletions(-) diff --git a/src/presentation/design-system/primitives/pagination.tsx b/src/presentation/design-system/primitives/pagination.tsx index 82f9b46a..610a6e08 100644 --- a/src/presentation/design-system/primitives/pagination.tsx +++ b/src/presentation/design-system/primitives/pagination.tsx @@ -32,10 +32,15 @@ export function Pagination(props: PaginationProps) { className="ui-pagination" role={nested ? "group" : undefined} > + {/* At the first or last page the edge button is aria-disabled, not + disabled: pressing "previous" on page 2 must not drop keyboard focus + when it becomes the first page. */} onChange(page - 1)} + aria-disabled={page <= 1 || undefined} + onClick={() => { + if (page > 1) onChange(page - 1); + }} variant="secondary" > @@ -52,8 +57,10 @@ export function Pagination(props: PaginationProps) { )} = pageCount} - onClick={() => onChange(page + 1)} + aria-disabled={page >= pageCount || undefined} + onClick={() => { + if (page < pageCount) onChange(page + 1); + }} variant="secondary" > diff --git a/src/presentation/layouts/app-shell.tsx b/src/presentation/layouts/app-shell.tsx index bf59bebe..32d853f1 100644 --- a/src/presentation/layouts/app-shell.tsx +++ b/src/presentation/layouts/app-shell.tsx @@ -93,7 +93,6 @@ export function AppShell() { {integrationAvailable ? ( ) : null} diff --git a/src/presentation/providers/session-provider.tsx b/src/presentation/providers/session-provider.tsx index d74dd6de..e8201049 100644 --- a/src/presentation/providers/session-provider.tsx +++ b/src/presentation/providers/session-provider.tsx @@ -3,6 +3,7 @@ import { useContext, useEffect, useMemo, + useRef, useState, useSyncExternalStore, type ReactNode, @@ -23,6 +24,12 @@ export type SessionContextValue = Readonly<{ }>; const SessionContext = createContext(null); +/** + * 1112/05-03. Set while a session action runs, shared by every session + * button: the shell's and a status page's buttons stay enabled while pending, + * so a press on either is ignored until the action ends. + */ +const SessionActionGateContext = createContext<{ current: boolean } | null>(null); export function SessionProvider({ children, @@ -46,6 +53,7 @@ export function SessionProvider({ recoveryDeclined && ownerState === "recovery-pending" ? "unauthenticated" : ownerState; + const actionGate = useRef(false); const value = useMemo( () => Object.freeze({ @@ -62,7 +70,11 @@ export function SessionProvider({ ); return ( - {children} + + + {children} + + ); } @@ -77,8 +89,11 @@ export function useSession(): SessionContextValue { export type SessionAction = "sign-in" | "sign-out" | "recover"; /** - * One session action at a time, with the pending and failed state every - * session button shows. Sign-in returns to the current URL, hash included. + * One session action at a time across every session button, with the + * pending and failed state the pressed button shows. Sign-in returns to the + * current URL, hash included. A press while an action runs, on this button + * or another, is ignored: the buttons stay enabled (`pending`, not + * `disabled`) so keyboard focus survives the action. */ export function useSessionAction(): Readonly<{ pending: boolean; @@ -89,8 +104,12 @@ export function useSessionAction(): Readonly<{ const { beginSignIn, signOut, recover } = useSession(); const [pending, setPending] = useState(false); const [failed, setFailed] = useState(false); + const ownGate = useRef(false); + const running = useContext(SessionActionGateContext) ?? ownGate; async function execute(action: SessionAction): Promise { + if (running.current) return; + running.current = true; setPending(true); setFailed(false); try { @@ -100,6 +119,7 @@ export function useSessionAction(): Readonly<{ } catch { setFailed(true); } finally { + running.current = false; setPending(false); } } diff --git a/src/presentation/routes/app-router.tsx b/src/presentation/routes/app-router.tsx index d391d1a8..cb363ce3 100644 --- a/src/presentation/routes/app-router.tsx +++ b/src/presentation/routes/app-router.tsx @@ -288,12 +288,11 @@ function ProtectedRoute({ } primaryAction={{ kind: "button", - label: pending - ? message("common.processing") - : recovering - ? message("action.recoverSession") - : message("action.signIn"), - disabled: pending, + label: recovering + ? message("action.recoverSession") + : message("action.signIn"), + pending, + pendingLabel: message("common.processing"), onAction: () => run(recovering ? "recover" : "sign-in"), }} surface="authentication-required" diff --git a/src/presentation/styles/theme/primitives.css b/src/presentation/styles/theme/primitives.css index 191b9512..b95e4544 100644 --- a/src/presentation/styles/theme/primitives.css +++ b/src/presentation/styles/theme/primitives.css @@ -28,7 +28,8 @@ background: var(--button-primary-hover); } - .ui-button:disabled { + .ui-button:disabled, + .ui-button[aria-disabled="true"] { cursor: not-allowed; opacity: var(--opacity-disabled); } diff --git a/src/presentation/templates/page-templates.tsx b/src/presentation/templates/page-templates.tsx index bd697d9b..0488385d 100644 --- a/src/presentation/templates/page-templates.tsx +++ b/src/presentation/templates/page-templates.tsx @@ -21,6 +21,15 @@ export type PageActionDefinition = label: string; onAction(): void; disabled?: boolean; + /** + * Work started by this action is still running. The button stays + * focusable and is marked `aria-busy`; `disabled` would drop keyboard + * focus (`docs/manual/02-decision-tables.md` 6절). The action ignores + * repeated presses itself. + */ + pending?: boolean; + /** Label while `pending`; the button keeps `label` when omitted. */ + pendingLabel?: string; variant?: "primary" | "secondary" | "danger" | "ghost"; }> | (Readonly<{ @@ -286,6 +295,8 @@ function PageActionBar(props: Readonly<{ disabled={action.disabled} key={index} onClick={action.onAction} + pending={action.pending} + pendingLabel={action.pendingLabel} variant={action.variant} > {action.label} diff --git a/tests/component/pagination.test.tsx b/tests/component/pagination.test.tsx index e4ee9730..3e3804f4 100644 --- a/tests/component/pagination.test.tsx +++ b/tests/component/pagination.test.tsx @@ -1,6 +1,8 @@ // @vitest-environment jsdom import { fireEvent, render, screen, within } from "@testing-library/react"; +import userEvent from "@testing-library/user-event"; +import { useState } from "react"; import { describe, expect, it, vi } from "vitest"; import { Pagination } from "../../src/presentation/design-system/index.ts"; @@ -116,3 +118,57 @@ describe("Pagination modified clicks", () => { expect(onChange).toHaveBeenCalledWith(2); }); }); + +// 1112/05-03. Reaching the first or last page must not take keyboard focus +// away from the edge button the user just pressed. +describe("Pagination edge buttons", () => { + function Controlled(props: Readonly<{ onChange(page: number): void }>) { + const [page, setPage] = useState(2); + return ( + { + props.onChange(next); + setPage(next); + }} + page={page} + pageCount={3} + pageLabel={(candidate) => `Page ${candidate}`} + previousLabel="Previous" + /> + ); + } + + it("keeps focus on previous when it reaches the first page and ignores further presses", async () => { + const user = userEvent.setup(); + const onChange = vi.fn(); + render(); + + const previous = screen.getByRole("button", { name: "Previous" }); + await user.click(previous); + expect(onChange).toHaveBeenCalledWith(1); + expect(previous).not.toBeDisabled(); + expect(previous).toHaveAttribute("aria-disabled", "true"); + expect(previous).toHaveFocus(); + + await user.keyboard("{Enter}"); + expect(onChange).toHaveBeenCalledOnce(); + }); + + it("marks next at the last page the same way", async () => { + const user = userEvent.setup(); + const onChange = vi.fn(); + render(); + + const next = screen.getByRole("button", { name: "Next" }); + await user.click(next); + expect(next).toHaveAttribute("aria-disabled", "true"); + expect(next).toHaveFocus(); + await user.click(next); + expect(onChange).toHaveBeenCalledOnce(); + expect(screen.getByRole("button", { name: "Previous" })).not.toHaveAttribute( + "aria-disabled", + ); + }); +}); diff --git a/tests/component/route-status-surfaces.test.tsx b/tests/component/route-status-surfaces.test.tsx index ef5108a1..6eed9c63 100644 --- a/tests/component/route-status-surfaces.test.tsx +++ b/tests/component/route-status-surfaces.test.tsx @@ -96,13 +96,41 @@ describe("route-level status surfaces", () => { expect(beginSignIn).toHaveBeenCalledWith( "/fixture/items#results", ); - expect(screen.getByRole("button", { name: "처리 중…" })).toBeDisabled(); + // 1112/05-03: pending, not disabled, so keyboard focus stays on it. + const busy = screen.getByRole("button", { name: "처리 중…" }); + expect(busy).not.toBeDisabled(); + expect(busy).toHaveAttribute("aria-busy", "true"); + expect(busy).toHaveFocus(); + await user.keyboard("{Enter}"); + expect(beginSignIn).toHaveBeenCalledOnce(); pending.reject(new Error("identity provider unavailable")); expect(await screen.findByRole("alert")).toHaveTextContent( "세션 작업을 완료하지 못했습니다.", ); - expect(screen.getByRole("button", { name: "로그인 시작" })).toBeEnabled(); + const retry = screen.getByRole("button", { name: "로그인 시작" }); + expect(retry).toBe(busy); + expect(retry).toBeEnabled(); + expect(retry).not.toHaveAttribute("aria-busy"); + expect(retry).toHaveFocus(); + }); + + // 1112/05-03. The shell's button and the page's button share one action. + it("ignores the other session button while one session action runs", async () => { + const user = userEvent.setup(); + const pending = deferred(); + const beginSignIn = vi.fn(() => pending.promise); + renderApp("/fixture/items", { session: sessionWithSignIn(beginSignIn) }); + + const shellButton = await within(screen.getByRole("banner")).findByRole("button", { + name: "로그인", + }); + await user.click(await screen.findByRole("button", { name: "로그인 시작" })); + await user.click(shellButton); + expect(beginSignIn).toHaveBeenCalledOnce(); + + pending.reject(new Error("identity provider unavailable")); + expect(await screen.findByRole("button", { name: "로그인 시작" })).not.toHaveAttribute("aria-busy"); }); it("returns to the current URL with its hash from the shell session action", async () => { @@ -116,12 +144,17 @@ describe("route-level status surfaces", () => { await within(banner).findByRole("button", { name: "로그인" }), ); expect(beginSignIn).toHaveBeenCalledWith("/fixture/first#buttons"); - expect(within(banner).getByRole("button", { name: "처리 중…" })).toBeDisabled(); + const busy = within(banner).getByRole("button", { name: "처리 중…" }); + expect(busy).not.toBeDisabled(); + expect(busy).toHaveAttribute("aria-busy", "true"); + await user.click(busy); + expect(beginSignIn).toHaveBeenCalledOnce(); pending.reject(new Error("identity provider unavailable")); expect(await within(banner).findByRole("alert")).toHaveTextContent( "세션 작업을 완료하지 못했습니다.", ); + expect(within(banner).getByRole("button", { name: "로그인" })).toHaveFocus(); }); it("answers an unknown address with a home link that keeps the basename", async () => {