@mdxui/terminal 2.0.0

package/src/renderers/ansi-css.ts

@@ -0,0 +1,576 @@
+/**
+ * ANSI to CSS Converter
+ *
+ * Converts ANSI escape codes to CSS styles for web rendering.
+ * This enables browser-based terminal emulators to display styled output.
+ *
+ * Supports:
+ * - 16 basic colors (30-37, 40-47)
+ * - Bright colors (90-97, 100-107)
+ * - 256-color mode (38;5;n and 48;5;n)
+ * - True color / 24-bit RGB (38;2;r;g;b and 48;2;r;g;b)
+ * - Text styles (bold, dim, italic, underline, strikethrough, inverse)
+ * - Reset codes (0, 22, 23, 24, 39, 49)
+ *
+ * @module
+ */
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * CSS style properties for a styled text span
+ */
+export interface CSSStyleProperties {
+  color?: string
+  backgroundColor?: string
+  fontWeight?: 'bold' | 'normal'
+  fontStyle?: 'italic' | 'normal'
+  textDecoration?: 'underline' | 'line-through' | 'none'
+  opacity?: number
+}
+
+/**
+ * A span of text with associated CSS styles
+ */
+export interface StyledSpan {
+  text: string
+  style: CSSStyleProperties
+}
+
+/**
+ * Result of parsing ANSI string to CSS
+ */
+export interface ANSIToCSSResult {
+  spans: StyledSpan[]
+  plainText: string
+}
+
+/**
+ * Internal state for tracking current styles during parsing
+ */
+interface StyleState {
+  color?: string
+  backgroundColor?: string
+  bold?: boolean
+  dim?: boolean
+  italic?: boolean
+  underline?: boolean
+  strikethrough?: boolean
+  inverse?: boolean
+}
+
+// ============================================================================
+// Color Maps
+// ============================================================================
+
+/** Standard 16 foreground color names (codes 30-37) */
+const FG_16_COLORS: Record<number, string> = {
+  30: 'black',
+  31: 'red',
+  32: 'green',
+  33: 'yellow',
+  34: 'blue',
+  35: 'magenta',
+  36: 'cyan',
+  37: 'white',
+}
+
+/** Bright foreground color hex values (codes 90-97) */
+const FG_BRIGHT_COLORS: Record<number, string> = {
+  90: 'gray',
+  91: '#ff5555',
+  92: '#55ff55',
+  93: '#ffff55',
+  94: '#5555ff',
+  95: '#ff55ff',
+  96: '#55ffff',
+  97: '#ffffff',
+}
+
+/** Standard 16 background color names (codes 40-47) */
+const BG_16_COLORS: Record<number, string> = {
+  40: 'black',
+  41: 'red',
+  42: 'green',
+  43: 'yellow',
+  44: 'blue',
+  45: 'magenta',
+  46: 'cyan',
+  47: 'white',
+}
+
+/** Standard 16 colors for 256-mode codes 0-15 */
+const STANDARD_16_HEX: string[] = [
+  '#000000', // 0 - black
+  '#800000', // 1 - maroon
+  '#008000', // 2 - green
+  '#808000', // 3 - olive
+  '#000080', // 4 - navy
+  '#800080', // 5 - purple
+  '#008080', // 6 - teal
+  '#c0c0c0', // 7 - silver
+  '#808080', // 8 - gray
+  '#ff0000', // 9 - red
+  '#00ff00', // 10 - lime
+  '#ffff00', // 11 - yellow
+  '#0000ff', // 12 - blue
+  '#ff00ff', // 13 - fuchsia
+  '#00ffff', // 14 - aqua
+  '#ffffff', // 15 - white
+]
+
+// ============================================================================
+// Color Conversion Utilities
+// ============================================================================
+
+/**
+ * Convert 256-color code to hex value.
+ *
+ * The 256-color palette is organized as:
+ * - 0-15: Standard 16 colors
+ * - 16-231: 6x6x6 color cube (216 colors)
+ * - 232-255: Grayscale ramp (24 shades)
+ */
+function ansi256ToHex(code: number): string {
+  // Standard 16 colors (0-15)
+  if (code < 16) {
+    return STANDARD_16_HEX[code]
+  }
+
+  // Grayscale ramp (232-255)
+  if (code >= 232) {
+    const gray = (code - 232) * 10 + 8
+    const hex = gray.toString(16).padStart(2, '0')
+    return `#${hex}${hex}${hex}`
+  }
+
+  // 6x6x6 color cube (16-231)
+  const cubeIndex = code - 16
+  const r = Math.floor(cubeIndex / 36)
+  const g = Math.floor((cubeIndex % 36) / 6)
+  const b = cubeIndex % 6
+
+  // Each color channel maps: 0=0, 1=95, 2=135, 3=175, 4=215, 5=255
+  const toValue = (n: number): number => (n === 0 ? 0 : 55 + n * 40)
+
+  const rVal = toValue(r).toString(16).padStart(2, '0')
+  const gVal = toValue(g).toString(16).padStart(2, '0')
+  const bVal = toValue(b).toString(16).padStart(2, '0')
+
+  return `#${rVal}${gVal}${bVal}`
+}
+
+// ============================================================================
+// SGR Code Processing
+// ============================================================================
+
+/**
+ * Process a single SGR (Select Graphic Rendition) parameter
+ */
+function processSGRCode(
+  code: number,
+  params: number[],
+  index: number,
+  state: StyleState
+): number {
+  // Reset all styles
+  if (code === 0) {
+    state.color = undefined
+    state.backgroundColor = undefined
+    state.bold = undefined
+    state.dim = undefined
+    state.italic = undefined
+    state.underline = undefined
+    state.strikethrough = undefined
+    state.inverse = undefined
+    return index
+  }
+
+  // Text styles
+  if (code === 1) {
+    state.bold = true
+    return index
+  }
+  if (code === 2) {
+    state.dim = true
+    return index
+  }
+  if (code === 3) {
+    state.italic = true
+    return index
+  }
+  if (code === 4) {
+    state.underline = true
+    return index
+  }
+  if (code === 7) {
+    state.inverse = true
+    return index
+  }
+  if (code === 9) {
+    state.strikethrough = true
+    return index
+  }
+
+  // Reset specific styles
+  if (code === 22) {
+    state.bold = false
+    state.dim = false
+    return index
+  }
+  if (code === 23) {
+    state.italic = false
+    return index
+  }
+  if (code === 24) {
+    state.underline = false
+    return index
+  }
+
+  // Standard 16 foreground colors (30-37)
+  if (code >= 30 && code <= 37) {
+    state.color = FG_16_COLORS[code]
+    return index
+  }
+
+  // Reset foreground color
+  if (code === 39) {
+    state.color = undefined
+    return index
+  }
+
+  // Standard 16 background colors (40-47)
+  if (code >= 40 && code <= 47) {
+    state.backgroundColor = BG_16_COLORS[code]
+    return index
+  }
+
+  // Reset background color
+  if (code === 49) {
+    state.backgroundColor = undefined
+    return index
+  }
+
+  // Bright foreground colors (90-97)
+  if (code >= 90 && code <= 97) {
+    state.color = FG_BRIGHT_COLORS[code]
+    return index
+  }
+
+  // Extended colors (38 = foreground, 48 = background)
+  if (code === 38 || code === 48) {
+    const isForeground = code === 38
+
+    // Check for 256-color mode (38;5;n or 48;5;n)
+    if (params[index + 1] === 5 && params[index + 2] !== undefined) {
+      const colorCode = params[index + 2]
+      const hexColor = ansi256ToHex(colorCode)
+      if (isForeground) {
+        state.color = hexColor
+      } else {
+        state.backgroundColor = hexColor
+      }
+      return index + 2
+    }
+
+    // Check for true color mode (38;2;r;g;b or 48;2;r;g;b)
+    if (
+      params[index + 1] === 2 &&
+      params[index + 2] !== undefined &&
+      params[index + 3] !== undefined &&
+      params[index + 4] !== undefined
+    ) {
+      const r = params[index + 2]
+      const g = params[index + 3]
+      const b = params[index + 4]
+      const rgbColor = `rgb(${r}, ${g}, ${b})`
+      if (isForeground) {
+        state.color = rgbColor
+      } else {
+        state.backgroundColor = rgbColor
+      }
+      return index + 4
+    }
+  }
+
+  // Unknown code - ignore
+  return index
+}
+
+// ============================================================================
+// Style State to CSS Properties
+// ============================================================================
+
+/**
+ * Convert internal style state to CSS properties object
+ */
+function stateToCSS(state: StyleState): CSSStyleProperties {
+  const css: CSSStyleProperties = {}
+
+  let fg = state.color
+  let bg = state.backgroundColor
+
+  // Handle inverse: swap foreground and background
+  if (state.inverse) {
+    const tempFg = fg
+    fg = bg || 'inherit' // If no bg, use default
+    bg = tempFg
+  }
+
+  if (fg) {
+    css.color = fg
+  }
+  if (bg) {
+    css.backgroundColor = bg
+  }
+  if (state.bold) {
+    css.fontWeight = 'bold'
+  } else if (state.bold === false) {
+    css.fontWeight = 'normal'
+  }
+  if (state.dim) {
+    css.opacity = 0.5
+  }
+  if (state.italic) {
+    css.fontStyle = 'italic'
+  } else if (state.italic === false) {
+    css.fontStyle = 'normal'
+  }
+  if (state.underline) {
+    css.textDecoration = 'underline'
+  } else if (state.underline === false) {
+    css.textDecoration = 'none'
+  }
+  if (state.strikethrough) {
+    css.textDecoration = 'line-through'
+  }
+
+  return css
+}
+
+/**
+ * Check if style state has any active styles
+ */
+function hasActiveStyles(state: StyleState): boolean {
+  return !!(
+    state.color ||
+    state.backgroundColor ||
+    state.bold ||
+    state.dim ||
+    state.italic ||
+    state.underline ||
+    state.strikethrough ||
+    state.inverse
+  )
+}
+
+/**
+ * Clone a style state
+ */
+function cloneState(state: StyleState): StyleState {
+  return { ...state }
+}
+
+// ============================================================================
+// ANSI Parsing
+// ============================================================================
+
+/**
+ * Regex to match ANSI escape sequences:
+ * - CSI sequences: ESC [ ... m (SGR codes)
+ * - OSC sequences: ESC ] ... (like hyperlinks)
+ * - Other escape sequences we want to strip
+ */
+const ANSI_REGEX = /\x1b(?:\[([0-9;]*)([A-Za-z])|\].*?(?:\x1b\\|\x07)|\[[^m]*)/g
+
+/**
+ * Parse ANSI string and extract styled spans
+ */
+function parseAnsi(ansiString: string): StyledSpan[] {
+  if (!ansiString) {
+    return []
+  }
+
+  const spans: StyledSpan[] = []
+  const state: StyleState = {}
+
+  let lastIndex = 0
+  let match: RegExpExecArray | null
+
+  // Reset regex state
+  ANSI_REGEX.lastIndex = 0
+
+  while ((match = ANSI_REGEX.exec(ansiString)) !== null) {
+    // Extract text before this escape sequence
+    const textBefore = ansiString.slice(lastIndex, match.index)
+    if (textBefore) {
+      spans.push({
+        text: textBefore,
+        style: stateToCSS(cloneState(state)),
+      })
+    }
+
+    // Process SGR sequence (ends with 'm')
+    const params = match[1]
+    const terminator = match[2]
+
+    if (terminator === 'm' && params !== undefined) {
+      // Parse the parameters
+      const codes = params
+        .split(';')
+        .filter((p) => p !== '')
+        .map((p) => parseInt(p, 10))
+
+      // Handle empty params (just \x1b[m means reset)
+      if (codes.length === 0) {
+        codes.push(0)
+      }
+
+      // Process each code
+      let i = 0
+      while (i < codes.length) {
+        i = processSGRCode(codes[i], codes, i, state) + 1
+      }
+    }
+
+    lastIndex = match.index + match[0].length
+  }
+
+  // Handle remaining text after last escape sequence
+  const remainingText = ansiString.slice(lastIndex)
+  if (remainingText) {
+    spans.push({
+      text: remainingText,
+      style: stateToCSS(cloneState(state)),
+    })
+  }
+
+  return spans
+}
+
+// ============================================================================
+// Public API
+// ============================================================================
+
+/**
+ * Converts ANSI-escaped string to CSS-styled spans.
+ *
+ * @param ansiString - String containing ANSI escape codes
+ * @returns Object with spans array and plain text
+ *
+ * @example
+ * ```ts
+ * const result = ansiToCSS('\x1b[31mRed text\x1b[0m')
+ * // result.spans[0].style.color === 'red'
+ * // result.plainText === 'Red text'
+ * ```
+ */
+export function ansiToCSS(ansiString: string): ANSIToCSSResult {
+  const spans = parseAnsi(ansiString)
+  const plainText = spans.map((s) => s.text).join('')
+
+  return {
+    spans,
+    plainText,
+  }
+}
+
+/**
+ * Converts a styled span to an inline CSS style string.
+ *
+ * @param span - A styled span object
+ * @returns CSS inline style string (e.g., "color: red; font-weight: bold")
+ */
+export function spanToInlineStyle(span: StyledSpan): string {
+  const parts: string[] = []
+
+  if (span.style.color) {
+    parts.push(`color: ${span.style.color}`)
+  }
+  if (span.style.backgroundColor) {
+    parts.push(`background-color: ${span.style.backgroundColor}`)
+  }
+  if (span.style.fontWeight) {
+    parts.push(`font-weight: ${span.style.fontWeight}`)
+  }
+  if (span.style.fontStyle) {
+    parts.push(`font-style: ${span.style.fontStyle}`)
+  }
+  if (span.style.textDecoration) {
+    parts.push(`text-decoration: ${span.style.textDecoration}`)
+  }
+  if (span.style.opacity !== undefined) {
+    parts.push(`opacity: ${span.style.opacity}`)
+  }
+
+  return parts.join('; ')
+}
+
+/**
+ * Escape HTML special characters to prevent XSS
+ */
+function escapeHTML(text: string): string {
+  return text
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;')
+}
+
+/**
+ * Converts ANSI-escaped string to HTML with styled span elements.
+ *
+ * @param ansiString - String containing ANSI escape codes
+ * @returns HTML string with styled spans
+ *
+ * @example
+ * ```ts
+ * const html = ansiToHTML('\x1b[31mRed text\x1b[0m')
+ * // html === '<span style="color: red">Red text</span>'
+ * ```
+ */
+export function ansiToHTML(ansiString: string): string {
+  if (!ansiString) {
+    return ''
+  }
+
+  const { spans } = ansiToCSS(ansiString)
+
+  if (spans.length === 0) {
+    return ''
+  }
+
+  // If single unstyled span, return plain text
+  if (spans.length === 1 && Object.keys(spans[0].style).length === 0) {
+    const text = escapeHTML(spans[0].text)
+    return text.replace(/\n/g, '<br>')
+  }
+
+  const htmlParts: string[] = []
+
+  for (const span of spans) {
+    const escapedText = escapeHTML(span.text).replace(/\n/g, '<br>')
+    const styleString = spanToInlineStyle(span)
+
+    if (styleString) {
+      htmlParts.push(`<span style="${styleString}">${escapedText}</span>`)
+    } else {
+      htmlParts.push(escapedText)
+    }
+  }
+
+  return htmlParts.join('')
+}
+
+/**
+ * Parses ANSI string to array of styled spans for React rendering.
+ *
+ * @param ansiString - String containing ANSI escape codes
+ * @returns Array of styled spans with React-compatible style objects
+ */
+export function parseAnsiToSpans(ansiString: string): StyledSpan[] {
+  return parseAnsi(ansiString)
+}