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

@@ -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<Line>` instead of `&str`
+  - 'layout::Alignment' is renamed to 'layout::HorizontalAlignment'
 - [v0.29.0](#v0290)
   - `Sparkline::data` takes `IntoIterator<Item = SparklineBar>` 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<Line>` ([#1595])
 
 [#1595]: https://github.com/ratatui/ratatui/pull/1595

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;

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::<Alignment>(), Ok(Alignment::Right));
         assert_eq!("".parse::<Alignment>(), 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::<VerticalAlignment>();
+        assert_eq!(top, Ok(VerticalAlignment::Top));
+
+        let center = "Center".parse::<VerticalAlignment>();
+        assert_eq!(center, Ok(VerticalAlignment::Center));
+
+        let bottom = "Bottom".parse::<VerticalAlignment>();
+        assert_eq!(bottom, Ok(VerticalAlignment::Bottom));
+
+        let invalid = "".parse::<VerticalAlignment>();
+        assert_eq!(invalid, Err(ParseError::VariantNotFound));
+    }
 }

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

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};