@gongfu/prd-editor/README.md

A professional PRD (Product Requirements Document) editor SDK with AI-powered features

# @kongfu/prd-editor

A professional PRD (Product Requirements Document) editor SDK with AI-powered features, real-time collaboration, and comprehensive document management.

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

## Features

- 📝 **Rich Text Editing** - Full-featured editor based on Tiptap
- 🤖 **AI Assistant** - Generate requirements, user stories, and acceptance criteria
- 🔄 **Version Control** - Track changes and restore previous versions
- 💬 **Comments** - Collaborative discussions on sections and requirements
- 📊 **Structured Documents** - Organized sections, requirements, and user stories
- 🎨 **Templates** - Pre-built templates for different PRD types
- 📤 **Export** - Export to Markdown, PDF, Word, and HTML
- 🌍 **i18n Support** - English and Chinese localization
- 🎯 **Validation** - Built-in document validation and scoring
- 👥 **Collaboration** - Real-time multi-user editing (coming soon)

## Installation

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

## Quick Start

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

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

  const handlePublish = async (document) => {
    console.log('Publishing document:', document);
    // Publish the document
  };

  return (
    <div style={{ height: '100vh' }}>
      <PrdEditor
        onSave={handleSave}
        onPublish={handlePublish}
        showAiAssistant={true}
        autosave={true}
      />
    </div>
  );
}
```

## Advanced Usage

### With Initial Document

```tsx
const document = {
  id: '1',
  title: 'E-commerce Platform PRD',
  version: '1.0.0',
  status: 'draft',
  author: {
    id: 'user-1',
    name: 'John Doe',
  },
  createdAt: new Date(),
  updatedAt: new Date(),
  sections: [
    {
      id: 'overview',
      type: 'overview',
      title: 'Executive Summary',
      content: '<p>This PRD outlines the requirements for our new e-commerce platform...</p>',
      order: 0,
    },
  ],
  requirements: [
    {
      id: 'req-1',
      type: 'functional',
      priority: 'must-have',
      title: 'User Authentication',
      description: 'Users must be able to register and log in securely',
      acceptanceCriteria: [
        'Email validation',
        'Password strength requirements',
        'Remember me option',
      ],
      status: 'approved',
    },
  ],
  userStories: [],
};

<PrdEditor
  document={document}
  onSave={handleSave}
  mode="dark"
/>
```

### Using Templates

```tsx
import { defaultTemplates } from '@kongfu/prd-editor';

const customTemplate = {
  id: 'mvp',
  name: 'MVP Template',
  description: 'Minimal template for MVP products',
  sections: [
    { type: 'overview', title: 'Problem Statement', required: true },
    { type: 'objectives', title: 'MVP Goals', required: true },
    { type: 'requirements', title: 'Core Features', required: true },
    { type: 'user-stories', title: 'User Stories', required: true },
    { type: 'timeline', title: 'Launch Timeline', required: true },
  ],
};

<PrdEditor
  templates={[...defaultTemplates, customTemplate]}
  onTemplateSelect={(template) => {
    console.log('Selected template:', template);
  }}
/>
```

### AI Configuration

```tsx
<PrdEditor
  aiConfig={{
    enabled: true,
    apiKey: 'your-api-key',
    model: 'gpt-4',
    suggestions: {
      requirements: true,
      userStories: true,
      acceptanceCriteria: true,
      risks: true,
    },
  }}
/>
```

### Custom Theme

```tsx
<PrdEditor
  mode="dark"
  theme={{
    primaryColor: '#3b82f6',
    backgroundColor: '#1f2937',
    textColor: '#f9fafb',
    borderColor: '#374151',
    toolbarBackgroundColor: '#111827',
    sidebarBackgroundColor: '#1f2937',
    highlightColor: '#3b82f6',
    successColor: '#10b981',
    warningColor: '#f59e0b',
    errorColor: '#ef4444',
  }}
