fix(terminal)!: make terminal module private (#1260)

This is a simplification of the public API that is helpful for new users
that are not familiar with how rust re-exports work, and helps avoid
clashes with other modules in the backends that are named terminal.

BREAKING CHANGE: The `terminal` module is now private and can not be
used directly. The types under this module are exported from the root of
the crate.

```diff
- use ratatui::terminal::{CompletedFrame, Frame, Terminal, TerminalOptions, ViewPort};
+ use ratatui::{CompletedFrame, Frame, Terminal, TerminalOptions, ViewPort};
```

Fixes: https://github.com/ratatui-org/ratatui/issues/1210

BREAKING-CHANGES.md

@@ -10,8 +10,9 @@ GitHub with a [breaking change] label.
 
 This is a quick summary of the sections below:
 
-- [v0.28.0](#v0280)
+- [v0.28.0](#v0280) (unreleased)
   - `Layout::init_cache` no longer returns bool and takes a `NonZeroUsize` instead of `usize`
+  - `ratatui::terminal` module is now private
 - [v0.27.0](#v0270)
   - List no clamps the selected index to list
   - Prelude items added / removed
@@ -58,6 +59,30 @@ This is a quick summary of the sections below:
   - MSRV is now 1.63.0
   - `List` no longer ignores empty strings
 
+## v0.28.0 (unreleased)
+
+### `Layout::init_cache` no longer returns bool and takes a `NonZeroUsize` instead of `usize` ([#1145])
+
+[#1145]: https://github.com/ratatui-org/ratatui/pull/1145
+
+```diff
+- let is_initialized = Layout::init_cache(100);
++ Layout::init_cache(NonZeroUsize::new(100).unwrap());
+```
+
+### `ratatui::terminal` module is now private ([#1160])
+
+[#1160]: https://github.com/ratatui-org/ratatui/pull/1160
+
+The `terminal` module is now private and can not be used directly. The types under this module are
+exported from the root of the crate. This reduces clashes with other modules in the backends that
+are also named terminal, and confusion about module exports for newer Rust users.
+
+```diff
+- use ratatui::terminal::{CompletedFrame, Frame, Terminal, TerminalOptions, ViewPort};
++ use ratatui::{CompletedFrame, Frame, Terminal, TerminalOptions, ViewPort};
+```
+
 ## [v0.27.0](https://github.com/ratatui-org/ratatui/releases/tag/v0.27.0)
 
 ### List no clamps the selected index to list ([#1159])

examples/barchart.rs

@@ -28,9 +28,9 @@ use ratatui::{
     },
     layout::{Constraint, Direction, Layout, Rect},
     style::{Color, Modifier, Style},
-    terminal::{Frame, Terminal},
     text::{Line, Span},
     widgets::{Bar, BarChart, BarGroup, Block, Paragraph},
+    Frame, Terminal,
 };
 
 struct Company<'a> {

examples/block.rs

@@ -30,12 +30,12 @@ use ratatui::{
     },
     layout::{Alignment, Constraint, Layout, Rect},
     style::{Style, Stylize},
-    terminal::Frame,
     text::Line,
     widgets::{
         block::{Position, Title},
         Block, BorderType, Borders, Padding, Paragraph, Wrap,
     },
+    Frame,
 };
 
 // These type aliases are used to make the code more readable by reducing repetition of the generic

examples/canvas.rs

@@ -28,11 +28,11 @@ use ratatui::{
     layout::{Constraint, Layout, Rect},
     style::{Color, Stylize},
     symbols::Marker,
-    terminal::{Frame, Terminal},
     widgets::{
         canvas::{Canvas, Circle, Map, MapResolution, Rectangle},
         Block, Widget,
     },
+    Frame, Terminal,
 };
 
 fn main() -> io::Result<()> {

examples/chart.rs

@@ -29,9 +29,9 @@ use ratatui::{
     layout::{Alignment, Constraint, Layout, Rect},
     style::{Color, Modifier, Style, Stylize},
     symbols::{self, Marker},
-    terminal::{Frame, Terminal},
     text::Span,
     widgets::{block::Title, Axis, Block, Chart, Dataset, GraphType, LegendPosition},
+    Frame, Terminal,
 };
 
 #[derive(Clone)]

examples/colors.rs

@@ -33,9 +33,9 @@ use ratatui::{
     },
     layout::{Alignment, Constraint, Layout, Rect},
     style::{Color, Style, Stylize},
-    terminal::{Frame, Terminal},
     text::Line,
     widgets::{Block, Borders, Paragraph},
+    Frame, Terminal,
 };
 
 type Result<T> = result::Result<T, Box<dyn Error>>;

examples/colors_rgb.rs

@@ -44,9 +44,9 @@ use ratatui::{
     },
     layout::{Constraint, Layout, Rect},
     style::Color,
-    terminal::Terminal,
     text::Text,
     widgets::Widget,
+    Terminal,
 };
 
 #[derive(Debug, Default)]

examples/constraint-explorer.rs

@@ -34,9 +34,9 @@ use ratatui::{
         Color, Style, Stylize,
     },
     symbols::{self, line},
-    terminal::Terminal,
     text::{Line, Span, Text},
     widgets::{Block, Paragraph, Widget, Wrap},
+    Terminal,
 };
 use strum::{Display, EnumIter, FromRepr};
 

examples/constraints.rs

@@ -30,12 +30,12 @@ use ratatui::{
     },
     style::{palette::tailwind, Color, Modifier, Style, Stylize},
     symbols,
-    terminal::Terminal,
     text::Line,
     widgets::{
         Block, Padding, Paragraph, Scrollbar, ScrollbarOrientation, ScrollbarState, StatefulWidget,
         Tabs, Widget,
     },
+    Terminal,
 };
 use strum::{Display, EnumIter, FromRepr, IntoEnumIterator};
 

examples/custom_widget.rs

@@ -28,9 +28,9 @@ use ratatui::{
     },
     layout::{Constraint, Layout, Rect},
     style::{Color, Style},
-    terminal::{Frame, Terminal},
     text::Line,
     widgets::{Paragraph, Widget},
+    Frame, Terminal,
 };
 
 /// A custom widget that renders a button with a label, theme and state.

