feat(uat-batch): Group I — Residential parity (4 ships)

I34–I37 from the 2026-05-21 plan.

Shipped:
  I34  Residential client header layout parity. Email / Call /
       WhatsApp action buttons mirror the main ClientDetailHeader.
       WhatsApp number resolves from phoneE164 (preferred) or strips
       the free-text phone to digits. Header surfaces "Linked to
       main client" chip when the auto-link matcher (I37) finds a
       counterpart in the main CRM.
  I35  Residential interests list rebuilt for parity with the main
       InterestList. New ResidentialInterestCard +
       getResidentialInterestColumns + residentialInterestFilter-
       Definitions; the list page drives DataTable + FilterBar +
       ColumnPicker + SavedViewsDropdown + bulkActions. List
       endpoint validator widened to accept pipelineStage as a
       string OR string[] and added a source filter. Service post-
       fetches client names via a single IN-list lookup so the
       table renders fullName in column 1 without N+1.
       New /api/v1/residential/interests/bulk supports
       change_stage + archive (100-id cap). Kanban view deferred.
  I36  Residential inquiries auto-forward to partner email(s).
       New registry entry residential_partner_recipients (comma-
       separated) under section residential.partner.
       createResidentialInterest fires
       forwardResidentialInquiryToPartner after the row lands.
       Helper uses the same branded shell other transactional
       emails use. Failures log + never block create. The
       /admin/residential-stages page picks up a registry-driven
       card so admins manage recipients alongside stages.
  I37  Auto-link residential ↔ main client. Migration 0080 adds
       residential_clients.linked_client_id (nullable FK, SET NULL
       on cascade) + partial index. New findAndLinkMatchingMainClient
       service matches by email first (case-insensitive client_contacts
       lookup) then by E.164 phone. First exact match wins. Fires
       fire-and-forget from createResidentialClient. Header surfaces
       the link via a "Linked to main client" chip. Backfill script
       + reverse-direction link from main ClientDetailHeader stay
       as follow-ups.

Verified: tsc clean, vitest 1454/1454, migration applied.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

src/components/residential/residential-interests-list.tsx

@@ -1,11 +1,20 @@
 'use client';
 
 import { useState } from 'react';
-import Link from 'next/link';
 import { useParams, useRouter } from 'next/navigation';
-import { useQuery } from '@tanstack/react-query';
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+import { Archive, ArrowRight, LayoutList, Plus } from 'lucide-react';
+import { toast } from 'sonner';
 
