ink-hud 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1510 @@
+import React from 'react';
+import { BoxProps } from 'ink';
+
+interface Pixel {
+    /** Whether the pixel is active (lit) */
+    active: boolean;
+    /** Color of the pixel */
+    color?: string;
+}
+/**
+ * A line of rendered text, consisting of segments with optional styling.
+ */
+type RenderedLine = Array<{
+    text: string;
+    color?: string;
+    backgroundColor?: string;
+}>;
+
+/**
+ * Renderer Module - Defines a unified interface for all renderers
+ */
+/**
+ * Renderer type
+ */
+type RendererType = 'braille' | 'block' | 'ascii';
+/**
+ * Renderer resolution information
+ * Represents how many pixels each character can display
+ */
+interface RendererResolution {
+    /** Pixels per character horizontally (e.g. Braille 2, Block 2, ASCII 1) */
+    horizontal: number;
+    /** Pixels per character vertically (e.g. Braille 4, Block 8, ASCII 1) */
+    vertical: number;
+}
+/**
+ * Renderer metadata
+ * Describes renderer capabilities and requirements
+ */
+interface RendererMetadata {
+    /** Renderer name */
+    name: RendererType;
+    /** Renderer display name */
+    displayName: string;
+    /** Renderer description */
+    description: string;
+    /** Renderer resolution */
+    resolution: RendererResolution;
+    /** Whether UTF-8 support is required */
+    requiresUtf8: boolean;
+    /** Whether Unicode support is required */
+    requiresUnicode: boolean;
+    /** Minimum terminal capability score requirement (0-100) */
+    minScore: number;
+}
+/**
+ * Abstract Renderer base class
+ *
+ * Provides common implementations for all drawing primitives. Subclasses only need to implement:
+ * - getMetadata(): Return renderer metadata
+ * - renderCanvas(): Convert Pixel[][] to terminal characters
+ */
+declare abstract class Renderer {
+    /**
+     * Get renderer metadata (must be implemented by subclasses)
+     */
+    abstract getMetadata(): RendererMetadata;
+    /**
+     * Render Canvas as styled lines of text (must be implemented by subclasses)
+     * @param pixels - 2D pixel array
+     * @param width - Canvas width (pixels)
+     * @param height - Canvas height (pixels)
+     * @returns Array of colored text lines
+     */
+    abstract renderCanvas(pixels: Pixel[][], width: number, height: number): RenderedLine[];
+    /**
+     * Create a blank Canvas
+     * @param width - Canvas width (pixels)
+     * @param height - Canvas height (pixels)
+     * @returns 2D pixel array
+     */
+    createCanvas(width: number, height: number): Pixel[][];
+    /**
+     * Set a single pixel on the Canvas
+     * @param canvas - Canvas
+     * @param x - x coordinate
+     * @param y - y coordinate
+     * @param pixel - Pixel properties (active, color, etc.)
+     */
+    setPixel(canvas: Pixel[][], x: number, y: number, pixel?: Partial<Pixel>): void;
+    /**
+     * Draw line segments (Bresenham's algorithm)
+     */
+    drawLine(canvas: Pixel[][], x0: number, y0: number, x1: number, y1: number, pixel?: Partial<Pixel>): void;
+    /**
+     * Draw circle or ring (Midpoint Circle algorithm)
+     */
+    drawCircle(canvas: Pixel[][], centerX: number, centerY: number, radius: number, filled?: boolean, pixel?: Partial<Pixel>): void;
+    /**
+     * Draw arc (Parametric equation)
+     */
+    drawArc(canvas: Pixel[][], centerX: number, centerY: number, radius: number, startAngle: number, endAngle: number, thickness?: number, pixel?: Partial<Pixel>): void;
+    /**
+     * Draw rectangle
+     */
+    drawRect(canvas: Pixel[][], x: number, y: number, width: number, height: number, filled?: boolean, pixel?: Partial<Pixel>): void;
+    /**
+     * Get renderer resolution
+     */
+    getResolution(): RendererResolution;
+    /**
+     * Get renderer name
+     */
+    getName(): RendererType;
+    /**
+     * Calculate number of character rows and columns needed to render specified dimensions
+     */
+    calculateCharDimensions(pixelWidth: number, pixelHeight: number): {
+        rows: number;
+        cols: number;
+    };
+}
+
+/**
+ * Braille Renderer
+ *
+ * Implements 2x4 dot matrix rendering using Braille Unicode characters (U+2800-U+28FF)
+ * Each character can represent 8 sub-pixels, providing 8x resolution
+ */
+declare class BrailleRenderer extends Renderer {
+    getMetadata(): RendererMetadata;
+    private createBrailleChar;
+    private pixelToDotIndex;
+    private fillBrailleDots;
+    private resolveColor;
+    renderCanvas(pixels: Pixel[][], width: number, height: number): RenderedLine[];
+}
+
+/**
+ * Block Elements renderer
+ *
+ * Implements 2x8 dot matrix rendering using Unicode Block Elements characters (U+2581-U+2588)
+ * Vertical 8x resolution, horizontal 2x resolution
+ */
+declare class BlockRenderer extends Renderer {
+    private static readonly BLOCK_LUT;
+    getMetadata(): RendererMetadata;
+    /**
+     * Determine primary color
+     */
+    private resolveColor;
+    renderCanvas(pixels: Pixel[][], width: number, height: number): RenderedLine[];
+}
+
+/**
+ * ASCII renderer
+ *
+ * Implements 1x3 dot matrix rendering using basic ASCII characters
+ * Simulates subtle height variations using top/middle/bottom character segments
+ */
+declare class AsciiRenderer extends Renderer {
+    getMetadata(): RendererMetadata;
+    /**
+     * Check if the pixel at the specified position is set
+     */
+    private isPixelSet;
+    private getCellPositions;
+    private getNeighborPosition;
+    private selectMultiPixelChar;
+    private selectHorizontalChar;
+    private selectDiagonalChar;
+    private selectIsolatedChar;
+    private selectSinglePixelChar;
+    /**
+     * Intelligently select ASCII character
+     * Select appropriate character based on 1x3 vertical pixels and adjacent column connections
+     */
+    private selectAsciiChar;
+    /**
+     * Determine the primary color for this character cell
+     */
+    private resolveColor;
+    renderCanvas(pixels: Pixel[][], width: number, height: number): RenderedLine[];
+}
+
+/**
+ * Terminal detection type definitions
+ *
+ * Define type interfaces for terminal capabilities and environment information
+ */
+/**
+ * Terminal capability information
+ *
+ * Describes features supported by the current terminal and the overall score
+ */
+interface TerminalCapabilities {
+    /** Whether UTF-8 encoding is supported */
+    supportsUtf8: boolean;
+    /** Whether Unicode characters are supported */
+    supportsUnicode: boolean;
+    /** Whether Braille characters are supported (U+2800-U+28FF) */
+    supportsBraille: boolean;
+    /** Whether Block Elements characters are supported (U+2580-U+259F) */
+    supportsBlockElements: boolean;
+    /** Whether colors are supported (16 colors or more) */
+    supportsColor: boolean;
+    /** Whether true color is supported (24-bit RGB) */
+    supportsTrueColor: boolean;
+    /** Comprehensive terminal capability score (0-100) */
+    score: number;
+}
+/**
+ * Environment information
+ *
+ * Terminal-related information extracted from process environment variables
+ */
+interface EnvironmentInfo {
+    /** Language environment variable (e.g. en_US.UTF-8) */
+    LANG?: string;
+    /** Terminal type (e.g. xterm-256color) */
+    TERM?: string;
+    /** Color support (e.g. truecolor) */
+    COLORTERM?: string;
+    /** Terminal program name (e.g. iTerm.app, Warp) */
+    TERM_PROGRAM?: string;
+    /** Terminal program version */
+    TERM_PROGRAM_VERSION?: string;
+}
+
+/**
+ * Terminal capabilities detector
+ *
+ * Automatically detect terminal-supported features by analyzing environment variables
+ */
+
+/**
+ * Terminal capabilities detector
+ *
+ * Analyze process environment variables to determine current terminal's supported character sets, colors, and other features
+ */
+declare class TerminalDetector {
+    /** Terminal whitelist supporting Braille characters (lowercase) */
+    private static readonly BRAILLE_SUPPORTED_TERMINALS;
+    /** Environment variable information */
+    private envInfo;
+    constructor(env?: NodeJS.ProcessEnv);
+    /**
+     * Extract relevant information from environment variables
+     * @param env - Environment variable object
+     * @returns Environment information
+     */
+    private extractEnvInfo;
+    /**
+     * Detect UTF-8 support
+     * @returns Whether UTF-8 is supported
+     */
+    private checkUtf8Support;
+    /**
+     * Detect Unicode support
+     * UTF-8 terminals usually support Unicode
+     * @returns Whether Unicode is supported
+     */
+    private checkUnicodeSupport;
+    /**
+     * Detect Braille character support
+     * Determine based on terminal program whitelist
+     * @returns Whether Braille characters are supported
+     */
+    private checkBrailleSupport;
+    /**
+     * Detect Block Elements character support
+     * Most terminals supporting Unicode also support Block Elements
+     * @returns Whether Block Elements are supported
+     */
+    private checkBlockElementsSupport;
+    /**
+     * Detect color support (16 colors or more)
+     * @returns Whether colors are supported
+     */
+    private checkColorSupport;
+    /**
+     * Detect true color support (24-bit RGB)
+     * @returns Whether true color is supported
+     */
+    private checkTrueColorSupport;
+    /**
+     * Calculate comprehensive terminal capability score (0-100)
+     * @returns Score
+     */
+    private calculateScore;
+    /**
+     * Detect terminal capabilities
+     * @returns Terminal capability information
+     */
+    detect(): TerminalCapabilities;
+    /**
+     * Get environment information
+     * @returns Environment information
+     */
+    getEnvironmentInfo(): EnvironmentInfo;
+}
+/**
+ * Global terminal detector instance
+ */
+declare const terminalDetector: TerminalDetector;
+
+/**
+ * Renderer Selector
+ *
+ * Automatically selects the optimal renderer based on terminal capabilities to achieve intelligent fallback
+ */
+
+/**
+ * Renderer Selector
+ *
+ * Automatically detects terminal capabilities and selects the optimal renderer
+ * Supports custom fallback chains and renderer caching
+ */
+declare class RendererSelector {
+    /** Terminal detector */
+    private detector;
+    constructor(detector?: TerminalDetector);
+    /**
+     * Creates a renderer instance of the specified type
+     * @param type - Renderer type
+     * @returns Renderer instance
+     */
+    private createRenderer;
+    /**
+     * Get renderer by type
+     * @param type - Renderer type
+     * @returns Renderer instance
+     */
+    getRenderer(type: RendererType): Renderer;
+    /**
+     * Check if the renderer meets terminal capability requirements
+     * @param renderer - Renderer instance
+     * @param capabilities - Terminal capabilities
+     * @returns Whether requirements are met
+     */
+    private isRendererSupported;
+    /**
+     * Automatically select the best renderer
+     *
+     * Try in the order of the priority chain, returning the first renderer that meets terminal capability requirements
+     * If none are satisfied, fallback to ASCII
+     *
+     * @param preferredChain - Priority chain (default: ['braille', 'block', 'ascii'])
+     * @returns Selected renderer instance
+     */
+    selectBest(preferredChain?: RendererType[]): Renderer;
+    /**
+     * Get terminal capability information
+     * @returns Terminal capabilities
+     */
+    getTerminalCapabilities(): TerminalCapabilities;
+}
+/**
+ * Global RendererSelector instance
+ */
+declare const rendererSelector: RendererSelector;
+
+/**
+ * ink-hud Context Provider
+ *
+ * Provide dependency injection, replacing the global singleton
+ */
+
+/**
+ * InkHud Context value
+ */
+interface InkHudContextValue {
+    /** Renderer selector */
+    selector: RendererSelector;
+    /** Get terminal capabilities */
+    getCapabilities: () => TerminalCapabilities;
+    /** Get renderer of specified type */
+    getRenderer: (type: RendererType) => Renderer;
+    /** Select best renderer */
+    selectBest: (chain?: RendererType[]) => Renderer;
+}
+/**
+ * InkHud Provider Props
+ */
+interface InkHudProviderProps {
+    /**
+     * Custom terminal detector
+     * For testing or simulating different terminal environments
+     */
+    detector?: TerminalDetector;
+    /**
+     * Force use of specified renderer
+     * Override automatic detection for testing or specific scenarios
+     */
+    forceRenderer?: RendererType;
+    children: React.ReactNode;
+}
+/**
+ * InkHud Context Provider
+ *
+ * Encapsulate renderer selection logic, supports dependency injection
+ *
+ * @example
+ * ```tsx
+ * // Standard usage (automatic detection)
+ * <InkHudProvider>
+ *     <MyApp />
+ * </InkHudProvider>
+ *
+ * // Inject mock for testing
+ * <InkHudProvider detector={mockDetector}>
+ *     <MyApp />
+ * </InkHudProvider>
+ *
+ * // Force ASCII renderer
+ * <InkHudProvider forceRenderer="ascii">
+ *     <MyApp />
+ * </InkHudProvider>
+ * ```
+ */
+declare const InkHudProvider: React.FC<InkHudProviderProps>;
+/**
+ * Get InkHud Context
+ *
+ * Even without a Provider, returns the default Context (using the global detector)
+ */
+declare function useInkHud(): InkHudContextValue;
+/**
+ * Get renderer selector
+ *
+ * Simplified Hook to directly get the selector
+ */
+declare function useRendererSelector(): RendererSelector;
+
+/**
+ * ThemeContext - Theme Context
+ *
+ * Provides unified color configuration, replacing hardcoded colors
+ */
+
+/**
+ * Semantic color configuration
+ */
+interface SemanticColors {
+    /** Success/Up */
+    success: string;
+    /** Error/Down */
+    error: string;
+    /** Warning */
+    warning: string;
+    /** Info */
+    info: string;
+    /** Secondary/Disabled */
+    muted: string;
+    /** Primary text */
+    text: string;
+    /** Secondary text */
+    textSecondary: string;
+}
+/**
+ * Theme configuration
+ */
+interface Theme {
+    /** Theme name */
+    name: string;
+    /** Series colors (for charts) */
+    palette: string[];
+    /** Semantic colors */
+    semantic: SemanticColors;
+    /** Heatmap gradient */
+    heatmapGradient: string[];
+}
+/**
+ * One Dark Theme (default)
+ */
+declare const ONE_DARK_THEME: Theme;
+/**
+ * Theme Provider Props
+ */
+interface ThemeProviderProps {
+    /** Custom theme (optional) */
+    theme?: Partial<Theme>;
+    children: React.ReactNode;
+}
+/**
+ * Theme Provider
+ *
+ * @example
+ * ```tsx
+ * <ThemeProvider>
+ *   <App />
+ * </ThemeProvider>
+ *
+ * // Custom theme
+ * <ThemeProvider theme={{ semantic: { success: '#00ff00' } }}>
+ *   <App />
+ * </ThemeProvider>
+ * ```
+ */
+declare const ThemeProvider: React.FC<ThemeProviderProps>;
+/**
+ * Get current theme
+ *
+ * @example
+ * ```tsx
+ * const theme = useTheme();
+ * <Text color={theme.semantic.success}>Success</Text>
+ * ```
+ */
+declare function useTheme(): Theme;
+/**
+ * Get semantic colors
+ *
+ * @example
+ * ```tsx
+ * const colors = useSemanticColors();
+ * <Text color={colors.error}>Error</Text>
+ * ```
+ */
+declare function useSemanticColors(): SemanticColors;
+
+/**
+ * Data scaling utility module
+ *
+ * Provides data normalization and linear scaling functions for mapping data to chart coordinate space
+ */
+/**
+ * Linear scale function
+ * Map value from input domain to output domain
+ *
+ * @param value - Value to scale
+ * @param domain - Input domain [min, max]
+ * @param range - Output range [min, max]
+ * @returns Scaled value
+ *
+ * @example
+ * linearScale(50, [0, 100], [0, 10]); // Returns 5
+ * linearScale(75, [0, 100], [0, 20]); // Returns 15
+ */
+declare function linearScale(value: number, domain: [number, number], range: [number, number]): number;
+/**
+ * Data normalization
+ * Map array data to [0, 1] interval
+ *
+ * @param data - Original data array
+ * @returns Normalized data array
+ *
+ * @example
+ * normalize([0, 50, 100]); // Returns [0, 0.5, 1]
+ * normalize([10, 20, 30]); // Returns [0, 0.5, 1]
+ */
+declare function normalize(data: number[]): number[];
+/**
+ * Scale data to specified range
+ * Map array data to specified output range
+ *
+ * @param data - Original data array
+ * @param range - Output range [min, max]
+ * @returns Scaled data array
+ *
+ * @example
+ * scaleToRange([0, 50, 100], [0, 10]); // Returns [0, 5, 10]
+ * scaleToRange([-10, 0, 10], [0, 100]); // Returns [0, 50, 100]
+ */
+declare function scaleToRange(data: number[], range: [number, number]): number[];
+/**
+ * Clamp value within specified range (clamp)
+ *
+ * @param value - Value to clamp
+ * @param min - Minimum value
+ * @param max - Maximum value
+ * @returns Clamped value
+ *
+ * @example
+ * clamp(5, 0, 10); // Returns 5
+ * clamp(-5, 0, 10); // Returns 0
+ * clamp(15, 0, 10); // Returns 10
+ */
+declare function clamp(value: number, min: number, max: number): number;
+
+/**
+ * Gradient tool module
+ *
+ * Use tinygradient and chalk to implement terminal color gradients
+ */
+/**
+ * Generate gradient color array
+ *
+ * @param colors - Start and end color array (supports hex, rgb, css color names)
+ * @param steps - Interpolation steps
+ * @returns Chalk color function array
+ *
+ * @example
+ * const gradient = createGradient(['#00f', '#0ff', '#0f0'], 10);
+ * gradient[0]('text'); // Blue
+ * gradient[9]('text'); // Green
+ */
+declare function createGradient(colors: string[], steps: number): Array<(text: string) => string>;
+/**
+ * Palette type
+ * Supports built-in palette names or custom color arrays
+ */
+type ColorPalette = 'one-dark' | 'one-dark-vivid' | string[];
+/**
+ * Assign different colors for data series
+ *
+ * @param seriesCount - Number of series
+ * @param palette - Palette configuration (default: 'one-dark')
+ * @returns Color array (hex format)
+ *
+ * @example
+ * const colors = assignColors(5);
+ * // Use Vivid variant
+ * const vividColors = assignColors(5, 'one-dark-vivid');
+ */
+declare function assignColors(seriesCount: number, palette?: ColorPalette): string[];
+/**
+ * Convert color string to chalk color function
+ *
+ * @param color - Color string (hex, css color names)
+ * @returns Chalk color function
+ *
+ * @example
+ * const colorFn = colorToChalk('#ff0000');
+ * console.log(colorFn('Red text'));
+ */
+declare function colorToChalk(color: string): (text: string) => string;
+
+/**
+ * Geometry calculation utility module
+ *
+ * Provides helper functions for calculating geometric shapes like circles and arcs
+ */
+/**
+ * Midpoint Circle Algorithm
+ * Calculate all points on the circle (8 symmetry points)
+ *
+ * @param centerX - Center x coordinate
+ * @param centerY - Center y coordinate
+ * @param radius - Radius
+ * @returns Array of coordinates for all points on circle
+ *
+ * @example
+ * const points = midpointCircle(50, 50, 20);
+ * points.forEach(([x, y]) => {
+ *     console.log(`Point coordinates: (${x}, ${y})`);
+ * });
+ */
+declare function midpointCircle(centerX: number, centerY: number, radius: number): Array<[number, number]>;
+/**
+ * Calculate point coordinates at specified angle on arc
+ * Using parametric equations: x = centerX + r * cos(θ), y = centerY + r * sin(θ)
+ *
+ * @param centerX - Center x coordinate
+ * @param centerY - Center y coordinate
+ * @param radius - Radius
+ * @param angle - Angle (radians)
+ * @returns Point coordinates [x, y]
+ *
+ * @example
+ * // Calculate the point at 45° (π/4 radians)
+ * const [x, y] = pointOnArc(50, 50, 20, Math.PI / 4);
+ */
+declare function pointOnArc(centerX: number, centerY: number, radius: number, angle: number): [number, number];
+/**
+ * Calculate multiple points on the arc
+ *
+ * @param centerX - Center x coordinate
+ * @param centerY - Center y coordinate
+ * @param radius - Radius
+ * @param startAngle - Start angle (radians)
+ * @param endAngle - End angle (radians)
+ * @param steps - Steps (default calculated based on radius)
+ * @returns Array of coordinates for all points on arc
+ *
+ * @example
+ * // Calculate arc points from 0° to 90°
+ * const points = arcPoints(50, 50, 20, 0, Math.PI / 2, 20);
+ */
+declare function arcPoints(centerX: number, centerY: number, radius: number, startAngle: number, endAngle: number, steps?: number): Array<[number, number]>;
+/**
+ * Convert angle from degrees to radians
+ *
+ * @param degrees - Angle (degrees)
+ * @returns Angle (radians)
+ *
+ * @example
+ * const radians = degreesToRadians(90); // π/2
+ */
+declare function degreesToRadians(degrees: number): number;
+/**
+ * Convert angle from radians to degrees
+ *
+ * @param radians - Angle (radians)
+ * @returns Angle (degrees)
+ *
+ * @example
+ * const degrees = radiansToDegrees(Math.PI / 2); // 90
+ */
+declare function radiansToDegrees(radians: number): number;
+/**
+ * Calculate distance between two points
+ *
+ * @param x1 - First point x coordinate
+ * @param y1 - First point y coordinate
+ * @param x2 - Second point x coordinate
+ * @param y2 - Second point y coordinate
+ * @returns Distance
+ *
+ * @example
+ * const distance = distanceBetweenPoints(0, 0, 3, 4); // 5
+ */
+declare function distanceBetweenPoints(x1: number, y1: number, x2: number, y2: number): number;
+
+/**
+ * Data downsampling module
+ *
+ * Provides downsampling algorithms for large datasets to display many data points in limited-width charts
+ */
+/**
+ * LTTB (Largest Triangle Three Buckets) algorithm
+ * An efficient data downsampling algorithm that preserves visually important data points
+ *
+ * Algorithm principles:
+ * 1. Always preserve first and last points
+ * 2. Divide intermediate data into multiple buckets
+ * 3. Select the point with largest triangle area in each bucket (forming largest triangle with adjacent points)
+ *
+ * @param data - Original data array
+ * @param threshold - Target number of data points
+ * @returns Downsampled data array
+ *
+ * @example
+ * const data = Array.from({ length: 1000 }, (_, i) => Math.sin(i / 10));
+ * const sampled = lttb(data, 100); // Downsample from 1000 points to 100 points
+ */
+declare function lttb(data: number[], threshold: number): number[];
+/**
+ * Simple fixed-interval downsampling
+ * Select one data point at fixed intervals
+ *
+ * @param data - Original data array
+ * @param threshold - Target number of data points
+ * @returns Downsampled data array
+ *
+ * @example
+ * const data = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+ * const sampled = fixedIntervalDownsampling(data, 5); // [1, 3, 5, 7, 10]
+ */
+declare function fixedIntervalDownsampling(data: number[], threshold: number): number[];
+/**
+ * Average Downsampling
+ * Divide data into multiple buckets, taking the average value for each bucket
+ *
+ * @param data - Original data array
+ * @param threshold - Target number of data points
+ * @returns Downsampled data array
+ *
+ * @example
+ * const data = [1, 2, 3, 4, 5, 6, 7, 8];
+ * const sampled = averageDownsampling(data, 4); // [1.5, 3.5, 5.5, 7.5]
+ */
+declare function averageDownsampling(data: number[], threshold: number): number[];
+/**
+ * Min-Max Downsampling
+ * Divide data into multiple buckets, preserving the Maximum and Minimum values for each bucket
+ * Suitable for preserving peaks and valleys in data
+ *
+ * @param data - Original data array
+ * @param threshold - Target number of data points (actual returned points will be 2x threshold)
+ * @returns Downsampled data array
+ *
+ * @example
+ * const data = [1, 5, 2, 8, 3, 6, 4, 7];
+ * const sampled = minMaxDownsampling(data, 4); // [1, 5, 2, 8, 3, 6, 4, 7]
+ */
+declare function minMaxDownsampling(data: number[], threshold: number): number[];
+
+/**
+ * Data smooth transition Hook module
+ *
+ * Provides smooth animation effects for data changes
+ */
+/**
+ * Easing function type
+ */
+type EasingFunction = (t: number) => number;
+/**
+ * Quadratic easing function (accelerate then decelerate)
+ * @param t - Progress (0-1)
+ * @returns Eased progress (0-1)
+ */
+declare function easeInOutQuad(t: number): number;
+/**
+ * Linear easing function (constant speed)
+ * @param t - Progress (0-1)
+ * @returns Eased progress (0-1)
+ */
+declare function easeLinear(t: number): number;
+/**
+ * Cubic ease-out function (decelerate)
+ * @param t - Progress (0-1)
+ * @returns Eased progress (0-1)
+ */
+declare function easeOutCubic(t: number): number;
+/**
+ * Cubic ease-in function (accelerate)
+ * @param t - Progress (0-1)
+ * @returns Eased progress (0-1)
+ */
+declare function easeInCubic(t: number): number;
+/**
+ * Data smooth transition Hook
+ * Smooth transition to new value when target changes
+ *
+ * @param targetValue - Target value
+ * @param duration - Transition duration (ms, default 300)
+ * @param easingFn - Easing function (default easeInOutQuad)
+ * @returns Current smooth value
+ *
+ * @example
+ * const smoothValue = useSmooth(cpuUsage, 500);
+ * return <LineChart series={[{ name: 'Value', data: [smoothValue] }]} />;
+ */
+declare function useSmooth(targetValue: number, duration?: number, easingFn?: EasingFunction): number;
+/**
+ * Array data smooth transition Hook
+ * Smooth transition to new data when target changes
+ *
+ * @param targetData - Target data array
+ * @param duration - Transition duration (ms, default 300)
+ * @param easingFn - Easing function (default easeInOutQuad)
+ * @returns Current smooth data array
+ *
+ * @example
+ * const smoothData = useSmoothArray(memoryData, 500);
+ * return <LineChart data={[{ name: 'Memory', data: smoothData }]} />;
+ */
+declare function useSmoothArray(targetData: number[], duration?: number, easingFn?: EasingFunction): number[];
+/**
+ * Throttling Hook
+ * Limit animation frame rate to avoid terminal flicker
+ *
+ * @param value - Current value
+ * @param fps - Target frame rate (default 30)
+ * @returns Throttled value
+ *
+ * @example
+ * const throttledValue = useThrottle(cpuUsage, 30);
+ */
+declare function useThrottle<T>(value: T, fps?: number): T;
+
+/**
+ * Common type definitions for Chart components
+ *
+ * Unified base property interface for all chart components
+ */
+
+/**
+ * Basic chart dimensions and renderer configuration
+ */
+interface BaseChartProps {
+    /** Chart width (character count) */
+    width?: number;
+    /** Chart height (character rows) */
+    height?: number;
+    /** Manually specify Renderer type */
+    renderer?: RendererType;
+    /** Custom renderer fallback chain */
+    rendererChain?: RendererType[];
+    /**
+     * Width offset
+     * @deprecated Recommend wrapping chart with `<Panel>`, Panel automatically handles border overhead
+     */
+    widthOffset?: number;
+    /**
+     * Height offset
+     * @deprecated Recommend wrapping chart with `<Panel>`, Panel automatically handles border overhead
+     */
+    heightOffset?: number;
+}
+/**
+ * Legend configuration
+ */
+interface LegendProps$1 {
+    /** Whether to show legend (default true) */
+    showLegend?: boolean;
+    /** Legend position (default 'right') */
+    legendPosition?: 'right' | 'bottom' | 'top';
+}
+/**
+ * Color configuration
+ */
+interface ColorProps {
+    /** Color array (auto-assigned if not specified) */
+    colors?: string[];
+    /** Palette name or custom color array */
+    colorPalette?: ColorPalette;
+}
+/**
+ * Axis configuration (shared by LineChart/AreaChart/BarChart)
+ */
+interface AxisProps$1 {
+    /** Whether to show axis (default true) */
+    showAxis?: boolean;
+    /** Whether to show X-axis (defaults to showAxis) */
+    showXAxis?: boolean;
+    /** Whether to show Y-axis (defaults to showAxis) */
+    showYAxis?: boolean;
+    /** X-axis label */
+    xAxisLabel?: string;
+    /** Y-axis label */
+    yAxisLabel?: string;
+    /** X-axis tick count (default 5) */
+    xTickCount?: number;
+    /** Y-axis tick count (default 5) */
+    yTickCount?: number;
+    /** X-axis tick formatter function */
+    xTickFormat?: (value: number) => string;
+    /** Y-axis tick formatter function */
+    yTickFormat?: (value: number) => string;
+    /** Whether to force X-axis ticks to be integers (default true) */
+    xIntegerScale?: boolean;
+    /** Whether to force Y-axis ticks to be integers (default false) */
+    yIntegerScale?: boolean;
+}
+/**
+ * Time series data configuration (shared by LineChart/AreaChart/BarChart)
+ */
+interface SeriesDataProps {
+    /** Multi-series data */
+    series?: Array<{
+        name: string;
+        data: number[];
+        color?: string;
+    }>;
+    /** Single-series data (simplified) */
+    data?: number[];
+    /** Single-series name (simplified) */
+    seriesName?: string;
+}
+/**
+ * Complete time series chart properties (shared by LineChart/AreaChart)
+ */
+type TimeSeriesChartProps = BaseChartProps & LegendProps$1 & ColorProps & AxisProps$1 & SeriesDataProps;
+
+/**
+ * LineChart - Basic line chart component
+ */
+
+/**
+ * LineChart component props
+ */
+type LineChartProps = TimeSeriesChartProps;
+declare const LineChart: React.FC<LineChartProps>;
+
+/**
+ * AreaChart - Basic area chart component
+ */
+
+/**
+ * AreaChart component props
+ */
+type AreaChartProps = TimeSeriesChartProps;
+declare const AreaChart: React.FC<AreaChartProps>;
+
+/**
+ * BarChart Basic bar chart component
+ */
+
+/**
+ * BarChart component props
+ */
+type BarChartProps = TimeSeriesChartProps & {
+    /** Orientation (default 'vertical') */
+    orientation?: 'vertical' | 'horizontal';
+};
+declare const BarChart: React.FC<BarChartProps>;
+
+/**
+ * PieChart Pie chart component
+ *
+ * Basic pie chart display with built-in legend
+ */
+
+/**
+ * PieChart data item
+ */
+interface PieChartDataItem {
+    /** Name */
+    name: string;
+    /** Value */
+    value: number;
+    /** Color (optional, auto-assigned if not specified) */
+    color?: string;
+}
+/**
+ * PieChart component props
+ */
+interface PieChartProps {
+    /**
+     * Data array - supports two formats:
+     * 1. Simplified mode: number[] (requires labels)
+     * 2. Detailed mode: PieChartDataItem[]
+     */
+    data?: number[] | PieChartDataItem[];
+    /**
+     * Label array (used in simplified mode)
+     * When used with data: number[], provides name for each value
+     */
+    labels?: string[];
+    /** Chart width (character count, default 30) */
+    width?: number;
+    /** Chart height (character lines, default 15) */
+    height?: number;
+    /** Outer radius (pixels, auto-calculated by default) */
+    radius?: number;
+    /** Aspect ratio correction (default 2) */
+    aspectRatio?: number;
+    /** Donut inner radius ratio (0-1, default 0) */
+    donutRatio?: number;
+    /** Whether to show percentage labels (default false) */
+    showLabels?: boolean;
+    /** Whether to show legend (default true) */
+    showLegend?: boolean;
+    /** Legend position (default 'right') */
+    legendPosition?: 'right' | 'bottom';
+    /** Color array (auto-assigned if not specified) */
+    colors?: string[];
+    /** Palette name or custom color array */
+    colorPalette?: ColorPalette;
+    /** Manually specify renderer type (optional) */
+    renderer?: RendererType;
+    /** Custom renderer fallback chain (default: ['braille', 'block', 'ascii']) */
+    rendererChain?: RendererType[];
+    /**
+     * Height offset
+     * @deprecated Recommend wrapping chart with `<Panel>`, Panel automatically handles border overhead
+     */
+    heightOffset?: number;
+    /**
+     * Width offset
+     * @deprecated Recommend wrapping chart with `<Panel>`, Panel automatically handles border overhead
+     */
+    widthOffset?: number;
+}
+/**
+ * PieChart Pie chart component
+ */
+declare const PieChart: React.FC<PieChartProps>;
+
+/**
+ * Sparkline - Mini trend chart component
+ */
+
+interface SparklineProps {
+    /** Array of data points */
+    data: number[];
+    /**
+     * Target width (character count)
+     * If number of data points exceeds width, will automatically use LTTB algorithm for downsampling
+     * If not provided, width will equal the number of data points
+     */
+    width?: number;
+    /** Minimum value (default: calculation from data) */
+    min?: number;
+    /** Maximum value (default: calculation from data) */
+    max?: number;
+    /** Color */
+    color?: string;
+    /** Rendering style (default: 'block') */
+    variant?: 'block' | 'braille' | 'ascii';
+}
+declare const Sparkline: React.FC<SparklineProps>;
+
+/**
+ * Coordinate axis component
+ *
+ * Used for X-axis and Y-axis display in charts
+ */
+
+/**
+ * Coordinate axis component props
+ */
+interface AxisProps {
+    /** Axis type */
+    type: 'x' | 'y';
+    /** Minimum data value */
+    min: number;
+    /** Maximum data value */
+    max: number;
+    /** Tick count (default 5) */
+    tickCount?: number;
+    /** Tick formatter function */
+    tickFormat?: (value: number) => string;
+    /** Axis label */
+    label?: string;
+    /** Axis length (character count) */
+    length: number;
+    /** Text color (default 'gray') */
+    color?: string;
+    /** Whether to show grid lines (default false) */
+    showGrid?: boolean;
+    /** Whether to force ticks to be integers (default false) */
+    integerScale?: boolean;
+}
+/**
+ * Coordinate axis component
+ *
+ * @example
+ * // X-axis
+ * <Axis type="x" min={0} max={100} length={50} label="Time" />
+ *
+ * // Y-axis
+ * <Axis type="y" min={0} max={100} length={10} label="Value" />
+ */
+declare const Axis: React.FC<AxisProps>;
+
+interface GridProps {
+    /** Number of columns in the grid (default: 12) */
+    columns?: number;
+    /** Gap between items (horizontal and vertical) */
+    gap?: number;
+    /**
+     * Total width of the grid in characters.
+     * If not provided, it will automatically use the terminal width (stdout.columns).
+     */
+    width?: number;
+    /**
+     * Width offset to subtract from the terminal width when auto-calculating.
+     * Use this to account for parent padding or borders.
+     * @deprecated Recommend wrapping content with `<Panel>`, which automatically handles border overhead
+     */
+    widthOffset?: number;
+    /**
+     * Default height for all rows/items in the grid.
+     * Can be overridden by individual GridItem height prop.
+     */
+    rowHeight?: number | string | undefined;
+    /** Children should be GridItem components */
+    children: React.ReactNode;
+}
+/**
+ * Grid Container
+ * Acts like a CSS Grid container, arranging items in columns.
+ */
+declare const Grid: React.FC<GridProps>;
+interface GridItemProps {
+    /** Number of columns to span (default: 1) */
+    span?: number;
+    /** Fixed height for this item */
+    height?: number | string;
+    /** Minimum height for this item */
+    minHeight?: number | string;
+    /** Overflow behavior */
+    overflow?: 'visible' | 'hidden';
+    children: React.ReactNode;
+}
+/**
+ * Grid Item
+ * A cell in the grid that spans a specific number of columns.
+ */
+declare const GridItem: React.FC<GridItemProps>;
+
+/**
+ * Legend component
+ *
+ * Used to display chart legend
+ */
+
+/**
+ * Legend item
+ */
+interface LegendItem {
+    /** Legend name */
+    name: string;
+    /** Legend color */
+    color: string;
+    /** Legend symbol (default '●') */
+    symbol?: string;
+}
+/**
+ * Legend component props
+ */
+interface LegendProps {
+    /** Legend items array */
+    items: LegendItem[];
+    /** Layout direction (default 'horizontal') */
+    position?: 'horizontal' | 'vertical';
+    /** Overall text color (defaults to each item's own color) */
+    color?: string;
+    /** Gap between legend items (default 2) */
+    gap?: number;
+}
+/**
+ * Legend component
+ *
+ * @example
+ * // Horizontal legend
+ * <Legend
+ *     items={[
+ *         { name: 'CPU', color: 'blue', symbol: '●' },
+ *         { name: 'Memory', color: 'green', symbol: '●' },
+ *     ]}
+ *     position="horizontal"
+ * />
+ *
+ * // Vertical legend
+ * <Legend
+ *     items={[
+ *         { name: 'Series 1', color: 'cyan' },
+ *         { name: 'Series 2', color: 'yellow' },
+ *     ]}
+ *     position="vertical"
+ * />
+ */
+declare const Legend: React.FC<LegendProps>;
+
+interface PanelProps {
+    /**
+     * Panel title
+     */
+    title?: string;
+    /**
+     * Title alignment
+     * @default 'left'
+     */
+    titleAlignment?: 'left' | 'center' | 'right';
+    /**
+     * Border style
+     * @default 'round'
+     */
+    borderStyle?: BoxProps['borderStyle'];
+    /**
+     * Border color
+     * @default 'white'
+     */
+    borderColor?: string;
+    /**
+     * Content padding
+     * @default 0
+     */
+    padding?: number;
+    /**
+     * Panel width
+     */
+    width?: number | string;
+    /**
+     * Panel height
+     */
+    height?: number | string;
+    /**
+     * Children (content)
+     */
+    children: React.ReactNode;
+}
+/**
+ * Panel - Card component with title and border
+ *
+ * Unified encapsulation of borders, titles, and padding, supporting various border styles.
+ */
+declare const Panel: React.FC<PanelProps>;
+
+interface GaugeProps {
+    /**
+     * Current value
+     */
+    value: number;
+    /**
+     * Minimum value
+     * @default 0
+     */
+    min?: number;
+    /**
+     * Maximum value
+     * @default 100
+     */
+    max?: number;
+    /**
+     * Progress bar width (character count), excluding percentage text
+     * @default 20
+     */
+    width?: number;
+    /**
+     * Fill color
+     * @default 'green'
+     */
+    color?: string;
+    /**
+     * Unfilled character color
+     * @default 'gray'
+     */
+    emptyColor?: string;
+    /**
+     * Whether to show percentage text
+     * @default true
+     */
+    showPercent?: boolean;
+    /**
+     * Rendering style
+     * - 'unicode': Use Unicode block characters (█░)
+     * - 'ascii': Use ASCII characters (#-)
+     * @default 'unicode'
+     */
+    variant?: 'unicode' | 'ascii';
+    /**
+     * Custom fill character (overrides variant setting)
+     */
+    fillChar?: string;
+    /**
+     * Custom unfilled character (overrides variant setting)
+     */
+    emptyChar?: string;
+    /**
+     * Prefix label
+     */
+    label?: string;
+}
+/**
+ * Gauge - Gauge/progress bar component
+ *
+ * Display progress or load of a single metric.
+ * Style examples:
+ * - unicode: [██████░░░░] 60%
+ * - ascii:   [######----] 60%
+ */
+declare const Gauge: React.FC<GaugeProps>;
+
+/**
+ * Multi-Style Big Fonts for BigNumber Component
+ *
+ * Supports three rendering styles:
+ * - block: Unicode Block Elements (█▀▄)
+ * - braille: Braille patterns (⠿)
+ * - ascii: Pure ASCII characters
+ */
+type FontStyle = 'block' | 'braille' | 'ascii';
+
+interface BigNumberProps {
+    /**
+     * Main value
+     */
+    value: string | number;
+    /**
+     * Subtitle/label
+     */
+    label?: string;
+    /**
+     * Color
+     * @default 'white'
+     */
+    color?: string;
+    /**
+     * Trend direction (for rendering arrows)
+     */
+    trendDirection?: 'up' | 'down' | 'neutral';
+    /**
+     * Trend label (e.g., "12%")
+     */
+    trendLabel?: string;
+    /**
+     * Trend arrow style
+     * - 'unicode': Use Unicode arrows
+     * - 'ascii': Use ASCII characters
+     * @default 'unicode'
+     */
+    variant?: 'unicode' | 'ascii';
+    /**
+     * Large font style
+     * - 'block': Block Elements characters (default)
+     * - 'braille': Braille Dot Matrix characters
+     * - 'ascii': Pure ASCII characters
+     * @default 'block'
+     */
+    fontStyle?: FontStyle;
+    /**
+     * Alignment
+     * @default 'center'
+     */
+    align?: 'left' | 'center' | 'right';
+}
+/**
+ * BigNumber - Key metric card component
+ *
+ * Display core KPIs with large font for main value, supports subtitle and trend indicators.
+ */
+declare const BigNumber: React.FC<BigNumberProps>;
+
+interface HeatmapProps {
+    /**
+     * Data matrix (2D array)
+     * e.g. rows x cols
+     */
+    data: number[][];
+    /**
+     * Color gradient (from low to high)
+     * Defaults to theme's heatmapGradient
+     */
+    colors?: string[];
+    /**
+     * Empty/zero value color (if not handled in gradient)
+     */
+    emptyColor?: string;
+    /**
+     * Rendering style
+     * - 'unicode': Use Unicode Blocks character (■)
+     * - 'ascii': Use ASCII characters (#)
+     * @default 'unicode'
+     */
+    variant?: 'unicode' | 'ascii';
+    /**
+     * Custom character (overrides variant setting)
+     */
+    char?: string;
+}
+declare const Heatmap: React.FC<HeatmapProps>;
+
+/**
+ * LogStream - Log stream display component
+ *
+ * Pure log display component, without borders and title.
+ * If borders are needed, please use the <Panel><LogStream /></Panel> pattern.
+ */
+
+interface LogStreamProps {
+    /**
+     * Array of log strings
+     */
+    logs: string[];
+    /**
+     * Maximum retained lines (counted from end)
+     * @default 100
+     */
+    maxLines?: number;
+    /**
+     * Display height (number of lines)
+     * If not provided, will adapt to content (but not exceed maxLines)
+     */
+    height?: number;
+    /**
+     * Display width (character count)
+     * If not provided, will adapt to parent container
+     */
+    width?: number;
+}
+/**
+ * LogStream - Scrolling log viewer component
+ *
+ * Features:
+ * - Automatically display latest logs (render tail)
+ * - Intelligently parse timestamps and log levels
+ * - Use icons and colors to distinguish levels
+ * - Support maximum line limit
+ */
+declare const LogStream: React.FC<LogStreamProps>;
+
+interface TableColumn<T> {
+    /**
+     * Header title
+     */
+    header: string;
+    /**
+     * Data accessor key (if property of T) or render function
+     */
+    accessor: keyof T | ((item: T) => React.ReactNode);
+    /**
+     * Optional fixed width (if not provided, auto-calculated)
+     */
+    width?: number;
+    /**
+     * Alignment
+     * @default 'left'
+     */
+    align?: 'left' | 'right' | 'center';
+}
+interface TableProps<T> {
+    /**
+     * Data array
+     */
+    data: T[];
+    /**
+     * Column definitions
+     */
+    columns: TableColumn<T>[];
+    /**
+     * Currently sorted column key (matches matches column header or some ID? Let's use header/index for simplicity or separate ID)
+     * For simplicity, let's match 'header' string or an index.
+     * Let's use the index of the column for simplicity in this TUI context, or match header string.
+     */
+    sortColumn?: number | string;
+    /**
+     * Sort direction
+     */
+    sortDirection?: 'asc' | 'desc';
+    /**
+     * Enable zebra striping
+     * @default false
+     */
+    zebra?: boolean;
+    /**
+     * Callback when a column header is activated (sorted)
+     */
+    onSort?: (column: TableColumn<T>, index: number) => void;
+}
+/**
+ * Table - Data table with interactive sort headers
+ */
+declare const Table: <T>({ data, columns, sortColumn, sortDirection, zebra, onSort, }: TableProps<T>) => React.JSX.Element;
+
+export { AreaChart, type AreaChartProps, AsciiRenderer, Axis, type AxisProps, BarChart, type BarChartProps, BigNumber, type BigNumberProps, BlockRenderer, BrailleRenderer, type EasingFunction, type EnvironmentInfo, Gauge, type GaugeProps, Grid, GridItem, type GridItemProps, type GridProps, Heatmap, type HeatmapProps, type InkHudContextValue, InkHudProvider, type InkHudProviderProps, Legend, type LegendItem, type LegendProps, LineChart, type LineChartProps, LogStream, type LogStreamProps, ONE_DARK_THEME, Panel, type PanelProps, PieChart, type PieChartDataItem, type PieChartProps, Renderer, type RendererMetadata, type RendererResolution, RendererSelector, type RendererType, type SemanticColors, Sparkline, type SparklineProps, Table, type TableColumn, type TableProps, type TerminalCapabilities, TerminalDetector, type Theme, ThemeProvider, arcPoints, assignColors, averageDownsampling, clamp, colorToChalk, createGradient, degreesToRadians, distanceBetweenPoints, easeInCubic, easeInOutQuad, easeLinear, easeOutCubic, fixedIntervalDownsampling, linearScale, lttb, midpointCircle, minMaxDownsampling, normalize, pointOnArc, radiansToDegrees, rendererSelector, scaleToRange, terminalDetector, useInkHud, useRendererSelector, useSemanticColors, useSmooth, useSmoothArray, useTheme, useThrottle };