@preferred-markdown-stream/vue 0.1.0

package/README.md

@@ -0,0 +1,32 @@
+# @preferred-markdown-stream/vue
+
+Vue bindings and runtime helpers for streaming Markdown rendering.
+
+## Installation
+
+```bash
+pnpm add @preferred-markdown-stream/vue vue
+```
+
+## Usage
+
+```ts
+import {
+  createStreamingMarkdownVNodes,
+  createVNodeRendererComponent,
+} from '@preferred-markdown-stream/vue'
+```
+
+## Public API
+
+- `addFadeInToVNodes(children, loading, fadeInClass?)`
+- `createStreamingMarkdownVNodes(content, loading)`
+- `createVNodeRendererComponent(vnodes)`
+- `setCodeBlockComponent(component)`
+
+## Notes
+
+- The package currently preserves the app's existing runtime behavior.
+- `fadeIn.ts` adapts the framework-agnostic tree animation helper for Vue VNodes.
+- `runtime.ts` stays internal and owns the Markdown renderer instance plus lazy capability loading.
+- `useStreamingMarkdown.ts` contains the repeated Vue wiring that was previously duplicated inside app components.

package/dist/fadeIn.d.ts

@@ -0,0 +1,2 @@
+import type { VNode } from 'vue';
+export declare function addFadeInToVNodes(childrenRaw: VNode[], loading: boolean, fadeInClass?: string): VNode[];

package/dist/fadeIn.js

