@stigmer/react 1.0.4 → 2.0.0

package/src/workflow/picker/recents.ts

@@ -0,0 +1,89 @@
+/**
+ * Manages a per-user list of recently used task kinds.
+ *
+ * Persisted to localStorage so recents survive page reloads and
+ * sessions. Scoped by a storage key prefix to allow per-workflow
+ * or per-project isolation if needed in the future.
+ *
+ * The store is intentionally simple and synchronous — localStorage
+ * access is fast enough for the 5-item list we maintain.
+ */
+
+const DEFAULT_STORAGE_KEY = "stigmer:picker:recent-kinds";
+const MAX_RECENTS = 5;
+
+/**
+ * A single recently-used task kind entry with a usage timestamp.
+ */
+export interface RecentKindEntry {
+  readonly kind: string;
+  readonly timestamp: number;
+}
+
+/**
+ * Retrieves the list of recently used task kinds, ordered by most recent first.
+ *
+ * Returns an empty array if localStorage is unavailable or contains
+ * invalid data.
+ */
+export function getRecentKinds(storageKey = DEFAULT_STORAGE_KEY): readonly RecentKindEntry[] {
+  try {
+    const raw = globalThis.localStorage?.getItem(storageKey);
+    if (!raw) return [];
+
+    const parsed: unknown = JSON.parse(raw);
+    if (!Array.isArray(parsed)) return [];
+
+    return parsed
+      .filter(isValidEntry)
+      .sort((a, b) => b.timestamp - a.timestamp)
+      .slice(0, MAX_RECENTS);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Records a task kind as recently used.
+ *
+ * If the kind already exists in the list, it is moved to the front
+ * (most recent). The list is capped at {@link MAX_RECENTS} entries.
+ */
+export function recordRecentKind(
+  kind: string,
+  storageKey = DEFAULT_STORAGE_KEY,
+): void {
+  try {
+    const existing = getRecentKinds(storageKey).filter((e) => e.kind !== kind);
+    const updated: RecentKindEntry[] = [
+      { kind, timestamp: Date.now() },
+      ...existing,
+    ].slice(0, MAX_RECENTS);
+
+    globalThis.localStorage?.setItem(storageKey, JSON.stringify(updated));
+  } catch {
+    // localStorage unavailable (SSR, private browsing quota exceeded)
+  }
+}
+
+/**
+ * Clears all recent kind entries. Useful for testing or user preference reset.
+ */
+export function clearRecentKinds(storageKey = DEFAULT_STORAGE_KEY): void {
+  try {
+    globalThis.localStorage?.removeItem(storageKey);
+  } catch {
+    // Silently ignore storage errors
+  }
+}
+
+function isValidEntry(value: unknown): value is RecentKindEntry {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "kind" in value &&
+    "timestamp" in value &&
+    typeof (value as RecentKindEntry).kind === "string" &&
+    typeof (value as RecentKindEntry).timestamp === "number"
+  );
+}

package/src/workflow/picker/suggestions.ts

@@ -0,0 +1,217 @@
+import type { InsertionContext } from "./insertion-context";
+
+/**
+ * A suggested task kind with a human-readable reason.
+ *
+ * Rendered in the "Suggested" section of the picker, above Recent and
+ * All Categories. Suggestions are derived from static domain knowledge
+ * about common workflow patterns.
+ */
+export interface TaskKindSuggestion {
+  readonly kind: string;
+  readonly reason: string;
+}
+
+/**
+ * Static compatibility map: source task kind -> suggested next kinds.
+ *
+ * Derived from the research report (Section 4.2) and common workflow
+ * authoring patterns observed across n8n, Retool, and Step Functions.
+ *
+ * The map encodes domain knowledge: "after an HTTP call, users commonly
+ * validate the response, transform the data, or branch on status."
+ */
+const SUGGESTIONS_AFTER_KIND: ReadonlyMap<string, readonly TaskKindSuggestion[]> = new Map([
+  [
+    "http_call",
+    [
+      { kind: "validate", reason: "Validate HTTP response" },
+      { kind: "transform", reason: "Transform response data" },
+      { kind: "switch_case", reason: "Branch on status/content" },
+    ],
+  ],
+  [
+    "grpc_call",
+    [
+      { kind: "validate", reason: "Validate gRPC response" },
+      { kind: "transform", reason: "Transform response data" },
+      { kind: "switch_case", reason: "Branch on result" },
+    ],
+  ],
+  [
+    "llm_call",
+    [
+      { kind: "eval", reason: "Evaluate LLM output quality" },
+      { kind: "switch_case", reason: "Branch on structured output" },
+      { kind: "set_vars", reason: "Store output in variables" },
+      { kind: "transform", reason: "Extract from response" },
+    ],
+  ],
+  [
+    "agent_call",
+    [
+      { kind: "switch_case", reason: "Branch on agent result" },
+      { kind: "human_input", reason: "Review agent output" },
+      { kind: "transform", reason: "Extract structured data" },
+      { kind: "eval", reason: "Evaluate agent quality" },
+    ],
+  ],
+  [
+    "transform",
+    [
+      { kind: "switch_case", reason: "Branch on transformed value" },
+      { kind: "http_call", reason: "Send transformed data" },
+      { kind: "agent_call", reason: "Process with agent" },
+      { kind: "validate", reason: "Validate transformation" },
+    ],
+  ],
+  [
+    "set_vars",
+    [
+      { kind: "switch_case", reason: "Branch on variable value" },
+      { kind: "http_call", reason: "Use variables in request" },
+      { kind: "agent_call", reason: "Pass variables to agent" },
+    ],
+  ],
+  [
+    "validate",
+    [
+      { kind: "switch_case", reason: "Branch on validation result" },
+      { kind: "transform", reason: "Fix validation issues" },
+      { kind: "raise_error", reason: "Fail on invalid data" },
+    ],
+  ],
+  [
+    "human_input",
+    [
+      { kind: "switch_case", reason: "Branch on approval decision" },
+      { kind: "agent_call", reason: "Continue with agent" },
+      { kind: "http_call", reason: "Proceed with API call" },
+      { kind: "notification", reason: "Notify about decision" },
+    ],
+  ],
+  [
+    "eval",
+    [
+      { kind: "switch_case", reason: "Branch on evaluation score" },
+      { kind: "human_input", reason: "Review if score is low" },
+      { kind: "notification", reason: "Alert on quality issue" },
+    ],
+  ],
+  [
+    "switch_case",
+    [
+      { kind: "agent_call", reason: "Process in branch" },
+      { kind: "http_call", reason: "Call API in branch" },
+      { kind: "llm_call", reason: "Generate in branch" },
+    ],
+  ],
+  [
+    "fork",
+    [
+      { kind: "transform", reason: "Merge parallel results" },
+      { kind: "switch_case", reason: "Branch on merged result" },
+      { kind: "agent_call", reason: "Process merged output" },
+    ],
+  ],
+  [
+    "for_each",
+    [
+      { kind: "transform", reason: "Aggregate iteration results" },
+      { kind: "switch_case", reason: "Branch on aggregated result" },
+    ],
+  ],
+  [
+    "listen",
+    [
+      { kind: "switch_case", reason: "Branch on event type" },
+      { kind: "agent_call", reason: "Process received event" },
+      { kind: "transform", reason: "Extract event data" },
+    ],
+  ],
+  [
+    "wait",
+    [
+      { kind: "http_call", reason: "Poll after delay" },
+      { kind: "agent_call", reason: "Resume processing" },
+      { kind: "notification", reason: "Notify after wait" },
+    ],
+  ],
+  [
+    "notification",
+    [
+      { kind: "wait", reason: "Wait for response" },
+      { kind: "listen", reason: "Wait for event" },
+      { kind: "human_input", reason: "Await acknowledgment" },
+    ],
+  ],
+]);
+
+/**
+ * Context-specific suggestions for branch addition modes.
+ */
+const SUGGESTIONS_FOR_BRANCH: ReadonlyMap<string, readonly TaskKindSuggestion[]> = new Map([
+  [
+    "add-switch-case",
+    [
+      { kind: "agent_call", reason: "Process this case with agent" },
+      { kind: "http_call", reason: "Call API for this case" },
+      { kind: "human_input", reason: "Require approval for this case" },
+      { kind: "llm_call", reason: "Generate for this case" },
+    ],
+  ],
+  [
+    "add-fork-branch",
+    [
+      { kind: "agent_call", reason: "Run agent in parallel" },
+      { kind: "http_call", reason: "Call API in parallel" },
+      { kind: "llm_call", reason: "Generate in parallel" },
+      { kind: "transform", reason: "Transform in parallel" },
+    ],
+  ],
+  [
+    "add-catch-handler",
+    [
+      { kind: "notification", reason: "Notify on error" },
+      { kind: "agent_call", reason: "Attempt recovery with agent" },
+      { kind: "raise_error", reason: "Re-raise with context" },
+      { kind: "http_call", reason: "Report error to service" },
+    ],
+  ],
+]);
+
+/** Default suggestions when no specific context is available. */
+const DEFAULT_SUGGESTIONS: readonly TaskKindSuggestion[] = [
+  { kind: "agent_call", reason: "Most common task type" },
+  { kind: "llm_call", reason: "Direct LLM invocation" },
+  { kind: "http_call", reason: "External API call" },
+  { kind: "switch_case", reason: "Conditional branching" },
+];
+
+/**
+ * Returns suggested task kinds for the given insertion context.
+ *
+ * The suggestions are based on a static compatibility map that encodes
+ * common workflow authoring patterns. Results are ordered by relevance
+ * (most common pairing first) and capped at `maxResults`.
+ */
+export function getSuggestedKinds(
+  context: InsertionContext,
+  maxResults = 5,
+): readonly TaskKindSuggestion[] {
+  // Branch-specific modes have their own suggestion sets
+  const branchSuggestions = SUGGESTIONS_FOR_BRANCH.get(context.mode);
+  if (branchSuggestions) {
+    return branchSuggestions.slice(0, maxResults);
+  }
+
+  // For edge-splice and append-after, look up by source kind
+  if (context.sourceKind) {
+    const kindSuggestions = SUGGESTIONS_AFTER_KIND.get(context.sourceKind);
+    if (kindSuggestions && kindSuggestions.length > 0) {
+      return kindSuggestions.slice(0, maxResults);
+    }
+  }
+
+  return DEFAULT_SUGGESTIONS.slice(0, maxResults);
+}

package/src/workflow/picker/usePickerData.ts

@@ -0,0 +1,171 @@
+"use client";
+
+import { useMemo } from "react";
+import type { TaskKindDescriptor, TaskKindCategory } from "../types";
+import type { WorkflowGraphModel } from "../workflow-graph-model";
+import { CATEGORY_ORDER } from "../canvas-constants";
+import type { InsertionContext } from "./insertion-context";
+import { buildInsertionHeader } from "./insertion-context";
+import { getSuggestedKinds, type TaskKindSuggestion } from "./suggestions";
+import { getDisabledKinds, getHiddenKinds, type DisabledKindEntry } from "./compatibility";
+import { getRecentKinds } from "./recents";
+
+/**
+ * A picker item enriched with context-awareness metadata.
+ */
+export interface PickerItem {
+  readonly descriptor: TaskKindDescriptor;
+  readonly disabled: boolean;
+  readonly disabledReason?: string;
+}
+
+/**
+ * A named section in the picker (Suggested, Recent, or a category group).
+ */
+export interface PickerSection {
+  readonly id: string;
+  readonly label: string;
+  readonly items: readonly PickerItem[];
+  /** If true, this section is a special (Suggested/Recent) section, not a category. */
+  readonly isSpecial?: boolean;
+}
+
+/**
+ * The complete picker data model returned by {@link usePickerData}.
+ */
+export interface PickerData {
+  /** Contextual header text (e.g., "Insert between A and B"). */
+  readonly header: string;
+  /** Ordered sections to render in the picker. */
+  readonly sections: readonly PickerSection[];
+  /** Flat list of all selectable (non-disabled) items for keyboard navigation. */
+  readonly selectableItems: readonly PickerItem[];
+  /** Whether the registry is still loading. */
+  readonly isLoading: boolean;
+}
+
+/**
+ * Computes the full picker data model from insertion context, task registry,
+ * and graph model.
+ *
+ * This hook is the bridge between the pure intelligence layer (suggestions,
+ * compatibility, recents) and the picker UI component. It produces a stable,
+ * memoized data structure that drives rendering.
+ *
+ * @param context - The insertion context describing where and how the user is inserting.
+ * @param categories - Category-grouped task descriptors from `useTaskKindRegistry()`.
+ * @param graph - The current workflow graph model (for constraint evaluation).
+ * @param isLoading - Whether the task kind registry is still loading.
+ * @param searchQuery - Current search query for filtering.
+ */
+export function usePickerData(
+  context: InsertionContext | null,
+  categories: ReadonlyMap<TaskKindCategory, readonly TaskKindDescriptor[]>,
+  graph: WorkflowGraphModel | null,
+  isLoading: boolean,
+  searchQuery: string,
+): PickerData {
+  return useMemo(() => {
+    const effectiveContext: InsertionContext = context ?? { mode: "add-at-position" };
+
+    if (isLoading) {
+      return {
+        header: buildInsertionHeader(effectiveContext),
+        sections: [],
+        selectableItems: [],
+        isLoading,
+      };
+    }
+
+    const header = buildInsertionHeader(effectiveContext);
+    const hiddenKinds = getHiddenKinds();
+    const disabledEntries = graph ? getDisabledKinds(effectiveContext, graph) : [];
+    const disabledMap = new Map(disabledEntries.map((d) => [d.kind, d.reason]));
+
+    // Build a flat lookup of all descriptors by kind
+    const allDescriptors = new Map<string, TaskKindDescriptor>();
+    for (const descriptors of categories.values()) {
+      for (const d of descriptors) {
+        if (!hiddenKinds.has(d.kind)) {
+          allDescriptors.set(d.kind, d);
+        }
+      }
+    }
+
+    const query = searchQuery.toLowerCase().trim();
+    const matchesSearch = (d: TaskKindDescriptor) =>
+      !query ||
+      d.displayName.toLowerCase().includes(query) ||
+      d.description.toLowerCase().includes(query) ||
+      d.kind.toLowerCase().includes(query);
+
+    const toPickerItem = (d: TaskKindDescriptor): PickerItem => ({
+      descriptor: d,
+      disabled: disabledMap.has(d.kind),
+      disabledReason: disabledMap.get(d.kind),
+    });
+
+    const sections: PickerSection[] = [];
+
+    // --- Suggested section ---
+    if (!query) {
+      const suggestions = getSuggestedKinds(effectiveContext);
+      const suggestedItems = suggestions
+        .map((s) => allDescriptors.get(s.kind))
+        .filter((d): d is TaskKindDescriptor => d !== undefined)
+        .map(toPickerItem);
+
+      if (suggestedItems.length > 0) {
+        sections.push({
+          id: "__suggested",
+          label: "Suggested",
+          items: suggestedItems,
+          isSpecial: true,
+        });
+      }
+    }
+
+    // --- Recent section ---
+    if (!query) {
+      const recents = getRecentKinds();
+      const recentItems = recents
+        .map((r) => allDescriptors.get(r.kind))
+        .filter((d): d is TaskKindDescriptor => d !== undefined)
+        .map(toPickerItem);
+
+      if (recentItems.length > 0) {
+        sections.push({
+          id: "__recent",
+          label: "Recent",
+          items: recentItems,
+          isSpecial: true,
+        });
+      }
+    }
+
+    // --- Category sections ---
+    for (const cat of CATEGORY_ORDER) {
+      const descriptors = categories.get(cat);
+      if (!descriptors || descriptors.length === 0) continue;
+
+      const filtered = descriptors
+        .filter((d) => !hiddenKinds.has(d.kind) && matchesSearch(d))
+        .map(toPickerItem);
+
+      if (filtered.length > 0) {
+        sections.push({
+          id: cat,
+          label: cat, // Display name is resolved by the UI component
+          items: filtered,
+        });
+      }
+    }
+
+    // Build flat selectable list (excludes disabled items)
+    const selectableItems = sections
+      .flatMap((s) => s.items)
+      .filter((item) => !item.disabled);
+
+    return { header, sections, selectableItems, isLoading };
+  }, [context, categories, graph, isLoading, searchQuery]);
+}

package/src/workflow/shortcut-registry.ts

@@ -0,0 +1,140 @@
+/**
+ * Canonical shortcut definitions for the workflow canvas editor.
+ *
+ * Single source of truth for all keyboard shortcuts — consumed by
+ * {@link useCanvasKeyboardShortcuts} (matching), {@link CanvasContextMenu}
+ * (hint labels), {@link NodeActions} (toolbar tooltips), and any future
+ * help dialog or documentation generator.
+ *
+ * Pure TypeScript — no React dependency. Safe to import from any layer.
+ *
+ * @since T11 (Context Menus and Keyboard Shortcuts)
+ */
+
+// ---------------------------------------------------------------------------
+// Platform detection
+// ---------------------------------------------------------------------------
+
+const IS_MAC: boolean =
+  typeof navigator !== "undefined" && /Mac|iPhone|iPad|iPod/.test(navigator.platform);
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * Where a shortcut is applicable.
+ *
+ * - `node` — single node selected
+ * - `edge` — single edge selected
+ * - `selection` — one or more nodes selected (multi-select)
+ * - `canvas` — no selection required, fires on the canvas
+ */
+export type ShortcutScope = "node" | "edge" | "selection" | "canvas";
+
+/** A single keyboard shortcut definition. */
+export interface ShortcutDefinition {
+  /** Stable identifier (e.g. `"duplicate"`, `"copy"`). */
+  readonly id: string;
+  /** Human-readable action label for menus and tooltips. */
+  readonly label: string;
+  /**
+   * Key chord in platform-agnostic notation.
+   *
+   * `Mod` resolves to `Cmd` on macOS, `Ctrl` elsewhere.
+   * Bare keys use their literal name (e.g. `"N"`, `"Escape"`).
+   */
+  readonly keys: string;
+  /** Platform-specific display string (e.g. `"⌘D"` or `"Ctrl+D"`). */
+  readonly hint: string;
+  /** Where this shortcut is active. */
+  readonly scope: ShortcutScope;
+  /** Whether the shortcut is restricted to design mode. */
+  readonly requiresDesignMode: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Hint formatting
+// ---------------------------------------------------------------------------
+
+function formatHint(keys: string): string {
+  if (IS_MAC) {
+    return keys
+      .replace(/Mod\+/g, "\u2318")
+      .replace(/Shift\+/g, "\u21E7")
+      .replace(/Alt\+/g, "\u2325")
+      .replace(/Backspace/g, "\u232B")
+      .replace(/Delete/g, "\u232B");
+  }
+  return keys
+    .replace(/Mod\+/g, "Ctrl+")
+    .replace(/Backspace/g, "Del")
+    .replace(/Delete/g, "Del");
+}
+
+// ---------------------------------------------------------------------------
+// Shortcut definitions
+// ---------------------------------------------------------------------------
+
+function def(
+  id: string,
+  label: string,
+  keys: string,
+  scope: ShortcutScope,
+  requiresDesignMode: boolean,
+): ShortcutDefinition {
+  return { id, label, keys, hint: formatHint(keys), scope, requiresDesignMode };
+}
+
+const DEFINITIONS: readonly ShortcutDefinition[] = [
+  // Single-node actions
+  def("duplicate",       "Duplicate",         "Mod+D",           "node",      true),
+  def("copy",            "Copy",              "Mod+C",           "selection", true),
+  def("cut",             "Cut",               "Mod+X",           "selection", true),
+  def("paste",           "Paste",             "Mod+V",           "canvas",    true),
+  def("delete",          "Delete",            "Backspace",       "selection", true),
+  def("addTaskAfter",    "Add task after\u2026", "N",            "node",      true),
+
+  // Canvas-wide actions
+  def("selectAll",       "Select all",        "Mod+A",           "canvas",    true),
+  def("undo",            "Undo",              "Mod+Z",           "canvas",    true),
+  def("redo",            "Redo",              "Mod+Shift+Z",     "canvas",    true),
+  def("escape",          "Deselect",          "Escape",          "canvas",    false),
+] as const;
+
+// ---------------------------------------------------------------------------
+// Registry lookup
+// ---------------------------------------------------------------------------
+
+const BY_ID = new Map<string, ShortcutDefinition>(
+  DEFINITIONS.map((d) => [d.id, d]),
+);
+
+/** All registered shortcut definitions. */
+export function getAllShortcuts(): readonly ShortcutDefinition[] {
+  return DEFINITIONS;
+}
+
+/**
+ * Look up a shortcut by its stable identifier.
+ *
+ * Returns `undefined` if the id is not registered — callers should
+ * treat this as a programming error (missing registry entry).
+ */
+export function getShortcut(id: string): ShortcutDefinition | undefined {
+  return BY_ID.get(id);
+}
+
+/**
+ * Get the display hint for a shortcut, or an empty string if not found.
+ *
+ * Convenience wrapper for context menu and toolbar hint labels.
+ */
+export function getShortcutHint(id: string): string {
+  return BY_ID.get(id)?.hint ?? "";
+}
+
+/** Whether the runtime platform is macOS / iOS. */
+export function isMacPlatform(): boolean {
+  return IS_MAC;
+}