@haklex/rich-editor 0.0.65 → 0.0.66

package/README.md

@@ -1,334 +1,141 @@
 # @haklex/rich-editor
 
-基于 [Lexical](https://lexical.dev/) 的富文本编辑器核心包。  
-负责 `编辑态` 运行时、节点注册、插件装配、Markdown 快捷键与主题系统。
+Core rich text editor based on Lexical. Provides the `RichEditor` component, all builtin and custom nodes, built-in plugins, and editor contexts.
 
-## 包定位
-
-- `@haklex/rich-editor`：编辑器核心（`RichEditor`）
-- `@haklex/rich-static-renderer`：只读渲染引擎（`RichRenderer`）
-- `@haklex/rich-renderers`：静态增强渲染器聚合（codeblock、image、video、mermaid...）
-- `@haklex/rich-renderers-edit`：编辑增强渲染器与扩展插件聚合
-- `@haklex/rich-kit-shiro`：一站式生产组合（编辑 + 渲染 + 常用扩展）
-
-## 安装
+## Installation
 
 ```bash
 pnpm add @haklex/rich-editor lexical @lexical/react react react-dom
 ```
 
-可选依赖（按功能开启）：
-
-- `katex`：数学公式渲染
-- `shiki`：代码高亮
-
-## 快速开始
+## Peer Dependencies
+
+| Package | Version | Required |
+| --- | --- | --- |
+| `@base-ui/react` | `^1.1.0` | Yes |
+| `@lexical/code` | `^0.41.0` | Yes |
+| `@lexical/extension` | `^0.41.0` | Yes |
+| `@lexical/link` | `^0.41.0` | Yes |
+| `@lexical/list` | `^0.41.0` | Yes |
+| `@lexical/markdown` | `^0.41.0` | Yes |
+| `@lexical/react` | `^0.41.0` | Yes |
+| `@lexical/rich-text` | `^0.41.0` | Yes |
+| `@lexical/table` | `^0.41.0` | Yes |
+| `lexical` | `^0.41.0` | Yes |
+| `lucide-react` | `^0.574.0` | Yes |
+| `react` | `>=19` | Yes |
+| `react-dom` | `>=19` | Yes |
+| `katex` | `>=0.16.0` | Optional |
+| `shiki` | `^3.0.0` | Optional |
+
+## Usage
 
 ```tsx
 import { RichEditor } from '@haklex/rich-editor'
-import type { SerializedEditorState } from 'lexical'
-import { useState } from 'react'
 import '@haklex/rich-editor/style.css'
 
-export function DemoEditor() {
-  const [value, setValue] = useState<SerializedEditorState | undefined>()
-
-  return (
-    <RichEditor
-      initialValue={value}
-      onChange={setValue}
-      variant="article"
-      theme="light"
-      placeholder="Write something..."
-      onSubmit={() => {
-        // Cmd/Ctrl + Enter
-      }}
-    />
-  )
-}
+<RichEditor
+  variant="article"
+  initialValue={savedState}
+  onChange={(value) => save(value)}
+/>
 ```
 
-如果要渲染只读内容：
+For read-only rendering, use `@haklex/rich-static-renderer` instead.
 
-```tsx
-import { RichRenderer } from '@haklex/rich-static-renderer'
+## Exports
 
-<RichRenderer value={value} />
-```
-
-## 数据格式
-
-`onChange` 返回的是 `SerializedEditorState`（Lexical JSON），推荐直接落库。  
-`initialValue` 直接喂回这个 JSON，可以做到无损回显。
+### Components
 
-## 导出入口
-
-| 入口 | 说明 |
+| Export | Description |
 | --- | --- |
-| `@haklex/rich-editor` | 完整导出（组件、节点、插件命令、上下文、类型） |
-| `@haklex/rich-editor/editor` | 轻入口：`RichEditor` + 节点配置 |
-| `@haklex/rich-editor/static` | 渲染/SSR 相关静态工具（供 `@haklex/rich-static-renderer` 与扩展包使用） |
-| `@haklex/rich-editor/styles` | 仅样式变量/variant class 导出（不含 Lexical theme 对象） |
-| `@haklex/rich-editor/style.css` | 打包后的编辑器样式 |
-
-## RichEditor API
-
-```ts
-type RichEditorVariant = 'article' | 'comment' | 'note'
-
-interface RichEditorProps {
-  initialValue?: SerializedEditorState
-  onChange?: (value: SerializedEditorState) => void
-  variant?: RichEditorVariant
-  theme?: 'light' | 'dark'
-  placeholder?: string
-  onSubmit?: () => void
-  autoFocus?: boolean
-  className?: string
-  contentClassName?: string
-  style?: React.CSSProperties
-  actions?: ReactNode
-  onEditorReady?: (editor: LexicalEditor | null) => void
-  extraNodes?: Array<Klass<LexicalNode>>
-  rendererConfig?: RendererConfig
-  imageUpload?: ImageUploadFn
-  debounceMs?: number
-  children?: ReactNode
-}
-```
-
-关键字段说明：
-
-- `extraNodes`：注册你自己的 Lexical 节点（扩展节点必配）
-- `rendererConfig`：覆写默认渲染器（如 Image/CodeBlock/LinkCard）
-- `actions`：插在编辑器底部 actions 区域（常用于 Slash 菜单）
-- `children`：插件插槽（如 `EmbedPlugin`、`TldrawPlugin`）
-- `imageUpload`：替换默认图片上传逻辑
-- `debounceMs`：`onChange` 的防抖间隔（毫秒）
-
-## RendererConfig API
-
-```ts
-interface RendererConfig {
-  Alert?: ComponentType<AlertRendererProps>
-  Banner?: ComponentType<BannerRendererProps>
-  CodeBlock?: ComponentType<CodeBlockRendererProps>
-  CodeSnippet?: ComponentType<CodeSnippetRendererProps>
-  Footnote?: ComponentType<FootnoteRendererProps>
-  FootnoteSection?: ComponentType<FootnoteSectionRendererProps>
-  Gallery?: ComponentType<GalleryRendererProps>
-  Image?: ComponentType<ImageRendererProps>
-  KaTeX?: ComponentType<KaTeXRendererProps>
-  LinkCard?: ComponentType<LinkCardRendererProps>
-  Mermaid?: ComponentType<MermaidRendererProps>
-  Mention?: ComponentType<MentionRendererProps>
-  Video?: ComponentType<VideoRendererProps>
-}
-```
-
-示例：覆写图片与代码块渲染器
-
-```tsx
-import type { RendererConfig } from '@haklex/rich-editor'
-
-const rendererConfig: RendererConfig = {
-  Image: MyImageRenderer,
-  CodeBlock: MyCodeBlockRenderer,
-}
-
-<RichEditor rendererConfig={rendererConfig} />
-```
-
-## 内置节点与插件
-
-默认内置节点（`config.ts` / `config-edit.ts`）：
-
-- 内置 Lexical 节点：Heading、Quote、List、Link、Table、Code、HorizontalRule...
-- 自定义节点：Spoiler、Mention、KaTeXInline、KaTeXBlock、Image、Alert、CodeBlock、Footnote、FootnoteSection、Video、LinkCard、Details、Grid、Banner、Mermaid
-
-`RichEditor` 默认挂载插件：
-
-- 历史/列表/链接/表格：`HistoryPlugin`、`ListPlugin`、`LinkPlugin`、`TablePlugin`
-- 编辑增强：`MarkdownShortcutsPlugin`、`CheckListPlugin`、`AutoLinkPlugin`
-- 内容能力：`ImagePlugin`、`ImageUploadPlugin`、`KaTeXPlugin`、`AlertPlugin`、`MermaidPlugin`、`HorizontalRulePlugin`
-- 生命周期：`OnChangePlugin`、`EditorRefPlugin`、`SubmitShortcutPlugin`（Cmd/Ctrl+Enter）、`AutoFocusPlugin`
-
-## 常用命令导出
-
-```ts
-INSERT_ALERT_COMMAND
-INSERT_IMAGE_COMMAND
-OPEN_IMAGE_UPLOAD_DIALOG_COMMAND
-INSERT_KATEX_INLINE_COMMAND
-INSERT_KATEX_BLOCK_COMMAND
-INSERT_MERMAID_COMMAND
-```
-
-可在自定义插件中 `editor.dispatchCommand(...)` 触发。
-
-## Markdown Transformer
-
-导出：`ALL_TRANSFORMERS`（`src/transformers`）
-
-覆盖能力包括：
-
-- Inline：Spoiler、Mention、Footnote、`++underline++`、上/下标、KaTeX inline
-- Block：FootnoteSection、Container(Banner/Details)、Git Alert、KaTeX block、Image/Video/CodeBlock/LinkCard/Mermaid/Grid/Table/HR + Lexical 默认 transformers
-
-参考：`docs/export-format-summary.md`
-
-## 设计模式
-
-### 1) Static / Edit 节点分离
+| `RichEditor` | Main editor component |
+| `ColorSchemeProvider` | Context provider for light/dark theme |
+| `FootnoteDefinitionsProvider` | Context provider for footnote definitions |
+| `NestedContentRendererProvider` | Context provider for nested content rendering |
 
-对“编辑态很重”的节点采用双类拆分：
+### Node Registries
 
-- 静态节点：用于只读渲染，依赖轻
-- 编辑节点：继承静态节点，覆盖 `decorate()` 挂重 UI（Popover、Dialog、Nested editor 等）
-
-典型：`AlertQuoteNode` / `AlertQuoteEditNode`、`CodeBlockNode` / `CodeBlockEditNode`。
-
-### 2) RendererWrapper 注入模式
-
-节点内部通过 `createRendererDecoration(...)` 把渲染职责交给 `RendererConfig`，实现：
-
-- 默认渲染器可直接用
-- 业务侧可按 key 定向覆写
-- 保持节点协议不变
-
-### 3) Command + Plugin 模式
-
-扩展插入动作统一走 `createCommand` + `registerCommand`，避免 UI 与文档结构硬耦合。
-
-## 扩展编写与接入
-
-下面是可直接复用的扩展落地流程。
-
-### 步骤 1：定义 Node（静态）
-
-```tsx
-import type {
-  EditorConfig,
-  LexicalEditor,
-  LexicalNode,
-  NodeKey,
-  SerializedLexicalNode,
-  Spread,
-} from 'lexical'
-import { DecoratorNode } from 'lexical'
-import type { ReactElement } from 'react'
-import { createElement } from 'react'
-
-import { PollRenderer } from './PollRenderer'
-
-type SerializedPollNode = Spread<
-  { question: string },
-  SerializedLexicalNode
->
-
-export class PollNode extends DecoratorNode<ReactElement> {
-  __question: string
-
-  static getType() {
-    return 'poll'
-  }
-
-  static clone(node: PollNode) {
-    return new PollNode(node.__question, node.__key)
-  }
-
-  constructor(question: string, key?: NodeKey) {
-    super(key)
-    this.__question = question
-  }
-
-  createDOM(_config: EditorConfig) {
-    const el = document.createElement('div')
-    el.className = 'rich-poll-wrapper'
-    return el
-  }
-
-  updateDOM() {
-    return false
-  }
-
-  isInline() {
-    return false
-  }
-
-  static importJSON(json: SerializedPollNode) {
-    return new PollNode(json.question)
-  }
-
-  exportJSON(): SerializedPollNode {
-    return {
-      ...super.exportJSON(),
-      type: 'poll',
-      question: this.__question,
-      version: 1,
-    }
-  }
-
-  decorate(_editor: LexicalEditor, _config: EditorConfig): ReactElement {
-    return createElement(PollRenderer, {
-      question: this.__question,
-    })
-  }
-}
-
-export function $isPollNode(
-  node: LexicalNode | null | undefined,
-): node is PollNode {
-  return node instanceof PollNode
-}
-```
-
-说明：`RendererConfig` 只能覆写预定义 key。  
-像 `Poll` 这种全新节点，一般采用“节点内直接渲染组件”或自定义 context 的方式。
-
-### 步骤 2：可选编辑态 Node
-
-如果编辑态需要重 UI，可以 `class PollEditNode extends PollNode` 并覆写 `decorate()`。
-
-还可以定义 slash 菜单项：
-
-```ts
-static slashMenuItems = [
-  {
-    title: 'Poll',
-    description: 'Insert a poll block',
-    section: 'MEDIA',
-    onSelect: (editor) => { ... },
-  },
-]
-```
+| Export | Description |
+| --- | --- |
+| `allNodes` | All static nodes (builtin + custom) |
+| `builtinNodes` | Lexical builtin nodes only |
+| `customNodes` | Custom static nodes only |
+| `allEditNodes` | All edit-mode nodes (builtin + custom edit) |
+| `customEditNodes` | Custom edit-mode nodes only |
 
-### 步骤 3：注册到编辑器与渲染器
+### Node Classes
 
-```tsx
-import { RichEditor } from '@haklex/rich-editor'
-import { RichRenderer } from '@haklex/rich-static-renderer'
+| Export | Description |
+| --- | --- |
+| `MermaidNode`, `$createMermaidNode`, `$isMermaidNode` | Mermaid diagram node |
+| `RubyNode`, `$createRubyNode`, `$isRubyNode` | Ruby annotation node |
+| `GridContainerNode`, `$createGridContainerNode`, `$isGridContainerNode` | Grid layout container |
+| `FootnoteSectionNode`, `$createFootnoteSectionNode`, `$isFootnoteSectionNode` | Footnote section node |
+| `FootnoteSectionEditNode` | Footnote section edit-mode node |
+| `ImageNode`, `$createImageNode`, `$isImageNode` | Image node |
+| `LinkCardNode`, `$createLinkCardNode`, `$isLinkCardNode` | Link card node |
+| `KaTeXBlockNode`, `$isKaTeXBlockNode` | KaTeX block equation node |
+| `KaTeXInlineNode`, `$isKaTeXInlineNode` | KaTeX inline equation node |
+| `MentionNode`, `$createMentionNode`, `$isMentionNode` | Mention node |
+
+### Plugins
+
+| Export | Description |
+| --- | --- |
+| `AutoLinkPlugin` | Automatic link detection |
+| `BlockExitPlugin` | Exit block nodes with Enter/arrow keys |
+| `HorizontalRulePlugin` | Horizontal rule insertion |
+| `ImagePlugin` | Image node handling |
+| `ImageUploadPlugin` | Image upload dialog and logic |
+| `KaTeXPlugin` | KaTeX equation insertion |
+| `LinkFaviconPlugin` | Favicon resolution for links |
+| `MarkdownShortcutsPlugin` | Markdown syntax shortcuts |
+| `MermaidPlugin` | Mermaid diagram insertion |
+| `FootnotePlugin` | Footnote insertion and management |
+
+### Commands
+
+| Export | Description |
+| --- | --- |
+| `INSERT_ALERT_COMMAND` | Insert an alert/callout block |
+| `INSERT_IMAGE_COMMAND` | Insert an image node |
+| `OPEN_IMAGE_UPLOAD_DIALOG_COMMAND` | Open the image upload dialog |
+| `INSERT_KATEX_BLOCK_COMMAND` | Insert a KaTeX block equation |
+| `INSERT_KATEX_INLINE_COMMAND` | Insert a KaTeX inline equation |
+| `INSERT_MERMAID_COMMAND` | Insert a Mermaid diagram |
 
-<RichEditor extraNodes={[PollEditNode]}>{/* <PollPlugin /> */}</RichEditor>
+### Utilities
 
-<RichRenderer value={value} extraNodes={[PollNode]} />
-```
+| Export | Description |
+| --- | --- |
+| `extractTextContent` | Extract plain text from editor state |
+| `collectCommandItems` | Collect slash menu / toolbar command items |
+| `computeImageMeta` | Compute thumbhash and dimensions for an image |
+| `decodeThumbHash` | Decode a thumbhash string to a data URL |
+| `createRendererDecoration` | Create a renderer decoration for decorator nodes |
+| `getVariantClass` | Get the CSS class for a variant |
+| `defaultImageUpload` | Default image upload implementation |
+| `buildBlockAnchor`, `buildRangeAnchor` | Comment anchor utilities |
+| `ALL_TRANSFORMERS` | All Markdown transformers (inline + block) |
 
-### 步骤 4：插件化插入命令（推荐）
+### Types
 
-```ts
-import { createCommand } from 'lexical'
+`RichEditorProps`, `RichEditorVariant`, `RendererConfig`, `ColorScheme`, `RendererMode`, `ImageUploadFn`, `ImageUploadResult`, `CommandItemConfig`, `SlashMenuItemConfig`, `ToolbarGroup`, `CommandPlacement`, and renderer prop types (`AlertRendererProps`, `ImageRendererProps`, `CodeBlockRendererProps`, etc.).
 
-export const INSERT_POLL_COMMAND = createCommand<{ question: string }>()
-```
+### Sub-path Exports
 
-在插件中注册命令，所有 UI（按钮、slash、快捷键）统一 dispatch 该命令。
+| Import Path | Description |
+| --- | --- |
+| `@haklex/rich-editor` | Full export (components, nodes, plugins, commands, contexts, types) |
+| `@haklex/rich-editor/editor` | Editor-specific entry (RichEditor + node configs) |
+| `@haklex/rich-editor/static` | Static/SSR utilities (for renderer and extension packages) |
+| `@haklex/rich-editor/styles` | Style variables and variant class exports |
+| `@haklex/rich-editor/style.css` | Compiled editor stylesheet |
 
-## 与聚合包配合
+## Part of Haklex
 
-- 只想增强只读渲染：`@haklex/rich-renderers`
-- 要增强编辑态：`@haklex/rich-renderers-edit`
-- 想直接开箱即用：`@haklex/rich-kit-shiro`
+This package is part of the [Haklex](../../README.md) rich editor ecosystem.
 
 ## License