@graph8/sdk 0.358.0 → 0.362.0

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)
 

package/blocks/deals/block.json

@@ -21,10 +21,14 @@
     "get_deal_analytics_deals_analytics_get",
     "get_deal_deals__deal_id__get",
     "get_deal_stage_velocity_deals_stage_velocity_get",
+    "get_my_team_member_team_members_me_get",
     "get_pipeline_pipelines__pipeline_id__get",
+    "list_contacts_contacts_get",
     "list_deal_history_deals__deal_id__history_get",
     "list_deals_deals_get",
     "list_pipelines_deals_pipelines_get",
+    "list_quotes_quotes_get",
+    "list_team_members_team_members_get",
     "reorder_stages_pipelines__pipeline_id__stages_reorder_put",
     "update_deal_deals__deal_id__patch",
     "update_stage_pipelines__pipeline_id__stages__stage_id__put"
@@ -92,6 +96,24 @@
       "tiers": [
         "read"
       ]
+    },
+    {
+      "name": "DealsScreen",
+      "file": "components/deals-screen.tsx",
+      "purpose": "Finished deals product: board and list, new deal with the owner defaulted to the API key user, deal detail with activity, forecast and pipeline settings.",
+      "operations": [],
+      "tiers": []
+    },
+    {
+      "name": "DealContactsTab",
+      "file": "components/deal-related.tsx",
+      "purpose": "A deal's contacts with roles; open one for the full CRM record. Also exports DealQuotesTab, a read-only list of the deal's quotes.",
+      "operations": [
+        "get_deal_deals__deal_id__get"
+      ],
+      "tiers": [
+        "read"
+      ]
     }
   ],
   "hooks": [
@@ -111,6 +133,15 @@
         "list_deals_deals_get",
         "update_deal_deals__deal_id__patch"
       ]
+    },
+    {
+      "name": "useDefaultOwner",
+      "file": "hooks/use-default-owner.ts",
+      "purpose": "The default deal owner: the API key user, else the first team member, plus the owner picker options.",
+      "operations": [
+        "get_my_team_member_team_members_me_get",
+        "list_team_members_team_members_get"
+      ]
     }
   ],
   "lib": [
@@ -160,9 +191,12 @@
     "campaigns:delete",
     "campaigns:read",
     "campaigns:write",
+    "contacts:read",
     "deals:delete",
     "deals:read",
-    "deals:write"
+    "deals:write",
+    "quotes:read",
+    "team:read"
   ],
   "defaults": [
     {
@@ -182,8 +216,8 @@
     },
     {
       "decision": "Who owns deals created in the UI",
-      "default": "The signed-in user of your app: pass their graph8 user id as ownerId (the API requires an owner)",
-      "askHuman": true
+      "default": "The API key's own user (GET /team-members/me). With an organisation key there is no person, so the first team member is preselected in an owner picker the person can change. Pass ownerId to DealDetail to override",
+      "askHuman": false
     },
     {
       "decision": "Weighted forecast",
@@ -193,6 +227,7 @@
   ],
   "peerDependencies": {
     "react": ">=18",
-    "@dnd-kit/core": "^6.3.1"
+    "@dnd-kit/core": "^6.3.1",
+    "lucide-react": ">=0.400.0"
   }
 }

package/blocks/deals/components/deal-detail.tsx

