@silvery/term 0.3.0

package/src/ansi/types.ts

@@ -0,0 +1,202 @@
+/**
+ * Type definitions for @silvery/ansi
+ */
+
+import type { TerminalCaps } from "./detection"
+
+// =============================================================================
+// Color Types
+// =============================================================================
+
+/**
+ * Color level supported by terminal.
+ * - 'basic': 16 colors (SGR 30-37, 40-47)
+ * - '256': 256 colors (SGR 38;5;n)
+ * - 'truecolor': 16M colors (SGR 38;2;r;g;b)
+ */
+export type ColorLevel = "basic" | "256" | "truecolor"
+
+/**
+ * RGB color tuple for underline color.
+ * Each component is 0-255.
+ */
+export type RGB = [r: number, g: number, b: number]
+
+/**
+ * Standard ANSI color names (the 16 base colors).
+ * These map to SGR 30-37 (foreground) and 40-47 (background),
+ * plus their bright variants (SGR 90-97, 100-107).
+ */
+export type AnsiColorName =
+  | "black"
+  | "red"
+  | "green"
+  | "yellow"
+  | "blue"
+  | "magenta"
+  | "cyan"
+  | "white"
+  | "gray"
+  | "grey"
+  | "blackBright"
+  | "redBright"
+  | "greenBright"
+  | "yellowBright"
+  | "blueBright"
+  | "magentaBright"
+  | "cyanBright"
+  | "whiteBright"
+
+/**
+ * Hex color string pattern.
+ * Accepts 3-digit (#rgb) and 6-digit (#rrggbb) hex colors.
+ */
+type HexColor = `#${string}`
+
+/**
+ * RGB function-style color string pattern.
+ * Format: rgb(r,g,b) where r, g, b are 0-255.
+ */
+type RgbColor = `rgb(${string})`
+
+/**
+ * Theme token color string pattern.
+ * Format: $name — resolved against the active theme at render time.
+ * Examples: $primary, $surface, $error, $bg, $fg, $muted
+ */
+type ThemeToken = `$${string}`
+
+/**
+ * Type-safe color value accepted by ansi APIs.
+ *
+ * Accepts:
+ * - ANSI color names: `"red"`, `"cyan"`, `"whiteBright"`, etc.
+ * - Hex colors: `"#ff0000"`, `"#f00"`
+ * - RGB function: `"rgb(255, 0, 0)"`
+ * - Theme tokens: `"$primary"`, `"$error"`, `"$surface"`
+ * - Any other string (for forward compatibility with custom color schemes)
+ *
+ * The union of known literals provides autocompletion in editors while
+ * the `string & {}` fallback allows arbitrary color strings.
+ */
+export type Color = AnsiColorName | HexColor | RgbColor | ThemeToken | (string & {})
+
+// =============================================================================
+// Underline Types
+// =============================================================================
+
+/**
+ * Extended underline styles supported by modern terminals.
+ *
+ * - `single`: Standard underline (SGR 4:1)
+ * - `double`: Two parallel lines (SGR 4:2)
+ * - `curly`: Wavy/squiggly line (SGR 4:3) - commonly used for spell check
+ * - `dotted`: Dotted line (SGR 4:4)
+ * - `dashed`: Dashed line (SGR 4:5)
+ */
+export type UnderlineStyle = "single" | "double" | "curly" | "dotted" | "dashed"
+
+// =============================================================================
+// Style Types
+// =============================================================================
+
+/**
+ * Style options for term.style() method.
+ */
+export interface StyleOptions {
+  color?: Color
+  bgColor?: Color
+  bold?: boolean
+  dim?: boolean
+  italic?: boolean
+  underline?: boolean
+  strikethrough?: boolean
+  inverse?: boolean
+}
+
+// =============================================================================
+// Console Types
+// =============================================================================
+
+/**
+ * Console method names that can be intercepted.
+ */
+export type ConsoleMethod = "log" | "info" | "warn" | "error" | "debug"
+
+/**
+ * Entry captured from console.
+ */
+export interface ConsoleEntry {
+  method: ConsoleMethod
+  args: unknown[]
+  stream: "stdout" | "stderr"
+}
+
+// =============================================================================
+// Term Types
+// =============================================================================
+
+/**
+ * Options for createTerm().
+ */
+export interface CreateTermOptions {
+  stdout?: NodeJS.WriteStream
+  stdin?: NodeJS.ReadStream
+
+  // Override auto-detection (for testing or forcing)
+  color?: ColorLevel | null // override hasColor()
+  unicode?: boolean // override hasUnicode()
+  cursor?: boolean // override hasCursor()
+
+  // Terminal capabilities override
+  caps?: Partial<TerminalCaps>
+}
+
+// Re-export TerminalCaps from detection for convenience
+export type { TerminalCaps } from "./detection"
+
+// =============================================================================
+// Terminal Emulator Types (duck-types for termless integration)
+// =============================================================================
+
+/**
+ * A screen region — duck-type matching termless RegionView.
+ * Provides text content and line access for assertions.
+ */
+export interface TermScreen {
+  getText(): string
+  getLines(): string[]
+  containsText?(text: string): boolean
+}
+
+/**
+ * A terminal emulator — duck-type matching termless Terminal.
+ * Accepts ANSI output, provides screen/scrollback for inspection.
+ */
+export interface TermEmulator {
+  readonly cols: number
+  readonly rows: number
+  readonly screen: TermScreen
+  readonly scrollback: TermScreen
+  feed(data: Uint8Array | string): void
+  resize(cols: number, rows: number): void
+  close(): Promise<void>
+}
+
+/**
+ * A terminal emulator backend — duck-type matching termless TerminalBackend.
+ * Raw backend that needs initialization. Pass to createTerm(backend, { cols, rows }).
+ *
+ * @example
+ * ```ts
+ * import { createXtermBackend } from "@termless/xtermjs"
+ * using term = createTerm(createXtermBackend(), { cols: 80, rows: 24 })
+ * ```
+ */
+export interface TermEmulatorBackend {
+  readonly name: string
+  init(opts: { cols: number; rows: number; scrollbackLimit?: number }): void
+  destroy(): void
+  feed(data: Uint8Array): void
+  resize(cols: number, rows: number): void
+}

