@incremark/vue 0.0.4 → 0.1.0

package/src/components/AutoScrollContainer.vue

@@ -0,0 +1,164 @@
+<script setup lang="ts">
+import { ref, watch, onMounted, onUnmounted, nextTick } from 'vue'
+
+const props = withDefaults(defineProps<{
+  /** 是否启用自动滚动 */
+  enabled?: boolean
+  /** 触发自动滚动的底部阈值（像素） */
+  threshold?: number
+  /** 滚动行为 */
+  behavior?: ScrollBehavior
+}>(), {
+  enabled: true,
+  threshold: 50,
+  behavior: 'instant'
+})
+
+const containerRef = ref<HTMLDivElement | null>(null)
+const isUserScrolledUp = ref(false)
+
+// 记录上一次滚动位置，用于判断滚动方向
+let lastScrollTop = 0
+let lastScrollHeight = 0
+
+/**
+ * 检查是否在底部附近
+ */
+function isNearBottom(): boolean {
+  const container = containerRef.value
+  if (!container) return true
+  
+  const { scrollTop, scrollHeight, clientHeight } = container
+  return scrollHeight - scrollTop - clientHeight <= props.threshold
+}
+
+/**
+ * 滚动到底部
+ */
+function scrollToBottom(force = false): void {
+  const container = containerRef.value
+  if (!container) return
+  
+  // 如果用户手动向上滚动了，且不是强制滚动，则不自动滚动
+  if (isUserScrolledUp.value && !force) return
+  
+  container.scrollTo({
+    top: container.scrollHeight,
+    behavior: props.behavior
+  })
+}
+
+/**
+ * 检查是否有滚动条
+ */
+function hasScrollbar(): boolean {
+  const container = containerRef.value
+  if (!container) return false
+  return container.scrollHeight > container.clientHeight
+}
+
+/**
+ * 处理滚动事件
+ */
+function handleScroll(): void {
+  const container = containerRef.value
+  if (!container) return
+  
+  const { scrollTop, scrollHeight, clientHeight } = container
+  
+  // 如果没有滚动条，恢复自动滚动
+  if (scrollHeight <= clientHeight) {
+    isUserScrolledUp.value = false
+    lastScrollTop = 0
+    lastScrollHeight = scrollHeight
+    return
+  }
+  
+  // 检查用户是否滚动到底部附近
+  if (isNearBottom()) {
+    // 用户滚动到底部，恢复自动滚动
+    isUserScrolledUp.value = false
+  } else {
+    // 判断是否是用户主动向上滚动
+    // 条件：scrollTop 减少（向上滚动）且 scrollHeight 没有变化（不是因为内容增加）
+    const isScrollingUp = scrollTop < lastScrollTop
+    const isContentUnchanged = scrollHeight === lastScrollHeight
+    
+    if (isScrollingUp && isContentUnchanged) {
+      // 用户主动向上滚动，暂停自动滚动
+      isUserScrolledUp.value = true
+    }
+  }
+  
+  // 更新记录
+  lastScrollTop = scrollTop
+  lastScrollHeight = scrollHeight
+}
+
+// 监听 slot 内容变化（使用 MutationObserver）
+let observer: MutationObserver | null = null
+
+onMounted(() => {
+  if (!containerRef.value) return
+  
+  // 初始化滚动位置记录
+  lastScrollTop = containerRef.value.scrollTop
+  lastScrollHeight = containerRef.value.scrollHeight
+  
+  observer = new MutationObserver(() => {
+    nextTick(() => {
+      if (!containerRef.value) return
+      
+      // 如果没有滚动条，重置状态
+      if (!hasScrollbar()) {
+        isUserScrolledUp.value = false
+      }
+      
+      // 更新 scrollHeight 记录（内容变化后）
+      lastScrollHeight = containerRef.value.scrollHeight
+      
+      // 自动滚动
+      if (props.enabled && !isUserScrolledUp.value) {
+        scrollToBottom()
+      }
+    })
+  })
+  
+  observer.observe(containerRef.value, {
+    childList: true,
+    subtree: true,
+    characterData: true
+  })
+})
+
+onUnmounted(() => {
+  observer?.disconnect()
+})
+
+// 暴露方法给父组件
+defineExpose({
+  /** 强制滚动到底部 */
+  scrollToBottom: () => scrollToBottom(true),
+  /** 是否用户手动向上滚动了 */
+  isUserScrolledUp: () => isUserScrolledUp.value,
+  /** 容器元素引用 */
+  container: containerRef
+})
+</script>
+
+<template>
+  <div
+    ref="containerRef"
+    class="auto-scroll-container"
+    @scroll="handleScroll"
+  >
+    <slot />
+  </div>
+</template>
+
+<style scoped>
+.auto-scroll-container {
+  overflow-y: auto;
+  height: 100%;
+}
+</style>

