@antdv-next/x-markdown 0.2.0 → 0.3.0

package/dist/XMarkdown/interface.d.ts

@@ -15,6 +15,8 @@ export interface FenceState {
     inFenced: boolean;
     fenceChar: string;
     fenceLen: number;
+    /** Spaces before the fence run of the current line; a fence may be indented up to 3 */
+    lineIndent: number;
     /** Leading `` ` ``/`~` run of the current (possibly incomplete) line */
     lineFenceChar: string;
     lineFenceLen: number;
@@ -22,25 +24,244 @@ export interface FenceState {
     /** Whether every char after the leading run is whitespace (closing fences allow only whitespace) */
     lineTailBlank: boolean;
 }
+/**
+ * Incremental table-shape state over `pending`, updated in O(1) per character —
+ * the same trick FenceState already uses. Re-scanning the whole pending buffer
+ * on every character is O(N²), and a table stays pending until its terminating
+ * blank line, so a long table pays that cost in full.
+ */
+export interface TableState {
+    /** Number of '\n' seen in pending */
+    newlines: number;
+    /** Whether the previous character was '\n' (used to detect the '\n\n' terminator) */
+    lastWasNewline: boolean;
+    /** pending contains a blank line, i.e. the table block already ended */
+    hasBlankLine: boolean;
+    /** pending's first line — the header row */
+    firstLine: string;
+    /** pending's second line — the delimiter row; may still be growing */
+    secondLine: string;
+    /**
+     * Memoized header/delimiter verdict. Stays null while the delimiter row is
+     * still being streamed (the verdict can change as it grows) and is frozen
+     * once that row is terminated, after which it never changes again.
+     */
+    shape: boolean | null;
+}
+/**
+ * Incremental section-boundary state for `streaming.incremental`. A section
+ * boundary is an offset (into the input) where a new top-level block starts
+ * and everything before it can be parsed on its own with the same result as
+ * parsing the whole document. Only column-0 ATX headings qualify, and whether
+ * such a line really starts a top-level block is decided by lexing the current
+ * section with marked (`trackSectionBoundary`) — never by a hand-written model
+ * of marked's block grammar.
+ */
+export interface SectionState {
+    /** Offsets where a new section starts. The first section implicitly starts at 0. */
+    offsets: number[];
+    /** Offset of the first character of the line currently being streamed */
+    lineStart: number;
+    /**
+     * Set once a construct that can be referenced from another section has been
+     * seen (link reference / footnote definition). Splitting is disabled for the
+     * rest of the stream and any offsets recorded so far are discarded.
+     */
+    noSplit: boolean;
+    /**
+     * Set once any line has carried the label terminator `]:`, the one thing
+     * every link reference / footnote definition contains. It is only a cheap
+     * gate that keeps the marked `links` probe off documents that cannot contain
+     * a definition; whether a definition really exists is marked's answer.
+     * Sticky, because a definition can complete arbitrarily far from its `]:`
+     * line — a title may span any number of lines, blank lines included — so
+     * there is no line count after which the question stops mattering.
+     */
+    sawDefinitionTrigger: boolean;
+    /**
+     * Input length the last `links` probe ran on (-1 before the first). Re-running
+     * the same text (the pass is idempotent) must not pay for the same lex twice,
+     * and the probe itself only runs when a recorded boundary makes its answer
+     * matter — see `settleDefinition`.
+     */
+    definitionCheckedLength: number;
+    /**
+     * An open raw block whose body may contain blank lines and heading-looking
+     * lines: `<pre>`/`<script>`/`<style>`/`<textarea>`, an HTML comment, a
+     * processing instruction, a declaration, CDATA, or `$$` / `\[` math. Its
+     * raw text is re-interpreted by the browser and DOMPurify (a `<?php` opens a
+     * bogus comment that can swallow a following `<h1>` open tag), so no
+     * boundary is recorded until it closes. `bodyChars` matters only for `exact`
+     * (`$$` math): the plugin's rule needs a non-empty body between the opener
+     * and its closing run.
+     */
+    rawBlock: {
+        close: string;
+        exact: boolean;
+        bodyChars?: number;
+    } | null;
+    /**
+     * A memoised "the current section still ends inside an open block" verdict
+     * (marked lexed `text[sectionStart..end]` and a heading there would be
+     * swallowed). It keeps a long fenced code block full of column-0 `#` lines
+     * from being re-lexed once per line; the check re-runs once the prefix has
+     * grown by more than `OPEN_BLOCK_MEMO_CHARS` or the fence scanner's verdict
+     * changes. It belongs to the current section implicitly: `offsets` only
+     * changes together with clearing this field. `fenceCause` says the refusal
+     * came from an unclosed fenced code block, whose body blank lines do not end
+     * (marked's own last top-level token is a fenced `code` token) — only such a
+     * memo survives a blank line. Only refusals are stored — reusing a stale
+     * refusal loses a split, never invents one.
+     */
+    openBlock: {
+        end: number;
+        fenceOpen: boolean;
+        fenceCause: boolean;
+    } | null;
+}
 export interface StreamCache {
     pending: string;
     token: StreamCacheTokenType;
     processedLength: number;
     completeMarkdown: string;
     fence: FenceState;
+    table: TableState;
+    sections: SectionState;
+}
+export interface AnimationConfig {
+    /**
+     * @description 淡入动画的持续时间（毫秒）
+     * @description The duration of the fade-in animation in milliseconds
+     * @default 200
+     */
+    fadeDuration?: number;
+    /**
+     * @description 动画的缓动函数
+     * @description Easing function for the animation
+     * @default 'ease-in-out'
+     */
+    easing?: string;
+    /**
+     * @description 淡入的单位。`chunk` 每次新到的文本单独淡入；`sentence` 把新到的文本并入当前句子，到分隔符才开始下一个淡入单元。与 `typewriter` 同时使用时应选 `sentence`，否则每帧放出的几个字都会各自成为一个淡入节点
+     * @description Unit of the fade-in. `chunk` fades in each newly arrived piece of text on its own; `sentence` appends new text to the current sentence and starts a new fade-in unit only after a delimiter. Use `sentence` together with `typewriter`, otherwise every few characters revealed per frame become their own fade-in node
+     * @default 'chunk'
+     */
+    splitBy?: "chunk" | "sentence";
+    /**
+     * @description `splitBy` 为 `sentence` 时的句子分隔符
+     * @description Sentence delimiters used when `splitBy` is `sentence`
+     * @default ['。', '！', '？', '.', '!', '?', '\n']
+     */
+    delimiters?: string[];
+    /**
+     * @description `splitBy` 为 `sentence` 时一个淡入单元最多容纳的字符数，超过后新到的文本另起一个单元
+     * @description With `splitBy: 'sentence'`, the most characters one fade-in unit holds; text arriving beyond it starts a new unit
+     * @default 120
+     */
+    maxSentenceChars?: number;
+}
+export interface TypewriterConfig {
+    /**
+     * @description 放出文本的单位。`char` 逐字放出；`sentence` 攒到分隔符再一起放出（围栏代码和行内代码里的分隔符不算，换行总是分隔符）
+     * @description Unit in which text is revealed. `char` reveals character by character; `sentence` reveals up to the next delimiter at once (delimiters inside fenced or inline code do not count, a newline always does)
+     * @default 'char'
+     */
+    unit?: "char" | "sentence";
+    /**
+     * @description 句子分隔符
+     * @description Sentence delimiters
+     * @default ['。', '！', '？', '.', '!', '?', '\n']
+     */
+    delimiters?: string[];
+    /**
+     * @description 最低放出速度（字/秒）。速度会随 chunk 到达节奏自适应，这是下限
+     * @description Minimum reveal speed in characters per second. The speed adapts to the chunk cadence; this is the floor
+     * @default 24
+     */
+    minCps?: number;
+    /**
+     * @description 最高放出速度（字/秒）
+     * @description Maximum reveal speed in characters per second
+     * @default 3000
+     */
+    maxCps?: number;
+    /**
+     * @description `unit` 为 `char` 时，放出一个分隔符后停顿的毫秒数
+     * @description With `unit: 'char'`, how many milliseconds to pause after revealing a delimiter
+     * @default 0
+     */
+    pauseMs?: number;
+    /**
+     * @description `unit` 为 `sentence` 时，自上一个分隔符起最多攒多少个字符；超过后退回逐字放出，直到下一个分隔符出现。防止长 URL、单行 JSON 这类没有标点的内容长时间不显示
+     * @description With `unit: 'sentence'`, the longest run since the previous delimiter that is held back; beyond it text is revealed character by character until the next delimiter appears. Prevents a long URL or a one-line JSON blob from staying invisible
+     * @default 120
+     */
+    maxSentenceChars?: number;
+}
+export interface TailConfig {
+    /**
+     * @description 尾部显示的内容，默认为 `▋`
+     * @description The content to display as tail, default is `▋`
+     * @default '▋'
+     */
+    content?: string;
+    /**
+     * @description 自定义尾部组件，优先级高于 content
+     * @description Custom tail component, takes precedence over content
+     */
+    component?: Component;
 }
 export interface StreamingOption {
-    hasNextChunk: boolean;
-    enableAnimation?: boolean;
-    animationConfig?: {
-        fadeDuration?: number;
-        easing?: string;
-    };
-    tail?: boolean | {
-        content?: string;
-        component?: Component;
+    /**
+     * @description 指示是否还有后续内容块，为 false 时刷新所有缓存并完成渲染
+     * @description Indicates whether more content chunks are expected. When false, flushes all cached content and completes rendering
+     * @default false
+     */
+    hasNextChunk?: boolean;
+    /**
+     * @description 流式期间按标题把正文切成若干段，只有正在增长的最后一段随每个 chunk 重新解析、消毒和渲染，前面的段直接复用。只在顶格的 ATX 标题（`# ` ～ `###### `）前切分，且该行必须真的开启一个新的顶层块——切分器把当前段交给渲染器所用的同一个 marked 实例来判定，而不是自己复刻块级语法，因此不会在围栏代码、HTML 块、列表、引用块或缩进代码内部切分。浏览器与 DOMPurify 会重新解释的原始块（`<pre>`、注释、`<?`、`<!`、`<![CDATA[`）以及 `$$` / `\[` 公式在闭合前不参与切分。**「没有切分」都是有意为之**：拒绝切分只会少复用一段，而多切一段会改变渲染结果。出现链接引用定义或脚注定义、或自定义组件标签跨越切点时不切分。`$$` 公式以自带的 Latex 插件规则为准，未注册该插件时用 `$$` 包住代码围栏的内容请关闭本选项。传对象可调整：短于 `minSectionChars` 的段并入下一段；`keepSectionsOnEnd`（默认 true）表示流结束（`hasNextChunk` 变为 false）后各段保持不变、已挂载的自定义组件不重新挂载，设为 false 则流结束时回到整篇一次性渲染，用了带全局状态的 marked 扩展（如标题 id 去重）时应关掉。
+     * @description Splits the document into sections at headings while streaming so that only the last, still-growing section is re-parsed, sanitized and rendered per chunk; earlier sections are reused as-is. A boundary is only placed before a column-0 ATX heading (`# ` to `###### `) **and only when the renderer's own marked instance reads that line as a new top-level block** — the splitter lexes the current section with the same `config` (extension plugins included) instead of re-implementing the block grammar, so it never splits inside fenced code, an HTML block, a list, a blockquote or indented code. Raw blocks the browser and DOMPurify re-interpret (`<pre>`, comments, `<?`, `<!`, `<![CDATA[`) and `$$` / `\[` math are held out of any split until they close. A case where no boundary is placed is deliberate: refusing only gives up incremental reuse, while an over-eager boundary would change the rendered DOM. Splitting is disabled when a link reference or footnote definition appears, or when a custom component tag spans the boundary. The `$$` math model follows the bundled Latex plugin; without that plugin registered, turn this off for content that wraps code fences in `$$` delimiters. Pass an object to tune it: sections shorter than `minSectionChars` are merged into the next one; `keepSectionsOnEnd` (default true) keeps the sections once the stream ends (`hasNextChunk` becomes false) so mounted custom components are not remounted, while false re-renders the whole document at once when the stream ends — turn it off when using marked extensions with document-wide state (e.g. heading id de-duplication).
+     * @default false
+     */
+    incremental?: boolean | {
+        minSectionChars?: number;
+        keepSectionsOnEnd?: boolean;
     };
+    /**
+     * @description 为块级元素（p、li、h1、h2、h3、h4）启用文字淡入动画
+     * @description Enables text fade-in animation for block elements (p, li, h1, h2, h3, h4)
+     * @default true
+     */
+    enableAnimation?: boolean;
+    /**
+     * @description 文字出现动画效果的配置
+     * @description Configuration for text appearance animation effects
+     */
+    animationConfig?: AnimationConfig;
+    /**
+     * @description 是否启用尾部动画；传入 `true` 使用默认 `▋`，传入对象可自定义内容
+     * @description Whether to enable tail animation; pass `true` for default `▋`, or object to customize content
+     * @default false
+     */
+    tail?: boolean | TailConfig;
+    /**
+     * @description 未完成的 Markdown 格式转换为自定义加载组件的映射配置，用于在流式渲染过程中为未闭合的链接和图片提供自定义loading组件
+     * @description Mapping configuration to convert incomplete Markdown formats to custom loading components, used to provide custom loading components for unclosed links and images during streaming rendering
+     * @default { link: 'incomplete-link', image: 'incomplete-image' }
+     */
     incompleteMarkdownComponentMap?: Partial<Record<StreamCacheTokenType, string>>;
+    /**
+     * @description 尚未写完的 Markdown 语法如何显示。`placeholder`：扣住不显示，或显示 `incompleteMarkdownComponentMap` 指定的占位组件；`complete`：把写到一半的强调、行内代码、链接文字、列表项当作已写完的文本立刻显示（`**加粗中` 显示为加粗，`[链接文字](https://` 先显示文字），图片、HTML、表格仍按 `placeholder` 处理。对某个语法显式配置了 `incompleteMarkdownComponentMap` 时以占位组件为准。
+     * @description How markdown syntax that has not finished streaming is shown. `placeholder`: hold it back, or show the placeholder component from `incompleteMarkdownComponentMap`; `complete`: show half-written emphasis, inline code, link text and list items as finished text right away (`**bold so far` renders bold, `[link text](https://` shows its text), while images, HTML and tables still follow `placeholder`. A token with an explicit `incompleteMarkdownComponentMap` entry always uses its placeholder.
+     * @default 'placeholder'
+     */
+    incompleteMarkdown?: "placeholder" | "complete";
+    /**
+     * @description 打字机效果：新到的内容不是整块出现，而是按 chunk 到达的节奏匀速放出。放出的永远是 `content` 的前缀，`hasNextChunk` 变为 false 时立即放完。传对象可配置单位、速度和分隔符
+     * @description Typewriter effect: newly arrived content is revealed at a steady pace that follows the chunk cadence instead of appearing in blocks. What is shown is always a prefix of `content`; everything is revealed at once when `hasNextChunk` becomes false. Pass an object to configure the unit, speed and delimiters
+     * @default false
+     */
+    typewriter?: boolean | TypewriterConfig;
 }
 export interface XMarkdownProps {
     content?: string;
@@ -50,7 +271,11 @@ export interface XMarkdownProps {
      * Extra props passed to custom components in `components` by tag name, keeping component references stable and avoiding remounts caused by inline functions
      */
     componentsProps?: Record<string, Record<string, unknown>>;
-    streaming?: StreamingOption;
+    /**
+     * @description 流式渲染行为的配置。传布尔值即开启预设：`true` 表示还有后续内容（等同 `hasNextChunk: true`）并打开 `incremental`、`incompleteMarkdown: 'complete'`、`typewriter`；`false` 表示流已结束，按最终内容一次性渲染。传对象则逐项配置
+     * @description Configuration for streaming rendering behavior. A boolean enables the preset: `true` means more content is coming (same as `hasNextChunk: true`) with `incremental`, `incompleteMarkdown: 'complete'` and `typewriter` switched on; `false` means the stream has ended and the final content is rendered at once. Pass an object to configure each option
+     */
+    streaming?: boolean | StreamingOption;
     config?: MarkedConfig;
     debug?: boolean;
     protectCustomTagNewlines?: boolean;
@@ -76,6 +301,9 @@ export interface AnimationTextProps {
     text: string;
     fadeDuration?: number;
     easing?: string;
+    splitBy?: "chunk" | "sentence";
+    delimiters?: string[];
+    maxSentenceChars?: number;
 }
 export interface DebugPanelProps {
     className?: string;
@@ -98,8 +326,7 @@ export interface RendererOptions {
     components?: Record<string, Component>;
     componentsProps?: Record<string, Record<string, unknown>>;
     enableAnimation?: boolean;
-    animationConfig?: {
-        fadeDuration?: number;
-        easing?: string;
-    };
+    animationConfig?: AnimationConfig;
 }
+/** 与上游 `TypewriterOption` 对齐的导出名。 Alias export matching the upstream name. */
+export type { TypewriterConfig as TypewriterOption };

package/dist/XMarkdown/utils/streaming.d.ts

@@ -0,0 +1,6 @@
+import { StreamingOption, XMarkdownProps } from '../interface';
+/**
+ * Normalise the `streaming` prop. Objects pass through untouched (the
+ * behaviour of every existing caller), booleans expand to the preset.
+ */
+export declare const resolveStreaming: (streaming: XMarkdownProps["streaming"]) => StreamingOption | undefined;

package/dist/XMarkdown/utils/streaming.js

@@ -0,0 +1,32 @@
+//#region src/XMarkdown/utils/streaming.ts
+/**
+* The preset behind `streaming={true}` / `streaming={false}`: every streaming
+* capability that needs no per-app configuration, switched on. The boolean is
+* `hasNextChunk`, so callers can pass their own "is the answer still
+* streaming" flag straight through.
+*/
+var PRESET = {
+	incremental: true,
+	incompleteMarkdown: "complete",
+	typewriter: true,
+	animationConfig: Object.freeze({ splitBy: "sentence" })
+};
+var STREAMING_ON = Object.freeze({
+	...PRESET,
+	hasNextChunk: true
+});
+var STREAMING_OFF = Object.freeze({
+	...PRESET,
+	hasNextChunk: false
+});
+/**
+* Normalise the `streaming` prop. Objects pass through untouched (the
+* behaviour of every existing caller), booleans expand to the preset.
+*/
+var resolveStreaming = (streaming) => {
+	if (streaming === true) return STREAMING_ON;
+	if (streaming === false) return STREAMING_OFF;
+	return streaming;
+};
+//#endregion
+export { resolveStreaming };

package/dist/index.d.ts

@@ -1,14 +1,18 @@
 export { default as XMarkdown } from './XMarkdown/index.vue';
 export type { XMarkdownProps } from './XMarkdown/interface';
-export type { StreamingOption } from './XMarkdown/interface';
+export type { StreamingOption, TypewriterOption } from './XMarkdown/interface';
+export type { AnimationConfig, TypewriterConfig } from './XMarkdown/interface';
+export type { StreamCacheTokenType } from './XMarkdown/interface';
 export type { MarkedConfig } from './XMarkdown/interface';
 export type { ComponentProps } from './XMarkdown/interface';
 export { Parser } from './XMarkdown/core/Parser';
 export { VueRenderer } from './XMarkdown/core/VueRenderer';
 export { detectUnclosedComponentTags } from './XMarkdown/core/detectUnclosedComponentTags';
-export { useStreaming } from './XMarkdown/composables/useStreaming';
+export { useStreaming, useStreamingCore, } from './XMarkdown/composables/useStreaming';
+export { useTypewriter } from './XMarkdown/composables/useTypewriter';
 export { useParser } from './XMarkdown/composables/useParser';
 export { useRenderer } from './XMarkdown/composables/useRenderer';
 export { useTail } from './XMarkdown/composables/useTail';
 export { AnimationText, DebugPanel, TailIndicator, } from './XMarkdown/components';
+export { resolveStreaming } from './XMarkdown/utils/streaming';
 export { resolveTailContent } from './XMarkdown/utils/tail';

package/dist/index.js

@@ -1,13 +1,15 @@
 import AnimationText_default from "./XMarkdown/components/AnimationText.js";
 import DebugPanel_default from "./XMarkdown/components/DebugPanel2.js";
 import TailIndicator_default from "./XMarkdown/components/TailIndicator.js";
-import { useStreaming } from "./XMarkdown/composables/useStreaming.js";
+import { detectUnclosedComponentTags } from "./XMarkdown/core/detectUnclosedComponentTags.js";
+import { resolveStreaming } from "./XMarkdown/utils/streaming.js";
+import { useStreaming, useStreamingCore } from "./XMarkdown/composables/useStreaming.js";
+import useTypewriter from "./XMarkdown/composables/useTypewriter.js";
 import { Parser } from "./XMarkdown/core/Parser.js";
 import { useParser } from "./XMarkdown/composables/useParser.js";
-import { detectUnclosedComponentTags } from "./XMarkdown/core/detectUnclosedComponentTags.js";
 import { VueRenderer } from "./XMarkdown/core/VueRenderer.js";
 import { useRenderer } from "./XMarkdown/composables/useRenderer.js";
 import { useTail } from "./XMarkdown/composables/useTail.js";
 import XMarkdown_default from "./XMarkdown/index2.js";
 import { resolveTailContent } from "./XMarkdown/utils/tail.js";
-export { AnimationText_default as AnimationText, DebugPanel_default as DebugPanel, Parser, TailIndicator_default as TailIndicator, VueRenderer, XMarkdown_default as XMarkdown, detectUnclosedComponentTags, resolveTailContent, useParser, useRenderer, useStreaming, useTail };
+export { AnimationText_default as AnimationText, DebugPanel_default as DebugPanel, Parser, TailIndicator_default as TailIndicator, VueRenderer, XMarkdown_default as XMarkdown, detectUnclosedComponentTags, resolveStreaming, resolveTailContent, useParser, useRenderer, useStreaming, useStreamingCore, useTail, useTypewriter };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antdv-next/x-markdown",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "license": "MIT",
   "files": [
     "dist",

package/plugins/Latex/index.js

@@ -38,14 +38,20 @@ function inlineKatex(renderer, replaceAlignStart) {
 			if (!match) return;
 			const rawText = dollarMatch?.[2] || nonStandardMatch?.[1] || nonStandardMatch?.[2] || "";
 			const text = replaceAlignStart ? replaceAlign(rawText.trim()) : rawText.trim();
+			const isBracketSyntax = nonStandardMatch?.[2] !== void 0;
+			const hasNewline = rawText.includes("\n");
 			return {
 				type: "inlineKatex",
 				raw: match[0],
 				text,
-				displayMode: true
+				displayMode: true,
+				isBlock: isBracketSyntax && hasNewline
 			};
 		},
-		renderer: (token) => `<span class="inline-katex">${renderer(token)}</span>`
+		renderer: (token) => {
+			const html = renderer(token);
+			return token.isBlock ? `<span class="block-katex">${html}</span>` : `<span class="inline-katex">${html}</span>`;
+		}
 	};
 }
 function blockKatex(renderer, replaceAlignStart) {