feat: Support adding an Offset to Position (#2239)

Adds Position::offset() and arithmentic ops (Position + Offset and
Position - Offset)

Fixes: https://github.com/ratatui/ratatui/issues/2018

ratatui-core/src/layout/position.rs

@@ -1,7 +1,8 @@
 #![warn(missing_docs)]
 use core::fmt;
+use core::ops::{Add, AddAssign, Sub, SubAssign};
 
-use crate::layout::Rect;
+use crate::layout::{Offset, Rect};
 
 /// Position in the terminal coordinate system.
 ///
@@ -23,10 +24,18 @@ use crate::layout::Rect;
 /// - [`from(Rect)`](Self::from) - Create from [`Rect`] (uses top-left corner)
 /// - [`into((u16, u16))`] - Convert to `(u16, u16)` tuple
 ///
+/// # Movement
+///
+/// - [`offset`](Self::offset) - Move by an [`Offset`]
+/// - [`Add<Offset>`](core::ops::Add) and [`Sub<Offset>`](core::ops::Sub) - Shift by offsets with
+///   clamping
+/// - [`AddAssign<Offset>`](core::ops::AddAssign) and [`SubAssign<Offset>`](core::ops::SubAssign) -
+///   In-place shifting
+///
 /// # Examples
 ///
 /// ```
-/// use ratatui_core::layout::{Position, Rect};
+/// use ratatui_core::layout::{Offset, Position, Rect};
 ///
 /// // the following are all equivalent
 /// let position = Position { x: 1, y: 2 };
@@ -36,6 +45,10 @@ use crate::layout::Rect;
 ///
 /// // position can be converted back into the components when needed
 /// let (x, y) = position.into();
+///
+/// // movement by offsets
+/// let position = Position::new(5, 5) + Offset::new(2, -3);
+/// assert_eq!(position, Position::new(7, 2));
 /// ```
 ///
 /// For comprehensive layout documentation and examples, see the [`layout`](crate::layout) module.
@@ -69,6 +82,15 @@ impl Position {
     pub const fn new(x: u16, y: u16) -> Self {
         Self { x, y }
     }
+
+    /// Moves the position by the given offset.
+    ///
+    /// Positive offsets move right and down, negative offsets move left and up. Values that would
+    /// move the position outside the `u16` range are clamped to the nearest edge.
+    #[must_use = "method returns the modified value"]
+    pub fn offset(self, offset: Offset) -> Self {
+        self + offset
+    }
 }
 
 impl From<(u16, u16)> for Position {
@@ -95,6 +117,68 @@ impl fmt::Display for Position {
     }
 }
 
+impl Add<Offset> for Position {
+    type Output = Self;
+
+    /// Moves the position by the given offset.
+    ///
+    /// Values that would move the position outside the `u16` range are clamped to the nearest
+    /// edge.
+    fn add(self, offset: Offset) -> Self {
+        let max = i32::from(u16::MAX);
+        let x = i32::from(self.x).saturating_add(offset.x).clamp(0, max) as u16;
+        let y = i32::from(self.y).saturating_add(offset.y).clamp(0, max) as u16;
+        Self { x, y }
+    }
+}
+
+impl Add<Position> for Offset {
+    type Output = Position;
+
+    /// Moves the position by the given offset.
+    ///
+    /// Values that would move the position outside the `u16` range are clamped to the nearest
+    /// edge.
+    fn add(self, position: Position) -> Position {
+        position + self
+    }
+}
+
+impl Sub<Offset> for Position {
+    type Output = Self;
+
+    /// Moves the position by the inverse of the given offset.
+    ///
+    /// Values that would move the position outside the `u16` range are clamped to the nearest
+    /// edge.
+    fn sub(self, offset: Offset) -> Self {
+        let max = i32::from(u16::MAX);
+        let x = i32::from(self.x).saturating_sub(offset.x).clamp(0, max) as u16;
+        let y = i32::from(self.y).saturating_sub(offset.y).clamp(0, max) as u16;
+        Self { x, y }
+    }
+}
+
+impl AddAssign<Offset> for Position {
+    /// Moves the position in place by the given offset.
+    ///
+    /// Values that would move the position outside the `u16` range are clamped to the nearest
+    /// edge.
+    fn add_assign(&mut self, offset: Offset) {
+        *self = *self + offset;
+    }
+}
+
+impl SubAssign<Offset> for Position {
+    /// Moves the position in place by the inverse of the given offset.
+    ///
+    /// Values that would move the position outside the `u16` range are clamped to the nearest
+    /// edge.
+    fn sub_assign(&mut self, offset: Offset) {
+        *self = *self - offset;
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use alloc::string::ToString;
@@ -104,15 +188,15 @@ mod tests {
     #[test]
     fn new() {
         let position = Position::new(1, 2);
-        assert_eq!(position.x, 1);
-        assert_eq!(position.y, 2);
+
+        assert_eq!(position, Position { x: 1, y: 2 });
     }
 
     #[test]
     fn from_tuple() {
         let position = Position::from((1, 2));
-        assert_eq!(position.x, 1);
-        assert_eq!(position.y, 2);
+
+        assert_eq!(position, Position { x: 1, y: 2 });
     }
 
     #[test]
@@ -127,8 +211,8 @@ mod tests {
     fn from_rect() {
         let rect = Rect::new(1, 2, 3, 4);
         let position = Position::from(rect);
-        assert_eq!(position.x, 1);
-        assert_eq!(position.y, 2);
+
+        assert_eq!(position, Position { x: 1, y: 2 });
     }
 
     #[test]
@@ -136,4 +220,34 @@ mod tests {
         let position = Position::new(1, 2);
         assert_eq!(position.to_string(), "(1, 2)");
     }
+
+    #[test]
+    fn offset_moves_position() {
+        let position = Position::new(2, 3).offset(Offset::new(5, 7));
+
+        assert_eq!(position, Position::new(7, 10));
+    }
+
+    #[test]
+    fn offset_clamps_to_bounds() {
+        let position = Position::new(1, 1).offset(Offset::MAX);
+
+        assert_eq!(position, Position::MAX);
+    }
+
+    #[test]
+    fn add_and_subtract_offset() {
+        let position = Position::new(10, 10) + Offset::new(-3, 4) - Offset::new(5, 20);
+
+        assert_eq!(position, Position::new(2, 0));
+    }
+
+    #[test]
+    fn add_assign_and_sub_assign_offset() {
+        let mut position = Position::new(5, 5);
+        position += Offset::new(2, 3);
+        position -= Offset::new(10, 1);
+
+        assert_eq!(position, Position::new(0, 7));
+    }
 }