pd-markdown 2.0.0 → 2.0.2

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,9 +1,17 @@
 {
   "name": "pd-markdown",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "type": "module",
+  "main": "./packages/web/dist/index.cjs",
+  "module": "./packages/web/dist/index.mjs",
+  "types": "./packages/web/dist/index.d.ts",
   "description": "A modular markdown parsing and rendering library",
   "exports": {
+    ".": {
+      "types": "./packages/web/dist/index.d.ts",
+      "import": "./packages/web/dist/index.mjs",
+      "require": "./packages/web/dist/index.cjs"
+    },
     "./parser": {
       "types": "./packages/parser/dist/index.d.ts",
       "import": "./packages/parser/dist/index.mjs",
@@ -22,6 +30,9 @@
   },
   "typesVersions": {
     "*": {
+      ".": [
+        "./packages/web/dist/index.d.ts"
+      ],
       "parser": [
         "./packages/parser/dist/index.d.ts"
       ],

package/packages/parser/dist/index.d.ts

@@ -1,4 +1,121 @@
-export type { Parser, ParserOptions, ParserPlugin, PluginConfig, FrontmatterData, FileData, } from './types';
-export { createParser, definePlugin } from './processor';
-export { transformHeading, transformList, transformTable } from './plugins';
-//# sourceMappingURL=index.d.ts.map
+import { Root } from 'mdast';
+import { VFile } from 'vfile';
+
+/**
+ * Parser plugin configuration
+ */
+interface ParserPlugin {
+    /** Unique plugin name */
+    name: string;
+    /** When to run: before or after built-in transforms */
+    phase: 'before' | 'after';
+    /** Transform function */
+    transform: (tree: Root, file: VFile) => void;
+}
+/**
+ * Parser options
+ */
+interface ParserOptions {
+    /** Custom plugins to add */
+    plugins?: ParserPlugin[];
+    /** Enable GFM syntax (default: true) */
+    gfm?: boolean;
+    /** Enable frontmatter parsing (default: true) */
+    frontmatter?: boolean;
+}
+/**
+ * Parser instance
+ */
+interface Parser {
+    /** Parse markdown string to AST */
+    parse(content: string): Root;
+}
+/**
+ * Plugin definition helper config
+ */
+interface PluginConfig<T = unknown> {
+    /** Plugin name */
+    name: string;
+    /** When to run */
+    phase: 'before' | 'after';
+    /** Transform function factory */
+    transform: (options?: T) => (tree: Root, file: VFile) => void;
+}
+/**
+ * Frontmatter data extracted from markdown
+ */
+interface FrontmatterData {
+    [key: string]: unknown;
+}
+/**
+ * Extended file data with frontmatter
+ */
+interface FileData {
+    frontmatter?: FrontmatterData;
+}
+
+/**
+ * Create a markdown parser with the specified options
+ *
+ * @param options - Parser configuration options
+ * @returns Parser instance with parse method
+ */
+declare function createParser(options?: ParserOptions): Parser;
+/**
+ * Type-safe helper to define a parser plugin
+ *
+ * @param config - Plugin configuration
+ * @returns Parser plugin
+ */
+declare function definePlugin<T = void>(config: {
+    name: string;
+    phase: 'before' | 'after';
+    transform: (options?: T) => (tree: Root, file: VFile) => void;
+}, options?: T): ParserPlugin;
+
+/**
+ * Transform plugin that adds slug IDs to headings
+ */
+declare function transformHeading(tree: Root): void;
+
+/**
+ * Extended list item with index
+ */
+declare module 'mdast' {
+    interface ListItemData {
+        index?: number;
+    }
+}
+/**
+ * Transform plugin that adds index to list items
+ */
+declare function transformList(tree: Root): void;
+
+/**
+ * Extended table data
+ */
+declare module 'mdast' {
+    interface TableData {
+        /** Header row */
+        header?: TableRow;
+        /** Body rows */
+        body?: TableRow[];
+    }
+    interface TableCellData {
+        /** Whether this cell is in header */
+        isHeader?: boolean;
+        /** Column alignment */
+        align?: 'left' | 'center' | 'right' | null;
+        /** Column index */
+        columnIndex?: number;
+    }
+}
+/**
+ * Transform plugin that enhances table structure
+ * - Separates header and body rows
+ * - Adds alignment and index info to cells
+ */
+declare function transformTable(tree: Root): void;
+
+export { createParser, definePlugin, transformHeading, transformList, transformTable };
+export type { FileData, FrontmatterData, Parser, ParserOptions, ParserPlugin, PluginConfig };

package/packages/utils/dist/index.d.ts

@@ -1,7 +1,144 @@
-export type { MdNode, MdRoot, Parent, Literal, Visitor, PluginOptions, Position, Location, } from './types';
-export { isParent, isLiteral, isNodeType } from './types';
-export { traverseAst, traverseAstWithCallbacks } from './ast/traverse';
-export { findNodes, findNode, findNodesBy, findParent } from './ast/query';
-export { slugify, uniqueSlugify } from './string/slugify';
-export { escapeHtml, sanitizeHtml, stripHtml } from './string/sanitize';
-//# sourceMappingURL=index.d.ts.map
+import { Root, Content, Parent, Literal } from 'mdast';
+export { Literal, Parent } from 'mdast';
+import { Node } from 'unist';
+
+/**
+ * All possible markdown node types
+ */
+type MdNode = Root | Content;
+/**
+ * Root node of markdown AST
+ */
+type MdRoot = Root;
+/**
+ * Visitor function for AST traversal
+ */
+type Visitor<T extends Node = MdNode> = (node: T, index: number | undefined, parent: Parent | undefined) => void | boolean;
+/**
+ * Plugin options base interface
+ */
+interface PluginOptions {
+    [key: string]: unknown;
+}
+/**
+ * Position information in source
+ */
+interface Position {
+    line: number;
+    column: number;
+    offset?: number;
+}
+/**
+ * Location in source
+ */
+interface Location {
+    start: Position;
+    end: Position;
+}
+/**
+ * Type guard to check if node is a parent node
+ */
+declare function isParent(node: Node): node is Parent;
+/**
+ * Type guard to check if node is a literal node
+ */
+declare function isLiteral(node: Node): node is Literal;
+/**
+ * Type guard to check if node has specific type
+ */
+declare function isNodeType<T extends MdNode>(node: Node, type: T['type']): node is T;
+
+/**
+ * Traverse AST in depth-first order
+ *
+ * @param node - Root node to start traversal
+ * @param visitor - Visitor function called for each node
+ *                  Return `false` to skip children of current node
+ *                  Return `true` or `undefined` to continue
+ */
+declare function traverseAst<T extends Node = MdNode>(node: T, visitor: Visitor<T>): void;
+/**
+ * Traverse AST with enter and leave callbacks
+ *
+ * @param node - Root node to start traversal
+ * @param callbacks - Object with optional enter and leave functions
+ */
+declare function traverseAstWithCallbacks<T extends Node = MdNode>(node: T, callbacks: {
+    enter?: Visitor<T>;
+    leave?: Visitor<T>;
+}): void;
+
+/**
+ * Find all nodes of a specific type in the AST
+ *
+ * @param node - Root node to search from
+ * @param type - Node type to find
+ * @returns Array of matching nodes
+ */
+declare function findNodes<T extends Node = MdNode>(node: Node, type: string): T[];
+/**
+ * Find the first node of a specific type in the AST
+ *
+ * @param node - Root node to search from
+ * @param type - Node type to find
+ * @returns The first matching node or undefined
+ */
+declare function findNode<T extends Node = MdNode>(node: Node, type: string): T | undefined;
+/**
+ * Find all nodes matching a predicate
+ *
+ * @param node - Root node to search from
+ * @param predicate - Function to test each node
+ * @returns Array of matching nodes
+ */
+declare function findNodesBy<T extends Node = MdNode>(node: Node, predicate: (node: Node) => boolean): T[];
+/**
+ * Get the parent of a node in the AST
+ * Note: This requires traversing from root, use sparingly
+ *
+ * @param root - Root node of the AST
+ * @param target - Node to find parent of
+ * @returns Parent node or undefined if not found or is root
+ */
+declare function findParent(root: Node, target: Node): Parent | undefined;
+
+/**
+ * Convert text to URL-safe slug
+ *
+ * @param text - Text to slugify
+ * @returns URL-safe slug
+ */
+declare function slugify(text: string): string;
+/**
+ * Generate unique slug with counter suffix for duplicates
+ *
+ * @param text - Text to slugify
+ * @param existingSlugs - Set of existing slugs to check against
+ * @returns Unique slug
+ */
+declare function uniqueSlugify(text: string, existingSlugs: Set<string>): string;
+
+/**
+ * Escape HTML special characters
+ *
+ * @param text - Text to escape
+ * @returns Escaped text safe for HTML insertion
+ */
+declare function escapeHtml(text: string): string;
+/**
+ * Sanitize HTML string by removing dangerous content
+ *
+ * @param html - HTML string to sanitize
+ * @returns Sanitized HTML string
+ */
+declare function sanitizeHtml(html: string): string;
+/**
+ * Strip all HTML tags from a string
+ *
+ * @param html - HTML string to strip
+ * @returns Plain text without HTML tags
+ */
+declare function stripHtml(html: string): string;
+
+export { escapeHtml, findNode, findNodes, findNodesBy, findParent, isLiteral, isNodeType, isParent, sanitizeHtml, slugify, stripHtml, traverseAst, traverseAstWithCallbacks, uniqueSlugify };
+export type { Location, MdNode, MdRoot, PluginOptions, Position, Visitor };