@graph8/sdk 0.373.0 → 0.374.0

package/blocks/email-signatures/components/email-signatures-screen.tsx

@@ -0,0 +1,166 @@
+"use client";
+
+/**
+ * EmailSignaturesScreen: the finished workspace for managed email signatures. No props needed.
+ *
+ * Composes: ScreenLayout (title, tabs, stats), Toolbar (search), SplitView + DetailPanel (the selected template, deep link
+ * `?id=`), FormSheet (new template via SignatureTemplateForm), TemplatePreview, SignatureAssignTemplate,
+ * SignatureTemplateDetails, SignatureMailboxes, SignatureCampaigns, SignaturePolicy and SignatureReport.
+ *
+ * Tabs (`?tab=`): Templates (list and detail), Mailboxes, Campaigns, Policy, Report. A template's detail (`?id=`) has Preview,
+ * Edit, Use on mailboxes and Details; `&view=full` shows it as a full page.
+ *
+ * User flows: see every template (search; the list is complete because the API does not page it); create one with blocks,
+ * placeholders and a live preview; open it and preview it as a real employee on a real mailbox, in full, compact or campaign
+ * form, or as plain text; edit it (sends only after the full record has loaded; a stale save is refused and explained);
+ * apply it to chosen mailboxes, a department or everyone (confirmed with the real number of mailboxes); make it the
+ * organisation default or archive it (both confirmed). On the Mailboxes tab: assign an employee to a mailbox (check the setup
+ * first), push, restore the old signature and change what a mailbox sends, one by one or in bulk, each confirmed. Campaigns
+ * add a banner for a time window and can be previewed and tested against a mailbox and recipients. The Policy tab turns
+ * management off, on or enforced, sets the default and department templates. The Report tab reads impressions and clicks.
+ * The API has no variables list, template delete (only archive), campaign delete, asset upload or employee self-service
+ * (see the README for the gaps).
+ *
+ * SDK operations: none directly. Every call lives in the composed parts, which confirm every change to what a mailbox sends.
+ */
+
+import { useState } from "react";
+import type { ReactNode } from "react";
+import { PenLine, 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 { DetailPanel } from "@/g8/components/screen/detail-panel";
+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 { plural } from "@/g8/lib/plural";
+import { useSignatureDeployments, useSignaturePolicy, useSignatureTemplates } from "../hooks/use-signatures-data";
+import { LAYOUTS, POLICY_MODES, isManaged, templateName } from "../lib/signatures-types";
+import type { SignatureTemplate } from "../lib/signatures-types";
+import { SignatureAssignTemplate } from "./signature-assign-template";
+import { SignatureCampaigns } from "./signature-campaigns";
+import { SignatureMailboxes } from "./signature-mailboxes";
+import { SignaturePolicy } from "./signature-policy";
+import { SignatureReport } from "./signature-report";
+import { SignatureTemplateDetails } from "./signature-template-details";
+import { SignatureTemplateForm } from "./signature-template-form";
+import { TemplatePreview } from "./signature-preview";
+
+export interface EmailSignaturesScreenProps {
+  renderRowActions?: (template: SignatureTemplate) => ReactNode;
+  renderDetailActions?: (template: SignatureTemplate) => ReactNode;
+  extraDetailTabs?: { id: string; label: string; render: (template: SignatureTemplate) => ReactNode }[];
+  toolbarActions?: ReactNode;
+  className?: string;
+}
+
+type Tab = "templates" | "mailboxes" | "campaigns" | "policy" | "report";
+const TABS: Tab[] = ["templates", "mailboxes", "campaigns", "policy", "report"];
+
+export function EmailSignaturesScreen({ renderRowActions, renderDetailActions, extraDetailTabs, toolbarActions, className }: EmailSignaturesScreenProps) {
+  const [id, setId] = useUrlState("id", "");
+  const [view, setView] = useUrlState("view", "");
+  const [tabParam, setTabParam] = useUrlState("tab", "templates");
+  const tab = (TABS.includes(tabParam as Tab) ? tabParam : "templates") as Tab;
+  const [search, setSearch] = useState("");
+  const [creating, setCreating] = useState(false);
+  const [savedVersion, setSavedVersion] = useState<{ id: string; version: number } | null>(null);
+  const list = useSignatureTemplates();
+  const deployments = useSignatureDeployments();
+  const policy = useSignaturePolicy();
+
+  const all = list.data ?? [];
+  const q = search.trim().toLowerCase();
+  const shown = all.filter((t) => !q || templateName(t).toLowerCase().includes(q));
+  const selected = all.find((t) => t.id === id);
+  const defaultId = policy.data?.data.default_template_id;
+  const closeDetail = (): void => { setId(null); setView(null); };
+  const rows = deployments.data ?? [];
+
+  const listBody = list.error && !list.data ? <ApiError error={list.error} title="Could not load templates" 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" /><Skeleton className="h-14 w-full" /></div>
+  ) : shown.length === 0 ? (
+    <EmptyState icon={<PenLine className="size-8" />} title={all.length === 0 ? "No signature templates yet" : "No templates match"} description={all.length === 0 ? "A template is the shared design of your team's email signatures. Create one, then assign it to mailboxes." : "Try another search."} action={all.length === 0 ? <Button onClick={() => setCreating(true)}>Create your first template</Button> : undefined} />
+  ) : (
+    <>
+      <p role="status" className="text-muted-foreground mb-2 text-xs">{shown.length === all.length ? `All ${plural(all.length, "template")}` : `${shown.length.toLocaleString()} of ${plural(all.length, "template")}`}</p>
+      <ul className="grid gap-2">
+        {shown.map((t) => (
+          <li key={t.id} className={`flex flex-wrap items-center justify-between gap-2 rounded-md border p-3 ${t.id === id ? "bg-muted" : ""}`}>
+            <button type="button" className="min-w-0 flex-1 text-left" onClick={() => setId(t.id)}>
+              <span className="block truncate font-medium">{templateName(t)}</span>
+              <span className="text-muted-foreground block truncate text-xs">{LAYOUTS.find((l) => l.value === t.data?.layout)?.label ?? "Layout unknown"} · {plural((t.data?.blocks ?? []).length, "block")} · version {t.version}</span>
+            </button>
+            {t.id === defaultId ? <StatusPill tone="positive">Default</StatusPill> : null}
+            {renderRowActions?.(t)}
+          </li>
+        ))}
+      </ul>
+    </>
+  );
+
+  const detail = selected ? (
+    <DetailPanel
+      title={templateName(selected)}
+      subtitle={LAYOUTS.find((l) => l.value === selected.data?.layout)?.label}
+      badges={selected.id === defaultId ? <StatusPill tone="positive">Organisation default</StatusPill> : undefined}
+      actions={renderDetailActions?.(selected)}
+      onClose={closeDetail}
+      onExpand={() => setView("full")}
+      onCollapse={view === "full" ? () => setView(null) : undefined}
+      tabs={[
+        { id: "preview", label: "Preview", content: <TemplatePreview key={`${selected.id}:${selected.version}`} templateId={selected.id} /> },
+        { id: "edit", label: "Edit", content: (
+          <div className="grid gap-3">
+            {savedVersion?.id === selected.id && savedVersion.version === selected.version ? <p role="status" className="text-sm">Template saved as version {selected.version}. To install it again on the mailboxes that use it, push them from the Mailboxes tab.</p> : null}
+            <SignatureTemplateForm key={selected.id} template={selected} onSaved={(saved) => setSavedVersion({ id: saved.id, version: saved.version })} />
+          </div>
+        ) },
+        { id: "use", label: "Use on mailboxes", content: <SignatureAssignTemplate key={selected.id} template={selected} /> },
+        { id: "details", label: "Details", content: <SignatureTemplateDetails template={selected} onArchived={closeDetail} /> },
+        ...(extraDetailTabs ?? []).map((t) => ({ id: t.id, label: t.label, content: t.render(selected) })),
+      ]}
+    />
+  ) : null;
+
+  const templatesTab = (
+    <SplitView
+      list={<div className="grid gap-3"><Toolbar search={{ value: search, onChange: setSearch, placeholder: "Search templates" }} actions={toolbarActions} />{listBody}</div>}
+      detail={detail}
+      detailOpen={Boolean(selected)}
+      onCloseDetail={closeDetail}
+      expanded={view === "full"}
+      onExpandedChange={(e) => setView(e ? "full" : null)}
+      detailWidth="xl"
+    />
+  );
+
+  const mode = POLICY_MODES.find((m) => m.value === policy.data?.data.mode)?.label;
+  return (
+    <ScreenLayout
+      className={className}
+      title="Email signatures"
+      description="Design one signature for the team and keep every mailbox on it."
+      icon={<PenLine className="size-5" />}
+      actions={<Button size="sm" onClick={() => { setTabParam(null); setCreating(true); }}><Plus className="size-4" />New template</Button>}
+      tabs={[{ id: "templates", label: "Templates", count: list.data ? all.length : undefined }, { id: "mailboxes", label: "Mailboxes" }, { id: "campaigns", label: "Campaigns" }, { id: "policy", label: "Policy" }, { id: "report", label: "Report" }]}
+      activeTab={tab}
+      onTabChange={(next) => { setTabParam(next === "templates" ? null : next); closeDetail(); }}
+      stats={tab === "templates" ? [
+        { label: "Templates", value: list.data ? all.length.toLocaleString() : "..." },
+        { label: "Managed mailboxes", value: deployments.data ? rows.filter((d) => isManaged(d)).length.toLocaleString() : "..." },
+        { label: "Need attention", value: deployments.data ? rows.filter((d) => d.alert).length.toLocaleString() : "...", tone: rows.some((d) => d.alert) ? "negative" : undefined },
+        { label: "Management", value: mode ?? (policy.data ? "Not set" : policy.error ? "Unavailable" : "...") },
+      ] : undefined}
+    >
+      {tab === "templates" ? templatesTab : tab === "mailboxes" ? <SignatureMailboxes /> : tab === "campaigns" ? <SignatureCampaigns /> : tab === "policy" ? <SignaturePolicy /> : <SignatureReport />}
+      <FormSheet open={creating} onOpenChange={setCreating} width="xl" title="New signature template" description="Design the signature once. Nothing reaches a mailbox until you apply it.">
+        {creating ? <SignatureTemplateForm onCancel={() => setCreating(false)} onSaved={(created) => { setCreating(false); setId(created.id); }} /> : null}
+      </FormSheet>
+    </ScreenLayout>
+  );
+}

