@mdxui/terminal 2.0.0

package/src/index.ts

@@ -0,0 +1,542 @@
+/**
+ * @mdxui/terminal
+ *
+ * OpenTUI renderer for MDXUI primitives.
+ * Build CLI dashboards with the same component contracts as web.
+ *
+ * @example
+ * ```tsx
+ * import { CLI, Box, Text } from '@mdxui/terminal'
+ *
+ * async function main() {
+ *   const cli = await CLI()
+ *   cli.render(
+ *     <Box border="single">
+ *       <Text color="cyan">Hello Terminal!</Text>
+ *     </Box>
+ *   )
+ * }
+ *
+ * main()
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // For more control, use the lower-level API
+ * import { createCliRenderer, createRoot } from '@mdxui/terminal'
+ *
+ * async function main() {
+ *   const renderer = await createCliRenderer()
+ *   const root = createRoot(renderer)
+ *   root.render(<App />)
+ * }
+ * ```
+ */
+
+import React, { createContext, useContext, useState, useEffect, type ReactNode } from 'react'
+import { detectColorSupport } from './theme'
+
+// Re-export components mapped to OpenTUI
+export * from './components'
+export * from './theme'
+export * from './keyboard'
+export * from './types'
+export * from './data'
+
+// Core compiler
+export * from './core/compiler'
+
+// Core parser
+export { parseUINode, parseUINodeFromJSON, ParseError } from './core/parser'
+
+// Core types (selective export to avoid conflicts with components/types RenderContext)
+export type { UINode, RenderTier, ThemeTokens } from './core/types'
+export type { RenderContext as CoreRenderContext } from './core/types'
+export { UINodeSchema, RenderTierSchema, ThemeTokensSchema, RenderContextSchema } from './core/types'
+
+// Renderers
+export { renderText } from './renderers/text'
+export type { TextRenderOptions } from './renderers/text'
+
+// ANSI to CSS conversion for web rendering
+export {
+  ansiToCSS,
+  ansiToHTML,
+  parseAnsiToSpans,
+  spanToInlineStyle,
+} from './renderers/ansi-css'
+export type {
+  CSSStyleProperties,
+  StyledSpan,
+  ANSIToCSSResult,
+} from './renderers/ansi-css'
+
+// ============================================================================
+// Renderer Setup
+// ============================================================================
+
+/**
+ * CLI renderer configuration options
+ */
+export interface CliRendererConfig {
+  /** Input stream (defaults to process.stdin) */
+  stdin?: NodeJS.ReadStream
+  /** Output stream (defaults to process.stdout) */
+  stdout?: NodeJS.WriteStream
+  /** Exit on Ctrl+C (defaults to true) */
+  exitOnCtrlC?: boolean
+  /** Target frames per second */
+  targetFps?: number
+  /** Use alternate screen buffer */
+  useAlternateScreen?: boolean
+  /** Enable mouse support */
+  useMouse?: boolean
+  /** Background color */
+  backgroundColor?: string
+}
+
+/**
+ * CLI renderer instance
+ */
+export interface CliRenderer {
+  /** Terminal width in columns */
+  width: number
+  /** Terminal height in rows */
+  height: number
+  /** Start the render loop */
+  start(): void
+  /** Stop the render loop */
+  stop(): void
+  /** Destroy the renderer and clean up */
+  destroy(): void
+  /** Request a render update */
+  requestRender(): void
+}
+
+/**
+ * Root interface for React rendering
+ */
+export interface Root {
+  /** Render a React element */
+  render(element: ReactNode): void
+  /** Unmount and clean up */
+  unmount(): void
+}
+
+/**
+ * Create an OpenTUI CLI renderer for terminal rendering.
+ *
+ * @param config - Optional configuration options
+ * @returns Promise resolving to a CLI renderer instance
+ *
+ * @example
+ * ```tsx
+ * import { createCliRenderer, createRoot } from '@mdxui/terminal'
+ *
+ * async function main() {
+ *   const renderer = await createCliRenderer()
+ *   const root = createRoot(renderer)
+ *   root.render(<App />)
+ * }
+ * ```
+ */
+export async function createCliRenderer(config?: CliRendererConfig): Promise<CliRenderer> {
+  const { createCliRenderer: opentuiCreateCliRenderer } = await import('@opentui/core')
+  return opentuiCreateCliRenderer(config)
+}
+
+/**
+ * Create a root for rendering a React tree with the given CLI renderer.
+ *
+ * @param renderer - The CLI renderer to use (from createCliRenderer)
+ * @returns A root object with render and unmount methods
+ *
+ * @example
+ * ```tsx
+ * const renderer = await createCliRenderer()
+ * const root = createRoot(renderer)
+ * root.render(<App />)
+ *
+ * // Later, to clean up:
+ * root.unmount()
+ * renderer.destroy()
+ * ```
+ */
+export function createRoot(renderer: CliRenderer): Root {
+  // Dynamic import to avoid issues in non-terminal environments
+  let rootInstance: Root | null = null
+  let initPromise: Promise<Root> | null = null
+
+  return {
+    render: async (element: ReactNode) => {
+      // Guard against race condition: if render() is called twice before
+      // the async import completes, we reuse the same initialization promise
+      // to ensure only one root instance is created
+      if (!initPromise) {
+        initPromise = import('@opentui/react').then(({ createRoot: opentuiCreateRoot }) => {
+          rootInstance = opentuiCreateRoot(renderer as any)
+          return rootInstance
+        })
+      }
+      const root = await initPromise
+      root.render(element)
+    },
+    unmount: () => {
+      if (rootInstance) {
+        rootInstance.unmount()
+        rootInstance = null
+      }
+      initPromise = null
+    },
+  }
+}
+
+// ============================================================================
+// High-Level CLI API
+// ============================================================================
+
+/**
+ * Options for the CLI() function
+ */
+export interface CLIOptions {
+  /** Color support level. Auto-detected if not specified. */
+  colorSupport?: 'none' | '16' | '256' | 'truecolor'
+  /** Input stream (defaults to process.stdin) */
+  stdin?: NodeJS.ReadStream
+  /** Output stream (defaults to process.stdout) */
+  stdout?: NodeJS.WriteStream
+  /** Exit on Ctrl+C (defaults to true) */
+  exitOnCtrlC?: boolean
+  /** Target frames per second */
+  targetFps?: number
+  /** Use alternate screen buffer */
+  useAlternateScreen?: boolean
+  /** Enable mouse support */
+  useMouse?: boolean
+  /** Background color */
+  backgroundColor?: string
+}
+
+/**
+ * CLI instance returned by CLI()
+ */
+export interface CLIInstance {
+  /** Terminal width in columns */
+  readonly width: number
+  /** Terminal height in rows */
+  readonly height: number
+  /** Render a React element to the terminal */
+  render: (element: ReactNode) => void
+  /** Clear the terminal */
+  clear: () => void
+  /** Destroy the CLI instance and clean up resources */
+  destroy: () => void
+  /** Request a render update */
+  requestRender: () => void
+  /** The underlying renderer instance */
+  readonly renderer: CliRenderer
+  /** The underlying root instance */
+  readonly root: Root
+}
+
+/**
+ * Create a high-level CLI instance for terminal rendering.
+ *
+ * This is the recommended entry point for building terminal UIs with @mdxui/terminal.
+ * It combines `createCliRenderer` and `createRoot` into a single, easy-to-use API.
+ *
+ * @param options - Optional configuration options
+ * @returns Promise resolving to a CLI instance with render, clear, and destroy methods
+ *
+ * @example
+ * ```tsx
+ * import { CLI, Box, Text } from '@mdxui/terminal'
+ *
+ * async function main() {
+ *   const cli = await CLI()
+ *   cli.render(
+ *     <Box border="single">
+ *       <Text color="cyan">Hello Terminal!</Text>
+ *     </Box>
+ *   )
+ * }
+ *
+ * main()
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With custom options
+ * const cli = await CLI({
+ *   useAlternateScreen: true,
+ *   useMouse: true,
+ *   exitOnCtrlC: true,
+ * })
+ * ```
+ */
+export async function CLI(options?: CLIOptions): Promise<CLIInstance> {
+  // Detect color support if not explicitly specified
+  const colorSupport = options?.colorSupport ?? detectColorSupport()
+
+  // Map our simplified color support to OpenTUI's config
+  // OpenTUI doesn't have a direct colorSupport option, but we can use it
+  // for future color adaptation in our components
+
+  // Create the underlying renderer - use dynamic import to get the real OpenTUI renderer
+  const { createCliRenderer: opentuiCreateCliRenderer } = await import('@opentui/core')
+  const { createRoot: opentuiCreateRoot } = await import('@opentui/react')
+
+  const opentuiRenderer = await opentuiCreateCliRenderer({
+    stdin: options?.stdin,
+    stdout: options?.stdout,
+    exitOnCtrlC: options?.exitOnCtrlC,
+    targetFps: options?.targetFps,
+    useAlternateScreen: options?.useAlternateScreen,
+    useMouse: options?.useMouse,
+    backgroundColor: options?.backgroundColor,
+  })
+
+  // Create the React root with the actual OpenTUI renderer
+  const root = opentuiCreateRoot(opentuiRenderer)
+
+  // Create a simplified interface that exposes what consumers need
+  const renderer: CliRenderer = {
+    get width() {
+      return opentuiRenderer.width
+    },
+    get height() {
+      return opentuiRenderer.height
+    },
+    start: () => opentuiRenderer.start(),
+    stop: () => opentuiRenderer.stop(),
+    destroy: () => opentuiRenderer.destroy(),
+    requestRender: () => opentuiRenderer.requestRender(),
+  }
+
+  return {
+    get width() {
+      return opentuiRenderer.width
+    },
+    get height() {
+      return opentuiRenderer.height
+    },
+    render: (element: ReactNode) => {
+      root.render(element)
+    },
+    clear: () => {
+      // Render empty to clear
+      root.render(null)
+    },
+    destroy: () => {
+      root.unmount()
+      opentuiRenderer.destroy()
+    },
+    requestRender: () => {
+      opentuiRenderer.requestRender()
+    },
+    renderer,
+    root,
+  }
+}
+
+// ============================================================================
+// Terminal-Specific Hooks
+// ============================================================================
+
+/**
+ * Get the current terminal dimensions, with automatic updates on resize.
+ *
+ * Returns `{ width, height }` representing the terminal's column and row count.
+ *
+ * **Behavior by environment:**
+ * - **Node.js TTY**: Uses `process.stdout.columns/rows` and subscribes to resize events
+ * - **Browser/Non-TTY**: Falls back to 80x24 defaults
+ *
+ * @returns Current terminal width and height in columns/rows
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { width, height } = useTerminalSize()
+ *   return <Text>Terminal: {width}x{height}</Text>
+ * }
+ * ```
+ */
+export function useTerminalSize(): { width: number; height: number } {
+  // Helper to get current dimensions
+  const getSize = (): { width: number; height: number } => {
+    if (typeof process !== 'undefined' && process.stdout?.columns && process.stdout?.rows) {
+      return {
+        width: process.stdout.columns,
+        height: process.stdout.rows,
+      }
+    }
+    // Default fallback for non-terminal environments (e.g., browser, tests)
+    return { width: 80, height: 24 }
+  }
+
+  const [size, setSize] = useState(getSize)
+
+  useEffect(() => {
+    // Only subscribe to resize events in Node.js TTY environment
+    if (typeof process === 'undefined' || !process.stdout?.on) {
+      return
+    }
+
+    const handleResize = () => {
+      setSize(getSize())
+    }
+
+    // Subscribe to resize events
+    process.stdout.on('resize', handleResize)
+
+    // Sync with current size in case it changed between initial render and effect
+    const currentSize = getSize()
+    if (currentSize.width !== size.width || currentSize.height !== size.height) {
+      setSize(currentSize)
+    }
+
+    // Cleanup listener on unmount
+    return () => {
+      process.stdout.off('resize', handleResize)
+    }
+  }, []) // Empty deps - we only want to set up listener once
+
+  return size
+}
+
+/**
+ * Access terminal context and capabilities.
+ *
+ * Provides terminal dimensions plus color support detection and raw mode status.
+ * Uses @opentui/react for dimensions and our color-support module for capabilities.
+ *
+ * @returns Terminal state including dimensions, color support level, and raw mode
+ *
+ * @example
+ * ```tsx
+ * function StatusBar() {
+ *   const { width, height, colorSupport } = useTerminal()
+ *   return (
+ *     <Box>
+ *       <Text>Size: {width}x{height}</Text>
+ *       <Text>Colors: {colorSupport}</Text>
+ *     </Box>
+ *   )
+ * }
+ * ```
+ */
+export function useTerminal(): {
+  width: number
+  height: number
+  colorSupport: 'none' | 'basic' | '256' | 'truecolor'
+  isRaw: boolean
+} {
+  const { width, height } = useTerminalSize()
+
+  // Detect color support using our existing utility
+  // detectColorSupport returns 'none' | '16' | '256' | 'truecolor'
+  // We map '16' to 'basic' for a more intuitive API
+  const detected = detectColorSupport()
+  const colorSupport: 'none' | 'basic' | '256' | 'truecolor' =
+    detected === '16' ? 'basic' : detected
+
+  // Check raw mode from process.stdin
+  const isRaw = typeof process !== 'undefined' && process.stdin?.isRaw === true
+
+  return {
+    width,
+    height,
+    colorSupport,
+    isRaw,
+  }
+}
+
+// useFocus is exported from ./keyboard
+// useKeyboard and keyboard bindings are exported from ./keyboard
+// For hotkey functionality, use createKeyboardManager with VIM_BINDINGS or COMMON_BINDINGS
+
+// ============================================================================
+// Theme Context
+// ============================================================================
+
+interface ThemeContextValue {
+  theme: 'light' | 'dark'
+  setTheme: (theme: 'light' | 'dark') => void
+  colors: Record<string, string>
+}
+
+const ThemeContext = createContext<ThemeContextValue | null>(null)
+
+/**
+ * Access current theme and colors
+ */
+export function useTheme(): ThemeContextValue {
+  const context = useContext(ThemeContext)
+  if (!context) {
+    // Return default theme if not in provider
+    return {
+      theme: 'dark',
+      setTheme: () => {},
+      colors: {},
+    }
+  }
+  return context
+}
+
+// ============================================================================
+// Providers
+// ============================================================================
+
+export interface TerminalProviderProps {
+  children?: ReactNode
+}
+
+/**
+ * Terminal context provider - wraps app with terminal capabilities
+ */
+export function TerminalProvider(props: TerminalProviderProps): React.ReactElement {
+  return React.createElement('terminal-provider', props)
+}
+
+export interface ThemeProviderProps {
+  children?: ReactNode
+  theme?: 'light' | 'dark'
+}
+
+/**
+ * Theme provider - provides color scheme to components
+ */
+export function ThemeProvider(props: ThemeProviderProps): React.ReactElement {
+  const value: ThemeContextValue = {
+    theme: props.theme || 'dark',
+    setTheme: () => {},
+    colors: {},
+  }
+  return React.createElement(
+    ThemeContext.Provider,
+    { value },
+    props.children
+  )
+}
+
+// FocusProvider is exported from ./keyboard
+
+// ============================================================================
+// App Shell
+// ============================================================================
+
+export interface TerminalAppProps {
+  children: React.ReactNode
+  /** Show status bar at bottom */
+  statusBar?: React.ReactNode
+  /** Handle quit (Ctrl+C, q) */
+  onQuit?: () => void
+}
+
+/**
+ * Terminal app shell with standard layout
+ */
+export function TerminalApp(props: TerminalAppProps): React.ReactElement {
+  return React.createElement('terminal-app', props)
+}