@incremark/vue 0.0.4 → 0.0.5

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

@@ -61,6 +61,9 @@ function escapeHtml(str: string): string {
     <del v-else-if="node.type === 'delete'">
       <IncremarkInline :nodes="(node.children as PhrasingContent[])" />
     </del>
+
+    <!-- 原始 HTML（用于 fade-mask 等特殊元素） -->
+    <span v-else-if="(node as any).type === 'html'" v-html="(node as any).value"></span>
   </template>
 </template>
 

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

@@ -6,3 +6,6 @@ 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
+  }
+}

package/src/index.ts

@@ -1,6 +1,12 @@
 // Composables
-export { useIncremark, useStreamRenderer, useDevTools } from './composables'
-export type { UseIncremarkOptions, UseStreamRendererOptions, UseDevToolsOptions } from './composables'
+export { useIncremark, useStreamRenderer, useDevTools, useBlockTransformer } from './composables'
+export type {
+  UseIncremarkOptions,
+  UseStreamRendererOptions,
+  UseDevToolsOptions,
+  UseBlockTransformerOptions,
+  UseBlockTransformerReturn
+} from './composables'
 
 // Components
 export {
@@ -15,7 +21,8 @@ export {
   IncremarkThematicBreak,
   IncremarkInline,
   IncremarkMath,
-  IncremarkDefault
+  IncremarkDefault,
+  AutoScrollContainer
 } from './components'
 export type { ComponentMap, BlockWithStableId } from './components'
 
@@ -26,5 +33,29 @@ export type {
   ParserOptions,
   BlockStatus,
   Root,
-  RootContent
+  RootContent,
+  // Transformer types
+  SourceBlock,
+  DisplayBlock,
+  TransformerPlugin,
+  TransformerOptions,
+  TransformerState,
+  AnimationEffect
+} from '@incremark/core'
+
+// Re-export transformer utilities and plugins
+export {
+  BlockTransformer,
+  createBlockTransformer,
+  countChars,
+  sliceAst,
+  cloneNode,
+  codeBlockPlugin,
+  mermaidPlugin,
+  imagePlugin,
+  mathPlugin,
+  thematicBreakPlugin,
+  defaultPlugins,
+  allPlugins,
+  createPlugin
 } from '@incremark/core'