From 7b45f74b719ff18329ddbf9f05a9ac53bf06f71d Mon Sep 17 00:00:00 2001 From: Josh McKinney Date: Tue, 4 Jun 2024 20:59:51 -0700 Subject: [PATCH] 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 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 ++++++++++++++++++++++++++++++--- src/layout/rect/iter.rs | 1 - src/lib.rs | 26 +++++++--------- src/prelude.rs | 8 ++--- src/terminal/terminal.rs | 4 +-- src/text/grapheme.rs | 2 +- src/text/line.rs | 3 +- src/text/span.rs | 3 +- src/text/text.rs | 2 +- src/widgets.rs | 2 +- src/widgets/barchart.rs | 2 +- src/widgets/block.rs | 12 +++++-- src/widgets/block/title.rs | 5 ++- src/widgets/canvas.rs | 20 ++++++------ src/widgets/canvas/line.rs | 10 ++++-- src/widgets/canvas/map.rs | 2 +- src/widgets/canvas/rectangle.rs | 2 +- src/widgets/chart.rs | 3 +- src/widgets/gauge.rs | 2 +- src/widgets/list.rs | 1 + src/widgets/paragraph.rs | 1 + src/widgets/sparkline.rs | 2 +- src/widgets/table/cell.rs | 2 +- src/widgets/table/row.rs | 2 +- src/widgets/table/table.rs | 2 +- src/widgets/tabs.rs | 2 +- 26 files changed, 118 insertions(+), 58 deletions(-) diff --git a/BREAKING-CHANGES.md b/BREAKING-CHANGES.md index 068acf1b..586702f1 100644 --- a/BREAKING-CHANGES.md +++ b/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: @@ -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`. 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 -Modifiers will need to be re-serialized. This is documented in the [`bitflags` +The `serde` representation of `bitflags` has changed. Any existing serialized types that have +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) diff --git a/src/layout/rect/iter.rs b/src/layout/rect/iter.rs index 3b34d471..2405f432 100644 --- a/src/layout/rect/iter.rs +++ b/src/layout/rect/iter.rs @@ -1,4 +1,3 @@ -use self::layout::Position; use crate::prelude::*; /// An iterator over rows within a `Rect`. diff --git a/src/lib.rs b/src/lib.rs index f89cfecd..9ff9db8c 100644 --- a/src/lib.rs +++ b/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; diff --git a/src/prelude.rs b/src/prelude.rs index 55250ab7..2546be60 100644 --- a/src/prelude.rs +++ b/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}, - style::{self, Color, Modifier, Style, Styled, Stylize}, - symbols::{self, Marker}, - terminal::{CompletedFrame, Frame, Terminal, TerminalOptions, Viewport}, + layout::{self, Alignment, Constraint, Direction, Layout, Margin, Position, Rect, Size}, + style::{self, Color, Modifier, Style, Stylize}, + symbols::{self}, + terminal::{Frame, Terminal}, text::{self, Line, Masked, Span, Text}, widgets::{block::BlockExt, StatefulWidget, Widget}, }; diff --git a/src/terminal/terminal.rs b/src/terminal/terminal.rs index b4bd28af..65d48cde 100644 --- a/src/terminal/terminal.rs +++ b/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 })?; diff --git a/src/text/grapheme.rs b/src/text/grapheme.rs index dc1cc4a8..7978481b 100644 --- a/src/text/grapheme.rs +++ b/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, diff --git a/src/text/line.rs b/src/text/line.rs index be6b13f4..fd738aaa 100644 --- a/src/text/line.rs +++ b/src/text/line.rs @@ -4,8 +4,7 @@ use std::{borrow::Cow, fmt}; use unicode_truncate::UnicodeTruncateStr; -use super::StyledGrapheme; -use crate::prelude::*; +use crate::{prelude::*, style::Styled, text::StyledGrapheme}; /// A line of text, consisting of one or more [`Span`]s. /// diff --git a/src/text/span.rs b/src/text/span.rs index cbd5d51a..990c276f 100644 --- a/src/text/span.rs +++ b/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::*; +use crate::{prelude::*, style::Styled, text::StyledGrapheme}; /// Represents a part of a line that is contiguous and where all characters share the same style. /// diff --git a/src/text/text.rs b/src/text/text.rs index d9dc4d03..76483dc3 100644 --- a/src/text/text.rs +++ b/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. /// diff --git a/src/widgets.rs b/src/widgets.rs index e0a56a57..ce79f598 100644 --- a/src/widgets.rs +++ b/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 { diff --git a/src/widgets/barchart.rs b/src/widgets/barchart.rs index 189a2ed1..c1ecfcd2 100644 --- a/src/widgets/barchart.rs +++ b/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; diff --git a/src/widgets/block.rs b/src/widgets/block.rs index 98f4e064..bffcfb3b 100644 --- a/src/widgets/block.rs +++ b/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() diff --git a/src/widgets/block/title.rs b/src/widgets/block/title.rs index 1d6141d4..f07fff6b 100644 --- a/src/widgets/block/title.rs +++ b/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") diff --git a/src/widgets/canvas.rs b/src/widgets/canvas.rs index d51dc3f3..59e5b932 100644 --- a/src/widgets/canvas.rs +++ b/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 = match marker { - symbols::Marker::Dot => Box::new(CharGrid::new(width, height, dot)), - symbols::Marker::Block => Box::new(CharGrid::new(width, height, block)), - symbols::Marker::Bar => Box::new(CharGrid::new(width, height, bar)), - symbols::Marker::Braille => Box::new(BrailleGrid::new(width, height)), - symbols::Marker::HalfBlock => Box::new(HalfBlockGrid::new(width, height)), + Marker::Dot => Box::new(CharGrid::new(width, height, dot)), + Marker::Block => Box::new(CharGrid::new(width, height, block)), + Marker::Bar => Box::new(CharGrid::new(width, height, bar)), + Marker::Braille => Box::new(BrailleGrid::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, 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 } diff --git a/src/widgets/canvas/line.rs b/src/widgets/canvas/line.rs index 14882643..1ea9529d 100644 --- a/src/widgets/canvas/line.rs +++ b/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 crate::{buffer::Buffer, layout::Rect}; + use super::*; + 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])] diff --git a/src/widgets/canvas/map.rs b/src/widgets/canvas/map.rs index 504bccc1..f990d61f 100644 --- a/src/widgets/canvas/map.rs +++ b/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() { diff --git a/src/widgets/canvas/rectangle.rs b/src/widgets/canvas/rectangle.rs index 93496f03..f2e2ffdf 100644 --- a/src/widgets/canvas/rectangle.rs +++ b/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() { diff --git a/src/widgets/chart.rs b/src/widgets/chart.rs index d4a56b6a..837f166c 100644 --- a/src/widgets/chart.rs +++ b/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") diff --git a/src/widgets/gauge.rs b/src/widgets/gauge.rs index bc62f4dd..1d2f5881 100644 --- a/src/widgets/gauge.rs +++ b/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. /// diff --git a/src/widgets/list.rs b/src/widgets/list.rs index d884b4bb..1306a5e0 100755 --- a/src/widgets/list.rs +++ b/src/widgets/list.rs @@ -3,6 +3,7 @@ use unicode_width::UnicodeWidthStr; use crate::{ prelude::*, + style::Styled, widgets::{Block, HighlightSpacing}, }; diff --git a/src/widgets/paragraph.rs b/src/widgets/paragraph.rs index 78074dff..871ed093 100644 --- a/src/widgets/paragraph.rs +++ b/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}, diff --git a/src/widgets/sparkline.rs b/src/widgets/sparkline.rs index f690286e..51fb987c 100644 --- a/src/widgets/sparkline.rs +++ b/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. /// diff --git a/src/widgets/table/cell.rs b/src/widgets/table/cell.rs index 77e136fe..f51a82f4 100644 --- a/src/widgets/table/cell.rs +++ b/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`]. /// diff --git a/src/widgets/table/row.rs b/src/widgets/table/row.rs index 13986f31..728b9d06 100644 --- a/src/widgets/table/row.rs +++ b/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. /// diff --git a/src/widgets/table/table.rs b/src/widgets/table/table.rs index ff522e91..cf260822 100644 --- a/src/widgets/table/table.rs +++ b/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. /// diff --git a/src/widgets/tabs.rs b/src/widgets/tabs.rs index 7547b645..dd7758c6 100755 --- a/src/widgets/tabs.rs +++ b/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);