kc-plate-editor 0.5.8 → 0.6.1

package/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+## [0.6.1] - 2026-03-01
+
+### Bug Fixes
+
+- **PDF 导出分页修复**：修复 `exportAsPdf` 在 `image` 模式下多页 PDF 内容重叠的严重 bug。原实现在每页绘制完整图片（pdf-lib 不支持子区域裁切），改为使用 canvas 逐页裁切后分别嵌入，确保每页只显示对应区域的内容。
+
+### Dependencies
+
+- 升级 `platejs` 52.0.17 → 52.3.2
+- 升级 `@platejs/ai` 52.1.0 → 52.3.1
+- 升级 `@platejs/markdown` 52.1.0 → 52.3.1
+
+### Code Quality
+
+- 将 `export.ts`、`copilot-kit.tsx` 中的 `var` 声明统一为 `const`/`let`
+- 移除 `export.ts` 中未使用的 `TNode`、`TPlateEditor` 导入
+- 移除 `copilot-kit.tsx` 中未使用的 `TNode` 导入
+- 清理 `find-replace.ts`、`outline.ts`、`word-count.ts` 中的多余空行
+
+### Testing
+
+- 新增 vitest 测试框架，支持 `pnpm test`、`pnpm test:watch`、`pnpm test:coverage`
+- 新增 10 个测试文件，共 134 个单元测试用例，覆盖以下模块：
+  - `text-utils` - 文本提取与摘要
+  - `validation` - 配置与内容验证（Zod Schema）
+  - `content-converter` - HTML/Markdown/JSON 格式转换与安全处理
+  - `plugin-factory` - 插件工厂与组合
+  - `find-replace` - 查找替换
+  - `toc` - 目录树操作
+  - `constants` - 常量定义
+  - `config-generator` - 代码生成
+  - `word-count` - 字数统计
+  - `export` - 导出逻辑

package/README.md

@@ -8,11 +8,32 @@
 
 | 版本 | 状态 | 说明 |
 |------|------|------|
-| v0.5.8 | ✅ 最新版本 | 内容格式转换优化（官方 API） |
+| v0.6.1 | ✅ 最新版本 | Bug 修复、代码质量、单元测试、依赖升级 |
+| v0.6.0 | ✅ 稳定版本 | 全面升级：AI SDK 6.x、Vite 7.x、依赖更新 |
+| v0.5.8 | ✅ 稳定版本 | 内容格式转换优化（官方 API） |
 | v0.5.6 | ✅ 稳定版本 | 增强上传配置灵活性 |
 | v0.5.5 | ✅ 稳定版本 | 快捷键保存、本地存储、目录跳转优化 |
 | v0.5.0 | ✅ 已发布私服 | 基础稳定版本 |
 
+### v0.6.0 更新内容
+
+- **依赖全面升级** - 更新至最新稳定版本
+  - `ai` 5.0.28 → 6.0.45（重大升级）
+  - `@ai-sdk/react` 2.0.28 → 3.0.47（重大升级）
+  - `vite` 5.4.11 → 7.3.1（重大升级）
+  - `platejs` 52.0.1 → 52.0.17
+  - `@platejs/ai` 52.0.6 → 52.1.0
+  - `@platejs/markdown` 52.0.4 → 52.1.0
+  - `typescript` 5.9.2 → 5.9.3
+  - `tailwindcss` 4.1.13 → 4.1.18
+  - `zod` 4.1.12 → 4.3.5
+  - `zustand` 5.0.8 → 5.0.10
+- **代码精简** - 移除 use-chat.ts 中约 1300 行的测试代码
+- **配置清理** - 移除废弃配置属性（uploadToken, authorization）
+- **类型优化** - 优化插件类型定义，改进 EditorPluginKit 类型
+- **HTTP 工具优化** - 简化请求头合并逻辑，移除兼容代码
+- **导出顺序修复** - 修复 package.json exports 中 types 字段顺序
+
 ### v0.5.8 更新内容
 
 - **内容格式转换** - 基于 Plate.js 官方 API 实现 JSON/HTML/Markdown 互转
@@ -1011,10 +1032,91 @@ src/
 
 ---
 
