@stigmer/react 1.0.4 → 2.0.1

package/src/workflow/task-type-visual-registry.ts

@@ -0,0 +1,222 @@
+import {
+  CANVAS_NODE_WIDTH,
+  CANVAS_NODE_HEIGHT,
+  SENTINEL_NODE_WIDTH,
+  SENTINEL_NODE_HEIGHT,
+} from "./canvas-constants";
+
+/**
+ * Semantic shape identifier for workflow nodes.
+ *
+ * Each visual class maps to a distinct SVG shape that communicates the
+ * task's structural role at a glance:
+ *
+ * - `task-card` — rounded rectangle for general work tasks
+ * - `decision-diamond` — rotated square for conditional branching
+ * - `parallel-bar` — wide horizontal bar for parallel splits
+ * - `event-circle` — circle for events, signals, and timing
+ * - `gate-octagon` — octagon for human review gates (stop sign metaphor)
+ * - `subworkflow-card` — double-border card for sub-workflow invocations
+ * - `container` — rounded container for tasks with nested children
+ * - `terminal-pill` — pill/capsule for start and end sentinels
+ */
+export type VisualClass =
+  | "task-card"
+  | "decision-diamond"
+  | "parallel-bar"
+  | "event-circle"
+  | "gate-octagon"
+  | "subworkflow-card"
+  | "container"
+  | "terminal-pill";
+
+/**
+ * Describes how a task kind's connection handles are structured.
+ *
+ * T02 (NodeShell) reads this to render the appropriate React Flow Handles.
+ * T01 defines the patterns; T02 implements the rendering.
+ */
+export type PortPattern =
+  | "standard"
+  | "branch-per-case"
+  | "branch-per-outcome"
+  | "branch-per-branch"
+  | "container"
+  | "source-only"
+  | "sink-only";
+
+/**
+ * Visual specification for a single workflow task kind.
+ *
+ * Combines shape, dimension, port, and accessibility metadata.
+ * The layout engine (dagre today, ELK in T03) uses `defaultWidth`
+ * and `defaultHeight + captionHeight` for node sizing. The renderer
+ * (T02 NodeShell) uses `visualClass` to select the SVG shape component.
+ *
+ * For non-rectangular shapes (diamond, octagon, circle), the task name
+ * renders as an external caption BELOW the shape. `captionHeight` reserves
+ * space for this caption in the layout bounding box. The SVG shape itself
+ * renders at `defaultHeight`, and the full layout allocation is
+ * `defaultHeight + captionHeight`.
+ */
+export interface TaskTypeVisualSpec {
+  readonly visualClass: VisualClass;
+  readonly defaultWidth: number;
+  readonly defaultHeight: number;
+  /**
+   * Height reserved for the task name caption below the shape.
+   * 0 for shapes with internal text (cards, bars, pills).
+   * >0 for non-rectangular shapes where text is placed externally.
+   */
+  readonly captionHeight: number;
+  readonly portPattern: PortPattern;
+  readonly isContainer: boolean;
+  readonly ariaShapeLabel: string;
+}
+
+const TASK_CARD: TaskTypeVisualSpec = {
+  visualClass: "task-card",
+  defaultWidth: CANVAS_NODE_WIDTH,
+  defaultHeight: CANVAS_NODE_HEIGHT,
+  captionHeight: 0,
+  portPattern: "standard",
+  isContainer: false,
+  ariaShapeLabel: "card",
+} as const;
+
+const DECISION_DIAMOND: TaskTypeVisualSpec = {
+  visualClass: "decision-diamond",
+  defaultWidth: 140,
+  defaultHeight: 120,
+  captionHeight: 24,
+  portPattern: "branch-per-case",
+  isContainer: false,
+  ariaShapeLabel: "diamond",
+} as const;
+
+const PARALLEL_BAR: TaskTypeVisualSpec = {
+  visualClass: "parallel-bar",
+  defaultWidth: 260,
+  defaultHeight: 32,
+  captionHeight: 0,
+  portPattern: "branch-per-branch",
+  isContainer: false,
+  ariaShapeLabel: "horizontal bar",
+} as const;
+
+const EVENT_CIRCLE: TaskTypeVisualSpec = {
+  visualClass: "event-circle",
+  defaultWidth: 80,
+  defaultHeight: 70,
+  captionHeight: 20,
+  portPattern: "standard",
+  isContainer: false,
+  ariaShapeLabel: "circle",
+} as const;
+
+const GATE_OCTAGON: TaskTypeVisualSpec = {
+  visualClass: "gate-octagon",
+  defaultWidth: 160,
+  defaultHeight: 140,
+  captionHeight: 24,
+  portPattern: "branch-per-outcome",
+  isContainer: false,
+  ariaShapeLabel: "octagon",
+} as const;
+
+const SUBWORKFLOW_CARD: TaskTypeVisualSpec = {
+  visualClass: "subworkflow-card",
+  defaultWidth: CANVAS_NODE_WIDTH,
+  defaultHeight: CANVAS_NODE_HEIGHT,
+  captionHeight: 0,
+  portPattern: "standard",
+  isContainer: false,
+  ariaShapeLabel: "sub-workflow card",
+} as const;
+
+const CONTAINER: TaskTypeVisualSpec = {
+  visualClass: "container",
+  defaultWidth: 280,
+  defaultHeight: 120,
+  captionHeight: 0,
+  portPattern: "container",
+  isContainer: true,
+  ariaShapeLabel: "container",
+} as const;
+
+const TERMINAL_PILL: TaskTypeVisualSpec = {
+  visualClass: "terminal-pill",
+  defaultWidth: SENTINEL_NODE_WIDTH,
+  defaultHeight: SENTINEL_NODE_HEIGHT,
+  captionHeight: 0,
+  portPattern: "source-only",
+  isContainer: false,
+  ariaShapeLabel: "pill",
+} as const;
+
+const TERMINAL_PILL_END: TaskTypeVisualSpec = {
+  ...TERMINAL_PILL,
+  portPattern: "sink-only",
+} as const;
+
+/**
+ * Static registry mapping every workflow task kind string to its
+ * visual specification.
+ *
+ * Includes all 20 `WorkflowTaskKind` enum values plus the two
+ * sentinel pseudo-kinds (`__start__`, `__end__`).
+ *
+ * Frozen to prevent accidental mutation — this is static metadata
+ * that must not change at runtime.
+ */
+export const VISUAL_REGISTRY: ReadonlyMap<string, TaskTypeVisualSpec> = Object.freeze(
+  new Map<string, TaskTypeVisualSpec>([
+    // ai
+    ["agent_call", TASK_CARD],
+    ["llm_call", TASK_CARD],
+    ["eval", TASK_CARD],
+
+    // control_flow
+    ["switch_case", DECISION_DIAMOND],
+    ["for_each", CONTAINER],
+    ["fork", PARALLEL_BAR],
+    ["try_catch", CONTAINER],
+    ["wait", EVENT_CIRCLE],
+
+    // invocation
+    ["http_call", TASK_CARD],
+    ["grpc_call", TASK_CARD],
+    ["activity_call", TASK_CARD],
+    ["run_workflow", SUBWORKFLOW_CARD],
+
+    // data
+    ["set_vars", TASK_CARD],
+    ["transform", TASK_CARD],
+    ["validate", TASK_CARD],
+
+    // governance
+    ["human_input", GATE_OCTAGON],
+
+    // event
+    ["listen", EVENT_CIRCLE],
+    ["emit_event", EVENT_CIRCLE],
+    ["notification", EVENT_CIRCLE],
+    ["raise_error", EVENT_CIRCLE],
+
+    // sentinels
+    ["__start__", TERMINAL_PILL],
+    ["__end__", TERMINAL_PILL_END],
+  ]),
+);
+
+const DEFAULT_SPEC: TaskTypeVisualSpec = TASK_CARD;
+
+/**
+ * Returns the visual specification for a task kind string.
+ *
+ * Falls back to `task-card` for unknown kinds, ensuring a valid spec
+ * is always returned even for future task kinds not yet in the registry.
+ */
+export function getVisualSpec(kind: string): TaskTypeVisualSpec {
+  return VISUAL_REGISTRY.get(kind) ?? DEFAULT_SPEC;
+}

