@eventcatalogtest/visualizer/README.md

ReactFlow nodes and visualizer components for EventCatalog Studio

# @eventcatalogtest/visualizer

React components for visualizing EventCatalog nodes, built for ReactFlow.

## Installation

```bash
npm install @eventcatalogtest/visualizer
# or
pnpm add @eventcatalogtest/visualizer
```

## Setup

### 1. Import the CSS (Required)

The components use Tailwind CSS classes. Import the CSS file in your main CSS file:

```css
/* In your main CSS file (e.g., globals.css, index.css) */
@import '@eventcatalogtest/visualizer/dist/styles.css';
```

### 2. Configure Tailwind (Required for proper styling)

The visualizer components use Tailwind CSS classes. You must configure your build system to include these classes:

#### For Tailwind CSS v4 (PostCSS):
Add the visualizer package to your `postcss.config.js`:

```js
export default {
  plugins: {
    "@tailwindcss/postcss": {
      content: [
        // ... your existing paths
        './node_modules/@eventcatalogtest/visualizer/dist/**/*.{js,mjs}',
        './node_modules/@eventcatalogtest/visualizer/src/**/*.{js,ts,jsx,tsx}',
      ],
    },
  },
};
```

#### For Tailwind CSS v3 (Config file):
Add the visualizer package to your `content` paths in `tailwind.config.js`:

```js
module.exports = {
  content: [
    // ... your existing paths
    './node_modules/@eventcatalogtest/visualizer/dist/**/*.{js,mjs}',
    './node_modules/@eventcatalogtest/visualizer/src/**/*.{js,ts,jsx,tsx}',
  ],
  // ... rest of config
}
```

**⚠️ Important**: Without this configuration, the Tailwind classes used by the visualizer components will be purged from your CSS build, resulting in unstyled components.

## Usage

### Basic EventNode

```tsx
import { EventNode } from '@eventcatalogtest/visualizer';

// Use as standalone component
<EventNode
  id="event-1"
  data={{
    name: "User Registered",
    version: "1.0.0",
    summary: "Fired when a user registers for the first time",
    mode: "full",
    owners: ["team-auth", "team-users"],
    sends: ["user-profile-updated"],
    receives: ["user-registration-request"]
  }}
  selected={false}
/>
```

### Standalone Usage

The EventNode is a pure visual component that can be used anywhere:

```tsx
import { EventNode } from '@eventcatalogtest/visualizer';

<EventNode
  id="event-1"
  data={{
    name: "User Registered",
    version: "1.0.0",
    summary: "Fired when a user registers for the first time",
    mode: "full",
  }}
  selected={false}
/>
```

### With ReactFlow

For ReactFlow integration, wrap the EventNode with ReactFlow handles:

```tsx
import { ReactFlow, Handle, Position } from '@xyflow/react';
import { EventNode } from '@eventcatalogtest/visualizer';

// Create a ReactFlow node wrapper
function ReactFlowEventNode(props) {
  const { id, data, selected } = props;
  return (
    <>
      <Handle type="target" position={Position.Left} />
      <Handle type="source" position={Position.Right} />
      <EventNode id={id} data={data} selected={selected} />
    </>
  );
}

const nodeTypes = {
  event: ReactFlowEventNode,
};

const nodes = [
  {
    id: '1',
    type: 'event',
    position: { x: 100, y: 100 },
    data: {
      name: 'User Registered',
      version: '1.0.0',
      summary: 'Fired when a user registers',
      mode: 'full',
    },
  },
];

export default function MyFlow() {
  return (
    <ReactFlow
      nodes={nodes}
      nodeTypes={nodeTypes}
    />
  );
}
```

## Node Configuration

The visualizer also exports node configurations:

```tsx
import { eventConfig } from '@eventcatalogtest/visualizer';

// Access node metadata
console.log(eventConfig.type); // 'event'
console.log(eventConfig.color); // 'orange'
console.log(eventConfig.icon); // Zap component
```

## Props

### EventNodeProps

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `id` | `string` | required | Node ID |
| `data` | `EventNodeData` | required | Node data |
| `selected` | `boolean` | `false` | Whether node is selected |

### EventNodeData

| Property | Type | Description |
|----------|------|-------------|
| `name` | `string` | Event name |
| `version` | `string` | Event version |
| `summary` | `string` | Event description |
| `mode` | `'simple' \| 'full'` | Display mode |
| `owners` | `string[]` | Event owners |
| `sends` | `string[]` | Messages this event sends |
| `receives` | `string[]` | Messages this event receives |

## Styling

Components are styled with Tailwind CSS classes. The package includes:

- **Tailwind Classes**: All standard Tailwind utilities used in components
- **Custom CSS**: Minimal custom styles exported in `dist/styles.css`
- **Responsive**: Components work across different screen sizes
- **Themeable**: Easy to customize with Tailwind's theming system

## Features

- ✅ **Pure Visual Component**: Clean separation between visual and ReactFlow concerns
- ✅ **Standalone Usage**: Works perfectly outside ReactFlow contexts
- ✅ **TypeScript**: Full TypeScript support with proper types
- ✅ **Self-Contained Styling**: Complete CSS bundle with all required Tailwind classes
- ✅ **Configurable**: Support for simple and full display modes
- ✅ **Framework Agnostic**: Can be wrapped for any flow library (ReactFlow, etc.)
- ✅ **Zero Dependencies**: No ReactFlow dependency, just pure React component