+## 发布到 npm
+
+### 前置条件
+
+- 已安装 Node.js 18+ 和 pnpm
+- 拥有 npm 账号并具有 `kc-plate-editor` 包的发布权限
+- npm 账号已开启 2FA 时，需准备好身份验证器 App（如 Google Authenticator）
+
+### 发布步骤
+
+```bash
+# 1. 进入项目目录
+cd kc-plate-editor
+
+# 2. 更新版本号（选择 patch/minor/major）
+npm version patch   # 0.6.1 → 0.6.2
+npm version minor   # 0.6.1 → 0.7.0
+npm version major   # 0.6.1 → 1.0.0
+# 或直接编辑 package.json 中的 version 字段
+
+# 3. 验证代码质量（typecheck + lint + test）
+pnpm run typecheck
+pnpm run lint
+pnpm run test
+
+# 4. 构建产物
+pnpm run build
+
+# 5. 登录 npm 官方 registry
+npm login --registry https://registry.npmjs.org/
+# 按提示在浏览器完成登录，回到终端按 Enter 确认
+
+# 6. 发布（开启 2FA 的账号需要 --otp 参数）
+npm publish --registry https://registry.npmjs.org/ --otp=你的6位验证码
+# 从身份验证器 App 获取 OTP 后立即执行（30秒有效期）
+```
+
+### 发布到私有 registry
+
+如果使用 Verdaccio、Nexus 等私有 npm 仓库：
+
+```bash
+# 1. 登录私有 registry
+npm login --registry http://your-private-registry:4873/
+
+# 2. 构建
+pnpm run build
+
+# 3. 发布到私有 registry（私服通常不需要 OTP）
+npm publish --registry http://your-private-registry:4873/
+```
+
+也可以在 `.npmrc` 中配置默认 registry 避免每次指定：
+
+```ini
+# .npmrc
+registry=http://your-private-registry:4873/
+```
+
+### 发布后验证
+
+```bash
+# 查看已发布的版本
+npm view kc-plate-editor versions --registry https://registry.npmjs.org/
+
+# 在其他项目中安装最新版
+pnpm add kc-plate-editor@latest
+```
+
+### 常见问题
+
+| 错误 | 原因 | 解决方式 |
+|------|------|----------|
+| `E403 Two-factor authentication required` | npm 账号开启了 2FA | 添加 `--otp=123456` 参数 |
+| `E401 Unauthorized` | 未登录或 token 过期 | 重新执行 `npm login` |
+| `E403 Forbidden` | 无发布权限 | 检查 npm 账号对该包的权限 |
+| `EPUBLISHCONFLICT` | 版本号已存在 | 更新 `package.json` 中的版本号 |
+
+---
+
 ## 更多资源
 
 - **在线示例** - 运行 `pnpm dev` 后访问 http://localhost:3001
 - **详细文档** - 查看 `docs/` 目录
+- **变更日志** - 查看 `CHANGELOG.md`
 - **Plate.js 文档** - https://platejs.org
 
 ---
@@ -1025,7 +1127,7 @@ src/
 - Plate.js 52
 - TypeScript 5.9
 - Tailwind CSS 4
-- Vite 5
+- Vite 7
 
 ---
 

package/dist/components/editor/hooks/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 编辑器 Hooks 统一导出
+ *
+ * 这些 hooks 将 PlateEditor 组件中的方法逻辑拆分出来，
+ * 提供更好的可复用性和性能（减少不必要的重新创建）
+ */
+export { useContentMethods, useMarkdownMethods, useHtmlMethods, useExportMethods, useFindReplaceMethods, useDocumentAnalysisMethods, useInsertMethods, useHistoryMethods, useEditorControlMethods, } from './use-editor-methods';

package/dist/components/editor/hooks/use-editor-methods.d.ts