package/src/workflow/templates/WorkflowTemplateCard.tsx

@@ -0,0 +1,176 @@
+"use client";
+
+import { useCallback, useMemo } from "react";
+import { cn } from "@stigmer/theme";
+import type { WorkflowTemplate, WorkflowTemplateMeta } from "./types";
+import { PATTERN_LABELS } from "./types";
+import { deriveTemplateMeta } from "./derive-template-metadata";
+import { TEMPLATE_CATEGORY_LABELS } from "../../resource-creation/templates/types";
+
+export interface WorkflowTemplateCardProps {
+  readonly template: WorkflowTemplate;
+  readonly onSelect: (template: WorkflowTemplate) => void;
+  readonly onPreview?: (template: WorkflowTemplate) => void;
+  readonly className?: string;
+}
+
+const CATEGORY_COLORS: Record<string, string> = {
+  "customer-support": "bg-blue-500/10 text-blue-700 dark:text-blue-400",
+  "code-review": "bg-violet-500/10 text-violet-700 dark:text-violet-400",
+  "data-analysis": "bg-amber-500/10 text-amber-700 dark:text-amber-400",
+  devops: "bg-emerald-500/10 text-emerald-700 dark:text-emerald-400",
+  content: "bg-pink-500/10 text-pink-700 dark:text-pink-400",
+  integration: "bg-cyan-500/10 text-cyan-700 dark:text-cyan-400",
+  general: "bg-muted text-muted-foreground",
+};
+
+const PATTERN_COLORS: Record<string, string> = {
+  parallel: "bg-violet-500/10 text-violet-700 dark:text-violet-400",
+  branching: "bg-amber-500/10 text-amber-700 dark:text-amber-400",
+  hitl: "bg-emerald-500/10 text-emerald-700 dark:text-emerald-400",
+  loop: "bg-pink-500/10 text-pink-700 dark:text-pink-400",
+  "error-handling": "bg-red-500/10 text-red-700 dark:text-red-400",
+  batch: "bg-cyan-500/10 text-cyan-700 dark:text-cyan-400",
+  "ai-pipeline": "bg-blue-500/10 text-blue-700 dark:text-blue-400",
+  "http-integration": "bg-orange-500/10 text-orange-700 dark:text-orange-400",
+};
+
+/**
+ * Enhanced template card for workflow templates.
+ *
+ * Shows the template name, description, category badge, pattern badges,
+ * task count, and env var count. Click selects the template; an optional
+ * preview button opens the graph preview dialog.
+ */
+export function WorkflowTemplateCard({
+  template,
+  onSelect,
+  onPreview,
+  className,
+}: WorkflowTemplateCardProps) {
+  const meta: WorkflowTemplateMeta = useMemo(
+    () => deriveTemplateMeta(template.data.yaml ?? ""),
+    [template.data.yaml],
+  );
+
+  const handleClick = useCallback(() => {
+    onSelect(template);
+  }, [onSelect, template]);
+
+  const handlePreview = useCallback(
+    (e: React.MouseEvent) => {
+      e.stopPropagation();
+      onPreview?.(template);
+    },
+    [onPreview, template],
+  );
+
+  const handleKeyDown = useCallback(
+    (e: React.KeyboardEvent) => {
+      if (e.key === "Enter" || e.key === " ") {
+        e.preventDefault();
+        onSelect(template);
+      }
+    },
+    [onSelect, template],
+  );
+
+  const categoryLabel =
+    TEMPLATE_CATEGORY_LABELS[template.category] ?? template.category;
+
+  return (
+    <div
+      role="button"
+      tabIndex={0}
+      onClick={handleClick}
+      onKeyDown={handleKeyDown}
+      aria-label={`Use ${template.name} template`}
+      className={cn(
+        "group flex cursor-pointer flex-col gap-3 rounded-lg border border-border bg-card p-4",
+        "transition-colors hover:border-primary hover:bg-accent",
+        "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+        className,
+      )}
+    >
+      {/* Header: name + category */}
+      <div className="flex items-start justify-between gap-2">
+        <div className="min-w-0 flex-1">
+          <p className="text-sm font-medium text-foreground">
+            {template.name}
+          </p>
+          <span
+            className={cn(
+              "mt-1 inline-block rounded-full px-2 py-0.5 text-[10px] font-medium",
+              CATEGORY_COLORS[template.category] ?? CATEGORY_COLORS.general,
+            )}
+          >
+            {categoryLabel}
+          </span>
+        </div>
+        {onPreview && (
+          <button
+            type="button"
+            onClick={handlePreview}
+            aria-label={`Preview ${template.name}`}
+            className={cn(
+              "rounded-md p-1 text-muted-foreground opacity-0 transition-opacity",
+              "hover:bg-accent hover:text-accent-foreground",
+              "focus-visible:opacity-100 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+              "group-hover:opacity-100",
+            )}
+          >
+            <PreviewIcon />
+          </button>
+        )}
+      </div>
+
+      {/* Description */}
+      <p className="line-clamp-2 text-xs leading-relaxed text-muted-foreground">
+        {template.description}
+      </p>
+
+      {/* Pattern badges */}
+      {meta.patterns.length > 0 && (
+        <div className="flex flex-wrap gap-1">
+          {meta.patterns.slice(0, 3).map((pattern) => (
+            <span
+              key={pattern}
+              className={cn(
+                "rounded px-1.5 py-0.5 text-[10px] font-medium",
+                PATTERN_COLORS[pattern] ?? "bg-muted text-muted-foreground",
+              )}
+            >
+              {PATTERN_LABELS[pattern]}
+            </span>
+          ))}
+        </div>
+      )}
+
+      {/* Metadata chips */}
+      <div className="flex items-center gap-3 text-[10px] text-muted-foreground">
+        <span>{meta.taskCount} tasks</span>
+        {meta.envVarCount > 0 && <span>{meta.envVarCount} env vars</span>}
+        {meta.hasBudget && <span>Budget</span>}
+      </div>
+    </div>
+  );
+}
+
+function PreviewIcon() {
+  return (
+    <svg
+      className="size-4"
+      xmlns="http://www.w3.org/2000/svg"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={2}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <path d="M2 12s3-7 10-7 10 7 10 7-3 7-10 7-10-7-10-7Z" />
+      <circle cx={12} cy={12} r={3} />
+    </svg>
+  );
+}

