@stigmer/react 1.0.4 → 2.0.0

package/src/workflow/motion-preference.ts

@@ -0,0 +1,49 @@
+/**
+ * Utility for respecting the user's motion preference (prefers-reduced-motion)
+ * in programmatic viewport animations (fitView, setCenter, etc.) that are NOT
+ * covered by the CSS-level reduced-motion rule in styles.css.
+ *
+ * React Flow's JS-driven animations (duration parameter on fitView/setCenter)
+ * bypass CSS media queries — they must be explicitly checked.
+ */
+
+let cachedPreference: boolean | null = null;
+let mediaQuery: MediaQueryList | null = null;
+
+function getMediaQuery(): MediaQueryList | null {
+  if (typeof window === "undefined") return null;
+  if (!mediaQuery) {
+    mediaQuery = window.matchMedia("(prefers-reduced-motion: reduce)");
+  }
+  return mediaQuery;
+}
+
+/**
+ * Returns true if the user prefers reduced motion.
+ * Caches the result and updates on media query change.
+ */
+export function prefersReducedMotion(): boolean {
+  if (typeof window === "undefined") return false;
+  const mq = getMediaQuery();
+  if (!mq) return false;
+
+  if (cachedPreference === null) {
+    cachedPreference = mq.matches;
+    mq.addEventListener("change", (e) => {
+      cachedPreference = e.matches;
+    });
+  }
+  return cachedPreference;
+}
+
+/**
+ * Returns 0 when the user prefers reduced motion, otherwise returns the
+ * desired duration. Use for all React Flow viewport animations.
+ *
+ * @example
+ * fitView({ duration: getAnimationDuration(300) });
+ * setCenter(x, y, { duration: getAnimationDuration(400) });
+ */
+export function getAnimationDuration(desiredMs: number): number {
+  return prefersReducedMotion() ? 0 : desiredMs;
+}

package/src/workflow/node-shell/BranchBadge.tsx

