@zombie-mermaid/ascii-renderer 2.2.1

package/dist/index.d.cts

@@ -0,0 +1,146 @@
+import { DiagramColors } from '@zombie-mermaid/core';
+import { Direction } from '@zombie-mermaid/core';
+
+export declare interface AsciiRenderOptions {
+    /** true = ASCII chars (+,-,|,>), false = Unicode box-drawing (┌,─,│,►). Default: false */
+    useAscii?: boolean;
+    /** Horizontal spacing between nodes. Default: 5 */
+    paddingX?: number;
+    /** Vertical spacing between nodes. Default: 5 */
+    paddingY?: number;
+    /** Padding inside node boxes. Default: 1 */
+    boxBorderPadding?: number;
+    /**
+     * Color mode for output.
+     * - 'none': No colors (plain text)
+     * - 'auto': Auto-detect (terminal ANSI capabilities, or HTML in browsers)
+     * - 'ansi16': 16-color ANSI
+     * - 'ansi256': 256-color xterm
+     * - 'truecolor': 24-bit RGB
+     * - 'html': HTML <span> tags with inline color styles (for browser rendering)
+     * Default: 'auto'
+     */
+    colorMode?: ColorMode | 'auto';
+    /** Theme colors for ASCII output. Uses default theme if not provided. */
+    theme?: Partial<AsciiTheme>;
+    /**
+     * Overlay spreadsheet-style row/column indices on the rendered output, to
+     * help debug layout spacing. Off by default.
+     */
+    showCoords?: boolean;
+    /**
+     * Force the diagram's layout direction, overriding the one its source
+     * declares (a flowchart's `graph LR` header, or a state diagram's
+     * top-level `direction LR` line). Applied after parsing and before
+     * layout — the source text is never rewritten. Replaces only the
+     * top-level direction: a nested subgraph's or composite state's own
+     * `direction` line still applies on top of it, exactly as it does on top
+     * of the diagram's own header.
+     *
+     * Flowchart and state diagrams only in ASCII output. The ASCII ER layout
+     * has no direction concept (it already ignores a source `direction`
+     * line), and sequence/class/XY-chart diagrams have none to override, so
+     * all of those ignore this option (no error; output is identical with or
+     * without it). Same semantics as `RenderOptions.direction` for SVG. See
+     * issue #276.
+     */
+    direction?: Direction;
+    /**
+     * Emit OSC 8 terminal hyperlinks: each node whose `click` directive
+     * declared an http/https/mailto/relative href gets its label wrapped in
+     * an `ESC ] 8 ; ; <url> ESC \` … `ESC ] 8 ; ; ESC \` pair, which
+     * terminals that support OSC 8 (iTerm2, WezTerm, kitty, Windows
+     * Terminal, VTE-based terminals) render as a clickable link. The
+     * sequences are zero-width and never affect layout; `click ... call fn()`
+     * bindings emit nothing. Off by default — not every terminal or pager
+     * handles OSC 8 gracefully (`less` needs `-R`), and no capability
+     * detection is attempted here; the caller decides. Ignored when
+     * `colorMode` is 'html'.
+     */
+    hyperlinks?: boolean;
+}
+
+/**
+ * Theme colors for ASCII output — hex color strings.
+ * Derived from the SVG theme system for visual consistency.
+ */
+export declare interface AsciiTheme {
+    /** Text color (node labels, edge labels) */
+    fg: string;
+    /** Box border color (node borders, subgraph borders) */
+    border: string;
+    /** Edge line color (paths between nodes) */
+    line: string;
+    /** Arrowhead color (▲▼◄► or ^v<>) */
+    arrow: string;
+    /** Theme accent color (optional, used by xycharts for series 0) */
+    accent?: string;
+    /** Background color (optional, used by xycharts for dark-mode-aware shading) */
+    bg?: string;
+    /** Corner character color (optional, defaults to line) */
+    corner?: string;
+    /** Junction character color (optional, defaults to border) */
+    junction?: string;
+}
+
+/** Color mode for output. */
+export declare type ColorMode = 'none' | 'ansi16' | 'ansi256' | 'truecolor' | 'html';
+
+/**
+ * Default ASCII theme derived from the SVG renderer's color palette.
+ * Uses the same mixing ratios to maintain visual consistency.
+ */
+export declare const DEFAULT_ASCII_THEME: AsciiTheme;
+
+/**
+ * Detect the best color mode for the current environment.
+ *
+ * Terminal detection order:
+ * 1. COLORTERM=truecolor or COLORTERM=24bit → truecolor
+ * 2. TERM contains "256color" → ansi256
+ * 3. TERM is set and not "dumb" → ansi16
+ *
+ * Browser: returns 'html' (uses <span> tags with inline styles).
+ * Unknown/piped: returns 'none'.
+ */
+export declare function detectColorMode(): ColorMode;
+
+/**
+ * Derive an AsciiTheme from SVG DiagramColors using the same mixing ratios.
+ * Honors optional enrichment colors (line, accent, border) when present,
+ * otherwise falls back to color-mix derivation — matching SVG behavior.
+ */
+export declare function diagramColorsToAsciiTheme(colors: DiagramColors): AsciiTheme;
+
+/**
+ * Render Mermaid diagram text to an ASCII/Unicode string.
+ *
+ * Synchronous — no async layout engine needed (unlike the SVG renderer).
+ * Auto-detects diagram type from the header line and dispatches to
+ * the appropriate renderer.
+ *
+ * @param text - Mermaid source text (any supported diagram type)
+ * @param options - Rendering options
+ * @returns Multi-line ASCII/Unicode string
+ *
+ * @example
+ * ```ts
+ * const result = renderMermaidASCII(`
+ *   graph LR
+ *     A --> B --> C
+ * `, { useAscii: true })
+ *
+ * // Output:
+ * // +---+     +---+     +---+
+ * // |   |     |   |     |   |
+ * // | A |---->| B |---->| C |
+ * // |   |     |   |     |   |
+ * // +---+     +---+     +---+
+ * ```
+ */
+export declare function renderMermaidASCII(text: string, options?: AsciiRenderOptions): string;
+
+/** @deprecated Use `renderMermaidASCII` */
+export declare const renderMermaidAscii: typeof renderMermaidASCII;
+
+export { }

