feat(widgets): implement Widget for Widget refs

[joshka]

Many widgets can be rendered without changing their state.

This commit implements The Widget trait for references to
widgets and changes their implementations to be immutable.

This allows us to render widgets without consuming them by passing a ref
to the widget when calling Frame::render_widget().

// this might be stored in a struct
let paragraph = Paragraph::new("Hello world!");

let [left, right] = area.split(&Layout::horizontal([20, 20]));
frame.render_widget(&paragraph, left);
frame.render_widget(&paragraph, right); // we can reuse the widget

Implemented for all widgets except BarChart (which has an implementation that
modifies the internal state and requires a rewrite to fix.

Other widgets will be implemented in follow up commits.

Fixes: #164
Replaces PRs: #122 and #16
Enables: #132
Validated as a viable working solution by: #836

[codecov]

Codecov Report

Attention: 24 lines in your changes are missing coverage. Please review.

Comparison is base (736605e) 92.3% compared to head (4dc61c2) 92.3%.

❗ Current head 4dc61c2 differs from pull request most recent head 2269c5d. Consider uploading reports for the commit 2269c5d to get more accurate results

Files	Patch %	Lines
src/text/line.rs	44.4%	5 Missing ⚠️
src/text/span.rs	37.5%	5 Missing ⚠️
src/text/text.rs	44.4%	5 Missing ⚠️
src/widgets/list.rs	75.0%	4 Missing ⚠️
src/widgets/table/table.rs	66.6%	4 Missing ⚠️
src/widgets/canvas.rs	88.8%	1 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##            main    #833     +/-   ##
=======================================
- Coverage   92.3%   92.3%   -0.1%     
=======================================
  Files         61      61             
  Lines      16096   16141     +45     
=======================================
+ Hits       14872   14903     +31     
- Misses      1224    1238     +14     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[joshka]

Not all the examples have been updated, but this is about a good enough size to review as it stands.

[Valentin271]

As stated on discord I like this way of introducing render by reference. Approved!

[joshka]

Fun fact that I discovered earlier tonight.

RefWidget and MutWidget aren't actually necessary as the same effect can be had by implementing Widget on &T.

impl Widget for Block<'_> {
    fn render(self, area: Rect, buf: &mut Buffer) {
        (&self).render(area, buf);
    }
}

impl Widget for &Block<'_> {
    fn render(self, area: Rect, buf: &mut Buffer) {
        if area.is_empty() {
            return;
        }
        self.render_borders(area, buf);
        self.render_titles(area, buf);
    }
}

This allows you to do all the things you'd need to against a reference to the widget - you can store it, render a reference to it, etc.

let block = Block::default().title("Block").borders(Borders::ALL);

// does not compile
terminal.draw(|frame| {
    frame.render_widget(block, frame.size());
    let _area = block.inner(Rect::default());
})?;

// compiles
terminal.draw(|frame| {
    frame.render_widget(&block, frame.size());
    let _area = block.inner(Rect::default());
})?;

The upshot of this is that instead of adding two traits, we should instead implement Widget on &T more often.
The latest commit makes this change and removes the RefWidget and MutWidget traits.

[kdheepak]

And instead of MutWidget we continue using the stateful widget strategy? I actually like that a lot.

[orhun]

Seconding kd here, I think having impl &T is much cleaner solution. And yeah, nice find!

[joshka]

And instead of MutWidget we continue using the stateful widget strategy? I actually like that a lot.

impl Widget on &mut SomeWidget also works for situations where it makes sense to just consider the widget as the state instead of having external state.

What this does suggest is that we could do with some really clear docs on these scenarios.

[Valentin271]

+1 for implementing on &T and &mut T.
Also +1 for keeping the StatefulWidget pattern.

What this does suggest is that we could do with some really clear docs on these scenarios.

Yep if we keep StatefuleWidget and &mut T this is essential.

[joshka]

StatefulWdget shouldn't go anywere - it's useful to have the state and widget separate - mainly it simplifies the application state. Often state values won't have any lifetimes, as they're just storing indexes, etc. This simplification is helpful to newer users (as it avoids the pain of adding lifetimes everywhere).

[joshka]

I rebased this on main, squashed to remove the RefWidget implmentation, and updated the commit message and PR comment to fit as a good changelog message.

[Valentin271]

Looks good, only the doc is a mandatory change for me.

[joshka]

I've pulled in the changes from main and finished off all the widgets except BarChart.

[Valentin271]

All good to me. We'll finally have render by ref! I still can't believe it was this simple.