@incremark/react 0.0.1

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 wangyishuai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,137 @@
+# @incremark/react
+
+Incremark 的 React 18+ 集成库。
+
+## 特性
+
+- 📦 **开箱即用** - 提供 `useIncremark` hook 和 `<Incremark>` 组件
+- 🎨 **可定制** - 支持自定义渲染组件
+- ⚡ **高性能** - 利用 React 的 reconciliation 机制
+- 🔧 **DevTools** - 内置开发者工具
+
+## 安装
+
+```bash
+pnpm add @incremark/core @incremark/react
+```
+
+## 快速开始
+
+```tsx
+import { useIncremark, Incremark } from '@incremark/react'
+
+function App() {
+  const { blocks, append, finalize, reset } = useIncremark({ gfm: true })
+
+  async function handleStream(stream: ReadableStream) {
+    reset()
+    const reader = stream.getReader()
+    const decoder = new TextDecoder()
+    
+    while (true) {
+      const { done, value } = await reader.read()
+      if (done) break
+      append(decoder.decode(value))
+    }
+    
+    finalize()
+  }
+
+  return (
+    <>
+      <button onClick={() => handleStream(stream)}>开始</button>
+      <Incremark blocks={blocks} />
+    </>
+  )
+}
+```
+
+## API
+
+### useIncremark(options)
+
+核心 hook。
+
+**返回值：**
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `markdown` | `string` | 完整 Markdown |
+| `blocks` | `Block[]` | 所有块 |
+| `completedBlocks` | `Block[]` | 已完成块 |
+| `pendingBlocks` | `Block[]` | 待处理块 |
+| `append` | `Function` | 追加内容 |
+| `finalize` | `Function` | 完成解析 |
+| `reset` | `Function` | 重置状态 |
+
+### useDevTools(incremark)
+
+启用 DevTools。
+
+```tsx
+const incremark = useIncremark()
+useDevTools(incremark)
+```
+
+### \<Incremark\>
+
+渲染组件。
+
+```tsx
+<Incremark 
+  blocks={blocks}
+  components={{ heading: MyHeading }}
+/>
+```
+
+## 自定义组件
+
+```tsx
+import { useIncremark, Incremark } from '@incremark/react'
+import MyCode from './MyCode'
+
+function App() {
+  const { blocks } = useIncremark()
+  
+  return (
+    <Incremark 
+      blocks={blocks} 
+      components={{ code: MyCode }}
+    />
+  )
+}
+```
+
+## 与 React Query 集成
+
+```tsx
+import { useQuery } from '@tanstack/react-query'
+import { useIncremark, Incremark } from '@incremark/react'
+
+function StreamingContent() {
+  const { blocks, append, finalize, reset } = useIncremark()
+  
+  const { refetch } = useQuery({
+    queryKey: ['chat'],
+    queryFn: async () => {
+      reset()
+      // ... 流式处理
+      finalize()
+      return null
+    },
+    enabled: false
+  })
+
+  return (
+    <>
+      <button onClick={() => refetch()}>开始</button>
+      <Incremark blocks={blocks} />
+    </>
+  )
+}
+```
+
+## License
+
+MIT
+

package/dist/index.d.ts

