npm package: @orsetra/karavan-designer
Description: Apache Camel Karavan Designer - Visual integration designer for Apache Camel with IBM Carbon Design System and Tailwind CSS
Author: Apache Camel Karavan Team
Latest version: 4.11.16

# Karavan Designer

Apache Camel Karavan Designer - Visual integration designer for Apache Camel

## Installation

```bash
npm install karavan-designer
# or
pnpm add karavan-designer
# or
yarn add karavan-designer
```

## Peer Dependencies

This package requires the following peer dependencies:

```json
{
  "react": "^18.0.0",
  "react-dom": "^18.0.0",
  "@orsetra/karavan-core": "^4.14.0"
}
```

## Usage

### Basic Usage

```typescript
import { KaravanApp } from '@orsetra/karavan-designer';
import { FetchDataProvider } from '@orsetra/karavan-designer/providers';
import '@patternfly/patternfly/patternfly.css';
import '@orsetra/karavan-designer/styles.css';

function App() {
  const dataProvider = new FetchDataProvider();

  return (
    <KaravanApp 
      dataProvider={dataProvider}
    />
  );
}
```

### With Custom Providers

```typescript
import { KaravanApp, DefaultCoreProvider } from 'karavan-designer';
import { FetchDataProvider } from 'karavan-designer/providers';

function App() {
  const coreProvider = new DefaultCoreProvider();
  const dataProvider = new FetchDataProvider();

  return (
    <KaravanApp 
      coreProvider={coreProvider}
      dataProvider={dataProvider}
    />
  );
}
```

### Using Individual Components

```typescript
import { KaravanLayout, MenuItem } from 'karavan-designer';
import { BlueprintIcon } from '@patternfly/react-icons';

function MyApp() {
  const pages = [
    new MenuItem("designer", "Designer", <BlueprintIcon/>),
    // ... more pages
  ];

  return (
    <KaravanLayout 
      loaded={true}
      pages={pages}
    >
      {(pageId, setPageId) => <YourPageContent />}
    </KaravanLayout>
  );
}
```

## Provider System

Karavan Designer uses a provider system to separate data loading from UI logic.

### CoreProvider

Interface for loading Camel core components:

```typescript
interface CoreProvider {
  loadComponents(): Promise<string[]>;
  loadKamelets(): Promise<string[]>;
  loadBeans(): Promise<string[]>;
  loadTemplates(): Promise<Map<string, string>>;
}
```

**DefaultCoreProvider** is used automatically if no `coreProvider` is specified.

### DataProvider

Interface for loading project data:

```typescript
interface DataProvider {
  loadData(): Promise<ProjectFile[]>;
  saveFile(filename: string, code: string, propertyOnly: boolean): Promise<void>;
}
```

### Creating Custom Providers

```typescript
import { DataProvider, ProjectFile } from 'karavan-designer/providers';

export class ApiDataProvider implements DataProvider {
  constructor(private apiUrl: string) {}

  async loadData(): Promise<ProjectFile[]> {
    const response = await fetch(`${this.apiUrl}/projects`);
    return response.json();
  }

  async saveFile(filename: string, code: string): Promise<void> {
    await fetch(`${this.apiUrl}/files/${filename}`, {
      method: 'PUT',
      body: code
    });
  }
}
```

## Components

### KaravanApp

Main application component with data loading and routing.

**Props:**
- `coreProvider?: CoreProvider` - Optional, defaults to DefaultCoreProvider
- `dataProvider: DataProvider` - Required

### KaravanLayout

Layout component with navigation and page management.

**Props:**
- `loaded: boolean` - Loading state
- `initialPageId?: string` - Initial page to display
- `pages: MenuItem[]` - Available pages
- `onPageChange?: (pageId: string) => void` - Page change callback
- `children: (pageId: string, setPageId: (pageId: string) => void) => React.ReactNode` - Render prop

### DesignerPage

Visual designer for Apache Camel routes.

### KnowledgebaseHome

Documentation and reference for Camel components and patterns.

## Styling

The package includes all necessary styles bundled in a single file for easy import.

### Simple Import (Recommended)

Import all styles at once:

```typescript
import '@patternfly/patternfly/patternfly.css';
import '@orsetra/karavan-designer/styles.css';
```

This single import includes all Karavan Designer styles:
- Base styles
- Designer components
- Properties panels
- Expression editors
- Topology views
- Knowledgebase

### Granular Import (Advanced)

For advanced users who want more control, individual CSS files are also available:

```typescript
// Import only specific styles
import '@orsetra/karavan-designer/dist/designer/karavan.css';
import '@orsetra/karavan-designer/dist/designer/route/DslElement.css';
// ... other specific styles
```

### Required Peer Styles

PatternFly styles are required and must be imported separately:

```bash
npm install @patternfly/patternfly
```

```typescript
import '@patternfly/patternfly/patternfly.css';
```

## License

Apache-2.0

## Links

- [Apache Camel](https://camel.apache.org/)
- [Apache Camel Karavan](https://github.com/apache/camel-karavan)