refactor!: remove items deprecated since 0.10 (#691)

Remove `Axis::title_style` and `Buffer::set_background` which are deprecated since 0.10

.github/CODEOWNERS

@@ -5,4 +5,4 @@
 # https://git-scm.com/docs/gitignore#_pattern_format
 
 # Maintainers
-* @orhun @mindoodoo @sayanarijit @sophacles @joshka @kdheepak
+* @orhun @mindoodoo @sayanarijit @joshka @kdheepak @Valentin271

.github/dependabot.yml

@@ -0,0 +1,18 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+
+version: 2
+updates:
+  # Maintain dependencies for Cargo
+  - package-ecosystem: "cargo"
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "weekly"
+  # Maintain dependencies for GitHub Actions
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 10

.github/workflows/cd.yml

@@ -23,7 +23,7 @@ jobs:
     if: ${{ !startsWith(github.event.ref, 'refs/tags/v') }}
     steps:
       - name: Checkout the repository
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with:
           fetch-depth: 0
 
@@ -77,7 +77,7 @@ jobs:
     if: ${{ startsWith(github.event.ref, 'refs/tags/v') }}
     steps:
       - name: Checkout the repository
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Publish on crates.io
         uses: actions-rs/cargo@v1

.github/workflows/check-pr.yml

@@ -46,20 +46,24 @@ jobs:
 
   check-breaking-change-label:
     runs-on: ubuntu-latest
+    env:
+      # use an environment variable to pass untrusted input to the script
+      # see https://securitylab.github.com/research/github-actions-untrusted-input/
+      PR_TITLE: ${{ github.event.pull_request.title }}
     steps:
     - name: Check breaking change label
       id: check_breaking_change
       run: |
         pattern='^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(\(\w+\))?!:'
         # Check if pattern matches
-        if echo "${{ github.event.pull_request.title }}" | grep -qE "$pattern"; then
+        if echo "${PR_TITLE}" | grep -qE "$pattern"; then
           echo "breaking_change=true" >> $GITHUB_OUTPUT
         else
           echo "breaking_change=false" >> $GITHUB_OUTPUT
         fi
     - name: Add label
       if: steps.check_breaking_change.outputs.breaking_change == 'true'
-      uses: actions/github-script@v6
+      uses: actions/github-script@v7
       with:
         github-token: ${{ secrets.GITHUB_TOKEN }}
         script: |

.github/workflows/ci.yml

@@ -30,10 +30,10 @@ jobs:
     steps:
       - name: Checkout
         if: github.event_name != 'pull_request'
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
       - name: Checkout
         if: github.event_name == 'pull_request'
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with:
           ref: ${{ github.event.pull_request.head.sha }}
       - name: Install Rust nightly
@@ -60,7 +60,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
       - name: Install Rust stable
         uses: dtolnay/rust-toolchain@stable
         with:
@@ -74,7 +74,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
       - name: Install Rust stable
         uses: dtolnay/rust-toolchain@stable
         with:
@@ -96,11 +96,11 @@ jobs:
       fail-fast: false
       matrix:
         os: [ ubuntu-latest, windows-latest, macos-latest ]
-        toolchain: [ "1.67.0", "stable" ]
+        toolchain: [ "1.70.0", "stable" ]
     runs-on: ${{ matrix.os }}
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
       - name: Install Rust {{ matrix.toolchain }}
         uses: dtolnay/rust-toolchain@master
         with:
@@ -120,7 +120,7 @@ jobs:
     runs-on: ${{ matrix.os }}
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
       - name: Install Rust stable
         uses: dtolnay/rust-toolchain@stable
       - name: Install cargo-make
@@ -135,7 +135,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ ubuntu-latest, windows-latest, macos-latest ]
-        toolchain: [ "1.67.0", "stable" ]
+        toolchain: [ "1.70.0", "stable" ]
         backend: [ crossterm, termion, termwiz ]
         exclude:
           # termion is not supported on windows
@@ -144,7 +144,7 @@ jobs:
     runs-on: ${{ matrix.os }}
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
       - name: Install Rust ${{ matrix.toolchain }}}
         uses: dtolnay/rust-toolchain@master
         with:

BREAKING-CHANGES.md

@@ -10,7 +10,16 @@ github with a [breaking change] label.
 
 This is a quick summary of the sections below:
 
