@incremark/react 0.2.7 → 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

@@ -4,6 +4,9 @@ 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';
 
@@ -293,6 +296,15 @@ interface UseBlockTransformerReturn<T = unknown> {
  */
 declare function useBlockTransformer<T = unknown>(sourceBlocks: SourceBlock<T>[], options?: UseBlockTransformerOptions): UseBlockTransformerReturn<T>;
 
+/**
+ * React 国际化 Hook
+ */
+interface UseLocaleReturn {
+    /** 翻译函数 */
+    t: (key: string) => string;
+}
+declare function useLocale(): UseLocaleReturn;
+
 type ComponentMap = Partial<Record<string, ComponentType<{
     node: any;
 }>>>;
@@ -588,6 +600,12 @@ interface 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 {
     /** 主题配置，可以是：
      * - 字符串：'default' | 'dark'
@@ -620,4 +638,4 @@ interface 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, 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, 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 };