@stigmer/react 1.0.3 → 2.0.0

package/src/workflow/WorkflowNode.tsx

@@ -0,0 +1,151 @@
+"use client";
+
+import { memo } from "react";
+import type { NodeProps } from "@xyflow/react";
+import { CATEGORY_COLORS } from "./canvas-constants";
+import type { CanvasTaskNodeData } from "./workflow-graph-conversions";
+import { getVisualSpec } from "./task-type-visual-registry";
+import { NodeShell, NodeContent, NodeHandles, NodeActions, ExecutionBadge, BranchBadge, DiffBadge } from "./node-shell";
+import { useWorkflowGraphMode } from "./WorkflowGraphModeContext";
+
+const NESTED_TASK_KINDS = new Set(["fork", "for_each", "try_catch"]);
+
+/**
+ * Unified workflow node component for the React Flow canvas.
+ *
+ * Composes single-responsibility sub-components and adapts rendering
+ * based on the current graph mode (design / overview / execution):
+ * - `NodeShell` — visual shape boundary (CSS or SVG based on visual class)
+ * - `NodeContent` — task name + kind badge
+ * - `NodeHandles` — connection ports driven by the visual registry
+ * - `NodeActions` — design-mode only interaction affordances
+ * - `ExecutionBadge` — execution-mode only status badge
+ */
+export const WorkflowNode = memo(function WorkflowNode({
+  id,
+  data,
+  selected,
+}: NodeProps & { data: CanvasTaskNodeData }) {
+  const mode = useWorkflowGraphMode();
+  const visualSpec = getVisualSpec(data.isSentinel ? id : data.kindString);
+  const categoryColor = CATEGORY_COLORS[data.category];
+  const errorCount = data.errorCount ?? 0;
+  const isNested = NESTED_TASK_KINDS.has(data.kindString);
+  const executionState = data.executionState;
+  const diffState = data.diffState;
+
+  return (
+    <div
+      data-visual-class={data.visualClass}
+      data-task-kind={data.kindString}
+      data-execution-status={executionState?.status}
+      data-diff-status={diffState?.status}
+      aria-label={buildAriaLabel(data, errorCount, executionState?.status)}
+      role="button"
+      className="focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--stgm-ring,#3b82f6)] focus-visible:ring-offset-1 rounded-sm"
+    >
+      <NodeShell
+        visualClass={visualSpec.visualClass}
+        width={visualSpec.defaultWidth}
+        height={visualSpec.defaultHeight}
+        captionHeight={visualSpec.captionHeight}
+        categoryColor={categoryColor}
+        selected={selected}
+        errorCount={mode === "design" ? errorCount : 0}
+        executionStatus={executionState?.status}
+        diffStatus={mode === "diff" ? diffState?.status : undefined}
+      >
+        <NodeContent
+          visualClass={visualSpec.visualClass}
+          taskName={data.taskName}
+          displayName={data.displayName}
+          categoryColor={categoryColor}
+          captionHeight={visualSpec.captionHeight}
+          isNested={isNested}
+        />
+      </NodeShell>
+
+      {/* Validation badge — design mode only */}
+      {mode === "design" && errorCount > 0 && (
+        <span
+          className="absolute -right-1.5 -top-1.5 z-20 flex h-4 min-w-4 items-center justify-center rounded-full bg-[var(--stgm-destructive,#ef4444)] px-1 text-[9px] font-bold leading-none text-[var(--stgm-destructive-foreground,#fff)]"
+          title={`${errorCount} validation ${errorCount === 1 ? "error" : "errors"}`}
+        >
+          {errorCount}
+        </span>
+      )}
+
+      {/* Execution badge — execution mode only */}
+      {mode === "execution" && executionState && (
+        <ExecutionBadge
+          status={executionState.status}
+          attemptNumber={executionState.attemptNumber}
+          forkProgress={data.forkProgress ?? undefined}
+          approvalToolName={data.approvalToolName}
+          agentActivity={data.agentActivity ?? undefined}
+        />
+      )}
+
+      {/* Diff badge — diff mode only */}
+      {mode === "diff" && diffState && (
+        <DiffBadge
+          status={diffState.status}
+          changedFieldCount={diffState.changedFields?.length}
+        />
+      )}
+
+      <NodeHandles portPattern={visualSpec.portPattern} data={data} />
+
+      {/* Branch badge — design mode only, for container/branch nodes */}
+      {mode === "design" && isNested && (
+        <BranchBadge kindString={data.kindString} config={data.config} />
+      )}
+
+      {/* Design-mode actions — hidden in other modes */}
+      {mode === "design" && !data.isSentinel && (
+        <NodeActions nodeId={id} taskName={data.taskName} kindString={data.kindString} />
+      )}
+    </div>
+  );
+});
+
+function buildAriaLabel(
+  data: CanvasTaskNodeData,
+  errorCount: number,
+  executionStatus?: string,
+): string {
+  const base = `${data.displayName} node ${data.taskName}, ${data.ariaShapeLabel} shape`;
+  const parts = [base];
+
+  const config = data.config as Record<string, unknown>;
+  if (data.kindString === "switch_case" && Array.isArray(config.cases)) {
+    const caseNames = (config.cases as Array<Record<string, unknown>>)
+      .filter((c) => c && typeof c.name === "string")
+      .map((c) => c.name as string);
+    if (caseNames.length > 0) {
+      parts.push(`${caseNames.length} branches: ${caseNames.join(", ")}`);
+    }
+  } else if (data.kindString === "fork" && Array.isArray(config.branches)) {
+    const branchNames = (config.branches as Array<Record<string, unknown>>)
+      .filter((b) => b && typeof b.name === "string")
+      .map((b) => b.name as string);
+    if (branchNames.length > 0) {
+      const joinPolicy = config.compete === true ? "race mode" : "wait for all";
+      parts.push(`${branchNames.length} branches: ${branchNames.join(", ")}. Join policy: ${joinPolicy}`);
+    }
+  } else if (data.kindString === "try_catch" && config.catch && typeof config.catch === "object") {
+    const catchAs = (config.catch as Record<string, unknown>).as as string | undefined;
+    parts.push(`catch handler: ${catchAs || "error"}`);
+  } else if (data.kindString === "for_each") {
+    const par = (config.max_parallelism as number) || 0;
+    parts.push(par > 0 ? `concurrency: ${par}` : "sequential");
+  }
+
+  if (executionStatus && executionStatus !== "not_reached") {
+    parts.push(executionStatus.replace(/_/g, " "));
+  }
+  if (errorCount > 0) {
+    parts.push(`${errorCount} ${errorCount === 1 ? "error" : "errors"}`);
+  }
+  return parts.join(", ");
+}

