pd-markdown 1.1.0 → 2.0.1

package/README.md

@@ -1,14 +1,15 @@
 # pd-markdown
 
-一个现代化的 Markdown 解析和渲染工具库，基于 unified/remark 构建，支持 React。
+一个现代化的 Markdown 解析和渲染工具库，基于 unified/remark 构建，专为 React 和现代流式 Web 应用设计。
 
 ## 特性
 
 - 🚀 **高性能解析** - 基于 unified/remark 的 Markdown 解析器
+- ⚡ **流式渲染** - 专为 AI 场景设计的 `StreamMarkdownRenderer` 和 `useStreamMarkdown`
 - 📝 **GFM 支持** - 完整支持 GitHub Flavored Markdown
 - 📋 **Frontmatter** - 支持 YAML frontmatter 解析
 - ⚛️ **React 组件** - 提供开箱即用的 React 渲染组件
-- 🎨 **可定制** - 支持自定义组件和插件
+- 🎨 **可定制** - 支持自定义组件覆盖（Heading, Code, Table 等）
 - 🔗 **自动锚点** - 标题自动生成 slug 锚点
 - 📦 **Tree-shakable** - 支持 ESM，优化打包体积
 
@@ -30,7 +31,7 @@ yarn add pd-markdown
 | 模块路径 | 描述 |
 | --- | --- |
 | `pd-markdown/parser` | Markdown 解析器，将 Markdown 转换为 AST |
-| `pd-markdown/web` | React 组件，用于渲染 Markdown |
+| `pd-markdown/web` | React 组件和 Hooks，用于渲染 Markdown 和处理流式内容 |
 | `pd-markdown/utils` | 工具函数库，提供 AST 操作和字符串处理 |
 
 ## 快速开始
