@mdxui/terminal 2.0.0

package/dist/renderers/index.d.ts

@@ -0,0 +1,546 @@
+export { A as ANSIToCSSResult, C as CSSStyleProperties, S as StyledSpan, T as TextRenderOptions, a as ansiToCSS, b as ansiToHTML, p as parseAnsiToSpans, r as renderText, s as spanToInlineStyle } from '../ansi-css-_3eSEU9d.js';
+import { U as UINode, a as RenderContext } from '../types-Bxu5PAgA.js';
+export { C as ClickableOptions, d as ComponentOptions, F as FocusableOptions, b as InputOptions, I as InteractiveRenderer, a as InteractiveRendererConfig, c as createInteractiveRenderer } from '../interactive-D0JkWosD.js';
+import 'zod';
+
+/**
+ * Markdown Renderer
+ *
+ * Converts UINode trees to Markdown strings for AI agent consumption via MCP.
+ *
+ * The Markdown renderer outputs structured markdown that is:
+ * - Easily parseable by AI agents
+ * - Human-readable in raw form
+ * - Compatible with MCP (Model Context Protocol) text transport
+ *
+ * Markdown Tier (tier 2 of 6):
+ * Designed for AI agents that consume structured text via MCP protocols.
+ * More structured than TEXT tier, less visual than ASCII/UNICODE/ANSI.
+ */
+
+/**
+ * Markdown render options
+ */
+interface MarkdownRenderOptions {
+    /** Maximum line width for wrapping (optional) */
+    width?: number;
+    /** Whether to include navigation footer hints */
+    includeNavFooter?: boolean;
+    /** Header level offset (e.g., 1 to start at H2 instead of H1) */
+    headerOffset?: number;
+    /** Whether to escape special markdown characters in content */
+    escapeContent?: boolean;
+}
+/**
+ * Renders a UINode tree to a Markdown string for AI agent consumption.
+ *
+ * @param node - The UINode tree to render
+ * @param options - Optional rendering configuration
+ * @returns Markdown string
+ */
+declare function renderMarkdown(node: UINode, options?: MarkdownRenderOptions): string;
+
+/**
+ * ASCII Renderer - TDD GREEN Phase Implementation
+ *
+ * This file implements the ASCII renderer for the 6-tier Universal Terminal UI.
+ * All output uses pure ASCII characters (0x00-0x7F) for maximum compatibility.
+ *
+ * ASCII Tier Constraints:
+ * - Output must contain ONLY ASCII characters (0x00-0x7F)
+ * - No unicode box drawing characters (U+2500-U+257F)
+ * - No ANSI escape sequences
+ * - No emoji or special symbols
+ */
+
+/**
+ * Renders a UINode tree to pure ASCII output for low-capability terminals.
+ */
+declare function renderASCII(node: UINode, context?: RenderContext): string;
+
+/**
+ * Unicode Renderer - Renders UINode trees using Unicode box-drawing characters
+ *
+ * This renderer is part of the 6-tier Universal Terminal UI system.
+ * It uses Unicode characters for beautiful terminal output without ANSI colors.
+ *
+ * Unicode box drawing characters:
+ * - Single: ┌ ─ ┐ │ └ ┘ ├ ┤ ┬ ┴ ┼
+ * - Double: ╔ ═ ╗ ║ ╚ ╝
+ * - Rounded: ╭ ╮ ╰ ╯
+ *
+ * Bullets: • ◦ ▪ ▸ ▾ ✓ ✗
+ * Progress: ▓ ░ ▒
+ * Spinners: ⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏
+ */
+
+/**
+ * Renders a UINode tree to Unicode box-drawing output.
+ *
+ * This renderer is part of the 6-tier Universal Terminal UI system.
+ * It outputs Unicode characters for beautiful terminal borders and
+ * symbols without using ANSI escape sequences for colors.
+ *
+ * @param node - The UINode tree to render
+ * @param context - Optional render context with width, height, theme
+ * @returns Unicode string ready for terminal output
+ *
+ * @example
+ * ```ts
+ * const node: UINode = {
+ *   type: 'box',
+ *   props: { border: 'single' },
+ *   children: [{ type: 'text', props: { content: 'Hello' } }]
+ * }
+ *
+ * const output = renderUnicode(node)
+ * // ┌───────┐
+ * // │ Hello │
+ * // └───────┘
+ * ```
+ */
+declare function renderUnicode(node: UINode, context?: RenderContext): string;
+
+/**
+ * ANSI Renderer
+ *
+ * Converts UINode trees to ANSI-escaped terminal strings with support for:
+ * - 16 color, 256 color, and true color modes
+ * - Text formatting (bold, italic, underline, etc.)
+ * - Theme colors (dark/light mode with semantic colors)
+ * - Graceful color degradation
+ */
+
+/**
+ * ANSI render options
+ */
+interface ANSIRenderOptions {
+    colorSupport?: 'none' | '16' | '256' | 'truecolor';
+    theme?: 'dark' | 'light';
+    width?: number;
+    resetBetweenElements?: boolean;
+}
+/**
+ * Renders a UINode tree to an ANSI-escaped string for terminal output.
+ *
+ * @param node - The UINode tree to render
+ * @param options - Rendering options (color support, theme, width)
+ * @returns ANSI-escaped string ready for terminal output
+ *
+ * @example
+ * ```tsx
+ * const node = { type: 'text', text: 'Hello', props: { color: 'cyan', bold: true } }
+ * const output = renderANSI(node)
+ * console.log(output) // Outputs bold cyan text
+ * ```
+ */
+declare function renderANSI(node: UINode, options?: ANSIRenderOptions): string;
+
+/**
+ * @mdxui/terminal Interactive String Renderer
+ *
+ * This module provides a string-based implementation of the interactive tier
+ * that does not depend on @opentui/core. It is used for testing and situations
+ * where a string output is needed rather than an actual TUI.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Renders a UINode to a string for the interactive tier.
+ * This provides compatibility with the test suite that expects
+ * a string-returning render function like other tiers.
+ */
+declare function renderInteractive(node: UINode, _context: RenderContext): string;
+
+/**
+ * Renderer Common Utilities
+ *
+ * Shared abstractions used across all 6-tier renderers (TEXT, MARKDOWN, ASCII, UNICODE, ANSI, INTERACTIVE).
+ * Extracted to ensure DRY principles and consistent behavior across renderers.
+ *
+ * Key abstractions:
+ * - Box drawing (ASCII/Unicode share logic)
+ * - Width/height calculations
+ * - Text alignment and wrapping
+ * - Indentation helpers
+ * - Character sanitization
+ * - Renderer registry pattern
+ */
+
+/**
+ * Box drawing character sets for different border styles
+ */
+interface BoxChars {
+    topLeft: string;
+    topRight: string;
+    bottomLeft: string;
+    bottomRight: string;
+    horizontal: string;
+    vertical: string;
+}
+/**
+ * Text alignment options
+ */
+type TextAlign = 'left' | 'center' | 'right';
+/**
+ * Indent calculation: returns a string of spaces for the given level
+ * Each level = 2 spaces
+ *
+ * @param level - Indentation level (0-based)
+ * @returns Indentation string (2 spaces per level)
+ */
+declare function getIndentStr(level: number): string;
+/**
+ * Calculates visible text width by counting characters
+ * This is a basic implementation; use in TEXT/MARKDOWN tiers
+ *
+ * @param text - Text to measure
+ * @returns Character count (visible width)
+ */
+declare function getTextWidth(text: string): number;
+/**
+ * Pads text to a given width for alignment
+ * Supports left/center/right alignment
+ *
+ * @param text - Text to pad
+ * @param width - Target width
+ * @param align - Alignment direction (default: 'left')
+ * @param padChar - Character to use for padding (default: space)
+ * @returns Padded text string
+ */
+declare function padText(text: string, width: number, align?: TextAlign, padChar?: string): string;
+/**
+ * Wraps text to fit within a given width, preserving words when possible.
+ * Handles explicit newlines and long words.
+ *
+ * @param text - Text to wrap
+ * @param maxWidth - Maximum line width
+ * @returns Array of wrapped lines
+ */
+declare function wrapText(text: string, maxWidth: number): string[];
+/**
+ * Sanitizes text to ensure only ASCII characters (0x00-0x7F) are present.
+ * Replaces unicode characters with ASCII equivalents or removes them.
+ *
+ * @param text - Text to sanitize
+ * @returns ASCII-safe text string
+ */
+declare function sanitizeToASCII(text: string): string;
+/**
+ * Converts unicode box drawing character to ASCII equivalent
+ * Used by sanitizeToASCII and ASCII renderer
+ *
+ * @param char - Unicode box drawing character
+ * @returns ASCII equivalent or '+'
+ */
+declare function boxDrawingToASCII(char: string): string;
+/**
+ * Builds a box (border + content) using provided box characters
+ * Shared logic for ASCII and Unicode renderers
+ *
+ * @param chars - Box characters (corners, edges)
+ * @param contentLines - Content lines to place inside box
+ * @param width - Total box width (including borders)
+ * @returns Array of box lines (ready to join with '\n')
+ */
+declare function buildBox(chars: BoxChars, contentLines: string[], width: number): string[];
+/**
+ * Extracts string values from mixed-type arrays
+ * Common pattern: converting items array to string array for rendering
+ *
+ * @param items - Array of unknown items
+ * @returns Array of string values
+ */
+declare function extractStringArray(items: unknown[]): string[];
+/**
+ * Extracts headers from column definitions
+ * Common pattern: table renderers need to map columns to headers
+ *
+ * @param columns - Array of column definitions with 'header' property
+ * @returns Array of header strings
+ */
+declare function extractHeaders(columns: Array<{
+    header?: string;
+    key?: string;
+}> | undefined): string[];
+/**
+ * Extracts values from a row using column keys
+ * Common pattern: table row rendering
+ *
+ * @param row - Object with row data
+ * @param columns - Array of column definitions with 'key' property
+ * @returns Array of row values as strings
+ */
+declare function extractRowValues(row: Record<string, unknown>, columns: Array<{
+    key: string;
+}> | undefined): string[];
+/**
+ * Combines multiple strings into a single output with separator
+ * Used for joining title, content, and footer sections
+ *
+ * @param parts - Array of string parts (filtered to remove empty)
+ * @param separator - String to join parts (default: '\n\n')
+ * @returns Joined string or empty string
+ */
+declare function joinParts(parts: string[], separator?: string): string;
+/**
+ * Type-safe property access with default fallback
+ * Used throughout renderers to safely extract typed props
+ *
+ * @param obj - Object to access
+ * @param key - Property key
+ * @param defaultValue - Fallback value if undefined
+ * @returns Property value or default
+ */
+declare function getProp<T>(obj: Record<string, unknown>, key: string, defaultValue: T): T;
+/**
+ * Renderer registry pattern: allows dynamic renderer lookup
+ * Used by multi-tier rendering to delegate to appropriate renderer
+ */
+type RendererRegistry = {
+    [tier in 'text' | 'markdown' | 'ascii' | 'unicode' | 'ansi' | 'interactive']?: (node: any, context?: any) => string;
+};
+/**
+ * Theme token color constants
+ * Shared across renderers for theme support
+ */
+declare const DEFAULT_THEME_TOKENS: {
+    readonly primary: "";
+    readonly secondary: "";
+    readonly muted: "";
+    readonly foreground: "";
+    readonly background: "";
+    readonly border: "";
+    readonly success: "";
+    readonly warning: "";
+    readonly error: "";
+    readonly info: "";
+};
+/**
+ * Default render context values
+ * Standard dimensions for terminal rendering
+ */
+declare const DEFAULT_RENDER_CONTEXT: {
+    readonly width: 80;
+    readonly height: 24;
+    readonly depth: 0;
+};
+/**
+ * ASCII box drawing characters
+ * Uses +, -, | for maximum compatibility
+ */
+declare const ASCII_BOX_CHARS: BoxChars;
+/**
+ * ASCII double-line box drawing characters
+ * Uses = for horizontal lines
+ */
+declare const ASCII_DOUBLE_BOX_CHARS: BoxChars;
+/**
+ * Unicode single-line box drawing characters
+ */
+declare const UNICODE_SINGLE_BOX_CHARS: BoxChars;
+/**
+ * Unicode double-line box drawing characters
+ */
+declare const UNICODE_DOUBLE_BOX_CHARS: BoxChars;
+/**
+ * Unicode rounded box drawing characters
+ */
+declare const UNICODE_ROUNDED_BOX_CHARS: BoxChars;
+/**
+ * Gets ASCII box characters for a border style
+ *
+ * @param style - Border style: 'single', 'double', or 'none'
+ * @returns BoxChars for the specified style
+ */
+declare function getASCIIBoxChars(style: string): BoxChars;
+/**
+ * Gets Unicode box characters for a border style
+ *
+ * @param style - Border style: 'single', 'double', 'rounded', or 'none'
+ * @returns BoxChars for the specified style
+ */
+declare function getUnicodeBoxChars(style: string): BoxChars;
+/**
+ * Unicode symbols for lists, progress, spinners, etc.
+ * Shared across Unicode and ANSI renderers
+ */
+declare const UNICODE_SYMBOLS: {
+    readonly bullet: "•";
+    readonly hollowBullet: "◦";
+    readonly squareBullet: "▪";
+    readonly triangleRight: "▸";
+    readonly triangleDown: "▾";
+    readonly checkmark: "✓";
+    readonly crossMark: "✗";
+    readonly unchecked: "☐";
+    readonly arrowRight: "→";
+    readonly arrowDown: "↓";
+    readonly progressFull: "▓";
+    readonly progressEmpty: "░";
+    readonly progressHalf: "▒";
+    readonly ellipsis: "…";
+    readonly middleDot: "·";
+    readonly teeLeft: "├";
+    readonly teeRight: "┤";
+    readonly teeTop: "┬";
+    readonly teeBottom: "┴";
+    readonly crossJunction: "┼";
+};
+/**
+ * Braille spinner animation frames
+ */
+declare const SPINNER_FRAMES: readonly ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+/**
+ * Calculates column widths for table rendering
+ *
+ * @param headers - Array of header strings
+ * @param rows - Array of row data (string arrays)
+ * @param maxTableWidth - Maximum allowed table width (optional)
+ * @returns Array of column widths
+ */
+declare function calculateColumnWidths(headers: string[], rows: string[][], maxTableWidth?: number): number[];
+/**
+ * Builds a table separator line
+ *
+ * @param colWidths - Array of column widths
+ * @param chars - Characters for corners and horizontal line
+ * @returns Separator line string
+ */
+declare function buildTableSeparator(colWidths: number[], chars: {
+    left: string;
+    middle: string;
+    right: string;
+    horizontal: string;
+}): string;
+/**
+ * Builds a table row with cell content
+ *
+ * @param cells - Array of cell content strings
+ * @param colWidths - Array of column widths
+ * @param vertical - Vertical separator character
+ * @returns Row line string
+ */
+declare function buildTableRow(cells: string[], colWidths: number[], vertical: string): string;
+/**
+ * Route matching mode for navigation components
+ */
+type RouteMatchMode = 'exact' | 'prefix' | 'pattern';
+/**
+ * Router adapter interface - implement this to integrate with any router library
+ * This abstraction allows components to work with React Router, Next.js, Vue Router, etc.
+ */
+interface RouterAdapter {
+    /** Get the current path/location */
+    getCurrentPath(): string;
+    /** Navigate to a path */
+    navigate(path: string): void;
+    /** Check if a path matches the current route */
+    isActive(path: string, mode?: RouteMatchMode): boolean;
+    /** Subscribe to route changes (returns unsubscribe function) */
+    subscribe?(callback: (path: string) => void): () => void;
+}
+/**
+ * Default router adapter that works without any router library
+ * Uses callbacks provided by the component user
+ */
+declare function createCallbackRouterAdapter(config: {
+    currentPath?: string;
+    onNavigate?: (path: string) => void;
+}): RouterAdapter;
+/**
+ * Matches a current path against a target path using the specified mode
+ *
+ * @param currentPath - The current route path
+ * @param targetPath - The path to match against
+ * @param mode - Match mode: 'exact', 'prefix', or 'pattern'
+ * @returns true if the paths match according to the mode
+ */
+declare function matchPath(currentPath: string, targetPath: string, mode?: RouteMatchMode): boolean;
+/**
+ * Normalizes a path by removing trailing slashes (except for root)
+ *
+ * @param path - Path to normalize
+ * @returns Normalized path
+ */
+declare function normalizePath(path: string): string;
+/**
+ * Matches a path against a pattern with :param and * wildcards
+ *
+ * @param path - Actual path to test
+ * @param pattern - Pattern with :param segments or * wildcard
+ * @returns true if the path matches the pattern
+ */
+declare function matchPathPattern(path: string, pattern: string): boolean;
+/**
+ * Generates breadcrumb segments from a path
+ *
+ * @param path - URL path (e.g., '/products/electronics/phones')
+ * @param options - Configuration for segment generation
+ * @returns Array of breadcrumb segments with labels and paths
+ */
+declare function generateBreadcrumbSegments(path: string, options?: {
+    /** Custom labels for specific paths (e.g., { '/products': 'Shop' }) */
+    labels?: Record<string, string>;
+    /** Function to generate label from segment (default: capitalize) */
+    labelGenerator?: (segment: string, fullPath: string) => string;
+    /** Whether to include home segment */
+    includeHome?: boolean;
+    /** Home segment label */
+    homeLabel?: string;
+}): Array<{
+    label: string;
+    path: string;
+}>;
+/**
+ * Formats a URL segment into a human-readable label
+ * Converts kebab-case or snake_case to Title Case
+ *
+ * @param segment - URL path segment (e.g., 'my-products')
+ * @returns Formatted label (e.g., 'My Products')
+ */
+declare function formatSegmentLabel(segment: string): string;
+/**
+ * Finds the active item in a navigation structure based on current path
+ *
+ * @param items - Array of items with path property
+ * @param currentPath - Current route path
+ * @param mode - Match mode for path comparison
+ * @returns The matching item's ID or undefined
+ */
+declare function findActiveItemByPath<T extends {
+    id: string;
+    path?: string;
+}>(items: T[], currentPath: string, mode?: RouteMatchMode): string | undefined;
+/**
+ * Finds the active item in nested navigation sections based on current path
+ *
+ * @param sections - Array of sections containing items with path property
+ * @param currentPath - Current route path
+ * @param mode - Match mode for path comparison
+ * @returns The matching item's ID or undefined
+ */
+declare function findActiveItemInSections<T extends {
+    id: string;
+    path?: string;
+}>(sections: Array<{
+    items: T[];
+}>, currentPath: string, mode?: RouteMatchMode): string | undefined;
+/**
+ * Builds a path by joining segments
+ *
+ * @param segments - Path segments to join
+ * @returns Joined and normalized path
+ */
+declare function joinPath(...segments: string[]): string;
+/**
+ * Extracts path parameters from a path using a pattern
+ *
+ * @param path - Actual path (e.g., '/users/123/edit')
+ * @param pattern - Pattern with :param segments (e.g., '/users/:id/edit')
+ * @returns Object with extracted parameters or null if no match
+ */
+declare function extractPathParams(path: string, pattern: string): Record<string, string> | null;
+
+export { ASCII_BOX_CHARS, ASCII_DOUBLE_BOX_CHARS, type BoxChars, DEFAULT_RENDER_CONTEXT, DEFAULT_THEME_TOKENS, type MarkdownRenderOptions, type RendererRegistry, type RouteMatchMode, type RouterAdapter, SPINNER_FRAMES, type TextAlign, UNICODE_DOUBLE_BOX_CHARS, UNICODE_ROUNDED_BOX_CHARS, UNICODE_SINGLE_BOX_CHARS, UNICODE_SYMBOLS, boxDrawingToASCII, buildBox, buildTableRow, buildTableSeparator, calculateColumnWidths, createCallbackRouterAdapter, extractHeaders, extractPathParams, extractRowValues, extractStringArray, findActiveItemByPath, findActiveItemInSections, formatSegmentLabel, generateBreadcrumbSegments, getASCIIBoxChars, getIndentStr, getProp, getTextWidth, getUnicodeBoxChars, joinParts, joinPath, matchPath, matchPathPattern, normalizePath, padText, renderANSI, renderASCII, renderInteractive, renderMarkdown, renderUnicode, sanitizeToASCII, wrapText };