@graph8/sdk 0.361.0 → 0.370.0

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

@@ -0,0 +1,379 @@
+"use client";
+
+/**
+ * TasksScreen: every task in the workspace in one place, the work queue behind the per-record TaskList.
+ * No props are required.
+ *
+ * Composes: ScreenLayout (with Open / Completed / All tabs), StatStrip, Toolbar, SplitView, DetailPanel, FormSheet
+ * (screen kit). It is the only crm screen that lists tasks across records.
+ *
+ * Flows: switch Open / Completed / All - search by title - filter by priority, type and linked record type - page through
+ * results - tick a task to complete or reopen it - open a task (deep link ?id=, full page with &view=full) to read, edit or delete it - create a task
+ * (standalone, or linked to a record with `defaultRecord`) - complete or delete many at once ("N of M" report, 404 =
+ * already gone) - jump to the linked contact or company through `onOpenRecord`.
+ *
+ * SDK operations: none of its own. listAllTasks and getTask are `read`; createGlobalTask and updateTask are `write`;
+ * deleteTask (detail and bulk) is `destructive` and goes through ConfirmSpendDialog. Priority: 1 high, 2 medium, 3 low, 0 none.
+ * Due dates are sent as YYYY-MM-DD and shown in UTC so a date never shifts a day.
+ */
+
+import { useEffect, useState } from "react";
+import type { FormEvent, ReactNode } from "react";
+import { Button, Input, Label, Skeleton, Table, TableBody, TableCell, TableHead, TableHeader, TableRow, Textarea } from "@graph8/sdk/ui";
+import { CheckCheck, CheckSquare, Plus, Trash2 } 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 { 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 { g8Delete, g8Get, g8Patch, g8Post } from "@/g8/lib/g8-client";
+import { useDebouncedValue } from "../hooks/use-debounced";
+import { usePageQuery } from "../hooks/use-page-query";
+import { errorStatus } from "../lib/crm-types";
+import { Pager, formatDay, useBulkDelete, useRowSelection } from "../lib/screen-parts";
+import type { TaskItem } from "./task-list";
+
+/** The fields TasksScreen reads from a task; the API may send more. */
+export interface WorkspaceTask extends TaskItem {
+  task_type?: string | null;
+  entity_type?: string | null;
+  entity_id?: string | null;
+  entity_label?: string | null;
+  created_at?: string | null;
+}
+
+export interface TasksScreenProps {
+  pageSize?: number;
+  /** Which tab opens first. Default "open". */
+  initialStatus?: "open" | "completed" | "all";
+  /** New tasks are linked to this record (for example when the screen sits on a contact page). */
+  defaultRecord?: { entity_type: "contact" | "company" | "deal"; entity_id: string };
+  /** Called to open the linked record of a task ("Open contact"). Without it the link is plain text. */
+  onOpenRecord?: (record: { entity_type: string; entity_id: string }) => void;
+  renderRowActions?: (task: WorkspaceTask) => ReactNode;
+  renderDetailActions?: (task: WorkspaceTask) => ReactNode;
+  toolbarActions?: ReactNode;
+  className?: string;
+}
+
+const PRIORITY: Record<number, string> = { 1: "High", 2: "Medium", 3: "Low", 4: "Low" };
+const TASK_TYPES = ["call", "email", "meeting", "todo"];
+const ENTITY_TYPES = ["contact", "company", "deal"];
+type Tab = "open" | "completed" | "all";
+
+function ymd(date = new Date()): string {
+  return `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, "0")}-${String(date.getDate()).padStart(2, "0")}`;
+}
+const isOverdue = (t: WorkspaceTask): boolean => t.status !== "completed" && Boolean(t.due_date) && t.due_date!.slice(0, 10) < ymd();
+/** `pagination.total` of a list answer (the typed envelope only declares the cursor fields). */
+const totalOf = (res?: { pagination?: unknown }): number | undefined => (res?.pagination as { total?: number } | undefined)?.total;
+const label = (s: string): string => s.charAt(0).toUpperCase() + s.slice(1);
+
+function PriorityPill({ priority }: { priority?: number | null }) {
+  if (!priority) return <span className="text-muted-foreground">-</span>;
+  return <StatusPill tone={priority === 1 ? "negative" : priority === 2 ? "warning" : "neutral"}>{PRIORITY[priority] ?? "Low"}</StatusPill>;
+}
+
+export function TasksScreen(props: TasksScreenProps) {
+  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 openId = idParam || null;
+  const [tab, setTab] = useState<Tab>(props.initialStatus ?? "open");
+  const [search, setSearch] = useState("");
+  const [priority, setPriority] = useState("");
+  const [taskType, setTaskType] = useState("");
+  const [entityType, setEntityType] = useState(props.defaultRecord?.entity_type ?? "");
+  const q = useDebouncedValue(search);
+  const [sheet, setSheet] = useState<"new" | "edit" | null>(null);
+  const [confirmDelete, setConfirmDelete] = useState(false);
+  const [note, setNote] = useState<string | null>(null);
+
+  const scope = { status: tab === "all" ? undefined : tab, search: q || undefined, priority: priority || undefined, task_type: taskType || undefined, entity_type: entityType || undefined, entity_id: props.defaultRecord?.entity_id };
+  const list = usePageQuery<WorkspaceTask>(
+    (page, signal) => g8Get<WorkspaceTask[]>("/tasks", { limit: pageSize, offset: (page - 1) * pageSize, ...scope }, { signal }),
+    [scope.status, scope.search, scope.priority, scope.task_type, scope.entity_type, scope.entity_id],
+    pageSize,
+    ["tasks", "list", "screen"],
+  );
+  const recordScope = { entity_type: props.defaultRecord?.entity_type, entity_id: props.defaultRecord?.entity_id };
+  const openCount = useG8Query((signal) => g8Get<WorkspaceTask[]>("/tasks", { status: "open", limit: 1, ...recordScope }, { signal }), [recordScope.entity_type, recordScope.entity_id], { key: ["tasks", "count", "open", recordScope] });
+  const doneCount = useG8Query((signal) => g8Get<WorkspaceTask[]>("/tasks", { status: "completed", limit: 1, ...recordScope }, { signal }), [recordScope.entity_type, recordScope.entity_id], { key: ["tasks", "count", "completed", recordScope] });
+  const selection = useRowSelection<WorkspaceTask>(JSON.stringify(scope));
+  const reload = () => { void list.refetch(); void openCount.refetch(); void doneCount.refetch(); };
+  const hasFilters = Boolean(search || priority || taskType || entityType);
+  const overdue = list.rows.filter(isOverdue).length;
+
+  const toggle = useG8Mutation((t: WorkspaceTask) => g8Patch(`/tasks/${t.id}`, { status: t.status === "completed" ? "open" : "completed" }), { invalidates: ["tasks"], onSuccess: reload });
+  const completeMany = useG8Mutation(async (ids: string[]) => {
+    const results = await Promise.allSettled(ids.map((id) => g8Patch(`/tasks/${id}`, { status: "completed" })));
+    return { done: ids.filter((_, i) => results[i].status === "fulfilled"), total: ids.length };
+  }, { invalidates: ["tasks"], onSuccess: ({ done, total }) => { selection.drop(done); setNote(done.length < total ? `Completed ${done.length} of ${total}. ${total - done.length} could not be updated; they are still selected.` : null); reload(); } });
+  const bulk = useBulkDelete<string>("/tasks", (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 && gone.includes(openId)) setIdParam(null);
+    reload();
+  });
+  useEffect(() => { setNote(null); }, [tab, q, priority, taskType, entityType]);
+  const allOnPage = list.rows.length > 0 && list.rows.every((r) => selection.selected.has(r.id));
+
+  return (
+    <ScreenLayout
+      className={props.className}
+      title="Tasks"
+      description="Follow-ups across every contact and company, so nothing slips."
+      icon={<CheckSquare className="size-5" aria-hidden />}
+      actions={<>{props.toolbarActions}<Button size="sm" onClick={() => setSheet("new")}><Plus className="size-4" aria-hidden />New task</Button></>}
+      tabs={[
+        { id: "open", label: "Open", count: totalOf(openCount.data) },
+        { id: "completed", label: "Completed", count: totalOf(doneCount.data) },
+        { id: "all", label: "All" },
+      ]}
+      activeTab={tab}
+      onTabChange={(id) => setTab(id as Tab)}
+      stats={[
+        { label: "Open", value: totalOf(openCount.data) ?? "-" },
+        { label: "Completed", value: totalOf(doneCount.data) ?? "-" },
+        { label: "Overdue on this page", value: overdue, tone: overdue ? "negative" : "neutral", hint: "Open tasks past their due date" },
+      ]}
+    >
+      <SplitView
+        detailOpen={openId != null}
+        expanded={full}
+        onExpandedChange={(e) => setView(e ? "full" : null)}
+        onCloseDetail={() => setIdParam(null)}
+        detailWidth="md"
+        list={
+          <div className="flex flex-col gap-3">
+            <Toolbar
+              search={{ value: search, onChange: setSearch, placeholder: "Search tasks by title" }}
+              filters={
+                <>
+                  <select aria-label="Filter by priority" className="h-9 rounded-md border bg-background px-2 text-sm" value={priority} onChange={(e) => setPriority(e.target.value)}>
+                    <option value="">Any priority</option><option value="1">High</option><option value="2">Medium</option><option value="3">Low</option>
+                  </select>
+                  <select aria-label="Filter by type" className="h-9 rounded-md border bg-background px-2 text-sm" value={taskType} onChange={(e) => setTaskType(e.target.value)}>
+                    <option value="">Any type</option>{TASK_TYPES.map((t) => <option key={t} value={t}>{label(t)}</option>)}
+                  </select>
+                  {props.defaultRecord ? null : (
+                    <select aria-label="Filter by linked record" className="h-9 rounded-md border bg-background px-2 text-sm" value={entityType} onChange={(e) => setEntityType(e.target.value)}>
+                      <option value="">Any record</option>{ENTITY_TYPES.map((t) => <option key={t} value={t}>{label(t)}</option>)}
+                    </select>
+                  )}
+                  {hasFilters ? <Button variant="ghost" size="sm" onClick={() => { setSearch(""); setPriority(""); setTaskType(""); setEntityType(props.defaultRecord?.entity_type ?? ""); }}>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>
+                <Button variant="outline" size="sm" loading={completeMany.loading} onClick={() => void completeMany.mutate(selection.ids)}><CheckCheck className="size-4" aria-hidden />Complete {selection.ids.length}</Button>
+                <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 tasks" onRetry={() => void list.refetch()} /> : null}
+            {toggle.error ? <ApiError error={toggle.error} title="Could not update the task" /> : 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(list.rows)} /></TableHead>
+                    <TableHead className="w-8"><span className="sr-only">Done</span></TableHead>
+                    <TableHead>Task</TableHead>
+                    <TableHead>Linked to</TableHead>
+                    <TableHead>Due</TableHead>
+                    <TableHead>Priority</TableHead>
+                    <TableHead>Assignee</TableHead>
+                    {props.renderRowActions ? <TableHead className="w-8"><span className="sr-only">Actions</span></TableHead> : null}
+                  </TableRow>
+                </TableHeader>
+                <TableBody>
+                  {list.loading && list.rows.length === 0
+                    ? Array.from({ length: 6 }, (_, i) => <TableRow key={`sk${i}`}><TableCell colSpan={7 + (props.renderRowActions ? 1 : 0)}><Skeleton className="h-6 w-full" /></TableCell></TableRow>)
+                    : list.rows.map((t) => {
+                        const done = t.status === "completed";
+                        return (
+                          <TableRow key={t.id} data-testid={`task-row-${t.id}`} data-state={t.id === openId ? "selected" : undefined} className="cursor-pointer" {...rowActivationProps(() => setIdParam(t.id))}>
+                            <TableCell onClick={(e) => e.stopPropagation()}><input type="checkbox" aria-label={`Select ${t.title}`} checked={selection.selected.has(t.id)} onChange={() => selection.toggle(t)} /></TableCell>
+                            <TableCell onClick={(e) => e.stopPropagation()}><input type="checkbox" aria-label={`${done ? "Reopen" : "Complete"} ${t.title}`} checked={done} onChange={() => void toggle.mutate(t)} /></TableCell>
+                            <TableCell className={done ? "text-muted-foreground line-through" : "font-medium"}><RecordLink param="id" id={t.id} onOpen={() => setIdParam(t.id)}>{t.title}</RecordLink></TableCell>
+                            <TableCell>{t.entity_label ? <span>{t.entity_label}{t.entity_type ? <span className="ml-1 text-xs text-muted-foreground">{label(t.entity_type)}</span> : null}</span> : <span className="text-muted-foreground">-</span>}</TableCell>
+                            <TableCell className="whitespace-nowrap">{t.due_date ? <span className={isOverdue(t) ? "text-destructive" : undefined}>{formatDay(t.due_date)}{isOverdue(t) ? " (overdue)" : ""}</span> : <span className="text-muted-foreground">-</span>}</TableCell>
+                            <TableCell><PriorityPill priority={t.priority} /></TableCell>
+                            <TableCell>{t.assignee_name || <span className="text-muted-foreground">-</span>}</TableCell>
+                            {props.renderRowActions ? <TableCell onClick={(e) => e.stopPropagation()}>{props.renderRowActions(t)}</TableCell> : null}
+                          </TableRow>
+                        );
+                      })}
+                </TableBody>
+              </Table>
+              {!list.loading && !list.error && list.rows.length === 0 ? (
+                <EmptyState
+                  title={hasFilters ? "No tasks match these filters" : tab === "completed" ? "Nothing completed yet" : "No tasks yet"}
+                  description={hasFilters ? "Try fewer filters." : "Add a follow-up so nothing slips."}
+                  action={hasFilters ? undefined : <Button onClick={() => setSheet("new")}>New task</Button>}
+                />
+              ) : null}
+              <Pager page={list.page} pageCount={list.pageCount} total={list.total} noun="tasks" hasNext={list.hasNext} loading={list.loading} onPage={list.setPage} />
+            </div>
+          </div>
+        }
+        detail={openId ? (
+          <TaskPanel key={openId} full={full} setFull={(v) => setView(v ? "full" : null)} taskId={openId} onClose={() => setIdParam(null)} onChanged={reload} onDeleted={() => { setIdParam(null); reload(); }}
+            onEdit={() => setSheet("edit")} sheetEditing={sheet === "edit"} onCloseEdit={() => setSheet(null)}
+            onOpenRecord={props.onOpenRecord} renderActions={props.renderDetailActions} />
+        ) : null}
+      />
+
+      <FormSheet open={sheet === "new"} onOpenChange={(o) => setSheet(o ? "new" : null)} title="New task" description={props.defaultRecord ? `Linked to this ${props.defaultRecord.entity_type}.` : "A standalone follow-up."}>
+        <TaskForm record={props.defaultRecord} onCancel={() => setSheet(null)} onSaved={(t) => { setSheet(null); reload(); if (t?.id) setIdParam(t.id); }} />
+      </FormSheet>
+
+      <ConfirmSpendDialog open={confirmDelete} tier="destructive" title={`Delete ${plural(selection.ids.length, "task")}`} description="They are removed for everyone." affected={selection.ids.length}
+        confirming={bulk.loading} onConfirm={() => void bulk.mutate(selection.ids)} onCancel={() => setConfirmDelete(false)} />
+    </ScreenLayout>
+  );
+}
+
+interface TaskPanelProps {
+  full: boolean;
+  setFull: (full: boolean) => void;
+  taskId: string;
+  onClose: () => void;
+  onChanged: () => void;
+  onDeleted: () => void;
+  onEdit: () => void;
+  sheetEditing: boolean;
+  onCloseEdit: () => void;
+  onOpenRecord?: TasksScreenProps["onOpenRecord"];
+  renderActions?: TasksScreenProps["renderDetailActions"];
+}
+
+function TaskPanel({ full, setFull, taskId, onClose, onChanged, onDeleted, onEdit, sheetEditing, onCloseEdit, onOpenRecord, renderActions }: TaskPanelProps) {
+  const [confirm, setConfirm] = useState(false);
+  const query = useG8Query((signal) => g8Get<WorkspaceTask>(`/tasks/${taskId}`, {}, { signal }), [taskId], { key: ["tasks", "detail", taskId] });
+  const toggle = useG8Mutation((t: WorkspaceTask) => g8Patch(`/tasks/${t.id}`, { status: t.status === "completed" ? "open" : "completed" }), { invalidates: ["tasks"], onSuccess: () => { void query.refetch(); onChanged(); } });
+  const remove = useG8Mutation(async () => {
+    try { await g8Delete(`/tasks/${taskId}`); } catch (e) { if (errorStatus(e) !== 404) throw e; }
+  }, { invalidates: [["tasks", "list"], ["tasks", "count"], ["tasks", "record"]], onSuccess: () => { setConfirm(false); onDeleted(); } });
+
+  if (query.loading && !query.data) return <div className="flex flex-col gap-3 p-4"><Skeleton className="h-14 w-full" /><Skeleton className="h-32 w-full" /></div>;
+  if (query.error && !query.data) return <div className="p-4"><ApiError error={query.error} title="Could not load this task" onRetry={() => void query.refetch()} /></div>;
+  const task = query.data!.data;
+  const done = task.status === "completed";
+  const dash = <span className="text-muted-foreground">-</span>;
+
+  return (
+    <>
+      <DetailPanel
+        title={task.title}
+        subtitle={task.entity_label ? `${task.entity_type ? label(task.entity_type) + ": " : ""}${task.entity_label}` : "Standalone task"}
+        badges={<StatusPill tone={done ? "positive" : isOverdue(task) ? "negative" : "info"} dot>{done ? "Completed" : isOverdue(task) ? "Overdue" : "Open"}</StatusPill>}
+        onClose={onClose}
+        onExpand={full ? undefined : () => setFull(true)}
+        onCollapse={full ? () => setFull(false) : undefined}
+        actions={
+          <>
+            {renderActions?.(task)}
+            {task.entity_type && task.entity_id && onOpenRecord ? <Button variant="outline" size="sm" onClick={() => onOpenRecord({ entity_type: task.entity_type!, entity_id: task.entity_id! })}>Open {task.entity_type}</Button> : null}
+            <Button variant="outline" size="sm" loading={toggle.loading} onClick={() => void toggle.mutate(task)}>{done ? "Reopen" : "Mark complete"}</Button>
+            <Button variant="outline" size="sm" onClick={onEdit}>Edit</Button>
+            <Button variant="destructive" size="sm" onClick={() => setConfirm(true)}>Delete</Button>
+          </>
+        }
+      >
+        <div className="flex flex-col gap-4 p-4">
+          {toggle.error ? <ApiError error={toggle.error} title="Could not update the task" /> : null}
+          {remove.error ? <ApiError error={remove.error} title="Could not delete the task" /> : null}
+          <KeyValueList columns={2} items={[
+            { label: "Due", value: task.due_date ? formatDay(task.due_date) : dash },
+            { label: "Priority", value: <PriorityPill priority={task.priority} /> },
+            { label: "Type", value: task.task_type ? label(task.task_type) : dash },
+            { label: "Assignee", value: task.assignee_name || dash },
+            { label: "Created", value: task.created_at ? formatDay(task.created_at) : dash },
+            ...(task.description ? [{ label: "Description", value: task.description }] : []),
+          ]} />
+        </div>
+      </DetailPanel>
+      <FormSheet open={sheetEditing} onOpenChange={(o) => { if (!o) onCloseEdit(); }} title="Edit task">
+        <TaskForm task={task} onCancel={onCloseEdit} onSaved={() => { onCloseEdit(); void query.refetch(); onChanged(); }} />
+      </FormSheet>
+      <ConfirmSpendDialog open={confirm} tier="destructive" title="Delete this task" description={task.title} affected={1}
+        confirming={remove.loading} onConfirm={() => void remove.mutate(undefined)} onCancel={() => setConfirm(false)} />
+    </>
+  );
+}
+
+interface TaskFormProps {
+  task?: WorkspaceTask;
+  record?: TasksScreenProps["defaultRecord"];
+  onSaved: (task?: WorkspaceTask) => void;
+  onCancel: () => void;
+}
+
+function TaskForm({ task, record, onSaved, onCancel }: TaskFormProps) {
+  const [title, setTitle] = useState(task?.title ?? "");
+  const [description, setDescription] = useState(task?.description ?? "");
+  const [due, setDue] = useState(task?.due_date ? task.due_date.slice(0, 10) : "");
+  const [priority, setPriority] = useState(String(task ? task.priority ?? 0 : 2));
+  const [taskType, setTaskType] = useState(task?.task_type ?? "");
+  const [error, setError] = useState<string | null>(null);
+  const save = useG8Mutation(async () => {
+    const body = { title: title.trim(), description: description.trim() || null, due_date: due || null, priority: Number(priority), task_type: taskType || null };
+    if (task) {
+      // An untouched priority is not sent, so editing a task without one never invents a priority.
+      const { priority: _skip, ...rest } = body;
+      const patch = Number(priority) === (task.priority ?? 0) ? rest : body;
+      return (await g8Patch<WorkspaceTask>(`/tasks/${task.id}`, patch)).data;
+    }
+    return (await g8Post<WorkspaceTask>("/tasks", { ...body, ...(record ? { entity_type: record.entity_type, entity_id: record.entity_id } : {}) })).data;
+  }, { invalidates: ["tasks"], onSuccess: (t) => onSaved(t) });
+  const submit = (e: FormEvent) => {
+    e.preventDefault();
+    if (!title.trim()) return setError("Give the task a title.");
+    setError(null);
+    void save.mutate(undefined);
+  };
+  return (
+    <form noValidate onSubmit={submit} className="flex flex-col gap-3" aria-label={task ? "Edit task" : "New task"}>
+      <div className="flex flex-col gap-1"><Label htmlFor="task-title">Title</Label><Input id="task-title" value={title} onChange={(e) => setTitle(e.target.value)} /></div>
+      <div className="flex flex-col gap-1"><Label htmlFor="task-desc">Description</Label><Textarea id="task-desc" rows={3} value={description} onChange={(e) => setDescription(e.target.value)} /></div>
+      <div className="grid grid-cols-1 gap-3 sm:grid-cols-3">
+        <div className="flex flex-col gap-1"><Label htmlFor="task-due">Due date</Label><Input id="task-due" type="date" value={due} onChange={(e) => setDue(e.target.value)} /></div>
+        <div className="flex flex-col gap-1"><Label htmlFor="task-priority">Priority</Label>
+          <select id="task-priority" className="h-9 rounded-md border bg-background px-2 text-sm" value={priority} onChange={(e) => setPriority(e.target.value)}>
+            <option value="1">High</option><option value="2">Medium</option><option value="3">Low</option><option value="0">None</option>
+          </select></div>
+        <div className="flex flex-col gap-1"><Label htmlFor="task-type">Type</Label>
+          <select id="task-type" className="h-9 rounded-md border bg-background px-2 text-sm" value={taskType} onChange={(e) => setTaskType(e.target.value)}>
+            <option value="">None</option>{TASK_TYPES.map((t) => <option key={t} value={t}>{label(t)}</option>)}
+          </select></div>
+      </div>
+      {error ? <p role="alert" className="text-sm text-destructive">{error}</p> : null}
+      {save.error ? <ApiError error={save.error} title="Could not save the task" /> : null}
+      <div className="flex justify-end gap-2">
+        <Button type="button" variant="ghost" onClick={onCancel}>Cancel</Button>
+        <Button type="submit" loading={save.loading}>{task ? "Save changes" : "Create task"}</Button>
+      </div>
+    </form>
+  );
+}

package/blocks/crm/hooks/use-custom-fields.ts

@@ -12,7 +12,12 @@ import type { CrmEntity, FieldDef } from "../lib/crm-types";
  */
 export function useCustomFields(entity: CrmEntity, listId?: number, enabled = true) {
   const path = entity === "contacts" ? "/fields" : "/fields/companies";
-  const query = useG8Query((signal) => g8Get<FieldDef[]>(path, { list_id: listId }, { signal }), [path, listId], { enabled });
+  const query = useG8Query((signal) => g8Get<FieldDef[]>(path, { list_id: listId }, { signal }), [path, listId], {
+    enabled,
+    // The schema rarely changes: share it between the table, the detail and the form, fresh for 30 s.
+    key: ["fields", entity, { listId }],
+    staleTime: 30_000,
+  });
   const all = (query.data?.data ?? []) as FieldDef[];
   return { fields: all.filter(isCustomField), all, loading: query.loading, error: query.error, refetch: query.refetch };
 }

package/blocks/crm/hooks/use-page-query.ts

@@ -3,6 +3,7 @@
 import { useState } from "react";
 import { useG8Query } from "@/g8/hooks/use-g8-query";
 import type { G8Envelope } from "@/g8/lib/g8-client";
+import type { G8QueryKey } from "@/g8/lib/g8-cache";
 import type { PageInfo } from "../lib/crm-types";
 
 export interface UsePageQueryResult<T> {
@@ -24,16 +25,21 @@ export interface UsePageQueryResult<T> {
  * have one, so the table keeps a page number instead.
  *
  * Changing `deps` (a filter, a search box) goes back to page 1 without a second request.
+ *
+ * Optional `cacheKey` joins the shared query cache (each page cached as `[...cacheKey, { page, deps }]`),
+ * so the list shows instantly when you come back and refreshes when a write invalidates its prefix.
  */
 export function usePageQuery<T>(
   fetchPage: (page: number, signal: AbortSignal) => Promise<G8Envelope<T[]>>,
   deps: readonly unknown[],
   pageSize = 25,
+  cacheKey?: readonly unknown[],
 ): UsePageQueryResult<T> {
   const key = JSON.stringify(deps);
   const [state, setState] = useState({ key, page: 1 });
   const page = state.key === key ? state.page : 1;
-  const query = useG8Query((signal) => fetchPage(page, signal), [key, page]);
+  const queryKey: G8QueryKey | undefined = cacheKey ? [...cacheKey, { page, pageSize, deps: key }] : undefined;
+  const query = useG8Query((signal) => fetchPage(page, signal), [key, page], { key: queryKey });
 
   const info = query.data?.pagination as Partial<PageInfo> | undefined;
   const rows = (query.data?.data ?? []) as T[];

package/blocks/crm/lib/crm-types.ts

@@ -102,9 +102,14 @@ export function isMasked(value: unknown): boolean {
   return typeof value === "string" && value.trim() === "***";
 }
 
-export function contactName(c: Pick<ContactRecord, "first_name" | "last_name" | "full_name" | "work_email">): string {
+export function contactName(c: Pick<ContactRecord, "first_name" | "last_name" | "full_name" | "work_email"> & { id?: number | string }): string {
   const joined = [c.first_name, c.last_name].filter(Boolean).join(" ").trim();
-  return joined || c.full_name || (c.work_email && !isMasked(c.work_email) ? c.work_email : "") || "Unnamed contact";
+  return joined || c.full_name || (c.work_email && !isMasked(c.work_email) ? c.work_email : "") || (c.id != null ? `#${c.id}` : "-");
+}
+
+/** A company's display name: name, then domain, then `#id`, then a dash. Never "Unnamed". */
+export function companyName(c: { name?: string | null; domain?: string | null; id?: number | string }): string {
+  return c.name || c.domain || (c.id != null ? `#${c.id}` : "-");
 }
 
 export function initials(name: string): string {
@@ -134,3 +139,8 @@ export function errorDetail(error: unknown): Record<string, unknown> | undefined
   const detail = (error as { detail?: unknown } | null)?.detail;
   return detail && typeof detail === "object" && !Array.isArray(detail) ? (detail as Record<string, unknown>) : undefined;
 }
+
+/** Passed as the second argument to a screen's `renderRowActions` / `renderDetailActions`: reload what the screen shows (filters, page, sort and selection are kept). */
+export interface ScreenActionContext {
+  reload: () => void;
+}

package/blocks/crm/lib/screen-parts.tsx

@@ -0,0 +1,105 @@
+"use client";
+
+/**
+ * Small pieces shared by ContactsScreen, CompaniesScreen and TasksScreen: client-side sorting of the loaded
+ * page, a sortable table header, row selection that resets with the data source, the retry-safe bulk delete
+ * (Promise.allSettled, 404 = already gone, always refetch) and a pager. No operations of its own except the
+ * DELETE the caller names.
+ */
+
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { Button, TableHead } from "@graph8/sdk/ui";
+import { ArrowDown, ArrowUp, ChevronsUpDown } from "lucide-react";
+import { g8Delete } from "@/g8/lib/g8-client";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { errorStatus, isMasked } from "./crm-types";
+
+export type SortDir = "asc" | "desc";
+export interface SortState { key: string; dir: SortDir }
+
+/** Sort rows by a text accessor. Empty and locked values always go last. Sorts only what is loaded (the API has no sort). */
+export function sortRows<T>(rows: T[], sort: SortState | null, get: (row: T, key: string) => string | null | undefined): T[] {
+  if (!sort) return rows;
+  const sign = sort.dir === "asc" ? 1 : -1;
+  const norm = (r: T) => { const v = get(r, sort.key); return v == null || v === "" || isMasked(v) ? null : v.toLowerCase(); };
+  return [...rows].sort((a, b) => {
+    const x = norm(a), y = norm(b);
+    if (x === y) return 0;
+    if (x == null) return 1;
+    if (y == null) return -1;
+    return x < y ? -sign : sign;
+  });
+}
+
+export function useSort(initial: SortState | null = null) {
+  const [sort, setSort] = useState<SortState | null>(initial);
+  const toggle = useCallback((key: string) => setSort((s) => (s?.key !== key ? { key, dir: "asc" } : s.dir === "asc" ? { key, dir: "desc" } : null)), []);
+  return { sort, toggle };
+}
+
+export function SortHead({ label, sortKey, sort, onSort, className }: { label: string; sortKey: string; sort: SortState | null; onSort: (key: string) => void; className?: string }) {
+  const active = sort?.key === sortKey;
+  const Icon = !active ? ChevronsUpDown : sort.dir === "asc" ? ArrowUp : ArrowDown;
+  return (
+    <TableHead className={className} aria-sort={active ? (sort.dir === "asc" ? "ascending" : "descending") : "none"}>
+      <button type="button" className="inline-flex items-center gap-1 font-medium hover:text-foreground" onClick={() => onSort(sortKey)}>
+        {label}<Icon className={`size-3.5 ${active ? "text-foreground" : "text-muted-foreground"}`} aria-hidden />
+      </button>
+    </TableHead>
+  );
+}
+
+/** Selected rows keyed by id. Clears itself when `scope` changes (another filter, list or reload). */
+export function useRowSelection<T extends { id: number | string }>(scope: string) {
+  const [selected, setSelected] = useState<Map<T["id"], T>>(new Map());
+  const last = useRef(scope);
+  useEffect(() => {
+    if (last.current === scope) return;
+    last.current = scope;
+    setSelected(new Map());
+  }, [scope]);
+  const toggle = (row: T) => setSelected((m) => { const n = new Map(m); if (!n.delete(row.id)) n.set(row.id, row); return n; });
+  const togglePage = (rows: T[]) => setSelected((m) => {
+    const n = new Map(m);
+    const all = rows.length > 0 && rows.every((r) => n.has(r.id));
+    for (const r of rows) all ? n.delete(r.id) : n.set(r.id, r);
+    return n;
+  });
+  const drop = (ids: Array<T["id"]>) => setSelected((m) => { const n = new Map(m); ids.forEach((id) => n.delete(id)); return n; });
+  const clear = () => setSelected(new Map());
+  const ids = useMemo(() => [...selected.keys()], [selected]);
+  return { selected, ids, rows: [...selected.values()], toggle, togglePage, drop, clear };
+}
+
+/** Deletes every id under `basePath` (`/contacts`). A 404 counts as done; never throws; `onSettled` gets who is gone. */
+export function useBulkDelete<Id extends number | string = number>(basePath: string, onSettled: (gone: Id[], total: number) => void) {
+  return useG8Mutation(async (ids: Id[]) => {
+    const results = await Promise.allSettled(ids.map((id) => g8Delete(`${basePath}/${id}`)));
+    const gone = ids.filter((_, i) => results[i].status === "fulfilled" || errorStatus((results[i] as PromiseRejectedResult).reason) === 404);
+    return { gone, total: ids.length };
+  }, {
+    // `/contacts` -> every cached contacts list and count refreshes (a deleted record's detail is left alone).
+    invalidates: [[basePath.split("/")[1], "list"], [basePath.split("/")[1], "count"], [basePath.split("/")[1], "record"]],
+    onSuccess: ({ gone, total }) => onSettled(gone, total),
+  });
+}
+
+export function Pager({ page, pageCount, total, noun, hasNext, loading, onPage }: { page: number; pageCount: number; total: number; noun: string; hasNext: boolean; loading: boolean; onPage: (p: number) => void }) {
+  return (
+    <div className="flex items-center justify-between border-t px-3 py-2 text-sm text-muted-foreground">
+      <span className="tabular-nums">{total.toLocaleString()} {noun}</span>
+      <div className="flex items-center gap-2">
+        <Button variant="outline" size="sm" disabled={page <= 1 || loading} onClick={() => onPage(page - 1)}>Previous</Button>
+        <span className="tabular-nums">Page {page} of {pageCount}</span>
+        <Button variant="outline" size="sm" disabled={!hasNext || loading} onClick={() => onPage(page + 1)}>Next</Button>
+      </div>
+    </div>
+  );
+}
+
+/** Date-only or timestamp to a short UTC date, so a `2026-10-15` due date never shifts a day. */
+export function formatDay(value?: string | null): string {
+  if (!value) return "";
+  const d = new Date(value.length === 10 ? `${value}T00:00:00Z` : value);
+  return Number.isNaN(d.getTime()) ? "" : d.toLocaleDateString(undefined, { timeZone: "UTC", month: "short", day: "numeric", year: "numeric" });
+}

package/blocks/deals/README.md

@@ -4,6 +4,29 @@ A kanban of deals by stage with drag and drop, a deal detail with history, a sta
 Install with `npx @graph8/sdk add deals` (depends on `crm`, whose notes, tasks and activity timeline you can
 compose under `DealDetail`'s `children`). Drag and drop needs `npm i @dnd-kit/core`.
 
+## Screens
+
+`DealsScreen` (`components/deals-screen.tsx`) is the finished product; mount it on a route with no props:
+`<DealsScreen />`. Everything below is reachable from it, no extra code.
+
+- Board and List views, search by name, a pipeline switcher when there is more than one pipeline.
+- Headline numbers: open deals, open value, estimated weighted value, won value.
+- Open a deal (board card or list row, deep link `?id=<deal id>`): Details (edit, stage history, confirmed delete) and
+  Activity tabs. Moving a card into a won or lost stage asks for the close date and amount first.
+- **New deal**: name, amount, close date, stage, an **owner** and **at least one contact**. The API requires both
+  (`owner_id`, and `contact_ids` with one or more mashup contact ids that all work at one company; the older note that
+  the list may be empty was wrong). A company that already has a deal is refused with 409 unless "Allow another deal"
+  is ticked.
+- Forecast tab (totals, win rate, stuck deals, estimated weighted pipeline) and Pipeline settings tab (stage names,
+  probabilities, won/lost types, order, delete).
+- Slots for cross-block glue, all optional: `renderRowActions(deal)`, `renderDetailActions(deal)`,
+  `extraDetailTabs`, `toolbarActions`. Example: add a Quotes tab with `<QuoteList dealId={deal.id} />`.
+
+Scopes the screen needs on top of the lists below: `team:read` (owner default and picker) and `contacts:read`
+(contact search). Proxy `allowedPrefixes` must include `deals`, `pipelines`, `team-members`, `contacts` (and `activity`
+for the timeline).
+
+
 ## The flow, in order
 
 1. **Pipelines** `GET /deals/pipelines` (`usePipelines`): `[{ id, name, is_default, stages: [{ id, name,
@@ -17,8 +40,8 @@ compose under `DealDetail`'s `children`). Drag and drop needs `npm i @dnd-kit/co
    won, and an owner. The board prompts for the date and amount first; if the API still answers 422 with
    `close_date_required_for_won_stage`, `amount_required_for_won_stage` or `owner_required_for_closed_stage`,
    the board shows what is missing and rolls back.
-5. **Create / edit** (`DealDetail`): `POST /deals` needs `name`, `owner_id` and `contact_ids` (a list, may be
-   empty); `stage_id` defaults to the first stage of the default pipeline. Edits send `expected_revision`;
+5. **Create / edit** (`DealDetail`): `POST /deals` needs `name`, `owner_id` and `contact_ids` (at least ONE mashup contact id;
+   all of them must work at the same company); `stage_id` defaults to the first stage of the default pipeline. Edits send `expected_revision`;
    a stale revision is refused, so reload and retry. `DELETE /deals/{id}` is destructive and confirmed.
 6. **Configure** (`StageEditor`): `GET /pipelines/{id}`, `POST .../stages`, `PUT .../stages/{stage_id}`,
    `PUT .../stages/reorder` (send every stage id in the new order), `DELETE .../stages/{stage_id}` (destructive,
@@ -40,7 +63,12 @@ create), `deal.id` + `deal.revision` (card -> detail -> update/delete).
 
 - The board shows the default pipeline. Moves save immediately; no confirm dialog (nobody is contacted).
 - Every card has a "Move to" select, the keyboard and screen-reader path, doing the same PATCH as dragging.
-- Ask the human only who should **own deals created in the UI** (the API requires an owner).
+- **Deal owner.** graph8 requires an owner on create, so `DealsScreen` never asks: it defaults to the API key's own
+  user (`GET /team-members/me`, the roster record of the person who minted a personal key, using their identity-provider
+  user id and falling back to their email). An organisation key has no person (that route answers 403), so the owner
+  picker preselects the first active team member of `GET /team-members`. The person can change the owner in the picker
+  before saving. `DealDetail` alone still takes `ownerId` as a prop.
+- Nothing about deals needs to be asked of the human. If the product has its own user model, pass that user's graph8 id as `ownerId` instead.
 
 ## Gotchas
 
@@ -70,6 +98,9 @@ create), `deal.id` + `deal.revision` (card -> detail -> update/delete).
 | `cliPipelines.deleteStage` | DELETE /pipelines/{id}/stages/{stage_id} | destructive | StageEditor |
 | `deals.getDealAnalytics` | GET /deals/analytics | read | ForecastView |
 | `deals.getDealStageVelocity` | GET /deals/stage-velocity | read | ForecastView |
+| `teamMembers.getMyTeamMember` | GET /team-members/me | read | useDefaultOwner (DealsScreen) |
+| `teamMembers.listTeamMembers` | GET /team-members | read | useDefaultOwner (DealsScreen) |
+| `contacts.listContacts` | GET /contacts | read | DealsScreen contact search |
 
 ## Recipes (server side)