kc-plate-editor 0.3.0 → 0.3.2

package/README.md

@@ -20,19 +20,21 @@ A powerful and customizable rich text editor built on [Plate](https://platejs.or
 - 🔧 **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
+- 🔍 **Find & Replace API**: Powerful find and replace API for building custom search functionality
+- 📊 **Word Count**: Real-time word, character, and paragraph counting with Chinese/English mixed text support
 - 📑 **Outline Navigation**: Automatic document outline generation
-- 📤 **Export**: Export to HTML, Markdown, PDF, and Image formats
+- 📤 **Export**: Export to HTML, Markdown, PDF (multi-page support), and Image formats with progress indicators
 - 🖥️ **Fullscreen Mode**: Distraction-free fullscreen editing
+- 🔧 **Extensible Toolbar**: Add custom buttons to the toolbar with `customToolbarButtons` prop
 
 ### 开发体验
 - 🔌 **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
+- 🛡️ **Error Handling**: Unified error handling with error boundaries and detailed error logging
+- 📦 **TypeScript**: Full TypeScript support with comprehensive type definitions and strict type safety
+- 🚀 **Performance**: Optimized rendering with debouncing, max match limits, and efficient algorithms
 - 🔧 **Plugin System**: Flexible plugin architecture with helper utilities
 - ⚡ **Modern Stack**: Built with React 19, Vite, and Tailwind CSS
+- 💾 **Config Persistence**: Automatic configuration persistence to localStorage
 
 ## Installation
 
@@ -93,7 +95,47 @@ const editorConfig = {
 
 function App() {
   return (
-    <ConfigProvider config={editorConfig}>
+    <ConfigProvider
+      config={editorConfig}
+      persistKey="my-editor-config"  // Custom localStorage key
+      enablePersist={true}            // Enable auto-save to localStorage
+    >
+      <PlateEditor />
+    </ConfigProvider>
+  );
+}
+```
+
+### Configuration Persistence
+
+The editor automatically saves configuration to localStorage:
+
+```tsx
+import { PlateEditor, ConfigProvider, useEditorConfig } from 'kc-plate-editor';
+
+function EditorSettings() {
+  const { config, updateConfig, resetConfig } = useEditorConfig();
+
+  return (
+    <div>
+      <h3>Settings</h3>
+      <select
+        value={config.locale}
+        onChange={(e) => updateConfig({ locale: e.target.value as 'zh-CN' | 'en-US' })}
+      >
+        <option value="zh-CN">中文</option>
+        <option value="en-US">English</option>
+      </select>
+
+      <button onClick={resetConfig}>Reset to Default</button>
+    </div>
+  );
+}
+
+function App() {
+  return (
+    <ConfigProvider enablePersist={true}>
+      <EditorSettings />
       <PlateEditor />
     </ConfigProvider>
   );
@@ -109,11 +151,8 @@ import {
   PlateEditor,
   MINIMAL_TOOLBAR,
   BASIC_TOOLBAR,
-  RICH_TEXT_TOOLBAR,
-  MARKDOWN_TOOLBAR,
-  BLOG_TOOLBAR,
   DOCUMENT_TOOLBAR,
-  COMMENT_TOOLBAR,
+  FULL_TOOLBAR,
   getToolbarPreset,
 } from 'kc-plate-editor';
 import type { ToolbarConfig } from 'kc-plate-editor';
@@ -122,26 +161,17 @@ function App() {
   // Use preset configurations
   return (
     <>
-      {/* Minimal editor */}
+      {/* Minimal editor - for simple text input */}
       <PlateEditor toolbarConfig={MINIMAL_TOOLBAR} />
 
-      {/* Basic editor */}
+      {/* Basic editor - for general editing */}
       <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 */}
+      {/* Document editor - for rich documents */}
       <PlateEditor toolbarConfig={DOCUMENT_TOOLBAR} />
 
-      {/* Comment editor */}
-      <PlateEditor toolbarConfig={COMMENT_TOOLBAR} />
+      {/* Full editor - all features */}
+      <PlateEditor toolbarConfig={FULL_TOOLBAR} />
 
       {/* Or use getToolbarPreset */}
       <PlateEditor toolbarConfig={getToolbarPreset('minimal')} />
@@ -182,6 +212,51 @@ Available feature groups:
 - **extraFormat**: Superscript, Subscript, Keyboard
 - **blockOps**: Indent, Outdent, Toggle
 
+### Custom Toolbar Buttons
+
+Extend the editor toolbar with your own custom buttons:
+
+```tsx
+import { useRef } from 'react';
+import { PlateEditor, type PlateEditorRef, type CustomToolbarButtons } from 'kc-plate-editor';
+
+function CustomButton({ editorRef }: { editorRef: React.RefObject<PlateEditorRef> }) {
+  const handleClick = () => {
+    if (!editorRef.current) return;
+
+    // Use editor API
+    const text = editorRef.current.getText();
+    alert(`Editor has ${text.length} characters`);
+  };
+
+  return (
+    <button onClick={handleClick} className="h-8 px-2 hover:bg-muted rounded-md">
+      Custom
+    </button>
+  );
+}
+
+function App() {
+  const editorRef = useRef<PlateEditorRef>(null);
+
+  const customButtons: CustomToolbarButtons = {
+    before: <CustomButton editorRef={editorRef} />,  // Add to toolbar start
+    after: <CustomButton editorRef={editorRef} />,   // Add to toolbar end
+  };
+
+  return (
+    <PlateEditor
+      ref={editorRef}
+      customToolbarButtons={customButtons}
+    />
+  );
+}
+```
+
+**Examples:**
+- 📁 [Custom Find & Replace Example](src/pages/CustomFindReplaceExample.tsx) - Complete example with UI
+- 📖 See the `/examples` route in the playground for more interactive examples
+
 ### Controlled Mode
 
 ```tsx
@@ -197,9 +272,9 @@ function App() {
   ]);
 
   return (
-    <PlateEditor 
-      value={content} 
-      onChange={setContent} 
+    <PlateEditor
+      value={content}
+      onChange={setContent}
     />
   );
 }
@@ -215,6 +290,7 @@ function App() {
 | onChange | (value: Value) => void | - | Content change callback |
 | plugins | EditorPluginKit | - | Custom plugin list |
 | toolbarConfig | ToolbarConfig | - | Toolbar configuration (see below) |
+| customToolbarButtons | CustomToolbarButtons | - | Custom toolbar buttons (see below) |
 | className | string | - | Custom CSS class |
 | disabled | boolean | false | Disable editor |
 | readOnly | boolean | false | Read-only mode |
@@ -222,8 +298,8 @@ function App() {
 | showToolbar | boolean | true | Show/hide toolbar |
 | toolbarSticky | boolean | true | Make toolbar sticky |
 | mode | 'edit' \| 'view' \| 'suggestion' | 'edit' | Editor mode |
+| showSettings | boolean | true | Show/hide settings button |
 | onModifiedChange | (isModified: boolean) => void | - | Modified state callback |
-| onFullscreenChange | (isFullscreen: boolean) => void | - | Fullscreen state callback |
 
 ### ToolbarConfig
 
@@ -243,18 +319,36 @@ interface ToolbarConfig {
 }
 ```
 
+### CustomToolbarButtons
+
+```typescript
+interface CustomToolbarButtons {
+  before?: React.ReactNode;  // Buttons to insert at the start of the toolbar
+  after?: React.ReactNode;   // Buttons to insert at the end of the toolbar
+}
+```
+
+**Example:**
+
+```tsx
+const customButtons: CustomToolbarButtons = {
+  before: <MyCustomButton />,  // Appears at the start
+  after: <AnotherButton />,    // Appears at the end
+};
+
+<PlateEditor customToolbarButtons={customButtons} />
+```
+
+See [Custom Toolbar Buttons](#custom-toolbar-buttons) section for complete examples.
+
 **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 |
+| `FULL_TOOLBAR` | All features enabled | Full-featured editor with all capabilities |
+| `BASIC_TOOLBAR` | Common text editing features | General purpose editing and content creation |
+| `MINIMAL_TOOLBAR` | Minimal feature set | Simple text input, comments, and notes |
+| `DOCUMENT_TOOLBAR` | Rich document features | Professional documents and formal writing |
 
 **Examples:**
 
@@ -354,6 +448,20 @@ interface EditorConfig {
   authorization?: string;     // Authorization header
   baseURL?: string;           // Base URL for API calls
 }
+
+interface ConfigProviderProps {
+  children: ReactNode;
+  config?: EditorConfig;
+  persistKey?: string;        // localStorage key for persistence (default: 'kc-plate-editor-config')
+  enablePersist?: boolean;    // Enable config persistence (default: true)
+}
+
+// Config context methods
+interface ConfigContextType {
+  config: EditorConfig;
+  updateConfig: (newConfig: Partial<EditorConfig>) => void;  // Update config
+  resetConfig: () => void;                                    // Reset to default
+}
 ```
 
 ### Exported Types
@@ -507,12 +615,34 @@ configureErrorHandler({
 });
 ```
 
-### Find & Replace
+### Find & Replace API
+
+The editor provides powerful find and replace APIs that you can use to build custom search functionality.
+
+**Core APIs:**
+
+```tsx
+// Find text and return match positions
+const matches = editorRef.current?.find('search text', {
+  caseSensitive: false,  // Optional: case-sensitive search (default: false)
+});
+
+// Replace text and return replacement count
+const count = editorRef.current?.replace(
+  'old text',
+  'new text',
+  {
+    replaceAll: true,      // Optional: replace all matches (default: false)
+    caseSensitive: false,  // Optional: case-sensitive search (default: false)
+  }
+);
+```
+
+**Basic Example:**
 
 ```tsx
 import { useRef } from 'react';
-import { PlateEditor } from 'kc-plate-editor';
-import type { PlateEditorRef } from 'kc-plate-editor';
+import { PlateEditor, type PlateEditorRef } from 'kc-plate-editor';
 
 function App() {
   const editorRef = useRef<PlateEditorRef>(null);
@@ -543,6 +673,38 @@ function App() {
 }
 ```
 
+**Custom Find & Replace UI Example:**
+
+For a complete example of building a custom find & replace UI with match highlighting, navigation, and more, see:
+- 📁 [Custom Find Replace Example](src/pages/CustomFindReplaceExample.tsx)
+- 🎮 Run the playground (`pnpm dev`) and visit the examples page
+
+**API Reference:**
+
+| Method | Parameters | Returns | Description |
+|--------|-----------|---------|-------------|
+| `find()` | `searchText: string`<br/>`options?: FindOptions` | `MatchPosition[]` | Find all matches in the editor |
+| `replace()` | `searchText: string`<br/>`replaceText: string`<br/>`options?: ReplaceOptions` | `number` | Replace text and return count |
+
+**Types:**
+
+```typescript
+interface FindOptions {
+  caseSensitive?: boolean;  // Default: false
+}
+
+interface ReplaceOptions {
+  caseSensitive?: boolean;  // Default: false
+  replaceAll?: boolean;     // Default: false
+}
+
+interface MatchPosition {
+  path: number[];  // Node path in the editor
+  offset: number;  // Character offset
+  length: number;  // Match length
+}
+```
+
 ### Word Count & Outline
 
 ```tsx
@@ -595,6 +757,36 @@ function App() {
 
 ### Export Functions
 
+The editor provides comprehensive export functionality with the following improvements:
+
+**HTML Export:**
+- ✅ Complete styling with Tailwind CSS and KaTeX
+- ✅ Embedded fonts (Inter, JetBrains Mono)
+- ✅ Responsive design
+- ✅ Error handling with user feedback
+
+**PDF Export:**
+- ✅ **Multi-page support**: Automatically splits long documents into multiple pages
+- ✅ **A4 page size**: Standard A4 format (595 x 842 points)
+- ✅ **Page margins**: 40pt margins on all sides
+- ✅ **High quality**: 2x scale for crisp text and images
+- ✅ **Auto-scaling**: Content automatically scaled to fit page width
+
+**Image Export:**
+- ✅ **High resolution**: 2x scale for better quality
+- ✅ **PNG format**: Lossless compression
+- ✅ **Full content**: Captures entire editor content
+
+**Markdown Export:**
+- ✅ Uses Plate.js native serialization
+- ✅ Preserves formatting and structure
+
+**All exports include:**
+- ⏳ **Loading indicators**: Shows "Exporting..." during export
+- ❌ **Error handling**: Displays error messages if export fails
+- 📝 **Console logging**: Detailed error logs for debugging
+- 🔒 **Type safety**: Full TypeScript support
+
 ```tsx
 import { useRef } from 'react';
 import { PlateEditor } from 'kc-plate-editor';
@@ -604,19 +796,26 @@ 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;
+    try {
+      switch (format) {
+        case 'html':
+          await editorRef.current?.exportAsHtml('document.html');
+          break;
+        case 'markdown':
+          await editorRef.current?.exportAsMarkdown('document.md');
+          break;
+        case 'pdf':
+          // Now supports multi-page PDF export!
+          await editorRef.current?.exportAsPdf('document.pdf');
+          break;
+        case 'image':
+          // High-quality 2x resolution
+          await editorRef.current?.exportAsImage('document.png');
+          break;
+      }
+      console.log(`${format.toUpperCase()} export successful!`);
+    } catch (error) {
+      console.error(`${format.toUpperCase()} export failed:`, error);
     }
   };
 
@@ -624,8 +823,8 @@ function App() {
     <>
       <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>
+      <button onClick={() => handleExport('pdf')}>Export PDF (Multi-page)</button>
+      <button onClick={() => handleExport('image')}>Export Image (2x)</button>
       <PlateEditor ref={editorRef} />
     </>
   );
@@ -792,17 +991,17 @@ Built with [Plate](https://platejs.org/) - a plugin framework for building rich
 
 ### Usage Guides
 
-- 📖 [中文使用手册](./docs/USAGE_GUIDE_CN.md) - 完整的中文使用指南
-- 📖 [English Usage Guide](./docs/USAGE_GUIDE_EN.md) - Complete English usage guide
-- 🔧 [API 实现指南](./docs/API_IMPLEMENTATION_GUIDE.md) - Backend API implementation guide
-- 🔌 [后端 API 文档](./docs/BACKEND_API.md) - Backend API documentation
+- 📖 [使用手册](./docs/使用手册.md) - 完整的使用指南
+- 📦 [发包指南](./docs/发包指南.md) - NPM 发布指南
+- 🔧 [后端接口实现指南](./docs/后端接口实现指南.md) - Backend API implementation guide
+- 🔌 [后端接口描述](./docs/后端接口描述.md) - Backend API documentation
 
 ### Examples
 
 For complete examples, check out:
-- `/examples` - Playground examples with various use cases
-- `FEATURES.md` - Detailed feature documentation
-- `CHANGELOG.md` - Version history and updates
+- Run the playground with `pnpm dev` and explore the examples page
+- Check `src/pages/` directory for example implementations
+- See the documentation in `docs/` directory
 
 ## Support
 

package/dist/components/configurator/CodeDrawer.d.ts

@@ -0,0 +1,10 @@
+type CodeFormat = 'typescript' | 'javascript' | 'json';
+interface CodeDrawerProps {
+    isOpen: boolean;
+    onClose: () => void;
+    code: string;
+    codeFormat: CodeFormat;
+    onCodeFormatChange: (format: CodeFormat) => void;
+}
+export declare function CodeDrawer({ isOpen, onClose, code, codeFormat, onCodeFormatChange, }: CodeDrawerProps): import("react/jsx-runtime").JSX.Element | null;
+export {};

package/dist/components/configurator/ConfiguratorTab.d.ts

@@ -0,0 +1 @@
+export declare function ConfiguratorTab(): import("react/jsx-runtime").JSX.Element;

package/dist/components/configurator/EditorPreview.d.ts

@@ -0,0 +1,9 @@
+import { ToolbarConfig } from '../../types/toolbar-config';
+import { Locale } from '../../locales';
+interface EditorPreviewProps {
+    config: ToolbarConfig;
+    locale: Locale;
+    editorKey: string;
+}
+export declare function EditorPreview({ config, locale, editorKey }: EditorPreviewProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/configurator/ExamplesDrawer.d.ts

@@ -0,0 +1,6 @@
+interface ExamplesDrawerProps {
+    isOpen: boolean;
+    onClose: () => void;
+}
+export declare function ExamplesDrawer({ isOpen, onClose }: ExamplesDrawerProps): import("react/jsx-runtime").JSX.Element | null;
+export {};

package/dist/components/configurator/FeatureSelector.d.ts

@@ -0,0 +1,10 @@
+interface FeatureSelectorProps {
+    selectedFeatures: Set<string>;
+    onToggleFeature: (featureId: string) => void;
+    onToggleGroupFeatures: (groupId: string) => void;
+    onSelectAll: () => void;
+    expandedGroups: Set<string>;
+    onToggleGroup: (groupId: string) => void;
+}
+export declare function FeatureSelector({ selectedFeatures, onToggleFeature, onToggleGroupFeatures, onSelectAll, expandedGroups, onToggleGroup, }: FeatureSelectorProps): import("react/jsx-runtime").JSX.Element;
+export {};

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

@@ -1,9 +1,29 @@
 import { Value } from 'platejs';
 import { TPlateEditor } from 'platejs/react';
 import { EditorPluginKit } from '../../types/plugin-types';
-import { ToolbarConfig } from '../../types/toolbar-config';
+import { ToolbarConfig, ToolbarAlign } from '../../types/toolbar-config';
 import { EditorMode, WordCountResult, OutlineItem, FindOptions, ReplaceOptions, MatchPosition } from '../../types/editor-types';
 import * as React from 'react';
+/**
+ * 自定义工具栏按钮配置
+ */
+export interface CustomToolbarButtons {
+    /** 在工具栏开始位置插入的按钮 */
+    before?: React.ReactNode;
+    /** 在工具栏末尾插入的按钮 */
+    after?: React.ReactNode;
+}
+/**
+ * 工具栏引用接口
+ */
+export interface ToolbarRef {
+    /** 获取工具栏容器元素 */
+    getElement: () => HTMLDivElement | null;
+    /** 设置工具栏可见性 */
+    setVisible: (visible: boolean) => void;
+    /** 获取工具栏可见性 */
+    isVisible: () => boolean;
+}
 /**
  * PlateEditor 组件属性
  */
@@ -30,16 +50,50 @@ export interface PlateEditorProps {
     toolbarSticky?: boolean;
     /** 编辑器模式：'edit' | 'view' | 'suggestion' */
     mode?: EditorMode;
+    /** 是否显示右侧设置按钮，默认 true */
+    showSettings?: boolean;
     /** 修改状态变化回调 */
     onModifiedChange?: (isModified: boolean) => void;
-    /** 全屏状态变化回调 */
-    onFullscreenChange?: (isFullscreen: boolean) => void;
+    /** 自定义工具栏按钮 */
+    customToolbarButtons?: CustomToolbarButtons;
+    /** 工具栏按钮对齐方式：left | center | right，默认 left */
+    toolbarAlign?: ToolbarAlign;
+    /** 工具栏是否占据全宽（不受内容区域宽度限制），默认 false */
+    toolbarFullWidth?: boolean;
+    /** 自定义工具栏的 CSS 类名 */
+    toolbarClassName?: string;
+    /** 自定义工具栏的内联样式对象 */
+    toolbarStyle?: React.CSSProperties;
+    /** 自定义渲染工具栏的函数 */
+    renderToolbar?: (toolbar: React.ReactNode) => React.ReactNode;
+    /** 编辑器内容区域的最大宽度 */
+    contentMaxWidth?: string | number;
+    /** 是否显示目录，默认 false */
+    showToc?: boolean;
+    /** 目录位置，默认 'left' */
+    tocPosition?: import('../../types/editor-types').TocPosition;
+    /** 目录宽度（当位置为 left/right 时），默认 '240px' */
+    tocWidth?: string | number;
+    /** 自定义目录的 CSS 类名 */
+    tocClassName?: string;
+    /** 自定义目录的内联样式对象 */
+    tocStyle?: React.CSSProperties;
+    /** 自定义渲染目录的函数 */
+    renderToc?: (toc: React.ReactNode) => React.ReactNode;
 }
 /**
  * PlateEditor 组件引用接口
  * 提供编辑器的所有操作方法
  */
 export interface PlateEditorRef {
+    /** 获取工具栏实例或引用 */
+    getToolbar: () => ToolbarRef | null;
+    /** 设置工具栏的显示/隐藏状态 */
+    setToolbarVisible: (visible: boolean) => void;
+    /** 获取目录实例或引用 */
+    getToc: () => import('../../types/editor-types').TocRef | null;
+    /** 设置目录的显示/隐藏状态 */
+    setTocVisible: (visible: boolean) => void;
     /** 获取编辑器内容（JSON 格式） */
     getContent: () => Value;
     /** 设置编辑器内容 */
@@ -52,7 +106,7 @@ export interface PlateEditorRef {
     getMarkdown: () => string;
     /** 从 Markdown 加载内容 */
     setMarkdown: (markdown: string) => void;
-    /** 导出为 HTML 格式 */
+    /** 导出为 HTML 文件 */
     getHtml: () => Promise<string>;
     /** 从 HTML 加载内容 */
     setHtml: (html: string) => void;
@@ -98,11 +152,5 @@ export interface PlateEditorRef {
     getOutline: () => OutlineItem[];
     /** 获取字数统计 */
     getWordCount: () => WordCountResult;
-    /** 进入全屏模式 */
-    enterFullscreen: () => Promise<void>;
-    /** 退出全屏模式 */
-    exitFullscreen: () => Promise<void>;
-    /** 检查是否处于全屏模式 */
-    isFullscreen: () => boolean;
 }
 export declare const PlateEditor: React.ForwardRefExoticComponent<PlateEditorProps & React.RefAttributes<PlateEditorRef>>;

package/dist/components/editor/plugins/configurable-toolbar-kit.d.ts

@@ -1,8 +1,24 @@
-import { ToolbarConfig } from '../../../types/toolbar-config';
+import { ToolbarConfig, ToolbarAlign } from '../../../types/toolbar-config';
+import { default as React } from 'react';
 export interface ConfigurableToolbarKitOptions {
     /** 是否显示工具栏，默认 true */
     showToolbar?: boolean;
     /** 工具栏是否吸顶，默认 true */
     toolbarSticky?: boolean;
+    /** 工具栏对齐方式（可选，当前仅预留，不影响渲染） */
+    toolbarAlign?: ToolbarAlign;
+    /** 是否全宽（可选，当前仅预留，不影响渲染） */
+    toolbarFullWidth?: boolean;
+    /** 自定义类名（可选） */
+    toolbarClassName?: string;
+    /** 内联样式（可选） */
+    toolbarStyle?: React.CSSProperties;
+    /** 自定义渲染函数（可选） */
+    renderToolbar?: (toolbar: React.ReactNode) => React.ReactNode;
+    /** 自定义按钮插槽（可选，当前仅预留，不影响渲染） */
+    customButtons?: {
+        before?: React.ReactNode;
+        after?: React.ReactNode;
+    };
 }
 export declare function createConfigurableToolbarKit(config: ToolbarConfig, options?: ConfigurableToolbarKitOptions): any[];

package/dist/components/editor/standalone-toolbar.d.ts

@@ -0,0 +1,52 @@
+import { ToolbarConfig, ToolbarAlign } from '../../types/toolbar-config';
+import { CustomToolbarButtons } from './plate-editor';
+import { EditorPluginKit } from '../../types/plugin-types';
+import * as React from 'react';
+/**
+ * 独立工具栏组件的属性
+ */
+export interface StandaloneToolbarProps {
+    /** 工具栏配置 */
+    config: ToolbarConfig;
+    /** 编辑器实例（可选，如果不提供则创建一个内部实例） */
+    editor?: any;
+    /** 自定义插件列表（可选） */
+    plugins?: EditorPluginKit;
+    /** 是否显示工具栏，默认 true */
+    showToolbar?: boolean;
+    /** 工具栏是否吸顶，默认 true */
+    sticky?: boolean;
+    /** 工具栏按钮对齐方式，默认 left */
+    align?: ToolbarAlign;
+    /** 工具栏是否占据全宽，默认 false */
+    fullWidth?: boolean;
+    /** 自定义工具栏的 CSS 类名 */
+    className?: string;
+    /** 自定义工具栏的内联样式对象 */
+    style?: React.CSSProperties;
+    /** 自定义工具栏按钮 */
+    customButtons?: CustomToolbarButtons;
+}
+/**
+ * 独立工具栏组件
+ * 可以在编辑器组件外部独立使用，提供完整的工具栏功能
+ *
+ * @example
+ * ```tsx
+ * // 基础使用
+ * <StandaloneToolbar config={FULL_TOOLBAR} />
+ *
+ * // 自定义样式和对齐
+ * <StandaloneToolbar
+ *   config={BASIC_TOOLBAR}
+ *   align="center"
+ *   className="my-custom-toolbar"
+ *   style={{ backgroundColor: '#f0f0f0' }}
+ * />
+ *
+ * // 与编辑器实例关联
+ * const editor = usePlateEditor({ plugins: EditorKit });
+ * <StandaloneToolbar config={FULL_TOOLBAR} editor={editor} />
+ * ```
+ */
+export declare const StandaloneToolbar: React.ForwardRefExoticComponent<StandaloneToolbarProps & React.RefAttributes<HTMLDivElement>>;