promkit

Since v0.14.0, promkit follows a decoupled architecture where orchestration is owned by the application rather than the library. This prevents key-binding conflicts and allows for complex application-specific logic (like focus management or validation) that cannot be generalized into presets.

The architecture is divided into four distinct responsibilities:

1. Prompt Lifecycle Runtime (promkit): Manages the lifecycle via initialize -> evaluate -> finalize and drives input events from a singleton EVENT_STREAM. TerminalSession handles terminal setup/teardown.
2. Application Event Policy: The developer (the application) implements the Prompt trait. This is where you define key bindings, focus transitions, validation flows, and quit conditions.
3. State Management and UI Materialization (promkit-widgets): Widgets implement the Widget trait. They are responsible for converting state into CreatedGraphemes (styled content, layout hints, and logical cursor positions). Widgets do not handle events.
4. Rendering (promkit-core): The Renderer<K> manages ordered chunks of graphemes. RendererLayout<K> handles terminal-size-dependent wrapping, pane allocation, and viewport clipping. Terminal::draw_rows performs the actual terminal I/O.

By separating these, promkit-widgets provides reusable state-to-view logic, while the application maintains full control over how those widgets interact.

promkit is designed around several key architectural principles:

• Application-owned composition: Instead of a rigid framework, you implement the Prompt lifecycle. This allows your application to own event policies like key bindings, focus, validation, and background work, combining only the specific widget states required.
• Optional runtime and terminal lifecycle: You can use an asynchronous prompt runtime or independently manage terminal states (raw mode, alternate screen, cursor visibility, mouse capture) using TerminalSession.
• Viewport-aware rendering: The promkit-core crate handles complex UI tasks like text wrapping/truncation, vertical pane allocation, cursor scrolling, clipping, resizing, and screen-to-widget hit testing.
• Efficient large-content projection: For heavy data formats like JSON, YAML, and CSV, widgets project only the visible terminal viewport to maintain performance during redraws.
• Feature-gated architecture: Modules are gated by Cargo features. You should only enable the runtime, terminal session, capabilities, and specific widgets your application actually uses.

The Prompt::run method provides a standard lifecycle for driving a terminal UI. The loop observes events from a singleton EVENT_STREAM, passes them to the application's evaluate implementation, and continues until a Signal::Quit is returned or an error occurs.

Lifecycle Stages:

1. initialize(): Setup phase.
2. evaluate(&event): The core loop where events are processed and state is updated.
3. finalize(): Teardown phase.

Data Flow Pattern: To update the UI, an application typically follows this flow within the evaluate loop:

1. Update widget states based on the event.
2. Call Widget::create_graphemes to get new content.
3. Call Renderer::update to modify the renderer's chunks.
4. Call Renderer::render to perform layout and drawing.

Note: In the current Prompt::run implementation, resize events are skipped in the main loop and should be handled via other mechanisms (like the terminal session or specific resize logic) to ensure stability.

self.initialize().await?;

while let Some(event) = EVENT_STREAM.lock().await.next().await {
    match event {
        Ok(event) => {
            if event.is_resize() {
                continue;
            }

            if self.evaluate(&event).await? == Signal::Quit {
                break;
            }
        }
        Err(_) => break,
    }
}

self.finalize()

The TextEditor struct provides a high-level API for managing text in a terminal environment, supporting basic editing operations like insertion, deletion, overwriting, and cursor movement. It handles complex terminal concerns such as grapheme clusters and display widths (columns) automatically.

Key Capabilities

• Editing: Insert characters, newlines, or overwrite existing text.
• Navigation: Move the cursor by index, by logical row/column, or to the head/tail of the text/lines.
• Deletion: Erase characters before or after the cursor, or erase to specific boundaries (like word breaks).
• Masking: Mask all characters except the cursor with a specific character (useful for password fields).
• Logical Positioning: Translate between absolute grapheme indices and logical TextPosition (row and column) based on terminal display width.

// Initialize a new editor with text
let mut editor = TextEditor::new("Hello World");

// Insert text
editor.insert('!');

// Move cursor
editor.move_to_tail();

editor.move_up();

TerminalSession is used to manage terminal states (like raw mode, alternate screen, cursor visibility, and mouse capture) for interactive applications.

When you create a session using TerminalSession::try_new, it applies the requested modes. The session is designed to be RAII-compliant: when the TerminalSession instance is dropped, it automatically attempts to restore the terminal to its original state. This restoration is also triggered during panic unwinding to prevent leaving the user's terminal in a broken state.

Key behaviors:

• Automatic Restoration: Dropping the session restores all applied modes.
• Error Resilience: If setup fails halfway through, TerminalSession attempts to roll back all previously applied modes before returning the error.
• Manual Restoration: You can call .restore() manually to return the terminal to its original state.
• Panic Safety: Restoration is attempted even if the application panics.

use promkit::{TerminalModes, TerminalSession};

fn run() -> std::io::Result<()> {
    // Define the modes you want to enable
    let modes = TerminalModes::RAW_MODE
        | TerminalModes::HIDDEN_CURSOR
        | TerminalModes::MOUSE_CAPTURE;

    // Start the session. The session will automatically restore the terminal when dropped.
    let _session = TerminalSession::try_new(modes)?;

    // Run your application's event loop here...

    Ok(())
}