From 67117cc5a56d8c4d2a7859511ae871ea39c44bcf Mon Sep 17 00:00:00 2001 From: donghyeon-ka Date: Sun, 27 Sep 2026 13:11:25 +0900 Subject: [PATCH] fix(forms): show unavailable save failures as a status, not an input error (F-10) Save failures outside sign-in, permission and retry still went into ErrorSummary under "review the entered information". They now reach FormFailureStatus with their own copy and action; the unused copy is gone. Co-Authored-By: Claude Opus 5.5 --- .../decisions/VD-04-native-form-facade.md | 3 +- .../typescript-state-and-data-flow.md | 4 +-- src/presentation/forms/form-components.tsx | 2 +- src/presentation/forms/use-app-form.ts | 10 ++++-- src/presentation/i18n/catalog.ts | 2 -- tests/component/form-foundation.test.tsx | 34 +++++++++++++++++++ 6 files changed, 47 insertions(+), 8 deletions(-) diff --git a/docs/architecture/decisions/VD-04-native-form-facade.md b/docs/architecture/decisions/VD-04-native-form-facade.md index 958581c6..a27fa86e 100644 --- a/docs/architecture/decisions/VD-04-native-form-facade.md +++ b/docs/architecture/decisions/VD-04-native-form-facade.md @@ -30,7 +30,8 @@ field orchestration까지 플랫폼 기본값으로 고정하게 된다. layout과 state slot만 소유하며 application/query/HTTP를 import하지 않는다. 8. (2026-09-25, 08-01) 입력 오류가 아닌 저장 실패는 ErrorSummary에 넣지 않는다. `useAppForm`은 `action: "reauth"`를 `reauth-required`, `FORBIDDEN`을 `forbidden`, - `action: "retry"`를 `retry-later`로 구분하고 그 실패를 `failure`로 낸다. 화면은 + `action: "retry"`를 `retry-later`로, 나머지 입력 외 실패를 `unavailable`로 구분하고 + 그 실패를 `failure`로 낸다(F-10). 화면은 `FormFailureStatus`로 문구와 행동(로그인·이동·다시 시도)을 보여 준다. 재로그인은 입력을 지운다는 안내를 버튼 앞에 둔다(`src/presentation/forms/use-app-form.ts`, `form-components.tsx`). diff --git a/docs/architecture/typescript-state-and-data-flow.md b/docs/architecture/typescript-state-and-data-flow.md index 3c60cddf..9e77d838 100644 --- a/docs/architecture/typescript-state-and-data-flow.md +++ b/docs/architecture/typescript-state-and-data-flow.md @@ -599,7 +599,7 @@ Form 또는 TanStack Form adapter를 평가한다. - `Description` - `FieldError` - `ErrorSummary` -- `FormFailureStatus` (재로그인·권한 없음·잠시 후 재시도 저장 실패) +- `FormFailureStatus` (재로그인·권한 없음·잠시 후 재시도·그 밖의 저장 불가 실패) - `useAppForm` - `mapValidationFailureToFields` - `useDirtyNavigationGuard` @@ -623,7 +623,7 @@ backend message와 알 수 없는 path는 field copy로 사용하지 않는다. 3. submitting 중 중복 제출 방지 4. 422 응답의 알려진 field만 표시하고 나머지는 form-level failure로 처리 5. 409 conflict는 validation error로 위장하지 않음 -5a. 401·403·429 같은 입력 외 실패는 ErrorSummary가 아니라 `FormFailureStatus`로 표시 +5a. 401·403·429와 404 같은 입력 외 실패는 ErrorSummary가 아니라 `FormFailureStatus`로 표시(`use-app-form.ts`의 `STATUS_RESULTS`) 6. 취소와 route 이탈 시 dirty policy 적용 7. form value → application command mapper를 별도 함수로 둠 8. browser autofill, IME composition, paste, password manager를 방해하지 않음 diff --git a/src/presentation/forms/form-components.tsx b/src/presentation/forms/form-components.tsx index f87d771f..4b91fc2f 100644 --- a/src/presentation/forms/form-components.tsx +++ b/src/presentation/forms/form-components.tsx @@ -82,7 +82,7 @@ export function ErrorSummary(props: Readonly<{ /** * 08-01. A save that failed for a reason other than the input (sign-in, - * permission, retry later) is announced here with its own action, not in + * permission, retry later, unavailable) is announced here with its own action, not in * ErrorSummary. Pass `useAppForm().failure`. */ export function FormFailureStatus(props: Readonly<{ diff --git a/src/presentation/forms/use-app-form.ts b/src/presentation/forms/use-app-form.ts index bb6e5b7d..9cdbf74c 100644 --- a/src/presentation/forms/use-app-form.ts +++ b/src/presentation/forms/use-app-form.ts @@ -239,8 +239,10 @@ export function useAppForm< outcome.error.kind === "FORBIDDEN" ? "forbidden" : "retry-later", ); } else { + // F-10. Not an input error either: shown by FormFailureStatus. unknownSubmissionRef.current = null; - setFormErrors(["form.unavailable"]); + setFormErrors([]); + setStatusFailure(outcome.error); setResult("unavailable"); } }, @@ -350,7 +352,10 @@ export function useAppForm< formErrors, pending, result, - /** The save failure behind `reauth-required`, `forbidden` or `retry-later`. */ + /** + * The save failure behind `reauth-required`, `forbidden`, `retry-later` + * or `unavailable`. + */ failure: STATUS_RESULTS.has(result) ? statusFailure : null, field, fieldId, @@ -371,6 +376,7 @@ const STATUS_RESULTS: ReadonlySet = new Set([ "reauth-required", "forbidden", "retry-later", + "unavailable", ]); function issuesToFieldErrors( diff --git a/src/presentation/i18n/catalog.ts b/src/presentation/i18n/catalog.ts index dc6758ae..03a0f202 100644 --- a/src/presentation/i18n/catalog.ts +++ b/src/presentation/i18n/catalog.ts @@ -147,7 +147,6 @@ const PLATFORM_KO_MESSAGES = { "form.validation.configuration": "입력 구성을 다시 확인해 주세요.", "form.conflict": "다른 변경과 충돌했습니다. 입력은 유지되었으니 최신 상태를 확인해 주세요.", - "form.unavailable": "저장하지 못했습니다. 잠시 후 다시 시도해 주세요.", "form.reauthLosesInput": "다시 로그인하면 이 화면에 입력한 내용은 사라집니다. 필요하면 먼저 복사해 두세요.", "form.remaining": "{count}자 남음", @@ -347,7 +346,6 @@ const PLATFORM_EN_MESSAGES = { "form.validation.configuration": "Review the input configuration.", "form.conflict": "Another update conflicts with this change. Your input has been preserved.", - "form.unavailable": "The change could not be saved. Try again shortly.", "form.reauthLosesInput": "Signing in again clears what you entered on this page. Copy it first if you need it.", "form.remaining": "{count} characters remaining", diff --git a/tests/component/form-foundation.test.tsx b/tests/component/form-foundation.test.tsx index a91113f8..91000a81 100644 --- a/tests/component/form-foundation.test.tsx +++ b/tests/component/form-foundation.test.tsx @@ -202,6 +202,40 @@ describe("local form facade", () => { }, ); + // F-10 (08-01). A save that failed for a reason the user cannot fix in the + // input is a status with its own action, never an input error summary. + it.each([ + ["NOT_FOUND", "요청한 항목을 찾을 수 없습니다.", "안전한 화면으로 이동"], + ["UNKNOWN_CLIENT_FAILURE", "요청을 처리할 수 없습니다.", "지원 정보 확인"], + ] as const)( + "shows an unavailable %s save as a status, not an input error", + async (kind, copy, action) => { + const user = userEvent.setup(); + const onFailureAction = vi.fn(); + render( + ({ + ok: false, + error: createFailure(kind, "CREATE_ENTITY", 0, { + effect: "NOT_APPLIED", + }), + })} + onFailureAction={onFailureAction} + />, + ); + await user.type(screen.getByRole("textbox", { name: /Name/ }), "Valid"); + await user.click(screen.getByRole("button", { name: "Submit" })); + + expect(await screen.findByTestId("result")).toHaveTextContent( + "unavailable", + ); + expect(screen.getByRole("alert")).toHaveTextContent(copy); + expect(document.body).not.toHaveTextContent("입력 내용을 확인해 주세요."); + await user.click(screen.getByRole("button", { name: action })); + expect(onFailureAction).toHaveBeenCalledOnce(); + }, + ); + it("keeps conflict input out of URL and storage", async () => { const user = userEvent.setup(); localStorage.clear();