@@ -0,0 +1,119 @@
+import { ParserOptions, ParsedBlock, Root, IncrementalUpdate, IncremarkParser, RootContent } from '@incremark/core';
+export { IncrementalUpdate, ParsedBlock, ParserOptions, Root, RootContent } from '@incremark/core';
+import * as _incremark_devtools from '@incremark/devtools';
+import { DevToolsOptions } from '@incremark/devtools';
+import React from 'react';
+
+interface UseIncremarkOptions extends ParserOptions {
+}
+interface BlockWithStableId$1 extends ParsedBlock {
+    stableId: string;
+}
+/**
+ * React Hook: Incremark 流式 Markdown 解析器
+ *
+ * @example
+ * ```tsx
+ * import { useIncremark } from '@incremark/react'
+ *
+ * function App() {
+ *   const { markdown, blocks, append, finalize, reset } = useIncremark()
+ *
+ *   async function handleStream(stream) {
+ *     for await (const chunk of stream) {
+ *       append(chunk)
+ *     }
+ *     finalize()
+ *   }
+ *
+ *   return <div>{markdown.length} 字符</div>
+ * }
+ * ```
+ */
+declare function useIncremark(options?: UseIncremarkOptions): {
+    /** 已收集的完整 Markdown 字符串 */
+    markdown: string;
+    /** 已完成的块列表 */
+    completedBlocks: ParsedBlock[];
+    /** 待处理的块列表 */
+    pendingBlocks: ParsedBlock[];
+    /** 当前完整的 AST */
+    ast: Root;
+    /** 所有块（完成 + 待处理），带稳定 ID */
+    blocks: BlockWithStableId$1[];
+    /** 是否正在加载 */
+    isLoading: boolean;
+    /** 追加内容 */
+    append: (chunk: string) => IncrementalUpdate;
+    /** 完成解析 */
+    finalize: () => IncrementalUpdate;
+    /** 强制中断 */
+    abort: () => IncrementalUpdate;
+    /** 重置解析器 */
+    reset: () => void;
+    /** 解析器实例 */
+    parser: IncremarkParser;
+};
+type UseIncremarkReturn = ReturnType<typeof useIncremark>;
+
+interface UseDevToolsOptions extends DevToolsOptions {
+}
+/**
+ * React DevTools 一行接入
+ *
+ * @example
+ * ```tsx
+ * import { useIncremark, useDevTools } from '@incremark/react'
+ *
+ * function App() {
+ *   const incremark = useIncremark()
+ *   useDevTools(incremark)  // 就这一行！
+ *
+ *   return <div>...</div>
+ * }
+ * ```
+ */
+declare function useDevTools(incremark: UseIncremarkReturn, options?: UseDevToolsOptions): _incremark_devtools.IncremarkDevTools | null;
+
+interface BlockWithStableId extends ParsedBlock {
+    stableId: string;
+}
+interface IncremarkProps {
+    /** 要渲染的块列表 */
+    blocks: BlockWithStableId[];
+    /** 自定义组件映射 */
+    components?: Partial<Record<string, React.ComponentType<{
+        node: any;
+    }>>>;
+    /** 是否显示块状态（待处理块边框） */
+    showBlockStatus?: boolean;
+    /** 自定义类名 */
+    className?: string;
+}
+/**
+ * Incremark 主渲染组件
+ *
+ * @example
+ * ```tsx
+ * import { useIncremark, Incremark } from '@incremark/react'
+ *
+ * function App() {
+ *   const { blocks } = useIncremark()
+ *   return <Incremark blocks={blocks} />
+ * }
+ * ```
+ */
+declare const Incremark: React.FC<IncremarkProps>;
+
+interface IncremarkRendererProps {
+    node: RootContent;
+    components?: Partial<Record<string, React.ComponentType<{
+        node: any;
+    }>>>;
+}
+/**
+ * 渲染单个 AST 节点
+ */
+declare const IncremarkRenderer: React.FC<IncremarkRendererProps>;
+
+export { Incremark, type IncremarkProps, IncremarkRenderer, type IncremarkRendererProps, type UseDevToolsOptions, type UseIncremarkOptions, type UseIncremarkReturn, useDevTools, useIncremark };

package/dist/index.js

