ds-markdown 0.0.14-beta.1 → 0.0.15-beta.0

package/README.en.md

@@ -38,6 +38,7 @@ A React component designed specifically for modern AI applications, providing sm
 - 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`
 
 ### 🔧 **Flexible and Easy to Use**
 
@@ -45,6 +46,13 @@ A React component designed specifically for modern AI applications, providing sm
 - **Imperative API**: Suitable for streaming data, better performance
 - **Native TypeScript support**: Complete type hints
 
+### 🧮 **Mathematical Formula Support**
+
+- **KaTeX Integration**: High-performance mathematical formula rendering
+- **Dual Syntax Support**: `$...$` and `\[...\]` delimiters
+- **Streaming Compatible**: Perfect support for mathematical formulas in typing animations
+- **Theme Adaptation**: Automatic adaptation to light/dark themes
+
 ---
 
 ## 📦 Quick Installation
@@ -64,39 +72,16 @@ pnpm add ds-markdown
 
 No installation required, use directly in browser:
 
+[DEMO](https://stackblitz.com/edit/stackblitz-starters-7vcclcw7?file=index.html)
+
 ```html
 <!-- Import styles -->
 <link rel="stylesheet" href="https://esm.sh/ds-markdown/dist/style.css" />
+<link rel="stylesheet" href="https://esm.sh/ds-markdown/dist/katex.css" />
 
 <!-- Import component -->
-<script type="importmap">
-  {
-    "imports": {
-      "react": "https://esm.sh/react@19.1.0",
-      "react-dom/client": "https://esm.sh/react-dom@19.1.0/client",
-      "ds-markdown": "https://esm.sh/ds-markdown"
-    }
-  }
-</script>
-<script type="module" src="https://esm.sh/tsx"></script>
-
-<script type="text/babel">
-  import { createRoot } from 'react-dom/client';
-  import DsMarkdown from 'ds-markdown';
-
-  const markdown = `
-# Hello ds-markdown
-
-This is a **high-performance** typing animation component!
-
-## Features
-- ⚡ Zero-delay streaming
-- 🎬 Smooth typing animation
-- 🎯 Perfect syntax support
-  `;
-
-  const root = createRoot(document.getElementById('root'));
-  root.render(<DsMarkdown interval={20}>{markdown}</DsMarkdown>);
+<script type="module">
+  import Markdown from 'https://esm.sh/ds-markdown';
 </script>
 ```
 
@@ -104,6 +89,8 @@ This is a **high-performance** typing animation component!
 
 ### Basic Usage
 
+[DEMO](https://stackblitz.com/edit/vitejs-vite-z94syu8j?file=src%2FApp.tsx)
+
 ```tsx
 import DsMarkdown from 'ds-markdown';
 import 'ds-markdown/style.css';
@@ -117,6 +104,23 @@ function App() {
 }
 ```
 
+### Mathematical Formula Support
+
+```tsx
+import DsMarkdown from 'ds-markdown';
+import 'ds-markdown/style.css';
+import 'ds-markdown/katex.css'; // Import mathematical formula styles
+
+function MathDemo() {
+  return (
+    <DsMarkdown interval={20} answerType="answer" math={{ isOpen: true, splitSymbol: 'dollar' }}>
+      # Pythagorean Theorem In a right triangle, the square of the hypotenuse equals the sum of squares of the two legs: $a^2 + b^2 = c^2$ Where: - $a$ and $b$ are the legs - $c$ is the hypotenuse For
+      the classic "3-4-5" triangle: $c = \sqrt{3 ^ (2 + 4) ^ 2} = \sqrt{25} = 5$
+    </DsMarkdown>
+  );
+}
+```
+
 ### AI Conversation Scenario
 
 ```tsx
@@ -173,40 +177,127 @@ Let's explore these new features together!`);
 | `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'`                                                                     |
+| `math`        | `IMarkdownMath`                             | Mathematical formula configuration | `{ isOpen: false, splitSymbol: 'dollar' }`                                    |
 | `onEnd`       | `(data: EndData) => void`                   | Typing completion callback         | -                                                                             |
 | `onStart`     | `(data: StartData) => void`                 | Typing start callback              | -                                                                             |
 | `onTypedChar` | `(data: CharData) => void`                  | Per-character typing callback      | -                                                                             |
 
