@mdxui/terminal 2.0.0

package/src/theme/color-convert.ts

@@ -0,0 +1,254 @@
+/**
+ * Color Conversion Utilities
+ *
+ * Functions for converting between color formats:
+ * - RGB to ANSI 256 color codes
+ * - Hex to RGB
+ * - True color (24-bit) escape sequences
+ *
+ * All public APIs include runtime validation via Zod schemas.
+ *
+ * @module
+ */
+
+import {
+  Ansi256CodeSchema,
+  HexColorSchema,
+  RgbComponentSchema,
+} from '../schemas'
+
+// ============================================================================
+// Internal Helpers
+// ============================================================================
+
+/**
+ * Convert RGB values to the nearest ANSI 256 color code
+ */
+function rgbToAnsi256(r: number, g: number, b: number): number {
+  // Check for exact black
+  if (r === 0 && g === 0 && b === 0) {
+    return 0
+  }
+
+  // Check for exact white
+  if (r === 255 && g === 255 && b === 255) {
+    return 15
+  }
+
+  // Check for grayscale (when r, g, b are close to each other)
+  if (Math.abs(r - g) < 10 && Math.abs(g - b) < 10 && Math.abs(r - b) < 10) {
+    const avg = (r + g + b) / 3
+    if (avg < 8) return 0 // black
+    if (avg > 248) return 15 // white
+    // Grayscale range: 232-255 (24 shades)
+    const grayIndex = Math.round((avg - 8) / 10)
+    return Math.min(255, Math.max(232, 232 + grayIndex))
+  }
+
+  // Convert to 6x6x6 color cube (colors 16-231)
+  const toColorCubeIndex = (v: number): number => {
+    if (v < 48) return 0
+    if (v < 115) return 1
+    return Math.min(5, Math.floor((v - 35) / 40))
+  }
+
+  const ri = toColorCubeIndex(r)
+  const gi = toColorCubeIndex(g)
+  const bi = toColorCubeIndex(b)
+
+  return 16 + 36 * ri + 6 * gi + bi
+}
+
+/**
+ * Parse hex color to RGB values.
+ *
+ * Handles edge cases:
+ * - Empty string returns black (0, 0, 0)
+ * - Invalid hex returns black (0, 0, 0)
+ * - Supports with/without # prefix
+ * - Supports 3-character shorthand (#fff)
+ */
+export function hexToRgb(hex: string): { r: number; g: number; b: number } {
+  // Handle empty or null input
+  if (!hex || typeof hex !== 'string') {
+    return { r: 0, g: 0, b: 0 }
+  }
+
+  // Remove # prefix if present
+  hex = hex.replace(/^#/, '')
+
+  // Handle empty after removing #
+  if (hex.length === 0) {
+    return { r: 0, g: 0, b: 0 }
+  }
+
+  // Handle shorthand hex (e.g., #fff -> #ffffff)
+  if (hex.length === 3) {
+    hex = hex
+      .split('')
+      .map((c) => c + c)
+      .join('')
+  }
+
+  // Validate hex string
+  if (!/^[0-9a-fA-F]{6}$/.test(hex)) {
+    return { r: 0, g: 0, b: 0 }
+  }
+
+  const num = parseInt(hex, 16)
+  return {
+    r: (num >> 16) & 255,
+    g: (num >> 8) & 255,
+    b: num & 255,
+  }
+}
+
+// ============================================================================
+// Public API
+// ============================================================================
+
+/**
+ * Options for RGB to ANSI conversion.
+ */
+export interface RgbToAnsiOptions {
+  /** If true, generates background color code; otherwise foreground */
+  background?: boolean
+}
+
+/**
+ * Converts RGB color values to an ANSI 256 escape sequence.
+ *
+ * @param r - Red component (0-255)
+ * @param g - Green component (0-255)
+ * @param b - Blue component (0-255)
+ * @param opts - Optional settings for background/foreground
+ * @returns ANSI escape sequence string
+ *
+ * @example
+ * ```tsx
+ * // Coral foreground color
+ * console.log(`${rgbToAnsi(255, 127, 80)}Coral text${ANSI.reset}`)
+ *
+ * // Blue background
+ * console.log(`${rgbToAnsi(0, 0, 255, { background: true })}Blue bg${ANSI.reset}`)
+ * ```
+ */
+export function rgbToAnsi(
+  r: number,
+  g: number,
+  b: number,
+  opts?: RgbToAnsiOptions
+): string {
+  const code = rgbToAnsi256(r, g, b)
+  const prefix = opts?.background ? '48' : '38'
+  return `\x1b[${prefix};5;${code}m`
+}
+
+/**
+ * Converts a hex color string to an ANSI 256 escape sequence.
+ *
+ * Supports both 3-character (#RGB) and 6-character (#RRGGBB) hex formats.
+ * The '#' prefix is optional.
+ *
+ * @param hex - Hex color string (e.g., '#ff7f50', 'ff7f50', '#f00')
+ * @param opts - Optional settings for background/foreground
+ * @returns ANSI escape sequence string
+ *
+ * @example
+ * ```tsx
+ * // Tomato red foreground
+ * console.log(`${hexToAnsi('#ff6347')}Tomato${ANSI.reset}`)
+ *
+ * // Short-form hex with background
+ * console.log(`${hexToAnsi('#f00', { background: true })}Red bg${ANSI.reset}`)
+ * ```
+ */
+export function hexToAnsi(hex: string, opts?: RgbToAnsiOptions): string {
+  const { r, g, b } = hexToRgb(hex)
+  return rgbToAnsi(r, g, b, opts)
+}
+
+/**
+ * Generate ANSI 256-color foreground escape code.
+ *
+ * @param n - ANSI 256 color code (0-255)
+ * @returns ANSI escape sequence string
+ * @throws {ZodError} If n is not a valid ANSI 256 code (0-255)
+ */
+export function ansi256(n: number): string {
+  Ansi256CodeSchema.parse(n)
+  return `\x1b[38;5;${n}m`
+}
+
+/**
+ * Generate ANSI 256-color background escape code.
+ *
+ * @param n - ANSI 256 color code (0-255)
+ * @returns ANSI escape sequence string
+ * @throws {ZodError} If n is not a valid ANSI 256 code (0-255)
+ */
+export function ansi256Bg(n: number): string {
+  Ansi256CodeSchema.parse(n)
+  return `\x1b[48;5;${n}m`
+}
+
+/**
+ * Generate true color (24-bit) foreground escape code.
+ *
+ * @param r - Red component (0-255)
+ * @param g - Green component (0-255)
+ * @param b - Blue component (0-255)
+ * @returns ANSI escape sequence string
+ * @throws {ZodError} If any component is not in range 0-255
+ */
+export function rgb(r: number, g: number, b: number): string {
+  RgbComponentSchema.parse(r)
+  RgbComponentSchema.parse(g)
+  RgbComponentSchema.parse(b)
+  return `\x1b[38;2;${r};${g};${b}m`
+}
+
+/**
+ * Generate true color (24-bit) background escape code.
+ *
+ * @param r - Red component (0-255)
+ * @param g - Green component (0-255)
+ * @param b - Blue component (0-255)
+ * @returns ANSI escape sequence string
+ * @throws {ZodError} If any component is not in range 0-255
+ */
+export function rgbBg(r: number, g: number, b: number): string {
+  RgbComponentSchema.parse(r)
+  RgbComponentSchema.parse(g)
+  RgbComponentSchema.parse(b)
+  return `\x1b[48;2;${r};${g};${b}m`
+}
+
+/**
+ * Generate true color foreground from hex color.
+ *
+ * @param color - Hex color string (#RGB, RGB, #RRGGBB, or RRGGBB)
+ * @returns ANSI escape sequence string
+ * @throws {ZodError} If color is not a valid hex color format
+ */
+export function hex(color: string): string {
+  HexColorSchema.parse(color)
+  const { r, g, b } = hexToRgb(color)
+  return `\x1b[38;2;${r};${g};${b}m`
+}
+
+/**
+ * Generate true color background from hex color.
+ *
+ * @param color - Hex color string (#RGB, RGB, #RRGGBB, or RRGGBB)
+ * @returns ANSI escape sequence string
+ * @throws {ZodError} If color is not a valid hex color format
+ */
+export function hexBg(color: string): string {
+  HexColorSchema.parse(color)
+  const { r, g, b } = hexToRgb(color)
+  return `\x1b[48;2;${r};${g};${b}m`
+}
+
+// Export the internal helper for use by other modules
+export { rgbToAnsi256 }

package/src/theme/color-support.ts

@@ -0,0 +1,321 @@
+/**
+ * Color Support Detection and Degradation
+ *
+ * Utilities for detecting terminal color capabilities and
+ * gracefully degrading colors for limited terminals.
+ *
+ * @module
+ */
+
+import { rgbToAnsi256 } from './color-convert'
+
+// ============================================================================
+// Type Definitions
+// ============================================================================
+
+/**
+ * Level of color support in the terminal.
+ *
+ * - `'none'` - No color support (monochrome)
+ * - `'16'` - Basic 16 ANSI colors
+ * - `'256'` - Extended 256 color palette
+ * - `'truecolor'` - Full 24-bit RGB color support
+ */
+export type ColorSupport = 'none' | '16' | '256' | 'truecolor'
+
+// ============================================================================
+// Color Support Detection
+// ============================================================================
+
+/**
+ * Detects the terminal's color support level.
+ *
+ * Checks environment variables in this order:
+ * 1. `NO_COLOR` - Forces no color support
+ * 2. `FORCE_COLOR` - Forces a specific color level (0-3)
+ * 3. `COLORTERM` - Checks for truecolor support
+ * 4. `TERM` - Checks terminal type for color hints
+ *
+ * @returns The detected color support level
+ *
+ * @example
+ * ```tsx
+ * const support = detectColorSupport()
+ * if (support === 'truecolor') {
+ *   // Use full RGB colors
+ * } else if (support === '256') {
+ *   // Use 256 color palette
+ * }
+ * ```
+ */
+export function detectColorSupport(): ColorSupport {
+  // NO_COLOR takes precedence
+  if (process.env.NO_COLOR) {
+    return 'none'
+  }
+
+  // FORCE_COLOR can override
+  if (process.env.FORCE_COLOR) {
+    const level = parseInt(process.env.FORCE_COLOR, 10)
+    if (level === 0) return 'none'
+    if (level === 1) return '16'
+    if (level === 2) return '256'
+    if (level >= 3) return 'truecolor'
+  }
+
+  // Check COLORTERM for truecolor
+  const colorTerm = process.env.COLORTERM
+  if (colorTerm === 'truecolor' || colorTerm === '24bit') {
+    return 'truecolor'
+  }
+
+  // Check TERM for color support
+  const term = process.env.TERM || ''
+
+  if (term === 'dumb') {
+    return 'none'
+  }
+
+  if (term.includes('256color')) {
+    return '256'
+  }
+
+  if (term.includes('color') || term.includes('xterm') || term.includes('vt100')) {
+    return '16'
+  }
+
+  // Default to 256 for most modern terminals
+  return '256'
+}
+
+// ============================================================================
+// Color Degradation
+// ============================================================================
+
+/**
+ * Map ANSI 256 color to basic 16 color
+ */
+function ansi256To16(code: number): number {
+  // Standard colors 0-7 map to 30-37
+  if (code < 8) {
+    return 30 + code
+  }
+
+  // Bright colors 8-15 map to 90-97
+  if (code < 16) {
+    return 90 + (code - 8)
+  }
+
+  // Color cube (16-231) and grayscale (232-255)
+  // Need to find the closest basic color
+
+  let r: number, g: number, b: number
+
+  if (code >= 232) {
+    // Grayscale
+    const gray = (code - 232) * 10 + 8
+    r = g = b = gray
+  } else {
+    // Color cube
+    const cubeIndex = code - 16
+    r = Math.floor(cubeIndex / 36) * 51
+    g = Math.floor((cubeIndex % 36) / 6) * 51
+    b = (cubeIndex % 6) * 51
+  }
+
+  // Find the closest basic color
+  // Basic colors: black, red, green, yellow, blue, magenta, cyan, white
+  const basicColors = [
+    { r: 0, g: 0, b: 0, code: 30 }, // black
+    { r: 170, g: 0, b: 0, code: 31 }, // red
+    { r: 0, g: 170, b: 0, code: 32 }, // green
+    { r: 170, g: 170, b: 0, code: 33 }, // yellow
+    { r: 0, g: 0, b: 170, code: 34 }, // blue
+    { r: 170, g: 0, b: 170, code: 35 }, // magenta
+    { r: 0, g: 170, b: 170, code: 36 }, // cyan
+    { r: 170, g: 170, b: 170, code: 37 }, // white
+    { r: 85, g: 85, b: 85, code: 90 }, // bright black
+    { r: 255, g: 85, b: 85, code: 91 }, // bright red
+    { r: 85, g: 255, b: 85, code: 92 }, // bright green
+    { r: 255, g: 255, b: 85, code: 93 }, // bright yellow
+    { r: 85, g: 85, b: 255, code: 94 }, // bright blue
+    { r: 255, g: 85, b: 255, code: 95 }, // bright magenta
+    { r: 85, g: 255, b: 255, code: 96 }, // bright cyan
+    { r: 255, g: 255, b: 255, code: 97 }, // bright white
+  ]
+
+  let minDist = Infinity
+  let closestCode = 37 // default to white
+
+  for (const bc of basicColors) {
+    const dist = Math.sqrt(
+      Math.pow(r - bc.r, 2) + Math.pow(g - bc.g, 2) + Math.pow(b - bc.b, 2)
+    )
+    if (dist < minDist) {
+      minDist = dist
+      closestCode = bc.code
+    }
+  }
+
+  return closestCode
+}
+
+/**
+ * Parse ANSI escape code to extract type and color code
+ */
+function parseAnsiCode(ansi: string): {
+  type: 'fg' | 'bg' | 'style'
+  format: '16' | '256' | 'truecolor'
+  code?: number
+  rgb?: { r: number; g: number; b: number }
+} | null {
+  // Match ANSI 256 foreground: \x1b[38;5;Nm
+  const fg256Match = ansi.match(/\x1b\[38;5;(\d+)m/)
+  if (fg256Match) {
+    return { type: 'fg', format: '256', code: parseInt(fg256Match[1], 10) }
+  }
+
+  // Match ANSI 256 background: \x1b[48;5;Nm
+  const bg256Match = ansi.match(/\x1b\[48;5;(\d+)m/)
+  if (bg256Match) {
+    return { type: 'bg', format: '256', code: parseInt(bg256Match[1], 10) }
+  }
+
+  // Match truecolor foreground: \x1b[38;2;R;G;Bm
+  const fgTrueMatch = ansi.match(/\x1b\[38;2;(\d+);(\d+);(\d+)m/)
+  if (fgTrueMatch) {
+    return {
+      type: 'fg',
+      format: 'truecolor',
+      rgb: {
+        r: parseInt(fgTrueMatch[1], 10),
+        g: parseInt(fgTrueMatch[2], 10),
+        b: parseInt(fgTrueMatch[3], 10),
+      },
+    }
+  }
+
+  // Match truecolor background: \x1b[48;2;R;G;Bm
+  const bgTrueMatch = ansi.match(/\x1b\[48;2;(\d+);(\d+);(\d+)m/)
+  if (bgTrueMatch) {
+    return {
+      type: 'bg',
+      format: 'truecolor',
+      rgb: {
+        r: parseInt(bgTrueMatch[1], 10),
+        g: parseInt(bgTrueMatch[2], 10),
+        b: parseInt(bgTrueMatch[3], 10),
+      },
+    }
+  }
+
+  // Match basic 16 color codes
+  const basicMatch = ansi.match(/\x1b\[(\d+)m/)
+  if (basicMatch) {
+    const code = parseInt(basicMatch[1], 10)
+    if (code >= 30 && code <= 37) {
+      return { type: 'fg', format: '16', code }
+    }
+    if (code >= 90 && code <= 97) {
+      return { type: 'fg', format: '16', code }
+    }
+    if (code >= 40 && code <= 47) {
+      return { type: 'bg', format: '16', code }
+    }
+    if (code >= 100 && code <= 107) {
+      return { type: 'bg', format: '16', code }
+    }
+    // Style code
+    return { type: 'style', format: '16', code }
+  }
+
+  return null
+}
+
+/**
+ * Degrades an ANSI color to work with limited terminal color support.
+ *
+ * Automatically converts colors down to simpler formats:
+ * - Truecolor to 256 colors
+ * - 256 colors to 16 basic colors
+ * - Any color to nothing if support is 'none'
+ *
+ * @param ansi - Original ANSI escape sequence
+ * @param support - Target color support level
+ * @returns Degraded ANSI escape sequence, or empty string for 'none'
+ *
+ * @example
+ * ```tsx
+ * const trueColorBlue = '\x1b[38;2;100;150;200m'
+ * const support = detectColorSupport()
+ *
+ * // Automatically degrade for the current terminal
+ * const blue = degradeColor(trueColorBlue, support)
+ * ```
+ */
+export function degradeColor(ansi: string, support: ColorSupport): string {
+  if (support === 'none') {
+    return ''
+  }
+
+  if (support === 'truecolor') {
+    // Truecolor supports everything
+    return ansi
+  }
+
+  const parsed = parseAnsiCode(ansi)
+  if (!parsed) {
+    return ansi
+  }
+
+  if (support === '256') {
+    // Convert truecolor to 256
+    if (parsed.format === 'truecolor' && parsed.rgb) {
+      const code = rgbToAnsi256(parsed.rgb.r, parsed.rgb.g, parsed.rgb.b)
+      const prefix = parsed.type === 'bg' ? '48' : '38'
+      return `\x1b[${prefix};5;${code}m`
+    }
+    return ansi
+  }
+
+  if (support === '16') {
+    // Convert 256 or truecolor to 16
+    if (parsed.format === '16') {
+      return ansi
+    }
+
+    let code256: number
+    if (parsed.format === 'truecolor' && parsed.rgb) {
+      code256 = rgbToAnsi256(parsed.rgb.r, parsed.rgb.g, parsed.rgb.b)
+    } else if (parsed.code !== undefined) {
+      code256 = parsed.code
+    } else {
+      return ansi
+    }
+
+    const code16 = ansi256To16(code256)
+    return `\x1b[${code16}m`
+  }
+
+  return ansi
+}
+
+/**
+ * Adapts a color based on terminal support level.
+ *
+ * Alias for {@link degradeColor} - use this when the intent is to
+ * "adapt" colors for the current terminal rather than "degrade" them.
+ *
+ * @param color - ANSI color escape sequence
+ * @param level - Target color support level
+ * @returns Adapted color escape sequence
+ *
+ * @example
+ * ```tsx
+ * const support = detectColorSupport()
+ * const color = adaptColor(theme.primary, support)
+ * ```
+ */
+export function adaptColor(color: string, level: ColorSupport): string {
+  return degradeColor(color, level)
+}

package/src/theme/index.ts

@@ -0,0 +1,134 @@
+/**
+ * @mdxui/terminal/theme
+ *
+ * Terminal theming system for mapping web design tokens to ANSI colors.
+ *
+ * This module provides:
+ * - ANSI escape code constants for styling terminal output
+ * - Tailwind CSS to ANSI color conversion
+ * - Theme creation and composition utilities
+ * - Color support detection and degradation
+ * - Box drawing character sets for UI borders
+ *
+ * @example
+ * ```tsx
+ * import { ANSI, styled, createTheme } from '@mdxui/terminal'
+ *
+ * // Apply styles to text
+ * console.log(styled('Hello', ANSI.bold, ANSI.cyan))
+ *
+ * // Create a custom theme
+ * const theme = createTheme({
+ *   primary: ANSI.brightGreen,
+ *   error: ANSI.brightRed,
+ * })
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+// ANSI escape code constants
+export { ANSI } from './ansi-codes'
+
+// Color conversion utilities
+export {
+  hexToRgb,
+  rgbToAnsi,
+  hexToAnsi,
+  ansi256,
+  ansi256Bg,
+  rgb,
+  rgbBg,
+  hex,
+  hexBg,
+  type RgbToAnsiOptions,
+} from './color-convert'
+
+// Tailwind to ANSI mapping
+export {
+  TAILWIND_COLORS,
+  tailwindToAnsi,
+  tailwindToTerminal,
+} from './tailwind-map'
+
+// Theme system
+export {
+  createTerminalTheme,
+  getThemeColor,
+  cssVarToAnsi,
+  applyThemeStyles,
+  defaultTheme,
+  colors,
+  themeTokens,
+  darkTheme,
+  lightTheme,
+  highContrastTheme,
+  themePresets,
+  createTheme,
+  extendTheme,
+  composeThemes,
+  createThemeVariant,
+  detectColorScheme,
+  type TerminalThemeColors,
+  type TerminalTheme,
+  type LegacyTerminalTheme,
+  type LegacyTerminalThemeWithExtras,
+  type CreateTerminalThemeOptions,
+} from './theme-system'
+
+// Text styling utilities
+export {
+  fg,
+  bg,
+  bold,
+  dim,
+  italic,
+  underline,
+  strikethrough,
+  style,
+  styled,
+} from './text-styles'
+
+// Color support detection and degradation
+export {
+  detectColorSupport,
+  degradeColor,
+  adaptColor,
+  type ColorSupport,
+} from './color-support'
+
+// ANSI stripping utilities
+export {
+  stripAnsi,
+  visibleLength,
+} from './strip-ansi'
+
+// Box drawing characters
+export {
+  boxChars,
+  drawBox,
+  type BoxStyle,
+} from './box-drawing'
+
+// Zod schemas for runtime validation
+export {
+  HexColorSchema,
+  RgbComponentSchema,
+  RgbColorSchema,
+  Ansi256CodeSchema,
+  AnsiEscapeSchema,
+  ThemeModeSchema,
+  TerminalThemeColorsSchema,
+  CreateTerminalThemeOptionsSchema,
+  LegacyTerminalThemeSchema,
+  LegacyTerminalThemeWithExtrasSchema,
+  CreateThemeInputSchema,
+  RgbToAnsiOptionsSchema,
+  ColorSupportSchema,
+  type HexColor,
+  type RgbColor,
+  type Ansi256Code,
+  type ThemeMode,
+  type CreateTerminalThemeOptionsInput,
+  type CreateThemeInput,
+} from '../schemas'