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//!   plus [`set_clipboard_mode`] to pin or disable the mechanism.
33//! - [`wrap`] — the underlying character-exact line-wrapping helpers.
34//!
35//! # Optional scrollbar
36//!
37//! With the default-on `scrollbar` feature, [`scrollbar`] adds a
38//! panel-agnostic vertical scrollbar: [`scroll_for_track_row`] maps a
39//! track click/drag to a scroll offset and [`render_scrollbar`] draws the
40//! thumb. [`MultiSelectPanel`] gains `scroll_to_track_row` /
41//! `render_scrollbar` convenience wrappers that plumb their own geometry in.
42//!
43//! [ratatui]: https://docs.rs/ratatui
44
45pub mod clipboard;
46pub mod multiselect;
47pub mod panel;
48#[cfg(feature = "scrollbar")]
49pub mod scrollbar;
50pub mod selection;
51#[cfg(feature = "terminal-guard")]
52pub mod terminal;
53pub mod wrap;
54pub mod wrapcache;
55
56pub use clipboard::{ClipboardMode, set_clipboard_mode};
57pub use multiselect::{AutoScroll, Motion, MultiSelectPanel};
58pub use panel::{MouseAction, MouseConfig, SelectablePanel};
59#[cfg(feature = "scrollbar")]
60pub use scrollbar::{ScrollbarStyle, render_scrollbar, scroll_for_track_row};
61#[cfg(feature = "terminal-guard")]
62pub use terminal::TerminalGuard;
63pub use wrapcache::{PanelWrap, TextPos, WrapMarker, WrapMode};
tui_panel_select/lib.rs

tui_panel_select/
lib.rs