package/src/workflow/WorkflowNodePopover.tsx

@@ -0,0 +1,168 @@
+"use client";
+
+import { memo, useCallback, useEffect, useRef } from "react";
+import { cn } from "@stigmer/theme";
+import type { CanvasTaskNodeData } from "./workflow-graph-conversions";
+import { kindToDisplayName, categorizeKind } from "./kind-metadata";
+import { CATEGORY_COLORS } from "./canvas-constants";
+
+/** Props for {@link WorkflowNodePopover}. */
+export interface WorkflowNodePopoverProps {
+  /** Node data from the clicked node. */
+  readonly data: CanvasTaskNodeData;
+  /** X position relative to the graph container. */
+  readonly x: number;
+  /** Y position relative to the graph container. */
+  readonly y: number;
+  /** Called to dismiss the popover. */
+  readonly onClose: () => void;
+  /**
+   * Called when the user clicks "Open in editor".
+   * Receives the task name so the host can switch to the editor tab.
+   */
+  readonly onOpenInEditor?: (taskName: string) => void;
+}
+
+/**
+ * Lightweight popover shown when clicking a node in the overview graph.
+ *
+ * Displays the task name, kind, category, and a brief config summary.
+ * Provides an "Open in editor" action link via callback prop.
+ *
+ * Positioned absolutely relative to the graph container at the click
+ * coordinates, with viewport clamping to stay within bounds.
+ */
+export const WorkflowNodePopover = memo(function WorkflowNodePopover({
+  data,
+  x,
+  y,
+  onClose,
+  onOpenInEditor,
+}: WorkflowNodePopoverProps) {
+  const ref = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    function handleClickOutside(e: MouseEvent) {
+      if (ref.current && !ref.current.contains(e.target as HTMLElement)) {
+        onClose();
+      }
+    }
+    function handleEscape(e: KeyboardEvent) {
+      if (e.key === "Escape") onClose();
+    }
+    document.addEventListener("mousedown", handleClickOutside);
+    document.addEventListener("keydown", handleEscape);
+    return () => {
+      document.removeEventListener("mousedown", handleClickOutside);
+      document.removeEventListener("keydown", handleEscape);
+    };
+  }, [onClose]);
+
+  const handleOpenInEditor = useCallback(() => {
+    onOpenInEditor?.(data.taskName);
+    onClose();
+  }, [onOpenInEditor, data.taskName, onClose]);
+
+  const displayName = kindToDisplayName(data.kindString);
+  const category = categorizeKind(data.kindString);
+  const categoryColor = CATEGORY_COLORS[category];
+  const configSummary = extractConfigSummary(data);
+
+  return (
+    <div
+      ref={ref}
+      role="dialog"
+      aria-label={`${data.taskName} task details`}
+      className={cn(
+        "absolute z-50 w-64 overflow-visible rounded-lg border border-[var(--stgm-border,#d4d4d8)]",
+        "bg-[var(--stgm-popover,#fff)] p-3 shadow-lg",
+        "text-[var(--stgm-popover-foreground,#1a1a2e)]",
+      )}
+      style={{
+        left: Math.min(x, (ref.current?.parentElement?.clientWidth ?? 800) - 272),
+        top: y + 8,
+        minWidth: "16rem",
+      }}
+    >
+      <div className="mb-2 flex items-center gap-2">
+        <span
+          className="inline-block h-2.5 w-2.5 shrink-0 rounded-full"
+          style={{ backgroundColor: categoryColor }}
+          aria-hidden="true"
+        />
+        <span className="truncate text-sm font-medium">{data.taskName}</span>
+      </div>
+
+      <div className="mb-2 flex items-center gap-2 text-xs text-[var(--stgm-muted-foreground,#737373)]">
+        <span className="rounded bg-[var(--stgm-muted,#f5f5f5)] px-1.5 py-0.5 font-medium">
+          {displayName}
+        </span>
+        <span className="capitalize">{category.replace(/_/g, " ")}</span>
+      </div>
+
+      {configSummary && (
+        <p className="mb-2 truncate text-xs text-[var(--stgm-muted-foreground,#737373)]">
+          {configSummary}
+        </p>
+      )}
+
+      {onOpenInEditor && (
+        <button
+          type="button"
+          onClick={handleOpenInEditor}
+          className={cn(
+            "mt-1 block w-full whitespace-nowrap rounded-md px-2.5 py-1.5 text-center text-xs font-medium",
+            "bg-[var(--stgm-primary,#6366f1)] text-[var(--stgm-primary-foreground,#fff)]",
+            "hover:bg-[var(--stgm-primary-hover,#4f46e5)]",
+            "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--stgm-ring,#6366f1)]",
+            "transition-colors",
+          )}
+        >
+          Open in editor
+        </button>
+      )}
+    </div>
+  );
+});
+
+function extractConfigSummary(data: CanvasTaskNodeData): string | null {
+  const config = data.config as Record<string, unknown> | undefined;
+  if (!config) return null;
+
+  switch (data.kindString) {
+    case "agent_call": {
+      const agent = config.agent as string | undefined;
+      return agent ? `Agent: ${agent}` : null;
+    }
+    case "call_http":
+    case "http_call": {
+      const method = (config.method as string) ?? "GET";
+      const url = config.url as string | undefined;
+      return url ? `${method.toUpperCase()} ${url}` : null;
+    }
+    case "call_llm":
+    case "llm_call": {
+      const model = config.model as string | undefined;
+      return model ? `Model: ${model}` : null;
+    }
+    case "switch_case": {
+      const cases = config.cases as unknown[];
+      return cases ? `${cases.length} case${cases.length === 1 ? "" : "s"}` : null;
+    }
+    case "fork": {
+      const branches = config.branches as unknown[];
+      return branches ? `${branches.length} branch${branches.length === 1 ? "" : "es"}` : null;
+    }
+    case "wait": {
+      const dur = config.duration as Record<string, unknown> | undefined;
+      const secs = dur?.seconds as number | undefined;
+      return secs ? `Wait ${secs}s` : null;
+    }
+    case "run_workflow": {
+      const wfRef = config.workflow_ref as string | undefined;
+      return wfRef ? `Workflow: ${wfRef}` : null;
+    }
+    default:
+      return null;
+  }
+}

