tui-panel-select

Panel-scoped mouse text selection and clipboard copy for ratatui apps.

A terminal's own click-drag selection can't be confined to one panel — it spans the full terminal row, sweeping up borders and neighbouring panels. This crate lets your app capture the mouse itself and implement a selection that is:

Confined to a single panel's rectangle — never spills into other panels or the border.
Natural "stream" selection — first line from the click column to its end, full lines in between, last line up to the release column (never a rectangular block).
Stable across resize / rewrap / scroll — selections are stored as logical (line, column) positions, not stale screen cells, so the same characters stay selected when the panel is resized or rewrapped.
Cheap on huge content — only the rows actually on screen are ever wrapped or painted, so a multi-megabyte body (or one enormous unbroken line) stays responsive.
Copy that works locally and remotely — on mouse-up the text is copied via a local clipboard tool (xclip/xsel/wl-copy/pbcopy/clip.exe) when available, falling back to an OSC 52 escape sequence for SSH/tmux sessions. Pin or disable the mechanism with set_clipboard_mode or the TUI_PANEL_SELECT_CLIPBOARD environment variable — see Choosing the clipboard backend.

Quick start — the batteries-included API

use std::sync::Arc;
use ratatui::layout::Rect;
use tui_panel_select::SelectablePanel;

let mut panel = SelectablePanel::new();

// Each frame, before drawing, give the panel its text and inner width.
panel.set_content(Arc::from("hello world\nsecond line"), 40);

// The panel's inner text area on screen, and its scroll offset (wrapped rows).
let area = Rect::new(1, 1, 40, 10);
let scroll = 0;

// Mouse down starts a selection; drag extends it; up copies it.
panel.begin_selection(area, scroll, (1, 1));   // click at 'h'
panel.extend_selection(area, scroll, (5, 1));  // drag to 'o'
assert_eq!(panel.selected_text().as_deref(), Some("hello"));
panel.copy_selection();                         // -> system clipboard

Rendering each frame:

# use tui_panel_select::SelectablePanel;
# use ratatui::layout::Rect;
# let panel = SelectablePanel::new();
# let area = Rect::new(0, 0, 40, 10);
# let scroll = 0u16;
// 1. Draw the visible wrapped rows into your panel:
let rows = panel.visible_rows(scroll, area.height);

// 2. Paint the highlight over the selected cells:
for (row, col_from, col_to) in panel.highlight_cells(area, scroll) {
    // invert/style cells [col_from, col_to) on terminal row `row`
}

Wire these into your event loop: capture the mouse (EnableMouseCapture), then call begin_selection on MouseEventKind::Down, extend_selection on Drag, and copy_selection on Up. Call set_content every frame — it only rebuilds its cache when the text (by Arc identity) or width actually changed.

Opt-in mouse handler

If you'd rather not wire the three events up yourself, handle_mouse does the common "drag to select, release to copy" flow in one call. Behaviour is configured per-application via MouseConfig (e.g. copy_on_release), and the low-level methods above stay available:

# use tui_panel_select::{MouseConfig, SelectablePanel};
# use ratatui::layout::Rect;
# use ratatui::crossterm::event::MouseEvent;
# fn demo(panel: &mut SelectablePanel, area: Rect, scroll: u16, ev: MouseEvent) {
let cfg = MouseConfig::default(); // copy_on_release: true
let _action = panel.handle_mouse(ev, area, scroll, &cfg);
# }

Panic-safe terminal guard (feature `terminal-guard`, on by default)

Enabling panel selection means turning on the terminal's mouse-tracking mode, which must be undone on exit and on any panic — otherwise the user's shell is left spewing tracking escape sequences. TerminalGuard centralises that: it enables mouse capture (and, optionally, the keyboard-enhancement protocol), wraps the panic hook, and restores everything on drop:

# fn main() -> std::io::Result<()> {
use tui_panel_select::TerminalGuard;

let mut terminal = ratatui::init();
let guard = TerminalGuard::install(true)?;
// ... run your event loop ...
drop(guard);           // restores mouse capture / keyboard flags
ratatui::restore();
# Ok(())
# }

Disable the terminal-guard feature (default-features = false) if you only want the pure selection/wrapping logic without the process-global panic hook.

Line layout: wrap or clip (`WrapMode`)

By default each raw line wider than the panel is wrapped onto multiple rows. For panels that show pre-formatted, column-aligned output (e.g. program output echoed verbatim), call set_wrap_mode(WrapMode::Clip) instead: every raw line then occupies exactly one screen row and anything past the right edge is clipped. Selection, copy and scrolling all follow suit (scrolling moves by whole lines, one row per line).

# use tui_panel_select::{SelectablePanel, WrapMode};
let mut panel = SelectablePanel::new();
panel.set_wrap_mode(WrapMode::Clip);

