Implement a list page that never confuses empty data with loading or failure.

Build a DrillListPage around a useDrills() query result. The page must represent initial loading, initial failure, successful empty data, populated data, background refresh, and refresh failure as distinct user-visible states. A retry command must work after either kind of failure, and previously loaded rows must remain usable while a refresh is running or fails.

On the first request the page reserves the list area with a skeleton. If three drills load, those rows appear. Pressing Refresh keeps all three rows visible, adds a small Refreshing drills status, and disables only the refresh command. If that request fails, the rows remain and an inline notice says Refresh failed; showing the last successful result with a Retry command. A successful response containing [] renders the real empty state, never a spinner or error placeholder.

• data === undefined means no successful snapshot exists; [] is successful empty data.
• Initial loading may replace the page body, but background refresh must preserve the last successful rows.
• Initial failure and refresh failure need different presentations because only one has useful stale data.
• Expose status changes without stealing focus; use aria-busy and a polite status message.
• Retry must call the supplied refetch operation and must not create duplicate requests while one is active.
• Keep the list region height stable enough that switching among loading, empty, and populated states does not cause a large layout jump.

1. Treat the query result as a small state machine instead of testing truthiness in arbitrary JSX branches.
2. First decide whether a successful snapshot exists. Without one, the only valid screens are initial loading or initial error.
3. Once a snapshot exists, choose empty or populated from data.length; neither branch is replaced during isFetching.
4. Layer refresh progress and refresh errors onto the successful snapshot as secondary status, not as replacement screens.
5. Disable Refresh while fetching and reuse the same refetch command for initial and background recovery.
6. Test transitions, not just static renders: loading to empty, loading to data, data to refreshing, and data to refresh failure.

type Drill = { id: string; title: string };

type DrillQuery = {
  data: Drill[] | undefined;
  error: Error | null;
  isLoading: boolean;
  isFetching: boolean;
  refetch: () => Promise<unknown>;
};

function DrillListPage({ query }: { query: DrillQuery }) {
  const { data, error, isLoading, isFetching, refetch } = query;
  const hasSnapshot = data !== undefined;

  if (!hasSnapshot && isLoading) {
    return (
      <main aria-busy="true" aria-label="Drills">
        <h1>Drills</h1>
        <DrillListSkeleton rows={5} />
        <span className="sr-only" role="status">Loading drills</span>
      </main>
    );
  }

  if (!hasSnapshot) {
    return (
      <main aria-label="Drills">
        <h1>Drills</h1>
        <ErrorState
          title="Drills could not be loaded"
          message={error?.message ?? "Try the request again."}
          onRetry={() => void refetch()}
          retryDisabled={isFetching}
        />
      </main>
    );
  }

  const isEmpty = data.length === 0;

  return (
    <main aria-label="Drills" aria-busy={isFetching}>
      <header className="list-header">
        <h1>Drills</h1>
        <button
          type="button"
          disabled={isFetching}
          onClick={() => void refetch()}
        >
          {isFetching ? "Refreshing..." : "Refresh"}
        </button>
      </header>

      <div className="list-status" aria-live="polite">
        {isFetching ? <span role="status">Refreshing drills</span> : null}
        {error ? (
          <InlineNotice>
            Refresh failed; showing the last successful result.
            <button type="button" onClick={() => void refetch()}>
              Retry
            </button>
          </InlineNotice>
        ) : null}
      </div>

      {isEmpty ? (
        <EmptyState title="No drills match this view" />
      ) : (
        <ul>
          {data.map((drill) => (
            <li key={drill.id}><DrillRow drill={drill} /></li>
          ))}
        </ul>
      )}
    </main>
  );
}

The query library may expose different names, but the important contract is unchanged: the absence of a successful snapshot controls the blocking states, while fetch activity and refresh errors decorate an existing snapshot.

Rendering the rows is O(n) time and O(n) UI space. The state derivation itself is constant work. Keeping stale data visible favors continuity and is usually appropriate for browse screens, but it is not correct when old data would authorize an action, display a critical balance, or violate a consistency requirement. In those cases the product may deliberately block interaction or label the snapshot with its age. Skeleton dimensions improve visual stability, but they should approximate the real layout rather than imitate every pixel.

• The first successful response is an empty array.
• A refresh changes a populated result to empty and the empty state replaces the rows only after success.
• A refresh fails after populated or empty data was already loaded.
• Retry is activated repeatedly before the first retry settles.
• Navigation changes the query key while an older request is still in flight.
• The API returns duplicate identifiers, which would make React row identity unstable.
• A screen reader should hear refresh progress without focus jumping away from the current row.

• Render data: undefined, isLoading: true and assert the skeleton and loading status, not the empty state.
• Resolve the first request with [] and assert the genuine empty message.
• Start a refetch with existing rows and assert the rows remain, aria-busy becomes true, and Refresh is disabled.
• Reject that refetch and assert both the stale rows and inline failure notice remain visible.
• Invoke Retry and verify refetch is called once while the current request is active.
• Resolve a later refresh with a different result and verify the list moves to the new successful snapshot.

• Empty flashes before loading: undefined and [] were treated as the same state.
• Rows disappear during refresh: isFetching was used as a full-page loading condition instead of distinguishing initial load.
• A refresh error destroys useful content: error rendering ran before checking whether a successful snapshot exists.
• Retry creates overlapping work: the command remains enabled while a request is active.
• The UI says loading forever after failure: the query state or manual reducer never completed its failure transition.
• Tests pass but users see layout jumps: the test asserted text only and ignored the reserved list region.