@tuicomponents/core 0.1.1

package/dist/index.d.cts

@@ -0,0 +1,715 @@
+import { ZodType, ZodTypeDef } from 'zod';
+import { Theme, Color, ThemeOptions } from 'chromaterm';
+export { Color as ChromatermColor, Theme as ChromatermTheme, ThemeOptions } from 'chromaterm';
+
+/**
+ * Semantic color mappings for TUI components.
+ * Maps component-level semantic names to chromaterm theme colors.
+ */
+interface SemanticColors {
+    /** Primary content color */
+    primary: Color;
+    /** Secondary/muted content */
+    secondary: Color;
+    /** Borders and separators */
+    border: Color;
+    /** Headers and titles */
+    header: Color;
+    /** Success state */
+    success: Color;
+    /** Warning state */
+    warning: Color;
+    /** Error state */
+    error: Color;
+    /** Informational text */
+    info: Color;
+    /** Added content (diffs) */
+    added: Color;
+    /** Removed content (diffs) */
+    removed: Color;
+    /** Modified content (diffs) */
+    modified: Color;
+}
+/**
+ * TUI component theme combining chromaterm's theme with semantic mappings.
+ */
+interface TuiTheme {
+    /** Underlying chromaterm theme with ANSI colors */
+    chromaterm: Theme;
+    /** Semantic color mappings for components */
+    semantic: SemanticColors;
+}
+/**
+ * Create a synchronous T1 (ANSI-16) theme.
+ * Use this when you need a theme immediately without probing.
+ *
+ * @returns TUI theme with ANSI-16 colors
+ *
+ * @example
+ * ```ts
+ * const theme = createThemeSync();
+ * console.log(theme.semantic.error("Error message"));
+ * ```
+ */
+declare function createThemeSync(): TuiTheme;
+/**
+ * Detect terminal capabilities and create an optimized theme.
+ * Uses OSC probing to detect the terminal's actual color palette.
+ *
+ * @param options - Theme detection options
+ * @returns Promise resolving to TUI theme with detected colors
+ *
+ * @example
+ * ```ts
+ * const theme = await detectTheme();
+ * console.log(theme.semantic.success("Success!"));
+ * ```
+ */
+declare function detectTheme(options?: ThemeOptions): Promise<TuiTheme>;
+/**
+ * Global default theme instance (T1 baseline).
+ * For full capability detection, use `detectTheme()` instead.
+ */
+declare const defaultTheme: TuiTheme;
+
+/**
+ * Unified semantic styling for TUI components.
+ *
+ * Provides consistent styling across render modes:
+ * - ANSI mode: Uses theme semantic colors
+ * - Markdown mode: Uses markdown formatting (backticks, bold, etc.)
+ */
+
+/**
+ * Semantic styling functions that work across render modes.
+ *
+ * Components call these functions to apply semantic styling:
+ * - In ANSI mode: Applies theme colors
+ * - In markdown mode: Applies markdown formatting
+ *
+ * @example
+ * ```ts
+ * // In a component render method:
+ * const styledText = context.style.secondary(sparklineBlocks);
+ * // ANSI mode: muted color
+ * // Markdown mode: `sparklineBlocks` (backtick wrapped)
+ * ```
+ */
+interface StyleFunctions {
+    /** Primary content - default foreground */
+    primary: (text: string) => string;
+    /** Secondary/muted content - subdued style */
+    secondary: (text: string) => string;
+    /** Headers and titles - emphasized style */
+    header: (text: string) => string;
+    /** Borders and separators - subtle style */
+    border: (text: string) => string;
+    /** Success state - positive indicator */
+    success: (text: string) => string;
+    /** Warning state - caution indicator */
+    warning: (text: string) => string;
+    /** Error state - negative indicator */
+    error: (text: string) => string;
+    /** Informational text - neutral highlight */
+    info: (text: string) => string;
+}
+/**
+ * Create style functions appropriate for the render mode.
+ *
+ * @param renderMode - The current render mode ("ansi" or "markdown")
+ * @param theme - Optional theme for ANSI mode styling
+ * @returns StyleFunctions that apply mode-appropriate styling
+ *
+ * @example
+ * ```ts
+ * // Markdown mode
+ * const style = createStyleFunctions("markdown");
+ * style.secondary("blocks") // Returns " `blocks`"
+ *
+ * // ANSI mode with theme
+ * const style = createStyleFunctions("ansi", theme);
+ * style.secondary("blocks") // Returns muted-colored text
+ *
+ * // ANSI mode without theme
+ * const style = createStyleFunctions("ansi");
+ * style.secondary("blocks") // Returns "blocks" unchanged
+ * ```
+ */
+declare function createStyleFunctions(renderMode: RenderMode, theme?: TuiTheme): StyleFunctions;
+
+/**
+ * Render mode for component output.
+ */
+type RenderMode = "ansi" | "markdown";
+/**
+ * Example input/output pair for a component.
+ */
+interface ComponentExample<TInput> {
+    /** Human-readable name for this example */
+    name: string;
+    /** Description of what this example demonstrates */
+    description?: string;
+    /** The input data for this example */
+    input: TInput;
+}
+/**
+ * Metadata describing a TUI component.
+ */
+interface ComponentMetadata<TInput> {
+    /** Unique name for this component (e.g., "table", "tree") */
+    name: string;
+    /** Human-readable description */
+    description: string;
+    /** Semantic version */
+    version: string;
+    /** Usage examples */
+    examples: ComponentExample<TInput>[];
+    /**
+     * Render modes this component supports.
+     * If not specified, defaults to ["ansi"].
+     */
+    supportedModes?: RenderMode[];
+}
+/**
+ * Context provided to components during rendering.
+ */
+interface RenderContext {
+    /** Available terminal width in columns */
+    width: number;
+    /** Whether output is going to a TTY */
+    isTTY: boolean;
+    /** Color support level: 0=none, 1=basic, 2=256, 3=truecolor */
+    colorLevel: 0 | 1 | 2 | 3;
+    /** Optional theme for styled output. If not provided, components render without colors. */
+    theme?: TuiTheme;
+    /**
+     * Render mode for output.
+     * - "ansi": Full ANSI escape codes for rich terminals
+     * - "markdown": Markdown-friendly output for AI assistants
+     * @default "ansi"
+     */
+    renderMode: RenderMode;
+    /**
+     * Semantic styling functions.
+     *
+     * Use these to apply consistent styling across render modes:
+     * - ANSI mode: Applies theme colors (or passthrough if no theme)
+     * - Markdown mode: Applies markdown formatting (backticks, bold, etc.)
+     *
+     * @example
+     * ```ts
+     * const styledBlocks = context.style.secondary(sparklineBlocks);
+     * // ANSI: muted color
+     * // Markdown: `sparklineBlocks`
+     * ```
+     */
+    style: StyleFunctions;
+}
+/**
+ * Result of rendering a component.
+ */
+interface RenderResult {
+    /** ANSI-formatted output string */
+    output: string;
+    /** Actual width of the widest line */
+    actualWidth: number;
+    /** Number of lines in the output */
+    lineCount: number;
+}
+/**
+ * A TUI component that renders structured data to terminal output.
+ */
+interface TuiComponent<TInput, TSchema extends ZodType<TInput, ZodTypeDef, unknown> = ZodType<TInput, ZodTypeDef, unknown>> {
+    /** Component metadata */
+    readonly metadata: ComponentMetadata<TInput>;
+    /** Zod schema for input validation */
+    readonly schema: TSchema;
+    /**
+     * Render the component with the given input and context.
+     * @param input - Validated input data
+     * @param context - Rendering context
+     * @returns Rendered output with metadata
+     */
+    render(input: TInput, context: RenderContext): RenderResult;
+    /**
+     * Get JSON Schema representation of the input schema.
+     * Used for CLI discovery and AI assistant integration.
+     */
+    getJsonSchema(): object;
+}
+/**
+ * Factory function type for creating TUI components.
+ */
+type ComponentFactory<TInput, TSchema extends ZodType<TInput, ZodTypeDef, unknown>> = () => TuiComponent<TInput, TSchema>;
+/**
+ * Base class helper for creating TUI components.
+ * Provides default implementations for common functionality.
+ */
+declare abstract class BaseTuiComponent<TInput, TSchema extends ZodType<TInput, ZodTypeDef, unknown>> implements TuiComponent<TInput, TSchema> {
+    abstract readonly metadata: ComponentMetadata<TInput>;
+    abstract readonly schema: TSchema;
+    abstract render(input: TInput, context: RenderContext): RenderResult;
+    getJsonSchema(): object;
+}
+
+/**
+ * Summary information about a registered component.
+ */
+interface ComponentInfo {
+    name: string;
+    description: string;
+    version: string;
+}
+/**
+ * A registered component with unknown input type.
+ * Used internally by the registry.
+ */
+type AnyComponent = TuiComponent<any, ZodType<any, ZodTypeDef, any>>;
+/**
+ * Global registry for TUI components.
+ * Enables CLI discovery and dynamic component lookup.
+ */
+declare class ComponentRegistry {
+    private components;
+    /**
+     * Register a component by invoking its factory function.
+     * @param factory - Factory function that creates the component
+     * @returns The created component instance
+     */
+    register<TInput, TSchema extends ZodType<TInput, ZodTypeDef, unknown>>(factory: () => TuiComponent<TInput, TSchema>): TuiComponent<TInput, TSchema>;
+    /**
+     * Get a component by name.
+     * @param name - Component name
+     * @returns The component or undefined if not found
+     */
+    get(name: string): AnyComponent | undefined;
+    /**
+     * Check if a component is registered.
+     * @param name - Component name
+     */
+    has(name: string): boolean;
+    /**
+     * List all registered components.
+     * @returns Array of component info objects
+     */
+    list(): ComponentInfo[];
+    /**
+     * Get all registered component names.
+     */
+    names(): string[];
+    /**
+     * Clear all registered components.
+     * Primarily useful for testing.
+     */
+    clear(): void;
+}
+/**
+ * Global component registry instance.
+ * Components register themselves here on import.
+ */
+declare const registry: ComponentRegistry;
+
+/**
+ * Get the visual width of a string in terminal columns.
+ * Handles emoji, CJK characters, ANSI escape codes, and zero-width characters.
+ *
+ * @param str - The string to measure
+ * @returns Width in terminal columns
+ *
+ * @example
+ * ```ts
+ * getStringWidth("hello");     // 5
+ * getStringWidth("你好");       // 4 (CJK characters are 2 columns each)
+ * getStringWidth("👋");         // 2 (emoji are typically 2 columns)
+ * getStringWidth("\x1b[31mred\x1b[0m"); // 3 (ANSI codes have 0 width)
+ * ```
+ */
+declare function getStringWidth(str: string): number;
+/**
+ * Options for padding operations.
+ */
+interface PadOptions {
+    /** Character to use for padding (default: space) */
+    padChar?: string;
+    /** Alignment direction */
+    align?: "left" | "right" | "center";
+}
+/**
+ * Pad a string to a target width.
+ * If the string is already wider than the target, it is returned unchanged.
+ *
+ * @param str - The string to pad
+ * @param targetWidth - Target width in columns
+ * @param options - Padding options
+ * @returns Padded string
+ *
+ * @example
+ * ```ts
+ * padToWidth("hi", 5);                    // "hi   "
+ * padToWidth("hi", 5, { align: "right" }); // "   hi"
+ * padToWidth("hi", 5, { align: "center" }); // " hi  "
+ * ```
+ */
+declare function padToWidth(str: string, targetWidth: number, options?: PadOptions): string;
+/**
+ * Options for truncation operations.
+ */
+interface TruncateOptions {
+    /** String to append when truncating (default: "…") */
+    ellipsis?: string;
+    /** Where to truncate: end or middle */
+    position?: "end" | "middle";
+}
+/**
+ * Truncate a string to fit within a target width.
+ * If the string already fits, it is returned unchanged.
+ *
+ * @param str - The string to truncate
+ * @param targetWidth - Maximum width in columns
+ * @param options - Truncation options
+ * @returns Truncated string
+ *
+ * @example
+ * ```ts
+ * truncateToWidth("hello world", 8);           // "hello w…"
+ * truncateToWidth("hello world", 8, { ellipsis: "..." }); // "hello..."
+ * truncateToWidth("hello world", 8, { position: "middle" }); // "hel…rld"
+ * ```
+ */
+declare function truncateToWidth(str: string, targetWidth: number, options?: TruncateOptions): string;
+/**
+ * Split a string into lines and measure each line's width.
+ *
+ * @param str - The string to analyze
+ * @returns Object with lines array and max width
+ */
+declare function measureLines(str: string): {
+    lines: string[];
+    maxWidth: number;
+    lineCount: number;
+};
+
+/**
+ * Default terminal dimensions when size cannot be determined.
+ */
+declare const DEFAULT_TERMINAL_WIDTH = 80;
+declare const DEFAULT_TERMINAL_HEIGHT = 24;
+/**
+ * Get the current terminal size.
+ *
+ * @returns Object with columns and rows
+ *
+ * @example
+ * ```ts
+ * const { columns, rows } = getTerminalSize();
+ * console.log(`Terminal is ${columns}x${rows}`);
+ * ```
+ */
+declare function getTerminalSize(): {
+    columns: number;
+    rows: number;
+};
+/**
+ * Get the current terminal width.
+ *
+ * @returns Width in columns
+ */
+declare function getTerminalWidth(): number;
+/**
+ * Check if stdout is a TTY.
+ *
+ * @returns true if running in a TTY
+ */
+declare function isTTY(): boolean;
+/**
+ * Detect the color support level of the terminal.
+ *
+ * @returns Color level: 0=none, 1=basic (16), 2=256, 3=truecolor (16m)
+ */
+declare function detectColorLevel(): 0 | 1 | 2 | 3;
+/**
+ * Options for creating a render context.
+ */
+interface CreateRenderContextOptions {
+    /** Override the detected terminal width */
+    width?: number;
+    /** Provide a custom theme (default: defaultTheme if colors enabled) */
+    theme?: TuiTheme;
+    /** Disable colors even if terminal supports them */
+    noColor?: boolean;
+    /**
+     * Explicit render mode override.
+     * If set, disables auto-detection.
+     */
+    renderMode?: RenderMode;
+    /**
+     * Whether to auto-detect render mode based on environment.
+     * When true (default), uses markdown mode in AI assistants.
+     * @default true
+     */
+    autoDetectMode?: boolean;
+}
+/**
+ * Create a render context from current terminal state.
+ *
+ * @param options - Optional overrides for the context
+ * @returns A RenderContext ready for component rendering
+ *
+ * @example
+ * ```ts
+ * // Auto-detect everything with theme
+ * const ctx = createRenderContext();
+ *
+ * // Force a specific width
+ * const ctx = createRenderContext({ width: 120 });
+ *
+ * // Disable colors
+ * const ctx = createRenderContext({ noColor: true });
+ *
+ * // Force markdown mode
+ * const ctx = createRenderContext({ renderMode: "markdown" });
+ * ```
+ */
+declare function createRenderContext(options?: CreateRenderContextOptions): RenderContext;
+
+/**
+ * Options for text wrapping.
+ */
+interface WrapOptions {
+    /** Whether to hard-wrap words that exceed the width */
+    hard?: boolean;
+    /** Whether to trim leading/trailing whitespace from each line */
+    trim?: boolean;
+    /** Whether to wrap at word boundaries (default: true) */
+    wordWrap?: boolean;
+}
+/**
+ * Wrap text to fit within a specified width.
+ * Preserves ANSI escape codes when wrapping.
+ *
+ * @param text - Text to wrap
+ * @param width - Maximum width in columns
+ * @param options - Wrapping options
+ * @returns Wrapped text with newlines
+ *
+ * @example
+ * ```ts
+ * wrapText("The quick brown fox jumps over the lazy dog", 20);
+ * // "The quick brown fox\njumps over the lazy\ndog"
+ *
+ * // With ANSI codes preserved
+ * wrapText("\x1b[31mRed text that is very long\x1b[0m", 10);
+ * // "\x1b[31mRed text\x1b[0m\n\x1b[31mthat is\x1b[0m\n\x1b[31mvery long\x1b[0m"
+ * ```
+ */
+declare function wrapText(text: string, width: number, options?: WrapOptions): string;
+/**
+ * Wrap text and return information about the result.
+ *
+ * @param text - Text to wrap
+ * @param width - Maximum width in columns
+ * @param options - Wrapping options
+ * @returns Object with wrapped text and metadata
+ */
+declare function wrapTextWithInfo(text: string, width: number, options?: WrapOptions): {
+    text: string;
+    lines: string[];
+    lineCount: number;
+    maxWidth: number;
+};
+
+/**
+ * Information about a process in the ancestry chain.
+ */
+interface ProcessAncestor {
+    pid: number;
+    command: string;
+}
+/**
+ * Result of environment detection.
+ */
+interface EnvironmentDetection {
+    /** Whether the environment is likely an AI assistant */
+    isAIAssistant: boolean;
+    /** Confidence level of the detection */
+    confidence: "high" | "medium" | "low";
+    /** Name of the detected assistant (if identified) */
+    detectedAssistant?: string;
+    /** Process tree from current process up to init */
+    processTree: ProcessAncestor[];
+}
+/**
+ * Walk up the process tree to find parent processes.
+ * Only works on Unix-like systems (macOS, Linux).
+ *
+ * @returns Array of process ancestors from immediate parent up
+ */
+declare function getProcessTree(): ProcessAncestor[];
+/**
+ * Detect the environment and determine if running in an AI assistant.
+ *
+ * Uses multiple heuristics:
+ * - Process tree analysis (most reliable)
+ * - TTY detection
+ * - Environment variables
+ * - Color support level
+ *
+ * @returns Detection result with confidence
+ *
+ * @example
+ * ```ts
+ * const detection = detectEnvironment();
+ * if (detection.isAIAssistant) {
+ *   console.log(`Running in ${detection.detectedAssistant}`);
+ * }
+ * ```
+ */
+declare function detectEnvironment(): EnvironmentDetection;
+/**
+ * Simple check if running in an AI assistant environment.
+ *
+ * @returns true if likely running in an AI assistant
+ *
+ * @example
+ * ```ts
+ * if (isRunningInAIAssistant()) {
+ *   // Use markdown-friendly output
+ * }
+ * ```
+ */
+declare function isRunningInAIAssistant(): boolean;
+
+/**
+ * Markdown rendering utilities for AI assistant-friendly output.
+ *
+ * These utilities help create output that renders well in environments
+ * that strip ANSI escape codes but support markdown rendering.
+ */
+/**
+ * Style types for the two-color markdown system.
+ * - "primary": Plain text (default terminal foreground)
+ * - "secondary": Inline code (`text`) - typically rendered with tan/yellow background
+ */
+type MarkdownStyle = "primary" | "secondary";
+/**
+ * Default anchor character for line starts.
+ * Using │ (U+2502 BOX DRAWINGS LIGHT VERTICAL) as it's visually unobtrusive
+ * and prevents leading whitespace collapse in markdown rendering.
+ */
+declare const DEFAULT_ANCHOR = "\u2502";
+/**
+ * Wrap text in inline code formatting.
+ *
+ * Adds a leading space before the opening backtick to compensate for
+ * the visual width difference when backticks are rendered as invisible.
+ *
+ * @param text - Text to wrap
+ * @returns Text wrapped in inline code with alignment compensation
+ *
+ * @example
+ * ```ts
+ * inlineCode("hello") // Returns " `hello`"
+ * ```
+ */
+declare function inlineCode(text: string): string;
+/**
+ * Add an anchor character to the start of a line.
+ *
+ * Markdown renderers often collapse leading whitespace. Using an anchor
+ * character at the start of each line preserves alignment.
+ *
+ * @param content - Line content (without the anchor)
+ * @param anchor - Anchor character to use (defaults to │)
+ * @returns Line with anchor prefix
+ *
+ * @example
+ * ```ts
+ * anchorLine("  Sales    ████████") // "│  Sales    ████████"
+ * ```
+ */
+declare function anchorLine(content: string, anchor?: string): string;
+/**
+ * Apply a markdown style to text.
+ *
+ * Implements the two-color system for markdown mode:
+ * - "primary": Returns text unchanged (plain foreground)
+ * - "secondary": Wraps text in inline code (typically tan/yellow background)
+ *
+ * @param text - Text to style
+ * @param style - Style to apply
+ * @returns Styled text
+ *
+ * @example
+ * ```ts
+ * applyMarkdownStyle("Sales", "primary")   // "Sales"
+ * applyMarkdownStyle("Support", "secondary") // " `Support`"
+ * ```
+ */
+declare function applyMarkdownStyle(text: string, style: MarkdownStyle): string;
+/**
+ * Join multiple lines with anchors.
+ *
+ * @param lines - Lines to join
+ * @param anchor - Anchor character to use
+ * @returns Lines joined with newlines, each prefixed with anchor
+ *
+ * @example
+ * ```ts
+ * joinAnchoredLines(["line 1", "line 2"]) // "│line 1\n│line 2"
+ * ```
+ */
+declare function joinAnchoredLines(lines: string[], anchor?: string): string;
+/**
+ * Strip markdown formatting characters that will be consumed during rendering.
+ *
+ * This removes:
+ * - Inline code backticks: `text` → text
+ * - Bold markers: **text** or __text__ → text
+ * - Italic markers at word boundaries: *text* or _text_ → text
+ *
+ * It preserves:
+ * - Mid-word underscores: foo_bar stays as foo_bar
+ * - Asterisks with surrounding spaces: a * b stays as a * b
+ * - Unmatched markers without a closing pair
+ *
+ * @param str - String potentially containing markdown formatting
+ * @returns String with consumed formatting characters removed
+ *
+ * @example
+ * ```ts
+ * stripMarkdownFormatting("`code`")     // "code"
+ * stripMarkdownFormatting("**bold**")   // "bold"
+ * stripMarkdownFormatting("_italic_")   // "italic"
+ * stripMarkdownFormatting("foo_bar")    // "foo_bar" (preserved)
+ * stripMarkdownFormatting("a * b")      // "a * b" (preserved)
+ * ```
+ */
+declare function stripMarkdownFormatting(str: string): string;
+/**
+ * Get the visual width of a string after markdown rendering.
+ *
+ * This accounts for markdown formatting characters that will be consumed
+ * (become invisible) when rendered, such as backticks for inline code,
+ * asterisks for bold/italic, etc.
+ *
+ * Use this instead of getStringWidth() when calculating alignment for
+ * markdown output where formatting characters affect visual width.
+ *
+ * @param str - String potentially containing markdown formatting
+ * @returns Visual width in columns after markdown rendering
+ *
+ * @example
+ * ```ts
+ * getStringWidth("`code`")           // 6 (counts backticks)
+ * getMarkdownRenderedWidth("`code`") // 4 (backticks will be invisible)
+ *
+ * getStringWidth("**bold**")           // 8 (counts asterisks)
+ * getMarkdownRenderedWidth("**bold**") // 4 (asterisks will be invisible)
+ *
+ * getStringWidth("foo_bar")           // 7
+ * getMarkdownRenderedWidth("foo_bar") // 7 (underscore preserved mid-word)
+ * ```
+ */
+declare function getMarkdownRenderedWidth(str: string): number;
+
+export { BaseTuiComponent, type ComponentExample, type ComponentFactory, type ComponentInfo, type ComponentMetadata, ComponentRegistry, type CreateRenderContextOptions, DEFAULT_ANCHOR, DEFAULT_TERMINAL_HEIGHT, DEFAULT_TERMINAL_WIDTH, type EnvironmentDetection, type MarkdownStyle, type PadOptions, type ProcessAncestor, type RenderContext, type RenderMode, type RenderResult, type SemanticColors, type StyleFunctions, type TruncateOptions, type TuiComponent, type TuiTheme, type WrapOptions, anchorLine, applyMarkdownStyle, createRenderContext, createStyleFunctions, createThemeSync, defaultTheme, detectColorLevel, detectEnvironment, detectTheme, getMarkdownRenderedWidth, getProcessTree, getStringWidth, getTerminalSize, getTerminalWidth, inlineCode, isRunningInAIAssistant, isTTY, joinAnchoredLines, measureLines, padToWidth, registry, stripMarkdownFormatting, truncateToWidth, wrapText, wrapTextWithInfo };