@@ -0,0 +1,125 @@
+"use client";
+
+import { memo, useMemo } from "react";
+import type { JsonObject } from "@bufbuild/protobuf";
+
+export interface BranchBadgeProps {
+  readonly kindString: string;
+  readonly config: JsonObject;
+}
+
+/**
+ * Decorative badge rendered below branch/container nodes in design mode.
+ *
+ * Shows contextual metadata:
+ * - fork: branch name chips + join policy
+ * - try_catch: catch handler indicator
+ * - for_each: iteration info (concurrency, error policy)
+ *
+ * @since T09 (Branch Management UX)
+ */
+export const BranchBadge = memo(function BranchBadge({
+  kindString,
+  config,
+}: BranchBadgeProps) {
+  const raw = config as Record<string, unknown>;
+
+  if (kindString === "fork") {
+    return <ForkBadge config={raw} />;
+  }
+
+  if (kindString === "try_catch") {
+    return <TryCatchBadge config={raw} />;
+  }
+
+  if (kindString === "for_each") {
+    return <ForEachBadge config={raw} />;
+  }
+
+  return null;
+});
+
+// ---------------------------------------------------------------------------
+
+function ForkBadge({ config }: { config: Record<string, unknown> }) {
+  const branches = useMemo(() => {
+    const raw = config.branches;
+    if (!Array.isArray(raw)) return [];
+    return raw
+      .filter((b): b is Record<string, unknown> => b != null && typeof b === "object")
+      .map((b) => (b.name as string) || "");
+  }, [config.branches]);
+
+  const compete = config.compete === true;
+
+  if (branches.length === 0) return null;
+
+  const maxVisible = 3;
+  const visible = branches.slice(0, maxVisible);
+  const overflow = branches.length > maxVisible ? branches.length - maxVisible : 0;
+
+  return (
+    <div className="absolute left-1/2 -translate-x-1/2 top-full mt-1 flex items-center gap-0.5 pointer-events-none">
+      {visible.map((name) => (
+        <span
+          key={name}
+          className="rounded bg-[var(--stgm-muted,#f5f5f5)] border border-[var(--stgm-border,#e5e5e5)] px-1 py-px text-[8px] font-medium text-[var(--stgm-muted-foreground,#737373)] whitespace-nowrap"
+        >
+          {name}
+        </span>
+      ))}
+      {overflow > 0 && (
+        <span className="text-[8px] text-[var(--stgm-muted-foreground,#737373)]">
+          +{overflow}
+        </span>
+      )}
+      {compete && (
+        <span className="ml-0.5 rounded bg-[var(--stgm-chart-amber,#f59e0b)]/10 border border-[var(--stgm-chart-amber,#f59e0b)]/30 px-1 py-px text-[8px] font-medium text-[var(--stgm-chart-amber,#f59e0b)] whitespace-nowrap">
+          race
+        </span>
+      )}
+    </div>
+  );
+}
+
+function TryCatchBadge({ config }: { config: Record<string, unknown> }) {
+  const catchBlock = config.catch;
+  if (!catchBlock || typeof catchBlock !== "object") return null;
+
+  const asVar = (catchBlock as Record<string, unknown>).as as string | undefined;
+
+  return (
+    <div className="absolute left-1/2 -translate-x-1/2 top-full mt-1 flex items-center gap-0.5 pointer-events-none">
+      <span className="rounded bg-[var(--stgm-destructive,#ef4444)]/10 border border-[var(--stgm-destructive,#ef4444)]/20 px-1 py-px text-[8px] font-medium text-[var(--stgm-destructive,#ef4444)] whitespace-nowrap">
+        catch: {asVar || "error"}
+      </span>
+    </div>
+  );
+}
+
+function ForEachBadge({ config }: { config: Record<string, unknown> }) {
+  const parallelism = (config.max_parallelism as number) || 0;
+  const onError = (config.on_error as string) || "";
+
+  const parts: string[] = [];
+  if (parallelism > 0) {
+    parts.push(`×${parallelism}`);
+  } else {
+    parts.push("seq");
+  }
+
+  const showErrorPolicy = parallelism > 0 && onError && onError !== "FOR_EACH_FAIL_FAST" && onError !== "FOR_EACH_ERROR_POLICY_UNSPECIFIED";
+
+  return (
+    <div className="absolute left-1/2 -translate-x-1/2 top-full mt-1 flex items-center gap-0.5 pointer-events-none">
+      <span className="rounded bg-[var(--stgm-muted,#f5f5f5)] border border-[var(--stgm-border,#e5e5e5)] px-1 py-px text-[8px] font-medium text-[var(--stgm-muted-foreground,#737373)] whitespace-nowrap">
+        ↻ {parts.join(" ")}
+      </span>
+      {showErrorPolicy && (
+        <span className="rounded bg-[var(--stgm-chart-amber,#f59e0b)]/10 border border-[var(--stgm-chart-amber,#f59e0b)]/30 px-1 py-px text-[8px] font-medium text-[var(--stgm-chart-amber,#f59e0b)] whitespace-nowrap">
+          {onError === "FOR_EACH_CONTINUE" ? "continue" : "skip"}
+        </span>
+      )}
+    </div>
+  );
+}

package/src/workflow/node-shell/DiffBadge.tsx

