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),