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/ISSUE_TEMPLATE/config.yml

@@ -1 +1,8 @@
 blank_issues_enabled: false
+contact_links:
+  - name: Discord Chat
+    url: https://discord.gg/pMCEU9hNEj
+    about: Ask questions about ratatui on Discord
+  - name: Matrix Chat
+    url: https://matrix.to/#/#ratatui:matrix.org
+    about: Ask questions about ratatui on Matrix

.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

@@ -0,0 +1,337 @@
+# Breaking Changes
+
+This document contains a list of breaking changes in each version and some notes to help migrate
+between versions. It is compile manually from the commit history and changelog. We also tag PRs on
+github with a [breaking change] label.
+
+[breaking change]: (https://github.com/ratatui-org/ratatui/issues?q=label%3A%22breaking+change%22)
+
+## Summary
+
+This is a quick summary of the sections below:
+
+- 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>`
+  - `Stylize` shorthands for `String` now consume the value and return `Span<'static>`
+  - `Spans` is removed
+- [v0.23.0](#v0230)
+  - `Scrollbar`: `track_symbol` now takes `Option<&str>`
+  - `Scrollbar`: symbols moved to `symbols` module
+  - MSRV is now 1.67.0
+- [v0.22.0](#v0220)
+  - serde representation of `Borders` and `Modifiers` has changed
+- [v0.21.0](#v0210)
+  - MSRV is now 1.65.0
+  - `terminal::ViewPort` is now an enum
+  - `"".as_ref()` must be annotated to implement `Into<Text<'a>>`
+  - `Marker::Block` renders as a block char instead of a bar char
+- [v0.20.0](#v0200)
+  - MSRV is now 1.63.0
+  - `List` no longer ignores empty strings
+
+## 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])
+
+[#456]: https://github.com/ratatui-org/ratatui/pull/456
+
+In order to support larger content lengths, the `position`, `content_length` and
+`viewport_content_length` methods on `ScrollbarState` now take `usize` instead of `u16`
+
+### `BorderType::line_symbols` renamed to `border_symbols` ([#529])
+
+[#529]: https://github.com/ratatui-org/ratatui/issues/529
+
+Applications can now set custom borders on a `Block` by calling `border_set()`. The
+`BorderType::line_symbols()` is renamed to `border_symbols()` and now returns a new struct
+`symbols::border::Set`. E.g.:
+
+```diff
+- let line_set: symbols::line::Set = BorderType::line_symbols(BorderType::Plain);
+// becomes
++ let border_set: symbols::border::Set = BorderType::border_symbols(BorderType::Plain);
+```
+
+### Generic `Backend` parameter removed from `Frame` ([#530])
+
+[#530]: https://github.com/ratatui-org/ratatui/issues/530
+
+`Frame` is no longer generic over Backend. Code that accepted `Frame<Backend>` will now need to
+accept `Frame`. To migrate existing code, remove any generic parameters from code that uses an
+instance of a Frame. E.g.:
+
+```diff
+- fn ui<B: Backend>(frame: &mut Frame<B>) { ... }
+// becomes
++ fn ui(frame: Frame) { ... }
+```
+
+### `Stylize` shorthands now consume rather than borrow `String` ([#466])
+
+[#466]: https://github.com/ratatui-org/ratatui/issues/466
+
+In order to support using `Stylize` shorthands (e.g. `"foo".red()`) on temporary `String` values, a
+new implementation of `Stylize` was added that returns a `Span<'static>`. This causes the value to
+be consumed rather than borrowed. Existing code that expects to use the string after a call will no
+longer compile. E.g.
+
+```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();
+```
+
+### Deprecated `Spans` type removed (replaced with `Line`) ([#426])
+
+[#426]: https://github.com/ratatui-org/ratatui/issues/426
+
+`Spans` was replaced with `Line` in 0.21.0. `Buffer::set_spans` was replaced with
+`Buffer::set_line`.
+
+```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);
+```
+
+## [v0.23.0](https://github.com/ratatui-org/ratatui/releases/tag/v0.23.0)
+
+### `Scrollbar::track_symbol()` now takes an `Option<&str>` instead of `&str` ([#360])
+
+[#360]: https://github.com/ratatui-org/ratatui/issues/360
+
+The track symbol of `Scrollbar` is now optional, this method now takes an optional value.
+
+```diff
+- let scrollbar = Scrollbar::default().track_symbol("|");
+// becomes
++ let scrollbar = Scrollbar::default().track_symbol(Some("|"));
+```
+
+### `Scrollbar` symbols moved to `symbols::scrollbar` and `widgets::scrollbar` module is private ([#330])
+
+[#330]: https://github.com/ratatui-org/ratatui/issues/330
+
+The symbols for defining scrollbars have been moved to the `symbols` module from the
+`widgets::scrollbar` module which is no longer public. To update your code update any imports to the
+new module locations. E.g.:
+
+```diff
+- use ratatui::{widgets::scrollbar::{Scrollbar, Set}};
+// becomes
++ use ratatui::{widgets::Scrollbar, symbols::scrollbar::Set} 
+```
+
+### MSRV updated to 1.67 ([#361])
+
+[#361]: https://github.com/ratatui-org/ratatui/issues/361
+
+The MSRV of ratatui is now 1.67 due to an MSRV update in a dependency (`time`).
+
+## [v0.22.0](https://github.com/ratatui-org/ratatui/releases/tag/v0.22.0)
+
+### bitflags updated to 2.3 ([#205])
+
+[#205]: https://github.com/ratatui-org/ratatui/issues/205
+
+The serde representation of bitflags has changed. Any existing serialized types that have Borders or
+Modifiers will need to be re-serialized. This is documented in the [bitflags
+changelog](https://github.com/bitflags/bitflags/blob/main/CHANGELOG.md#200-rc2)..
+
+## [v0.21.0](https://github.com/ratatui-org/ratatui/releases/tag/v0.21.0)
+
+### MSRV is 1.65.0  ([#171])
+
+[#171]: https://github.com/ratatui-org/ratatui/issues/171
+
+The minimum supported rust version is now 1.65.0.
+
+### `Terminal::with_options()` stabilized to allow configuring the viewport ([#114])
+
+[#114]: https://github.com/ratatui-org/ratatui/issues/114
+
+In order to support inline viewports, the unstable method `Terminal::with_options()` was stabilized
+and  `ViewPort` was changed from a struct to an enum.
+
+```diff
+let terminal = Terminal::with_options(backend, TerminalOptions {
+-    viewport: Viewport::fixed(area),
+});
+// becomes
+let terminal = Terminal::with_options(backend, TerminalOptions {
++    viewport: Viewport::Fixed(area),
+});
+```
+
+### Code that binds `Into<Text<'a>>` now requires type annotations ([#168])
+
+[#168]: https://github.com/ratatui-org/ratatui/issues/168
+
+A new type `Masked` was introduced that implements `From<Text<'a>>`. This causes any code that did
+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.:
+
+```diff
+- let paragraph = Paragraph::new("".as_ref());
+// becomes
++ let paragraph = Paragraph::new("".as_str());
+```
+
+### `Marker::Block` now renders as a block rather than a bar character ([#133])
+
+[#133]: https://github.com/ratatui-org/ratatui/issues/133
+
+Code using the `Block` marker that previously rendered using a half block character (`'▀'``) now
+renders using the full block character (`'█'`). A new marker variant`Bar` is introduced to replace
+the existing code.
+
+```diff
+- let canvas = Canvas::default().marker(Marker::Block);
+// becomes
++ let canvas = Canvas::default().marker(Marker::Bar);
+```
+
+## [v0.20.0](https://github.com/ratatui-org/ratatui/releases/tag/v0.20.0)
+
+v0.20.0 was the first release of Ratatui - versions prior to this were release as tui-rs. See the
+[Changelog](./CHANGELOG.md) for more details.
+
+### MSRV is update to 1.63.0 ([#80])
+
+[#80]: https://github.com/ratatui-org/ratatui/issues/80
+
+The minimum supported rust version is 1.63.0
+
+### List no longer ignores empty string in items ([#42])
+
+[#42]: https://github.com/ratatui-org/ratatui/issues/42
+
+The following code now renders 3 items instead of 2. Code which relies on the previous behavior will
+need to manually filter empty items prior to display.
+
+```rust
+let items = vec![
+    ListItem::new("line one"),
+    ListItem::new(""),
+    ListItem::new("line four"),
+];
+```

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,33 +18,28 @@ exclude = [
 ]
 autoexamples = true
 edition = "2021"
-rust-version = "1.67.0"
+rust-version = "1.70.0"
 
 [badges]
 
 [dependencies]
-#! The crate provides a set of optional features that can be enabled in your `cargo.toml` file.
-#!
-#! Generally an application will only use one backend, so you should only enable one of the following features:
-## enables the [`CrosstermBackend`] backend and adds a dependency on the [Crossterm crate].
 crossterm = { version = "0.27", optional = true }
-## enables the [`TermionBackend`] backend and adds a dependency on the [Termion crate].
 termion = { version = "2.0", optional = true }
-## enables the [`TermwizBackend`] backend and adds a dependency on the [Termwiz crate].
 termwiz = { version = "0.20.0", optional = true }
 
 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"
@@ -60,7 +55,20 @@ palette = "0.7.3"
 pretty_assertions = "1.4.0"
 
 [features]
-default = ["crossterm"]
+#! The crate provides a set of optional features that can be enabled in your `cargo.toml` file.
+#!
+## By default, we enable the crossterm backend as this is a reasonable choice for most applications
+## as it is supported on Linux/Mac/Windows systems. We also enable the `underline-color` feature
+## which allows you to set the underline color of text.
+default = ["crossterm", "underline-color"]
+#! Generally an application will only use one backend, so you should only enable one of the following features:
+## enables the [`CrosstermBackend`] backend and adds a dependency on the [Crossterm crate].
+crossterm = ["dep:crossterm"]
+## enables the [`TermionBackend`] backend and adds a dependency on the [Termion crate].
+termion = ["dep:termion"]
+## enables the [`TermwizBackend`] backend and adds a dependency on the [Termwiz crate].
+termwiz = ["dep:termwiz"]
+
 #! The following optional features are available for all backends:
 ## enables serialization and deserialization of style and color types using the [Serde crate].
 ## This is useful if you want to save themes to a file.
@@ -77,6 +85,26 @@ all-widgets = ["widget-calendar"]
 ## enables the [`calendar`] widget module and adds a dependency on the [Time crate].
 widget-calendar = ["dep:time"]
 
+#! Underline color is only supported by the [`CrosstermBackend`] backend, and is not supported
+#! on Windows 7.
+## 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
@@ -95,6 +123,9 @@ harness = false
 name = "list"
 harness = false
 
+[lib]
+bench = false
+
 [[bench]]
 name = "paragraph"
 harness = false
@@ -155,6 +186,11 @@ name = "demo2"
 required-features = ["crossterm", "widget-calendar"]
 doc-scrape-examples = true
 
+[[example]]
+name = "docsrs"
+required-features = ["crossterm"]
+doc-scrape-examples = false
+
 [[example]]
 name = "gauge"
 required-features = ["crossterm"]
@@ -196,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

@@ -9,9 +9,9 @@ ALL_FEATURES = "all-widgets,macros,serde"
 
 # Windows does not support building termion, so this avoids the build failure by providing two
 # sets of flags, one for Windows and one for other platforms.
-# Windows: --features=all-widgets,macros,serde,crossterm,termwiz
-# Other: --all-features
-ALL_FEATURES_FLAG = { source = "${CARGO_MAKE_RUST_TARGET_OS}", default_value = "--all-features", mapping = { "windows" = "--features=all-widgets,macros,serde,crossterm,termwiz" } }
+# 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,unstable", mapping = { "windows" = "--features=all-widgets,macros,serde,crossterm,termwiz,unstable" } }
 
 [tasks.default]
 alias = "ci"

README.md

@@ -1,22 +1,41 @@
-![Demo of
-Ratatui](https://raw.githubusercontent.com/ratatui-org/ratatui/aa09e59dc0058347f68d7c1e0c91f863c6f2b8c9/examples/demo2.gif)
-<!--
-Permalink to https://github.com/ratatui-org/ratatui/blob/images/examples/demo2.gif
-See RELEASE.md for instructions on creating the demo gif
---->
+<details>
+<summary>Table of Contents</summary>
+
+- [Ratatui](#ratatui)
+  - [Installation](#installation)
+  - [Introduction](#introduction)
+  - [Other Documentation](#other-documentation)
+  - [Quickstart](#quickstart)
+  - [Status of this fork](#status-of-this-fork)
+  - [Rust version requirements](#rust-version-requirements)
+  - [Widgets](#widgets)
+    - [Built in](#built-in)
+    - [Third\-party libraries, bootstrapping templates and
+      widgets](#third-party-libraries-bootstrapping-templates-and-widgets)
+  - [Apps](#apps)
+  - [Alternatives](#alternatives)
+  - [Acknowledgments](#acknowledgments)
+  - [License](#license)
+
+</details>
+
+<!-- cargo-rdme start -->
+
+![Demo](https://raw.githubusercontent.com/ratatui-org/ratatui/b33c878808c4c40591d7a2d9f9d94d6fee95a96f/examples/demo2.gif)
 
 <div align="center">
 
-[![Crates.io](https://img.shields.io/crates/v/ratatui?logo=rust&style=flat-square)](https://crates.io/crates/ratatui)
-[![License](https://img.shields.io/crates/l/ratatui?style=flat-square)](./LICENSE) [![GitHub CI
-Status](https://img.shields.io/github/actions/workflow/status/ratatui-org/ratatui/ci.yml?style=flat-square&logo=github)](https://github.com/ratatui-org/ratatui/actions?query=workflow%3ACI+)
-[![Docs.rs](https://img.shields.io/docsrs/ratatui?logo=rust&style=flat-square)](https://docs.rs/crate/ratatui/)<br>
-[![Dependency
-Status](https://deps.rs/repo/github/ratatui-org/ratatui/status.svg?style=flat-square)](https://deps.rs/repo/github/ratatui-org/ratatui)
-[![Codecov](https://img.shields.io/codecov/c/github/ratatui-org/ratatui?logo=codecov&style=flat-square&token=BAQ8SOKEST)](https://app.codecov.io/gh/ratatui-org/ratatui)
-[![Discord](https://img.shields.io/discord/1070692720437383208?label=discord&logo=discord&style=flat-square)](https://discord.gg/pMCEU9hNEj)
-[![Matrix](https://img.shields.io/matrix/ratatui-general%3Amatrix.org?style=flat-square&logo=matrix&label=Matrix)](https://matrix.to/#/#ratatui:matrix.org)<br>
+[![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)
@@ -24,119 +43,308 @@ Status](https://deps.rs/repo/github/ratatui-org/ratatui/status.svg?style=flat-sq
 
 </div>
 
-<img align="left" src="https://avatars.githubusercontent.com/u/125200832?s=128&v=4">
-
 # Ratatui
 
-`ratatui` is a [Rust](https://www.rust-lang.org) library that is all about cooking up terminal user
-interfaces. It is a community fork of the original [tui-rs](https://github.com/fdehau/tui-rs)
-project.
-
-<details>
-<summary>Table of Contents</summary>
-
-* [Ratatui](#ratatui)
-  * [Installation](#installation)
-  * [Introduction](#introduction)
-  * [Quickstart](#quickstart)
-  * [Status of this fork](#status-of-this-fork)
-  * [Rust version requirements](#rust-version-requirements)
-  * [Documentation](#documentation)
-  * [Examples](#examples)
-  * [Widgets](#widgets)
-    * [Built in](#built-in)
-    * [Third\-party libraries, bootstrapping templates and
-      widgets](#third-party-libraries-bootstrapping-templates-and-widgets)
-  * [Apps](#apps)
-  * [Alternatives](#alternatives)
-  * [Contributors](#contributors)
-  * [Acknowledgments](#acknowledgments)
-  * [License](#license)
-
-</details>
+[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
 
+Add `ratatui` and `crossterm` as dependencies to your cargo.toml:
+
 ```shell
-cargo add ratatui --features all-widgets
+cargo add ratatui crossterm
 ```
 
-Or modify your `Cargo.toml`
-
-```toml
-[dependencies]
-ratatui = { version = "0.23.0", features = ["all-widgets"]}
-```
+Ratatui uses [Crossterm] by default as it works on most platforms. See the [Installation]
+section of the [Ratatui Website] for more details on how to use other backends ([Termion] /
+[Termwiz]).
 
 ## Introduction
 
-`ratatui` is a terminal UI library that supports multiple backends:
+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 Website] for
+more info.
 
-* [crossterm](https://github.com/crossterm-rs/crossterm) [default]
-* [termion](https://github.com/ticki/termion)
-* [termwiz](https://github.com/wez/wezterm/tree/master/termwiz)
+## Other documentation
 
-The library is based on the principle of immediate rendering with intermediate buffers. This means
-that at each new frame you should build all widgets that are supposed to be part of the UI. While
-providing a great flexibility for rich and interactive UI, this may introduce overhead for highly
-dynamic content. So, the implementation try to minimize the number of ansi escapes sequences
-generated to draw the updated UI. In practice, given the speed of `Rust` the overhead rather comes
-from the terminal emulator than the library itself.
-
-Moreover, the library does not provide any input handling nor any event system and you may rely on
-the previously cited libraries to achieve such features.
-
-We keep a [CHANGELOG](./CHANGELOG.md) generated by [git-cliff](https://github.com/orhun/git-cliff)
-utilizing [Conventional Commits](https://www.conventionalcommits.org/).
+- [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].
+- [Contributing] - Please read this if you are interested in contributing to the project.
+- [Breaking Changes] - a list of breaking changes in the library.
 
 ## Quickstart
 
 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](./examples/hello_world.rs). For more guidance on how to create Ratatui apps, see
-the [Docs](https://docs.rs/ratatui) and [Examples](#examples). There is also a starter template
-available at [rust-tui-template](https://github.com/ratatui-org/rust-tui-template).
+[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 Website] and the various
+[Examples]. There are also several starter templates available:
+
+- [template]
+- [async-template] (book and template)
+
+Every application built with `ratatui` needs to implement the following steps:
+
+- Initialize the terminal
+- A main loop to:
+  - Handle input events
+  - Draw the UI
+- Restore the terminal state
+
+The library contains a [`prelude`] module that re-exports the most commonly used traits and
+types for convenience. Most examples in the documentation will use this instead of showing the
+full path of each type.
+
+### Initialize and restore the terminal
+
+The [`Terminal`] type is the main entry point for any Ratatui application. It is a light
+abstraction over a choice of [`Backend`] implementations that provides functionality to draw
+each frame, clear the screen, hide the cursor, etc. It is parametrized over any type that
+implements the [`Backend`] trait which has implementations for [Crossterm], [Termion] and
+[Termwiz].
+
+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 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 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
+Website] for more info. For example, if you are using [Crossterm], you can use the
+[`crossterm::event`] module to handle events.
+
+### Example
 
 ```rust
-fn main() -> Result<(), Box<dyn Error>> {
-    let mut terminal = setup_terminal()?;
-    run(&mut terminal)?;
-    restore_terminal(&mut terminal)?;
+use std::io::{self, stdout};
+use crossterm::{
+    event::{self, Event, KeyCode},
+    ExecutableCommand,
+    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen}
+};
+use ratatui::{prelude::*, widgets::*};
+
+fn main() -> io::Result<()> {
+    enable_raw_mode()?;
+    stdout().execute(EnterAlternateScreen)?;
+    let mut terminal = Terminal::new(CrosstermBackend::new(stdout()))?;
+
+    let mut should_quit = false;
+    while !should_quit {
+        terminal.draw(ui)?;
+        should_quit = handle_events()?;
+    }
+
+    disable_raw_mode()?;
+    stdout().execute(LeaveAlternateScreen)?;
     Ok(())
 }
 
-fn setup_terminal() -> Result<Terminal<CrosstermBackend<Stdout>>, Box<dyn Error>> {
-    let mut stdout = io::stdout();
-    enable_raw_mode()?;
-    execute!(stdout, EnterAlternateScreen)?;
-    Ok(Terminal::new(CrosstermBackend::new(stdout))?)
-}
-
-fn restore_terminal(
-    terminal: &mut Terminal<CrosstermBackend<Stdout>>,
-) -> Result<(), Box<dyn Error>> {
-    disable_raw_mode()?;
-    execute!(terminal.backend_mut(), LeaveAlternateScreen,)?;
-    Ok(terminal.show_cursor()?)
-}
-
-fn run(terminal: &mut Terminal<CrosstermBackend<Stdout>>) -> Result<(), Box<dyn Error>> {
-    Ok(loop {
-        terminal.draw(|frame| {
-            let greeting = Paragraph::new("Hello World!");
-            frame.render_widget(greeting, frame.size());
-        })?;
-        if event::poll(Duration::from_millis(250))? {
-            if let Event::Key(key) = event::read()? {
-                if KeyCode::Char('q') == key.code {
-                    break;
-                }
+fn handle_events() -> io::Result<bool> {
+    if event::poll(std::time::Duration::from_millis(50))? {
+        if let Event::Key(key) = event::read()? {
+            if key.kind == event::KeyEventKind::Press && key.code == KeyCode::Char('q') {
+                return Ok(true);
             }
-        }
-    })
+       }
+    }
+    Ok(false)
+}
+
+fn ui(frame: &mut Frame) {
+    frame.render_widget(
+        Paragraph::new("Hello World!")
+            .block(Block::default().title("Greeting").borders(Borders::ALL)),
+        frame.size(),
+    );
 }
 ```
 
+Running this example produces the following output:
+
+![docsrs-hello]
+
+## Layout
+
+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 Website] for more info.
+
+```rust
+use ratatui::{prelude::*, widgets::*};
+
+fn ui(frame: &mut Frame) {
+    let main_layout = Layout::new(
+        Direction::Vertical,
+        [
+            Constraint::Length(1),
+            Constraint::Min(0),
+            Constraint::Length(1),
+        ]
+    )
+    .split(frame.size());
+    frame.render_widget(
+        Block::new().borders(Borders::TOP).title("Title Bar"),
+        main_layout[0],
+    );
+    frame.render_widget(
+        Block::new().borders(Borders::TOP).title("Status Bar"),
+        main_layout[2],
+    );
+
+    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],
+    );
+    frame.render_widget(
+        Block::default().borders(Borders::ALL).title("Right"),
+        inner_layout[1],
+    );
+}
+```
+
+Running this example produces the following output:
+
+![docsrs-layout]
+
+## Text and styling
+
+The [`Text`], [`Line`] and [`Span`] types are the building blocks of the library and are used in
+many places. [`Text`] is a list of [`Line`]s and a [`Line`] is a list of [`Span`]s. A [`Span`]
+is a string with a specific style.
+
+The [`style` module] provides types that represent the various styling options. The most
+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 Website] for more info.
+
+```rust
+use ratatui::{prelude::*, widgets::*};
+
+fn ui(frame: &mut Frame) {
+    let areas = Layout::new(
+        Direction::Vertical,
+        [
+            Constraint::Length(1),
+            Constraint::Length(1),
+            Constraint::Length(1),
+            Constraint::Length(1),
+            Constraint::Min(0),
+        ]
+    )
+    .split(frame.size());
+
+    let span1 = Span::raw("Hello ");
+    let span2 = Span::styled(
+        "World",
+        Style::new()
+            .fg(Color::Green)
+            .bg(Color::White)
+            .add_modifier(Modifier::BOLD),
+    );
+    let span3 = "!".red().on_light_yellow().italic();
+
+    let line = Line::from(vec![span1, span2, span3]);
+    let text: Text = Text::from(vec![line]);
+
+    frame.render_widget(Paragraph::new(text), areas[0]);
+    // or using the short-hand syntax and implicit conversions
+    frame.render_widget(
+        Paragraph::new("Hello World!".red().on_white().bold()),
+        areas[1],
+    );
+
+    // to style the whole widget instead of just the text
+    frame.render_widget(
+        Paragraph::new("Hello World!").style(Style::new().red().on_white()),
+        areas[2],
+    );
+    // or using the short-hand syntax
+    frame.render_widget(Paragraph::new("Hello World!").blue().on_yellow(), areas[3]);
+}
+```
+
+Running this example produces the following output:
+
+![docsrs-styling]
+
+[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://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
+[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
+[`Frame`]: terminal::Frame
+[`render_widget`]: terminal::Frame::render_widget
+[`Widget`]: widgets::Widget
+[`Layout`]: layout::Layout
+[`Text`]: text::Text
+[`Line`]: text::Line
+[`Span`]: text::Span
+[`Style`]: style::Style
+[`style` module]: style
+[`Stylize`]: style::Stylize
+[`Backend`]: backend::Backend
+[`backend` module]: backend
+[`crossterm::event`]: https://docs.rs/crossterm/latest/crossterm/event/index.html
+[Ratatui]: https://ratatui.rs
+[Crossterm]: https://crates.io/crates/crossterm
+[Termion]: https://crates.io/crates/termion
+[Termwiz]: https://crates.io/crates/termwiz
+[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]:
+    https://img.shields.io/github/actions/workflow/status/ratatui-org/ratatui/ci.yml?style=flat-square&logo=github
+[Codecov Badge]:
+    https://img.shields.io/codecov/c/github/ratatui-org/ratatui?logo=codecov&style=flat-square&token=BAQ8SOKEST
+[Dependencies Badge]: https://deps.rs/repo/github/ratatui-org/ratatui/status.svg?style=flat-square
+[Discord Badge]:
+    https://img.shields.io/discord/1070692720437383208?label=discord&logo=discord&style=flat-square
+[Docs Badge]: https://img.shields.io/docsrs/ratatui?logo=rust&style=flat-square
+[License Badge]: https://img.shields.io/crates/l/ratatui?style=flat-square
+[Matrix Badge]:
+    https://img.shields.io/matrix/ratatui-general%3Amatrix.org?style=flat-square&logo=matrix&label=Matrix
+
+<!-- cargo-rdme end -->
+
 ## Status of this fork
 
 In response to the original maintainer [**Florian Dehau**](https://github.com/fdehau)'s issue
@@ -159,35 +367,6 @@ you are interested in working on a PR or issue opened in the previous repository
 
 Since version 0.23.0, The Minimum Supported Rust Version (MSRV) of `ratatui` is 1.67.0.
 
-## Documentation
-
-The documentation can be found on [docs.rs.](https://docs.rs/ratatui)
-
-## Examples
-
-The demo shown in the gif above is available on all available backends.
-
-```shell
-# crossterm
-cargo run --example demo
-# termion
-cargo run --example demo --no-default-features --features=termion
-# termwiz
-cargo run --example demo --no-default-features --features=termwiz
-```
-
-The UI code for this is in [examples/demo/ui.rs](./examples/demo/ui.rs) while the application state
-is in [examples/demo/app.rs](./examples/demo/app.rs).
-
-If the user interface contains glyphs that are not displayed correctly by your terminal, you may
-want to run the demo without those symbols:
-
-```shell
-cargo run --example demo --release -- --tick-rate 200 --enhanced-graphics false
-```
-
-More examples are available in the [examples](./examples/) folder.
-
 ## Widgets
 
 ### Built in
@@ -195,21 +374,21 @@ More examples are available in the [examples](./examples/) folder.
 The library comes with the following
 [widgets](https://docs.rs/ratatui/latest/ratatui/widgets/index.html):
 
-* [BarChart](https://docs.rs/ratatui/latest/ratatui/widgets/struct.BarChart.html)
-* [Block](https://docs.rs/ratatui/latest/ratatui/widgets/block/struct.Block.html)
-* [Calendar](https://docs.rs/ratatui/latest/ratatui/widgets/calendar/index.html)
-* [Canvas](https://docs.rs/ratatui/latest/ratatui/widgets/canvas/struct.Canvas.html) which allows
+- [BarChart](https://docs.rs/ratatui/latest/ratatui/widgets/struct.BarChart.html)
+- [Block](https://docs.rs/ratatui/latest/ratatui/widgets/block/struct.Block.html)
+- [Calendar](https://docs.rs/ratatui/latest/ratatui/widgets/calendar/index.html)
+- [Canvas](https://docs.rs/ratatui/latest/ratatui/widgets/canvas/struct.Canvas.html) which allows
   rendering [points, lines, shapes and a world
   map](https://docs.rs/ratatui/latest/ratatui/widgets/canvas/index.html)
-* [Chart](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Chart.html)
-* [Clear](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Clear.html)
-* [Gauge](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Gauge.html)
-* [List](https://docs.rs/ratatui/latest/ratatui/widgets/struct.List.html)
-* [Paragraph](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Paragraph.html)
-* [Scrollbar](https://docs.rs/ratatui/latest/ratatui/widgets/scrollbar/struct.Scrollbar.html)
-* [Sparkline](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Sparkline.html)
-* [Table](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Table.html)
-* [Tabs](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Tabs.html)
+- [Chart](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Chart.html)
+- [Clear](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Clear.html)
+- [Gauge](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Gauge.html)
+- [List](https://docs.rs/ratatui/latest/ratatui/widgets/struct.List.html)
+- [Paragraph](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Paragraph.html)
+- [Scrollbar](https://docs.rs/ratatui/latest/ratatui/widgets/scrollbar/struct.Scrollbar.html)
+- [Sparkline](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Sparkline.html)
+- [Table](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Table.html)
+- [Tabs](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Tabs.html)
 
 Each widget has an associated example which can be found in the [examples](./examples/) folder. Run
 each examples with cargo (e.g. to run the gauge example `cargo run --example gauge`), and quit by
@@ -220,48 +399,42 @@ be installed with `cargo install cargo-make`).
 
 ### Third-party libraries, bootstrapping templates and widgets
 
-* [ansi-to-tui](https://github.com/uttarayan21/ansi-to-tui) — Convert ansi colored text to
+- [ansi-to-tui](https://github.com/uttarayan21/ansi-to-tui) — Convert ansi colored text to
   `ratatui::text::Text`
-* [color-to-tui](https://github.com/uttarayan21/color-to-tui) — Parse hex colors to
+- [color-to-tui](https://github.com/uttarayan21/color-to-tui) — Parse hex colors to
   `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
+- [rust-tui-template](https://github.com/ratatui-org/rust-tui-template) — A template for
+  bootstrapping a Rust TUI application with Tui-rs & crossterm
+- [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
-* [tui-log](https://github.com/kegesch/tui-log-rs) — Example of how to use logging with Tui-rs
-* [tui-logger](https://github.com/gin66/tui-logger) — Logger and Widget for Tui-rs
-* [tui-realm](https://github.com/veeso/tui-realm) — Tui-rs framework to build stateful applications
+- [tui-clap](https://github.com/kegesch/tui-clap-rs) — Use clap-rs together with Tui-rs
+- [tui-log](https://github.com/kegesch/tui-log-rs) — Example of how to use logging with Tui-rs
+- [tui-logger](https://github.com/gin66/tui-logger) — Logger and Widget for Tui-rs
+- [tui-realm](https://github.com/veeso/tui-realm) — Tui-rs framework to build stateful applications
   with a React/Elm inspired approach
-* [tui-realm-treeview](https://github.com/veeso/tui-realm-treeview) — Treeview component for
+- [tui-realm-treeview](https://github.com/veeso/tui-realm-treeview) — Treeview component for
   Tui-realm
-* [tui-rs-tree-widgets](https://github.com/EdJoPaTo/tui-rs-tree-widget): Widget for tree data
+- [tui-rs-tree-widgets](https://github.com/EdJoPaTo/tui-rs-tree-widget) — Widget for tree data
   structures.
-* [tui-windows](https://github.com/markatk/tui-windows-rs) — Tui-rs abstraction to handle multiple
+- [tui-windows](https://github.com/markatk/tui-windows-rs) — Tui-rs abstraction to handle multiple
   windows and their rendering
-* [tui-textarea](https://github.com/rhysd/tui-textarea): Simple yet powerful multi-line text editor
+- [tui-textarea](https://github.com/rhysd/tui-textarea) — Simple yet powerful multi-line text editor
   widget supporting several key shortcuts, undo/redo, text search, etc.
-* [tui-input](https://github.com/sayanarijit/tui-input): TUI input library supporting multiple
+- [tui-input](https://github.com/sayanarijit/tui-input) — TUI input library supporting multiple
   backends and tui-rs.
-* [tui-term](https://github.com/a-kenji/tui-term): A pseudoterminal widget library
+- [tui-term](https://github.com/a-kenji/tui-term) — A pseudoterminal widget library
   that enables the rendering of terminal applications as ratatui widgets.
 
 ## 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
 
 You might want to checkout [Cursive](https://github.com/gyscos/Cursive) for an alternative solution
 to build text user interfaces in Rust.
 
-## Contributors
-
-[![GitHub
-Contributors](https://contrib.rocks/image?repo=ratatui-org/ratatui)](https://github.com/ratatui-org/ratatui/graphs/contributors)
-
 ## Acknowledgments
 
 Special thanks to [**Pavel Fomchenkov**](https://github.com/nawok) for his work in designing **an

RELEASE.md

@@ -17,11 +17,28 @@ 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)
 1. Commit and push the changes.
 1. Create a new tag: `git tag -a v[X.Y.Z]`
 1. Push the tag: `git push --tags`
 1. Wait for [Continuous Deployment](https://github.com/ratatui-org/ratatui/actions) workflow to
    finish.
+
+## Alpha Releases
+
+Alpha releases are automatically released every Saturday via [cd.yml](./.github/workflows/cd.yml)
+and can be manually be created when necessary by triggering the [Continuous
+Deployment](https://github.com/ratatui-org/ratatui/actions/workflows/cd.yml) workflow.
+
+We automatically release an alpha release with a patch level bump + alpha.num weekly (and when we
+need to manually). E.g. the last release was 0.22.0, and the most recent alpha release is
+0.22.1-alpha.1.
+
+These releases will have whatever happened to be in main at the time of release, so they're useful
+for apps that need to get releases from crates.io, but may contain more bugs and be generally less
+tested than normal releases.
+
+See [#147](https://github.com/ratatui-org/ratatui/issues/147) and
+[#359](https://github.com/ratatui-org/ratatui/pull/359) for more info on the alpha release process.

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

@@ -1,10 +1,18 @@
 # Examples
 
-These gifs were created using [Charm VHS](https://github.com/charmbracelet/vhs).
+These gifs were created using [VHS](https://github.com/charmbracelet/vhs). Each example has a
+corresponding `.tape` file that holds instructions for how to generate the images. Note that the
+images themselves are stored in a separate git branch to avoid bloating the main repository.
 
-VHS has a problem rendering some background color transitions, which shows up in several examples
-below. See <https://github.com/charmbracelet/vhs/issues/344> for more info. These problems don't
-occur in a terminal.
+## Demo2
+
+This is the demo example from the main README and crate page. Source: [demo2](./demo2/).
+
+```shell
+cargo run --example=demo2 --features="crossterm widget-calendar"
+```
+
+![Demo2][demo2.gif]
 
 ## Demo
 
@@ -58,7 +66,7 @@ Demonstrates the [`Calendar`](https://docs.rs/ratatui/latest/ratatui/widgets/cal
 widget. Source: [calendar.rs](./calendar.rs).
 
 ```shell
-cargo run --example=calendar --features=crossterm widget-calendar
+cargo run --example=calendar --features="crossterm widget-calendar"
 ```
 
 ![Calendar][calendar.gif]
@@ -102,19 +110,20 @@ cargo run --example=colors --features=crossterm
 
 Demonstrates the available RGB
 [`Color`](https://docs.rs/ratatui/latest/ratatui/style/enum.Color.html) options. These can be used
-in any style field. Source: [colors_rgb.rs](./colors_rgb.rs).
+in any style field. Source: [colors_rgb.rs](./colors_rgb.rs). Uses a half block technique to render
+two square-ish pixels in the space of a single rectangular terminal cell.
 
 ```shell
 cargo run --example=colors_rgb --features=crossterm
 ```
 
-![Colors RGB][colors_rgb.gif]
+![Colors RGB][colors_rgb.png]
 
 ## Custom Widget
 
 Demonstrates how to implement the
-[`Widget`](https://docs.rs/ratatui/latest/ratatui/widgets/trait.Widget.html) trait. Source:
-[custom_widget.rs](./custom_widget.rs).
+[`Widget`](https://docs.rs/ratatui/latest/ratatui/widgets/trait.Widget.html) trait. Also shows mouse
+interaction. Source: [custom_widget.rs](./custom_widget.rs).
 
 ```shell
 cargo run --example=custom_widget --features=crossterm
@@ -127,10 +136,6 @@ cargo run --example=custom_widget --features=crossterm
 Demonstrates the [`Gauge`](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Gauge.html) widget.
 Source: [gauge.rs](./gauge.rs).
 
-> [!NOTE] The backgrounds render poorly when we generate this example using VHS. This problem
-> doesn't generally happen during normal rendering in a terminal. See
-> [vhs#344](https://github.com/charmbracelet/vhs/issues/344) for more details.
-
 ```shell
 cargo run --example=gauge --features=crossterm
 ```
@@ -139,7 +144,7 @@ cargo run --example=gauge --features=crossterm
 
 ## Inline
 
-Demonstrates the
+Demonstrates how to use the
 [`Inline`](https://docs.rs/ratatui/latest/ratatui/terminal/enum.Viewport.html#variant.Inline)
 Viewport mode for ratatui apps. Source: [inline.rs](./inline.rs).
 
@@ -216,12 +221,20 @@ Demonstrates how to render a widget over the top of previously rendered widgets
 cargo run --example=popup --features=crossterm
 ```
 
-> [!NOTE] The background renders poorly after the popup when we generate this example using VHS.
-> This problem doesn't generally happen during normal rendering in a terminal. See
-> [vhs#344](https://github.com/charmbracelet/vhs/issues/344) for more details.
-
 ![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)
@@ -238,10 +251,6 @@ cargo run --example=scrollbar --features=crossterm
 Demonstrates the [`Sparkline`](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Sparkline.html)
 widget. Source: [sparkline.rs](./sparkline.rs).
 
-> [!NOTE] The background renders poorly in the second sparkline when we generate this example using
-> VHS. This problem doesn't generally happen during normal rendering in a terminal. See
-> [vhs#344](https://github.com/charmbracelet/vhs/issues/344) for more details.
-
 ```shell
 cargo run --example=sparkline --features=crossterm
 ```
@@ -292,15 +301,17 @@ To update these examples in bulk:
 examples/generate.bash
 ```
 -->
+
 [barchart.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/barchart.gif?raw=true
 [block.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/block.gif?raw=true
 [calendar.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/calendar.gif?raw=true
 [canvas.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/canvas.gif?raw=true
 [chart.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/chart.gif?raw=true
 [colors.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/colors.gif?raw=true
-[colors_rgb.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/colors_rgb.gif?raw=true
+[colors_rgb.png]: https://github.com/ratatui-org/ratatui/blob/images/examples/colors_rgb.png?raw=true
 [custom_widget.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/custom_widget.gif?raw=true
 [demo.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/demo.gif?raw=true
+[demo2.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/demo2.gif?raw=true
 [gauge.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/gauge.gif?raw=true
 [hello_world.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/hello_world.gif?raw=true
 [inline.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/inline.gif?raw=true
@@ -310,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/barchart.rs

@@ -119,9 +119,7 @@ fn run_app<B: Backend>(
     loop {
         terminal.draw(|f| ui(f, &app))?;
 
-        let timeout = tick_rate
-            .checked_sub(last_tick.elapsed())
-            .unwrap_or_else(|| Duration::from_secs(0));
+        let timeout = tick_rate.saturating_sub(last_tick.elapsed());
         if crossterm::event::poll(timeout)? {
             if let Event::Key(key) = event::read()? {
                 if let KeyCode::Char('q') = key.code {
@@ -136,10 +134,10 @@ fn run_app<B: Backend>(
     }
 }
 
-fn ui<B: Backend>(f: &mut Frame<B>, app: &App) {
+fn ui(f: &mut Frame, app: &App) {
     let chunks = Layout::default()
         .direction(Direction::Vertical)
-        .constraints([Constraint::Ratio(1, 3), Constraint::Ratio(2, 3)].as_ref())
+        .constraints([Constraint::Ratio(1, 3), Constraint::Ratio(2, 3)])
         .split(f.size());
 
     let barchart = BarChart::default()
@@ -152,7 +150,7 @@ fn ui<B: Backend>(f: &mut Frame<B>, app: &App) {
 
     let chunks = Layout::default()
         .direction(Direction::Horizontal)
-        .constraints([Constraint::Percentage(50), Constraint::Percentage(50)].as_ref())
+        .constraints([Constraint::Percentage(50), Constraint::Percentage(50)])
         .split(chunks[1]);
 
     draw_bar_with_group_labels(f, app, chunks[0]);
@@ -198,10 +196,7 @@ fn create_groups<'a>(app: &'a App, combine_values_and_labels: bool) -> Vec<BarGr
         .collect()
 }
 
-fn draw_bar_with_group_labels<B>(f: &mut Frame<B>, app: &App, area: Rect)
-where
-    B: Backend,
-{
+fn draw_bar_with_group_labels(f: &mut Frame, app: &App, area: Rect) {
     let groups = create_groups(app, false);
 
     let mut barchart = BarChart::default()
@@ -228,10 +223,7 @@ where
     }
 }
 
-fn draw_horizontal_bars<B>(f: &mut Frame<B>, app: &App, area: Rect)
-where
-    B: Backend,
-{
+fn draw_horizontal_bars(f: &mut Frame, app: &App, area: Rect) {
     let groups = create_groups(app, true);
 
     let mut barchart = BarChart::default()
@@ -260,10 +252,7 @@ where
     }
 }
 
-fn draw_legend<B>(f: &mut Frame<B>, area: Rect)
-where
-    B: Backend,
-{
+fn draw_legend(f: &mut Frame, area: Rect) {
     let text = vec![
         Line::from(Span::styled(
             TOTAL_REVENUE,

examples/barchart.tape

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

examples/block.rs

@@ -21,7 +21,6 @@ use ratatui::{
 
 // These type aliases are used to make the code more readable by reducing repetition of the generic
 // types. They are not necessary for the functionality of the code.
-type Frame<'a> = ratatui::Frame<'a, CrosstermBackend<Stdout>>;
 type Terminal = ratatui::Terminal<CrosstermBackend<Stdout>>;
 type Result<T> = std::result::Result<T, Box<dyn Error>>;
 
@@ -106,18 +105,18 @@ fn ui(frame: &mut Frame) {
 fn calculate_layout(area: Rect) -> (Rect, Vec<Vec<Rect>>) {
     let layout = Layout::default()
         .direction(Direction::Vertical)
-        .constraints(vec![Constraint::Length(1), Constraint::Min(0)])
+        .constraints([Constraint::Length(1), Constraint::Min(0)])
         .split(area);
     let title_area = layout[0];
     let main_areas = Layout::default()
         .direction(Direction::Vertical)
-        .constraints(vec![Constraint::Max(4); 9])
+        .constraints([Constraint::Max(4); 9])
         .split(layout[1])
         .iter()
         .map(|&area| {
             Layout::default()
                 .direction(Direction::Horizontal)
-                .constraints(vec![Constraint::Percentage(50), Constraint::Percentage(50)])
+                .constraints([Constraint::Percentage(50), Constraint::Percentage(50)])
                 .split(area)
                 .to_vec()
         })

examples/block.tape

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

examples/calendar.rs

@@ -16,7 +16,7 @@ fn main() -> Result<(), Box<dyn Error>> {
     let mut terminal = Terminal::new(backend)?;
 
     loop {
-        let _ = terminal.draw(|f| draw(f));
+        let _ = terminal.draw(draw);
 
         if let Event::Key(key) = event::read()? {
             #[allow(clippy::single_match)]
@@ -35,7 +35,7 @@ fn main() -> Result<(), Box<dyn Error>> {
     Ok(())
 }
 
-fn draw<B: Backend>(f: &mut Frame<B>) {
+fn draw(f: &mut Frame) {
     let app_area = f.size();
 
     let calarea = Rect {
@@ -69,14 +69,11 @@ fn split_rows(area: &Rect) -> Rc<[Rect]> {
     let list_layout = Layout::default()
         .direction(Direction::Vertical)
         .margin(0)
-        .constraints(
-            [
-                Constraint::Percentage(33),
-                Constraint::Percentage(33),
-                Constraint::Percentage(33),
-            ]
-            .as_ref(),
-        );
+        .constraints([
+            Constraint::Percentage(33),
+            Constraint::Percentage(33),
+            Constraint::Percentage(33),
+        ]);
 
     list_layout.split(*area)
 }
@@ -85,15 +82,12 @@ fn split_cols(area: &Rect) -> Rc<[Rect]> {
     let list_layout = Layout::default()
         .direction(Direction::Horizontal)
         .margin(0)
-        .constraints(
-            [
-                Constraint::Percentage(25),
-                Constraint::Percentage(25),
-                Constraint::Percentage(25),
-                Constraint::Percentage(25),
-            ]
-            .as_ref(),
-        );
+        .constraints([
+            Constraint::Percentage(25),
+            Constraint::Percentage(25),
+            Constraint::Percentage(25),
+            Constraint::Percentage(25),
+        ]);
 
     list_layout.split(*area)
 }

examples/calendar.tape

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

examples/canvas.rs

@@ -1,28 +1,29 @@
 use std::{
-    error::Error,
-    io,
+    io::{self, stdout, Stdout},
     time::{Duration, Instant},
 };
 
 use crossterm::{
-    event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode},
-    execute,
+    event::{self, Event, KeyCode},
     terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+    ExecutableCommand,
 };
 use ratatui::{
     prelude::*,
     widgets::{canvas::*, *},
 };
 
+fn main() -> io::Result<()> {
+    App::run()
+}
+
 struct App {
     x: f64,
     y: f64,
-    ball: Rectangle,
+    ball: Circle,
     playground: Rect,
     vx: f64,
     vy: f64,
-    dir_x: bool,
-    dir_y: bool,
     tick_count: u64,
     marker: Marker,
 }
@@ -32,155 +33,166 @@ impl App {
         App {
             x: 0.0,
             y: 0.0,
-            ball: Rectangle {
-                x: 10.0,
-                y: 30.0,
-                width: 10.0,
-                height: 10.0,
+            ball: Circle {
+                x: 20.0,
+                y: 40.0,
+                radius: 10.0,
                 color: Color::Yellow,
             },
-            playground: Rect::new(10, 10, 100, 100),
+            playground: Rect::new(10, 10, 200, 100),
             vx: 1.0,
             vy: 1.0,
-            dir_x: true,
-            dir_y: true,
             tick_count: 0,
             marker: Marker::Dot,
         }
     }
 
-    fn on_tick(&mut self) {
-        self.tick_count += 1;
-        // only change marker every 4 ticks (1s) to avoid stroboscopic effect
-        if (self.tick_count % 4) == 0 {
-            self.marker = match self.marker {
-                Marker::Dot => Marker::Block,
-                Marker::Block => Marker::Bar,
-                Marker::Bar => Marker::Braille,
-                Marker::Braille => Marker::Dot,
-            };
-        }
-        if self.ball.x < self.playground.left() as f64
-            || self.ball.x + self.ball.width > self.playground.right() as f64
-        {
-            self.dir_x = !self.dir_x;
-        }
-        if self.ball.y < self.playground.top() as f64
-            || self.ball.y + self.ball.height > self.playground.bottom() as f64
-        {
-            self.dir_y = !self.dir_y;
-        }
-
-        if self.dir_x {
-            self.ball.x += self.vx;
-        } else {
-            self.ball.x -= self.vx;
-        }
-
-        if self.dir_y {
-            self.ball.y += self.vy;
-        } else {
-            self.ball.y -= self.vy
-        }
-    }
-}
-
-fn main() -> Result<(), Box<dyn Error>> {
-    // setup terminal
-    enable_raw_mode()?;
-    let mut stdout = io::stdout();
-    execute!(stdout, EnterAlternateScreen, EnableMouseCapture)?;
-    let backend = CrosstermBackend::new(stdout);
-    let mut terminal = Terminal::new(backend)?;
-
-    // create app and run it
-    let tick_rate = Duration::from_millis(250);
-    let app = App::new();
-    let res = run_app(&mut terminal, app, tick_rate);
-
-    // restore terminal
-    disable_raw_mode()?;
-    execute!(
-        terminal.backend_mut(),
-        LeaveAlternateScreen,
-        DisableMouseCapture
-    )?;
-    terminal.show_cursor()?;
-
-    if let Err(err) = res {
-        println!("{err:?}");
-    }
-
-    Ok(())
-}
-
-fn run_app<B: Backend>(
-    terminal: &mut Terminal<B>,
-    mut app: App,
-    tick_rate: Duration,
-) -> io::Result<()> {
-    let mut last_tick = Instant::now();
-    loop {
-        terminal.draw(|f| ui(f, &app))?;
-
-        let timeout = tick_rate
-            .checked_sub(last_tick.elapsed())
-            .unwrap_or_else(|| Duration::from_secs(0));
-        if event::poll(timeout)? {
-            if let Event::Key(key) = event::read()? {
-                match key.code {
-                    KeyCode::Char('q') => {
-                        return Ok(());
+    pub fn run() -> io::Result<()> {
+        let mut terminal = init_terminal()?;
+        let mut app = App::new();
+        let mut last_tick = Instant::now();
+        let tick_rate = Duration::from_millis(16);
+        loop {
+            let _ = terminal.draw(|frame| app.ui(frame));
+            let timeout = tick_rate.saturating_sub(last_tick.elapsed());
+            if event::poll(timeout)? {
+                if let Event::Key(key) = event::read()? {
+                    match key.code {
+                        KeyCode::Char('q') => break,
+                        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,
+                        _ => {}
                     }
-                    KeyCode::Down => {
-                        app.y += 1.0;
-                    }
-                    KeyCode::Up => {
-                        app.y -= 1.0;
-                    }
-                    KeyCode::Right => {
-                        app.x += 1.0;
-                    }
-                    KeyCode::Left => {
-                        app.x -= 1.0;
-                    }
-                    _ => {}
                 }
             }
+
+            if last_tick.elapsed() >= tick_rate {
+                app.on_tick();
+                last_tick = Instant::now();
+            }
+        }
+        restore_terminal()
+    }
+
+    fn on_tick(&mut self) {
+        self.tick_count += 1;
+        // only change marker every 180 ticks (3s) to avoid stroboscopic effect
+        if (self.tick_count % 180) == 0 {
+            self.marker = match self.marker {
+                Marker::Dot => Marker::Braille,
+                Marker::Braille => Marker::Block,
+                Marker::Block => Marker::HalfBlock,
+                Marker::HalfBlock => Marker::Bar,
+                Marker::Bar => Marker::Dot,
+            };
+        }
+        // bounce the ball by flipping the velocity vector
+        let ball = &self.ball;
+        let playground = self.playground;
+        if ball.x - ball.radius < playground.left() as f64
+            || ball.x + ball.radius > playground.right() as f64
+        {
+            self.vx = -self.vx;
+        }
+        if ball.y - ball.radius < playground.top() as f64
+            || ball.y + ball.radius > playground.bottom() as f64
+        {
+            self.vy = -self.vy;
         }
 
-        if last_tick.elapsed() >= tick_rate {
-            app.on_tick();
-            last_tick = Instant::now();
-        }
+        self.ball.x += self.vx;
+        self.ball.y += self.vy;
+    }
+
+    fn ui(&self, frame: &mut Frame) {
+        let main_layout = Layout::default()
+            .direction(Direction::Horizontal)
+            .constraints([Constraint::Percentage(50), Constraint::Percentage(50)])
+            .split(frame.size());
+
+        let right_layout = Layout::default()
+            .direction(Direction::Vertical)
+            .constraints([Constraint::Percentage(50), Constraint::Percentage(50)])
+            .split(main_layout[1]);
+
+        frame.render_widget(self.map_canvas(), main_layout[0]);
+        frame.render_widget(self.pong_canvas(), right_layout[0]);
+        frame.render_widget(self.boxes_canvas(right_layout[1]), right_layout[1]);
+    }
+
+    fn map_canvas(&self) -> impl Widget + '_ {
+        Canvas::default()
+            .block(Block::default().borders(Borders::ALL).title("World"))
+            .marker(self.marker)
+            .paint(|ctx| {
+                ctx.draw(&Map {
+                    color: Color::Green,
+                    resolution: MapResolution::High,
+                });
+                ctx.print(self.x, -self.y, "You are here".yellow());
+            })
+            .x_bounds([-180.0, 180.0])
+            .y_bounds([-90.0, 90.0])
+    }
+
+    fn pong_canvas(&self) -> impl Widget + '_ {
+        Canvas::default()
+            .block(Block::default().borders(Borders::ALL).title("Pong"))
+            .marker(self.marker)
+            .paint(|ctx| {
+                ctx.draw(&self.ball);
+            })
+            .x_bounds([10.0, 210.0])
+            .y_bounds([10.0, 110.0])
+    }
+
+    fn boxes_canvas(&self, area: Rect) -> impl Widget {
+        let (left, right, bottom, top) =
+            (0.0, area.width as f64, 0.0, area.height as f64 * 2.0 - 4.0);
+        Canvas::default()
+            .block(Block::default().borders(Borders::ALL).title("Rects"))
+            .marker(self.marker)
+            .x_bounds([left, right])
+            .y_bounds([bottom, top])
+            .paint(|ctx| {
+                for i in 0..=11 {
+                    ctx.draw(&Rectangle {
+                        x: (i * i + 3 * i) as f64 / 2.0 + 2.0,
+                        y: 2.0,
+                        width: i as f64,
+                        height: i as f64,
+                        color: Color::Red,
+                    });
+                    ctx.draw(&Rectangle {
+                        x: (i * i + 3 * i) as f64 / 2.0 + 2.0,
+                        y: 21.0,
+                        width: i as f64,
+                        height: i as f64,
+                        color: Color::Blue,
+                    });
+                }
+                for i in 0..100 {
+                    if i % 10 != 0 {
+                        ctx.print(i as f64 + 1.0, 0.0, format!("{i}", i = i % 10));
+                    }
+                    if i % 2 == 0 && i % 10 != 0 {
+                        ctx.print(0.0, i as f64, format!("{i}", i = i % 10));
+                    }
+                }
+            })
     }
 }
 
-fn ui<B: Backend>(f: &mut Frame<B>, app: &App) {
-    let chunks = Layout::default()
-        .direction(Direction::Horizontal)
-        .constraints([Constraint::Percentage(50), Constraint::Percentage(50)].as_ref())
-        .split(f.size());
-    let canvas = Canvas::default()
-        .block(Block::default().borders(Borders::ALL).title("World"))
-        .marker(app.marker)
-        .paint(|ctx| {
-            ctx.draw(&Map {
-                color: Color::White,
-                resolution: MapResolution::High,
-            });
-            ctx.print(app.x, -app.y, "You are here".yellow());
-        })
-        .x_bounds([-180.0, 180.0])
-        .y_bounds([-90.0, 90.0]);
-    f.render_widget(canvas, chunks[0]);
-    let canvas = Canvas::default()
-        .block(Block::default().borders(Borders::ALL).title("Pong"))
-        .marker(app.marker)
-        .paint(|ctx| {
-            ctx.draw(&app.ball);
-        })
-        .x_bounds([10.0, 110.0])
-        .y_bounds([10.0, 110.0]);
-    f.render_widget(canvas, chunks[1]);
+fn init_terminal() -> io::Result<Terminal<CrosstermBackend<Stdout>>> {
+    enable_raw_mode()?;
+    stdout().execute(EnterAlternateScreen)?;
+    Terminal::new(CrosstermBackend::new(stdout()))
+}
+
+fn restore_terminal() -> io::Result<()> {
+    disable_raw_mode()?;
+    stdout().execute(LeaveAlternateScreen)?;
+    Ok(())
 }

examples/canvas.tape

@@ -1,12 +1,13 @@
 # This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
 # To run this script, install vhs and run `vhs ./examples/canvas.tape`
 Output "target/canvas.gif"
-Set Theme "OceanicMaterial"
+Set Theme "Aardvark Blue"
+Set FontSize 12
 Set Width 1200
 Set Height 800
 Hide
 Type "cargo run --example=canvas --features=crossterm"
 Enter
-Sleep 1s
+Sleep 2s
 Show
-Sleep 5s
+Sleep 30s

examples/chart.rs

@@ -125,9 +125,7 @@ fn run_app<B: Backend>(
     loop {
         terminal.draw(|f| ui(f, &app))?;
 
-        let timeout = tick_rate
-            .checked_sub(last_tick.elapsed())
-            .unwrap_or_else(|| Duration::from_secs(0));
+        let timeout = tick_rate.saturating_sub(last_tick.elapsed());
         if crossterm::event::poll(timeout)? {
             if let Event::Key(key) = event::read()? {
                 if let KeyCode::Char('q') = key.code {
@@ -142,18 +140,15 @@ fn run_app<B: Backend>(
     }
 }
 
-fn ui<B: Backend>(f: &mut Frame<B>, app: &App) {
+fn ui(f: &mut Frame, app: &App) {
     let size = f.size();
     let chunks = Layout::default()
         .direction(Direction::Vertical)
-        .constraints(
-            [
-                Constraint::Ratio(1, 3),
-                Constraint::Ratio(1, 3),
-                Constraint::Ratio(1, 3),
-            ]
-            .as_ref(),
-        )
+        .constraints([
+            Constraint::Ratio(1, 3),
+            Constraint::Ratio(1, 3),
+            Constraint::Ratio(1, 3),
+        ])
         .split(size);
     let x_labels = vec![
         Span::styled(
@@ -226,7 +221,8 @@ fn ui<B: Backend>(f: &mut Frame<B>, 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()
@@ -254,6 +250,8 @@ fn ui<B: Backend>(f: &mut Frame<B>, 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/chart.tape

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

examples/colors.rs

@@ -41,10 +41,10 @@ fn run_app<B: Backend>(terminal: &mut Terminal<B>) -> io::Result<()> {
     }
 }
 
-fn ui<B: Backend>(frame: &mut Frame<B>) {
+fn ui(frame: &mut Frame) {
     let layout = Layout::default()
         .direction(Direction::Vertical)
-        .constraints(vec![
+        .constraints([
             Constraint::Length(30),
             Constraint::Length(17),
             Constraint::Length(2),
@@ -75,10 +75,10 @@ const NAMED_COLORS: [Color; 16] = [
     Color::White,
 ];
 
-fn render_named_colors<B: Backend>(frame: &mut Frame<B>, area: Rect) {
+fn render_named_colors(frame: &mut Frame, area: Rect) {
     let layout = Layout::default()
         .direction(Direction::Vertical)
-        .constraints(vec![Constraint::Length(3); 10])
+        .constraints([Constraint::Length(3); 10])
         .split(area);
 
     render_fg_named_colors(frame, Color::Reset, layout[0]);
@@ -94,20 +94,20 @@ fn render_named_colors<B: Backend>(frame: &mut Frame<B>, area: Rect) {
     render_bg_named_colors(frame, Color::White, layout[9]);
 }
 
-fn render_fg_named_colors<B: Backend>(frame: &mut Frame<B>, bg: Color, area: Rect) {
+fn render_fg_named_colors(frame: &mut Frame, bg: Color, area: Rect) {
     let block = title_block(format!("Foreground colors on {bg} background"));
     let inner = block.inner(area);
     frame.render_widget(block, area);
 
     let layout = Layout::default()
         .direction(Direction::Vertical)
-        .constraints(vec![Constraint::Length(1); 2])
+        .constraints([Constraint::Length(1); 2])
         .split(inner)
         .iter()
         .flat_map(|area| {
             Layout::default()
                 .direction(Direction::Horizontal)
-                .constraints(vec![Constraint::Ratio(1, 8); 8])
+                .constraints([Constraint::Ratio(1, 8); 8])
                 .split(*area)
                 .to_vec()
         })
@@ -119,20 +119,20 @@ fn render_fg_named_colors<B: Backend>(frame: &mut Frame<B>, bg: Color, area: Rec
     }
 }
 
-fn render_bg_named_colors<B: Backend>(frame: &mut Frame<B>, fg: Color, area: Rect) {
+fn render_bg_named_colors(frame: &mut Frame, fg: Color, area: Rect) {
     let block = title_block(format!("Background colors with {fg} foreground"));
     let inner = block.inner(area);
     frame.render_widget(block, area);
 
     let layout = Layout::default()
         .direction(Direction::Vertical)
-        .constraints(vec![Constraint::Length(1); 2])
+        .constraints([Constraint::Length(1); 2])
         .split(inner)
         .iter()
         .flat_map(|area| {
             Layout::default()
                 .direction(Direction::Horizontal)
-                .constraints(vec![Constraint::Ratio(1, 8); 8])
+                .constraints([Constraint::Ratio(1, 8); 8])
                 .split(*area)
                 .to_vec()
         })
@@ -144,14 +144,14 @@ fn render_bg_named_colors<B: Backend>(frame: &mut Frame<B>, fg: Color, area: Rec
     }
 }
 
-fn render_indexed_colors<B: Backend>(frame: &mut Frame<B>, area: Rect) {
+fn render_indexed_colors(frame: &mut Frame, area: Rect) {
     let block = title_block("Indexed colors".into());
     let inner = block.inner(area);
     frame.render_widget(block, area);
 
     let layout = Layout::default()
         .direction(Direction::Vertical)
-        .constraints(vec![
+        .constraints([
             Constraint::Length(1), // 0 - 15
             Constraint::Length(1), // blank
             Constraint::Min(6),    // 16 - 123
@@ -164,7 +164,7 @@ fn render_indexed_colors<B: Backend>(frame: &mut Frame<B>, area: Rect) {
     //    0   1   2   3   4   5    6   7   8   9  10  11   12  13  14  15
     let color_layout = Layout::default()
         .direction(Direction::Horizontal)
-        .constraints(vec![Constraint::Length(5); 16])
+        .constraints([Constraint::Length(5); 16])
         .split(layout[0]);
     for i in 0..16 {
         let color = Color::Indexed(i);
@@ -198,7 +198,7 @@ fn render_indexed_colors<B: Backend>(frame: &mut Frame<B>, area: Rect) {
         .flat_map(|area| {
             Layout::default()
                 .direction(Direction::Horizontal)
-                .constraints(vec![Constraint::Length(27); 3])
+                .constraints([Constraint::Length(27); 3])
                 .split(*area)
                 .to_vec()
         })
@@ -206,7 +206,7 @@ fn render_indexed_colors<B: Backend>(frame: &mut Frame<B>, area: Rect) {
         .flat_map(|area| {
             Layout::default()
                 .direction(Direction::Vertical)
-                .constraints(vec![Constraint::Length(1); 6])
+                .constraints([Constraint::Length(1); 6])
                 .split(area)
                 .to_vec()
         })
@@ -214,7 +214,7 @@ fn render_indexed_colors<B: Backend>(frame: &mut Frame<B>, area: Rect) {
         .flat_map(|area| {
             Layout::default()
                 .direction(Direction::Horizontal)
-                .constraints(vec![Constraint::Min(4); 6])
+                .constraints([Constraint::Min(4); 6])
                 .split(area)
                 .to_vec()
         })
@@ -243,10 +243,10 @@ fn title_block(title: String) -> Block<'static> {
         .title_style(Style::new().reset())
 }
 
-fn render_indexed_grayscale<B: Backend>(frame: &mut Frame<B>, area: Rect) {
+fn render_indexed_grayscale(frame: &mut Frame, area: Rect) {
     let layout = Layout::default()
         .direction(Direction::Vertical)
-        .constraints(vec![
+        .constraints([
             Constraint::Length(1), // 232 - 243
             Constraint::Length(1), // 244 - 255
         ])
@@ -255,7 +255,7 @@ fn render_indexed_grayscale<B: Backend>(frame: &mut Frame<B>, area: Rect) {
         .flat_map(|area| {
             Layout::default()
                 .direction(Direction::Horizontal)
-                .constraints(vec![Constraint::Length(6); 12])
+                .constraints([Constraint::Length(6); 12])
                 .split(*area)
                 .to_vec()
         })

examples/colors.tape

@@ -1,13 +1,7 @@
 # This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
 # To run this script, install vhs and run `vhs ./examples/colors.tape`
 Output "target/colors.gif"
-# The OceanicMaterial theme is a good choice for this example (Obsidian is almost as good) because:
-# - Black is dark and distinct from the default background
-# - White is light and distinct from the default foreground
-# - Normal and bright colors are distinct
-# - Black and DarkGray are distinct
-# - White and Gray are distinct
-Set Theme "OceanicMaterial"
+Set Theme "Aardvark Blue"
 Set Width 1200
 Set Height 1410
 Hide

examples/colors_rgb.rs

@@ -89,7 +89,7 @@ impl RgbColors {
     fn layout(area: Rect) -> Rc<[Rect]> {
         Layout::default()
             .direction(Direction::Vertical)
-            .constraints(vec![Constraint::Length(1), Constraint::Min(0)])
+            .constraints([Constraint::Length(1), Constraint::Min(0)])
             .split(area)
     }
 

examples/colors_rgb.tape

@@ -1,18 +1,13 @@
 # This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
 # To run this script, install vhs and run `vhs ./examples/colors_rgb.tape`
 Output "target/colors_rgb.gif"
-# The OceanicMaterial theme is a good choice for this example (Obsidian is almost as good) because:
-# - Black is dark and distinct from the default background
-# - White is light and distinct from the default foreground
-# - Normal and bright colors are distinct
-# - Black and DarkGray are distinct
-# - White and Gray are distinct
-Set Theme "OceanicMaterial"
+Set Theme "Aardvark Blue"
 Set Width 1200
-Set Height 1410
+Set Height 800
 Hide
 Type "cargo run --example=colors_rgb --features=crossterm"
 Enter
 Sleep 2s
+Screenshot "target/colors_rgb.png"
 Show
 Sleep 1s

examples/custom_widget.rs

@@ -1,27 +1,121 @@
-use std::{error::Error, io};
+use std::{error::Error, io, ops::ControlFlow, time::Duration};
 
 use crossterm::{
-    event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode},
+    event::{
+        self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode, MouseButton, MouseEvent,
+        MouseEventKind,
+    },
     execute,
     terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
 };
 use ratatui::{prelude::*, widgets::*};
 
-#[derive(Default)]
-struct Label<'a> {
-    text: &'a str,
+/// A custom widget that renders a button with a label, theme and state.
+#[derive(Debug, Clone)]
+struct Button<'a> {
+    label: Line<'a>,
+    theme: Theme,
+    state: State,
 }
 
-impl<'a> Widget for Label<'a> {
-    fn render(self, area: Rect, buf: &mut Buffer) {
-        buf.set_string(area.left(), area.top(), self.text, Style::default());
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum State {
+    Normal,
+    Selected,
+    Active,
+}
+
+#[derive(Debug, Clone, Copy)]
+struct Theme {
+    text: Color,
+    background: Color,
+    highlight: Color,
+    shadow: Color,
+}
+
+const BLUE: Theme = Theme {
+    text: Color::Rgb(16, 24, 48),
+    background: Color::Rgb(48, 72, 144),
+    highlight: Color::Rgb(64, 96, 192),
+    shadow: Color::Rgb(32, 48, 96),
+};
+
+const RED: Theme = Theme {
+    text: Color::Rgb(48, 16, 16),
+    background: Color::Rgb(144, 48, 48),
+    highlight: Color::Rgb(192, 64, 64),
+    shadow: Color::Rgb(96, 32, 32),
+};
+
+const GREEN: Theme = Theme {
+    text: Color::Rgb(16, 48, 16),
+    background: Color::Rgb(48, 144, 48),
+    highlight: Color::Rgb(64, 192, 64),
+    shadow: Color::Rgb(32, 96, 32),
+};
+
+/// A button with a label that can be themed.
+impl<'a> Button<'a> {
+    pub fn new<T: Into<Line<'a>>>(label: T) -> Button<'a> {
+        Button {
+            label: label.into(),
+            theme: BLUE,
+            state: State::Normal,
+        }
+    }
+
+    pub fn theme(mut self, theme: Theme) -> Button<'a> {
+        self.theme = theme;
+        self
+    }
+
+    pub fn state(mut self, state: State) -> Button<'a> {
+        self.state = state;
+        self
     }
 }
 
-impl<'a> Label<'a> {
-    fn text(mut self, text: &'a str) -> Label<'a> {
-        self.text = text;
-        self
+impl<'a> Widget for Button<'a> {
+    fn render(self, area: Rect, buf: &mut Buffer) {
+        let (background, text, shadow, highlight) = self.colors();
+        buf.set_style(area, Style::new().bg(background).fg(text));
+
+        // render top line if there's enough space
+        if area.height > 2 {
+            buf.set_string(
+                area.x,
+                area.y,
+                "▔".repeat(area.width as usize),
+                Style::new().fg(highlight).bg(background),
+            );
+        }
+        // render bottom line if there's enough space
+        if area.height > 1 {
+            buf.set_string(
+                area.x,
+                area.y + area.height - 1,
+                "▁".repeat(area.width as usize),
+                Style::new().fg(shadow).bg(background),
+            );
+        }
+        // render label centered
+        buf.set_line(
+            area.x + (area.width.saturating_sub(self.label.width() as u16)) / 2,
+            area.y + (area.height.saturating_sub(1)) / 2,
+            &self.label,
+            area.width,
+        );
+    }
+}
+
+impl Button<'_> {
+    fn colors(&self) -> (Color, Color, Color, Color) {
+        let theme = self.theme;
+        match self.state {
+            State::Normal => (theme.background, theme.text, theme.shadow, theme.highlight),
+            State::Selected => (theme.highlight, theme.text, theme.shadow, theme.highlight),
+            State::Active => (theme.background, theme.text, theme.highlight, theme.shadow),
+        }
     }
 }
 
@@ -53,19 +147,126 @@ fn main() -> Result<(), Box<dyn Error>> {
 }
 
 fn run_app<B: Backend>(terminal: &mut Terminal<B>) -> io::Result<()> {
+    let mut selected_button: usize = 0;
+    let button_states = &mut [State::Selected, State::Normal, State::Normal];
     loop {
-        terminal.draw(ui)?;
-
-        if let Event::Key(key) = event::read()? {
-            if let KeyCode::Char('q') = key.code {
-                return Ok(());
+        terminal.draw(|frame| ui(frame, button_states))?;
+        if !event::poll(Duration::from_millis(100))? {
+            continue;
+        }
+        match event::read()? {
+            Event::Key(key) => {
+                if key.kind != event::KeyEventKind::Press {
+                    continue;
+                }
+                if handle_key_event(key, button_states, &mut selected_button).is_break() {
+                    break;
+                }
             }
+            Event::Mouse(mouse) => handle_mouse_event(mouse, button_states, &mut selected_button),
+            _ => (),
         }
     }
+    Ok(())
 }
 
-fn ui<B: Backend>(f: &mut Frame<B>) {
-    let size = f.size();
-    let label = Label::default().text("Test");
-    f.render_widget(label, size);
+fn ui(frame: &mut Frame, states: &[State; 3]) {
+    let layout = Layout::default()
+        .direction(Direction::Vertical)
+        .constraints([
+            Constraint::Length(1),
+            Constraint::Max(3),
+            Constraint::Length(1),
+            Constraint::Min(0), // ignore remaining space
+        ])
+        .split(frame.size());
+    frame.render_widget(
+        Paragraph::new("Custom Widget Example (mouse enabled)"),
+        layout[0],
+    );
+    render_buttons(frame, layout[1], states);
+    frame.render_widget(
+        Paragraph::new("←/→: select, Space: toggle, q: quit"),
+        layout[2],
+    );
+}
+
+fn render_buttons(frame: &mut Frame<'_>, area: Rect, states: &[State; 3]) {
+    let layout = Layout::default()
+        .direction(Direction::Horizontal)
+        .constraints([
+            Constraint::Length(15),
+            Constraint::Length(15),
+            Constraint::Length(15),
+            Constraint::Min(0), // ignore remaining space
+        ])
+        .split(area);
+    frame.render_widget(Button::new("Red").theme(RED).state(states[0]), layout[0]);
+    frame.render_widget(
+        Button::new("Green").theme(GREEN).state(states[1]),
+        layout[1],
+    );
+    frame.render_widget(Button::new("Blue").theme(BLUE).state(states[2]), layout[2]);
+}
+
+fn handle_key_event(
+    key: event::KeyEvent,
+    button_states: &mut [State; 3],
+    selected_button: &mut usize,
+) -> ControlFlow<()> {
+    match key.code {
+        KeyCode::Char('q') => return ControlFlow::Break(()),
+        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::Char('l') => {
+            button_states[*selected_button] = State::Normal;
+            *selected_button = selected_button.saturating_add(1).min(2);
+            button_states[*selected_button] = State::Selected;
+        }
+        KeyCode::Char(' ') => {
+            if button_states[*selected_button] == State::Active {
+                button_states[*selected_button] = State::Normal;
+            } else {
+                button_states[*selected_button] = State::Active;
+            }
+        }
+        _ => (),
+    }
+    ControlFlow::Continue(())
+}
+
+fn handle_mouse_event(
+    mouse: MouseEvent,
+    button_states: &mut [State; 3],
+    selected_button: &mut usize,
+) {
+    match mouse.kind {
+        MouseEventKind::Moved => {
+            let old_selected_button = *selected_button;
+            *selected_button = match mouse.column {
+                x if x < 15 => 0,
+                x if x < 30 => 1,
+                _ => 2,
+            };
+            if old_selected_button != *selected_button {
+                if button_states[old_selected_button] != State::Active {
+                    button_states[old_selected_button] = State::Normal;
+                }
+                if button_states[*selected_button] != State::Active {
+                    button_states[*selected_button] = State::Selected;
+                }
+            }
+        }
+        MouseEventKind::Down(MouseButton::Left) => {
+            if button_states[*selected_button] == State::Active {
+                button_states[*selected_button] = State::Normal;
+            } else {
+                button_states[*selected_button] = State::Active;
+            }
+        }
+        _ => (),
+    }
 }

examples/custom_widget.tape

@@ -1,12 +1,21 @@
 # This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
 # To run this script, install vhs and run `vhs ./examples/custom_widget.tape`
 Output "target/custom_widget.gif"
-Set Theme "OceanicMaterial"
-Set Width 1200
-Set Height 200
+Set Theme "Aardvark Blue"
+Set Width 760
+Set Height 260
 Hide
 Type "cargo run --example=custom_widget --features=crossterm"
 Enter
-Sleep 1s
+Sleep 2s
 Show
-Sleep 5s
+Sleep 1s
+Set TypingSpeed 0.7s
+Right
+Right
+Space
+Space
+Left
+Space
+Left
+Space

examples/demo.tape

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

examples/demo/crossterm.rs

@@ -50,18 +50,16 @@ fn run_app<B: Backend>(
     loop {
         terminal.draw(|f| ui::draw(f, &mut app))?;
 
-        let timeout = tick_rate
-            .checked_sub(last_tick.elapsed())
-            .unwrap_or_else(|| Duration::from_secs(0));
+        let timeout = tick_rate.saturating_sub(last_tick.elapsed());
         if crossterm::event::poll(timeout)? {
             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

@@ -1,6 +1,5 @@
 use std::{
     error::Error,
-    io,
     time::{Duration, Instant},
 };
 
@@ -32,26 +31,24 @@ fn run_app(
     terminal: &mut Terminal<TermwizBackend>,
     mut app: App,
     tick_rate: Duration,
-) -> io::Result<()> {
+) -> Result<(), Box<dyn Error>> {
     let mut last_tick = Instant::now();
     loop {
         terminal.draw(|f| ui::draw(f, &mut app))?;
 
-        let timeout = tick_rate
-            .checked_sub(last_tick.elapsed())
-            .unwrap_or_else(|| Duration::from_secs(0));
-        if let Ok(Some(input)) = terminal
+        let timeout = tick_rate.saturating_sub(last_tick.elapsed());
+        if let Some(input) = terminal
             .backend_mut()
             .buffered_terminal_mut()
             .terminal()
-            .poll_input(Some(timeout))
+            .poll_input(Some(timeout))?
         {
             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

@@ -5,9 +5,9 @@ use ratatui::{
 
 use crate::app::App;
 
-pub fn draw<B: Backend>(f: &mut Frame<B>, app: &mut App) {
+pub fn draw(f: &mut Frame, app: &mut App) {
     let chunks = Layout::default()
-        .constraints([Constraint::Length(3), Constraint::Min(0)].as_ref())
+        .constraints([Constraint::Length(3), Constraint::Min(0)])
         .split(f.size());
     let titles = app
         .tabs
@@ -28,38 +28,26 @@ pub fn draw<B: Backend>(f: &mut Frame<B>, app: &mut App) {
     };
 }
 
-fn draw_first_tab<B>(f: &mut Frame<B>, app: &mut App, area: Rect)
-where
-    B: Backend,
-{
+fn draw_first_tab(f: &mut Frame, app: &mut App, area: Rect) {
     let chunks = Layout::default()
-        .constraints(
-            [
-                Constraint::Length(9),
-                Constraint::Min(8),
-                Constraint::Length(7),
-            ]
-            .as_ref(),
-        )
+        .constraints([
+            Constraint::Length(9),
+            Constraint::Min(8),
+            Constraint::Length(7),
+        ])
         .split(area);
     draw_gauges(f, app, chunks[0]);
     draw_charts(f, app, chunks[1]);
     draw_text(f, chunks[2]);
 }
 
-fn draw_gauges<B>(f: &mut Frame<B>, app: &mut App, area: Rect)
-where
-    B: Backend,
-{
+fn draw_gauges(f: &mut Frame, app: &mut App, area: Rect) {
     let chunks = Layout::default()
-        .constraints(
-            [
-                Constraint::Length(2),
-                Constraint::Length(3),
-                Constraint::Length(1),
-            ]
-            .as_ref(),
-        )
+        .constraints([
+            Constraint::Length(2),
+            Constraint::Length(3),
+            Constraint::Length(1),
+        ])
         .margin(1)
         .split(area);
     let block = Block::default().borders(Borders::ALL).title("Graphs");
@@ -102,10 +90,7 @@ where
     f.render_widget(line_gauge, chunks[2]);
 }
 
-fn draw_charts<B>(f: &mut Frame<B>, app: &mut App, area: Rect)
-where
-    B: Backend,
-{
+fn draw_charts(f: &mut Frame, app: &mut App, area: Rect) {
     let constraints = if app.show_chart {
         vec![Constraint::Percentage(50), Constraint::Percentage(50)]
     } else {
@@ -117,11 +102,11 @@ where
         .split(area);
     {
         let chunks = Layout::default()
-            .constraints([Constraint::Percentage(50), Constraint::Percentage(50)].as_ref())
+            .constraints([Constraint::Percentage(50), Constraint::Percentage(50)])
             .split(chunks[0]);
         {
             let chunks = Layout::default()
-                .constraints([Constraint::Percentage(50), Constraint::Percentage(50)].as_ref())
+                .constraints([Constraint::Percentage(50), Constraint::Percentage(50)])
                 .direction(Direction::Horizontal)
                 .split(chunks[0]);
 
@@ -249,10 +234,7 @@ where
     }
 }
 
-fn draw_text<B>(f: &mut Frame<B>, area: Rect)
-where
-    B: Backend,
-{
+fn draw_text(f: &mut Frame, area: Rect) {
     let text = vec![
         text::Line::from("This is a paragraph with several lines. You can change style your text the way you want"),
         text::Line::from(""),
@@ -290,12 +272,9 @@ where
     f.render_widget(paragraph, area);
 }
 
-fn draw_second_tab<B>(f: &mut Frame<B>, app: &mut App, area: Rect)
-where
-    B: Backend,
-{
+fn draw_second_tab(f: &mut Frame, app: &mut App, area: Rect) {
     let chunks = Layout::default()
-        .constraints([Constraint::Percentage(30), Constraint::Percentage(70)].as_ref())
+        .constraints([Constraint::Percentage(30), Constraint::Percentage(70)])
         .direction(Direction::Horizontal)
         .split(area);
     let up_style = Style::default().fg(Color::Green);
@@ -310,18 +289,20 @@ where
         };
         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()
@@ -379,10 +360,7 @@ where
     f.render_widget(map, chunks[1]);
 }
 
-fn draw_third_tab<B>(f: &mut Frame<B>, _app: &mut App, area: Rect)
-where
-    B: Backend,
-{
+fn draw_third_tab(f: &mut Frame, _app: &mut App, area: Rect) {
     let chunks = Layout::default()
         .direction(Direction::Horizontal)
         .constraints([Constraint::Ratio(1, 2), Constraint::Ratio(1, 2)])
@@ -417,12 +395,14 @@ where
             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-social.tape

@@ -2,7 +2,7 @@
 # To run this script, install vhs and run `vhs ./examples/demo.tape`
 
 Output "target/demo2-social.gif"
-Set Theme "OceanicMaterial"
+Set Theme "Aardvark Blue"
 # Github social preview size (1280x640 with 80px padding) and must be < 1MB
 # This puts some constraints on the amount of interactivity we can do.
 Set Width 1280

examples/demo2.tape

@@ -2,7 +2,7 @@
 # To run this script, install vhs and run `vhs ./examples/demo.tape`
 # NOTE: Requires VHS 0.6.1 or later for Screenshot support
 Output "target/demo2.gif"
-Set Theme "OceanicMaterial"
+Set Theme "Aardvark Blue"
 # The reason for this strange size is that the social preview image for this
 # demo is 1280x64 with 80 pixels of padding on each side. We want a version
 # without the padding for README.md, etc.

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

@@ -30,7 +30,7 @@ impl Widget for TracerouteTab {
         Block::new().style(THEME.content).render(area, buf);
         let area = Layout::default()
             .direction(Direction::Horizontal)
-            .constraints(vec![Constraint::Ratio(1, 2), Constraint::Ratio(1, 2)])
+            .constraints([Constraint::Ratio(1, 2), Constraint::Ratio(1, 2)])
             .split(area);
         let left_area = layout(area[0], Direction::Vertical, vec![0, 3]);
         render_hops(self.selected_row, left_area[0], buf);
@@ -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,
@@ -111,11 +110,11 @@ fn render_map(selected_row: usize, area: Rect, buf: &mut Buffer) {
                 .padding(Padding::new(1, 0, 1, 0))
                 .style(theme.style),
         )
-        .marker(Marker::Dot)
+        .marker(Marker::HalfBlock)
         // picked to show Australia for the demo as it's the most interesting part of the map
         // (and the only part with hops ;))
-        .x_bounds([113.0, 154.0])
-        .y_bounds([-42.0, -11.0])
+        .x_bounds([112.0, 155.0])
+        .y_bounds([-46.0, -11.0])
         .paint(|context| {
             context.draw(&map);
             if let Some(path) = path {

examples/docsrs.rs

@@ -0,0 +1,126 @@
+use std::io::{self, stdout};
+
+use crossterm::{
+    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+    ExecutableCommand,
+};
+use ratatui::{prelude::*, widgets::*};
+
+/// Example code for libr.rs
+///
+/// When cargo-rdme supports doc comments that import from code, this will be imported
+/// rather than copied to the lib.rs file.
+fn main() -> io::Result<()> {
+    let arg = std::env::args().nth(1).unwrap_or_default();
+    enable_raw_mode()?;
+    stdout().execute(EnterAlternateScreen)?;
+    let mut terminal = Terminal::new(CrosstermBackend::new(stdout()))?;
+
+    let mut should_quit = false;
+    while !should_quit {
+        terminal.draw(match arg.as_str() {
+            "hello_world" => hello_world,
+            "layout" => layout,
+            "styling" => styling,
+            _ => hello_world,
+        })?;
+        should_quit = handle_events()?;
+    }
+
+    disable_raw_mode()?;
+    stdout().execute(LeaveAlternateScreen)?;
+    Ok(())
+}
+
+fn hello_world(frame: &mut Frame) {
+    frame.render_widget(
+        Paragraph::new("Hello World!")
+            .block(Block::default().title("Greeting").borders(Borders::ALL)),
+        frame.size(),
+    );
+}
+
+use crossterm::event::{self, Event, KeyCode};
+fn handle_events() -> io::Result<bool> {
+    if event::poll(std::time::Duration::from_millis(50))? {
+        if let Event::Key(key) = event::read()? {
+            if key.kind == event::KeyEventKind::Press && key.code == KeyCode::Char('q') {
+                return Ok(true);
+            }
+        }
+    }
+    Ok(false)
+}
+
+fn layout(frame: &mut Frame) {
+    let main_layout = Layout::default()
+        .direction(Direction::Vertical)
+        .constraints([
+            Constraint::Length(1),
+            Constraint::Min(0),
+            Constraint::Length(1),
+        ])
+        .split(frame.size());
+    frame.render_widget(
+        Block::new().borders(Borders::TOP).title("Title Bar"),
+        main_layout[0],
+    );
+    frame.render_widget(
+        Block::new().borders(Borders::TOP).title("Status Bar"),
+        main_layout[2],
+    );
+
+    let inner_layout = Layout::default()
+        .direction(Direction::Horizontal)
+        .constraints([Constraint::Percentage(50), Constraint::Percentage(50)])
+        .split(main_layout[1]);
+    frame.render_widget(
+        Block::default().borders(Borders::ALL).title("Left"),
+        inner_layout[0],
+    );
+    frame.render_widget(
+        Block::default().borders(Borders::ALL).title("Right"),
+        inner_layout[1],
+    );
+}
+
+fn styling(frame: &mut Frame) {
+    let areas = Layout::default()
+        .direction(Direction::Vertical)
+        .constraints([
+            Constraint::Length(1),
+            Constraint::Length(1),
+            Constraint::Length(1),
+            Constraint::Length(1),
+            Constraint::Min(0),
+        ])
+        .split(frame.size());
+
+    let span1 = Span::raw("Hello ");
+    let span2 = Span::styled(
+        "World",
+        Style::new()
+            .fg(Color::Green)
+            .bg(Color::White)
+            .add_modifier(Modifier::BOLD),
+    );
+    let span3 = "!".red().on_light_yellow().italic();
+
+    let line = Line::from(vec![span1, span2, span3]);
+    let text: Text = Text::from(vec![line]);
+
+    frame.render_widget(Paragraph::new(text), areas[0]);
+    // or using the short-hand syntax and implicit conversions
+    frame.render_widget(
+        Paragraph::new("Hello World!".red().on_white().bold()),
+        areas[1],
+    );
+
+    // to style the whole widget instead of just the text
+    frame.render_widget(
+        Paragraph::new("Hello World!").style(Style::new().red().on_white()),
+        areas[2],
+    );
+    // or using the short-hand syntax
+    frame.render_widget(Paragraph::new("Hello World!").blue().on_yellow(), areas[3]);
+}

examples/docsrs.tape

@@ -0,0 +1,39 @@
+# This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
+# To run this script, install vhs and run `vhs ./examples/demo.tape`
+# NOTE: Requires VHS 0.6.1 or later for Screenshot support
+Output "target/docsrs.gif"
+Set Theme "Aardvark Blue"
+# The reason for this strange size is that the social preview image for this
+# demo is 1280x64 with 80 pixels of padding on each side. We want a version
+# without the padding for README.md, etc.
+Set Width 640
+Set Height 160
+Set Padding 0
+Hide
+Type "cargo run --example docsrs --features crossterm"
+Enter
+Sleep 2s
+Show
+Sleep 1s
+Screenshot "target/docsrs-hello.png"
+Sleep 1s
+Hide
+Type "q"
+Type "cargo run --example docsrs --features crossterm -- layout"
+Enter
+Sleep 2s
+Show
+Sleep 1s
+Screenshot "target/docsrs-layout.png"
+Sleep 1s
+Hide
+Type "q"
+Type "cargo run --example docsrs --features crossterm -- styling"
+Enter
+Sleep 2s
+Show
+Sleep 1s
+Screenshot "target/docsrs-styling.png"
+Sleep 1s
+Hide
+Type "q"

examples/gauge.rs

@@ -1,17 +1,32 @@
 use std::{
-    error::Error,
-    io,
-    time::{Duration, Instant},
+    io::{self, stdout, Stdout},
+    rc::Rc,
+    time::Duration,
 };
 
+use anyhow::Result;
 use crossterm::{
-    event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode},
-    execute,
+    event::{self, Event, KeyCode, KeyEventKind},
     terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+    ExecutableCommand,
 };
-use ratatui::{prelude::*, widgets::*};
+use ratatui::{
+    prelude::*,
+    widgets::{block::Title, *},
+};
+
+fn main() -> Result<()> {
+    App::run()
+}
 
 struct App {
+    term: Term,
+    should_quit: bool,
+    state: AppState,
+}
+
+#[derive(Debug, Default, Clone, Copy)]
+struct AppState {
     progress1: u16,
     progress2: u16,
     progress3: f64,
@@ -19,141 +34,154 @@ struct App {
 }
 
 impl App {
-    fn new() -> App {
-        App {
-            progress1: 0,
-            progress2: 0,
-            progress3: 0.45,
-            progress4: 0,
+    fn run() -> Result<()> {
+        // run at ~10 fps minus the time it takes to draw
+        let timeout = Duration::from_secs_f32(1.0 / 10.0);
+        let mut app = Self::start()?;
+        while !app.should_quit {
+            app.update();
+            app.draw()?;
+            app.handle_events(timeout)?;
         }
+        app.stop()?;
+        Ok(())
     }
 
-    fn on_tick(&mut self) {
-        self.progress1 += 1;
-        if self.progress1 > 100 {
-            self.progress1 = 0;
-        }
-        self.progress2 += 2;
-        if self.progress2 > 100 {
-            self.progress2 = 0;
-        }
-        self.progress3 += 0.001;
-        if self.progress3 > 1.0 {
-            self.progress3 = 0.0;
-        }
-        self.progress4 += 1;
-        if self.progress4 > 100 {
-            self.progress4 = 0;
-        }
-    }
-}
-
-fn main() -> Result<(), Box<dyn Error>> {
-    // setup terminal
-    enable_raw_mode()?;
-    let mut stdout = io::stdout();
-    execute!(stdout, EnterAlternateScreen, EnableMouseCapture)?;
-    let backend = CrosstermBackend::new(stdout);
-    let mut terminal = Terminal::new(backend)?;
-
-    // create app and run it
-    let tick_rate = Duration::from_millis(250);
-    let app = App::new();
-    let res = run_app(&mut terminal, app, tick_rate);
-
-    // restore terminal
-    disable_raw_mode()?;
-    execute!(
-        terminal.backend_mut(),
-        LeaveAlternateScreen,
-        DisableMouseCapture
-    )?;
-    terminal.show_cursor()?;
-
-    if let Err(err) = res {
-        println!("{err:?}");
+    fn start() -> Result<Self> {
+        Ok(App {
+            term: Term::start()?,
+            should_quit: false,
+            state: AppState {
+                progress1: 0,
+                progress2: 0,
+                progress3: 0.0,
+                progress4: 0,
+            },
+        })
     }
 
-    Ok(())
-}
+    fn stop(&mut self) -> Result<()> {
+        Term::stop()?;
+        Ok(())
+    }
 
-fn run_app<B: Backend>(
-    terminal: &mut Terminal<B>,
-    mut app: App,
-    tick_rate: Duration,
-) -> io::Result<()> {
-    let mut last_tick = Instant::now();
-    loop {
-        terminal.draw(|f| ui(f, &app))?;
+    fn update(&mut self) {
+        self.state.progress1 = (self.state.progress1 + 4).min(100);
+        self.state.progress2 = (self.state.progress2 + 3).min(100);
+        self.state.progress3 = (self.state.progress3 + 0.02).min(1.0);
+        self.state.progress4 = (self.state.progress4 + 1).min(100);
+    }
 
-        let timeout = tick_rate
-            .checked_sub(last_tick.elapsed())
-            .unwrap_or_else(|| Duration::from_secs(0));
-        if crossterm::event::poll(timeout)? {
+    fn draw(&mut self) -> Result<()> {
+        self.term.draw(|frame| {
+            let state = self.state;
+            let layout = Self::equal_layout(frame);
+            Self::render_gauge1(state.progress1, frame, layout[0]);
+            Self::render_gauge2(state.progress2, frame, layout[1]);
+            Self::render_gauge3(state.progress3, frame, layout[2]);
+            Self::render_gauge4(state.progress4, frame, layout[3]);
+        })?;
+        Ok(())
+    }
+
+    fn handle_events(&mut self, timeout: Duration) -> io::Result<()> {
+        if event::poll(timeout)? {
             if let Event::Key(key) = event::read()? {
-                if let KeyCode::Char('q') = key.code {
-                    return Ok(());
+                if key.kind == KeyEventKind::Press {
+                    if let KeyCode::Char('q') = key.code {
+                        self.should_quit = true;
+                    }
                 }
             }
         }
-        if last_tick.elapsed() >= tick_rate {
-            app.on_tick();
-            last_tick = Instant::now();
-        }
+        Ok(())
+    }
+
+    fn equal_layout(frame: &Frame) -> Rc<[Rect]> {
+        Layout::default()
+            .direction(Direction::Vertical)
+            .constraints([
+                Constraint::Percentage(25),
+                Constraint::Percentage(25),
+                Constraint::Percentage(25),
+                Constraint::Percentage(25),
+            ])
+            .split(frame.size())
+    }
+
+    fn render_gauge1(progress: u16, frame: &mut Frame, area: Rect) {
+        let title = Self::title_block("Gauge with percentage progress");
+        let gauge = Gauge::default()
+            .block(title)
+            .gauge_style(Style::new().light_red())
+            .percent(progress);
+        frame.render_widget(gauge, area);
+    }
+
+    fn render_gauge2(progress: u16, frame: &mut Frame, area: Rect) {
+        let title = Self::title_block("Gauge with percentage progress and custom label");
+        let label = format!("{}/100", progress);
+        let gauge = Gauge::default()
+            .block(title)
+            .gauge_style(Style::new().blue().on_light_blue())
+            .percent(progress)
+            .label(label);
+        frame.render_widget(gauge, area);
+    }
+
+    fn render_gauge3(progress: f64, frame: &mut Frame, area: Rect) {
+        let title =
+            Self::title_block("Gauge with ratio progress, custom label with style, and unicode");
+        let label = Span::styled(
+            format!("{:.2}%", progress * 100.0),
+            Style::new().red().italic().bold(),
+        );
+        let gauge = Gauge::default()
+            .block(title)
+            .gauge_style(Style::default().fg(Color::Yellow))
+            .ratio(progress)
+            .label(label)
+            .use_unicode(true);
+        frame.render_widget(gauge, area);
+    }
+
+    fn render_gauge4(progress: u16, frame: &mut Frame, area: Rect) {
+        let title = Self::title_block("Gauge with percentage progress and label");
+        let label = format!("{}/100", progress);
+        let gauge = Gauge::default()
+            .block(title)
+            .gauge_style(Style::new().green().italic())
+            .percent(progress)
+            .label(label);
+        frame.render_widget(gauge, area);
+    }
+
+    fn title_block(title: &str) -> Block {
+        let title = Title::from(title).alignment(Alignment::Center);
+        Block::default().title(title).borders(Borders::TOP)
     }
 }
 
-fn ui<B: Backend>(f: &mut Frame<B>, app: &App) {
-    let chunks = Layout::default()
-        .direction(Direction::Vertical)
-        .constraints(
-            [
-                Constraint::Percentage(25),
-                Constraint::Percentage(25),
-                Constraint::Percentage(25),
-                Constraint::Percentage(25),
-            ]
-            .as_ref(),
-        )
-        .split(f.size());
-
-    let gauge = Gauge::default()
-        .block(Block::default().title("Gauge1").borders(Borders::ALL))
-        .gauge_style(Style::default().fg(Color::Yellow))
-        .percent(app.progress1);
-    f.render_widget(gauge, chunks[0]);
-
-    let label = format!("{}/100", app.progress2);
-    let gauge = Gauge::default()
-        .block(Block::default().title("Gauge2").borders(Borders::ALL))
-        .gauge_style(Style::default().fg(Color::Magenta).bg(Color::Green))
-        .percent(app.progress2)
-        .label(label);
-    f.render_widget(gauge, chunks[1]);
-
-    let label = Span::styled(
-        format!("{:.2}%", app.progress3 * 100.0),
-        Style::default()
-            .fg(Color::Red)
-            .add_modifier(Modifier::ITALIC | Modifier::BOLD),
-    );
-    let gauge = Gauge::default()
-        .block(Block::default().title("Gauge3").borders(Borders::ALL))
-        .gauge_style(Style::default().fg(Color::Yellow))
-        .ratio(app.progress3)
-        .label(label)
-        .use_unicode(true);
-    f.render_widget(gauge, chunks[2]);
-
-    let label = format!("{}/100", app.progress4);
-    let gauge = Gauge::default()
-        .block(Block::default().title("Gauge4").borders(Borders::ALL))
-        .gauge_style(
-            Style::default()
-                .fg(Color::Cyan)
-                .add_modifier(Modifier::ITALIC),
-        )
-        .percent(app.progress4)
-        .label(label);
-    f.render_widget(gauge, chunks[3]);
+struct Term {
+    terminal: Terminal<CrosstermBackend<Stdout>>,
+}
+
+impl Term {
+    pub fn start() -> io::Result<Term> {
+        stdout().execute(EnterAlternateScreen)?;
+        enable_raw_mode()?;
+        let terminal = Terminal::new(CrosstermBackend::new(stdout()))?;
+        Ok(Self { terminal })
+    }
+
+    pub fn stop() -> io::Result<()> {
+        disable_raw_mode()?;
+        stdout().execute(LeaveAlternateScreen)?;
+        Ok(())
+    }
+
+    fn draw(&mut self, frame: impl FnOnce(&mut Frame)) -> Result<()> {
+        self.terminal.draw(frame)?;
+        Ok(())
+    }
 }

examples/gauge.tape

@@ -1,9 +1,9 @@
 # This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
 # To run this script, install vhs and run `vhs ./examples/gauge.tape`
 Output "target/gauge.gif"
-Set Theme "OceanicMaterial"
+Set Theme "Aardvark Blue"
 Set Width 1200
-Set Height 600
+Set Height 550
 Hide
 Type "cargo run --example=gauge --features=crossterm"
 Enter

examples/generate.bash

@@ -5,7 +5,11 @@
 # - cargo: https://doc.rust-lang.org/cargo/getting-started/installation.html
 # - gh: https://github.com/cli/cli
 # - git: https://git-scm.com/
-# - vhs: https://github.com/charmbracelet/vhs
+# - vhs: https://github.com/charmbracelet/vhs - currently this needs to be installed from the
+#   main branch, as the latest release doesn't support the theme we use or the Screenshot
+#   command. Install using `go install github.com/charmbracelet/vhs@main``
+# - go: https://golang.org/doc/install
+# - ttyd: https://github.com/tsl0922/ttyd
 
 # Exit on error. Append "|| true" if you expect an error.
 set -o errexit
@@ -21,11 +25,10 @@ set -o pipefail
 # ensure that running each example doesn't have to wait for the build
 cargo build --examples --features=crossterm,all-widgets
 
-for tape in examples/*.tape
-do
-    gif=${tape/examples\/}
+for tape in examples/*.tape; do
+    gif=${tape/examples\//}
     gif=${gif/.tape/.gif}
-    vhs $tape --quiet
+    ~/go/bin/vhs $tape --quiet
     # this can be pasted into the examples README.md
     echo "[${gif}]: https://github.com/ratatui-org/ratatui/blob/images/examples/${gif}?raw=true"
 done
@@ -35,4 +38,4 @@ cp target/*.gif examples/
 git add examples/*.gif
 git commit -m 'docs(examples): update images'
 gh pr create
-git sw main
+git sw -

examples/hello_world.rs

@@ -61,7 +61,7 @@ fn run(terminal: &mut Terminal<CrosstermBackend<Stdout>>) -> Result<()> {
 
 /// Render the application. This is where you would draw the application UI. This example just
 /// draws a greeting.
-fn render_app(frame: &mut ratatui::Frame<CrosstermBackend<Stdout>>) {
+fn render_app(frame: &mut Frame) {
     let greeting = Paragraph::new("Hello World! (press 'q' to quit)");
     frame.render_widget(greeting, frame.size());
 }

examples/hello_world.tape

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

examples/inline.rs

@@ -98,9 +98,7 @@ fn input_handling(tx: mpsc::Sender<Event>) {
         let mut last_tick = Instant::now();
         loop {
             // poll for tick rate duration, if no events, sent tick event.
-            let timeout = tick_rate
-                .checked_sub(last_tick.elapsed())
-                .unwrap_or_else(|| Duration::from_secs(0));
+            let timeout = tick_rate.saturating_sub(last_tick.elapsed());
             if crossterm::event::poll(timeout).unwrap() {
                 match crossterm::event::read().unwrap() {
                     crossterm::event::Event::Key(key) => tx.send(Event::Input(key)).unwrap(),
@@ -216,14 +214,14 @@ fn run_app<B: Backend>(
     Ok(())
 }
 
-fn ui<B: Backend>(f: &mut Frame<B>, downloads: &Downloads) {
+fn ui(f: &mut Frame, downloads: &Downloads) {
     let size = f.size();
 
     let block = Block::default().title(block::Title::from("Progress").alignment(Alignment::Center));
     f.render_widget(block, size);
 
     let chunks = Layout::default()
-        .constraints(vec![Constraint::Length(2), Constraint::Length(4)])
+        .constraints([Constraint::Length(2), Constraint::Length(4)])
         .margin(1)
         .split(size);
 
@@ -237,7 +235,7 @@ fn ui<B: Backend>(f: &mut Frame<B>, downloads: &Downloads) {
 
     let chunks = Layout::default()
         .direction(Direction::Horizontal)
-        .constraints(vec![Constraint::Percentage(20), Constraint::Percentage(80)])
+        .constraints([Constraint::Percentage(20), Constraint::Percentage(80)])
         .split(chunks[1]);
 
     // in progress downloads

examples/inline.tape

@@ -1,7 +1,7 @@
 # This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
 # To run this script, install vhs and run `vhs ./examples/inline.tape`
 Output "target/inline.gif"
-Set Theme "OceanicMaterial"
+Set Theme "Aardvark Blue"
 Set Width 1200
 Set Height 600
 Type "cargo run --example=inline --features=crossterm"

examples/layout.rs

@@ -37,7 +37,7 @@ fn main() -> Result<(), Box<dyn Error>> {
 
 fn run_app<B: Backend>(terminal: &mut Terminal<B>) -> io::Result<()> {
     loop {
-        terminal.draw(|f| ui(f))?;
+        terminal.draw(ui)?;
 
         if let Event::Key(key) = event::read()? {
             if let KeyCode::Char('q') = key.code {
@@ -47,10 +47,10 @@ fn run_app<B: Backend>(terminal: &mut Terminal<B>) -> io::Result<()> {
     }
 }
 
-fn ui<B: Backend>(frame: &mut Frame<B>) {
+fn ui(frame: &mut Frame) {
     let main_layout = Layout::default()
         .direction(Direction::Vertical)
-        .constraints(vec![
+        .constraints([
             Length(4),  // text
             Length(50), // examples
             Min(0),     // fills remaining space
@@ -71,7 +71,7 @@ fn ui<B: Backend>(frame: &mut Frame<B>) {
 
     let example_rows = Layout::default()
         .direction(Direction::Vertical)
-        .constraints(vec![
+        .constraints([
             Length(9),
             Length(9),
             Length(9),
@@ -85,7 +85,7 @@ fn ui<B: Backend>(frame: &mut Frame<B>) {
         .flat_map(|area| {
             Layout::default()
                 .direction(Direction::Horizontal)
-                .constraints(vec![
+                .constraints([
                     Length(14),
                     Length(14),
                     Length(14),
@@ -169,8 +169,8 @@ fn ui<B: Backend>(frame: &mut Frame<B>) {
 }
 
 /// Renders a single example box
-fn render_example_combination<B: Backend>(
-    frame: &mut Frame<B>,
+fn render_example_combination(
+    frame: &mut Frame,
     area: Rect,
     title: &str,
     constraints: Vec<(Constraint, Constraint)>,
@@ -195,11 +195,7 @@ fn render_example_combination<B: Backend>(
 }
 
 /// Renders a single example line
-fn render_single_example<B: Backend>(
-    frame: &mut Frame<B>,
-    area: Rect,
-    constraints: Vec<Constraint>,
-) {
+fn render_single_example(frame: &mut Frame, area: Rect, constraints: Vec<Constraint>) {
     let red = Paragraph::new(constraint_label(constraints[0])).on_red();
     let blue = Paragraph::new(constraint_label(constraints[1])).on_blue();
     let green = Paragraph::new("·".repeat(12)).on_green();

examples/layout.tape

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

examples/list.rs

@@ -175,17 +175,15 @@ fn run_app<B: Backend>(
     loop {
         terminal.draw(|f| ui(f, &mut app))?;
 
-        let timeout = tick_rate
-            .checked_sub(last_tick.elapsed())
-            .unwrap_or_else(|| Duration::from_secs(0));
+        let timeout = tick_rate.saturating_sub(last_tick.elapsed());
         if crossterm::event::poll(timeout)? {
             if let Event::Key(key) = event::read()? {
                 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(),
                         _ => {}
                     }
                 }
@@ -198,11 +196,11 @@ fn run_app<B: Backend>(
     }
 }
 
-fn ui<B: Backend>(f: &mut Frame<B>, app: &mut App) {
+fn ui(f: &mut Frame, app: &mut App) {
     // Create two chunks with equal horizontal screen space
     let chunks = Layout::default()
         .direction(Direction::Horizontal)
-        .constraints([Constraint::Percentage(50), Constraint::Percentage(50)].as_ref())
+        .constraints([Constraint::Percentage(50), Constraint::Percentage(50)])
         .split(f.size());
 
     // Iterate through all elements in the `items` app and append some debug text to it.
@@ -275,6 +273,6 @@ fn ui<B: Backend>(f: &mut Frame<B>, 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/list.tape

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

examples/modifiers.rs

@@ -43,10 +43,10 @@ fn run_app<B: Backend>(terminal: &mut Terminal<B>) -> io::Result<()> {
     }
 }
 
-fn ui<B: Backend>(frame: &mut Frame<B>) {
+fn ui(frame: &mut Frame) {
     let layout = Layout::default()
         .direction(Direction::Vertical)
-        .constraints(vec![Constraint::Length(1), Constraint::Min(0)])
+        .constraints([Constraint::Length(1), Constraint::Min(0)])
         .split(frame.size());
     frame.render_widget(
         Paragraph::new("Note: not all terminals support all modifiers")
@@ -55,13 +55,13 @@ fn ui<B: Backend>(frame: &mut Frame<B>) {
     );
     let layout = Layout::default()
         .direction(Direction::Vertical)
-        .constraints(vec![Constraint::Length(1); 50])
+        .constraints([Constraint::Length(1); 50])
         .split(layout[1])
         .iter()
         .flat_map(|area| {
             Layout::default()
                 .direction(Direction::Horizontal)
-                .constraints(vec![Constraint::Percentage(20); 5])
+                .constraints([Constraint::Percentage(20); 5])
                 .split(*area)
                 .to_vec()
         })

examples/modifiers.tape

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

examples/panic.rs

@@ -102,7 +102,7 @@ fn run_tui<B: Backend>(terminal: &mut Terminal<B>, app: &mut App) -> io::Result<
 }
 
 /// Render the TUI.
-fn ui<B: Backend>(f: &mut Frame<B>, app: &App) {
+fn ui(f: &mut Frame, app: &App) {
     let text = vec![
         if app.hook_enabled {
             Line::from("HOOK IS CURRENTLY **ENABLED**")

examples/panic.tape

@@ -1,7 +1,7 @@
 # This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
 # To run this script, install vhs and run `vhs ./examples/panic.tape`
 Output "target/panic.gif"
-Set Theme "OceanicMaterial"
+Set Theme "Aardvark Blue"
 Set Width 1200
 Set Height 600
 Type "cargo run --example=panic --features=crossterm"

examples/paragraph.rs

@@ -64,9 +64,7 @@ fn run_app<B: Backend>(
     loop {
         terminal.draw(|f| ui(f, &app))?;
 
-        let timeout = tick_rate
-            .checked_sub(last_tick.elapsed())
-            .unwrap_or_else(|| Duration::from_secs(0));
+        let timeout = tick_rate.saturating_sub(last_tick.elapsed());
         if crossterm::event::poll(timeout)? {
             if let Event::Key(key) = event::read()? {
                 if let KeyCode::Char('q') = key.code {
@@ -81,7 +79,7 @@ fn run_app<B: Backend>(
     }
 }
 
-fn ui<B: Backend>(f: &mut Frame<B>, app: &App) {
+fn ui(f: &mut Frame, app: &App) {
     let size = f.size();
 
     // Words made "loooong" to demonstrate line breaking.
@@ -94,15 +92,12 @@ fn ui<B: Backend>(f: &mut Frame<B>, app: &App) {
 
     let chunks = Layout::default()
         .direction(Direction::Vertical)
-        .constraints(
-            [
-                Constraint::Percentage(25),
-                Constraint::Percentage(25),
-                Constraint::Percentage(25),
-                Constraint::Percentage(25),
-            ]
-            .as_ref(),
-        )
+        .constraints([
+            Constraint::Percentage(25),
+            Constraint::Percentage(25),
+            Constraint::Percentage(25),
+            Constraint::Percentage(25),
+        ])
         .split(size);
 
     let text = vec![

examples/paragraph.tape

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

examples/popup.rs

@@ -61,11 +61,11 @@ fn run_app<B: Backend>(terminal: &mut Terminal<B>, mut app: App) -> io::Result<(
     }
 }
 
-fn ui<B: Backend>(f: &mut Frame<B>, app: &App) {
+fn ui(f: &mut Frame, app: &App) {
     let size = f.size();
 
     let chunks = Layout::default()
-        .constraints([Constraint::Percentage(20), Constraint::Percentage(80)].as_ref())
+        .constraints([Constraint::Percentage(20), Constraint::Percentage(80)])
         .split(size);
 
     let text = if app.show_popup {
@@ -96,25 +96,19 @@ fn ui<B: Backend>(f: &mut Frame<B>, app: &App) {
 fn centered_rect(percent_x: u16, percent_y: u16, r: Rect) -> Rect {
     let popup_layout = Layout::default()
         .direction(Direction::Vertical)
-        .constraints(
-            [
-                Constraint::Percentage((100 - percent_y) / 2),
-                Constraint::Percentage(percent_y),
-                Constraint::Percentage((100 - percent_y) / 2),
-            ]
-            .as_ref(),
-        )
+        .constraints([
+            Constraint::Percentage((100 - percent_y) / 2),
+            Constraint::Percentage(percent_y),
+            Constraint::Percentage((100 - percent_y) / 2),
+        ])
         .split(r);
 
     Layout::default()
         .direction(Direction::Horizontal)
-        .constraints(
-            [
-                Constraint::Percentage((100 - percent_x) / 2),
-                Constraint::Percentage(percent_x),
-                Constraint::Percentage((100 - percent_x) / 2),
-            ]
-            .as_ref(),
-        )
+        .constraints([
+            Constraint::Percentage((100 - percent_x) / 2),
+            Constraint::Percentage(percent_x),
+            Constraint::Percentage((100 - percent_x) / 2),
+        ])
         .split(popup_layout[1])[1]
 }

examples/popup.tape

@@ -1,7 +1,7 @@
 # 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/popup.gif"
-Set Theme "OceanicMaterial"
+Set Theme "Aardvark Blue"
 Set Width 1200
 Set Height 600
 Hide

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/scrollbar.rs

@@ -57,9 +57,7 @@ fn run_app<B: Backend>(
     loop {
         terminal.draw(|f| ui(f, &mut app))?;
 
-        let timeout = tick_rate
-            .checked_sub(last_tick.elapsed())
-            .unwrap_or_else(|| Duration::from_secs(0));
+        let timeout = tick_rate.saturating_sub(last_tick.elapsed());
         if crossterm::event::poll(timeout)? {
             if let Event::Key(key) = event::read()? {
                 match key.code {
@@ -94,7 +92,7 @@ fn run_app<B: Backend>(
     }
 }
 
-fn ui<B: Backend>(f: &mut Frame<B>, app: &mut App) {
+fn ui(f: &mut Frame, app: &mut App) {
     let size = f.size();
 
     // Words made "loooong" to demonstrate line breaking.
@@ -107,16 +105,13 @@ fn ui<B: Backend>(f: &mut Frame<B>, app: &mut App) {
 
     let chunks = Layout::default()
         .direction(Direction::Vertical)
-        .constraints(
-            [
-                Constraint::Min(1),
-                Constraint::Percentage(25),
-                Constraint::Percentage(25),
-                Constraint::Percentage(25),
-                Constraint::Percentage(25),
-            ]
-            .as_ref(),
-        )
+        .constraints([
+            Constraint::Min(1),
+            Constraint::Percentage(25),
+            Constraint::Percentage(25),
+            Constraint::Percentage(25),
+            Constraint::Percentage(25),
+        ])
         .split(size);
 
     let text = vec![

examples/scrollbar.tape

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

examples/sparkline.rs

@@ -109,9 +109,7 @@ fn run_app<B: Backend>(
     loop {
         terminal.draw(|f| ui(f, &app))?;
 
-        let timeout = tick_rate
-            .checked_sub(last_tick.elapsed())
-            .unwrap_or_else(|| Duration::from_secs(0));
+        let timeout = tick_rate.saturating_sub(last_tick.elapsed());
         if crossterm::event::poll(timeout)? {
             if let Event::Key(key) = event::read()? {
                 if let KeyCode::Char('q') = key.code {
@@ -126,17 +124,14 @@ fn run_app<B: Backend>(
     }
 }
 
-fn ui<B: Backend>(f: &mut Frame<B>, app: &App) {
+fn ui(f: &mut Frame, app: &App) {
     let chunks = Layout::default()
         .direction(Direction::Vertical)
-        .constraints(
-            [
-                Constraint::Length(3),
-                Constraint::Length(3),
-                Constraint::Min(0),
-            ]
-            .as_ref(),
-        )
+        .constraints([
+            Constraint::Length(3),
+            Constraint::Length(3),
+            Constraint::Min(0),
+        ])
         .split(f.size());
     let sparkline = Sparkline::default()
         .block(

examples/sparkline.tape

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

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(),
                     _ => {}
                 }
             }
@@ -113,9 +113,9 @@ fn run_app<B: Backend>(terminal: &mut Terminal<B>, mut app: App) -> io::Result<(
     }
 }
 
-fn ui<B: Backend>(f: &mut Frame<B>, app: &mut App) {
+fn ui(f: &mut Frame, app: &mut App) {
     let rects = Layout::default()
-        .constraints([Constraint::Percentage(100)].as_ref())
+        .constraints([Constraint::Percentage(100)])
         .split(f.size());
 
     let selected_style = Style::default().add_modifier(Modifier::REVERSED);
@@ -137,15 +137,17 @@ fn ui<B: Backend>(f: &mut Frame<B>, 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/table.tape

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

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(),
                     _ => {}
                 }
             }
@@ -78,11 +78,11 @@ fn run_app<B: Backend>(terminal: &mut Terminal<B>, mut app: App) -> io::Result<(
     }
 }
 
-fn ui<B: Backend>(f: &mut Frame<B>, app: &App) {
+fn ui(f: &mut Frame, app: &App) {
     let size = f.size();
     let chunks = Layout::default()
         .direction(Direction::Vertical)
-        .constraints([Constraint::Length(3), Constraint::Min(0)].as_ref())
+        .constraints([Constraint::Length(3), Constraint::Min(0)])
         .split(size);
 
     let block = Block::default().on_white().black();
@@ -98,12 +98,8 @@ fn ui<B: Backend>(f: &mut Frame<B>, app: &App) {
     let tabs = Tabs::new(titles)
         .block(Block::default().borders(Borders::ALL).title("Tabs"))
         .select(app.index)
-        .style(Style::default().fg(Color::Cyan))
-        .highlight_style(
-            Style::default()
-                .add_modifier(Modifier::BOLD)
-                .bg(Color::Black),
-        );
+        .style(Style::default().cyan().on_gray())
+        .highlight_style(Style::default().bold().on_black());
     f.render_widget(tabs, chunks[0]);
     let inner = match app.index {
         0 => Block::default().title("Inner 0").borders(Borders::ALL),

examples/tabs.tape

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

examples/user_input.rs

@@ -171,17 +171,14 @@ fn run_app<B: Backend>(terminal: &mut Terminal<B>, mut app: App) -> io::Result<(
     }
 }
 
-fn ui<B: Backend>(f: &mut Frame<B>, app: &App) {
+fn ui(f: &mut Frame, app: &App) {
     let chunks = Layout::default()
         .direction(Direction::Vertical)
-        .constraints(
-            [
-                Constraint::Length(1),
-                Constraint::Length(3),
-                Constraint::Min(1),
-            ]
-            .as_ref(),
-        )
+        .constraints([
+            Constraint::Length(1),
+            Constraint::Length(3),
+            Constraint::Min(1),
+        ])
         .split(f.size());
 
     let (msg, style) = match app.input_mode {

examples/user_input.tape

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

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

@@ -4,12 +4,14 @@
 //! [Crossterm]: https://crates.io/crates/crossterm
 use std::io::{self, Write};
 
+#[cfg(feature = "underline-color")]
+use crossterm::style::SetUnderlineColor;
 use crossterm::{
     cursor::{Hide, MoveTo, Show},
     execute, queue,
     style::{
-        Attribute as CAttribute, Color as CColor, Print, SetAttribute, SetBackgroundColor,
-        SetForegroundColor, SetUnderlineColor,
+        Attribute as CAttribute, Attributes as CAttributes, Color as CColor, ContentStyle, Print,
+        SetAttribute, SetBackgroundColor, SetForegroundColor,
     },
     terminal::{self, Clear},
 };
@@ -19,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.
@@ -124,6 +126,7 @@ where
     {
         let mut fg = Color::Reset;
         let mut bg = Color::Reset;
+        #[cfg(feature = "underline-color")]
         let mut underline_color = Color::Reset;
         let mut modifier = Modifier::empty();
         let mut last_pos: Option<(u16, u16)> = None;
@@ -151,22 +154,31 @@ where
                 queue!(self.writer, SetBackgroundColor(color))?;
                 bg = cell.bg;
             }
+            #[cfg(feature = "underline-color")]
             if cell.underline_color != underline_color {
                 let color = CColor::from(cell.underline_color);
                 queue!(self.writer, SetUnderlineColor(color))?;
                 underline_color = cell.underline_color;
             }
 
-            queue!(self.writer, Print(&cell.symbol))?;
+            queue!(self.writer, Print(cell.symbol()))?;
         }
 
-        queue!(
+        #[cfg(feature = "underline-color")]
+        return queue!(
             self.writer,
             SetForegroundColor(CColor::Reset),
             SetBackgroundColor(CColor::Reset),
             SetUnderlineColor(CColor::Reset),
-            SetAttribute(CAttribute::Reset)
-        )
+            SetAttribute(CAttribute::Reset),
+        );
+        #[cfg(not(feature = "underline-color"))]
+        return queue!(
+            self.writer,
+            SetForegroundColor(CColor::Reset),
+            SetBackgroundColor(CColor::Reset),
+            SetAttribute(CAttribute::Reset),
+        );
     }
 
     fn hide_cursor(&mut self) -> io::Result<()> {
@@ -262,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.
@@ -332,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,16 +16,27 @@ 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,
-    #[cfg(feature = "crossterm")]
+    #[cfg(feature = "underline-color")]
     pub underline_color: Color,
     pub modifier: Modifier,
     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);
@@ -55,7 +66,7 @@ impl Cell {
         if let Some(c) = style.bg {
             self.bg = c;
         }
-        #[cfg(feature = "crossterm")]
+        #[cfg(feature = "underline-color")]
         if let Some(c) = style.underline_color {
             self.underline_color = c;
         }
@@ -64,7 +75,7 @@ impl Cell {
         self
     }
 
-    #[cfg(feature = "crossterm")]
+    #[cfg(feature = "underline-color")]
     pub fn style(&self) -> Style {
         Style::default()
             .fg(self.fg)
@@ -73,7 +84,7 @@ impl Cell {
             .add_modifier(self.modifier)
     }
 
-    #[cfg(not(feature = "crossterm"))]
+    #[cfg(not(feature = "underline-color"))]
     pub fn style(&self) -> Style {
         Style::default()
             .fg(self.fg)
@@ -95,7 +106,7 @@ impl Cell {
         self.symbol.push(' ');
         self.fg = Color::Reset;
         self.bg = Color::Reset;
-        #[cfg(feature = "crossterm")]
+        #[cfg(feature = "underline-color")]
         {
             self.underline_color = Color::Reset;
         }
@@ -106,11 +117,12 @@ impl Cell {
 
 impl Default for Cell {
     fn default() -> Cell {
+        #[allow(deprecated)] // For Cell::symbol
         Cell {
             symbol: " ".into(),
             fg: Color::Reset,
             bg: Color::Reset,
-            #[cfg(feature = "crossterm")]
+            #[cfg(feature = "underline-color")]
             underline_color: Color::Reset,
             modifier: Modifier::empty(),
             skip: false,
@@ -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 = "crossterm")]
-///     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,12 +552,12 @@ 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);
-                #[cfg(feature = "crossterm")]
+                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);
                     if last_style != Some(style) {
@@ -568,7 +565,7 @@ impl Debug for Buffer {
                         styles.push((x, y, c.fg, c.bg, c.underline_color, c.modifier));
                     }
                 }
-                #[cfg(not(feature = "crossterm"))]
+                #[cfg(not(feature = "underline-color"))]
                 {
                     let style = (c.fg, c.bg, c.modifier);
                     if last_style != Some(style) {
@@ -586,12 +583,12 @@ impl Debug for Buffer {
         }
         f.write_str("    ],\n    styles: [\n")?;
         for s in styles {
-            #[cfg(feature = "crossterm")]
+            #[cfg(feature = "underline-color")]
             f.write_fmt(format_args!(
                 "        x: {}, y: {}, fg: {:?}, bg: {:?}, underline: {:?}, modifier: {:?},\n",
                 s.0, s.1, s.2, s.3, s.4, s.5
             ))?;
-            #[cfg(not(feature = "crossterm"))]
+            #[cfg(not(feature = "underline-color"))]
             f.write_fmt(format_args!(
                 "        x: {}, y: {}, fg: {:?}, bg: {:?}, modifier: {:?},\n",
                 s.0, s.1, s.2, s.3, s.4
@@ -625,7 +622,7 @@ mod tests {
                 .bg(Color::Yellow)
                 .add_modifier(Modifier::BOLD),
         );
-        #[cfg(feature = "crossterm")]
+        #[cfg(feature = "underline-color")]
         assert_eq!(
             format!("{buf:?}"),
             indoc::indoc!(
@@ -643,7 +640,7 @@ mod tests {
                 }"
             )
         );
-        #[cfg(not(feature = "crossterm"))]
+        #[cfg(not(feature = "underline-color"))]
         assert_eq!(
             format!("{buf:?}"),
             indoc::indoc!(
@@ -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

@@ -0,0 +1,356 @@
+#![warn(missing_docs)]
+use std::{
+    cmp::{max, min},
+    fmt,
+};
+
+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)]
+#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
+pub struct Rect {
+    /// The x coordinate of the top left corner of the rect.
+    pub x: u16,
+    /// The y coordinate of the top left corner of the rect.
+    pub y: u16,
+    /// The width of the rect.
+    pub width: u16,
+    /// The height of the rect.
+    pub height: u16,
+}
+
+impl fmt::Display for Rect {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "{}x{}+{}+{}", self.width, self.height, self.x, self.y)
+    }
+}
+
+impl Rect {
+    /// Creates a new rect, with width and height limited to keep the area under max u16. If
+    /// clipped, aspect ratio will be preserved.
+    pub fn new(x: u16, y: u16, width: u16, height: u16) -> Rect {
+        let max_area = u16::max_value();
+        let (clipped_width, clipped_height) =
+            if u32::from(width) * u32::from(height) > u32::from(max_area) {
+                let aspect_ratio = f64::from(width) / f64::from(height);
+                let max_area_f = f64::from(max_area);
+                let height_f = (max_area_f / aspect_ratio).sqrt();
+                let width_f = height_f * aspect_ratio;
+                (width_f as u16, height_f as u16)
+            } else {
+                (width, height)
+            };
+        Rect {
+            x,
+            y,
+            width: clipped_width,
+            height: clipped_height,
+        }
+    }
+
+    /// The area of the rect. If the area is larger than the maximum value of u16, it will be
+    /// clamped to u16::MAX.
+    pub const fn area(self) -> u16 {
+        self.width.saturating_mul(self.height)
+    }
+
+    /// Returns true if the rect has no area.
+    pub const fn is_empty(self) -> bool {
+        self.width == 0 || self.height == 0
+    }
+
+    /// Returns the left coordinate of the rect.
+    pub const fn left(self) -> u16 {
+        self.x
+    }
+
+    /// Returns the right coordinate of the rect. This is the first coordinate outside of the rect.
+    ///
+    /// If the right coordinate is larger than the maximum value of u16, it will be clamped to
+    /// u16::MAX.
+    pub const fn right(self) -> u16 {
+        self.x.saturating_add(self.width)
+    }
+
+    /// Returns the top coordinate of the rect.
+    pub const fn top(self) -> u16 {
+        self.y
+    }
+
+    /// Returns the bottom coordinate of the rect. This is the first coordinate outside of the rect.
+    ///
+    /// If the bottom coordinate is larger than the maximum value of u16, it will be clamped to
+    /// u16::MAX.
+    pub const fn bottom(self) -> u16 {
+        self.y.saturating_add(self.height)
+    }
+
+    /// Returns a new rect inside the current one, with the given margin on each side.
+    ///
+    /// If the margin is larger than the rect, the returned rect will have no area.
+    pub fn inner(self, margin: &Margin) -> Rect {
+        let doubled_margin_horizontal = margin.horizontal.saturating_mul(2);
+        let doubled_margin_vertical = margin.vertical.saturating_mul(2);
+
+        if self.width < doubled_margin_horizontal || self.height < doubled_margin_vertical {
+            Rect::default()
+        } else {
+            Rect {
+                x: self.x.saturating_add(margin.horizontal),
+                y: self.y.saturating_add(margin.vertical),
+                width: self.width.saturating_sub(doubled_margin_horizontal),
+                height: self.height.saturating_sub(doubled_margin_vertical),
+            }
+        }
+    }
+
+    /// 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);
+        let y1 = min(self.y, other.y);
+        let x2 = max(self.right(), other.right());
+        let y2 = max(self.bottom(), other.bottom());
+        Rect {
+            x: x1,
+            y: y1,
+            width: x2.saturating_sub(x1),
+            height: y2.saturating_sub(y1),
+        }
+    }
+
+    /// Returns a new rect that is the intersection of the current one and the given one.
+    ///
+    /// If the two rects do not intersect, the returned rect will have no area.
+    pub fn intersection(self, other: Rect) -> Rect {
+        let x1 = max(self.x, other.x);
+        let y1 = max(self.y, other.y);
+        let x2 = min(self.right(), other.right());
+        let y2 = min(self.bottom(), other.bottom());
+        Rect {
+            x: x1,
+            y: y1,
+            width: x2.saturating_sub(x1),
+            height: y2.saturating_sub(y1),
+        }
+    }
+
+    /// Returns true if the two rects intersect.
+    pub const fn intersects(self, other: Rect) -> bool {
+        self.x < other.right()
+            && self.right() > other.x
+            && self.y < other.bottom()
+            && self.bottom() > other.y
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn to_string() {
+        assert_eq!(Rect::new(1, 2, 3, 4).to_string(), "3x4+1+2");
+    }
+
+    #[test]
+    fn new() {
+        assert_eq!(
+            Rect::new(1, 2, 3, 4),
+            Rect {
+                x: 1,
+                y: 2,
+                width: 3,
+                height: 4
+            }
+        );
+    }
+
+    #[test]
+    fn area() {
+        assert_eq!(Rect::new(1, 2, 3, 4).area(), 12);
+    }
+
+    #[test]
+    fn is_empty() {
+        assert!(!Rect::new(1, 2, 3, 4).is_empty());
+        assert!(Rect::new(1, 2, 0, 4).is_empty());
+        assert!(Rect::new(1, 2, 3, 0).is_empty());
+    }
+
+    #[test]
+    fn left() {
+        assert_eq!(Rect::new(1, 2, 3, 4).left(), 1);
+    }
+
+    #[test]
+    fn right() {
+        assert_eq!(Rect::new(1, 2, 3, 4).right(), 4);
+    }
+
+    #[test]
+    fn top() {
+        assert_eq!(Rect::new(1, 2, 3, 4).top(), 2);
+    }
+
+    #[test]
+    fn bottom() {
+        assert_eq!(Rect::new(1, 2, 3, 4).bottom(), 6);
+    }
+
+    #[test]
+    fn inner() {
+        assert_eq!(
+            Rect::new(1, 2, 3, 4).inner(&Margin::new(1, 2)),
+            Rect::new(2, 4, 1, 0)
+        );
+    }
+
+    #[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!(
+            Rect::new(1, 2, 3, 4).union(Rect::new(2, 3, 4, 5)),
+            Rect::new(1, 2, 5, 6)
+        );
+    }
+
+    #[test]
+    fn intersection() {
+        assert_eq!(
+            Rect::new(1, 2, 3, 4).intersection(Rect::new(2, 3, 4, 5)),
+            Rect::new(2, 3, 2, 3)
+        );
+    }
+
+    #[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)));
+        assert!(!Rect::new(1, 2, 3, 4).intersects(Rect::new(5, 6, 7, 8)));
+    }
+
+    #[test]
+    fn size_truncation() {
+        for width in 256u16..300u16 {
+            for height in 256u16..300u16 {
+                let rect = Rect::new(0, 0, width, height);
+                rect.area(); // Should not panic.
+                assert!(rect.width < width || rect.height < height);
+                // The target dimensions are rounded down so the math will not be too precise
+                // but let's make sure the ratios don't diverge crazily.
+                assert!(
+                    (f64::from(rect.width) / f64::from(rect.height)
+                        - f64::from(width) / f64::from(height))
+                    .abs()
+                        < 1.0
+                );
+            }
+        }
+
+        // One dimension below 255, one above. Area above max u16.
+        let width = 900;
+        let height = 100;
+        let rect = Rect::new(0, 0, width, height);
+        assert_ne!(rect.width, 900);
+        assert_ne!(rect.height, 100);
+        assert!(rect.width < width || rect.height < height);
+    }
+
+    #[test]
+    fn size_preservation() {
+        for width in 0..256u16 {
+            for height in 0..256u16 {
+                let rect = Rect::new(0, 0, width, height);
+                rect.area(); // Should not panic.
+                assert_eq!(rect.width, width);
+                assert_eq!(rect.height, height);
+            }
+        }
+
+        // One dimension below 255, one above. Area below max u16.
+        let rect = Rect::new(0, 0, 300, 100);
+        assert_eq!(rect.width, 300);
+        assert_eq!(rect.height, 100);
+    }
+
+    #[test]
+    fn can_be_const() {
+        const RECT: Rect = Rect {
+            x: 0,
+            y: 0,
+            width: 10,
+            height: 10,
+        };
+        const _AREA: u16 = RECT.area();
+        const _LEFT: u16 = RECT.left();
+        const _RIGHT: u16 = RECT.right();
+        const _TOP: u16 = RECT.top();
+        const _BOTTOM: u16 = RECT.bottom();
+        assert!(RECT.intersects(RECT));
+    }
+}

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,180 +1,344 @@
 #![forbid(unsafe_code)]
 
-//! [ratatui](https://github.com/ratatui-org/ratatui) is a library that is all about cooking up terminal user
-//! interfaces (TUIs).
+//! ![Demo](https://raw.githubusercontent.com/ratatui-org/ratatui/b33c878808c4c40591d7a2d9f9d94d6fee95a96f/examples/demo2.gif)
 //!
-//! ![Demo](https://raw.githubusercontent.com/ratatui-org/ratatui/aa09e59dc0058347f68d7c1e0c91f863c6f2b8c9/examples/demo2.gif)
-// this is a permalink to https://github.com/ratatui-org/ratatui/blob/images/examples/demo2.gif
+//! <div align="center">
 //!
-//! # Get started
+//! [![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>
 //!
-//! ## Adding `ratatui` as a dependency
+//! [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)
 //!
-//! Add the following to your `Cargo.toml`:
-//! ```toml
-//! [dependencies]
-//! crossterm = "0.27"
-//! ratatui = "0.23"
+//! </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.
+//!
+//! ## Installation
+//!
+//! Add `ratatui` and `crossterm` as dependencies to your cargo.toml:
+//!
+//! ```shell
+//! cargo add ratatui crossterm
 //! ```
 //!
-//! The crate is using the `crossterm` backend by default that works on most platforms. But if for
-//! example you want to use the `termion` backend instead. This can be done by changing your
-//! dependencies specification to the following:
+//! Ratatui uses [Crossterm] by default as it works on most platforms. See the [Installation]
+//! section of the [Ratatui Website] for more details on how to use other backends ([Termion] /
+//! [Termwiz]).
 //!
-//! ```toml
-//! [dependencies]
-//! termion = "2.0.1"
-//! ratatui = { version = "0.23", default-features = false, features = ['termion'] }
-//! ```
+//! ## Introduction
 //!
-//! The same logic applies for all other available backends.
+//! 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 Website]
+//! for more info.
 //!
-//! ## Creating a `Terminal`
+//! ## Other documentation
 //!
-//! Every application using `ratatui` should start by instantiating a `Terminal`. It is a light
-//! abstraction over available backends that provides basic functionalities such as clearing the
-//! screen, hiding the cursor, etc.
+//! - [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].
+//! - [Contributing] - Please read this if you are interested in contributing to the project.
+//! - [Breaking Changes] - a list of breaking changes in the library.
+//!
+//! ## Quickstart
+//!
+//! 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 Website] and the
+//! various [Examples]. There are also several starter templates available:
+//!
+//! - [template]
+//! - [async-template] (book and template)
+//!
+//! Every application built with `ratatui` needs to implement the following steps:
+//!
+//! - Initialize the terminal
+//! - A main loop to:
+//!   - Handle input events
+//!   - Draw the UI
+//! - Restore the terminal state
+//!
+//! The library contains a [`prelude`] module that re-exports the most commonly used traits and
+//! types for convenience. Most examples in the documentation will use this instead of showing the
+//! full path of each type.
+//!
+//! ### Initialize and restore the terminal
+//!
+//! The [`Terminal`] type is the main entry point for any Ratatui application. It is a light
+//! abstraction over a choice of [`Backend`] implementations that provides functionality to draw
+//! each frame, clear the screen, hide the cursor, etc. It is parametrized over any type that
+//! implements the [`Backend`] trait which has implementations for [Crossterm], [Termion] and
+//! [Termwiz].
+//!
+//! 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 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 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
+//! Website] for more info. For example, if you are using [Crossterm], you can use the
+//! [`crossterm::event`] module to handle events.
+//!
+//! ### Example
 //!
 //! ```rust,no_run
-//! use std::io;
-//! use ratatui::prelude::*;
-//!
-//! fn main() -> Result<(), io::Error> {
-//!     let stdout = io::stdout();
-//!     let backend = CrosstermBackend::new(stdout);
-//!     let mut terminal = Terminal::new(backend)?;
-//!     Ok(())
-//! }
-//! ```
-//!
-//! If you had previously chosen `termion` as a backend, the terminal can be created in a similar
-//! way:
-//!
-//! ```rust,ignore
-//! use std::io;
-//! use ratatui::prelude::*;
-//! use termion::raw::IntoRawMode;
-//!
-//! fn main() -> Result<(), io::Error> {
-//!     let stdout = io::stdout().into_raw_mode()?;
-//!     let backend = TermionBackend::new(stdout);
-//!     let mut terminal = Terminal::new(backend)?;
-//!     Ok(())
-//! }
-//! ```
-//!
-//! You may also refer to the examples to find out how to create a `Terminal` for each available
-//! backend.
-//!
-//! ## Building a User Interface (UI)
-//!
-//! Every component of your interface will be implementing the `Widget` trait. The library comes
-//! with a predefined set of widgets that should meet most of your use cases. You are also free to
-//! implement your own.
-//!
-//! Each widget follows a builder pattern API providing a default configuration along with methods
-//! to customize them. The widget is then rendered using [`Frame::render_widget`] which takes your
-//! widget instance and an area to draw to.
-//!
-//! The following example renders a block of the size of the terminal:
-//!
-//! ```rust,no_run
-//! use std::{io, thread, time::Duration};
-//! use ratatui::{prelude::*, widgets::*};
+//! use std::io::{self, stdout};
 //! use crossterm::{
-//!     event::{self, DisableMouseCapture, EnableMouseCapture},
-//!     execute,
-//!     terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+//!     event::{self, Event, KeyCode},
+//!     ExecutableCommand,
+//!     terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen}
 //! };
+//! use ratatui::{prelude::*, widgets::*};
 //!
-//! fn main() -> Result<(), io::Error> {
-//!     // setup terminal
+//! fn main() -> io::Result<()> {
 //!     enable_raw_mode()?;
-//!     let mut stdout = io::stdout();
-//!     execute!(stdout, EnterAlternateScreen, EnableMouseCapture)?;
-//!     let backend = CrosstermBackend::new(stdout);
-//!     let mut terminal = Terminal::new(backend)?;
+//!     stdout().execute(EnterAlternateScreen)?;
+//!     let mut terminal = Terminal::new(CrosstermBackend::new(stdout()))?;
 //!
-//!     terminal.draw(|f| {
-//!         let size = f.size();
-//!         let block = Block::default()
-//!             .title("Block")
-//!             .borders(Borders::ALL);
-//!         f.render_widget(block, size);
-//!     })?;
+//!     let mut should_quit = false;
+//!     while !should_quit {
+//!         terminal.draw(ui)?;
+//!         should_quit = handle_events()?;
+//!     }
 //!
-//!     // Start a thread to discard any input events. Without handling events, the
-//!     // stdin buffer will fill up, and be read into the shell when the program exits.
-//!     thread::spawn(|| loop {
-//!         event::read();
-//!     });
-//!
-//!     thread::sleep(Duration::from_millis(5000));
-//!
-//!     // restore terminal
 //!     disable_raw_mode()?;
-//!     execute!(
-//!         terminal.backend_mut(),
-//!         LeaveAlternateScreen,
-//!         DisableMouseCapture
-//!     )?;
-//!     terminal.show_cursor()?;
-//!
+//!     stdout().execute(LeaveAlternateScreen)?;
 //!     Ok(())
 //! }
+//!
+//! fn handle_events() -> io::Result<bool> {
+//!     if event::poll(std::time::Duration::from_millis(50))? {
+//!         if let Event::Key(key) = event::read()? {
+//!             if key.kind == event::KeyEventKind::Press && key.code == KeyCode::Char('q') {
+//!                 return Ok(true);
+//!             }
+//!        }
+//!     }
+//!     Ok(false)
+//! }
+//!
+//! fn ui(frame: &mut Frame) {
+//!     frame.render_widget(
+//!         Paragraph::new("Hello World!")
+//!             .block(Block::default().title("Greeting").borders(Borders::ALL)),
+//!         frame.size(),
+//!     );
+//! }
 //! ```
 //!
+//! Running this example produces the following output:
+//!
+//! ![docsrs-hello]
+//!
 //! ## Layout
 //!
-//! The library comes with a basic yet useful layout management object called `Layout`. As you may
-//! see below and in the examples, the library makes heavy use of the builder pattern to provide
-//! full customization. And `Layout` is no exception:
+//! 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 Website] for more info.
 //!
 //! ```rust,no_run
 //! use ratatui::{prelude::*, widgets::*};
 //!
-//! fn ui<B: Backend>(f: &mut Frame<B>) {
-//!    let chunks = Layout::default()
-//!         .direction(Direction::Vertical)
-//!         .margin(1)
-//!         .constraints(
-//!             [
-//!                 Constraint::Percentage(10),
-//!                 Constraint::Percentage(80),
-//!                 Constraint::Percentage(10)
-//!             ].as_ref()
-//!         )
-//!         .split(f.size());
-//!     let block = Block::default()
-//!          .title("Block")
-//!          .borders(Borders::ALL);
-//!     f.render_widget(block, chunks[0]);
-//!     let block = Block::default()
-//!          .title("Block 2")
-//!          .borders(Borders::ALL);
-//!     f.render_widget(block, chunks[1]);
+//! fn ui(frame: &mut Frame) {
+//!     let main_layout = Layout::new(
+//!         Direction::Vertical,
+//!         [
+//!             Constraint::Length(1),
+//!             Constraint::Min(0),
+//!             Constraint::Length(1),
+//!         ]
+//!     )
+//!     .split(frame.size());
+//!     frame.render_widget(
+//!         Block::new().borders(Borders::TOP).title("Title Bar"),
+//!         main_layout[0],
+//!     );
+//!     frame.render_widget(
+//!         Block::new().borders(Borders::TOP).title("Status Bar"),
+//!         main_layout[2],
+//!     );
+//!
+//!     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],
+//!     );
+//!     frame.render_widget(
+//!         Block::default().borders(Borders::ALL).title("Right"),
+//!         inner_layout[1],
+//!     );
 //! }
 //! ```
 //!
-//! This let you describe responsive terminal UI by nesting layouts. You should note that by default
-//! the computed layout tries to fill the available space completely. So if for any reason you might
-//! need a blank space somewhere, try to pass an additional constraint and don't use the
-//! corresponding area.
+//! Running this example produces the following output:
 //!
-//! # Features
+//! ![docsrs-layout]
+//!
+//! ## Text and styling
+//!
+//! The [`Text`], [`Line`] and [`Span`] types are the building blocks of the library and are used in
+//! many places. [`Text`] is a list of [`Line`]s and a [`Line`] is a list of [`Span`]s. A [`Span`]
+//! is a string with a specific style.
+//!
+//! The [`style` module] provides types that represent the various styling options. The most
+//! 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 Website] for more info.
+//!
+//! ```rust,no_run
+//! use ratatui::{prelude::*, widgets::*};
+//!
+//! fn ui(frame: &mut Frame) {
+//!     let areas = Layout::new(
+//!         Direction::Vertical,
+//!         [
+//!             Constraint::Length(1),
+//!             Constraint::Length(1),
+//!             Constraint::Length(1),
+//!             Constraint::Length(1),
+//!             Constraint::Min(0),
+//!         ]
+//!     )
+//!     .split(frame.size());
+//!
+//!     let span1 = Span::raw("Hello ");
+//!     let span2 = Span::styled(
+//!         "World",
+//!         Style::new()
+//!             .fg(Color::Green)
+//!             .bg(Color::White)
+//!             .add_modifier(Modifier::BOLD),
+//!     );
+//!     let span3 = "!".red().on_light_yellow().italic();
+//!
+//!     let line = Line::from(vec![span1, span2, span3]);
+//!     let text: Text = Text::from(vec![line]);
+//!
+//!     frame.render_widget(Paragraph::new(text), areas[0]);
+//!     // or using the short-hand syntax and implicit conversions
+//!     frame.render_widget(
+//!         Paragraph::new("Hello World!".red().on_white().bold()),
+//!         areas[1],
+//!     );
+//!
+//!     // to style the whole widget instead of just the text
+//!     frame.render_widget(
+//!         Paragraph::new("Hello World!").style(Style::new().red().on_white()),
+//!         areas[2],
+//!     );
+//!     // or using the short-hand syntax
+//!     frame.render_widget(Paragraph::new("Hello World!").blue().on_yellow(), areas[3]);
+//! }
+//! ```
+//!
+//! Running this example produces the following output:
+//!
+//! ![docsrs-styling]
+#![cfg_attr(feature = "document-features", doc = "\n## Features")]
 #![cfg_attr(feature = "document-features", doc = document_features::document_features!())]
+#![cfg_attr(
+    feature = "document-features",
+    doc = "[`CrossTermBackend`]: backend::CrosstermBackend"
+)]
+#![cfg_attr(
+    feature = "document-features",
+    doc = "[`TermionBackend`]: backend::TermionBackend"
+)]
+#![cfg_attr(
+    feature = "document-features",
+    doc = "[`TermwizBackend`]: backend::TermwizBackend"
+)]
+#![cfg_attr(
+    feature = "document-features",
+    doc = "[`calendar`]: widgets::calendar::Monthly"
+)]
 //!
+//! [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://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
+//! [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
+//! [`Frame`]: terminal::Frame
+//! [`render_widget`]: terminal::Frame::render_widget
+//! [`Widget`]: widgets::Widget
 //! [`Layout`]: layout::Layout
-//! [`backend`]: backend
-//! [`calendar`]: widgets::calendar
-//! [`CrosstermBackend`]: backend::CrosstermBackend
-//! [`TermionBackend`]: backend::TermionBackend
-//! [`TermwizBackend`]: backend::TermwizBackend
-//! [Crossterm crate]: https://crates.io/crates/crossterm
-//! [Serde crate]: https://crates.io/crates/serde
-//! [Termion crate]: https://crates.io/crates/termion
-//! [Termwiz crate]: https://crates.io/crates/termwiz
-//! [Time crate]: https://crates.io/crates/time
+//! [`Text`]: text::Text
+//! [`Line`]: text::Line
+//! [`Span`]: text::Span
+//! [`Style`]: style::Style
+//! [`style` module]: style
+//! [`Stylize`]: style::Stylize
+//! [`Backend`]: backend::Backend
+//! [`backend` module]: backend
+//! [`crossterm::event`]: https://docs.rs/crossterm/latest/crossterm/event/index.html
+//! [Ratatui]: https://ratatui.rs
+//! [Crossterm]: https://crates.io/crates/crossterm
+//! [Termion]: https://crates.io/crates/termion
+//! [Termwiz]: https://crates.io/crates/termwiz
+//! [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]:
+//!     https://img.shields.io/github/actions/workflow/status/ratatui-org/ratatui/ci.yml?style=flat-square&logo=github
+//! [Codecov Badge]:
+//!     https://img.shields.io/codecov/c/github/ratatui-org/ratatui?logo=codecov&style=flat-square&token=BAQ8SOKEST
+//! [Dependencies Badge]: https://deps.rs/repo/github/ratatui-org/ratatui/status.svg?style=flat-square
+//! [Discord Badge]:
+//!     https://img.shields.io/discord/1070692720437383208?label=discord&logo=discord&style=flat-square
+//! [Docs Badge]: https://img.shields.io/docsrs/ratatui?logo=rust&style=flat-square
+//! [License Badge]: https://img.shields.io/crates/l/ratatui?style=flat-square
+//! [Matrix Badge]:
+//!     https://img.shields.io/matrix/ratatui-general%3Amatrix.org?style=flat-square&logo=matrix&label=Matrix
 
 // show the feature flags in the generated documentation
 #![cfg_attr(docsrs, feature(doc_auto_cfg))]

src/style.rs

@@ -140,7 +140,7 @@ impl fmt::Debug for Modifier {
 /// let styles = [
 ///     Style::default().fg(Color::Blue).add_modifier(Modifier::BOLD | Modifier::ITALIC),
 ///     Style::default().bg(Color::Red).add_modifier(Modifier::UNDERLINED),
-///     #[cfg(feature = "crossterm")]
+///     #[cfg(feature = "underline-color")]
 ///     Style::default().underline_color(Color::Green),
 ///     Style::default().fg(Color::Yellow).remove_modifier(Modifier::ITALIC),
 /// ];
@@ -152,7 +152,7 @@ impl fmt::Debug for Modifier {
 ///     Style {
 ///         fg: Some(Color::Yellow),
 ///         bg: Some(Color::Red),
-///         #[cfg(feature = "crossterm")]
+///         #[cfg(feature = "underline-color")]
 ///         underline_color: Some(Color::Green),
 ///         add_modifier: Modifier::BOLD | Modifier::UNDERLINED,
 ///         sub_modifier: Modifier::empty(),
@@ -179,7 +179,7 @@ impl fmt::Debug for Modifier {
 ///     Style {
 ///         fg: Some(Color::Yellow),
 ///         bg: Some(Color::Reset),
-///         #[cfg(feature = "crossterm")]
+///         #[cfg(feature = "underline-color")]
 ///         underline_color: Some(Color::Reset),
 ///         add_modifier: Modifier::empty(),
 ///         sub_modifier: Modifier::empty(),
@@ -192,7 +192,7 @@ impl fmt::Debug for Modifier {
 pub struct Style {
     pub fg: Option<Color>,
     pub bg: Option<Color>,
-    #[cfg(feature = "crossterm")]
+    #[cfg(feature = "underline-color")]
     pub underline_color: Option<Color>,
     pub add_modifier: Modifier,
     pub sub_modifier: Modifier,
@@ -220,7 +220,7 @@ impl Style {
         Style {
             fg: None,
             bg: None,
-            #[cfg(feature = "crossterm")]
+            #[cfg(feature = "underline-color")]
             underline_color: None,
             add_modifier: Modifier::empty(),
             sub_modifier: Modifier::empty(),
@@ -232,7 +232,7 @@ impl Style {
         Style {
             fg: Some(Color::Reset),
             bg: Some(Color::Reset),
-            #[cfg(feature = "crossterm")]
+            #[cfg(feature = "underline-color")]
             underline_color: Some(Color::Reset),
             add_modifier: Modifier::empty(),
             sub_modifier: Modifier::all(),
@@ -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
@@ -272,9 +274,12 @@ impl Style {
     /// Changes the underline color. The text must be underlined with a modifier for this to work.
     ///
     /// This uses a non-standard ANSI escape sequence. It is supported by most terminal emulators,
-    /// but is only implemented in the crossterm backend.
+    /// but is only implemented in the crossterm backend and enabled by the `underline-color`
+    /// feature flag.
     ///
-    /// See [Wikipedia](https://en.wikipedia.org/wiki/ANSI_escape_code#SGR_(Select_Graphic_Rendition)_parameters) code `58` and `59` for more information.
+    /// See
+    /// [Wikipedia](https://en.wikipedia.org/wiki/ANSI_escape_code#SGR_(Select_Graphic_Rendition)_parameters)
+    /// code `58` and `59` for more information.
     ///
     /// ## Examples
     ///
@@ -284,7 +289,8 @@ impl Style {
     /// let diff = Style::default().underline_color(Color::Red).add_modifier(Modifier::UNDERLINED);
     /// assert_eq!(style.patch(diff), Style::default().underline_color(Color::Red).add_modifier(Modifier::UNDERLINED));
     /// ```
-    #[cfg(feature = "crossterm")]
+    #[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
@@ -304,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);
@@ -324,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);
@@ -343,11 +351,12 @@ 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);
 
-        #[cfg(feature = "crossterm")]
+        #[cfg(feature = "underline-color")]
         {
             self.underline_color = other.underline_color.or(self.underline_color);
         }

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/symbols.rs

@@ -54,6 +54,12 @@ pub mod block {
     };
 }
 
+pub mod half_block {
+    pub const UPPER: char = '▀';
+    pub const LOWER: char = '▄';
+    pub const FULL: char = '█';
+}
+
 pub mod bar {
     pub const FULL: &str = "█";
     pub const SEVEN_EIGHTHS: &str = "▇";
@@ -157,7 +163,7 @@ pub mod line {
     pub const DOUBLE_CROSS: &str = "╬";
     pub const THICK_CROSS: &str = "╋";
 
-    #[derive(Debug, Clone, Eq, PartialEq, Hash)]
+    #[derive(Debug, Clone, Copy, Eq, PartialEq, Hash)]
     pub struct Set {
         pub vertical: &'static str,
         pub horizontal: &'static str,
@@ -229,6 +235,154 @@ pub mod line {
     };
 }
 
+pub mod border {
+    use super::line;
+
+    #[derive(Debug, Clone, Copy, Eq, PartialEq, Hash)]
+    pub struct Set {
+        pub top_left: &'static str,
+        pub top_right: &'static str,
+        pub bottom_left: &'static str,
+        pub bottom_right: &'static str,
+        pub vertical_left: &'static str,
+        pub vertical_right: &'static str,
+        pub horizontal_top: &'static str,
+        pub horizontal_bottom: &'static str,
+    }
+
+    impl Default for Set {
+        fn default() -> Self {
+            PLAIN
+        }
+    }
+
+    /// Border Set with a single line width
+    ///
+    /// ```text
+    /// ┌─────┐
+    /// │xxxxx│
+    /// │xxxxx│
+    /// └─────┘
+    pub const PLAIN: Set = Set {
+        top_left: line::NORMAL.top_left,
+        top_right: line::NORMAL.top_right,
+        bottom_left: line::NORMAL.bottom_left,
+        bottom_right: line::NORMAL.bottom_right,
+        vertical_left: line::NORMAL.vertical,
+        vertical_right: line::NORMAL.vertical,
+        horizontal_top: line::NORMAL.horizontal,
+        horizontal_bottom: line::NORMAL.horizontal,
+    };
+
+    /// Border Set with a single line width and rounded corners
+    ///
+    /// ```text
+    /// ╭─────╮
+    /// │xxxxx│
+    /// │xxxxx│
+    /// ╰─────╯
+    pub const ROUNDED: Set = Set {
+        top_left: line::ROUNDED.top_left,
+        top_right: line::ROUNDED.top_right,
+        bottom_left: line::ROUNDED.bottom_left,
+        bottom_right: line::ROUNDED.bottom_right,
+        vertical_left: line::ROUNDED.vertical,
+        vertical_right: line::ROUNDED.vertical,
+        horizontal_top: line::ROUNDED.horizontal,
+        horizontal_bottom: line::ROUNDED.horizontal,
+    };
+
+    /// Border Set with a double line width
+    ///
+    /// ```text
+    /// ╔═════╗
+    /// ║xxxxx║
+    /// ║xxxxx║
+    /// ╚═════╝
+    pub const DOUBLE: Set = Set {
+        top_left: line::DOUBLE.top_left,
+        top_right: line::DOUBLE.top_right,
+        bottom_left: line::DOUBLE.bottom_left,
+        bottom_right: line::DOUBLE.bottom_right,
+        vertical_left: line::DOUBLE.vertical,
+        vertical_right: line::DOUBLE.vertical,
+        horizontal_top: line::DOUBLE.horizontal,
+        horizontal_bottom: line::DOUBLE.horizontal,
+    };
+
+    /// Border Set with a thick line width
+    ///
+    /// ```text
+    /// ┏━━━━━┓
+    /// ┃xxxxx┃
+    /// ┃xxxxx┃
+    /// ┗━━━━━┛
+    pub const THICK: Set = Set {
+        top_left: line::THICK.top_left,
+        top_right: line::THICK.top_right,
+        bottom_left: line::THICK.bottom_left,
+        bottom_right: line::THICK.bottom_right,
+        vertical_left: line::THICK.vertical,
+        vertical_right: line::THICK.vertical,
+        horizontal_top: line::THICK.horizontal,
+        horizontal_bottom: line::THICK.horizontal,
+    };
+
+    pub const QUADRANT_TOP_LEFT: &str = "▘";
+    pub const QUADRANT_TOP_RIGHT: &str = "▝";
+    pub const QUADRANT_BOTTOM_LEFT: &str = "▖";
+    pub const QUADRANT_BOTTOM_RIGHT: &str = "▗";
+    pub const QUADRANT_TOP_HALF: &str = "▀";
+    pub const QUADRANT_BOTTOM_HALF: &str = "▄";
+    pub const QUADRANT_LEFT_HALF: &str = "▌";
+    pub const QUADRANT_RIGHT_HALF: &str = "▐";
+    pub const QUADRANT_TOP_LEFT_BOTTOM_LEFT_BOTTOM_RIGHT: &str = "▙";
+    pub const QUADRANT_TOP_LEFT_TOP_RIGHT_BOTTOM_LEFT: &str = "▛";
+    pub const QUADRANT_TOP_LEFT_TOP_RIGHT_BOTTOM_RIGHT: &str = "▜";
+    pub const QUADRANT_TOP_RIGHT_BOTTOM_LEFT_BOTTOM_RIGHT: &str = "▟";
+    pub const QUADRANT_TOP_LEFT_BOTTOM_RIGHT: &str = "▚";
+    pub const QUADRANT_TOP_RIGHT_BOTTOM_LEFT: &str = "▞";
+    pub const QUADRANT_BLOCK: &str = "█";
+
+    /// Quadrant used for setting a border outside a block by one half cell "pixel".
+    ///
+    /// ```text
+    /// ▛▀▀▀▀▀▜
+    /// ▌xxxxx▐
+    /// ▌xxxxx▐
+    /// ▙▄▄▄▄▄▟
+    /// ```
+    pub const QUADRANT_OUTSIDE: Set = Set {
+        top_left: QUADRANT_TOP_LEFT_TOP_RIGHT_BOTTOM_LEFT,
+        top_right: QUADRANT_TOP_LEFT_TOP_RIGHT_BOTTOM_RIGHT,
+        bottom_left: QUADRANT_TOP_LEFT_BOTTOM_LEFT_BOTTOM_RIGHT,
+        bottom_right: QUADRANT_TOP_RIGHT_BOTTOM_LEFT_BOTTOM_RIGHT,
+        vertical_left: QUADRANT_LEFT_HALF,
+        vertical_right: QUADRANT_RIGHT_HALF,
+        horizontal_top: QUADRANT_TOP_HALF,
+        horizontal_bottom: QUADRANT_BOTTOM_HALF,
+    };
+
+    /// Quadrant used for setting a border inside a block by one half cell "pixel".
+    ///
+    /// ```text
+    /// ▗▄▄▄▄▄▖
+    /// ▐xxxxx▌
+    /// ▐xxxxx▌
+    /// ▝▀▀▀▀▀▘
+    /// ```
+    pub const QUADRANT_INSIDE: Set = Set {
+        top_right: QUADRANT_BOTTOM_LEFT,
+        top_left: QUADRANT_BOTTOM_RIGHT,
+        bottom_right: QUADRANT_TOP_LEFT,
+        bottom_left: QUADRANT_TOP_RIGHT,
+        vertical_left: QUADRANT_RIGHT_HALF,
+        vertical_right: QUADRANT_LEFT_HALF,
+        horizontal_top: QUADRANT_BOTTOM_HALF,
+        horizontal_bottom: QUADRANT_TOP_HALF,
+    };
+}
+
 pub const DOT: &str = "•";
 
 pub mod braille {
@@ -260,6 +414,10 @@ pub enum Marker {
     /// Braille Patterns. If your terminal does not support this, you will see unicode replacement
     /// characters (<28>) instead of Braille dots.
     Braille,
+    /// Use the unicode block and half block characters ("█", "▄", and "▀") to represent points in
+    /// a grid that is double the resolution of the terminal. Because each terminal cell is
+    /// generally about twice as tall as it is wide, this allows for a square grid of pixels.
+    HalfBlock,
 }
 
 pub mod scrollbar {

src/terminal.rs

@@ -81,7 +81,7 @@ pub struct TerminalOptions {
     pub viewport: Viewport,
 }
 
-/// An interface that Ratatui to interact and draw [`Frame`]s on the user's terminal.
+/// An interface to interact and draw [`Frame`]s on the user's terminal.
 ///
 /// This is the main entry point for Ratatui. It is responsible for drawing and maintaining the
 /// state of the buffers, cursor and viewport.
@@ -91,9 +91,11 @@ pub struct TerminalOptions {
 /// terminal libraries: [Crossterm], [Termion] and [Termwiz]. See the [`backend`] module for more
 /// information.
 ///
-/// The terminal has two buffers that are used to draw the application. The first buffer is the
-/// current buffer and the second buffer is the previous buffer. The two buffers are compared at
-/// the end of each draw pass to output only the changes to the terminal.
+/// The `Terminal` struct maintains two buffers: the current and the previous.
+/// When the widgets are drawn, the changes are accumulated in the current buffer.
+/// At the end of each draw pass, the two buffers are compared, and only the changes
+/// between these buffers are written to the terminal, avoiding any redundant operations.
+/// After flushing these changes, the buffers are swapped to prepare for the next draw cycle./
 ///
 /// The terminal also has a viewport which is the area of the terminal that is currently visible to
 /// the user. It can be either fullscreen, inline or fixed. See [`Viewport`] for more information.
@@ -225,10 +227,11 @@ where
     }
 
     /// Get a Frame object which provides a consistent view into the terminal state for rendering.
-    pub fn get_frame(&mut self) -> Frame<B> {
+    pub fn get_frame(&mut self) -> Frame {
         Frame {
-            terminal: self,
             cursor_position: None,
+            viewport_area: self.viewport_area,
+            buffer: self.current_buffer_mut(),
         }
     }
 
@@ -321,7 +324,7 @@ where
     /// ```
     pub fn draw<F>(&mut self, f: F) -> io::Result<CompletedFrame>
     where
-        F: FnOnce(&mut Frame<B>),
+        F: FnOnce(&mut Frame),
     {
         // Autoresize - otherwise we get glitches if shrinking or potential desync between widgets
         // and the terminal (if growing), which may OOB.
@@ -331,7 +334,7 @@ where
         f(&mut frame);
         // We can't change the cursor position right away because we have to flush the frame to
         // stdout first. But we also can't keep the frame around, since it holds a &mut to
-        // Terminal. Thus, we're taking the important data out of the Frame and dropping it.
+        // Buffer. Thus, we're taking the important data out of the Frame and dropping it.
         let cursor_position = frame.cursor_position;
 
         // Draw to stdout
@@ -468,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(())
     }
@@ -545,46 +560,31 @@ fn compute_inline_size<B: Backend>(
 /// This is obtained via the closure argument of [`Terminal::draw`]. It is used to render widgets
 /// to the terminal and control the cursor position.
 ///
-/// The changes drawn to the frame are not immediately applied to the terminal. They are only
-/// applied after the closure returns. This allows for widgets to be drawn in any order. The
-/// changes are then compared to the previous frame and only the necessary updates are applied to
-/// the terminal.
+/// The changes drawn to the frame are applied only to the current [`Buffer`].
+/// After the closure returns, the current buffer is compared to the previous
+/// buffer and only the changes are applied to the terminal.
 ///
-/// The [`Frame`] is generic over a [`Backend`] implementation which is used to interface with the
-/// underlying terminal library. The [`Backend`] trait is implemented for three popular Rust
-/// terminal libraries: [Crossterm], [Termion] and [Termwiz]. See the [`backend`] module for more
-/// information.
-///
-/// [Crossterm]: https://crates.io/crates/crossterm
-/// [Termion]: https://crates.io/crates/termion
-/// [Termwiz]: https://crates.io/crates/termwiz
-/// [`backend`]: crate::backend
-/// [`Backend`]: crate::backend::Backend
 /// [`Buffer`]: crate::buffer::Buffer
 #[derive(Debug, Hash)]
-pub struct Frame<'a, B: 'a>
-where
-    B: Backend,
-{
-    /// The terminal that this frame is associated with.
-    terminal: &'a mut Terminal<B>,
-
+pub struct Frame<'a> {
     /// Where should the cursor be after drawing this frame?
     ///
     /// If `None`, the cursor is hidden and its position is controlled by the backend. If `Some((x,
     /// y))`, the cursor is shown and placed at `(x, y)` after the call to `Terminal::draw()`.
     cursor_position: Option<(u16, u16)>,
+    /// The area of the viewport
+    viewport_area: Rect,
+
+    /// The buffer that is used to draw the current frame
+    buffer: &'a mut Buffer,
 }
 
-impl<'a, B> Frame<'a, B>
-where
-    B: Backend,
-{
+impl Frame<'_> {
     /// The size of the current frame
     ///
     /// This is guaranteed not to change when rendering.
     pub fn size(&self) -> Rect {
-        self.terminal.viewport_area
+        self.viewport_area
     }
 
     /// Render a [`Widget`] to the current buffer using [`Widget::render`].
@@ -609,7 +609,7 @@ where
     where
         W: Widget,
     {
-        widget.render(area, self.terminal.current_buffer_mut());
+        widget.render(area, self.buffer);
     }
 
     /// Render a [`StatefulWidget`] to the current buffer using [`StatefulWidget::render`].
@@ -641,7 +641,7 @@ where
     where
         W: StatefulWidget,
     {
-        widget.render(area, self.terminal.current_buffer_mut(), state);
+        widget.render(area, self.buffer, state);
     }
 
     /// After drawing this frame, make the cursor visible and put it at the specified (x, y)
@@ -653,6 +653,11 @@ where
     pub fn set_cursor(&mut self, x: u16, y: u16) {
         self.cursor_position = Some((x, y));
     }
+
+    /// Gets the buffer that this `Frame` draws into as a mutable reference.
+    pub fn buffer_mut(&mut self) -> &mut Buffer {
+        self.buffer
+    }
 }
 
 /// `CompletedFrame` represents the state of the terminal after all changes performed in the last

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,52 +287,96 @@ 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
     }
 }
 
-impl<'a> BarChart<'a> {
-    /// Check the bars, which fits inside the available space and removes
-    /// the bars and the groups, which are outside of the available space.
-    fn remove_invisible_groups_and_bars(&mut self, mut width: u16) {
-        for group_index in 0..self.data.len() {
-            let n_bars = self.data[group_index].bars.len() as u16;
-            let group_width = n_bars * self.bar_width + n_bars.saturating_sub(1) * self.bar_gap;
+struct LabelInfo {
+    group_label_visible: bool,
+    bar_label_visible: bool,
+    height: u16,
+}
 
-            if width > group_width {
-                width = width.saturating_sub(group_width + self.group_gap + self.bar_gap);
-            } else {
-                let max_bars = (width + self.bar_gap) / (self.bar_width + self.bar_gap);
-                if max_bars == 0 {
-                    self.data.truncate(group_index);
-                } else {
-                    self.data[group_index].bars.truncate(max_bars as usize);
-                    self.data.truncate(group_index + 1);
+impl<'a> BarChart<'a> {
+    /// Returns the visible bars length in ticks. A cell contains 8 ticks.
+    /// `available_space` used to calculate how many bars can fit in the space
+    /// `bar_max_length` is the maximal length a bar can take.
+    fn group_ticks(&self, available_space: u16, bar_max_length: u16) -> Vec<Vec<u64>> {
+        let max: u64 = self.maximum_data_value();
+        self.data
+            .iter()
+            .scan(available_space, |space, group| {
+                if *space == 0 {
+                    return None;
                 }
-                break;
-            }
-        }
+                let n_bars = group.bars.len() as u16;
+                let group_width = n_bars * self.bar_width + n_bars.saturating_sub(1) * self.bar_gap;
+
+                let n_bars = if *space > group_width {
+                    *space = space.saturating_sub(group_width + self.group_gap + self.bar_gap);
+                    Some(n_bars)
+                } else {
+                    let max_bars = (*space + self.bar_gap) / (self.bar_width + self.bar_gap);
+                    if max_bars > 0 {
+                        *space = 0;
+                        Some(max_bars)
+                    } else {
+                        None
+                    }
+                };
+
+                n_bars.map(|n| {
+                    group
+                        .bars
+                        .iter()
+                        .take(n as usize)
+                        .map(|bar| bar.value * u64::from(bar_max_length) * 8 / max)
+                        .collect()
+                })
+            })
+            .collect()
     }
 
-    /// Get the number of lines needed for the labels.
+    /// Get label information.
     ///
-    /// The number of lines depends on whether we need to print the bar labels and/or the group
-    /// labels.
-    /// - If there are no labels, return 0.
-    /// - If there are only bar labels, return 1.
-    /// - If there are only group labels, return 1.
-    /// - If there are both bar and group labels, return 2.
-    fn label_height(&self) -> u16 {
-        let has_group_labels = self.data.iter().any(|e| e.label.is_some());
-        let has_data_labels = self
+    /// height is the number of lines, which depends on whether we need to print the bar
+    /// labels and/or the group labels.
+    /// - If there are no labels, height is 0.
+    /// - If there are only bar labels, height is 1.
+    /// - If there are only group labels, height is 1.
+    /// - If there are both bar and group labels, height is 2.
+    fn label_info(&self, available_height: u16) -> LabelInfo {
+        if available_height == 0 {
+            return LabelInfo {
+                group_label_visible: false,
+                bar_label_visible: false,
+                height: 0,
+            };
+        }
+
+        let bar_label_visible = self
             .data
             .iter()
             .any(|e| e.bars.iter().any(|e| e.label.is_some()));
 
-        // convert true to 1 and false to 0 and add the two values
-        u16::from(has_group_labels) + u16::from(has_data_labels)
+        if available_height == 1 && bar_label_visible {
+            return LabelInfo {
+                group_label_visible: false,
+                bar_label_visible: true,
+                height: 1,
+            };
+        }
+
+        let group_label_visible = self.data.iter().any(|e| e.label.is_some());
+        LabelInfo {
+            group_label_visible,
+            bar_label_visible,
+            // convert true to 1 and false to 0 and add the two values
+            height: u16::from(group_label_visible) + u16::from(bar_label_visible),
+        }
     }
 
     /// renders the block if there is one and updates the area to the inner area
@@ -334,7 +388,7 @@ impl<'a> BarChart<'a> {
         }
     }
 
-    fn render_horizontal_bars(self, buf: &mut Buffer, bars_area: Rect, max: u64) {
+    fn render_horizontal(self, buf: &mut Buffer, area: Rect) {
         // get the longest label
         let label_size = self
             .data
@@ -345,35 +399,25 @@ impl<'a> BarChart<'a> {
             .max()
             .unwrap_or(0) as u16;
 
-        let label_x = bars_area.x;
+        let label_x = area.x;
         let bars_area = {
             let margin = if label_size == 0 { 0 } else { 1 };
             Rect {
-                x: bars_area.x + label_size + margin,
-                width: bars_area.width - label_size - margin,
-                ..bars_area
+                x: area.x + label_size + margin,
+                width: area.width - label_size - margin,
+                ..area
             }
         };
 
-        // convert the bar values to ratatui::symbols::bar::Set
-        let groups: Vec<Vec<u16>> = self
-            .data
-            .iter()
-            .map(|group| {
-                group
-                    .bars
-                    .iter()
-                    .map(|bar| (bar.value * u64::from(bars_area.width) / max) as u16)
-                    .collect()
-            })
-            .collect();
+        let group_ticks = self.group_ticks(bars_area.height, bars_area.width);
 
         // print all visible bars, label and values
         let mut bar_y = bars_area.top();
-        for (group_data, mut group) in groups.into_iter().zip(self.data) {
+        for (ticks_vec, mut group) in group_ticks.into_iter().zip(self.data) {
             let bars = std::mem::take(&mut group.bars);
 
-            for (bar_length, bar) in group_data.into_iter().zip(bars) {
+            for (ticks, bar) in ticks_vec.into_iter().zip(bars) {
+                let bar_length = (ticks / 8) as u16;
                 let bar_style = self.bar_style.patch(bar.style);
 
                 for y in 0..self.bar_width {
@@ -425,26 +469,27 @@ impl<'a> BarChart<'a> {
         }
     }
 
-    fn render_vertical_bars(&self, buf: &mut Buffer, bars_area: Rect, max: u64) {
-        // convert the bar values to ratatui::symbols::bar::Set
-        let mut groups: Vec<Vec<u64>> = self
-            .data
-            .iter()
-            .map(|group| {
-                group
-                    .bars
-                    .iter()
-                    .map(|bar| bar.value * u64::from(bars_area.height) * 8 / max)
-                    .collect()
-            })
-            .collect();
+    fn render_vertical(self, buf: &mut Buffer, area: Rect) {
+        let label_info = self.label_info(area.height - 1);
 
+        let bars_area = Rect {
+            height: area.height - label_info.height,
+            ..area
+        };
+
+        let group_ticks = self.group_ticks(bars_area.width, bars_area.height);
+        self.render_vertical_bars(bars_area, buf, &group_ticks);
+        self.render_labels_and_values(area, buf, label_info, &group_ticks);
+    }
+
+    fn render_vertical_bars(&self, area: Rect, buf: &mut Buffer, group_ticks: &[Vec<u64>]) {
         // print all visible bars (without labels and values)
-        for j in (0..bars_area.height).rev() {
-            let mut bar_x = bars_area.left();
-            for (group_data, group) in groups.iter_mut().zip(&self.data) {
-                for (d, bar) in group_data.iter_mut().zip(&group.bars) {
-                    let symbol = match d {
+        let mut bar_x = area.left();
+        for (ticks_vec, group) in group_ticks.iter().zip(&self.data) {
+            for (ticks, bar) in ticks_vec.iter().zip(&group.bars) {
+                let mut ticks = *ticks;
+                for j in (0..area.height).rev() {
+                    let symbol = match ticks {
                         0 => self.bar_set.empty,
                         1 => self.bar_set.one_eighth,
                         2 => self.bar_set.one_quarter,
@@ -459,20 +504,16 @@ impl<'a> BarChart<'a> {
                     let bar_style = self.bar_style.patch(bar.style);
 
                     for x in 0..self.bar_width {
-                        buf.get_mut(bar_x + x, bars_area.top() + j)
+                        buf.get_mut(bar_x + x, area.top() + j)
                             .set_symbol(symbol)
                             .set_style(bar_style);
                     }
 
-                    if *d > 8 {
-                        *d -= 8;
-                    } else {
-                        *d = 0;
-                    }
-                    bar_x += self.bar_gap + self.bar_width;
+                    ticks = ticks.saturating_sub(8);
                 }
-                bar_x += self.group_gap;
+                bar_x += self.bar_gap + self.bar_width;
             }
+            bar_x += self.group_gap;
         }
     }
 
@@ -489,36 +530,42 @@ impl<'a> BarChart<'a> {
             .max(1u64)
     }
 
-    fn render_labels_and_values(self, area: Rect, buf: &mut Buffer, label_height: u16) {
+    fn render_labels_and_values(
+        self,
+        area: Rect,
+        buf: &mut Buffer,
+        label_info: LabelInfo,
+        group_ticks: &[Vec<u64>],
+    ) {
         // print labels and values in one go
         let mut bar_x = area.left();
-        let bar_y = area.bottom() - label_height - 1;
-        for mut group in self.data.into_iter() {
+        let bar_y = area.bottom() - label_info.height - 1;
+        for (mut group, ticks_vec) in self.data.into_iter().zip(group_ticks) {
             if group.bars.is_empty() {
                 continue;
             }
             let bars = std::mem::take(&mut group.bars);
+
             // print group labels under the bars or the previous labels
-            let label_max_width =
-                bars.len() as u16 * (self.bar_width + self.bar_gap) - self.bar_gap;
-            let group_area = Rect {
-                x: bar_x,
-                y: area.bottom() - 1,
-                width: label_max_width,
-                height: 1,
-            };
-            group.render_label(buf, group_area, self.label_style);
+            if label_info.group_label_visible {
+                let label_max_width =
+                    ticks_vec.len() as u16 * (self.bar_width + self.bar_gap) - self.bar_gap;
+                let group_area = Rect {
+                    x: bar_x,
+                    y: area.bottom() - 1,
+                    width: label_max_width,
+                    height: 1,
+                };
+                group.render_label(buf, group_area, self.label_style);
+            }
 
             // print the bar values and numbers
-            for bar in bars.into_iter() {
-                bar.render_label_and_value(
-                    buf,
-                    self.bar_width,
-                    bar_x,
-                    bar_y,
-                    self.value_style,
-                    self.label_style,
-                );
+            for (mut bar, ticks) in bars.into_iter().zip(ticks_vec) {
+                if label_info.bar_label_visible {
+                    bar.render_label(buf, self.bar_width, bar_x, bar_y + 1, self.label_style);
+                }
+
+                bar.render_value(buf, self.bar_width, bar_x, bar_y, self.value_style, *ticks);
 
                 bar_x += self.bar_gap + self.bar_width;
             }
@@ -532,39 +579,14 @@ impl<'a> Widget for BarChart<'a> {
         buf.set_style(area, self.style);
 
         self.render_block(&mut area, buf);
-        if area.area() == 0 {
-            return;
-        }
-        if self.data.is_empty() {
-            return;
-        }
-        if self.bar_width == 0 {
-            return;
-        }
 
-        let label_height = self.label_height();
-        if area.height <= label_height {
+        if area.is_empty() || self.data.is_empty() || self.bar_width == 0 {
             return;
         }
 
-        let max = self.maximum_data_value();
-
         match self.direction {
-            Direction::Horizontal => {
-                // remove invisible groups and bars, since we don't need to print them
-                self.remove_invisible_groups_and_bars(area.height);
-                self.render_horizontal_bars(buf, area, max);
-            }
-            Direction::Vertical => {
-                // remove invisible groups and bars, since we don't need to print them
-                self.remove_invisible_groups_and_bars(area.width);
-                let bars_area = Rect {
-                    height: area.height - label_height,
-                    ..area
-                };
-                self.render_vertical_bars(buf, bars_area, max);
-                self.render_labels_and_values(area, buf, label_height);
-            }
+            Direction::Horizontal => self.render_horizontal(buf, area),
+            Direction::Vertical => self.render_vertical(buf, area),
         }
     }
 }
@@ -607,7 +629,7 @@ mod tests {
             buffer,
             Buffer::with_lines(vec![
                 "  █            ",
-                "█ █            ",
+                "1 2            ",
                 "f b            ",
             ])
         );
@@ -629,7 +651,7 @@ mod tests {
             Buffer::with_lines(vec![
                 "╔Block════════╗",
                 "║  █          ║",
-                "║█ █          ║",
+                "║1 2          ║",
                 "║f b          ║",
                 "╚═════════════╝",
             ])
@@ -657,7 +679,7 @@ mod tests {
             buffer,
             Buffer::with_lines(vec![
                 "  █ █          ",
-                "█ █ █          ",
+                "1 2 █          ",
                 "f b b          ",
             ])
         );
@@ -672,7 +694,7 @@ mod tests {
         widget.render(buffer.area, &mut buffer);
         let mut expected = Buffer::with_lines(vec![
             "  █            ",
-            "█ █            ",
+            "1 2            ",
             "f b            ",
         ]);
         for (x, y) in iproduct!([0, 2], [0, 1]) {
@@ -709,7 +731,7 @@ mod tests {
             buffer,
             Buffer::with_lines(vec![
                 "   █           ",
-                "█  █           ",
+                "1  2           ",
                 "f  b           ",
             ])
         );
@@ -726,7 +748,7 @@ mod tests {
             buffer,
             Buffer::with_lines(vec![
                 "    █          ",
-                "  ▄ █          ",
+                "  ▄ 3          ",
                 "f b b          ",
             ])
         );
@@ -753,7 +775,7 @@ mod tests {
             buffer,
             Buffer::with_lines(vec![
                 "                  ",
-                "  ▁ ▂ ▃ ▄ ▅ ▆ ▇ █ ",
+                "  ▁ ▂ ▃ ▄ ▅ ▆ ▇ 8 ",
                 "a b c d e f g h i ",
             ])
         );
@@ -786,7 +808,7 @@ mod tests {
         widget.render(buffer.area, &mut buffer);
         let mut expected = Buffer::with_lines(vec![
             "  █            ",
-            "█ █            ",
+            "1 2            ",
             "f b            ",
         ]);
         expected.get_mut(0, 2).set_fg(Color::Red);
@@ -803,7 +825,7 @@ mod tests {
         widget.render(buffer.area, &mut buffer);
         let mut expected = Buffer::with_lines(vec![
             "  █            ",
-            "█ █            ",
+            "1 2            ",
             "f b            ",
         ]);
         for (x, y) in iproduct!(0..15, 0..3) {
@@ -812,166 +834,6 @@ mod tests {
         assert_buffer_eq!(buffer, expected);
     }
 
-    #[test]
-    fn does_not_render_less_than_two_rows() {
-        let mut buffer = Buffer::empty(Rect::new(0, 0, 15, 1));
-        let widget = BarChart::default().data(&[("foo", 1), ("bar", 2)]);
-        widget.render(buffer.area, &mut buffer);
-        assert_buffer_eq!(buffer, Buffer::empty(Rect::new(0, 0, 15, 1)));
-    }
-
-    fn create_test_barchart<'a>() -> BarChart<'a> {
-        BarChart::default()
-            .group_gap(2)
-            .data(BarGroup::default().label("G1".into()).bars(&[
-                Bar::default().value(2),
-                Bar::default().value(1),
-                Bar::default().value(2),
-            ]))
-            .data(BarGroup::default().label("G2".into()).bars(&[
-                Bar::default().value(1),
-                Bar::default().value(2),
-                Bar::default().value(1),
-            ]))
-            .data(BarGroup::default().label("G3".into()).bars(&[
-                Bar::default().value(1),
-                Bar::default().value(2),
-                Bar::default().value(1),
-            ]))
-    }
-
-    #[test]
-    fn test_invisible_groups_and_bars_full() {
-        let chart = create_test_barchart();
-        // Check that the BarChart is shown in full
-        {
-            let mut c = chart.clone();
-            c.remove_invisible_groups_and_bars(21);
-            assert_eq!(c.data.len(), 3);
-            assert_eq!(c.data[2].bars.len(), 3);
-        }
-
-        let mut buffer = Buffer::empty(Rect::new(0, 0, 21, 3));
-        chart.render(buffer.area, &mut buffer);
-        let expected = Buffer::with_lines(vec![
-            "█   █     █       █  ",
-            "█ █ █   █ █ █   █ █ █",
-            "G1      G2      G3   ",
-        ]);
-
-        assert_buffer_eq!(buffer, expected);
-    }
-
-    #[test]
-    fn test_invisible_groups_and_bars_missing_last_2_bars() {
-        // Last 2 bars of G3 should be out of screen. (screen width is 17)
-        let chart = create_test_barchart();
-
-        {
-            let mut w = chart.clone();
-            w.remove_invisible_groups_and_bars(17);
-            assert_eq!(w.data.len(), 3);
-            assert_eq!(w.data[2].bars.len(), 1);
-        }
-
-        let mut buffer = Buffer::empty(Rect::new(0, 0, 17, 3));
-        chart.render(buffer.area, &mut buffer);
-        let expected = Buffer::with_lines(vec![
-            "█   █     █      ",
-            "█ █ █   █ █ █   █",
-            "G1      G2      G",
-        ]);
-        assert_buffer_eq!(buffer, expected);
-    }
-
-    #[test]
-    fn test_invisible_groups_and_bars_missing_last_group() {
-        // G3 should be out of screen. (screen width is 16)
-        let chart = create_test_barchart();
-
-        {
-            let mut w = chart.clone();
-            w.remove_invisible_groups_and_bars(16);
-            assert_eq!(w.data.len(), 2);
-            assert_eq!(w.data[1].bars.len(), 3);
-        }
-
-        let mut buffer = Buffer::empty(Rect::new(0, 0, 16, 3));
-        chart.render(buffer.area, &mut buffer);
-        let expected = Buffer::with_lines(vec![
-            "█   █     █     ",
-            "█ █ █   █ █ █   ",
-            "G1      G2      ",
-        ]);
-        assert_buffer_eq!(buffer, expected);
-    }
-
-    #[test]
-    fn test_invisible_groups_and_bars_show_only_1_bar() {
-        let chart = create_test_barchart();
-
-        {
-            let mut w = chart.clone();
-            w.remove_invisible_groups_and_bars(1);
-            assert_eq!(w.data.len(), 1);
-            assert_eq!(w.data[0].bars.len(), 1);
-        }
-
-        let mut buffer = Buffer::empty(Rect::new(0, 0, 1, 3));
-        chart.render(buffer.area, &mut buffer);
-        let expected = Buffer::with_lines(vec!["█", "█", "G"]);
-        assert_buffer_eq!(buffer, expected);
-    }
-
-    #[test]
-    fn test_invisible_groups_and_bars_all_bars_outside_visible_area() {
-        let chart = create_test_barchart();
-
-        {
-            let mut w = chart.clone();
-            w.remove_invisible_groups_and_bars(0);
-            assert_eq!(w.data.len(), 0);
-        }
-
-        let mut buffer = Buffer::empty(Rect::new(0, 0, 0, 3));
-        // Check if the render method panics
-        chart.render(buffer.area, &mut buffer);
-    }
-
-    #[test]
-    fn test_label_height() {
-        {
-            let barchart = BarChart::default().data(
-                BarGroup::default()
-                    .label("Group Label".into())
-                    .bars(&[Bar::default().value(2).label("Bar Label".into())]),
-            );
-            assert_eq!(barchart.label_height(), 2);
-        }
-
-        {
-            let barchart = BarChart::default().data(
-                BarGroup::default()
-                    .label("Group Label".into())
-                    .bars(&[Bar::default().value(2)]),
-            );
-            assert_eq!(barchart.label_height(), 1);
-        }
-
-        {
-            let barchart = BarChart::default().data(
-                BarGroup::default().bars(&[Bar::default().value(2).label("Bar Label".into())]),
-            );
-            assert_eq!(barchart.label_height(), 1);
-        }
-
-        {
-            let barchart =
-                BarChart::default().data(BarGroup::default().bars(&[Bar::default().value(2)]));
-            assert_eq!(barchart.label_height(), 0);
-        }
-    }
-
     #[test]
     fn can_be_stylized() {
         assert_eq!(
@@ -995,7 +857,7 @@ mod tests {
 
         let mut buffer = Buffer::empty(Rect::new(0, 0, 3, 3));
         chart.render(buffer.area, &mut buffer);
-        let expected = Buffer::with_lines(vec!["  █", "█ █", "G  "]);
+        let expected = Buffer::with_lines(vec!["  █", "1 2", "G  "]);
         assert_buffer_eq!(buffer, expected);
     }
 
@@ -1168,17 +1030,29 @@ mod tests {
 
     #[test]
     fn test_group_label_center() {
-        let chart: BarChart<'_> = BarChart::default().data(
-            BarGroup::default()
-                .label(Line::from(Span::from("G")).alignment(Alignment::Center))
-                .bars(&[Bar::default().value(2), Bar::default().value(5)]),
-        );
+        // test the centered group position when one bar is outside the group
+        let group = BarGroup::from(&[("a", 1), ("b", 2), ("c", 3), ("c", 4)]);
+        let chart = BarChart::default()
+            .data(
+                group
+                    .clone()
+                    .label(Line::from("G1").alignment(Alignment::Center)),
+            )
+            .data(group.label(Line::from("G2").alignment(Alignment::Center)));
 
-        let mut buffer = Buffer::empty(Rect::new(0, 0, 3, 3));
+        let mut buffer = Buffer::empty(Rect::new(0, 0, 13, 5));
         chart.render(buffer.area, &mut buffer);
 
-        let expected = Buffer::with_lines(vec!["  █", "▆ █", " G "]);
-        assert_buffer_eq!(buffer, expected);
+        assert_buffer_eq!(
+            buffer,
+            Buffer::with_lines(vec![
+                "    ▂ █     ▂",
+                "  ▄ █ █   ▄ █",
+                "▆ 2 3 4 ▆ 2 3",
+                "a b c c a b c",
+                "  G1     G2  ",
+            ])
+        );
     }
 
     #[test]
@@ -1192,7 +1066,7 @@ mod tests {
         let mut buffer = Buffer::empty(Rect::new(0, 0, 3, 3));
         chart.render(buffer.area, &mut buffer);
 
-        let expected = Buffer::with_lines(vec!["  █", "▆ █", "  G"]);
+        let expected = Buffer::with_lines(vec!["  █", "▆ 5", "  G"]);
         assert_buffer_eq!(buffer, expected);
     }
 
@@ -1238,4 +1112,234 @@ mod tests {
         chart.render(buffer.area, &mut buffer);
         assert_buffer_eq!(buffer, Buffer::empty(Rect::new(0, 0, 0, 10)));
     }
+
+    #[test]
+    fn single_line() {
+        let mut group: BarGroup = (&[
+            ("a", 0),
+            ("b", 1),
+            ("c", 2),
+            ("d", 3),
+            ("e", 4),
+            ("f", 5),
+            ("g", 6),
+            ("h", 7),
+            ("i", 8),
+        ])
+            .into();
+        group = group.label("Group".into());
+
+        let chart = BarChart::default()
+            .data(group)
+            .bar_set(symbols::bar::NINE_LEVELS);
+
+        let mut buffer = Buffer::empty(Rect::new(0, 0, 17, 1));
+        chart.render(buffer.area, &mut buffer);
+
+        assert_buffer_eq!(buffer, Buffer::with_lines(vec!["  ▁ ▂ ▃ ▄ ▅ ▆ ▇ 8"]));
+    }
+
+    #[test]
+    fn two_lines() {
+        let mut group: BarGroup = (&[
+            ("a", 0),
+            ("b", 1),
+            ("c", 2),
+            ("d", 3),
+            ("e", 4),
+            ("f", 5),
+            ("g", 6),
+            ("h", 7),
+            ("i", 8),
+        ])
+            .into();
+        group = group.label("Group".into());
+
+        let chart = BarChart::default()
+            .data(group)
+            .bar_set(symbols::bar::NINE_LEVELS);
+
+        let mut buffer = Buffer::empty(Rect::new(0, 0, 17, 3));
+        chart.render(Rect::new(0, 1, buffer.area.width, 2), &mut buffer);
+
+        assert_buffer_eq!(
+            buffer,
+            Buffer::with_lines(vec![
+                "                 ",
+                "  ▁ ▂ ▃ ▄ ▅ ▆ ▇ 8",
+                "a b c d e f g h i",
+            ])
+        );
+    }
+
+    #[test]
+    fn three_lines() {
+        let mut group: BarGroup = (&[
+            ("a", 0),
+            ("b", 1),
+            ("c", 2),
+            ("d", 3),
+            ("e", 4),
+            ("f", 5),
+            ("g", 6),
+            ("h", 7),
+            ("i", 8),
+        ])
+            .into();
+        group = group.label(Line::from("Group").alignment(Alignment::Center));
+
+        let chart = BarChart::default()
+            .data(group)
+            .bar_set(symbols::bar::NINE_LEVELS);
+
+        let mut buffer = Buffer::empty(Rect::new(0, 0, 17, 3));
+        chart.render(buffer.area, &mut buffer);
+
+        assert_buffer_eq!(
+            buffer,
+            Buffer::with_lines(vec![
+                "  ▁ ▂ ▃ ▄ ▅ ▆ ▇ 8",
+                "a b c d e f g h i",
+                "      Group      ",
+            ])
+        );
+    }
+
+    #[test]
+    fn three_lines_double_width() {
+        let mut group = BarGroup::from(&[
+            ("a", 0),
+            ("b", 1),
+            ("c", 2),
+            ("d", 3),
+            ("e", 4),
+            ("f", 5),
+            ("g", 6),
+            ("h", 7),
+            ("i", 8),
+        ]);
+        group = group.label(Line::from("Group").alignment(Alignment::Center));
+
+        let chart = BarChart::default()
+            .data(group)
+            .bar_width(2)
+            .bar_set(symbols::bar::NINE_LEVELS);
+
+        let mut buffer = Buffer::empty(Rect::new(0, 0, 26, 3));
+        chart.render(buffer.area, &mut buffer);
+
+        assert_buffer_eq!(
+            buffer,
+            Buffer::with_lines(vec![
+                "   1▁ 2▂ 3▃ 4▄ 5▅ 6▆ 7▇ 8█",
+                "a  b  c  d  e  f  g  h  i ",
+                "          Group           ",
+            ])
+        );
+    }
+
+    #[test]
+    fn four_lines() {
+        let mut group: BarGroup = (&[
+            ("a", 0),
+            ("b", 1),
+            ("c", 2),
+            ("d", 3),
+            ("e", 4),
+            ("f", 5),
+            ("g", 6),
+            ("h", 7),
+            ("i", 8),
+        ])
+            .into();
+        group = group.label(Line::from("Group").alignment(Alignment::Center));
+
+        let chart = BarChart::default()
+            .data(group)
+            .bar_set(symbols::bar::NINE_LEVELS);
+
+        let mut buffer = Buffer::empty(Rect::new(0, 0, 17, 4));
+        chart.render(buffer.area, &mut buffer);
+
+        assert_buffer_eq!(
+            buffer,
+            Buffer::with_lines(vec![
+                "          ▂ ▄ ▆ █",
+                "  ▂ ▄ ▆ 4 5 6 7 8",
+                "a b c d e f g h i",
+                "      Group      ",
+            ])
+        );
+    }
+
+    #[test]
+    fn two_lines_without_bar_labels() {
+        let group = BarGroup::default()
+            .label(Line::from("Group").alignment(Alignment::Center))
+            .bars(&[
+                Bar::default().value(0),
+                Bar::default().value(1),
+                Bar::default().value(2),
+                Bar::default().value(3),
+                Bar::default().value(4),
+                Bar::default().value(5),
+                Bar::default().value(6),
+                Bar::default().value(7),
+                Bar::default().value(8),
+            ]);
+
+        let chart = BarChart::default().data(group);
+
+        let mut buffer = Buffer::empty(Rect::new(0, 0, 17, 3));
+        chart.render(Rect::new(0, 1, buffer.area.width, 2), &mut buffer);
+
+        assert_buffer_eq!(
+            buffer,
+            Buffer::with_lines(vec![
+                "                 ",
+                "  ▁ ▂ ▃ ▄ ▅ ▆ ▇ 8",
+                "      Group      ",
+            ])
+        );
+    }
+
+    #[test]
+    fn one_lines_with_more_bars() {
+        let bars: Vec<Bar> = (0..30).map(|i| Bar::default().value(i)).collect();
+
+        let chart = BarChart::default().data(BarGroup::default().bars(&bars));
+
+        let mut buffer = Buffer::empty(Rect::new(0, 0, 59, 1));
+        chart.render(buffer.area, &mut buffer);
+
+        assert_buffer_eq!(
+            buffer,
+            Buffer::with_lines(vec![
+                "        ▁ ▁ ▁ ▁ ▂ ▂ ▂ ▃ ▃ ▃ ▃ ▄ ▄ ▄ ▄ ▅ ▅ ▅ ▆ ▆ ▆ ▆ ▇ ▇ ▇ █",
+            ])
+        );
+    }
+
+    #[test]
+    fn first_bar_of_the_group_is_half_outside_view() {
+        let chart = BarChart::default()
+            .data(&[("a", 1), ("b", 2)])
+            .data(&[("a", 1), ("b", 2)])
+            .bar_width(2);
+
+        let mut buffer = Buffer::empty(Rect::new(0, 0, 7, 6));
+        chart.render(buffer.area, &mut buffer);
+
+        assert_buffer_eq!(
+            buffer,
+            Buffer::with_lines(vec![
+                "   ██  ",
+                "   ██  ",
+                "▄▄ ██  ",
+                "██ ██  ",
+                "1█ 2█  ",
+                "a  b   ",
+            ])
+        );
+    }
 }

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
@@ -139,16 +144,15 @@ impl<'a> Bar<'a> {
         }
     }
 
-    pub(super) fn render_label_and_value(
+    pub(super) fn render_value(
         self,
         buf: &mut Buffer,
         max_width: u16,
         x: u16,
         y: u16,
         default_value_style: Style,
-        default_label_style: Style,
+        ticks: u64,
     ) {
-        // render the value
         if self.value != 0 {
             let value_label = if let Some(text) = self.text_value {
                 text
@@ -157,7 +161,10 @@ impl<'a> Bar<'a> {
             };
 
             let width = value_label.width() as u16;
-            if width < max_width {
+            const TICKS_PER_LINE: u64 = 8;
+            // if we have enough space or the ticks are greater equal than 1 cell (8)
+            // then print the value
+            if width < max_width || (width == max_width && ticks >= TICKS_PER_LINE) {
                 buf.set_string(
                     x + (max_width.saturating_sub(value_label.len() as u16) >> 1),
                     y,
@@ -166,9 +173,17 @@ impl<'a> Bar<'a> {
                 );
             }
         }
+    }
 
-        // render the label
-        if let Some(mut label) = self.label {
+    pub(super) fn render_label(
+        &mut self,
+        buf: &mut Buffer,
+        max_width: u16,
+        x: u16,
+        y: u16,
+        default_label_style: Style,
+    ) {
+        if let Some(label) = &mut self.label {
             // patch label styles
             for span in &mut label.spans {
                 span.style = default_label_style.patch(span.style);
@@ -176,8 +191,8 @@ impl<'a> Bar<'a> {
 
             buf.set_line(
                 x + (max_width.saturating_sub(label.width() as u16) >> 1),
-                y + 1,
-                &label,
+                y,
+                label,
                 max_width,
             );
         }

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

@@ -16,7 +16,7 @@ use crate::{
     buffer::Buffer,
     layout::{Alignment, Rect},
     style::{Style, Styled},
-    symbols::line,
+    symbols::border,
     widgets::{Borders, Widget},
 };
 
@@ -70,18 +70,46 @@ pub enum BorderType {
     /// ┗━━━━━━━┛
     /// ```
     Thick,
+    /// A border with a single line on the inside of a half block.
+    ///
+    /// # Example
+    ///
+    /// ```plain
+    /// ▗▄▄▄▄▄▄▄▖
+    /// ▐       ▌
+    /// ▐       ▌
+    /// ▝▀▀▀▀▀▀▀▘
+    QuadrantInside,
+
+    /// A border with a single line on the outside of a half block.
+    ///
+    /// # Example
+    ///
+    /// ```plain
+    /// ▛▀▀▀▀▀▀▀▜
+    /// ▌       ▐
+    /// ▌       ▐
+    /// ▙▄▄▄▄▄▄▄▟
+    QuadrantOutside,
 }
 
 impl BorderType {
-    /// Convert this `BorderType` into the corresponding [`Set`](line::Set) of lines.
-    pub const fn line_symbols(border_type: BorderType) -> line::Set {
+    /// Convert this `BorderType` into the corresponding [`Set`](border::Set) of border symbols.
+    pub const fn border_symbols(border_type: BorderType) -> border::Set {
         match border_type {
-            BorderType::Plain => line::NORMAL,
-            BorderType::Rounded => line::ROUNDED,
-            BorderType::Double => line::DOUBLE,
-            BorderType::Thick => line::THICK,
+            BorderType::Plain => border::PLAIN,
+            BorderType::Rounded => border::ROUNDED,
+            BorderType::Double => border::DOUBLE,
+            BorderType::Thick => border::THICK,
+            BorderType::QuadrantInside => border::QUADRANT_INSIDE,
+            BorderType::QuadrantOutside => border::QUADRANT_OUTSIDE,
         }
     }
+
+    /// Convert this `BorderType` into the corresponding [`Set`](border::Set) of border symbols.
+    pub const fn to_border_set(self) -> border::Set {
+        Self::border_symbols(self)
+    }
 }
 
 /// Defines the padding of a [`Block`].
@@ -213,10 +241,9 @@ pub struct Block<'a> {
     borders: Borders,
     /// Border style
     border_style: Style,
-    /// Type of the border. The default is plain lines but one can choose to have rounded or
-    /// doubled lines instead.
-    border_type: BorderType,
-
+    /// The symbols used to render the border. The default is plain lines but one can choose to
+    /// have rounded or doubled lines instead or a custom set of symbols
+    border_set: border::Set,
     /// Widget style
     style: Style,
     /// Block padding
@@ -233,7 +260,7 @@ impl<'a> Block<'a> {
             titles_position: Position::Top,
             borders: Borders::NONE,
             border_style: Style::new(),
-            border_type: BorderType::Plain,
+            border_set: BorderType::Plain.to_border_set(),
             style: Style::new(),
             padding: Padding::zero(),
         }
@@ -302,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
@@ -325,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
@@ -354,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
@@ -372,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
@@ -384,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
@@ -406,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
@@ -414,9 +447,42 @@ impl<'a> Block<'a> {
     /// Sets the symbols used to display the border (e.g. single line, double line, thick or
     /// rounded borders).
     ///
+    /// Setting this overwrites any custom [`border_set`](Block::border_set) that was set.
+    ///
     /// See [`BorderType`] for the full list of available symbols.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use ratatui::{prelude::*, widgets::*};
+    /// Block::default().title("Block").borders(Borders::ALL).border_type(BorderType::Rounded);
+    /// // Renders
+    /// // ╭Block╮
+    /// // │     │
+    /// // ╰─────╯
+    /// ```
+    #[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_type = border_type;
+        self.border_set = border_type.to_border_set();
+        self
+    }
+
+    /// Sets the symbols used to display the border as a [`crate::symbols::border::Set`].
+    ///
+    /// Setting this overwrites any [`border_type`](Block::border_type) that was set.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use ratatui::{prelude::*, widgets::*};
+    /// Block::default().title("Block").borders(Borders::ALL).border_set(symbols::border::DOUBLE);
+    /// // Renders
+    /// // ╔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
     }
 
@@ -427,7 +493,7 @@ impl<'a> Block<'a> {
     /// Draw a block nested within another block
     /// ```
     /// # use ratatui::{prelude::*, widgets::*};
-    /// # fn render_nested_block<B: Backend>(frame: &mut Frame<B>) {
+    /// # fn render_nested_block(frame: &mut Frame) {
     /// let outer_block = Block::default().title("Outer").borders(Borders::ALL);
     /// let inner_block = Block::default().title("Inner").borders(Borders::ALL);
     ///
@@ -450,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);
         }
 
@@ -474,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.
@@ -504,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
@@ -511,20 +585,20 @@ impl<'a> Block<'a> {
 
     fn render_borders(&self, area: Rect, buf: &mut Buffer) {
         buf.set_style(area, self.style);
-        let symbols = BorderType::line_symbols(self.border_type);
+        let symbols = self.border_set;
 
         // Sides
         if self.borders.intersects(Borders::LEFT) {
             for y in area.top()..area.bottom() {
                 buf.get_mut(area.left(), y)
-                    .set_symbol(symbols.vertical)
+                    .set_symbol(symbols.vertical_left)
                     .set_style(self.border_style);
             }
         }
         if self.borders.intersects(Borders::TOP) {
             for x in area.left()..area.right() {
                 buf.get_mut(x, area.top())
-                    .set_symbol(symbols.horizontal)
+                    .set_symbol(symbols.horizontal_top)
                     .set_style(self.border_style);
             }
         }
@@ -532,7 +606,7 @@ impl<'a> Block<'a> {
             let x = area.right() - 1;
             for y in area.top()..area.bottom() {
                 buf.get_mut(x, y)
-                    .set_symbol(symbols.vertical)
+                    .set_symbol(symbols.vertical_right)
                     .set_style(self.border_style);
             }
         }
@@ -540,7 +614,7 @@ impl<'a> Block<'a> {
             let y = area.bottom() - 1;
             for x in area.left()..area.right() {
                 buf.get_mut(x, y)
-                    .set_symbol(symbols.horizontal)
+                    .set_symbol(symbols.horizontal_bottom)
                     .set_style(self.border_style);
             }
         }
@@ -881,9 +955,81 @@ 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: line::Set = BorderType::line_symbols(BorderType::Plain);
+        const _PLAIN: border::Set = BorderType::border_symbols(BorderType::Plain);
     }
 
     #[test]
@@ -927,7 +1073,7 @@ mod tests {
                 titles_position: Position::Top,
                 borders: Borders::NONE,
                 border_style: Style::new(),
-                border_type: BorderType::Plain,
+                border_set: BorderType::Plain.to_border_set(),
                 style: Style::new(),
                 padding: Padding::zero(),
             }
@@ -1119,6 +1265,7 @@ mod tests {
             ])
         );
     }
+
     #[test]
     fn render_rounded_border() {
         let mut buffer = Buffer::empty(Rect::new(0, 0, 15, 3));
@@ -1135,6 +1282,7 @@ mod tests {
             ])
         );
     }
+
     #[test]
     fn render_double_border() {
         let mut buffer = Buffer::empty(Rect::new(0, 0, 15, 3));
@@ -1152,6 +1300,40 @@ mod tests {
         );
     }
 
+    #[test]
+    fn render_quadrant_inside() {
+        let mut buffer = Buffer::empty(Rect::new(0, 0, 15, 3));
+        Block::default()
+            .borders(Borders::ALL)
+            .border_type(BorderType::QuadrantInside)
+            .render(buffer.area, &mut buffer);
+        assert_buffer_eq!(
+            buffer,
+            Buffer::with_lines(vec![
+                "▗▄▄▄▄▄▄▄▄▄▄▄▄▄▖",
+                "▐             ▌",
+                "▝▀▀▀▀▀▀▀▀▀▀▀▀▀▘",
+            ])
+        );
+    }
+
+    #[test]
+    fn render_border_quadrant_outside() {
+        let mut buffer = Buffer::empty(Rect::new(0, 0, 15, 3));
+        Block::default()
+            .borders(Borders::ALL)
+            .border_type(BorderType::QuadrantOutside)
+            .render(buffer.area, &mut buffer);
+        assert_buffer_eq!(
+            buffer,
+            Buffer::with_lines(vec![
+                "▛▀▀▀▀▀▀▀▀▀▀▀▀▀▜",
+                "▌             ▐",
+                "▙▄▄▄▄▄▄▄▄▄▄▄▄▄▟",
+            ])
+        );
+    }
+
     #[test]
     fn render_solid_border() {
         let mut buffer = Buffer::empty(Rect::new(0, 0, 15, 3));
@@ -1168,4 +1350,30 @@ mod tests {
             ])
         );
     }
+
+    #[test]
+    fn render_custom_border_set() {
+        let mut buffer = Buffer::empty(Rect::new(0, 0, 15, 3));
+        Block::default()
+            .borders(Borders::ALL)
+            .border_set(border::Set {
+                top_left: "1",
+                top_right: "2",
+                bottom_left: "3",
+                bottom_right: "4",
+                vertical_left: "L",
+                vertical_right: "R",
+                horizontal_top: "T",
+                horizontal_bottom: "B",
+            })
+            .render(buffer.area, &mut buffer);
+        assert_buffer_eq!(
+            buffer,
+            Buffer::with_lines(vec![
+                "1TTTTTTTTTTTTT2",
+                "L             R",
+                "3BBBBBBBBBBBBB4",
+            ])
+        );
+    }
 }

src/widgets/canvas.rs

@@ -5,7 +5,9 @@ mod points;
 mod rectangle;
 mod world;
 
-use std::fmt::Debug;
+use std::{fmt::Debug, iter::zip};
+
+use itertools::Itertools;
 
 pub use self::{
     circle::Circle,
@@ -36,36 +38,78 @@ pub struct Label<'a> {
     line: TextLine<'a>,
 }
 
+/// A single layer of the canvas.
+///
+/// This allows the canvas to be drawn in multiple layers. This is useful if you want to draw
+/// multiple shapes on the canvas in specific order.
 #[derive(Debug, Default, Clone, Eq, PartialEq, Hash)]
 struct Layer {
+    // a string of characters representing the grid. This will be wrapped to the width of the grid
+    // when rendering
     string: String,
-    colors: Vec<Color>,
+    // colors for foreground and background
+    colors: Vec<(Color, Color)>,
 }
 
+/// A grid of cells that can be painted on.
+///
+/// The grid represents a particular screen region measured in rows and columns. The underlying
+/// resolution of the grid might exceed the number of rows and columns. For example, a grid of
+/// Braille patterns will have a resolution of 2x4 dots per cell. This means that a grid of 10x10
+/// cells will have a resolution of 20x40 dots.
 trait Grid: Debug {
+    /// Get the width of the grid in number of terminal columns
     fn width(&self) -> u16;
+    /// Get the height of the grid in number of terminal rows
     fn height(&self) -> u16;
+    /// Get the resolution of the grid in number of dots. This doesn't have to be the same as the
+    /// number of rows and columns of the grid. For example, a grid of Braille patterns will have a
+    /// resolution of 2x4 dots per cell. This means that a grid of 10x10 cells will have a
+    /// resolution of 20x40 dots.
     fn resolution(&self) -> (f64, f64);
+    /// Paint a point of the grid. The point is expressed in number of dots starting at the origin
+    /// of the grid in the top left corner. Note that this is not the same as the (x, y) coordinates
+    /// of the canvas.
     fn paint(&mut self, x: usize, y: usize, color: Color);
+    /// Save the current state of the grid as a layer to be rendered
     fn save(&self) -> Layer;
+    /// Reset the grid to its initial state
     fn reset(&mut self);
 }
 
+/// The BrailleGrid is a grid made up of cells each containing a Braille pattern.
+///
+/// This makes it possible to draw shapes with a resolution of 2x4 dots per cell. This is useful
+/// when you want to draw shapes with a high resolution. Font support for Braille patterns is
+/// required to see the dots. If your terminal or font does not support this unicode block, you
+/// will see unicode replacement characters (<28>) instead of braille dots.
+///
+/// This grid type only supports a single foreground color for each 2x4 dots cell. There is no way
+/// to set the individual color of each dot in the braille pattern.
 #[derive(Debug, Default, Clone, Eq, PartialEq, Hash)]
 struct BrailleGrid {
+    /// width of the grid in number of terminal columns
     width: u16,
+    /// height of the grid in number of terminal rows
     height: u16,
-    cells: Vec<u16>,
+    /// represents the unicode braille patterns. Will take a value between 0x2800 and 0x28FF
+    /// this is converted to a utf16 string when converting to a layer. See
+    /// <https://en.wikipedia.org/wiki/Braille_Patterns> for more info.
+    utf16_code_points: Vec<u16>,
+    /// The color of each cell only supports foreground colors for now as there's no way to
+    /// individually set the background color of each dot in the braille pattern.
     colors: Vec<Color>,
 }
 
 impl BrailleGrid {
+    /// Create a new BrailleGrid with the given width and height measured in terminal columns and
+    /// rows respectively.
     fn new(width: u16, height: u16) -> BrailleGrid {
         let length = usize::from(width * height);
         BrailleGrid {
             width,
             height,
-            cells: vec![symbols::braille::BLANK; length],
+            utf16_code_points: vec![symbols::braille::BLANK; length],
             colors: vec![Color::Reset; length],
         }
     }
@@ -81,31 +125,26 @@ impl Grid for BrailleGrid {
     }
 
     fn resolution(&self) -> (f64, f64) {
-        (
-            f64::from(self.width) * 2.0 - 1.0,
-            f64::from(self.height) * 4.0 - 1.0,
-        )
+        (f64::from(self.width) * 2.0, f64::from(self.height) * 4.0)
     }
 
     fn save(&self) -> Layer {
-        Layer {
-            string: String::from_utf16(&self.cells).unwrap(),
-            colors: self.colors.clone(),
-        }
+        let string = String::from_utf16(&self.utf16_code_points).unwrap();
+        // the background color is always reset for braille patterns
+        let colors = self.colors.iter().map(|c| (*c, Color::Reset)).collect();
+        Layer { string, colors }
     }
 
     fn reset(&mut self) {
-        for c in &mut self.cells {
-            *c = symbols::braille::BLANK;
-        }
-        for c in &mut self.colors {
-            *c = Color::Reset;
-        }
+        self.utf16_code_points.fill(symbols::braille::BLANK);
+        self.colors.fill(Color::Reset);
     }
 
     fn paint(&mut self, x: usize, y: usize, color: Color) {
         let index = y / 4 * self.width as usize + x / 2;
-        if let Some(c) = self.cells.get_mut(index) {
+        // using get_mut here because we are indexing the vector with usize values
+        // and we want to make sure we don't panic if the index is out of bounds
+        if let Some(c) = self.utf16_code_points.get_mut(index) {
             *c |= symbols::braille::DOTS[y % 4][x % 2];
         }
         if let Some(c) = self.colors.get_mut(index) {
@@ -114,16 +153,27 @@ impl Grid for BrailleGrid {
     }
 }
 
+/// The CharGrid is a grid made up of cells each containing a single character.
+///
+/// This makes it possible to draw shapes with a resolution of 1x1 dots per cell. This is useful
+/// when you want to draw shapes with a low resolution.
 #[derive(Debug, Default, Clone, Eq, PartialEq, Hash)]
 struct CharGrid {
+    /// width of the grid in number of terminal columns
     width: u16,
+    /// height of the grid in number of terminal rows
     height: u16,
+    /// represents a single character for each cell
     cells: Vec<char>,
+    /// The color of each cell
     colors: Vec<Color>,
+    /// The character to use for every cell - e.g. a block, dot, etc.
     cell_char: char,
 }
 
 impl CharGrid {
+    /// Create a new CharGrid with the given width and height measured in terminal columns and
+    /// rows respectively.
     fn new(width: u16, height: u16, cell_char: char) -> CharGrid {
         let length = usize::from(width * height);
         CharGrid {
@@ -146,27 +196,25 @@ impl Grid for CharGrid {
     }
 
     fn resolution(&self) -> (f64, f64) {
-        (f64::from(self.width) - 1.0, f64::from(self.height) - 1.0)
+        (f64::from(self.width), f64::from(self.height))
     }
 
     fn save(&self) -> Layer {
         Layer {
             string: self.cells.iter().collect(),
-            colors: self.colors.clone(),
+            colors: self.colors.iter().map(|c| (*c, Color::Reset)).collect(),
         }
     }
 
     fn reset(&mut self) {
-        for c in &mut self.cells {
-            *c = ' ';
-        }
-        for c in &mut self.colors {
-            *c = Color::Reset;
-        }
+        self.cells.fill(' ');
+        self.colors.fill(Color::Reset);
     }
 
     fn paint(&mut self, x: usize, y: usize, color: Color) {
         let index = y * self.width as usize + x;
+        // using get_mut here because we are indexing the vector with usize values
+        // and we want to make sure we don't panic if the index is out of bounds
         if let Some(c) = self.cells.get_mut(index) {
             *c = self.cell_char;
         }
@@ -176,6 +224,128 @@ impl Grid for CharGrid {
     }
 }
 
+/// The HalfBlockGrid is a grid made up of cells each containing a half block character.
+///
+/// In terminals, each character is usually twice as tall as it is wide. Unicode has a couple of
+/// vertical half block characters, the upper half block '▀' and lower half block '▄' which take up
+/// half the height of a normal character but the full width. Together with an empty space ' ' and a
+/// full block '█', we can effectively double the resolution of a single cell. In addition, because
+/// each character can have a foreground and background color, we can control the color of the upper
+/// and lower half of each cell. This allows us to draw shapes with a resolution of 1x2 "pixels" per
+/// cell.
+///
+/// This allows for more flexibility than the BrailleGrid which only supports a single
+/// foreground color for each 2x4 dots cell, and the CharGrid which only supports a single
+/// character for each cell.
+#[derive(Debug, Default, Clone, Eq, PartialEq, Hash)]
+struct HalfBlockGrid {
+    /// width of the grid in number of terminal columns
+    width: u16,
+    /// height of the grid in number of terminal rows
+    height: u16,
+    /// represents a single color for each "pixel" arranged in column, row order
+    pixels: Vec<Vec<Color>>,
+}
+
+impl HalfBlockGrid {
+    /// Create a new HalfBlockGrid with the given width and height measured in terminal columns and
+    /// rows respectively.
+    fn new(width: u16, height: u16) -> HalfBlockGrid {
+        HalfBlockGrid {
+            width,
+            height,
+            pixels: vec![vec![Color::Reset; width as usize]; height as usize * 2],
+        }
+    }
+}
+
+impl Grid for HalfBlockGrid {
+    fn width(&self) -> u16 {
+        self.width
+    }
+
+    fn height(&self) -> u16 {
+        self.height
+    }
+
+    fn resolution(&self) -> (f64, f64) {
+        (f64::from(self.width), f64::from(self.height) * 2.0)
+    }
+
+    fn save(&self) -> Layer {
+        // Given that we store the pixels in a grid, and that we want to use 2 pixels arranged
+        // vertically to form a single terminal cell, which can be either empty, upper half block,
+        // lower half block or full block, we need examine the pixels in vertical pairs to decide
+        // what character to print in each cell. So these are the 4 states we use to represent each
+        // cell:
+        //
+        // 1. upper: reset, lower: reset => ' ' fg: reset / bg: reset
+        // 2. upper: reset, lower: color => '▄' fg: lower color / bg: reset
+        // 3. upper: color, lower: reset => '▀' fg: upper color / bg: reset
+        // 4. upper: color, lower: color => '▀' fg: upper color / bg: lower color
+        //
+        // Note that because the foreground reset color (i.e. default foreground color) is usually
+        // not the same as the background reset color (i.e. default background color), we need to
+        // swap around the colors for that state (2 reset/color).
+        //
+        // When the upper and lower colors are the same, we could continue to use an upper half
+        // block, but we choose to use a full block instead. This allows us to write unit tests that
+        // treat the cell as a single character instead of two half block characters.
+
+        // first we join each adjacent row together to get an iterator that contains vertical pairs
+        // of pixels, with the lower row being the first element in the pair
+        let vertical_color_pairs = self
+            .pixels
+            .iter()
+            .tuples()
+            .flat_map(|(upper_row, lower_row)| zip(upper_row, lower_row));
+
+        // then we work out what character to print for each pair of pixels
+        let string = vertical_color_pairs
+            .clone()
+            .map(|(upper, lower)| match (upper, lower) {
+                (Color::Reset, Color::Reset) => ' ',
+                (Color::Reset, _) => symbols::half_block::LOWER,
+                (_, Color::Reset) => symbols::half_block::UPPER,
+                (&lower, &upper) => {
+                    if lower == upper {
+                        symbols::half_block::FULL
+                    } else {
+                        symbols::half_block::UPPER
+                    }
+                }
+            })
+            .collect();
+
+        // then we convert these each vertical pair of pixels into a foreground and background color
+        let colors = vertical_color_pairs
+            .map(|(upper, lower)| {
+                let (fg, bg) = match (upper, lower) {
+                    (Color::Reset, Color::Reset) => (Color::Reset, Color::Reset),
+                    (Color::Reset, &lower) => (lower, Color::Reset),
+                    (&upper, Color::Reset) => (upper, Color::Reset),
+                    (&upper, &lower) => (upper, lower),
+                };
+                (fg, bg)
+            })
+            .collect();
+
+        Layer { string, colors }
+    }
+
+    fn reset(&mut self) {
+        self.pixels.fill(vec![Color::Reset; self.width as usize]);
+    }
+
+    fn paint(&mut self, x: usize, y: usize, color: Color) {
+        self.pixels[y][x] = color;
+    }
+}
+
+/// Painter is an abstraction over the [`Context`] that allows to draw shapes on the grid.
+///
+/// It is used by the [`Shape`] trait to draw shapes on the grid. It can be useful to think of this
+/// as similar to the [`Buffer`] struct that is used to draw widgets on the terminal.
 #[derive(Debug)]
 pub struct Painter<'a, 'b> {
     context: &'a mut Context<'b>,
@@ -185,6 +355,17 @@ pub struct Painter<'a, 'b> {
 impl<'a, 'b> Painter<'a, 'b> {
     /// Convert the (x, y) coordinates to location of a point on the grid
     ///
+    /// (x, y) coordinates are expressed in the coordinate system of the canvas. The origin is in
+    /// the lower left corner of the canvas (unlike most other coordinates in Ratatui where the
+    /// origin is the upper left corner). The x and y bounds of the canvas define the specific area
+    /// of some coordinate system that will be drawn on the canvas. The resolution of the grid is
+    /// used to convert the (x, y) coordinates to the location of a point on the grid.
+    ///
+    /// The grid coordinates are expressed in the coordinate system of the grid. The origin is in
+    /// the top left corner of the grid. The x and y bounds of the grid are always [0, width - 1]
+    /// and [0, height - 1] respectively. The resolution of the grid is used to convert the (x, y)
+    /// coordinates to the location of a point on the grid.
+    ///
     /// # Examples:
     /// ```
     /// use ratatui::{prelude::*, widgets::canvas::*};
@@ -215,8 +396,8 @@ impl<'a, 'b> Painter<'a, 'b> {
         if width == 0.0 || height == 0.0 {
             return None;
         }
-        let x = ((x - left) * self.resolution.0 / width) as usize;
-        let y = ((top - y) * self.resolution.1 / height) as usize;
+        let x = ((x - left) * (self.resolution.0 - 1.0) / width) as usize;
+        let y = ((top - y) * (self.resolution.1 - 1.0) / height) as usize;
         Some((x, y))
     }
 
@@ -246,6 +427,11 @@ impl<'a, 'b> From<&'a mut Context<'b>> for Painter<'a, 'b> {
 }
 
 /// Holds the state of the Canvas when painting to it.
+///
+/// This is used by the [`Canvas`] widget to draw shapes on the grid. It can be useful to think of
+/// this as similar to the [`Frame`] struct that is used to draw widgets on the terminal.
+///
+/// [`Frame`]: crate::prelude::Frame
 #[derive(Debug)]
 pub struct Context<'a> {
     x_bounds: [f64; 2],
@@ -257,6 +443,22 @@ pub struct Context<'a> {
 }
 
 impl<'a> Context<'a> {
+    /// Create a new Context with the given width and height measured in terminal columns and rows
+    /// respectively. The x and y bounds define the specific area of some coordinate system that
+    /// will be drawn on the canvas. The marker defines the type of points used to draw the shapes.
+    ///
+    /// Applications should not use this directly but rather use the [`Canvas`] widget. This will be
+    /// created by the [`Canvas::paint`] moethod and passed to the closure that is used to draw on
+    /// the canvas.
+    ///
+    /// The x and y bounds should be specified as left/right and bottom/top respectively. For
+    /// example, if you want to draw a map of the world, you might want to use the following bounds:
+    ///
+    /// ```
+    /// use ratatui::{prelude::*, widgets::canvas::*};
+    ///
+    /// let ctx = Context::new(100, 100, [-180.0, 180.0], [-90.0, 90.0], symbols::Marker::Braille);
+    /// ```
     pub fn new(
         width: u16,
         height: u16,
@@ -272,6 +474,7 @@ impl<'a> Context<'a> {
             symbols::Marker::Block => Box::new(CharGrid::new(width, height, block)),
             symbols::Marker::Bar => Box::new(CharGrid::new(width, height, bar)),
             symbols::Marker::Braille => Box::new(BrailleGrid::new(width, height)),
+            symbols::Marker::HalfBlock => Box::new(HalfBlockGrid::new(width, height)),
         };
         Context {
             x_bounds,
@@ -293,14 +496,16 @@ impl<'a> Context<'a> {
         shape.draw(&mut painter);
     }
 
-    /// Go one layer above in the canvas.
+    /// Save the existing state of the grid as a layer to be rendered and reset the grid to its
+    /// initial state for the next layer.
     pub fn layer(&mut self) {
         self.layers.push(self.grid.save());
         self.grid.reset();
         self.dirty = false;
     }
 
-    /// Print a string on the canvas at the given position
+    /// Print a string on the canvas at the given position. Note that the text is always printed
+    /// on top of the canvas and is not affected by the layers.
     pub fn print<T>(&mut self, x: f64, y: f64, line: T)
     where
         T: Into<TextLine<'a>>,
@@ -330,6 +535,22 @@ impl<'a> Context<'a> {
 ///
 /// See [Unicode Braille Patterns](https://en.wikipedia.org/wiki/Braille_Patterns) for more info.
 ///
+/// The HalfBlock marker is useful when you want to draw shapes with a higher resolution than a
+/// CharGrid but lower than a BrailleGrid. This grid type supports a foreground and background color
+/// for each terminal cell. This allows for more flexibility than the BrailleGrid which only
+/// supports a single foreground color for each 2x4 dots cell.
+///
+/// The Canvas widget is used by calling the [`Canvas::paint`] method and passing a closure that
+/// will be used to draw on the canvas. The closure will be passed a [`Context`] object that can be
+/// used to draw shapes on the canvas.
+///
+/// The [`Context`] object provides a [`Context::draw`] method that can be used to draw shapes on
+/// the canvas. The [`Context::layer`] method can be used to save the current state of the canvas
+/// and start a new layer. This is useful if you want to draw multiple shapes on the canvas in
+/// specific order. The [`Context`] object also provides a [`Context::print`] method that can be
+/// used to print text on the canvas. Note that the text is always printed on top of the canvas and
+/// is not affected by the layers.
+///
 /// # Examples
 ///
 /// ```
@@ -371,7 +592,7 @@ where
     block: Option<Block<'a>>,
     x_bounds: [f64; 2],
     y_bounds: [f64; 2],
-    painter: Option<F>,
+    paint_func: Option<F>,
     background_color: Color,
     marker: symbols::Marker,
 }
@@ -385,7 +606,7 @@ where
             block: None,
             x_bounds: [0.0, 0.0],
             y_bounds: [0.0, 0.0],
-            painter: None,
+            paint_func: None,
             background_color: Color::Reset,
             marker: symbols::Marker::Braille,
         }
@@ -396,6 +617,7 @@ impl<'a, F> Canvas<'a, F>
 where
     F: Fn(&mut Context),
 {
+    /// Set the block that will be rendered around the canvas
     pub fn block(mut self, block: Block<'a>) -> Canvas<'a, F> {
         self.block = Some(block);
         self
@@ -420,10 +642,11 @@ where
 
     /// Store the closure that will be used to draw to the Canvas
     pub fn paint(mut self, f: F) -> Canvas<'a, F> {
-        self.painter = Some(f);
+        self.paint_func = Some(f);
         self
     }
 
+    /// Change the background color of the canvas
     pub fn background_color(mut self, color: Color) -> Canvas<'a, F> {
         self.background_color = color;
         self
@@ -433,12 +656,18 @@ where
     /// as they provide a more fine grained result but you might want to use the simple dot or
     /// block instead if the targeted terminal does not support those symbols.
     ///
+    /// The HalfBlock marker is useful when you want to draw shapes with a higher resolution than a
+    /// CharGrid but lower than a BrailleGrid. This grid type supports a foreground and background
+    /// color for each terminal cell. This allows for more flexibility than the BrailleGrid which
+    /// only supports a single foreground color for each 2x4 dots cell.
+    ///
     /// # Examples
     ///
     /// ```
     /// use ratatui::{prelude::*, widgets::canvas::*};
     ///
     /// Canvas::default().marker(symbols::Marker::Braille).paint(|ctx| {});
+    /// Canvas::default().marker(symbols::Marker::HalfBlock).paint(|ctx| {});
     /// Canvas::default().marker(symbols::Marker::Dot).paint(|ctx| {});
     /// Canvas::default().marker(symbols::Marker::Block).paint(|ctx| {});
     /// ```
@@ -466,7 +695,7 @@ where
 
         let width = canvas_area.width as usize;
 
-        let Some(ref painter) = self.painter else {
+        let Some(ref painter) = self.paint_func else {
             return;
         };
 
@@ -484,17 +713,19 @@ where
 
         // Retrieve painted points for each layer
         for layer in ctx.layers {
-            for (i, (ch, color)) in layer
-                .string
-                .chars()
-                .zip(layer.colors.into_iter())
-                .enumerate()
-            {
+            for (index, (ch, colors)) in layer.string.chars().zip(layer.colors).enumerate() {
                 if ch != ' ' && ch != '\u{2800}' {
-                    let (x, y) = (i % width, i / width);
-                    buf.get_mut(x as u16 + canvas_area.left(), y as u16 + canvas_area.top())
-                        .set_char(ch)
-                        .set_fg(color);
+                    let (x, y) = (
+                        (index % width) as u16 + canvas_area.left(),
+                        (index / width) as u16 + canvas_area.top(),
+                    );
+                    let cell = buf.get_mut(x, y).set_char(ch);
+                    if colors.0 != Color::Reset {
+                        cell.set_fg(colors.0);
+                    }
+                    if colors.1 != Color::Reset {
+                        cell.set_bg(colors.1);
+                    }
                 }
             }
         }

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/canvas/rectangle.rs

@@ -94,6 +94,41 @@ mod tests {
         assert_buffer_eq!(buffer, expected);
     }
 
+    #[test]
+    fn draw_half_block_lines() {
+        let mut buffer = Buffer::empty(Rect::new(0, 0, 10, 10));
+        let canvas = Canvas::default()
+            .marker(Marker::HalfBlock)
+            .x_bounds([0.0, 10.0])
+            .y_bounds([0.0, 10.0])
+            .paint(|context| {
+                context.draw(&Rectangle {
+                    x: 0.0,
+                    y: 0.0,
+                    width: 10.0,
+                    height: 10.0,
+                    color: Color::Red,
+                });
+            });
+        canvas.render(buffer.area, &mut buffer);
+        let mut expected = Buffer::with_lines(vec![
+            "█▀▀▀▀▀▀▀▀█",
+            "█        █",
+            "█        █",
+            "█        █",
+            "█        █",
+            "█        █",
+            "█        █",
+            "█        █",
+            "█        █",
+            "█▄▄▄▄▄▄▄▄█",
+        ]);
+        expected.set_style(buffer.area, Style::new().red().on_red());
+        expected.set_style(buffer.area.inner(&Margin::new(1, 0)), Style::reset().red());
+        expected.set_style(buffer.area.inner(&Margin::new(1, 1)), Style::reset());
+        assert_buffer_eq!(buffer, expected);
+    }
+
     #[test]
     fn draw_braille_lines() {
         let mut buffer = Buffer::empty(Rect::new(0, 0, 10, 10));

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/clear.rs

@@ -10,7 +10,7 @@ use crate::{buffer::Buffer, layout::Rect, widgets::Widget};
 /// ```
 /// use ratatui::{prelude::*, widgets::*};
 ///
-/// fn draw_on_clear<B: Backend>(f: &mut Frame<B>, area: Rect) {
+/// fn draw_on_clear(f: &mut Frame, area: Rect) {
 ///     let block = Block::default().title("Block").borders(Borders::ALL);
 ///     f.render_widget(Clear, area); // <- this will clear/reset the area first
 ///     f.render_widget(block, area); // now render the block widget