package/blocks/email-signatures/components/signature-assign-template.tsx

@@ -0,0 +1,119 @@
+"use client";
+
+/**
+ * SignatureAssignTemplate: point mailboxes at a template. Choose the mailboxes one by one, every mailbox of a department, or
+ * every mailbox; the API then queues a re-install on each.
+ *
+ * SDK operations, in order (the mailbox, member and deployment reads come from the shared hooks):
+ *   1. assignSignatureTemplate (POST /signatures/templates/{template_id}/assign)   write   replaces the signature the chosen mailboxes SEND:
+ *      ConfirmSpendDialog (external) first, sized from the mailboxes the choice really covers.
+ * Targets are exclusive (mailbox ids, a department, or all mailboxes) and every target must already have an employee
+ * assigned (Mailboxes tab); the API refuses the whole call otherwise, so those mailboxes are shown disabled with the reason.
+ * "All mailboxes" is only offered when every active mailbox is assigned and the list is complete. The result says how many
+ * mailboxes were queued; progress then shows in the Mailboxes tab.
+ */
+
+import { useState } from "react";
+import { Button } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { FirstNotice } from "@/g8/components/paging-notices";
+import { StatusPill } from "@/g8/components/screen/status-pill";
+import { g8Post } from "@/g8/lib/g8-client";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { plural } from "@/g8/lib/plural";
+import { MAILBOX_LIMIT, useSignatureMailboxes, useSignatureMembers } from "../hooks/use-signatures-data";
+import { isManaged, templateName } from "../lib/signatures-types";
+import type { SignatureTemplate } from "../lib/signatures-types";
+
+export interface SignatureAssignTemplateProps {
+  template: SignatureTemplate;
+  onAssigned?: (count: number) => void;
+}
+
+type Mode = "mailboxes" | "department" | "all";
+interface Result { count: number }
+
+const SELECT = "border-input bg-background h-9 rounded-md border px-2 text-sm";
+
+export function SignatureAssignTemplate({ template, onAssigned }: SignatureAssignTemplateProps) {
+  const box = useSignatureMailboxes();
+  const members = useSignatureMembers();
+  const [mode, setMode] = useState<Mode>("mailboxes");
+  const [picked, setPicked] = useState<number[]>([]);
+  const [department, setDepartment] = useState("");
+  const [confirm, setConfirm] = useState(false);
+  const [done, setDone] = useState<Result | null>(null);
+
+  const assigned = box.mailboxes.filter((m) => isManaged(m.deployment));
+  const unassigned = box.mailboxes.filter((m) => !isManaged(m.deployment));
+  const deptOf = (memberId: string | undefined): string | null => members.data?.find((x) => x.id === memberId)?.department ?? null;
+  const departments = [...new Set(assigned.map((m) => deptOf(m.deployment?.assignment?.member_id)).filter((d): d is string => Boolean(d)))].sort();
+  const inDepartment = assigned.filter((m) => deptOf(m.deployment?.assignment?.member_id) === department);
+  const allowAll = unassigned.length === 0 && !box.truncated && !box.mailboxesError && box.mailboxes.length > 0;
+  const covered = mode === "mailboxes" ? picked.filter((id) => assigned.some((m) => m.id === id)).length : mode === "department" ? inDepartment.length : box.mailboxes.length;
+  const ready = covered > 0 && (mode !== "department" || department !== "") && (mode !== "all" || allowAll);
+
+  const apply = useG8Mutation(async (): Promise<Result> => {
+    const body = mode === "mailboxes" ? { mailbox_ids: picked.filter((id) => assigned.some((m) => m.id === id)) } : mode === "department" ? { department } : { all_mailboxes: true };
+    return (await g8Post<Result>(`/signatures/templates/${encodeURIComponent(template.id)}/assign`, body)).data;
+  }, {
+    onSuccess: (r) => { setConfirm(false); setDone(r); setPicked([]); onAssigned?.(r.count); },
+    onError: () => setConfirm(false),
+    invalidates: [["signatures", "deployments"]],
+  });
+
+  if (box.loading) return <p className="text-muted-foreground text-sm" aria-busy="true">Loading mailboxes</p>;
+  if (box.error) return <ApiError error={box.error} title="Could not load mailboxes" onRetry={box.refetch} />;
+
+  return (
+    <div className="grid gap-3">
+      <p className="text-muted-foreground text-sm">Choose which mailboxes send {templateName(template)}. Each mailbox keeps its employee; only the template changes.</p>
+      <fieldset className="grid gap-1 text-sm">
+        <legend className="mb-1 font-medium">Apply to</legend>
+        <label className="flex items-center gap-2"><input type="radio" name="g8-sig-target" checked={mode === "mailboxes"} onChange={() => setMode("mailboxes")} />Chosen mailboxes</label>
+        <label className="flex items-center gap-2"><input type="radio" name="g8-sig-target" checked={mode === "department"} onChange={() => setMode("department")} />Every mailbox in a department</label>
+        <label className="flex items-center gap-2"><input type="radio" name="g8-sig-target" checked={mode === "all"} disabled={!allowAll} onChange={() => setMode("all")} />Every mailbox{allowAll ? "" : unassigned.length > 0 ? ` (${plural(unassigned.length, "mailbox")} still without an employee)` : " (the full list could not be confirmed)"}</label>
+      </fieldset>
+      {box.mailboxesError ? <ApiError compact error={box.mailboxesError} title="Mailboxes without a signature are not listed" onRetry={box.refetch} /> : null}
+      {mode === "mailboxes" ? (
+        <ul className="grid gap-1" aria-label="Mailboxes">
+          {box.mailboxes.map((m) => {
+            const ok = isManaged(m.deployment);
+            return (
+              <li key={m.id} className="flex items-center gap-2 text-sm">
+                <input type="checkbox" id={`g8-sig-mb-${m.id}`} disabled={!ok} checked={picked.includes(m.id)} onChange={(e) => setPicked(e.target.checked ? [...picked, m.id] : picked.filter((id) => id !== m.id))} />
+                <label htmlFor={`g8-sig-mb-${m.id}`}>{m.email}</label>
+                {!ok ? <StatusPill tone="neutral">No employee assigned</StatusPill> : null}
+              </li>
+            );
+          })}
+        </ul>
+      ) : null}
+      {mode === "department" ? (
+        <div className="grid gap-1">
+          <select aria-label="Department" className={SELECT} value={department} onChange={(e) => setDepartment(e.target.value)}>
+            <option value="">Choose a department</option>
+            {departments.map((d) => <option key={d} value={d}>{d}</option>)}
+          </select>
+          {departments.length === 0 ? <p className="text-muted-foreground text-xs">No assigned employee has a department yet.</p> : null}
+        </div>
+      ) : null}
+      <FirstNotice shown={box.mailboxes.length} limit={MAILBOX_LIMIT} noun="mailboxes" force={box.truncated} />
+      {apply.error ? <ApiError error={apply.error} title="Could not apply the template" /> : null}
+      {done ? <p role="status" className="text-sm">Queued {plural(done.count, "mailbox")} to install {templateName(template)}. Follow progress in the Mailboxes tab.</p> : null}
+      <div><Button type="button" disabled={!ready} onClick={() => setConfirm(true)}>Apply to {plural(covered, "mailbox")}</Button></div>
+      <ConfirmSpendDialog
+        open={confirm}
+        tier="external"
+        title={`Apply ${templateName(template)} to ${plural(covered, "mailbox")}?`}
+        affected={covered}
+        description="These mailboxes will send this signature on new emails. Emails already sent do not change. A mailbox can be given its old signature back from the Mailboxes tab unless the policy is enforced."
+        confirmLabel="Apply template"
+        confirming={apply.loading}
+        onCancel={() => setConfirm(false)}
+        onConfirm={() => void apply.mutate(undefined)}
+      />
+    </div>
+  );
+}

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>
+  );
+}