Merge pull request Junirezz#997 from ToryMic/fix/911-frontend-implement-loading-skeletons-and-empty-states-for-vault-pages

[911] Frontend: Implement loading skeletons and empty states for vault pages

Author: Junirezz

.github/workflows/docs.yml

@@ -14,9 +14,10 @@ jobs:
         uses: actions/checkout@v4
 
       - name: Setup Rust
-        uses: dtolnay/rust-toolchain@stable
+        uses: dtolnay/rust-toolchain@1.85.0
 
       - name: Generate Rust docs
         run: |
           cargo doc -p share-price-math --no-deps
           cargo doc -p mock-strategy --no-deps
+        continue-on-error: false

docs/VAULT_UX_PATTERN_LIBRARY.md

@@ -212,6 +212,34 @@ Vault interactions are asynchronous and must distinguish between these states:
 - `stale`: the last known data is visible, but refresh freshness is degraded
 - `optimistic`: local cache reflects the expected result before server confirmation
 
+### Loading skeletons (vault pages)
+
+Use contextual skeletons from `frontend/src/components/Skeleton.tsx` instead of blank panels:
+
+| Surface | Skeleton |
+| --- | --- |
+| Vault dashboard cards / stats | `DashboardCardSkeleton`, `VaultStatSkeleton`, `SharePriceSkeleton` |
+| Charts | `ChartSkeleton` |
+| Portfolio summary | `PortfolioCardSkeleton` |
+| Transaction rows / tables | `TransactionRowSkeleton`, `TableSkeleton` |
+| Analytics widgets | `AnalyticsWidgetSkeleton` |
+| Lazy route fallback | `RouteLoadingFallback` |
+
+Rules:
+
+- Mark loading regions with `aria-busy="true"` and keep `aria-hidden` on decorative skeleton chrome.
+- Prefer delayed loading (`useDelayedLoading`) for short fetches to avoid skeleton flash.
+- Do not show empty-state CTAs while `isLoading` is true.
+
+### Empty states (vault pages)
+
+Use `frontend/src/components/ui/EmptyState` with an explicit `kind`:
+
+- `no-data` — wallet connected, no deposits/positions yet (offer deposit intent)
+- `no-results` / `search` — filters returned nothing (offer reset filters)
+- `permission` — wallet disconnected or access required
+- `error` — fetch failed after retries (offer retry)
+
 Rules:
 
 - Pending transactions must disable duplicate submission.

frontend/src/components/Skeleton.test.tsx

@@ -0,0 +1,63 @@
+import { describe, it, expect } from "vitest";
+import { render } from "@testing-library/react";
+import Skeleton, {
+  SkeletonBlock,
+  SkeletonCircle,
+  SkeletonText,
+  TableSkeleton,
+  DashboardCardSkeleton,
+  ChartSkeleton,
+  SharePriceSkeleton,
+  VaultStatSkeleton,
+  TransactionRowSkeleton,
+  PortfolioCardSkeleton,
+  AnalyticsWidgetSkeleton,
+} from "./Skeleton";
+
+describe("Skeleton", () => {
+  it("renders SkeletonBlock with aria-hidden", () => {
+    const { container } = render(<SkeletonBlock width="100px" height="20px" />);
+    const el = container.querySelector(".skeleton");
+    expect(el).toBeTruthy();
+    expect(el?.getAttribute("aria-hidden")).toBe("true");
+  });
+
+  it("exports SkeletonBlock as default", () => {
+    const { container } = render(<Skeleton width="50px" height="10px" />);
+    expect(container.querySelector(".skeleton")).toBeTruthy();
+  });
+
+  it("renders SkeletonCircle as a round block", () => {
+    const { container } = render(<SkeletonCircle width={24} height={24} />);
+    const el = container.querySelector(".skeleton") as HTMLElement;
+    expect(el.style.borderRadius).toBe("50%");
+  });
+
+  it("renders multi-line SkeletonText", () => {
+    const { container } = render(<SkeletonText lines={3} />);
+    expect(container.querySelectorAll(".skeleton")).toHaveLength(3);
+  });
+
+  it("renders TableSkeleton with expected rows and columns", () => {
+    const { container } = render(<TableSkeleton columns={3} rows={2} />);
+    expect(container.querySelectorAll("tr.data-table-row")).toHaveLength(2);
+    expect(container.querySelectorAll("td")).toHaveLength(6);
+  });
+
+  it("renders vault page skeleton variants", () => {
+    const variants = [
+      <DashboardCardSkeleton key="dash" />,
+      <ChartSkeleton key="chart" />,
+      <SharePriceSkeleton key="share" />,
+      <VaultStatSkeleton key="stat" />,
+      <TransactionRowSkeleton key="tx" />,
+      <PortfolioCardSkeleton key="port" />,
+      <AnalyticsWidgetSkeleton key="analytics" />,
+    ];
+    for (const variant of variants) {
+      const { container, unmount } = render(variant);
+      expect(container.querySelector(".skeleton")).toBeTruthy();
+      unmount();
+    }
+  });
+});