@@ -0,0 +1,72 @@
+"use client";
+
+import { memo } from "react";
+import { cn } from "@stigmer/theme";
+import type { NodeDiffStatus } from "../diff/types";
+
+export interface DiffBadgeProps {
+  readonly status: NodeDiffStatus;
+  /** Number of changed top-level config fields (shown for modified nodes). */
+  readonly changedFieldCount?: number;
+}
+
+/**
+ * Compact diff status badge rendered at the top-right corner of a workflow
+ * node in diff mode. Uses text/icon differentiation beyond color alone
+ * (WCAG 1.4.1 compliance).
+ *
+ * Mirrors the positioning and sizing pattern of {@link ExecutionBadge}.
+ */
+export const DiffBadge = memo(function DiffBadge({
+  status,
+  changedFieldCount,
+}: DiffBadgeProps) {
+  if (status === "unchanged") return null;
+
+  const { icon, label, className } = DIFF_BADGE_CONFIG[status];
+  const displayText =
+    status === "modified" && changedFieldCount != null && changedFieldCount > 0
+      ? `~${changedFieldCount}`
+      : icon;
+
+  return (
+    <span
+      className={cn(
+        "absolute -right-1.5 -top-1.5 z-20 flex h-5 min-w-5 items-center justify-center rounded-full px-1 text-[10px] font-semibold leading-none shadow-sm",
+        className,
+      )}
+      title={label}
+      aria-label={label}
+      data-diff-status={status}
+    >
+      {displayText}
+    </span>
+  );
+});
+
+interface DiffBadgeConfig {
+  icon: string;
+  label: string;
+  className: string;
+}
+
+const DIFF_BADGE_CONFIG: Record<
+  Exclude<NodeDiffStatus, "unchanged">,
+  DiffBadgeConfig
+> = {
+  added: {
+    icon: "+",
+    label: "Added",
+    className: "bg-[var(--stgm-success,#22c55e)] text-[var(--stgm-success-foreground,#fff)]",
+  },
+  removed: {
+    icon: "−",
+    label: "Removed",
+    className: "bg-[var(--stgm-destructive,#ef4444)] text-[var(--stgm-destructive-foreground,#fff)]",
+  },
+  modified: {
+    icon: "~",
+    label: "Modified",
+    className: "bg-[var(--stgm-warning,#f59e0b)] text-[var(--stgm-warning-foreground,#fff)]",
+  },
+};

package/src/workflow/node-shell/ExecutionBadge.tsx