-- [Unreleased (v0.24.0)](#unreleased-0240)
+- Unreleased (0.24.1)
+  - Removed `Axis::title_style` and `Buffer::set_background`
+  - `List::new()` now accepts `IntoIterator<Item = Into<ListItem<'a>>>`
+  - `Table::new()` now requires specifying the widths
+  - `Table::widths()` now accepts `IntoIterator<Item = AsRef<Constraint>>`
+  - Layout::new() now accepts direction and constraint parameters
+  - The default `Tabs::highlight_style` is now `Style::new().reversed()`
+
+- [v0.24.0](#v0240)
+  - MSRV is now 1.70.0
   - `ScrollbarState`: `position`, `content_length`, and `viewport_content_length` are now `usize`
   - `BorderType`: `line_symbols` is now `border_symbols` and returns `symbols::border::set`
   - `Frame<'a, B: Backend>` is now `Frame<'a>`
@@ -31,7 +40,110 @@ This is a quick summary of the sections below:
   - MSRV is now 1.63.0
   - `List` no longer ignores empty strings
 
-## Unreleased (0.24.0)
+## Unreleased (v0.24.1)
+
+### Removed `Axis::title_style` and `Buffer::set_background`
+
+These items were deprecated since 0.10.
+
+- You should use styling capabilities of [`text::Line`] given as argument of [`Axis::title`]
+instead of `Axis::title_style`
+- You should use styling capabilities of [`Buffer::set_style`] instead of `Buffer::set_background`
+
+[`text::Line`]: https://docs.rs/ratatui/latest/ratatui/text/struct.Line.html
+[`Axis::title`]: https://docs.rs/ratatui/latest/ratatui/widgets/struct.Axis.html#method.title
+[`Buffer::set_style`]: https://docs.rs/ratatui/latest/ratatui/buffer/struct.Buffer.html#method.set_style
+
+### `List::new()` now accepts `IntoIterator<Item = Into<ListItem<'a>>>` ([#672])
+
+[#672]: https://github.com/ratatui-org/ratatui/pull/672
+
+Previously `List::new()` took `Into<Vec<ListItem<'a>>>`. This change will throw a compilation 
+error for `IntoIterator`s with an indeterminate item (e.g. empty vecs).
+
+E.g.
+
+```diff
+- let list = List::new(vec![]);
+// becomes
++ let list = List::default();
+```
+
+### The default `Tabs::highlight_style` is now `Style::new().reversed()` ([#635])
+
+Previously the default highlight style for tabs was `Style::default()`, which meant that a `Tabs`
+widget in the default configuration would not show any indication of the selected tab.
+
+[#635]: https://github.com/ratatui-org/ratatui/pull/635
+
+### The default `Tabs::highlight_style` is now `Style::new().reversed()` ([#635])
+
+Previously the default highlight style for tabs was `Style::default()`, which meant that a `Tabs`
+widget in the default configuration would not show any indication of the selected tab.
+
+
+### `Table::new()` now requires specifying the widths of the columns (#664)
+
+[#664]: https://github.com/ratatui-org/ratatui/pull/664
+
+Previously `Table`s could be constructed without widths. In almost all cases this is an error.
+A new widths parameter is now mandatory on `Table::new()`. Existing code of the form:
+
+```diff
+- Table::new(rows).widths(widths)
+```
+
+Should be updated to:
+
+```diff
++ Table::new(rows, widths)
+```
+
+For ease of automated replacement in cases where the amount of code broken by this change is large
+or complex, it may be convenient to replace `Table::new` with `Table::default().rows`.
+
+```diff
+- Table::new(rows).block(block).widths(widths);
+// becomes
++ Table::default().rows(rows).widths(widths)
+```
+
+### `Table::widths()` now accepts `IntoIterator<Item = AsRef<Constraint>>` ([#663])
+
+[#663]: https://github.com/ratatui-org/ratatui/pull/663
+
+Previously `Table::widths()` took a slice (`&'a [Constraint]`). This change will introduce clippy
+`needless_borrow` warnings for places where slices are passed to this method. To fix these, remove
+the `&`.
+
+E.g.
+
+```diff
+- let table = Table::new(rows).widths(&[Constraint::Length(1)]);
+// becomes
++ let table = Table::new(rows).widths([Constraint::Length(1)]);
+```
+
+### Layout::new() now accepts direction and constraint parameters ([#557])
+
+[#557]: https://github.com/ratatui-org/ratatui/pull/557
+
+Previously layout new took no parameters. Existing code should either use `Layout::default()` or
+the new constructor.
+
+```rust
+let layout = layout::new()
+  .direction(Direction::Vertical)
+  .constraints([Constraint::Min(1), Constraint::Max(2)]);
+// becomes either
+let layout = layout::default()
+  .direction(Direction::Vertical)
+  .constraints([Constraint::Min(1), Constraint::Max(2)]);
+// or
+let layout = layout::new(Direction::Vertical, [Constraint::Min(1), Constraint::Max(2)]);
+```
+
+## [v0.24.0](https://github.com/ratatui-org/ratatui/releases/tag/v0.24.0)
 
 ### ScrollbarState field type changed from `u16` to `usize` ([#456])
 
@@ -48,10 +160,10 @@ Applications can now set custom borders on a `Block` by calling `border_set()`.
 `BorderType::line_symbols()` is renamed to `border_symbols()` and now returns a new struct
 `symbols::border::Set`. E.g.:
 
-```rust
-let line_set: symbols::line::Set = BorderType::line_symbols(BorderType::Plain);
+```diff
+- let line_set: symbols::line::Set = BorderType::line_symbols(BorderType::Plain);
 // becomes
-let border_set: symbols::border::Set = BorderType::border_symbols(BorderType::Plain);
++ let border_set: symbols::border::Set = BorderType::border_symbols(BorderType::Plain);
 ```
 
 ### Generic `Backend` parameter removed from `Frame` ([#530])
@@ -62,10 +174,10 @@ let border_set: symbols::border::Set = BorderType::border_symbols(BorderType::Pl
 accept `Frame`. To migrate existing code, remove any generic parameters from code that uses an
 instance of a Frame. E.g.:
 
-```rust
-fn ui<B: Backend>(frame: &mut Frame<B>) { ... }
+```diff
+- fn ui<B: Backend>(frame: &mut Frame<B>) { ... }
 // becomes
-fn ui(frame: Frame) { ... }
++ fn ui(frame: Frame) { ... }
 ```
 
 ### `Stylize` shorthands now consume rather than borrow `String` ([#466])
@@ -77,13 +189,13 @@ new implementation of `Stylize` was added that returns a `Span<'static>`. This c
 be consumed rather than borrowed. Existing code that expects to use the string after a call will no
 longer compile. E.g.
 
-```rust
-let s = String::new("foo");
-let span1 = s.red();
-let span2 = s.blue(); // will no longer compile as s is consumed by the previous line
+```diff
+- let s = String::new("foo");
+- let span1 = s.red();
+- let span2 = s.blue(); // will no longer compile as s is consumed by the previous line
 // becomes
-let span1 = s.clone().red();
-let span2 = s.blue();
++ let span1 = s.clone().red();
++ let span2 = s.blue();
 ```
 
 ### Deprecated `Spans` type removed (replaced with `Line`) ([#426])
@@ -93,12 +205,12 @@ let span2 = s.blue();
 `Spans` was replaced with `Line` in 0.21.0. `Buffer::set_spans` was replaced with
 `Buffer::set_line`.
 
-```rust
-let spans = Spans::from(some_string_str_span_or_vec_span);
-buffer.set_spans(0, 0, spans, 10);
+```diff
+- let spans = Spans::from(some_string_str_span_or_vec_span);
+- buffer.set_spans(0, 0, spans, 10);
 // becomes
-let line - Line::from(some_string_str_span_or_vec_span);
-buffer.set_line(0, 0, line, 10);
++ let line - Line::from(some_string_str_span_or_vec_span);
++ buffer.set_line(0, 0, line, 10);
 ```
 
 ## [v0.23.0](https://github.com/ratatui-org/ratatui/releases/tag/v0.23.0)
@@ -109,10 +221,10 @@ buffer.set_line(0, 0, line, 10);
 
 The track symbol of `Scrollbar` is now optional, this method now takes an optional value.
 
-```rust
-let scrollbar = Scrollbar::default().track_symbol("|");
+```diff
+- let scrollbar = Scrollbar::default().track_symbol("|");
 // becomes
-let scrollbar = Scrollbar::default().track_symbol(Some("|"));
++ let scrollbar = Scrollbar::default().track_symbol(Some("|"));
 ```
 
 ### `Scrollbar` symbols moved to `symbols::scrollbar` and `widgets::scrollbar` module is private ([#330])
@@ -123,10 +235,10 @@ The symbols for defining scrollbars have been moved to the `symbols` module from
 `widgets::scrollbar` module which is no longer public. To update your code update any imports to the
 new module locations. E.g.:
 
-```rust
-use ratatui::{widgets::scrollbar::{Scrollbar, Set}};
+```diff
+- use ratatui::{widgets::scrollbar::{Scrollbar, Set}};
 // becomes
-use ratatui::{widgets::Scrollbar, symbols::scrollbar::Set} 
++ use ratatui::{widgets::Scrollbar, symbols::scrollbar::Set} 
 ```
 
 ### MSRV updated to 1.67 ([#361])
@@ -160,13 +272,13 @@ The minimum supported rust version is now 1.65.0.
 In order to support inline viewports, the unstable method `Terminal::with_options()` was stabilized
 and  `ViewPort` was changed from a struct to an enum.
 
-```rust
+```diff
 let terminal = Terminal::with_options(backend, TerminalOptions {
-    viewport: Viewport::fixed(area),
+-    viewport: Viewport::fixed(area),
 });
 // becomes
 let terminal = Terminal::with_options(backend, TerminalOptions {
-    viewport: Viewport::Fixed(area),
++    viewport: Viewport::Fixed(area),
 });
 ```
 
@@ -178,10 +290,10 @@ A new type `Masked` was introduced that implements `From<Text<'a>>`. This causes
 previously did not need to use type annotations to fail to compile.  To fix this, annotate or call
 to_string() / to_owned() / as_str() on the value. E.g.:
 
-```rust
-let paragraph = Paragraph::new("".as_ref());
+```diff
+- let paragraph = Paragraph::new("".as_ref());
 // becomes
-let paragraph = Paragraph::new("".as_str());
++ let paragraph = Paragraph::new("".as_str());
 ```
 
 ### `Marker::Block` now renders as a block rather than a bar character ([#133])
@@ -192,10 +304,10 @@ Code using the `Block` marker that previously rendered using a half block charac
 renders using the full block character (`'█'`). A new marker variant`Bar` is introduced to replace
 the existing code.
 
-```rust
-let canvas = Canvas::default().marker(Marker::Block);
+```diff
+- let canvas = Canvas::default().marker(Marker::Block);
 // becomes
-let canvas = Canvas::default().marker(Marker::Bar);
++ let canvas = Canvas::default().marker(Marker::Bar);
 ```
 
 ## [v0.20.0](https://github.com/ratatui-org/ratatui/releases/tag/v0.20.0)

CHANGELOG.md

@@ -2,6 +2,675 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.24.0](https://github.com/ratatui-org/ratatui/releases/tag/0.24.0) - 2023-10-23
+
+We are excited to announce the new version of `ratatui` - a Rust library that's all about cooking up TUIs 🐭
+
+In this version, we've introduced features like window size API, enhanced chart rendering, and more.
+The list of \*breaking changes\* can be found [here](https://github.com/ratatui-org/ratatui/blob/main/BREAKING-CHANGES.md) ⚠️.
+Also, we created various tutorials and walkthroughs in [Ratatui Book](https://github.com/ratatui-org/ratatui-book) which is available at <https://ratatui.rs> 🚀
+
+✨ **Release highlights**: <https://ratatui.rs/highlights/v0.24.html>
+
+### Features
+
+- [c6c3f88](https://github.com/ratatui-org/ratatui/commit/c6c3f88a79515a085fb8a96fe150843dab6dd5bc)
+  _(backend)_ Implement common traits for `WindowSize` ([#586](https://github.com/ratatui-org/ratatui/issues/586))
+
+- [d077903](https://github.com/ratatui-org/ratatui/commit/d0779034e741834aac36b5b7a87c54bd8c50b7f2)
+  _(backend)_ Backend provides window_size, add Size struct ([#276](https://github.com/ratatui-org/ratatui/issues/276))
+
+  ```text
+  For image (sixel, iTerm2, Kitty...) support that handles graphics in
+  terms of `Rect` so that the image area can be included in layouts.
+
+  For example: an image is loaded with a known pixel-size, and drawn, but
+  the image protocol has no mechanism of knowing the actual cell/character
+  area that been drawn on. It is then impossible to skip overdrawing the
+  area.
+
+  Returning the window size in pixel-width / pixel-height, together with
+  columns / rows, it can be possible to account the pixel size of each cell
+  / character, and then known the `Rect` of a given image, and also resize
+  the image so that it fits exactly in a `Rect`.
+
+  Crossterm and termwiz also both return both sizes from one syscall,
+  while termion does two.
+
+  Add a `Size` struct for the cases where a `Rect`'s `x`/`y` is unused
+  (always zero).
+
+  `Size` is not "clipped" for `area < u16::max_value()` like `Rect`. This
+  is why there are `From` implementations between the two.
+  ```
+
+- [301366c](https://github.com/ratatui-org/ratatui/commit/301366c4fa33524b0634bbd3dcf1abd1a1ebe7c6)
+  _(barchart)_ Render charts smaller than 3 lines ([#532](https://github.com/ratatui-org/ratatui/issues/532))
+
+  ```text
+  The bar values are not shown if the value width is equal the bar width
+  and the bar is height is less than one line
+
+  Add an internal structure `LabelInfo` which stores the reserved height
+  for the labels (0, 1 or 2) and also whether the labels will be shown.
+
+  Fixes ratatui-org#513
+  ```
+
+- [32e4619](https://github.com/ratatui-org/ratatui/commit/32e461953c8c9231edeef65c410b295916f26f3e)
+  _(block)_ Allow custom symbols for borders ([#529](https://github.com/ratatui-org/ratatui/issues/529)) [**breaking**]
+
+  ````text
+  Adds a new `Block::border_set` method that allows the user to specify
+  the symbols used for the border.
+
+  Added two new border types: `BorderType::QuadrantOutside` and
+  `BorderType::QuadrantInside`. These are used to draw borders using the
+  unicode quadrant characters (which look like half block "pixels").
+
+  ```
+  ▛▀▀▜
+  ▌  ▐
+  ▙▄▄▟
+
+  ▗▄▄▖
+  ▐  ▌
+  ▝▀▀▘
+  ```
+  Fixes: https://github.com/ratatui-org/ratatui/issues/528
+
+  BREAKING CHANGES:
+  - BorderType::to_line_set is renamed to to_border_set
+  - BorderType::line_symbols is renamed to border_symbols
+  ````
+
+- [4541336](https://github.com/ratatui-org/ratatui/commit/45413365146ede5472dc28e0ee1970d245e2fa02)
+  _(canvas)_ Implement half block marker ([#550](https://github.com/ratatui-org/ratatui/issues/550))
+
+  ```text
+  * feat(canvas): implement half block marker
+
+  A useful technique for the terminal is to use half blocks to draw a grid
+  of "pixels" on the screen. Because we can set two colors per cell, and
+  because terminal cells are about twice as tall as they are wide, we can
+  draw a grid of half blocks that looks like a grid of square pixels.
+
+  This commit adds a new `HalfBlock` marker that can be used in the Canvas
+  widget and the associated HalfBlockGrid.
+
+  Also updated demo2 to use the new marker as it looks much nicer.
+
+  Adds docs for many of the methods and structs on canvas.
+
+  Changes the grid resolution method to return the pixel count
+  rather than the index of the last pixel.
+  This is an internal detail with no user impact.
+  ```
+
+- [be55a5f](https://github.com/ratatui-org/ratatui/commit/be55a5fbcdffc4fd6aeb7edffa32f6e6c942a41e)
+  _(examples)_ Add demo2 example ([#500](https://github.com/ratatui-org/ratatui/issues/500))
+
+- [082cbcb](https://github.com/ratatui-org/ratatui/commit/082cbcbc501d4284dc7e142227f9e04ef17da61d)
+  _(frame)_ Remove generic Backend parameter ([#530](https://github.com/ratatui-org/ratatui/issues/530)) [**breaking**]
+
+  ````text
+  This change simplifies UI code that uses the Frame type. E.g.:
+
+  ```rust
+  fn draw<B: Backend>(frame: &mut Frame<B>) {
+      // ...
+  }
+  ```
+
+  Frame was generic over Backend because it stored a reference to the
+  terminal in the field. Instead it now directly stores the viewport area
+  and current buffer. These are provided at creation time and are valid
+  for the duration of the frame.
+
+  BREAKING CHANGE: Frame is no longer generic over Backend. Code that
+  accepted a Frame<Backend> will now need to accept a Frame.
+  ````
+
+- [d67fa2c](https://github.com/ratatui-org/ratatui/commit/d67fa2c00d6d6125eeefa0eeeb032664dae9a4de)
+  _(line)_ Add `Line::raw` constructor ([#511](https://github.com/ratatui-org/ratatui/issues/511))
+
+  ```text
+  * feat(line): add `Line::raw` constructor
+
+  There is already `Span::raw` and `Text::raw` methods
+  and this commit simply adds `Line::raw` method for symmetry.
+
+  Multi-line content is converted to multiple spans with the new line removed
+  ```
+
+- [cbf86da](https://github.com/ratatui-org/ratatui/commit/cbf86da0e7e4a2d99ace8df68854de74157a665a)
+  _(rect)_ Add is_empty() to simplify some common checks ([#534](https://github.com/ratatui-org/ratatui/issues/534))
+
+  ```text
+  - add `Rect::is_empty()` that checks whether either height or width == 0
+  - refactored `Rect` into layout/rect.rs from layout.rs. No public API change as
+     the module is private and the type is re-exported under the `layout` module.
+  ```
+
+- [15641c8](https://github.com/ratatui-org/ratatui/commit/15641c8475b7596c97a0affce0d6082c4b9586c2)
+  _(uncategorized)_ Add `buffer_mut` method on `Frame` ✨ ([#548](https://github.com/ratatui-org/ratatui/issues/548))
+
+### Bug Fixes
+
+- [638d596](https://github.com/ratatui-org/ratatui/commit/638d596a3b7aec723a2354cf0e261b207ac412f8)
+  _(layout)_ Use LruCache for layout cache ([#487](https://github.com/ratatui-org/ratatui/issues/487))
+
+  ```text
+  The layout cache now uses a LruCache with default size set to 16 entries.
+  Previously the cache was backed by a HashMap, and was able to grow
+  without bounds as a new entry was added for every new combination of
+  layout parameters.
+
+  - Added a new method (`layout::init_cache(usize)`) that allows the cache
+  size to be changed if necessary. This will only have an effect if it is called
+  prior to any calls to `layout::split()` as the cache is wrapped in a `OnceLock`
+  ```
+
+- [8d507c4](https://github.com/ratatui-org/ratatui/commit/8d507c43fa866ab4c0eda9fd169f307fba2a1109)
+  _(backend)_ Add feature flag for underline-color ([#570](https://github.com/ratatui-org/ratatui/issues/570))
+
+  ````text
+  Windows 7 doesn't support the underline color attribute, so we need to
+  make it optional. This commit adds a feature flag for the underline
+  color attribute - it is enabled by default, but can be disabled by
+  passing `--no-default-features` to cargo.
+
+  We could specically check for Windows 7 and disable the feature flag
+  automatically, but I think it's better for this check to be done by the
+  crossterm crate, since it's the one that actually knows about the
+  underlying terminal.
+
+  To disable the feature flag in an application that supports Windows 7,
+  add the following to your Cargo.toml:
+
+  ```toml
+  ratatui = { version = "0.24.0", default-features = false, features = ["crossterm"] }
+  ```
+
+  Fixes https://github.com/ratatui-org/ratatui/issues/555
+  ````
+
+- [c3155a2](https://github.com/ratatui-org/ratatui/commit/c3155a24895ec4dfb1a8e580fb9ee3d31e9af139)
+  _(barchart)_ Add horizontal labels([#518](https://github.com/ratatui-org/ratatui/issues/518))
+
+  ```text
+  Labels were missed in the initial implementation of the horizontal
+  mode for the BarChart widget. This adds them.
+
+  Fixes https://github.com/ratatui-org/ratatui/issues/499
+  ```
+
+- [c5ea656](https://github.com/ratatui-org/ratatui/commit/c5ea656385843c880b3bef45dccbe8ea57431d10)
+  _(barchart)_ Avoid divide by zero in rendering ([#525](https://github.com/ratatui-org/ratatui/issues/525))
+
+- [c9b8e7c](https://github.com/ratatui-org/ratatui/commit/c9b8e7cf412de235082f1fcd1698468c4b1b6171)
+  _(barchart)_ Render value labels with unicode correctly ([#515](https://github.com/ratatui-org/ratatui/issues/515))
+
+  ```text
+  An earlier change introduced a bug where the width of value labels with
+  unicode characters was incorrectly using the string length in bytes
+  instead of the unicode character count. This reverts the earlier change.
+  ```
+
+- [c8ab2d5](https://github.com/ratatui-org/ratatui/commit/c8ab2d59087f5b475ecf6ffa31b89ce24b6b1d28)
+  _(chart)_ Use graph style for top line ([#462](https://github.com/ratatui-org/ratatui/issues/462))
+
+  ```text
+  A bug in the rendering caused the top line of the chart to be rendered
+  using the style of the chart, instead of the dataset style. This is
+  fixed by only setting the style for the width of the text, and not the
+  entire row.
+  ```
+
+- [0c7d547](https://github.com/ratatui-org/ratatui/commit/0c7d547db196a7cf65a6bf8cde74bd908407a3ff)
+  _(docs)_ Don't fail rustdoc due to termion ([#503](https://github.com/ratatui-org/ratatui/issues/503))
+
+  ```text
+  Windows cannot compile termion, so it is not included in the docs.
+  Rustdoc will fail if it cannot find a link, so the docs fail to build
+  on windows.
+
+  This replaces the link to TermionBackend with one that does not fail
+  during checks.
+
+  Fixes https://github.com/ratatui-org/ratatui/issues/498
+  ```
+
+- [0c52ff4](https://github.com/ratatui-org/ratatui/commit/0c52ff431a1eedb0e38b5c8fb6623d4da17fa97e)
+  _(gauge)_ Fix gauge widget colors ([#572](https://github.com/ratatui-org/ratatui/issues/572))
+
+  ```text
+  The background colors of the gauge had a workaround for the issue we had
+  with VHS / TTYD rendering the background color of the gauge. This
+  workaround is no longer necessary in the updated versions of VHS / TTYD.
+
+  Fixes https://github.com/ratatui-org/ratatui/issues/501
+  ```
+
+- [11076d0](https://github.com/ratatui-org/ratatui/commit/11076d0af3a76229af579fb40684fdd37df172dd)
+  _(rect)_ Fix arithmetic overflow edge cases ([#543](https://github.com/ratatui-org/ratatui/issues/543))
+
+  ```text
+  Fixes https://github.com/ratatui-org/ratatui/issues/258
+  ```
+
+- [21303f2](https://github.com/ratatui-org/ratatui/commit/21303f21672de1405135bb785497c30150644078)
+  _(rect)_ Prevent overflow in inner() and area() ([#523](https://github.com/ratatui-org/ratatui/issues/523))
+
+- [ebd3680](https://github.com/ratatui-org/ratatui/commit/ebd3680a471d96ae1d8f52cd9e4a8a80c142d060)
+  _(stylize)_ Add Stylize impl for String ([#466](https://github.com/ratatui-org/ratatui/issues/466)) [**breaking**]
+
+  ```text
+  Although the `Stylize` trait is already implemented for `&str` which
+  extends to `String`, it is not implemented for `String` itself. This
+  commit adds an impl of Stylize that returns a Span<'static> for `String`
+  so that code can call Stylize methods on temporary `String`s.
+
+  E.g. the following now compiles instead of failing with a compile error
+  about referencing a temporary value:
+
+      let s = format!("hello {name}!", "world").red();
+
+  BREAKING CHANGE: This may break some code that expects to call Stylize
+  methods on `String` values and then use the String value later. This
+  will now fail to compile because the String is consumed by set_style
+  instead of a slice being created and consumed.
+
+  This can be fixed by cloning the `String`. E.g.:
+
+      let s = String::from("hello world");
+      let line = Line::from(vec![s.red(), s.green()]); // fails to compile
+      let line = Line::from(vec![s.clone().red(), s.green()]); // works
+
+  Fixes https://discord.com/channels/1070692720437383208/1072907135664529508/1148229700821450833
+  ```
+
+### Refactor
+
+- [2fd85af](https://github.com/ratatui-org/ratatui/commit/2fd85af33c5cb7c04286e4e4198a939b4857eadc)
+  _(barchart)_ Simplify internal implementation ([#544](https://github.com/ratatui-org/ratatui/issues/544))
+
+  ```text
+  Replace `remove_invisible_groups_and_bars` with `group_ticks`
+  `group_ticks` calculates the visible bar length in ticks. (A cell contains 8 ticks).
+
+  It is used for 2 purposes:
+  1. to get the bar length in ticks for rendering
+  2. since it delivers only the values of the visible bars, If we zip these values
+     with the groups and bars, then we will filter out the invisible groups and bars
+  ```
+
+### Documentation
+
+- [0c68ebe](https://github.com/ratatui-org/ratatui/commit/0c68ebed4f63a595811006e0af221b11a83780cf)
+  _(block)_ Add documentation to Block ([#469](https://github.com/ratatui-org/ratatui/issues/469))
+
+- [0fe7385](https://github.com/ratatui-org/ratatui/commit/0fe738500cd461aeafa0a63b37ed6250777f3599)
+  _(gauge)_ Add docs for `Gauge` and `LineGauge` ([#514](https://github.com/ratatui-org/ratatui/issues/514))
+
+- [27c5637](https://github.com/ratatui-org/ratatui/commit/27c56376756b854db6d2fd8939419bd8578f8a90)
+  _(readme)_ Fix links to CONTRIBUTING.md and BREAKING-CHANGES.md ([#577](https://github.com/ratatui-org/ratatui/issues/577))
+
+- [1947c58](https://github.com/ratatui-org/ratatui/commit/1947c58c60127ee7d1a72bcd408ee23062b8c4ec)
+  _(backend)_ Improve backend module docs ([#489](https://github.com/ratatui-org/ratatui/issues/489))
+
+- [e098731](https://github.com/ratatui-org/ratatui/commit/e098731d6c1a68a0319d544301ac91cf2d05ccb2)
+  _(barchart)_ Add documentation to `BarChart` ([#449](https://github.com/ratatui-org/ratatui/issues/449))
+
+  ```text
+  Add documentation to the `BarChart` widgets and its sub-modules.
+  ```
+
+- [17797d8](https://github.com/ratatui-org/ratatui/commit/17797d83dab07dc6b76e7a3838e3e17fc3c94711)
+  _(canvas)_ Add support note for Braille marker ([#472](https://github.com/ratatui-org/ratatui/issues/472))
+
+- [3cf0b83](https://github.com/ratatui-org/ratatui/commit/3cf0b83bda5deee18b8a1233acec0a21fde1f5f4)
+  _(color)_ Document true color support ([#477](https://github.com/ratatui-org/ratatui/issues/477))
+
+  ```text
+  * refactor(style): move Color to separate color mod
+
+  * docs(color): document true color support
+  ```
+
+- [e5caf17](https://github.com/ratatui-org/ratatui/commit/e5caf170c8c304b952cbff7499fd4da17ab154ea)
+  _(custom_widget)_ Make button sticky when clicking with mouse ([#561](https://github.com/ratatui-org/ratatui/issues/561))
+
+- [ad2dc56](https://github.com/ratatui-org/ratatui/commit/ad2dc5646dae04fa5502e677182cdeb0c3630cce)
+  _(examples)_ Update examples readme ([#576](https://github.com/ratatui-org/ratatui/issues/576))
+
+  ```text
+  remove VHS bug info, tweak colors_rgb image, update some of the instructions. add demo2
+  ```
+
+- [b61f65b](https://github.com/ratatui-org/ratatui/commit/b61f65bc20918380f2854253d4301ea804fc7437)
+  _(examples)_ Update theme to Aardvark Blue ([#574](https://github.com/ratatui-org/ratatui/issues/574))
+
+  ```text
+  This is a nicer theme that makes the colors pop
+  ```
+
+- [61af0d9](https://github.com/ratatui-org/ratatui/commit/61af0d99069ec99b3075cd499ede13cc2143401f)
+  _(examples)_ Make custom widget example into a button ([#539](https://github.com/ratatui-org/ratatui/issues/539))
+
+  ```text
+  The widget also now supports mouse
+  ```
+
+- [6b8725f](https://github.com/ratatui-org/ratatui/commit/6b8725f09173f418e9f17933d8ef8c943af444de)
+  _(examples)_ Add colors_rgb example ([#476](https://github.com/ratatui-org/ratatui/issues/476))
+
+- [5c785b2](https://github.com/ratatui-org/ratatui/commit/5c785b22709fb64a0982722e4f6d0021ccf621b2)
+  _(examples)_ Move example gifs to github ([#460](https://github.com/ratatui-org/ratatui/issues/460))
+
+  ```text
+  - A new orphan branch named "images" is created to store the example
+    images
+  ```
+
+- [ca9bcd3](https://github.com/ratatui-org/ratatui/commit/ca9bcd3156f55cd2df4edf003aa1401abbed9b12)
+  _(examples)_ Add descriptions and update theme ([#460](https://github.com/ratatui-org/ratatui/issues/460))
+
+  ```text
+  - Use the OceanicMaterial consistently in examples
+  ```
+
+- [080a05b](https://github.com/ratatui-org/ratatui/commit/080a05bbd3357cde3f0a02721a0f7f1aa206206b)
+  _(paragraph)_ Add docs for alignment fn ([#467](https://github.com/ratatui-org/ratatui/issues/467))
+
+- [1e20475](https://github.com/ratatui-org/ratatui/commit/1e204750617acccf952b1845a3c7ce86e2b90cf7)
+  _(stylize)_ Improve docs for style shorthands ([#491](https://github.com/ratatui-org/ratatui/issues/491))
+
+  ```text
+  The Stylize trait was introduced in 0.22 to make styling less verbose.
+  This adds a bunch of documentation comments to the style module and
+  types to make this easier to discover.
+  ```
+
+- [dd9a8df](https://github.com/ratatui-org/ratatui/commit/dd9a8df03ab09d2381ef5ddd0c2b6ef5517b44df)
+  _(table)_ Add documentation for `block` and `header` methods of the `Table` widget ([#505](https://github.com/ratatui-org/ratatui/issues/505))
+
+- [232be80](https://github.com/ratatui-org/ratatui/commit/232be80325cb899359ea1389516c421e57bc9cce)
+  _(table)_ Add documentation for `Table::new()` ([#471](https://github.com/ratatui-org/ratatui/issues/471))
+
+- [3bda372](https://github.com/ratatui-org/ratatui/commit/3bda37284781b62560cde2a7fa774211f651ec25)
+  _(tabs)_ Add documentation to `Tabs` ([#535](https://github.com/ratatui-org/ratatui/issues/535))
+
+- [42f8169](https://github.com/ratatui-org/ratatui/commit/42f816999e2cd573c498c4885069a5523707663c)
+  _(terminal)_ Add docs for terminal module ([#486](https://github.com/ratatui-org/ratatui/issues/486))
+
+  ```text
+  - moves the impl Terminal block up to be closer to the type definition
+  ```
+
+- [28e7fd4](https://github.com/ratatui-org/ratatui/commit/28e7fd4bc58edf537b66b69095691ae06872acd8)
+  _(terminal)_ Fix doc comment ([#452](https://github.com/ratatui-org/ratatui/issues/452))
+
+- [51fdcbe](https://github.com/ratatui-org/ratatui/commit/51fdcbe7e936b3af3ee6a8ae8fee43df31aab27c)
+  _(title)_ Add documentation to title ([#443](https://github.com/ratatui-org/ratatui/issues/443))
+
+  ```text
+  This adds documentation for Title and Position
+  ```
+
+- [d4976d4](https://github.com/ratatui-org/ratatui/commit/d4976d4b63d4a17adb31bbe853a82109e2caaf1b)
+  _(widgets)_ Update the list of available widgets ([#496](https://github.com/ratatui-org/ratatui/issues/496))
+
+- [6c7bef8](https://github.com/ratatui-org/ratatui/commit/6c7bef8d111bbc3ecfe228b14002c5db9634841c)
+  _(uncategorized)_ Replace colons with dashes in README.md for consistency ([#566](https://github.com/ratatui-org/ratatui/issues/566))
+
+- [88ae348](https://github.com/ratatui-org/ratatui/commit/88ae3485c2c540b4ee630ab13e613e84efa7440a)
+  _(uncategorized)_ Update `Frame` docstring to remove reference to generic backend ([#564](https://github.com/ratatui-org/ratatui/issues/564))
+
+- [089f8ba](https://github.com/ratatui-org/ratatui/commit/089f8ba66a50847780c4416b9b8833778a95e558)
+  _(uncategorized)_ Add double quotes to instructions for features ([#560](https://github.com/ratatui-org/ratatui/issues/560))
+
+- [346e7b4](https://github.com/ratatui-org/ratatui/commit/346e7b4f4d53063ee13b04758b1b994e4f14e51c)
+  _(uncategorized)_ Add summary to breaking changes ([#549](https://github.com/ratatui-org/ratatui/issues/549))
+
+- [401a7a7](https://github.com/ratatui-org/ratatui/commit/401a7a7f7111989d7dda11524b211a488483e732)
+  _(uncategorized)_ Improve clarity in documentation for `Frame` and `Terminal` 📚 ([#545](https://github.com/ratatui-org/ratatui/issues/545))
+
+- [e35e413](https://github.com/ratatui-org/ratatui/commit/e35e4135c9080389baa99e13814aace7784d9cb3)
+  _(uncategorized)_ Fix terminal comment ([#547](https://github.com/ratatui-org/ratatui/issues/547))
+
+- [8ae4403](https://github.com/ratatui-org/ratatui/commit/8ae4403b63a82d353b224c898b15249f30215476)
+  _(uncategorized)_ Fix `Terminal` docstring ([#546](https://github.com/ratatui-org/ratatui/issues/546))
+
+- [9cfb133](https://github.com/ratatui-org/ratatui/commit/9cfb133a981c070a27342d78f4b9451673d8b349)
+  _(uncategorized)_ Document alpha release process ([#542](https://github.com/ratatui-org/ratatui/issues/542))
+
+  ```text
+  Fixes https://github.com/ratatui-org/ratatui/issues/412
+  ```
+
+- [4548a9b](https://github.com/ratatui-org/ratatui/commit/4548a9b7e22b07c1bd6839280c44123b8679589d)
+  _(uncategorized)_ Add BREAKING-CHANGES.md ([#538](https://github.com/ratatui-org/ratatui/issues/538))
+
+  ```text
+  Document the breaking changes in each version. This document is
+  manually curated by summarizing the breaking changes in the changelog.
+  ```
+
+- [c0991cc](https://github.com/ratatui-org/ratatui/commit/c0991cc576b3ade02494cb33fd7c290aba55bfb8)
+  _(uncategorized)_ Make library and README consistent ([#526](https://github.com/ratatui-org/ratatui/issues/526))
+
+  ```text
+  * docs: make library and README consistent
+
+  Generate the bulk of the README from the library documentation, so that
+  they are consistent using cargo-rdme.
+
+  - Removed the Contributors section, as it is redundant with the github
+    contributors list.
+  - Removed the info about the other backends and replaced it with a
+    pointer to the documentation.
+  - add docsrs example, vhs tape and images that will end up in the README
+  ```
+
+- [1414fbc](https://github.com/ratatui-org/ratatui/commit/1414fbcc05b4dfd7706cc68fcaba7d883e22f869)
+  _(uncategorized)_ Import prelude::\* in doc examples ([#490](https://github.com/ratatui-org/ratatui/issues/490))
+
+  ```text
+  This commit adds `prelude::*` all doc examples and widget::* to those
+  that need it. This is done to highlight the use of the prelude and
+  simplify the examples.
+
+  - Examples in Type and module level comments show all imports and use
+    `prelude::*` and `widget::*` where possible.
+  - Function level comments hide imports unless there are imports other
+    than `prelude::*` and `widget::*`.
+  ```
+
+- [74c5244](https://github.com/ratatui-org/ratatui/commit/74c5244be12031e372797c3c7949914552293f5c)
+  _(uncategorized)_ Add logo and favicon to docs.rs page ([#473](https://github.com/ratatui-org/ratatui/issues/473))
+
+- [927a5d8](https://github.com/ratatui-org/ratatui/commit/927a5d8251a7947446100f4bb4d7a8e3ec2ad962)
+  _(uncategorized)_ Fix documentation lint warnings ([#450](https://github.com/ratatui-org/ratatui/issues/450))
+
+- [eda2fb7](https://github.com/ratatui-org/ratatui/commit/eda2fb7077dcf0b158d1a69d2725aeb9464162be)
+  _(uncategorized)_ Use ratatui 📚 ([#446](https://github.com/ratatui-org/ratatui/issues/446))
+
+### Testing
+
+- [ea70bff](https://github.com/ratatui-org/ratatui/commit/ea70bffe5d3ec68dcf9eff015437d2474c08f855)
+  _(barchart)_ Add benchmarks ([#455](https://github.com/ratatui-org/ratatui/issues/455))
+
+- [94af2a2](https://github.com/ratatui-org/ratatui/commit/94af2a29e10248ed709bbc8a7bf2f569894abc62)
+  _(buffer)_ Allow with_lines to accept Vec<Into<Line>> ([#494](https://github.com/ratatui-org/ratatui/issues/494))
+
+  ```text
+  This allows writing unit tests without having to call set_style on the
+  expected buffer.
+  ```
+
+### Miscellaneous Tasks
+
+- [1278131](https://github.com/ratatui-org/ratatui/commit/127813120eb17a7652b90e4333bb576e510ff51b)
+  _(changelog)_ Make the scopes lowercase in the changelog ([#479](https://github.com/ratatui-org/ratatui/issues/479))
+
+- [82b40be](https://github.com/ratatui-org/ratatui/commit/82b40be4ab8aa735070dff1681c3d711147792e1)
+  _(ci)_ Improve checking the PR title ([#464](https://github.com/ratatui-org/ratatui/issues/464))
+
+  ```text
+  - Use [`action-semantic-pull-request`](https://github.com/amannn/action-semantic-pull-request)
+  - Allow only reading the PR contents
+  - Enable merge group
+  ```
+
+- [a20bd6a](https://github.com/ratatui-org/ratatui/commit/a20bd6adb5431d19140acdf1f9201381a31b2b24)
+  _(deps)_ Update lru requirement from 0.11.1 to 0.12.0 ([#581](https://github.com/ratatui-org/ratatui/issues/581))
+
+  ```text
+  Updates the requirements on [lru](https://github.com/jeromefroe/lru-rs) to permit the latest version.
+  - [Changelog](https://github.com/jeromefroe/lru-rs/blob/master/CHANGELOG.md)
+  - [Commits](https://github.com/jeromefroe/lru-rs/compare/0.11.1...0.12.0)
+
+  ---
+  updated-dependencies:
+  - dependency-name: lru
+    dependency-type: direct:production
+  ...
+  ```
+
+- [5213f78](https://github.com/ratatui-org/ratatui/commit/5213f78d25927d834ada29b8c1023fcba5c891c6)
+  _(deps)_ Bump actions/checkout from 3 to 4 ([#580](https://github.com/ratatui-org/ratatui/issues/580))
+
+  ```text
+  Bumps [actions/checkout](https://github.com/actions/checkout) from 3 to 4.
+  - [Release notes](https://github.com/actions/checkout/releases)
+  - [Changelog](https://github.com/actions/checkout/blob/main/CHANGELOG.md)
+  - [Commits](https://github.com/actions/checkout/compare/v3...v4)
+
+  ---
+  updated-dependencies:
+  - dependency-name: actions/checkout
+    dependency-type: direct:production
+    update-type: version-update:semver-major
+  ...
+  ```
+
+- [6cbdb06](https://github.com/ratatui-org/ratatui/commit/6cbdb06fd86858849d2454d09393a8e43c10741f)
+  _(examples)_ Refactor some examples ([#578](https://github.com/ratatui-org/ratatui/issues/578))
+
+  ```text
+  * chore(examples): Simplify timeout calculation with `Duration::saturating_sub`
+  ```
+
+- [12f9291](https://github.com/ratatui-org/ratatui/commit/12f92911c74211a22c6c142762ccb459d399763b)
+  _(github)_ Create dependabot.yml ([#575](https://github.com/ratatui-org/ratatui/issues/575))
+
+  ```text
+  * chore: Create dependabot.yml
+
+  * Update .github/dependabot.yml
+  ```
+
+- [3a57e76](https://github.com/ratatui-org/ratatui/commit/3a57e76ed18b93f0bcee264d818a469920ce70db)
+  _(github)_ Add contact links for issues ([#567](https://github.com/ratatui-org/ratatui/issues/567))
+
+- [5498a88](https://github.com/ratatui-org/ratatui/commit/5498a889ae8bd4ccb51b04d3a848dd2f58935906)
+  _(spans)_ Remove deprecated `Spans` type ([#426](https://github.com/ratatui-org/ratatui/issues/426))
+
+  ```text
+  The `Spans` type (plural, not singular) was replaced with a more ergonomic `Line` type
+  in Ratatui v0.21.0 and marked deprecated byt left for backwards compatibility. This is now
+  removed.
+
+  - `Line` replaces `Spans`
+  - `Buffer::set_line` replaces `Buffer::set_spans`
+  ```
+
+- [fbf1a45](https://github.com/ratatui-org/ratatui/commit/fbf1a451c85871db598cf1df2ad9a50edbe07cd2)
+  _(uncategorized)_ Simplify constraints ([#556](https://github.com/ratatui-org/ratatui/issues/556))
+
+  ```text
+  Use bare arrays rather than array refs / Vecs for all constraint
+  examples.
+  ```
+
+- [a7bf4b3](https://github.com/ratatui-org/ratatui/commit/a7bf4b3f36f3281017d112ac1a67af7e82308261)
+  _(uncategorized)_ Use modern modules syntax ([#492](https://github.com/ratatui-org/ratatui/issues/492))
+
+  ```text
+  Move xxx/mod.rs to xxx.rs
+  ```
+
+- [af36282](https://github.com/ratatui-org/ratatui/commit/af36282df5d8dd1b4e6b32bba0539dba3382c23c)
+  _(uncategorized)_ Only run check pr action on pull_request_target events ([#485](https://github.com/ratatui-org/ratatui/issues/485))
+
+- [322e46f](https://github.com/ratatui-org/ratatui/commit/322e46f15d8326d18c951be4c57e3b47005285bc)
+  _(uncategorized)_ Prevent PR merge with do not merge labels ♻️ ([#484](https://github.com/ratatui-org/ratatui/issues/484))
+
+- [983ea7f](https://github.com/ratatui-org/ratatui/commit/983ea7f7a5371dd608891a0e2a7444a16e9fdc54)
+  _(uncategorized)_ Fix check for if breaking change label should be added ♻️ ([#483](https://github.com/ratatui-org/ratatui/issues/483))
+
+- [384e616](https://github.com/ratatui-org/ratatui/commit/384e616231c1579328e7a4ba1a7130f624753ad1)
+  _(uncategorized)_ Add a check for if breaking change label should be added ♻️ ([#481](https://github.com/ratatui-org/ratatui/issues/481))
+
+- [5f6aa30](https://github.com/ratatui-org/ratatui/commit/5f6aa30be54ea5dfcef730d709707a814e64deee)
+  _(uncategorized)_ Check documentation lint ([#454](https://github.com/ratatui-org/ratatui/issues/454))
+
+- [47ae602](https://github.com/ratatui-org/ratatui/commit/47ae602df43674928f10016e2edc97c550b01ba2)
+  _(uncategorized)_ Check that PR title matches conventional commit guidelines ♻️ ([#459](https://github.com/ratatui-org/ratatui/issues/459))
+
+- [28c6157](https://github.com/ratatui-org/ratatui/commit/28c61571e8a90345a866285a6f8459b24b70578a)
+  _(uncategorized)_ Add documentation guidelines ([#447](https://github.com/ratatui-org/ratatui/issues/447))
+
+### Continuous Integration
+
+- [343c6cd](https://github.com/ratatui-org/ratatui/commit/343c6cdc47c4fe38e64633d982aa413be356fb90)
+  _(lint)_ Move formatting and doc checks first ([#465](https://github.com/ratatui-org/ratatui/issues/465))
+
+  ```text
+  Putting the formatting and doc checks first to ensure that more critical
+  errors are caught first (e.g. a conventional commit error or typo should
+  not prevent the formatting and doc checks from running).
+  ```
+
+- [c95a75c](https://github.com/ratatui-org/ratatui/commit/c95a75c5d5e0370c98a2a37bcbd65bde996b2306)
+  _(makefile)_ Remove termion dependency from doc lint ([#470](https://github.com/ratatui-org/ratatui/issues/470))
+
+  ```text
+  Only build termion on non-windows targets
+  ```
+
+- [b996102](https://github.com/ratatui-org/ratatui/commit/b996102837dad7c77710bcbbc524c6e9691bd96f)
+  _(makefile)_ Add format target ([#468](https://github.com/ratatui-org/ratatui/issues/468))
+
+  ```text
+  - add format target to Makefile.toml that actually fixes the formatting
+  - rename fmt target to lint-format
+  - rename style-check target to lint-style
+  - rename typos target to lint-typos
+  - rename check-docs target to lint-docs
+  - add section to CONTRIBUTING.md about formatting
+  ```
+
+- [572df75](https://github.com/ratatui-org/ratatui/commit/572df758ba1056759aa6f79c9e975854d27331db)
+  _(uncategorized)_ Put commit id first in changelog ([#463](https://github.com/ratatui-org/ratatui/issues/463))
+
+- [878b6fc](https://github.com/ratatui-org/ratatui/commit/878b6fc258110b41e85833c35150d7dfcedf31ca)
+  _(uncategorized)_ Ignore benches from code coverage ([#461](https://github.com/ratatui-org/ratatui/issues/461))
+
+### Contributors
+
+Thank you so much to everyone that contributed to this release!
+
+Here is the list of contributors who have contributed to `ratatui` for the first time!
+
+- @[aatukaj](https://github.com/aatukaj)
+- @[DreadedHippy](https://github.com/DreadedHippy)
+- @[marianomarciello](https://github.com/marianomarciello)
+- @[HeeillWang](https://github.com/HeeillWang)
+- @[tz629](https://github.com/tz629)
+- @[hueblu](https://github.com/hueblu)
+
 ## [v0.23.0](https://github.com/ratatui-org/ratatui/releases/tag/v0.23.0) - 2023-08-28
 
 We are thrilled to release the new version of `ratatui` 🐭, the official successor[\*](https://github.com/fdehau/tui-rs/commit/335f5a4563342f9a4ee19e2462059e1159dcbf25) of [`tui-rs`](https://github.com/fdehau/tui-rs).

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "ratatui"
-version = "0.23.0" # crate version
+version = "0.24.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/"
@@ -18,7 +18,7 @@ exclude = [
 ]
 autoexamples = true
 edition = "2021"
-rust-version = "1.67.0"
+rust-version = "1.70.0"
 
 [badges]
 
@@ -31,14 +31,15 @@ serde = { version = "1", optional = true, features = ["derive"] }
 bitflags = "2.3"
 cassowary = "0.3"
 indoc = "2.0"
-itertools = "0.11"
+itertools = "0.12"
 paste = "1.0.2"
 strum = { version = "0.25", features = ["derive"] }
 time = { version = "0.3.11", optional = true, features = ["local-offset"] }
 unicode-segmentation = "1.10"
 unicode-width = "0.1"
 document-features = { version = "0.2.7", optional = true }
-lru = "0.11.1"
+lru = "0.12.0"
+stability = "0.1.1"
 
 [dev-dependencies]
 anyhow = "1.0.71"
@@ -89,6 +90,21 @@ widget-calendar = ["dep:time"]
 ## enables the backend code that sets the underline color.
 underline-color = ["dep:crossterm"]
 
+#! The following features are unstable and may change in the future:
+
+## Enable all unstable features.
+unstable = ["unstable-segment-size", "unstable-rendered-line-info"]
+
+## Enables the [`Layout::segment_size`](crate::layout::Layout::segment_size) method which is experimental and may change in the
+## future. See [Issue #536](https://github.com/ratatui-org/ratatui/issues/536) for more details.
+unstable-segment-size = []
+
+## Enables the [`Paragraph::line_count`](crate::widgets::Paragraph::line_count)
+## [`Paragraph::line_width`](crate::widgets::Paragraph::line_width) methods
+## which are experimental and may change in the future.
+## See [Issue 293](https://github.com/ratatui-org/ratatui/issues/293) for more details.
+unstable-rendered-line-info = []
+
 [package.metadata.docs.rs]
 all-features = true
 # see https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html
@@ -107,6 +123,9 @@ harness = false
 name = "list"
 harness = false
 
+[lib]
+bench = false
+
 [[bench]]
 name = "paragraph"
 harness = false
@@ -213,6 +232,11 @@ name = "popup"
 required-features = ["crossterm"]
 doc-scrape-examples = true
 
+[[example]]
+name = "ratatui-logo"
+required-features = ["crossterm"]
+doc-scrape-examples = true
+
 [[example]]
 name = "scrollbar"
 required-features = ["crossterm"]

Makefile.toml

@@ -11,7 +11,7 @@ ALL_FEATURES = "all-widgets,macros,serde"
 # sets of flags, one for Windows and one for other platforms.
 # Windows: --features=all-widgets,macros,serde,crossterm,termwiz,underline-color
 # Other: --features=all-widgets,macros,serde,crossterm,termion,termwiz,underline-color
-ALL_FEATURES_FLAG = { source = "${CARGO_MAKE_RUST_TARGET_OS}", default_value = "--features=all-widgets,macros,serde,crossterm,termion,termwiz", mapping = { "windows" = "--features=all-widgets,macros,serde,crossterm,termwiz" } }
+ALL_FEATURES_FLAG = { source = "${CARGO_MAKE_RUST_TARGET_OS}", default_value = "--features=all-widgets,macros,serde,crossterm,termion,termwiz,unstable", mapping = { "windows" = "--features=all-widgets,macros,serde,crossterm,termwiz,unstable" } }
 
 [tasks.default]
 alias = "ci"

README.md

@@ -21,31 +21,33 @@
 
 <!-- cargo-rdme start -->
 
-![Demo](https://raw.githubusercontent.com/ratatui-org/ratatui/aa09e59dc0058347f68d7c1e0c91f863c6f2b8c9/examples/demo2.gif)
+![Demo](https://raw.githubusercontent.com/ratatui-org/ratatui/b33c878808c4c40591d7a2d9f9d94d6fee95a96f/examples/demo2.gif)
 
 <div align="center">
 
-[![Crate Badge]](https://crates.io/crates/ratatui) [![License Badge]](./LICENSE) [![CI
-Badge]](https://github.com/ratatui-org/ratatui/actions?query=workflow%3ACI+) [![Docs
-Badge]](https://docs.rs/crate/ratatui/)<br>
-[![Dependencies Badge]](https://deps.rs/repo/github/ratatui-org/ratatui) [![Codecov
-Badge]](https://app.codecov.io/gh/ratatui-org/ratatui) [![Discord
-Badge]](https://discord.gg/pMCEU9hNEj) [![Matrix
-Badge]](https://matrix.to/#/#ratatui:matrix.org)<br>
-[Documentation](https://docs.rs/ratatui) · [Ratatui Book](https://ratatui.rs) ·
-[Examples](https://github.com/ratatui-org/ratatui/tree/main/examples) · [Report a
-bug](https://github.com/ratatui-org/ratatui/issues/new?labels=bug&projects=&template=bug_report.md)
-· [Request a
-Feature](https://github.com/ratatui-org/ratatui/issues/new?labels=enhancement&projects=&template=feature_request.md)
+[![Crate Badge]](https://crates.io/crates/ratatui)
+[![License Badge]](./LICENSE)
+[![CI Badge]](https://github.com/ratatui-org/ratatui/actions?query=workflow%3ACI+)
+[![Docs Badge]](https://docs.rs/crate/ratatui/)<br>
+[![Dependencies Badge]](https://deps.rs/repo/github/ratatui-org/ratatui)
+[![Codecov Badge]](https://app.codecov.io/gh/ratatui-org/ratatui)
+[![Discord Badge]](https://discord.gg/pMCEU9hNEj)
+[![Matrix Badge]](https://matrix.to/#/#ratatui:matrix.org)<br>
+
+[Documentation](https://docs.rs/ratatui)
+· [Ratatui Website](https://ratatui.rs)
+· [Examples](https://github.com/ratatui-org/ratatui/tree/main/examples)
+· [Report a bug](https://github.com/ratatui-org/ratatui/issues/new?labels=bug&projects=&template=bug_report.md)
+· [Request a Feature](https://github.com/ratatui-org/ratatui/issues/new?labels=enhancement&projects=&template=feature_request.md)
 · [Send a Pull Request](https://github.com/ratatui-org/ratatui/compare)
 
 </div>
 
 # Ratatui
 
-[Ratatui] is a crate for cooking up terminal user interfaces in rust. It is a lightweight
-library that provides a set of widgets and utilities to build complex rust TUIs. Ratatui was
-forked from the [Tui-rs crate] in 2023 in order to continue its development.
+[Ratatui] is a crate for cooking up terminal user interfaces in Rust. It is a lightweight
+library that provides a set of widgets and utilities to build complex Rust TUIs. Ratatui was
+forked from the [tui-rs] crate in 2023 in order to continue its development.
 
 ## Installation
 
@@ -56,7 +58,7 @@ cargo add ratatui crossterm
 ```
 
 Ratatui uses [Crossterm] by default as it works on most platforms. See the [Installation]
-section of the [Ratatui Book] for more details on how to use other backends ([Termion] /
+section of the [Ratatui Website] for more details on how to use other backends ([Termion] /
 [Termwiz]).
 
 ## Introduction
@@ -64,12 +66,12 @@ section of the [Ratatui Book] for more details on how to use other backends ([Te
 Ratatui is based on the principle of immediate rendering with intermediate buffers. This means
 that for each frame, your app must render all widgets that are supposed to be part of the UI.
 This is in contrast to the retained mode style of rendering where widgets are updated and then
-automatically redrawn on the next frame. See the [Rendering] section of the [Ratatui Book] for
+automatically redrawn on the next frame. See the [Rendering] section of the [Ratatui Website] for
 more info.
 
 ## Other documentation
 
-- [Ratatui Book] - explains the library's concepts and provides step-by-step tutorials
+- [Ratatui Website] - explains the library's concepts and provides step-by-step tutorials
 - [Examples] - a collection of examples that demonstrate how to use the library.
 - [API Documentation] - the full API documentation for the library on docs.rs.
 - [Changelog] - generated by [git-cliff] utilizing [Conventional Commits].
@@ -81,12 +83,11 @@ more info.
 The following example demonstrates the minimal amount of code necessary to setup a terminal and
 render "Hello World!". The full code for this example which contains a little more detail is in
 [hello_world.rs]. For more guidance on different ways to structure your application see the
-[Application Patterns] and [Hello World tutorial] sections in the [Ratatui Book] and the various
+[Application Patterns] and [Hello World tutorial] sections in the [Ratatui Website] and the various
 [Examples]. There are also several starter templates available:
 
-- [rust-tui-template]
-- [ratatui-async-template] (book and template)
-- [simple-tui-rs]
+- [template]
+- [async-template] (book and template)
 
 Every application built with `ratatui` needs to implement the following steps:
 
@@ -110,20 +111,20 @@ implements the [`Backend`] trait which has implementations for [Crossterm], [Ter
 
 Most applications should enter the Alternate Screen when starting and leave it when exiting and
 also enable raw mode to disable line buffering and enable reading key events. See the [`backend`
-module] and the [Backends] section of the [Ratatui Book] for more info.
+module] and the [Backends] section of the [Ratatui Website] for more info.
 
 ### Drawing the UI
 
 The drawing logic is delegated to a closure that takes a [`Frame`] instance as argument. The
 [`Frame`] provides the size of the area to draw to and allows the app to render any [`Widget`]
-using the provided [`render_widget`] method. See the [Widgets] section of the [Ratatui Book] for
+using the provided [`render_widget`] method. See the [Widgets] section of the [Ratatui Website] for
 more info.
 
 ### Handling events
 
 Ratatui does not include any input handling. Instead event handling can be implemented by
 calling backend library methods directly. See the [Handling Events] section of the [Ratatui
-Book] for more info. For example, if you are using [Crossterm], you can use the
+Website] for more info. For example, if you are using [Crossterm], you can use the
 [`crossterm::event`] module to handle events.
 
 ### Example
@@ -182,20 +183,21 @@ Running this example produces the following output:
 The library comes with a basic yet useful layout management object called [`Layout`] which
 allows you to split the available space into multiple areas and then render widgets in each
 area. This lets you describe a responsive terminal UI by nesting layouts. See the [Layout]
-section of the [Ratatui Book] for more info.
+section of the [Ratatui Website] for more info.
 
 ```rust
 use ratatui::{prelude::*, widgets::*};
 
 fn ui(frame: &mut Frame) {
-    let main_layout = Layout::default()
-        .direction(Direction::Vertical)
-        .constraints([
+    let main_layout = Layout::new(
+        Direction::Vertical,
+        [
             Constraint::Length(1),
             Constraint::Min(0),
             Constraint::Length(1),
-        ])
-        .split(frame.size());
+        ]
+    )
+    .split(frame.size());
     frame.render_widget(
         Block::new().borders(Borders::TOP).title("Title Bar"),
         main_layout[0],
@@ -205,10 +207,11 @@ fn ui(frame: &mut Frame) {
         main_layout[2],
     );
 
-    let inner_layout = Layout::default()
-        .direction(Direction::Horizontal)
-        .constraints([Constraint::Percentage(50), Constraint::Percentage(50)])
-        .split(main_layout[1]);
+    let inner_layout = Layout::new(
+        Direction::Horizontal,
+        [Constraint::Percentage(50), Constraint::Percentage(50)]
+    )
+    .split(main_layout[1]);
     frame.render_widget(
         Block::default().borders(Borders::ALL).title("Left"),
         inner_layout[0],
@@ -234,22 +237,23 @@ The [`style` module] provides types that represent the various styling options.
 important one is [`Style`] which represents the foreground and background colors and the text
 attributes of a [`Span`]. The [`style` module] also provides a [`Stylize`] trait that allows
 short-hand syntax to apply a style to widgets and text. See the [Styling Text] section of the
-[Ratatui Book] for more info.
+[Ratatui Website] for more info.
 
 ```rust
 use ratatui::{prelude::*, widgets::*};
 
 fn ui(frame: &mut Frame) {
-    let areas = Layout::default()
-        .direction(Direction::Vertical)
-        .constraints([
+    let areas = Layout::new(
+        Direction::Vertical,
+        [
             Constraint::Length(1),
             Constraint::Length(1),
             Constraint::Length(1),
             Constraint::Length(1),
             Constraint::Min(0),
-        ])
-        .split(frame.size());
+        ]
+    )
+    .split(frame.size());
 
     let span1 = Span::raw("Hello ");
     let span2 = Span::styled(
@@ -285,21 +289,20 @@ Running this example produces the following output:
 
 ![docsrs-styling]
 
-[Ratatui Book]: https://ratatui.rs
-[Installation]: https://ratatui.rs/installation.html
-[Rendering]: https://ratatui.rs/concepts/rendering/index.html
-[Application Patterns]: https://ratatui.rs/concepts/application_patterns/index.html
-[Hello World tutorial]: https://ratatui.rs/tutorial/hello_world.html
-[Backends]: https://ratatui.rs/concepts/backends/index.html
-[Widgets]: https://ratatui.rs/how-to/widgets/index.html
-[Handling Events]: https://ratatui.rs/concepts/event_handling.html
-[Layout]: https://ratatui.rs/how-to/layout/index.html
-[Styling Text]: https://ratatui.rs/how-to/render/style-text.html
-[rust-tui-template]: https://github.com/ratatui-org/rust-tui-template
-[ratatui-async-template]: https://ratatui-org.github.io/ratatui-async-template/
-[simple-tui-rs]: https://github.com/pmsanford/simple-tui-rs
+[Ratatui Website]: https://ratatui.rs/
+[Installation]: https://ratatui.rs/installation/
+[Rendering]: https://ratatui.rs/concepts/rendering/
+[Application Patterns]: https://ratatui.rs/concepts/application-patterns/
+[Hello World tutorial]: https://ratatui.rs/tutorials/hello-world/
+[Backends]: https://ratatui.rs/concepts/backends/
+[Widgets]: https://ratatui.rs/how-to/widgets/
+[Handling Events]: https://ratatui.rs/concepts/event-handling/
+[Layout]: https://ratatui.rs/how-to/layout/
+[Styling Text]: https://ratatui.rs/how-to/render/style-text/
+[template]: https://github.com/ratatui-org/template
+[async-template]: https://ratatui-org.github.io/async-template
 [Examples]: https://github.com/ratatui-org/ratatui/tree/main/examples
-[git-cliff]: https://github.com/orhun/git-cliff
+[git-cliff]: https://git-cliff.org
 [Conventional Commits]: https://www.conventionalcommits.org
 [API Documentation]: https://docs.rs/ratatui
 [Changelog]: https://github.com/ratatui-org/ratatui/blob/main/CHANGELOG.md
@@ -325,7 +328,7 @@ Running this example produces the following output:
 [Crossterm]: https://crates.io/crates/crossterm
 [Termion]: https://crates.io/crates/termion
 [Termwiz]: https://crates.io/crates/termwiz
-[Tui-rs crate]: https://crates.io/crates/tui
+[tui-rs]: https://crates.io/crates/tui
 [hello_world.rs]: https://github.com/ratatui-org/ratatui/blob/main/examples/hello_world.rs
 [Crate Badge]: https://img.shields.io/crates/v/ratatui?logo=rust&style=flat-square
 [CI Badge]:
@@ -402,7 +405,6 @@ be installed with `cargo install cargo-make`).
   `ratatui::style::Color`
 - [rust-tui-template](https://github.com/ratatui-org/rust-tui-template) — A template for
   bootstrapping a Rust TUI application with Tui-rs & crossterm
-- [simple-tui-rs](https://github.com/pmsanford/simple-tui-rs) — A simple example tui-rs app
 - [tui-builder](https://github.com/jkelleyrtp/tui-builder) — Batteries-included MVC framework for
   Tui-rs + Crossterm apps
 - [tui-clap](https://github.com/kegesch/tui-clap-rs) — Use clap-rs together with Tui-rs
@@ -425,8 +427,8 @@ be installed with `cargo install cargo-make`).
 
 ## Apps
 
-Check out the list of more than 50 [Apps using
-`Ratatui`](https://github.com/ratatui-org/ratatui/wiki/Apps-using-Ratatui)!
+Check out [awesome-ratatui](https://github.com/ratatui-org/awesome-ratatui) for a curated list of
+awesome apps/libraries built with `ratatui`!
 
 ## Alternatives
 

RELEASE.md

@@ -17,7 +17,6 @@ actions](.github/workflows/cd.yml) and triggered by pushing a tag.
    Avoid adding the gif to the git repo as binary files tend to bloat repositories.
 
 1. Bump the version in [Cargo.toml](Cargo.toml).
-1. Bump versions in the doc comments of [lib.rs](src/lib.rs).
 1. Ensure [CHANGELOG.md](CHANGELOG.md) is updated. [git-cliff](https://github.com/orhun/git-cliff)
    can be used for generating the entries.
 1. Ensure that any breaking changes are documented in [BREAKING-CHANGES.md](./BREAKING-CHANGES.md)

SECURITY.md

@@ -0,0 +1,9 @@
+# Security Policy
+
+## Supported Versions
+
+We only support the latest version of this crate.
+
+## Reporting a Vulnerability
+
+To report secuirity vulnerability, please use the form at https://github.com/ratatui-org/ratatui/security/advisories/new

cliff.toml

@@ -80,6 +80,8 @@ commit_parsers = [
   { message = "^chore\\(release\\): prepare for", skip = true },
   { message = "^chore\\(pr\\)", skip = true },
   { message = "^chore\\(pull\\)", skip = true },
+  { message = "^chore\\(deps\\)", skip = true },
+  { message = "^chore\\(changelog\\)", skip = true },
   { message = "^[cC]hore", group = "<!-- 07 -->Miscellaneous Tasks" },
   { body = ".*security", group = "<!-- 08 -->Security" },
   { message = "^build", group = "<!-- 09 -->Build" },

codecov.yml

@@ -1,3 +1,14 @@
+coverage: # https://docs.codecov.com/docs/codecovyml-reference#coverage
+  precision: 1 # e.g. 89.1%
+  round: down
+  range: 85..100 # https://docs.codecov.com/docs/coverage-configuration#section-range
+  status: # https://docs.codecov.com/docs/commit-status
+    project:
+      default:
+        threshold: 1% # Avoid false negatives
 ignore:
   - "examples"
   - "benches"
+comment: # https://docs.codecov.com/docs/pull-request-comments
+  # make the comments less noisy
+  require_changes: true

examples/README.md

@@ -9,7 +9,7 @@ images themselves are stored in a separate git branch to avoid bloating the main
 This is the demo example from the main README and crate page. Source: [demo2](./demo2/).
 
 ```shell
-cargo run --example=demo2 --features=crossterm
+cargo run --example=demo2 --features="crossterm widget-calendar"
 ```
 
 ![Demo2][demo2.gif]
@@ -223,6 +223,18 @@ cargo run --example=popup --features=crossterm
 
 ![Popup][popup.gif]
 
+## Ratatui-logo
+
+A fun example of using half blocks to render graphics Source:
+[ratatui-logo.rs](./ratatui-logo.rs).
+
+>
+```shell
+cargo run --example=ratatui-logo --features=crossterm
+```
+
+![Ratatui Logo][ratatui-logo.gif]
+
 ## Scrollbar
 
 Demonstrates the [`Scrollbar`](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Scrollbar.html)
@@ -309,6 +321,7 @@ examples/generate.bash
 [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
 [popup.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/popup.gif?raw=true
+[ratatui-logo.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/ratatui-logo.gif?raw=true
 [scrollbar.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/scrollbar.gif?raw=true
 [sparkline.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/sparkline.gif?raw=true
 [table.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/table.gif?raw=true

examples/canvas.rs

@@ -59,10 +59,10 @@ impl App {
                 if let Event::Key(key) = event::read()? {
                     match key.code {
                         KeyCode::Char('q') => break,
-                        KeyCode::Down => app.y += 1.0,
-                        KeyCode::Up => app.y -= 1.0,
-                        KeyCode::Right => app.x += 1.0,
-                        KeyCode::Left => app.x -= 1.0,
+                        KeyCode::Down | KeyCode::Char('j') => app.y += 1.0,
+                        KeyCode::Up | KeyCode::Char('k') => app.y -= 1.0,
+                        KeyCode::Right | KeyCode::Char('l') => app.x += 1.0,
+                        KeyCode::Left | KeyCode::Char('h') => app.x -= 1.0,
                         _ => {}
                     }
                 }

examples/chart.rs

@@ -221,7 +221,8 @@ fn ui(f: &mut Frame, app: &App) {
                 .style(Style::default().fg(Color::Gray))
                 .bounds([0.0, 5.0])
                 .labels(vec!["0".bold(), "2.5".into(), "5.0".bold()]),
-        );
+        )
+        .hidden_legend_constraints((Constraint::Ratio(1, 2), Constraint::Ratio(1, 2)));
     f.render_widget(chart, chunks[1]);
 
     let datasets = vec![Dataset::default()
@@ -249,6 +250,8 @@ fn ui(f: &mut Frame, app: &App) {
                 .style(Style::default().fg(Color::Gray))
                 .bounds([0.0, 5.0])
                 .labels(vec!["0".bold(), "2.5".into(), "5".bold()]),
-        );
+        )
+        .legend_position(Some(LegendPosition::TopLeft))
+        .hidden_legend_constraints((Constraint::Ratio(1, 2), Constraint::Ratio(1, 2)));
     f.render_widget(chart, chunks[2]);
 }

examples/custom_widget.rs

@@ -216,12 +216,12 @@ fn handle_key_event(
 ) -> ControlFlow<()> {
     match key.code {
         KeyCode::Char('q') => return ControlFlow::Break(()),
-        KeyCode::Left => {
+        KeyCode::Left | KeyCode::Char('h') => {
             button_states[*selected_button] = State::Normal;
             *selected_button = selected_button.saturating_sub(1);
             button_states[*selected_button] = State::Selected;
         }
-        KeyCode::Right => {
+        KeyCode::Right | KeyCode::Char('l') => {
             button_states[*selected_button] = State::Normal;
             *selected_button = selected_button.saturating_add(1).min(2);
             button_states[*selected_button] = State::Selected;

examples/demo/crossterm.rs

@@ -55,11 +55,11 @@ fn run_app<B: Backend>(
             if let Event::Key(key) = event::read()? {
                 if key.kind == KeyEventKind::Press {
                     match key.code {
+                        KeyCode::Left | KeyCode::Char('h') => app.on_left(),
+                        KeyCode::Up | KeyCode::Char('k') => app.on_up(),
+                        KeyCode::Right | KeyCode::Char('l') => app.on_right(),
+                        KeyCode::Down | KeyCode::Char('j') => app.on_down(),
                         KeyCode::Char(c) => app.on_key(c),
-                        KeyCode::Left => app.on_left(),
-                        KeyCode::Up => app.on_up(),
-                        KeyCode::Right => app.on_right(),
-                        KeyCode::Down => app.on_down(),
                         _ => {}
                     }
                 }

examples/demo/termion.rs

@@ -39,11 +39,11 @@ fn run_app<B: Backend>(
 
         match events.recv()? {
             Event::Input(key) => match key {
+                Key::Up | Key::Char('k') => app.on_up(),
+                Key::Down | Key::Char('j') => app.on_down(),
+                Key::Left | Key::Char('h') => app.on_left(),
+                Key::Right | Key::Char('l') => app.on_right(),
                 Key::Char(c) => app.on_key(c),
-                Key::Up => app.on_up(),
-                Key::Down => app.on_down(),
-                Key::Left => app.on_left(),
-                Key::Right => app.on_right(),
                 _ => {}
             },
             Event::Tick => app.on_tick(),

examples/demo/termwiz.rs

@@ -45,10 +45,10 @@ fn run_app(
         {
             match input {
                 InputEvent::Key(key_code) => match key_code.key {
-                    KeyCode::UpArrow => app.on_up(),
-                    KeyCode::DownArrow => app.on_down(),
-                    KeyCode::LeftArrow => app.on_left(),
-                    KeyCode::RightArrow => app.on_right(),
+                    KeyCode::UpArrow | KeyCode::Char('k') => app.on_up(),
+                    KeyCode::DownArrow | KeyCode::Char('j') => app.on_down(),
+                    KeyCode::LeftArrow | KeyCode::Char('h') => app.on_left(),
+                    KeyCode::RightArrow | KeyCode::Char('l') => app.on_right(),
                     KeyCode::Char(c) => app.on_key(c),
                     _ => {}
                 },

examples/demo/ui.rs

@@ -289,18 +289,20 @@ fn draw_second_tab(f: &mut Frame, app: &mut App, area: Rect) {
         };
         Row::new(vec![s.name, s.location, s.status]).style(style)
     });
-    let table = Table::new(rows)
-        .header(
-            Row::new(vec!["Server", "Location", "Status"])
-                .style(Style::default().fg(Color::Yellow))
-                .bottom_margin(1),
-        )
-        .block(Block::default().title("Servers").borders(Borders::ALL))
-        .widths(&[
+    let table = Table::new(
+        rows,
+        [
             Constraint::Length(15),
             Constraint::Length(15),
             Constraint::Length(10),
-        ]);
+        ],
+    )
+    .header(
+        Row::new(vec!["Server", "Location", "Status"])
+            .style(Style::default().fg(Color::Yellow))
+            .bottom_margin(1),
+    )
+    .block(Block::default().title("Servers").borders(Borders::ALL));
     f.render_widget(table, chunks[0]);
 
     let map = Canvas::default()
@@ -393,12 +395,14 @@ fn draw_third_tab(f: &mut Frame, _app: &mut App, area: Rect) {
             Row::new(cells)
         })
         .collect();
-    let table = Table::new(items)
-        .block(Block::default().title("Colors").borders(Borders::ALL))
-        .widths(&[
+    let table = Table::new(
+        items,
+        [
             Constraint::Ratio(1, 3),
             Constraint::Ratio(1, 3),
             Constraint::Ratio(1, 3),
-        ]);
+        ],
+    )
+    .block(Block::default().title("Colors").borders(Borders::ALL));
     f.render_widget(table, chunks[0]);
 }

examples/demo2/tabs/recipe.rs

@@ -146,10 +146,9 @@ fn render_ingredients(selected_row: usize, area: Rect, buf: &mut Buffer) {
     let rows = INGREDIENTS.iter().map(|&i| i.into()).collect_vec();
     let theme = THEME.recipe;
     StatefulWidget::render(
-        Table::new(rows)
+        Table::new(rows, [Constraint::Length(7), Constraint::Length(30)])
             .block(Block::new().style(theme.ingredients))
             .header(Row::new(vec!["Qty", "Ingredient"]).style(theme.ingredients_header))
-            .widths(&[Constraint::Length(7), Constraint::Length(30)])
             .highlight_style(Style::new().light_yellow()),
         area,
         buf,

examples/demo2/tabs/traceroute.rs

@@ -50,9 +50,8 @@ fn render_hops(selected_row: usize, area: Rect, buf: &mut Buffer) {
         .title_alignment(Alignment::Center)
         .padding(Padding::new(1, 1, 1, 1));
     StatefulWidget::render(
-        Table::new(rows)
+        Table::new(rows, [Constraint::Max(100), Constraint::Length(15)])
             .header(Row::new(vec!["Host", "Address"]).set_style(THEME.traceroute.header))
-            .widths(&[Constraint::Max(100), Constraint::Length(15)])
             .highlight_style(THEME.traceroute.selected)
             .block(block),
         area,

examples/list.rs

@@ -181,9 +181,9 @@ fn run_app<B: Backend>(
                 if key.kind == KeyEventKind::Press {
                     match key.code {
                         KeyCode::Char('q') => return Ok(()),
-                        KeyCode::Left => app.items.unselect(),
-                        KeyCode::Down => app.items.next(),
-                        KeyCode::Up => app.items.previous(),
+                        KeyCode::Left | KeyCode::Char('h') => app.items.unselect(),
+                        KeyCode::Down | KeyCode::Char('j') => app.items.next(),
+                        KeyCode::Up | KeyCode::Char('k') => app.items.previous(),
                         _ => {}
                     }
                 }
@@ -273,6 +273,6 @@ fn ui(f: &mut Frame, app: &mut App) {
         .collect();
     let events_list = List::new(events)
         .block(Block::default().borders(Borders::ALL).title("List"))
-        .start_corner(Corner::BottomLeft);
+        .direction(ListDirection::BottomToTop);
     f.render_widget(events_list, chunks[1]);
 }

examples/ratatui-logo.rs

@@ -0,0 +1,71 @@
+use std::{
+    io::{self, stdout},
+    thread::sleep,
+    time::Duration,
+};
+
+use crossterm::terminal::{disable_raw_mode, enable_raw_mode};
+use indoc::indoc;
+use itertools::izip;
+use ratatui::{prelude::*, widgets::*};
+
+/// A fun example of using half block characters to draw a logo
+fn main() -> io::Result<()> {
+    let r = indoc! {"
+            ▄▄▄
+            █▄▄▀
+            █  █
+        "}
+    .lines();
+    let a = indoc! {"
+             ▄▄
+            █▄▄█
+            █  █
+        "}
+    .lines();
+    let t = indoc! {"
+            ▄▄▄
+             █
+             █
+        "}
+    .lines();
+    let u = indoc! {"
+            ▄  ▄
+            █  █
+            ▀▄▄▀
+        "}
+    .lines();
+    let i = indoc! {"
+            ▄
+            █
+            █
+        "}
+    .lines();
+    let mut terminal = init()?;
+    terminal.draw(|frame| {
+        let logo = izip!(r, a.clone(), t.clone(), a, t, u, i)
+            .map(|(r, a, t, a2, t2, u, i)| {
+                format!("{:5}{:5}{:4}{:5}{:4}{:5}{:5}", r, a, t, a2, t2, u, i)
+            })
+            .collect::<Vec<_>>()
+            .join("\n");
+        frame.render_widget(Paragraph::new(logo), frame.size());
+    })?;
+    sleep(Duration::from_secs(5));
+    restore()?;
+    println!();
+    Ok(())
+}
+
+pub fn init() -> io::Result<Terminal<impl Backend>> {
+    enable_raw_mode()?;
+    let options = TerminalOptions {
+        viewport: Viewport::Inline(3),
+    };
+    Terminal::with_options(CrosstermBackend::new(stdout()), options)
+}
+
+pub fn restore() -> io::Result<()> {
+    disable_raw_mode()?;
+    Ok(())
+}

examples/ratatui-logo.tape

@@ -0,0 +1,12 @@
+# 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`
+Output "target/ratatui-logo.gif"
+Set Theme "Aardvark Blue"
+Set Width 550
+Set Height 220
+Hide
+Type "cargo run --example=ratatui-logo --features=crossterm"
+Enter
+Sleep 2s
+Show
+Sleep 2s

examples/table.rs

@@ -104,8 +104,8 @@ fn run_app<B: Backend>(terminal: &mut Terminal<B>, mut app: App) -> io::Result<(
             if key.kind == KeyEventKind::Press {
                 match key.code {
                     KeyCode::Char('q') => return Ok(()),
-                    KeyCode::Down => app.next(),
-                    KeyCode::Up => app.previous(),
+                    KeyCode::Down | KeyCode::Char('j') => app.next(),
+                    KeyCode::Up | KeyCode::Char('k') => app.previous(),
                     _ => {}
                 }
             }
@@ -137,15 +137,17 @@ fn ui(f: &mut Frame, app: &mut App) {
         let cells = item.iter().map(|c| Cell::from(*c));
         Row::new(cells).height(height as u16).bottom_margin(1)
     });
-    let t = Table::new(rows)
-        .header(header)
-        .block(Block::default().borders(Borders::ALL).title("Table"))
-        .highlight_style(selected_style)
-        .highlight_symbol(">> ")
-        .widths(&[
+    let t = Table::new(
+        rows,
+        [
             Constraint::Percentage(50),
             Constraint::Max(30),
             Constraint::Min(10),
-        ]);
+        ],
+    )
+    .header(header)
+    .block(Block::default().borders(Borders::ALL).title("Table"))
+    .highlight_style(selected_style)
+    .highlight_symbol(">> ");
     f.render_stateful_widget(t, rects[0], &mut app.state);
 }

examples/tabs.rs

@@ -69,8 +69,8 @@ fn run_app<B: Backend>(terminal: &mut Terminal<B>, mut app: App) -> io::Result<(
             if key.kind == KeyEventKind::Press {
                 match key.code {
                     KeyCode::Char('q') => return Ok(()),
-                    KeyCode::Right => app.next(),
-                    KeyCode::Left => app.previous(),
+                    KeyCode::Right | KeyCode::Char('l') => app.next(),
+                    KeyCode::Left | KeyCode::Char('h') => app.previous(),
                     _ => {}
                 }
             }

src/backend.rs

@@ -11,7 +11,7 @@
 //!
 //! Additionally, a [`TestBackend`] is provided for testing purposes.
 //!
-//! See the [Backend Comparison] section of the [Ratatui Book] for more details on the different
+//! See the [Backend Comparison] section of the [Ratatui Website] for more details on the different
 //! backends.
 //!
 //! Each backend supports a number of features, such as [raw mode](#raw-mode), [alternate
@@ -98,7 +98,7 @@
 //! [examples]: https://github.com/ratatui-org/ratatui/tree/main/examples#readme
 //! [Backend Comparison]:
 //!     https://ratatui-org.github.io/ratatui-book/concepts/backends/comparison.html
-//! [Ratatui Book]: https://ratatui-org.github.io/ratatui-book
+//! [Ratatui Website]: https://ratatui-org.github.io/ratatui-book
 use std::io;
 
 use strum::{Display, EnumString};
@@ -140,6 +140,7 @@ pub enum ClearType {
 }
 
 /// The window size in characters (columns / rows) as well as pixels.
+#[derive(Debug, Clone, Copy, Eq, PartialEq, Hash)]
 pub struct WindowSize {
     /// Size of the window in characters (columns / rows).
     pub columns_rows: Size,
@@ -227,7 +228,7 @@ pub trait Backend {
     /// [`get_cursor`]: Backend::get_cursor
     fn set_cursor(&mut self, x: u16, y: u16) -> io::Result<()>;
 
-    /// Clears the whole terminal scree
+    /// Clears the whole terminal screen
     ///
     /// # Example
     ///

src/backend/crossterm.rs

@@ -10,8 +10,8 @@ use crossterm::{
     cursor::{Hide, MoveTo, Show},
     execute, queue,
     style::{
-        Attribute as CAttribute, Color as CColor, Print, SetAttribute, SetBackgroundColor,
-        SetForegroundColor,
+        Attribute as CAttribute, Attributes as CAttributes, Color as CColor, ContentStyle, Print,
+        SetAttribute, SetBackgroundColor, SetForegroundColor,
     },
     terminal::{self, Clear},
 };
@@ -21,7 +21,7 @@ use crate::{
     buffer::Cell,
     layout::Size,
     prelude::Rect,
-    style::{Color, Modifier},
+    style::{Color, Modifier, Style},
 };
 
 /// A [`Backend`] implementation that uses [Crossterm] to render to the terminal.
@@ -161,7 +161,7 @@ where
                 underline_color = cell.underline_color;
             }
 
-            queue!(self.writer, Print(&cell.symbol))?;
+            queue!(self.writer, Print(cell.symbol()))?;
         }
 
         #[cfg(feature = "underline-color")]
@@ -274,6 +274,32 @@ impl From<Color> for CColor {
     }
 }
 
+impl From<CColor> for Color {
+    fn from(value: CColor) -> Self {
+        match value {
+            CColor::Reset => Self::Reset,
+            CColor::Black => Self::Black,
+            CColor::DarkRed => Self::Red,
+            CColor::DarkGreen => Self::Green,
+            CColor::DarkYellow => Self::Yellow,
+            CColor::DarkBlue => Self::Blue,
+            CColor::DarkMagenta => Self::Magenta,
+            CColor::DarkCyan => Self::Cyan,
+            CColor::Grey => Self::Gray,
+            CColor::DarkGrey => Self::DarkGray,
+            CColor::Red => Self::LightRed,
+            CColor::Green => Self::LightGreen,
+            CColor::Blue => Self::LightBlue,
+            CColor::Yellow => Self::LightYellow,
+            CColor::Magenta => Self::LightMagenta,
+            CColor::Cyan => Self::LightCyan,
+            CColor::White => Self::White,
+            CColor::Rgb { r, g, b } => Self::Rgb(r, g, b),
+            CColor::AnsiValue(v) => Self::Indexed(v),
+        }
+    }
+}
+
 /// The `ModifierDiff` struct is used to calculate the difference between two `Modifier`
 /// values. This is useful when updating the terminal display, as it allows for more
 /// efficient updates by only sending the necessary changes.
@@ -344,3 +370,303 @@ impl ModifierDiff {
         Ok(())
     }
 }
+
+impl From<CAttribute> for Modifier {
+    fn from(value: CAttribute) -> Self {
+        // `Attribute*s*` (note the *s*) contains multiple `Attribute`
+        // We convert `Attribute` to `Attribute*s*` (containing only 1 value) to avoid implementing
+        // the conversion again
+        Modifier::from(CAttributes::from(value))
+    }
+}
+
+impl From<CAttributes> for Modifier {
+    fn from(value: CAttributes) -> Self {
+        let mut res = Modifier::empty();
+
+        if value.has(CAttribute::Bold) {
+            res |= Modifier::BOLD;
+        }
+        if value.has(CAttribute::Dim) {
+            res |= Modifier::DIM;
+        }
+        if value.has(CAttribute::Italic) {
+            res |= Modifier::ITALIC;
+        }
+        if value.has(CAttribute::Underlined)
+            || value.has(CAttribute::DoubleUnderlined)
+            || value.has(CAttribute::Undercurled)
+            || value.has(CAttribute::Underdotted)
+            || value.has(CAttribute::Underdashed)
+        {
+            res |= Modifier::UNDERLINED;
+        }
+        if value.has(CAttribute::SlowBlink) {
+            res |= Modifier::SLOW_BLINK;
+        }
+        if value.has(CAttribute::RapidBlink) {
+            res |= Modifier::RAPID_BLINK;
+        }
+        if value.has(CAttribute::Reverse) {
+            res |= Modifier::REVERSED;
+        }
+        if value.has(CAttribute::Hidden) {
+            res |= Modifier::HIDDEN;
+        }
+        if value.has(CAttribute::CrossedOut) {
+            res |= Modifier::CROSSED_OUT;
+        }
+
+        res
+    }
+}
+
+impl From<ContentStyle> for Style {
+    fn from(value: ContentStyle) -> Self {
+        let mut sub_modifier = Modifier::empty();
+
+        if value.attributes.has(CAttribute::NoBold) {
+            sub_modifier |= Modifier::BOLD;
+        }
+        if value.attributes.has(CAttribute::NoItalic) {
+            sub_modifier |= Modifier::ITALIC;
+        }
+        if value.attributes.has(CAttribute::NotCrossedOut) {
+            sub_modifier |= Modifier::CROSSED_OUT;
+        }
+        if value.attributes.has(CAttribute::NoUnderline) {
+            sub_modifier |= Modifier::UNDERLINED;
+        }
+        if value.attributes.has(CAttribute::NoHidden) {
+            sub_modifier |= Modifier::HIDDEN;
+        }
+        if value.attributes.has(CAttribute::NoBlink) {
+            sub_modifier |= Modifier::RAPID_BLINK | Modifier::SLOW_BLINK;
+        }
+        if value.attributes.has(CAttribute::NoReverse) {
+            sub_modifier |= Modifier::REVERSED;
+        }
+
+        Self {
+            fg: value.foreground_color.map(|c| c.into()),
+            bg: value.background_color.map(|c| c.into()),
+            #[cfg(feature = "underline-color")]
+            underline_color: value.underline_color.map(|c| c.into()),
+            add_modifier: value.attributes.into(),
+            sub_modifier,
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn from_crossterm_color() {
+        assert_eq!(Color::from(CColor::Reset), Color::Reset);
+        assert_eq!(Color::from(CColor::Black), Color::Black);
+        assert_eq!(Color::from(CColor::DarkGrey), Color::DarkGray);
+        assert_eq!(Color::from(CColor::Red), Color::LightRed);
+        assert_eq!(Color::from(CColor::DarkRed), Color::Red);
+        assert_eq!(Color::from(CColor::Green), Color::LightGreen);
+        assert_eq!(Color::from(CColor::DarkGreen), Color::Green);
+        assert_eq!(Color::from(CColor::Yellow), Color::LightYellow);
+        assert_eq!(Color::from(CColor::DarkYellow), Color::Yellow);
+        assert_eq!(Color::from(CColor::Blue), Color::LightBlue);
+        assert_eq!(Color::from(CColor::DarkBlue), Color::Blue);
+        assert_eq!(Color::from(CColor::Magenta), Color::LightMagenta);
+        assert_eq!(Color::from(CColor::DarkMagenta), Color::Magenta);
+        assert_eq!(Color::from(CColor::Cyan), Color::LightCyan);
+        assert_eq!(Color::from(CColor::DarkCyan), Color::Cyan);
+        assert_eq!(Color::from(CColor::White), Color::White);
+        assert_eq!(Color::from(CColor::Grey), Color::Gray);
+        assert_eq!(
+            Color::from(CColor::Rgb { r: 0, g: 0, b: 0 }),
+            Color::Rgb(0, 0, 0)
+        );
+        assert_eq!(
+            Color::from(CColor::Rgb {
+                r: 10,
+                g: 20,
+                b: 30
+            }),
+            Color::Rgb(10, 20, 30)
+        );
+        assert_eq!(Color::from(CColor::AnsiValue(32)), Color::Indexed(32));
+        assert_eq!(Color::from(CColor::AnsiValue(37)), Color::Indexed(37));
+    }
+
+    mod modifier {
+        use super::*;
+
+        #[test]
+        fn from_crossterm_attribute() {
+            assert_eq!(Modifier::from(CAttribute::Reset), Modifier::empty());
+            assert_eq!(Modifier::from(CAttribute::Bold), Modifier::BOLD);
+            assert_eq!(Modifier::from(CAttribute::Italic), Modifier::ITALIC);
+            assert_eq!(Modifier::from(CAttribute::Underlined), Modifier::UNDERLINED);
+            assert_eq!(
+                Modifier::from(CAttribute::DoubleUnderlined),
+                Modifier::UNDERLINED
+            );
+            assert_eq!(
+                Modifier::from(CAttribute::Underdotted),
+                Modifier::UNDERLINED
+            );
+            assert_eq!(Modifier::from(CAttribute::Dim), Modifier::DIM);
+            assert_eq!(
+                Modifier::from(CAttribute::NormalIntensity),
+                Modifier::empty()
+            );
+            assert_eq!(
+                Modifier::from(CAttribute::CrossedOut),
+                Modifier::CROSSED_OUT
+            );
+            assert_eq!(Modifier::from(CAttribute::NoUnderline), Modifier::empty());
+            assert_eq!(Modifier::from(CAttribute::OverLined), Modifier::empty());
+            assert_eq!(Modifier::from(CAttribute::SlowBlink), Modifier::SLOW_BLINK);
+            assert_eq!(
+                Modifier::from(CAttribute::RapidBlink),
+                Modifier::RAPID_BLINK
+            );
+            assert_eq!(Modifier::from(CAttribute::Hidden), Modifier::HIDDEN);
+            assert_eq!(Modifier::from(CAttribute::NoHidden), Modifier::empty());
+            assert_eq!(Modifier::from(CAttribute::Reverse), Modifier::REVERSED);
+        }
+
+        #[test]
+        fn from_crossterm_attributes() {
+            assert_eq!(
+                Modifier::from(CAttributes::from(CAttribute::Bold)),
+                Modifier::BOLD
+            );
+            assert_eq!(
+                Modifier::from(CAttributes::from(
+                    [CAttribute::Bold, CAttribute::Italic].as_ref()
+                )),
+                Modifier::BOLD | Modifier::ITALIC
+            );
+            assert_eq!(
+                Modifier::from(CAttributes::from(
+                    [CAttribute::Bold, CAttribute::NotCrossedOut].as_ref()
+                )),
+                Modifier::BOLD
+            );
+            assert_eq!(
+                Modifier::from(CAttributes::from(
+                    [CAttribute::Dim, CAttribute::Underdotted].as_ref()
+                )),
+                Modifier::DIM | Modifier::UNDERLINED
+            );
+            assert_eq!(
+                Modifier::from(CAttributes::from(
+                    [CAttribute::Dim, CAttribute::SlowBlink, CAttribute::Italic].as_ref()
+                )),
+                Modifier::DIM | Modifier::SLOW_BLINK | Modifier::ITALIC
+            );
+            assert_eq!(
+                Modifier::from(CAttributes::from(
+                    [
+                        CAttribute::Hidden,
+                        CAttribute::NoUnderline,
+                        CAttribute::NotCrossedOut
+                    ]
+                    .as_ref()
+                )),
+                Modifier::HIDDEN
+            );
+            assert_eq!(
+                Modifier::from(CAttributes::from(CAttribute::Reverse)),
+                Modifier::REVERSED
+            );
+            assert_eq!(
+                Modifier::from(CAttributes::from(CAttribute::Reset)),
+                Modifier::empty()
+            );
+            assert_eq!(
+                Modifier::from(CAttributes::from(
+                    [CAttribute::RapidBlink, CAttribute::CrossedOut].as_ref()
+                )),
+                Modifier::RAPID_BLINK | Modifier::CROSSED_OUT
+            );
+        }
+    }
+
+    #[test]
+    fn from_crossterm_content_style() {
+        assert_eq!(Style::from(ContentStyle::default()), Style::default());
+        assert_eq!(
+            Style::from(ContentStyle {
+                foreground_color: Some(CColor::DarkYellow),
+                ..Default::default()
+            }),
+            Style::default().fg(Color::Yellow)
+        );
+        assert_eq!(
+            Style::from(ContentStyle {
+                background_color: Some(CColor::DarkYellow),
+                ..Default::default()
+            }),
+            Style::default().bg(Color::Yellow)
+        );
+        assert_eq!(
+            Style::from(ContentStyle {
+                attributes: CAttributes::from(CAttribute::Bold),
+                ..Default::default()
+            }),
+            Style::default().add_modifier(Modifier::BOLD)
+        );
+        assert_eq!(
+            Style::from(ContentStyle {
+                attributes: CAttributes::from(CAttribute::NoBold),
+                ..Default::default()
+            }),
+            Style::default().remove_modifier(Modifier::BOLD)
+        );
+        assert_eq!(
+            Style::from(ContentStyle {
+                attributes: CAttributes::from(CAttribute::Italic),
+                ..Default::default()
+            }),
+            Style::default().add_modifier(Modifier::ITALIC)
+        );
+        assert_eq!(
+            Style::from(ContentStyle {
+                attributes: CAttributes::from(CAttribute::NoItalic),
+                ..Default::default()
+            }),
+            Style::default().remove_modifier(Modifier::ITALIC)
+        );
+        assert_eq!(
+            Style::from(ContentStyle {
+                attributes: CAttributes::from([CAttribute::Bold, CAttribute::Italic].as_ref()),
+                ..Default::default()
+            }),
+            Style::default()
+                .add_modifier(Modifier::BOLD)
+                .add_modifier(Modifier::ITALIC)
+        );
+        assert_eq!(
+            Style::from(ContentStyle {
+                attributes: CAttributes::from([CAttribute::NoBold, CAttribute::NoItalic].as_ref()),
+                ..Default::default()
+            }),
+            Style::default()
+                .remove_modifier(Modifier::BOLD)
+                .remove_modifier(Modifier::ITALIC)
+        );
+    }
+
+    #[test]
+    #[cfg(feature = "underline-color")]
+    fn from_crossterm_content_style_underline() {
+        assert_eq!(
+            Style::from(ContentStyle {
+                underline_color: Some(CColor::DarkRed),
+                ..Default::default()
+            }),
+            Style::default().underline_color(Color::Red)
+        )
+    }
+}

src/backend/termion.rs

@@ -179,7 +179,7 @@ where
                 write!(string, "{}", Bg(cell.bg)).unwrap();
                 bg = cell.bg;
             }
-            string.push_str(&cell.symbol);
+            string.push_str(cell.symbol());
         }
         write!(
             self.writer,

src/backend/termwiz.rs

@@ -176,7 +176,7 @@ impl Backend for TermwizBackend {
                     },
                 )));
 
-            self.buffered_terminal.add_change(&cell.symbol);
+            self.buffered_terminal.add_change(cell.symbol());
         }
         Ok(())
     }

src/backend/test.rs

@@ -9,7 +9,7 @@ use std::{
 use unicode_width::UnicodeWidthStr;
 
 use crate::{
-    backend::{Backend, WindowSize},
+    backend::{Backend, ClearType, WindowSize},
     buffer::{Buffer, Cell},
     layout::{Rect, Size},
 };
@@ -56,11 +56,11 @@ fn buffer_view(buffer: &Buffer) -> String {
         view.push('"');
         for (x, c) in cells.iter().enumerate() {
             if skip == 0 {
-                view.push_str(&c.symbol);
+                view.push_str(c.symbol());
             } else {
-                overwritten.push((x, &c.symbol));
+                overwritten.push((x, c.symbol()));
             }
-            skip = std::cmp::max(skip, c.symbol.width()).saturating_sub(1);
+            skip = std::cmp::max(skip, c.symbol().width()).saturating_sub(1);
         }
         view.push('"');
         if !overwritten.is_empty() {
@@ -179,6 +179,71 @@ impl Backend for TestBackend {
         Ok(())
     }
 
+    fn clear_region(&mut self, clear_type: super::ClearType) -> io::Result<()> {
+        match clear_type {
+            ClearType::All => self.clear()?,
+            ClearType::AfterCursor => {
+                let index = self.buffer.index_of(self.pos.0, self.pos.1) + 1;
+                self.buffer.content[index..].fill(Cell::default());
+            }
+            ClearType::BeforeCursor => {
+                let index = self.buffer.index_of(self.pos.0, self.pos.1);
+                self.buffer.content[..index].fill(Cell::default());
+            }
+            ClearType::CurrentLine => {
+                let line_start_index = self.buffer.index_of(0, self.pos.1);
+                let line_end_index = self.buffer.index_of(self.width - 1, self.pos.1);
+                self.buffer.content[line_start_index..=line_end_index].fill(Cell::default());
+            }
+            ClearType::UntilNewLine => {
+                let index = self.buffer.index_of(self.pos.0, self.pos.1);
+                let line_end_index = self.buffer.index_of(self.width - 1, self.pos.1);
+                self.buffer.content[index..=line_end_index].fill(Cell::default());
+            }
+        }
+        Ok(())
+    }
+
+    /// Inserts n line breaks at the current cursor position.
+    ///
+    /// After the insertion, the cursor x position will be incremented by 1 (unless it's already
+    /// at the end of line). This is a common behaviour of terminals in raw mode.
+    ///
+    /// If the number of lines to append is fewer than the number of lines in the buffer after the
+    /// cursor y position then the cursor is moved down by n rows.
+    ///
+    /// If the number of lines to append is greater than the number of lines in the buffer after
+    /// the cursor y position then that number of empty lines (at most the buffer's height in this
+    /// case but this limit is instead replaced with scrolling in most backend implementations) will
+    /// be added after the current position and the cursor will be moved to the last row.
+    fn append_lines(&mut self, n: u16) -> io::Result<()> {
+        let (cur_x, cur_y) = self.get_cursor()?;
+
+        // the next column ensuring that we don't go past the last column
+        let new_cursor_x = cur_x.saturating_add(1).min(self.width.saturating_sub(1));
+
+        let max_y = self.height.saturating_sub(1);
+        let lines_after_cursor = max_y.saturating_sub(cur_y);
+        if n > lines_after_cursor {
+            let rotate_by = n.saturating_sub(lines_after_cursor).min(max_y);
+
+            if rotate_by == self.height - 1 {
+                self.clear()?;
+            }
+
+            self.set_cursor(0, rotate_by)?;
+            self.clear_region(ClearType::BeforeCursor)?;
+            self.buffer
+                .content
+                .rotate_left((self.width * rotate_by).into());
+        }
+
+        let new_cursor_y = cur_y.saturating_add(n).min(max_y);
+        self.set_cursor(new_cursor_x, new_cursor_y)?;
+
+        Ok(())
+    }
+
     fn size(&self) -> Result<Rect, io::Error> {
         Ok(Rect::new(0, 0, self.width, self.height))
     }
@@ -310,13 +375,299 @@ mod tests {
 
     #[test]
     fn clear() {
-        let mut backend = TestBackend::new(10, 2);
+        let mut backend = TestBackend::new(10, 4);
         let mut cell = Cell::default();
         cell.set_symbol("a");
         backend.draw([(0, 0, &cell)].into_iter()).unwrap();
         backend.draw([(0, 1, &cell)].into_iter()).unwrap();
         backend.clear().unwrap();
-        backend.assert_buffer(&Buffer::with_lines(vec!["          "; 2]));
+        backend.assert_buffer(&Buffer::with_lines(vec![
+            "          ",
+            "          ",
+            "          ",
+            "          ",
+        ]));
+    }
+
+    #[test]
+    fn clear_region_all() {
+        let mut backend = TestBackend::new(10, 5);
+        backend.buffer = Buffer::with_lines(vec![
+            "aaaaaaaaaa",
+            "aaaaaaaaaa",
+            "aaaaaaaaaa",
+            "aaaaaaaaaa",
+            "aaaaaaaaaa",
+        ]);
+
+        backend.clear_region(ClearType::All).unwrap();
+        backend.assert_buffer(&Buffer::with_lines(vec![
+            "          ",
+            "          ",
+            "          ",
+            "          ",
+            "          ",
+        ]));
+    }
+
+    #[test]
+    fn clear_region_after_cursor() {
+        let mut backend = TestBackend::new(10, 5);
+        backend.buffer = Buffer::with_lines(vec![
+            "aaaaaaaaaa",
+            "aaaaaaaaaa",
+            "aaaaaaaaaa",
+            "aaaaaaaaaa",
+            "aaaaaaaaaa",
+        ]);
+
+        backend.set_cursor(3, 2).unwrap();
+        backend.clear_region(ClearType::AfterCursor).unwrap();
+        backend.assert_buffer(&Buffer::with_lines(vec![
+            "aaaaaaaaaa",
+            "aaaaaaaaaa",
+            "aaaa      ",
+            "          ",
+            "          ",
+        ]));
+    }
+
+    #[test]
+    fn clear_region_before_cursor() {
+        let mut backend = TestBackend::new(10, 5);
+        backend.buffer = Buffer::with_lines(vec![
+            "aaaaaaaaaa",
+            "aaaaaaaaaa",
+            "aaaaaaaaaa",
+            "aaaaaaaaaa",
+            "aaaaaaaaaa",
+        ]);
+
+        backend.set_cursor(5, 3).unwrap();
+        backend.clear_region(ClearType::BeforeCursor).unwrap();
+        backend.assert_buffer(&Buffer::with_lines(vec![
+            "          ",
+            "          ",
+            "          ",
+            "     aaaaa",
+            "aaaaaaaaaa",
+        ]));
+    }
+
+    #[test]
+    fn clear_region_current_line() {
+        let mut backend = TestBackend::new(10, 5);
+        backend.buffer = Buffer::with_lines(vec![
+            "aaaaaaaaaa",
+            "aaaaaaaaaa",
+            "aaaaaaaaaa",
+            "aaaaaaaaaa",
+            "aaaaaaaaaa",
+        ]);
+
+        backend.set_cursor(3, 1).unwrap();
+        backend.clear_region(ClearType::CurrentLine).unwrap();
+        backend.assert_buffer(&Buffer::with_lines(vec![
+            "aaaaaaaaaa",
+            "          ",
+            "aaaaaaaaaa",
+            "aaaaaaaaaa",
+            "aaaaaaaaaa",
+        ]));
+    }
+
+    #[test]
+    fn clear_region_until_new_line() {
+        let mut backend = TestBackend::new(10, 5);
+        backend.buffer = Buffer::with_lines(vec![
+            "aaaaaaaaaa",
+            "aaaaaaaaaa",
+            "aaaaaaaaaa",
+            "aaaaaaaaaa",
+            "aaaaaaaaaa",
+        ]);
+
+        backend.set_cursor(3, 0).unwrap();
+        backend.clear_region(ClearType::UntilNewLine).unwrap();
+        backend.assert_buffer(&Buffer::with_lines(vec![
+            "aaa       ",
+            "aaaaaaaaaa",
+            "aaaaaaaaaa",
+            "aaaaaaaaaa",
+            "aaaaaaaaaa",
+        ]));
+    }
+
+    #[test]
+    fn append_lines_not_at_last_line() {
+        let mut backend = TestBackend::new(10, 5);
+        backend.buffer = Buffer::with_lines(vec![
+            "aaaaaaaaaa",
+            "bbbbbbbbbb",
+            "cccccccccc",
+            "dddddddddd",
+            "eeeeeeeeee",
+        ]);
+
+        backend.set_cursor(0, 0).unwrap();
+
+        // If the cursor is not at the last line in the terminal the addition of a
+        // newline simply moves the cursor down and to the right
+
+        backend.append_lines(1).unwrap();
+        assert_eq!(backend.get_cursor().unwrap(), (1, 1));
+
+        backend.append_lines(1).unwrap();
+        assert_eq!(backend.get_cursor().unwrap(), (2, 2));
+
+        backend.append_lines(1).unwrap();
+        assert_eq!(backend.get_cursor().unwrap(), (3, 3));
+
+        backend.append_lines(1).unwrap();
+        assert_eq!(backend.get_cursor().unwrap(), (4, 4));
+
+        // As such the buffer should remain unchanged
+        backend.assert_buffer(&Buffer::with_lines(vec![
+            "aaaaaaaaaa",
+            "bbbbbbbbbb",
+            "cccccccccc",
+            "dddddddddd",
+            "eeeeeeeeee",
+        ]));
+    }
+
+    #[test]
+    fn append_lines_at_last_line() {
+        let mut backend = TestBackend::new(10, 5);
+        backend.buffer = Buffer::with_lines(vec![
+            "aaaaaaaaaa",
+            "bbbbbbbbbb",
+            "cccccccccc",
+            "dddddddddd",
+            "eeeeeeeeee",
+        ]);
+
+        // If the cursor is at the last line in the terminal the addition of a
+        // newline will scroll the contents of the buffer
+        backend.set_cursor(0, 4).unwrap();
+
+        backend.append_lines(1).unwrap();
+
+        backend.buffer = Buffer::with_lines(vec![
+            "bbbbbbbbbb",
+            "cccccccccc",
+            "dddddddddd",
+            "eeeeeeeeee",
+            "          ",
+        ]);
+
+        // It also moves the cursor to the right, as is common of the behaviour of
+        // terminals in raw-mode
+        assert_eq!(backend.get_cursor().unwrap(), (1, 4));
+    }
+
+    #[test]
+    fn append_multiple_lines_not_at_last_line() {
+        let mut backend = TestBackend::new(10, 5);
+        backend.buffer = Buffer::with_lines(vec![
+            "aaaaaaaaaa",
+            "bbbbbbbbbb",
+            "cccccccccc",
+            "dddddddddd",
+            "eeeeeeeeee",
+        ]);
+
+        backend.set_cursor(0, 0).unwrap();
+
+        // If the cursor is not at the last line in the terminal the addition of multiple
+        // newlines simply moves the cursor n lines down and to the right by 1
+
+        backend.append_lines(4).unwrap();
+        assert_eq!(backend.get_cursor().unwrap(), (1, 4));
+
+        // As such the buffer should remain unchanged
+        backend.assert_buffer(&Buffer::with_lines(vec![
+            "aaaaaaaaaa",
+            "bbbbbbbbbb",
+            "cccccccccc",
+            "dddddddddd",
+            "eeeeeeeeee",
+        ]));
+    }
+
+    #[test]
+    fn append_multiple_lines_past_last_line() {
+        let mut backend = TestBackend::new(10, 5);
+        backend.buffer = Buffer::with_lines(vec![
+            "aaaaaaaaaa",
+            "bbbbbbbbbb",
+            "cccccccccc",
+            "dddddddddd",
+            "eeeeeeeeee",
+        ]);
+
+        backend.set_cursor(0, 3).unwrap();
+
+        backend.append_lines(3).unwrap();
+        assert_eq!(backend.get_cursor().unwrap(), (1, 4));
+
+        backend.assert_buffer(&Buffer::with_lines(vec![
+            "cccccccccc",
+            "dddddddddd",
+            "eeeeeeeeee",
+            "          ",
+            "          ",
+        ]));
+    }
+
+    #[test]
+    fn append_multiple_lines_where_cursor_at_end_appends_height_lines() {
+        let mut backend = TestBackend::new(10, 5);
+        backend.buffer = Buffer::with_lines(vec![
+            "aaaaaaaaaa",
+            "bbbbbbbbbb",
+            "cccccccccc",
+            "dddddddddd",
+            "eeeeeeeeee",
+        ]);
+
+        backend.set_cursor(0, 4).unwrap();
+
+        backend.append_lines(5).unwrap();
+        assert_eq!(backend.get_cursor().unwrap(), (1, 4));
+
+        backend.assert_buffer(&Buffer::with_lines(vec![
+            "          ",
+            "          ",
+            "          ",
+            "          ",
+            "          ",
+        ]));
+    }
+
+    #[test]
+    fn append_multiple_lines_where_cursor_appends_height_lines() {
+        let mut backend = TestBackend::new(10, 5);
+        backend.buffer = Buffer::with_lines(vec![
+            "aaaaaaaaaa",
+            "bbbbbbbbbb",
+            "cccccccccc",
+            "dddddddddd",
+            "eeeeeeeeee",
+        ]);
+
+        backend.set_cursor(0, 0).unwrap();
+
+        backend.append_lines(5).unwrap();
+        assert_eq!(backend.get_cursor().unwrap(), (1, 4));
+
+        backend.assert_buffer(&Buffer::with_lines(vec![
+            "bbbbbbbbbb",
+            "cccccccccc",
+            "dddddddddd",
+            "eeeeeeeeee",
+            "          ",
+        ]));
     }
 
     #[test]

src/buffer.rs

@@ -16,6 +16,12 @@ use crate::{
 #[derive(Debug, Clone, Eq, PartialEq, Hash)]
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 pub struct Cell {
+    #[deprecated(
+        since = "0.24.1",
+        note = "This field will be hidden at next major version. Use `Cell::symbol` method to get \
+                the value. Use `Cell::set_symbol` to update the field. Use `Cell::default` to \
+                create `Cell` instance"
+    )]
     pub symbol: String,
     pub fg: Color,
     pub bg: Color,
@@ -25,7 +31,12 @@ pub struct Cell {
     pub skip: bool,
 }
 
+#[allow(deprecated)] // For Cell::symbol
 impl Cell {
+    pub fn symbol(&self) -> &str {
+        self.symbol.as_str()
+    }
+
     pub fn set_symbol(&mut self, symbol: &str) -> &mut Cell {
         self.symbol.clear();
         self.symbol.push_str(symbol);
@@ -106,6 +117,7 @@ impl Cell {
 
 impl Default for Cell {
     fn default() -> Cell {
+        #[allow(deprecated)] // For Cell::symbol
         Cell {
             symbol: " ".into(),
             fg: Color::Reset,
@@ -132,19 +144,16 @@ impl Default for Cell {
 ///
 /// let mut buf = Buffer::empty(Rect{x: 0, y: 0, width: 10, height: 5});
 /// buf.get_mut(0, 2).set_symbol("x");
-/// assert_eq!(buf.get(0, 2).symbol, "x");
+/// assert_eq!(buf.get(0, 2).symbol(), "x");
+///
 /// buf.set_string(3, 0, "string", Style::default().fg(Color::Red).bg(Color::White));
-/// assert_eq!(buf.get(5, 0), &Cell{
-///     symbol: String::from("r"),
-///     fg: Color::Red,
-///     bg: Color::White,
-///     #[cfg(feature = "underline-color")]
-///     underline_color: Color::Reset,
-///     modifier: Modifier::empty(),
-///     skip: false
-/// });
+/// let cell = buf.get_mut(5, 0);
+/// assert_eq!(cell.symbol(), "r");
+/// assert_eq!(cell.fg, Color::Red);
+/// assert_eq!(cell.bg, Color::White);
+///
 /// buf.get_mut(5, 0).set_char('x');
-/// assert_eq!(buf.get(5, 0).symbol, "x");
+/// assert_eq!(buf.get(5, 0).symbol(), "x");
 /// ```
 #[derive(Default, Clone, Eq, PartialEq, Hash)]
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
@@ -358,18 +367,6 @@ impl Buffer {
         self.set_stringn(x, y, span.content.as_ref(), width as usize, span.style)
     }
 
-    #[deprecated(
-        since = "0.10.0",
-        note = "You should use styling capabilities of `Buffer::set_style`"
-    )]
-    pub fn set_background(&mut self, area: Rect, color: Color) {
-        for y in area.top()..area.bottom() {
-            for x in area.left()..area.right() {
-                self.get_mut(x, y).set_bg(color);
-            }
-        }
-    }
-
     pub fn set_style(&mut self, area: Rect, style: Style) {
         for y in area.top()..area.bottom() {
             for x in area.left()..area.right() {
@@ -471,9 +468,9 @@ impl Buffer {
                 updates.push((x, y, &next_buffer[i]));
             }
 
-            to_skip = current.symbol.width().saturating_sub(1);
+            to_skip = current.symbol().width().saturating_sub(1);
 
-            let affected_width = std::cmp::max(current.symbol.width(), previous.symbol.width());
+            let affected_width = std::cmp::max(current.symbol().width(), previous.symbol().width());
             invalidated = std::cmp::max(affected_width, invalidated).saturating_sub(1);
         }
         updates
@@ -555,11 +552,11 @@ impl Debug for Buffer {
             f.write_str("        \"")?;
             for (x, c) in line.iter().enumerate() {
                 if skip == 0 {
-                    f.write_str(&c.symbol)?;
+                    f.write_str(c.symbol())?;
                 } else {
-                    overwritten.push((x, &c.symbol));
+                    overwritten.push((x, c.symbol()));
                 }
-                skip = std::cmp::max(skip, c.symbol.width()).saturating_sub(1);
+                skip = std::cmp::max(skip, c.symbol().width()).saturating_sub(1);
                 #[cfg(feature = "underline-color")]
                 {
                     let style = (c.fg, c.bg, c.underline_color, c.modifier);
@@ -1043,4 +1040,14 @@ mod tests {
         buf.set_string(0, 1, "bar", Style::new().blue());
         assert_eq!(buf, Buffer::with_lines(vec!["foo".red(), "bar".blue()]));
     }
+
+    #[test]
+    fn cell_symbol_field() {
+        let mut cell = Cell::default();
+        assert_eq!(cell.symbol(), " ");
+        cell.set_symbol("あ"); // Multi-byte character
+        assert_eq!(cell.symbol(), "あ");
+        cell.set_symbol("👨‍👩‍👧‍👦"); // Multiple code units combined with ZWJ
+        assert_eq!(cell.symbol(), "👨‍👩‍👧‍👦");
+    }
 }

src/layout/rect.rs

@@ -6,6 +6,10 @@ use std::{
 
 use crate::prelude::*;
 
+mod offset;
+
+pub use offset::*;
+
 /// A simple rectangle used in the computation of the layout and to give widgets a hint about the
 /// area they are supposed to render to.
 #[derive(Debug, Default, Clone, Copy, Eq, PartialEq, Hash)]
@@ -106,6 +110,26 @@ impl Rect {
         }
     }
 
+    /// Moves the `Rect` without modifying its size.
+    ///
+    /// Moves the `Rect` according to the given offset without modifying its [`width`](Rect::width)
+    /// or [`height`](Rect::height).
+    /// - Positive `x` moves the whole `Rect` to the right, negative to the left.
+    /// - Positive `y` moves the whole `Rect` to the bottom, negative to the top.
+    ///
+    /// See [`Offset`] for details.
+    pub fn offset(self, offset: Offset) -> Rect {
+        Rect {
+            x: i32::from(self.x)
+                .saturating_add(offset.x)
+                .clamp(0, (u16::MAX - self.width) as i32) as u16,
+            y: i32::from(self.y)
+                .saturating_add(offset.y)
+                .clamp(0, (u16::MAX - self.height) as i32) as u16,
+            ..self
+        }
+    }
+
     /// Returns a new rect that contains both the current one and the given one.
     pub fn union(self, other: Rect) -> Rect {
         let x1 = min(self.x, other.x);
@@ -131,8 +155,8 @@ impl Rect {
         Rect {
             x: x1,
             y: y1,
-            width: x2 - x1,
-            height: y2 - y1,
+            width: x2.saturating_sub(x1),
+            height: y2.saturating_sub(y1),
         }
     }
 
@@ -207,6 +231,39 @@ mod tests {
         );
     }
 
+    #[test]
+    fn offset() {
+        assert_eq!(
+            Rect::new(1, 2, 3, 4).offset(Offset { x: 5, y: 6 }),
+            Rect::new(6, 8, 3, 4),
+        );
+    }
+
+    #[test]
+    fn negative_offset() {
+        assert_eq!(
+            Rect::new(4, 3, 3, 4).offset(Offset { x: -2, y: -1 }),
+            Rect::new(2, 2, 3, 4),
+        );
+    }
+
+    #[test]
+    fn negative_offset_saturate() {
+        assert_eq!(
+            Rect::new(1, 2, 3, 4).offset(Offset { x: -5, y: -6 }),
+            Rect::new(0, 0, 3, 4),
+        );
+    }
+
+    /// Offsets a [`Rect`] making it go outside [`u16::MAX`], it should keep its size.
+    #[test]
+    fn offset_saturate_max() {
+        assert_eq!(
+            Rect::new(u16::MAX - 500, u16::MAX - 500, 100, 100).offset(Offset { x: 1000, y: 1000 }),
+            Rect::new(u16::MAX - 100, u16::MAX - 100, 100, 100),
+        );
+    }
+
     #[test]
     fn union() {
         assert_eq!(
@@ -223,6 +280,14 @@ mod tests {
         );
     }
 
+    #[test]
+    fn intersection_underflow() {
+        assert_eq!(
+            Rect::new(1, 1, 2, 2).intersection(Rect::new(4, 4, 2, 2)),
+            Rect::new(4, 4, 0, 0)
+        );
+    }
+
     #[test]
     fn intersects() {
         assert!(Rect::new(1, 2, 3, 4).intersects(Rect::new(2, 3, 4, 5)));

src/layout/rect/offset.rs

@@ -0,0 +1,12 @@
+/// Amounts by which to move a [`Rect`](super::Rect).
+///
+/// Positive numbers move to the right/bottom and negative to the left/top.
+///
+/// See [`Rect::offset`](super::Rect::offset)
+#[derive(Debug, Default, Clone, Copy)]
+pub struct Offset {
+    /// How much to move on the X axis
+    pub x: i32,
+    /// How much to move on the Y axis
+    pub y: i32,
+}

src/lib.rs

@@ -1,30 +1,32 @@
 #![forbid(unsafe_code)]
 
-//! ![Demo](https://raw.githubusercontent.com/ratatui-org/ratatui/aa09e59dc0058347f68d7c1e0c91f863c6f2b8c9/examples/demo2.gif)
+//! ![Demo](https://raw.githubusercontent.com/ratatui-org/ratatui/b33c878808c4c40591d7a2d9f9d94d6fee95a96f/examples/demo2.gif)
 //!
 //! <div align="center">
 //!
-//! [![Crate Badge]](https://crates.io/crates/ratatui) [![License Badge]](./LICENSE) [![CI
-//! Badge]](https://github.com/ratatui-org/ratatui/actions?query=workflow%3ACI+) [![Docs
-//! Badge]](https://docs.rs/crate/ratatui/)<br>
-//! [![Dependencies Badge]](https://deps.rs/repo/github/ratatui-org/ratatui) [![Codecov
-//! Badge]](https://app.codecov.io/gh/ratatui-org/ratatui) [![Discord
-//! Badge]](https://discord.gg/pMCEU9hNEj) [![Matrix
-//! Badge]](https://matrix.to/#/#ratatui:matrix.org)<br>
-//! [Documentation](https://docs.rs/ratatui) · [Ratatui Book](https://ratatui.rs) ·
-//! [Examples](https://github.com/ratatui-org/ratatui/tree/main/examples) · [Report a
-//! bug](https://github.com/ratatui-org/ratatui/issues/new?labels=bug&projects=&template=bug_report.md)
-//! · [Request a
-//! Feature](https://github.com/ratatui-org/ratatui/issues/new?labels=enhancement&projects=&template=feature_request.md)
+//! [![Crate Badge]](https://crates.io/crates/ratatui)
+//! [![License Badge]](./LICENSE)
+//! [![CI Badge]](https://github.com/ratatui-org/ratatui/actions?query=workflow%3ACI+)
+//! [![Docs Badge]](https://docs.rs/crate/ratatui/)<br>
+//! [![Dependencies Badge]](https://deps.rs/repo/github/ratatui-org/ratatui)
+//! [![Codecov Badge]](https://app.codecov.io/gh/ratatui-org/ratatui)
+//! [![Discord Badge]](https://discord.gg/pMCEU9hNEj)
+//! [![Matrix Badge]](https://matrix.to/#/#ratatui:matrix.org)<br>
+//!
+//! [Documentation](https://docs.rs/ratatui)
+//! · [Ratatui Website](https://ratatui.rs)
+//! · [Examples](https://github.com/ratatui-org/ratatui/tree/main/examples)
+//! · [Report a bug](https://github.com/ratatui-org/ratatui/issues/new?labels=bug&projects=&template=bug_report.md)
+//! · [Request a Feature](https://github.com/ratatui-org/ratatui/issues/new?labels=enhancement&projects=&template=feature_request.md)
 //! · [Send a Pull Request](https://github.com/ratatui-org/ratatui/compare)
 //!
 //! </div>
 //!
 //! # Ratatui
 //!
-//! [Ratatui] is a crate for cooking up terminal user interfaces in rust. It is a lightweight
-//! library that provides a set of widgets and utilities to build complex rust TUIs. Ratatui was
-//! forked from the [Tui-rs crate] in 2023 in order to continue its development.
+//! [Ratatui] is a crate for cooking up terminal user interfaces in Rust. It is a lightweight
+//! library that provides a set of widgets and utilities to build complex Rust TUIs. Ratatui was
+//! forked from the [tui-rs] crate in 2023 in order to continue its development.
 //!
 //! ## Installation
 //!
@@ -35,7 +37,7 @@
 //! ```
 //!
 //! Ratatui uses [Crossterm] by default as it works on most platforms. See the [Installation]
-//! section of the [Ratatui Book] for more details on how to use other backends ([Termion] /
+//! section of the [Ratatui Website] for more details on how to use other backends ([Termion] /
 //! [Termwiz]).
 //!
 //! ## Introduction
@@ -43,12 +45,12 @@
 //! Ratatui is based on the principle of immediate rendering with intermediate buffers. This means
 //! that for each frame, your app must render all widgets that are supposed to be part of the UI.
 //! This is in contrast to the retained mode style of rendering where widgets are updated and then
-//! automatically redrawn on the next frame. See the [Rendering] section of the [Ratatui Book] for
-//! more info.
+//! automatically redrawn on the next frame. See the [Rendering] section of the [Ratatui Website]
+//! for more info.
 //!
 //! ## Other documentation
 //!
-//! - [Ratatui Book] - explains the library's concepts and provides step-by-step tutorials
+//! - [Ratatui Website] - explains the library's concepts and provides step-by-step tutorials
 //! - [Examples] - a collection of examples that demonstrate how to use the library.
 //! - [API Documentation] - the full API documentation for the library on docs.rs.
 //! - [Changelog] - generated by [git-cliff] utilizing [Conventional Commits].
@@ -60,12 +62,11 @@
 //! The following example demonstrates the minimal amount of code necessary to setup a terminal and
 //! render "Hello World!". The full code for this example which contains a little more detail is in
 //! [hello_world.rs]. For more guidance on different ways to structure your application see the
-//! [Application Patterns] and [Hello World tutorial] sections in the [Ratatui Book] and the various
-//! [Examples]. There are also several starter templates available:
+//! [Application Patterns] and [Hello World tutorial] sections in the [Ratatui Website] and the
+//! various [Examples]. There are also several starter templates available:
 //!
-//! - [rust-tui-template]
-//! - [ratatui-async-template] (book and template)
-//! - [simple-tui-rs]
+//! - [template]
+//! - [async-template] (book and template)
 //!
 //! Every application built with `ratatui` needs to implement the following steps:
 //!
@@ -89,20 +90,20 @@
 //!
 //! Most applications should enter the Alternate Screen when starting and leave it when exiting and
 //! also enable raw mode to disable line buffering and enable reading key events. See the [`backend`
-//! module] and the [Backends] section of the [Ratatui Book] for more info.
+//! module] and the [Backends] section of the [Ratatui Website] for more info.
 //!
 //! ### Drawing the UI
 //!
 //! The drawing logic is delegated to a closure that takes a [`Frame`] instance as argument. The
 //! [`Frame`] provides the size of the area to draw to and allows the app to render any [`Widget`]
-//! using the provided [`render_widget`] method. See the [Widgets] section of the [Ratatui Book] for
-//! more info.
+//! using the provided [`render_widget`] method. See the [Widgets] section of the [Ratatui Website]
+//! for more info.
 //!
 //! ### Handling events
 //!
 //! Ratatui does not include any input handling. Instead event handling can be implemented by
 //! calling backend library methods directly. See the [Handling Events] section of the [Ratatui
-//! Book] for more info. For example, if you are using [Crossterm], you can use the
+//! Website] for more info. For example, if you are using [Crossterm], you can use the
 //! [`crossterm::event`] module to handle events.
 //!
 //! ### Example
@@ -161,20 +162,21 @@
 //! The library comes with a basic yet useful layout management object called [`Layout`] which
 //! allows you to split the available space into multiple areas and then render widgets in each
 //! area. This lets you describe a responsive terminal UI by nesting layouts. See the [Layout]
-//! section of the [Ratatui Book] for more info.
+//! section of the [Ratatui Website] for more info.
 //!
 //! ```rust,no_run
 //! use ratatui::{prelude::*, widgets::*};
 //!
 //! fn ui(frame: &mut Frame) {
-//!     let main_layout = Layout::default()
-//!         .direction(Direction::Vertical)
-//!         .constraints([
+//!     let main_layout = Layout::new(
+//!         Direction::Vertical,
+//!         [
 //!             Constraint::Length(1),
 //!             Constraint::Min(0),
 //!             Constraint::Length(1),
-//!         ])
-//!         .split(frame.size());
+//!         ]
+//!     )
+//!     .split(frame.size());
 //!     frame.render_widget(
 //!         Block::new().borders(Borders::TOP).title("Title Bar"),
 //!         main_layout[0],
@@ -184,10 +186,11 @@
 //!         main_layout[2],
 //!     );
 //!
-//!     let inner_layout = Layout::default()
-//!         .direction(Direction::Horizontal)
-//!         .constraints([Constraint::Percentage(50), Constraint::Percentage(50)])
-//!         .split(main_layout[1]);
+//!     let inner_layout = Layout::new(
+//!         Direction::Horizontal,
+//!         [Constraint::Percentage(50), Constraint::Percentage(50)]
+//!     )
+//!     .split(main_layout[1]);
 //!     frame.render_widget(
 //!         Block::default().borders(Borders::ALL).title("Left"),
 //!         inner_layout[0],
@@ -213,22 +216,23 @@
 //! important one is [`Style`] which represents the foreground and background colors and the text
 //! attributes of a [`Span`]. The [`style` module] also provides a [`Stylize`] trait that allows
 //! short-hand syntax to apply a style to widgets and text. See the [Styling Text] section of the
-//! [Ratatui Book] for more info.
+//! [Ratatui Website] for more info.
 //!
 //! ```rust,no_run
 //! use ratatui::{prelude::*, widgets::*};
 //!
 //! fn ui(frame: &mut Frame) {
-//!     let areas = Layout::default()
-//!         .direction(Direction::Vertical)
-//!         .constraints([
+//!     let areas = Layout::new(
+//!         Direction::Vertical,
+//!         [
 //!             Constraint::Length(1),
 //!             Constraint::Length(1),
 //!             Constraint::Length(1),
 //!             Constraint::Length(1),
 //!             Constraint::Min(0),
-//!         ])
-//!         .split(frame.size());
+//!         ]
+//!     )
+//!     .split(frame.size());
 //!
 //!     let span1 = Span::raw("Hello ");
 //!     let span2 = Span::styled(
@@ -282,26 +286,25 @@
     doc = "[`calendar`]: widgets::calendar::Monthly"
 )]
 //!
-//! [Ratatui Book]: https://ratatui.rs
-//! [Installation]: https://ratatui.rs/installation.html
-//! [Rendering]: https://ratatui.rs/concepts/rendering/index.html
-//! [Application Patterns]: https://ratatui.rs/concepts/application_patterns/index.html
-//! [Hello World tutorial]: https://ratatui.rs/tutorial/hello_world.html
-//! [Backends]: https://ratatui.rs/concepts/backends/index.html
-//! [Widgets]: https://ratatui.rs/how-to/widgets/index.html
-//! [Handling Events]: https://ratatui.rs/concepts/event_handling.html
-//! [Layout]: https://ratatui.rs/how-to/layout/index.html
-//! [Styling Text]: https://ratatui.rs/how-to/render/style-text.html
-//! [rust-tui-template]: https://github.com/ratatui-org/rust-tui-template
-//! [ratatui-async-template]: https://ratatui-org.github.io/ratatui-async-template/
-//! [simple-tui-rs]: https://github.com/pmsanford/simple-tui-rs
+//! [Ratatui Website]: https://ratatui.rs/
+//! [Installation]: https://ratatui.rs/installation/
+//! [Rendering]: https://ratatui.rs/concepts/rendering/
+//! [Application Patterns]: https://ratatui.rs/concepts/application-patterns/
+//! [Hello World tutorial]: https://ratatui.rs/tutorials/hello-world/
+//! [Backends]: https://ratatui.rs/concepts/backends/
+//! [Widgets]: https://ratatui.rs/how-to/widgets/
+//! [Handling Events]: https://ratatui.rs/concepts/event-handling/
+//! [Layout]: https://ratatui.rs/how-to/layout/
+//! [Styling Text]: https://ratatui.rs/how-to/render/style-text/
+//! [template]: https://github.com/ratatui-org/template
+//! [async-template]: https://ratatui-org.github.io/async-template
 //! [Examples]: https://github.com/ratatui-org/ratatui/tree/main/examples
-//! [git-cliff]: https://github.com/orhun/git-cliff
+//! [git-cliff]: https://git-cliff.org
 //! [Conventional Commits]: https://www.conventionalcommits.org
 //! [API Documentation]: https://docs.rs/ratatui
 //! [Changelog]: https://github.com/ratatui-org/ratatui/blob/main/CHANGELOG.md
-//! [Contributing]: https:://github.com/ratatui-org/ratatui/blob/main/CONTRIBUTING.md
-//! [Breaking Changes]: https:://github.com/ratatui-org/ratatui/blob/main/BREAKING-CHANGES.md
+//! [Contributing]: https://github.com/ratatui-org/ratatui/blob/main/CONTRIBUTING.md
+//! [Breaking Changes]: https://github.com/ratatui-org/ratatui/blob/main/BREAKING-CHANGES.md
 //! [docsrs-hello]: https://github.com/ratatui-org/ratatui/blob/c3c3c289b1eb8d562afb1931adb4dc719cd48490/examples/docsrs-hello.png?raw=true
 //! [docsrs-layout]: https://github.com/ratatui-org/ratatui/blob/c3c3c289b1eb8d562afb1931adb4dc719cd48490/examples/docsrs-layout.png?raw=true
 //! [docsrs-styling]: https://github.com/ratatui-org/ratatui/blob/c3c3c289b1eb8d562afb1931adb4dc719cd48490/examples/docsrs-styling.png?raw=true
@@ -322,7 +325,7 @@
 //! [Crossterm]: https://crates.io/crates/crossterm
 //! [Termion]: https://crates.io/crates/termion
 //! [Termwiz]: https://crates.io/crates/termwiz
-//! [Tui-rs crate]: https://crates.io/crates/tui
+//! [tui-rs]: https://crates.io/crates/tui
 //! [hello_world.rs]: https://github.com/ratatui-org/ratatui/blob/main/examples/hello_world.rs
 //! [Crate Badge]: https://img.shields.io/crates/v/ratatui?logo=rust&style=flat-square
 //! [CI Badge]:

src/style.rs

@@ -249,6 +249,7 @@ impl Style {
     /// let diff = Style::default().fg(Color::Red);
     /// assert_eq!(style.patch(diff), Style::default().fg(Color::Red));
     /// ```
+    #[must_use = "`fg` returns the modified style without modifying the original"]
     pub const fn fg(mut self, color: Color) -> Style {
         self.fg = Some(color);
         self
@@ -264,6 +265,7 @@ impl Style {
     /// let diff = Style::default().bg(Color::Red);
     /// assert_eq!(style.patch(diff), Style::default().bg(Color::Red));
     /// ```
+    #[must_use = "`bg` returns the modified style without modifying the original"]
     pub const fn bg(mut self, color: Color) -> Style {
         self.bg = Some(color);
         self
@@ -288,6 +290,7 @@ impl Style {
     /// assert_eq!(style.patch(diff), Style::default().underline_color(Color::Red).add_modifier(Modifier::UNDERLINED));
     /// ```
     #[cfg(feature = "underline-color")]
+    #[must_use = "`underline_color` returns the modified style without modifying the original"]
     pub const fn underline_color(mut self, color: Color) -> Style {
         self.underline_color = Some(color);
         self
@@ -307,6 +310,7 @@ impl Style {
     /// assert_eq!(patched.add_modifier, Modifier::BOLD | Modifier::ITALIC);
     /// assert_eq!(patched.sub_modifier, Modifier::empty());
     /// ```
+    #[must_use = "`add_modifier` returns the modified style without modifying the original"]
     pub const fn add_modifier(mut self, modifier: Modifier) -> Style {
         self.sub_modifier = self.sub_modifier.difference(modifier);
         self.add_modifier = self.add_modifier.union(modifier);
@@ -327,6 +331,7 @@ impl Style {
     /// assert_eq!(patched.add_modifier, Modifier::BOLD);
     /// assert_eq!(patched.sub_modifier, Modifier::ITALIC);
     /// ```
+    #[must_use = "`remove_modifier` returns the modified style without modifying the original"]
     pub const fn remove_modifier(mut self, modifier: Modifier) -> Style {
         self.add_modifier = self.add_modifier.difference(modifier);
         self.sub_modifier = self.sub_modifier.union(modifier);
@@ -346,6 +351,7 @@ impl Style {
     ///     Style::default().patch(style_1).patch(style_2),
     ///     Style::default().patch(combined));
     /// ```
+    #[must_use = "`patch` returns the modified style without modifying the original"]
     pub fn patch(mut self, other: Style) -> Style {
         self.fg = other.fg.or(self.fg);
         self.bg = other.bg.or(self.bg);

src/style/stylize.rs

@@ -40,11 +40,13 @@ macro_rules! color {
     ( $color:ident ) => {
         paste! {
             #[doc = "Sets the foreground color to [`" $color "`](Color::" $color:camel ")."]
+            #[must_use = concat!("`", stringify!($color), "` returns the modified style without modifying the original")]
             fn $color(self) -> T {
                 self.fg(Color::[<$color:camel>])
             }
 
             #[doc = "Sets the background color to [`" $color "`](Color::" $color:camel ")."]
+            #[must_use = concat!("`on_", stringify!($color), "` returns the modified style without modifying the original")]
             fn [<on_ $color>](self) -> T {
                 self.bg(Color::[<$color:camel>])
             }
@@ -76,6 +78,7 @@ macro_rules! modifier {
     ( $modifier:ident ) => {
         paste! {
             #[doc = "Adds the [`" $modifier:upper "`](Modifier::" $modifier:upper ") modifier."]
+            #[must_use = concat!("`", stringify!($modifier), "` returns the modified style without modifying the original")]
             fn [<$modifier>](self) -> T {
                 self.add_modifier(Modifier::[<$modifier:upper>])
             }
@@ -83,6 +86,7 @@ macro_rules! modifier {
 
         paste! {
             #[doc = "Removes the [`" $modifier:upper "`](Modifier::" $modifier:upper ") modifier."]
+            #[must_use = concat!("`not_", stringify!($modifier), "` returns the modified style without modifying the original")]
             fn [<not_ $modifier>](self) -> T {
                 self.remove_modifier(Modifier::[<$modifier:upper>])
             }
@@ -126,10 +130,15 @@ macro_rules! modifier {
 /// let block = Block::default().title("Title").borders(Borders::ALL).on_white().bold();
 /// ```
 pub trait Stylize<'a, T>: Sized {
+    #[must_use = "`bg` returns the modified style without modifying the original"]
     fn bg(self, color: Color) -> T;
+    #[must_use = "`fg` returns the modified style without modifying the original"]
     fn fg<S: Into<Color>>(self, color: S) -> T;
+    #[must_use = "`reset` returns the modified style without modifying the original"]
     fn reset(self) -> T;
+    #[must_use = "`add_modifier` returns the modified style without modifying the original"]
     fn add_modifier(self, modifier: Modifier) -> T;
+    #[must_use = "`remove_modifier` returns the modified style without modifying the original"]
     fn remove_modifier(self, modifier: Modifier) -> T;
 
     color!(black);

src/terminal.rs

@@ -471,38 +471,50 @@ where
             return Ok(());
         }
 
+        // Clear the viewport off the screen
         self.clear()?;
-        let height = height.min(self.last_known_size.height);
-        self.backend.append_lines(height)?;
-        let missing_lines =
-            height.saturating_sub(self.last_known_size.bottom() - self.viewport_area.top());
+
+        // Move the viewport by height, but don't move it past the bottom of the terminal
+        let viewport_at_bottom = self.last_known_size.bottom() - self.viewport_area.height;
+        self.set_viewport_area(Rect {
+            y: self
+                .viewport_area
+                .y
+                .saturating_add(height)
+                .min(viewport_at_bottom),
+            ..self.viewport_area
+        });
+
+        // Draw contents into buffer
         let area = Rect {
             x: self.viewport_area.left(),
-            y: self.viewport_area.top().saturating_sub(missing_lines),
+            y: 0,
             width: self.viewport_area.width,
             height,
         };
         let mut buffer = Buffer::empty(area);
-
         draw_fn(&mut buffer);
 
-        let iter = buffer.content.iter().enumerate().map(|(i, c)| {
-            let (x, y) = buffer.pos_of(i);
-            (x, y, c)
-        });
-        self.backend.draw(iter)?;
-        self.backend.flush()?;
+        // Split buffer into screen-sized chunks and draw
+        let max_chunk_size = (self.viewport_area.top() * area.width).into();
+        for buffer_content_chunk in buffer.content.chunks(max_chunk_size) {
+            let chunk_size = buffer_content_chunk.len() as u16 / area.width;
 
-        let remaining_lines = self.last_known_size.height - area.bottom();
-        let missing_lines = self.viewport_area.height.saturating_sub(remaining_lines);
-        self.backend.append_lines(self.viewport_area.height)?;
+            self.backend
+                .append_lines(self.viewport_area.height.saturating_sub(1) + chunk_size)?;
 
-        self.set_viewport_area(Rect {
-            x: area.left(),
-            y: area.bottom().saturating_sub(missing_lines),
-            width: area.width,
-            height: self.viewport_area.height,
-        });
+            let iter = buffer_content_chunk.iter().enumerate().map(|(i, c)| {
+                let (x, y) = buffer.pos_of(i);
+                (
+                    x,
+                    self.viewport_area.top().saturating_sub(chunk_size) + y,
+                    c,
+                )
+            });
+            self.backend.draw(iter)?;
+            self.backend.flush()?;
+            self.set_cursor(self.viewport_area.left(), self.viewport_area.top())?;
+        }
 
         Ok(())
     }

src/text/span.rs

@@ -11,6 +11,26 @@ use crate::style::{Style, Styled};
 /// A `Span` is the smallest unit of text that can be styled. It is usually combined in the [`Line`]
 /// type to represent a line of text where each `Span` may have a different style.
 ///
+/// # Constructor Methods
+///
+/// - [`Span::default`] creates an span with empty content and the default style.
+/// - [`Span::raw`] creates an span with the specified content and the default style.
+/// - [`Span::styled`] creates an span with the specified content and style.
+///
+/// # Setter Methods
+///
+/// These methods are fluent setters. They return a new `Span` with the specified property set.
+///
+/// - [`Span::content`] sets the content of the span.
+/// - [`Span::style`] sets the style of the span.
+///
+/// # Other Methods
+///
+/// - [`Span::patch_style`] patches the style of the span, adding modifiers from the given style.
+/// - [`Span::reset_style`] resets the style of the span.
+/// - [`Span::width`] returns the unicode width of the content held by this span.
+/// - [`Span::styled_graphemes`] returns an iterator over the graphemes held by this span.
+///
 /// # Examples
 ///
 /// A `Span` with `style` set to [`Style::default()`] can be created from a `&str`, a `String`, or
@@ -35,12 +55,14 @@ use crate::style::{Style, Styled};
 ///
 /// let span = Span::styled("test content", Style::new().green());
 /// let span = Span::styled(String::from("test content"), Style::new().green());
+///
+/// // using Stylize trait shortcuts
 /// let span = "test content".green();
 /// let span = String::from("test content").green();
 /// ```
 ///
-/// `Span` implements [`Stylize`], which allows it to be styled using the shortcut methods. Styles
-/// applied are additive.
+/// `Span` implements the [`Styled`] trait, which allows it to be styled using the shortcut methods
+/// defined in the [`Stylize`] trait.
 ///
 /// ```rust
 /// use ratatui::prelude::*;
@@ -100,6 +122,82 @@ impl<'a> Span<'a> {
         }
     }
 
+    /// Sets the content of the span.
+    ///
+    /// This is a fluent setter method which must be chained or used as it consumes self
+    ///
+    /// Accepts any type that can be converted to [`Cow<str>`] (e.g. `&str`, `String`, `&String`,
+    /// etc.).
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// # use ratatui::prelude::*;
+    /// let mut span = Span::default().content("content");
+    /// ```
+    #[must_use = "method moves the value of self and returns the modified value"]
+    pub fn content<T>(mut self, content: T) -> Self
+    where
+        T: Into<Cow<'a, str>>,
+    {
+        self.content = content.into();
+        self
+    }
+
+    /// Sets the style of the span.
+    ///
+    /// This is a fluent setter method which must be chained or used as it consumes self
+    ///
+    /// In contrast to [`Span::patch_style`], this method replaces the style of the span instead of
+    /// patching it.
+    ///
+    /// Accepts any type that can be converted to [`Style`]
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// # use ratatui::prelude::*;
+    /// let mut span = Span::default().style(Style::new().green());
+    /// ```
+    #[must_use = "method moves the value of self and returns the modified value"]
+    pub fn style<T>(mut self, style: T) -> Self
+    where
+        T: Into<Style>,
+    {
+        self.style = style.into();
+        self
+    }
+
+    /// Patches the style of the Span, adding modifiers from the given style.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// # use ratatui::prelude::*;
+    /// let mut span = Span::styled("test content", Style::new().green().italic());
+    /// span.patch_style(Style::new().red().on_yellow().bold());
+    /// assert_eq!(span.style, Style::new().red().on_yellow().italic().bold());
+    /// ```
+    pub fn patch_style(&mut self, style: Style) {
+        self.style = self.style.patch(style);
+    }
+
+    /// Resets the style of the Span.
+    ///
+    /// This is Equivalent to calling `patch_style(Style::reset())`.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// # use ratatui::prelude::*;
+    /// let mut span = Span::styled("Test Content", Style::new().green().on_yellow().italic());
+    /// span.reset_style();
+    /// assert_eq!(span.style, Style::reset());
+    /// ```
+    pub fn reset_style(&mut self) {
+        self.patch_style(Style::reset());
+    }
+
     /// Returns the unicode width of the content held by this span.
     pub fn width(&self) -> usize {
         self.content.width()
@@ -141,36 +239,6 @@ impl<'a> Span<'a> {
                 style: base_style.patch(self.style),
             })
     }
-
-    /// Patches the style of the Span, adding modifiers from the given style.
-    ///
-    /// # Example
-    ///
-    /// ```rust
-    /// # use ratatui::prelude::*;
-    /// let mut span = Span::styled("test content", Style::new().green().italic());
-    /// span.patch_style(Style::new().red().on_yellow().bold());
-    /// assert_eq!(span.style, Style::new().red().on_yellow().italic().bold());
-    /// ```
-    pub fn patch_style(&mut self, style: Style) {
-        self.style = self.style.patch(style);
-    }
-
-    /// Resets the style of the Span.
-    ///
-    /// This is Equivalent to calling `patch_style(Style::reset())`.
-    ///
-    /// # Example
-    ///
-    /// ```rust
-    /// # use ratatui::prelude::*;
-    /// let mut span = Span::styled("Test Content", Style::new().green().on_yellow().italic());
-    /// span.reset_style();
-    /// assert_eq!(span.style, Style::reset());
-    /// ```
-    pub fn reset_style(&mut self) {
-        self.patch_style(Style::reset());
-    }
 }
 
 impl<'a, T> From<T> for Span<'a>
@@ -239,6 +307,18 @@ mod tests {
         assert_eq!(span.style, style);
     }
 
+    #[test]
+    fn set_content() {
+        let span = Span::default().content("test content");
+        assert_eq!(span.content, Cow::Borrowed("test content"));
+    }
+
+    #[test]
+    fn set_style() {
+        let span = Span::default().style(Style::new().green());
+        assert_eq!(span.style, Style::new().green());
+    }
+
     #[test]
     fn from_ref_str_borrowed_cow() {
         let content = "test content";

src/title.rs

@@ -87,7 +87,7 @@ pub enum Position {
 }
 
 impl<'a> Title<'a> {
-    /// Builder pattern method for setting the title content.
+    /// Set the title content.
     pub fn content<T>(mut self, content: T) -> Title<'a>
     where
         T: Into<Line<'a>>,
@@ -96,13 +96,15 @@ impl<'a> Title<'a> {
         self
     }
 
-    /// Builder pattern method for setting the title alignment.
+    /// Set the title alignment.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn alignment(mut self, alignment: Alignment) -> Title<'a> {
         self.alignment = Some(alignment);
         self
     }
 
-    /// Builder pattern method for setting the title position.
+    /// Set the title position.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn position(mut self, position: Position) -> Title<'a> {
         self.position = Some(position);
         self

src/widgets.rs

@@ -1,7 +1,7 @@
 //! `widgets` is a collection of types that implement [`Widget`] or [`StatefulWidget`] or both.
 //!
-//! All widgets are implemented using the builder pattern and are consumable objects. They are not
-//! meant to be stored but used as *commands* to draw common figures in the UI.
+//! Widgets are created for each frame as they are consumed after rendered.
+//! They are not meant to be stored but used as *commands* to draw common figures in the UI.
 //!
 //! The available widgets are:
 //! - [`Block`]: a basic widget that draws a block with optional borders, titles and styles.
@@ -43,10 +43,10 @@ use bitflags::bitflags;
 pub use self::{
     barchart::{Bar, BarChart, BarGroup},
     block::{Block, BorderType, Padding},
-    chart::{Axis, Chart, Dataset, GraphType},
+    chart::{Axis, Chart, Dataset, GraphType, LegendPosition},
     clear::Clear,
     gauge::{Gauge, LineGauge},
-    list::{List, ListItem, ListState},
+    list::{List, ListDirection, ListItem, ListState},
     paragraph::{Paragraph, Wrap},
     scrollbar::{ScrollDirection, Scrollbar, ScrollbarOrientation, ScrollbarState},
     sparkline::{RenderDirection, Sparkline},

src/widgets/barchart.rs

@@ -127,6 +127,7 @@ impl<'a> BarChart<'a> {
     }
 
     /// Surround the [`BarChart`] with a [`Block`].
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn block(mut self, block: Block<'a>) -> BarChart<'a> {
         self.block = Some(block);
         self
@@ -161,6 +162,7 @@ impl<'a> BarChart<'a> {
     /// // █ █ █
     /// // f b b
     /// ```
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn max(mut self, max: u64) -> BarChart<'a> {
         self.max = Some(max);
         self
@@ -170,6 +172,7 @@ impl<'a> BarChart<'a> {
     ///
     /// It is also possible to set individually the style of each [`Bar`].
     /// In this case the default style will be patched by the individual style
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn bar_style(mut self, style: Style) -> BarChart<'a> {
         self.bar_style = style;
         self
@@ -182,6 +185,7 @@ impl<'a> BarChart<'a> {
     ///
     /// If not set, this defaults to `1`.  
     /// The bar label also uses this value as its width.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn bar_width(mut self, width: u16) -> BarChart<'a> {
         self.bar_width = width;
         self
@@ -205,6 +209,7 @@ impl<'a> BarChart<'a> {
     /// // █   █
     /// // f   b
     /// ```
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn bar_gap(mut self, gap: u16) -> BarChart<'a> {
         self.bar_gap = gap;
         self
@@ -213,6 +218,7 @@ impl<'a> BarChart<'a> {
     /// The [`bar::Set`](crate::symbols::bar::Set) to use for displaying the bars.
     ///
     /// If not set, the default is [`bar::NINE_LEVELS`](crate::symbols::bar::NINE_LEVELS).
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn bar_set(mut self, bar_set: symbols::bar::Set) -> BarChart<'a> {
         self.bar_set = bar_set;
         self
@@ -226,6 +232,7 @@ impl<'a> BarChart<'a> {
     /// # See also
     ///
     /// [Bar::value_style] to set the value style individually.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn value_style(mut self, style: Style) -> BarChart<'a> {
         self.value_style = style;
         self
@@ -239,12 +246,14 @@ impl<'a> BarChart<'a> {
     /// # See also
     ///
     /// [Bar::label] to set the label style individually.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn label_style(mut self, style: Style) -> BarChart<'a> {
         self.label_style = style;
         self
     }
 
     /// Set the gap between [`BarGroup`].
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn group_gap(mut self, gap: u16) -> BarChart<'a> {
         self.group_gap = gap;
         self
@@ -253,6 +262,7 @@ impl<'a> BarChart<'a> {
     /// Set the style of the entire chart.
     ///
     /// The style will be applied to everything that isn't styled (borders, bars, labels, ...).
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn style(mut self, style: Style) -> BarChart<'a> {
         self.style = style;
         self
@@ -277,6 +287,7 @@ impl<'a> BarChart<'a> {
     ///
     /// █bar██
     /// ```
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn direction(mut self, direction: Direction) -> BarChart<'a> {
         self.direction = direction;
         self

src/widgets/barchart/bar.rs

@@ -49,6 +49,7 @@ impl<'a> Bar<'a> {
     ///
     /// [`Bar::value_style`] to style the value.  
     /// [`Bar::text_value`] to set the displayed value.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn value(mut self, value: u64) -> Bar<'a> {
         self.value = value;
         self
@@ -61,6 +62,7 @@ impl<'a> Bar<'a> {
     /// For [`Horizontal`](crate::layout::Direction::Horizontal) bars,
     /// display the label **in** the bar.  
     /// See [`BarChart::direction`](crate::widgets::BarChart::direction) to set the direction.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn label(mut self, label: Line<'a>) -> Bar<'a> {
         self.label = Some(label);
         self
@@ -70,6 +72,7 @@ impl<'a> Bar<'a> {
     ///
     /// This will apply to every non-styled element.
     /// It can be seen and used as a default value.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn style(mut self, style: Style) -> Bar<'a> {
         self.style = style;
         self
@@ -80,6 +83,7 @@ impl<'a> Bar<'a> {
     /// # See also
     ///
     /// [`Bar::value`] to set the value.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn value_style(mut self, style: Style) -> Bar<'a> {
         self.value_style = style;
         self
@@ -93,6 +97,7 @@ impl<'a> Bar<'a> {
     /// # See also
     ///
     /// [`Bar::value`] to set the value.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn text_value(mut self, text_value: String) -> Bar<'a> {
         self.text_value = Some(text_value);
         self

src/widgets/barchart/bar_group.rs

@@ -26,12 +26,14 @@ pub struct BarGroup<'a> {
 
 impl<'a> BarGroup<'a> {
     /// Set the group label
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn label(mut self, label: Line<'a>) -> BarGroup<'a> {
         self.label = Some(label);
         self
     }
 
     /// Set the bars of the group to be shown
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn bars(mut self, bars: &[Bar<'a>]) -> BarGroup<'a> {
         self.bars = bars.to_vec();
         self

src/widgets/block.rs

@@ -329,6 +329,7 @@ impl<'a> Block<'a> {
     /// Applies the style to all titles.
     ///
     /// If a [`Title`] already has a style, the title's style will add on top of this one.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub const fn title_style(mut self, style: Style) -> Block<'a> {
         self.titles_style = style;
         self
@@ -352,6 +353,7 @@ impl<'a> Block<'a> {
     ///     .title("bar")
     ///     .title_alignment(Alignment::Center);
     /// ```
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub const fn title_alignment(mut self, alignment: Alignment) -> Block<'a> {
         self.titles_alignment = alignment;
         self
@@ -381,6 +383,7 @@ impl<'a> Block<'a> {
     ///     .title("bar")
     ///     .title_position(Position::Bottom);
     /// ```
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub const fn title_position(mut self, position: Position) -> Block<'a> {
         self.titles_position = position;
         self
@@ -399,6 +402,7 @@ impl<'a> Block<'a> {
     ///     .borders(Borders::ALL)
     ///     .border_style(Style::new().blue());
     /// ```
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub const fn border_style(mut self, style: Style) -> Block<'a> {
         self.border_style = style;
         self
@@ -411,6 +415,7 @@ impl<'a> Block<'a> {
     /// [`Block::border_style`].
     ///
     /// This will also apply to the widget inside that block, unless the inner widget is styled.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub const fn style(mut self, style: Style) -> Block<'a> {
         self.style = style;
         self
@@ -433,6 +438,7 @@ impl<'a> Block<'a> {
     /// # use ratatui::{prelude::*, widgets::*};
     /// Block::default().borders(Borders::LEFT | Borders::RIGHT);
     /// ```
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub const fn borders(mut self, flag: Borders) -> Block<'a> {
         self.borders = flag;
         self
@@ -455,6 +461,7 @@ impl<'a> Block<'a> {
     /// // │     │
     /// // ╰─────╯
     /// ```
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub const fn border_type(mut self, border_type: BorderType) -> Block<'a> {
         self.border_set = border_type.to_border_set();
         self
@@ -473,6 +480,7 @@ impl<'a> Block<'a> {
     /// // ╔Block╗
     /// // ║     ║
     /// // ╚═════╝
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub const fn border_set(mut self, border_set: border::Set) -> Block<'a> {
         self.border_set = border_set;
         self
@@ -508,14 +516,15 @@ impl<'a> Block<'a> {
             inner.x = inner.x.saturating_add(1).min(inner.right());
             inner.width = inner.width.saturating_sub(1);
         }
-        if self.borders.intersects(Borders::TOP) || !self.titles.is_empty() {
+        if self.borders.intersects(Borders::TOP) || self.have_title_at_position(Position::Top) {
             inner.y = inner.y.saturating_add(1).min(inner.bottom());
             inner.height = inner.height.saturating_sub(1);
         }
         if self.borders.intersects(Borders::RIGHT) {
             inner.width = inner.width.saturating_sub(1);
         }
-        if self.borders.intersects(Borders::BOTTOM) {
+        if self.borders.intersects(Borders::BOTTOM) || self.have_title_at_position(Position::Bottom)
+        {
             inner.height = inner.height.saturating_sub(1);
         }
 
@@ -532,6 +541,12 @@ impl<'a> Block<'a> {
         inner
     }
 
+    fn have_title_at_position(&self, position: Position) -> bool {
+        self.titles
+            .iter()
+            .any(|title| title.position.unwrap_or(self.titles_position) == position)
+    }
+
     /// Defines the padding inside a `Block`.
     ///
     /// See [`Padding`] for more information.
@@ -562,6 +577,7 @@ impl<'a> Block<'a> {
     /// // │  content  │
     /// // └───────────┘
     /// ```
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub const fn padding(mut self, padding: Padding) -> Block<'a> {
         self.padding = padding;
         self
@@ -939,6 +955,78 @@ mod tests {
         );
     }
 
+    #[test]
+    fn inner_takes_into_account_border_and_title() {
+        let test_rect = Rect::new(0, 0, 0, 2);
+
+        let top_top = Block::default()
+            .title(Title::from("Test").position(Position::Top))
+            .borders(Borders::TOP);
+        assert_eq!(top_top.inner(test_rect), Rect::new(0, 1, 0, 1));
+
+        let top_bot = Block::default()
+            .title(Title::from("Test").position(Position::Top))
+            .borders(Borders::BOTTOM);
+        assert_eq!(top_bot.inner(test_rect), Rect::new(0, 1, 0, 0));
+
+        let bot_top = Block::default()
+            .title(Title::from("Test").position(Position::Bottom))
+            .borders(Borders::TOP);
+        assert_eq!(bot_top.inner(test_rect), Rect::new(0, 1, 0, 0));
+
+        let bot_bot = Block::default()
+            .title(Title::from("Test").position(Position::Bottom))
+            .borders(Borders::BOTTOM);
+        assert_eq!(bot_bot.inner(test_rect), Rect::new(0, 0, 0, 1));
+    }
+
+    #[test]
+    fn have_title_at_position_takes_into_account_all_positioning_declarations() {
+        let block = Block::default();
+        assert!(!block.have_title_at_position(Position::Top));
+        assert!(!block.have_title_at_position(Position::Bottom));
+
+        let block = Block::default().title(Title::from("Test").position(Position::Top));
+        assert!(block.have_title_at_position(Position::Top));
+        assert!(!block.have_title_at_position(Position::Bottom));
+
+        let block = Block::default().title(Title::from("Test").position(Position::Bottom));
+        assert!(!block.have_title_at_position(Position::Top));
+        assert!(block.have_title_at_position(Position::Bottom));
+
+        let block = Block::default()
+            .title(Title::from("Test").position(Position::Top))
+            .title_position(Position::Bottom);
+        assert!(block.have_title_at_position(Position::Top));
+        assert!(!block.have_title_at_position(Position::Bottom));
+
+        let block = Block::default()
+            .title(Title::from("Test").position(Position::Bottom))
+            .title_position(Position::Top);
+        assert!(!block.have_title_at_position(Position::Top));
+        assert!(block.have_title_at_position(Position::Bottom));
+
+        let block = Block::default()
+            .title(Title::from("Test").position(Position::Top))
+            .title(Title::from("Test").position(Position::Bottom));
+        assert!(block.have_title_at_position(Position::Top));
+        assert!(block.have_title_at_position(Position::Bottom));
+
+        let block = Block::default()
+            .title(Title::from("Test").position(Position::Top))
+            .title(Title::from("Test"))
+            .title_position(Position::Bottom);
+        assert!(block.have_title_at_position(Position::Top));
+        assert!(block.have_title_at_position(Position::Bottom));
+
+        let block = Block::default()
+            .title(Title::from("Test"))
+            .title(Title::from("Test").position(Position::Bottom))
+            .title_position(Position::Top);
+        assert!(block.have_title_at_position(Position::Top));
+        assert!(block.have_title_at_position(Position::Bottom));
+    }
+
     #[test]
     fn border_type_can_be_const() {
         const _PLAIN: border::Set = BorderType::border_symbols(BorderType::Plain);

src/widgets/canvas/line.rs

@@ -128,7 +128,7 @@ mod tests {
 
         let mut expected = Buffer::with_lines(expected_lines);
         for cell in expected.content.iter_mut() {
-            if cell.symbol == "•" {
+            if cell.symbol() == "•" {
                 cell.set_style(Style::new().red());
             }
         }

src/widgets/chart.rs

@@ -39,28 +39,19 @@ impl<'a> Axis<'a> {
         self
     }
 
-    #[deprecated(
-        since = "0.10.0",
-        note = "You should use styling capabilities of `text::Line` given as argument of the `title` method to apply styling to the title."
-    )]
-    pub fn title_style(mut self, style: Style) -> Axis<'a> {
-        if let Some(t) = self.title {
-            let title = String::from(t);
-            self.title = Some(TextLine::from(Span::styled(title, style)));
-        }
-        self
-    }
-
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn bounds(mut self, bounds: [f64; 2]) -> Axis<'a> {
         self.bounds = bounds;
         self
     }
 
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn labels(mut self, labels: Vec<Span<'a>>) -> Axis<'a> {
         self.labels = Some(labels);
         self
     }
 
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn style(mut self, style: Style) -> Axis<'a> {
         self.style = style;
         self
@@ -70,6 +61,7 @@ impl<'a> Axis<'a> {
     /// The alignment behaves differently based on the axis:
     /// - Y-Axis: The labels are aligned within the area on the left of the axis
     /// - X-Axis: The first X-axis label is aligned relative to the Y-axis
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn labels_alignment(mut self, alignment: Alignment) -> Axis<'a> {
         self.labels_alignment = alignment;
         self
@@ -86,6 +78,113 @@ pub enum GraphType {
     Line,
 }
 
+#[derive(Debug, Default, Clone, Copy, Eq, PartialEq)]
+pub enum LegendPosition {
+    Top,
+    #[default]
+    TopRight,
+    TopLeft,
+    Left,
+    Right,
+    Bottom,
+    BottomRight,
+    BottomLeft,
+}
+
+impl LegendPosition {
+    fn layout(
+        &self,
+        area: Rect,
+        legend_width: u16,
+        legend_height: u16,
+        x_title_width: u16,
+        y_title_width: u16,
+    ) -> Option<Rect> {
+        let mut height_margin = (area.height - legend_height) as i32;
+        if x_title_width != 0 {
+            height_margin -= 1;
+        }
+        if y_title_width != 0 {
+            height_margin -= 1;
+        }
+        if height_margin < 0 {
+            return None;
+        };
+
+        let (x, y) = match self {
+            Self::TopRight => {
+                if legend_width + y_title_width > area.width {
+                    (area.right() - legend_width, area.top() + 1)
+                } else {
+                    (area.right() - legend_width, area.top())
+                }
+            }
+            Self::TopLeft => {
+                if y_title_width != 0 {
+                    (area.left(), area.top() + 1)
+                } else {
+                    (area.left(), area.top())
+                }
+            }
+            Self::Top => {
+                let x = (area.width - legend_width) / 2;
+                if area.left() + y_title_width > x {
+                    (area.left() + x, area.top() + 1)
+                } else {
+                    (area.left() + x, area.top())
+                }
+            }
+            Self::Left => {
+                let mut y = (area.height - legend_height) / 2;
+                if y_title_width != 0 {
+                    y += 1;
+                }
+                if x_title_width != 0 {
+                    y = y.saturating_sub(1);
+                }
+                (area.left(), area.top() + y)
+            }
+            Self::Right => {
+                let mut y = (area.height - legend_height) / 2;
+                if y_title_width != 0 {
+                    y += 1;
+                }
+                if x_title_width != 0 {
+                    y = y.saturating_sub(1);
+                }
+                (area.right() - legend_width, area.top() + y)
+            }
+            Self::BottomLeft => {
+                if x_title_width + legend_width > area.width {
+                    (area.left(), area.bottom() - legend_height - 1)
+                } else {
+                    (area.left(), area.bottom() - legend_height)
+                }
+            }
+            Self::BottomRight => {
+                if x_title_width != 0 {
+                    (
+                        area.right() - legend_width,
+                        area.bottom() - legend_height - 1,
+                    )
+                } else {
+                    (area.right() - legend_width, area.bottom() - legend_height)
+                }
+            }
+            Self::Bottom => {
+                let x = area.left() + (area.width - legend_width) / 2;
+                if x + legend_width > area.right() - x_title_width {
+                    (x, area.bottom() - legend_height - 1)
+                } else {
+                    (x, area.bottom() - legend_height)
+                }
+            }
+        };
+
+        Some(Rect::new(x, y, legend_width, legend_height))
+    }
+}
+
 /// A group of data points
 #[derive(Debug, Default, Clone, PartialEq)]
 pub struct Dataset<'a> {
@@ -110,21 +209,25 @@ impl<'a> Dataset<'a> {
         self
     }
 
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn data(mut self, data: &'a [(f64, f64)]) -> Dataset<'a> {
         self.data = data;
         self
     }
 
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn marker(mut self, marker: symbols::Marker) -> Dataset<'a> {
         self.marker = marker;
         self
     }
 
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn graph_type(mut self, graph_type: GraphType) -> Dataset<'a> {
         self.graph_type = graph_type;
         self
     }
 
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn style(mut self, style: Style) -> Dataset<'a> {
         self.style = style;
         self
@@ -201,6 +304,9 @@ pub struct Chart<'a> {
     style: Style,
     /// Constraints used to determine whether the legend should be shown or not
     hidden_legend_constraints: (Constraint, Constraint),
+    /// The position detnermine where the legenth is shown or hide regaurdless of
+    /// `hidden_legend_constraints`
+    legend_position: Option<LegendPosition>,
 }
 
 impl<'a> Chart<'a> {
@@ -212,24 +318,29 @@ impl<'a> Chart<'a> {
             style: Style::default(),
             datasets,
             hidden_legend_constraints: (Constraint::Ratio(1, 4), Constraint::Ratio(1, 4)),
+            legend_position: Some(LegendPosition::default()),
         }
     }
 
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn block(mut self, block: Block<'a>) -> Chart<'a> {
         self.block = Some(block);
         self
     }
 
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn style(mut self, style: Style) -> Chart<'a> {
         self.style = style;
         self
     }
 
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn x_axis(mut self, axis: Axis<'a>) -> Chart<'a> {
         self.x_axis = axis;
         self
     }
 
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn y_axis(mut self, axis: Axis<'a>) -> Chart<'a> {
         self.y_axis = axis;
         self
@@ -250,11 +361,29 @@ impl<'a> Chart<'a> {
     /// let _chart: Chart = Chart::new(vec![])
     ///     .hidden_legend_constraints(constraints);
     /// ```
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn hidden_legend_constraints(mut self, constraints: (Constraint, Constraint)) -> Chart<'a> {
         self.hidden_legend_constraints = constraints;
         self
     }
 
+    /// Set the position of a legend or hide it.
+    ///
+    /// If [`None`], hide the legend even if satisfied with
+    /// [`hidden_legend_constraints`](Self::hidden_legend_constraints)
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use ratatui::widgets::{Chart, LegendPosition};
+    /// let _chart: Chart = Chart::new(vec![])
+    ///     .legend_position(Some(LegendPosition::TopLeft));
+    /// ```
+    pub fn legend_position(mut self, position: Option<LegendPosition>) -> Chart<'a> {
+        self.legend_position = position;
+        self
+    }
+
     /// Compute the internal layout of the chart given the area. If the area is too small some
     /// elements may be automatically hidden
     fn layout(&self, area: Rect) -> ChartLayout {
@@ -301,27 +430,38 @@ impl<'a> Chart<'a> {
             }
         }
 
-        if let Some(inner_width) = self.datasets.iter().map(|d| d.name.width() as u16).max() {
-            let legend_width = inner_width + 2;
-            let legend_height = self.datasets.len() as u16 + 2;
-            let max_legend_width = self
-                .hidden_legend_constraints
-                .0
-                .apply(layout.graph_area.width);
-            let max_legend_height = self
-                .hidden_legend_constraints
-                .1
-                .apply(layout.graph_area.height);
-            if inner_width > 0
-                && legend_width < max_legend_width
-                && legend_height < max_legend_height
-            {
-                layout.legend_area = Some(Rect::new(
-                    layout.graph_area.right() - legend_width,
-                    layout.graph_area.top(),
-                    legend_width,
-                    legend_height,
-                ));
+        if let Some(legend_position) = self.legend_position {
+            if let Some(inner_width) = self.datasets.iter().map(|d| d.name.width() as u16).max() {
+                let legend_width = inner_width + 2;
+                let legend_height = self.datasets.len() as u16 + 2;
+                let max_legend_width = self
+                    .hidden_legend_constraints
+                    .0
+                    .apply(layout.graph_area.width);
+                let max_legend_height = self
+                    .hidden_legend_constraints
+                    .1
+                    .apply(layout.graph_area.height);
+                if inner_width > 0
+                    && legend_width <= max_legend_width
+                    && legend_height <= max_legend_height
+                {
+                    layout.legend_area = legend_position.layout(
+                        layout.graph_area,
+                        legend_width,
+                        legend_height,
+                        layout
+                            .title_x
+                            .and(self.x_axis.title.as_ref())
+                            .map(|t| t.width() as u16)
+                            .unwrap_or_default(),
+                        layout
+                            .title_y
+                            .and(self.y_axis.title.as_ref())
+                            .map(|t| t.width() as u16)
+                            .unwrap_or_default(),
+                    );
+                }
             }
         }
         layout
@@ -335,7 +475,12 @@ impl<'a> Chart<'a> {
             .map(|l| l.iter().map(Span::width).max().unwrap_or_default() as u16)
             .unwrap_or_default();
 
-        if let Some(first_x_label) = self.x_axis.labels.as_ref().and_then(|labels| labels.get(0)) {
+        if let Some(first_x_label) = self
+            .x_axis
+            .labels
+            .as_ref()
+            .and_then(|labels| labels.first())
+        {
             let first_label_width = first_x_label.content.width() as u16;
             let width_left_of_y_axis = match self.x_axis.labels_alignment {
                 Alignment::Left => {
@@ -540,24 +685,12 @@ impl<'a> Widget for Chart<'a> {
                 .render(graph_area, buf);
         }
 
-        if let Some(legend_area) = layout.legend_area {
-            buf.set_style(legend_area, original_style);
-            Block::default()
-                .borders(Borders::ALL)
-                .render(legend_area, buf);
-            for (i, dataset) in self.datasets.iter().enumerate() {
-                buf.set_string(
-                    legend_area.x + 1,
-                    legend_area.y + 1 + i as u16,
-                    &dataset.name,
-                    dataset.style,
-                );
-            }
-        }
-
         if let Some((x, y)) = layout.title_x {
             let title = self.x_axis.title.unwrap();
-            let width = title.width() as u16;
+            let width = graph_area
+                .right()
+                .saturating_sub(x)
+                .min(title.width() as u16);
             buf.set_style(
                 Rect {
                     x,
@@ -572,7 +705,10 @@ impl<'a> Widget for Chart<'a> {
 
         if let Some((x, y)) = layout.title_y {
             let title = self.y_axis.title.unwrap();
-            let width = title.width() as u16;
+            let width = graph_area
+                .right()
+                .saturating_sub(x)
+                .min(title.width() as u16);
             buf.set_style(
                 Rect {
                     x,
@@ -584,6 +720,21 @@ impl<'a> Widget for Chart<'a> {
             );
             buf.set_line(x, y, &title, width);
         }
+
+        if let Some(legend_area) = layout.legend_area {
+            buf.set_style(legend_area, original_style);
+            Block::default()
+                .borders(Borders::ALL)
+                .render(legend_area, buf);
+            for (i, dataset) in self.datasets.iter().enumerate() {
+                buf.set_string(
+                    legend_area.x + 1,
+                    legend_area.y + 1 + i as u16,
+                    &dataset.name,
+                    dataset.style,
+                );
+            }
+        }
     }
 }
 
@@ -726,4 +877,295 @@ mod tests {
 
         assert_eq!(buffer, Buffer::with_lines(vec![" ".repeat(8); 4]))
     }
+
+    #[test]
+    fn test_chart_have_a_topleft_legend() {
+        let chart = Chart::new(vec![Dataset::default().name("Ds1")])
+            .legend_position(Some(LegendPosition::TopLeft));
+
+        let area = Rect::new(0, 0, 30, 20);
+        let mut buffer = Buffer::empty(area);
+
+        chart.render(buffer.area, &mut buffer);
+
+        let expected = Buffer::with_lines(vec![
+            "┌───┐                         ",
+            "│Ds1│                         ",
+            "└───┘                         ",
+            "                              ",
+            "                              ",
+            "                              ",
+            "                              ",
+            "                              ",
+            "                              ",
+            "                              ",
+            "                              ",
+            "                              ",
+            "                              ",
+            "                              ",
+            "                              ",
+            "                              ",
+            "                              ",
+            "                              ",
+            "                              ",
+            "                              ",
+        ]);
+
+        assert_eq!(buffer, expected);
+    }
+
+    #[test]
+    fn test_chart_have_a_long_y_axis_title_overlapping_legend() {
+        let chart = Chart::new(vec![Dataset::default().name("Ds1")])
+            .y_axis(Axis::default().title("The title overlap a legend."));
+
+        let area = Rect::new(0, 0, 30, 20);
+        let mut buffer = Buffer::empty(area);
+
+        chart.render(buffer.area, &mut buffer);
+
+        let expected = Buffer::with_lines(vec![
+            "The title overlap a legend.   ",
+            "                         ┌───┐",
+            "                         │Ds1│",
+            "                         └───┘",
+            "                              ",
+            "                              ",
+            "                              ",
+            "                              ",
+            "                              ",
+            "                              ",
+            "                              ",
+            "                              ",
+            "                              ",
+            "                              ",
+            "                              ",
+            "                              ",
+            "                              ",
+            "                              ",
+            "                              ",
+            "                              ",
+        ]);
+
+        assert_eq!(buffer, expected);
+    }
+
+    #[test]
+    fn test_chart_have_overflowed_y_axis() {
+        let chart = Chart::new(vec![Dataset::default().name("Ds1")])
+            .y_axis(Axis::default().title("The title overlap a legend."));
+
+        let area = Rect::new(0, 0, 10, 10);
+        let mut buffer = Buffer::empty(area);
+
+        chart.render(buffer.area, &mut buffer);
+
+        let expected = Buffer::with_lines(vec![
+            "          ",
+            "          ",
+            "          ",
+            "          ",
+            "          ",
+            "          ",
+            "          ",
+            "          ",
+            "          ",
+            "          ",
+        ]);
+
+        assert_eq!(buffer, expected);
+    }
+
+    #[test]
+    fn test_legend_area_can_fit_same_chart_area() {
+        let name = "Data";
+        let chart = Chart::new(vec![Dataset::default().name(name)])
+            .hidden_legend_constraints((Constraint::Percentage(100), Constraint::Percentage(100)));
+
+        let area = Rect::new(0, 0, name.len() as u16 + 2, 3);
+        let mut buffer = Buffer::empty(area);
+
+        let expected = Buffer::with_lines(vec!["┌────┐", "│Data│", "└────┘"]);
+
+        [
+            LegendPosition::TopLeft,
+            LegendPosition::Top,
+            LegendPosition::TopRight,
+            LegendPosition::Left,
+            LegendPosition::Right,
+            LegendPosition::Bottom,
+            LegendPosition::BottomLeft,
+            LegendPosition::BottomRight,
+        ]
+        .iter()
+        .for_each(|&position| {
+            let chart = chart.clone().legend_position(Some(position));
+            buffer.reset();
+            chart.render(buffer.area, &mut buffer);
+            assert_eq!(buffer, expected);
+        });
+    }
+
+    #[test]
+    fn test_legend_of_chart_have_odd_margin_size() {
+        let name = "Data";
+        let base_chart = Chart::new(vec![Dataset::default().name(name)])
+            .hidden_legend_constraints((Constraint::Percentage(100), Constraint::Percentage(100)));
+
+        let area = Rect::new(0, 0, name.len() as u16 + 2 + 3, 3 + 3);
+        let mut buffer = Buffer::empty(area);
+
+        let chart = base_chart
+            .clone()
+            .legend_position(Some(LegendPosition::TopLeft));
+        buffer.reset();
+        chart.render(buffer.area, &mut buffer);
+        assert_eq!(
+            buffer,
+            Buffer::with_lines(vec![
+                "┌────┐   ",
+                "│Data│   ",
+                "└────┘   ",
+                "         ",
+                "         ",
+                "         ",
+            ])
+        );
+        buffer.reset();
+
+        let chart = base_chart
+            .clone()
+            .legend_position(Some(LegendPosition::Top));
+        buffer.reset();
+        chart.render(buffer.area, &mut buffer);
+        assert_eq!(
+            buffer,
+            Buffer::with_lines(vec![
+                " ┌────┐  ",
+                " │Data│  ",
+                " └────┘  ",
+                "         ",
+                "         ",
+                "         ",
+            ])
+        );
+
+        let chart = base_chart
+            .clone()
+            .legend_position(Some(LegendPosition::TopRight));
+        buffer.reset();
+        chart.render(buffer.area, &mut buffer);
+        assert_eq!(
+            buffer,
+            Buffer::with_lines(vec![
+                "   ┌────┐",
+                "   │Data│",
+                "   └────┘",
+                "         ",
+                "         ",
+                "         ",
+            ])
+        );
+
+        let chart = base_chart
+            .clone()
+            .legend_position(Some(LegendPosition::Left));
+        buffer.reset();
+        chart.render(buffer.area, &mut buffer);
+        assert_eq!(
+            buffer,
+            Buffer::with_lines(vec![
+                "         ",
+                "┌────┐   ",
+                "│Data│   ",
+                "└────┘   ",
+                "         ",
+                "         ",
+            ])
+        );
+        buffer.reset();
+
+        let chart = base_chart
+            .clone()
+            .legend_position(Some(LegendPosition::Right));
+        buffer.reset();
+        chart.render(buffer.area, &mut buffer);
+        assert_eq!(
+            buffer,
+            Buffer::with_lines(vec![
+                "         ",
+                "   ┌────┐",
+                "   │Data│",
+                "   └────┘",
+                "         ",
+                "         ",
+            ])
+        );
+
+        let chart = base_chart
+            .clone()
+            .legend_position(Some(LegendPosition::BottomLeft));
+        buffer.reset();
+        chart.render(buffer.area, &mut buffer);
+        assert_eq!(
+            buffer,
+            Buffer::with_lines(vec![
+                "         ",
+                "         ",
+                "         ",
+                "┌────┐   ",
+                "│Data│   ",
+                "└────┘   ",
+            ])
+        );
+
+        let chart = base_chart
+            .clone()
+            .legend_position(Some(LegendPosition::Bottom));
+        buffer.reset();
+        chart.render(buffer.area, &mut buffer);
+        assert_eq!(
+            buffer,
+            Buffer::with_lines(vec![
+                "         ",
+                "         ",
+                "         ",
+                " ┌────┐  ",
+                " │Data│  ",
+                " └────┘  ",
+            ])
+        );
+
+        let chart = base_chart
+            .clone()
+            .legend_position(Some(LegendPosition::BottomRight));
+        buffer.reset();
+        chart.render(buffer.area, &mut buffer);
+        assert_eq!(
+            buffer,
+            Buffer::with_lines(vec![
+                "         ",
+                "         ",
+                "         ",
+                "   ┌────┐",
+                "   │Data│",
+                "   └────┘",
+            ])
+        );
+
+        let chart = base_chart.clone().legend_position(None);
+        buffer.reset();
+        chart.render(buffer.area, &mut buffer);
+        assert_eq!(
+            buffer,
+            Buffer::with_lines(vec![
+                "         ",
+                "         ",
+                "         ",
+                "         ",
+                "         ",
+                "         ",
+            ])
+        );
+    }
 }

src/widgets/gauge.rs

@@ -66,6 +66,7 @@ impl<'a> Gauge<'a> {
     ///
     /// The gauge is rendered in the inner portion of the block once space for borders and padding
     /// is reserved. Styles set on the block do **not** affect the bar itself.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn block(mut self, block: Block<'a>) -> Gauge<'a> {
         self.block = Some(block);
         self
@@ -80,6 +81,7 @@ impl<'a> Gauge<'a> {
     /// # See also
     ///
     /// See [`Gauge::ratio`] to set from a float.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn percent(mut self, percent: u16) -> Gauge<'a> {
         assert!(
             percent <= 100,
@@ -101,6 +103,7 @@ impl<'a> Gauge<'a> {
     /// # See also
     ///
     /// See [`Gauge::percent`] to set from a percentage.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn ratio(mut self, ratio: f64) -> Gauge<'a> {
         assert!(
             (0.0..=1.0).contains(&ratio),
@@ -114,6 +117,7 @@ impl<'a> Gauge<'a> {
     ///
     /// For a left-aligned label, see [`LineGauge`].
     /// If the label is not defined, it is the percentage filled.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn label<T>(mut self, label: T) -> Gauge<'a>
     where
         T: Into<Span<'a>>,
@@ -126,12 +130,14 @@ impl<'a> Gauge<'a> {
     ///
     /// This will style the block (if any non-styled) and background of the widget (everything
     /// except the bar itself). [`Block`] style set with [`Gauge::block`] takes precedence.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn style(mut self, style: Style) -> Gauge<'a> {
         self.style = style;
         self
     }
 
     /// Sets the style of the bar.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn gauge_style(mut self, style: Style) -> Gauge<'a> {
         self.gauge_style = style;
         self
@@ -142,6 +148,7 @@ impl<'a> Gauge<'a> {
     /// This enables the use of
     /// [unicode block characters](https://en.wikipedia.org/wiki/Block_Elements).
     /// This is useful to display a higher precision bar (8 extra fractional parts per cell).
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn use_unicode(mut self, unicode: bool) -> Gauge<'a> {
         self.use_unicode = unicode;
         self
@@ -265,6 +272,7 @@ pub struct LineGauge<'a> {
 
 impl<'a> LineGauge<'a> {
     /// Surrounds the `LineGauge` with a [`Block`].
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn block(mut self, block: Block<'a>) -> Self {
         self.block = Some(block);
         self
@@ -278,6 +286,7 @@ impl<'a> LineGauge<'a> {
     /// # Panics
     ///
     /// This method panics if `ratio` is **not** between 0 and 1 inclusively.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn ratio(mut self, ratio: f64) -> Self {
         assert!(
             (0.0..=1.0).contains(&ratio),
@@ -294,6 +303,7 @@ impl<'a> LineGauge<'a> {
     /// See [`symbols::line::Set`] for more information. Predefined sets are also available, see
     /// [`NORMAL`](symbols::line::NORMAL), [`DOUBLE`](symbols::line::DOUBLE) and
     /// [`THICK`](symbols::line::THICK).
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn line_set(mut self, set: symbols::line::Set) -> Self {
         self.line_set = set;
         self
@@ -315,12 +325,14 @@ impl<'a> LineGauge<'a> {
     ///
     /// This will style everything except the bar itself, so basically the block (if any) and
     /// background.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn style(mut self, style: Style) -> Self {
         self.style = style;
         self
     }
 
     /// Sets the style of the bar.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn gauge_style(mut self, style: Style) -> Self {
         self.gauge_style = style;
         self
@@ -419,19 +431,19 @@ mod tests {
     #[test]
     #[should_panic]
     fn gauge_invalid_percentage() {
-        Gauge::default().percent(110);
+        let _ = Gauge::default().percent(110);
     }
 
     #[test]
     #[should_panic]
     fn gauge_invalid_ratio_upper_bound() {
-        Gauge::default().ratio(1.1);
+        let _ = Gauge::default().ratio(1.1);
     }
 
     #[test]
     #[should_panic]
     fn gauge_invalid_ratio_lower_bound() {
-        Gauge::default().ratio(-0.5);
+        let _ = Gauge::default().ratio(-0.5);
     }
 
     #[test]

src/widgets/paragraph.rs

@@ -6,7 +6,7 @@ use crate::{
     style::{Style, Styled},
     text::{StyledGrapheme, Text},
     widgets::{
-        reflow::{LineComposer, LineTruncator, WordWrapper},
+        reflow::{LineComposer, LineTruncator, WordWrapper, WrappedLine},
         Block, Widget,
     },
 };
@@ -138,6 +138,7 @@ impl<'a> Paragraph<'a> {
     ///         .title("Paragraph")
     ///         .borders(Borders::ALL));
     /// ```
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn block(mut self, block: Block<'a>) -> Paragraph<'a> {
         self.block = Some(block);
         self
@@ -155,6 +156,7 @@ impl<'a> Paragraph<'a> {
     /// let paragraph = Paragraph::new("Hello, world!")
     ///    .style(Style::new().red().on_white());
     /// ```
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn style(mut self, style: Style) -> Paragraph<'a> {
         self.style = style;
         self
@@ -171,6 +173,7 @@ impl<'a> Paragraph<'a> {
     /// let paragraph = Paragraph::new("Hello, world!")
     ///   .wrap(Wrap { trim: true });
     /// ```
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn wrap(mut self, wrap: Wrap) -> Paragraph<'a> {
         self.wrap = Some(wrap);
         self
@@ -187,6 +190,7 @@ impl<'a> Paragraph<'a> {
     ///
     /// For more information about future scrolling design and concerns, see [RFC: Design of
     /// Scrollable Widgets](https://github.com/ratatui-org/ratatui/issues/174) on GitHub.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn scroll(mut self, offset: (Vertical, Horizontal)) -> Paragraph<'a> {
         self.scroll = offset;
         self
@@ -204,10 +208,82 @@ impl<'a> Paragraph<'a> {
     /// let paragraph = Paragraph::new("Hello World")
     ///     .alignment(Alignment::Center);
     /// ```
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn alignment(mut self, alignment: Alignment) -> Paragraph<'a> {
         self.alignment = alignment;
         self
     }
+
+    /// Calculates the number of lines needed to fully render.
+    ///
+    /// Given a max line width, this method calculates the number of lines that a paragraph will
+    /// need in order to be fully rendered. For paragraphs that do not use wrapping, this count is
+    /// simply the number of lines present in the paragraph.
+    ///
+    /// # Example
+    ///
+    /// ```ignore
+    /// # use ratatui::{prelude::*, widgets::*};
+    /// let paragraph = Paragraph::new("Hello World")
+    ///     .wrap(Wrap { trim: false });
+    /// assert_eq!(paragraph.line_count(20), 1);
+    /// assert_eq!(paragraph.line_count(10), 2);
+    /// ```
+    #[stability::unstable(
+        feature = "rendered-line-info",
+        reason = "The design for text wrapping is not stable and might affect this API.",
+        issue = "https://github.com/ratatui-org/ratatui/issues/293"
+    )]
+    pub fn line_count(&self, width: u16) -> usize {
+        if width < 1 {
+            return 0;
+        }
+
+        if let Some(Wrap { trim }) = self.wrap {
+            let styled = self.text.lines.iter().map(|line| {
+                let graphemes = line
+                    .spans
+                    .iter()
+                    .flat_map(|span| span.styled_graphemes(self.style));
+                let alignment = line.alignment.unwrap_or(self.alignment);
+                (graphemes, alignment)
+            });
+            let mut line_composer = WordWrapper::new(styled, width, trim);
+            let mut count = 0;
+            while line_composer.next_line().is_some() {
+                count += 1;
+            }
+            count
+        } else {
+            self.text.lines.len()
+        }
+    }
+
+    /// Calculates the shortest line width needed to avoid any word being wrapped or truncated.
+    ///
+    /// # Example
+    ///
+    /// ```ignore
+    /// # use ratatui::{prelude::*, widgets::*};
+    /// let paragraph = Paragraph::new("Hello World");
+    /// assert_eq!(paragraph.line_width(), 11);
+    ///
+    /// let paragraph = Paragraph::new("Hello World\nhi\nHello World!!!");
+    /// assert_eq!(paragraph.line_width(), 14);
+    /// ```
+    #[stability::unstable(
+        feature = "rendered-line-info",
+        reason = "The design for text wrapping is not stable and might affect this API.",
+        issue = "https://github.com/ratatui-org/ratatui/issues/293"
+    )]
+    pub fn line_width(&self) -> usize {
+        self.text
+            .lines
+            .iter()
+            .map(|l| l.width())
+            .max()
+            .unwrap_or_default()
+    }
 }
 
 impl<'a> Widget for Paragraph<'a> {
@@ -226,49 +302,53 @@ impl<'a> Widget for Paragraph<'a> {
             return;
         }
 
-        let style = self.style;
         let styled = self.text.lines.iter().map(|line| {
-            (
-                line.spans
-                    .iter()
-                    .flat_map(|span| span.styled_graphemes(style)),
-                line.alignment.unwrap_or(self.alignment),
-            )
+            let graphemes = line
+                .spans
+                .iter()
+                .flat_map(|span| span.styled_graphemes(self.style));
+            let alignment = line.alignment.unwrap_or(self.alignment);
+            (graphemes, alignment)
         });
 
-        let mut line_composer: Box<dyn LineComposer> = if let Some(Wrap { trim }) = self.wrap {
-            Box::new(WordWrapper::new(styled, text_area.width, trim))
+        if let Some(Wrap { trim }) = self.wrap {
+            let line_composer = WordWrapper::new(styled, text_area.width, trim);
+            self.render_text(line_composer, text_area, buf);
         } else {
-            let mut line_composer = Box::new(LineTruncator::new(styled, text_area.width));
+            let mut line_composer = LineTruncator::new(styled, text_area.width);
             line_composer.set_horizontal_offset(self.scroll.1);
-            line_composer
-        };
+            self.render_text(line_composer, text_area, buf);
+        }
+    }
+}
+
+impl<'a> Paragraph<'a> {
+    fn render_text<C: LineComposer<'a>>(&self, mut composer: C, area: Rect, buf: &mut Buffer) {
         let mut y = 0;
-        while let Some((current_line, current_line_width, current_line_alignment)) =
-            line_composer.next_line()
+        while let Some(WrappedLine {
+            line: current_line,
+            width: current_line_width,
+            alignment: current_line_alignment,
+        }) = composer.next_line()
         {
             if y >= self.scroll.0 {
-                let mut x =
-                    get_line_offset(current_line_width, text_area.width, current_line_alignment);
+                let mut x = get_line_offset(current_line_width, area.width, current_line_alignment);
                 for StyledGrapheme { symbol, style } in current_line {
                     let width = symbol.width();
                     if width == 0 {
                         continue;
                     }
-                    buf.get_mut(text_area.left() + x, text_area.top() + y - self.scroll.0)
-                        .set_symbol(if symbol.is_empty() {
-                            // If the symbol is empty, the last char which rendered last time will
-                            // leave on the line. It's a quick fix.
-                            " "
-                        } else {
-                            symbol
-                        })
+                    // If the symbol is empty, the last char which rendered last time will
+                    // leave on the line. It's a quick fix.
+                    let symbol = if symbol.is_empty() { " " } else { symbol };
+                    buf.get_mut(area.left() + x, area.top() + y - self.scroll.0)
+                        .set_symbol(symbol)
                         .set_style(*style);
                     x += width as u16;
                 }
             }
             y += 1;
-            if y >= text_area.height + self.scroll.0 {
+            if y >= area.height + self.scroll.0 {
                 break;
             }
         }
@@ -294,7 +374,7 @@ mod test {
         backend::TestBackend,
         style::{Color, Modifier, Stylize},
         text::{Line, Span},
-        widgets::Borders,
+        widgets::{block::Position, Borders},
         Terminal,
     };
 
@@ -477,6 +557,20 @@ mod test {
         );
     }
 
+    #[test]
+    fn test_render_paragraph_with_block_with_bottom_title_and_border() {
+        let block = Block::default()
+            .title("Title")
+            .title_position(Position::Bottom)
+            .borders(Borders::BOTTOM);
+        let paragraph = Paragraph::new("Hello, world!").block(block);
+
+        test_case(
+            &paragraph,
+            Buffer::with_lines(vec!["Hello, world!  ", "Title──────────"]),
+        );
+    }
+
     #[test]
     fn test_render_paragraph_with_word_wrap() {
         let text = "This is a long line of text that should wrap      and contains a superultramegagigalong word.";
@@ -792,4 +886,46 @@ mod test {
                 .remove_modifier(Modifier::DIM)
         )
     }
+
+    #[test]
+    fn widgets_paragraph_count_rendered_lines() {
+        let paragraph = Paragraph::new("Hello World");
+        assert_eq!(paragraph.line_count(20), 1);
+        assert_eq!(paragraph.line_count(10), 1);
+        let paragraph = Paragraph::new("Hello World").wrap(Wrap { trim: false });
+        assert_eq!(paragraph.line_count(20), 1);
+        assert_eq!(paragraph.line_count(10), 2);
+        let paragraph = Paragraph::new("Hello World").wrap(Wrap { trim: true });
+        assert_eq!(paragraph.line_count(20), 1);
+        assert_eq!(paragraph.line_count(10), 2);
+
+        let text = "Hello World ".repeat(100);
+        let paragraph = Paragraph::new(text.trim());
+        assert_eq!(paragraph.line_count(11), 1);
+        assert_eq!(paragraph.line_count(6), 1);
+        let paragraph = paragraph.wrap(Wrap { trim: false });
+        assert_eq!(paragraph.line_count(11), 100);
+        assert_eq!(paragraph.line_count(6), 200);
+        let paragraph = paragraph.wrap(Wrap { trim: true });
+        assert_eq!(paragraph.line_count(11), 100);
+        assert_eq!(paragraph.line_count(6), 200);
+    }
+
+    #[test]
+    fn widgets_paragraph_line_width() {
+        let paragraph = Paragraph::new("Hello World");
+        assert_eq!(paragraph.line_width(), 11);
+        let paragraph = Paragraph::new("Hello World").wrap(Wrap { trim: false });
+        assert_eq!(paragraph.line_width(), 11);
+        let paragraph = Paragraph::new("Hello World").wrap(Wrap { trim: true });
+        assert_eq!(paragraph.line_width(), 11);
+
+        let text = "Hello World ".repeat(100);
+        let paragraph = Paragraph::new(text);
+        assert_eq!(paragraph.line_width(), 1200);
+        let paragraph = paragraph.wrap(Wrap { trim: false });
+        assert_eq!(paragraph.line_width(), 1200);
+        let paragraph = paragraph.wrap(Wrap { trim: true });
+        assert_eq!(paragraph.line_width(), 1200);
+    }
 }

src/widgets/reflow.rs

@@ -11,7 +11,16 @@ const NBSP: &str = "\u{00a0}";
 /// Cannot implement it as Iterator since it yields slices of the internal buffer (need streaming
 /// iterators for that).
 pub trait LineComposer<'a> {
-    fn next_line(&mut self) -> Option<(&[StyledGrapheme<'a>], u16, Alignment)>;
+    fn next_line<'lend>(&'lend mut self) -> Option<WrappedLine<'lend, 'a>>;
+}
+
+pub struct WrappedLine<'lend, 'text> {
+    /// One line reflowed to the correct width
+    pub line: &'lend [StyledGrapheme<'text>],
+    /// The width of the line
+    pub width: u16,
+    /// Whether the line was aligned left or right
+    pub alignment: Alignment,
 }
 
 /// A state machine that wraps lines on word boundaries.
@@ -56,7 +65,7 @@ where
     O: Iterator<Item = (I, Alignment)>,
     I: Iterator<Item = StyledGrapheme<'a>>,
 {
-    fn next_line(&mut self) -> Option<(&[StyledGrapheme<'a>], u16, Alignment)> {
+    fn next_line<'lend>(&'lend mut self) -> Option<WrappedLine<'lend, 'a>> {
         if self.max_line_width == 0 {
             return None;
         }
@@ -200,7 +209,11 @@ where
 
         if let Some(line) = current_line {
             self.current_line = line;
-            Some((&self.current_line[..], line_width, self.current_alignment))
+            Some(WrappedLine {
+                line: &self.current_line[..],
+                width: line_width,
+                alignment: self.current_alignment,
+            })
         } else {
             None
         }
@@ -249,7 +262,7 @@ where
     O: Iterator<Item = (I, Alignment)>,
     I: Iterator<Item = StyledGrapheme<'a>>,
 {
-    fn next_line(&mut self) -> Option<(&[StyledGrapheme<'a>], u16, Alignment)> {
+    fn next_line<'lend>(&'lend mut self) -> Option<WrappedLine<'lend, 'a>> {
         if self.max_line_width == 0 {
             return None;
         }
@@ -296,11 +309,11 @@ where
         if lines_exhausted {
             None
         } else {
-            Some((
-                &self.current_line[..],
-                current_line_width,
-                current_alignment,
-            ))
+            Some(WrappedLine {
+                line: &self.current_line[..],
+                width: current_line_width,
+                alignment: current_alignment,
+            })
         }
     }
 }
@@ -360,7 +373,12 @@ mod test {
         let mut lines = vec![];
         let mut widths = vec![];
         let mut alignments = vec![];
-        while let Some((styled, width, alignment)) = composer.next_line() {
+        while let Some(WrappedLine {
+            line: styled,
+            width,
+            alignment,
+        }) = composer.next_line()
+        {
             let line = styled
                 .iter()
                 .map(|StyledGrapheme { symbol, .. }| *symbol)

src/widgets/scrollbar.rs

@@ -62,18 +62,21 @@ impl ScrollbarState {
         }
     }
     /// Sets the scroll position of the scrollbar and returns the modified ScrollbarState.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn position(mut self, position: usize) -> Self {
         self.position = position;
         self
     }
 
     /// Sets the length of the scrollable content and returns the modified ScrollbarState.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn content_length(mut self, content_length: usize) -> Self {
         self.content_length = content_length;
         self
     }
 
     /// Sets the length of the viewport content and returns the modified ScrollbarState.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn viewport_content_length(mut self, viewport_content_length: usize) -> Self {
         self.viewport_content_length = viewport_content_length;
         self
@@ -204,6 +207,7 @@ impl<'a> Scrollbar<'a> {
 
     /// Sets the orientation of the scrollbar.
     /// Resets the symbols to [`DOUBLE_VERTICAL`] or [`DOUBLE_HORIZONTAL`] based on orientation
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn orientation(mut self, orientation: ScrollbarOrientation) -> Self {
         self.orientation = orientation;
         let set = if self.is_vertical() {
@@ -215,54 +219,63 @@ impl<'a> Scrollbar<'a> {
     }
 
     /// Sets the orientation and symbols for the scrollbar from a [`Set`].
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn orientation_and_symbol(mut self, orientation: ScrollbarOrientation, set: Set) -> Self {
         self.orientation = orientation;
         self.symbols(set)
     }
 
     /// Sets the symbol that represents the thumb of the scrollbar.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn thumb_symbol(mut self, thumb_symbol: &'a str) -> Self {
         self.thumb_symbol = thumb_symbol;
         self
     }
 
     /// Sets the style that represents the thumb of the scrollbar.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn thumb_style(mut self, thumb_style: Style) -> Self {
         self.thumb_style = thumb_style;
         self
     }
 
     /// Sets the symbol that represents the track of the scrollbar.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn track_symbol(mut self, track_symbol: Option<&'a str>) -> Self {
         self.track_symbol = track_symbol;
         self
     }
 
     /// Sets the style that is used for the track of the scrollbar.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn track_style(mut self, track_style: Style) -> Self {
         self.track_style = track_style;
         self
     }
 
     /// Sets the symbol that represents the beginning of the scrollbar.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn begin_symbol(mut self, begin_symbol: Option<&'a str>) -> Self {
         self.begin_symbol = begin_symbol;
         self
     }
 
     /// Sets the style that is used for the beginning of the scrollbar.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn begin_style(mut self, begin_style: Style) -> Self {
         self.begin_style = begin_style;
         self
     }
 
     /// Sets the symbol that represents the end of the scrollbar.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn end_symbol(mut self, end_symbol: Option<&'a str>) -> Self {
         self.end_symbol = end_symbol;
         self
     }
 
     /// Sets the style that is used for the end of the scrollbar.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn end_style(mut self, end_style: Style) -> Self {
         self.end_style = end_style;
         self
@@ -281,6 +294,7 @@ impl<'a> Scrollbar<'a> {
     ///
     /// Only sets begin_symbol, end_symbol and track_symbol if they already contain a value.
     /// If they were set to `None` explicitly, this function will respect that choice.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn symbols(mut self, symbol: Set) -> Self {
         self.thumb_symbol = symbol.thumb;
         if self.track_symbol.is_some() {
@@ -304,6 +318,7 @@ impl<'a> Scrollbar<'a> {
     /// │  └──────── thumb
     /// └─────────── begin
     /// ```
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn style(mut self, style: Style) -> Self {
         self.track_style = style;
         self.thumb_style = style;

src/widgets/sparkline.rs

@@ -1,3 +1,4 @@
+#![warn(missing_docs)]
 use std::cmp::min;
 
 use strum::{Display, EnumString};
@@ -12,6 +13,18 @@ use crate::{
 
 /// Widget to render a sparkline over one or more lines.
 ///
+/// You can create a `Sparkline` using [`Sparkline::default`].
+///
+/// `Sparkline` can be styled either using [`Sparkline::style`] or preferably using the methods
+/// provided by the [`Stylize`](crate::style::Stylize) trait.
+///
+/// # Setter methods
+///
+/// - [`Sparkline::block`] wraps the sparkline in a [`Block`]
+/// - [`Sparkline::data`] defines the dataset, you'll almost always want to use it
+/// - [`Sparkline::max`] sets the maximum value of bars
+/// - [`Sparkline::direction`] sets the render direction
+///
 /// # Examples
 ///
 /// ```
@@ -21,7 +34,8 @@ use crate::{
 ///     .block(Block::default().title("Sparkline").borders(Borders::ALL))
 ///     .data(&[0, 2, 3, 4, 1, 4, 10])
 ///     .max(5)
-///     .style(Style::default().fg(Color::Red).bg(Color::White));
+///     .direction(RenderDirection::RightToLeft)
+///     .style(Style::default().red().on_white());
 /// ```
 #[derive(Debug, Clone, Eq, PartialEq)]
 pub struct Sparkline<'a> {
@@ -40,10 +54,15 @@ pub struct Sparkline<'a> {
     direction: RenderDirection,
 }
 
+/// Defines the direction in which sparkline will be rendered.
+///
+/// See [`Sparkline::direction`].
 #[derive(Debug, Default, Display, EnumString, Clone, Copy, Eq, PartialEq, Hash)]
 pub enum RenderDirection {
+    /// The first value is on the left, going to the right
     #[default]
     LeftToRight,
+    /// The first value is on the right, going to the left
     RightToLeft,
 }
 
@@ -61,31 +80,64 @@ impl<'a> Default for Sparkline<'a> {
 }
 
 impl<'a> Sparkline<'a> {
+    /// Wraps the sparkline with the given `block`.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn block(mut self, block: Block<'a>) -> Sparkline<'a> {
         self.block = Some(block);
         self
     }
 
+    /// Sets the style of the entire widget.
+    ///
+    /// The foreground corresponds to the bars while the background is everything else.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn style(mut self, style: Style) -> Sparkline<'a> {
         self.style = style;
         self
     }
 
+    /// Sets the dataset for the sparkline.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # use ratatui::{prelude::*, widgets::*};
+    /// # fn ui(frame: &mut Frame) {
+    /// # let area = Rect::default();
+    /// let sparkline = Sparkline::default().data(&[1, 2, 3]);
+    /// frame.render_widget(sparkline, area);
+    /// # }
+    /// ```
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn data(mut self, data: &'a [u64]) -> Sparkline<'a> {
         self.data = data;
         self
     }
 
+    /// Sets the maximum value of bars.
+    ///
+    /// Every bar will be scaled accordingly. If no max is given, this will be the max in the
+    /// dataset.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn max(mut self, max: u64) -> Sparkline<'a> {
         self.max = Some(max);
         self
     }
 
+    /// Sets the characters used to display the bars.
+    ///
+    /// Can be [`symbols::bar::THREE_LEVELS`], [`symbols::bar::NINE_LEVELS`] (default) or a custom
+    /// [`Set`](symbols::bar::Set).
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn bar_set(mut self, bar_set: symbols::bar::Set) -> Sparkline<'a> {
         self.bar_set = bar_set;
         self
     }
 
+    /// Sets the direction of the sparkline.
+    ///
+    /// [`RenderDirection::LeftToRight`] by default.
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn direction(mut self, direction: RenderDirection) -> Sparkline<'a> {
         self.direction = direction;
         self

src/widgets/tabs.rs

@@ -2,17 +2,22 @@
 use crate::{
     buffer::Buffer,
     layout::Rect,
-    style::{Style, Styled},
+    style::{Modifier, Style, Styled},
     symbols,
     text::{Line, Span},
     widgets::{Block, Widget},
 };
 
+const DEFAULT_HIGHLIGHT_STYLE: Style = Style::new().add_modifier(Modifier::REVERSED);
+
 /// A widget that displays a horizontal set of Tabs with a single tab selected.
 ///
 /// Each tab title is stored as a [`Line`] which can be individually styled. The selected tab is set
 /// using [`Tabs::select`] and styled using [`Tabs::highlight_style`]. The divider can be customized
-/// with [`Tabs::divider`].
+/// with [`Tabs::divider`]. Padding can be set with [`Tabs::padding`] or [`Tabs::padding_left`] and
+/// [`Tabs::padding_right`].
+///
+/// The divider defaults to |, and padding defaults to a singular space on each side.
 ///
 /// # Example
 ///
@@ -24,7 +29,8 @@ use crate::{
 ///     .style(Style::default().white())
 ///     .highlight_style(Style::default().yellow())
 ///     .select(2)
-///     .divider(symbols::DOT);
+///     .divider(symbols::DOT)
+///     .padding("->", "<-");
 /// ```
 #[derive(Debug, Default, Clone, Eq, PartialEq, Hash)]
 pub struct Tabs<'a> {
@@ -40,6 +46,10 @@ pub struct Tabs<'a> {
     highlight_style: Style,
     /// Tab divider
     divider: Span<'a>,
+    /// Tab Left Padding
+    padding_left: Line<'a>,
+    /// Tab Right Padding
+    padding_right: Line<'a>,
 }
 
 impl<'a> Tabs<'a> {
@@ -48,6 +58,18 @@ impl<'a> Tabs<'a> {
     /// `titles` can be a [`Vec`] of [`&str`], [`String`] or anything that can be converted into
     /// [`Line`]. As such, titles can be styled independently.
     ///
+    /// The selected tab can be set with [`Tabs::select`]. The first tab has index 0 (this is also
+    /// the default index).
+    ///
+    /// The selected tab can have a different style with [`Tabs::highlight_style`]. This defaults to
+    /// a style with the [`Modifier::REVERSED`] modifier added.
+    ///
+    /// The default divider is a pipe (`|`), but it can be customized with [`Tabs::divider`].
+    ///
+    /// The entire widget can be styled with [`Tabs::style`].
+    ///
+    /// The widget can be wrapped in a [`Block`] using [`Tabs::block`].
+    ///
     /// # Examples
     ///
     /// Basic titles.
@@ -70,12 +92,15 @@ impl<'a> Tabs<'a> {
             titles: titles.into_iter().map(Into::into).collect(),
             selected: 0,
             style: Style::default(),
-            highlight_style: Style::default(),
+            highlight_style: DEFAULT_HIGHLIGHT_STYLE,
             divider: Span::raw(symbols::line::VERTICAL),
+            padding_left: Line::from(" "),
+            padding_right: Line::from(" "),
         }
     }
 
     /// Surrounds the `Tabs` with a [`Block`].
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn block(mut self, block: Block<'a>) -> Tabs<'a> {
         self.block = Some(block);
         self
@@ -83,8 +108,9 @@ impl<'a> Tabs<'a> {
 
     /// Sets the selected tab.
     ///
-    /// The first tab has index 0 (this is also the default index).  
+    /// The first tab has index 0 (this is also the default index).
     /// The selected tab can have a different style with [`Tabs::highlight_style`].
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn select(mut self, selected: usize) -> Tabs<'a> {
         self.selected = selected;
         self
@@ -95,6 +121,7 @@ impl<'a> Tabs<'a> {
     /// This will set the given style on the entire render area.
     /// More precise style can be applied to the titles by styling the ones given to [`Tabs::new`].
     /// The selected tab can be styled differently using [`Tabs::highlight_style`].
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn style(mut self, style: Style) -> Tabs<'a> {
         self.style = style;
         self
@@ -103,6 +130,7 @@ impl<'a> Tabs<'a> {
     /// Sets the style for the highlighted tab.
     ///
     /// Highlighted tab can be selected with [`Tabs::select`].
+    #[must_use = "method moves the value of self and returns the modified value"]
     pub fn highlight_style(mut self, style: Style) -> Tabs<'a> {
         self.highlight_style = style;
         self
@@ -121,7 +149,7 @@ impl<'a> Tabs<'a> {
     /// ```
     /// Use dash (`-`) as separator.
     /// ```
-    /// # use ratatui::{prelude::*, widgets::Tabs, symbols};
+    /// # use ratatui::{prelude::*, widgets::Tabs};
     /// let tabs = Tabs::new(vec!["Tab 1", "Tab 2"]).divider("-");
     /// ```
     pub fn divider<T>(mut self, divider: T) -> Tabs<'a>
@@ -131,6 +159,70 @@ impl<'a> Tabs<'a> {
         self.divider = divider.into();
         self
     }
+
+    /// Sets the padding between tabs.
+    ///
+    /// Both default to space.
+    ///
+    /// # Examples
+    ///
+    /// A space on either side of the tabs.
+    /// ```
+    /// # use ratatui::{prelude::*, widgets::Tabs};
+    /// let tabs = Tabs::new(vec!["Tab 1", "Tab 2"]).padding(" ", " ");
+    /// ```
+    /// Nothing on either side of the tabs.
+    /// ```
+    /// # use ratatui::{prelude::*, widgets::Tabs};
+    /// let tabs = Tabs::new(vec!["Tab 1", "Tab 2"]).padding("", "");
+    /// ```
+    pub fn padding<T, U>(mut self, left: T, right: U) -> Tabs<'a>
+    where
+        T: Into<Line<'a>>,
+        U: Into<Line<'a>>,
+    {
+        self.padding_left = left.into();
+        self.padding_right = right.into();
+        self
+    }
+
+    /// Sets the left side padding between tabs.
+    ///
+    /// Defaults to a space.
+    ///
+    /// # Example
+    ///
+    /// An arrow on the left of tabs.
+    /// ```
+    /// # use ratatui::{prelude::*, widgets::Tabs};
+    /// let tabs = Tabs::new(vec!["Tab 1", "Tab 2"]).padding_left("->");
+    /// ```
+    pub fn padding_left<T>(mut self, padding: T) -> Tabs<'a>
+    where
+        T: Into<Line<'a>>,
+    {
+        self.padding_left = padding.into();
+        self
+    }
+
+    /// Sets the right side padding between tabs.
+    ///
+    /// Defaults to a space.
+    ///
+    /// # Example
+    ///
+    /// An arrow on the right of tabs.
+    /// ```
+    /// # use ratatui::{prelude::*, widgets::Tabs};
+    /// let tabs = Tabs::new(vec!["Tab 1", "Tab 2"]).padding_right("<-");
+    /// ```
+    pub fn padding_right<T>(mut self, padding: T) -> Tabs<'a>
+    where
+        T: Into<Line<'a>>,
+    {
+        self.padding_left = padding.into();
+        self
+    }
 }
 
 impl<'a> Styled for Tabs<'a> {
@@ -165,11 +257,21 @@ impl<'a> Widget for Tabs<'a> {
         let titles_length = self.titles.len();
         for (i, title) in self.titles.into_iter().enumerate() {
             let last_title = titles_length - 1 == i;
-            x = x.saturating_add(1);
+            let remaining_width = tabs_area.right().saturating_sub(x);
+
+            if remaining_width == 0 {
+                break;
+            }
+
+            // Left Padding
+            let pos = buf.set_line(x, tabs_area.top(), &self.padding_left, remaining_width);
+            x = pos.0;
             let remaining_width = tabs_area.right().saturating_sub(x);
             if remaining_width == 0 {
                 break;
             }
+
+            // Title
             let pos = buf.set_line(x, tabs_area.top(), &title, remaining_width);
             if i == self.selected {
                 buf.set_style(
@@ -182,11 +284,20 @@ impl<'a> Widget for Tabs<'a> {
                     self.highlight_style,
                 );
             }
-            x = pos.0.saturating_add(1);
+            x = pos.0;
+            let remaining_width = tabs_area.right().saturating_sub(x);
+            if remaining_width == 0 {
+                break;
+            }
+
+            // Right Padding
+            let pos = buf.set_line(x, tabs_area.top(), &self.padding_right, remaining_width);
+            x = pos.0;
             let remaining_width = tabs_area.right().saturating_sub(x);
             if remaining_width == 0 || last_title {
                 break;
             }
+
             let pos = buf.set_span(x, tabs_area.top(), &self.divider, remaining_width);
             x = pos.0;
         }
@@ -214,8 +325,10 @@ mod tests {
                 ],
                 selected: 0,
                 style: Style::default(),
-                highlight_style: Style::default(),
+                highlight_style: DEFAULT_HIGHLIGHT_STYLE,
                 divider: Span::raw(symbols::line::VERTICAL),
+                padding_right: Line::from(" "),
+                padding_left: Line::from(" "),
             }
         );
     }
@@ -229,40 +342,56 @@ mod tests {
     #[test]
     fn render_default() {
         let tabs = Tabs::new(vec!["Tab1", "Tab2", "Tab3", "Tab4"]);
-        assert_buffer_eq!(
-            render(tabs, Rect::new(0, 0, 30, 1)),
-            Buffer::with_lines(vec![" Tab1 │ Tab2 │ Tab3 │ Tab4    "])
-        );
+        let mut expected = Buffer::with_lines(vec![" Tab1 │ Tab2 │ Tab3 │ Tab4    "]);
+        // first tab selected
+        expected.set_style(Rect::new(1, 0, 4, 1), DEFAULT_HIGHLIGHT_STYLE);
+        assert_buffer_eq!(render(tabs, Rect::new(0, 0, 30, 1)), expected);
+    }
+
+    #[test]
+    fn render_no_padding() {
+        let tabs = Tabs::new(vec!["Tab1", "Tab2", "Tab3", "Tab4"]).padding("", "");
+        let mut expected = Buffer::with_lines(vec!["Tab1│Tab2│Tab3│Tab4           "]);
+        // first tab selected
+        expected.set_style(Rect::new(0, 0, 4, 1), DEFAULT_HIGHLIGHT_STYLE);
+        assert_buffer_eq!(render(tabs, Rect::new(0, 0, 30, 1)), expected);
+    }
+
+    #[test]
+    fn render_more_padding() {
+        let tabs = Tabs::new(vec!["Tab1", "Tab2", "Tab3", "Tab4"]).padding("---", "++");
+        let mut expected = Buffer::with_lines(vec!["---Tab1++│---Tab2++│---Tab3++│"]);
+        // first tab selected
+        expected.set_style(Rect::new(3, 0, 4, 1), DEFAULT_HIGHLIGHT_STYLE);
+        assert_buffer_eq!(render(tabs, Rect::new(0, 0, 30, 1)), expected);
     }
 
     #[test]
     fn render_with_block() {
         let tabs = Tabs::new(vec!["Tab1", "Tab2", "Tab3", "Tab4"])
             .block(Block::default().title("Tabs").borders(Borders::ALL));
-        assert_buffer_eq!(
-            render(tabs, Rect::new(0, 0, 30, 3)),
-            Buffer::with_lines(vec![
-                "┌Tabs────────────────────────┐",
-                "│ Tab1 │ Tab2 │ Tab3 │ Tab4  │",
-                "└────────────────────────────┘",
-            ])
-        );
+        let mut expected = Buffer::with_lines(vec![
+            "┌Tabs────────────────────────┐",
+            "│ Tab1 │ Tab2 │ Tab3 │ Tab4  │",
+            "└────────────────────────────┘",
+        ]);
+        // first tab selected
+        expected.set_style(Rect::new(2, 1, 4, 1), DEFAULT_HIGHLIGHT_STYLE);
+        assert_buffer_eq!(render(tabs, Rect::new(0, 0, 30, 3)), expected);
     }
 
     #[test]
     fn render_style() {
         let tabs =
             Tabs::new(vec!["Tab1", "Tab2", "Tab3", "Tab4"]).style(Style::default().fg(Color::Red));
-        assert_buffer_eq!(
-            render(tabs, Rect::new(0, 0, 30, 1)),
-            Buffer::with_lines(vec![" Tab1 │ Tab2 │ Tab3 │ Tab4    ".red()])
-        );
+        let mut expected = Buffer::with_lines(vec![" Tab1 │ Tab2 │ Tab3 │ Tab4    ".red()]);
+        expected.set_style(Rect::new(1, 0, 4, 1), DEFAULT_HIGHLIGHT_STYLE.red());
+        assert_buffer_eq!(render(tabs, Rect::new(0, 0, 30, 1)), expected);
     }
 
     #[test]
     fn render_select() {
-        let tabs = Tabs::new(vec!["Tab1", "Tab2", "Tab3", "Tab4"])
-            .highlight_style(Style::new().reversed());
+        let tabs = Tabs::new(vec!["Tab1", "Tab2", "Tab3", "Tab4"]);
 
         // first tab selected
         assert_buffer_eq!(
@@ -305,13 +434,13 @@ mod tests {
     fn render_style_and_selected() {
         let tabs = Tabs::new(vec!["Tab1", "Tab2", "Tab3", "Tab4"])
             .style(Style::new().red())
-            .highlight_style(Style::new().reversed())
+            .highlight_style(Style::new().underlined())
             .select(0);
         assert_buffer_eq!(
             render(tabs, Rect::new(0, 0, 30, 1)),
             Buffer::with_lines(vec![Line::from(vec![
                 " ".red(),
-                "Tab1".red().reversed(),
+                "Tab1".red().underlined(),
                 " │ Tab2 │ Tab3 │ Tab4    ".red(),
             ])])
         );
@@ -320,10 +449,10 @@ mod tests {
     #[test]
     fn render_divider() {
         let tabs = Tabs::new(vec!["Tab1", "Tab2", "Tab3", "Tab4"]).divider("--");
-        assert_buffer_eq!(
-            render(tabs, Rect::new(0, 0, 30, 1)),
-            Buffer::with_lines(vec![" Tab1 -- Tab2 -- Tab3 -- Tab4 ",])
-        );
+        let mut expected = Buffer::with_lines(vec![" Tab1 -- Tab2 -- Tab3 -- Tab4 "]);
+        // first tab selected
+        expected.set_style(Rect::new(1, 0, 4, 1), DEFAULT_HIGHLIGHT_STYLE);
+        assert_buffer_eq!(render(tabs, Rect::new(0, 0, 30, 1)), expected);
     }
 
     #[test]

tests/terminal.rs

@@ -1,10 +1,12 @@
 use std::error::Error;
 
 use ratatui::{
+    assert_buffer_eq,
     backend::{Backend, TestBackend},
     layout::Rect,
-    widgets::Paragraph,
-    Terminal,
+    prelude::Buffer,
+    widgets::{Paragraph, Widget},
+    Terminal, TerminalOptions, Viewport,
 };
 
 #[test]
@@ -23,9 +25,9 @@ fn swap_buffer_clears_prev_buffer() {
     terminal
         .current_buffer_mut()
         .set_string(0, 0, "Hello", ratatui::style::Style::reset());
-    assert_eq!(terminal.current_buffer_mut().content()[0].symbol, "H");
+    assert_eq!(terminal.current_buffer_mut().content()[0].symbol(), "H");
     terminal.swap_buffers();
-    assert_eq!(terminal.current_buffer_mut().content()[0].symbol, " ");
+    assert_eq!(terminal.current_buffer_mut().content()[0].symbol(), " ");
 }
 
 #[test]
@@ -36,14 +38,158 @@ fn terminal_draw_returns_the_completed_frame() -> Result<(), Box<dyn Error>> {
         let paragraph = Paragraph::new("Test");
         f.render_widget(paragraph, f.size());
     })?;
-    assert_eq!(frame.buffer.get(0, 0).symbol, "T");
+    assert_eq!(frame.buffer.get(0, 0).symbol(), "T");
     assert_eq!(frame.area, Rect::new(0, 0, 10, 10));
     terminal.backend_mut().resize(8, 8);
     let frame = terminal.draw(|f| {
         let paragraph = Paragraph::new("test");
         f.render_widget(paragraph, f.size());
     })?;
-    assert_eq!(frame.buffer.get(0, 0).symbol, "t");
+    assert_eq!(frame.buffer.get(0, 0).symbol(), "t");
     assert_eq!(frame.area, Rect::new(0, 0, 8, 8));
     Ok(())
 }
+
+#[test]
+fn terminal_insert_before_moves_viewport() -> Result<(), Box<dyn Error>> {
+    // When we have a terminal with 5 lines, and a single line viewport, if we insert a
+    // number of lines less than the `terminal height - viewport height` it should move
+    // viewport down to accommodate the new lines.
+
+    let backend = TestBackend::new(20, 5);
+    let mut terminal = Terminal::with_options(
+        backend,
+        TerminalOptions {
+            viewport: Viewport::Inline(1),
+        },
+    )?;
+
+    // insert_before cannot guarantee the contents of the viewport remain unharmed
+    // by potential scrolling as such it is necessary to call draw afterwards to
+    // redraw the contents of the viewport over the newly designated area.
+    terminal.insert_before(2, |buf| {
+        Paragraph::new(vec![
+            "------ Line 1 ------".into(),
+            "------ Line 2 ------".into(),
+        ])
+        .render(buf.area, buf);
+    })?;
+
+    terminal.draw(|f| {
+        let paragraph = Paragraph::new("[---- Viewport ----]");
+        f.render_widget(paragraph, f.size());
+    })?;
+
+    assert_buffer_eq!(
+        terminal.backend().buffer().clone(),
+        Buffer::with_lines(vec![
+            "------ Line 1 ------",
+            "------ Line 2 ------",
+            "[---- Viewport ----]",
+            "                    ",
+            "                    ",
+        ])
+    );
+
+    Ok(())
+}
+
+#[test]
+fn terminal_insert_before_scrolls_on_large_input() -> Result<(), Box<dyn Error>> {
+    // When we have a terminal with 5 lines, and a single line viewport, if we insert many
+    // lines before the viewport (greater than `terminal height - viewport height`) it should
+    // move the viewport down to the bottom of the terminal and scroll all lines above the viewport
+    // until all have been added to the buffer.
+
+    let backend = TestBackend::new(20, 5);
+    let mut terminal = Terminal::with_options(
+        backend,
+        TerminalOptions {
+            viewport: Viewport::Inline(1),
+        },
+    )?;
+
+    terminal.insert_before(5, |buf| {
+        Paragraph::new(vec![
+            "------ Line 1 ------".into(),
+            "------ Line 2 ------".into(),
+            "------ Line 3 ------".into(),
+            "------ Line 4 ------".into(),
+            "------ Line 5 ------".into(),
+        ])
+        .render(buf.area, buf);
+    })?;
+
+    terminal.draw(|f| {
+        let paragraph = Paragraph::new("[---- Viewport ----]");
+        f.render_widget(paragraph, f.size());
+    })?;
+
+    assert_buffer_eq!(
+        terminal.backend().buffer().clone(),
+        Buffer::with_lines(vec![
+            "------ Line 2 ------",
+            "------ Line 3 ------",
+            "------ Line 4 ------",
+            "------ Line 5 ------",
+            "[---- Viewport ----]",
+        ])
+    );
+
+    Ok(())
+}
+
+#[test]
+fn terminal_insert_before_scrolls_on_many_inserts() -> Result<(), Box<dyn Error>> {
+    // This test ensures similar behaviour to `terminal_insert_before_scrolls_on_large_input`
+    // but covers a bug previously present whereby multiple small insertions
+    // (less than `terminal height - viewport height`) would have disparate behaviour to one large
+    // insertion. This was caused by an undocumented cap on the height to be inserted, which has now
+    // been removed.
+
+    let backend = TestBackend::new(20, 5);
+    let mut terminal = Terminal::with_options(
+        backend,
+        TerminalOptions {
+            viewport: Viewport::Inline(1),
+        },
+    )?;
+
+    terminal.insert_before(1, |buf| {
+        Paragraph::new(vec!["------ Line 1 ------".into()]).render(buf.area, buf);
+    })?;
+
+    terminal.insert_before(1, |buf| {
+        Paragraph::new(vec!["------ Line 2 ------".into()]).render(buf.area, buf);
+    })?;
+
+    terminal.insert_before(1, |buf| {
+        Paragraph::new(vec!["------ Line 3 ------".into()]).render(buf.area, buf);
+    })?;
+
+    terminal.insert_before(1, |buf| {
+        Paragraph::new(vec!["------ Line 4 ------".into()]).render(buf.area, buf);
+    })?;
+
+    terminal.insert_before(1, |buf| {
+        Paragraph::new(vec!["------ Line 5 ------".into()]).render(buf.area, buf);
+    })?;
+
+    terminal.draw(|f| {
+        let paragraph = Paragraph::new("[---- Viewport ----]");
+        f.render_widget(paragraph, f.size());
+    })?;
+
+    assert_buffer_eq!(
+        terminal.backend().buffer().clone(),
+        Buffer::with_lines(vec![
+            "------ Line 2 ------",
+            "------ Line 3 ------",
+            "------ Line 4 ------",
+            "------ Line 5 ------",
+            "[---- Viewport ----]",
+        ])
+    );
+
+    Ok(())
+}

tests/widgets_list.rs

@@ -20,7 +20,7 @@ fn list_should_shows_the_length() {
     assert_eq!(list.len(), 3);
     assert!(!list.is_empty());
 
-    let empty_list = List::new(vec![]);
+    let empty_list = List::default();
     assert_eq!(empty_list.len(), 0);
     assert!(empty_list.is_empty());
 }

tests/widgets_table.rs

@@ -19,19 +19,21 @@ fn widgets_table_column_spacing_can_be_changed() {
         terminal
             .draw(|f| {
                 let size = f.size();
-                let table = Table::new(vec![
-                    Row::new(vec!["Row11", "Row12", "Row13"]),
-                    Row::new(vec!["Row21", "Row22", "Row23"]),
-                    Row::new(vec!["Row31", "Row32", "Row33"]),
-                    Row::new(vec!["Row41", "Row42", "Row43"]),
-                ])
+                let table = Table::new(
+                    vec![
+                        Row::new(vec!["Row11", "Row12", "Row13"]),
+                        Row::new(vec!["Row21", "Row22", "Row23"]),
+                        Row::new(vec!["Row31", "Row32", "Row33"]),
+                        Row::new(vec!["Row41", "Row42", "Row43"]),
+                    ],
+                    [
+                        Constraint::Length(5),
+                        Constraint::Length(5),
+                        Constraint::Length(5),
+                    ],
+                )
                 .header(Row::new(vec!["Head1", "Head2", "Head3"]).bottom_margin(1))
                 .block(Block::default().borders(Borders::ALL))
-                .widths(&[
-                    Constraint::Length(5),
-                    Constraint::Length(5),
-                    Constraint::Length(5),
-                ])
                 .column_spacing(column_spacing);
                 f.render_widget(table, size);
             })
@@ -117,15 +119,17 @@ fn widgets_table_columns_widths_can_use_fixed_length_constraints() {
         terminal
             .draw(|f| {
                 let size = f.size();
-                let table = Table::new(vec![
-                    Row::new(vec!["Row11", "Row12", "Row13"]),
-                    Row::new(vec!["Row21", "Row22", "Row23"]),
-                    Row::new(vec!["Row31", "Row32", "Row33"]),
-                    Row::new(vec!["Row41", "Row42", "Row43"]),
-                ])
+                let table = Table::new(
+                    vec![
+                        Row::new(vec!["Row11", "Row12", "Row13"]),
+                        Row::new(vec!["Row21", "Row22", "Row23"]),
+                        Row::new(vec!["Row31", "Row32", "Row33"]),
+                        Row::new(vec!["Row41", "Row42", "Row43"]),
+                    ],
+                    widths,
+                )
                 .header(Row::new(vec!["Head1", "Head2", "Head3"]).bottom_margin(1))
-                .block(Block::default().borders(Borders::ALL))
-                .widths(widths);
+                .block(Block::default().borders(Borders::ALL));
                 f.render_widget(table, size);
             })
             .unwrap();
@@ -198,28 +202,31 @@ fn widgets_table_columns_widths_can_use_fixed_length_constraints() {
 
 #[test]
 fn widgets_table_columns_widths_can_use_percentage_constraints() {
-    let test_case = |widths, expected| {
+    #[track_caller]
+    fn test_case(widths: &[Constraint], expected: Buffer) {
         let backend = TestBackend::new(30, 10);
         let mut terminal = Terminal::new(backend).unwrap();
 
         terminal
             .draw(|f| {
                 let size = f.size();
-                let table = Table::new(vec![
-                    Row::new(vec!["Row11", "Row12", "Row13"]),
-                    Row::new(vec!["Row21", "Row22", "Row23"]),
-                    Row::new(vec!["Row31", "Row32", "Row33"]),
-                    Row::new(vec!["Row41", "Row42", "Row43"]),
-                ])
+                let table = Table::new(
+                    vec![
+                        Row::new(vec!["Row11", "Row12", "Row13"]),
+                        Row::new(vec!["Row21", "Row22", "Row23"]),
+                        Row::new(vec!["Row31", "Row32", "Row33"]),
+                        Row::new(vec!["Row41", "Row42", "Row43"]),
+                    ],
+                    widths,
+                )
                 .header(Row::new(vec!["Head1", "Head2", "Head3"]).bottom_margin(1))
                 .block(Block::default().borders(Borders::ALL))
-                .widths(widths)
                 .column_spacing(0);
                 f.render_widget(table, size);
             })
             .unwrap();
         terminal.backend().assert_buffer(&expected);
-    };
+    }
 
     // columns of zero width show nothing
     test_case(
@@ -312,15 +319,17 @@ fn widgets_table_columns_widths_can_use_mixed_constraints() {
         terminal
             .draw(|f| {
                 let size = f.size();
-                let table = Table::new(vec![
-                    Row::new(vec!["Row11", "Row12", "Row13"]),
-                    Row::new(vec!["Row21", "Row22", "Row23"]),
-                    Row::new(vec!["Row31", "Row32", "Row33"]),
-                    Row::new(vec!["Row41", "Row42", "Row43"]),
-                ])
+                let table = Table::new(
+                    vec![
+                        Row::new(vec!["Row11", "Row12", "Row13"]),
+                        Row::new(vec!["Row21", "Row22", "Row23"]),
+                        Row::new(vec!["Row31", "Row32", "Row33"]),
+                        Row::new(vec!["Row41", "Row42", "Row43"]),
+                    ],
+                    widths,
+                )
                 .header(Row::new(vec!["Head1", "Head2", "Head3"]).bottom_margin(1))
-                .block(Block::default().borders(Borders::ALL))
-                .widths(widths);
+                .block(Block::default().borders(Borders::ALL));
                 f.render_widget(table, size);
             })
             .unwrap();
@@ -422,15 +431,17 @@ fn widgets_table_columns_widths_can_use_ratio_constraints() {
         terminal
             .draw(|f| {
                 let size = f.size();
-                let table = Table::new(vec![
-                    Row::new(vec!["Row11", "Row12", "Row13"]),
-                    Row::new(vec!["Row21", "Row22", "Row23"]),
-                    Row::new(vec!["Row31", "Row32", "Row33"]),
-                    Row::new(vec!["Row41", "Row42", "Row43"]),
-                ])
+                let table = Table::new(
+                    vec![
+                        Row::new(vec!["Row11", "Row12", "Row13"]),
+                        Row::new(vec!["Row21", "Row22", "Row23"]),
+                        Row::new(vec!["Row31", "Row32", "Row33"]),
+                        Row::new(vec!["Row41", "Row42", "Row43"]),
+                    ],
+                    widths,
+                )
                 .header(Row::new(vec!["Head1", "Head2", "Head3"]).bottom_margin(1))
                 .block(Block::default().borders(Borders::ALL))
-                .widths(widths)
                 .column_spacing(0);
                 f.render_widget(table, size);
             })
@@ -527,20 +538,22 @@ fn widgets_table_can_have_rows_with_multi_lines() {
         terminal
             .draw(|f| {
                 let size = f.size();
-                let table = Table::new(vec![
-                    Row::new(vec!["Row11", "Row12", "Row13"]),
-                    Row::new(vec!["Row21", "Row22", "Row23"]).height(2),
-                    Row::new(vec!["Row31", "Row32", "Row33"]),
-                    Row::new(vec!["Row41", "Row42", "Row43"]).height(2),
-                ])
+                let table = Table::new(
+                    vec![
+                        Row::new(vec!["Row11", "Row12", "Row13"]),
+                        Row::new(vec!["Row21", "Row22", "Row23"]).height(2),
+                        Row::new(vec!["Row31", "Row32", "Row33"]),
+                        Row::new(vec!["Row41", "Row42", "Row43"]).height(2),
+                    ],
+                    [
+                        Constraint::Length(5),
+                        Constraint::Length(5),
+                        Constraint::Length(5),
+                    ],
+                )
                 .header(Row::new(vec!["Head1", "Head2", "Head3"]).bottom_margin(1))
                 .block(Block::default().borders(Borders::ALL))
                 .highlight_symbol(">> ")
-                .widths(&[
-                    Constraint::Length(5),
-                    Constraint::Length(5),
-                    Constraint::Length(5),
-                ])
                 .column_spacing(1);
                 f.render_stateful_widget(table, size, state);
             })
@@ -621,21 +634,23 @@ fn widgets_table_enable_always_highlight_spacing() {
         terminal
             .draw(|f| {
                 let size = f.size();
-                let table = Table::new(vec![
-                    Row::new(vec!["Row11", "Row12", "Row13"]),
-                    Row::new(vec!["Row21", "Row22", "Row23"]).height(2),
-                    Row::new(vec!["Row31", "Row32", "Row33"]),
-                    Row::new(vec!["Row41", "Row42", "Row43"]).height(2),
-                ])
+                let table = Table::new(
+                    vec![
+                        Row::new(vec!["Row11", "Row12", "Row13"]),
+                        Row::new(vec!["Row21", "Row22", "Row23"]).height(2),
+                        Row::new(vec!["Row31", "Row32", "Row33"]),
+                        Row::new(vec!["Row41", "Row42", "Row43"]).height(2),
+                    ],
+                    [
+                        Constraint::Length(5),
+                        Constraint::Length(5),
+                        Constraint::Length(5),
+                    ],
+                )
                 .header(Row::new(vec!["Head1", "Head2", "Head3"]).bottom_margin(1))
                 .block(Block::default().borders(Borders::ALL))
                 .highlight_symbol(">> ")
                 .highlight_spacing(space)
-                .widths(&[
-                    Constraint::Length(5),
-                    Constraint::Length(5),
-                    Constraint::Length(5),
-                ])
                 .column_spacing(1);
                 f.render_stateful_widget(table, size, state);
             })
@@ -755,28 +770,31 @@ fn widgets_table_can_have_elements_styled_individually() {
     terminal
         .draw(|f| {
             let size = f.size();
-            let table = Table::new(vec![
-                Row::new(vec!["Row11", "Row12", "Row13"]).style(Style::default().fg(Color::Green)),
-                Row::new(vec![
-                    Cell::from("Row21"),
-                    Cell::from("Row22").style(Style::default().fg(Color::Yellow)),
-                    Cell::from(Line::from(vec![
-                        Span::raw("Row"),
-                        Span::styled("23", Style::default().fg(Color::Blue)),
-                    ]))
-                    .style(Style::default().fg(Color::Red)),
-                ])
-                .style(Style::default().fg(Color::LightGreen)),
-            ])
+            let table = Table::new(
+                vec![
+                    Row::new(vec!["Row11", "Row12", "Row13"])
+                        .style(Style::default().fg(Color::Green)),
+                    Row::new(vec![
+                        Cell::from("Row21"),
+                        Cell::from("Row22").style(Style::default().fg(Color::Yellow)),
+                        Cell::from(Line::from(vec![
+                            Span::raw("Row"),
+                            Span::styled("23", Style::default().fg(Color::Blue)),
+                        ]))
+                        .style(Style::default().fg(Color::Red)),
+                    ])
+                    .style(Style::default().fg(Color::LightGreen)),
+                ],
+                [
+                    Constraint::Length(6),
+                    Constraint::Length(6),
+                    Constraint::Length(6),
+                ],
+            )
             .header(Row::new(vec!["Head1", "Head2", "Head3"]).bottom_margin(1))
             .block(Block::default().borders(Borders::LEFT | Borders::RIGHT))
             .highlight_symbol(">> ")
             .highlight_style(Style::default().add_modifier(Modifier::BOLD))
-            .widths(&[
-                Constraint::Length(6),
-                Constraint::Length(6),
-                Constraint::Length(6),
-            ])
             .column_spacing(1);
             f.render_stateful_widget(table, size, &mut state);
         })
@@ -830,15 +848,17 @@ fn widgets_table_should_render_even_if_empty() {
     terminal
         .draw(|f| {
             let size = f.size();
-            let table = Table::new(vec![])
-                .header(Row::new(vec!["Head1", "Head2", "Head3"]))
-                .block(Block::default().borders(Borders::LEFT | Borders::RIGHT))
-                .widths(&[
+            let table = Table::new(
+                vec![],
+                [
                     Constraint::Length(6),
                     Constraint::Length(6),
                     Constraint::Length(6),
-                ])
-                .column_spacing(1);
+                ],
+            )
+            .header(Row::new(vec!["Head1", "Head2", "Head3"]))
+            .block(Block::default().borders(Borders::LEFT | Borders::RIGHT))
+            .column_spacing(1);
             f.render_widget(table, size);
         })
         .unwrap();
@@ -868,17 +888,19 @@ fn widgets_table_columns_dont_panic() {
 
     // based on https://github.com/fdehau/tui-rs/issues/470#issuecomment-852562848
     let table1_width = 98;
-    let table1 = Table::new(vec![Row::new(vec!["r1", "r2", "r3", "r4"])])
-        .header(Row::new(vec!["h1", "h2", "h3", "h4"]))
-        .block(Block::default().borders(Borders::ALL))
-        .highlight_symbol(">> ")
-        .column_spacing(1)
-        .widths(&[
+    let table1 = Table::new(
+        vec![Row::new(vec!["r1", "r2", "r3", "r4"])],
+        [
             Constraint::Percentage(15),
             Constraint::Percentage(15),
             Constraint::Percentage(25),
             Constraint::Percentage(45),
-        ]);
+        ],
+    )
+    .header(Row::new(vec!["h1", "h2", "h3", "h4"]))
+    .block(Block::default().borders(Borders::ALL))
+    .highlight_symbol(">> ")
+    .column_spacing(1);
 
     let mut state = TableState::default();
 
@@ -898,21 +920,23 @@ fn widgets_table_should_clamp_offset_if_rows_are_removed() {
     terminal
         .draw(|f| {
             let size = f.size();
-            let table = Table::new(vec![
-                Row::new(vec!["Row01", "Row02", "Row03"]),
-                Row::new(vec!["Row11", "Row12", "Row13"]),
-                Row::new(vec!["Row21", "Row22", "Row23"]),
-                Row::new(vec!["Row31", "Row32", "Row33"]),
-                Row::new(vec!["Row41", "Row42", "Row43"]),
-                Row::new(vec!["Row51", "Row52", "Row53"]),
-            ])
+            let table = Table::new(
+                vec![
+                    Row::new(vec!["Row01", "Row02", "Row03"]),
+                    Row::new(vec!["Row11", "Row12", "Row13"]),
+                    Row::new(vec!["Row21", "Row22", "Row23"]),
+                    Row::new(vec!["Row31", "Row32", "Row33"]),
+                    Row::new(vec!["Row41", "Row42", "Row43"]),
+                    Row::new(vec!["Row51", "Row52", "Row53"]),
+                ],
+                [
+                    Constraint::Length(5),
+                    Constraint::Length(5),
+                    Constraint::Length(5),
+                ],
+            )
             .header(Row::new(vec!["Head1", "Head2", "Head3"]).bottom_margin(1))
             .block(Block::default().borders(Borders::ALL))
-            .widths(&[
-                Constraint::Length(5),
-                Constraint::Length(5),
-                Constraint::Length(5),
-            ])
             .column_spacing(1);
             f.render_stateful_widget(table, size, &mut state);
         })
@@ -934,15 +958,17 @@ fn widgets_table_should_clamp_offset_if_rows_are_removed() {
     terminal
         .draw(|f| {
             let size = f.size();
-            let table = Table::new(vec![Row::new(vec!["Row31", "Row32", "Row33"])])
-                .header(Row::new(vec!["Head1", "Head2", "Head3"]).bottom_margin(1))
-                .block(Block::default().borders(Borders::ALL))
-                .widths(&[
+            let table = Table::new(
+                vec![Row::new(vec!["Row31", "Row32", "Row33"])],
+                [
                     Constraint::Length(5),
                     Constraint::Length(5),
                     Constraint::Length(5),
-                ])
-                .column_spacing(1);
+                ],
+            )
+            .header(Row::new(vec!["Head1", "Head2", "Head3"]).bottom_margin(1))
+            .block(Block::default().borders(Borders::ALL))
+            .column_spacing(1);
             f.render_stateful_widget(table, size, &mut state);
         })
         .unwrap();

tests/widgets_tabs.rs

@@ -1,5 +1,11 @@
 use ratatui::{
-    backend::TestBackend, buffer::Buffer, layout::Rect, symbols, text::Line, widgets::Tabs,
+    backend::TestBackend,
+    buffer::Buffer,
+    layout::Rect,
+    style::{Style, Stylize},
+    symbols,
+    text::Line,
+    widgets::Tabs,
     Terminal,
 };
 
@@ -43,6 +49,7 @@ fn widgets_tabs_should_truncate_the_last_item() {
             );
         })
         .unwrap();
-    let expected = Buffer::with_lines(vec![format!(" Tab1 {} T ", symbols::line::VERTICAL)]);
+    let mut expected = Buffer::with_lines(vec![format!(" Tab1 {} T ", symbols::line::VERTICAL)]);
+    expected.set_style(Rect::new(1, 0, 4, 1), Style::new().reversed());
     terminal.backend().assert_buffer(&expected);
 }

typos.toml

@@ -2,3 +2,8 @@
 
 [default.extend-words]
 ratatui = "ratatui"
+
+[type.md]
+extend-ignore-re = [
+  "\\[[[:xdigit:]]{7}\\]\\(https://github.com/ratatui-org/ratatui/commit/[[:xdigit:]]{40}\\)",
+]