examples/demo/crossterm.rs

@@ -11,7 +11,7 @@ use ratatui::{
         execute,
         terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
     },
-    terminal::Terminal,
+    Terminal,
 };
 
 use crate::{app::App, ui};

examples/demo/termion.rs

@@ -2,13 +2,13 @@ use std::{error::Error, io, sync::mpsc, thread, time::Duration};
 
 use ratatui::{
     backend::{Backend, TermionBackend},
-    terminal::Terminal,
     termion::{
         event::Key,
         input::{MouseTerminal, TermRead},
         raw::IntoRawMode,
         screen::IntoAlternateScreen,
     },
+    Terminal,
 };
 
 use crate::{app::App, ui};

examples/demo/termwiz.rs

@@ -5,11 +5,11 @@ use std::{
 
 use ratatui::{
     backend::TermwizBackend,
-    terminal::Terminal,
     termwiz::{
         input::{InputEvent, KeyCode},
         terminal::Terminal as TermwizTerminal,
     },
+    Terminal,
 };
 
 use crate::{app::App, ui};

examples/demo/ui.rs

@@ -2,13 +2,13 @@ use ratatui::{
     layout::{Constraint, Layout, Rect},
     style::{Color, Modifier, Style},
     symbols,
-    terminal::Frame,
     text::{self, Span},
     widgets::{
         canvas::{self, Canvas, Circle, Map, MapResolution, Rectangle},
         Axis, BarChart, Block, Cell, Chart, Dataset, Gauge, LineGauge, List, ListItem, Paragraph,
         Row, Sparkline, Table, Tabs, Wrap,
     },
+    Frame,
 };
 
 use crate::app::App;

examples/demo2/app.rs

@@ -8,9 +8,9 @@ use ratatui::{
     crossterm::event::{Event, KeyCode, KeyEvent, KeyEventKind},
     layout::{Constraint, Layout, Rect},
     style::Color,
-    terminal::Terminal,
     text::{Line, Span},
     widgets::{Block, Tabs, Widget},
+    Terminal,
 };
 use strum::{Display, EnumIter, FromRepr, IntoEnumIterator};
 

examples/demo2/big_text.rs

@@ -26,9 +26,9 @@
 //!     layout::{self, Alignment, Constraint, Direction, Layout, Margin, Rect},
 //!     style::{self, Color, Modifier, Style, Styled, Stylize},
 //!     symbols::{self, Marker},
-//!     terminal::{CompletedFrame, Frame, Terminal, TerminalOptions, Viewport},
 //!     text::{self, Line, Masked, Span, Text},
 //!     widgets::{block::BlockExt, StatefulWidget, Widget},
+//!     CompletedFrame, Frame, Terminal, TerminalOptions, Viewport,
 //! };
 //! use tui_big_text::{BigTextBuilder, PixelSize};
 //!

examples/demo2/destroy.rs

@@ -4,8 +4,8 @@ use ratatui::{
     buffer::Buffer,
     layout::{Flex, Layout, Rect},
     style::{Color, Style},
-    terminal::Frame,
     widgets::Widget,
+    Frame,
 };
 use unicode_width::UnicodeWidthStr;
 

examples/demo2/term.rs

@@ -12,7 +12,7 @@ use ratatui::{
         ExecutableCommand,
     },
     layout::Rect,
-    terminal::{Terminal, TerminalOptions, Viewport},
+    Terminal, TerminalOptions, Viewport,
 };
 
 pub fn init() -> Result<Terminal<impl Backend>> {

examples/docsrs.rs

@@ -24,9 +24,9 @@ use ratatui::{
     },
     layout::{Constraint, Layout},
     style::{Color, Modifier, Style, Stylize},
-    terminal::{Frame, Terminal},
     text::{Line, Span, Text},
     widgets::{Block, Borders, Paragraph},
+    Frame, Terminal,
 };
 
 /// Example code for lib.rs