package/dist/index.d.ts

@@ -0,0 +1,146 @@
+import { DiagramColors } from '@zombie-mermaid/core';
+import { Direction } from '@zombie-mermaid/core';
+
+export declare interface AsciiRenderOptions {
+    /** true = ASCII chars (+,-,|,>), false = Unicode box-drawing (┌,─,│,►). Default: false */
+    useAscii?: boolean;
+    /** Horizontal spacing between nodes. Default: 5 */
+    paddingX?: number;
+    /** Vertical spacing between nodes. Default: 5 */
+    paddingY?: number;
+    /** Padding inside node boxes. Default: 1 */
+    boxBorderPadding?: number;
+    /**
+     * Color mode for output.
+     * - 'none': No colors (plain text)
+     * - 'auto': Auto-detect (terminal ANSI capabilities, or HTML in browsers)
+     * - 'ansi16': 16-color ANSI
+     * - 'ansi256': 256-color xterm
+     * - 'truecolor': 24-bit RGB
+     * - 'html': HTML <span> tags with inline color styles (for browser rendering)
+     * Default: 'auto'
+     */
+    colorMode?: ColorMode | 'auto';
+    /** Theme colors for ASCII output. Uses default theme if not provided. */
+    theme?: Partial<AsciiTheme>;
+    /**
+     * Overlay spreadsheet-style row/column indices on the rendered output, to
+     * help debug layout spacing. Off by default.
+     */
+    showCoords?: boolean;
+    /**
+     * Force the diagram's layout direction, overriding the one its source
+     * declares (a flowchart's `graph LR` header, or a state diagram's
+     * top-level `direction LR` line). Applied after parsing and before
+     * layout — the source text is never rewritten. Replaces only the
+     * top-level direction: a nested subgraph's or composite state's own
+     * `direction` line still applies on top of it, exactly as it does on top
+     * of the diagram's own header.
+     *
+     * Flowchart and state diagrams only in ASCII output. The ASCII ER layout
+     * has no direction concept (it already ignores a source `direction`
+     * line), and sequence/class/XY-chart diagrams have none to override, so
+     * all of those ignore this option (no error; output is identical with or
+     * without it). Same semantics as `RenderOptions.direction` for SVG. See
+     * issue #276.
+     */
+    direction?: Direction;
+    /**
+     * Emit OSC 8 terminal hyperlinks: each node whose `click` directive
+     * declared an http/https/mailto/relative href gets its label wrapped in
+     * an `ESC ] 8 ; ; <url> ESC \` … `ESC ] 8 ; ; ESC \` pair, which
+     * terminals that support OSC 8 (iTerm2, WezTerm, kitty, Windows
+     * Terminal, VTE-based terminals) render as a clickable link. The
+     * sequences are zero-width and never affect layout; `click ... call fn()`
+     * bindings emit nothing. Off by default — not every terminal or pager
+     * handles OSC 8 gracefully (`less` needs `-R`), and no capability
+     * detection is attempted here; the caller decides. Ignored when
+     * `colorMode` is 'html'.
+     */
+    hyperlinks?: boolean;
+}
+
+/**
+ * Theme colors for ASCII output — hex color strings.
+ * Derived from the SVG theme system for visual consistency.
+ */
+export declare interface AsciiTheme {
+    /** Text color (node labels, edge labels) */
+    fg: string;
+    /** Box border color (node borders, subgraph borders) */
+    border: string;
+    /** Edge line color (paths between nodes) */
+    line: string;
+    /** Arrowhead color (▲▼◄► or ^v<>) */
+    arrow: string;
+    /** Theme accent color (optional, used by xycharts for series 0) */
+    accent?: string;
+    /** Background color (optional, used by xycharts for dark-mode-aware shading) */
+    bg?: string;
+    /** Corner character color (optional, defaults to line) */
+    corner?: string;
+    /** Junction character color (optional, defaults to border) */
+    junction?: string;
+}
+
+/** Color mode for output. */
+export declare type ColorMode = 'none' | 'ansi16' | 'ansi256' | 'truecolor' | 'html';
+
+/**
+ * Default ASCII theme derived from the SVG renderer's color palette.
+ * Uses the same mixing ratios to maintain visual consistency.
+ */
+export declare const DEFAULT_ASCII_THEME: AsciiTheme;
+
+/**
+ * Detect the best color mode for the current environment.
+ *
+ * Terminal detection order:
+ * 1. COLORTERM=truecolor or COLORTERM=24bit → truecolor
+ * 2. TERM contains "256color" → ansi256
+ * 3. TERM is set and not "dumb" → ansi16
+ *
+ * Browser: returns 'html' (uses <span> tags with inline styles).
+ * Unknown/piped: returns 'none'.
+ */
+export declare function detectColorMode(): ColorMode;
+
+/**
+ * Derive an AsciiTheme from SVG DiagramColors using the same mixing ratios.
+ * Honors optional enrichment colors (line, accent, border) when present,
+ * otherwise falls back to color-mix derivation — matching SVG behavior.
+ */
+export declare function diagramColorsToAsciiTheme(colors: DiagramColors): AsciiTheme;
+
+/**
+ * Render Mermaid diagram text to an ASCII/Unicode string.
+ *
+ * Synchronous — no async layout engine needed (unlike the SVG renderer).
+ * Auto-detects diagram type from the header line and dispatches to
+ * the appropriate renderer.
+ *
+ * @param text - Mermaid source text (any supported diagram type)
+ * @param options - Rendering options
+ * @returns Multi-line ASCII/Unicode string
+ *
+ * @example
+ * ```ts
+ * const result = renderMermaidASCII(`
+ *   graph LR
+ *     A --> B --> C
+ * `, { useAscii: true })
+ *
+ * // Output:
+ * // +---+     +---+     +---+
+ * // |   |     |   |     |   |
+ * // | A |---->| B |---->| C |
+ * // |   |     |   |     |   |
+ * // +---+     +---+     +---+
+ * ```
+ */
+export declare function renderMermaidASCII(text: string, options?: AsciiRenderOptions): string;
+
+/** @deprecated Use `renderMermaidASCII` */
+export declare const renderMermaidAscii: typeof renderMermaidASCII;
+
+export { }