feat: enhance field reports handling in dashboard with image preloading and visibility filtering

Author: williamluke4

components/dashboard/Dashboard.tsx

@@ -330,19 +330,20 @@ export function Dashboard() {
     [selectedTokens]
   );
 
-  // Field reports filtering
-  const { visibleReports, dismissReport, resetDismissed } = useFieldReports({
+  // Image preloading for field reports
+  const { isImageLoaded, resetPreloaded } = useImagePreloader({
     reports: reportsData?.reports ?? [],
     currentDate: date,
     selectedVoucherAddresses,
-    maxVisible: 3,
   });
 
-  // Image preloading for field reports
-  const { resetPreloaded } = useImagePreloader({
+  // Field reports filtering
+  const { visibleReports, dismissReport, resetDismissed } = useFieldReports({
     reports: reportsData?.reports ?? [],
     currentDate: date,
     selectedVoucherAddresses,
+    isImageLoaded,
+    maxVisible: 3,
   });
 
   // Reset dismissed reports and preloaded images when animation restarts from beginning

components/dashboard/FieldReportCard.tsx

@@ -2,7 +2,7 @@
  * Individual field report card with animations
  */
 
-import React from "react";
+import React, { useState } from "react";
 import { CloseIcon } from "@components/icons";
 import type { VisibleReport } from "@/types";
 
@@ -12,6 +12,9 @@ export interface FieldReportCardProps {
 }
 
 export function FieldReportCard({ report, onDismiss }: FieldReportCardProps) {
+  const [imgLoaded, setImgLoaded] = useState(false);
+  const [imgError, setImgError] = useState(false);
+
   const handleDismiss = (e: React.MouseEvent) => {
     e.preventDefault();
     e.stopPropagation();
@@ -26,12 +29,17 @@ export function FieldReportCard({ report, onDismiss }: FieldReportCardProps) {
       className="block w-72 max-w-[calc(100vw-2rem)] bg-white/95 backdrop-blur-sm rounded-lg shadow-xl border border-gray-200 overflow-hidden hover:shadow-2xl hover:scale-[1.02] transition-all cursor-pointer"
     >
       {/* Image */}
-      {report.image_url && (
+      {report.image_url && !imgError && (
         <div className="relative h-32 w-full">
+          {!imgLoaded && (
+            <div className="absolute inset-0 bg-gray-200 animate-pulse" />
+          )}
           <img
             src={report.image_url}
             alt={report.title}
-            className="w-full h-full object-cover"
+            className={`w-full h-full object-cover transition-opacity duration-300 ${imgLoaded ? "opacity-100" : "opacity-0"}`}
+            onLoad={() => setImgLoaded(true)}
+            onError={() => setImgError(true)}
           />
           <div className="absolute inset-0 bg-gradient-to-t from-black/30 to-transparent" />
           <button

hooks/dashboard/useFieldReports.ts

@@ -10,6 +10,7 @@ export interface UseFieldReportsOptions {
   reports: FieldReport[];
   currentDate: number;
   selectedVoucherAddresses: Set<string>;
+  isImageLoaded?: (url: string) => boolean;
   maxVisible?: number;
 }
 
@@ -24,6 +25,7 @@ export function useFieldReports({
   reports,
   currentDate,
   selectedVoucherAddresses,
+  isImageLoaded,
   maxVisible = 3,
 }: UseFieldReportsOptions): UseFieldReportsReturn {
   const [dismissedIds, setDismissedIds] = useState<Set<number>>(new Set());
@@ -53,6 +55,10 @@ export function useFieldReports({
       // Skip future reports
       if (!hasStarted) continue;
 
+      // Skip reports whose image hasn't loaded yet
+      if (isImageLoaded && report.image_url && !isImageLoaded(report.image_url))
+        continue;
+
       // Determine visibility state
       const wasVisible = prevVisibleRef.current.has(report.id);
       let visibility: ReportVisibility;
@@ -73,7 +79,7 @@ export function useFieldReports({
 
     // Limit visible count
     return active.slice(0, maxVisible);
-  }, [reports, currentDate, selectedVoucherAddresses, dismissedIds, maxVisible]);
+  }, [reports, currentDate, selectedVoucherAddresses, dismissedIds, isImageLoaded, maxVisible]);
 
   // Update tracking ref after render
   useEffect(() => {

hooks/dashboard/useImagePreloader.ts

@@ -1,56 +1,117 @@
 /**
  * Hook for preloading field report images based on timeline position
+ * and tracking their load completion state
  */
 
-import { useCallback, useEffect, useRef } from "react";
+import { useCallback, useEffect, useRef, useState } from "react";
 import type { FieldReport } from "@/types";
 
 export interface UseImagePreloaderOptions {
   reports: FieldReport[];
   currentDate: number;
   selectedVoucherAddresses: Set<string>;
-  preloadWindowMs?: number; // Default: 7 days ahead
+  preloadWindowMs?: number; // Default: 30 days ahead
 }
 
 export interface UseImagePreloaderReturn {
+  isImageLoaded: (url: string) => boolean;
   resetPreloaded: () => void;
 }
 
-const SEVEN_DAYS_MS = 7 * 24 * 60 * 60 * 1000;
+const THIRTY_DAYS_MS = 30 * 24 * 60 * 60 * 1000;
 
 export function useImagePreloader({
   reports,
   currentDate,
   selectedVoucherAddresses,
-  preloadWindowMs = SEVEN_DAYS_MS,
+  preloadWindowMs = THIRTY_DAYS_MS,
 }: UseImagePreloaderOptions): UseImagePreloaderReturn {
   const preloadedUrls = useRef<Set<string>>(new Set());
+  const [loadedUrls, setLoadedUrls] = useState<Set<string>>(new Set());
 
+  // Eagerly preload all matching report images on initial data load
+  const eagerPreloadDone = useRef(false);
+  useEffect(() => {
+    if (eagerPreloadDone.current || reports.length === 0) return;
+    eagerPreloadDone.current = true;
+
+    for (const report of reports) {
+      if (!report.image_url) continue;
+      if (preloadedUrls.current.has(report.image_url)) continue;
+
+      const hasMatch = report.vouchers.some((v) =>
+        selectedVoucherAddresses.has(v)
+      );
+      if (!hasMatch) continue;
+
+      const url = report.image_url;
+      preloadedUrls.current.add(url);
+      const img = new Image();
+      img.onload = () => {
+        setLoadedUrls((prev) => {
+          const next = new Set(prev);
+          next.add(url);
+          return next;
+        });
+      };
+      img.onerror = () => {
+        // Mark as loaded on error too so the card isn't blocked forever
+        setLoadedUrls((prev) => {
+          const next = new Set(prev);
+          next.add(url);
+          return next;
+        });
+      };
+      img.src = url;
+    }
+  }, [reports, selectedVoucherAddresses]);
+
+  // Window-based preloading for any new reports not yet handled
   useEffect(() => {
     const upcomingCutoff = currentDate + preloadWindowMs;
 
     for (const report of reports) {
       if (!report.image_url) continue;
       if (preloadedUrls.current.has(report.image_url)) continue;
 
-      // Check if report has any vouchers matching selected ones
       const hasMatch = report.vouchers.some((v) =>
         selectedVoucherAddresses.has(v)
       );
       if (!hasMatch) continue;
 
-      // Preload if within window or currently visible (past period_from)
       if (report.period_from <= upcomingCutoff) {
+        const url = report.image_url;
+        preloadedUrls.current.add(url);
         const img = new Image();
-        img.src = report.image_url;
-        preloadedUrls.current.add(report.image_url);
+        img.onload = () => {
+          setLoadedUrls((prev) => {
+            const next = new Set(prev);
+            next.add(url);
+            return next;
+          });
+        };
+        img.onerror = () => {
+          setLoadedUrls((prev) => {
+            const next = new Set(prev);
+            next.add(url);
+            return next;
+          });
+        };
+        img.src = url;
       }
     }
   }, [reports, currentDate, selectedVoucherAddresses, preloadWindowMs]);
 
+  const isImageLoaded = useCallback(
+    (url: string) => loadedUrls.has(url),
+    [loadedUrls]
+  );
+
   const resetPreloaded = useCallback(() => {
     preloadedUrls.current.clear();
+    eagerPreloadDone.current = false;
+    setLoadedUrls(new Set());
   }, []);
 
-  return { resetPreloaded };
+  return { isImageLoaded, resetPreloaded };
 }