package/src/workflow/templates/WorkflowTemplateGallery.tsx

@@ -0,0 +1,221 @@
+"use client";
+
+import { useCallback, useState, type ReactNode } from "react";
+import { cn } from "@stigmer/theme";
+import type { WorkflowTemplate } from "./types";
+import { WORKFLOW_CATEGORY_LABELS } from "./types";
+import { useTemplateFilter } from "../../resource-creation/useTemplateFilter";
+import type { WorkflowTemplateData } from "./types";
+import { WorkflowTemplateCard } from "./WorkflowTemplateCard";
+import { WorkflowTemplatePreview } from "./WorkflowTemplatePreview";
+
+export interface WorkflowTemplateGalleryProps {
+  readonly templates: readonly WorkflowTemplate[];
+  readonly onSelect: (template: WorkflowTemplate) => void;
+  readonly emptyContent?: ReactNode;
+  readonly className?: string;
+}
+
+/**
+ * Searchable, filterable gallery of workflow templates.
+ *
+ * Composes the headless `useTemplateFilter` hook with workflow-specific
+ * `WorkflowTemplateCard` components. Includes an integrated preview
+ * dialog — clicking the eye icon on a card opens a graph preview
+ * before committing to the template.
+ *
+ * Keyboard navigation follows the same pattern as the generic
+ * `TemplateGallery`: Tab between search/tabs/cards, Arrow keys
+ * navigate tabs, Enter/Space activates.
+ */
+export function WorkflowTemplateGallery({
+  templates,
+  onSelect,
+  emptyContent,
+  className,
+}: WorkflowTemplateGalleryProps) {
+  const {
+    filtered,
+    query,
+    setQuery,
+    activeCategory,
+    setActiveCategory,
+    availableCategories,
+  } = useTemplateFilter<WorkflowTemplateData>({ templates });
+
+  const [previewTemplate, setPreviewTemplate] =
+    useState<WorkflowTemplate | null>(null);
+
+  const handlePreview = useCallback((template: WorkflowTemplate) => {
+    setPreviewTemplate(template);
+  }, []);
+
+  const handlePreviewClose = useCallback(() => {
+    setPreviewTemplate(null);
+  }, []);
+
+  const handlePreviewSelect = useCallback(
+    (template: WorkflowTemplate) => {
+      setPreviewTemplate(null);
+      onSelect(template);
+    },
+    [onSelect],
+  );
+
+  const handleTabKeyDown = useCallback(
+    (e: React.KeyboardEvent<HTMLDivElement>) => {
+      const tabs =
+        e.currentTarget.querySelectorAll<HTMLButtonElement>('[role="tab"]');
+      if (!tabs.length) return;
+
+      const currentIndex = Array.from(tabs).findIndex(
+        (t) => t === document.activeElement,
+      );
+      if (currentIndex === -1) return;
+
+      let nextIndex: number | null = null;
+      if (e.key === "ArrowRight") {
+        nextIndex = (currentIndex + 1) % tabs.length;
+      } else if (e.key === "ArrowLeft") {
+        nextIndex = (currentIndex - 1 + tabs.length) % tabs.length;
+      } else if (e.key === "Home") {
+        nextIndex = 0;
+      } else if (e.key === "End") {
+        nextIndex = tabs.length - 1;
+      }
+
+      if (nextIndex !== null) {
+        e.preventDefault();
+        tabs[nextIndex]!.focus();
+        tabs[nextIndex]!.click();
+      }
+    },
+    [],
+  );
+
+  return (
+    <div className={cn("flex flex-col gap-4", className)}>
+      {/* Search input */}
+      <div className="relative">
+        <SearchIcon />
+        <input
+          type="search"
+          value={query}
+          onChange={(e) => setQuery(e.target.value)}
+          placeholder="Search templates…"
+          aria-label="Search workflow templates"
+          className={cn(
+            "w-full rounded-md border border-input bg-input-bg py-2 pl-9 pr-3 text-sm text-foreground",
+            "placeholder:text-muted-foreground",
+            "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+          )}
+        />
+      </div>
+
+      {/* Category tabs */}
+      {availableCategories.length > 1 && (
+        <div
+          role="tablist"
+          aria-label="Template categories"
+          onKeyDown={handleTabKeyDown}
+          className="flex flex-wrap gap-1"
+        >
+          <CategoryTab
+            label="All"
+            isActive={activeCategory === null}
+            onClick={() => setActiveCategory(null)}
+          />
+          {availableCategories.map((cat) => (
+            <CategoryTab
+              key={cat}
+              label={WORKFLOW_CATEGORY_LABELS[cat] ?? cat}
+              isActive={activeCategory === cat}
+              onClick={() => setActiveCategory(cat)}
+            />
+          ))}
+        </div>
+      )}
+
+      {/* Card grid */}
+      {filtered.length > 0 ? (
+        <div
+          role="list"
+          aria-label="Workflow templates"
+          className="grid grid-cols-1 gap-3 sm:grid-cols-2 lg:grid-cols-3"
+        >
+          {filtered.map((template) => (
+            <div key={template.id} role="listitem">
+              <WorkflowTemplateCard
+                template={template}
+                onSelect={onSelect}
+                onPreview={handlePreview}
+              />
+            </div>
+          ))}
+        </div>
+      ) : (
+        (emptyContent ?? (
+          <div className="py-8 text-center text-sm text-muted-foreground">
+            No templates match your search.
+          </div>
+        ))
+      )}
+
+      {/* Preview dialog */}
+      <WorkflowTemplatePreview
+        template={previewTemplate}
+        open={previewTemplate !== null}
+        onClose={handlePreviewClose}
+        onSelect={handlePreviewSelect}
+      />
+    </div>
+  );
+}
+
+function CategoryTab({
+  label,
+  isActive,
+  onClick,
+}: {
+  readonly label: string;
+  readonly isActive: boolean;
+  readonly onClick: () => void;
+}) {
+  return (
+    <button
+      type="button"
+      role="tab"
+      aria-selected={isActive}
+      tabIndex={isActive ? 0 : -1}
+      onClick={onClick}
+      className={cn(
+        "rounded-md px-2.5 py-1 text-xs font-medium transition-colors",
+        "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+        isActive
+          ? "bg-primary text-primary-foreground"
+          : "bg-muted text-muted-foreground hover:bg-accent hover:text-accent-foreground",
+      )}
+    >
+      {label}
+    </button>
+  );
+}
+
+function SearchIcon() {
+  return (
+    <svg
+      className="pointer-events-none absolute left-3 top-1/2 size-4 -translate-y-1/2 text-muted-foreground"
+      xmlns="http://www.w3.org/2000/svg"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={2}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <circle cx={11} cy={11} r={8} />
+      <path d="m21 21-4.3-4.3" />
+    </svg>
+  );
+}