From 7420bafe49d00e6d9bf6416086ab5c967cfc0f1b Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Thu, 12 Nov 2026 22:53:23 +0900 Subject: [PATCH 01/10] =?UTF-8?q?fix(form):=20=EB=8B=A4=EC=8B=9C=20?= =?UTF-8?q?=EB=A7=88=EC=9A=B4=ED=8A=B8=ED=95=9C=20=ED=8F=BC=EC=9D=98=20?= =?UTF-8?q?=EC=9E=AC=EC=A0=84=EC=86=A1=EC=9D=B4=20=EB=B3=B4=EB=82=B4?= =?UTF-8?q?=EC=A7=80=20=EC=95=8A=EC=9D=80=20=ED=99=94=EB=A9=B4=20=EA=B0=92?= =?UTF-8?q?=EC=9D=84=20=EC=A0=80=EC=9E=A5=20=EA=B0=92=EC=9C=BC=EB=A1=9C=20?= =?UTF-8?q?=EC=93=B0=EC=A7=80=20=EC=95=8A=EB=8A=94=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 저장 결과가 불명인 채 페이지를 떠났다 돌아오면 폼은 새로 마운트되어 보낸 값을 모른다. 그때 resendUnknown은 화면 값을 제출 값으로 썼다 (unknownSubmissionRef ?? values). 재전송이 성공하면 기본 resetOnSuccess가 사용자가 돌아와 입력한, 보낸 적 없는 값을 지우거나 깨끗한 값으로 표시했다. 재전송이 쓰기 전에 거절되어 결과 불명에 남으면 그 화면 값을 보낸 값으로 기억해, 다음 「변경됨으로 확인」이 같은 일을 했다. 같은 상황의 settleApplied는 이미 화면 값과 dirty를 그대로 둔다(1106/08-01). 그 settleApplied 분기를 지키던 시험은 참조 기능 시험과 함께 지워졌다. 고른 방법: 결과 불명 기록을 { values: Values | null }로 바꿔 "보낸 값 모름"을 따로 둔다. 재전송은 그 값만 쓰고, 값을 모르면 성공·적용 확인을 settleApplied의 재마운트 분기와 같은 처리(settleUnsentValues)로 끝낸다. 기록이 남아 있는 동안 새 저장은 그대로 막는다. 버린 대안: 화면 값을 쓰되 성공 뒤 값을 되돌리기(사용자가 친 값을 잃는다). 위험·한계: 다시 마운트한 폼에서 결과 불명이 확인되기 전까지는 폼도 새 저장을 막는다(전에도 재전송이 불명으로 남으면 막았다). 결과 불명 상태를 코디네이터와 폼이 따로 갖는 구조(1112/01-01)는 결정 대기다. 검증: tests/component/form-foundation.test.tsx의 새 describe 셋 중 둘이 고치기 전 코드에서 실패하고 고친 뒤 통과한다(desktop, PR 본문). Refs: 1106/03-01, 1112/01-02, 1112/10-01 --- src/presentation/forms/use-app-form.ts | 64 ++++++++++++++------- tests/component/form-foundation.test.tsx | 73 ++++++++++++++++++++++++ 2 files changed, 116 insertions(+), 21 deletions(-) diff --git a/src/presentation/forms/use-app-form.ts b/src/presentation/forms/use-app-form.ts index 47abaea5..406b7300 100644 --- a/src/presentation/forms/use-app-form.ts +++ b/src/presentation/forms/use-app-form.ts @@ -111,7 +111,10 @@ export function useAppForm< const [result, setResult] = useState("idle"); const [statusFailure, setStatusFailure] = useState(null); const pendingRef = useRef | null> | null>(null); - const unknownSubmissionRef = useRef(null); + // The save whose effect is unknown: what it sent, or `values: null` when + // an earlier mount sent it (a resend from a remounted form). Held, it keeps + // a new save from going out as a new request. + const unknownSubmissionRef = useRef | null>(null); // 1103/08-02. A save that ends in neither a field error nor success shows // its status above the form while the page disables the button that had // focus, so the browser drops focus to the body. The status takes focus @@ -231,22 +234,30 @@ export function useAppForm< [defaultValues, resetOnSuccess], ); + /** + * The save went through, with values this form did not send: an earlier + * mount sent them. 1106/08-01. The confirmed save is shown, and focus, + * lost with the button that confirmed it, goes to the feedback area that + * shows it. The values on screen were never sent, so they and the dirty + * state stay as they are (diff review of 1106/08-01). + */ + const settleUnsentValues = useCallback(() => { + unknownSubmissionRef.current = null; + focusFeedbackRef.current = focusIsLost(); + setFieldErrors({} as FieldErrors); + setFormErrors([]); + setResult("success"); + }, []); + const settleApplied = useCallback(() => { - const submittedValues = unknownSubmissionRef.current; - if (!submittedValues) { - // 1106/08-01. After a remount the form no longer holds the submitted - // values. The confirmed save is shown, and focus, lost with the - // confirm button, goes to the feedback area that shows it. The values - // on screen were never sent, so they and the dirty state stay as they - // are (diff review of 1106/08-01). - focusFeedbackRef.current = focusIsLost(); - setFieldErrors({} as FieldErrors); - setFormErrors([]); - setResult("success"); + const submittedValues = unknownSubmissionRef.current?.values ?? null; + if (submittedValues === null) { + // After a remount the form no longer holds the submitted values. + settleUnsentValues(); return; } settleSuccessfulValues(submittedValues); - }, [settleSuccessfulValues]); + }, [settleSuccessfulValues, settleUnsentValues]); const settleNotApplied = useCallback(() => { if (!unknownSubmissionRef.current) return; @@ -256,10 +267,19 @@ export function useAppForm< setResult("idle"); }, []); + /** + * `submittedValues` is null when this form did not send the request the + * outcome answers (a resend after a remount): a success then keeps the + * values on screen, and a result left unknown holds no values either. + */ const applyOutcome = useCallback( - (outcome: FormResult, submittedValues: Values) => { + (outcome: FormResult, submittedValues: Values | null) => { + const settleSaved = () => + submittedValues === null + ? settleUnsentValues() + : settleSuccessfulValues(submittedValues); if (outcome.ok) { - settleSuccessfulValues(submittedValues); + settleSaved(); return; } const refusal = refusalFor(refusalMessages, outcome.error); @@ -303,13 +323,13 @@ export function useAppForm< setResult("reauth-required"); } else if (outcome.error.effect === "MAYBE_APPLIED") { focusFeedbackRef.current = true; - unknownSubmissionRef.current = submittedValues; + unknownSubmissionRef.current = { values: submittedValues }; setFormErrors([]); // 0929/08-04. Kept for its request id, not shown as a status. setStatusFailure(outcome.error); setResult("effect-unknown"); } else if (outcome.error.effect === "APPLIED_CONFIRMED") { - settleSuccessfulValues(submittedValues); + settleSaved(); } else if (outcome.error.kind === "CONFLICT") { focusFeedbackRef.current = true; unknownSubmissionRef.current = null; @@ -341,6 +361,7 @@ export function useAppForm< focusFirstError, refusalMessages, settleSuccessfulValues, + settleUnsentValues, ], ); @@ -421,15 +442,16 @@ export function useAppForm< send: () => Promise | null>, ): Promise | null> => { if (pendingRef.current) return pendingRef.current; - // After a remount the form no longer holds the submitted values. - const submittedValues = unknownSubmissionRef.current ?? values; + // After a remount the form no longer holds the submitted values, and + // the values on screen were never sent (1106/03-01 diff review FR-03). + const submittedValues = unknownSubmissionRef.current?.values ?? null; const resend = (async () => { setPending(true); try { const outcome = await send(); if (outcome && resendLeftUnknown(outcome)) { focusFeedbackRef.current = true; - unknownSubmissionRef.current = submittedValues; + unknownSubmissionRef.current = { values: submittedValues }; setFieldErrors({} as FieldErrors); setFormErrors(["form.resendLater"]); setResult("effect-unknown"); @@ -446,7 +468,7 @@ export function useAppForm< pendingRef.current = resend; return resend; }, - [applyOutcome, values], + [applyOutcome], ); return Object.freeze({ diff --git a/tests/component/form-foundation.test.tsx b/tests/component/form-foundation.test.tsx index 0b9d18b6..0324f8fd 100644 --- a/tests/component/form-foundation.test.tsx +++ b/tests/component/form-foundation.test.tsx @@ -165,6 +165,11 @@ function FormHarness(props: Readonly<{ >; resetOnSuccess?: boolean; onFailureAction?(): void; + /** Resends the save an earlier mount left unknown (`resendUnknown`). */ + resend?(): Promise< + | Readonly<{ ok: true; value: string }> + | Readonly<{ ok: false; error: ReturnType }> + >; }>) { const form = useAppForm({ schema, @@ -179,6 +184,7 @@ function FormHarness(props: Readonly<{ submit: props.submit, resetOnSuccess: props.resetOnSuccess, }); + const resend = props.resend; return (
void form.submitForm(event)}> + {resend ? ( + + ) : null} @@ -632,6 +641,70 @@ describe("local form facade", () => { }); }); +// 1106/08-01, 1106/03-01 (diff review FR-03), 1112/10-01. A page left while +// its save was unknown comes back with a new form: the coordinator still +// holds the unknown save, the form no longer knows the values it sent. The +// values on screen were typed after the save and never sent, so no way out +// of the unknown result may take them as the saved values: they and the +// dirty state stay as they are, and the leave guard still protects them. +describe("a form mounted again while its save is unknown", () => { + const leftUnknown = () => + Promise.resolve({ + ok: false as const, + error: createFailure("RATE_LIMITED", "CREATE_ENTITY", 0, { + effect: "NOT_APPLIED", + httpStatus: 429, + code: "RATE_LIMIT_EXCEEDED", + }), + }); + + it("keeps the values on screen when the earlier save is confirmed applied", async () => { + const user = userEvent.setup(); + const submit = vi.fn(); + render(); + await user.type(screen.getByRole("textbox", { name: /Name/ }), "Beta"); + + await user.click(screen.getByRole("button", { name: "Confirm applied" })); + + expect(screen.getByTestId("result")).toHaveTextContent("success"); + expect(screen.getByRole("textbox", { name: /Name/ })).toHaveValue("Beta"); + expect(screen.getByTestId("dirty")).toHaveTextContent("true"); + expect(submit).not.toHaveBeenCalled(); + }); + + it("keeps the values on screen when the resend succeeds", async () => { + const user = userEvent.setup(); + const resend = vi.fn(async () => ({ ok: true as const, value: "saved" })); + render(); + await user.type(screen.getByRole("textbox", { name: /Name/ }), "Beta"); + + await user.click(screen.getByRole("button", { name: "Resend" })); + + await waitFor(() => + expect(screen.getByTestId("result")).toHaveTextContent("success"), + ); + expect(resend).toHaveBeenCalledTimes(1); + expect(screen.getByRole("textbox", { name: /Name/ })).toHaveValue("Beta"); + expect(screen.getByTestId("dirty")).toHaveTextContent("true"); + }); + + it("keeps the values on screen when a resend left unknown is then confirmed applied", async () => { + const user = userEvent.setup(); + render(); + await user.type(screen.getByRole("textbox", { name: /Name/ }), "Beta"); + await user.click(screen.getByRole("button", { name: "Resend" })); + await waitFor(() => + expect(screen.getByTestId("result")).toHaveTextContent("effect-unknown"), + ); + + await user.click(screen.getByRole("button", { name: "Confirm applied" })); + + expect(screen.getByTestId("result")).toHaveTextContent("success"); + expect(screen.getByRole("textbox", { name: /Name/ })).toHaveValue("Beta"); + expect(screen.getByTestId("dirty")).toHaveTextContent("true"); + }); +}); + // 1101/14.4. Every code the paired backend can put in a field error's // details[].code: clean-architecture-backend-template 5786126c, // ClientSafeValidationDetails.java RULES (18-42) and its INVALID fallback. -- 2.54.0 From 353bed7ac24ebd10376731733f76c556c772fc87 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Thu, 12 Nov 2026 22:53:40 +0900 Subject: [PATCH 02/10] =?UTF-8?q?fix(design-system):=20=EA=B3=B5=ED=86=B5?= =?UTF-8?q?=20primitive=EC=9D=98=20=ED=82=A4=EB=B3=B4=EB=93=9C=C2=B7?= =?UTF-8?q?=EB=B3=B4=EC=A1=B0=EA=B8=B0=EC=88=A0=20=EB=8F=99=EC=9E=91?= =?UTF-8?q?=EC=9D=84=20=EC=95=BD=EC=86=8D=EB=8C=80=EB=A1=9C=20=EB=A7=9E?= =?UTF-8?q?=EC=B6=98=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 공통 primitive가 디자인 시스템 설계 8.1·8.2절과 WCAG 2.2 AA 약속을 어긴다. - Popover가 이름 없는 role="dialog"를 그린다(1112/05-10). - Dialog 안의 Menu·Popover·Tooltip에서 Escape를 누르면 Dialog까지 닫힌다. Dialog가 안쪽이 처리한 Escape를 보지 않는다(05-11). - SearchField는 required 기호만, Checkbox는 상태만 있다(05-13). - Toast를 닫기 버튼으로 닫으면 포커스가 body로 떨어진다(05-14). - TextArea 글자 수가 (암묵 status)이라 글자마다 발표되고 입력과 이어지지 않는다(05-17). - 라우트 h1의 :focus outline 제거가 layer 순서로 키보드 :focus-visible 표시까지 지운다(05-02). Tooltip이 pointer-events: none과 틈 때문에 포인터를 설명 위로 옮기면 사라진다(1.4.13, 05-06). - 홈 readiness 목록이 role 없는 div에 aria-label을 단다(05-15). - fe-a11y·fe-ux 스킬이 제출 실패 때 오류 요약으로 포커스가 간다고 적는다. 코드는 첫 오류 필드로 보낸다(05-09). 고른 방법: Popover는 trigger id로 이름을 받는다. Popover·Tooltip은 Escape를 capture 단계에서 받아 preventDefault하고, Dialog는 기본 동작이 막힌 Escape(과 그 뒤 cancel)를 넘긴다. Tooltip은 보일 때(hover·focus)만 Escape를 가진다. 숨은 tooltip이 다른 Dialog의 Escape를 막지 않게 하려는 것이다. Toast 닫기는 다음 toast의 닫기 버튼, 없으면 toast로 들어오기 전 요소로 포커스를 돌린다. TextArea 글자 수는 aria-describedby로 잇고 0에 닿을 때만 따로 발표한다. h1은 :focus:not(:focus-visible)만 outline을 지운다. Tooltip은 보일 때만 포인터를 받고 ::before 다리로 틈을 메운다. 버린 대안: Dialog가 안쪽 layer 목록을 들고 Escape를 나누기(primitive끼리 묶인다). 위험·한계: native 가 막힌 keydown 뒤에도 cancel을 쏘는지는 브라우저마다 다를 수 있어, Dialog는 같은 task의 cancel 하나를 넘긴다. Toast가 돌려줄 요소가 지워졌으면 포커스를 옮기지 않는다. 시각 골든이 바뀌는지는 desktop test:visual로 본다. 검증: 새 component 시험(tests/component/design-system-a11y.test.tsx, starter-pages), e2e(app-shell focus ring, 세 엔진), storybook(tooltip hover)의 RED·GREEN은 desktop에서 돌려 PR 본문에 적는다. Refs: 1112/05-02, 1112/05-06, 1112/05-09, 1112/05-10, 1112/05-11, 1112/05-13, 1112/05-14, 1112/05-15, 1112/05-17 --- .claude/skills/fe-a11y/SKILL.md | 2 +- .claude/skills/fe-ux/SKILL.md | 2 +- .../design-system/primitives/checkbox.tsx | 6 +- .../design-system/primitives/dialog.tsx | 17 +- .../design-system/primitives/popover.tsx | 18 +- .../design-system/primitives/search-field.tsx | 3 + .../design-system/primitives/text-area.tsx | 73 +++--- .../design-system/primitives/toast.tsx | 35 ++- .../design-system/primitives/tooltip.tsx | 38 +++- src/presentation/pages/home-page.tsx | 2 +- src/presentation/styles/theme/primitives.css | 12 + src/presentation/styles/theme/templates.css | 4 +- tests/component/design-system-a11y.test.tsx | 212 ++++++++++++++++++ tests/component/starter-pages.test.tsx | 12 +- tests/e2e/app-shell.spec.ts | 24 ++ tests/storybook/galleries.spec.ts | 16 ++ 16 files changed, 424 insertions(+), 52 deletions(-) create mode 100644 tests/component/design-system-a11y.test.tsx diff --git a/.claude/skills/fe-a11y/SKILL.md b/.claude/skills/fe-a11y/SKILL.md index eb80cea5..98ef2c2e 100644 --- a/.claude/skills/fe-a11y/SKILL.md +++ b/.claude/skills/fe-a11y/SKILL.md @@ -51,7 +51,7 @@ paths: 폼 -- [ ] label·설명·오류가 같은 ID 체계와 `aria-describedby`로 연결된다(M5). required는 기호와 programmatic 상태를 함께 가진다. 제출 실패 시 오류 요약으로 포커스가 간다. — DS 8.3절 +- [ ] label·설명·오류가 같은 ID 체계와 `aria-describedby`로 연결된다(M5). required는 기호와 programmatic 상태를 함께 가진다. 입력 오류로 제출이 실패하면 첫 오류 필드로 포커스가 가고, 오류 요약은 그 필드들로 가는 링크다(`src/presentation/forms/use-app-form.ts` `focusFirstError`). 입력 오류가 아닌 실패는 feedback 자리가 포커스를 받는다. — DS 8.3절 - [ ] IME 조합 중에 검증하거나 제출하지 않는다. — DS 8.1절 시각 diff --git a/.claude/skills/fe-ux/SKILL.md b/.claude/skills/fe-ux/SKILL.md index 3cb18f56..afa7fc08 100644 --- a/.claude/skills/fe-ux/SKILL.md +++ b/.claude/skills/fe-ux/SKILL.md @@ -58,7 +58,7 @@ paths: 폼 -- [ ] label·설명·오류가 연결되고, 제출 실패 시 오류 요약으로 포커스가 가며, 요약 항목은 그 필드로 간다. — `docs/design/2026-07-26-design-system-platform-design.md` 8.3절 +- [ ] label·설명·오류가 연결되고, 입력 오류로 제출이 실패하면 첫 오류 필드로 포커스가 가며, 오류 요약 항목은 그 필드로 간다(`src/presentation/forms/use-app-form.ts` `focusFirstError`). — `docs/design/2026-07-26-design-system-platform-design.md` 8.3절 - [ ] 409를 검증 오류로 위장하지 않는다. 이탈 확인(`useDirtyNavigationGuard`)은 성공 저장 뒤 풀고 이동한다. — `docs/design/2026-07-26-typescript-state-and-data-flow-design.md` 8절, `docs/design/2026-07-26-routing-pages-and-patterns-design.md` 6.4절 - [ ] 자동 완성·IME·붙여넣기·비밀번호 관리자를 막지 않는다. 입력을 loading skeleton으로 덮지 않는다. — data-flow 8절 diff --git a/src/presentation/design-system/primitives/checkbox.tsx b/src/presentation/design-system/primitives/checkbox.tsx index bfce9843..b132724b 100644 --- a/src/presentation/design-system/primitives/checkbox.tsx +++ b/src/presentation/design-system/primitives/checkbox.tsx @@ -42,7 +42,11 @@ export const Checkbox = forwardRef( }} type="checkbox" /> - {label} + + {label} + {/* 1112/05-13. The symbol as Field draws it; the state is on the input. */} + {props.required ? : null} + {description ? (