-import { Input } from '@/components/ui/input';
+import { Button } from '@/components/ui/button';
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from '@/components/ui/dialog';
 import {
   Select,
   SelectContent,
@@ -13,51 +22,73 @@ import {
   SelectTrigger,
   SelectValue,
 } from '@/components/ui/select';
+import { ColumnPicker } from '@/components/shared/column-picker';
+import { DataTable } from '@/components/shared/data-table';
+import { EmptyState } from '@/components/shared/empty-state';
+import { FilterBar } from '@/components/shared/filter-bar';
 import { PageHeader } from '@/components/shared/page-header';
+import { SaveViewDialog } from '@/components/shared/save-view-dialog';
+import { SavedViewsDropdown } from '@/components/shared/saved-views-dropdown';
+import { TableSkeleton } from '@/components/shared/loading-skeleton';
+import { useConfirmation } from '@/hooks/use-confirmation';
+import { usePaginatedQuery } from '@/hooks/use-paginated-query';
+import { usePermissions } from '@/hooks/use-permissions';
 import { useRealtimeInvalidation } from '@/hooks/use-realtime-invalidation';
+import { useTablePreferences } from '@/hooks/use-table-preferences';
 import { apiFetch } from '@/lib/api/client';
-import { PIPELINE_STAGES } from '@/lib/validators/residential';
-
-interface ResidentialInterestRow {
-  id: string;
-  residentialClientId: string;
-  pipelineStage: string;
-  source: string | null;
-  notes: string | null;
-  preferences: string | null;
-  assignedTo: string | null;
-  updatedAt: string;
-}
-
-interface ListResponse {
-  data: ResidentialInterestRow[];
-  pagination: { total: number };
-}
-
-const STAGE_LABELS: Record<string, string> = {
-  new: 'New',
-  contacted: 'Contacted',
-  viewing_scheduled: 'Viewing scheduled',
-  offer_made: 'Offer made',
-  offer_accepted: 'Offer accepted',
-  closed_won: 'Closed - won',
-  closed_lost: 'Closed - lost',
-};
+import { ResidentialInterestCard } from './residential-interest-card';
+import {
+  getResidentialInterestColumns,
+  RESIDENTIAL_INTEREST_COLUMN_OPTIONS,
+  RESIDENTIAL_INTEREST_DEFAULT_HIDDEN,
+  type ResidentialInterestRow,
+} from './residential-interest-columns';
+import {
+  DEFAULT_RESIDENTIAL_PIPELINE_STAGES,
+  RESIDENTIAL_STAGE_LABELS,
+  residentialInterestFilterDefinitions,
+} from './residential-interest-filters';
 
+/**
+ * Residential interests list — parity with the main InterestList. Wires
+ * the same DataTable + FilterBar + ColumnPicker + SavedViews + bulkActions
+ * stack onto the /api/v1/residential/interests endpoint. Kanban view is
+ * intentionally omitted (the residential pipeline stages differ and the
+ * board layout isn't yet wired through for them — opens as a follow-up).
+ */
 export function ResidentialInterestsList() {
   const params = useParams<{ portSlug: string }>();
   const router = useRouter();
   const portSlug = params?.portSlug ?? '';
-  const [search, setSearch] = useState('');
-  const [stage, setStage] = useState<string>('all');
+  const queryClient = useQueryClient();
+  const { confirm, dialog: confirmDialog } = useConfirmation();
+  const { can } = usePermissions();
+  const [saveViewOpen, setSaveViewOpen] = useState(false);
 
-  const { data, isLoading } = useQuery<ListResponse>({
-    queryKey: ['residential-interests', { search, stage }],
-    queryFn: () => {
-      const qs = new URLSearchParams({ search, limit: '50' });
-      if (stage !== 'all') qs.set('pipelineStage', stage);
-      return apiFetch(`/api/v1/residential/interests?${qs.toString()}`);
-    },
+  // Bulk-action dialog state — same shape as the main InterestList so
+  // the inner controls feel identical.
+  const [stageDialog, setStageDialog] = useState<{ ids: string[] } | null>(null);
+  const [stageChoice, setStageChoice] = useState<string>(
+    DEFAULT_RESIDENTIAL_PIPELINE_STAGES[0] ?? 'new',
+  );
+
+  const {
+    data,
+    pagination,
+    isLoading,
+    isFetching,
+    sort,
+    setSort,
+    setPage,
+    setPageSize,
+    filters,
+    setFilter,
+    setAllFilters,
+    clearFilters,
+  } = usePaginatedQuery<ResidentialInterestRow>({
+    queryKey: ['residential-interests'],
+    endpoint: '/api/v1/residential/interests',
+    filterDefinitions: residentialInterestFilterDefinitions,
   });
 
   useRealtimeInvalidation({
@@ -66,141 +97,231 @@ export function ResidentialInterestsList() {
     'residential_interest:archived': [['residential-interests']],
   });
 
+  // Mirror the main list's two-mutation idiom — per-row archive when the
+  // rep uses the kebab on a single row, bulk endpoint when they tick the
+  // checkbox in the header.
+  const archiveMutation = useMutation({
+    mutationFn: (id: string) =>
+      apiFetch(`/api/v1/residential/interests/${id}`, { method: 'DELETE' }),
+    onSuccess: () => {
+      void queryClient.invalidateQueries({ queryKey: ['residential-interests'] });
+    },
+  });
+
+  const bulkMutation = useMutation({
+    mutationFn: async (
+      payload:
+        | { action: 'archive'; ids: string[] }
+        | { action: 'change_stage'; ids: string[]; pipelineStage: string },
+    ) =>
+      apiFetch<{
+        data: { summary: { total: number; succeeded: number; failed: number } };
+      }>('/api/v1/residential/interests/bulk', { method: 'POST', body: payload }),
+    onSuccess: (res) => {
+      void queryClient.invalidateQueries({ queryKey: ['residential-interests'] });
+      const s = res.data.summary;
+      if (s.failed > 0) {
+        toast.warning(
+          `${s.succeeded} of ${s.total} succeeded. ${s.failed} failed — check the activity log.`,
+        );
+      } else {
+        toast.success(`Updated ${s.succeeded} interest${s.succeeded === 1 ? '' : 's'}`);
+      }
+    },
+  });
+
+  const columns = getResidentialInterestColumns({
+    portSlug,
+    onArchive: async (interest) => {
+      const ok = await confirm({
+        title: 'Archive interest',
+        description: 'This can be undone from the archived list.',
+        confirmLabel: 'Archive',
+      });
+      if (!ok) return;
+      archiveMutation.mutate(interest.id);
+    },
+  });
+
+  // Persisted per-user column visibility + density.
+  const { hidden, setHidden, density } = useTablePreferences(
+    'residential_interests',
+    RESIDENTIAL_INTEREST_DEFAULT_HIDDEN,
+  );
+  const columnVisibility = Object.fromEntries(hidden.map((id) => [id, false]));
+
+  // Stages enum is set at module load — no runtime invariant to enforce.
+  // (Earlier draft had a useEffect resetting `stageChoice` if it fell
+  // out of the enum; React Compiler flags setState-in-effect, so we
+  // rely on the dropdown's controlled value to enforce validity.)
+
   return (
     <div className="space-y-4">
       <PageHeader
         title="Residential Interests"
         description="Inquiries flowing through the residential pipeline"
+        variant="gradient"
+        actions={
+          <div className="flex items-center gap-2">
+            <div
+              className="hidden sm:flex items-center border rounded-md overflow-hidden"
+              role="group"
+              aria-label="View mode"
+            >
+              <Button
+                size="sm"
+                variant="default"
+                className="rounded-none"
+                aria-label="Table view"
+                aria-pressed
+                disabled
+              >
+                <LayoutList className="h-4 w-4" aria-hidden />
+              </Button>
+            </div>
+          </div>
+        }
       />
 
-      <div className="flex items-center gap-2">
-        <Input
-          placeholder="Search notes / preferences…"
-          value={search}
-          onChange={(e) => setSearch(e.target.value)}
-          className="max-w-sm h-9"
+      <div className="flex flex-wrap items-center gap-2">
+        <FilterBar
+          filters={residentialInterestFilterDefinitions}
+          values={filters}
+          onChange={setFilter}
+          onClear={clearFilters}
         />
-        <Select value={stage} onValueChange={setStage}>
-          <SelectTrigger className="w-52">
-            <SelectValue placeholder="All stages" />
-          </SelectTrigger>
-          <SelectContent>
-            <SelectItem value="all">All stages</SelectItem>
-            {PIPELINE_STAGES.map((s) => (
-              <SelectItem key={s} value={s}>
-                {STAGE_LABELS[s] ?? s}
-              </SelectItem>
-            ))}
-          </SelectContent>
-        </Select>
+        <div className="ml-auto flex flex-wrap items-center gap-2">
+          <SavedViewsDropdown
+            entityType="residential_interests"
+            onApplyView={(savedFilters) => setAllFilters(savedFilters)}
+          />
+          <ColumnPicker
+            columns={RESIDENTIAL_INTEREST_COLUMN_OPTIONS}
+            hidden={hidden}
+            onChange={setHidden}
+            onSaveView={() => setSaveViewOpen(true)}
+          />
+        </div>
       </div>
 
-      {/* Desktop: table layout. Hidden below lg; mobile renders cards. */}
-      <div className="hidden lg:block rounded-lg border bg-card overflow-hidden">
-        <table className="w-full text-sm">
-          <thead className="bg-muted/40 text-xs text-muted-foreground">
-            <tr>
-              <th className="text-left font-medium px-3 py-2">Stage</th>
-              <th className="text-left font-medium px-3 py-2">Preferences</th>
-              <th className="text-left font-medium px-3 py-2">Notes</th>
-              <th className="text-left font-medium px-3 py-2">Source</th>
-              <th className="text-left font-medium px-3 py-2">Updated</th>
-            </tr>
-          </thead>
-          <tbody>
-            {isLoading && (
-              <tr>
-                <td colSpan={5} className="px-3 py-8 text-center text-muted-foreground">
-                  Loading…
-                </td>
-              </tr>
-            )}
-            {!isLoading && data?.data.length === 0 && (
-              <tr>
-                <td colSpan={5} className="px-3 py-8 text-center text-muted-foreground">
-                  No interests match.
-                </td>
-              </tr>
-            )}
-            {data?.data.map((i) => (
-              <tr
-                key={i.id}
-                className="border-t hover:bg-muted/30 transition-colors cursor-pointer"
-                // Whole-row navigation — clicking anywhere on the row opens
-                // the interest detail. The first-cell Link still works for
-                // middle-click / Cmd+click "open in new tab" + keyboard
-                // navigation; the row onClick covers the common case where
-                // reps click on Preferences / Notes columns.
-                onClick={() => router.push(`/${portSlug}/residential/interests/${i.id}` as never)}
-              >
-                <td className="px-3 py-2">
-                  <Link
-                    /* eslint-disable-next-line @typescript-eslint/no-explicit-any */
-                    href={`/${portSlug}/residential/interests/${i.id}` as any}
-                    className="font-medium hover:underline"
-                    // Don't fire the row's onClick when the rep middle-clicks
-                    // the link — the Link's native handler covers that path.
-                    onClick={(e) => e.stopPropagation()}
-                  >
-                    {STAGE_LABELS[i.pipelineStage] ?? i.pipelineStage}
-                  </Link>
-                </td>
-                <td className="px-3 py-2 text-muted-foreground truncate max-w-xs">
-                  {i.preferences ?? '-'}
-                </td>
-                <td className="px-3 py-2 text-muted-foreground truncate max-w-xs">
-                  {i.notes ?? '-'}
-                </td>
-                <td className="px-3 py-2 capitalize text-muted-foreground">{i.source ?? '-'}</td>
-                <td className="px-3 py-2 text-muted-foreground text-xs">
-                  {new Date(i.updatedAt).toLocaleDateString()}
-                </td>
-              </tr>
-            ))}
-          </tbody>
-        </table>
-      </div>
+      <SaveViewDialog
+        open={saveViewOpen}
+        onOpenChange={setSaveViewOpen}
+        entityType="residential_interests"
+        currentFilters={filters}
+        currentSort={sort}
+      />
 
-      {/* Mobile: card list. Stage as the headline (it's the most actionable
-          field for triage), preferences/notes truncated below. */}
-      <div className="lg:hidden space-y-2">
-        {isLoading && (
-          <div className="rounded-lg border bg-card px-3 py-8 text-center text-sm text-muted-foreground">
-            Loading…
+      {isLoading ? (
+        <TableSkeleton />
+      ) : (
+        <DataTable
+          columns={columns}
+          columnVisibility={columnVisibility}
+          density={density}
+          data={data}
+          pagination={pagination}
+          onPaginationChange={(p, ps) => {
+            setPage(p);
+            setPageSize(ps);
+          }}
+          sort={sort}
+          onSortChange={setSort}
+          isLoading={isFetching && !isLoading}
+          getRowId={(row) => row.id}
+          onRowClick={(row) => router.push(`/${portSlug}/residential/interests/${row.id}` as never)}
+          bulkActions={
+            can('residential_interests', 'edit')
+              ? [
+                  {
+                    label: 'Change stage',
+                    icon: ArrowRight,
+                    onClick: (ids) => {
+                      if (ids.length === 0) return;
+                      setStageChoice(DEFAULT_RESIDENTIAL_PIPELINE_STAGES[0] ?? 'new');
+                      setStageDialog({ ids });
+                    },
+                  },
+                  ...(can('residential_interests', 'delete')
+                    ? [
+                        {
+                          label: 'Archive',
+                          icon: Archive,
+                          variant: 'destructive' as const,
+                          onClick: async (ids: string[]) => {
+                            if (ids.length === 0) return;
+                            const ok = await confirm({
+                              title: `Archive ${ids.length} interest${ids.length === 1 ? '' : 's'}`,
+                              description: 'This can be undone from the archived list.',
+                              confirmLabel: 'Archive',
+                            });
+                            if (!ok) return;
+                            bulkMutation.mutate({ action: 'archive', ids });
+                          },
+                        },
+                      ]
+                    : []),
+                ]
+              : undefined
+          }
+          cardRender={(row) => (
+            <ResidentialInterestCard interest={row.original} portSlug={portSlug} />
+          )}
+          emptyState={
+            <EmptyState
+              title="No residential interests"
+              description="Inquiries will appear here once the website intake fires or a rep creates one manually."
+              icon={Plus}
+            />
+          }
+        />
+      )}
+
+      {/* Bulk: change stage */}
+      <Dialog open={!!stageDialog} onOpenChange={(o) => !o && setStageDialog(null)}>
+        <DialogContent>
+          <DialogHeader>
+            <DialogTitle>Change stage</DialogTitle>
+            <DialogDescription>
+              Move {stageDialog?.ids.length ?? 0} interest
+              {stageDialog?.ids.length === 1 ? '' : 's'} to a new pipeline stage.
+            </DialogDescription>
+          </DialogHeader>
+          <div className="py-2">
+            <Select value={stageChoice} onValueChange={setStageChoice}>
+              <SelectTrigger>
+                <SelectValue />
+              </SelectTrigger>
+              <SelectContent>
+                {DEFAULT_RESIDENTIAL_PIPELINE_STAGES.map((s) => (
+                  <SelectItem key={s} value={s}>
+                    {RESIDENTIAL_STAGE_LABELS[s] ?? s}
+                  </SelectItem>
+                ))}
+              </SelectContent>
+            </Select>
           </div>
-        )}
-        {!isLoading && data?.data.length === 0 && (
-          <div className="rounded-lg border bg-card px-3 py-8 text-center text-sm text-muted-foreground">
-            No interests match.
-          </div>
-        )}
-        {data?.data.map((i) => (
-          <Link
-            key={i.id}
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            href={`/${portSlug}/residential/interests/${i.id}` as any}
-            className="block rounded-lg border bg-card p-3 transition-colors hover:bg-muted/30"
-          >
-            <div className="flex items-start justify-between gap-2">
-              <p className="font-medium text-sm">
-                {STAGE_LABELS[i.pipelineStage] ?? i.pipelineStage}
-              </p>
-              <span className="shrink-0 text-[11px] text-muted-foreground">
-                {new Date(i.updatedAt).toLocaleDateString()}
-              </span>
-            </div>
-            {i.preferences ? (
-              <p className="mt-1 line-clamp-2 text-xs text-muted-foreground">{i.preferences}</p>
-            ) : null}
-            {i.notes ? (
-              <p className="mt-1 line-clamp-1 text-xs text-muted-foreground/80">{i.notes}</p>
-            ) : null}
-            {i.source ? (
-              <p className="mt-1 text-[11px] capitalize text-muted-foreground">{i.source}</p>
-            ) : null}
-          </Link>
-        ))}
-      </div>
+          <DialogFooter>
+            <Button variant="outline" onClick={() => setStageDialog(null)}>
+              Cancel
+            </Button>
+            <Button
+              disabled={bulkMutation.isPending}
+              onClick={() => {
+                if (!stageDialog) return;
+                bulkMutation.mutate(
+                  { action: 'change_stage', ids: stageDialog.ids, pipelineStage: stageChoice },
+                  { onSettled: () => setStageDialog(null) },
+                );
+              }}
+            >
+              Apply
+            </Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+
+      {confirmDialog}
     </div>
   );
 }