kc-plate-editor 0.2.1 → 0.3.0

package/README.md

@@ -4,6 +4,7 @@ A powerful and customizable rich text editor built on [Plate](https://platejs.or
 
 ## Features
 
+### 核心功能
 - 🎨 **Rich Text Editing**: Support for headings, lists, tables, code blocks, and more
 - 🤖 **AI-Powered**: Built-in AI assistance and copilot features
 - 🎯 **Drag & Drop**: Intuitive drag-and-drop interface for blocks
@@ -12,10 +13,25 @@ A powerful and customizable rich text editor built on [Plate](https://platejs.or
 - 💬 **Collaboration**: Comments and suggestions
 - 🌐 **Internationalization**: Built-in i18n support (English & Chinese)
 - 📱 **Responsive**: Adaptive toolbar for mobile and desktop
+
+### 工具栏系统
 - ⚙️ **Configurable Toolbar**: Flexible toolbar configuration system with visual configurator
-- 🔌 **Extended API**: Markdown/HTML import/export, text extraction
-- 🎨 **Customizable**: Extensive plugin system and theming support
-- 📦 **TypeScript**: Full TypeScript support with type definitions
+- 🎯 **Toolbar Presets**: Pre-configured toolbar templates (Full, Basic, Minimal, Rich Text, Markdown, Blog, Document, Comment)
+- 🔧 **Granular Control**: Fine-grained control over individual toolbar features
+
+### 扩展功能
+- 🔍 **Find & Replace**: Built-in text search and replace functionality
+- 📊 **Word Count**: Real-time word, character, and paragraph counting
+- 📑 **Outline Navigation**: Automatic document outline generation
+- 📤 **Export**: Export to HTML, Markdown, PDF, and Image formats
+- 🖥️ **Fullscreen Mode**: Distraction-free fullscreen editing
+
+### 开发体验
+- 🔌 **Extended API**: Comprehensive API with 30+ methods for content manipulation
+- 🛡️ **Error Handling**: Unified error handling with error boundaries
+- 📦 **TypeScript**: Full TypeScript support with comprehensive type definitions
+- 🚀 **Performance**: Optimized rendering with React.memo and useMemo
+- 🔧 **Plugin System**: Flexible plugin architecture with helper utilities
 - ⚡ **Modern Stack**: Built with React 19, Vite, and Tailwind CSS
 
 ## Installation
@@ -89,38 +105,54 @@ function App() {
 Configure exactly which toolbar features you need:
 
 ```tsx
-import { PlateEditor, createMinimalConfig, createFullConfig } from 'kc-plate-editor';
+import {
+  PlateEditor,
+  MINIMAL_TOOLBAR,
+  BASIC_TOOLBAR,
+  RICH_TEXT_TOOLBAR,
+  MARKDOWN_TOOLBAR,
+  BLOG_TOOLBAR,
+  DOCUMENT_TOOLBAR,
+  COMMENT_TOOLBAR,
+  getToolbarPreset,
+} from 'kc-plate-editor';
 import type { ToolbarConfig } from 'kc-plate-editor';
 
 function App() {
-  // Minimal configuration
-  const minimalConfig: ToolbarConfig = {
-    history: true,
-    textFormat: ['bold', 'italic', 'underline'],
-    insert: ['link'],
-  };
-  
-  // Comment editor configuration
-  const commentConfig: ToolbarConfig = {
-    history: true,
-    textFormat: ['bold', 'italic'],
-    insert: ['link', 'emoji'],
-  };
-  
-  // Full configuration (all features)
-  const fullConfig = createFullConfig();
-  
+  // Use preset configurations
   return (
     <>
       {/* Minimal editor */}
-      <PlateEditor toolbarConfig={minimalConfig} />
-      
+      <PlateEditor toolbarConfig={MINIMAL_TOOLBAR} />
+
+      {/* Basic editor */}
+      <PlateEditor toolbarConfig={BASIC_TOOLBAR} />
+
+      {/* Rich text editor */}
+      <PlateEditor toolbarConfig={RICH_TEXT_TOOLBAR} />
+
+      {/* Markdown editor */}
+      <PlateEditor toolbarConfig={MARKDOWN_TOOLBAR} />
+
+      {/* Blog editor */}
+      <PlateEditor toolbarConfig={BLOG_TOOLBAR} />
+
+      {/* Document editor */}
+      <PlateEditor toolbarConfig={DOCUMENT_TOOLBAR} />
+
       {/* Comment editor */}
-      <PlateEditor toolbarConfig={commentConfig} />
-      
-      {/* Full featured editor */}
-      <PlateEditor toolbarConfig={fullConfig} />
-      
+      <PlateEditor toolbarConfig={COMMENT_TOOLBAR} />
+
+      {/* Or use getToolbarPreset */}
+      <PlateEditor toolbarConfig={getToolbarPreset('minimal')} />
+
+      {/* Custom configuration */}
+      <PlateEditor toolbarConfig={{
+        history: true,
+        textFormat: ['bold', 'italic', 'underline'],
+        insert: ['link', 'image'],
+      }} />
+
       {/* Default editor (all features) */}
       <PlateEditor />
     </>
@@ -181,12 +213,17 @@ function App() {
 |------|------|---------|-------------|
 | value | Value | - | Editor content (controlled) |
 | onChange | (value: Value) => void | - | Content change callback |
-| plugins | any[] | - | Custom plugin list |
+| plugins | EditorPluginKit | - | Custom plugin list |
 | toolbarConfig | ToolbarConfig | - | Toolbar configuration (see below) |
 | className | string | - | Custom CSS class |
 | disabled | boolean | false | Disable editor |
 | readOnly | boolean | false | Read-only mode |
 | autoFocus | boolean | false | Auto focus on mount |
+| showToolbar | boolean | true | Show/hide toolbar |
+| toolbarSticky | boolean | true | Make toolbar sticky |
+| mode | 'edit' \| 'view' \| 'suggestion' | 'edit' | Editor mode |
+| onModifiedChange | (isModified: boolean) => void | - | Modified state callback |
+| onFullscreenChange | (isFullscreen: boolean) => void | - | Fullscreen state callback |
 
 ### ToolbarConfig
 
@@ -197,14 +234,28 @@ interface ToolbarConfig {
   color?: boolean | ('textColor' | 'backgroundColor' | 'highlight')[];
   align?: boolean | ('left' | 'center' | 'right' | 'justify')[];
   list?: boolean | ('bulleted' | 'numbered' | 'todo')[];
-  insert?: boolean | ('link' | 'image' | 'video' | 'table' | 'emoji' | 'equation')[];
+  insert?: boolean | ('link' | 'image' | 'video' | 'audio' | 'file' | 'table' | 'emoji' | 'equation')[];
   advanced?: boolean | ('ai' | 'comment' | 'export' | 'import')[];
   typography?: boolean | ('fontSize' | 'lineHeight')[];
   extraFormat?: boolean | ('superscript' | 'subscript' | 'keyboard')[];
   blockOps?: boolean | ('indent' | 'outdent' | 'toggle')[];
+  turnInto?: boolean;
 }
 ```
 
+**Toolbar Presets:**
+
+| Preset | Description | Use Case |
+|--------|-------------|----------|
+| `FULL_TOOLBAR` | All features enabled | Full-featured editor |
+| `BASIC_TOOLBAR` | Common text editing features | General purpose editing |
+| `MINIMAL_TOOLBAR` | Minimal feature set | Simple text input |
+| `RICH_TEXT_TOOLBAR` | Rich formatting features | Document editing |
+| `MARKDOWN_TOOLBAR` | Markdown-focused features | Markdown editing |
+| `BLOG_TOOLBAR` | Blog post editing features | Blog/article writing |
+| `DOCUMENT_TOOLBAR` | Formal document features | Professional documents |
+| `COMMENT_TOOLBAR` | Comment/annotation features | Comments and notes |
+
 **Examples:**
 
 ```typescript
@@ -221,33 +272,73 @@ interface ToolbarConfig {
   insert: ['link', 'image'],
   list: true
 }
+
+// Use preset
+import { MARKDOWN_TOOLBAR } from 'kc-plate-editor';
+<PlateEditor toolbarConfig={MARKDOWN_TOOLBAR} />
 ```
 
 ### PlateEditorRef Methods
 
+The editor ref provides 30+ methods for comprehensive content manipulation:
+
 ```typescript
 interface PlateEditorRef {
-  // Content management
-  getContent: () => Value;              // Get editor content (JSON)
-  setContent: (content: Value) => void; // Set editor content
-  resetContent: () => void;             // Reset to initial content
-  getEditor: () => any;                 // Get editor instance (advanced)
-  
-  // Markdown support
-  getMarkdown: () => string;            // Export as Markdown
-  setMarkdown: (markdown: string) => void; // Load from Markdown
-  
-  // HTML support
-  getHtml: () => Promise<string>;       // Export as HTML
-  setHtml: (html: string) => void;      // Load from HTML
-  
-  // Text utilities
-  getText: () => string;                // Get plain text
-  isEmpty: () => boolean;               // Check if empty
-  
-  // Editor control
-  focus: () => void;                    // Focus editor
-  blur: () => void;                     // Blur editor
+  // ========== Content Management ==========
+  getContent: () => Value;                    // Get editor content (JSON)
+  setContent: (content: Value) => void;       // Set editor content
+  resetContent: () => void;                   // Reset to initial content
+  getEditor: () => TPlateEditor;              // Get editor instance (advanced)
+
+  // ========== Markdown Support ==========
+  getMarkdown: () => string;                  // Export as Markdown
+  setMarkdown: (markdown: string) => void;    // Load from Markdown
+
+  // ========== HTML Support ==========
+  getHtml: () => Promise<string>;             // Export as HTML
+  setHtml: (html: string) => void;            // Load from HTML
+
+  // ========== Text Utilities ==========
+  getText: () => string;                      // Get plain text
+  isEmpty: () => boolean;                     // Check if empty
+
+  // ========== Editor Control ==========
+  focus: () => void;                          // Focus editor
+  blur: () => void;                           // Blur editor
+
+  // ========== Modified State ==========
+  isModified: () => boolean;                  // Check if content is modified
+  resetModifiedState: () => void;             // Reset modified state
+
+  // ========== Content Insertion ==========
+  insertText: (text: string) => void;         // Insert text
+  insertMarkdown: (markdown: string) => void; // Insert Markdown content
+  toggleMark: (mark: string) => void;         // Toggle mark (bold, italic, etc.)
+  insertLink: (url: string, text?: string) => void; // Insert link
+  insertImage: (url: string) => void;         // Insert image
+
+  // ========== History Operations ==========
+  undo: () => void;                           // Undo
+  redo: () => void;                           // Redo
+
+  // ========== Export Functions ==========
+  exportAsHtml: (filename?: string) => Promise<void>;     // Export as HTML file
+  exportAsMarkdown: (filename?: string) => Promise<void>; // Export as Markdown file
+  exportAsPdf: (filename?: string) => Promise<void>;      // Export as PDF file
+  exportAsImage: (filename?: string) => Promise<void>;    // Export as Image file
+
+  // ========== Find & Replace ==========
+  find: (searchText: string, options?: FindOptions) => MatchPosition[];
+  replace: (searchText: string, replaceText: string, options?: ReplaceOptions) => number;
+
+  // ========== Document Analysis ==========
+  getOutline: () => OutlineItem[];            // Get document outline
+  getWordCount: () => WordCountResult;        // Get word count statistics
+
+  // ========== Fullscreen Control ==========
+  enterFullscreen: () => Promise<void>;       // Enter fullscreen mode
+  exitFullscreen: () => Promise<void>;        // Exit fullscreen mode
+  isFullscreen: () => boolean;                // Check fullscreen state
 }
 ```
 
@@ -265,20 +356,346 @@ interface EditorConfig {
 }
 ```
 
+### Exported Types
+
+```typescript
+// Core types
+import type {
+  PlateEditorProps,
+  PlateEditorRef,
+  EditorPluginKit,
+  EditorPlugin,
+  PluginKitOptions,
+  PluginKitFactory,
+} from 'kc-plate-editor';
+
+// Toolbar types
+import type {
+  ToolbarConfig,
+  ToolbarFeatureId,
+  ToolbarGroupId,
+  ToolbarPresetName,
+  ToolbarFeature,
+  ToolbarGroup,
+} from 'kc-plate-editor';
+
+// Editor types
+import type {
+  EditorMode,
+  EditorValue,
+  FindOptions,
+  ReplaceOptions,
+  WordCountResult,
+  OutlineItem,
+  MatchPosition,
+} from 'kc-plate-editor';
+
+// Error handling types
+import type {
+  EditorErrorBoundaryProps,
+  ErrorHandlerConfig,
+} from 'kc-plate-editor';
+
+// Config types
+import type {
+  EditorConfig,
+  ConfigProviderProps,
+  I18nProviderProps,
+  Locale,
+  LocaleMessages,
+} from 'kc-plate-editor';
+```
+
+### Exported Utilities
+
+```typescript
+// Plugin utilities
+import {
+  createPluginFactory,
+  mergePluginKits,
+  filterPluginKit,
+  replacePlugin,
+  insertPluginBefore,
+  insertPluginAfter,
+} from 'kc-plate-editor';
+
+// Toolbar utilities
+import {
+  TOOLBAR_FEATURES,
+  getAllFeatures,
+  getFeaturesByGroup,
+  getFeatureById,
+  isFeatureEnabled,
+  getEnabledFeatures,
+  createFullConfig,
+  createMinimalConfig,
+  getToolbarPreset,
+} from 'kc-plate-editor';
+
+// Document utilities
+import {
+  findText,
+  replaceText,
+  getWordCount,
+  getOutline,
+  exportAsHtml,
+  exportAsMarkdown,
+  exportAsPdf,
+  exportAsImage,
+  enterFullscreen,
+  exitFullscreen,
+  isFullscreen,
+} from 'kc-plate-editor';
+
+// Error handling utilities
+import {
+  EditorError,
+  EditorErrorType,
+  handleEditorError,
+  configureErrorHandler,
+  safeExecute,
+  withErrorBoundary,
+  getFriendlyErrorMessage,
+} from 'kc-plate-editor';
+
+// Config generation utilities
+import {
+  generateConfig,
+  generateCode,
+  generateTypeScriptCode,
+  generateJavaScriptCode,
+  generateJSON,
+  getCodeFormatName,
+} from 'kc-plate-editor';
+```
+
 ## Advanced Usage
 
+### Error Handling
+
+Wrap your editor with error boundary for better error handling:
+
+```tsx
+import { PlateEditor, EditorErrorBoundary } from 'kc-plate-editor';
+
+function App() {
+  return (
+    <EditorErrorBoundary>
+      <PlateEditor />
+    </EditorErrorBoundary>
+  );
+}
+
+// Or use HOC
+import { withErrorBoundary } from 'kc-plate-editor';
+
+const SafeEditor = withErrorBoundary(PlateEditor);
+
+function App() {
+  return <SafeEditor />;
+}
+
+// Configure global error handler
+import { configureErrorHandler } from 'kc-plate-editor';
+
+configureErrorHandler({
+  logToConsole: true,
+  onError: (error) => {
+    // Send to error tracking service
+    console.error('Editor error:', error);
+  },
+});
+```
+
+### Find & Replace
+
+```tsx
+import { useRef } from 'react';
+import { PlateEditor } from 'kc-plate-editor';
+import type { PlateEditorRef } from 'kc-plate-editor';
+
+function App() {
+  const editorRef = useRef<PlateEditorRef>(null);
+
+  const handleFind = () => {
+    const matches = editorRef.current?.find('search text', {
+      caseSensitive: false,
+    });
+    console.log(`Found ${matches?.length} matches`);
+  };
+
+  const handleReplace = () => {
+    const count = editorRef.current?.replace(
+      'old text',
+      'new text',
+      { replaceAll: true, caseSensitive: false }
+    );
+    console.log(`Replaced ${count} occurrences`);
+  };
+
+  return (
+    <>
+      <button onClick={handleFind}>Find</button>
+      <button onClick={handleReplace}>Replace All</button>
+      <PlateEditor ref={editorRef} />
+    </>
+  );
+}
+```
+
+### Word Count & Outline
+
+```tsx
+import { useRef, useState } from 'react';
+import { PlateEditor } from 'kc-plate-editor';
+import type { PlateEditorRef, WordCountResult, OutlineItem } from 'kc-plate-editor';
+
+function App() {
+  const editorRef = useRef<PlateEditorRef>(null);
+  const [wordCount, setWordCount] = useState<WordCountResult | null>(null);
+  const [outline, setOutline] = useState<OutlineItem[]>([]);
+
+  const updateStats = () => {
+    const count = editorRef.current?.getWordCount();
+    const outline = editorRef.current?.getOutline();
+    setWordCount(count || null);
+    setOutline(outline || []);
+  };
+
+  return (
+    <>
+      <button onClick={updateStats}>Update Stats</button>
+
+      {wordCount && (
+        <div>
+          <p>Words: {wordCount.words}</p>
+          <p>Characters: {wordCount.charactersWithSpaces}</p>
+          <p>Paragraphs: {wordCount.paragraphs}</p>
+        </div>
+      )}
+
+      {outline.length > 0 && (
+        <nav>
+          <h3>Outline</h3>
+          <ul>
+            {outline.map((item) => (
+              <li key={item.id} style={{ marginLeft: `${item.depth * 20}px` }}>
+                {item.title}
+              </li>
+            ))}
+          </ul>
+        </nav>
+      )}
+
+      <PlateEditor ref={editorRef} />
+    </>
+  );
+}
+```
+
+### Export Functions
+
+```tsx
+import { useRef } from 'react';
+import { PlateEditor } from 'kc-plate-editor';
+import type { PlateEditorRef } from 'kc-plate-editor';
+
+function App() {
+  const editorRef = useRef<PlateEditorRef>(null);
+
+  const handleExport = async (format: 'html' | 'markdown' | 'pdf' | 'image') => {
+    switch (format) {
+      case 'html':
+        await editorRef.current?.exportAsHtml('document.html');
+        break;
+      case 'markdown':
+        await editorRef.current?.exportAsMarkdown('document.md');
+        break;
+      case 'pdf':
+        await editorRef.current?.exportAsPdf('document.pdf');
+        break;
+      case 'image':
+        await editorRef.current?.exportAsImage('document.png');
+        break;
+    }
+  };
+
+  return (
+    <>
+      <button onClick={() => handleExport('html')}>Export HTML</button>
+      <button onClick={() => handleExport('markdown')}>Export Markdown</button>
+      <button onClick={() => handleExport('pdf')}>Export PDF</button>
+      <button onClick={() => handleExport('image')}>Export Image</button>
+      <PlateEditor ref={editorRef} />
+    </>
+  );
+}
+```
+
+### Fullscreen Mode
+
+```tsx
+import { useRef } from 'react';
+import { PlateEditor } from 'kc-plate-editor';
+import type { PlateEditorRef } from 'kc-plate-editor';
+
+function App() {
+  const editorRef = useRef<PlateEditorRef>(null);
+
+  const toggleFullscreen = async () => {
+    if (editorRef.current?.isFullscreen()) {
+      await editorRef.current?.exitFullscreen();
+    } else {
+      await editorRef.current?.enterFullscreen();
+    }
+  };
+
+  return (
+    <>
+      <button onClick={toggleFullscreen}>Toggle Fullscreen</button>
+      <PlateEditor
+        ref={editorRef}
+        onFullscreenChange={(isFullscreen) => {
+          console.log('Fullscreen:', isFullscreen);
+        }}
+      />
+    </>
+  );
+}
+```
+
 ### Custom Plugins
 
 ```tsx
-import { PlateEditor, BaseEditorKit } from 'kc-plate-editor';
+import {
+  PlateEditor,
+  BaseEditorKit,
+  mergePluginKits,
+  filterPluginKit,
+  replacePlugin,
+} from 'kc-plate-editor';
 import { MyCustomPlugin } from './plugins';
 
-const customPlugins = [
-  ...BaseEditorKit,
-  MyCustomPlugin,
-];
-
 function App() {
+  // Merge plugin kits
+  const customPlugins = mergePluginKits(
+    BaseEditorKit,
+    [MyCustomPlugin]
+  );
+
+  // Filter plugins
+  const filteredPlugins = filterPluginKit(
+    BaseEditorKit,
+    (plugin) => plugin.key !== 'unwanted-plugin'
+  );
+
+  // Replace a plugin
+  const updatedPlugins = replacePlugin(
+    BaseEditorKit,
+    'old-plugin',
+    MyCustomPlugin
+  );
+
   return <PlateEditor plugins={customPlugins} />;
 }
 ```

package/dist/components/editor/editor-base-kit.d.ts

@@ -1 +1,7 @@
-export declare const BaseEditorKit: any[];
+import { EditorPluginKit } from '../../types/plugin-types';
+/**
+ * 基础编辑器插件集合
+ * 仅包含核心功能插件，不包含 UI 组件
+ * 适用于静态渲染、服务端渲染或自定义 UI 场景
+ */
+export declare const BaseEditorKit: EditorPluginKit;

package/dist/components/editor/editor-kit.d.ts

@@ -1,5 +1,17 @@
 import { Value } from 'platejs';
 import { TPlateEditor } from 'platejs/react';
-export declare const EditorKit: any[];
+import { EditorPluginKit } from '../../types/plugin-types';
+/**
+ * 完整的编辑器插件集合
+ * 包含所有功能插件，适用于全功能编辑器
+ */
+export declare const EditorKit: EditorPluginKit;
+/**
+ * 编辑器实例类型
+ */
 export type MyEditor = TPlateEditor<Value, (typeof EditorKit)[number]>;
+/**
+ * 获取编辑器实例的 Hook
+ * @returns 编辑器实例
+ */
 export declare const useEditor: () => MyEditor;