@incremark/react 0.2.6 → 0.3.0

package/README.en.md

@@ -1,15 +1,18 @@
 # @incremark/react
 
-React 18+ integration for Incremark.
+React 18+ integration library for Incremark, providing high-performance streaming Markdown rendering components.
 
 **[🇨🇳 中文](./README.md)** | 🇺🇸 English
 
-## Features
+## Core Advantages
 
-- 📦 **Out of the Box** - Provides `useIncremark` hook and `<Incremark>` component
-- 🎨 **Customizable** - Support for custom render components
-- ⚡ **High Performance** - Leverages React's reconciliation mechanism
-- 🔧 **DevTools** - Built-in developer tools
+- 📦 **Out of the Box** - Provides `IncremarkContent` component and `useIncremark` hook
+- ⚡ **Extreme Performance** - Incremental parsing with O(n) complexity, dual-engine support
+- ⌨️ **Typewriter Effect** - Built-in animation effects (fade-in, typing)
+- 🎨 **Highly Customizable** - Custom components, code blocks, containers
+- 🎯 **Theme System** - Built-in ThemeProvider with light/dark themes
+- 📜 **Auto Scroll** - Built-in AutoScrollContainer component
+- 🔧 **DevTools** - Built-in developer debugging tools
 
 ## Installation
 
@@ -19,20 +22,63 @@ pnpm add @incremark/core @incremark/react
 
 ## Quick Start
 
-**1. Import Styles**
+### Recommended: IncremarkContent Component
 
 ```tsx
+import { useState } from 'react'
+import { IncremarkContent } from '@incremark/react'
 import '@incremark/react/styles.css'
+
+function App() {
+  const [content, setContent] = useState('')
+  const [isFinished, setIsFinished] = useState(false)
+
+  // Handle AI streaming output
+  async function handleStream(stream: ReadableStream) {
+    setContent('')
+    setIsFinished(false)
+    
+    const reader = stream.getReader()
+    const decoder = new TextDecoder()
+    
+    while (true) {
+      const { done, value } = await reader.read()
+      if (done) break
+      setContent(prev => prev + decoder.decode(value))
+    }
+    
+    setIsFinished(true)
+  }
+
+  return (
+    <>
+      <button onClick={() => handleStream(stream)}>Start</button>
+      <IncremarkContent 
+        content={content} 
+        isFinished={isFinished}
+        incremarkOptions={{
+          gfm: true,
+          math: true,
+          containers: true,
+          htmlTree: true
+        }}
+      />
+    </>
+  )
+}
 ```
 
-**2. Use in Your Component**
+### Advanced: useIncremark Hook
 
 ```tsx
 import { useIncremark, Incremark } from '@incremark/react'
 import '@incremark/react/styles.css'
 
 function App() {
-  const { blocks, append, finalize, reset } = useIncremark({ gfm: true })
+  const { blocks, append, finalize, reset } = useIncremark({ 
+    gfm: true,
+    math: true
+  })
 
   async function handleStream(stream: ReadableStream) {
     reset()
@@ -57,64 +103,170 @@ function App() {
 }
 ```
 
-## API
-
-### useIncremark(options)
+## IncremarkContent Component
+
+Declarative all-in-one component, recommended for most scenarios.
+
+### Props
+
+```ts
+interface IncremarkContentProps {
+  // Input (choose one)
+  content?: string                       // Accumulated Markdown string
+  stream?: () => AsyncGenerator<string>  // Async generator function
+
+  // Status
+  isFinished?: boolean                   // Stream finished flag (required for content mode)
+
+  // Configuration
+  incremarkOptions?: {
+    gfm?: boolean              // GFM support
+    math?: boolean             // Math formulas
+    htmlTree?: boolean         // HTML structured parsing
+    containers?: boolean       // ::: container syntax
+    typewriter?: {             // Typewriter effect
+      enabled?: boolean
+      charsPerTick?: number | [number, number]
+      tickInterval?: number
+      effect?: 'none' | 'fade-in' | 'typing'
+      cursor?: string
+    }
+  }
 
-Core hook.
+  // Custom rendering
+  components?: ComponentMap                          // Custom components
+  customContainers?: Record<string, ComponentType>   // Custom containers
+  customCodeBlocks?: Record<string, ComponentType>   // Custom code blocks
+  codeBlockConfigs?: Record<string, CodeBlockConfig>
 
-**Returns:**
+  // Styling
+  showBlockStatus?: boolean    // Show block status border
+  pendingClass?: string        // CSS class for pending blocks
+}
+```
 