diff --git a/src/presentation/design-system/primitives/dialog.tsx b/src/presentation/design-system/primitives/dialog.tsx index fcb0ea3b..8e1563d2 100644 --- a/src/presentation/design-system/primitives/dialog.tsx +++ b/src/presentation/design-system/primitives/dialog.tsx @@ -41,6 +41,7 @@ export const Dialog = forwardRef( const dialogRef = useRef(null); const previousFocusRef = useRef(null); const focusRestoreGenerationRef = useRef(0); + const innerEscapeRef = useRef(false); const titleId = useId(); const descriptionId = useId(); useImperativeHandle(forwardedRef, () => dialogRef.current!, []); @@ -103,16 +104,26 @@ export const Dialog = forwardRef( className={`ui-dialog ${className}`.trim()} onCancel={(event) => { event.preventDefault(); + // The Escape that fired this cancel closed an inner layer. + if (innerEscapeRef.current) return; onClose(); }} onClick={(event) => { if (event.target === event.currentTarget) onClose(); }} onKeyDown={(event) => { - if (event.key === "Escape") { - event.preventDefault(); - onClose(); + if (event.key !== "Escape") return; + // 1112/05-11. A Menu, Popover or Tooltip inside handled this Escape + // (it prevented the default): it closes that layer, not the Dialog. + if (event.defaultPrevented) { + innerEscapeRef.current = true; + globalThis.setTimeout(() => { + innerEscapeRef.current = false; + }, 0); + return; } + event.preventDefault(); + onClose(); }} ref={dialogRef} > diff --git a/src/presentation/design-system/primitives/popover.tsx b/src/presentation/design-system/primitives/popover.tsx index 98e1438d..27ec21d7 100644 --- a/src/presentation/design-system/primitives/popover.tsx +++ b/src/presentation/design-system/primitives/popover.tsx @@ -12,6 +12,7 @@ export function Popover({ triggerLabel, children }: PopoverProps) { const rootRef = useRef(null); const triggerRef = useRef(null); const contentId = useId(); + const triggerId = useId(); useEffect(() => { if (!open) return; @@ -24,17 +25,20 @@ export function Popover({ triggerLabel, children }: PopoverProps) { triggerRef.current?.focus(); } } + // Capture phase, and the default prevented: the Escape closes this + // layer only, not a Dialog around it (1112/05-11). function closeOnEscape(event: KeyboardEvent) { - if (event.key === "Escape") { + if (event.key === "Escape" && !event.defaultPrevented) { + event.preventDefault(); setOpen(false); triggerRef.current?.focus(); } } document.addEventListener("pointerdown", closeOutside); - document.addEventListener("keydown", closeOnEscape); + document.addEventListener("keydown", closeOnEscape, true); return () => { document.removeEventListener("pointerdown", closeOutside); - document.removeEventListener("keydown", closeOnEscape); + document.removeEventListener("keydown", closeOnEscape, true); }; }, [open]); @@ -43,6 +47,7 @@ export function Popover({ triggerLabel, children }: PopoverProps) { {open ? ( -