frontend/src/context/ToastContext.tsx

@@ -77,6 +77,8 @@ export const ToastProvider: React.FC<{ children: React.ReactNode }> = ({
     ...options
   }: ToastOptions) => {
     const dedupeKey = generateDedupeKey({ ...options, variant });
+    // Invoked from event handlers / async callbacks, not during render.
+    // eslint-disable-next-line react-hooks/purity -- timestamp for toast dedupe window
     const now = Date.now();
 
     // Check for duplicate within dedupe window

frontend/src/hooks/useAsyncActionButton.ts

@@ -39,6 +39,7 @@ export function useAsyncActionButton({
   const [status, setStatus] = useState<AsyncActionStatus>("idle");
 
   useEffect(() => {
+    /* eslint-disable react-hooks/set-state-in-effect -- mirror external async flags into button status */
     if (isPending) {
       setStatus("pending");
       return;
@@ -56,6 +57,7 @@ export function useAsyncActionButton({
     if (!isPending && !isSuccess && !isError) {
       setStatus("idle");
     }
+    /* eslint-enable react-hooks/set-state-in-effect */
   }, [isPending, isSuccess, isError, successResetMs, errorResetMs]);
 
   const label = useMemo(() => {

frontend/src/hooks/useWalletHeartbeat.ts

@@ -76,6 +76,7 @@ export function useWalletHeartbeat(
 
   useEffect(() => {
     if (!walletAddress) {
+      // eslint-disable-next-line react-hooks/set-state-in-effect -- reset heartbeat when wallet disconnects
       setHeartbeat(INITIAL);
       return;
     }

frontend/src/lib/security.test.ts

@@ -148,7 +148,7 @@ describe('escapeHtml', () => {
     expect(escapeHtml('<img src=x onerror=alert(1)>'))
       .toBe('&lt;img src=x onerror=alert(1)&gt;');
     expect(escapeHtml('Test & "quotes"'))
-      .toBe('Test &amp; "quotes"');
+      .toBe('Test &amp; &quot;quotes&quot;');
   });
 
   test('preserves safe text', () => {

frontend/src/pages/Portfolio.test.tsx

@@ -1,4 +1,4 @@
-import { fireEvent, render, screen, waitFor, within } from "@testing-library/react";
+import { fireEvent, render, screen, waitFor } from "@testing-library/react";
 import { MemoryRouter, Route, Routes, useLocation } from "react-router-dom";
 import { describe, expect, it, vi, beforeEach } from "vitest";
 import Portfolio from "./Portfolio";

frontend/src/pages/Portfolio.tsx

@@ -29,6 +29,7 @@ import { useReferralStats, useReferralLink } from "../hooks/useReferral";
 import ShareModal from "../components/ShareModal";
 import EmptyState from "../components/ui/EmptyState";
 import FirstTimePortfolioPanel from "../components/FirstTimePortfolioPanel";
+import { PortfolioCardSkeleton } from "../components/Skeleton";
 import { useNavigate } from "react-router-dom";
 import { triggerDepositIntent } from "../lib/vaultIntentActions";
 import { formatCurrency, formatNumber, formatPercent } from "../lib/formatters";
@@ -413,67 +414,81 @@ const Portfolio: React.FC<PortfolioProps> = ({ walletAddress }) => {
           <div
             className="portfolio-summary-grid"
             style={{ marginBottom: "8px" }}
+            aria-busy={isLoading || undefined}
           >
-            <PortfolioSummaryCard
-              label={t("portfolio.totalNetValue")}
-              value={formatSensitiveCurrency(totalValue)}
-              icon={<DollarSign size={20} color="var(--accent-cyan)" />}
-              trend={totalNetValueTrend}
-              trendPositive={totalGain >= 0}
-            />
-            <PortfolioSummaryCard
-              label={t("portfolio.cumulativeYield")}
-              value={formatSensitiveCurrency(totalGain, true)}
-              icon={<TrendingUp size={20} color="var(--accent-purple)" />}
-              trend={cumulativeYieldTrend}
-              trendPositive={totalGain >= 0}
-            />
-            <PortfolioSummaryCard
-              label={
-                <span style={{ display: "flex", alignItems: "center", gap: "6px" }}>
-                  Weighted Avg APY
-                  <HelpIcon
-                    variant="tooltip"
-                    content="The portfolio-value-weighted average of all active position APYs."
-                  />
-                </span>
-              }
-              value={formatPercent(weightedApy, {
-                locale,
-                minimumFractionDigits: 2,
-                maximumFractionDigits: 2,
-              })}
-              icon={<Percent size={20} color="var(--accent-cyan)" />}
-              trend={weightedApyTrend}
-              trendPositive={true}
-            />
-            <PortfolioSummaryCard
-              label={t("portfolio.activePositions")}
-              value={holdings.filter(h => h.status === 'active').length.toString()}
-              icon={<Briefcase size={20} color="var(--text-secondary)" />}
-            />
-            <PortfolioSummaryCard
-              label={
-                <span style={{ display: "flex", alignItems: "center", gap: "6px" }}>
-                  Referral Earnings
-                  <HelpIcon
-                    variant="tooltip"
-                    content={t("portfolio.referralTooltip")}
-                  />
-                </span>
-              }
-              value={referralStats ? `$${referralStats.total_reward_earned}` : "$0.00"}
-              icon={<TrendingUp size={20} color="var(--accent-green)" />}
-              trend={referralStats ? `${referralStats.referral_count} referral${referralStats.referral_count !== 1 ? 's' : ''}` : "0 referrals"}
-              trendPositive={true}
-            />
-            <PortfolioSummaryCard
-              label={t("portfolio.shareReferralLink")}
-              value=""
-              icon={<Share2 size={20} color="var(--accent-cyan)" />}
-              onClick={() => setShowShareModal(true)}
-              clickable={true}
-            />
+            {isLoading ? (
+              <>
+                <PortfolioCardSkeleton />
+                <PortfolioCardSkeleton />
+                <PortfolioCardSkeleton />
+                <PortfolioCardSkeleton />
+                <PortfolioCardSkeleton />
+                <PortfolioCardSkeleton />
+              </>
+            ) : (
+              <>
+                <PortfolioSummaryCard
+                  label={t("portfolio.totalNetValue")}
+                  value={formatSensitiveCurrency(totalValue)}
+                  icon={<DollarSign size={20} color="var(--accent-cyan)" />}
+                  trend={totalNetValueTrend}
+                  trendPositive={totalGain >= 0}
+                />
+                <PortfolioSummaryCard
+                  label={t("portfolio.cumulativeYield")}
+                  value={formatSensitiveCurrency(totalGain, true)}
+                  icon={<TrendingUp size={20} color="var(--accent-purple)" />}
+                  trend={cumulativeYieldTrend}
+                  trendPositive={totalGain >= 0}
+                />
+                <PortfolioSummaryCard
+                  label={
+                    <span style={{ display: "flex", alignItems: "center", gap: "6px" }}>
+                      Weighted Avg APY
+                      <HelpIcon
+                        variant="tooltip"
+                        content="The portfolio-value-weighted average of all active position APYs."
+                      />
+                    </span>
+                  }
+                  value={formatPercent(weightedApy, {
+                    locale,
+                    minimumFractionDigits: 2,
+                    maximumFractionDigits: 2,
+                  })}
+                  icon={<Percent size={20} color="var(--accent-cyan)" />}
+                  trend={weightedApyTrend}
+                  trendPositive={true}
+                />
+                <PortfolioSummaryCard
+                  label={t("portfolio.activePositions")}
+                  value={holdings.filter(h => h.status === 'active').length.toString()}
+                  icon={<Briefcase size={20} color="var(--text-secondary)" />}
+                />
+                <PortfolioSummaryCard
+                  label={
+                    <span style={{ display: "flex", alignItems: "center", gap: "6px" }}>
+                      Referral Earnings
+                      <HelpIcon
+                        variant="tooltip"
+                        content={t("portfolio.referralTooltip")}
+                      />
+                    </span>
+                  }
+                  value={referralStats ? `$${referralStats.total_reward_earned}` : "$0.00"}
+                  icon={<TrendingUp size={20} color="var(--accent-green)" />}
+                  trend={referralStats ? `${referralStats.referral_count} referral${referralStats.referral_count !== 1 ? 's' : ''}` : "0 referrals"}
+                  trendPositive={true}
+                />
+                <PortfolioSummaryCard
+                  label={t("portfolio.shareReferralLink")}
+                  value=""
+                  icon={<Share2 size={20} color="var(--accent-cyan)" />}
+                  onClick={() => setShowShareModal(true)}
+                  clickable={true}
+                />
+              </>
+            )}
           </div>
 
           <YieldBreakdownChart totalGain={totalGain} />

frontend/src/pages/TransactionHistory.test.tsx

@@ -1,6 +1,6 @@
 import { render, screen, fireEvent, waitFor, within } from "@testing-library/react";
 import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
-import { MemoryRouter, Route, Routes, useSearchParams } from "react-router-dom";
+import { MemoryRouter } from "react-router-dom";
 import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
 import TransactionHistory from "./TransactionHistory";
 import * as transactionApi from "../lib/transactionApi";
@@ -66,11 +66,6 @@ function makeManyTransactions(count: number): Transaction[] {
   );
 }
 
-function UrlProbe() {
-  const [params] = useSearchParams();
-  return <div data-testid="url-probe">{params.toString()}</div>;
-}
-
 function renderPage(walletAddress: string | null, initialEntries = ["/"]) {
   const queryClient = new QueryClient({
     defaultOptions: { queries: { retry: false } },