-| Property | Type | Description |
-|----------|------|-------------|
-| `markdown` | `string` | Complete Markdown |
-| `blocks` | `Block[]` | All blocks |
-| `completedBlocks` | `Block[]` | Completed blocks |
-| `pendingBlocks` | `Block[]` | Pending blocks |
-| `append` | `Function` | Append content |
-| `finalize` | `Function` | Complete parsing |
-| `reset` | `Function` | Reset state |
-| `render` | `Function` | Render once (reset + append + finalize) |
+### Example: Enable Typewriter Effect
 
-### useDevTools(incremark)
+```tsx
+<IncremarkContent 
+  content={content} 
+  isFinished={isFinished}
+  incremarkOptions={{
+    gfm: true,
+    typewriter: {
+      enabled: true,
+      charsPerTick: [1, 3],
+      tickInterval: 30,
+      effect: 'fade-in'
+    }
+  }}
+/>
+```
 
-Enable DevTools.
+### Example: Custom Components
 
 ```tsx
-const incremark = useIncremark()
-useDevTools(incremark)
+import CustomHeading from './CustomHeading'
+import WarningContainer from './WarningContainer'
+import EchartsCodeBlock from './EchartsCodeBlock'
+
+<IncremarkContent 
+  content={content} 
+  isFinished={isFinished}
+  components={{ heading: CustomHeading }}
+  customContainers={{ warning: WarningContainer }}
+  customCodeBlocks={{ echarts: EchartsCodeBlock }}
+  codeBlockConfigs={{ echarts: { takeOver: true } }}
+/>
 ```
 
-### \<Incremark\>
-
-Render component.
+## Theme System
 
 ```tsx
-<Incremark 
-  blocks={blocks}
-  components={{ heading: MyHeading }}
-/>
+import { ThemeProvider, IncremarkContent } from '@incremark/react'
+
+// Built-in theme
+<ThemeProvider theme="dark">
+  <IncremarkContent content={content} isFinished={isFinished} />
+</ThemeProvider>
+
+// Custom theme
+<ThemeProvider theme={{ color: { brand: { primary: '#8b5cf6' } } }}>
+  <IncremarkContent content={content} isFinished={isFinished} />
+</ThemeProvider>
 ```
 
-## Custom Components
+## Auto Scroll
 
 ```tsx
-import { useIncremark, Incremark } from '@incremark/react'
-import MyCode from './MyCode'
+import { useRef, useState } from 'react'
+import { AutoScrollContainer, IncremarkContent, type AutoScrollContainerRef } from '@incremark/react'
 
 function App() {
-  const { blocks } = useIncremark()
-  
+  const scrollRef = useRef<AutoScrollContainerRef>(null)
+  const [autoScrollEnabled, setAutoScrollEnabled] = useState(true)
+
   return (
-    <Incremark 
-      blocks={blocks} 
-      components={{ code: MyCode }}
-    />
+    <div>
+      <AutoScrollContainer 
+        ref={scrollRef} 
+        enabled={autoScrollEnabled}
+        threshold={50}
+        behavior="smooth"
+      >
+        <IncremarkContent content={content} isFinished={isFinished} />
+      </AutoScrollContainer>
+      
+      <button onClick={() => scrollRef.current?.scrollToBottom()}>
+        Scroll to Bottom
+      </button>
+    </div>
   )
 }
 ```
 
