@mesantosrai/pipeline-canvas 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 NovoProtein AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,545 @@
+# @novoprotein/pipeline-canvas
+
+A React component library for building visual pipeline/workflow canvases using React Flow.
+
+## Installation from Private GitHub Repo
+
+### Using SSH (Recommended for Private Repos)
+
+```bash
+npm install git+ssh://git@github.com:santosrai/pipeline-canvas.git
+```
+
+### Using HTTPS with Personal Access Token
+
+```bash
+npm install git+https://YOUR_TOKEN@github.com/santosrai/pipeline-canvas.git
+```
+
+### Using Specific Branch or Tag
+
+```bash
+npm install git+ssh://git@github.com:santosrai/pipeline-canvas.git#main
+npm install git+ssh://git@github.com:santosrai/pipeline-canvas.git#v1.0.0
+```
+
+## Setup
+
+1. Install dependencies:
+```bash
+npm install
+```
+
+2. Build the library:
+```bash
+npm run build
+```
+
+## Peer Dependencies
+
+Make sure you have these installed in your consuming project:
+
+```bash
+npm install react react-dom reactflow zustand lucide-react
+```
+
+### shadcn/ui Components (Required)
+
+This library uses shadcn/ui components. You need to install the required Radix UI packages and utilities:
+
+```bash
+npm install @radix-ui/react-dialog @radix-ui/react-dropdown-menu @radix-ui/react-label @radix-ui/react-select @radix-ui/react-slot @radix-ui/react-tooltip class-variance-authority clsx tailwind-merge
+```
+
+**Note**: The library includes shadcn component implementations in `components/ui/`, but you must install the peer dependencies above for them to work.
+
+## Usage
+
+### Basic Example (Standalone - No Dependencies)
+
+The library works completely standalone without any dependencies:
+
+```tsx
+import { PipelineCanvas, PipelineCanvasProvider } from '@novoprotein/pipeline-canvas';
+import '@novoprotein/pipeline-canvas/style.css';
+
+function App() {
+  return (
+    <PipelineCanvasProvider>
+      <div style={{ width: '100vw', height: '100vh' }}>
+        <PipelineCanvas />
+      </div>
+    </PipelineCanvasProvider>
+  );
+}
+```
+
+**Note**: Without dependencies, the library works in "offline mode":
+- Pipelines are saved locally (localStorage)
+- No backend sync
+- No authentication required
+- File uploads work if your API supports unauthenticated requests
+
+### With Authentication and API Client
+
+For full functionality (backend sync, authenticated operations):
+
+```tsx
+import { 
+  PipelineCanvas, 
+  PipelineCanvasProvider,
+  type ApiClient,
+  type AuthState 
+} from '@novoprotein/pipeline-canvas';
+import '@novoprotein/pipeline-canvas/style.css';
+
+function App() {
+  // Your API client (compatible with axios, fetch, or custom)
+  const apiClient: ApiClient = {
+    get: async (url: string) => {
+      const response = await fetch(`/api${url}`, {
+        headers: { 'Authorization': `Bearer ${token}` }
+      });
+      return { data: await response.json() };
+    },
+    post: async (url: string, data: any) => {
+      const response = await fetch(`/api${url}`, {
+        method: 'POST',
+        headers: { 
+          'Content-Type': 'application/json',
+          'Authorization': `Bearer ${token}`
+        },
+        body: JSON.stringify(data)
+      });
+      return { data: await response.json() };
+    },
+  };
+
+  // Your auth state
+  const authState: AuthState = {
+    user: { id: 'user-123', email: 'user@example.com' },
+    isAuthenticated: true,
+    accessToken: token,
+  };
+
+  // Session ID for execution context
+  const sessionId = 'session-456';
+
+  // Auth headers function for file uploads
+  const getAuthHeaders = () => ({
+    'Authorization': `Bearer ${token}`
+  });
+
+  return (
+    <PipelineCanvasProvider
+      apiClient={apiClient}
+      authState={authState}
+      sessionId={sessionId}
+      getAuthHeaders={getAuthHeaders}
+    >
+      <div style={{ width: '100vw', height: '100vh' }}>
+        <PipelineCanvas />
+      </div>
+    </PipelineCanvasProvider>
+  );
+}
+```
+
+### With Axios API Client
+
+If you're using axios:
+
+```tsx
+import axios from 'axios';
+import { PipelineCanvasProvider, type ApiClient } from '@novoprotein/pipeline-canvas';
+
+const apiClient: ApiClient = {
+  get: (url: string, config?) => axios.get(url, config),
+  post: (url: string, data?: any, config?) => axios.post(url, data, config),
+  put: (url: string, data?: any, config?) => axios.put(url, data, config),
+  patch: (url: string, data?: any, config?) => axios.patch(url, data, config),
+  delete: (url: string, config?) => axios.delete(url, config),
+};
+
+function App() {
+  return (
+    <PipelineCanvasProvider apiClient={apiClient}>
+      <PipelineCanvas />
+    </PipelineCanvasProvider>
+  );
+}
+```
+
+### Partial Dependencies
+
+You can provide only the dependencies you need:
+
+```tsx
+// Only API client (no auth)
+<PipelineCanvasProvider apiClient={myApiClient}>
+  <PipelineCanvas />
+</PipelineCanvasProvider>
+
+// Only auth state (local operations only)
+<PipelineCanvasProvider authState={authState}>
+  <PipelineCanvas />
+</PipelineCanvasProvider>
+
+// Everything optional - works standalone
+<PipelineCanvasProvider>
+  <PipelineCanvas />
+</PipelineCanvasProvider>
+```
+
+### Using the Store
+
+```tsx
+import { usePipelineStore } from '@novoprotein/pipeline-canvas';
+
+function MyComponent() {
+  const { nodes, edges, addNode } = usePipelineStore();
+  
+  return (
+    <div>
+      <p>Nodes: {nodes.length}</p>
+      <button onClick={() => addNode({ id: '1', type: 'input', data: {} })}>
+        Add Node
+      </button>
+    </div>
+  );
+}
+```
+
+### Using Context Directly
+
+You can also access dependencies directly from context:
+
+```tsx
+import { usePipelineContext } from '@novoprotein/pipeline-canvas';
+
+function MyComponent() {
+  const { apiClient, authState, sessionId, getAuthHeaders } = usePipelineContext();
+  
+  // Use dependencies as needed
+  if (authState?.user) {
+    // User is authenticated
+  }
+  
+  return <div>...</div>;
+}
+```
+
+## Dependency Injection
+
+The library uses dependency injection to remain standalone and flexible. All dependencies are **optional**:
+
+- **`apiClient`**: For backend operations (save, load, sync pipelines)
+- **`authState`**: For user-specific features and authentication
+- **`sessionId`**: For execution context and session tracking
+- **`getAuthHeaders`**: For authenticated file uploads
+- **`logger`**: For structured logging (optional, uses console by default)
+- **`errorReporter`**: For error tracking (Sentry, LogRocket, etc.)
+
+### Graceful Degradation
+
+When dependencies are not provided:
+- ✅ Pipelines work locally (localStorage)
+- ✅ All UI features work
+- ✅ Pipeline execution works (with provided apiClient or external APIs)
+- ⚠️ Backend sync is skipped
+- ⚠️ User-specific features are disabled
+- ⚠️ File uploads may fail if API requires authentication
+
+### Integration Examples
+
+#### With Zustand Auth Store
+
+```tsx
+import { useAuthStore } from './stores/authStore';
+import { PipelineCanvasProvider } from '@novoprotein/pipeline-canvas';
+
+function App() {
+  const user = useAuthStore(state => state.user);
+  const token = useAuthStore(state => state.accessToken);
+  
+  const authState = {
+    user,
+    isAuthenticated: !!user,
+    accessToken: token,
+  };
+  
+  return (
+    <PipelineCanvasProvider authState={authState}>
+      <PipelineCanvas />
+    </PipelineCanvasProvider>
+  );
+}
+```
+
+#### With React Context Auth
+
+```tsx
+import { useContext } from 'react';
+import { AuthContext } from './AuthContext';
+import { PipelineCanvasProvider } from '@novoprotein/pipeline-canvas';
+
+function App() {
+  const { user, token } = useContext(AuthContext);
+  
+  return (
+    <PipelineCanvasProvider
+      authState={{ user, isAuthenticated: !!user, accessToken: token }}
+    >
+      <PipelineCanvas />
+    </PipelineCanvasProvider>
+  );
+}
+```
+
+## Logging and Error Tracking
+
+The library supports structured logging and error tracking through dependency injection. This allows you to integrate with your own logging systems (Sentry, LogRocket, Bugsnag, etc.) or use the default console logger.
+
+### Basic Usage (Default Logger)
+
+By default, the library uses a console logger that only logs in development mode:
+
+```tsx
+import { PipelineCanvasProvider } from '@novoprotein/pipeline-canvas';
+
+// No logger needed - uses default console logger (development only)
+<PipelineCanvasProvider>
+  <PipelineCanvas />
+</PipelineCanvasProvider>
+```
+
+### Custom Logger
+
+Provide your own logger for structured logging:
+
+```tsx
+import { 
+  PipelineCanvasProvider,
+  type Logger 
+} from '@novoprotein/pipeline-canvas';
+
+const myLogger: Logger = {
+  debug: (message, data) => {
+    // Your debug logging logic
+    console.debug(`[Pipeline] ${message}`, data);
+  },
+  info: (message, data) => {
+    // Your info logging logic
+    console.info(`[Pipeline] ${message}`, data);
+  },
+  warn: (message, data) => {
+    // Your warning logging logic
+    console.warn(`[Pipeline] ${message}`, data);
+  },
+  error: (message, error, data) => {
+    // Your error logging logic
+    console.error(`[Pipeline] ${message}`, error, data);
+  },
+};
+
+<PipelineCanvasProvider logger={myLogger}>
+  <PipelineCanvas />
+</PipelineCanvasProvider>
+```
+
+### Error Tracking (Sentry Example)
+
+Integrate with error tracking services:
+
+```tsx
+import * as Sentry from '@sentry/react';
+import { 
+  PipelineCanvasProvider,
+  type ErrorReporter 
+} from '@novoprotein/pipeline-canvas';
+
+const errorReporter: ErrorReporter = {
+  captureException: (error, context) => {
+    Sentry.captureException(error, {
+      extra: context,
+      tags: {
+        component: 'pipeline-canvas',
+      },
+    });
+  },
+  captureMessage: (message, level, context) => {
+    Sentry.captureMessage(message, {
+      level: level === 'error' ? 'error' : level === 'warning' ? 'warning' : 'info',
+      extra: context,
+      tags: {
+        component: 'pipeline-canvas',
+      },
+    });
+  },
+  setUser: (user) => {
+    Sentry.setUser({
+      id: user.id,
+      email: user.email,
+    });
+  },
+  setContext: (key, context) => {
+    Sentry.setContext(key, context);
+  },
+};
+
+<PipelineCanvasProvider errorReporter={errorReporter}>
+  <PipelineCanvas />
+</PipelineCanvasProvider>
+```
+
+### LogRocket Example
+
+```tsx
+import LogRocket from 'logrocket';
+import { PipelineCanvasProvider, type ErrorReporter } from '@novoprotein/pipeline-canvas';
+
+const errorReporter: ErrorReporter = {
+  captureException: (error, context) => {
+    LogRocket.captureException(error, {
+      extra: context,
+    });
+  },
+  captureMessage: (message, level, context) => {
+    LogRocket.captureMessage(message, {
+      level,
+      extra: context,
+    });
+  },
+  setUser: (user) => {
+    LogRocket.identify(user.id, {
+      email: user.email,
+    });
+  },
+};
+
+<PipelineCanvasProvider errorReporter={errorReporter}>
+  <PipelineCanvas />
+</PipelineCanvasProvider>
+```
+
+### Using Logger in Your Code
+
+You can access the logger from context:
+
+```tsx
+import { usePipelineContext } from '@novoprotein/pipeline-canvas';
+
+function MyComponent() {
+  const { logger } = usePipelineContext();
+  
+  const handleAction = () => {
+    logger?.info('Action performed', { action: 'click' });
+  };
+  
+  return <button onClick={handleAction}>Click me</button>;
+}
+```
+
+### What Gets Logged
+
+The library logs:
+- **Pipeline execution events**: Start, completion, errors
+- **Node execution**: Status changes, errors, results
+- **API requests**: Request/response details (if enabled)
+- **User actions**: Pipeline save, load, delete operations
+- **Errors**: All errors with full context (node ID, pipeline ID, error details)
+
+### Privacy and Security
+
+- **No automatic data collection**: Logging is opt-in via dependency injection
+- **You control what gets logged**: Provide your own logger/error reporter
+- **No external calls**: Default logger only uses console (no network requests)
+- **Context-aware**: All logs include relevant context (pipeline ID, node ID, etc.)
+
+### Styling
+
+The library uses Tailwind CSS classes and shadcn/ui CSS variables. Make sure Tailwind is configured in your project:
+
+```js
+// tailwind.config.js
+module.exports = {
+  content: [
+    './src/**/*.{js,jsx,ts,tsx}',
+    './node_modules/@novoprotein/pipeline-canvas/**/*.{js,jsx,ts,tsx}',
+  ],
+  theme: {
+    extend: {
+      // shadcn/ui theme variables are included in the library's style.css
+    },
+  },
+  // ... rest of config
+};
+```
+
+Also import the CSS file in your main entry:
+
+```tsx
+// main.tsx or App.tsx
+import '@novoprotein/pipeline-canvas/style.css';
+```
+
+The library includes shadcn/ui CSS variables for theming. The components support both light and dark themes via CSS variables.
+
+## Development
+
+```bash
+# Type check
+npm run type-check
+
+# Build
+npm run build
+```
+
+### Creating New Node Types
+
+When creating a new node type, **please read the [Node Development Guide](../../docs/node-development-guide.md)** first. It covers critical best practices and common pitfalls, including:
+
+- ✅ Always initialize nodes with default config
+- ✅ Keep execution logs accessible after completion
+- ✅ Don't force navigation during execution
+- ✅ Handle multiple data structures in output extraction
+- ✅ Common pitfalls and how to avoid them
+
+This guide will save you time and prevent common issues!
+
+## Project Structure
+
+```
+pipeline-canvas/
+├── components/          # React components
+│   ├── PipelineCanvas.tsx
+│   ├── PipelineNodeConfig.tsx
+│   ├── PipelineNodePalette.tsx
+│   ├── PipelineExecution.tsx
+│   ├── PipelineManager.tsx
+│   ├── CustomHandle.tsx
+│   └── ExecutionLogsPanel.tsx
+├── nodes/               # Node type configurations (JSON)
+│   ├── input_node/
+│   ├── rfdiffusion_node/
+│   ├── proteinmpnn_node/
+│   └── alphafold_node/
+├── store/               # Zustand store
+│   └── pipelineStore.ts
+├── types/               # TypeScript types
+│   └── index.ts
+├── utils/               # Utility functions
+│   ├── topologicalSort.ts
+│   └── nodeLoader.ts
+├── dist/                # Build output (generated)
+├── index.ts             # Main export file
+├── style.css            # CSS styles
+├── package.json
+├── tsconfig.json
+└── vite.config.ts
+```
+
+## License
+
+MIT
+

