@mdxui/terminal 2.0.0

package/src/theme/theme-system.ts

@@ -0,0 +1,568 @@
+/**
+ * Theme System
+ *
+ * Terminal theme creation, composition, and management utilities.
+ * Provides dark/light mode themes with semantic color tokens.
+ *
+ * All public APIs include runtime validation via Zod schemas.
+ *
+ * @module
+ */
+
+import { ANSI } from './ansi-codes'
+import {
+  CreateTerminalThemeOptionsSchema,
+  CreateThemeInputSchema,
+} from '../schemas'
+
+// ============================================================================
+// Type Definitions
+// ============================================================================
+
+/**
+ * Color tokens for a terminal theme.
+ *
+ * All values are ANSI escape sequences that can be directly concatenated
+ * with text to apply styling.
+ */
+export interface TerminalThemeColors {
+  /** Primary brand/accent color for key UI elements */
+  primary: string
+  /** Secondary color for less prominent elements */
+  secondary: string
+  /** Accent color for highlights and special elements */
+  accent: string
+  /** Muted/dimmed color for less important text */
+  muted: string
+
+  /** Success state indicator (green) */
+  success: string
+  /** Warning state indicator (yellow/orange) */
+  warning: string
+  /** Error state indicator (red) */
+  error: string
+  /** Informational state indicator (blue) */
+  info: string
+
+  /** Border/divider color */
+  border: string
+  /** Background color (usually includes background escape) */
+  background: string
+  /** Default text/foreground color */
+  foreground: string
+
+  /** Selection/highlight background */
+  selection: string
+  /** Focus indicator color */
+  focus: string
+}
+
+/**
+ * A complete terminal theme with color mode and color tokens.
+ *
+ * @example
+ * ```tsx
+ * const theme = createTerminalTheme({ mode: 'dark' })
+ * console.log(`${theme.colors.primary}Primary text${ANSI.reset}`)
+ * ```
+ */
+export interface TerminalTheme {
+  /** Color mode: 'dark' or 'light' */
+  mode: 'dark' | 'light'
+  /** Color token values */
+  colors: TerminalThemeColors
+}
+
+/**
+ * Legacy theme interface for backward compatibility.
+ *
+ * @deprecated Use {@link TerminalTheme} with {@link createTerminalTheme} instead.
+ */
+export interface LegacyTerminalTheme {
+  primary: string
+  secondary: string
+  accent: string
+  muted: string
+  success: string
+  warning: string
+  error: string
+  info: string
+  border: string
+  background: string
+  foreground: string
+  selection: string
+  focus: string
+}
+
+export interface LegacyTerminalThemeWithExtras extends LegacyTerminalTheme {
+  typography?: {
+    headingWeight: string
+    bodyWeight: string
+    codeFont: string
+  }
+  spacing?: {
+    xs: number
+    sm: number
+    md: number
+    lg: number
+    xl: number
+  }
+}
+
+/**
+ * Options for creating a terminal theme.
+ */
+export interface CreateTerminalThemeOptions {
+  /** Color mode: 'dark' (default) or 'light' */
+  mode?: 'dark' | 'light'
+  /** Custom color overrides */
+  colors?: Partial<TerminalThemeColors>
+}
+
+// ============================================================================
+// Theme Color Presets
+// ============================================================================
+
+const darkThemeColors: TerminalThemeColors = {
+  primary: '\x1b[38;5;33m', // Blue
+  secondary: '\x1b[38;5;39m', // Lighter blue
+  accent: '\x1b[38;5;200m', // Magenta/Pink
+  muted: '\x1b[38;5;243m', // Gray
+
+  success: '\x1b[38;5;71m', // Green
+  warning: '\x1b[38;5;220m', // Yellow
+  error: '\x1b[38;5;160m', // Red
+  info: '\x1b[38;5;33m', // Blue
+
+  border: '\x1b[38;5;240m', // Dark gray
+  background: '\x1b[48;5;234m', // Very dark gray
+  foreground: '\x1b[38;5;252m', // Light gray
+
+  selection: '\x1b[48;5;24m', // Dark blue background
+  focus: '\x1b[48;5;33m', // Blue background
+}
+
+const lightThemeColors: TerminalThemeColors = {
+  primary: '\x1b[38;5;25m', // Darker blue for light mode
+  secondary: '\x1b[38;5;31m', // Darker cyan
+  accent: '\x1b[38;5;127m', // Darker magenta
+  muted: '\x1b[38;5;245m', // Medium gray
+
+  success: '\x1b[38;5;28m', // Darker green
+  warning: '\x1b[38;5;172m', // Darker yellow/orange
+  error: '\x1b[38;5;124m', // Darker red
+  info: '\x1b[38;5;25m', // Darker blue
+
+  border: '\x1b[38;5;250m', // Light gray
+  background: '\x1b[48;5;255m', // White
+  foreground: '\x1b[38;5;235m', // Dark gray
+
+  selection: '\x1b[48;5;153m', // Light blue background
+  focus: '\x1b[48;5;33m', // Blue background
+}
+
+// ============================================================================
+// Theme Creation
+// ============================================================================
+
+/**
+ * Creates a terminal theme with dark or light mode base colors.
+ *
+ * Provides sensible defaults for all color tokens based on the selected mode,
+ * with optional overrides for individual colors.
+ *
+ * @param options - Theme creation options
+ * @returns A complete terminal theme object
+ * @throws {ZodError} If options are invalid (invalid mode or color format)
+ *
+ * @example
+ * ```tsx
+ * // Dark theme with defaults
+ * const darkTheme = createTerminalTheme({ mode: 'dark' })
+ *
+ * // Light theme with custom primary color
+ * const customTheme = createTerminalTheme({
+ *   mode: 'light',
+ *   colors: { primary: '\x1b[38;5;27m' }
+ * })
+ * ```
+ */
+export function createTerminalTheme(
+  options: CreateTerminalThemeOptions
+): TerminalTheme {
+  // Validate input with Zod schema
+  CreateTerminalThemeOptionsSchema.parse(options)
+
+  const mode = options.mode || 'dark'
+  const baseColors = mode === 'dark' ? darkThemeColors : lightThemeColors
+
+  return {
+    mode,
+    colors: {
+      ...baseColors,
+      ...options.colors,
+    },
+  }
+}
+
+/**
+ * Gets a color value from a theme by its key name.
+ *
+ * @param theme - The terminal theme to get the color from
+ * @param key - The color key (e.g., 'primary', 'error')
+ * @param fallback - Optional fallback if the key is not found
+ * @returns The ANSI color escape sequence
+ * @throws If key is not found and no fallback is provided
+ *
+ * @example
+ * ```tsx
+ * const theme = createTerminalTheme({ mode: 'dark' })
+ * const errorColor = getThemeColor(theme, 'error')
+ * console.log(`${errorColor}Error message${ANSI.reset}`)
+ * ```
+ */
+export function getThemeColor(
+  theme: TerminalTheme,
+  key: keyof TerminalThemeColors,
+  fallback?: string
+): string {
+  const color = theme.colors[key]
+  if (color !== undefined) {
+    return color
+  }
+  if (fallback !== undefined) {
+    return fallback
+  }
+  throw new Error(`Unknown theme color key: ${key}`)
+}
+
+// ============================================================================
+// CSS Variable Mapping
+// ============================================================================
+
+const CSS_VAR_TO_THEME_KEY: Record<string, keyof TerminalThemeColors> = {
+  '--primary': 'primary',
+  '--secondary': 'secondary',
+  '--accent': 'accent',
+  '--muted': 'muted',
+  '--muted-foreground': 'muted',
+  '--success': 'success',
+  '--warning': 'warning',
+  '--error': 'error',
+  '--destructive': 'error',
+  '--info': 'info',
+  '--border': 'border',
+  '--background': 'background',
+  '--foreground': 'foreground',
+  '--selection': 'selection',
+  '--focus': 'focus',
+}
+
+/**
+ * Maps a CSS custom property name to its ANSI theme color.
+ *
+ * Useful for converting web-based CSS variable references to terminal colors.
+ *
+ * @param cssVar - CSS variable name (e.g., '--primary', '--error')
+ * @param theme - The terminal theme to look up colors from
+ * @returns ANSI escape sequence, or empty string if not found
+ *
+ * @example
+ * ```tsx
+ * const theme = createTerminalTheme({ mode: 'dark' })
+ * const primary = cssVarToAnsi('--primary', theme)
+ * const error = cssVarToAnsi('--destructive', theme) // maps to error
+ * ```
+ */
+export function cssVarToAnsi(cssVar: string, theme: TerminalTheme): string {
+  const key = CSS_VAR_TO_THEME_KEY[cssVar]
+  if (key && theme.colors[key]) {
+    return theme.colors[key]
+  }
+  return ''
+}
+
+// ============================================================================
+// Theme-Aware Styling
+// ============================================================================
+
+/**
+ * Applies a theme color to text with automatic reset.
+ *
+ * A convenience function that wraps text with a theme color and
+ * appends the reset code.
+ *
+ * @param text - The text to style
+ * @param theme - The terminal theme to use
+ * @param styleKey - The theme color key to apply
+ * @returns Styled text with ANSI codes
+ *
+ * @example
+ * ```tsx
+ * const theme = createTerminalTheme({ mode: 'dark' })
+ * console.log(applyThemeStyles('Error!', theme, 'error'))
+ * console.log(applyThemeStyles('Success!', theme, 'success'))
+ * ```
+ */
+export function applyThemeStyles(
+  text: string,
+  theme: TerminalTheme,
+  styleKey: keyof TerminalThemeColors
+): string {
+  const color = theme.colors[styleKey]
+  if (!color) {
+    return text
+  }
+  return `${color}${text}${ANSI.reset}`
+}
+
+// ============================================================================
+// Legacy Theme Presets
+// ============================================================================
+
+export const defaultTheme: LegacyTerminalThemeWithExtras = {
+  primary: ANSI.cyan,
+  secondary: ANSI.blue,
+  accent: ANSI.magenta,
+  muted: ANSI.brightBlack,
+
+  success: ANSI.green,
+  warning: ANSI.yellow,
+  error: ANSI.red,
+  info: ANSI.blue,
+
+  border: ANSI.brightBlack,
+  background: '',
+  foreground: ANSI.white,
+
+  selection: ANSI.bgBlue,
+  focus: ANSI.bgCyan,
+
+  typography: {
+    headingWeight: 'bold',
+    bodyWeight: 'normal',
+    codeFont: 'monospace',
+  },
+
+  spacing: {
+    xs: 1,
+    sm: 2,
+    md: 4,
+    lg: 8,
+    xl: 16,
+  },
+}
+
+/**
+ * Named color constants matching theme semantic colors.
+ */
+export const colors = {
+  primary: ANSI.cyan,
+  secondary: ANSI.blue,
+  accent: ANSI.magenta,
+  muted: ANSI.brightBlack,
+  success: ANSI.green,
+  warning: ANSI.yellow,
+  error: ANSI.red,
+  info: ANSI.blue,
+}
+
+/**
+ * Theme tokens for semantic access.
+ */
+export const themeTokens = {
+  primary: 'primary',
+  secondary: 'secondary',
+  accent: 'accent',
+  muted: 'muted',
+  success: 'success',
+  warning: 'warning',
+  error: 'error',
+  info: 'info',
+} as const
+
+export const darkTheme: LegacyTerminalThemeWithExtras = {
+  ...defaultTheme,
+  background: ANSI.bgBlack,
+  foreground: ANSI.brightWhite,
+}
+
+export const lightTheme: LegacyTerminalThemeWithExtras = {
+  ...defaultTheme,
+  background: ANSI.bgWhite,
+  foreground: ANSI.black,
+}
+
+export const highContrastTheme: LegacyTerminalThemeWithExtras = {
+  ...defaultTheme,
+  foreground: ANSI.brightWhite,
+  background: ANSI.bgBlack,
+  primary: ANSI.brightCyan,
+  secondary: ANSI.brightBlue,
+}
+
+export const themePresets = {
+  default: defaultTheme,
+  dark: darkTheme,
+  light: lightTheme,
+  highContrast: highContrastTheme,
+}
+
+// ============================================================================
+// Theme Creation & Composition Utilities
+// ============================================================================
+
+/**
+ * Deep merge two objects
+ */
+function deepMerge<T extends Record<string, unknown>>(target: T, source: Partial<T>): T {
+  const result = { ...target }
+
+  for (const key of Object.keys(source) as (keyof T)[]) {
+    const sourceValue = source[key]
+    const targetValue = target[key]
+
+    if (sourceValue !== undefined) {
+      if (
+        typeof sourceValue === 'object' &&
+        sourceValue !== null &&
+        !Array.isArray(sourceValue) &&
+        typeof targetValue === 'object' &&
+        targetValue !== null &&
+        !Array.isArray(targetValue)
+      ) {
+        result[key] = deepMerge(
+          targetValue as Record<string, unknown>,
+          sourceValue as Record<string, unknown>
+        ) as T[keyof T]
+      } else {
+        result[key] = sourceValue as T[keyof T]
+      }
+    }
+  }
+
+  return result
+}
+
+/**
+ * Creates a legacy theme with partial overrides from defaults.
+ *
+ * @deprecated Use {@link createTerminalTheme} for new code.
+ *
+ * @param partial - Partial theme overrides
+ * @returns Complete legacy theme with overrides applied
+ * @throws {ZodError} If any color value is not a valid ANSI escape sequence
+ *
+ * @example
+ * ```tsx
+ * const theme = createTheme({
+ *   primary: ANSI.brightGreen,
+ *   error: ANSI.brightRed,
+ * })
+ * ```
+ */
+export function createTheme(partial: Partial<LegacyTerminalThemeWithExtras>): LegacyTerminalThemeWithExtras {
+  // Validate input with Zod schema
+  CreateThemeInputSchema.parse(partial)
+
+  return deepMerge(defaultTheme as unknown as Record<string, unknown>, partial as unknown as Record<string, unknown>) as unknown as LegacyTerminalThemeWithExtras
+}
+
+/**
+ * Extends a base theme with overrides.
+ *
+ * Performs a deep merge of the override values onto the base theme,
+ * allowing nested properties (like typography, spacing) to be
+ * partially overridden.
+ *
+ * @param base - The base theme to extend
+ * @param overrides - Values to override in the base theme
+ * @returns New theme with overrides applied
+ *
+ * @example
+ * ```tsx
+ * const customTheme = extendTheme(defaultTheme, {
+ *   primary: ANSI.brightMagenta,
+ *   typography: { headingWeight: 'bold' },
+ * })
+ * ```
+ */
+export function extendTheme<T extends LegacyTerminalThemeWithExtras>(
+  base: T,
+  overrides: Partial<T> & Record<string, unknown>
+): T & Record<string, unknown> {
+  return deepMerge(base as unknown as Record<string, unknown>, overrides as unknown as Record<string, unknown>) as unknown as T & Record<string, unknown>
+}
+
+/**
+ * Composes multiple theme objects into one.
+ *
+ * Later themes in the argument list override values from earlier themes.
+ * Useful for building up themes from multiple partial configurations.
+ *
+ * @param themes - Theme objects to compose (later overrides earlier)
+ * @returns Merged theme object
+ *
+ * @example
+ * ```tsx
+ * const theme = composeThemes(
+ *   baseTheme,
+ *   brandColorOverrides,
+ *   userPreferences
+ * )
+ * ```
+ */
+export function composeThemes<T extends Record<string, unknown>>(...themes: T[]): T {
+  return themes.reduce((acc, theme) => deepMerge(acc, theme), {} as T)
+}
+
+/**
+ * Creates a named theme variant from a base theme.
+ *
+ * Convenience function for creating theme variants. The name parameter
+ * is currently unused but reserved for future theme registry features.
+ *
+ * @param base - The base theme to start from
+ * @param _name - Name for the variant (reserved for future use)
+ * @param overrides - Values to override in the base theme
+ * @returns New theme variant
+ *
+ * @example
+ * ```tsx
+ * const warningTheme = createThemeVariant(defaultTheme, 'warning', {
+ *   primary: ANSI.yellow,
+ *   accent: ANSI.brightYellow,
+ * })
+ * ```
+ */
+export function createThemeVariant(
+  base: LegacyTerminalThemeWithExtras,
+  _name: string,
+  overrides: Partial<LegacyTerminalThemeWithExtras>
+): LegacyTerminalThemeWithExtras {
+  return extendTheme(base, overrides)
+}
+
+// ============================================================================
+// Color Scheme Detection
+// ============================================================================
+
+/**
+ * Detect system color scheme preference (dark/light)
+ */
+export function detectColorScheme(): 'dark' | 'light' {
+  // Most terminals are dark by default
+  if (typeof process !== 'undefined') {
+    const colorBg = process.env?.COLORFGBG
+    if (colorBg) {
+      const parts = colorBg.split(';')
+      if (parts.length >= 2) {
+        const bg = parseInt(parts[1], 10)
+        if (bg > 7 && bg < 16) {
+          return 'light'
+        }
+      }
+    }
+  }
+  return 'dark'
+}

