@termuijs/widgets 0.1.1 → 0.1.2

package/dist/index.d.cts

@@ -136,19 +136,31 @@ interface TextProps {
     content: string;
     wrap?: boolean;
     align?: 'left' | 'center' | 'right';
+    /** Vertical scroll offset (lines to skip from top). Default: 0. */
+    scrollY?: number;
+    /** Horizontal scroll offset (columns to skip from left). Default: 0. */
+    scrollX?: number;
 }
 /**
- * Text — renders a string of text with word-wrapping and alignment.
+ * Text — renders a string of text with word-wrapping, alignment, and scrolling.
  */
 declare class Text extends Widget {
     private _content;
     private _wrap;
     private _align;
+    private _scrollY;
+    private _scrollX;
     constructor(content: string, style?: Partial<Style>, props?: Partial<TextProps>);
     /** Update the text content */
     setContent(content: string): void;
     /** Get current text content */
     getContent(): string;
+    /** Set vertical scroll offset (lines to skip). */
+    setScrollY(offset: number): void;
+    /** Set horizontal scroll offset (columns to skip). */
+    setScrollX(offset: number): void;
+    /** Get the total number of lines after wrapping. */
+    getLineCount(): number;
     protected _renderSelf(screen: Screen): void;
 }
 
@@ -259,6 +271,70 @@ declare class TextInput extends Widget {
     protected _renderSelf(screen: Screen): void;
 }
 
