fix(widgets)!: rename StatefulWidgetRef::render_ref to render_stateful_ref

This commit renames the `StatefulWidgetRef::render_ref` method to
`render_stateful_ref`. This helps avoid collisions with the `WidgetRef`
trait's `render_ref` method. This change is breaking and requires
updating all implementations of `StatefulWidgetRef`.

BREAKING CHANGE: `StatefulWidgetRef::render_ref` has been renamed to
`StatefulWidgetRef::render_stateful_ref`.

```diff
 trait StatefulWidgetRef {
     type State;
-    fn render_ref(&self, area: Rect, buf: &mut Buffer, state: &mut Self::State) { }
+    fn render_stateful_ref(&self, area: Rect, buf: &mut Buffer, state: &mut Self::State) { }
 }
```

Partially addresses <https://github.com/ratatui-org/ratatui/issues/996>

BREAKING-CHANGES.md

@@ -55,6 +55,20 @@ This is a quick summary of the sections below:
 
 ## Unreleased
 
+### `StatefulWidgetRef::render_ref` renamed to `render_stateful_ref` [#1184]
+
+[#1184]: https://github.com/ratatui-org/ratatui/pull/1184
+
+This change helps avoid collisions with `WidgetRef::render_ref`.
+
+```diff
+ trait StatefulWidgetRef {
+     type State;
+-    fn render_ref(&self, area: Rect, buf: &mut Buffer, state: &mut Self::State) { }
++    fn render_stateful_ref(&self, area: Rect, buf: &mut Buffer, state: &mut Self::State) { }
+ }
+```
+
 ### Prelude items added / removed ([#1149])
 
 The following items have been removed from the prelude:

src/terminal/frame.rs

@@ -129,7 +129,7 @@ impl Frame<'_> {
     }
 
     /// Render a [`StatefulWidgetRef`] to the current buffer using
-    /// [`StatefulWidgetRef::render_ref`].
+    /// [`StatefulWidgetRef::render_stateful_ref`].
     ///
     /// Usually the area argument is the size of the current frame or a sub-area of the current
     /// frame (which can be obtained using [`Layout`] to split the total area).
@@ -157,7 +157,7 @@ impl Frame<'_> {
     where
         W: StatefulWidgetRef,
     {
-        widget.render_ref(area, self.buffer, state);
+        widget.render_stateful_ref(area, self.buffer, state);
     }
 
     /// After drawing this frame, make the cursor visible and put it at the specified (x, y)

src/widgets.rs

