ratatui-labs

Experimental Ratatui labs-style APIs and prototype Ratatui work.

This crate is a Ratatui namespace reservation that can host small experiments before they are ready to move into focused crates or the main Ratatui repository. APIs in this crate are experimental and may change or disappear.

ratatui-labs is not intended to become a broad implementation crate. When an experiment grows a clear concept boundary, prefer a focused crate with its own crate-level documentation, examples, and validation. This crate can then provide a short compatibility namespace for the experiment while the API is evaluated.

Command Palette Experiment

The command palette experiment now lives in two concept-owned crates:

ratatui-action for semantic action identity, metadata, availability, inputs, and invocations.
ratatui-command-palette for palette state, filtering, selection, and event emission.

The palette does not own application state or execute application callbacks. It consumes action metadata and emits invocation, preview, and lifecycle events that the application handles.

use ratatui_labs::{
    action::spec::ActionSpec,
    command_palette::{event::PaletteEvent, state::PaletteState},
};

let actions = vec![ActionSpec::new("document.open", "Open document")];
let mut palette = PaletteState::new();
palette.open(&actions);

if let Some(PaletteEvent::Invoke(invocation)) = palette.accept(&actions) {
    assert_eq!(invocation.id().as_str(), "document.open");
}

Run the first interactive example with:

cargo run -p ratatui-command-palette --example command-palette
cargo run -p ratatui-command-palette --example command-palette -- --help
cargo run -p ratatui-command-palette --example command-palette -- --renderer split

Rendered validation for this example is captured by the repository Betamax tape:

just betamax

Layout Experiment

The frame-local layout coordination experiment lives in ratatui-layout. It records visible regions, focus targets, pointer targets, cursor requests, viewport metadata, and scroll metrics produced by a render pass so applications can route later input events without adopting a retained widget tree.

Start with ratatui_layout::docs when exploring the coordination model, or use the umbrella re-export:

use ratatui_labs::layout::{
    frame::FrameSnapshot,
    pointer::{PointerTarget, PointerTargets},
};
use ratatui_core::layout::Rect;

let frame = FrameSnapshot::new(Rect::new(0, 0, 20, 1))
    .mouse(PointerTargets::new().target(PointerTarget::new("save", Rect::new(0, 0, 6, 1))));

assert_eq!(frame.route_position((2, 0)).unwrap().id, "save");

Text Wrapping Experiment

The ratatui-textwrap experiment materializes styled Span, Line, and Text inputs as owned, wrapped text. The umbrella crate exposes it as ratatui_labs::textwrap; the focused ratatui-textwrap README is the canonical usage guide.

use ratatui_core::text::Line;
use ratatui_labs::textwrap::{TextWrapper, WrapAlgorithm};

let wrapping = TextWrapper::new().algorithm(WrapAlgorithm::OptimalFit);
let wrapped = wrapping.wrap(Line::from("alpha beta"), 8);
assert_eq!(wrapped.lines.len(), 2);

Custom widgets can call textwrap::algorithms::paragraph::wrap_line or the line-level first-fit and optimal-fit functions without constructing a complete Text.

The crate points at the main Ratatui project rather than a separate implementation repository:

Documentation for this reservation crate is published at:

https://docs.rs/ratatui-labs

Derive Macro Experiment

The derive macro experiment lives in ratatui-derive. It currently provides FromRect, a proc macro for named layout-area structs that generates impl From<Rect> for YourStruct.

The API is experimental and published with a beta version while the name, attribute grammar, and generated public contract are evaluated in real applications.

use ratatui_core::layout::Rect;
use ratatui_labs::derive::FromRect;

#[derive(FromRect)]
#[layout(horizontal, spacing = 2, crate = ratatui_core)]
struct ButtonDemoAreas {
    #[length(46)]
    gallery: Rect,

    #[min(34)]
    debug: Rect,
}

let area = Rect::new(0, 0, 100, 20);
let areas = ButtonDemoAreas::from(area);
assert_eq!(areas.gallery.width, 46);

Related Crates And Overlap

This reservation may overlap with:

ratatui-unstable, ratatui-experimental, and future unstable API policy.
the experimental ratatui-action and ratatui-command-palette crates in this workspace.
the experimental ratatui-layout crate in this workspace.
the experimental ratatui-textwrap crate in this workspace.