@graph8/sdk 0.362.0 → 0.373.0

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

@@ -0,0 +1,377 @@
+"use client";
+
+/**
+ * ContactsScreen: the finished contacts workspace. A searchable, filterable, sortable, paginated grid on the left;
+ * the open contact (timeline, notes, tasks, fields) beside it. No props are required.
+ *
+ * Composes: ScreenLayout, StatStrip, Toolbar, SplitView, DetailPanel, FormSheet (screen kit) with RecordForm,
+ * ActivityTimeline, NotesPanel, TaskList, ImportWizard and DedupeReview (this block).
+ *
+ * Flows: search and filter (name, title, seniority, country; debounced, latest request wins) - sort the loaded
+ * page - paginate - open a contact (deep link ?id=, full page with &view=full) - create a contact (a 409 opens the existing one) - edit - delete one
+ * 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.
+ *
+ * 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.
+ *
+ * Locked (masked) emails and phones show as Locked: save the contact to a list or enrich it to reveal them.
+ */
+
+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 { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { EmptyState } from "@/g8/components/empty-state";
+import { DetailPanel } from "@/g8/components/screen/detail-panel";
+import { EntityAvatar } from "@/g8/components/screen/entity-avatar";
+import { FormSheet } from "@/g8/components/screen/form-sheet";
+import { KeyValueList } from "@/g8/components/screen/key-value-list";
+import { ScreenLayout } from "@/g8/components/screen/screen-layout";
+import { SplitView } from "@/g8/components/screen/split-view";
+import { StatusPill } from "@/g8/components/screen/status-pill";
+import { Toolbar } from "@/g8/components/screen/toolbar";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { rowActivationProps } from "@/g8/hooks/use-row-activation";
+import { RecordLink } from "@/g8/components/screen/record-link";
+import { plural } from "@/g8/lib/plural";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { useUrlState } from "@/g8/hooks/use-url-state";
+import { useUrlFilters } from "@/g8/hooks/use-url-filters";
+import { ListSelect } from "./list-select";
+import { MoreFilters, TextFilter } from "@/g8/components/screen/filter-controls";
+import { g8Delete, g8Get } from "@/g8/lib/g8-client";
+import { usePageQuery } from "../hooks/use-page-query";
+import { contactName, contactSubtitle, errorStatus, isMasked, location } from "../lib/crm-types";
+import type { ContactRecord, ScreenActionContext } from "../lib/crm-types";
+import { Pager, SortHead, formatDay, sortRows, useBulkDelete, useRowSelection, useSort } from "../lib/screen-parts";
+import { ActivityTimeline } from "./activity-timeline";
+import { DedupeReview } from "./dedupe-review";
+import { ImportWizard } from "./import-wizard";
+import { NotesPanel } from "./notes-panel";
+import { RecordForm } from "./record-form";
+import { TaskList } from "./task-list";
+
+export interface ContactsScreenProps {
+  /** Only members of this list. */
+  listId?: number;
+  pageSize?: number;
+  /** Buttons at the end of each row (enrich, add to list...). */
+  renderRowActions?: (row: ContactRecord, ctx: ScreenActionContext) => ReactNode;
+  /** Buttons in the open contact's header. */
+  renderDetailActions?: (contact: ContactRecord, ctx: ScreenActionContext) => ReactNode;
+  /** Extra tabs on the open contact. */
+  extraDetailTabs?: Array<{ id: string; label: string; render: (contact: ContactRecord) => ReactNode }>;
+  /** Extra buttons in the page header, before "New contact". */
+  toolbarActions?: ReactNode;
+  /** Extra bulk actions next to Delete (add to list, enrich, enroll...). */
+  renderBulkActions?: (selection: { ids: number[]; rows: ContactRecord[]; clear: () => void }) => ReactNode;
+  /** Called with a company id from the contact panel ("Open company"). Without it the button is hidden. */
+  onOpenCompany?: (companyId: number) => void;
+  className?: string;
+}
+
+/** Every filter the contacts API takes (name, email, job title, seniority, company name and id, country, state, city, department, industry), plus `list`. */
+const FILTER_KEYS = ["name", "job_title", "seniority_level", "country", "email", "company_name", "company_id", "state", "city", "job_department", "industry", "list"] as const;
+type FilterKey = (typeof FILTER_KEYS)[number];
+const MORE_KEYS: readonly FilterKey[] = ["email", "company_name", "company_id", "state", "city", "job_department", "industry", "list"];
+const SENIORITY = ["C-Suite", "VP", "Director", "Manager"];
+
+function sortValue(row: ContactRecord, key: string): string | null | undefined {
+  if (key === "name") return contactName(row);
+  if (key === "title") return row.job_title;
+  if (key === "company") return row.company_name;
+  if (key === "location") return location(row);
+  return null;
+}
+
+function Locked() {
+  return <span className="inline-flex items-center gap-1 italic text-muted-foreground" title="Locked: save to a list or enrich to reveal"><Lock className="size-3" aria-hidden />Locked</span>;
+}
+function Cell({ value }: { value?: string | null }) {
+  return isMasked(value) ? <Locked /> : <>{value || <span className="text-muted-foreground">-</span>}</>;
+}
+
+export function ContactsScreen(props: ContactsScreenProps) {
+  const { listId, pageSize = 25 } = props;
+  const [idParam, setIdParamRaw] = useUrlState("id");
+  const [view, setView] = useUrlState("view");
+  const full = view === "full" && idParam != null && idParam !== "";
+  /** Changing or clearing the open record also leaves the full-page view. */
+  const setIdParam = (v: string | null): void => { if (v == null) setView(null); setIdParamRaw(v); };
+  const parsedId = idParam ? Number(idParam) : null;
+  /** A malformed deep link (`?id=abc`) opens nothing instead of fetching /contacts/NaN. */
+  const openId = parsedId != null && Number.isFinite(parsedId) ? parsedId : null;
+  // The filters live in the URL (`c_email=...`), so a filtered view survives reload, Back and sharing.
+  const urlFilters = useUrlFilters(FILTER_KEYS, { prefix: "c_" });
+  const { draft, filters } = urlFilters;
+  const apiFilters = Object.fromEntries(Object.entries(filters).filter(([k, v]) => v && k !== "list"));
+  const effectiveListId = listId ?? (filters.list ? Number(filters.list) : undefined);
+  const [sheet, setSheet] = useState<"new" | "import" | "dupes" | null>(null);
+  const [confirmDelete, setConfirmDelete] = useState(false);
+  const [note, setNote] = useState<string | null>(null);
+  const { sort, toggle: toggleSort } = useSort();
+
+  const list = usePageQuery<ContactRecord>(
+    (page, signal) => g8Get<ContactRecord[]>("/contacts", { page, limit: pageSize, list_id: effectiveListId, ...apiFilters }, { signal }),
+    [effectiveListId, filters],
+    pageSize,
+    ["contacts", "list", "screen"],
+    urlFilters.ready,
+  );
+  const dupes = useG8Query((signal) => g8Get<{ pending?: number; count?: number }>("/duplicates/counts", { entity_type: "contact" }, { signal }), [], { key: ["duplicates", "counts", "contact"] });
+  const selection = useRowSelection<ContactRecord>(`${listId}|${JSON.stringify(filters)}`);
+  const rows = useMemo(() => sortRows(list.rows, sort, sortValue), [list.rows, sort]);
+  const hasFilters = urlFilters.active;
+  const pending = dupes.data?.data.pending ?? dupes.data?.data.count;
+  const lockedOnPage = list.rows.filter((r) => isMasked(r.work_email)).length;
+
+  const bulk = useBulkDelete("/contacts", (gone, total) => {
+    selection.drop(gone);
+    setConfirmDelete(false);
+    setNote(gone.length < total ? `Deleted ${gone.length} of ${total}. ${total - gone.length} could not be deleted; they are still selected.` : null);
+    if (openId != null && gone.includes(openId)) setIdParam(null);
+    void list.refetch();
+    void dupes.refetch();
+  });
+  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);
+
+  useEffect(() => { setNote(null); }, [filters, listId]);
+
+  return (
+    <ScreenLayout
+      className={props.className}
+      title="Contacts"
+      description="Everyone you sell to, with their history, notes and follow-ups."
+      icon={<Users className="size-5" aria-hidden />}
+      actions={
+        <>
+          {props.toolbarActions}
+          <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>
+        </>
+      }
+      stats={[
+        { label: "Contacts", value: list.loading && list.total === 0 ? "-" : list.total.toLocaleString(), hint: hasFilters ? "Matching the filters" : listId ? "In this list" : "In your workspace" },
+        { label: "Possible duplicates", value: pending ?? "-", tone: pending ? "warning" : "neutral", hint: "Review and merge" },
+        { label: "Locked on this page", value: lockedOnPage, hint: "Save to a list or enrich to reveal" },
+      ]}
+    >
+      <SplitView
+        detailOpen={openId != null}
+        expanded={full}
+        onExpandedChange={(e) => setView(e ? "full" : null)}
+        onCloseDetail={() => setIdParam(null)}
+        detailWidth="lg"
+        list={
+          <div className="flex flex-col gap-3">
+            <Toolbar
+              search={{ value: draft.name, onChange: (v) => set("name", v), placeholder: "Search contacts by name" }}
+              filters={
+                <>
+                  <input aria-label="Filter by job title" placeholder="Job title" className="h-9 w-36 rounded-md border bg-background px-3 text-sm" value={draft.job_title} onChange={(e) => set("job_title", e.target.value)} />
+                  <select aria-label="Filter by seniority" className="h-9 rounded-md border bg-background px-2 text-sm" value={draft.seniority_level} onChange={(e) => set("seniority_level", e.target.value)}>
+                    <option value="">Any seniority</option>
+                    {SENIORITY.map((s) => <option key={s} value={s}>{s}</option>)}
+                  </select>
+                  <input aria-label="Filter by country" placeholder="Country" className="h-9 w-32 rounded-md border bg-background px-3 text-sm" value={draft.country} onChange={(e) => set("country", e.target.value)} />
+                  <MoreFilters activeCount={MORE_KEYS.filter((k) => draft[k]).length}>
+                    <TextFilter label="email" type="email" value={draft.email} onChange={(v) => set("email", v)} className="w-44" />
+                    <TextFilter label="company name" placeholder="Company" value={draft.company_name} onChange={(v) => set("company_name", v)} />
+                    <TextFilter label="company ID" placeholder="Company ID" type="number" value={draft.company_id} onChange={(v) => set("company_id", v)} className="w-28" />
+                    <TextFilter label="industry" value={draft.industry} onChange={(v) => set("industry", v)} />
+                    <TextFilter label="department" placeholder="Department" value={draft.job_department} onChange={(v) => set("job_department", v)} />
+                    <TextFilter label="state" value={draft.state} onChange={(v) => set("state", v)} className="w-28" />
+                    <TextFilter label="city" value={draft.city} onChange={(v) => set("city", v)} className="w-32" />
+                    {listId == null ? <ListSelect label="Filter by list" emptyOption="Any list" value={draft.list} valueLabel={`List ${draft.list}`} pageSize={100} onChange={(l) => set("list", l ? String(l.id) : "")} /> : null}
+                  </MoreFilters>
+                  {hasFilters ? <Button variant="ghost" size="sm" onClick={urlFilters.clear}>Clear filters</Button> : null}
+                </>
+              }
+            />
+
+            {selection.ids.length > 0 ? (
+              <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 })}
+                <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>
+            ) : null}
+            {list.error ? <ApiError error={list.error} title="Could not load contacts" onRetry={() => void list.refetch()} /> : null}
+            {note ? <p role="alert" className="text-sm text-destructive">{note}</p> : null}
+
+            <div className="overflow-hidden rounded-md border">
+              <Table>
+                <TableHeader>
+                  <TableRow>
+                    <TableHead className="w-8"><input type="checkbox" aria-label="Select page" checked={allOnPage} onChange={() => selection.togglePage(rows)} /></TableHead>
+                    <SortHead label="Name" sortKey="name" sort={sort} onSort={toggleSort} />
+                    <SortHead label="Title" sortKey="title" sort={sort} onSort={toggleSort} />
+                    <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}
+                  </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>)
+                    : rows.map((row) => {
+                        const name = contactName(row);
+                        return (
+                          <TableRow key={row.id} data-testid={`contact-row-${row.id}`} data-state={row.id === openId ? "selected" : undefined} className="cursor-pointer" {...rowActivationProps(() => setIdParam(String(row.id)))}>
+                            <TableCell onClick={(e) => e.stopPropagation()}>
+                              <input type="checkbox" aria-label={`Select ${name}`} checked={selection.selected.has(row.id)} onChange={() => selection.toggle(row)} />
+                            </TableCell>
+                            <TableCell>
+                              <span className="flex items-center gap-2 font-medium"><EntityAvatar name={name} kind="person" size="sm" /><RecordLink param="id" id={row.id} onOpen={() => setIdParam(String(row.id))}>{name}</RecordLink></span>
+                            </TableCell>
+                            <TableCell><Cell value={row.job_title} /></TableCell>
+                            <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}
+                          </TableRow>
+                        );
+                      })}
+                </TableBody>
+              </Table>
+              {!list.loading && !list.error && rows.length === 0 ? (
+                <EmptyState
+                  title={hasFilters ? "No contacts match these filters" : "No contacts yet"}
+                  description={hasFilters ? "Try fewer filters." : "Add your first contact or import a file."}
+                  action={hasFilters ? <Button variant="outline" onClick={urlFilters.clear}>Clear filters</Button> : <Button onClick={() => setSheet("new")}>New contact</Button>}
+                />
+              ) : null}
+              <Pager page={list.page} pageCount={list.pageCount} total={list.total} noun="contacts" hasNext={list.hasNext} loading={list.loading} onPage={list.setPage} />
+            </div>
+            {sort ? <p className="text-xs text-muted-foreground">Sorted within this page only.</p> : null}
+          </div>
+        }
+        detail={openId != null ? (
+          <ContactPanel key={openId} full={full} setFull={(v) => setView(v ? "full" : null)} contactId={openId} seed={list.rows.find((r) => r.id === openId)} onClose={() => setIdParam(null)} onChanged={reload} onDeleted={() => { setIdParam(null); reload(); }}
+            onOpenCompany={props.onOpenCompany} renderActions={props.renderDetailActions} extraTabs={props.extraDetailTabs} />
+        ) : null}
+      />
+
+      <FormSheet open={sheet === "new"} onOpenChange={(o) => setSheet(o ? "new" : null)} title="New contact" description="A name, an email or a LinkedIn URL is enough.">
+        <RecordForm entity="contact" listId={listId} onCancel={() => setSheet(null)}
+          onSaved={({ id }) => { setSheet(null); reload(); if (id != null) setIdParam(String(id)); }}
+          onDuplicate={(existing) => { setSheet(null); if (existing != null) setIdParam(String(existing)); }} />
+      </FormSheet>
+      <FormSheet open={sheet === "import"} onOpenChange={(o) => setSheet(o ? "import" : null)} title="Import contacts" description="Upload a CSV or Excel file, map the columns and choose where they go.">
+        <ImportWizard listId={listId} onImported={reload} />
+      </FormSheet>
+      <FormSheet open={sheet === "dupes"} onOpenChange={(o) => setSheet(o ? "dupes" : null)} title="Duplicate contacts" description="Merge pairs, or mark them as not duplicates.">
+        <DedupeReview entity="contact" onChanged={reload} />
+      </FormSheet>
+
+      <ConfirmSpendDialog
+        open={confirmDelete}
+        tier="destructive"
+        title={`Delete ${plural(selection.ids.length, "contact")}`}
+        description="They are removed from every list and sequence."
+        affected={selection.ids.length}
+        confirming={bulk.loading}
+        onConfirm={() => void bulk.mutate(selection.ids)}
+        onCancel={() => setConfirmDelete(false)}
+      />
+    </ScreenLayout>
+  );
+}
+
+interface ContactPanelProps {
+  full: boolean;
+  setFull: (full: boolean) => void;
+  contactId: number;
+  /** The list row, for fields the detail answer lacks (owner). */
+  seed?: ContactRecord;
+  onClose: () => void;
+  onChanged: () => void;
+  onDeleted: () => void;
+  onOpenCompany?: (companyId: number) => void;
+  renderActions?: ContactsScreenProps["renderDetailActions"];
+  extraTabs?: ContactsScreenProps["extraDetailTabs"];
+}
+
+function ContactPanel({ full, setFull, contactId, seed, onClose, onChanged, onDeleted, onOpenCompany, renderActions, extraTabs = [] }: ContactPanelProps) {
+  const [editing, setEditing] = useState(false);
+  const [confirm, setConfirm] = useState(false);
+  const [feedKey, setFeedKey] = useState(0);
+  const query = useG8Query((signal) => g8Get<ContactRecord>(`/contacts/${contactId}`, { include_custom_fields: true }, { signal }), [contactId], {
+    key: ["contacts", "detail", contactId],
+    // The row the contact was opened from paints the panel at once; the full record replaces it.
+    placeholderData: seed ? { data: seed } : undefined,
+  });
+  /** Edit, delete and slot actions wait for the full record: a list row must never seed the edit form. */
+  const partial = query.isPlaceholderData === true;
+  const remove = useG8Mutation(async () => {
+    try { await g8Delete(`/contacts/${contactId}`); } catch (e) { if (errorStatus(e) !== 404) throw e; }
+  }, { invalidates: [["contacts", "list"]], onSuccess: () => { setConfirm(false); onDeleted(); } });
+  const bump = () => setFeedKey((k) => k + 1);
+
+  if (query.loading && !query.data) return <div className="flex flex-col gap-3 p-4"><Skeleton className="h-14 w-full" /><Skeleton className="h-40 w-full" /></div>;
+  // A failed full record must not leave the list row on screen with every action disabled.
+  if (query.error && (!query.data || partial)) return <div className="p-4"><ApiError error={query.error} title="Could not load this contact" onRetry={() => void query.refetch()} /></div>;
+  const contact = query.data!.data;
+  const name = contactName(contact);
+  const val = (v?: string | null): ReactNode => (isMasked(v) ? <Locked /> : v || <span className="text-muted-foreground">-</span>);
+
+  const overview = (
+    <KeyValueList columns={2} items={[
+      { label: "Work email", value: val(contact.work_email) },
+      { label: "Direct phone", value: val(contact.direct_phone) },
+      { label: "Mobile phone", value: val(contact.mobile_phone) },
+      { label: "LinkedIn", value: val(contact.linkedin_url) },
+      { label: "Seniority", value: val(contact.seniority_level) },
+      { label: "Department", value: val(contact.job_department) },
+      { label: "Location", value: val(location(contact)) },
+      { label: "Owner", value: val(contact.owner_name ?? seed?.owner_name) },
+      { label: "Added", value: val(formatDay(contact.created_at)) },
+      ...Object.entries(contact.custom_fields ?? {}).map(([k, v]) => ({ label: k, value: val(v) })),
+      ...(contact.about ? [{ label: "About", value: contact.about }] : []),
+    ]} />
+  );
+
+  return (
+    <>
+      <DetailPanel
+        title={name}
+        subtitle={contactSubtitle(contact)}
+        avatar={<EntityAvatar name={name} kind="person" size="lg" />}
+        badges={isMasked(contact.work_email) ? <StatusPill tone="warning" dot>Locked email</StatusPill> : undefined}
+        onClose={onClose}
+        onExpand={full ? undefined : () => setFull(true)}
+        onCollapse={full ? () => setFull(false) : undefined}
+        actions={
+          <>
+            {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>
+            <Button variant="destructive" size="sm" disabled={partial} onClick={() => setConfirm(true)}>Delete</Button>
+          </>
+        }
+        tabs={[
+          { id: "overview", label: "Overview", content: overview },
+          { 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} /> },
+          ...(partial ? [] : extraTabs).map((t) => ({ id: t.id, label: t.label, content: t.render(contact) })),
+        ]}
+      />
+      {remove.error ? <div className="p-4"><ApiError error={remove.error} title="Could not delete the contact" /></div> : null}
+      <FormSheet open={editing && !partial} onOpenChange={setEditing} title={`Edit ${name}`}>
+        <RecordForm entity="contact" record={contact} onCancel={() => setEditing(false)} onSaved={() => { setEditing(false); void query.refetch(); bump(); onChanged(); }} />
+      </FormSheet>
+      <ConfirmSpendDialog open={confirm} tier="destructive" title={`Delete ${name}`} description="The contact is removed from every list and sequence." affected={1}
+        confirming={remove.loading} onConfirm={() => void remove.mutate(undefined)} onCancel={() => setConfirm(false)} />
+    </>
+  );
+}