End of line wrap marker (`WrapMarker)

There is an optional WrapMarker that can be added to a SelectablePanel. The WrapMarker can be built with the WrapMarkerBuilder like so:

# use tui_panel_select::{SelectablePanel, WrapMode, WrapMarker};
let mut panel = SelectablePanel::new();
panel.set_wrap_mode(WrapMode::Wrap);
let wrap_marker = WrapMarker::builder().glyph('>').build();
panel.set_wrap_marker(wrap_marker);

Vertical scrollbar (feature `scrollbar`, on by default)

Two panel-agnostic helpers wire up a native-feeling vertical scrollbar for any scrollable content:

scroll_for_track_row(track, row, max_scroll) maps a click or drag anywhere in the scrollbar track to a scroll offset (proportional, clamped to the track), so dragging the thumb — or clicking anywhere along it — jumps there.
render_scrollbar(area, buf, total, capacity, start, &style) draws a ratatui scrollbar into a track column, sizing the thumb from the content totals and no-op-ing when everything already fits.

A MultiSelectPanel (which owns its scroll offset) has convenience wrappers that plumb their own geometry in:

# use tui_panel_select::{MultiSelectPanel, ScrollbarStyle};
# use ratatui::{buffer::Buffer, layout::Rect, style::{Style, Color}};
# fn demo(panel: &mut MultiSelectPanel, track: Rect, clicked_row: u16, buf: &mut Buffer) {
// On a scrollbar click/drag: jump/scroll to that row.
panel.scroll_to_track_row(track, clicked_row);

// Each frame: draw the bar (styled to taste; a no-op when content fits).
let style = ScrollbarStyle {
    track_style: Style::default().fg(Color::DarkGray),
    thumb_style: Style::default().fg(Color::Cyan),
    ..ScrollbarStyle::default()
};
panel.render_scrollbar(track, buf, &style);
# }

Disable the feature (default-features = false) if you draw your own indicator.

ANSI-coloured content (feature `ansi`, off by default)

If your panel text contains ANSI escape sequences (e.g. coloured program output), enable the ansi feature and feed it via set_ansi_content instead of set_content. Rendered rows (visible_rows) keep their colour, while selection, copy and all geometry operate on the plain, stripped text — so you don't have to maintain a second, un-coloured copy yourself:

tui-panel-select = { version = "0.1", features = ["ansi"] }

# use std::sync::Arc;
# use tui_panel_select::{SelectablePanel, WrapMode};
# fn demo(panel: &mut SelectablePanel, colored: Arc<str>, width: usize) {
panel.set_wrap_mode(WrapMode::Clip);      // often paired with clip for verbatim output
panel.set_ansi_content(colored, width);   // escapes parsed once, colour preserved
# }

Low-level primitives

If your app already owns its selection state (e.g. multiple simultaneous selections, keyboard-extended selection, excluding decorative characters from the copied text), skip SelectablePanel and use the stateless building blocks directly:

[wrapcache::PanelWrap] / [wrapcache::TextPos] — the line/wrap cache and logical positions, with conversions between screen and logical space.
[selection] — pure functions: point_to_textpos, extract_text, highlight_cells, strip_positions.
[clipboard::copy_to_clipboard] — local tool + OSC 52 fallback.
[wrap] — the underlying character-exact line-wrapping helpers.

Choosing the clipboard backend

copy_to_clipboard tries a local clipboard tool first and only falls back to OSC 52. That order is deliberate: writing an OSC 52 sequence to stdout always "succeeds" whether or not the terminal acts on it, so there is no failure to detect and nothing to fall back from — preferring it would silently drop the copy on the many terminals that ignore it (GNOME Terminal/VTE among them).

When both an X11 display and a Wayland display are reachable, the X11 tools are tried first. Setting the Wayland selection needs a serial from an input event, so it needs keyboard focus and therefore a mapped surface, unless the compositor implements wlr-data-control — which GNOME does not. Under GNOME, wl-copy consequently maps a real window and the desktop lists it as a running application for as long as it owns the selection, flashing an entry into the app bar on every copy. An X11 selection owner needs no mapped window, and XWayland's clipboard bridge still propagates the selection to Wayland clients.

Override the choice with TUI_PANEL_SELECT_CLIPBOARD (auto, x11, wayland, osc52, none) or, from code, set_clipboard_mode:

use tui_panel_select::{ClipboardMode, set_clipboard_mode};

// Compositor with XWayland but no clipboard bridging? Force the native path.
set_clipboard_mode(ClipboardMode::Wayland);

Test suites should disable it. Copying reaches the real system clipboard, so any test that exercises a copy path will overwrite whatever the developer had copied — and each spawned helper must be reaped or it lingers as an unkillable zombie. Disable it once during test setup:

use tui_panel_select::{ClipboardMode, set_clipboard_mode};

set_clipboard_mode(ClipboardMode::None);

License

MIT

tui-panel-select 0.1.6