@incremark/vue 0.0.1

package/src/components/IncremarkMath.vue

@@ -0,0 +1,150 @@
+<script setup lang="ts">
+import { computed, ref, watch, shallowRef, onUnmounted } from 'vue'
+
+// Math 节点类型（来自 mdast-util-math）
+interface MathNode {
+  type: 'math' | 'inlineMath'
+  value: string
+  data?: {
+    hName?: string
+    hProperties?: Record<string, any>
+  }
+}
+
+const props = withDefaults(
+  defineProps<{
+    node: MathNode
+    /** 渲染延迟（毫秒），用于流式输入时防抖 */
+    renderDelay?: number
+  }>(),
+  {
+    renderDelay: 300
+  }
+)
+
+const renderedHtml = ref('')
+const renderError = ref('')
+const isLoading = ref(false)
+const katexRef = shallowRef<any>(null)
+let renderTimer: ReturnType<typeof setTimeout> | null = null
+
+const isInline = computed(() => props.node.type === 'inlineMath')
+const formula = computed(() => props.node.value)
+
+// 带防抖动的渲染
+function scheduleRender() {
+  if (!formula.value) {
+    renderedHtml.value = ''
+    return
+  }
+
+  // 清除之前的定时器
+  if (renderTimer) {
+    clearTimeout(renderTimer)
+  }
+
+  isLoading.value = true
+
+  // 防抖动延迟渲染
+  renderTimer = setTimeout(() => {
+    doRender()
+  }, props.renderDelay)
+}
+
+async function doRender() {
+  if (!formula.value) return
+
+  try {
+    // 动态导入 KaTeX
+    if (!katexRef.value) {
+      // @ts-ignore - katex 是可选依赖
+      const katexModule = await import('katex')
+      katexRef.value = katexModule.default
+    }
+
+    const katex = katexRef.value
+    renderedHtml.value = katex.renderToString(formula.value, {
+      displayMode: !isInline.value,
+      throwOnError: false,
+      strict: false
+    })
+    renderError.value = ''
+  } catch (e: any) {
+    // 静默失败，可能是公式不完整
+    renderError.value = ''
+    renderedHtml.value = ''
+  } finally {
+    isLoading.value = false
+  }
+}
+
+onUnmounted(() => {
+  if (renderTimer) {
+    clearTimeout(renderTimer)
+  }
+})
+
+watch(formula, scheduleRender, { immediate: true })
+</script>
+
+<template>
+  <!-- 行内公式 -->
+  <span v-if="isInline" class="incremark-math-inline">
+    <!-- 渲染成功 -->
+    <span v-if="renderedHtml && !isLoading" v-html="renderedHtml" />
+    <!-- 加载中或未渲染：显示源码 -->
+    <code v-else class="math-source">{{ formula }}</code>
+  </span>
+  <!-- 块级公式 -->
+  <div v-else class="incremark-math-block">
+    <!-- 渲染成功 -->
+    <div v-if="renderedHtml && !isLoading" v-html="renderedHtml" class="math-rendered" />
+    <!-- 加载中或未渲染：显示源码 -->
+    <pre v-else class="math-source-block"><code>{{ formula }}</code></pre>
+  </div>
+</template>
+
+<style scoped>
+.incremark-math-inline {
+  display: inline;
+}
+
+.incremark-math-block {
+  margin: 1em 0;
+  padding: 1em;
+  overflow-x: auto;
+  text-align: center;
+}
+
+.math-source {
+  background: #f3f4f6;
+  padding: 0.1em 0.3em;
+  border-radius: 3px;
+  font-size: 0.9em;
+  color: #6b7280;
+}
+
+.math-source-block {
+  margin: 0;
+  padding: 1em;
+  background: #f3f4f6;
+  border-radius: 6px;
+  text-align: left;
+}
+
+.math-source-block code {
+  font-family: 'Fira Code', monospace;
+  font-size: 0.9em;
+  color: #374151;
+}
+
+.math-rendered :deep(.katex) {
+  font-size: 1.1em;
+}
+
+.math-rendered :deep(.katex-display) {
+  margin: 0;
+  overflow-x: auto;
+  overflow-y: hidden;
+}
+</style>

package/src/components/IncremarkParagraph.vue

@@ -0,0 +1,21 @@
+<script setup lang="ts">
+import type { Paragraph } from 'mdast'
+import IncremarkInline from './IncremarkInline.vue'
+
+defineProps<{
+  node: Paragraph
+}>()
+</script>
+
+<template>
+  <p class="incremark-paragraph">
+    <IncremarkInline :nodes="node.children" />
+  </p>
+</template>
+
+<style scoped>
+.incremark-paragraph {
+  margin: 0.75em 0;
+  line-height: 1.6;
+}
+</style>

