@graph8/sdk 0.370.0 → 0.374.0

package/blocks/email-signatures/components/signature-block-editor.tsx

@@ -0,0 +1,87 @@
+"use client";
+
+/**
+ * SignatureBlockEditor: edit the ordered blocks of a signature template (kind, text, link, image, locked, required), with
+ * placeholders to insert, move up and down, remove and add. A pure form control: it calls no operation and owns no
+ * state, so SignatureTemplateForm keeps the draft and validates it with `templateProblems`.
+ */
+
+import { ArrowDown, ArrowUp, Plus, Trash2 } from "lucide-react";
+import { Button, Input, Label, Textarea } from "@graph8/sdk/ui";
+import { BLOCK_KINDS, VARIABLES, nextBlockId, variableText } from "../lib/signatures-types";
+import type { BlockKind, TemplateBlock } from "../lib/signatures-types";
+
+export interface SignatureBlockEditorProps {
+  blocks: TemplateBlock[];
+  onChange: (blocks: TemplateBlock[]) => void;
+  disabled?: boolean;
+}
+
+const SELECT = "border-input bg-background h-9 w-full rounded-md border px-2 text-sm disabled:opacity-50";
+
+export function SignatureBlockEditor({ blocks, onChange, disabled }: SignatureBlockEditorProps) {
+  const patch = (i: number, change: Partial<TemplateBlock>): void => onChange(blocks.map((b, at) => (at === i ? { ...b, ...change } : b)));
+  const move = (i: number, by: number): void => {
+    const to = i + by;
+    if (to < 0 || to >= blocks.length) return;
+    const next = [...blocks];
+    [next[i], next[to]] = [next[to], next[i]];
+    onChange(next);
+  };
+  const add = (kind: BlockKind): void => onChange([...blocks, { id: nextBlockId(kind, blocks), kind, text: "", url: "", image: "", locked: false, required: false }]);
+
+  return (
+    <div className="grid gap-3">
+      <ol className="grid gap-3">
+        {blocks.map((b, i) => {
+          const hint = BLOCK_KINDS.find((k) => k.value === b.kind)?.hint;
+          return (
+            <li key={i} className="grid gap-2 rounded-md border p-3" aria-label={`Block ${i + 1}: ${b.id}`}>
+              <div className="flex flex-wrap items-end gap-2">
+                <div className="min-w-40 flex-1">
+                  <Label htmlFor={`g8-sig-kind-${i}`} className="mb-1">Block {i + 1} type</Label>
+                  <select id={`g8-sig-kind-${i}`} className={SELECT} value={b.kind} disabled={disabled} onChange={(e) => patch(i, { kind: e.target.value as BlockKind })}>
+                    {BLOCK_KINDS.map((k) => <option key={k.value} value={k.value}>{k.label}</option>)}
+                  </select>
+                </div>
+                <div className="w-40">
+                  <Label htmlFor={`g8-sig-id-${i}`} className="mb-1">Block id</Label>
+                  <Input id={`g8-sig-id-${i}`} value={b.id} disabled={disabled} onChange={(e) => patch(i, { id: e.target.value })} />
+                </div>
+                <div className="flex gap-1">
+                  <Button type="button" size="sm" variant="ghost" aria-label={`Move block ${i + 1} up`} disabled={disabled || i === 0} onClick={() => move(i, -1)}><ArrowUp className="size-4" /></Button>
+                  <Button type="button" size="sm" variant="ghost" aria-label={`Move block ${i + 1} down`} disabled={disabled || i === blocks.length - 1} onClick={() => move(i, 1)}><ArrowDown className="size-4" /></Button>
+                  <Button type="button" size="sm" variant="ghost" aria-label={`Remove block ${i + 1}`} disabled={disabled} onClick={() => onChange(blocks.filter((_, at) => at !== i))}><Trash2 className="size-4" /></Button>
+                </div>
+              </div>
+              {hint ? <p className="text-muted-foreground text-xs">{hint}</p> : null}
+              <div>
+                <Label htmlFor={`g8-sig-text-${i}`} className="mb-1">Text</Label>
+                <Textarea id={`g8-sig-text-${i}`} rows={3} value={b.text} disabled={disabled} onChange={(e) => patch(i, { text: e.target.value })} />
+                <select aria-label={`Insert a placeholder into block ${i + 1}`} className={`${SELECT} mt-1`} value="" disabled={disabled} onChange={(e) => e.target.value && patch(i, { text: `${b.text}${variableText(e.target.value)}` })}>
+                  <option value="">Insert a placeholder</option>
+                  {VARIABLES.map((v) => <option key={v.token} value={v.token}>{v.label} ({variableText(v.token)})</option>)}
+                </select>
+              </div>
+              <div className="grid gap-2 sm:grid-cols-2">
+                <div><Label htmlFor={`g8-sig-url-${i}`} className="mb-1">Link (optional)</Label><Input id={`g8-sig-url-${i}`} value={b.url} disabled={disabled} placeholder="https://" onChange={(e) => patch(i, { url: e.target.value })} /></div>
+                <div><Label htmlFor={`g8-sig-image-${i}`} className="mb-1">Image address (optional)</Label><Input id={`g8-sig-image-${i}`} value={b.image} disabled={disabled} placeholder="https://" onChange={(e) => patch(i, { image: e.target.value })} /></div>
+              </div>
+              <div className="flex flex-wrap gap-4 text-sm">
+                <label className="flex items-center gap-2"><input type="checkbox" checked={b.required} disabled={disabled} onChange={(e) => patch(i, e.target.checked ? { required: true, locked: true } : { required: false })} />Required (always shown)</label>
+                <label className="flex items-center gap-2"><input type="checkbox" checked={b.locked} disabled={disabled || b.required} onChange={(e) => patch(i, { locked: e.target.checked })} />Locked (employees cannot change it)</label>
+              </div>
+            </li>
+          );
+        })}
+      </ol>
+      <div className="flex flex-wrap items-center gap-2">
+        <select aria-label="Add a block" className={`${SELECT} w-56`} value="" disabled={disabled || blocks.length >= 30} onChange={(e) => e.target.value && add(e.target.value as BlockKind)}>
+          <option value="">Add a block</option>
+          {BLOCK_KINDS.map((k) => <option key={k.value} value={k.value}>{k.label}</option>)}
+        </select>
+        <span className="text-muted-foreground flex items-center gap-1 text-xs"><Plus className="size-3" />{blocks.length} of 30 blocks</span>
+      </div>
+    </div>
+  );
+}