@@ -360,14 +360,14 @@ impl<W: WidgetRef> WidgetRef for Option<W> {
 ///
 /// This trait was introduced in Ratatui 0.26.0 and is implemented for all the internal stateful
 /// widgets. Implementors should prefer to implement this over the `StatefulWidget` trait and add an
-/// implementation of `StatefulWidget` that calls `StatefulWidgetRef::render_ref` where backwards
+/// implementation of `StatefulWidget` that calls `StatefulWidgetRef::render_stateful_ref` where
-/// compatibility is required.
+/// backwards compatibility is required.
 ///
 /// A blanket implementation of `StatefulWidget` for `&W` where `W` implements `StatefulWidgetRef`
 /// is provided.
 ///
-/// See the documentation for [`WidgetRef`] for more information on boxed widgets.
+/// See the documentation for [`WidgetRef`] for more information on boxed widgets. See the
-/// See the documentation for [`StatefulWidget`] for more information on stateful widgets.
+/// documentation for [`StatefulWidget`] for more information on stateful widgets.
 ///
 /// # Examples
 ///
@@ -379,7 +379,7 @@ impl<W: WidgetRef> WidgetRef for Option<W> {
 ///
 /// impl StatefulWidgetRef for PersonalGreeting {
 ///     type State = String;
-///     fn render_ref(&self, area: Rect, buf: &mut Buffer, state: &mut Self::State) {
+///     fn render_stateful_ref(&self, area: Rect, buf: &mut Buffer, state: &mut Self::State) {
 ///         Line::raw(format!("Hello {}", state)).render(area, buf);
 ///     }
 /// }
@@ -387,7 +387,7 @@ impl<W: WidgetRef> WidgetRef for Option<W> {
 /// impl StatefulWidget for PersonalGreeting {
 ///     type State = String;
 ///     fn render(self, area: Rect, buf: &mut Buffer, state: &mut Self::State) {
-///         (&self).render_ref(area, buf, state);
+///         self.render_stateful_ref(area, buf, state);
 ///     }
 /// }
 ///
@@ -406,7 +406,7 @@ pub trait StatefulWidgetRef {
     type State;
     /// Draws the current state of the widget in the given buffer. That is the only method required
     /// to implement a custom stateful widget.
-    fn render_ref(&self, area: Rect, buf: &mut Buffer, state: &mut Self::State);
+    fn render_stateful_ref(&self, area: Rect, buf: &mut Buffer, state: &mut Self::State);
 }
 
 // Note: while StatefulWidgetRef is marked as unstable, the blanket implementation of StatefulWidget
@@ -420,7 +420,7 @@ pub trait StatefulWidgetRef {
 // impl<W: StatefulWidgetRef> StatefulWidget for &W {
 //     type State = W::State;
 //     fn render(self, area: Rect, buf: &mut Buffer, state: &mut Self::State) {
-//         StatefulWidgetRef::render_ref(self, area, buf, state);
+//         self.render_stateful_ref(area, buf, state);
 //     }
 // }
 
@@ -583,7 +583,7 @@ mod tests {
 
         impl StatefulWidgetRef for PersonalGreeting {
             type State = String;
-            fn render_ref(&self, area: Rect, buf: &mut Buffer, state: &mut Self::State) {
+            fn render_stateful_ref(&self, area: Rect, buf: &mut Buffer, state: &mut Self::State) {
                 Line::from(format!("Hello {state}")).render(area, buf);
             }
         }
@@ -591,7 +591,7 @@ mod tests {
         #[rstest]
         fn render_ref(mut buf: Buffer, mut state: String) {
             let widget = PersonalGreeting;
-            widget.render_ref(buf.area, &mut buf, &mut state);
+            widget.render_stateful_ref(buf.area, &mut buf, &mut state);
             assert_eq!(buf, Buffer::with_lines(["Hello world         "]));
         }
 
@@ -610,7 +610,7 @@ mod tests {
         #[rstest]
         fn box_render_render(mut buf: Buffer, mut state: String) {
             let widget = Box::new(PersonalGreeting);
-            widget.render_ref(buf.area, &mut buf, &mut state);
+            widget.render_stateful_ref(buf.area, &mut buf, &mut state);
             assert_eq!(buf, Buffer::with_lines(["Hello world         "]));
         }
     }

src/widgets/list.rs

@@ -854,7 +854,7 @@ impl Widget for List<'_> {
 impl WidgetRef for List<'_> {
     fn render_ref(&self, area: Rect, buf: &mut Buffer) {
         let mut state = ListState::default();
-        StatefulWidgetRef::render_ref(self, area, buf, &mut state);
+        self.render_stateful_ref(area, buf, &mut state);
     }
 }
 
@@ -862,7 +862,7 @@ impl StatefulWidget for List<'_> {
     type State = ListState;
 
     fn render(self, area: Rect, buf: &mut Buffer, state: &mut Self::State) {
-        StatefulWidgetRef::render_ref(&self, area, buf, state);
+        self.render_stateful_ref(area, buf, state);
     }
 }
 
@@ -870,14 +870,14 @@ impl StatefulWidget for List<'_> {
 impl StatefulWidget for &List<'_> {
     type State = ListState;
     fn render(self, area: Rect, buf: &mut Buffer, state: &mut Self::State) {
-        StatefulWidgetRef::render_ref(self, area, buf, state);
+        self.render_stateful_ref(area, buf, state);
     }
 }
 
 impl StatefulWidgetRef for List<'_> {
     type State = ListState;
 
-    fn render_ref(&self, area: Rect, buf: &mut Buffer, state: &mut Self::State) {
+    fn render_stateful_ref(&self, area: Rect, buf: &mut Buffer, state: &mut Self::State) {
         buf.set_style(area, self.style);
         self.block.render_ref(area, buf);
         let list_area = self.block.inner_if_some(area);

src/widgets/table/table.rs

@@ -596,14 +596,14 @@ impl StatefulWidget for Table<'_> {
 impl StatefulWidget for &Table<'_> {
     type State = TableState;
     fn render(self, area: Rect, buf: &mut Buffer, state: &mut Self::State) {
-        StatefulWidgetRef::render_ref(self, area, buf, state);
+        self.render_stateful_ref(area, buf, state);
     }
 }
 
 impl StatefulWidgetRef for Table<'_> {
     type State = TableState;
 
-    fn render_ref(&self, area: Rect, buf: &mut Buffer, state: &mut Self::State) {
+    fn render_stateful_ref(&self, area: Rect, buf: &mut Buffer, state: &mut Self::State) {
         buf.set_style(area, self.style);
         self.block.render_ref(area, buf);
         let table_area = self.block.inner_if_some(area);