@carlonicora/nextjs-jsonapi 5.2.0 → 5.3.0

package/src/features/email-automation/components/canvas/buildCanvasGraph.ts

@@ -0,0 +1,141 @@
+import type { Edge, Node } from "@xyflow/react";
+import { autoLayout, LayoutEdge, LayoutNode } from "./shared";
+
+export const TRIGGER_NODE_ID = "trigger";
+export const TRIGGER_SOURCE_HANDLE = "trigger-source";
+export const STEP_NODE_PREFIX = "step:";
+export const STEP_SOURCE_HANDLE_PREFIX = "step-source-";
+export const STEP_TARGET_HANDLE_PREFIX = "step-target-";
+
+export const TRIGGER_NODE_WIDTH = 200;
+export const TRIGGER_NODE_HEIGHT = 56;
+export const STEP_NODE_WIDTH = 200;
+export const STEP_NODE_HEIGHT = 72;
+
+/**
+ * The fields the canvas reads from a step. `EmailAutomationStepInterface`
+ * satisfies it structurally; the narrow shape keeps this function pure and
+ * testable with plain objects.
+ */
+export type CanvasStep = {
+  id: string;
+  subject: string;
+  delayHours: number;
+  positionX?: number;
+  positionY?: number;
+  sentCount: number;
+  next?: { id: string };
+};
+
+export type TriggerNodeData = { label: string };
+
+export type EmailStepNodeData = {
+  stepId: string;
+  subject: string;
+  sentCount: number;
+  orphan: boolean;
+  manuallyPositioned: boolean;
+};
+
+export type DelayEdgeData = { targetStepId: string; delayHours: number };
+
+export type CanvasGraph = { nodes: Node[]; edges: Edge[]; orphanIds: string[] };
+
+/**
+ * The head is the oldest step with no incoming NEXT, exactly as the API picks
+ * it (`findHead`). `steps` arrive ordered by createdAt ASC from
+ * `findByAutomation`, so the first step nobody points at is the head.
+ */
+export function findHeadStepId(steps: CanvasStep[]): string | null {
+  const pointedAt = new Set(steps.map((s) => s.next?.id).filter((id): id is string => !!id));
+  return steps.find((s) => !pointedAt.has(s.id))?.id ?? null;
+}
+
+const stepNodeId = (stepId: string) => `${STEP_NODE_PREFIX}${stepId}`;
+
+/**
+ * Turns the automation's steps into React Flow nodes and edges: the trigger
+ * node, one node per step, a trigger→head edge, and one edge per NEXT link.
+ * Steps not reachable from the head (walking next→next) are orphans: they
+ * never send and render dashed.
+ */
+export function buildCanvasGraph(steps: CanvasStep[], triggerLabel: string): CanvasGraph {
+  const byId = new Map(steps.map((s) => [s.id, s]));
+  const headId = findHeadStepId(steps);
+
+  const chain = new Set<string>();
+  let cursor = headId ? byId.get(headId) : undefined;
+  while (cursor && !chain.has(cursor.id)) {
+    chain.add(cursor.id);
+    cursor = cursor.next ? byId.get(cursor.next.id) : undefined;
+  }
+  const orphanIds = steps.filter((s) => !chain.has(s.id)).map((s) => s.id);
+
+  const layoutNodes: LayoutNode[] = [
+    { id: TRIGGER_NODE_ID, width: TRIGGER_NODE_WIDTH, height: TRIGGER_NODE_HEIGHT, manuallyPositioned: false },
+    ...steps.map((s) => ({
+      id: stepNodeId(s.id),
+      width: STEP_NODE_WIDTH,
+      height: STEP_NODE_HEIGHT,
+      manuallyPositioned: typeof s.positionX === "number" && typeof s.positionY === "number",
+      x: s.positionX,
+      y: s.positionY,
+    })),
+  ];
+
+  const edges: Edge[] = [];
+  const layoutEdges: LayoutEdge[] = [];
+
+  const pushEdge = (source: string, sourceHandle: string, target: CanvasStep) => {
+    const data: DelayEdgeData = { targetStepId: target.id, delayHours: target.delayHours };
+    edges.push({
+      id: `next:${source}->${target.id}`,
+      source,
+      sourceHandle,
+      target: stepNodeId(target.id),
+      targetHandle: `${STEP_TARGET_HANDLE_PREFIX}${target.id}`,
+      type: "delayEdge",
+      label: `${target.delayHours}h`,
+      data,
+    });
+    layoutEdges.push({ source, target: stepNodeId(target.id) });
+  };
+
+  const head = headId ? byId.get(headId) : undefined;
+  if (head) pushEdge(TRIGGER_NODE_ID, TRIGGER_SOURCE_HANDLE, head);
+  for (const s of steps) {
+    const next = s.next ? byId.get(s.next.id) : undefined;
+    if (next) pushEdge(stepNodeId(s.id), `${STEP_SOURCE_HANDLE_PREFIX}${s.id}`, next);
+  }
+
+  const positions = autoLayout(layoutNodes, layoutEdges);
+
+  const nodes: Node[] = [
+    {
+      id: TRIGGER_NODE_ID,
+      type: "triggerNode",
+      position: positions[TRIGGER_NODE_ID],
+      deletable: false,
+      data: { data: { label: triggerLabel } satisfies TriggerNodeData },
+    },
+    ...steps.map((s) => {
+      const id = stepNodeId(s.id);
+      return {
+        id,
+        type: "emailStepNode",
+        position: positions[id],
+        data: {
+          data: {
+            stepId: s.id,
+            subject: s.subject,
+            sentCount: s.sentCount,
+            orphan: !chain.has(s.id),
+            manuallyPositioned: typeof s.positionX === "number" && typeof s.positionY === "number",
+          } satisfies EmailStepNodeData,
+        },
+      } satisfies Node;
+    }),
+  ];
+
+  return { nodes, edges, orphanIds };
+}