package/blocks/crm/components/dedupe-review.tsx

@@ -21,6 +21,7 @@
 import { useState } from "react";
 import { Button, Tabs, TabsContent, TabsList, TabsTrigger } from "@graph8/sdk/ui";
 import { ApiError } from "@/g8/components/api-error";
+import { FirstNotice } from "@/g8/components/paging-notices";
 import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
 import { EmptyState } from "@/g8/components/empty-state";
 import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
@@ -29,6 +30,7 @@ import { useJobPoll } from "@/g8/hooks/use-job-poll";
 import { usePaginated } from "@/g8/hooks/use-paginated";
 import { g8Get, g8Post } from "@/g8/lib/g8-client";
 import { isMasked } from "../lib/crm-types";
+import { useBrand } from "@/g8/hooks/use-brand";
 
 export interface DedupeReviewProps {
   entity: "contact" | "company";
@@ -49,10 +51,14 @@ const CRITERIA = [
 function side(pair: Pair, s: "a" | "b", entity: "contact" | "company") {
   const name = entity === "contact" ? [pair[`${s}_first_name`], pair[`${s}_last_name`]].filter(Boolean).join(" ") : String(pair[`${s}_name`] ?? "");
   const lines = entity === "contact" ? [pair[`${s}_email`], pair[`${s}_phone`], pair[`${s}_owner_name`]] : [pair[`${s}_domain`], pair[`${s}_industry`], pair[`${s}_owner_name`]];
-  return { id: pair[`${s}_id`] as number, name: name || "Unnamed", lines: lines.filter(Boolean).map((l) => (isMasked(l) ? "Locked" : String(l))) };
+  return { id: pair[`${s}_id`] as number, name: name || String([pair[`${s}_email`], pair[`${s}_domain`]].find((v) => v && !isMasked(v)) ?? `#${pair[`${s}_id`]}`), lines: lines.filter(Boolean).map((l) => (isMasked(l) ? "Locked" : String(l))) };
 }
 
+/** The recent-merges API has no paging: a full read is announced under the list. */
+const RECENT_LIMIT = 25;
+
 export function DedupeReview({ entity, onChanged, className }: DedupeReviewProps) {
+  const brand = useBrand();
   const plural = entity === "contact" ? "contacts" : "companies";
   const [merging, setMerging] = useState<{ pair: Pair; keep: "a" | "b" } | null>(null);
   const [picked, setPicked] = useState<Set<string>>(new Set());
@@ -65,7 +71,7 @@ export function DedupeReview({ entity, onChanged, className }: DedupeReviewProps
     const res = await g8Get<{ items: Pair[]; next_cursor?: string | null }>("/duplicates", { entity_type: entity, status: "pending", limit: 25, cursor }, { signal });
     return { data: res.data.items ?? [], pagination: { next_cursor: res.data.next_cursor ?? null } };
   }, [entity]);
-  const recent = useG8Query((signal) => g8Get<MergeRow[]>("/duplicates/recent-merges", { entity_type: entity, limit: 25 }, { signal }), [entity]);
+  const recent = useG8Query((signal) => g8Get<MergeRow[]>("/duplicates/recent-merges", { entity_type: entity, limit: RECENT_LIMIT }, { signal }), [entity]);
   const [busy, setBusy] = useState<string | null>(null);
   const dropPick = (id: string | undefined) => id && setPicked((p) => { const n = new Set(p); n.delete(id); return n; });
   const refreshAll = () => { void pairs.reload(); void counts.refetch(); void recent.refetch(); onChanged?.(); };
@@ -73,9 +79,9 @@ export function DedupeReview({ entity, onChanged, className }: DedupeReviewProps
   const merge = useG8Mutation((v: { pair: Pair; keep: "a" | "b" }) => {
     const keepId = v.pair[`${v.keep}_id`], dropId = v.pair[`${v.keep === "a" ? "b" : "a"}_id`];
     return g8Post(`/${plural}/${keepId}/merge`, { secondary_id: dropId, suggestion_id: v.pair.suggestion_id });
-  }, { onSuccess: (_r, v) => { dropPick(v.pair.suggestion_id); setMerging(null); refreshAll(); } });
-  const reject = useG8Mutation((id: string) => { setBusy(id); return g8Post(`/duplicates/${id}/reject`, {}); }, { onSuccess: (_r, id) => { dropPick(id); setBusy(null); refreshAll(); }, onError: () => setBusy(null) });
-  const undo = useG8Mutation((id: string) => { setBusy(id); return g8Post(`/duplicates/undo-merge/${id}`, {}); }, { onSuccess: () => { setBusy(null); refreshAll(); }, onError: () => setBusy(null) });
+  }, { invalidates: [plural, "duplicates"], onSuccess: (_r, v) => { dropPick(v.pair.suggestion_id); setMerging(null); refreshAll(); } });
+  const reject = useG8Mutation((id: string) => { setBusy(id); return g8Post(`/duplicates/${id}/reject`, {}); }, { invalidates: ["duplicates"], onSuccess: (_r, id) => { dropPick(id); setBusy(null); refreshAll(); }, onError: () => setBusy(null) });
+  const undo = useG8Mutation((id: string) => { setBusy(id); return g8Post(`/duplicates/undo-merge/${id}`, {}); }, { invalidates: [plural, "duplicates"], onSuccess: () => { setBusy(null); refreshAll(); }, onError: () => setBusy(null) });
   const bulk = useG8Mutation(() => g8Post<{ run_id: string }>("/duplicates/bulk-merge", { suggestion_ids: [...picked], criterion }), {
     onSuccess: (r) => { setBulkOpen(false); setRunId(r.data.run_id); },
   });
@@ -109,7 +115,7 @@ export function DedupeReview({ entity, onChanged, className }: DedupeReviewProps
           {run.polling || run.status ? <p role="status" className="text-sm text-muted-foreground">Merging: {run.status?.merged ?? 0} of {run.status?.total ?? picked.size} done, {run.status?.blocked ?? 0} blocked.</p> : null}
           {mergeError ? <ApiError error={mergeError} title="That did not go through" /> : null}
           {pairs.error ? <ApiError error={pairs.error} title="Could not load duplicates" onRetry={() => void pairs.reload()} /> : null}
-          {!pairs.loading && !pairs.error && pairs.items.length === 0 ? <EmptyState title="No duplicates to review" description="New suggestions appear here when graph8 finds likely matches." /> : null}
+          {!pairs.loading && !pairs.error && pairs.items.length === 0 ? <EmptyState title="No duplicates to review" description={`New suggestions appear here when ${brand.linkLabel} finds likely matches.`} /> : null}
 
           {pairs.items.map((pair) => (
             <div key={pair.suggestion_id} className="rounded-md border p-3" data-testid="duplicate-pair">
@@ -143,6 +149,7 @@ export function DedupeReview({ entity, onChanged, className }: DedupeReviewProps
               {m.can_undo ? <Button size="sm" variant="outline" loading={undo.loading && busy === m.id} onClick={() => void undo.mutate(m.id)}>Undo</Button> : null}
             </div>
           ))}
+          <FirstNotice shown={(recent.data?.data ?? []).length} limit={RECENT_LIMIT} noun="merges" />
         </TabsContent>
       </Tabs>
 

package/blocks/crm/components/import-wizard.tsx

@@ -20,10 +20,12 @@
 import { useEffect, useState } from "react";
 import { Button, Input, Label, Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@graph8/sdk/ui";
 import { ApiError } from "@/g8/components/api-error";
+import { ListSelect } from "./list-select";
 import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
 import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
 import { useG8Query } from "@/g8/hooks/use-g8-query";
 import { g8Get, g8Post } from "@/g8/lib/g8-client";
+import { useBrand } from "@/g8/hooks/use-brand";
 
 export interface ImportWizardProps {
   /** Largest file accepted. Default 5 MiB: the /api/g8 proxy rejects bigger bodies (raise maxBodyBytes there first). */
@@ -37,7 +39,6 @@ export interface ImportWizardProps {
 export interface ImportResult { imported?: number | null; updated?: number | null; skipped?: number | null; failed?: number | null; list_id?: number | null }
 interface Upload { datafile_id: string; row_count?: number | null; columns: string[] }
 interface Preview { rows: Array<Record<string, unknown>>; total: number }
-interface ListOption { id: number; title: string; type?: string | null }
 
 export const IMPORT_TARGETS: Array<{ value: string; label: string }> = [
   { value: "CONTACT_FIRST_NAME", label: "First name" }, { value: "CONTACT_LAST_NAME", label: "Last name" },
@@ -68,6 +69,7 @@ export function guessMapping(columns: string[]): Record<string, string> {
 }
 
 export function ImportWizard({ listId, onImported, maxBytes = 5 * 1024 * 1024, className }: ImportWizardProps) {
+  const brand = useBrand();
   const [tooBig, setTooBig] = useState<string | null>(null);
   const [upload, setUpload] = useState<Upload | null>(null);
   const [mapping, setMapping] = useState<Record<string, string>>({});
@@ -78,7 +80,6 @@ export function ImportWizard({ listId, onImported, maxBytes = 5 * 1024 * 1024, c
   const [confirmOpen, setConfirmOpen] = useState(false);
   const [result, setResult] = useState<ImportResult | null>(null);
 
-  const lists = useG8Query((signal) => g8Get<ListOption[]>("/lists", { limit: 200 }, { signal }), [], { enabled: upload != null && listId == null });
   const send = useG8Mutation((file: File) => { const body = new FormData(); body.append("file", file); return g8Post<Upload>("/imports", body); }, {
     onSuccess: (r) => { setUpload(r.data); setMapping(guessMapping(r.data.columns ?? [])); },
   });
@@ -105,7 +106,7 @@ export function ImportWizard({ listId, onImported, maxBytes = 5 * 1024 * 1024, c
   if (result) {
     return (
       <div className={`flex flex-col gap-3 ${className ?? ""}`} role="status">
-        <h3 className="text-base font-semibold">Import finished</h3>
+        <h3 className="text-base font-medium">Import finished</h3>
         <p className="text-sm">{result.imported ?? 0} new, {result.updated ?? 0} updated, {result.skipped ?? 0} skipped, {result.failed ?? 0} failed.</p>
         <Button variant="outline" onClick={() => { setResult(null); setUpload(null); setMapping({}); setDestination(listId); setNewListTitle(""); setPolicy("autofill"); setEnrich(false); run.reset(); preview.reset(); }}>Import another file</Button>
       </div>
@@ -159,15 +160,12 @@ export function ImportWizard({ listId, onImported, maxBytes = 5 * 1024 * 1024, c
             <h3 className="text-sm font-medium">3. Destination and rules</h3>
             {listId == null ? (
               <div className="flex flex-wrap items-center gap-2">
-                <select aria-label="Destination list" className="h-9 rounded-md border bg-background px-2 text-sm" value={destination ?? ""} onChange={(e) => setDestination(e.target.value ? Number(e.target.value) : undefined)}>
-                  <option value="">New list...</option>
-                  {(lists.data?.data ?? []).filter((l) => !l.type || l.type === "contacts").map((l) => <option key={l.id} value={l.id}>{l.title}</option>)}
-                </select>
+                <ListSelect label="Destination list" emptyOption="New list..." type="contacts" pageSize={200} value={destination} valueLabel={newListTitle.trim() || undefined} enabled={upload != null && listId == null} selectClassName="h-9 rounded-md border bg-background px-2 text-sm" onChange={(l) => setDestination(l ? l.id : undefined)} />
                 {destination == null ? <Input aria-label="New list name" placeholder="New list name" className="w-56" value={newListTitle} onChange={(e) => setNewListTitle(e.target.value)} /> : null}
               </div>
             ) : null}
             <label className="flex items-center gap-2 text-sm"><input type="checkbox" checked={policy === "override"} onChange={(e) => setPolicy(e.target.checked ? "override" : "autofill")} /> Overwrite existing values (default only fills blanks)</label>
-            <label className="flex items-center gap-2 text-sm"><input type="checkbox" checked={enrich} onChange={(e) => setEnrich(e.target.checked)} /> Fill missing fields from graph8 (uses credits)</label>
+            <label className="flex items-center gap-2 text-sm"><input type="checkbox" checked={enrich} onChange={(e) => setEnrich(e.target.checked)} /> Fill missing fields from {brand.linkLabel} (uses credits)</label>
           </section>
 
           {run.error ? <ApiError error={run.error} title="The import failed" /> : null}
@@ -181,7 +179,7 @@ export function ImportWizard({ listId, onImported, maxBytes = 5 * 1024 * 1024, c
         open={confirmOpen}
         tier={enrich ? "billable" : "destructive"}
         title={`Import ${rows.toLocaleString()} rows`}
-        description={policy === "override" ? "Matching contacts get their existing values replaced by the file." : "Missing fields are filled from graph8."}
+        description={policy === "override" ? "Matching contacts get their existing values replaced by the file." : `Missing fields are filled from ${brand.linkLabel}.`}
         affected={enrich ? undefined : rows}
         confirming={run.loading}
         confirmLabel="Import"

package/blocks/crm/components/list-select.tsx

@@ -0,0 +1,20 @@
+"use client";
+
+/**
+ * ListSelect: the audience-list dropdown with the list read wired in. A native select that is searchable (server
+ * search once there is more than one page) and paged ("Load more lists"), so the 201st list is reachable. It is the
+ * foundation's ListSelect plus `GET /lists` (the foundation holds no API scope); every block that picks a list
+ * (forms, lists, newsletter, nurture, sequencer, dialer) imports this one.
+ *
+ * SDK operations, in order:
+ *   1. GET /lists?search&page&limit   (lists.listLists)   read - through lib/read-lists.ts
+ */
+import { ListSelect as BaseListSelect } from "@/g8/components/list-select";
+import type { ListSelectProps } from "@/g8/components/list-select";
+import { readLists } from "../lib/read-lists";
+
+export type { ListSelectOption } from "@/g8/components/list-select";
+
+export function ListSelect(props: Omit<ListSelectProps, "read">) {
+  return <BaseListSelect {...props} read={readLists} />;
+}

package/blocks/crm/components/notes-panel.tsx

@@ -45,11 +45,11 @@ export function NotesPanel({ entity, entityId, onChanged, className }: NotesPane
   const [editing, setEditing] = useState<{ id: string; content: string } | null>(null);
   const [deleting, setDeleting] = useState<NoteItem | null>(null);
 
-  const notes = useG8Query((signal) => g8Get<NoteItem[]>(base, undefined, { signal }), [base]);
+  const notes = useG8Query((signal) => g8Get<NoteItem[]>(base, undefined, { signal }), [base], { key: ["notes", entity, entityId] });
   const done = () => { void notes.refetch(); onChanged?.(); };
-  const add = useG8Mutation((content: string) => g8Post(base, { content }), { onSuccess: () => { setDraft(""); done(); } });
-  const edit = useG8Mutation((v: { id: string; content: string }) => g8Patch(`/notes/${v.id}`, { content: v.content }), { onSuccess: () => { setEditing(null); done(); } });
-  const remove = useG8Mutation((id: string) => g8Delete(`/notes/${id}`), { onSuccess: () => { setDeleting(null); done(); } });
+  const add = useG8Mutation((content: string) => g8Post(base, { content }), { invalidates: [["notes", entity, entityId]], onSuccess: () => { setDraft(""); done(); } });
+  const edit = useG8Mutation((v: { id: string; content: string }) => g8Patch(`/notes/${v.id}`, { content: v.content }), { invalidates: [["notes"]], onSuccess: () => { setEditing(null); done(); } });
+  const remove = useG8Mutation((id: string) => g8Delete(`/notes/${id}`), { invalidates: [["notes"]], onSuccess: () => { setDeleting(null); done(); } });
 
   const items = (notes.data?.data ?? []) as NoteItem[];
   return (