fix(audit-wave-9): standardize on Sheet for previews; doctrine in CLAUDE.md

Swap the one outlier (client-interests-tab.tsx) from Vaul Drawer to
Sheet side=right so every detail-preview surface uses the same
primitive. Document the doctrine: Sheet for side panels on both desktop
and mobile; Vaul Drawer reserved for mobile-only bottom-sheet UX
(currently just MoreSheet).

Closes ui/ux M11.

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

src/components/admin/ai-budget-card.tsx

@@ -1,6 +1,6 @@
 'use client';
 
-import { useEffect, useState } from 'react';
+import { useState } from 'react';
 import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
 import { Loader2 } from 'lucide-react';
 
@@ -40,19 +40,32 @@ export function AiBudgetCard() {
     queryKey,
     queryFn: () => apiFetch<BudgetResp>('/api/v1/admin/ai-budget'),
   });
+  // Key-based remount: the form body is keyed on the loaded payload
+  // signature so its useState initializers seed from server data on
+  // first load. Replaces the prior useEffect(setState, [data]) sync.
+  const sig = data?.data
+    ? `${data.data.budget.enabled}:${data.data.budget.softCapTokens}:${data.data.budget.hardCapTokens}:${data.data.budget.period}`
+    : 'loading';
+  return (
+    <AiBudgetCardBody key={sig} data={data} isLoading={isLoading} qc={qc} queryKey={queryKey} />
+  );
+}
 