@@ -0,0 +1,89 @@
+import { Value } from 'platejs';
+import { TPlateEditor } from 'platejs/react';
+import { HtmlSerializeOptions } from '../../../lib/content-converter';
+import { FindOptions, ReplaceOptions } from '../../../types/editor-types';
+/**
+ * 编辑器方法 Hook
+ * 将 PlateEditor 中的方法逻辑拆分出来，提升性能和可维护性
+ */
+import * as React from 'react';
+/**
+ * 内容管理方法 Hook
+ * 提供 getContent, setContent, resetContent 等方法
+ */
+export declare function useContentMethods(editor: TPlateEditor | null, initialValueRef: React.RefObject<Value>, previousValueRef: React.MutableRefObject<Value>, onChange?: (value: Value) => void): {
+    getContent: () => Value;
+    setContent: (content: Value) => void;
+    resetContent: () => void;
+    getText: () => string;
+    isEmpty: () => boolean;
+};
+/**
+ * Markdown 方法 Hook
+ */
+export declare function useMarkdownMethods(editor: TPlateEditor | null, previousValueRef: React.MutableRefObject<Value>, onChange?: (value: Value) => void): {
+    getMarkdown: () => string;
+    setMarkdown: (markdown: string) => void;
+    insertMarkdown: (markdown: string) => void;
+};
+/**
+ * HTML 方法 Hook
+ */
+export declare function useHtmlMethods(editor: TPlateEditor | null, previousValueRef: React.MutableRefObject<Value>, onChange?: (value: Value) => void): {
+    getHtml: (options?: HtmlSerializeOptions) => Promise<string>;
+    setHtml: (html: string) => void;
+};
+/**
+ * 导出方法 Hook
+ */
+export declare function useExportMethods(editor: TPlateEditor | null): {
+    exportAsHtml: (filename?: string) => Promise<void>;
+    exportAsMarkdown: (filename?: string) => Promise<void>;
+    exportAsPdf: (filename?: string) => Promise<void>;
+    exportAsImage: (filename?: string) => Promise<void>;
+};
+/**
+ * 查找替换方法 Hook
+ */
+export declare function useFindReplaceMethods(editor: TPlateEditor | null): {
+    find: (searchText: string, options?: FindOptions) => import('../../../types/editor-types').MatchPosition[];
+    replace: (searchText: string, replaceText: string, options?: ReplaceOptions) => number;
+};
+/**
+ * 文档分析方法 Hook
+ */
+export declare function useDocumentAnalysisMethods(editor: TPlateEditor | null): {
+    getOutline: () => import('../../../types/editor-types').OutlineItem[];
+    getWordCount: () => import('../../../types/editor-types').WordCountResult;
+};
+/**
+ * 插入方法 Hook
+ */
+export declare function useInsertMethods(editor: TPlateEditor | null): {
+    insertText: (text: string) => void;
+    toggleMark: (mark: string) => void;
+    insertLink: (url: string, text?: string) => void;
+    insertImage: (url: string) => void;
+    insertNodes: (nodes: Value, options?: {
+        at?: number[];
+    }) => void;
+    insertCodeBlock: (code: string, language?: string) => void;
+    insertBlockquote: (text: string) => void;
+};
+/**
+ * 历史操作方法 Hook
+ */
+export declare function useHistoryMethods(editor: TPlateEditor | null): {
+    undo: () => void;
+    redo: () => void;
+    canUndo: () => boolean;
+    canRedo: () => boolean;
+    clearHistory: () => void;
+};
+/**
+ * 编辑器控制方法 Hook
+ */
+export declare function useEditorControlMethods(editor: TPlateEditor | null): {
+    focus: () => void;
+    blur: () => void;
+};

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

@@ -91,6 +91,8 @@ export interface PlateEditorProps {
     onAutoSave?: (content: Value) => void;
     /** 保存回调（用于快捷键保存 Ctrl+S / Cmd+S） */
     onSave?: (content: Value) => void;
+    /** 是否将编辑器状态同步到全局 Store，默认 false */
+    syncToStore?: boolean;
 }
 /**
  * PlateEditor 组件引用接口
@@ -194,5 +196,64 @@ export interface PlateEditorRef {
     restoreAutoSave: () => Value | null;
     /** 清除自动保存数据 */
     clearAutoSave: () => void;
