@mdxui/terminal 2.0.0

package/src/theme/text-styles.ts

@@ -0,0 +1,206 @@
+/**
+ * Text Styling Utilities
+ *
+ * Functions for applying ANSI styles to text with automatic reset.
+ * Includes semantic color helpers and compound style application.
+ *
+ * @module
+ */
+
+import { ANSI } from './ansi-codes'
+import { colors, defaultTheme, type LegacyTerminalTheme } from './theme-system'
+
+// ============================================================================
+// Semantic Color Styling
+// ============================================================================
+
+/**
+ * Applies a foreground color to text with automatic reset.
+ *
+ * Accepts either a semantic color name ('primary', 'error', etc.) or
+ * a raw ANSI escape sequence.
+ *
+ * @param colorName - Semantic color name or ANSI escape sequence
+ * @param text - The text to colorize
+ * @returns Colored text with ANSI codes
+ *
+ * @example
+ * ```tsx
+ * console.log(fg('error', 'Something went wrong'))
+ * console.log(fg('success', 'Operation completed'))
+ * console.log(fg(ANSI.brightCyan, 'Custom color'))
+ * ```
+ */
+export function fg(colorName: keyof typeof colors | string, text: string): string {
+  const colorCode = colors[colorName as keyof typeof colors] || defaultTheme[colorName as keyof LegacyTerminalTheme] || colorName
+  return `${colorCode}${text}${ANSI.reset}`
+}
+
+/**
+ * Applies a background color to text with automatic reset.
+ *
+ * Accepts either a semantic color name ('primary', 'error', etc.) or
+ * a raw ANSI escape sequence.
+ *
+ * @param colorName - Semantic color name or ANSI escape sequence
+ * @param text - The text to highlight
+ * @returns Highlighted text with ANSI codes
+ *
+ * @example
+ * ```tsx
+ * console.log(bg('error', 'ALERT'))
+ * console.log(bg('success', ' OK '))
+ * ```
+ */
+export function bg(colorName: keyof typeof colors | string, text: string): string {
+  const bgMap: Record<string, string> = {
+    primary: ANSI.bgCyan,
+    secondary: ANSI.bgBlue,
+    accent: ANSI.bgMagenta,
+    muted: ANSI.bgBlack,
+    success: ANSI.bgGreen,
+    warning: ANSI.bgYellow,
+    error: ANSI.bgRed,
+    info: ANSI.bgBlue,
+  }
+  const colorCode = bgMap[colorName] || colorName
+  return `${colorCode}${text}${ANSI.reset}`
+}
+
+// ============================================================================
+// Text Style Modifiers
+// ============================================================================
+
+/**
+ * Applies bold styling to text.
+ *
+ * @param text - The text to make bold
+ * @returns Bold text with ANSI codes
+ */
+export function bold(text: string): string {
+  return `${ANSI.bold}${text}${ANSI.reset}`
+}
+
+/**
+ * Applies dim/faint styling to text.
+ *
+ * @param text - The text to dim
+ * @returns Dimmed text with ANSI codes
+ */
+export function dim(text: string): string {
+  return `${ANSI.dim}${text}${ANSI.reset}`
+}
+
+/**
+ * Applies italic styling to text.
+ *
+ * Note: Not all terminals support italic text.
+ *
+ * @param text - The text to italicize
+ * @returns Italic text with ANSI codes
+ */
+export function italic(text: string): string {
+  return `${ANSI.italic}${text}${ANSI.reset}`
+}
+
+/**
+ * Applies underline styling to text.
+ *
+ * @param text - The text to underline
+ * @returns Underlined text with ANSI codes
+ */
+export function underline(text: string): string {
+  return `${ANSI.underline}${text}${ANSI.reset}`
+}
+
+/**
+ * Applies strikethrough styling to text.
+ *
+ * Note: Not all terminals support strikethrough text.
+ *
+ * @param text - The text to strike through
+ * @returns Strikethrough text with ANSI codes
+ */
+export function strikethrough(text: string): string {
+  return `${ANSI.strikethrough}${text}${ANSI.reset}`
+}
+
+// ============================================================================
+// Compound Styling
+// ============================================================================
+
+/**
+ * Applies multiple style modifiers to text.
+ *
+ * Accepts an array of modifier names (e.g., 'bold', 'red', 'underline')
+ * and applies all of them to the text.
+ *
+ * @param text - The text to style
+ * @param modifiers - Array of modifier names
+ * @returns Styled text with ANSI codes
+ *
+ * @example
+ * ```tsx
+ * console.log(style('Important', ['bold', 'red', 'underline']))
+ * console.log(style('Info', ['cyan', 'italic']))
+ * ```
+ */
+export function style(text: string, modifiers: string[]): string {
+  const modifierMap: Record<string, string> = {
+    bold: ANSI.bold,
+    dim: ANSI.dim,
+    italic: ANSI.italic,
+    underline: ANSI.underline,
+    strikethrough: ANSI.strikethrough,
+    black: ANSI.black,
+    red: ANSI.red,
+    green: ANSI.green,
+    yellow: ANSI.yellow,
+    blue: ANSI.blue,
+    magenta: ANSI.magenta,
+    cyan: ANSI.cyan,
+    white: ANSI.white,
+    brightBlack: ANSI.brightBlack,
+    brightRed: ANSI.brightRed,
+    brightGreen: ANSI.brightGreen,
+    brightYellow: ANSI.brightYellow,
+    brightBlue: ANSI.brightBlue,
+    brightMagenta: ANSI.brightMagenta,
+    brightCyan: ANSI.brightCyan,
+    brightWhite: ANSI.brightWhite,
+  }
+
+  const codes = modifiers.map(m => modifierMap[m] || '').filter(Boolean)
+  if (codes.length === 0) return text
+
+  return `${codes.join('')}${text}${ANSI.reset}`
+}
+
+/**
+ * Wraps text with ANSI escape codes and automatically appends reset.
+ *
+ * The primary utility for applying multiple ANSI styles to text.
+ * Accepts any number of ANSI escape code strings.
+ *
+ * @param text - The text to style (returns empty string if null/undefined)
+ * @param codes - ANSI escape code strings to apply
+ * @returns Styled text with reset appended
+ *
+ * @example
+ * ```tsx
+ * // Bold cyan text
+ * console.log(styled('Hello', ANSI.bold, ANSI.cyan))
+ *
+ * // Error styling
+ * console.log(styled('Error!', ANSI.bold, ANSI.red, ANSI.bgBlack))
+ * ```
+ */
+export function styled(text: string, ...codes: string[]): string {
+  // Handle null/undefined text
+  if (text == null) return ''
+  if (codes.length === 0) return String(text)
+  // Filter out empty/null codes
+  const validCodes = codes.filter((c) => c && typeof c === 'string')
+  if (validCodes.length === 0) return String(text)
+  return `${validCodes.join('')}${text}${ANSI.reset}`
+}