package/blocks/email-signatures/components/signature-campaign-form.tsx

@@ -0,0 +1,165 @@
+"use client";
+
+/**
+ * SignatureCampaignForm: create or edit a signature banner campaign (an optional banner injected into managed signatures
+ * for a time window), preview its banner, and test who it would reach.
+ *
+ * SDK operations, in order (mailboxes and members come from the shared hooks):
+ *   1. previewSignatureCampaign (POST /signatures/campaigns/preview)   write*  renders the banner from the unsaved draft; with a mailbox and
+ *      recipient addresses it also says whether the campaign would apply and which campaign wins on priority. Changes nothing.
+ *   2. createSignatureCampaign (POST /signatures/campaigns)            write   a campaign; it only applies once its status is Scheduled and the time is inside its dates
+ *   3. updateSignatureCampaign (PATCH /signatures/campaigns/{campaign_id}) write REPLACES the campaign and sends the revision that was read (409 if stale)
+ * *A POST, so the contract tiers it as a write.
+ * The API has no read-one operation: the campaign list row is the complete stored campaign, so an edit is seeded from it and
+ * the list is refreshed after every save. Dates are picked in the viewer's time zone and sent as timezone-aware instants,
+ * as the API requires. Emptied lists are sent as empty lists. A static native campaign must be sender-wide (no recipient
+ * rules), which is checked before the save is offered. Audience-list targeting (recipient_list_ids) has no list picker here, so
+ * the block does not depend on the lists block: a campaign that already targets lists keeps them on every save, and the
+ * person can remove that targeting; adding lists is done through the API (see the README).
+ */
+
+import { useState } from "react";
+import { Button, Input, Label, Textarea } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { SafeSignatureFrame } from "./signature-preview";
+import { g8Patch, g8Post } from "@/g8/lib/g8-client";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { plural } from "@/g8/lib/plural";
+import { useSignatureMailboxes, useSignatureMembers } from "../hooks/use-signatures-data";
+import { CAMPAIGN_STATUSES, fromLocalInput, isConflict, isManaged, splitList, toLocalInput } from "../lib/signatures-types";
+import type { CampaignData, CampaignPreview, SignatureCampaign } from "../lib/signatures-types";
+
+export interface SignatureCampaignFormProps {
+  /** Edit this campaign; omit to create one. */
+  campaign?: SignatureCampaign;
+  onSaved: (campaign: SignatureCampaign) => void;
+  onCancel?: () => void;
+  onReload?: () => void;
+}
+
+const SELECT = "border-input bg-background h-9 w-full rounded-md border px-2 text-sm";
+
+export function SignatureCampaignForm({ campaign, onSaved, onCancel, onReload }: SignatureCampaignFormProps) {
+  const d: CampaignData = campaign?.data ?? {};
+  const box = useSignatureMailboxes();
+  const members = useSignatureMembers();
+  const [name, setName] = useState(d.name ?? "");
+  const [blockId] = useState(d.block?.id ?? "banner");
+  const [text, setText] = useState(d.block?.text ?? "");
+  const [url, setUrl] = useState(d.block?.url ?? "");
+  const [image, setImage] = useState(d.block?.image ?? "");
+  const [starts, setStarts] = useState(toLocalInput(d.starts_at));
+  const [ends, setEnds] = useState(toLocalInput(d.ends_at));
+  const [status, setStatus] = useState(d.status ?? "draft");
+  const [priority, setPriority] = useState(String(d.priority ?? 0));
+  const [mailboxIds, setMailboxIds] = useState<number[]>(d.mailbox_ids ?? []);
+  const [domains, setDomains] = useState((d.recipient_domains ?? []).join(", "));
+  const [excluded, setExcluded] = useState((d.excluded_domains ?? []).join(", "));
+  const [external, setExternal] = useState(d.external_only ?? true);
+  const [depts, setDepts] = useState<string[]>(d.departments ?? []);
+  const [listIds, setListIds] = useState<number[]>(d.recipient_list_ids ?? []);
+  const [native, setNative] = useState(d.native_static ?? false);
+  const [testMailbox, setTestMailbox] = useState("");
+  const [testTo, setTestTo] = useState("");
+
+  const startIso = fromLocalInput(starts);
+  const endIso = fromLocalInput(ends);
+  const prio = Number(priority);
+  const departments = [...new Set([...(members.data ?? []).map((m) => m.department).filter((x): x is string => Boolean(x)), ...depts])].sort();
+  const rules = splitList(domains).length + splitList(excluded).length + listIds.length > 0 || external;
+  const problems = [
+    name.trim() === "" ? "Give the campaign a name." : "",
+    !startIso || !endIso ? "Choose when it starts and ends." : startIso >= endIso ? "It must end after it starts." : "",
+    !Number.isInteger(prio) || prio < -1000 || prio > 1000 ? "Priority is a whole number from -1000 to 1000." : "",
+    native && rules ? "A static native campaign must go to every recipient: turn off external only and remove the recipient rules." : "",
+  ].filter(Boolean);
+
+  const data = (): Record<string, unknown> => ({
+    name: name.trim(),
+    block: { id: blockId, kind: "banner", text, url, image, locked: false, required: false },
+    starts_at: startIso, ends_at: endIso, status, priority: prio,
+    mailbox_ids: mailboxIds, recipient_domains: splitList(domains), excluded_domains: splitList(excluded),
+    external_only: external, departments: depts, recipient_list_ids: listIds, native_static: native,
+  });
+
+  const save = useG8Mutation(async (): Promise<SignatureCampaign> => (campaign
+    ? await g8Patch<SignatureCampaign>(`/signatures/campaigns/${encodeURIComponent(campaign.id)}`, { version: campaign.revision, data: data() })
+    : await g8Post<SignatureCampaign>("/signatures/campaigns", { data: data() })).data, {
+    onSuccess: onSaved,
+    invalidates: [["signatures", "campaigns"]],
+  });
+  const preview = useG8Mutation(async (): Promise<CampaignPreview> => (await g8Post<CampaignPreview>("/signatures/campaigns/preview", {
+    data: data(),
+    ...(testMailbox ? { mailbox_id: Number(testMailbox), recipients: splitList(testTo), ...(campaign ? { campaign_id: campaign.id } : {}) } : {}),
+  })).data);
+  const toggle = <T,>(list: T[], v: T, on: boolean): T[] => (on ? [...list, v] : list.filter((x) => x !== v));
+  const match = preview.data?.matching as { matches?: boolean; selected_campaign_id?: string | null; limitation?: string } | null | undefined;
+
+  return (
+    <form className="grid gap-4" onSubmit={(e) => { e.preventDefault(); if (problems.length === 0) void save.mutate(undefined); }}>
+      <div><Label htmlFor="g8-sig-cname" className="mb-1">Campaign name</Label><Input id="g8-sig-cname" value={name} placeholder="Autumn webinar" onChange={(e) => setName(e.target.value)} /></div>
+      <fieldset className="grid gap-2"><legend className="mb-1 text-sm font-medium">Banner</legend>
+        <div><Label htmlFor="g8-sig-ctext" className="mb-1">Text (also the image description)</Label><Textarea id="g8-sig-ctext" rows={2} value={text} onChange={(e) => setText(e.target.value)} /></div>
+        <div className="grid gap-2 sm:grid-cols-2">
+          <div><Label htmlFor="g8-sig-curl" className="mb-1">Link</Label><Input id="g8-sig-curl" value={url} placeholder="https://" onChange={(e) => setUrl(e.target.value)} /></div>
+          <div><Label htmlFor="g8-sig-cimage" className="mb-1">Image address</Label><Input id="g8-sig-cimage" value={image} placeholder="https://" onChange={(e) => setImage(e.target.value)} /></div>
+        </div>
+      </fieldset>
+      <div className="grid gap-3 sm:grid-cols-2">
+        <div><Label htmlFor="g8-sig-cstart" className="mb-1">Starts</Label><Input id="g8-sig-cstart" type="datetime-local" value={starts} onChange={(e) => setStarts(e.target.value)} /></div>
+        <div><Label htmlFor="g8-sig-cend" className="mb-1">Ends</Label><Input id="g8-sig-cend" type="datetime-local" value={ends} onChange={(e) => setEnds(e.target.value)} /></div>
+        <div>
+          <Label htmlFor="g8-sig-cstatus" className="mb-1">Status</Label>
+          <select id="g8-sig-cstatus" className={SELECT} value={status} onChange={(e) => setStatus(e.target.value)}>
+            {CAMPAIGN_STATUSES.map((s) => <option key={s.value} value={s.value}>{s.label}</option>)}
+            {CAMPAIGN_STATUSES.some((s) => s.value === status) ? null : <option value={status}>{status}</option>}
+          </select>
+          <p className="text-muted-foreground mt-1 text-xs">Only a Scheduled campaign is added to signatures, and only between its dates.</p>
+        </div>
+        <div><Label htmlFor="g8-sig-cprio" className="mb-1">Priority</Label><Input id="g8-sig-cprio" type="number" value={priority} onChange={(e) => setPriority(e.target.value)} /><p className="text-muted-foreground mt-1 text-xs">When campaigns overlap, the higher number wins.</p></div>
+      </div>
+      <fieldset className="grid gap-2"><legend className="mb-1 text-sm font-medium">Who sees it</legend>
+        <p className="text-muted-foreground text-xs">Leave the mailboxes and departments empty to include everyone.</p>
+        {box.mailboxes.length > 0 ? (
+          <div className="grid max-h-32 gap-1 overflow-y-auto" role="group" aria-label="Mailboxes">
+            {box.mailboxes.map((m) => <label key={m.id} className="flex items-center gap-2 text-sm"><input type="checkbox" checked={mailboxIds.includes(m.id)} onChange={(e) => setMailboxIds(toggle(mailboxIds, m.id, e.target.checked))} />{m.email}</label>)}
+          </div>
+        ) : null}
+        {departments.length > 0 ? (
+          <div className="flex flex-wrap gap-3" role="group" aria-label="Departments">
+            {departments.map((x) => <label key={x} className="flex items-center gap-2 text-sm"><input type="checkbox" checked={depts.includes(x)} onChange={(e) => setDepts(toggle(depts, x, e.target.checked))} />{x}</label>)}
+          </div>
+        ) : null}
+        <label className="flex items-center gap-2 text-sm"><input type="checkbox" checked={external} onChange={(e) => setExternal(e.target.checked)} />Only emails to people outside the company</label>
+        <div><Label htmlFor="g8-sig-cdomains" className="mb-1">Only these recipient domains</Label><Input id="g8-sig-cdomains" value={domains} placeholder="acme.com, example.org" onChange={(e) => setDomains(e.target.value)} /></div>
+        <div><Label htmlFor="g8-sig-cexcl" className="mb-1">Never these recipient domains</Label><Input id="g8-sig-cexcl" value={excluded} onChange={(e) => setExcluded(e.target.value)} /></div>
+        {listIds.length > 0 ? (
+          <div className="flex flex-wrap items-center gap-2 rounded-md border p-2 text-sm">
+            <span>Only people on {plural(listIds.length, "audience list")} (set through the API; kept when you save). They apply only to emails sent from a sequence.</span>
+            <Button type="button" size="sm" variant="outline" onClick={() => setListIds([])}>Remove list targeting</Button>
+          </div>
+        ) : null}
+        <label className="flex items-center gap-2 text-sm"><input type="checkbox" checked={native} onChange={(e) => setNative(e.target.checked)} />Static native campaign (installed in the mail account, sender-wide)</label>
+      </fieldset>
+      <section aria-label="Test the campaign" className="grid gap-2 rounded-md border p-3">
+        <h3 className="text-sm font-medium">Preview and test</h3>
+        <div className="grid gap-2 sm:grid-cols-2">
+          <select aria-label="Test from mailbox" className={SELECT} value={testMailbox} onChange={(e) => setTestMailbox(e.target.value)}><option value="">Only render the banner</option>{box.mailboxes.filter((m) => isManaged(m.deployment)).map((m) => <option key={m.id} value={m.id}>{m.email}</option>)}</select>
+          <Input aria-label="Test recipients" value={testTo} placeholder="buyer@acme.com" disabled={testMailbox === ""} onChange={(e) => setTestTo(e.target.value)} />
+        </div>
+        <div><Button type="button" size="sm" variant="outline" disabled={problems.length > 0} loading={preview.loading} onClick={() => void preview.mutate(undefined)}>Preview</Button></div>
+        {preview.error ? <ApiError error={preview.error} title="Could not render the preview" /> : null}
+        {preview.data ? <SafeSignatureFrame html={preview.data.html} title="Banner preview" className="border-border h-32 w-full rounded-md border bg-white" /> : null}
+        {match ? <p role="status" className="text-sm">{match.matches ? "This campaign would be added to that email." : "This campaign would not be added to that email."} {match.limitation}</p> : null}
+      </section>
+      {problems.length > 0 ? <ul role="alert" className="text-error list-disc pl-5 text-xs">{problems.map((p) => <li key={p}>{p}</li>)}</ul> : null}
+      {save.error && isConflict(save.error) ? (
+        <div className="grid gap-2"><ApiError error={save.error} title="Someone else changed this campaign" />{onReload ? <div><Button type="button" size="sm" variant="outline" onClick={onReload}>Load the newer version</Button></div> : null}</div>
+      ) : save.error ? <ApiError error={save.error} title="Could not save the campaign" /> : null}
+      <div className="flex gap-2">
+        <Button type="submit" loading={save.loading} disabled={problems.length > 0}>{campaign ? "Save changes" : "Create campaign"}</Button>
+        {onCancel ? <Button type="button" variant="outline" onClick={onCancel}>Cancel</Button> : null}
+      </div>
+    </form>
+  );
+}

