From 8bcecabc4016aa46d42524c5d3c3e6c7318d6548 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 13 Nov 2026 18:39:43 +0900 Subject: [PATCH 1/5] =?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 () => { -- 2.54.0 From d42ad073ee2cb36480146ba766f536a5a358f8a4 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 13 Nov 2026 18:40:13 +0900 Subject: [PATCH 2/5] =?UTF-8?q?fix(i18n):=20=EC=83=81=ED=83=9C=20=ED=99=94?= =?UTF-8?q?=EB=A9=B4=20=EB=AC=B8=EA=B5=AC=EB=A5=BC=20=EC=B5=9C=EC=A2=85=20?= =?UTF-8?q?=EC=82=AC=EC=9A=A9=EC=9E=90=20=EB=A7=90=EB=A1=9C=20=EC=93=B0?= =?UTF-8?q?=EA=B3=A0=20=EC=88=AB=EC=9E=90=C2=B7=EB=8B=A8=EC=88=98=ED=98=95?= =?UTF-8?q?=C2=B7=EB=AC=B8=EC=9E=A5=20=EC=A1=B0=EB=A6=BD=EC=9D=84=20catalo?= =?UTF-8?q?g=EC=97=90=20=EB=A7=A1=EA=B8=B4=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 화면 문구 셋이 어긋난다. - 상태 화면 문구가 템플릿 개발자용이다(04-01). 생성 기능은 모두 `session-required`라 로그인 전 최종 사용자에게 "이 화면은 인증 연동 지점을 확인하기 위한 보호 라우트입니다."가 보인다. 끈 기능 화면은 "코드에는 포함되어 있으며 운영자가 다시 켤 수 있습니다.", 연동 실패 화면은 "외부 인증 소유자가 연결되면…"이다. - 숫자를 locale formatter 없이 그린다(04-03). 생성 목록이 "총 12345개 항목"을 그리고, TextArea는 en에서 남은 1자도 "1 characters remaining"이다. - ko·en 뜻이 다르다(04-07). en `form.conflict`에 "최신 상태를 확인해 주세요"가 없고, en 문서 제목 "Page not found"와 h1 "Page not found."가 다르다. ErrorSummary가 번역 문장 사이에 JSX 글자 ": "를 넣는다. 고른 방법: 세 설명을 사용자 말("이 화면을 보려면 로그인해 주세요." 등)로 바꾸고 운영 설명은 뺐다. 생성 목록은 `useLocale().number(total)`을 넘긴다. TextArea는 `plural`로 `form.remaining.one`(en 단수)과 `form.remaining`을 고른다. en 충돌 문구에 행동을 더하고 not-found 제목을 h1과 같게 했다. 오류 요약 항목은 `form.errorSummary.item` "{label}: {message}"로 잇는다. 연동 실패 화면의 제목 "로그인 연동이 필요합니다."는 짝 백엔드 매뉴얼이 그 글자로 가리켜 그대로 뒀다. 검증 V4가 반박한 부분(세 화면에 행동 버튼이 없다, ProgressBar `%`)은 고치지 않았다: 셸 탐색이 늘 있고, `%`는 ko·en 결과가 같다. 위험·한계: 다운스트림이 이 키의 옛 문장을 시험으로 고정했으면 문장을 바꾼다. 이미 생성한 기능의 목록 페이지는 `count: query.data.total`을 그대로 갖는다. `number(query.data.total)`로 바꾸면 된다(생성 명령의 새 출력과 같다). 검증: `tests/unit/i18n-contract.test.ts`(개발자 낱말, not-found 제목, 항목 문장), `tests/component/design-system-a11y.test.tsx`(en 단수·복수), `tests/unit/create-feature.test.ts`(생성 목록의 `number(`)가 고치기 전에 실패하고 고친 뒤 통과한다. 생성 기능 시험의 total 12345 → "총 12,345개 항목"은 FE-GATE-005가 돌린다(desktop, PR 본문). Refs: 1112/04-01, 1112/04-03, 1112/04-07 --- scripts/create-feature.ts | 11 ++++--- .../design-system/primitives/text-area.tsx | 7 ++-- src/presentation/forms/form-components.tsx | 7 ++-- src/presentation/i18n/catalog.ts | 20 +++++++----- src/presentation/i18n/message-contract.ts | 1 + tests/component/design-system-a11y.test.tsx | 24 ++++++++++++++ tests/component/router.test.tsx | 2 +- tests/unit/create-feature.test.ts | 5 +-- tests/unit/i18n-contract.test.ts | 32 +++++++++++++++++++ 9 files changed, 90 insertions(+), 19 deletions(-) diff --git a/scripts/create-feature.ts b/scripts/create-feature.ts index a68fe5a2..5d4c39bf 100644 --- a/scripts/create-feature.ts +++ b/scripts/create-feature.ts @@ -1182,7 +1182,7 @@ ${write ? `import { ${camel}RouteUrl } from "./${base}-routes.ts";\n` : ""}impor * the page heading. */ export default function ${pascal}ListPage() { - const { message } = useLocale(); + const { message, number } = useLocale(); const query = use${pascal}Items(); return ( @@ -1348,13 +1350,14 @@ describe("${names.id} list page through the router", () => { HttpResponse.json({ success: true, data: [{ id: "item-1", name: "First item" }], - meta: { page: { number: 0, size: 20, total: 41, sort: null } }, + meta: { page: { number: 0, size: 20, total: 12345, sort: null } }, }), ), ); await openList(); - expect(await screen.findByText("총 41개 항목")).toBeVisible(); + // 1112/04-03. The count is a locale-formatted number. + expect(await screen.findByText("총 12,345개 항목")).toBeVisible(); }); // The backend answers an empty list as \`data: []\`, never by dropping \`data\`. diff --git a/src/presentation/design-system/primitives/text-area.tsx b/src/presentation/design-system/primitives/text-area.tsx index 99e4beac..e31d4dc7 100644 --- a/src/presentation/design-system/primitives/text-area.tsx +++ b/src/presentation/design-system/primitives/text-area.tsx @@ -27,7 +27,7 @@ export const TextArea = forwardRef( }, ref, ) { - const { message } = useLocale(); + const { message, plural } = useLocale(); const [uncontrolledValue, setUncontrolledValue] = useState( String(defaultValue ?? ""), ); @@ -55,7 +55,10 @@ export const TextArea = forwardRef( ? null : maxLengthMessage ? maxLengthMessage(remaining) - : message("form.remaining", { count: remaining }); + : plural(remaining, { + one: message("form.remaining.one", { count: remaining }), + other: message("form.remaining", { count: remaining }), + }); return ( <>