@graph8/sdk 0.373.0 → 0.374.0

package/blocks/crm/components/contacts-screen.tsx

@@ -12,6 +12,11 @@
  * or many (confirm, "N of M" report, 404 = already gone) - import a CSV/Excel file - review and merge duplicates -
  * add notes and tasks - hand a contact to other blocks through the slot props.
  *
+ * Record actions: assign an owner to a whole list (only with renderOwnerPicker, never for a selection), tag chips on the open
+ * contact plus add/remove tags on a selection and a tag manager, edit one field on a selection, verify emails and unlock
+ * locked contacts (both billable, behind ConfirmSpendDialog with the count taken from the selection), AI documents and
+ * signals/next best step tabs on the open contact. Each action also works from the row's "..." button.
+ *
  * SDK operations: none of its own. listContacts, getContact, getActivityFeed, duplicateCounts are `read`;
  * the forms, notes and tasks are `write`; deleteContact (rows, detail and bulk) is `destructive` and always goes
  * through ConfirmSpendDialog. Nothing here sends a message to a person.
@@ -22,7 +27,7 @@
 import { useEffect, useMemo, useState } from "react";
 import type { ReactNode } from "react";
 import { Button, Skeleton, Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@graph8/sdk/ui";
-import { Building2, GitMerge, Lock, Plus, Trash2, Upload, Users } from "lucide-react";
+import { Building2, GitMerge, Lock, Plus, Tags, Trash2, Upload, Users } from "lucide-react";
 import { ApiError } from "@/g8/components/api-error";
 import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
 import { EmptyState } from "@/g8/components/empty-state";
@@ -52,7 +57,18 @@ import { ActivityTimeline } from "./activity-timeline";
 import { DedupeReview } from "./dedupe-review";
 import { ImportWizard } from "./import-wizard";
 import { NotesPanel } from "./notes-panel";
+import { OwnerAssignListButton } from "./owner-assign";
+import type { OwnerPickerProps } from "./owner-assign";
 import { RecordForm } from "./record-form";
+import { BulkUpdateButton } from "./bulk-update";
+import { ContactDocumentsTab } from "./contact-documents-tab";
+import { ContactInsightsTab } from "./contact-insights-tab";
+import { UnlockInfoButton } from "./unlock-info-button";
+import { VerifyEmailButton } from "./verify-email-button";
+import { ContactRowActions } from "./contact-row-actions";
+import { ContactTagChips } from "./contact-tag-chips";
+import { TagAssignButton } from "./tag-assign";
+import { TagManager } from "./tag-manager";
 import { TaskList } from "./task-list";
 
 export interface ContactsScreenProps {
@@ -69,6 +85,13 @@ export interface ContactsScreenProps {
   toolbarActions?: ReactNode;
   /** Extra bulk actions next to Delete (add to list, enrich, enroll...). */
   renderBulkActions?: (selection: { ids: number[]; rows: ContactRecord[]; clear: () => void }) => ReactNode;
+  /**
+   * Team-member picker for "Assign owner to all N in this list" (pass the pickers block's MemberPicker:
+   * `renderOwnerPicker={(p) => <MemberPicker label="New owner" {...p} />}`). Injected so crm does not depend on pickers.
+   * Without it the action is hidden. It is offered only when a list is in scope with no other filter, and never for a selection:
+   * the API assigns owners by filter, not by id.
+   */
+  renderOwnerPicker?: (props: OwnerPickerProps) => ReactNode;
   /** Called with a company id from the contact panel ("Open company"). Without it the button is hidden. */
   onOpenCompany?: (companyId: number) => void;
   className?: string;
@@ -85,6 +108,7 @@ function sortValue(row: ContactRecord, key: string): string | null | undefined {
   if (key === "title") return row.job_title;
   if (key === "company") return row.company_name;
   if (key === "location") return location(row);
+  if (key === "owner") return row.owner_name;
   return null;
 }
 
@@ -112,6 +136,7 @@ export function ContactsScreen(props: ContactsScreenProps) {
   const effectiveListId = listId ?? (filters.list ? Number(filters.list) : undefined);
   const [sheet, setSheet] = useState<"new" | "import" | "dupes" | null>(null);
   const [confirmDelete, setConfirmDelete] = useState(false);
+  const [tagManager, setTagManager] = useState(false);
   const [note, setNote] = useState<string | null>(null);
   const { sort, toggle: toggleSort } = useSort();
 
@@ -137,6 +162,8 @@ export function ContactsScreen(props: ContactsScreenProps) {
     void list.refetch();
     void dupes.refetch();
   });
+  /** The freshest copy of each selected row (a refetch after unlock or owner change replaces the stored one). */
+  const selectedRows = selection.ids.map((id) => list.rows.find((r) => r.id === id) ?? selection.selected.get(id)!).filter(Boolean);
   const allOnPage = rows.length > 0 && rows.every((r) => selection.selected.has(r.id));
   const reload = () => { void list.refetch(); void dupes.refetch(); };
   const set = (key: FilterKey, v: string) => urlFilters.set(key, v);
@@ -152,6 +179,8 @@ export function ContactsScreen(props: ContactsScreenProps) {
       actions={
         <>
           {props.toolbarActions}
+          {effectiveListId != null && Object.keys(apiFilters).length === 0 && props.renderOwnerPicker ? <OwnerAssignListButton renderPicker={props.renderOwnerPicker} listId={effectiveListId} total={list.loading ? null : list.total} onDone={reload} /> : null}
+          <Button variant="outline" size="sm" onClick={() => setTagManager(true)}><Tags className="size-4" aria-hidden />Manage tags</Button>
           <Button variant="outline" size="sm" onClick={() => setSheet("dupes")}><GitMerge className="size-4" aria-hidden />Duplicates{pending ? ` (${pending})` : ""}</Button>
           <Button variant="outline" size="sm" onClick={() => setSheet("import")}><Upload className="size-4" aria-hidden />Import</Button>
           <Button size="sm" onClick={() => setSheet("new")}><Plus className="size-4" aria-hidden />New contact</Button>
@@ -200,6 +229,10 @@ export function ContactsScreen(props: ContactsScreenProps) {
               <div className="flex flex-wrap items-center gap-2 rounded-md border bg-muted/40 px-3 py-2 text-sm" role="status">
                 <span className="tabular-nums">{selection.ids.length} selected</span>
                 {props.renderBulkActions?.({ ids: selection.ids, rows: selection.rows, clear: selection.clear })}
+                <TagAssignButton contactIds={selection.ids} onDone={reload} />
+                <BulkUpdateButton contactIds={selection.ids} onDone={reload} />
+                <VerifyEmailButton rows={selectedRows} onDone={reload} />
+                <UnlockInfoButton rows={selectedRows} onDone={reload} />
                 <Button variant="destructive" size="sm" onClick={() => setConfirmDelete(true)}><Trash2 className="size-4" aria-hidden />Delete {selection.ids.length}</Button>
                 <Button variant="ghost" size="sm" onClick={selection.clear}>Clear selection</Button>
               </div>
@@ -217,12 +250,13 @@ export function ContactsScreen(props: ContactsScreenProps) {
                     <SortHead label="Company" sortKey="company" sort={sort} onSort={toggleSort} />
                     <TableHead>Email</TableHead>
                     <SortHead label="Location" sortKey="location" sort={sort} onSort={toggleSort} />
-                    {props.renderRowActions ? <TableHead className="w-8"><span className="sr-only">Actions</span></TableHead> : null}
+                    <SortHead label="Owner" sortKey="owner" sort={sort} onSort={toggleSort} />
+                    <TableHead className="w-8"><span className="sr-only">Actions</span></TableHead>
                   </TableRow>
                 </TableHeader>
                 <TableBody>
                   {list.loading && rows.length === 0
-                    ? Array.from({ length: 6 }, (_, i) => <TableRow key={`sk${i}`}><TableCell colSpan={6 + (props.renderRowActions ? 1 : 0)}><Skeleton className="h-6 w-full" /></TableCell></TableRow>)
+                    ? Array.from({ length: 6 }, (_, i) => <TableRow key={`sk${i}`}><TableCell colSpan={8}><Skeleton className="h-6 w-full" /></TableCell></TableRow>)
                     : rows.map((row) => {
                         const name = contactName(row);
                         return (
@@ -237,7 +271,10 @@ export function ContactsScreen(props: ContactsScreenProps) {
                             <TableCell><Cell value={row.company_name} /></TableCell>
                             <TableCell><Cell value={row.work_email} /></TableCell>
                             <TableCell><Cell value={location(row)} /></TableCell>
-                            {props.renderRowActions ? <TableCell onClick={(e) => e.stopPropagation()}>{props.renderRowActions(row, { reload })}</TableCell> : null}
+                            <TableCell><Cell value={row.owner_name} /></TableCell>
+                            <TableCell onClick={(e) => e.stopPropagation()}>
+                              <span className="flex items-center gap-1">{props.renderRowActions?.(row, { reload })}<ContactRowActions row={row} onDone={reload} /></span>
+                            </TableCell>
                           </TableRow>
                         );
                       })}
@@ -273,6 +310,7 @@ export function ContactsScreen(props: ContactsScreenProps) {
         <DedupeReview entity="contact" onChanged={reload} />
       </FormSheet>
 
+      <TagManager open={tagManager} onOpenChange={setTagManager} onChanged={reload} />
       <ConfirmSpendDialog
         open={confirmDelete}
         tier="destructive"
@@ -352,6 +390,7 @@ function ContactPanel({ full, setFull, contactId, seed, onClose, onChanged, onDe
         onCollapse={full ? () => setFull(false) : undefined}
         actions={
           <>
+            {partial ? null : <><VerifyEmailButton rows={[contact]} onDone={() => { void query.refetch(); onChanged(); }} /><UnlockInfoButton rows={[contact]} onDone={() => { void query.refetch(); onChanged(); }} /></>}
             {partial ? null : renderActions?.(contact, { reload: () => { void query.refetch(); bump(); onChanged(); } })}
             {contact.company?.id && onOpenCompany ? <Button variant="outline" size="sm" onClick={() => onOpenCompany(contact.company!.id as number)}><Building2 className="size-4" aria-hidden />Open company</Button> : null}
             <Button variant="outline" size="sm" disabled={partial} title={partial ? "Loading the full record" : undefined} onClick={() => setEditing(true)}>Edit</Button>
@@ -359,10 +398,12 @@ function ContactPanel({ full, setFull, contactId, seed, onClose, onChanged, onDe
           </>
         }
         tabs={[
-          { id: "overview", label: "Overview", content: overview },
+          { id: "overview", label: "Overview", content: <div className="flex flex-col gap-4"><ContactTagChips contactId={contactId} onChanged={onChanged} />{overview}</div> },
           { id: "activity", label: "Activity", content: <ActivityTimeline entityType="contact" entityId={contactId} refreshKey={feedKey} /> },
           { id: "notes", label: "Notes", content: <NotesPanel entity="contact" entityId={contactId} onChanged={bump} /> },
           { id: "tasks", label: "Tasks", content: <TaskList entity="contact" entityId={contactId} onChanged={bump} /> },
+          { id: "documents", label: "AI documents", content: <ContactDocumentsTab contactId={contactId} contactName={name} /> },
+          { id: "insights", label: "Insights", content: <ContactInsightsTab contactId={contactId} /> },
           ...(partial ? [] : extraTabs).map((t) => ({ id: t.id, label: t.label, content: t.render(contact) })),
         ]}
       />

package/blocks/crm/components/owner-assign.tsx

@@ -0,0 +1,132 @@
+"use client";
+
+/**
+ * OwnerAssignListButton: "Assign owner to all N contacts in this list". The ONLY owner action, and deliberately not a
+ * selection action.
+ *
+ * Why not for a selection: `POST /contacts/assign-owner` takes a FILTER (`list_id` + `filterModel`), not ids, and resolves
+ * it server-side across EVERY matching contact; its docstring warns the count is unbounded. Addressing a selection through
+ * an id filter would reassign the whole list or org if the key were ever ignored or renamed, so selections, rows and the
+ * open contact do not get an owner action here. There is no id-addressed owner write in the contract (bulk-update and
+ * PATCH take no owner), so that is an API gap: assign-owner needs an `ids` field.
+ *
+ * SDK operations, in order:
+ *   1. listTeamMembers    GET /team-members                 via the injected picker (read, fetched when the picker opens)
+ *   2. assignContactOwner POST /contacts/assign-owner { owner_id, list_id, filterModel: {} }   (write)
+ *        Scope = the whole list, nothing else. N comes from the list's own count (the screen's total with no other filter
+ *        applied), is shown in the confirm, and the button is disabled until that count has loaded. `owner_id: null`
+ *        clears every owner in the list. Both paths go through ConfirmSpendDialog and name the list and N.
+ */
+
+import { useState } from "react";
+import type { ReactNode } from "react";
+import { Button, Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle } from "@graph8/sdk/ui";
+import { UserCog } from "lucide-react";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { g8Post } from "@/g8/lib/g8-client";
+import { plural } from "@/g8/lib/plural";
+
+/** A team member, as the injected picker reports it: the user id the API takes, and a name for the confirm. */
+export interface OwnerChoice { id: string; name: string }
+
+export interface OwnerPickerProps {
+  value: string | null;
+  onChange: (member: OwnerChoice) => void;
+}
+
+export interface OwnerAssignListButtonProps {
+  /**
+   * Renders the team-member picker (the pickers block's MemberPicker: `renderPicker={(p) => <MemberPicker label="New owner" {...p} />}`).
+   * It is injected so crm does not depend on pickers. Without it the button renders nothing: an owner is never typed as a raw id.
+   */
+  renderPicker?: (props: OwnerPickerProps) => ReactNode;
+  listId: number;
+  /** Shown in the confirm: "Q4 target accounts". Falls back to "list <id>". */
+  listName?: string | null;
+  /** The number of contacts in the list, from a real read. Null while it loads: the button stays disabled. */
+  total: number | null;
+  onDone?: (result: { updated: number | null; ownerId: string | null }) => void;
+  variant?: "default" | "outline" | "secondary" | "ghost";
+  size?: "default" | "sm";
+  className?: string;
+}
+
+/** `updated` from the answer: `{ updated }`, `{ data: { updated } }`; null when the API did not say. */
+export function updatedCount(data: unknown): number | null {
+  const o = data as { updated?: unknown; data?: { updated?: unknown } } | null | undefined;
+  const n = o?.updated ?? o?.data?.updated;
+  return typeof n === "number" ? n : null;
+}
+
+export function OwnerAssignListButton({ renderPicker, listId, listName, total, onDone, variant = "outline", size = "sm", className }: OwnerAssignListButtonProps) {
+  const [open, setOpen] = useState(false);
+  const [member, setMember] = useState<OwnerChoice | null>(null);
+  const [pending, setPending] = useState<"assign" | "remove" | null>(null);
+  const [done, setDone] = useState<{ updated: number | null; total: number; removed: boolean } | null>(null);
+  const label = listName?.trim() || `list ${listId}`;
+  const n = total ?? 0;
+
+  const run = useG8Mutation(async (v: { ownerId: string | null; total: number }) => {
+    const res = await g8Post<unknown>("/contacts/assign-owner", { owner_id: v.ownerId, list_id: listId, filterModel: {} });
+    return { updated: updatedCount(res.data), ownerId: v.ownerId, total: v.total };
+  }, {
+    invalidates: [["contacts", "list"], ["contacts", "detail"], ["contacts", "record"]],
+    onSuccess: (r) => { setPending(null); setDone({ updated: r.updated, total: r.total, removed: r.ownerId == null }); onDone?.({ updated: r.updated, ownerId: r.ownerId }); },
+  });
+
+  const close = () => { setOpen(false); setMember(null); setDone(null); setPending(null); run.reset(); };
+  const short = done && done.updated != null && done.updated !== done.total;
+  const ready = total != null && total > 0;
+  if (!renderPicker) return null;
+
+  return (
+    <>
+      <Button className={className} variant={variant} size={size} disabled={!ready} title={total == null ? "Loading the list size" : total === 0 ? "This list has no contacts" : undefined} onClick={() => setOpen(true)}>
+        <UserCog className="size-4" aria-hidden />Assign owner to all{total != null ? ` ${total.toLocaleString()}` : ""}
+      </Button>
+      <Dialog open={open} onOpenChange={(o) => (o ? setOpen(true) : close())}>
+        <DialogContent>
+          <DialogHeader>
+            <DialogTitle>Assign an owner to the whole list</DialogTitle>
+            <DialogDescription>This changes every contact in {label}, {plural(n, "contact")}. It does not use your selection.</DialogDescription>
+          </DialogHeader>
+          {done ? (
+            <div role="status" className="text-sm">
+              <p className="font-medium">{done.updated == null ? "Done." : `${done.removed ? "Removed the owner from" : "Assigned the owner to"} ${plural(done.updated, "contact")}.`}</p>
+              {short ? <p className="mt-1 text-destructive">The list had {done.total.toLocaleString()} contacts, but the server updated {done.updated!.toLocaleString()}.</p> : null}
+            </div>
+          ) : (
+            <>
+              {renderPicker?.({ value: member?.id ?? null, onChange: (m) => { setMember({ id: m.id, name: m.name }); run.reset(); } })}
+              {run.error && !pending ? <ApiError error={run.error} title="Could not change the owner" /> : null}
+            </>
+          )}
+          <DialogFooter>
+            {done ? <Button onClick={close}>Done</Button> : (
+              <>
+                <Button variant="ghost" onClick={close}>Cancel</Button>
+                <Button variant="outline" disabled={run.loading} onClick={() => setPending("remove")}>Remove all owners</Button>
+                <Button disabled={!member || run.loading} onClick={() => setPending("assign")}>Assign owner</Button>
+              </>
+            )}
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+      <ConfirmSpendDialog
+        open={pending != null}
+        tier="destructive"
+        title={pending === "remove" ? `Remove the owner from all ${plural(n, "contact")} in ${label}` : `Make ${member?.name ?? "this person"} the owner of all ${plural(n, "contact")} in ${label}`}
+        description={pending === "remove"
+          ? "Every contact in the list will have no owner. The previous owners are not remembered, so this cannot be undone from here."
+          : "Every contact in the list gets this owner, replacing whoever owns it now. The previous owners are not remembered."}
+        affected={n}
+        confirmLabel={pending === "remove" ? "Remove owners" : "Assign owner"}
+        confirming={run.loading}
+        onConfirm={() => void run.mutate({ ownerId: pending === "remove" ? null : member?.id ?? null, total: n })}
+        onCancel={() => setPending(null)}
+      />
+    </>
+  );
+}

package/blocks/crm/components/record-open-links.tsx

@@ -0,0 +1,79 @@
+"use client";
+
+/**
+ * RecordOpenLinks: "Open contact" and "Open company" buttons for something that only knows ids (a call log entry, a
+ * website visitor). The ids are CHECKED against your CRM first, so a button is only shown for a record that exists
+ * and, when you pass `expectCompanyDomain`, for a company whose domain matches (event ids and CRM ids are not always
+ * the same id space). A record that cannot be loaded renders nothing, never a link to the wrong or a missing page.
+ *
+ * SDK operations, in order:
+ *   1. getContact  GET /contacts/{contact_id}   (read; only with a numeric `contactId`)
+ *   2. getCompany  GET /companies/{company_id}  (read; only with a `companyId` that the contact did not already give)
+ * Nothing here is billable, external or destructive.
+ */
+
+import { Button } from "@graph8/sdk/ui";
+import { Building2, UserRound } from "lucide-react";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Get } from "@/g8/lib/g8-client";
+import type { ContactRecord } from "../lib/crm-types";
+
+export interface RecordOpenLinksProps {
+  /** A CRM contact id (number or numeric string). Anything else is ignored. */
+  contactId?: number | string | null;
+  /** A CRM company id. Optional: a contact that has a company supplies it. */
+  companyId?: number | string | null;
+  /** When set, a company is linked only if its domain equals this (case-insensitive). */
+  expectCompanyDomain?: string | null;
+  /** When set, the contact is linked only if its name equals this (case-insensitive, extra spaces ignored). */
+  expectContactName?: string | null;
+  onOpenContact?: (contactId: number) => void;
+  onOpenCompany?: (companyId: number) => void;
+  size?: "default" | "sm";
+}
+
+const idOf = (v: number | string | null | undefined): number | null => {
+  const s = String(v ?? "").trim();
+  return /^\d+$/.test(s) ? Number(s) : null;
+};
+const nameKey = (n: string | null | undefined): string => (n ?? "").trim().toLowerCase().split(/\s+/).filter(Boolean).join(" ");
+const domainOf = (d: string | null | undefined): string => (d ?? "").trim().toLowerCase().replace(/^www\./, "");
+
+export function RecordOpenLinks({ contactId, companyId, expectCompanyDomain, expectContactName, onOpenContact, onOpenCompany, size = "sm" }: RecordOpenLinksProps) {
+  const cid = idOf(contactId);
+  const contact = useG8Query(
+    async (signal) => (await g8Get<ContactRecord>(`/contacts/${cid}`, undefined, { signal })).data ?? null,
+    [cid],
+    { enabled: cid != null && Boolean(onOpenContact || onOpenCompany), key: ["contacts", "open-links", cid] },
+  );
+  const c = contact.data;
+  // A contact whose name is not the expected one is some other person that happens to share the id: link nothing from it.
+  const contactOk = Boolean(c) && (!expectContactName || nameKey(expectContactName) === nameKey(c?.full_name || [c?.first_name, c?.last_name].filter(Boolean).join(" ")));
+  const fromContact = c && contactOk ? idOf(c.company_id ?? c.company?.id) : null;
+  const ownCompany = idOf(companyId);
+  const coId = fromContact ?? ownCompany;
+  // A company id that came from the caller (not from the contact) is verified by loading it.
+  const needsCheck = fromContact == null && ownCompany != null && Boolean(onOpenCompany);
+  const company = useG8Query(
+    async (signal) => (await g8Get<{ id?: number; domain?: string | null }>(`/companies/${ownCompany}`, undefined, { signal })).data ?? null,
+    [ownCompany],
+    { enabled: needsCheck && (cid == null || contact.data !== undefined || Boolean(contact.error)), key: ["companies", "open-links", ownCompany] },
+  );
+  const companyOk = fromContact != null || (needsCheck && company.data != null && (!expectCompanyDomain || domainOf(company.data.domain) === domainOf(expectCompanyDomain)));
+  return (
+    <>
+      {onOpenContact && contactOk && cid != null ? (
+        <Button size={size} variant="outline" onClick={() => onOpenContact(cid)}>
+          <UserRound className="mr-1 size-4" aria-hidden />
+          Open contact
+        </Button>
+      ) : null}
+      {onOpenCompany && coId != null && companyOk ? (
+        <Button size={size} variant="outline" onClick={() => onOpenCompany(coId)}>
+          <Building2 className="mr-1 size-4" aria-hidden />
+          Open company
+        </Button>
+      ) : null}
+    </>
+  );
+}

package/blocks/crm/components/tag-assign.tsx

@@ -0,0 +1,112 @@
+"use client";
+
+/**
+ * TagAssignButton: add tags to, or remove tags from, a selection of contacts. A dialog lists the org's tags as checkboxes;
+ * the person picks the tags and whether to add or remove them.
+ *
+ * SDK operations, in order:
+ *   1. listContactTags     GET /contacts/tags                                         (read, via useContactTags, when opened)
+ *   2. assignContactTags   POST /contacts/tags/assign   { tag_ids, contact_ids }     (write, idempotent)
+ *   3. unassignContactTags POST /contacts/tags/unassign { tag_ids, contact_ids }     (write; tag definitions survive)
+ *
+ * One request for the whole selection (the API takes up to 200,000 contacts). The answer's `tagged` / `untagged` count is
+ * the number of contacts that changed; contacts that already had the tag are not counted, and the dialog says so.
+ */
+
+import { useState } from "react";
+import { Button, Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle } from "@graph8/sdk/ui";
+import { Tags } from "lucide-react";
+import { ApiError } from "@/g8/components/api-error";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { g8Post } from "@/g8/lib/g8-client";
+import { plural } from "@/g8/lib/plural";
+import { useContactTags } from "../hooks/use-contact-tags";
+import { TagChip } from "./contact-tag-chips";
+
+export interface TagAssignButtonProps {
+  contactIds: ReadonlyArray<number>;
+  onDone?: (result: { changed: number | null; mode: "add" | "remove" }) => void;
+  label?: string;
+  variant?: "default" | "outline" | "secondary" | "ghost";
+  size?: "default" | "sm";
+  className?: string;
+  defaultOpen?: boolean;
+  onClosed?: () => void;
+}
+
+type Mode = "add" | "remove";
+
+export function TagAssignButton({ contactIds, onDone, label = "Tags", variant = "outline", size = "sm", className, defaultOpen = false, onClosed }: TagAssignButtonProps) {
+  const [open, setOpen] = useState(defaultOpen);
+  const [mode, setMode] = useState<Mode>("add");
+  const [picked, setPicked] = useState<ReadonlySet<string>>(new Set());
+  const [done, setDone] = useState<{ changed: number | null; mode: Mode; total: number } | null>(null);
+  const tags = useContactTags({ enabled: open });
+
+  const apply = useG8Mutation(async (v: { mode: Mode; tagIds: string[]; ids: number[] }) => {
+    const body = { tag_ids: v.tagIds, contact_ids: v.ids };
+    const res = v.mode === "add" ? await g8Post<Record<string, unknown>>("/contacts/tags/assign", body) : await g8Post<Record<string, unknown>>("/contacts/tags/unassign", body);
+    const n = res.data?.[v.mode === "add" ? "tagged" : "untagged"];
+    return { changed: typeof n === "number" ? n : null, mode: v.mode, total: v.ids.length };
+  }, {
+    invalidates: [["contact-tags"], ["contacts", "tags"], ["contacts", "list"]],
+    onSuccess: (r) => { setDone(r); onDone?.({ changed: r.changed, mode: r.mode }); },
+  });
+
+  const close = () => { setOpen(false); setPicked(new Set()); setDone(null); apply.reset(); onClosed?.(); };
+  const toggle = (id: string) => setPicked((s) => { const n = new Set(s); if (!n.delete(id)) n.add(id); return n; });
+  const count = contactIds.length;
+
+  return (
+    <>
+      {defaultOpen ? null : <Button className={className} variant={variant} size={size} disabled={count === 0} onClick={() => setOpen(true)}><Tags className="size-4" aria-hidden />{label}</Button>}
+      <Dialog open={open} onOpenChange={(o) => (o ? setOpen(true) : close())}>
+        <DialogContent>
+          <DialogHeader>
+            <DialogTitle>Tag {plural(count, "contact")}</DialogTitle>
+            <DialogDescription>Tags group contacts outside lists. Adding a tag a contact already has changes nothing.</DialogDescription>
+          </DialogHeader>
+          {done ? (
+            <p role="status" className="text-sm font-medium">
+              {done.changed == null ? "Done." : done.mode === "add" ? `Tagged ${plural(done.changed, "contact")}.` : `Removed the tags from ${plural(done.changed, "contact")}.`}
+              {done.changed != null && done.changed < done.total ? <span className="block font-normal text-muted-foreground">{(done.total - done.changed).toLocaleString()} already matched and did not change.</span> : null}
+            </p>
+          ) : (
+            <>
+              <div role="radiogroup" aria-label="Action" className="flex gap-2">
+                {(["add", "remove"] as const).map((m) => (
+                  <Button key={m} role="radio" aria-checked={mode === m} variant={mode === m ? "default" : "outline"} size="sm" onClick={() => { setMode(m); apply.reset(); }}>{m === "add" ? "Add tags" : "Remove tags"}</Button>
+                ))}
+              </div>
+              {tags.error ? <ApiError error={tags.error} title="Could not load tags" onRetry={() => void tags.refetch()} /> : null}
+              {tags.loading ? <p className="text-sm text-muted-foreground" role="status">Loading tags</p> : null}
+              {!tags.loading && !tags.error && tags.tags.length === 0 ? <p className="text-sm text-muted-foreground">No tags yet. Create one in Manage tags.</p> : null}
+              <ul className="flex max-h-64 flex-col gap-1 overflow-y-auto">
+                {tags.tags.map((t) => (
+                  <li key={t.id}>
+                    <label className="flex cursor-pointer items-center gap-2 rounded-md px-2 py-1 hover:bg-muted">
+                      <input type="checkbox" checked={picked.has(t.id)} onChange={() => toggle(t.id)} aria-label={t.name} />
+                      <TagChip tag={t} />
+                      {t.contact_count != null ? <span className="ml-auto text-xs tabular-nums text-muted-foreground">{t.contact_count.toLocaleString()}</span> : null}
+                    </label>
+                  </li>
+                ))}
+              </ul>
+              {apply.error ? <ApiError error={apply.error} title="Could not change the tags" /> : null}
+            </>
+          )}
+          <DialogFooter>
+            {done ? <Button onClick={close}>Done</Button> : (
+              <>
+                <Button variant="ghost" onClick={close}>Cancel</Button>
+                <Button loading={apply.loading} disabled={picked.size === 0 || count === 0} onClick={() => void apply.mutate({ mode, tagIds: [...picked], ids: [...contactIds] })}>
+                  {mode === "add" ? `Add ${plural(picked.size, "tag")}` : `Remove ${plural(picked.size, "tag")}`}
+                </Button>
+              </>
+            )}
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+    </>
+  );
+}