From fcb47d60f3df205c18f5fa9459e9ba2c8d0c9649 Mon Sep 17 00:00:00 2001 From: Josh McKinney Date: Sun, 6 Apr 2025 10:00:59 -0700 Subject: [PATCH] feat!: rename Alignment to HorizontalAlignment and add VerticalAlignment (#1735) We don't anticipate removing or deprecating the type alias in the near future, but it is recommended to update your imports to use the new name. Added a VerticalAlignment enum to make the API more consistent. We don't have a specific use case for it yet, but it's better to add it now and be able to use it in the future. BREAKING-CHANGE: The `Alignment` enum has been renamed to `HorizontalAlignment` to better reflect its purpose. A type alias has been added to maintain backwards compatibility, however there are some cases where type aliases are not enough to maintain backwards compatibility. E.g. when using glob imports to import all the enum variants. This should not affect most users, but it is recommended to update your imports to use the new name. ```diff - use ratatui::layout::Alignment; + use ratatui::layout::HorizontalAlignment; - use Alignment::*; + use HorizontalAlignment::*; ``` --- BREAKING-CHANGES.md | 21 +++++++++++++ ratatui-core/src/layout.rs | 2 +- ratatui-core/src/layout/alignment.rs | 45 +++++++++++++++++++++++++++- ratatui-widgets/src/block.rs | 3 +- ratatui/src/prelude.rs | 3 +- 5 files changed, 70 insertions(+), 4 deletions(-) diff --git a/BREAKING-CHANGES.md b/BREAKING-CHANGES.md index 33ec0af8..0153d014 100644 --- a/BREAKING-CHANGES.md +++ b/BREAKING-CHANGES.md @@ -14,6 +14,7 @@ This is a quick summary of the sections below: - The `From` impls for backend types are now replaced with more specific traits - `FrameExt` trait for `unstable-widget-ref` feature - `List::highlight_symbol` now accepts `Into` instead of `&str` + - 'layout::Alignment' is renamed to 'layout::HorizontalAlignment' - [v0.29.0](#v0290) - `Sparkline::data` takes `IntoIterator` instead of `&[u64]` and is no longer const - Removed public fields from `Rect` iterators @@ -78,6 +79,26 @@ This is a quick summary of the sections below: ## Unreleased (0.30.0) +### `layout::Alignment` is renamed to `layout::HorizontalAlignment` ([#1735]) + +[#1735]: https://github.com/ratatui/ratatui/pull/1691 + +The `Alignment` enum has been renamed to `HorizontalAlignment` to better reflect its purpose. A type +alias has been added to maintain backwards compatibility, however there are some cases where type +aliases are not enough to maintain backwards compatibility. E.g. when using glob imports to import +all the enum variants. + +We don't expect to remove or deprecate the type alias in the near future, but it is recommended to +update your imports to use the new name. + +```diff +- use ratatui::layout::Alignment; ++ use ratatui::layout::HorizontalAlignment; + +- use Alignment::*; ++ use HorizontalAlignment::*; +``` + ### `List::highlight_symbol` accepts `Into` ([#1595]) [#1595]: https://github.com/ratatui/ratatui/pull/1595 diff --git a/ratatui-core/src/layout.rs b/ratatui-core/src/layout.rs index f7e2cf18..a6982607 100644 --- a/ratatui-core/src/layout.rs +++ b/ratatui-core/src/layout.rs @@ -11,7 +11,7 @@ mod position; mod rect; mod size; -pub use alignment::Alignment; +pub use alignment::{Alignment, HorizontalAlignment, VerticalAlignment}; pub use constraint::Constraint; pub use direction::Direction; pub use flex::Flex; diff --git a/ratatui-core/src/layout/alignment.rs b/ratatui-core/src/layout/alignment.rs index 8ca21216..7b6553cb 100644 --- a/ratatui-core/src/layout/alignment.rs +++ b/ratatui-core/src/layout/alignment.rs @@ -1,13 +1,34 @@ use strum::{Display, EnumString}; +/// A type alias for `HorizontalAlignment`. +/// +/// Prior to Ratatui 0.30.0, [`HorizontalAlignment`] was named `Alignment`. This alias is provided +/// for backwards compatibility. Because this type is used almost everywhere in Ratatui related apps +/// and libraries, it's unlikely that this alias will be removed in the future. +pub type Alignment = HorizontalAlignment; + +/// A type representing horizontal alignment. +/// +/// Prior to Ratatui 0.30.0, this type was named `Alignment`. In Ratatui 0.30.0, the name was +/// changed to `HorizontalAlignment` to make it more descriptive. The old name is still available as +/// an alias for backwards compatibility. #[derive(Debug, Default, Display, EnumString, Clone, Copy, Eq, PartialEq, Hash)] -pub enum Alignment { +pub enum HorizontalAlignment { #[default] Left, Center, Right, } +/// A type representing vertical alignment. +#[derive(Debug, Default, Display, EnumString, Clone, Copy, Eq, PartialEq, Hash)] +pub enum VerticalAlignment { + #[default] + Top, + Center, + Bottom, +} + #[cfg(test)] mod tests { use strum::ParseError; @@ -28,4 +49,26 @@ mod tests { assert_eq!("Right".parse::(), Ok(Alignment::Right)); assert_eq!("".parse::(), Err(ParseError::VariantNotFound)); } + + #[test] + fn vertical_alignment_to_string() { + assert_eq!(VerticalAlignment::Top.to_string(), "Top"); + assert_eq!(VerticalAlignment::Center.to_string(), "Center"); + assert_eq!(VerticalAlignment::Bottom.to_string(), "Bottom"); + } + + #[test] + fn vertical_alignment_from_str() { + let top = "Top".parse::(); + assert_eq!(top, Ok(VerticalAlignment::Top)); + + let center = "Center".parse::(); + assert_eq!(center, Ok(VerticalAlignment::Center)); + + let bottom = "Bottom".parse::(); + assert_eq!(bottom, Ok(VerticalAlignment::Bottom)); + + let invalid = "".parse::(); + assert_eq!(invalid, Err(ParseError::VariantNotFound)); + } } diff --git a/ratatui-widgets/src/block.rs b/ratatui-widgets/src/block.rs index 2ff84f04..441e5b73 100644 --- a/ratatui-widgets/src/block.rs +++ b/ratatui-widgets/src/block.rs @@ -900,6 +900,7 @@ impl Styled for Block<'_> { #[cfg(test)] mod tests { + use ratatui_core::layout::HorizontalAlignment; use ratatui_core::style::{Color, Modifier, Stylize}; use rstest::rstest; use strum::ParseError; @@ -1222,7 +1223,7 @@ mod tests { #[test] fn title() { - use Alignment::*; + use HorizontalAlignment::*; use Position::*; let mut buffer = Buffer::empty(Rect::new(0, 0, 11, 3)); #[allow(deprecated)] // until Title is removed diff --git a/ratatui/src/prelude.rs b/ratatui/src/prelude.rs index 9bdbd363..a0e45873 100644 --- a/ratatui/src/prelude.rs +++ b/ratatui/src/prelude.rs @@ -38,7 +38,8 @@ pub use crate::backend::{FromTermion, IntoTermion, TermionBackend}; pub use crate::backend::{FromTermwiz, IntoTermwiz, TermwizBackend}; pub use crate::buffer::{self, Buffer}; pub use crate::layout::{ - self, Alignment, Constraint, Direction, Layout, Margin, Position, Rect, Size, + self, Alignment, Constraint, Direction, HorizontalAlignment, Layout, Margin, Position, Rect, + Size, VerticalAlignment, }; pub use crate::style::{self, Color, Modifier, Style, Stylize}; pub use crate::text::{self, Line, Masked, Span, Text};