package/src/features/email-automation/components/canvas/edges/DelayEdge.tsx

@@ -0,0 +1,68 @@
+"use client";
+
+import { BaseEdge, Edge, EdgeLabelRenderer, EdgeProps, getBezierPath } from "@xyflow/react";
+import { useEmailAutomation } from "../../../contexts/EmailAutomationContext";
+import { DelayEdgeData } from "../buildCanvasGraph";
+
+type DelayEdgeType = Edge<DelayEdgeData>;
+
+/**
+ * ClueEdge recipe: a bezier with a label chip at its midpoint. The chip shows
+ * the target step's delay and opens that step's editor. It is a plain
+ * <button>: Base UI popovers do not work inside the React Flow canvas.
+ */
+export function DelayEdge({
+  id,
+  sourceX,
+  sourceY,
+  targetX,
+  targetY,
+  sourcePosition,
+  targetPosition,
+  label,
+  data,
+}: EdgeProps<DelayEdgeType>) {
+  const { select } = useEmailAutomation();
+  const [edgePath, labelX, labelY] = getBezierPath({
+    sourceX,
+    sourceY,
+    sourcePosition,
+    targetX,
+    targetY,
+    targetPosition,
+  });
+
+  const targetStepId = data?.targetStepId;
+
+  return (
+    <>
+      <BaseEdge id={id} path={edgePath} className="stroke-foreground/60" interactionWidth={24} />
+      <EdgeLabelRenderer>
+        {/* Inline position + pointer-events per React Flow docs: the label
+            portal sets pointer-events:none, so the label sets it back to
+            'all' and carries `nodrag nopan nowheel` for event isolation. */}
+        <div
+          className="nodrag nopan nowheel"
+          style={{
+            position: "absolute",
+            transform: `translate(-50%, -50%) translate(${labelX}px, ${labelY}px)`,
+            pointerEvents: "all",
+            zIndex: 1000,
+          }}
+          onMouseDown={(e) => e.stopPropagation()}
+        >
+          <button
+            type="button"
+            className="nodrag nopan bg-background hover:bg-accent text-foreground border-border h-auto rounded border px-2 py-1 text-xs tabular-nums shadow-sm"
+            onClick={(e) => {
+              e.stopPropagation();
+              if (targetStepId) select(targetStepId);
+            }}
+          >
+            {label}
+          </button>
+        </div>
+      </EdgeLabelRenderer>
+    </>
+  );
+}

