tui_prompts/lib.rs
1//! A [Ratatui] widget set for friendly prompts and input flows. Part of the [tui-widgets] suite by
2//! [Joshka].
3//!
4//! [![Crate badge]][Crate]
5//! [![Docs Badge]][Docs]
6//! [![Deps Badge]][Dependency Status]
7//! [![License Badge]][License]
8//! [![Coverage Badge]][Coverage]
9//! [![Discord Badge]][Ratatui Discord]
10//!
11//! [GitHub Repository] · [API Docs] · [Examples] · [Changelog] · [Contributing]
12//!
13//! # Installation
14//!
15//! ```shell
16//! cargo add ratatui tui-prompts crossterm
17//! ```
18//!
19//! # Usage
20//!
21//! Pick a prompt type, keep its state, and render it inside your UI.
22//!
23//! ## Text Prompt
24//!
25//! <details>
26//! <summary>Code</summary>
27//!
28//! ```rust
29//! use ratatui::layout::{Constraint, Direction, Layout, Rect};
30//! use ratatui::Frame;
31//! use tui_prompts::{Prompt, TextPrompt, TextRenderStyle, TextState};
32//!
33//! struct App<'a> {
34//! username_state: TextState<'a>,
35//! password_state: TextState<'a>,
36//! invisible_state: TextState<'a>,
37//! }
38//!
39//! impl<'a> App<'a> {
40//! fn draw_ui(&mut self, frame: &mut Frame) {
41//! let (username_area, password_area, invisible_area) = split_layout(frame.area());
42//!
43//! TextPrompt::from("Username")
44//! .draw(frame, username_area, &mut self.username_state);
45//!
46//! TextPrompt::from("Password")
47//! .with_render_style(TextRenderStyle::Password)
48//! .draw(frame, password_area, &mut self.password_state);
49//!
50//! TextPrompt::from("Invisible")
51//! .with_render_style(TextRenderStyle::Invisible)
52//! .draw(frame, invisible_area, &mut self.invisible_state);
53//! }
54//! }
55//!
56//! fn split_layout(area: Rect) -> (Rect, Rect, Rect) {
57//! let rows = Layout::default()
58//! .direction(Direction::Vertical)
59//! .constraints([
60//! Constraint::Length(1),
61//! Constraint::Length(1),
62//! Constraint::Length(1),
63//! ])
64//! .split(area);
65//! (rows[0], rows[1], rows[2])
66//! }
67//! ```
68//!
69//! </details>
70//!
71//! 
72//!
73//! See the [text example] for more details.
74//!
75//! ## Soft Wrapping
76//!
77//! Text is automatically character wrapped to fit in the render area.
78//!
79//! 
80//!
81//! See the [multi line example] for more details.
82//!
83//! # Features
84//!
85//! - [x] Text prompt
86//! - [x] Password prompt
87//! - [x] Invisible prompt
88//! - [x] Readline / emacs style Key Bindings
89//! - [x] Crossterm backend
90//! - [x] Soft wrapping single lines
91//! - [ ] Multi-line input
92//! - [ ] Scrolling
93//! - [ ] More prompt types:
94//! - [ ] Number
95//! - [ ] Confirm
96//! - [ ] List
97//! - [ ] Toggle
98//! - [ ] Select
99//! - [ ] Multi-select
100//! - [ ] Autocomplete
101//! - [ ] Autocomplete multi-select
102//! - [ ] Date
103//! - [ ] Bracketed paste
104//! - [ ] Validation
105//! - [ ] Default initial value
106//! - [ ] Custom style
107//! - [ ] Themes
108//! - [ ] Custom formatting
109//! - [ ] Backend agnostic keyboard event handling
110//! - [Termion]
111//! - [Termwiz]
112//! - [ ] Customizable key bindings
113//! - [ ] Handle more advanced multi-key bindings e.g. `^[b` and `^[f`
114//! - [ ] Prompt chaining
115//!
116//! # Key Bindings
117//!
118//! | Key | Action |
119//! | --- | --- |
120//! | Home, Ctrl+A | Move cursor to beginning of line |
121//! | End, Ctrl+E | Move cursor to end of line |
122//! | Left, Ctrl+B | Move cursor one character left |
123//! | Right, Ctrl+F | Move cursor one character right |
124//! | Backspace (Delete on Mac), Ctrl+H | Delete character before cursor |
125//! | Delete (Fn+Delete on Mac), Ctrl+D | Delete character at cursor |
126//! | Ctrl+K | Delete all characters from the cursor to the end of line |
127//! | Ctrl+U | Delete the entire line |
128//! | Enter | Complete the prompt |
129//! | Escape, Ctrl+C | Abort the prompt |
130//!
131//! # More widgets
132//!
133//! For the full suite of widgets, see [tui-widgets].
134//!
135//! [Joshka]: https://github.com/joshka
136//! [tui-widgets]: https://crates.io/crates/tui-widgets
137//! [Crate]: https://crates.io/crates/tui-prompts
138//! [Docs]: https://docs.rs/tui-prompts/
139//! [Dependency Status]: https://deps.rs/repo/github/ratatui/tui-widgets
140//! [Coverage]: https://app.codecov.io/gh/ratatui/tui-widgets
141//! [Ratatui Discord]: https://discord.gg/pMCEU9hNEj
142//! [GitHub Repository]: https://github.com/ratatui/tui-widgets
143//! [API Docs]: https://docs.rs/tui-prompts/
144//! [Examples]: https://github.com/ratatui/tui-widgets/tree/main/tui-prompts/examples
145//! [text example]: https://github.com/ratatui/tui-widgets/tree/main/tui-prompts/examples/text.rs
146//! [multi line example]: https://github.com/ratatui/tui-widgets/tree/main/tui-prompts/examples/multi_line.rs
147//! [Changelog]: https://github.com/ratatui/tui-widgets/blob/main/tui-prompts/CHANGELOG.md
148//! [Contributing]: https://github.com/ratatui/tui-widgets/blob/main/CONTRIBUTING.md
149//! [Crate badge]: https://img.shields.io/crates/v/tui-prompts?logo=rust&style=flat
150//! [Docs Badge]: https://img.shields.io/docsrs/tui-prompts?logo=rust&style=flat
151//! [Deps Badge]: https://deps.rs/repo/github/ratatui/tui-widgets/status.svg?style=flat
152//! [License Badge]: https://img.shields.io/crates/l/tui-prompts?style=flat
153//! [License]: https://github.com/ratatui/tui-widgets/blob/main/LICENSE-MIT
154//! [Coverage Badge]:
155//! https://img.shields.io/codecov/c/github/ratatui/tui-widgets?logo=codecov&style=flat
156//! [Discord Badge]:
157//! https://img.shields.io/discord/1070692720437383208?logo=discord&style=flat
158//! [Ratatui]: https://crates.io/crates/ratatui
159//! [Termion]: https://crates.io/crates/termion
160//! [Termwiz]: https://crates.io/crates/termwiz
161
162mod prompt;
163mod status;
164
165mod text_prompt;
166mod text_state;
167
168pub use prompt::*;
169pub use status::*;
170pub use text_prompt::*;
171pub use text_state::*;
172
173pub mod prelude {
174 pub use crate::{FocusState, Prompt, State, Status, TextPrompt, TextRenderStyle, TextState};
175}