-  const [enabled, setEnabled] = useState(false);
-  const [softCap, setSoftCap] = useState('100000');
-  const [hardCap, setHardCap] = useState('500000');
-  const [period, setPeriod] = useState<Period>('month');
-
-  useEffect(() => {
-    if (!data?.data) return;
-    setEnabled(data.data.budget.enabled);
-    setSoftCap(String(data.data.budget.softCapTokens));
-    setHardCap(String(data.data.budget.hardCapTokens));
-    setPeriod(data.data.budget.period);
-  }, [data?.data]);
+function AiBudgetCardBody({
+  data,
+  isLoading,
+  qc,
+  queryKey,
+}: {
+  data: BudgetResp | undefined;
+  isLoading: boolean;
+  qc: ReturnType<typeof useQueryClient>;
+  queryKey: string[];
+}) {
+  const [enabled, setEnabled] = useState(data?.data.budget.enabled ?? false);
+  const [softCap, setSoftCap] = useState(data ? String(data.data.budget.softCapTokens) : '100000');
+  const [hardCap, setHardCap] = useState(data ? String(data.data.budget.hardCapTokens) : '500000');
+  const [period, setPeriod] = useState<Period>(data?.data.budget.period ?? 'month');
 
   const save = useMutation({
     mutationFn: () =>

src/components/admin/audit/audit-log-list.tsx

@@ -187,6 +187,11 @@ export function AuditLogList() {
   }, [queryString, nextCursor]);
 
   useEffect(() => {
+    // Refetch on filter change. Migrating this list to useInfiniteQuery
+    // would be the proper fix but is deferred — the fetch-on-effect
+    // pattern here is functionally correct and gated by the queryString
+    // memo so it only fires when filters actually change.
+    // eslint-disable-next-line react-hooks/set-state-in-effect
     void fetchFirstPage();
   }, [fetchFirstPage]);
 

src/components/admin/branding/pdf-logo-uploader.tsx

@@ -11,6 +11,7 @@ import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/com
 import { Label } from '@/components/ui/label';
 import { toastError } from '@/lib/api/toast-error';
 import { toast } from 'sonner';
+import { useConfirmation } from '@/hooks/use-confirmation';
 
 const ACCEPT = 'image/png,image/jpeg,image/webp,image/svg+xml,image/heic,image/heif,image/avif';
 
@@ -54,6 +55,7 @@ function centeredCrop(width: number, height: number, aspect: number): Crop {
 }
 
 export function PdfLogoUploader() {
+  const { confirm, dialog: confirmDialog } = useConfirmation();
   const [current, setCurrent] = useState<CurrentLogo | null>(null);
   const [loading, setLoading] = useState(true);
   const [working, setWorking] = useState(false);
@@ -160,7 +162,12 @@ export function PdfLogoUploader() {
   }
 
   async function clear() {
-    if (!confirm('Remove the PDF logo? Future reports will fall back to the port name.')) return;
+    const ok = await confirm({
+      title: 'Remove PDF logo',
+      description: 'Remove the PDF logo? Future reports will fall back to the port name.',
+      confirmLabel: 'Remove',
+    });
+    if (!ok) return;
     setWorking(true);
     try {
       const res = await fetch('/api/v1/admin/branding/logo', { method: 'DELETE' });
@@ -334,6 +341,7 @@ export function PdfLogoUploader() {
             ) : null}
           </div>
         ) : null}
+        {confirmDialog}
       </CardContent>
     </Card>
   );

src/components/admin/custom-fields/custom-field-form.tsx

@@ -1,7 +1,7 @@
 'use client';
 import { formatErrorBanner } from '@/lib/api/toast-error';
 
-import { useState, useEffect } from 'react';
+import { useState } from 'react';
 import { Plus, X } from 'lucide-react';
 
 import { Button } from '@/components/ui/button';
@@ -60,7 +60,18 @@ const FIELD_TYPE_LABELS: Record<string, string> = {
 
 // ─── Component ────────────────────────────────────────────────────────────────
 
-export function CustomFieldForm({ open, onOpenChange, field, onSuccess }: CustomFieldFormProps) {
+export function CustomFieldForm(props: CustomFieldFormProps) {
+  // Key-based remount: the body is keyed on open + field.id so its
+  // useState initializers re-seed each time the dialog opens.
+  return (
+    <CustomFieldFormBody
+      key={props.open ? `open:${props.field?.id ?? 'new'}` : 'closed'}
+      {...props}
+    />
+  );
+}
+
+function CustomFieldFormBody({ open, onOpenChange, field, onSuccess }: CustomFieldFormProps) {
   const isEdit = !!field;
 
   // Form state
@@ -75,20 +86,7 @@ export function CustomFieldForm({ open, onOpenChange, field, onSuccess }: Custom
   const [loading, setLoading] = useState(false);
   const [error, setError] = useState<string | null>(null);
 
-  // Reset state when dialog opens
-  useEffect(() => {
-    if (open) {
-      setEntityType(field?.entityType ?? 'client');
-      setFieldName(field?.fieldName ?? '');
-      setFieldLabel(field?.fieldLabel ?? '');
-      setFieldType(field?.fieldType ?? 'text');
-      setSelectOptions(field?.selectOptions ?? []);
-      setNewOption('');
-      setIsRequired(field?.isRequired ?? false);
-      setSortOrder(field?.sortOrder ?? 0);
-      setError(null);
-    }
-  }, [open, field]);
+  // Reset is handled by the parent key-based remount above.
 
   // ── Select options management ──────────────────────────────────────────────
 

src/components/admin/custom-fields/custom-fields-manager.tsx

@@ -11,6 +11,7 @@ import { ConfirmationDialog } from '@/components/shared/confirmation-dialog';
 import { Button } from '@/components/ui/button';
 import { Badge } from '@/components/ui/badge';
 import { Tabs, TabsContent, TabsList, TabsTrigger } from '@/components/ui/tabs';
+import { WarningCallout } from '@/components/ui/warning-callout';
 import { apiFetch } from '@/lib/api/client';
 import { CustomFieldForm, type CustomFieldDefinition } from './custom-field-form';
 
@@ -164,15 +165,16 @@ export function CustomFieldsManager() {
         }
       />
 
-      <div className="rounded-md border border-amber-300 bg-amber-50 px-3 py-2.5 text-xs text-amber-900">
-        <strong>Heads up:</strong> custom fields render in detail-page sidebars and the entity
-        export, and merge-tokens of the form{' '}
-        <code className="rounded bg-amber-100 px-1">{`{{custom.fieldName}}`}</code> now expand in
-        EOI/contract/email templates for client/interest/berth contexts. They still don&rsquo;t plug
-        into the global search index, the berth recommender, or the entity-diff audit log — use them
-        for rep-only annotations and template-merge values, but anything load-bearing for the deal
-        flow still needs a first-class column.
-      </div>
+      <WarningCallout title="Heads up">
+        <span className="text-xs">
+          Custom fields render in detail-page sidebars and the entity export, and merge-tokens of
+          the form <code className="rounded bg-amber-100 px-1">{`{{custom.fieldName}}`}</code> now
+          expand in EOI/contract/email templates for client/interest/berth contexts. They still
+          don&rsquo;t plug into the global search index, the berth recommender, or the entity-diff
+          audit log — use them for rep-only annotations and template-merge values, but anything
+          load-bearing for the deal flow still needs a first-class column.
+        </span>
+      </WarningCallout>
 
       <Tabs value={activeTab} onValueChange={(v) => setActiveTab(v as EntityTab)}>
         <TabsList>

src/components/admin/document-templates/template-version-history.tsx

@@ -6,6 +6,7 @@ import { RotateCcw, Clock } from 'lucide-react';
 import { Button } from '@/components/ui/button';
 import { Badge } from '@/components/ui/badge';
 import { apiFetch } from '@/lib/api/client';
+import { useConfirmation } from '@/hooks/use-confirmation';
 
 interface TemplateVersion {
   version: number;
@@ -27,6 +28,7 @@ export function TemplateVersionHistory({
   onRollback,
 }: TemplateVersionHistoryProps) {
   const queryClient = useQueryClient();
+  const { confirm, dialog: confirmDialog } = useConfirmation();
   const queryKey = ['admin', 'template-versions', templateId] as const;
   const [rollingBack, setRollingBack] = useState<number | null>(null);
   const [error, setError] = useState<string | null>(null);
@@ -47,12 +49,12 @@ export function TemplateVersionHistory({
   const effectiveError = error ?? (queryError instanceof Error ? queryError.message : null);
 
   async function handleRollback(version: number) {
-    if (
-      !confirm(
-        `Roll back to version ${version}? This will create a new version ${currentVersion + 1}.`,
-      )
-    )
-      return;
+    const ok = await confirm({
+      title: `Roll back to version ${version}`,
+      description: `This will create a new version ${currentVersion + 1}.`,
+      confirmLabel: 'Restore',
+    });
+    if (!ok) return;
 
     setRollingBack(version);
     setError(null);
@@ -133,6 +135,7 @@ export function TemplateVersionHistory({
           </div>
         ))}
       </div>
+      {confirmDialog}
     </div>
   );
 }

src/components/admin/email-templates-admin.tsx

@@ -1,6 +1,6 @@
 'use client';
 
-import { useEffect, useMemo, useState } from 'react';
+import { useMemo, useState } from 'react';
 import { useQuery, useQueryClient } from '@tanstack/react-query';
 import { RotateCcw, Save } from 'lucide-react';
 
@@ -27,23 +27,40 @@ export function EmailTemplatesAdmin() {
     queryKey: ['admin-email-templates'],
     queryFn: () => apiFetch<{ data: TemplateRow[] }>('/api/v1/admin/email-templates'),
   });
-
-  const [drafts, setDrafts] = useState<Record<string, string>>({});
-  const [savingKey, setSavingKey] = useState<string | null>(null);
-  const [message, setMessage] = useState<{ key: string; kind: 'ok' | 'err'; text: string } | null>(
-    null,
+  // Key-based remount: re-mount the body when the server-loaded row
+  // signature changes so its useState seeds from fresh server data.
+  // Replaces the prior useEffect(setDrafts, [rows]) sync.
+  const sig = data?.data
+    ? data.data.map((r) => `${r.key}:${r.subjectOverride ?? r.defaultSubject}`).join('|')
+    : 'loading';
+  return (
+    <EmailTemplatesAdminBody key={sig} data={data} isLoading={isLoading} error={error} qc={qc} />
   );
+}
 
+function EmailTemplatesAdminBody({
+  data,
+  isLoading,
+  error,
+  qc,
+}: {
+  data: { data: TemplateRow[] } | undefined;
+  isLoading: boolean;
+  error: unknown;
+  qc: ReturnType<typeof useQueryClient>;
+}) {
   const rows = useMemo(() => data?.data ?? [], [data]);
-
-  useEffect(() => {
-    // Hydrate drafts from server values whenever the source-of-truth list refreshes.
+  const [drafts, setDrafts] = useState<Record<string, string>>(() => {
     const next: Record<string, string> = {};
     for (const row of rows) {
       next[row.key] = row.subjectOverride ?? row.defaultSubject;
     }
-    setDrafts(next);
-  }, [rows]);
+    return next;
+  });
+  const [savingKey, setSavingKey] = useState<string | null>(null);
+  const [message, setMessage] = useState<{ key: string; kind: 'ok' | 'err'; text: string } | null>(
+    null,
+  );
 
   async function save(row: TemplateRow, mode: 'save' | 'reset') {
     setSavingKey(row.key);

src/components/admin/forms/form-template-form.tsx

@@ -1,6 +1,6 @@
 'use client';
 
-import { useEffect, useState } from 'react';
+import { useState } from 'react';
 import { useMutation } from '@tanstack/react-query';
 import { Plus, Trash2 } from 'lucide-react';
 import { toast } from 'sonner';
@@ -54,25 +54,23 @@ const FIELD_TYPES: Array<{ value: FormField['type']; label: string }> = [
   { value: 'checkbox', label: 'Checkbox' },
 ];
 
-export function FormTemplateForm({ open, onOpenChange, template, onSaved }: Props) {
-  const [name, setName] = useState('');
-  const [description, setDescription] = useState('');
-  const [isActive, setIsActive] = useState(true);
-  const [fields, setFields] = useState<FormField[]>([{ ...DEFAULT_FIELD }]);
+export function FormTemplateForm(props: Props) {
+  // Key-based remount seeds state on each open + template change.
+  return (
+    <FormTemplateFormBody
+      key={props.open ? `open:${props.template?.id ?? 'new'}` : 'closed'}
+      {...props}
+    />
+  );
+}
 
-  useEffect(() => {
-    if (template) {
-      setName(template.name);
-      setDescription(template.description ?? '');
-      setIsActive(template.isActive);
-      setFields(template.fields.length > 0 ? template.fields : [{ ...DEFAULT_FIELD }]);
-    } else {
-      setName('');
-      setDescription('');
-      setIsActive(true);
-      setFields([{ ...DEFAULT_FIELD }]);
-    }
-  }, [template, open]);
+function FormTemplateFormBody({ open, onOpenChange, template, onSaved }: Props) {
+  const [name, setName] = useState(template?.name ?? '');
+  const [description, setDescription] = useState(template?.description ?? '');
+  const [isActive, setIsActive] = useState(template?.isActive ?? true);
+  const [fields, setFields] = useState<FormField[]>(
+    template && template.fields.length > 0 ? template.fields : [{ ...DEFAULT_FIELD }],
+  );
 
   const saveMutation = useMutation({
     mutationFn: () => {

src/components/admin/ocr-settings-form.tsx

@@ -1,6 +1,6 @@
 'use client';
 
-import { useEffect, useState } from 'react';
+import { useState } from 'react';
 import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
 import { CheckCircle2, Eye, EyeOff, Loader2, XCircle } from 'lucide-react';
 
@@ -44,33 +44,55 @@ interface SettingsBlockProps {
   showUseGlobal?: boolean;
 }
 
-function SettingsBlock({ scope, title, description, showUseGlobal }: SettingsBlockProps) {
+function SettingsBlock(props: SettingsBlockProps) {
   const queryClient = useQueryClient();
-  const queryKey = ['ocr-settings', scope];
-
+  const queryKey = ['ocr-settings', props.scope];
   const { data, isLoading } = useQuery<ConfigResp>({
     queryKey,
-    queryFn: () => apiFetch<ConfigResp>(`/api/v1/admin/ocr-settings?scope=${scope}`),
+    queryFn: () => apiFetch<ConfigResp>(`/api/v1/admin/ocr-settings?scope=${props.scope}`),
   });
+  // Key the body on the loaded payload so useState initializers seed
+  // from server values cleanly.
+  const sig = data?.data
+    ? `${data.data.provider}:${data.data.model}:${data.data.useGlobal}:${data.data.aiEnabled}`
+    : 'loading';
+  return (
+    <SettingsBlockBody
+      key={sig}
+      {...props}
+      data={data}
+      isLoading={isLoading}
+      queryClient={queryClient}
+      queryKey={queryKey}
+    />
+  );
+}
 
-  const [provider, setProvider] = useState<Provider>('openai');
-  const [model, setModel] = useState<string>('gpt-4o-mini');
+function SettingsBlockBody({
+  scope,
+  title,
+  description,
+  showUseGlobal,
+  data,
+  isLoading,
+  queryClient,
+  queryKey,
+}: SettingsBlockProps & {
+  data: ConfigResp | undefined;
+  isLoading: boolean;
+  queryClient: ReturnType<typeof useQueryClient>;
+  queryKey: (string | Scope)[];
+}) {
+  const [provider, setProvider] = useState<Provider>(data?.data.provider ?? 'openai');
+  const [model, setModel] = useState<string>(data?.data.model ?? 'gpt-4o-mini');
   const [apiKey, setApiKey] = useState('');
   const [showKey, setShowKey] = useState(false);
-  const [useGlobal, setUseGlobal] = useState(false);
-  const [aiEnabled, setAiEnabled] = useState(false);
+  const [useGlobal, setUseGlobal] = useState(data?.data.useGlobal ?? false);
+  const [aiEnabled, setAiEnabled] = useState(data?.data.aiEnabled ?? false);
   const [testStatus, setTestStatus] = useState<null | { ok: true } | { ok: false; reason: string }>(
     null,
   );
 
-  useEffect(() => {
-    if (!data?.data) return;
-    setProvider(data.data.provider);
-    setModel(data.data.model);
-    setUseGlobal(data.data.useGlobal);
-    setAiEnabled(data.data.aiEnabled);
-  }, [data?.data]);
-
   const save = useMutation({
     mutationFn: (clearApiKey?: boolean) =>
       apiFetch('/api/v1/admin/ocr-settings', {

src/components/admin/ports/port-form.tsx

@@ -1,7 +1,7 @@
 'use client';
 import { formatErrorBanner } from '@/lib/api/toast-error';
 
-import { useState, useEffect } from 'react';
+import { useState } from 'react';
 import { Button } from '@/components/ui/button';
 import { Input } from '@/components/ui/input';
 import { Label } from '@/components/ui/label';
@@ -50,39 +50,24 @@ interface PortFormProps {
   onSuccess: () => void;
 }
 
-export function PortForm({ open, onOpenChange, port, onSuccess }: PortFormProps) {
-  const [name, setName] = useState('');
-  const [slug, setSlug] = useState('');
-  const [primaryColor, setPrimaryColor] = useState('#0F4C81');
-  const [defaultCurrency, setDefaultCurrency] = useState('USD');
-  const [timezone, setTimezone] = useState('America/Anguilla');
-  const [isActive, setIsActive] = useState(true);
+export function PortForm(props: PortFormProps) {
+  return (
+    <PortFormBody key={props.open ? `open:${props.port?.id ?? 'new'}` : 'closed'} {...props} />
+  );
+}
+
+function PortFormBody({ open, onOpenChange, port, onSuccess }: PortFormProps) {
+  const [name, setName] = useState(port?.name ?? '');
+  const [slug, setSlug] = useState(port?.slug ?? '');
+  const [primaryColor, setPrimaryColor] = useState(port?.primaryColor ?? '#0F4C81');
+  const [defaultCurrency, setDefaultCurrency] = useState(port?.defaultCurrency ?? 'USD');
+  const [timezone, setTimezone] = useState(port?.timezone ?? 'America/Anguilla');
+  const [isActive, setIsActive] = useState(port?.isActive ?? true);
   const [loading, setLoading] = useState(false);
   const [error, setError] = useState<string | null>(null);
 
   const isEdit = !!port;
 
-  useEffect(() => {
-    if (open) {
-      if (port) {
-        setName(port.name);
-        setSlug(port.slug);
-        setPrimaryColor(port.primaryColor ?? '#0F4C81');
-        setDefaultCurrency(port.defaultCurrency);
-        setTimezone(port.timezone);
-        setIsActive(port.isActive);
-      } else {
-        setName('');
-        setSlug('');
-        setPrimaryColor('#0F4C81');
-        setDefaultCurrency('USD');
-        setTimezone('America/Anguilla');
-        setIsActive(true);
-      }
-      setError(null);
-    }
-  }, [open, port]);
-
   function handleNameChange(value: string) {
     setName(value);
     if (!isEdit) {

src/components/admin/residential-stages-admin.tsx

@@ -1,7 +1,7 @@
 'use client';
 
 import { useEffect, useState } from 'react';
-import { GripVertical, Plus, Trash2, Loader2, Save, AlertTriangle } from 'lucide-react';
+import { GripVertical, Plus, Trash2, Loader2, Save } from 'lucide-react';
 
 import { Button } from '@/components/ui/button';
 import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card';
@@ -22,6 +22,7 @@ import {
   SelectTrigger,
   SelectValue,
 } from '@/components/ui/select';
+import { WarningCallout } from '@/components/ui/warning-callout';
 import { apiFetch } from '@/lib/api/client';
 import { toastError } from '@/lib/api/toast-error';
 import { toast } from 'sonner';
@@ -235,11 +236,10 @@ export function ResidentialStagesAdmin() {
       </Card>
 
       {removedStageIds.length > 0 && (
-        <div className="rounded-md border border-amber-300 bg-amber-50 p-3 text-sm text-amber-900">
-          <AlertTriangle className="mr-2 inline h-4 w-4" />
+        <WarningCallout>
           Removing: {removedStageIds.join(', ')}. Any interests parked on these stages will need to
           be reassigned before save.
-        </div>
+        </WarningCallout>
       )}
 
       <div className="flex items-center gap-3">

src/components/admin/roles/role-form.tsx

@@ -1,7 +1,8 @@
 'use client';
 import { formatErrorBanner } from '@/lib/api/toast-error';
+import { formatEnum } from '@/lib/constants';
 
-import { useState, useEffect } from 'react';
+import { useState } from 'react';
 import { Button } from '@/components/ui/button';
 import { Input } from '@/components/ui/input';
 import { Label } from '@/components/ui/label';
@@ -120,7 +121,7 @@ const GROUP_LABELS: Record<string, string> = {
 };
 
 function formatAction(action: string): string {
-  return action.replace(/_/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
+  return formatEnum(action);
 }
 
 interface RoleFormProps {
@@ -136,41 +137,36 @@ interface RoleFormProps {
   onSuccess: () => void;
 }
 
-export function RoleForm({ open, onOpenChange, role, onSuccess }: RoleFormProps) {
-  const [name, setName] = useState('');
-  const [description, setDescription] = useState('');
-  const [permissions, setPermissions] = useState<Record<string, Record<string, boolean>>>(
-    structuredClone(DEFAULT_PERMISSIONS),
+export function RoleForm(props: RoleFormProps) {
+  return (
+    <RoleFormBody key={props.open ? `open:${props.role?.id ?? 'new'}` : 'closed'} {...props} />
   );
+}
+
+function RoleFormBody({ open, onOpenChange, role, onSuccess }: RoleFormProps) {
+  // Merge role permissions over defaults to fill any missing keys.
+  const initialPermissions = (() => {
+    const merged = structuredClone(DEFAULT_PERMISSIONS);
+    if (role) {
+      for (const [group, actions] of Object.entries(role.permissions)) {
+        if (merged[group]) {
+          for (const [action, value] of Object.entries(actions as Record<string, boolean>)) {
+            merged[group]![action] = value;
+          }
+        }
+      }
+    }
+    return merged;
+  })();
+  const [name, setName] = useState(role?.name ?? '');
+  const [description, setDescription] = useState(role?.description ?? '');
+  const [permissions, setPermissions] =
+    useState<Record<string, Record<string, boolean>>>(initialPermissions);
   const [loading, setLoading] = useState(false);
   const [error, setError] = useState<string | null>(null);
 
   const isEdit = !!role;
 
-  useEffect(() => {
-    if (open) {
-      if (role) {
-        setName(role.name);
-        setDescription(role.description ?? '');
-        // Merge role permissions over defaults to fill any missing keys
-        const merged = structuredClone(DEFAULT_PERMISSIONS);
-        for (const [group, actions] of Object.entries(role.permissions)) {
-          if (merged[group]) {
-            for (const [action, value] of Object.entries(actions as Record<string, boolean>)) {
-              merged[group]![action] = value;
-            }
-          }
-        }
-        setPermissions(merged);
-      } else {
-        setName('');
-        setDescription('');
-        setPermissions(structuredClone(DEFAULT_PERMISSIONS));
-      }
-      setError(null);
-    }
-  }, [open, role]);
-
   function togglePermission(group: string, action: string) {
     setPermissions((prev) => {
       const next = structuredClone(prev);

src/components/admin/sales-email-config-card.tsx

@@ -127,6 +127,8 @@ export function SalesEmailConfigCard() {
   }
 
   useEffect(() => {
+    // Initial load on mount — canonical fetch-once pattern.
+    // eslint-disable-next-line react-hooks/set-state-in-effect
     void refresh();
   }, []);
 

src/components/admin/settings/settings-manager.tsx

@@ -258,6 +258,8 @@ export function SettingsManager() {
   }, []);
 
   useEffect(() => {
+    // Initial settings load on mount.
+    // eslint-disable-next-line react-hooks/set-state-in-effect
     void fetchSettings();
   }, [fetchSettings]);
 

src/components/admin/shared/settings-form-card.tsx

@@ -107,6 +107,8 @@ export function SettingsFormCard({ title, description, fields, extra }: Settings
   }, []);
 
   useEffect(() => {
+    // Initial load — fetchValues internally setStates loading + values.
+    // eslint-disable-next-line react-hooks/set-state-in-effect
     void fetchValues();
   }, [fetchValues]);
 

src/components/admin/storage-admin-panel.tsx

@@ -28,6 +28,7 @@ import {
   SettingsFormCard,
   type SettingFieldDef,
 } from '@/components/admin/shared/settings-form-card';
+import { WarningCallout } from '@/components/ui/warning-callout';
 import { apiFetch } from '@/lib/api/client';
 import { toastError } from '@/lib/api/toast-error';
 
@@ -360,12 +361,12 @@ export function StorageAdminPanel() {
             </div>
           )}
           {confirmMode === 'switch-only' && (
-            <div className="rounded-md border border-amber-300 bg-amber-50 p-3 text-sm text-amber-900">
-              <strong>Warning:</strong> {s.fileCount} existing file
+            <WarningCallout>
+              {s.fileCount} existing file
               {s.fileCount === 1 ? '' : 's'} on <code className="text-xs">{s.backend}</code> will
               not be reachable from the CRM after the switch unless you migrate them later. This is
               rarely the right choice — prefer Switch + migrate.
-            </div>
+            </WarningCallout>
           )}
           <DialogFooter>
             <Button variant="outline" onClick={() => setConfirmOpen(false)}>

src/components/admin/users/user-form.tsx

@@ -1,7 +1,8 @@
 'use client';
 import { formatErrorBanner } from '@/lib/api/toast-error';
 
-import { useState, useEffect } from 'react';
+import { useState } from 'react';
+import { useQuery } from '@tanstack/react-query';
 import { Button } from '@/components/ui/button';
 import { Input } from '@/components/ui/input';
 import { Label } from '@/components/ui/label';
@@ -53,75 +54,49 @@ interface UserFormProps {
   onSuccess: () => void;
 }
 
-export function UserForm({ open, onOpenChange, user, onSuccess }: UserFormProps) {
-  const [roles, setRoles] = useState<Role[]>([]);
-  const [firstName, setFirstName] = useState('');
-  const [lastName, setLastName] = useState('');
-  const [email, setEmail] = useState('');
-  const [originalEmail, setOriginalEmail] = useState('');
+export function UserForm(props: UserFormProps) {
+  return (
+    <UserFormBody key={props.open ? `open:${props.user?.userId ?? 'new'}` : 'closed'} {...props} />
+  );
+}
+
+function UserFormBody({ open, onOpenChange, user, onSuccess }: UserFormProps) {
+  // Derive initial first/last names from the user payload.
+  const initialNames = (() => {
+    if (!user) return { first: '', last: '' };
+    if (user.firstName || user.lastName) {
+      return { first: user.firstName ?? '', last: user.lastName ?? '' };
+    }
+    const source = user.fullName ?? user.displayName;
+    const parts = source.split(/\s+/);
+    return { first: parts[0] ?? '', last: parts.slice(1).join(' ') };
+  })();
+  // useQuery replaces the prior useEffect(fetch+setRoles) pattern.
+  const rolesQuery = useQuery<{ data: Role[] }>({
+    queryKey: ['admin', 'roles'],
+    queryFn: () => apiFetch('/api/v1/admin/roles'),
+    enabled: open,
+  });
+  const roles = rolesQuery.data?.data ?? [];
+  const [firstName, setFirstName] = useState(initialNames.first);
+  const [lastName, setLastName] = useState(initialNames.last);
+  const [email, setEmail] = useState(user?.email ?? '');
+  const [originalEmail] = useState(user?.email ?? '');
   const [emailConfirmOpen, setEmailConfirmOpen] = useState(false);
   const [password, setPassword] = useState('');
-  const [displayName, setDisplayName] = useState('');
-  const [phoneValue, setPhoneValue] = useState<PhoneInputValue | null>(null);
-  const [roleId, setRoleId] = useState('');
-  const [isActive, setIsActive] = useState(true);
-  const [residentialAccess, setResidentialAccess] = useState(false);
+  const [displayName, setDisplayName] = useState(user?.displayName ?? '');
+  const [phoneValue, setPhoneValue] = useState<PhoneInputValue | null>(
+    user?.phone ? { e164: user.phone, country: 'US' } : null,
+  );
+  const [roleId, setRoleId] = useState(user?.role.id ?? '');
+  const [isActive, setIsActive] = useState(user?.isActive ?? true);
+  const [residentialAccess, setResidentialAccess] = useState(user?.residentialAccess ?? false);
   const [loading, setLoading] = useState(false);
   const [error, setError] = useState<string | null>(null);
 
   const isEdit = !!user;
   const fullName = `${firstName} ${lastName}`.trim();
 
-  useEffect(() => {
-    if (open) {
-      void apiFetch<{ data: Role[] }>('/api/v1/admin/roles').then((res) => setRoles(res.data));
-    }
-  }, [open]);
-
-  useEffect(() => {
-    if (open) {
-      if (user) {
-        // Prefer canonical first/last from the API; fall back to a best-
-        // effort split of displayName for older records that pre-date the
-        // first_name/last_name columns.
-        const first = user.firstName ?? '';
-        const last = user.lastName ?? '';
-        if (first || last) {
-          setFirstName(first);
-          setLastName(last);
-        } else if (user.fullName) {
-          const parts = user.fullName.split(/\s+/);
-          setFirstName(parts[0] ?? '');
-          setLastName(parts.slice(1).join(' '));
-        } else {
-          const parts = user.displayName.split(/\s+/);
-          setFirstName(parts[0] ?? '');
-          setLastName(parts.slice(1).join(' '));
-        }
-        setEmail(user.email);
-        setOriginalEmail(user.email);
-        setDisplayName(user.displayName);
-        setPhoneValue(user.phone ? { e164: user.phone, country: 'US' } : null);
-        setRoleId(user.role.id);
-        setIsActive(user.isActive);
-        setResidentialAccess(user.residentialAccess ?? false);
-        setPassword('');
-      } else {
-        setFirstName('');
-        setLastName('');
-        setEmail('');
-        setOriginalEmail('');
-        setDisplayName('');
-        setPhoneValue(null);
-        setRoleId('');
-        setIsActive(true);
-        setResidentialAccess(false);
-        setPassword('');
-      }
-      setError(null);
-    }
-  }, [open, user]);
-
   function handleSubmit(e: React.FormEvent) {
     e.preventDefault();
     // Admin email change for an existing user goes through a confirmation

src/components/admin/users/user-permission-matrix.tsx

@@ -12,6 +12,8 @@ import { Button } from '@/components/ui/button';
 import { Label } from '@/components/ui/label';
 import { ScrollArea } from '@/components/ui/scroll-area';
 import { apiFetch } from '@/lib/api/client';
+import { formatEnum } from '@/lib/constants';
+import { WarningCallout } from '@/components/ui/warning-callout';
 import { cn } from '@/lib/utils';
 
 /**
@@ -103,7 +105,7 @@ const PERMISSION_LEAVES: Record<string, string[]> = {
 };
 
 function formatAction(action: string): string {
-  return action.replace(/_/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
+  return formatEnum(action);
 }
 
 type Overrides = Record<string, Record<string, boolean>>;
@@ -223,13 +225,13 @@ export function UserPermissionMatrix({ userId }: UserPermissionMatrixProps) {
 
   return (
     <div className="space-y-3">
-      <div className="rounded-md border border-amber-200 bg-amber-50 px-3 py-2 text-xs text-amber-900">
-        <p>
+      <WarningCallout icon={false}>
+        <span className="text-xs">
           Permission overrides save <strong>on the button below</strong>, separately from the
-          Profile &amp; role tab. Switching tabs or closing the drawer without clicking
-          <strong> Save overrides</strong> drops your changes.
-        </p>
-      </div>
+          Profile &amp; role tab. Switching tabs or closing the drawer without clicking{' '}
+          <strong>Save overrides</strong> drops your changes.
+        </span>
+      </WarningCallout>
       <p className="text-xs text-muted-foreground">
         Each toggle defaults to <strong>Inherit</strong> (role + port override decide). Switch to
         <strong> Grant</strong> or <strong>Deny</strong> to force the value for this user only.

src/components/admin/vocabularies/vocabularies-manager.tsx

@@ -84,6 +84,8 @@ export function VocabulariesManager() {
   }, []);
 
   useEffect(() => {
+    // Initial vocabularies load on mount.
+    // eslint-disable-next-line react-hooks/set-state-in-effect
     void fetchAll();
   }, [fetchAll]);