package/src/components/IncremarkRenderer.vue

@@ -0,0 +1,38 @@
+<script setup lang="ts">
+import type { RootContent } from 'mdast'
+import type { Component } from 'vue'
+import IncremarkHeading from './IncremarkHeading.vue'
+import IncremarkParagraph from './IncremarkParagraph.vue'
+import IncremarkCode from './IncremarkCode.vue'
+import IncremarkList from './IncremarkList.vue'
+import IncremarkTable from './IncremarkTable.vue'
+import IncremarkBlockquote from './IncremarkBlockquote.vue'
+import IncremarkThematicBreak from './IncremarkThematicBreak.vue'
+import IncremarkMath from './IncremarkMath.vue'
+import IncremarkDefault from './IncremarkDefault.vue'
+
+defineProps<{
+  node: RootContent
+}>()
+
+const componentMap: Record<string, Component> = {
+  heading: IncremarkHeading,
+  paragraph: IncremarkParagraph,
+  code: IncremarkCode,
+  list: IncremarkList,
+  table: IncremarkTable,
+  blockquote: IncremarkBlockquote,
+  thematicBreak: IncremarkThematicBreak,
+  math: IncremarkMath,
+  inlineMath: IncremarkMath,
+}
+
+function getComponent(type: string): Component {
+  return componentMap[type] || IncremarkDefault
+}
+</script>
+
+<template>
+  <component :is="getComponent(node.type)" :node="node" />
+</template>
+

package/src/components/IncremarkTable.vue

@@ -0,0 +1,74 @@
+<script setup lang="ts">
+import type { Table, TableCell, PhrasingContent } from 'mdast'
+import IncremarkInline from './IncremarkInline.vue'
+
+defineProps<{
+  node: Table
+}>()
+
+function getCellContent(cell: TableCell): PhrasingContent[] {
+  return cell.children as PhrasingContent[]
+}
+</script>
+
+<template>
+  <div class="incremark-table-wrapper">
+    <table class="incremark-table">
+      <thead>
+        <tr v-if="node.children[0]">
+          <th 
+            v-for="(cell, cellIndex) in node.children[0].children" 
+            :key="cellIndex"
+            :style="{ textAlign: node.align?.[cellIndex] || 'left' }"
+          >
+            <IncremarkInline :nodes="getCellContent(cell)" />
+          </th>
+        </tr>
+      </thead>
+      <tbody>
+        <tr v-for="(row, rowIndex) in node.children.slice(1)" :key="rowIndex">
+          <td 
+            v-for="(cell, cellIndex) in row.children" 
+            :key="cellIndex"
+            :style="{ textAlign: node.align?.[cellIndex] || 'left' }"
+          >
+            <IncremarkInline :nodes="getCellContent(cell)" />
+          </td>
+        </tr>
+      </tbody>
+    </table>
+  </div>
+</template>
+
+<style scoped>
+.incremark-table-wrapper {
+  overflow-x: auto;
+  margin: 1em 0;
+}
+
+.incremark-table {
+  width: 100%;
+  border-collapse: collapse;
+  font-size: 14px;
+}
+
+.incremark-table th,
+.incremark-table td {
+  border: 1px solid #ddd;
+  padding: 10px 14px;
+}
+
+.incremark-table th {
+  background: #f8f9fa;
+  font-weight: 600;
+}
+
+.incremark-table tr:nth-child(even) {
+  background: #fafafa;
+}
+
+.incremark-table tr:hover {
+  background: #f0f0f0;
+}
+</style>
+

package/src/components/IncremarkThematicBreak.vue

@@ -0,0 +1,16 @@
+<script setup lang="ts">
+// ThematicBreak 不需要 props
+</script>
+
+<template>
+  <hr class="incremark-hr" />
+</template>
+
+<style scoped>
+.incremark-hr {
+  margin: 2em 0;
+  border: none;
+  border-top: 2px solid #e5e5e5;
+}
+</style>
+

package/src/components/index.ts

@@ -0,0 +1,18 @@
+// 主组件
+export { default as Incremark } from './Incremark.vue'
+export type { ComponentMap, BlockWithStableId } from './Incremark.vue'
+
+// 渲染器组件 - 用于自定义渲染
+export { default as IncremarkRenderer } from './IncremarkRenderer.vue'
+
+// 各节点类型组件 - 用于自定义或扩展
+export { default as IncremarkHeading } from './IncremarkHeading.vue'
+export { default as IncremarkParagraph } from './IncremarkParagraph.vue'
+export { default as IncremarkCode } from './IncremarkCode.vue'
+export { default as IncremarkList } from './IncremarkList.vue'
+export { default as IncremarkTable } from './IncremarkTable.vue'
+export { default as IncremarkBlockquote } from './IncremarkBlockquote.vue'
+export { default as IncremarkThematicBreak } from './IncremarkThematicBreak.vue'
+export { default as IncremarkInline } from './IncremarkInline.vue'
+export { default as IncremarkMath } from './IncremarkMath.vue'
+export { default as IncremarkDefault } from './IncremarkDefault.vue'

