ds-markdown 0.1.1 → 0.1.2-beta.0

package/README.en.md

@@ -20,39 +20,30 @@ A React component designed specifically for modern AI applications, providing sm
 
 ## ✨ Core Features
 
-### 🎯 **Perfect Replication**
+### 🤖 **AI Conversation Scenarios**
 
 - 1:1 recreation of [DeepSeek website](https://chat.deepseek.com/) chat response effects
 - Support for both thinking process (`thinking`) and answer content (`answer`) modes
-- Native Markdown syntax support, including code highlighting, tables, lists, etc.
-- Light/dark theme support, perfectly adapting to different scenarios
+- Perfect adaptation to streaming data with zero-delay response to user input
 
-### ⚡ **Ultimate Performance**
+### 📊 **Content Display Scenarios**
 
-- Smart batch processing, zero lag rendering for large documents
-- Dual timer modes: `requestAnimationFrame` + `setTimeout`
-- Built-in streaming syntax buffering, avoiding incomplete Markdown rendering errors
+- Complete Markdown syntax support, including code highlighting, tables, lists, etc.
+- Mathematical formula rendering (KaTeX), supporting `$...$` and `\[...\]` syntax
+- Light/dark theme support, adapting to different product styles
+- Plugin architecture supporting remark/rehype plugin extensions
 
-### 🎬 **Smooth Animation**
+### 🔧 **Developer Experience**
 
-- High-frequency typing support (`requestAnimationFrame` mode supports typing intervals as low as `0ms`)
-- Frame-synchronized rendering, perfectly matching browser 60fps
-- Smart character batch processing for more natural visual effects
 - Support for typing interruption `stop` and resume `resume`
+- Support for disabling and enabling typing
 
-### 🔧 **Flexible and Easy to Use**
-
-- **Declarative API**: Suitable for simple scenarios, React-style
-- **Imperative API**: Suitable for streaming data, better performance
-- **Native TypeScript support**: Complete type hints
-
-### 🧮 **Mathematical Formula Support**
+### 🎬 **Smooth Animation**
 
-- **KaTeX Integration**: High-performance mathematical formula rendering
-- **Plugin Architecture**: Flexible configuration through plugin system
-- **Dual Syntax Support**: `$...$` and `\[...\]` delimiters
-- **Streaming Compatible**: Perfect support for mathematical formulas in typing animations
-- **Theme Adaptation**: Automatic adaptation to light/dark themes
+- Dual timer mode optimization, supporting `requestAnimationFrame` and `setTimeout` modes
+- High-frequency typing support (`requestAnimationFrame` mode supports typing intervals as low as `0ms`)
+- Frame-synchronized rendering, perfectly matching browser refresh rate
+- Smart character batch processing for more natural visual effects
 
 ---
 
@@ -76,8 +67,10 @@ No installation required, use directly in browser:
 [DEMO](https://stackblitz.com/edit/stackblitz-starters-7vcclcw7?file=index.html)
 
 ```html
-<!-- Import styles -->
+<!-- Import styles, required -->
 <link rel="stylesheet" href="https://esm.sh/ds-markdown/dist/style.css" />
+
+<!-- Import katex math formula styles, only if needed -->
 <link rel="stylesheet" href="https://esm.sh/ds-markdown/dist/katex.css" />
 
 <!-- Import component -->
@@ -105,13 +98,37 @@ function App() {
 }
 ```
 
+### Disable Typing Animation
+
+```tsx
+import DsMarkdown from 'ds-markdown';
+import 'ds-markdown/style.css';
+
+function StaticDemo() {
+  const [disableTyping, setDisableTyping] = useState(false);
+
+  return (
+    <div>
+      <button onClick={() => setDisableTyping(!disableTyping)}>{disableTyping ? 'Enable' : 'Disable'} Typing Effect</button>
+
+      <DsMarkdown interval={20} answerType="answer" disableTyping={disableTyping}>
+        # Static Display Mode When `disableTyping` is `true`, content will be displayed immediately without typing animation. This is very useful in certain scenarios: - 📄 Static document display -
+        🔄 Toggle display modes - ⚡ Quick content preview
+      </DsMarkdown>
+    </div>
+  );
+}
+```
+
 ### Mathematical Formula Support
 
 ```tsx
 import DsMarkdown from 'ds-markdown';
+// If you need to display formulas, import the formula conversion plugin
 import { katexPlugin } from 'ds-markdown/plugins';
 import 'ds-markdown/style.css';
-import 'ds-markdown/katex.css'; // Import mathematical formula styles
+// If you need to display formulas, import mathematical formula styles
+import 'ds-markdown/katex.css';
 
 function MathDemo() {
   return (
@@ -171,32 +188,47 @@ Let's explore these new features together!`);
 
 ## 📚 Complete API Documentation
 
-### Declarative API (Recommended for Beginners)
+### Default export DsMarkdown and MarkdownCMD props
+
+```js
+import DsMarkdown, { MarkdownCMD } from 'ds-markdown';
+```
+
+| Property        | Type                                          | Description                     | Default                                                                       |
+| --------------- | --------------------------------------------- | ------------------------------- | ----------------------------------------------------------------------------- |
+| `interval`      | `number`                                      | Typing interval (milliseconds)  | `30`                                                                          |
+| `timerType`     | `'setTimeout'` \| `'requestAnimationFrame'`   | Timer type                      | Current default is `setTimeout`, will change to `requestAnimationFrame` later |
+| `answerType`    | `'thinking'` \| `'answer'`                    | Content type (affects styling)  | `'answer'`                                                                    |
+| `theme`         | `'light'` \| `'dark'`                         | Theme type                      | `'light'`                                                                     |
+| `plugins`       | `IMarkdownPlugin[]`                           | Plugin configuration            | `[]`                                                                          |
+| `math`          | [IMarkdownMath](#IMarkdownMath)               | Mathematical formula config     | `{ splitSymbol: 'dollar' }`                                                   |
+| `onEnd`         | `(data: EndData) => void`                     | Typing completion callback      | -                                                                             |
+| `onStart`       | `(data: StartData) => void`                   | Typing start callback           | -                                                                             |
+| `onTypedChar`   | `(data: `[ITypedChar](#ITypedChar)`) => void` | Character-by-character callback | -                                                                             |
+| `disableTyping` | `boolean`                                     | Disable typing animation        | `false`                                                                       |
+
+> Note: If `disableTyping` changes from `true` to `false` during typing, all remaining characters will be displayed at once on the next typing trigger.
+
+### ITypedChar
 
-| Property      | Type                                        | Description                        | Default                                                                       |
-| ------------- | ------------------------------------------- | ---------------------------------- | ----------------------------------------------------------------------------- |
-| `interval`    | `number`                                    | Typing interval (milliseconds)     | `30`                                                                          |
-| `timerType`   | `'setTimeout'` \| `'requestAnimationFrame'` | Timer type                         | Current default is `setTimeout`, will change to `requestAnimationFrame` later |
-| `answerType`  | `'thinking'` \| `'answer'`                  | Content type (affects style theme) | `'answer'`                                                                    |
-| `theme`       | `'light'` \| `'dark'`                       | Theme type                         | `'light'`                                                                     |
-| `plugins`     | `IMarkdownPlugin[]`                         | Plugin configuration               | `[]`                                                                          |
-| `math`        | `IMarkdownMath`                             | Mathematical formula configuration | `{ splitSymbol: 'dollar' }`                                                   |
-| `onEnd`       | `(data: EndData) => void`                   | Typing completion callback         | -                                                                             |
-| `onStart`     | `(data: StartData) => void`                 | Typing start callback              | -                                                                             |
-| `onTypedChar` | `(data: CharData) => void`                  | Per-character typing callback      | -                                                                             |
+| Property       | Type     | Description                        | Default |
+| -------------- | -------- | ---------------------------------- | ------- |
+| `percent`      | `number` | Typing progress percentage         | `0`     |
+| `currentChar`  | `string` | Current character being typed      | -       |
+| `currentIndex` | `number` | Current index in the entire string | `0`     |
 
-### Mathematical Formula Configuration
+#### IMarkdownMath
 
-| Property      | Type                      | Description                         | Default   |
-| ------------- | ------------------------- | ----------------------------------- | --------- |
-| `splitSymbol` | `'dollar'` \| `'bracket'` | Mathematical formula delimiter type | `'dollar' |
+| Property      | Type                      | Description                    | Default    |
+| ------------- | ------------------------- | ------------------------------ | ---------- |
+| `splitSymbol` | `'dollar'` \| `'bracket'` | Mathematical formula delimiter | `'dollar'` |
 
-**Delimiter Description:**
+**Delimiter explanation:**
 
-- `'dollar'`: Use `$...$` and `$$...$$` syntax
-- `'bracket'`: Use `\(...\)` and `\[...\]` syntax
+- `'dollar'`: Uses `$...$` and `$$...$$` syntax
+- `'bracket'`: Uses `\(...\)` and `\[...\]` syntax
 
-### Plugin Configuration
+#### IMarkdownPlugin
 
 | Property       | Type                      | Description      | Default |
 | -------------- | ------------------------- | ---------------- | ------- |
@@ -205,17 +237,26 @@ Let's explore these new features together!`);
 | `type`         | `'buildIn'` \| `'custom'` | Plugin type      | -       |
 | `id`           | `any`                     | Plugin unique ID | -       |
 
-### Imperative API (Recommended for Streaming Scenarios)
+### Component Exposed Methods
+
+#### Default export DsMarkdown
+
+| Method   | Parameters | Description   |
+| -------- | ---------- | ------------- |
+| `stop`   | -          | Pause typing  |
+| `resume` | -          | Resume typing |
+
+#### MarkdownCMD Exposed Methods
 
 | Method            | Parameters                                  | Description                   |
 | ----------------- | ------------------------------------------- | ----------------------------- |
 | `push`            | `(content: string, answerType: AnswerType)` | Add content and start typing  |
 | `clear`           | -                                           | Clear all content and state   |
 | `triggerWholeEnd` | -                                           | Manually trigger end callback |
-| `stop`            | -                                           | Pause typing animation        |
-| `resume`          | -                                           | Resume typing animation       |
+| `stop`            | -                                           | Pause typing                  |
+| `resume`          | -                                           | Resume typing                 |
 
-**Usage Example:**
+**Usage example:**
 
 ```tsx
 markdownRef.current?.stop(); // Pause animation
@@ -226,6 +267,10 @@ markdownRef.current?.resume(); // Resume animation
 
 ## 🧮 Mathematical Formula Usage Guide
 
+[DEMO1: Pythagorean Theorem](https://stackblitz.com/edit/vitejs-vite-z94syu8j?file=src%2FApp.tsx)
+
+[DEMO2: Problem Solving](https://stackblitz.com/edit/vitejs-vite-xk9lxagc?file=README.md)
+
 ### Basic Syntax
 
 ```tsx
@@ -246,7 +291,7 @@ import { katexPlugin } from 'ds-markdown/plugins';
 ### Delimiter Selection
 
 ```tsx
-// Use dollar symbol delimiters (default)
+// Using dollar sign delimiters (default)
 <DsMarkdown
   plugins={[katexPlugin]}
   math={{ splitSymbol: 'dollar' }}
@@ -255,7 +300,7 @@ import { katexPlugin } from 'ds-markdown/plugins';
   Block: $$\sum_{i=1}^{n} x_i = x_1 + x_2 + \cdots + x_n$$
 </DsMarkdown>
 
-// Use bracket delimiters
+// Using bracket delimiters
 <DsMarkdown
   plugins={[katexPlugin]}
   math={{ splitSymbol: 'bracket' }}
@@ -270,10 +315,10 @@ import { katexPlugin } from 'ds-markdown/plugins';
 ```tsx
 // Perfect support for mathematical formulas in streaming output
 const mathContent = [
-  'Pythagorean Theorem: ',
+  'Pythagorean Theorem:',
   '$a^2 + b^2 = c^2$',
   '\n\n',
-  'Where:\n',
+  'Where:',
   '- $a$ and $b$ are the legs\n',
   '- $c$ is the hypotenuse\n\n',
   'For the classic "3-4-5" triangle:\n',
@@ -344,15 +389,15 @@ const customPlugin = createBuildInPlugin({
 
 ```typescript
 // 🎯 Features
-- Time-driven: Calculate character count based on actual elapsed time
-- Batch processing: Can process multiple characters per frame
-- Frame synchronization: Synchronized with browser 60fps refresh rate
-- High-frequency optimization: Perfect support for high-speed typing with interval < 16ms
+- Time-driven: Calculates character count based on actual elapsed time
+- Batch processing: Can process multiple characters in a single frame
+- Frame-synchronized: Syncs with browser 60fps refresh rate
+- High-frequency optimized: Perfect support for interval < 16ms high-speed typing
 
 // 🎯 Use Cases
 - Default choice for modern web applications
-- Pursuing smooth animation effects
-- High-frequency typing (interval > 0 is sufficient)
+- Pursuit of smooth animation effects
+- High-frequency typing (interval > 0 works)
 - AI real-time conversation scenarios
 ```
 
@@ -360,28 +405,28 @@ const customPlugin = createBuildInPlugin({
 
 ```typescript
 // 🎯 Features
-- Single character: Process exactly one character each time
-- Fixed interval: Execute strictly according to set time
-- Beat feeling: Classic typewriter rhythm
+- Single character: Precisely processes one character at a time
+- Fixed interval: Strictly executes at set time intervals
+- Rhythmic: Classic typewriter rhythm feel
 - Precise control: Suitable for specific timing requirements
 
 // 🎯 Use Cases
-- Need precise time control
+- Need precise timing control
 - Creating retro typewriter effects
 - Scenarios with high compatibility requirements
 ```
 
 ### 📊 Performance Comparison
 
-| Feature                     | requestAnimationFrame                          | setTimeout                      |
-| --------------------------- | ---------------------------------------------- | ------------------------------- |
-| **Character Processing**    | Can process multiple characters per frame      | Process one character each time |
-| **High-frequency Interval** | ✅ Excellent (5ms → 3 characters per frame)    | ❌ May lag                      |
-| **Low-frequency Interval**  | ✅ Normal (100ms → 1 character after 6 frames) | ✅ Precise                      |
-| **Visual Effect**           | 🎬 Smooth animation feeling                    | ⚡ Precise beat feeling         |
-| **Performance Overhead**    | 🟢 Low (frame synchronization)                 | 🟡 Medium (timer)               |
+| Feature                  | requestAnimationFrame               | setTimeout              |
+| ------------------------ | ----------------------------------- | ----------------------- |
+| **Character Processing** | Multiple characters per frame       | One character at a time |
+| **High Frequency**       | ✅ Excellent (5ms → 3 chars/frame)  | ❌ May lag              |
+| **Low Frequency**        | ✅ Normal (100ms → 1 char/6 frames) | ✅ Precise              |
+| **Visual Effect**        | 🎬 Smooth animation feel            | ⚡ Precise rhythm feel  |
+| **Performance Overhead** | 🟢 Low (frame-synced)               | 🟡 Medium (timer)       |
 
-High-frequency recommended `requestAnimationFrame`, low-frequency recommended `setTimeout`
+High frequency recommended `requestAnimationFrame`, low frequency recommended `setTimeout`
 
 ---
 
@@ -405,16 +450,16 @@ function StreamingChat() {
     // Thinking phase
     markdownRef.current?.push('🤔 Analyzing your question...', 'thinking');
     await delay(1000);
-    markdownRef.current?.push('\n\n✅ Analysis complete, starting to answer', 'thinking');
+    markdownRef.current?.push('\n\n✅ Analysis complete, starting answer', 'thinking');
 
     // Streaming answer
     const chunks = [
-      '# React 19 New Features Analysis\n\n',
+      '# React 19 Feature Analysis\n\n',
       '## 🚀 React Compiler\n',
       'The biggest highlight of React 19 is the introduction of **React Compiler**:\n\n',
-      '- 🎯 **Automatic Optimization**: No need for manual memo and useMemo\n',
-      '- ⚡ **Performance Boost**: Compile-time optimization, zero runtime overhead\n',
-      '- 🔧 **Backward Compatible**: No need to modify existing code\n\n',
+      '- 🎯 **Automatic optimization**: No need for manual memo and useMemo\n',
+      '- ⚡ **Performance boost**: Compile-time optimization, zero runtime overhead\n',
+      '- 🔧 **Backward compatible**: Existing code needs no modification\n\n',
       '## 📝 Actions Simplify Forms\n',
       'The new Actions API makes form handling simpler:\n\n',
       '```tsx\n',
@@ -439,9 +484,9 @@ function StreamingChat() {
 
   return (
     <div className="chat-container">
-      <button onClick={simulateAIResponse}>🤖 Ask about React 19 New Features</button>
+      <button onClick={simulateAIResponse}>🤖 Ask about React 19 features</button>
 
-      <MarkdownCMD ref={markdownRef} interval={10} timerType="requestAnimationFrame" onEnd={(data) => console.log('Paragraph complete:', data)} />
+      <MarkdownCMD ref={markdownRef} interval={10} timerType="requestAnimationFrame" onEnd={(data) => console.log('Section complete:', data)} />
     </div>
   );
 }
@@ -461,7 +506,7 @@ function MathStreamingDemo() {
     markdownRef.current?.clear();
 
     const mathChunks = [
-      '# Pythagorean Theorem Explanation\n\n',
+      '# Pythagorean Theorem Explained\n\n',
       'In a right triangle, the square of the hypotenuse equals the sum of squares of the two legs:\n\n',
       '$a^2 + b^2 = c^2$\n\n',
       'Where:\n',
@@ -488,64 +533,6 @@ function MathStreamingDemo() {
 }
 ```
 
-### 🔄 Streaming Markdown Syntax Processing
-
-**Core Problem**: Incomplete Markdown syntax during streaming output can cause rendering errors
-
-```tsx
-// 🚨 Problem scenario
-push('#'); // "# "
-push(' '); // "# "
-push('Title'); // "# Title"
-push('\n'); // "# Title\n"
-push('1'); // "# Title\n1"     ← This will be incorrectly parsed as paragraph
-push('.'); // "# Title\n1."    ← Forms correct list
-push(' Item'); // "# Title\n1. Item"
-```
-
-**✅ Smart Solution**: Built-in synchronous buffering mechanism
-
-```tsx
-// Component intelligently handles syntax boundaries
-const handleStreamingMarkdown = () => {
-  const chunks = ['#', ' ', 'Use', 'Skills', '\n', '1', '.', ' ', 'Skill1', '\n', '2', '.', ' Skill2'];
-
-  chunks.forEach((chunk) => {
-    markdownRef.current?.push(chunk, 'answer');
-    // No delay needed, component internally buffers intelligently
-  });
-};
-
-// 🧠 Intelligent processing flow:
-// 1. Real-time detection of incomplete syntax like "# Use Skills\n1"
-// 2. Intelligent buffering, waiting for more characters
-// 3. Process immediately after receiving "." to form "1."
-// 4. Zero delay, pure synchronous processing
-```
-
-**Supported Syntax Detection**:
-
-````typescript
-// ✅ Complete syntax (immediate processing)
-'## Title'; // Complete title
-'1. List item'; // Complete list item
-'- Item'; // Complete unordered list
-'> Quote content'; // Complete quote
-'```javascript'; // Code block start
-'```'; // Code block end
-'Content ending with newline\n'; // Newline boundary
-'$a + b$'; // Complete mathematical formula
-'$$\\sum x$$'; // Complete block mathematical formula
-
-// 🔄 Incomplete syntax (intelligent buffering)
-'##'; // Only title symbol
-'1'; // Only number
-'```java'; // Possible code block start
-'$a +'; // Incomplete mathematical formula
-````
-
----
-
 ## 🔧 Best Practices
 
 ### 1. Performance Optimization
@@ -572,21 +559,21 @@ useEffect(() => {
 
 // ❌ Avoid: Frequent children updates
 const [content, setContent] = useState('');
-// Each update will re-parse the entire content
+// Each update re-parses the entire content
 ```
 
 ### 3. Mathematical Formula Optimization
 
 ```tsx
-// ✅ Recommended: Load mathematical formula styles on demand
+// ✅ Recommended: Load math formula styles on demand
 import 'ds-markdown/style.css';
 import 'ds-markdown/katex.css'; // Only import when needed
 
-// ✅ Recommended: Reasonable use of delimiters
-// For simple formulas, use $...$ for conciseness
+// ✅ Recommended: Use delimiters appropriately
+// For simple formulas, use $...$ for simplicity
 // For complex formulas, use $$...$$ for clarity
 
-// ✅ Recommended: Plugin-based configuration
+// ✅ Recommended: Plugin configuration
 import { katexPlugin } from 'ds-markdown/plugins';
 <DsMarkdown plugins={[katexPlugin]}>Mathematical formula content</DsMarkdown>;
 ```
@@ -599,101 +586,3 @@ import { MarkdownCMDRef } from 'ds-markdown';
 const ref = useRef<MarkdownCMDRef>(null);
 // Complete TypeScript type hints
 ```
-
-### 5. Style Customization
-
-```css
-/* Thinking area styles */
-.ds-markdown-thinking {
-  background: rgba(255, 193, 7, 0.1);
-  border-left: 3px solid #ffc107;
-  padding: 12px;
-  border-radius: 6px;
-  margin: 8px 0;
-}
-
-/* Answer area styles */
-.ds-markdown-answer {
-  color: #333;
-  line-height: 1.6;
-  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
-}
-
-/* Code block styles */
-.ds-markdown pre {
-  background: #f8f9fa;
-  border-radius: 8px;
-  padding: 16px;
-  overflow-x: auto;
-}
-
-/* Table styles */
-.ds-markdown-table {
-  border-collapse: collapse;
-  width: 100%;
-  margin: 16px 0;
-}
-
-.ds-markdown-table th,
-.ds-markdown-table td {
-  border: 1px solid #ddd;
-  padding: 8px 12px;
-  text-align: left;
-}
-
-/* Mathematical formula styles */
-.katex {
-  font-size: 1.1em;
-}
-
-.katex-display {
-  margin: 1em 0;
-  text-align: center;
-}
-
-/* Dark theme mathematical formulas */
-[data-theme='dark'] .katex {
-  color: #e1e1e1;
-}
-```
-
----
-
-## 🌐 Compatibility
-
-| Environment    | Version Requirement                 | Description              |
-| -------------- | ----------------------------------- | ------------------------ |
-| **React**      | 16.8.0+                             | Requires Hooks support   |
-| **TypeScript** | 4.0+                                | Optional but recommended |
-| **Browser**    | Chrome 60+, Firefox 55+, Safari 12+ | Modern browsers          |
-| **Node.js**    | 14.0+                               | Build environment        |
-
----
-
-## 🤝 Contributing
-
-Welcome to submit Issues and Pull Requests!
-
-1. Fork this repository
-2. Create feature branch: `git checkout -b feature/amazing-feature`
-3. Commit changes: `git commit -m 'Add amazing feature'`
-4. Push branch: `git push origin feature/amazing-feature`
-5. Submit Pull Request
-
----
-
-## 📄 License
-
-MIT © [onshinpei](https://github.com/onshinpei)
-
----
-
-<div align="center">
-  <strong>If this project helps you, please give it a ⭐️ Star!</strong>
-  
-  <br><br>
-  
-  [🐛 Report Issues](https://github.com/onshinpei/ds-markdown/issues) | 
-  [💡 Feature Suggestions](https://github.com/onshinpei/ds-markdown/issues) | 
-  [📖 View Documentation](https://onshinpei.github.io/ds-markdown/)
-</div>