feat(miner-ui): redesign ledgers route with StateBoundary + skeletons (#6512)

jaytbarimbao-collab · jaytbarimbao-collab · commit 5497d7cd7807 · 2026-07-16T12:56:49.000-04:00
Replace the two hand-rolled loading/error/empty <p> blocks in the ledgers route — the read-only ledger summary and the separate governor-control section — with the shared @loopover/ui-kit StateBoundary, each keeping its own independent boundary so a governor-state fetch failure never blanks the ledger summary (and vice-versa). Content-shaped Skeleton placeholders replace the flat loading text so the layout no longer jumps when the first poll resolves, and the governor-control row is regrouped into a single muted surface container using existing design tokens. lib/ledgers.ts, lib/governor.ts, both fetch loops, and the pause/resume Button wiring are untouched — purely presentational. Closes #6512
diff --git a/apps/loopover-miner-ui/src/governor.test.tsx b/apps/loopover-miner-ui/src/governor.test.tsx
@@ -35,11 +35,12 @@ describe("defaultGovernorPauseState (#4857)", () => {
 });
 
 describe("GovernorControlSection (#4857)", () => {
-  it("renders the loading state before the first result arrives", () => {
+  it("renders a content-shaped loading skeleton (role=status), not the old flat loading text (#6512)", () => {
     render(
       <GovernorControlSection result={null} pending={false} onPause={() => undefined} onResume={() => undefined} />,
     );
-    expect(screen.getByText(/Loading governor state/i)).toBeTruthy();
+    expect(screen.getByRole("status", { name: /loading governor state/i })).toBeTruthy();
+    expect(screen.queryByText("Loading governor state…")).toBeNull(); // the pre-#6512 sentence is gone
   });
 
   it("renders an error message when the local API is unreachable", () => {
diff --git a/apps/loopover-miner-ui/src/ledgers.test.tsx b/apps/loopover-miner-ui/src/ledgers.test.tsx
@@ -112,9 +112,10 @@ describe("LedgersView (#4855)", () => {
     expect(screen.getByRole("alert").textContent).toContain("connection refused");
   });
 
-  it("renders the loading state before the first result arrives", () => {
+  it("renders a content-shaped loading skeleton (role=status), not the old flat loading text (#6512)", () => {
     render(<LedgersView result={null} />);
-    expect(screen.getByText(/Loading local ledgers/i)).toBeTruthy();
+    expect(screen.getByRole("status", { name: /loading local ledgers/i })).toBeTruthy();
+    expect(screen.queryByText("Loading local ledgers…")).toBeNull(); // the pre-#6512 sentence is gone
   });
 });
 
diff --git a/apps/loopover-miner-ui/src/routes/ledgers.tsx b/apps/loopover-miner-ui/src/routes/ledgers.tsx
@@ -4,9 +4,17 @@ import { useEffect, useState } from "react";
 import { Button } from "@loopover/ui-kit/components/button";
 import { Card, CardContent, CardHeader } from "@loopover/ui-kit/components/card";
 import { Input } from "@loopover/ui-kit/components/input";
+import { Skeleton } from "@loopover/ui-kit/components/skeleton";
+import { StateBoundary } from "@loopover/ui-kit/components/state-views";
 import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@loopover/ui-kit/components/table";
 
-import { CLAIM_STATUSES, fetchLedgers, type ClaimStatus, type LedgersResult } from "../lib/ledgers";
+import {
+  CLAIM_STATUSES,
+  fetchLedgers,
+  type ClaimStatus,
+  type LedgersResult,
+  type LedgersSummary,
+} from "../lib/ledgers";
 import { fetchGovernorPauseState, pauseGovernor, resumeGovernor, type GovernorPauseStateResult } from "../lib/governor";
 
 export const Route = createFileRoute("/ledgers")({
@@ -15,8 +23,15 @@ export const Route = createFileRoute("/ledgers")({
 
 // Read-only views over the miner's local claim / event / governor ledgers (#4855). All three are aggregated
 // server-side (see vite-ledgers-api.ts) to status/type counts plus a small feed of SAFE columns — raw payloads
-// and the free-text claim note never reach this component. Same 4-state pattern as the portfolio/run-history
-// views (loading / error / fresh-install empty / populated).
+// and the free-text claim note never reach this component.
+//
+// #6512: the two hand-rolled loading/error/empty `<p>` blocks (the read-only ledger summary, and the SEPARATE
+// governor control section) are each replaced by the shared @loopover/ui-kit `StateBoundary`, with a
+// content-shaped `Skeleton` placeholder for the loading state so the layout doesn't jump when the poll resolves.
+// The two flows keep their OWN independent boundary — a governor-state fetch failure must not blank the ledger
+// summary, and vice-versa. Purely presentational: `lib/ledgers.ts`/`lib/governor.ts`, the two fetch loops, and
+// the pause/resume Button wiring are untouched; only the loading/error chrome and the governor-control layout
+// change.
 //
 // The governor control section below is a SEPARATE fetch/action loop from the read-only ledger summary above
 // (#4857, the governor half): it reads/writes the governor's pause state via vite-governor-api.ts, the
@@ -57,81 +72,54 @@ function CountTable({ counts, keyLabel }: { counts: Record<string, number>; keyL
   );
 }
 
-export function GovernorControlSection({
-  result,
-  pending,
-  onPause,
-  onResume,
-}: {
-  result: GovernorPauseStateResult | null;
-  pending: boolean;
-  onPause: (reason?: string) => void;
-  onResume: () => void;
-}) {
-  // Optional pause reason, mirroring the CLI's `governor pause [--reason <text>]`; an empty field
-  // is passed through as `undefined` so it matches the CLI's own optional-flag behavior.
-  const [reason, setReason] = useState("");
+/** Card+table-shaped loading placeholder for the ledger summary: mirrors the 3 status cards and the stacked
+ *  count/feed tables below them, so the summary keeps its shape while the first fetch resolves. `role="status"`
+ *  keeps the loading state announced to assistive tech (as the flat "Loading local ledgers…" text it replaces
+ *  was). */
+function LedgerSummarySkeleton() {
   return (
-    <section className="grid gap-3">
-      <h3 className="font-display text-token-base font-semibold">Governor control</h3>
-      {result === null ? (
-        <p className="text-token-sm text-muted-foreground">Loading governor state…</p>
-      ) : !result.ok ? (
-        <p role="alert" className="text-token-sm text-[var(--danger)]">
-          Could not read the local governor state: {result.error}
-        </p>
-      ) : (
-        <div className="flex flex-wrap items-center gap-3">
-          <p className="text-token-sm text-muted-foreground">
-            {result.pauseState.paused
-              ? `Paused since ${result.pauseState.pausedAt}${result.pauseState.reason ? ` (${result.pauseState.reason})` : ""}`
-              : "Not paused"}
-          </p>
-          {result.pauseState.paused ? (
-            <Button size="sm" variant="outline" disabled={pending} onClick={onResume}>
-              Resume governor
-            </Button>
-          ) : (
-            <>
-              <Input
-                type="text"
-                value={reason}
-                onChange={(event) => setReason(event.target.value)}
-                disabled={pending}
-                placeholder="Reason (optional)"
-                aria-label="Pause reason"
-                className="w-auto flex-1 min-w-[12rem]"
-              />
-              <Button size="sm" variant="destructive" disabled={pending} onClick={() => onPause(reason || undefined)}>
-                Pause governor
-              </Button>
-            </>
-          )}
+    <div className="grid gap-6" role="status" aria-label="Loading local ledgers">
+      <section className="grid gap-3">
+        <Skeleton className="h-5 w-28" />
+        <div className="grid gap-4 sm:grid-cols-3">
+          {Array.from({ length: 3 }).map((_, index) => (
+            <Card key={index}>
+              <CardContent className="p-4">
+                <Skeleton className="h-3 w-16" />
+                <Skeleton className="mt-2 h-8 w-12" />
+              </CardContent>
+            </Card>
+          ))}
         </div>
-      )}
-    </section>
+      </section>
+      {Array.from({ length: 2 }).map((_, index) => (
+        <section key={index} className="grid gap-3">
+          <Skeleton className="h-5 w-40" />
+          <Skeleton className="h-24 w-full" />
+        </section>
+      ))}
+    </div>
   );
 }
 
-export function LedgersView({ result }: { result: LedgersResult | null }) {
-  if (result === null) {
-    return <p className="text-token-sm text-muted-foreground">Loading local ledgers…</p>;
-  }
-  if (!result.ok) {
-    return (
-      <p role="alert" className="text-token-sm text-[var(--danger)]">
-        Could not read the local ledgers: {result.error}
-      </p>
-    );
-  }
-  const { claims, events, governor } = result.summary;
-  if (claims.total === 0 && events.total === 0 && governor.total === 0) {
-    return (
-      <p className="text-token-sm text-muted-foreground">
-        No ledger activity yet — claims, events, and governor entries appear here once the miner starts working.
-      </p>
-    );
-  }
+/** Row-shaped loading placeholder for the governor control section: a status line plus an action-sized block,
+ *  matching the "Not paused / Resume" row it stands in for. Its own `role="status"` announces this flow
+ *  independently of the ledger-summary skeleton above. */
+function GovernorControlSkeleton() {
+  return (
+    <div
+      className="flex flex-wrap items-center gap-3 rounded-token-sm bg-muted/40 p-3"
+      role="status"
+      aria-label="Loading governor state"
+    >
+      <Skeleton className="h-5 w-40" />
+      <Skeleton className="h-9 w-28" />
+    </div>
+  );
+}
+
+function LedgersSummaryContent({ summary }: { summary: LedgersSummary }) {
+  const { claims, events, governor } = summary;
   return (
     <div className="grid gap-6">
       <section className="grid gap-3">
@@ -199,6 +187,86 @@ export function LedgersView({ result }: { result: LedgersResult | null }) {
   );
 }
 
+export function GovernorControlSection({
+  result,
+  pending,
+  onPause,
+  onResume,
+}: {
+  result: GovernorPauseStateResult | null;
+  pending: boolean;
+  onPause: (reason?: string) => void;
+  onResume: () => void;
+}) {
+  // Optional pause reason, mirroring the CLI's `governor pause [--reason <text>]`; an empty field
+  // is passed through as `undefined` so it matches the CLI's own optional-flag behavior.
+  const [reason, setReason] = useState("");
+  const errorText = result !== null && !result.ok ? result.error : undefined;
+  return (
+    <section className="grid gap-3">
+      <h3 className="font-display text-token-base font-semibold">Governor control</h3>
+      <StateBoundary
+        isLoading={result === null}
+        isError={result !== null && !result.ok}
+        loadingSkeleton={<GovernorControlSkeleton />}
+        errorTitle="Couldn't read the local governor state"
+        errorDescription={errorText}
+      >
+        {result?.ok && (
+          <div className="flex flex-wrap items-center gap-3 rounded-token-sm bg-muted/40 p-3">
+            <p className="text-token-sm text-muted-foreground">
+              {result.pauseState.paused
+                ? `Paused since ${result.pauseState.pausedAt}${result.pauseState.reason ? ` (${result.pauseState.reason})` : ""}`
+                : "Not paused"}
+            </p>
+            {result.pauseState.paused ? (
+              <Button size="sm" variant="outline" disabled={pending} onClick={onResume} className="ml-auto">
+                Resume governor
+              </Button>
+            ) : (
+              <div className="ml-auto flex flex-wrap items-center gap-3">
+                <Input
+                  type="text"
+                  value={reason}
+                  onChange={(event) => setReason(event.target.value)}
+                  disabled={pending}
+                  placeholder="Reason (optional)"
+                  aria-label="Pause reason"
+                  className="w-auto flex-1 min-w-[12rem]"
+                />
+                <Button size="sm" variant="destructive" disabled={pending} onClick={() => onPause(reason || undefined)}>
+                  Pause governor
+                </Button>
+              </div>
+            )}
+          </div>
+        )}
+      </StateBoundary>
+    </section>
+  );
+}
+
+export function LedgersView({ result }: { result: LedgersResult | null }) {
+  const summary = result?.ok ? result.summary : null;
+  const isEmpty =
+    summary !== null && summary.claims.total === 0 && summary.events.total === 0 && summary.governor.total === 0;
+  const errorText = result !== null && !result.ok ? result.error : undefined;
+  return (
+    <StateBoundary
+      isLoading={result === null}
+      isError={result !== null && !result.ok}
+      isEmpty={isEmpty}
+      loadingSkeleton={<LedgerSummarySkeleton />}
+      errorTitle="Couldn't read the local ledgers"
+      errorDescription={errorText}
+      emptyTitle="No ledger activity yet"
+      emptyDescription="Claims, events, and governor entries appear here once the miner starts working."
+    >
+      {summary && <LedgersSummaryContent summary={summary} />}
+    </StateBoundary>
+  );
+}
+
 export function LedgersPage({
   loadLedgers = fetchLedgers,
   loadGovernorPauseState = fetchGovernorPauseState,
