npm package: @mantir/headless-view
Description: A reusable headless execution view for Mantir workflows.
Author: Mantir Team
Latest version: 0.1.13

# @mantir/headless-view

A reusable, headless execution view for Mantir workflows. This package provides a complete UI experience for running workflows, handling interruptions, and visualizing progress.

## Installation

```bash
npm install @mantir/headless-view
# or
pnpm add @mantir/headless-view
# or
yarn add @mantir/headless-view
```

## Usage

### 1. Import Styles

If you are not using Tailwind CSS in your project, or you want the default Mantir styles "out of the box", import the CSS file in your main entry point (e.g., `_app.tsx`, `layout.tsx`, or `main.tsx`):

```tsx
import '@mantir/headless-view/styles.css';
```

### 2. Use the Component

```tsx
import { HeadlessExecutor } from '@mantir/headless-view';

function App() {
  const workflow = { /* your workflow object */ };

  return (
    <div className="my-container">
      <HeadlessExecutor 
        workflow={workflow} 
        apiEndpoint="/api/execute" 
        onResult={(result) => console.log('Final workflow result:', result)}
        onDone={() => console.log('Execution finished')}
        initialInput="Programmatic input value"
      />
    </div>
  );
}
```

### 3. Custom Logic with Hooks

If you want to build your own UI but use the Mantir execution logic:

```tsx
import { useWorkflowExecution } from '@mantir/headless-view';

function CustomExecutor({ workflow }) {
  const { 
    messages, 
    isRunning, 
    pendingInterrupt, 
    execute, // Programmatic trigger
    resume 
  } = useWorkflowExecution({
    apiEndpoint: "/api/execute",
    workflow: workflow, // Pass to enable initialInput auto-start
    initialInput: "Hello world",
    onResult: (data) => console.log(data),
    onDone: () => console.log("Done")
  });

  return (
    <div>
      {/* Your custom UI here */}
    </div>
  );
}
```

## Props / Hook Options

- **apiEndpoint**: `(string)` The URL to post workflow execution requests to.
- **workflow**: `(Workflow, optional)` The JSON workflow definition. When provided with `initialInput`, enables auto-start.
- **initialInput**: `(string, optional)` If provided, the workflow will automatically start on mount using this value.
- **onResult**: `(callback, optional)` Called when the workflow produces a final JSON result.
- **onDone**: `(callback, optional)` Called when the execution stream finishes completely.
- **onMessage**: `(callback, optional)` Called for every message/trace event.
- **onInterrupt**: `(callback, optional)` Called when the workflow requires user input.
- **onError**: `(callback, optional)` Called if a network or execution error occurs.

## Configuration for Tailwind CSS Projects

If your project already uses Tailwind CSS (v3 or v4) and you want to use your project's theme and styles, you should add the package to your Tailwind configuration instead of importing the CSS file.

### Tailwind CSS v4
In your `globals.css`:
```css
@source "path/to/node_modules/@mantir/headless-view/dist/**/*.{js,mjs}";
```

### Tailwind CSS v3
In your `tailwind.config.js`:
```javascript
module.exports = {
  content: [
    "./node_modules/@mantir/headless-view/dist/**/*.{js,mjs}",
    // ...
  ],
  // ...
}
```

## Peer Dependencies

- `react` >= 18
- `react-dom` >= 18

## API Reference

### `useWorkflowExecution` Hook

Returns an object with:

- **messages**: `Message[]` - Array of all messages from the workflow execution
- **isRunning**: `boolean` - Whether the workflow is currently executing
- **error**: `Error | null` - Any error that occurred during execution
- **pendingInterrupt**: `any | null` - Details of any pending user input request
- **currentThreadId**: `string | undefined` - The current execution thread ID
- **execute**: `(workflow: Workflow, input: string) => Promise<void>` - Programmatically start a workflow
- **restart**: `(workflow: Workflow, input: string) => Promise<void>` - Restart the workflow from the beginning
- **resume**: `(workflow: Workflow, value: any) => Promise<void>` - Resume after an interrupt
- **runExecution**: Internal execution function (advanced use only)

### Message Type

```typescript
interface Message {
  id: string;
  role: "user" | "assistant" | "system" | "trace";
  content: string;
  meta?: any;
}
```