package/src/ansi/underline.ts

@@ -0,0 +1,156 @@
+/**
+ * Extended underline style functions.
+ *
+ * Provides curly, dotted, dashed, and double underline styles
+ * with graceful fallback to standard underline on unsupported terminals.
+ */
+
+import chalk from "chalk"
+import {
+  UNDERLINE_CODES,
+  UNDERLINE_COLOR_RESET,
+  UNDERLINE_STANDARD,
+  UNDERLINE_RESET_STANDARD,
+  buildUnderlineColorCode,
+} from "./constants"
+import { detectExtendedUnderline } from "./detection"
+import type { UnderlineStyle, RGB } from "./types"
+
+// =============================================================================
+// Extended Underline Functions
+// =============================================================================
+
+/**
+ * Apply an extended underline style to text.
+ * Falls back to regular underline on unsupported terminals.
+ *
+ * @param text - Text to underline
+ * @param style - Underline style (default: "single")
+ * @returns Styled text with ANSI codes
+ */
+export function underline(text: string, style: UnderlineStyle = "single"): string {
+  if (!detectExtendedUnderline() || style === "single") {
+    return chalk.underline(text)
+  }
+
+  return `${UNDERLINE_CODES[style]}${text}${UNDERLINE_CODES.reset}`
+}
+
+/**
+ * Apply curly/wavy underline to text.
+ * Commonly used for spell check errors in IDEs.
+ * Falls back to regular underline on unsupported terminals.
+ *
+ * @param text - Text to underline
+ * @returns Styled text with curly underline
+ *
+ * @example
+ * ```ts
+ * import { curlyUnderline, chalk } from '@silvery/ansi';
+ *
+ * console.log(curlyUnderline('misspelled'));
+ * console.log(chalk.red(curlyUnderline('error')));
+ * ```
+ */
+export function curlyUnderline(text: string): string {
+  return underline(text, "curly")
+}
+
+/**
+ * Apply dotted underline to text.
+ * Falls back to regular underline on unsupported terminals.
+ *
+ * @param text - Text to underline
+ * @returns Styled text with dotted underline
+ */
+export function dottedUnderline(text: string): string {
+  return underline(text, "dotted")
+}
+
+/**
+ * Apply dashed underline to text.
+ * Falls back to regular underline on unsupported terminals.
+ *
+ * @param text - Text to underline
+ * @returns Styled text with dashed underline
+ */
+export function dashedUnderline(text: string): string {
+  return underline(text, "dashed")
+}
+
+/**
+ * Apply double underline to text.
+ * Falls back to regular underline on unsupported terminals.
+ *
+ * @param text - Text to underline
+ * @returns Styled text with double underline
+ */
+export function doubleUnderline(text: string): string {
+  return underline(text, "double")
+}
+
+// =============================================================================
+// Underline Color Functions
+// =============================================================================
+
+/**
+ * Set underline color independently of text color.
+ * On unsupported terminals, the color is ignored but underline still applies.
+ *
+ * @param r - Red component (0-255)
+ * @param g - Green component (0-255)
+ * @param b - Blue component (0-255)
+ * @param text - Text to style
+ * @returns Styled text with colored underline
+ *
+ * @example
+ * ```ts
+ * import { underlineColor, chalk } from '@silvery/ansi';
+ *
+ * // Red underline (text color unchanged)
+ * console.log(underlineColor(255, 0, 0, 'warning'));
+ *
+ * // Red underline with blue text
+ * console.log(chalk.blue(underlineColor(255, 0, 0, 'blue text, red underline')));
+ * ```
+ */
+export function underlineColor(r: number, g: number, b: number, text: string): string {
+  if (!detectExtendedUnderline()) {
+    // Fallback: just apply regular underline, ignore color
+    return chalk.underline(text)
+  }
+
+  const colorCode = buildUnderlineColorCode(r, g, b)
+  return `${UNDERLINE_STANDARD}${colorCode}${text}${UNDERLINE_COLOR_RESET}${UNDERLINE_RESET_STANDARD}`
+}
+
+/**
+ * Combine underline style with underline color.
+ *
+ * @param style - Underline style ('curly', 'dotted', 'dashed', 'double', 'single')
+ * @param rgb - Color as [r, g, b] tuple (0-255 each)
+ * @param text - Text to style
+ * @returns Styled text with colored underline in specified style
+ *
+ * @example
+ * ```ts
+ * import { styledUnderline, chalk } from '@silvery/ansi';
+ *
+ * // Red curly underline (spell-check style)
+ * console.log(styledUnderline('curly', [255, 0, 0], 'misspelled'));
+ *
+ * // Orange dashed underline with yellow text
+ * console.log(chalk.yellow(styledUnderline('dashed', [255, 165, 0], 'warning')));
+ * ```
+ */
+export function styledUnderline(style: UnderlineStyle, rgb: RGB, text: string): string {
+  if (!detectExtendedUnderline()) {
+    return chalk.underline(text)
+  }
+
+  const [r, g, b] = rgb
+  const styleCode = UNDERLINE_CODES[style]
+  const colorCode = buildUnderlineColorCode(r, g, b)
+
+  return `${styleCode}${colorCode}${text}${UNDERLINE_CODES.reset}${UNDERLINE_COLOR_RESET}`
+}

