Merge pull request #303 from magaret457/feature/offline-detection-ux

feat(offline): add useNetworkStatus hook, NetworkBanner, and React Query sync (#241)

Author: jhayniffy

frontend/src/app/layout.tsx

@@ -9,6 +9,7 @@ import { Toaster } from "@/components/ui/toaster";
 import { WalletProvider, NetworkMismatchModal } from "@/features/wallet";
 import { inter, ibmPlexMono } from "@/lib/fonts";
 import { QueryProvider } from "@/lib/query";
+import { NetworkBanner } from "@/components/ui/network-banner";
 
 export const viewport: Viewport = {
   width: "device-width",
@@ -86,6 +87,7 @@ export default async function RootLayout({ children }: { children: React.ReactNo
         <ThemeProvider defaultTheme="system" storageKey="niffyinsur-theme">
           <QueryProvider>
             <WalletProvider>
+              <NetworkBanner />
               {children}
               <CookieConsentBanner />
               <NetworkMismatchModal />

frontend/src/components/ui/__tests__/network-status.test.tsx

@@ -0,0 +1,110 @@
+/**
+ * Tests for useNetworkStatus hook and NetworkBanner component.
+ * Uses Jest + @testing-library/react (jsdom environment).
+ */
+import { act, renderHook } from '@testing-library/react'
+import { render, screen } from '@testing-library/react'
+import { onlineManager } from '@tanstack/react-query'
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function fireOnline() {
+  Object.defineProperty(navigator, 'onLine', { value: true, configurable: true })
+  window.dispatchEvent(new Event('online'))
+}
+
+function fireOffline() {
+  Object.defineProperty(navigator, 'onLine', { value: false, configurable: true })
+  window.dispatchEvent(new Event('offline'))
+}
+
+// ── useNetworkStatus ──────────────────────────────────────────────────────────
+
+describe('useNetworkStatus', () => {
+  beforeEach(() => {
+    // Start each test online
+    Object.defineProperty(navigator, 'onLine', { value: true, configurable: true })
+  })
+
+  it('returns isOnline=true when navigator.onLine is true', async () => {
+    const { useNetworkStatus } = await import('@/hooks/use-network-status')
+    const { result } = renderHook(() => useNetworkStatus())
+    expect(result.current.isOnline).toBe(true)
+  })
+
+  it('transitions to isOnline=false on offline event', async () => {
+    const { useNetworkStatus } = await import('@/hooks/use-network-status')
+    const { result } = renderHook(() => useNetworkStatus())
+
+    act(() => { fireOffline() })
+
+    expect(result.current.isOnline).toBe(false)
+  })
+
+  it('transitions back to isOnline=true on online event', async () => {
+    const { useNetworkStatus } = await import('@/hooks/use-network-status')
+    const { result } = renderHook(() => useNetworkStatus())
+
+    act(() => { fireOffline() })
+    expect(result.current.isOnline).toBe(false)
+
+    act(() => { fireOnline() })
+    expect(result.current.isOnline).toBe(true)
+  })
+
+  it('calls onlineManager.setOnline(false) when going offline', async () => {
+    const spy = jest.spyOn(onlineManager, 'setOnline')
+    const { useNetworkStatus } = await import('@/hooks/use-network-status')
+    renderHook(() => useNetworkStatus())
+
+    act(() => { fireOffline() })
+
+    expect(spy).toHaveBeenCalledWith(false)
+    spy.mockRestore()
+  })
+
+  it('calls onlineManager.setOnline(true) when coming back online', async () => {
+    const spy = jest.spyOn(onlineManager, 'setOnline')
+    const { useNetworkStatus } = await import('@/hooks/use-network-status')
+    renderHook(() => useNetworkStatus())
+
+    act(() => { fireOffline() })
+    act(() => { fireOnline() })
+
+    expect(spy).toHaveBeenCalledWith(true)
+    spy.mockRestore()
+  })
+})
+
+// ── NetworkBanner ─────────────────────────────────────────────────────────────
+
+describe('NetworkBanner', () => {
+  beforeEach(() => {
+    Object.defineProperty(navigator, 'onLine', { value: true, configurable: true })
+  })
+
+  it('renders nothing when online', async () => {
+    const { NetworkBanner } = await import('@/components/ui/network-banner')
+    const { container } = render(<NetworkBanner />)
+    expect(container.firstChild).toBeNull()
+  })
+
+  it('renders the banner when offline', async () => {
+    Object.defineProperty(navigator, 'onLine', { value: false, configurable: true })
+    const { NetworkBanner } = await import('@/components/ui/network-banner')
+    render(<NetworkBanner />)
+    expect(screen.getByTestId('network-banner')).toBeInTheDocument()
+    expect(screen.getByRole('alert')).toBeInTheDocument()
+  })
+
+  it('hides the banner after coming back online', async () => {
+    Object.defineProperty(navigator, 'onLine', { value: false, configurable: true })
+    const { NetworkBanner } = await import('@/components/ui/network-banner')
+    render(<NetworkBanner />)
+    expect(screen.getByTestId('network-banner')).toBeInTheDocument()
+
+    act(() => { fireOnline() })
+
+    expect(screen.queryByTestId('network-banner')).toBeNull()
+  })
+})

frontend/src/components/ui/index.ts

@@ -50,6 +50,8 @@ export { Badge, badgeVariants } from './badge'
 export { WalletAddress, type WalletAddressProps, type StellarNetwork } from './wallet-address'
 export { Stepper, StepContent, type Step } from './stepper'
 export { InlineError } from './inline-error'
+export { NetworkBanner } from './network-banner'
+export { WriteRetryButton } from './write-retry-button'
 export { VoteEducationPanel } from '../claims/vote-education-panel'
 export { VoteTally } from '../claims/vote-tally'
 export { VoteConfirmModal } from '../claims/vote-confirm-modal'

frontend/src/components/ui/network-banner.tsx

@@ -0,0 +1,28 @@
+'use client'
+
+import { WifiOff } from 'lucide-react'
+import { useNetworkStatus } from '@/hooks/use-network-status'
+
+/**
+ * NetworkBanner — non-blocking, persistent banner shown while the browser is
+ * offline. Sits at the top of the viewport (z-[200]) so it never obscures
+ * interactive content. Disappears automatically on reconnection.
+ */
+export function NetworkBanner() {
+  const { isOnline } = useNetworkStatus()
+
+  if (isOnline) return null
+
+  return (
+    <div
+      role="alert"
+      aria-live="assertive"
+      data-testid="network-banner"
+      className="fixed inset-x-0 top-0 z-[200] flex items-center gap-2 bg-yellow-500 px-4 py-2 text-sm font-medium text-yellow-950"
+      style={{ paddingTop: `calc(0.5rem + env(safe-area-inset-top, 0px))` }}
+    >
+      <WifiOff className="h-4 w-4 shrink-0" aria-hidden="true" />
+      <span>You&apos;re offline. Some features may be unavailable.</span>
+    </div>
+  )
+}

frontend/src/components/ui/write-retry-button.tsx

@@ -0,0 +1,34 @@
+'use client'
+
+import { Button } from '@/components/ui/button'
+import { useNetworkStatus } from '@/hooks/use-network-status'
+
+interface WriteRetryButtonProps {
+  onRetry: () => void
+  label?: string
+  disabled?: boolean
+}
+
+/**
+ * Shown after a write operation (transaction) fails while offline.
+ * Write ops must NOT auto-retry — the user must explicitly confirm.
+ */
+export function WriteRetryButton({
+  onRetry,
+  label = 'Retry',
+  disabled,
+}: WriteRetryButtonProps) {
+  const { isOnline } = useNetworkStatus()
+
+  return (
+    <Button
+      variant="outline"
+      size="sm"
+      onClick={onRetry}
+      disabled={disabled || !isOnline}
+      title={!isOnline ? 'Reconnect to retry' : undefined}
+    >
+      {label}
+    </Button>
+  )
+}

frontend/src/hooks/use-network-status.ts

@@ -0,0 +1,42 @@
+'use client'
+
+import { useEffect, useState } from 'react'
+import { onlineManager } from '@tanstack/react-query'
+
+export interface NetworkStatus {
+  isOnline: boolean
+}
+
+/**
+ * Tracks browser online/offline state and syncs React Query's onlineManager
+ * so background refetching is automatically paused while offline and resumed
+ * on reconnection.
+ */
+export function useNetworkStatus(): NetworkStatus {
+  const [isOnline, setIsOnline] = useState(
+    typeof navigator !== 'undefined' ? navigator.onLine : true,
+  )
+
+  useEffect(() => {
+    function handleOnline() {
+      setIsOnline(true)
+      onlineManager.setOnline(true)
+    }
+    function handleOffline() {
+      setIsOnline(false)
+      onlineManager.setOnline(false)
+    }
+
+    // Sync initial state with React Query
+    onlineManager.setOnline(navigator.onLine)
+
+    window.addEventListener('online', handleOnline)
+    window.addEventListener('offline', handleOffline)
+    return () => {
+      window.removeEventListener('online', handleOnline)
+      window.removeEventListener('offline', handleOffline)
+    }
+  }, [])
+
+  return { isOnline }
+}