docs(examples): Update block example

[joshka]

[joshka]

I have several goals in re-doing this example:

• to create consistency the the setup / restore code, so we can document that once for all the examples
• to use similar styles, colors, sizing, etc. across widgets so it looks like a harmonious set of examples
• to show off every feature of the widget (a method per block makes it easy to see which code draws which block)
• to easily see catch visual regressions (e.g. this example highlights the title style bug)
• to be able to see visually how any PRs change the display of a widget

My hope is that by starting with a single easy example and then doing a more complex one, we have a couple of high quality examples that we can point at and then make the other widgets consistent with (e.g. add some issues labelled good first issue). Keeping the example code super simple and obvious makes it easy to update when we add / change functionality.

[joshka]

Added a couple of comments, and removed unnecessary anonymous lifetimes on Paragraphs.

ratatui/examples/block.rs

Lines 22 to 26 in 52c660a

	// These type aliases are used to make the code more readable by reducing repetition of the generic
	// types. They are not necessary for the functionality of the code.
	type Frame<'a> = ratatui::Frame<'a, CrosstermBackend<Stdout>>;
	type Terminal = ratatui::Terminal<CrosstermBackend<Stdout>>;
	type Result<T> = std::result::Result<T, Box<dyn Error>>;

ratatui/examples/block.rs

Lines 103 to 106 in 52c660a

	/// Calculate the layout of the UI elements.
	///
	/// Returns a tuple of the title area and the main areas.
	fn calculate_layout(area: Rect) -> (Rect, Vec<Vec<Rect>>) {

[codecov]

Codecov Report

Merging #351 (52c660a) into main (b9290b3) will decrease coverage by 0.33%.
Report is 9 commits behind head on main.
The diff coverage is 57.84%.

@@            Coverage Diff             @@
##             main     #351      +/-   ##
==========================================
- Coverage   85.08%   84.76%   -0.33%     
==========================================
  Files          40       40              
  Lines        8608     8603       -5     
==========================================
- Hits         7324     7292      -32     
- Misses       1284     1311      +27     

Files Changed	Coverage Δ
src/backend/crossterm.rs	0.00% <0.00%> (ø)
src/backend/termion.rs	27.46% <0.00%> (-0.59%)	⬇️
src/terminal.rs	55.73% <0.00%> (-0.47%)	⬇️
src/text/masked.rs	98.64% <0.00%> (ø)
src/widgets/calendar.rs	81.06% <0.00%> (-1.25%)	⬇️
src/widgets/canvas/circle.rs	97.14% <0.00%> (ø)
src/widgets/canvas/line.rs	59.67% <0.00%> (ø)
src/widgets/canvas/map.rs	0.00% <0.00%> (ø)
src/widgets/canvas/mod.rs	91.61% <0.00%> (-0.27%)	⬇️
src/widgets/canvas/points.rs	85.71% <0.00%> (+39.56%)	⬆️
... and 25 more

[kdheepak]

I like having an example like this!

Thoughts on making this interactive? If I could hit j and k to cycle through the various options you have here and the gif showed all cycles, that would be visually easier to grok.

Also, maybe for styled borders, only change foreground colors? (this is feedback that I think could go in a separate PR about making everything prettier)

[joshka]

Those are both good points.

I think it’s worth making interactive examples separate to the examples that demonstrate how things look. There’s a lot of ways of doing interactivity that work well small for demos but don’t scale well to apps that have more a diverse UI.

I experimented a little with having a cli flag to to choose the example to display so we could use VHS to generate smaller images to include directly in the docs, but it’s difficult to keep it simple with that approach. This example would be easy to refactor to add interactivity though, so perhaps let’s revisit the idea after this.

My rationale behind the styled borders using the background color was to make it easy to contrast the difference between the block style and border style. The background makes it obvious how the dark gray styling on the paragraph combines with the background block style. Background color also helps show which things affect blank space not just the text (which the foreground doesn’t). Do you think this makes sense?

Overall my goal is to try to pare this down to the absolute minimal amount of code necessary to show the info we need. There’s some ideas I have about fixing the backend implementations that could make this even smaller.

[joshka]

Merging this to make it easy to see that #363 fixes the bug