package/src/ansi/utils.ts

@@ -0,0 +1,65 @@
+/**
+ * ANSI string utilities.
+ *
+ * This module can be imported separately via `@silvery/ansi/utils`
+ * for projects that only need ANSI stripping without chalk.
+ */
+
+import stringWidth from "string-width"
+
+// =============================================================================
+// ANSI Regex Pattern
+// =============================================================================
+
+/**
+ * ANSI escape code pattern for stripping.
+ *
+ * Matches:
+ * - ESC CSI SGR sequences: \x1b[31m, \x1b[4:3m, \x1b[38:2::255:100:0m
+ * - C1 CSI SGR sequences: \x9b31m, \x9b4:3m
+ * - ESC OSC 8 hyperlinks (BEL-terminated): \x1b]8;;<url>\x07
+ * - ESC OSC 8 hyperlinks (ST-terminated): \x1b]8;;<url>\x1b\\
+ * - C1 OSC 8 hyperlinks (BEL-terminated): \x9d8;;<url>\x07
+ * - C1 OSC 8 hyperlinks (ST-terminated): \x9d8;;<url>\x1b\\
+ * - C1 OSC 8 hyperlinks (C1 ST-terminated): \x9d8;;<url>\x9c
+ */
+export const ANSI_REGEX =
+  /\x1b\[[0-9;:]*m|\x9b[0-9;:]*m|\x1b\]8;;[^\x07\x1b]*(?:\x07|\x1b\\)|\x9d8;;[^\x07\x1b\x9c]*(?:\x07|\x1b\\|\x9c)/g
+
+// =============================================================================
+// String Utilities
+// =============================================================================
+
+/**
+ * Strip all ANSI escape codes from a string.
+ *
+ * @param text - String potentially containing ANSI codes
+ * @returns Clean string with all ANSI codes removed
+ *
+ * @example
+ * ```ts
+ * stripAnsi('\x1b[31mred\x1b[0m') // 'red'
+ * stripAnsi('\x1b[4:3mwavy\x1b[4:0m') // 'wavy'
+ * ```
+ */
+export function stripAnsi(text: string): string {
+  return text.replace(ANSI_REGEX, "")
+}
+
+/**
+ * Get the display width of a string, excluding ANSI escape codes.
+ * Correctly handles CJK characters, emoji, and other wide characters.
+ *
+ * @param text - String potentially containing ANSI codes
+ * @returns Number of terminal columns the text will occupy
+ *
+ * @example
+ * ```ts
+ * displayLength('\x1b[31mhello\x1b[0m') // 5
+ * displayLength('hello') // 5
+ * displayLength('한글') // 4 (2 chars × 2 cells each)
+ * ```
+ */
+export function displayLength(text: string): number {
+  return stringWidth(stripAnsi(text))
+}