package/src/features/email-automation/components/canvas/nodes/EmailStepNode.tsx

@@ -0,0 +1,43 @@
+"use client";
+
+import { Handle, Node, NodeProps, Position } from "@xyflow/react";
+import { MailIcon } from "lucide-react";
+import { useTranslations } from "next-intl";
+import { EmailStepNodeData, STEP_SOURCE_HANDLE_PREFIX, STEP_TARGET_HANDLE_PREFIX } from "../buildCanvasGraph";
+
+type EmailStepNodeType = Node<{ data: EmailStepNodeData }>;
+
+/**
+ * 200px card (SceneNode recipe): subject bold, "sent N" muted. An orphan (not
+ * reachable from the trigger, so it never sends) is the dashed, faded variant
+ * with a caption. Plain elements only: Base UI menus/popovers do not work
+ * inside React Flow nodes; clicks and context menus are handled by the canvas.
+ */
+export function EmailStepNode({ data }: NodeProps<EmailStepNodeType>) {
+  const d = data.data;
+  const t = useTranslations();
+
+  const shellClass = d.orphan
+    ? "border border-dashed border-foreground/30 bg-muted/40 opacity-60"
+    : "border bg-background border-foreground/25 text-foreground";
+
+  return (
+    <div className={`w-[200px] cursor-pointer rounded-md p-2 shadow-sm ${shellClass}`}>
+      <Handle type="target" position={Position.Left} id={`${STEP_TARGET_HANDLE_PREFIX}${d.stepId}`} />
+      <Handle type="source" position={Position.Right} id={`${STEP_SOURCE_HANDLE_PREFIX}${d.stepId}`} />
+
+      <div className="flex items-center gap-1 text-sm font-medium">
+        <MailIcon className="size-3 shrink-0" />
+        <span className="truncate">{d.subject}</span>
+      </div>
+
+      <div className="text-muted-foreground mt-1 text-xs tabular-nums">
+        {t("emailAutomations.canvas.sent", { count: d.sentCount })}
+      </div>
+
+      {d.orphan && (
+        <div className="text-muted-foreground mt-1 text-xs italic">{t("emailAutomations.canvas.orphan")}</div>
+      )}
+    </div>
+  );
+}

package/src/features/email-automation/components/canvas/nodes/TriggerNode.tsx

@@ -0,0 +1,23 @@
+"use client";
+
+import { Handle, Node, NodeProps, Position } from "@xyflow/react";
+import { ZapIcon } from "lucide-react";
+import { TRIGGER_SOURCE_HANDLE, TriggerNodeData } from "../buildCanvasGraph";
+
+// React Flow v12 requires the Node generic to carry the data shape.
+type TriggerNodeType = Node<{ data: TriggerNodeData }>;
+
+/**
+ * The fixed head of the chain (SecretTargetNode recipe). Source handle only:
+ * people enter here. Plain element, no Base UI inside the node; the click that
+ * opens EmailAutomationEditor is handled by the canvas (`onNodeClick`).
+ */
+export function TriggerNode({ data }: NodeProps<TriggerNodeType>) {
+  return (
+    <div className="bg-foreground text-background flex w-[200px] cursor-pointer items-center justify-center gap-1 rounded-full px-4 py-2 text-center shadow-md">
+      <ZapIcon className="size-3 shrink-0 opacity-60" />
+      <div className="truncate text-sm font-medium">{data.data.label}</div>
+      <Handle type="source" position={Position.Right} id={TRIGGER_SOURCE_HANDLE} />
+    </div>
+  );
+}

