@invect/ui 0.0.1

package/src/demo/FlowViewer.tsx

@@ -0,0 +1,294 @@
+/**
+ * FlowViewer — Stripped-down, read-only React Flow canvas for embedding in docs.
+ *
+ * Renders a flow from static data with:
+ * - Nodes and edges on a React Flow canvas
+ * - Double-click a node to open its config panel (read-only)
+ * - Agent node tool display
+ * - No sidebar, toolbar, run controls, chat, or mutations
+ *
+ * @example
+ * ```tsx
+ * import { FlowViewer } from '@invect/ui/demo';
+ * import '@invect/ui/styles';
+ *
+ * <FlowViewer
+ *   nodes={[
+ *     { id: '1', type: 'core.input', position: { x: 0, y: 0 },
+ *       data: { id: '1', type: 'core.input', display_name: 'Input', reference_id: 'input', status: 'default', params: {} } },
+ *     { id: '2', type: 'core.model', position: { x: 300, y: 0 },
+ *       data: { id: '2', type: 'core.model', display_name: 'GPT-4', reference_id: 'gpt4', status: 'default', params: {} } },
+ *   ]}
+ *   edges={[{ id: 'e1-2', source: '1', target: '2' }]}
+ *   nodeDefinitions={[...]}
+ *   theme="dark"
+ *   style={{ height: 500 }}
+ * />
+ * ```
+ */
+
+import React, { useMemo, useCallback, useRef, useState, useEffect } from 'react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import {
+  ReactFlow,
+  ReactFlowProvider,
+  Controls,
+  Background,
+  BackgroundVariant,
+  type Node,
+  type Edge,
+  type NodeTypes,
+  type EdgeTypes,
+} from '@xyflow/react';
+import { GraphNodeType } from '@invect/core/types';
+import { ThemeProvider, useTheme } from '../contexts/ThemeProvider';
+import { ApiProvider } from '../contexts/ApiContext';
+import { NodeRegistryProvider } from '../contexts/NodeRegistryContext';
+import { PluginRegistryProvider } from '../contexts/PluginRegistryContext';
+import { ValidationProvider } from '../contexts/ValidationContext';
+import { UniversalNode, AgentNode, type ToolDefinition } from '../components/nodes';
+import { BatchFlowEdge, defaultEdgeOptions } from '../components/graph';
+import {
+  AgentToolCallbacksProvider,
+  type AgentToolCallbacks,
+} from '../contexts/AgentToolCallbacksContext';
+import { NodeConfigPanel } from '../components/flow-editor/node-config-panel/NodeConfigPanel';
+import { useFlowEditorStore } from '../components/flow-editor/flow-editor.store';
+import type { NodeDefinition } from '../types/node-definition.types';
+import type { ReactFlowNodeData, AgentToolDefinition } from '@invect/core/types';
+import { createDemoApiClient } from './demo-api-client';
+import type { ApiClient } from '../api/client';
+import '../app.css';
+
+const EDGE_TYPES: EdgeTypes = {
+  default: BatchFlowEdge,
+};
+
+const FIT_VIEW_OPTIONS = {
+  duration: 0,
+  padding: 0.2,
+} as const;
+
+export interface FlowViewerProps {
+  /** React Flow nodes to render */
+  nodes: Node<ReactFlowNodeData>[];
+  /** React Flow edges to render */
+  edges: Edge[];
+  /** Node definitions for rendering and config panel */
+  nodeDefinitions?: NodeDefinition[];
+  /** Agent tool definitions (shown on agent nodes) */
+  agentTools?: AgentToolDefinition[];
+  /** Theme mode */
+  theme?: 'light' | 'dark' | 'system';
+  /** Allow double-click to open the node config panel */
+  interactive?: boolean;
+  /** Show React Flow controls (zoom, fit) */
+  showControls?: boolean;
+  /** CSS class name for the outer container */
+  className?: string;
+  /** Inline styles for the outer container */
+  style?: React.CSSProperties;
+  /** Additional class for the outer container */
+  containerClassName?: string;
+}
+
+// No-op for read-only tool callbacks
+const toolNoop = () => {
+  // intentionally empty — viewer is read-only
+};
+
+/** Internal canvas component — must be inside ReactFlowProvider */
+function FlowViewerCanvas({
+  nodes,
+  edges,
+  nodeDefinitions = [],
+  agentTools = [],
+  interactive = true,
+  showControls = true,
+}: Omit<FlowViewerProps, 'theme' | 'className' | 'style' | 'containerClassName'>) {
+  const { resolvedTheme } = useTheme();
+  const dialogContainerRef = useRef<HTMLDivElement | null>(null);
+
+  // Config panel state
+  const [configPanelOpen, setConfigPanelOpen] = useState(false);
+  const [selectedNodeId, setSelectedNodeId] = useState<string | null>(null);
+
+  // Sync nodes into Zustand store so NodeConfigPanel can read them
+  const syncFromServer = useFlowEditorStore((s) => s.syncFromServer);
+  const setFlowId = useFlowEditorStore((s) => s.setFlowId);
+
+  useEffect(() => {
+    setFlowId('demo-flow', undefined);
+    syncFromServer(nodes, edges, 'demo-flow:1', 'Demo Flow');
+  }, [nodes, edges, syncFromServer, setFlowId]);
+
+  // Build nodeTypes mapping from definitions
+  const nodeTypes: NodeTypes = useMemo(() => {
+    // eslint-disable-next-line typescript/no-explicit-any
+    const mapping: Record<string, React.ComponentType<any>> = {
+      [GraphNodeType.AGENT]: AgentNode,
+      default: UniversalNode,
+    };
+    for (const def of nodeDefinitions) {
+      if (!(def.type in mapping)) {
+        mapping[def.type] = UniversalNode;
+      }
+    }
+    return mapping;
+  }, [nodeDefinitions]);
+
+  // Transform agent tools for context
+  const availableTools: ToolDefinition[] = useMemo(
+    () =>
+      agentTools
+        .filter((tool) => tool.provider?.id !== 'triggers' && !tool.id.startsWith('trigger.'))
+        .map((tool) => ({
+          id: tool.id,
+          name: tool.name,
+          description: tool.description,
+          category: tool.category as ToolDefinition['category'],
+          tags: tool.tags,
+          inputSchema: tool.inputSchema,
+          nodeType: tool.nodeType,
+          provider: tool.provider,
+        })),
+    [agentTools],
+  );
+
+  // Agent tool callbacks (read-only — no mutations in viewer mode)
+  const agentToolCallbacks = useMemo<AgentToolCallbacks>(
+    () => ({
+      onOpenToolSelector: toolNoop,
+      onShowMoreTools: toolNoop,
+      onRemoveTool: toolNoop,
+      onToolClick: toolNoop,
+      availableTools,
+      selectedToolNodeId: null,
+      selectedToolInstanceId: null,
+    }),
+    [availableTools],
+  );
+
+  const handleNodeDoubleClick = useCallback(
+    (_event: React.MouseEvent, clickedNode: Node) => {
+      if (!interactive) {
+        return;
+      }
+      setSelectedNodeId(clickedNode.id);
+      setConfigPanelOpen(true);
+    },
+    [interactive],
+  );
+
+  const handlePanelOpenChange = useCallback((open: boolean) => {
+    if (!open) {
+      setConfigPanelOpen(false);
+      setSelectedNodeId(null);
+    }
+  }, []);
+
+  return (
+    <div
+      ref={dialogContainerRef}
+      style={{ width: '100%', height: '100%', background: 'var(--canvas-background)' }}
+    >
+      <AgentToolCallbacksProvider value={agentToolCallbacks}>
+        <ReactFlow
+          nodes={nodes}
+          edges={edges}
+          nodeTypes={nodeTypes}
+          edgeTypes={EDGE_TYPES}
+          defaultEdgeOptions={defaultEdgeOptions}
+          colorMode={resolvedTheme}
+          fitView
+          fitViewOptions={FIT_VIEW_OPTIONS}
+          onNodeDoubleClick={interactive ? handleNodeDoubleClick : undefined}
+          nodesDraggable={false}
+          nodesConnectable={false}
+          elementsSelectable={interactive}
+          panOnScroll
+          panOnDrag
+          zoomOnScroll
+          zoomOnPinch
+          zoomOnDoubleClick={false}
+        >
+          {showControls && <Controls />}
+          <Background variant={BackgroundVariant.Dots} gap={20} size={1.2} />
+        </ReactFlow>
+      </AgentToolCallbacksProvider>
+
+      {interactive && (
+        <NodeConfigPanel
+          open={configPanelOpen}
+          nodeId={selectedNodeId}
+          flowId="demo-flow"
+          onOpenChange={handlePanelOpenChange}
+          portalContainer={dialogContainerRef.current}
+          availableTools={availableTools}
+        />
+      )}
+    </div>
+  );
+}
+
+/**
+ * Self-contained flow viewer with all necessary providers.
+ * Renders React Flow canvas with Invect node styling.
+ */
+export function FlowViewer({
+  theme = 'dark',
+  className,
+  style,
+  containerClassName,
+  nodeDefinitions = [],
+  agentTools = [],
+  ...canvasProps
+}: FlowViewerProps) {
+  // Create a stable QueryClient for the viewer
+  const queryClient = useMemo(
+    () =>
+      new QueryClient({
+        defaultOptions: {
+          queries: { staleTime: Infinity, retry: false },
+        },
+      }),
+    [],
+  );
+
+  // Create mock API client with the node definitions and agent tools
+  const mockClient = useMemo(
+    () =>
+      createDemoApiClient({
+        nodeDefinitions,
+        agentTools,
+      }) as unknown as ApiClient,
+    [nodeDefinitions, agentTools],
+  );
+
+  return (
+    <div
+      className={containerClassName}
+      style={{ position: 'relative', overflow: 'hidden', ...style }}
+    >
+      <ThemeProvider defaultTheme={theme} storageKey="invect-viewer-theme" className={className}>
+        <QueryClientProvider client={queryClient}>
+          <ApiProvider apiClient={mockClient}>
+            <PluginRegistryProvider plugins={[]}>
+              <ValidationProvider>
+                <NodeRegistryProvider>
+                  <ReactFlowProvider>
+                    <FlowViewerCanvas
+                      nodeDefinitions={nodeDefinitions}
+                      agentTools={agentTools}
+                      {...canvasProps}
+                    />
+                  </ReactFlowProvider>
+                </NodeRegistryProvider>
+              </ValidationProvider>
+            </PluginRegistryProvider>
+          </ApiProvider>
+        </QueryClientProvider>
+      </ThemeProvider>
+    </div>
+  );
+}

