Merge pull request #269 from AustineSamuel/error-boundary

feat(frontend): route-segment error.tsx for claims, policies, and admin

Author: jhayniffy

frontend/README.md

@@ -144,3 +144,38 @@ To enable locally:
 NEXT_PUBLIC_ANALYTICS_ENABLED=true
 NEXT_PUBLIC_ANALYTICS_DOMAIN=your-domain.com
 ```
+
+## Architecture notes
+
+### Route error boundaries (`error.tsx`)
+
+Next.js **App Router** isolates render failures per route **segment** using a
+client `error.tsx` next to `page.tsx` / `layout.tsx`. When a segment throws
+during render (or in a child Server/Client component during that render pass),
+only that subtree is replaced by the error UI; the root layout (navigation,
+wallet provider, etc.) keeps running.
+
+**Current segment boundaries**
+
+| Segment      | Path              | Role |
+|-------------|-------------------|------|
+| Claims      | `app/claims/`     | Claims board list and nested routes |
+| Policies    | `app/policies/`   | Policy dashboard (`PolicyDashboard`); `/dashboard` redirects here |
+| Admin       | `app/admin/`      | Admin placeholder segment |
+| Policy flow | `app/policy/`     | Quote/bind policy wizard |
+| Quote       | `app/quote/`      | Quote flow |
+| Support     | `app/support/`    | Support |
+
+Shared UI: `RouteError` (`src/components/route-error.tsx`) — user-safe message,
+support reference when present, **Try again** (`reset()`), **Go to dashboard**
+link. Development-only collapsible stack trace.
+
+**Observability:** `logRouteSegmentError` (`src/lib/observability.ts`) records
+anonymized metadata in production via Plausible (`route_segment_error`: segment,
+error name, optional digest). **No** `error.message` or stack is sent to
+analytics or shown to users in production.
+
+**Out of scope for these boundaries:** Wallet signing and other **event
+handler** errors are not caught by `error.tsx`; components must handle those
+inline (try/catch / toast) so users get immediate feedback without replacing the
+whole segment.

frontend/src/app/__tests__/route-segment-error-pages.test.tsx

@@ -0,0 +1,35 @@
+/**
+ * @jest-environment jsdom
+ */
+import { render, screen } from '@testing-library/react'
+import React from 'react'
+
+const routeErrorMock = jest.fn(({ segment }: { segment: string }) => (
+  <div data-testid="route-error" data-segment={segment} />
+))
+
+jest.mock('@/components/route-error', () => ({
+  RouteError: (props: { segment: string }) => routeErrorMock(props),
+}))
+
+import ClaimsError from '@/app/claims/error'
+import PoliciesError from '@/app/policies/error'
+import AdminError from '@/app/admin/error'
+
+describe('Route segment error.tsx wiring', () => {
+  const err = new Error('boom') as Error & { digest?: string }
+  const reset = jest.fn()
+
+  beforeEach(() => {
+    routeErrorMock.mockClear()
+  })
+
+  it.each([
+    [ClaimsError, 'claims'],
+    [PoliciesError, 'policies'],
+    [AdminError, 'admin'],
+  ] as const)('passes segment to RouteError', (ErrorPage, segment) => {
+    render(<ErrorPage error={err} reset={reset} />)
+    expect(screen.getByTestId('route-error')).toHaveAttribute('data-segment', segment)
+  })
+})

frontend/src/app/admin/error.tsx

@@ -0,0 +1,13 @@
+'use client'
+
+import { RouteError } from '@/components/route-error'
+
+export default function AdminError({
+  error,
+  reset,
+}: {
+  error: Error & { digest?: string }
+  reset: () => void
+}) {
+  return <RouteError error={error} reset={reset} area="Admin" segment="admin" />
+}

frontend/src/app/admin/layout.tsx

@@ -0,0 +1,5 @@
+import type { ReactNode } from 'react'
+
+export default function AdminLayout({ children }: { children: ReactNode }) {
+  return children
+}

frontend/src/app/admin/page.tsx

@@ -0,0 +1,14 @@
+export const metadata = { title: 'Admin' }
+
+/**
+ * Placeholder admin segment so `error.tsx` can scope failures without affecting
+ * the rest of the app. Extend with real admin UI when available.
+ */
+export default function AdminPage() {
+  return (
+    <main className="container mx-auto px-4 py-8 max-w-3xl">
+      <h1 className="text-2xl font-semibold text-gray-900 mb-2">Admin</h1>
+      <p className="text-sm text-muted-foreground">Administrative tools will appear here.</p>
+    </main>
+  )
+}

frontend/src/app/claims/error.tsx

@@ -1,5 +1,5 @@
 'use client';
 import { RouteError } from '@/components/route-error';
 export default function ClaimsError({ error, reset }: { error: Error & { digest?: string }; reset: () => void }) {
-  return <RouteError error={error} reset={reset} area="Claims Board" />;
+  return <RouteError error={error} reset={reset} area="Claims Board" segment="claims" />;
 }

frontend/src/app/dashboard/page.tsx

@@ -1,12 +1,6 @@
-import { PolicyDashboard } from '@/features/policies/components/PolicyDashboard';
-
-export const metadata = { title: 'My Policies' };
+import { redirect } from 'next/navigation'
 
+/** Canonical policies list lives under `/policies` (segment-level error boundary). */
 export default function PolicyDashboardPage() {
-  return (
-    <main className="container mx-auto px-4 py-8 max-w-6xl">
-      <h1 className="text-2xl font-bold text-gray-900 mb-6">My Policies</h1>
-      <PolicyDashboard />
-    </main>
-  );
+  redirect('/policies')
 }

frontend/src/app/policies/error.tsx

@@ -0,0 +1,13 @@
+'use client'
+
+import { RouteError } from '@/components/route-error'
+
+export default function PoliciesError({
+  error,
+  reset,
+}: {
+  error: Error & { digest?: string }
+  reset: () => void
+}) {
+  return <RouteError error={error} reset={reset} area="Policies" segment="policies" />
+}

frontend/src/app/policies/layout.tsx

@@ -0,0 +1,5 @@
+import type { ReactNode } from 'react'
+
+export default function PoliciesLayout({ children }: { children: ReactNode }) {
+  return children
+}

frontend/src/app/policies/page.tsx

@@ -0,0 +1,12 @@
+import { PolicyDashboard } from '@/features/policies/components/PolicyDashboard'
+
+export const metadata = { title: 'My Policies' }
+
+export default function PoliciesPage() {
+  return (
+    <main className="container mx-auto px-4 py-8 max-w-6xl">
+      <h1 className="text-2xl font-bold text-gray-900 mb-6">My Policies</h1>
+      <PolicyDashboard />
+    </main>
+  )
+}