/>
```

### Export Options

```tsx
const handleExport = async (format) => {
  const exportOptions = {
    format,
    includeComments: true,
    includeVersionHistory: false,
    includeMetadata: true,
    watermark: 'CONFIDENTIAL',
  };
  
  // Handle export based on format
  switch (format) {
    case 'pdf':
      // Generate PDF
      break;
    case 'docx':
      // Generate Word document
      break;
    case 'markdown':
      // Already handled by default
      break;
  }
};

<PrdEditor
  onExport={handleExport}
/>
```

### Using the Store

```tsx
import { usePrdStore } from '@kongfu/prd-editor';

function DocumentStats() {
  const { document, validation, calculateProgress } = usePrdStore();
  
  if (!document) return null;
  
  const progress = calculateProgress(document);
  
  return (
    <div>
      <h3>Document Progress</h3>
      <p>Requirements: {progress.completed}/{progress.total}</p>
      <p>Completion: {progress.percentage}%</p>
      
      {validation && (
        <div>
          <p>Validation Score: {validation.score}/100</p>
          <p>Errors: {validation.errors.length}</p>
          <p>Warnings: {validation.warnings.length}</p>
        </div>
      )}
    </div>
  );
}
```

## API Reference

### PrdEditor Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `document` | `PrdDocument` | - | Initial document to load |
| `mode` | `'light' \| 'dark'` | `'light'` | Color mode |
| `readOnly` | `boolean` | `false` | Disable editing |
| `showToolbar` | `boolean` | `true` | Show editor toolbar |
| `showOutline` | `boolean` | `true` | Show document outline |
| `showComments` | `boolean` | `true` | Show comments panel |
| `showVersionHistory` | `boolean` | `true` | Show version history |
| `showAiAssistant` | `boolean` | `true` | Show AI assistant |
| `autosave` | `boolean` | `true` | Enable autosave |
| `autosaveInterval` | `number` | `30000` | Autosave interval (ms) |
| `templates` | `PrdTemplate[]` | - | Available templates |
| `locale` | `'en' \| 'zh-CN'` | `'en'` | UI language |
| `theme` | `PrdEditorTheme` | - | Custom theme |
| `aiConfig` | `AiConfig` | - | AI configuration |
| `onChange` | `(document) => void` | - | Document change handler |
| `onSave` | `(document) => Promise<void>` | - | Save handler |
| `onPublish` | `(document) => Promise<void>` | - | Publish handler |
| `onExport` | `(format) => Promise<void>` | - | Export handler |

### Document Structure

```typescript
interface PrdDocument {
  id: string;
  title: string;
  version: string;
  status: 'draft' | 'review' | 'approved' | 'published';
  author: {
    id: string;
    name: string;
    avatar?: string;
  };
  createdAt: Date;
  updatedAt: Date;
  publishedAt?: Date;
  sections: PrdSection[];
  requirements: PrdRequirement[];
  userStories: UserStory[];
  collaborators?: Collaborator[];
  tags?: string[];
  metadata?: Record<string, any>;
}
```

### Section Types

- `overview` - Executive summary
- `background` - Context and background
- `objectives` - Goals and objectives
- `scope` - Project scope
- `requirements` - Detailed requirements
- `user-stories` - User stories
- `acceptance-criteria` - Acceptance criteria
- `timeline` - Timeline and milestones
- `risks` - Risks and mitigation
- `appendix` - Additional information
- `custom` - Custom section type

### Requirement Priorities

- `must-have` - Critical requirements
- `should-have` - Important requirements
- `could-have` - Nice-to-have features
- `wont-have` - Out of scope

## Keyboard Shortcuts

| Shortcut | Action |
|----------|--------|
| `Ctrl/Cmd + S` | Save document |
| `Ctrl/Cmd + B` | Bold text |
| `Ctrl/Cmd + I` | Italic text |
| `Ctrl/Cmd + K` | Insert link |
| `Ctrl/Cmd + Z` | Undo |
| `Ctrl/Cmd + Shift + Z` | Redo |
| `Ctrl/Cmd + /` | Toggle comment |

## 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