feat(payment): #4 offline payment-queue management UI (#141)

The offline payment queue (paymentQueue, IndexedDB) shipped long ago but had no
user-facing controls — OfflineRetryBanner is display-only and lives only on
/payment-result. This adds the management layer:

- PaymentQueuePanel (5-file molecular): live online/offline/syncing status,
  queued items with per-item retry count (Attempt N/5 → "Max retries" at the
  cap), a manual "Retry now" (paymentQueue.retryFailed + sync, disabled offline
  / when empty), and a "Clear queue" behind an inline confirmation
  (paymentQueue.clear). Targets paymentQueue, not the messaging queue.
- Wired into /payment/dashboard behind the existing provider feature-flag gate.
- E2E: un-skipped a real "queue UI renders on the dashboard" test (no creds
  needed — the queue is client-side); rewrote the 8 stale "UI not yet
  implemented" skip reasons to the actual remaining blocker (a queue-seed
  fixture / provider creds), since the UI now exists.

Verification: type-check, lint, structure (110/110), build green; 7 component
tests (empty state, item+retry-count rendering, retry→retryFailed+sync,
offline-disables-retry, clear-needs-confirmation) pass.

Co-authored-by: TurtleWolfe <TurtleWolfe@users.noreply.github.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: 3 people

src/app/payment/dashboard/PaymentDashboardContent.tsx

@@ -2,6 +2,7 @@
 
 import React from 'react';
 import { PaymentHistory } from '@/components/payment/PaymentHistory';
+import { PaymentQueuePanel } from '@/components/payment/PaymentQueuePanel';
 import { featureFlags } from '@/config/payment';
 
 /**
@@ -43,6 +44,18 @@ export function PaymentDashboardContent() {
         </div>
       )}
 
+      {/* Offline payment queue management (#4). Shown when a provider is
+          configured — the queue itself works offline regardless, but the panel
+          is only meaningful where payments can actually be made. */}
+      {!noProvidersConfigured && (
+        <section aria-labelledby="payment-queue-heading">
+          <h2 id="payment-queue-heading" className="sr-only">
+            Offline payment queue
+          </h2>
+          <PaymentQueuePanel />
+        </section>
+      )}
+
       <section aria-labelledby="payment-history-heading">
         <h2 id="payment-history-heading" className="mb-4 text-2xl font-bold">
           Payment History

src/components/payment/PaymentQueuePanel/PaymentQueuePanel.accessibility.test.tsx

@@ -0,0 +1,56 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { render, waitFor } from '@testing-library/react';
+import { axe, toHaveNoViolations } from 'jest-axe';
+import PaymentQueuePanel from './PaymentQueuePanel';
+import type { PaymentQueueItem } from '@/lib/offline-queue/types';
+
+expect.extend(toHaveNoViolations);
+
+const items: PaymentQueueItem[] = [
+  {
+    id: 1,
+    status: 'failed',
+    retries: 2,
+    createdAt: Date.now(),
+    type: 'payment_intent',
+    data: { amount: 1000 },
+    lastError: 'Network error',
+  } as PaymentQueueItem,
+];
+
+let queueData: PaymentQueueItem[] = [];
+
+vi.mock('@/lib/offline-queue/payment-adapter', () => ({
+  paymentQueue: {
+    getQueue: () => Promise.resolve(queueData),
+    retryFailed: () => Promise.resolve(0),
+    sync: () =>
+      Promise.resolve({ success: 0, failed: 0, skipped: 0, conflicted: 0 }),
+    clear: () => Promise.resolve(),
+  },
+}));
+
+vi.mock('@/hooks/useOfflineStatus', () => ({
+  useOfflineStatus: () => ({ isOffline: false }),
+}));
+
+describe('PaymentQueuePanel Accessibility', () => {
+  beforeEach(() => {
+    queueData = [];
+  });
+
+  it('has no violations in the empty state', async () => {
+    const { container } = render(<PaymentQueuePanel pollIntervalMs={999999} />);
+    await waitFor(() => expect(container.firstChild).toBeInTheDocument());
+    expect(await axe(container)).toHaveNoViolations();
+  });
+
+  it('has no violations with queued items', async () => {
+    queueData = items;
+    const { container, findByTestId } = render(
+      <PaymentQueuePanel pollIntervalMs={999999} />
+    );
+    await findByTestId('queue-items');
+    expect(await axe(container)).toHaveNoViolations();
+  });
+});

src/components/payment/PaymentQueuePanel/PaymentQueuePanel.stories.tsx

@@ -0,0 +1,24 @@
+import type { Meta, StoryObj } from '@storybook/nextjs-vite';
+import PaymentQueuePanel from './PaymentQueuePanel';
+
+const meta: Meta<typeof PaymentQueuePanel> = {
+  title: 'Features/Payment/PaymentQueuePanel',
+  component: PaymentQueuePanel,
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component:
+          'User-facing management surface for the offline payment queue (#4) — status, queued items + retry counts, manual retry, and clear-queue. Reads the live `paymentQueue`; in Storybook (empty IndexedDB) it shows the empty state.',
+      },
+    },
+  },
+  tags: ['autodocs'],
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: { pollIntervalMs: 999999 },
+};

src/components/payment/PaymentQueuePanel/PaymentQueuePanel.test.tsx