@@ -45,19 +46,37 @@ function App() {
 # Hello World
 
 This is a **markdown** document.
-
-## Features
-
-- GFM support
-- Frontmatter parsing
-- Custom components
 `
 
   return <MarkdownRenderer source={markdown} />
 }
 ```
 
-### 使用预解析的 AST（SSR 优化）
+### 流式渲染 (AI 场景)
+
+```tsx
+import { StreamMarkdownRenderer, useStreamMarkdown } from 'pd-markdown/web'
+
+function AIResponse() {
+  const stream = useStreamMarkdown()
+
+  // 模拟从流中读取数据
+  const onNewChunk = (chunk: string) => {
+    stream.append(chunk)
+    if (isLastChunk) stream.done()
+  }
+
+  return (
+    <StreamMarkdownRenderer 
+      source={stream.source} 
+      isStreaming={stream.isStreaming}
+      showCursor={true}
+    />
+  )
+}
+```
+
+### 使用预解析的 AST (SSR 优化)
 
 ```tsx
 import { createParser } from 'pd-markdown/parser'
@@ -73,19 +92,6 @@ function Page({ ast }) {
 }
 ```
 
-### 使用 Hook
-
-```tsx
-import { useMarkdown, MarkdownRenderer } from 'pd-markdown/web'
-
-function MarkdownPreview({ source }) {
-  const ast = useMarkdown(source)
-  
-  // 可以对 AST 进行自定义处理
-  return <MarkdownRenderer ast={ast} />
-}
-```
-
 ## API 文档
 
 ### pd-markdown/parser
@@ -100,192 +106,68 @@ import { createParser } from 'pd-markdown/parser'
 const parser = createParser({
   gfm: true,           // 启用 GFM 支持（默认 true）
   frontmatter: true,   // 启用 frontmatter 解析（默认 true）
-  plugins: [],         // 自定义插件
 })
 
 const ast = parser.parse('# Hello World')
 ```
 
-#### `definePlugin(config)`
+### pd-markdown/web
 
-定义自定义解析器插件。
+#### `<MarkdownRenderer />`
 
-```ts
-import { definePlugin } from 'pd-markdown/parser'
-
-const myPlugin = definePlugin({
-  name: 'my-plugin',
-  phase: 'after',  // 'before' | 'after'
-  transform: () => (tree, file) => {
-    // 处理 AST
-    console.log(tree)
-  },
-})
-```
+主渲染组件。支持 `source` 字符串或预解析的 `ast`。
 
-### pd-markdown/web
+#### `<StreamMarkdownRenderer />`
 
-#### `<MarkdownRenderer />`
+流式渲染组件，专为实时生成的内容优化。
 
-主渲染组件。
+- `showCursor`: 是否显示打字机光标
+- `enableAnimation`: 是否启用新块淡入动画
+- `isStreaming`: 标记当前流是否仍在进行
 
-```tsx
-interface MarkdownRendererProps {
-  /** Markdown 源字符串（将被解析） */
-  source?: string
-  /** 预解析的 AST（跳过解析，适用于 SSR） */
-  ast?: Root
-  /** 自定义组件覆盖 */
-  components?: Partial<ComponentMap>
-  /** 包装器 CSS 类名 */
-  className?: string
-  /** 包装器内联样式 */
-  style?: CSSProperties
-  /** 解析器选项（仅在使用 source 时生效） */
-  parserOptions?: ParserOptions
-}
+#### `useStreamMarkdown(options?)`
+
+管理流式 Markdown 状态的 Hook。
+
+```ts
+const { source, ast, append, done, reset } = useStreamMarkdown({
+  parseDebounceMs: 30, // 解析防抖，优化超快流速下的性能
+})
 ```
 
-#### 自定义组件
+#### 自定义组件覆盖
 
 ```tsx
 import { MarkdownRenderer, type ComponentMap } from 'pd-markdown/web'
 
 const customComponents: Partial<ComponentMap> = {
   heading: ({ node, children }) => (
-    <h2 className="custom-heading">{children}</h2>
-  ),
-  code: ({ node, children }) => (
-    <pre className="custom-code-block">
-      <code>{children}</code>
-    </pre>
+    <h2 style={{ color: 'blue' }}>{children}</h2>
   ),
 }
 
 function App() {
-  return (
-    <MarkdownRenderer 
-      source={markdown} 
-      components={customComponents}
-    />
-  )
+  return <MarkdownRenderer source={md} components={customComponents} />
 }
 ```
 
-#### 可自定义的组件列表
-
-| 组件名 | 对应节点 |
-| --- | --- |
-| `heading` | 标题 (h1-h6) |
-| `paragraph` | 段落 |
-| `list` | 列表 |
-| `listItem` | 列表项 |
-| `table` | 表格 |
-| `tableRow` | 表格行 |
-| `tableCell` | 表格单元格 |
-| `code` | 代码块 |
-| `inlineCode` | 行内代码 |
-| `link` | 链接 |
-| `image` | 图片 |
-| `blockquote` | 引用块 |
-
 ### pd-markdown/utils
 
-工具函数库，提供 AST 操作和字符串处理功能。
+提供强大的 AST 遍历与处理工具。
 
 ```ts
-import {
-  // AST 遍历
-  traverseAst,
-  findNodes,
-  findNode,
-  // 类型守卫
-  isParent,
-  isLiteral,
-  isNodeType,
-  // 字符串处理
-  slugify,
-  uniqueSlugify,
-  escapeHtml,
-  sanitizeHtml,
-} from 'pd-markdown/utils'
-
-// 查找所有标题节点
-const headings = findNodes(ast, 'heading')
-
-// 生成 slug
-const slug = slugify('Hello World') // 'hello-world'
-```
-
-## 示例
-
-### 博客文章渲染
-
-```tsx
-import { createParser } from 'pd-markdown/parser'
-import { MarkdownRenderer } from 'pd-markdown/web'
-
-const parser = createParser()
-
-function BlogPost({ content }) {
-  const ast = parser.parse(content)
-  
-  return (
-    <article className="prose">
-      <MarkdownRenderer 
-        ast={ast}
-        className="markdown-body"
-      />
-    </article>
-  )
-}
-```
-
-### 代码高亮
-
-```tsx
-import { MarkdownRenderer, type CodeProps } from 'pd-markdown/web'
-import Prism from 'prismjs'
-
-function CodeBlock({ node, children }: CodeProps) {
-  const lang = node.lang || 'text'
-  const highlighted = Prism.highlight(
-    String(children),
-    Prism.languages[lang] || Prism.languages.text,
-    lang
-  )
-  
-  return (
-    <pre className={`language-${lang}`}>
-      <code dangerouslySetInnerHTML={{ __html: highlighted }} />
-    </pre>
-  )
-}
+import { traverseAst, findNodes, slugify } from 'pd-markdown/utils'
 
-function App() {
-  return (
-    <MarkdownRenderer 
-      source={markdown}
-      components={{ code: CodeBlock }}
-    />
-  )
-}
+// 提取所有标题
+const headings = findNodes(ast, 'heading')
 ```
 
 ## 开发
 
 ```bash
-# 安装依赖
 pnpm install
-
-# 构建
 pnpm build
-
-# 运行测试
 pnpm test
-
-# 类型检查
-pnpm typecheck
 ```
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pd-markdown",
-  "version": "1.1.0",
+  "version": "2.0.1",
   "type": "module",
   "description": "A modular markdown parsing and rendering library",
   "exports": {
@@ -36,6 +36,15 @@
   "files": [
     "packages/*/dist"
   ],
+  "scripts": {
+    "build": "pnpm -r run build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "clean": "pnpm -r run clean",
+    "prepublishOnly": "pnpm run build"
+  },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
@@ -82,13 +91,5 @@
     "type": "git",
     "url": "https://github.com/LaoChen1994/pd-markdown"
   },
-  "sideEffects": false,
-  "scripts": {
-    "build": "pnpm -r run build",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage",
-    "typecheck": "tsc --noEmit",
-    "clean": "pnpm -r run clean"
-  }
-}
+  "sideEffects": false
+}

