@incremark/vue 0.2.7 → 0.3.1

package/README.en.md

@@ -1,15 +1,18 @@
 # @incremark/vue
 
-Vue 3 integration for Incremark.
+Vue 3 integration library for Incremark, providing high-performance streaming Markdown rendering components.
 
 **[🇨🇳 中文](./README.md)** | 🇺🇸 English
 
-## Features
+## Core Advantages
 
-- 📦 **Out of the Box** - Provides `useIncremark` composable and `<Incremark>` component
-- 🎨 **Customizable** - Support for custom render components
-- ⚡ **High Performance** - Optimized with `shallowRef` and `markRaw`
-- 🔧 **DevTools** - Built-in developer tools
+- 📦 **Out of the Box** - Provides `IncremarkContent` component and `useIncremark` composable
+- ⚡ **Extreme Performance** - Incremental parsing with O(n) complexity, dual-engine support
+- ⌨️ **Typewriter Effect** - Built-in animation effects (fade-in, typing)
+- 🎨 **Highly Customizable** - Custom components, code blocks, containers
+- 🎯 **Theme System** - Built-in ThemeProvider with light/dark themes
+- 📜 **Auto Scroll** - Built-in AutoScrollContainer component
+- 🔧 **DevTools** - Built-in developer debugging tools
 
 ## Installation
 
@@ -19,20 +22,56 @@ pnpm add @incremark/core @incremark/vue
 
 ## Quick Start
 
-**1. Import Styles**
+### Recommended: IncremarkContent Component
 
-```ts
+```vue
+<script setup>
+import { ref } from 'vue'
+import { IncremarkContent } from '@incremark/vue'
 import '@incremark/vue/style.css'
+
+const content = ref('')
+const isFinished = ref(false)
+
+// Handle AI streaming output
+async function handleStream(stream) {
+  content.value = ''
+  isFinished.value = false
+  
+  for await (const chunk of stream) {
+    content.value += chunk
+  }
+  
+  isFinished.value = true
+}
+</script>
+
+<template>
+  <button @click="handleStream(stream)">Start</button>
+  <IncremarkContent 
+    :content="content" 
+    :is-finished="isFinished"
+    :incremark-options="{
+      gfm: true,
+      math: true,
+      containers: true,
+      htmlTree: true
+    }"
+  />
+</template>
 ```
 
-**2. Use in Your Component**
+### Advanced: useIncremark Composable
 
 ```vue
 <script setup>
 import { useIncremark, Incremark } from '@incremark/vue'
 import '@incremark/vue/style.css'
 