-## Integration with React Query
+## useIncremark API
+
+```ts
+const {
+  // State
+  markdown,           // string - Complete Markdown
+  blocks,             // Block[] - All blocks
+  completedBlocks,    // Block[] - Completed blocks
+  pendingBlocks,      // Block[] - Pending blocks
+  isLoading,          // boolean - Is loading
+  isDisplayComplete,  // boolean - Is display complete
+  
+  // Methods
+  append,             // (chunk: string) => IncrementalUpdate
+  finalize,           // () => IncrementalUpdate
+  reset,              // () => void
+  render,             // (content: string) => IncrementalUpdate
+  
+  // Typewriter controls
+  typewriter: {
+    enabled,          // boolean - Is enabled
+    isProcessing,     // boolean - Is processing
+    skip,             // () => void - Skip animation
+    setOptions        // (options) => void - Update config
+  }
+} = useIncremark(options)
+```
+
+## DevTools
+
+```tsx
+import { useIncremark, useDevTools, Incremark } from '@incremark/react'
+
+function App() {
+  const incremark = useIncremark()
+  useDevTools(incremark)
+
+  return <Incremark blocks={incremark.blocks} />
+}
+```
+
+## React Query Integration
 
 ```tsx
 import { useQuery } from '@tanstack/react-query'
@@ -127,7 +279,7 @@ function StreamingContent() {
     queryKey: ['chat'],
     queryFn: async () => {
       reset()
-      // ... streaming handling
+      // ... streaming logic
       finalize()
       return null
     },
@@ -143,7 +295,24 @@ function StreamingContent() {
 }
 ```
 
+## Math Formula Support
+
+Built-in support, just enable `math: true`:
+
+```tsx
+<IncremarkContent 
+  content={content} 
+  isFinished={isFinished}
+  incremarkOptions={{ math: true }}
+/>
+```
+
+Import KaTeX styles:
+
+```ts
+import 'katex/dist/katex.min.css'
+```
+
 ## License
 
 MIT
-

package/dist/index.d.ts

@@ -1,9 +1,12 @@
 import { ParserOptions, AnimationEffect, TransformerPlugin, ParsedBlock, Root, IncrementalUpdate, IncremarkParser, SourceBlock, TransformerOptions, DisplayBlock, BlockTransformer } from '@incremark/core';
 export { AnimationEffect, BlockTransformer, DisplayBlock, IncrementalUpdate, ParsedBlock, ParserOptions, Root, RootContent, SourceBlock, TransformerOptions, TransformerPlugin, TransformerState, allPlugins, cloneNode, codeBlockPlugin, countChars, createBlockTransformer, createPlugin, defaultPlugins, imagePlugin, mathPlugin, mermaidPlugin, sliceAst, thematicBreakPlugin } from '@incremark/core';
-import React, { ReactNode } from 'react';
+import React$1, { ReactNode, ComponentType } from 'react';
 import { Definition, FootnoteDefinition, RootContent, PhrasingContent } from 'mdast';
 import * as _incremark_devtools from '@incremark/devtools';
 import { DevToolsOptions } from '@incremark/devtools';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { IncremarkLocale } from '@incremark/shared';
+export { IncremarkLocale, en, zhCN } from '@incremark/shared';
 import { DesignTokens } from '@incremark/theme';
 export { DesignTokens, applyTheme, darkTheme, defaultTheme, generateCSSVars, mergeTheme } from '@incremark/theme';
 
