feat(prelude): add a prelude (#304)

This allows users of the library to easily use ratatui without a huge amount of imports

examples/barchart.rs

@@ -9,13 +9,7 @@ use crossterm::{
     execute,
     terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
 };
-use ratatui::{
-    backend::{Backend, CrosstermBackend},
-    layout::{Constraint, Direction, Layout},
-    style::{Color, Modifier, Style},
-    widgets::{BarChart, Block, Borders},
-    Frame, Terminal,
-};
+use ratatui::prelude::*;
 
 struct App<'a> {
     data: Vec<(&'a str, u64)>,

examples/block.rs

@@ -5,13 +5,7 @@ use crossterm::{
     execute,
     terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
 };
-use ratatui::{
-    backend::{Backend, CrosstermBackend},
-    layout::{Alignment, Constraint, Direction, Layout},
-    style::{Color, Style, Stylize},
-    widgets::{block::title::Title, Block, BorderType, Borders, Padding, Paragraph},
-    Frame, Terminal,
-};
+use ratatui::prelude::*;
 
 fn main() -> Result<(), Box<dyn Error>> {
     // setup terminal
@@ -61,7 +55,7 @@ fn ui<B: Backend>(f: &mut Frame<B>) {
     // Surrounding block
     let block = Block::default()
         .borders(Borders::ALL)
-        .title(Title::from("Main block with round corners").alignment(Alignment::Center))
+        .title(BlockTitle::from("Main block with round corners").alignment(Alignment::Center))
         .border_type(BorderType::Rounded);
     f.render_widget(block, size);
 
@@ -84,8 +78,9 @@ fn ui<B: Backend>(f: &mut Frame<B>) {
     f.render_widget(block, top_chunks[0]);
 
     // Top right inner block with styled title aligned to the right
-    let block = Block::default()
-        .title(Title::from("Styled title".white().on_red().bold()).alignment(Alignment::Right));
+    let block = Block::default().title(
+        BlockTitle::from("Styled title".white().on_red().bold()).alignment(Alignment::Right),
+    );
     f.render_widget(block, top_chunks[1]);
 
     // Bottom two inner blocks

examples/calendar.rs

@@ -5,13 +5,7 @@ use crossterm::{
     execute,
     terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
 };
-use ratatui::{
-    backend::{Backend, CrosstermBackend},
-    layout::{Constraint, Direction, Layout, Rect},
-    style::{Color, Modifier, Style},
-    widgets::calendar::{CalendarEventStore, DateStyler, Monthly},
-    Frame, Terminal,
-};
+use ratatui::prelude::*;
 use time::{Date, Month, OffsetDateTime};
 
 fn main() -> Result<(), Box<dyn Error>> {

examples/canvas.rs

@@ -9,17 +9,7 @@ use crossterm::{
     execute,
     terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
 };
-use ratatui::{
-    backend::{Backend, CrosstermBackend},
-    layout::{Constraint, Direction, Layout, Rect},
-    style::{Color, Stylize},
-    symbols::Marker,
-    widgets::{
-        canvas::{Canvas, Map, MapResolution, Rectangle},
-        Block, Borders,
-    },
-    Frame, Terminal,
-};
+use ratatui::prelude::*;
 
 struct App {
     x: f64,

examples/chart.rs

@@ -9,15 +9,7 @@ use crossterm::{
     execute,
     terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
 };
-use ratatui::{
-    backend::{Backend, CrosstermBackend},
-    layout::{Constraint, Direction, Layout},
-    style::{Color, Modifier, Style, Stylize},
-    symbols,
-    text::Span,
-    widgets::{Axis, Block, Borders, Chart, Dataset, GraphType},
-    Frame, Terminal,
-};
+use ratatui::prelude::*;
 
 const DATA: [(f64, f64); 5] = [(0.0, 0.0), (1.0, 1.0), (2.0, 2.0), (3.0, 3.0), (4.0, 4.0)];
 const DATA2: [(f64, f64); 7] = [

examples/custom_widget.rs

@@ -5,14 +5,7 @@ use crossterm::{
     execute,
     terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
 };
-use ratatui::{
-    backend::{Backend, CrosstermBackend},
-    buffer::Buffer,
-    layout::Rect,
-    style::Style,
-    widgets::Widget,
-    Frame, Terminal,
-};
+use ratatui::prelude::*;
 
 #[derive(Default)]
 struct Label<'a> {

examples/demo/app.rs

@@ -2,7 +2,7 @@ use rand::{
     distributions::{Distribution, Uniform},
     rngs::ThreadRng,
 };
-use ratatui::widgets::ListState;
+use ratatui::prelude::*;
 
 const TASKS: [&str; 24] = [
     "Item1", "Item2", "Item3", "Item4", "Item5", "Item6", "Item7", "Item8", "Item9", "Item10",

examples/demo/crossterm.rs

@@ -9,10 +9,7 @@ use crossterm::{
     execute,
     terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
 };
-use ratatui::{
-    backend::{Backend, CrosstermBackend},
-    Terminal,
-};
+use ratatui::prelude::*;
 
 use crate::{app::App, ui};
 

examples/demo/termion.rs

@@ -1,9 +1,6 @@
 use std::{error::Error, io, sync::mpsc, thread, time::Duration};
 
-use ratatui::{
-    backend::{Backend, TermionBackend},
-    Terminal,
-};
+use ratatui::prelude::*;
 use termion::{
     event::Key,
     input::{MouseTerminal, TermRead},

examples/demo/termwiz.rs

@@ -4,7 +4,7 @@ use std::{
     time::{Duration, Instant},
 };
 
-use ratatui::{backend::TermwizBackend, Terminal};
+use ratatui::prelude::*;
 use termwiz::{input::*, terminal::Terminal as TermwizTerminal};
 
 use crate::{app::App, ui};

examples/demo/ui.rs

@@ -1,16 +1,4 @@
-use ratatui::{
-    backend::Backend,
-    layout::{Constraint, Direction, Layout, Rect},
-    style::{Color, Modifier, Style},
-    symbols,
-    text::{Line, Span},
-    widgets::{
-        canvas::{Canvas, Circle, Line as CanvasLine, Map, MapResolution, Rectangle},
-        Axis, BarChart, Block, Borders, Cell, Chart, Dataset, Gauge, LineGauge, List, ListItem,
-        Paragraph, Row, Sparkline, Table, Tabs, Wrap,
-    },
-    Frame,
-};
+use ratatui::prelude::*;
 
 use crate::app::App;
 

examples/gauge.rs

@@ -9,14 +9,7 @@ use crossterm::{
     execute,
     terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
 };
-use ratatui::{
-    backend::{Backend, CrosstermBackend},
-    layout::{Constraint, Direction, Layout},
-    style::{Color, Modifier, Style},
-    text::Span,
-    widgets::{Block, Borders, Gauge},
-    Frame, Terminal,
-};
+use ratatui::prelude::*;
 
 struct App {
     progress1: u16,

examples/hello_world.rs

@@ -9,7 +9,7 @@ use crossterm::{
     execute,
     terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
 };
-use ratatui::{backend::CrosstermBackend, widgets::Paragraph, Terminal};
+use ratatui::prelude::*;
 
 /// This is a bare minimum example. There are many approaches to running an application loop, so
 /// this is not meant to be prescriptive. It is only meant to demonstrate the basic setup and

examples/inline.rs

@@ -8,15 +8,7 @@ use std::{
 };
 
 use rand::distributions::{Distribution, Uniform};
-use ratatui::{
-    backend::{Backend, CrosstermBackend},
-    layout::{Alignment, Constraint, Direction, Layout, Rect},
-    style::{Color, Modifier, Style},
-    symbols,
-    text::{Line, Span},
-    widgets::{block::title::Title, Block, Gauge, LineGauge, List, ListItem, Paragraph, Widget},
-    Frame, Terminal, TerminalOptions, Viewport,
-};
+use ratatui::prelude::*;
 
 const NUM_DOWNLOADS: usize = 10;
 
@@ -227,7 +219,7 @@ fn run_app<B: Backend>(
 fn ui<B: Backend>(f: &mut Frame<B>, downloads: &Downloads) {
     let size = f.size();
 
-    let block = Block::default().title(Title::from("Progress").alignment(Alignment::Center));
+    let block = Block::default().title(BlockTitle::from("Progress").alignment(Alignment::Center));
     f.render_widget(block, size);
 
     let chunks = Layout::default()

examples/layout.rs

@@ -5,12 +5,7 @@ use crossterm::{
     execute,
     terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
 };
-use ratatui::{
-    backend::{Backend, CrosstermBackend},
-    layout::{Constraint, Direction, Layout},
-    widgets::{Block, Borders},
-    Frame, Terminal,
-};
+use ratatui::prelude::*;
 
 fn main() -> Result<(), Box<dyn Error>> {
     // setup terminal

examples/list.rs

@@ -9,14 +9,7 @@ use crossterm::{
     execute,
     terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
 };
-use ratatui::{
-    backend::{Backend, CrosstermBackend},
-    layout::{Constraint, Corner, Direction, Layout},
-    style::{Color, Modifier, Style, Stylize},
-    text::{Line, Span},
-    widgets::{Block, Borders, List, ListItem, ListState},
-    Frame, Terminal,
-};
+use ratatui::prelude::*;
 
 struct StatefulList<T> {
     state: ListState,

examples/panic.rs

@@ -23,13 +23,7 @@ use crossterm::{
     event::{self, Event, KeyCode},
     terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
 };
-use ratatui::{
-    backend::{Backend, CrosstermBackend},
-    layout::Alignment,
-    text::Line,
-    widgets::{Block, Borders, Paragraph},
-    Frame, Terminal,
-};
+use ratatui::prelude::*;
 
 type Result<T> = std::result::Result<T, Box<dyn Error>>;
 

examples/paragraph.rs

@@ -9,14 +9,7 @@ use crossterm::{
     execute,
     terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
 };
-use ratatui::{
-    backend::{Backend, CrosstermBackend},
-    layout::{Alignment, Constraint, Direction, Layout},
-    style::{Color, Modifier, Style, Stylize},
-    text::{Line, Masked, Span},
-    widgets::{Block, Borders, Paragraph, Wrap},
-    Frame, Terminal,
-};
+use ratatui::prelude::*;
 
 struct App {
     scroll: u16,

examples/popup.rs

@@ -5,13 +5,7 @@ use crossterm::{
     execute,
     terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
 };
-use ratatui::{
-    backend::{Backend, CrosstermBackend},
-    layout::{Alignment, Constraint, Direction, Layout, Rect},
-    style::Stylize,
-    widgets::{Block, Borders, Clear, Paragraph, Wrap},
-    Frame, Terminal,
-};
+use ratatui::prelude::*;
 
 struct App {
     show_popup: bool,

examples/scrollbar.rs

@@ -9,16 +9,7 @@ use crossterm::{
     execute,
     terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
 };
-use ratatui::{
-    backend::{Backend, CrosstermBackend},
-    layout::{Alignment, Constraint, Direction, Layout, Margin},
-    style::{Color, Modifier, Style, Stylize},
-    text::{Line, Masked, Span},
-    widgets::{
-        scrollbar, Block, Borders, Paragraph, Scrollbar, ScrollbarOrientation, ScrollbarState,
-    },
-    Frame, Terminal,
-};
+use ratatui::{prelude::*, widgets::scrollbar};
 
 #[derive(Default)]
 struct App {

examples/sparkline.rs

@@ -13,13 +13,7 @@ use rand::{
     distributions::{Distribution, Uniform},
     rngs::ThreadRng,
 };
-use ratatui::{
-    backend::{Backend, CrosstermBackend},
-    layout::{Constraint, Direction, Layout},
-    style::{Color, Style},
-    widgets::{Block, Borders, Sparkline},
-    Frame, Terminal,
-};
+use ratatui::prelude::*;
 
 #[derive(Clone)]
 pub struct RandomSignal {

examples/table.rs

@@ -5,13 +5,7 @@ use crossterm::{
     execute,
     terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
 };
-use ratatui::{
-    backend::{Backend, CrosstermBackend},
-    layout::{Constraint, Layout},
-    style::{Color, Modifier, Style},
-    widgets::{Block, Borders, Cell, Row, Table, TableState},
-    Frame, Terminal,
-};
+use ratatui::prelude::*;
 
 struct App<'a> {
     state: TableState,

examples/tabs.rs

@@ -5,14 +5,7 @@ use crossterm::{
     execute,
     terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
 };
-use ratatui::{
-    backend::{Backend, CrosstermBackend},
-    layout::{Constraint, Direction, Layout},
-    style::{Color, Modifier, Style, Stylize},
-    text::Line,
-    widgets::{Block, Borders, Tabs},
-    Frame, Terminal,
-};
+use ratatui::prelude::*;
 
 struct App<'a> {
     pub titles: Vec<&'a str>,

examples/user_input.rs

@@ -16,14 +16,7 @@ use crossterm::{
     execute,
     terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
 };
-use ratatui::{
-    backend::{Backend, CrosstermBackend},
-    layout::{Constraint, Direction, Layout},
-    style::{Color, Modifier, Style, Stylize},
-    text::{Line, Span, Text},
-    widgets::{Block, Borders, List, ListItem, Paragraph},
-    Frame, Terminal,
-};
+use ratatui::prelude::*;
 use unicode_width::UnicodeWidthStr;
 
 enum InputMode {

src/lib.rs

@@ -187,3 +187,36 @@ pub mod text;
 pub mod widgets;
 
 pub use self::terminal::{Frame, Terminal, TerminalOptions, Viewport};
+
+/// A prelude for conveniently writing applications using this library.
+///
+/// ```rust,no_run
+/// use ratatui::prelude::*;
+/// ```
+pub mod prelude {
+    #[cfg(feature = "crossterm")]
+    pub use crate::backend::CrosstermBackend;
+    #[cfg(feature = "termion")]
+    pub use crate::backend::TermionBackend;
+    #[cfg(feature = "termwiz")]
+    pub use crate::backend::TermwizBackend;
+    #[cfg(feature = "widget-calendar")]
+    pub use crate::widgets::calendar::{CalendarEventStore, DateStyler, Monthly};
+    pub use crate::{
+        backend::Backend,
+        buffer::Buffer,
+        layout::{Alignment, Constraint, Corner, Direction, Layout, Margin, Rect},
+        style::{Color, Modifier, Style, Stylize},
+        symbols::{self, Marker},
+        terminal::{Frame, Terminal, TerminalOptions, Viewport},
+        text::{Line, Masked, Span, Text},
+        widgets::{
+            block::{Block, Position as BlockTitlePosition, Title as BlockTitle},
+            canvas::{Canvas, Circle, Line as CanvasLine, Map, MapResolution, Rectangle},
+            Axis, BarChart, BorderType, Borders, Cell, Chart, Clear, Dataset, Gauge, GraphType,
+            LineGauge, List, ListItem, ListState, Padding, Paragraph, RenderDirection, Row,
+            ScrollDirection, Scrollbar, ScrollbarOrientation, ScrollbarState, Sparkline,
+            StatefulWidget, Table, TableState, Tabs, Widget, Wrap,
+        },
+    };
+}

src/widgets/block.rs

@@ -1,7 +1,7 @@
 #[path = "../title.rs"]
 pub mod title;
 
-use self::title::{Position, Title};
+pub use self::title::{Position, Title};
 use crate::{
     buffer::Buffer,
     layout::{Alignment, Rect},