docs(examples): add missing examples to README (#1225)

Resolves: #1014

.github/ISSUE_TEMPLATE/bug_report.md

@@ -2,7 +2,7 @@
 name: Bug report
 about: Create an issue about a bug you encountered
 title: ''
-labels: bug
+labels: 'Type: Bug'
 assignees: ''
 ---
 
@@ -17,26 +17,22 @@ A detailed and complete issue is more likely to be processed quickly.
 A clear and concise description of what the bug is.
 -->
 
-
 ## To Reproduce
 <!--
 Try to reduce the issue to a simple code sample exhibiting the problem.
 Ideally, fork the project and add a test or an example.
 -->
 
-
 ## Expected behavior
 <!--
 A clear and concise description of what you expected to happen.
 -->
 
-
 ## Screenshots
 <!--
 If applicable, add screenshots, gifs or videos to help explain your problem.
 -->
 
-
 ## Environment
 <!--
 Add a description of the systems where you are observing the issue. For example:

.github/ISSUE_TEMPLATE/config.yml

@@ -1,5 +1,11 @@
 blank_issues_enabled: false
 contact_links:
+  - name: Frequently Asked Questions
+    url: https://ratatui.rs/faq/
+    about: Check the website FAQ section to see if your question has already been answered
+  - name: Ratatui Forum
+    url: https://forum.ratatui.rs
+    about: Ask questions about ratatui on our Forum
   - name: Discord Chat
     url: https://discord.gg/pMCEU9hNEj
     about: Ask questions about ratatui on Discord

.github/ISSUE_TEMPLATE/feature_request.md

@@ -2,7 +2,7 @@
 name: Feature request
 about: Suggest an idea for this project
 title: ''
-labels: enhancement
+labels: 'Type: Enhancement'
 assignees: ''
 
 ---

BREAKING-CHANGES.md

@@ -10,12 +10,15 @@ GitHub with a [breaking change] label.
 
 This is a quick summary of the sections below:
 
-- [Unreleased](#unreleased)
+- [v0.27.0](#v0270)
+  - List no clamps the selected index to list
+  - Prelude items added / removed
   - 'termion' updated to 4.0
   - `Rect::inner` takes `Margin` directly instead of reference
   - `Buffer::filled` takes `Cell` directly instead of reference
   - `Stylize::bg()` now accepts `Into<Color>`
   - Removed deprecated `List::start_corner`
+  - `LineGauge::gauge_style` is deprecated
 - [v0.26.0](#v0260)
   - `Flex::Start` is the new default flex mode for `Layout`
   - `patch_style` & `reset_style` now consume and return `Self`
@@ -53,7 +56,17 @@ This is a quick summary of the sections below:
   - MSRV is now 1.63.0
   - `List` no longer ignores empty strings
 
-## Unreleased
+## [v0.27.0](https://github.com/ratatui-org/ratatui/releases/tag/v0.27.0)
+
+### List no clamps the selected index to list ([#1159])
+
+[#1149]: https://github.com/ratatui-org/ratatui/pull/1149
+
+The `List` widget now clamps the selected index to the bounds of the list when navigating with
+`first`, `last`, `previous`, and `next`, as well as when setting the index directly with `select`.
+
+Previously selecting an index past the end of the list would show treat the list as having a
+selection which was not visible. Now the last item in the list will be selected instead.
 
 ### Prelude items added / removed ([#1149])
 
@@ -100,8 +113,6 @@ To update your app:
 + let position: some_crate::Position = ...;
 ```
 
-[#1149]: https://github.com/ratatui-org/ratatui/pull/1149
-
 ### Termion is updated to 4.0 [#1106]
 
 Changelog: <https://gitlab.redox-os.org/redox-os/termion/-/blob/master/CHANGELOG.md>
@@ -167,6 +178,19 @@ flexible types from calling scopes, though it can break some type inference in t
 
 `layout::Corner` was removed entirely.
 
+### `LineGauge::gauge_style` is deprecated ([#565])
+
+[#565]: https://github.com/ratatui-org/ratatui/pull/1148
+
+`LineGauge::gauge_style` is deprecated and replaced with `LineGauge::filled_style` and `LineGauge::unfilled_style`:
+
+```diff
+let gauge = LineGauge::default()
+- .gauge_style(Style::default().fg(Color::Red).bg(Color::Blue)
++ .filled_style(Style::default().fg(Color::Green))
++ .unfilled_style(Style::default().fg(Color::White));
+```
+
 ## [v0.26.0](https://github.com/ratatui-org/ratatui/releases/tag/v0.26.0)
 
 ### `Flex::Start` is the new default flex mode for `Layout` ([#881])

CHANGELOG.md

@@ -2,6 +2,379 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.27.0](https://github.com/ratatui-org/ratatui/releases/tag/v0.27.0) - 2024-06-24
+
+In this version, we have focused on enhancing usability and functionality with new features like
+background styles for LineGauge, palette colors, and various other improvements including
+improved performance. Also, we added brand new examples for tracing and creating hyperlinks!
+
+✨ **Release highlights**: <https://ratatui.rs/highlights/v027/>
+
+⚠️ List of breaking changes can be found [here](https://github.com/ratatui-org/ratatui/blob/main/BREAKING-CHANGES.md).
+
+### Features
+
+- [eef1afe](https://github.com/ratatui-org/ratatui/commit/eef1afe9155089dca489a9159c368a5ac07e7585) _(linegauge)_ Allow LineGauge background styles by @nowNick in [#565](https://github.com/ratatui-org/ratatui/pull/565)
+
+  ```text
+  This PR deprecates `gauge_style` in favor of `filled_style` and
+  `unfilled_style` which can have it's foreground and background styled.
+
+  `cargo run --example=line_gauge --features=crossterm`
+  ```
+
+  https://github.com/ratatui-org/ratatui/assets/5149215/5fb2ce65-8607-478f-8be4-092e08612f5b
+
+  Implements:<https://github.com/ratatui-org/ratatui/issues/424>
+
+- [1365620](https://github.com/ratatui-org/ratatui/commit/13656206064b53c7f86f179b570c7769399212a3) _(borders)_ Add FULL and EMPTY border sets by @joshka in [#1182](https://github.com/ratatui-org/ratatui/pull/1182)
+
+  `border::FULL` uses a full block symbol, while `border::EMPTY` uses an
+  empty space. This is useful for when you need to allocate space for the
+  border and apply the border style to a block without actually drawing a
+  border. This makes it possible to style the entire title area or a block
+  rather than just the title content.
+
+```rust
+use ratatui::{symbols::border, widgets::Block};
+let block = Block::bordered().title("Title").border_set(border::FULL);
+let block = Block::bordered().title("Title").border_set(border::EMPTY);
+```
+
+- [7a48c5b](https://github.com/ratatui-org/ratatui/commit/7a48c5b11b3d51b915ccc187d0499b6e0e88b89d) _(cell)_ Add EMPTY and (const) new method by @EdJoPaTo in [#1143](https://github.com/ratatui-org/ratatui/pull/1143)
+
+  ```text
+  This simplifies calls to `Buffer::filled` in tests.
+  ```
+
+- [3f2f2cd](https://github.com/ratatui-org/ratatui/commit/3f2f2cd6abf67a04809ff314025a462a3c2e2446) _(docs)_ Add tracing example by @joshka in [#1192](https://github.com/ratatui-org/ratatui/pull/1192)
+
+  ```text
+  Add an example that demonstrates logging to a file for:
+  ```
+
+  <https://forum.ratatui.rs/t/how-do-you-println-debug-your-tui-programs/66>
+
+```shell
+cargo run --example tracing
+RUST_LOG=trace cargo run --example=tracing
+cat tracing.log
+```
+
+![Made with VHS](https://vhs.charm.sh/vhs-21jgJCedh2YnFDONw0JW7l.gif)
+
+- [1520ed9](https://github.com/ratatui-org/ratatui/commit/1520ed9d106f99580a9e529212e43dac06a2f6d2) _(layout)_ Impl Display for Position and Size by @joshka in [#1162](https://github.com/ratatui-org/ratatui/pull/1162)
+
+- [46977d8](https://github.com/ratatui-org/ratatui/commit/46977d88519d28ccac1c94e171af0c9cca071dbc) _(list)_ Add list navigation methods (first, last, previous, next) by @joshka in [#1159](https://github.com/ratatui-org/ratatui/pull/1159) [**breaking**]
+
+  ```text
+  Also cleans up the list example significantly (see also
+  <https://github.com/ratatui-org/ratatui/issues/1157>)
+  ```
+
+  Fixes:<https://github.com/ratatui-org/ratatui/pull/1159>
+
+  BREAKING CHANGE:The `List` widget now clamps the selected index to the
+  bounds of the list when navigating with `first`, `last`, `previous`, and
+  `next`, as well as when setting the index directly with `select`.
+
+- [10d7788](https://github.com/ratatui-org/ratatui/commit/10d778866edea55207ff3f03d063c9fec619b9c9) _(style)_ Add conversions from the palette crate colors by @joshka in [#1172](https://github.com/ratatui-org/ratatui/pull/1172)
+
+  ````text
+  This is behind the "palette" feature flag.
+
+  ```rust
+  use palette::{LinSrgb, Srgb};
+  use ratatui::style::Color;
+
+  let color = Color::from(Srgb::new(1.0f32, 0.0, 0.0));
+  let color = Color::from(LinSrgb::new(1.0f32, 0.0, 0.0));
+  ```
+  ````
+
+- [7ef2dae](https://github.com/ratatui-org/ratatui/commit/7ef2daee060a7fe964a8de64eafcb6062228e035) _(text)_ support conversion from Display to Span, Line and Text by @orhun in [#1167](https://github.com/ratatui-org/ratatui/pull/1167)
+
+  ````text
+  Now you can create `Line` and `Text` from numbers like so:
+
+  ```rust
+  let line = 42.to_line();
+  let text = 666.to_text();
+  ```
+  ````
+
+- [74a32af](https://github.com/ratatui-org/ratatui/commit/74a32afbaef8851f9462b27094d88d518e56addf) _(uncategorized)_ Re-export backends from the ratatui crate by @joshka in [#1151](https://github.com/ratatui-org/ratatui/pull/1151)
+
+  ```text
+  `crossterm`, `termion`, and `termwiz` can now be accessed as
+  `ratatui::{crossterm, termion, termwiz}` respectively. This makes it
+  possible to just add the Ratatui crate as a dependency and use the
+  backend of choice without having to add the backend crates as
+  dependencies.
+
+  To update existing code, replace all instances of `crossterm::` with
+  `ratatui::crossterm::`, `termion::` with `ratatui::termion::`, and
+  `termwiz::` with `ratatui::termwiz::`.
+  ```
+
+- [3594180](https://github.com/ratatui-org/ratatui/commit/35941809e11ab43309dd83a8f67bb375f5e7ff2b) _(uncategorized)_ Make Stylize's `.bg(color)` generic by @kdheepak in [#1103](https://github.com/ratatui-org/ratatui/pull/1103) [**breaking**]
+
+- [0b5fd6b](https://github.com/ratatui-org/ratatui/commit/0b5fd6bf8eb64662df96900faea3608d4cbb3984) _(uncategorized)_ Add writer() and writer_mut() to termion and crossterm backends by @enricozb in [#991](https://github.com/ratatui-org/ratatui/pull/991)
+
+  ```text
+  It is sometimes useful to obtain access to the writer if we want to see
+  what has been written so far. For example, when using &mut [u8] as a
+  writer.
+  ```
+
+### Bug Fixes
+
+- [efa965e](https://github.com/ratatui-org/ratatui/commit/efa965e1e806c60cb1bdb2d1715f960db0857704) _(line)_ Remove newlines when converting strings to Lines by @joshka in [#1191](https://github.com/ratatui-org/ratatui/pull/1191)
+
+  `Line::from("a\nb")` now returns a line with two `Span`s instead of 1
+
+  Fixes:https://github.com/ratatui-org/ratatui/issues/1111
+
+- [d370aa7](https://github.com/ratatui-org/ratatui/commit/d370aa75af99da3e0c41ceb28e2d02ee81cd2538) _(span)_ Ensure that zero-width characters are rendered correctly by @joshka in [#1165](https://github.com/ratatui-org/ratatui/pull/1165)
+
+- [127d706](https://github.com/ratatui-org/ratatui/commit/127d706ee4876a58230f42f4a730b18671eae167) _(table)_ Ensure render offset without selection properly by @joshka in [#1187](https://github.com/ratatui-org/ratatui/pull/1187)
+
+  Fixes:<https://github.com/ratatui-org/ratatui/issues/1179>
+
+- [4bfdc15](https://github.com/ratatui-org/ratatui/commit/4bfdc15b80ba14489d359ab1f88564c3bd016c19) _(uncategorized)_ Render of &str and String doesn't respect area.width by @thscharler in [#1177](https://github.com/ratatui-org/ratatui/pull/1177)
+
+- [e6871b9](https://github.com/ratatui-org/ratatui/commit/e6871b9e21c25acf1e203f4860198c37aa9429a1) _(uncategorized)_ Avoid unicode-width breaking change in tests by @joshka in [#1171](https://github.com/ratatui-org/ratatui/pull/1171)
+
+  ```text
+  unicode-width 0.1.13 changed the width of \u{1} from 0 to 1.
+  Our tests assumed that \u{1} had a width of 0, so this change replaces
+  the \u{1} character with \u{200B} (zero width space) in the tests.
+
+  Upstream issue (closed as won't fix):
+  https://github.com/unicode-rs/unicode-width/issues/55
+  ```
+
+- [7f3efb0](https://github.com/ratatui-org/ratatui/commit/7f3efb02e6f846fc72079f0921abd2cee09d2d83) _(uncategorized)_ Pin unicode-width crate to 0.1.13 by @joshka in [#1170](https://github.com/ratatui-org/ratatui/pull/1170)
+
+  ```text
+  semver breaking change in 0.1.13
+  <https://github.com/unicode-rs/unicode-width/issues/55>
+
+  <!-- Please read CONTRIBUTING.md before submitting any pull request. -->
+  ```
+
+- [42cda6d](https://github.com/ratatui-org/ratatui/commit/42cda6d28706bf83308787ca784f374f6c286a02) _(uncategorized)_ Prevent panic from string_slice by @EdJoPaTo in [#1140](https://github.com/ratatui-org/ratatui/pull/1140)
+
+  <https://rust-lang.github.io/rust-clippy/master/index.html#string_slice>
+
+### Refactor
+
+- [73fd367](https://github.com/ratatui-org/ratatui/commit/73fd367a740924ce80ef7a0cd13a66b5094f7a54) _(block)_ Group builder pattern methods by @EdJoPaTo in [#1134](https://github.com/ratatui-org/ratatui/pull/1134)
+
+- [257db62](https://github.com/ratatui-org/ratatui/commit/257db6257f392a07ee238b439344d91566beb740) _(cell)_ Must_use and simplify style() by @EdJoPaTo in [#1124](https://github.com/ratatui-org/ratatui/pull/1124)
+
+  ```text
+  <!-- Please read CONTRIBUTING.md before submitting any pull request. -->
+  ```
+
+- [bf20369](https://github.com/ratatui-org/ratatui/commit/bf2036987f04d83f4f2b8338fab1b4fd7f4cc81d) _(cell)_ Reset instead of applying default by @EdJoPaTo in [#1127](https://github.com/ratatui-org/ratatui/pull/1127)
+
+  ```text
+  Using reset is clearer to me what actually happens. On the other case a
+  struct is created to override the old one completely which basically
+  does the same in a less clear way.
+  ```
+
+- [7d175f8](https://github.com/ratatui-org/ratatui/commit/7d175f85c1905c08adf547dd37cc89c63039f480) _(lint)_ Fix new lint warnings by @EdJoPaTo in [#1178](https://github.com/ratatui-org/ratatui/pull/1178)
+
+- [cf67ed9](https://github.com/ratatui-org/ratatui/commit/cf67ed9b884347cef034b09e0e9f9d4aff74ab0a) _(lint)_ Use clippy::or_fun_call by @EdJoPaTo in [#1138](https://github.com/ratatui-org/ratatui/pull/1138)
+
+  <https://rust-lang.github.io/rust-clippy/master/index.html#or_fun_call>
+
+- [4770e71](https://github.com/ratatui-org/ratatui/commit/4770e715819475cdca2f2ccdbac00cba203cd6d2) _(list)_ Remove deprecated `start_corner` and `Corner` by @Valentin271 in [#759](https://github.com/ratatui-org/ratatui/pull/759) [**breaking**]
+
+  `List::start_corner` was deprecated in v0.25. Use `List::direction` and
+  `ListDirection` instead.
+
+```diff
+- list.start_corner(Corner::TopLeft);
+- list.start_corner(Corner::TopRight);
+// This is not an error, BottomRight rendered top to bottom previously
+- list.start_corner(Corner::BottomRight);
+// all becomes
++ list.direction(ListDirection::TopToBottom);
+```
+
+```diff
+- list.start_corner(Corner::BottomLeft);
+// becomes
++ list.direction(ListDirection::BottomToTop);
+```
+
+`layout::Corner` is removed entirely.
+
+- [4f77910](https://github.com/ratatui-org/ratatui/commit/4f7791079edd16b54dc8cdfc95bb72b282a09576) _(padding)_ Add Padding::ZERO as a constant by @EdJoPaTo in [#1133](https://github.com/ratatui-org/ratatui/pull/1133)
+
+  ```text
+  Deprecate Padding::zero()
+  ```
+
+- [8061813](https://github.com/ratatui-org/ratatui/commit/8061813f324c08e11196e62fca22c2f6b9216b7e) _(uncategorized)_ Expand glob imports by @joshka in [#1152](https://github.com/ratatui-org/ratatui/pull/1152)
+
+  ```text
+  Consensus is that explicit imports make it easier to understand the
+  example code. This commit removes the prelude import from all examples
+  and replaces it with the necessary imports, and expands other glob
+  imports (widget::*, Constraint::*, KeyCode::*, etc.) everywhere else.
+  Prelude glob imports not in examples are not covered by this PR.
+
+  See https://github.com/ratatui-org/ratatui/issues/1150 for more details.
+  ```
+
+- [d929971](https://github.com/ratatui-org/ratatui/commit/d92997105bde15a1fd43829466ec8cc46bffe121) _(uncategorized)_ Dont manually impl Default for defaults by @EdJoPaTo in [#1142](https://github.com/ratatui-org/ratatui/pull/1142)
+
+  ```text
+  Replace `impl Default` by `#[derive(Default)]` when its implementation
+  equals.
+  ```
+
+- [8a60a56](https://github.com/ratatui-org/ratatui/commit/8a60a561c95691912cbf41d55866abafcba0127d) _(uncategorized)_ Needless_pass_by_ref_mut by @EdJoPaTo in [#1137](https://github.com/ratatui-org/ratatui/pull/1137)
+
+  <https://rust-lang.github.io/rust-clippy/master/index.html#needless_pass_by_ref_mut>
+
+- [1de9a82](https://github.com/ratatui-org/ratatui/commit/1de9a82b7a871a83995d224785cae139c6f4787b) _(uncategorized)_ Simplify if let by @EdJoPaTo in [#1135](https://github.com/ratatui-org/ratatui/pull/1135)
+
+  ```text
+  While looking through lints
+  [`clippy::option_if_let_else`](https://rust-lang.github.io/rust-clippy/master/index.html#option_if_let_else)
+  found these. Other findings are more complex so I skipped them.
+  ```
+
+### Documentation
+
+- [1908b06](https://github.com/ratatui-org/ratatui/commit/1908b06b4a497ff1cfb2c8d8c165d2a241ee1864) _(borders)_ Add missing closing code blocks by @orhun in [#1195](https://github.com/ratatui-org/ratatui/pull/1195)
+
+- [38bb196](https://github.com/ratatui-org/ratatui/commit/38bb19640449c7a3eee3a2fba6450071395e5e06) _(breaking-changes)_ Mention `LineGauge::gauge_style` by @orhun in [#1194](https://github.com/ratatui-org/ratatui/pull/1194)
+
+  see #565
+
+- [07efde5](https://github.com/ratatui-org/ratatui/commit/07efde5233752e1bcb7ae94a91b9e36b7fadb01b) _(examples)_ Add hyperlink example by @joshka in [#1063](https://github.com/ratatui-org/ratatui/pull/1063)
+
+- [7fdccaf](https://github.com/ratatui-org/ratatui/commit/7fdccafd52f4ddad1a3c9dda59fada59af21ecfa) _(examples)_ Add vhs tapes for constraint-explorer and minimal examples by @joshka in [#1164](https://github.com/ratatui-org/ratatui/pull/1164)
+
+- [4f307e6](https://github.com/ratatui-org/ratatui/commit/4f307e69db058891675d0f12d75ef49006c511d6) _(examples)_ Simplify paragraph example by @joshka in [#1169](https://github.com/ratatui-org/ratatui/pull/1169)
+
+  Related:https://github.com/ratatui-org/ratatui/issues/1157
+
+- [f429f68](https://github.com/ratatui-org/ratatui/commit/f429f688da536a52266144e63a1a7897ec6b7f26) _(examples)_ Remove lifetimes from the List example by @matta in [#1132](https://github.com/ratatui-org/ratatui/pull/1132)
+
+  ```text
+  Simplify the List example by removing lifetimes not strictly necessary
+  to demonstrate how Ratatui lists work. Instead, the sample strings are
+  copied into each `TodoItem`. To further simplify, I changed the code to
+  use a new TodoItem::new function, rather than an implementation of the
+  `From` trait.
+  ```
+
+- [308c1df](https://github.com/ratatui-org/ratatui/commit/308c1df6495ee4373f808007a1566ca7e9279933) _(readme)_ Add links to forum by @joshka in [#1188](https://github.com/ratatui-org/ratatui/pull/1188)
+
+- [2f8a936](https://github.com/ratatui-org/ratatui/commit/2f8a9363fc6c54fe2b10792c9f57fbb40b06bc0f) _(uncategorized)_ Fix links on docs.rs by @EdJoPaTo in [#1144](https://github.com/ratatui-org/ratatui/pull/1144)
+
+  ```text
+  This also results in a more readable Cargo.toml as the locations of the
+  things are more obvious now.
+
+  Includes rewording of the underline-color feature.
+
+  Logs of the errors: https://docs.rs/crate/ratatui/0.26.3/builds/1224962
+  Also see #989
+  ```
+
+### Performance
+
+- [4ce67fc](https://github.com/ratatui-org/ratatui/commit/4ce67fc84e3bc472e9ae97aece85f8ffae091834) _(buffer)_ Filled moves the cell to be filled by @EdJoPaTo in [#1148](https://github.com/ratatui-org/ratatui/pull/1148) [**breaking**]
+
+- [8b447ec](https://github.com/ratatui-org/ratatui/commit/8b447ec4d6276c3110285e663417487ff18dafc1) _(rect)_ `Rect::inner` takes `Margin` directly instead of reference by @EdJoPaTo in [#1008](https://github.com/ratatui-org/ratatui/pull/1008) [**breaking**]
+
+  BREAKING CHANGE:Margin needs to be passed without reference now.
+
+```diff
+-let area = area.inner(&Margin {
++let area = area.inner(Margin {
+     vertical: 0,
+     horizontal: 2,
+ });
+```
+
+### Styling
+
+- [df4b706](https://github.com/ratatui-org/ratatui/commit/df4b706674de806bdf2a1fb8c04d0654b6b0b891) _(uncategorized)_ Enable more rustfmt settings by @EdJoPaTo in [#1125](https://github.com/ratatui-org/ratatui/pull/1125)
+
+### Testing
+
+- [d6587bc](https://github.com/ratatui-org/ratatui/commit/d6587bc6b0db955aeac6af167e1b8ef81a3afcc9) _(style)_ Use rstest by @EdJoPaTo in [#1136](https://github.com/ratatui-org/ratatui/pull/1136)
+
+  ```text
+  <!-- Please read CONTRIBUTING.md before submitting any pull request. -->
+  ```
+
+### Miscellaneous Tasks
+
+- [7b45f74](https://github.com/ratatui-org/ratatui/commit/7b45f74b719ff18329ddbf9f05a9ac53bf06f71d) _(prelude)_ Add / remove items by @joshka in [#1149](https://github.com/ratatui-org/ratatui/pull/1149) [**breaking**]
+
+  ```text
+  his PR removes the items from the prelude that don't form a coherent
+  common vocabulary and adds the missing items that do.
+
+  Based on a comment at
+  <https://www.reddit.com/r/rust/comments/1cle18j/comment/l2uuuh7/>
+  ```
+
+  BREAKING CHANGE:The following items have been removed from the prelude:
+
+- `style::Styled` - this trait is useful for widgets that want to
+  support the Stylize trait, but it adds complexity as widgets have two
+  `style` methods and a `set_style` method.
+- `symbols::Marker` - this item is used by code that needs to draw to
+  the `Canvas` widget, but it's not a common item that would be used by
+  most users of the library.
+- `terminal::{CompletedFrame, TerminalOptions, Viewport}` - these items
+  are rarely used by code that needs to interact with the terminal, and
+  they're generally only ever used once in any app.
+
+The following items have been added to the prelude:
+
+- `layout::{Position, Size}` - these items are used by code that needs
+  to interact with the layout system. These are newer items that were
+  added in the last few releases, which should be used more liberally.
+
+- [cd64367](https://github.com/ratatui-org/ratatui/commit/cd64367e244a1588206f653fd79678ce62a86a2f) _(symbols)_ Add tests for line symbols by @joshka in [#1186](https://github.com/ratatui-org/ratatui/pull/1186)
+
+- [8cfc316](https://github.com/ratatui-org/ratatui/commit/8cfc316bccb48e88660d14cd18c0df2264c4d6ce) _(uncategorized)_ Alphabetize examples in Cargo.toml by @joshka in [#1145](https://github.com/ratatui-org/ratatui/pull/1145)
+
+### Build
+
+- [70df102](https://github.com/ratatui-org/ratatui/commit/70df102de0154cdfbd6508659cf6ed649f820bc8) _(bench)_ Improve benchmark consistency by @EdJoPaTo in [#1126](https://github.com/ratatui-org/ratatui/pull/1126)
+
+  ```text
+  Codegen units are optimized on their own. Per default bench / release
+  have 16 codegen units. What ends up in a codeget unit is rather random
+  and can influence a benchmark result as a code change can move stuff
+  into a different codegen unit → prevent / allow LLVM optimizations
+  unrelated to the actual change.
+
+  More details: https://doc.rust-lang.org/cargo/reference/profiles.html
+  ```
+
+### New Contributors
+
+- @thscharler made their first contribution in [#1177](https://github.com/ratatui-org/ratatui/pull/1177)
+- @matta made their first contribution in [#1132](https://github.com/ratatui-org/ratatui/pull/1132)
+- @nowNick made their first contribution in [#565](https://github.com/ratatui-org/ratatui/pull/565)
+- @enricozb made their first contribution in [#991](https://github.com/ratatui-org/ratatui/pull/991)
+
+**Full Changelog**: https://github.com/ratatui-org/ratatui/compare/v0.26.3...v0.27.0
+
 ## [0.26.3](https://github.com/ratatui-org/ratatui/releases/tag/v0.26.3) - 2024-05-19
 
 We are happy to announce a brand new [**Ratatui Forum**](https://forum.ratatui.rs) 🐭 for Rust & TUI enthusiasts.

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "ratatui"
-version = "0.26.3" # crate version
+version = "0.27.0" # crate version
 authors = ["Florian Dehau <work@fdehau.com>", "The Ratatui Developers"]
 description = "A library that's all about cooking up terminal user interfaces"
 documentation = "https://docs.rs/ratatui/latest/ratatui/"
@@ -30,12 +30,12 @@ cassowary = "0.3"
 compact_str = "0.7.1"
 crossterm = { version = "0.27", optional = true }
 document-features = { version = "0.2.7", optional = true }
+instability = "0.3.1"
 itertools = "0.13"
 lru = "0.12.0"
 paste = "1.0.2"
 palette = { version = "0.7.6", optional = true }
 serde = { version = "1", optional = true, features = ["derive"] }
-stability = "0.2.0"
 strum = { version = "0.26", features = ["derive"] }
 strum_macros = { version = "0.26.3" }
 termion = { version = "4.0.0", optional = true }

examples/README.md

@@ -141,6 +141,30 @@ of the VHS tape.
 
 <https://github.com/ratatui-org/ratatui/assets/381361/485e775a-e0b5-4133-899b-1e8aeb56e774>
 
+## Constraint Explorer
+
+Demonstrates the behaviour of each
+[`Constraint`](https://docs.rs/ratatui/latest/ratatui/layout/enum.Constraint.html) option with
+respect to each other across different `Flex` modes.
+
+```shell
+cargo run --example=constraint-explorer --features=crossterm
+```
+
+![Constraint Explorer][constraint-explorer.gif]
+
+## Constraints
+
+Demonstrates how to use
+[`Constraint`](https://docs.rs/ratatui/latest/ratatui/layout/enum.Constraint.html) options for
+defining layout element sizes.
+
+![Constraints][constraints.gif]
+
+```shell
+cargo run --example=constraints --features=crossterm
+```
+
 ## Custom Widget
 
 Demonstrates how to implement the
@@ -164,6 +188,17 @@ cargo run --example=gauge --features=crossterm
 
 ![Gauge][gauge.gif]
 
+## Flex
+
+Demonstrates the different [`Flex`](https://docs.rs/ratatui/latest/ratatui/layout/enum.Flex.html)
+modes for controlling layout space distribution.
+
+```shell
+cargo run --example=flex --features=crossterm
+```
+
+![Flex][flex.gif]
+
 ## Line Gauge
 
 Demonstrates the [`Line
@@ -176,6 +211,16 @@ cargo run --example=line_gauge --features=crossterm
 
 ![LineGauge][line_gauge.gif]
 
+## Hyperlink
+
+Demonstrates how to use OSC 8 to create hyperlinks in the terminal.
+
+```shell
+cargo run --example=hyperlink --features="crossterm unstable-widget-ref"
+```
+
+![Hyperlink][hyperlink.gif]
+
 ## Inline
 
 Demonstrates how to use the
@@ -222,6 +267,16 @@ cargo run --example=modifiers --features=crossterm
 
 ![Modifiers][modifiers.gif]
 
+## Minimal
+
+Demonstrates how to create a minimal `Hello World!` program.
+
+```shell
+cargo run --example=minimal --features=crossterm
+```
+
+![Minimal][minimal.gif]
+
 ## Panic
 
 Demonstrates how to handle panics by ensuring that panic messages are written correctly to the
@@ -313,6 +368,17 @@ cargo run --example=tabs --features=crossterm
 
 ![Tabs][tabs.gif]
 
+## Tracing
+
+Demonstrates how to use the [tracing crate](https://crates.io/crates/tracing) for logging. Creates
+a file named `tracing.log` in the current directory.
+
+```shell
+cargo run --example=tracing --features=crossterm
+```
+
+![Tracing][tracing.gif]
+
 ## User Input
 
 Demonstrates one approach to accepting user input. Source [user_input.rs](./user_input.rs).
@@ -350,15 +416,20 @@ examples/vhs/generate.bash
 [canvas.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/canvas.gif?raw=true
 [chart.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/chart.gif?raw=true
 [colors.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/colors.gif?raw=true
+[constraint-explorer.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/constraint-explorer.gif?raw=true
+[constraints.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/constraints.gif?raw=true
 [custom_widget.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/custom_widget.gif?raw=true
 [demo.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/demo.gif?raw=true
 [demo2.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/demo2.gif?raw=true
+[flex.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/flex.gif?raw=true
 [gauge.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/gauge.gif?raw=true
 [hello_world.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/hello_world.gif?raw=true
+[hyperlink.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/hyperlink.gif?raw=true
 [inline.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/inline.gif?raw=true
 [layout.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/layout.gif?raw=true
 [list.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/list.gif?raw=true
 [line_gauge.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/line_gauge.gif?raw=true
+[minimal.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/minimal.gif?raw=true
 [modifiers.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/modifiers.gif?raw=true
 [panic.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/panic.gif?raw=true
 [paragraph.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/paragraph.gif?raw=true
@@ -368,6 +439,7 @@ examples/vhs/generate.bash
 [sparkline.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/sparkline.gif?raw=true
 [table.gif]:  https://vhs.charm.sh/vhs-6njXBytDf0rwPufUtmSSpI.gif
 [tabs.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/tabs.gif?raw=true
+[tracing.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/tracing.gif?raw=true
 [user_input.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/user_input.gif?raw=true
 
 [alpha version of Ratatui]: https://crates.io/crates/ratatui/versions

examples/colors_rgb.rs

@@ -37,12 +37,16 @@ use palette::{convert::FromColorUnclamped, Okhsv, Srgb};
 use ratatui::{
     backend::{Backend, CrosstermBackend},
     buffer::Buffer,
-    crossterm::event::{self, Event, KeyCode, KeyEventKind},
+    crossterm::{
+        event::{self, Event, KeyCode, KeyEventKind},
+        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+        ExecutableCommand,
+    },
     layout::{Constraint, Layout, Rect},
     style::Color,
+    terminal::Terminal,
     text::Text,
     widgets::Widget,
-    Terminal,
 };
 
 #[derive(Debug, Default)]
@@ -97,9 +101,9 @@ struct ColorsWidget {
 
 fn main() -> Result<()> {
     install_error_hooks()?;
-    let backend = CrosstermBackend::stdout()?;
-    let terminal = Terminal::new(backend)?;
+    let terminal = init_terminal()?;
     App::default().run(terminal)?;
+    restore_terminal()?;
     Ok(())
 }
 
@@ -268,12 +272,27 @@ fn install_error_hooks() -> Result<()> {
     let panic = panic.into_panic_hook();
     let error = error.into_eyre_hook();
     eyre::set_hook(Box::new(move |e| {
-        let _ = CrosstermBackend::restore(stdout());
+        let _ = restore_terminal();
         error(e)
     }))?;
     panic::set_hook(Box::new(move |info| {
-        let _ = CrosstermBackend::restore(stdout());
+        let _ = restore_terminal();
         panic(info);
     }));
     Ok(())
 }
+
+fn init_terminal() -> Result<Terminal<impl Backend>> {
+    enable_raw_mode()?;
+    stdout().execute(EnterAlternateScreen)?;
+    let mut terminal = Terminal::new(CrosstermBackend::new(stdout()))?;
+    terminal.clear()?;
+    terminal.hide_cursor()?;
+    Ok(terminal)
+}
+
+fn restore_terminal() -> Result<()> {
+    disable_raw_mode()?;
+    stdout().execute(LeaveAlternateScreen)?;
+    Ok(())
+}

examples/list.rs

@@ -13,19 +13,19 @@
 //! [examples]: https://github.com/ratatui-org/ratatui/blob/main/examples
 //! [examples readme]: https://github.com/ratatui-org/ratatui/blob/main/examples/README.md
 
-use std::{error::Error, io, io::stdout};
+use std::{error::Error, io};
 
-use color_eyre::config::HookBuilder;
+use crossterm::event::KeyEvent;
 use ratatui::{
-    backend::{Backend, CrosstermBackend},
+    backend::Backend,
     buffer::Buffer,
-    crossterm::{
-        event::{self, Event, KeyCode, KeyEventKind},
-        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-        ExecutableCommand,
+    crossterm::event::{self, Event, KeyCode, KeyEventKind},
+    layout::{Constraint, Layout, Rect},
+    style::{
+        palette::tailwind::{BLUE, GREEN, SLATE},
+        Color, Modifier, Style, Stylize,
     },
-    layout::{Alignment, Constraint, Layout, Rect},
-    style::{palette::tailwind, Color, Modifier, Style, Stylize},
+    symbols,
     terminal::Terminal,
     text::Line,
     widgets::{
@@ -34,342 +34,302 @@ use ratatui::{
     },
 };
 
-const TODO_HEADER_BG: Color = tailwind::BLUE.c950;
-const NORMAL_ROW_COLOR: Color = tailwind::SLATE.c950;
-const ALT_ROW_COLOR: Color = tailwind::SLATE.c900;
-const SELECTED_STYLE_FG: Color = tailwind::BLUE.c300;
-const TEXT_COLOR: Color = tailwind::SLATE.c200;
-const COMPLETED_TEXT_COLOR: Color = tailwind::GREEN.c500;
+const TODO_HEADER_STYLE: Style = Style::new().fg(SLATE.c100).bg(BLUE.c800);
+const NORMAL_ROW_BG: Color = SLATE.c950;
+const ALT_ROW_BG_COLOR: Color = SLATE.c900;
+const SELECTED_STYLE: Style = Style::new().bg(SLATE.c800).add_modifier(Modifier::BOLD);
+const TEXT_FG_COLOR: Color = SLATE.c200;
+const COMPLETED_TEXT_FG_COLOR: Color = GREEN.c500;
 
-#[derive(Copy, Clone)]
-enum Status {
-    Todo,
-    Completed,
+fn main() -> Result<(), Box<dyn Error>> {
+    tui::init_error_hooks()?;
+    let terminal = tui::init_terminal()?;
+
+    let mut app = App::default();
+    app.run(terminal)?;
+
+    tui::restore_terminal()?;
+    Ok(())
 }
 
+/// This struct holds the current state of the app. In particular, it has the `todo_list` field
+/// which is a wrapper around `ListState`. Keeping track of the state lets us render the
+/// associated widget with its state and have access to features such as natural scrolling.
+///
+/// Check the event handling at the bottom to see how to change the state on incoming events. Check
+/// the drawing logic for items on how to specify the highlighting style for selected items.
+struct App {
+    should_exit: bool,
+    todo_list: TodoList,
+}
+
+struct TodoList {
+    items: Vec<TodoItem>,
+    state: ListState,
+}
+
+#[derive(Debug)]
 struct TodoItem {
     todo: String,
     info: String,
     status: Status,
 }
 
-impl TodoItem {
-    fn new(todo: &str, info: &str, status: Status) -> Self {
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
+enum Status {
+    Todo,
+    Completed,
+}
+
+impl Default for App {
+    fn default() -> Self {
         Self {
-            todo: todo.to_string(),
-            info: info.to_string(),
-            status,
-        }
-    }
-}
-
-struct TodoList {
-    state: ListState,
-    items: Vec<TodoItem>,
-    last_selected: Option<usize>,
-}
-
-/// This struct holds the current state of the app. In particular, it has the `items` field which is
-/// a wrapper around `ListState`. Keeping track of the items state let us render the associated
-/// widget with its state and have access to features such as natural scrolling.
-///
-/// Check the event handling at the bottom to see how to change the state on incoming events.
-/// Check the drawing logic for items on how to specify the highlighting style for selected items.
-struct App {
-    items: TodoList,
-}
-
-fn main() -> Result<(), Box<dyn Error>> {
-    // setup terminal
-    init_error_hooks()?;
-    let terminal = init_terminal()?;
-
-    // create app and run it
-    App::new().run(terminal)?;
-
-    restore_terminal()?;
-
-    Ok(())
-}
-
-fn init_error_hooks() -> color_eyre::Result<()> {
-    let (panic, error) = HookBuilder::default().into_hooks();
-    let panic = panic.into_panic_hook();
-    let error = error.into_eyre_hook();
-    color_eyre::eyre::set_hook(Box::new(move |e| {
-        let _ = restore_terminal();
-        error(e)
-    }))?;
-    std::panic::set_hook(Box::new(move |info| {
-        let _ = restore_terminal();
-        panic(info);
-    }));
-    Ok(())
-}
-
-fn init_terminal() -> color_eyre::Result<Terminal<impl Backend>> {
-    enable_raw_mode()?;
-    stdout().execute(EnterAlternateScreen)?;
-    let backend = CrosstermBackend::new(stdout());
-    let terminal = Terminal::new(backend)?;
-    Ok(terminal)
-}
-
-fn restore_terminal() -> color_eyre::Result<()> {
-    disable_raw_mode()?;
-    stdout().execute(LeaveAlternateScreen)?;
-    Ok(())
-}
-
-impl App {
-    fn new() -> Self {
-        Self {
-            items: TodoList::with_items(&[
-                ("Rewrite everything with Rust!", "I can't hold my inner voice. He tells me to rewrite the complete universe with Rust", Status::Todo),
-                ("Rewrite all of your tui apps with Ratatui", "Yes, you heard that right. Go and replace your tui with Ratatui.", Status::Completed),
-                ("Pet your cat", "Minnak loves to be pet by you! Don't forget to pet and give some treats!", Status::Todo),
-                ("Walk with your dog", "Max is bored, go walk with him!", Status::Todo),
-                ("Pay the bills", "Pay the train subscription!!!", Status::Completed),
-                ("Refactor list example", "If you see this info that means I completed this task!", Status::Completed),
+            should_exit: false,
+            todo_list: TodoList::from_iter([
+                (Status::Todo, "Rewrite everything with Rust!", "I can't hold my inner voice. He tells me to rewrite the complete universe with Rust"),
+                (Status::Completed, "Rewrite all of your tui apps with Ratatui", "Yes, you heard that right. Go and replace your tui with Ratatui."),
+                (Status::Todo, "Pet your cat", "Minnak loves to be pet by you! Don't forget to pet and give some treats!"),
+                (Status::Todo, "Walk with your dog", "Max is bored, go walk with him!"),
+                (Status::Completed, "Pay the bills", "Pay the train subscription!!!"),
+                (Status::Completed, "Refactor list example", "If you see this info that means I completed this task!"),
             ]),
         }
     }
+}
 
-    /// Changes the status of the selected list item
-    fn change_status(&mut self) {
-        if let Some(i) = self.items.state.selected() {
-            self.items.items[i].status = match self.items.items[i].status {
-                Status::Completed => Status::Todo,
-                Status::Todo => Status::Completed,
-            }
+impl FromIterator<(Status, &'static str, &'static str)> for TodoList {
+    fn from_iter<I: IntoIterator<Item = (Status, &'static str, &'static str)>>(iter: I) -> Self {
+        let items = iter
+            .into_iter()
+            .map(|(status, todo, info)| TodoItem::new(status, todo, info))
+            .collect();
+        let state = ListState::default();
+        Self { items, state }
+    }
+}
+
+impl TodoItem {
+    fn new(status: Status, todo: &str, info: &str) -> Self {
+        Self {
+            status,
+            todo: todo.to_string(),
+            info: info.to_string(),
         }
     }
-
-    fn go_top(&mut self) {
-        self.items.state.select(Some(0));
-    }
-
-    fn go_bottom(&mut self) {
-        self.items.state.select(Some(self.items.items.len() - 1));
-    }
 }
 
 impl App {
     fn run(&mut self, mut terminal: Terminal<impl Backend>) -> io::Result<()> {
-        loop {
-            self.draw(&mut terminal)?;
-
+        while !self.should_exit {
+            terminal.draw(|f| f.render_widget(&mut *self, f.size()))?;
             if let Event::Key(key) = event::read()? {
-                if key.kind == KeyEventKind::Press {
-                    match key.code {
-                        KeyCode::Char('q') | KeyCode::Esc => return Ok(()),
-                        KeyCode::Char('h') | KeyCode::Left => self.items.unselect(),
-                        KeyCode::Char('j') | KeyCode::Down => self.items.next(),
-                        KeyCode::Char('k') | KeyCode::Up => self.items.previous(),
-                        KeyCode::Char('l') | KeyCode::Right | KeyCode::Enter => {
-                            self.change_status();
-                        }
-                        KeyCode::Char('g') => self.go_top(),
-                        KeyCode::Char('G') => self.go_bottom(),
-                        _ => {}
-                    }
-                }
+                self.handle_key(key);
+            };
+        }
+        Ok(())
+    }
+
+    fn handle_key(&mut self, key: KeyEvent) {
+        if key.kind != KeyEventKind::Press {
+            return;
+        }
+        match key.code {
+            KeyCode::Char('q') | KeyCode::Esc => self.should_exit = true,
+            KeyCode::Char('h') | KeyCode::Left => self.select_none(),
+            KeyCode::Char('j') | KeyCode::Down => self.select_next(),
+            KeyCode::Char('k') | KeyCode::Up => self.select_previous(),
+            KeyCode::Char('g') | KeyCode::Home => self.select_first(),
+            KeyCode::Char('G') | KeyCode::End => self.select_last(),
+            KeyCode::Char('l') | KeyCode::Right | KeyCode::Enter => {
+                self.toggle_status();
             }
+            _ => {}
         }
     }
 
-    fn draw(&mut self, terminal: &mut Terminal<impl Backend>) -> io::Result<()> {
-        terminal.draw(|f| f.render_widget(self, f.size()))?;
-        Ok(())
+    fn select_none(&mut self) {
+        self.todo_list.state.select(None);
+    }
+
+    fn select_next(&mut self) {
+        self.todo_list.state.select_next();
+    }
+    fn select_previous(&mut self) {
+        self.todo_list.state.select_previous();
+    }
+
+    fn select_first(&mut self) {
+        self.todo_list.state.select_first();
+    }
+
+    fn select_last(&mut self) {
+        self.todo_list.state.select_last();
+    }
+
+    /// Changes the status of the selected list item
+    fn toggle_status(&mut self) {
+        if let Some(i) = self.todo_list.state.selected() {
+            self.todo_list.items[i].status = match self.todo_list.items[i].status {
+                Status::Completed => Status::Todo,
+                Status::Todo => Status::Completed,
+            }
+        }
     }
 }
 
 impl Widget for &mut App {
     fn render(self, area: Rect, buf: &mut Buffer) {
-        // Create a space for header, todo list and the footer.
-        let vertical = Layout::vertical([
+        let [header_area, main_area, footer_area] = Layout::vertical([
             Constraint::Length(2),
-            Constraint::Min(0),
-            Constraint::Length(2),
-        ]);
-        let [header_area, rest_area, footer_area] = vertical.areas(area);
+            Constraint::Fill(1),
+            Constraint::Length(1),
+        ])
+        .areas(area);
 
-        // Create two chunks with equal vertical screen space. One for the list and the other for
-        // the info block.
-        let vertical = Layout::vertical([Constraint::Percentage(50), Constraint::Percentage(50)]);
-        let [upper_item_list_area, lower_item_list_area] = vertical.areas(rest_area);
+        let [list_area, item_area] =
+            Layout::vertical([Constraint::Fill(1), Constraint::Fill(1)]).areas(main_area);
 
-        render_title(header_area, buf);
-        self.render_todo(upper_item_list_area, buf);
-        self.render_info(lower_item_list_area, buf);
-        render_footer(footer_area, buf);
+        App::render_header(header_area, buf);
+        App::render_footer(footer_area, buf);
+        self.render_list(list_area, buf);
+        self.render_selected_item(item_area, buf);
     }
 }
 
+/// Rendering logic for the app
 impl App {
-    fn render_todo(&mut self, area: Rect, buf: &mut Buffer) {
-        // We create two blocks, one is for the header (outer) and the other is for list (inner).
-        let outer_block = Block::new()
-            .borders(Borders::NONE)
-            .title_alignment(Alignment::Center)
-            .title("TODO List")
-            .fg(TEXT_COLOR)
-            .bg(TODO_HEADER_BG);
-        let inner_block = Block::new()
-            .borders(Borders::NONE)
-            .fg(TEXT_COLOR)
-            .bg(NORMAL_ROW_COLOR);
+    fn render_header(area: Rect, buf: &mut Buffer) {
+        Paragraph::new("Ratatui List Example")
+            .bold()
+            .centered()
+            .render(area, buf);
+    }
 
-        // We get the inner area from outer_block. We'll use this area later to render the table.
-        let outer_area = area;
-        let inner_area = outer_block.inner(outer_area);
+    fn render_footer(area: Rect, buf: &mut Buffer) {
+        Paragraph::new("Use ↓↑ to move, ← to unselect, → to change status, g/G to go top/bottom.")
+            .centered()
+            .render(area, buf);
+    }
 
-        // We can render the header in outer_area.
-        outer_block.render(outer_area, buf);
+    fn render_list(&mut self, area: Rect, buf: &mut Buffer) {
+        let block = Block::new()
+            .title(Line::raw("TODO List").centered())
+            .borders(Borders::TOP)
+            .border_set(symbols::border::EMPTY)
+            .border_style(TODO_HEADER_STYLE)
+            .bg(NORMAL_ROW_BG);
 
         // Iterate through all elements in the `items` and stylize them.
         let items: Vec<ListItem> = self
-            .items
+            .todo_list
             .items
             .iter()
             .enumerate()
-            .map(|(i, todo_item)| todo_item.to_list_item(i))
+            .map(|(i, todo_item)| {
+                let color = alternate_colors(i);
+                ListItem::from(todo_item).bg(color)
+            })
             .collect();
 
         // Create a List from all list items and highlight the currently selected one
-        let items = List::new(items)
-            .block(inner_block)
-            .highlight_style(
-                Style::default()
-                    .add_modifier(Modifier::BOLD)
-                    .add_modifier(Modifier::REVERSED)
-                    .fg(SELECTED_STYLE_FG),
-            )
+        let list = List::new(items)
+            .block(block)
+            .highlight_style(SELECTED_STYLE)
             .highlight_symbol(">")
             .highlight_spacing(HighlightSpacing::Always);
 
-        // We can now render the item list
-        // (look careful we are using StatefulWidget's render.)
-        // ratatui::widgets::StatefulWidget::render as stateful_render
-        StatefulWidget::render(items, inner_area, buf, &mut self.items.state);
+        // We need to disambiguate this trait method as both `Widget` and `StatefulWidget` share the
+        // same method name `render`.
+        StatefulWidget::render(list, area, buf, &mut self.todo_list.state);
     }
 
-    fn render_info(&self, area: Rect, buf: &mut Buffer) {
+    fn render_selected_item(&self, area: Rect, buf: &mut Buffer) {
         // We get the info depending on the item's state.
-        let info = if let Some(i) = self.items.state.selected() {
-            match self.items.items[i].status {
-                Status::Completed => format!("✓ DONE: {}", self.items.items[i].info),
-                Status::Todo => format!("TODO: {}", self.items.items[i].info),
+        let info = if let Some(i) = self.todo_list.state.selected() {
+            match self.todo_list.items[i].status {
+                Status::Completed => format!("✓ DONE: {}", self.todo_list.items[i].info),
+                Status::Todo => format!("☐ TODO: {}", self.todo_list.items[i].info),
             }
         } else {
-            "Nothing to see here...".to_string()
+            "Nothing selected...".to_string()
         };
 
         // We show the list item's info under the list in this paragraph
-        let outer_info_block = Block::new()
-            .borders(Borders::NONE)
-            .title_alignment(Alignment::Center)
-            .title("TODO Info")
-            .fg(TEXT_COLOR)
-            .bg(TODO_HEADER_BG);
-        let inner_info_block = Block::new()
-            .borders(Borders::NONE)
-            .padding(Padding::horizontal(1))
-            .bg(NORMAL_ROW_COLOR);
-
-        // This is a similar process to what we did for list. outer_info_area will be used for
-        // header inner_info_area will be used for the list info.
-        let outer_info_area = area;
-        let inner_info_area = outer_info_block.inner(outer_info_area);
-
-        // We can render the header. Inner info will be rendered later
-        outer_info_block.render(outer_info_area, buf);
-
-        let info_paragraph = Paragraph::new(info)
-            .block(inner_info_block)
-            .fg(TEXT_COLOR)
-            .wrap(Wrap { trim: false });
+        let block = Block::new()
+            .title(Line::raw("TODO Info").centered())
+            .borders(Borders::TOP)
+            .border_set(symbols::border::EMPTY)
+            .border_style(TODO_HEADER_STYLE)
+            .bg(NORMAL_ROW_BG)
+            .padding(Padding::horizontal(1));
 
         // We can now render the item info
-        info_paragraph.render(inner_info_area, buf);
+        Paragraph::new(info)
+            .block(block)
+            .fg(TEXT_FG_COLOR)
+            .wrap(Wrap { trim: false })
+            .render(area, buf);
     }
 }
 
-fn render_title(area: Rect, buf: &mut Buffer) {
-    Paragraph::new("Ratatui List Example")
-        .bold()
-        .centered()
-        .render(area, buf);
-}
-
-fn render_footer(area: Rect, buf: &mut Buffer) {
-    Paragraph::new("\nUse ↓↑ to move, ← to unselect, → to change status, g/G to go top/bottom.")
-        .centered()
-        .render(area, buf);
-}
-
-impl TodoList {
-    fn with_items(items: &[(&str, &str, Status)]) -> Self {
-        Self {
-            state: ListState::default(),
-            items: items
-                .iter()
-                .map(|(todo, info, status)| TodoItem::new(todo, info, *status))
-                .collect(),
-            last_selected: None,
-        }
+const fn alternate_colors(i: usize) -> Color {
+    if i % 2 == 0 {
+        NORMAL_ROW_BG
+    } else {
+        ALT_ROW_BG_COLOR
     }
+}
 
-    fn next(&mut self) {
-        let i = match self.state.selected() {
-            Some(i) => {
-                if i >= self.items.len() - 1 {
-                    0
-                } else {
-                    i + 1
-                }
+impl From<&TodoItem> for ListItem<'_> {
+    fn from(value: &TodoItem) -> Self {
+        let line = match value.status {
+            Status::Todo => Line::styled(format!(" ☐ {}", value.todo), TEXT_FG_COLOR),
+            Status::Completed => {
+                Line::styled(format!(" ✓ {}", value.todo), COMPLETED_TEXT_FG_COLOR)
             }
-            None => self.last_selected.unwrap_or(0),
         };
-        self.state.select(Some(i));
-    }
-
-    fn previous(&mut self) {
-        let i = match self.state.selected() {
-            Some(i) => {
-                if i == 0 {
-                    self.items.len() - 1
-                } else {
-                    i - 1
-                }
-            }
-            None => self.last_selected.unwrap_or(0),
-        };
-        self.state.select(Some(i));
-    }
-
-    fn unselect(&mut self) {
-        let offset = self.state.offset();
-        self.last_selected = self.state.selected();
-        self.state.select(None);
-        *self.state.offset_mut() = offset;
+        ListItem::new(line)
     }
 }
 
-impl TodoItem {
-    fn to_list_item(&self, index: usize) -> ListItem {
-        let bg_color = match index % 2 {
-            0 => NORMAL_ROW_COLOR,
-            _ => ALT_ROW_COLOR,
-        };
-        let line = match self.status {
-            Status::Todo => Line::styled(format!(" ☐ {}", self.todo), TEXT_COLOR),
-            Status::Completed => Line::styled(
-                format!(" ✓ {}", self.todo),
-                (COMPLETED_TEXT_COLOR, bg_color),
-            ),
-        };
+mod tui {
+    use std::{io, io::stdout};
 
-        ListItem::new(line).bg(bg_color)
+    use color_eyre::config::HookBuilder;
+    use ratatui::{
+        backend::{Backend, CrosstermBackend},
+        crossterm::{
+            terminal::{
+                disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen,
+            },
+            ExecutableCommand,
+        },
+        terminal::Terminal,
+    };
+
+    pub fn init_error_hooks() -> color_eyre::Result<()> {
+        let (panic, error) = HookBuilder::default().into_hooks();
+        let panic = panic.into_panic_hook();
+        let error = error.into_eyre_hook();
+        color_eyre::eyre::set_hook(Box::new(move |e| {
+            let _ = restore_terminal();
+            error(e)
+        }))?;
+        std::panic::set_hook(Box::new(move |info| {
+            let _ = restore_terminal();
+            panic(info);
+        }));
+        Ok(())
+    }
+
+    pub fn init_terminal() -> io::Result<Terminal<impl Backend>> {
+        stdout().execute(EnterAlternateScreen)?;
+        enable_raw_mode()?;
+        Terminal::new(CrosstermBackend::new(stdout()))
+    }
+
+    pub fn restore_terminal() -> io::Result<()> {
+        stdout().execute(LeaveAlternateScreen)?;
+        disable_raw_mode()
     }
 }

examples/minimal.rs

@@ -15,7 +15,11 @@
 
 use ratatui::{
     backend::CrosstermBackend,
-    crossterm::event::{self, Event, KeyCode, KeyEventKind},
+    crossterm::{
+        event::{self, Event, KeyCode, KeyEventKind},
+        execute,
+        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+    },
     text::Text,
     Terminal,
 };
@@ -27,9 +31,9 @@ use ratatui::{
 /// [examples]: https://github.com/ratatui-org/ratatui/blob/main/examples
 /// [hello-world]: https://github.com/ratatui-org/ratatui/blob/main/examples/hello_world.rs
 fn main() -> Result<(), Box<dyn std::error::Error>> {
-    let backend = CrosstermBackend::stdout()?;
-    let mut terminal = Terminal::new(backend)?;
-    terminal.clear()?;
+    let mut terminal = Terminal::new(CrosstermBackend::new(std::io::stdout()))?;
+    enable_raw_mode()?;
+    execute!(terminal.backend_mut(), EnterAlternateScreen)?;
     loop {
         terminal.draw(|frame| frame.render_widget(Text::raw("Hello World!"), frame.size()))?;
         if let Event::Key(key) = event::read()? {
@@ -38,5 +42,7 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
             }
         }
     }
+    disable_raw_mode()?;
+    execute!(terminal.backend_mut(), LeaveAlternateScreen)?;
     Ok(())
 }

examples/vhs/constraint-explorer.tape

@@ -1,5 +1,5 @@
 # This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
-# To run this script, install vhs and run `vhs ./examples/constraints.tape`
+# To run this script, install vhs and run `vhs ./examples/constraint-explorer.tape`
 Output "target/constraint-explorer.gif"
 Set Theme "Aardvark Blue"
 Set FontSize 18

examples/vhs/demo2-destroy.tape

@@ -1,5 +1,5 @@
 # This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
-# To run this script, install vhs and run `vhs ./examples/demo.tape`
+# To run this script, install vhs and run `vhs ./examples/demo2-destroy.tape`
 # NOTE: Requires VHS 0.6.1 or later for Screenshot support
 Output "target/demo2-destroy.gif"
 Set Theme "Aardvark Blue"

examples/vhs/demo2-social.tape

@@ -1,5 +1,5 @@
 # This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
-# To run this script, install vhs and run `vhs ./examples/demo.tape`
+# To run this script, install vhs and run `vhs ./examples/demo2-social.tape`
 
 Output "target/demo2-social.gif"
 Set Theme "Aardvark Blue"

examples/vhs/demo2.tape

@@ -1,5 +1,5 @@
 # This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
-# To run this script, install vhs and run `vhs ./examples/demo.tape`
+# To run this script, install vhs and run `vhs ./examples/demo2.tape`
 # NOTE: Requires VHS 0.6.1 or later for Screenshot support
 Output "target/demo2.gif"
 Set Theme "Aardvark Blue"

examples/vhs/docsrs.tape

@@ -1,5 +1,5 @@
 # This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
-# To run this script, install vhs and run `vhs ./examples/demo.tape`
+# To run this script, install vhs and run `vhs ./examples/docsrs.tape`
 # NOTE: Requires VHS 0.6.1 or later for Screenshot support
 Output "target/docsrs.gif"
 Set Theme "Aardvark Blue"

examples/vhs/flex.tape

@@ -1,5 +1,5 @@
 # This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
-# To run this script, install vhs and run `vhs ./examples/layout.tape`
+# To run this script, install vhs and run `vhs ./examples/flex.tape`
 Output "target/flex.gif"
 Set Theme "Aardvark Blue"
 Set Width 1200

examples/vhs/hyperlink.tape

@@ -1,13 +1,13 @@
 # This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
-# To run this script, install vhs and run `vhs ./examples/hello_world.tape`
+# To run this script, install vhs and run `vhs ./examples/hyperlink.tape`
 Output "target/hyperlink.gif"
 Set Theme "Aardvark Blue"
-Set Width 600
-Set Height 150
+Set Width 1200
+Set Height 200
 Hide
 Type "cargo run --example=hyperlink --features=crossterm,unstable-widget-ref"
 Enter
-Sleep 2s
+Sleep 3s
 Show
 Sleep 1s
 Hide

examples/vhs/minimal.tape

@@ -1,5 +1,5 @@
 # This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
-# To run this script, install vhs and run `vhs ./examples/hello_world.tape`
+# To run this script, install vhs and run `vhs ./examples/minimal.tape`
 Output "target/minimal.gif"
 Set Theme "Aardvark Blue"
 Set Width 1200

examples/vhs/ratatui-logo.tape

@@ -1,5 +1,5 @@
 # This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
-# To run this script, install vhs and run `vhs ./examples/popup.tape`
+# To run this script, install vhs and run `vhs ./examples/ratatui-logo.tape`
 Output "target/ratatui-logo.gif"
 Set Theme "Aardvark Blue"
 Set Width 550

examples/vhs/tracing.tape

@@ -1,5 +1,5 @@
 # This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
-# To run this script, install vhs and run `vhs ./examples/barchart.tape`
+# To run this script, install vhs and run `vhs ./examples/tracing.tape`
 Output "target/tracing.gif"
 Set Theme "Aardvark Blue"
 Set Width 1200

src/backend.rs

@@ -104,10 +104,7 @@ use std::io;
 
 use strum::{Display, EnumString};
 
-use crate::{
-    buffer::Cell,
-    layout::{Rect, Size},
-};
+use crate::{buffer::Cell, layout::Size, prelude::Rect};
 
 #[cfg(feature = "termion")]
 mod termion;

src/backend/crossterm.rs

@@ -5,77 +5,77 @@
 use std::io::{self, Write};
 
 #[cfg(feature = "underline-color")]
-use crate::crossterm::style::SetUnderlineColor;
+use crossterm::style::SetUnderlineColor;
+
 use crate::{
     backend::{Backend, ClearType, WindowSize},
     buffer::Cell,
     crossterm::{
         cursor::{Hide, MoveTo, Show},
-        event::{
-            DisableBracketedPaste, DisableFocusChange, DisableMouseCapture, EnableBracketedPaste,
-            EnableFocusChange, EnableMouseCapture, KeyboardEnhancementFlags,
-            PopKeyboardEnhancementFlags, PushKeyboardEnhancementFlags,
-        },
         execute, queue,
         style::{
             Attribute as CAttribute, Attributes as CAttributes, Color as CColor, Colors,
             ContentStyle, Print, SetAttribute, SetBackgroundColor, SetColors, SetForegroundColor,
         },
-        terminal::{
-            disable_raw_mode, enable_raw_mode, Clear, EnterAlternateScreen, LeaveAlternateScreen,
-        },
+        terminal::{self, Clear},
     },
-    layout::{Rect, Size},
+    layout::Size,
+    prelude::Rect,
     style::{Color, Modifier, Style},
 };
 
 /// A [`Backend`] implementation that uses [Crossterm] to render to the terminal.
 ///
-/// The `CrosstermBackend` struct is a wrapper around a writer implementing [`Write`], which is used
-/// to send commands to the terminal. It provides methods for drawing content, manipulating the
-/// cursor, and clearing the terminal screen.
+/// The `CrosstermBackend` struct is a wrapper around a writer implementing [`Write`], which is
+/// used to send commands to the terminal. It provides methods for drawing content, manipulating
+/// the cursor, and clearing the terminal screen.
 ///
-/// Convenience methods ([`CrosstermBackend::stdout`] and [`CrosstermBackend::stderr`] are provided
-/// to create a `CrosstermBackend` with [`std::io::stdout`] or [`std::io::stderr`] as the writer
-/// with raw mode enabled and the terminal switched to the alternate screen.
+/// Most applications should not call the methods on `CrosstermBackend` directly, but will instead
+/// use the [`Terminal`] struct, which provides a more ergonomic interface.
 ///
-/// If the default settings are not desired, the `CrosstermBackend` can be configured using the
-/// `with_*` methods. These methods return an [`io::Result`] containing self so that they can be
-/// chained with other methods. The settings are restored when the `CrosstermBackend` is dropped.
-/// - [`CrosstermBackend::with_raw_mode`] enables raw mode for the terminal.
-/// - [`CrosstermBackend::with_alternate_screen`] switches to the alternate screen.
-/// - [`CrosstermBackend::with_mouse_capture`] enables mouse capture.
-/// - [`CrosstermBackend::with_bracketed_paste`] enables bracketed paste.
-/// - [`CrosstermBackend::with_focus_change`] enables focus change.
-/// - [`CrosstermBackend::with_keyboard_enhancement_flags`] enables keyboard enhancement flags.
-///
-/// If a backend is configured using the `with_*` methods, the settings are restored when the
-/// `CrosstermBackend` is dropped.
+/// Usually applications will enable raw mode and switch to alternate screen mode after creating
+/// a `CrosstermBackend`. This is done by calling [`crossterm::terminal::enable_raw_mode`] and
+/// [`crossterm::terminal::EnterAlternateScreen`] (and the corresponding disable/leave functions
+/// when the application exits). This is not done automatically by the backend because it is
+/// possible that the application may want to use the terminal for other purposes (like showing
+/// help text) before entering alternate screen mode.
 ///
 /// # Example
 ///
 /// ```rust,no_run
+/// use std::io::{stderr, stdout};
+///
 /// use ratatui::{
-///     backend::{Backend, CrosstermBackend},
-///     crossterm::event::KeyboardEnhancementFlags,
+///     crossterm::{
+///         terminal::{
+///             disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen,
+///         },
+///         ExecutableCommand,
+///     },
+///     prelude::*,
 /// };
 ///
-/// let backend = CrosstermBackend::stdout()?;
+/// let mut backend = CrosstermBackend::new(stdout());
 /// // or
-/// let backend = CrosstermBackend::stderr()?;
-/// // or with custom settings
-/// let backend = CrosstermBackend::new(std::io::stdout())
-///     .with_raw_mode()?
-///     .with_alternate_screen()?
-///     .with_mouse_capture()?
-///     .with_bracketed_paste()?
-///     .with_focus_change()?
-///     .with_keyboard_enhancement_flags(KeyboardEnhancementFlags::DISAMBIGUATE_ESCAPE_CODES)?;
+/// let backend = CrosstermBackend::new(stderr());
+/// let mut terminal = Terminal::new(backend)?;
+///
+/// enable_raw_mode()?;
+/// stdout().execute(EnterAlternateScreen)?;
+///
+/// terminal.clear()?;
+/// terminal.draw(|frame| {
+///     // -- snip --
+/// })?;
+///
+/// stdout().execute(LeaveAlternateScreen)?;
+/// disable_raw_mode()?;
+///
 /// # std::io::Result::Ok(())
 /// ```
 ///
-/// See the the [Examples] directory for more examples. See the [`backend`] module documentation for
-/// more details on raw mode and alternate screen.
+/// See the the [Examples] directory for more examples. See the [`backend`] module documentation
+/// for more details on raw mode and alternate screen.
 ///
 /// [`Write`]: std::io::Write
 /// [`Terminal`]: crate::terminal::Terminal
@@ -83,16 +83,9 @@ use crate::{
 /// [Crossterm]: https://crates.io/crates/crossterm
 /// [Examples]: https://github.com/ratatui-org/ratatui/tree/main/examples/README.md
 #[derive(Debug, Default, Clone, Eq, PartialEq, Hash)]
-#[allow(clippy::struct_excessive_bools)]
 pub struct CrosstermBackend<W: Write> {
     /// The writer used to send commands to the terminal.
     writer: W,
-    restore_raw_mode_on_drop: bool,
-    restore_alternate_screen_on_drop: bool,
-    restore_mouse_capture_on_drop: bool,
-    restore_bracketed_paste_on_drop: bool,
-    restore_focus_change_on_drop: bool,
-    restore_keyboard_enhancement_flags_on_drop: bool,
 }
 
 impl<W> CrosstermBackend<W>
@@ -101,30 +94,19 @@ where
 {
     /// Creates a new `CrosstermBackend` with the given writer.
     ///
-    /// Applications will typically use [`CrosstermBackend::stdout`] or [`CrosstermBackend::stderr`]
-    /// to create a `CrosstermBackend` with [`std::io::stdout`] or [`std::io::stderr`] as the
-    /// writer.
-    ///
     /// # Example
     ///
     /// ```rust,no_run
-    /// # use ratatui::backend::CrosstermBackend;
-    /// let backend = CrosstermBackend::new(std::io::stdout());
+    /// # use std::io::stdout;
+    /// # use ratatui::prelude::*;
+    /// let backend = CrosstermBackend::new(stdout());
     /// ```
     pub const fn new(writer: W) -> Self {
-        Self {
-            writer,
-            restore_raw_mode_on_drop: false,
-            restore_alternate_screen_on_drop: false,
-            restore_mouse_capture_on_drop: false,
-            restore_bracketed_paste_on_drop: false,
-            restore_focus_change_on_drop: false,
-            restore_keyboard_enhancement_flags_on_drop: false,
-        }
+        Self { writer }
     }
 
     /// Gets the writer.
-    #[stability::unstable(
+    #[instability::unstable(
         feature = "backend-writer",
         issue = "https://github.com/ratatui-org/ratatui/pull/991"
     )]
@@ -136,7 +118,7 @@ where
     ///
     /// Note: writing to the writer may cause incorrect output after the write. This is due to the
     /// way that the Terminal implements diffing Buffers.
-    #[stability::unstable(
+    #[instability::unstable(
         feature = "backend-writer",
         issue = "https://github.com/ratatui-org/ratatui/pull/991"
     )]
@@ -145,223 +127,6 @@ where
     }
 }
 
-impl CrosstermBackend<io::Stdout> {
-    /// Creates a new `CrosstermBackend` with `std::io::stdout`, enables raw mode, and switches to
-    /// the alternate screen.
-    ///
-    /// Raw mode and alternate screen are restored when the `CrosstermBackend` is dropped.
-    ///
-    /// # Example
-    ///
-    /// ```rust,no_run
-    /// # use ratatui::backend::CrosstermBackend;
-    /// let backend = CrosstermBackend::stdout();
-    /// ```
-    pub fn stdout() -> io::Result<Self> {
-        Self::new(io::stdout())
-            .with_raw_mode()?
-            .with_alternate_screen()
-    }
-}
-
-impl CrosstermBackend<io::Stderr> {
-    /// Creates a new `CrosstermBackend` with `std::io::stderr`, enables raw mode, and switches to
-    /// the alternate screen.
-    ///
-    /// Raw mode and alternate screen are restored when the `CrosstermBackend` is dropped.
-    ///
-    /// # Example
-    ///
-    /// ```rust,no_run
-    /// # use ratatui::backend::CrosstermBackend;
-    /// let backend = CrosstermBackend::stderr();
-    /// ```
-    pub fn stderr() -> io::Result<Self> {
-        Self::new(io::stderr())
-            .with_raw_mode()?
-            .with_alternate_screen()
-    }
-}
-
-impl<W: Write> CrosstermBackend<W> {
-    /// Enables raw mode for the terminal.
-    ///
-    /// Returns an [`io::Result`] containing self so that it can be chained with other methods.
-    ///
-    /// Raw mode is restored when the `CrosstermBackend` is dropped.
-    ///
-    /// # Example
-    ///
-    /// ```rust,no_run
-    /// # use ratatui::backend::CrosstermBackend;
-    /// let backend = CrosstermBackend::stdout()?.with_raw_mode()?;
-    /// # std::io::Result::Ok(())
-    /// ```
-    pub fn with_raw_mode(mut self) -> io::Result<Self> {
-        enable_raw_mode()?;
-        self.restore_raw_mode_on_drop = true;
-        Ok(self)
-    }
-
-    /// Switches to the alternate screen.
-    ///
-    /// Returns an [`io::Result`] containing self so that it can be chained with other methods.
-    ///
-    /// Alternate screen is restored when the `CrosstermBackend` is dropped.
-    ///
-    /// # Example
-    ///
-    /// ```rust,no_run
-    /// # use ratatui::backend::CrosstermBackend;
-    /// let backend = CrosstermBackend::stdout()?.with_alternate_screen()?;
-    /// # std::io::Result::Ok(())
-    /// ```
-    pub fn with_alternate_screen(mut self) -> io::Result<Self> {
-        execute!(self.writer, EnterAlternateScreen)?;
-        self.restore_alternate_screen_on_drop = true;
-        Ok(self)
-    }
-
-    /// Enables mouse capture for the terminal.
-    ///
-    /// Returns an [`io::Result`] containing self so that it can be chained with other methods.
-    ///
-    /// Mouse capture is disabled when the `CrosstermBackend` is dropped.
-    ///
-    /// # Example
-    ///
-    /// ```rust,no_run
-    /// # use ratatui::backend::CrosstermBackend;
-    /// let backend = CrosstermBackend::stdout()?.with_mouse_capture()?;
-    /// # std::io::Result::Ok(())
-    /// ```
-    pub fn with_mouse_capture(mut self) -> io::Result<Self> {
-        execute!(self.writer, EnableMouseCapture)?;
-        self.restore_mouse_capture_on_drop = true;
-        Ok(self)
-    }
-
-    /// Enables bracketed paste for the terminal.
-    ///
-    /// Returns an [`io::Result`] containing self so that it can be chained with other methods.
-    ///
-    /// # Example
-    ///
-    /// ```rust,no_run
-    /// # use ratatui::backend::CrosstermBackend;
-    /// let backend = CrosstermBackend::stdout()?.with_bracketed_paste()?;
-    /// # std::io::Result::Ok(())
-    /// ```
-    pub fn with_bracketed_paste(mut self) -> io::Result<Self> {
-        execute!(self.writer, EnableBracketedPaste)?;
-        self.restore_bracketed_paste_on_drop = true;
-        Ok(self)
-    }
-
-    /// Enables focus change for the terminal.
-    ///
-    /// Returns an [`io::Result`] containing self so that it can be chained with other methods.
-    ///
-    /// # Example
-    ///
-    /// ```rust,no_run
-    /// # use ratatui::backend::CrosstermBackend;
-    /// let backend = CrosstermBackend::stdout()?.with_focus_change()?;
-    /// # std::io::Result::Ok(())
-    pub fn with_focus_change(mut self) -> io::Result<Self> {
-        execute!(self.writer, EnableFocusChange)?;
-        self.restore_focus_change_on_drop = true;
-        Ok(self)
-    }
-
-    /// Enables keyboard enhancement flags for the terminal.
-    ///
-    /// Returns an [`io::Result`] containing self so that it can be chained with other methods.
-    ///
-    /// # Example
-    ///
-    /// ```rust,no_run
-    /// use ratatui::{backend::CrosstermBackend, crossterm::event::KeyboardEnhancementFlags};
-    ///
-    /// let backend = CrosstermBackend::stdout()?
-    ///     .with_keyboard_enhancement_flags(KeyboardEnhancementFlags::DISAMBIGUATE_ESCAPE_CODES)?;
-    /// # std::io::Result::Ok(())
-    /// ```
-    pub fn with_keyboard_enhancement_flags(
-        mut self,
-        flags: KeyboardEnhancementFlags,
-    ) -> io::Result<Self> {
-        execute!(self.writer, PushKeyboardEnhancementFlags(flags))?;
-        self.restore_keyboard_enhancement_flags_on_drop = true;
-        Ok(self)
-    }
-
-    /// Restores the terminal to its default state.
-    ///
-    /// This method:
-    ///
-    /// - Disables raw mode
-    /// - Leaves the alternate screen
-    /// - Disables mouse capture
-    /// - Disables bracketed paste
-    /// - Disables focus change
-    /// - Pops keyboard enhancement flags
-    ///
-    /// This method is an associated method rather than an instance method to make it possible to
-    /// call without having a `CrosstermBackend` instance. This is often useful in the context of
-    /// error / panic handling.
-    ///
-    /// If you have created a `CrosstermBackend` using the `with_*` methods, the settings are
-    /// restored when the `CrosstermBackend` is dropped, so you do not need to call this method
-    /// manually.
-    ///
-    /// # Example
-    ///
-    /// ```rust,no_run
-    /// # use ratatui::backend::CrosstermBackend;
-    /// CrosstermBackend::restore(std::io::stderr())?;
-    /// # std::io::Result::Ok(())
-    /// ```
-    pub fn restore(mut writer: W) -> io::Result<()> {
-        disable_raw_mode()?;
-        execute!(
-            writer,
-            LeaveAlternateScreen,
-            DisableMouseCapture,
-            DisableBracketedPaste,
-            DisableFocusChange,
-            PopKeyboardEnhancementFlags
-        )?;
-        writer.flush()
-    }
-}
-
-impl<W: Write> Drop for CrosstermBackend<W> {
-    fn drop(&mut self) {
-        // note that these are not checked for errors because there is nothing that can be done if
-        // they fail. The terminal is likely in a bad state, and the application is exiting anyway.
-        if self.restore_raw_mode_on_drop {
-            let _ = disable_raw_mode();
-        }
-        if self.restore_mouse_capture_on_drop {
-            let _ = execute!(self.writer, DisableMouseCapture);
-        }
-        if self.restore_alternate_screen_on_drop {
-            let _ = execute!(self.writer, LeaveAlternateScreen);
-        }
-        if self.restore_bracketed_paste_on_drop {
-            let _ = execute!(self.writer, DisableBracketedPaste);
-        }
-        if self.restore_focus_change_on_drop {
-            let _ = execute!(self.writer, DisableFocusChange);
-        }
-        if self.restore_keyboard_enhancement_flags_on_drop {
-            let _ = execute!(self.writer, PopKeyboardEnhancementFlags);
-        }
-        let _ = self.writer.flush();
-    }
-}
-
 impl<W> Write for CrosstermBackend<W>
 where
     W: Write,
@@ -482,7 +247,7 @@ where
     }
 
     fn size(&self) -> io::Result<Rect> {
-        let (width, height) = crossterm::terminal::size()?;
+        let (width, height) = terminal::size()?;
         Ok(Rect::new(0, 0, width, height))
     }
 
@@ -492,7 +257,7 @@ where
             rows,
             width,
             height,
-        } = crossterm::terminal::window_size()?;
+        } = terminal::window_size()?;
         Ok(WindowSize {
             columns_rows: Size {
                 width: columns,
@@ -572,6 +337,7 @@ impl ModifierDiff {
     where
         W: io::Write,
     {
+        //use crossterm::Attribute;
         let removed = self.from - self.to;
         if removed.contains(Modifier::REVERSED) {
             queue!(w, SetAttribute(CAttribute::NoReverse))?;

src/backend/termion.rs

@@ -88,7 +88,7 @@ where
     }
 
     /// Gets the writer.
-    #[stability::unstable(
+    #[instability::unstable(
         feature = "backend-writer",
         issue = "https://github.com/ratatui-org/ratatui/pull/991"
     )]
@@ -99,7 +99,7 @@ where
     /// Gets the writer as a mutable reference.
     /// Note: writing to the writer may cause incorrect output after the write. This is due to the
     /// way that the Terminal implements diffing Buffers.
-    #[stability::unstable(
+    #[instability::unstable(
         feature = "backend-writer",
         issue = "https://github.com/ratatui-org/ratatui/pull/991"
     )]

src/layout/constraint.rs

@@ -310,7 +310,7 @@ impl Constraint {
     /// ```rust
     /// # use ratatui::prelude::*;
     /// # let area = Rect::default();
-    /// let constraints = Constraint::from_mins([1, 2, 3]);
+    /// let constraints = Constraint::from_fills([1, 2, 3]);
     /// let layout = Layout::default().constraints(constraints).split(area);
     /// ```
     pub fn from_fills<T>(proportional_factors: T) -> Vec<Self>

src/symbols/border.rs

@@ -25,6 +25,7 @@ impl Default for Set {
 /// │xxxxx│
 /// │xxxxx│
 /// └─────┘
+/// ```
 pub const PLAIN: Set = Set {
     top_left: line::NORMAL.top_left,
     top_right: line::NORMAL.top_right,
@@ -43,6 +44,7 @@ pub const PLAIN: Set = Set {
 /// │xxxxx│
 /// │xxxxx│
 /// ╰─────╯
+/// ```
 pub const ROUNDED: Set = Set {
     top_left: line::ROUNDED.top_left,
     top_right: line::ROUNDED.top_right,
@@ -61,6 +63,7 @@ pub const ROUNDED: Set = Set {
 /// ║xxxxx║
 /// ║xxxxx║
 /// ╚═════╝
+/// ```
 pub const DOUBLE: Set = Set {
     top_left: line::DOUBLE.top_left,
     top_right: line::DOUBLE.top_right,
@@ -79,6 +82,7 @@ pub const DOUBLE: Set = Set {
 /// ┃xxxxx┃
 /// ┃xxxxx┃
 /// ┗━━━━━┛
+/// ```
 pub const THICK: Set = Set {
     top_left: line::THICK.top_left,
     top_right: line::THICK.top_right,
@@ -242,6 +246,7 @@ pub const PROPORTIONAL_TALL: Set = Set {
 /// █xx█
 /// █xx█
 /// ████
+/// ```
 pub const FULL: Set = Set {
     top_left: block::FULL,
     top_right: block::FULL,

src/terminal/frame.rs

@@ -94,7 +94,7 @@ impl Frame<'_> {
     /// # }
     /// ```
     #[allow(clippy::needless_pass_by_value)]
-    #[stability::unstable(feature = "widget-ref")]
+    #[instability::unstable(feature = "widget-ref")]
     pub fn render_widget_ref<W: WidgetRef>(&mut self, widget: W, area: Rect) {
         widget.render_ref(area, self.buffer);
     }
@@ -152,7 +152,7 @@ impl Frame<'_> {
     /// # }
     /// ```
     #[allow(clippy::needless_pass_by_value)]
-    #[stability::unstable(feature = "widget-ref")]
+    #[instability::unstable(feature = "widget-ref")]
     pub fn render_stateful_widget_ref<W>(&mut self, widget: W, area: Rect, state: &mut W::State)
     where
         W: StatefulWidgetRef,

src/terminal/terminal.rs

@@ -234,39 +234,145 @@ where
         Ok(())
     }
 
-    /// Synchronizes terminal size, calls the rendering closure, flushes the current internal state
-    /// and prepares for the next draw call.
+    /// Draws a single frame to the terminal.
     ///
-    /// This is the main entry point for drawing to the terminal.
+    /// Returns a [`CompletedFrame`] if successful, otherwise a [`std::io::Error`].
     ///
-    /// The changes drawn to the frame are applied only to the current [`Buffer`]. After the closure
-    /// returns, the current buffer is compared to the previous buffer and only the changes are
-    /// applied to the terminal.
+    /// If the render callback passed to this method can fail, use [`try_draw`] instead.
+    ///
+    /// Applications should call `draw` or [`try_draw`] in a loop to continuously render the
+    /// terminal. These methods are the main entry points for drawing to the terminal.
+    ///
+    /// [`try_draw`]: Terminal::try_draw
+    ///
+    /// This method will:
+    ///
+    /// - autoresize the terminal if necessary
+    /// - call the render callback, passing it a [`Frame`] reference to render to
+    /// - flush the current internal state by copying the current buffer to the backend
+    /// - move the cursor to the last known position if it was set during the rendering closure
+    /// - return a [`CompletedFrame`] with the current buffer and the area of the terminal
+    ///
+    /// The [`CompletedFrame`] returned by this method can be useful for debugging or testing
+    /// purposes, but it is often not used in regular applicationss.
+    ///
+    /// The render callback should fully render the entire frame when called, including areas that
+    /// are unchanged from the previous frame. This is because each frame is compared to the
+    /// previous frame to determine what has changed, and only the changes are written to the
+    /// terminal. If the render callback does not fully render the frame, the terminal will not be
+    /// in a consistent state.
     ///
     /// # Examples
     ///
-    /// ```rust,no_run
-    /// # use std::io::stdout;
-    /// # use ratatui::{prelude::*, widgets::Paragraph};
-    /// let backend = CrosstermBackend::new(stdout());
-    /// let mut terminal = Terminal::new(backend)?;
+    /// ```
+    /// # let backend = ratatui::backend::TestBackend::new(10, 10);
+    /// # let mut terminal = ratatui::Terminal::new(backend)?;
+    /// use std::io;
+    ///
+    /// use ratatui::widgets::Paragraph;
+    ///
+    /// // with a closure
     /// terminal.draw(|frame| {
     ///     let area = frame.size();
     ///     frame.render_widget(Paragraph::new("Hello World!"), area);
     ///     frame.set_cursor(0, 0);
     /// })?;
-    /// # std::io::Result::Ok(())
+    ///
+    /// // or with a function
+    /// terminal.draw(render)?;
+    ///
+    /// fn render(frame: &mut ratatui::Frame) {
+    ///     frame.render_widget(Paragraph::new("Hello World!"), frame.size());
+    /// }
+    /// # io::Result::Ok(())
     /// ```
-    pub fn draw<F>(&mut self, f: F) -> io::Result<CompletedFrame>
+    pub fn draw<F>(&mut self, render_callback: F) -> io::Result<CompletedFrame>
     where
         F: FnOnce(&mut Frame),
+    {
+        self.try_draw(|frame| {
+            render_callback(frame);
+            io::Result::Ok(())
+        })
+    }
+
+    /// Tries to draw a single frame to the terminal.
+    ///
+    /// Returns [`Result::Ok`] containing a [`CompletedFrame`] if successful, otherwise
+    /// [`Result::Err`] containing the [`std::io::Error`] that caused the failure.
+    ///
+    /// This is the equivalent of [`Terminal::draw`] but the render callback is a function or
+    /// closure that returns a `Result` instead of nothing.
+    ///
+    /// Applications should call `try_draw` or [`draw`] in a loop to continuously render the
+    /// terminal. These methods are the main entry points for drawing to the terminal.
+    ///
+    /// [`draw`]: Terminal::draw
+    ///
+    /// This method will:
+    ///
+    /// - autoresize the terminal if necessary
+    /// - call the render callback, passing it a [`Frame`] reference to render to
+    /// - flush the current internal state by copying the current buffer to the backend
+    /// - move the cursor to the last known position if it was set during the rendering closure
+    /// - return a [`CompletedFrame`] with the current buffer and the area of the terminal
+    ///
+    /// The render callback passed to `try_draw` can return any [`Result`] with an error type that
+    /// can be converted into an [`std::io::Error`] using the [`Into`] trait. This makes it possible
+    /// to use the `?` operator to propagate errors that occur during rendering. If the render
+    /// callback returns an error, the error will be returned from `try_draw` as an
+    /// [`std::io::Error`] and the terminal will not be updated.
+    ///
+    /// The [`CompletedFrame`] returned by this method can be useful for debugging or testing
+    /// purposes, but it is often not used in regular applicationss.
+    ///
+    /// The render callback should fully render the entire frame when called, including areas that
+    /// are unchanged from the previous frame. This is because each frame is compared to the
+    /// previous frame to determine what has changed, and only the changes are written to the
+    /// terminal. If the render function does not fully render the frame, the terminal will not be
+    /// in a consistent state.
+    ///
+    /// # Examples
+    ///
+    /// ```should_panic
+    /// # let backend = ratatui::backend::TestBackend::new(10, 10);
+    /// # let mut terminal = ratatui::Terminal::new(backend)?;
+    /// use std::io;
+    ///
+    /// use ratatui::widgets::Paragraph;
+    ///
+    /// // with a closure
+    /// terminal.try_draw(|frame| {
+    ///     let value: u8 = "not a number".parse().map_err(io::Error::other)?;
+    ///     let area = frame.size();
+    ///     frame.render_widget(Paragraph::new("Hello World!"), area);
+    ///     frame.set_cursor(0, 0);
+    ///     io::Result::Ok(())
+    /// })?;
+    ///
+    /// // or with a function
+    /// terminal.try_draw(render)?;
+    ///
+    /// fn render(frame: &mut ratatui::Frame) -> io::Result<()> {
+    ///     let value: u8 = "not a number".parse().map_err(io::Error::other)?;
+    ///     frame.render_widget(Paragraph::new("Hello World!"), frame.size());
+    ///     Ok(())
+    /// }
+    /// # io::Result::Ok(())
+    /// ```
+    pub fn try_draw<F, E>(&mut self, render_callback: F) -> io::Result<CompletedFrame>
+    where
+        F: FnOnce(&mut Frame) -> Result<(), E>,
+        E: Into<io::Error>,
     {
         // Autoresize - otherwise we get glitches if shrinking or potential desync between widgets
         // and the terminal (if growing), which may OOB.
         self.autoresize()?;
 
         let mut frame = self.get_frame();
-        f(&mut frame);
+
+        render_callback(&mut frame).map_err(Into::into)?;
+
         // We can't change the cursor position right away because we have to flush the frame to
         // stdout first. But we also can't keep the frame around, since it holds a &mut to
         // Buffer. Thus, we're taking the important data out of the Frame and dropping it.

src/text.rs

@@ -48,14 +48,14 @@ mod grapheme;
 pub use grapheme::StyledGrapheme;
 
 mod line;
-pub use line::Line;
+pub use line::{Line, ToLine};
 
 mod masked;
 pub use masked::Masked;
 
 mod span;
-pub use span::Span;
+pub use span::{Span, ToSpan};
 
 #[allow(clippy::module_inception)]
 mod text;
-pub use text::Text;
+pub use text::{Text, ToText};

src/text/grapheme.rs

@@ -1,5 +1,8 @@
 use crate::{prelude::*, style::Styled};
 
+const NBSP: &str = "\u{00a0}";
+const ZWSP: &str = "\u{200b}";
+
 /// A grapheme associated to a style.
 /// Note that, although `StyledGrapheme` is the smallest divisible unit of text,
 /// it actually is not a member of the text type hierarchy (`Text` -> `Line` -> `Span`).
@@ -22,6 +25,11 @@ impl<'a> StyledGrapheme<'a> {
             style: style.into(),
         }
     }
+
+    pub(crate) fn is_whitespace(&self) -> bool {
+        let symbol = self.symbol;
+        symbol == ZWSP || symbol.chars().all(char::is_whitespace) && symbol != NBSP
+    }
 }
 
 impl<'a> Styled for StyledGrapheme<'a> {

src/text/line.rs

@@ -649,6 +649,29 @@ fn spans_after_width<'a>(
         })
 }
 
+/// A trait for converting a value to a [`Line`].
+///
+/// This trait is automatically implemented for any type that implements the [`Display`] trait. As
+/// such, `ToLine` shouln't be implemented directly: [`Display`] should be implemented instead, and
+/// you get the `ToLine` implementation for free.
+///
+/// [`Display`]: std::fmt::Display
+pub trait ToLine {
+    /// Converts the value to a [`Line`].
+    fn to_line(&self) -> Line<'_>;
+}
+
+/// # Panics
+///
+/// In this implementation, the `to_line` method panics if the `Display` implementation returns an
+/// error. This indicates an incorrect `Display` implementation since `fmt::Write for String` never
+/// returns an error itself.
+impl<T: fmt::Display> ToLine for T {
+    fn to_line(&self) -> Line<'_> {
+        Line::from(self.to_string())
+    }
+}
+
 impl fmt::Display for Line<'_> {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         for span in &self.spans {
@@ -824,6 +847,12 @@ mod tests {
         assert_eq!(line.spans, vec![Span::from("Hello"), Span::from("world!")]);
     }
 
+    #[test]
+    fn to_line() {
+        let line = 42.to_line();
+        assert_eq!(vec![Span::from("42")], line.spans);
+    }
+
     #[test]
     fn from_vec() {
         let spans = vec![

src/text/span.rs

@@ -406,6 +406,29 @@ impl WidgetRef for Span<'_> {
     }
 }
 
+/// A trait for converting a value to a [`Span`].
+///
+/// This trait is automatically implemented for any type that implements the [`Display`] trait. As
+/// such, `ToSpan` shouln't be implemented directly: [`Display`] should be implemented instead, and
+/// you get the `ToSpan` implementation for free.
+///
+/// [`Display`]: std::fmt::Display
+pub trait ToSpan {
+    /// Converts the value to a [`Span`].
+    fn to_span(&self) -> Span<'_>;
+}
+
+/// # Panics
+///
+/// In this implementation, the `to_span` method panics if the `Display` implementation returns an
+/// error. This indicates an incorrect `Display` implementation since `fmt::Write for String` never
+/// returns an error itself.
+impl<T: fmt::Display> ToSpan for T {
+    fn to_span(&self) -> Span<'_> {
+        Span::raw(self.to_string())
+    }
+}
+
 impl fmt::Display for Span<'_> {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         fmt::Display::fmt(&self.content, f)
@@ -507,6 +530,12 @@ mod tests {
         assert_eq!(span.style, Style::default());
     }
 
+    #[test]
+    fn to_span() {
+        assert_eq!(42.to_span(), Span::raw("42"));
+        assert_eq!("test".to_span(), Span::raw("test"));
+    }
+
     #[test]
     fn reset_style() {
         let span = Span::styled("test content", Style::new().green()).reset_style();

src/text/text.rs

@@ -580,6 +580,29 @@ where
     }
 }
 
+/// A trait for converting a value to a [`Text`].
+///
+/// This trait is automatically implemented for any type that implements the [`Display`] trait. As
+/// such, `ToText` shouldn't be implemented directly: [`Display`] should be implemented instead, and
+/// you get the `ToText` implementation for free.
+///
+/// [`Display`]: std::fmt::Display
+pub trait ToText<'a> {
+    /// Converts the value to a [`Text`].
+    fn to_text(&self) -> Text<'a>;
+}
+
+/// # Panics
+///
+/// In this implementation, the `to_text` method panics if the `Display` implementation returns an
+/// error. This indicates an incorrect `Display` implementation since `fmt::Write for String` never
+/// returns an error itself.
+impl<'a, T: fmt::Display> ToText<'a> for T {
+    fn to_text(&self) -> Text<'a> {
+        Text::raw(self.to_string())
+    }
+}
+
 impl fmt::Display for Text<'_> {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         for (position, line) in self.iter().with_position() {
@@ -747,6 +770,24 @@ mod tests {
         assert_eq!(text.lines, vec![Line::from("The first line")]);
     }
 
+    #[rstest]
+    #[case(42, Text::from("42"))]
+    #[case("just\ntesting", Text::from("just\ntesting"))]
+    #[case(true, Text::from("true"))]
+    #[case(6.66, Text::from("6.66"))]
+    #[case('a', Text::from("a"))]
+    #[case(String::from("hello"), Text::from("hello"))]
+    #[case(-1, Text::from("-1"))]
+    #[case("line1\nline2", Text::from("line1\nline2"))]
+    #[case(
+        "first line\nsecond line\nthird line",
+        Text::from("first line\nsecond line\nthird line")
+    )]
+    #[case("trailing newline\n", Text::from("trailing newline\n"))]
+    fn to_text(#[case] value: impl fmt::Display, #[case] expected: Text) {
+        assert_eq!(value.to_text(), expected);
+    }
+
     #[test]
     fn from_vec_line() {
         let text = Text::from(vec![

src/widgets.rs

@@ -297,7 +297,7 @@ pub trait StatefulWidget {
 /// # }
 /// # }
 /// ```
-#[stability::unstable(feature = "widget-ref")]
+#[instability::unstable(feature = "widget-ref")]
 pub trait WidgetRef {
     /// Draws the current state of the widget in the given buffer. That is the only method required
     /// to implement a custom widget.
@@ -398,7 +398,7 @@ impl<W: WidgetRef> WidgetRef for Option<W> {
 /// }
 /// # }
 /// ```
-#[stability::unstable(feature = "widget-ref")]
+#[instability::unstable(feature = "widget-ref")]
 pub trait StatefulWidgetRef {
     /// State associated with the stateful widget.
     ///

src/widgets/block.rs

@@ -35,6 +35,30 @@ pub use title::{Position, Title};
 ///
 /// Without left border───
 /// ```
+/// # Constructor methods
+///
+/// - [`Block::new`] creates a new [`Block`] with no border or paddings.
+/// - [`Block::bordered`] Create a new block with all borders shown.
+///
+/// # Setter methods
+///
+/// These methods are fluent setters. They return a new [`Block`] with the specified property set.
+///
+/// - [`Block::borders`] Defines which borders to display.
+/// - [`Block::border_style`] Defines the style of the borders.
+/// - [`Block::border_type`] Sets the symbols used to display the border (e.g. single line, double
+///   line, thick or rounded borders).
+/// - [`Block::padding`] Defines the padding inside a [`Block`].
+/// - [`Block::style`] Sets the base style of the widget.
+/// - [`Block::title`] Adds a title to the block.
+/// - [`Block::title_alignment`] Sets the default [`Alignment`] for all block titles.
+/// - [`Block::title_style`] Applies the style to all titles.
+/// - [`Block::title_top`] Adds a title to the top of the block.
+/// - [`Block::title_bottom`] Adds a title to the bottom of the block.
+/// - [`Block::title_position`] Adds a title to the block.
+///
+/// # Other Methods
+/// - [`Block::inner`] Compute the inner area of a block based on its border visibility rules.
 ///
 /// # Examples
 ///
@@ -63,6 +87,20 @@ pub use title::{Position, Title};
 ///     .title("Title 1")
 ///     .title(Title::from("Title 2").position(Position::Bottom));
 /// ```
+///
+/// You can also pass it as parameters of another widget so that the block surrounds them:
+/// ```
+/// use ratatui::{
+///     prelude::*,
+///     widgets::{Block, Borders, List},
+/// };
+///
+/// let surrounding_block = Block::default()
+///     .borders(Borders::ALL)
+///     .title("Here is a list of items");
+/// let items = ["Item 1", "Item 2", "Item 3"];
+/// let list = List::new(items).block(surrounding_block);
+/// ```
 #[derive(Debug, Default, Clone, Eq, PartialEq, Hash)]
 pub struct Block<'a> {
     /// List of titles

src/widgets/list.rs

@@ -157,6 +157,72 @@ impl ListState {
             self.offset = 0;
         }
     }
+
+    /// Selects the next item or the first one if no item is selected
+    ///
+    /// Note: until the list is rendered, the number of items is not known, so the index is set to
+    /// `0` and will be corrected when the list is rendered
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// # use ratatui::{prelude::*, widgets::*};
+    /// let mut state = ListState::default();
+    /// state.select_next();
+    /// ```
+    pub fn select_next(&mut self) {
+        let next = self.selected.map_or(0, |i| i.saturating_add(1));
+        self.select(Some(next));
+    }
+
+    /// Selects the previous item or the last one if no item is selected
+    ///
+    /// Note: until the list is rendered, the number of items is not known, so the index is set to
+    /// `usize::MAX` and will be corrected when the list is rendered
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// # use ratatui::{prelude::*, widgets::*};
+    /// let mut state = ListState::default();
+    /// state.select_previous();
+    /// ```
+    pub fn select_previous(&mut self) {
+        let previous = self.selected.map_or(usize::MAX, |i| i.saturating_sub(1));
+        self.select(Some(previous));
+    }
+
+    /// Selects the first item
+    ///
+    /// Note: until the list is rendered, the number of items is not known, so the index is set to
+    /// `0` and will be corrected when the list is rendered
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// # use ratatui::{prelude::*, widgets::*};
+    /// let mut state = ListState::default();
+    /// state.select_first();
+    /// ```
+    pub fn select_first(&mut self) {
+        self.select(Some(0));
+    }
+
+    /// Selects the last item
+    ///
+    /// Note: until the list is rendered, the number of items is not known, so the index is set to
+    /// `usize::MAX` and will be corrected when the list is rendered
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// # use ratatui::{prelude::*, widgets::*};
+    /// let mut state = ListState::default();
+    /// state.select_last();
+    /// ```
+    pub fn select_last(&mut self) {
+        self.select(Some(usize::MAX));
+    }
 }
 
 /// A single item in a [`List`]
@@ -882,10 +948,20 @@ impl StatefulWidgetRef for List<'_> {
         self.block.render_ref(area, buf);
         let list_area = self.block.inner_if_some(area);
 
-        if list_area.is_empty() || self.items.is_empty() {
+        if list_area.is_empty() {
             return;
         }
 
+        if self.items.is_empty() {
+            state.select(None);
+            return;
+        }
+
+        // If the selected index is out of bounds, set it to the last item
+        if state.selected.is_some_and(|s| s >= self.items.len()) {
+            state.select(Some(self.items.len().saturating_sub(1)));
+        }
+
         let list_height = list_area.height as usize;
 
         let (first_visible_index, last_visible_index) =
@@ -1009,6 +1085,11 @@ mod tests {
 
     use super::*;
 
+    #[fixture]
+    fn single_line_buf() -> Buffer {
+        Buffer::empty(Rect::new(0, 0, 10, 1))
+    }
+
     #[test]
     fn test_list_state_selected() {
         let mut state = ListState::default();
@@ -1036,6 +1117,96 @@ mod tests {
         assert_eq!(state.offset, 0);
     }
 
+    #[test]
+    fn test_list_state_navigation() {
+        let mut state = ListState::default();
+        state.select_first();
+        assert_eq!(state.selected, Some(0));
+
+        state.select_previous(); // should not go below 0
+        assert_eq!(state.selected, Some(0));
+
+        state.select_next();
+        assert_eq!(state.selected, Some(1));
+
+        state.select_previous();
+        assert_eq!(state.selected, Some(0));
+
+        state.select_last();
+        assert_eq!(state.selected, Some(usize::MAX));
+
+        state.select_next(); // should not go above usize::MAX
+        assert_eq!(state.selected, Some(usize::MAX));
+
+        state.select_previous();
+        assert_eq!(state.selected, Some(usize::MAX - 1));
+
+        state.select_next();
+        assert_eq!(state.selected, Some(usize::MAX));
+
+        let mut state = ListState::default();
+        state.select_next();
+        assert_eq!(state.selected, Some(0));
+
+        let mut state = ListState::default();
+        state.select_previous();
+        assert_eq!(state.selected, Some(usize::MAX));
+    }
+
+    #[rstest]
+    fn test_list_state_empty_list(mut single_line_buf: Buffer) {
+        let mut state = ListState::default();
+
+        let items: Vec<ListItem> = Vec::new();
+        let list = List::new(items);
+        state.select_first();
+        StatefulWidget::render(list, single_line_buf.area, &mut single_line_buf, &mut state);
+        assert_eq!(state.selected, None);
+    }
+
+    #[rstest]
+    fn test_list_state_single_item(mut single_line_buf: Buffer) {
+        let mut state = ListState::default();
+
+        let items = vec![ListItem::new("Item 1")];
+        let list = List::new(items);
+        state.select_first();
+        StatefulWidget::render(
+            &list,
+            single_line_buf.area,
+            &mut single_line_buf,
+            &mut state,
+        );
+        assert_eq!(state.selected, Some(0));
+
+        state.select_last();
+        StatefulWidget::render(
+            &list,
+            single_line_buf.area,
+            &mut single_line_buf,
+            &mut state,
+        );
+        assert_eq!(state.selected, Some(0));
+
+        state.select_previous();
+        StatefulWidget::render(
+            &list,
+            single_line_buf.area,
+            &mut single_line_buf,
+            &mut state,
+        );
+        assert_eq!(state.selected, Some(0));
+
+        state.select_next();
+        StatefulWidget::render(
+            &list,
+            single_line_buf.area,
+            &mut single_line_buf,
+            &mut state,
+        );
+        assert_eq!(state.selected, Some(0));
+    }
+
     #[test]
     fn test_list_item_new_from_str() {
         let item = ListItem::new("Test item");
@@ -1302,7 +1473,7 @@ mod tests {
             &single_item,
             Some(1),
             [
-                "  Item 0  ",
+                ">>Item 0  ",
                 "          ",
                 "          ",
                 "          ",
@@ -1360,7 +1531,7 @@ mod tests {
             [
                 "  Item 0  ",
                 "  Item 1  ",
-                "  Item 2  ",
+                ">>Item 2  ",
                 "          ",
                 "          ",
             ],
@@ -2099,11 +2270,6 @@ mod tests {
         ]);
     }
 
-    #[fixture]
-    fn single_line_buf() -> Buffer {
-        Buffer::empty(Rect::new(0, 0, 10, 1))
-    }
-
     /// Regression test for a bug where highlight symbol being greater than width caused a panic due
     /// to subtraction with underflow.
     ///

src/widgets/paragraph.rs

@@ -270,7 +270,7 @@ impl<'a> Paragraph<'a> {
     /// assert_eq!(paragraph.line_count(20), 1);
     /// assert_eq!(paragraph.line_count(10), 2);
     /// ```
-    #[stability::unstable(
+    #[instability::unstable(
         feature = "rendered-line-info",
         issue = "https://github.com/ratatui-org/ratatui/issues/293"
     )]
@@ -313,7 +313,7 @@ impl<'a> Paragraph<'a> {
     /// let paragraph = Paragraph::new("Hello World\nhi\nHello World!!!");
     /// assert_eq!(paragraph.line_width(), 14);
     /// ```
-    #[stability::unstable(
+    #[instability::unstable(
         feature = "rendered-line-info",
         issue = "https://github.com/ratatui-org/ratatui/issues/293"
     )]

src/widgets/reflow.rs

@@ -5,9 +5,6 @@ use unicode_width::UnicodeWidthStr;
 
 use crate::{layout::Alignment, text::StyledGrapheme};
 
-const NBSP: &str = "\u{00a0}";
-const ZWSP: &str = "\u{200b}";
-
 /// A state machine to pack styled symbols into lines.
 /// Cannot implement it as Iterator since it yields slices of the internal buffer (need streaming
 /// iterators for that).
@@ -59,6 +56,124 @@ where
             trim,
         }
     }
+
+    fn next_cached_line(&mut self) -> Option<Vec<StyledGrapheme<'a>>> {
+        self.wrapped_lines.as_mut()?.next()
+    }
+
+    /// Split an input line (`line_symbols`) into wrapped lines
+    /// and cache them to be emitted later
+    fn process_input(&mut self, line_symbols: impl IntoIterator<Item = StyledGrapheme<'a>>) {
+        let mut result_lines = vec![];
+        let mut pending_line = vec![];
+        let mut line_width = 0;
+        let mut pending_word = vec![];
+        let mut word_width = 0;
+        let mut pending_whitespace: VecDeque<StyledGrapheme> = VecDeque::new();
+        let mut whitespace_width = 0;
+        let mut non_whitespace_previous = false;
+
+        for grapheme in line_symbols {
+            let is_whitespace = grapheme.is_whitespace();
+            let symbol_width = grapheme.symbol.width() as u16;
+
+            // ignore symbols wider than line limit
+            if symbol_width > self.max_line_width {
+                continue;
+            }
+
+            let word_found = non_whitespace_previous && is_whitespace;
+            // current word would overflow after removing whitespace
+            let trimmed_overflow = pending_line.is_empty()
+                && self.trim
+                && word_width + symbol_width > self.max_line_width;
+            // separated whitespace would overflow on its own
+            let whitespace_overflow = pending_line.is_empty()
+                && self.trim
+                && whitespace_width + symbol_width > self.max_line_width;
+            // current full word (including whitespace) would overflow
+            let untrimmed_overflow = pending_line.is_empty()
+                && !self.trim
+                && word_width + whitespace_width + symbol_width > self.max_line_width;
+
+            // append finished segment to current line
+            if word_found || trimmed_overflow || whitespace_overflow || untrimmed_overflow {
+                if !pending_line.is_empty() || !self.trim {
+                    pending_line.extend(pending_whitespace.drain(..));
+                    line_width += whitespace_width;
+                }
+
+                pending_line.append(&mut pending_word);
+                line_width += word_width;
+
+                pending_whitespace.clear();
+                whitespace_width = 0;
+                word_width = 0;
+            }
+
+            // pending line fills up limit
+            let line_full = line_width >= self.max_line_width;
+            // pending word would overflow line limit
+            let pending_word_overflow = symbol_width > 0
+                && line_width + whitespace_width + word_width >= self.max_line_width;
+
+            // add finished wrapped line to remaining lines
+            if line_full || pending_word_overflow {
+                let mut remaining_width = u16::saturating_sub(self.max_line_width, line_width);
+
+                result_lines.push(std::mem::take(&mut pending_line));
+                line_width = 0;
+
+                // remove whitespace up to the end of line
+                while let Some(grapheme) = pending_whitespace.front() {
+                    let width = grapheme.symbol.width() as u16;
+
+                    if width > remaining_width {
+                        break;
+                    }
+
+                    whitespace_width -= width;
+                    remaining_width -= width;
+                    pending_whitespace.pop_front();
+                }
+
+                // don't count first whitespace toward next word
+                if is_whitespace && pending_whitespace.is_empty() {
+                    continue;
+                }
+            }
+
+            // append symbol to a pending buffer
+            if is_whitespace {
+                whitespace_width += symbol_width;
+                pending_whitespace.push_back(grapheme);
+            } else {
+                word_width += symbol_width;
+                pending_word.push(grapheme);
+            }
+
+            non_whitespace_previous = !is_whitespace;
+        }
+
+        // append remaining text parts
+        if pending_line.is_empty() && pending_word.is_empty() && !pending_whitespace.is_empty() {
+            result_lines.push(vec![]);
+        }
+        if !pending_line.is_empty() || !self.trim {
+            pending_line.extend(pending_whitespace);
+        }
+        pending_line.extend(pending_word);
+
+        if !pending_line.is_empty() {
+            result_lines.push(pending_line);
+        }
+        if result_lines.is_empty() {
+            result_lines.push(vec![]);
+        }
+
+        // save processed lines for emitting later
+        self.wrapped_lines = Some(result_lines.into_iter());
+    }
 }
 
 impl<'a, O, I> LineComposer<'a> for WordWrapper<'a, O, I>
@@ -72,155 +187,26 @@ where
             return None;
         }
 
-        let mut current_line: Option<Vec<StyledGrapheme<'a>>> = None;
-        let mut line_width: u16 = 0;
+        loop {
+            // emit next cached line if present
+            if let Some(line) = self.next_cached_line() {
+                let line_width = line
+                    .iter()
+                    .map(|grapheme| grapheme.symbol.width() as u16)
+                    .sum();
 
-        // Try to repeatedly retrieve next line
-        while current_line.is_none() {
-            // Retrieve next preprocessed wrapped line
-            if let Some(line_iterator) = &mut self.wrapped_lines {
-                if let Some(line) = line_iterator.next() {
-                    line_width = line
-                        .iter()
-                        .map(|grapheme| grapheme.symbol.width())
-                        .sum::<usize>() as u16;
-                    current_line = Some(line);
-                }
+                self.current_line = line;
+                return Some(WrappedLine {
+                    line: &self.current_line,
+                    width: line_width,
+                    alignment: self.current_alignment,
+                });
             }
 
-            // When no more preprocessed wrapped lines
-            if current_line.is_none() {
-                // Try to calculate next wrapped lines based on current whole line
-                if let Some((line_symbols, line_alignment)) = &mut self.input_lines.next() {
-                    // Save the whole line's alignment
-                    self.current_alignment = *line_alignment;
-                    let mut wrapped_lines = vec![]; // Saves the wrapped lines
-                                                    // Saves the unfinished wrapped line
-                    let (mut current_line, mut current_line_width) = (vec![], 0);
-                    // Saves the partially processed word
-                    let (mut unfinished_word, mut word_width) = (vec![], 0);
-                    // Saves the whitespaces of the partially unfinished word
-                    let (mut unfinished_whitespaces, mut whitespace_width) =
-                        (VecDeque::<StyledGrapheme>::new(), 0);
-
-                    let mut has_seen_non_whitespace = false;
-                    for StyledGrapheme { symbol, style } in line_symbols {
-                        let symbol_whitespace = symbol == ZWSP
-                            || (symbol.chars().all(&char::is_whitespace) && symbol != NBSP);
-                        let symbol_width = symbol.width() as u16;
-                        // Ignore characters wider than the total max width
-                        if symbol_width > self.max_line_width {
-                            continue;
-                        }
-
-                        // Append finished word to current line
-                        if has_seen_non_whitespace && symbol_whitespace
-                            // Append if trimmed (whitespaces removed) word would overflow
-                            || word_width + symbol_width > self.max_line_width && current_line.is_empty() && self.trim
-                            // Append if removed whitespace would overflow -> reset whitespace counting to prevent overflow
-                            || whitespace_width + symbol_width > self.max_line_width && current_line.is_empty() && self.trim
-                            // Append if complete word would overflow
-                            || word_width + whitespace_width + symbol_width > self.max_line_width && current_line.is_empty() && !self.trim
-                        {
-                            if !current_line.is_empty() || !self.trim {
-                                // Also append whitespaces if not trimming or current line is not
-                                // empty
-                                current_line.extend(
-                                    std::mem::take(&mut unfinished_whitespaces).into_iter(),
-                                );
-                                current_line_width += whitespace_width;
-                            }
-                            // Append trimmed word
-                            current_line.append(&mut unfinished_word);
-                            current_line_width += word_width;
-
-                            // Clear whitespace buffer
-                            unfinished_whitespaces.clear();
-                            whitespace_width = 0;
-                            word_width = 0;
-                        }
-
-                        // Append the unfinished wrapped line to wrapped lines if it is as wide as
-                        // max line width
-                        if current_line_width >= self.max_line_width
-                            // or if it would be too long with the current partially processed word added
-                            || current_line_width + whitespace_width + word_width >= self.max_line_width && symbol_width > 0
-                        {
-                            let mut remaining_width = (i32::from(self.max_line_width)
-                                - i32::from(current_line_width))
-                            .max(0) as u16;
-                            wrapped_lines.push(std::mem::take(&mut current_line));
-                            current_line_width = 0;
-
-                            // Remove all whitespaces till end of just appended wrapped line + next
-                            // whitespace
-                            let mut first_whitespace = unfinished_whitespaces.pop_front();
-                            while let Some(grapheme) = first_whitespace.as_ref() {
-                                let symbol_width = grapheme.symbol.width() as u16;
-                                whitespace_width -= symbol_width;
-
-                                if symbol_width > remaining_width {
-                                    break;
-                                }
-                                remaining_width -= symbol_width;
-                                first_whitespace = unfinished_whitespaces.pop_front();
-                            }
-                            // In case all whitespaces have been exhausted
-                            if symbol_whitespace && first_whitespace.is_none() {
-                                // Prevent first whitespace to count towards next word
-                                continue;
-                            }
-                        }
-
-                        // Append symbol to unfinished, partially processed word
-                        if symbol_whitespace {
-                            whitespace_width += symbol_width;
-                            unfinished_whitespaces.push_back(StyledGrapheme { symbol, style });
-                        } else {
-                            word_width += symbol_width;
-                            unfinished_word.push(StyledGrapheme { symbol, style });
-                        }
-
-                        has_seen_non_whitespace = !symbol_whitespace;
-                    }
-
-                    // Append remaining text parts
-                    if !unfinished_word.is_empty() || !unfinished_whitespaces.is_empty() {
-                        if current_line.is_empty() && unfinished_word.is_empty() {
-                            wrapped_lines.push(vec![]);
-                        } else if !self.trim || !current_line.is_empty() {
-                            current_line.extend(unfinished_whitespaces.into_iter());
-                        } else {
-                            // TODO: explain why this else branch is ok.
-                            // See clippy::else_if_without_else
-                        }
-                        current_line.append(&mut unfinished_word);
-                    }
-                    if !current_line.is_empty() {
-                        wrapped_lines.push(current_line);
-                    }
-                    if wrapped_lines.is_empty() {
-                        // Append empty line if there was nothing to wrap in the first place
-                        wrapped_lines.push(vec![]);
-                    }
-
-                    self.wrapped_lines = Some(wrapped_lines.into_iter());
-                } else {
-                    // No more whole lines available -> stop repeatedly retrieving next wrapped line
-                    break;
-                }
-            }
-        }
-
-        if let Some(line) = current_line {
-            self.current_line = line;
-            Some(WrappedLine {
-                line: &self.current_line,
-                width: line_width,
-                alignment: self.current_alignment,
-            })
-        } else {
-            None
+            // otherwise, process pending wrapped lines from input
+            let (line_symbols, line_alignment) = self.input_lines.next()?;
+            self.current_alignment = line_alignment;
+            self.process_input(line_symbols);
         }
     }
 }

src/widgets/table/table.rs

@@ -613,6 +613,14 @@ impl StatefulWidgetRef for Table<'_> {
             return;
         }
 
+        if state.selected.is_some_and(|s| s >= self.rows.len()) {
+            state.select(Some(self.rows.len().saturating_sub(1)));
+        }
+
+        if self.rows.is_empty() {
+            state.select(None);
+        }
+
         let selection_width = self.selection_width(state);
         let columns_widths = self.get_columns_widths(table_area.width, selection_width);
         let (header_area, rows_area, footer_area) = self.layout(table_area);
@@ -1016,6 +1024,60 @@ mod tests {
         assert_eq!(table.widths, vec![Constraint::Percentage(100)], "vec ref");
     }
 
+    #[cfg(test)]
+    mod state {
+        use rstest::{fixture, rstest};
+
+        use super::TableState;
+        use crate::{
+            buffer::Buffer,
+            layout::{Constraint, Rect},
+            widgets::{Row, StatefulWidget, Table},
+        };
+
+        #[fixture]
+        fn table_buf() -> Buffer {
+            Buffer::empty(Rect::new(0, 0, 10, 10))
+        }
+
+        #[rstest]
+        fn test_list_state_empty_list(mut table_buf: Buffer) {
+            let mut state = TableState::default();
+
+            let rows: Vec<Row> = Vec::new();
+            let widths = vec![Constraint::Percentage(100)];
+            let table = Table::new(rows, widths);
+            state.select_first();
+            StatefulWidget::render(table, table_buf.area, &mut table_buf, &mut state);
+            assert_eq!(state.selected, None);
+        }
+
+        #[rstest]
+        fn test_list_state_single_item(mut table_buf: Buffer) {
+            let mut state = TableState::default();
+
+            let widths = vec![Constraint::Percentage(100)];
+
+            let items = vec![Row::new(vec!["Item 1"])];
+            let table = Table::new(items, widths);
+            state.select_first();
+            StatefulWidget::render(&table, table_buf.area, &mut table_buf, &mut state);
+            assert_eq!(state.selected, Some(0));
+
+            state.select_last();
+            StatefulWidget::render(&table, table_buf.area, &mut table_buf, &mut state);
+            assert_eq!(state.selected, Some(0));
+
+            state.select_previous();
+            StatefulWidget::render(&table, table_buf.area, &mut table_buf, &mut state);
+            assert_eq!(state.selected, Some(0));
+
+            state.select_next();
+            StatefulWidget::render(&table, table_buf.area, &mut table_buf, &mut state);
+            assert_eq!(state.selected, Some(0));
+        }
+    }
+
     #[cfg(test)]
     mod render {
         use rstest::rstest;

src/widgets/table/table_state.rs

@@ -175,6 +175,72 @@ impl TableState {
             self.offset = 0;
         }
     }
+
+    /// Selects the next item or the first one if no item is selected
+    ///
+    /// Note: until the table is rendered, the number of items is not known, so the index is set to
+    /// `0` and will be corrected when the table is rendered
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// # use ratatui::{prelude::*, widgets::*};
+    /// let mut state = TableState::default();
+    /// state.select_next();
+    /// ```
+    pub fn select_next(&mut self) {
+        let next = self.selected.map_or(0, |i| i.saturating_add(1));
+        self.select(Some(next));
+    }
+
+    /// Selects the previous item or the last one if no item is selected
+    ///
+    /// Note: until the table is rendered, the number of items is not known, so the index is set to
+    /// `usize::MAX` and will be corrected when the table is rendered
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// # use ratatui::{prelude::*, widgets::*};
+    /// let mut state = TableState::default();
+    /// state.select_previous();
+    /// ```
+    pub fn select_previous(&mut self) {
+        let previous = self.selected.map_or(usize::MAX, |i| i.saturating_sub(1));
+        self.select(Some(previous));
+    }
+
+    /// Selects the first item
+    ///
+    /// Note: until the table is rendered, the number of items is not known, so the index is set to
+    /// `0` and will be corrected when the table is rendered
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// # use ratatui::{prelude::*, widgets::*};
+    /// let mut state = TableState::default();
+    /// state.select_first();
+    /// ```
+    pub fn select_first(&mut self) {
+        self.select(Some(0));
+    }
+
+    /// Selects the last item
+    ///
+    /// Note: until the table is rendered, the number of items is not known, so the index is set to
+    /// `usize::MAX` and will be corrected when the table is rendered
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// # use ratatui::{prelude::*, widgets::*};
+    /// let mut state = TableState::default();
+    /// state.select_last();
+    /// ```
+    pub fn select_last(&mut self) {
+        self.select(Some(usize::MAX));
+    }
 }
 
 #[cfg(test)]
@@ -239,4 +305,40 @@ mod tests {
         state.select(None);
         assert_eq!(state.selected, None);
     }
+
+    #[test]
+    fn test_table_state_navigation() {
+        let mut state = TableState::default();
+        state.select_first();
+        assert_eq!(state.selected, Some(0));
+
+        state.select_previous(); // should not go below 0
+        assert_eq!(state.selected, Some(0));
+
+        state.select_next();
+        assert_eq!(state.selected, Some(1));
+
+        state.select_previous();
+        assert_eq!(state.selected, Some(0));
+
+        state.select_last();
+        assert_eq!(state.selected, Some(usize::MAX));
+
+        state.select_next(); // should not go above usize::MAX
+        assert_eq!(state.selected, Some(usize::MAX));
+
+        state.select_previous();
+        assert_eq!(state.selected, Some(usize::MAX - 1));
+
+        state.select_next();
+        assert_eq!(state.selected, Some(usize::MAX));
+
+        let mut state = TableState::default();
+        state.select_next();
+        assert_eq!(state.selected, Some(0));
+
+        let mut state = TableState::default();
+        state.select_previous();
+        assert_eq!(state.selected, Some(usize::MAX));
+    }
 }

tests/widgets_list.rs

@@ -186,7 +186,7 @@ fn widgets_list_should_clamp_offset_if_items_are_removed() {
         })
         .unwrap();
     terminal.backend().assert_buffer_lines([
-        "   Item 3 ",
+        ">> Item 3 ",
         "          ",
         "          ",
         "          ",