package/dist/_virtual/dynamic-import-helper.mjs

@@ -0,0 +1,17 @@
+const l = (r, n, t) => {
+  const e = r[n];
+  return e ? typeof e == "function" ? e() : Promise.resolve(e) : new Promise((i, o) => {
+    (typeof queueMicrotask == "function" ? queueMicrotask : setTimeout)(
+      o.bind(
+        null,
+        new Error(
+          "Unknown variable dynamic import: " + n + (n.split("/").length !== t ? ". Note that variables only represent file names one level deep." : "")
+        )
+      )
+    );
+  });
+};
+export {
+  l as default
+};
+//# sourceMappingURL=dynamic-import-helper.mjs.map

package/dist/_virtual/dynamic-import-helper.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"dynamic-import-helper.mjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;"}

package/dist/components/CustomHandle.d.ts

@@ -0,0 +1,9 @@
+import React from 'react';
+import { Position } from 'reactflow';
+interface CustomHandleProps {
+    type: 'source' | 'target';
+    position: Position;
+}
+export declare const CustomHandle: React.FC<CustomHandleProps>;
+export {};
+//# sourceMappingURL=CustomHandle.d.ts.map

package/dist/components/CustomHandle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CustomHandle.d.ts","sourceRoot":"","sources":["../../components/CustomHandle.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAU,QAAQ,EAAE,MAAM,WAAW,CAAC;AAE7C,UAAU,iBAAiB;IACzB,IAAI,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC1B,QAAQ,EAAE,QAAQ,CAAC;CACpB;AAED,eAAO,MAAM,YAAY,EAAE,KAAK,CAAC,EAAE,CAAC,iBAAiB,CAUpD,CAAC"}

