@incremark/react 0.0.5 → 0.1.2

package/dist/index.d.ts

@@ -1,32 +1,85 @@
-import { ParserOptions, ParsedBlock, Root, IncrementalUpdate, IncremarkParser, SourceBlock, TransformerOptions, DisplayBlock, AnimationEffect, BlockTransformer, RootContent } from '@incremark/core';
+import { ParserOptions, AnimationEffect, TransformerPlugin, ParsedBlock, Root, IncrementalUpdate, IncremarkParser, SourceBlock, TransformerOptions, DisplayBlock, 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';
 
+/** 打字机效果配置 */
+interface TypewriterOptions {
+    /** 是否启用打字机效果（可动态切换） */
+    enabled?: boolean;
+    /** 每次显示的字符数，可以是固定值或范围 [min, max] */
+    charsPerTick?: number | [number, number];
+    /** 更新间隔 (ms) */
+    tickInterval?: number;
+    /** 动画效果: 'none' | 'fade-in' | 'typing' */
+    effect?: AnimationEffect;
+    /** 光标字符（仅 typing 效果使用） */
+    cursor?: string;
+    /** 页面不可见时暂停 */
+    pauseOnHidden?: boolean;
+    /** 自定义插件 */
+    plugins?: TransformerPlugin[];
+}
 interface UseIncremarkOptions extends ParserOptions {
+    /** 打字机配置，传入即创建 transformer（可通过 enabled 控制是否启用） */
+    typewriter?: TypewriterOptions;
 }
 interface BlockWithStableId$1 extends ParsedBlock {
     stableId: string;
 }
+/** 打字机控制对象 */
+interface TypewriterControls {
+    /** 是否启用 */
+    enabled: boolean;
+    /** 设置启用状态 */
+    setEnabled: (enabled: boolean) => void;
+    /** 是否正在处理中 */
+    isProcessing: boolean;
+    /** 是否已暂停 */
+    isPaused: boolean;
+    /** 当前动画效果 */
+    effect: AnimationEffect;
+    /** 跳过动画，直接显示全部 */
+    skip: () => void;
+    /** 暂停动画 */
+    pause: () => void;
+    /** 恢复动画 */
+    resume: () => void;
+    /** 动态更新配置 */
+    setOptions: (options: Partial<TypewriterOptions>) => void;
+}
 /**
  * React Hook: Incremark 流式 Markdown 解析器
  *
  * @example
  * ```tsx
- * import { useIncremark } from '@incremark/react'
+ * import { useIncremark, Incremark } from '@incremark/react'
  *
  * function App() {
- *   const { markdown, blocks, append, finalize, reset } = useIncremark()
+ *   // 基础用法
+ *   const { blocks, append, finalize } = useIncremark()
  *
- *   async function handleStream(stream) {
- *     for await (const chunk of stream) {
- *       append(chunk)
+ *   // 启用打字机效果
+ *   const { blocks, append, finalize, typewriter } = useIncremark({
+ *     typewriter: {
+ *       enabled: true,       // 可动态切换
+ *       charsPerTick: [1, 3],
+ *       tickInterval: 30,
+ *       effect: 'typing',
+ *       cursor: '|'
  *     }
- *     finalize()
- *   }
+ *   })
+ *
+ *   // 动态切换打字机效果
+ *   typewriter.setEnabled(false)
  *
- *   return <div>{markdown.length} 字符</div>
+ *   return (
+ *     <>
+ *       <Incremark blocks={blocks} />
+ *       {typewriter.isProcessing && <button onClick={typewriter.skip}>跳过</button>}
+ *     </>
+ *   )
  * }
  * ```
  */
@@ -39,7 +92,7 @@ declare function useIncremark(options?: UseIncremarkOptions): {
     pendingBlocks: ParsedBlock[];
     /** 当前完整的 AST */
     ast: Root;
-    /** 所有块（完成 + 待处理），带稳定 ID */
+    /** 用于渲染的 blocks（根据打字机设置自动处理） */
     blocks: BlockWithStableId$1[];
     /** 是否正在加载 */
     isLoading: boolean;
@@ -49,12 +102,14 @@ declare function useIncremark(options?: UseIncremarkOptions): {
     finalize: () => IncrementalUpdate;
     /** 强制中断 */
     abort: () => IncrementalUpdate;
-    /** 重置解析器 */
+    /** 重置解析器和打字机 */
     reset: () => void;
     /** 一次性渲染（reset + append + finalize） */
     render: (content: string) => IncrementalUpdate;
     /** 解析器实例 */
     parser: IncremarkParser;
+    /** 打字机控制 */
+    typewriter: TypewriterControls;
 };
 type UseIncremarkReturn = ReturnType<typeof useIncremark>;
 
@@ -180,7 +235,7 @@ declare const Incremark: React.FC<IncremarkProps>;
 interface IncremarkRendererProps {
     node: RootContent;
     components?: Partial<Record<string, React.ComponentType<{
-        node: any;
+        node: RootContent;
     }>>>;
 }
 /**
@@ -230,4 +285,4 @@ interface AutoScrollContainerRef {
  */
 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 };
+export { AutoScrollContainer, type AutoScrollContainerProps, type AutoScrollContainerRef, Incremark, type IncremarkProps, IncremarkRenderer, type IncremarkRendererProps, type TypewriterControls, type TypewriterOptions, type UseBlockTransformerOptions, type UseBlockTransformerReturn, type UseDevToolsOptions, type UseIncremarkOptions, type UseIncremarkReturn, useBlockTransformer, useDevTools, useIncremark };

package/dist/index.js

@@ -1,31 +1,125 @@
 // src/hooks/useIncremark.ts
-import { useState, useCallback, useMemo, useRef } from "react";
+import { useState, useCallback, useMemo, useRef, useEffect } from "react";
 import {
-  createIncremarkParser
+  createIncremarkParser,
+  createBlockTransformer,
+  defaultPlugins
 } from "@incremark/core";
 function useIncremark(options = {}) {
   const parserRef = useRef(null);
+  const transformerRef = useRef(null);
+  const hasTypewriterConfig = !!options.typewriter;
+  const cursorRef = useRef(options.typewriter?.cursor ?? "|");
   if (!parserRef.current) {
     parserRef.current = createIncremarkParser(options);
   }
+  if (hasTypewriterConfig && !transformerRef.current) {
+    const twOptions = options.typewriter;
+    transformerRef.current = createBlockTransformer({
+      charsPerTick: twOptions.charsPerTick ?? [1, 3],
+      tickInterval: twOptions.tickInterval ?? 30,
+      effect: twOptions.effect ?? "none",
+      pauseOnHidden: twOptions.pauseOnHidden ?? true,
+      plugins: twOptions.plugins ?? defaultPlugins,
+      onChange: () => {
+        setForceUpdateCount((c) => c + 1);
+      }
+    });
+  }
   const parser = parserRef.current;
+  const transformer = transformerRef.current;
   const [markdown, setMarkdown] = useState("");
   const [completedBlocks, setCompletedBlocks] = useState([]);
   const [pendingBlocks, setPendingBlocks] = useState([]);
   const [isLoading, setIsLoading] = useState(false);
-  const blocks = useMemo(() => {
-    const result = [];
-    for (const block of completedBlocks) {
-      result.push({ ...block, stableId: block.id });
+  const [forceUpdateCount, setForceUpdateCount] = useState(0);
+  const [typewriterEnabled, setTypewriterEnabled] = useState(options.typewriter?.enabled ?? hasTypewriterConfig);
+  const [isTypewriterProcessing, setIsTypewriterProcessing] = useState(false);
+  const [isTypewriterPaused, setIsTypewriterPaused] = useState(false);
+  const [typewriterEffect, setTypewriterEffect] = useState(
+    options.typewriter?.effect ?? "none"
+  );
+  const sourceBlocks = useMemo(
+    () => completedBlocks.map((block) => ({
+      id: block.id,
+      node: block.node,
+      status: block.status
+    })),
+    [completedBlocks]
+  );
+  useEffect(() => {
+    if (!transformer) return;
+    transformer.push(sourceBlocks);
+    const displayBlocks = transformer.getDisplayBlocks();
+    const currentDisplaying = displayBlocks.find((b) => !b.isDisplayComplete);
+    if (currentDisplaying) {
+      const updated = sourceBlocks.find((b) => b.id === currentDisplaying.id);
+      if (updated) {
+        transformer.update(updated);
+      }
     }
-    for (let i = 0; i < pendingBlocks.length; i++) {
-      result.push({
-        ...pendingBlocks[i],
-        stableId: `pending-${i}`
-      });
+    setIsTypewriterProcessing(transformer.isProcessing());
+    setIsTypewriterPaused(transformer.isPausedState());
+  }, [sourceBlocks, transformer]);
+  const addCursorToNode = useCallback((node, cursor) => {
+    const cloned = JSON.parse(JSON.stringify(node));
+    function addToLast(n) {
+      if (n.children && n.children.length > 0) {
+        for (let i = n.children.length - 1; i >= 0; i--) {
+          if (addToLast(n.children[i])) {
+            return true;
+          }
+        }
+        n.children.push({ type: "text", value: cursor });
+        return true;
+      }
+      if (n.type === "text" && typeof n.value === "string") {
+        n.value += cursor;
+        return true;
+      }
+      if (typeof n.value === "string") {
+        n.value += cursor;
+        return true;
+      }
+      return false;
     }
-    return result;
-  }, [completedBlocks, pendingBlocks]);
+    addToLast(cloned);
+    return cloned;
+  }, []);
+  const blocks = useMemo(() => {
+    if (!typewriterEnabled || !transformer) {
+      const result = [];
+      for (const block of completedBlocks) {
+        result.push({ ...block, stableId: block.id });
+      }
+      for (let i = 0; i < pendingBlocks.length; i++) {
+        result.push({
+          ...pendingBlocks[i],
+          stableId: `pending-${i}`
+        });
+      }
+      return result;
+    }
+    const displayBlocks = transformer.getDisplayBlocks();
+    return displayBlocks.map((db, index) => {
+      const isPending = !db.isDisplayComplete;
+      const isLastPending = isPending && index === displayBlocks.length - 1;
+      let node = db.displayNode;
+      if (typewriterEffect === "typing" && isLastPending) {
+        node = addCursorToNode(db.displayNode, cursorRef.current);
+      }
+      return {
+        id: db.id,
+        stableId: db.id,
+        status: db.isDisplayComplete ? "completed" : "pending",
+        isLastPending,
+        node,
+        startOffset: 0,
+        endOffset: 0,
+        rawText: ""
+      };
+    });
+  }, [completedBlocks, pendingBlocks, typewriterEnabled, typewriterEffect, addCursorToNode, forceUpdateCount]);
   const ast = useMemo(
     () => ({
       type: "root",
@@ -65,7 +159,8 @@ function useIncremark(options = {}) {
     setPendingBlocks([]);
     setMarkdown("");
     setIsLoading(false);
-  }, [parser]);
+    transformer?.reset();
+  }, [parser, transformer]);
   const render = useCallback(
     (content) => {
       const update = parser.render(content);
@@ -77,6 +172,59 @@ function useIncremark(options = {}) {
     },
     [parser]
   );
+  const skip = useCallback(() => {
+    transformer?.skip();
+    setIsTypewriterProcessing(false);
+  }, [transformer]);
+  const pause = useCallback(() => {
+    transformer?.pause();
+    setIsTypewriterPaused(true);
+  }, [transformer]);
+  const resume = useCallback(() => {
+    transformer?.resume();
+    setIsTypewriterPaused(false);
+  }, [transformer]);
+  const setTypewriterOptions = useCallback(
+    (opts) => {
+      if (opts.enabled !== void 0) {
+        setTypewriterEnabled(opts.enabled);
+      }
+      if (opts.charsPerTick !== void 0 || opts.tickInterval !== void 0 || opts.effect !== void 0 || opts.pauseOnHidden !== void 0) {
+        transformer?.setOptions({
+          charsPerTick: opts.charsPerTick,
+          tickInterval: opts.tickInterval,
+          effect: opts.effect,
+          pauseOnHidden: opts.pauseOnHidden
+        });
+      }
+      if (opts.effect !== void 0) {
+        setTypewriterEffect(opts.effect);
+      }
+      if (opts.cursor !== void 0) {
+        cursorRef.current = opts.cursor;
+      }
+    },
+    [transformer]
+  );
+  const typewriter = useMemo(
+    () => ({
+      enabled: typewriterEnabled,
+      setEnabled: setTypewriterEnabled,
+      isProcessing: isTypewriterProcessing,
+      isPaused: isTypewriterPaused,
+      effect: typewriterEffect,
+      skip,
+      pause,
+      resume,
+      setOptions: setTypewriterOptions
+    }),
+    [typewriterEnabled, isTypewriterProcessing, isTypewriterPaused, typewriterEffect, skip, pause, resume, setTypewriterOptions]
+  );
+  useEffect(() => {
+    return () => {
+      transformer?.destroy();
+    };
+  }, [transformer]);
   return {
     /** 已收集的完整 Markdown 字符串 */
     markdown,
@@ -86,7 +234,7 @@ function useIncremark(options = {}) {
     pendingBlocks,
     /** 当前完整的 AST */
     ast,
-    /** 所有块（完成 + 待处理），带稳定 ID */
+    /** 用于渲染的 blocks（根据打字机设置自动处理） */
     blocks,
     /** 是否正在加载 */
     isLoading,
@@ -96,22 +244,24 @@ function useIncremark(options = {}) {
     finalize,
     /** 强制中断 */
     abort,
-    /** 重置解析器 */
+    /** 重置解析器和打字机 */
     reset,
     /** 一次性渲染（reset + append + finalize） */
     render,
     /** 解析器实例 */
-    parser
+    parser,
+    /** 打字机控制 */
+    typewriter
   };
 }
 
 // src/hooks/useDevTools.ts
-import { useEffect, useRef as useRef2 } from "react";
+import { useEffect as useEffect2, useRef as useRef2 } from "react";
 import { createDevTools } from "@incremark/devtools";
 function useDevTools(incremark, options = {}) {
   const devtoolsRef = useRef2(null);
   const optionsRef = useRef2(options);
-  useEffect(() => {
+  useEffect2(() => {
     const devtools = createDevTools(optionsRef.current);
     devtoolsRef.current = devtools;
     incremark.parser.setOnChange((state) => {
@@ -138,9 +288,9 @@ function useDevTools(incremark, options = {}) {
 }
 
 // src/hooks/useBlockTransformer.ts
-import { useState as useState2, useCallback as useCallback2, useRef as useRef3, useEffect as useEffect2 } from "react";
+import { useState as useState2, useCallback as useCallback2, useRef as useRef3, useEffect as useEffect3 } from "react";
 import {
-  createBlockTransformer
+  createBlockTransformer as createBlockTransformer2
 } from "@incremark/core";
 function useBlockTransformer(sourceBlocks, options = {}) {
   const [displayBlocks, setDisplayBlocks] = useState2([]);
@@ -149,7 +299,7 @@ function useBlockTransformer(sourceBlocks, options = {}) {
   const [effect, setEffect] = useState2(options.effect ?? "none");
   const transformerRef = useRef3(null);
   if (!transformerRef.current) {
-    transformerRef.current = createBlockTransformer({
+    transformerRef.current = createBlockTransformer2({
       ...options,
       onChange: (blocks) => {
         setDisplayBlocks(blocks);
@@ -159,7 +309,7 @@ function useBlockTransformer(sourceBlocks, options = {}) {
     });
   }
   const transformer = transformerRef.current;
-  useEffect2(() => {
+  useEffect3(() => {
     transformer.push(sourceBlocks);
     const currentDisplaying = displayBlocks.find((b) => !b.isDisplayComplete);
     if (currentDisplaying) {
@@ -169,7 +319,7 @@ function useBlockTransformer(sourceBlocks, options = {}) {
       }
     }
   }, [sourceBlocks, transformer]);
-  useEffect2(() => {
+  useEffect3(() => {
     return () => {
       transformer.destroy();
     };
@@ -214,12 +364,26 @@ function useBlockTransformer(sourceBlocks, options = {}) {
 // src/components/IncremarkRenderer.tsx
 import React from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
+function getStableText(node) {
+  if (!node.chunks || node.chunks.length === 0) {
+    return node.value;
+  }
+  return node.value.slice(0, node.stableLength ?? 0);
+}
 function renderInlineChildren(children) {
   if (!children) return null;
   return children.map((child, i) => {
     switch (child.type) {
-      case "text":
-        return /* @__PURE__ */ jsx(React.Fragment, { children: child.value }, i);
+      case "text": {
+        const textNode = child;
+        if (textNode.chunks && textNode.chunks.length > 0) {
+          return /* @__PURE__ */ jsxs(React.Fragment, { children: [
+            getStableText(textNode),
+            textNode.chunks.map((chunk) => /* @__PURE__ */ jsx("span", { className: "incremark-fade-in", children: chunk.text }, chunk.createdAt))
+          ] }, i);
+        }
+        return /* @__PURE__ */ jsx(React.Fragment, { children: textNode.value }, i);
+      }
       case "strong":
         return /* @__PURE__ */ jsx("strong", { children: renderInlineChildren(child.children) }, i);
       case "emphasis":
@@ -236,6 +400,8 @@ function renderInlineChildren(children) {
         return /* @__PURE__ */ jsx("del", { children: renderInlineChildren(child.children) }, i);
       case "paragraph":
         return /* @__PURE__ */ jsx(React.Fragment, { children: renderInlineChildren(child.children) }, i);
+      case "html":
+        return /* @__PURE__ */ jsx("span", { dangerouslySetInnerHTML: { __html: child.value } }, i);
       default:
         return /* @__PURE__ */ jsx("span", { children: child.value || "" }, i);
     }
@@ -254,7 +420,7 @@ var DefaultList = ({ node }) => {
   const Tag = node.ordered ? "ol" : "ul";
   return /* @__PURE__ */ jsx(Tag, { className: "incremark-list", children: node.children?.map((item, i) => /* @__PURE__ */ jsx("li", { children: renderInlineChildren(item.children) }, i)) });
 };
-var DefaultBlockquote = ({ node }) => /* @__PURE__ */ jsx("blockquote", { className: "incremark-blockquote", children: node.children?.map((child, i) => /* @__PURE__ */ jsx(React.Fragment, { children: child.type === "paragraph" ? /* @__PURE__ */ jsx("p", { children: renderInlineChildren(child.children) }) : renderInlineChildren(child.children || []) }, i)) });
+var DefaultBlockquote = ({ node }) => /* @__PURE__ */ jsx("blockquote", { className: "incremark-blockquote", children: node.children?.map((child, i) => /* @__PURE__ */ jsx(React.Fragment, { children: child.type === "paragraph" ? /* @__PURE__ */ jsx("p", { children: renderInlineChildren(child.children) }) : "children" in child && Array.isArray(child.children) ? renderInlineChildren(child.children) : null }, i)) });
 var DefaultTable = ({ node }) => /* @__PURE__ */ jsx("div", { className: "incremark-table-wrapper", children: /* @__PURE__ */ jsxs("table", { className: "incremark-table", children: [
   /* @__PURE__ */ jsx("thead", { children: node.children?.[0] && /* @__PURE__ */ jsx("tr", { children: node.children[0].children?.map((cell, i) => /* @__PURE__ */ jsx("th", { children: renderInlineChildren(cell.children) }, i)) }) }),
   /* @__PURE__ */ jsx("tbody", { children: node.children?.slice(1).map((row, i) => /* @__PURE__ */ jsx("tr", { children: row.children?.map((cell, j) => /* @__PURE__ */ jsx("td", { children: renderInlineChildren(cell.children) }, j)) }, i)) })
@@ -298,7 +464,7 @@ var Incremark = ({
 // src/components/AutoScrollContainer.tsx
 import {
   useRef as useRef4,
-  useEffect as useEffect3,
+  useEffect as useEffect4,
   useCallback as useCallback3,
   useState as useState3,
   forwardRef,
@@ -363,14 +529,14 @@ var AutoScrollContainer = forwardRef(
       lastScrollTopRef.current = scrollTop;
       lastScrollHeightRef.current = scrollHeight;
     }, [isNearBottom]);
-    useEffect3(() => {
+    useEffect4(() => {
       const container = containerRef.current;
       if (container) {
         lastScrollTopRef.current = container.scrollTop;
         lastScrollHeightRef.current = container.scrollHeight;
       }
     }, []);
-    useEffect3(() => {
+    useEffect4(() => {
       const container = containerRef.current;
       if (!container || !enabled) return;
       const observer = new MutationObserver(() => {
@@ -423,7 +589,7 @@ AutoScrollContainer.displayName = "AutoScrollContainer";
 // src/index.ts
 import {
   BlockTransformer as BlockTransformer2,
-  createBlockTransformer as createBlockTransformer2,
+  createBlockTransformer as createBlockTransformer3,
   countChars,
   sliceAst,
   cloneNode,
@@ -432,7 +598,7 @@ import {
   imagePlugin,
   mathPlugin,
   thematicBreakPlugin,
-  defaultPlugins,
+  defaultPlugins as defaultPlugins2,
   allPlugins,
   createPlugin
 } from "@incremark/core";
@@ -445,9 +611,9 @@ export {
   cloneNode,
   codeBlockPlugin,
   countChars,
-  createBlockTransformer2 as createBlockTransformer,
+  createBlockTransformer3 as createBlockTransformer,
   createPlugin,
-  defaultPlugins,
+  defaultPlugins2 as defaultPlugins,
   imagePlugin,
   mathPlugin,
   mermaidPlugin,

package/dist/styles.css

@@ -189,3 +189,18 @@
   font-size: 11px;
 }
 
+/* ============ 渐入动画效果 ============ */
+
+.incremark-fade-in {
+  animation: incremark-fade-in 0.4s ease-out;
+}
+
+@keyframes incremark-fade-in {
+  from {
+    opacity: 0;
+  }
+  to {
+    opacity: 1;
+  }
+}
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@incremark/react",
-  "version": "0.0.5",
+  "version": "0.1.2",
   "license": "MIT",
   "description": "Incremark React integration - Incremental Markdown parser for AI streaming",
   "type": "module",
@@ -19,12 +19,13 @@
   ],
   "peerDependencies": {
     "react": ">=18.0.0",
-    "@incremark/core": "0.0.5"
+    "@incremark/core": "0.1.2"
   },
   "dependencies": {
-    "@incremark/devtools": "0.0.5"
+    "@incremark/devtools": "0.1.2"
   },
   "devDependencies": {
+    "@types/mdast": "^4.0.0",
     "@types/react": "^18.2.0",
     "react": "^18.2.0",
     "tsup": "^8.0.0",
@@ -35,7 +36,7 @@
     "url": "https://github.com/kingshuaishuai/incremark.git",
     "directory": "packages/react"
   },
-  "homepage": "https://incremark-docs.vercel.app/",
+  "homepage": "https://www.incremark.com/",
   "scripts": {
     "build": "tsup && cp src/styles.css dist/styles.css",
     "dev": "tsup --watch"