chore(prelude)!: add / remove items (#1149)

his PR removes the items from the prelude that don't form a coherent
common vocabulary and adds the missing items that do.

Based on a comment at
<https://www.reddit.com/r/rust/comments/1cle18j/comment/l2uuuh7/>

BREAKING CHANGE:
The following items have been removed from the prelude:
- `style::Styled` - this trait is useful for widgets that want to
  support the Stylize trait, but it adds complexity as widgets have two
  `style` methods and a `set_style` method.
- `symbols::Marker` - this item is used by code that needs to draw to
  the `Canvas` widget, but it's not a common item that would be used by
  most users of the library.
- `terminal::{CompletedFrame, TerminalOptions, Viewport}` - these items
  are rarely used by code that needs to interact with the terminal, and
  they're generally only ever used once in any app.

The following items have been added to the prelude:
- `layout::{Position, Size}` - these items are used by code that needs
  to interact with the layout system. These are newer items that were
  added in the last few releases, which should be used more liberally.

BREAKING-CHANGES.md

@@ -55,6 +55,53 @@ This is a quick summary of the sections below:
 
 ## Unreleased
 
+### Prelude items added / removed ([#1149])
+
+The following items have been removed from the prelude:
+
+- `style::Styled` - this trait is useful for widgets that want to
+  support the Stylize trait, but it adds complexity as widgets have two
+  `style` methods and a `set_style` method.
+- `symbols::Marker` - this item is used by code that needs to draw to
+  the `Canvas` widget, but it's not a common item that would be used by
+  most users of the library.
+- `terminal::{CompletedFrame, TerminalOptions, Viewport}` - these items
+  are rarely used by code that needs to interact with the terminal, and
+  they're generally only ever used once in any app.
+
+The following items have been added to the prelude:
+
+- `layout::{Position, Size}` - these items are used by code that needs
+  to interact with the layout system. These are newer items that were
+  added in the last few releases, which should be used more liberally.
+  This may cause conflicts for types defined elsewhere with a similar
+  name.
+
+To update your app:
+
+```diff
+// if your app uses Styled::style() or Styled::set_style():
+-use ratatui::prelude::*;
++use ratatui::{prelude::*, style::Styled};
+
+// if your app uses symbols::Marker:
+-use ratatui::prelude::*;
++use ratatui::{prelude::*, symbols::Marker}
+
+// if your app uses terminal::{CompletedFrame, TerminalOptions, Viewport}
+-use ratatui::prelude::*;
++use ratatui::{prelude::*, terminal::{CompletedFrame, TerminalOptions, Viewport}};
+
+// to disambiguate existing types named Position or Size:
+- use some_crate::{Position, Size};
+- let size: Size = ...;
+- let position: Position = ...;
++ let size: some_crate::Size = ...;
++ let position: some_crate::Position = ...;
+```
+
+[#1149]: https://github.com/ratatui-org/ratatui/pull/1149
+
 ### Termion is updated to 4.0 [#1106]
 
 Changelog: <https://gitlab.redox-os.org/redox-os/termion/-/blob/master/CHANGELOG.md>
@@ -97,9 +144,9 @@ wildcard. In this case, you need to either handle the two new variants, `MouseLe
 Previously, `Stylize::bg()` accepted `Color` but now accepts `Into<Color>`. This allows more
 flexible types from calling scopes, though it can break some type inference in the calling scope.
 
-### Remove deprecated `List::start_corner` and `layout::Corner` ([#757])
+### Remove deprecated `List::start_corner` and `layout::Corner` ([#759])
 
-[#757]: https://github.com/ratatui-org/ratatui/pull/757
+[#759]: https://github.com/ratatui-org/ratatui/pull/759
 
 `List::start_corner` was deprecated in v0.25. Use `List::direction` and `ListDirection` instead.
 
@@ -460,8 +507,8 @@ The MSRV of ratatui is now 1.67 due to an MSRV update in a dependency (`time`).
 
 [#205]: https://github.com/ratatui-org/ratatui/issues/205
 
-The `serde` representation of `bitflags` has changed. Any existing serialized types that have Borders or
+The `serde` representation of `bitflags` has changed. Any existing serialized types that have
-Modifiers will need to be re-serialized. This is documented in the [`bitflags`
+Borders or Modifiers will need to be re-serialized. This is documented in the [`bitflags`
 changelog](https://github.com/bitflags/bitflags/blob/main/CHANGELOG.md#200-rc2)..
 
 ## [v0.21.0](https://github.com/ratatui-org/ratatui/releases/tag/v0.21.0)

src/layout/rect/iter.rs

@@ -1,4 +1,3 @@
-use self::layout::Position;
 use crate::prelude::*;
 
 /// An iterator over rows within a `Rect`.

src/lib.rs

@@ -327,26 +327,24 @@
     html_favicon_url = "https://raw.githubusercontent.com/ratatui-org/ratatui/main/assets/favicon.ico"
 )]
 
-pub mod backend;
-pub mod buffer;
-pub mod layout;
-pub mod style;
-pub mod symbols;
-pub mod terminal;
-pub mod text;
-pub mod widgets;
-
-#[doc(inline)]
-pub use self::terminal::{CompletedFrame, Frame, Terminal, TerminalOptions, Viewport};
-
-pub mod prelude;
-
 /// re-export the `crossterm` crate so that users don't have to add it as a dependency
 #[cfg(feature = "crossterm")]
 pub use crossterm;
+#[doc(inline)]
+pub use terminal::{CompletedFrame, Frame, Terminal, TerminalOptions, Viewport};
 /// re-export the `termion` crate so that users don't have to add it as a dependency
 #[cfg(feature = "termion")]
 pub use termion;
 /// re-export the `termwiz` crate so that users don't have to add it as a dependency
 #[cfg(feature = "termwiz")]
 pub use termwiz;
+
+pub mod backend;
+pub mod buffer;
+pub mod layout;
+pub mod prelude;
+pub mod style;
+pub mod symbols;
+pub mod terminal;
+pub mod text;
+pub mod widgets;

src/prelude.rs

@@ -27,10 +27,10 @@ pub(crate) use crate::widgets::{StatefulWidgetRef, WidgetRef};
 pub use crate::{
     backend::{self, Backend},
     buffer::{self, Buffer},
-    layout::{self, Alignment, Constraint, Direction, Layout, Margin, Rect},
+    layout::{self, Alignment, Constraint, Direction, Layout, Margin, Position, Rect, Size},
-    style::{self, Color, Modifier, Style, Styled, Stylize},
+    style::{self, Color, Modifier, Style, Stylize},
-    symbols::{self, Marker},
+    symbols::{self},
-    terminal::{CompletedFrame, Frame, Terminal, TerminalOptions, Viewport},
+    terminal::{Frame, Terminal},
     text::{self, Line, Masked, Span, Text},
     widgets::{block::BlockExt, StatefulWidget, Widget},
 };

src/terminal/terminal.rs

@@ -1,6 +1,6 @@
 use std::io;
 
-use crate::{backend::ClearType, prelude::*};
+use crate::{backend::ClearType, prelude::*, CompletedFrame, TerminalOptions, Viewport};
 
 /// An interface to interact and draw [`Frame`]s on the user's terminal.
 ///
@@ -126,7 +126,7 @@ where
     ///
     /// ```rust
     /// # use std::io::stdout;
-    /// # use ratatui::{prelude::*, backend::TestBackend};
+    /// # use ratatui::{prelude::*, backend::TestBackend, terminal::{Viewport, TerminalOptions}};
     /// let backend = CrosstermBackend::new(stdout());
     /// let viewport = Viewport::Fixed(Rect::new(0, 0, 10, 10));
     /// let terminal = Terminal::with_options(backend, TerminalOptions { viewport })?;

src/text/grapheme.rs

@@ -1,4 +1,4 @@
-use crate::prelude::*;
+use crate::{prelude::*, style::Styled};
 
 /// A grapheme associated to a style.
 /// Note that, although `StyledGrapheme` is the smallest divisible unit of text,

src/text/line.rs

@@ -4,8 +4,7 @@ use std::{borrow::Cow, fmt};
 
 use unicode_truncate::UnicodeTruncateStr;
 
-use super::StyledGrapheme;
+use crate::{prelude::*, style::Styled, text::StyledGrapheme};
-use crate::prelude::*;
 
 /// A line of text, consisting of one or more [`Span`]s.
 ///

src/text/span.rs

@@ -3,8 +3,7 @@ use std::{borrow::Cow, fmt};
 use unicode_segmentation::UnicodeSegmentation;
 use unicode_width::UnicodeWidthStr;
 
-use super::StyledGrapheme;
+use crate::{prelude::*, style::Styled, text::StyledGrapheme};
-use crate::prelude::*;
 
 /// Represents a part of a line that is contiguous and where all characters share the same style.
 ///

src/text/text.rs

@@ -3,7 +3,7 @@ use std::{borrow::Cow, fmt};
 
 use itertools::{Itertools, Position};
 
-use crate::prelude::*;
+use crate::{prelude::*, style::Styled};
 
 /// A string split over one or more lines.
 ///

src/widgets.rs

@@ -474,7 +474,7 @@ mod tests {
     use rstest::{fixture, rstest};
 
     use super::*;
-    use crate::prelude::*;
+    use crate::text::Line;
 
     #[fixture]
     fn buf() -> Buffer {

src/widgets/barchart.rs

@@ -1,4 +1,4 @@
-use crate::{prelude::*, widgets::Block};
+use crate::{prelude::*, style::Styled, widgets::Block};
 
 mod bar;
 mod bar_group;

src/widgets/block.rs

@@ -8,7 +8,7 @@
 use itertools::Itertools;
 use strum::{Display, EnumString};
 
-use crate::{prelude::*, symbols::border, widgets::Borders};
+use crate::{prelude::*, style::Styled, symbols::border, widgets::Borders};
 
 mod padding;
 pub mod title;
@@ -53,7 +53,10 @@ pub use title::{Position, Title};
 /// ```
 /// use ratatui::{
 ///     prelude::*,
-///     widgets::{block::*, *},
+///     widgets::{
+///         block::{Position, Title},
+///         Block,
+///     },
 /// };
 ///
 /// Block::new()
@@ -354,7 +357,10 @@ impl<'a> Block<'a> {
     /// ```
     /// use ratatui::{
     ///     prelude::*,
-    ///     widgets::{block::*, *},
+    ///     widgets::{
+    ///         block::{Position, Title},
+    ///         Block,
+    ///     },
     /// };
     ///
     /// Block::new()

src/widgets/block/title.rs

@@ -36,7 +36,10 @@ use crate::{layout::Alignment, text::Line};
 /// ```
 /// use ratatui::{
 ///     prelude::*,
-///     widgets::{block::*, *},
+///     widgets::{
+///         block::{Position, Title},
+///         Block,
+///     },
 /// };
 ///
 /// Title::from("Title")

src/widgets/canvas.rs

@@ -30,7 +30,7 @@ pub use self::{
     points::Points,
     rectangle::Rectangle,
 };
-use crate::{prelude::*, text::Line as TextLine, widgets::Block};
+use crate::{prelude::*, symbols::Marker, text::Line as TextLine, widgets::Block};
 
 /// Something that can be drawn on a [`Canvas`].
 ///
@@ -464,17 +464,17 @@ impl<'a> Context<'a> {
         height: u16,
         x_bounds: [f64; 2],
         y_bounds: [f64; 2],
-        marker: symbols::Marker,
+        marker: Marker,
     ) -> Self {
         let dot = symbols::DOT.chars().next().unwrap();
         let block = symbols::block::FULL.chars().next().unwrap();
         let bar = symbols::bar::HALF.chars().next().unwrap();
         let grid: Box<dyn Grid> = match marker {
-            symbols::Marker::Dot => Box::new(CharGrid::new(width, height, dot)),
+            Marker::Dot => Box::new(CharGrid::new(width, height, dot)),
-            symbols::Marker::Block => Box::new(CharGrid::new(width, height, block)),
+            Marker::Block => Box::new(CharGrid::new(width, height, block)),
-            symbols::Marker::Bar => Box::new(CharGrid::new(width, height, bar)),
+            Marker::Bar => Box::new(CharGrid::new(width, height, bar)),
-            symbols::Marker::Braille => Box::new(BrailleGrid::new(width, height)),
+            Marker::Braille => Box::new(BrailleGrid::new(width, height)),
-            symbols::Marker::HalfBlock => Box::new(HalfBlockGrid::new(width, height)),
+            Marker::HalfBlock => Box::new(HalfBlockGrid::new(width, height)),
         };
         Self {
             x_bounds,
@@ -604,7 +604,7 @@ where
     y_bounds: [f64; 2],
     paint_func: Option<F>,
     background_color: Color,
-    marker: symbols::Marker,
+    marker: Marker,
 }
 
 impl<'a, F> Default for Canvas<'a, F>
@@ -618,7 +618,7 @@ where
             y_bounds: [0.0, 0.0],
             paint_func: None,
             background_color: Color::Reset,
-            marker: symbols::Marker::Braille,
+            marker: Marker::Braille,
         }
     }
 }
@@ -717,7 +717,7 @@ where
     ///     .paint(|ctx| {});
     /// ```
     #[must_use = "method moves the value of self and returns the modified value"]
-    pub const fn marker(mut self, marker: symbols::Marker) -> Self {
+    pub const fn marker(mut self, marker: Marker) -> Self {
         self.marker = marker;
         self
     }

src/widgets/canvas/line.rs

@@ -114,8 +114,14 @@ fn draw_line_high(painter: &mut Painter, x1: usize, y1: usize, x2: usize, y2: us
 mod tests {
     use rstest::rstest;
 
-    use super::{super::*, *};
+    use super::*;
-    use crate::{buffer::Buffer, layout::Rect};
+    use crate::{
+        buffer::Buffer,
+        layout::Rect,
+        style::{Style, Stylize},
+        symbols::Marker,
+        widgets::{canvas::Canvas, Widget},
+    };
 
     #[rstest]
     #[case::off_grid(&Line::new(-1.0, -1.0, 10.0, 10.0, Color::Red), ["          "; 10])]

src/widgets/canvas/map.rs

@@ -65,7 +65,7 @@ mod tests {
     use strum::ParseError;
 
     use super::*;
-    use crate::{prelude::*, widgets::canvas::Canvas};
+    use crate::{prelude::*, symbols::Marker, widgets::canvas::Canvas};
 
     #[test]
     fn map_resolution_to_string() {

src/widgets/canvas/rectangle.rs

@@ -66,7 +66,7 @@ impl Shape for Rectangle {
 #[cfg(test)]
 mod tests {
     use super::*;
-    use crate::{prelude::*, widgets::canvas::Canvas};
+    use crate::{prelude::*, symbols::Marker, widgets::canvas::Canvas};
 
     #[test]
     fn draw_block_lines() {

src/widgets/chart.rs

@@ -6,6 +6,7 @@ use unicode_width::UnicodeWidthStr;
 use crate::{
     layout::Flex,
     prelude::*,
+    style::Styled,
     widgets::{
         canvas::{Canvas, Line as CanvasLine, Points},
         Block,
@@ -285,7 +286,7 @@ impl LegendPosition {
 /// This example draws a red line between two points.
 ///
 /// ```rust
-/// use ratatui::{prelude::*, widgets::*};
+/// use ratatui::{prelude::*, symbols::Marker, widgets::*};
 ///
 /// let dataset = Dataset::default()
 ///     .name("dataset 1")

src/widgets/gauge.rs

@@ -1,4 +1,4 @@
-use crate::{prelude::*, widgets::Block};
+use crate::{prelude::*, style::Styled, widgets::Block};
 
 /// A widget to display a progress bar.
 ///

src/widgets/list.rs

@@ -3,6 +3,7 @@ use unicode_width::UnicodeWidthStr;
 
 use crate::{
     prelude::*,
+    style::Styled,
     widgets::{Block, HighlightSpacing},
 };
 

src/widgets/paragraph.rs

@@ -2,6 +2,7 @@ use unicode_width::UnicodeWidthStr;
 
 use crate::{
     prelude::*,
+    style::Styled,
     text::StyledGrapheme,
     widgets::{
         reflow::{LineComposer, LineTruncator, WordWrapper, WrappedLine},

src/widgets/sparkline.rs

@@ -2,7 +2,7 @@ use std::cmp::min;
 
 use strum::{Display, EnumString};
 
-use crate::{prelude::*, widgets::Block};
+use crate::{prelude::*, style::Styled, widgets::Block};
 
 /// Widget to render a sparkline over one or more lines.
 ///

src/widgets/table/cell.rs

@@ -1,4 +1,4 @@
-use crate::prelude::*;
+use crate::{prelude::*, style::Styled};
 
 /// A [`Cell`] contains the [`Text`] to be displayed in a [`Row`] of a [`Table`].
 ///

src/widgets/table/row.rs

@@ -1,5 +1,5 @@
 use super::Cell;
-use crate::prelude::*;
+use crate::{prelude::*, style::Styled};
 
 /// A single row of data to be displayed in a [`Table`] widget.
 ///

src/widgets/table/table.rs

@@ -3,7 +3,7 @@ use itertools::Itertools;
 #[allow(unused_imports)] // `Cell` is used in the doc comment but not the code
 use super::Cell;
 use super::{HighlightSpacing, Row, TableState};
-use crate::{layout::Flex, prelude::*, widgets::Block};
+use crate::{layout::Flex, prelude::*, style::Styled, widgets::Block};
 
 /// A widget to display data in formatted columns.
 ///

src/widgets/tabs.rs

@@ -1,4 +1,4 @@
-use crate::{prelude::*, widgets::Block};
+use crate::{prelude::*, style::Styled, widgets::Block};
 
 const DEFAULT_HIGHLIGHT_STYLE: Style = Style::new().add_modifier(Modifier::REVERSED);