fix(a11y): 처리 중인 세션·상태 화면 버튼이 꺼지지 않고 포커스를 지킨다

셸 헤더의 세션 버튼과 로그인 안내(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
This commit is contained in:
DongHyeonka
2026-11-13 19:03:18 +09:00
parent ee95573f9b
commit 8bcecabc40
8 changed files with 147 additions and 21 deletions
@@ -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. */}
<IconButton
accessibleName={previousLabel}
disabled={page <= 1}
onClick={() => onChange(page - 1)}
aria-disabled={page <= 1 || undefined}
onClick={() => {
if (page > 1) onChange(page - 1);
}}
variant="secondary"
>
<PreviousDirectionalIcon />
@@ -52,8 +57,10 @@ export function Pagination(props: PaginationProps) {
)}
<IconButton
accessibleName={nextLabel}
disabled={page >= pageCount}
onClick={() => onChange(page + 1)}
aria-disabled={page >= pageCount || undefined}
onClick={() => {
if (page < pageCount) onChange(page + 1);
}}
variant="secondary"
>
<NextDirectionalIcon />
+3 -4
View File
@@ -93,7 +93,6 @@ export function AppShell() {
<SessionStatus />
{integrationAvailable ? (
<Button
disabled={sessionAction.pending}
onClick={() =>
sessionAction.run(
sessionState === "authenticated"
@@ -103,11 +102,11 @@ export function AppShell() {
: "sign-in",
)
}
pending={sessionAction.pending}
pendingLabel={message("common.processing")}
size="compact"
>
{sessionAction.pending
? message("common.processing")
: sessionActionLabel}
{sessionActionLabel}
</Button>
) : null}
</div>
@@ -3,6 +3,7 @@ import {
useContext,
useEffect,
useMemo,
useRef,
useState,
useSyncExternalStore,
type ReactNode,
@@ -23,6 +24,12 @@ export type SessionContextValue = Readonly<{
}>;
const SessionContext = createContext<SessionContextValue | null>(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<SessionContextValue>(
() =>
Object.freeze({
@@ -62,7 +70,11 @@ export function SessionProvider({
);
return (
<SessionContext.Provider value={value}>{children}</SessionContext.Provider>
<SessionContext.Provider value={value}>
<SessionActionGateContext.Provider value={actionGate}>
{children}
</SessionActionGateContext.Provider>
</SessionContext.Provider>
);
}
@@ -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<void> {
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);
}
}
+5 -6
View File
@@ -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"
+2 -1
View File
@@ -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);
}
@@ -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}
+56
View File
@@ -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 (
<Pagination
label="Pages"
nextLabel="Next"
onChange={(next) => {
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(<Controlled onChange={onChange} />);
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(<Controlled onChange={onChange} />);
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",
);
});
});
+36 -3
View File
@@ -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 () => {