@@ -69,7 +72,7 @@ interface DefinitionsProviderProps {
  * }
  * ```
  */
-declare const DefinitionsProvider: React.FC<DefinitionsProviderProps>;
+declare const DefinitionsProvider: React$1.FC<DefinitionsProviderProps>;
 /**
  * useDefinitions Hook
  *
@@ -111,10 +114,9 @@ interface UseIncremarkOptions extends ParserOptions {
     /** 打字机配置，传入即创建 transformer（可通过 enabled 控制是否启用） */
     typewriter?: TypewriterOptions;
 }
-interface BlockWithStableId$1 extends ParsedBlock {
-    stableId: string;
+type RenderableBlock = ParsedBlock & {
     isLastPending?: boolean;
-}
+};
 /** 打字机控制对象 */
 interface TypewriterControls {
     /** 是否启用 */
@@ -175,7 +177,7 @@ declare function useIncremark(options?: UseIncremarkOptions): {
     /** 当前完整的 AST */
     ast: Root;
     /** 用于渲染的 blocks（根据打字机设置自动处理） */
-    blocks: BlockWithStableId$1[];
+    blocks: RenderableBlock[];
     /** 是否正在加载 */
     isLoading: boolean;
     /** 是否已完成（finalize） */
@@ -294,10 +296,50 @@ interface UseBlockTransformerReturn<T = unknown> {
  */
 declare function useBlockTransformer<T = unknown>(sourceBlocks: SourceBlock<T>[], options?: UseBlockTransformerOptions): UseBlockTransformerReturn<T>;
 
-interface BlockWithStableId extends ParsedBlock {
-    stableId: string;
-    isLastPending?: boolean;
+/**
+ * React 国际化 Hook
+ */
+interface UseLocaleReturn {
+    /** 翻译函数 */
+    t: (key: string) => string;
 }
+declare function useLocale(): UseLocaleReturn;
+
+type ComponentMap = Partial<Record<string, ComponentType<{
+    node: any;
+}>>>;
+/**
+ * 代码块配置
+ */
+interface CodeBlockConfig$1 {
+    /** 是否从一开始就接管渲染，而不是等到 completed 状态 */
+    takeOver?: boolean;
+}
+interface IncremarkContentProps {
+    stream?: () => AsyncGenerator<string>;
+    content?: string;
+    components?: ComponentMap;
+    /** 自定义容器组件映射，key 为容器名称（如 'warning', 'info'） */
+    customContainers?: Record<string, ComponentType<{
+        name: string;
+        options?: Record<string, any>;
+        children?: React.ReactNode;
+    }>>;
+    /** 自定义代码块组件映射，key 为代码语言名称（如 'echart', 'mermaid'） */
+    customCodeBlocks?: Record<string, ComponentType<{
+        codeStr: string;
+        lang?: string;
+        completed?: boolean;
+        takeOver?: boolean;
+    }>>;
+    /** 代码块配置映射，key 为代码语言名称 */
+    codeBlockConfigs?: Record<string, CodeBlockConfig$1>;
+    isFinished?: boolean;
+    incremarkOptions?: UseIncremarkOptions;
+    pendingClass?: string;
+    showBlockStatus?: boolean;
+}
+
 /**
  * 代码块配置
  */
@@ -307,22 +349,22 @@ interface CodeBlockConfig {
 }
 interface IncremarkProps {
     /** 要渲染的块列表 */
-    blocks?: BlockWithStableId[];
+    blocks?: RenderableBlock[];
     /** 内容是否完全显示完成（用于控制脚注等需要在内容完全显示后才出现的元素）
      * 如果传入了 incremark，则会自动使用 incremark.isDisplayComplete，此 prop 被忽略 */
     isDisplayComplete?: boolean;
     /** 自定义组件映射 */
-    components?: Partial<Record<string, React.ComponentType<{
+    components?: Partial<Record<string, React$1.ComponentType<{
         node: any;
     }>>>;
     /** 自定义容器组件映射，key 为容器名称（如 'warning', 'info'） */
-    customContainers?: Record<string, React.ComponentType<{
+    customContainers?: Record<string, React$1.ComponentType<{
         name: string;
         options?: Record<string, any>;
-        children?: React.ReactNode;
+        children?: React$1.ReactNode;
     }>>;
     /** 自定义代码块组件映射，key 为代码语言名称（如 'echart', 'mermaid'） */
-    customCodeBlocks?: Record<string, React.ComponentType<{
+    customCodeBlocks?: Record<string, React$1.ComponentType<{
         codeStr: string;
         lang?: string | undefined;
         completed?: boolean | undefined;
@@ -334,6 +376,10 @@ interface IncremarkProps {
     showBlockStatus?: boolean;
     /** 自定义类名 */
     className?: string;
+    /** 待处理块的样式类名 */
+    pendingClass?: string;
+    /** 已完成块的样式类名 */
+    completedClass?: string;
     /** 可选：useIncremark 返回的对象（用于自动提供 context） */
     incremark?: UseIncremarkReturn;
 }
@@ -351,7 +397,26 @@ interface IncremarkProps {
  * }
  * ```
  */