package/src/features/email-automation/components/canvas/shared/CanvasToolbar.tsx

@@ -0,0 +1,53 @@
+"use client";
+
+import { useReactFlow } from "@xyflow/react";
+import { ListRestartIcon, MaximizeIcon, MinusIcon, PlusIcon } from "lucide-react";
+import { useTranslations } from "next-intl";
+import { Button } from "../../../../../shadcnui";
+
+export function CanvasToolbar({ onTidy }: { onTidy: () => void | Promise<void> }) {
+  const t = useTranslations();
+  const { zoomIn, zoomOut, fitView } = useReactFlow();
+
+  return (
+    <div data-help="canvas.toolbar" className="absolute end-2 top-2 z-10 flex flex-col gap-1 max-md:top-14">
+      <Button
+        type="button"
+        variant="outline"
+        size="icon"
+        onClick={() => zoomIn()}
+        aria-label={t("canvas.toolbar.zoomIn")}
+      >
+        <PlusIcon className="h-4 w-4" />
+      </Button>
+      <Button
+        type="button"
+        variant="outline"
+        size="icon"
+        onClick={() => zoomOut()}
+        aria-label={t("canvas.toolbar.zoomOut")}
+      >
+        <MinusIcon className="h-4 w-4" />
+      </Button>
+      <Button
+        type="button"
+        variant="outline"
+        size="icon"
+        onClick={() => fitView({ duration: 300 })}
+        aria-label={t("canvas.toolbar.fitView")}
+      >
+        <MaximizeIcon className="h-4 w-4" />
+      </Button>
+      <Button
+        type="button"
+        variant="outline"
+        size="icon"
+        onClick={() => void onTidy()}
+        title={t("canvas.toolbar.tidyTooltip")}
+        aria-label={t("canvas.toolbar.tidy")}
+      >
+        <ListRestartIcon className="h-4 w-4" />
+      </Button>
+    </div>
+  );
+}

package/src/features/email-automation/components/canvas/shared/EmptyCanvas.tsx

@@ -0,0 +1,11 @@
+"use client";
+
+import type { ReactNode } from "react";
+
+export function EmptyCanvas({ children }: { children: ReactNode }) {
+  return (
+    <div className="text-muted-foreground flex h-full w-full items-center justify-center px-6 text-center text-sm">
+      {children}
+    </div>
+  );
+}

package/src/features/email-automation/components/canvas/shared/__tests__/autoLayout.spec.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it } from "vitest";
+import { autoLayout, LayoutEdge, LayoutNode } from "../autoLayout";
+
+describe("autoLayout", () => {
+  it("returns a position for every node", () => {
+    const nodes: LayoutNode[] = [
+      { id: "a", width: 200, height: 120, manuallyPositioned: false },
+      { id: "b", width: 200, height: 120, manuallyPositioned: false },
+    ];
+    const edges: LayoutEdge[] = [{ source: "a", target: "b" }];
+    const result = autoLayout(nodes, edges);
+    expect(Object.keys(result).sort()).toEqual(["a", "b"]);
+    expect(typeof result.a.x).toBe("number");
+    expect(typeof result.b.x).toBe("number");
+  });
+
+  it("respects manuallyPositioned: keeps pinned x/y verbatim", () => {
+    const nodes: LayoutNode[] = [
+      { id: "a", width: 200, height: 120, manuallyPositioned: true, x: 999, y: 888 },
+      { id: "b", width: 200, height: 120, manuallyPositioned: false },
+    ];
+    const edges: LayoutEdge[] = [{ source: "a", target: "b" }];
+    const result = autoLayout(nodes, edges);
+    expect(result.a).toEqual({ x: 999, y: 888 });
+    expect(result.b).not.toEqual({ x: 999, y: 888 });
+  });
+
+  it("is deterministic on identical input", () => {
+    const nodes: LayoutNode[] = [
+      { id: "a", width: 200, height: 120, manuallyPositioned: false },
+      { id: "b", width: 200, height: 120, manuallyPositioned: false },
+      { id: "c", width: 200, height: 120, manuallyPositioned: false },
+    ];
+    const edges: LayoutEdge[] = [
+      { source: "a", target: "b" },
+      { source: "b", target: "c" },
+    ];
+    const r1 = autoLayout(nodes, edges);
+    const r2 = autoLayout(nodes, edges);
+    expect(r1).toEqual(r2);
+  });
+});