@@ -0,0 +1,4 @@
+import { addFadeInClassToTreeNodes } from '@preferred-markdown-stream/core';
+export function addFadeInToVNodes(childrenRaw, loading, fadeInClass = 'fade-in') {
+    return addFadeInClassToTreeNodes(childrenRaw, loading, fadeInClass);
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { addFadeInToVNodes, } from './fadeIn.js';
+export { setCodeBlockComponent, } from './render.js';
+export { createStreamingMarkdownVNodes, createVNodeRendererComponent, } from './useStreamingMarkdown.js';

package/dist/index.js

@@ -0,0 +1,3 @@
+export { addFadeInToVNodes, } from './fadeIn.js';
+export { setCodeBlockComponent, } from './render.js';
+export { createStreamingMarkdownVNodes, createVNodeRendererComponent, } from './useStreamingMarkdown.js';

package/dist/render.d.ts

@@ -0,0 +1,17 @@
+export interface Plugin<Ctx = any> {
+    name: string;
+    register?: (ctx: Ctx) => any;
+}
+export declare const DOM_ATTR_NAME: {
+    SOURCE_LINE_START: string;
+    SOURCE_LINE_END: string;
+    ORIGIN_SRC: string;
+    ORIGIN_HREF: string;
+    LOCAL_IMAGE: string;
+    ONLY_CHILD: string;
+    TOKEN_IDX: string;
+    DISPLAY_NONE: string;
+};
+export declare function setCodeBlockComponent(component: any): void;
+declare function render_(md: any): void;
+export default render_;

package/dist/render.js

@@ -0,0 +1,326 @@
+import { escapeHtml, unescapeAll } from 'markdown-it/lib/common/utils.mjs';
+import { Comment, createVNode, Fragment, h, Text, } from 'vue';
+export const DOM_ATTR_NAME = {
+    SOURCE_LINE_START: 'data-source-line',
+    SOURCE_LINE_END: 'data-source-line-end',
+    ORIGIN_SRC: 'origin-src',
+    ORIGIN_HREF: 'origin-href',
+    LOCAL_IMAGE: 'local-image',
+    ONLY_CHILD: 'auto-center',
+    TOKEN_IDX: 'data-token-idx',
+    DISPLAY_NONE: 'display-none',
+};
+const sensitiveUrlReg = /^javascript:|vbscript:|file:/i;
+const sensitiveAttrReg = /^href|src|xlink:href|poster/i;
+const attrNameReg = /^[a-z_:][\w:.-]*$/i;
+const attrEventReg = /^on/i;
+const CODE_INFO_SPLIT_REGEXP = /(\s+)/g;
+const STREAMING_TEXT_SPLIT_REGEXP = /(?<=[。？！；、，,;\n])|(?<!\w\.\w.)(?<![A-Z][a-z]\.)(?<=[.?!`])/g;
+const defaultRules = {};
+function validateAttrName(name) {
+    return attrNameReg.test(name) && !attrEventReg.test(name);
+}
+function getLine(token, env) {
+    const [lineStart, lineEnd] = token.map || [0, 1];
+    // macro, calc line offset, see `markdown-macro` plugin.
+    let sOffset = 0;
+    if (env?.macroLines && env.bMarks && env.eMarks) {
+        const sPos = env.bMarks[lineStart];
+        for (let i = 0; i < env.macroLines.length; i++) {
+            const { matchPos, lineOffset, posOffset, currentPosOffset } = env.macroLines[i];
+            if (sPos + posOffset > matchPos
+                && sPos + posOffset - currentPosOffset > matchPos) {
+                sOffset = lineOffset;
+            }
+            else {
+                break;
+            }
+        }
+    }
+    return [lineStart + sOffset, lineEnd + sOffset];
+}
+function processToken(token, env) {
+    if (!token.meta) {
+        token.meta = {};
+    }
+    if (env?.safeMode && token.attrs) {
+        for (let [name, val] of token.attrs) {
+            name = name.toLowerCase();
+            if (sensitiveAttrReg.test(name) && sensitiveUrlReg.test(val)) {
+                token.attrSet(name, '');
+            }
+            if (name === 'href' && val.toLowerCase().startsWith('data:')) {
+                token.attrSet(name, '');
+            }
+        }
+    }
+    if (token.block) {
+        const [lineStart, lineEnd] = getLine(token, env);
+        if (token.map) {
+            token.attrSet(DOM_ATTR_NAME.SOURCE_LINE_START, String(lineStart + 1));
+            token.attrSet(DOM_ATTR_NAME.SOURCE_LINE_END, String(lineEnd + 1));
+            if (!token.meta.attrs) {
+                token.meta.attrs = {};
+            }
+            // transform array to object
+            if (token.attrs) {
+                for (const [name, val] of token.attrs) {
+                    token.meta.attrs[name] = val;
+                }
+            }
+        }
+    }
+}
+defaultRules.code_inline = function (tokens, idx, _, __, slf) {
+    const token = tokens[idx];
+    return createVNode('code', { ...slf.renderAttrs(token), key: idx }, token.content);
+};
+defaultRules.code_block = function (tokens, idx, _, __, slf) {
+    const token = tokens[idx];
+    const attrs = slf.renderAttrs(token);
+    const preAttrs = {
+        [DOM_ATTR_NAME.SOURCE_LINE_START]: attrs[DOM_ATTR_NAME.SOURCE_LINE_START],
+        [DOM_ATTR_NAME.SOURCE_LINE_END]: attrs[DOM_ATTR_NAME.SOURCE_LINE_END],
+    };
+    delete attrs[DOM_ATTR_NAME.SOURCE_LINE_START];
+    delete attrs[DOM_ATTR_NAME.SOURCE_LINE_END];
+    return h('pre', preAttrs, [
+        h('code', attrs, [createVNode(Text, {}, token.content)]),
+    ]);
+};
+/**
+ * Custom code block component slot.
+ * When set via `setCodeBlockComponent()`, the fence rule delegates rendering
+ * to this component instead of the default `pre > code`.
+ *
+ * The component receives props: `{ language: string, content: string, preAttrs: Record<string, any> }`
+ * where `content` is the highlighted HTML string.
+ */
+let customCodeBlockComponent = null;
+export function setCodeBlockComponent(component) {
+    customCodeBlockComponent = component;
+}
+// fence rule
+defaultRules.fence = function (tokens, idx, options, _, slf) {
+    const token = tokens[idx];
+    const info = token.info ? unescapeAll(token.info).trim() : '';
+    let langName = '';
+    let langAttrs = '';
+    let i;
+    let arr;
+    let tmpAttrs;
+    let tmpToken;
+    if (info) {
+        arr = info.split(CODE_INFO_SPLIT_REGEXP);
+        langName = arr[0];
+        langAttrs = arr.slice(2).join('');
+    }
+    const highlighted = options.highlight
+        ? options.highlight(token.content, langName, langAttrs)
+            || escapeHtml(token.content)
+        : escapeHtml(token.content);
+    const buildVNode = (attrs) => {
+        const preAttrs = {
+            'data-info': info,
+            'data-lang': langName,
+            [DOM_ATTR_NAME.SOURCE_LINE_START]: attrs[DOM_ATTR_NAME.SOURCE_LINE_START],
+            [DOM_ATTR_NAME.SOURCE_LINE_END]: attrs[DOM_ATTR_NAME.SOURCE_LINE_END],
+        };
+        delete attrs[DOM_ATTR_NAME.SOURCE_LINE_START];
+        delete attrs[DOM_ATTR_NAME.SOURCE_LINE_END];
+        if (customCodeBlockComponent) {
+            return h(customCodeBlockComponent, {
+                language: langName,
+                content: highlighted,
+                preAttrs,
+            });
+        }
+        // Default: simple pre > code
+        return h('pre', preAttrs, [
+            createVNode('code', { innerHTML: highlighted }, []),
+        ]);
+    };
+    // If language exists, inject class gently, without modifying original token.
+    if (info) {
+        i = token.attrIndex('class');
+        tmpAttrs = token.attrs ? [...token.attrs] : [];
+        if (i < 0) {
+            tmpAttrs.push(['class', options.langPrefix + langName]);
+        }
+        else {
+            tmpAttrs[i] = [...tmpAttrs[i]];
+            tmpAttrs[i][1] += ` ${options.langPrefix}${langName}`;
+        }
+        // Fake token just to render attributes
+        tmpToken = {
+            attrs: tmpAttrs,
+        };
+        return buildVNode(slf.renderAttrs(tmpToken));
+    }
+    return buildVNode(slf.renderAttrs(token));
+};
+defaultRules.image = function (tokens, idx, options, env, slf) {
+    const token = tokens[idx];
+    return h('img', {
+        ...slf.renderAttrs(token),
+        alt: slf.renderInlineAsText(token.children || [], options, env),
+    }, []);
+};
+defaultRules.hardbreak = function (_, idx) {
+    return h('br', { key: idx });
+};
+defaultRules.softbreak = function (_, idx, options) {
+    return options.breaks ? h('br', { key: idx }) : null;
+};
+defaultRules.list_item_open = function (tokens, idx, _, __, self) {
+    return h('li', { key: idx, ...self.renderAttrs(tokens[idx]) }, []);
+};
+defaultRules.paragraph_open = function (tokens, idx, _, __, self) {
+    // 强制添加 p 标签，即使单个列表项。从而防止列表项元素突变。
+    return h('p', { key: idx, ...self.renderAttrs(tokens[idx]) }, []);
+};
+defaultRules.text = function (tokens, idx, _, env) {
+    const token = tokens[idx];
+    if (env.sanitize) {
+        // 检查 content 是否包含是句尾符号，如 '，', '。', '？', '！', '. '
+        // 使用
+        // 分割英语 (?<!\w\.\w.)(?<![A-Z][a-z]\.)(?<=\.|\?)
+        // 分割中文 (?<=[。？！；])
+        const splited = token.content.split(STREAMING_TEXT_SPLIT_REGEXP);
+        return splited.map((content, i) => {
+            return createVNode('span', { key: i }, { default: () => content });
+        });
+    }
+    else {
+        // console.log('text', token)
+        return createVNode(Text, { key: idx }, token.content);
+        // return createVNode(Text, { key: idx }, token.content)
+    }
+};
+defaultRules.html_block = function (tokens, idx) {
+    const token = tokens[idx];
+    if (token.contentVNode) {
+        return token.contentVNode;
+    }
+    return createHtmlVNode(token.content);
+};
+defaultRules.html_inline = function (tokens, idx) {
+    const token = tokens[idx];
+    if (token.contentVNode) {
+        return token.contentVNode;
+    }
+    return createHtmlVNode(token.content);
+};
+function createHtmlVNode(html) {
+    const div = document.createElement('template');
+    div.innerHTML = html;
+    const elements = div.content.children;
+    const children = [];
+    for (const element of elements) {
+        const tagName = element.tagName.toLowerCase();
+        const attrs = {
+            key: element.outerHTML,
+        };
+        for (let j = 0; j < element.attributes.length; j++) {
+            const attr = element.attributes[j];
+            attrs[attr.name] = attr.value;
+        }
+        attrs.innerHTML = element.innerHTML;
+        attrs.key = element.innerHTML;
+        children.push(h(tagName, attrs, []));
+    }
+    return h(Fragment, {}, children);
+}
+function renderToken(tokens, idx) {
+    const token = tokens[idx];
+    if (token.nesting === -1) {
+        return null;
+    }
+    // Tight list paragraphs
+    if (token.hidden) {
+        return createVNode(Fragment, {}, []);
+    }
+    if (token.tag === '--') {
+        return createVNode(Comment);
+    }
+    return createVNode(token.tag, this.renderAttrs(token), []);
+}
+function renderAttrs(token) {
+    if (!token.attrs) {
+        return {};
+    }
+    const result = {};
+    // eslint-disable-next-line unicorn/no-array-for-each
+    token.attrs.forEach((token) => {
+        if (validateAttrName(token[0])) {
+            result[token[0]] = token[1];
+        }
+    });
+    return result;
+}
+function render(tokens, options, env) {
+    const rules = this.rules;
+    const vNodeParents = [];
+    return tokens
+        .map((token, i) => {
+        processToken(token, env);
+        if (token.block) {
+            token.attrSet(DOM_ATTR_NAME.TOKEN_IDX, i.toString());
+        }
+        const { type } = token;
+        let vnode = null;
+        let parent = null;
+        if (type === 'inline') {
+            vnode = this.render(token.children || [], options, env);
+        }
+        else if (rules[type]) {
+            const result = rules[type](tokens, i, options, env, this);
+            if (typeof result === 'string') {
+                vnode = createHtmlVNode(result);
+            }
+            else if (result && result.node && result.parent) {
+                parent = result.parent;
+                vnode = result.node;
+            }
+            else {
+                vnode = result;
+            }
+        }
+        else {
+            vnode = this.renderToken(tokens, i, options);
+        }
+        let isChild = false;
+        const parentNode = vNodeParents.length > 0 ? vNodeParents.at(-1) : null;
+        if (vnode && parentNode) {
+            if (typeof parentNode.type === 'string'
+                || parentNode.type === Fragment) {
+                const children = Array.isArray(parentNode.children)
+                    ? parentNode.children
+                    : [];
+                parentNode.children = [...children, vnode];
+            }
+            isChild = true;
+        }
+        if (token.nesting === 1) {
+            if (parent) {
+                vNodeParents.push(parent);
+            }
+            else if (vnode) {
+                vNodeParents.push(vnode);
+            }
+        }
+        if (token.nesting === -1) {
+            vNodeParents.pop();
+        }
+        return isChild ? null : vnode;
+    })
+        .filter(node => !!node);
+}
+function render_(md) {
+    md.renderer.rules = { ...md.renderer.rules, ...defaultRules };
+    md.renderer.render = render;
+    md.renderer.renderInline = render;
+    md.renderer.renderAttrs = renderAttrs;
+    md.renderer.renderToken = renderToken;
+}
+export default render_;

package/dist/runtime.d.ts

@@ -0,0 +1,6 @@
+import markdownit from 'markdown-it';
+export declare const md: markdownit;
+export declare const isKatexLoaded: import("vue").Ref<boolean, boolean>;
+export declare const isShikiLoaded: import("vue").Ref<boolean, boolean>;
+export declare function loadKatex(): Promise<void>;
+export declare function loadShiki(): Promise<void>;

package/dist/runtime.js

@@ -0,0 +1,65 @@
+import markdownit from 'markdown-it';
+import todo from 'markdown-it-todo';
+import { ref } from 'vue';
+import VNodePlugin from './render.js';
+export const md = markdownit({
+    linkify: true,
+    typographer: true,
+    breaks: true,
+    html: true,
+});
+md.use(VNodePlugin);
+md.use(todo);
+// Lazy load katex and shiki to reduce initial bundle size
+export const isKatexLoaded = ref(false);
+export const isShikiLoaded = ref(false);
+export async function loadKatex() {
+    if (isKatexLoaded.value) {
+        return;
+    }
+    const [katex, texmath] = await Promise.all([
+        import('katex'),
+        import('markdown-it-texmath'),
+        import('katex/dist/katex.min.css'), // Lazy load CSS
+    ]);
+    const tm = texmath.default.use(katex.default);
+    md.use(tm, { delimiters: ['brackets', 'dollars'] });
+    isKatexLoaded.value = true;
+}
+export async function loadShiki() {
+    if (isShikiLoaded.value) {
+        return;
+    }
+    try {
+        const Shiki = await import('@shikijs/markdown-it');
+        const shiki = await Shiki.default({
+            theme: 'vitesse-dark',
+            // Only load most commonly used languages to reduce bundle size
+            langs: [
+                'javascript',
+                'typescript',
+                'python',
+                'bash',
+                'json',
+                'html',
+                'css',
+                'markdown',
+                'vue',
+                'rust',
+                'go',
+                'java',
+                'sql',
+                'jsx',
+                'tsx',
+            ],
+            fallbackLanguage: 'markdown',
+        });
+        md.use(shiki);
+        isShikiLoaded.value = true;
+    }
+    catch (error) {
+        console.error('Failed to load Shiki:', error);
+        // If Shiki fails to load, ensure repeated attempts are skipped.
+        isShikiLoaded.value = true;
+    }
+}

package/dist/useStreamingMarkdown.d.ts

@@ -0,0 +1,14 @@
+import type { Ref, VNode } from 'vue';
+export declare function createStreamingMarkdownVNodes(content: Readonly<Ref<string>>, loading: Readonly<Ref<boolean>>): {
+    contentFinal: import("vue").ComputedRef<string>;
+    contentVNodes: import("@vueuse/core").ComputedRefWithControl<VNode<import("vue").RendererNode, import("vue").RendererElement, {
+        [key: string]: any;
+    }>[]>;
+    debouncedLoading: Ref<boolean, boolean>;
+    formattedContent: import("vue").ComputedRef<string>;
+};
+export declare function createVNodeRendererComponent(vnodes: {
+    value: VNode[];
+}): import("vue").DefineComponent<{}, () => VNode<import("vue").RendererNode, import("vue").RendererElement, {
+    [key: string]: any;
+}>[], {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;

package/dist/useStreamingMarkdown.js

@@ -0,0 +1,62 @@
+import { splitContent } from '@preferred-markdown-stream/core';
+import { computedWithControl } from '@vueuse/core';
+import { computed, defineComponent, ref, watch } from 'vue';
+import { addFadeInToVNodes } from './fadeIn.js';
+import { isKatexLoaded, isShikiLoaded, loadKatex, loadShiki, md, } from './runtime.js';
+function ensureMarkdownCapabilities(content) {
+    if (content.includes('```') || content.includes('`')) {
+        loadShiki();
+    }
+    if (content.includes('$')
+        || content.includes(String.raw `\(`)
+        || content.includes(String.raw `\[`)) {
+        loadKatex();
+    }
+}
+function renderMarkdown(content) {
+    ensureMarkdownCapabilities(content);
+    return md.render(content, {
+        sanitize: true,
+    });
+}
+export function createStreamingMarkdownVNodes(content, loading) {
+    // Trailing-only debounce: true takes effect immediately,
+    // false is delayed so the last batch of content still animates.
+    const debouncedLoading = ref(loading.value);
+    let offTimer;
+    watch(loading, (val) => {
+        if (offTimer !== undefined) {
+            clearTimeout(offTimer);
+            offTimer = undefined;
+        }
+        if (val) {
+            debouncedLoading.value = true;
+        }
+        else {
+            offTimer = setTimeout(() => {
+                debouncedLoading.value = false;
+            }, 1000);
+        }
+    });
+    const formattedContent = computed(() => splitContent(content.value));
+    const contentFinal = computed(() => loading.value ? formattedContent.value : content.value);
+    const contentVNodes = computedWithControl(() => [isShikiLoaded.value, isKatexLoaded.value, contentFinal.value], () => {
+        const currentContent = contentFinal.value ?? '';
+        const rendered = renderMarkdown(currentContent);
+        return addFadeInToVNodes(rendered, debouncedLoading.value);
+    });
+    return {
+        contentFinal,
+        contentVNodes,
+        debouncedLoading,
+        formattedContent,
+    };
+}
+export function createVNodeRendererComponent(vnodes) {
+    return defineComponent({
+        setup() {
+            // eslint-disable-next-line unicorn/consistent-function-scoping
+            return () => vnodes.value;
+        },
+    });
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@preferred-markdown-stream/vue",
+  "type": "module",
+  "version": "0.1.0",
+  "private": false,
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "README.md",
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p ./tsconfig.build.json",
+    "test": "vitest run --config ./vitest.config.ts",
+    "typecheck": "tsc -p ./tsconfig.json"
+  },
+  "peerDependencies": {
+    "vue": "^3.5.0"
+  },
+  "dependencies": {
+    "@preferred-markdown-stream/core": "workspace:*",
+    "@shikijs/markdown-it": "^4.0.2",
+    "@vueuse/core": "^14.2.1",
+    "katex": "^0.16.42",
+    "markdown-it": "^14.1.1",
+    "markdown-it-texmath": "^1.0.0",
+    "markdown-it-todo": "^1.0.5"
+  },
+  "devDependencies": {
+    "@types/markdown-it": "^14.1.2",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.1",
+    "vue": "^3.5.30"
+  }
+}