Crate ftui_widgets

Expand description

Core widgets for FrankenTUI.

This crate provides the Widget and StatefulWidget traits, along with a collection of ready-to-use widgets for building terminal UIs.

Widgets render into a Frame rather than directly into a Buffer. The Frame provides access to several subsystems beyond the cell grid:

frame.buffer - The cell grid for drawing characters and styles
frame.hit_grid - Optional mouse hit testing (for interactive widgets)
frame.cursor_position - Cursor placement (for input widgets)
frame.cursor_visible - Cursor visibility control
frame.degradation - Performance budget hints (for adaptive rendering)

§Role in FrankenTUI

ftui-widgets is the standard widget library. It provides the reusable building blocks (tables, lists, inputs, graphs, etc.) that most apps will render inside their view() functions.

§How it fits in the system

Widgets render into ftui-render::Frame using ftui-style for appearance and ftui-text for text measurement and wrapping. The runtime drives these widgets by calling your model’s view() on each frame.

Widgets fall into four categories based on which Frame features they use:

§Category A: Simple Buffer-Only Widgets

Most widgets only need buffer access. These are the simplest to implement:

impl Widget for MyWidget {
    fn render(&self, area: Rect, frame: &mut Frame) {
        // Just write to the buffer
        frame.buffer.set(area.x, area.y, Cell::from_char('X'));
    }
}

Examples: block::Block, paragraph::Paragraph, rule::Rule, StatusLine

§Category B: Interactive Widgets with Hit Testing

Widgets that handle mouse clicks register hit regions:

impl Widget for ClickableList {
    fn render(&self, area: Rect, frame: &mut Frame) {
        // Draw items...
        for (i, item) in self.items.iter().enumerate() {
            let row_area = Rect::new(area.x, area.y + i as u16, area.width, 1);
            // Draw item to buffer...

            // Register hit region for mouse interaction
            if let Some(id) = self.hit_id {
                frame.register_hit(row_area, id, HitRegion::Content, i as u64);
            }
        }
    }
}

Examples: list::List, table::Table, scrollbar::Scrollbar

§Category C: Input Widgets with Cursor Control

Text input widgets need to position the cursor:

impl Widget for TextInput {
    fn render(&self, area: Rect, frame: &mut Frame) {
        // Draw the input content...

        // Position cursor when focused
        if self.focused {
            let cursor_x = area.x + self.cursor_offset as u16;
            frame.cursor_position = Some((cursor_x, area.y));
            frame.cursor_visible = true;
        }
    }
}

Examples: TextInput

§Category D: Adaptive Widgets with Degradation Support

Complex widgets can adapt their rendering based on performance budget:

impl Widget for FancyProgressBar {
    fn render(&self, area: Rect, frame: &mut Frame) {
        let deg = frame.buffer.degradation;

        if !deg.render_decorative() {
            // Skip decorative elements at reduced budgets
            return;
        }

        if deg.apply_styling() {
            // Use full styling and effects
        } else {
            // Use simplified ASCII rendering
        }
    }
}

Examples: ProgressBar, Spinner

§Essential vs Decorative Widgets

The Widget::is_essential method indicates whether a widget should always render, even at EssentialOnly degradation level:

Essential: Text inputs, primary content, status information
Decorative: Borders, scrollbars, spinners, visual separators

Re-exports§