@@ -0,0 +1,214 @@
+// src/hooks/useIncremark.ts
+import { useState, useCallback, useMemo, useRef } from "react";
+import {
+  createIncremarkParser
+} from "@incremark/core";
+function useIncremark(options = {}) {
+  const parserRef = useRef(null);
+  if (!parserRef.current) {
+    parserRef.current = createIncremarkParser(options);
+  }
+  const parser = parserRef.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 });
+    }
+    for (let i = 0; i < pendingBlocks.length; i++) {
+      result.push({
+        ...pendingBlocks[i],
+        stableId: `pending-${i}`
+      });
+    }
+    return result;
+  }, [completedBlocks, pendingBlocks]);
+  const ast = useMemo(
+    () => ({
+      type: "root",
+      children: [...completedBlocks.map((b) => b.node), ...pendingBlocks.map((b) => b.node)]
+    }),
+    [completedBlocks, pendingBlocks]
+  );
+  const append = useCallback(
+    (chunk) => {
+      setIsLoading(true);
+      const update = parser.append(chunk);
+      setMarkdown(parser.getBuffer());
+      if (update.completed.length > 0) {
+        setCompletedBlocks((prev) => [...prev, ...update.completed]);
+      }
+      setPendingBlocks(update.pending);
+      return update;
+    },
+    [parser]
+  );
+  const finalize = useCallback(() => {
+    const update = parser.finalize();
+    setMarkdown(parser.getBuffer());
+    if (update.completed.length > 0) {
+      setCompletedBlocks((prev) => [...prev, ...update.completed]);
+    }
+    setPendingBlocks([]);
+    setIsLoading(false);
+    return update;
+  }, [parser]);
+  const abort = useCallback(() => {
+    return finalize();
+  }, [finalize]);
+  const reset = useCallback(() => {
+    parser.reset();
+    setCompletedBlocks([]);
+    setPendingBlocks([]);
+    setMarkdown("");
+    setIsLoading(false);
+  }, [parser]);
+  return {
+    /** 已收集的完整 Markdown 字符串 */
+    markdown,
+    /** 已完成的块列表 */
+    completedBlocks,
+    /** 待处理的块列表 */
+    pendingBlocks,
+    /** 当前完整的 AST */
+    ast,
+    /** 所有块（完成 + 待处理），带稳定 ID */
+    blocks,
+    /** 是否正在加载 */
+    isLoading,
+    /** 追加内容 */
+    append,
+    /** 完成解析 */
+    finalize,
+    /** 强制中断 */
+    abort,
+    /** 重置解析器 */
+    reset,
+    /** 解析器实例 */
+    parser
+  };
+}
+
+// src/hooks/useDevTools.ts
+import { useEffect, useRef as useRef2 } from "react";
+import { createDevTools } from "@incremark/devtools";
+function useDevTools(incremark, options = {}) {
+  const devtoolsRef = useRef2(null);
+  const optionsRef = useRef2(options);
+  useEffect(() => {
+    const devtools = createDevTools(optionsRef.current);
+    devtoolsRef.current = devtools;
+    incremark.parser.setOnChange((state) => {
+      const blocks = [
+        ...state.completedBlocks.map((b) => ({ ...b, stableId: b.id })),
+        ...state.pendingBlocks.map((b, i) => ({ ...b, stableId: `pending-${i}` }))
+      ];
+      devtools.update({
+        blocks,
+        completedBlocks: state.completedBlocks,
+        pendingBlocks: state.pendingBlocks,
+        markdown: state.markdown,
+        ast: state.ast,
+        isLoading: state.pendingBlocks.length > 0
+      });
+    });
+    devtools.mount();
+    return () => {
+      devtools.unmount();
+      incremark.parser.setOnChange(void 0);
+    };
+  }, [incremark.parser]);
+  return devtoolsRef.current;
+}
+
+// src/components/IncremarkRenderer.tsx
+import React from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+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 "strong":
+        return /* @__PURE__ */ jsx("strong", { children: renderInlineChildren(child.children) }, i);
+      case "emphasis":
+        return /* @__PURE__ */ jsx("em", { children: renderInlineChildren(child.children) }, i);
+      case "inlineCode":
+        return /* @__PURE__ */ jsx("code", { className: "incremark-inline-code", children: child.value }, i);
+      case "link":
+        return /* @__PURE__ */ jsx("a", { href: child.url, target: "_blank", rel: "noopener noreferrer", children: renderInlineChildren(child.children) }, i);
+      case "image":
+        return /* @__PURE__ */ jsx("img", { src: child.url, alt: child.alt || "", loading: "lazy" }, i);
+      case "break":
+        return /* @__PURE__ */ jsx("br", {}, i);
+      case "delete":
+        return /* @__PURE__ */ jsx("del", { children: renderInlineChildren(child.children) }, i);
+      case "paragraph":
+        return /* @__PURE__ */ jsx(React.Fragment, { children: renderInlineChildren(child.children) }, i);
+      default:
+        return /* @__PURE__ */ jsx("span", { children: child.value || "" }, i);
+    }
+  });
+}
+var DefaultHeading = ({ node }) => {
+  const Tag = `h${node.depth}`;
+  return /* @__PURE__ */ jsx(Tag, { className: "incremark-heading", children: renderInlineChildren(node.children) });
+};
+var DefaultParagraph = ({ node }) => /* @__PURE__ */ jsx("p", { className: "incremark-paragraph", children: renderInlineChildren(node.children) });
+var DefaultCode = ({ node }) => /* @__PURE__ */ jsxs("div", { className: "incremark-code", children: [
+  /* @__PURE__ */ jsx("div", { className: "code-header", children: /* @__PURE__ */ jsx("span", { className: "language", children: node.lang || "text" }) }),
+  /* @__PURE__ */ jsx("pre", { children: /* @__PURE__ */ jsx("code", { children: node.value }) })
+] });
+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 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)) })
+] }) });
+var DefaultThematicBreak = () => /* @__PURE__ */ jsx("hr", { className: "incremark-hr" });
+var DefaultDefault = ({ node }) => /* @__PURE__ */ jsx("div", { className: "incremark-unknown", "data-type": node.type, children: /* @__PURE__ */ jsx("pre", { children: JSON.stringify(node, null, 2) }) });
+var defaultComponents = {
+  heading: DefaultHeading,
+  paragraph: DefaultParagraph,
+  code: DefaultCode,
+  list: DefaultList,
+  blockquote: DefaultBlockquote,
+  table: DefaultTable,
+  thematicBreak: DefaultThematicBreak
+};
+var IncremarkRenderer = ({ node, components = {} }) => {
+  const mergedComponents = { ...defaultComponents, ...components };
+  const Component = mergedComponents[node.type] || DefaultDefault;
+  return /* @__PURE__ */ jsx(Component, { node });
+};
+
+// src/components/Incremark.tsx
+import { jsx as jsx2 } from "react/jsx-runtime";
+var Incremark = ({
+  blocks,
+  components,
+  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
+  )) });
+};
+export {
+  Incremark,
+  IncremarkRenderer,
+  useDevTools,
+  useIncremark
+};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@incremark/react",
+  "version": "0.0.1",
+  "license": "MIT",
+  "description": "Incremark React integration - Incremental Markdown parser for AI streaming",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "@incremark/core": "0.0.1"
+  },
+  "dependencies": {
+    "@incremark/devtools": "0.0.1"
+  },
+  "devDependencies": {
+    "@types/react": "^18.2.0",
+    "react": "^18.2.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch"
+  }
+}