+    /** 获取选中的文本 */
+    getSelectedText: () => string;
+    /** 检查是否有选中内容 */
+    hasSelection: () => boolean;
+    /** 获取当前选区 */
+    getSelection: () => {
+        anchor: {
+            path: number[];
+            offset: number;
+        };
+        focus: {
+            path: number[];
+            offset: number;
+        };
+    } | null;
+    /** 选中所有内容 */
+    selectAll: () => void;
+    /** 取消选中 */
+    deselect: () => void;
+    /** 检查是否可以撤销 */
+    canUndo: () => boolean;
+    /** 检查是否可以重做 */
+    canRedo: () => boolean;
+    /** 清空历史记录 */
+    clearHistory: () => void;
+    /**
+     * 插入节点
+     * @param nodes 要插入的节点数组
+     * @param options 插入选项
+     */
+    insertNodes: (nodes: Value, options?: {
+        at?: number[];
+    }) => void;
+    /**
+     * 插入代码块
+     * @param code 代码内容
+     * @param language 代码语言
+     */
+    insertCodeBlock: (code: string, language?: string) => void;
+    /**
+     * 插入引用块
+     * @param text 引用内容
+     */
+    insertBlockquote: (text: string) => void;
+    /** 滚动到顶部 */
+    scrollToTop: () => void;
+    /** 滚动到底部 */
+    scrollToBottom: () => void;
+    /**
+     * 滚动到指定节点
+     * @param nodeId 节点 ID
+     */
+    scrollToNode: (nodeId: string) => void;
+    /** 获取当前编辑模式 */
+    getMode: () => import('../../types/editor-types').EditorMode;
+    /** 设置编辑模式 */
+    setMode: (mode: import('../../types/editor-types').EditorMode) => void;
+    /** 切换只读状态 */
+    toggleReadOnly: () => void;
 }
 export declare const PlateEditor: React.ForwardRefExoticComponent<PlateEditorProps & React.RefAttributes<PlateEditorRef>>;

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

@@ -1,3 +1,4 @@
+import { EditorPluginKit } from '../../../types/plugin-types';
 export declare const aiChatPlugin: import('platejs/react').PlatePlugin<import('platejs').PluginConfig<"aiChat", {
     chatOptions: {
         api: string;
@@ -95,4 +96,4 @@ export declare const aiChatPlugin: import('platejs/react').PlatePlugin<import('p
         format?: "all" | "none" | "single";
     } | undefined) => void;
 }>, {}>>;
-export declare const AIKit: any[];
+export declare const AIKit: EditorPluginKit;

package/dist/components/editor/plugins/block-menu-kit.d.ts

@@ -39,6 +39,7 @@ export declare const BlockMenuKit: (import('platejs/react').PlatePlugin<import('
     };
     editorPaddingRight?: import('react').CSSProperties["width"];
     enableContextMenu?: boolean;
+    disableSelectAll?: boolean;
     isSelecting?: boolean;
     isSelectionAreaVisible?: boolean;
     rightSelectionAreaClassName?: string;

package/dist/components/editor/plugins/block-placeholder-kit.d.ts

@@ -1,28 +1,2 @@
-export declare const createBlockPlaceholderKit: (locale?: "zh-CN" | "en-US") => import('platejs/react').PlatePlugin<import('platejs').PluginConfig<"blockPlaceholder", {
-    _target: {
-        node: import('platejs').TElement;
-        placeholder: string;
-    } | null;
-    placeholders: Record<string, string>;
-    query: (context: import('platejs/react').PlatePluginContext<import('platejs/react').BlockPlaceholderConfig> & {
-        node: import('platejs').TElement;
-        path: import('platejs').Path;
-    }) => boolean;
-    className?: string;
-}, {}, {}, {
-    placeholder: (node: import('platejs').TElement) => string | undefined;
-}>>[];
-export declare const BlockPlaceholderKit: import('platejs/react').PlatePlugin<import('platejs').PluginConfig<"blockPlaceholder", {
-    _target: {
-        node: import('platejs').TElement;
-        placeholder: string;
-    } | null;
-    placeholders: Record<string, string>;
-    query: (context: import('platejs/react').PlatePluginContext<import('platejs/react').BlockPlaceholderConfig> & {
-        node: import('platejs').TElement;
-        path: import('platejs').Path;
-    }) => boolean;
-    className?: string;
-}, {}, {}, {
-    placeholder: (node: import('platejs').TElement) => string | undefined;
-}>>[];
+export declare const createBlockPlaceholderKit: (locale?: "zh-CN" | "en-US") => any[];
+export declare const BlockPlaceholderKit: any[];

package/dist/components/editor/plugins/block-selection-kit.d.ts

@@ -39,6 +39,7 @@ export declare const BlockSelectionKit: import('platejs/react').PlatePlugin<impo
     };
     editorPaddingRight?: import('react').CSSProperties["width"];
     enableContextMenu?: boolean;
+    disableSelectAll?: boolean;
     isSelecting?: boolean;
     isSelectionAreaVisible?: boolean;
     rightSelectionAreaClassName?: string;

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

@@ -1,4 +1,5 @@
 import { ToolbarConfig, ToolbarAlign } from '../../../types/toolbar-config';