-### Imperative API (Recommended for Streaming Scenarios)
+### Mathematical Formula Configuration
 
-```typescript
-import { MarkdownCMD, MarkdownCMDRef } from 'ds-markdown';
+| Property      | Type                      | Description                           | Default    |
+| ------------- | ------------------------- | ------------------------------------- | ---------- |
+| `isOpen`      | `boolean`                 | Enable mathematical formula rendering | `false`    |
+| `splitSymbol` | `'dollar'` \| `'bracket'` | Mathematical formula delimiter type   | `'dollar'` |
 
-interface MarkdownCMDRef {
-  push: (content: string, answerType: AnswerType) => void;
-  clear: () => void;
-  triggerWholeEnd: () => void;
-}
-```
+**Delimiter Description:**
+
+- `'dollar'`: Use `$...$` and `$$...$$` syntax
+- `'bracket'`: Use `\(...\)` and `\[...\]` syntax
+
+### Imperative API (Recommended for Streaming Scenarios)
 
 | 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       |
+
+**Usage Example:**
+
+```tsx
+markdownRef.current?.stop(); // Pause animation
+markdownRef.current?.resume(); // Resume animation
+```
 
 ---
 
-## 🎛️ Timer Mode Detailed Explanation
+## 🧮 Mathematical Formula Usage Guide
+
+### Basic Syntax
+
+```tsx
+// 1. Enable mathematical formula support
+<DsMarkdown math={{ isOpen: true }}>
+  # Mathematical Formula Example
+
+  // Inline formula
+  This is an inline formula: $E = mc^2$
+
+  // Block formula
+  $$\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}$$
+</DsMarkdown>
+```
+
+### Delimiter Selection
+
+```tsx
+// Use dollar symbol delimiters (default)
+<DsMarkdown math={{ isOpen: true, splitSymbol: 'dollar' }}>
+  Inline: $a + b = c$
+  Block: $$\sum_{i=1}^{n} x_i = x_1 + x_2 + \cdots + x_n$$
+</DsMarkdown>
+
+// Use bracket delimiters
+<DsMarkdown math={{ isOpen: true, splitSymbol: 'bracket' }}>
+  Inline: \(a + b = c\)
+  Block: \[\sum_{i=1}^{n} x_i = x_1 + x_2 + \cdots + x_n\]
+</DsMarkdown>
+```
+
+### Streaming Mathematical Formulas
+
+```tsx
+// Perfect support for mathematical formulas in streaming output
+const mathContent = [
+  'Pythagorean Theorem: ',
+  '$a^2 + b^2 = c^2$',
+  '\n\n',
+  'Where:\n',
+  '- $a$ and $b$ are the legs\n',
+  '- $c$ is the hypotenuse\n\n',
+  'For the classic "3-4-5" triangle:\n',
+  '$c = \\sqrt{3^2 + 4^2} = \\sqrt{25} = 5$\n\n',
+  'This theorem has wide applications in geometry!',
+];
+
+mathContent.forEach((chunk) => {
+  markdownRef.current?.push(chunk, 'answer');
+});
+```
+
+### Style Customization
+
+```css
+/* Mathematical formula style customization */
+.katex {
+  font-size: 1.1em;
+}
+
+.katex-display {
+  margin: 1em 0;
+  text-align: center;
+}
+
+/* Dark theme adaptation */
+[data-theme='dark'] .katex {
+  color: #e1e1e1;
+}
+```
+
+---
+
+## 🎛️ Timer Mode Details
 
 ### `requestAnimationFrame` Mode 🌟 (Recommended)
 
 ```typescript
 // 🎯 Features
 - Time-driven: Calculate character count based on actual elapsed time
-- Batch processing: Can process multiple characters within a single frame
-- Frame-synchronized: Synchronized with browser 60fps refresh rate
-- High-frequency optimized: Perfect support for interval < 16ms high-speed typing
+- 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
 
 // 🎯 Use Cases
 - Default choice for modern web applications
@@ -219,9 +310,9 @@ interface MarkdownCMDRef {
 
 ```typescript
 // 🎯 Features
