From 58484935801fa9317451a2c800b87eed8b545dfa Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Thu, 24 Sep 2026 15:13:49 +0900 Subject: [PATCH] fix(presentation): show a disabled query as idle instead of empty (R3-4) A disabled query (no data, no error, not fetching) fell through deriveAsyncState to "empty", so AsyncSurface rendered the "no items" copy before the query had even started. - AsyncState.base gains "idle" for "not started / waiting on a precondition". A completed empty result (`[]`, `""`, `null`) stays "empty"; a real first load stays "initial-loading". - AsyncSurface renders an optional `idle` slot for idle, else nothing (no skeleton, no aria-busy, no empty copy, no children). Consumer-facing: AsyncState["base"] union adds "idle" (additive); AsyncSurface gains an optional `idle` prop. No in-repo exhaustive switch over base needed changes. RED (before the fix, node scripts/run-vitest.ts on the two files): application-query-bridge > disabled query: expected 'empty' to be 'idle' async-surface > derives base state 4 ({}): expected 'empty' to be 'idle' async-surface > idle renders neither loading nor empty: toBeEmptyDOMElement() received the empty-copy section Tests 3 failed | 25 passed (pins for first load, [] and null empty passed) Co-Authored-By: Claude Opus 5.5 --- src/application/view-models/async-state.ts | 10 +++--- src/presentation/components/async-surface.tsx | 4 +++ .../application-query-bridge.test.tsx | 16 +++++++++- tests/component/async-surface.test.tsx | 32 +++++++++++++++++++ 4 files changed, 57 insertions(+), 5 deletions(-) diff --git a/src/application/view-models/async-state.ts b/src/application/view-models/async-state.ts index ecea1f9f..3d573d7d 100644 --- a/src/application/view-models/async-state.ts +++ b/src/application/view-models/async-state.ts @@ -1,6 +1,7 @@ import type { AppFailure } from "../../contracts/errors.ts"; export const ASYNC_BASE_STATES = Object.freeze([ + "idle", "initial-loading", "success", "empty", @@ -91,13 +92,14 @@ export function deriveAsyncState(signals: AsyncSignals): AsyncState { ? "initial-loading" : signals.failure && !hasData ? "terminal-error" - : empty + : empty || signals.data === null ? "empty" : hasData ? "success" - : // Nothing loading, failed or present (a disabled query) is not - // a load in progress. - "empty"; + : // Nothing loading, failed or returned yet (a disabled query + // waiting on a precondition): not started, not a load or a + // completed empty result. + "idle"; const indicator = signals.hasMutationEffectUnknown && hasData diff --git a/src/presentation/components/async-surface.tsx b/src/presentation/components/async-surface.tsx index ee494478..08bde41e 100644 --- a/src/presentation/components/async-surface.tsx +++ b/src/presentation/components/async-surface.tsx @@ -91,6 +91,8 @@ export function TerminalErrorSurface({ export type AsyncSurfaceProps = Readonly<{ state: AsyncState; children?: ReactNode; + /** Shown while the query has not started (e.g. disabled); nothing if omitted. */ + idle?: ReactNode; onAction?: () => void; onRetry?: () => void; onResolveConflict?: () => void; @@ -102,12 +104,14 @@ export type AsyncSurfaceProps = Readonly<{ export function AsyncSurface({ state, children, + idle, onAction, onRetry, onResolveConflict, onReconcileUnknownEffect, }: AsyncSurfaceProps) { const { message } = useLocale(); + if (state.base === "idle") return idle ?? null; if (state.base === "initial-loading") return ; if (state.base === "empty") return ; if (state.base === "terminal-error" && state.failure) { diff --git a/tests/component/application-query-bridge.test.tsx b/tests/component/application-query-bridge.test.tsx index 03edce88..5044a926 100644 --- a/tests/component/application-query-bridge.test.tsx +++ b/tests/component/application-query-bridge.test.tsx @@ -124,10 +124,24 @@ describe("application query inbound bridge", () => { { wrapper: wrapper(client) }, ); - expect(hook.result.current.state.base).not.toBe("initial-loading"); + expect(hook.result.current.state.base).toBe("idle"); expect(execute).not.toHaveBeenCalled(); }); + it("reports a completed query without items as empty, not idle", async () => { + const client = queryClient(); + const hook = renderHook( + () => + useApplicationQuery({ + queryKey: ["resource", "completed-empty"], + execute: async () => ({ ok: true as const, value: [] as string[] }), + }), + { wrapper: wrapper(client) }, + ); + + await waitFor(() => expect(hook.result.current.state.base).toBe("empty")); + }); + it("still reports a real first load as loading, including a paused offline one", async () => { const client = queryClient(); const execute = vi.fn( diff --git a/tests/component/async-surface.test.tsx b/tests/component/async-surface.test.tsx index f1e1c392..24d1ddd0 100644 --- a/tests/component/async-surface.test.tsx +++ b/tests/component/async-surface.test.tsx @@ -13,6 +13,8 @@ describe("async UI state matrix", () => { [{ isInitialLoading: true }, "initial-loading"], [{ data: [{ id: "1" }] }, "success"], [{ data: [] }, "empty"], + [{ data: null }, "empty"], + [{}, "idle"], [ { failure: createFailure("SERVER_FAILURE", "LIST", 0) }, "terminal-error", @@ -185,6 +187,36 @@ describe("async UI state matrix", () => { expect(action).toHaveBeenCalledOnce(); }); + it("renders an idle query as neither loading nor empty", () => { + const { container, rerender } = render( + content, + ); + expect(container).toBeEmptyDOMElement(); + + rerender( + 조건을 먼저 선택하세요.

} + > + content +
, + ); + expect(screen.getByText("조건을 먼저 선택하세요.")).toBeVisible(); + expect(container.querySelector("[aria-busy]")).toBeNull(); + expect(screen.queryByText("표시할 항목이 없습니다.")).toBeNull(); + expect(screen.queryByText("content")).toBeNull(); + }); + + it("still renders loading for a first load and the empty copy for an empty result", () => { + const { container, rerender } = render( + , + ); + expect(container.querySelector('[aria-busy="true"]')).not.toBeNull(); + + rerender(); + expect(screen.getByText("표시할 항목이 없습니다.")).toBeVisible(); + }); + it("does not retain a terminal error after usable data is restored", () => { const failed = deriveAsyncState({ failure: createFailure("SERVER_FAILURE", "LIST", 0),