package/packages/parser/README.md

@@ -0,0 +1,120 @@
+# pd-markdown/parser
+
+基于 unified/remark 的 Markdown 解析器，将 Markdown 转换为 AST。
+
+## 安装
+
+```bash
+npm install pd-markdown
+```
+
+## 使用
+
+### 基础解析
+
+```ts
+import { createParser } from 'pd-markdown/parser'
+
+const parser = createParser()
+const ast = parser.parse('# Hello World')
+
+console.log(ast)
+// {
+//   type: 'root',
+//   children: [
+//     { type: 'heading', depth: 1, children: [...] }
+//   ]
+// }
+```
+
+### 解析选项
+
+```ts
+const parser = createParser({
+  gfm: true,           // 启用 GFM 支持（默认 true）
+  frontmatter: true,   // 启用 frontmatter 解析（默认 true）
+})
+```
+
+### Frontmatter 支持
+
+解析 YAML frontmatter：
+
+```ts
+const markdown = `---
+title: My Article
+date: 2024-01-01
+---
+
+# Hello World
+`
+
+const parser = createParser({ frontmatter: true })
+const ast = parser.parse(markdown)
+```
+
+### 自定义插件
+
+```ts
+import { createParser, definePlugin } from 'pd-markdown/parser'
+
+const myPlugin = definePlugin({
+  name: 'my-plugin',
+  phase: 'after',
+  transform: () => (tree, file) => {
+    // 处理 AST
+    console.log('Processing tree:', tree.type)
+  },
+})
+
+const parser = createParser({
+  plugins: [myPlugin],
+})
+```
+
+## API
+
+### `createParser(options?)`
+
+创建解析器实例。
+
+**参数：**
+- `options.gfm` - 启用 GFM 支持（默认 `true`）
+- `options.frontmatter` - 启用 frontmatter 解析（默认 `true`）
+- `options.plugins` - 自定义插件数组
+
+**返回：**
+- `Parser` 实例，包含 `parse(content)` 方法
+
+### `definePlugin(config)`
+
+定义自定义插件。
+
+**参数：**
+- `config.name` - 插件名称
+- `config.phase` - 执行阶段：`'before'` 或 `'after'`
+- `config.transform` - 转换函数
+
+## 导出
+
+```ts
+// 核心函数
+export { createParser, definePlugin }
+
+// 类型
+export type {
+  Parser,
+  ParserOptions,
+  ParserPlugin,
+  PluginConfig,
+  FrontmatterData,
+  FileData,
+}
+
+// 内置转换插件（高级用法）
+export { transformHeading, transformList, transformTable }
+```
+
+## License
+
+MIT

package/packages/utils/README.md

@@ -0,0 +1,130 @@
+# pd-markdown/utils
+
+Markdown 处理工具函数库。
+
+## 安装
+
+```bash
+npm install pd-markdown
+```
+
+## API
+
+### AST 遍历
+
+```ts
+import { traverseAst, traverseAstWithCallbacks } from 'pd-markdown/utils'
+
+// 遍历所有节点
+traverseAst(tree, (node, index, parent) => {
+  console.log(node.type)
+})
+
+// 带回调的遍历
+traverseAstWithCallbacks(tree, {
+  heading: (node) => console.log('Found heading:', node.depth),
+  paragraph: (node) => console.log('Found paragraph'),
+})
+```
+
+### AST 查询
+
+```ts
+import { findNodes, findNode, findNodesBy, findParent } from 'pd-markdown/utils'
+
+// 查找所有指定类型的节点
+const headings = findNodes(tree, 'heading')
+
+// 查找第一个匹配的节点
+const firstHeading = findNode(tree, 'heading')
+
+// 按条件查找
+const h1Headings = findNodesBy(tree, 
+  (node) => node.type === 'heading' && node.depth === 1
+)
+
+// 查找父节点
+const parent = findParent(tree, someNode)
+```
+
+### 类型守卫
+
+```ts
+import { isParent, isLiteral, isNodeType } from 'pd-markdown/utils'
+
+if (isParent(node)) {
+  console.log('Children:', node.children)
+}
+
+if (isLiteral(node)) {
+  console.log('Value:', node.value)
+}
+
+if (isNodeType(node, 'heading')) {
+  console.log('Heading depth:', node.depth)
+}
+```
+
+### Slug 生成
+
+```ts
+import { slugify, uniqueSlugify } from 'pd-markdown/utils'
+
+// 基础 slug 生成
+slugify('Hello World')        // 'hello-world'
+slugify('API 参考')           // 'api-参考'
+slugify('What is React?')     // 'what-is-react'
+
+// 唯一 slug 生成（避免重复）
+const slugs = new Set<string>()
+slug = uniqueSlugify('Hello', slugs)  // 'hello'
+slug = uniqueSlugify('Hello', slugs)  // 'hello-1'
+slug = uniqueSlugify('Hello', slugs)  // 'hello-2'
+```
+
+### HTML 处理
+
+```ts
+import { escapeHtml, sanitizeHtml, stripHtml } from 'pd-markdown/utils'
+
+// 转义 HTML 特殊字符
+escapeHtml('<script>alert("xss")</script>')
+// '&lt;script&gt;alert("xss")&lt;/script&gt;'
+
+// 清理 HTML 标签
+sanitizeHtml('<p>Hello</p>')  // 'Hello'
+
+// 移除 HTML 标签
+stripHtml('<p>Hello <b>World</b></p>')  // 'Hello World'
+```
+
+## 导出
+
+```ts
+// 类型
+export type {
+  MdNode,
+  MdRoot,
+  Parent,
+  Literal,
+  Visitor,
+  PluginOptions,
+  Position,
+  Location,
+}
+
+// AST 操作
+export { traverseAst, traverseAstWithCallbacks }
+export { findNodes, findNode, findNodesBy, findParent }
+
+// 类型守卫
+export { isParent, isLiteral, isNodeType }
+
+// 字符串处理
+export { slugify, uniqueSlugify }
+export { escapeHtml, sanitizeHtml, stripHtml }
+```
+
+## License
+
+MIT

