@termuijs/widgets 0.1.3 → 0.1.5

package/dist/index.d.cts

@@ -1,3 +1,4 @@
+import * as _termuijs_core from '@termuijs/core';
 import { Style, Rect, EventEmitter, KeyEvent, MouseEvent, LayoutNode, Screen, Color } from '@termuijs/core';
 
 /**
@@ -190,6 +191,293 @@ declare class LogView extends Widget {
     private _getLineColor;
 }
 
+interface TreeNode {
+    label: string;
+    children?: TreeNode[];
+    expanded?: boolean;
+    data?: unknown;
+}
+interface TreeOptions {
+    nodes: TreeNode[];
+    onSelect?: (node: TreeNode, path: number[]) => void;
+    indent?: number;
+}
+interface VisibleEntry {
+    node: TreeNode;
+    depth: number;
+    path: number[];
+}
+/**
+ * Tree — a collapsible tree widget for displaying hierarchical data.
+ *
+ * Supports:
+ * - Expand/collapse of parent nodes
+ * - Keyboard navigation (ArrowUp/Down/Left/Right, j/k/h/l, Home/End)
+ * - Enter/Space to toggle or select
+ * - onSelect callback for leaf nodes
+ * - Unicode and ASCII fallback symbols
+ * - Scrolling when tree exceeds visible height
+ */
+declare class Tree extends Widget {
+    private _nodes;
+    private _onSelect?;
+    protected _indent: number;
+    protected _selectedIndex: number;
+    protected _scrollOffset: number;
+    protected _visibleNodes: VisibleEntry[];
+    constructor(options: TreeOptions, style?: Partial<Style>);
+    get selectedIndex(): number;
+    get selectedNode(): TreeNode | undefined;
+    setNodes(nodes: TreeNode[]): void;
+    /** Move cursor up one visible row */
+    movePrev(): void;
+    /** Move cursor down one visible row */
+    moveNext(): void;
+    /** Go to first visible node */
+    moveFirst(): void;
+    /** Go to last visible node */
+    moveLast(): void;
+    /** Expand the selected node (if it's a collapsed parent) */
+    expand(): void;
+    /** Collapse the selected node, or move to parent if already collapsed/leaf */
+    collapse(): void;
+    /** Toggle expand/collapse (parent) or call onSelect (leaf) */
+    toggle(): void;
+    /**
+     * Handle a key event. Call this from your app's key-routing logic
+     * when this widget is focused.
+     */
+    handleKey(key: string): void;
+    protected _renderSelf(screen: Screen): void;
+    /** Rebuild the flat visible-node list from the tree */
+    private _buildVisibleNodes;
+    /** Ensure scroll keeps the selected index in view */
+    private _clampScroll;
+}
+
+type JSONNodeType = 'null' | 'boolean' | 'number' | 'string' | 'array' | 'object' | 'unknown';
+interface JSONNodeData {
+    type: JSONNodeType;
+    /** Original key (if any) that prefixes the label */
+    key?: string;
+    /** Raw primitive value (for non-container nodes) */
+    value?: unknown;
+}
+interface JSONViewOptions {
+    /** The JSON value to display */
+    data: unknown;
+    /** Callback when a leaf node is selected */
+    onSelect?: (node: TreeNode, path: number[]) => void;
+    /** Spaces per indent level (default: 2) */
+    indent?: number;
+}
+/**
+ * Convert any JSON-compatible value to a TreeNode, optionally prefixed
+ * by `key` (the property name or array index in the parent container).
+ */
+declare function jsonToTree(value: unknown, key?: string): TreeNode;
+/**
+ * JSONView — a syntax-colored, collapsible JSON viewer.
+ *
+ * Extends `Tree` and overrides `_renderSelf` to colorize each row:
+ * - Key portion (the `"key: "` prefix) is rendered in cyan
+ * - Value portion is colored by JSON type:
+ *   - string  → green
+ *   - number  → yellow
+ *   - boolean / null → magenta
+ *   - object `{n}` / array `[n]` → white (default)
+ *
+ * Usage:
+ * ```ts
+ * const view = new JSONView({ data: { name: 'Alice', age: 30 } });
+ * view.updateRect({ x: 0, y: 0, width: 60, height: 20 });
+ * view.render(screen);
+ * ```
+ */
+declare class JSONView extends Tree {
+    constructor(options: JSONViewOptions, style?: Partial<Style>);
+    /**
+     * Replicate Tree's _renderSelf but colorize key/value segments.
+     * We access the private state via `(this as any)` since Tree doesn't
+     * expose those fields publicly — the tradeoff of extending vs composing.
+     */
+    protected _renderSelf(screen: Screen): void;
+}
+
+interface DiffLine {
+    type: 'add' | 'remove' | 'context';
+    content: string;
+    lineNo?: number;
+}
+interface DiffViewOptions {
+    lines: DiffLine[];
+    showLineNumbers?: boolean;
+    gutterWidth?: number;
+}
+/**
+ * DiffView — a scrollable unified diff viewer with +/- line coloring.
+ *
+ * Supports:
+ * - Gutter with optional right-aligned line numbers (dim)
+ * - '+' prefix for added lines (green fg)
+ * - '-' prefix for removed lines (red fg)
+ * - ' ' prefix for context lines (dim fg)
+ * - Keyboard scrolling: ArrowUp/Down, j/k, PageUp/PageDown, Home/End
+ */
+declare class DiffView extends Widget {
+    private _lines;
+    private _scrollOffset;
+    private _showLineNumbers;
+    private _gutterWidth;
+    constructor(options: DiffViewOptions, style?: Partial<Style>);
+    setLines(lines: DiffLine[]): void;
+    protected _renderSelf(screen: Screen): void;
+    handleKey(key: string): void;
+}
+
+interface StreamingTextOptions {
+    /** Full text content */
+    text: string;
+    /** Cursor character. Default: '▋' */
+    cursor?: string;
+    /** Characters to reveal per tick (0 = show all immediately). Default: 0 */
+    speed?: number;
+    /** Cursor blink interval in ms. Default: 530 */
+    blinkInterval?: number;
+}
+/**
+ * StreamingText — renders text that "streams in" token by token with a blinking cursor.
+ *
+ * Useful for displaying AI response streams or typewriter-style text effects.
+ *
+ * - When `speed === 0`: shows full text immediately, cursor blinks at end.
+ * - When `speed > 0`: reveals `speed` chars per `tick()` call until complete.
+ * - Cursor blinks every `blinkInterval` ms via the shared timer pool.
+ */
+declare class StreamingText extends Widget {
+    private _text;
+    private _cursor;
+    private _speed;
+    private _blinkInterval;
+    /** Number of characters currently revealed (used when speed > 0) */
+    private _revealed;
+    private _cursorVisible;
+    private _blinkUnsub?;
+    constructor(options: StreamingTextOptions, style?: Partial<Style>);
+    /** Replace text content and reset the revealed counter to 0. */
+    setText(text: string): void;
+    /**
+     * Advance `_revealed` by `speed` characters.
+     * Call this from an external tick/render loop when `speed > 0`.
+     */
+    tick(): void;
+    /** Returns true when all text has been revealed. */
+    isComplete(): boolean;
+    /** Lifecycle: start the blink timer (only when motion is enabled). */
+    mount(): void;
+    /** Lifecycle: stop the blink timer. */
+    unmount(): void;
+    protected _renderSelf(screen: Screen): void;
+}
+
+type MessageRole = 'user' | 'assistant' | 'system' | 'tool';
+interface ChatMessageOptions {
+    role: MessageRole;
+    content: string;
+    timestamp?: Date;
+}
+/**
+ * ChatMessage — displays a single chat message with a colored role badge
+ * and word-wrapped content text.
+ *
+ * Layout:
+ *   Row 0: [Role badge] (colored)   optional timestamp (dim, right-aligned)
+ *   Row 1..N: content text, word-wrapped, indented 2 spaces
+ */
+declare class ChatMessage extends Widget {
+    private _role;
+    private _content;
+    private _timestamp?;
+    constructor(options: ChatMessageOptions, style?: Partial<Style>);
+    /** Update the message content and mark dirty. */
+    setContent(content: string): void;
+    /** Update the message role and mark dirty. */
+    setRole(role: MessageRole): void;
+    protected _renderSelf(screen: Screen): void;
+}
+
+type ToolCallStatus = 'pending' | 'running' | 'done' | 'error';
+interface ToolCallOptions {
+    name: string;
+    args: Record<string, unknown>;
+    result?: unknown;
+    status: ToolCallStatus;
+    collapsed?: boolean;
+}
+interface ToolApprovalOptions extends ToolCallOptions {
+    onApprove?: () => void;
+    onDeny?: () => void;
+}
+/**
+ * ToolCall — displays an AI tool invocation with status indicator,
+ * tool name, arguments, and optional result.
+ *
+ * Layout (expanded):
+ *   Row 0: ▶/▼ tool_name [status-symbol] [status-label]
+ *   Row 1+: "  arg: value" (one per arg, 2-space indent)
+ *   (if done/error and result present): "  result: ..."
+ *
+ * Space or Enter toggles collapsed/expanded state.
+ */
+declare class ToolCall extends Widget {
+    protected _name: string;
+    protected _args: Record<string, unknown>;
+    protected _result: unknown;
+    protected _status: ToolCallStatus;
+    protected _collapsed: boolean;
+    constructor(options: ToolCallOptions, style?: Partial<Style>);
+    setStatus(status: ToolCallStatus): void;
+    setResult(result: unknown): void;
+    collapse(): void;
+    expand(): void;
+    handleKey(key: string): void;
+    protected _renderSelf(screen: Screen): void;
+}
+/**
+ * ToolApproval — extends ToolCall with an approval prompt row.
+ * When focused, shows "[y] Approve  [n] Deny" after the args/result.
+ * y/Enter calls onApprove; n/Escape calls onDeny.
+ */
+declare class ToolApproval extends ToolCall {
+    private _onApprove?;
+    private _onDeny?;
+    constructor(options: ToolApprovalOptions, style?: Partial<Style>);
+    protected _renderSelf(screen: Screen): void;
+    handleKey(key: string): void;
+}
+
+interface ScrollRange {
+    start: number;
+    end: number;
+    offsetPx: number;
+}
+/**
+ * Compute visible range for fixed-height items.
+ * @param scrollOffset - first visible item index (scroll position in items, NOT pixels)
+ * @param viewportItems - number of items visible in the viewport
+ * @param itemCount - total number of items
+ * @param overscan - extra items to render beyond viewport edges (default: 2)
+ */
+declare function computeRange(scrollOffset: number, viewportItems: number, itemCount: number, overscan?: number): ScrollRange;
+/**
+ * Compute visible range for variable-height items.
+ * @param scrollPx - scroll position in pixels
+ * @param viewportPx - viewport height in pixels
+ * @param sizes - array of item heights in pixels
+ * @param overscan - extra items to render (default: 2)
+ */
+declare function computeVariableRange(scrollPx: number, viewportPx: number, sizes: number[], overscan?: number): ScrollRange;
+
 interface ListItem {
     label: string;
     value: string;
@@ -335,6 +623,60 @@ declare class VirtualList extends Widget {
     private _clampScroll;
 }
 
+interface Command {
+    id: string;
+    label: string;
+    description?: string;
+    action: () => void;
+}
+interface CommandPaletteOptions {
+    commands: Command[];
+    onClose?: () => void;
+    /** Placeholder shown when query is empty. Default: 'Type to search...' */
+    placeholder?: string;
+    /** Max number of commands shown at once. Default: 8 */
+    maxVisible?: number;
+}
+/**
+ * CommandPalette — a fuzzy-search overlay widget.
+ *
+ * Renders a floating panel with:
+ * - Row 0: `> ` + query text (or placeholder when empty)
+ * - Rows 1..N: filtered command list with label + description
+ *
+ * Key bindings:
+ * - Printable chars: append to query
+ * - Backspace: delete last query character
+ * - ArrowUp / k: move selection up
+ * - ArrowDown / j: move selection down
+ * - Enter: execute selected command
+ * - Escape: call onClose
+ */
+declare class CommandPalette extends Widget {
+    private _commands;
+    private _filtered;
+    private _query;
+    private _selectedIndex;
+    private _options;
+    constructor(options: CommandPaletteOptions, style?: Partial<Style>);
+    /** Update the full command list and re-filter. */
+    setCommands(commands: Command[]): void;
+    /**
+     * Reset query, re-filter all commands, reset selection.
+     * Call this when opening the palette.
+     */
+    open(): void;
+    /** Current query string. */
+    getQuery(): string;
+    /** Filter commands based on current query (case-insensitive substring). */
+    private _filter;
+    private _executeSelected;
+    private _moveUp;
+    private _moveDown;
+    handleKey(key: string): void;
+    protected _renderSelf(screen: Screen): void;
+}
+
 interface TableColumn {
     /** Column header label */
     header: string;
@@ -503,6 +845,137 @@ declare class BarChart extends Widget {
     private _renderHorizontal;
 }
 
+interface GridOptions {
+    /** Number of equal-width columns */
+    columns: number;
+    /** Gap between items in both directions (default: 1) */
+    gap?: number;
+    /** Row gap override (overrides gap for rows) */
+    rowGap?: number;
+    /** Column gap override (overrides gap for columns) */
+    colGap?: number;
+}
+/**
+ * Grid — a CSS-Grid-like layout widget.
+ *
+ * Items fill left-to-right, wrapping to a new row every `columns` items.
+ * Internally creates a column-flex Box per row, each with equal-flex-grow items.
+ *
+ * The `addChild()` override means the reconciler's generic child-adding
+ * loop works without any special casing.
+ */
+declare class Grid extends Widget {
+    private _columns;
+    private _colGap;
+    private _rowGap;
+    private _rows;
+    private _itemCount;
+    constructor(style: Partial<Style>, options: GridOptions);
+    protected _renderSelf(_screen: Screen): void;
+    /**
+     * Add a widget to the grid. Items fill left-to-right,
+     * wrapping to a new row automatically every `columns` items.
+     * Overrides Widget.addChild so the reconciler generic loop works unchanged.
+     */
+    addChild(widget: Widget): void;
+    /** Add an item explicitly (alias for addChild) */
+    addItem(widget: Widget): void;
+    /** Remove all items and reset the grid */
+    clearItems(): void;
+}
+
+interface ScrollViewOptions {
+    /** Total height of content in rows */
+    contentHeight?: number;
+    /** Show scrollbar indicator on right edge */
+    showScrollbar?: boolean;
+}
+/**
+ * ScrollView — a height-bounded scrollable container.
+ *
+ * Children are rendered with a vertical offset applied (scrolling).
+ * Responds to up/down arrow keys and Page Up/Page Down.
+ */
+declare class ScrollView extends Widget {
+    private _scrollOffset;
+    private _contentHeight;
+    private _showScrollbar;
+    constructor(style?: Partial<Style>, opts?: ScrollViewOptions);
+    /** Set the total content height (in rows) */
+    setContentHeight(h: number): void;
+    /** Get current scroll offset */
+    get scrollOffset(): number;
+    /** Scroll by delta rows */
+    scrollBy(delta: number): void;
+    /** Scroll to absolute offset */
+    scrollTo(offset: number): void;
+    private _clampOffset;
+    /** Handle keyboard navigation */
+    onKey(event: KeyEvent): void;
+    render(screen: Screen): void;
+    private _renderScrollbar;
+    protected _renderSelf(_screen: Screen): void;
+}
+
+interface CenterOptions {
+    /** Center horizontally (default: true) */
+    horizontal?: boolean;
+    /** Center vertically (default: true) */
+    vertical?: boolean;
+}
+/**
+ * Center — centers a single child widget horizontally and/or vertically.
+ *
+ * Computes centering offsets at render time from the child's measured size.
+ */
+declare class Center extends Widget {
+    private _horizontal;
+    private _vertical;
+    constructor(style?: Partial<Style>, opts?: CenterOptions);
+    protected _renderSelf(_screen: Screen): void;
+    render(screen: Screen): void;
+}
+
+interface CardOptions {
+    /** Optional title shown in the top border */
+    title?: string;
+    /** Color for the border and title */
+    borderColor?: Color;
+}
+/**
+ * Card — a bordered container with an optional title in the top border.
+ *
+ * Like a Box with border + padding, but supports embedding a title string
+ * directly in the top border line.
+ */
+declare class Card extends Widget {
+    private _title;
+    private _borderColor?;
+    constructor(style?: Partial<Style>, opts?: CardOptions);
+    setTitle(title: string): void;
+    protected _renderSelf(screen: Screen): void;
+}
+
+interface ColumnsOptions {
+    /** Gap between columns in cells (default: 1) */
+    gap?: number;
+}
+/**
+ * Columns — splits available width evenly across child widgets.
+ *
+ * Children are laid out side-by-side with equal flex-grow.
+ * Internally uses a flex-row Box; the addChild override applies
+ * flexGrow:1 to each child so the reconciler's generic loop works.
+ */
+declare class Columns extends Widget {
+    private _inner;
+    constructor(style?: Partial<Style>, opts?: ColumnsOptions);
+    addChild(widget: Widget): void;
+    removeChild(widget: Widget): void;
+    clearChildren(): void;
+    protected _renderSelf(_screen: Screen): void;
+}
+
 interface ProgressBarOptions {
     /** Current value (0–1) */
     value?: number;
@@ -543,6 +1016,49 @@ declare class ProgressBar extends Widget {
     protected _renderSelf(screen: Screen): void;
 }
 
+/**
+ * A single progress item in MultiProgress
+ */
+interface ProgressItem {
+    label: string;
+    value: number;
+    color?: Color;
+}
+/**
+ * Options for MultiProgress widget
+ */
+interface MultiProgressOptions {
+    items: ProgressItem[];
+    labelWidth?: number;
+    showValues?: boolean;
+}
+/**
+ * MultiProgress — stacks multiple labeled progress bars in a vertical list.
+ *
+ * Each item renders on its own row with a label, bar, and optional percentage.
+ *
+ * Supports:
+ * - Multiple items with individual colors
+ * - Custom label column width
+ * - Optional percentage display
+ * - Smooth animation-ready value changes
+ */
+declare class MultiProgress extends Widget {
+    private _items;
+    private _labelWidth;
+    private _showValues;
+    constructor(options: MultiProgressOptions, style?: Partial<Style>);
+    /**
+     * Replace all items and mark dirty
+     */
+    setItems(items: ProgressItem[]): void;
+    /**
+     * Update a single item's value
+     */
+    updateItem(index: number, value: number): void;
+    protected _renderSelf(screen: Screen): void;
+}
+
 /**
  * Built-in spinner frame sets.
  */
@@ -578,6 +1094,7 @@ declare class Spinner extends Widget {
     private _color;
     private _lastTick;
     private _elapsed;
+    private _timerUnsub?;
     constructor(style?: Partial<Style>, options?: SpinnerOptions);
     /** Update the spinner label */
     setLabel(label: string): void;
@@ -586,6 +1103,10 @@ declare class Spinner extends Widget {
      * Call this with a delta (ms) from the render loop.
      */
     tick(deltaMs: number): void;
+    /** Lifecycle: start the frame-advance timer (only when motion is enabled). */
+    mount(): void;
+    /** Lifecycle: stop the frame-advance timer. */
+    unmount(): void;
     protected _renderSelf(screen: Screen): void;
 }
 
@@ -621,4 +1142,282 @@ declare class Scrollbar extends Widget {
     protected _renderSelf(screen: Screen): void;
 }
 
-export { type Bar, BarChart, type BarChartDirection, type BarChartOptions, type BarGroup, Box, Gauge, type GaugeOptions, List, type ListItem, LogView, type LogViewOptions, ProgressBar, type ProgressBarOptions, SPINNER_FRAMES, Scrollbar, type ScrollbarOptions, type ScrollbarOrientation, Sparkline, type SparklineOptions, Spinner, type SpinnerOptions, StatusIndicator, type StatusIndicatorOptions, Table, type TableColumn, type TableOptions, type TableRow, Text, TextInput, type TextProps, VirtualList, type VirtualListOptions, Widget, type WidgetEvents };
+interface SkeletonOptions {
+    /** Animation style: 'pulse' alternates two chars; 'shimmer' scrolls a highlight band */
+    variant?: 'pulse' | 'shimmer';
+    /** Animation interval in ms (default: 600) */
+    intervalMs?: number;
+    /** Characters for pulse: [dim, bright]. Default: ['░', '▒'] (ASCII fallback: ['-', '#']) */
+    chars?: [string, string];
+    /** Color for the bright state (optional) */
+    color?: Color;
+}
+/**
+ * Skeleton — animated loading placeholder.
+ *
+ * Supports:
+ * - 'pulse' variant: alternates between dim and bright fill characters
+ * - 'shimmer' variant: scrolls a bright band (~20% width) across the widget
+ * - Automatic ASCII fallback when unicode is unavailable
+ * - No animation when caps.motion is false (static frame 0)
+ */
+declare class Skeleton extends Widget {
+    private _frame;
+    private _shimmerPos;
+    private _unsub?;
+    private _chars;
+    private _variant;
+    private _intervalMs;
+    constructor(style?: Partial<Style>, options?: SkeletonOptions);
+    unmount(): void;
+    protected _renderSelf(screen: Screen): void;
+}
+
+type StatusVariant = 'success' | 'error' | 'warning' | 'info';
+interface StatusMessageOptions {
+    /** Variant determines icon and color */
+    variant?: StatusVariant;
+    /** Override the icon character */
+    icon?: string;
+}
+/**
+ * StatusMessage — a single-line status indicator.
+ *
+ * Renders an icon (✓/✗/⚠/ℹ) followed by a message, colored by variant.
+ */
+declare class StatusMessage extends Widget {
+    private _message;
+    private _variant;
+    private _icon?;
+    constructor(message: string, style?: Partial<Style>, opts?: StatusMessageOptions);
+    setMessage(message: string): void;
+    setVariant(variant: StatusVariant): void;
+    protected _renderSelf(screen: Screen): void;
+}
+
+interface BannerOptions {
+    /** Variant determines border color */
+    variant?: StatusVariant;
+    /** Title displayed on first line in bold */
+    title?: string;
+    /** Body text */
+    body?: string;
+}
+/**
+ * Banner — full-width alert with title and body text.
+ *
+ * Shows a bordered box with a bold title line and body text,
+ * colored according to variant. The border is drawn manually
+ * to use the variant color.
+ */
+declare class Banner extends Widget {
+    private _variant;
+    private _title;
+    private _body;
+    constructor(style?: Partial<Style>, opts?: BannerOptions);
+    setTitle(title: string): void;
+    setBody(body: string): void;
+    setVariant(variant: StatusVariant): void;
+    protected _renderSelf(screen: Screen): void;
+}
+
+interface KeyValuePair {
+    key: string;
+    value: string;
+}
+interface KeyValueOptions {
+    /** Separator between key and value (default: ': ') */
+    separator?: string;
+    /** Color for keys */
+    keyColor?: _termuijs_core.Color;
+    /** Color for values */
+    valueColor?: _termuijs_core.Color;
+}
+/**
+ * KeyValue — aligned key: value pairs.
+ *
+ * Keys are right-aligned to the width of the longest key.
+ * Values follow after the separator.
+ */
+declare class KeyValue extends Widget {
+    private _pairs;
+    private _separator;
+    private _keyColor?;
+    private _valueColor?;
+    constructor(pairs: Array<KeyValuePair> | Record<string, string>, style?: Partial<Style>, opts?: KeyValueOptions);
+    setPairs(pairs: Array<KeyValuePair> | Record<string, string>): void;
+    protected _renderSelf(screen: Screen): void;
+}
+
+interface SidebarItem {
+    label: string;
+    badge?: string;
+    active?: boolean;
+}
+interface SidebarOptions {
+    /** Whether the sidebar is collapsed */
+    collapsed?: boolean;
+    /** Collapsed width in cells (default: 3) */
+    collapsedWidth?: number;
+    /** Active item highlight color */
+    activeColor?: _termuijs_core.Color;
+    /** Badge color */
+    badgeColor?: _termuijs_core.Color;
+}
+/**
+ * Sidebar — a vertical list of navigation items with optional badges.
+ *
+ * Supports active item highlighting and collapsible mode.
+ */
+declare class Sidebar extends Widget {
+    private _items;
+    private _collapsed;
+    private _collapsedWidth;
+    private _activeColor;
+    private _badgeColor;
+    constructor(items: SidebarItem[], style?: Partial<Style>, opts?: SidebarOptions);
+    setItems(items: SidebarItem[]): void;
+    setCollapsed(collapsed: boolean): void;
+    toggle(): void;
+    get isCollapsed(): boolean;
+    protected _renderSelf(screen: Screen): void;
+}
+
+interface LineChartOptions {
+    /** Color of the plotted points/lines */
+    color?: Color;
+    /** Show Y-axis labels */
+    showYAxis?: boolean;
+    /** Show X-axis labels */
+    showXAxis?: boolean;
+    /** Label for the Y axis */
+    yLabel?: string;
+    /** Maximum Y value (auto if not set) */
+    max?: number;
+    /** Minimum Y value (auto if not set) */
+    min?: number;
+}
+/**
+ * LineChart — ASCII/Unicode line plot for a series of numbers.
+ *
+ * Normalizes data to the available height, samples to fit width.
+ * Plots points with simple vertical bar connectors between adjacent points.
+ */
+declare class LineChart extends Widget {
+    private _data;
+    private _color;
+    private _showYAxis;
+    private _showXAxis;
+    private _yLabel;
+    private _max?;
+    private _min?;
+    constructor(data: number[], style?: Partial<Style>, opts?: LineChartOptions);
+    setData(data: number[]): void;
+    pushValue(value: number): void;
+    protected _renderSelf(screen: Screen): void;
+}
+
+interface HeatMapOptions {
+    /** Color for maximum value cells */
+    highColor?: Color;
+    /** Color for minimum value cells */
+    lowColor?: Color;
+    /** Row labels (left side) */
+    rowLabels?: string[];
+    /** Column labels (top) */
+    colLabels?: string[];
+}
+/**
+ * HeatMap — 2D matrix displayed with character-density shading.
+ *
+ * Values are normalized 0–1 and mapped to 4 shading levels.
+ */
+declare class HeatMap extends Widget {
+    private _matrix;
+    private _highColor;
+    private _lowColor;
+    private _rowLabels;
+    private _colLabels;
+    constructor(matrix: number[][], style?: Partial<Style>, opts?: HeatMapOptions);
+    setMatrix(matrix: number[][]): void;
+    protected _renderSelf(screen: Screen): void;
+}
+
+interface DefinitionPair {
+    term: string;
+    definition: string;
+}
+interface DefinitionOptions {
+    /** Indentation for definition lines (default: 2) */
+    indent?: number;
+    /** Blank line between pairs (default: true) */
+    spacing?: boolean;
+    /** Color for term labels */
+    termColor?: _termuijs_core.Color;
+    /** Color for definition text */
+    definitionColor?: _termuijs_core.Color;
+}
+/**
+ * Definition — term + definition pairs, stacked vertically.
+ *
+ * Each pair renders as:
+ *   Term
+ *     definition text (indented)
+ *
+ * Similar to KeyValue but stacked rather than inline.
+ */
+declare class Definition extends Widget {
+    private _pairs;
+    private _indent;
+    private _spacing;
+    private _termColor?;
+    private _definitionColor?;
+    constructor(pairs: DefinitionPair[] | Record<string, string>, style?: Partial<Style>, opts?: DefinitionOptions);
+    setPairs(pairs: DefinitionPair[] | Record<string, string>): void;
+    protected _renderSelf(screen: Screen): void;
+}
+
+interface BigTextOptions {
+    /** Color for the rendered characters */
+    color?: Color;
+}
+/**
+ * BigText — renders text as large 5×3 ASCII art banner characters.
+ *
+ * Supports A–Z (uppercase), 0–9, and common punctuation.
+ * Unrecognized characters fall back to a narrow glyph.
+ */
+declare class BigText extends Widget {
+    private _text;
+    private _color;
+    constructor(text: string, style?: Partial<Style>, opts?: BigTextOptions);
+    setText(text: string): void;
+    protected _renderSelf(screen: Screen): void;
+}
+
+interface GradientOptions {
+    /** Start color (hex string like '#ff0000' or named color string) */
+    startColor?: string;
+    /** End color (hex string like '#0000ff' or named color string) */
+    endColor?: string;
+    /** Text alignment */
+    align?: 'left' | 'center' | 'right';
+}
+/**
+ * Gradient — text rendered with a smooth color gradient.
+ *
+ * Each character is colored by linearly interpolating between startColor and endColor.
+ * Falls back to a single foreground color if true-color is unavailable.
+ */
+declare class Gradient extends Widget {
+    private _text;
+    private _startColor;
+    private _endColor;
+    private _align;
+    constructor(text: string, style?: Partial<Style>, opts?: GradientOptions);
+    setText(text: string): void;
+    setColors(start: string, end: string): void;
+    protected _renderSelf(screen: Screen): void;
+}
+
+export { Banner, type BannerOptions, type Bar, BarChart, type BarChartDirection, type BarChartOptions, type BarGroup, BigText, type BigTextOptions, Box, Card, type CardOptions, Center, type CenterOptions, ChatMessage, type ChatMessageOptions, Columns, type ColumnsOptions, type Command, CommandPalette, type CommandPaletteOptions, Definition, type DefinitionOptions, type DefinitionPair, type DiffLine, DiffView, type DiffViewOptions, Gauge, type GaugeOptions, Gradient, type GradientOptions, Grid, type GridOptions, HeatMap, type HeatMapOptions, type JSONNodeData, type JSONNodeType, JSONView, type JSONViewOptions, KeyValue, type KeyValueOptions, type KeyValuePair, LineChart, type LineChartOptions, List, type ListItem, LogView, type LogViewOptions, type MessageRole, MultiProgress, type MultiProgressOptions, ProgressBar, type ProgressBarOptions, type ProgressItem, SPINNER_FRAMES, type ScrollRange, ScrollView, type ScrollViewOptions, Scrollbar, type ScrollbarOptions, type ScrollbarOrientation, Sidebar, type SidebarItem, type SidebarOptions, Skeleton, type SkeletonOptions, Sparkline, type SparklineOptions, Spinner, type SpinnerOptions, StatusIndicator, type StatusIndicatorOptions, StatusMessage, type StatusMessageOptions, type StatusVariant, StreamingText, type StreamingTextOptions, Table, type TableColumn, type TableOptions, type TableRow, Text, TextInput, type TextProps, ToolApproval, type ToolApprovalOptions, ToolCall, type ToolCallOptions, type ToolCallStatus, Tree, type TreeNode, type TreeOptions, VirtualList, type VirtualListOptions, Widget, type WidgetEvents, computeRange, computeVariableRange, jsonToTree };