+import { EditorPluginKit } from '../../../types/plugin-types';
 import { default as React } from 'react';
 export interface ConfigurableToolbarKitOptions {
     /** 是否显示工具栏，默认 true */
@@ -20,5 +21,12 @@ export interface ConfigurableToolbarKitOptions {
         before?: React.ReactNode;
         after?: React.ReactNode;
     };
+    /** 是否显示目录切换按钮 */
+    showTocButton?: boolean;
+    /** 目录切换按钮状态引用（使用 ref 避免重新创建 plugins） */
+    tocStateRef?: React.RefObject<{
+        visible: boolean;
+        setVisible: (v: boolean | ((prev: boolean) => boolean)) => void;
+    }>;
 }
-export declare function createConfigurableToolbarKit(config: ToolbarConfig, options?: ConfigurableToolbarKitOptions): any[];
+export declare function createConfigurableToolbarKit(config: ToolbarConfig, options?: ConfigurableToolbarKitOptions): EditorPluginKit;

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

@@ -1,10 +1,50 @@
+import { TElement } from 'platejs';
 import { EditorConfig } from '../../../lib/config-provider';
+import { EditorPluginKit } from '../../../types/plugin-types';
+/**
+ * Copilot 配置选项
+ */
+export interface CopilotOptions {
+    /** API 地址 */
+    apiUrl?: string;
+    /** 自定义请求头 */
+    headers?: Record<string, string>;
+    /** 系统提示词 */
+    systemPrompt?: string;
+    /** 防抖延迟（毫秒），默认 500 */
+    debounceDelay?: number;
+    /** 是否在错误时使用随机文本填充，默认 true */
+    useFallbackOnError?: boolean;
+    /** 自定义提示生成函数 */
+    getPrompt?: (context: {
+        editor: unknown;
+        contextEntry: [TElement, number[]] | null;
+    }) => string;
+    /** 自定义补全结果处理函数 */
+    onComplete?: (completion: string) => string;
+    /** 快捷键配置 */
+    shortcuts?: {
+        accept?: string;
+        acceptNextWord?: string;
+        reject?: string;
+        triggerSuggestion?: string;
+    };
+    /** 是否启用，默认 true */
+    enabled?: boolean;
+}
+/** 导出系统提示词供外部使用 */
+export declare const COPILOT_SYSTEM_PROMPT = "You are an advanced AI writing assistant, similar to VSCode Copilot but for general text. Your task is to predict and generate the next part of the text based on the given context.\n\nRules:\n- Continue the text naturally up to the next punctuation mark (., ,, ;, :, ?, or !).\n- Maintain style and tone. Don't repeat given text.\n- For unclear context, provide the most likely continuation.\n- Handle code snippets, lists, or structured text if needed.\n- Don't include \"\"\" in your response.\n- CRITICAL: Always end with a punctuation mark.\n- CRITICAL: Avoid starting a new block. Do not use block formatting like >, #, 1., 2., -, etc. The suggestion should continue in the same block as the context.\n- If no context is provided or you can't generate a continuation, return \"0\" without explanation.";
 /**
  * 创建 Copilot 插件配置
  * @param editorConfig 编辑器配置（可选，用于自定义 API 地址和请求头）
+ * @param options Copilot 特定配置选项
  */
-export declare function createCopilotKit(editorConfig?: EditorConfig): any[];
+export declare function createCopilotKit(editorConfig?: EditorConfig, options?: CopilotOptions): EditorPluginKit;
 /**
  * 默认 Copilot 插件（使用默认配置）
  */
-export declare const CopilotKit: any[];
+export declare const CopilotKit: EditorPluginKit;
+/**
+ * 创建禁用的 Copilot Kit（仅包含 Markdown 支持）
+ */
+export declare const DisabledCopilotKit: EditorPluginKit;

package/dist/components/editor/plugins/exit-break-kit.d.ts

@@ -1,4 +1 @@
-export declare const ExitBreakKit: import('platejs').SlatePlugin<import('platejs').PluginConfig<"exitBreak", {}, {}, Record<"exitBreak", {
-    insert: (options: Omit<import('platejs').InsertExitBreakOptions, "reverse">) => true | undefined;
-    insertBefore: (options: Omit<import('platejs').InsertExitBreakOptions, "reverse">) => true | undefined;
-}>, {}>>[];
+export declare const ExitBreakKit: any[];