package/blocks/email-signatures/components/signature-campaigns.tsx

@@ -0,0 +1,75 @@
+"use client";
+
+/**
+ * SignatureCampaigns: the banner campaigns that are added to managed signatures for a time window: the list with status,
+ * dates and priority, and a sheet to create or edit one.
+ *
+ * SDK operations: none directly. The list comes from the shared hook (listSignatureCampaigns, GET /signatures/campaigns,
+ * read, not paged: the UI says "All N") and the writes and preview live in SignatureCampaignForm
+ * (createSignatureCampaign, updateSignatureCampaign, previewSignatureCampaign). The API has no delete: stop a campaign by
+ * setting its status to Paused (or Draft), which keeps its report numbers.
+ */
+
+import { useState } from "react";
+import { Megaphone, Plus } from "lucide-react";
+import { Button, Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { EmptyState } from "@/g8/components/empty-state";
+import { FormSheet } from "@/g8/components/screen/form-sheet";
+import { StatusPill, humanizeStatus, toneForStatus } from "@/g8/components/screen/status-pill";
+import { plural } from "@/g8/lib/plural";
+import { useSignatureCampaigns } from "../hooks/use-signatures-data";
+import { formatWhen } from "../lib/signatures-types";
+import type { SignatureCampaign } from "../lib/signatures-types";
+import { SignatureCampaignForm } from "./signature-campaign-form";
+
+export function SignatureCampaigns() {
+  const list = useSignatureCampaigns();
+  const [editing, setEditing] = useState<SignatureCampaign | "new" | null>(null);
+  const rows = list.data ?? [];
+  // The edit form is seeded from the campaign as the list holds it now (the API has no read-one), never from a stale copy.
+  const current = editing && editing !== "new" ? rows.find((c) => c.id === editing.id) ?? editing : editing;
+
+  const body = list.error && !list.data ? <ApiError error={list.error} title="Could not load campaigns" onRetry={() => void list.refetch()} /> : !list.data ? (
+    <div aria-busy="true" className="grid gap-2"><Skeleton className="h-14 w-full" /><Skeleton className="h-14 w-full" /></div>
+  ) : rows.length === 0 ? (
+    <EmptyState icon={<Megaphone className="size-8" />} title="No campaigns yet" description="A campaign adds a banner to signatures for a time window, for example a webinar or a launch." action={<Button onClick={() => setEditing("new")}>Create a campaign</Button>} />
+  ) : (
+    <>
+      <p role="status" className="text-muted-foreground mb-2 text-xs">All {plural(rows.length, "campaign")}</p>
+      <ul className="grid gap-2">
+        {rows.map((c) => (
+          <li key={c.id} className="flex flex-wrap items-center justify-between gap-2 rounded-md border p-3">
+            <div className="min-w-0 flex-1">
+              <span className="block truncate font-medium">{c.data.name || "Untitled campaign"}</span>
+              <span className="text-muted-foreground block text-xs">{formatWhen(c.data.starts_at)} to {formatWhen(c.data.ends_at)} · priority {c.data.priority ?? 0}</span>
+            </div>
+            <StatusPill tone={toneForStatus(c.data.status)}>{humanizeStatus(c.data.status)}</StatusPill>
+            <Button size="sm" variant="outline" aria-label={`Edit ${c.data.name || "campaign"}`} onClick={() => setEditing(c)}>Edit</Button>
+          </li>
+        ))}
+      </ul>
+    </>
+  );
+
+  return (
+    <div className="grid gap-3">
+      <div className="flex items-center justify-between gap-2">
+        <p className="text-muted-foreground text-sm">Banners added to managed signatures between two dates.</p>
+        <Button size="sm" onClick={() => setEditing("new")}><Plus className="size-4" />New campaign</Button>
+      </div>
+      {body}
+      <FormSheet open={editing !== null} onOpenChange={(o) => !o && setEditing(null)} width="xl" title={editing === "new" ? "New campaign" : "Edit campaign"} description="A banner shown in signatures during its dates.">
+        {current ? (
+          <SignatureCampaignForm
+            key={current === "new" ? "new" : `${current.id}:${current.revision}`}
+            campaign={current === "new" ? undefined : current}
+            onSaved={() => setEditing(null)}
+            onCancel={() => setEditing(null)}
+            onReload={() => void list.refetch()}
+          />
+        ) : null}
+      </FormSheet>
+    </div>
+  );
+}

package/blocks/email-signatures/components/signature-identity-form.tsx

@@ -0,0 +1,131 @@
+"use client";
+
+/**
+ * SignatureIdentityForm: give one mailbox a managed signature by binding it to an employee (and, optionally, a template).
+ *
+ * SDK operations, in order:
+ *   1. previewSignatureSetup (POST /signatures/setup-preview)     write*   "Check setup": a dry run against the mail provider. Confirms the
+ *      employee account and the send-as address resolve and shows the signature installed there today. Changes nothing.
+ *   2. assignSignatureIdentity (POST /signatures/assignments)     write    a TAKEOVER: the mailbox's current signature is captured for
+ *      restore and replaced, and the first install is queued. ConfirmSpendDialog (external) first, naming the mailbox.
+ * *A POST, so the contract tiers it as a write.
+ * The API requires the employee account to be the employee's own directory email and the send-as address to be the mailbox
+ * address, so both are shown read-only and derived from the two choices: nothing is typed or guessed. The mailbox's current
+ * revision (0 when it has no assignment yet) is sent so a stale screen cannot overwrite a newer change (409). When the mailbox
+ * is already assigned, its template, workspace integration, employee overrides and native-install request are carried over
+ * unchanged unless the person edits them here. A provider refusal (422) shows its state and reason.
+ */
+
+import { useState } from "react";
+import { Button, Label } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { KeyValueList } from "@/g8/components/screen/key-value-list";
+import { g8Post } from "@/g8/lib/g8-client";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useSignatureDeployments, useSignatureMembers, useSignatureTemplates } from "../hooks/use-signatures-data";
+import { isConflict, memberLabel, templateName } from "../lib/signatures-types";
+import type { Assignment, SignatureMailbox } from "../lib/signatures-types";
+
+export interface SignatureIdentityFormProps {
+  mailbox: SignatureMailbox;
+  onDone: () => void;
+  onCancel?: () => void;
+}
+
+interface SetupCheck { html?: string; plain?: string; identity_verified?: boolean; write_verified?: boolean; message?: string }
+
+const SELECT = "border-input bg-background h-9 w-full rounded-md border px-2 text-sm";
+
+export function SignatureIdentityForm({ mailbox, onDone, onCancel }: SignatureIdentityFormProps) {
+  const members = useSignatureMembers();
+  const templates = useSignatureTemplates();
+  const deployments = useSignatureDeployments();
+  const current = mailbox.deployment?.assignment;
+  const [memberId, setMemberId] = useState(current?.member_id ?? "");
+  const [templateId, setTemplateId] = useState(current?.template_id ?? "");
+  const [native, setNative] = useState(Boolean(current?.native_requested));
+  const [confirm, setConfirm] = useState(false);
+  const member = members.data?.find((m) => m.id === memberId);
+  const usable = Boolean(member?.email);
+
+  const assignment = (): Assignment => ({
+    member_id: memberId,
+    ...(templateId ? { template_id: templateId } : {}),
+    account_subject: member?.email ?? "",
+    send_as_email: mailbox.email,
+    ...(current?.integration_id ? { integration_id: current.integration_id } : {}),
+    overrides: current?.overrides ?? {},
+    native_requested: native,
+  });
+
+  const check = useG8Mutation(async (): Promise<SetupCheck> => (await g8Post<SetupCheck>("/signatures/setup-preview", { mailbox_id: mailbox.id, data: assignment() })).data);
+  const assign = useG8Mutation(async (): Promise<unknown> => (
+    await g8Post("/signatures/assignments", {
+      mailbox_ids: [mailbox.id],
+      expected_revisions: { [mailbox.id]: mailbox.deployment?.revision ?? 0 },
+      confirm_takeover: true,
+      data: assignment(),
+    })
+  ).data, {
+    onSuccess: () => { setConfirm(false); onDone(); },
+    onError: () => setConfirm(false),
+    invalidates: [["signatures", "deployments"]],
+  });
+
+  const err = assign.error;
+  return (
+    <form className="grid gap-3" onSubmit={(e) => { e.preventDefault(); if (usable) setConfirm(true); }}>
+      <p className="text-muted-foreground text-sm">Mailbox: <span className="text-foreground font-medium">{mailbox.email}</span></p>
+      <div>
+        <Label htmlFor="g8-sig-employee" className="mb-1">Employee</Label>
+        <select id="g8-sig-employee" className={SELECT} value={memberId} onChange={(e) => { setMemberId(e.target.value); check.reset(); }}>
+          <option value="">Choose an employee</option>
+          {(members.data ?? []).map((m) => <option key={m.id} value={m.id}>{memberLabel(m)}{m.department ? ` (${m.department})` : ""}</option>)}
+        </select>
+        {memberId !== "" && !usable ? <p role="alert" className="text-error mt-1 text-xs">This employee has no directory email, so a signature cannot be assigned to them.</p> : null}
+      </div>
+      <div>
+        <Label htmlFor="g8-sig-template" className="mb-1">Template</Label>
+        <select id="g8-sig-template" className={SELECT} value={templateId} onChange={(e) => setTemplateId(e.target.value)}>
+          <option value="">The department or organisation default</option>
+          {(templates.data ?? []).map((t) => <option key={t.id} value={t.id}>{templateName(t)}</option>)}
+        </select>
+      </div>
+      <KeyValueList columns={2} items={[
+        { label: "Employee account", value: member?.email ?? "" },
+        { label: "Send-as address", value: mailbox.email },
+      ]} />
+      <label className="flex items-center gap-2 text-sm"><input type="checkbox" checked={native} onChange={(e) => setNative(e.target.checked)} />Also install it inside the mail account when the policy allows native installation</label>
+      {check.data ? (
+        <div role="status" className="grid gap-1 rounded-md border p-3 text-sm">
+          <p>{check.data.message ?? "Checked."}</p>
+          {check.data.plain ? <p className="text-muted-foreground text-xs">Signature there today: {check.data.plain}</p> : null}
+        </div>
+      ) : null}
+      {check.error ? <ApiError error={check.error} title="The mail account could not be checked" /> : null}
+      {err && isConflict(err) ? (
+        <div className="grid gap-2">
+          <ApiError error={err} title="This mailbox changed since you opened it" />
+          <div><Button type="button" size="sm" variant="outline" onClick={() => { void deployments.refetch(); onCancel?.(); }}>Reload and start again</Button></div>
+        </div>
+      ) : err ? <ApiError error={err} title="Could not assign the signature" /> : null}
+      <div className="flex flex-wrap gap-2">
+        <Button type="button" variant="outline" disabled={!usable} loading={check.loading} onClick={() => void check.mutate(undefined)}>Check setup</Button>
+        <Button type="submit" disabled={!usable} loading={assign.loading}>{mailbox.deployment ? "Update assignment" : "Assign signature"}</Button>
+        {onCancel ? <Button type="button" variant="ghost" onClick={onCancel}>Cancel</Button> : null}
+      </div>
+      <ConfirmSpendDialog
+        open={confirm}
+        tier="external"
+        title={`Take over the signature of ${mailbox.email}?`}
+        affected={1}
+        description={<p>The signature this mailbox sends today is saved so it can be restored, then replaced by {templateId ? templateName(templates.data?.find((t) => t.id === templateId)) : "the default template"} for {memberLabel(member)}. New emails from this mailbox carry it.</p>}
+        confirmLabel="Take over signature"
+        confirming={assign.loading}
+        onCancel={() => setConfirm(false)}
+        onConfirm={() => void assign.mutate(undefined)}
+      />
+    </form>
+  );
+}