feat(client-archive): smart-restore wizard with auto/opt-in/locked sections

Replaces the simple confirm-restore dialog with a wizard that reads the
persisted archive_metadata via /restore-dossier and surfaces:
- auto-reversed (e.g. berth still available → re-attached on restore)
- opt-in to undo (e.g. berth now under offer to another client)
- locked (e.g. yacht transferred and new owner has active interests)

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

src/components/clients/client-detail-header.tsx

@@ -1,19 +1,20 @@
 'use client';
 
+import { useRouter } from 'next/navigation';
 import { useState } from 'react';
-import { useMutation, useQueryClient } from '@tanstack/react-query';
-import { Archive, Mail, MessageCircle, Phone, RotateCcw } from 'lucide-react';
+import { Archive, Mail, MessageCircle, Phone, RotateCcw, Trash2 } from 'lucide-react';
 import { format } from 'date-fns';
 
 import { Button } from '@/components/ui/button';
 import { Badge } from '@/components/ui/badge';
 import { TagBadge } from '@/components/shared/tag-badge';
-import { ArchiveConfirmDialog } from '@/components/shared/archive-confirm-dialog';
+import { PermissionGate } from '@/components/shared/permission-gate';
 import { SmartArchiveDialog } from '@/components/clients/smart-archive-dialog';
+import { SmartRestoreDialog } from '@/components/clients/smart-restore-dialog';
+import { HardDeleteDialog } from '@/components/clients/hard-delete-dialog';
 import { DetailHeaderStrip } from '@/components/shared/detail-header-strip';
 import { PortalInviteButton } from '@/components/clients/portal-invite-button';
 import { GdprExportButton } from '@/components/clients/gdpr-export-button';
-import { apiFetch } from '@/lib/api/client';
 import { cn } from '@/lib/utils';
 import { getCountryName } from '@/lib/i18n/countries';
 
@@ -37,20 +38,12 @@ interface ClientDetailHeaderProps {
 }
 
 export function ClientDetailHeader({ client }: ClientDetailHeaderProps) {
-  const queryClient = useQueryClient();
+  const router = useRouter();
   const [archiveOpen, setArchiveOpen] = useState(false);
+  const [hardDeleteOpen, setHardDeleteOpen] = useState(false);
 
   const isArchived = !!client.archivedAt;
 
-  const restoreMutation = useMutation({
-    mutationFn: () => apiFetch(`/api/v1/clients/${client.id}/restore`, { method: 'POST' }),
-    onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: ['clients', client.id] });
-      queryClient.invalidateQueries({ queryKey: ['clients'] });
-      setArchiveOpen(false);
-    },
-  });
-
   const primaryEmail =
     client.contacts?.find((c) => c.channel === 'email' && c.isPrimary)?.value ??
     client.contacts?.find((c) => c.channel === 'email')?.value;
@@ -161,36 +154,46 @@ export function ClientDetailHeader({ client }: ClientDetailHeaderProps) {
             )}
           </div>
 
-          {/* Top-right: archive/restore as a small icon button - destructive
-              action sits out of the primary action flow. */}
-          <button
-            type="button"
-            onClick={() => setArchiveOpen(true)}
-            aria-label={isArchived ? 'Restore client' : 'Archive client'}
-            title={isArchived ? 'Restore client' : 'Archive client'}
-            className={cn(
-              'shrink-0 rounded-md p-1.5 text-muted-foreground/70 transition-colors',
-              'hover:bg-foreground/5 hover:text-foreground',
-              isArchived ? 'hover:text-foreground' : 'hover:text-destructive',
+          {/* Top-right: archive/restore + (for archived clients with the
+              right perm) permanently-delete. Destructive actions sit out
+              of the primary action flow. */}
+          <div className="flex items-start gap-1">
+            {isArchived && (
+              <PermissionGate resource="admin" action="permanently_delete_clients">
+                <button
+                  type="button"
+                  onClick={() => setHardDeleteOpen(true)}
+                  aria-label="Permanently delete client"
+                  title="Permanently delete client"
+                  className="shrink-0 rounded-md p-1.5 text-muted-foreground/70 transition-colors hover:bg-destructive/10 hover:text-destructive"
+                >
+                  <Trash2 className="size-4" />
+                </button>
+              </PermissionGate>
             )}
-          >
-            {isArchived ? <RotateCcw className="size-4" /> : <Archive className="size-4" />}
-          </button>
+            <button
+              type="button"
+              onClick={() => setArchiveOpen(true)}
+              aria-label={isArchived ? 'Restore client' : 'Archive client'}
+              title={isArchived ? 'Restore client' : 'Archive client'}
+              className={cn(
+                'shrink-0 rounded-md p-1.5 text-muted-foreground/70 transition-colors',
+                'hover:bg-foreground/5 hover:text-foreground',
+                isArchived ? 'hover:text-foreground' : 'hover:text-destructive',
+              )}
+            >
+              {isArchived ? <RotateCcw className="size-4" /> : <Archive className="size-4" />}
+            </button>
+          </div>
         </div>
       </DetailHeaderStrip>
 
-      {/* Restore flow keeps the simple confirm dialog (the smart restore
-          wizard ships in a follow-on commit). Archive uses the new smart
-          dialog with the dossier + per-section decisions. */}
       {isArchived ? (
-        <ArchiveConfirmDialog
+        <SmartRestoreDialog
           open={archiveOpen}
           onOpenChange={setArchiveOpen}
-          entityName={client.fullName}
-          entityType="Client"
-          isArchived
-          onConfirm={() => restoreMutation.mutate()}
-          isLoading={restoreMutation.isPending}
+          clientId={client.id}
+          clientName={client.fullName}
         />
       ) : (
         <SmartArchiveDialog
@@ -200,6 +203,16 @@ export function ClientDetailHeader({ client }: ClientDetailHeaderProps) {
           clientName={client.fullName}
         />
       )}
+
+      {isArchived && (
+        <HardDeleteDialog
+          open={hardDeleteOpen}
+          onOpenChange={setHardDeleteOpen}
+          clientId={client.id}
+          clientName={client.fullName}
+          onDeleted={() => router.back()}
+        />
+      )}
     </>
   );
 }