package/src/composables/index.ts

@@ -0,0 +1,8 @@
+export { useIncremark } from './useIncremark'
+export type { UseIncremarkOptions } from './useIncremark'
+
+export { useStreamRenderer } from './useStreamRenderer'
+export type { UseStreamRendererOptions } from './useStreamRenderer'
+
+export { useDevTools } from './useDevTools'
+export type { UseDevToolsOptions } from './useDevTools'

package/src/composables/useDevTools.ts

@@ -0,0 +1,54 @@
+import { onMounted, onUnmounted } from 'vue'
+import { createDevTools, type DevToolsOptions } from '@incremark/devtools'
+import type { UseIncremarkReturn } from './useIncremark'
+
+export interface UseDevToolsOptions extends DevToolsOptions {}
+
+/**
+ * Vue 3 DevTools 一行接入
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { useIncremark, useDevTools } from '@incremark/vue'
+ *
+ * const incremark = useIncremark()
+ * useDevTools(incremark)  // 就这一行！
+ * </script>
+ * ```
+ */
+export function useDevTools(
+  incremark: UseIncremarkReturn,
+  options: UseDevToolsOptions = {}
+) {
+  const devtools = createDevTools(options)
+
+  // 设置 parser 的 onChange 回调
+  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
+    })
+  })
+
+  onMounted(() => {
+    devtools.mount()
+  })
+
+  onUnmounted(() => {
+    devtools.unmount()
+    // 清理回调
+    incremark.parser.setOnChange(undefined)
+  })
+
+  return devtools
+}

package/src/composables/useIncremark.ts

@@ -0,0 +1,147 @@
+import { ref, shallowRef, computed, markRaw } from 'vue'
+import {
+  IncremarkParser,
+  createIncremarkParser,
+  type ParserOptions,
+  type ParsedBlock,
+  type IncrementalUpdate,
+  type Root
+} from '@incremark/core'
+
+export interface UseIncremarkOptions extends ParserOptions {}
+
+/** useIncremark 的返回类型 */
+export type UseIncremarkReturn = ReturnType<typeof useIncremark>
+
+/**
+ * Vue 3 Composable: Incremark 流式 Markdown 解析器
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { useIncremark } from '@incremark/vue'
+ *
+ * const { markdown, blocks, append, finalize } = useIncremark()
+ *
+ * // 处理 AI 流式输出
+ * async function handleStream(stream) {
+ *   for await (const chunk of stream) {
+ *     append(chunk)
+ *   }
+ *   finalize()
+ * }
+ * </script>
+ *
+ * <template>
+ *   <div>已接收: {{ markdown.length }} 字符</div>
+ * </template>
+ * ```
+ */
+export function useIncremark(options: UseIncremarkOptions = {}) {
+  const parser = createIncremarkParser(options)
+  const completedBlocks = shallowRef<ParsedBlock[]>([])
+  const pendingBlocks = shallowRef<ParsedBlock[]>([])
+  const isLoading = ref(false)
+  // 使用 ref 存储 markdown，确保响应式
+  const markdown = ref('')
+
+  const ast = computed<Root>(() => ({
+    type: 'root',
+    children: [
+      ...completedBlocks.value.map((b) => b.node),
+      ...pendingBlocks.value.map((b) => b.node)
+    ]
+  }))
+
+  // 所有块，带稳定 ID（已完成块用真实 ID，待处理块用索引）
+  const blocks = computed(() => {
+    const result: Array<ParsedBlock & { stableId: string }> = []
+
+    for (const block of completedBlocks.value) {
+      result.push({ ...block, stableId: block.id })
+    }
+
+    for (let i = 0; i < pendingBlocks.value.length; i++) {
+      result.push({
+        ...pendingBlocks.value[i],
+        stableId: `pending-${i}`
+      })
+    }
+
+    return result
+  })
+
+  function append(chunk: string): IncrementalUpdate {
+    isLoading.value = true
+    const update = parser.append(chunk)
+
+    // 更新 markdown ref
+    markdown.value = parser.getBuffer()
+
+    // 使用 markRaw 避免深层响应式
+    if (update.completed.length > 0) {
+      completedBlocks.value = [
+        ...completedBlocks.value,
+        ...update.completed.map((b) => markRaw(b))
+      ]
+    }
+    pendingBlocks.value = update.pending.map((b) => markRaw(b))
+
+    return update
+  }
+
+  function finalize(): IncrementalUpdate {
+    const update = parser.finalize()
+
+    // 更新 markdown ref
+    markdown.value = parser.getBuffer()
+
+    if (update.completed.length > 0) {
+      completedBlocks.value = [
+        ...completedBlocks.value,
+        ...update.completed.map((b) => markRaw(b))
+      ]
+    }
+    pendingBlocks.value = []
+    isLoading.value = false
+
+    return update
+  }
+
+  function abort(): IncrementalUpdate {
+    return finalize()
+  }
+
+  function reset(): void {
+    parser.reset()
+    completedBlocks.value = []
+    pendingBlocks.value = []
+    markdown.value = ''
+    isLoading.value = false
+  }
+
+  return {
+    /** 已收集的完整 Markdown 字符串 */
+    markdown,
+    /** 已完成的块列表 */
+    completedBlocks,
+    /** 待处理的块列表 */
+    pendingBlocks,
+    /** 当前完整的 AST */
+    ast,
+    /** 所有块（完成 + 待处理），带稳定 ID */
+    blocks,
+    /** 是否正在加载 */
+    isLoading,
+    /** 追加内容 */
+    append,
+    /** 完成解析 */
+    finalize,
+    /** 强制中断 */
+    abort,
+    /** 重置解析器 */
+    reset,
+    /** 解析器实例 */
+    parser
+  }
+}