-- Single character: Precisely processes one character at a time
-- Fixed interval: Executes strictly according to set time
-- Rhythmic feel: Classic typewriter rhythm
+- Single character: Process exactly one character each time
+- Fixed interval: Execute strictly according to set time
+- Beat feeling: Classic typewriter rhythm
 - Precise control: Suitable for specific timing requirements
 
 // 🎯 Use Cases
@@ -232,15 +323,15 @@ interface MarkdownCMDRef {
 
 ### 📊 Performance Comparison
 
-| Feature                     | requestAnimationFrame                     | setTimeout                      |
-| --------------------------- | ----------------------------------------- | ------------------------------- |
-| **Character Processing**    | Can process multiple characters per frame | Process one character at a time |
-| **High-frequency Interval** | ✅ Excellent (5ms → 3 chars per frame)    | ❌ May lag                      |
-| **Low-frequency Interval**  | ✅ Normal (100ms → 1 char after 6 frames) | ✅ Precise                      |
-| **Visual Effect**           | 🎬 Smooth animation feel                  | ⚡ Precise rhythmic feel        |
-| **Performance Overhead**    | 🟢 Low (frame-synchronized)               | 🟡 Medium (timer)               |
+| 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)               |
 
-High-frequency recommends `requestAnimationFrame`, low-frequency recommends `setTimeout`
+High-frequency recommended `requestAnimationFrame`, low-frequency recommended `setTimeout`
 
 ---
 
@@ -248,7 +339,7 @@ High-frequency recommends `requestAnimationFrame`, low-frequency recommends `set
 
 ### 📝 AI Streaming Conversation
 
-[DEMO: 🔧 StackBlitz 体验](https://stackblitz.com/edit/vitejs-vite-2ri8kex3?file=src%2FApp.tsx)
+[DEMO: 🔧 StackBlitz Experience](https://stackblitz.com/edit/vitejs-vite-2ri8kex3?file=src%2FApp.tsx)
 
 ````tsx
 import { useRef } from 'react';
@@ -264,7 +355,7 @@ function StreamingChat() {
     // Thinking phase
     markdownRef.current?.push('🤔 Analyzing your question...', 'thinking');
     await delay(1000);
-    markdownRef.current?.push('\n\n✅ Analysis complete, starting answer', 'thinking');
+    markdownRef.current?.push('\n\n✅ Analysis complete, starting to answer', 'thinking');
 
     // Streaming answer
     const chunks = [
@@ -273,7 +364,7 @@ function StreamingChat() {
       '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**: Existing code needs no modification\n\n',
+      '- 🔧 **Backward Compatible**: No need to modify existing code\n\n',
       '## 📝 Actions Simplify Forms\n',
       'The new Actions API makes form handling simpler:\n\n',
       '```tsx\n',
@@ -298,9 +389,9 @@ function StreamingChat() {
 
   return (
     <div className="chat-container">
-      <button onClick={simulateAIResponse}>🤖 Ask About React 19 Features</button>
+      <button onClick={simulateAIResponse}>🤖 Ask about React 19 New Features</button>
 
-      <MarkdownCMD ref={markdownRef} interval={10} timerType="requestAnimationFrame" onEnd={(data) => console.log('Paragraph completed:', data)} />
+      <MarkdownCMD ref={markdownRef} interval={10} timerType="requestAnimationFrame" onEnd={(data) => console.log('Paragraph complete:', data)} />
     </div>
   );
 }