package/packages/web/README.md

@@ -0,0 +1,110 @@
+# pd-markdown/web
+
+React 组件库，用于渲染 Markdown，支持静态渲染和流式输出。
+
+## 安装
+
+```bash
+npm install pd-markdown
+```
+
+**Peer Dependencies：**
+- react >= 18.0.0
+- react-dom >= 18.0.0
+
+## 使用
+
+### 基础渲染
+
+```tsx
+import { MarkdownRenderer } from 'pd-markdown/web'
+
+function App() {
+  const markdown = '# Hello World'
+  return <MarkdownRenderer source={markdown} />
+}
+```
+
+### 流式渲染 (专为 AI 场景优化)
+
+支持实时显示正在生成的 Markdown 内容，带有光标指示器和区块加载动画。
+
+```tsx
+import { StreamMarkdownRenderer, useStreamMarkdown } from 'pd-markdown/web'
+
+function AIConversation() {
+  const stream = useStreamMarkdown()
+
+  // 当收到新的内容块时
+  const onNewData = (chunk: string) => {
+    stream.append(chunk)
+  }
+
+  // 结束流
+  const onDataDone = () => {
+    stream.done()
+  }
+
+  return (
+    <StreamMarkdownRenderer 
+      source={stream.source} 
+      ast={stream.ast} // 使用 hook 提供的预解析 AST 性能更佳
+      isStreaming={stream.isStreaming}
+      showCursor={true}
+    />
+  )
+}
+```
+
+### 自定义组件覆盖
+
+```tsx
+import { MarkdownRenderer, type ComponentMap } from 'pd-markdown/web'
+
+const components: Partial<ComponentMap> = {
+  // 覆盖标题渲染
+  heading: ({ node, children }) => (
+    <h2 className={`heading-level-${node.depth}`}>{children}</h2>
+  ),
+  // 覆盖代码块渲染
+  code: ({ node }) => (
+    <pre><code>{node.value}</code></pre>
+  )
+}
+
+function App() {
+  return <MarkdownRenderer source={md} components={components} />
+}
+```
+
+## API 参考
+
+### 组件
+
+#### `<MarkdownRenderer />`
+用于普通 Markdown 字符串或 AST 的渲染。
+
+#### `<StreamMarkdownRenderer />`
+继承自 `MarkdownRenderer`，增加了对流式状态的支持。
+- `showCursor`: `boolean` - 是否显示闪烁的光标。
+- `enableAnimation`: `boolean` - 是否开启新内容飞入/淡入动画。
+- `isStreaming`: `boolean` - 标记流是否活跃。
+
+### Hooks
+
+#### `useStreamMarkdown(options?)`
+管理流式内容的状态管理 Hook。返回：
+- `source`: 当前累计的所有文本。
+- `ast`: 当前文本对应的 Root 节点。
+- `isStreaming`: 是否正在流式传输中。
+- `isDone`: 是否已完成。
+- `append(chunk)`: 追加新的内容块。
+- `done()`: 标记流已终结。
+- `reset()`: 重置所有状态。
+
+#### `useMarkdown(source, options?)`
+用于手动触发解析并获取 AST 的 Hook。
+
+## License
+
+MIT