@graph8/sdk 0.362.0 → 0.373.0

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

@@ -0,0 +1,359 @@
+"use client";
+
+/**
+ * CompaniesScreen: the finished accounts workspace. A searchable, filterable, sortable, paginated grid of companies on the
+ * left; the open company (people, timeline, notes, tasks, fields) beside it. No props are required.
+ *
+ * Composes: ScreenLayout, StatStrip, Toolbar, SplitView, DetailPanel, FormSheet (screen kit) with RecordForm,
+ * ContactTable and RecordForm (the People tab and "Add person"), ActivityTimeline, NotesPanel, TaskList and DedupeReview (this block).
+ *
+ * Flows: search and filter (name, domain, industry, country; debounced) - sort the loaded page - paginate - open a company
+ * (deep link ?id=, full page with &view=full) - create a company (a domain is required; an existing one is merged) - edit - delete one or many (confirm,
+ * "N of M" report, 404 = already gone) - see, open and add its people - add notes and tasks - review and merge duplicates -
+ * hand a company to other blocks through the slot props.
+ *
+ * SDK operations: none of its own. listCompanies, getCompany, getActivityFeed, duplicateCounts are `read`; forms, notes and
+ * tasks are `write`; deleteCompany (rows, detail and bulk) is `destructive` and always goes through ConfirmSpendDialog.
+ * Company import is not part of the API (the import wizard writes contacts, which create their companies by domain).
+ */
+
+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, Plus, Trash2, UserPlus } 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 { 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 { MoreFilters, RangeFilter, TextFilter } from "@/g8/components/screen/filter-controls";
+import { g8Delete, g8Get } from "@/g8/lib/g8-client";
+import { usePageQuery } from "../hooks/use-page-query";
+import { companyName, errorStatus, location } from "../lib/crm-types";
+import type { CompanyRecord, ContactRecord, ScreenActionContext } from "../lib/crm-types";
+import { Pager, SortHead, formatDay, sortRows, useBulkDelete, useRowSelection, useSort } from "../lib/screen-parts";
+import { ActivityTimeline } from "./activity-timeline";
+import { ContactTable } from "./contact-table";
+import { DedupeReview } from "./dedupe-review";
+import { NotesPanel } from "./notes-panel";
+import { RecordForm } from "./record-form";
+import { TaskList } from "./task-list";
+
+export interface CompaniesScreenProps {
+  pageSize?: number;
+  /** Buttons at the end of each row. */
+  renderRowActions?: (row: CompanyRecord, ctx: ScreenActionContext) => ReactNode;
+  /** Buttons in the open company's header. */
+  renderDetailActions?: (company: CompanyRecord, ctx: ScreenActionContext) => ReactNode;
+  /** Extra tabs on the open company. */
+  extraDetailTabs?: Array<{ id: string; label: string; render: (company: CompanyRecord) => ReactNode }>;
+  /** Extra buttons in the page header, before "New company". */
+  toolbarActions?: ReactNode;
+  /** Extra bulk actions next to Delete. */
+  renderBulkActions?: (selection: { ids: number[]; rows: CompanyRecord[]; clear: () => void }) => ReactNode;
+  /** Called when a person in the People tab is clicked. Without it the rows are not clickable. */
+  onOpenContact?: (contact: ContactRecord) => void;
+  className?: string;
+}
+
+/** Every filter the companies API takes: text (name, domain, industry, country, state, city, description) and four from/to ranges. */
+const FILTER_KEYS = ["name", "domain", "industry", "country", "state", "city", "description", "employee_count_min", "employee_count_max", "revenue_min", "revenue_max", "founded_year_min", "founded_year_max", "linkedin_followers_min", "linkedin_followers_max"] as const;
+type FilterKey = (typeof FILTER_KEYS)[number];
+const MORE_KEYS: readonly FilterKey[] = FILTER_KEYS.filter((k) => !["name", "domain", "industry", "country"].includes(k));
+
+function sortValue(row: CompanyRecord, key: string): string | null | undefined {
+  if (key === "name") return row.name || row.domain;
+  if (key === "domain") return row.domain;
+  if (key === "industry") return row.industry;
+  if (key === "employees") return row.employee_count;
+  if (key === "location") return location(row);
+  return null;
+}
+
+const dash = <span className="text-muted-foreground">-</span>;
+
+export function CompaniesScreen(props: CompaniesScreenProps) {
+  const { 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 /companies/NaN. */
+  const openId = parsedId != null && Number.isFinite(parsedId) ? parsedId : null;
+  // The filters live in the URL (`co_city=...`), so a filtered view survives reload, Back and sharing.
+  const urlFilters = useUrlFilters(FILTER_KEYS, { prefix: "co_" });
+  const { draft, filters } = urlFilters;
+  const [sheet, setSheet] = useState<"new" | "dupes" | null>(null);
+  const [confirmDelete, setConfirmDelete] = useState(false);
+  const [note, setNote] = useState<string | null>(null);
+  const { sort, toggle: toggleSort } = useSort();
+
+  const list = usePageQuery<CompanyRecord>(
+    (page, signal) => g8Get<CompanyRecord[]>("/companies", { page, limit: pageSize, ...Object.fromEntries(Object.entries(filters).filter(([, v]) => v)) }, { signal }),
+    [filters],
+    pageSize,
+    ["companies", "list", "screen"],
+    urlFilters.ready,
+  );
+  const dupes = useG8Query((signal) => g8Get<{ pending?: number; count?: number }>("/duplicates/counts", { entity_type: "company" }, { signal }), [], { key: ["duplicates", "counts", "company"] });
+  const selection = useRowSelection<CompanyRecord>(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 industries = new Set(list.rows.map((r) => r.industry).filter(Boolean)).size;
+  const reload = () => { void list.refetch(); void dupes.refetch(); };
+  const set = (key: FilterKey, v: string) => urlFilters.set(key, v);
+  const allOnPage = rows.length > 0 && rows.every((r) => selection.selected.has(r.id));
+
+  const bulk = useBulkDelete("/companies", (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);
+    reload();
+  });
+  useEffect(() => { setNote(null); }, [filters]);
+
+  return (
+    <ScreenLayout
+      className={props.className}
+      title="Companies"
+      description="Every account, who works there and what has happened with them."
+      icon={<Building2 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 size="sm" onClick={() => setSheet("new")}><Plus className="size-4" aria-hidden />New company</Button>
+        </>
+      }
+      stats={[
+        { label: "Companies", value: list.loading && list.total === 0 ? "-" : list.total.toLocaleString(), hint: hasFilters ? "Matching the filters" : "In your workspace" },
+        { label: "Possible duplicates", value: pending ?? "-", tone: pending ? "warning" : "neutral", hint: "Review and merge" },
+        { label: "Industries on this page", value: industries, hint: "Distinct industries in view" },
+      ]}
+    >
+      <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 companies by name" }}
+              filters={
+                <>
+                  <input aria-label="Filter by domain" placeholder="Domain" className="h-9 w-36 rounded-md border bg-background px-3 text-sm" value={draft.domain} onChange={(e) => set("domain", e.target.value)} />
+                  <input aria-label="Filter by industry" placeholder="Industry" className="h-9 w-36 rounded-md border bg-background px-3 text-sm" value={draft.industry} onChange={(e) => set("industry", e.target.value)} />
+                  <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="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" />
+                    <TextFilter label="description" value={draft.description} onChange={(v) => set("description", v)} className="w-44" />
+                    <RangeFilter label="Employees" min={draft.employee_count_min} max={draft.employee_count_max} onMinChange={(v) => set("employee_count_min", v)} onMaxChange={(v) => set("employee_count_max", v)} />
+                    <RangeFilter label="Revenue" min={draft.revenue_min} max={draft.revenue_max} onMinChange={(v) => set("revenue_min", v)} onMaxChange={(v) => set("revenue_max", v)} />
+                    <RangeFilter label="Founded" min={draft.founded_year_min} max={draft.founded_year_max} onMinChange={(v) => set("founded_year_min", v)} onMaxChange={(v) => set("founded_year_max", v)} />
+                    <RangeFilter label="LinkedIn followers" min={draft.linkedin_followers_min} max={draft.linkedin_followers_max} onMinChange={(v) => set("linkedin_followers_min", v)} onMaxChange={(v) => set("linkedin_followers_max", v)} />
+                  </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 companies" 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="Company" sortKey="name" sort={sort} onSort={toggleSort} />
+                    <SortHead label="Domain" sortKey="domain" sort={sort} onSort={toggleSort} />
+                    <SortHead label="Industry" sortKey="industry" sort={sort} onSort={toggleSort} />
+                    <SortHead label="Employees" sortKey="employees" sort={sort} onSort={toggleSort} />
+                    <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 = companyName(row);
+                        return (
+                          <TableRow key={row.id} data-testid={`company-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} imageUrl={row.logo_url} kind="company" size="sm" /><RecordLink param="id" id={row.id} onOpen={() => setIdParam(String(row.id))}>{name}</RecordLink></span></TableCell>
+                            <TableCell>{row.domain || dash}</TableCell>
+                            <TableCell>{row.industry || dash}</TableCell>
+                            <TableCell>{row.employee_count || dash}</TableCell>
+                            <TableCell>{location(row) || dash}</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 companies match these filters" : "No companies yet"}
+                  description={hasFilters ? "Try fewer filters." : "Add a company, or import contacts and their companies are created from their domains."}
+                  action={hasFilters ? <Button variant="outline" onClick={urlFilters.clear}>Clear filters</Button> : <Button onClick={() => setSheet("new")}>New company</Button>}
+                />
+              ) : null}
+              <Pager page={list.page} pageCount={list.pageCount} total={list.total} noun="companies" 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 ? (
+          <CompanyPanel key={openId} full={full} setFull={(v) => setView(v ? "full" : null)} companyId={openId} seed={list.rows.find((r) => r.id === openId)} onClose={() => setIdParam(null)} onChanged={reload} onDeleted={() => { setIdParam(null); reload(); }}
+            onOpenContact={props.onOpenContact} renderActions={props.renderDetailActions} extraTabs={props.extraDetailTabs} />
+        ) : null}
+      />
+
+      <FormSheet open={sheet === "new"} onOpenChange={(o) => setSheet(o ? "new" : null)} title="New company" description="A domain identifies the company; if it exists, it is updated instead.">
+        <RecordForm entity="company" onCancel={() => setSheet(null)} onSaved={({ id }) => { setSheet(null); reload(); if (id != null) setIdParam(String(id)); }} />
+      </FormSheet>
+      <FormSheet open={sheet === "dupes"} onOpenChange={(o) => setSheet(o ? "dupes" : null)} title="Duplicate companies" description="Merge pairs, or mark them as not duplicates.">
+        <DedupeReview entity="company" onChanged={reload} />
+      </FormSheet>
+
+      <ConfirmSpendDialog
+        open={confirmDelete}
+        tier="destructive"
+        title={`Delete ${plural(selection.ids.length, "company", "companies")}`}
+        description="Their contacts stay but lose the company link."
+        affected={selection.ids.length}
+        confirming={bulk.loading}
+        onConfirm={() => void bulk.mutate(selection.ids)}
+        onCancel={() => setConfirmDelete(false)}
+      />
+    </ScreenLayout>
+  );
+}
+
+interface CompanyPanelProps {
+  full: boolean;
+  setFull: (full: boolean) => void;
+  companyId: number;
+  /** The list row, for fields the detail answer lacks (owner). */
+  seed?: CompanyRecord;
+  onClose: () => void;
+  onChanged: () => void;
+  onDeleted: () => void;
+  onOpenContact?: (contact: ContactRecord) => void;
+  renderActions?: CompaniesScreenProps["renderDetailActions"];
+  extraTabs?: CompaniesScreenProps["extraDetailTabs"];
+}
+
+function CompanyPanel({ full, setFull, companyId, seed, onClose, onChanged, onDeleted, onOpenContact, renderActions, extraTabs = [] }: CompanyPanelProps) {
+  const [editing, setEditing] = useState(false);
+  const [confirm, setConfirm] = useState(false);
+  const [feedKey, setFeedKey] = useState(0);
+  const [addingPerson, setAddingPerson] = useState(false);
+  const [peopleKey, setPeopleKey] = useState(0);
+  const query = useG8Query((signal) => g8Get<CompanyRecord>(`/companies/${companyId}`, { include_custom_fields: true }, { signal }), [companyId], {
+    key: ["companies", "detail", companyId],
+    // The row the company 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(`/companies/${companyId}`); } catch (e) { if (errorStatus(e) !== 404) throw e; }
+  }, { invalidates: [["companies", "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 company" onRetry={() => void query.refetch()} /></div>;
+  const company = query.data!.data;
+  const name = companyName(company);
+  const val = (v?: string | number | null): ReactNode => (v == null || v === "" ? dash : v);
+
+  return (
+    <>
+      <DetailPanel
+        title={name}
+        subtitle={[company.domain, company.industry].filter(Boolean).join(" - ") || "No domain or industry"}
+        avatar={<EntityAvatar name={name} imageUrl={company.logo_url} kind="company" size="lg" />}
+        onClose={onClose}
+        onExpand={full ? undefined : () => setFull(true)}
+        onCollapse={full ? () => setFull(false) : undefined}
+        actions={
+          <>
+            {partial ? null : renderActions?.(company, { reload: () => { void query.refetch(); bump(); onChanged(); } })}
+            <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: (
+            <KeyValueList columns={2} items={[
+              { label: "Website", value: val(company.website) },
+              { label: "Phone", value: val(company.phone) },
+              { label: "Employees", value: val(company.employee_count) },
+              { label: "Revenue", value: val(company.revenue) },
+              { label: "Founded", value: val(company.founded_year) },
+              { label: "Location", value: val(location(company)) },
+              { label: "LinkedIn", value: val(company.linkedin_url) },
+              { label: "Owner", value: val(company.owner_name ?? seed?.owner_name) },
+              { label: "People", value: val(company.contact_count) },
+              { label: "Added", value: val(formatDay(company.created_at)) },
+              ...Object.entries(company.custom_fields ?? {}).map(([k, v]) => ({ label: k, value: val(v) })),
+              ...(company.description ? [{ label: "About", value: company.description }] : []),
+            ]} />
+          ) },
+          { id: "people", label: "People", content: (
+            <div className="flex flex-col gap-3">
+              <div><Button variant="outline" size="sm" onClick={() => setAddingPerson(true)}><UserPlus className="size-4" aria-hidden />Add person</Button></div>
+              <ContactTable key={peopleKey} companyId={companyId} pageSize={10} onOpen={onOpenContact} />
+            </div>
+          ) },
+          { id: "activity", label: "Activity", content: <ActivityTimeline entityType="company" entityId={companyId} refreshKey={feedKey} /> },
+          { id: "notes", label: "Notes", content: <NotesPanel entity="company" entityId={companyId} onChanged={bump} /> },
+          { id: "tasks", label: "Tasks", content: <TaskList entity="company" entityId={companyId} onChanged={bump} /> },
+          ...(partial ? [] : extraTabs).map((t) => ({ id: t.id, label: t.label, content: t.render(company) })),
+        ]}
+      />
+      {remove.error ? <div className="p-4"><ApiError error={remove.error} title="Could not delete the company" /></div> : null}
+      <FormSheet open={editing && !partial} onOpenChange={setEditing} title={`Edit ${name}`}>
+        <RecordForm entity="company" record={company} onCancel={() => setEditing(false)} onSaved={() => { setEditing(false); void query.refetch(); bump(); onChanged(); }} />
+      </FormSheet>
+      <FormSheet open={addingPerson} onOpenChange={setAddingPerson} title={`Add a person at ${name}`} description="They are linked to this company by its domain.">
+        <RecordForm entity="contact" defaults={company.domain ? { company_domain: company.domain } : undefined} onCancel={() => setAddingPerson(false)}
+          onSaved={() => { setAddingPerson(false); setPeopleKey((k) => k + 1); bump(); onChanged(); void query.refetch(); }}
+          onDuplicate={() => setAddingPerson(false)} />
+      </FormSheet>
+      <ConfirmSpendDialog open={confirm} tier="destructive" title={`Delete ${name}`} description="Its contacts stay but lose the company link." affected={1}
+        confirming={remove.loading} onConfirm={() => void remove.mutate(undefined)} onCancel={() => setConfirm(false)} />
+    </>
+  );
+}

package/blocks/crm/components/company-detail.tsx

@@ -21,7 +21,7 @@ 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 { g8Delete, g8Get } from "@/g8/lib/g8-client";
-import { initials, location } from "../lib/crm-types";
+import { companyName, initials, location } from "../lib/crm-types";
 import type { CompanyRecord, ContactRecord } from "../lib/crm-types";
 import { ActivityTimeline } from "./activity-timeline";
 import { ContactTable } from "./contact-table";
@@ -52,21 +52,23 @@ export function CompanyDetail({ companyId, onDeleted, onOpenContact, renderActio
   const [editing, setEditing] = useState(false);
   const [confirmDelete, setConfirmDelete] = useState(false);
   const [feedKey, setFeedKey] = useState(0);
-  const query = useG8Query((signal) => g8Get<CompanyRecord>(`/companies/${companyId}`, { include_custom_fields: true }, { signal }), [companyId]);
-  const remove = useG8Mutation(() => g8Delete(`/companies/${companyId}`), { onSuccess: () => { setConfirmDelete(false); onDeleted?.(companyId); } });
+  const query = useG8Query((signal) => g8Get<CompanyRecord>(`/companies/${companyId}`, { include_custom_fields: true }, { signal }), [companyId], { key: ["companies", "detail", companyId] });
+  const remove = useG8Mutation(() => g8Delete(`/companies/${companyId}`), { invalidates: [["companies", "list"]], onSuccess: () => { setConfirmDelete(false); onDeleted?.(companyId); } });
   const bump = () => setFeedKey((k) => k + 1);
 
-  if (query.loading && !query.data) return <div className={`flex flex-col gap-3 ${className ?? ""}`}><Skeleton className="h-16 w-full" /><Skeleton className="h-40 w-full" /></div>;
-  if (query.error && !query.data) return <ApiError error={query.error} title="Could not load this company" onRetry={() => void query.refetch()} />;
+  // The hook keeps the previous record's data while the next one loads: show THIS record only (edit, delete and tabs all act on companyId).
+  const wrongRecord = query.data != null && String(query.data.data?.id) !== String(companyId);
+  if (query.error && (!query.data || wrongRecord)) return <ApiError error={query.error} title="Could not load this company" onRetry={() => void query.refetch()} />;
+  if ((query.loading && !query.data) || wrongRecord) return <div className={`flex flex-col gap-3 ${className ?? ""}`}><Skeleton className="h-16 w-full" /><Skeleton className="h-40 w-full" /></div>;
   const company = query.data!.data;
-  const name = company.name || company.domain || "Unnamed company";
+  const name = companyName(company);
 
   return (
     <div className={`flex flex-col gap-4 ${className ?? ""}`}>
       <header className="flex flex-wrap items-center gap-3">
-        <div aria-hidden className="flex size-12 items-center justify-center rounded-md bg-muted text-sm font-semibold">{initials(name)}</div>
+        <div aria-hidden className="flex size-12 items-center justify-center rounded-md bg-muted text-sm font-medium">{initials(name)}</div>
         <div className="min-w-0 flex-1">
-          <h2 className="truncate text-lg font-semibold">{name}</h2>
+          <h2 className="truncate text-lg font-medium">{name}</h2>
           <p className="truncate text-sm text-muted-foreground">{[company.domain, company.industry].filter(Boolean).join(" - ") || "No domain or industry"}</p>
         </div>
         <div className="flex flex-wrap items-center gap-2">

package/blocks/crm/components/company-table.tsx

@@ -17,11 +17,14 @@ import { ApiError } from "@/g8/components/api-error";
 import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
 import { EmptyState } from "@/g8/components/empty-state";
 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 { g8Delete, g8Get } from "@/g8/lib/g8-client";
 import { useCustomFields } from "../hooks/use-custom-fields";
 import { useDebouncedValue } from "../hooks/use-debounced";
 import { usePageQuery } from "../hooks/use-page-query";
-import { errorStatus, fieldLabel, location } from "../lib/crm-types";
+import { companyName, errorStatus, fieldLabel, location } from "../lib/crm-types";
 import type { CompanyRecord } from "../lib/crm-types";
 
 export interface CompanyFilters {
@@ -32,6 +35,8 @@ export interface CompanyFilters {
 }
 
 export interface CompanyTableProps {
+  /** URL param the host screen reads for this record type. With it the name is a real link (Cmd-click opens it in a new tab); without it a plain button. */
+  linkParam?: string;
   pageSize?: number;
   initialFilters?: CompanyFilters;
   selectable?: boolean;
@@ -57,6 +62,7 @@ export function CompanyTable(props: CompanyTableProps) {
     (page, signal) => g8Get<CompanyRecord[]>("/companies", { page, limit: pageSize, include_custom_fields: customFields || undefined, ...filters }, { signal }),
     [filters, customFields, props.refreshKey],
     pageSize,
+    ["companies", "list", "table"],
   );
 
   const ids = useMemo(() => [...selected.keys()], [selected]);
@@ -89,6 +95,7 @@ export function CompanyTable(props: CompanyTableProps) {
     const gone = toDelete.filter((_, i) => results[i].status === "fulfilled" || errorStatus((results[i] as PromiseRejectedResult).reason) === 404);
     return { gone, total: toDelete.length };
   }, {
+    invalidates: [["companies", "list"]],
     onSuccess: ({ gone, total }) => {
       setConfirmOpen(false);
       const next = new Map(selected);
@@ -139,9 +146,9 @@ export function CompanyTable(props: CompanyTableProps) {
             {list.loading && list.rows.length === 0
               ? Array.from({ length: 5 }, (_, i) => <TableRow key={`sk${i}`}><TableCell colSpan={5 + columns.length + (selectable ? 1 : 0)}><Skeleton className="h-5 w-full" /></TableCell></TableRow>)
               : list.rows.map((row) => (
-                  <TableRow key={row.id} data-testid={`company-row-${row.id}`} className={onOpen ? "cursor-pointer" : undefined} onClick={() => onOpen?.(row)}>
+                  <TableRow key={row.id} data-testid={`company-row-${row.id}`} className={onOpen ? "cursor-pointer" : undefined} {...(onOpen ? rowActivationProps(() => onOpen(row)) : {})}>
                     {selectable ? <TableCell onClick={(e) => e.stopPropagation()}><input type="checkbox" aria-label={`Select ${row.name ?? row.domain}`} checked={selected.has(row.id)} onChange={() => toggle(row)} /></TableCell> : null}
-                    <TableCell className="font-medium">{row.name || row.domain || "Unnamed company"}</TableCell>
+                    <TableCell className="font-medium">{onOpen ? <RecordLink param={props.linkParam} id={row.id} onOpen={() => onOpen(row)}>{companyName(row)}</RecordLink> : companyName(row)}</TableCell>
                     <TableCell>{row.domain || "-"}</TableCell>
                     <TableCell>{row.industry || "-"}</TableCell>
                     <TableCell>{row.employee_count || "-"}</TableCell>
@@ -165,7 +172,7 @@ export function CompanyTable(props: CompanyTableProps) {
         </div>
       </div>
 
-      <ConfirmSpendDialog open={confirmOpen} tier="destructive" title={`Delete ${ids.length} compan${ids.length === 1 ? "y" : "ies"}`}
+      <ConfirmSpendDialog open={confirmOpen} tier="destructive" title={`Delete ${plural(ids.length, "company", "companies")}`}
         description="Their contacts stay, but lose the company link." affected={ids.length} confirming={remove.loading}
         onConfirm={() => void remove.mutate(ids)} onCancel={() => setConfirmOpen(false)} />
     </div>

package/blocks/crm/components/contact-detail.tsx

@@ -25,7 +25,7 @@ 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 { g8Delete, g8Get } from "@/g8/lib/g8-client";
-import { contactName, initials, isMasked, location } from "../lib/crm-types";
+import { contactName, contactSubtitle, initials, isMasked, location } from "../lib/crm-types";
 import type { ContactRecord } from "../lib/crm-types";
 import { ActivityTimeline } from "./activity-timeline";
 import { NotesPanel } from "./notes-panel";
@@ -58,25 +58,28 @@ export function ContactDetail({ contactId, onDeleted, onOpenCompany, renderActio
   const [editing, setEditing] = useState(false);
   const [confirmDelete, setConfirmDelete] = useState(false);
   const [feedKey, setFeedKey] = useState(0);
-  const query = useG8Query((signal) => g8Get<ContactRecord>(`/contacts/${contactId}`, { include_custom_fields: true }, { signal }), [contactId]);
+  const query = useG8Query((signal) => g8Get<ContactRecord>(`/contacts/${contactId}`, { include_custom_fields: true }, { signal }), [contactId], { key: ["contacts", "detail", contactId] });
   const remove = useG8Mutation(() => g8Delete(`/contacts/${contactId}`), {
+    invalidates: [["contacts", "list"]],
     onSuccess: () => { setConfirmDelete(false); onDeleted?.(contactId); },
   });
   const bump = () => setFeedKey((k) => k + 1);
 
-  if (query.loading && !query.data) return <div className={`flex flex-col gap-3 ${className ?? ""}`}><Skeleton className="h-16 w-full" /><Skeleton className="h-40 w-full" /></div>;
-  if (query.error && !query.data) return <ApiError error={query.error} title="Could not load this contact" onRetry={() => void query.refetch()} />;
+  // The hook keeps the previous record's data while the next one loads: show THIS record only (edit, delete and tabs all act on contactId).
+  const wrongRecord = query.data != null && String(query.data.data?.id) !== String(contactId);
+  if (query.error && (!query.data || wrongRecord)) return <ApiError error={query.error} title="Could not load this contact" onRetry={() => void query.refetch()} />;
+  if ((query.loading && !query.data) || wrongRecord) return <div className={`flex flex-col gap-3 ${className ?? ""}`}><Skeleton className="h-16 w-full" /><Skeleton className="h-40 w-full" /></div>;
   const contact = query.data!.data;
   const name = contactName(contact);
 
   return (
     <div className={`flex flex-col gap-4 ${className ?? ""}`}>
       <header className="flex flex-wrap items-center gap-3">
-        <div aria-hidden className="flex size-12 items-center justify-center rounded-full bg-muted text-sm font-semibold">{initials(name)}</div>
+        <div aria-hidden className="flex size-12 items-center justify-center rounded-full bg-muted text-sm font-medium">{initials(name)}</div>
         <div className="min-w-0 flex-1">
-          <h2 className="truncate text-lg font-semibold">{name}</h2>
+          <h2 className="truncate text-lg font-medium">{name}</h2>
           <p className="truncate text-sm text-muted-foreground">
-            {[contact.job_title, contact.company?.name].filter(Boolean).join(" at ") || "No title or company"}
+            {contactSubtitle(contact)}
           </p>
         </div>
         <div className="flex flex-wrap items-center gap-2">

package/blocks/crm/components/contact-lookup-link.tsx

@@ -0,0 +1,44 @@
+"use client";
+
+/**
+ * ContactLookupLink: "Open contact" for something that only knows a person's email (an inbox thread, a meeting
+ * attendee, a visitor). It looks the email up in your CRM and, when exactly one contact has it, shows a button that
+ * calls `onOpen(contactId)` (route to your contacts screen: `router.push("/contacts?id=" + id)`). When nobody has that
+ * email it renders nothing, so a thread from a stranger gets no dead button.
+ *
+ * SDK operations, in order:
+ *   1. listContacts  GET /contacts?email=<email>&limit=2   (read)
+ * Nothing here is billable, external or destructive.
+ */
+
+import { Button } from "@graph8/sdk/ui";
+import { UserRound } from "lucide-react";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Get } from "@/g8/lib/g8-client";
+
+export interface ContactLookupLinkProps {
+  /** The person's email. Nothing is looked up (and nothing rendered) without one. */
+  email?: string | null;
+  /** Called with the CRM contact id when the button is clicked. */
+  onOpen: (contactId: number) => void;
+  label?: string;
+  variant?: "default" | "outline" | "secondary" | "ghost";
+  size?: "default" | "sm";
+}
+
+export function ContactLookupLink({ email, onOpen, label = "Open contact", variant = "outline", size = "sm" }: ContactLookupLinkProps) {
+  const address = email?.trim().toLowerCase() ?? "";
+  const q = useG8Query(
+    async (signal) => ((await g8Get<Array<{ id: number; work_email?: string | null }>>("/contacts", { email: address, limit: 2, page: 1 }, { signal })).data ?? []),
+    [address],
+    { enabled: address.includes("@"), key: ["contacts", "by-email", address] },
+  );
+  const match = (q.data ?? []).find((c) => !c.work_email || c.work_email.toLowerCase() === address);
+  if (!address || !match) return null;
+  return (
+    <Button size={size} variant={variant} onClick={() => onOpen(match.id)}>
+      <UserRound className="mr-1 size-4" aria-hidden />
+      {label}
+    </Button>
+  );
+}

package/blocks/crm/components/contact-table.tsx

@@ -20,6 +20,9 @@ import { ApiError } from "@/g8/components/api-error";
 import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
 import { EmptyState } from "@/g8/components/empty-state";
 import { g8Delete, g8Get } from "@/g8/lib/g8-client";
+import { rowActivationProps } from "@/g8/hooks/use-row-activation";
+import { RecordLink } from "@/g8/components/screen/record-link";
+import { plural } from "@/g8/lib/plural";
 import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
 import { useCustomFields } from "../hooks/use-custom-fields";
 import { useDebouncedValue } from "../hooks/use-debounced";
@@ -35,6 +38,8 @@ export interface ContactFilters {
 }
 
 export interface ContactTableProps {
+  /** URL param the host screen reads for this record type. With it the name is a real link (Cmd-click opens it in a new tab); without it a plain button. */
+  linkParam?: string;
   /** Only members of this list. */
   listId?: number;
   /** Only people of this company (mashup company id). */
@@ -82,6 +87,7 @@ export function ContactTable(props: ContactTableProps) {
       ),
     [listId, companyId, filters, customFields, props.refreshKey],
     pageSize,
+    ["contacts", "list", "table"],
   );
 
   const ids = useMemo(() => [...selected.keys()], [selected]);
@@ -117,6 +123,7 @@ export function ContactTable(props: ContactTableProps) {
     const gone = toDelete.filter((_, i) => results[i].status === "fulfilled" || errorStatus((results[i] as PromiseRejectedResult).reason) === 404);
     return { gone, total: toDelete.length };
   }, {
+    invalidates: [["contacts", "list"]],
     onSuccess: ({ gone, total }) => {
       setConfirmOpen(false);
       const next = new Map(selected);
@@ -172,13 +179,13 @@ export function ContactTable(props: ContactTableProps) {
                   <TableRow key={`sk${i}`}><TableCell colSpan={5 + columns.length + (selectable ? 1 : 0)}><Skeleton className="h-5 w-full" /></TableCell></TableRow>
                 ))
               : list.rows.map((row) => (
-                  <TableRow key={row.id} data-testid={`contact-row-${row.id}`} className={onOpen ? "cursor-pointer" : undefined} onClick={() => onOpen?.(row)}>
+                  <TableRow key={row.id} data-testid={`contact-row-${row.id}`} className={onOpen ? "cursor-pointer" : undefined} {...(onOpen ? rowActivationProps(() => onOpen(row)) : {})}>
                     {selectable ? (
                       <TableCell onClick={(e) => e.stopPropagation()}>
                         <input type="checkbox" aria-label={`Select ${contactName(row)}`} checked={selected.has(row.id)} onChange={() => toggle(row)} />
                       </TableCell>
                     ) : null}
-                    <TableCell className="font-medium">{contactName(row)}</TableCell>
+                    <TableCell className="font-medium">{onOpen ? <RecordLink param={props.linkParam} id={row.id} onOpen={() => onOpen(row)}>{contactName(row)}</RecordLink> : contactName(row)}</TableCell>
                     <TableCell><CellValue value={row.job_title} /></TableCell>
                     <TableCell><CellValue value={row.company_name} /></TableCell>
                     <TableCell><CellValue value={row.work_email} /></TableCell>
@@ -205,7 +212,7 @@ export function ContactTable(props: ContactTableProps) {
       <ConfirmSpendDialog
         open={confirmOpen}
         tier="destructive"
-        title={`Delete ${ids.length} contact${ids.length === 1 ? "" : "s"}`}
+        title={`Delete ${plural(ids.length, "contact")}`}
         description="They are removed from every list and sequence."
         affected={ids.length}
         confirming={remove.loading}