@@ -0,0 +1,126 @@
+import { render, screen, waitFor, fireEvent } from '@testing-library/react';
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import PaymentQueuePanel from './PaymentQueuePanel';
+import type { PaymentQueueItem } from '@/lib/offline-queue/types';
+
+const mockQueue = {
+  getQueue: vi.fn(),
+  retryFailed: vi.fn(),
+  sync: vi.fn(),
+  clear: vi.fn(),
+};
+let offline = false;
+
+vi.mock('@/lib/offline-queue/payment-adapter', () => ({
+  paymentQueue: {
+    getQueue: (...a: unknown[]) => mockQueue.getQueue(...a),
+    retryFailed: (...a: unknown[]) => mockQueue.retryFailed(...a),
+    sync: (...a: unknown[]) => mockQueue.sync(...a),
+    clear: (...a: unknown[]) => mockQueue.clear(...a),
+  },
+}));
+
+vi.mock('@/hooks/useOfflineStatus', () => ({
+  useOfflineStatus: () => ({ isOffline: offline }),
+}));
+
+function makeItem(over: Partial<PaymentQueueItem> = {}): PaymentQueueItem {
+  return {
+    id: 1,
+    status: 'pending',
+    retries: 0,
+    createdAt: Date.now(),
+    type: 'payment_intent',
+    data: { amount: 1000 },
+    ...over,
+  } as PaymentQueueItem;
+}
+
+describe('PaymentQueuePanel', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    offline = false;
+    mockQueue.getQueue.mockResolvedValue([]);
+    mockQueue.retryFailed.mockResolvedValue(0);
+    mockQueue.sync.mockResolvedValue({
+      success: 0,
+      failed: 0,
+      skipped: 0,
+      conflicted: 0,
+    });
+    mockQueue.clear.mockResolvedValue(undefined);
+  });
+
+  it('shows the empty state when the queue is empty', async () => {
+    render(<PaymentQueuePanel pollIntervalMs={999999} />);
+    await waitFor(() =>
+      expect(screen.getByTestId('queue-count')).toHaveTextContent(
+        /no queued payments/i
+      )
+    );
+    expect(screen.getByTestId('queue-retry')).toBeDisabled();
+    expect(screen.getByTestId('queue-clear')).toBeDisabled();
+  });
+
+  it('lists queued items with their retry counts', async () => {
+    mockQueue.getQueue.mockResolvedValue([
+      makeItem({ id: 1, retries: 2 }),
+      makeItem({ id: 2, status: 'failed', retries: 5, lastError: 'boom' }),
+    ]);
+    render(<PaymentQueuePanel pollIntervalMs={999999} />);
+    await waitFor(() =>
+      expect(screen.getByTestId('queue-items')).toBeInTheDocument()
+    );
+    expect(screen.getByTestId('queue-item-retries-1')).toHaveTextContent(
+      /attempt 2\/5/i
+    );
+    // At max retries → "Max retries"
+    expect(screen.getByTestId('queue-item-retries-2')).toHaveTextContent(
+      /max retries/i
+    );
+    expect(screen.getByText('boom')).toBeInTheDocument();
+    expect(screen.getByTestId('queue-count')).toHaveTextContent(/1 pending/i);
+    expect(screen.getByTestId('queue-count')).toHaveTextContent(/1 failed/i);
+  });
+
+  it('retry calls retryFailed then sync', async () => {
+    mockQueue.getQueue.mockResolvedValue([
+      makeItem({ status: 'failed', retries: 1 }),
+    ]);
+    render(<PaymentQueuePanel pollIntervalMs={999999} />);
+    await waitFor(() =>
+      expect(screen.getByTestId('queue-retry')).toBeEnabled()
+    );
+    fireEvent.click(screen.getByTestId('queue-retry'));
+    await waitFor(() => expect(mockQueue.retryFailed).toHaveBeenCalledTimes(1));
+    expect(mockQueue.sync).toHaveBeenCalledTimes(1);
+  });
+
+  it('disables Retry now when offline', async () => {
+    offline = true;
+    mockQueue.getQueue.mockResolvedValue([makeItem()]);
+    render(<PaymentQueuePanel pollIntervalMs={999999} />);
+    await waitFor(() =>
+      expect(screen.getByTestId('queue-conn-state')).toHaveTextContent(
+        /offline/i
+      )
+    );
+    expect(screen.getByTestId('queue-retry')).toBeDisabled();
+  });
+
+  it('clear requires confirmation before calling clear()', async () => {
+    mockQueue.getQueue.mockResolvedValue([makeItem()]);
+    render(<PaymentQueuePanel pollIntervalMs={999999} />);
+    await waitFor(() =>
+      expect(screen.getByTestId('queue-clear')).toBeEnabled()
+    );
+
+    fireEvent.click(screen.getByTestId('queue-clear'));
+    // Confirmation appears; clear NOT yet called.
+    expect(screen.getByTestId('queue-clear-confirm')).toBeInTheDocument();
+    expect(mockQueue.clear).not.toHaveBeenCalled();
+
+    fireEvent.click(screen.getByTestId('queue-clear-confirm-yes'));
+    await waitFor(() => expect(mockQueue.clear).toHaveBeenCalledTimes(1));
+  });
+});