remons-render-markdown 1.0.27 → 1.0.28-beta.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "remons-render-markdown",
-  "version": "1.0.27",
+  "version": "1.0.28-beta.10",
   "description": "一个基于 React 的 Markdown 渲染组件，支持 GFM（GitHub Flavored Markdown）、代码高亮、Mermaid 图表、Tabs 渲染等功能。",
   "type": "module",
   "main": "./dist/index.mjs",
@@ -48,16 +48,16 @@
   "devDependencies": {
     "@ant-design/icons": "^6.3.2",
     "@changesets/cli": "^2.27.0",
-    "@types/react": "^18.2.0",
-    "@types/react-dom": "^18.2.0",
+    "@types/react": "^18.3.0",
+    "@types/react-dom": "^18.3.0",
     "@typescript-eslint/eslint-plugin": "^6.0.0",
     "@typescript-eslint/parser": "^6.0.0",
     "@vitejs/plugin-react": "^4.3.0",
     "eslint": "^8.0.0",
     "less": "^4.2.0",
     "prettier": "^3.0.0",
-    "react": "^18.2.0",
-    "react-dom": "^18.2.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
     "terser": "^5.50.0",
     "typescript": "^5.3.0",
     "vite": "^8.0.0",
@@ -67,10 +67,9 @@
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
-    "access": "public" 
+    "access": "public"
   },
   "dependencies": {
-    "@mdit/plugin-alert": "^2.0.0",
     "@mdit/plugin-tab": "^2.0.0",
     "@panzoom/panzoom": "^4.6.2",
     "classnames": "^2.5.1",
@@ -84,6 +83,7 @@
     "markdown-it-task-lists": "^2.1.1",
     "markdown-it-toc-done-right": "^4.2.0",
     "methods-r": "^2.0.0-rc.1",
+    "morphdom": "^2.7.8",
     "viewerjs": "^1.11.9"
   },
   "repository": {

package/readme.md

@@ -21,6 +21,7 @@
 ### 核心功能
 
 - **GFM 支持**: 完整的 GitHub Flavored Markdown 渲染
+- **增量渲染**: 基于 morphdom 的 DOM 差异化更新，适用于流式输出场景
 - **代码高亮**: 基于 highlight.js 的代码语法高亮
 - **Mermaid 图表**: 支持 Mermaid 语法渲染流程图、时序图等
 - **Tab 标签页**: 支持 Tab 标签页语法
@@ -28,6 +29,7 @@
 - **目录锚点**: 自动生成文档目录和锚点链接（自行实现目录渲染）
 - **代码复制**: 一键复制代码块
 - **代码折叠**: 支持代码块折叠展开
+- **深色模式**: 自动适配深色/浅色主题
 
 ## API
 
@@ -40,7 +42,7 @@ npm install remons-render-markdown
 ### 导出内容
 
 ```typescript
-import RenderMarkdown, { markdownFormat, languagesCommon,  initHighlighter } from 'remons-render-markdown';
+import RenderMarkdown, { markdownFormat, languagesCommon,  initHighlighter, useIncrementalRender } from 'remons-render-markdown';
 ```
 
 #### 默认导出
@@ -52,6 +54,8 @@ import RenderMarkdown, { markdownFormat, languagesCommon,  initHighlighter } fro
 - **markdownFormat**: Markdown 解析函数，返回 `{ anchor: AnchorItem[], info: string }`
 - **languagesCommon**: 默认支持的语言包配置（javascript, typescript, css, json, bash, xml, plaintext）
 - **initHighlighter**: 初始化高亮语言包的函数
+- **useIncrementalRender**: 增量渲染 hook，使用 morphdom 进行 DOM 差异化更新，适用于流式输出场景
+- **renderMermaid**: 独立的 Mermaid 图表渲染组件
 
 ### RenderMarkdown 组件 Props
 
@@ -65,6 +69,7 @@ import RenderMarkdown, { markdownFormat, languagesCommon,  initHighlighter } fro
 | editButton | React.ReactNode | ❌ | - | 自定义编辑按钮 |
 | backTopTarget | HTMLElement | ❌ | body | 返回顶部按钮监听的容器 |
 | showDriverGuide | boolean | ❌ | false | 是否显示新手引导 |
+| showToc | boolean | ❌ | false | 是否显示目录（TOC）按钮和侧边栏 |
 
 ### markdownFormat 函数
 
@@ -251,6 +256,62 @@ console.log(x + y);
 }
 ```
 
+### 使用 useIncrementalRender 实现增量渲染
+
+`useIncrementalRender` 适用于流式输出场景（如 AI 对话），通过 morphdom 实现高效的 DOM 差异化更新。
+
+```tsx
+import { useIncrementalRender } from 'remons-render-markdown';
+
+function StreamingContent({ content }) {
+  const { anchors, hasContent, setInnerRef } = useIncrementalRender({
+    content,
+    // 可选：节流时间，默认 16ms
+    throttleMs: 16,
+  });
+
+  return (
+    <div>
+      {hasContent && <div ref={setInnerRef} />}
+      {anchors.length > 0 && (
+        <ul>
+          {anchors.map((item) => (
+            <li key={item.href}>
+              <a href={`#${item.href}`}>{item.title}</a>
+            </li>
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+}
+```
+
+**参数：**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| content | string | ✅ | - | Markdown 内容 |
+| codeType | string | ❌ | - | 代码类型，不传则按 Markdown 渲染 |
+| customRenderers | MarkdownPlugin[] | ❌ | - | 自定义 markdown-it 插件 |
+| throttleMs | number | ❌ | 16 | 节流时间（ms） |
+| onNodeDiscarded | (el: HTMLElement) => void | ❌ | - | 节点被 diff 移除后触发（含被移除子树的子节点），用于清理 React Root 等挂载状态 |
+
+**返回值：**
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| anchors | AnchorItem[] | 文档锚点列表 |
+| hasContent | boolean | 是否有内容 |
+| setInnerRef | (node: HTMLDivElement) => void | 内容容器的 ref 回调 |
+
+**增量渲染与自定义插件（customRenderers）的配合约定：**
+
+1. 插件产出的容器节点（如 `:::badge` / `:::linkCard` / `<plugin-container>`）按"标签 + className"语义匹配，内容位移时不同类型的块不会被错配到旧节点上。
+2. 元素上 JS 后加的 `data-*` 属性（如初始化守卫位 `data-xxx-inited`）在 diff 后会被保留，"只初始化一次"的守卫逻辑不会在增量渲染中被重复触发。
+3. JS 动态插入的额外子节点（如 React 挂载点、收起按钮）默认会被 diff 移除；若需跨增量渲染保留，请给节点设置 `data-md-persist` 属性（见导出常量 `MD_PERSIST_ATTR`）。
+4. 被 diff 移除的节点会触发 `onNodeDiscarded`，请在此卸载挂载在其上的 React Root，避免内存泄漏。
+
 ### 关于语法
 
 #### mermaid 图表
@@ -292,8 +353,6 @@ title: 图表标题
 
 #### Alert 提示框
 
-依赖于 `@mdit/plugin-alert` 插件，参考 [mdit-plugin-alert](https://mdit-plugins.github.io/zh/alert.html) 的文档。
-
 语法示例：
 
 ```markdown