@@ -30,6 +30,8 @@ export interface DealDetailProps {
   /** Create mode: contact ids to link (the API requires the list; it may be empty). */
   contactIds?: number[];
   pipelineId?: string;
+  /** Create mode: allow a second deal for a company that already has one (the API refuses it with 409 otherwise). */
+  allowDuplicate?: boolean;
   onSaved?: (deal: Deal) => void;
   onDeleted?: (dealId: string) => void;
   children?: ReactNode;
@@ -50,7 +52,7 @@ function fromDeal(d: Deal): Form {
   return { name: d.name ?? "", amount: d.amount != null ? String(d.amount) : "", closeDate: d.close_date?.slice(0, 10) ?? "", stageId: d.stage_id ?? "", description: d.description ?? "" };
 }
 
-export function DealDetail({ dealId, ownerId, contactIds = [], pipelineId, onSaved, onDeleted, children, className }: DealDetailProps) {
+export function DealDetail({ dealId, ownerId, contactIds = [], pipelineId, allowDuplicate, onSaved, onDeleted, children, className }: DealDetailProps) {
   const { pipelines, defaultPipeline } = usePipelines();
   const [form, setForm] = useState<Form>(EMPTY);
   const [confirmDelete, setConfirmDelete] = useState(false);
@@ -77,7 +79,7 @@ export function DealDetail({ dealId, ownerId, contactIds = [], pipelineId, onSav
     };
     const env = effectiveId
       ? await g8Patch(`/deals/${encodeURIComponent(effectiveId)}`, { ...body, expected_revision: (dealId ? deal.data?.revision : createdRevision) ?? undefined })
-      : await g8Post("/deals", { ...body, owner_id: ownerId, contact_ids: contactIds, pipeline_id: pipeline?.id, amount: body.amount ?? undefined, close_date: body.close_date ?? undefined });
+      : await g8Post("/deals", { ...body, owner_id: ownerId, contact_ids: contactIds, allow_duplicate: allowDuplicate || undefined, pipeline_id: pipeline?.id, amount: body.amount ?? undefined, close_date: body.close_date ?? undefined });
     return dataOf<Deal>(env);
   }, { onSuccess: (saved) => { if (!dealId && saved.id) { setCreatedId(saved.id); setCreatedRevision(saved.revision ?? null); } if (dealId) { void deal.refetch(); void history.refetch(); } onSaved?.(saved); } });
   const remove = useG8Mutation(async () => { await g8Delete(`/deals/${encodeURIComponent(dealId as string)}`); }, { onSuccess: () => { setConfirmDelete(false); onDeleted?.(dealId as string); }, onError: () => setConfirmDelete(false) });

package/blocks/deals/components/deal-related.tsx

@@ -0,0 +1,87 @@
+"use client";
+
+/**
+ * Related records of one deal, as tabs of the deal's full detail: its contacts (open one for the full CRM record)
+ * and its quotes (read-only list; open one in your quotes screen through `onOpenQuote`).
+ *
+ * SDK operations, in order:
+ *   DealContactsTab: GET /deals/{id}                    (deals.getDeal)    read - the deal's contacts and roles
+ *                    GET /contacts/{id} ...             (crm ContactDetail, in a side sheet)
+ *   DealQuotesTab:   GET /quotes?deal_id=&page=&limit   (quotes.listQuotes) read - needs the quotes:read scope
+ * Nothing here is billable, external or destructive.
+ */
+import { useState } from "react";
+import { FileText, Users } from "lucide-react";
+import { Sheet, SheetContent, SheetDescription, SheetHeader, SheetTitle, Skeleton, Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { EmptyState } from "@/g8/components/empty-state";
+import { EntityAvatar } from "@/g8/components/screen/entity-avatar";
+import { StatusPill, toneForStatus, humanizeStatus } from "@/g8/components/screen/status-pill";
+import { g8Get } from "@/g8/lib/g8-client";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { ContactDetail } from "@/g8/crm/components/contact-detail";
+import { dataOf, type Deal } from "../lib/deals-types";
+
+export function DealContactsTab({ dealId }: { dealId: string }) {
+  const [open, setOpen] = useState<number | null>(null);
+  const q = useG8Query(async (signal) => dataOf<Deal>(await g8Get(`/deals/${encodeURIComponent(dealId)}`, undefined, { signal })), [dealId]);
+  if (q.error) return <ApiError error={q.error} title="Could not load the deal's contacts" onRetry={() => void q.refetch()} />;
+  if (!q.data) return <Skeleton className="h-24 w-full" aria-label="Loading contacts" />;
+  const contacts = q.data.contacts ?? [];
+  if (contacts.length === 0) return <EmptyState icon={<Users className="size-8" />} title="No contacts on this deal" description="Contacts are attached when the deal is created." />;
+  return (
+    <>
+      <ul className="divide-y rounded-md border" aria-label="Deal contacts">
+        {contacts.map((c) => (
+          <li key={c.id}>
+            <button type="button" className="flex w-full items-center gap-3 p-3 text-left hover:bg-muted" onClick={() => setOpen(c.id)}>
+              <EntityAvatar name={c.name || c.email || "Contact"} size="md" />
+              <span className="min-w-0 flex-1">
+                <span className="block truncate text-sm font-medium">{c.name || c.email || `Contact ${c.id}`}</span>
+                <span className="block truncate text-xs text-muted-foreground">{[c.title, c.email].filter(Boolean).join(" · ")}</span>
+              </span>
+              {c.role ? <StatusPill tone="neutral">{humanizeStatus(c.role)}</StatusPill> : null}
+              {q.data?.primary_contact?.id === c.id ? <StatusPill tone="info">Primary</StatusPill> : null}
+            </button>
+          </li>
+        ))}
+      </ul>
+      <Sheet open={open != null} onOpenChange={(o) => { if (!o) setOpen(null); }}>
+        <SheetContent className="w-full overflow-y-auto sm:max-w-2xl">
+          <SheetHeader><SheetTitle>Contact</SheetTitle><SheetDescription>The full CRM record.</SheetDescription></SheetHeader>
+          {open != null ? <ContactDetail contactId={open} /> : null}
+        </SheetContent>
+      </Sheet>
+    </>
+  );
+}
+
+interface QuoteRow { id: string; title?: string | null; quote_number?: string | null; status?: string | null; total?: number | null; currency?: string | null }
+
+export function DealQuotesTab({ dealId, onOpenQuote }: { dealId: string; onOpenQuote?: (quoteId: string) => void }) {
+  const q = useG8Query(async (signal) => {
+    const env = await g8Get("/quotes", { deal_id: dealId, page: 1, limit: 50 }, { signal });
+    const inner = dataOf<{ items?: QuoteRow[] } | QuoteRow[]>(env);
+    return Array.isArray(inner) ? inner : (inner.items ?? []);
+  }, [dealId]);
+  if (q.error) return <ApiError error={q.error} title="Could not load quotes" onRetry={() => void q.refetch()} />;
+  if (!q.data) return <Skeleton className="h-24 w-full" aria-label="Loading quotes" />;
+  if (q.data.length === 0) return <EmptyState icon={<FileText className="size-8" />} title="No quotes for this deal" description="Create one from the Quotes screen." />;
+  return (
+    <Table>
+      <TableHeader><TableRow><TableHead>Quote</TableHead><TableHead>Status</TableHead><TableHead className="text-right">Total</TableHead></TableRow></TableHeader>
+      <TableBody>
+        {q.data.map((r) => (
+          <TableRow key={r.id}>
+            <TableCell>
+              {onOpenQuote ? <button type="button" className="font-medium hover:underline" onClick={() => onOpenQuote(r.id)}>{r.title || "Untitled quote"}</button> : <span className="font-medium">{r.title || "Untitled quote"}</span>}
+              <div className="text-xs text-muted-foreground">{r.quote_number}</div>
+            </TableCell>
+            <TableCell><StatusPill tone={toneForStatus(r.status)} dot>{humanizeStatus(r.status)}</StatusPill></TableCell>
+            <TableCell className="text-right tabular-nums">{r.total == null ? "" : (r.total / 100).toLocaleString(undefined, { style: "currency", currency: r.currency || "USD" })}</TableCell>
+          </TableRow>
+        ))}
+      </TableBody>
+    </Table>
+  );
+}

package/blocks/deals/components/deals-screen.tsx

@@ -0,0 +1,293 @@
+"use client";
+
+/**
+ * DealsScreen: the finished deals product. Board and list of the pipeline, a deal detail, new deal, forecast and
+ * pipeline stage settings in one screen. No props are required.
+ *
+ * It composes: PipelineBoard (kanban, drag or "Move to"), a deals table, DealDetail (edit, stage history, delete),
+ * ForecastView, StageEditor, DealContactsTab, DealQuotesTab and the crm block's ActivityTimeline and ContactDetail.
+ *
+ * Flows:
+ *   - Board / List toggle, search by deal name, switch pipeline (when there is more than one).
+ *   - Headline numbers: open deals, open value, estimated weighted value, won value (from the loaded deals).
+ *   - Open a deal (board card or list row; deep link ?id=, full page with &view=full) -> Details (every field,
+ *     edit, stage history, confirmed delete), Contacts (open the full CRM record), Quotes and Activity tabs. Moving a card into a won/lost stage asks for the close date and amount.
+ *   - New deal: name, amount, close date, stage, plus the two things the API requires. The OWNER defaults to the API
+ *     key's own user (GET /team-members/me); with an organisation key it defaults to the first team member and an
+ *     owner picker lets the person change it. At least ONE CONTACT is required by the API (`contact_ids`), found with a
+ *     search box. A company that already has a deal is refused (409) unless "Allow another deal" is ticked.
+ *   - Forecast tab (ForecastView) and Pipeline settings tab (stage summary with deal counts and values, plus StageEditor: names, probabilities, order, delete).
+ *
+ * SDK operations (all through the composed parts): listPipelines, listDeals, getDeal, listDealHistory, createDeal,
+ * updateDeal, deleteDeal (confirmed), getDealAnalytics, getDealStageVelocity, the pipeline-stage writes,
+ * listTeamMembers + getMyTeamMember (the owner default) and the crm block's listContacts + activity feed.
+ * Nothing here is billable or external; delete is destructive and goes through ConfirmSpendDialog inside DealDetail.
+ *
+ * Slots for cross-block glue (all optional): renderRowActions, renderDetailActions, extraDetailTabs, toolbarActions.
+ */
+import { useMemo, useState, type ReactNode } from "react";
+import { Handshake, Plus, Search, X } from "lucide-react";
+import { Button, Input, Skeleton, Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+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 { 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 { useUrlState } from "@/g8/hooks/use-url-state";
+import { g8Get } from "@/g8/lib/g8-client";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { ActivityTimeline } from "@/g8/crm/components/activity-timeline";
+import { useDebouncedValue } from "@/g8/crm/hooks/use-debounced";
+import { contactName, type ContactRecord } from "@/g8/crm/lib/crm-types";
+import { useDefaultOwner } from "../hooks/use-default-owner";
+import { usePipelineDeals } from "../hooks/use-pipeline-deals";
+import { usePipelines } from "../hooks/use-pipelines";
+import { dataOf, formatDate, formatMoney, stageKind, sumMoney, weightedPipeline, type Deal, type Stage } from "../lib/deals-types";
+import { DealDetail } from "./deal-detail";
+import { DealContactsTab, DealQuotesTab } from "./deal-related";
+import { ForecastView } from "./forecast-view";
+import { PipelineBoard } from "./pipeline-board";
+import { StageEditor } from "./stage-editor";
+
+export interface DealsScreenProps {
+  /** Start on this pipeline; defaults to the org's default one. */
+  pipelineId?: string;
+  /** Extra buttons per list row (for example "Create quote" from the quotes block). */
+  renderRowActions?: (deal: Deal) => ReactNode;
+  /** Extra buttons in the detail header. */
+  renderDetailActions?: (deal: Deal) => ReactNode;
+  /** Extra tabs in the detail panel, for example a Quotes tab. */
+  extraDetailTabs?: Array<{ id: string; label: string; render: (deal: Deal) => ReactNode }>;
+  /** Extra controls at the right of the toolbar. */
+  toolbarActions?: ReactNode;
+  /** Open a quote of the deal in your quotes screen; without it the Quotes tab is read-only. */
+  onOpenQuote?: (quoteId: string) => void;
+}
+
+type View = "board" | "list" | "forecast" | "stages";
+const VIEWS: Array<{ id: View; label: string }> = [
+  { id: "board", label: "Board" },
+  { id: "list", label: "List" },
+  { id: "forecast", label: "Forecast" },
+  { id: "stages", label: "Pipeline settings" },
+];
+const asView = (v: string | null | undefined): View => (VIEWS.some((x) => x.id === v) ? (v as View) : "board");
+
+function stageTone(stage: Stage | undefined): "neutral" | "positive" | "negative" | "info" {
+  const kind = stageKind(stage);
+  return kind === "won" ? "positive" : kind === "lost" ? "negative" : "info";
+}
+
+/** Contact search + chips for the new-deal sheet. The API requires at least one contact. */
+function ContactPicker({ value, onChange }: { value: ContactRecord[]; onChange: (next: ContactRecord[]) => void }) {
+  const [text, setText] = useState("");
+  const term = useDebouncedValue(text.trim());
+  const found = useG8Query(async (signal) => {
+    const env = await g8Get<ContactRecord[]>("/contacts", { name: term, limit: 8, page: 1 }, { signal });
+    return env.data ?? [];
+  }, [term], { enabled: term.length > 1 });
+  const choices = (found.data ?? []).filter((c) => !value.some((v) => v.id === c.id));
+  return (
+    <div className="space-y-2">
+      <label htmlFor="deal-contact-search" className="text-sm font-medium">Contacts</label>
+      <div className="flex flex-wrap gap-1">
+        {value.map((c) => (
+          <span key={c.id} className="inline-flex items-center gap-1 rounded-full border bg-muted px-2 py-0.5 text-xs">
+            {contactName(c)}
+            <button type="button" aria-label={`Remove ${contactName(c)}`} onClick={() => onChange(value.filter((v) => v.id !== c.id))}><X className="size-3" /></button>
+          </span>
+        ))}
+      </div>
+      <div className="relative">
+        <Search className="pointer-events-none absolute left-2 top-2.5 size-4 text-muted-foreground" aria-hidden />
+        <Input id="deal-contact-search" className="pl-8" placeholder="Search contacts by name" value={text} onChange={(e) => setText(e.target.value)} />
+      </div>
+      {found.error ? <ApiError error={found.error} title="Could not search contacts" /> : null}
+      {term.length > 1 && !found.loading && choices.length === 0 && !found.error ? <p className="text-xs text-muted-foreground">No other contacts match.</p> : null}
+      <ul className="divide-y rounded-md border empty:hidden" aria-label="Matching contacts">
+        {choices.map((c) => (
+          <li key={c.id}>
+            <button type="button" className="flex w-full items-center gap-2 p-2 text-left text-sm hover:bg-muted" onClick={() => { onChange([...value, c]); setText(""); }}>
+              <EntityAvatar name={contactName(c)} size="sm" />
+              <span className="font-medium">{contactName(c)}</span>
+              <span className="text-xs text-muted-foreground">{[c.job_title, c.company_name].filter(Boolean).join(" at ")}</span>
+            </button>
+          </li>
+        ))}
+      </ul>
+      <p className="text-xs text-muted-foreground">graph8 needs at least one contact on a deal. Every contact must work at the same company.</p>
+    </div>
+  );
+}
+
+function NewDealForm({ pipelineId, onCreated }: { pipelineId?: string; onCreated: (deal: Deal) => void }) {
+  const owner = useDefaultOwner();
+  const [ownerId, setOwnerId] = useState<string | null>(null);
+  const [contacts, setContacts] = useState<ContactRecord[]>([]);
+  const [duplicate, setDuplicate] = useState(false);
+  const effectiveOwner = ownerId ?? owner.defaultOwner?.id ?? "";
+  if (owner.loading) return <Skeleton className="h-40 w-full" aria-label="Loading owners" />;
+  if (!effectiveOwner) return <ApiError error={owner.error ?? new Error("No team member found to own this deal.")} title="A deal needs an owner" onRetry={() => void owner.reload()} />;
+  return (
+    <div className="space-y-4">
+      <div className="space-y-1">
+        <label htmlFor="deal-owner" className="text-sm font-medium">Owner</label>
+        <select id="deal-owner" className="h-9 w-full rounded-md border bg-background px-2 text-sm" value={effectiveOwner} onChange={(e) => setOwnerId(e.target.value)}>
+          {owner.owners.map((o) => <option key={o.id} value={o.id}>{o.name}{o.email && o.email !== o.name ? ` (${o.email})` : ""}</option>)}
+        </select>
+        <p className="text-xs text-muted-foreground">{owner.source === "key" && ownerId === null ? "Defaults to you, the owner of this API key." : "Defaults to the first team member because this key has no person."}</p>
+      </div>
+      <ContactPicker value={contacts} onChange={setContacts} />
+      <label className="flex items-center gap-2 text-sm"><input type="checkbox" checked={duplicate} onChange={(e) => setDuplicate(e.target.checked)} />Allow another deal for a company that already has one</label>
+      {contacts.length === 0 ? <p className="rounded-md border border-dashed p-3 text-sm text-muted-foreground">Pick a contact to continue.</p> : (
+        <DealDetail key={contacts.map((c) => c.id).join(",")} ownerId={effectiveOwner} contactIds={contacts.map((c) => c.id)} pipelineId={pipelineId} allowDuplicate={duplicate} onSaved={onCreated} />
+      )}
+    </div>
+  );
+}
+
+/** Every stage of the pipeline with its type, probability, deal count and value: the read side of pipeline settings. */
+function StageSummary({ stages, deals }: { stages: Stage[]; deals: Deal[] }) {
+  return (
+    <Table aria-label="Stages">
+      <TableHeader><TableRow><TableHead>Stage</TableHead><TableHead>Type</TableHead><TableHead className="text-right">Probability</TableHead><TableHead className="text-right">Deals</TableHead><TableHead className="text-right">Value</TableHead></TableRow></TableHeader>
+      <TableBody>
+        {stages.map((s) => {
+          const here = deals.filter((d) => d.stage_id === s.id);
+          return (
+            <TableRow key={s.id}>
+              <TableCell className="font-medium">{s.name}</TableCell>
+              <TableCell><StatusPill tone={stageTone(s)} dot>{stageKind(s) === "won" ? "Closed won" : stageKind(s) === "lost" ? "Closed lost" : "Open"}</StatusPill></TableCell>
+              <TableCell className="text-right tabular-nums">{s.probability == null ? "" : `${s.probability}%`}</TableCell>
+              <TableCell className="text-right tabular-nums">{here.length.toLocaleString()}</TableCell>
+              <TableCell className="text-right tabular-nums">{sumMoney(here)}</TableCell>
+            </TableRow>
+          );
+        })}
+      </TableBody>
+    </Table>
+  );
+}
+
+function DealRows({ deals, stages, selectedId, onOpen, renderRowActions }: { deals: Deal[]; stages: Stage[]; selectedId: string | null; onOpen: (d: Deal) => void; renderRowActions?: (d: Deal) => ReactNode }) {
+  const byId = new Map(stages.map((s) => [s.id, s]));
+  return (
+    <Table>
+      <TableHeader><TableRow><TableHead>Deal</TableHead><TableHead>Stage</TableHead><TableHead className="text-right">Amount</TableHead><TableHead>Owner</TableHead><TableHead>Close date</TableHead>{renderRowActions ? <TableHead /> : null}</TableRow></TableHeader>
+      <TableBody>
+        {deals.map((d) => {
+          const stage = d.stage_id ? byId.get(d.stage_id) : undefined;
+          return (
+            <TableRow key={d.id} data-state={selectedId === d.id ? "selected" : undefined} className="cursor-pointer" onClick={() => onOpen(d)}>
+              <TableCell><button type="button" className="font-medium hover:underline" onClick={(e) => { e.stopPropagation(); onOpen(d); }}>{d.name || "Untitled deal"}</button></TableCell>
+              <TableCell><StatusPill tone={stageTone(stage)} dot>{stage?.name ?? d.stage_name ?? "Unknown"}</StatusPill></TableCell>
+              <TableCell className="text-right tabular-nums">{formatMoney(d.amount, d.currency)}</TableCell>
+              <TableCell><span className="inline-flex items-center gap-2"><EntityAvatar name={d.owner_name ?? d.owner_email ?? "?"} size="sm" />{d.owner_name ?? d.owner_email ?? "No owner"}</span></TableCell>
+              <TableCell className="tabular-nums">{formatDate(d.close_date)}</TableCell>
+              {renderRowActions ? <TableCell onClick={(e) => e.stopPropagation()}>{renderRowActions(d)}</TableCell> : null}
+            </TableRow>
+          );
+        })}
+      </TableBody>
+    </Table>
+  );
+}
+
+export function DealsScreen({ pipelineId: initialPipelineId, renderRowActions, renderDetailActions, extraDetailTabs, toolbarActions, onOpenQuote }: DealsScreenProps) {
+  const [viewParam, setViewParam] = useUrlState("tab", "board");
+  const [selectedId, setSelectedId] = useUrlState("id");
+  const [mode, setMode] = useUrlState("view");
+  const [pipelineParam, setPipelineParam] = useUrlState("pipeline", initialPipelineId ?? "");
+  const [searchText, setSearchText] = useState("");
+  const search = useDebouncedValue(searchText.trim());
+  const [creating, setCreating] = useState(false);
+  const [version, setVersion] = useState(0);
+  const view = asView(viewParam);
+  const pipelines = usePipelines();
+  const pipeline = pipelines.pipelines.find((p) => p.id === pipelineParam) ?? pipelines.defaultPipeline;
+  const data = usePipelineDeals(pipeline?.id, { search });
+  const stages = pipeline?.stages ?? [];
+  const refresh = () => { setVersion((v) => v + 1); void data.reload(); };
+
+  const stats = useMemo(() => {
+    const open = data.deals.filter((d) => stageKind(stages.find((s) => s.id === d.stage_id)) === "open");
+    const won = data.deals.filter((d) => stageKind(stages.find((s) => s.id === d.stage_id)) === "won");
+    const cur = data.deals[0]?.currency;
+    const weighted = (group: ReadonlyArray<Deal>) => Math.round(weightedPipeline(group, stages).value);
+    return [
+      { label: "Open deals", value: open.length.toLocaleString() },
+      { label: "Open value", value: sumMoney(open, undefined, cur) },
+      { label: "Weighted (estimate)", value: sumMoney(data.deals, weighted, cur), hint: "Open deals times stage probability" },
+      { label: "Won", value: sumMoney(won, undefined, cur), tone: "positive" as const },
+    ];
+  }, [data.deals, stages]);
+
+  const listed = data.deals.find((d) => d.id === selectedId);
+  // A deep link can point at a deal in another pipeline or hidden by the search: resolve it directly.
+  const fetched = useG8Query(async (signal) => dataOf<Deal>(await g8Get(`/deals/${encodeURIComponent(selectedId ?? "")}`, undefined, { signal })), [selectedId, version], { enabled: Boolean(selectedId) && !listed && !data.loading });
+  const selected = listed ?? (fetched.data?.id === selectedId ? fetched.data : undefined);
+  const open = (id: string) => setSelectedId(id);
+  const close = () => { setSelectedId(null); setMode(null); };
+  const showToolbar = view === "board" || view === "list";
+
+  const detail = selectedId ? (
+    <DetailPanel
+      title={selected?.name || "Deal"}
+      subtitle={selected ? [selected.stage_name, formatMoney(selected.amount, selected.currency)].join(" · ") : undefined}
+      badges={selected ? <StatusPill tone={stageTone(stages.find((s) => s.id === selected.stage_id))} dot>{selected.stage_name ?? "Open"}</StatusPill> : undefined}
+      actions={selected && renderDetailActions ? renderDetailActions(selected) : undefined}
+      onClose={close}
+      onExpand={mode === "full" ? undefined : () => setMode("full")}
+      onCollapse={mode === "full" ? () => setMode(null) : undefined}
+      tabs={[
+        { id: "details", label: "Details", content: <DealDetail key={selectedId} dealId={selectedId} onSaved={refresh} onDeleted={() => { close(); refresh(); }} /> },
+        { id: "contacts", label: "Contacts", content: <DealContactsTab key={selectedId} dealId={selectedId} /> },
+        { id: "quotes", label: "Quotes", content: <DealQuotesTab key={selectedId} dealId={selectedId} onOpenQuote={onOpenQuote} /> },
+        { id: "activity", label: "Activity", content: <ActivityTimeline entityType="deal" entityId={selectedId} /> },
+        ...(extraDetailTabs ?? []).map((t) => ({ id: t.id, label: t.label, content: selected ? t.render(selected) : null })),
+      ]}
+    />
+  ) : null;
+
+  const list = data.error ? <ApiError error={data.error} title="Could not load deals" onRetry={() => void data.reload()} /> : data.loading && data.deals.length === 0 ? <Skeleton className="h-48 w-full" aria-label="Loading deals" /> : data.deals.length === 0 ? (
+    <EmptyState icon={<Handshake className="size-8" />} title={search ? "No deals match your search" : "No deals yet"} description={search ? "Try a different name." : "Create your first deal. It lands in the first stage of the pipeline."} action={search ? undefined : <Button onClick={() => setCreating(true)}>New deal</Button>} />
+  ) : <DealRows deals={data.deals} stages={stages} selectedId={selectedId} onOpen={(d) => open(d.id)} renderRowActions={renderRowActions} />;
+
+  let body: ReactNode;
+  if (view === "forecast") body = <ForecastView pipelineId={pipeline?.id} />;
+  else if (view === "stages") body = pipeline ? <div className="space-y-6"><StageSummary stages={stages} deals={data.deals} /><StageEditor pipelineId={pipeline.id} onChanged={refresh} /></div> : <EmptyState title="No pipeline yet" description="Create a pipeline in graph8 first." />;
+  else body = <SplitView detailOpen={Boolean(selectedId)} onCloseDetail={close} expanded={mode === "full" && Boolean(selectedId)} onExpandedChange={(full) => setMode(full ? "full" : null)} detailWidth="lg" detail={detail} list={view === "board" ? <PipelineBoard key={`${pipeline?.id}-${version}`} pipelineId={pipeline?.id} search={search} onSelectDeal={(d) => open(d.id)} onChanged={() => void data.reload()} /> : list} />;
+
+  return (
+    <ScreenLayout
+      title="Deals"
+      description="Move deals through your pipeline and see what is likely to close."
+      icon={<Handshake className="size-5" />}
+      actions={<Button onClick={() => setCreating(true)}><Plus className="size-4" aria-hidden />New deal</Button>}
+      tabs={VIEWS}
+      activeTab={view}
+      onTabChange={(id) => { setViewParam(id); if (id !== "board" && id !== "list") setSearchText(""); }}
+      stats={stats}
+      toolbar={showToolbar ? (
+        <Toolbar
+          search={{ value: searchText, onChange: setSearchText, placeholder: "Search deals" }}
+          filters={pipelines.pipelines.length > 1 ? (
+            <select aria-label="Pipeline" className="h-9 rounded-md border bg-background px-2 text-sm" value={pipeline?.id ?? ""} onChange={(e) => { setPipelineParam(e.target.value); close(); }}>
+              {pipelines.pipelines.map((p) => <option key={p.id} value={p.id}>{p.name}</option>)}
+            </select>
+          ) : undefined}
+          actions={toolbarActions}
+        />
+      ) : undefined}
+    >
+      {pipelines.error ? <ApiError error={pipelines.error} title="Could not load pipelines" onRetry={() => void pipelines.refetch()} /> : body}
+      <FormSheet open={creating} onOpenChange={setCreating} title="New deal" description="The deal lands in the first stage unless you pick another.">
+        {creating ? <NewDealForm pipelineId={pipeline?.id} onCreated={(deal) => { setCreating(false); refresh(); if (deal.id) { setViewParam("board"); open(deal.id); } }} /> : null}
+      </FormSheet>
+    </ScreenLayout>
+  );
+}

package/blocks/deals/components/pipeline-board.tsx

@@ -29,6 +29,8 @@ export interface PipelineBoardProps {
   search?: string;
   ownerId?: string;
   onSelectDeal?: (deal: Deal) => void;
+  /** Called after a stage move was saved, so a screen can refresh its totals. */
+  onChanged?: () => void;
   className?: string;
 }
 
@@ -92,7 +94,7 @@ function CloseDialog({ stage, deal, onConfirm, onCancel }: { stage: Stage; deal:
   );
 }
 
-export function PipelineBoard({ pipelineId, search, ownerId, onSelectDeal, className }: PipelineBoardProps) {
+export function PipelineBoard({ pipelineId, search, ownerId, onSelectDeal, onChanged, className }: PipelineBoardProps) {
   const pipelines = usePipelines();
   const pipeline = pipelines.pipelines.find((p) => p.id === pipelineId) ?? pipelines.defaultPipeline;
   const { deals, loading, error, reload, moveDeal, movingIds } = usePipelineDeals(pipeline?.id, { search, ownerId });
@@ -110,7 +112,7 @@ export function PipelineBoard({ pipelineId, search, ownerId, onSelectDeal, class
     if (deal.stage_id === stage.id || movingIds.has(deal.id)) return;
     setMoveError(null);
     if (stageKind(stage) !== "open" && !extra) { setClosing({ deal, stage }); return; }
-    try { await moveDeal(deal, stage.id, extra); } catch (err) {
+    try { await moveDeal(deal, stage.id, extra); onChanged?.(); } catch (err) {
       const marker = closedStageMarker(err);
       setMoveError(marker ? new Error(`The API needs more before this deal can close (${marker.replace(/_/g, " ")}).`) : err);
     }