@gongfu/prompt-editor/README.md

A powerful prompt engineering editor SDK for AI applications

# @kongfu/prompt-editor

A powerful and flexible prompt engineering editor SDK for AI applications. Build professional prompt management interfaces with ease.

[![npm version](https://img.shields.io/npm/v/@kongfu/prompt-editor.svg)](https://www.npmjs.com/package/@kongfu/prompt-editor)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Features

- 🎨 **Beautiful UI** - Modern, clean interface with light/dark mode support
- 🔧 **Variable System** - Define and manage dynamic variables with validation
- 👁️ **Live Preview** - See prompt output in real-time as you edit
- 📝 **Monaco Editor** - Powerful code editing with syntax highlighting
- 🌍 **i18n Support** - Built-in English and Chinese localization
- 📦 **Import/Export** - Support for JSON, YAML, Markdown, and plain text
- 🎯 **Type Safe** - Full TypeScript support with comprehensive types
- 🎭 **Customizable** - Extensive configuration options and theming
- ⚡ **Lightweight** - Minimal dependencies, optimized bundle size

## Installation

```bash
npm install @kongfu/prompt-editor
# or
yarn add @kongfu/prompt-editor
# or
pnpm add @kongfu/prompt-editor
```

## Quick Start

```tsx
import { PromptEditor } from '@kongfu/prompt-editor';
import '@kongfu/prompt-editor/styles.css';

function App() {
  const handleSave = async (template) => {
    console.log('Saving template:', template);
    // Save to your backend
  };

  return (
    <PromptEditor
      height="600px"
      onSave={handleSave}
      locale="en"
    />
  );
}
```

## Advanced Usage

### With Initial Template

```tsx
const initialTemplate = {
  id: 'welcome-email',
  name: 'Welcome Email Template',
  content: 'Hello {{userName}},\n\nWelcome to {{companyName}}!',
  variables: [
    {
      name: 'userName',
      type: 'text',
      description: 'The name of the user',
      required: true,
    },
    {
      name: 'companyName',
      type: 'text',
      defaultValue: 'Our Company',
    },
  ],
};

<PromptEditor
  initialTemplate={initialTemplate}
  showPreview={true}
  onSave={handleSave}
/>
```

### Custom Variable Types

```tsx
const customVariableTypes = [
  {
    type: 'date',
    label: 'Date',
    defaultValue: new Date().toISOString().split('T')[0],
    render: ({ value, onChange }) => (
      <input
        type="date"
        value={value}
        onChange={(e) => onChange(e.target.value)}
      />
    ),
    validate: (value) => {
      if (!value) return 'Date is required';
      return true;
    },
  },
];

<PromptEditor
  customVariableTypes={customVariableTypes}
/>
```

### Custom Toolbar Actions

```tsx
const customToolbar = {
  showSave: true,
  showExport: true,
  customActions: [
    {
      id: 'test',
      label: 'Test Prompt',
      icon: <TestIcon />,
      onClick: () => {
        // Test prompt with AI
      },
    },
  ],
};

<PromptEditor
  toolbar={customToolbar}
/>
```

### Theming

```tsx
const darkTheme = {
  primaryColor: '#3b82f6',
  backgroundColor: '#1a1a1a',
  textColor: '#e0e0e0',
  borderColor: '#404040',
  monacoTheme: 'vs-dark',
};

<PromptEditor
  mode="dark"
  theme={darkTheme}
/>
```

## API Reference

### PromptEditor Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `initialTemplate` | `PromptTemplate` | - | Initial template to load |
| `mode` | `'light' \| 'dark'` | `'light'` | Color mode |
| `height` | `string \| number` | `'600px'` | Editor height |
| `width` | `string \| number` | `'100%'` | Editor width |
| `readOnly` | `boolean` | `false` | Make editor read-only |
| `showLineNumbers` | `boolean` | `true` | Show line numbers |
| `showVariablePanel` | `boolean` | `true` | Show variable panel |
| `showPreview` | `boolean` | `true` | Show preview panel |
| `locale` | `'en' \| 'zh-CN'` | `'en'` | UI language |
| `theme` | `PromptEditorTheme` | - | Custom theme |
| `onSave` | `(template: PromptTemplate) => void \| Promise<void>` | - | Save callback |
| `onExport` | `(template: PromptTemplate, format: ExportFormat) => void` | - | Export callback |
| `onImport` | `(file: File) => Promise<PromptTemplate>` | - | Import callback |
| `customVariableTypes` | `CustomVariableType[]` | - | Custom variable types |
| `toolbar` | `ToolbarConfig` | - | Toolbar configuration |

### Types

```typescript
interface PromptTemplate {
  id: string;
  name: string;
  description?: string;
  content: string;
  variables: PromptVariable[];
  category?: string;
  tags?: string[];
  author?: string;
  version?: string;
  createdAt?: Date;
  updatedAt?: Date;
}

interface PromptVariable {
  name: string;
  type: 'text' | 'number' | 'boolean' | 'select' | 'multiline';
  description?: string;
  defaultValue?: any;
  required?: boolean;
  options?: Array<{ label: string; value: any }>;
  validation?: {
    min?: number;
    max?: number;
    pattern?: string;
    message?: string;
  };
}
```

## Using with Zustand Store

The editor comes with a built-in Zustand store for advanced state management:

```tsx
import { usePromptEditorStore } from '@kongfu/prompt-editor';

function MyComponent() {
  const { 
    template, 
    updateVariable, 
    addVariable,
    validate 
  } = usePromptEditorStore();

  // Access and modify editor state programmatically
}
```

## Export/Import Formats

### JSON Format
```json
{
  "id": "template-1",
  "name": "My Template",
  "content": "Hello {{name}}",
  "variables": [
    {
      "name": "name",
      "type": "text",
      "required": true
    }
  ]
}
```

### YAML Format
```yaml
id: template-1
name: My Template
content: Hello {{name}}
variables:
  - name: name
    type: text
    required: true
```

### Markdown Format
```markdown
# My Template

## Variables

### `{{name}}`
- Type: text
- Required: Yes

## Prompt

```
Hello {{name}}
```
```

## Styling

The component uses CSS variables for theming. You can override them:

```css
.prompt-editor {
  --pe-primary: #2563eb;
  --pe-primary-hover: #1d4ed8;
  --pe-bg-primary: #ffffff;
  --pe-text-primary: #333333;
  --pe-border: #e0e0e0;
}
```

## Browser Support

- Chrome (latest)
- Firefox (latest)
- Safari (latest)
- Edge (latest)

## Contributing

Contributions are welcome! Please read our contributing guidelines before submitting PRs.

## License

MIT © Kongfu Team