-declare const Incremark: React.FC<IncremarkProps>;
+declare const Incremark: React$1.FC<IncremarkProps>;
+
+/**
+ * IncremarkContent 组件
+ *
+ * 提供开箱即用的 Markdown 渲染体验，自动处理流式内容和普通内容
+ *
+ * @example
+ * ```tsx
+ * // 普通内容
+ * <IncremarkContent content={markdownString} />
+ *
+ * // 流式内容
+ * <IncremarkContent stream={() => streamGenerator()} />
+ *
+ * // 增量更新内容
+ * <IncremarkContent content={partialContent} isFinished={false} />
+ * ```
+ */
+declare const IncremarkContent: React$1.FC<IncremarkContentProps>;
 
 /**
  * 容器节点类型定义
@@ -366,15 +431,15 @@ interface ContainerNode {
 
 interface IncremarkRendererProps {
     node: RootContent | ContainerNode;
-    components?: Partial<Record<string, React.ComponentType<{
+    components?: Partial<Record<string, React$1.ComponentType<{
         node: any;
     }>>>;
-    customContainers?: Record<string, React.ComponentType<{
+    customContainers?: Record<string, React$1.ComponentType<{
         name: string;
         options?: Record<string, any>;
         children?: ReactNode;
     }>>;
-    customCodeBlocks?: Record<string, React.ComponentType<{
+    customCodeBlocks?: Record<string, React$1.ComponentType<{
         codeStr: string;
         lang?: string;
         completed?: boolean;
@@ -388,11 +453,11 @@ interface IncremarkRendererProps {
 /**
  * 渲染单个 AST 节点
  */