package/src/composables/useStreamRenderer.ts

@@ -0,0 +1,55 @@
+import { ref, computed, type Ref, type ComputedRef } from 'vue'
+import type { ParsedBlock } from '@incremark/core'
+
+export interface BlockWithStableId extends ParsedBlock {
+  /** 稳定的渲染 ID（用于 Vue key） */
+  stableId: string
+}
+
+export interface UseStreamRendererOptions {
+  /** 已完成的块 */
+  completedBlocks: Ref<ParsedBlock[]>
+  /** 待处理的块 */
+  pendingBlocks: Ref<ParsedBlock[]>
+}
+
+export interface UseStreamRendererReturn {
+  /** 带稳定 ID 的已完成块 */
+  stableCompletedBlocks: ComputedRef<BlockWithStableId[]>
+  /** 带稳定 ID 的待处理块 */
+  stablePendingBlocks: ComputedRef<BlockWithStableId[]>
+  /** 所有带稳定 ID 的块 */
+  allStableBlocks: ComputedRef<BlockWithStableId[]>
+}
+
+/**
+ * Vue 3 Composable: 流式渲染辅助
+ *
+ * 为块分配稳定的渲染 ID，确保 Vue 的虚拟 DOM 复用
+ */
+export function useStreamRenderer(options: UseStreamRendererOptions): UseStreamRendererReturn {
+  const { completedBlocks, pendingBlocks } = options
+
+  const stableCompletedBlocks = computed<BlockWithStableId[]>(() =>
+    completedBlocks.value.map((block) => ({
+      ...block,
+      stableId: block.id
+    }))
+  )
+
+  const stablePendingBlocks = computed<BlockWithStableId[]>(() =>
+    pendingBlocks.value.map((block, index) => ({
+      ...block,
+      stableId: `pending-${index}`
+    }))
+  )
+
+  const allStableBlocks = computed(() => [...stableCompletedBlocks.value, ...stablePendingBlocks.value])
+
+  return {
+    stableCompletedBlocks,
+    stablePendingBlocks,
+    allStableBlocks
+  }
+}
+

package/src/index.ts

@@ -0,0 +1,30 @@
+// Composables
+export { useIncremark, useStreamRenderer, useDevTools } from './composables'
+export type { UseIncremarkOptions, UseStreamRendererOptions, UseDevToolsOptions } from './composables'
+
+// Components
+export {
+  Incremark,
+  IncremarkRenderer,
+  IncremarkHeading,
+  IncremarkParagraph,
+  IncremarkCode,
+  IncremarkList,
+  IncremarkTable,
+  IncremarkBlockquote,
+  IncremarkThematicBreak,
+  IncremarkInline,
+  IncremarkMath,
+  IncremarkDefault
+} from './components'
+export type { ComponentMap, BlockWithStableId } from './components'
+
+// Re-export core types
+export type {
+  ParsedBlock,
+  IncrementalUpdate,
+  ParserOptions,
+  BlockStatus,
+  Root,
+  RootContent
+} from '@incremark/core'