package/dist/components/CustomHandle.mjs

@@ -0,0 +1,18 @@
+import { jsx as s } from "react/jsx-runtime";
+import { Position as r, Handle as m } from "reactflow";
+const a = ({ type: e, position: t }) => {
+  const o = t === r.Left;
+  return /* @__PURE__ */ s(
+    m,
+    {
+      type: e,
+      position: t,
+      className: "custom-handle",
+      style: o ? { left: -6 } : { right: -6 }
+    }
+  );
+};
+export {
+  a as CustomHandle
+};
+//# sourceMappingURL=CustomHandle.mjs.map

package/dist/components/CustomHandle.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"CustomHandle.mjs","sources":["../../components/CustomHandle.tsx"],"sourcesContent":["import React from 'react';\nimport { Handle, Position } from 'reactflow';\n\ninterface CustomHandleProps {\n  type: 'source' | 'target';\n  position: Position;\n}\n\nexport const CustomHandle: React.FC<CustomHandleProps> = ({ type, position }) => {\n  const isLeft = position === Position.Left;\n  return (\n    <Handle\n      type={type}\n      position={position}\n      className=\"custom-handle\"\n      style={isLeft ? { left: -6 } : { right: -6 }}\n    />\n  );\n};\n\n\n\n\n\n"],"names":["CustomHandle","type","position","isLeft","Position","jsx","Handle"],"mappings":";;AAQO,MAAMA,IAA4C,CAAC,EAAE,MAAAC,GAAM,UAAAC,QAAe;AAC/E,QAAMC,IAASD,MAAaE,EAAS;AACrC,SACE,gBAAAC;AAAA,IAACC;AAAA,IAAA;AAAA,MACC,MAAAL;AAAA,MACA,UAAAC;AAAA,MACA,WAAU;AAAA,MACV,OAAOC,IAAS,EAAE,MAAM,OAAO,EAAE,OAAO,GAAA;AAAA,IAAG;AAAA,EAAA;AAGjD;"}

package/dist/components/ExecutionLogsPanel.d.ts

@@ -0,0 +1,3 @@
+import React from 'react';
+export declare const ExecutionLogsPanel: React.FC;
+//# sourceMappingURL=ExecutionLogsPanel.d.ts.map

package/dist/components/ExecutionLogsPanel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExecutionLogsPanel.d.ts","sourceRoot":"","sources":["../../components/ExecutionLogsPanel.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AA8N1B,eAAO,MAAM,kBAAkB,EAAE,KAAK,CAAC,EAoItC,CAAC"}