package/src/features/email-automation/components/canvas/shared/__tests__/longPress.spec.ts

@@ -0,0 +1,51 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { createLongPressTracker } from "../longPress";
+
+describe("createLongPressTracker", () => {
+  beforeEach(() => vi.useFakeTimers());
+  afterEach(() => vi.useRealTimers());
+
+  it("fires after the hold delay with the press point", () => {
+    const onLongPress = vi.fn();
+    const tracker = createLongPressTracker({ onLongPress });
+    tracker.down("scene:1", 40, 50);
+    vi.advanceTimersByTime(499);
+    expect(onLongPress).not.toHaveBeenCalled();
+    vi.advanceTimersByTime(1);
+    expect(onLongPress).toHaveBeenCalledWith({ target: "scene:1", clientX: 40, clientY: 50 });
+  });
+
+  it("does not fire when the finger lifts early", () => {
+    const onLongPress = vi.fn();
+    const tracker = createLongPressTracker({ onLongPress });
+    tracker.down("scene:1", 0, 0);
+    vi.advanceTimersByTime(300);
+    tracker.up();
+    vi.advanceTimersByTime(500);
+    expect(onLongPress).not.toHaveBeenCalled();
+    expect(tracker.consumeClick()).toBe(false);
+  });
+
+  it("tolerates jitter but cancels on a real move (pan or drag)", () => {
+    const onLongPress = vi.fn();
+    const tracker = createLongPressTracker({ onLongPress });
+    tracker.down("scene:1", 0, 0);
+    tracker.move(5, 5);
+    vi.advanceTimersByTime(500);
+    expect(onLongPress).toHaveBeenCalledTimes(1);
+
+    tracker.down("scene:1", 0, 0);
+    tracker.move(20, 0);
+    vi.advanceTimersByTime(500);
+    expect(onLongPress).toHaveBeenCalledTimes(1);
+  });
+
+  it("swallows exactly one click after a fired press", () => {
+    const tracker = createLongPressTracker({ onLongPress: () => {} });
+    tracker.down("scene:1", 0, 0);
+    vi.advanceTimersByTime(500);
+    tracker.up();
+    expect(tracker.consumeClick()).toBe(true);
+    expect(tracker.consumeClick()).toBe(false);
+  });
+});

package/src/features/email-automation/components/canvas/shared/autoLayout.ts