+interface VirtualListOptions {
+    /** Total number of items (the full dataset size) */
+    totalItems: number;
+    /** Height of each item in rows (default: 1) */
+    itemHeight?: number;
+    /** Render function: returns the string content for an item at a given index */
+    renderItem: (index: number) => string;
+    /** Style overrides */
+    style?: Partial<Style>;
+    /** Callback when an item is selected (Enter key) */
+    onSelect?: (index: number) => void;
+    /** Number of overscan rows to render above/below the viewport (default: 2) */
+    overscan?: number;
+    /** Show scrollbar (default: true) */
+    showScrollbar?: boolean;
+}
+/**
+ * VirtualList — a scroll-virtualized list widget.
+ *
+ * Only renders the items visible in the viewport plus
+ * a small overscan buffer, enabling smooth scrolling
+ * through datasets of any size.
+ *
+ * Performance:
+ * - 100 items → renders ~26 rows
+ * - 1,000,000 items → still renders only ~26 rows
+ */
+declare class VirtualList extends Widget {
+    private _totalItems;
+    private _itemHeight;
+    private _renderItem;
+    private _onSelect?;
+    private _selectedIndex;
+    private _scrollOffset;
+    private _overscan;
+    private _showScrollbar;
+    constructor(options: VirtualListOptions);
+    get totalItems(): number;
+    get selectedIndex(): number;
+    get scrollOffset(): number;
+    /** Update the total item count (e.g., after data refresh) */
+    setTotalItems(count: number): void;
+    /** Update the render function (e.g., when data changes) */
+    setRenderItem(fn: (index: number) => string): void;
+    /** Move selection up by one */
+    selectPrev(): void;
+    /** Move selection down by one */
+    selectNext(): void;
+    /** Jump to the first item */
+    selectFirst(): void;
+    /** Jump to the last item */
+    selectLast(): void;
+    /** Page up — move by viewport height */
+    pageUp(): void;
+    /** Page down — move by viewport height */
+    pageDown(): void;
+    /** Scroll to a specific index */
+    scrollTo(index: number): void;
+    /** Confirm the current selection */
+    confirm(): void;
+    protected _renderSelf(screen: Screen): void;
+    private _clampScroll;
+}
+
 interface TableColumn {
     /** Column header label */
     header: string;
@@ -380,6 +456,53 @@ declare class StatusIndicator extends Widget {
     protected _renderSelf(screen: Screen): void;
 }
 
+interface Bar {
+    value: number;
+    label?: string;
+    color?: Color;
+}
+interface BarGroup {
+    label?: string;
+    bars: Bar[];
+}
+type BarChartDirection = 'vertical' | 'horizontal';
+interface BarChartOptions {
+    /** Direction bars grow. Default: 'vertical'. */
+    direction?: BarChartDirection;
+    /** Width of each bar in cells. Default: 1. */
+    barWidth?: number;
+    /** Gap between bars in a group. Default: 1. */
+    barGap?: number;
+    /** Gap between groups. Default: 2. */
+    groupGap?: number;
+    /** Max value for scaling. Auto-detected if not set. */
+    max?: number;
+    /** Color for bars without a per-bar color. */
+    barColor?: Color;
+    /** Color for value labels. */
+    valueColor?: Color;
+    /** Color for text labels. */
+    labelColor?: Color;
+}
+declare class BarChart extends Widget {
+    private _data;
+    private _direction;
+    private _barWidth;
+    private _barGap;
+    private _groupGap;
+    private _max?;
+    private _barColor;
+    private _valueColor;
+    private _labelColor;
+    constructor(data: BarGroup[], style?: Partial<Style>, opts?: BarChartOptions);
+    setData(data: BarGroup[]): void;
+    setMax(max: number | undefined): void;
+    protected _renderSelf(screen: Screen): void;
+    private _computeMax;
+    private _renderVertical;
+    private _renderHorizontal;
+}
+
 interface ProgressBarOptions {
     /** Current value (0–1) */
     value?: number;
@@ -466,4 +589,36 @@ declare class Spinner extends Widget {
     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 };
+type ScrollbarOrientation = 'verticalRight' | 'verticalLeft' | 'horizontalBottom' | 'horizontalTop';
+interface ScrollbarOptions {
+    /** Total number of content items. */
+    contentLength: number;
+    /** Number of items visible in the viewport. */
+    viewportLength: number;
+    /** Current scroll position (0-based). */
+    position?: number;
+    /** Scrollbar orientation. Default: 'verticalRight'. */
+    orientation?: ScrollbarOrientation;
+    /** Color of the thumb. */
+    thumbColor?: Color;
+    /** Color of the track. */
+    trackColor?: Color;
+    /** Show begin/end arrow symbols. Default: true. */
+    showArrows?: boolean;
+}
+declare class Scrollbar extends Widget {
+    private _contentLength;
+    private _viewportLength;
+    private _position;
+    private _orientation;
+    private _thumbColor;
+    private _trackColor;
+    private _showArrows;
+    constructor(style: Partial<Style> | undefined, opts: ScrollbarOptions);
+    setPosition(position: number): void;
+    setContentLength(length: number): void;
+    setViewportLength(length: number): void;
+    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 };

package/dist/index.d.ts

@@ -136,19 +136,31 @@ interface TextProps {
     content: string;
     wrap?: boolean;
     align?: 'left' | 'center' | 'right';
+    /** Vertical scroll offset (lines to skip from top). Default: 0. */
+    scrollY?: number;
+    /** Horizontal scroll offset (columns to skip from left). Default: 0. */
+    scrollX?: number;
 }
 /**
- * Text — renders a string of text with word-wrapping and alignment.
+ * Text — renders a string of text with word-wrapping, alignment, and scrolling.
  */
 declare class Text extends Widget {
     private _content;
     private _wrap;
     private _align;
+    private _scrollY;
+    private _scrollX;
     constructor(content: string, style?: Partial<Style>, props?: Partial<TextProps>);
     /** Update the text content */
     setContent(content: string): void;
     /** Get current text content */
     getContent(): string;
+    /** Set vertical scroll offset (lines to skip). */
+    setScrollY(offset: number): void;
+    /** Set horizontal scroll offset (columns to skip). */
+    setScrollX(offset: number): void;
+    /** Get the total number of lines after wrapping. */
+    getLineCount(): number;
     protected _renderSelf(screen: Screen): void;
 }
 
@@ -259,6 +271,70 @@ declare class TextInput extends Widget {
     protected _renderSelf(screen: Screen): void;
 }
 
+interface VirtualListOptions {
+    /** Total number of items (the full dataset size) */
+    totalItems: number;
+    /** Height of each item in rows (default: 1) */
+    itemHeight?: number;
+    /** Render function: returns the string content for an item at a given index */
+    renderItem: (index: number) => string;
+    /** Style overrides */
+    style?: Partial<Style>;
+    /** Callback when an item is selected (Enter key) */
+    onSelect?: (index: number) => void;
+    /** Number of overscan rows to render above/below the viewport (default: 2) */
+    overscan?: number;
+    /** Show scrollbar (default: true) */
+    showScrollbar?: boolean;
+}
+/**
+ * VirtualList — a scroll-virtualized list widget.
+ *
+ * Only renders the items visible in the viewport plus
+ * a small overscan buffer, enabling smooth scrolling
+ * through datasets of any size.
+ *
+ * Performance:
+ * - 100 items → renders ~26 rows
+ * - 1,000,000 items → still renders only ~26 rows
+ */
+declare class VirtualList extends Widget {
+    private _totalItems;
+    private _itemHeight;
+    private _renderItem;
+    private _onSelect?;
+    private _selectedIndex;
+    private _scrollOffset;
+    private _overscan;
+    private _showScrollbar;
+    constructor(options: VirtualListOptions);
+    get totalItems(): number;
+    get selectedIndex(): number;
+    get scrollOffset(): number;
+    /** Update the total item count (e.g., after data refresh) */
+    setTotalItems(count: number): void;
+    /** Update the render function (e.g., when data changes) */
+    setRenderItem(fn: (index: number) => string): void;
+    /** Move selection up by one */
+    selectPrev(): void;
+    /** Move selection down by one */
+    selectNext(): void;
+    /** Jump to the first item */
+    selectFirst(): void;
+    /** Jump to the last item */
+    selectLast(): void;
+    /** Page up — move by viewport height */
+    pageUp(): void;
+    /** Page down — move by viewport height */
+    pageDown(): void;
+    /** Scroll to a specific index */
+    scrollTo(index: number): void;
+    /** Confirm the current selection */
+    confirm(): void;
+    protected _renderSelf(screen: Screen): void;
+    private _clampScroll;
+}
+
 interface TableColumn {
     /** Column header label */
     header: string;
@@ -380,6 +456,53 @@ declare class StatusIndicator extends Widget {
     protected _renderSelf(screen: Screen): void;
 }
 
+interface Bar {
+    value: number;
+    label?: string;
+    color?: Color;
+}
+interface BarGroup {
+    label?: string;
+    bars: Bar[];
+}
+type BarChartDirection = 'vertical' | 'horizontal';
+interface BarChartOptions {
+    /** Direction bars grow. Default: 'vertical'. */
+    direction?: BarChartDirection;
+    /** Width of each bar in cells. Default: 1. */
+    barWidth?: number;
+    /** Gap between bars in a group. Default: 1. */
+    barGap?: number;
+    /** Gap between groups. Default: 2. */
+    groupGap?: number;
+    /** Max value for scaling. Auto-detected if not set. */
+    max?: number;
+    /** Color for bars without a per-bar color. */
+    barColor?: Color;
+    /** Color for value labels. */
+    valueColor?: Color;
+    /** Color for text labels. */
+    labelColor?: Color;
+}
+declare class BarChart extends Widget {
+    private _data;
+    private _direction;
+    private _barWidth;
+    private _barGap;
+    private _groupGap;
+    private _max?;
+    private _barColor;
+    private _valueColor;
+    private _labelColor;
+    constructor(data: BarGroup[], style?: Partial<Style>, opts?: BarChartOptions);
+    setData(data: BarGroup[]): void;
+    setMax(max: number | undefined): void;
+    protected _renderSelf(screen: Screen): void;
+    private _computeMax;
+    private _renderVertical;
+    private _renderHorizontal;
+}
+
 interface ProgressBarOptions {
     /** Current value (0–1) */
     value?: number;
@@ -466,4 +589,36 @@ declare class Spinner extends Widget {
     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 };
+type ScrollbarOrientation = 'verticalRight' | 'verticalLeft' | 'horizontalBottom' | 'horizontalTop';
+interface ScrollbarOptions {
+    /** Total number of content items. */
+    contentLength: number;
+    /** Number of items visible in the viewport. */
+    viewportLength: number;
+    /** Current scroll position (0-based). */
+    position?: number;
+    /** Scrollbar orientation. Default: 'verticalRight'. */
+    orientation?: ScrollbarOrientation;
+    /** Color of the thumb. */
+    thumbColor?: Color;
+    /** Color of the track. */
+    trackColor?: Color;
+    /** Show begin/end arrow symbols. Default: true. */
+    showArrows?: boolean;
+}
+declare class Scrollbar extends Widget {
+    private _contentLength;
+    private _viewportLength;
+    private _position;
+    private _orientation;
+    private _thumbColor;
+    private _trackColor;
+    private _showArrows;
+    constructor(style: Partial<Style> | undefined, opts: ScrollbarOptions);
+    setPosition(position: number): void;
+    setContentLength(length: number): void;
+    setViewportLength(length: number): void;
+    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 };