@incremark/react 0.0.4 → 0.0.5

package/README.md

@@ -7,6 +7,7 @@ Incremark 的 React 18+ 集成库。
 ## 特性
 
 - 📦 **开箱即用** - 提供 `useIncremark` hook 和 `<Incremark>` 组件
+- ⌨️ **打字机效果** - 内置 `useBlockTransformer` 实现逐字符显示
 - 🎨 **可定制** - 支持自定义渲染组件
 - ⚡ **高性能** - 利用 React 的 reconciliation 机制
 - 🔧 **DevTools** - 内置开发者工具
@@ -71,11 +72,96 @@ function App() {
 | `blocks` | `Block[]` | 所有块 |
 | `completedBlocks` | `Block[]` | 已完成块 |
 | `pendingBlocks` | `Block[]` | 待处理块 |
+| `isLoading` | `boolean` | 是否正在加载 |
 | `append` | `Function` | 追加内容 |
 | `finalize` | `Function` | 完成解析 |
 | `reset` | `Function` | 重置状态 |
 | `render` | `Function` | 一次性渲染（reset + append + finalize） |
 
+### useBlockTransformer(sourceBlocks, options)
+
+打字机效果 hook。作为解析器和渲染器之间的中间层，控制内容的逐步显示。
+
+**参数：**
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `sourceBlocks` | `SourceBlock[]` | 源 blocks（通常来自 `completedBlocks`） |
+| `options.charsPerTick` | `number` | 每次显示的字符数（默认：2） |
+| `options.tickInterval` | `number` | 每次显示的间隔时间 ms（默认：50） |
+| `options.plugins` | `TransformerPlugin[]` | 插件列表（用于特殊块的处理） |
+
+**返回值：**
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `displayBlocks` | `DisplayBlock[]` | 用于渲染的 blocks |
+| `isProcessing` | `boolean` | 是否正在处理中 |
+| `skip` | `Function` | 跳过动画，立即显示全部内容 |
+| `reset` | `Function` | 重置状态 |
+| `setOptions` | `Function` | 动态更新配置 |
+
+**使用示例：**
+
+```tsx
+import { useMemo, useState, useEffect } from 'react'
+import { useIncremark, useBlockTransformer, Incremark, defaultPlugins } from '@incremark/react'
+
+function App() {
+  const { completedBlocks, append, finalize, reset: resetParser } = useIncremark()
+  
+  // 配置打字机速度
+  const [typewriterSpeed, setTypewriterSpeed] = useState(2)
+  const [typewriterInterval, setTypewriterInterval] = useState(50)
+
+  // 转换为 SourceBlock 格式
+  const sourceBlocks = useMemo(() => 
+    completedBlocks.map(block => ({
+      id: block.id,
+      node: block.node,
+      status: block.status
+    })),
+    [completedBlocks]
+  )
+
+  // 使用 BlockTransformer
+  const { 
+    displayBlocks, 
+    isProcessing, 
+    skip, 
+    reset: resetTransformer,
+    setOptions 
+  } = useBlockTransformer(sourceBlocks, {
+    charsPerTick: typewriterSpeed,
+    tickInterval: typewriterInterval,
+    plugins: defaultPlugins
+  })
+
+  // 监听配置变化
+  useEffect(() => {
+    setOptions({ charsPerTick: typewriterSpeed, tickInterval: typewriterInterval })
+  }, [typewriterSpeed, typewriterInterval, setOptions])
+
+  // 转换为渲染格式
+  const renderBlocks = useMemo(() => 
+    displayBlocks.map(db => ({
+      ...db,
+      stableId: db.id,
+      node: db.displayNode,
+      status: db.isDisplayComplete ? 'completed' : 'pending'
+    })),
+    [displayBlocks]
+  )
+
+  return (
+    <div>
+      <Incremark blocks={renderBlocks} />
+      {isProcessing && <button onClick={skip}>跳过</button>}
+    </div>
+  )
+}
+```
+
 ### useDevTools(incremark)
 
 启用 DevTools。
@@ -93,9 +179,18 @@ useDevTools(incremark)
 <Incremark 
   blocks={blocks}
   components={{ heading: MyHeading }}
+  showBlockStatus={true}
 />
 ```
 
+**Props：**
+
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `blocks` | `Block[]` | 要渲染的 blocks |
+| `components` | `object` | 自定义组件映射 |
+| `showBlockStatus` | `boolean` | 是否显示块状态（pending/completed） |
+
 ## 自定义组件
 
 ```tsx
@@ -114,6 +209,44 @@ function App() {
 }
 ```
 
+## 插件系统
+
+BlockTransformer 支持插件来处理特殊类型的块：
+
+```tsx
+import { 
+  defaultPlugins,
+  codeBlockPlugin,
+  imagePlugin,
+  mermaidPlugin,
+  mathPlugin,
+  thematicBreakPlugin,
+  createPlugin
+} from '@incremark/react'
+
+// 使用默认插件集
+const { displayBlocks } = useBlockTransformer(sourceBlocks, {
+  plugins: defaultPlugins
+})
+
+// 或自定义插件
+const myPlugin = createPlugin({
+  name: 'my-plugin',
+  match: (node) => node.type === 'myType',
+  transform: (node) => ({ displayNode: node, isComplete: true })
+})
+```
+
+**内置插件：**
+
+| 插件 | 说明 |
+|------|------|
+| `codeBlockPlugin` | 代码块整体显示 |
+| `imagePlugin` | 图片整体显示 |
+| `mermaidPlugin` | Mermaid 图表整体显示 |
+| `mathPlugin` | 数学公式整体显示 |
+| `thematicBreakPlugin` | 分隔线整体显示 |
+
 ## 与 React Query 集成
 
 ```tsx
@@ -143,7 +276,61 @@ function StreamingContent() {
 }
 ```
 
+## AutoScrollContainer
+
+自动滚动容器组件，适用于流式内容场景：
+
+```tsx
+import { useRef, useState } from 'react'
+import { AutoScrollContainer, Incremark, type AutoScrollContainerRef } from '@incremark/react'
+
+function App() {
+  const scrollRef = useRef<AutoScrollContainerRef>(null)
+  const [autoScrollEnabled, setAutoScrollEnabled] = useState(true)
+
+  return (
+    <div>
+      <AutoScrollContainer 
+        ref={scrollRef} 
+        enabled={autoScrollEnabled}
+        threshold={50}
+        behavior="smooth"
+      >
+        <Incremark blocks={blocks} />
+      </AutoScrollContainer>
+      
+      {/* 显示滚动状态 */}
+      {scrollRef.current?.isUserScrolledUp() && (
+        <span>用户已暂停自动滚动</span>
+      )}
+      
+      {/* 强制滚动到底部 */}
+      <button onClick={() => scrollRef.current?.scrollToBottom()}>
+        滚动到底部
+      </button>
+    </div>
+  )
+}
+```
+
+**Props：**
+
+| Prop | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `enabled` | `boolean` | `true` | 是否启用自动滚动 |
+| `threshold` | `number` | `50` | 触发自动滚动的底部阈值（像素） |
+| `behavior` | `ScrollBehavior` | `'instant'` | 滚动行为 |
+| `className` | `string` | - | 容器类名 |
+| `style` | `CSSProperties` | - | 容器样式 |
+
+**Ref 方法（通过 useRef）：**
+
+| 方法 | 说明 |
+|------|------|
+| `scrollToBottom()` | 强制滚动到底部 |
+| `isUserScrolledUp()` | 返回用户是否手动向上滚动了 |
+| `container` | 容器 DOM 元素引用 |
+
 ## License
 
 MIT
-

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { ParserOptions, ParsedBlock, Root, IncrementalUpdate, IncremarkParser, RootContent } from '@incremark/core';
-export { IncrementalUpdate, ParsedBlock, ParserOptions, Root, RootContent } from '@incremark/core';
+import { ParserOptions, ParsedBlock, Root, IncrementalUpdate, IncremarkParser, SourceBlock, TransformerOptions, DisplayBlock, AnimationEffect, BlockTransformer, RootContent } 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 * as _incremark_devtools from '@incremark/devtools';
 import { DevToolsOptions } from '@incremark/devtools';
 import React from 'react';
@@ -77,8 +77,78 @@ interface UseDevToolsOptions extends DevToolsOptions {
  */
 declare function useDevTools(incremark: UseIncremarkReturn, options?: UseDevToolsOptions): _incremark_devtools.IncremarkDevTools | null;
 
+interface UseBlockTransformerOptions extends Omit<TransformerOptions, 'onChange'> {
+}
+interface UseBlockTransformerReturn<T = unknown> {
+    /** 用于渲染的 display blocks */
+    displayBlocks: DisplayBlock<T>[];
+    /** 是否正在处理中 */
+    isProcessing: boolean;
+    /** 是否已暂停 */
+    isPaused: boolean;
+    /** 当前动画效果 */
+    effect: AnimationEffect;
+    /** 跳过所有动画 */
+    skip: () => void;
+    /** 重置状态 */
+    reset: () => void;
+    /** 暂停动画 */
+    pause: () => void;
+    /** 恢复动画 */
+    resume: () => void;
+    /** 动态更新配置 */
+    setOptions: (options: Partial<Pick<TransformerOptions, 'charsPerTick' | 'tickInterval' | 'effect' | 'pauseOnHidden'>>) => void;
+    /** transformer 实例（用于高级用法） */
+    transformer: BlockTransformer<T>;
+}
+/**
+ * React Hook: Block Transformer
+ *
+ * 用于控制 blocks 的逐步显示（打字机效果）
+ * 作为解析器和渲染器之间的中间层
+ *
+ * 特性：
+ * - 使用 requestAnimationFrame 实现流畅动画
+ * - 支持随机步长 `charsPerTick: [1, 3]`
+ * - 支持动画效果 `effect: 'typing'`
+ * - 页面不可见时自动暂停
+ *
+ * @example
+ * ```tsx
+ * import { useIncremark, useBlockTransformer, defaultPlugins } from '@incremark/react'
+ *
+ * function App() {
+ *   const { completedBlocks, append, finalize } = useIncremark()
+ *
+ *   // 转换为 SourceBlock 格式
+ *   const sourceBlocks = useMemo(() => completedBlocks.map(block => ({
+ *     id: block.id,
+ *     node: block.node,
+ *     status: block.status
+ *   })), [completedBlocks])
+ *
+ *   // 添加打字机效果
+ *   const { displayBlocks, isProcessing, skip, effect } = useBlockTransformer(sourceBlocks, {
+ *     charsPerTick: [1, 3],  // 随机步长
+ *     tickInterval: 30,
+ *     effect: 'typing',      // 光标效果
+ *     plugins: defaultPlugins
+ *   })
+ *
+ *   return (
+ *     <div className={effect === 'typing' ? 'typing' : ''}>
+ *       <Incremark blocks={displayBlocks} />
+ *       {isProcessing && <button onClick={skip}>跳过</button>}
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+declare function useBlockTransformer<T = unknown>(sourceBlocks: SourceBlock<T>[], options?: UseBlockTransformerOptions): UseBlockTransformerReturn<T>;
+
 interface BlockWithStableId extends ParsedBlock {
     stableId: string;
+    isLastPending?: boolean;
 }
 interface IncremarkProps {
     /** 要渲染的块列表 */
@@ -118,4 +188,46 @@ interface IncremarkRendererProps {
  */
 declare const IncremarkRenderer: React.FC<IncremarkRendererProps>;
 
-export { Incremark, type IncremarkProps, IncremarkRenderer, type IncremarkRendererProps, type UseDevToolsOptions, type UseIncremarkOptions, type UseIncremarkReturn, useDevTools, useIncremark };
+interface AutoScrollContainerProps {
+    /** 子元素 */
+    children: React.ReactNode;
+    /** 是否启用自动滚动 */
+    enabled?: boolean;
+    /** 触发自动滚动的底部阈值（像素） */
+    threshold?: number;
+    /** 滚动行为 */
+    behavior?: ScrollBehavior;
+    /** 容器样式 */
+    style?: React.CSSProperties;
+    /** 容器类名 */
+    className?: string;
+}
+interface AutoScrollContainerRef {
+    /** 强制滚动到底部 */
+    scrollToBottom: () => void;
+    /** 是否用户手动向上滚动了 */
+    isUserScrolledUp: () => boolean;
+    /** 容器元素引用 */
+    container: HTMLDivElement | null;
+}
+/**
+ * 自动滚动容器
+ *
+ * 当内容更新时自动滚动到底部。
+ * 如果用户手动向上滚动，则暂停自动滚动，直到用户再次滚动到底部。
+ *
+ * @example
+ * ```tsx
+ * const scrollRef = useRef<AutoScrollContainerRef>(null)
+ *
+ * <AutoScrollContainer ref={scrollRef} enabled={true}>
+ *   <Incremark blocks={blocks} />
+ * </AutoScrollContainer>
+ *
+ * // 强制滚动到底部
+ * scrollRef.current?.scrollToBottom()
+ * ```
+ */
+declare const AutoScrollContainer: React.ForwardRefExoticComponent<AutoScrollContainerProps & React.RefAttributes<AutoScrollContainerRef>>;
+
+export { AutoScrollContainer, type AutoScrollContainerProps, type AutoScrollContainerRef, Incremark, type IncremarkProps, IncremarkRenderer, type IncremarkRendererProps, type UseBlockTransformerOptions, type UseBlockTransformerReturn, type UseDevToolsOptions, type UseIncremarkOptions, type UseIncremarkReturn, useBlockTransformer, useDevTools, useIncremark };

package/dist/index.js

@@ -137,6 +137,80 @@ function useDevTools(incremark, options = {}) {
   return devtoolsRef.current;
 }
 
+// src/hooks/useBlockTransformer.ts
+import { useState as useState2, useCallback as useCallback2, useRef as useRef3, useEffect as useEffect2 } from "react";
+import {
+  createBlockTransformer
+} from "@incremark/core";
+function useBlockTransformer(sourceBlocks, options = {}) {
+  const [displayBlocks, setDisplayBlocks] = useState2([]);
+  const [isProcessing, setIsProcessing] = useState2(false);
+  const [isPaused, setIsPaused] = useState2(false);
+  const [effect, setEffect] = useState2(options.effect ?? "none");
+  const transformerRef = useRef3(null);
+  if (!transformerRef.current) {
+    transformerRef.current = createBlockTransformer({
+      ...options,
+      onChange: (blocks) => {
+        setDisplayBlocks(blocks);
+        setIsProcessing(transformerRef.current?.isProcessing() ?? false);
+        setIsPaused(transformerRef.current?.isPausedState() ?? false);
+      }
+    });
+  }
+  const transformer = transformerRef.current;
+  useEffect2(() => {
+    transformer.push(sourceBlocks);
+    const currentDisplaying = displayBlocks.find((b) => !b.isDisplayComplete);
+    if (currentDisplaying) {
+      const updated = sourceBlocks.find((b) => b.id === currentDisplaying.id);
+      if (updated) {
+        transformer.update(updated);
+      }
+    }
+  }, [sourceBlocks, transformer]);
+  useEffect2(() => {
+    return () => {
+      transformer.destroy();
+    };
+  }, [transformer]);
+  const skip = useCallback2(() => {
+    transformer.skip();
+  }, [transformer]);
+  const reset = useCallback2(() => {
+    transformer.reset();
+  }, [transformer]);
+  const pause = useCallback2(() => {
+    transformer.pause();
+    setIsPaused(true);
+  }, [transformer]);
+  const resume = useCallback2(() => {
+    transformer.resume();
+    setIsPaused(false);
+  }, [transformer]);
+  const setOptionsCallback = useCallback2(
+    (opts) => {
+      transformer.setOptions(opts);
+      if (opts.effect !== void 0) {
+        setEffect(opts.effect);
+      }
+    },
+    [transformer]
+  );
+  return {
+    displayBlocks,
+    isProcessing,
+    isPaused,
+    effect,
+    skip,
+    reset,
+    pause,
+    resume,
+    setOptions: setOptionsCallback,
+    transformer
+  };
+}
+
 // src/components/IncremarkRenderer.tsx
 import React from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
@@ -210,18 +284,176 @@ var Incremark = ({
   showBlockStatus = true,
   className = ""
 }) => {
-  return /* @__PURE__ */ jsx2("div", { className: `incremark ${className}`, children: blocks.map((block) => /* @__PURE__ */ jsx2(
-    "div",
-    {
-      className: `incremark-block ${showBlockStatus && block.status === "pending" ? "pending" : ""}`,
-      children: /* @__PURE__ */ jsx2(IncremarkRenderer, { node: block.node, components })
-    },
-    block.stableId
-  )) });
+  return /* @__PURE__ */ jsx2("div", { className: `incremark ${className}`, children: blocks.map((block) => {
+    const isPending = block.status === "pending";
+    const classes = [
+      "incremark-block",
+      isPending ? "incremark-pending" : "incremark-completed",
+      block.isLastPending ? "incremark-last-pending" : ""
+    ].filter(Boolean).join(" ");
+    return /* @__PURE__ */ jsx2("div", { className: classes, children: /* @__PURE__ */ jsx2(IncremarkRenderer, { node: block.node, components }) }, block.stableId);
+  }) });
 };
+
+// src/components/AutoScrollContainer.tsx
+import {
+  useRef as useRef4,
+  useEffect as useEffect3,
+  useCallback as useCallback3,
+  useState as useState3,
+  forwardRef,
+  useImperativeHandle
+} from "react";
+import { jsx as jsx3 } from "react/jsx-runtime";
+var AutoScrollContainer = forwardRef(
+  ({
+    children,
+    enabled = true,
+    threshold = 50,
+    behavior = "instant",
+    style,
+    className
+  }, ref) => {
+    const containerRef = useRef4(null);
+    const [isUserScrolledUp, setIsUserScrolledUp] = useState3(false);
+    const lastScrollTopRef = useRef4(0);
+    const lastScrollHeightRef = useRef4(0);
+    const isNearBottom = useCallback3(() => {
+      const container = containerRef.current;
+      if (!container) return true;
+      const { scrollTop, scrollHeight, clientHeight } = container;
+      return scrollHeight - scrollTop - clientHeight <= threshold;
+    }, [threshold]);
+    const scrollToBottom = useCallback3(
+      (force = false) => {
+        const container = containerRef.current;
+        if (!container) return;
+        if (isUserScrolledUp && !force) return;
+        container.scrollTo({
+          top: container.scrollHeight,
+          behavior
+        });
+      },
+      [isUserScrolledUp, behavior]
+    );
+    const hasScrollbar = useCallback3(() => {
+      const container = containerRef.current;
+      if (!container) return false;
+      return container.scrollHeight > container.clientHeight;
+    }, []);
+    const handleScroll = useCallback3(() => {
+      const container = containerRef.current;
+      if (!container) return;
+      const { scrollTop, scrollHeight, clientHeight } = container;
+      if (scrollHeight <= clientHeight) {
+        setIsUserScrolledUp(false);
+        lastScrollTopRef.current = 0;
+        lastScrollHeightRef.current = scrollHeight;
+        return;
+      }
+      if (isNearBottom()) {
+        setIsUserScrolledUp(false);
+      } else {
+        const isScrollingUp = scrollTop < lastScrollTopRef.current;
+        const isContentUnchanged = scrollHeight === lastScrollHeightRef.current;
+        if (isScrollingUp && isContentUnchanged) {
+          setIsUserScrolledUp(true);
+        }
+      }
+      lastScrollTopRef.current = scrollTop;
+      lastScrollHeightRef.current = scrollHeight;
+    }, [isNearBottom]);
+    useEffect3(() => {
+      const container = containerRef.current;
+      if (container) {
+        lastScrollTopRef.current = container.scrollTop;
+        lastScrollHeightRef.current = container.scrollHeight;
+      }
+    }, []);
+    useEffect3(() => {
+      const container = containerRef.current;
+      if (!container || !enabled) return;
+      const observer = new MutationObserver(() => {
+        requestAnimationFrame(() => {
+          if (!containerRef.current) return;
+          const { scrollHeight, clientHeight } = containerRef.current;
+          if (scrollHeight <= clientHeight) {
+            setIsUserScrolledUp(false);
+          }
+          lastScrollHeightRef.current = scrollHeight;
+          if (!isUserScrolledUp) {
+            scrollToBottom();
+          }
+        });
+      });
+      observer.observe(container, {
+        childList: true,
+        subtree: true,
+        characterData: true
+      });
+      return () => observer.disconnect();
+    }, [enabled, isUserScrolledUp, scrollToBottom]);
+    useImperativeHandle(
+      ref,
+      () => ({
+        scrollToBottom: () => scrollToBottom(true),
+        isUserScrolledUp: () => isUserScrolledUp,
+        container: containerRef.current
+      }),
+      [scrollToBottom, isUserScrolledUp]
+    );
+    return /* @__PURE__ */ jsx3(
+      "div",
+      {
+        ref: containerRef,
+        className,
+        style: {
+          overflowY: "auto",
+          height: "100%",
+          ...style
+        },
+        onScroll: handleScroll,
+        children
+      }
+    );
+  }
+);
+AutoScrollContainer.displayName = "AutoScrollContainer";
+
+// src/index.ts
+import {
+  BlockTransformer as BlockTransformer2,
+  createBlockTransformer as createBlockTransformer2,
+  countChars,
+  sliceAst,
+  cloneNode,
+  codeBlockPlugin,
+  mermaidPlugin,
+  imagePlugin,
+  mathPlugin,
+  thematicBreakPlugin,
+  defaultPlugins,
+  allPlugins,
+  createPlugin
+} from "@incremark/core";
 export {
+  AutoScrollContainer,
+  BlockTransformer2 as BlockTransformer,
   Incremark,
   IncremarkRenderer,
+  allPlugins,
+  cloneNode,
+  codeBlockPlugin,
+  countChars,
+  createBlockTransformer2 as createBlockTransformer,
+  createPlugin,
+  defaultPlugins,
+  imagePlugin,
+  mathPlugin,
+  mermaidPlugin,
+  sliceAst,
+  thematicBreakPlugin,
+  useBlockTransformer,
   useDevTools,
   useIncremark
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@incremark/react",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "license": "MIT",
   "description": "Incremark React integration - Incremental Markdown parser for AI streaming",
   "type": "module",
@@ -19,10 +19,10 @@
   ],
   "peerDependencies": {
     "react": ">=18.0.0",
-    "@incremark/core": "0.0.4"
+    "@incremark/core": "0.0.5"
   },
   "dependencies": {
-    "@incremark/devtools": "0.0.4"
+    "@incremark/devtools": "0.0.5"
   },
   "devDependencies": {
     "@types/react": "^18.2.0",