# Swirl

**Visual workflow builder library for React** — drag-and-drop automation with React Flow and Material-UI.

[![npm version](https://img.shields.io/npm/v/@boltic/swirl.svg)](https://www.npmjs.com/package/@boltic/swirl)
[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
[![React](https://img.shields.io/badge/React-18.x-61dafb.svg)](https://reactjs.org/)
[![Material-UI](https://img.shields.io/badge/Material--UI-5.x-007fff.svg)](https://mui.com/)
[![React Flow](https://img.shields.io/badge/React%20Flow-Powered-3b82f6.svg)](https://reactflow.dev/)

---

## Installation

```bash
npm install @boltic/swirl
```

**Peer dependencies** (install in your app if not already present):

```bash
npm install react react-dom @mui/material @emotion/react @emotion/styled
```

---

## Quick Start

1. Import the component and styles.
2. Provide required configuration (URLs, entity ID, token, integration state).
3. Render `<WorkflowBuilder />` or `<ExecutionData />`.

### WorkflowBuilder (visual editor)

```tsx
import { WorkflowBuilder } from '@boltic/swirl';
import '@boltic/swirl/dist/style.css';

function App() {
    const WORKFLOW_URLS = {
        VORTEX_MAIN_URL: 'https://api.example.com/workflow',
        FRONTEND_URL: 'https://yourapp.com',
        VORTEX_WEBHOOK_URL: 'https://api.example.com/webhook',
        VORTEX_SYNC_DOMAIN: 'https://sync.example.com',
        SERVERLESS_URL: 'https://serverless.example.com',
        TESSERACT_MAIN_URL: 'https://tesseract.example.com',
        // Add other URLs your backend requires
    };

    return (
        <WorkflowBuilder
            WORKFLOW_URLS={WORKFLOW_URLS}
            ENTITY_ID="your-entity-id"
            TOKEN="your-auth-token"
            INTEGRATION_DATA={{}}
            SET_INTEGRATION_DATA={() => {}}
            USER_DATA={{}}
            currentSubscription={null}
            pro_integration={false}
            openUpgradeModal={() => {}}
            analytics={{}}
            ALERT_TOP_BAR={null}
            openIntegrationDrawer={(data) => console.log('Integration:', data)}
            api={undefined}
            navigate={(path) => window.history.pushState({}, '', path)}
        />
    );
}
```

### ExecutionData (execution monitoring)

Use this to show execution list and details (typically on a route like `/workflows/:workflowId/executions`). The component reads `workflowId` from the URL when used inside your router.

```tsx
import { ExecutionData } from '@boltic/swirl';
import '@boltic/swirl/dist/style.css';

function ExecutionsPage() {
    return (
        <ExecutionData
            WORKFLOW_URLS={WORKFLOW_URLS}
            ENTITY_ID="your-entity-id"
            TOKEN="your-auth-token"
            USER_DATA={{}}
            currentSubscription={null}
            openUpgradeModal={() => {}}
            analytics={{}}
            isAccountLevel={false}
            api={undefined}
            navigate={(path) => window.history.pushState({}, '', path)}
        />
    );
}
```

---

## Features

- **Visual workflow builder** — Drag-and-drop canvas for designing workflows (React Flow).
- **Node-based model** — Triggers, activities, conditions, loops, and parallel branches.
- **Execution monitoring** — List, filter, and inspect workflow runs and logs.
- **80+ activities** — HTTP, webhooks, email, Slack, mapper, conditions, scheduling, storage, AI, and more.
- **Ripple forms** — Schema-driven activity configuration.
- **Theming** — Material-UI theme; works with your app’s `ThemeProvider`.
- **TypeScript** — Typed props and exports (`WorkflowBuilderProps`, `ExecutionDataProps`, `IntegrationFormProps`).

---

## Exports

| Export            | Description                                                  |
| ----------------- | ------------------------------------------------------------ |
| `WorkflowBuilder` | Main workflow editor (canvas, palette, drawer, save/deploy). |
| `ExecutionData`   | Execution list and detail view (use on executions route).    |
| `IntegrationForm` | Standalone integration/activity form drawer (advanced).      |

---

## API Reference

### WorkflowBuilder props

| Prop                    | Type        | Required | Description                                  |
| ----------------------- | ----------- | -------- | -------------------------------------------- |
| `WORKFLOW_URLS`         | `object`    | Yes      | Service base URLs (see below).               |
| `ENTITY_ID`             | `string`    | Yes      | Tenant/organization identifier.              |
| `TOKEN`                 | `string`    | Yes      | Auth token for API calls.                    |
| `INTEGRATION_DATA`      | `object`    | Yes      | Integration/credential state.                |
| `SET_INTEGRATION_DATA`  | `function`  | Yes      | Updater for integration state.               |
| `USER_DATA`             | `object`    | Yes      | Current user context.                        |
| `currentSubscription`   | `any`       | Yes      | Subscription/plan data.                      |
| `pro_integration`       | `boolean`   | Yes      | Whether pro integrations are enabled.        |
| `openUpgradeModal`      | `function`  | Yes      | Callback to open upgrade UI.                 |
| `analytics`             | `object`    | Yes      | Analytics config.                            |
| `ALERT_TOP_BAR`         | `ReactNode` | Yes      | Optional top bar (e.g. banner).              |
| `openIntegrationDrawer` | `function`  | No       | Callback when user opens integration drawer. |
| `api`                   | `object`    | No       | Custom HTTP client (replaces default axios). |
| `navigate`              | `function`  | No       | Navigation function (e.g. router).           |

### ExecutionData props

| Prop                  | Type       | Required | Description                               |
| --------------------- | ---------- | -------- | ----------------------------------------- |
| `WORKFLOW_URLS`       | `object`   | Yes      | Service base URLs.                        |
| `ENTITY_ID`           | `string`   | Yes      | Tenant/organization identifier.           |
| `TOKEN`               | `string`   | Yes      | Auth token.                               |
| `USER_DATA`           | `object`   | Yes      | Current user context.                     |
| `currentSubscription` | `any`      | Yes      | Subscription data.                        |
| `openUpgradeModal`    | `function` | Yes      | Callback to open upgrade UI.              |
| `analytics`           | `object`   | Yes      | Analytics config.                         |
| `isAccountLevel`      | `boolean`  | Yes      | Whether view is account-level executions. |
| `api`                 | `object`   | No       | Custom HTTP client.                       |
| `navigate`            | `function` | No       | Navigation function.                      |

### WORKFLOW_URLS (shape)

Provide at least the URLs your backend and activities use. Common keys:

| Key                  | Description                              |
| -------------------- | ---------------------------------------- |
| `VORTEX_MAIN_URL`    | Main workflow API.                       |
| `FRONTEND_URL`       | Frontend app URL.                        |
| `VORTEX_WEBHOOK_URL` | Webhook base URL.                        |
| `VORTEX_SYNC_DOMAIN` | Sync service domain.                     |
| `SERVERLESS_URL`     | Serverless functions.                    |
| `TESSERACT_MAIN_URL` | OCR service.                             |
| `ATHENA_MAIN_URL`    | Analytics (optional).                    |
| …                    | Add any other keys your backend expects. |

---

## Theming

Swirl uses Material-UI. Wrap your app (or the Swirl components) in a `ThemeProvider` to match your app theme:

```tsx
import { ThemeProvider, createTheme } from '@mui/material/styles';
import { WorkflowBuilder } from '@boltic/swirl';
import '@boltic/swirl/dist/style.css';

const theme = createTheme({
    palette: {
        primary: { main: '#1976d2' },
        secondary: { main: '#dc004e' },
    },
});

function App() {
    return (
        <ThemeProvider theme={theme}>
            <WorkflowBuilder {...props} />
        </ThemeProvider>
    );
}
```

---

## Build outputs

When you install from npm you get:

- **ESM**: `dist/swirl.es.js`
- **UMD**: `dist/swirl.umd.js` (global `window.swirl`)
- **CSS**: `dist/style.css`
- **Types**: `dist/index.d.ts`

UMD example:

```html
<link rel="stylesheet" href="node_modules/@boltic/swirl/dist/style.css" />
<script src="node_modules/@boltic/swirl/dist/swirl.umd.js"></script>
<script>
    const { WorkflowBuilder } = window.swirl;
</script>
```

---

## Development (contributors)

- **Node**: 24.x LTS (≥ 24.0.0). Enforced via `engines` in package.json and `.npmrc` (`engine-strict=true`).
- **Commands**: `npm install` → `npm run build`
- **Local dev**: See repository for SSL and `run.local.sh` setup.
- **Publishing**: From `fcz0` (SIT), `fcz5` (UAT), or `master` (production). Use npm dist-tags `sit`, `uat`, or `latest`. Requires npm account with 2FA; contact [ahmedsakri@gofynd.com](mailto:ahmedsakri@gofynd.com) for publish access.

---

## Support

- **Email**: [ahmedsakri@gofynd.com](mailto:ahmedsakri@gofynd.com)

---

**Made with ❤️ by the Boltic Team**
