@ant-design/x-markdown-mini 0.1.0-beta.0

package/dist/index.d.mts

@@ -0,0 +1,508 @@
+import { Token, Tokens, MarkedExtension } from 'marked';
+export { MarkedExtension, Token, Tokens } from 'marked';
+
+type BuiltinPlatform = 'wechat' | 'alipay';
+type Platform = BuiltinPlatform | (string & {});
+type PlatformInput = Platform | 'auto';
+interface PlatformCapabilities {
+    supportsOlStart: boolean;
+    requiresHttpsImage: boolean;
+    anchorHrefMode: 'href' | 'data-href';
+    supportsTable: boolean;
+    supportsPre: boolean;
+    supportsBlockquote: boolean;
+}
+interface PlatformRenderer {
+    name: Platform;
+    capabilities: PlatformCapabilities;
+    renderTokens(tokens: Token[], ctx: RenderContext): MiniNode[];
+}
+
+/**
+ * 语义流式渲染配置
+ */
+interface SemanticStreamingConfig {
+    /** 语义分隔符正则，默认按句/标点切块 */
+    delimiters?: RegExp;
+    /** 单块最大字符数，超长句强制按长度切 */
+    maxChunkSize?: number;
+    /**
+     * 语义块之间的延迟（ms）。
+     * - number: 恒定延迟
+     * - number[]: 按已渲染块序号变速（如 [300,200,100,0] 随块加速），超出长度取最后一项
+     */
+    chunkDelay?: number | number[];
+    /**
+     * 块内字符延迟（ms），打字机逐字节奏。
+     * - number: 恒定延迟
+     * - number[]: 按已渲染块序号变速（如 [50,30,20,10,50]），超出长度取最后一项
+     */
+    charDelay?: number | number[];
+}
+/**
+ * 流式渲染配置
+ */
+interface StreamingConfig {
+    /**
+     * 是否还有后续输入。
+     * - true: 还有后续输入，保留未完成片段
+     * - false: 本轮输入后 flush 剩余内容并结束
+     */
+    hasNextChunk: boolean;
+    /**
+     * 语义分块开关 / 配置：
+     * - true: 启用默认语义分块
+     * - false: 关闭语义分块，直接一次性渲染
+     * - object: 启用语义分块并覆盖配置（delimiters / maxChunkSize / chunkDelay / charDelay）
+     */
+    semantic?: boolean | SemanticStreamingConfig;
+    /**
+     * 流式块动画开关
+     * - true: 启用流式块动画
+     * - false: 关闭流式块动画
+     */
+    enableAnimation?: boolean;
+}
+interface XMarkdownMiniProps {
+    /** Markdown 文本（全量或当前累计流式内容） */
+    content: string;
+    /** 目标平台，可选，默认 auto 自动识别 */
+    platform?: PlatformInput;
+    /**
+     * 流式渲染：
+     * - false: 关闭流式，走一次性渲染
+     * - true: 开启默认流式优化（等同 { hasNextChunk: true, semantic: true, enableAnimation: true }）
+     * - object: 自定义流式行为，需显式提供 hasNextChunk
+     */
+    streaming?: false | true | StreamingConfig;
+    /** 文本是否可选择（推荐默认 true，各端适配尽量映射） */
+    selectable?: boolean;
+    /** GFM 表格、删除线、自动换行（默认 true）。Per-call 可覆盖构造时的默认值 */
+    gfm?: boolean;
+    /** 软换行 \n 解析为 <br>（默认 false）。Per-call 可覆盖构造时的默认值 */
+    breaks?: boolean;
+    /**
+     * Per-call extensions that override instance-level extensions for this render.
+     * Accepts XMarkdownExtension (preferred, with miniRenderer) or MarkedExtension.
+     * Tokenizers are registered via `marked.use()`; renderers are resolved through
+     * the per-call list (instance-level `components` extension is always preserved).
+     */
+    extensions?: (XMarkdownExtension | MarkedExtension)[];
+    /** 渲染生命周期 */
+    onRenderStart?: () => void;
+    onRenderProgress?: (payload: {
+        markdown: string;
+    }) => void;
+    onRenderComplete?: () => void;
+    /** 流式时每轮解析完成回调，用于 setData(nodes) */
+    onPatch?: (nodes: MiniNode[]) => void;
+}
+interface XMarkdownMiniTokenProps {
+    /** Markdown 文本（全量或累计流式内容） */
+    content: string;
+    /** GFM 表格、删除线、自动换行（默认 true）。Per-call 可覆盖构造时的默认值 */
+    gfm?: boolean;
+    /** 软换行 \n 解析为 <br>（默认 false）。Per-call 可覆盖构造时的默认值 */
+    breaks?: boolean;
+    /**
+     * Per-call extensions that override instance-level extensions for this render.
+     * Accepts XMarkdownExtension (preferred, with miniRenderer) or MarkedExtension.
+     * Tokenizers are registered via `marked.use()`; renderers are resolved through
+     * the per-call list (instance-level `components` extension is always preserved).
+     */
+    extensions?: (XMarkdownExtension | MarkedExtension)[];
+    /**
+   * 流式解析：
+   * - false: 关闭流式，走一次性 lex
+   * - true: 开启默认流式优化（等同 { hasNextChunk: true, semantic: true }）
+   * - object: 自定义流式行为，需显式提供 hasNextChunk
+   */
+    streaming?: false | true | StreamingConfig;
+    /** 生命周期 */
+    onRenderStart?: () => void;
+    onRenderProgress?: (payload: {
+        markdown: string;
+    }) => void;
+    onRenderComplete?: () => void;
+    /** 流式时每轮 lex 完成回调，用于拿到 marked Token[] */
+    onPatch?: (tokens: Token[]) => void;
+}
+/**
+ * A tokenizer + renderer extension colocated on a single object — the
+ * preferred shape for new XMarkdownMini extensions. Structurally mirrors
+ * marked's `TokenizerAndRendererExtension` but adds `miniRenderer` so the
+ * renderer can return `MiniNode` directly instead of HTML.
+ */
+interface XMarkdownTokenizerExtension {
+    /** Token.type produced by this tokenizer. */
+    name: string;
+    /** Tokenizer level: 'block' or 'inline'. */
+    level?: 'block' | 'inline';
+    /** Marked start hook: returns the index of the next potential match. */
+    start?: (src: string) => number | undefined;
+    /** Marked tokenizer hook. */
+    tokenizer?: (this: any, src: string, tokens: Token[]) => Tokens.Generic | undefined;
+    /** Optional child token names (forwarded to marked). */
+    childTokens?: string[];
+    /** Preferred: return a MiniNode tree directly for this token. */
+    miniRenderer?: (token: Token, ctx: RenderContext) => MiniNode | MiniNode[] | null | undefined;
+    /**
+     * marked-style HTML renderer. When present without `miniRenderer`, the HTML
+     * output is run through `htmlToMiniNodes` and the result is used.
+     */
+    renderer?: (this: any, token: Token) => string;
+}
+/**
+ * Preferred extension shape for `XMarkdownMiniOptions.extensions`. A subset of
+ * `MarkedExtension` whose tokenizer entries carry `miniRenderer` / `renderer`
+ * alongside the tokenizer. `MarkedExtension`s (e.g. community plugins that
+ * only emit HTML) are also accepted in the same array.
+ */
+interface XMarkdownExtension {
+    /** Tokenizer entries with colocated mini-program renderers. */
+    extensions?: XMarkdownTokenizerExtension[];
+    /** Marked walkTokens hook (forwarded to marked). */
+    walkTokens?: MarkedExtension['walkTokens'];
+    /** Marked hooks (forwarded to marked). */
+    hooks?: MarkedExtension['hooks'];
+    /** Marked tokenizer overrides (forwarded to marked). */
+    tokenizer?: MarkedExtension['tokenizer'];
+}
+/** 渲染上下文：transformer 共用的公共配置。 */
+interface RenderContext {
+    /** 是否启用块级动画 */
+    animation?: boolean;
+    /** 文本是否可选择 */
+    selectable?: boolean;
+    /**
+     * 是否对文本节点的 value 做 HTML 实体转义。
+     * - true（默认）：用于会解码实体的平台节点容器
+     * - false：用于自渲染组件（<text>{{value}}</text> 不解码实体）
+     */
+    escapeText?: boolean;
+    /**
+     * Colocated tokenizer+renderer extensions registered on the instance.
+     */
+    extensions?: readonly XMarkdownExtension[];
+    /**
+     * Recursively render an inline token array to MiniNode[]. Provided by the
+     * platform transformer; used by custom extension miniRenderers that emit
+     * tokens with children (e.g. <custom-tag>inner</custom-tag>).
+     */
+    renderInlineTokens?: (tokens: Token[]) => MiniNode[];
+}
+interface MiniNode {
+    /** 标签名，小写 */
+    name: string;
+    /**
+     * 自定义组件原始标签名。仅由 `components` 白名单合成的节点携带，等于 `name`，
+     * 用于宿主页面在作用域插槽 / dispatcher 里按 `node.tag` 分发（对齐 markdown-x 约定）。
+     */
+    tag?: string;
+    /** 属性，class/style 等小写 */
+    attrs?: Record<string, string | number | boolean>;
+    /** 子节点 */
+    children?: MiniNode[];
+    /** 是否开启动画 */
+    animate?: boolean;
+}
+
+/**
+ * Streaming tail preprocessor:
+ * - 'remend' (default): auto-completes unfinished markdown tail syntax
+ * - false: disables fixup
+ * - function: custom tail preprocessor
+ */
+type StreamingFixup = 'remend' | false | ((text: string) => string);
+
+interface XMarkdownMiniOptions {
+    /**
+     * Whether to escape text nodes. Defaults to true for native mini-program node output.
+     * Custom component paths should pass false because <text>{{value}}</text>
+     * does not decode HTML entities.
+     */
+    escapeText?: boolean;
+    /**
+     * Streaming tail fixup strategy. Defaults to 'remend'.
+     * Only affects streaming paths; one-shot parse/render calls are untouched.
+     */
+    streamingFixup?: StreamingFixup;
+    /** GFM 表格、删除线、自动换行（默认 true） */
+    gfm?: boolean;
+    /** 软换行 \n 解析为 <br>（默认 false） */
+    breaks?: boolean;
+    /**
+     * Per-instance extensions. Accepts either the colocated
+     * `XMarkdownExtension` shape (tokenizer + `miniRenderer` / `renderer` on the
+     * same object — preferred) or a plain `MarkedExtension` (for community
+     * marked plugins that only emit HTML). All entries are forwarded to
+     * `new Marked(...)`; the new fields (`miniRenderer`) are ignored by marked.
+     * Can be overridden per render call via `renderNodes({ extensions })` /
+     * `renderTokens({ extensions })`.
+     */
+    extensions?: (XMarkdownExtension | MarkedExtension)[];
+    /**
+     * Whitelist of literal custom-component tags allowed in Markdown source.
+     * For each entry, an internal inline tokenizer is synthesized that matches
+     * `<tag attrs>inner</tag>` (or `<tag attrs />`) and emits a MiniNode whose
+     * `name` is the tag and whose `children` are the recursively rendered
+     * inner inline tokens.
+     *
+     * Tags NOT in this list fall through to marked's built-in `html` token
+     * handling. Self-closing and empty tags omit `children`.
+     *
+     * @example
+     * ```ts
+     * new XMarkdownMini({ components: ['ant-button', 'ant-icon'] });
+     * // "<ant-button type=\"primary\">OK</ant-button>" → MiniNode tree
+     * ```
+     *
+     * Limitations: this PoC uses non-greedy matching, so nested same-tag
+     * occurrences (e.g. `<x><x>…</x></x>`) match against the innermost
+     * `</x>` and will not produce a nested structure.
+     */
+    components?: string[];
+}
+/**
+ * Independent renderer instance with isolated streaming state.
+ * Use one instance per concurrent streaming markdown source.
+ */
+declare class XMarkdownMini {
+    private tokenStreamProcessor;
+    private nodeStreamProcessor;
+    private readonly escapeText;
+    private readonly fixup;
+    private readonly gfm;
+    private readonly breaks;
+    private readonly marked;
+    private activeTokenStreamDefaults;
+    private activeNodeStreamDefaults;
+    /** Instance-level user extensions (from constructor options). */
+    private readonly extensions;
+    /** Components extension synthesized from `opts.components`, kept separate so
+     *  per-call extensions can override user extensions but keep components. */
+    private readonly componentsExtension;
+    constructor(opts?: XMarkdownMiniOptions);
+    /**
+     * Build the full RenderContext.extensions list for a render call.
+     * Per-call extensions replace instance-level user extensions; the
+     * components extension is always appended so that `<custom-tag>` sugar
+     * continues to work regardless of per-call overrides.
+     */
+    private resolveExtensions;
+    /**
+     * Register per-call extensions with the Marked instance and return a
+     * snapshot of the previous defaults so they can be restored after the call.
+     * Returns `null` if nothing to apply (no per-call extensions).
+     */
+    private applyPerCallExtensions;
+    private restoreDefaults;
+    private buildMarkedOptions;
+    private lex;
+    /**
+     * Parses markdown into marked's native Token[] without platform rendering.
+     */
+    parse(content: string): Token[];
+    /**
+     * Pure JS entry. Returns marked Token[] for callers that render themselves.
+     */
+    render(content: string): Token[];
+    render(props: XMarkdownMiniTokenProps): Token[];
+    /**
+     * Token streaming entry. AI streaming fixup runs on markdown text before lex.
+     */
+    renderTokens(props: XMarkdownMiniTokenProps): Token[];
+    /**
+     * Component/node entry. Tokens are rendered by the selected platform renderer.
+     */
+    renderNodes(props: XMarkdownMiniProps): MiniNode[];
+    /** Resets streaming state, usually during component detach/unmount. */
+    reset(): void;
+}
+
+declare const alipayRenderer: PlatformRenderer;
+
+interface TokensToAlipayOptions extends RenderContext {
+    options?: {
+        gfm?: boolean;
+        breaks?: boolean;
+    };
+}
+/**
+ * Converts markdown into Alipay mini-program nodes.
+ * Kept for compatibility; new code can parse once and call tokensToAlipayNodes().
+ */
+declare function tokensToAlipay(content: string, opts?: TokensToAlipayOptions): MiniNode[];
+/** Converts pre-lexed marked Token[] into Alipay mini-program nodes. */
+declare function tokensToAlipayNodes(tokens: Token[], ctx?: RenderContext): MiniNode[];
+
+interface TokensToWechatOptions extends RenderContext {
+    options?: {
+        gfm?: boolean;
+        breaks?: boolean;
+    };
+}
+/**
+ * Converts markdown into WeChat mini-program nodes.
+ * Kept for compatibility; new code can parse once and call tokensToWechatNodes().
+ */
+declare function tokensToWechat(content: string, opts?: TokensToWechatOptions): MiniNode[];
+/** Converts pre-lexed marked Token[] into WeChat mini-program nodes. */
+declare function tokensToWechatNodes(tokens: Token[], ctx?: RenderContext): MiniNode[];
+
+declare const wechatRenderer: PlatformRenderer;
+
+declare function resolvePlatform(platform?: PlatformInput): Platform;
+declare function getPlatformRenderer(platform: Platform): PlatformRenderer;
+declare function registerPlatformRenderer(renderer: PlatformRenderer): void;
+
+interface StreamingProcessorConfig<T> {
+    /**
+     * 把一段已经过流式预处理的 markdown 文本转成平台节点的函数。
+     *
+     * 重要边界：AI 流式处理发生在 lex 之前。StreamingProcessor 只处理字符串层：
+     * 增量合并、语义切块、稳定段缓存、tail fixup。调用 transform 时，入参仍是
+     * markdown 字符串；调用方（通常是 XMarkdownMini）才在 transform 内部执行
+     * marked lexer，并交给平台 renderer。
+     */
+    transform: (markdown: string) => T[];
+    /**
+     * 可选的 tail 预处理。流式渲染时，每次 flush 只对 tail（未稳定段）调用一次，
+     * 已 commit 的稳定段不会再被处理。典型用法：接 remend 补全未闭合的 markdown
+     * 语法（**bold / `code` / [link]( 等），避免 AI 流式输出时闪烁。
+     *
+     * 注意：fixup 只影响传给 `transform` 的字符串，不会写回 renderedText，因此
+     * `getRenderedText()` 与 `onUpdate` 回调中拿到的仍是用户原始内容。
+     */
+    fixup?: (tail: string) => string;
+    onUpdate: (markdown: string) => void;
+    onPatch: (nodes: T[]) => void;
+    onComplete: () => void;
+    semanticEnabled?: boolean;
+    delimiters?: RegExp;
+    maxChunkSize?: number;
+    /** number = 恒定；number[] = 按已渲染块序号变速（随块加速），超出取末项 */
+    chunkDelay?: number | number[];
+    /** number = 恒定；number[] = 按已渲染块序号变速，超出取末项 */
+    charDelay?: number | number[];
+}
+/**
+ * 流式处理器：
+ * - 增量合并 markdown 文本（前缀匹配则视作追加，否则 reset）
+ * - 已稳定（前面已被空行收尾）的块只进入 transform 一次，缓存为 stableNodes
+ * - 仅对未稳定的 tail（最后一段）每次重新走 fixup → transform
+ * - chunkDelay/charDelay 全为 0 时跳过 setTimeout 链，单次 onPatch 即返回
+ * - 否则走语义切块的"打字机"模式：按 delimiters / maxChunkSize 推进 renderedText
+ */
+declare class StreamingProcessor<T = unknown> {
+    private buffer;
+    private renderedText;
+    private previousMarkdown;
+    private stableNodes;
+    private committedLen;
+    /** Whether the character at committedLen is inside a fenced code block (used for incremental scanning). */
+    private committedInFence;
+    private committedFenceChar;
+    private pendingChunks;
+    private chunkIndex;
+    /** 已渲染块的累计序号，用于数组变速延迟（charDelay/chunkDelay 为数组时按此取值）。 */
+    private chunkRenderIndex;
+    private activeChunk;
+    private activeChunkOffset;
+    private timer;
+    private currentHasNextChunk;
+    private readonly config;
+    constructor(cfg: StreamingProcessorConfig<T>);
+    /** 内容更新：增量则追加到 buffer，否则 reset 后整段替换。 */
+    handleContentUpdate(content: string): void;
+    reset(): void;
+    /**
+     * 推进渲染。若 chunk/charDelay 都为 0，立即一次性 flush；否则进入打字机循环。
+     */
+    runRenderLoop(hasNextChunk: boolean): void;
+    /** 当前已输出给 UI 的完整 markdown 字符串 */
+    getRenderedText(): string;
+    /** 是否还有待处理 chunks（外部可据此判断是否完成） */
+    hasPendingChunks(): boolean;
+    /** 按 delimiters + maxChunkSize 把 buffer 切成 chunk 序列；hasNext=false 时 flush 末尾。 */
+    private splitIntoChunks;
+    private scheduleNext;
+    private cancelScheduledRender;
+    /** 推进 commit 点：从上次 committedLen 开始增量扫描，找 fenced code 之外的最后一段「双换行」位置。 */
+    private advanceCommit;
+    /** 重新解析 tail 部分，与 stableNodes 合并后 emit。 */
+    private flushNodes;
+}
+
+/**
+ * 自包含行内脚注扩展。
+ *
+ * 语法：`[^标签:内容]`，例如 `Markdown[^1:一种轻量标记语言]`。
+ * - `标签`（可选，到第一个 `:` 为止）：marker 显示文本，默认 `注`。
+ * - `内容`：popover 文本，**自包含**在节点里，宿主组件本地即可弹层，
+ *   不依赖跨组件边界的事件/数据传递（微信尤其需要）。
+ *
+ * 产出一个 `name: 'footnote'` 的 MiniNode（带 `tag` 以便宿主按 tag 分发），
+ * 经 `Markdown` 组件的 slot（支付宝）/ 抽象节点（微信）交给宿主渲染 marker + popover。
+ */
+interface FootnoteOptions {
+    /** 缺省 marker 文本（无显式标签时），默认 `注`。 */
+    defaultLabel?: string;
+}
+declare function Footnote(options?: FootnoteOptions): XMarkdownExtension;
+
+/**
+ * 把 marked inline Token[] 扁平成一层 InlineRun[]，配合小程序 `<text>` 模板使用。
+ *
+ * 背景：mini-program 的 `<text>` 不能嵌套自定义组件，所以模板无法递归通过 `<text>`
+ * 渲染任意深度的 strong/em/del/code 嵌套——必须在 JS 层把嵌套结构拍平为单层
+ * 文本片段序列，每个片段携带「class 链」让模板按类拼样式。
+ *
+ * 与旧 flattenInline 的差别：输入是 marked 原生 Token[]，不再经过 MiniNode 中转。
+ * 这样组件可以直接消费 XMarkdownMini.parse() 的输出，无需 transformer 层。
+ *
+ * Link / Image 由模板单独渲染（小程序 `<text>` 之外的 `<image>` / 可点击 `<text>`），
+ * 不并入文本 run。Hard break 用独立 `kind:'br'` 占位。
+ */
+type InlineRunKind = 'text' | 'br' | 'link' | 'image';
+interface InlineRun {
+    kind: InlineRunKind;
+    /** 用作文本节点或链接文本；image 的话是 alt */
+    value: string;
+    /** 空格分隔的样式类链，e.g. "md-strong md-em" */
+    classes: string;
+    /** link / image 的属性。其他 kind 不带 attrs。 */
+    attrs?: {
+        href?: string;
+        src?: string;
+        alt?: string;
+        title?: string;
+    };
+}
+interface FlattenInlineTokensOptions {
+    /**
+     * 是否对文本值做 HTML 转义。
+     * - true：用于会解码实体的平台节点容器
+     * - false：用于自渲染 `<text>{{value}}</text>` 模板（不解码实体）
+     */
+    escapeText: boolean;
+}
+declare function flattenInlineTokens(tokens: Token[], opts: FlattenInlineTokensOptions): InlineRun[];
+
+/**
+ * Parses markdown into marked Token[] without platform rendering.
+ */
+declare function parse(content: string): Token[];
+/**
+ * Pure JS entry. `render(markdown)` returns marked Token[].
+ * Component/node rendering belongs to `renderNodes(props)`.
+ */
+declare function render(content: string): Token[];
+declare function render(props: XMarkdownMiniTokenProps): Token[];
+/**
+ * Node rendering entry for mini-program components.
+ * Use `new XMarkdownMini()` for concurrent streaming sources.
+ */
+declare function renderNodes(props: XMarkdownMiniProps): MiniNode[];
+
+export { type BuiltinPlatform, type FlattenInlineTokensOptions, Footnote, type FootnoteOptions, type InlineRun, type InlineRunKind, type MiniNode, type Platform, type PlatformCapabilities, type PlatformInput, type PlatformRenderer, type RenderContext, type SemanticStreamingConfig, type StreamingConfig, type StreamingFixup, StreamingProcessor, type XMarkdownExtension, XMarkdownMini, type XMarkdownMiniOptions, type XMarkdownMiniProps, type XMarkdownMiniTokenProps, type XMarkdownTokenizerExtension, alipayRenderer, flattenInlineTokens, getPlatformRenderer, parse, registerPlatformRenderer, render, renderNodes, resolvePlatform, tokensToAlipay, tokensToAlipayNodes, tokensToWechat, tokensToWechatNodes, wechatRenderer };