fix: Update src/backend/crossterm.rs

Co-authored-by: EdJoPaTo <rfc-conform-git-commit-email@funny-long-domain-label-everyone-hates-as-it-is-too-long.edjopato.de>

.cargo-husky/hooks/pre-push

@@ -1,16 +0,0 @@
-#!/usr/bin/env bash
-
-if !(command cargo-make >/dev/null 2>&1); then # Check if cargo-make is installed
-    echo Attempting to run cargo-make as part of the pre-push hook but it\'s not installed.
-    echo Please install it by running the following command:
-    echo
-    echo "    cargo install --force cargo-make"
-    echo
-    echo If you don\'t want to run cargo-make as part of the pre-push hook, you can run
-    echo the following command instead of git push:
-    echo
-    echo "    git push --no-verify"
-    exit 1
-fi
-
-cargo make ci

.editorconfig

@@ -2,6 +2,12 @@
 
 root = true
 
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+
 [*.rs]
 indent_style = space
 indent_size = 4

.github/CODEOWNERS

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

.github/workflows/cd.yml

@@ -37,7 +37,7 @@ jobs:
           args: --allow-dirty --token ${{ secrets.CARGO_TOKEN }}
 
       - name: Generate a changelog
-        uses: orhun/git-cliff-action@v2
+        uses: orhun/git-cliff-action@v3
         with:
           config: cliff.toml
           args: --unreleased --tag ${{ env.NEXT_TAG }} --strip header

.github/workflows/check-pr.yml

@@ -44,24 +44,6 @@ jobs:
           header: pr-title-lint-error
           delete: true
 
-  check-signed:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      pull-requests: write
-    steps:
-      # Check commit signature and add comment if needed
-      - name: Check signed commits in PR
-        uses: 1Password/check-signed-commits-action@v1
-        with:
-          comment: |
-            Thank you for opening this pull request!
-
-            We require commits to be signed and it looks like this PR contains unsigned commits.
-
-            Get help in the [CONTRIBUTING.md](https://github.com/ratatui-org/ratatui/blob/main/CONTRIBUTING.md#sign-your-commits)
-            or on [Github doc](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits).
-
   check-breaking-change-label:
     runs-on: ubuntu-latest
     env:
@@ -102,4 +84,3 @@ jobs:
           echo "Pull request is labeled as 'do not merge'"
           echo "This workflow fails so that the pull request cannot be merged"
           exit 1
-

.github/workflows/ci.yml

@@ -29,28 +29,19 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        if: github.event_name != 'pull_request'
         uses: actions/checkout@v4
-      - name: Checkout
-        if: github.event_name == 'pull_request'
-        uses: actions/checkout@v4
-        with:
-          ref: ${{ github.event.pull_request.head.sha }}
       - name: Install Rust nightly
         uses: dtolnay/rust-toolchain@nightly
         with:
           components: rustfmt
       - name: Install cargo-make
         uses: taiki-e/install-action@cargo-make
+      - name: Cache Cargo dependencies
+        uses: Swatinem/rust-cache@v2
       - name: Check formatting
         run: cargo make lint-format
       - name: Check documentation
         run: cargo make lint-docs
-      - name: Check conventional commits
-        uses: crate-ci/committed@master
-        with:
-          args: "-vv"
-          commits: HEAD
       - name: Check typos
         uses: crate-ci/typos@master
       - name: Lint dependencies
@@ -67,6 +58,8 @@ jobs:
           components: clippy
       - name: Install cargo-make
         uses: taiki-e/install-action@cargo-make
+      - name: Cache Cargo dependencies
+        uses: Swatinem/rust-cache@v2
       - name: Run cargo make clippy-all
         run: cargo make clippy
 
@@ -83,10 +76,12 @@ jobs:
         uses: taiki-e/install-action@v2
         with:
           tool: cargo-llvm-cov,cargo-make
+      - name: Cache Cargo dependencies
+        uses: Swatinem/rust-cache@v2
       - name: Generate coverage
         run: cargo make coverage
       - name: Upload to codecov.io
-        uses: codecov/codecov-action@v3
+        uses: codecov/codecov-action@v4
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
           fail_ci_if_error: true
@@ -95,8 +90,8 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: [ ubuntu-latest, windows-latest, macos-latest ]
-        toolchain: [ "1.70.0", "stable" ]
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        toolchain: ["1.74.0", "stable"]
     runs-on: ${{ matrix.os }}
     steps:
       - name: Checkout
@@ -107,6 +102,8 @@ jobs:
           toolchain: ${{ matrix.toolchain }}
       - name: Install cargo-make
         uses: taiki-e/install-action@cargo-make
+      - name: Cache Cargo dependencies
+        uses: Swatinem/rust-cache@v2
       - name: Run cargo make check
         run: cargo make check
         env:
@@ -116,7 +113,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: [ ubuntu-latest, windows-latest, macos-latest ]
+        os: [ubuntu-latest, windows-latest, macos-latest]
     runs-on: ${{ matrix.os }}
     steps:
       - name: Checkout
@@ -125,6 +122,8 @@ jobs:
         uses: dtolnay/rust-toolchain@stable
       - name: Install cargo-make
         uses: taiki-e/install-action@cargo-make
+      - name: Cache Cargo dependencies
+        uses: Swatinem/rust-cache@v2
       - name: Test docs
         run: cargo make test-doc
         env:
@@ -134,9 +133,9 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: [ ubuntu-latest, windows-latest, macos-latest ]
-        toolchain: [ "1.70.0", "stable" ]
-        backend: [ crossterm, termion, termwiz ]
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        toolchain: ["1.74.0", "stable"]
+        backend: [crossterm, termion, termwiz]
         exclude:
           # termion is not supported on windows
           - os: windows-latest
@@ -153,6 +152,8 @@ jobs:
         uses: taiki-e/install-action@cargo-make
       - name: Install cargo-nextest
         uses: taiki-e/install-action@nextest
+      - name: Cache Cargo dependencies
+        uses: Swatinem/rust-cache@v2
       - name: Test ${{ matrix.backend }}
         run: cargo make test-backend ${{ matrix.backend }}
         env:

BREAKING-CHANGES.md

@@ -2,7 +2,7 @@
 
 This document contains a list of breaking changes in each version and some notes to help migrate
 between versions. It is compiled manually from the commit history and changelog. We also tag PRs on
-github with a [breaking change] label.
+GitHub with a [breaking change] label.
 
 [breaking change]: (https://github.com/ratatui-org/ratatui/issues?q=label%3A%22breaking+change%22)
 
@@ -10,7 +10,14 @@ github with a [breaking change] label.
 
 This is a quick summary of the sections below:
 
-- [v0.26.0 (unreleased)](#v0260-unreleased)
+- [Unreleased](#unreleased)
+  - 'termion' updated to 4.0
+  - `Rect::inner` takes `Margin` directly instead of reference
+  - `Buffer::filled` takes `Cell` directly instead of reference
+  - `Stylize::bg()` now accepts `Into<Color>`
+  - Removed deprecated `List::start_corner`
+- [v0.26.0](#v0260)
+  - `Flex::Start` is the new default flex mode for `Layout`
   - `patch_style` & `reset_style` now consume and return `Self`
   - Removed deprecated `Block::title_on_bottom`
   - `Line` now has an extra `style` field which applies the style to the entire line
@@ -36,7 +43,7 @@ This is a quick summary of the sections below:
   - `Scrollbar`: symbols moved to `symbols` module
   - MSRV is now 1.67.0
 - [v0.22.0](#v0220)
-  - serde representation of `Borders` and `Modifiers` has changed
+  - `serde` representation of `Borders` and `Modifiers` has changed
 - [v0.21.0](#v0210)
   - MSRV is now 1.65.0
   - `terminal::ViewPort` is now an enum
@@ -46,13 +53,148 @@ This is a quick summary of the sections below:
   - MSRV is now 1.63.0
   - `List` no longer ignores empty strings
 
-## v0.26.0 (unreleased)
+## Unreleased
+
+### Prelude items added / removed ([#1149])
+
+The following items have been removed from the prelude:
+
+- `style::Styled` - this trait is useful for widgets that want to
+  support the Stylize trait, but it adds complexity as widgets have two
+  `style` methods and a `set_style` method.
+- `symbols::Marker` - this item is used by code that needs to draw to
+  the `Canvas` widget, but it's not a common item that would be used by
+  most users of the library.
+- `terminal::{CompletedFrame, TerminalOptions, Viewport}` - these items
+  are rarely used by code that needs to interact with the terminal, and
+  they're generally only ever used once in any app.
+
+The following items have been added to the prelude:
+
+- `layout::{Position, Size}` - these items are used by code that needs
+  to interact with the layout system. These are newer items that were
+  added in the last few releases, which should be used more liberally.
+  This may cause conflicts for types defined elsewhere with a similar
+  name.
+
+To update your app:
+
+```diff
+// if your app uses Styled::style() or Styled::set_style():
+-use ratatui::prelude::*;
++use ratatui::{prelude::*, style::Styled};
+
+// if your app uses symbols::Marker:
+-use ratatui::prelude::*;
++use ratatui::{prelude::*, symbols::Marker}
+
+// if your app uses terminal::{CompletedFrame, TerminalOptions, Viewport}
+-use ratatui::prelude::*;
++use ratatui::{prelude::*, terminal::{CompletedFrame, TerminalOptions, Viewport}};
+
+// to disambiguate existing types named Position or Size:
+- use some_crate::{Position, Size};
+- let size: Size = ...;
+- let position: Position = ...;
++ let size: some_crate::Size = ...;
++ let position: some_crate::Position = ...;
+```
+
+[#1149]: https://github.com/ratatui-org/ratatui/pull/1149
+
+### Termion is updated to 4.0 [#1106]
+
+Changelog: <https://gitlab.redox-os.org/redox-os/termion/-/blob/master/CHANGELOG.md>
+
+A change is only necessary if you were matching on all variants of the `MouseEvent` enum without a
+wildcard. In this case, you need to either handle the two new variants, `MouseLeft` and
+`MouseRight`, or add a wildcard.
+
+[#1106]: https://github.com/ratatui-org/ratatui/pull/1106
+
+### `Rect::inner` takes `Margin` directly instead of reference ([#1008])
+
+[#1008]: https://github.com/ratatui-org/ratatui/pull/1008
+
+`Margin` needs to be passed without reference now.
+
+```diff
+-let area = area.inner(&Margin {
++let area = area.inner(Margin {
+     vertical: 0,
+     horizontal: 2,
+ });
+```
+
+### `Buffer::filled` takes `Cell` directly instead of reference ([#1148])
+
+[#1148]: https://github.com/ratatui-org/ratatui/pull/1148
+
+`Buffer::filled` moves the `Cell` instead of taking a reference.
+
+```diff
+-Buffer::filled(area, &Cell::new("X"));
++Buffer::filled(area, Cell::new("X"));
+```
+
+### `Stylize::bg()` now accepts `Into<Color>` ([#1103])
+
+[#1103]: https://github.com/ratatui-org/ratatui/pull/1103
+
+Previously, `Stylize::bg()` accepted `Color` but now accepts `Into<Color>`. This allows more
+flexible types from calling scopes, though it can break some type inference in the calling scope.
+
+### Remove deprecated `List::start_corner` and `layout::Corner` ([#759])
+
+[#759]: https://github.com/ratatui-org/ratatui/pull/759
+
+`List::start_corner` was deprecated in v0.25. Use `List::direction` and `ListDirection` instead.
+
+```diff
+- list.start_corner(Corner::TopLeft);
+- list.start_corner(Corner::TopRight);
+// This is not an error, BottomRight rendered top to bottom previously
+- list.start_corner(Corner::BottomRight);
+// all becomes
++ list.direction(ListDirection::TopToBottom);
+```
+
+```diff
+- list.start_corner(Corner::BottomLeft);
+// becomes
++ list.direction(ListDirection::BottomToTop);
+```
+
+`layout::Corner` was removed entirely.
+
+## [v0.26.0](https://github.com/ratatui-org/ratatui/releases/tag/v0.26.0)
+
+### `Flex::Start` is the new default flex mode for `Layout` ([#881])
+
+[#881]: https://github.com/ratatui-org/ratatui/pull/881
+
+Previously, constraints would stretch to fill all available space, violating constraints if
+necessary.
+
+With v0.26.0, `Flex` modes are introduced, and the default is `Flex::Start`, which will align
+areas associated with constraints to be beginning of the area. With v0.26.0, additionally,
+`Min` constraints grow to fill excess space. These changes will allow users to build layouts
+more easily.
+
+With v0.26.0, users will most likely not need to change what constraints they use to create
+existing layouts with `Flex::Start`. However, to get old behavior, use `Flex::Legacy`.
+
+```diff
+- let rects = Layout::horizontal([Length(1), Length(2)]).split(area);
+// becomes
++ let rects = Layout::horizontal([Length(1), Length(2)]).flex(Flex::Legacy).split(area);
+```
 
 ### `Table::new()` now accepts `IntoIterator<Item: Into<Row<'a>>>` ([#774])
 
 [#774]: https://github.com/ratatui-org/ratatui/pull/774
 
-Previously, `Table::new()` accepted `IntoIterator<Item=Row<'a>>`.  The argument change to
+Previously, `Table::new()` accepted `IntoIterator<Item=Row<'a>>`. The argument change to
 `IntoIterator<Item: Into<Row<'a>>>`, This allows more flexible types from calling scopes, though it
 can some break type inference in the calling scope for empty containers.
 
@@ -69,7 +211,7 @@ This can be resolved either by providing an explicit type (e.g. `Vec::<Row>::new
 
 [#776]: https://github.com/ratatui-org/ratatui/pull/776
 
-Previously, `Tabs::new()` accepted `Vec<T>` where `T: Into<Line<'a>>`.  This allows more flexible
+Previously, `Tabs::new()` accepted `Vec<T>` where `T: Into<Line<'a>>`. This allows more flexible
 types from calling scopes, though it can break some type inference in the calling scope.
 
 This typically occurs when collecting an iterator prior to calling `Tabs::new`, and can be resolved
@@ -86,7 +228,7 @@ by removing the call to `.collect()`.
 [#751]: https://github.com/ratatui-org/ratatui/pull/751
 
 The default() implementation of Table now sets the column_spacing field to 1 and the segment_size
-field to SegmentSize::None. This will affect the rendering of a small amount of apps.
+field to `SegmentSize::None`. This will affect the rendering of a small amount of apps.
 
 To use the previous default values, call `table.segment_size(Default::default())` and
 `table.column_spacing(0)`.
@@ -110,8 +252,6 @@ The following example shows how to migrate for `Line`, but the same applies for
 
 ### Remove deprecated `Block::title_on_bottom` ([#757])
 
-[#757]: https://github.com/ratatui-org/ratatui/pull/757
-
 `Block::title_on_bottom` was deprecated in v0.22. Use `Block::title` and `Title::position` instead.
 
 ```diff
@@ -132,7 +272,7 @@ longer can be called from a constant context.
 [#708]: https://github.com/ratatui-org/ratatui/pull/708
 
 Previously the style of a `Line` was stored in the `Span`s that make up the line. Now the `Line`
-itself has a `style` field, which can be set with the `Line::style` method. Any code that creates
+itself has a `style` field, which can be set with the `Line::styled` method. Any code that creates
 `Line`s using the struct initializer instead of constructors will fail to compile due to the added
 field. This can be easily fixed by adding `..Default::default()` to the field list or by using a
 constructor method (`Line::styled()`, `Line::raw()`) or conversion method (`Line::from()`).
@@ -200,8 +340,8 @@ widget in the default configuration would not show any indication of the selecte
 
 [#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:
+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)
@@ -259,7 +399,7 @@ let layout = layout::new(Direction::Vertical, [Constraint::Min(1), Constraint::M
 
 ## [v0.24.0](https://github.com/ratatui-org/ratatui/releases/tag/v0.24.0)
 
-### ScrollbarState field type changed from `u16` to `usize` ([#456])
+### `ScrollbarState` field type changed from `u16` to `usize` ([#456])
 
 [#456]: https://github.com/ratatui-org/ratatui/pull/456
 
@@ -363,12 +503,12 @@ 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])
+### `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
+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)
@@ -400,9 +540,9 @@ let terminal = Terminal::with_options(backend, TerminalOptions {
 
 [#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
+A new type `Masked` was introduced that implements `From<Text<'a>>`. This causes any code that
 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.:
+`to_string()` / `to_owned()` / `as_str()` on the value. E.g.:
 
 ```diff
 - let paragraph = Paragraph::new("".as_ref());

CONTRIBUTING.md

@@ -54,21 +54,11 @@ describes the nature of the problem that the commit is solving and any unintuiti
 change. It's rare that code changes can easily communicate intent, so make sure this is clearly
 documented.
 
-### Clean up your commits
-
-The final version of your PR that will be committed to the repository should be rebased and tested
-against main. Every commit will end up as a line in the changelog, so please squash commits that are
-only formatting or incremental fixes to things brought up as part of the PR review. Aim for a single
-commit (unless there is a strong reason to stack the commits). See [Git Best Practices - On Sausage
-Making](https://sethrobertson.github.io/GitBestPractices/#sausage) for more on this.
-
 ### Run CI tests before pushing a PR
 
-We're using [cargo-husky](https://github.com/rhysd/cargo-husky) to automatically run git hooks,
-which will run `cargo make ci` before each push. To initialize the hook  run `cargo test`. If
-`cargo-make` is not installed, it will provide instructions to install it for you. This will ensure
-that your code is formatted, compiles and passes all tests before you push. If you need to skip this
-check, you can use `git push --no-verify`.
+Running `cargo make ci` before pushing will perform the same checks that we do in the CI process.
+It's not mandatory to do this before pushing, however it may save you time to do so instead of
+waiting for GitHub to run the checks.
 
 ### Sign your commits
 
@@ -120,7 +110,8 @@ exist to show coverage directly in your editor. E.g.:
 
 ### Documentation
 
-Here are some guidelines for writing documentation in Ratatui.  
+Here are some guidelines for writing documentation in Ratatui.
+
 Every public API **must** be documented.
 
 Keep in mind that Ratatui tends to attract beginner Rust users that may not be familiar with Rust
@@ -133,10 +124,9 @@ the concepts pointing to the various methods. Focus on interaction with various
 enough information that helps understand why you might want something.
 
 Examples should help users understand a particular usage, not test a feature. They should be as
-simple as possible.  
-Prefer hiding imports and using wildcards to keep things concise. Some imports may still be shown
-to demonstrate a particular non-obvious import (e.g. `Stylize` trait to use style methods).  
-Speaking of `Stylize`, you should use it over the more verbose style setters:
+simple as possible. Prefer hiding imports and using wildcards to keep things concise. Some imports
+may still be shown to demonstrate a particular non-obvious import (e.g. `Stylize` trait to use style
+methods). Speaking of `Stylize`, you should use it over the more verbose style setters:
 
 ```rust
 let style = Style::new().red().bold();
@@ -146,7 +136,7 @@ let style = Style::default().fg(Color::Red).add_modifier(Modifiers::BOLD);
 
 #### Format
 
-- First line is summary, second is blank, third onward is more detail  
+- First line is summary, second is blank, third onward is more detail
 
 ```rust
 /// Summary
@@ -156,10 +146,10 @@ let style = Style::default().fg(Color::Red).add_modifier(Modifiers::BOLD);
 fn foo() {}
 ```
 
-- Max line length is 100 characters  
+- Max line length is 100 characters
 See [vscode rewrap extension](https://marketplace.visualstudio.com/items?itemName=stkb.rewrap)
 
-- Doc comments are above macros  
+- Doc comments are above macros
 i.e.
 
 ```rust
@@ -168,7 +158,7 @@ i.e.
 struct Foo {}
 ```
 
-- Code items should be between backticks  
+- Code items should be between backticks
 i.e. ``[`Block`]``, **NOT** ``[Block]``
 
 ### Deprecation notice

Cargo.toml

@@ -1,11 +1,13 @@
 [package]
 name = "ratatui"
-version = "0.25.0" # crate version
+version = "0.26.3" # 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/"
-keywords = ["tui", "terminal", "dashboard"]
 repository = "https://github.com/ratatui-org/ratatui"
+homepage = "https://ratatui.rs"
+keywords = ["tui", "terminal", "dashboard"]
+categories = ["command-line-interface"]
 readme = "README.md"
 license = "MIT"
 exclude = [
@@ -18,48 +20,88 @@ exclude = [
 ]
 autoexamples = true
 edition = "2021"
-rust-version = "1.70.0"
+rust-version = "1.74.0"
 
 [badges]
 
 [dependencies]
-crossterm = { version = "0.27", optional = true }
-termion = { version = "3.0", optional = true }
-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.12"
+compact_str = "0.7.1"
+crossterm = { version = "0.27", optional = true }
+document-features = { version = "0.2.7", optional = true }
+itertools = "0.13"
+lru = "0.12.0"
 paste = "1.0.2"
-strum = { version = "0.25", features = ["derive"] }
+palette = { version = "0.7.6", optional = true }
+serde = { version = "1", optional = true, features = ["derive"] }
+stability = "0.2.0"
+strum = { version = "0.26", features = ["derive"] }
+strum_macros = { version = "0.26.3" }
+termion = { version = "4.0.0", optional = true }
+termwiz = { version = "0.22.0", optional = true }
 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.12.0"
-stability = "0.1.1"
-compact_str = "0.7.1"
+unicode-truncate = "1"
+unicode-width = "0.1.13"
 
 [dev-dependencies]
 anyhow = "1.0.71"
 argh = "0.1.12"
 better-panic = "0.3.0"
-cargo-husky = { version = "1.5.0", default-features = false, features = [
-  "user-hooks",
-] }
 color-eyre = "0.6.2"
 criterion = { version = "0.5.1", features = ["html_reports"] }
-derive_builder = "0.12.0"
+derive_builder = "0.20.0"
 fakeit = "1.1"
 font8x8 = "0.3.1"
+indoc = "2"
 palette = "0.7.3"
 pretty_assertions = "1.4.0"
 rand = "0.8.5"
 rand_chacha = "0.3.1"
-rstest = "0.18.2"
+rstest = "0.21.0"
 serde_json = "1.0.109"
+tracing = "0.1.40"
+tracing-appender = "0.2.3"
+tracing-subscriber = { version = "0.3.18", features = ["env-filter"] }
+
+[lints.rust]
+unsafe_code = "forbid"
+
+[lints.clippy]
+cargo = { level = "warn", priority = -1 }
+pedantic = { level = "warn", priority = -1 }
+cast_possible_truncation = "allow"
+cast_possible_wrap = "allow"
+cast_precision_loss = "allow"
+cast_sign_loss = "allow"
+missing_errors_doc = "allow"
+missing_panics_doc = "allow"
+module_name_repetitions = "allow"
+must_use_candidate = "allow"
+
+# nursery or restricted
+as_underscore = "warn"
+deref_by_slicing = "warn"
+else_if_without_else = "warn"
+empty_line_after_doc_comments = "warn"
+equatable_if_let = "warn"
+fn_to_numeric_cast_any = "warn"
+format_push_string = "warn"
+map_err_ignore = "warn"
+missing_const_for_fn = "warn"
+mixed_read_write_in_expression = "warn"
+mod_module_files = "warn"
+needless_pass_by_ref_mut = "warn"
+needless_raw_strings = "warn"
+or_fun_call = "warn"
+redundant_type_annotations = "warn"
+rest_pat_in_fully_bound_structs = "warn"
+string_lit_chars_any = "warn"
+string_slice = "warn"
+string_to_string = "warn"
+unnecessary_self_imports = "warn"
+use_self = "warn"
 
 [features]
 #! The crate provides a set of optional features that can be enabled in your `cargo.toml` file.
@@ -69,55 +111,65 @@ serde_json = "1.0.109"
 ## 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].
+## enables the [`CrosstermBackend`](backend::CrosstermBackend) backend and adds a dependency on [`crossterm`].
 crossterm = ["dep:crossterm"]
-## enables the [`TermionBackend`] backend and adds a dependency on the [Termion crate].
+## enables the [`TermionBackend`](backend::TermionBackend) backend and adds a dependency on [`termion`].
 termion = ["dep:termion"]
-## enables the [`TermwizBackend`] backend and adds a dependency on the [Termwiz crate].
+## enables the [`TermwizBackend`](backend::TermwizBackend) backend and adds a dependency on [`termwiz`].
 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].
+## 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.
 serde = ["dep:serde", "bitflags/serde", "compact_str/serde"]
 
 ## enables the [`border!`] macro.
 macros = []
 
+## enables conversions from colors in the [`palette`] crate to [`Color`](crate::style::Color).
+palette = ["dep:palette"]
+
 ## enables all widgets.
 all-widgets = ["widget-calendar"]
 
 #! Widgets that add dependencies are gated behind feature flags to prevent unused transitive
 #! dependencies. The available features are:
-## enables the [`calendar`] widget module and adds a dependency on the [Time crate].
+## enables the [`calendar`](widgets::calendar) widget module and adds a dependency on [`time`].
 widget-calendar = ["dep:time"]
 
-#! Underline color is only supported by the [`CrosstermBackend`] backend, and is not supported
-#! on Windows 7.
+#! The following optional features are only available for some backends:
+
 ## enables the backend code that sets the underline color.
+## Underline color is only supported by the [`CrosstermBackend`](backend::CrosstermBackend) backend,
+## and is not supported on Windows 7.
 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"]
+unstable = ["unstable-rendered-line-info", "unstable-widget-ref"]
 
-## 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
+## Enables the [`Paragraph::line_count`](widgets::Paragraph::line_count)
+## [`Paragraph::line_width`](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 = []
 
+## Enables the [`WidgetRef`](widgets::WidgetRef) and [`StatefulWidgetRef`](widgets::StatefulWidgetRef) traits which are experimental and may change in
+## the future.
+unstable-widget-ref = []
+
 [package.metadata.docs.rs]
 all-features = true
 # see https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html
 cargo-args = ["-Zunstable-options", "-Zrustdoc-scrape-examples"]
 rustdoc-args = ["--cfg", "docsrs"]
 
+# Improve benchmark consistency
+[profile.bench]
+codegen-units = 1
+lto = true
+
 [[bench]]
 name = "barchart"
 harness = false
@@ -126,6 +178,10 @@ harness = false
 name = "block"
 harness = false
 
+[[bench]]
+name = "line"
+harness = false
+
 [[bench]]
 name = "list"
 harness = false
@@ -153,13 +209,13 @@ required-features = ["crossterm"]
 doc-scrape-examples = true
 
 [[example]]
-name = "canvas"
-required-features = ["crossterm"]
+name = "calendar"
+required-features = ["crossterm", "widget-calendar"]
 doc-scrape-examples = true
 
 [[example]]
-name = "calendar"
-required-features = ["crossterm", "widget-calendar"]
+name = "canvas"
+required-features = ["crossterm"]
 doc-scrape-examples = true
 
 [[example]]
@@ -178,6 +234,16 @@ name = "colors_rgb"
 required-features = ["crossterm"]
 doc-scrape-examples = true
 
+[[example]]
+name = "constraint-explorer"
+required-features = ["crossterm"]
+doc-scrape-examples = true
+
+[[example]]
+name = "constraints"
+required-features = ["crossterm"]
+doc-scrape-examples = false
+
 [[example]]
 name = "custom_widget"
 required-features = ["crossterm"]
@@ -198,6 +264,11 @@ name = "docsrs"
 required-features = ["crossterm"]
 doc-scrape-examples = false
 
+[[example]]
+name = "flex"
+required-features = ["crossterm"]
+doc-scrape-examples = true
+
 [[example]]
 name = "gauge"
 required-features = ["crossterm"]
@@ -208,19 +279,24 @@ name = "hello_world"
 required-features = ["crossterm"]
 doc-scrape-examples = true
 
+[[example]]
+name = "inline"
+required-features = ["crossterm"]
+doc-scrape-examples = true
+
 [[example]]
 name = "layout"
 required-features = ["crossterm"]
 doc-scrape-examples = true
 
 [[example]]
-name = "constraints"
+name = "line_gauge"
 required-features = ["crossterm"]
-doc-scrape-examples = false
+doc-scrape-examples = true
 
 [[example]]
-name = "flex"
-required-features = ["crossterm"]
+name = "hyperlink"
+required-features = ["crossterm", "unstable-widget-ref"]
 doc-scrape-examples = true
 
 [[example]]
@@ -228,6 +304,12 @@ name = "list"
 required-features = ["crossterm"]
 doc-scrape-examples = true
 
+[[example]]
+name = "minimal"
+required-features = ["crossterm"]
+# prefer to show the more featureful examples in the docs
+doc-scrape-examples = false
+
 [[example]]
 name = "modifiers"
 required-features = ["crossterm"]
@@ -275,12 +357,12 @@ required-features = ["crossterm"]
 doc-scrape-examples = true
 
 [[example]]
-name = "user_input"
+name = "tracing"
 required-features = ["crossterm"]
 doc-scrape-examples = true
 
 [[example]]
-name = "inline"
+name = "user_input"
 required-features = ["crossterm"]
 doc-scrape-examples = true
 

FUNDING.json

@@ -0,0 +1,7 @@
+{
+  "drips": {
+    "ethereum": {
+      "ownedBy": "0x6053C8984f4F214Ad12c4653F28514E1E09213B5"
+    }
+  }
+}

LICENSE

@@ -1,7 +1,7 @@
 The MIT License (MIT)
 
 Copyright (c) 2016-2022 Florian Dehau
-Copyright (c) 2023 The Ratatui Developers
+Copyright (c) 2023-2024 The Ratatui Developers
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

Makefile.toml

@@ -7,11 +7,12 @@ skip_core_tasks = true
 # all features except the backend ones
 ALL_FEATURES = "all-widgets,macros,serde"
 
+[env.ALL_FEATURES_FLAG]
 # 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,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" } }
+source = "${CARGO_MAKE_RUST_TARGET_OS}"
+default_value = "--features=all-widgets,macros,serde,crossterm,termion,termwiz,underline-color,unstable"
+mapping = { "windows" = "--features=all-widgets,macros,serde,crossterm,termwiz,underline-color,unstable" }
 
 [tasks.default]
 alias = "ci"

README.md

@@ -25,10 +25,10 @@
 
 <div align="center">
 
-[![Crate Badge]][Crate] [![Docs Badge]][API Docs] [![CI Badge]][CI Workflow] [![License
-Badge]](./LICENSE)<br>
-[![Codecov Badge]][Codecov] [![Deps.rs Badge]][Deps.rs] [![Discord Badge]][Discord Server]
-[![Matrix Badge]][Matrix]<br>
+[![Crate Badge]][Crate] [![Docs Badge]][API Docs] [![CI Badge]][CI Workflow] [![Deps.rs
+Badge]][Deps.rs]<br> [![Codecov Badge]][Codecov] [![License Badge]](./LICENSE) [![Sponsors
+Badge]][GitHub Sponsors]<br> [![Discord Badge]][Discord Server] [![Matrix Badge]][Matrix]
+[![Forum Badge]][Forum]<br>
 
 [Ratatui Website] · [API Docs] · [Examples] · [Changelog] · [Breaking Changes]<br>
 [Contributing] · [Report a bug] · [Request a Feature] · [Create a Pull Request]
@@ -43,10 +43,10 @@ Ratatui was forked from the [tui-rs] crate in 2023 in order to continue its deve
 
 ## Installation
 
-Add `ratatui` and `crossterm` as dependencies to your cargo.toml:
+Add `ratatui` as a dependency to your cargo.toml:
 
 ```shell
-cargo add ratatui crossterm
+cargo add ratatui
 ```
 
 Ratatui uses [Crossterm] by default as it works on most platforms. See the [Installation]
@@ -61,9 +61,13 @@ This is in contrast to the retained mode style of rendering where widgets are up
 automatically redrawn on the next frame. See the [Rendering] section of the [Ratatui Website]
 for more info.
 
+You can also watch the [FOSDEM 2024 talk] about Ratatui which gives a brief introduction to
+terminal user interfaces and showcases the features of Ratatui, along with a hello world demo.
+
 ## Other documentation
 
 - [Ratatui Website] - explains the library's concepts and provides step-by-step tutorials
+- [Ratatui Forum][Forum] - a place to ask questions and discuss the library
 - [API Docs] - the full API documentation for the library on docs.rs.
 - [Examples] - a collection of examples that demonstrate how to use the library.
 - [Contributing] - Please read this if you are interested in contributing to the project.
@@ -107,7 +111,8 @@ module] and the [Backends] section of the [Ratatui Website] for more info.
 
 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]
+using the provided [`render_widget`] method. After this closure returns, a diff is performed and
+only the changes are drawn to the terminal. See the [Widgets] section of the [Ratatui Website]
 for more info.
 
 ### Handling events
@@ -122,12 +127,17 @@ Website] for more info. For example, if you are using [Crossterm], you can use t
 ```rust
 use std::io::{self, stdout};
 
-use crossterm::{
-    event::{self, Event, KeyCode},
-    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-    ExecutableCommand,
+use ratatui::{
+    crossterm::{
+        event::{self, Event, KeyCode},
+        terminal::{
+            disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen,
+        },
+        ExecutableCommand,
+    },
+    prelude::*,
+    widgets::*,
 };
-use ratatui::{prelude::*, widgets::*};
 
 fn main() -> io::Result<()> {
     enable_raw_mode()?;
@@ -158,8 +168,7 @@ fn handle_events() -> io::Result<bool> {
 
 fn ui(frame: &mut Frame) {
     frame.render_widget(
-        Paragraph::new("Hello World!")
-            .block(Block::default().title("Greeting").borders(Borders::ALL)),
+        Paragraph::new("Hello World!").block(Block::bordered().title("Greeting")),
         frame.size(),
     );
 }
@@ -203,14 +212,8 @@ fn ui(frame: &mut Frame) {
         [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],
-    );
+    frame.render_widget(Block::bordered().title("Left"), inner_layout[0]);
+    frame.render_widget(Block::bordered().title("Right"), inner_layout[1]);
 }
 ```
 
@@ -301,6 +304,7 @@ Running this example produces the following output:
 [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
+[FOSDEM 2024 talk]: https://www.youtube.com/watch?v=NU0q6NOLJ20
 [docsrs-hello]: https://github.com/ratatui-org/ratatui/blob/c3c3c289b1eb8d562afb1931adb4dc719cd48490/examples/docsrs-hello.png?raw=true
 [docsrs-layout]: https://github.com/ratatui-org/ratatui/blob/c3c3c289b1eb8d562afb1931adb4dc719cd48490/examples/docsrs-layout.png?raw=true
 [docsrs-styling]: https://github.com/ratatui-org/ratatui/blob/c3c3c289b1eb8d562afb1931adb4dc719cd48490/examples/docsrs-styling.png?raw=true
@@ -322,23 +326,23 @@ Running this example produces the following output:
 [Termion]: https://crates.io/crates/termion
 [Termwiz]: https://crates.io/crates/termwiz
 [tui-rs]: https://crates.io/crates/tui
-[Crate Badge]: https://img.shields.io/crates/v/ratatui?logo=rust&style=flat-square
-[License Badge]: https://img.shields.io/crates/l/ratatui?style=flat-square
-[CI Badge]:
-    https://img.shields.io/github/actions/workflow/status/ratatui-org/ratatui/ci.yml?style=flat-square&logo=github
+[GitHub Sponsors]: https://github.com/sponsors/ratatui-org
+[Crate Badge]: https://img.shields.io/crates/v/ratatui?logo=rust&style=flat-square&logoColor=E05D44&color=E05D44
+[License Badge]: https://img.shields.io/crates/l/ratatui?style=flat-square&color=1370D3
+[CI Badge]: https://img.shields.io/github/actions/workflow/status/ratatui-org/ratatui/ci.yml?style=flat-square&logo=github
 [CI Workflow]: https://github.com/ratatui-org/ratatui/actions/workflows/ci.yml
-[Codecov Badge]:
-    https://img.shields.io/codecov/c/github/ratatui-org/ratatui?logo=codecov&style=flat-square&token=BAQ8SOKEST
+[Codecov Badge]: https://img.shields.io/codecov/c/github/ratatui-org/ratatui?logo=codecov&style=flat-square&token=BAQ8SOKEST&color=C43AC3&logoColor=C43AC3
 [Codecov]: https://app.codecov.io/gh/ratatui-org/ratatui
 [Deps.rs Badge]: https://deps.rs/repo/github/ratatui-org/ratatui/status.svg?style=flat-square
 [Deps.rs]: https://deps.rs/repo/github/ratatui-org/ratatui
-[Discord Badge]:
-    https://img.shields.io/discord/1070692720437383208?label=discord&logo=discord&style=flat-square
+[Discord Badge]: https://img.shields.io/discord/1070692720437383208?label=discord&logo=discord&style=flat-square&color=1370D3&logoColor=1370D3
 [Discord Server]: https://discord.gg/pMCEU9hNEj
-[Docs Badge]: https://img.shields.io/docsrs/ratatui?logo=rust&style=flat-square
-[Matrix Badge]:
-    https://img.shields.io/matrix/ratatui-general%3Amatrix.org?style=flat-square&logo=matrix&label=Matrix
+[Docs Badge]: https://img.shields.io/docsrs/ratatui?logo=rust&style=flat-square&logoColor=E05D44
+[Matrix Badge]: https://img.shields.io/matrix/ratatui-general%3Amatrix.org?style=flat-square&logo=matrix&label=Matrix&color=C43AC3
 [Matrix]: https://matrix.to/#/#ratatui:matrix.org
+[Forum Badge]: https://img.shields.io/discourse/likes?server=https%3A%2F%2Fforum.ratatui.rs&style=flat-square&logo=discourse&label=forum&color=C43AC3
+[Forum]: https://forum.ratatui.rs
+[Sponsors Badge]: https://img.shields.io/github/sponsors/ratatui-org?logo=github&style=flat-square&color=1370D3
 
 <!-- cargo-rdme end -->
 
@@ -353,9 +357,10 @@ In order to organize ourselves, we currently use a [Discord server](https://disc
 feel free to join and come chat! There is also a [Matrix](https://matrix.org/) bridge available at
 [#ratatui:matrix.org](https://matrix.to/#/#ratatui:matrix.org).
 
-While we do utilize Discord for coordinating, it's not essential for contributing.
-Our primary open-source workflow is centered around GitHub.
-For significant discussions, we rely on GitHub — please open an issue, a discussion or a PR.
+While we do utilize Discord for coordinating, it's not essential for contributing. We have recently
+launched the [Ratatui Forum][Forum], and our primary open-source workflow is centered around GitHub.
+For bugs and features, we rely on GitHub. Please [Report a bug], [Request a Feature] or [Create a
+Pull Request].
 
 Please make sure you read the updated [contributing](./CONTRIBUTING.md) guidelines, especially if
 you are interested in working on a PR or issue opened in the previous repository.

bacon.toml

@@ -44,6 +44,16 @@ command = [
 ]
 need_stdout = true
 
+[jobs.test-unit]
+command = [
+    "cargo", "test",
+    "--lib",
+    "--all-features",
+    "--color", "always",
+    "--", "--color", "always", # see https://github.com/Canop/bacon/issues/124
+]
+need_stdout = true
+
 [jobs.doc]
 command = [
     "cargo", "+nightly", "doc",
@@ -74,7 +84,7 @@ on_success = "job:doc" # so that we don't open the browser at each change
 command = [
     "cargo", "llvm-cov",
     "--lcov", "--output-path", "target/lcov.info",
-    "--all-features", 
+    "--all-features",
     "--color", "always",
 ]
 
@@ -97,4 +107,6 @@ ctrl-c = "job:check-crossterm"
 ctrl-t = "job:check-termion"
 ctrl-w = "job:check-termwiz"
 v = "job:coverage"
-u = "job:coverage-unit-tests-only"
+ctrl-v = "job:coverage-unit-tests-only"
+u = "job:test-unit"
+n = "job:nextest"

benches/barchart.rs

@@ -8,7 +8,7 @@ use ratatui::{
 };
 
 /// Benchmark for rendering a barchart.
-pub fn barchart(c: &mut Criterion) {
+fn barchart(c: &mut Criterion) {
     let mut group = c.benchmark_group("barchart");
     let mut rng = rand::thread_rng();
 
@@ -66,7 +66,7 @@ fn render(bencher: &mut Bencher, barchart: &BarChart) {
             bench_barchart.render(buffer.area, &mut buffer);
         },
         criterion::BatchSize::LargeInput,
-    )
+    );
 }
 
 criterion_group!(benches, barchart);

benches/block.rs

@@ -1,44 +1,42 @@
-use criterion::{criterion_group, criterion_main, BatchSize, Bencher, BenchmarkId, Criterion};
+use criterion::{criterion_group, criterion_main, BatchSize, Bencher, Criterion};
 use ratatui::{
     buffer::Buffer,
-    layout::Rect,
-    prelude::Alignment,
+    layout::{Alignment, Rect},
     widgets::{
         block::{Position, Title},
-        Block, Borders, Padding, Widget,
+        Block, Padding, Widget,
     },
 };
 
 /// Benchmark for rendering a block.
-pub fn block(c: &mut Criterion) {
+fn block(c: &mut Criterion) {
     let mut group = c.benchmark_group("block");
 
-    for buffer_size in &[
-        Rect::new(0, 0, 100, 50),  // vertically split screen
-        Rect::new(0, 0, 200, 50),  // 1080p fullscreen with medium font
-        Rect::new(0, 0, 256, 256), // Max sized area
+    for (width, height) in [
+        (100, 50),  // vertically split screen
+        (200, 50),  // 1080p fullscreen with medium font
+        (256, 256), // Max sized area
     ] {
-        let buffer_area = buffer_size.area();
+        let buffer_size = Rect::new(0, 0, width, height);
 
         // Render an empty block
         group.bench_with_input(
-            BenchmarkId::new("render_empty", buffer_area),
+            format!("render_empty/{width}x{height}"),
             &Block::new(),
             |b, block| render(b, block, buffer_size),
         );
 
         // Render with all features
         group.bench_with_input(
-            BenchmarkId::new("render_all_feature", buffer_area),
-            &Block::new()
-                .borders(Borders::ALL)
+            format!("render_all_feature/{width}x{height}"),
+            &Block::bordered()
+                .padding(Padding::new(5, 5, 2, 2))
                 .title("test title")
                 .title(
                     Title::from("bottom left title")
                         .alignment(Alignment::Right)
                         .position(Position::Bottom),
-                )
-                .padding(Padding::new(5, 5, 2, 2)),
+                ),
             |b, block| render(b, block, buffer_size),
         );
     }
@@ -47,8 +45,8 @@ pub fn block(c: &mut Criterion) {
 }
 
 /// render the block into a buffer of the given `size`
-fn render(bencher: &mut Bencher, block: &Block, size: &Rect) {
-    let mut buffer = Buffer::empty(*size);
+fn render(bencher: &mut Bencher, block: &Block, size: Rect) {
+    let mut buffer = Buffer::empty(size);
     // We use `iter_batched` to clone the value in the setup function.
     // See https://github.com/ratatui-org/ratatui/pull/377.
     bencher.iter_batched(
@@ -57,7 +55,7 @@ fn render(bencher: &mut Bencher, block: &Block, size: &Rect) {
             bench_block.render(buffer.area, &mut buffer);
         },
         BatchSize::SmallInput,
-    )
+    );
 }
 
 criterion_group!(benches, block);

benches/line.rs

@@ -0,0 +1,39 @@
+use std::hint::black_box;
+
+use criterion::{criterion_group, criterion_main, Criterion};
+use ratatui::{
+    buffer::Buffer,
+    layout::{Alignment, Rect},
+    style::Stylize,
+    text::Line,
+    widgets::Widget,
+};
+
+fn line_render(criterion: &mut Criterion) {
+    for alignment in [Alignment::Left, Alignment::Center, Alignment::Right] {
+        let mut group = criterion.benchmark_group(format!("line_render/{alignment}"));
+        group.sample_size(1000);
+
+        let line = &Line::from(vec![
+            "This".red(),
+            " ".green(),
+            "is".italic(),
+            " ".blue(),
+            "SPARTA!!".bold(),
+        ])
+        .alignment(alignment);
+
+        for width in [0, 3, 4, 6, 7, 10, 42] {
+            let area = Rect::new(0, 0, width, 1);
+
+            group.bench_function(width.to_string(), |bencher| {
+                let mut buffer = Buffer::empty(area);
+                bencher.iter(|| black_box(line).render(area, &mut buffer));
+            });
+        }
+        group.finish();
+    }
+}
+
+criterion_group!(benches, line_render);
+criterion_main!(benches);

benches/list.rs

@@ -7,7 +7,7 @@ use ratatui::{
 
 /// Benchmark for rendering a list.
 /// It only benchmarks the render with a different amount of items.
-pub fn list(c: &mut Criterion) {
+fn list(c: &mut Criterion) {
     let mut group = c.benchmark_group("list");
 
     for line_count in [64, 2048, 16384] {
@@ -33,7 +33,7 @@ pub fn list(c: &mut Criterion) {
                     ListState::default()
                         .with_offset(line_count / 2)
                         .with_selected(Some(line_count / 2)),
-                )
+                );
             },
         );
     }
@@ -52,7 +52,7 @@ fn render(bencher: &mut Bencher, list: &List) {
             Widget::render(bench_list, buffer.area, &mut buffer);
         },
         BatchSize::LargeInput,
-    )
+    );
 }
 
 /// render the list into a common size buffer with a state
@@ -66,7 +66,7 @@ fn render_stateful(bencher: &mut Bencher, list: &List, mut state: ListState) {
             StatefulWidget::render(bench_list, buffer.area, &mut buffer, &mut state);
         },
         BatchSize::LargeInput,
-    )
+    );
 }
 
 criterion_group!(benches, list);

benches/paragraph.rs

@@ -17,15 +17,15 @@ const WRAP_WIDTH: u16 = 100;
 /// Benchmark for rendering a paragraph with a given number of lines. The design of this benchmark
 /// allows comparison of the performance of rendering a paragraph with different numbers of lines.
 /// as well as comparing with the various settings on the scroll and wrap features.
-pub fn paragraph(c: &mut Criterion) {
+fn paragraph(c: &mut Criterion) {
     let mut group = c.benchmark_group("paragraph");
-    for &line_count in [64, 2048, MAX_SCROLL_OFFSET].iter() {
+    for line_count in [64, 2048, MAX_SCROLL_OFFSET] {
         let lines = random_lines(line_count);
         let lines = lines.as_str();
 
         // benchmark that measures the overhead of creating a paragraph separately from rendering
         group.bench_with_input(BenchmarkId::new("new", line_count), lines, |b, lines| {
-            b.iter(|| Paragraph::new(black_box(lines)))
+            b.iter(|| Paragraph::new(black_box(lines)));
         });
 
         // render the paragraph with no scroll
@@ -38,14 +38,14 @@ pub fn paragraph(c: &mut Criterion) {
         // scroll the paragraph by half the number of lines and render
         group.bench_with_input(
             BenchmarkId::new("render_scroll_half", line_count),
-            &Paragraph::new(lines).scroll((0u16, line_count / 2)),
+            &Paragraph::new(lines).scroll((0, line_count / 2)),
             |bencher, paragraph| render(bencher, paragraph, NO_WRAP_WIDTH),
         );
 
         // scroll the paragraph by the full number of lines and render
         group.bench_with_input(
             BenchmarkId::new("render_scroll_full", line_count),
-            &Paragraph::new(lines).scroll((0u16, line_count)),
+            &Paragraph::new(lines).scroll((0, line_count)),
             |bencher, paragraph| render(bencher, paragraph, NO_WRAP_WIDTH),
         );
 
@@ -61,7 +61,7 @@ pub fn paragraph(c: &mut Criterion) {
             BenchmarkId::new("render_wrap_scroll_full", line_count),
             &Paragraph::new(lines)
                 .wrap(Wrap { trim: false })
-                .scroll((0u16, line_count)),
+                .scroll((0, line_count)),
             |bencher, paragraph| render(bencher, paragraph, WRAP_WIDTH),
         );
     }
@@ -79,7 +79,7 @@ fn render(bencher: &mut Bencher, paragraph: &Paragraph, width: u16) {
             bench_paragraph.render(buffer.area, &mut buffer);
         },
         BatchSize::LargeInput,
-    )
+    );
 }
 
 /// Create a string with the given number of lines filled with nonsense words
@@ -87,7 +87,7 @@ fn render(bencher: &mut Bencher, paragraph: &Paragraph, width: u16) {
 /// English language has about 5.1 average characters per word so including the space between words
 /// this should emit around 200 characters per paragraph on average.
 fn random_lines(count: u16) -> String {
-    let count = count as i64;
+    let count = i64::from(count);
     let sentence_count = 3;
     let word_count = 11;
     fakeit::words::paragraph(count, sentence_count, word_count, "\n".into())

benches/sparkline.rs

@@ -7,7 +7,7 @@ use ratatui::{
 };
 
 /// Benchmark for rendering a sparkline.
-pub fn sparkline(c: &mut Criterion) {
+fn sparkline(c: &mut Criterion) {
     let mut group = c.benchmark_group("sparkline");
     let mut rng = rand::thread_rng();
 
@@ -38,7 +38,7 @@ fn render(bencher: &mut Bencher, sparkline: &Sparkline) {
             bench_sparkline.render(buffer.area, &mut buffer);
         },
         criterion::BatchSize::LargeInput,
-    )
+    );
 }
 
 criterion_group!(benches, sparkline);

cliff.toml

@@ -1,4 +1,9 @@
-# configuration for https://github.com/orhun/git-cliff
+# git-cliff ~ configuration file
+# https://git-cliff.org/docs/configuration
+
+[remote.github]
+owner = "ratatui-org"
+repo = "ratatui"
 
 [changelog]
 # changelog header
@@ -21,8 +26,10 @@ body = """
 {% endif -%}
 
 {% macro commit(commit) -%}
-- [{{ commit.id | truncate(length=7, end="") }}]({{ "https://github.com/ratatui-org/ratatui/commit/" ~ commit.id }})
-  *({{commit.scope | default(value = "uncategorized") | lower }})* {{ commit.message | upper_first }}
+- [{{ commit.id | truncate(length=7, end="") }}]({{ "https://github.com/ratatui-org/ratatui/commit/" ~ commit.id }}) \
+  *({{commit.scope | default(value = "uncategorized") | lower }})* {{ commit.message | upper_first | trim }}\
+  {% if commit.github.username %} by @{{ commit.github.username }}{%- endif -%}\
+  {% if commit.github.pr_number %} in [#{{ commit.github.pr_number }}]({{ self::remote_url() }}/pull/{{ commit.github.pr_number }}){%- endif %}\
 {%- if commit.breaking %} [**breaking**]{% endif %}
 {%- if commit.body %}
 
@@ -33,8 +40,7 @@ body = """
 {%- for footer in commit.footers %}
 {%- if footer.token != "Signed-off-by" and footer.token != "Co-authored-by" %}
 
-  {{ footer.token | indent(prefix="  ") }}{{ footer.separator }}
-  {{ footer.value | indent(prefix="  ") }}
+  {{ footer.token | indent(prefix="  ") }}{{ footer.separator }}{{ footer.value }}
 {%- endif %}
 {%- endfor %}
 {% endmacro -%}
@@ -50,6 +56,28 @@ body = """
 {%- endif -%}
 {%- endfor -%}
 {%- endfor %}
+
+{% if github.contributors | filter(attribute="is_first_time", value=true) | length != 0 %}
+### New Contributors
+{%- endif %}\
+{% for contributor in github.contributors | filter(attribute="is_first_time", value=true) %}
+* @{{ contributor.username }} made their first contribution
+{%- if contributor.pr_number %} in \
+[#{{ contributor.pr_number }}]({{ self::remote_url() }}/pull/{{ contributor.pr_number }}) \
+{%- endif %}
+{%- endfor -%}
+
+{% if version %}
+{% if previous.version %}
+**Full Changelog**: {{ self::remote_url() }}/compare/{{ previous.version }}...{{ version }}
+{% endif %}
+{% else -%}
+  {% raw %}\n{% endraw %}
+{% endif %}
+
+{%- macro remote_url() -%}
+https://github.com/{{ remote.github.owner }}/{{ remote.github.repo }}\
+{% endmacro %}
 """
 
 
@@ -69,7 +97,7 @@ filter_unconventional = true
 split_commits = false
 # regex for preprocessing the commit messages
 commit_preprocessors = [
-  { pattern = '\((\w+\s)?#([0-9]+)\)', replace = "([#${2}](https://github.com/ratatui-org/ratatui/issues/${2}))" },
+  { pattern = '\((\w+\s)?#([0-9]+)\)', replace = "" },
   { pattern = '(better safe shared layout cache)', replace = "perf(layout): ${1}" },
   { pattern = '(Clarify README.md)', replace = "docs(readme): ${1}" },
   { pattern = '(Update README.md)', replace = "docs(readme): ${1}" },

clippy.toml

@@ -0,0 +1,17 @@
+avoid-breaking-exported-api = false
+
+# https://rust-lang.github.io/rust-clippy/master/index.html#/multiple_crate_versions
+# ratatui -> bitflags v2.3
+# termwiz -> wezterm-blob-leases -> mac_address -> nix -> bitflags v1.3.2
+# crossterm -> all the windows- deps https://github.com/ratatui-org/ratatui/pull/1064#issuecomment-2078848980
+allowed-duplicate-crates = [
+    "bitflags",
+    "windows-targets",
+    "windows_aarch64_gnullvm",
+    "windows_aarch64_msvc",
+    "windows_i686_gnu",
+    "windows_i686_msvc",
+    "windows_x86_64_gnu",
+    "windows_x86_64_gnullvm",
+    "windows_x86_64_msvc",
+]

examples/README.md

@@ -1,20 +1,20 @@
 # Examples
 
-This folder contains unreleased code. View the [examples for the latest release
-(0.25.0)](https://github.com/ratatui-org/ratatui/tree/v0.25.0/examples) instead.
+This folder might use unreleased code. View the examples for the latest release instead.
 
 > [!WARNING]
 >
-> There are backwards incompatible changes in these examples, as they are designed to compile
+> There may be backwards incompatible changes in these examples, as they are designed to compile
 > against the `main` branch.
 >
 > There are a few workaround for this problem:
 >
 > - View the examples as they were when the latest version was release by selecting the tag that
->   matches that version. E.g. <https://github.com/ratatui-org/ratatui/tree/v0.25.0/examples>. There
->   is a combo box at the top of this page which allows you to select any previous tagged version.
-> - To view the code locally, checkout the tag using `git switch --detach v0.25.0`.
-> - Use the latest [alpha version of Ratatui]. These are released weekly on Saturdays.
+>   matches that version. E.g. <https://github.com/ratatui-org/ratatui/tree/v0.26.1/examples>.
+> - If you're viewing this file on GitHub, there is a combo box at the top of this page  which
+>   allows you to select any previous tagged version.
+> - To view the code locally, checkout the tag. E.g. `git switch --detach v0.26.1`.
+> - Use the latest [alpha version of Ratatui] in your app. These are released weekly on Saturdays.
 > - Compile your code against the main branch either locally by adding e.g. `path = "../ratatui"` to
 >   the dependency, or remotely by adding `git = "https://github.com/ratatui-org/ratatui"`
 >
@@ -164,6 +164,18 @@ cargo run --example=gauge --features=crossterm
 
 ![Gauge][gauge.gif]
 
+## Line Gauge
+
+Demonstrates the [`Line
+Gauge`](https://docs.rs/ratatui/latest/ratatui/widgets/struct.LineGauge.html) widget. Source:
+[line_gauge.rs](./line_gauge.rs).
+
+```shell
+cargo run --example=line_gauge --features=crossterm
+```
+
+![LineGauge][line_gauge.gif]
+
 ## Inline
 
 Demonstrates how to use the
@@ -328,7 +340,7 @@ Links to images to make them easier to update in bulk. Use the following script
 the examples to the images branch. (Requires push access to the branch).
 
 ```shell
-examples/generate.bash
+examples/vhs/generate.bash
 ```
 -->
 
@@ -346,6 +358,7 @@ examples/generate.bash
 [inline.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/inline.gif?raw=true
 [layout.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/layout.gif?raw=true
 [list.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/list.gif?raw=true
+[line_gauge.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/line_gauge.gif?raw=true
 [modifiers.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/modifiers.gif?raw=true
 [panic.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/panic.gif?raw=true
 [paragraph.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/paragraph.gif?raw=true

examples/barchart.rs

@@ -1,15 +1,37 @@
+//! # [Ratatui] `BarChart` example
+//!
+//! The latest version of this example is available in the [examples] folder in the repository.
+//!
+//! Please note that the examples are designed to be run against the `main` branch of the Github
+//! repository. This means that you may not be able to compile with the latest release version on
+//! crates.io, or the one that you have installed locally.
+//!
+//! See the [examples readme] for more information on finding examples that match the version of the
+//! library you are using.
+//!
+//! [Ratatui]: https://github.com/ratatui-org/ratatui
+//! [examples]: https://github.com/ratatui-org/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui-org/ratatui/blob/main/examples/README.md
+
 use std::{
     error::Error,
     io,
     time::{Duration, Instant},
 };
 
-use crossterm::{
-    event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode},
-    execute,
-    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+use ratatui::{
+    backend::{Backend, CrosstermBackend},
+    crossterm::{
+        event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode},
+        execute,
+        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+    },
+    layout::{Constraint, Direction, Layout, Rect},
+    style::{Color, Modifier, Style},
+    terminal::{Frame, Terminal},
+    text::{Line, Span},
+    widgets::{Bar, BarChart, BarGroup, Block, Paragraph},
 };
-use ratatui::{prelude::*, widgets::*};
 
 struct Company<'a> {
     revenue: [u64; 4],
@@ -26,7 +48,7 @@ struct App<'a> {
 const TOTAL_REVENUE: &str = "Total Revenue";
 
 impl<'a> App<'a> {
-    fn new() -> App<'a> {
+    fn new() -> Self {
         App {
             data: vec![
                 ("B1", 9),
@@ -122,7 +144,7 @@ fn run_app<B: Backend>(
         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 {
+                if key.code == KeyCode::Char('q') {
                     return Ok(());
                 }
             }
@@ -137,11 +159,11 @@ fn run_app<B: Backend>(
 fn ui(frame: &mut Frame, app: &App) {
     let vertical = Layout::vertical([Constraint::Ratio(1, 3), Constraint::Ratio(2, 3)]);
     let horizontal = Layout::horizontal([Constraint::Percentage(50), Constraint::Percentage(50)]);
-    let [top, bottom] = frame.size().split(&vertical);
-    let [left, right] = bottom.split(&horizontal);
+    let [top, bottom] = vertical.areas(frame.size());
+    let [left, right] = horizontal.areas(bottom);
 
     let barchart = BarChart::default()
-        .block(Block::default().title("Data1").borders(Borders::ALL))
+        .block(Block::bordered().title("Data1"))
         .data(&app.data)
         .bar_width(9)
         .bar_style(Style::default().fg(Color::Yellow))
@@ -152,6 +174,7 @@ fn ui(frame: &mut Frame, app: &App) {
     draw_horizontal_bars(frame, app, right);
 }
 
+#[allow(clippy::cast_precision_loss)]
 fn create_groups<'a>(app: &'a App, combine_values_and_labels: bool) -> Vec<BarGroup<'a>> {
     app.months
         .iter()
@@ -185,27 +208,29 @@ fn create_groups<'a>(app: &'a App, combine_values_and_labels: bool) -> Vec<BarGr
                 })
                 .collect();
             BarGroup::default()
-                .label(Line::from(month).alignment(Alignment::Center))
+                .label(Line::from(month).centered())
                 .bars(&bars)
         })
         .collect()
 }
 
+#[allow(clippy::cast_possible_truncation)]
 fn draw_bar_with_group_labels(f: &mut Frame, app: &App, area: Rect) {
+    const LEGEND_HEIGHT: u16 = 6;
+
     let groups = create_groups(app, false);
 
     let mut barchart = BarChart::default()
-        .block(Block::default().title("Data1").borders(Borders::ALL))
+        .block(Block::bordered().title("Data1"))
         .bar_width(7)
         .group_gap(3);
 
     for group in groups {
-        barchart = barchart.data(group)
+        barchart = barchart.data(group);
     }
 
     f.render_widget(barchart, area);
 
-    const LEGEND_HEIGHT: u16 = 6;
     if area.height >= LEGEND_HEIGHT && area.width >= TOTAL_REVENUE.len() as u16 + 2 {
         let legend_width = TOTAL_REVENUE.len() as u16 + 2;
         let legend_area = Rect {
@@ -218,23 +243,25 @@ fn draw_bar_with_group_labels(f: &mut Frame, app: &App, area: Rect) {
     }
 }
 
+#[allow(clippy::cast_possible_truncation)]
 fn draw_horizontal_bars(f: &mut Frame, app: &App, area: Rect) {
+    const LEGEND_HEIGHT: u16 = 6;
+
     let groups = create_groups(app, true);
 
     let mut barchart = BarChart::default()
-        .block(Block::default().title("Data1").borders(Borders::ALL))
+        .block(Block::bordered().title("Data1"))
         .bar_width(1)
         .group_gap(1)
         .bar_gap(0)
         .direction(Direction::Horizontal);
 
     for group in groups {
-        barchart = barchart.data(group)
+        barchart = barchart.data(group);
     }
 
     f.render_widget(barchart, area);
 
-    const LEGEND_HEIGHT: u16 = 6;
     if area.height >= LEGEND_HEIGHT && area.width >= TOTAL_REVENUE.len() as u16 + 2 {
         let legend_width = TOTAL_REVENUE.len() as u16 + 2;
         let legend_area = Rect {
@@ -263,15 +290,13 @@ fn draw_legend(f: &mut Frame, area: Rect) {
             "- Company B",
             Style::default().fg(Color::Yellow),
         )),
-        Line::from(vec![Span::styled(
+        Line::from(Span::styled(
             "- Company C",
             Style::default().fg(Color::White),
-        )]),
+        )),
     ];
 
-    let block = Block::default()
-        .borders(Borders::ALL)
-        .style(Style::default().fg(Color::White));
+    let block = Block::bordered().style(Style::default().fg(Color::White));
     let paragraph = Paragraph::new(text).block(block);
     f.render_widget(paragraph, area);
 }

examples/block.rs

@@ -1,3 +1,18 @@
+//! # [Ratatui] Block example
+//!
+//! The latest version of this example is available in the [examples] folder in the repository.
+//!
+//! Please note that the examples are designed to be run against the `main` branch of the Github
+//! repository. This means that you may not be able to compile with the latest release version on
+//! crates.io, or the one that you have installed locally.
+//!
+//! See the [examples readme] for more information on finding examples that match the version of the
+//! library you are using.
+//!
+//! [Ratatui]: https://github.com/ratatui-org/ratatui
+//! [examples]: https://github.com/ratatui-org/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui-org/ratatui/blob/main/examples/README.md
+
 use std::{
     error::Error,
     io::{stdout, Stdout},
@@ -5,14 +20,18 @@ use std::{
     time::Duration,
 };
 
-use crossterm::{
-    event::{self, Event, KeyCode},
-    execute,
-    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-};
 use itertools::Itertools;
 use ratatui::{
-    prelude::*,
+    backend::CrosstermBackend,
+    crossterm::{
+        event::{self, Event, KeyCode},
+        execute,
+        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+    },
+    layout::{Alignment, Constraint, Layout, Rect},
+    style::{Style, Stylize},
+    terminal::Frame,
+    text::Line,
     widgets::{
         block::{Position, Title},
         Block, BorderType, Borders, Padding, Paragraph, Wrap,
@@ -62,7 +81,7 @@ fn run(terminal: &mut Terminal) -> Result<()> {
 fn handle_events() -> Result<ControlFlow<()>> {
     if event::poll(Duration::from_millis(100))? {
         if let Event::Key(key) = event::read()? {
-            if let KeyCode::Char('q') = key.code {
+            if key.code == KeyCode::Char('q') {
                 return Ok(ControlFlow::Break(()));
             }
         }
@@ -104,8 +123,8 @@ fn ui(frame: &mut Frame) {
 /// Returns a tuple of the title area and the main areas.
 fn calculate_layout(area: Rect) -> (Rect, Vec<Vec<Rect>>) {
     let main_layout = Layout::vertical([Constraint::Length(1), Constraint::Min(0)]);
-    let block_layout = &Layout::vertical([Constraint::Max(4); 9]);
-    let [title_area, main_area] = area.split(&main_layout);
+    let block_layout = Layout::vertical([Constraint::Max(4); 9]);
+    let [title_area, main_area] = main_layout.areas(area);
     let main_areas = block_layout
         .split(main_area)
         .iter()
@@ -135,7 +154,7 @@ fn placeholder_paragraph() -> Paragraph<'static> {
 fn render_borders(paragraph: &Paragraph, border: Borders, frame: &mut Frame, area: Rect) {
     let block = Block::new()
         .borders(border)
-        .title(format!("Borders::{border:#?}", border = border));
+        .title(format!("Borders::{border:#?}"));
     frame.render_widget(paragraph.clone().block(block), area);
 }
 
@@ -145,23 +164,20 @@ fn render_border_type(
     frame: &mut Frame,
     area: Rect,
 ) {
-    let block = Block::new()
-        .borders(Borders::ALL)
+    let block = Block::bordered()
         .border_type(border_type)
         .title(format!("BorderType::{border_type:#?}"));
     frame.render_widget(paragraph.clone().block(block), area);
 }
 fn render_styled_borders(paragraph: &Paragraph, frame: &mut Frame, area: Rect) {
-    let block = Block::new()
-        .borders(Borders::ALL)
+    let block = Block::bordered()
         .border_style(Style::new().blue().on_white().bold().italic())
         .title("Styled borders");
     frame.render_widget(paragraph.clone().block(block), area);
 }
 
 fn render_styled_block(paragraph: &Paragraph, frame: &mut Frame, area: Rect) {
-    let block = Block::new()
-        .borders(Borders::ALL)
+    let block = Block::bordered()
         .style(Style::new().blue().on_white().bold().italic())
         .title("Styled block");
     frame.render_widget(paragraph.clone().block(block), area);
@@ -169,8 +185,7 @@ fn render_styled_block(paragraph: &Paragraph, frame: &mut Frame, area: Rect) {
 
 // Note: this currently renders incorrectly, see https://github.com/ratatui-org/ratatui/issues/349
 fn render_styled_title(paragraph: &Paragraph, frame: &mut Frame, area: Rect) {
-    let block = Block::new()
-        .borders(Borders::ALL)
+    let block = Block::bordered()
         .title("Styled title")
         .title_style(Style::new().blue().on_white().bold().italic());
     frame.render_widget(paragraph.clone().block(block), area);
@@ -181,21 +196,19 @@ fn render_styled_title_content(paragraph: &Paragraph, frame: &mut Frame, area: R
         "Styled ".blue().on_white().bold().italic(),
         "title content".red().on_white().bold().italic(),
     ]);
-    let block = Block::new().borders(Borders::ALL).title(title);
+    let block = Block::bordered().title(title);
     frame.render_widget(paragraph.clone().block(block), area);
 }
 
 fn render_multiple_titles(paragraph: &Paragraph, frame: &mut Frame, area: Rect) {
-    let block = Block::new()
-        .borders(Borders::ALL)
+    let block = Block::bordered()
         .title("Multiple".blue().on_white().bold().italic())
         .title("Titles".red().on_white().bold().italic());
     frame.render_widget(paragraph.clone().block(block), area);
 }
 
 fn render_multiple_title_positions(paragraph: &Paragraph, frame: &mut Frame, area: Rect) {
-    let block = Block::new()
-        .borders(Borders::ALL)
+    let block = Block::bordered()
         .title(
             Title::from("top left")
                 .position(Position::Top)
@@ -230,16 +243,15 @@ fn render_multiple_title_positions(paragraph: &Paragraph, frame: &mut Frame, are
 }
 
 fn render_padding(paragraph: &Paragraph, frame: &mut Frame, area: Rect) {
-    let block = Block::new()
-        .borders(Borders::ALL)
-        .title("Padding")
-        .padding(Padding::new(5, 10, 1, 2));
+    let block = Block::bordered()
+        .padding(Padding::new(5, 10, 1, 2))
+        .title("Padding");
     frame.render_widget(paragraph.clone().block(block), area);
 }
 
 fn render_nested_blocks(paragraph: &Paragraph, frame: &mut Frame, area: Rect) {
-    let outer_block = Block::new().borders(Borders::ALL).title("Outer block");
-    let inner_block = Block::new().borders(Borders::ALL).title("Inner block");
+    let outer_block = Block::bordered().title("Outer block");
+    let inner_block = Block::bordered().title("Inner block");
     let inner = outer_block.inner(area);
     frame.render_widget(outer_block, area);
     frame.render_widget(paragraph.clone().block(inner_block), inner);

examples/calendar.rs

@@ -1,11 +1,32 @@
+//! # [Ratatui] Calendar example
+//!
+//! The latest version of this example is available in the [examples] folder in the repository.
+//!
+//! Please note that the examples are designed to be run against the `main` branch of the Github
+//! repository. This means that you may not be able to compile with the latest release version on
+//! crates.io, or the one that you have installed locally.
+//!
+//! See the [examples readme] for more information on finding examples that match the version of the
+//! library you are using.
+//!
+//! [Ratatui]: https://github.com/ratatui-org/ratatui
+//! [examples]: https://github.com/ratatui-org/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui-org/ratatui/blob/main/examples/README.md
+
 use std::{error::Error, io};
 
-use crossterm::{
-    event::{self, Event, KeyCode},
-    execute,
-    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+use ratatui::{
+    backend::CrosstermBackend,
+    crossterm::{
+        event::{self, Event, KeyCode},
+        execute,
+        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+    },
+    layout::{Constraint, Layout, Rect},
+    style::{Color, Modifier, Style},
+    widgets::calendar::{CalendarEventStore, DateStyler, Monthly},
+    Frame, Terminal,
 };
-use ratatui::{prelude::*, widgets::calendar::*};
 use time::{Date, Month, OffsetDateTime};
 
 fn main() -> Result<(), Box<dyn Error>> {
@@ -35,8 +56,8 @@ fn main() -> Result<(), Box<dyn Error>> {
     Ok(())
 }
 
-fn draw(f: &mut Frame) {
-    let app_area = f.size();
+fn draw(frame: &mut Frame) {
+    let app_area = frame.size();
 
     let calarea = Rect {
         x: app_area.x + 1,
@@ -63,7 +84,7 @@ fn draw(f: &mut Frame) {
     });
     for col in cols {
         let cal = cals::get_cal(start.month(), start.year(), &list);
-        f.render_widget(cal, col);
+        frame.render_widget(cal, col);
         start = start.replace_month(start.month().next()).unwrap();
     }
 }
@@ -149,17 +170,16 @@ fn make_dates(current_year: i32) -> CalendarEventStore {
 }
 
 mod cals {
+    #[allow(clippy::wildcard_imports)]
     use super::*;
 
-    pub(super) fn get_cal<'a, DS: DateStyler>(m: Month, y: i32, es: DS) -> Monthly<'a, DS> {
-        use Month::*;
+    pub fn get_cal<'a, DS: DateStyler>(m: Month, y: i32, es: DS) -> Monthly<'a, DS> {
         match m {
-            May => example1(m, y, es),
-            June => example2(m, y, es),
-            July => example3(m, y, es),
-            December => example3(m, y, es),
-            February => example4(m, y, es),
-            November => example5(m, y, es),
+            Month::May => example1(m, y, es),
+            Month::June => example2(m, y, es),
+            Month::July | Month::December => example3(m, y, es),
+            Month::February => example4(m, y, es),
+            Month::November => example5(m, y, es),
             _ => default(m, y, es),
         }
     }

examples/canvas.rs

@@ -1,16 +1,38 @@
+//! # [Ratatui] Canvas example
+//!
+//! The latest version of this example is available in the [examples] folder in the repository.
+//!
+//! Please note that the examples are designed to be run against the `main` branch of the Github
+//! repository. This means that you may not be able to compile with the latest release version on
+//! crates.io, or the one that you have installed locally.
+//!
+//! See the [examples readme] for more information on finding examples that match the version of the
+//! library you are using.
+//!
+//! [Ratatui]: https://github.com/ratatui-org/ratatui
+//! [examples]: https://github.com/ratatui-org/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui-org/ratatui/blob/main/examples/README.md
+
 use std::{
     io::{self, stdout, Stdout},
     time::{Duration, Instant},
 };
 
-use crossterm::{
-    event::{self, Event, KeyCode},
-    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-    ExecutableCommand,
-};
 use ratatui::{
-    prelude::*,
-    widgets::{canvas::*, *},
+    backend::CrosstermBackend,
+    crossterm::{
+        event::{self, Event, KeyCode},
+        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+        ExecutableCommand,
+    },
+    layout::{Constraint, Layout, Rect},
+    style::{Color, Stylize},
+    symbols::Marker,
+    terminal::{Frame, Terminal},
+    widgets::{
+        canvas::{Canvas, Circle, Map, MapResolution, Rectangle},
+        Block, Widget,
+    },
 };
 
 fn main() -> io::Result<()> {
@@ -29,8 +51,8 @@ struct App {
 }
 
 impl App {
-    fn new() -> App {
-        App {
+    fn new() -> Self {
+        Self {
             x: 0.0,
             y: 0.0,
             ball: Circle {
@@ -49,7 +71,7 @@ impl App {
 
     pub fn run() -> io::Result<()> {
         let mut terminal = init_terminal()?;
-        let mut app = App::new();
+        let mut app = Self::new();
         let mut last_tick = Instant::now();
         let tick_rate = Duration::from_millis(16);
         loop {
@@ -91,13 +113,13 @@ impl App {
         // 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
+        if ball.x - ball.radius < f64::from(playground.left())
+            || ball.x + ball.radius > f64::from(playground.right())
         {
             self.vx = -self.vx;
         }
-        if ball.y - ball.radius < playground.top() as f64
-            || ball.y + ball.radius > playground.bottom() as f64
+        if ball.y - ball.radius < f64::from(playground.top())
+            || ball.y + ball.radius > f64::from(playground.bottom())
         {
             self.vy = -self.vy;
         }
@@ -110,8 +132,8 @@ impl App {
         let horizontal =
             Layout::horizontal([Constraint::Percentage(50), Constraint::Percentage(50)]);
         let vertical = Layout::vertical([Constraint::Percentage(50), Constraint::Percentage(50)]);
-        let [map, right] = frame.size().split(&horizontal);
-        let [pong, boxes] = right.split(&vertical);
+        let [map, right] = horizontal.areas(frame.size());
+        let [pong, boxes] = vertical.areas(right);
 
         frame.render_widget(self.map_canvas(), map);
         frame.render_widget(self.pong_canvas(), pong);
@@ -120,7 +142,7 @@ impl App {
 
     fn map_canvas(&self) -> impl Widget + '_ {
         Canvas::default()
-            .block(Block::default().borders(Borders::ALL).title("World"))
+            .block(Block::bordered().title("World"))
             .marker(self.marker)
             .paint(|ctx| {
                 ctx.draw(&Map {
@@ -135,7 +157,7 @@ impl App {
 
     fn pong_canvas(&self) -> impl Widget + '_ {
         Canvas::default()
-            .block(Block::default().borders(Borders::ALL).title("Pong"))
+            .block(Block::bordered().title("Pong"))
             .marker(self.marker)
             .paint(|ctx| {
                 ctx.draw(&self.ball);
@@ -145,36 +167,38 @@ impl App {
     }
 
     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);
+        let left = 0.0;
+        let right = f64::from(area.width);
+        let bottom = 0.0;
+        let top = f64::from(area.height).mul_add(2.0, -4.0);
         Canvas::default()
-            .block(Block::default().borders(Borders::ALL).title("Rects"))
+            .block(Block::bordered().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,
+                        x: f64::from(i * i + 3 * i) / 2.0 + 2.0,
                         y: 2.0,
-                        width: i as f64,
-                        height: i as f64,
+                        width: f64::from(i),
+                        height: f64::from(i),
                         color: Color::Red,
                     });
                     ctx.draw(&Rectangle {
-                        x: (i * i + 3 * i) as f64 / 2.0 + 2.0,
+                        x: f64::from(i * i + 3 * i) / 2.0 + 2.0,
                         y: 21.0,
-                        width: i as f64,
-                        height: i as f64,
+                        width: f64::from(i),
+                        height: f64::from(i),
                         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));
+                        ctx.print(f64::from(i) + 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));
+                        ctx.print(0.0, f64::from(i), format!("{i}", i = i % 10));
                     }
                 }
             })

examples/chart.rs

@@ -1,21 +1,41 @@
+//! # [Ratatui] Chart example
+//!
+//! The latest version of this example is available in the [examples] folder in the repository.
+//!
+//! Please note that the examples are designed to be run against the `main` branch of the Github
+//! repository. This means that you may not be able to compile with the latest release version on
+//! crates.io, or the one that you have installed locally.
+//!
+//! See the [examples readme] for more information on finding examples that match the version of the
+//! library you are using.
+//!
+//! [Ratatui]: https://github.com/ratatui-org/ratatui
+//! [examples]: https://github.com/ratatui-org/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui-org/ratatui/blob/main/examples/README.md
+
 use std::{
     error::Error,
     io,
     time::{Duration, Instant},
 };
 
-use crossterm::{
-    event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode},
-    execute,
-    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-};
 use ratatui::{
-    prelude::*,
-    widgets::{block::Title, *},
+    backend::{Backend, CrosstermBackend},
+    crossterm::{
+        event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode},
+        execute,
+        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+    },
+    layout::{Alignment, Constraint, Layout, Rect},
+    style::{Color, Modifier, Style, Stylize},
+    symbols::{self, Marker},
+    terminal::{Frame, Terminal},
+    text::Span,
+    widgets::{block::Title, Axis, Block, Chart, Dataset, GraphType, LegendPosition},
 };
 
 #[derive(Clone)]
-pub struct SinSignal {
+struct SinSignal {
     x: f64,
     interval: f64,
     period: f64,
@@ -23,8 +43,8 @@ pub struct SinSignal {
 }
 
 impl SinSignal {
-    pub fn new(interval: f64, period: f64, scale: f64) -> SinSignal {
-        SinSignal {
+    const fn new(interval: f64, period: f64, scale: f64) -> Self {
+        Self {
             x: 0.0,
             interval,
             period,
@@ -51,12 +71,12 @@ struct App {
 }
 
 impl App {
-    fn new() -> App {
+    fn new() -> Self {
         let mut signal1 = SinSignal::new(0.2, 3.0, 18.0);
         let mut signal2 = SinSignal::new(0.1, 2.0, 10.0);
         let data1 = signal1.by_ref().take(200).collect::<Vec<(f64, f64)>>();
         let data2 = signal2.by_ref().take(200).collect::<Vec<(f64, f64)>>();
-        App {
+        Self {
             signal1,
             data1,
             signal2,
@@ -66,14 +86,12 @@ impl App {
     }
 
     fn on_tick(&mut self) {
-        for _ in 0..5 {
-            self.data1.remove(0);
-        }
+        self.data1.drain(0..5);
         self.data1.extend(self.signal1.by_ref().take(5));
-        for _ in 0..10 {
-            self.data2.remove(0);
-        }
+
+        self.data2.drain(0..10);
         self.data2.extend(self.signal2.by_ref().take(10));
+
         self.window[0] += 1.0;
         self.window[1] += 1.0;
     }
@@ -120,7 +138,7 @@ fn run_app<B: Backend>(
         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 {
+                if key.code == KeyCode::Char('q') {
                     return Ok(());
                 }
             }
@@ -137,8 +155,8 @@ fn ui(frame: &mut Frame, app: &App) {
 
     let vertical = Layout::vertical([Constraint::Percentage(40), Constraint::Percentage(60)]);
     let horizontal = Layout::horizontal([Constraint::Ratio(1, 2), Constraint::Ratio(1, 2)]);
-    let [chart1, bottom] = area.split(&vertical);
-    let [line_chart, scatter] = bottom.split(&horizontal);
+    let [chart1, bottom] = vertical.areas(area);
+    let [line_chart, scatter] = horizontal.areas(bottom);
 
     render_chart1(frame, chart1, app);
     render_line_chart(frame, line_chart);
@@ -171,11 +189,7 @@ fn render_chart1(f: &mut Frame, area: Rect, app: &App) {
     ];
 
     let chart = Chart::new(datasets)
-        .block(
-            Block::default()
-                .title("Chart 1".cyan().bold())
-                .borders(Borders::ALL),
-        )
+        .block(Block::bordered().title("Chart 1".cyan().bold()))
         .x_axis(
             Axis::default()
                 .title("X Axis")
@@ -204,13 +218,11 @@ fn render_line_chart(f: &mut Frame, area: Rect) {
 
     let chart = Chart::new(datasets)
         .block(
-            Block::default()
-                .title(
-                    Title::default()
-                        .content("Line chart".cyan().bold())
-                        .alignment(Alignment::Center),
-                )
-                .borders(Borders::ALL),
+            Block::bordered().title(
+                Title::default()
+                    .content("Line chart".cyan().bold())
+                    .alignment(Alignment::Center),
+            ),
         )
         .x_axis(
             Axis::default()
@@ -229,7 +241,7 @@ fn render_line_chart(f: &mut Frame, area: Rect) {
         .legend_position(Some(LegendPosition::TopLeft))
         .hidden_legend_constraints((Constraint::Ratio(1, 2), Constraint::Ratio(1, 2)));
 
-    f.render_widget(chart, area)
+    f.render_widget(chart, area);
 }
 
 fn render_scatter(f: &mut Frame, area: Rect) {
@@ -256,7 +268,7 @@ fn render_scatter(f: &mut Frame, area: Rect) {
 
     let chart = Chart::new(datasets)
         .block(
-            Block::new().borders(Borders::all()).title(
+            Block::bordered().title(
                 Title::default()
                     .content("Scatter chart".cyan().bold())
                     .alignment(Alignment::Center),
@@ -297,7 +309,7 @@ const HEAVY_PAYLOAD_DATA: [(f64, f64); 9] = [
 const MEDIUM_PAYLOAD_DATA: [(f64, f64); 29] = [
     (1963., 29500.),
     (1964., 30600.),
-    (1965., 177900.),
+    (1965., 177_900.),
     (1965., 21000.),
     (1966., 17900.),
     (1966., 8400.),
@@ -327,7 +339,7 @@ const MEDIUM_PAYLOAD_DATA: [(f64, f64); 29] = [
 ];
 
 const SMALL_PAYLOAD_DATA: [(f64, f64); 23] = [
-    (1961., 118500.),
+    (1961., 118_500.),
     (1962., 14900.),
     (1975., 21400.),
     (1980., 32800.),

examples/colors.rs

@@ -1,5 +1,21 @@
-/// This example shows all the colors supported by ratatui. It will render a grid of foreground
-/// and background colors with their names and indexes.
+//! # [Ratatui] Colors example
+//!
+//! The latest version of this example is available in the [examples] folder in the repository.
+//!
+//! Please note that the examples are designed to be run against the `main` branch of the Github
+//! repository. This means that you may not be able to compile with the latest release version on
+//! crates.io, or the one that you have installed locally.
+//!
+//! See the [examples readme] for more information on finding examples that match the version of the
+//! library you are using.
+//!
+//! [Ratatui]: https://github.com/ratatui-org/ratatui
+//! [examples]: https://github.com/ratatui-org/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui-org/ratatui/blob/main/examples/README.md
+
+// This example shows all the colors supported by ratatui. It will render a grid of foreground
+// and background colors with their names and indexes.
+
 use std::{
     error::Error,
     io::{self, Stdout},
@@ -7,13 +23,20 @@ use std::{
     time::Duration,
 };
 
-use crossterm::{
-    event::{self, Event, KeyCode},
-    execute,
-    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-};
 use itertools::Itertools;
-use ratatui::{prelude::*, widgets::*};
+use ratatui::{
+    backend::{Backend, CrosstermBackend},
+    crossterm::{
+        event::{self, Event, KeyCode},
+        execute,
+        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+    },
+    layout::{Alignment, Constraint, Layout, Rect},
+    style::{Color, Style, Stylize},
+    terminal::{Frame, Terminal},
+    text::Line,
+    widgets::{Block, Borders, Paragraph},
+};
 
 type Result<T> = result::Result<T, Box<dyn Error>>;
 
@@ -33,7 +56,7 @@ fn run_app<B: Backend>(terminal: &mut Terminal<B>) -> io::Result<()> {
 
         if event::poll(Duration::from_millis(250))? {
             if let Event::Key(key) = event::read()? {
-                if let KeyCode::Char('q') = key.code {
+                if key.code == KeyCode::Char('q') {
                     return Ok(());
                 }
             }
@@ -211,12 +234,12 @@ fn render_indexed_colors(frame: &mut Frame, area: Rect) {
 }
 
 fn title_block(title: String) -> Block<'static> {
-    Block::default()
+    Block::new()
         .borders(Borders::TOP)
-        .border_style(Style::new().dark_gray())
-        .title(title)
         .title_alignment(Alignment::Center)
+        .border_style(Style::new().dark_gray())
         .title_style(Style::new().reset())
+        .title(title)
 }
 
 fn render_indexed_grayscale(frame: &mut Frame, area: Rect) {

examples/colors_rgb.rs

@@ -1,107 +1,250 @@
-/// This example shows the full range of RGB colors that can be displayed in the terminal.
-///
-/// Requires a terminal that supports 24-bit color (true color) and unicode.
+//! # [Ratatui] `Colors_RGB` example
+//!
+//! The latest version of this example is available in the [examples] folder in the repository.
+//!
+//! Please note that the examples are designed to be run against the `main` branch of the Github
+//! repository. This means that you may not be able to compile with the latest release version on
+//! crates.io, or the one that you have installed locally.
+//!
+//! See the [examples readme] for more information on finding examples that match the version of the
+//! library you are using.
+//!
+//! [Ratatui]: https://github.com/ratatui-org/ratatui
+//! [examples]: https://github.com/ratatui-org/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui-org/ratatui/blob/main/examples/README.md
+
+// This example shows the full range of RGB colors that can be displayed in the terminal.
+//
+// Requires a terminal that supports 24-bit color (true color) and unicode.
+//
+// This example also demonstrates how implementing the Widget trait on a mutable reference
+// allows the widget to update its state while it is being rendered. This allows the fps
+// widget to update the fps calculation and the colors widget to update a cached version of
+// the colors to render instead of recalculating them every frame.
+//
+// This is an alternative to using the `StatefulWidget` trait and a separate state struct. It
+// is useful when the state is only used by the widget and doesn't need to be shared with
+// other widgets.
+
 use std::{
     io::stdout,
+    panic,
     time::{Duration, Instant},
 };
 
-use color_eyre::config::HookBuilder;
-use crossterm::{
-    event::{self, Event, KeyCode, KeyEventKind},
-    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-    ExecutableCommand,
-};
+use color_eyre::{config::HookBuilder, eyre, Result};
 use palette::{convert::FromColorUnclamped, Okhsv, Srgb};
-use ratatui::{prelude::*, widgets::*};
-
-fn main() -> color_eyre::Result<()> {
-    App::run()
-}
+use ratatui::{
+    backend::{Backend, CrosstermBackend},
+    buffer::Buffer,
+    crossterm::event::{self, Event, KeyCode, KeyEventKind},
+    layout::{Constraint, Layout, Rect},
+    style::Color,
+    text::Text,
+    widgets::Widget,
+    Terminal,
+};
 
 #[derive(Debug, Default)]
 struct App {
-    should_quit: bool,
-    // a 2d vec of the colors to render, calculated when the size changes as this is expensive
-    // to calculate every frame
-    colors: Vec<Vec<Color>>,
-    last_size: Rect,
-    fps: Fps,
-    frame_count: usize,
+    /// The current state of the app (running or quit)
+    state: AppState,
+
+    /// A widget that displays the current frames per second
+    fps_widget: FpsWidget,
+
+    /// A widget that displays the full range of RGB colors that can be displayed in the terminal.
+    colors_widget: ColorsWidget,
 }
 
+#[derive(Debug, Default, PartialEq, Eq)]
+enum AppState {
+    /// The app is running
+    #[default]
+    Running,
+
+    /// The user has requested the app to quit
+    Quit,
+}
+
+/// A widget that displays the current frames per second
 #[derive(Debug)]
-struct Fps {
+struct FpsWidget {
+    /// The number of elapsed frames that have passed - used to calculate the fps
     frame_count: usize,
+
+    /// The last instant that the fps was calculated
     last_instant: Instant,
+
+    /// The current frames per second
     fps: Option<f32>,
 }
 
-struct AppWidget<'a> {
-    title: Paragraph<'a>,
-    fps_widget: FpsWidget<'a>,
-    rgb_colors_widget: RgbColorsWidget<'a>,
-}
+/// A widget that displays the full range of RGB colors that can be displayed in the terminal.
+///
+/// This widget is animated and will change colors over time.
+#[derive(Debug, Default)]
+struct ColorsWidget {
+    /// The colors to render - should be double the height of the area as we render two rows of
+    /// pixels for each row of the widget using the half block character. This is computed any time
+    /// the size of the widget changes.
+    colors: Vec<Vec<Color>>,
 
-struct FpsWidget<'a> {
-    fps: &'a Fps,
-}
-
-struct RgbColorsWidget<'a> {
-    /// The colors to render - should be double the height of the area
-    colors: &'a Vec<Vec<Color>>,
-    /// the number of elapsed frames that have passed - used to animate the colors
+    /// the number of elapsed frames that have passed - used to animate the colors by shifting the
+    /// x index by the frame number
     frame_count: usize,
 }
 
+fn main() -> Result<()> {
+    install_error_hooks()?;
+    let backend = CrosstermBackend::stdout()?;
+    let terminal = Terminal::new(backend)?;
+    App::default().run(terminal)?;
+    Ok(())
+}
+
 impl App {
-    pub fn run() -> color_eyre::Result<()> {
-        install_panic_hook()?;
-
-        let mut terminal = init_terminal()?;
-        let mut app = Self::default();
-
-        while !app.should_quit {
-            app.tick();
-            terminal.draw(|frame| {
-                let size = frame.size();
-                app.setup_colors(size);
-                frame.render_widget(AppWidget::new(&app), size);
-            })?;
-            app.handle_events()?;
+    /// Run the app
+    ///
+    /// This is the main event loop for the app.
+    pub fn run(mut self, mut terminal: Terminal<impl Backend>) -> Result<()> {
+        while self.is_running() {
+            terminal.draw(|frame| frame.render_widget(&mut self, frame.size()))?;
+            self.handle_events()?;
         }
-        restore_terminal()?;
         Ok(())
     }
 
-    fn tick(&mut self) {
-        self.frame_count += 1;
-        self.fps.tick();
+    const fn is_running(&self) -> bool {
+        matches!(self.state, AppState::Running)
     }
 
-    fn handle_events(&mut self) -> color_eyre::Result<()> {
-        if event::poll(Duration::from_secs_f32(1.0 / 60.0))? {
+    /// Handle any events that have occurred since the last time the app was rendered.
+    ///
+    /// Currently, this only handles the q key to quit the app.
+    fn handle_events(&mut self) -> Result<()> {
+        // Ensure that the app only blocks for a period that allows the app to render at
+        // approximately 60 FPS (this doesn't account for the time to render the frame, and will
+        // also update the app immediately any time an event occurs)
+        let timeout = Duration::from_secs_f32(1.0 / 60.0);
+        if event::poll(timeout)? {
             if let Event::Key(key) = event::read()? {
                 if key.kind == KeyEventKind::Press && key.code == KeyCode::Char('q') {
-                    self.should_quit = true;
+                    self.state = AppState::Quit;
                 };
             }
         }
         Ok(())
     }
+}
 
-    fn setup_colors(&mut self, size: Rect) {
-        // only update the colors if the size has changed since the last time we rendered
-        if self.last_size.width == size.width && self.last_size.height == size.height {
-            return;
+/// Implement the Widget trait for &mut App so that it can be rendered
+///
+/// This is implemented on a mutable reference so that the app can update its state while it is
+/// being rendered. This allows the fps widget to update the fps calculation and the colors widget
+/// to update the colors to render.
+impl Widget for &mut App {
+    fn render(self, area: Rect, buf: &mut Buffer) {
+        use Constraint::{Length, Min};
+        let [top, colors] = Layout::vertical([Length(1), Min(0)]).areas(area);
+        let [title, fps] = Layout::horizontal([Min(0), Length(8)]).areas(top);
+        Text::from("colors_rgb example. Press q to quit")
+            .centered()
+            .render(title, buf);
+        self.fps_widget.render(fps, buf);
+        self.colors_widget.render(colors, buf);
+    }
+}
+
+/// Default impl for `FpsWidget`
+///
+/// Manual impl is required because we need to initialize the `last_instant` field to the current
+/// instant.
+impl Default for FpsWidget {
+    fn default() -> Self {
+        Self {
+            frame_count: 0,
+            last_instant: Instant::now(),
+            fps: None,
         }
-        self.last_size = size;
+    }
+}
+
+/// Widget impl for `FpsWidget`
+///
+/// This is implemented on a mutable reference so that we can update the frame count and fps
+/// calculation while rendering.
+impl Widget for &mut FpsWidget {
+    fn render(self, area: Rect, buf: &mut Buffer) {
+        self.calculate_fps();
+        if let Some(fps) = self.fps {
+            let text = format!("{fps:.1} fps");
+            Text::from(text).render(area, buf);
+        }
+    }
+}
+
+impl FpsWidget {
+    /// Update the fps calculation.
+    ///
+    /// This updates the fps once a second, but only if the widget has rendered at least 2 frames
+    /// since the last calculation. This avoids noise in the fps calculation when rendering on slow
+    /// machines that can't render at least 2 frames per second.
+    #[allow(clippy::cast_precision_loss)]
+    fn calculate_fps(&mut self) {
+        self.frame_count += 1;
+        let elapsed = self.last_instant.elapsed();
+        if elapsed > Duration::from_secs(1) && self.frame_count > 2 {
+            self.fps = Some(self.frame_count as f32 / elapsed.as_secs_f32());
+            self.frame_count = 0;
+            self.last_instant = Instant::now();
+        }
+    }
+}
+
+/// Widget impl for `ColorsWidget`
+///
+/// This is implemented on a mutable reference so that we can update the frame count and store a
+/// cached version of the colors to render instead of recalculating them every frame.
+impl Widget for &mut ColorsWidget {
+    /// Render the widget
+    fn render(self, area: Rect, buf: &mut Buffer) {
+        self.setup_colors(area);
+        let colors = &self.colors;
+        for (xi, x) in (area.left()..area.right()).enumerate() {
+            // animate the colors by shifting the x index by the frame number
+            let xi = (xi + self.frame_count) % (area.width as usize);
+            for (yi, y) in (area.top()..area.bottom()).enumerate() {
+                // render a half block character for each row of pixels with the foreground color
+                // set to the color of the pixel and the background color set to the color of the
+                // pixel below it
+                let fg = colors[yi * 2][xi];
+                let bg = colors[yi * 2 + 1][xi];
+                buf.get_mut(x, y).set_char('▀').set_fg(fg).set_bg(bg);
+            }
+        }
+        self.frame_count += 1;
+    }
+}
+
+impl ColorsWidget {
+    /// Setup the colors to render.
+    ///
+    /// This is called once per frame to setup the colors to render. It caches the colors so that
+    /// they don't need to be recalculated every frame.
+    #[allow(clippy::cast_precision_loss)]
+    fn setup_colors(&mut self, size: Rect) {
         let Rect { width, height, .. } = size;
         // double the height because each screen row has two rows of half block pixels
-        let height = height * 2;
-        self.colors.clear();
+        let height = height as usize * 2;
+        let width = width as usize;
+        // only update the colors if the size has changed since the last time we rendered
+        if self.colors.len() == height && self.colors[0].len() == width {
+            return;
+        }
+        self.colors = Vec::with_capacity(height);
         for y in 0..height {
-            let mut row = Vec::new();
+            let mut row = Vec::with_capacity(width);
             for x in 0..width {
                 let hue = x as f32 * 360.0 / width as f32;
                 let value = (height - y) as f32 / height as f32;
@@ -117,109 +260,20 @@ impl App {
     }
 }
 
-impl Fps {
-    fn tick(&mut self) {
-        self.frame_count += 1;
-        let elapsed = self.last_instant.elapsed();
-        // update the fps every second, but only if we've rendered at least 2 frames (to avoid
-        // noise in the fps calculation)
-        if elapsed > Duration::from_secs(1) && self.frame_count > 2 {
-            self.fps = Some(self.frame_count as f32 / elapsed.as_secs_f32());
-            self.frame_count = 0;
-            self.last_instant = Instant::now();
-        }
-    }
-}
-
-impl Default for Fps {
-    fn default() -> Self {
-        Self {
-            frame_count: 0,
-            last_instant: Instant::now(),
-            fps: None,
-        }
-    }
-}
-
-impl<'a> AppWidget<'a> {
-    fn new(app: &'a App) -> Self {
-        let title =
-            Paragraph::new("colors_rgb example. Press q to quit").alignment(Alignment::Center);
-        Self {
-            title,
-            fps_widget: FpsWidget { fps: &app.fps },
-            rgb_colors_widget: RgbColorsWidget {
-                colors: &app.colors,
-                frame_count: app.frame_count,
-            },
-        }
-    }
-}
-
-impl Widget for AppWidget<'_> {
-    fn render(self, area: Rect, buf: &mut Buffer) {
-        let vertical = Layout::vertical([Constraint::Length(1), Constraint::Min(0)]);
-        let horizontal = Layout::horizontal([Constraint::Min(0), Constraint::Length(8)]);
-        let [top, colors] = area.split(&vertical);
-        let [title, fps] = top.split(&horizontal);
-
-        self.title.render(title, buf);
-        self.fps_widget.render(fps, buf);
-        self.rgb_colors_widget.render(colors, buf);
-    }
-}
-
-impl Widget for RgbColorsWidget<'_> {
-    fn render(self, area: Rect, buf: &mut Buffer) {
-        let colors = self.colors;
-        for (xi, x) in (area.left()..area.right()).enumerate() {
-            // animate the colors by shifting the x index by the frame number
-            let xi = (xi + self.frame_count) % (area.width as usize);
-            for (yi, y) in (area.top()..area.bottom()).enumerate() {
-                let fg = colors[yi * 2][xi];
-                let bg = colors[yi * 2 + 1][xi];
-                buf.get_mut(x, y).set_char('▀').set_fg(fg).set_bg(bg);
-            }
-        }
-    }
-}
-
-impl<'a> Widget for FpsWidget<'a> {
-    fn render(self, area: Rect, buf: &mut Buffer) {
-        if let Some(fps) = self.fps.fps {
-            let text = format!("{:.1} fps", fps);
-            Paragraph::new(text).render(area, buf);
-        }
-    }
-}
-
-/// Install a panic hook that restores the terminal before panicking.
-fn install_panic_hook() -> color_eyre::Result<()> {
+/// Install `color_eyre` panic and error hooks
+///
+/// The hooks restore the terminal to a usable state before printing the error message.
+fn install_error_hooks() -> Result<()> {
     let (panic, error) = HookBuilder::default().into_hooks();
     let panic = panic.into_panic_hook();
     let error = error.into_eyre_hook();
-    color_eyre::eyre::set_hook(Box::new(move |e| {
-        let _ = restore_terminal();
+    eyre::set_hook(Box::new(move |e| {
+        let _ = CrosstermBackend::restore(stdout());
         error(e)
     }))?;
-    std::panic::set_hook(Box::new(move |info| {
-        let _ = restore_terminal();
-        panic(info)
+    panic::set_hook(Box::new(move |info| {
+        let _ = CrosstermBackend::restore(stdout());
+        panic(info);
     }));
     Ok(())
 }
-
-fn init_terminal() -> color_eyre::Result<Terminal<impl Backend>> {
-    enable_raw_mode()?;
-    stdout().execute(EnterAlternateScreen)?;
-    let mut terminal = Terminal::new(CrosstermBackend::new(stdout()))?;
-    terminal.clear()?;
-    terminal.hide_cursor()?;
-    Ok(terminal)
-}
-
-fn restore_terminal() -> color_eyre::Result<()> {
-    disable_raw_mode()?;
-    stdout().execute(LeaveAlternateScreen)?;
-    Ok(())
-}

examples/constraint-explorer.rs

@@ -0,0 +1,652 @@
+//! # [Ratatui] Constraint explorer example
+//!
+//! The latest version of this example is available in the [examples] folder in the repository.
+//!
+//! Please note that the examples are designed to be run against the `main` branch of the Github
+//! repository. This means that you may not be able to compile with the latest release version on
+//! crates.io, or the one that you have installed locally.
+//!
+//! See the [examples readme] for more information on finding examples that match the version of the
+//! library you are using.
+//!
+//! [Ratatui]: https://github.com/ratatui-org/ratatui
+//! [examples]: https://github.com/ratatui-org/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui-org/ratatui/blob/main/examples/README.md
+
+use std::io::{self, stdout};
+
+use color_eyre::{config::HookBuilder, Result};
+use itertools::Itertools;
+use ratatui::{
+    backend::{Backend, CrosstermBackend},
+    buffer::Buffer,
+    crossterm::{
+        event::{self, Event, KeyCode, KeyEventKind},
+        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+        ExecutableCommand,
+    },
+    layout::{
+        Constraint::{self, Fill, Length, Max, Min, Percentage, Ratio},
+        Flex, Layout, Rect,
+    },
+    style::{
+        palette::tailwind::{BLUE, SKY, SLATE, STONE},
+        Color, Style, Stylize,
+    },
+    symbols::{self, line},
+    terminal::Terminal,
+    text::{Line, Span, Text},
+    widgets::{Block, Paragraph, Widget, Wrap},
+};
+use strum::{Display, EnumIter, FromRepr};
+
+#[derive(Default)]
+struct App {
+    mode: AppMode,
+    spacing: u16,
+    constraints: Vec<Constraint>,
+    selected_index: usize,
+    value: u16,
+}
+
+#[derive(Debug, Default, PartialEq, Eq)]
+enum AppMode {
+    #[default]
+    Running,
+    Quit,
+}
+
+/// A variant of [`Constraint`] that can be rendered as a tab.
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, EnumIter, FromRepr, Display)]
+enum ConstraintName {
+    #[default]
+    Length,
+    Percentage,
+    Ratio,
+    Min,
+    Max,
+    Fill,
+}
+
+/// A widget that renders a [`Constraint`] as a block. E.g.:
+/// ```plain
+/// ┌──────────────┐
+/// │  Length(16)  │
+/// │     16px     │
+/// └──────────────┘
+/// ```
+struct ConstraintBlock {
+    constraint: Constraint,
+    legend: bool,
+    selected: bool,
+}
+
+/// A widget that renders a spacer with a label indicating the width of the spacer. E.g.:
+///
+/// ```plain
+/// ┌      ┐
+///   8 px
+/// └      ┘
+/// ```
+struct SpacerBlock;
+
+fn main() -> Result<()> {
+    init_error_hooks()?;
+    let terminal = init_terminal()?;
+    App::default().run(terminal)?;
+    restore_terminal()?;
+    Ok(())
+}
+
+// App behaviour
+impl App {
+    fn run(&mut self, mut terminal: Terminal<impl Backend>) -> Result<()> {
+        self.insert_test_defaults();
+
+        while self.is_running() {
+            self.draw(&mut terminal)?;
+            self.handle_events()?;
+        }
+        Ok(())
+    }
+
+    // TODO remove these - these are just for testing
+    fn insert_test_defaults(&mut self) {
+        self.constraints = vec![
+            Constraint::Length(20),
+            Constraint::Length(20),
+            Constraint::Length(20),
+        ];
+        self.value = 20;
+    }
+
+    fn is_running(&self) -> bool {
+        self.mode == AppMode::Running
+    }
+
+    fn draw(&self, terminal: &mut Terminal<impl Backend>) -> io::Result<()> {
+        terminal.draw(|frame| frame.render_widget(self, frame.size()))?;
+        Ok(())
+    }
+
+    fn handle_events(&mut self) -> Result<()> {
+        match event::read()? {
+            Event::Key(key) if key.kind == KeyEventKind::Press => match key.code {
+                KeyCode::Char('q') | KeyCode::Esc => self.exit(),
+                KeyCode::Char('1') => self.swap_constraint(ConstraintName::Min),
+                KeyCode::Char('2') => self.swap_constraint(ConstraintName::Max),
+                KeyCode::Char('3') => self.swap_constraint(ConstraintName::Length),
+                KeyCode::Char('4') => self.swap_constraint(ConstraintName::Percentage),
+                KeyCode::Char('5') => self.swap_constraint(ConstraintName::Ratio),
+                KeyCode::Char('6') => self.swap_constraint(ConstraintName::Fill),
+                KeyCode::Char('+') => self.increment_spacing(),
+                KeyCode::Char('-') => self.decrement_spacing(),
+                KeyCode::Char('x') => self.delete_block(),
+                KeyCode::Char('a') => self.insert_block(),
+                KeyCode::Char('k') | KeyCode::Up => self.increment_value(),
+                KeyCode::Char('j') | KeyCode::Down => self.decrement_value(),
+                KeyCode::Char('h') | KeyCode::Left => self.prev_block(),
+                KeyCode::Char('l') | KeyCode::Right => self.next_block(),
+                _ => {}
+            },
+            _ => {}
+        }
+        Ok(())
+    }
+
+    fn increment_value(&mut self) {
+        let Some(constraint) = self.constraints.get_mut(self.selected_index) else {
+            return;
+        };
+        match constraint {
+            Constraint::Length(v)
+            | Constraint::Min(v)
+            | Constraint::Max(v)
+            | Constraint::Fill(v)
+            | Constraint::Percentage(v) => *v = v.saturating_add(1),
+            Constraint::Ratio(_n, d) => *d = d.saturating_add(1),
+        };
+    }
+
+    fn decrement_value(&mut self) {
+        let Some(constraint) = self.constraints.get_mut(self.selected_index) else {
+            return;
+        };
+        match constraint {
+            Constraint::Length(v)
+            | Constraint::Min(v)
+            | Constraint::Max(v)
+            | Constraint::Fill(v)
+            | Constraint::Percentage(v) => *v = v.saturating_sub(1),
+            Constraint::Ratio(_n, d) => *d = d.saturating_sub(1),
+        };
+    }
+
+    /// select the next block with wrap around
+    fn next_block(&mut self) {
+        if self.constraints.is_empty() {
+            return;
+        }
+        let len = self.constraints.len();
+        self.selected_index = (self.selected_index + 1) % len;
+    }
+
+    /// select the previous block with wrap around
+    fn prev_block(&mut self) {
+        if self.constraints.is_empty() {
+            return;
+        }
+        let len = self.constraints.len();
+        self.selected_index = (self.selected_index + self.constraints.len() - 1) % len;
+    }
+
+    /// delete the selected block
+    fn delete_block(&mut self) {
+        if self.constraints.is_empty() {
+            return;
+        }
+        self.constraints.remove(self.selected_index);
+        self.selected_index = self.selected_index.saturating_sub(1);
+    }
+
+    /// insert a block after the selected block
+    fn insert_block(&mut self) {
+        let index = self
+            .selected_index
+            .saturating_add(1)
+            .min(self.constraints.len());
+        let constraint = Constraint::Length(self.value);
+        self.constraints.insert(index, constraint);
+        self.selected_index = index;
+    }
+
+    fn increment_spacing(&mut self) {
+        self.spacing = self.spacing.saturating_add(1);
+    }
+
+    fn decrement_spacing(&mut self) {
+        self.spacing = self.spacing.saturating_sub(1);
+    }
+
+    fn exit(&mut self) {
+        self.mode = AppMode::Quit;
+    }
+
+    fn swap_constraint(&mut self, name: ConstraintName) {
+        if self.constraints.is_empty() {
+            return;
+        }
+        let constraint = match name {
+            ConstraintName::Length => Length(self.value),
+            ConstraintName::Percentage => Percentage(self.value),
+            ConstraintName::Min => Min(self.value),
+            ConstraintName::Max => Max(self.value),
+            ConstraintName::Fill => Fill(self.value),
+            ConstraintName::Ratio => Ratio(1, u32::from(self.value) / 4), // for balance
+        };
+        self.constraints[self.selected_index] = constraint;
+    }
+}
+
+impl From<Constraint> for ConstraintName {
+    fn from(constraint: Constraint) -> Self {
+        match constraint {
+            Length(_) => Self::Length,
+            Percentage(_) => Self::Percentage,
+            Ratio(_, _) => Self::Ratio,
+            Min(_) => Self::Min,
+            Max(_) => Self::Max,
+            Fill(_) => Self::Fill,
+        }
+    }
+}
+
+impl Widget for &App {
+    fn render(self, area: Rect, buf: &mut Buffer) {
+        let [header_area, instructions_area, swap_legend_area, _, blocks_area] =
+            Layout::vertical([
+                Length(2), // header
+                Length(2), // instructions
+                Length(1), // swap key legend
+                Length(1), // gap
+                Fill(1),   // blocks
+            ])
+            .areas(area);
+
+        App::header().render(header_area, buf);
+        App::instructions().render(instructions_area, buf);
+        App::swap_legend().render(swap_legend_area, buf);
+        self.render_layout_blocks(blocks_area, buf);
+    }
+}
+
+// App rendering
+impl App {
+    const HEADER_COLOR: Color = SLATE.c200;
+    const TEXT_COLOR: Color = SLATE.c400;
+    const AXIS_COLOR: Color = SLATE.c500;
+
+    fn header() -> impl Widget {
+        let text = "Constraint Explorer";
+        text.bold().fg(Self::HEADER_COLOR).into_centered_line()
+    }
+
+    fn instructions() -> impl Widget {
+        let text = "◄ ►: select, ▲ ▼: edit, 1-6: swap, a: add, x: delete, q: quit, + -: spacing";
+        Paragraph::new(text)
+            .fg(Self::TEXT_COLOR)
+            .centered()
+            .wrap(Wrap { trim: false })
+    }
+
+    fn swap_legend() -> impl Widget {
+        #[allow(unstable_name_collisions)]
+        Paragraph::new(
+            Line::from(
+                [
+                    ConstraintName::Min,
+                    ConstraintName::Max,
+                    ConstraintName::Length,
+                    ConstraintName::Percentage,
+                    ConstraintName::Ratio,
+                    ConstraintName::Fill,
+                ]
+                .iter()
+                .enumerate()
+                .map(|(i, name)| {
+                    format!("  {i}: {name}  ", i = i + 1)
+                        .fg(SLATE.c200)
+                        .bg(name.color())
+                })
+                .intersperse(Span::from(" "))
+                .collect_vec(),
+            )
+            .centered(),
+        )
+        .wrap(Wrap { trim: false })
+    }
+
+    /// A bar like `<----- 80 px (gap: 2 px) ----->`
+    ///
+    /// Only shows the gap when spacing is not zero
+    fn axis(&self, width: u16) -> impl Widget {
+        let label = if self.spacing != 0 {
+            format!("{} px (gap: {} px)", width, self.spacing)
+        } else {
+            format!("{width} px")
+        };
+        let bar_width = width.saturating_sub(2) as usize; // we want to `<` and `>` at the ends
+        let width_bar = format!("<{label:-^bar_width$}>");
+        Paragraph::new(width_bar).fg(Self::AXIS_COLOR).centered()
+    }
+
+    fn render_layout_blocks(&self, area: Rect, buf: &mut Buffer) {
+        let [user_constraints, area] = Layout::vertical([Length(3), Fill(1)])
+            .spacing(1)
+            .areas(area);
+
+        self.render_user_constraints_legend(user_constraints, buf);
+
+        let [start, center, end, space_around, space_between] =
+            Layout::vertical([Length(7); 5]).areas(area);
+
+        self.render_layout_block(Flex::Start, start, buf);
+        self.render_layout_block(Flex::Center, center, buf);
+        self.render_layout_block(Flex::End, end, buf);
+        self.render_layout_block(Flex::SpaceAround, space_around, buf);
+        self.render_layout_block(Flex::SpaceBetween, space_between, buf);
+    }
+
+    fn render_user_constraints_legend(&self, area: Rect, buf: &mut Buffer) {
+        let blocks = Layout::horizontal(
+            self.constraints
+                .iter()
+                .map(|_| Constraint::Fill(1))
+                .collect_vec(),
+        )
+        .split(area);
+
+        for (i, (area, constraint)) in blocks.iter().zip(self.constraints.iter()).enumerate() {
+            let selected = self.selected_index == i;
+            ConstraintBlock::new(*constraint, selected, true).render(*area, buf);
+        }
+    }
+
+    fn render_layout_block(&self, flex: Flex, area: Rect, buf: &mut Buffer) {
+        let [label_area, axis_area, blocks_area] =
+            Layout::vertical([Length(1), Max(1), Length(4)]).areas(area);
+
+        if label_area.height > 0 {
+            format!("Flex::{flex:?}").bold().render(label_area, buf);
+        }
+
+        self.axis(area.width).render(axis_area, buf);
+
+        let (blocks, spacers) = Layout::horizontal(&self.constraints)
+            .flex(flex)
+            .spacing(self.spacing)
+            .split_with_spacers(blocks_area);
+
+        for (i, (area, constraint)) in blocks.iter().zip(self.constraints.iter()).enumerate() {
+            let selected = self.selected_index == i;
+            ConstraintBlock::new(*constraint, selected, false).render(*area, buf);
+        }
+
+        for area in spacers.iter() {
+            SpacerBlock.render(*area, buf);
+        }
+    }
+}
+
+impl Widget for ConstraintBlock {
+    fn render(self, area: Rect, buf: &mut Buffer) {
+        match area.height {
+            1 => self.render_1px(area, buf),
+            2 => self.render_2px(area, buf),
+            _ => self.render_4px(area, buf),
+        }
+    }
+}
+
+impl ConstraintBlock {
+    const TEXT_COLOR: Color = SLATE.c200;
+
+    const fn new(constraint: Constraint, selected: bool, legend: bool) -> Self {
+        Self {
+            constraint,
+            legend,
+            selected,
+        }
+    }
+
+    fn label(&self, width: u16) -> String {
+        let long_width = format!("{width} px");
+        let short_width = format!("{width}");
+        // border takes up 2 columns
+        let available_space = width.saturating_sub(2) as usize;
+        let width_label = if long_width.len() < available_space {
+            long_width
+        } else if short_width.len() < available_space {
+            short_width
+        } else {
+            String::new()
+        };
+        format!("{}\n{}", self.constraint, width_label)
+    }
+
+    fn render_1px(&self, area: Rect, buf: &mut Buffer) {
+        let lighter_color = ConstraintName::from(self.constraint).lighter_color();
+        let main_color = ConstraintName::from(self.constraint).color();
+        let selected_color = if self.selected {
+            lighter_color
+        } else {
+            main_color
+        };
+        Block::new()
+            .fg(Self::TEXT_COLOR)
+            .bg(selected_color)
+            .render(area, buf);
+    }
+
+    fn render_2px(&self, area: Rect, buf: &mut Buffer) {
+        let lighter_color = ConstraintName::from(self.constraint).lighter_color();
+        let main_color = ConstraintName::from(self.constraint).color();
+        let selected_color = if self.selected {
+            lighter_color
+        } else {
+            main_color
+        };
+        Block::bordered()
+            .border_set(symbols::border::QUADRANT_OUTSIDE)
+            .border_style(Style::reset().fg(selected_color).reversed())
+            .render(area, buf);
+    }
+
+    fn render_4px(&self, area: Rect, buf: &mut Buffer) {
+        let lighter_color = ConstraintName::from(self.constraint).lighter_color();
+        let main_color = ConstraintName::from(self.constraint).color();
+        let selected_color = if self.selected {
+            lighter_color
+        } else {
+            main_color
+        };
+        let color = if self.legend {
+            selected_color
+        } else {
+            main_color
+        };
+        let label = self.label(area.width);
+        let block = Block::bordered()
+            .border_set(symbols::border::QUADRANT_OUTSIDE)
+            .border_style(Style::reset().fg(color).reversed())
+            .fg(Self::TEXT_COLOR)
+            .bg(color);
+        Paragraph::new(label)
+            .centered()
+            .fg(Self::TEXT_COLOR)
+            .bg(color)
+            .block(block)
+            .render(area, buf);
+
+        if !self.legend {
+            let border_color = if self.selected {
+                lighter_color
+            } else {
+                main_color
+            };
+            if let Some(last_row) = area.rows().last() {
+                buf.set_style(last_row, border_color);
+            }
+        }
+    }
+}
+
+impl Widget for SpacerBlock {
+    fn render(self, area: Rect, buf: &mut Buffer) {
+        match area.height {
+            1 => (),
+            2 => Self::render_2px(area, buf),
+            3 => Self::render_3px(area, buf),
+            _ => Self::render_4px(area, buf),
+        }
+    }
+}
+
+impl SpacerBlock {
+    const TEXT_COLOR: Color = SLATE.c500;
+    const BORDER_COLOR: Color = SLATE.c600;
+
+    /// A block with a corner borders
+    fn block() -> impl Widget {
+        let corners_only = symbols::border::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: " ",
+            vertical_right: " ",
+            horizontal_top: " ",
+            horizontal_bottom: " ",
+        };
+        Block::bordered()
+            .border_set(corners_only)
+            .border_style(Self::BORDER_COLOR)
+    }
+
+    /// A vertical line used if there is not enough space to render the block
+    fn line() -> impl Widget {
+        Paragraph::new(Text::from(vec![
+            Line::from(""),
+            Line::from("│"),
+            Line::from("│"),
+            Line::from(""),
+        ]))
+        .style(Self::BORDER_COLOR)
+    }
+
+    /// A label that says "Spacer" if there is enough space
+    fn spacer_label(width: u16) -> impl Widget {
+        let label = if width >= 6 { "Spacer" } else { "" };
+        label.fg(Self::TEXT_COLOR).into_centered_line()
+    }
+
+    /// A label that says "8 px" if there is enough space
+    fn label(width: u16) -> impl Widget {
+        let long_label = format!("{width} px");
+        let short_label = format!("{width}");
+        let label = if long_label.len() < width as usize {
+            long_label
+        } else if short_label.len() < width as usize {
+            short_label
+        } else {
+            String::new()
+        };
+        Line::styled(label, Self::TEXT_COLOR).centered()
+    }
+
+    fn render_2px(area: Rect, buf: &mut Buffer) {
+        if area.width > 1 {
+            Self::block().render(area, buf);
+        } else {
+            Self::line().render(area, buf);
+        }
+    }
+
+    fn render_3px(area: Rect, buf: &mut Buffer) {
+        if area.width > 1 {
+            Self::block().render(area, buf);
+        } else {
+            Self::line().render(area, buf);
+        }
+
+        let row = area.rows().nth(1).unwrap_or_default();
+        Self::spacer_label(area.width).render(row, buf);
+    }
+
+    fn render_4px(area: Rect, buf: &mut Buffer) {
+        if area.width > 1 {
+            Self::block().render(area, buf);
+        } else {
+            Self::line().render(area, buf);
+        }
+
+        let row = area.rows().nth(1).unwrap_or_default();
+        Self::spacer_label(area.width).render(row, buf);
+
+        let row = area.rows().nth(2).unwrap_or_default();
+        Self::label(area.width).render(row, buf);
+    }
+}
+
+impl ConstraintName {
+    const fn color(self) -> Color {
+        match self {
+            Self::Length => SLATE.c700,
+            Self::Percentage => SLATE.c800,
+            Self::Ratio => SLATE.c900,
+            Self::Fill => SLATE.c950,
+            Self::Min => BLUE.c800,
+            Self::Max => BLUE.c900,
+        }
+    }
+
+    const fn lighter_color(self) -> Color {
+        match self {
+            Self::Length => STONE.c500,
+            Self::Percentage => STONE.c600,
+            Self::Ratio => STONE.c700,
+            Self::Fill => STONE.c800,
+            Self::Min => SKY.c600,
+            Self::Max => SKY.c700,
+        }
+    }
+}
+
+fn init_error_hooks() -> Result<()> {
+    let (panic, error) = HookBuilder::default().into_hooks();
+    let panic = panic.into_panic_hook();
+    let error = error.into_eyre_hook();
+    color_eyre::eyre::set_hook(Box::new(move |e| {
+        let _ = restore_terminal();
+        error(e)
+    }))?;
+    std::panic::set_hook(Box::new(move |info| {
+        let _ = restore_terminal();
+        panic(info);
+    }));
+    Ok(())
+}
+
+fn init_terminal() -> Result<Terminal<impl Backend>> {
+    enable_raw_mode()?;
+    stdout().execute(EnterAlternateScreen)?;
+    let backend = CrosstermBackend::new(stdout());
+    let terminal = Terminal::new(backend)?;
+    Ok(terminal)
+}
+
+fn restore_terminal() -> Result<()> {
+    disable_raw_mode()?;
+    stdout().execute(LeaveAlternateScreen)?;
+    Ok(())
+}

examples/constraints.rs

@@ -1,20 +1,48 @@
+//! # [Ratatui] Constraints example
+//!
+//! The latest version of this example is available in the [examples] folder in the repository.
+//!
+//! Please note that the examples are designed to be run against the `main` branch of the Github
+//! repository. This means that you may not be able to compile with the latest release version on
+//! crates.io, or the one that you have installed locally.
+//!
+//! See the [examples readme] for more information on finding examples that match the version of the
+//! library you are using.
+//!
+//! [Ratatui]: https://github.com/ratatui-org/ratatui
+//! [examples]: https://github.com/ratatui-org/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui-org/ratatui/blob/main/examples/README.md
+
 use std::io::{self, stdout};
 
 use color_eyre::{config::HookBuilder, Result};
-use crossterm::{
-    event::{self, Event, KeyCode},
-    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-    ExecutableCommand,
+use ratatui::{
+    backend::{Backend, CrosstermBackend},
+    buffer::Buffer,
+    crossterm::{
+        event::{self, Event, KeyCode, KeyEventKind},
+        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+        ExecutableCommand,
+    },
+    layout::{
+        Constraint::{self, Fill, Length, Max, Min, Percentage, Ratio},
+        Layout, Rect,
+    },
+    style::{palette::tailwind, Color, Modifier, Style, Stylize},
+    symbols,
+    terminal::Terminal,
+    text::Line,
+    widgets::{
+        Block, Padding, Paragraph, Scrollbar, ScrollbarOrientation, ScrollbarState, StatefulWidget,
+        Tabs, Widget,
+    },
 };
-use ratatui::{layout::Constraint::*, prelude::*, style::palette::tailwind, widgets::*};
 use strum::{Display, EnumIter, FromRepr, IntoEnumIterator};
 
 const SPACER_HEIGHT: u16 = 0;
 const ILLUSTRATION_HEIGHT: u16 = 4;
 const EXAMPLE_HEIGHT: u16 = ILLUSTRATION_HEIGHT + SPACER_HEIGHT;
 
-// priority 1
-const FIXED_COLOR: Color = tailwind::RED.c900;
 // priority 2
 const MIN_COLOR: Color = tailwind::BLUE.c900;
 const MAX_COLOR: Color = tailwind::BLUE.c800;
@@ -23,7 +51,7 @@ const LENGTH_COLOR: Color = tailwind::SLATE.c700;
 const PERCENTAGE_COLOR: Color = tailwind::SLATE.c800;
 const RATIO_COLOR: Color = tailwind::SLATE.c900;
 // priority 4
-const PROPORTIONAL_COLOR: Color = tailwind::SLATE.c950;
+const FILL_COLOR: Color = tailwind::SLATE.c950;
 
 #[derive(Default, Clone, Copy)]
 struct App {
@@ -39,13 +67,12 @@ struct App {
 #[derive(Default, Debug, Copy, Clone, Display, FromRepr, EnumIter, PartialEq, Eq)]
 enum SelectedTab {
     #[default]
-    Fixed,
     Min,
     Max,
     Length,
     Percentage,
     Ratio,
-    Proportional,
+    Fill,
 }
 
 #[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
@@ -83,7 +110,7 @@ impl App {
         self.max_scroll_offset = (self.selected_tab.get_example_count() - 1) * EXAMPLE_HEIGHT;
     }
 
-    fn is_running(&self) -> bool {
+    fn is_running(self) -> bool {
         self.state == AppState::Running
     }
 
@@ -94,15 +121,17 @@ impl App {
 
     fn handle_events(&mut self) -> Result<()> {
         if let Event::Key(key) = event::read()? {
-            use KeyCode::*;
+            if key.kind != KeyEventKind::Press {
+                return Ok(());
+            }
             match key.code {
-                Char('q') | Esc => self.quit(),
-                Char('l') | Right => self.next(),
-                Char('h') | Left => self.previous(),
-                Char('j') | Down => self.down(),
-                Char('k') | Up => self.up(),
-                Char('g') | Home => self.top(),
-                Char('G') | End => self.bottom(),
+                KeyCode::Char('q') | KeyCode::Esc => self.quit(),
+                KeyCode::Char('l') | KeyCode::Right => self.next(),
+                KeyCode::Char('h') | KeyCode::Left => self.previous(),
+                KeyCode::Char('j') | KeyCode::Down => self.down(),
+                KeyCode::Char('k') | KeyCode::Up => self.up(),
+                KeyCode::Char('g') | KeyCode::Home => self.top(),
+                KeyCode::Char('G') | KeyCode::End => self.bottom(),
                 _ => (),
             }
         }
@@ -126,14 +155,14 @@ impl App {
     }
 
     fn up(&mut self) {
-        self.scroll_offset = self.scroll_offset.saturating_sub(1)
+        self.scroll_offset = self.scroll_offset.saturating_sub(1);
     }
 
     fn down(&mut self) {
         self.scroll_offset = self
             .scroll_offset
             .saturating_add(1)
-            .min(self.max_scroll_offset)
+            .min(self.max_scroll_offset);
     }
 
     fn top(&mut self) {
@@ -147,20 +176,16 @@ impl App {
 
 impl Widget for App {
     fn render(self, area: Rect, buf: &mut Buffer) {
-        let [tabs, axis, demo] = area.split(&Layout::vertical([
-            Constraint::Fixed(3),
-            Constraint::Fixed(3),
-            Proportional(0),
-        ]));
+        let [tabs, axis, demo] = Layout::vertical([Length(3), Length(3), Fill(0)]).areas(area);
 
         self.render_tabs(tabs, buf);
-        self.render_axis(axis, buf);
+        Self::render_axis(axis, buf);
         self.render_demo(demo, buf);
     }
 }
 
 impl App {
-    fn render_tabs(&self, area: Rect, buf: &mut Buffer) {
+    fn render_tabs(self, area: Rect, buf: &mut Buffer) {
         let titles = SelectedTab::iter().map(SelectedTab::to_tab_title);
         let block = Block::new()
             .title("Constraints ".bold())
@@ -174,17 +199,17 @@ impl App {
             .render(area, buf);
     }
 
-    fn render_axis(&self, area: Rect, buf: &mut Buffer) {
+    fn render_axis(area: Rect, buf: &mut Buffer) {
         let width = area.width as usize;
         // a bar like `<----- 80 px ----->`
-        let width_label = format!("{} px", width);
+        let width_label = format!("{width} px");
         let width_bar = format!(
             "<{width_label:-^width$}>",
             width = width - width_label.len() / 2
         );
         Paragraph::new(width_bar.dark_gray())
-            .alignment(Alignment::Center)
-            .block(Block::default().padding(Padding {
+            .centered()
+            .block(Block::new().padding(Padding {
                 left: 0,
                 right: 0,
                 top: 1,
@@ -197,7 +222,8 @@ impl App {
     ///
     /// This function renders the demo content into a separate buffer and then splices the buffer
     /// into the main buffer. This is done to make it possible to handle scrolling easily.
-    fn render_demo(&self, area: Rect, buf: &mut Buffer) {
+    #[allow(clippy::cast_possible_truncation)]
+    fn render_demo(self, area: Rect, buf: &mut Buffer) {
         // render demo content into a separate buffer so all examples fit we add an extra
         // area.height to make sure the last example is fully visible even when the scroll offset is
         // at the max
@@ -237,43 +263,40 @@ impl App {
 
 impl SelectedTab {
     /// Get the previous tab, if there is no previous tab return the current tab.
-    fn previous(&self) -> Self {
-        let current_index: usize = *self as usize;
+    fn previous(self) -> Self {
+        let current_index: usize = self as usize;
         let previous_index = current_index.saturating_sub(1);
-        Self::from_repr(previous_index).unwrap_or(*self)
+        Self::from_repr(previous_index).unwrap_or(self)
     }
 
     /// Get the next tab, if there is no next tab return the current tab.
-    fn next(&self) -> Self {
-        let current_index = *self as usize;
+    fn next(self) -> Self {
+        let current_index = self as usize;
         let next_index = current_index.saturating_add(1);
-        Self::from_repr(next_index).unwrap_or(*self)
+        Self::from_repr(next_index).unwrap_or(self)
     }
 
-    fn get_example_count(&self) -> u16 {
-        use SelectedTab::*;
+    const fn get_example_count(self) -> u16 {
+        #[allow(clippy::match_same_arms)]
         match self {
-            Fixed => 4,
-            Length => 4,
-            Percentage => 5,
-            Ratio => 4,
-            Proportional => 2,
-            Min => 5,
-            Max => 5,
+            Self::Length => 4,
+            Self::Percentage => 5,
+            Self::Ratio => 4,
+            Self::Fill => 2,
+            Self::Min => 5,
+            Self::Max => 5,
         }
     }
 
-    fn to_tab_title(value: SelectedTab) -> Line<'static> {
-        use SelectedTab::*;
+    fn to_tab_title(value: Self) -> Line<'static> {
         let text = format!("  {value}  ");
         let color = match value {
-            Fixed => FIXED_COLOR,
-            Length => LENGTH_COLOR,
-            Percentage => PERCENTAGE_COLOR,
-            Ratio => RATIO_COLOR,
-            Proportional => PROPORTIONAL_COLOR,
-            Min => MIN_COLOR,
-            Max => MAX_COLOR,
+            Self::Length => LENGTH_COLOR,
+            Self::Percentage => PERCENTAGE_COLOR,
+            Self::Ratio => RATIO_COLOR,
+            Self::Fill => FILL_COLOR,
+            Self::Min => MIN_COLOR,
+            Self::Max => MAX_COLOR,
         };
         text.fg(tailwind::SLATE.c200).bg(color).into()
     }
@@ -282,59 +305,40 @@ impl SelectedTab {
 impl Widget for SelectedTab {
     fn render(self, area: Rect, buf: &mut Buffer) {
         match self {
-            SelectedTab::Fixed => self.render_fixed_example(area, buf),
-            SelectedTab::Length => self.render_length_example(area, buf),
-            SelectedTab::Percentage => self.render_percentage_example(area, buf),
-            SelectedTab::Ratio => self.render_ratio_example(area, buf),
-            SelectedTab::Proportional => self.render_proportional_example(area, buf),
-            SelectedTab::Min => self.render_min_example(area, buf),
-            SelectedTab::Max => self.render_max_example(area, buf),
+            Self::Length => Self::render_length_example(area, buf),
+            Self::Percentage => Self::render_percentage_example(area, buf),
+            Self::Ratio => Self::render_ratio_example(area, buf),
+            Self::Fill => Self::render_fill_example(area, buf),
+            Self::Min => Self::render_min_example(area, buf),
+            Self::Max => Self::render_max_example(area, buf),
         }
     }
 }
 
 impl SelectedTab {
-    fn render_fixed_example(&self, area: Rect, buf: &mut Buffer) {
-        let [example1, example2, example3, example4, _] =
-            area.split(&Layout::vertical([Fixed(EXAMPLE_HEIGHT); 5]));
+    fn render_length_example(area: Rect, buf: &mut Buffer) {
+        let [example1, example2, example3, _] =
+            Layout::vertical([Length(EXAMPLE_HEIGHT); 4]).areas(area);
 
-        Example::new(&[Fixed(40), Proportional(0)]).render(example1, buf);
-        Example::new(&[Fixed(20), Fixed(20), Proportional(0)]).render(example2, buf);
-        Example::new(&[Fixed(20), Min(20), Max(20)]).render(example3, buf);
-        Example::new(&[
-            Length(20),
-            Percentage(20),
-            Ratio(1, 5),
-            Proportional(1),
-            Fixed(15),
-        ])
-        .render(example4, buf);
+        Example::new(&[Length(20), Length(20)]).render(example1, buf);
+        Example::new(&[Length(20), Min(20)]).render(example2, buf);
+        Example::new(&[Length(20), Max(20)]).render(example3, buf);
     }
 
-    fn render_length_example(&self, area: Rect, buf: &mut Buffer) {
-        let [example1, example2, example3, example4, _] =
-            area.split(&Layout::vertical([Fixed(EXAMPLE_HEIGHT); 5]));
-
-        Example::new(&[Length(20), Fixed(20)]).render(example1, buf);
-        Example::new(&[Length(20), Length(20)]).render(example2, buf);
-        Example::new(&[Length(20), Min(20)]).render(example3, buf);
-        Example::new(&[Length(20), Max(20)]).render(example4, buf);
-    }
-
-    fn render_percentage_example(&self, area: Rect, buf: &mut Buffer) {
+    fn render_percentage_example(area: Rect, buf: &mut Buffer) {
         let [example1, example2, example3, example4, example5, _] =
-            area.split(&Layout::vertical([Fixed(EXAMPLE_HEIGHT); 6]));
+            Layout::vertical([Length(EXAMPLE_HEIGHT); 6]).areas(area);
 
-        Example::new(&[Percentage(75), Proportional(0)]).render(example1, buf);
-        Example::new(&[Percentage(25), Proportional(0)]).render(example2, buf);
+        Example::new(&[Percentage(75), Fill(0)]).render(example1, buf);
+        Example::new(&[Percentage(25), Fill(0)]).render(example2, buf);
         Example::new(&[Percentage(50), Min(20)]).render(example3, buf);
         Example::new(&[Percentage(0), Max(0)]).render(example4, buf);
-        Example::new(&[Percentage(0), Proportional(0)]).render(example5, buf);
+        Example::new(&[Percentage(0), Fill(0)]).render(example5, buf);
     }
 
-    fn render_ratio_example(&self, area: Rect, buf: &mut Buffer) {
+    fn render_ratio_example(area: Rect, buf: &mut Buffer) {
         let [example1, example2, example3, example4, _] =
-            area.split(&Layout::vertical([Fixed(EXAMPLE_HEIGHT); 5]));
+            Layout::vertical([Length(EXAMPLE_HEIGHT); 5]).areas(area);
 
         Example::new(&[Ratio(1, 2); 2]).render(example1, buf);
         Example::new(&[Ratio(1, 4); 4]).render(example2, buf);
@@ -342,16 +346,16 @@ impl SelectedTab {
         Example::new(&[Ratio(1, 2), Percentage(25), Length(10)]).render(example4, buf);
     }
 
-    fn render_proportional_example(&self, area: Rect, buf: &mut Buffer) {
-        let [example1, example2, _] = area.split(&Layout::vertical([Fixed(EXAMPLE_HEIGHT); 3]));
+    fn render_fill_example(area: Rect, buf: &mut Buffer) {
+        let [example1, example2, _] = Layout::vertical([Length(EXAMPLE_HEIGHT); 3]).areas(area);
 
-        Example::new(&[Proportional(1), Proportional(2), Proportional(3)]).render(example1, buf);
-        Example::new(&[Proportional(1), Percentage(50), Proportional(1)]).render(example2, buf);
+        Example::new(&[Fill(1), Fill(2), Fill(3)]).render(example1, buf);
+        Example::new(&[Fill(1), Percentage(50), Fill(1)]).render(example2, buf);
     }
 
-    fn render_min_example(&self, area: Rect, buf: &mut Buffer) {
+    fn render_min_example(area: Rect, buf: &mut Buffer) {
         let [example1, example2, example3, example4, example5, _] =
-            area.split(&Layout::vertical([Fixed(EXAMPLE_HEIGHT); 6]));
+            Layout::vertical([Length(EXAMPLE_HEIGHT); 6]).areas(area);
 
         Example::new(&[Percentage(100), Min(0)]).render(example1, buf);
         Example::new(&[Percentage(100), Min(20)]).render(example2, buf);
@@ -360,9 +364,9 @@ impl SelectedTab {
         Example::new(&[Percentage(100), Min(80)]).render(example5, buf);
     }
 
-    fn render_max_example(&self, area: Rect, buf: &mut Buffer) {
+    fn render_max_example(area: Rect, buf: &mut Buffer) {
         let [example1, example2, example3, example4, example5, _] =
-            area.split(&Layout::vertical([Fixed(EXAMPLE_HEIGHT); 6]));
+            Layout::vertical([Length(EXAMPLE_HEIGHT); 6]).areas(area);
 
         Example::new(&[Percentage(0), Max(0)]).render(example1, buf);
         Example::new(&[Percentage(0), Max(20)]).render(example2, buf);
@@ -386,27 +390,23 @@ impl Example {
 
 impl Widget for Example {
     fn render(self, area: Rect, buf: &mut Buffer) {
-        let [area, _] = area.split(&Layout::vertical([
-            Fixed(ILLUSTRATION_HEIGHT),
-            Fixed(SPACER_HEIGHT),
-        ]));
+        let [area, _] =
+            Layout::vertical([Length(ILLUSTRATION_HEIGHT), Length(SPACER_HEIGHT)]).areas(area);
         let blocks = Layout::horizontal(&self.constraints).split(area);
 
         for (block, constraint) in blocks.iter().zip(&self.constraints) {
-            self.illustration(*constraint, block.width)
-                .render(*block, buf);
+            Self::illustration(*constraint, block.width).render(*block, buf);
         }
     }
 }
 
 impl Example {
-    fn illustration(&self, constraint: Constraint, width: u16) -> Paragraph {
+    fn illustration(constraint: Constraint, width: u16) -> impl Widget {
         let color = match constraint {
-            Constraint::Fixed(_) => FIXED_COLOR,
             Constraint::Length(_) => LENGTH_COLOR,
             Constraint::Percentage(_) => PERCENTAGE_COLOR,
             Constraint::Ratio(_, _) => RATIO_COLOR,
-            Constraint::Proportional(_) => PROPORTIONAL_COLOR,
+            Constraint::Fill(_) => FILL_COLOR,
             Constraint::Min(_) => MIN_COLOR,
             Constraint::Max(_) => MAX_COLOR,
         };
@@ -418,9 +418,7 @@ impl Example {
             .border_set(symbols::border::QUADRANT_OUTSIDE)
             .border_style(Style::reset().fg(color).reversed())
             .style(Style::default().fg(fg).bg(color));
-        Paragraph::new(text)
-            .alignment(Alignment::Center)
-            .block(block)
+        Paragraph::new(text).centered().block(block)
     }
 }
 
@@ -434,7 +432,7 @@ fn init_error_hooks() -> Result<()> {
     }))?;
     std::panic::set_hook(Box::new(move |info| {
         let _ = restore_terminal();
-        panic(info)
+        panic(info);
     }));
     Ok(())
 }

examples/custom_widget.rs

@@ -1,14 +1,37 @@
+//! # [Ratatui] Custom Widget example
+//!
+//! The latest version of this example is available in the [examples] folder in the repository.
+//!
+//! Please note that the examples are designed to be run against the `main` branch of the Github
+//! repository. This means that you may not be able to compile with the latest release version on
+//! crates.io, or the one that you have installed locally.
+//!
+//! See the [examples readme] for more information on finding examples that match the version of the
+//! library you are using.
+//!
+//! [Ratatui]: https://github.com/ratatui-org/ratatui
+//! [examples]: https://github.com/ratatui-org/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui-org/ratatui/blob/main/examples/README.md
+
 use std::{error::Error, io, ops::ControlFlow, time::Duration};
 
-use crossterm::{
-    event::{
-        self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode, MouseButton, MouseEvent,
-        MouseEventKind,
+use ratatui::{
+    backend::{Backend, CrosstermBackend},
+    buffer::Buffer,
+    crossterm::{
+        event::{
+            self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode, MouseButton, MouseEvent,
+            MouseEventKind,
+        },
+        execute,
+        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
     },
-    execute,
-    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+    layout::{Constraint, Layout, Rect},
+    style::{Color, Style},
+    terminal::{Frame, Terminal},
+    text::Line,
+    widgets::{Paragraph, Widget},
 };
-use ratatui::{prelude::*, widgets::*};
 
 /// A custom widget that renders a button with a label, theme and state.
 #[derive(Debug, Clone)]
@@ -56,7 +79,7 @@ const GREEN: Theme = Theme {
 
 /// A button with a label that can be themed.
 impl<'a> Button<'a> {
-    pub fn new<T: Into<Line<'a>>>(label: T) -> Button<'a> {
+    pub fn new<T: Into<Line<'a>>>(label: T) -> Self {
         Button {
             label: label.into(),
             theme: BLUE,
@@ -64,18 +87,19 @@ impl<'a> Button<'a> {
         }
     }
 
-    pub fn theme(mut self, theme: Theme) -> Button<'a> {
+    pub const fn theme(mut self, theme: Theme) -> Self {
         self.theme = theme;
         self
     }
 
-    pub fn state(mut self, state: State) -> Button<'a> {
+    pub const fn state(mut self, state: State) -> Self {
         self.state = state;
         self
     }
 }
 
 impl<'a> Widget for Button<'a> {
+    #[allow(clippy::cast_possible_truncation)]
     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));
@@ -109,7 +133,7 @@ impl<'a> Widget for Button<'a> {
 }
 
 impl Button<'_> {
-    fn colors(&self) -> (Color, Color, Color, Color) {
+    const fn colors(&self) -> (Color, Color, Color, Color) {
         let theme = self.theme;
         match self.state {
             State::Normal => (theme.background, theme.text, theme.shadow, theme.highlight),
@@ -148,7 +172,7 @@ 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];
+    let mut button_states = [State::Selected, State::Normal, State::Normal];
     loop {
         terminal.draw(|frame| ui(frame, button_states))?;
         if !event::poll(Duration::from_millis(100))? {
@@ -159,25 +183,27 @@ fn run_app<B: Backend>(terminal: &mut Terminal<B>) -> io::Result<()> {
                 if key.kind != event::KeyEventKind::Press {
                     continue;
                 }
-                if handle_key_event(key, button_states, &mut selected_button).is_break() {
+                if handle_key_event(key, &mut button_states, &mut selected_button).is_break() {
                     break;
                 }
             }
-            Event::Mouse(mouse) => handle_mouse_event(mouse, button_states, &mut selected_button),
+            Event::Mouse(mouse) => {
+                handle_mouse_event(mouse, &mut button_states, &mut selected_button);
+            }
             _ => (),
         }
     }
     Ok(())
 }
 
-fn ui(frame: &mut Frame, states: &[State; 3]) {
+fn ui(frame: &mut Frame, states: [State; 3]) {
     let vertical = Layout::vertical([
         Constraint::Length(1),
         Constraint::Max(3),
         Constraint::Length(1),
         Constraint::Min(0), // ignore remaining space
     ]);
-    let [title, buttons, help, _] = frame.size().split(&vertical);
+    let [title, buttons, help, _] = vertical.areas(frame.size());
 
     frame.render_widget(
         Paragraph::new("Custom Widget Example (mouse enabled)"),
@@ -187,14 +213,14 @@ fn ui(frame: &mut Frame, states: &[State; 3]) {
     frame.render_widget(Paragraph::new("←/→: select, Space: toggle, q: quit"), help);
 }
 
-fn render_buttons(frame: &mut Frame<'_>, area: Rect, states: &[State; 3]) {
+fn render_buttons(frame: &mut Frame<'_>, area: Rect, states: [State; 3]) {
     let horizontal = Layout::horizontal([
         Constraint::Length(15),
         Constraint::Length(15),
         Constraint::Length(15),
         Constraint::Min(0), // ignore remaining space
     ]);
-    let [red, green, blue, _] = area.split(&horizontal);
+    let [red, green, blue, _] = horizontal.areas(area);
 
     frame.render_widget(Button::new("Red").theme(RED).state(states[0]), red);
     frame.render_widget(Button::new("Green").theme(GREEN).state(states[1]), green);

examples/demo/app.rs

@@ -2,7 +2,7 @@ use rand::{
     distributions::{Distribution, Uniform},
     rngs::ThreadRng,
 };
-use ratatui::widgets::*;
+use ratatui::widgets::ListState;
 
 const TASKS: [&str; 24] = [
     "Item1", "Item2", "Item3", "Item4", "Item5", "Item6", "Item7", "Item8", "Item9", "Item10",
@@ -73,8 +73,8 @@ pub struct RandomSignal {
 }
 
 impl RandomSignal {
-    pub fn new(lower: u64, upper: u64) -> RandomSignal {
-        RandomSignal {
+    pub fn new(lower: u64, upper: u64) -> Self {
+        Self {
             distribution: Uniform::new(lower, upper),
             rng: rand::thread_rng(),
         }
@@ -97,8 +97,8 @@ pub struct SinSignal {
 }
 
 impl SinSignal {
-    pub fn new(interval: f64, period: f64, scale: f64) -> SinSignal {
-        SinSignal {
+    pub const fn new(interval: f64, period: f64, scale: f64) -> Self {
+        Self {
             x: 0.0,
             interval,
             period,
@@ -122,8 +122,8 @@ pub struct TabsState<'a> {
 }
 
 impl<'a> TabsState<'a> {
-    pub fn new(titles: Vec<&'a str>) -> TabsState {
-        TabsState { titles, index: 0 }
+    pub fn new(titles: Vec<&'a str>) -> Self {
+        Self { titles, index: 0 }
     }
     pub fn next(&mut self) {
         self.index = (self.index + 1) % self.titles.len();
@@ -144,8 +144,8 @@ pub struct StatefulList<T> {
 }
 
 impl<T> StatefulList<T> {
-    pub fn with_items(items: Vec<T>) -> StatefulList<T> {
-        StatefulList {
+    pub fn with_items(items: Vec<T>) -> Self {
+        Self {
             state: ListState::default(),
             items,
         }
@@ -191,9 +191,7 @@ where
     S: Iterator,
 {
     fn on_tick(&mut self) {
-        for _ in 0..self.tick_rate {
-            self.points.remove(0);
-        }
+        self.points.drain(0..self.tick_rate);
         self.points
             .extend(self.source.by_ref().take(self.tick_rate));
     }
@@ -237,7 +235,7 @@ pub struct App<'a> {
 }
 
 impl<'a> App<'a> {
-    pub fn new(title: &'a str, enhanced_graphics: bool) -> App<'a> {
+    pub fn new(title: &'a str, enhanced_graphics: bool) -> Self {
         let mut rand_signal = RandomSignal::new(0, 100);
         let sparkline_points = rand_signal.by_ref().take(300).collect();
         let mut sin_signal = SinSignal::new(0.2, 3.0, 18.0);

examples/demo/crossterm.rs

@@ -4,12 +4,15 @@ use std::{
     time::{Duration, Instant},
 };
 
-use crossterm::{
-    event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode, KeyEventKind},
-    execute,
-    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+use ratatui::{
+    backend::{Backend, CrosstermBackend},
+    crossterm::{
+        event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode, KeyEventKind},
+        execute,
+        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+    },
+    terminal::Terminal,
 };
-use ratatui::prelude::*;
 
 use crate::{app::App, ui};
 

examples/demo/main.rs

@@ -1,3 +1,18 @@
+//! # [Ratatui] Original Demo example
+//!
+//! The latest version of this example is available in the [examples] folder in the repository.
+//!
+//! Please note that the examples are designed to be run against the `main` branch of the Github
+//! repository. This means that you may not be able to compile with the latest release version on
+//! crates.io, or the one that you have installed locally.
+//!
+//! See the [examples readme] for more information on finding examples that match the version of the
+//! library you are using.
+//!
+//! [Ratatui]: https://github.com/ratatui-org/ratatui
+//! [examples]: https://github.com/ratatui-org/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui-org/ratatui/blob/main/examples/README.md
+
 use std::{error::Error, time::Duration};
 
 use argh::FromArgs;

examples/demo/termion.rs

@@ -1,11 +1,14 @@
 use std::{error::Error, io, sync::mpsc, thread, time::Duration};
 
-use ratatui::prelude::*;
-use termion::{
-    event::Key,
-    input::{MouseTerminal, TermRead},
-    raw::IntoRawMode,
-    screen::IntoAlternateScreen,
+use ratatui::{
+    backend::{Backend, TermionBackend},
+    terminal::Terminal,
+    termion::{
+        event::Key,
+        input::{MouseTerminal, TermRead},
+        raw::IntoRawMode,
+        screen::IntoAlternateScreen,
+    },
 };
 
 use crate::{app::App, ui};

examples/demo/termwiz.rs

@@ -3,8 +3,14 @@ use std::{
     time::{Duration, Instant},
 };
 
-use ratatui::prelude::*;
-use termwiz::{input::*, terminal::Terminal as TermwizTerminal};
+use ratatui::{
+    backend::TermwizBackend,
+    terminal::Terminal,
+    termwiz::{
+        input::{InputEvent, KeyCode},
+        terminal::Terminal as TermwizTerminal,
+    },
+};
 
 use crate::{app::App, ui};
 

examples/demo/ui.rs

@@ -1,6 +1,14 @@
 use ratatui::{
-    prelude::*,
-    widgets::{canvas::*, *},
+    layout::{Constraint, Layout, Rect},
+    style::{Color, Modifier, Style},
+    symbols,
+    terminal::Frame,
+    text::{self, Span},
+    widgets::{
+        canvas::{self, Canvas, Circle, Map, MapResolution, Rectangle},
+        Axis, BarChart, Block, Cell, Chart, Dataset, Gauge, LineGauge, List, ListItem, Paragraph,
+        Row, Sparkline, Table, Tabs, Wrap,
+    },
 };
 
 use crate::app::App;
@@ -13,7 +21,7 @@ pub fn draw(f: &mut Frame, app: &mut App) {
         .iter()
         .map(|t| text::Line::from(Span::styled(*t, Style::default().fg(Color::Green))))
         .collect::<Tabs>()
-        .block(Block::default().borders(Borders::ALL).title(app.title))
+        .block(Block::bordered().title(app.title))
         .highlight_style(Style::default().fg(Color::Yellow))
         .select(app.tabs.index);
     f.render_widget(tabs, chunks[0]);
@@ -45,12 +53,12 @@ fn draw_gauges(f: &mut Frame, app: &mut App, area: Rect) {
     ])
     .margin(1)
     .split(area);
-    let block = Block::default().borders(Borders::ALL).title("Graphs");
+    let block = Block::bordered().title("Graphs");
     f.render_widget(block, area);
 
     let label = format!("{:.2}%", app.progress * 100.0);
     let gauge = Gauge::default()
-        .block(Block::default().title("Gauge:"))
+        .block(Block::new().title("Gauge:"))
         .gauge_style(
             Style::default()
                 .fg(Color::Magenta)
@@ -63,7 +71,7 @@ fn draw_gauges(f: &mut Frame, app: &mut App, area: Rect) {
     f.render_widget(gauge, chunks[0]);
 
     let sparkline = Sparkline::default()
-        .block(Block::default().title("Sparkline:"))
+        .block(Block::new().title("Sparkline:"))
         .style(Style::default().fg(Color::Green))
         .data(&app.sparkline.points)
         .bar_set(if app.enhanced_graphics {
@@ -74,8 +82,8 @@ fn draw_gauges(f: &mut Frame, app: &mut App, area: Rect) {
     f.render_widget(sparkline, chunks[1]);
 
     let line_gauge = LineGauge::default()
-        .block(Block::default().title("LineGauge:"))
-        .gauge_style(Style::default().fg(Color::Magenta))
+        .block(Block::new().title("LineGauge:"))
+        .filled_style(Style::default().fg(Color::Magenta))
         .line_set(if app.enhanced_graphics {
             symbols::line::THICK
         } else {
@@ -85,6 +93,7 @@ fn draw_gauges(f: &mut Frame, app: &mut App, area: Rect) {
     f.render_widget(line_gauge, chunks[2]);
 }
 
+#[allow(clippy::too_many_lines)]
 fn draw_charts(f: &mut Frame, app: &mut App, area: Rect) {
     let constraints = if app.show_chart {
         vec![Constraint::Percentage(50), Constraint::Percentage(50)]
@@ -108,7 +117,7 @@ fn draw_charts(f: &mut Frame, app: &mut App, area: Rect) {
                 .map(|i| ListItem::new(vec![text::Line::from(Span::raw(*i))]))
                 .collect();
             let tasks = List::new(tasks)
-                .block(Block::default().borders(Borders::ALL).title("List"))
+                .block(Block::bordered().title("List"))
                 .highlight_style(Style::default().add_modifier(Modifier::BOLD))
                 .highlight_symbol("> ");
             f.render_stateful_widget(tasks, chunks[0], &mut app.tasks.state);
@@ -136,12 +145,12 @@ fn draw_charts(f: &mut Frame, app: &mut App, area: Rect) {
                     ListItem::new(content)
                 })
                 .collect();
-            let logs = List::new(logs).block(Block::default().borders(Borders::ALL).title("List"));
+            let logs = List::new(logs).block(Block::bordered().title("List"));
             f.render_stateful_widget(logs, chunks[1], &mut app.logs.state);
         }
 
         let barchart = BarChart::default()
-            .block(Block::default().borders(Borders::ALL).title("Bar chart"))
+            .block(Block::bordered().title("Bar chart"))
             .data(&app.barchart)
             .bar_width(3)
             .bar_gap(2)
@@ -193,14 +202,12 @@ fn draw_charts(f: &mut Frame, app: &mut App, area: Rect) {
         ];
         let chart = Chart::new(datasets)
             .block(
-                Block::default()
-                    .title(Span::styled(
-                        "Chart",
-                        Style::default()
-                            .fg(Color::Cyan)
-                            .add_modifier(Modifier::BOLD),
-                    ))
-                    .borders(Borders::ALL),
+                Block::bordered().title(Span::styled(
+                    "Chart",
+                    Style::default()
+                        .fg(Color::Cyan)
+                        .add_modifier(Modifier::BOLD),
+                )),
             )
             .x_axis(
                 Axis::default()
@@ -252,7 +259,7 @@ fn draw_text(f: &mut Frame, area: Rect) {
             "One more thing is that it should display unicode characters: 10€"
         ),
     ];
-    let block = Block::default().borders(Borders::ALL).title(Span::styled(
+    let block = Block::bordered().title(Span::styled(
         "Footer",
         Style::default()
             .fg(Color::Magenta)
@@ -290,11 +297,11 @@ fn draw_second_tab(f: &mut Frame, app: &mut App, area: Rect) {
             .style(Style::default().fg(Color::Yellow))
             .bottom_margin(1),
     )
-    .block(Block::default().title("Servers").borders(Borders::ALL));
+    .block(Block::bordered().title("Servers"));
     f.render_widget(table, chunks[0]);
 
     let map = Canvas::default()
-        .block(Block::default().title("World").borders(Borders::ALL))
+        .block(Block::bordered().title("World"))
         .paint(|ctx| {
             ctx.draw(&Map {
                 color: Color::White,
@@ -388,6 +395,6 @@ fn draw_third_tab(f: &mut Frame, _app: &mut App, area: Rect) {
             Constraint::Ratio(1, 3),
         ],
     )
-    .block(Block::default().title("Colors").borders(Borders::ALL));
+    .block(Block::bordered().title("Colors"));
     f.render_widget(table, chunks[0]);
 }

examples/demo2/app.rs

@@ -1,252 +1,229 @@
 use std::time::Duration;
 
-use anyhow::{Context, Result};
-use crossterm::event::{Event, KeyCode, KeyEvent, KeyEventKind, KeyModifiers};
-use rand::Rng;
-use rand_chacha::rand_core::SeedableRng;
-use ratatui::{buffer::Cell, layout::Flex, prelude::*, widgets::Widget};
-use unicode_width::UnicodeWidthStr;
+use color_eyre::{eyre::Context, Result};
+use itertools::Itertools;
+use ratatui::{
+    backend::Backend,
+    buffer::Buffer,
+    crossterm::event::{Event, KeyCode, KeyEvent, KeyEventKind},
+    layout::{Constraint, Layout, Rect},
+    style::Color,
+    terminal::Terminal,
+    text::{Line, Span},
+    widgets::{Block, Tabs, Widget},
+};
+use strum::{Display, EnumIter, FromRepr, IntoEnumIterator};
 
 use crate::{
-    big_text::{BigTextBuilder, PixelSize},
-    Root, Term,
+    destroy,
+    tabs::{AboutTab, EmailTab, RecipeTab, TracerouteTab, WeatherTab},
+    term, THEME,
 };
 
-#[derive(Debug)]
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
 pub struct App {
-    term: Term,
-    context: AppContext,
     mode: Mode,
+    tab: Tab,
+    about_tab: AboutTab,
+    recipe_tab: RecipeTab,
+    email_tab: EmailTab,
+    traceroute_tab: TracerouteTab,
+    weather_tab: WeatherTab,
 }
 
 #[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
 enum Mode {
     #[default]
-    Normal,
+    Running,
     Destroy,
     Quit,
 }
 
-#[derive(Debug, Default, Clone, Copy)]
-pub struct AppContext {
-    pub tab_index: usize,
-    pub row_index: usize,
+#[derive(Debug, Clone, Copy, Default, Display, EnumIter, FromRepr, PartialEq, Eq)]
+enum Tab {
+    #[default]
+    About,
+    Recipe,
+    Email,
+    Traceroute,
+    Weather,
+}
+
+pub fn run(terminal: &mut Terminal<impl Backend>) -> Result<()> {
+    App::default().run(terminal)
 }
 
 impl App {
-    fn new() -> Result<Self> {
-        Ok(Self {
-            term: Term::start()?,
-            context: AppContext::default(),
-            mode: Mode::Normal,
-        })
-    }
-
-    pub fn run() -> Result<()> {
-        install_panic_hook();
-        let mut app = Self::new()?;
-        while !app.should_quit() {
-            app.draw()?;
-            app.handle_events()?;
+    /// Run the app until the user quits.
+    pub fn run(&mut self, terminal: &mut Terminal<impl Backend>) -> Result<()> {
+        while self.is_running() {
+            self.draw(terminal)?;
+            self.handle_events()?;
         }
-        Term::stop()?;
         Ok(())
     }
 
-    fn draw(&mut self) -> Result<()> {
-        self.term
+    fn is_running(&self) -> bool {
+        self.mode != Mode::Quit
+    }
+
+    /// Draw a single frame of the app.
+    fn draw(&self, terminal: &mut Terminal<impl Backend>) -> Result<()> {
+        terminal
             .draw(|frame| {
-                frame.render_widget(Root::new(&self.context), frame.size());
+                frame.render_widget(self, frame.size());
                 if self.mode == Mode::Destroy {
-                    destroy(frame);
+                    destroy::destroy(frame);
                 }
             })
-            .context("terminal.draw")?;
+            .wrap_err("terminal.draw")?;
         Ok(())
     }
 
+    /// Handle events from the terminal.
+    ///
+    /// This function is called once per frame, The events are polled from the stdin with timeout of
+    /// 1/50th of a second. This was chosen to try to match the default frame rate of a GIF in VHS.
     fn handle_events(&mut self) -> Result<()> {
-        // https://superuser.com/questions/1449366/do-60-fps-gifs-actually-exist-or-is-the-maximum-50-fps
-        const GIF_FRAME_RATE: f64 = 50.0;
-        match Term::next_event(Duration::from_secs_f64(1.0 / GIF_FRAME_RATE))? {
-            Some(Event::Key(key)) => self.handle_key_event(key),
-            Some(Event::Resize(width, height)) => {
-                Ok(self.term.resize(Rect::new(0, 0, width, height))?)
-            }
-            _ => Ok(()),
+        let timeout = Duration::from_secs_f64(1.0 / 50.0);
+        match term::next_event(timeout)? {
+            Some(Event::Key(key)) if key.kind == KeyEventKind::Press => self.handle_key_press(key),
+            _ => {}
         }
+        Ok(())
     }
 
-    fn handle_key_event(&mut self, key: KeyEvent) -> Result<()> {
-        if key.kind != KeyEventKind::Press {
-            return Ok(());
-        }
-
-        let context = &mut self.context;
-        const TAB_COUNT: usize = 5;
+    fn handle_key_press(&mut self, key: KeyEvent) {
         match key.code {
-            KeyCode::Char('q') | KeyCode::Esc => {
-                self.mode = Mode::Quit;
-            }
-            KeyCode::Tab | KeyCode::BackTab if key.modifiers.contains(KeyModifiers::SHIFT) => {
-                let tab_index = context.tab_index + TAB_COUNT; // to wrap around properly
-                context.tab_index = tab_index.saturating_sub(1) % TAB_COUNT;
-                context.row_index = 0;
-            }
-            KeyCode::Tab | KeyCode::BackTab => {
-                context.tab_index = context.tab_index.saturating_add(1) % TAB_COUNT;
-                context.row_index = 0;
-            }
-            KeyCode::Up | KeyCode::Char('k') => {
-                context.row_index = context.row_index.saturating_sub(1);
-            }
-            KeyCode::Down | KeyCode::Char('j') => {
-                context.row_index = context.row_index.saturating_add(1);
-            }
-            KeyCode::Char('d') => {
-                self.mode = Mode::Destroy;
-            }
+            KeyCode::Char('q') | KeyCode::Esc => self.mode = Mode::Quit,
+            KeyCode::Char('h') | KeyCode::Left => self.prev_tab(),
+            KeyCode::Char('l') | KeyCode::Right => self.next_tab(),
+            KeyCode::Char('k') | KeyCode::Up => self.prev(),
+            KeyCode::Char('j') | KeyCode::Down => self.next(),
+            KeyCode::Char('d') | KeyCode::Delete => self.destroy(),
             _ => {}
         };
-        Ok(())
     }
 
-    fn should_quit(&self) -> bool {
-        self.mode == Mode::Quit
+    fn prev(&mut self) {
+        match self.tab {
+            Tab::About => self.about_tab.prev_row(),
+            Tab::Recipe => self.recipe_tab.prev(),
+            Tab::Email => self.email_tab.prev(),
+            Tab::Traceroute => self.traceroute_tab.prev_row(),
+            Tab::Weather => self.weather_tab.prev(),
+        }
+    }
+
+    fn next(&mut self) {
+        match self.tab {
+            Tab::About => self.about_tab.next_row(),
+            Tab::Recipe => self.recipe_tab.next(),
+            Tab::Email => self.email_tab.next(),
+            Tab::Traceroute => self.traceroute_tab.next_row(),
+            Tab::Weather => self.weather_tab.next(),
+        }
+    }
+
+    fn prev_tab(&mut self) {
+        self.tab = self.tab.prev();
+    }
+
+    fn next_tab(&mut self) {
+        self.tab = self.tab.next();
+    }
+
+    fn destroy(&mut self) {
+        self.mode = Mode::Destroy;
     }
 }
 
-/// delay the start of the animation so it doesn't start immediately
-const DELAY: usize = 240;
-/// higher means more pixels per frame are modified in the animation
-const DRIP_SPEED: usize = 50;
-/// delay the start of the text animation so it doesn't start immediately after the initial delay
-const TEXT_DELAY: usize = 240;
+/// Implement Widget for &App rather than for App as we would otherwise have to clone or copy the
+/// entire app state on every frame. For this example, the app state is small enough that it doesn't
+/// matter, but for larger apps this can be a significant performance improvement.
+impl Widget for &App {
+    fn render(self, area: Rect, buf: &mut Buffer) {
+        let vertical = Layout::vertical([
+            Constraint::Length(1),
+            Constraint::Min(0),
+            Constraint::Length(1),
+        ]);
+        let [title_bar, tab, bottom_bar] = vertical.areas(area);
 
-/// Destroy mode activated by pressing `d`
-fn destroy(frame: &mut Frame<'_>) {
-    let frame_count = frame.count().saturating_sub(DELAY);
-    if frame_count == 0 {
-        return;
+        Block::new().style(THEME.root).render(area, buf);
+        self.render_title_bar(title_bar, buf);
+        self.render_selected_tab(tab, buf);
+        App::render_bottom_bar(bottom_bar, buf);
     }
-
-    let area = frame.size();
-    let buf = frame.buffer_mut();
-
-    drip(frame_count, area, buf);
-    text(frame_count, area, buf);
 }
 
-/// Move a bunch of random pixels down one row.
-///
-/// Each pick some random pixels and move them each down one row. This is a very inefficient way to
-/// do this, but it works well enough for this demo.
-fn drip(frame_count: usize, area: Rect, buf: &mut Buffer) {
-    // a seeded rng as we have to move the same random pixels each frame
-    let mut rng = rand_chacha::ChaCha8Rng::seed_from_u64(10);
-    let ramp_frames = 450;
-    let fractional_speed = frame_count as f64 / ramp_frames as f64;
-    let variable_speed = DRIP_SPEED as f64 * fractional_speed * fractional_speed * fractional_speed;
-    let pixel_count = (frame_count as f64 * variable_speed).floor() as usize;
-    for _ in 0..pixel_count {
-        let src_x = rng.gen_range(0..area.width);
-        let src_y = rng.gen_range(1..area.height - 2);
-        let src = buf.get_mut(src_x, src_y).clone();
-        // 1% of the time, move a blank or pixel (10:1) to the top line of the screen
-        if rng.gen_ratio(1, 100) {
-            let dest_x = rng
-                .gen_range(src_x.saturating_sub(5)..src_x.saturating_add(5))
-                .clamp(area.left(), area.right() - 1);
-            let dest_y = area.top() + 1;
+impl App {
+    fn render_title_bar(&self, area: Rect, buf: &mut Buffer) {
+        let layout = Layout::horizontal([Constraint::Min(0), Constraint::Length(43)]);
+        let [title, tabs] = layout.areas(area);
 
-            let dest = buf.get_mut(dest_x, dest_y);
-            // copy the cell to the new location about 1/10 of the time blank out the cell the rest
-            // of the time. This has the effect of gradually removing the pixels from the screen.
-            if rng.gen_ratio(1, 10) {
-                *dest = src;
-            } else {
-                *dest = Cell::default();
-            }
-        } else {
-            // move the pixel down one row
-            let dest_x = src_x;
-            let dest_y = src_y.saturating_add(1).min(area.bottom() - 2);
-            // copy the cell to the new location
-            let dest = buf.get_mut(dest_x, dest_y);
-            *dest = src;
+        Span::styled("Ratatui", THEME.app_title).render(title, buf);
+        let titles = Tab::iter().map(Tab::title);
+        Tabs::new(titles)
+            .style(THEME.tabs)
+            .highlight_style(THEME.tabs_selected)
+            .select(self.tab as usize)
+            .divider("")
+            .padding("", "")
+            .render(tabs, buf);
+    }
+
+    fn render_selected_tab(&self, area: Rect, buf: &mut Buffer) {
+        match self.tab {
+            Tab::About => self.about_tab.render(area, buf),
+            Tab::Recipe => self.recipe_tab.render(area, buf),
+            Tab::Email => self.email_tab.render(area, buf),
+            Tab::Traceroute => self.traceroute_tab.render(area, buf),
+            Tab::Weather => self.weather_tab.render(area, buf),
+        };
+    }
+
+    fn render_bottom_bar(area: Rect, buf: &mut Buffer) {
+        let keys = [
+            ("H/←", "Left"),
+            ("L/→", "Right"),
+            ("K/↑", "Up"),
+            ("J/↓", "Down"),
+            ("D/Del", "Destroy"),
+            ("Q/Esc", "Quit"),
+        ];
+        let spans = keys
+            .iter()
+            .flat_map(|(key, desc)| {
+                let key = Span::styled(format!(" {key} "), THEME.key_binding.key);
+                let desc = Span::styled(format!(" {desc} "), THEME.key_binding.description);
+                [key, desc]
+            })
+            .collect_vec();
+        Line::from(spans)
+            .centered()
+            .style((Color::Indexed(236), Color::Indexed(232)))
+            .render(area, buf);
+    }
+}
+
+impl Tab {
+    fn next(self) -> Self {
+        let current_index = self as usize;
+        let next_index = current_index.saturating_add(1);
+        Self::from_repr(next_index).unwrap_or(self)
+    }
+
+    fn prev(self) -> Self {
+        let current_index = self as usize;
+        let prev_index = current_index.saturating_sub(1);
+        Self::from_repr(prev_index).unwrap_or(self)
+    }
+
+    fn title(self) -> String {
+        match self {
+            Self::About => String::new(),
+            tab => format!(" {tab} "),
         }
     }
 }
-
-/// draw some text fading in and out from black to red and back
-fn text(frame_count: usize, area: Rect, buf: &mut Buffer) {
-    let sub_frame = frame_count.saturating_sub(TEXT_DELAY);
-    if sub_frame == 0 {
-        return;
-    }
-
-    let line = "RATATUI";
-    let big_text = BigTextBuilder::default()
-        .lines([line.into()])
-        .pixel_size(PixelSize::Full)
-        .style(Style::new().fg(Color::Rgb(255, 0, 0)))
-        .build()
-        .unwrap();
-
-    // the font size is 8x8 for each character and we have 1 line
-    let area = centered_rect(area, line.width() as u16 * 8, 8);
-
-    let mask_buf = &mut Buffer::empty(area);
-    big_text.render(area, mask_buf);
-
-    let percentage = (sub_frame as f64 / 480.0).clamp(0.0, 1.0);
-
-    for row in area.rows() {
-        for col in row.columns() {
-            let cell = buf.get_mut(col.x, col.y);
-            let mask_cell = mask_buf.get(col.x, col.y);
-            cell.set_symbol(mask_cell.symbol());
-
-            // blend the mask cell color with the cell color
-            let cell_color = cell.style().bg.unwrap_or(Color::Rgb(0, 0, 0));
-            let mask_color = mask_cell.style().fg.unwrap_or(Color::Rgb(255, 0, 0));
-
-            let color = blend(mask_color, cell_color, percentage);
-            cell.set_style(Style::new().fg(color));
-        }
-    }
-}
-
-fn blend(mask_color: Color, cell_color: Color, percentage: f64) -> Color {
-    let Color::Rgb(mask_red, mask_green, mask_blue) = mask_color else {
-        return mask_color;
-    };
-    let Color::Rgb(cell_red, cell_green, cell_blue) = cell_color else {
-        return mask_color;
-    };
-
-    let red = mask_red as f64 * percentage + cell_red as f64 * (1.0 - percentage);
-    let green = mask_green as f64 * percentage + cell_green as f64 * (1.0 - percentage);
-    let blue = mask_blue as f64 * percentage + cell_blue as f64 * (1.0 - percentage);
-
-    Color::Rgb(red as u8, green as u8, blue as u8)
-}
-
-/// a centered rect of the given size
-fn centered_rect(area: Rect, width: u16, height: u16) -> Rect {
-    let horizontal = Layout::horizontal([width]).flex(Flex::Center);
-    let vertical = Layout::vertical([height]).flex(Flex::Center);
-    let [area] = area.split(&vertical);
-    let [area] = area.split(&horizontal);
-    area
-}
-
-pub fn install_panic_hook() {
-    better_panic::install();
-    let hook = std::panic::take_hook();
-    std::panic::set_hook(Box::new(move |info| {
-        let _ = Term::stop();
-        hook(info);
-        std::process::exit(1);
-    }));
-}

examples/demo2/big_text.rs

@@ -20,7 +20,16 @@
 //!
 //! ```rust
 //! use anyhow::Result;
-//! use ratatui::prelude::*;
+//! use ratatui::{
+//!     backend::{self, Backend, CrosstermBackend},
+//!     buffer::{self, Buffer},
+//!     layout::{self, Alignment, Constraint, Direction, Layout, Margin, Rect},
+//!     style::{self, Color, Modifier, Style, Styled, Stylize},
+//!     symbols::{self, Marker},
+//!     terminal::{CompletedFrame, Frame, Terminal, TerminalOptions, Viewport},
+//!     text::{self, Line, Masked, Span, Text},
+//!     widgets::{block::BlockExt, StatefulWidget, Widget},
+//! };
 //! use tui_big_text::{BigTextBuilder, PixelSize};
 //!
 //! fn render(frame: &mut Frame) -> Result<()> {
@@ -50,7 +59,13 @@ use std::cmp::min;
 
 use derive_builder::Builder;
 use font8x8::UnicodeFonts;
-use ratatui::{prelude::*, text::StyledGrapheme, widgets::Widget};
+use ratatui::{
+    buffer::Buffer,
+    layout::Rect,
+    style::Style,
+    text::{Line, StyledGrapheme},
+    widgets::Widget,
+};
 
 #[allow(unused)]
 #[derive(Debug, Clone, Copy, Eq, PartialEq, Hash, Default)]
@@ -79,7 +94,16 @@ pub enum PixelSize {
 /// # Examples
 ///
 /// ```rust
-/// use ratatui::prelude::*;
+/// use ratatui::{
+///     backend::{self, Backend, CrosstermBackend},
+///     buffer::{self, Buffer},
+///     layout::{self, Alignment, Constraint, Direction, Layout, Margin, Rect},
+///     style::{self, Color, Modifier, Style, Styled, Stylize},
+///     symbols::{self, Marker},
+///     terminal::{CompletedFrame, Frame, Terminal, TerminalOptions, Viewport},
+///     text::{self, Line, Masked, Span, Text},
+///     widgets::{block::BlockExt, StatefulWidget, Widget},
+/// };
 /// use tui_big_text::{BigTextBuilder, PixelSize};
 ///
 /// BigText::builder()
@@ -129,24 +153,24 @@ pub struct BigText<'a> {
 
     /// The size of single glyphs
     ///
-    /// Defaults to `BigTextSize::default()` (=> BigTextSize::Full)
+    /// Defaults to `BigTextSize::default()` (=> `BigTextSize::Full`)
     #[builder(default)]
     pixel_size: PixelSize,
 }
 
 impl Widget for BigText<'_> {
     fn render(self, area: Rect, buf: &mut Buffer) {
-        let layout = layout(area, &self.pixel_size);
+        let layout = layout(area, self.pixel_size);
         for (line, line_layout) in self.lines.iter().zip(layout) {
             for (g, cell) in line.styled_graphemes(self.style).zip(line_layout) {
-                render_symbol(g, cell, buf, &self.pixel_size);
+                render_symbol(&g, cell, buf, self.pixel_size);
             }
         }
     }
 }
 
 /// Returns how many cells are needed to display a full 8x8 glyphe using the given font size
-fn cells_per_glyph(size: &PixelSize) -> (u16, u16) {
+const fn cells_per_glyph(size: PixelSize) -> (u16, u16) {
     match size {
         PixelSize::Full => (8, 8),
         PixelSize::HalfHeight => (8, 4),
@@ -160,7 +184,7 @@ fn cells_per_glyph(size: &PixelSize) -> (u16, u16) {
 /// The size of each cell depends on given font size
 fn layout(
     area: Rect,
-    pixel_size: &PixelSize,
+    pixel_size: PixelSize,
 ) -> impl IntoIterator<Item = impl IntoIterator<Item = Rect>> {
     let (width, height) = cells_per_glyph(pixel_size);
     (area.top()..area.bottom())
@@ -178,7 +202,7 @@ fn layout(
 
 /// Render a single grapheme into a cell by looking up the corresponding 8x8 bitmap in the
 /// `BITMAPS` array and setting the corresponding cells in the buffer.
-fn render_symbol(grapheme: StyledGrapheme, area: Rect, buf: &mut Buffer, pixel_size: &PixelSize) {
+fn render_symbol(grapheme: &StyledGrapheme, area: Rect, buf: &mut Buffer, pixel_size: PixelSize) {
     buf.set_style(area, grapheme.style);
     let c = grapheme.symbol.chars().next().unwrap(); // TODO: handle multi-char graphemes
     if let Some(glyph) = font8x8::BASIC_FONTS.get(c) {
@@ -187,7 +211,7 @@ fn render_symbol(grapheme: StyledGrapheme, area: Rect, buf: &mut Buffer, pixel_s
 }
 
 /// Get the correct unicode symbol for two vertical "pixels"
-fn get_symbol_half_height(top: u8, bottom: u8) -> char {
+const fn get_symbol_half_height(top: u8, bottom: u8) -> char {
     match top {
         0 => match bottom {
             0 => ' ',
@@ -201,7 +225,7 @@ fn get_symbol_half_height(top: u8, bottom: u8) -> char {
 }
 
 /// Get the correct unicode symbol for two horizontal "pixels"
-fn get_symbol_half_width(left: u8, right: u8) -> char {
+const fn get_symbol_half_width(left: u8, right: u8) -> char {
     match left {
         0 => match right {
             0 => ' ',
@@ -215,20 +239,26 @@ fn get_symbol_half_width(left: u8, right: u8) -> char {
 }
 
 /// Get the correct unicode symbol for 2x2 "pixels"
-fn get_symbol_half_size(top_left: u8, top_right: u8, bottom_left: u8, bottom_right: u8) -> char {
-    let top_left = if top_left > 0 { 1 } else { 0 };
-    let top_right = if top_right > 0 { 1 } else { 0 };
-    let bottom_left = if bottom_left > 0 { 1 } else { 0 };
-    let bottom_right = if bottom_right > 0 { 1 } else { 0 };
-
+const fn get_symbol_half_size(
+    top_left: u8,
+    top_right: u8,
+    bottom_left: u8,
+    bottom_right: u8,
+) -> char {
     const QUADRANT_SYMBOLS: [char; 16] = [
         ' ', '▘', '▝', '▀', '▖', '▌', '▞', '▛', '▗', '▚', '▐', '▜', '▄', '▙', '▟', '█',
     ];
-    QUADRANT_SYMBOLS[top_left + (top_right << 1) + (bottom_left << 2) + (bottom_right << 3)]
+
+    let top_left = if top_left > 0 { 1 } else { 0 };
+    let top_right = if top_right > 0 { 1 << 1 } else { 0 };
+    let bottom_left = if bottom_left > 0 { 1 << 2 } else { 0 };
+    let bottom_right = if bottom_right > 0 { 1 << 3 } else { 0 };
+
+    QUADRANT_SYMBOLS[top_left + top_right + bottom_left + bottom_right]
 }
 
 /// Render a single 8x8 glyph into a cell by setting the corresponding cells in the buffer.
-fn render_glyph(glyph: [u8; 8], area: Rect, buf: &mut Buffer, pixel_size: &PixelSize) {
+fn render_glyph(glyph: [u8; 8], area: Rect, buf: &mut Buffer, pixel_size: PixelSize) {
     let (width, height) = cells_per_glyph(pixel_size);
 
     let glyph_vertical_index = (0..glyph.len()).step_by(8 / height as usize);
@@ -270,7 +300,7 @@ fn render_glyph(glyph: [u8; 8], area: Rect, buf: &mut Buffer, pixel_size: &Pixel
 
 #[cfg(test)]
 mod tests {
-    use ratatui::assert_buffer_eq;
+    use ratatui::style::Stylize;
 
     use super::*;
 
@@ -302,7 +332,7 @@ mod tests {
             .build()?;
         let mut buf = Buffer::empty(Rect::new(0, 0, 80, 8));
         big_text.render(buf.area, &mut buf);
-        let expected = Buffer::with_lines(vec![
+        let expected = Buffer::with_lines([
             " ████     ██                     ███            ████      ██                    ",
             "██  ██                            ██             ██                             ",
             "███      ███    █████    ███ ██   ██     ████    ██      ███    █████    ████   ",
@@ -312,7 +342,7 @@ mod tests {
             " ████    ████   ██  ██      ██   ████    ████   ███████  ████   ██  ██   ████   ",
             "                        █████                                                   ",
         ]);
-        assert_buffer_eq!(buf, expected);
+        assert_eq!(buf, expected);
         Ok(())
     }
 
@@ -323,7 +353,7 @@ mod tests {
             .build()?;
         let mut buf = Buffer::empty(Rect::new(0, 0, 70, 6));
         big_text.render(buf.area, &mut buf);
-        let expected = Buffer::with_lines(vec![
+        let expected = Buffer::with_lines([
             "██████                                             █               ███",
             "█ ██ █                                            ██                ██",
             "  ██    ██ ███  ██  ██  █████    ████    ████    █████   ████       ██",
@@ -331,7 +361,7 @@ mod tests {
             "  ██     ██  ██ ██  ██  ██  ██  ██       █████    ██    ██████  ██  ██",
             "  ██     ██     ██  ██  ██  ██  ██  ██  ██  ██    ██ █  ██      ██  ██",
         ]);
-        assert_buffer_eq!(buf, expected);
+        assert_eq!(buf, expected);
         Ok(())
     }
 
@@ -342,7 +372,7 @@ mod tests {
             .build()?;
         let mut buf = Buffer::empty(Rect::new(0, 0, 40, 16));
         big_text.render(buf.area, &mut buf);
-        let expected = Buffer::with_lines(vec![
+        let expected = Buffer::with_lines([
             "██   ██          ███       █      ██    ",
             "███ ███           ██      ██            ",
             "███████ ██  ██    ██     █████   ███    ",
@@ -360,7 +390,7 @@ mod tests {
             "███████  ████   ██  ██   ████   █████   ",
             "                                        ",
         ]);
-        assert_buffer_eq!(buf, expected);
+        assert_eq!(buf, expected);
         Ok(())
     }
 
@@ -372,18 +402,17 @@ mod tests {
             .build()?;
         let mut buf = Buffer::empty(Rect::new(0, 0, 48, 8));
         big_text.render(buf.area, &mut buf);
-        let mut expected = Buffer::with_lines(vec![
-            " ████      █             ███               ███  ",
-            "██  ██    ██              ██                ██  ",
-            "███      █████  ██  ██    ██     ████       ██  ",
-            " ███      ██    ██  ██    ██    ██  ██   █████  ",
-            "   ███    ██    ██  ██    ██    ██████  ██  ██  ",
-            "██  ██    ██ █   █████    ██    ██      ██  ██  ",
-            " ████      ██       ██   ████    ████    ███ ██ ",
-            "                █████                           ",
+        let expected = Buffer::with_lines([
+            " ████      █             ███               ███  ".bold(),
+            "██  ██    ██              ██                ██  ".bold(),
+            "███      █████  ██  ██    ██     ████       ██  ".bold(),
+            " ███      ██    ██  ██    ██    ██  ██   █████  ".bold(),
+            "   ███    ██    ██  ██    ██    ██████  ██  ██  ".bold(),
+            "██  ██    ██ █   █████    ██    ██      ██  ██  ".bold(),
+            " ████      ██       ██   ████    ████    ███ ██ ".bold(),
+            "                █████                           ".bold(),
         ]);
-        expected.set_style(Rect::new(0, 0, 48, 8), Style::new().bold());
-        assert_buffer_eq!(buf, expected);
+        assert_eq!(buf, expected);
         Ok(())
     }
 
@@ -398,7 +427,7 @@ mod tests {
             .build()?;
         let mut buf = Buffer::empty(Rect::new(0, 0, 40, 24));
         big_text.render(buf.area, &mut buf);
-        let mut expected = Buffer::with_lines(vec![
+        let mut expected = Buffer::with_lines([
             "██████             ███                  ",
             " ██  ██             ██                  ",
             " ██  ██  ████       ██                  ",
@@ -427,7 +456,7 @@ mod tests {
         expected.set_style(Rect::new(0, 0, 24, 8), Style::new().red());
         expected.set_style(Rect::new(0, 8, 40, 8), Style::new().green());
         expected.set_style(Rect::new(0, 16, 32, 8), Style::new().blue());
-        assert_buffer_eq!(buf, expected);
+        assert_eq!(buf, expected);
         Ok(())
     }
 
@@ -439,13 +468,13 @@ mod tests {
             .build()?;
         let mut buf = Buffer::empty(Rect::new(0, 0, 80, 4));
         big_text.render(buf.area, &mut buf);
-        let expected = Buffer::with_lines(vec![
+        let expected = Buffer::with_lines([
             "▄█▀▀█▄    ▀▀                     ▀██            ▀██▀      ▀▀                    ",
             "▀██▄     ▀██    ██▀▀█▄  ▄█▀▀▄█▀   ██    ▄█▀▀█▄   ██      ▀██    ██▀▀█▄  ▄█▀▀█▄  ",
             "▄▄ ▀██    ██    ██  ██  ▀█▄▄██    ██    ██▀▀▀▀   ██  ▄█   ██    ██  ██  ██▀▀▀▀  ",
             " ▀▀▀▀    ▀▀▀▀   ▀▀  ▀▀  ▄▄▄▄█▀   ▀▀▀▀    ▀▀▀▀   ▀▀▀▀▀▀▀  ▀▀▀▀   ▀▀  ▀▀   ▀▀▀▀   ",
         ]);
-        assert_buffer_eq!(buf, expected);
+        assert_eq!(buf, expected);
         Ok(())
     }
 
@@ -457,12 +486,12 @@ mod tests {
             .build()?;
         let mut buf = Buffer::empty(Rect::new(0, 0, 70, 3));
         big_text.render(buf.area, &mut buf);
-        let expected = Buffer::with_lines(vec![
+        let expected = Buffer::with_lines([
             "█▀██▀█                                            ▄█               ▀██",
             "  ██    ▀█▄█▀█▄ ██  ██  ██▀▀█▄  ▄█▀▀█▄   ▀▀▀█▄   ▀██▀▀  ▄█▀▀█▄   ▄▄▄██",
             "  ██     ██  ▀▀ ██  ██  ██  ██  ██  ▄▄  ▄█▀▀██    ██ ▄  ██▀▀▀▀  ██  ██",
         ]);
-        assert_buffer_eq!(buf, expected);
+        assert_eq!(buf, expected);
         Ok(())
     }
 
@@ -474,7 +503,7 @@ mod tests {
             .build()?;
         let mut buf = Buffer::empty(Rect::new(0, 0, 40, 8));
         big_text.render(buf.area, &mut buf);
-        let expected = Buffer::with_lines(vec![
+        let expected = Buffer::with_lines([
             "██▄ ▄██          ▀██      ▄█      ▀▀    ",
             "███████ ██  ██    ██     ▀██▀▀   ▀██    ",
             "██ ▀ ██ ██  ██    ██      ██ ▄    ██    ",
@@ -484,7 +513,7 @@ mod tests {
             " ██  ▄█   ██    ██  ██  ██▀▀▀▀   ▀▀▀█▄  ",
             "▀▀▀▀▀▀▀  ▀▀▀▀   ▀▀  ▀▀   ▀▀▀▀   ▀▀▀▀▀   ",
         ]);
-        assert_buffer_eq!(buf, expected);
+        assert_eq!(buf, expected);
         Ok(())
     }
 
@@ -497,14 +526,13 @@ mod tests {
             .build()?;
         let mut buf = Buffer::empty(Rect::new(0, 0, 48, 4));
         big_text.render(buf.area, &mut buf);
-        let mut expected = Buffer::with_lines(vec![
-            "▄█▀▀█▄    ▄█             ▀██               ▀██  ",
-            "▀██▄     ▀██▀▀  ██  ██    ██    ▄█▀▀█▄   ▄▄▄██  ",
-            "▄▄ ▀██    ██ ▄  ▀█▄▄██    ██    ██▀▀▀▀  ██  ██  ",
-            " ▀▀▀▀      ▀▀   ▄▄▄▄█▀   ▀▀▀▀    ▀▀▀▀    ▀▀▀ ▀▀ ",
+        let expected = Buffer::with_lines([
+            "▄█▀▀█▄    ▄█             ▀██               ▀██  ".bold(),
+            "▀██▄     ▀██▀▀  ██  ██    ██    ▄█▀▀█▄   ▄▄▄██  ".bold(),
+            "▄▄ ▀██    ██ ▄  ▀█▄▄██    ██    ██▀▀▀▀  ██  ██  ".bold(),
+            " ▀▀▀▀      ▀▀   ▄▄▄▄█▀   ▀▀▀▀    ▀▀▀▀    ▀▀▀ ▀▀ ".bold(),
         ]);
-        expected.set_style(Rect::new(0, 0, 48, 4), Style::new().bold());
-        assert_buffer_eq!(buf, expected);
+        assert_eq!(buf, expected);
         Ok(())
     }
 
@@ -520,7 +548,7 @@ mod tests {
             .build()?;
         let mut buf = Buffer::empty(Rect::new(0, 0, 40, 12));
         big_text.render(buf.area, &mut buf);
-        let mut expected = Buffer::with_lines(vec![
+        let mut expected = Buffer::with_lines([
             "▀██▀▀█▄            ▀██                  ",
             " ██▄▄█▀ ▄█▀▀█▄   ▄▄▄██                  ",
             " ██ ▀█▄ ██▀▀▀▀  ██  ██                  ",
@@ -537,7 +565,7 @@ mod tests {
         expected.set_style(Rect::new(0, 0, 24, 4), Style::new().red());
         expected.set_style(Rect::new(0, 4, 40, 4), Style::new().green());
         expected.set_style(Rect::new(0, 8, 32, 4), Style::new().blue());
-        assert_buffer_eq!(buf, expected);
+        assert_eq!(buf, expected);
         Ok(())
     }
 
@@ -549,7 +577,7 @@ mod tests {
             .build()?;
         let mut buf = Buffer::empty(Rect::new(0, 0, 40, 8));
         big_text.render(buf.area, &mut buf);
-        let expected = Buffer::with_lines(vec![
+        let expected = Buffer::with_lines([
             "▐█▌  █          ▐█      ██   █          ",
             "█ █              █      ▐▌              ",
             "█▌  ▐█  ██▌ ▐█▐▌ █  ▐█▌ ▐▌  ▐█  ██▌ ▐█▌ ",
@@ -559,7 +587,7 @@ mod tests {
             "▐█▌ ▐█▌ █ █   █ ▐█▌ ▐█▌ ███▌▐█▌ █ █ ▐█▌ ",
             "            ██▌                         ",
         ]);
-        assert_buffer_eq!(buf, expected);
+        assert_eq!(buf, expected);
         Ok(())
     }
 
@@ -571,7 +599,7 @@ mod tests {
             .build()?;
         let mut buf = Buffer::empty(Rect::new(0, 0, 35, 6));
         big_text.render(buf.area, &mut buf);
-        let expected = Buffer::with_lines(vec![
+        let expected = Buffer::with_lines([
             "███                      ▐       ▐█",
             "▌█▐                      █        █",
             " █  █▐█ █ █ ██▌ ▐█▌ ▐█▌ ▐██ ▐█▌   █",
@@ -579,7 +607,7 @@ mod tests {
             " █  ▐▌▐▌█ █ █ █ █   ▐██  █  ███ █ █",
             " █  ▐▌  █ █ █ █ █ █ █ █  █▐ █   █ █",
         ]);
-        assert_buffer_eq!(buf, expected);
+        assert_eq!(buf, expected);
         Ok(())
     }
 
@@ -591,7 +619,7 @@ mod tests {
             .build()?;
         let mut buf = Buffer::empty(Rect::new(0, 0, 20, 16));
         big_text.render(buf.area, &mut buf);
-        let expected = Buffer::with_lines(vec![
+        let expected = Buffer::with_lines([
             "█ ▐▌    ▐█   ▐   █  ",
             "█▌█▌     █   █      ",
             "███▌█ █  █  ▐██ ▐█  ",
@@ -609,7 +637,7 @@ mod tests {
             "███▌▐█▌ █ █ ▐█▌ ██▌ ",
             "                    ",
         ]);
-        assert_buffer_eq!(buf, expected);
+        assert_eq!(buf, expected);
         Ok(())
     }
 
@@ -622,18 +650,17 @@ mod tests {
             .build()?;
         let mut buf = Buffer::empty(Rect::new(0, 0, 24, 8));
         big_text.render(buf.area, &mut buf);
-        let mut expected = Buffer::with_lines(vec![
-            "▐█▌  ▐      ▐█       ▐█ ",
-            "█ █  █       █        █ ",
-            "█▌  ▐██ █ █  █  ▐█▌   █ ",
-            "▐█   █  █ █  █  █ █ ▐██ ",
-            " ▐█  █  █ █  █  ███ █ █ ",
-            "█ █  █▐ ▐██  █  █   █ █ ",
-            "▐█▌  ▐▌   █ ▐█▌ ▐█▌ ▐█▐▌",
-            "        ██▌             ",
+        let expected = Buffer::with_lines([
+            "▐█▌  ▐      ▐█       ▐█ ".bold(),
+            "█ █  █       █        █ ".bold(),
+            "█▌  ▐██ █ █  █  ▐█▌   █ ".bold(),
+            "▐█   █  █ █  █  █ █ ▐██ ".bold(),
+            " ▐█  █  █ █  █  ███ █ █ ".bold(),
+            "█ █  █▐ ▐██  █  █   █ █ ".bold(),
+            "▐█▌  ▐▌   █ ▐█▌ ▐█▌ ▐█▐▌".bold(),
+            "        ██▌             ".bold(),
         ]);
-        expected.set_style(Rect::new(0, 0, 24, 8), Style::new().bold());
-        assert_buffer_eq!(buf, expected);
+        assert_eq!(buf, expected);
         Ok(())
     }
 
@@ -649,7 +676,7 @@ mod tests {
             .build()?;
         let mut buf = Buffer::empty(Rect::new(0, 0, 20, 24));
         big_text.render(buf.area, &mut buf);
-        let mut expected = Buffer::with_lines(vec![
+        let mut expected = Buffer::with_lines([
             "███      ▐█         ",
             "▐▌▐▌      █         ",
             "▐▌▐▌▐█▌   █         ",
@@ -678,7 +705,7 @@ mod tests {
         expected.set_style(Rect::new(0, 0, 12, 8), Style::new().red());
         expected.set_style(Rect::new(0, 8, 20, 8), Style::new().green());
         expected.set_style(Rect::new(0, 16, 16, 8), Style::new().blue());
-        assert_buffer_eq!(buf, expected);
+        assert_eq!(buf, expected);
         Ok(())
     }
 
@@ -711,13 +738,13 @@ mod tests {
             .build()?;
         let mut buf = Buffer::empty(Rect::new(0, 0, 40, 4));
         big_text.render(buf.area, &mut buf);
-        let expected = Buffer::with_lines(vec![
+        let expected = Buffer::with_lines([
             "▟▀▙  ▀          ▝█      ▜▛   ▀          ",
             "▜▙  ▝█  █▀▙ ▟▀▟▘ █  ▟▀▙ ▐▌  ▝█  █▀▙ ▟▀▙ ",
             "▄▝█  █  █ █ ▜▄█  █  █▀▀ ▐▌▗▌ █  █ █ █▀▀ ",
             "▝▀▘ ▝▀▘ ▀ ▀ ▄▄▛ ▝▀▘ ▝▀▘ ▀▀▀▘▝▀▘ ▀ ▀ ▝▀▘ ",
         ]);
-        assert_buffer_eq!(buf, expected);
+        assert_eq!(buf, expected);
         Ok(())
     }
 
@@ -729,12 +756,12 @@ mod tests {
             .build()?;
         let mut buf = Buffer::empty(Rect::new(0, 0, 35, 3));
         big_text.render(buf.area, &mut buf);
-        let expected = Buffer::with_lines(vec![
+        let expected = Buffer::with_lines([
             "▛█▜                      ▟       ▝█",
             " █  ▜▟▜▖█ █ █▀▙ ▟▀▙ ▝▀▙ ▝█▀ ▟▀▙ ▗▄█",
             " █  ▐▌▝▘█ █ █ █ █ ▄ ▟▀█  █▗ █▀▀ █ █",
         ]);
-        assert_buffer_eq!(buf, expected);
+        assert_eq!(buf, expected);
         Ok(())
     }
 
@@ -746,7 +773,7 @@ mod tests {
             .build()?;
         let mut buf = Buffer::empty(Rect::new(0, 0, 20, 8));
         big_text.render(buf.area, &mut buf);
-        let expected = Buffer::with_lines(vec![
+        let expected = Buffer::with_lines([
             "█▖▟▌    ▝█   ▟   ▀  ",
             "███▌█ █  █  ▝█▀ ▝█  ",
             "█▝▐▌█ █  █   █▗  █  ",
@@ -756,7 +783,7 @@ mod tests {
             "▐▌▗▌ █  █ █ █▀▀ ▝▀▙ ",
             "▀▀▀▘▝▀▘ ▀ ▀ ▝▀▘ ▀▀▘ ",
         ]);
-        assert_buffer_eq!(buf, expected);
+        assert_eq!(buf, expected);
         Ok(())
     }
 
@@ -769,14 +796,13 @@ mod tests {
             .build()?;
         let mut buf = Buffer::empty(Rect::new(0, 0, 24, 4));
         big_text.render(buf.area, &mut buf);
-        let mut expected = Buffer::with_lines(vec![
-            "▟▀▙  ▟      ▝█       ▝█ ",
-            "▜▙  ▝█▀ █ █  █  ▟▀▙ ▗▄█ ",
-            "▄▝█  █▗ ▜▄█  █  █▀▀ █ █ ",
-            "▝▀▘  ▝▘ ▄▄▛ ▝▀▘ ▝▀▘ ▝▀▝▘",
+        let expected = Buffer::with_lines([
+            "▟▀▙  ▟      ▝█       ▝█ ".bold(),
+            "▜▙  ▝█▀ █ █  █  ▟▀▙ ▗▄█ ".bold(),
+            "▄▝█  █▗ ▜▄█  █  █▀▀ █ █ ".bold(),
+            "▝▀▘  ▝▘ ▄▄▛ ▝▀▘ ▝▀▘ ▝▀▝▘".bold(),
         ]);
-        expected.set_style(Rect::new(0, 0, 24, 4), Style::new().bold());
-        assert_buffer_eq!(buf, expected);
+        assert_eq!(buf, expected);
         Ok(())
     }
 
@@ -792,7 +818,7 @@ mod tests {
             .build()?;
         let mut buf = Buffer::empty(Rect::new(0, 0, 20, 12));
         big_text.render(buf.area, &mut buf);
-        let mut expected = Buffer::with_lines(vec![
+        let mut expected = Buffer::with_lines([
             "▜▛▜▖     ▝█         ",
             "▐▙▟▘▟▀▙ ▗▄█         ",
             "▐▌▜▖█▀▀ █ █         ",
@@ -809,7 +835,7 @@ mod tests {
         expected.set_style(Rect::new(0, 0, 12, 4), Style::new().red());
         expected.set_style(Rect::new(0, 4, 20, 4), Style::new().green());
         expected.set_style(Rect::new(0, 8, 16, 4), Style::new().blue());
-        assert_buffer_eq!(buf, expected);
+        assert_eq!(buf, expected);
         Ok(())
     }
 }

examples/demo2/colors.rs

@@ -1,5 +1,5 @@
 use palette::{IntoColor, Okhsv, Srgb};
-use ratatui::{prelude::*, widgets::*};
+use ratatui::{buffer::Buffer, layout::Rect, style::Color, widgets::Widget};
 
 /// A widget that renders a color swatch of RGB colors.
 ///
@@ -9,13 +9,14 @@ use ratatui::{prelude::*, widgets::*};
 pub struct RgbSwatch;
 
 impl Widget for RgbSwatch {
+    #[allow(clippy::cast_precision_loss, clippy::similar_names)]
     fn render(self, area: Rect, buf: &mut Buffer) {
         for (yi, y) in (area.top()..area.bottom()).enumerate() {
-            let value = area.height as f32 - yi as f32;
-            let value_fg = value / (area.height as f32);
-            let value_bg = (value - 0.5) / (area.height as f32);
+            let value = f32::from(area.height) - yi as f32;
+            let value_fg = value / f32::from(area.height);
+            let value_bg = (value - 0.5) / f32::from(area.height);
             for (xi, x) in (area.left()..area.right()).enumerate() {
-                let hue = xi as f32 * 360.0 / area.width as f32;
+                let hue = xi as f32 * 360.0 / f32::from(area.width);
                 let fg = color_from_oklab(hue, Okhsv::max_saturation(), value_fg);
                 let bg = color_from_oklab(hue, Okhsv::max_saturation(), value_bg);
                 buf.get_mut(x, y).set_char('▀').set_fg(fg).set_bg(bg);
@@ -24,7 +25,7 @@ impl Widget for RgbSwatch {
     }
 }
 
-/// Convert a hue and value into an RGB color via the OkLab color space.
+/// Convert a hue and value into an RGB color via the Oklab color space.
 ///
 /// See <https://bottosson.github.io/posts/oklab/> for more details.
 pub fn color_from_oklab(hue: f32, saturation: f32, value: f32) -> Color {

examples/demo2/destroy.rs

@@ -0,0 +1,146 @@
+use rand::Rng;
+use rand_chacha::rand_core::SeedableRng;
+use ratatui::{
+    buffer::Buffer,
+    layout::{Flex, Layout, Rect},
+    style::{Color, Style},
+    terminal::Frame,
+    widgets::Widget,
+};
+use unicode_width::UnicodeWidthStr;
+
+use crate::big_text::{BigTextBuilder, PixelSize};
+
+/// delay the start of the animation so it doesn't start immediately
+const DELAY: usize = 240;
+/// higher means more pixels per frame are modified in the animation
+const DRIP_SPEED: usize = 50;
+/// delay the start of the text animation so it doesn't start immediately after the initial delay
+const TEXT_DELAY: usize = 240;
+
+/// Destroy mode activated by pressing `d`
+pub fn destroy(frame: &mut Frame<'_>) {
+    let frame_count = frame.count().saturating_sub(DELAY);
+    if frame_count == 0 {
+        return;
+    }
+
+    let area = frame.size();
+    let buf = frame.buffer_mut();
+
+    drip(frame_count, area, buf);
+    text(frame_count, area, buf);
+}
+
+/// Move a bunch of random pixels down one row.
+///
+/// Each pick some random pixels and move them each down one row. This is a very inefficient way to
+/// do this, but it works well enough for this demo.
+#[allow(
+    clippy::cast_possible_truncation,
+    clippy::cast_precision_loss,
+    clippy::cast_sign_loss
+)]
+fn drip(frame_count: usize, area: Rect, buf: &mut Buffer) {
+    // a seeded rng as we have to move the same random pixels each frame
+    let mut rng = rand_chacha::ChaCha8Rng::seed_from_u64(10);
+    let ramp_frames = 450;
+    let fractional_speed = frame_count as f64 / f64::from(ramp_frames);
+    let variable_speed = DRIP_SPEED as f64 * fractional_speed * fractional_speed * fractional_speed;
+    let pixel_count = (frame_count as f64 * variable_speed).floor() as usize;
+    for _ in 0..pixel_count {
+        let src_x = rng.gen_range(0..area.width);
+        let src_y = rng.gen_range(1..area.height - 2);
+        let src = buf.get_mut(src_x, src_y).clone();
+        // 1% of the time, move a blank or pixel (10:1) to the top line of the screen
+        if rng.gen_ratio(1, 100) {
+            let dest_x = rng
+                .gen_range(src_x.saturating_sub(5)..src_x.saturating_add(5))
+                .clamp(area.left(), area.right() - 1);
+            let dest_y = area.top() + 1;
+
+            let dest = buf.get_mut(dest_x, dest_y);
+            // copy the cell to the new location about 1/10 of the time blank out the cell the rest
+            // of the time. This has the effect of gradually removing the pixels from the screen.
+            if rng.gen_ratio(1, 10) {
+                *dest = src;
+            } else {
+                dest.reset();
+            }
+        } else {
+            // move the pixel down one row
+            let dest_x = src_x;
+            let dest_y = src_y.saturating_add(1).min(area.bottom() - 2);
+            // copy the cell to the new location
+            let dest = buf.get_mut(dest_x, dest_y);
+            *dest = src;
+        }
+    }
+}
+
+/// draw some text fading in and out from black to red and back
+#[allow(clippy::cast_possible_truncation, clippy::cast_precision_loss)]
+fn text(frame_count: usize, area: Rect, buf: &mut Buffer) {
+    let sub_frame = frame_count.saturating_sub(TEXT_DELAY);
+    if sub_frame == 0 {
+        return;
+    }
+
+    let line = "RATATUI";
+    let big_text = BigTextBuilder::default()
+        .lines([line.into()])
+        .pixel_size(PixelSize::Full)
+        .style(Style::new().fg(Color::Rgb(255, 0, 0)))
+        .build()
+        .unwrap();
+
+    // the font size is 8x8 for each character and we have 1 line
+    let area = centered_rect(area, line.width() as u16 * 8, 8);
+
+    let mask_buf = &mut Buffer::empty(area);
+    big_text.render(area, mask_buf);
+
+    let percentage = (sub_frame as f64 / 480.0).clamp(0.0, 1.0);
+
+    for row in area.rows() {
+        for col in row.columns() {
+            let cell = buf.get_mut(col.x, col.y);
+            let mask_cell = mask_buf.get(col.x, col.y);
+            cell.set_symbol(mask_cell.symbol());
+
+            // blend the mask cell color with the cell color
+            let cell_color = cell.style().bg.unwrap_or(Color::Rgb(0, 0, 0));
+            let mask_color = mask_cell.style().fg.unwrap_or(Color::Rgb(255, 0, 0));
+
+            let color = blend(mask_color, cell_color, percentage);
+            cell.set_style(Style::new().fg(color));
+        }
+    }
+}
+
+fn blend(mask_color: Color, cell_color: Color, percentage: f64) -> Color {
+    let Color::Rgb(mask_red, mask_green, mask_blue) = mask_color else {
+        return mask_color;
+    };
+    let Color::Rgb(cell_red, cell_green, cell_blue) = cell_color else {
+        return mask_color;
+    };
+
+    let remain = 1.0 - percentage;
+
+    let red = f64::from(mask_red).mul_add(percentage, f64::from(cell_red) * remain);
+    let green = f64::from(mask_green).mul_add(percentage, f64::from(cell_green) * remain);
+    let blue = f64::from(mask_blue).mul_add(percentage, f64::from(cell_blue) * remain);
+
+    #[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
+    Color::Rgb(red as u8, green as u8, blue as u8)
+}
+
+/// a centered rect of the given size
+fn centered_rect(area: Rect, width: u16, height: u16) -> Rect {
+    let horizontal = Layout::horizontal([width]).flex(Flex::Center);
+    let vertical = Layout::vertical([height]).flex(Flex::Center);
+    let [area] = vertical.areas(area);
+    let [area] = horizontal.areas(area);
+    area
+}

examples/demo2/errors.rs

@@ -0,0 +1,18 @@
+use color_eyre::{config::HookBuilder, Result};
+
+use crate::term;
+
+pub fn init_hooks() -> Result<()> {
+    let (panic, error) = HookBuilder::default().into_hooks();
+    let panic = panic.into_panic_hook();
+    let error = error.into_eyre_hook();
+    color_eyre::eyre::set_hook(Box::new(move |e| {
+        let _ = term::restore();
+        error(e)
+    }))?;
+    std::panic::set_hook(Box::new(move |info| {
+        let _ = term::restore();
+        panic(info);
+    }));
+    Ok(())
+}

examples/demo2/main.rs

@@ -1,18 +1,44 @@
-use anyhow::Result;
-pub use app::*;
-pub use colors::*;
-pub use root::*;
-pub use term::*;
-pub use theme::*;
+//! # [Ratatui] Demo2 example
+//!
+//! The latest version of this example is available in the [examples] folder in the repository.
+//!
+//! Please note that the examples are designed to be run against the `main` branch of the Github
+//! repository. This means that you may not be able to compile with the latest release version on
+//! crates.io, or the one that you have installed locally.
+//!
+//! See the [examples readme] for more information on finding examples that match the version of the
+//! library you are using.
+//!
+//! [Ratatui]: https://github.com/ratatui-org/ratatui
+//! [examples]: https://github.com/ratatui-org/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui-org/ratatui/blob/main/examples/README.md
+
+#![allow(
+    clippy::missing_errors_doc,
+    clippy::module_name_repetitions,
+    clippy::must_use_candidate
+)]
 
 mod app;
 mod big_text;
 mod colors;
-mod root;
+mod destroy;
+mod errors;
 mod tabs;
 mod term;
 mod theme;
 
+use color_eyre::Result;
+
+pub use self::{
+    colors::{color_from_oklab, RgbSwatch},
+    theme::THEME,
+};
+
 fn main() -> Result<()> {
-    App::run()
+    errors::init_hooks()?;
+    let terminal = &mut term::init()?;
+    app::run(terminal)?;
+    term::restore()?;
+    Ok(())
 }

examples/demo2/root.rs

@@ -1,79 +0,0 @@
-use itertools::Itertools;
-use ratatui::{prelude::*, widgets::*};
-
-use crate::{tabs::*, AppContext, THEME};
-
-pub struct Root<'a> {
-    context: &'a AppContext,
-}
-
-impl<'a> Root<'a> {
-    pub fn new(context: &'a AppContext) -> Self {
-        Root { context }
-    }
-}
-
-impl Widget for Root<'_> {
-    fn render(self, area: Rect, buf: &mut Buffer) {
-        Block::new().style(THEME.root).render(area, buf);
-        let vertical = Layout::vertical([
-            Constraint::Length(1),
-            Constraint::Min(0),
-            Constraint::Length(1),
-        ]);
-        let [title_bar, tab, bottom_bar] = area.split(&vertical);
-        self.render_title_bar(title_bar, buf);
-        self.render_selected_tab(tab, buf);
-        self.render_bottom_bar(bottom_bar, buf);
-    }
-}
-
-impl Root<'_> {
-    fn render_title_bar(&self, area: Rect, buf: &mut Buffer) {
-        let horizontal = Layout::horizontal([Constraint::Min(0), Constraint::Length(45)]);
-        let [title, tabs] = area.split(&horizontal);
-
-        Paragraph::new(Span::styled("Ratatui", THEME.app_title)).render(title, buf);
-        let titles = vec!["", " Recipe ", " Email ", " Traceroute ", " Weather "];
-        Tabs::new(titles)
-            .style(THEME.tabs)
-            .highlight_style(THEME.tabs_selected)
-            .select(self.context.tab_index)
-            .divider("")
-            .render(tabs, buf);
-    }
-
-    fn render_selected_tab(&self, area: Rect, buf: &mut Buffer) {
-        let row_index = self.context.row_index;
-        match self.context.tab_index {
-            0 => AboutTab::new(row_index).render(area, buf),
-            1 => RecipeTab::new(row_index).render(area, buf),
-            2 => EmailTab::new(row_index).render(area, buf),
-            3 => TracerouteTab::new(row_index).render(area, buf),
-            4 => WeatherTab::new(row_index).render(area, buf),
-            _ => unreachable!(),
-        };
-    }
-
-    fn render_bottom_bar(&self, area: Rect, buf: &mut Buffer) {
-        let keys = [
-            ("Q/Esc", "Quit"),
-            ("Tab", "Next Tab"),
-            ("↑/k", "Up"),
-            ("↓/j", "Down"),
-        ];
-        let spans = keys
-            .iter()
-            .flat_map(|(key, desc)| {
-                let key = Span::styled(format!(" {} ", key), THEME.key_binding.key);
-                let desc = Span::styled(format!(" {} ", desc), THEME.key_binding.description);
-                [key, desc]
-            })
-            .collect_vec();
-        Paragraph::new(Line::from(spans))
-            .alignment(Alignment::Center)
-            .fg(Color::Indexed(236))
-            .bg(Color::Indexed(232))
-            .render(area, buf);
-    }
-}

examples/demo2/tabs/about.rs

@@ -1,5 +1,9 @@
 use itertools::Itertools;
-use ratatui::{prelude::*, widgets::*};
+use ratatui::{
+    buffer::Buffer,
+    layout::{Alignment, Constraint, Layout, Margin, Rect},
+    widgets::{Block, Borders, Clear, Padding, Paragraph, Widget, Wrap},
+};
 
 use crate::{RgbSwatch, THEME};
 
@@ -38,13 +42,18 @@ const RATATUI_LOGO: [&str; 32] = [
     "  █xxxxxxxxxxxxxxxxxxxxx█ █     ",
 ];
 
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
 pub struct AboutTab {
-    selected_row: usize,
+    row_index: usize,
 }
 
 impl AboutTab {
-    pub fn new(selected_row: usize) -> Self {
-        Self { selected_row }
+    pub fn prev_row(&mut self) {
+        self.row_index = self.row_index.saturating_sub(1);
+    }
+
+    pub fn next_row(&mut self) {
+        self.row_index = self.row_index.saturating_add(1);
     }
 }
 
@@ -52,27 +61,23 @@ impl Widget for AboutTab {
     fn render(self, area: Rect, buf: &mut Buffer) {
         RgbSwatch.render(area, buf);
         let horizontal = Layout::horizontal([Constraint::Length(34), Constraint::Min(0)]);
-        let [description, logo] = area.split(&horizontal);
+        let [description, logo] = horizontal.areas(area);
         render_crate_description(description, buf);
-        render_logo(self.selected_row, logo, buf);
+        render_logo(self.row_index, logo, buf);
     }
 }
 
 fn render_crate_description(area: Rect, buf: &mut Buffer) {
-    let area = area.inner(
-        &(Margin {
-            vertical: 4,
-            horizontal: 2,
-        }),
-    );
+    let area = area.inner(Margin {
+        vertical: 4,
+        horizontal: 2,
+    });
     Clear.render(area, buf); // clear out the color swatches
     Block::new().style(THEME.content).render(area, buf);
-    let area = area.inner(
-        &(Margin {
-            vertical: 1,
-            horizontal: 2,
-        }),
-    );
+    let area = area.inner(Margin {
+        vertical: 1,
+        horizontal: 2,
+    });
     let text = "- cooking up terminal user interfaces -
 
     Ratatui is a Rust crate that provides widgets (e.g. Paragraph, Table) and draws them to the \
@@ -92,17 +97,18 @@ fn render_crate_description(area: Rect, buf: &mut Buffer) {
         .render(area, buf);
 }
 
-/// Use half block characters to render a logo based on the RATATUI_LOGO const.
+/// Use half block characters to render a logo based on the `RATATUI_LOGO` const.
 ///
 /// The logo is rendered in three colors, one for the rat, one for the terminal, and one for the
 /// rat's eye. The eye color alternates between two colors based on the selected row.
+#[allow(clippy::cast_possible_truncation)]
 pub fn render_logo(selected_row: usize, area: Rect, buf: &mut Buffer) {
     let eye_color = if selected_row % 2 == 0 {
         THEME.logo.rat_eye
     } else {
         THEME.logo.rat_eye_alt
     };
-    let area = area.inner(&Margin {
+    let area = area.inner(Margin {
         vertical: 0,
         horizontal: 2,
     });

examples/demo2/tabs/email.rs

@@ -1,5 +1,14 @@
 use itertools::Itertools;
-use ratatui::{prelude::*, widgets::*};
+use ratatui::{
+    buffer::Buffer,
+    layout::{Constraint, Layout, Margin, Rect},
+    style::{Styled, Stylize},
+    text::Line,
+    widgets::{
+        Block, BorderType, Borders, Clear, List, ListItem, ListState, Padding, Paragraph,
+        Scrollbar, ScrollbarState, StatefulWidget, Tabs, Widget,
+    },
+};
 use unicode_width::UnicodeWidthStr;
 
 use crate::{RgbSwatch, THEME};
@@ -39,36 +48,40 @@ const EMAILS: &[Email] = &[
     },
 ];
 
-#[derive(Debug, Default)]
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
 pub struct EmailTab {
-    selected_index: usize,
+    row_index: usize,
 }
 
 impl EmailTab {
-    pub fn new(selected_index: usize) -> Self {
-        Self {
-            selected_index: selected_index % EMAILS.len(),
-        }
+    /// Select the previous email (with wrap around).
+    pub fn prev(&mut self) {
+        self.row_index = self.row_index.saturating_add(EMAILS.len() - 1) % EMAILS.len();
+    }
+
+    /// Select the next email (with wrap around).
+    pub fn next(&mut self) {
+        self.row_index = self.row_index.saturating_add(1) % EMAILS.len();
     }
 }
 
 impl Widget for EmailTab {
     fn render(self, area: Rect, buf: &mut Buffer) {
         RgbSwatch.render(area, buf);
-        let area = area.inner(&Margin {
+        let area = area.inner(Margin {
             vertical: 1,
             horizontal: 2,
         });
         Clear.render(area, buf);
         let vertical = Layout::vertical([Constraint::Length(5), Constraint::Min(0)]);
-        let [inbox, email] = area.split(&vertical);
-        render_inbox(self.selected_index, inbox, buf);
-        render_email(self.selected_index, email, buf);
+        let [inbox, email] = vertical.areas(area);
+        render_inbox(self.row_index, inbox, buf);
+        render_email(self.row_index, email, buf);
     }
 }
 fn render_inbox(selected_index: usize, area: Rect, buf: &mut Buffer) {
     let vertical = Layout::vertical([Constraint::Length(1), Constraint::Min(0)]);
-    let [tabs, inbox] = area.split(&vertical);
+    let [tabs, inbox] = vertical.areas(area);
     let theme = THEME.email;
     Tabs::new(vec![" Inbox ", " Sent ", " Drafts "])
         .style(theme.tabs)
@@ -123,7 +136,7 @@ fn render_email(selected_index: usize, area: Rect, buf: &mut Buffer) {
     block.render(area, buf);
     if let Some(email) = email {
         let vertical = Layout::vertical([Constraint::Length(3), Constraint::Min(0)]);
-        let [headers_area, body_area] = inner.split(&vertical);
+        let [headers_area, body_area] = vertical.areas(inner);
         let headers = vec![
             Line::from(vec![
                 "From: ".set_style(theme.header),

examples/demo2/tabs/recipe.rs

@@ -1,5 +1,14 @@
 use itertools::Itertools;
-use ratatui::{prelude::*, widgets::*};
+use ratatui::{
+    buffer::Buffer,
+    layout::{Alignment, Constraint, Layout, Margin, Rect},
+    style::{Style, Stylize},
+    text::Line,
+    widgets::{
+        Block, Clear, Padding, Paragraph, Row, Scrollbar, ScrollbarOrientation, ScrollbarState,
+        StatefulWidget, Table, TableState, Widget, Wrap,
+    },
+};
 
 use crate::{RgbSwatch, THEME};
 
@@ -10,6 +19,7 @@ struct Ingredient {
 }
 
 impl Ingredient {
+    #[allow(clippy::cast_possible_truncation)]
     fn height(&self) -> u16 {
         self.name.lines().count() as u16
     }
@@ -84,23 +94,27 @@ const INGREDIENTS: &[Ingredient] = &[
     },
 ];
 
-#[derive(Debug)]
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
 pub struct RecipeTab {
-    selected_row: usize,
+    row_index: usize,
 }
 
 impl RecipeTab {
-    pub fn new(selected_row: usize) -> Self {
-        Self {
-            selected_row: selected_row % INGREDIENTS.len(),
-        }
+    /// Select the previous item in the ingredients list (with wrap around)
+    pub fn prev(&mut self) {
+        self.row_index = self.row_index.saturating_add(INGREDIENTS.len() - 1) % INGREDIENTS.len();
+    }
+
+    /// Select the next item in the ingredients list (with wrap around)
+    pub fn next(&mut self) {
+        self.row_index = self.row_index.saturating_add(1) % INGREDIENTS.len();
     }
 }
 
 impl Widget for RecipeTab {
     fn render(self, area: Rect, buf: &mut Buffer) {
         RgbSwatch.render(area, buf);
-        let area = area.inner(&Margin {
+        let area = area.inner(Margin {
             vertical: 1,
             horizontal: 2,
         });
@@ -117,19 +131,17 @@ impl Widget for RecipeTab {
             height: area.height - 3,
             ..area
         };
-        render_scrollbar(self.selected_row, scrollbar_area, buf);
+        render_scrollbar(self.row_index, scrollbar_area, buf);
 
-        let area = area.inner(&Margin {
+        let area = area.inner(Margin {
             horizontal: 2,
             vertical: 1,
         });
-        let [recipe, ingredients] = area.split(&Layout::horizontal([
-            Constraint::Length(44),
-            Constraint::Min(0),
-        ]));
+        let [recipe, ingredients] =
+            Layout::horizontal([Constraint::Length(44), Constraint::Min(0)]).areas(area);
 
         render_recipe(recipe, buf);
-        render_ingredients(self.selected_row, ingredients, buf);
+        render_ingredients(self.row_index, ingredients, buf);
     }
 }
 
@@ -146,7 +158,7 @@ fn render_recipe(area: Rect, buf: &mut Buffer) {
 
 fn render_ingredients(selected_row: usize, area: Rect, buf: &mut Buffer) {
     let mut state = TableState::default().with_selected(Some(selected_row));
-    let rows = INGREDIENTS.iter().cloned();
+    let rows = INGREDIENTS.iter().copied();
     let theme = THEME.recipe;
     StatefulWidget::render(
         Table::new(rows, [Constraint::Length(7), Constraint::Length(30)])
@@ -169,5 +181,5 @@ fn render_scrollbar(position: usize, area: Rect, buf: &mut Buffer) {
         .end_symbol(None)
         .track_symbol(None)
         .thumb_symbol("▐")
-        .render(area, buf, &mut state)
+        .render(area, buf, &mut state);
 }

examples/demo2/tabs/traceroute.rs

@@ -1,28 +1,39 @@
 use itertools::Itertools;
 use ratatui::{
-    prelude::*,
-    widgets::{canvas::*, *},
+    buffer::Buffer,
+    layout::{Alignment, Constraint, Layout, Margin, Rect},
+    style::{Styled, Stylize},
+    symbols::Marker,
+    widgets::{
+        canvas::{self, Canvas, Map, MapResolution, Points},
+        Block, BorderType, Clear, Padding, Row, Scrollbar, ScrollbarOrientation, ScrollbarState,
+        Sparkline, StatefulWidget, Table, TableState, Widget,
+    },
 };
 
 use crate::{RgbSwatch, THEME};
 
-#[derive(Debug)]
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
 pub struct TracerouteTab {
-    selected_row: usize,
+    row_index: usize,
 }
 
 impl TracerouteTab {
-    pub fn new(selected_row: usize) -> Self {
-        Self {
-            selected_row: selected_row % HOPS.len(),
-        }
+    /// Select the previous row (with wrap around).
+    pub fn prev_row(&mut self) {
+        self.row_index = self.row_index.saturating_add(HOPS.len() - 1) % HOPS.len();
+    }
+
+    /// Select the next row (with wrap around).
+    pub fn next_row(&mut self) {
+        self.row_index = self.row_index.saturating_add(1) % HOPS.len();
     }
 }
 
 impl Widget for TracerouteTab {
     fn render(self, area: Rect, buf: &mut Buffer) {
         RgbSwatch.render(area, buf);
-        let area = area.inner(&Margin {
+        let area = area.inner(Margin {
             vertical: 1,
             horizontal: 2,
         });
@@ -30,12 +41,12 @@ impl Widget for TracerouteTab {
         Block::new().style(THEME.content).render(area, buf);
         let horizontal = Layout::horizontal([Constraint::Ratio(1, 2), Constraint::Ratio(1, 2)]);
         let vertical = Layout::vertical([Constraint::Min(0), Constraint::Length(3)]);
-        let [left, map] = area.split(&horizontal);
-        let [hops, pings] = left.split(&vertical);
+        let [left, map] = horizontal.areas(area);
+        let [hops, pings] = vertical.areas(left);
 
-        render_hops(self.selected_row, hops, buf);
-        render_ping(self.selected_row, pings, buf);
-        render_map(self.selected_row, map, buf);
+        render_hops(self.row_index, hops, buf);
+        render_ping(self.row_index, pings, buf);
+        render_map(self.row_index, map, buf);
     }
 }
 
@@ -45,10 +56,10 @@ fn render_hops(selected_row: usize, area: Rect, buf: &mut Buffer) {
         .iter()
         .map(|hop| Row::new(vec![hop.host, hop.address]))
         .collect_vec();
-    let block = Block::default()
-        .title("Traceroute bad.horse".bold().white())
+    let block = Block::new()
+        .padding(Padding::new(1, 1, 1, 1))
         .title_alignment(Alignment::Center)
-        .padding(Padding::new(1, 1, 1, 1));
+        .title("Traceroute bad.horse".bold().white());
     StatefulWidget::render(
         Table::new(rows, [Constraint::Max(100), Constraint::Length(15)])
             .header(Row::new(vec!["Host", "Address"]).set_style(THEME.traceroute.header))
@@ -100,7 +111,7 @@ fn render_map(selected_row: usize, area: Rect, buf: &mut Buffer) {
     let theme = THEME.traceroute.map;
     let path: Option<(&Hop, &Hop)> = HOPS.iter().tuple_windows().nth(selected_row);
     let map = Map {
-        resolution: canvas::MapResolution::High,
+        resolution: MapResolution::High,
         color: theme.color,
     };
     Canvas::default()

examples/demo2/tabs/weather.rs

@@ -1,61 +1,71 @@
 use itertools::Itertools;
 use palette::Okhsv;
 use ratatui::{
-    prelude::*,
-    widgets::{calendar::CalendarEventStore, *},
+    buffer::Buffer,
+    layout::{Constraint, Direction, Layout, Margin, Rect},
+    style::{Color, Style, Stylize},
+    symbols,
+    widgets::{
+        calendar::{CalendarEventStore, Monthly},
+        Bar, BarChart, BarGroup, Block, Clear, LineGauge, Padding, Widget,
+    },
 };
 use time::OffsetDateTime;
 
 use crate::{color_from_oklab, RgbSwatch, THEME};
 
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
 pub struct WeatherTab {
-    pub selected_row: usize,
+    pub download_progress: usize,
 }
 
 impl WeatherTab {
-    pub fn new(selected_row: usize) -> Self {
-        Self { selected_row }
+    /// Simulate a download indicator by decrementing the row index.
+    pub fn prev(&mut self) {
+        self.download_progress = self.download_progress.saturating_sub(1);
+    }
+
+    /// Simulate a download indicator by incrementing the row index.
+    pub fn next(&mut self) {
+        self.download_progress = self.download_progress.saturating_add(1);
     }
 }
 
 impl Widget for WeatherTab {
     fn render(self, area: Rect, buf: &mut Buffer) {
         RgbSwatch.render(area, buf);
-        let area = area.inner(&Margin {
+        let area = area.inner(Margin {
             vertical: 1,
             horizontal: 2,
         });
         Clear.render(area, buf);
         Block::new().style(THEME.content).render(area, buf);
 
-        let area = area.inner(&Margin {
+        let area = area.inner(Margin {
             horizontal: 2,
             vertical: 1,
         });
-        let [main, _, gauges] = area.split(&Layout::vertical([
+        let [main, _, gauges] = Layout::vertical([
             Constraint::Min(0),
             Constraint::Length(1),
             Constraint::Length(1),
-        ]));
-        let [calendar, charts] = main.split(&Layout::horizontal([
-            Constraint::Length(23),
-            Constraint::Min(0),
-        ]));
-        let [simple, horizontal] = charts.split(&Layout::vertical([
-            Constraint::Length(29),
-            Constraint::Min(0),
-        ]));
+        ])
+        .areas(area);
+        let [calendar, charts] =
+            Layout::horizontal([Constraint::Length(23), Constraint::Min(0)]).areas(main);
+        let [simple, horizontal] =
+            Layout::vertical([Constraint::Length(29), Constraint::Min(0)]).areas(charts);
 
         render_calendar(calendar, buf);
         render_simple_barchart(simple, buf);
         render_horizontal_barchart(horizontal, buf);
-        render_gauge(self.selected_row, gauges, buf);
+        render_gauge(self.download_progress, gauges, buf);
     }
 }
 
 fn render_calendar(area: Rect, buf: &mut Buffer) {
     let date = OffsetDateTime::now_utc().date();
-    calendar::Monthly::new(date, CalendarEventStore::today(Style::new().red().bold()))
+    Monthly::new(date, CalendarEventStore::today(Style::new().red().bold()))
         .block(Block::new().padding(Padding::new(0, 0, 2, 0)))
         .show_month_header(Style::new().bold())
         .show_weekdays_header(Style::new().italic())
@@ -80,7 +90,7 @@ fn render_simple_barchart(area: Rect, buf: &mut Buffer) {
                 // This doesn't actually render correctly as the text is too wide for the bar
                 // See https://github.com/ratatui-org/ratatui/issues/513 for more info
                 // (the demo GIFs hack around this by hacking the calculation in bars.rs)
-                .text_value(format!("{}°", value))
+                .text_value(format!("{value}°"))
                 .style(if value > 70 {
                     Style::new().fg(Color::Red)
                 } else {
@@ -124,20 +134,22 @@ fn render_horizontal_barchart(area: Rect, buf: &mut Buffer) {
         .render(area, buf);
 }
 
+#[allow(clippy::cast_precision_loss)]
 pub fn render_gauge(progress: usize, area: Rect, buf: &mut Buffer) {
     let percent = (progress * 3).min(100) as f64;
 
     render_line_gauge(percent, area, buf);
 }
 
+#[allow(clippy::cast_possible_truncation)]
 fn render_line_gauge(percent: f64, area: Rect, buf: &mut Buffer) {
     // cycle color hue based on the percent for a neat effect yellow -> red
     let hue = 90.0 - (percent as f32 * 0.6);
     let value = Okhsv::max_value();
-    let fg = color_from_oklab(hue, Okhsv::max_saturation(), value);
-    let bg = color_from_oklab(hue, Okhsv::max_saturation(), value * 0.5);
+    let filled_color = color_from_oklab(hue, Okhsv::max_saturation(), value);
+    let unfilled_color = color_from_oklab(hue, Okhsv::max_saturation(), value * 0.5);
     let label = if percent < 100.0 {
-        format!("Downloading: {}%", percent)
+        format!("Downloading: {percent}%")
     } else {
         "Download Complete!".into()
     };
@@ -145,7 +157,8 @@ fn render_line_gauge(percent: f64, area: Rect, buf: &mut Buffer) {
         .ratio(percent / 100.0)
         .label(label)
         .style(Style::new().light_blue())
-        .gauge_style(Style::new().fg(fg).bg(bg))
+        .filled_style(Style::new().fg(filled_color))
+        .unfilled_style(Style::new().fg(unfilled_color))
         .line_set(symbols::line::THICK)
         .render(area, buf);
 }

examples/demo2/term.rs

@@ -1,71 +1,46 @@
 use std::{
-    io::{self, stdout, Stdout},
-    ops::{Deref, DerefMut},
+    io::{self, stdout},
     time::Duration,
 };
 
-use anyhow::{Context, Result};
-use crossterm::{
-    event::{self, Event},
-    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-    ExecutableCommand,
+use color_eyre::{eyre::WrapErr, Result};
+use ratatui::{
+    backend::{Backend, CrosstermBackend},
+    crossterm::{
+        event::{self, Event},
+        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+        ExecutableCommand,
+    },
+    layout::Rect,
+    terminal::{Terminal, TerminalOptions, Viewport},
 };
-use ratatui::prelude::*;
 
-/// A wrapper around the terminal that handles setting up and tearing down the terminal
-/// and provides a helper method to read events from the terminal.
-#[derive(Debug)]
-pub struct Term {
-    terminal: Terminal<CrosstermBackend<Stdout>>,
+pub fn init() -> Result<Terminal<impl Backend>> {
+    // this size is to match the size of the terminal when running the demo
+    // using vhs in a 1280x640 sized window (github social preview size)
+    let options = TerminalOptions {
+        viewport: Viewport::Fixed(Rect::new(0, 0, 81, 18)),
+    };
+    let terminal = Terminal::with_options(CrosstermBackend::new(io::stdout()), options)?;
+    enable_raw_mode().context("enable raw mode")?;
+    stdout()
+        .execute(EnterAlternateScreen)
+        .wrap_err("enter alternate screen")?;
+    Ok(terminal)
 }
 
-impl Term {
-    pub fn start() -> Result<Self> {
-        // this size is to match the size of the terminal when running the demo
-        // using vhs in a 1280x640 sized window (github social preview size)
-        let options = TerminalOptions {
-            viewport: Viewport::Fixed(Rect::new(0, 0, 81, 18)),
-        };
-        let terminal = Terminal::with_options(CrosstermBackend::new(io::stdout()), options)?;
-        enable_raw_mode().context("enable raw mode")?;
-        stdout()
-            .execute(EnterAlternateScreen)
-            .context("enter alternate screen")?;
-        Ok(Self { terminal })
-    }
-
-    pub fn stop() -> Result<()> {
-        disable_raw_mode().context("disable raw mode")?;
-        stdout()
-            .execute(LeaveAlternateScreen)
-            .context("leave alternate screen")?;
-        Ok(())
-    }
-
-    pub fn next_event(timeout: Duration) -> io::Result<Option<Event>> {
-        if !event::poll(timeout)? {
-            return Ok(None);
-        }
-        let event = event::read()?;
-        Ok(Some(event))
-    }
+pub fn restore() -> Result<()> {
+    disable_raw_mode().context("disable raw mode")?;
+    stdout()
+        .execute(LeaveAlternateScreen)
+        .wrap_err("leave alternate screen")?;
+    Ok(())
 }
 
-impl Deref for Term {
-    type Target = Terminal<CrosstermBackend<Stdout>>;
-    fn deref(&self) -> &Self::Target {
-        &self.terminal
-    }
-}
-
-impl DerefMut for Term {
-    fn deref_mut(&mut self) -> &mut Self::Target {
-        &mut self.terminal
-    }
-}
-
-impl Drop for Term {
-    fn drop(&mut self) {
-        let _ = Term::stop();
+pub fn next_event(timeout: Duration) -> Result<Option<Event>> {
+    if !event::poll(timeout)? {
+        return Ok(None);
     }
+    let event = event::read()?;
+    Ok(Some(event))
 }

examples/demo2/theme.rs

@@ -1,4 +1,4 @@
-use ratatui::prelude::*;
+use ratatui::style::{Color, Modifier, Style};
 
 pub struct Theme {
     pub root: Style,

examples/docsrs.rs

@@ -1,12 +1,35 @@
+//! # [Ratatui] Docs.rs example
+//!
+//! The latest version of this example is available in the [examples] folder in the repository.
+//!
+//! Please note that the examples are designed to be run against the `main` branch of the Github
+//! repository. This means that you may not be able to compile with the latest release version on
+//! crates.io, or the one that you have installed locally.
+//!
+//! See the [examples readme] for more information on finding examples that match the version of the
+//! library you are using.
+//!
+//! [Ratatui]: https://github.com/ratatui-org/ratatui
+//! [examples]: https://github.com/ratatui-org/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui-org/ratatui/blob/main/examples/README.md
+
 use std::io::{self, stdout};
 
-use crossterm::{
-    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-    ExecutableCommand,
+use ratatui::{
+    backend::CrosstermBackend,
+    crossterm::{
+        event::{self, Event, KeyCode},
+        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+        ExecutableCommand,
+    },
+    layout::{Constraint, Layout},
+    style::{Color, Modifier, Style, Stylize},
+    terminal::{Frame, Terminal},
+    text::{Line, Span, Text},
+    widgets::{Block, Borders, Paragraph},
 };
-use ratatui::{prelude::*, widgets::*};
 
-/// Example code for libr.rs
+/// Example code for lib.rs
 ///
 /// When cargo-rdme supports doc comments that import from code, this will be imported
 /// rather than copied to the lib.rs file.
@@ -19,7 +42,6 @@ fn main() -> io::Result<()> {
     let mut should_quit = false;
     while !should_quit {
         terminal.draw(match arg.as_str() {
-            "hello_world" => hello_world,
             "layout" => layout,
             "styling" => styling,
             _ => hello_world,
@@ -34,13 +56,11 @@ fn main() -> io::Result<()> {
 
 fn hello_world(frame: &mut Frame) {
     frame.render_widget(
-        Paragraph::new("Hello World!")
-            .block(Block::default().title("Greeting").borders(Borders::ALL)),
+        Paragraph::new("Hello World!").block(Block::bordered().title("Greeting")),
         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()? {
@@ -59,8 +79,8 @@ fn layout(frame: &mut Frame) {
         Constraint::Length(1),
     ]);
     let horizontal = Layout::horizontal([Constraint::Ratio(1, 2); 2]);
-    let [title_bar, main_area, status_bar] = frame.size().split(&vertical);
-    let [left, right] = main_area.split(&horizontal);
+    let [title_bar, main_area, status_bar] = vertical.areas(frame.size());
+    let [left, right] = horizontal.areas(main_area);
 
     frame.render_widget(
         Block::new().borders(Borders::TOP).title("Title Bar"),
@@ -70,8 +90,8 @@ fn layout(frame: &mut Frame) {
         Block::new().borders(Borders::TOP).title("Status Bar"),
         status_bar,
     );
-    frame.render_widget(Block::default().borders(Borders::ALL).title("Left"), left);
-    frame.render_widget(Block::default().borders(Borders::ALL).title("Right"), right);
+    frame.render_widget(Block::bordered().title("Left"), left);
+    frame.render_widget(Block::bordered().title("Right"), right);
 }
 
 fn styling(frame: &mut Frame) {

examples/flex.rs

@@ -1,57 +1,116 @@
+//! # [Ratatui] Flex example
+//!
+//! The latest version of this example is available in the [examples] folder in the repository.
+//!
+//! Please note that the examples are designed to be run against the `main` branch of the Github
+//! repository. This means that you may not be able to compile with the latest release version on
+//! crates.io, or the one that you have installed locally.
+//!
+//! See the [examples readme] for more information on finding examples that match the version of the
+//! library you are using.
+//!
+//! [Ratatui]: https://github.com/ratatui-org/ratatui
+//! [examples]: https://github.com/ratatui-org/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui-org/ratatui/blob/main/examples/README.md
+
 use std::io::{self, stdout};
 
 use color_eyre::{config::HookBuilder, Result};
-use crossterm::{
-    event::{self, Event, KeyCode, KeyEventKind},
-    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-    ExecutableCommand,
-};
 use ratatui::{
-    layout::{Constraint::*, Flex},
-    prelude::*,
-    style::palette::tailwind,
-    widgets::{block::Title, *},
+    backend::{Backend, CrosstermBackend},
+    buffer::Buffer,
+    crossterm::{
+        event::{self, Event, KeyCode, KeyEventKind},
+        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+        ExecutableCommand,
+    },
+    layout::{
+        Alignment,
+        Constraint::{self, Fill, Length, Max, Min, Percentage, Ratio},
+        Flex, Layout, Rect,
+    },
+    style::{palette::tailwind, Color, Modifier, Style, Stylize},
+    symbols::{self, line},
+    terminal::Terminal,
+    text::{Line, Text},
+    widgets::{
+        block::Title, Block, Paragraph, Scrollbar, ScrollbarOrientation, ScrollbarState,
+        StatefulWidget, Tabs, Widget,
+    },
 };
 use strum::{Display, EnumIter, FromRepr, IntoEnumIterator};
 
 const EXAMPLE_DATA: &[(&str, &[Constraint])] = &[
     (
-        "Min(u16) takes any excess space when using `Stretch` or `StretchLast`",
-        &[Fixed(20), Min(20), Max(20)],
+        "Min(u16) takes any excess space always",
+        &[Length(10), Min(10), Max(10), Percentage(10), Ratio(1,10)],
     ),
     (
-        "Proportional(u16) takes any excess space in all `Flex` layouts",
-        &[Length(20), Percentage(20), Ratio(1, 5), Proportional(1)],
+        "Fill(u16) takes any excess space always",
+        &[Length(20), Percentage(20), Ratio(1, 5), Fill(1)],
     ),
     (
-        "In `StretchLast`, last constraint of lowest priority takes excess space",
-        &[Length(20), Fixed(20), Percentage(20)],
+        "Here's all constraints in one line",
+        &[Length(10), Min(10), Max(10), Percentage(10), Ratio(1,10), Fill(1)],
     ),
-    ("", &[Fixed(20), Percentage(20), Length(20)]),
-    ("", &[Percentage(20), Length(20), Fixed(20)]),
-    ("", &[Length(20), Length(15)]),
-    ("Spacing has no effect in `SpaceAround` and `SpaceBetween`", &[Proportional(1), Proportional(1)]),
-    ("", &[Length(20), Fixed(20)]),
     (
-        "When not using `Flex::Stretch` or `Flex::StretchLast`,\n`Min(u16)` and `Max(u16)` collapse to their lowest values",
+        "",
+        &[Max(50), Min(50)],
+    ),
+    (
+        "",
+        &[Max(20), Length(10)],
+    ),
+    (
+        "",
+        &[Max(20), Length(10)],
+    ),
+    (
+        "Min grows always but also allows Fill to grow",
+        &[Percentage(50), Fill(1), Fill(2), Min(50)],
+    ),
+    (
+        "In `Legacy`, the last constraint of lowest priority takes excess space",
+        &[Length(20), Length(20), Percentage(20)],
+    ),
+    ("", &[Length(20), Percentage(20), Length(20)]),
+    ("A lowest priority constraint will be broken before a high priority constraint", &[Ratio(1,4), Percentage(20)]),
+    ("`Length` is higher priority than `Percentage`", &[Percentage(20), Length(10)]),
+    ("`Min/Max` is higher priority than `Length`", &[Length(10), Max(20)]),
+    ("", &[Length(100), Min(20)]),
+    ("`Length` is higher priority than `Min/Max`", &[Max(20), Length(10)]),
+    ("", &[Min(20), Length(90)]),
+    ("Fill is the lowest priority and will fill any excess space", &[Fill(1), Ratio(1, 4)]),
+    ("Fill can be used to scale proportionally with other Fill blocks", &[Fill(1), Percentage(20), Fill(2)]),
+    ("", &[Ratio(1, 3), Percentage(20), Ratio(2, 3)]),
+    ("Legacy will stretch the last lowest priority constraint\nStretch will only stretch equal weighted constraints", &[Length(20), Length(15)]),
+    ("", &[Percentage(20), Length(15)]),
+    ("`Fill(u16)` fills up excess space, but is lower priority to spacers.\ni.e. Fill will only have widths in Flex::Stretch and Flex::Legacy", &[Fill(1), Fill(1)]),
+    ("", &[Length(20), Length(20)]),
+    (
+        "When not using `Flex::Stretch` or `Flex::Legacy`,\n`Min(u16)` and `Max(u16)` collapse to their lowest values",
         &[Min(20), Max(20)],
     ),
     (
-        "`SpaceBetween` stretches when there's only one constraint",
+        "",
         &[Max(20)],
     ),
-    ("", &[Min(20), Max(20), Length(20), Fixed(20)]),
-    ("`Proportional(u16)` always fills up space in every `Flex` layout", &[Proportional(0), Proportional(0)]),
+    ("", &[Min(20), Max(20), Length(20), Length(20)]),
+    ("", &[Fill(0), Fill(0)]),
     (
-        "`Proportional(1)` can be to scale with respect to other `Proportional(2)`",
-        &[Proportional(1), Proportional(2)],
+        "`Fill(1)` can be to scale with respect to other `Fill(2)`",
+        &[Fill(1), Fill(2)],
     ),
     (
-        "`Proportional(0)` collapses if there are other non-zero `Proportional(_)`\nconstraints. e.g. `[Proportional(0), Proportional(0), Proportional(1)]`:",
+        "",
+        &[Fill(1), Min(10), Max(10), Fill(2)],
+    ),
+    (
+        "`Fill(0)` collapses if there are other non-zero `Fill(_)`\nconstraints. e.g. `[Fill(0), Fill(0), Fill(1)]`:",
         &[
-            Proportional(0),
-            Proportional(0),
-            Proportional(1),
+            Fill(0),
+            Fill(0),
+            Fill(1),
         ],
     ),
 ];
@@ -87,8 +146,7 @@ struct Example {
 #[derive(Default, Debug, Copy, Clone, PartialEq, Eq, FromRepr, Display, EnumIter)]
 enum SelectedTab {
     #[default]
-    StretchLast,
-    Stretch,
+    Legacy,
     Start,
     Center,
     End,
@@ -101,12 +159,6 @@ fn main() -> Result<()> {
     Layout::init_cache(EXAMPLE_DATA.len() * SelectedTab::iter().len() * 100);
     init_error_hooks()?;
     let terminal = init_terminal()?;
-
-    // Each line in the example is a layout
-    // so 13 examples * 7 = 91 currently
-    // Plus additional layout for tabs ...
-    Layout::init_cache(120);
-
     App::default().run(terminal)?;
 
     restore_terminal()?;
@@ -123,7 +175,7 @@ impl App {
         Ok(())
     }
 
-    fn is_running(&self) -> bool {
+    fn is_running(self) -> bool {
         self.state == AppState::Running
     }
 
@@ -133,18 +185,17 @@ impl App {
     }
 
     fn handle_events(&mut self) -> Result<()> {
-        use KeyCode::*;
         match event::read()? {
             Event::Key(key) if key.kind == KeyEventKind::Press => match key.code {
-                Char('q') | Esc => self.quit(),
-                Char('l') | Right => self.next(),
-                Char('h') | Left => self.previous(),
-                Char('j') | Down => self.down(),
-                Char('k') | Up => self.up(),
-                Char('g') | Home => self.top(),
-                Char('G') | End => self.bottom(),
-                Char('+') => self.increment_spacing(),
-                Char('-') => self.decrement_spacing(),
+                KeyCode::Char('q') | KeyCode::Esc => self.quit(),
+                KeyCode::Char('l') | KeyCode::Right => self.next(),
+                KeyCode::Char('h') | KeyCode::Left => self.previous(),
+                KeyCode::Char('j') | KeyCode::Down => self.down(),
+                KeyCode::Char('k') | KeyCode::Up => self.up(),
+                KeyCode::Char('g') | KeyCode::Home => self.top(),
+                KeyCode::Char('G') | KeyCode::End => self.bottom(),
+                KeyCode::Char('+') => self.increment_spacing(),
+                KeyCode::Char('-') => self.decrement_spacing(),
                 _ => (),
             },
             _ => {}
@@ -161,14 +212,14 @@ impl App {
     }
 
     fn up(&mut self) {
-        self.scroll_offset = self.scroll_offset.saturating_sub(1)
+        self.scroll_offset = self.scroll_offset.saturating_sub(1);
     }
 
     fn down(&mut self) {
         self.scroll_offset = self
             .scroll_offset
             .saturating_add(1)
-            .min(max_scroll_offset())
+            .min(max_scroll_offset());
     }
 
     fn top(&mut self) {
@@ -197,8 +248,7 @@ fn max_scroll_offset() -> u16 {
     example_height()
         - EXAMPLE_DATA
             .last()
-            .map(|(desc, _)| get_description_height(desc) + 4)
-            .unwrap_or(0)
+            .map_or(0, |(desc, _)| get_description_height(desc) + 4)
 }
 
 /// The height of all examples combined
@@ -213,21 +263,21 @@ fn example_height() -> u16 {
 
 impl Widget for App {
     fn render(self, area: Rect, buf: &mut Buffer) {
-        let layout = Layout::vertical([Fixed(3), Fixed(1), Proportional(0)]);
-        let [tabs, axis, demo] = area.split(&layout);
+        let layout = Layout::vertical([Length(3), Length(1), Fill(0)]);
+        let [tabs, axis, demo] = layout.areas(area);
         self.tabs().render(tabs, buf);
         let scroll_needed = self.render_demo(demo, buf);
         let axis_width = if scroll_needed {
-            axis.width - 1
+            axis.width.saturating_sub(1)
         } else {
             axis.width
         };
-        self.axis(axis_width, self.spacing).render(axis, buf);
+        Self::axis(axis_width, self.spacing).render(axis, buf);
     }
 }
 
 impl App {
-    fn tabs(&self) -> impl Widget {
+    fn tabs(self) -> impl Widget {
         let tab_titles = SelectedTab::iter().map(SelectedTab::to_tab_title);
         let block = Block::new()
             .title(Title::from("Flex Layouts ".bold()))
@@ -241,17 +291,17 @@ impl App {
     }
 
     /// a bar like `<----- 80 px (gap: 2 px)? ----->`
-    fn axis(&self, width: u16, spacing: u16) -> impl Widget {
+    fn axis(width: u16, spacing: u16) -> impl Widget {
         let width = width as usize;
         // only show gap when spacing is not zero
         let label = if spacing != 0 {
-            format!("{} px (gap: {} px)", width, spacing)
+            format!("{width} px (gap: {spacing} px)")
         } else {
-            format!("{} px", width)
+            format!("{width} px")
         };
-        let bar_width = width - 2; // we want to `<` and `>` at the ends
+        let bar_width = width.saturating_sub(2); // we want to `<` and `>` at the ends
         let width_bar = format!("<{label:-^bar_width$}>");
-        Paragraph::new(width_bar.dark_gray()).alignment(Alignment::Center)
+        Paragraph::new(width_bar.dark_gray()).centered()
     }
 
     /// Render the demo content
@@ -260,6 +310,7 @@ impl App {
     /// into the main buffer. This is done to make it possible to handle scrolling easily.
     ///
     /// Returns bool indicating whether scroll was needed
+    #[allow(clippy::cast_possible_truncation)]
     fn render_demo(self, area: Rect, buf: &mut Buffer) -> bool {
         // render demo content into a separate buffer so all examples fit we add an extra
         // area.height to make sure the last example is fully visible even when the scroll offset is
@@ -305,32 +356,30 @@ impl App {
 
 impl SelectedTab {
     /// Get the previous tab, if there is no previous tab return the current tab.
-    fn previous(&self) -> Self {
-        let current_index: usize = *self as usize;
+    fn previous(self) -> Self {
+        let current_index: usize = self as usize;
         let previous_index = current_index.saturating_sub(1);
-        Self::from_repr(previous_index).unwrap_or(*self)
+        Self::from_repr(previous_index).unwrap_or(self)
     }
 
     /// Get the next tab, if there is no next tab return the current tab.
-    fn next(&self) -> Self {
-        let current_index = *self as usize;
+    fn next(self) -> Self {
+        let current_index = self as usize;
         let next_index = current_index.saturating_add(1);
-        Self::from_repr(next_index).unwrap_or(*self)
+        Self::from_repr(next_index).unwrap_or(self)
     }
 
     /// Convert a `SelectedTab` into a `Line` to display it by the `Tabs` widget.
-    fn to_tab_title(value: SelectedTab) -> Line<'static> {
-        use tailwind::*;
-        use SelectedTab::*;
+    fn to_tab_title(value: Self) -> Line<'static> {
+        use tailwind::{INDIGO, ORANGE, SKY};
         let text = value.to_string();
         let color = match value {
-            StretchLast => ORANGE.c400,
-            Stretch => ORANGE.c300,
-            Start => SKY.c400,
-            Center => SKY.c300,
-            End => SKY.c200,
-            SpaceAround => INDIGO.c400,
-            SpaceBetween => INDIGO.c300,
+            Self::Legacy => ORANGE.c400,
+            Self::Start => SKY.c400,
+            Self::Center => SKY.c300,
+            Self::End => SKY.c200,
+            Self::SpaceAround => INDIGO.c400,
+            Self::SpaceBetween => INDIGO.c300,
         };
         format!(" {text} ").fg(color).bg(Color::Black).into()
     }
@@ -341,21 +390,18 @@ impl StatefulWidget for SelectedTab {
     fn render(self, area: Rect, buf: &mut Buffer, spacing: &mut Self::State) {
         let spacing = *spacing;
         match self {
-            SelectedTab::StretchLast => self.render_examples(area, buf, Flex::StretchLast, spacing),
-            SelectedTab::Stretch => self.render_examples(area, buf, Flex::Stretch, spacing),
-            SelectedTab::Start => self.render_examples(area, buf, Flex::Start, spacing),
-            SelectedTab::Center => self.render_examples(area, buf, Flex::Center, spacing),
-            SelectedTab::End => self.render_examples(area, buf, Flex::End, spacing),
-            SelectedTab::SpaceAround => self.render_examples(area, buf, Flex::SpaceAround, spacing),
-            SelectedTab::SpaceBetween => {
-                self.render_examples(area, buf, Flex::SpaceBetween, spacing)
-            }
+            Self::Legacy => Self::render_examples(area, buf, Flex::Legacy, spacing),
+            Self::Start => Self::render_examples(area, buf, Flex::Start, spacing),
+            Self::Center => Self::render_examples(area, buf, Flex::Center, spacing),
+            Self::End => Self::render_examples(area, buf, Flex::End, spacing),
+            Self::SpaceAround => Self::render_examples(area, buf, Flex::SpaceAround, spacing),
+            Self::SpaceBetween => Self::render_examples(area, buf, Flex::SpaceBetween, spacing),
         }
     }
 }
 
 impl SelectedTab {
-    fn render_examples(&self, area: Rect, buf: &mut Buffer, flex: Flex, spacing: u16) {
+    fn render_examples(area: Rect, buf: &mut Buffer, flex: Flex, spacing: u16) {
         let heights = EXAMPLE_DATA
             .iter()
             .map(|(desc, _)| get_description_height(desc) + 4);
@@ -380,18 +426,19 @@ impl Example {
 impl Widget for Example {
     fn render(self, area: Rect, buf: &mut Buffer) {
         let title_height = get_description_height(&self.description);
-        let layout = Layout::vertical([Fixed(title_height), Proportional(0)]);
-        let [title, illustrations] = area.split(&layout);
-        let blocks = Layout::horizontal(&self.constraints)
+        let layout = Layout::vertical([Length(title_height), Fill(0)]);
+        let [title, illustrations] = layout.areas(area);
+
+        let (blocks, spacers) = Layout::horizontal(&self.constraints)
             .flex(self.flex)
             .spacing(self.spacing)
-            .split(illustrations);
+            .split_with_spacers(illustrations);
 
         if !self.description.is_empty() {
             Paragraph::new(
                 self.description
                     .split('\n')
-                    .map(|s| format!("// {}", s).italic().fg(tailwind::SLATE.c400))
+                    .map(|s| format!("// {s}").italic().fg(tailwind::SLATE.c400))
                     .map(Line::from)
                     .collect::<Vec<Line>>(),
             )
@@ -399,14 +446,62 @@ impl Widget for Example {
         }
 
         for (block, constraint) in blocks.iter().zip(&self.constraints) {
-            self.illustration(*constraint, block.width)
-                .render(*block, buf);
+            Self::illustration(*constraint, block.width).render(*block, buf);
+        }
+
+        for spacer in spacers.iter() {
+            Self::render_spacer(*spacer, buf);
         }
     }
 }
 
 impl Example {
-    fn illustration(&self, constraint: Constraint, width: u16) -> Paragraph {
+    fn render_spacer(spacer: Rect, buf: &mut Buffer) {
+        if spacer.width > 1 {
+            let corners_only = symbols::border::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: " ",
+                vertical_right: " ",
+                horizontal_top: " ",
+                horizontal_bottom: " ",
+            };
+            Block::bordered()
+                .border_set(corners_only)
+                .border_style(Style::reset().dark_gray())
+                .render(spacer, buf);
+        } else {
+            Paragraph::new(Text::from(vec![
+                Line::from(""),
+                Line::from("│"),
+                Line::from("│"),
+                Line::from(""),
+            ]))
+            .style(Style::reset().dark_gray())
+            .render(spacer, buf);
+        }
+        let width = spacer.width;
+        let label = if width > 4 {
+            format!("{width} px")
+        } else if width > 2 {
+            format!("{width}")
+        } else {
+            String::new()
+        };
+        let text = Text::from(vec![
+            Line::raw(""),
+            Line::raw(""),
+            Line::styled(label, Style::reset().dark_gray()),
+        ]);
+        Paragraph::new(text)
+            .style(Style::reset().dark_gray())
+            .alignment(Alignment::Center)
+            .render(spacer, buf);
+    }
+
+    fn illustration(constraint: Constraint, width: u16) -> impl Widget {
         let main_color = color_for_constraint(constraint);
         let fg_color = Color::White;
         let title = format!("{constraint}");
@@ -416,22 +511,19 @@ impl Example {
             .border_set(symbols::border::QUADRANT_OUTSIDE)
             .border_style(Style::reset().fg(main_color).reversed())
             .style(Style::default().fg(fg_color).bg(main_color));
-        Paragraph::new(text)
-            .alignment(Alignment::Center)
-            .block(block)
+        Paragraph::new(text).centered().block(block)
     }
 }
 
-fn color_for_constraint(constraint: Constraint) -> Color {
-    use tailwind::*;
+const fn color_for_constraint(constraint: Constraint) -> Color {
+    use tailwind::{BLUE, SLATE};
     match constraint {
-        Constraint::Fixed(_) => RED.c900,
         Constraint::Min(_) => BLUE.c900,
         Constraint::Max(_) => BLUE.c800,
         Constraint::Length(_) => SLATE.c700,
         Constraint::Percentage(_) => SLATE.c800,
         Constraint::Ratio(_, _) => SLATE.c900,
-        Constraint::Proportional(_) => SLATE.c950,
+        Constraint::Fill(_) => SLATE.c950,
     }
 }
 
@@ -445,7 +537,7 @@ fn init_error_hooks() -> Result<()> {
     }))?;
     std::panic::set_hook(Box::new(move |info| {
         let _ = restore_terminal();
-        panic(info)
+        panic(info);
     }));
     Ok(())
 }
@@ -464,6 +556,7 @@ fn restore_terminal() -> Result<()> {
     Ok(())
 }
 
+#[allow(clippy::cast_possible_truncation)]
 fn get_description_height(s: &str) -> u16 {
     if s.is_empty() {
         0

examples/gauge.rs

@@ -1,94 +1,110 @@
-use std::{
-    io::{self, stdout, Stdout},
-    time::Duration,
-};
+//! # [Ratatui] Gauge example
+//!
+//! The latest version of this example is available in the [examples] folder in the repository.
+//!
+//! Please note that the examples are designed to be run against the `main` branch of the Github
+//! repository. This means that you may not be able to compile with the latest release version on
+//! crates.io, or the one that you have installed locally.
+//!
+//! See the [examples readme] for more information on finding examples that match the version of the
+//! library you are using.
+//!
+//! [Ratatui]: https://github.com/ratatui-org/ratatui
+//! [examples]: https://github.com/ratatui-org/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui-org/ratatui/blob/main/examples/README.md
 
-use anyhow::Result;
-use crossterm::{
-    event::{self, Event, KeyCode, KeyEventKind},
-    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-    ExecutableCommand,
-};
+use std::{io::stdout, time::Duration};
+
+use color_eyre::{config::HookBuilder, Result};
 use ratatui::{
-    prelude::*,
-    widgets::{block::Title, *},
+    backend::{Backend, CrosstermBackend},
+    buffer::Buffer,
+    crossterm::{
+        event::{self, Event, KeyCode, KeyEventKind},
+        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+        ExecutableCommand,
+    },
+    layout::{Alignment, Constraint, Layout, Rect},
+    style::{palette::tailwind, Color, Style, Stylize},
+    terminal::Terminal,
+    text::Span,
+    widgets::{block::Title, Block, Borders, Gauge, Padding, Paragraph, Widget},
 };
 
-fn main() -> Result<()> {
-    App::run()
-}
-
-struct App {
-    term: Term,
-    should_quit: bool,
-    state: AppState,
-}
+const GAUGE1_COLOR: Color = tailwind::RED.c800;
+const GAUGE2_COLOR: Color = tailwind::GREEN.c800;
+const GAUGE3_COLOR: Color = tailwind::BLUE.c800;
+const GAUGE4_COLOR: Color = tailwind::ORANGE.c800;
+const CUSTOM_LABEL_COLOR: Color = tailwind::SLATE.c200;
 
 #[derive(Debug, Default, Clone, Copy)]
-struct AppState {
+struct App {
+    state: AppState,
+    progress_columns: u16,
     progress1: u16,
-    progress2: u16,
+    progress2: f64,
     progress3: f64,
-    progress4: u16,
+    progress4: f64,
+}
+
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
+enum AppState {
+    #[default]
+    Running,
+    Started,
+    Quitting,
+}
+
+fn main() -> Result<()> {
+    init_error_hooks()?;
+    let terminal = init_terminal()?;
+    App::default().run(terminal)?;
+    restore_terminal()?;
+    Ok(())
 }
 
 impl App {
-    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)?;
+    fn run(&mut self, mut terminal: Terminal<impl Backend>) -> Result<()> {
+        while self.state != AppState::Quitting {
+            self.draw(&mut terminal)?;
+            self.handle_events()?;
+            self.update(terminal.size()?.width);
         }
-        app.stop()?;
         Ok(())
     }
 
-    fn start() -> Result<Self> {
-        Ok(App {
-            term: Term::start()?,
-            should_quit: false,
-            state: AppState {
-                progress1: 0,
-                progress2: 0,
-                progress3: 0.0,
-                progress4: 0,
-            },
-        })
-    }
-
-    fn stop(&mut self) -> Result<()> {
-        Term::stop()?;
+    fn draw(&self, terminal: &mut Terminal<impl Backend>) -> Result<()> {
+        terminal.draw(|f| f.render_widget(self, f.size()))?;
         Ok(())
     }
 
-    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);
+    fn update(&mut self, terminal_width: u16) {
+        if self.state != AppState::Started {
+            return;
+        }
+
+        // progress1 and progress2 help show the difference between ratio and percentage measuring
+        // the same thing, but converting to either a u16 or f64. Effectively, we're showing the
+        // difference between how a continuous gauge acts for floor and rounded values.
+        self.progress_columns = (self.progress_columns + 1).clamp(0, terminal_width);
+        self.progress1 = self.progress_columns * 100 / terminal_width;
+        self.progress2 = f64::from(self.progress_columns) * 100.0 / f64::from(terminal_width);
+
+        // progress3 and progress4 similarly show the difference between unicode and non-unicode
+        // gauges measuring the same thing.
+        self.progress3 = (self.progress3 + 0.1).clamp(40.0, 100.0);
+        self.progress4 = (self.progress4 + 0.1).clamp(40.0, 100.0);
     }
 
-    fn draw(&mut self) -> Result<()> {
-        self.term.draw(|frame| {
-            let state = self.state;
-            let layout = Layout::vertical([Constraint::Ratio(1, 4); 4]).split(frame.size());
-            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<()> {
+    fn handle_events(&mut self) -> Result<()> {
+        let timeout = Duration::from_secs_f32(1.0 / 20.0);
         if event::poll(timeout)? {
             if let Event::Key(key) = event::read()? {
                 if key.kind == KeyEventKind::Press {
-                    if let KeyCode::Char('q') = key.code {
-                        self.should_quit = true;
+                    match key.code {
+                        KeyCode::Char(' ') | KeyCode::Enter => self.start(),
+                        KeyCode::Char('q') | KeyCode::Esc => self.quit(),
+                        _ => {}
                     }
                 }
             }
@@ -96,79 +112,133 @@ impl App {
         Ok(())
     }
 
-    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 start(&mut self) {
+        self.state = AppState::Started;
     }
 
-    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()
+    fn quit(&mut self) {
+        self.state = AppState::Quitting;
+    }
+}
+
+impl Widget for &App {
+    #[allow(clippy::similar_names)]
+    fn render(self, area: Rect, buf: &mut Buffer) {
+        use Constraint::{Length, Min, Ratio};
+        let layout = Layout::vertical([Length(2), Min(0), Length(1)]);
+        let [header_area, gauge_area, footer_area] = layout.areas(area);
+
+        let layout = Layout::vertical([Ratio(1, 4); 4]);
+        let [gauge1_area, gauge2_area, gauge3_area, gauge4_area] = layout.areas(gauge_area);
+
+        render_header(header_area, buf);
+        render_footer(footer_area, buf);
+
+        self.render_gauge1(gauge1_area, buf);
+        self.render_gauge2(gauge2_area, buf);
+        self.render_gauge3(gauge3_area, buf);
+        self.render_gauge4(gauge4_area, buf);
+    }
+}
+
+fn render_header(area: Rect, buf: &mut Buffer) {
+    Paragraph::new("Ratatui Gauge Example")
+        .bold()
+        .alignment(Alignment::Center)
+        .fg(CUSTOM_LABEL_COLOR)
+        .render(area, buf);
+}
+
+fn render_footer(area: Rect, buf: &mut Buffer) {
+    Paragraph::new("Press ENTER to start")
+        .alignment(Alignment::Center)
+        .fg(CUSTOM_LABEL_COLOR)
+        .bold()
+        .render(area, buf);
+}
+
+impl App {
+    fn render_gauge1(&self, area: Rect, buf: &mut Buffer) {
+        let title = title_block("Gauge with percentage");
+        Gauge::default()
             .block(title)
-            .gauge_style(Style::new().blue().on_light_blue())
-            .percent(progress)
-            .label(label);
-        frame.render_widget(gauge, area);
+            .gauge_style(GAUGE1_COLOR)
+            .percent(self.progress1)
+            .render(area, buf);
     }
 
-    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");
+    fn render_gauge2(&self, area: Rect, buf: &mut Buffer) {
+        let title = title_block("Gauge with ratio and custom label");
         let label = Span::styled(
-            format!("{:.2}%", progress * 100.0),
-            Style::new().red().italic().bold(),
+            format!("{:.1}/100", self.progress2),
+            Style::new().italic().bold().fg(CUSTOM_LABEL_COLOR),
         );
-        let gauge = Gauge::default()
+        Gauge::default()
             .block(title)
-            .gauge_style(Style::default().fg(Color::Yellow))
-            .ratio(progress)
+            .gauge_style(GAUGE2_COLOR)
+            .ratio(self.progress2 / 100.0)
             .label(label)
-            .use_unicode(true);
-        frame.render_widget(gauge, area);
+            .render(area, buf);
     }
 
-    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()
+    fn render_gauge3(&self, area: Rect, buf: &mut Buffer) {
+        let title = title_block("Gauge with ratio (no unicode)");
+        let label = format!("{:.1}%", self.progress3);
+        Gauge::default()
             .block(title)
-            .gauge_style(Style::new().green().italic())
-            .percent(progress)
-            .label(label);
-        frame.render_widget(gauge, area);
+            .gauge_style(GAUGE3_COLOR)
+            .ratio(self.progress3 / 100.0)
+            .label(label)
+            .render(area, buf);
     }
 
-    fn title_block(title: &str) -> Block {
-        let title = Title::from(title).alignment(Alignment::Center);
-        Block::default().title(title).borders(Borders::TOP)
+    fn render_gauge4(&self, area: Rect, buf: &mut Buffer) {
+        let title = title_block("Gauge with ratio (unicode)");
+        let label = format!("{:.1}%", self.progress3);
+        Gauge::default()
+            .block(title)
+            .gauge_style(GAUGE4_COLOR)
+            .ratio(self.progress4 / 100.0)
+            .label(label)
+            .use_unicode(true)
+            .render(area, buf);
     }
 }
 
-struct Term {
-    terminal: Terminal<CrosstermBackend<Stdout>>,
+fn title_block(title: &str) -> Block {
+    let title = Title::from(title).alignment(Alignment::Center);
+    Block::new()
+        .borders(Borders::NONE)
+        .padding(Padding::vertical(1))
+        .title(title)
+        .fg(CUSTOM_LABEL_COLOR)
 }
 
-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(())
-    }
+fn init_error_hooks() -> color_eyre::Result<()> {
+    let (panic, error) = HookBuilder::default().into_hooks();
+    let panic = panic.into_panic_hook();
+    let error = error.into_eyre_hook();
+    color_eyre::eyre::set_hook(Box::new(move |e| {
+        let _ = restore_terminal();
+        error(e)
+    }))?;
+    std::panic::set_hook(Box::new(move |info| {
+        let _ = restore_terminal();
+        panic(info);
+    }));
+    Ok(())
+}
+
+fn init_terminal() -> color_eyre::Result<Terminal<impl Backend>> {
+    enable_raw_mode()?;
+    stdout().execute(EnterAlternateScreen)?;
+    let backend = CrosstermBackend::new(stdout());
+    let terminal = Terminal::new(backend)?;
+    Ok(terminal)
+}
+
+fn restore_terminal() -> color_eyre::Result<()> {
+    disable_raw_mode()?;
+    stdout().execute(LeaveAlternateScreen)?;
+    Ok(())
 }

examples/hello_world.rs

@@ -1,15 +1,34 @@
+//! # [Ratatui] Hello World example
+//!
+//! The latest version of this example is available in the [examples] folder in the repository.
+//!
+//! Please note that the examples are designed to be run against the `main` branch of the Github
+//! repository. This means that you may not be able to compile with the latest release version on
+//! crates.io, or the one that you have installed locally.
+//!
+//! See the [examples readme] for more information on finding examples that match the version of the
+//! library you are using.
+//!
+//! [Ratatui]: https://github.com/ratatui-org/ratatui
+//! [examples]: https://github.com/ratatui-org/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui-org/ratatui/blob/main/examples/README.md
+
 use std::{
     io::{self, Stdout},
     time::Duration,
 };
 
 use anyhow::{Context, Result};
-use crossterm::{
-    event::{self, Event, KeyCode},
-    execute,
-    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+use ratatui::{
+    backend::CrosstermBackend,
+    crossterm::{
+        event::{self, Event, KeyCode},
+        execute,
+        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+    },
+    terminal::{Frame, Terminal},
+    widgets::Paragraph,
 };
-use ratatui::{prelude::*, widgets::*};
 
 /// This is a bare minimum example. There are many approaches to running an application loop, so
 /// this is not meant to be prescriptive. It is only meant to demonstrate the basic setup and

examples/hyperlink.rs

@@ -0,0 +1,151 @@
+//! # [Ratatui] Hyperlink examplew
+//!
+//! Shows how to use [OSC 8] to create hyperlinks in the terminal.
+//!
+//! The latest version of this example is available in the [examples] folder in the repository.
+//!
+//! Please note that the examples are designed to be run against the `main` branch of the Github
+//! repository. This means that you may not be able to compile with the latest release version on
+//! crates.io, or the one that you have installed locally.
+//!
+//! See the [examples readme] for more information on finding examples that match the version of the
+//! library you are using.
+//!
+//! [OSC 8]: https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda
+//! [Ratatui]: https://github.com/ratatui-org/ratatui
+//! [examples]: https://github.com/ratatui-org/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui-org/ratatui/blob/main/examples/README.md
+
+use std::{
+    io::{self, stdout, Stdout},
+    panic,
+};
+
+use color_eyre::{
+    config::{EyreHook, HookBuilder, PanicHook},
+    eyre, Result,
+};
+use crossterm::{
+    event::{self, Event, KeyCode},
+    execute,
+    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+    ExecutableCommand,
+};
+use itertools::Itertools;
+use ratatui::{prelude::*, widgets::WidgetRef};
+
+fn main() -> Result<()> {
+    init_error_handling()?;
+    let mut terminal = init_terminal()?;
+    let app = App::new();
+    app.run(&mut terminal)?;
+    restore_terminal()?;
+    Ok(())
+}
+
+struct App {
+    hyperlink: Hyperlink<'static>,
+}
+
+impl App {
+    fn new() -> Self {
+        let text = Line::from(vec!["Example ".into(), "hyperlink".blue()]);
+        let hyperlink = Hyperlink::new(text, "https://example.com");
+        Self { hyperlink }
+    }
+
+    fn run(self, terminal: &mut Terminal<CrosstermBackend<Stdout>>) -> io::Result<()> {
+        loop {
+            terminal.draw(|frame| frame.render_widget(&self.hyperlink, frame.size()))?;
+            if let Event::Key(key) = event::read()? {
+                if matches!(key.code, KeyCode::Char('q') | KeyCode::Esc) {
+                    break;
+                }
+            }
+        }
+        Ok(())
+    }
+}
+
+/// A hyperlink widget that renders a hyperlink in the terminal using [OSC 8].
+///
+/// [OSC 8]: https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda
+struct Hyperlink<'content> {
+    text: Text<'content>,
+    url: String,
+}
+
+impl<'content> Hyperlink<'content> {
+    fn new(text: impl Into<Text<'content>>, url: impl Into<String>) -> Self {
+        Self {
+            text: text.into(),
+            url: url.into(),
+        }
+    }
+}
+
+impl WidgetRef for Hyperlink<'_> {
+    fn render_ref(&self, area: Rect, buffer: &mut Buffer) {
+        self.text.render_ref(area, buffer);
+
+        // this is a hacky workaround for https://github.com/ratatui-org/ratatui/issues/902, a bug
+        // in the terminal code that incorrectly calculates the width of ANSI escape sequences. It
+        // works by rendering the hyperlink as a series of 2-character chunks, which is the
+        // calculated width of the hyperlink text.
+        for (i, two_chars) in self
+            .text
+            .to_string()
+            .chars()
+            .chunks(2)
+            .into_iter()
+            .enumerate()
+        {
+            let text = two_chars.collect::<String>();
+            let hyperlink = format!("\x1B]8;;{}\x07{}\x1B]8;;\x07", self.url, text);
+            buffer
+                .get_mut(area.x + i as u16 * 2, area.y)
+                .set_symbol(hyperlink.as_str());
+        }
+    }
+}
+
+/// Initialize the terminal with raw mode and alternate screen.
+fn init_terminal() -> io::Result<Terminal<CrosstermBackend<Stdout>>> {
+    enable_raw_mode()?;
+    stdout().execute(EnterAlternateScreen)?;
+    Terminal::new(CrosstermBackend::new(stdout()))
+}
+
+/// Restore the terminal to its original state.
+fn restore_terminal() -> io::Result<()> {
+    disable_raw_mode()?;
+    execute!(stdout(), LeaveAlternateScreen)?;
+    Ok(())
+}
+
+/// Initialize error handling with color-eyre.
+pub fn init_error_handling() -> Result<()> {
+    let (panic_hook, eyre_hook) = HookBuilder::default().into_hooks();
+    set_panic_hook(panic_hook);
+    set_error_hook(eyre_hook)?;
+    Ok(())
+}
+
+/// Install a panic hook that restores the terminal before printing the panic.
+fn set_panic_hook(panic_hook: PanicHook) {
+    let panic_hook = panic_hook.into_panic_hook();
+    panic::set_hook(Box::new(move |panic_info| {
+        let _ = restore_terminal();
+        panic_hook(panic_info);
+    }));
+}
+
+/// Install an error hook that restores the terminal before printing the error.
+fn set_error_hook(eyre_hook: EyreHook) -> Result<()> {
+    let eyre_hook = eyre_hook.into_eyre_hook();
+    eyre::set_hook(Box::new(move |error| {
+        let _ = restore_terminal();
+        eyre_hook(error)
+    }))?;
+    Ok(())
+}

examples/inline.rs

@@ -1,3 +1,18 @@
+//! # [Ratatui] Inline example
+//!
+//! The latest version of this example is available in the [examples] folder in the repository.
+//!
+//! Please note that the examples are designed to be run against the `main` branch of the Github
+//! repository. This means that you may not be able to compile with the latest release version on
+//! crates.io, or the one that you have installed locally.
+//!
+//! See the [examples readme] for more information on finding examples that match the version of the
+//! library you are using.
+//!
+//! [Ratatui]: https://github.com/ratatui-org/ratatui
+//! [examples]: https://github.com/ratatui-org/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui-org/ratatui/blob/main/examples/README.md
+
 use std::{
     collections::{BTreeMap, VecDeque},
     error::Error,
@@ -8,7 +23,16 @@ use std::{
 };
 
 use rand::distributions::{Distribution, Uniform};
-use ratatui::{prelude::*, widgets::*};
+use ratatui::{
+    backend::{Backend, CrosstermBackend},
+    layout::{Alignment, Constraint, Layout, Rect},
+    style::{Color, Modifier, Style},
+    symbols,
+    terminal::{Frame, Terminal, Viewport},
+    text::{Line, Span},
+    widgets::{block, Block, Gauge, LineGauge, List, ListItem, Paragraph, Widget},
+    TerminalOptions,
+};
 
 const NUM_DOWNLOADS: usize = 10;
 
@@ -114,6 +138,7 @@ fn input_handling(tx: mpsc::Sender<Event>) {
     });
 }
 
+#[allow(clippy::cast_precision_loss, clippy::needless_pass_by_value)]
 fn workers(tx: mpsc::Sender<Event>) -> Vec<Worker> {
     (0..4)
         .map(|id| {
@@ -153,6 +178,7 @@ fn downloads() -> Downloads {
     }
 }
 
+#[allow(clippy::needless_pass_by_value)]
 fn run_app<B: Backend>(
     terminal: &mut Terminal<B>,
     workers: Vec<Worker>,
@@ -179,7 +205,7 @@ fn run_app<B: Backend>(
             Event::DownloadUpdate(worker_id, _download_id, progress) => {
                 let download = downloads.in_progress.get_mut(&worker_id).unwrap();
                 download.progress = progress;
-                redraw = false
+                redraw = false;
             }
             Event::DownloadDone(worker_id, download_id) => {
                 let download = downloads.in_progress.remove(&worker_id).unwrap();
@@ -217,18 +243,19 @@ fn run_app<B: Backend>(
 fn ui(f: &mut Frame, downloads: &Downloads) {
     let area = f.size();
 
-    let block = Block::default().title(block::Title::from("Progress").alignment(Alignment::Center));
+    let block = Block::new().title(block::Title::from("Progress").alignment(Alignment::Center));
     f.render_widget(block, area);
 
     let vertical = Layout::vertical([Constraint::Length(2), Constraint::Length(4)]).margin(1);
     let horizontal = Layout::horizontal([Constraint::Percentage(20), Constraint::Percentage(80)]);
-    let [progress_area, main] = area.split(&vertical);
-    let [list_area, gauge_area] = main.split(&horizontal);
+    let [progress_area, main] = vertical.areas(area);
+    let [list_area, gauge_area] = horizontal.areas(main);
 
     // total progress
     let done = NUM_DOWNLOADS - downloads.pending.len() - downloads.in_progress.len();
+    #[allow(clippy::cast_precision_loss)]
     let progress = LineGauge::default()
-        .gauge_style(Style::default().fg(Color::Blue))
+        .filled_style(Style::default().fg(Color::Blue))
         .label(format!("{done}/{NUM_DOWNLOADS}"))
         .ratio(done as f64 / NUM_DOWNLOADS as f64);
     f.render_widget(progress, progress_area);
@@ -256,6 +283,7 @@ fn ui(f: &mut Frame, downloads: &Downloads) {
     let list = List::new(items);
     f.render_widget(list, list_area);
 
+    #[allow(clippy::cast_possible_truncation)]
     for (i, (_, download)) in downloads.in_progress.iter().enumerate() {
         let gauge = Gauge::default()
             .gauge_style(Style::default().fg(Color::Yellow))

examples/layout.rs

@@ -1,12 +1,38 @@
+//! # [Ratatui] Layout example
+//!
+//! The latest version of this example is available in the [examples] folder in the repository.
+//!
+//! Please note that the examples are designed to be run against the `main` branch of the Github
+//! repository. This means that you may not be able to compile with the latest release version on
+//! crates.io, or the one that you have installed locally.
+//!
+//! See the [examples readme] for more information on finding examples that match the version of the
+//! library you are using.
+//!
+//! [Ratatui]: https://github.com/ratatui-org/ratatui
+//! [examples]: https://github.com/ratatui-org/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui-org/ratatui/blob/main/examples/README.md
+
 use std::{error::Error, io};
 
-use crossterm::{
-    event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode},
-    execute,
-    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-};
 use itertools::Itertools;
-use ratatui::{layout::Constraint::*, prelude::*, widgets::*};
+use ratatui::{
+    backend::{Backend, CrosstermBackend},
+    crossterm::{
+        event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode},
+        execute,
+        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+    },
+    layout::{
+        Constraint,
+        Constraint::{Length, Max, Min, Percentage, Ratio},
+        Layout, Rect,
+    },
+    style::{Color, Style, Stylize},
+    terminal::{Frame, Terminal},
+    text::Line,
+    widgets::{Block, Paragraph},
+};
 
 fn main() -> Result<(), Box<dyn Error>> {
     // setup terminal
@@ -40,26 +66,26 @@ fn run_app<B: Backend>(terminal: &mut Terminal<B>) -> io::Result<()> {
         terminal.draw(ui)?;
 
         if let Event::Key(key) = event::read()? {
-            if let KeyCode::Char('q') = key.code {
+            if key.code == KeyCode::Char('q') {
                 return Ok(());
             }
         }
     }
 }
 
+#[allow(clippy::too_many_lines)]
 fn ui(frame: &mut Frame) {
     let vertical = Layout::vertical([
         Length(4),  // text
         Length(50), // examples
         Min(0),     // fills remaining space
     ]);
-    let [text_area, examples_area, _] = frame.size().split(&vertical);
+    let [text_area, examples_area, _] = vertical.areas(frame.size());
 
     // title
     frame.render_widget(
         Paragraph::new(vec![
-            Line::from("Horizontal Layout Example. Press q to quit".dark_gray())
-                .alignment(Alignment::Center),
+            Line::from("Horizontal Layout Example. Press q to quit".dark_gray()).centered(),
             Line::from("Each line has 2 constraints, plus Min(0) to fill the remaining space."),
             Line::from("E.g. the second line of the Len/Min box is [Length(2), Min(2), Min(0)]"),
             Line::from("Note: constraint labels that don't fit are truncated"),
@@ -80,12 +106,12 @@ fn ui(frame: &mut Frame) {
         .iter()
         .flat_map(|area| {
             Layout::horizontal([
-                Constraint::Length(14),
-                Constraint::Length(14),
-                Constraint::Length(14),
-                Constraint::Length(14),
-                Constraint::Length(14),
-                Constraint::Min(0), // fills remaining space
+                Length(14),
+                Length(14),
+                Length(14),
+                Length(14),
+                Length(14),
+                Min(0), // fills remaining space
             ])
             .split(*area)
             .iter()
@@ -169,16 +195,15 @@ fn render_example_combination(
     title: &str,
     constraints: Vec<(Constraint, Constraint)>,
 ) {
-    let block = Block::default()
+    let block = Block::bordered()
         .title(title.gray())
         .style(Style::reset())
-        .borders(Borders::ALL)
         .border_style(Style::default().fg(Color::DarkGray));
     let inner = block.inner(area);
     frame.render_widget(block, area);
     let layout = Layout::vertical(vec![Length(1); constraints.len() + 1]).split(inner);
-    for (i, (a, b)) in constraints.iter().enumerate() {
-        render_single_example(frame, layout[i], vec![*a, *b, Min(0)]);
+    for (i, (a, b)) in constraints.into_iter().enumerate() {
+        render_single_example(frame, layout[i], vec![a, b, Min(0)]);
     }
     // This is to make it easy to visually see the alignment of the examples
     // with the constraints.
@@ -191,7 +216,7 @@ fn render_single_example(frame: &mut Frame, area: Rect, constraints: Vec<Constra
     let blue = Paragraph::new(constraint_label(constraints[1])).on_blue();
     let green = Paragraph::new("·".repeat(12)).on_green();
     let horizontal = Layout::horizontal(constraints);
-    let [r, b, g] = area.split(&horizontal);
+    let [r, b, g] = horizontal.areas(area);
     frame.render_widget(red, r);
     frame.render_widget(blue, b);
     frame.render_widget(green, g);
@@ -199,12 +224,11 @@ fn render_single_example(frame: &mut Frame, area: Rect, constraints: Vec<Constra
 
 fn constraint_label(constraint: Constraint) -> String {
     match constraint {
-        Length(n) => format!("{n}"),
-        Min(n) => format!("{n}"),
-        Max(n) => format!("{n}"),
-        Percentage(n) => format!("{n}"),
-        Proportional(n) => format!("{n}"),
-        Fixed(n) => format!("{n}"),
-        Ratio(a, b) => format!("{a}:{b}"),
+        Constraint::Ratio(a, b) => format!("{a}:{b}"),
+        Constraint::Length(n)
+        | Constraint::Min(n)
+        | Constraint::Max(n)
+        | Constraint::Percentage(n)
+        | Constraint::Fill(n) => format!("{n}"),
     }
 }

examples/line_gauge.rs

@@ -0,0 +1,218 @@
+//! # [Ratatui] Line Gauge example
+//!
+//! The latest version of this example is available in the [examples] folder in the repository.
+//!
+//! Please note that the examples are designed to be run against the `main` branch of the Github
+//! repository. This means that you may not be able to compile with the latest release version on
+//! crates.io, or the one that you have installed locally.
+//!
+//! See the [examples readme] for more information on finding examples that match the version of the
+//! library you are using.
+//!
+//! [Ratatui]: https://github.com/ratatui-org/ratatui
+//! [examples]: https://github.com/ratatui-org/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui-org/ratatui/blob/main/examples/README.md
+
+use std::{io::stdout, time::Duration};
+
+use color_eyre::{config::HookBuilder, Result};
+use ratatui::{
+    backend::{Backend, CrosstermBackend},
+    buffer::Buffer,
+    crossterm::{
+        event::{self, Event, KeyCode, KeyEventKind},
+        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+        ExecutableCommand,
+    },
+    layout::{Alignment, Constraint, Layout, Rect},
+    style::{palette::tailwind, Color, Style, Stylize},
+    terminal::Terminal,
+    widgets::{block::Title, Block, Borders, LineGauge, Padding, Paragraph, Widget},
+};
+
+const CUSTOM_LABEL_COLOR: Color = tailwind::SLATE.c200;
+
+#[derive(Debug, Default, Clone, Copy)]
+struct App {
+    state: AppState,
+    progress_columns: u16,
+    progress: f64,
+}
+
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
+enum AppState {
+    #[default]
+    Running,
+    Started,
+    Quitting,
+}
+
+fn main() -> Result<()> {
+    init_error_hooks()?;
+    let terminal = init_terminal()?;
+    App::default().run(terminal)?;
+    restore_terminal()?;
+    Ok(())
+}
+
+impl App {
+    fn run(&mut self, mut terminal: Terminal<impl Backend>) -> Result<()> {
+        while self.state != AppState::Quitting {
+            self.draw(&mut terminal)?;
+            self.handle_events()?;
+            self.update(terminal.size()?.width);
+        }
+        Ok(())
+    }
+
+    fn draw(&self, terminal: &mut Terminal<impl Backend>) -> Result<()> {
+        terminal.draw(|f| f.render_widget(self, f.size()))?;
+        Ok(())
+    }
+
+    fn update(&mut self, terminal_width: u16) {
+        if self.state != AppState::Started {
+            return;
+        }
+
+        self.progress_columns = (self.progress_columns + 1).clamp(0, terminal_width);
+        self.progress = f64::from(self.progress_columns) / f64::from(terminal_width);
+    }
+
+    fn handle_events(&mut self) -> Result<()> {
+        let timeout = Duration::from_secs_f32(1.0 / 20.0);
+        if event::poll(timeout)? {
+            if let Event::Key(key) = event::read()? {
+                if key.kind == KeyEventKind::Press {
+                    match key.code {
+                        KeyCode::Char(' ') | KeyCode::Enter => self.start(),
+                        KeyCode::Char('q') | KeyCode::Esc => self.quit(),
+                        _ => {}
+                    }
+                }
+            }
+        }
+        Ok(())
+    }
+
+    fn start(&mut self) {
+        self.state = AppState::Started;
+    }
+
+    fn quit(&mut self) {
+        self.state = AppState::Quitting;
+    }
+}
+
+impl Widget for &App {
+    fn render(self, area: Rect, buf: &mut Buffer) {
+        use Constraint::{Length, Min, Ratio};
+        let layout = Layout::vertical([Length(2), Min(0), Length(1)]);
+        let [header_area, main_area, footer_area] = layout.areas(area);
+
+        let layout = Layout::vertical([Ratio(1, 3); 3]);
+        let [gauge1_area, gauge2_area, gauge3_area] = layout.areas(main_area);
+
+        header().render(header_area, buf);
+        footer().render(footer_area, buf);
+
+        self.render_gauge1(gauge1_area, buf);
+        self.render_gauge2(gauge2_area, buf);
+        self.render_gauge3(gauge3_area, buf);
+    }
+}
+
+fn header() -> impl Widget {
+    Paragraph::new("Ratatui Line Gauge Example")
+        .bold()
+        .alignment(Alignment::Center)
+        .fg(CUSTOM_LABEL_COLOR)
+}
+
+fn footer() -> impl Widget {
+    Paragraph::new("Press ENTER / SPACE to start")
+        .alignment(Alignment::Center)
+        .fg(CUSTOM_LABEL_COLOR)
+        .bold()
+}
+
+impl App {
+    fn render_gauge1(&self, area: Rect, buf: &mut Buffer) {
+        let title = title_block("Blue / red only foreground");
+        LineGauge::default()
+            .block(title)
+            .filled_style(Style::default().fg(Color::Blue))
+            .unfilled_style(Style::default().fg(Color::Red))
+            .label("Foreground:")
+            .ratio(self.progress)
+            .render(area, buf);
+    }
+
+    fn render_gauge2(&self, area: Rect, buf: &mut Buffer) {
+        let title = title_block("Blue / red only background");
+        LineGauge::default()
+            .block(title)
+            .filled_style(Style::default().fg(Color::Blue).bg(Color::Blue))
+            .unfilled_style(Style::default().fg(Color::Red).bg(Color::Red))
+            .label("Background:")
+            .ratio(self.progress)
+            .render(area, buf);
+    }
+
+    fn render_gauge3(&self, area: Rect, buf: &mut Buffer) {
+        let title = title_block("Fully styled with background");
+        LineGauge::default()
+            .block(title)
+            .filled_style(
+                Style::default()
+                    .fg(tailwind::BLUE.c400)
+                    .bg(tailwind::BLUE.c600),
+            )
+            .unfilled_style(
+                Style::default()
+                    .fg(tailwind::RED.c400)
+                    .bg(tailwind::RED.c800),
+            )
+            .label("Both:")
+            .ratio(self.progress)
+            .render(area, buf);
+    }
+}
+
+fn title_block(title: &str) -> Block {
+    let title = Title::from(title).alignment(Alignment::Center);
+    Block::default()
+        .title(title)
+        .borders(Borders::NONE)
+        .fg(CUSTOM_LABEL_COLOR)
+        .padding(Padding::vertical(1))
+}
+
+fn init_error_hooks() -> color_eyre::Result<()> {
+    let (panic, error) = HookBuilder::default().into_hooks();
+    let panic = panic.into_panic_hook();
+    let error = error.into_eyre_hook();
+    color_eyre::eyre::set_hook(Box::new(move |e| {
+        let _ = restore_terminal();
+        error(e)
+    }))?;
+    std::panic::set_hook(Box::new(move |info| {
+        let _ = restore_terminal();
+        panic(info);
+    }));
+    Ok(())
+}
+
+fn init_terminal() -> color_eyre::Result<Terminal<impl Backend>> {
+    enable_raw_mode()?;
+    stdout().execute(EnterAlternateScreen)?;
+    let backend = CrosstermBackend::new(stdout());
+    let terminal = Terminal::new(backend)?;
+    Ok(terminal)
+}
+
+fn restore_terminal() -> color_eyre::Result<()> {
+    disable_raw_mode()?;
+    stdout().execute(LeaveAlternateScreen)?;
+    Ok(())
+}

examples/list.rs

@@ -1,27 +1,321 @@
-use std::{
-    error::Error,
-    io,
-    time::{Duration, Instant},
+//! # [Ratatui] List example
+//!
+//! The latest version of this example is available in the [examples] folder in the repository.
+//!
+//! Please note that the examples are designed to be run against the `main` branch of the Github
+//! repository. This means that you may not be able to compile with the latest release version on
+//! crates.io, or the one that you have installed locally.
+//!
+//! See the [examples readme] for more information on finding examples that match the version of the
+//! library you are using.
+//!
+//! [Ratatui]: https://github.com/ratatui-org/ratatui
+//! [examples]: https://github.com/ratatui-org/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui-org/ratatui/blob/main/examples/README.md
+
+use std::{error::Error, io, io::stdout};
+
+use color_eyre::config::HookBuilder;
+use ratatui::{
+    backend::{Backend, CrosstermBackend},
+    buffer::Buffer,
+    crossterm::{
+        event::{self, Event, KeyCode, KeyEventKind},
+        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+        ExecutableCommand,
+    },
+    layout::{Alignment, Constraint, Layout, Rect},
+    style::{palette::tailwind, Color, Modifier, Style, Stylize},
+    terminal::Terminal,
+    text::Line,
+    widgets::{
+        Block, Borders, HighlightSpacing, List, ListItem, ListState, Padding, Paragraph,
+        StatefulWidget, Widget, Wrap,
+    },
 };
 
-use crossterm::{
-    event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode, KeyEventKind},
-    execute,
-    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-};
-use ratatui::{prelude::*, widgets::*};
+const TODO_HEADER_BG: Color = tailwind::BLUE.c950;
+const NORMAL_ROW_COLOR: Color = tailwind::SLATE.c950;
+const ALT_ROW_COLOR: Color = tailwind::SLATE.c900;
+const SELECTED_STYLE_FG: Color = tailwind::BLUE.c300;
+const TEXT_COLOR: Color = tailwind::SLATE.c200;
+const COMPLETED_TEXT_COLOR: Color = tailwind::GREEN.c500;
 
-struct StatefulList<T> {
+#[derive(Copy, Clone)]
+enum Status {
+    Todo,
+    Completed,
+}
+
+struct TodoItem {
+    todo: String,
+    info: String,
+    status: Status,
+}
+
+impl TodoItem {
+    fn new(todo: &str, info: &str, status: Status) -> Self {
+        Self {
+            todo: todo.to_string(),
+            info: info.to_string(),
+            status,
+        }
+    }
+}
+
+struct TodoList {
     state: ListState,
-    items: Vec<T>,
+    items: Vec<TodoItem>,
     last_selected: Option<usize>,
 }
 
-impl<T> StatefulList<T> {
-    fn with_items(items: Vec<T>) -> StatefulList<T> {
-        StatefulList {
+/// This struct holds the current state of the app. In particular, it has the `items` field which is
+/// a wrapper around `ListState`. Keeping track of the items state let us render the associated
+/// widget with its state and have access to features such as natural scrolling.
+///
+/// Check the event handling at the bottom to see how to change the state on incoming events.
+/// Check the drawing logic for items on how to specify the highlighting style for selected items.
+struct App {
+    items: TodoList,
+}
+
+fn main() -> Result<(), Box<dyn Error>> {
+    // setup terminal
+    init_error_hooks()?;
+    let terminal = init_terminal()?;
+
+    // create app and run it
+    App::new().run(terminal)?;
+
+    restore_terminal()?;
+
+    Ok(())
+}
+
+fn init_error_hooks() -> color_eyre::Result<()> {
+    let (panic, error) = HookBuilder::default().into_hooks();
+    let panic = panic.into_panic_hook();
+    let error = error.into_eyre_hook();
+    color_eyre::eyre::set_hook(Box::new(move |e| {
+        let _ = restore_terminal();
+        error(e)
+    }))?;
+    std::panic::set_hook(Box::new(move |info| {
+        let _ = restore_terminal();
+        panic(info);
+    }));
+    Ok(())
+}
+
+fn init_terminal() -> color_eyre::Result<Terminal<impl Backend>> {
+    enable_raw_mode()?;
+    stdout().execute(EnterAlternateScreen)?;
+    let backend = CrosstermBackend::new(stdout());
+    let terminal = Terminal::new(backend)?;
+    Ok(terminal)
+}
+
+fn restore_terminal() -> color_eyre::Result<()> {
+    disable_raw_mode()?;
+    stdout().execute(LeaveAlternateScreen)?;
+    Ok(())
+}
+
+impl App {
+    fn new() -> Self {
+        Self {
+            items: TodoList::with_items(&[
+                ("Rewrite everything with Rust!", "I can't hold my inner voice. He tells me to rewrite the complete universe with Rust", Status::Todo),
+                ("Rewrite all of your tui apps with Ratatui", "Yes, you heard that right. Go and replace your tui with Ratatui.", Status::Completed),
+                ("Pet your cat", "Minnak loves to be pet by you! Don't forget to pet and give some treats!", Status::Todo),
+                ("Walk with your dog", "Max is bored, go walk with him!", Status::Todo),
+                ("Pay the bills", "Pay the train subscription!!!", Status::Completed),
+                ("Refactor list example", "If you see this info that means I completed this task!", Status::Completed),
+            ]),
+        }
+    }
+
+    /// Changes the status of the selected list item
+    fn change_status(&mut self) {
+        if let Some(i) = self.items.state.selected() {
+            self.items.items[i].status = match self.items.items[i].status {
+                Status::Completed => Status::Todo,
+                Status::Todo => Status::Completed,
+            }
+        }
+    }
+
+    fn go_top(&mut self) {
+        self.items.state.select(Some(0));
+    }
+
+    fn go_bottom(&mut self) {
+        self.items.state.select(Some(self.items.items.len() - 1));
+    }
+}
+
+impl App {
+    fn run(&mut self, mut terminal: Terminal<impl Backend>) -> io::Result<()> {
+        loop {
+            self.draw(&mut terminal)?;
+
+            if let Event::Key(key) = event::read()? {
+                if key.kind == KeyEventKind::Press {
+                    match key.code {
+                        KeyCode::Char('q') | KeyCode::Esc => return Ok(()),
+                        KeyCode::Char('h') | KeyCode::Left => self.items.unselect(),
+                        KeyCode::Char('j') | KeyCode::Down => self.items.next(),
+                        KeyCode::Char('k') | KeyCode::Up => self.items.previous(),
+                        KeyCode::Char('l') | KeyCode::Right | KeyCode::Enter => {
+                            self.change_status();
+                        }
+                        KeyCode::Char('g') => self.go_top(),
+                        KeyCode::Char('G') => self.go_bottom(),
+                        _ => {}
+                    }
+                }
+            }
+        }
+    }
+
+    fn draw(&mut self, terminal: &mut Terminal<impl Backend>) -> io::Result<()> {
+        terminal.draw(|f| f.render_widget(self, f.size()))?;
+        Ok(())
+    }
+}
+
+impl Widget for &mut App {
+    fn render(self, area: Rect, buf: &mut Buffer) {
+        // Create a space for header, todo list and the footer.
+        let vertical = Layout::vertical([
+            Constraint::Length(2),
+            Constraint::Min(0),
+            Constraint::Length(2),
+        ]);
+        let [header_area, rest_area, footer_area] = vertical.areas(area);
+
+        // Create two chunks with equal vertical screen space. One for the list and the other for
+        // the info block.
+        let vertical = Layout::vertical([Constraint::Percentage(50), Constraint::Percentage(50)]);
+        let [upper_item_list_area, lower_item_list_area] = vertical.areas(rest_area);
+
+        render_title(header_area, buf);
+        self.render_todo(upper_item_list_area, buf);
+        self.render_info(lower_item_list_area, buf);
+        render_footer(footer_area, buf);
+    }
+}
+
+impl App {
+    fn render_todo(&mut self, area: Rect, buf: &mut Buffer) {
+        // We create two blocks, one is for the header (outer) and the other is for list (inner).
+        let outer_block = Block::new()
+            .borders(Borders::NONE)
+            .title_alignment(Alignment::Center)
+            .title("TODO List")
+            .fg(TEXT_COLOR)
+            .bg(TODO_HEADER_BG);
+        let inner_block = Block::new()
+            .borders(Borders::NONE)
+            .fg(TEXT_COLOR)
+            .bg(NORMAL_ROW_COLOR);
+
+        // We get the inner area from outer_block. We'll use this area later to render the table.
+        let outer_area = area;
+        let inner_area = outer_block.inner(outer_area);
+
+        // We can render the header in outer_area.
+        outer_block.render(outer_area, buf);
+
+        // Iterate through all elements in the `items` and stylize them.
+        let items: Vec<ListItem> = self
+            .items
+            .items
+            .iter()
+            .enumerate()
+            .map(|(i, todo_item)| todo_item.to_list_item(i))
+            .collect();
+
+        // Create a List from all list items and highlight the currently selected one
+        let items = List::new(items)
+            .block(inner_block)
+            .highlight_style(
+                Style::default()
+                    .add_modifier(Modifier::BOLD)
+                    .add_modifier(Modifier::REVERSED)
+                    .fg(SELECTED_STYLE_FG),
+            )
+            .highlight_symbol(">")
+            .highlight_spacing(HighlightSpacing::Always);
+
+        // We can now render the item list
+        // (look careful we are using StatefulWidget's render.)
+        // ratatui::widgets::StatefulWidget::render as stateful_render
+        StatefulWidget::render(items, inner_area, buf, &mut self.items.state);
+    }
+
+    fn render_info(&self, area: Rect, buf: &mut Buffer) {
+        // We get the info depending on the item's state.
+        let info = if let Some(i) = self.items.state.selected() {
+            match self.items.items[i].status {
+                Status::Completed => format!("✓ DONE: {}", self.items.items[i].info),
+                Status::Todo => format!("TODO: {}", self.items.items[i].info),
+            }
+        } else {
+            "Nothing to see here...".to_string()
+        };
+
+        // We show the list item's info under the list in this paragraph
+        let outer_info_block = Block::new()
+            .borders(Borders::NONE)
+            .title_alignment(Alignment::Center)
+            .title("TODO Info")
+            .fg(TEXT_COLOR)
+            .bg(TODO_HEADER_BG);
+        let inner_info_block = Block::new()
+            .borders(Borders::NONE)
+            .padding(Padding::horizontal(1))
+            .bg(NORMAL_ROW_COLOR);
+
+        // This is a similar process to what we did for list. outer_info_area will be used for
+        // header inner_info_area will be used for the list info.
+        let outer_info_area = area;
+        let inner_info_area = outer_info_block.inner(outer_info_area);
+
+        // We can render the header. Inner info will be rendered later
+        outer_info_block.render(outer_info_area, buf);
+
+        let info_paragraph = Paragraph::new(info)
+            .block(inner_info_block)
+            .fg(TEXT_COLOR)
+            .wrap(Wrap { trim: false });
+
+        // We can now render the item info
+        info_paragraph.render(inner_info_area, buf);
+    }
+}
+
+fn render_title(area: Rect, buf: &mut Buffer) {
+    Paragraph::new("Ratatui List Example")
+        .bold()
+        .centered()
+        .render(area, buf);
+}
+
+fn render_footer(area: Rect, buf: &mut Buffer) {
+    Paragraph::new("\nUse ↓↑ to move, ← to unselect, → to change status, g/G to go top/bottom.")
+        .centered()
+        .render(area, buf);
+}
+
+impl TodoList {
+    fn with_items(items: &[(&str, &str, Status)]) -> Self {
+        Self {
             state: ListState::default(),
-            items,
+            items: items
+                .iter()
+                .map(|(todo, info, status)| TodoItem::new(todo, info, *status))
+                .collect(),
             last_selected: None,
         }
     }
@@ -62,220 +356,20 @@ impl<T> StatefulList<T> {
     }
 }
 
-/// This struct holds the current state of the app. In particular, it has the `items` field which is
-/// a wrapper around `ListState`. Keeping track of the items state let us render the associated
-/// widget with its state and have access to features such as natural scrolling.
-///
-/// Check the event handling at the bottom to see how to change the state on incoming events.
-/// Check the drawing logic for items on how to specify the highlighting style for selected items.
-struct App<'a> {
-    items: StatefulList<(&'a str, usize)>,
-    events: Vec<(&'a str, &'a str)>,
-}
+impl TodoItem {
+    fn to_list_item(&self, index: usize) -> ListItem {
+        let bg_color = match index % 2 {
+            0 => NORMAL_ROW_COLOR,
+            _ => ALT_ROW_COLOR,
+        };
+        let line = match self.status {
+            Status::Todo => Line::styled(format!(" ☐ {}", self.todo), TEXT_COLOR),
+            Status::Completed => Line::styled(
+                format!(" ✓ {}", self.todo),
+                (COMPLETED_TEXT_COLOR, bg_color),
+            ),
+        };
 
-impl<'a> App<'a> {
-    fn new() -> App<'a> {
-        App {
-            items: StatefulList::with_items(vec![
-                ("Item0", 1),
-                ("Item1", 2),
-                ("Item2", 1),
-                ("Item3", 3),
-                ("Item4", 1),
-                ("Item5", 4),
-                ("Item6", 1),
-                ("Item7", 3),
-                ("Item8", 1),
-                ("Item9", 6),
-                ("Item10", 1),
-                ("Item11", 3),
-                ("Item12", 1),
-                ("Item13", 2),
-                ("Item14", 1),
-                ("Item15", 1),
-                ("Item16", 4),
-                ("Item17", 1),
-                ("Item18", 5),
-                ("Item19", 4),
-                ("Item20", 1),
-                ("Item21", 2),
-                ("Item22", 1),
-                ("Item23", 3),
-                ("Item24", 1),
-            ]),
-            events: vec![
-                ("Event1", "INFO"),
-                ("Event2", "INFO"),
-                ("Event3", "CRITICAL"),
-                ("Event4", "ERROR"),
-                ("Event5", "INFO"),
-                ("Event6", "INFO"),
-                ("Event7", "WARNING"),
-                ("Event8", "INFO"),
-                ("Event9", "INFO"),
-                ("Event10", "INFO"),
-                ("Event11", "CRITICAL"),
-                ("Event12", "INFO"),
-                ("Event13", "INFO"),
-                ("Event14", "INFO"),
-                ("Event15", "INFO"),
-                ("Event16", "INFO"),
-                ("Event17", "ERROR"),
-                ("Event18", "ERROR"),
-                ("Event19", "INFO"),
-                ("Event20", "INFO"),
-                ("Event21", "WARNING"),
-                ("Event22", "INFO"),
-                ("Event23", "INFO"),
-                ("Event24", "WARNING"),
-                ("Event25", "INFO"),
-                ("Event26", "INFO"),
-            ],
-        }
-    }
-
-    /// Rotate through the event list.
-    /// This only exists to simulate some kind of "progress"
-    fn on_tick(&mut self) {
-        let event = self.events.remove(0);
-        self.events.push(event);
+        ListItem::new(line).bg(bg_color)
     }
 }
-
-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, &mut app))?;
-
-        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 | KeyCode::Char('h') => app.items.unselect(),
-                        KeyCode::Down | KeyCode::Char('j') => app.items.next(),
-                        KeyCode::Up | KeyCode::Char('k') => app.items.previous(),
-                        _ => {}
-                    }
-                }
-            }
-        }
-        if last_tick.elapsed() >= tick_rate {
-            app.on_tick();
-            last_tick = Instant::now();
-        }
-    }
-}
-
-fn ui(f: &mut Frame, app: &mut App) {
-    // Create two chunks with equal horizontal screen space
-    let horizontal = Layout::horizontal([Constraint::Percentage(50), Constraint::Percentage(50)]);
-    let [item_list_area, event_list_area] = f.size().split(&horizontal);
-
-    // Iterate through all elements in the `items` app and append some debug text to it.
-    let items: Vec<ListItem> = app
-        .items
-        .items
-        .iter()
-        .map(|i| {
-            let mut lines = vec![Line::from(i.0.bold()).alignment(Alignment::Center)];
-            for _ in 0..i.1 {
-                lines.push(
-                    "Lorem ipsum dolor sit amet, consectetur adipiscing elit."
-                        .italic()
-                        .into(),
-                );
-            }
-            ListItem::new(lines).style(Style::default().fg(Color::Black).bg(Color::White))
-        })
-        .collect();
-
-    // Create a List from all list items and highlight the currently selected one
-    let items = List::new(items)
-        .block(Block::default().borders(Borders::ALL).title("List"))
-        .highlight_style(
-            Style::default()
-                .bg(Color::LightGreen)
-                .add_modifier(Modifier::BOLD),
-        )
-        .highlight_symbol(">> ");
-
-    // We can now render the item list
-    f.render_stateful_widget(items, item_list_area, &mut app.items.state);
-
-    // Let's do the same for the events.
-    // The event list doesn't have any state and only displays the current state of the list.
-    let events: Vec<ListItem> = app
-        .events
-        .iter()
-        .rev()
-        .map(|&(event, level)| {
-            // Colorcode the level depending on its type
-            let s = match level {
-                "CRITICAL" => Style::default().fg(Color::Red),
-                "ERROR" => Style::default().fg(Color::Magenta),
-                "WARNING" => Style::default().fg(Color::Yellow),
-                "INFO" => Style::default().fg(Color::Blue),
-                _ => Style::default(),
-            };
-            // Add a example datetime and apply proper spacing between them
-            let header = Line::from(vec![
-                Span::styled(format!("{level:<9}"), s),
-                " ".into(),
-                "2020-01-01 10:00:00".italic(),
-            ]);
-            // The event gets its own line
-            let log = Line::from(vec![event.into()]);
-
-            // Here several things happen:
-            // 1. Add a `---` spacing line above the final list entry
-            // 2. Add the Level + datetime
-            // 3. Add a spacer line
-            // 4. Add the actual event
-            ListItem::new(vec![
-                Line::from("-".repeat(event_list_area.width as usize)),
-                header,
-                Line::from(""),
-                log,
-            ])
-        })
-        .collect();
-    let events_list = List::new(events)
-        .block(Block::default().borders(Borders::ALL).title("List"))
-        .direction(ListDirection::BottomToTop);
-    f.render_widget(events_list, event_list_area);
-}

examples/minimal.rs

@@ -0,0 +1,42 @@
+//! # [Ratatui] Minimal example
+//!
+//! The latest version of this example is available in the [examples] folder in the repository.
+//!
+//! Please note that the examples are designed to be run against the `main` branch of the Github
+//! repository. This means that you may not be able to compile with the latest release version on
+//! crates.io, or the one that you have installed locally.
+//!
+//! See the [examples readme] for more information on finding examples that match the version of the
+//! library you are using.
+//!
+//! [Ratatui]: https://github.com/ratatui-org/ratatui
+//! [examples]: https://github.com/ratatui-org/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui-org/ratatui/blob/main/examples/README.md
+
+use ratatui::{
+    backend::CrosstermBackend,
+    crossterm::event::{self, Event, KeyCode, KeyEventKind},
+    text::Text,
+    Terminal,
+};
+
+/// This is a bare minimum example. There are many approaches to running an application loop, so
+/// this is not meant to be prescriptive. See the [examples] folder for more complete examples.
+/// In particular, the [hello-world] example is a good starting point.
+///
+/// [examples]: https://github.com/ratatui-org/ratatui/blob/main/examples
+/// [hello-world]: https://github.com/ratatui-org/ratatui/blob/main/examples/hello_world.rs
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let backend = CrosstermBackend::stdout()?;
+    let mut terminal = Terminal::new(backend)?;
+    terminal.clear()?;
+    loop {
+        terminal.draw(|frame| frame.render_widget(Text::raw("Hello World!"), frame.size()))?;
+        if let Event::Key(key) = event::read()? {
+            if key.kind == KeyEventKind::Press && key.code == KeyCode::Char('q') {
+                break;
+            }
+        }
+    }
+    Ok(())
+}

examples/modifiers.rs

@@ -1,6 +1,22 @@
-/// This example is useful for testing how your terminal emulator handles different modifiers.
-/// It will render a grid of combinations of foreground and background colors with all
-/// modifiers applied to them.
+//! # [Ratatui] Modifiers example
+//!
+//! The latest version of this example is available in the [examples] folder in the repository.
+//!
+//! Please note that the examples are designed to be run against the `main` branch of the Github
+//! repository. This means that you may not be able to compile with the latest release version on
+//! crates.io, or the one that you have installed locally.
+//!
+//! See the [examples readme] for more information on finding examples that match the version of the
+//! library you are using.
+//!
+//! [Ratatui]: https://github.com/ratatui-org/ratatui
+//! [examples]: https://github.com/ratatui-org/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui-org/ratatui/blob/main/examples/README.md
+
+// This example is useful for testing how your terminal emulator handles different modifiers.
+// It will render a grid of combinations of foreground and background colors with all
+// modifiers applied to them.
+
 use std::{
     error::Error,
     io::{self, Stdout},
@@ -9,13 +25,20 @@ use std::{
     time::Duration,
 };
 
-use crossterm::{
-    event::{self, Event, KeyCode},
-    execute,
-    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-};
 use itertools::Itertools;
-use ratatui::{prelude::*, widgets::*};
+use ratatui::{
+    backend::{Backend, CrosstermBackend},
+    crossterm::{
+        event::{self, Event, KeyCode},
+        execute,
+        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+    },
+    layout::{Constraint, Layout},
+    style::{Color, Modifier, Style, Stylize},
+    terminal::{Frame, Terminal},
+    text::Line,
+    widgets::Paragraph,
+};
 
 type Result<T> = result::Result<T, Box<dyn Error>>;
 
@@ -35,7 +58,7 @@ fn run_app<B: Backend>(terminal: &mut Terminal<B>) -> io::Result<()> {
 
         if event::poll(Duration::from_millis(250))? {
             if let Event::Key(key) = event::read()? {
-                if let KeyCode::Char('q') = key.code {
+                if key.code == KeyCode::Char('q') {
                     return Ok(());
                 }
             }
@@ -45,7 +68,7 @@ fn run_app<B: Backend>(terminal: &mut Terminal<B>) -> io::Result<()> {
 
 fn ui(frame: &mut Frame) {
     let vertical = Layout::vertical([Constraint::Length(1), Constraint::Min(0)]);
-    let [text_area, main_area] = frame.size().split(&vertical);
+    let [text_area, main_area] = vertical.areas(frame.size());
     frame.render_widget(
         Paragraph::new("Note: not all terminals support all modifiers")
             .style(Style::default().fg(Color::Red).add_modifier(Modifier::BOLD)),
@@ -72,8 +95,8 @@ fn ui(frame: &mut Frame) {
         .chain(Modifier::all().iter())
         .collect_vec();
     let mut index = 0;
-    for bg in colors.iter() {
-        for fg in colors.iter() {
+    for bg in &colors {
+        for fg in &colors {
             for modifier in &all_modifiers {
                 let modifier_name = format!("{modifier:11?}");
                 let padding = (" ").repeat(12 - modifier_name.len());

examples/panic.rs

@@ -1,3 +1,18 @@
+//! # [Ratatui] Panic Hook example
+//!
+//! The latest version of this example is available in the [examples] folder in the repository.
+//!
+//! Please note that the examples are designed to be run against the `main` branch of the Github
+//! repository. This means that you may not be able to compile with the latest release version on
+//! crates.io, or the one that you have installed locally.
+//!
+//! See the [examples readme] for more information on finding examples that match the version of the
+//! library you are using.
+//!
+//! [Ratatui]: https://github.com/ratatui-org/ratatui
+//! [examples]: https://github.com/ratatui-org/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui-org/ratatui/blob/main/examples/README.md
+
 //! How to use a panic hook to reset the terminal before printing the panic to
 //! the terminal.
 //!
@@ -16,11 +31,16 @@
 
 use std::{error::Error, io};
 
-use crossterm::{
-    event::{self, Event, KeyCode},
-    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+use ratatui::{
+    backend::{Backend, CrosstermBackend},
+    crossterm::{
+        event::{self, Event, KeyCode},
+        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+    },
+    terminal::{Frame, Terminal},
+    text::Line,
+    widgets::{Block, Paragraph},
 };
-use ratatui::{prelude::*, widgets::*};
 
 type Result<T> = std::result::Result<T, Box<dyn Error>>;
 
@@ -124,11 +144,9 @@ fn ui(f: &mut Frame, app: &App) {
         Line::from("try first without the panic handler to see the difference"),
     ];
 
-    let b = Block::default()
-        .title("Panic Handler Demo")
-        .borders(Borders::ALL);
+    let paragraph = Paragraph::new(text)
+        .block(Block::bordered().title("Panic Handler Demo"))
+        .centered();
 
-    let p = Paragraph::new(text).block(b).alignment(Alignment::Center);
-
-    f.render_widget(p, f.size());
+    f.render_widget(paragraph, f.size());
 }

examples/paragraph.rs

@@ -1,146 +1,231 @@
+//! # [Ratatui] Paragraph example
+//!
+//! The latest version of this example is available in the [examples] folder in the repository.
+//!
+//! Please note that the examples are designed to be run against the `main` branch of the Github
+//! repository. This means that you may not be able to compile with the latest release version on
+//! crates.io, or the one that you have installed locally.
+//!
+//! See the [examples readme] for more information on finding examples that match the version of the
+//! library you are using.
+//!
+//! [Ratatui]: https://github.com/ratatui-org/ratatui
+//! [examples]: https://github.com/ratatui-org/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui-org/ratatui/blob/main/examples/README.md
+
 use std::{
-    error::Error,
-    io,
+    io::{self},
     time::{Duration, Instant},
 };
 
-use crossterm::{
-    event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode},
-    execute,
-    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+use crossterm::event::KeyEventKind;
+use ratatui::{
+    buffer::Buffer,
+    crossterm::event::{self, Event, KeyCode},
+    layout::{Constraint, Layout, Rect},
+    style::{Color, Stylize},
+    text::{Line, Masked, Span},
+    widgets::{Block, Paragraph, Widget, Wrap},
 };
-use ratatui::{prelude::*, widgets::*};
 
-struct App {
-    scroll: u16,
-}
-
-impl App {
-    fn new() -> App {
-        App { scroll: 0 }
-    }
-
-    fn on_tick(&mut self) {
-        self.scroll += 1;
-        self.scroll %= 10;
-    }
-}
-
-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:?}");
-    }
+use self::common::{init_terminal, install_hooks, restore_terminal, Tui};
 
+fn main() -> color_eyre::Result<()> {
+    install_hooks()?;
+    let mut terminal = init_terminal()?;
+    let mut app = App::new();
+    app.run(&mut terminal)?;
+    restore_terminal()?;
     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))?;
+#[derive(Debug)]
+struct App {
+    should_exit: bool,
+    scroll: u16,
+    last_tick: Instant,
+}
 
-        let timeout = tick_rate.saturating_sub(last_tick.elapsed());
-        if crossterm::event::poll(timeout)? {
+impl App {
+    /// The duration between each tick.
+    const TICK_RATE: Duration = Duration::from_millis(250);
+
+    /// Create a new instance of the app.
+    fn new() -> Self {
+        Self {
+            should_exit: false,
+            scroll: 0,
+            last_tick: Instant::now(),
+        }
+    }
+
+    /// Run the app until the user exits.
+    fn run(&mut self, terminal: &mut Tui) -> io::Result<()> {
+        while !self.should_exit {
+            self.draw(terminal)?;
+            self.handle_events()?;
+            if self.last_tick.elapsed() >= Self::TICK_RATE {
+                self.on_tick();
+                self.last_tick = Instant::now();
+            }
+        }
+        Ok(())
+    }
+
+    /// Draw the app to the terminal.
+    fn draw(&mut self, terminal: &mut Tui) -> io::Result<()> {
+        terminal.draw(|frame| frame.render_widget(self, frame.size()))?;
+        Ok(())
+    }
+
+    /// Handle events from the terminal.
+    fn handle_events(&mut self) -> io::Result<()> {
+        let timeout = Self::TICK_RATE.saturating_sub(self.last_tick.elapsed());
+        while event::poll(timeout)? {
             if let Event::Key(key) = event::read()? {
-                if let KeyCode::Char('q') = key.code {
-                    return Ok(());
+                if key.kind == KeyEventKind::Press && key.code == KeyCode::Char('q') {
+                    self.should_exit = true;
                 }
             }
         }
-        if last_tick.elapsed() >= tick_rate {
-            app.on_tick();
-            last_tick = Instant::now();
-        }
+        Ok(())
+    }
+
+    /// Update the app state on each tick.
+    fn on_tick(&mut self) {
+        self.scroll = (self.scroll + 1) % 10;
     }
 }
 
-fn ui(f: &mut Frame, app: &App) {
-    let size = f.size();
+impl Widget for &mut App {
+    fn render(self, area: Rect, buf: &mut Buffer) {
+        let areas = Layout::vertical([Constraint::Max(9); 4]).split(area);
+        Paragraph::new(create_lines(area))
+            .block(title_block("Default alignment (Left), no wrap"))
+            .gray()
+            .render(areas[0], buf);
+        Paragraph::new(create_lines(area))
+            .block(title_block("Default alignment (Left), with wrap"))
+            .gray()
+            .wrap(Wrap { trim: true })
+            .render(areas[1], buf);
+        Paragraph::new(create_lines(area))
+            .block(title_block("Right alignment, with wrap"))
+            .gray()
+            .right_aligned()
+            .wrap(Wrap { trim: true })
+            .render(areas[2], buf);
+        Paragraph::new(create_lines(area))
+            .block(title_block("Center alignment, with wrap, with scroll"))
+            .gray()
+            .centered()
+            .wrap(Wrap { trim: true })
+            .scroll((self.scroll, 0))
+            .render(areas[3], buf);
+    }
+}
 
-    // Words made "loooong" to demonstrate line breaking.
-    let s = "Veeeeeeeeeeeeeeeery    loooooooooooooooooong   striiiiiiiiiiiiiiiiiiiiiiiiiing.   ";
-    let mut long_line = s.repeat(usize::from(size.width) / s.len() + 4);
-    long_line.push('\n');
+/// Create a bordered block with a title.
+fn title_block(title: &str) -> Block {
+    Block::bordered()
+        .gray()
+        .title(title.bold().into_centered_line())
+}
 
-    let block = Block::default().black();
-    f.render_widget(block, size);
-
-    let layout = Layout::vertical([Constraint::Ratio(1, 4); 4]).split(size);
-
-    let text = vec![
-        Line::from("This is a line "),
-        Line::from("This is a line   ".red()),
-        Line::from("This is a line".on_blue()),
-        Line::from("This is a longer line".crossed_out()),
-        Line::from(long_line.on_green()),
-        Line::from("This is a line".green().italic()),
-        Line::from(vec![
+/// Create some lines to display in the paragraph.
+fn create_lines(area: Rect) -> Vec<Line<'static>> {
+    let short_line = "A long line to demonstrate line wrapping. ";
+    let long_line = short_line.repeat(usize::from(area.width) / short_line.len() + 4);
+    let mut styled_spans = vec![];
+    for span in [
+        "Styled".blue(),
+        "Spans".red().on_white(),
+        "Bold".bold(),
+        "Italic".italic(),
+        "Underlined".underlined(),
+        "Strikethrough".crossed_out(),
+    ] {
+        styled_spans.push(span);
+        styled_spans.push(" ".into());
+    }
+    vec![
+        Line::raw("Unstyled Line"),
+        Line::raw("Styled Line").black().on_red().bold().italic(),
+        Line::from(styled_spans),
+        Line::from(long_line.green().italic()),
+        Line::from_iter([
             "Masked text: ".into(),
-            Span::styled(
-                Masked::new("password", '*'),
-                Style::default().fg(Color::Red),
-            ),
+            Span::styled(Masked::new("my secret password", '*'), Color::Red),
         ]),
-    ];
+    ]
+}
 
-    let create_block = |title| {
-        Block::default()
-            .borders(Borders::ALL)
-            .style(Style::default().fg(Color::Gray))
-            .title(Span::styled(
-                title,
-                Style::default().add_modifier(Modifier::BOLD),
-            ))
+/// A module for common functionality used in the examples.
+mod common {
+    use std::{
+        io::{self, stdout, Stdout},
+        panic,
     };
 
-    let paragraph = Paragraph::new(text.clone())
-        .style(Style::default().fg(Color::Gray))
-        .block(create_block("Default alignment (Left), no wrap"));
-    f.render_widget(paragraph, layout[0]);
+    use color_eyre::{
+        config::{EyreHook, HookBuilder, PanicHook},
+        eyre,
+    };
+    use crossterm::ExecutableCommand;
+    use ratatui::{
+        backend::CrosstermBackend,
+        crossterm::terminal::{
+            disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen,
+        },
+        terminal::Terminal,
+    };
 
-    let paragraph = Paragraph::new(text.clone())
-        .style(Style::default().fg(Color::Gray))
-        .block(create_block("Default alignment (Left), with wrap"))
-        .wrap(Wrap { trim: true });
-    f.render_widget(paragraph, layout[1]);
+    // A simple alias for the terminal type used in this example.
+    pub type Tui = Terminal<CrosstermBackend<Stdout>>;
 
-    let paragraph = Paragraph::new(text.clone())
-        .style(Style::default().fg(Color::Gray))
-        .block(create_block("Right alignment, with wrap"))
-        .alignment(Alignment::Right)
-        .wrap(Wrap { trim: true });
-    f.render_widget(paragraph, layout[2]);
+    /// Initialize the terminal and enter alternate screen mode.
+    pub fn init_terminal() -> io::Result<Tui> {
+        enable_raw_mode()?;
+        stdout().execute(EnterAlternateScreen)?;
+        let backend = CrosstermBackend::new(stdout());
+        Terminal::new(backend)
+    }
 
-    let paragraph = Paragraph::new(text)
-        .style(Style::default().fg(Color::Gray))
-        .block(create_block("Center alignment, with wrap, with scroll"))
-        .alignment(Alignment::Center)
-        .wrap(Wrap { trim: true })
-        .scroll((app.scroll, 0));
-    f.render_widget(paragraph, layout[3]);
+    /// Restore the terminal to its original state.
+    pub fn restore_terminal() -> io::Result<()> {
+        disable_raw_mode()?;
+        stdout().execute(LeaveAlternateScreen)?;
+        Ok(())
+    }
+
+    /// Installs hooks for panic and error handling.
+    ///
+    /// Makes the app resilient to panics and errors by restoring the terminal before printing the
+    /// panic or error message. This prevents error messages from being messed up by the terminal
+    /// state.
+    pub fn install_hooks() -> color_eyre::Result<()> {
+        let (panic_hook, eyre_hook) = HookBuilder::default().into_hooks();
+        install_panic_hook(panic_hook);
+        install_error_hook(eyre_hook)?;
+        Ok(())
+    }
+
+    /// Install a panic hook that restores the terminal before printing the panic.
+    fn install_panic_hook(panic_hook: PanicHook) {
+        let panic_hook = panic_hook.into_panic_hook();
+        panic::set_hook(Box::new(move |panic_info| {
+            let _ = restore_terminal();
+            panic_hook(panic_info);
+        }));
+    }
+
+    /// Install an error hook that restores the terminal before printing the error.
+    fn install_error_hook(eyre_hook: EyreHook) -> color_eyre::Result<()> {
+        let eyre_hook = eyre_hook.into_eyre_hook();
+        eyre::set_hook(Box::new(move |error| {
+            let _ = restore_terminal();
+            eyre_hook(error)
+        }))?;
+        Ok(())
+    }
 }

examples/popup.rs

@@ -1,19 +1,43 @@
+//! # [Ratatui] Popup example
+//!
+//! The latest version of this example is available in the [examples] folder in the repository.
+//!
+//! Please note that the examples are designed to be run against the `main` branch of the Github
+//! repository. This means that you may not be able to compile with the latest release version on
+//! crates.io, or the one that you have installed locally.
+//!
+//! See the [examples readme] for more information on finding examples that match the version of the
+//! library you are using.
+//!
+//! [Ratatui]: https://github.com/ratatui-org/ratatui
+//! [examples]: https://github.com/ratatui-org/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui-org/ratatui/blob/main/examples/README.md
+
+// See also https://github.com/joshka/tui-popup and
+// https://github.com/sephiroth74/tui-confirm-dialog
+
 use std::{error::Error, io};
 
-use crossterm::{
-    event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode, KeyEventKind},
-    execute,
-    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+use ratatui::{
+    backend::{Backend, CrosstermBackend},
+    crossterm::{
+        event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode, KeyEventKind},
+        execute,
+        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+    },
+    layout::{Constraint, Layout, Rect},
+    style::Stylize,
+    terminal::{Frame, Terminal},
+    widgets::{Block, Clear, Paragraph, Wrap},
 };
-use ratatui::{prelude::*, widgets::*};
 
 struct App {
     show_popup: bool,
 }
 
 impl App {
-    fn new() -> App {
-        App { show_popup: false }
+    const fn new() -> Self {
+        Self { show_popup: false }
     }
 }
 
@@ -65,7 +89,7 @@ fn ui(f: &mut Frame, app: &App) {
     let area = f.size();
 
     let vertical = Layout::vertical([Constraint::Percentage(20), Constraint::Percentage(80)]);
-    let [instructions, content] = area.split(&vertical);
+    let [instructions, content] = vertical.areas(area);
 
     let text = if app.show_popup {
         "Press p to close the popup"
@@ -73,18 +97,15 @@ fn ui(f: &mut Frame, app: &App) {
         "Press p to show the popup"
     };
     let paragraph = Paragraph::new(text.slow_blink())
-        .alignment(Alignment::Center)
+        .centered()
         .wrap(Wrap { trim: true });
     f.render_widget(paragraph, instructions);
 
-    let block = Block::default()
-        .title("Content")
-        .borders(Borders::ALL)
-        .on_blue();
+    let block = Block::bordered().title("Content").on_blue();
     f.render_widget(block, content);
 
     if app.show_popup {
-        let block = Block::default().title("Popup").borders(Borders::ALL);
+        let block = Block::bordered().title("Popup");
         let area = centered_rect(60, 20, area);
         f.render_widget(Clear, area); //this clears out the background
         f.render_widget(block, area);

examples/ratatui-logo.rs

@@ -1,55 +1,72 @@
+//! # [Ratatui] Logo example
+//!
+//! The latest version of this example is available in the [examples] folder in the repository.
+//!
+//! Please note that the examples are designed to be run against the `main` branch of the Github
+//! repository. This means that you may not be able to compile with the latest release version on
+//! crates.io, or the one that you have installed locally.
+//!
+//! See the [examples readme] for more information on finding examples that match the version of the
+//! library you are using.
+//!
+//! [Ratatui]: https://github.com/ratatui-org/ratatui
+//! [examples]: https://github.com/ratatui-org/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui-org/ratatui/blob/main/examples/README.md
+
 use std::{
     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::*};
+use ratatui::{
+    backend::{Backend, CrosstermBackend},
+    crossterm::terminal::{disable_raw_mode, enable_raw_mode},
+    terminal::{Terminal, Viewport},
+    widgets::Paragraph,
+    TerminalOptions,
+};
 
 /// A fun example of using half block characters to draw a logo
-fn main() -> io::Result<()> {
+#[allow(clippy::many_single_char_names)]
+fn logo() -> String {
     let r = indoc! {"
             ▄▄▄
             █▄▄▀
             █  █
-        "}
-    .lines();
+        "};
     let a = indoc! {"
              ▄▄
             █▄▄█
             █  █
-        "}
-    .lines();
+        "};
     let t = indoc! {"
             ▄▄▄
              █
              █
-        "}
-    .lines();
+        "};
     let u = indoc! {"
             ▄  ▄
             █  █
             ▀▄▄▀
-        "}
-    .lines();
+        "};
     let i = indoc! {"
             ▄
             █
             █
-        "}
-    .lines();
+        "};
+    izip!(r.lines(), a.lines(), t.lines(), u.lines(), i.lines())
+        .map(|(r, a, t, u, i)| format!("{r:5}{a:5}{t:4}{a:5}{t:4}{u:5}{i:5}"))
+        .collect::<Vec<_>>()
+        .join("\n")
+}
+
+fn main() -> io::Result<()> {
     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());
+        frame.render_widget(Paragraph::new(logo()), frame.size());
     })?;
     sleep(Duration::from_secs(5));
     restore()?;
@@ -57,7 +74,7 @@ fn main() -> io::Result<()> {
     Ok(())
 }
 
-pub fn init() -> io::Result<Terminal<impl Backend>> {
+fn init() -> io::Result<Terminal<impl Backend>> {
     enable_raw_mode()?;
     let options = TerminalOptions {
         viewport: Viewport::Inline(3),
@@ -65,7 +82,7 @@ pub fn init() -> io::Result<Terminal<impl Backend>> {
     Terminal::with_options(CrosstermBackend::new(stdout()), options)
 }
 
-pub fn restore() -> io::Result<()> {
+fn restore() -> io::Result<()> {
     disable_raw_mode()?;
     Ok(())
 }

examples/scrollbar.rs

@@ -1,15 +1,40 @@
+//! # [Ratatui] Scrollbar example
+//!
+//! The latest version of this example is available in the [examples] folder in the repository.
+//!
+//! Please note that the examples are designed to be run against the `main` branch of the Github
+//! repository. This means that you may not be able to compile with the latest release version on
+//! crates.io, or the one that you have installed locally.
+//!
+//! See the [examples readme] for more information on finding examples that match the version of the
+//! library you are using.
+//!
+//! [Ratatui]: https://github.com/ratatui-org/ratatui
+//! [examples]: https://github.com/ratatui-org/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui-org/ratatui/blob/main/examples/README.md
+
+#![warn(clippy::pedantic)]
+
 use std::{
     error::Error,
     io,
     time::{Duration, Instant},
 };
 
-use crossterm::{
-    event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode},
-    execute,
-    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+use ratatui::{
+    backend::{Backend, CrosstermBackend},
+    crossterm::{
+        event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode},
+        execute,
+        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+    },
+    layout::{Alignment, Constraint, Layout, Margin},
+    style::{Color, Style, Stylize},
+    symbols::scrollbar,
+    terminal::{Frame, Terminal},
+    text::{Line, Masked, Span},
+    widgets::{Block, Paragraph, Scrollbar, ScrollbarOrientation, ScrollbarState},
 };
-use ratatui::{prelude::*, symbols::scrollbar, widgets::*};
 
 #[derive(Default)]
 struct App {
@@ -92,6 +117,7 @@ fn run_app<B: Backend>(
     }
 }
 
+#[allow(clippy::too_many_lines, clippy::cast_possible_truncation)]
 fn ui(f: &mut Frame, app: &mut App) {
     let size = f.size();
 
@@ -118,10 +144,7 @@ fn ui(f: &mut Frame, app: &mut App) {
         Line::from("This is a line".reset()),
         Line::from(vec![
             Span::raw("Masked text: "),
-            Span::styled(
-                Masked::new("password", '*'),
-                Style::default().fg(Color::Red),
-            ),
+            Span::styled(Masked::new("password", '*'), Style::new().fg(Color::Red)),
         ]),
         Line::from("This is a line "),
         Line::from("This is a line   ".red()),
@@ -131,10 +154,7 @@ fn ui(f: &mut Frame, app: &mut App) {
         Line::from("This is a line".reset()),
         Line::from(vec![
             Span::raw("Masked text: "),
-            Span::styled(
-                Masked::new("password", '*'),
-                Style::default().fg(Color::Red),
-            ),
+            Span::styled(Masked::new("password", '*'), Style::new().fg(Color::Red)),
         ]),
     ];
     app.vertical_scroll_state = app.vertical_scroll_state.content_length(text.len());
@@ -142,9 +162,9 @@ fn ui(f: &mut Frame, app: &mut App) {
 
     let create_block = |title: &'static str| Block::bordered().gray().title(title.bold());
 
-    let title = Block::default()
-        .title("Use h j k l or ◄ ▲ ▼ ► to scroll ".bold())
-        .title_alignment(Alignment::Center);
+    let title = Block::new()
+        .title_alignment(Alignment::Center)
+        .title("Use h j k l or ◄ ▲ ▼ ► to scroll ".bold());
     f.render_widget(title, chunks[0]);
 
     let paragraph = Paragraph::new(text.clone())
@@ -153,8 +173,7 @@ fn ui(f: &mut Frame, app: &mut App) {
         .scroll((app.vertical_scroll as u16, 0));
     f.render_widget(paragraph, chunks[1]);
     f.render_stateful_widget(
-        Scrollbar::default()
-            .orientation(ScrollbarOrientation::VerticalRight)
+        Scrollbar::new(ScrollbarOrientation::VerticalRight)
             .begin_symbol(Some("↑"))
             .end_symbol(Some("↓")),
         chunks[1],
@@ -169,13 +188,12 @@ fn ui(f: &mut Frame, app: &mut App) {
         .scroll((app.vertical_scroll as u16, 0));
     f.render_widget(paragraph, chunks[2]);
     f.render_stateful_widget(
-        Scrollbar::default()
-            .orientation(ScrollbarOrientation::VerticalLeft)
+        Scrollbar::new(ScrollbarOrientation::VerticalLeft)
             .symbols(scrollbar::VERTICAL)
             .begin_symbol(None)
             .track_symbol(None)
             .end_symbol(None),
-        chunks[2].inner(&Margin {
+        chunks[2].inner(Margin {
             vertical: 1,
             horizontal: 0,
         }),
@@ -190,11 +208,10 @@ fn ui(f: &mut Frame, app: &mut App) {
         .scroll((0, app.horizontal_scroll as u16));
     f.render_widget(paragraph, chunks[3]);
     f.render_stateful_widget(
-        Scrollbar::default()
-            .orientation(ScrollbarOrientation::HorizontalBottom)
+        Scrollbar::new(ScrollbarOrientation::HorizontalBottom)
             .thumb_symbol("🬋")
             .end_symbol(None),
-        chunks[3].inner(&Margin {
+        chunks[3].inner(Margin {
             vertical: 0,
             horizontal: 1,
         }),
@@ -209,11 +226,10 @@ fn ui(f: &mut Frame, app: &mut App) {
         .scroll((0, app.horizontal_scroll as u16));
     f.render_widget(paragraph, chunks[4]);
     f.render_stateful_widget(
-        Scrollbar::default()
-            .orientation(ScrollbarOrientation::HorizontalBottom)
+        Scrollbar::new(ScrollbarOrientation::HorizontalBottom)
             .thumb_symbol("░")
             .track_symbol(Some("─")),
-        chunks[4].inner(&Margin {
+        chunks[4].inner(Margin {
             vertical: 0,
             horizontal: 1,
         }),

examples/sparkline.rs

@@ -1,29 +1,50 @@
+//! # [Ratatui] Sparkline example
+//!
+//! The latest version of this example is available in the [examples] folder in the repository.
+//!
+//! Please note that the examples are designed to be run against the `main` branch of the Github
+//! repository. This means that you may not be able to compile with the latest release version on
+//! crates.io, or the one that you have installed locally.
+//!
+//! See the [examples readme] for more information on finding examples that match the version of the
+//! library you are using.
+//!
+//! [Ratatui]: https://github.com/ratatui-org/ratatui
+//! [examples]: https://github.com/ratatui-org/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui-org/ratatui/blob/main/examples/README.md
+
 use std::{
     error::Error,
     io,
     time::{Duration, Instant},
 };
 
-use crossterm::{
-    event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode},
-    execute,
-    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-};
 use rand::{
     distributions::{Distribution, Uniform},
     rngs::ThreadRng,
 };
-use ratatui::{prelude::*, widgets::*};
+use ratatui::{
+    backend::{Backend, CrosstermBackend},
+    crossterm::{
+        event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode},
+        execute,
+        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+    },
+    layout::{Constraint, Layout},
+    style::{Color, Style},
+    terminal::{Frame, Terminal},
+    widgets::{Block, Borders, Sparkline},
+};
 
 #[derive(Clone)]
-pub struct RandomSignal {
+struct RandomSignal {
     distribution: Uniform<u64>,
     rng: ThreadRng,
 }
 
 impl RandomSignal {
-    pub fn new(lower: u64, upper: u64) -> RandomSignal {
-        RandomSignal {
+    fn new(lower: u64, upper: u64) -> Self {
+        Self {
             distribution: Uniform::new(lower, upper),
             rng: rand::thread_rng(),
         }
@@ -45,12 +66,12 @@ struct App {
 }
 
 impl App {
-    fn new() -> App {
+    fn new() -> Self {
         let mut signal = RandomSignal::new(0, 100);
         let data1 = signal.by_ref().take(200).collect::<Vec<u64>>();
         let data2 = signal.by_ref().take(200).collect::<Vec<u64>>();
         let data3 = signal.by_ref().take(200).collect::<Vec<u64>>();
-        App {
+        Self {
             signal,
             data1,
             data2,
@@ -112,7 +133,7 @@ fn run_app<B: Backend>(
         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 {
+                if key.code == KeyCode::Char('q') {
                     return Ok(());
                 }
             }
@@ -133,18 +154,18 @@ fn ui(f: &mut Frame, app: &App) {
     .split(f.size());
     let sparkline = Sparkline::default()
         .block(
-            Block::default()
-                .title("Data1")
-                .borders(Borders::LEFT | Borders::RIGHT),
+            Block::new()
+                .borders(Borders::LEFT | Borders::RIGHT)
+                .title("Data1"),
         )
         .data(&app.data1)
         .style(Style::default().fg(Color::Yellow));
     f.render_widget(sparkline, chunks[0]);
     let sparkline = Sparkline::default()
         .block(
-            Block::default()
-                .title("Data2")
-                .borders(Borders::LEFT | Borders::RIGHT),
+            Block::new()
+                .borders(Borders::LEFT | Borders::RIGHT)
+                .title("Data2"),
         )
         .data(&app.data2)
         .style(Style::default().bg(Color::Green));
@@ -152,9 +173,9 @@ fn ui(f: &mut Frame, app: &App) {
     // Multiline
     let sparkline = Sparkline::default()
         .block(
-            Block::default()
-                .title("Data3")
-                .borders(Borders::LEFT | Borders::RIGHT),
+            Block::new()
+                .borders(Borders::LEFT | Borders::RIGHT)
+                .title("Data3"),
         )
         .data(&app.data3)
         .style(Style::default().fg(Color::Red));

examples/table.rs

@@ -1,12 +1,37 @@
+//! # [Ratatui] Table example
+//!
+//! The latest version of this example is available in the [examples] folder in the repository.
+//!
+//! Please note that the examples are designed to be run against the `main` branch of the Github
+//! repository. This means that you may not be able to compile with the latest release version on
+//! crates.io, or the one that you have installed locally.
+//!
+//! See the [examples readme] for more information on finding examples that match the version of the
+//! library you are using.
+//!
+//! [Ratatui]: https://github.com/ratatui-org/ratatui
+//! [examples]: https://github.com/ratatui-org/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui-org/ratatui/blob/main/examples/README.md
+
 use std::{error::Error, io};
 
-use crossterm::{
-    event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode, KeyEventKind},
-    execute,
-    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-};
 use itertools::Itertools;
-use ratatui::{prelude::*, widgets::*};
+use ratatui::{
+    backend::{Backend, CrosstermBackend},
+    crossterm::{
+        event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode, KeyEventKind},
+        execute,
+        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+    },
+    layout::{Constraint, Layout, Margin, Rect},
+    style::{self, Color, Modifier, Style, Stylize},
+    terminal::{Frame, Terminal},
+    text::{Line, Text},
+    widgets::{
+        Block, BorderType, Cell, HighlightSpacing, Paragraph, Row, Scrollbar, ScrollbarOrientation,
+        ScrollbarState, Table, TableState,
+    },
+};
 use style::palette::tailwind;
 use unicode_width::UnicodeWidthStr;
 
@@ -33,7 +58,7 @@ struct TableColors {
 }
 
 impl TableColors {
-    fn new(color: &tailwind::Palette) -> Self {
+    const fn new(color: &tailwind::Palette) -> Self {
         Self {
             buffer_bg: tailwind::SLATE.c950,
             header_bg: color.c900,
@@ -54,7 +79,7 @@ struct Data {
 }
 
 impl Data {
-    fn ref_array(&self) -> [&String; 3] {
+    const fn ref_array(&self) -> [&String; 3] {
         [&self.name, &self.address, &self.email]
     }
 
@@ -81,9 +106,9 @@ struct App {
 }
 
 impl App {
-    fn new() -> App {
+    fn new() -> Self {
         let data_vec = generate_fake_names();
-        App {
+        Self {
             state: TableState::default().with_selected(0),
             longest_item_lens: constraint_len_calculator(&data_vec),
             scroll_state: ScrollbarState::new((data_vec.len() - 1) * ITEM_HEIGHT),
@@ -132,7 +157,7 @@ impl App {
     }
 
     pub fn set_colors(&mut self) {
-        self.colors = TableColors::new(&PALETTES[self.color_index])
+        self.colors = TableColors::new(&PALETTES[self.color_index]);
     }
 }
 
@@ -195,13 +220,12 @@ fn run_app<B: Backend>(terminal: &mut Terminal<B>, mut app: App) -> io::Result<(
 
         if let Event::Key(key) = event::read()? {
             if key.kind == KeyEventKind::Press {
-                use KeyCode::*;
                 match key.code {
-                    Char('q') | Esc => return Ok(()),
-                    Char('j') | Down => app.next(),
-                    Char('k') | Up => app.previous(),
-                    Char('l') | Right => app.next_color(),
-                    Char('h') | Left => app.previous_color(),
+                    KeyCode::Char('q') | KeyCode::Esc => return Ok(()),
+                    KeyCode::Char('j') | KeyCode::Down => app.next(),
+                    KeyCode::Char('k') | KeyCode::Up => app.previous(),
+                    KeyCode::Char('l') | KeyCode::Right => app.next_color(),
+                    KeyCode::Char('h') | KeyCode::Left => app.previous_color(),
                     _ => {}
                 }
             }
@@ -230,8 +254,7 @@ fn render_table(f: &mut Frame, app: &mut App, area: Rect) {
         .fg(app.colors.selected_style_fg);
 
     let header = ["Name", "Address", "Email"]
-        .iter()
-        .cloned()
+        .into_iter()
         .map(Cell::from)
         .collect::<Row>()
         .style(header_style)
@@ -242,9 +265,8 @@ fn render_table(f: &mut Frame, app: &mut App, area: Rect) {
             _ => app.colors.alt_row_color,
         };
         let item = data.ref_array();
-        item.iter()
-            .cloned()
-            .map(|content| Cell::from(Text::from(format!("\n{}\n", content))))
+        item.into_iter()
+            .map(|content| Cell::from(Text::from(format!("\n{content}\n"))))
             .collect::<Row>()
             .style(Style::new().fg(app.colors.row_fg).bg(color))
             .height(4)
@@ -293,6 +315,7 @@ fn constraint_len_calculator(items: &[Data]) -> (u16, u16, u16) {
         .max()
         .unwrap_or(0);
 
+    #[allow(clippy::cast_possible_truncation)]
     (name_len as u16, address_len as u16, email_len as u16)
 }
 
@@ -302,7 +325,7 @@ fn render_scrollbar(f: &mut Frame, app: &mut App, area: Rect) {
             .orientation(ScrollbarOrientation::VerticalRight)
             .begin_symbol(None)
             .end_symbol(None),
-        area.inner(&Margin {
+        area.inner(Margin {
             vertical: 1,
             horizontal: 1,
         }),
@@ -310,15 +333,14 @@ fn render_scrollbar(f: &mut Frame, app: &mut App, area: Rect) {
     );
 }
 
-fn render_footer(f: &mut Frame, app: &mut App, area: Rect) {
+fn render_footer(f: &mut Frame, app: &App, area: Rect) {
     let info_footer = Paragraph::new(Line::from(INFO_TEXT))
         .style(Style::new().fg(app.colors.row_fg).bg(app.colors.buffer_bg))
-        .alignment(Alignment::Center)
+        .centered()
         .block(
-            Block::default()
-                .borders(Borders::ALL)
-                .border_style(Style::new().fg(app.colors.footer_border_color))
-                .border_type(BorderType::Double),
+            Block::bordered()
+                .border_type(BorderType::Double)
+                .border_style(Style::new().fg(app.colors.footer_border_color)),
         );
     f.render_widget(info_footer, area);
 }

examples/tabs.rs

@@ -1,109 +1,257 @@
-use std::{error::Error, io};
+//! # [Ratatui] Tabs example
+//!
+//! The latest version of this example is available in the [examples] folder in the repository.
+//!
+//! Please note that the examples are designed to be run against the `main` branch of the Github
+//! repository. This means that you may not be able to compile with the latest release version on
+//! crates.io, or the one that you have installed locally.
+//!
+//! See the [examples readme] for more information on finding examples that match the version of the
+//! library you are using.
+//!
+//! [Ratatui]: https://github.com/ratatui-org/ratatui
+//! [examples]: https://github.com/ratatui-org/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui-org/ratatui/blob/main/examples/README.md
 
-use crossterm::{
-    event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode, KeyEventKind},
-    execute,
-    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+use std::io::stdout;
+
+use color_eyre::{config::HookBuilder, Result};
+use ratatui::{
+    backend::{Backend, CrosstermBackend},
+    buffer::Buffer,
+    crossterm::{
+        event::{self, Event, KeyCode, KeyEventKind},
+        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+        ExecutableCommand,
+    },
+    layout::{Constraint, Layout, Rect},
+    style::{palette::tailwind, Color, Stylize},
+    symbols,
+    terminal::Terminal,
+    text::Line,
+    widgets::{Block, Padding, Paragraph, Tabs, Widget},
 };
-use ratatui::{prelude::*, widgets::*};
+use strum::{Display, EnumIter, FromRepr, IntoEnumIterator};
 
-struct App<'a> {
-    pub titles: Vec<&'a str>,
-    pub index: usize,
+#[derive(Default)]
+struct App {
+    state: AppState,
+    selected_tab: SelectedTab,
 }
 
-impl<'a> App<'a> {
-    fn new() -> App<'a> {
-        App {
-            titles: vec!["Tab0", "Tab1", "Tab2", "Tab3"],
-            index: 0,
-        }
-    }
-
-    pub fn next(&mut self) {
-        self.index = (self.index + 1) % self.titles.len();
-    }
-
-    pub fn previous(&mut self) {
-        if self.index > 0 {
-            self.index -= 1;
-        } else {
-            self.index = self.titles.len() - 1;
-        }
-    }
+#[derive(Default, Clone, Copy, PartialEq, Eq)]
+enum AppState {
+    #[default]
+    Running,
+    Quitting,
 }
 
-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 app = App::new();
-    let res = run_app(&mut terminal, app);
-
-    // restore terminal
-    disable_raw_mode()?;
-    execute!(
-        terminal.backend_mut(),
-        LeaveAlternateScreen,
-        DisableMouseCapture
-    )?;
-    terminal.show_cursor()?;
-
-    if let Err(err) = res {
-        println!("{err:?}");
-    }
+#[derive(Default, Clone, Copy, Display, FromRepr, EnumIter)]
+enum SelectedTab {
+    #[default]
+    #[strum(to_string = "Tab 1")]
+    Tab1,
+    #[strum(to_string = "Tab 2")]
+    Tab2,
+    #[strum(to_string = "Tab 3")]
+    Tab3,
+    #[strum(to_string = "Tab 4")]
+    Tab4,
+}
 
+fn main() -> Result<()> {
+    init_error_hooks()?;
+    let mut terminal = init_terminal()?;
+    App::default().run(&mut terminal)?;
+    restore_terminal()?;
     Ok(())
 }
 
-fn run_app<B: Backend>(terminal: &mut Terminal<B>, mut app: App) -> io::Result<()> {
-    loop {
-        terminal.draw(|f| ui(f, &app))?;
+impl App {
+    fn run(&mut self, terminal: &mut Terminal<impl Backend>) -> Result<()> {
+        while self.state == AppState::Running {
+            self.draw(terminal)?;
+            self.handle_events()?;
+        }
+        Ok(())
+    }
 
+    fn draw(&self, terminal: &mut Terminal<impl Backend>) -> Result<()> {
+        terminal.draw(|frame| frame.render_widget(self, frame.size()))?;
+        Ok(())
+    }
+
+    fn handle_events(&mut self) -> std::io::Result<()> {
         if let Event::Key(key) = event::read()? {
             if key.kind == KeyEventKind::Press {
                 match key.code {
-                    KeyCode::Char('q') => return Ok(()),
-                    KeyCode::Right | KeyCode::Char('l') => app.next(),
-                    KeyCode::Left | KeyCode::Char('h') => app.previous(),
+                    KeyCode::Char('l') | KeyCode::Right => self.next_tab(),
+                    KeyCode::Char('h') | KeyCode::Left => self.previous_tab(),
+                    KeyCode::Char('q') | KeyCode::Esc => self.quit(),
                     _ => {}
                 }
             }
         }
+        Ok(())
+    }
+
+    pub fn next_tab(&mut self) {
+        self.selected_tab = self.selected_tab.next();
+    }
+
+    pub fn previous_tab(&mut self) {
+        self.selected_tab = self.selected_tab.previous();
+    }
+
+    pub fn quit(&mut self) {
+        self.state = AppState::Quitting;
     }
 }
 
-fn ui(f: &mut Frame, app: &App) {
-    let area = f.size();
-    let vertical = Layout::vertical([Constraint::Length(3), Constraint::Min(0)]);
-    let [tabs_area, inner_area] = area.split(&vertical);
+impl SelectedTab {
+    /// Get the previous tab, if there is no previous tab return the current tab.
+    fn previous(self) -> Self {
+        let current_index: usize = self as usize;
+        let previous_index = current_index.saturating_sub(1);
+        Self::from_repr(previous_index).unwrap_or(self)
+    }
 
-    let block = Block::default().on_white().black();
-    f.render_widget(block, area);
-    let tabs = app
-        .titles
-        .iter()
-        .map(|t| {
-            let (first, rest) = t.split_at(1);
-            Line::from(vec![first.yellow(), rest.green()])
-        })
-        .collect::<Tabs>()
-        .block(Block::default().borders(Borders::ALL).title("Tabs"))
-        .select(app.index)
-        .style(Style::default().cyan().on_gray())
-        .highlight_style(Style::default().bold().on_black());
-    f.render_widget(tabs, tabs_area);
-    let inner = match app.index {
-        0 => Block::default().title("Inner 0").borders(Borders::ALL),
-        1 => Block::default().title("Inner 1").borders(Borders::ALL),
-        2 => Block::default().title("Inner 2").borders(Borders::ALL),
-        3 => Block::default().title("Inner 3").borders(Borders::ALL),
-        _ => unreachable!(),
-    };
-    f.render_widget(inner, inner_area);
+    /// Get the next tab, if there is no next tab return the current tab.
+    fn next(self) -> Self {
+        let current_index = self as usize;
+        let next_index = current_index.saturating_add(1);
+        Self::from_repr(next_index).unwrap_or(self)
+    }
+}
+
+impl Widget for &App {
+    fn render(self, area: Rect, buf: &mut Buffer) {
+        use Constraint::{Length, Min};
+        let vertical = Layout::vertical([Length(1), Min(0), Length(1)]);
+        let [header_area, inner_area, footer_area] = vertical.areas(area);
+
+        let horizontal = Layout::horizontal([Min(0), Length(20)]);
+        let [tabs_area, title_area] = horizontal.areas(header_area);
+
+        render_title(title_area, buf);
+        self.render_tabs(tabs_area, buf);
+        self.selected_tab.render(inner_area, buf);
+        render_footer(footer_area, buf);
+    }
+}
+
+impl App {
+    fn render_tabs(&self, area: Rect, buf: &mut Buffer) {
+        let titles = SelectedTab::iter().map(SelectedTab::title);
+        let highlight_style = (Color::default(), self.selected_tab.palette().c700);
+        let selected_tab_index = self.selected_tab as usize;
+        Tabs::new(titles)
+            .highlight_style(highlight_style)
+            .select(selected_tab_index)
+            .padding("", "")
+            .divider(" ")
+            .render(area, buf);
+    }
+}
+
+fn render_title(area: Rect, buf: &mut Buffer) {
+    "Ratatui Tabs Example".bold().render(area, buf);
+}
+
+fn render_footer(area: Rect, buf: &mut Buffer) {
+    Line::raw("◄ ► to change tab | Press q to quit")
+        .centered()
+        .render(area, buf);
+}
+
+impl Widget for SelectedTab {
+    fn render(self, area: Rect, buf: &mut Buffer) {
+        // in a real app these might be separate widgets
+        match self {
+            Self::Tab1 => self.render_tab0(area, buf),
+            Self::Tab2 => self.render_tab1(area, buf),
+            Self::Tab3 => self.render_tab2(area, buf),
+            Self::Tab4 => self.render_tab3(area, buf),
+        }
+    }
+}
+
+impl SelectedTab {
+    /// Return tab's name as a styled `Line`
+    fn title(self) -> Line<'static> {
+        format!("  {self}  ")
+            .fg(tailwind::SLATE.c200)
+            .bg(self.palette().c900)
+            .into()
+    }
+
+    fn render_tab0(self, area: Rect, buf: &mut Buffer) {
+        Paragraph::new("Hello, World!")
+            .block(self.block())
+            .render(area, buf);
+    }
+
+    fn render_tab1(self, area: Rect, buf: &mut Buffer) {
+        Paragraph::new("Welcome to the Ratatui tabs example!")
+            .block(self.block())
+            .render(area, buf);
+    }
+
+    fn render_tab2(self, area: Rect, buf: &mut Buffer) {
+        Paragraph::new("Look! I'm different than others!")
+            .block(self.block())
+            .render(area, buf);
+    }
+
+    fn render_tab3(self, area: Rect, buf: &mut Buffer) {
+        Paragraph::new("I know, these are some basic changes. But I think you got the main idea.")
+            .block(self.block())
+            .render(area, buf);
+    }
+
+    /// A block surrounding the tab's content
+    fn block(self) -> Block<'static> {
+        Block::bordered()
+            .border_set(symbols::border::PROPORTIONAL_TALL)
+            .padding(Padding::horizontal(1))
+            .border_style(self.palette().c700)
+    }
+
+    const fn palette(self) -> tailwind::Palette {
+        match self {
+            Self::Tab1 => tailwind::BLUE,
+            Self::Tab2 => tailwind::EMERALD,
+            Self::Tab3 => tailwind::INDIGO,
+            Self::Tab4 => tailwind::RED,
+        }
+    }
+}
+
+fn init_error_hooks() -> color_eyre::Result<()> {
+    let (panic, error) = HookBuilder::default().into_hooks();
+    let panic = panic.into_panic_hook();
+    let error = error.into_eyre_hook();
+    color_eyre::eyre::set_hook(Box::new(move |e| {
+        let _ = restore_terminal();
+        error(e)
+    }))?;
+    std::panic::set_hook(Box::new(move |info| {
+        let _ = restore_terminal();
+        panic(info);
+    }));
+    Ok(())
+}
+
+fn init_terminal() -> color_eyre::Result<Terminal<impl Backend>> {
+    enable_raw_mode()?;
+    stdout().execute(EnterAlternateScreen)?;
+    let backend = CrosstermBackend::new(stdout());
+    let terminal = Terminal::new(backend)?;
+    Ok(terminal)
+}
+
+fn restore_terminal() -> color_eyre::Result<()> {
+    disable_raw_mode()?;
+    stdout().execute(LeaveAlternateScreen)?;
+    Ok(())
 }

examples/tracing.rs

@@ -0,0 +1,154 @@
+//! # [Ratatui] Tracing example
+//!
+//! The latest version of this example is available in the [examples] folder in the repository.
+//!
+//! Please note that the examples are designed to be run against the `main` branch of the Github
+//! repository. This means that you may not be able to compile with the latest release version on
+//! crates.io, or the one that you have installed locally.
+//!
+//! See the [examples readme] for more information on finding examples that match the version of the
+//! library you are using.
+//!
+//! [Ratatui]: https://github.com/ratatui-org/ratatui
+//! [examples]: https://github.com/ratatui-org/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui-org/ratatui/blob/main/examples/README.md
+
+// A simple example demonstrating how to use the [tracing] with Ratatui to log to a file.
+//
+// This example demonstrates how to use the [tracing] crate with Ratatui to log to a file. The
+// example sets up a simple logger that logs to a file named `tracing.log` in the current directory.
+//
+// Run the example with `cargo run --example tracing` and then view the `tracing.log` file to see
+// the logs. To see more logs, you can run the example with `RUST_LOG=tracing=debug cargo run
+// --example`
+//
+// For a helpful widget that handles logging, see the [tui-logger] crate.
+//
+// [tracing]: https://crates.io/crates/tracing
+// [tui-logger]: https://crates.io/crates/tui-logger
+
+use std::{fs::File, io::stdout, panic, time::Duration};
+
+use color_eyre::{
+    config::HookBuilder,
+    eyre::{self, Context},
+    Result,
+};
+use crossterm::{
+    event::{self, Event, KeyCode},
+    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+    ExecutableCommand,
+};
+use ratatui::{
+    backend::{Backend, CrosstermBackend},
+    terminal::Terminal,
+    widgets::{Block, Paragraph},
+};
+use tracing::{debug, info, instrument, trace, Level};
+use tracing_appender::{non_blocking, non_blocking::WorkerGuard};
+use tracing_subscriber::EnvFilter;
+
+fn main() -> Result<()> {
+    init_error_hooks()?;
+    let _guard = init_tracing()?;
+    info!("Starting tracing example");
+
+    let mut terminal = init_terminal()?;
+    let mut events = vec![]; // a buffer to store the recent events to display in the UI
+    while !should_exit(&events) {
+        handle_events(&mut events)?;
+        terminal.draw(|frame| ui(frame, &events))?;
+    }
+    restore_terminal()?;
+    info!("Exiting tracing example");
+    println!("See the tracing.log file for the logs");
+    Ok(())
+}
+
+fn should_exit(events: &[Event]) -> bool {
+    events
+        .iter()
+        .any(|event| matches!(event, Event::Key(key) if key.code == KeyCode::Char('q')))
+}
+
+/// Handle events and insert them into the events vector keeping only the last 10 events
+#[instrument(skip(events))]
+fn handle_events(events: &mut Vec<Event>) -> Result<()> {
+    // Render the UI at least once every 100ms
+    if event::poll(Duration::from_millis(100))? {
+        let event = event::read()?;
+        debug!(?event);
+        events.insert(0, event);
+    }
+    events.truncate(10);
+    Ok(())
+}
+
+#[instrument(skip_all)]
+fn ui(frame: &mut ratatui::Frame, events: &[Event]) {
+    // To view this event, run the example with `RUST_LOG=tracing=debug cargo run --example tracing`
+    trace!(frame_count = frame.count(), event_count = events.len());
+    let area = frame.size();
+    let events = events.iter().map(|e| format!("{e:?}")).collect::<Vec<_>>();
+    let paragraph = Paragraph::new(events.join("\n"))
+        .block(Block::bordered().title("Tracing example. Press 'q' to quit."));
+    frame.render_widget(paragraph, area);
+}
+
+/// Initialize the tracing subscriber to log to a file
+///
+/// This function initializes the tracing subscriber to log to a file named `tracing.log` in the
+/// current directory. The function returns a [`WorkerGuard`] that must be kept alive for the
+/// duration of the program to ensure that logs are flushed to the file on shutdown. The logs are
+/// written in a non-blocking fashion to ensure that the logs do not block the main thread.
+fn init_tracing() -> Result<WorkerGuard> {
+    let file = File::create("tracing.log").wrap_err("failed to create tracing.log")?;
+    let (non_blocking, guard) = non_blocking(file);
+
+    // By default, the subscriber is configured to log all events with a level of `DEBUG` or higher,
+    // but this can be changed by setting the `RUST_LOG` environment variable.
+    let env_filter = EnvFilter::builder()
+        .with_default_directive(Level::DEBUG.into())
+        .from_env_lossy();
+
+    tracing_subscriber::fmt()
+        .with_writer(non_blocking)
+        .with_env_filter(env_filter)
+        .init();
+    Ok(guard)
+}
+
+/// Initialize the error hooks to ensure that the terminal is restored to a sane state before
+/// exiting
+fn init_error_hooks() -> Result<()> {
+    let (panic, error) = HookBuilder::default().into_hooks();
+    let panic = panic.into_panic_hook();
+    let error = error.into_eyre_hook();
+    eyre::set_hook(Box::new(move |e| {
+        let _ = restore_terminal();
+        error(e)
+    }))?;
+    panic::set_hook(Box::new(move |info| {
+        let _ = restore_terminal();
+        panic(info);
+    }));
+    Ok(())
+}
+
+#[instrument]
+fn init_terminal() -> Result<Terminal<impl Backend>> {
+    enable_raw_mode()?;
+    stdout().execute(EnterAlternateScreen)?;
+    let backend = CrosstermBackend::new(stdout());
+    let terminal = Terminal::new(backend)?;
+    debug!("terminal initialized");
+    Ok(terminal)
+}
+
+#[instrument]
+fn restore_terminal() -> Result<()> {
+    disable_raw_mode()?;
+    stdout().execute(LeaveAlternateScreen)?;
+    debug!("terminal restored");
+    Ok(())
+}

examples/user_input.rs

@@ -1,25 +1,47 @@
+//! # [Ratatui] User Input example
+//!
+//! The latest version of this example is available in the [examples] folder in the repository.
+//!
+//! Please note that the examples are designed to be run against the `main` branch of the Github
+//! repository. This means that you may not be able to compile with the latest release version on
+//! crates.io, or the one that you have installed locally.
+//!
+//! See the [examples readme] for more information on finding examples that match the version of the
+//! library you are using.
+//!
+//! [Ratatui]: https://github.com/ratatui-org/ratatui
+//! [examples]: https://github.com/ratatui-org/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui-org/ratatui/blob/main/examples/README.md
+
+// A simple example demonstrating how to handle user input. This is a bit out of the scope of
+// the library as it does not provide any input handling out of the box. However, it may helps
+// some to get started.
+//
+// This is a very simple example:
+//   * An input box always focused. Every character you type is registered here.
+//   * An entered character is inserted at the cursor position.
+//   * Pressing Backspace erases the left character before the cursor position
+//   * Pressing Enter pushes the current input in the history of previous messages. **Note: ** as
+//   this is a relatively simple example unicode characters are unsupported and their use will
+// result in undefined behaviour.
+//
+// See also https://github.com/rhysd/tui-textarea and https://github.com/sayanarijit/tui-input/
+
 use std::{error::Error, io};
 
-/// A simple example demonstrating how to handle user input. This is
-/// a bit out of the scope of the library as it does not provide any
-/// input handling out of the box. However, it may helps some to get
-/// started.
-///
-/// This is a very simple example:
-///   * An input box always focused. Every character you type is registered
-///   here.
-///   * An entered character is inserted at the cursor position.
-///   * Pressing Backspace erases the left character before the cursor position
-///   * Pressing Enter pushes the current input in the history of previous
-///   messages.
-/// **Note: ** as this is a relatively simple example unicode characters are unsupported and
-/// their use will result in undefined behaviour.
-use crossterm::{
-    event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode, KeyEventKind},
-    execute,
-    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+use ratatui::{
+    backend::{Backend, CrosstermBackend},
+    crossterm::{
+        event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode, KeyEventKind},
+        execute,
+        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+    },
+    layout::{Constraint, Layout},
+    style::{Color, Modifier, Style, Stylize},
+    terminal::{Frame, Terminal},
+    text::{Line, Span, Text},
+    widgets::{Block, List, ListItem, Paragraph},
 };
-use ratatui::{prelude::*, widgets::*};
 
 enum InputMode {
     Normal,
@@ -31,49 +53,59 @@ struct App {
     /// Current value of the input box
     input: String,
     /// Position of cursor in the editor area.
-    cursor_position: usize,
+    character_index: usize,
     /// Current input mode
     input_mode: InputMode,
     /// History of recorded messages
     messages: Vec<String>,
 }
 
-impl Default for App {
-    fn default() -> App {
-        App {
+impl App {
+    const fn new() -> Self {
+        Self {
             input: String::new(),
             input_mode: InputMode::Normal,
             messages: Vec::new(),
-            cursor_position: 0,
+            character_index: 0,
         }
     }
-}
 
-impl App {
     fn move_cursor_left(&mut self) {
-        let cursor_moved_left = self.cursor_position.saturating_sub(1);
-        self.cursor_position = self.clamp_cursor(cursor_moved_left);
+        let cursor_moved_left = self.character_index.saturating_sub(1);
+        self.character_index = self.clamp_cursor(cursor_moved_left);
     }
 
     fn move_cursor_right(&mut self) {
-        let cursor_moved_right = self.cursor_position.saturating_add(1);
-        self.cursor_position = self.clamp_cursor(cursor_moved_right);
+        let cursor_moved_right = self.character_index.saturating_add(1);
+        self.character_index = self.clamp_cursor(cursor_moved_right);
     }
 
     fn enter_char(&mut self, new_char: char) {
-        self.input.insert(self.cursor_position, new_char);
-
+        let index = self.byte_index();
+        self.input.insert(index, new_char);
         self.move_cursor_right();
     }
 
+    /// Returns the byte index based on the character position.
+    ///
+    /// Since each character in a string can be contain multiple bytes, it's necessary to calculate
+    /// the byte index based on the index of the character.
+    fn byte_index(&self) -> usize {
+        self.input
+            .char_indices()
+            .map(|(i, _)| i)
+            .nth(self.character_index)
+            .unwrap_or(self.input.len())
+    }
+
     fn delete_char(&mut self) {
-        let is_not_cursor_leftmost = self.cursor_position != 0;
+        let is_not_cursor_leftmost = self.character_index != 0;
         if is_not_cursor_leftmost {
             // Method "remove" is not used on the saved text for deleting the selected char.
             // Reason: Using remove on String works on bytes instead of the chars.
             // Using remove would require special care because of char boundaries.
 
-            let current_index = self.cursor_position;
+            let current_index = self.character_index;
             let from_left_to_current_index = current_index - 1;
 
             // Getting all characters before the selected character.
@@ -89,11 +121,11 @@ impl App {
     }
 
     fn clamp_cursor(&self, new_cursor_pos: usize) -> usize {
-        new_cursor_pos.clamp(0, self.input.len())
+        new_cursor_pos.clamp(0, self.input.chars().count())
     }
 
     fn reset_cursor(&mut self) {
-        self.cursor_position = 0;
+        self.character_index = 0;
     }
 
     fn submit_message(&mut self) {
@@ -112,7 +144,7 @@ fn main() -> Result<(), Box<dyn Error>> {
     let mut terminal = Terminal::new(backend)?;
 
     // create app and run it
-    let app = App::default();
+    let app = App::new();
     let res = run_app(&mut terminal, app);
 
     // restore terminal
@@ -165,7 +197,7 @@ fn run_app<B: Backend>(terminal: &mut Terminal<B>, mut app: App) -> io::Result<(
                     }
                     _ => {}
                 },
-                _ => {}
+                InputMode::Editing => {}
             }
         }
     }
@@ -177,7 +209,7 @@ fn ui(f: &mut Frame, app: &App) {
         Constraint::Length(3),
         Constraint::Min(1),
     ]);
-    let [help_area, input_area, messages_area] = f.size().split(&vertical);
+    let [help_area, input_area, messages_area] = vertical.areas(f.size());
 
     let (msg, style) = match app.input_mode {
         InputMode::Normal => (
@@ -210,7 +242,7 @@ fn ui(f: &mut Frame, app: &App) {
             InputMode::Normal => Style::default(),
             InputMode::Editing => Style::default().fg(Color::Yellow),
         })
-        .block(Block::default().borders(Borders::ALL).title("Input"));
+        .block(Block::bordered().title("Input"));
     f.render_widget(input, input_area);
     match app.input_mode {
         InputMode::Normal =>
@@ -220,13 +252,14 @@ fn ui(f: &mut Frame, app: &App) {
         InputMode::Editing => {
             // Make the cursor visible and ask ratatui to put it at the specified coordinates after
             // rendering
+            #[allow(clippy::cast_possible_truncation)]
             f.set_cursor(
                 // Draw the cursor at the current position in the input field.
                 // This position is can be controlled via the left and right arrow key
-                input_area.x + app.cursor_position as u16 + 1,
+                input_area.x + app.character_index as u16 + 1,
                 // Move one line down, from the border to the input line
                 input_area.y + 1,
-            )
+            );
         }
     }
 
@@ -239,7 +272,6 @@ fn ui(f: &mut Frame, app: &App) {
             ListItem::new(content)
         })
         .collect();
-    let messages =
-        List::new(messages).block(Block::default().borders(Borders::ALL).title("Messages"));
+    let messages = List::new(messages).block(Block::bordered().title("Messages"));
     f.render_widget(messages, messages_area);
 }

examples/vhs/constraint-explorer.tape

@@ -0,0 +1,30 @@
+# This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
+# To run this script, install vhs and run `vhs ./examples/constraints.tape`
+Output "target/constraint-explorer.gif"
+Set Theme "Aardvark Blue"
+Set FontSize 18
+Set Width 1200
+Set Height 950
+Hide
+Type "cargo run --example=constraint-explorer --features=crossterm"
+Enter
+Sleep 2s
+Show
+Set TypingSpeed 2s
+Type "1"
+Type "2"
+Right
+Type "4"
+Type "5"
+Up
+Up
+Down
+Down
+Right
+Set TypingSpeed 0.5s
+Type "++++++++"
+Type "--------"
+Type "aaa"
+Sleep 2s
+Type "xxx"
+Hide

examples/vhs/custom_widget.tape

@@ -18,4 +18,4 @@ Space
 Left
 Space
 Left
-Space
+Space

examples/vhs/demo2-destroy.tape

@@ -15,4 +15,4 @@ Enter
 Sleep 2s
 Show
 Type "d"
-Sleep 30s
+Sleep 30s

examples/vhs/demo2-social.tape

@@ -40,4 +40,4 @@ Tab
 # Weather
 Set TypingSpeed 100ms
 Down 40
-Sleep 2s
+Sleep 2s

examples/vhs/demo2.tape

@@ -46,4 +46,4 @@ Tab
 Screenshot "target/demo2-weather.png"
 Set TypingSpeed 100ms
 Down 40
-Sleep 2s
+Sleep 2s

examples/vhs/gauge.tape

@@ -3,10 +3,12 @@
 Output "target/gauge.gif"
 Set Theme "Aardvark Blue"
 Set Width 1200
-Set Height 550
+Set Height 850
 Hide
 Type "cargo run --example=gauge --features=crossterm"
 Enter
-Sleep 1s
+Sleep 2s
 Show
-Sleep 20s
+Sleep 2s
+Enter 1
+Sleep 15s

examples/vhs/generate.bash

@@ -25,12 +25,12 @@ 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\//}
-    gif=${gif/.tape/.gif}
-    ~/go/bin/vhs $tape --quiet
+for tape_path in examples/vhs/*.tape; do
+    tape_file=${tape_path/examples\/vhs\//} # strip the examples/vhs/ prefix
+    gif_file=${tape_file/.tape/.gif}        # replace the .tape suffix with .gif
+    ~/go/bin/vhs $tape_path --quiet
     # this can be pasted into the examples README.md
-    echo "[${gif}]: https://github.com/ratatui-org/ratatui/blob/images/examples/${gif}?raw=true"
+    echo "[${gif_file}]: https://github.com/ratatui-org/ratatui/blob/images/examples/${gif_file}?raw=true"
 done
 git switch images
 git pull --rebase upstream images

examples/vhs/hyperlink.tape

@@ -0,0 +1,15 @@
+# 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/hyperlink.gif"
+Set Theme "Aardvark Blue"
+Set Width 600
+Set Height 150
+Hide
+Type "cargo run --example=hyperlink --features=crossterm,unstable-widget-ref"
+Enter
+Sleep 2s
+Show
+Sleep 1s
+Hide
+Type "q"
+

examples/vhs/line_gauge.tape

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

examples/vhs/list.tape

@@ -3,13 +3,22 @@
 Output "target/list.gif"
 Set Theme "Aardvark Blue"
 Set Width 1200
-Set Height 600
+Set Height 612
 Hide
 Type "cargo run --example=list --features=crossterm"
 Enter
-Sleep 1s
+Sleep 10s
 Show
-Down@1s 4
-Up@1s 2
+Sleep 2s
+Down@1.5s 3
+Right@1.5s 1
+Sleep 1.5s
+Down@1.5s 3
+Sleep 1.5s
+Up@1s 1
+Sleep 1s
+Right@1.5s 1
+Sleep 1.5s
+Up@1s 4
 Left@1s 1
-Sleep 5s
+Sleep 2s

examples/vhs/minimal.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/hello_world.tape`
+Output "target/minimal.gif"
+Set Theme "Aardvark Blue"
+Set Width 1200
+Set Height 200
+Hide
+Type "cargo run --example=minimal --features=crossterm"
+Enter
+Sleep 1s
+Show
+Sleep 5s