examples/flex.rs

@@ -34,12 +34,12 @@ use ratatui::{
     },
     style::{palette::tailwind, Color, Modifier, Style, Stylize},
     symbols::{self, line},
-    terminal::Terminal,
     text::{Line, Text},
     widgets::{
         block::Title, Block, Paragraph, Scrollbar, ScrollbarOrientation, ScrollbarState,
         StatefulWidget, Tabs, Widget,
     },
+    Terminal,
 };
 use strum::{Display, EnumIter, FromRepr, IntoEnumIterator};
 

examples/gauge.rs

@@ -26,9 +26,9 @@ use ratatui::{
     },
     layout::{Alignment, Constraint, Layout, Rect},
     style::{palette::tailwind, Color, Style, Stylize},
-    terminal::Terminal,
     text::Span,
     widgets::{block::Title, Block, Borders, Gauge, Padding, Paragraph, Widget},
+    Terminal,
 };
 
 const GAUGE1_COLOR: Color = tailwind::RED.c800;

examples/hello_world.rs

@@ -26,8 +26,8 @@ use ratatui::{
         execute,
         terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
     },
-    terminal::{Frame, Terminal},
     widgets::Paragraph,
+    Frame, Terminal,
 };
 
 /// This is a bare minimum example. There are many approaches to running an application loop, so

examples/inline.rs

@@ -28,10 +28,9 @@ use ratatui::{
     layout::{Alignment, Constraint, Layout, Rect},
     style::{Color, Modifier, Style},
     symbols,
-    terminal::{Frame, Terminal, Viewport},
     text::{Line, Span},
     widgets::{block, Block, Gauge, LineGauge, List, ListItem, Paragraph, Widget},
-    TerminalOptions,
+    Frame, Terminal, TerminalOptions, Viewport,
 };
 
 const NUM_DOWNLOADS: usize = 10;

examples/layout.rs

@@ -29,9 +29,9 @@ use ratatui::{
         Layout, Rect,
     },
     style::{Color, Style, Stylize},
-    terminal::{Frame, Terminal},
     text::Line,
     widgets::{Block, Paragraph},
+    Frame, Terminal,
 };
 
 fn main() -> Result<(), Box<dyn Error>> {

examples/line_gauge.rs

@@ -26,8 +26,8 @@ use ratatui::{
     },
     layout::{Alignment, Constraint, Layout, Rect},
     style::{palette::tailwind, Color, Style, Stylize},
-    terminal::Terminal,
     widgets::{block::Title, Block, Borders, LineGauge, Padding, Paragraph, Widget},
+    Terminal,
 };
 
 const CUSTOM_LABEL_COLOR: Color = tailwind::SLATE.c200;

examples/list.rs

@@ -26,12 +26,12 @@ use ratatui::{
         Color, Modifier, Style, Stylize,
     },
     symbols,
-    terminal::Terminal,
     text::Line,
     widgets::{
         Block, Borders, HighlightSpacing, List, ListItem, ListState, Padding, Paragraph,
         StatefulWidget, Widget, Wrap,
     },
+    Terminal,
 };
 
 const TODO_HEADER_STYLE: Style = Style::new().fg(SLATE.c100).bg(BLUE.c800);
@@ -304,7 +304,7 @@ mod tui {
             },
             ExecutableCommand,
         },