@@ -0,0 +1,55 @@
+import dagre from "dagre";
+
+export type LayoutNode = {
+  id: string;
+  /** node body dimensions in canvas px — used by dagre to allocate space */
+  width: number;
+  height: number;
+  /** if true, dagre leaves position alone and uses these (x, y) verbatim */
+  manuallyPositioned: boolean;
+  x?: number;
+  y?: number;
+};
+
+export type LayoutEdge = {
+  source: string;
+  target: string;
+};
+
+export type LayoutResult = Record<string, { x: number; y: number }>;
+
+/**
+ * Deterministic LR layout. Pinned nodes keep their (x, y). Unpinned nodes
+ * are laid out by dagre and returned in the result map.
+ */
+export function autoLayout(nodes: LayoutNode[], edges: LayoutEdge[]): LayoutResult {
+  const g = new dagre.graphlib.Graph();
+  g.setGraph({ rankdir: "LR", nodesep: 60, ranksep: 100, marginx: 24, marginy: 24 });
+  g.setDefaultEdgeLabel(() => ({}));
+
+  for (const n of nodes) {
+    g.setNode(n.id, { width: n.width, height: n.height });
+  }
+  for (const e of edges) {
+    if (g.hasNode(e.source) && g.hasNode(e.target)) {
+      g.setEdge(e.source, e.target);
+    }
+  }
+
+  dagre.layout(g);
+
+  const result: LayoutResult = {};
+  for (const n of nodes) {
+    if (n.manuallyPositioned && typeof n.x === "number" && typeof n.y === "number") {
+      result[n.id] = { x: n.x, y: n.y };
+    } else {
+      const laid = g.node(n.id);
+      // dagre returns center coords; React Flow expects top-left, so subtract half dims.
+      result[n.id] = {
+        x: laid.x - n.width / 2,
+        y: laid.y - n.height / 2,
+      };
+    }
+  }
+  return result;
+}

package/src/features/email-automation/components/canvas/shared/index.ts

@@ -0,0 +1,4 @@
+export * from "./CanvasToolbar";
+export * from "./EmptyCanvas";
+export * from "./autoLayout";
+export * from "./longPress";

package/src/features/email-automation/components/canvas/shared/longPress.ts

@@ -0,0 +1,57 @@
+export const LONG_PRESS_MS = 500;
+export const LONG_PRESS_MOVE_TOLERANCE_PX = 10;
+
+/**
+ * Touch long-press detector for canvas nodes. A finger held still for
+ * LONG_PRESS_MS on a node fires `onLongPress` with the press point; any move
+ * beyond the tolerance (a pan or a node drag), a lift or a cancel aborts it.
+ * After a fired press, `consumeClick()` returns true once, so the caller can
+ * swallow the click that the finger lift produces.
+ */
+export function createLongPressTracker(params: {
+  onLongPress: (press: { target: string; clientX: number; clientY: number }) => void;
+  delayMs?: number;
+  moveTolerancePx?: number;
+  setTimer?: (fn: () => void, ms: number) => unknown;
+  clearTimer?: (handle: unknown) => void;
+}) {
+  const delay = params.delayMs ?? LONG_PRESS_MS;
+  const tolerance = params.moveTolerancePx ?? LONG_PRESS_MOVE_TOLERANCE_PX;
+  const setTimer = params.setTimer ?? ((fn: () => void, ms: number) => setTimeout(fn, ms));
+  const clearTimer = params.clearTimer ?? ((handle: unknown) => clearTimeout(handle as ReturnType<typeof setTimeout>));
+
+  let timer: unknown = null;
+  let start: { x: number; y: number } | null = null;
+  let fired = false;
+
+  const cancel = () => {
+    if (timer !== null) clearTimer(timer);
+    timer = null;
+    start = null;
+  };
+
+  return {
+    down(target: string, clientX: number, clientY: number) {
+      cancel();
+      fired = false;
+      start = { x: clientX, y: clientY };
+      timer = setTimer(() => {
+        timer = null;
+        start = null;
+        fired = true;
+        params.onLongPress({ target, clientX, clientY });
+      }, delay);
+    },
+    move(clientX: number, clientY: number) {
+      if (!start) return;
+      if (Math.hypot(clientX - start.x, clientY - start.y) > tolerance) cancel();
+    },
+    up: cancel,
+    cancel,
+    consumeClick(): boolean {
+      const wasFired = fired;
+      fired = false;
+      return wasFired;
+    },
+  };
+}

package/src/features/email-automation/components/containers/EmailAutomationContainer.tsx