package/src/components/Incremark.vue

@@ -17,6 +17,7 @@ export type ComponentMap = Partial<Record<string, Component>>
 // 带稳定 ID 的块类型
 export interface BlockWithStableId extends ParsedBlock {
   stableId: string
+  isLastPending?: boolean // 是否是最后一个 pending 块
 }
 
 const props = withDefaults(
@@ -73,7 +74,8 @@ function getComponent(type: string): Component {
         :class="[
           'incremark-block',
           block.status === 'completed' ? completedClass : pendingClass,
-          { 'incremark-show-status': showBlockStatus }
+          { 'incremark-show-status': showBlockStatus },
+          { 'incremark-last-pending': block.isLastPending }
         ]"
       >
         <component :is="getComponent(block.node.type)" :node="block.node" />

package/src/components/IncremarkInline.vue

@@ -1,27 +1,83 @@
 <script setup lang="ts">
-import type { PhrasingContent } from 'mdast'
+import type { PhrasingContent, Text, HTML } from 'mdast'
+import type { TextChunk } from '@incremark/core'
 import IncremarkMath from './IncremarkMath.vue'
 
+// 扩展的文本节点类型（支持 chunks）
+interface TextNodeWithChunks extends Text {
+  stableLength?: number
+  chunks?: TextChunk[]
+}
+
+// Math 节点类型
+interface MathNode {
+  type: 'math' | 'inlineMath'
+  value: string
+}
+
 defineProps<{
   nodes: PhrasingContent[]
 }>()
 
-function escapeHtml(str: string): string {
-  return str
-    .replace(/&/g, '&amp;')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;')
-    .replace(/"/g, '&quot;')
+/**
+ * 获取文本节点的稳定部分（不需要动画）
+ */
+function getStableText(node: TextNodeWithChunks): string {
+  if (!node.chunks || node.chunks.length === 0) {
+    return node.value
+  }
+  return node.value.slice(0, node.stableLength ?? 0)
+}
+
+/**
+ * 类型守卫：检查是否是带 chunks 的文本节点
+ */
+function hasChunks(node: PhrasingContent): node is TextNodeWithChunks {
+  return node.type === 'text' && 'chunks' in node && Array.isArray((node as TextNodeWithChunks).chunks)
+}
+
+/**
+ * 获取节点的 chunks（类型安全）
+ */
+function getChunks(node: PhrasingContent): TextChunk[] | undefined {
+  if (hasChunks(node)) {
+    return node.chunks
+  }
+  return undefined
+}
+
+/**
+ * 类型守卫：检查是否是 HTML 节点
+ */
+function isHtmlNode(node: PhrasingContent): node is HTML {
+  return node.type === 'html'
+}
+
+/**
+ * 类型守卫：检查是否是 inlineMath 节点
+ * inlineMath 是 mdast-util-math 扩展的类型，不在标准 PhrasingContent 中
+ */
+function isInlineMath(node: PhrasingContent): node is PhrasingContent & MathNode {
+  return (node as unknown as MathNode).type === 'inlineMath'
 }
 </script>
 
 <template>
   <template v-for="(node, idx) in nodes" :key="idx">
-    <!-- 文本 -->
-    <template v-if="node.type === 'text'">{{ node.value }}</template>
+    <!-- 文本（支持 chunks 渐入动画） -->
+    <template v-if="node.type === 'text'">
+      <!-- 稳定文本（已经显示过的部分，无动画） -->
+      {{ getStableText(node as TextNodeWithChunks) }}
+      <!-- 新增的 chunk 部分（带渐入动画） -->
+      <span 
+        v-for="chunk in getChunks(node)" 
+        :key="chunk.createdAt"
+        class="incremark-fade-in"
+      >{{ chunk.text }}</span>
+    </template>
 
     <!-- 行内公式 -->
-    <IncremarkMath v-else-if="(node as any).type === 'inlineMath'" :node="node as any" />
+    <IncremarkMath v-else-if="isInlineMath(node)" :node="(node as unknown as MathNode)" />
 
     <!-- 加粗 -->
     <strong v-else-if="node.type === 'strong'">
@@ -61,6 +117,9 @@ function escapeHtml(str: string): string {
     <del v-else-if="node.type === 'delete'">
       <IncremarkInline :nodes="(node.children as PhrasingContent[])" />
     </del>
+
+    <!-- 原始 HTML -->
+    <span v-else-if="isHtmlNode(node)" v-html="node.value"></span>
   </template>
 </template>
 
@@ -72,4 +131,18 @@ function escapeHtml(str: string): string {
   font-family: 'Fira Code', 'SF Mono', Consolas, monospace;
   font-size: 0.9em;
 }
+
+/* 渐入动画 */
+.incremark-fade-in {
+  animation: incremark-fade-in 0.4s ease-out;
+}
+
+@keyframes incremark-fade-in {
+  from { 
+    opacity: 0; 
+  }
+  to { 
+    opacity: 1; 
+  }
+}
 </style>

package/src/components/index.ts

@@ -16,3 +16,6 @@ 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'
+
+// 工具组件
+export { default as AutoScrollContainer } from './AutoScrollContainer.vue'

package/src/composables/index.ts

@@ -1,8 +1,11 @@
 export { useIncremark } from './useIncremark'
-export type { UseIncremarkOptions } from './useIncremark'
+export type { UseIncremarkOptions, TypewriterOptions, TypewriterControls } from './useIncremark'
 
 export { useStreamRenderer } from './useStreamRenderer'
 export type { UseStreamRendererOptions } from './useStreamRenderer'
 
 export { useDevTools } from './useDevTools'
 export type { UseDevToolsOptions } from './useDevTools'
+
+export { useBlockTransformer } from './useBlockTransformer'
+export type { UseBlockTransformerOptions, UseBlockTransformerReturn } from './useBlockTransformer'

package/src/composables/useBlockTransformer.ts

@@ -0,0 +1,141 @@
+import { ref, watch, computed, onUnmounted, type Ref, type ComputedRef } from 'vue'
+import {
+  BlockTransformer,
+  createBlockTransformer,
+  type TransformerOptions,
+  type DisplayBlock,
+  type SourceBlock,
+  type AnimationEffect
+} from '@incremark/core'
+
+export interface UseBlockTransformerOptions extends Omit<TransformerOptions, 'onChange'> {}
+
+export interface UseBlockTransformerReturn<T = unknown> {
+  /** 用于渲染的 display blocks */
+  displayBlocks: ComputedRef<DisplayBlock<T>[]>
+  /** 是否正在处理中 */
+  isProcessing: ComputedRef<boolean>
+  /** 是否已暂停 */
+  isPaused: ComputedRef<boolean>
+  /** 当前动画效果 */
+  effect: ComputedRef<AnimationEffect>
+  /** 跳过所有动画 */
+  skip: () => void
+  /** 重置状态 */
+  reset: () => void
+  /** 暂停动画 */
+  pause: () => void
+  /** 恢复动画 */
+  resume: () => void
+  /** 动态更新配置 */
+  setOptions: (options: Partial<Pick<TransformerOptions, 'charsPerTick' | 'tickInterval' | 'effect' | 'pauseOnHidden'>>) => void
+  /** transformer 实例（用于高级用法） */
+  transformer: BlockTransformer<T>
+}
+
+/**
+ * Vue 3 Composable: Block Transformer
+ *
+ * 用于控制 blocks 的逐步显示（打字机效果）
+ * 作为解析器和渲染器之间的中间层
+ *
+ * 特性：
+ * - 使用 requestAnimationFrame 实现流畅动画
+ * - 支持随机步长 `charsPerTick: [1, 3]`
+ * - 支持动画效果 `effect: 'typing'`
+ * - 页面不可见时自动暂停
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { useIncremark, useBlockTransformer, defaultPlugins } from '@incremark/vue'
+ *
+ * const { blocks, completedBlocks, append, finalize } = useIncremark()
+ *
+ * // 使用 completedBlocks 作为输入（ID 稳定）
+ * const sourceBlocks = computed(() => completedBlocks.value.map(b => ({
+ *   id: b.id,
+ *   node: b.node,
+ *   status: b.status
+ * })))
+ *
+ * // 添加打字机效果
+ * const { displayBlocks, isProcessing, skip, effect } = useBlockTransformer(sourceBlocks, {
+ *   charsPerTick: [1, 3],  // 随机步长
+ *   tickInterval: 30,
+ *   effect: 'typing',      // 光标效果
+ *   plugins: defaultPlugins
+ * })
+ * </script>
+ *
+ * <template>
+ *   <Incremark :blocks="displayBlocks" :class="{ 'typing': effect === 'typing' }" />
+ *   <button v-if="isProcessing" @click="skip">跳过</button>
+ * </template>
+ * ```
+ */
+export function useBlockTransformer<T = unknown>(
+  sourceBlocks: Ref<SourceBlock<T>[]> | ComputedRef<SourceBlock<T>[]>,
+  options: UseBlockTransformerOptions = {}
+): UseBlockTransformerReturn<T> {
+  const displayBlocksRef = ref<DisplayBlock<T>[]>([])
+  const isProcessingRef = ref(false)
+  const isPausedRef = ref(false)
+  const effectRef = ref<AnimationEffect>(options.effect ?? 'none')
+
+  const transformer = createBlockTransformer<T>({
+    ...options,
+    onChange: (blocks) => {
+      displayBlocksRef.value = blocks as DisplayBlock<T>[]
+      isProcessingRef.value = transformer.isProcessing()
+      isPausedRef.value = transformer.isPausedState()
+    }
+  })
+
+  // 监听源 blocks 变化
+  watch(
+    sourceBlocks,
+    (blocks) => {
+      // 推入新 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 }
+  )
+
+  onUnmounted(() => {
+    transformer.destroy()
+  })
+
+  return {
+    displayBlocks: computed(() => displayBlocksRef.value) as ComputedRef<DisplayBlock<T>[]>,
+    isProcessing: computed(() => isProcessingRef.value),
+    isPaused: computed(() => isPausedRef.value),
+    effect: computed(() => effectRef.value),
+    skip: () => transformer.skip(),
+    reset: () => transformer.reset(),
+    pause: () => {
+      transformer.pause()
+      isPausedRef.value = true
+    },
+    resume: () => {
+      transformer.resume()
+      isPausedRef.value = false
+    },
+    setOptions: (opts) => {
+      transformer.setOptions(opts)
+      if (opts.effect !== undefined) {
+        effectRef.value = opts.effect
+      }
+    },
+    transformer
+  }
+}