package/src/workflow/WorkflowOverviewGraph.tsx

@@ -0,0 +1,267 @@
+"use client";
+
+import { memo, useCallback, useEffect, useMemo, useRef, useState } from "react";
+import {
+  ReactFlow,
+  Controls,
+  MiniMap,
+  Background,
+  BackgroundVariant,
+  MarkerType,
+  useReactFlow,
+  ReactFlowProvider,
+  applyNodeChanges,
+} from "@xyflow/react";
+import type { Node, NodeChange } from "@xyflow/react";
+import { cn } from "@stigmer/theme";
+import type { Workflow } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/api_pb";
+import { WorkflowNode } from "./WorkflowNode";
+import { CanvasTransitionEdge } from "./CanvasTransitionEdge";
+import { CANVAS_TASK_NODE_TYPE, CANVAS_TRANSITION_EDGE_TYPE } from "./workflow-graph-conversions";
+import type { CanvasTaskNodeData } from "./workflow-graph-conversions";
+import { WorkflowGraphModeProvider } from "./WorkflowGraphModeContext";
+import { useWorkflowOverviewGraph } from "./useWorkflowOverviewGraph";
+import { WorkflowNodePopover } from "./WorkflowNodePopover";
+import { getVisualSpec } from "./task-type-visual-registry";
+
+/** Props for {@link WorkflowOverviewGraph}. */
+export interface WorkflowOverviewGraphProps {
+  /** The workflow blueprint to visualize. */
+  readonly workflow: Workflow | null | undefined;
+  /**
+   * Called when the user clicks "Open in editor" in the node popover.
+   * Receives the task name so the caller can activate the editor tab
+   * and select the corresponding node.
+   */
+  readonly onOpenInEditor?: (taskName: string) => void;
+  /**
+   * Whether nodes can be dragged to rearrange the layout.
+   * Useful in fullscreen/presentation contexts where the user wants to
+   * manually position nodes for discussion. Does not persist changes.
+   * @default false
+   */
+  readonly nodesDraggable?: boolean;
+  /** Additional CSS class names for the root container. */
+  readonly className?: string;
+}
+
+const nodeTypes = {
+  [CANVAS_TASK_NODE_TYPE]: WorkflowNode,
+} as const;
+
+const edgeTypes = {
+  [CANVAS_TRANSITION_EDGE_TYPE]: CanvasTransitionEdge,
+} as const;
+
+const defaultEdgeOptions = {
+  markerEnd: { type: MarkerType.ArrowClosed, width: 16, height: 16 },
+};
+
+/**
+ * Read-only interactive workflow graph for the overview context.
+ *
+ * Renders the workflow blueprint in a React Flow canvas using the unified
+ * `WorkflowNode` / `CanvasTransitionEdge` rendering system in `"overview"` mode.
+ * Supports pan, zoom, minimap, and a click-to-inspect popover on task nodes.
+ *
+ * Designed for embedding in both the Stigmer Console and third-party
+ * dashboards — no routing, auth, or app-shell dependencies (DD-004).
+ *
+ * @example
+ * ```tsx
+ * <WorkflowOverviewGraph
+ *   workflow={workflow}
+ *   onOpenInEditor={(taskName) => switchToEditorTab(taskName)}
+ * />
+ * ```
+ */
+export const WorkflowOverviewGraph = memo(function WorkflowOverviewGraph(
+  props: WorkflowOverviewGraphProps,
+) {
+  return (
+    <ReactFlowProvider>
+      <WorkflowOverviewGraphInner
+        workflow={props.workflow}
+        onOpenInEditor={props.onOpenInEditor}
+        nodesDraggable={props.nodesDraggable}
+        className={props.className}
+      />
+    </ReactFlowProvider>
+  );
+});
+
+function WorkflowOverviewGraphInner({
+  workflow,
+  onOpenInEditor,
+  nodesDraggable: draggable = false,
+  className,
+}: WorkflowOverviewGraphProps) {
+  const {
+    nodes: baseNodes,
+    nodesWithSelection,
+    edges,
+    selectedTaskName,
+    setSelectedTaskName,
+  } = useWorkflowOverviewGraph({ workflow });
+
+  const { fitView } = useReactFlow();
+  const didFitRef = useRef(false);
+
+  // Track drag-repositioned nodes. Keyed by node ID → position.
+  // Resets when the underlying graph structure changes (workflow edited).
+  const [dragPositions, setDragPositions] = useState<Record<string, { x: number; y: number }>>({});
+
+  useEffect(() => {
+    setDragPositions({});
+  }, [baseNodes]);
+
+  const displayNodes = useMemo(() => {
+    if (!draggable || Object.keys(dragPositions).length === 0) {
+      return nodesWithSelection;
+    }
+    return nodesWithSelection.map((n) => {
+      const pos = dragPositions[n.id];
+      return pos ? { ...n, position: pos } : n;
+    });
+  }, [nodesWithSelection, draggable, dragPositions]);
+
+  const handleNodesChange = useCallback(
+    (changes: NodeChange[]) => {
+      if (!draggable) return;
+      const posChanges = changes.filter(
+        (c): c is NodeChange & { type: "position"; position: { x: number; y: number } } =>
+          c.type === "position" && "position" in c && c.position != null,
+      );
+      if (posChanges.length === 0) return;
+      setDragPositions((prev) => {
+        const next = { ...prev };
+        for (const c of posChanges) {
+          next[c.id] = c.position;
+        }
+        return next;
+      });
+    },
+    [draggable],
+  );
+
+  const [popoverAnchor, setPopoverAnchor] = useState<{
+    x: number;
+    y: number;
+    data: CanvasTaskNodeData;
+  } | null>(null);
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    if (nodesWithSelection.length > 0 && !didFitRef.current) {
+      didFitRef.current = true;
+      setTimeout(() => fitView({ padding: 0.15, duration: 300 }), 50);
+    }
+  }, [nodesWithSelection.length, fitView]);
+
+  const handleNodeClick = useCallback(
+    (event: React.MouseEvent, node: Node) => {
+      const data = node.data as CanvasTaskNodeData;
+      if (data.isSentinel) return;
+
+      const name = data.taskName;
+      const isDeselect = name === selectedTaskName;
+
+      if (isDeselect) {
+        setSelectedTaskName(null);
+        setPopoverAnchor(null);
+        return;
+      }
+
+      setSelectedTaskName(name);
+
+      const rect = containerRef.current?.getBoundingClientRect();
+      if (rect) {
+        setPopoverAnchor({
+          x: event.clientX - rect.left,
+          y: event.clientY - rect.top,
+          data,
+        });
+      }
+    },
+    [selectedTaskName, setSelectedTaskName],
+  );
+
+  const handlePaneClick = useCallback(() => {
+    setSelectedTaskName(null);
+    setPopoverAnchor(null);
+  }, [setSelectedTaskName]);
+
+  const handlePopoverClose = useCallback(() => {
+    setSelectedTaskName(null);
+    setPopoverAnchor(null);
+  }, [setSelectedTaskName]);
+
+  if (!workflow?.spec?.tasks?.length) {
+    return (
+      <div className={cn("flex h-full items-center justify-center text-sm text-[var(--stgm-muted-foreground,#737373)]", className)}>
+        No tasks to visualize
+      </div>
+    );
+  }
+
+  if (nodesWithSelection.length === 0) {
+    return (
+      <div className={cn("flex h-full items-center justify-center", className)}>
+        <GraphLoadingSkeleton />
+      </div>
+    );
+  }
+
+  return (
+    <WorkflowGraphModeProvider mode="overview">
+      <div ref={containerRef} className={cn("relative h-full w-full", className)}>
+        <ReactFlow
+          nodes={displayNodes}
+          edges={edges}
+          onNodesChange={draggable ? handleNodesChange : undefined}
+          nodeTypes={nodeTypes}
+          edgeTypes={edgeTypes}
+          defaultEdgeOptions={defaultEdgeOptions}
+          onNodeClick={handleNodeClick}
+          onPaneClick={handlePaneClick}
+          nodesDraggable={draggable}
+          nodesConnectable={false}
+          elementsSelectable={true}
+          panOnDrag={true}
+          zoomOnScroll={true}
+          fitView={false}
+          minZoom={0.2}
+          maxZoom={2}
+          proOptions={{ hideAttribution: true }}
+        >
+          <Background variant={BackgroundVariant.Dots} gap={16} size={1} />
+          <Controls showInteractive={false} />
+          <MiniMap pannable zoomable />
+        </ReactFlow>
+
+        {popoverAnchor && (
+          <WorkflowNodePopover
+            data={popoverAnchor.data}
+            x={popoverAnchor.x}
+            y={popoverAnchor.y}
+            onClose={handlePopoverClose}
+            onOpenInEditor={onOpenInEditor}
+          />
+        )}
+      </div>
+    </WorkflowGraphModeProvider>
+  );
+}
+
+function GraphLoadingSkeleton() {
+  return (
+    <div className="flex flex-col items-center gap-3">
+      <div className="h-8 w-8 animate-pulse rounded-full bg-[var(--stgm-muted,#e5e5e5)]" />
+      <div className="h-3 w-24 animate-pulse rounded bg-[var(--stgm-muted,#e5e5e5)]" />
+      <div className="mt-2 flex gap-4">
+        <div className="h-10 w-32 animate-pulse rounded-md bg-[var(--stgm-muted,#e5e5e5)]" />
+        <div className="h-10 w-32 animate-pulse rounded-md bg-[var(--stgm-muted,#e5e5e5)]" />
+      </div>
+    </div>
+  );
+}