@@ -0,0 +1,80 @@
+"use client";
+
+import { useTranslations } from "next-intl";
+import { RoundPageContainer } from "../../../../components";
+import { SharedProvider } from "../../../../contexts/SharedContext";
+import { Modules } from "../../../../core";
+import { usePageUrlGenerator } from "../../../../hooks";
+import { BreadcrumbItemData } from "../../../../interfaces";
+import { EmailAutomationProvider, useEmailAutomation } from "../../contexts/EmailAutomationContext";
+import { EmailAutomationActiveSwitch } from "../canvas/EmailAutomationActiveSwitch";
+import { EmailAutomationCanvasTab } from "../canvas/EmailAutomationCanvasTab";
+import { EmailAutomationEditor } from "../forms/EmailAutomationEditor";
+import { EmailAutomationRecipientsList } from "../lists/EmailAutomationRecipientsList";
+
+export type EmailAutomationContainerProps = {
+  automationId: string;
+};
+
+export function EmailAutomationContainer({ automationId }: EmailAutomationContainerProps) {
+  return (
+    <EmailAutomationProvider automationId={automationId}>
+      <EmailAutomationShell />
+    </EmailAutomationProvider>
+  );
+}
+
+function EmailAutomationShell() {
+  const t = useTranslations();
+  const generateUrl = usePageUrlGenerator();
+  const { automation, reload } = useEmailAutomation();
+
+  if (!automation) return null;
+
+  const breadcrumbs: BreadcrumbItemData[] = [
+    { name: t("emailAutomations.admin.title"), href: generateUrl({ page: Modules.EmailAutomation }) },
+    { name: automation.name },
+  ];
+
+  // The page chrome (title + header functions) is published here rather than by
+  // AdministrationProvider: SharedProvider replaces its value for the subtree,
+  // so this one carries the administration title type plus the automation name.
+  return (
+    <SharedProvider
+      value={{
+        breadcrumbs,
+        title: {
+          type: t("emailAutomations.admin.title"),
+          element: automation.name,
+          functions: [
+            <EmailAutomationActiveSwitch key="emailAutomationActiveSwitch" />,
+            <EmailAutomationEditor key="emailAutomationEditor" automation={automation} onSuccess={reload} />,
+          ],
+        },
+      }}
+    >
+      <RoundPageContainer
+        module={Modules.EmailAutomation}
+        id={automation.id}
+        fullWidth
+        forceHeader
+        // The canvas is sized h-full: it needs the viewport-bound shell and a
+        // fillHeight tab, or it resolves to zero height.
+        scroll="fixed"
+        tabs={[
+          {
+            sectionKey: "canvas",
+            label: t("emailAutomations.tabs.canvas"),
+            content: <EmailAutomationCanvasTab />,
+            fillHeight: true,
+          },
+          {
+            sectionKey: "recipients",
+            label: t("emailAutomations.tabs.recipients"),
+            content: <EmailAutomationRecipientsList />,
+          },
+        ]}
+      />
+    </SharedProvider>
+  );
+}

package/src/features/email-automation/components/containers/EmailAutomationsListContainer.tsx

@@ -0,0 +1,27 @@
+"use client";
+
+import { RoundPageContainer } from "../../../../components";
+import { Modules } from "../../../../core";
+import { AdministrationProvider } from "../../../administration/contexts/AdministrationContext";
+import { EmailAutomationsList } from "../lists/EmailAutomationsList";
+
+/**
+ * Page container for the administrative email-automation list.
+ *
+ * Client component by necessity: `module={Modules.EmailAutomation}` is a
+ * registry entry carrying an icon component and methods, which a Server
+ * Component cannot pass across the boundary. Routes mount this container
+ * instead — the same shape as every other list page.
+ *
+ * No `forceHeader`: ContentListTable draws its own header row with the title
+ * and the create action, exactly as the company and user list pages do.
+ */
+export function EmailAutomationsListContainer() {
+  return (
+    <AdministrationProvider>
+      <RoundPageContainer module={Modules.EmailAutomation} fullWidth>
+        <EmailAutomationsList fullWidth />
+      </RoundPageContainer>
+    </AdministrationProvider>
+  );
+}