pub use align::Align;
pub use align::VerticalAlignment;
pub use badge::Badge;
pub use cached::CacheKey;
pub use cached::CachedWidget;
pub use cached::CachedWidgetState;
pub use cached::FnKey;
pub use cached::HashKey;
pub use cached::NoCacheKey;
pub use columns::Column;
pub use columns::Columns;
pub use constraint_overlay::ConstraintOverlay;
pub use constraint_overlay::ConstraintOverlayStyle;
pub use group::Group;
pub use help_registry::HelpContent;
pub use help_registry::HelpId;
pub use help_registry::HelpRegistry;
pub use help_registry::Keybinding;
pub use history_panel::HistoryEntry;
pub use history_panel::HistoryPanel;
pub use history_panel::HistoryPanelMode;
pub use layout_debugger::LayoutConstraints;
pub use layout_debugger::LayoutDebugger;
pub use layout_debugger::LayoutRecord;
pub use log_ring::LogRing;
pub use log_viewer::LogViewer;
pub use log_viewer::LogViewerState;
pub use log_viewer::LogWrapMode;
pub use log_viewer::SearchConfig;
pub use log_viewer::SearchMode;
pub use paginator::Paginator;
pub use paginator::PaginatorMode;
pub use panel::Panel;
pub use sparkline::Sparkline;
pub use status_line::StatusItem;
pub use status_line::StatusLine;
pub use virtualized::HeightCache;
pub use virtualized::ItemHeight;
pub use virtualized::RenderItem;
pub use virtualized::Virtualized;
pub use virtualized::VirtualizedList;
pub use virtualized::VirtualizedListState;
pub use virtualized::VirtualizedStorage;
pub use voi_debug_overlay::VoiDebugOverlay;
pub use voi_debug_overlay::VoiDecisionSummary;
pub use voi_debug_overlay::VoiLedgerEntry;
pub use voi_debug_overlay::VoiObservationSummary;
pub use voi_debug_overlay::VoiOverlayData;
pub use voi_debug_overlay::VoiOverlayStyle;
pub use voi_debug_overlay::VoiPosteriorSummary;
pub use toast::KeyEvent as ToastKeyEvent;
pub use toast::Toast;
pub use toast::ToastAction;
pub use toast::ToastAnimationConfig;
pub use toast::ToastAnimationPhase;
pub use toast::ToastAnimationState;
pub use toast::ToastConfig;
pub use toast::ToastContent;
pub use toast::ToastEasing;
pub use toast::ToastEntranceAnimation;
pub use toast::ToastEvent;
pub use toast::ToastExitAnimation;
pub use toast::ToastIcon;
pub use toast::ToastId;
pub use toast::ToastPosition;
pub use toast::ToastState;
pub use toast::ToastStyle;
pub use notification_queue::NotificationPriority;
pub use notification_queue::NotificationQueue;
pub use notification_queue::QueueAction;
pub use notification_queue::QueueConfig;
pub use notification_queue::QueueStats;
pub use measurable::MeasurableWidget;
pub use measurable::SizeConstraints;
pub use measure_cache::CacheStats;
pub use measure_cache::MeasureCache;
pub use measure_cache::WidgetId;
pub use modal::BackdropConfig;
pub use modal::MODAL_HIT_BACKDROP;
pub use modal::MODAL_HIT_CONTENT;
pub use modal::Modal;
pub use modal::ModalAction;
pub use modal::ModalConfig;
pub use modal::ModalPosition;
pub use modal::ModalSizeConstraints;
pub use modal::ModalState;
pub use inspector::DiagnosticEntry;
pub use inspector::DiagnosticEventKind;
pub use inspector::DiagnosticLog;
pub use inspector::HitInfo;
pub use inspector::InspectorMode;
pub use inspector::InspectorOverlay;
pub use inspector::InspectorState;
pub use inspector::InspectorStyle;
pub use inspector::TelemetryCallback;
pub use inspector::TelemetryHooks;
pub use inspector::WidgetInfo;
pub use inspector::diagnostics_enabled;
pub use inspector::init_diagnostics;
pub use inspector::is_deterministic_mode;
pub use inspector::reset_event_counter;
pub use inspector::set_diagnostics_enabled;
pub use focus::FocusEvent;
pub use focus::FocusGraph;
pub use focus::FocusGroup;
pub use focus::FocusId;
pub use focus::FocusManager;
pub use focus::FocusNode;
pub use focus::FocusTrap;
pub use focus::NavDirection;
pub use drag::DragConfig;
pub use drag::DragPayload;
pub use drag::DragState;
pub use drag::Draggable;
pub use drag::DropPosition;
pub use drag::DropResult;
pub use drag::DropTarget;
pub use stateful::StateKey;
pub use stateful::Stateful;
pub use stateful::VersionedState;
pub use list::ListPersistState;
pub use table::TablePersistState;
pub use tree::TreePersistState;
pub use virtualized::VirtualizedListPersistState;
pub use undo_support::ListOperation;
pub use undo_support::ListUndoExt;
pub use undo_support::SelectionOperation;
pub use undo_support::TableOperation;
pub use undo_support::TableUndoExt;
pub use undo_support::TextEditOperation;
pub use undo_support::TextInputUndoExt;
pub use undo_support::TreeOperation;
pub use undo_support::TreeUndoExt;
pub use undo_support::UndoSupport;
pub use undo_support::UndoWidgetId;
pub use undo_support::WidgetTextEditCmd;
pub use validation_error::ANIMATION_DURATION_MS;
pub use validation_error::ERROR_BG_DEFAULT;
pub use validation_error::ERROR_FG_DEFAULT;
pub use validation_error::ERROR_ICON_DEFAULT;
pub use validation_error::ValidationErrorDisplay;
pub use validation_error::ValidationErrorState;

