@incremark/vue 0.1.0 → 0.2.0

package/src/composables/useIncremark.ts

@@ -1,19 +1,15 @@
-import { ref, shallowRef, computed, markRaw, watch, onUnmounted, type Ref, type ComputedRef } from 'vue'
+import { ref, shallowRef, computed, markRaw, type ComputedRef } from 'vue'
 import {
-  IncremarkParser,
   createIncremarkParser,
-  createBlockTransformer,
-  defaultPlugins,
   type ParserOptions,
   type ParsedBlock,
   type IncrementalUpdate,
   type Root,
-  type RootContent,
-  type DisplayBlock,
   type TransformerPlugin,
-  type AnimationEffect,
-  type BlockTransformer
+  type AnimationEffect
 } from '@incremark/core'
+import { useProvideDefinations } from './useProvideDefinations'
+import { useTypewriter } from './useTypewriter'
 
 /** 打字机效果配置 */
 export interface TypewriterOptions {
@@ -40,8 +36,10 @@ export interface UseIncremarkOptions extends ParserOptions {
 
 /** 打字机控制对象 */
 export interface TypewriterControls {
-  /** 是否启用 */
-  enabled: Ref<boolean>
+  /** 是否启用（只读） */
+  enabled: ComputedRef<boolean>
+  /** 设置是否启用 */
+  setEnabled: (enabled: boolean) => void
   /** 是否正在处理中 */
   isProcessing: ComputedRef<boolean>
   /** 是否已暂停 */
@@ -94,39 +92,33 @@ export type UseIncremarkReturn = ReturnType<typeof useIncremark>
  * ```
  */
 export function useIncremark(options: UseIncremarkOptions = {}) {
+  // 内部自动提供 definitions context
+  const { setDefinations, setFootnoteDefinitions, setFootnoteReferenceOrder } = useProvideDefinations()
+
   // 解析器
-  const parser = createIncremarkParser(options)
+  const parser = createIncremarkParser({
+    ...options,
+    onChange: (state) => {
+      setDefinations(state.definitions)
+      setFootnoteDefinitions(state.footnoteDefinitions)
+      // 调用用户提供的 onChange
+      options.onChange?.(state)
+    }
+  })
+
   const completedBlocks = shallowRef<ParsedBlock[]>([])
   const pendingBlocks = shallowRef<ParsedBlock[]>([])
   const isLoading = ref(false)
   const markdown = ref('')
+  const isFinalized = ref(false)
+  const footnoteReferenceOrder = ref<string[]>([])
 
-  // 打字机相关状态
-  const typewriterEnabled = ref(options.typewriter?.enabled ?? !!options.typewriter)
-  const displayBlocksRef = shallowRef<DisplayBlock<RootContent>[]>([])
-  const isTypewriterProcessing = ref(false)
-  const isTypewriterPaused = ref(false)
-  const typewriterEffect = ref<AnimationEffect>(options.typewriter?.effect ?? 'none')
-  const typewriterCursor = ref(options.typewriter?.cursor ?? '|')
-
-  // 创建 transformer（如果有 typewriter 配置）
-  let transformer: BlockTransformer<RootContent> | null = null
-
-  if (options.typewriter) {
-    const twOptions = options.typewriter
-    transformer = createBlockTransformer<RootContent>({
-      charsPerTick: twOptions.charsPerTick ?? [1, 3],
-      tickInterval: twOptions.tickInterval ?? 30,
-      effect: twOptions.effect ?? 'none',
-      pauseOnHidden: twOptions.pauseOnHidden ?? true,
-      plugins: twOptions.plugins ?? defaultPlugins,
-      onChange: (blocks) => {
-        displayBlocksRef.value = blocks
-        isTypewriterProcessing.value = transformer?.isProcessing() ?? false
-        isTypewriterPaused.value = transformer?.isPausedState() ?? false
-      }
-    })
-  }
+  // 使用 useTypewriter composable 管理打字机效果
+  const { blocks, typewriter, transformer } = useTypewriter({
+    typewriter: options.typewriter,
+    completedBlocks,
+    pendingBlocks
+  })
 
   // AST
   const ast = computed<Root>(() => ({
@@ -137,115 +129,6 @@ export function useIncremark(options: UseIncremarkOptions = {}) {
     ]
   }))
 
-  // 将 completedBlocks 转换为 SourceBlock 格式
-  const sourceBlocks = computed(() => {
-    return completedBlocks.value.map(block => ({
-      id: block.id,
-      node: block.node,
-      status: block.status as 'pending' | 'stable' | 'completed'
-    }))
-  })
-
-  // 监听 sourceBlocks 变化，推送给 transformer
-  if (transformer) {
-    watch(
-      sourceBlocks,
-      (blocks) => {
-        transformer!.push(blocks)
-
-        // 更新正在显示的 block
-        const currentDisplaying = displayBlocksRef.value.find((b) => !b.isDisplayComplete)
-        if (currentDisplaying) {
-          const updated = blocks.find((b) => b.id === currentDisplaying.id)
-          if (updated) {
-            transformer!.update(updated)
-          }
-        }
-      },
-      { immediate: true, deep: true }
-    )
-  }
-
-  /**
-   * 在节点末尾添加光标
-   */
-  function addCursorToNode(node: RootContent, cursor: string): RootContent {
-    const cloned = JSON.parse(JSON.stringify(node))
-
-    function addToLast(n: { children?: unknown[]; type?: string; value?: string }): boolean {
-      if (n.children && n.children.length > 0) {
-        for (let i = n.children.length - 1; i >= 0; i--) {
-          if (addToLast(n.children[i] as { children?: unknown[]; type?: string; value?: string })) {
-            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
-    }
-
-    addToLast(cloned)
-    return cloned
-  }
-
-  // 原始 blocks（不经过打字机）
-  const rawBlocks = 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
-  })
-
-  // 最终用于渲染的 blocks
-  const blocks = computed(() => {
-    // 未启用打字机或没有 transformer：返回原始 blocks
-    if (!typewriterEnabled.value || !transformer) {
-      return rawBlocks.value
-    }
-
-    // 启用打字机：使用 displayBlocks
-    return displayBlocksRef.value.map((db, index) => {
-      const isPending = !db.isDisplayComplete
-      const isLastPending = isPending && index === displayBlocksRef.value.length - 1
-
-      // typing 效果时添加光标
-      let node = db.displayNode
-      if (typewriterEffect.value === 'typing' && isLastPending) {
-        node = addCursorToNode(db.displayNode, typewriterCursor.value)
-      }
-
-      return {
-        id: db.id,
-        stableId: db.id,
-        status: (db.isDisplayComplete ? 'completed' : 'pending') as 'pending' | 'stable' | 'completed',
-        isLastPending,
-        node,
-        startOffset: 0,
-        endOffset: 0,
-        rawText: ''
-      }
-    })
-  })
-
   function append(chunk: string): IncrementalUpdate {
     isLoading.value = true
     const update = parser.append(chunk)
@@ -260,6 +143,10 @@ export function useIncremark(options: UseIncremarkOptions = {}) {
     }
     pendingBlocks.value = update.pending.map((b) => markRaw(b))
 
+    // 更新脚注引用顺序
+    footnoteReferenceOrder.value = update.footnoteReferenceOrder
+    setFootnoteReferenceOrder(update.footnoteReferenceOrder)
+
     return update
   }
 
@@ -276,6 +163,11 @@ export function useIncremark(options: UseIncremarkOptions = {}) {
     }
     pendingBlocks.value = []
     isLoading.value = false
+    isFinalized.value = true
+
+    // 更新脚注引用顺序
+    footnoteReferenceOrder.value = update.footnoteReferenceOrder
+    setFootnoteReferenceOrder(update.footnoteReferenceOrder)
 
     return update
   }
@@ -290,6 +182,8 @@ export function useIncremark(options: UseIncremarkOptions = {}) {
     pendingBlocks.value = []
     markdown.value = ''
     isLoading.value = false
+    isFinalized.value = false
+    footnoteReferenceOrder.value = []
 
     // 重置 transformer
     transformer?.reset()
@@ -302,51 +196,13 @@ export function useIncremark(options: UseIncremarkOptions = {}) {
     completedBlocks.value = parser.getCompletedBlocks().map(b => markRaw(b))
     pendingBlocks.value = []
     isLoading.value = false
+    isFinalized.value = true
+    footnoteReferenceOrder.value = update.footnoteReferenceOrder
+    setFootnoteReferenceOrder(update.footnoteReferenceOrder)
 
     return update
   }
 
-  // 打字机控制对象
-  const typewriter: TypewriterControls = {
-    enabled: typewriterEnabled,
-    isProcessing: computed(() => isTypewriterProcessing.value),
-    isPaused: computed(() => isTypewriterPaused.value),
-    effect: computed(() => typewriterEffect.value),
-    skip: () => transformer?.skip(),
-    pause: () => {
-      transformer?.pause()
-      isTypewriterPaused.value = true
-    },
-    resume: () => {
-      transformer?.resume()
-      isTypewriterPaused.value = false
-    },
-    setOptions: (opts) => {
-      if (opts.enabled !== undefined) {
-        typewriterEnabled.value = opts.enabled
-      }
-      if (opts.charsPerTick !== undefined || opts.tickInterval !== undefined || opts.effect !== undefined || opts.pauseOnHidden !== undefined) {
-        transformer?.setOptions({
-          charsPerTick: opts.charsPerTick,
-          tickInterval: opts.tickInterval,
-          effect: opts.effect,
-          pauseOnHidden: opts.pauseOnHidden
-        })
-      }
-      if (opts.effect !== undefined) {
-        typewriterEffect.value = opts.effect
-      }
-      if (opts.cursor !== undefined) {
-        typewriterCursor.value = opts.cursor
-      }
-    }
-  }
-
-  // 清理
-  onUnmounted(() => {
-    transformer?.destroy()
-  })
-
   return {
     /** 已收集的完整 Markdown 字符串 */
     markdown,
@@ -360,6 +216,10 @@ export function useIncremark(options: UseIncremarkOptions = {}) {
     blocks,
     /** 是否正在加载 */
     isLoading,
+    /** 是否已完成（finalize） */
+    isFinalized,
+    /** 脚注引用的出现顺序 */
+    footnoteReferenceOrder,
     /** 追加内容 */
     append,
     /** 完成解析 */

package/src/composables/useProvideDefinations.ts

@@ -0,0 +1,61 @@
+import { ref, provide, type InjectionKey, type Ref } from 'vue';
+import type { Definition, FootnoteDefinition } from 'mdast';
+
+export const definationsInjectionKey: InjectionKey<{
+  definations: Ref<Record<string, Definition>>
+  footnoteDefinitions: Ref<Record<string, FootnoteDefinition>>
+  footnoteReferenceOrder: Ref<string[]>
+}> = Symbol('provideDefinations');
+
+export function useProvideDefinations() {
+  const definations = ref<Record<string, Definition>>({});
+  const footnoteDefinitions = ref<Record<string, FootnoteDefinition>>({});
+  const footnoteReferenceOrder = ref<string[]>([]);
+
+  provide(definationsInjectionKey, {
+    definations,
+    footnoteDefinitions,
+    footnoteReferenceOrder
+  });
+
+  function setDefinations(definitions: Record<string, Definition>) {
+    definations.value = definitions;
+  }
+
+  function setFootnoteDefinitions(definitions: Record<string, FootnoteDefinition>) {
+    footnoteDefinitions.value = definitions;
+  }
+
+  function setFootnoteReferenceOrder(order: string[]) {
+    footnoteReferenceOrder.value = order;
+  }
+
+  function clearDefinations() {
+    definations.value = {};
+  }
+
+  function clearFootnoteDefinitions() {
+    footnoteDefinitions.value = {};
+  }
+
+  function clearFootnoteReferenceOrder() {
+    footnoteReferenceOrder.value = [];
+  }
+
+  function clearAllDefinations() {
+    clearDefinations();
+    clearFootnoteDefinitions();
+    clearFootnoteReferenceOrder();
+  }
+
+  return {
+    setDefinations,
+    setFootnoteDefinitions,
+    setFootnoteReferenceOrder,
+    clearDefinations,
+    clearFootnoteDefinitions,
+    clearFootnoteReferenceOrder,
+    clearAllDefinations
+  }
+
+}

package/src/composables/useTypewriter.ts

@@ -0,0 +1,205 @@
+/**
+ * @file useTypewriter Composable - 打字机效果管理
+ *
+ * @description
+ * 管理打字机效果的状态和控制逻辑，从 useIncremark 中拆分出来以简化代码。
+ *
+ * @author Incremark Team
+ * @license MIT
+ */
+
+import { ref, shallowRef, computed, watch, onUnmounted, type Ref, type ComputedRef } from 'vue'
+import {
+  createBlockTransformer,
+  defaultPlugins,
+  type RootContent,
+  type ParsedBlock,
+  type DisplayBlock,
+  type AnimationEffect,
+  type BlockTransformer
+} from '@incremark/core'
+import type { TypewriterOptions, TypewriterControls } from './useIncremark'
+import { addCursorToNode } from '../utils/cursor'
+
+export interface UseTypewriterOptions {
+  typewriter?: TypewriterOptions
+  completedBlocks: Ref<ParsedBlock[]>
+  pendingBlocks: Ref<ParsedBlock[]>
+}
+
+export interface UseTypewriterReturn {
+  /** 用于渲染的 blocks（经过打字机处理或原始blocks） */
+  blocks: ComputedRef<Array<ParsedBlock & { stableId: string }>>
+  /** 打字机控制对象 */
+  typewriter: TypewriterControls
+  /** transformer 实例 */
+  transformer: BlockTransformer<RootContent> | null
+}
+
+/**
+ * useTypewriter Composable
+ *
+ * @description
+ * 管理打字机效果的所有状态和逻辑。
+ *
+ * @param options - 打字机配置和数据
+ * @returns 打字机状态和控制对象
+ */
+export function useTypewriter(options: UseTypewriterOptions): UseTypewriterReturn {
+  const { typewriter: typewriterConfig, completedBlocks, pendingBlocks } = options
+
+  // 打字机状态
+  const typewriterEnabled = ref(typewriterConfig?.enabled ?? !!typewriterConfig)
+  const displayBlocksRef = shallowRef<DisplayBlock<RootContent>[]>([])
+  const isTypewriterProcessing = ref(false)
+  const isTypewriterPaused = ref(false)
+  const typewriterEffect = ref<AnimationEffect>(typewriterConfig?.effect ?? 'none')
+  const typewriterCursor = ref(typewriterConfig?.cursor ?? '|')
+
+  // 创建 transformer（如果有 typewriter 配置）
+  let transformer: BlockTransformer<RootContent> | null = null
+
+  if (typewriterConfig) {
+    const twOptions = typewriterConfig
+    transformer = createBlockTransformer<RootContent>({
+      charsPerTick: twOptions.charsPerTick ?? [1, 3],
+      tickInterval: twOptions.tickInterval ?? 30,
+      effect: twOptions.effect ?? 'none',
+      pauseOnHidden: twOptions.pauseOnHidden ?? true,
+      plugins: twOptions.plugins ?? defaultPlugins,
+      onChange: (blocks) => {
+        displayBlocksRef.value = blocks as DisplayBlock<RootContent>[]
+        isTypewriterProcessing.value = transformer?.isProcessing() ?? false
+        isTypewriterPaused.value = transformer?.isPausedState() ?? false
+      }
+    })
+  }
+
+  // 将 completedBlocks 转换为 SourceBlock 格式
+  const sourceBlocks = computed(() => {
+    return completedBlocks.value.map(block => ({
+      id: block.id,
+      node: block.node,
+      status: block.status as 'pending' | 'stable' | 'completed'
+    }))
+  })
+
+  // 监听 sourceBlocks 变化，推送给 transformer
+  if (transformer) {
+    watch(
+      sourceBlocks,
+      (blocks) => {
+        transformer!.push(blocks)
+
+        // 更新正在显示的 block
+        const currentDisplaying = displayBlocksRef.value.find((b) => !b.isDisplayComplete)
+        if (currentDisplaying) {
+          const updated = blocks.find((b) => b.id === currentDisplaying.id)
+          if (updated) {
+            transformer!.update(updated)
+          }
+        }
+      },
+      { immediate: true, deep: true }
+    )
+  }
+
+  // 原始 blocks（不经过打字机）
+  const rawBlocks = 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
+  })
+
+  // 最终用于渲染的 blocks
+  const blocks = computed(() => {
+    // 未启用打字机或没有 transformer：返回原始 blocks
+    if (!typewriterEnabled.value || !transformer) {
+      return rawBlocks.value
+    }
+
+    // 启用打字机：使用 displayBlocks
+    return displayBlocksRef.value.map((db, index) => {
+      const isPending = !db.isDisplayComplete
+      const isLastPending = isPending && index === displayBlocksRef.value.length - 1
+
+      // typing 效果时添加光标
+      let node = db.displayNode
+      if (typewriterEffect.value === 'typing' && isLastPending) {
+        node = addCursorToNode(db.displayNode, typewriterCursor.value)
+      }
+
+      return {
+        id: db.id,
+        stableId: db.id,
+        status: (db.isDisplayComplete ? 'completed' : 'pending') as 'pending' | 'stable' | 'completed',
+        isLastPending,
+        node,
+        startOffset: 0,
+        endOffset: 0,
+        rawText: ''
+      }
+    })
+  })
+
+  // 打字机控制对象
+  const typewriterControls: TypewriterControls = {
+    enabled: computed(() => typewriterEnabled.value),
+    setEnabled: (value: boolean) => {
+      typewriterEnabled.value = value
+    },
+    isProcessing: computed(() => isTypewriterProcessing.value),
+    isPaused: computed(() => isTypewriterPaused.value),
+    effect: computed(() => typewriterEffect.value),
+    skip: () => transformer?.skip(),
+    pause: () => {
+      transformer?.pause()
+      isTypewriterPaused.value = true
+    },
+    resume: () => {
+      transformer?.resume()
+      isTypewriterPaused.value = false
+    },
+    setOptions: (opts) => {
+      if (opts.enabled !== undefined) {
+        typewriterEnabled.value = opts.enabled
+      }
+      if (opts.charsPerTick !== undefined || opts.tickInterval !== undefined || opts.effect !== undefined || opts.pauseOnHidden !== undefined) {
+        transformer?.setOptions({
+          charsPerTick: opts.charsPerTick,
+          tickInterval: opts.tickInterval,
+          effect: opts.effect,
+          pauseOnHidden: opts.pauseOnHidden
+        })
+      }
+      if (opts.effect !== undefined) {
+        typewriterEffect.value = opts.effect
+      }
+      if (opts.cursor !== undefined) {
+        typewriterCursor.value = opts.cursor
+      }
+    }
+  }
+
+  // 清理
+  onUnmounted(() => {
+    transformer?.destroy()
+  })
+
+  return {
+    blocks,
+    typewriter: typewriterControls,
+    transformer
+  }
+}

package/src/index.ts

@@ -1,5 +1,7 @@
 // Composables
 export { useIncremark, useStreamRenderer, useDevTools, useBlockTransformer } from './composables'
+export { useProvideDefinations } from './composables/useProvideDefinations'
+export { useDefinationsContext } from './composables/useDefinationsContext'
 export type {
   UseIncremarkOptions,
   TypewriterOptions,
@@ -23,10 +25,13 @@ export {
   IncremarkThematicBreak,
   IncremarkInline,
   IncremarkMath,
+  IncremarkHtmlElement,
   IncremarkDefault,
+  IncremarkFootnotes,
   AutoScrollContainer
 } from './components'
 export type { ComponentMap, BlockWithStableId } from './components'
+export { default as ThemeProvider } from './ThemeProvider.vue'
 
 // Re-export core types
 export type {
@@ -61,3 +66,13 @@ export {
   allPlugins,
   createPlugin
 } from '@incremark/core'
+
+// Re-export theme utilities
+export {
+  type DesignTokens,
+  defaultTheme,
+  darkTheme,
+  generateCSSVars,
+  mergeTheme,
+  applyTheme
+} from '@incremark/theme'

package/src/utils/cursor.ts

@@ -0,0 +1,46 @@
+/**
+ * @file Cursor Utils - 光标工具函数
+ *
+ * @description
+ * 用于在 AST 节点末尾添加光标的工具函数。
+ *
+ * @author Incremark Team
+ * @license MIT
+ */
+
+import type { RootContent } from '@incremark/core'
+
+/**
+ * 在节点末尾添加光标
+ *
+ * @param node - 要添加光标的节点
+ * @param cursor - 光标字符
+ * @returns 添加了光标的新节点
+ */
+export function addCursorToNode(node: RootContent, cursor: string): RootContent {
+  const cloned = JSON.parse(JSON.stringify(node))
+
+  function addToLast(n: { children?: unknown[]; type?: string; value?: string }): boolean {
+    if (n.children && n.children.length > 0) {
+      for (let i = n.children.length - 1; i >= 0; i--) {
+        if (addToLast(n.children[i] as { children?: unknown[]; type?: string; value?: string })) {
+          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
+  }
+
+  addToLast(cloned)
+  return cloned
+}