-declare const IncremarkRenderer: React.FC<IncremarkRendererProps>;
+declare const IncremarkRenderer: React$1.FC<IncremarkRendererProps>;
 
 interface AutoScrollContainerProps {
     /** 子元素 */
-    children: React.ReactNode;
+    children: React$1.ReactNode;
     /** 是否启用自动滚动 */
     enabled?: boolean;
     /** 触发自动滚动的底部阈值（像素） */
@@ -400,7 +465,7 @@ interface AutoScrollContainerProps {
     /** 滚动行为 */
     behavior?: ScrollBehavior;
     /** 容器样式 */
-    style?: React.CSSProperties;
+    style?: React$1.CSSProperties;
     /** 容器类名 */
     className?: string;
 }
@@ -430,7 +495,7 @@ interface AutoScrollContainerRef {
  * scrollRef.current?.scrollToBottom()
  * ```
  */
-declare const AutoScrollContainer: React.ForwardRefExoticComponent<AutoScrollContainerProps & React.RefAttributes<AutoScrollContainerRef>>;
+declare const AutoScrollContainer: React$1.ForwardRefExoticComponent<AutoScrollContainerProps & React$1.RefAttributes<AutoScrollContainerRef>>;
 
 interface IncremarkInlineProps {
     nodes: PhrasingContent[];
@@ -450,7 +515,7 @@ interface IncremarkInlineProps {
  *
  * 注意：此组件与 Vue 版本保持完全一致的逻辑和结构
  */
-declare const IncremarkInline: React.FC<IncremarkInlineProps>;
+declare const IncremarkInline: React$1.FC<IncremarkInlineProps>;
 
 /**
  * HtmlElementNode 类型定义（与 @incremark/core 中的定义一致）
@@ -474,7 +539,7 @@ interface IncremarkHtmlElementProps {
  *
  * 渲染结构化的 HTML 元素节点
  */
-declare const IncremarkHtmlElement: React.FC<IncremarkHtmlElementProps>;
+declare const IncremarkHtmlElement: React$1.FC<IncremarkHtmlElementProps>;
 
 /**
  * 脚注列表组件
@@ -501,7 +566,7 @@ declare const IncremarkHtmlElement: React.FC<IncremarkHtmlElementProps>;
  * <IncremarkFootnotes />
  * ```
  */
-declare const IncremarkFootnotes: React.FC;
+declare const IncremarkFootnotes: React$1.FC;
 
 /**
  * @file IncremarkContainerProvider - Incremark 容器级 Provider
@@ -533,7 +598,13 @@ interface IncremarkContainerProviderProps {
  * @param props - 组件参数
  * @returns ReactElement
  */
-declare const IncremarkContainerProvider: React.FC<IncremarkContainerProviderProps>;
+declare const IncremarkContainerProvider: React$1.FC<IncremarkContainerProviderProps>;
+
+interface ConfigProviderProps {
+    children: ReactNode;
+    locale?: IncremarkLocale;
+}
+declare function ConfigProvider({ children, locale }: ConfigProviderProps): react_jsx_runtime.JSX.Element;
 
 interface ThemeProviderProps {
     /** 主题配置，可以是：
@@ -565,6 +636,6 @@ interface ThemeProviderProps {
  * </ThemeProvider>
  * ```
  */
-declare const ThemeProvider: React.FC<ThemeProviderProps>;
+declare const ThemeProvider: React$1.FC<ThemeProviderProps>;
 
-export { AutoScrollContainer, type AutoScrollContainerProps, type AutoScrollContainerRef, type DefinitionsContextValue, DefinitionsProvider, type DefinitionsProviderProps, type HtmlElementNode, Incremark, IncremarkContainerProvider, type IncremarkContainerProviderProps, IncremarkFootnotes, IncremarkHtmlElement, type IncremarkHtmlElementProps, IncremarkInline, type IncremarkInlineProps, type IncremarkProps, IncremarkRenderer, type IncremarkRendererProps, ThemeProvider, type ThemeProviderProps, type TypewriterControls, type TypewriterOptions, type UseBlockTransformerOptions, type UseBlockTransformerReturn, type UseDevToolsOptions, type UseIncremarkOptions, type UseIncremarkReturn, useBlockTransformer, useDefinitions, useDevTools, useIncremark };
+export { AutoScrollContainer, type AutoScrollContainerProps, type AutoScrollContainerRef, ConfigProvider, type DefinitionsContextValue, DefinitionsProvider, type DefinitionsProviderProps, type HtmlElementNode, Incremark, IncremarkContainerProvider, type IncremarkContainerProviderProps, IncremarkContent, type IncremarkContentProps, IncremarkFootnotes, IncremarkHtmlElement, type IncremarkHtmlElementProps, IncremarkInline, type IncremarkInlineProps, type IncremarkProps, IncremarkRenderer, type IncremarkRendererProps, ThemeProvider, type ThemeProviderProps, type TypewriterControls, type TypewriterOptions, type UseBlockTransformerOptions, type UseBlockTransformerReturn, type UseDevToolsOptions, type UseIncremarkOptions, type UseIncremarkReturn, type UseLocaleReturn, useBlockTransformer, useDefinitions, useDevTools, useIncremark, useLocale };