-        terminal::Terminal,
+        Terminal,
     };
 
     pub fn init_error_hooks() -> color_eyre::Result<()> {

examples/modifiers.rs

@@ -35,9 +35,9 @@ use ratatui::{
     },
     layout::{Constraint, Layout},
     style::{Color, Modifier, Style, Stylize},
-    terminal::{Frame, Terminal},
     text::Line,
     widgets::Paragraph,
+    Frame, Terminal,
 };
 
 type Result<T> = result::Result<T, Box<dyn Error>>;

examples/panic.rs

@@ -37,9 +37,9 @@ use ratatui::{
         event::{self, Event, KeyCode},
         terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
     },
-    terminal::{Frame, Terminal},
     text::Line,
     widgets::{Block, Paragraph},
+    Frame, Terminal,
 };
 
 type Result<T> = std::result::Result<T, Box<dyn Error>>;

examples/paragraph.rs

@@ -177,7 +177,7 @@ mod common {
         crossterm::terminal::{
             disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen,
         },
-        terminal::Terminal,
+        Terminal,
     };
 
     // A simple alias for the terminal type used in this example.

examples/popup.rs

@@ -27,8 +27,8 @@ use ratatui::{
     },
     layout::{Constraint, Layout, Rect},
     style::Stylize,
-    terminal::{Frame, Terminal},
     widgets::{Block, Clear, Paragraph, Wrap},
+    Frame, Terminal,
 };
 
 struct App {

examples/ratatui-logo.rs

@@ -24,9 +24,8 @@ use itertools::izip;
 use ratatui::{
     backend::{Backend, CrosstermBackend},
     crossterm::terminal::{disable_raw_mode, enable_raw_mode},
-    terminal::{Terminal, Viewport},
     widgets::Paragraph,
-    TerminalOptions,
+    Terminal, TerminalOptions, Viewport,
 };
 
 /// A fun example of using half block characters to draw a logo

examples/scrollbar.rs

@@ -31,9 +31,9 @@ use ratatui::{
     layout::{Alignment, Constraint, Layout, Margin},
     style::{Color, Style, Stylize},
     symbols::scrollbar,
-    terminal::{Frame, Terminal},
     text::{Line, Masked, Span},
     widgets::{Block, Paragraph, Scrollbar, ScrollbarOrientation, ScrollbarState},
+    Frame, Terminal,
 };
 
 #[derive(Default)]

examples/sparkline.rs

@@ -32,8 +32,8 @@ use ratatui::{
     },
     layout::{Constraint, Layout},
     style::{Color, Style},
-    terminal::{Frame, Terminal},
     widgets::{Block, Borders, Sparkline},
+    Frame, Terminal,
 };
 
 #[derive(Clone)]

examples/table.rs

@@ -25,12 +25,12 @@ use ratatui::{
     },
     layout::{Constraint, Layout, Margin, Rect},
     style::{self, Color, Modifier, Style, Stylize},
-    terminal::{Frame, Terminal},
     text::{Line, Text},
     widgets::{
         Block, BorderType, Cell, HighlightSpacing, Paragraph, Row, Scrollbar, ScrollbarOrientation,
         ScrollbarState, Table, TableState,
     },
+    Frame, Terminal,
 };
 use style::palette::tailwind;
 use unicode_width::UnicodeWidthStr;

examples/tabs.rs

@@ -27,9 +27,9 @@ use ratatui::{
     layout::{Constraint, Layout, Rect},
     style::{palette::tailwind, Color, Stylize},
     symbols,
-    terminal::Terminal,
     text::Line,
     widgets::{Block, Padding, Paragraph, Tabs, Widget},
+    Terminal,
 };
 use strum::{Display, EnumIter, FromRepr, IntoEnumIterator};
 

examples/tracing.rs

@@ -41,8 +41,8 @@ use crossterm::{
 };
 use ratatui::{
     backend::{Backend, CrosstermBackend},
-    terminal::Terminal,
     widgets::{Block, Paragraph},
+    Terminal,
 };
 use tracing::{debug, info, instrument, trace, Level};
 use tracing_appender::{non_blocking, non_blocking::WorkerGuard};

examples/user_input.rs

@@ -38,9 +38,9 @@ use ratatui::{
     },
     layout::{Constraint, Layout},
     style::{Color, Modifier, Style, Stylize},
-    terminal::{Frame, Terminal},
     text::{Line, Span, Text},
     widgets::{Block, List, ListItem, Paragraph},
+    Frame, Terminal,
 };
 
 enum InputMode {

src/lib.rs

@@ -348,6 +348,6 @@ pub mod layout;
 pub mod prelude;
 pub mod style;
 pub mod symbols;
-pub mod terminal;
+mod terminal;
 pub mod text;
 pub mod widgets;