@incremark/core 0.0.4 → 0.1.0

package/src/transformer/styles.css

@@ -0,0 +1,33 @@
+/**
+ * Incremark BlockTransformer Animation Styles
+ * 
+ * 这些样式用于配合 BlockTransformer 的 effect 选项
+ * 可以直接导入使用，或复制到你的项目中自定义
+ * 
+ * 注意：光标字符已直接内嵌到内容中，以下样式仅供参考
+ */
+
+/* ============ Typing 打字机光标效果 ============ */
+
+/**
+ * 容器需要添加 .incremark-typing 类
+ * 光标字符已直接添加到正在输入的块内容末尾
+ */
+.incremark-typing .incremark-pending {
+  /* 光标字符已内嵌在内容中，默认为 | */
+}
+
+/* ============ 代码块特殊处理 ============ */
+
+/* 代码块内使用等宽字体 */
+.incremark-typing pre,
+.incremark-typing code {
+  font-family: monospace;
+}
+
+/* ============ 工具类 ============ */
+
+/* 平滑过渡 */
+.incremark-smooth * {
+  transition: opacity 0.1s ease-out;
+}

package/src/transformer/types.ts

@@ -0,0 +1,114 @@
+import type { RootContent } from 'mdast'
+
+/**
+ * 源 Block 类型（来自解析器）
+ */
+export interface SourceBlock<T = unknown> {
+  /** 唯一标识 */
+  id: string
+  /** AST 节点 */
+  node: RootContent
+  /** 块状态 */
+  status: 'pending' | 'stable' | 'completed'
+  /** 用户自定义元数据 */
+  meta?: T
+}
+
+/**
+ * 显示用的 Block（转换后）
+ */
+export interface DisplayBlock<T = unknown> extends SourceBlock<T> {
+  /** 用于显示的 AST 节点（可能是截断的） */
+  displayNode: RootContent
+  /** 显示进度 0-1 */
+  progress: number
+  /** 是否已完成显示 */
+  isDisplayComplete: boolean
+}
+
+/**
+ * 动画效果类型
+ * - 'none': 无动画效果
+ * - 'fade-in': 新增字符渐入效果
+ * - 'typing': 打字机光标效果
+ */
+export type AnimationEffect = 'none' | 'fade-in' | 'typing'
+
+/**
+ * Transformer 插件
+ */
+export interface TransformerPlugin {
+  /** 插件名称 */
+  name: string
+
+  /**
+   * 判断是否处理此节点
+   * 返回 true 表示这个插件要处理此节点
+   */
+  match?: (node: RootContent) => boolean
+
+  /**
+   * 自定义字符数计算
+   * 返回 undefined 则使用默认逻辑
+   * 返回 0 表示立即显示（不参与逐字符效果）
+   */
+  countChars?: (node: RootContent) => number | undefined
+
+  /**
+   * 自定义截断逻辑
+   * @param node 原始节点
+   * @param displayedChars 当前应显示的字符数
+   * @param totalChars 该节点的总字符数
+   * @returns 截断后的节点，null 表示不显示
+   */
+  sliceNode?: (
+    node: RootContent,
+    displayedChars: number,
+    totalChars: number
+  ) => RootContent | null
+
+  /**
+   * 节点显示完成时的回调
+   */
+  onComplete?: (node: RootContent) => void
+}
+
+/**
+ * Transformer 配置选项
+ */
+export interface TransformerOptions {
+  /**
+   * 每 tick 增加的字符数
+   * - number: 固定步长（默认 1）
+   * - [min, max]: 随机步长区间（更自然的打字效果）
+   */
+  charsPerTick?: number | [number, number]
+  /** tick 间隔 (ms)，默认 20 */
+  tickInterval?: number
+  /** 动画效果，默认 'none' */
+  effect?: AnimationEffect
+  /** 插件列表 */
+  plugins?: TransformerPlugin[]
+  /** 状态变化回调 */
+  onChange?: (displayBlocks: DisplayBlock[]) => void
+  /**
+   * 是否在页面不可见时自动暂停
+   * 默认 true，节省资源
+   */
+  pauseOnHidden?: boolean
+}
+
+/**
+ * Transformer 内部状态
+ */
+export interface TransformerState<T = unknown> {
+  /** 已完成显示的 blocks */
+  completedBlocks: SourceBlock<T>[]
+  /** 当前正在显示的 block */
+  currentBlock: SourceBlock<T> | null
+  /** 当前 block 已显示的字符数 */
+  currentProgress: number
+  /** 等待显示的 blocks */
+  pendingBlocks: SourceBlock<T>[]
+}
+

package/src/transformer/utils.ts