Modules§

align: Alignment container widget.
badge: Badge widget (status/priority pills). Badge widget.
block: Block widget with borders, titles, and padding.
borders: Border styling primitives.
cached: Cached widget wrapper with manual invalidation and optional cache keys.
columns: Columns widget: lays out children side-by-side using Flex constraints.
command_palette: Command Palette widget for instant action search.
constraint_overlay: Constraint visualization overlay for layout debugging.
drag: Drag-and-drop protocol: Draggable sources, DropTarget targets, and DragPayload. Drag-and-drop protocol (bd-1csc.1 + bd-1csc.2).
emoji: Emoji widget for rendering emoji characters with width-aware layout.
error_boundary: Widget error boundaries with panic recovery.
fenwick: Fenwick tree (Binary Indexed Tree) for O(log n) prefix sum queries. Cache-friendly Fenwick tree (Binary Indexed Tree) for prefix sums.
file_picker: File picker widget for browsing and selecting files.
focus: Focus management: navigation graph for keyboard-driven focus traversal. Focus management: navigation graph, manager, and spatial navigation.
group: Group container widget.
height_predictor: Bayesian height prediction with conformal bounds for virtualized lists. Bayesian height prediction with conformal bounds for virtualized lists.
help: Help widget for displaying keybinding lists.
help_registry: Central registry for contextual help content.
hint_ranker: Utility-based keybinding hint ranking with Bayesian posteriors. Utility-based keybinding hint ranking with Bayesian posteriors.
history_panel: Undo/redo history panel widget for displaying command history. History panel widget for displaying undo/redo command history.
input: Text input widget.
inspector: UI Inspector overlay for debugging widget trees and hit-test regions. UI Inspector overlay for debugging widget trees and hit-test regions.
json_view: JSON view widget for pretty-printing JSON text.
keyboard_drag: Keyboard-driven drag-and-drop support (bd-1csc.4).
layout: Layout composition widget.
layout_debugger: Layout constraint debugger utilities.
list: List widget.
log_ring: Bounded circular buffer for log storage.
log_viewer: A scrolling log viewer widget optimized for streaming append-only content.
measurable: Intrinsic sizing support for content-aware layout. Intrinsic sizing support for widgets.
measure_cache: Measure cache for memoizing widget measure results. Measure cache for memoizing widget measure() results.
modal: Modal container widget (overlay layer), dialog presets, modal stack management, and animations.
notification_queue: Notification queue for managing multiple toast notifications. Notification queue manager for handling multiple concurrent toast notifications.
padding: Padding container widget.
paginator: Paginator widget.
panel: Panel widget: border + optional title/subtitle + inner padding + child content.
paragraph: Multi-line styled text paragraph widget.
pretty: Pretty-printing widget for Rust values.
progress: Progress bar widget.
rule: Horizontal rule (divider) widget.
scrollbar: Scrollbar widget.
sparkline: Sparkline widget for compact trend visualization.
spinner: Spinner widget.
stateful: Opt-in persistable state trait for widgets. Opt-in trait for widgets with persistable state.
status_line: Status line widget for agent harness UIs.
stopwatch: Stopwatch widget for displaying elapsed time.
table: Table widget with rows, columns, and selection.
textarea: Multi-line text editing widget.
timer: Countdown timer widget.
toast: Toast widget for transient notifications. Toast widget for displaying transient notifications.
tree: Tree widget for hierarchical display.
undo_support: Undo support for widgets. Undo support for widgets.
validation_error: Inline validation error display widget. Inline validation error display widget.
virtualized: Virtualization primitives for efficient rendering of large content.
voi_debug_overlay: VOI debug overlay widget (Galaxy-Brain).

Structs§

Budgeted: Budget-aware wrapper that registers widget signals and respects refresh budgets.

Traits§

StatefulWidget: A widget that renders based on mutable state.
Widget: A widget that can render itself into a Frame.