@@ -0,0 +1,170 @@
+"use client";
+
+import { memo } from "react";
+import { cn } from "@stigmer/theme";
+import type { NodeExecutionStatus } from "../workflow-graph-conversions";
+
+/** Fork branch completion progress (T06). */
+export interface ForkProgressInfo {
+  readonly completed: number;
+  readonly total: number;
+  readonly compete: boolean;
+}
+
+/** Live agent activity summary for running agent_call nodes. */
+export interface AgentActivityInfo {
+  readonly agentSlug: string;
+  readonly currentToolName: string;
+  readonly messagesCount: number;
+  readonly toolCallsCount: number;
+}
+
+export interface ExecutionBadgeProps {
+  readonly status: NodeExecutionStatus;
+  readonly attemptNumber?: number;
+  /** Fork branch progress. When present on a running fork node, replaces the generic spinner. */
+  readonly forkProgress?: ForkProgressInfo;
+  /** Tool name awaiting approval. Displayed in the badge when status is waiting_approval. */
+  readonly approvalToolName?: string;
+  /** Live agent activity. When present on a running agent_call node, shows what the agent is doing. */
+  readonly agentActivity?: AgentActivityInfo;
+}
+
+/**
+ * Compact status badge rendered at the top-right corner of a workflow node
+ * in execution mode. Provides text/icon differentiation beyond color alone
+ * (WCAG 1.4.1 compliance).
+ *
+ * For fork nodes, displays branch completion progress (e.g. "1/3") when
+ * the fork is running and `forkProgress` is provided (T06).
+ *
+ * Uses the same positioning pattern as the validation error badge in
+ * `WorkflowNode.tsx`.
+ */
+export const ExecutionBadge = memo(function ExecutionBadge({
+  status,
+  attemptNumber,
+  forkProgress,
+  approvalToolName,
+  agentActivity,
+}: ExecutionBadgeProps) {
+  if (status === "not_reached" || status === "pending") return null;
+
+  // Approval-specific badge: show tool name when available.
+  if (status === "waiting_approval" && approvalToolName) {
+    const approvalLabel = `Awaiting approval: ${approvalToolName}`;
+    return (
+      <span
+        className={cn(
+          "absolute -right-1.5 -top-1.5 z-20 flex h-5 items-center gap-0.5 rounded-full px-1.5 text-[10px] font-semibold leading-none shadow-sm",
+          "bg-[var(--stgm-warning,#f59e0b)] text-[var(--stgm-warning-foreground,#fff)]",
+        )}
+        title={approvalLabel}
+        aria-label={approvalLabel}
+      >
+        ✋
+        <span className="max-w-[60px] truncate">{approvalToolName}</span>
+      </span>
+    );
+  }
+
+  // Agent activity badge: show what the agent is doing (tool name or message count).
+  if (status === "running" && agentActivity && (agentActivity.currentToolName || agentActivity.messagesCount > 0)) {
+    const displayText = agentActivity.currentToolName || `${agentActivity.messagesCount} msgs`;
+    const agentLabel = agentActivity.currentToolName
+      ? `Agent using tool: ${agentActivity.currentToolName}`
+      : `Agent: ${agentActivity.messagesCount} messages, ${agentActivity.toolCallsCount} tool calls`;
+
+    return (
+      <span
+        className={cn(
+          "absolute -right-1.5 -top-1.5 z-20 flex h-5 items-center gap-0.5 rounded-full px-1.5 text-[10px] font-semibold leading-none shadow-sm",
+          "bg-[var(--stgm-primary,#6366f1)] text-[var(--stgm-primary-foreground,#fff)]",
+        )}
+        title={agentLabel}
+        aria-label={agentLabel}
+      >
+        {agentActivity.currentToolName ? "🔧" : "💬"}
+        <span className="max-w-[60px] truncate">{displayText}</span>
+      </span>
+    );
+  }
+
+  // Fork-specific running badge: show branch progress instead of generic spinner.
+  if (status === "running" && forkProgress) {
+    const progressLabel = forkProgress.compete
+      ? `Fork race, ${forkProgress.completed} of ${forkProgress.total} branches completed`
+      : `Fork running, ${forkProgress.completed} of ${forkProgress.total} branches completed`;
+
+    return (
+      <span
+        className={cn(
+          "absolute -right-1.5 -top-1.5 z-20 flex h-5 min-w-5 items-center justify-center rounded-full px-1.5 text-[10px] font-semibold leading-none shadow-sm",
+          "bg-[var(--stgm-primary,#6366f1)] text-[var(--stgm-primary-foreground,#fff)]",
+        )}
+        title={progressLabel}
+        aria-label={progressLabel}
+      >
+        {forkProgress.completed}/{forkProgress.total}
+        {forkProgress.compete && <span className="ml-0.5">⚡</span>}
+      </span>
+    );
+  }
+
+  const { icon, label, className } = BADGE_CONFIG[status];
+
+  return (
+    <span
+      className={cn(
+        "absolute -right-1.5 -top-1.5 z-20 flex h-5 min-w-5 items-center justify-center rounded-full px-1 text-[10px] font-semibold leading-none shadow-sm",
+        className,
+      )}
+      title={label + (attemptNumber && attemptNumber > 1 ? ` (attempt ${attemptNumber})` : "")}
+      aria-label={label}
+    >
+      {icon}
+      {status === "retrying" && attemptNumber != null && attemptNumber > 1 && (
+        <span className="ml-0.5">{attemptNumber}</span>
+      )}
+    </span>
+  );
+});
+
+interface BadgeConfig {
+  icon: string;
+  label: string;
+  className: string;
+}
+
+const BADGE_CONFIG: Record<Exclude<NodeExecutionStatus, "not_reached" | "pending">, BadgeConfig> = {
+  running: {
+    icon: "⟳",
+    label: "Running",
+    className: "bg-[var(--stgm-primary,#6366f1)] text-[var(--stgm-primary-foreground,#fff)]",
+  },
+  completed: {
+    icon: "✓",
+    label: "Completed",
+    className: "bg-[var(--stgm-success,#22c55e)] text-[var(--stgm-success-foreground,#fff)]",
+  },
+  failed: {
+    icon: "✕",
+    label: "Failed",
+    className: "bg-[var(--stgm-destructive,#ef4444)] text-[var(--stgm-destructive-foreground,#fff)]",
+  },
+  skipped: {
+    icon: "—",
+    label: "Skipped",
+    className: "bg-[var(--stgm-muted,#e5e5e5)] text-[var(--stgm-muted-foreground,#737373)]",
+  },
+  retrying: {
+    icon: "↻",
+    label: "Retrying",
+    className: "bg-[var(--stgm-warning,#f59e0b)] text-[var(--stgm-warning-foreground,#fff)]",
+  },
+  waiting_approval: {
+    icon: "✋",
+    label: "Waiting for approval",
+    className: "bg-[var(--stgm-warning,#f59e0b)] text-[var(--stgm-warning-foreground,#fff)]",
+  },
+};