@@ -308,37 +399,74 @@ function StreamingChat() {
 const delay = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
 ````
 
+### 🧮 Mathematical Formula Streaming Rendering
+
+```tsx
+function MathStreamingDemo() {
+  const markdownRef = useRef<MarkdownCMDRef>(null);
+
+  const simulateMathResponse = async () => {
+    markdownRef.current?.clear();
+
+    const mathChunks = [
+      '# Pythagorean Theorem Explanation\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',
+      '- $a$ and $b$ are the legs\n',
+      '- $c$ is the hypotenuse\n\n',
+      'For the classic "3-4-5" triangle:\n',
+      '$c = \\sqrt{3^2 + 4^2} = \\sqrt{25} = 5$\n\n',
+      'This theorem has wide applications in geometry!',
+    ];
+
+    for (const chunk of mathChunks) {
+      await delay(150);
+      markdownRef.current?.push(chunk, 'answer');
+    }
+  };
+
+  return (
+    <div>
+      <button onClick={simulateMathResponse}>📐 Explain Pythagorean Theorem</button>
+
+      <MarkdownCMD ref={markdownRef} interval={20} timerType="requestAnimationFrame" math={{ isOpen: true, splitSymbol: 'dollar' }} />
+    </div>
+  );
+}
+```
+
 ### 🔄 Streaming Markdown Syntax Processing
 
-**Core Issue**: During streaming output, incomplete Markdown syntax can cause rendering errors
+**Core Problem**: Incomplete Markdown syntax during streaming output can cause rendering errors
 
 ```tsx
-// 🚨 Problem Scenario
+// 🚨 Problem scenario
 push('#'); // "# "
 push(' '); // "# "
 push('Title'); // "# Title"
 push('\n'); // "# Title\n"
-push('1'); // "# Title\n1"     ← This will be misinterpreted as paragraph
+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 in component
+**✅ Smart Solution**: Built-in synchronous buffering mechanism
 
 ```tsx
 // Component intelligently handles syntax boundaries
 const handleStreamingMarkdown = () => {
-  const chunks = ['#', ' ', 'Using', 'Skills', '\n', '1', '.', ' ', 'Skill1', '\n', '2', '.', ' Skill2'];
+  const chunks = ['#', ' ', 'Use', 'Skills', '\n', '1', '.', ' ', 'Skill1', '\n', '2', '.', ' Skill2'];
 
   chunks.forEach((chunk) => {
     markdownRef.current?.push(chunk, 'answer');
-    // No delay needed, component buffers intelligently internally
+    // No delay needed, component internally buffers intelligently
   });
 };
 
-// 🧠 Smart Processing Flow:
-// 1. Real-time detection of "# Using Skills\n1" incomplete syntax
-// 2. Smart buffering, waiting for more characters
+// 🧠 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
 ```
@@ -346,7 +474,7 @@ const handleStreamingMarkdown = () => {
 **Supported Syntax Detection**:
 
 ````typescript
-// ✅ Complete syntax (process immediately)
+// ✅ Complete syntax (immediate processing)
 '## Title'; // Complete title
 '1. List item'; // Complete list item
 '- Item'; // Complete unordered list
@@ -354,11 +482,14 @@ const handleStreamingMarkdown = () => {
 '```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 (smart buffering)
-'##'; // Only title symbols
+// 🔄 Incomplete syntax (intelligent buffering)
+'##'; // Only title symbol
 '1'; // Only number
 '```java'; // Possible code block start
+'$a +'; // Incomplete mathematical formula
 ````
 
 ---
@@ -371,7 +502,7 @@ const handleStreamingMarkdown = () => {
 // ✅ Recommended configuration
 <DsMarkdown
   timerType="requestAnimationFrame"
-  interval={15} // 15-30ms for optimal experience
+  interval={15} // 15-30ms for best experience
 />
 
 // ❌ Avoid too small intervals
@@ -392,7 +523,22 @@ const [content, setContent] = useState('');
 // Each update will re-parse the entire content
 ```
 
-### 3. Type Safety
+### 3. Mathematical Formula Optimization
+
+```tsx
+// ✅ Recommended: Load mathematical 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
+// For complex formulas, use $$...$$ for clarity
+
+// ❌ Avoid: Enable mathematical formulas when not needed
+<DsMarkdown math={{ isOpen: true }}>Plain text content</DsMarkdown>;
+```
+
+### 4. Type Safety
 
 ```tsx
 import { MarkdownCMDRef } from 'ds-markdown';
@@ -401,7 +547,7 @@ const ref = useRef<MarkdownCMDRef>(null);
 // Complete TypeScript type hints
 ```
 
-### 4. Style Customization
+### 5. Style Customization
 
 ```css
 /* Thinking area styles */
@@ -441,22 +587,37 @@ const ref = useRef<MarkdownCMDRef>(null);
   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         |
+| 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 Guide
+## 🤝 Contributing
 
 Welcome to submit Issues and Pull Requests!
 
@@ -475,7 +636,7 @@ MIT © [onshinpei](https://github.com/onshinpei)
 ---
 
 <div align="center">
-  <strong>If this project helps you, please give it a ⭐️ Star for support!</strong>
+  <strong>If this project helps you, please give it a ⭐️ Star!</strong>
   
   <br><br>