-const { blocks, append, finalize, reset } = useIncremark({ gfm: true })
+const { blocks, append, finalize, reset } = useIncremark({ 
+  gfm: true,
+  math: true
+})
 
 async function handleStream(stream) {
   reset()
@@ -44,89 +83,200 @@ async function handleStream(stream) {
 </script>
 
 <template>
-  <button @click="handleStream">Start</button>
+  <button @click="handleStream(stream)">Start</button>
   <Incremark :blocks="blocks" />
 </template>
 ```
 
-## API
+## IncremarkContent Component
 
-### useIncremark(options)
+Declarative all-in-one component, recommended for most scenarios.
 
-Core composable.
+### Props
 
-**Returns:**
+```ts
+interface IncremarkContentProps {
+  // Input (choose one)
+  content?: string                       // Accumulated Markdown string
+  stream?: () => AsyncGenerator<string>  // Async generator function
+
+  // Status
+  isFinished?: boolean                   // Stream finished flag (required for content mode)
+
+  // Configuration
+  incremarkOptions?: {
+    gfm?: boolean              // GFM support
+    math?: boolean             // Math formulas
+    htmlTree?: boolean         // HTML structured parsing
+    containers?: boolean       // ::: container syntax
+    typewriter?: {             // Typewriter effect
+      enabled?: boolean
+      charsPerTick?: number | [number, number]
+      tickInterval?: number
+      effect?: 'none' | 'fade-in' | 'typing'
+      cursor?: string
+    }
+  }
 
-| Property | Type | Description |
-|----------|------|-------------|
-| `markdown` | `Ref<string>` | Complete Markdown |
-| `blocks` | `ComputedRef<Block[]>` | All blocks |
-| `completedBlocks` | `ShallowRef<Block[]>` | Completed blocks |
-| `pendingBlocks` | `ShallowRef<Block[]>` | Pending blocks |
-| `append` | `Function` | Append content |
-| `finalize` | `Function` | Complete parsing |
-| `reset` | `Function` | Reset state |
-| `render` | `Function` | Render once (reset + append + finalize) |
+  // Custom rendering
+  components?: ComponentMap                        // Custom components
+  customContainers?: Record<string, Component>     // Custom containers
+  customCodeBlocks?: Record<string, Component>     // Custom code blocks
+  codeBlockConfigs?: Record<string, CodeBlockConfig>
 
-### useDevTools(incremark)
+  // Styling
+  showBlockStatus?: boolean    // Show block status border
+  pendingClass?: string        // CSS class for pending blocks
+}
+```
 
-Enable DevTools.
+### Example: Enable Typewriter Effect
 
-```ts
-const incremark = useIncremark()
-useDevTools(incremark)
+```vue
+<IncremarkContent 
+  :content="content" 
+  :is-finished="isFinished"
+  :incremark-options="{
+    gfm: true,
+    typewriter: {
+      enabled: true,
+      charsPerTick: [1, 3],
+      tickInterval: 30,
+      effect: 'fade-in'
+    }
+  }"
+/>
 ```
 
-### \<Incremark\>
+### Example: Custom Components
+
+```vue
+<script setup>
+import CustomHeading from './CustomHeading.vue'
+import WarningContainer from './WarningContainer.vue'
+import EchartsCodeBlock from './EchartsCodeBlock.vue'
+</script>
+
+<template>
+  <IncremarkContent 
+    :content="content" 
+    :is-finished="isFinished"
+    :components="{ heading: CustomHeading }"
+    :custom-containers="{ warning: WarningContainer }"
+    :custom-code-blocks="{ echarts: EchartsCodeBlock }"
+    :code-block-configs="{ echarts: { takeOver: true } }"
+  />
+</template>
+```
 
-Render component.
+## Theme System
 
 ```vue
-<Incremark 
-  :blocks="blocks"
-  :components="{ heading: MyHeading }"
-/>
+<script setup>
+import { ThemeProvider, IncremarkContent } from '@incremark/vue'
+</script>
+
+<template>
+  <!-- Built-in theme -->
+  <ThemeProvider theme="dark">
+    <IncremarkContent :content="content" :is-finished="isFinished" />
+  </ThemeProvider>
+
+  <!-- Custom theme -->
+  <ThemeProvider :theme="{ color: { brand: { primary: '#8b5cf6' } } }">
+    <IncremarkContent :content="content" :is-finished="isFinished" />
+  </ThemeProvider>
+</template>
 ```
 
-## Custom Components
+## Auto Scroll
 
 ```vue
 <script setup>
-import { useIncremark, Incremark } from '@incremark/vue'
-import MyCode from './MyCode.vue'
+import { ref } from 'vue'
+import { AutoScrollContainer, IncremarkContent } from '@incremark/vue'
 
-const { blocks } = useIncremark()
+const scrollRef = ref()
+const autoScrollEnabled = ref(true)
 </script>
 
 <template>
-  <Incremark 
-    :blocks="blocks" 
-    :components="{ code: MyCode }"
-  />
+  <AutoScrollContainer 
+    ref="scrollRef" 
+    :enabled="autoScrollEnabled"
+    :threshold="50"
+    behavior="smooth"
+  >
+    <IncremarkContent :content="content" :is-finished="isFinished" />
+  </AutoScrollContainer>
+  
+  <button @click="scrollRef?.scrollToBottom()">
+    Scroll to Bottom
+  </button>
 </template>
 ```
 
-## Math Formula Support
+## useIncremark API
 
-```bash
-pnpm add micromark-extension-math mdast-util-math katex
+```ts
+const {
+  // State
+  markdown,           // Ref<string> - Complete Markdown
+  blocks,             // ComputedRef<Block[]> - All blocks
+  completedBlocks,    // ShallowRef<Block[]> - Completed blocks
+  pendingBlocks,      // ShallowRef<Block[]> - Pending blocks
+  isLoading,          // Ref<boolean> - Is loading
+  isDisplayComplete,  // ComputedRef<boolean> - Is display complete
+  
+  // Methods
+  append,             // (chunk: string) => IncrementalUpdate
+  finalize,           // () => IncrementalUpdate
+  reset,              // () => void
+  render,             // (content: string) => IncrementalUpdate
+  
+  // Typewriter controls
+  typewriter: {
+    enabled,          // Ref<boolean> - Is enabled
+    isProcessing,     // Ref<boolean> - Is processing
+    skip,             // () => void - Skip animation
+    setOptions        // (options) => void - Update config
+  }
+} = useIncremark(options)
 ```
 
+## DevTools
+
 ```vue
 <script setup>
-import { useIncremark } from '@incremark/vue'
-import { math } from 'micromark-extension-math'
-import { mathFromMarkdown } from 'mdast-util-math'
-import 'katex/dist/katex.min.css'
+import { useIncremark, useDevTools, Incremark } from '@incremark/vue'
 
-const { blocks } = useIncremark({
-  extensions: [math()],
-  mdastExtensions: [mathFromMarkdown()]
-})
+const incremark = useIncremark()
+useDevTools(incremark)
 </script>
+
+<template>
+  <Incremark :blocks="incremark.blocks" />
+</template>
+```
+
+## Math Formula Support
+
+Built-in support, just enable `math: true`:
+
+```vue
+<IncremarkContent 
+  :content="content" 
+  :is-finished="isFinished"
+  :incremark-options="{ math: true }"
+/>
+```
+
+Import KaTeX styles:
+
+```ts
+import 'katex/dist/katex.min.css'
 ```
 
 ## License
 
 MIT
-

package/dist/components/ConfigProvider.vue.d.ts

@@ -0,0 +1,19 @@
+import type { IncremarkLocale } from '@incremark/shared';
+interface Props {
+    /** locale 对象 */
+    locale?: IncremarkLocale;
+}
+declare var __VLS_1: {};
+type __VLS_Slots = {} & {
+    default?: (props: typeof __VLS_1) => any;
+};
+declare const __VLS_component: import("vue").DefineComponent<Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<Props> & Readonly<{}>, {
+    locale: IncremarkLocale;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: __VLS_WithSlots<typeof __VLS_component, __VLS_Slots>;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/components/Incremark.vue.d.ts

@@ -12,13 +12,6 @@ export interface CodeBlockConfig {
     /** 是否从一开始就接管渲染，而不是等到 completed 状态 */
     takeOver?: boolean;
 }
-/**
- * 代码块配置
- */
-export interface CodeBlockConfig {
-    /** 是否从一开始就接管渲染，而不是等到 completed 状态 */
-    takeOver?: boolean;
-}
 type __VLS_Props = {
     /** 要渲染的块列表（来自 useIncremark 的 blocks） */
     blocks?: RenderableBlock[];

package/dist/components/IncremarkCode.vue.d.ts

@@ -1,7 +1,7 @@
 import type { Code } from 'mdast';
 import type { Component } from 'vue';
 import type { CodeBlockConfig } from './Incremark.vue';
-type __VLS_Props = {
+interface Props {
     node: Code;
     /** Shiki 主题，默认 github-dark */
     theme?: string;
@@ -17,14 +17,17 @@ type __VLS_Props = {
     codeBlockConfigs?: Record<string, CodeBlockConfig>;
     /** 块状态，用于判断是否使用自定义组件 */
     blockStatus?: 'pending' | 'stable' | 'completed';
-};
-declare const _default: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+    /** 默认代码块渲染组件（当不是 mermaid 且没有自定义组件时使用） */
+    defaultCodeComponent?: Component;
+}
+declare const _default: import("vue").DefineComponent<Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<Props> & Readonly<{}>, {
     theme: string;
+    mermaidDelay: number;
     fallbackTheme: string;
     disableHighlight: boolean;
-    mermaidDelay: number;
     customCodeBlocks: Record<string, Component>;
     codeBlockConfigs: Record<string, CodeBlockConfig>;
     blockStatus: "pending" | "stable" | "completed";
+    defaultCodeComponent: Component;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 export default _default;

package/dist/components/IncremarkCodeDefault.vue.d.ts

@@ -0,0 +1,16 @@
+import type { Code } from 'mdast';
+interface Props {
+    node: Code;
+    /** Shiki 主题，默认 github-dark */
+    theme?: string;
+    /** 默认回退主题（当指定主题加载失败时使用），默认 github-dark */
+    fallbackTheme?: string;
+    /** 是否禁用代码高亮 */
+    disableHighlight?: boolean;
+}
+declare const _default: import("vue").DefineComponent<Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<Props> & Readonly<{}>, {
+    theme: string;
+    fallbackTheme: string;
+    disableHighlight: boolean;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+export default _default;

package/dist/components/IncremarkCodeMermaid.vue.d.ts

@@ -0,0 +1,10 @@
+import type { Code } from 'mdast';
+interface Props {
+    node: Code;
+    /** Mermaid 渲染延迟（毫秒），用于流式输入时防抖 */
+    mermaidDelay?: number;
+}
+declare const _default: import("vue").DefineComponent<Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<Props> & Readonly<{}>, {
+    mermaidDelay: number;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+export default _default;

package/dist/components/SvgIcon.vue.d.ts

@@ -0,0 +1,13 @@
+/**
+ * SvgIcon 组件
+ *
+ * 直接渲染 SVG 字符串
+ */
+interface Props {
+    /** SVG 字符串内容 */
+    svg: string;
+    /** 图标大小 class，如 incremark-icon--sm, incremark-icon--md 等 */
+    sizeClass?: string;
+}
+declare const _default: import("vue").DefineComponent<Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+export default _default;

package/dist/composables/index.d.ts

@@ -6,3 +6,4 @@ export { useDevTools } from './useDevTools';
 export type { UseDevToolsOptions } from './useDevTools';
 export { useBlockTransformer } from './useBlockTransformer';
 export type { UseBlockTransformerOptions, UseBlockTransformerReturn } from './useBlockTransformer';
+export { useLocale, type UseLocaleReturn } from './useLocale';

package/dist/composables/useIncremark.d.ts

@@ -1,5 +1,5 @@
 import { type ComputedRef, type MaybeRefOrGetter } from 'vue';
-import { type ParserOptions, type ParsedBlock, type IncrementalUpdate, type Root, type TransformerPlugin, type AnimationEffect } from '@incremark/core';
+import { type IncremarkParserOptions, type ParsedBlock, type IncrementalUpdate, type Root, type TransformerPlugin, type AnimationEffect } from '@incremark/core';
 /** 打字机效果配置 */
 export interface TypewriterOptions {
     /** 是否启用打字机效果（可响应式切换） */
@@ -17,7 +17,7 @@ export interface TypewriterOptions {
     /** 自定义插件 */
     plugins?: TransformerPlugin[];
 }
-export interface UseIncremarkOptions extends ParserOptions {
+export interface UseIncremarkOptions extends IncremarkParserOptions {
     /** 打字机配置，传入即创建 transformer（可通过 enabled 控制是否启用） */
     typewriter?: TypewriterOptions;
 }

package/dist/composables/useLocale.d.ts

@@ -0,0 +1,21 @@
+import { type Ref, type ComputedRef, type InjectionKey } from 'vue';
+import type { IncremarkLocale } from '@incremark/shared';
+/**
+ * Locale 注入 key，用于 provide/inject
+ */
+declare const LOCALE_KEY: InjectionKey<Ref<IncremarkLocale>>;
+/**
+ * Vue 国际化 Hook
+ */
+export interface UseLocaleReturn {
+    /** 翻译函数 */
+    t: ComputedRef<(key: string) => string>;
+}
+/**
+ * 使用 locale
+ */
+export declare function useLocale(): UseLocaleReturn;
+/**
+ * 提供 locale 的 key（用于 ConfigProvider）
+ */
+export { LOCALE_KEY };

package/dist/composables/useShiki.d.ts

@@ -47,8 +47,12 @@ declare class ShikiManager {
      */
     disposeAll(): void;
 }
-declare const shikiManager: ShikiManager;
-export { shikiManager, ShikiManager };
+/**
+ * 获取 ShikiManager 单例（延迟初始化）
+ * 避免模块加载时立即创建实例，支持 SSR
+ */
+declare function getShikiManager(): ShikiManager;
+export { getShikiManager, ShikiManager };
 /**
  * 使用 Shiki Highlighter（组合式函数）
  *

package/dist/index.d.ts

@@ -1,9 +1,14 @@
-export { useIncremark, useStreamRenderer, useDevTools, useBlockTransformer } from './composables';
+export { useIncremark, useStreamRenderer, useDevTools, useBlockTransformer, useLocale } from './composables';
 export { useProvideDefinations } from './composables/useProvideDefinations';
 export { useDefinationsContext } from './composables/useDefinationsContext';
 export type { UseIncremarkOptions, TypewriterOptions, TypewriterControls, UseStreamRendererOptions, UseDevToolsOptions, UseBlockTransformerOptions, UseBlockTransformerReturn } from './composables';
 export * from './components';
 export { default as ThemeProvider } from './ThemeProvider.vue';
+export { default as ConfigProvider } from './components/ConfigProvider.vue';
 export type { ParsedBlock, IncrementalUpdate, ParserOptions, BlockStatus, Root, RootContent, SourceBlock, DisplayBlock, TransformerPlugin, TransformerOptions, TransformerState, AnimationEffect } from '@incremark/core';
 export { BlockTransformer, createBlockTransformer, countChars, sliceAst, cloneNode, codeBlockPlugin, mermaidPlugin, imagePlugin, mathPlugin, thematicBreakPlugin, defaultPlugins, allPlugins, createPlugin } from '@incremark/core';
 export { type DesignTokens, defaultTheme, darkTheme, generateCSSVars, mergeTheme, applyTheme } from '@incremark/theme';
+import { en as enShared, zhCN as zhCNShared } from '@incremark/shared';
+import type { IncremarkLocale } from '@incremark/shared';
+export { enShared as en, zhCNShared as zhCN };
+export type { IncremarkLocale };