docs(constraint): add note about percentages (#1368)

Co-authored-by: Orhun Parmaksız <orhun@archlinux.org>

.github/CODEOWNERS

@@ -1,8 +1,11 @@
-# See https://help.github.com/articles/about-codeowners/
+# See <https://help.github.com/articles/about-codeowners/>
+
 # for more info about CODEOWNERS file
 
 # It uses the same pattern rule for gitignore file
-# https://git-scm.com/docs/gitignore#_pattern_format
+
+# <https://git-scm.com/docs/gitignore#_pattern_format>
 
 # Maintainers
-* @ratatui-org/maintainers
+
+* @ratatui/maintainers

.github/workflows/ci.yml

@@ -17,20 +17,15 @@ concurrency:
   group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
   cancel-in-progress: true
 
-env:
-  # don't install husky hooks during CI as they are only needed for for pre-push
-  CARGO_HUSKY_DONT_INSTALL_HOOKS: true
-
-# lint, clippy and coveraget jobs are intentionally early in the workflow to catch simple
-# formatting, typos, and missing tests as early as possible. This allows us to fix these and
-# resubmit the PR without having to wait for the comprehensive matrix of tests to complete.
+# lint, clippy and coverage jobs are intentionally early in the workflow to catch simple formatting,
+# typos, and missing tests as early as possible. This allows us to fix these and resubmit the PR
+# without having to wait for the comprehensive matrix of tests to complete.
 jobs:
   rustfmt:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - name: Install Rust nightly
-        uses: dtolnay/rust-toolchain@nightly
+      - uses: dtolnay/rust-toolchain@nightly
         with:
           components: rustfmt
       - run: cargo +nightly fmt --all --check
@@ -47,16 +42,21 @@ jobs:
       - uses: actions/checkout@v4
       - uses: EmbarkStudios/cargo-deny-action@v2
 
+  cargo-machete:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: Swatinem/rust-cache@v2
+      - uses: bnjbvr/cargo-machete@v0.6.2
+
   clippy:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - name: Install Rust stable
-        uses: dtolnay/rust-toolchain@stable
+      - uses: dtolnay/rust-toolchain@stable
         with:
           components: clippy
-      - name: Install cargo-make
-        uses: taiki-e/install-action@cargo-make
+      - uses: taiki-e/install-action@cargo-make
       - uses: Swatinem/rust-cache@v2
       - run: cargo make clippy
 
@@ -64,8 +64,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - name: Lint markdown
-        uses: DavidAnson/markdownlint-cli2-action@v16
+      - uses: DavidAnson/markdownlint-cli2-action@v16
         with:
           globs: |
             '**/*.md'
@@ -75,19 +74,15 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - name: Install Rust stable
-        uses: dtolnay/rust-toolchain@stable
+      - uses: dtolnay/rust-toolchain@stable
         with:
           components: llvm-tools
-      - name: Install cargo-llvm-cov and cargo-make
-        uses: taiki-e/install-action@v2
+      - uses: taiki-e/install-action@v2
         with:
           tool: cargo-llvm-cov,cargo-make
       - uses: Swatinem/rust-cache@v2
-      - name: Generate coverage
-        run: cargo make coverage
-      - name: Upload to codecov.io
-        uses: codecov/codecov-action@v4
+      - run: cargo make coverage
+      - uses: codecov/codecov-action@v4
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
           fail_ci_if_error: true
@@ -101,12 +96,10 @@ jobs:
     runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v4
-      - name: Install Rust {{ matrix.toolchain }}
-        uses: dtolnay/rust-toolchain@master
+      - uses: dtolnay/rust-toolchain@master
         with:
           toolchain: ${{ matrix.toolchain }}
-      - name: Install cargo-make
-        uses: taiki-e/install-action@cargo-make
+      - uses: taiki-e/install-action@cargo-make
       - uses: Swatinem/rust-cache@v2
       - run: cargo make check
         env:
@@ -114,14 +107,17 @@ jobs:
 
   lint-docs:
     runs-on: ubuntu-latest
+    env:
+      RUSTDOCFLAGS: -Dwarnings
     steps:
       - uses: actions/checkout@v4
-      - name: Install Rust nightly
-        uses: dtolnay/rust-toolchain@nightly
-      - name: Install cargo-make
-        uses: taiki-e/install-action@cargo-make
+      - uses: dtolnay/rust-toolchain@nightly
+      - uses: dtolnay/install@cargo-docs-rs
       - uses: Swatinem/rust-cache@v2
-      - run: cargo make lint-docs
+      # Run cargo rustdoc with the same options that would be used by docs.rs, taking into account
+      # the package.metadata.docs.rs configured in Cargo.toml.
+      # https://github.com/dtolnay/cargo-docs-rs
+      - run: cargo +nightly docs-rs
 
   test-doc:
     strategy:
@@ -131,13 +127,10 @@ jobs:
     runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v4
-      - name: Install Rust stable
-        uses: dtolnay/rust-toolchain@stable
-      - name: Install cargo-make
-        uses: taiki-e/install-action@cargo-make
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: taiki-e/install-action@cargo-make
       - uses: Swatinem/rust-cache@v2
-      - name: Test docs
-        run: cargo make test-doc
+      - run: cargo make test-doc
         env:
           RUST_BACKTRACE: full
 
@@ -155,14 +148,12 @@ jobs:
     runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v4
-      - name: Install Rust ${{ matrix.toolchain }}}
-        uses: dtolnay/rust-toolchain@master
+      - uses: dtolnay/rust-toolchain@master
         with:
           toolchain: ${{ matrix.toolchain }}
-      - name: Install cargo-make
-        uses: taiki-e/install-action@cargo-make
-      - name: Install cargo-nextest
-        uses: taiki-e/install-action@nextest
+      - uses: taiki-e/install-action@v2
+        with:
+          tool: cargo-make,nextest
       - uses: Swatinem/rust-cache@v2
       - run: cargo make test-backend ${{ matrix.backend }}
         env:

.github/workflows/release-alpha.yml

@@ -1,4 +1,4 @@
-name: Continuous Deployment
+name: Release alpha version
 
 on:
   workflow_dispatch:
@@ -6,9 +6,6 @@ on:
     # At 00:00 on Saturday
     # https://crontab.guru/#0_0_*_*_6
     - cron: "0 0 * * 6"
-  push:
-    tags:
-      - "v*.*.*"
 
 defaults:
   run:
@@ -20,7 +17,6 @@ jobs:
     runs-on: ubuntu-latest
     permissions:
       contents: write
-    if: ${{ !startsWith(github.event.ref, 'refs/tags/v') }}
     steps:
       - name: Checkout the repository
         uses: actions/checkout@v4
@@ -30,14 +26,14 @@ jobs:
       - name: Calculate the next release
         run: .github/workflows/calculate-alpha-release.bash
 
-      - name: Publish on crates.io
-        uses: actions-rs/cargo@v1
-        with:
-          command: publish
-          args: --allow-dirty --token ${{ secrets.CARGO_TOKEN }}
+      - name: Install Rust stable
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Publish
+        run: cargo publish --allow-dirty --token ${{ secrets.CARGO_TOKEN }}
 
       - name: Generate a changelog
-        uses: orhun/git-cliff-action@v3
+        uses: orhun/git-cliff-action@v4
         with:
           config: cliff.toml
           args: --unreleased --tag ${{ env.NEXT_TAG }} --strip header
@@ -50,17 +46,3 @@ jobs:
           tag: ${{ env.NEXT_TAG }}
           prerelease: true
           bodyFile: BODY.md
-
-  publish-stable:
-    name: Create a stable release
-    runs-on: ubuntu-latest
-    if: ${{ startsWith(github.event.ref, 'refs/tags/v') }}
-    steps:
-      - name: Checkout the repository
-        uses: actions/checkout@v4
-
-      - name: Publish on crates.io
-        uses: actions-rs/cargo@v1
-        with:
-          command: publish
-          args: --token ${{ secrets.CARGO_TOKEN }}

.github/workflows/release-stable.yml

@@ -0,0 +1,45 @@
+name: Release stable version
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+jobs:
+  publish-stable:
+    name: Create an stable release
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout the repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Generate a changelog
+        uses: orhun/git-cliff-action@v4
+        with:
+          config: cliff.toml
+          args: --latest --strip header
+        env:
+          OUTPUT: BODY.md
+
+      - name: Publish on GitHub
+        uses: ncipollo/release-action@v1
+        with:
+          prerelease: false
+          bodyFile: BODY.md
+
+  publish-crate:
+    name: Publish crate
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout the repository
+        uses: actions/checkout@v4
+
+      - name: Install Rust stable
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Publish
+        run: cargo publish --token ${{ secrets.CARGO_TOKEN }}

BREAKING-CHANGES.md

@@ -4,7 +4,7 @@ This document contains a list of breaking changes in each version and some notes
 between versions. It is compiled manually from the commit history and changelog. We also tag PRs on
 GitHub with a [breaking change] label.
 
-[breaking change]: (https://github.com/ratatui-org/ratatui/issues?q=label%3A%22breaking+change%22)
+[breaking change]: (https://github.com/ratatui/ratatui/issues?q=label%3A%22breaking+change%22)
 
 ## Summary
 
@@ -69,14 +69,14 @@ This is a quick summary of the sections below:
 
 ### `Backend::size` returns `Size` instead of `Rect` ([#1254])
 
-[#1254]: https://github.com/ratatui-org/ratatui/pull/1254
+[#1254]: https://github.com/ratatui/ratatui/pull/1254
 
 The `Backend::size` method returns a `Size` instead of a `Rect`.
 There is no need for the position here as it was always 0,0.
 
 ### `Backend` trait migrates to `get/set_cursor_position` ([#1284])
 
-[#1284]: https://github.com/ratatui-org/ratatui/pull/1284
+[#1284]: https://github.com/ratatui/ratatui/pull/1284
 
 If you just use the types implementing the `Backend` trait, you will see deprecation hints but
 nothing is a breaking change for you.
@@ -87,7 +87,7 @@ and a default implementation for them exists.
 
 ### Ratatui now requires Crossterm 0.28.0 ([#1278])
 
-[#1278]: https://github.com/ratatui-org/ratatui/pull/1278
+[#1278]: https://github.com/ratatui/ratatui/pull/1278
 
 Crossterm is updated to version 0.28.0, which is a semver incompatible version with the previous
 version (0.27.0). Ratatui re-exports the version of crossterm that it is compatible with under
@@ -95,8 +95,8 @@ version (0.27.0). Ratatui re-exports the version of crossterm that it is compati
 
 ### `Axis::labels()` now accepts `IntoIterator<Into<Line>>` ([#1273] and [#1283])
 
-[#1273]: https://github.com/ratatui-org/ratatui/pull/1173
-[#1283]: https://github.com/ratatui-org/ratatui/pull/1283
+[#1273]: https://github.com/ratatui/ratatui/pull/1173
+[#1283]: https://github.com/ratatui/ratatui/pull/1283
 
 Previously Axis::labels accepted `Vec<Span>`. Any code that uses conversion methods that infer the
 type will need to be rewritten as the compiler cannot infer the correct type.
@@ -108,7 +108,7 @@ type will need to be rewritten as the compiler cannot infer the correct type.
 
 ### `Layout::init_cache` no longer returns bool and takes a `NonZeroUsize` instead of `usize` ([#1245])
 
-[#1245]: https://github.com/ratatui-org/ratatui/pull/1245
+[#1245]: https://github.com/ratatui/ratatui/pull/1245
 
 ```diff
 - let is_initialized = Layout::init_cache(100);
@@ -117,7 +117,7 @@ type will need to be rewritten as the compiler cannot infer the correct type.
 
 ### `ratatui::terminal` module is now private ([#1160])
 
-[#1160]: https://github.com/ratatui-org/ratatui/pull/1160
+[#1160]: https://github.com/ratatui/ratatui/pull/1160
 
 The `terminal` module is now private and can not be used directly. The types under this module are
 exported from the root of the crate. This reduces clashes with other modules in the backends that
@@ -130,21 +130,21 @@ are also named terminal, and confusion about module exports for newer Rust users
 
 ### `ToText` no longer has a lifetime ([#1234])
 
-[#1234]: https://github.com/ratatui-org/ratatui/pull/1234
+[#1234]: https://github.com/ratatui/ratatui/pull/1234
 
 This change simplifies the trait and makes it easier to implement.
 
 ### `Frame::size` is deprecated and renamed to `Frame::area`
 
-[#1293]: https://github.com/ratatui-org/ratatui/pull/1293
+[#1293]: https://github.com/ratatui/ratatui/pull/1293
 
-`Frame::size` is renamed to `Frame::area` as its the more correct name.
+`Frame::size` is renamed to `Frame::area` as it's the more correct name.
 
-## [v0.27.0](https://github.com/ratatui-org/ratatui/releases/tag/v0.27.0)
+## [v0.27.0](https://github.com/ratatui/ratatui/releases/tag/v0.27.0)
 
 ### List no clamps the selected index to list ([#1159])
 
-[#1149]: https://github.com/ratatui-org/ratatui/pull/1149
+[#1149]: https://github.com/ratatui/ratatui/pull/1149
 
 The `List` widget now clamps the selected index to the bounds of the list when navigating with
 `first`, `last`, `previous`, and `next`, as well as when setting the index directly with `select`.
@@ -205,11 +205,11 @@ A change is only necessary if you were matching on all variants of the `MouseEve
 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
+[#1106]: https://github.com/ratatui/ratatui/pull/1106
 
 ### `Rect::inner` takes `Margin` directly instead of reference ([#1008])
 
-[#1008]: https://github.com/ratatui-org/ratatui/pull/1008
+[#1008]: https://github.com/ratatui/ratatui/pull/1008
 
 `Margin` needs to be passed without reference now.
 
@@ -223,7 +223,7 @@ wildcard. In this case, you need to either handle the two new variants, `MouseLe
 
 ### `Buffer::filled` takes `Cell` directly instead of reference ([#1148])
 
-[#1148]: https://github.com/ratatui-org/ratatui/pull/1148
+[#1148]: https://github.com/ratatui/ratatui/pull/1148
 
 `Buffer::filled` moves the `Cell` instead of taking a reference.
 
@@ -234,14 +234,14 @@ wildcard. In this case, you need to either handle the two new variants, `MouseLe
 
 ### `Stylize::bg()` now accepts `Into<Color>` ([#1103])
 
-[#1103]: https://github.com/ratatui-org/ratatui/pull/1103
+[#1103]: https://github.com/ratatui/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
+[#759]: https://github.com/ratatui/ratatui/pull/759
 
 `List::start_corner` was deprecated in v0.25. Use `List::direction` and `ListDirection` instead.
 
@@ -264,7 +264,7 @@ flexible types from calling scopes, though it can break some type inference in t
 
 ### `LineGauge::gauge_style` is deprecated ([#565])
 
-[#565]: https://github.com/ratatui-org/ratatui/pull/1148
+[#565]: https://github.com/ratatui/ratatui/pull/1148
 
 `LineGauge::gauge_style` is deprecated and replaced with `LineGauge::filled_style` and `LineGauge::unfilled_style`:
 
@@ -275,11 +275,11 @@ let gauge = LineGauge::default()
 + .unfilled_style(Style::default().fg(Color::White));
 ```
 
-## [v0.26.0](https://github.com/ratatui-org/ratatui/releases/tag/v0.26.0)
+## [v0.26.0](https://github.com/ratatui/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
+[#881]: https://github.com/ratatui/ratatui/pull/881
 
 Previously, constraints would stretch to fill all available space, violating constraints if
 necessary.
@@ -300,7 +300,7 @@ existing layouts with `Flex::Start`. However, to get old behavior, use `Flex::Le
 
 ### `Table::new()` now accepts `IntoIterator<Item: Into<Row<'a>>>` ([#774])
 
-[#774]: https://github.com/ratatui-org/ratatui/pull/774
+[#774]: https://github.com/ratatui/ratatui/pull/774
 
 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
@@ -317,7 +317,7 @@ This can be resolved either by providing an explicit type (e.g. `Vec::<Row>::new
 
 ### `Tabs::new()` now accepts `IntoIterator<Item: Into<Line<'a>>>` ([#776])
 
-[#776]: https://github.com/ratatui-org/ratatui/pull/776
+[#776]: https://github.com/ratatui/ratatui/pull/776
 
 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.
@@ -333,7 +333,7 @@ by removing the call to `.collect()`.
 
 ### Table::default() now sets segment_size to None and column_spacing to ([#751])
 
-[#751]: https://github.com/ratatui-org/ratatui/pull/751
+[#751]: https://github.com/ratatui/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.
@@ -343,7 +343,7 @@ To use the previous default values, call `table.segment_size(Default::default())
 
 ### `patch_style` & `reset_style` now consumes and returns `Self` ([#754])
 
-[#754]: https://github.com/ratatui-org/ratatui/pull/754
+[#754]: https://github.com/ratatui/ratatui/pull/754
 
 Previously, `patch_style` and `reset_style` in `Text`, `Line` and `Span` were using a mutable
 reference to `Self`. To be more consistent with the rest of `ratatui`, which is using fluent
@@ -369,7 +369,7 @@ The following example shows how to migrate for `Line`, but the same applies for
 
 ### `Block` style methods cannot be used in a const context ([#720])
 
-[#720]: https://github.com/ratatui-org/ratatui/pull/720
+[#720]: https://github.com/ratatui/ratatui/pull/720
 
 Previously the `style()`, `border_style()` and `title_style()` methods could be used to create a
 `Block` in a constant context. These now accept `Into<Style>` instead of `Style`. These methods no
@@ -377,7 +377,7 @@ longer can be called from a constant context.
 
 ### `Line` now has a `style` field that applies to the entire line ([#708])
 
-[#708]: https://github.com/ratatui-org/ratatui/pull/708
+[#708]: https://github.com/ratatui/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::styled` method. Any code that creates
@@ -401,11 +401,11 @@ the `Span::style` field.
       .alignment(Alignment::Left);
 ```
 
-## [v0.25.0](https://github.com/ratatui-org/ratatui/releases/tag/v0.25.0)
+## [v0.25.0](https://github.com/ratatui/ratatui/releases/tag/v0.25.0)
 
 ### Removed `Axis::title_style` and `Buffer::set_background` ([#691])
 
-[#691]: https://github.com/ratatui-org/ratatui/pull/691
+[#691]: https://github.com/ratatui/ratatui/pull/691
 
 These items were deprecated since 0.10.
 
@@ -419,7 +419,7 @@ These items were deprecated since 0.10.
 
 ### `List::new()` now accepts `IntoIterator<Item = Into<ListItem<'a>>>` ([#672])
 
-[#672]: https://github.com/ratatui-org/ratatui/pull/672
+[#672]: https://github.com/ratatui/ratatui/pull/672
 
 Previously `List::new()` took `Into<Vec<ListItem<'a>>>`. This change will throw a compilation
 error for `IntoIterator`s with an indeterminate item (e.g. empty vecs).
@@ -434,7 +434,7 @@ E.g.
 
 ### The default `Tabs::highlight_style` is now `Style::new().reversed()` ([#635])
 
-[#635]: https://github.com/ratatui-org/ratatui/pull/635
+[#635]: https://github.com/ratatui/ratatui/pull/635
 
 Previously the default highlight style for tabs was `Style::default()`, which meant that a `Tabs`
 widget in the default configuration would not show any indication of the selected tab.
@@ -446,7 +446,7 @@ widget in the default configuration would not show any indication of the selecte
 
 ### `Table::new()` now requires specifying the widths of the columns ([#664])
 
-[#664]: https://github.com/ratatui-org/ratatui/pull/664
+[#664]: https://github.com/ratatui/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:
@@ -472,7 +472,7 @@ or complex, it may be convenient to replace `Table::new` with `Table::default().
 
 ### `Table::widths()` now accepts `IntoIterator<Item = AsRef<Constraint>>` ([#663])
 
-[#663]: https://github.com/ratatui-org/ratatui/pull/663
+[#663]: https://github.com/ratatui/ratatui/pull/663
 
 Previously `Table::widths()` took a slice (`&'a [Constraint]`). This change will introduce clippy
 `needless_borrow` warnings for places where slices are passed to this method. To fix these, remove
@@ -488,7 +488,7 @@ E.g.
 
 ### Layout::new() now accepts direction and constraint parameters ([#557])
 
-[#557]: https://github.com/ratatui-org/ratatui/pull/557
+[#557]: https://github.com/ratatui/ratatui/pull/557
 
 Previously layout new took no parameters. Existing code should either use `Layout::default()` or
 the new constructor.
@@ -505,18 +505,18 @@ let layout = layout::default()
 let layout = layout::new(Direction::Vertical, [Constraint::Min(1), Constraint::Max(2)]);
 ```
 
-## [v0.24.0](https://github.com/ratatui-org/ratatui/releases/tag/v0.24.0)
+## [v0.24.0](https://github.com/ratatui/ratatui/releases/tag/v0.24.0)
 
 ### `ScrollbarState` field type changed from `u16` to `usize` ([#456])
 
-[#456]: https://github.com/ratatui-org/ratatui/pull/456
+[#456]: https://github.com/ratatui/ratatui/pull/456
 
 In order to support larger content lengths, the `position`, `content_length` and
 `viewport_content_length` methods on `ScrollbarState` now take `usize` instead of `u16`
 
 ### `BorderType::line_symbols` renamed to `border_symbols` ([#529])
 
-[#529]: https://github.com/ratatui-org/ratatui/issues/529
+[#529]: https://github.com/ratatui/ratatui/issues/529
 
 Applications can now set custom borders on a `Block` by calling `border_set()`. The
 `BorderType::line_symbols()` is renamed to `border_symbols()` and now returns a new struct
@@ -530,7 +530,7 @@ Applications can now set custom borders on a `Block` by calling `border_set()`.
 
 ### Generic `Backend` parameter removed from `Frame` ([#530])
 
-[#530]: https://github.com/ratatui-org/ratatui/issues/530
+[#530]: https://github.com/ratatui/ratatui/issues/530
 
 `Frame` is no longer generic over Backend. Code that accepted `Frame<Backend>` will now need to
 accept `Frame`. To migrate existing code, remove any generic parameters from code that uses an
@@ -544,7 +544,7 @@ instance of a Frame. E.g.:
 
 ### `Stylize` shorthands now consume rather than borrow `String` ([#466])
 
-[#466]: https://github.com/ratatui-org/ratatui/issues/466
+[#466]: https://github.com/ratatui/ratatui/issues/466
 
 In order to support using `Stylize` shorthands (e.g. `"foo".red()`) on temporary `String` values, a
 new implementation of `Stylize` was added that returns a `Span<'static>`. This causes the value to
@@ -562,7 +562,7 @@ longer compile. E.g.
 
 ### Deprecated `Spans` type removed (replaced with `Line`) ([#426])
 
-[#426]: https://github.com/ratatui-org/ratatui/issues/426
+[#426]: https://github.com/ratatui/ratatui/issues/426
 
 `Spans` was replaced with `Line` in 0.21.0. `Buffer::set_spans` was replaced with
 `Buffer::set_line`.
@@ -575,11 +575,11 @@ longer compile. E.g.
 + buffer.set_line(0, 0, line, 10);
 ```
 
-## [v0.23.0](https://github.com/ratatui-org/ratatui/releases/tag/v0.23.0)
+## [v0.23.0](https://github.com/ratatui/ratatui/releases/tag/v0.23.0)
 
 ### `Scrollbar::track_symbol()` now takes an `Option<&str>` instead of `&str` ([#360])
 
-[#360]: https://github.com/ratatui-org/ratatui/issues/360
+[#360]: https://github.com/ratatui/ratatui/issues/360
 
 The track symbol of `Scrollbar` is now optional, this method now takes an optional value.
 
@@ -591,7 +591,7 @@ The track symbol of `Scrollbar` is now optional, this method now takes an option
 
 ### `Scrollbar` symbols moved to `symbols::scrollbar` and `widgets::scrollbar` module is private ([#330])
 
-[#330]: https://github.com/ratatui-org/ratatui/issues/330
+[#330]: https://github.com/ratatui/ratatui/issues/330
 
 The symbols for defining scrollbars have been moved to the `symbols` module from the
 `widgets::scrollbar` module which is no longer public. To update your code update any imports to the
@@ -605,31 +605,31 @@ new module locations. E.g.:
 
 ### MSRV updated to 1.67 ([#361])
 
-[#361]: https://github.com/ratatui-org/ratatui/issues/361
+[#361]: https://github.com/ratatui/ratatui/issues/361
 
 The MSRV of ratatui is now 1.67 due to an MSRV update in a dependency (`time`).
 
-## [v0.22.0](https://github.com/ratatui-org/ratatui/releases/tag/v0.22.0)
+## [v0.22.0](https://github.com/ratatui/ratatui/releases/tag/v0.22.0)
 
 ### `bitflags` updated to 2.3 ([#205])
 
-[#205]: https://github.com/ratatui-org/ratatui/issues/205
+[#205]: https://github.com/ratatui/ratatui/issues/205
 
 The `serde` representation of `bitflags` has changed. Any existing serialized types that have
 Borders or Modifiers will need to be re-serialized. This is documented in the [`bitflags`
 changelog](https://github.com/bitflags/bitflags/blob/main/CHANGELOG.md#200-rc2)..
 
-## [v0.21.0](https://github.com/ratatui-org/ratatui/releases/tag/v0.21.0)
+## [v0.21.0](https://github.com/ratatui/ratatui/releases/tag/v0.21.0)
 
 ### MSRV is 1.65.0 ([#171])
 
-[#171]: https://github.com/ratatui-org/ratatui/issues/171
+[#171]: https://github.com/ratatui/ratatui/issues/171
 
 The minimum supported rust version is now 1.65.0.
 
 ### `Terminal::with_options()` stabilized to allow configuring the viewport ([#114])
 
-[#114]: https://github.com/ratatui-org/ratatui/issues/114
+[#114]: https://github.com/ratatui/ratatui/issues/114
 
 In order to support inline viewports, the unstable method `Terminal::with_options()` was stabilized
 and `ViewPort` was changed from a struct to an enum.
@@ -646,7 +646,7 @@ let terminal = Terminal::with_options(backend, TerminalOptions {
 
 ### Code that binds `Into<Text<'a>>` now requires type annotations ([#168])
 
-[#168]: https://github.com/ratatui-org/ratatui/issues/168
+[#168]: https://github.com/ratatui/ratatui/issues/168
 
 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
@@ -660,7 +660,7 @@ previously did not need to use type annotations to fail to compile. To fix this,
 
 ### `Marker::Block` now renders as a block rather than a bar character ([#133])
 
-[#133]: https://github.com/ratatui-org/ratatui/issues/133
+[#133]: https://github.com/ratatui/ratatui/issues/133
 
 Code using the `Block` marker that previously rendered using a half block character (`'▀'``) now
 renders using the full block character (`'█'`). A new marker variant`Bar` is introduced to replace
@@ -672,20 +672,20 @@ the existing code.
 + let canvas = Canvas::default().marker(Marker::Bar);
 ```
 
-## [v0.20.0](https://github.com/ratatui-org/ratatui/releases/tag/v0.20.0)
+## [v0.20.0](https://github.com/ratatui/ratatui/releases/tag/v0.20.0)
 
 v0.20.0 was the first release of Ratatui - versions prior to this were release as tui-rs. See the
 [Changelog](./CHANGELOG.md) for more details.
 
 ### MSRV is update to 1.63.0 ([#80])
 
-[#80]: https://github.com/ratatui-org/ratatui/issues/80
+[#80]: https://github.com/ratatui/ratatui/issues/80
 
 The minimum supported rust version is 1.63.0
 
 ### List no longer ignores empty string in items ([#42])
 
-[#42]: https://github.com/ratatui-org/ratatui/issues/42
+[#42]: https://github.com/ratatui/ratatui/issues/42
 
 The following code now renders 3 items instead of 2. Code which relies on the previous behavior will
 need to manually filter empty items prior to display.

CONTRIBUTING.md

@@ -8,7 +8,7 @@ creating a new issue before making the change, or starting a discussion on
 
 ## Reporting issues
 
-Before reporting an issue on the [issue tracker](https://github.com/ratatui-org/ratatui/issues),
+Before reporting an issue on the [issue tracker](https://github.com/ratatui/ratatui/issues),
 please check that it has not already been reported by searching for some related keywords. Please
 also check [`tui-rs` issues](https://github.com/fdehau/tui-rs/issues/) and link any related issues
 found.
@@ -79,14 +79,14 @@ defaults depending on your platform of choice. Building the project should be as
 `cargo make build`.
 
 ```shell
-git clone https://github.com/ratatui-org/ratatui.git
+git clone https://github.com/ratatui/ratatui.git
 cd ratatui
 cargo make build
 ```
 
 ### Tests
 
-The [test coverage](https://app.codecov.io/gh/ratatui-org/ratatui) of the crate is reasonably
+The [test coverage](https://app.codecov.io/gh/ratatui/ratatui) of the crate is reasonably
 good, but this can always be improved. Focus on keeping the tests simple and obvious and write unit
 tests for all new or modified code. Beside the usual doc and unit tests, one of the most valuable
 test you can write for Ratatui is a test against the `TestBackend`. It allows you to assert the
@@ -171,7 +171,7 @@ time to update. However, if a deprecation is blocking for us to implement a new
 
 We don't currently use any unsafe code in Ratatui, and would like to keep it that way. However, there
 may be specific cases that this becomes necessary in order to avoid slowness. Please see [this
-discussion](https://github.com/ratatui-org/ratatui/discussions/66) for more about the decision.
+discussion](https://github.com/ratatui/ratatui/discussions/66) for more about the decision.
 
 ## Continuous Integration
 
@@ -196,7 +196,7 @@ it is useful to refer to when contributing code, documentation, or issues with R
 
 We imported all the PRs from the original repository, implemented many of the smaller ones, and
 made notes on the leftovers. These are marked as draft PRs and labelled as [imported from
-tui](https://github.com/ratatui-org/ratatui/pulls?q=is%3Apr+is%3Aopen+label%3A%22imported+from+tui%22).
+tui](https://github.com/ratatui/ratatui/pulls?q=is%3Apr+is%3Aopen+label%3A%22imported+from+tui%22).
 We have documented the current state of those PRs, and anyone is welcome to pick them up and
 continue the work on them.
 

Cargo.toml

@@ -1,10 +1,10 @@
 [package]
 name = "ratatui"
-version = "0.28.0" # crate version
+version = "0.28.1" # 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/"
-repository = "https://github.com/ratatui-org/ratatui"
+repository = "https://github.com/ratatui/ratatui"
 homepage = "https://ratatui.rs"
 keywords = ["tui", "terminal", "dashboard"]
 categories = ["command-line-interface"]
@@ -21,8 +21,6 @@ exclude = [
 edition = "2021"
 rust-version = "1.74.0"
 
-[badges]
-
 [dependencies]
 bitflags = "2.3"
 cassowary = "0.3"
@@ -35,21 +33,22 @@ lru = "0.12.0"
 paste = "1.0.2"
 palette = { version = "0.7.6", optional = true }
 serde = { version = "1", optional = true, features = ["derive"] }
-strum = { version = "0.26", features = ["derive"] }
-strum_macros = { version = "0.26.3" }
-termion = { version = "4.0.0", optional = true }
+strum = { version = "0.26.3", features = ["derive"] }
 termwiz = { version = "0.22.0", optional = true }
 time = { version = "0.3.11", optional = true, features = ["local-offset"] }
 unicode-segmentation = "1.10"
 unicode-truncate = "1"
 unicode-width = "0.1.13"
 
+[target.'cfg(not(windows))'.dependencies]
+# termion is not supported on Windows
+termion = { version = "4.0.0", optional = true }
+
 [dev-dependencies]
 argh = "0.1.12"
 color-eyre = "0.6.2"
 criterion = { version = "0.5.1", features = ["html_reports"] }
 crossterm = { version = "0.28.1", features = ["event-stream"] }
-derive_builder = "0.20.0"
 fakeit = "1.1"
 font8x8 = "0.3.1"
 futures = "0.3.30"
@@ -156,18 +155,25 @@ underline-color = ["dep:crossterm"]
 #! The following features are unstable and may change in the future:
 
 ## Enable all unstable features.
-unstable = ["unstable-rendered-line-info", "unstable-widget-ref"]
+unstable = [
+  "unstable-rendered-line-info",
+  "unstable-widget-ref",
+  "unstable-backend-writer",
+]
 
 ## 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.
+## See [Issue 293](https://github.com/ratatui/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 = []
 
+## Enables getting access to backends' writers.
+unstable-backend-writer = []
+
 [package.metadata.docs.rs]
 all-features = true
 # see https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html
@@ -294,7 +300,7 @@ doc-scrape-examples = true
 
 [[example]]
 name = "hyperlink"
-required-features = ["crossterm", "unstable-widget-ref"]
+required-features = ["crossterm"]
 doc-scrape-examples = true
 
 [[example]]
@@ -364,6 +370,11 @@ name = "user_input"
 required-features = ["crossterm"]
 doc-scrape-examples = true
 
+[[example]]
+name = "widget_impl"
+required-features = ["crossterm", "unstable-widget-ref"]
+doc-scrape-examples = true
+
 [[test]]
 name = "state_serde"
 required-features = ["serde"]

MAINTAINERS.md

@@ -6,10 +6,10 @@ This file documents current and past maintainers.
 - [joshka](https://github.com/joshka)
 - [kdheepak](https://github.com/kdheepak)
 - [Valentin271](https://github.com/Valentin271)
-- [EdJoPaTo](https://github.com/EdJoPaTo)
 
 ## Past Maintainers
 
 - [fdehau](https://github.com/fdehau)
 - [mindoodoo](https://github.com/mindoodoo)
 - [sayanarijit](https://github.com/sayanarijit)
+- [EdJoPaTo](https://github.com/EdJoPaTo)

Makefile.toml

@@ -5,14 +5,7 @@ skip_core_tasks = true
 
 [env]
 # 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.
-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" }
+NON_BACKEND_FEATURES = "all-widgets,macros,serde"
 
 [tasks.default]
 alias = "ci"
@@ -23,7 +16,7 @@ dependencies = ["lint", "clippy", "check", "test"]
 
 [tasks.lint]
 description = "Lint code style (formatting, typos, docs, markdown)"
-dependencies = ["lint-format", "lint-typos", "lint-docs", "lint-markdown"]
+dependencies = ["lint-format", "lint-typos", "lint-docs"]
 
 [tasks.lint-format]
 description = "Lint code formatting"
@@ -48,8 +41,7 @@ toolchain = "nightly"
 command = "cargo"
 args = [
   "rustdoc",
-  "--no-default-features",
-  "${ALL_FEATURES_FLAG}",
+  "--all-features",
   "--",
   "-Zunstable-options",
   "--check",
@@ -64,22 +56,12 @@ args = ["**/*.md", "!target"]
 [tasks.check]
 description = "Check code for errors and warnings"
 command = "cargo"
-args = [
-  "check",
-  "--all-targets",
-  "--no-default-features",
-  "${ALL_FEATURES_FLAG}",
-]
+args = ["check", "--all-targets", "--all-features"]
 
 [tasks.build]
 description = "Compile the project"
 command = "cargo"
-args = [
-  "build",
-  "--all-targets",
-  "--no-default-features",
-  "${ALL_FEATURES_FLAG}",
-]
+args = ["build", "--all-targets", "--all-features"]
 
 [tasks.clippy]
 description = "Run Clippy for linting"
@@ -87,10 +69,9 @@ command = "cargo"
 args = [
   "clippy",
   "--all-targets",
+  "--all-features",
   "--tests",
   "--benches",
-  "--no-default-features",
-  "${ALL_FEATURES_FLAG}",
   "--",
   "-D",
   "warnings",
@@ -108,18 +89,12 @@ run_task = { name = ["test-lib", "test-doc"] }
 description = "Run default tests"
 dependencies = ["install-nextest"]
 command = "cargo"
-args = [
-  "nextest",
-  "run",
-  "--all-targets",
-  "--no-default-features",
-  "${ALL_FEATURES_FLAG}",
-]
+args = ["nextest", "run", "--all-targets", "--all-features"]
 
 [tasks.test-doc]
 description = "Run documentation tests"
 command = "cargo"
-args = ["test", "--doc", "--no-default-features", "${ALL_FEATURES_FLAG}"]
+args = ["test", "--doc", "--all-features"]
 
 [tasks.test-backend]
 # takes a command line parameter to specify the backend to test (e.g. "crossterm")
@@ -132,7 +107,7 @@ args = [
   "--all-targets",
   "--no-default-features",
   "--features",
-  "${ALL_FEATURES},${@}",
+  "${NON_BACKEND_FEATURES},${@}",
 ]
 
 [tasks.coverage]
@@ -143,8 +118,7 @@ args = [
   "--lcov",
   "--output-path",
   "target/lcov.info",
-  "--no-default-features",
-  "${ALL_FEATURES_FLAG}",
+  "--all-features",
 ]
 
 [tasks.run-example]

README.md

@@ -4,14 +4,18 @@
 - [Ratatui](#ratatui)
   - [Installation](#installation)
   - [Introduction](#introduction)
-  - [Other Documentation](#other-documentation)
+  - [Other documentation](#other-documentation)
   - [Quickstart](#quickstart)
+    - [Initialize and restore the terminal](#initialize-and-restore-the-terminal)
+    - [Drawing the UI](#drawing-the-ui)
+    - [Handling events](#handling-events)
+    - [Example](#example)
+  - [Layout](#layout)
+  - [Text and styling](#text-and-styling)
   - [Status of this fork](#status-of-this-fork)
-  - [Rust version requirements](#rust-version-requirements)
   - [Widgets](#widgets)
     - [Built in](#built-in)
-    - [Third\-party libraries, bootstrapping templates and
-      widgets](#third-party-libraries-bootstrapping-templates-and-widgets)
+    - [Third-party libraries, bootstrapping templates and widgets](#third-party-libraries-bootstrapping-templates-and-widgets)
   - [Apps](#apps)
   - [Alternatives](#alternatives)
   - [Acknowledgments](#acknowledgments)
@@ -21,7 +25,7 @@
 
 <!-- cargo-rdme start -->
 
-![Demo](https://github.com/ratatui-org/ratatui/blob/87ae72dbc756067c97f6400d3e2a58eeb383776e/examples/demo2-destroy.gif?raw=true)
+![Demo](https://github.com/ratatui/ratatui/blob/87ae72dbc756067c97f6400d3e2a58eeb383776e/examples/demo2-destroy.gif?raw=true)
 
 <div align="center">
 
@@ -170,7 +174,7 @@ fn handle_events() -> io::Result<bool> {
 fn ui(frame: &mut Frame) {
     frame.render_widget(
         Paragraph::new("Hello World!").block(Block::bordered().title("Greeting")),
-        frame.size(),
+        frame.area(),
     );
 }
 ```
@@ -199,7 +203,7 @@ fn ui(frame: &mut Frame) {
         Constraint::Min(0),
         Constraint::Length(1),
     ])
-    .areas(frame.size());
+    .areas(frame.area());
     let [left_area, right_area] =
         Layout::horizontal([Constraint::Percentage(50), Constraint::Percentage(50)])
             .areas(main_area);
@@ -237,7 +241,7 @@ use ratatui::{
 };
 
 fn ui(frame: &mut Frame) {
-    let areas = Layout::vertical([Constraint::Length(1); 4]).split(frame.size());
+    let areas = Layout::vertical([Constraint::Length(1); 4]).split(frame.area());
 
     let line = Line::from(vec![
         Span::raw("Hello "),
@@ -280,21 +284,21 @@ Running this example produces the following output:
 [Handling Events]: https://ratatui.rs/concepts/event-handling/
 [Layout]: https://ratatui.rs/how-to/layout/
 [Styling Text]: https://ratatui.rs/how-to/render/style-text/
-[templates]: https://github.com/ratatui-org/templates/
-[Examples]: https://github.com/ratatui-org/ratatui/tree/main/examples/README.md
-[Report a bug]: https://github.com/ratatui-org/ratatui/issues/new?labels=bug&projects=&template=bug_report.md
-[Request a Feature]: https://github.com/ratatui-org/ratatui/issues/new?labels=enhancement&projects=&template=feature_request.md
-[Create a Pull Request]: https://github.com/ratatui-org/ratatui/compare
+[templates]: https://github.com/ratatui/templates/
+[Examples]: https://github.com/ratatui/ratatui/tree/main/examples/README.md
+[Report a bug]: https://github.com/ratatui/ratatui/issues/new?labels=bug&projects=&template=bug_report.md
+[Request a Feature]: https://github.com/ratatui/ratatui/issues/new?labels=enhancement&projects=&template=feature_request.md
+[Create a Pull Request]: https://github.com/ratatui/ratatui/compare
 [git-cliff]: https://git-cliff.org
 [Conventional Commits]: https://www.conventionalcommits.org
 [API Docs]: https://docs.rs/ratatui
-[Changelog]: https://github.com/ratatui-org/ratatui/blob/main/CHANGELOG.md
-[Contributing]: https://github.com/ratatui-org/ratatui/blob/main/CONTRIBUTING.md
-[Breaking Changes]: https://github.com/ratatui-org/ratatui/blob/main/BREAKING-CHANGES.md
+[Changelog]: https://github.com/ratatui/ratatui/blob/main/CHANGELOG.md
+[Contributing]: https://github.com/ratatui/ratatui/blob/main/CONTRIBUTING.md
+[Breaking Changes]: https://github.com/ratatui/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
+[docsrs-hello]: https://github.com/ratatui/ratatui/blob/c3c3c289b1eb8d562afb1931adb4dc719cd48490/examples/docsrs-hello.png?raw=true
+[docsrs-layout]: https://github.com/ratatui/ratatui/blob/c3c3c289b1eb8d562afb1931adb4dc719cd48490/examples/docsrs-layout.png?raw=true
+[docsrs-styling]: https://github.com/ratatui/ratatui/blob/c3c3c289b1eb8d562afb1931adb4dc719cd48490/examples/docsrs-styling.png?raw=true
 [`Frame`]: terminal::Frame
 [`render_widget`]: terminal::Frame::render_widget
 [`Widget`]: widgets::Widget
@@ -313,15 +317,15 @@ 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
-[GitHub Sponsors]: https://github.com/sponsors/ratatui-org
+[GitHub Sponsors]: https://github.com/sponsors/ratatui
 [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&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
+[CI Badge]: https://img.shields.io/github/actions/workflow/status/ratatui/ratatui/ci.yml?style=flat-square&logo=github
+[CI Workflow]: https://github.com/ratatui/ratatui/actions/workflows/ci.yml
+[Codecov Badge]: https://img.shields.io/codecov/c/github/ratatui/ratatui?logo=codecov&style=flat-square&token=BAQ8SOKEST&color=C43AC3&logoColor=C43AC3
+[Codecov]: https://app.codecov.io/gh/ratatui/ratatui
+[Deps.rs Badge]: https://deps.rs/repo/github/ratatui/ratatui/status.svg?style=flat-square
+[Deps.rs]: https://deps.rs/repo/github/ratatui/ratatui
 [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&logoColor=E05D44
@@ -329,7 +333,7 @@ Running this example produces the following output:
 [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
+[Sponsors Badge]: https://img.shields.io/github/sponsors/ratatui?logo=github&style=flat-square&color=1370D3
 
 <!-- cargo-rdme end -->
 
@@ -387,7 +391,7 @@ be installed with `cargo install cargo-make`).
   `ratatui::text::Text`
 - [color-to-tui](https://github.com/uttarayan21/color-to-tui) — Parse hex colors to
   `ratatui::style::Color`
-- [templates](https://github.com/ratatui-org/templates) — Starter templates for
+- [templates](https://github.com/ratatui/templates) — Starter templates for
   bootstrapping a Rust TUI application with Ratatui & crossterm
 - [tui-builder](https://github.com/jkelleyrtp/tui-builder) — Batteries-included MVC framework for
   Tui-rs + Crossterm apps
@@ -411,7 +415,7 @@ be installed with `cargo install cargo-make`).
 
 ## Apps
 
-Check out [awesome-ratatui](https://github.com/ratatui-org/awesome-ratatui) for a curated list of
+Check out [awesome-ratatui](https://github.com/ratatui/awesome-ratatui) for a curated list of
 awesome apps/libraries built with `ratatui`!
 
 ## Alternatives
@@ -422,7 +426,7 @@ to build text user interfaces in Rust.
 ## Acknowledgments
 
 Special thanks to [**Pavel Fomchenkov**](https://github.com/nawok) for his work in designing **an
-awesome logo** for the ratatui project and ratatui-org organization.
+awesome logo** for the ratatui project and ratatui organization.
 
 ## License
 

RELEASE.md

@@ -1,5 +1,12 @@
 # Creating a Release
 
+Our release strategy is:
+
+> Release major versions with detailed summaries when necessary, while releasing minor versions
+> weekly or as needed without extensive announcements.
+>
+> Versioning scheme being `0.x.y`, where `x` is the major version and `y` is the minor version.
+
 [crates.io](https://crates.io/crates/ratatui) releases are automated via [GitHub
 actions](.github/workflows/cd.yml) and triggered by pushing a tag.
 
@@ -12,7 +19,7 @@ actions](.github/workflows/cd.yml) and triggered by pushing a tag.
    ```
 
 1. Switch branches to the images branch and copy demo2.gif to examples/, commit, and push.
-1. Grab the permalink from <https://github.com/ratatui-org/ratatui/blob/images/examples/demo2.gif> and
+1. Grab the permalink from <https://github.com/ratatui/ratatui/blob/images/examples/demo2.gif> and
    append `?raw=true` to redirect to the actual image url. Then update the link in the main README.
    Avoid adding the gif to the git repo as binary files tend to bloat repositories.
 
@@ -21,16 +28,16 @@ actions](.github/workflows/cd.yml) and triggered by pushing a tag.
    can be used for generating the entries.
 1. Ensure that any breaking changes are documented in [BREAKING-CHANGES.md](./BREAKING-CHANGES.md)
 1. Commit and push the changes.
-1. Create a new tag: `git tag -a v[X.Y.Z]`
+1. Create a new tag: `git tag -a v[0.x.y]`
 1. Push the tag: `git push --tags`
-1. Wait for [Continuous Deployment](https://github.com/ratatui-org/ratatui/actions) workflow to
+1. Wait for [Continuous Deployment](https://github.com/ratatui/ratatui/actions) workflow to
    finish.
 
 ## Alpha Releases
 
 Alpha releases are automatically released every Saturday via [cd.yml](./.github/workflows/cd.yml)
 and can be manually be created when necessary by triggering the [Continuous
-Deployment](https://github.com/ratatui-org/ratatui/actions/workflows/cd.yml) workflow.
+Deployment](https://github.com/ratatui/ratatui/actions/workflows/cd.yml) workflow.
 
 We automatically release an alpha release with a patch level bump + alpha.num weekly (and when we
 need to manually). E.g. the last release was 0.22.0, and the most recent alpha release is
@@ -40,5 +47,5 @@ These releases will have whatever happened to be in main at the time of release,
 for apps that need to get releases from crates.io, but may contain more bugs and be generally less
 tested than normal releases.
 
-See [#147](https://github.com/ratatui-org/ratatui/issues/147) and
-[#359](https://github.com/ratatui-org/ratatui/pull/359) for more info on the alpha release process.
+See [#147](https://github.com/ratatui/ratatui/issues/147) and
+[#359](https://github.com/ratatui/ratatui/pull/359) for more info on the alpha release process.

SECURITY.md

@@ -6,4 +6,4 @@ We only support the latest version of this crate.
 
 ## Reporting a Vulnerability
 
-To report secuirity vulnerability, please use the form at <https://github.com/ratatui-org/ratatui/security/advisories/new>
+To report secuirity vulnerability, please use the form at <https://github.com/ratatui/ratatui/security/advisories/new>

benches/main/barchart.rs

@@ -59,7 +59,7 @@ fn barchart(c: &mut Criterion) {
 fn render(bencher: &mut Bencher, barchart: &BarChart) {
     let mut buffer = Buffer::empty(Rect::new(0, 0, 200, 50));
     // We use `iter_batched` to clone the value in the setup function.
-    // See https://github.com/ratatui-org/ratatui/pull/377.
+    // See https://github.com/ratatui/ratatui/pull/377.
     bencher.iter_batched(
         || barchart.clone(),
         |bench_barchart| {

benches/main/block.rs

@@ -48,7 +48,7 @@ fn block(c: &mut Criterion) {
 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.
+    // See https://github.com/ratatui/ratatui/pull/377.
     bencher.iter_batched(
         || block.to_owned(),
         |bench_block| {

benches/main/list.rs

@@ -45,7 +45,7 @@ fn list(c: &mut Criterion) {
 fn render(bencher: &mut Bencher, list: &List) {
     let mut buffer = Buffer::empty(Rect::new(0, 0, 200, 50));
     // We use `iter_batched` to clone the value in the setup function.
-    // See https://github.com/ratatui-org/ratatui/pull/377.
+    // See https://github.com/ratatui/ratatui/pull/377.
     bencher.iter_batched(
         || list.to_owned(),
         |bench_list| {
@@ -59,7 +59,7 @@ fn render(bencher: &mut Bencher, list: &List) {
 fn render_stateful(bencher: &mut Bencher, list: &List, mut state: ListState) {
     let mut buffer = Buffer::empty(Rect::new(0, 0, 200, 50));
     // We use `iter_batched` to clone the value in the setup function.
-    // See https://github.com/ratatui-org/ratatui/pull/377.
+    // See https://github.com/ratatui/ratatui/pull/377.
     bencher.iter_batched(
         || list.to_owned(),
         |bench_list| {

benches/main/paragraph.rs

@@ -70,7 +70,7 @@ fn paragraph(c: &mut Criterion) {
 fn render(bencher: &mut Bencher, paragraph: &Paragraph, width: u16) {
     let mut buffer = Buffer::empty(Rect::new(0, 0, width, 50));
     // We use `iter_batched` to clone the value in the setup function.
-    // See https://github.com/ratatui-org/ratatui/pull/377.
+    // See https://github.com/ratatui/ratatui/pull/377.
     bencher.iter_batched(
         || paragraph.to_owned(),
         |bench_paragraph| {

benches/main/sparkline.rs

@@ -31,7 +31,7 @@ fn sparkline(c: &mut Criterion) {
 fn render(bencher: &mut Bencher, sparkline: &Sparkline) {
     let mut buffer = Buffer::empty(Rect::new(0, 0, 200, 50));
     // We use `iter_batched` to clone the value in the setup function.
-    // See https://github.com/ratatui-org/ratatui/pull/377.
+    // See https://github.com/ratatui/ratatui/pull/377.
     bencher.iter_batched(
         || sparkline.clone(),
         |bench_sparkline| {

cliff.toml

@@ -2,7 +2,7 @@
 # https://git-cliff.org/docs/configuration
 
 [remote.github]
-owner = "ratatui-org"
+owner = "ratatui"
 repo = "ratatui"
 
 [changelog]
@@ -24,11 +24,11 @@ body = """
 {%- if not version %}
 ## [unreleased]
 {% else -%}
-## [{{ version }}](https://github.com/ratatui-org/ratatui/releases/tag/{{ version }}) - {{ timestamp | date(format="%Y-%m-%d") }}
+## [{{ version }}](https://github.com/ratatui/ratatui/releases/tag/{{ version }}) - {{ timestamp | date(format="%Y-%m-%d") }}
 {% endif -%}
 
 {% macro commit(commit) -%}
-- [{{ commit.id | truncate(length=7, end="") }}]({{ "https://github.com/ratatui-org/ratatui/commit/" ~ commit.id }}) \
+- [{{ commit.id | truncate(length=7, end="") }}]({{ "https://github.com/ratatui/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 %}\

clippy.toml

@@ -3,7 +3,7 @@ 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
+# crossterm -> all the windows- deps https://github.com/ratatui/ratatui/pull/1064#issuecomment-2078848980
 allowed-duplicate-crates = [
     "bitflags",
     "windows-targets",

examples/README.md

@@ -10,13 +10,13 @@ This folder might use unreleased code. View the examples for the latest release
 > 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.26.1/examples>.
+>   matches that version. E.g. <https://github.com/ratatui/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"`
+>   the dependency, or remotely by adding `git = "https://github.com/ratatui/ratatui"`
 >
 > For a list of unreleased breaking changes, see [BREAKING-CHANGES.md].
 >
@@ -170,7 +170,7 @@ cargo run --example=colors_rgb --features=crossterm
 Note: VHs renders full screen animations poorly, so this is a screen capture rather than the output
 of the VHS tape.
 
-<https://github.com/ratatui-org/ratatui/assets/381361/485e775a-e0b5-4133-899b-1e8aeb56e774>
+<https://github.com/ratatui/ratatui/assets/381361/485e775a-e0b5-4133-899b-1e8aeb56e774>
 
 ## Constraint Explorer
 
@@ -441,38 +441,38 @@ examples/vhs/generate.bash
 ```
 -->
 
-[barchart.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/barchart.gif?raw=true
-[barchart-grouped.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/barchart-grouped.gif?raw=true
-[block.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/block.gif?raw=true
-[calendar.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/calendar.gif?raw=true
-[canvas.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/canvas.gif?raw=true
-[chart.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/chart.gif?raw=true
-[colors.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/colors.gif?raw=true
-[constraint-explorer.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/constraint-explorer.gif?raw=true
-[constraints.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/constraints.gif?raw=true
-[custom_widget.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/custom_widget.gif?raw=true
-[demo.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/demo.gif?raw=true
-[demo2.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/demo2.gif?raw=true
-[flex.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/flex.gif?raw=true
-[gauge.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/gauge.gif?raw=true
-[hello_world.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/hello_world.gif?raw=true
-[hyperlink.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/hyperlink.gif?raw=true
-[inline.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/inline.gif?raw=true
-[layout.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/layout.gif?raw=true
-[list.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/list.gif?raw=true
-[line_gauge.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/line_gauge.gif?raw=true
-[minimal.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/minimal.gif?raw=true
-[modifiers.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/modifiers.gif?raw=true
-[panic.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/panic.gif?raw=true
-[paragraph.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/paragraph.gif?raw=true
-[popup.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/popup.gif?raw=true
-[ratatui-logo.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/ratatui-logo.gif?raw=true
-[scrollbar.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/scrollbar.gif?raw=true
-[sparkline.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/sparkline.gif?raw=true
+[barchart.gif]: https://github.com/ratatui/ratatui/blob/images/examples/barchart.gif?raw=true
+[barchart-grouped.gif]: https://github.com/ratatui/ratatui/blob/images/examples/barchart-grouped.gif?raw=true
+[block.gif]: https://github.com/ratatui/ratatui/blob/images/examples/block.gif?raw=true
+[calendar.gif]: https://github.com/ratatui/ratatui/blob/images/examples/calendar.gif?raw=true
+[canvas.gif]: https://github.com/ratatui/ratatui/blob/images/examples/canvas.gif?raw=true
+[chart.gif]: https://github.com/ratatui/ratatui/blob/images/examples/chart.gif?raw=true
+[colors.gif]: https://github.com/ratatui/ratatui/blob/images/examples/colors.gif?raw=true
+[constraint-explorer.gif]: https://github.com/ratatui/ratatui/blob/images/examples/constraint-explorer.gif?raw=true
+[constraints.gif]: https://github.com/ratatui/ratatui/blob/images/examples/constraints.gif?raw=true
+[custom_widget.gif]: https://github.com/ratatui/ratatui/blob/images/examples/custom_widget.gif?raw=true
+[demo.gif]: https://github.com/ratatui/ratatui/blob/images/examples/demo.gif?raw=true
+[demo2.gif]: https://github.com/ratatui/ratatui/blob/images/examples/demo2.gif?raw=true
+[flex.gif]: https://github.com/ratatui/ratatui/blob/images/examples/flex.gif?raw=true
+[gauge.gif]: https://github.com/ratatui/ratatui/blob/images/examples/gauge.gif?raw=true
+[hello_world.gif]: https://github.com/ratatui/ratatui/blob/images/examples/hello_world.gif?raw=true
+[hyperlink.gif]: https://github.com/ratatui/ratatui/blob/images/examples/hyperlink.gif?raw=true
+[inline.gif]: https://github.com/ratatui/ratatui/blob/images/examples/inline.gif?raw=true
+[layout.gif]: https://github.com/ratatui/ratatui/blob/images/examples/layout.gif?raw=true
+[list.gif]: https://github.com/ratatui/ratatui/blob/images/examples/list.gif?raw=true
+[line_gauge.gif]: https://github.com/ratatui/ratatui/blob/images/examples/line_gauge.gif?raw=true
+[minimal.gif]: https://github.com/ratatui/ratatui/blob/images/examples/minimal.gif?raw=true
+[modifiers.gif]: https://github.com/ratatui/ratatui/blob/images/examples/modifiers.gif?raw=true
+[panic.gif]: https://github.com/ratatui/ratatui/blob/images/examples/panic.gif?raw=true
+[paragraph.gif]: https://github.com/ratatui/ratatui/blob/images/examples/paragraph.gif?raw=true
+[popup.gif]: https://github.com/ratatui/ratatui/blob/images/examples/popup.gif?raw=true
+[ratatui-logo.gif]: https://github.com/ratatui/ratatui/blob/images/examples/ratatui-logo.gif?raw=true
+[scrollbar.gif]: https://github.com/ratatui/ratatui/blob/images/examples/scrollbar.gif?raw=true
+[sparkline.gif]: https://github.com/ratatui/ratatui/blob/images/examples/sparkline.gif?raw=true
 [table.gif]:  https://vhs.charm.sh/vhs-6njXBytDf0rwPufUtmSSpI.gif
-[tabs.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/tabs.gif?raw=true
-[tracing.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/tracing.gif?raw=true
-[user_input.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/user_input.gif?raw=true
+[tabs.gif]: https://github.com/ratatui/ratatui/blob/images/examples/tabs.gif?raw=true
+[tracing.gif]: https://github.com/ratatui/ratatui/blob/images/examples/tracing.gif?raw=true
+[user_input.gif]: https://github.com/ratatui/ratatui/blob/images/examples/user_input.gif?raw=true
 
 [alpha version of Ratatui]: https://crates.io/crates/ratatui/versions
-[BREAKING-CHANGES.md]: https://github.com/ratatui-org/ratatui/blob/main/BREAKING-CHANGES.md
+[BREAKING-CHANGES.md]: https://github.com/ratatui/ratatui/blob/main/BREAKING-CHANGES.md

examples/async.rs

@@ -26,9 +26,9 @@
 //! 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
+//! [Ratatui]: https://github.com/ratatui/ratatui
+//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md
 use std::{
     sync::{Arc, RwLock},
     time::Duration,
@@ -41,23 +41,22 @@ use octocrab::{
     OctocrabBuilder, Page,
 };
 use ratatui::{
-    crossterm::event::{Event, EventStream, KeyCode},
-    layout::Offset,
-    prelude::{Buffer, Constraint, Line, Modifier, Rect, Stylize},
-    widgets::{
-        Block, BorderType, HighlightSpacing, Row, StatefulWidget, Table, TableState, Widget,
-    },
+    buffer::Buffer,
+    crossterm::event::{Event, EventStream, KeyCode, KeyEventKind},
+    layout::{Constraint, Layout, Rect},
+    style::{Style, Stylize},
+    text::Line,
+    widgets::{Block, HighlightSpacing, Row, StatefulWidget, Table, TableState, Widget},
+    DefaultTerminal, Frame,
 };
 
-use self::terminal::Terminal;
-
 #[tokio::main]
 async fn main() -> Result<()> {
     color_eyre::install()?;
     init_octocrab()?;
-    let terminal = terminal::init()?;
+    let terminal = ratatui::init();
     let app_result = App::default().run(terminal).await;
-    terminal::restore();
+    ratatui::restore();
     app_result
 }
 
@@ -76,48 +75,45 @@ fn init_octocrab() -> Result<()> {
 #[derive(Debug, Default)]
 struct App {
     should_quit: bool,
-    pulls: PullRequestsWidget,
+    pull_requests: PullRequestListWidget,
 }
 
 impl App {
     const FRAMES_PER_SECOND: f32 = 60.0;
 
-    pub async fn run(mut self, mut terminal: Terminal) -> Result<()> {
-        self.pulls.run();
+    pub async fn run(mut self, mut terminal: DefaultTerminal) -> Result<()> {
+        self.pull_requests.run();
 
-        let mut interval =
-            tokio::time::interval(Duration::from_secs_f32(1.0 / Self::FRAMES_PER_SECOND));
+        let period = Duration::from_secs_f32(1.0 / Self::FRAMES_PER_SECOND);
+        let mut interval = tokio::time::interval(period);
         let mut events = EventStream::new();
 
         while !self.should_quit {
             tokio::select! {
-                _ = interval.tick() => self.draw(&mut terminal)?,
-                Some(Ok(event)) = events.next() =>  self.handle_event(&event),
+                _ = interval.tick() => { terminal.draw(|frame| self.draw(frame))?; },
+                Some(Ok(event)) = events.next() => self.handle_event(&event),
             }
         }
         Ok(())
     }
 
-    fn draw(&self, terminal: &mut Terminal) -> Result<()> {
-        terminal.draw(|frame| {
-            let area = frame.area();
-            frame.render_widget(
-                Line::from("ratatui async example").centered().cyan().bold(),
-                area,
-            );
-            let area = area.offset(Offset { x: 0, y: 1 }).intersection(area);
-            frame.render_widget(&self.pulls, area);
-        })?;
-        Ok(())
+    fn draw(&self, frame: &mut Frame) {
+        let vertical = Layout::vertical([Constraint::Length(1), Constraint::Fill(1)]);
+        let [title_area, body_area] = vertical.areas(frame.area());
+        let title = Line::from("Ratatui async example").centered().bold();
+        frame.render_widget(title, title_area);
+        frame.render_widget(&self.pull_requests, body_area);
     }
 
     fn handle_event(&mut self, event: &Event) {
-        if let Event::Key(event) = event {
-            match event.code {
-                KeyCode::Char('q') => self.should_quit = true,
-                KeyCode::Char('j') => self.pulls.scroll_down(),
-                KeyCode::Char('k') => self.pulls.scroll_up(),
-                _ => {}
+        if let Event::Key(key) = event {
+            if key.kind == KeyEventKind::Press {
+                match key.code {
+                    KeyCode::Char('q') | KeyCode::Esc => self.should_quit = true,
+                    KeyCode::Char('j') | KeyCode::Down => self.pull_requests.scroll_down(),
+                    KeyCode::Char('k') | KeyCode::Up => self.pull_requests.scroll_up(),
+                    _ => {}
+                }
             }
         }
     }
@@ -126,19 +122,19 @@ impl App {
 /// A widget that displays a list of pull requests.
 ///
 /// This is an async widget that fetches the list of pull requests from the GitHub API. It contains
-/// an inner `Arc<RwLock<PullRequests>>` that holds the state of the widget. Cloning the widget
-/// will clone the Arc, so you can pass it around to other threads, and this is used to spawn a
-/// background task to fetch the pull requests.
+/// an inner `Arc<RwLock<PullRequestListState>>` that holds the state of the widget. Cloning the
+/// widget will clone the Arc, so you can pass it around to other threads, and this is used to spawn
+/// a background task to fetch the pull requests.
 #[derive(Debug, Clone, Default)]
-struct PullRequestsWidget {
-    inner: Arc<RwLock<PullRequests>>,
-    selected_index: usize, // no need to lock this since it's only accessed by the main thread
+struct PullRequestListWidget {
+    state: Arc<RwLock<PullRequestListState>>,
 }
 
 #[derive(Debug, Default)]
-struct PullRequests {
-    pulls: Vec<PullRequest>,
+struct PullRequestListState {
+    pull_requests: Vec<PullRequest>,
     loading_state: LoadingState,
+    table_state: TableState,
 }
 
 #[derive(Debug, Clone)]
@@ -157,7 +153,7 @@ enum LoadingState {
     Error(String),
 }
 
-impl PullRequestsWidget {
+impl PullRequestListWidget {
     /// Start fetching the pull requests in the background.
     ///
     /// This method spawns a background task that fetches the pull requests from the GitHub API.
@@ -172,7 +168,7 @@ impl PullRequestsWidget {
         // messages to refresh on demand, or with an interval timer to refresh every N seconds
         self.set_loading_state(LoadingState::Loading);
         match octocrab::instance()
-            .pulls("ratatui-org", "ratatui")
+            .pulls("ratatui", "ratatui")
             .list()
             .sort(Sort::Updated)
             .direction(Direction::Descending)
@@ -185,9 +181,12 @@ impl PullRequestsWidget {
     }
     fn on_load(&self, page: &Page<OctoPullRequest>) {
         let prs = page.items.iter().map(Into::into);
-        let mut inner = self.inner.write().unwrap();
-        inner.loading_state = LoadingState::Loaded;
-        inner.pulls.extend(prs);
+        let mut state = self.state.write().unwrap();
+        state.loading_state = LoadingState::Loaded;
+        state.pull_requests.extend(prs);
+        if !state.pull_requests.is_empty() {
+            state.table_state.select(Some(0));
+        }
     }
 
     fn on_err(&self, err: &octocrab::Error) {
@@ -195,15 +194,15 @@ impl PullRequestsWidget {
     }
 
     fn set_loading_state(&self, state: LoadingState) {
-        self.inner.write().unwrap().loading_state = state;
+        self.state.write().unwrap().loading_state = state;
     }
 
-    fn scroll_down(&mut self) {
-        self.selected_index = self.selected_index.saturating_add(1);
+    fn scroll_down(&self) {
+        self.state.write().unwrap().table_state.scroll_down_by(1);
     }
 
-    fn scroll_up(&mut self) {
-        self.selected_index = self.selected_index.saturating_sub(1);
+    fn scroll_up(&self) {
+        self.state.write().unwrap().table_state.scroll_up_by(1);
     }
 }
 
@@ -223,19 +222,19 @@ impl From<&OctoPullRequest> for PullRequest {
     }
 }
 
-impl Widget for &PullRequestsWidget {
+impl Widget for &PullRequestListWidget {
     fn render(self, area: Rect, buf: &mut Buffer) {
-        let inner = self.inner.read().unwrap();
+        let mut state = self.state.write().unwrap();
 
-        // a block with a right aligned title with the loading state
-        let loading_state = Line::from(format!("{:?}", inner.loading_state)).right_aligned();
+        // a block with a right aligned title with the loading state on the right
+        let loading_state = Line::from(format!("{:?}", state.loading_state)).right_aligned();
         let block = Block::bordered()
-            .border_type(BorderType::Rounded)
             .title("Pull Requests")
-            .title(loading_state);
+            .title(loading_state)
+            .title_bottom("j/k to scroll, q to quit");
 
         // a table with the list of pull requests
-        let rows = inner.pulls.iter();
+        let rows = state.pull_requests.iter();
         let widths = [
             Constraint::Length(5),
             Constraint::Fill(1),
@@ -245,10 +244,9 @@ impl Widget for &PullRequestsWidget {
             .block(block)
             .highlight_spacing(HighlightSpacing::Always)
             .highlight_symbol(">>")
-            .highlight_style(Modifier::REVERSED);
-        let mut table_state = TableState::new().with_selected(self.selected_index);
+            .highlight_style(Style::new().on_blue());
 
-        StatefulWidget::render(table, area, buf, &mut table_state);
+        StatefulWidget::render(table, area, buf, &mut state.table_state);
     }
 }
 
@@ -258,42 +256,3 @@ impl From<&PullRequest> for Row<'_> {
         Row::new(vec![pr.id, pr.title, pr.url])
     }
 }
-
-mod terminal {
-    use std::io;
-
-    use crossterm::{
-        execute,
-        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-    };
-    use ratatui::prelude::{CrosstermBackend, Terminal as RatatuiTerminal};
-
-    /// A type alias for the terminal type used in this example.
-    pub type Terminal = RatatuiTerminal<CrosstermBackend<io::Stdout>>;
-
-    pub fn init() -> io::Result<Terminal> {
-        set_panic_hook();
-        enable_raw_mode()?;
-        execute!(io::stdout(), EnterAlternateScreen)?;
-        let backend = CrosstermBackend::new(io::stdout());
-        Terminal::new(backend)
-    }
-
-    fn set_panic_hook() {
-        let hook = std::panic::take_hook();
-        std::panic::set_hook(Box::new(move |info| {
-            restore();
-            hook(info);
-        }));
-    }
-
-    /// Restores the terminal to its original state.
-    pub fn restore() {
-        if let Err(err) = disable_raw_mode() {
-            eprintln!("error disabling raw mode: {err}");
-        }
-        if let Err(err) = execute!(io::stdout(), LeaveAlternateScreen) {
-            eprintln!("error leaving alternate screen: {err}");
-        }
-    }
-}

examples/barchart-grouped.rs

@@ -9,21 +9,29 @@
 //! 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
+//! [Ratatui]: https://github.com/ratatui/ratatui
+//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md
 
 use std::iter::zip;
 
 use color_eyre::Result;
 use ratatui::{
-    crossterm::event::{self, Event, KeyCode},
-    prelude::{Color, Constraint, Direction, Frame, Layout, Line, Style},
-    style::Stylize,
+    crossterm::event::{self, Event, KeyCode, KeyEventKind},
+    layout::{Constraint, Direction, Layout},
+    style::{Color, Style, Stylize},
+    text::Line,
     widgets::{Bar, BarChart, BarGroup, Block},
+    DefaultTerminal, Frame,
 };
 
-use self::terminal::Terminal;
+fn main() -> Result<()> {
+    color_eyre::install()?;
+    let terminal = ratatui::init();
+    let app_result = App::new().run(terminal);
+    ratatui::restore();
+    app_result
+}
 
 const COMPANY_COUNT: usize = 3;
 const PERIOD_COUNT: usize = 4;
@@ -45,15 +53,6 @@ struct Company {
     color: Color,
 }
 
-fn main() -> Result<()> {
-    color_eyre::install()?;
-    let mut terminal = terminal::init()?;
-    let app = App::new();
-    app.run(&mut terminal)?;
-    terminal::restore()?;
-    Ok(())
-}
-
 impl App {
     const fn new() -> Self {
         Self {
@@ -63,33 +62,27 @@ impl App {
         }
     }
 
-    fn run(mut self, terminal: &mut Terminal) -> Result<()> {
+    fn run(mut self, mut terminal: DefaultTerminal) -> Result<()> {
         while !self.should_exit {
-            self.draw(terminal)?;
+            terminal.draw(|frame| self.draw(frame))?;
             self.handle_events()?;
         }
         Ok(())
     }
 
-    fn draw(&self, terminal: &mut Terminal) -> Result<()> {
-        terminal.draw(|frame| self.render(frame))?;
-        Ok(())
-    }
-
     fn handle_events(&mut self) -> Result<()> {
         if let Event::Key(key) = event::read()? {
-            if key.code == KeyCode::Char('q') {
+            if key.kind == KeyEventKind::Press && key.code == KeyCode::Char('q') {
                 self.should_exit = true;
             }
         }
         Ok(())
     }
 
-    fn render(&self, frame: &mut Frame) {
+    fn draw(&self, frame: &mut Frame) {
         use Constraint::{Fill, Length, Min};
-        let [title, top, bottom] = Layout::vertical([Length(1), Fill(1), Min(20)])
-            .spacing(1)
-            .areas(frame.area());
+        let vertical = Layout::vertical([Length(1), Fill(1), Min(20)]).spacing(1);
+        let [title, top, bottom] = vertical.areas(frame.area());
 
         frame.render_widget("Grouped Barchart".bold().into_centered_line(), title);
         frame.render_widget(self.vertical_revenue_barchart(), top);
@@ -98,12 +91,12 @@ impl App {
 
     /// Create a vertical revenue bar chart with the data from the `revenues` field.
     fn vertical_revenue_barchart(&self) -> BarChart<'_> {
-        let title = Line::from("Company revenues (Vertical)").centered();
         let mut barchart = BarChart::default()
-            .block(Block::new().title(title))
+            .block(Block::new().title(Line::from("Company revenues (Vertical)").centered()))
             .bar_gap(0)
             .bar_width(6)
             .group_gap(2);
+
         for group in self
             .revenues
             .iter()
@@ -216,63 +209,3 @@ impl Company {
             .value_style(Style::new().fg(Color::Black).bg(self.color))
     }
 }
-
-/// Contains functions common to all examples
-mod terminal {
-    use std::{
-        io::{self, stdout, Stdout},
-        panic,
-    };
-
-    use ratatui::{
-        backend::CrosstermBackend,
-        crossterm::{
-            execute,
-            terminal::{
-                disable_raw_mode, enable_raw_mode, Clear, ClearType, EnterAlternateScreen,
-                LeaveAlternateScreen,
-            },
-        },
-    };
-
-    // A type alias to simplify the usage of the terminal and make it easier to change the backend
-    // or choice of writer.
-    pub type Terminal = ratatui::Terminal<CrosstermBackend<Stdout>>;
-
-    /// Initialize the terminal by enabling raw mode and entering the alternate screen.
-    ///
-    /// This function should be called before the program starts to ensure that the terminal is in
-    /// the correct state for the application.
-    pub fn init() -> io::Result<Terminal> {
-        install_panic_hook();
-        enable_raw_mode()?;
-        execute!(stdout(), EnterAlternateScreen)?;
-        let backend = CrosstermBackend::new(stdout());
-        let terminal = Terminal::new(backend)?;
-        Ok(terminal)
-    }
-
-    /// Restore the terminal by leaving the alternate screen and disabling raw mode.
-    ///
-    /// This function should be called before the program exits to ensure that the terminal is
-    /// restored to its original state.
-    pub fn restore() -> io::Result<()> {
-        disable_raw_mode()?;
-        execute!(
-            stdout(),
-            LeaveAlternateScreen,
-            Clear(ClearType::FromCursorDown),
-        )
-    }
-
-    /// Install a panic hook that restores the terminal before printing the panic.
-    ///
-    /// This prevents error messages from being messed up by the terminal state.
-    fn install_panic_hook() {
-        let panic_hook = panic::take_hook();
-        panic::set_hook(Box::new(move |panic_info| {
-            let _ = restore();
-            panic_hook(panic_info);
-        }));
-    }
-}

examples/barchart.rs

@@ -9,35 +9,34 @@
 //! 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
+//! [Ratatui]: https://github.com/ratatui/ratatui
+//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md
 
 use color_eyre::Result;
 use rand::{thread_rng, Rng};
 use ratatui::{
-    crossterm::event::{self, Event, KeyCode},
+    crossterm::event::{self, Event, KeyCode, KeyEventKind},
     layout::{Constraint, Direction, Layout},
-    prelude::{Color, Line, Style, Stylize},
+    style::{Color, Style, Stylize},
+    text::Line,
     widgets::{Bar, BarChart, BarGroup, Block},
+    DefaultTerminal, Frame,
 };
 
-use self::terminal::Terminal;
+fn main() -> Result<()> {
+    color_eyre::install()?;
+    let terminal = ratatui::init();
+    let app_result = App::new().run(terminal);
+    ratatui::restore();
+    app_result
+}
 
 struct App {
     should_exit: bool,
     temperatures: Vec<u8>,
 }
 
-fn main() -> Result<()> {
-    color_eyre::install()?;
-    let mut terminal = terminal::init()?;
-    let app = App::new();
-    app.run(&mut terminal)?;
-    terminal::restore()?;
-    Ok(())
-}
-
 impl App {
     fn new() -> Self {
         let mut rng = thread_rng();
@@ -48,29 +47,24 @@ impl App {
         }
     }
 
-    fn run(mut self, terminal: &mut Terminal) -> Result<()> {
+    fn run(mut self, mut terminal: DefaultTerminal) -> Result<()> {
         while !self.should_exit {
-            self.draw(terminal)?;
+            terminal.draw(|frame| self.draw(frame))?;
             self.handle_events()?;
         }
         Ok(())
     }
 
-    fn draw(&self, terminal: &mut Terminal) -> Result<()> {
-        terminal.draw(|frame| self.render(frame))?;
-        Ok(())
-    }
-
     fn handle_events(&mut self) -> Result<()> {
         if let Event::Key(key) = event::read()? {
-            if key.code == KeyCode::Char('q') {
+            if key.kind == KeyEventKind::Press && key.code == KeyCode::Char('q') {
                 self.should_exit = true;
             }
         }
         Ok(())
     }
 
-    fn render(&self, frame: &mut ratatui::Frame) {
+    fn draw(&self, frame: &mut Frame) {
         let [title, vertical, horizontal] = Layout::vertical([
             Constraint::Length(1),
             Constraint::Fill(1),
@@ -78,6 +72,7 @@ impl App {
         ])
         .spacing(1)
         .areas(frame.area());
+
         frame.render_widget("Barchart".bold().into_centered_line(), title);
         frame.render_widget(vertical_barchart(&self.temperatures), vertical);
         frame.render_widget(horizontal_barchart(&self.temperatures), horizontal);
@@ -88,16 +83,8 @@ impl App {
 fn vertical_barchart(temperatures: &[u8]) -> BarChart {
     let bars: Vec<Bar> = temperatures
         .iter()
-        .map(|v| u64::from(*v))
         .enumerate()
-        .map(|(i, value)| {
-            Bar::default()
-                .value(value)
-                .label(Line::from(format!("{i:>02}:00")))
-                .text_value(format!("{value:>3}°"))
-                .style(temperature_style(value))
-                .value_style(temperature_style(value).reversed())
-        })
+        .map(|(hour, value)| vertical_bar(hour, value))
         .collect();
     let title = Line::from("Weather (Vertical)").centered();
     BarChart::default()
@@ -106,21 +93,21 @@ fn vertical_barchart(temperatures: &[u8]) -> BarChart {
         .bar_width(5)
 }
 
+fn vertical_bar(hour: usize, temperature: &u8) -> Bar {
+    Bar::default()
+        .value(u64::from(*temperature))
+        .label(Line::from(format!("{hour:>02}:00")))
+        .text_value(format!("{temperature:>3}°"))
+        .style(temperature_style(*temperature))
+        .value_style(temperature_style(*temperature).reversed())
+}
+
 /// Create a horizontal bar chart from the temperatures data.
 fn horizontal_barchart(temperatures: &[u8]) -> BarChart {
     let bars: Vec<Bar> = temperatures
         .iter()
-        .map(|v| u64::from(*v))
         .enumerate()
-        .map(|(i, value)| {
-            let style = temperature_style(value);
-            Bar::default()
-                .value(value)
-                .label(Line::from(format!("{i:>02}:00")))
-                .text_value(format!("{value:>3}°"))
-                .style(style)
-                .value_style(style.reversed())
-        })
+        .map(|(hour, value)| horizontal_bar(hour, value))
         .collect();
     let title = Line::from("Weather (Horizontal)").centered();
     BarChart::default()
@@ -131,69 +118,19 @@ fn horizontal_barchart(temperatures: &[u8]) -> BarChart {
         .direction(Direction::Horizontal)
 }
 
+fn horizontal_bar(hour: usize, temperature: &u8) -> Bar {
+    let style = temperature_style(*temperature);
+    Bar::default()
+        .value(u64::from(*temperature))
+        .label(Line::from(format!("{hour:>02}:00")))
+        .text_value(format!("{temperature:>3}°"))
+        .style(style)
+        .value_style(style.reversed())
+}
+
 /// create a yellow to red value based on the value (50-90)
-fn temperature_style(value: u64) -> Style {
-    let green = (255.0 * (1.0 - (value - 50) as f64 / 40.0)) as u8;
+fn temperature_style(value: u8) -> Style {
+    let green = (255.0 * (1.0 - f64::from(value - 50) / 40.0)) as u8;
     let color = Color::Rgb(255, green, 0);
     Style::new().fg(color)
 }
-
-/// Contains functions common to all examples
-mod terminal {
-    use std::{
-        io::{self, stdout, Stdout},
-        panic,
-    };
-
-    use ratatui::{
-        backend::CrosstermBackend,
-        crossterm::{
-            execute,
-            terminal::{
-                disable_raw_mode, enable_raw_mode, Clear, ClearType, EnterAlternateScreen,
-                LeaveAlternateScreen,
-            },
-        },
-    };
-
-    // A type alias to simplify the usage of the terminal and make it easier to change the backend
-    // or choice of writer.
-    pub type Terminal = ratatui::Terminal<CrosstermBackend<Stdout>>;
-
-    /// Initialize the terminal by enabling raw mode and entering the alternate screen.
-    ///
-    /// This function should be called before the program starts to ensure that the terminal is in
-    /// the correct state for the application.
-    pub fn init() -> io::Result<Terminal> {
-        install_panic_hook();
-        enable_raw_mode()?;
-        execute!(stdout(), EnterAlternateScreen)?;
-        let backend = CrosstermBackend::new(stdout());
-        let terminal = Terminal::new(backend)?;
-        Ok(terminal)
-    }
-
-    /// Restore the terminal by leaving the alternate screen and disabling raw mode.
-    ///
-    /// This function should be called before the program exits to ensure that the terminal is
-    /// restored to its original state.
-    pub fn restore() -> io::Result<()> {
-        disable_raw_mode()?;
-        execute!(
-            stdout(),
-            LeaveAlternateScreen,
-            Clear(ClearType::FromCursorDown),
-        )
-    }
-
-    /// Install a panic hook that restores the terminal before printing the panic.
-    ///
-    /// This prevents error messages from being messed up by the terminal state.
-    fn install_panic_hook() {
-        let panic_hook = panic::take_hook();
-        panic::set_hook(Box::new(move |panic_info| {
-            let _ = restore();
-            panic_hook(panic_info);
-        }));
-    }
-}

examples/block.rs

@@ -9,25 +9,13 @@
 //! 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
+//! [Ratatui]: https://github.com/ratatui/ratatui
+//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md
 
-use std::{
-    error::Error,
-    io::{stdout, Stdout},
-    ops::ControlFlow,
-    time::Duration,
-};
-
-use itertools::Itertools;
+use color_eyre::Result;
 use ratatui::{
-    backend::CrosstermBackend,
-    crossterm::{
-        event::{self, Event, KeyCode},
-        execute,
-        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-    },
+    crossterm::event::{self, Event, KeyCode, KeyEventKind},
     layout::{Alignment, Constraint, Layout, Rect},
     style::{Style, Stylize},
     text::Line,
@@ -35,61 +23,29 @@ use ratatui::{
         block::{Position, Title},
         Block, BorderType, Borders, Padding, Paragraph, Wrap,
     },
-    Frame,
+    DefaultTerminal, Frame,
 };
 
-// These type aliases are used to make the code more readable by reducing repetition of the generic
-// types. They are not necessary for the functionality of the code.
-type Terminal = ratatui::Terminal<CrosstermBackend<Stdout>>;
-type Result<T> = std::result::Result<T, Box<dyn Error>>;
-
 fn main() -> Result<()> {
-    let mut terminal = setup_terminal()?;
-    let result = run(&mut terminal);
-    restore_terminal(terminal)?;
-
-    if let Err(err) = result {
-        eprintln!("{err:?}");
-    }
-    Ok(())
+    color_eyre::install()?;
+    let terminal = ratatui::init();
+    let result = run(terminal);
+    ratatui::restore();
+    result
 }
 
-fn setup_terminal() -> Result<Terminal> {
-    enable_raw_mode()?;
-    let mut stdout = stdout();
-    execute!(stdout, EnterAlternateScreen)?;
-    let backend = CrosstermBackend::new(stdout);
-    let terminal = Terminal::new(backend)?;
-    Ok(terminal)
-}
-
-fn restore_terminal(mut terminal: Terminal) -> Result<()> {
-    disable_raw_mode()?;
-    execute!(terminal.backend_mut(), LeaveAlternateScreen)?;
-    Ok(())
-}
-
-fn run(terminal: &mut Terminal) -> Result<()> {
+fn run(mut terminal: DefaultTerminal) -> Result<()> {
     loop {
-        terminal.draw(ui)?;
-        if handle_events()?.is_break() {
-            return Ok(());
-        }
-    }
-}
-
-fn handle_events() -> Result<ControlFlow<()>> {
-    if event::poll(Duration::from_millis(100))? {
+        terminal.draw(draw)?;
         if let Event::Key(key) = event::read()? {
-            if key.code == KeyCode::Char('q') {
-                return Ok(ControlFlow::Break(()));
+            if key.kind == KeyEventKind::Press && key.code == KeyCode::Char('q') {
+                break Ok(());
             }
         }
     }
-    Ok(ControlFlow::Continue(()))
 }
 
-fn ui(frame: &mut Frame) {
+fn draw(frame: &mut Frame) {
     let (title_area, layout) = calculate_layout(frame.area());
 
     render_title(frame, title_area);
@@ -133,7 +89,7 @@ fn calculate_layout(area: Rect) -> (Rect, Vec<Vec<Rect>>) {
                 .split(area)
                 .to_vec()
         })
-        .collect_vec();
+        .collect();
     (title_area, main_areas)
 }
 
@@ -183,7 +139,6 @@ fn render_styled_block(paragraph: &Paragraph, frame: &mut Frame, area: Rect) {
     frame.render_widget(paragraph.clone().block(block), area);
 }
 
-// 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::bordered()
         .title("Styled title")

examples/calendar.rs

@@ -9,62 +9,44 @@
 //! 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};
+//! [Ratatui]: https://github.com/ratatui/ratatui
+//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md
 
+use color_eyre::Result;
 use ratatui::{
-    backend::CrosstermBackend,
-    crossterm::{
-        event::{self, Event, KeyCode},
-        execute,
-        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-    },
-    layout::{Constraint, Layout, Rect},
+    crossterm::event::{self, Event, KeyCode, KeyEventKind},
+    layout::{Constraint, Layout, Margin},
     style::{Color, Modifier, Style},
     widgets::calendar::{CalendarEventStore, DateStyler, Monthly},
-    Frame, Terminal,
+    DefaultTerminal, Frame,
 };
 use time::{Date, Month, OffsetDateTime};
 
-fn main() -> Result<(), Box<dyn Error>> {
-    enable_raw_mode()?;
-    let mut stdout = io::stdout();
-    execute!(stdout, EnterAlternateScreen)?;
-    let backend = CrosstermBackend::new(stdout);
-    let mut terminal = Terminal::new(backend)?;
+fn main() -> Result<()> {
+    color_eyre::install()?;
+    let terminal = ratatui::init();
+    let result = run(terminal);
+    ratatui::restore();
+    result
+}
 
+fn run(mut terminal: DefaultTerminal) -> Result<()> {
     loop {
-        let _ = terminal.draw(draw);
-
+        terminal.draw(draw)?;
         if let Event::Key(key) = event::read()? {
-            #[allow(clippy::single_match)]
-            match key.code {
-                KeyCode::Char(_) => {
-                    break;
-                }
-                _ => {}
-            };
+            if key.kind == KeyEventKind::Press && key.code == KeyCode::Char('q') {
+                break Ok(());
+            }
         }
     }
-
-    disable_raw_mode()?;
-    execute!(terminal.backend_mut(), LeaveAlternateScreen)?;
-    terminal.show_cursor()?;
-    Ok(())
 }
 
 fn draw(frame: &mut Frame) {
-    let app_area = frame.area();
-
-    let calarea = Rect {
-        x: app_area.x + 1,
-        y: app_area.y + 1,
-        height: app_area.height - 1,
-        width: app_area.width - 1,
-    };
+    let area = frame.area().inner(Margin {
+        vertical: 1,
+        horizontal: 1,
+    });
 
     let mut start = OffsetDateTime::now_local()
         .unwrap()
@@ -76,7 +58,7 @@ fn draw(frame: &mut Frame) {
 
     let list = make_dates(start.year());
 
-    let rows = Layout::vertical([Constraint::Ratio(1, 3); 3]).split(calarea);
+    let rows = Layout::vertical([Constraint::Ratio(1, 3); 3]).split(area);
     let cols = rows.iter().flat_map(|row| {
         Layout::horizontal([Constraint::Ratio(1, 4); 4])
             .split(*row)

examples/canvas.rs

@@ -9,22 +9,15 @@
 //! 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
+//! [Ratatui]: https://github.com/ratatui/ratatui
+//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md
 
-use std::{
-    io::{self, stdout, Stdout},
-    time::{Duration, Instant},
-};
+use std::time::{Duration, Instant};
 
+use color_eyre::Result;
 use ratatui::{
-    backend::CrosstermBackend,
-    crossterm::{
-        event::{self, Event, KeyCode},
-        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-        ExecutableCommand,
-    },
+    crossterm::event::{self, Event, KeyCode},
     layout::{Constraint, Layout, Rect},
     style::{Color, Stylize},
     symbols::Marker,
@@ -32,11 +25,15 @@ use ratatui::{
         canvas::{Canvas, Circle, Map, MapResolution, Rectangle},
         Block, Widget,
     },
-    Frame, Terminal,
+    DefaultTerminal, Frame,
 };
 
-fn main() -> io::Result<()> {
-    App::run()
+fn main() -> Result<()> {
+    color_eyre::install()?;
+    let terminal = ratatui::init();
+    let app_result = App::new().run(terminal);
+    ratatui::restore();
+    app_result
 }
 
 struct App {
@@ -69,33 +66,30 @@ impl App {
         }
     }
 
-    pub fn run() -> io::Result<()> {
-        let mut terminal = init_terminal()?;
-        let mut app = Self::new();
-        let mut last_tick = Instant::now();
+    pub fn run(mut self, mut terminal: DefaultTerminal) -> Result<()> {
         let tick_rate = Duration::from_millis(16);
+        let mut last_tick = Instant::now();
         loop {
-            let _ = terminal.draw(|frame| app.ui(frame));
+            terminal.draw(|frame| self.draw(frame))?;
             let timeout = tick_rate.saturating_sub(last_tick.elapsed());
             if event::poll(timeout)? {
                 if let Event::Key(key) = event::read()? {
                     match key.code {
-                        KeyCode::Char('q') => break,
-                        KeyCode::Down | KeyCode::Char('j') => app.y += 1.0,
-                        KeyCode::Up | KeyCode::Char('k') => app.y -= 1.0,
-                        KeyCode::Right | KeyCode::Char('l') => app.x += 1.0,
-                        KeyCode::Left | KeyCode::Char('h') => app.x -= 1.0,
+                        KeyCode::Char('q') => break Ok(()),
+                        KeyCode::Down | KeyCode::Char('j') => self.y += 1.0,
+                        KeyCode::Up | KeyCode::Char('k') => self.y -= 1.0,
+                        KeyCode::Right | KeyCode::Char('l') => self.x += 1.0,
+                        KeyCode::Left | KeyCode::Char('h') => self.x -= 1.0,
                         _ => {}
                     }
                 }
             }
 
             if last_tick.elapsed() >= tick_rate {
-                app.on_tick();
+                self.on_tick();
                 last_tick = Instant::now();
             }
         }
-        restore_terminal()
     }
 
     fn on_tick(&mut self) {
@@ -128,7 +122,7 @@ impl App {
         self.ball.y += self.vy;
     }
 
-    fn ui(&self, frame: &mut Frame) {
+    fn draw(&self, frame: &mut Frame) {
         let horizontal =
             Layout::horizontal([Constraint::Percentage(50), Constraint::Percentage(50)]);
         let vertical = Layout::vertical([Constraint::Percentage(50), Constraint::Percentage(50)]);
@@ -204,15 +198,3 @@ impl App {
             })
     }
 }
-
-fn init_terminal() -> io::Result<Terminal<CrosstermBackend<Stdout>>> {
-    enable_raw_mode()?;
-    stdout().execute(EnterAlternateScreen)?;
-    Terminal::new(CrosstermBackend::new(stdout()))
-}
-
-fn restore_terminal() -> io::Result<()> {
-    disable_raw_mode()?;
-    stdout().execute(LeaveAlternateScreen)?;
-    Ok(())
-}

examples/chart.rs

@@ -9,31 +9,39 @@
 //! 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
+//! [Ratatui]: https://github.com/ratatui/ratatui
+//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md
 
-use std::{
-    error::Error,
-    io,
-    time::{Duration, Instant},
-};
+use std::time::{Duration, Instant};
 
+use color_eyre::Result;
 use ratatui::{
-    backend::{Backend, CrosstermBackend},
-    crossterm::{
-        event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode},
-        execute,
-        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-    },
+    crossterm::event::{self, Event, KeyCode},
     layout::{Alignment, Constraint, Layout, Rect},
     style::{Color, Modifier, Style, Stylize},
     symbols::{self, Marker},
     text::Span,
     widgets::{block::Title, Axis, Block, Chart, Dataset, GraphType, LegendPosition},
-    Frame, Terminal,
+    DefaultTerminal, Frame,
 };
 
+fn main() -> Result<()> {
+    color_eyre::install()?;
+    let terminal = ratatui::init();
+    let app_result = App::new().run(terminal);
+    ratatui::restore();
+    app_result
+}
+
+struct App {
+    signal1: SinSignal,
+    data1: Vec<(f64, f64)>,
+    signal2: SinSignal,
+    data2: Vec<(f64, f64)>,
+    window: [f64; 2],
+}
+
 #[derive(Clone)]
 struct SinSignal {
     x: f64,
@@ -62,14 +70,6 @@ impl Iterator for SinSignal {
     }
 }
 
-struct App {
-    signal1: SinSignal,
-    data1: Vec<(f64, f64)>,
-    signal2: SinSignal,
-    data2: Vec<(f64, f64)>,
-    window: [f64; 2],
-}
-
 impl App {
     fn new() -> Self {
         let mut signal1 = SinSignal::new(0.2, 3.0, 18.0);
@@ -85,6 +85,27 @@ impl App {
         }
     }
 
+    fn run(mut self, mut terminal: DefaultTerminal) -> Result<()> {
+        let tick_rate = Duration::from_millis(250);
+        let mut last_tick = Instant::now();
+        loop {
+            terminal.draw(|frame| self.draw(frame))?;
+
+            let timeout = tick_rate.saturating_sub(last_tick.elapsed());
+            if event::poll(timeout)? {
+                if let Event::Key(key) = event::read()? {
+                    if key.code == KeyCode::Char('q') {
+                        return Ok(());
+                    }
+                }
+            }
+            if last_tick.elapsed() >= tick_rate {
+                self.on_tick();
+                last_tick = Instant::now();
+            }
+        }
+    }
+
     fn on_tick(&mut self) {
         self.data1.drain(0..5);
         self.data1.extend(self.signal1.by_ref().take(5));
@@ -95,118 +116,65 @@ impl App {
         self.window[0] += 1.0;
         self.window[1] += 1.0;
     }
-}
 
-fn main() -> Result<(), Box<dyn Error>> {
-    // setup terminal
-    enable_raw_mode()?;
-    let mut stdout = io::stdout();
-    execute!(stdout, EnterAlternateScreen, EnableMouseCapture)?;
-    let backend = CrosstermBackend::new(stdout);
-    let mut terminal = Terminal::new(backend)?;
+    fn draw(&self, frame: &mut Frame) {
+        let [top, bottom] = Layout::vertical([Constraint::Fill(1); 2]).areas(frame.area());
+        let [animated_chart, bar_chart] =
+            Layout::horizontal([Constraint::Fill(1), Constraint::Length(29)]).areas(top);
+        let [line_chart, scatter] = Layout::horizontal([Constraint::Fill(1); 2]).areas(bottom);
 
-    // 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:?}");
+        self.render_animated_chart(frame, animated_chart);
+        render_barchart(frame, bar_chart);
+        render_line_chart(frame, line_chart);
+        render_scatter(frame, scatter);
     }
 
-    Ok(())
-}
+    fn render_animated_chart(&self, frame: &mut Frame, area: Rect) {
+        let x_labels = vec![
+            Span::styled(
+                format!("{}", self.window[0]),
+                Style::default().add_modifier(Modifier::BOLD),
+            ),
+            Span::raw(format!("{}", (self.window[0] + self.window[1]) / 2.0)),
+            Span::styled(
+                format!("{}", self.window[1]),
+                Style::default().add_modifier(Modifier::BOLD),
+            ),
+        ];
+        let datasets = vec![
+            Dataset::default()
+                .name("data2")
+                .marker(symbols::Marker::Dot)
+                .style(Style::default().fg(Color::Cyan))
+                .data(&self.data1),
+            Dataset::default()
+                .name("data3")
+                .marker(symbols::Marker::Braille)
+                .style(Style::default().fg(Color::Yellow))
+                .data(&self.data2),
+        ];
 
-fn run_app<B: Backend>(
-    terminal: &mut Terminal<B>,
-    mut app: App,
-    tick_rate: Duration,
-) -> io::Result<()> {
-    let mut last_tick = Instant::now();
-    loop {
-        terminal.draw(|f| ui(f, &app))?;
+        let chart = Chart::new(datasets)
+            .block(Block::bordered())
+            .x_axis(
+                Axis::default()
+                    .title("X Axis")
+                    .style(Style::default().fg(Color::Gray))
+                    .labels(x_labels)
+                    .bounds(self.window),
+            )
+            .y_axis(
+                Axis::default()
+                    .title("Y Axis")
+                    .style(Style::default().fg(Color::Gray))
+                    .labels(["-20".bold(), "0".into(), "20".bold()])
+                    .bounds([-20.0, 20.0]),
+            );
 
-        let timeout = tick_rate.saturating_sub(last_tick.elapsed());
-        if crossterm::event::poll(timeout)? {
-            if let Event::Key(key) = event::read()? {
-                if key.code == KeyCode::Char('q') {
-                    return Ok(());
-                }
-            }
-        }
-        if last_tick.elapsed() >= tick_rate {
-            app.on_tick();
-            last_tick = Instant::now();
-        }
+        frame.render_widget(chart, area);
     }
 }
 
-fn ui(frame: &mut Frame, app: &App) {
-    let [top, bottom] = Layout::vertical([Constraint::Fill(1); 2]).areas(frame.area());
-    let [animated_chart, bar_chart] =
-        Layout::horizontal([Constraint::Fill(1), Constraint::Length(29)]).areas(top);
-    let [line_chart, scatter] = Layout::horizontal([Constraint::Fill(1); 2]).areas(bottom);
-
-    render_animated_chart(frame, animated_chart, app);
-    render_barchart(frame, bar_chart);
-    render_line_chart(frame, line_chart);
-    render_scatter(frame, scatter);
-}
-
-fn render_animated_chart(f: &mut Frame, area: Rect, app: &App) {
-    let x_labels = vec![
-        Span::styled(
-            format!("{}", app.window[0]),
-            Style::default().add_modifier(Modifier::BOLD),
-        ),
-        Span::raw(format!("{}", (app.window[0] + app.window[1]) / 2.0)),
-        Span::styled(
-            format!("{}", app.window[1]),
-            Style::default().add_modifier(Modifier::BOLD),
-        ),
-    ];
-    let datasets = vec![
-        Dataset::default()
-            .name("data2")
-            .marker(symbols::Marker::Dot)
-            .style(Style::default().fg(Color::Cyan))
-            .data(&app.data1),
-        Dataset::default()
-            .name("data3")
-            .marker(symbols::Marker::Braille)
-            .style(Style::default().fg(Color::Yellow))
-            .data(&app.data2),
-    ];
-
-    let chart = Chart::new(datasets)
-        .block(Block::bordered())
-        .x_axis(
-            Axis::default()
-                .title("X Axis")
-                .style(Style::default().fg(Color::Gray))
-                .labels(x_labels)
-                .bounds(app.window),
-        )
-        .y_axis(
-            Axis::default()
-                .title("Y Axis")
-                .style(Style::default().fg(Color::Gray))
-                .labels(["-20".bold(), "0".into(), "20".bold()])
-                .bounds([-20.0, 20.0]),
-        );
-
-    f.render_widget(chart, area);
-}
-
 fn render_barchart(frame: &mut Frame, bar_chart: Rect) {
     let dataset = Dataset::default()
         .marker(symbols::Marker::HalfBlock)
@@ -252,7 +220,7 @@ fn render_barchart(frame: &mut Frame, bar_chart: Rect) {
     frame.render_widget(chart, bar_chart);
 }
 
-fn render_line_chart(f: &mut Frame, area: Rect) {
+fn render_line_chart(frame: &mut Frame, area: Rect) {
     let datasets = vec![Dataset::default()
         .name("Line from only 2 points".italic())
         .marker(symbols::Marker::Braille)
@@ -285,10 +253,10 @@ 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);
+    frame.render_widget(chart, area);
 }
 
-fn render_scatter(f: &mut Frame, area: Rect) {
+fn render_scatter(frame: &mut Frame, area: Rect) {
     let datasets = vec![
         Dataset::default()
             .name("Heavy")
@@ -334,7 +302,7 @@ fn render_scatter(f: &mut Frame, area: Rect) {
         )
         .hidden_legend_constraints((Constraint::Ratio(1, 2), Constraint::Ratio(1, 2)));
 
-    f.render_widget(chart, area);
+    frame.render_widget(chart, area);
 }
 
 // Data from https://ourworldindata.org/space-exploration-satellites

examples/colors.rs

@@ -9,62 +9,44 @@
 //! 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
+//! [Ratatui]: https://github.com/ratatui/ratatui
+//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui/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},
-    result,
-    time::Duration,
-};
-
+use color_eyre::Result;
 use itertools::Itertools;
 use ratatui::{
-    backend::{Backend, CrosstermBackend},
-    crossterm::{
-        event::{self, Event, KeyCode},
-        execute,
-        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-    },
+    crossterm::event::{self, Event, KeyCode, KeyEventKind},
     layout::{Alignment, Constraint, Layout, Rect},
     style::{Color, Style, Stylize},
     text::Line,
     widgets::{Block, Borders, Paragraph},
-    Frame, Terminal,
+    DefaultTerminal, Frame,
 };
 
-type Result<T> = result::Result<T, Box<dyn Error>>;
-
 fn main() -> Result<()> {
-    let mut terminal = setup_terminal()?;
-    let res = run_app(&mut terminal);
-    restore_terminal(terminal)?;
-    if let Err(err) = res {
-        eprintln!("{err:?}");
-    }
-    Ok(())
+    color_eyre::install()?;
+    let terminal = ratatui::init();
+    let app_result = run(terminal);
+    ratatui::restore();
+    app_result
 }
 
-fn run_app<B: Backend>(terminal: &mut Terminal<B>) -> io::Result<()> {
+fn run(mut terminal: DefaultTerminal) -> Result<()> {
     loop {
-        terminal.draw(ui)?;
-
-        if event::poll(Duration::from_millis(250))? {
-            if let Event::Key(key) = event::read()? {
-                if key.code == KeyCode::Char('q') {
-                    return Ok(());
-                }
+        terminal.draw(draw)?;
+        if let Event::Key(key) = event::read()? {
+            if key.kind == KeyEventKind::Press && key.code == KeyCode::Char('q') {
+                return Ok(());
             }
         }
     }
 }
 
-fn ui(frame: &mut Frame) {
+fn draw(frame: &mut Frame) {
     let layout = Layout::vertical([
         Constraint::Length(30),
         Constraint::Length(17),
@@ -117,19 +99,16 @@ fn render_fg_named_colors(frame: &mut Frame, bg: Color, area: Rect) {
     let inner = block.inner(area);
     frame.render_widget(block, area);
 
-    let layout = Layout::vertical([Constraint::Length(1); 2])
-        .split(inner)
-        .iter()
-        .flat_map(|area| {
-            Layout::horizontal([Constraint::Ratio(1, 8); 8])
-                .split(*area)
-                .to_vec()
-        })
-        .collect_vec();
-    for (i, &fg) in NAMED_COLORS.iter().enumerate() {
+    let vertical = Layout::vertical([Constraint::Length(1); 2]).split(inner);
+    let areas = vertical.iter().flat_map(|area| {
+        Layout::horizontal([Constraint::Ratio(1, 8); 8])
+            .split(*area)
+            .to_vec()
+    });
+    for (fg, area) in NAMED_COLORS.into_iter().zip(areas) {
         let color_name = fg.to_string();
         let paragraph = Paragraph::new(color_name).fg(fg).bg(bg);
-        frame.render_widget(paragraph, layout[i]);
+        frame.render_widget(paragraph, area);
     }
 }
 
@@ -138,19 +117,16 @@ fn render_bg_named_colors(frame: &mut Frame, fg: Color, area: Rect) {
     let inner = block.inner(area);
     frame.render_widget(block, area);
 
-    let layout = Layout::vertical([Constraint::Length(1); 2])
-        .split(inner)
-        .iter()
-        .flat_map(|area| {
-            Layout::horizontal([Constraint::Ratio(1, 8); 8])
-                .split(*area)
-                .to_vec()
-        })
-        .collect_vec();
-    for (i, &bg) in NAMED_COLORS.iter().enumerate() {
+    let vertical = Layout::vertical([Constraint::Length(1); 2]).split(inner);
+    let areas = vertical.iter().flat_map(|area| {
+        Layout::horizontal([Constraint::Ratio(1, 8); 8])
+            .split(*area)
+            .to_vec()
+    });
+    for (bg, area) in NAMED_COLORS.into_iter().zip(areas) {
         let color_name = bg.to_string();
         let paragraph = Paragraph::new(color_name).fg(fg).bg(bg);
-        frame.render_widget(paragraph, layout[i]);
+        frame.render_widget(paragraph, area);
     }
 }
 
@@ -271,20 +247,3 @@ fn render_indexed_grayscale(frame: &mut Frame, area: Rect) {
         frame.render_widget(paragraph, layout[i as usize - 232]);
     }
 }
-
-fn setup_terminal() -> Result<Terminal<CrosstermBackend<Stdout>>> {
-    enable_raw_mode()?;
-    let mut stdout = io::stdout();
-    execute!(stdout, EnterAlternateScreen)?;
-    let backend = CrosstermBackend::new(stdout);
-    let mut terminal = Terminal::new(backend)?;
-    terminal.hide_cursor()?;
-    Ok(terminal)
-}
-
-fn restore_terminal(mut terminal: Terminal<CrosstermBackend<Stdout>>) -> Result<()> {
-    disable_raw_mode()?;
-    execute!(terminal.backend_mut(), LeaveAlternateScreen)?;
-    terminal.show_cursor()?;
-    Ok(())
-}

examples/colors_rgb.rs

@@ -9,9 +9,9 @@
 //! 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
+//! [Ratatui]: https://github.com/ratatui/ratatui
+//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md
 
 // This example shows the full range of RGB colors that can be displayed in the terminal.
 //
@@ -26,29 +26,28 @@
 // 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 std::time::{Duration, Instant};
 
-use color_eyre::{config::HookBuilder, eyre, Result};
+use color_eyre::Result;
 use palette::{convert::FromColorUnclamped, Okhsv, Srgb};
 use ratatui::{
-    backend::{Backend, CrosstermBackend},
     buffer::Buffer,
-    crossterm::{
-        event::{self, Event, KeyCode, KeyEventKind},
-        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-        ExecutableCommand,
-    },
+    crossterm::event::{self, Event, KeyCode, KeyEventKind},
     layout::{Constraint, Layout, Position, Rect},
     style::Color,
     text::Text,
     widgets::Widget,
-    Terminal,
+    DefaultTerminal,
 };
 
+fn main() -> Result<()> {
+    color_eyre::install()?;
+    let terminal = ratatui::init();
+    let app_result = App::default().run(terminal);
+    ratatui::restore();
+    app_result
+}
+
 #[derive(Debug, Default)]
 struct App {
     /// The current state of the app (running or quit)
@@ -99,19 +98,11 @@ struct ColorsWidget {
     frame_count: usize,
 }
 
-fn main() -> Result<()> {
-    install_error_hooks()?;
-    let terminal = init_terminal()?;
-    App::default().run(terminal)?;
-    restore_terminal()?;
-    Ok(())
-}
-
 impl App {
     /// Run the app
     ///
     /// This is the main event loop for the app.
-    pub fn run(mut self, mut terminal: Terminal<impl Backend>) -> Result<()> {
+    pub fn run(mut self, mut terminal: DefaultTerminal) -> Result<()> {
         while self.is_running() {
             terminal.draw(|frame| frame.render_widget(&mut self, frame.area()))?;
             self.handle_events()?;
@@ -263,36 +254,3 @@ impl ColorsWidget {
         }
     }
 }
-
-/// 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();
-    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(())
-}
-
-fn init_terminal() -> Result<Terminal<impl Backend>> {
-    enable_raw_mode()?;
-    stdout().execute(EnterAlternateScreen)?;
-    let mut terminal = Terminal::new(CrosstermBackend::new(stdout()))?;
-    terminal.clear()?;
-    terminal.hide_cursor()?;
-    Ok(terminal)
-}
-
-fn restore_terminal() -> Result<()> {
-    disable_raw_mode()?;
-    stdout().execute(LeaveAlternateScreen)?;
-    Ok(())
-}

examples/constraint-explorer.rs

@@ -9,22 +9,15 @@
 //! 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
+//! [Ratatui]: https://github.com/ratatui/ratatui
+//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md
 
-use std::io::{self, stdout};
-
-use color_eyre::{config::HookBuilder, Result};
+use color_eyre::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,
-    },
+    crossterm::event::{self, Event, KeyCode, KeyEventKind},
     layout::{
         Constraint::{self, Fill, Length, Max, Min, Percentage, Ratio},
         Flex, Layout, Rect,
@@ -36,10 +29,18 @@ use ratatui::{
     symbols::{self, line},
     text::{Line, Span, Text},
     widgets::{Block, Paragraph, Widget, Wrap},
-    Terminal,
+    DefaultTerminal,
 };
 use strum::{Display, EnumIter, FromRepr};
 
+fn main() -> Result<()> {
+    color_eyre::install()?;
+    let terminal = ratatui::init();
+    let app_result = App::default().run(terminal);
+    ratatui::restore();
+    app_result
+}
+
 #[derive(Default)]
 struct App {
     mode: AppMode,
@@ -90,21 +91,13 @@ struct ConstraintBlock {
 /// ```
 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<()> {
+    fn run(mut self, mut terminal: DefaultTerminal) -> Result<()> {
         self.insert_test_defaults();
 
         while self.is_running() {
-            self.draw(&mut terminal)?;
+            terminal.draw(|frame| frame.render_widget(&self, frame.area()))?;
             self.handle_events()?;
         }
         Ok(())
@@ -124,11 +117,6 @@ impl App {
         self.mode == AppMode::Running
     }
 
-    fn draw(&self, terminal: &mut Terminal<impl Backend>) -> io::Result<()> {
-        terminal.draw(|frame| frame.render_widget(self, frame.area()))?;
-        Ok(())
-    }
-
     fn handle_events(&mut self) -> Result<()> {
         match event::read()? {
             Event::Key(key) if key.kind == KeyEventKind::Press => match key.code {
@@ -358,13 +346,8 @@ impl App {
     }
 
     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);
+        let constraints = self.constraints.iter().map(|_| Constraint::Fill(1));
+        let blocks = Layout::horizontal(constraints).split(area);
 
         for (i, (area, constraint)) in blocks.iter().zip(self.constraints.iter()).enumerate() {
             let selected = self.selected_index == i;
@@ -621,32 +604,3 @@ impl ConstraintName {
         }
     }
 }
-
-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

@@ -9,21 +9,14 @@
 //! 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
+//! [Ratatui]: https://github.com/ratatui/ratatui
+//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md
 
-use std::io::{self, stdout};
-
-use color_eyre::{config::HookBuilder, Result};
+use color_eyre::Result;
 use ratatui::{
-    backend::{Backend, CrosstermBackend},
     buffer::Buffer,
-    crossterm::{
-        event::{self, Event, KeyCode, KeyEventKind},
-        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-        ExecutableCommand,
-    },
+    crossterm::event::{self, Event, KeyCode, KeyEventKind},
     layout::{
         Constraint::{self, Fill, Length, Max, Min, Percentage, Ratio},
         Layout, Rect,
@@ -35,7 +28,7 @@ use ratatui::{
         Block, Padding, Paragraph, Scrollbar, ScrollbarOrientation, ScrollbarState, StatefulWidget,
         Tabs, Widget,
     },
-    Terminal,
+    DefaultTerminal,
 };
 use strum::{Display, EnumIter, FromRepr, IntoEnumIterator};
 
@@ -53,6 +46,14 @@ const RATIO_COLOR: Color = tailwind::SLATE.c900;
 // priority 4
 const FILL_COLOR: Color = tailwind::SLATE.c950;
 
+fn main() -> Result<()> {
+    color_eyre::install()?;
+    let terminal = ratatui::init();
+    let app_result = App::default().run(terminal);
+    ratatui::restore();
+    app_result
+}
+
 #[derive(Default, Clone, Copy)]
 struct App {
     selected_tab: SelectedTab,
@@ -82,22 +83,11 @@ enum AppState {
     Quit,
 }
 
-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<()> {
+    fn run(mut self, mut terminal: DefaultTerminal) -> Result<()> {
         self.update_max_scroll_offset();
         while self.is_running() {
-            self.draw(&mut terminal)?;
+            terminal.draw(|frame| frame.render_widget(self, frame.area()))?;
             self.handle_events()?;
         }
         Ok(())
@@ -111,11 +101,6 @@ impl App {
         self.state == AppState::Running
     }
 
-    fn draw(self, terminal: &mut Terminal<impl Backend>) -> io::Result<()> {
-        terminal.draw(|frame| frame.render_widget(self, frame.area()))?;
-        Ok(())
-    }
-
     fn handle_events(&mut self) -> Result<()> {
         if let Event::Key(key) = event::read()? {
             if key.kind != KeyEventKind::Press {
@@ -418,32 +403,3 @@ impl Example {
         Paragraph::new(text).centered().block(block)
     }
 }
-
-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/custom_widget.rs

@@ -9,14 +9,14 @@
 //! 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
+//! [Ratatui]: https://github.com/ratatui/ratatui
+//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md
 
-use std::{error::Error, io, ops::ControlFlow, time::Duration};
+use std::{io::stdout, ops::ControlFlow, time::Duration};
 
+use color_eyre::Result;
 use ratatui::{
-    backend::{Backend, CrosstermBackend},
     buffer::Buffer,
     crossterm::{
         event::{
@@ -24,15 +24,26 @@ use ratatui::{
             MouseEventKind,
         },
         execute,
-        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
     },
     layout::{Constraint, Layout, Rect},
     style::{Color, Style},
     text::Line,
     widgets::{Paragraph, Widget},
-    Frame, Terminal,
+    DefaultTerminal, Frame,
 };
 
+fn main() -> Result<()> {
+    color_eyre::install()?;
+    let terminal = ratatui::init();
+    execute!(stdout(), EnableMouseCapture)?;
+    let app_result = run(terminal);
+    ratatui::restore();
+    if let Err(err) = execute!(stdout(), DisableMouseCapture) {
+        eprintln!("Error disabling mouse capture: {err}");
+    }
+    app_result
+}
+
 /// A custom widget that renders a button with a label, theme and state.
 #[derive(Debug, Clone)]
 struct Button<'a> {
@@ -143,38 +154,11 @@ impl Button<'_> {
     }
 }
 
-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 res = run_app(&mut terminal);
-
-    // 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>) -> io::Result<()> {
+fn run(mut terminal: DefaultTerminal) -> Result<()> {
     let mut selected_button: usize = 0;
     let mut button_states = [State::Selected, State::Normal, State::Normal];
     loop {
-        terminal.draw(|frame| ui(frame, button_states))?;
+        terminal.draw(|frame| draw(frame, button_states))?;
         if !event::poll(Duration::from_millis(100))? {
             continue;
         }
@@ -196,7 +180,7 @@ fn run_app<B: Backend>(terminal: &mut Terminal<B>) -> io::Result<()> {
     Ok(())
 }
 
-fn ui(frame: &mut Frame, states: [State; 3]) {
+fn draw(frame: &mut Frame, states: [State; 3]) {
     let vertical = Layout::vertical([
         Constraint::Length(1),
         Constraint::Max(3),

examples/demo/app.rs

@@ -122,7 +122,7 @@ pub struct TabsState<'a> {
 }
 
 impl<'a> TabsState<'a> {
-    pub fn new(titles: Vec<&'a str>) -> Self {
+    pub const fn new(titles: Vec<&'a str>) -> Self {
         Self { titles, index: 0 }
     }
     pub fn next(&mut self) {

examples/demo/crossterm.rs

@@ -26,7 +26,7 @@ pub fn run(tick_rate: Duration, enhanced_graphics: bool) -> Result<(), Box<dyn E
 
     // create app and run it
     let app = App::new("Crossterm Demo", enhanced_graphics);
-    let res = run_app(&mut terminal, app, tick_rate);
+    let app_result = run_app(&mut terminal, app, tick_rate);
 
     // restore terminal
     disable_raw_mode()?;
@@ -37,7 +37,7 @@ pub fn run(tick_rate: Duration, enhanced_graphics: bool) -> Result<(), Box<dyn E
     )?;
     terminal.show_cursor()?;
 
-    if let Err(err) = res {
+    if let Err(err) = app_result {
         println!("{err:?}");
     }
 
@@ -51,10 +51,10 @@ fn run_app<B: Backend>(
 ) -> io::Result<()> {
     let mut last_tick = Instant::now();
     loop {
-        terminal.draw(|f| ui::draw(f, &mut app))?;
+        terminal.draw(|frame| ui::draw(frame, &mut app))?;
 
         let timeout = tick_rate.saturating_sub(last_tick.elapsed());
-        if crossterm::event::poll(timeout)? {
+        if event::poll(timeout)? {
             if let Event::Key(key) = event::read()? {
                 if key.kind == KeyEventKind::Press {
                     match key.code {

examples/demo/main.rs

@@ -9,9 +9,9 @@
 //! 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
+//! [Ratatui]: https://github.com/ratatui/ratatui
+//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md
 
 use std::{error::Error, time::Duration};
 
@@ -20,7 +20,7 @@ use argh::FromArgs;
 mod app;
 #[cfg(feature = "crossterm")]
 mod crossterm;
-#[cfg(feature = "termion")]
+#[cfg(all(not(windows), feature = "termion"))]
 mod termion;
 #[cfg(feature = "termwiz")]
 mod termwiz;
@@ -43,9 +43,13 @@ fn main() -> Result<(), Box<dyn Error>> {
     let tick_rate = Duration::from_millis(cli.tick_rate);
     #[cfg(feature = "crossterm")]
     crate::crossterm::run(tick_rate, cli.enhanced_graphics)?;
-    #[cfg(feature = "termion")]
+    #[cfg(all(not(windows), feature = "termion", not(feature = "crossterm")))]
     crate::termion::run(tick_rate, cli.enhanced_graphics)?;
-    #[cfg(feature = "termwiz")]
+    #[cfg(all(
+        feature = "termwiz",
+        not(feature = "crossterm"),
+        not(feature = "termion")
+    ))]
     crate::termwiz::run(tick_rate, cli.enhanced_graphics)?;
     Ok(())
 }

examples/demo/termion.rs

@@ -1,3 +1,4 @@
+#![allow(dead_code)]
 use std::{error::Error, io, sync::mpsc, thread, time::Duration};
 
 use ratatui::{
@@ -38,7 +39,7 @@ fn run_app<B: Backend>(
 ) -> Result<(), Box<dyn Error>> {
     let events = events(tick_rate);
     loop {
-        terminal.draw(|f| ui::draw(f, &mut app))?;
+        terminal.draw(|frame| ui::draw(frame, &mut app))?;
 
         match events.recv()? {
             Event::Input(key) => match key {

examples/demo/termwiz.rs

@@ -1,3 +1,4 @@
+#![allow(dead_code)]
 use std::{
     error::Error,
     time::{Duration, Instant},
@@ -21,12 +22,12 @@ pub fn run(tick_rate: Duration, enhanced_graphics: bool) -> Result<(), Box<dyn E
 
     // create app and run it
     let app = App::new("Termwiz Demo", enhanced_graphics);
-    let res = run_app(&mut terminal, app, tick_rate);
+    let app_result = run_app(&mut terminal, app, tick_rate);
 
     terminal.show_cursor()?;
     terminal.flush()?;
 
-    if let Err(err) = res {
+    if let Err(err) = app_result {
         println!("{err:?}");
     }
 
@@ -40,7 +41,7 @@ fn run_app(
 ) -> Result<(), Box<dyn Error>> {
     let mut last_tick = Instant::now();
     loop {
-        terminal.draw(|f| ui::draw(f, &mut app))?;
+        terminal.draw(|frame| ui::draw(frame, &mut app))?;
 
         let timeout = tick_rate.saturating_sub(last_tick.elapsed());
         if let Some(input) = terminal

examples/demo/ui.rs

@@ -13,8 +13,8 @@ use ratatui::{
 
 use crate::app::App;
 
-pub fn draw(f: &mut Frame, app: &mut App) {
-    let chunks = Layout::vertical([Constraint::Length(3), Constraint::Min(0)]).split(f.area());
+pub fn draw(frame: &mut Frame, app: &mut App) {
+    let chunks = Layout::vertical([Constraint::Length(3), Constraint::Min(0)]).split(frame.area());
     let tabs = app
         .tabs
         .titles
@@ -24,28 +24,28 @@ pub fn draw(f: &mut Frame, app: &mut App) {
         .block(Block::bordered().title(app.title))
         .highlight_style(Style::default().fg(Color::Yellow))
         .select(app.tabs.index);
-    f.render_widget(tabs, chunks[0]);
+    frame.render_widget(tabs, chunks[0]);
     match app.tabs.index {
-        0 => draw_first_tab(f, app, chunks[1]),
-        1 => draw_second_tab(f, app, chunks[1]),
-        2 => draw_third_tab(f, app, chunks[1]),
+        0 => draw_first_tab(frame, app, chunks[1]),
+        1 => draw_second_tab(frame, app, chunks[1]),
+        2 => draw_third_tab(frame, app, chunks[1]),
         _ => {}
     };
 }
 
-fn draw_first_tab(f: &mut Frame, app: &mut App, area: Rect) {
+fn draw_first_tab(frame: &mut Frame, app: &mut App, area: Rect) {
     let chunks = Layout::vertical([
         Constraint::Length(9),
         Constraint::Min(8),
         Constraint::Length(7),
     ])
     .split(area);
-    draw_gauges(f, app, chunks[0]);
-    draw_charts(f, app, chunks[1]);
-    draw_text(f, chunks[2]);
+    draw_gauges(frame, app, chunks[0]);
+    draw_charts(frame, app, chunks[1]);
+    draw_text(frame, chunks[2]);
 }
 
-fn draw_gauges(f: &mut Frame, app: &mut App, area: Rect) {
+fn draw_gauges(frame: &mut Frame, app: &mut App, area: Rect) {
     let chunks = Layout::vertical([
         Constraint::Length(2),
         Constraint::Length(3),
@@ -54,7 +54,7 @@ fn draw_gauges(f: &mut Frame, app: &mut App, area: Rect) {
     .margin(1)
     .split(area);
     let block = Block::bordered().title("Graphs");
-    f.render_widget(block, area);
+    frame.render_widget(block, area);
 
     let label = format!("{:.2}%", app.progress * 100.0);
     let gauge = Gauge::default()
@@ -68,7 +68,7 @@ fn draw_gauges(f: &mut Frame, app: &mut App, area: Rect) {
         .use_unicode(app.enhanced_graphics)
         .label(label)
         .ratio(app.progress);
-    f.render_widget(gauge, chunks[0]);
+    frame.render_widget(gauge, chunks[0]);
 
     let sparkline = Sparkline::default()
         .block(Block::new().title("Sparkline:"))
@@ -79,7 +79,7 @@ fn draw_gauges(f: &mut Frame, app: &mut App, area: Rect) {
         } else {
             symbols::bar::THREE_LEVELS
         });
-    f.render_widget(sparkline, chunks[1]);
+    frame.render_widget(sparkline, chunks[1]);
 
     let line_gauge = LineGauge::default()
         .block(Block::new().title("LineGauge:"))
@@ -90,11 +90,11 @@ fn draw_gauges(f: &mut Frame, app: &mut App, area: Rect) {
             symbols::line::NORMAL
         })
         .ratio(app.progress);
-    f.render_widget(line_gauge, chunks[2]);
+    frame.render_widget(line_gauge, chunks[2]);
 }
 
 #[allow(clippy::too_many_lines)]
-fn draw_charts(f: &mut Frame, app: &mut App, area: Rect) {
+fn draw_charts(frame: &mut Frame, app: &mut App, area: Rect) {
     let constraints = if app.show_chart {
         vec![Constraint::Percentage(50), Constraint::Percentage(50)]
     } else {
@@ -120,7 +120,7 @@ fn draw_charts(f: &mut Frame, app: &mut App, area: Rect) {
                 .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);
+            frame.render_stateful_widget(tasks, chunks[0], &mut app.tasks.state);
 
             // Draw logs
             let info_style = Style::default().fg(Color::Blue);
@@ -146,7 +146,7 @@ fn draw_charts(f: &mut Frame, app: &mut App, area: Rect) {
                 })
                 .collect();
             let logs = List::new(logs).block(Block::bordered().title("List"));
-            f.render_stateful_widget(logs, chunks[1], &mut app.logs.state);
+            frame.render_stateful_widget(logs, chunks[1], &mut app.logs.state);
         }
 
         let barchart = BarChart::default()
@@ -167,7 +167,7 @@ fn draw_charts(f: &mut Frame, app: &mut App, area: Rect) {
             )
             .label_style(Style::default().fg(Color::Yellow))
             .bar_style(Style::default().fg(Color::Green));
-        f.render_widget(barchart, chunks[1]);
+        frame.render_widget(barchart, chunks[1]);
     }
     if app.show_chart {
         let x_labels = vec![
@@ -227,11 +227,11 @@ fn draw_charts(f: &mut Frame, app: &mut App, area: Rect) {
                         Span::styled("20", Style::default().add_modifier(Modifier::BOLD)),
                     ]),
             );
-        f.render_widget(chart, chunks[1]);
+        frame.render_widget(chart, chunks[1]);
     }
 }
 
-fn draw_text(f: &mut Frame, area: Rect) {
+fn draw_text(frame: &mut Frame, area: Rect) {
     let text = vec![
         text::Line::from("This is a paragraph with several lines. You can change style your text the way you want"),
         text::Line::from(""),
@@ -266,10 +266,10 @@ fn draw_text(f: &mut Frame, area: Rect) {
             .add_modifier(Modifier::BOLD),
     ));
     let paragraph = Paragraph::new(text).block(block).wrap(Wrap { trim: true });
-    f.render_widget(paragraph, area);
+    frame.render_widget(paragraph, area);
 }
 
-fn draw_second_tab(f: &mut Frame, app: &mut App, area: Rect) {
+fn draw_second_tab(frame: &mut Frame, app: &mut App, area: Rect) {
     let chunks =
         Layout::horizontal([Constraint::Percentage(30), Constraint::Percentage(70)]).split(area);
     let up_style = Style::default().fg(Color::Green);
@@ -298,7 +298,7 @@ fn draw_second_tab(f: &mut Frame, app: &mut App, area: Rect) {
             .bottom_margin(1),
     )
     .block(Block::bordered().title("Servers"));
-    f.render_widget(table, chunks[0]);
+    frame.render_widget(table, chunks[0]);
 
     let map = Canvas::default()
         .block(Block::bordered().title("World"))
@@ -352,10 +352,10 @@ fn draw_second_tab(f: &mut Frame, app: &mut App, area: Rect) {
         })
         .x_bounds([-180.0, 180.0])
         .y_bounds([-90.0, 90.0]);
-    f.render_widget(map, chunks[1]);
+    frame.render_widget(map, chunks[1]);
 }
 
-fn draw_third_tab(f: &mut Frame, _app: &mut App, area: Rect) {
+fn draw_third_tab(frame: &mut Frame, _app: &mut App, area: Rect) {
     let chunks = Layout::horizontal([Constraint::Ratio(1, 2), Constraint::Ratio(1, 2)]).split(area);
     let colors = [
         Color::Reset,
@@ -396,5 +396,5 @@ fn draw_third_tab(f: &mut Frame, _app: &mut App, area: Rect) {
         ],
     )
     .block(Block::bordered().title("Colors"));
-    f.render_widget(table, chunks[0]);
+    frame.render_widget(table, chunks[0]);
 }

examples/demo2/app.rs

@@ -1,23 +1,23 @@
 use std::time::Duration;
 
 use color_eyre::{eyre::Context, Result};
+use crossterm::event;
 use itertools::Itertools;
 use ratatui::{
-    backend::Backend,
     buffer::Buffer,
     crossterm::event::{Event, KeyCode, KeyEvent, KeyEventKind},
     layout::{Constraint, Layout, Rect},
     style::Color,
     text::{Line, Span},
     widgets::{Block, Tabs, Widget},
-    Terminal,
+    DefaultTerminal, Frame,
 };
 use strum::{Display, EnumIter, FromRepr, IntoEnumIterator};
 
 use crate::{
     destroy,
     tabs::{AboutTab, EmailTab, RecipeTab, TracerouteTab, WeatherTab},
-    term, THEME,
+    THEME,
 };
 
 #[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
@@ -49,15 +49,13 @@ enum Tab {
     Weather,
 }
 
-pub fn run(terminal: &mut Terminal<impl Backend>) -> Result<()> {
-    App::default().run(terminal)
-}
-
 impl App {
     /// Run the app until the user quits.
-    pub fn run(&mut self, terminal: &mut Terminal<impl Backend>) -> Result<()> {
+    pub fn run(mut self, mut terminal: DefaultTerminal) -> Result<()> {
         while self.is_running() {
-            self.draw(terminal)?;
+            terminal
+                .draw(|frame| self.draw(frame))
+                .wrap_err("terminal.draw")?;
             self.handle_events()?;
         }
         Ok(())
@@ -68,16 +66,11 @@ impl App {
     }
 
     /// Draw a single frame of the app.
-    fn draw(&self, terminal: &mut Terminal<impl Backend>) -> Result<()> {
-        terminal
-            .draw(|frame| {
-                frame.render_widget(self, frame.area());
-                if self.mode == Mode::Destroy {
-                    destroy::destroy(frame);
-                }
-            })
-            .wrap_err("terminal.draw")?;
-        Ok(())
+    fn draw(&self, frame: &mut Frame) {
+        frame.render_widget(self, frame.area());
+        if self.mode == Mode::Destroy {
+            destroy::destroy(frame);
+        }
     }
 
     /// Handle events from the terminal.
@@ -86,8 +79,11 @@ impl App {
     /// 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<()> {
         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),
+        if !event::poll(timeout)? {
+            return Ok(());
+        }
+        match event::read()? {
+            Event::Key(key) if key.kind == KeyEventKind::Press => self.handle_key_press(key),
             _ => {}
         }
         Ok(())

examples/demo2/errors.rs

@@ -1,18 +0,0 @@
-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

@@ -9,9 +9,9 @@
 //! 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
+//! [Ratatui]: https://github.com/ratatui/ratatui
+//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md
 
 #![allow(
     clippy::missing_errors_doc,
@@ -22,12 +22,18 @@
 mod app;
 mod colors;
 mod destroy;
-mod errors;
 mod tabs;
-mod term;
 mod theme;
 
+use std::io::stdout;
+
+use app::App;
 use color_eyre::Result;
+use crossterm::{
+    execute,
+    terminal::{EnterAlternateScreen, LeaveAlternateScreen},
+};
+use ratatui::{layout::Rect, TerminalOptions, Viewport};
 
 pub use self::{
     colors::{color_from_oklab, RgbSwatch},
@@ -35,9 +41,14 @@ pub use self::{
 };
 
 fn main() -> Result<()> {
-    errors::init_hooks()?;
-    let terminal = &mut term::init()?;
-    app::run(terminal)?;
-    term::restore()?;
-    Ok(())
+    color_eyre::install()?;
+    // 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 viewport = Viewport::Fixed(Rect::new(0, 0, 81, 18));
+    let terminal = ratatui::init_with_options(TerminalOptions { viewport });
+    execute!(stdout(), EnterAlternateScreen).expect("failed to enter alternate screen");
+    let app_result = App::default().run(terminal);
+    execute!(stdout(), LeaveAlternateScreen).expect("failed to leave alternate screen");
+    ratatui::restore();
+    app_result
 }

examples/demo2/tabs/email.rs

@@ -96,13 +96,10 @@ fn render_inbox(selected_index: usize, area: Rect, buf: &mut Buffer) {
         .map(|e| e.from.width())
         .max()
         .unwrap_or_default();
-    let items = EMAILS
-        .iter()
-        .map(|e| {
-            let from = format!("{:width$}", e.from, width = from_width).into();
-            ListItem::new(Line::from(vec![from, " ".into(), e.subject.into()]))
-        })
-        .collect_vec();
+    let items = EMAILS.iter().map(|e| {
+        let from = format!("{:width$}", e.from, width = from_width).into();
+        ListItem::new(Line::from(vec![from, " ".into(), e.subject.into()]))
+    });
     let mut state = ListState::default().with_selected(Some(selected_index));
     StatefulWidget::render(
         List::new(items)

examples/demo2/tabs/traceroute.rs

@@ -52,10 +52,7 @@ impl Widget for TracerouteTab {
 
 fn render_hops(selected_row: usize, area: Rect, buf: &mut Buffer) {
     let mut state = TableState::default().with_selected(Some(selected_row));
-    let rows = HOPS
-        .iter()
-        .map(|hop| Row::new(vec![hop.host, hop.address]))
-        .collect_vec();
+    let rows = HOPS.iter().map(|hop| Row::new(vec![hop.host, hop.address]));
     let block = Block::new()
         .padding(Padding::new(1, 1, 1, 1))
         .title_alignment(Alignment::Center)

examples/demo2/tabs/weather.rs

@@ -88,7 +88,7 @@ fn render_simple_barchart(area: Rect, buf: &mut Buffer) {
             Bar::default()
                 .value(value)
                 // 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
+                // See https://github.com/ratatui/ratatui/issues/513 for more info
                 // (the demo GIFs hack around this by hacking the calculation in bars.rs)
                 .text_value(format!("{value}°"))
                 .style(if value > 70 {

examples/demo2/term.rs

@@ -1,46 +0,0 @@
-use std::{
-    io::{self, stdout},
-    time::Duration,
-};
-
-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, TerminalOptions, Viewport,
-};
-
-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)
-}
-
-pub fn restore() -> Result<()> {
-    disable_raw_mode().context("disable raw mode")?;
-    stdout()
-        .execute(LeaveAlternateScreen)
-        .wrap_err("leave alternate screen")?;
-    Ok(())
-}
-
-pub fn next_event(timeout: Duration) -> Result<Option<Event>> {
-    if !event::poll(timeout)? {
-        return Ok(None);
-    }
-    let event = event::read()?;
-    Ok(Some(event))
-}

examples/docsrs.rs

@@ -9,51 +9,55 @@
 //! 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};
+//! [Ratatui]: https://github.com/ratatui/ratatui
+//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md
 
+use color_eyre::Result;
 use ratatui::{
-    backend::CrosstermBackend,
-    crossterm::{
-        event::{self, Event, KeyCode},
-        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-        ExecutableCommand,
-    },
+    crossterm::event::{self, Event, KeyCode},
     layout::{Constraint, Layout},
     style::{Color, Modifier, Style, Stylize},
     text::{Line, Span, Text},
     widgets::{Block, Borders, Paragraph},
-    Frame, Terminal,
+    DefaultTerminal, Frame,
 };
 
 /// 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.
-fn main() -> io::Result<()> {
-    let arg = std::env::args().nth(1).unwrap_or_default();
-    enable_raw_mode()?;
-    stdout().execute(EnterAlternateScreen)?;
-    let mut terminal = Terminal::new(CrosstermBackend::new(stdout()))?;
+fn main() -> Result<()> {
+    color_eyre::install()?;
+    let first_arg = std::env::args().nth(1).unwrap_or_default();
+    let terminal = ratatui::init();
+    let app_result = run(terminal, &first_arg);
+    ratatui::restore();
+    app_result
+}
 
+fn run(mut terminal: DefaultTerminal, first_arg: &str) -> Result<()> {
     let mut should_quit = false;
     while !should_quit {
-        terminal.draw(match arg.as_str() {
+        terminal.draw(match first_arg {
             "layout" => layout,
             "styling" => styling,
             _ => hello_world,
         })?;
         should_quit = handle_events()?;
     }
-
-    disable_raw_mode()?;
-    stdout().execute(LeaveAlternateScreen)?;
     Ok(())
 }
 
+fn handle_events() -> std::io::Result<bool> {
+    if let Event::Key(key) = event::read()? {
+        if key.kind == event::KeyEventKind::Press && key.code == KeyCode::Char('q') {
+            return Ok(true);
+        }
+    }
+    Ok(false)
+}
+
 fn hello_world(frame: &mut Frame) {
     frame.render_widget(
         Paragraph::new("Hello World!").block(Block::bordered().title("Greeting")),
@@ -61,17 +65,6 @@ fn hello_world(frame: &mut Frame) {
     );
 }
 
-fn handle_events() -> io::Result<bool> {
-    if event::poll(std::time::Duration::from_millis(50))? {
-        if let Event::Key(key) = event::read()? {
-            if key.kind == event::KeyEventKind::Press && key.code == KeyCode::Char('q') {
-                return Ok(true);
-            }
-        }
-    }
-    Ok(false)
-}
-
 fn layout(frame: &mut Frame) {
     let vertical = Layout::vertical([
         Constraint::Length(1),

examples/flex.rs

@@ -9,24 +9,16 @@
 //! 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
+//! [Ratatui]: https://github.com/ratatui/ratatui
+//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md
 
-use std::{
-    io::{self, stdout},
-    num::NonZeroUsize,
-};
+use std::num::NonZeroUsize;
 
-use color_eyre::{config::HookBuilder, Result};
+use color_eyre::Result;
 use ratatui::{
-    backend::{Backend, CrosstermBackend},
     buffer::Buffer,
-    crossterm::{
-        event::{self, Event, KeyCode, KeyEventKind},
-        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-        ExecutableCommand,
-    },
+    crossterm::event::{self, Event, KeyCode, KeyEventKind},
     layout::{
         Alignment,
         Constraint::{self, Fill, Length, Max, Min, Percentage, Ratio},
@@ -39,10 +31,18 @@ use ratatui::{
         block::Title, Block, Paragraph, Scrollbar, ScrollbarOrientation, ScrollbarState,
         StatefulWidget, Tabs, Widget,
     },
-    Terminal,
+    DefaultTerminal,
 };
 use strum::{Display, EnumIter, FromRepr, IntoEnumIterator};
 
+fn main() -> Result<()> {
+    color_eyre::install()?;
+    let terminal = ratatui::init();
+    let app_result = App::default().run(terminal);
+    ratatui::restore();
+    app_result
+}
+
 const EXAMPLE_DATA: &[(&str, &[Constraint])] = &[
     (
         "Min(u16) takes any excess space always",
@@ -157,25 +157,18 @@ enum SelectedTab {
     SpaceBetween,
 }
 
-fn main() -> Result<()> {
-    // assuming the user changes spacing about a 100 times or so
-    Layout::init_cache(
-        NonZeroUsize::new(EXAMPLE_DATA.len() * SelectedTab::iter().len() * 100).unwrap(),
-    );
-    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<()> {
-        self.draw(&mut terminal)?;
+    fn run(mut self, mut terminal: DefaultTerminal) -> Result<()> {
+        // increase the layout cache to account for the number of layout events. This ensures that
+        // layout is not generally reprocessed on every frame (which would lead to possible janky
+        // results when there are more than one possible solution to the requested layout). This
+        // assumes the user changes spacing about a 100 times or so.
+        let cache_size = EXAMPLE_DATA.len() * SelectedTab::iter().len() * 100;
+        Layout::init_cache(NonZeroUsize::new(cache_size).unwrap());
+
         while self.is_running() {
+            terminal.draw(|frame| frame.render_widget(self, frame.area()))?;
             self.handle_events()?;
-            self.draw(&mut terminal)?;
         }
         Ok(())
     }
@@ -184,11 +177,6 @@ impl App {
         self.state == AppState::Running
     }
 
-    fn draw(self, terminal: &mut Terminal<impl Backend>) -> io::Result<()> {
-        terminal.draw(|frame| frame.render_widget(self, frame.area()))?;
-        Ok(())
-    }
-
     fn handle_events(&mut self) -> Result<()> {
         match event::read()? {
             Event::Key(key) if key.kind == KeyEventKind::Press => match key.code {
@@ -532,35 +520,6 @@ const fn color_for_constraint(constraint: Constraint) -> Color {
     }
 }
 
-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(())
-}
-
 #[allow(clippy::cast_possible_truncation)]
 fn get_description_height(s: &str) -> u16 {
     if s.is_empty() {

examples/gauge.rs

@@ -9,26 +9,21 @@
 //! 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
+//! [Ratatui]: https://github.com/ratatui/ratatui
+//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md
 
-use std::{io::stdout, time::Duration};
+use std::time::Duration;
 
-use color_eyre::{config::HookBuilder, Result};
+use color_eyre::Result;
 use ratatui::{
-    backend::{Backend, CrosstermBackend},
     buffer::Buffer,
-    crossterm::{
-        event::{self, Event, KeyCode, KeyEventKind},
-        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-        ExecutableCommand,
-    },
+    crossterm::event::{self, Event, KeyCode, KeyEventKind},
     layout::{Alignment, Constraint, Layout, Rect},
     style::{palette::tailwind, Color, Style, Stylize},
     text::Span,
     widgets::{block::Title, Block, Borders, Gauge, Padding, Paragraph, Widget},
-    Terminal,
+    DefaultTerminal,
 };
 
 const GAUGE1_COLOR: Color = tailwind::RED.c800;
@@ -56,28 +51,23 @@ enum AppState {
 }
 
 fn main() -> Result<()> {
-    init_error_hooks()?;
-    let terminal = init_terminal()?;
-    App::default().run(terminal)?;
-    restore_terminal()?;
-    Ok(())
+    color_eyre::install()?;
+    let terminal = ratatui::init();
+    let app_result = App::default().run(terminal);
+    ratatui::restore();
+    app_result
 }
 
 impl App {
-    fn run(&mut self, mut terminal: Terminal<impl Backend>) -> Result<()> {
+    fn run(mut self, mut terminal: DefaultTerminal) -> Result<()> {
         while self.state != AppState::Quitting {
-            self.draw(&mut terminal)?;
+            terminal.draw(|frame| frame.render_widget(&self, frame.area()))?;
             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.area()))?;
-        Ok(())
-    }
-
     fn update(&mut self, terminal_width: u16) {
         if self.state != AppState::Started {
             return;
@@ -213,32 +203,3 @@ fn title_block(title: &str) -> Block {
         .title(title)
         .fg(CUSTOM_LABEL_COLOR)
 }
-
-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

@@ -9,25 +9,17 @@
 //! 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
+//! [Ratatui]: https://github.com/ratatui/ratatui
+//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md
 
-use std::{
-    io::{self, Stdout},
-    time::Duration,
-};
+use std::time::Duration;
 
 use color_eyre::{eyre::Context, Result};
 use ratatui::{
-    backend::CrosstermBackend,
-    crossterm::{
-        event::{self, Event, KeyCode},
-        execute,
-        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-    },
+    crossterm::event::{self, Event, KeyCode},
     widgets::Paragraph,
-    Frame, Terminal,
+    DefaultTerminal, Frame,
 };
 
 /// This is a bare minimum example. There are many approaches to running an application loop, so
@@ -38,50 +30,19 @@ use ratatui::{
 /// and exits when the user presses 'q'.
 fn main() -> Result<()> {
     color_eyre::install()?; // augment errors / panics with easy to read messages
-    let mut terminal = init_terminal().context("setup failed")?;
-    let result = run(&mut terminal).context("app loop failed");
-    restore_terminal();
-    result
-}
-
-/// Setup the terminal. This is where you would enable raw mode, enter the alternate screen, and
-/// hide the cursor. This example does not handle errors.
-fn init_terminal() -> Result<Terminal<CrosstermBackend<Stdout>>> {
-    set_panic_hook();
-    let mut stdout = io::stdout();
-    enable_raw_mode().context("failed to enable raw mode")?;
-    execute!(stdout, EnterAlternateScreen).context("unable to enter alternate screen")?;
-    Terminal::new(CrosstermBackend::new(stdout)).context("creating terminal failed")
-}
-
-/// Restore the terminal. This is where you disable raw mode, leave the alternate screen, and show
-/// the cursor.
-fn restore_terminal() {
-    // There's not a lot we can do if these fail, so we just print an error message.
-    if let Err(err) = disable_raw_mode() {
-        eprintln!("Error disabling raw mode: {err}");
-    }
-    if let Err(err) = execute!(io::stdout(), LeaveAlternateScreen) {
-        eprintln!("Error leaving alternate screen: {err}");
-    }
-}
-
-/// Replace the default panic hook with one that restores the terminal before panicking.
-fn set_panic_hook() {
-    let hook = std::panic::take_hook();
-    std::panic::set_hook(Box::new(move |panic_info| {
-        restore_terminal();
-        hook(panic_info);
-    }));
+    let terminal = ratatui::init();
+    let app_result = run(terminal).context("app loop failed");
+    ratatui::restore();
+    app_result
 }
 
 /// Run the application loop. This is where you would handle events and update the application
 /// state. This example exits when the user presses 'q'. Other styles of application loops are
 /// possible, for example, you could have multiple application states and switch between them based
 /// on events, or you could have a single application state and update it based on events.
-fn run(terminal: &mut Terminal<CrosstermBackend<Stdout>>) -> Result<()> {
+fn run(mut terminal: DefaultTerminal) -> Result<()> {
     loop {
-        terminal.draw(render_app)?;
+        terminal.draw(draw)?;
         if should_quit()? {
             break;
         }
@@ -89,19 +50,18 @@ fn run(terminal: &mut Terminal<CrosstermBackend<Stdout>>) -> Result<()> {
     Ok(())
 }
 
-/// Render the application. This is where you would draw the application UI. This example just
-/// draws a greeting.
-fn render_app(frame: &mut Frame) {
+/// Render the application. This is where you would draw the application UI. This example draws a
+/// greeting.
+fn draw(frame: &mut Frame) {
     let greeting = Paragraph::new("Hello World! (press 'q' to quit)");
     frame.render_widget(greeting, frame.area());
 }
 
 /// Check if the user has pressed 'q'. This is where you would handle events. This example just
 /// checks if the user has pressed 'q' and returns true if they have. It does not handle any other
-/// events. There is a 250ms timeout on the event poll so that the application can exit in a timely
-/// manner, and to ensure that the terminal is rendered at least once every 250ms. This allows you
-/// to do other work in the application loop, such as updating the application state, without
-/// blocking the event loop for too long.
+/// events. There is a 250ms timeout on the event poll to ensure that the terminal is rendered at
+/// least once every 250ms. This allows you to do other work in the application loop, such as
+/// updating the application state, without blocking the event loop for too long.
 fn should_quit() -> Result<bool> {
     if event::poll(Duration::from_millis(250)).context("event poll failed")? {
         if let Event::Key(key) = event::read().context("event read failed")? {

examples/hyperlink.rs

@@ -12,35 +12,28 @@
 //! 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
+//! [Ratatui]: https://github.com/ratatui/ratatui
+//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui/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 color_eyre::Result;
 use itertools::Itertools;
-use ratatui::{prelude::*, widgets::WidgetRef};
+use ratatui::{
+    buffer::Buffer,
+    crossterm::event::{self, Event, KeyCode},
+    layout::Rect,
+    style::Stylize,
+    text::{Line, Text},
+    widgets::Widget,
+    DefaultTerminal,
+};
 
 fn main() -> Result<()> {
-    init_error_handling()?;
-    let mut terminal = init_terminal()?;
-    let app = App::new();
-    app.run(&mut terminal)?;
-    restore_terminal()?;
-    Ok(())
+    color_eyre::install()?;
+    let terminal = ratatui::init();
+    let app_result = App::new().run(terminal);
+    ratatui::restore();
+    app_result
 }
 
 struct App {
@@ -54,7 +47,7 @@ impl App {
         Self { hyperlink }
     }
 
-    fn run(self, terminal: &mut Terminal<CrosstermBackend<Stdout>>) -> io::Result<()> {
+    fn run(self, mut terminal: DefaultTerminal) -> Result<()> {
         loop {
             terminal.draw(|frame| frame.render_widget(&self.hyperlink, frame.area()))?;
             if let Event::Key(key) = event::read()? {
@@ -84,11 +77,11 @@ impl<'content> Hyperlink<'content> {
     }
 }
 
-impl WidgetRef for Hyperlink<'_> {
-    fn render_ref(&self, area: Rect, buffer: &mut Buffer) {
-        self.text.render_ref(area, buffer);
+impl Widget for &Hyperlink<'_> {
+    fn render(self, area: Rect, buffer: &mut Buffer) {
+        (&self.text).render(area, buffer);
 
-        // this is a hacky workaround for https://github.com/ratatui-org/ratatui/issues/902, a bug
+        // this is a hacky workaround for https://github.com/ratatui/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.
@@ -106,44 +99,3 @@ impl WidgetRef for Hyperlink<'_> {
         }
     }
 }
-
-/// 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

@@ -9,22 +9,22 @@
 //! 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
+//! [Ratatui]: https://github.com/ratatui/ratatui
+//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md
 
 use std::{
     collections::{BTreeMap, VecDeque},
-    error::Error,
-    io,
     sync::mpsc,
     thread,
     time::{Duration, Instant},
 };
 
+use color_eyre::Result;
 use rand::distributions::{Distribution, Uniform};
 use ratatui::{
-    backend::{Backend, CrosstermBackend},
+    backend::Backend,
+    crossterm::event,
     layout::{Alignment, Constraint, Layout, Rect},
     style::{Color, Modifier, Style},
     symbols,
@@ -33,19 +33,40 @@ use ratatui::{
     Frame, Terminal, TerminalOptions, Viewport,
 };
 
+fn main() -> Result<()> {
+    color_eyre::install()?;
+    let mut terminal = ratatui::init_with_options(TerminalOptions {
+        viewport: Viewport::Inline(8),
+    });
+
+    let (tx, rx) = mpsc::channel();
+    input_handling(tx.clone());
+    let workers = workers(tx);
+    let mut downloads = downloads();
+
+    for w in &workers {
+        let d = downloads.next(w.id).unwrap();
+        w.tx.send(d).unwrap();
+    }
+
+    let app_result = run(&mut terminal, workers, downloads, rx);
+
+    ratatui::restore();
+
+    app_result
+}
+
 const NUM_DOWNLOADS: usize = 10;
 
 type DownloadId = usize;
 type WorkerId = usize;
-
 enum Event {
-    Input(crossterm::event::KeyEvent),
+    Input(event::KeyEvent),
     Tick,
     Resize,
     DownloadUpdate(WorkerId, DownloadId, f64),
     DownloadDone(WorkerId, DownloadId),
 }
-
 struct Downloads {
     pending: VecDeque<Download>,
     in_progress: BTreeMap<WorkerId, DownloadInProgress>,
@@ -69,52 +90,20 @@ impl Downloads {
         }
     }
 }
-
 struct DownloadInProgress {
     id: DownloadId,
     started_at: Instant,
     progress: f64,
 }
-
 struct Download {
     id: DownloadId,
     size: usize,
 }
-
 struct Worker {
     id: WorkerId,
     tx: mpsc::Sender<Download>,
 }
 
-fn main() -> Result<(), Box<dyn Error>> {
-    crossterm::terminal::enable_raw_mode()?;
-    let stdout = io::stdout();
-    let backend = CrosstermBackend::new(stdout);
-    let mut terminal = Terminal::with_options(
-        backend,
-        TerminalOptions {
-            viewport: Viewport::Inline(8),
-        },
-    )?;
-
-    let (tx, rx) = mpsc::channel();
-    input_handling(tx.clone());
-    let workers = workers(tx);
-    let mut downloads = downloads();
-
-    for w in &workers {
-        let d = downloads.next(w.id).unwrap();
-        w.tx.send(d).unwrap();
-    }
-
-    run_app(&mut terminal, workers, downloads, rx)?;
-
-    crossterm::terminal::disable_raw_mode()?;
-    terminal.clear()?;
-
-    Ok(())
-}
-
 fn input_handling(tx: mpsc::Sender<Event>) {
     let tick_rate = Duration::from_millis(200);
     thread::spawn(move || {
@@ -122,10 +111,10 @@ fn input_handling(tx: mpsc::Sender<Event>) {
         loop {
             // poll for tick rate duration, if no events, sent tick event.
             let timeout = tick_rate.saturating_sub(last_tick.elapsed());
-            if crossterm::event::poll(timeout).unwrap() {
-                match crossterm::event::read().unwrap() {
-                    crossterm::event::Event::Key(key) => tx.send(Event::Input(key)).unwrap(),
-                    crossterm::event::Event::Resize(_, _) => tx.send(Event::Resize).unwrap(),
+            if event::poll(timeout).unwrap() {
+                match event::read().unwrap() {
+                    event::Event::Key(key) => tx.send(Event::Input(key)).unwrap(),
+                    event::Event::Resize(_, _) => tx.send(Event::Resize).unwrap(),
                     _ => {}
                 };
             }
@@ -178,22 +167,22 @@ fn downloads() -> Downloads {
 }
 
 #[allow(clippy::needless_pass_by_value)]
-fn run_app<B: Backend>(
-    terminal: &mut Terminal<B>,
+fn run(
+    terminal: &mut Terminal<impl Backend>,
     workers: Vec<Worker>,
     mut downloads: Downloads,
     rx: mpsc::Receiver<Event>,
-) -> Result<(), Box<dyn Error>> {
+) -> Result<()> {
     let mut redraw = true;
     loop {
         if redraw {
-            terminal.draw(|f| ui(f, &downloads))?;
+            terminal.draw(|frame| draw(frame, &downloads))?;
         }
         redraw = true;
 
         match rx.recv()? {
             Event::Input(event) => {
-                if event.code == crossterm::event::KeyCode::Char('q') {
+                if event.code == event::KeyCode::Char('q') {
                     break;
                 }
             }
@@ -239,11 +228,11 @@ fn run_app<B: Backend>(
     Ok(())
 }
 
-fn ui(f: &mut Frame, downloads: &Downloads) {
-    let area = f.area();
+fn draw(frame: &mut Frame, downloads: &Downloads) {
+    let area = frame.area();
 
     let block = Block::new().title(block::Title::from("Progress").alignment(Alignment::Center));
-    f.render_widget(block, area);
+    frame.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)]);
@@ -257,7 +246,7 @@ fn ui(f: &mut Frame, downloads: &Downloads) {
         .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);
+    frame.render_widget(progress, progress_area);
 
     // in progress downloads
     let items: Vec<ListItem> = downloads
@@ -280,7 +269,7 @@ fn ui(f: &mut Frame, downloads: &Downloads) {
         })
         .collect();
     let list = List::new(items);
-    f.render_widget(list, list_area);
+    frame.render_widget(list, list_area);
 
     #[allow(clippy::cast_possible_truncation)]
     for (i, (_, download)) in downloads.in_progress.iter().enumerate() {
@@ -290,7 +279,7 @@ fn ui(f: &mut Frame, downloads: &Downloads) {
         if gauge_area.top().saturating_add(i as u16) > area.bottom() {
             continue;
         }
-        f.render_widget(
+        frame.render_widget(
             gauge,
             Rect {
                 x: gauge_area.left(),

examples/layout.rs

@@ -9,72 +9,44 @@
 //! 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};
+//! [Ratatui]: https://github.com/ratatui/ratatui
+//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md
 
 use itertools::Itertools;
 use ratatui::{
-    backend::{Backend, CrosstermBackend},
-    crossterm::{
-        event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode},
-        execute,
-        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-    },
+    crossterm::event::{self, Event, KeyCode, KeyEventKind},
     layout::{
-        Constraint,
-        Constraint::{Length, Max, Min, Percentage, Ratio},
+        Constraint::{self, Length, Max, Min, Percentage, Ratio},
         Layout, Rect,
     },
     style::{Color, Style, Stylize},
     text::Line,
     widgets::{Block, Paragraph},
-    Frame, Terminal,
+    DefaultTerminal, Frame,
 };
 
-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 res = run_app(&mut terminal);
-
-    // restore terminal
-    disable_raw_mode()?;
-    execute!(
-        terminal.backend_mut(),
-        LeaveAlternateScreen,
-        DisableMouseCapture
-    )?;
-    terminal.show_cursor()?;
-
-    if let Err(err) = res {
-        println!("{err:?}");
-    }
-
-    Ok(())
+fn main() -> color_eyre::Result<()> {
+    color_eyre::install()?;
+    let terminal = ratatui::init();
+    let app_result = run(terminal);
+    ratatui::restore();
+    app_result
 }
 
-fn run_app<B: Backend>(terminal: &mut Terminal<B>) -> io::Result<()> {
+fn run(mut terminal: DefaultTerminal) -> color_eyre::Result<()> {
     loop {
-        terminal.draw(ui)?;
-
+        terminal.draw(draw)?;
         if let Event::Key(key) = event::read()? {
-            if key.code == KeyCode::Char('q') {
-                return Ok(());
+            if key.kind == KeyEventKind::Press && key.code == KeyCode::Char('q') {
+                break Ok(());
             }
         }
     }
 }
 
 #[allow(clippy::too_many_lines)]
-fn ui(frame: &mut Frame) {
+fn draw(frame: &mut Frame) {
     let vertical = Layout::vertical([
         Length(4),  // text
         Length(50), // examples
@@ -102,31 +74,28 @@ fn ui(frame: &mut Frame) {
         Min(0), // fills remaining space
     ])
     .split(examples_area);
-    let example_areas = example_rows
+    let example_areas = example_rows.iter().flat_map(|area| {
+        Layout::horizontal([
+            Length(14),
+            Length(14),
+            Length(14),
+            Length(14),
+            Length(14),
+            Min(0), // fills remaining space
+        ])
+        .split(*area)
         .iter()
-        .flat_map(|area| {
-            Layout::horizontal([
-                Length(14),
-                Length(14),
-                Length(14),
-                Length(14),
-                Length(14),
-                Min(0), // fills remaining space
-            ])
-            .split(*area)
-            .iter()
-            .copied()
-            .take(5) // ignore Min(0)
-            .collect_vec()
-        })
-        .collect_vec();
+        .copied()
+        .take(5) // ignore Min(0)
+        .collect_vec()
+    });
 
     // the examples are a cartesian product of the following constraints
     // e.g. Len/Len, Len/Min, Len/Max, Len/Perc, Len/Ratio, Min/Len, Min/Min, ...
     let examples = [
         (
             "Len",
-            vec![
+            [
                 Length(0),
                 Length(2),
                 Length(3),
@@ -135,17 +104,11 @@ fn ui(frame: &mut Frame) {
                 Length(15),
             ],
         ),
-        (
-            "Min",
-            vec![Min(0), Min(2), Min(3), Min(6), Min(10), Min(15)],
-        ),
-        (
-            "Max",
-            vec![Max(0), Max(2), Max(3), Max(6), Max(10), Max(15)],
-        ),
+        ("Min", [Min(0), Min(2), Min(3), Min(6), Min(10), Min(15)]),
+        ("Max", [Max(0), Max(2), Max(3), Max(6), Max(10), Max(15)]),
         (
             "Perc",
-            vec![
+            [
                 Percentage(0),
                 Percentage(25),
                 Percentage(50),
@@ -156,7 +119,7 @@ fn ui(frame: &mut Frame) {
         ),
         (
             "Ratio",
-            vec![
+            [
                 Ratio(0, 4),
                 Ratio(1, 4),
                 Ratio(2, 4),
@@ -167,24 +130,15 @@ fn ui(frame: &mut Frame) {
         ),
     ];
 
-    for (i, (a, b)) in examples
+    for ((a, b), area) in examples
         .iter()
         .cartesian_product(examples.iter())
-        .enumerate()
+        .zip(example_areas)
     {
         let (name_a, examples_a) = a;
         let (name_b, examples_b) = b;
-        let constraints = examples_a
-            .iter()
-            .copied()
-            .zip(examples_b.iter().copied())
-            .collect_vec();
-        render_example_combination(
-            frame,
-            example_areas[i],
-            &format!("{name_a}/{name_b}"),
-            constraints,
-        );
+        let constraints = examples_a.iter().copied().zip(examples_b.iter().copied());
+        render_example_combination(frame, area, &format!("{name_a}/{name_b}"), constraints);
     }
 }
 
@@ -193,7 +147,7 @@ fn render_example_combination(
     frame: &mut Frame,
     area: Rect,
     title: &str,
-    constraints: Vec<(Constraint, Constraint)>,
+    constraints: impl ExactSizeIterator<Item = (Constraint, Constraint)>,
 ) {
     let block = Block::bordered()
         .title(title.gray())
@@ -202,8 +156,8 @@ fn render_example_combination(
     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.into_iter().enumerate() {
-        render_single_example(frame, layout[i], vec![a, b, Min(0)]);
+    for ((a, b), &area) in constraints.into_iter().zip(layout.iter()) {
+        render_single_example(frame, area, vec![a, b, Min(0)]);
     }
     // This is to make it easy to visually see the alignment of the examples
     // with the constraints.

examples/line_gauge.rs

@@ -9,29 +9,32 @@
 //! 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
+//! [Ratatui]: https://github.com/ratatui/ratatui
+//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md
 
-use std::{io::stdout, time::Duration};
+use std::time::Duration;
 
-use color_eyre::{config::HookBuilder, Result};
+use color_eyre::Result;
 use ratatui::{
-    backend::{Backend, CrosstermBackend},
     buffer::Buffer,
-    crossterm::{
-        event::{self, Event, KeyCode, KeyEventKind},
-        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-        ExecutableCommand,
-    },
+    crossterm::event::{self, Event, KeyCode, KeyEventKind},
     layout::{Alignment, Constraint, Layout, Rect},
     style::{palette::tailwind, Color, Style, Stylize},
     widgets::{block::Title, Block, Borders, LineGauge, Padding, Paragraph, Widget},
-    Terminal,
+    DefaultTerminal,
 };
 
 const CUSTOM_LABEL_COLOR: Color = tailwind::SLATE.c200;
 
+fn main() -> Result<()> {
+    color_eyre::install()?;
+    let terminal = ratatui::init();
+    let app_result = App::default().run(terminal);
+    ratatui::restore();
+    app_result
+}
+
 #[derive(Debug, Default, Clone, Copy)]
 struct App {
     state: AppState,
@@ -47,29 +50,16 @@ enum AppState {
     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<()> {
+    fn run(mut self, mut terminal: DefaultTerminal) -> Result<()> {
         while self.state != AppState::Quitting {
-            self.draw(&mut terminal)?;
+            terminal.draw(|frame| frame.render_widget(&self, frame.area()))?;
             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.area()))?;
-        Ok(())
-    }
-
     fn update(&mut self, terminal_width: u16) {
         if self.state != AppState::Started {
             return;
@@ -187,32 +177,3 @@ fn title_block(title: &str) -> Block {
         .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

@@ -9,17 +9,14 @@
 //! 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
+//! [Ratatui]: https://github.com/ratatui/ratatui
+//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md
 
-use std::{error::Error, io};
-
-use crossterm::event::KeyEvent;
+use color_eyre::Result;
 use ratatui::{
-    backend::Backend,
     buffer::Buffer,
-    crossterm::event::{self, Event, KeyCode, KeyEventKind},
+    crossterm::event::{self, Event, KeyCode, KeyEvent, KeyEventKind},
     layout::{Constraint, Layout, Rect},
     style::{
         palette::tailwind::{BLUE, GREEN, SLATE},
@@ -31,7 +28,7 @@ use ratatui::{
         Block, Borders, HighlightSpacing, List, ListItem, ListState, Padding, Paragraph,
         StatefulWidget, Widget, Wrap,
     },
-    Terminal,
+    DefaultTerminal,
 };
 
 const TODO_HEADER_STYLE: Style = Style::new().fg(SLATE.c100).bg(BLUE.c800);
@@ -41,15 +38,12 @@ const SELECTED_STYLE: Style = Style::new().bg(SLATE.c800).add_modifier(Modifier:
 const TEXT_FG_COLOR: Color = SLATE.c200;
 const COMPLETED_TEXT_FG_COLOR: Color = GREEN.c500;
 
-fn main() -> Result<(), Box<dyn Error>> {
-    tui::init_error_hooks()?;
-    let terminal = tui::init_terminal()?;
-
-    let mut app = App::default();
-    app.run(terminal)?;
-
-    tui::restore_terminal()?;
-    Ok(())
+fn main() -> Result<()> {
+    color_eyre::install()?;
+    let terminal = ratatui::init();
+    let app_result = App::default().run(terminal);
+    ratatui::restore();
+    app_result
 }
 
 /// This struct holds the current state of the app. In particular, it has the `todo_list` field
@@ -119,9 +113,9 @@ impl TodoItem {
 }
 
 impl App {
-    fn run(&mut self, mut terminal: Terminal<impl Backend>) -> io::Result<()> {
+    fn run(mut self, mut terminal: DefaultTerminal) -> Result<()> {
         while !self.should_exit {
-            terminal.draw(|f| f.render_widget(&mut *self, f.area()))?;
+            terminal.draw(|frame| frame.render_widget(&mut self, frame.area()))?;
             if let Event::Key(key) = event::read()? {
                 self.handle_key(key);
             };
@@ -291,45 +285,3 @@ impl From<&TodoItem> for ListItem<'_> {
         ListItem::new(line)
     }
 }
-
-mod tui {
-    use std::{io, io::stdout};
-
-    use color_eyre::config::HookBuilder;
-    use ratatui::{
-        backend::{Backend, CrosstermBackend},
-        crossterm::{
-            terminal::{
-                disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen,
-            },
-            ExecutableCommand,
-        },
-        Terminal,
-    };
-
-    pub fn init_error_hooks() -> color_eyre::Result<()> {
-        let (panic, error) = HookBuilder::default().into_hooks();
-        let panic = panic.into_panic_hook();
-        let error = error.into_eyre_hook();
-        color_eyre::eyre::set_hook(Box::new(move |e| {
-            let _ = restore_terminal();
-            error(e)
-        }))?;
-        std::panic::set_hook(Box::new(move |info| {
-            let _ = restore_terminal();
-            panic(info);
-        }));
-        Ok(())
-    }
-
-    pub fn init_terminal() -> io::Result<Terminal<impl Backend>> {
-        stdout().execute(EnterAlternateScreen)?;
-        enable_raw_mode()?;
-        Terminal::new(CrosstermBackend::new(stdout()))
-    }
-
-    pub fn restore_terminal() -> io::Result<()> {
-        stdout().execute(LeaveAlternateScreen)?;
-        disable_raw_mode()
-    }
-}

examples/minimal.rs

@@ -1,5 +1,12 @@
 //! # [Ratatui] Minimal example
 //!
+//! 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
+//!
 //! 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
@@ -9,40 +16,25 @@
 //! 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
+//! [Ratatui]: https://github.com/ratatui/ratatui
+//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md
 
 use ratatui::{
-    backend::CrosstermBackend,
-    crossterm::{
-        event::{self, Event, KeyCode, KeyEventKind},
-        execute,
-        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-    },
+    crossterm::event::{self, Event},
     text::Text,
-    Terminal,
+    Frame,
 };
 
-/// 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 mut terminal = Terminal::new(CrosstermBackend::new(std::io::stdout()))?;
-    enable_raw_mode()?;
-    execute!(terminal.backend_mut(), EnterAlternateScreen)?;
+fn main() {
+    let mut terminal = ratatui::init();
     loop {
-        terminal.draw(|frame| frame.render_widget(Text::raw("Hello World!"), frame.area()))?;
-        if let Event::Key(key) = event::read()? {
-            if key.kind == KeyEventKind::Press && key.code == KeyCode::Char('q') {
-                break;
-            }
+        terminal
+            .draw(|frame: &mut Frame| frame.render_widget(Text::raw("Hello World!"), frame.area()))
+            .expect("failed to draw frame");
+        if matches!(event::read().expect("failed to read event"), Event::Key(_)) {
+            break;
         }
     }
-    disable_raw_mode()?;
-    execute!(terminal.backend_mut(), LeaveAlternateScreen)?;
-    Ok(())
+    ratatui::restore();
 }

examples/modifiers.rs

@@ -9,64 +9,48 @@
 //! 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
+//! [Ratatui]: https://github.com/ratatui/ratatui
+//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui/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},
-    iter::once,
-    result,
-    time::Duration,
-};
+use std::{error::Error, iter::once, result};
 
 use itertools::Itertools;
 use ratatui::{
-    backend::{Backend, CrosstermBackend},
-    crossterm::{
-        event::{self, Event, KeyCode},
-        execute,
-        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-    },
+    crossterm::event::{self, Event, KeyCode, KeyEventKind},
     layout::{Constraint, Layout},
     style::{Color, Modifier, Style, Stylize},
     text::Line,
     widgets::Paragraph,
-    Frame, Terminal,
+    DefaultTerminal, Frame,
 };
 
 type Result<T> = result::Result<T, Box<dyn Error>>;
 
 fn main() -> Result<()> {
-    let mut terminal = setup_terminal()?;
-    let res = run_app(&mut terminal);
-    restore_terminal(terminal)?;
-    if let Err(err) = res {
-        eprintln!("{err:?}");
-    }
-    Ok(())
+    color_eyre::install()?;
+    let terminal = ratatui::init();
+    let app_result = run(terminal);
+    ratatui::restore();
+    app_result
 }
 
-fn run_app<B: Backend>(terminal: &mut Terminal<B>) -> io::Result<()> {
+fn run(mut terminal: DefaultTerminal) -> Result<()> {
     loop {
-        terminal.draw(ui)?;
-
-        if event::poll(Duration::from_millis(250))? {
-            if let Event::Key(key) = event::read()? {
-                if key.code == KeyCode::Char('q') {
-                    return Ok(());
-                }
+        terminal.draw(draw)?;
+        if let Event::Key(key) = event::read()? {
+            if key.kind == KeyEventKind::Press && key.code == KeyCode::Char('q') {
+                return Ok(());
             }
         }
     }
 }
 
-fn ui(frame: &mut Frame) {
+fn draw(frame: &mut Frame) {
     let vertical = Layout::vertical([Constraint::Length(1), Constraint::Min(0)]);
     let [text_area, main_area] = vertical.areas(frame.area());
     frame.render_widget(
@@ -114,20 +98,3 @@ fn ui(frame: &mut Frame) {
         }
     }
 }
-
-fn setup_terminal() -> Result<Terminal<CrosstermBackend<Stdout>>> {
-    enable_raw_mode()?;
-    let mut stdout = io::stdout();
-    execute!(stdout, EnterAlternateScreen)?;
-    let backend = CrosstermBackend::new(stdout);
-    let mut terminal = Terminal::new(backend)?;
-    terminal.hide_cursor()?;
-    Ok(terminal)
-}
-
-fn restore_terminal(mut terminal: Terminal<CrosstermBackend<Stdout>>) -> Result<()> {
-    disable_raw_mode()?;
-    execute!(terminal.backend_mut(), LeaveAlternateScreen)?;
-    terminal.show_cursor()?;
-    Ok(())
-}

examples/panic.rs

@@ -9,144 +9,102 @@
 //! 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.
+//! [Ratatui]: https://github.com/ratatui/ratatui
+//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md
 //!
-//! When exiting normally or when handling `Result::Err`, we can reset the
-//! terminal manually at the end of `main` just before we print the error.
+//! Prior to Ratatui 0.28.1, a panic hook had to be manually set up to ensure that the terminal was
+//! reset when a panic occurred. This was necessary because a panic would interrupt the normal
+//! control flow and leave the terminal in a distorted state.
 //!
-//! Because a panic interrupts the normal control flow, manually resetting the
-//! terminal at the end of `main` won't do us any good. Instead, we need to
-//! make sure to set up a panic hook that first resets the terminal before
-//! handling the panic. This both reuses the standard panic hook to ensure a
-//! consistent panic handling UX and properly resets the terminal to not
-//! distort the output.
+//! Starting with Ratatui 0.28.1, the panic hook is automatically set up by the new `ratatui::init`
+//! function, so you no longer need to manually set up the panic hook. This example now demonstrates
+//! how the panic hook acts when it is enabled by default.
 //!
-//! That's why this example is set up to show both situations, with and without
-//! the chained panic hook, to see the difference.
-
-use std::{error::Error, io};
+//! When exiting normally or when handling `Result::Err`, we can reset the terminal manually at the
+//! end of `main` just before we print the error.
+//!
+//! Because a panic interrupts the normal control flow, manually resetting the terminal at the end
+//! of `main` won't do us any good. Instead, we need to make sure to set up a panic hook that first
+//! resets the terminal before handling the panic. This both reuses the standard panic hook to
+//! ensure a consistent panic handling UX and properly resets the terminal to not distort the
+//! output.
+//!
+//! That's why this example is set up to show both situations, with and without the panic hook, to
+//! see the difference.
+//!
+//! For more information on how to set this up manually, see the [Color Eyre recipe] in the Ratatui
+//! website.
+//!
+//! [Color Eyre recipe]: https://ratatui.rs/recipes/apps/color-eyre
 
+use color_eyre::{eyre::bail, Result};
 use ratatui::{
-    backend::{Backend, CrosstermBackend},
-    crossterm::{
-        event::{self, Event, KeyCode},
-        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-    },
+    crossterm::event::{self, Event, KeyCode},
     text::Line,
     widgets::{Block, Paragraph},
-    Frame, Terminal,
+    DefaultTerminal, Frame,
 };
 
-type Result<T> = std::result::Result<T, Box<dyn Error>>;
-
-#[derive(Default)]
+fn main() -> Result<()> {
+    color_eyre::install()?;
+    let terminal = ratatui::init();
+    let app_result = App::new().run(terminal);
+    ratatui::restore();
+    app_result
+}
 struct App {
     hook_enabled: bool,
 }
 
 impl App {
-    fn chain_hook(&mut self) {
-        let original_hook = std::panic::take_hook();
-
-        std::panic::set_hook(Box::new(move |panic| {
-            reset_terminal().unwrap();
-            original_hook(panic);
-        }));
-
-        self.hook_enabled = true;
-    }
-}
-
-fn main() -> Result<()> {
-    let mut terminal = init_terminal()?;
-
-    let mut app = App::default();
-    let res = run_tui(&mut terminal, &mut app);
-
-    reset_terminal()?;
-
-    if let Err(err) = res {
-        println!("{err:?}");
+    const fn new() -> Self {
+        Self { hook_enabled: true }
     }
 
-    Ok(())
-}
+    fn run(mut self, mut terminal: DefaultTerminal) -> Result<()> {
+        loop {
+            terminal.draw(|frame| self.draw(frame))?;
 
-/// Initializes the terminal.
-fn init_terminal() -> Result<Terminal<CrosstermBackend<io::Stdout>>> {
-    crossterm::execute!(io::stdout(), EnterAlternateScreen)?;
-    enable_raw_mode()?;
-
-    let backend = CrosstermBackend::new(io::stdout());
-
-    let mut terminal = Terminal::new(backend)?;
-    terminal.hide_cursor()?;
-
-    Ok(terminal)
-}
-
-/// Resets the terminal.
-fn reset_terminal() -> Result<()> {
-    disable_raw_mode()?;
-    crossterm::execute!(io::stdout(), LeaveAlternateScreen)?;
-
-    Ok(())
-}
-
-/// Runs the TUI loop.
-fn run_tui<B: Backend>(terminal: &mut Terminal<B>, app: &mut App) -> io::Result<()> {
-    loop {
-        terminal.draw(|f| ui(f, app))?;
-
-        if let Event::Key(key) = event::read()? {
-            match key.code {
-                KeyCode::Char('p') => {
-                    panic!("intentional demo panic");
-                }
-
-                KeyCode::Char('e') => {
-                    app.chain_hook();
-                }
-
-                _ => {
-                    return Ok(());
+            if let Event::Key(key) = event::read()? {
+                match key.code {
+                    KeyCode::Char('p') => panic!("intentional demo panic"),
+                    KeyCode::Char('e') => bail!("intentional demo error"),
+                    KeyCode::Char('h') => {
+                        let _ = std::panic::take_hook();
+                        self.hook_enabled = false;
+                    }
+                    KeyCode::Char('q') => return Ok(()),
+                    _ => {}
                 }
             }
         }
     }
-}
-
-/// Render the TUI.
-fn ui(f: &mut Frame, app: &App) {
-    let text = vec![
-        if app.hook_enabled {
-            Line::from("HOOK IS CURRENTLY **ENABLED**")
-        } else {
-            Line::from("HOOK IS CURRENTLY **DISABLED**")
-        },
-        Line::from(""),
-        Line::from("press `p` to panic"),
-        Line::from("press `e` to enable the terminal-resetting panic hook"),
-        Line::from("press any other key to quit without panic"),
-        Line::from(""),
-        Line::from("when you panic without the chained hook,"),
-        Line::from("you will likely have to reset your terminal afterwards"),
-        Line::from("with the `reset` command"),
-        Line::from(""),
-        Line::from("with the chained panic hook enabled,"),
-        Line::from("you should see the panic report as you would without ratatui"),
-        Line::from(""),
-        Line::from("try first without the panic handler to see the difference"),
-    ];
-
-    let paragraph = Paragraph::new(text)
-        .block(Block::bordered().title("Panic Handler Demo"))
-        .centered();
-
-    f.render_widget(paragraph, f.area());
+
+    fn draw(&self, frame: &mut Frame) {
+        let text = vec![
+            if self.hook_enabled {
+                Line::from("HOOK IS CURRENTLY **ENABLED**")
+            } else {
+                Line::from("HOOK IS CURRENTLY **DISABLED**")
+            },
+            Line::from(""),
+            Line::from("Press `p` to cause a panic"),
+            Line::from("Press `e` to cause an error"),
+            Line::from("Press `h` to disable the panic hook"),
+            Line::from("Press `q` to quit"),
+            Line::from(""),
+            Line::from("When your app panics without a panic hook, you will likely have to"),
+            Line::from("reset your terminal afterwards with the `reset` command"),
+            Line::from(""),
+            Line::from("Try first with the panic handler enabled, and then with it disabled"),
+            Line::from("to see the difference"),
+        ];
+
+        let paragraph = Paragraph::new(text)
+            .block(Block::bordered().title("Panic Handler Demo"))
+            .centered();
+
+        frame.render_widget(paragraph, frame.area());
+    }
 }

examples/paragraph.rs

@@ -9,34 +9,32 @@
 //! 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
+//! [Ratatui]: https://github.com/ratatui/ratatui
+//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md
 
 use std::{
     io::{self},
     time::{Duration, Instant},
 };
 
-use crossterm::event::KeyEventKind;
+use color_eyre::Result;
 use ratatui::{
     buffer::Buffer,
-    crossterm::event::{self, Event, KeyCode},
+    crossterm::event::{self, Event, KeyCode, KeyEventKind},
     layout::{Constraint, Layout, Rect},
     style::{Color, Stylize},
     text::{Line, Masked, Span},
     widgets::{Block, Paragraph, Widget, Wrap},
+    DefaultTerminal,
 };
 
-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 main() -> Result<()> {
+    color_eyre::install()?;
+    let terminal = ratatui::init();
+    let app_result = App::new().run(terminal);
+    ratatui::restore();
+    app_result
 }
 
 #[derive(Debug)]
@@ -60,9 +58,9 @@ impl App {
     }
 
     /// Run the app until the user exits.
-    fn run(&mut self, terminal: &mut Tui) -> io::Result<()> {
+    fn run(mut self, mut terminal: DefaultTerminal) -> Result<()> {
         while !self.should_exit {
-            self.draw(terminal)?;
+            terminal.draw(|frame| frame.render_widget(&self, frame.area()))?;
             self.handle_events()?;
             if self.last_tick.elapsed() >= Self::TICK_RATE {
                 self.on_tick();
@@ -72,12 +70,6 @@ impl App {
         Ok(())
     }
 
-    /// Draw the app to the terminal.
-    fn draw(&mut self, terminal: &mut Tui) -> io::Result<()> {
-        terminal.draw(|frame| frame.render_widget(self, frame.area()))?;
-        Ok(())
-    }
-
     /// Handle events from the terminal.
     fn handle_events(&mut self) -> io::Result<()> {
         let timeout = Self::TICK_RATE.saturating_sub(self.last_tick.elapsed());
@@ -97,7 +89,7 @@ impl App {
     }
 }
 
-impl Widget for &mut App {
+impl Widget for &App {
     fn render(self, area: Rect, buf: &mut Buffer) {
         let areas = Layout::vertical([Constraint::Max(9); 4]).split(area);
         Paragraph::new(create_lines(area))
@@ -159,73 +151,3 @@ fn create_lines(area: Rect) -> Vec<Line<'static>> {
         ]),
     ]
 }
-
-/// A module for common functionality used in the examples.
-mod common {
-    use std::{
-        io::{self, stdout, Stdout},
-        panic,
-    };
-
-    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,
-    };
-
-    // A simple alias for the terminal type used in this example.
-    pub type Tui = Terminal<CrosstermBackend<Stdout>>;
-
-    /// 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)
-    }
-
-    /// 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

@@ -9,122 +9,85 @@
 //! 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
+//! [Ratatui]: https://github.com/ratatui/ratatui
+//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui/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 color_eyre::Result;
 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},
+    crossterm::event::{self, Event, KeyCode, KeyEventKind},
+    layout::{Constraint, Flex, Layout, Rect},
     style::Stylize,
     widgets::{Block, Clear, Paragraph, Wrap},
-    Frame, Terminal,
+    DefaultTerminal, Frame,
 };
 
+fn main() -> Result<()> {
+    color_eyre::install()?;
+    let terminal = ratatui::init();
+    let app_result = App::default().run(terminal);
+    ratatui::restore();
+    app_result
+}
+
+#[derive(Default)]
 struct App {
     show_popup: bool,
 }
 
 impl App {
-    const fn new() -> Self {
-        Self { show_popup: false }
-    }
-}
+    fn run(mut self, mut terminal: DefaultTerminal) -> Result<()> {
+        loop {
+            terminal.draw(|frame| self.draw(frame))?;
 
-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:?}");
-    }
-
-    Ok(())
-}
-
-fn run_app<B: Backend>(terminal: &mut Terminal<B>, mut app: App) -> io::Result<()> {
-    loop {
-        terminal.draw(|f| ui(f, &app))?;
-
-        if let Event::Key(key) = event::read()? {
-            if key.kind == KeyEventKind::Press {
-                match key.code {
-                    KeyCode::Char('q') => return Ok(()),
-                    KeyCode::Char('p') => app.show_popup = !app.show_popup,
-                    _ => {}
+            if let Event::Key(key) = event::read()? {
+                if key.kind == KeyEventKind::Press {
+                    match key.code {
+                        KeyCode::Char('q') => return Ok(()),
+                        KeyCode::Char('p') => self.show_popup = !self.show_popup,
+                        _ => {}
+                    }
                 }
             }
         }
     }
-}
 
-fn ui(f: &mut Frame, app: &App) {
-    let area = f.area();
+    fn draw(&self, frame: &mut Frame) {
+        let area = frame.area();
 
-    let vertical = Layout::vertical([Constraint::Percentage(20), Constraint::Percentage(80)]);
-    let [instructions, content] = vertical.areas(area);
+        let vertical = Layout::vertical([Constraint::Percentage(20), Constraint::Percentage(80)]);
+        let [instructions, content] = vertical.areas(area);
 
-    let text = if app.show_popup {
-        "Press p to close the popup"
-    } else {
-        "Press p to show the popup"
-    };
-    let paragraph = Paragraph::new(text.slow_blink())
-        .centered()
-        .wrap(Wrap { trim: true });
-    f.render_widget(paragraph, instructions);
+        let text = if self.show_popup {
+            "Press p to close the popup"
+        } else {
+            "Press p to show the popup"
+        };
+        let paragraph = Paragraph::new(text.slow_blink())
+            .centered()
+            .wrap(Wrap { trim: true });
+        frame.render_widget(paragraph, instructions);
 
-    let block = Block::bordered().title("Content").on_blue();
-    f.render_widget(block, content);
+        let block = Block::bordered().title("Content").on_blue();
+        frame.render_widget(block, content);
 
-    if app.show_popup {
-        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);
+        if self.show_popup {
+            let block = Block::bordered().title("Popup");
+            let area = popup_area(area, 60, 20);
+            frame.render_widget(Clear, area); //this clears out the background
+            frame.render_widget(block, area);
+        }
     }
 }
 
 /// helper function to create a centered rect using up certain percentage of the available rect `r`
-fn centered_rect(percent_x: u16, percent_y: u16, r: Rect) -> Rect {
-    let popup_layout = Layout::vertical([
-        Constraint::Percentage((100 - percent_y) / 2),
-        Constraint::Percentage(percent_y),
-        Constraint::Percentage((100 - percent_y) / 2),
-    ])
-    .split(r);
-
-    Layout::horizontal([
-        Constraint::Percentage((100 - percent_x) / 2),
-        Constraint::Percentage(percent_x),
-        Constraint::Percentage((100 - percent_x) / 2),
-    ])
-    .split(popup_layout[1])[1]
+fn popup_area(area: Rect, percent_x: u16, percent_y: u16) -> Rect {
+    let vertical = Layout::vertical([Constraint::Percentage(percent_y)]).flex(Flex::Center);
+    let horizontal = Layout::horizontal([Constraint::Percentage(percent_x)]).flex(Flex::Center);
+    let [area] = vertical.areas(area);
+    let [area] = horizontal.areas(area);
+    area
 }

examples/ratatui-logo.rs

@@ -9,24 +9,19 @@
 //! 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
+//! [Ratatui]: https://github.com/ratatui/ratatui
+//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md
 
 use std::{
-    io::{self, stdout},
+    io::{self},
     thread::sleep,
     time::Duration,
 };
 
 use indoc::indoc;
 use itertools::izip;
-use ratatui::{
-    backend::{Backend, CrosstermBackend},
-    crossterm::terminal::{disable_raw_mode, enable_raw_mode},
-    widgets::Paragraph,
-    Terminal, TerminalOptions, Viewport,
-};
+use ratatui::{widgets::Paragraph, TerminalOptions, Viewport};
 
 /// A fun example of using half block characters to draw a logo
 #[allow(clippy::many_single_char_names)]
@@ -63,23 +58,12 @@ fn logo() -> String {
 }
 
 fn main() -> io::Result<()> {
-    let mut terminal = init()?;
+    let mut terminal = ratatui::init_with_options(TerminalOptions {
+        viewport: Viewport::Inline(3),
+    });
     terminal.draw(|frame| frame.render_widget(Paragraph::new(logo()), frame.area()))?;
     sleep(Duration::from_secs(5));
-    restore()?;
+    ratatui::restore();
     println!();
     Ok(())
 }
-
-fn init() -> io::Result<Terminal<impl Backend>> {
-    enable_raw_mode()?;
-    let options = TerminalOptions {
-        viewport: Viewport::Inline(3),
-    };
-    Terminal::with_options(CrosstermBackend::new(stdout()), options)
-}
-
-fn restore() -> io::Result<()> {
-    disable_raw_mode()?;
-    Ok(())
-}

examples/scrollbar.rs

@@ -9,31 +9,23 @@
 //! 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
+//! [Ratatui]: https://github.com/ratatui/ratatui
+//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md
 
 #![warn(clippy::pedantic)]
 
-use std::{
-    error::Error,
-    io,
-    time::{Duration, Instant},
-};
+use std::time::{Duration, Instant};
 
+use color_eyre::Result;
 use ratatui::{
-    backend::{Backend, CrosstermBackend},
-    crossterm::{
-        event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode},
-        execute,
-        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-    },
+    crossterm::event::{self, Event, KeyCode},
     layout::{Alignment, Constraint, Layout, Margin},
     style::{Color, Style, Stylize},
     symbols::scrollbar,
     text::{Line, Masked, Span},
     widgets::{Block, Paragraph, Scrollbar, ScrollbarOrientation, ScrollbarState},
-    Frame, Terminal,
+    DefaultTerminal, Frame,
 };
 
 #[derive(Default)]
@@ -44,195 +36,176 @@ struct App {
     pub horizontal_scroll: usize,
 }
 
-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::default();
-    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 main() -> Result<()> {
+    color_eyre::install()?;
+    let terminal = ratatui::init();
+    let app_result = App::default().run(terminal);
+    ratatui::restore();
+    app_result
 }
 
-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))?;
+impl App {
+    fn run(mut self, mut terminal: DefaultTerminal) -> Result<()> {
+        let tick_rate = Duration::from_millis(250);
+        let mut last_tick = Instant::now();
+        loop {
+            terminal.draw(|frame| self.draw(frame))?;
 
-        let timeout = tick_rate.saturating_sub(last_tick.elapsed());
-        if crossterm::event::poll(timeout)? {
-            if let Event::Key(key) = event::read()? {
-                match key.code {
-                    KeyCode::Char('q') => return Ok(()),
-                    KeyCode::Char('j') | KeyCode::Down => {
-                        app.vertical_scroll = app.vertical_scroll.saturating_add(1);
-                        app.vertical_scroll_state =
-                            app.vertical_scroll_state.position(app.vertical_scroll);
+            let timeout = tick_rate.saturating_sub(last_tick.elapsed());
+            if event::poll(timeout)? {
+                if let Event::Key(key) = event::read()? {
+                    match key.code {
+                        KeyCode::Char('q') => return Ok(()),
+                        KeyCode::Char('j') | KeyCode::Down => {
+                            self.vertical_scroll = self.vertical_scroll.saturating_add(1);
+                            self.vertical_scroll_state =
+                                self.vertical_scroll_state.position(self.vertical_scroll);
+                        }
+                        KeyCode::Char('k') | KeyCode::Up => {
+                            self.vertical_scroll = self.vertical_scroll.saturating_sub(1);
+                            self.vertical_scroll_state =
+                                self.vertical_scroll_state.position(self.vertical_scroll);
+                        }
+                        KeyCode::Char('h') | KeyCode::Left => {
+                            self.horizontal_scroll = self.horizontal_scroll.saturating_sub(1);
+                            self.horizontal_scroll_state = self
+                                .horizontal_scroll_state
+                                .position(self.horizontal_scroll);
+                        }
+                        KeyCode::Char('l') | KeyCode::Right => {
+                            self.horizontal_scroll = self.horizontal_scroll.saturating_add(1);
+                            self.horizontal_scroll_state = self
+                                .horizontal_scroll_state
+                                .position(self.horizontal_scroll);
+                        }
+                        _ => {}
                     }
-                    KeyCode::Char('k') | KeyCode::Up => {
-                        app.vertical_scroll = app.vertical_scroll.saturating_sub(1);
-                        app.vertical_scroll_state =
-                            app.vertical_scroll_state.position(app.vertical_scroll);
-                    }
-                    KeyCode::Char('h') | KeyCode::Left => {
-                        app.horizontal_scroll = app.horizontal_scroll.saturating_sub(1);
-                        app.horizontal_scroll_state =
-                            app.horizontal_scroll_state.position(app.horizontal_scroll);
-                    }
-                    KeyCode::Char('l') | KeyCode::Right => {
-                        app.horizontal_scroll = app.horizontal_scroll.saturating_add(1);
-                        app.horizontal_scroll_state =
-                            app.horizontal_scroll_state.position(app.horizontal_scroll);
-                    }
-                    _ => {}
                 }
             }
-        }
-        if last_tick.elapsed() >= tick_rate {
-            last_tick = Instant::now();
+            if last_tick.elapsed() >= tick_rate {
+                last_tick = Instant::now();
+            }
         }
     }
-}
-
-#[allow(clippy::too_many_lines, clippy::cast_possible_truncation)]
-fn ui(f: &mut Frame, app: &mut App) {
-    let area = f.area();
-
-    // Words made "loooong" to demonstrate line breaking.
-    let s = "Veeeeeeeeeeeeeeeery    loooooooooooooooooong   striiiiiiiiiiiiiiiiiiiiiiiiiing.   ";
-    let mut long_line = s.repeat(usize::from(area.width) / s.len() + 4);
-    long_line.push('\n');
-
-    let chunks = Layout::vertical([
-        Constraint::Min(1),
-        Constraint::Percentage(25),
-        Constraint::Percentage(25),
-        Constraint::Percentage(25),
-        Constraint::Percentage(25),
-    ])
-    .split(area);
-
-    let text = vec![
-        Line::from("This is a line "),
-        Line::from("This is a line   ".red()),
-        Line::from("This is a line".on_dark_gray()),
-        Line::from("This is a longer line".crossed_out()),
-        Line::from(long_line.clone()),
-        Line::from("This is a line".reset()),
-        Line::from(vec![
-            Span::raw("Masked text: "),
-            Span::styled(Masked::new("password", '*'), Style::new().fg(Color::Red)),
-        ]),
-        Line::from("This is a line "),
-        Line::from("This is a line   ".red()),
-        Line::from("This is a line".on_dark_gray()),
-        Line::from("This is a longer line".crossed_out()),
-        Line::from(long_line.clone()),
-        Line::from("This is a line".reset()),
-        Line::from(vec![
-            Span::raw("Masked text: "),
-            Span::styled(Masked::new("password", '*'), Style::new().fg(Color::Red)),
-        ]),
-    ];
-    app.vertical_scroll_state = app.vertical_scroll_state.content_length(text.len());
-    app.horizontal_scroll_state = app.horizontal_scroll_state.content_length(long_line.len());
-
-    let create_block = |title: &'static str| Block::bordered().gray().title(title.bold());
-
-    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())
-        .gray()
-        .block(create_block("Vertical scrollbar with arrows"))
-        .scroll((app.vertical_scroll as u16, 0));
-    f.render_widget(paragraph, chunks[1]);
-    f.render_stateful_widget(
-        Scrollbar::new(ScrollbarOrientation::VerticalRight)
-            .begin_symbol(Some("↑"))
-            .end_symbol(Some("↓")),
-        chunks[1],
-        &mut app.vertical_scroll_state,
-    );
-
-    let paragraph = Paragraph::new(text.clone())
-        .gray()
-        .block(create_block(
-            "Vertical scrollbar without arrows, without track symbol and mirrored",
-        ))
-        .scroll((app.vertical_scroll as u16, 0));
-    f.render_widget(paragraph, chunks[2]);
-    f.render_stateful_widget(
-        Scrollbar::new(ScrollbarOrientation::VerticalLeft)
-            .symbols(scrollbar::VERTICAL)
-            .begin_symbol(None)
-            .track_symbol(None)
-            .end_symbol(None),
-        chunks[2].inner(Margin {
-            vertical: 1,
-            horizontal: 0,
-        }),
-        &mut app.vertical_scroll_state,
-    );
-
-    let paragraph = Paragraph::new(text.clone())
-        .gray()
-        .block(create_block(
-            "Horizontal scrollbar with only begin arrow & custom thumb symbol",
-        ))
-        .scroll((0, app.horizontal_scroll as u16));
-    f.render_widget(paragraph, chunks[3]);
-    f.render_stateful_widget(
-        Scrollbar::new(ScrollbarOrientation::HorizontalBottom)
-            .thumb_symbol("🬋")
-            .end_symbol(None),
-        chunks[3].inner(Margin {
-            vertical: 0,
-            horizontal: 1,
-        }),
-        &mut app.horizontal_scroll_state,
-    );
-
-    let paragraph = Paragraph::new(text.clone())
-        .gray()
-        .block(create_block(
-            "Horizontal scrollbar without arrows & custom thumb and track symbol",
-        ))
-        .scroll((0, app.horizontal_scroll as u16));
-    f.render_widget(paragraph, chunks[4]);
-    f.render_stateful_widget(
-        Scrollbar::new(ScrollbarOrientation::HorizontalBottom)
-            .thumb_symbol("░")
-            .track_symbol(Some("─")),
-        chunks[4].inner(Margin {
-            vertical: 0,
-            horizontal: 1,
-        }),
-        &mut app.horizontal_scroll_state,
-    );
+
+    #[allow(clippy::too_many_lines, clippy::cast_possible_truncation)]
+    fn draw(&mut self, frame: &mut Frame) {
+        let area = frame.area();
+
+        // Words made "loooong" to demonstrate line breaking.
+        let s =
+            "Veeeeeeeeeeeeeeeery    loooooooooooooooooong   striiiiiiiiiiiiiiiiiiiiiiiiiing.   ";
+        let mut long_line = s.repeat(usize::from(area.width) / s.len() + 4);
+        long_line.push('\n');
+
+        let chunks = Layout::vertical([
+            Constraint::Min(1),
+            Constraint::Percentage(25),
+            Constraint::Percentage(25),
+            Constraint::Percentage(25),
+            Constraint::Percentage(25),
+        ])
+        .split(area);
+
+        let text = vec![
+            Line::from("This is a line "),
+            Line::from("This is a line   ".red()),
+            Line::from("This is a line".on_dark_gray()),
+            Line::from("This is a longer line".crossed_out()),
+            Line::from(long_line.clone()),
+            Line::from("This is a line".reset()),
+            Line::from(vec![
+                Span::raw("Masked text: "),
+                Span::styled(Masked::new("password", '*'), Style::new().fg(Color::Red)),
+            ]),
+            Line::from("This is a line "),
+            Line::from("This is a line   ".red()),
+            Line::from("This is a line".on_dark_gray()),
+            Line::from("This is a longer line".crossed_out()),
+            Line::from(long_line.clone()),
+            Line::from("This is a line".reset()),
+            Line::from(vec![
+                Span::raw("Masked text: "),
+                Span::styled(Masked::new("password", '*'), Style::new().fg(Color::Red)),
+            ]),
+        ];
+        self.vertical_scroll_state = self.vertical_scroll_state.content_length(text.len());
+        self.horizontal_scroll_state = self.horizontal_scroll_state.content_length(long_line.len());
+
+        let create_block = |title: &'static str| Block::bordered().gray().title(title.bold());
+
+        let title = Block::new()
+            .title_alignment(Alignment::Center)
+            .title("Use h j k l or ◄ ▲ ▼ ► to scroll ".bold());
+        frame.render_widget(title, chunks[0]);
+
+        let paragraph = Paragraph::new(text.clone())
+            .gray()
+            .block(create_block("Vertical scrollbar with arrows"))
+            .scroll((self.vertical_scroll as u16, 0));
+        frame.render_widget(paragraph, chunks[1]);
+        frame.render_stateful_widget(
+            Scrollbar::new(ScrollbarOrientation::VerticalRight)
+                .begin_symbol(Some("↑"))
+                .end_symbol(Some("↓")),
+            chunks[1],
+            &mut self.vertical_scroll_state,
+        );
+
+        let paragraph = Paragraph::new(text.clone())
+            .gray()
+            .block(create_block(
+                "Vertical scrollbar without arrows, without track symbol and mirrored",
+            ))
+            .scroll((self.vertical_scroll as u16, 0));
+        frame.render_widget(paragraph, chunks[2]);
+        frame.render_stateful_widget(
+            Scrollbar::new(ScrollbarOrientation::VerticalLeft)
+                .symbols(scrollbar::VERTICAL)
+                .begin_symbol(None)
+                .track_symbol(None)
+                .end_symbol(None),
+            chunks[2].inner(Margin {
+                vertical: 1,
+                horizontal: 0,
+            }),
+            &mut self.vertical_scroll_state,
+        );
+
+        let paragraph = Paragraph::new(text.clone())
+            .gray()
+            .block(create_block(
+                "Horizontal scrollbar with only begin arrow & custom thumb symbol",
+            ))
+            .scroll((0, self.horizontal_scroll as u16));
+        frame.render_widget(paragraph, chunks[3]);
+        frame.render_stateful_widget(
+            Scrollbar::new(ScrollbarOrientation::HorizontalBottom)
+                .thumb_symbol("🬋")
+                .end_symbol(None),
+            chunks[3].inner(Margin {
+                vertical: 0,
+                horizontal: 1,
+            }),
+            &mut self.horizontal_scroll_state,
+        );
+
+        let paragraph = Paragraph::new(text.clone())
+            .gray()
+            .block(create_block(
+                "Horizontal scrollbar without arrows & custom thumb and track symbol",
+            ))
+            .scroll((0, self.horizontal_scroll as u16));
+        frame.render_widget(paragraph, chunks[4]);
+        frame.render_stateful_widget(
+            Scrollbar::new(ScrollbarOrientation::HorizontalBottom)
+                .thumb_symbol("░")
+                .track_symbol(Some("─")),
+            chunks[4].inner(Margin {
+                vertical: 0,
+                horizontal: 1,
+            }),
+            &mut self.horizontal_scroll_state,
+        );
+    }
 }

examples/sparkline.rs

@@ -9,33 +9,40 @@
 //! 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
+//! [Ratatui]: https://github.com/ratatui/ratatui
+//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md
 
-use std::{
-    error::Error,
-    io,
-    time::{Duration, Instant},
-};
+use std::time::{Duration, Instant};
 
+use color_eyre::Result;
 use rand::{
     distributions::{Distribution, Uniform},
     rngs::ThreadRng,
 };
 use ratatui::{
-    backend::{Backend, CrosstermBackend},
-    crossterm::{
-        event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode},
-        execute,
-        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-    },
+    crossterm::event::{self, Event, KeyCode},
     layout::{Constraint, Layout},
     style::{Color, Style},
     widgets::{Block, Borders, Sparkline},
-    Frame, Terminal,
+    DefaultTerminal, Frame,
 };
 
+fn main() -> Result<()> {
+    color_eyre::install()?;
+    let terminal = ratatui::init();
+    let app_result = App::new().run(terminal);
+    ratatui::restore();
+    app_result
+}
+
+struct App {
+    signal: RandomSignal,
+    data1: Vec<u64>,
+    data2: Vec<u64>,
+    data3: Vec<u64>,
+}
+
 #[derive(Clone)]
 struct RandomSignal {
     distribution: Uniform<u64>,
@@ -58,13 +65,6 @@ impl Iterator for RandomSignal {
     }
 }
 
-struct App {
-    signal: RandomSignal,
-    data1: Vec<u64>,
-    data2: Vec<u64>,
-    data3: Vec<u64>,
-}
-
 impl App {
     fn new() -> Self {
         let mut signal = RandomSignal::new(0, 100);
@@ -90,94 +90,63 @@ impl App {
         self.data3.pop();
         self.data3.insert(0, value);
     }
-}
 
-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)?;
+    fn run(mut self, mut terminal: DefaultTerminal) -> Result<()> {
+        let tick_rate = Duration::from_millis(250);
 
-    // 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);
+        let mut last_tick = Instant::now();
+        loop {
+            terminal.draw(|frame| self.draw(frame))?;
 
-    // restore terminal
-    disable_raw_mode()?;
-    execute!(
-        terminal.backend_mut(),
-        LeaveAlternateScreen,
-        DisableMouseCapture
-    )?;
-    terminal.show_cursor()?;
-
-    if let Err(err) = res {
-        println!("{err:?}");
-    }
-
-    Ok(())
-}
-
-fn run_app<B: Backend>(
-    terminal: &mut Terminal<B>,
-    mut app: App,
-    tick_rate: Duration,
-) -> io::Result<()> {
-    let mut last_tick = Instant::now();
-    loop {
-        terminal.draw(|f| ui(f, &app))?;
-
-        let timeout = tick_rate.saturating_sub(last_tick.elapsed());
-        if crossterm::event::poll(timeout)? {
-            if let Event::Key(key) = event::read()? {
-                if key.code == KeyCode::Char('q') {
-                    return Ok(());
+            let timeout = tick_rate.saturating_sub(last_tick.elapsed());
+            if event::poll(timeout)? {
+                if let Event::Key(key) = event::read()? {
+                    if key.code == KeyCode::Char('q') {
+                        return Ok(());
+                    }
                 }
             }
-        }
-        if last_tick.elapsed() >= tick_rate {
-            app.on_tick();
-            last_tick = Instant::now();
+            if last_tick.elapsed() >= tick_rate {
+                self.on_tick();
+                last_tick = Instant::now();
+            }
         }
     }
-}
 
-fn ui(f: &mut Frame, app: &App) {
-    let chunks = Layout::vertical([
-        Constraint::Length(3),
-        Constraint::Length(3),
-        Constraint::Min(0),
-    ])
-    .split(f.area());
-    let sparkline = Sparkline::default()
-        .block(
-            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::new()
-                .borders(Borders::LEFT | Borders::RIGHT)
-                .title("Data2"),
-        )
-        .data(&app.data2)
-        .style(Style::default().bg(Color::Green));
-    f.render_widget(sparkline, chunks[1]);
-    // Multiline
-    let sparkline = Sparkline::default()
-        .block(
-            Block::new()
-                .borders(Borders::LEFT | Borders::RIGHT)
-                .title("Data3"),
-        )
-        .data(&app.data3)
-        .style(Style::default().fg(Color::Red));
-    f.render_widget(sparkline, chunks[2]);
+    fn draw(&self, frame: &mut Frame) {
+        let chunks = Layout::vertical([
+            Constraint::Length(3),
+            Constraint::Length(3),
+            Constraint::Min(0),
+        ])
+        .split(frame.area());
+        let sparkline = Sparkline::default()
+            .block(
+                Block::new()
+                    .borders(Borders::LEFT | Borders::RIGHT)
+                    .title("Data1"),
+            )
+            .data(&self.data1)
+            .style(Style::default().fg(Color::Yellow));
+        frame.render_widget(sparkline, chunks[0]);
+        let sparkline = Sparkline::default()
+            .block(
+                Block::new()
+                    .borders(Borders::LEFT | Borders::RIGHT)
+                    .title("Data2"),
+            )
+            .data(&self.data2)
+            .style(Style::default().bg(Color::Green));
+        frame.render_widget(sparkline, chunks[1]);
+        // Multiline
+        let sparkline = Sparkline::default()
+            .block(
+                Block::new()
+                    .borders(Borders::LEFT | Borders::RIGHT)
+                    .title("Data3"),
+            )
+            .data(&self.data3)
+            .style(Style::default().fg(Color::Red));
+        frame.render_widget(sparkline, chunks[2]);
+    }
 }

examples/table.rs

@@ -9,20 +9,14 @@
 //! 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};
+//! [Ratatui]: https://github.com/ratatui/ratatui
+//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md
 
+use color_eyre::Result;
 use itertools::Itertools;
 use ratatui::{
-    backend::{Backend, CrosstermBackend},
-    crossterm::{
-        event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode, KeyEventKind},
-        execute,
-        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-    },
+    crossterm::event::{self, Event, KeyCode, KeyEventKind},
     layout::{Constraint, Layout, Margin, Rect},
     style::{self, Color, Modifier, Style, Stylize},
     text::{Line, Text},
@@ -30,7 +24,7 @@ use ratatui::{
         Block, BorderType, Cell, HighlightSpacing, Paragraph, Row, Scrollbar, ScrollbarOrientation,
         ScrollbarState, Table, TableState,
     },
-    Frame, Terminal,
+    DefaultTerminal, Frame,
 };
 use style::palette::tailwind;
 use unicode_width::UnicodeWidthStr;
@@ -46,6 +40,13 @@ const INFO_TEXT: &str =
 
 const ITEM_HEIGHT: usize = 4;
 
+fn main() -> Result<()> {
+    color_eyre::install()?;
+    let terminal = ratatui::init();
+    let app_result = App::new().run(terminal);
+    ratatui::restore();
+    app_result
+}
 struct TableColors {
     buffer_bg: Color,
     header_bg: Color,
@@ -117,6 +118,7 @@ impl App {
             items: data_vec,
         }
     }
+
     pub fn next(&mut self) {
         let i = match self.state.selected() {
             Some(i) => {
@@ -159,6 +161,115 @@ impl App {
     pub fn set_colors(&mut self) {
         self.colors = TableColors::new(&PALETTES[self.color_index]);
     }
+
+    fn run(mut self, mut terminal: DefaultTerminal) -> Result<()> {
+        loop {
+            terminal.draw(|frame| self.draw(frame))?;
+
+            if let Event::Key(key) = event::read()? {
+                if key.kind == KeyEventKind::Press {
+                    match key.code {
+                        KeyCode::Char('q') | KeyCode::Esc => return Ok(()),
+                        KeyCode::Char('j') | KeyCode::Down => self.next(),
+                        KeyCode::Char('k') | KeyCode::Up => self.previous(),
+                        KeyCode::Char('l') | KeyCode::Right => self.next_color(),
+                        KeyCode::Char('h') | KeyCode::Left => self.previous_color(),
+                        _ => {}
+                    }
+                }
+            }
+        }
+    }
+
+    fn draw(&mut self, frame: &mut Frame) {
+        let vertical = &Layout::vertical([Constraint::Min(5), Constraint::Length(3)]);
+        let rects = vertical.split(frame.area());
+
+        self.set_colors();
+
+        self.render_table(frame, rects[0]);
+        self.render_scrollbar(frame, rects[0]);
+        self.render_footer(frame, rects[1]);
+    }
+
+    fn render_table(&mut self, frame: &mut Frame, area: Rect) {
+        let header_style = Style::default()
+            .fg(self.colors.header_fg)
+            .bg(self.colors.header_bg);
+        let selected_style = Style::default()
+            .add_modifier(Modifier::REVERSED)
+            .fg(self.colors.selected_style_fg);
+
+        let header = ["Name", "Address", "Email"]
+            .into_iter()
+            .map(Cell::from)
+            .collect::<Row>()
+            .style(header_style)
+            .height(1);
+        let rows = self.items.iter().enumerate().map(|(i, data)| {
+            let color = match i % 2 {
+                0 => self.colors.normal_row_color,
+                _ => self.colors.alt_row_color,
+            };
+            let item = data.ref_array();
+            item.into_iter()
+                .map(|content| Cell::from(Text::from(format!("\n{content}\n"))))
+                .collect::<Row>()
+                .style(Style::new().fg(self.colors.row_fg).bg(color))
+                .height(4)
+        });
+        let bar = " █ ";
+        let t = Table::new(
+            rows,
+            [
+                // + 1 is for padding.
+                Constraint::Length(self.longest_item_lens.0 + 1),
+                Constraint::Min(self.longest_item_lens.1 + 1),
+                Constraint::Min(self.longest_item_lens.2),
+            ],
+        )
+        .header(header)
+        .highlight_style(selected_style)
+        .highlight_symbol(Text::from(vec![
+            "".into(),
+            bar.into(),
+            bar.into(),
+            "".into(),
+        ]))
+        .bg(self.colors.buffer_bg)
+        .highlight_spacing(HighlightSpacing::Always);
+        frame.render_stateful_widget(t, area, &mut self.state);
+    }
+
+    fn render_scrollbar(&mut self, frame: &mut Frame, area: Rect) {
+        frame.render_stateful_widget(
+            Scrollbar::default()
+                .orientation(ScrollbarOrientation::VerticalRight)
+                .begin_symbol(None)
+                .end_symbol(None),
+            area.inner(Margin {
+                vertical: 1,
+                horizontal: 1,
+            }),
+            &mut self.scroll_state,
+        );
+    }
+
+    fn render_footer(&self, frame: &mut Frame, area: Rect) {
+        let info_footer = Paragraph::new(Line::from(INFO_TEXT))
+            .style(
+                Style::new()
+                    .fg(self.colors.row_fg)
+                    .bg(self.colors.buffer_bg),
+            )
+            .centered()
+            .block(
+                Block::bordered()
+                    .border_type(BorderType::Double)
+                    .border_style(Style::new().fg(self.colors.footer_border_color)),
+            );
+        frame.render_widget(info_footer, area);
+    }
 }
 
 fn generate_fake_names() -> Vec<Data> {
@@ -183,115 +294,7 @@ fn generate_fake_names() -> Vec<Data> {
             }
         })
         .sorted_by(|a, b| a.name.cmp(&b.name))
-        .collect_vec()
-}
-
-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:?}");
-    }
-
-    Ok(())
-}
-
-fn run_app<B: Backend>(terminal: &mut Terminal<B>, mut app: App) -> io::Result<()> {
-    loop {
-        terminal.draw(|f| ui(f, &mut app))?;
-
-        if let Event::Key(key) = event::read()? {
-            if key.kind == KeyEventKind::Press {
-                match key.code {
-                    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(),
-                    _ => {}
-                }
-            }
-        }
-    }
-}
-
-fn ui(f: &mut Frame, app: &mut App) {
-    let rects = Layout::vertical([Constraint::Min(5), Constraint::Length(3)]).split(f.area());
-
-    app.set_colors();
-
-    render_table(f, app, rects[0]);
-
-    render_scrollbar(f, app, rects[0]);
-
-    render_footer(f, app, rects[1]);
-}
-
-fn render_table(f: &mut Frame, app: &mut App, area: Rect) {
-    let header_style = Style::default()
-        .fg(app.colors.header_fg)
-        .bg(app.colors.header_bg);
-    let selected_style = Style::default()
-        .add_modifier(Modifier::REVERSED)
-        .fg(app.colors.selected_style_fg);
-
-    let header = ["Name", "Address", "Email"]
-        .into_iter()
-        .map(Cell::from)
-        .collect::<Row>()
-        .style(header_style)
-        .height(1);
-    let rows = app.items.iter().enumerate().map(|(i, data)| {
-        let color = match i % 2 {
-            0 => app.colors.normal_row_color,
-            _ => app.colors.alt_row_color,
-        };
-        let item = data.ref_array();
-        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)
-    });
-    let bar = " █ ";
-    let t = Table::new(
-        rows,
-        [
-            // + 1 is for padding.
-            Constraint::Length(app.longest_item_lens.0 + 1),
-            Constraint::Min(app.longest_item_lens.1 + 1),
-            Constraint::Min(app.longest_item_lens.2),
-        ],
-    )
-    .header(header)
-    .highlight_style(selected_style)
-    .highlight_symbol(Text::from(vec![
-        "".into(),
-        bar.into(),
-        bar.into(),
-        "".into(),
-    ]))
-    .bg(app.colors.buffer_bg)
-    .highlight_spacing(HighlightSpacing::Always);
-    f.render_stateful_widget(t, area, &mut app.state);
+        .collect()
 }
 
 fn constraint_len_calculator(items: &[Data]) -> (u16, u16, u16) {
@@ -319,32 +322,6 @@ fn constraint_len_calculator(items: &[Data]) -> (u16, u16, u16) {
     (name_len as u16, address_len as u16, email_len as u16)
 }
 
-fn render_scrollbar(f: &mut Frame, app: &mut App, area: Rect) {
-    f.render_stateful_widget(
-        Scrollbar::default()
-            .orientation(ScrollbarOrientation::VerticalRight)
-            .begin_symbol(None)
-            .end_symbol(None),
-        area.inner(Margin {
-            vertical: 1,
-            horizontal: 1,
-        }),
-        &mut app.scroll_state,
-    );
-}
-
-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))
-        .centered()
-        .block(
-            Block::bordered()
-                .border_type(BorderType::Double)
-                .border_style(Style::new().fg(app.colors.footer_border_color)),
-        );
-    f.render_widget(info_footer, area);
-}
-
 #[cfg(test)]
 mod tests {
     use crate::Data;

examples/tabs.rs

@@ -9,30 +9,31 @@
 //! 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
+//! [Ratatui]: https://github.com/ratatui/ratatui
+//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md
 
-use std::io::stdout;
-
-use color_eyre::{config::HookBuilder, Result};
+use color_eyre::Result;
 use ratatui::{
-    backend::{Backend, CrosstermBackend},
     buffer::Buffer,
-    crossterm::{
-        event::{self, Event, KeyCode, KeyEventKind},
-        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-        ExecutableCommand,
-    },
+    crossterm::event::{self, Event, KeyCode, KeyEventKind},
     layout::{Constraint, Layout, Rect},
     style::{palette::tailwind, Color, Stylize},
     symbols,
     text::Line,
     widgets::{Block, Padding, Paragraph, Tabs, Widget},
-    Terminal,
+    DefaultTerminal,
 };
 use strum::{Display, EnumIter, FromRepr, IntoEnumIterator};
 
+fn main() -> Result<()> {
+    color_eyre::install()?;
+    let terminal = ratatui::init();
+    let app_result = App::default().run(terminal);
+    ratatui::restore();
+    app_result
+}
+
 #[derive(Default)]
 struct App {
     state: AppState,
@@ -59,28 +60,15 @@ enum SelectedTab {
     Tab4,
 }
 
-fn main() -> Result<()> {
-    init_error_hooks()?;
-    let mut terminal = init_terminal()?;
-    App::default().run(&mut terminal)?;
-    restore_terminal()?;
-    Ok(())
-}
-
 impl App {
-    fn run(&mut self, terminal: &mut Terminal<impl Backend>) -> Result<()> {
+    fn run(mut self, mut terminal: DefaultTerminal) -> Result<()> {
         while self.state == AppState::Running {
-            self.draw(terminal)?;
+            terminal.draw(|frame| frame.render_widget(&self, frame.area()))?;
             self.handle_events()?;
         }
         Ok(())
     }
 
-    fn draw(&self, terminal: &mut Terminal<impl Backend>) -> Result<()> {
-        terminal.draw(|frame| frame.render_widget(self, frame.area()))?;
-        Ok(())
-    }
-
     fn handle_events(&mut self) -> std::io::Result<()> {
         if let Event::Key(key) = event::read()? {
             if key.kind == KeyEventKind::Press {
@@ -226,32 +214,3 @@ impl SelectedTab {
         }
     }
 }
-
-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

@@ -9,9 +9,9 @@
 //! 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
+//! [Ratatui]: https://github.com/ratatui/ratatui
+//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md
 
 // A simple example demonstrating how to use the [tracing] with Ratatui to log to a file.
 //
@@ -27,39 +27,32 @@
 // [tracing]: https://crates.io/crates/tracing
 // [tui-logger]: https://crates.io/crates/tui-logger
 
-use std::{fs::File, io::stdout, panic, time::Duration};
+use std::{fs::File, 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 color_eyre::{eyre::Context, Result};
 use ratatui::{
-    backend::{Backend, CrosstermBackend},
+    crossterm::event::{self, Event, KeyCode},
     widgets::{Block, Paragraph},
-    Terminal,
+    Frame,
 };
 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()?;
+    color_eyre::install()?;
+
     let _guard = init_tracing()?;
     info!("Starting tracing example");
 
-    let mut terminal = init_terminal()?;
+    let mut terminal = ratatui::init();
     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))?;
+        terminal.draw(|frame| draw(frame, &events))?;
     }
-    restore_terminal()?;
+    ratatui::restore();
+
     info!("Exiting tracing example");
     println!("See the tracing.log file for the logs");
     Ok(())
@@ -85,7 +78,7 @@ fn handle_events(events: &mut Vec<Event>) -> Result<()> {
 }
 
 #[instrument(skip_all)]
-fn ui(frame: &mut ratatui::Frame, events: &[Event]) {
+fn draw(frame: &mut 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 events = events.iter().map(|e| format!("{e:?}")).collect::<Vec<_>>();
@@ -116,38 +109,3 @@ fn init_tracing() -> Result<WorkerGuard> {
         .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

@@ -9,9 +9,9 @@
 //! 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
+//! [Ratatui]: https://github.com/ratatui/ratatui
+//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui/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
@@ -27,25 +27,22 @@
 //
 // See also https://github.com/rhysd/tui-textarea and https://github.com/sayanarijit/tui-input/
 
-use std::{error::Error, io};
-
+use color_eyre::Result;
 use ratatui::{
-    backend::{Backend, CrosstermBackend},
-    crossterm::{
-        event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode, KeyEventKind},
-        execute,
-        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-    },
+    crossterm::event::{self, Event, KeyCode, KeyEventKind},
     layout::{Constraint, Layout, Position},
     style::{Color, Modifier, Style, Stylize},
     text::{Line, Span, Text},
     widgets::{Block, List, ListItem, Paragraph},
-    Frame, Terminal,
+    DefaultTerminal, Frame,
 };
 
-enum InputMode {
-    Normal,
-    Editing,
+fn main() -> Result<()> {
+    color_eyre::install()?;
+    let terminal = ratatui::init();
+    let app_result = App::new().run(terminal);
+    ratatui::restore();
+    app_result
 }
 
 /// App holds the state of the application
@@ -60,6 +57,11 @@ struct App {
     messages: Vec<String>,
 }
 
+enum InputMode {
+    Normal,
+    Editing,
+}
+
 impl App {
     const fn new() -> Self {
         Self {
@@ -133,142 +135,104 @@ impl App {
         self.input.clear();
         self.reset_cursor();
     }
-}
 
-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)?;
+    fn run(mut self, mut terminal: DefaultTerminal) -> Result<()> {
+        loop {
+            terminal.draw(|frame| self.draw(frame))?;
 
-    // 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:?}");
-    }
-
-    Ok(())
-}
-
-fn run_app<B: Backend>(terminal: &mut Terminal<B>, mut app: App) -> io::Result<()> {
-    loop {
-        terminal.draw(|f| ui(f, &app))?;
-
-        if let Event::Key(key) = event::read()? {
-            match app.input_mode {
-                InputMode::Normal => match key.code {
-                    KeyCode::Char('e') => {
-                        app.input_mode = InputMode::Editing;
-                    }
-                    KeyCode::Char('q') => {
-                        return Ok(());
-                    }
-                    _ => {}
-                },
-                InputMode::Editing if key.kind == KeyEventKind::Press => match key.code {
-                    KeyCode::Enter => app.submit_message(),
-                    KeyCode::Char(to_insert) => {
-                        app.enter_char(to_insert);
-                    }
-                    KeyCode::Backspace => {
-                        app.delete_char();
-                    }
-                    KeyCode::Left => {
-                        app.move_cursor_left();
-                    }
-                    KeyCode::Right => {
-                        app.move_cursor_right();
-                    }
-                    KeyCode::Esc => {
-                        app.input_mode = InputMode::Normal;
-                    }
-                    _ => {}
-                },
-                InputMode::Editing => {}
+            if let Event::Key(key) = event::read()? {
+                match self.input_mode {
+                    InputMode::Normal => match key.code {
+                        KeyCode::Char('e') => {
+                            self.input_mode = InputMode::Editing;
+                        }
+                        KeyCode::Char('q') => {
+                            return Ok(());
+                        }
+                        _ => {}
+                    },
+                    InputMode::Editing if key.kind == KeyEventKind::Press => match key.code {
+                        KeyCode::Enter => self.submit_message(),
+                        KeyCode::Char(to_insert) => self.enter_char(to_insert),
+                        KeyCode::Backspace => self.delete_char(),
+                        KeyCode::Left => self.move_cursor_left(),
+                        KeyCode::Right => self.move_cursor_right(),
+                        KeyCode::Esc => self.input_mode = InputMode::Normal,
+                        _ => {}
+                    },
+                    InputMode::Editing => {}
+                }
             }
         }
     }
-}
 
-fn ui(f: &mut Frame, app: &App) {
-    let vertical = Layout::vertical([
-        Constraint::Length(1),
-        Constraint::Length(3),
-        Constraint::Min(1),
-    ]);
-    let [help_area, input_area, messages_area] = vertical.areas(f.area());
+    fn draw(&self, frame: &mut Frame) {
+        let vertical = Layout::vertical([
+            Constraint::Length(1),
+            Constraint::Length(3),
+            Constraint::Min(1),
+        ]);
+        let [help_area, input_area, messages_area] = vertical.areas(frame.area());
 
-    let (msg, style) = match app.input_mode {
-        InputMode::Normal => (
-            vec![
-                "Press ".into(),
-                "q".bold(),
-                " to exit, ".into(),
-                "e".bold(),
-                " to start editing.".bold(),
-            ],
-            Style::default().add_modifier(Modifier::RAPID_BLINK),
-        ),
-        InputMode::Editing => (
-            vec![
-                "Press ".into(),
-                "Esc".bold(),
-                " to stop editing, ".into(),
-                "Enter".bold(),
-                " to record the message".into(),
-            ],
-            Style::default(),
-        ),
-    };
-    let text = Text::from(Line::from(msg)).patch_style(style);
-    let help_message = Paragraph::new(text);
-    f.render_widget(help_message, help_area);
+        let (msg, style) = match self.input_mode {
+            InputMode::Normal => (
+                vec![
+                    "Press ".into(),
+                    "q".bold(),
+                    " to exit, ".into(),
+                    "e".bold(),
+                    " to start editing.".bold(),
+                ],
+                Style::default().add_modifier(Modifier::RAPID_BLINK),
+            ),
+            InputMode::Editing => (
+                vec![
+                    "Press ".into(),
+                    "Esc".bold(),
+                    " to stop editing, ".into(),
+                    "Enter".bold(),
+                    " to record the message".into(),
+                ],
+                Style::default(),
+            ),
+        };
+        let text = Text::from(Line::from(msg)).patch_style(style);
+        let help_message = Paragraph::new(text);
+        frame.render_widget(help_message, help_area);
 
-    let input = Paragraph::new(app.input.as_str())
-        .style(match app.input_mode {
-            InputMode::Normal => Style::default(),
-            InputMode::Editing => Style::default().fg(Color::Yellow),
-        })
-        .block(Block::bordered().title("Input"));
-    f.render_widget(input, input_area);
-    match app.input_mode {
-        // Hide the cursor. `Frame` does this by default, so we don't need to do anything here
-        InputMode::Normal => {}
+        let input = Paragraph::new(self.input.as_str())
+            .style(match self.input_mode {
+                InputMode::Normal => Style::default(),
+                InputMode::Editing => Style::default().fg(Color::Yellow),
+            })
+            .block(Block::bordered().title("Input"));
+        frame.render_widget(input, input_area);
+        match self.input_mode {
+            // Hide the cursor. `Frame` does this by default, so we don't need to do anything here
+            InputMode::Normal => {}
 
-        // Make the cursor visible and ask ratatui to put it at the specified coordinates after
-        // rendering
-        #[allow(clippy::cast_possible_truncation)]
-        InputMode::Editing => f.set_cursor_position(Position::new(
-            // 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.character_index as u16 + 1,
-            // Move one line down, from the border to the input line
-            input_area.y + 1,
-        )),
+            // Make the cursor visible and ask ratatui to put it at the specified coordinates after
+            // rendering
+            #[allow(clippy::cast_possible_truncation)]
+            InputMode::Editing => frame.set_cursor_position(Position::new(
+                // 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 + self.character_index as u16 + 1,
+                // Move one line down, from the border to the input line
+                input_area.y + 1,
+            )),
+        }
+
+        let messages: Vec<ListItem> = self
+            .messages
+            .iter()
+            .enumerate()
+            .map(|(i, m)| {
+                let content = Line::from(Span::raw(format!("{i}: {m}")));
+                ListItem::new(content)
+            })
+            .collect();
+        let messages = List::new(messages).block(Block::bordered().title("Messages"));
+        frame.render_widget(messages, messages_area);
     }
-
-    let messages: Vec<ListItem> = app
-        .messages
-        .iter()
-        .enumerate()
-        .map(|(i, m)| {
-            let content = Line::from(Span::raw(format!("{i}: {m}")));
-            ListItem::new(content)
-        })
-        .collect();
-    let messages = List::new(messages).block(Block::bordered().title("Messages"));
-    f.render_widget(messages, messages_area);
 }

examples/vhs/generate.bash

@@ -30,7 +30,7 @@ for tape_path in examples/vhs/*.tape; do
     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_file}]: https://github.com/ratatui-org/ratatui/blob/images/examples/${gif_file}?raw=true"
+    echo "[${gif_file}]: https://github.com/ratatui/ratatui/blob/images/examples/${gif_file}?raw=true"
 done
 git switch images
 git pull --rebase upstream images

examples/widget_impl.rs

@@ -0,0 +1,258 @@
+//! # [Ratatui] Widgets implementation examples
+//!
+//! This example demonstrates various ways to implement widget traits in Ratatui on a type, a
+//! reference, and a mutable reference. It also shows how to use the `WidgetRef` trait to render
+//! boxed widgets.
+//!
+//! 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::time::{Duration, Instant};
+
+use color_eyre::Result;
+use crossterm::event::{self, Event, KeyCode};
+use ratatui::{
+    buffer::Buffer,
+    layout::{Constraint, Layout, Position, Rect, Size},
+    style::{Color, Style},
+    widgets::{Widget, WidgetRef},
+    DefaultTerminal,
+};
+
+fn main() -> Result<()> {
+    color_eyre::install()?;
+    let terminal = ratatui::init();
+    let result = App::default().run(terminal);
+    ratatui::restore();
+    result
+}
+
+#[derive(Default)]
+struct App {
+    should_quit: bool,
+    timer: Timer,
+    #[cfg(feature = "unstable-widget-ref")]
+    boxed_squares: BoxedSquares,
+    green_square: RightAlignedSquare,
+}
+
+impl App {
+    fn run(mut self, mut terminal: DefaultTerminal) -> Result<()> {
+        while !self.should_quit {
+            self.draw(&mut terminal)?;
+            self.handle_events()?;
+        }
+        Ok(())
+    }
+
+    fn draw(&mut self, tui: &mut DefaultTerminal) -> Result<()> {
+        tui.draw(|frame| frame.render_widget(self, frame.area()))?;
+        Ok(())
+    }
+
+    fn handle_events(&mut self) -> Result<()> {
+        // Handle events at least 50 frames per second (gifs are usually 50fps)
+        let timeout = Duration::from_secs_f64(1.0 / 50.0);
+        if !event::poll(timeout)? {
+            return Ok(());
+        }
+        if let Event::Key(key) = event::read()? {
+            match key.code {
+                KeyCode::Char('q') | KeyCode::Esc => self.should_quit = true,
+                _ => {}
+            }
+        }
+        Ok(())
+    }
+}
+
+/// Implement the `Widget` trait on a mutable reference to the `App` type.
+///
+/// This allows the `App` type to be rendered as a widget. The `App` type owns several other widgets
+/// that are rendered as part of the app. The `Widget` trait is implemented on a mutable reference
+/// to the `App` type, which allows this to be rendered without consuming the `App` type, and allows
+/// the sub-widgets to be mutatable.
+impl Widget for &mut App {
+    fn render(self, area: Rect, buf: &mut Buffer) {
+        let constraints = Constraint::from_lengths([1, 1, 2, 1]);
+        let [greeting, timer, squares, position] = Layout::vertical(constraints).areas(area);
+
+        // render an ephemeral greeting widget
+        Greeting::new("Ratatui!").render(greeting, buf);
+
+        // render a reference to the timer widget
+        self.timer.render(timer, buf);
+
+        // render a boxed widget containing red and blue squares
+        #[cfg(feature = "unstable-widget-ref")]
+        self.boxed_squares.render(squares, buf);
+
+        // render a mutable reference to the green square widget
+        self.green_square.render(squares, buf);
+        // Display the dynamically updated position of the green square
+        let square_position = format!("Green square is at {}", self.green_square.last_position);
+        square_position.render(position, buf);
+    }
+}
+
+/// An ephemeral greeting widget.
+///
+/// This widget is implemented on the type itself, which means that it is consumed when it is
+/// rendered. This is useful for widgets that are cheap to create, don't need to be reused, and
+/// don't need to store any state between renders. This is the simplest way to implement a widget in
+/// Ratatui, but in most cases, it is better to implement the `Widget` trait on a reference to the
+/// type, as shown in the other examples below.
+///
+/// This was the way most widgets were implemented in Ratatui before `Widget` was implemented on
+/// references in [PR #903] (merged in Ratatui 0.26.0).
+///
+/// [PR #903]: https://github.com/ratatui-org/ratatui/pull/903
+struct Greeting {
+    name: String,
+}
+
+impl Greeting {
+    fn new(name: &str) -> Self {
+        Self {
+            name: name.to_string(),
+        }
+    }
+}
+
+impl Widget for Greeting {
+    fn render(self, area: Rect, buf: &mut Buffer) {
+        let greeting = format!("Hello, {}!", self.name);
+        greeting.render(area, buf);
+    }
+}
+
+/// A timer widget that displays the elapsed time since the timer was started.
+#[derive(Debug)]
+struct Timer {
+    start: Instant,
+}
+
+impl Default for Timer {
+    fn default() -> Self {
+        Self {
+            start: Instant::now(),
+        }
+    }
+}
+
+/// This implements `Widget` on a reference to the type, which means that it can be reused and
+/// doesn't need to be consumed when it is rendered. This is useful for widgets that need to store
+/// state and be updated over time.
+///
+/// This approach was probably always available in Ratatui, but it wasn't widely used until `Widget`
+/// was implemented on references in [PR #903] (merged in Ratatui 0.26.0). This is because all the
+/// built-in widgets previously would consume themselves when rendered.
+impl Widget for &Timer {
+    fn render(self, area: Rect, buf: &mut Buffer) {
+        let elapsed = self.start.elapsed().as_secs_f32();
+        let message = format!("Elapsed: {elapsed:.1?}s");
+        message.render(area, buf);
+    }
+}
+
+/// A widget that contains a list of several different widgets.
+struct BoxedSquares {
+    squares: Vec<Box<dyn WidgetRef>>,
+}
+
+impl Default for BoxedSquares {
+    fn default() -> Self {
+        let red_square: Box<dyn WidgetRef> = Box::new(RedSquare);
+        let blue_square: Box<dyn WidgetRef> = Box::new(BlueSquare);
+        Self {
+            squares: vec![red_square, blue_square],
+        }
+    }
+}
+
+/// A widget that renders a red square.
+struct RedSquare;
+
+/// A widget that renders a blue square.
+struct BlueSquare;
+
+/// This implements the `Widget` trait on a reference to the type. It contains a list of boxed
+/// widgets that implement the `WidgetRef` trait. This is useful for widgets that contain a list of
+/// other widgets that can be different types.
+impl Widget for &BoxedSquares {
+    fn render(self, area: Rect, buf: &mut Buffer) {
+        let constraints = vec![Constraint::Length(4); self.squares.len()];
+        let areas = Layout::horizontal(constraints).split(area);
+        for (widget, area) in self.squares.iter().zip(areas.iter()) {
+            widget.render_ref(*area, buf);
+        }
+    }
+}
+
+/// `RedSquare` and `BlueSquare` are widgets that render a red and blue square, respectively. They
+/// implement the `WidgetRef` trait instead of the `Widget` trait, which which allows them to be
+/// rendered as boxed widgets. It's not possible to use Widget for this as a dynamic reference to a
+/// widget cannot generally be moved out of the box.
+impl WidgetRef for RedSquare {
+    fn render_ref(&self, area: Rect, buf: &mut Buffer) {
+        fill(area, buf, "█", Color::Red);
+    }
+}
+
+impl WidgetRef for BlueSquare {
+    fn render_ref(&self, area: Rect, buf: &mut Buffer) {
+        fill(area, buf, "█", Color::Blue);
+    }
+}
+
+/// A widget that renders a green square aligned to the right of the area.
+#[derive(Default)]
+struct RightAlignedSquare {
+    last_position: Position,
+}
+
+/// This widget is implemented on a mutable reference to the type, which means that it can store
+/// state and update it when it is rendered. This is useful for widgets that need to store the
+/// result of some calculation that can only be done when the widget is rendered.
+///
+/// The x and y coordinates of the square are stored in the widget and updated when the widget is
+/// rendered. This allows the square to be aligned to the right of the area. These coordinates could
+/// be used to perform hit testing (e.g. checking if a mouse click is inside the square). This app
+/// just displays the coordinates as a string.
+///
+/// This approach was probably always available in Ratatui, but it wasn't widely used either. This
+/// is an alternative to implementing the `StatefulWidget` trait, for situations where you want to
+/// store the state in the widget itself instead of a separate struct.
+impl Widget for &mut RightAlignedSquare {
+    /// Render a green square aligned to the right of the area and store the position.
+    fn render(self, area: Rect, buf: &mut Buffer) {
+        const WIDTH: u16 = 4;
+        let x = area.right() - WIDTH; // Align to the right
+        self.last_position = Position { x, y: area.y };
+        let size = Size::new(WIDTH, area.height);
+        let area = Rect::from((self.last_position, size));
+        fill(area, buf, "█", Color::Green);
+    }
+}
+
+/// Fill the area with the specified symbol and style.
+///
+/// This probably should be a method on the `Buffer` type, but it is defined here for simplicity.
+/// <https://github.com/ratatui-org/ratatui/issues/1146>
+fn fill<S: Into<Style>>(area: Rect, buf: &mut Buffer, symbol: &str, style: S) {
+    let style = style.into();
+    for y in area.top()..area.bottom() {
+        for x in area.left()..area.right() {
+            buf[(x, y)].set_symbol(symbol).set_style(style);
+        }
+    }
+}

src/backend.rs

@@ -96,10 +96,10 @@
 //! [Crossterm]: https://crates.io/crates/crossterm
 //! [Termion]: https://crates.io/crates/termion
 //! [Termwiz]: https://crates.io/crates/termwiz
-//! [Examples]: https://github.com/ratatui-org/ratatui/tree/main/examples/README.md
+//! [Examples]: https://github.com/ratatui/ratatui/tree/main/examples/README.md
 //! [Backend Comparison]:
 //!     https://ratatui.rs/concepts/backends/comparison/
-//! [Ratatui Website]: https://ratatui-org.github.io/ratatui-book
+//! [Ratatui Website]: https://ratatui.rs
 use std::io;
 
 use strum::{Display, EnumString};
@@ -109,9 +109,9 @@ use crate::{
     layout::{Position, Size},
 };
 
-#[cfg(feature = "termion")]
+#[cfg(all(not(windows), feature = "termion"))]
 mod termion;
-#[cfg(feature = "termion")]
+#[cfg(all(not(windows), feature = "termion"))]
 pub use self::termion::TermionBackend;
 
 #[cfg(feature = "crossterm")]

src/backend/crossterm.rs

@@ -80,7 +80,7 @@ use crate::{
 /// [`Terminal`]: crate::terminal::Terminal
 /// [`backend`]: crate::backend
 /// [Crossterm]: https://crates.io/crates/crossterm
-/// [Examples]: https://github.com/ratatui-org/ratatui/tree/main/examples/README.md
+/// [Examples]: https://github.com/ratatui/ratatui/tree/main/examples/README.md
 #[derive(Debug, Default, Clone, Eq, PartialEq, Hash)]
 pub struct CrosstermBackend<W: Write> {
     /// The writer used to send commands to the terminal.
@@ -93,6 +93,11 @@ where
 {
     /// Creates a new `CrosstermBackend` with the given writer.
     ///
+    /// Most applications will use either [`stdout`](std::io::stdout) or
+    /// [`stderr`](std::io::stderr) as writer. See the [FAQ] to determine which one to use.
+    ///
+    /// [FAQ]: https://ratatui.rs/faq/#should-i-use-stdout-or-stderr
+    ///
     /// # Example
     ///
     /// ```rust,no_run
@@ -107,7 +112,7 @@ where
     /// Gets the writer.
     #[instability::unstable(
         feature = "backend-writer",
-        issue = "https://github.com/ratatui-org/ratatui/pull/991"
+        issue = "https://github.com/ratatui/ratatui/pull/991"
     )]
     pub const fn writer(&self) -> &W {
         &self.writer
@@ -119,7 +124,7 @@ where
     /// way that the Terminal implements diffing Buffers.
     #[instability::unstable(
         feature = "backend-writer",
-        issue = "https://github.com/ratatui-org/ratatui/pull/991"
+        issue = "https://github.com/ratatui/ratatui/pull/991"
     )]
     pub fn writer_mut(&mut self) -> &mut W {
         &mut self.writer

src/backend/termion.rs

@@ -76,6 +76,11 @@ where
 {
     /// Creates a new Termion backend with the given writer.
     ///
+    /// Most applications will use either [`stdout`](std::io::stdout) or
+    /// [`stderr`](std::io::stderr) as writer. See the [FAQ] to determine which one to use.
+    ///
+    /// [FAQ]: https://ratatui.rs/faq/#should-i-use-stdout-or-stderr
+    ///
     /// # Example
     ///
     /// ```rust,no_run
@@ -90,7 +95,7 @@ where
     /// Gets the writer.
     #[instability::unstable(
         feature = "backend-writer",
-        issue = "https://github.com/ratatui-org/ratatui/pull/991"
+        issue = "https://github.com/ratatui/ratatui/pull/991"
     )]
     pub const fn writer(&self) -> &W {
         &self.writer
@@ -101,7 +106,7 @@ where
     /// way that the Terminal implements diffing Buffers.
     #[instability::unstable(
         feature = "backend-writer",
-        issue = "https://github.com/ratatui-org/ratatui/pull/991"
+        issue = "https://github.com/ratatui/ratatui/pull/991"
     )]
     pub fn writer_mut(&mut self) -> &mut W {
         &mut self.writer

src/backend/termwiz.rs

@@ -57,7 +57,7 @@ use crate::{
 /// [`Terminal`]: crate::terminal::Terminal
 /// [`BufferedTerminal`]: termwiz::terminal::buffered::BufferedTerminal
 /// [Termwiz]: https://crates.io/crates/termwiz
-/// [Examples]: https://github.com/ratatui-org/ratatui/tree/main/examples/README.md
+/// [Examples]: https://github.com/ratatui/ratatui/tree/main/examples/README.md
 pub struct TermwizBackend {
     buffered_terminal: BufferedTerminal<SystemTerminal>,
 }

src/backend/test.rs

@@ -3,7 +3,7 @@
 
 use std::{
     fmt::{self, Write},
-    io,
+    io, iter,
 };
 
 use unicode_width::UnicodeWidthStr;
@@ -35,6 +35,7 @@ use crate::{
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 pub struct TestBackend {
     buffer: Buffer,
+    scrollback: Buffer,
     cursor: bool,
     pos: (u16, u16),
 }
@@ -73,6 +74,7 @@ impl TestBackend {
     pub fn new(width: u16, height: u16) -> Self {
         Self {
             buffer: Buffer::empty(Rect::new(0, 0, width, height)),
+            scrollback: Buffer::empty(Rect::new(0, 0, width, 0)),
             cursor: false,
             pos: (0, 0),
         }
@@ -83,9 +85,29 @@ impl TestBackend {
         &self.buffer
     }
 
+    /// Returns a reference to the internal scrollback buffer of the `TestBackend`.
+    ///
+    /// The scrollback buffer represents the part of the screen that is currently hidden from view,
+    /// but that could be accessed by scrolling back in the terminal's history. This would normally
+    /// be done using the terminal's scrollbar or an equivalent keyboard shortcut.
+    ///
+    /// The scrollback buffer starts out empty. Lines are appended when they scroll off the top of
+    /// the main buffer. This happens when lines are appended to the bottom of the main buffer
+    /// using [`Backend::append_lines`].
+    ///
+    /// The scrollback buffer has a maximum height of [`u16::MAX`]. If lines are appended to the
+    /// bottom of the scrollback buffer when it is at its maximum height, a corresponding number of
+    /// lines will be removed from the top.
+    pub const fn scrollback(&self) -> &Buffer {
+        &self.scrollback
+    }
+
     /// Resizes the `TestBackend` to the specified width and height.
     pub fn resize(&mut self, width: u16, height: u16) {
         self.buffer.resize(Rect::new(0, 0, width, height));
+        let scrollback_height = self.scrollback.area.height;
+        self.scrollback
+            .resize(Rect::new(0, 0, width, scrollback_height));
     }
 
     /// Asserts that the `TestBackend`'s buffer is equal to the expected buffer.
@@ -93,6 +115,7 @@ impl TestBackend {
     /// This is a shortcut for `assert_eq!(self.buffer(), &expected)`.
     ///
     /// # Panics
+    ///
     /// When they are not equal, a panic occurs with a detailed error message showing the
     /// differences between the expected and actual buffers.
     #[allow(deprecated)]
@@ -102,11 +125,42 @@ impl TestBackend {
         crate::assert_buffer_eq!(&self.buffer, expected);
     }
 
+    /// Asserts that the `TestBackend`'s scrollback buffer is equal to the expected buffer.
+    ///
+    /// This is a shortcut for `assert_eq!(self.scrollback(), &expected)`.
+    ///
+    /// # Panics
+    ///
+    /// When they are not equal, a panic occurs with a detailed error message showing the
+    /// differences between the expected and actual buffers.
+    #[track_caller]
+    pub fn assert_scrollback(&self, expected: &Buffer) {
+        assert_eq!(&self.scrollback, expected);
+    }
+
+    /// Asserts that the `TestBackend`'s scrollback buffer is empty.
+    ///
+    /// # Panics
+    ///
+    /// When the scrollback buffer is not equal, a panic occurs with a detailed error message
+    /// showing the differences between the expected and actual buffers.
+    pub fn assert_scrollback_empty(&self) {
+        let expected = Buffer {
+            area: Rect {
+                width: self.scrollback.area.width,
+                ..Rect::ZERO
+            },
+            content: vec![],
+        };
+        self.assert_scrollback(&expected);
+    }
+
     /// Asserts that the `TestBackend`'s buffer is equal to the expected lines.
     ///
     /// This is a shortcut for `assert_eq!(self.buffer(), &Buffer::with_lines(expected))`.
     ///
     /// # Panics
+    ///
     /// When they are not equal, a panic occurs with a detailed error message showing the
     /// differences between the expected and actual buffers.
     #[track_caller]
@@ -118,11 +172,29 @@ impl TestBackend {
         self.assert_buffer(&Buffer::with_lines(expected));
     }
 
+    /// Asserts that the `TestBackend`'s scrollback buffer is equal to the expected lines.
+    ///
+    /// This is a shortcut for `assert_eq!(self.scrollback(), &Buffer::with_lines(expected))`.
+    ///
+    /// # Panics
+    ///
+    /// When they are not equal, a panic occurs with a detailed error message showing the
+    /// differences between the expected and actual buffers.
+    #[track_caller]
+    pub fn assert_scrollback_lines<'line, Lines>(&self, expected: Lines)
+    where
+        Lines: IntoIterator,
+        Lines::Item: Into<crate::text::Line<'line>>,
+    {
+        self.assert_scrollback(&Buffer::with_lines(expected));
+    }
+
     /// Asserts that the `TestBackend`'s cursor position is equal to the expected one.
     ///
     /// This is a shortcut for `assert_eq!(self.get_cursor_position().unwrap(), expected)`.
     ///
     /// # Panics
+    ///
     /// When they are not equal, a panic occurs with a detailed error message showing the
     /// differences between the expected and actual position.
     #[track_caller]
@@ -215,7 +287,7 @@ impl Backend for TestBackend {
     /// the cursor y position then that number of empty lines (at most the buffer's height in this
     /// case but this limit is instead replaced with scrolling in most backend implementations) will
     /// be added after the current position and the cursor will be moved to the last row.
-    fn append_lines(&mut self, n: u16) -> io::Result<()> {
+    fn append_lines(&mut self, line_count: u16) -> io::Result<()> {
         let Position { x: cur_x, y: cur_y } = self.get_cursor_position()?;
         let Rect { width, height, .. } = self.buffer.area;
 
@@ -224,19 +296,29 @@ impl Backend for TestBackend {
 
         let max_y = height.saturating_sub(1);
         let lines_after_cursor = max_y.saturating_sub(cur_y);
-        if n > lines_after_cursor {
-            let rotate_by = n.saturating_sub(lines_after_cursor).min(max_y);
 
-            if rotate_by == height - 1 {
-                self.clear()?;
-            }
+        if line_count > lines_after_cursor {
+            // We need to insert blank lines at the bottom and scroll the lines from the top into
+            // scrollback.
+            let scroll_by: usize = (line_count - lines_after_cursor).into();
+            let width: usize = self.buffer.area.width.into();
+            let cells_to_scrollback = self.buffer.content.len().min(width * scroll_by);
 
-            self.set_cursor_position(Position { x: 0, y: rotate_by })?;
-            self.clear_region(ClearType::BeforeCursor)?;
-            self.buffer.content.rotate_left((width * rotate_by).into());
+            append_to_scrollback(
+                &mut self.scrollback,
+                self.buffer.content.splice(
+                    0..cells_to_scrollback,
+                    iter::repeat_with(Default::default).take(cells_to_scrollback),
+                ),
+            );
+            self.buffer.content.rotate_left(cells_to_scrollback);
+            append_to_scrollback(
+                &mut self.scrollback,
+                iter::repeat_with(Default::default).take(width * scroll_by - cells_to_scrollback),
+            );
         }
 
-        let new_cursor_y = cur_y.saturating_add(n).min(max_y);
+        let new_cursor_y = cur_y.saturating_add(line_count).min(max_y);
         self.set_cursor_position(Position::new(new_cursor_x, new_cursor_y))?;
 
         Ok(())
@@ -263,8 +345,25 @@ impl Backend for TestBackend {
     }
 }
 
+/// Append the provided cells to the bottom of a scrollback buffer. The number of cells must be a
+/// multiple of the buffer's width. If the scrollback buffer ends up larger than 65535 lines tall,
+/// then lines will be removed from the top to get it down to size.
+fn append_to_scrollback(scrollback: &mut Buffer, cells: impl IntoIterator<Item = Cell>) {
+    scrollback.content.extend(cells);
+    let width = scrollback.area.width as usize;
+    let new_height = (scrollback.content.len() / width).min(u16::MAX as usize);
+    let keep_from = scrollback
+        .content
+        .len()
+        .saturating_sub(width * u16::MAX as usize);
+    scrollback.content.drain(0..keep_from);
+    scrollback.area.height = new_height as u16;
+}
+
 #[cfg(test)]
 mod tests {
+    use itertools::Itertools as _;
+
     use super::*;
 
     #[test]
@@ -273,6 +372,7 @@ mod tests {
             TestBackend::new(10, 2),
             TestBackend {
                 buffer: Buffer::with_lines(["          "; 2]),
+                scrollback: Buffer::empty(Rect::new(0, 0, 10, 0)),
                 cursor: false,
                 pos: (0, 0),
             }
@@ -323,6 +423,13 @@ mod tests {
         backend.assert_buffer_lines(["aaaaaaaaaa"; 2]);
     }
 
+    #[test]
+    #[should_panic = "assertion `left == right` failed"]
+    fn assert_scrollback_panics() {
+        let backend = TestBackend::new(10, 2);
+        backend.assert_scrollback_lines(["aaaaaaaaaa"; 2]);
+    }
+
     #[test]
     fn display() {
         let backend = TestBackend::new(10, 2);
@@ -536,6 +643,7 @@ mod tests {
             "dddddddddd",
             "eeeeeeeeee",
         ]);
+        backend.assert_scrollback_empty();
     }
 
     #[test]
@@ -557,13 +665,14 @@ mod tests {
 
         backend.append_lines(1).unwrap();
 
-        backend.buffer = Buffer::with_lines([
+        backend.assert_buffer_lines([
             "bbbbbbbbbb",
             "cccccccccc",
             "dddddddddd",
             "eeeeeeeeee",
             "          ",
         ]);
+        backend.assert_scrollback_lines(["aaaaaaaaaa"]);
 
         // It also moves the cursor to the right, as is common of the behaviour of
         // terminals in raw-mode
@@ -597,6 +706,7 @@ mod tests {
             "dddddddddd",
             "eeeeeeeeee",
         ]);
+        backend.assert_scrollback_empty();
     }
 
     #[test]
@@ -624,6 +734,7 @@ mod tests {
             "          ",
             "          ",
         ]);
+        backend.assert_scrollback_lines(["aaaaaaaaaa", "bbbbbbbbbb"]);
     }
 
     #[test]
@@ -651,6 +762,13 @@ mod tests {
             "          ",
             "          ",
         ]);
+        backend.assert_scrollback_lines([
+            "aaaaaaaaaa",
+            "bbbbbbbbbb",
+            "cccccccccc",
+            "dddddddddd",
+            "eeeeeeeeee",
+        ]);
     }
 
     #[test]
@@ -676,6 +794,115 @@ mod tests {
             "eeeeeeeeee",
             "          ",
         ]);
+        backend.assert_scrollback_lines(["aaaaaaaaaa"]);
+    }
+
+    #[test]
+    fn append_multiple_lines_where_cursor_at_end_appends_more_than_height_lines() {
+        let mut backend = TestBackend::new(10, 5);
+        backend.buffer = Buffer::with_lines([
+            "aaaaaaaaaa",
+            "bbbbbbbbbb",
+            "cccccccccc",
+            "dddddddddd",
+            "eeeeeeeeee",
+        ]);
+
+        backend
+            .set_cursor_position(Position { x: 0, y: 4 })
+            .unwrap();
+
+        backend.append_lines(8).unwrap();
+        backend.assert_cursor_position(Position { x: 1, y: 4 });
+
+        backend.assert_buffer_lines([
+            "          ",
+            "          ",
+            "          ",
+            "          ",
+            "          ",
+        ]);
+        backend.assert_scrollback_lines([
+            "aaaaaaaaaa",
+            "bbbbbbbbbb",
+            "cccccccccc",
+            "dddddddddd",
+            "eeeeeeeeee",
+            "          ",
+            "          ",
+            "          ",
+        ]);
+    }
+
+    #[test]
+    fn append_lines_truncates_beyond_u16_max() -> io::Result<()> {
+        let mut backend = TestBackend::new(10, 5);
+
+        // Fill the scrollback with 65535 + 10 lines.
+        let row_count = u16::MAX as usize + 10;
+        for row in 0..=row_count {
+            if row > 4 {
+                backend.set_cursor_position(Position { x: 0, y: 4 })?;
+                backend.append_lines(1)?;
+            }
+            let cells = format!("{row:>10}").chars().map(Cell::from).collect_vec();
+            let content = cells
+                .iter()
+                .enumerate()
+                .map(|(column, cell)| (column as u16, 4.min(row) as u16, cell));
+            backend.draw(content)?;
+        }
+
+        // check that the buffer contains the last 5 lines appended
+        backend.assert_buffer_lines([
+            "     65541",
+            "     65542",
+            "     65543",
+            "     65544",
+            "     65545",
+        ]);
+
+        // TODO: ideally this should be something like:
+        //     let lines = (6..=65545).map(|row| format!("{row:>10}"));
+        //     backend.assert_scrollback_lines(lines);
+        // but there's some truncation happening in Buffer::with_lines that needs to be fixed
+        assert_eq!(
+            Buffer {
+                area: Rect::new(0, 0, 10, 5),
+                content: backend.scrollback.content[0..10 * 5].to_vec(),
+            },
+            Buffer::with_lines([
+                "         6",
+                "         7",
+                "         8",
+                "         9",
+                "        10",
+            ]),
+            "first 5 lines of scrollback should have been truncated"
+        );
+
+        assert_eq!(
+            Buffer {
+                area: Rect::new(0, 0, 10, 5),
+                content: backend.scrollback.content[10 * 65530..10 * 65535].to_vec(),
+            },
+            Buffer::with_lines([
+                "     65536",
+                "     65537",
+                "     65538",
+                "     65539",
+                "     65540",
+            ]),
+            "last 5 lines of scrollback should have been appended"
+        );
+
+        // These checks come after the content checks as otherwise we won't see the failing content
+        // when these checks fail.
+        // Make sure the scrollback is the right size.
+        assert_eq!(backend.scrollback.area.width, 10);
+        assert_eq!(backend.scrollback.area.height, 65535);
+        assert_eq!(backend.scrollback.content.len(), 10 * 65535);
+        Ok(())
     }
 
     #[test]

src/buffer/buffer.rs

@@ -246,7 +246,7 @@ impl Buffer {
     ///
     /// Returns `None` if the given coordinates are outside of the Buffer's area.
     ///
-    /// Note that this is private because of <https://github.com/ratatui-org/ratatui/issues/1122>
+    /// Note that this is private because of <https://github.com/ratatui/ratatui/issues/1122>
     #[must_use]
     const fn index_of_opt(&self, position: Position) -> Option<usize> {
         let area = self.area;

src/buffer/cell.rs

@@ -13,7 +13,7 @@ pub struct Cell {
     /// This is a [`CompactString`] which is a wrapper around [`String`] that uses a small inline
     /// buffer for short strings.
     ///
-    /// See <https://github.com/ratatui-org/ratatui/pull/601> for more information.
+    /// See <https://github.com/ratatui/ratatui/pull/601> for more information.
     symbol: CompactString,
 
     /// The foreground color of the cell.
@@ -157,6 +157,14 @@ impl Default for Cell {
     }
 }
 
+impl From<char> for Cell {
+    fn from(ch: char) -> Self {
+        let mut cell = Self::EMPTY;
+        cell.set_char(ch);
+        cell
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;

src/layout/constraint.rs

@@ -1,6 +1,5 @@
 use std::fmt;
 
-use itertools::Itertools;
 use strum::EnumIs;
 
 /// A constraint that defines the size of a layout element.
@@ -117,8 +116,12 @@ pub enum Constraint {
 
     /// Applies a percentage of the available space to the element
     ///
-    /// Converts the given percentage to a floating-point value and multiplies that with area.
-    /// This value is rounded back to a integer as part of the layout split calculation.
+    /// Converts the given percentage to a floating-point value and multiplies that with area. This
+    /// value is rounded back to a integer as part of the layout split calculation.
+    ///
+    /// **Note**: As this value only accepts a `u16`, certain percentages that cannot be
+    /// represented exactly (e.g. 1/3) are not possible. You might want to use
+    /// [`Constraint::Ratio`] or [`Constraint::Fill`] in such cases.
     ///
     /// # Examples
     ///
@@ -229,7 +232,7 @@ impl Constraint {
     where
         T: IntoIterator<Item = u16>,
     {
-        lengths.into_iter().map(Self::Length).collect_vec()
+        lengths.into_iter().map(Self::Length).collect()
     }
 
     /// Convert an iterator of ratios into a vector of constraints
@@ -246,10 +249,7 @@ impl Constraint {
     where
         T: IntoIterator<Item = (u32, u32)>,
     {
-        ratios
-            .into_iter()
-            .map(|(n, d)| Self::Ratio(n, d))
-            .collect_vec()
+        ratios.into_iter().map(|(n, d)| Self::Ratio(n, d)).collect()
     }
 
     /// Convert an iterator of percentages into a vector of constraints
@@ -266,7 +266,7 @@ impl Constraint {
     where
         T: IntoIterator<Item = u16>,
     {
-        percentages.into_iter().map(Self::Percentage).collect_vec()
+        percentages.into_iter().map(Self::Percentage).collect()
     }
 
     /// Convert an iterator of maxes into a vector of constraints
@@ -283,7 +283,7 @@ impl Constraint {
     where
         T: IntoIterator<Item = u16>,
     {
-        maxes.into_iter().map(Self::Max).collect_vec()
+        maxes.into_iter().map(Self::Max).collect()
     }
 
     /// Convert an iterator of mins into a vector of constraints
@@ -300,7 +300,7 @@ impl Constraint {
     where
         T: IntoIterator<Item = u16>,
     {
-        mins.into_iter().map(Self::Min).collect_vec()
+        mins.into_iter().map(Self::Min).collect()
     }
 
     /// Convert an iterator of proportional factors into a vector of constraints
@@ -317,10 +317,7 @@ impl Constraint {
     where
         T: IntoIterator<Item = u16>,
     {
-        proportional_factors
-            .into_iter()
-            .map(Self::Fill)
-            .collect_vec()
+        proportional_factors.into_iter().map(Self::Fill).collect()
     }
 }
 

src/layout/layout.rs

@@ -107,7 +107,7 @@ thread_local! {
 /// example](https://camo.githubusercontent.com/77d22f3313b782a81e5e033ef82814bb48d786d2598699c27f8e757ccee62021/68747470733a2f2f7668732e636861726d2e73682f7668732d315a4e6f4e4c4e6c4c746b4a58706767396e435635652e676966)
 ///
 /// [`cassowary-rs`]: https://crates.io/crates/cassowary
-/// [Examples]: https://github.com/ratatui-org/ratatui/blob/main/examples/README.md
+/// [Examples]: https://github.com/ratatui/ratatui/blob/main/examples/README.md
 #[derive(Debug, Default, Clone, Eq, PartialEq, Hash)]
 pub struct Layout {
     direction: Direction,
@@ -428,7 +428,7 @@ impl Layout {
     /// ```rust
     /// # use ratatui::prelude::*;
     /// # fn render(frame: &mut Frame) {
-    /// let area = frame.size();
+    /// let area = frame.area();
     /// let layout = Layout::vertical([Constraint::Length(1), Constraint::Min(0)]);
     /// let [top, main] = layout.areas(area);
     ///
@@ -460,7 +460,7 @@ impl Layout {
     /// ```rust
     /// # use ratatui::prelude::*;
     /// # fn render(frame: &mut Frame) {
-    /// let area = frame.size();
+    /// let area = frame.area();
     /// let layout = Layout::vertical([Constraint::Length(1), Constraint::Min(0)]);
     /// let [top, main] = layout.areas(area);
     /// let [before, inbetween, after] = layout.spacers(area);
@@ -1315,9 +1315,9 @@ mod tests {
                 .flex(flex)
                 .split(area);
             let mut buffer = Buffer::empty(area);
-            for (i, c) in ('a'..='z').take(constraints.len()).enumerate() {
+            for (c, &area) in ('a'..='z').take(constraints.len()).zip(layout.iter()) {
                 let s = c.to_string().repeat(area.width as usize);
-                Paragraph::new(s).render(layout[i], &mut buffer);
+                Paragraph::new(s).render(area, &mut buffer);
             }
             assert_eq!(buffer, Buffer::with_lines([expected]));
         }
@@ -1888,7 +1888,7 @@ mod tests {
             );
 
             // minimal bug from
-            // https://github.com/ratatui-org/ratatui/pull/404#issuecomment-1681850644
+            // https://github.com/ratatui/ratatui/pull/404#issuecomment-1681850644
             // TODO: check if this bug is now resolved?
             let layout = Layout::default()
                 .constraints([Min(1), Length(0), Min(1)])

src/layout/rect.rs

@@ -236,7 +236,7 @@ impl Rect {
     /// ```rust
     /// # use ratatui::prelude::*;
     /// # fn render(frame: &mut Frame) {
-    /// let area = frame.size();
+    /// let area = frame.area();
     /// let rect = Rect::new(0, 0, 100, 100).clamp(area);
     /// # }
     /// ```

src/lib.rs

@@ -1,4 +1,4 @@
-//! ![Demo](https://github.com/ratatui-org/ratatui/blob/87ae72dbc756067c97f6400d3e2a58eeb383776e/examples/demo2-destroy.gif?raw=true)
+//! ![Demo](https://github.com/ratatui/ratatui/blob/87ae72dbc756067c97f6400d3e2a58eeb383776e/examples/demo2-destroy.gif?raw=true)
 //!
 //! <div align="center">
 //!
@@ -102,53 +102,28 @@
 //! ### Example
 //!
 //! ```rust,no_run
-//! use std::io::{self, stdout};
-//!
 //! use ratatui::{
-//!     backend::CrosstermBackend,
-//!     crossterm::{
-//!         event::{self, Event, KeyCode},
-//!         terminal::{
-//!             disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen,
-//!         },
-//!         ExecutableCommand,
-//!     },
+//!     crossterm::event::{self, Event, KeyCode, KeyEventKind},
 //!     widgets::{Block, Paragraph},
-//!     Frame, Terminal,
 //! };
 //!
-//! fn main() -> io::Result<()> {
-//!     enable_raw_mode()?;
-//!     stdout().execute(EnterAlternateScreen)?;
-//!     let mut terminal = Terminal::new(CrosstermBackend::new(stdout()))?;
-//!
-//!     let mut should_quit = false;
-//!     while !should_quit {
-//!         terminal.draw(ui)?;
-//!         should_quit = handle_events()?;
-//!     }
-//!
-//!     disable_raw_mode()?;
-//!     stdout().execute(LeaveAlternateScreen)?;
-//!     Ok(())
-//! }
-//!
-//! fn handle_events() -> io::Result<bool> {
-//!     if event::poll(std::time::Duration::from_millis(50))? {
+//! fn main() -> std::io::Result<()> {
+//!     let mut terminal = ratatui::init();
+//!     loop {
+//!         terminal.draw(|frame| {
+//!             frame.render_widget(
+//!                 Paragraph::new("Hello World!").block(Block::bordered().title("Greeting")),
+//!                 frame.area(),
+//!             );
+//!         })?;
 //!         if let Event::Key(key) = event::read()? {
-//!             if key.kind == event::KeyEventKind::Press && key.code == KeyCode::Char('q') {
-//!                 return Ok(true);
+//!             if key.kind == KeyEventKind::Press && key.code == KeyCode::Char('q') {
+//!                 break;
 //!             }
 //!         }
 //!     }
-//!     Ok(false)
-//! }
-//!
-//! fn ui(frame: &mut Frame) {
-//!     frame.render_widget(
-//!         Paragraph::new("Hello World!").block(Block::bordered().title("Greeting")),
-//!         frame.size(),
-//!     );
+//!     ratatui::restore();
+//!     Ok(())
 //! }
 //! ```
 //!
@@ -170,13 +145,13 @@
 //!     Frame,
 //! };
 //!
-//! fn ui(frame: &mut Frame) {
+//! fn draw(frame: &mut Frame) {
 //!     let [title_area, main_area, status_area] = Layout::vertical([
 //!         Constraint::Length(1),
 //!         Constraint::Min(0),
 //!         Constraint::Length(1),
 //!     ])
-//!     .areas(frame.size());
+//!     .areas(frame.area());
 //!     let [left_area, right_area] =
 //!         Layout::horizontal([Constraint::Percentage(50), Constraint::Percentage(50)])
 //!             .areas(main_area);
@@ -213,8 +188,8 @@
 //!     Frame,
 //! };
 //!
-//! fn ui(frame: &mut Frame) {
-//!     let areas = Layout::vertical([Constraint::Length(1); 4]).split(frame.size());
+//! fn draw(frame: &mut Frame) {
+//!     let areas = Layout::vertical([Constraint::Length(1); 4]).split(frame.area());
 //!
 //!     let line = Line::from(vec![
 //!         Span::raw("Hello "),
@@ -259,21 +234,21 @@
 //! [Handling Events]: https://ratatui.rs/concepts/event-handling/
 //! [Layout]: https://ratatui.rs/how-to/layout/
 //! [Styling Text]: https://ratatui.rs/how-to/render/style-text/
-//! [templates]: https://github.com/ratatui-org/templates/
-//! [Examples]: https://github.com/ratatui-org/ratatui/tree/main/examples/README.md
-//! [Report a bug]: https://github.com/ratatui-org/ratatui/issues/new?labels=bug&projects=&template=bug_report.md
-//! [Request a Feature]: https://github.com/ratatui-org/ratatui/issues/new?labels=enhancement&projects=&template=feature_request.md
-//! [Create a Pull Request]: https://github.com/ratatui-org/ratatui/compare
+//! [templates]: https://github.com/ratatui/templates/
+//! [Examples]: https://github.com/ratatui/ratatui/tree/main/examples/README.md
+//! [Report a bug]: https://github.com/ratatui/ratatui/issues/new?labels=bug&projects=&template=bug_report.md
+//! [Request a Feature]: https://github.com/ratatui/ratatui/issues/new?labels=enhancement&projects=&template=feature_request.md
+//! [Create a Pull Request]: https://github.com/ratatui/ratatui/compare
 //! [git-cliff]: https://git-cliff.org
 //! [Conventional Commits]: https://www.conventionalcommits.org
 //! [API Docs]: https://docs.rs/ratatui
-//! [Changelog]: https://github.com/ratatui-org/ratatui/blob/main/CHANGELOG.md
-//! [Contributing]: https://github.com/ratatui-org/ratatui/blob/main/CONTRIBUTING.md
-//! [Breaking Changes]: https://github.com/ratatui-org/ratatui/blob/main/BREAKING-CHANGES.md
+//! [Changelog]: https://github.com/ratatui/ratatui/blob/main/CHANGELOG.md
+//! [Contributing]: https://github.com/ratatui/ratatui/blob/main/CONTRIBUTING.md
+//! [Breaking Changes]: https://github.com/ratatui/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
+//! [docsrs-hello]: https://github.com/ratatui/ratatui/blob/c3c3c289b1eb8d562afb1931adb4dc719cd48490/examples/docsrs-hello.png?raw=true
+//! [docsrs-layout]: https://github.com/ratatui/ratatui/blob/c3c3c289b1eb8d562afb1931adb4dc719cd48490/examples/docsrs-layout.png?raw=true
+//! [docsrs-styling]: https://github.com/ratatui/ratatui/blob/c3c3c289b1eb8d562afb1931adb4dc719cd48490/examples/docsrs-styling.png?raw=true
 //! [`Frame`]: terminal::Frame
 //! [`render_widget`]: terminal::Frame::render_widget
 //! [`Widget`]: widgets::Widget
@@ -292,15 +267,15 @@
 //! [Termion]: https://crates.io/crates/termion
 //! [Termwiz]: https://crates.io/crates/termwiz
 //! [tui-rs]: https://crates.io/crates/tui
-//! [GitHub Sponsors]: https://github.com/sponsors/ratatui-org
+//! [GitHub Sponsors]: https://github.com/sponsors/ratatui
 //! [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&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
+//! [CI Badge]: https://img.shields.io/github/actions/workflow/status/ratatui/ratatui/ci.yml?style=flat-square&logo=github
+//! [CI Workflow]: https://github.com/ratatui/ratatui/actions/workflows/ci.yml
+//! [Codecov Badge]: https://img.shields.io/codecov/c/github/ratatui/ratatui?logo=codecov&style=flat-square&token=BAQ8SOKEST&color=C43AC3&logoColor=C43AC3
+//! [Codecov]: https://app.codecov.io/gh/ratatui/ratatui
+//! [Deps.rs Badge]: https://deps.rs/repo/github/ratatui/ratatui/status.svg?style=flat-square
+//! [Deps.rs]: https://deps.rs/repo/github/ratatui/ratatui
 //! [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&logoColor=E05D44
@@ -308,21 +283,25 @@
 //! [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
+//! [Sponsors Badge]: https://img.shields.io/github/sponsors/ratatui?logo=github&style=flat-square&color=1370D3
 
 // show the feature flags in the generated documentation
 #![cfg_attr(docsrs, feature(doc_auto_cfg))]
 #![doc(
-    html_logo_url = "https://raw.githubusercontent.com/ratatui-org/ratatui/main/assets/logo.png",
-    html_favicon_url = "https://raw.githubusercontent.com/ratatui-org/ratatui/main/assets/favicon.ico"
+    html_logo_url = "https://raw.githubusercontent.com/ratatui/ratatui/main/assets/logo.png",
+    html_favicon_url = "https://raw.githubusercontent.com/ratatui/ratatui/main/assets/favicon.ico"
 )]
 
 /// re-export the `crossterm` crate so that users don't have to add it as a dependency
 #[cfg(feature = "crossterm")]
 pub use crossterm;
+#[cfg(feature = "crossterm")]
+pub use terminal::{
+    init, init_with_options, restore, try_init, try_init_with_options, try_restore, DefaultTerminal,
+};
 pub use terminal::{CompletedFrame, Frame, Terminal, TerminalOptions, Viewport};
 /// re-export the `termion` crate so that users don't have to add it as a dependency
-#[cfg(feature = "termion")]
+#[cfg(all(not(windows), feature = "termion"))]
 pub use termion;
 /// re-export the `termwiz` crate so that users don't have to add it as a dependency
 #[cfg(feature = "termwiz")]

src/prelude.rs

@@ -19,7 +19,7 @@
 
 #[cfg(feature = "crossterm")]
 pub use crate::backend::CrosstermBackend;
-#[cfg(feature = "termion")]
+#[cfg(all(not(windows), feature = "termion"))]
 pub use crate::backend::TermionBackend;
 #[cfg(feature = "termwiz")]
 pub use crate::backend::TermwizBackend;

src/style/color.rs

@@ -113,7 +113,7 @@ pub enum Color {
     /// If the terminal does not support true color, code using the  [`TermwizBackend`] will
     /// fallback to the default text color. Crossterm and Termion do not have this capability and
     /// the display will be unpredictable (e.g. Terminal.app may display glitched blinking text).
-    /// See <https://github.com/ratatui-org/ratatui/issues/475> for an example of this problem.
+    /// See <https://github.com/ratatui/ratatui/issues/475> for an example of this problem.
     ///
     /// See also: <https://en.wikipedia.org/wiki/ANSI_escape_code#24-bit>
     ///

src/style/stylize.rs

@@ -346,7 +346,7 @@ mod tests {
         // issue as above without the `Styled` trait impl for `String`
         let items = [String::from("a"), String::from("b")];
         let sss = items.iter().map(|s| format!("{s}{s}").red()).collect_vec();
-        assert_eq!(sss, vec![Span::from("aa").red(), Span::from("bb").red()]);
+        assert_eq!(sss, [Span::from("aa").red(), Span::from("bb").red()]);
     }
 
     #[test]

src/terminal.rs

@@ -18,7 +18,7 @@
 //! let backend = CrosstermBackend::new(stdout());
 //! let mut terminal = Terminal::new(backend)?;
 //! terminal.draw(|frame| {
-//!     let area = frame.size();
+//!     let area = frame.area();
 //!     frame.render_widget(Paragraph::new("Hello world!"), area);
 //! })?;
 //! # std::io::Result::Ok(())
@@ -32,9 +32,15 @@
 //! [`Buffer`]: crate::buffer::Buffer
 
 mod frame;
+#[cfg(feature = "crossterm")]
+mod init;
 mod terminal;
 mod viewport;
 
 pub use frame::{CompletedFrame, Frame};
+#[cfg(feature = "crossterm")]
+pub use init::{
+    init, init_with_options, restore, try_init, try_init_with_options, try_restore, DefaultTerminal,
+};
 pub use terminal::{Options as TerminalOptions, Terminal};
 pub use viewport::Viewport;

src/terminal/frame.rs

@@ -60,7 +60,7 @@ impl Frame<'_> {
     /// If your app listens for a resize event from the backend, it should ignore the values from
     /// the event for any calculations that are used to render the current frame and use this value
     /// instead as this is the area of the buffer that is used to render the current frame.
-    #[deprecated = "use .area() as its the more correct name"]
+    #[deprecated = "use .area() as it's the more correct name"]
     pub const fn size(&self) -> Rect {
         self.viewport_area
     }

src/terminal/init.rs

@@ -0,0 +1,244 @@
+use std::io::{self, stdout, Stdout};
+
+use crossterm::{
+    execute,
+    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+};
+
+use super::TerminalOptions;
+use crate::{backend::CrosstermBackend, Terminal};
+
+/// A type alias for the default terminal type.
+///
+/// This is a [`Terminal`] using the [`CrosstermBackend`] which writes to [`Stdout`]. This is a
+/// reasonable default for most applications. To use a different backend or output stream, instead
+/// use [`Terminal`] and a [backend][`crate::backend`] of your choice directly.
+pub type DefaultTerminal = Terminal<CrosstermBackend<Stdout>>;
+
+/// Initialize a terminal with reasonable defaults for most applications.
+///
+/// This will create a new [`DefaultTerminal`] and initialize it with the following defaults:
+///
+/// - Backend: [`CrosstermBackend`] writing to [`Stdout`]
+/// - Raw mode is enabled
+/// - Alternate screen buffer enabled
+/// - A panic hook is installed that restores the terminal before panicking. Ensure that this method
+///   is called after any other panic hooks that may be installed to ensure that the terminal is
+///   restored before those hooks are called.
+///
+/// For more control over the terminal initialization, use [`Terminal::new`] or
+/// [`Terminal::with_options`].
+///
+/// Ensure that this method is called *after* your app installs any other panic hooks to ensure the
+/// terminal is restored before the other hooks are called.
+///
+/// Generally, use this function instead of [`try_init`] to ensure that the terminal is restored
+/// correctly if any of the initialization steps fail. If you need to handle the error yourself, use
+/// [`try_init`] instead.
+///
+/// # Panics
+///
+/// This function will panic if any of the following steps fail:
+///
+/// - Enabling raw mode
+/// - Entering the alternate screen buffer
+/// - Creating the terminal fails due to being unable to calculate the terminal size
+///
+/// # Examples
+///
+/// ```rust,no_run
+/// let terminal = ratatui::init();
+/// ```
+pub fn init() -> DefaultTerminal {
+    try_init().expect("failed to initialize terminal")
+}
+
+/// Try to initialize a terminal using reasonable defaults for most applications.
+///
+/// This function will attempt to create a [`DefaultTerminal`] and initialize it with the following
+/// defaults:
+///
+/// - Raw mode is enabled
+/// - Alternate screen buffer enabled
+/// - A panic hook is installed that restores the terminal before panicking.
+/// - A [`Terminal`] is created using [`CrosstermBackend`] writing to [`Stdout`]
+///
+/// If any of these steps fail, the error is returned.
+///
+/// Ensure that this method is called *after* your app installs any other panic hooks to ensure the
+/// terminal is restored before the other hooks are called.
+///
+/// Generally, you should use [`init`] instead of this function, as the panic hook installed by this
+/// function will ensure that any failures during initialization will restore the terminal before
+/// panicking. This function is provided for cases where you need to handle the error yourself.
+///
+/// # Examples
+///
+/// ```no_run
+/// let terminal = ratatui::try_init()?;
+/// # Ok::<(), std::io::Error>(())
+/// ```
+pub fn try_init() -> io::Result<DefaultTerminal> {
+    set_panic_hook();
+    enable_raw_mode()?;
+    execute!(stdout(), EnterAlternateScreen)?;
+    let backend = CrosstermBackend::new(stdout());
+    Terminal::new(backend)
+}
+
+/// Initialize a terminal with the given options and reasonable defaults.
+///
+/// This function allows the caller to specify a custom [`Viewport`] via the [`TerminalOptions`]. It
+/// will create a new [`DefaultTerminal`] and initialize it with the given options and the following
+/// defaults:
+///
+/// [`Viewport`]: crate::Viewport
+///
+/// - Raw mode is enabled
+/// - A panic hook is installed that restores the terminal before panicking.
+///
+/// Unlike [`init`], this function does not enter the alternate screen buffer as this may not be
+/// desired in all cases. If you need the alternate screen buffer, you should enable it manually
+/// after calling this function.
+///
+/// For more control over the terminal initialization, use [`Terminal::with_options`].
+///
+/// Ensure that this method is called *after* your app installs any other panic hooks to ensure the
+/// terminal is restored before the other hooks are called.
+///
+/// Generally, use this function instead of [`try_init_with_options`] to ensure that the terminal is
+/// restored correctly if any of the initialization steps fail. If you need to handle the error
+/// yourself, use [`try_init_with_options`] instead.
+///
+/// # Panics
+///
+/// This function will panic if any of the following steps fail:
+///
+/// - Enabling raw mode
+/// - Creating the terminal fails due to being unable to calculate the terminal size
+///
+/// # Examples
+///
+/// ```rust,no_run
+/// use ratatui::{TerminalOptions, Viewport};
+///
+/// let options = TerminalOptions {
+///     viewport: Viewport::Inline(5),
+/// };
+/// let terminal = ratatui::init_with_options(options);
+/// ```
+pub fn init_with_options(options: TerminalOptions) -> DefaultTerminal {
+    try_init_with_options(options).expect("failed to initialize terminal")
+}
+
+/// Try to initialize a terminal with the given options and reasonable defaults.
+///
+/// This function allows the caller to specify a custom [`Viewport`] via the [`TerminalOptions`]. It
+/// will attempt to create a [`DefaultTerminal`] and initialize it with the given options and the
+/// following defaults:
+///
+/// [`Viewport`]: crate::Viewport
+///
+/// - Raw mode is enabled
+/// - A panic hook is installed that restores the terminal before panicking.
+///
+/// Unlike [`try_init`], this function does not enter the alternate screen buffer as this may not be
+/// desired in all cases. If you need the alternate screen buffer, you should enable it manually
+/// after calling this function.
+///
+/// If any of these steps fail, the error is returned.
+///
+/// Ensure that this method is called *after* your app installs any other panic hooks to ensure the
+/// terminal is restored before the other hooks are called.
+///
+/// Generally, you should use [`init_with_options`] instead of this function, as the panic hook
+/// installed by this function will ensure that any failures during initialization will restore the
+/// terminal before panicking. This function is provided for cases where you need to handle the
+/// error yourself.
+///
+/// # Examples
+///
+/// ```no_run
+/// use ratatui::{TerminalOptions, Viewport};
+///
+/// let options = TerminalOptions {
+///     viewport: Viewport::Inline(5),
+/// };
+/// let terminal = ratatui::try_init_with_options(options)?;
+/// # Ok::<(), std::io::Error>(())
+/// ```
+pub fn try_init_with_options(options: TerminalOptions) -> io::Result<DefaultTerminal> {
+    set_panic_hook();
+    enable_raw_mode()?;
+    let backend = CrosstermBackend::new(stdout());
+    Terminal::with_options(backend, options)
+}
+
+/// Restores the terminal to its original state.
+///
+/// This function should be called before the program exits to ensure that the terminal is
+/// restored to its original state.
+///
+/// This function will attempt to restore the terminal to its original state by performing the
+/// following steps:
+///
+/// 1. Raw mode is disabled.
+/// 2. The alternate screen buffer is left.
+///
+/// If either of these steps fail, the error is printed to stderr and ignored.
+///
+/// Use this function over [`try_restore`] when you don't need to handle the error yourself, as
+/// ignoring the error is generally the correct behavior when cleaning up before exiting. If you
+/// need to handle the error yourself, use [`try_restore`] instead.
+///
+/// # Examples
+///
+/// ```rust,no_run
+/// ratatui::restore();
+/// ```
+pub fn restore() {
+    if let Err(err) = try_restore() {
+        // There's not much we can do if restoring the terminal fails, so we just print the error
+        eprintln!("Failed to restore terminal: {err}");
+    }
+}
+
+/// Restore the terminal to its original state.
+///
+/// This function will attempt to restore the terminal to its original state by performing the
+/// following steps:
+///
+/// 1. Raw mode is disabled.
+/// 2. The alternate screen buffer is left.
+///
+/// If either of these steps fail, the error is returned.
+///
+/// Use [`restore`] instead of this function when you don't need to handle the error yourself, as
+/// ignoring the error is generally the correct behavior when cleaning up before exiting. If you
+/// need to handle the error yourself, use this function instead.
+///
+/// # Examples
+///
+/// ```no_run
+/// ratatui::try_restore()?;
+/// # Ok::<(), std::io::Error>(())
+/// ```
+pub fn try_restore() -> io::Result<()> {
+    // disabling raw mode first is important as it has more side effects than leaving the alternate
+    // screen buffer
+    disable_raw_mode()?;
+    execute!(stdout(), LeaveAlternateScreen)?;
+    Ok(())
+}
+
+/// Sets a panic hook that restores the terminal before panicking.
+///
+/// Replaces the panic hook with a one that will restore the terminal state before calling the
+/// original panic hook. This ensures that the terminal is left in a good state when a panic occurs.
+fn set_panic_hook() {
+    let hook = std::panic::take_hook();
+    std::panic::set_hook(Box::new(move |info| {
+        restore();
+        hook(info);
+    }));
+}

src/terminal/terminal.rs

@@ -1,6 +1,8 @@
 use std::io;
 
-use crate::{backend::ClearType, prelude::*, CompletedFrame, TerminalOptions, Viewport};
+use crate::{
+    backend::ClearType, buffer::Cell, prelude::*, CompletedFrame, TerminalOptions, Viewport,
+};
 
 /// An interface to interact and draw [`Frame`]s on the user's terminal.
 ///
@@ -36,7 +38,7 @@ use crate::{backend::ClearType, prelude::*, CompletedFrame, TerminalOptions, Vie
 /// let backend = CrosstermBackend::new(stdout());
 /// let mut terminal = Terminal::new(backend)?;
 /// terminal.draw(|frame| {
-///     let area = frame.size();
+///     let area = frame.area();
 ///     frame.render_widget(Paragraph::new("Hello World!"), area);
 /// })?;
 /// # std::io::Result::Ok(())
@@ -203,7 +205,6 @@ where
     /// of the screen.
     pub fn resize(&mut self, area: Rect) -> io::Result<()> {
         let next_area = match self.viewport {
-            Viewport::Fullscreen => area,
             Viewport::Inline(height) => {
                 let offset_in_previous_viewport = self
                     .last_known_cursor_pos
@@ -217,7 +218,7 @@ where
                 )?
                 .0
             }
-            Viewport::Fixed(area) => area,
+            Viewport::Fixed(_) | Viewport::Fullscreen => area,
         };
         self.set_viewport_area(next_area);
         self.clear()?;
@@ -282,7 +283,7 @@ where
     ///
     /// // with a closure
     /// terminal.draw(|frame| {
-    ///     let area = frame.size();
+    ///     let area = frame.area();
     ///     frame.render_widget(Paragraph::new("Hello World!"), area);
     ///     frame.set_cursor_position(Position { x: 0, y: 0 });
     /// })?;
@@ -291,7 +292,7 @@ where
     /// terminal.draw(render)?;
     ///
     /// fn render(frame: &mut ratatui::Frame) {
-    ///     frame.render_widget(Paragraph::new("Hello World!"), frame.size());
+    ///     frame.render_widget(Paragraph::new("Hello World!"), frame.area());
     /// }
     /// # std::io::Result::Ok(())
     /// ```
@@ -354,7 +355,7 @@ where
     /// // with a closure
     /// terminal.try_draw(|frame| {
     ///     let value: u8 = "not a number".parse().map_err(io::Error::other)?;
-    ///     let area = frame.size();
+    ///     let area = frame.area();
     ///     frame.render_widget(Paragraph::new("Hello World!"), area);
     ///     frame.set_cursor_position(Position { x: 0, y: 0 });
     ///     io::Result::Ok(())
@@ -365,7 +366,7 @@ where
     ///
     /// fn render(frame: &mut ratatui::Frame) -> io::Result<()> {
     ///     let value: u8 = "not a number".parse().map_err(io::Error::other)?;
-    ///     frame.render_widget(Paragraph::new("Hello World!"), frame.size());
+    ///     frame.render_widget(Paragraph::new("Hello World!"), frame.area());
     ///     Ok(())
     /// }
     /// # io::Result::Ok(())
@@ -494,32 +495,58 @@ where
     }
 
     /// Insert some content before the current inline viewport. This has no effect when the
-    /// viewport is fullscreen.
+    /// viewport is not inline.
     ///
-    /// This function scrolls down the current viewport by the given height. The newly freed space
-    /// is then made available to the `draw_fn` closure through a writable `Buffer`.
+    /// The `draw_fn` closure will be called to draw into a writable `Buffer` that is `height`
+    /// lines tall. The content of that `Buffer` will then be inserted before the viewport.
+    ///
+    /// If the viewport isn't yet at the bottom of the screen, inserted lines will push it towards
+    /// the bottom. Once the viewport is at the bottom of the screen, inserted lines will scroll
+    /// the area of the screen above the viewport upwards.
     ///
     /// Before:
     /// ```ignore
-    /// +-------------------+
-    /// |                   |
-    /// |      viewport     |
-    /// |                   |
-    /// +-------------------+
+    /// +---------------------+
+    /// | pre-existing line 1 |
+    /// | pre-existing line 2 |
+    /// +---------------------+
+    /// |       viewport      |
+    /// +---------------------+
+    /// |                     |
+    /// |                     |
+    /// +---------------------+
     /// ```
     ///
-    /// After:
+    /// After inserting 2 lines:
     /// ```ignore
-    /// +-------------------+
-    /// |      buffer       |
-    /// +-------------------+
-    /// +-------------------+
-    /// |                   |
-    /// |      viewport     |
-    /// |                   |
-    /// +-------------------+
+    /// +---------------------+
+    /// | pre-existing line 1 |
+    /// | pre-existing line 2 |
+    /// |   inserted line 1   |
+    /// |   inserted line 2   |
+    /// +---------------------+
+    /// |       viewport      |
+    /// +---------------------+
+    /// +---------------------+
     /// ```
     ///
+    /// After inserting 2 more lines:
+    /// ```ignore
+    /// +---------------------+
+    /// | pre-existing line 2 |
+    /// |   inserted line 1   |
+    /// |   inserted line 2   |
+    /// |   inserted line 3   |
+    /// |   inserted line 4   |
+    /// +---------------------+
+    /// |       viewport      |
+    /// +---------------------+
+    /// ```
+    ///
+    /// If more lines are inserted than there is space on the screen, then the top lines will go
+    /// directly into the terminal's scrollback buffer. At the limit, if the viewport takes up the
+    /// whole screen, all lines will be inserted directly into the scrollback buffer.
+    ///
     /// # Examples
     ///
     /// ## Insert a single line before the current viewport
@@ -545,51 +572,121 @@ where
             return Ok(());
         }
 
-        // Clear the viewport off the screen
-        self.clear()?;
-
-        // Move the viewport by height, but don't move it past the bottom of the terminal
-        let viewport_at_bottom = self.last_known_area.bottom() - self.viewport_area.height;
-        self.set_viewport_area(Rect {
-            y: self
-                .viewport_area
-                .y
-                .saturating_add(height)
-                .min(viewport_at_bottom),
-            ..self.viewport_area
-        });
-
-        // Draw contents into buffer
+        // The approach of this function is to first render all of the lines to insert into a
+        // temporary buffer, and then to loop drawing chunks from the buffer to the screen. drawing
+        // this buffer onto the screen.
         let area = Rect {
-            x: self.viewport_area.left(),
+            x: 0,
             y: 0,
             width: self.viewport_area.width,
             height,
         };
         let mut buffer = Buffer::empty(area);
         draw_fn(&mut buffer);
+        let mut buffer = buffer.content.as_slice();
 
-        // Split buffer into screen-sized chunks and draw
-        let max_chunk_size = (self.viewport_area.top() * area.width).into();
-        for buffer_content_chunk in buffer.content.chunks(max_chunk_size) {
-            let chunk_size = buffer_content_chunk.len() as u16 / area.width;
+        // Use i32 variables so we don't have worry about overflowed u16s when adding, or about
+        // negative results when subtracting.
+        let mut drawn_height: i32 = self.viewport_area.top().into();
+        let mut buffer_height: i32 = height.into();
+        let viewport_height: i32 = self.viewport_area.height.into();
+        let screen_height: i32 = self.last_known_area.height.into();
 
-            self.backend
-                .append_lines(self.viewport_area.height.saturating_sub(1) + chunk_size)?;
-
-            let iter = buffer_content_chunk.iter().enumerate().map(|(i, c)| {
-                let (x, y) = buffer.pos_of(i);
-                (
-                    x,
-                    self.viewport_area.top().saturating_sub(chunk_size) + y,
-                    c,
-                )
-            });
-            self.backend.draw(iter)?;
-            self.backend.flush()?;
-            self.set_cursor_position(self.viewport_area.as_position())?;
+        // The algorithm here is to loop, drawing large chunks of text (up to a screen-full at a
+        // time), until the remainder of the buffer plus the viewport fits on the screen. We choose
+        // this loop condition because it guarantees that we can write the remainder of the buffer
+        // with just one call to Self::draw_lines().
+        while buffer_height + viewport_height > screen_height {
+            // We will draw as much of the buffer as possible on this iteration in order to make
+            // forward progress. So we have:
+            //
+            //     to_draw = min(buffer_height, screen_height)
+            //
+            // We may need to scroll the screen up to make room to draw. We choose the minimal
+            // possible scroll amount so we don't end up with the viewport sitting in the middle of
+            // the screen when this function is done. The amount to scroll by is:
+            //
+            //     scroll_up = max(0, drawn_height + to_draw - screen_height)
+            //
+            // We want `scroll_up` to be enough so that, after drawing, we have used the whole
+            // screen (drawn_height - scroll_up + to_draw = screen_height). However, there might
+            // already be enough room on the screen to draw without scrolling (drawn_height +
+            // to_draw <= screen_height). In this case, we just don't scroll at all.
+            let to_draw = buffer_height.min(screen_height);
+            let scroll_up = 0.max(drawn_height + to_draw - screen_height);
+            self.scroll_up(scroll_up as u16)?;
+            buffer = self.draw_lines((drawn_height - scroll_up) as u16, to_draw as u16, buffer)?;
+            drawn_height += to_draw - scroll_up;
+            buffer_height -= to_draw;
         }
 
+        // There is now enough room on the screen for the remaining buffer plus the viewport,
+        // though we may still need to scroll up some of the existing text first. It's possible
+        // that by this point we've drained the buffer, but we may still need to scroll up to make
+        // room for the viewport.
+        //
+        // We want to scroll up the exact amount that will leave us completely filling the screen.
+        // However, it's possible that the viewport didn't start on the bottom of the screen and
+        // the added lines weren't enough to push it all the way to the bottom. We deal with this
+        // case by just ensuring that our scroll amount is non-negative.
+        //
+        // We want:
+        //   screen_height = drawn_height - scroll_up + buffer_height + viewport_height
+        // Or, equivalently:
+        //   scroll_up = drawn_height + buffer_height + viewport_height - screen_height
+        let scroll_up = 0.max(drawn_height + buffer_height + viewport_height - screen_height);
+        self.scroll_up(scroll_up as u16)?;
+        self.draw_lines(
+            (drawn_height - scroll_up) as u16,
+            buffer_height as u16,
+            buffer,
+        )?;
+        drawn_height += buffer_height - scroll_up;
+
+        self.set_viewport_area(Rect {
+            y: drawn_height as u16,
+            ..self.viewport_area
+        });
+
+        // Clear the viewport off the screen. We didn't clear earlier for two reasons. First, it
+        // wasn't necessary because the buffer we drew out of isn't sparse, so it overwrote
+        // whatever was on the screen. Second, there is a weird bug with tmux where a full screen
+        // clear plus immediate scrolling causes some garbage to go into the scrollback.
+        self.clear()?;
+
+        Ok(())
+    }
+
+    /// Draw lines at the given vertical offset. The slice of cells must contain enough cells
+    /// for the requested lines. A slice of the unused cells are returned.
+    fn draw_lines<'a>(
+        &mut self,
+        y_offset: u16,
+        lines_to_draw: u16,
+        cells: &'a [Cell],
+    ) -> io::Result<&'a [Cell]> {
+        let width: usize = self.last_known_area.width.into();
+        let (to_draw, remainder) = cells.split_at(width * lines_to_draw as usize);
+        if lines_to_draw > 0 {
+            let iter = to_draw
+                .iter()
+                .enumerate()
+                .map(|(i, c)| ((i % width) as u16, y_offset + (i / width) as u16, c));
+            self.backend.draw(iter)?;
+            self.backend.flush()?;
+        }
+        Ok(remainder)
+    }
+
+    /// Scroll the whole screen up by the given number of lines.
+    fn scroll_up(&mut self, lines_to_scroll: u16) -> io::Result<()> {
+        if lines_to_scroll > 0 {
+            self.set_cursor_position(Position::new(
+                0,
+                self.last_known_area.height.saturating_sub(1),
+            ))?;
+            self.backend.append_lines(lines_to_scroll)?;
+        }
         Ok(())
     }
 }

src/text/line.rs

@@ -741,11 +741,11 @@ mod tests {
     #[test]
     fn raw_str() {
         let line = Line::raw("test content");
-        assert_eq!(line.spans, vec![Span::raw("test content")]);
+        assert_eq!(line.spans, [Span::raw("test content")]);
         assert_eq!(line.alignment, None);
 
         let line = Line::raw("a\nb");
-        assert_eq!(line.spans, vec![Span::raw("a"), Span::raw("b")]);
+        assert_eq!(line.spans, [Span::raw("a"), Span::raw("b")]);
         assert_eq!(line.alignment, None);
     }
 
@@ -754,7 +754,7 @@ mod tests {
         let style = Style::new().yellow();
         let content = "Hello, world!";
         let line = Line::styled(content, style);
-        assert_eq!(line.spans, vec![Span::raw(content)]);
+        assert_eq!(line.spans, [Span::raw(content)]);
         assert_eq!(line.style, style);
     }
 
@@ -763,7 +763,7 @@ mod tests {
         let style = Style::new().yellow();
         let content = String::from("Hello, world!");
         let line = Line::styled(content.clone(), style);
-        assert_eq!(line.spans, vec![Span::raw(content)]);
+        assert_eq!(line.spans, [Span::raw(content)]);
         assert_eq!(line.style, style);
     }
 
@@ -772,7 +772,7 @@ mod tests {
         let style = Style::new().yellow();
         let content = Cow::from("Hello, world!");
         let line = Line::styled(content.clone(), style);
-        assert_eq!(line.spans, vec![Span::raw(content)]);
+        assert_eq!(line.spans, [Span::raw(content)]);
         assert_eq!(line.style, style);
     }
 
@@ -861,28 +861,28 @@ mod tests {
     fn from_string() {
         let s = String::from("Hello, world!");
         let line = Line::from(s);
-        assert_eq!(line.spans, vec![Span::from("Hello, world!")]);
+        assert_eq!(line.spans, [Span::from("Hello, world!")]);
 
         let s = String::from("Hello\nworld!");
         let line = Line::from(s);
-        assert_eq!(line.spans, vec![Span::from("Hello"), Span::from("world!")]);
+        assert_eq!(line.spans, [Span::from("Hello"), Span::from("world!")]);
     }
 
     #[test]
     fn from_str() {
         let s = "Hello, world!";
         let line = Line::from(s);
-        assert_eq!(line.spans, vec![Span::from("Hello, world!")]);
+        assert_eq!(line.spans, [Span::from("Hello, world!")]);
 
         let s = "Hello\nworld!";
         let line = Line::from(s);
-        assert_eq!(line.spans, vec![Span::from("Hello"), Span::from("world!")]);
+        assert_eq!(line.spans, [Span::from("Hello"), Span::from("world!")]);
     }
 
     #[test]
     fn to_line() {
         let line = 42.to_line();
-        assert_eq!(vec![Span::from("42")], line.spans);
+        assert_eq!(line.spans, [Span::from("42")]);
     }
 
     #[test]
@@ -925,7 +925,7 @@ mod tests {
     fn from_span() {
         let span = Span::styled("Hello, world!", Style::default().fg(Color::Yellow));
         let line = Line::from(span.clone());
-        assert_eq!(line.spans, vec![span],);
+        assert_eq!(line.spans, [span]);
     }
 
     #[test]
@@ -969,14 +969,14 @@ mod tests {
     #[test]
     fn extend() {
         let mut line = Line::from("Hello, ");
-        line.extend(vec![Span::raw("world!")]);
-        assert_eq!(line.spans, vec![Span::raw("Hello, "), Span::raw("world!")]);
+        line.extend([Span::raw("world!")]);
+        assert_eq!(line.spans, [Span::raw("Hello, "), Span::raw("world!")]);
 
         let mut line = Line::from("Hello, ");
-        line.extend(vec![Span::raw("world! "), Span::raw("How are you?")]);
+        line.extend([Span::raw("world! "), Span::raw("How are you?")]);
         assert_eq!(
             line.spans,
-            vec![
+            [
                 Span::raw("Hello, "),
                 Span::raw("world! "),
                 Span::raw("How are you?")
@@ -1193,7 +1193,7 @@ mod tests {
             assert_eq!(buf, Buffer::with_lines(["lo wo"]));
         }
 
-        /// Part of a regression test for <https://github.com/ratatui-org/ratatui/issues/1032> which
+        /// Part of a regression test for <https://github.com/ratatui/ratatui/issues/1032> which
         /// found panics with truncating lines that contained multi-byte characters.
         #[test]
         fn regression_1032() {
@@ -1209,7 +1209,7 @@ mod tests {
 
         /// Documentary test to highlight the crab emoji width / length discrepancy
         ///
-        /// Part of a regression test for <https://github.com/ratatui-org/ratatui/issues/1032> which
+        /// Part of a regression test for <https://github.com/ratatui/ratatui/issues/1032> which
         /// found panics with truncating lines that contained multi-byte characters.
         #[test]
         fn crab_emoji_width() {
@@ -1220,7 +1220,7 @@ mod tests {
             assert_eq!(crab.width(), 2); // display width
         }
 
-        /// Part of a regression test for <https://github.com/ratatui-org/ratatui/issues/1032> which
+        /// Part of a regression test for <https://github.com/ratatui/ratatui/issues/1032> which
         /// found panics with truncating lines that contained multi-byte characters.
         #[rstest]
         #[case::left_4(Alignment::Left, 4, "1234")]
@@ -1242,7 +1242,7 @@ mod tests {
             assert_eq!(buf, Buffer::with_lines([expected]));
         }
 
-        /// Part of a regression test for <https://github.com/ratatui-org/ratatui/issues/1032> which
+        /// Part of a regression test for <https://github.com/ratatui/ratatui/issues/1032> which
         /// found panics with truncating lines that contained multi-byte characters.
         ///
         /// centering is tricky because there's an ambiguity about whether to take one more char
@@ -1331,7 +1331,7 @@ mod tests {
             assert_eq!(buf, Buffer::with_lines([expected]));
         }
 
-        /// Part of a regression test for <https://github.com/ratatui-org/ratatui/issues/1032> which
+        /// Part of a regression test for <https://github.com/ratatui/ratatui/issues/1032> which
         /// found panics with truncating lines that contained multi-byte characters.
         ///
         /// Flag emoji are actually two independent characters, so they can be truncated in the
@@ -1345,7 +1345,7 @@ mod tests {
             assert_eq!(str.width(), 6); // flag is 2 display width
         }
 
-        /// Part of a regression test for <https://github.com/ratatui-org/ratatui/issues/1032> which
+        /// Part of a regression test for <https://github.com/ratatui/ratatui/issues/1032> which
         /// found panics with truncating lines that contained multi-byte characters.
         #[rstest]
         #[case::flag_1(1, " ")]

src/text/masked.rs

@@ -125,10 +125,10 @@ mod tests {
         let masked = Masked::new("12345", 'x');
 
         let text: Text = (&masked).into();
-        assert_eq!(text.lines, vec![Line::from("xxxxx")]);
+        assert_eq!(text.lines, [Line::from("xxxxx")]);
 
         let text: Text = masked.into();
-        assert_eq!(text.lines, vec![Line::from("xxxxx")]);
+        assert_eq!(text.lines, [Line::from("xxxxx")]);
     }
 
     #[test]

src/text/span.rs

@@ -81,7 +81,7 @@ use crate::{prelude::*, style::Styled, text::StyledGrapheme};
 /// use ratatui::prelude::*;
 ///
 /// # fn render_frame(frame: &mut Frame) {
-/// frame.render_widget("test content".green().on_yellow().italic(), frame.size());
+/// frame.render_widget("test content".green().on_yellow().italic(), frame.area());
 /// # }
 /// ```
 /// [`Line`]: crate::text::Line
@@ -569,7 +569,7 @@ mod tests {
         assert_eq!(Span::raw("").width(), 0);
         assert_eq!(Span::raw("test").width(), 4);
         assert_eq!(Span::raw("test content").width(), 12);
-        // Needs reconsideration: https://github.com/ratatui-org/ratatui/issues/1271
+        // Needs reconsideration: https://github.com/ratatui/ratatui/issues/1271
         assert_eq!(Span::raw("test\ncontent").width(), 12);
     }
 
@@ -786,7 +786,7 @@ mod tests {
         }
     }
 
-    /// Regression test for <https://github.com/ratatui-org/ratatui/issues/1160> One line contains
+    /// Regression test for <https://github.com/ratatui/ratatui/issues/1160> One line contains
     /// some Unicode Left-Right-Marks (U+200E)
     ///
     /// The issue was that a zero-width character at the end of the buffer causes the buffer bounds

src/text/text.rs

@@ -1,8 +1,6 @@
 #![warn(missing_docs)]
 use std::{borrow::Cow, fmt};
 
-use itertools::{Itertools, Position};
-
 use crate::{prelude::*, style::Styled};
 
 /// A string split over one or more lines.
@@ -632,12 +630,11 @@ impl<T: fmt::Display> ToText for T {
 
 impl fmt::Display for Text<'_> {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        for (position, line) in self.iter().with_position() {
-            if position == Position::Last {
-                write!(f, "{line}")?;
-            } else {
+        if let Some((last, rest)) = self.lines.split_last() {
+            for line in rest {
                 writeln!(f, "{line}")?;
             }
+            write!(f, "{last}")?;
         }
         Ok(())
     }
@@ -794,7 +791,7 @@ mod tests {
     #[test]
     fn from_line() {
         let text = Text::from(Line::from("The first line"));
-        assert_eq!(text.lines, vec![Line::from("The first line")]);
+        assert_eq!(text.lines, [Line::from("The first line")]);
     }
 
     #[rstest]
@@ -945,11 +942,12 @@ mod tests {
         );
     }
 
-    #[test]
-    fn display_raw_text() {
-        let text = Text::raw("The first line\nThe second line");
-
-        assert_eq!(format!("{text}"), "The first line\nThe second line");
+    #[rstest]
+    #[case::one_line("The first line")]
+    #[case::multiple_lines("The first line\nThe second line")]
+    fn display_raw_text(#[case] value: &str) {
+        let text = Text::raw(value);
+        assert_eq!(format!("{text}"), value);
     }
 
     #[test]
@@ -1041,7 +1039,7 @@ mod tests {
     fn push_line_empty() {
         let mut text = Text::default();
         text.push_line(Line::from("Hello, world!"));
-        assert_eq!(text.lines, vec![Line::from("Hello, world!")]);
+        assert_eq!(text.lines, [Line::from("Hello, world!")]);
     }
 
     #[test]
@@ -1063,7 +1061,7 @@ mod tests {
     fn push_span_empty() {
         let mut text = Text::default();
         text.push_span(Span::raw("Hello, world!"));
-        assert_eq!(text.lines, vec![Line::from(Span::raw("Hello, world!"))],);
+        assert_eq!(text.lines, [Line::from(Span::raw("Hello, world!"))]);
     }
 
     mod widget {

src/widgets.rs

@@ -68,7 +68,7 @@ use crate::{buffer::Buffer, layout::Rect, style::Style};
 /// internal widgets. In addition to the above benefit of rendering references to widgets, this also
 /// allows you to render boxed widgets. This is useful when you want to store a collection of
 /// widgets with different types. You can then iterate over the collection and render each widget.
-/// See <https://github.com/ratatui-org/ratatui/issues/1287> for more information.
+/// See <https://github.com/ratatui/ratatui/issues/1287> for more information.
 ///
 /// In general where you expect a widget to immutably work on its data, we recommended to implement
 /// `Widget` for a reference to the widget (`impl Widget for &MyWidget`). If you need to store state
@@ -88,7 +88,7 @@ use crate::{buffer::Buffer, layout::Rect, style::Style};
 /// # let mut terminal = Terminal::new(backend).unwrap();
 ///
 /// terminal.draw(|frame| {
-///     frame.render_widget(Clear, frame.size());
+///     frame.render_widget(Clear, frame.area());
 /// });
 /// ```
 ///
@@ -245,7 +245,7 @@ pub trait StatefulWidget {
 ///
 /// This trait was introduced in Ratatui 0.26.0 and is implemented for all the internal widgets. It
 /// is currently marked as unstable as we are still evaluating the API and may make changes in the
-/// future. See <https://github.com/ratatui-org/ratatui/issues/1287> for more information.
+/// future. See <https://github.com/ratatui/ratatui/issues/1287> for more information.
 ///
 /// A blanket implementation of `Widget` for `&W` where `W` implements `WidgetRef` is provided.
 ///
@@ -368,7 +368,7 @@ impl<W: WidgetRef> WidgetRef for Option<W> {
 ///
 /// This trait was introduced in Ratatui 0.26.0 and is implemented for all the internal stateful
 /// widgets. It is currently marked as unstable as we are still evaluating the API and may make
-/// changes in the future. See <https://github.com/ratatui-org/ratatui/issues/1287> for more
+/// changes in the future. See <https://github.com/ratatui/ratatui/issues/1287> for more
 /// information.
 ///
 /// A blanket implementation of `StatefulWidget` for `&W` where `W` implements `StatefulWidgetRef`

src/widgets/block.rs

@@ -288,7 +288,7 @@ impl<'a> Block<'a> {
     /// - [`Block::title_alignment`]
     /// - [`Block::title_position`]
     ///
-    /// [Block example]: https://github.com/ratatui-org/ratatui/blob/main/examples/README.md#block
+    /// [Block example]: https://github.com/ratatui/ratatui/blob/main/examples/README.md#block
     #[must_use = "method moves the value of self and returns the modified value"]
     pub fn title<T>(mut self, title: T) -> Self
     where
@@ -595,7 +595,7 @@ impl<'a> Block<'a> {
     /// let outer_block = Block::bordered().title("Outer");
     /// let inner_block = Block::bordered().title("Inner");
     ///
-    /// let outer_area = frame.size();
+    /// let outer_area = frame.area();
     /// let inner_area = outer_block.inner(outer_area);
     ///
     /// frame.render_widget(outer_block, outer_area);
@@ -787,7 +787,7 @@ impl Block<'_> {
     /// Currently (due to the way lines are truncated), the right side of the leftmost title will
     /// be cut off if the block is too small to fit all titles. This is not ideal and should be
     /// the left side of that leftmost that is cut off. This is due to the line being truncated
-    /// incorrectly. See <https://github.com/ratatui-org/ratatui/issues/932>
+    /// incorrectly. See <https://github.com/ratatui/ratatui/issues/932>
     #[allow(clippy::similar_names)]
     fn render_right_titles(&self, position: Position, area: Rect, buf: &mut Buffer) {
         let titles = self.filtered_titles(position, Alignment::Right);
@@ -1381,7 +1381,7 @@ mod tests {
         }
     }
 
-    /// This is a regression test for bug <https://github.com/ratatui-org/ratatui/issues/929>
+    /// This is a regression test for bug <https://github.com/ratatui/ratatui/issues/929>
     #[test]
     fn render_right_aligned_empty_title() {
         let mut buffer = Buffer::empty(Rect::new(0, 0, 15, 3));

src/widgets/chart.rs

@@ -82,7 +82,7 @@ impl<'a> Axis<'a> {
     /// more than 3 labels is currently broken and the middle labels won't be in the correct
     /// position, see [issue 334].
     ///
-    /// [issue 334]: https://github.com/ratatui-org/ratatui/issues/334
+    /// [issue 334]: https://github.com/ratatui/ratatui/issues/334
     ///
     /// `labels` is a vector of any type that can be converted into a [`Line`] (e.g. `&str`,
     /// `String`, `&Line`, `Span`, ...). This allows you to style the labels using the methods

src/widgets/list/list.rs

@@ -28,7 +28,7 @@ use crate::{
 /// See the list in the [Examples] directory for a more in depth example of the various
 /// configuration options and for how to handle state.
 ///
-/// [Examples]: https://github.com/ratatui-org/ratatui/blob/main/examples/README.md
+/// [Examples]: https://github.com/ratatui/ratatui/blob/main/examples/README.md
 ///
 /// # Fluent setters
 ///

src/widgets/list/rendering.rs

@@ -1250,7 +1250,7 @@ mod tests {
     /// Regression test for a bug where highlight symbol being greater than width caused a panic due
     /// to subtraction with underflow.
     ///
-    /// See [#949](https://github.com/ratatui-org/ratatui/pull/949) for details
+    /// See [#949](https://github.com/ratatui/ratatui/pull/949) for details
     #[rstest]
     #[case::under(">>>>", "Item1", ">>>>Item1 ")] // enough space to render the highlight symbol
     #[case::exact(">>>>>", "Item1", ">>>>>Item1")] // exact space to render the highlight symbol

src/widgets/list/state.rs

@@ -15,7 +15,7 @@
 /// See the list in the [Examples] directory for a more in depth example of the various
 /// configuration options and for how to handle state.
 ///
-/// [Examples]: https://github.com/ratatui-org/ratatui/blob/main/examples/README.md
+/// [Examples]: https://github.com/ratatui/ratatui/blob/main/examples/README.md
 ///
 /// # Example
 ///

src/widgets/paragraph.rs

@@ -220,7 +220,7 @@ impl<'a> Paragraph<'a> {
     /// convention across the crate.
     ///
     /// For more information about future scrolling design and concerns, see [RFC: Design of
-    /// Scrollable Widgets](https://github.com/ratatui-org/ratatui/issues/174) on GitHub.
+    /// Scrollable Widgets](https://github.com/ratatui/ratatui/issues/174) on GitHub.
     #[must_use = "method moves the value of self and returns the modified value"]
     pub const fn scroll(mut self, offset: (Vertical, Horizontal)) -> Self {
         self.scroll = Position {
@@ -313,7 +313,7 @@ impl<'a> Paragraph<'a> {
     /// ```
     #[instability::unstable(
         feature = "rendered-line-info",
-        issue = "https://github.com/ratatui-org/ratatui/issues/293"
+        issue = "https://github.com/ratatui/ratatui/issues/293"
     )]
     pub fn line_count(&self, width: u16) -> usize {
         if width < 1 {
@@ -368,7 +368,7 @@ impl<'a> Paragraph<'a> {
     /// ```
     #[instability::unstable(
         feature = "rendered-line-info",
-        issue = "https://github.com/ratatui-org/ratatui/issues/293"
+        issue = "https://github.com/ratatui/ratatui/issues/293"
     )]
     pub fn line_width(&self) -> usize {
         let width = self.text.iter().map(Line::width).max().unwrap_or_default();
@@ -1128,7 +1128,7 @@ mod test {
         assert_eq!(p.alignment, Alignment::Right);
     }
 
-    /// Regression test for <https://github.com/ratatui-org/ratatui/issues/990>
+    /// Regression test for <https://github.com/ratatui/ratatui/issues/990>
     ///
     /// This test ensures that paragraphs with a block and styled text are rendered correctly.
     /// It has been simplified from the original issue but tests the same functionality.

src/widgets/reflow.rs

@@ -51,7 +51,7 @@ where
     O: Iterator<Item = (I, Alignment)>,
     I: Iterator<Item = StyledGrapheme<'a>>,
 {
-    pub fn new(lines: O, max_line_width: u16, trim: bool) -> Self {
+    pub const fn new(lines: O, max_line_width: u16, trim: bool) -> Self {
         Self {
             input_lines: lines,
             max_line_width,
@@ -250,7 +250,7 @@ where
     O: Iterator<Item = (I, Alignment)>,
     I: Iterator<Item = StyledGrapheme<'a>>,
 {
-    pub fn new(lines: O, max_line_width: u16) -> Self {
+    pub const fn new(lines: O, max_line_width: u16) -> Self {
         Self {
             input_lines: lines,
             max_line_width,
@@ -500,7 +500,7 @@ mod test {
             .filter(|g| g.chars().any(|c| !c.is_whitespace()))
             .collect();
         assert_eq!(word_wrapper, expected);
-        assert_eq!(line_truncator, vec!["a"]);
+        assert_eq!(line_truncator, ["a"]);
     }
 
     #[test]
@@ -511,8 +511,8 @@ mod test {
                     両端点では、";
         let (word_wrapper, _, _) = run_composer(Composer::WordWrapper { trim: true }, text, width);
         let (line_truncator, _, _) = run_composer(Composer::LineTruncator, text, width);
-        assert_eq!(word_wrapper, vec!["", "a", "a", "a", "a"]);
-        assert_eq!(line_truncator, vec!["", "a", "a"]);
+        assert_eq!(word_wrapper, ["", "a", "a", "a", "a"]);
+        assert_eq!(line_truncator, ["", "a", "a"]);
     }
 
     /// Tests `WordWrapper` with words some of which exceed line length and some not.
@@ -541,8 +541,8 @@ mod test {
         let (word_wrapper, word_wrapper_width, _) =
             run_composer(Composer::WordWrapper { trim: true }, text, width);
         let (line_truncator, _, _) = run_composer(Composer::LineTruncator, text, width);
-        assert_eq!(line_truncator, vec!["コンピュータ上で文字"]);
-        let wrapped = vec![
+        assert_eq!(line_truncator, ["コンピュータ上で文字"]);
+        let wrapped = [
             "コンピュータ上で文字",
             "を扱う場合、典型的に",
             "は文字による通信を行",
@@ -550,7 +550,7 @@ mod test {
             "は、",
         ];
         assert_eq!(word_wrapper, wrapped);
-        assert_eq!(word_wrapper_width, vec![width, width, width, width, 4]);
+        assert_eq!(word_wrapper_width, [width, width, width, width, 4]);
     }
 
     #[test]
@@ -559,8 +559,8 @@ mod test {
         let text = "AAAAAAAAAAAAAAAAAAAA    AAA";
         let (word_wrapper, _, _) = run_composer(Composer::WordWrapper { trim: true }, text, width);
         let (line_truncator, _, _) = run_composer(Composer::LineTruncator, text, width);
-        assert_eq!(word_wrapper, vec!["AAAAAAAAAAAAAAAAAAAA", "AAA",]);
-        assert_eq!(line_truncator, vec!["AAAAAAAAAAAAAAAAAAAA"]);
+        assert_eq!(word_wrapper, ["AAAAAAAAAAAAAAAAAAAA", "AAA"]);
+        assert_eq!(line_truncator, ["AAAAAAAAAAAAAAAAAAAA"]);
     }
 
     /// Tests truncation of leading whitespace.
@@ -570,8 +570,8 @@ mod test {
         let text = "                                                                     ";
         let (word_wrapper, _, _) = run_composer(Composer::WordWrapper { trim: true }, text, width);
         let (line_truncator, _, _) = run_composer(Composer::LineTruncator, text, width);
-        assert_eq!(word_wrapper, vec![""]);
-        assert_eq!(line_truncator, vec!["                    "]);
+        assert_eq!(word_wrapper, [""]);
+        assert_eq!(line_truncator, ["                    "]);
     }
 
     /// Tests an input starting with a letter, followed by spaces - some of the behaviour is
@@ -586,8 +586,8 @@ mod test {
         // after 20 of which a word break occurs (probably shouldn't). The second line break
         // discards all whitespace. The result should probably be vec!["a"] but it doesn't matter
         // that much.
-        assert_eq!(word_wrapper, vec!["a", ""]);
-        assert_eq!(line_truncator, vec!["a                   "]);
+        assert_eq!(word_wrapper, ["a", ""]);
+        assert_eq!(line_truncator, ["a                   "]);
     }
 
     #[test]
@@ -614,7 +614,7 @@ mod test {
             ]
         );
         // Odd-sized lines have a space in them.
-        assert_eq!(word_wrapper_width, vec![8, 20, 17, 17, 20, 4]);
+        assert_eq!(word_wrapper_width, [8, 20, 17, 17, 20, 4]);
     }
 
     /// Ensure words separated by nbsp are wrapped as if they were a single one.
@@ -624,15 +624,15 @@ mod test {
         let text = "AAAAAAAAAAAAAAA AAAA\u{00a0}AAA";
         let (word_wrapper, word_wrapper_widths, _) =
             run_composer(Composer::WordWrapper { trim: true }, text, width);
-        assert_eq!(word_wrapper, vec!["AAAAAAAAAAAAAAA", "AAAA\u{00a0}AAA",]);
-        assert_eq!(word_wrapper_widths, vec![15, 8]);
+        assert_eq!(word_wrapper, ["AAAAAAAAAAAAAAA", "AAAA\u{00a0}AAA"]);
+        assert_eq!(word_wrapper_widths, [15, 8]);
 
         // Ensure that if the character was a regular space, it would be wrapped differently.
         let text_space = text.replace('\u{00a0}', " ");
         let (word_wrapper_space, word_wrapper_widths, _) =
             run_composer(Composer::WordWrapper { trim: true }, text_space, width);
-        assert_eq!(word_wrapper_space, vec!["AAAAAAAAAAAAAAA AAAA", "AAA",]);
-        assert_eq!(word_wrapper_widths, vec![20, 3]);
+        assert_eq!(word_wrapper_space, ["AAAAAAAAAAAAAAA AAAA", "AAA"]);
+        assert_eq!(word_wrapper_widths, [20, 3]);
     }
 
     #[test]
@@ -640,7 +640,7 @@ mod test {
         let width = 20;
         let text = "AAAAAAAAAAAAAAAAAAAA    AAA";
         let (word_wrapper, _, _) = run_composer(Composer::WordWrapper { trim: false }, text, width);
-        assert_eq!(word_wrapper, vec!["AAAAAAAAAAAAAAAAAAAA", "   AAA",]);
+        assert_eq!(word_wrapper, ["AAAAAAAAAAAAAAAAAAAA", "   AAA"]);
     }
 
     #[test]
@@ -678,8 +678,8 @@ mod test {
         let line = "foo\u{200B}";
         let (word_wrapper, _, _) = run_composer(Composer::WordWrapper { trim: true }, line, width);
         let (line_truncator, _, _) = run_composer(Composer::LineTruncator, line, width);
-        assert_eq!(word_wrapper, vec!["foo"]);
-        assert_eq!(line_truncator, vec!["foo\u{200B}"]);
+        assert_eq!(word_wrapper, ["foo"]);
+        assert_eq!(line_truncator, ["foo\u{200B}"]);
     }
 
     #[test]
@@ -716,6 +716,6 @@ mod test {
         let width = 3;
         let line = "foo\u{200b}bar";
         let (word_wrapper, _, _) = run_composer(Composer::WordWrapper { trim: true }, line, width);
-        assert_eq!(word_wrapper, vec!["foo", "bar"]);
+        assert_eq!(word_wrapper, ["foo", "bar"]);
     }
 }

src/widgets/scrollbar.rs

@@ -59,7 +59,7 @@ use crate::{
 ///
 /// let mut scrollbar_state = ScrollbarState::new(items.len()).position(vertical_scroll);
 ///
-/// let area = frame.size();
+/// let area = frame.area();
 /// // Note we render the paragraph
 /// frame.render_widget(paragraph, area);
 /// // and the scrollbar, those are separate widgets
@@ -1015,7 +1015,7 @@ mod tests {
         assert_eq!(buffer, Buffer::with_lines([expected]));
     }
 
-    /// Fixes <https://github.com/ratatui-org/ratatui/pull/959> which was a bug that would not
+    /// Fixes <https://github.com/ratatui/ratatui/pull/959> which was a bug that would not
     /// render a thumb when the viewport was very small in comparison to the content length.
     #[rstest]
     #[case::position_0("#----", 0, 100)]