react-super-mermaid 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,301 @@
+import * as react from 'react';
+import { RefObject } from 'react';
+
+/** 本套件實際用到的 mermaid API 子集 — 避免直接相依 mermaid 匯出的型別。 */
+interface MermaidRenderResult {
+    svg: string;
+    bindFunctions?: (element: Element) => void;
+}
+interface MermaidLike {
+    initialize: (config: unknown) => void;
+    render: (id: string, text: string, container?: Element) => Promise<MermaidRenderResult>;
+    parse?: (text: string) => Promise<unknown> | unknown;
+}
+/** 如何取得外部 mermaid:注入實例 > peer 動態 import('mermaid') > CDN。 */
+interface MermaidSource {
+    /** (a) host 已 import 的 mermaid 實例,最高優先,不再動態載入。 */
+    instance?: MermaidLike;
+    /** (c) mermaid ESM build 的 CDN 網址,如 .../mermaid@11/dist/mermaid.esm.min.mjs。 */
+    cdnUrl?: string;
+}
+interface LoadMermaidOptions {
+    source?: MermaidSource;
+    /** 強制重新解析(清掉模組級快取)。 */
+    fresh?: boolean;
+}
+/** svg-pan-zoom 工廠函式(預設匯出),只列出本套件用到的形狀。 */
+type SvgPanZoomFactory = (svg: SVGElement, options?: Record<string, unknown>) => PanZoomInstance;
+interface SvgPanZoomSource {
+    instance?: SvgPanZoomFactory;
+    cdnUrl?: string;
+}
+/** svg-pan-zoom 實例 — 只列出本套件用到的方法。 */
+interface PanZoomInstance {
+    destroy: () => void;
+    zoomBy: (factor: number) => void;
+    zoom: (scale: number) => void;
+    getZoom: () => number;
+    resize: () => void;
+    fit: () => void;
+    center: () => void;
+    pan: (point: {
+        x: number;
+        y: number;
+    }) => void;
+    getPan: () => {
+        x: number;
+        y: number;
+    };
+    getSizes: () => {
+        width: number;
+        height: number;
+        realZoom: number;
+        viewBox: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+    };
+}
+type MermaidTheme = 'colorful' | 'sketch' | 'auto' | 'default' | 'dark' | 'neutral' | 'forest';
+type MermaidBaseTheme = 'default' | 'dark' | 'neutral' | 'forest';
+interface RenderDiagramOptions {
+    /** mermaid 原始碼字串。 */
+    code: string;
+    /** 渲染目標;字串視為 CSS selector。省略則只回傳 detached SVG。 */
+    container?: HTMLElement | string;
+    theme?: MermaidTheme;
+    dark?: boolean;
+    /** sketch 抖動亂數種子,預設 42。 */
+    seed?: number;
+    /** sketch 手寫字體來源覆寫。 */
+    fontUrl?: string;
+    /** 透傳給 mermaid.initialize 的設定(深合併)。 */
+    mermaidConfig?: Record<string, unknown>;
+    /** 如何取得 mermaid。 */
+    mermaid?: MermaidSource;
+    /** 是否注入套件內建 CSS,預設 true。 */
+    injectStyles?: boolean;
+}
+interface RenderResult {
+    /** 已注入 container(若有提供)的 SVG 元素。 */
+    svg: SVGSVGElement;
+    /** 序列化後的 SVG 字串。 */
+    svgString: string;
+    /** 本次 render 使用的唯一 id。 */
+    id: string;
+}
+type RasterType = 'png' | 'jpeg' | 'webp';
+interface ExportRasterOptions {
+    /** 解析度倍率,預設 2。 */
+    scale?: 1 | 2 | 4;
+    /** 透明背景(JPEG 不支援,會自動填白)。 */
+    transparent?: boolean;
+    /** 明確指定背景色,覆寫 transparent。 */
+    background?: string;
+    type?: RasterType;
+    /** jpeg / webp 的品質 0..1,預設 0.92。 */
+    quality?: number;
+}
+interface SearchState {
+    current: number;
+    total: number;
+}
+
+interface ThemeOption {
+    value: MermaidTheme;
+    label: string;
+}
+declare const DEFAULT_THEME_OPTIONS: ThemeOption[];
+interface ToolbarProps {
+    theme: MermaidTheme;
+    themeOptions: ThemeOption[];
+    onThemeChange: (theme: MermaidTheme) => void;
+    zoomPercent: number;
+    onZoomIn: () => void;
+    onZoomOut: () => void;
+    onActualSize: () => void;
+    onReset: () => void;
+    searchEnabled: boolean;
+    searchOpen: boolean;
+    onToggleSearch: () => void;
+    exportEnabled: boolean;
+    exporting: boolean;
+    onExportSvg: () => void;
+    onExportPng: () => void;
+}
+declare function Toolbar(props: ToolbarProps): React.JSX.Element;
+
+interface MermaidViewerProps {
+    /** mermaid 原始碼字串(必填)。 */
+    code: string;
+    /** 主題,預設 'colorful'。toolbar 會即時切換;傳入新值也會同步。 */
+    theme?: MermaidTheme;
+    /** 暗色;省略時自動偵測 prefers-color-scheme。 */
+    dark?: boolean;
+    /** 是否顯示 toolbox(主題 / 縮放 / 搜尋 / 匯出)。預設 true;false = 只顯示圖表。 */
+    toolbar?: boolean;
+    /** 自訂 toolbar 上的主題選項。 */
+    themeOptions?: ThemeOption[];
+    /** 是否啟用 pan/zoom。預設 true。 */
+    panZoom?: boolean;
+    /** 是否啟用搜尋(toolbar 內)。預設 true。 */
+    search?: boolean;
+    /** 是否啟用匯出 SVG/PNG(toolbar 內)。預設 true。 */
+    exportable?: boolean;
+    /** 是否綁定鍵盤快捷鍵(/ Ctrl+F 搜尋、+ - 0 1 縮放)。預設 true。 */
+    keyboard?: boolean;
+    /** sketch 抖動種子,預設 42。 */
+    seed?: number;
+    /** sketch 手寫字體來源覆寫。 */
+    fontUrl?: string;
+    /** 如何取得 mermaid:注入實例 / CDN。省略則動態 import peer。 */
+    mermaid?: MermaidSource;
+    /** 透傳給 mermaid.initialize 的設定。 */
+    mermaidConfig?: Record<string, unknown>;
+    /** 如何取得 svg-pan-zoom。省略則動態 import peer。 */
+    svgPanZoom?: SvgPanZoomSource;
+    /** 是否注入套件內建 CSS,預設 true。 */
+    injectStyles?: boolean;
+    className?: string;
+    style?: React.CSSProperties;
+    onRender?: (svg: SVGSVGElement) => void;
+    onError?: (err: Error) => void;
+}
+/** 命令式控制(透過 ref),適合 toolbar={false} 時 host 自建按鈕。 */
+interface MermaidViewerHandle {
+    zoomIn: () => void;
+    zoomOut: () => void;
+    fit: () => void;
+    reset: () => void;
+    actualSize: () => void;
+    getZoomPercent: () => number;
+    search: (term: string) => SearchState;
+    next: () => SearchState;
+    prev: () => SearchState;
+    clearSearch: () => void;
+    exportSvg: () => string;
+    exportPng: (opts?: ExportRasterOptions) => Promise<Blob>;
+    downloadSvg: (filename?: string) => void;
+    downloadPng: (filename?: string, opts?: ExportRasterOptions) => Promise<void>;
+    getSvg: () => SVGSVGElement | null;
+}
+declare const MermaidViewer: react.ForwardRefExoticComponent<MermaidViewerProps & react.RefAttributes<MermaidViewerHandle>>;
+
+/**
+ * 只顯示圖表的便利元件 = <MermaidViewer toolbar={false} />。
+ * 仍支援 pan/zoom 與透過 ref 的命令式控制(host 可自建按鈕)。
+ */
+declare const MermaidDiagram: react.ForwardRefExoticComponent<Omit<MermaidViewerProps, "toolbar"> & react.RefAttributes<MermaidViewerHandle>>;
+
+type RenderStatus = 'loading' | 'ready' | 'error';
+interface UseMermaidViewerOptions {
+    code: string;
+    theme: MermaidTheme;
+    dark: boolean;
+    seed: number;
+    fontUrl?: string;
+    mermaidConfig?: Record<string, unknown>;
+    mermaid?: MermaidSource;
+    svgPanZoom?: SvgPanZoomSource;
+    panZoom: boolean;
+    injectStyles: boolean;
+    onRender?: (svg: SVGSVGElement) => void;
+    onError?: (err: Error) => void;
+}
+interface UseMermaidViewerResult {
+    stageRef: RefObject<HTMLDivElement>;
+    status: RenderStatus;
+    error: string;
+    zoomPercent: number;
+    zoomIn: () => void;
+    zoomOut: () => void;
+    fit: () => void;
+    reset: () => void;
+    actualSize: () => void;
+    getZoomPercent: () => number;
+    search: (term: string, pan?: boolean) => SearchState;
+    next: (pan?: boolean) => SearchState;
+    prev: (pan?: boolean) => SearchState;
+    clearSearch: () => void;
+    exportSvg: () => string;
+    exportPng: (opts?: ExportRasterOptions) => Promise<Blob>;
+    downloadSvg: (filename?: string) => void;
+    downloadPng: (filename?: string, opts?: ExportRasterOptions) => Promise<void>;
+    getSvg: () => SVGSVGElement | null;
+}
+declare function useMermaidViewer(opts: UseMermaidViewerOptions): UseMermaidViewerResult;
+
+type PostProcess = 'colorful' | 'sketch' | 'none';
+interface ResolvedTheme {
+    base: MermaidBaseTheme;
+    look: 'classic' | 'handDrawn';
+    postProcess: PostProcess;
+}
+declare function resolveTheme(theme: MermaidTheme, dark: boolean): ResolvedTheme;
+
+/**
+ * 一次性渲染:載入 mermaid、渲染、後處理並(若有 container)注入頁面。
+ * 不附 pan/zoom — 適合靜態美化輸出。互動請用 createViewer / <MermaidViewer>。
+ */
+declare function renderDiagram(opts: RenderDiagramOptions): Promise<RenderResult>;
+
+declare function loadMermaid(opts?: LoadMermaidOptions): Promise<MermaidLike>;
+
+declare function loadSvgPanZoom(source?: SvgPanZoomSource): Promise<SvgPanZoomFactory | null>;
+
+declare function ensureStyles(): void;
+
+interface ColorizeOptions {
+    dark?: boolean;
+}
+/** 在已渲染的 mermaid SVG 上套用 Colorful 樣式(就地修改 DOM)。 */
+declare function colorizeDiagram(root: ParentNode, opts?: ColorizeOptions): void;
+
+interface SketchOptions {
+    dark?: boolean;
+    /** 位移濾鏡亂數種子,固定值可確保每次 render 的抖動一致(與 handDrawnSeed 對齊)。 */
+    seed?: number;
+}
+declare const SKETCH_FONT = "'Virgil', 'KaiTi', 'Comic Sans MS', cursive";
+declare const DEFAULT_VIRGIL_FONT_URL = "https://cdn.jsdelivr.net/npm/react-super-mermaid/dist/Virgil.woff2";
+/**
+ * 對已渲染的 mermaid SVG 套用手繪風(就地修改 DOM)。
+ * 僅處理 sequenceDiagram;其他圖型回傳 false 由呼叫端維持原生 handDrawn 結果。
+ */
+declare function sketchifyDiagram(root: ParentNode, opts?: SketchOptions): boolean;
+/**
+ * 注入 Virgil 的 @font-face 並等待載入完成。
+ * 必須在 mermaid.render 之前 await — 否則 mermaid 會用 fallback 字體量測文字寬度,
+ * 導致換成 Virgil 後文字溢出方框。載入失敗時靜默退回 fallback 字體,不阻斷渲染。
+ *
+ * @param fontUrl Virgil woff2 的來源網址;省略則用 DEFAULT_VIRGIL_FONT_URL(jsDelivr)。
+ */
+declare function ensureSketchFont(fontUrl?: string): Promise<void>;
+
+interface PreparedSvg {
+    serialized: string;
+    width: number;
+    height: number;
+    /** 含 <foreignObject>(htmlLabels)→ 點陣化可能污染 canvas,呼叫端宜退回 SVG。 */
+    hasForeignObject: boolean;
+}
+/** 解析 mermaid 重繪出來的 SVG 字串(htmlLabels 關閉的 pristine 版),整理成可匯出形式。 */
+declare function prepareSvgString(svgText: string): PreparedSvg | undefined;
+/** 整理一個已存在的 SVG 元素(就地設定尺寸、移除 style 後序列化)。 */
+declare function prepareSvgElement(svg: SVGSVGElement): PreparedSvg;
+/**
+ * 從畫面上 live SVG(已上色、可能被 pan/zoom 包了 viewport transform)複製一份、
+ * 還原縮放平移後序列化。供同步的 exportSvg() 使用。
+ */
+declare function serializeLiveSvg(svg: SVGSVGElement): PreparedSvg;
+declare function svgBlob(serialized: string): Blob;
+/** 把整理好的 SVG 經 Image + canvas 點陣化成 Blob。 */
+declare function rasterizeToBlob(prepared: PreparedSvg, opts?: ExportRasterOptions & {
+    dark?: boolean;
+}): Promise<Blob>;
+/** 觸發瀏覽器下載一個 Blob。 */
+declare function downloadBlob(blob: Blob, filename: string): void;
+
+export { type ColorizeOptions, DEFAULT_THEME_OPTIONS, DEFAULT_VIRGIL_FONT_URL, type ExportRasterOptions, type LoadMermaidOptions, type MermaidBaseTheme, MermaidDiagram, type MermaidLike, type MermaidSource, type MermaidTheme, MermaidViewer, type MermaidViewerHandle, type MermaidViewerProps, type PanZoomInstance, type PreparedSvg, type RasterType, type RenderDiagramOptions, type RenderResult, type RenderStatus, SKETCH_FONT, type SearchState, type SketchOptions, type SvgPanZoomSource, type ThemeOption, Toolbar, type ToolbarProps, type UseMermaidViewerOptions, type UseMermaidViewerResult, colorizeDiagram, downloadBlob, ensureSketchFont, ensureStyles, loadMermaid, loadSvgPanZoom, prepareSvgElement, prepareSvgString, rasterizeToBlob, renderDiagram, resolveTheme, serializeLiveSvg, sketchifyDiagram, svgBlob, useMermaidViewer };