package/src/demo/demo-api-client.ts

@@ -0,0 +1,246 @@
+/**
+ * DemoApiClient — A mock ApiClient that returns static data for frontend-only demos.
+ *
+ * Uses a Proxy to intercept all method calls. Methods that have registered mock
+ * data return it; all others return safe empty defaults (empty arrays, empty objects).
+ * Write operations (create, update, delete, execute) are silently no-ops.
+ */
+
+import type {
+  Flow,
+  FlowRun,
+  NodeExecution,
+  Credential,
+  ReactFlowData,
+  PaginatedResponse,
+  DashboardStats,
+  AgentToolDefinition,
+  NodeDefinition,
+} from '../api/types';
+
+export interface DemoData {
+  /** Flows to show on the dashboard */
+  flows?: Flow[];
+  /** Map of flowId → ReactFlowData for the flow editor canvas */
+  flowReactFlowData?: Record<string, ReactFlowData>;
+  /** Node definitions for the palette and registry */
+  nodeDefinitions?: NodeDefinition[];
+  /** Agent tool definitions */
+  agentTools?: AgentToolDefinition[];
+  /** Dashboard stats override */
+  dashboardStats?: Partial<DashboardStats>;
+  /** Flow runs (execution history) */
+  flowRuns?: FlowRun[];
+  /** Node executions keyed by flowRunId */
+  nodeExecutions?: Record<string, NodeExecution[]>;
+  /** Credentials */
+  credentials?: Credential[];
+  /** Chat messages keyed by flowId */
+  chatMessages?: Record<
+    string,
+    Array<{
+      id: string;
+      flowId: string;
+      role: 'user' | 'assistant' | 'system' | 'tool';
+      content: string;
+      toolMeta?: Record<string, unknown> | null;
+      createdAt: string;
+    }>
+  >;
+}
+
+const EMPTY_PAGINATED = <T>(items: T[] = []): PaginatedResponse<T> => ({
+  data: items,
+  pagination: {
+    page: 1,
+    limit: items.length || 20,
+    totalPages: 1,
+  },
+});
+
+const DEFAULT_STATS: DashboardStats = {
+  totalFlows: 0,
+  totalRuns: 0,
+  runsLast24h: 0,
+  activeRuns: 0,
+  successRate: 100,
+  failedRunsLast24h: 0,
+  runsByStatus: {},
+  recentRuns: [],
+};
+
+// No-op function to satisfy lint rules about empty functions
+const noop = () => {
+  // intentionally empty — demo mock
+};
+
+/**
+ * Creates a mock API client backed entirely by static data.
+ * No HTTP requests are ever made.
+ */
+export function createDemoApiClient(data: DemoData = {}): Record<string, unknown> {
+  const {
+    flows = [],
+    flowReactFlowData = {},
+    nodeDefinitions = [],
+    agentTools = [],
+    dashboardStats = {},
+    flowRuns = [],
+    nodeExecutions = {},
+    credentials = [],
+    chatMessages = {},
+  } = data;
+
+  const stats: DashboardStats = {
+    ...DEFAULT_STATS,
+    totalFlows: flows.length,
+    totalRuns: flowRuns.length,
+    runsLast24h: flowRuns.length,
+    successRate:
+      flowRuns.length > 0
+        ? Math.round(
+            (flowRuns.filter((r) => r.status === 'SUCCESS').length / flowRuns.length) * 100,
+          )
+        : 100,
+    runsByStatus: flowRuns.reduce(
+      (acc, r) => {
+        acc[r.status] = (acc[r.status] || 0) + 1;
+        return acc;
+      },
+      {} as Record<string, number>,
+    ),
+    recentRuns: flowRuns.slice(0, 10),
+    ...dashboardStats,
+  } as DashboardStats;
+
+  // Method implementations for read operations
+  const methods: Record<string, (...args: unknown[]) => unknown> = {
+    // Identity
+    getBaseURL: () => 'demo://mock',
+    setBaseURL: noop,
+    setUserId: noop,
+
+    // Dashboard
+    getDashboardStats: async () => stats,
+
+    // Flows
+    getFlows: async () => EMPTY_PAGINATED(flows),
+    getFlow: async (...args: unknown[]) => {
+      const id = args[0] as string;
+      return flows.find((f) => f.id === id) ?? flows[0] ?? null;
+    },
+    getFlowReactFlowData: async (...args: unknown[]) => {
+      const flowId = args[0] as string;
+      return flowReactFlowData[flowId] ?? null;
+    },
+    getFlowVersions: async () => EMPTY_PAGINATED([]),
+
+    // Nodes
+    getAvailableNodes: async () => nodeDefinitions,
+    resolveNodeDefinition: async () => null,
+    loadFieldOptions: async () => [],
+
+    // Agent tools
+    getAgentTools: async () => agentTools,
+
+    // Credentials
+    listCredentials: async () => credentials,
+    getCredential: async (...args: unknown[]) => {
+      const id = args[0] as string;
+      return credentials.find((c) => c.id === id) ?? null;
+    },
+    getCredentialUsage: async () => ({ flowsCount: 0, nodesCount: 0, lastUsedAt: null }),
+
+    // OAuth2 (empty)
+    getOAuth2Providers: async () => [],
+    getOAuth2Provider: async () => null,
+
+    // Flow runs
+    getFlowRun: async (...args: unknown[]) => {
+      const id = args[0] as string;
+      return flowRuns.find((r) => r.id === id) ?? null;
+    },
+    getFlowRunsByFlowId: async (...args: unknown[]) => {
+      const flowId = args[0] as string;
+      const matching = flowRuns.filter((r) => r.flowId === flowId);
+      return EMPTY_PAGINATED(matching);
+    },
+    getAllFlowRuns: async () => EMPTY_PAGINATED(flowRuns),
+
+    // Node executions
+    getNodeExecutionsByFlowRun: async (...args: unknown[]) => {
+      const flowRunId = args[0] as string;
+      return nodeExecutions[flowRunId] ?? [];
+    },
+    getAllNodeExecutions: async () => {
+      const all = Object.values(nodeExecutions).flat();
+      return EMPTY_PAGINATED(all);
+    },
+
+    // Models (empty)
+    getModels: async () => [],
+    getModelsForCredential: async () => [],
+
+    // Databases
+    getAvailableDatabases: async () => [],
+
+    // Triggers (empty)
+    listTriggersForFlow: async () => [],
+    getTrigger: async () => null,
+
+    // Chat
+    getChatStatus: async () => ({ enabled: true }),
+    getChatModels: async () => [
+      { id: 'claude-sonnet-4-20250514', name: 'Claude Sonnet 4', provider: 'anthropic' },
+      { id: 'gpt-4o', name: 'GPT-4o', provider: 'openai' },
+    ],
+    getChatMessages: async (...args: unknown[]) => {
+      const flowId = args[0] as string;
+      return chatMessages[flowId] ?? [];
+    },
+
+    // === Write operations (all no-ops for demo) ===
+    createFlow: async () => flows[0] ?? {},
+    createFlowWithVersion: async () => flows[0] ?? {},
+    updateFlow: async () => flows[0] ?? {},
+    deleteFlow: async () => undefined,
+    createFlowVersion: async () => ({}),
+    validateFlow: async () => ({ isValid: true, errors: [], warnings: [] }),
+    executeFlow: async () => ({}),
+    executeFlowToNode: async () => ({}),
+    testNode: async () => ({}),
+    testModelPrompt: async () => ({}),
+    testJsExpression: async () => ({}),
+    testMapper: async () => ({}),
+    executeSqlQuery: async () => ({}),
+    createCredential: async () => ({}),
+    updateCredential: async () => ({}),
+    deleteCredential: async () => undefined,
+    testCredential: async () => ({ success: true }),
+    testCredentialRequest: async () => ({}),
+    startOAuth2Flow: async () => ({}),
+    handleOAuth2Callback: async () => ({}),
+    refreshOAuth2Credential: async () => ({}),
+    pauseFlowRun: async () => ({}),
+    resumeFlowRun: async () => ({}),
+    cancelFlowRun: async () => ({}),
+    createTrigger: async () => ({}),
+    updateTrigger: async () => ({}),
+    deleteTrigger: async () => undefined,
+    syncTriggersForFlow: async () => ({}),
+    sendChatMessage: async () => ({}),
+    saveChatMessages: async () => ({}),
+    deleteChatMessages: async () => ({}),
+  };
+
+  // Proxy catches any method not explicitly listed above and returns a safe fallback
+  return new Proxy(methods, {
+    get(target, prop: string) {
+      if (prop in target) {
+        return target[prop];
+      }
+      // Unknown method — return async no-op
+      return async () => null;
+    },
+  });
+}

package/src/demo/index.ts

@@ -0,0 +1,28 @@
+// Demo / preview components for embedding Invect UI without a backend.
+//
+// These components are designed for documentation, marketing pages,
+// and interactive previews where no Invect server is available.
+
+export { DemoInvect, type DemoInvectProps } from './DemoInvect';
+export { FlowViewer, type FlowViewerProps } from './FlowViewer';
+export { createDemoApiClient, type DemoData } from './demo-api-client';
+export {
+  sampleNodeDefinitions,
+  simpleFlowNodes,
+  simpleFlowEdges,
+  branchingFlowNodes,
+  branchingFlowEdges,
+  showcaseFlowNodes,
+  showcaseFlowEdges,
+  showcaseAgentTools,
+  sampleDemoData,
+} from './sample-data';
+
+// Re-export types commonly needed when constructing demo data
+export type { NodeDefinition } from '../types/node-definition.types';
+export type {
+  ReactFlowNodeData,
+  ReactFlowNode,
+  ReactFlowEdge,
+  AgentToolDefinition,
+} from '@invect/core/types';