package/src/types.ts

@@ -0,0 +1,103 @@
+/**
+ * @mdxui/terminal Type Definitions
+ *
+ * Branded types and type utilities for type-safe terminal components.
+ *
+ * @packageDocumentation
+ */
+
+// ============================================================================
+// Branded Types
+// ============================================================================
+
+/**
+ * Brand symbol for FocusId type.
+ * Used to create a nominal/branded type that prevents accidental string usage.
+ */
+declare const FocusIdBrand: unique symbol
+
+/**
+ * Branded type for focus element IDs.
+ *
+ * This is a nominal/branded type that appears as a string at runtime but
+ * provides compile-time type safety. You cannot accidentally pass an
+ * arbitrary string where a FocusId is expected.
+ *
+ * @example
+ * ```tsx
+ * import { createFocusId, type FocusId } from '@mdxui/terminal'
+ *
+ * // Correct - use createFocusId to get a valid FocusId
+ * const id: FocusId = createFocusId('my-element')
+ *
+ * // Error - cannot assign plain string to FocusId
+ * const badId: FocusId = 'some-string' // TypeScript error!
+ * ```
+ */
+export type FocusId = string & { readonly [FocusIdBrand]: true }
+
+/**
+ * Counter for generating unique focus IDs.
+ * @internal
+ */
+let focusIdCounter = 0
+
+/**
+ * Creates a branded FocusId from an optional string.
+ *
+ * If no id is provided, generates a unique id like `focus-1`, `focus-2`, etc.
+ * The returned value is typed as FocusId, which provides compile-time
+ * safety against accidentally using wrong strings.
+ *
+ * @param id - Optional custom ID string. If not provided, auto-generates one.
+ * @returns A branded FocusId that can be used with focus management APIs.
+ *
+ * @example
+ * ```tsx
+ * import { createFocusId } from '@mdxui/terminal'
+ *
+ * // Auto-generate an ID
+ * const autoId = createFocusId() // 'focus-1', 'focus-2', etc.
+ *
+ * // Use a custom ID
+ * const customId = createFocusId('submit-button')
+ *
+ * // Use with useFocus
+ * const focusable = useFocus({ id: 'my-element' })
+ * console.log(focusable.id) // FocusId typed
+ * ```
+ */
+export function createFocusId(id?: string): FocusId {
+  return (id ?? `focus-${++focusIdCounter}`) as FocusId
+}
+
+/**
+ * Type guard to check if a value is a valid FocusId.
+ *
+ * At runtime, FocusId is just a string, so this check validates that
+ * the value is a non-empty string. For compile-time safety, use the
+ * branded type system instead.
+ *
+ * @param value - Value to check
+ * @returns True if value could be a valid FocusId
+ *
+ * @example
+ * ```tsx
+ * const maybeId: unknown = getUserInput()
+ * if (isFocusId(maybeId)) {
+ *   // maybeId is now typed as FocusId
+ *   focusManager.focusById(maybeId)
+ * }
+ * ```
+ */
+export function isFocusId(value: unknown): value is FocusId {
+  return typeof value === 'string' && value.length > 0
+}
+
+/**
+ * Resets the focus ID counter. For testing purposes only.
+ * @internal
+ */
+export function __resetFocusIdCounter(): void {
+  focusIdCounter = 0
+}