@@ -0,0 +1,191 @@
+import type { RootContent, Text, Parent } from 'mdast'
+
+/**
+ * 文本块片段（用于渐入动画）
+ */
+export interface TextChunk {
+  /** 文本内容 */
+  text: string
+  /** 创建时间戳 */
+  createdAt: number
+}
+
+/**
+ * 扩展的文本节点（支持 chunks）
+ */
+export interface TextNodeWithChunks extends Text {
+  /** 稳定部分的长度（不需要动画） */
+  stableLength?: number
+  /** 临时的文本片段，用于渐入动画 */
+  chunks?: TextChunk[]
+}
+
+/**
+ * AST 节点的通用类型（文本节点或容器节点）
+ */
+interface AstNode {
+  type: string
+  value?: string
+  children?: AstNode[]
+}
+
+/**
+ * 计算 AST 节点的总字符数
+ */
+export function countChars(node: RootContent): number {
+  let count = 0
+
+  function traverse(n: AstNode): void {
+    if (n.value && typeof n.value === 'string') {
+      count += n.value.length
+      return
+    }
+    if (n.children && Array.isArray(n.children)) {
+      for (const child of n.children) {
+        traverse(child)
+      }
+    }
+  }
+
+  traverse(node as AstNode)
+  return count
+}
+
+/**
+ * 累积的 chunks 信息
+ */
+export interface AccumulatedChunks {
+  /** 已经稳定显示的字符数（不需要动画） */
+  stableChars: number
+  /** 累积的 chunk 列表 */
+  chunks: TextChunk[]
+}
+
+/** chunk 范围信息 */
+interface ChunkRange {
+  start: number
+  end: number
+  chunk: TextChunk
+}
+
+/**
+ * 截断 AST 节点，只保留前 maxChars 个字符
+ * 支持 chunks（用于渐入动画）
+ * 
+ * @param node 原始节点
+ * @param maxChars 最大字符数
+ * @param accumulatedChunks 累积的 chunks 信息（用于渐入动画）
+ * @returns 截断后的节点，如果 maxChars <= 0 返回 null
+ */
+export function sliceAst(
+  node: RootContent, 
+  maxChars: number,
+  accumulatedChunks?: AccumulatedChunks
+): RootContent | null {
+  if (maxChars <= 0) return null
+
+  let remaining = maxChars
+  let charIndex = 0
+  
+  // 计算 chunks 在文本中的范围
+  const chunkRanges: ChunkRange[] = []
+  if (accumulatedChunks && accumulatedChunks.chunks.length > 0) {
+    let chunkStart = accumulatedChunks.stableChars
+    for (const chunk of accumulatedChunks.chunks) {
+      chunkRanges.push({
+        start: chunkStart,
+        end: chunkStart + chunk.text.length,
+        chunk
+      })
+      chunkStart += chunk.text.length
+    }
+  }
+
+  function process(n: AstNode): AstNode | null {
+    if (remaining <= 0) return null
+
+    // 文本类节点：截断 value，可能添加 chunks
+    if (n.value && typeof n.value === 'string') {
+      const take = Math.min(n.value.length, remaining)
+      remaining -= take
+      if (take === 0) return null
+
+      const slicedValue = n.value.slice(0, take)
+      const nodeStart = charIndex
+      const nodeEnd = charIndex + take
+      charIndex += take
+      
+      const result: AstNode & { stableLength?: number; chunks?: TextChunk[] } = { 
+        ...n, 
+        value: slicedValue 
+      }
+      
+      // 检查是否有 chunks 落在这个节点范围内
+      if (chunkRanges.length > 0 && accumulatedChunks) {
+        const nodeChunks: TextChunk[] = []
+        let firstChunkLocalStart = take  // 第一个 chunk 在节点中的起始位置
+        
+        for (const range of chunkRanges) {
+          // 计算 chunk 与当前节点的交集
+          const overlapStart = Math.max(range.start, nodeStart)
+          const overlapEnd = Math.min(range.end, nodeEnd)
+          
+          if (overlapStart < overlapEnd) {
+            // 有交集，提取对应的文本
+            const localStart = overlapStart - nodeStart
+            const localEnd = overlapEnd - nodeStart
+            const chunkText = slicedValue.slice(localStart, localEnd)
+            
+            if (chunkText.length > 0) {
+              // 记录第一个 chunk 的起始位置
+              if (nodeChunks.length === 0) {
+                firstChunkLocalStart = localStart
+              }
+              nodeChunks.push({
+                text: chunkText,
+                createdAt: range.chunk.createdAt
+              })
+            }
+          }
+        }
+        
+        if (nodeChunks.length > 0) {
+          result.stableLength = firstChunkLocalStart
+          result.chunks = nodeChunks
+        }
+      }
+      
+      return result
+    }
+
+    // 容器节点：递归处理 children
+    if (n.children && Array.isArray(n.children)) {
+      const newChildren: AstNode[] = []
+      for (const child of n.children) {
+        if (remaining <= 0) break
+        const processed = process(child)
+        if (processed) {
+          newChildren.push(processed)
+        }
+      }
+      if (newChildren.length === 0) {
+        return null
+      }
+      return { ...n, children: newChildren }
+    }
+
+    // 其他节点（如 thematicBreak, image）
+    remaining -= 1
+    charIndex += 1
+    return { ...n }
+  }
+
+  return process(node as AstNode) as RootContent | null
+}
+
+/**
+ * 深拷贝 AST 节点
+ */
+export function cloneNode<T extends RootContent>(node: T): T {
+  return JSON.parse(JSON.stringify(node))
+}