@termuijs/widgets 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,469 @@
+import { Style, Rect, EventEmitter, KeyEvent, MouseEvent, LayoutNode, Screen, Color } from '@termuijs/core';
+
+/**
+ * Event map for widgets.
+ */
+interface WidgetEvents {
+    key: KeyEvent;
+    mouse: MouseEvent;
+    focus: void;
+    blur: void;
+    mount: void;
+    unmount: void;
+}
+/**
+ * Base class for all TermUI widgets.
+ *
+ * Provides:
+ * - Unique ID generation
+ * - Style management and merging
+ * - Layout node generation with rect sync
+ * - Border/padding rendering into the screen buffer
+ * - Child management
+ * - Focus support
+ * - Event emission
+ */
+declare abstract class Widget {
+    /** Unique widget identifier */
+    readonly id: string;
+    /** Widget's style */
+    protected _style: Style;
+    /** Child widgets */
+    protected _children: Widget[];
+    /** Parent widget (null for root) */
+    parent: Widget | null;
+    /** Computed layout rectangle */
+    protected _rect: Rect;
+    /** Reference to the layout node (set during getLayoutNode) */
+    private _layoutNode;
+    /** Whether this widget can receive focus */
+    focusable: boolean;
+    /** Tab index for focus ordering */
+    tabIndex: number;
+    /** Event emitter for this widget */
+    readonly events: EventEmitter<WidgetEvents>;
+    /** Whether the widget is currently focused */
+    isFocused: boolean;
+    /**
+     * Dirty flag — true when this widget needs re-rendering.
+     * Newly created widgets start dirty.
+     */
+    protected _dirty: boolean;
+    constructor(style?: Partial<Style>);
+    /** Get the current style */
+    get style(): Style;
+    /** Update the style (merge with existing) */
+    setStyle(style: Partial<Style>): void;
+    /** Get the computed rect after layout */
+    get rect(): Rect;
+    /** Add a child widget */
+    addChild(child: Widget): void;
+    /** Remove a child widget */
+    removeChild(child: Widget): void;
+    /** Remove all children */
+    clearChildren(): void;
+    /** Get all children */
+    get children(): ReadonlyArray<Widget>;
+    /**
+     * Build the LayoutNode tree for this widget.
+     * Stores a reference so we can sync computed rects back via syncLayout().
+     */
+    getLayoutNode(): LayoutNode;
+    /**
+     * After computeLayout() has been called, sync the computed rects
+     * from the layout tree back into widget `_rect` fields.
+     * This MUST be called after computeLayout() and before render().
+     */
+    syncLayout(): void;
+    /**
+     * Render this widget (and children) into the screen buffer.
+     * Automatically pushes a clip region if overflow is hidden (default).
+     */
+    render(screen: Screen): void;
+    /**
+     * Override this to render the widget's own content.
+     * The rect is available as `this._rect`.
+     */
+    protected abstract _renderSelf(screen: Screen): void;
+    /**
+     * Update the computed rect from layout results.
+     */
+    updateRect(rect: Rect): void;
+    /**
+     * Mark this widget as needing re-render.
+     * Propagates up to parent so the render loop can detect changes.
+     */
+    markDirty(): void;
+    /**
+     * Clear the dirty flag after rendering.
+     */
+    clearDirty(): void;
+    /** Check if this widget (or any child) needs re-rendering */
+    get isDirty(): boolean;
+    /**
+     * Render the border around this widget, including focus ring if focused.
+     */
+    protected _renderBorder(screen: Screen): void;
+    /**
+     * Get the inner content area (after border + padding).
+     */
+    protected _getContentRect(): Rect;
+    /**
+     * Check if a point hits this widget.
+     */
+    hitTest(x: number, y: number): boolean;
+    /** Lifecycle: called when the widget is mounted */
+    mount(): void;
+    /** Lifecycle: called when the widget is unmounted */
+    unmount(): void;
+}
+
+/**
+ * Box — the fundamental container widget, similar to a `<div>`.
+ *
+ * Supports:
+ * - Flexbox layout (row/column)
+ * - Border styles (single/double/round/heavy/dashed)
+ * - Padding and margin
+ * - Background color
+ */
+declare class Box extends Widget {
+    constructor(style?: Partial<Style>);
+    protected _renderSelf(screen: Screen): void;
+}
+
+interface TextProps {
+    content: string;
+    wrap?: boolean;
+    align?: 'left' | 'center' | 'right';
+}
+/**
+ * Text — renders a string of text with word-wrapping and alignment.
+ */
+declare class Text extends Widget {
+    private _content;
+    private _wrap;
+    private _align;
+    constructor(content: string, style?: Partial<Style>, props?: Partial<TextProps>);
+    /** Update the text content */
+    setContent(content: string): void;
+    /** Get current text content */
+    getContent(): string;
+    protected _renderSelf(screen: Screen): void;
+}
+
+interface LogViewOptions {
+    /** Highlight rules: keyword → color */
+    highlight?: Record<string, Color>;
+    /** Auto-scroll to bottom */
+    autoScroll?: boolean;
+}
+/**
+ * LogView — scrollable, highlighted log output.
+ *
+ * Supports keyword-based color highlighting (ERROR → red, WARN → yellow, etc.)
+ */
+declare class LogView extends Widget {
+    private _lines;
+    private _scrollOffset;
+    private _highlight;
+    private _autoScroll;
+    constructor(style?: Partial<Style>, opts?: LogViewOptions);
+    setLines(lines: string[]): void;
+    appendLine(line: string): void;
+    scrollUp(n?: number): void;
+    scrollDown(n?: number): void;
+    private _scrollToBottom;
+    protected _renderSelf(screen: Screen): void;
+    private _getLineColor;
+}
+
+interface ListItem {
+    label: string;
+    value: string;
+    disabled?: boolean;
+}
+/**
+ * List — a scrollable, selectable list of items.
+ *
+ * Supports:
+ * - Keyboard navigation (up/down/Home/End)
+ * - Scrolling when items exceed visible height
+ * - Custom item styling
+ * - Disabled items
+ */
+declare class List extends Widget {
+    private _items;
+    private _selectedIndex;
+    private _scrollOffset;
+    private _onSelect?;
+    constructor(items: ListItem[], style?: Partial<Style>, onSelect?: (item: ListItem, index: number) => void);
+    get selectedIndex(): number;
+    get selectedItem(): ListItem | undefined;
+    setItems(items: ListItem[]): void;
+    /** Move selection up */
+    selectPrev(): void;
+    /** Move selection down */
+    selectNext(): void;
+    /** Confirm the current selection */
+    confirm(): void;
+    protected _renderSelf(screen: Screen): void;
+    private _clampScroll;
+}
+
+/**
+ * TextInput — a single-line text input field.
+ *
+ * Supports:
+ * - Cursor movement (left/right/Home/End)
+ * - Character insertion and deletion
+ * - Placeholder text
+ * - Password masking
+ * - Max length constraint
+ */
+declare class TextInput extends Widget {
+    private _value;
+    private _cursorPos;
+    private _placeholder;
+    private _mask;
+    private _maxLength;
+    private _onChange?;
+    private _onSubmit?;
+    constructor(style?: Partial<Style>, options?: {
+        placeholder?: string;
+        mask?: string;
+        maxLength?: number;
+        onChange?: (value: string) => void;
+        onSubmit?: (value: string) => void;
+    });
+    get value(): string;
+    set value(v: string);
+    /**
+     * Handle a typed character.
+     */
+    insertChar(char: string): void;
+    /**
+     * Delete the character before the cursor.
+     */
+    deleteBack(): void;
+    /**
+     * Delete the character after the cursor.
+     */
+    deleteForward(): void;
+    moveCursorLeft(): void;
+    moveCursorRight(): void;
+    moveCursorHome(): void;
+    moveCursorEnd(): void;
+    submit(): void;
+    clear(): void;
+    protected _renderSelf(screen: Screen): void;
+}
+
+interface TableColumn {
+    /** Column header label */
+    header: string;
+    /** Key to pull data from row objects */
+    key: string;
+    /** Fixed width (chars). If omitted, auto-distributes. */
+    width?: number;
+    /** Text alignment within the column */
+    align?: 'left' | 'center' | 'right';
+}
+type TableRow = Record<string, string | number>;
+interface TableOptions {
+    /** Whether to show the header row */
+    showHeader?: boolean;
+    /** Color for the header row */
+    headerColor?: Color;
+    /** Whether rows are zebra-striped */
+    stripe?: boolean;
+    /** Stripe color */
+    stripeColor?: Color;
+    /** Column separator character */
+    separator?: string;
+}
+/**
+ * Table — renders tabular data with columns, headers, and optional zebra-striping.
+ *
+ * Supports:
+ * - Auto-width column distribution
+ * - Fixed and percentage widths
+ * - Header styling
+ * - Zebra striping
+ * - Text alignment per column
+ * - Truncation for overflow
+ */
+declare class Table extends Widget {
+    private _columns;
+    private _rows;
+    private _showHeader;
+    private _headerColor;
+    private _stripe;
+    private _stripeColor;
+    private _separator;
+    constructor(columns: TableColumn[], rows: TableRow[], style?: Partial<Style>, options?: TableOptions);
+    setRows(rows: TableRow[]): void;
+    protected _renderSelf(screen: Screen): void;
+    private _computeColumnWidths;
+    private _alignText;
+}
+
+interface GaugeOptions {
+    /** Color of the filled portion */
+    color?: Color;
+    /** Show percentage label */
+    showLabel?: boolean;
+}
+/**
+ * Gauge — a self-contained metric display with label, bar, and value.
+ *
+ * Example:
+ *   CPU ████████░░░░ 65%
+ */
+declare class Gauge extends Widget {
+    private _label;
+    private _value;
+    private _color;
+    private _showLabel;
+    constructor(label: string, style?: Partial<Style>, opts?: GaugeOptions);
+    setValue(value: number): void;
+    getValue(): number;
+    setLabel(label: string): void;
+    protected _renderSelf(screen: Screen): void;
+}
+
+interface SparklineOptions {
+    /** Color of the sparkline */
+    color?: Color;
+    /** Show min/max labels */
+    showRange?: boolean;
+}
+/**
+ * Sparkline — a compact inline chart showing a data trend.
+ *
+ * Example:
+ *   Latency ▂▃▅▇▅▃▂▁▃▅█▅▃
+ */
+declare class Sparkline extends Widget {
+    private _label;
+    private _data;
+    private _color;
+    private _showRange;
+    constructor(label: string, style?: Partial<Style>, opts?: SparklineOptions);
+    setData(data: number[]): void;
+    pushValue(value: number): void;
+    protected _renderSelf(screen: Screen): void;
+}
+
+interface StatusIndicatorOptions {
+    /** Color when up/active */
+    upColor?: Color;
+    /** Color when down/inactive */
+    downColor?: Color;
+}
+/**
+ * StatusIndicator — simple up/down indicator with label.
+ *
+ * Example:
+ *   ● API Server — Online
+ *   ○ Worker — Offline
+ */
+declare class StatusIndicator extends Widget {
+    private _label;
+    private _isUp;
+    private _upColor;
+    private _downColor;
+    constructor(label: string, isUp: boolean, style?: Partial<Style>, opts?: StatusIndicatorOptions);
+    setStatus(isUp: boolean): void;
+    getStatus(): boolean;
+    setLabel(label: string): void;
+    protected _renderSelf(screen: Screen): void;
+}
+
+interface ProgressBarOptions {
+    /** Current value (0–1) */
+    value?: number;
+    /** Character for the filled portion */
+    fillChar?: string;
+    /** Character for the empty portion */
+    emptyChar?: string;
+    /** Color of the filled portion */
+    fillColor?: Color;
+    /** Show percentage label */
+    showLabel?: boolean;
+    /** Label format: 'percent' | 'fraction' | 'custom' */
+    labelFormat?: 'percent' | 'fraction';
+    /** Total for fraction display */
+    total?: number;
+}
+/**
+ * ProgressBar — horizontal progress indicator.
+ *
+ * Supports:
+ * - Configurable fill/empty characters
+ * - Custom fill color
+ * - Percentage or fraction label
+ * - Smooth animation-ready value changes
+ */
+declare class ProgressBar extends Widget {
+    private _value;
+    private _fillChar;
+    private _emptyChar;
+    private _fillColor;
+    private _showLabel;
+    private _labelFormat;
+    private _total;
+    constructor(style?: Partial<Style>, options?: ProgressBarOptions);
+    /** Set progress value (0–1) */
+    setValue(value: number): void;
+    get value(): number;
+    protected _renderSelf(screen: Screen): void;
+}
+
+/**
+ * Built-in spinner frame sets.
+ */
+declare const SPINNER_FRAMES: Record<string, {
+    frames: string[];
+    interval: number;
+}>;
+interface SpinnerOptions {
+    /** Spinner preset name or custom frames */
+    spinner?: string | {
+        frames: string[];
+        interval: number;
+    };
+    /** Text label displayed after the spinner */
+    label?: string;
+    /** Color for the spinner frames */
+    color?: Color;
+}
+/**
+ * Spinner — animated loading indicator.
+ *
+ * Supports:
+ * - 8 built-in spinner presets
+ * - Custom frame sequences
+ * - Configurable color and label
+ * - Automatic frame advancement via tick()
+ */
+declare class Spinner extends Widget {
+    private _frames;
+    private _interval;
+    private _frameIndex;
+    private _label;
+    private _color;
+    private _lastTick;
+    private _elapsed;
+    constructor(style?: Partial<Style>, options?: SpinnerOptions);
+    /** Update the spinner label */
+    setLabel(label: string): void;
+    /**
+     * Advance the spinner frame based on elapsed time.
+     * Call this with a delta (ms) from the render loop.
+     */
+    tick(deltaMs: number): void;
+    protected _renderSelf(screen: Screen): void;
+}
+
+export { Box, Gauge, type GaugeOptions, List, type ListItem, LogView, type LogViewOptions, ProgressBar, type ProgressBarOptions, SPINNER_FRAMES, Sparkline, type SparklineOptions, Spinner, type SpinnerOptions, StatusIndicator, type StatusIndicatorOptions, Table, type TableColumn, type TableOptions, type TableRow, Text, TextInput, type TextProps, Widget, type WidgetEvents };