tui_panel_select/
lib.rs

1//! Panel-scoped text selection and clipboard copy for [ratatui] apps.
2//!
3//! A terminal's own click-drag selection can't be confined to one panel — it
4//! spans the full terminal row, sweeping up borders and neighbouring panels.
5//! This crate lets an app capture the mouse itself and implement its own
6//! selection that is **confined to a single panel's rectangle**, uses natural
7//! "stream" semantics (never a rectangular block), **survives resizes,
8//! rewraps and scrolling** (selections are stored as logical line/column
9//! positions, not stale screen cells), and stays cheap even for
10//! multi-megabyte content (only what's on screen is ever wrapped or painted).
11//! On mouse-up the selected text is copied to the system clipboard, working
12//! both on a local desktop and over SSH/tmux (OSC 52 fallback).
13//!
14//! # Two ways to use it
15//!
16//! **Batteries-included:** [`SelectablePanel`] bundles the cache and
17//! selection state into one object with a tiny API — `set_content`,
18//! `begin_selection`, `extend_selection`, `selected_text`, `copy_selection`,
19//! `highlight_cells`, `visible_rows`. See its module for a worked example.
20//! [`MultiSelectPanel`] is a richer sibling for panels that need **multiple
21//! selection regions**, **keyboard extension**, **owned scrolling with drag
22//! auto-scroll**, and **styled (syntax-highlighted) content**.
23//!
24//! **Primitives:** if your app already owns its selection state (e.g. you
25//! support multiple simultaneous selections or keyboard extension), use the
26//! stateless building blocks directly:
27//! - [`PanelWrap`] / [`TextPos`] — the line/wrap cache and logical positions
28//!   ([`wrapcache`]).
29//! - [`selection`] — pure functions: `point_to_textpos`, `extract_text`,
30//!   `highlight_cells`, `strip_positions`.
31//! - [`clipboard`] — `copy_to_clipboard` (local tool + OSC 52 fallback).
32//! - [`wrap`] — the underlying character-exact line-wrapping helpers.
33//!
34//! # Optional scrollbar
35//!
36//! With the default-on `scrollbar` feature, [`scrollbar`] adds a
37//! panel-agnostic vertical scrollbar: [`scroll_for_track_row`] maps a
38//! track click/drag to a scroll offset and [`render_scrollbar`] draws the
39//! thumb. [`MultiSelectPanel`] gains `scroll_to_track_row` /
40//! `render_scrollbar` convenience wrappers that plumb their own geometry in.
41//!
42//! [ratatui]: https://docs.rs/ratatui
43
44pub mod clipboard;
45pub mod multiselect;
46pub mod panel;
47#[cfg(feature = "scrollbar")]
48pub mod scrollbar;
49pub mod selection;
50#[cfg(feature = "terminal-guard")]
51pub mod terminal;
52pub mod wrap;
53pub mod wrapcache;
54
55pub use multiselect::{AutoScroll, Motion, MultiSelectPanel};
56pub use panel::{MouseAction, MouseConfig, SelectablePanel};
57#[cfg(feature = "scrollbar")]
58pub use scrollbar::{ScrollbarStyle, render_scrollbar, scroll_for_track_row};
59#[cfg(feature = "terminal-guard")]
60pub use terminal::TerminalGuard;
61pub use wrapcache::{PanelWrap, TextPos, WrapMarker, WrapMode};
tui_panel_select/lib.rs

tui_panel_select/
lib.rs
