chore: release 0.30.0-alpha.1 (#1618)

Versions:

```
ratatui = { path = "ratatui", version = "0.30.0-alpha.1" }
ratatui-core = { path = "ratatui-core", version = "0.1.0-alpha.2" }
ratatui-crossterm = { path = "ratatui-crossterm", version = "0.1.0-alpha.1" }
ratatui-termion = { path = "ratatui-termion", version = "0.1.0-alpha.1" }
ratatui-termwiz = { path = "ratatui-termwiz", version = "0.1.0-alpha.1" }
ratatui-widgets = { path = "ratatui-widgets", version = "0.3.0-alpha.1" }
```

.cargo/config.toml

@@ -0,0 +1,2 @@
+[alias]
+xtask = "run --package xtask --"

.cz.toml

@@ -32,17 +32,17 @@ schema_pattern = "(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)
 type = "list"
 name = "change_type"
 choices = [
-    { value = "build", name = "build: Changes that affect the build system or external dependencies (example scopes: pip, docker, npm)", key = "b" },
-    { value = "chore", name = "chore: A modification that generally does not fall into any other category", key = "c" },
-    { value = "ci", name = "ci: Changes to our CI configuration files and scripts (example scopes: GitLabCI)", key = "i" },
-    { value = "docs", name = "docs: Documentation only changes", key = "d" },
-    { value = "feat", name = "feat: A new feature.", key = "f" },
-    { value = "fix", name = "fix: A bug fix.", key = "x" },
-    { value = "perf", name = "perf: A code change that improves performance", key = "p" },
-    { value = "refactor", name = "refactor: A code change that neither fixes a bug nor adds a feature", key = "r" },
-    { value = "revert", name = "revert: Revert previous commits", key = "v" },
-    { value = "style", name = "style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)", key = "s" },
-    { value = "test", name = "test: Adding missing or correcting existing tests", key = "t" },
+  { value = "build", name = "build: Changes that affect the build system or external dependencies (example scopes: pip, docker, npm)", key = "b" },
+  { value = "chore", name = "chore: A modification that generally does not fall into any other category", key = "c" },
+  { value = "ci", name = "ci: Changes to our CI configuration files and scripts (example scopes: GitLabCI)", key = "i" },
+  { value = "docs", name = "docs: Documentation only changes", key = "d" },
+  { value = "feat", name = "feat: A new feature.", key = "f" },
+  { value = "fix", name = "fix: A bug fix.", key = "x" },
+  { value = "perf", name = "perf: A code change that improves performance", key = "p" },
+  { value = "refactor", name = "refactor: A code change that neither fixes a bug nor adds a feature", key = "r" },
+  { value = "revert", name = "revert: Revert previous commits", key = "v" },
+  { value = "style", name = "style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)", key = "s" },
+  { value = "test", name = "test: Adding missing or correcting existing tests", key = "t" },
 ]
 message = "Select the type of change you are committing"
 

.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/FUNDING.yml

@@ -0,0 +1,2 @@
+github: ratatui
+open_collective: ratatui

.github/workflows/bench_track_fork_pr.yml

@@ -18,43 +18,22 @@ jobs:
       PR_EVENT: event.json
     steps:
       - name: Download Benchmark Results
-        uses: actions/github-script@v7
+        uses: dawidd6/action-download-artifact@v7
         with:
-          script: |
-            async function downloadArtifact(artifactName) {
-              let allArtifacts = await github.rest.actions.listWorkflowRunArtifacts({
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                run_id: context.payload.workflow_run.id,
-              });
-              let matchArtifact = allArtifacts.data.artifacts.filter((artifact) => {
-                return artifact.name == artifactName
-              })[0];
-              if (!matchArtifact) {
-                core.setFailed(`Failed to find artifact: ${artifactName}`);
-              }
-              let download = await github.rest.actions.downloadArtifact({
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                artifact_id: matchArtifact.id,
-                archive_format: 'zip',
-              });
-              let fs = require('fs');
-              fs.writeFileSync(`${process.env.GITHUB_WORKSPACE}/${artifactName}.zip`, Buffer.from(download.data));
-            }
-            await downloadArtifact(process.env.BENCHMARK_RESULTS);
-            await downloadArtifact(process.env.PR_EVENT);
-      - name: Unzip Benchmark Results
-        run: |
-          unzip $BENCHMARK_RESULTS.zip
-          unzip $PR_EVENT.zip
+          name: ${{ env.BENCHMARK_RESULTS }}
+          run_id: ${{ github.event.workflow_run.id }}
+      - name: Download PR Event
+        uses: dawidd6/action-download-artifact@v7
+        with:
+          name: ${{ env.PR_EVENT }}
+          run_id: ${{ github.event.workflow_run.id }}
       - name: Export PR Event Data
         uses: actions/github-script@v7
         with:
           script: |
             let fs = require('fs');
             let prEvent = JSON.parse(fs.readFileSync(process.env.PR_EVENT, {encoding: 'utf8'}));
-            core.exportVariable("PR_HEAD", `${prEvent.number}/merge`);
+            core.exportVariable("PR_HEAD", prEvent.pull_request.head.ref);
             core.exportVariable("PR_BASE", prEvent.pull_request.base.ref);
             core.exportVariable("PR_BASE_SHA", prEvent.pull_request.base.sha);
             core.exportVariable("PR_NUMBER", prEvent.number);
@@ -64,12 +43,14 @@ jobs:
           bencher run \
           --project ratatui-org \
           --token '${{ secrets.BENCHER_API_TOKEN }}' \
-          --branch '${{ env.PR_HEAD }}' \
-          --branch-start-point '${{ env.PR_BASE }}' \
-          --branch-start-point-hash '${{ env.PR_BASE_SHA }}' \
+          --branch "$PR_HEAD" \
+          --start-point "$PR_BASE" \
+          --start-point-hash "$PR_BASE_SHA" \
+          --start-point-clone-thresholds \
+          --start-point-reset \
           --testbed ubuntu-latest \
           --adapter rust_criterion \
           --err \
           --github-actions '${{ secrets.GITHUB_TOKEN }}' \
-          --ci-number '${{ env.PR_NUMBER }}' \
-          --file "$BENCHMARK_RESULTS"
+          --ci-number "$PR_NUMBER" \
+          --file "$BENCHMARK_RESULTS"

.github/workflows/ci.yml

@@ -9,7 +9,6 @@ on:
   pull_request:
     branches:
       - main
-  merge_group:
 
 # ensure that the workflow is only triggered once per PR,  subsequent pushes to the PR will cancel
 # and restart the workflow. See https://docs.github.com/en/actions/using-jobs/using-concurrency
@@ -17,82 +16,95 @@ 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:
+  # Lint the formatting of the codebase.
+  lint-formatting:
+    name: Check Formatting
     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 }
+      - uses: Swatinem/rust-cache@v2
+      - uses: taiki-e/install-action@v2
         with:
-          components: rustfmt
-      - run: cargo +nightly fmt --all --check
+          tool: taplo-cli
+      - run: cargo xtask format --check
 
-  typos:
+  # Check for typos in the codebase.
+  # See <https://github.com/crate-ci/typos/>
+  lint-typos:
+    name: Check Typos
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
       - uses: crate-ci/typos@master
 
+  # Check for any disallowed dependencies in the codebase due to license / security issues.
+  # See <https://github.com/EmbarkStudios/cargo-deny>
   dependencies:
+    name: Check Dependencies
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
       - uses: EmbarkStudios/cargo-deny-action@v2
 
-  clippy:
+  # Check for any unused dependencies in the codebase.
+  # See <https://github.com/bnjbvr/cargo-machete/>
+  cargo-machete:
+    name: Check Unused Dependencies
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - name: Install Rust stable
-        uses: dtolnay/rust-toolchain@stable
-        with:
-          components: clippy
-      - name: Install cargo-make
-        uses: taiki-e/install-action@cargo-make
-      - uses: Swatinem/rust-cache@v2
-      - run: cargo make clippy
+      - uses: bnjbvr/cargo-machete@v0.7.0
 
-  markdownlint:
+  # Run cargo clippy.
+  lint-clippy:
+    name: Check Clippy
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - name: Lint markdown
-        uses: DavidAnson/markdownlint-cli2-action@v16
+      - uses: dtolnay/rust-toolchain@stable
+        with: { components: clippy }
+      - uses: Swatinem/rust-cache@v2
+      - run: cargo xtask clippy
+
+  # Run markdownlint on all markdown files in the repository.
+  lint-markdown:
+    name: Check Markdown
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: DavidAnson/markdownlint-cli2-action@v18
         with:
           globs: |
             '**/*.md'
             '!target'
 
+  # Run cargo coverage. This will generate a coverage report and upload it to codecov.
+  # <https://app.codecov.io/gh/ratatui/ratatui>
   coverage:
+    name: Coverage Report
     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
-        with:
-          tool: cargo-llvm-cov,cargo-make
+      - uses: taiki-e/install-action@cargo-llvm-cov
       - uses: Swatinem/rust-cache@v2
-      - name: Generate coverage
-        run: cargo make coverage
-      - name: Upload to codecov.io
-        uses: codecov/codecov-action@v4
+      - run: cargo xtask coverage
+      - uses: codecov/codecov-action@v5
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
           fail_ci_if_error: true
 
+  # Run cargo check. This is a fast way to catch any obvious errors in the code.
   check:
+    name: Check ${{ matrix.os }} ${{ matrix.toolchain }}
     strategy:
       fail-fast: false
       matrix:
@@ -101,69 +113,76 @@ 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: Swatinem/rust-cache@v2
-      - run: cargo make check
-        env:
-          RUST_BACKTRACE: full
+      - run: cargo xtask check --all-features
 
-  lint-docs:
+  # Check if README.md is up-to-date with the crate's documentation.
+  check-readme:
+    name: Check README
     runs-on: ubuntu-latest
     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: Swatinem/rust-cache@v2
-      - run: cargo make lint-docs
+      - uses: taiki-e/install-action@cargo-rdme
+      - run: cargo xtask readme --check
 
-  test-doc:
-    strategy:
-      fail-fast: false
-      matrix:
-        os: [ubuntu-latest, windows-latest, macos-latest]
-    runs-on: ${{ matrix.os }}
+  # 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
+  lint-docs:
+    name: Check Docs
+    runs-on: ubuntu-latest
+    env:
+      RUSTDOCFLAGS: -Dwarnings
     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@nightly
+      - uses: dtolnay/install@cargo-docs-rs
       - uses: Swatinem/rust-cache@v2
-      - name: Test docs
-        run: cargo make test-doc
-        env:
-          RUST_BACKTRACE: full
+      - run: cargo xtask docs
 
-  test:
+  # Run cargo test on the documentation of the crate. This will catch any code examples that don't
+  # compile, or any other issues in the documentation.
+  test-docs:
+    name: Test Docs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - run: cargo xtask test-docs
+
+  # Run cargo test on the libraries of the crate.
+  test-libs:
+    name: Test Libs ${{ matrix.toolchain }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        toolchain: ["1.74.0", "stable"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - run: cargo xtask test-libs
+
+  # Run cargo test on all the backends.
+  test-backends:
+    name: Test ${{matrix.backend}} on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, windows-latest, macos-latest]
-        toolchain: ["1.74.0", "stable"]
         backend: [crossterm, termion, termwiz]
         exclude:
           # termion is not supported on windows
           - os: windows-latest
             backend: termion
-    runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v4
-      - name: Install Rust ${{ matrix.toolchain }}}
-        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: dtolnay/rust-toolchain@stable
       - uses: Swatinem/rust-cache@v2
-      - run: cargo make test-backend ${{ matrix.backend }}
-        env:
-          RUST_BACKTRACE: full
+      - run: cargo xtask test-backend ${{ matrix.backend }}

.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 }}

.gitignore

@@ -1,5 +1,4 @@
 target
-Cargo.lock
 *.log
 *.rs.rustfmt
 .gdb_history

.taplo.toml

@@ -0,0 +1,12 @@
+include = ["**/*.toml"]
+
+[formatting]
+column_width = 100
+reorder_keys = false
+
+[[rule]]
+include = ["**/Cargo.toml"]
+keys = ["dependencies", "dev-dependencies", "build-dependencies", "workspace.dependencies"]
+
+[rule.formatting]
+reorder_keys = true

BREAKING-CHANGES.md

@@ -4,14 +4,24 @@ 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
 
 This is a quick summary of the sections below:
 
+- [Unreleased](#unreleased)
+  - The `From` impls for backend types are now replaced with more specific traits
+  - `FrameExt` trait for `unstable-widget-ref` feature
+- [v0.29.0](#v0290)
+  - `Sparkline::data` takes `IntoIterator<Item = SparklineBar>` instead of `&[u64]` and is no longer const
+  - Removed public fields from `Rect` iterators
+  - `Line` now implements `From<Cow<str>`
+  - `Table::highlight_style` is now `Table::row_highlight_style`
+  - `Tabs::select` now accepts `Into<Option<usize>>`
+  - `Color::from_hsl` is now behind the `palette` feature
 - [v0.28.0](#v0280)
-  ⁻ `Backend::size` returns `Size` instead of `Rect`
+  - `Backend::size` returns `Size` instead of `Rect`
   - `Backend` trait migrates to `get/set_cursor_position`
   - Ratatui now requires Crossterm 0.28.0
   - `Axis::labels` now accepts `IntoIterator<Into<Line>>`
@@ -65,18 +75,222 @@ This is a quick summary of the sections below:
   - MSRV is now 1.63.0
   - `List` no longer ignores empty strings
 
-## v0.28.0
+## Unreleased (0.30.0)
+
+### `FrameExt` trait for `unstable-widget-ref` feature ([#1530])
+
+[#1530]: https://github.com/ratatui/ratatui/pull/1530
+
+To call `Frame::render_widget_ref()` or `Frame::render_stateful_widget_ref()` you now need to:
+
+1. Import the `FrameExt` trait from `ratatui::widgets`.
+2. Enable the `unstable-widget-ref` feature.
+
+For example:
+
+```rust
+use ratatui::{
+    layout::Rect,
+    widgets::{Block, FrameExt},
+};
+
+let block = Block::new();
+let area = Rect::new(0, 0, 5, 5);
+frame.render_widget_ref(&block, area);
+```
+
+### `WidgetRef` no longer has a blanket implementation of Widget
+
+Previously there was a blanket implementation of Widget for WidgetRef. This has been reversed to
+instead be a blanket implementation of WidgetRef for all &W where W: Widget. Any widgets that
+previously implemented WidgetRef directly should now instead implement Widget for a reference to the
+type.
+
+```diff
+-impl WidgetRef for Foo {
+-    fn render_ref(&self, area: Rect, buf: &mut Buffer)
++impl Widget for &Foo {
++    fn render(self, area: Rect, buf: &mut Buffer)
+}
+```
+
+### The `From` impls for backend types are now replaced with more specific traits [#1464]
+
+[#1464]: https://github.com/ratatui/ratatui/pull/1464
+
+Crossterm gains `ratatui::backend::crossterm::{FromCrossterm, IntoCrossterm}`
+Termwiz gains `ratatui::backend::termwiz::{FromTermwiz, IntoTermwiz}`
+
+This is necessary in order to avoid the orphan rule when implementing `From` for crossterm types
+once the crossterm types are moved to a separate crate.
+
+```diff
++ use ratatui::backend::crossterm::{FromCrossterm, IntoCrossterm};
+
+let crossterm_color = crossterm::style::Color::Black;
+- let ratatui_color = crossterm_color.into();
+- let ratatui_color = ratatui::style::Color::from(crossterm_color);
++ let ratatui_color = ratatui::style::Color::from_crossterm(crossterm_color);
+- let crossterm_color = ratatui_color.into();
+- let crossterm_color = crossterm::style::Color::from(ratatui_color);
++ let crossterm_color = ratatui_color.into_crossterm();
+
+let crossterm_attribute = crossterm::style::types::Attribute::Bold;
+- let ratatui_modifier = crossterm_attribute.into();
+- let ratatui_modifier = ratatui::style::Modifier::from(crossterm_attribute);
++ let ratatui_modifier = ratatui::style::Modifier::from_crossterm(crossterm_attribute);
+- let crossterm_attribute = ratatui_modifier.into();
+- let crossterm_attribute = crossterm::style::types::Attribute::from(ratatui_modifier);
++ let crossterm_attribute = ratatui_modifier.into_crossterm();
+```
+
+Similar conversions for `ContentStyle` -> `Style` and `Attributes` -> `Modifier` exist for
+Crossterm and the various Termion and Termwiz types as well.
+
+### `Bar::label()` and `BarGroup::label()` now accepts `Into<Line<'a>>`. ([#1471])
+
+[#1471]: https://github.com/ratatui/ratatui/pull/1471
+
+Previously `Bar::label()` and `BarGroup::label()` accepted `Line<'a>`, but they now accepts `Into<Line<'a>>`.
+
+for `Bar::label()`:
+
+```diff
+- Bar::default().label("foo".into());
++ Bar::default().label("foo");
+```
+
+for `BarGroup::label()`:
+
+```diff
+- BarGroup::default().label("bar".into());
++ BarGroup::default().label("bar");
+```
+
+### `Bar::text_value` now accepts `Into<String>` ([#1471])
+
+Previously `Bar::text_value` accepted `String`, but now it accepts `Into<String>`.
+
+for `Bar::text_value()`:
+
+```diff
+- Bar::default().text_value("foobar".into());
++ Bar::default().text_value("foobar");
+```
+
+## [v0.29.0](https://github.com/ratatui/ratatui/releases/tag/v0.29.0)
+
+### `Sparkline::data` takes `IntoIterator<Item = SparklineBar>` instead of `&[u64]` and is no longer const ([#1326])
+
+[#1326]: https://github.com/ratatui/ratatui/pull/1326
+
+The `Sparkline::data` method has been modified to accept `IntoIterator<Item = SparklineBar>`
+instead of `&[u64]`.
+
+`SparklineBar` is a struct that contains an `Option<u64>` value, which represents an possible
+_absent_ value, as distinct from a `0` value. This change allows the `Sparkline` to style
+data points differently, depending on whether they are present or absent.
+
+`SparklineBar` also contains an `Option<Style>` that will be used to apply a style the bar in
+addition to any other styling applied to the `Sparkline`.
+
+Several `From` implementations have been added to `SparklineBar` to support existing callers who
+provide `&[u64]` and other types that can be converted to `SparklineBar`, such as `Option<u64>`.
+
+If you encounter any type inference issues, you may need to provide an explicit type for the data
+passed to `Sparkline::data`. For example, if you are passing a single value, you may need to use
+`into()` to convert it to form that can be used as a `SparklineBar`:
+
+```diff
+let value = 1u8;
+- Sparkline::default().data(&[value.into()]);
++ Sparkline::default().data(&[u64::from(value)]);
+```
+
+As a consequence of this change, the `data` method is no longer a `const fn`.
+
+### `Color::from_hsl` is now behind the `palette` feature and accepts `palette::Hsl` ([#1418])
+
+[#1418]: https://github.com/ratatui/ratatui/pull/1418
+
+Previously `Color::from_hsl` accepted components as individual f64 parameters. It now accepts a
+single `palette::Hsl` value and is gated behind a `palette` feature flag.
+
+```diff
+- Color::from_hsl(360.0, 100.0, 100.0)
++ Color::from_hsl(Hsl::new(360.0, 100.0, 100.0))
+```
+
+### Removed public fields from `Rect` iterators ([#1358], [#1424])
+
+[#1358]: https://github.com/ratatui/ratatui/pull/1358
+[#1424]: https://github.com/ratatui/ratatui/pull/1424
+
+The `pub` modifier has been removed from fields on the `Columns`,`Rows`, and `Positions` iterators.
+These fields were not intended to be public and should not have been accessed directly.
+
+### `Rect::area()` now returns u32 instead of u16 ([#1378])
+
+[#1378]: https://github.com/ratatui/ratatui/pull/1378
+
+This is likely to impact anything which relies on `Rect::area` maxing out at u16::MAX. It can now
+return up to u16::MAX * u16::MAX (2^32 - 2^17 + 1).
+
+### `Line` now implements `From<Cow<str>` ([#1373])
+
+[#1373]: https://github.com/ratatui/ratatui/pull/1373
+
+As this adds an extra conversion, ambiguous inferred expressions may no longer compile.
+
+```rust
+// given:
+struct Foo { ... }
+impl From<Foo> for String { ... }
+impl From<Foo> for Cow<str> { ... }
+
+let foo = Foo { ... };
+let line = Line::from(foo); // now fails due to now ambiguous inferred type
+// replace with e.g.
+let line = Line::from(String::from(foo));
+```
+
+### `Tabs::select()` now accepts `Into<Option<usize>>` ([#1413])
+
+[#1413]: https://github.com/ratatui/ratatui/pull/1413
+
+Previously `Tabs::select()` accepted `usize`, but it now accepts `Into<Option<usize>>`. This breaks
+any code already using parameter type inference:
+
+```diff
+let selected = 1u8;
+- let tabs = Tabs::new(["A", "B"]).select(selected.into())
++ let tabs = Tabs::new(["A", "B"]).select(selected as usize)
+```
+
+### `Table::highlight_style` is now `Table::row_highlight_style` ([#1331])
+
+[#1331]: https://github.com/ratatui/ratatui/pull/1331
+
+The `Table::highlight_style` is now deprecated in favor of `Table::row_highlight_style`.
+
+Also, the serialized output of the `TableState` will now include the "selected_column" field.
+Software that manually parse the serialized the output (with anything other than the `Serialize`
+implementation on `TableState`) may have to be refactored if the "selected_column" field is not
+accounted for. This does not affect users who rely on the `Deserialize`, or `Serialize`
+implementation on the state.
+
+## [v0.28.0](https://github.com/ratatui/ratatui/releases/tag/v0.28.0)
 
 ### `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 +301,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 +309,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 +322,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 +331,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 +344,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`
+### `Frame::size` is deprecated and renamed to `Frame::area` ([#1293])
 
-[#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 +419,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 +437,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 +448,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 +478,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 +489,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 +514,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 +531,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 +547,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 +557,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 +583,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 +591,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 +615,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 +633,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 +648,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 +660,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 +686,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 +702,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 +719,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 +744,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 +758,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 +776,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 +789,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 +805,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 +819,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 +860,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 +874,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 +886,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.
@@ -31,7 +31,7 @@ guarantee that the behavior is unchanged.
 
 ### Code formatting
 
-Run `cargo make format` before committing to ensure that code is consistently formatted with
+Run `cargo xtask format` before committing to ensure that code is consistently formatted with
 rustfmt. Configuration is in [`rustfmt.toml`](./rustfmt.toml).
 
 ### Search `tui-rs` for similar work
@@ -56,7 +56,7 @@ documented.
 
 ### Run CI tests before pushing a PR
 
-Running `cargo make ci` before pushing will perform the same checks that we do in the CI process.
+Running `cargo xtask ci` before pushing will perform the same checks that we do in the CI process.
 It's not mandatory to do this before pushing, however it may save you time to do so instead of
 waiting for GitHub to run the checks.
 
@@ -71,22 +71,22 @@ in GitHub docs.
 
 ### Setup
 
-Clone the repo and build it using [cargo-make](https://sagiegurari.github.io/cargo-make/)
+TL;DR: Clone the repo and build it using `cargo xtask`.
 
 Ratatui is an ordinary Rust project where common tasks are managed with
-[cargo-make](https://github.com/sagiegurari/cargo-make/). It wraps common `cargo` commands with sane
+[cargo-xtask](https://github.com/matklad/cargo-xtask). It wraps common `cargo` commands with sane
 defaults depending on your platform of choice. Building the project should be as easy as running
-`cargo make build`.
+`cargo xtask build`.
 
 ```shell
-git clone https://github.com/ratatui-org/ratatui.git
+git clone https://github.com/ratatui/ratatui.git
 cd ratatui
-cargo make build
+cargo xtask 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
 
@@ -182,7 +182,7 @@ We use GitHub Actions for the CI where we perform the following checks:
 - The code should conform to the default format enforced by `rustfmt`.
 - The code should not contain common style issues `clippy`.
 
-You can also check most of those things yourself locally using `cargo make ci` which will offer you
+You can also check most of those things yourself locally using `cargo xtask ci` which will offer you
 a shorter feedback loop than pushing to github.
 
 ## Relationship with `tui-rs`
@@ -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,80 +1,64 @@
-[package]
-name = "ratatui"
-version = "0.28.0" # crate version
+[workspace]
+resolver = "2"
+members = ["ratatui", "ratatui-*", "xtask", "examples/apps/*"]
+default-members = [
+  "ratatui",
+  "ratatui-core",
+  "ratatui-crossterm",
+  # this is not included as it doesn't compile on windows
+  # "ratatui-termion",
+  "ratatui-termwiz",
+  "ratatui-widgets",
+  "examples/apps/*",
+]
+
+[workspace.package]
 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"]
 readme = "README.md"
 license = "MIT"
-exclude = [
-  "assets/*",
-  ".github",
-  "Makefile.toml",
-  "CONTRIBUTING.md",
-  "*.log",
-  "tags",
-]
+exclude = ["assets/*", ".github", "Makefile.toml", "CONTRIBUTING.md", "*.log", "tags"]
 edition = "2021"
 rust-version = "1.74.0"
 
-[badges]
+[workspace.dependencies]
+bitflags = "2.7.0"
+color-eyre = "0.6.3"
+crossterm = "0.28.1"
+document-features = "0.2.7"
+indoc = "2.0.5"
+instability = "0.3.7"
+itertools = "0.13.0"
+pretty_assertions = "1.4.1"
+ratatui = { path = "ratatui", version = "0.30.0-alpha.1" }
+ratatui-core = { path = "ratatui-core", version = "0.1.0-alpha.2" }
+ratatui-crossterm = { path = "ratatui-crossterm", version = "0.1.0-alpha.1" }
+ratatui-termion = { path = "ratatui-termion", version = "0.1.0-alpha.1" }
+ratatui-termwiz = { path = "ratatui-termwiz", version = "0.1.0-alpha.1" }
+ratatui-widgets = { path = "ratatui-widgets", version = "0.3.0-alpha.1" }
+rstest = "0.24.0"
+serde = { version = "1.0.217", features = ["derive"] }
+serde_json = "1.0.135"
+strum = { version = "0.26.3", features = ["derive"] }
+termwiz = { version = "0.22.0" }
+unicode-segmentation = "1.12.0"
+# See <https://github.com/ratatui/ratatui/issues/1271> for information about why we pin unicode-width
+termion = "4.0.0"
+unicode-width = "=0.2.0"
 
-[dependencies]
-bitflags = "2.3"
-cassowary = "0.3"
-compact_str = "0.8.0"
-crossterm = { version = "0.28.1", optional = true }
-document-features = { version = "0.2.7", optional = true }
-instability = "0.3.1"
-itertools = "0.13"
-lru = "0.12.0"
-paste = "1.0.2"
-palette = { version = "0.7.6", optional = true }
-serde = { version = "1", optional = true, features = ["derive"] }
-strum = { version = "0.26", features = ["derive"] }
-strum_macros = { version = "0.26.3" }
-termion = { version = "4.0.0", optional = true }
-termwiz = { version = "0.22.0", optional = true }
-time = { version = "0.3.11", optional = true, features = ["local-offset"] }
-unicode-segmentation = "1.10"
-unicode-truncate = "1"
-unicode-width = "0.1.13"
+# Improve benchmark consistency
+[profile.bench]
+codegen-units = 1
+lto = 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"
-indoc = "2"
-octocrab = "0.39.0"
-pretty_assertions = "1.4.0"
-rand = "0.8.5"
-rand_chacha = "0.3.1"
-rstest = "0.22.0"
-serde_json = "1.0.109"
-tokio = { version = "1.39.2", features = [
-  "rt",
-  "macros",
-  "time",
-  "rt-multi-thread",
-] }
-tracing = "0.1.40"
-tracing-appender = "0.2.3"
-tracing-subscriber = { version = "0.3.18", features = ["env-filter"] }
-
-[lints.rust]
+[workspace.lints.rust]
 unsafe_code = "forbid"
 
-[lints.clippy]
-cargo = { level = "warn", priority = -1 }
+[workspace.lints.clippy]
 pedantic = { level = "warn", priority = -1 }
 cast_possible_truncation = "allow"
 cast_possible_wrap = "allow"
@@ -111,259 +95,3 @@ string_slice = "warn"
 string_to_string = "warn"
 unnecessary_self_imports = "warn"
 use_self = "warn"
-
-[features]
-#! The crate provides a set of optional features that can be enabled in your `cargo.toml` file.
-#!
-## By default, we enable the crossterm backend as this is a reasonable choice for most applications
-## as it is supported on Linux/Mac/Windows systems. We also enable the `underline-color` feature
-## which allows you to set the underline color of text.
-default = ["crossterm", "underline-color"]
-#! Generally an application will only use one backend, so you should only enable one of the following features:
-## enables the [`CrosstermBackend`](backend::CrosstermBackend) backend and adds a dependency on [`crossterm`].
-crossterm = ["dep:crossterm"]
-## enables the [`TermionBackend`](backend::TermionBackend) backend and adds a dependency on [`termion`].
-termion = ["dep:termion"]
-## enables the [`TermwizBackend`](backend::TermwizBackend) backend and adds a dependency on [`termwiz`].
-termwiz = ["dep:termwiz"]
-
-#! The following optional features are available for all backends:
-## enables serialization and deserialization of style and color types using the [`serde`] crate.
-## This is useful if you want to save themes to a file.
-serde = ["dep:serde", "bitflags/serde", "compact_str/serde"]
-
-## enables the [`border!`] macro.
-macros = []
-
-## enables conversions from colors in the [`palette`] crate to [`Color`](crate::style::Color).
-palette = ["dep:palette"]
-
-## enables all widgets.
-all-widgets = ["widget-calendar"]
-
-#! Widgets that add dependencies are gated behind feature flags to prevent unused transitive
-#! dependencies. The available features are:
-## enables the [`calendar`](widgets::calendar) widget module and adds a dependency on [`time`].
-widget-calendar = ["dep:time"]
-
-#! The following optional features are only available for some backends:
-
-## enables the backend code that sets the underline color.
-## Underline color is only supported by the [`CrosstermBackend`](backend::CrosstermBackend) backend,
-## and is not supported on Windows 7.
-underline-color = ["dep:crossterm"]
-
-#! The following features are unstable and may change in the future:
-
-## Enable all unstable features.
-unstable = ["unstable-rendered-line-info", "unstable-widget-ref"]
-
-## Enables the [`Paragraph::line_count`](widgets::Paragraph::line_count)
-## [`Paragraph::line_width`](widgets::Paragraph::line_width) methods
-## which are experimental and may change in the future.
-## See [Issue 293](https://github.com/ratatui-org/ratatui/issues/293) for more details.
-unstable-rendered-line-info = []
-
-## Enables the [`WidgetRef`](widgets::WidgetRef) and [`StatefulWidgetRef`](widgets::StatefulWidgetRef) traits which are experimental and may change in
-## the future.
-unstable-widget-ref = []
-
-[package.metadata.docs.rs]
-all-features = true
-# see https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html
-cargo-args = ["-Zunstable-options", "-Zrustdoc-scrape-examples"]
-rustdoc-args = ["--cfg", "docsrs"]
-
-# Improve benchmark consistency
-[profile.bench]
-codegen-units = 1
-lto = true
-
-[lib]
-bench = false
-
-[[bench]]
-name = "main"
-harness = false
-
-[[example]]
-name = "async"
-required-features = ["crossterm"]
-doc-scrape-examples = true
-
-[[example]]
-name = "barchart"
-required-features = ["crossterm"]
-doc-scrape-examples = true
-
-[[example]]
-name = "barchart-grouped"
-required-features = ["crossterm"]
-doc-scrape-examples = true
-
-[[example]]
-name = "block"
-required-features = ["crossterm"]
-doc-scrape-examples = true
-
-[[example]]
-name = "calendar"
-required-features = ["crossterm", "widget-calendar"]
-doc-scrape-examples = true
-
-[[example]]
-name = "canvas"
-required-features = ["crossterm"]
-doc-scrape-examples = true
-
-[[example]]
-name = "chart"
-required-features = ["crossterm"]
-doc-scrape-examples = true
-
-[[example]]
-name = "colors"
-required-features = ["crossterm"]
-# this example is a bit verbose, so we don't want to include it in the docs
-doc-scrape-examples = false
-
-[[example]]
-name = "colors_rgb"
-required-features = ["crossterm", "palette"]
-doc-scrape-examples = true
-
-[[example]]
-name = "constraint-explorer"
-required-features = ["crossterm"]
-doc-scrape-examples = true
-
-[[example]]
-name = "constraints"
-required-features = ["crossterm"]
-doc-scrape-examples = false
-
-[[example]]
-name = "custom_widget"
-required-features = ["crossterm"]
-doc-scrape-examples = true
-
-[[example]]
-name = "demo"
-# this runs for all of the terminal backends, so it can't be built using --all-features or scraped
-doc-scrape-examples = false
-
-[[example]]
-name = "demo2"
-required-features = ["crossterm", "palette", "widget-calendar"]
-doc-scrape-examples = true
-
-[[example]]
-name = "docsrs"
-required-features = ["crossterm"]
-doc-scrape-examples = false
-
-[[example]]
-name = "flex"
-required-features = ["crossterm"]
-doc-scrape-examples = true
-
-[[example]]
-name = "gauge"
-required-features = ["crossterm"]
-doc-scrape-examples = true
-
-[[example]]
-name = "hello_world"
-required-features = ["crossterm"]
-doc-scrape-examples = true
-
-[[example]]
-name = "inline"
-required-features = ["crossterm"]
-doc-scrape-examples = true
-
-[[example]]
-name = "layout"
-required-features = ["crossterm"]
-doc-scrape-examples = true
-
-[[example]]
-name = "line_gauge"
-required-features = ["crossterm"]
-doc-scrape-examples = true
-
-[[example]]
-name = "hyperlink"
-required-features = ["crossterm", "unstable-widget-ref"]
-doc-scrape-examples = true
-
-[[example]]
-name = "list"
-required-features = ["crossterm"]
-doc-scrape-examples = true
-
-[[example]]
-name = "minimal"
-required-features = ["crossterm"]
-# prefer to show the more featureful examples in the docs
-doc-scrape-examples = false
-
-[[example]]
-name = "modifiers"
-required-features = ["crossterm"]
-# this example is a bit verbose, so we don't want to include it in the docs
-doc-scrape-examples = false
-
-[[example]]
-name = "panic"
-required-features = ["crossterm"]
-doc-scrape-examples = true
-
-[[example]]
-name = "paragraph"
-required-features = ["crossterm"]
-doc-scrape-examples = true
-
-[[example]]
-name = "popup"
-required-features = ["crossterm"]
-doc-scrape-examples = true
-
-[[example]]
-name = "ratatui-logo"
-required-features = ["crossterm"]
-doc-scrape-examples = true
-
-[[example]]
-name = "scrollbar"
-required-features = ["crossterm"]
-doc-scrape-examples = true
-
-[[example]]
-name = "sparkline"
-required-features = ["crossterm"]
-doc-scrape-examples = true
-
-[[example]]
-name = "table"
-required-features = ["crossterm"]
-doc-scrape-examples = true
-
-[[example]]
-name = "tabs"
-required-features = ["crossterm"]
-doc-scrape-examples = true
-
-[[example]]
-name = "tracing"
-required-features = ["crossterm"]
-doc-scrape-examples = true
-
-[[example]]
-name = "user_input"
-required-features = ["crossterm"]
-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

@@ -1,180 +0,0 @@
-# configuration for https://github.com/sagiegurari/cargo-make
-
-[config]
-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" }
-
-[tasks.default]
-alias = "ci"
-
-[tasks.ci]
-description = "Run continuous integration tasks"
-dependencies = ["lint", "clippy", "check", "test"]
-
-[tasks.lint]
-description = "Lint code style (formatting, typos, docs, markdown)"
-dependencies = ["lint-format", "lint-typos", "lint-docs", "lint-markdown"]
-
-[tasks.lint-format]
-description = "Lint code formatting"
-toolchain = "nightly"
-command = "cargo"
-args = ["fmt", "--all", "--check"]
-
-[tasks.format]
-description = "Fix code formatting"
-toolchain = "nightly"
-command = "cargo"
-args = ["fmt", "--all"]
-
-[tasks.lint-typos]
-description = "Run typo checks"
-install_crate = { crate_name = "typos-cli", binary = "typos", test_arg = "--version" }
-command = "typos"
-
-[tasks.lint-docs]
-description = "Check documentation for errors and warnings"
-toolchain = "nightly"
-command = "cargo"
-args = [
-  "rustdoc",
-  "--no-default-features",
-  "${ALL_FEATURES_FLAG}",
-  "--",
-  "-Zunstable-options",
-  "--check",
-  "-Dwarnings",
-]
-
-[tasks.lint-markdown]
-description = "Check markdown files for errors and warnings"
-command = "markdownlint-cli2"
-args = ["**/*.md", "!target"]
-
-[tasks.check]
-description = "Check code for errors and warnings"
-command = "cargo"
-args = [
-  "check",
-  "--all-targets",
-  "--no-default-features",
-  "${ALL_FEATURES_FLAG}",
-]
-
-[tasks.build]
-description = "Compile the project"
-command = "cargo"
-args = [
-  "build",
-  "--all-targets",
-  "--no-default-features",
-  "${ALL_FEATURES_FLAG}",
-]
-
-[tasks.clippy]
-description = "Run Clippy for linting"
-command = "cargo"
-args = [
-  "clippy",
-  "--all-targets",
-  "--tests",
-  "--benches",
-  "--no-default-features",
-  "${ALL_FEATURES_FLAG}",
-  "--",
-  "-D",
-  "warnings",
-]
-
-[tasks.install-nextest]
-description = "Install cargo-nextest"
-install_crate = { crate_name = "cargo-nextest", binary = "cargo-nextest", test_arg = "--help" }
-
-[tasks.test]
-description = "Run tests"
-run_task = { name = ["test-lib", "test-doc"] }
-
-[tasks.test-lib]
-description = "Run default tests"
-dependencies = ["install-nextest"]
-command = "cargo"
-args = [
-  "nextest",
-  "run",
-  "--all-targets",
-  "--no-default-features",
-  "${ALL_FEATURES_FLAG}",
-]
-
-[tasks.test-doc]
-description = "Run documentation tests"
-command = "cargo"
-args = ["test", "--doc", "--no-default-features", "${ALL_FEATURES_FLAG}"]
-
-[tasks.test-backend]
-# takes a command line parameter to specify the backend to test (e.g. "crossterm")
-description = "Run backend-specific tests"
-dependencies = ["install-nextest"]
-command = "cargo"
-args = [
-  "nextest",
-  "run",
-  "--all-targets",
-  "--no-default-features",
-  "--features",
-  "${ALL_FEATURES},${@}",
-]
-
-[tasks.coverage]
-description = "Generate code coverage report"
-command = "cargo"
-args = [
-  "llvm-cov",
-  "--lcov",
-  "--output-path",
-  "target/lcov.info",
-  "--no-default-features",
-  "${ALL_FEATURES_FLAG}",
-]
-
-[tasks.run-example]
-private = true
-condition = { env_set = ["TUI_EXAMPLE_NAME"] }
-command = "cargo"
-args = [
-  "run",
-  "--release",
-  "--example",
-  "${TUI_EXAMPLE_NAME}",
-  "--features",
-  "all-widgets",
-]
-
-[tasks.build-examples]
-description = "Compile project examples"
-command = "cargo"
-args = ["build", "--examples", "--release", "--features", "all-widgets"]
-
-[tasks.run-examples]
-description = "Run project examples"
-dependencies = ["build-examples"]
-script = '''
-#!@duckscript
-files = glob_array ./examples/*.rs
-for file in ${files}
-  name = basename ${file}
-  name = substring ${name} -3
-  set_env TUI_EXAMPLE_NAME ${name}
-  cm_run_task run-example
-end
-'''

README.md

@@ -1,429 +1,170 @@
 <details>
 <summary>Table of Contents</summary>
 
-- [Ratatui](#ratatui)
-  - [Installation](#installation)
-  - [Introduction](#introduction)
-  - [Other Documentation](#other-documentation)
-  - [Quickstart](#quickstart)
-  - [Status of this fork](#status-of-this-fork)
-  - [Rust version requirements](#rust-version-requirements)
-  - [Widgets](#widgets)
-    - [Built in](#built-in)
-    - [Third\-party libraries, bootstrapping templates and
-      widgets](#third-party-libraries-bootstrapping-templates-and-widgets)
-  - [Apps](#apps)
-  - [Alternatives](#alternatives)
-  - [Acknowledgments](#acknowledgments)
-  - [License](#license)
+- [Quickstart](#quickstart)
+- [Documentation](#documentation)
+- [Templates](#templates)
+- [Built with Ratatui](#built-with-ratatui)
+- [Alternatives](#alternatives)
+- [Contributing](#contributing)
+- [Acknowledgements](#acknowledgements)
+- [License](#license)
 
 </details>
 
-<!-- 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">
 
-[![Crate Badge]][Crate] [![Docs Badge]][API Docs] [![CI Badge]][CI Workflow] [![Deps.rs
-Badge]][Deps.rs]<br> [![Codecov Badge]][Codecov] [![License Badge]](./LICENSE) [![Sponsors
-Badge]][GitHub Sponsors]<br> [![Discord Badge]][Discord Server] [![Matrix Badge]][Matrix]
-[![Forum Badge]][Forum]<br>
-
-[Ratatui Website] · [API Docs] · [Examples] · [Changelog] · [Breaking Changes]<br>
-[Contributing] · [Report a bug] · [Request a Feature] · [Create a Pull Request]
+[![Crate Badge]][Crate] [![Repo Badge]][Repo] [![Docs Badge]][Docs] [![License Badge]][License]  \
+[![CI Badge]][CI] [![Deps Badge]][Deps] [![Codecov Badge]][Codecov] [![Sponsors Badge]][Sponsors]  \
+[Ratatui Website] · [Docs] · [Widget Examples] · [App Examples] · [Changelog]  \
+[Breaking Changes] · [Contributing] · [Report a bug] · [Request a Feature]
 
 </div>
 
-# Ratatui
-
-[Ratatui][Ratatui Website] is a crate for cooking up terminal user interfaces in Rust. It is a
-lightweight library that provides a set of widgets and utilities to build complex Rust TUIs.
-Ratatui was forked from the [tui-rs] crate in 2023 in order to continue its development.
-
-## Installation
-
-Add `ratatui` as a dependency to your cargo.toml:
-
-```shell
-cargo add ratatui
-```
-
-Ratatui uses [Crossterm] by default as it works on most platforms. See the [Installation]
-section of the [Ratatui Website] for more details on how to use other backends ([Termion] /
-[Termwiz]).
-
-## Introduction
-
-Ratatui is based on the principle of immediate rendering with intermediate buffers. This means
-that for each frame, your app must render all widgets that are supposed to be part of the UI.
-This is in contrast to the retained mode style of rendering where widgets are updated and then
-automatically redrawn on the next frame. See the [Rendering] section of the [Ratatui Website]
-for more info.
-
-You can also watch the [FOSDEM 2024 talk] about Ratatui which gives a brief introduction to
-terminal user interfaces and showcases the features of Ratatui, along with a hello world demo.
-
-## Other documentation
-
-- [Ratatui Website] - explains the library's concepts and provides step-by-step tutorials
-- [Ratatui Forum][Forum] - a place to ask questions and discuss the library
-- [API Docs] - the full API documentation for the library on docs.rs.
-- [Examples] - a collection of examples that demonstrate how to use the library.
-- [Contributing] - Please read this if you are interested in contributing to the project.
-- [Changelog] - generated by [git-cliff] utilizing [Conventional Commits].
-- [Breaking Changes] - a list of breaking changes in the library.
+[Ratatui][Ratatui Website] (_ˌræ.təˈtu.i_) is a Rust crate for cooking up terminal user interfaces
+(TUIs). It provides a simple and flexible way to create text-based user interfaces in the terminal,
+which can be used for command-line applications, dashboards, and other interactive console programs.
 
 ## Quickstart
 
-The following example demonstrates the minimal amount of code necessary to setup a terminal and
-render "Hello World!". The full code for this example which contains a little more detail is in
-the [Examples] directory. For more guidance on different ways to structure your application see
-the [Application Patterns] and [Hello World tutorial] sections in the [Ratatui Website] and the
-various [Examples]. There are also several starter templates available in the [templates]
-repository.
+Ratatui has [templates] available to help you get started quickly. You can use the
+[`cargo-generate`] command to create a new project with Ratatui:
 
-Every application built with `ratatui` needs to implement the following steps:
+```shell
+cargo install --locked cargo-generate
+cargo generate ratatui/templates
+```
 
-- Initialize the terminal
-- A main loop to:
-  - Handle input events
-  - Draw the UI
-- Restore the terminal state
-
-The library contains a [`prelude`] module that re-exports the most commonly used traits and
-types for convenience. Most examples in the documentation will use this instead of showing the
-full path of each type.
-
-### Initialize and restore the terminal
-
-The [`Terminal`] type is the main entry point for any Ratatui application. It is a light
-abstraction over a choice of [`Backend`] implementations that provides functionality to draw
-each frame, clear the screen, hide the cursor, etc. It is parametrized over any type that
-implements the [`Backend`] trait which has implementations for [Crossterm], [Termion] and
-[Termwiz].
-
-Most applications should enter the Alternate Screen when starting and leave it when exiting and
-also enable raw mode to disable line buffering and enable reading key events. See the [`backend`
-module] and the [Backends] section of the [Ratatui Website] for more info.
-
-### Drawing the UI
-
-The drawing logic is delegated to a closure that takes a [`Frame`] instance as argument. The
-[`Frame`] provides the size of the area to draw to and allows the app to render any [`Widget`]
-using the provided [`render_widget`] method. After this closure returns, a diff is performed and
-only the changes are drawn to the terminal. See the [Widgets] section of the [Ratatui Website]
-for more info.
-
-### Handling events
-
-Ratatui does not include any input handling. Instead event handling can be implemented by
-calling backend library methods directly. See the [Handling Events] section of the [Ratatui
-Website] for more info. For example, if you are using [Crossterm], you can use the
-[`crossterm::event`] module to handle events.
-
-### Example
+Selecting the Hello World template produces the following application:
 
 ```rust
-use std::io::{self, stdout};
+use color_eyre::Result;
+use crossterm::event::{self, Event};
+use ratatui::{DefaultTerminal, Frame};
 
-use ratatui::{
-    backend::CrosstermBackend,
-    crossterm::{
-        event::{self, Event, KeyCode},
-        terminal::{
-            disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen,
-        },
-        ExecutableCommand,
-    },
-    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 main() -> Result<()> {
+    color_eyre::install()?;
+    let terminal = ratatui::init();
+    let result = run(terminal);
+    ratatui::restore();
+    result
 }
 
-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);
-            }
+fn run(mut terminal: DefaultTerminal) -> Result<()> {
+    loop {
+        terminal.draw(render)?;
+        if matches!(event::read()?, Event::Key(_)) {
+            break Ok(());
         }
     }
-    Ok(false)
 }
 
-fn ui(frame: &mut Frame) {
-    frame.render_widget(
-        Paragraph::new("Hello World!").block(Block::bordered().title("Greeting")),
-        frame.size(),
-    );
+fn render(frame: &mut Frame) {
+    frame.render_widget("hello world", frame.area());
 }
 ```
 
-Running this example produces the following output:
+## Documentation
 
-![docsrs-hello]
+- [Docs] - the full API documentation for the library on docs.rs.
+- [Ratatui Website] - explains the library's concepts and provides step-by-step tutorials.
+- [Ratatui Forum] - a place to ask questions and discuss the library.
+- [Widget Examples] - a collection of examples that demonstrate how to use the library.
+- [App Examples] - a collection of more complex examples that demonstrate how to build apps.
+- [Changelog] - generated by [git-cliff] utilizing [Conventional Commits].
+- [Breaking Changes] - a list of breaking changes in the library.
 
-## Layout
+You can also watch the [EuroRust 2024 talk] to learn about common concepts in Ratatui and what's
+possible to build with it.
 
-The library comes with a basic yet useful layout management object called [`Layout`] which
-allows you to split the available space into multiple areas and then render widgets in each
-area. This lets you describe a responsive terminal UI by nesting layouts. See the [Layout]
-section of the [Ratatui Website] for more info.
+## Templates
 
-```rust
-use ratatui::{
-    layout::{Constraint, Layout},
-    widgets::Block,
-    Frame,
-};
+If you're looking to get started quickly, you can use one of the available templates from the
+[templates] repository using [`cargo-generate`]:
 
-fn ui(frame: &mut Frame) {
-    let [title_area, main_area, status_area] = Layout::vertical([
-        Constraint::Length(1),
-        Constraint::Min(0),
-        Constraint::Length(1),
-    ])
-    .areas(frame.size());
-    let [left_area, right_area] =
-        Layout::horizontal([Constraint::Percentage(50), Constraint::Percentage(50)])
-            .areas(main_area);
-
-    frame.render_widget(Block::bordered().title("Title Bar"), title_area);
-    frame.render_widget(Block::bordered().title("Status Bar"), status_area);
-    frame.render_widget(Block::bordered().title("Left"), left_area);
-    frame.render_widget(Block::bordered().title("Right"), right_area);
-}
+```shell
+cargo generate ratatui/templates
 ```
 
-Running this example produces the following output:
+## Built with Ratatui
 
-![docsrs-layout]
+[![Awesome](https://awesome.re/badge-flat2.svg)][awesome-ratatui]
 
-## Text and styling
-
-The [`Text`], [`Line`] and [`Span`] types are the building blocks of the library and are used in
-many places. [`Text`] is a list of [`Line`]s and a [`Line`] is a list of [`Span`]s. A [`Span`]
-is a string with a specific style.
-
-The [`style` module] provides types that represent the various styling options. The most
-important one is [`Style`] which represents the foreground and background colors and the text
-attributes of a [`Span`]. The [`style` module] also provides a [`Stylize`] trait that allows
-short-hand syntax to apply a style to widgets and text. See the [Styling Text] section of the
-[Ratatui Website] for more info.
-
-```rust
-use ratatui::{
-    layout::{Constraint, Layout},
-    style::{Color, Modifier, Style, Stylize},
-    text::{Line, Span},
-    widgets::{Block, Paragraph},
-    Frame,
-};
-
-fn ui(frame: &mut Frame) {
-    let areas = Layout::vertical([Constraint::Length(1); 4]).split(frame.size());
-
-    let line = Line::from(vec![
-        Span::raw("Hello "),
-        Span::styled(
-            "World",
-            Style::new()
-                .fg(Color::Green)
-                .bg(Color::White)
-                .add_modifier(Modifier::BOLD),
-        ),
-        "!".red().on_light_yellow().italic(),
-    ]);
-    frame.render_widget(line, areas[0]);
-
-    // using the short-hand syntax and implicit conversions
-    let paragraph = Paragraph::new("Hello World!".red().on_white().bold());
-    frame.render_widget(paragraph, areas[1]);
-
-    // style the whole widget instead of just the text
-    let paragraph = Paragraph::new("Hello World!").style(Style::new().red().on_white());
-    frame.render_widget(paragraph, areas[2]);
-
-    // use the simpler short-hand syntax
-    let paragraph = Paragraph::new("Hello World!").blue().on_yellow();
-    frame.render_widget(paragraph, areas[3]);
-}
-```
-
-Running this example produces the following output:
-
-![docsrs-styling]
-
-[Ratatui Website]: https://ratatui.rs/
-[Installation]: https://ratatui.rs/installation/
-[Rendering]: https://ratatui.rs/concepts/rendering/
-[Application Patterns]: https://ratatui.rs/concepts/application-patterns/
-[Hello World tutorial]: https://ratatui.rs/tutorials/hello-world/
-[Backends]: https://ratatui.rs/concepts/backends/
-[Widgets]: https://ratatui.rs/how-to/widgets/
-[Handling Events]: https://ratatui.rs/concepts/event-handling/
-[Layout]: https://ratatui.rs/how-to/layout/
-[Styling Text]: https://ratatui.rs/how-to/render/style-text/
-[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
-[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
-[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
-[`Frame`]: terminal::Frame
-[`render_widget`]: terminal::Frame::render_widget
-[`Widget`]: widgets::Widget
-[`Layout`]: layout::Layout
-[`Text`]: text::Text
-[`Line`]: text::Line
-[`Span`]: text::Span
-[`Style`]: style::Style
-[`style` module]: style
-[`Stylize`]: style::Stylize
-[`Backend`]: backend::Backend
-[`backend` module]: backend
-[`crossterm::event`]: https://docs.rs/crossterm/latest/crossterm/event/index.html
-[Crate]: https://crates.io/crates/ratatui
-[Crossterm]: https://crates.io/crates/crossterm
-[Termion]: https://crates.io/crates/termion
-[Termwiz]: https://crates.io/crates/termwiz
-[tui-rs]: https://crates.io/crates/tui
-[GitHub Sponsors]: https://github.com/sponsors/ratatui-org
-[Crate Badge]: https://img.shields.io/crates/v/ratatui?logo=rust&style=flat-square&logoColor=E05D44&color=E05D44
-[License Badge]: https://img.shields.io/crates/l/ratatui?style=flat-square&color=1370D3
-[CI Badge]: https://img.shields.io/github/actions/workflow/status/ratatui-org/ratatui/ci.yml?style=flat-square&logo=github
-[CI Workflow]: https://github.com/ratatui-org/ratatui/actions/workflows/ci.yml
-[Codecov Badge]: https://img.shields.io/codecov/c/github/ratatui-org/ratatui?logo=codecov&style=flat-square&token=BAQ8SOKEST&color=C43AC3&logoColor=C43AC3
-[Codecov]: https://app.codecov.io/gh/ratatui-org/ratatui
-[Deps.rs Badge]: https://deps.rs/repo/github/ratatui-org/ratatui/status.svg?style=flat-square
-[Deps.rs]: https://deps.rs/repo/github/ratatui-org/ratatui
-[Discord Badge]: https://img.shields.io/discord/1070692720437383208?label=discord&logo=discord&style=flat-square&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
-[Matrix Badge]: https://img.shields.io/matrix/ratatui-general%3Amatrix.org?style=flat-square&logo=matrix&label=Matrix&color=C43AC3
-[Matrix]: https://matrix.to/#/#ratatui:matrix.org
-[Forum Badge]: https://img.shields.io/discourse/likes?server=https%3A%2F%2Fforum.ratatui.rs&style=flat-square&logo=discourse&label=forum&color=C43AC3
-[Forum]: https://forum.ratatui.rs
-[Sponsors Badge]: https://img.shields.io/github/sponsors/ratatui-org?logo=github&style=flat-square&color=1370D3
-
-<!-- cargo-rdme end -->
-
-## Status of this fork
-
-In response to the original maintainer [**Florian Dehau**](https://github.com/fdehau)'s issue
-regarding the [future of `tui-rs`](https://github.com/fdehau/tui-rs/issues/654), several members of
-the community forked the project and created this crate. We look forward to continuing the work
-started by Florian 🚀
-
-In order to organize ourselves, we currently use a [Discord server](https://discord.gg/pMCEU9hNEj),
-feel free to join and come chat! There is also a [Matrix](https://matrix.org/) bridge available at
-[#ratatui:matrix.org](https://matrix.to/#/#ratatui:matrix.org).
-
-While we do utilize Discord for coordinating, it's not essential for contributing. We have recently
-launched the [Ratatui Forum][Forum], and our primary open-source workflow is centered around GitHub.
-For bugs and features, we rely on GitHub. Please [Report a bug], [Request a Feature] or [Create a
-Pull Request].
-
-Please make sure you read the updated [contributing](./CONTRIBUTING.md) guidelines, especially if
-you are interested in working on a PR or issue opened in the previous repository.
-
-## Widgets
-
-### Built in
-
-The library comes with the following
-[widgets](https://docs.rs/ratatui/latest/ratatui/widgets/index.html):
-
-- [BarChart](https://docs.rs/ratatui/latest/ratatui/widgets/struct.BarChart.html)
-- [Block](https://docs.rs/ratatui/latest/ratatui/widgets/block/struct.Block.html)
-- [Calendar](https://docs.rs/ratatui/latest/ratatui/widgets/calendar/index.html)
-- [Canvas](https://docs.rs/ratatui/latest/ratatui/widgets/canvas/struct.Canvas.html) which allows
-  rendering [points, lines, shapes and a world
-  map](https://docs.rs/ratatui/latest/ratatui/widgets/canvas/index.html)
-- [Chart](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Chart.html)
-- [Clear](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Clear.html)
-- [Gauge](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Gauge.html)
-- [List](https://docs.rs/ratatui/latest/ratatui/widgets/struct.List.html)
-- [Paragraph](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Paragraph.html)
-- [Scrollbar](https://docs.rs/ratatui/latest/ratatui/widgets/scrollbar/struct.Scrollbar.html)
-- [Sparkline](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Sparkline.html)
-- [Table](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Table.html)
-- [Tabs](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Tabs.html)
-
-Each widget has an associated example which can be found in the [Examples] folder. Run each example
-with cargo (e.g. to run the gauge example `cargo run --example gauge`), and quit by pressing `q`.
-
-You can also run all examples by running `cargo make run-examples` (requires `cargo-make` that can
-be installed with `cargo install cargo-make`).
-
-### Third-party libraries, bootstrapping templates and widgets
-
-- [ansi-to-tui](https://github.com/uttarayan21/ansi-to-tui) — Convert ansi colored text to
-  `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
-  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
-- [tui-clap](https://github.com/kegesch/tui-clap-rs) — Use clap-rs together with Tui-rs
-- [tui-log](https://github.com/kegesch/tui-log-rs) — Example of how to use logging with Tui-rs
-- [tui-logger](https://github.com/gin66/tui-logger) — Logger and Widget for Tui-rs
-- [tui-realm](https://github.com/veeso/tui-realm) — Tui-rs framework to build stateful applications
-  with a React/Elm inspired approach
-- [tui-realm-treeview](https://github.com/veeso/tui-realm-treeview) — Treeview component for
-  Tui-realm
-- [tui-rs-tree-widgets](https://github.com/EdJoPaTo/tui-rs-tree-widget) — Widget for tree data
-  structures.
-- [tui-windows](https://github.com/markatk/tui-windows-rs) — Tui-rs abstraction to handle multiple
-  windows and their rendering
-- [tui-textarea](https://github.com/rhysd/tui-textarea) — Simple yet powerful multi-line text editor
-  widget supporting several key shortcuts, undo/redo, text search, etc.
-- [tui-input](https://github.com/sayanarijit/tui-input) — TUI input library supporting multiple
-  backends and tui-rs.
-- [tui-term](https://github.com/a-kenji/tui-term) — A pseudoterminal widget library
-  that enables the rendering of terminal applications as ratatui widgets.
-
-## Apps
-
-Check out [awesome-ratatui](https://github.com/ratatui-org/awesome-ratatui) for a curated list of
-awesome apps/libraries built with `ratatui`!
+Check out the [showcase] section of the website, or the [awesome-ratatui] repository for a curated
+list of awesome apps and libraries built with Ratatui!
 
 ## Alternatives
 
-You might want to checkout [Cursive](https://github.com/gyscos/Cursive) for an alternative solution
-to build text user interfaces in Rust.
+- [Cursive](https://crates.io/crates/cursive) - a ncurses-based TUI library.
+- [iocraft](https://crates.io/crates/iocraft) - a declarative TUI library.
 
-## Acknowledgments
+## Contributing
 
-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.
+[![Discord Badge]][Discord Server] [![Matrix Badge]][Matrix] [![Forum Badge]][Ratatui Forum]
+
+Feel free to join our [Discord server](https://discord.gg/pMCEU9hNEj) for discussions and questions!
+There is also a [Matrix](https://matrix.org/) bridge available at
+[#ratatui:matrix.org](https://matrix.to/#/#ratatui:matrix.org). We have also recently launched the
+[Ratatui Forum].
+
+We rely on GitHub for [bugs][Report a bug] and [feature requests][Request a Feature].
+
+Please make sure you read the [contributing](./CONTRIBUTING.md) guidelines before [creating a pull
+request][Create a Pull Request].
+
+## Acknowledgements
+
+Ratatui was forked from the [tui-rs] crate in 2023 in order to continue its development. None of
+this could be possible without [Florian Dehau] who originally created [tui-rs] which inspired many
+Rust TUIs.
+
+Special thanks to [Pavel Fomchenkov] for his work in designing an awesome logo for the Ratatui
+project and organization.
 
 ## License
 
-[MIT](./LICENSE)
+This project is licensed under the [MIT License][License].
+
+[Repo]: https://github.com/ratatui/ratatui
+[Ratatui Website]: https://ratatui.rs/
+[Ratatui Forum]: https://forum.ratatui.rs
+[Docs]: https://docs.rs/ratatui
+[Widget Examples]: https://github.com/ratatui/ratatui/tree/main/ratatui-widgets/examples
+[App Examples]: https://github.com/ratatui/ratatui/tree/main/examples
+[Changelog]: https://github.com/ratatui/ratatui/blob/main/CHANGELOG.md
+[git-cliff]: https://git-cliff.org
+[Conventional Commits]: https://www.conventionalcommits.org
+[Breaking Changes]: https://github.com/ratatui/ratatui/blob/main/BREAKING-CHANGES.md
+[EuroRust 2024 talk]: https://www.youtube.com/watch?v=hWG51Mc1DlM
+[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
+[Contributing]: https://github.com/ratatui/ratatui/blob/main/CONTRIBUTING.md
+[Crate]: https://crates.io/crates/ratatui
+[tui-rs]: https://crates.io/crates/tui
+[Sponsors]: https://github.com/sponsors/ratatui
+[Crate Badge]: https://img.shields.io/crates/v/ratatui?logo=rust&style=flat-square&color=E05D44
+[Repo Badge]: https://img.shields.io/badge/repo-ratatui/ratatui-1370D3?style=flat-square&logo=github
+[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/ratatui/ci.yml?style=flat-square&logo=github
+[CI]: 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
+[Codecov]: https://app.codecov.io/gh/ratatui/ratatui
+[Deps Badge]: https://deps.rs/repo/github/ratatui/ratatui/status.svg?path=ratatui&style=flat-square
+[Deps]: https://deps.rs/repo/github/ratatui/ratatui?path=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/badge/docs-ratatui-1370D3?style=flat-square&logo=rust
+[Matrix Badge]: https://img.shields.io/matrix/ratatui-general%3Amatrix.org?style=flat-square&logo=matrix&label=Matrix&color=C43AC3
+[Matrix]: https://matrix.to/#/#ratatui:matrix.org
+[Forum Badge]: https://img.shields.io/discourse/likes?server=https%3A%2F%2Fforum.ratatui.rs&style=flat-square&logo=discourse&label=forum&color=C43AC3
+[Sponsors Badge]: https://img.shields.io/github/sponsors/ratatui?logo=github&style=flat-square&color=1370D3
+[templates]: https://github.com/ratatui/templates/
+[showcase]: https://ratatui.rs/showcase/
+[awesome-ratatui]: https://github.com/ratatui/awesome-ratatui
+[Pavel Fomchenkov]: https://github.com/nawok
+[Florian Dehau]: https://github.com/fdehau
+[`cargo-generate`]: https://crates.io/crates/cargo-generate
+[License]: ./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>

bacon.toml

@@ -8,101 +8,64 @@
 default_job = "check"
 
 [jobs.check]
-command = ["cargo", "check", "--all-features", "--color", "always"]
+command = ["cargo", "xtask", "check"]
 need_stdout = false
 
 [jobs.check-all]
-command = ["cargo", "check", "--all-targets", "--all-features", "--color", "always"]
+command = ["cargo", "xtask", "check", "--all-features"]
 need_stdout = false
 
 [jobs.check-crossterm]
-command = ["cargo", "check", "--color", "always", "--all-targets", "--no-default-features", "--features", "crossterm"]
+command = ["cargo", "xtask", "check-crossterm"]
 need_stdout = false
 
 [jobs.check-termion]
-command = ["cargo", "check", "--color", "always", "--all-targets", "--no-default-features", "--features", "termion"]
+command = ["cargo", "xtask", "check-termion"]
 need_stdout = false
 
 [jobs.check-termwiz]
-command = ["cargo", "check", "--color", "always", "--all-targets", "--no-default-features", "--features", "termwiz"]
+command = ["cargo", "xtask", "check-termwiz"]
 need_stdout = false
 
-[jobs.clippy]
-command = [
-    "cargo", "clippy",
-    "--all-targets",
-    "--color", "always",
-]
+[jobs.clippy-all]
+command = ["cargo", "xtask", "clippy"]
 need_stdout = false
 
 [jobs.test]
-command = [
-    "cargo", "test",
-    "--all-features",
-    "--color", "always",
-    "--", "--color", "always", # see https://github.com/Canop/bacon/issues/124
-]
+command = ["cargo", "xtask", "test"]
 need_stdout = true
 
 [jobs.test-unit]
-command = [
-    "cargo", "test",
-    "--lib",
-    "--all-features",
-    "--color", "always",
-    "--", "--color", "always", # see https://github.com/Canop/bacon/issues/124
-]
+command = ["cargo", "xtask", "test-libs"]
 need_stdout = true
 
 [jobs.doc]
-command = [
-    "cargo", "+nightly", "doc",
-    "-Zunstable-options", "-Zrustdoc-scrape-examples",
-    "--all-features",
-    "--color", "always",
-    "--no-deps",
-]
-env.RUSTDOCFLAGS = "--cfg docsrs"
+command = ["cargo", "xtask", "docs"]
 need_stdout = false
 
-# If the doc compiles, then it opens in your browser and bacon switches
-# to the previous job
 [jobs.doc-open]
-command = [
-    "cargo", "+nightly", "doc",
-    "-Zunstable-options", "-Zrustdoc-scrape-examples",
-    "--all-features",
-    "--color", "always",
-    "--no-deps",
-    "--open",
-]
-env.RUSTDOCFLAGS = "--cfg docsrs"
+command = ["cargo", "xtask", "docs", "--open"]
+on_success = "job:doc"
 need_stdout = false
-on_success = "job:doc" # so that we don't open the browser at each change
 
 [jobs.coverage]
-command = [
-    "cargo", "llvm-cov",
-    "--lcov", "--output-path", "target/lcov.info",
-    "--all-features",
-    "--color", "always",
-]
+command = ["cargo", "xtask", "coverage"]
 
 [jobs.coverage-unit-tests-only]
-command = [
-    "cargo", "llvm-cov",
-    "--lcov", "--output-path", "target/lcov.info",
-    "--lib",
-    "--all-features",
-    "--color", "always",
-]
+command = ["cargo", "xtask", "coverage-unit"]
+
+[jobs.hack]
+command = ["cargo", "xtask", "hack"]
+
+[jobs.format]
+command = ["cargo", "xtask", "format"]
 
 # You may define here keybindings that would be specific to
 # a project, for example a shortcut to launch a specific job.
 # Shortcuts to internal functions (scrolling, toggling, etc.)
 # should go in your personal global prefs.toml file instead.
 [keybindings]
-# alt-m = "job:my-job"
+ctrl-h = "job:hack"
 ctrl-c = "job:check-crossterm"
 ctrl-t = "job:check-termion"
 ctrl-w = "job:check-termwiz"
@@ -110,3 +73,4 @@ v = "job:coverage"
 ctrl-v = "job:coverage-unit-tests-only"
 u = "job:test-unit"
 n = "job:nextest"
+f = "job:format"

benches/main/rect.rs

@@ -1,24 +0,0 @@
-use criterion::{black_box, criterion_group, BenchmarkId, Criterion};
-use ratatui::layout::Rect;
-
-fn rect_rows_benchmark(c: &mut Criterion) {
-    let rect_sizes = vec![
-        Rect::new(0, 0, 1, 16),
-        Rect::new(0, 0, 1, 1024),
-        Rect::new(0, 0, 1, 65535),
-    ];
-    let mut group = c.benchmark_group("rect_rows");
-    for rect in rect_sizes {
-        group.bench_with_input(BenchmarkId::new("rows", rect.height), &rect, |b, rect| {
-            b.iter(|| {
-                for row in rect.rows() {
-                    // Perform any necessary operations on each row
-                    black_box(row);
-                }
-            });
-        });
-    }
-    group.finish();
-}
-
-criterion_group!(benches, rect_rows_benchmark);

cliff.toml

@@ -2,7 +2,7 @@
 # https://git-cliff.org/docs/configuration
 
 [remote.github]
-owner = "ratatui-org"
+owner = "ratatui"
 repo = "ratatui"
 
 [changelog]
@@ -24,25 +24,15 @@ 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 %}\
+  {% if commit.remote.username %} by @{{ commit.remote.username }}{%- endif -%}\
+  {% if commit.remote.pr_number %} in [#{{ commit.remote.pr_number }}]({{ self::remote_url() }}/pull/{{ commit.remote.pr_number }}){%- endif %}\
 {%- if commit.breaking %} [**breaking**]{% endif %}
-{%- if commit.body %}\n\n{{ commit.body | indent(prefix="  > ", first=true, blank=true) }}
-{%- endif %}
-{%- for footer in commit.footers %}\n
-{%- if footer.token != "Signed-off-by" and footer.token != "Co-authored-by" %}
-  >
-{{ footer.token | indent(prefix="  > ", first=true, blank=true) }}
-{{- footer.separator }}
-{{- footer.value| indent(prefix="  > ", first=false, blank=true)  }}
-{%- endif %}
-{%- endfor %}
 {% endmacro -%}
 
 {% for group, commits in commits | group_by(attribute="group") %}

clippy.toml

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

deny.toml

@@ -4,13 +4,16 @@
 version = 2
 confidence-threshold = 0.8
 allow = [
-    "Apache-2.0",
-    "BSD-2-Clause",
-    "BSD-3-Clause",
-    "ISC",
-    "MIT",
-    "Unicode-DFS-2016",
-    "WTFPL",
+  "Apache-2.0",
+  "BSD-2-Clause",
+  "BSD-3-Clause",
+  "ISC",
+  "MIT",
+  "OpenSSL",
+  "Unicode-3.0",
+  "Unicode-DFS-2016",
+  "WTFPL",
+  "Zlib",
 ]
 
 [advisories]
@@ -23,3 +26,15 @@ multiple-versions = "allow"
 unknown-registry = "deny"
 unknown-git = "warn"
 allow-registry = ["https://github.com/rust-lang/crates.io-index"]
+
+[[licenses.clarify]]
+crate = "ring"
+# SPDX considers OpenSSL to encompass both the OpenSSL and SSLeay licenses
+# https://spdx.org/licenses/OpenSSL.html
+# ISC - Both BoringSSL and ring use this for their new files
+# MIT - "Files in third_party/ have their own licenses, as described therein. The MIT
+# license, for third_party/fiat, which, unlike other third_party directories, is
+# compiled into non-test libraries, is included below."
+# OpenSSL - Obviously
+expression = "ISC AND MIT AND OpenSSL"
+license-files = [{ path = "LICENSE", hash = 0xbd0eed23 }]

examples/README.md

@@ -1,6 +1,19 @@
 # Examples
 
-This folder might use unreleased code. View the examples for the latest release instead.
+This folder contains examples that are more app focused. There are also other examples in example
+folders under each crate folder e.g. [ratatui examples], [ratatui-widgets examples].
+
+[ratatui examples]: ../ratatui/examples
+[ratatui-widgets examples]: ../ratatui-widgets/examples
+
+You can run these examples using:
+
+```shell
+cargo run -p example-name
+```
+
+This folder might use unreleased code. Consider viewing the examples in the `latest` branch instead
+of the `main` branch for code which is guaranteed to work with the released ratatui version.
 
 > [!WARNING]
 >
@@ -10,469 +23,44 @@ 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>.
-> - If you're viewing this file on GitHub, there is a combo box at the top of this page  which
+>   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].
 >
 > We don't keep the CHANGELOG updated with unreleased changes, check the git commit history or run
 > `git-cliff -u` against a cloned version of this repository.
 
-## Design choices
+## Demo
 
-The examples contain some opinionated choices in order to make it easier for newer rustaceans to
-easily be productive in creating applications:
+This is the original demo example from the main README. It is available for each of the backends.
+[Source](./apps/demo/).
 
-- Each example has an App struct, with methods that implement a main loop, handle events and drawing
-  the UI.
-- We use color_eyre for handling errors and panics. See [How to use color-eyre with Ratatui] on the
-  website for more information about this.
-- Common code is not extracted into a separate file. This makes each example self-contained and easy
-  to read as a whole.
-
-Not every example has been updated with all these points in mind yet, however over time they will
-be. None of the above choices are strictly necessary for Ratatui apps, but these choices make
-examples easier to run, maintain and explain. These choices are designed to help newer users fall
-into the pit of success when incorporating example code into their own apps. We may also eventually
-move some of these design choices into the core of Ratatui to simplify apps.
-
-[How to use color-eyre with Ratatui]: https://ratatui.rs/how-to/develop-apps/color_eyre/
+![Demo](https://github.com/ratatui/ratatui/blob/images/examples/demo.gif?raw=true)
 
 ## Demo2
 
-This is the demo example from the main README and crate page. Source: [demo2](./demo2/).
+This is the demo example from the main README and crate page. [Source](./apps/demo2/).
 
-```shell
-cargo run --example=demo2 --features="crossterm widget-calendar"
-```
+![Demo2](https://github.com/ratatui/ratatui/blob/images/examples/demo2.gif?raw=true)
 
-![Demo2][demo2.gif]
+## Mouse Drawing demo
 
-## Demo
+Shows how to handle mouse events. [Source](./apps/mouse-drawing/).
 
-This is the previous demo example from the main README. It is available for each of the backends. Source:
-[demo.rs](./demo/).
+## Async GitHub demo
 
-```shell
-cargo run --example=demo --features=crossterm
-cargo run --example=demo --no-default-features --features=termion
-cargo run --example=demo --no-default-features --features=termwiz
-```
+Shows how to fetch data from GitHub API asynchronously. [Source](./apps/async-github/).
 
-![Demo][demo.gif]
+## Weather demo
 
-## Hello World
+Shows how to render weather data using barchart widget. [Source](./apps/weather/).
 
-This is a pretty boring example, but it contains some good documentation
-on writing tui apps. Source: [hello_world.rs](./hello_world.rs).
+## Calendar explorer demo
 
-```shell
-cargo run --example=hello_world --features=crossterm
-```
-
-![Hello World][hello_world.gif]
-
-## Barchart
-
-Demonstrates the [`BarChart`](https://docs.rs/ratatui/latest/ratatui/widgets/struct.BarChart.html)
-widget. Source: [barchart.rs](./barchart.rs).
-
-```shell
-cargo run --example=barchart --features=crossterm
-```
-
-![Barchart][barchart.gif]
-
-## Barchart (Grouped)
-
-Demonstrates the [`BarChart`](https://docs.rs/ratatui/latest/ratatui/widgets/struct.BarChart.html)
-widget with groups. Source: [barchart-grouped.rs](./barchart-grouped.rs).
-
-```shell
-cargo run --example=barchart-grouped --features=crossterm
-```
-
-![Barchart Grouped][barchart-grouped.gif]
-
-## Block
-
-Demonstrates the [`Block`](https://docs.rs/ratatui/latest/ratatui/widgets/block/struct.Block.html)
-widget. Source: [block.rs](./block.rs).
-
-```shell
-cargo run --example=block --features=crossterm
-```
-
-![Block][block.gif]
-
-## Calendar
-
-Demonstrates the [`Calendar`](https://docs.rs/ratatui/latest/ratatui/widgets/calendar/index.html)
-widget. Source: [calendar.rs](./calendar.rs).
-
-```shell
-cargo run --example=calendar --features="crossterm widget-calendar"
-```
-
-![Calendar][calendar.gif]
-
-## Canvas
-
-Demonstrates the [`Canvas`](https://docs.rs/ratatui/latest/ratatui/widgets/canvas/index.html) widget
-and related shapes in the
-[`canvas`](https://docs.rs/ratatui/latest/ratatui/widgets/canvas/index.html) module. Source:
-[canvas.rs](./canvas.rs).
-
-```shell
-cargo run --example=canvas --features=crossterm
-```
-
-![Canvas][canvas.gif]
-
-## Chart
-
-Demonstrates the [`Chart`](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Chart.html) widget.
-Source: [chart.rs](./chart.rs).
-
-```shell
-cargo run --example=chart --features=crossterm
-```
-
-![Chart][chart.gif]
-
-## Colors
-
-Demonstrates the available [`Color`](https://docs.rs/ratatui/latest/ratatui/style/enum.Color.html)
-options. These can be used in any style field. Source: [colors.rs](./colors.rs).
-
-```shell
-cargo run --example=colors --features=crossterm
-```
-
-![Colors][colors.gif]
-
-## Colors (RGB)
-
-Demonstrates the available RGB
-[`Color`](https://docs.rs/ratatui/latest/ratatui/style/enum.Color.html) options. These can be used
-in any style field. Source: [colors_rgb.rs](./colors_rgb.rs). Uses a half block technique to render
-two square-ish pixels in the space of a single rectangular terminal cell.
-
-```shell
-cargo run --example=colors_rgb --features=crossterm
-```
-
-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>
-
-## Constraint Explorer
-
-Demonstrates the behaviour of each
-[`Constraint`](https://docs.rs/ratatui/latest/ratatui/layout/enum.Constraint.html) option with
-respect to each other across different `Flex` modes.
-
-```shell
-cargo run --example=constraint-explorer --features=crossterm
-```
-
-![Constraint Explorer][constraint-explorer.gif]
-
-## Constraints
-
-Demonstrates how to use
-[`Constraint`](https://docs.rs/ratatui/latest/ratatui/layout/enum.Constraint.html) options for
-defining layout element sizes.
-
-![Constraints][constraints.gif]
-
-```shell
-cargo run --example=constraints --features=crossterm
-```
-
-## Custom Widget
-
-Demonstrates how to implement the
-[`Widget`](https://docs.rs/ratatui/latest/ratatui/widgets/trait.Widget.html) trait. Also shows mouse
-interaction. Source: [custom_widget.rs](./custom_widget.rs).
-
-```shell
-cargo run --example=custom_widget --features=crossterm
-```
-
-![Custom Widget][custom_widget.gif]
-
-## Gauge
-
-Demonstrates the [`Gauge`](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Gauge.html) widget.
-Source: [gauge.rs](./gauge.rs).
-
-```shell
-cargo run --example=gauge --features=crossterm
-```
-
-![Gauge][gauge.gif]
-
-## Flex
-
-Demonstrates the different [`Flex`](https://docs.rs/ratatui/latest/ratatui/layout/enum.Flex.html)
-modes for controlling layout space distribution.
-
-```shell
-cargo run --example=flex --features=crossterm
-```
-
-![Flex][flex.gif]
-
-## Line Gauge
-
-Demonstrates the [`Line
-Gauge`](https://docs.rs/ratatui/latest/ratatui/widgets/struct.LineGauge.html) widget. Source:
-[line_gauge.rs](./line_gauge.rs).
-
-```shell
-cargo run --example=line_gauge --features=crossterm
-```
-
-![LineGauge][line_gauge.gif]
-
-## Hyperlink
-
-Demonstrates how to use OSC 8 to create hyperlinks in the terminal.
-
-```shell
-cargo run --example=hyperlink --features="crossterm unstable-widget-ref"
-```
-
-![Hyperlink][hyperlink.gif]
-
-## Inline
-
-Demonstrates how to use the
-[`Inline`](https://docs.rs/ratatui/latest/ratatui/terminal/enum.Viewport.html#variant.Inline)
-Viewport mode for ratatui apps. Source: [inline.rs](./inline.rs).
-
-```shell
-cargo run --example=inline --features=crossterm
-```
-
-![Inline][inline.gif]
-
-## Layout
-
-Demonstrates the [`Layout`](https://docs.rs/ratatui/latest/ratatui/layout/struct.Layout.html) and
-interaction between each constraint. Source:  [layout.rs](./layout.rs).
-
-```shell
-cargo run --example=layout --features=crossterm
-```
-
-![Layout][layout.gif]
-
-## List
-
-Demonstrates the [`List`](https://docs.rs/ratatui/latest/ratatui/widgets/struct.List.html) widget.
-Source: [list.rs](./list.rs).
-
-```shell
-cargo run --example=list --features=crossterm
-```
-
-![List][list.gif]
-
-## Modifiers
-
-Demonstrates the style
-[`Modifiers`](https://docs.rs/ratatui/latest/ratatui/style/struct.Modifier.html). Source:
-[modifiers.rs](./modifiers.rs).
-
-```shell
-cargo run --example=modifiers --features=crossterm
-```
-
-![Modifiers][modifiers.gif]
-
-## Minimal
-
-Demonstrates how to create a minimal `Hello World!` program.
-
-```shell
-cargo run --example=minimal --features=crossterm
-```
-
-![Minimal][minimal.gif]
-
-## Panic
-
-Demonstrates how to handle panics by ensuring that panic messages are written correctly to the
-screen. Source: [panic.rs](./panic.rs).
-
-```shell
-cargo run --example=panic --features=crossterm
-```
-
-![Panic][panic.gif]
-
-## Paragraph
-
-Demonstrates the [`Paragraph`](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Paragraph.html)
-widget. Source: [paragraph.rs](./paragraph.rs)
-
-```shell
-cargo run --example=paragraph --features=crossterm
-```
-
-![Paragraph][paragraph.gif]
-
-## Popup
-
-Demonstrates how to render a widget over the top of previously rendered widgets using the
-[`Clear`](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Clear.html) widget. Source:
-[popup.rs](./popup.rs).
-
->
-```shell
-cargo run --example=popup --features=crossterm
-```
-
-![Popup][popup.gif]
-
-## Ratatui-logo
-
-A fun example of using half blocks to render graphics Source:
-[ratatui-logo.rs](./ratatui-logo.rs).
-
->
-```shell
-cargo run --example=ratatui-logo --features=crossterm
-```
-
-![Ratatui Logo][ratatui-logo.gif]
-
-## Scrollbar
-
-Demonstrates the [`Scrollbar`](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Scrollbar.html)
-widget. Source: [scrollbar.rs](./scrollbar.rs).
-
-```shell
-cargo run --example=scrollbar --features=crossterm
-```
-
-![Scrollbar][scrollbar.gif]
-
-## Sparkline
-
-Demonstrates the [`Sparkline`](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Sparkline.html)
-widget. Source: [sparkline.rs](./sparkline.rs).
-
-```shell
-cargo run --example=sparkline --features=crossterm
-```
-
-![Sparkline][sparkline.gif]
-
-## Table
-
-Demonstrates the [`Table`](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Table.html) widget.
-Source: [table.rs](./table.rs).
-
-```shell
-cargo run --example=table --features=crossterm
-```
-
-![Table][table.gif]
-
-## Tabs
-
-Demonstrates the [`Tabs`](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Tabs.html) widget.
-Source: [tabs.rs](./tabs.rs).
-
-```shell
-cargo run --example=tabs --features=crossterm
-```
-
-![Tabs][tabs.gif]
-
-## Tracing
-
-Demonstrates how to use the [tracing crate](https://crates.io/crates/tracing) for logging. Creates
-a file named `tracing.log` in the current directory.
-
-```shell
-cargo run --example=tracing --features=crossterm
-```
-
-![Tracing][tracing.gif]
-
-## User Input
-
-Demonstrates one approach to accepting user input. Source [user_input.rs](./user_input.rs).
-
-> [!NOTE]
-> Consider using [`tui-textarea`](https://crates.io/crates/tui-textarea) or
-> [`tui-input`](https://crates.io/crates/tui-input) crates for more functional text entry UIs.
-
-```shell
-cargo run --example=user_input --features=crossterm
-```
-
-![User Input][user_input.gif]
-
-## How to update these examples
-
-These gifs were created using [VHS](https://github.com/charmbracelet/vhs). Each example has a
-corresponding `.tape` file that holds instructions for how to generate the images. Note that the
-images themselves are stored in a separate `images` git branch to avoid bloating the main
-repository.
-
-<!--
-
-Links to images to make them easier to update in bulk. Use the following script to update and upload
-the examples to the images branch. (Requires push access to the branch).
-
-```shell
-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
-[table.gif]:  https://vhs.charm.sh/vhs-6njXBytDf0rwPufUtmSSpI.gif
-[tabs.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/tabs.gif?raw=true
-[tracing.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/tracing.gif?raw=true
-[user_input.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/user_input.gif?raw=true
-
-[alpha version of Ratatui]: https://crates.io/crates/ratatui/versions
-[BREAKING-CHANGES.md]: https://github.com/ratatui-org/ratatui/blob/main/BREAKING-CHANGES.md
+Shows how to render a calendar with different styles. [Source](./apps/calendar-explorer/).

examples/apps/async-github/Cargo.toml

@@ -0,0 +1,22 @@
+[package]
+name = "async-github"
+version = "0.1.0"
+authors.workspace = true
+documentation.workspace = true
+repository.workspace = true
+homepage.workspace = true
+keywords.workspace = true
+categories.workspace = true
+readme.workspace = true
+license.workspace = true
+exclude.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+
+[dependencies]
+color-eyre = "0.6.3"
+crossterm = { workspace = true, features = ["event-stream"] }
+octocrab = "0.42.1"
+ratatui.workspace = true
+tokio = { version = "1.43.0", features = ["rt-multi-thread", "macros"] }
+tokio-stream = "0.1.17"

examples/apps/async-github/README.md

@@ -0,0 +1,9 @@
+# Async GitHub demo
+
+This example demonstrates how to use Ratatui with widgets that fetch data from GitHub API asynchronously.
+
+To run this demo:
+
+```shell
+cargo run -p async-github
+```

examples/apps/async-github/src/main.rs

@@ -1,9 +1,7 @@
 //! # [Ratatui] Async example
 //!
 //! This example demonstrates how to use Ratatui with widgets that fetch data asynchronously. It
-//! uses the `octocrab` crate to fetch a list of pull requests from the GitHub API. You will need an
-//! environment variable named `GITHUB_TOKEN` with a valid GitHub personal access token. The token
-//! does not need any special permissions.
+//! uses the `octocrab` crate to fetch a list of pull requests from the GitHub API.
 //!
 //! <https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token>
 //! <https://github.com/settings/tokens/new> to create a new token (select classic, and no scopes)
@@ -26,98 +24,81 @@
 //! 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,
 };
 
-use color_eyre::{eyre::Context, Result, Section};
-use futures::StreamExt;
+use color_eyre::Result;
 use octocrab::{
     params::{pulls::Sort, Direction},
-    OctocrabBuilder, Page,
+    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;
+use tokio_stream::StreamExt;
 
 #[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
 }
 
-fn init_octocrab() -> Result<()> {
-    let token = std::env::var("GITHUB_TOKEN")
-        .wrap_err("The GITHUB_TOKEN environment variable was not found")
-        .suggestion(
-            "Go to https://github.com/settings/tokens/new to create a token, and re-run:
-            GITHUB_TOKEN=ghp_... cargo run --example async --features crossterm",
-        )?;
-    let crab = OctocrabBuilder::new().personal_token(token).build()?;
-    octocrab::initialise(crab);
-    Ok(())
-}
-
 #[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 +107,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 +138,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 +153,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 +166,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 +179,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 +207,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 +229,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);
+            .row_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 +241,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/apps/calendar-explorer/Cargo.toml

@@ -0,0 +1,15 @@
+[package]
+name = "calendar-explorer"
+publish = false
+license.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+
+[dependencies]
+color-eyre.workspace = true
+crossterm.workspace = true
+ratatui.workspace = true
+time = { version = "0.3.37", features = ["formatting", "parsing"] }
+
+[lints]
+workspace = true

examples/apps/calendar-explorer/README.md

@@ -0,0 +1,9 @@
+# Calendar explorer demo
+
+This example shows how to render a calendar with different styles.
+
+To run this demo:
+
+```shell
+cargo run -p calendar-explorer
+```

examples/apps/calendar-explorer/src/main.rs

@@ -0,0 +1,248 @@
+//! A Ratatui example that demonstrates how to render calendar with different styles.
+//!
+//! Marks the holidays and seasons on the calendar.
+//!
+//! This example runs with the Ratatui library code in the branch that you are currently reading.
+//! See the [`latest`] branch for the code which works with the most recent Ratatui release.
+//!
+//! [`latest`]: https://github.com/ratatui/ratatui/tree/latest
+//! [`BarChart`]: https://docs.rs/ratatui/latest/ratatui/widgets/struct.BarChart.html
+
+use std::fmt;
+
+use color_eyre::Result;
+use crossterm::event::{self, Event, KeyCode, KeyEventKind};
+use ratatui::{
+    layout::{Constraint, Layout, Margin, Rect},
+    style::{Color, Modifier, Style, Stylize},
+    text::{Line, Text},
+    widgets::calendar::{CalendarEventStore, Monthly},
+    DefaultTerminal, Frame,
+};
+use time::{ext::NumericalDuration, Date, Month, OffsetDateTime};
+
+fn main() -> Result<()> {
+    color_eyre::install()?;
+    let terminal = ratatui::init();
+    let result = run(terminal);
+    ratatui::restore();
+    result
+}
+
+/// Run the application.
+fn run(mut terminal: DefaultTerminal) -> Result<()> {
+    let mut selected_date = OffsetDateTime::now_local()?.date();
+    let mut calendar_style = StyledCalendar::Default;
+    loop {
+        terminal.draw(|frame| render(frame, calendar_style, selected_date))?;
+        if let Event::Key(key) = event::read()? {
+            if key.kind == KeyEventKind::Press {
+                match key.code {
+                    KeyCode::Char('q') => break Ok(()),
+                    KeyCode::Char('s') => calendar_style = calendar_style.next(),
+                    KeyCode::Char('n') | KeyCode::Tab => selected_date = next_month(selected_date),
+                    KeyCode::Char('p') | KeyCode::BackTab => {
+                        selected_date = previous_month(selected_date);
+                    }
+                    KeyCode::Char('h') | KeyCode::Left => selected_date -= 1.days(),
+                    KeyCode::Char('j') | KeyCode::Down => selected_date += 1.weeks(),
+                    KeyCode::Char('k') | KeyCode::Up => selected_date -= 1.weeks(),
+                    KeyCode::Char('l') | KeyCode::Right => selected_date += 1.days(),
+                    _ => {}
+                }
+            }
+        }
+    }
+}
+
+fn next_month(date: Date) -> Date {
+    if date.month() == Month::December {
+        date.replace_month(Month::January)
+            .unwrap()
+            .replace_year(date.year() + 1)
+            .unwrap()
+    } else {
+        date.replace_month(date.month().next()).unwrap()
+    }
+}
+
+fn previous_month(date: Date) -> Date {
+    if date.month() == Month::January {
+        date.replace_month(Month::December)
+            .unwrap()
+            .replace_year(date.year() - 1)
+            .unwrap()
+    } else {
+        date.replace_month(date.month().previous()).unwrap()
+    }
+}
+
+/// Draw the UI with a calendar.
+fn render(frame: &mut Frame, calendar_style: StyledCalendar, selected_date: Date) {
+    let header = Text::from_iter([
+        Line::from("Calendar Example".bold()),
+        Line::from(
+            "<q> Quit | <s> Change Style | <n> Next Month | <p> Previous Month, <hjkl> Move",
+        ),
+        Line::from(format!(
+            "Current date: {selected_date} | Current style: {calendar_style}"
+        )),
+    ]);
+
+    let vertical = Layout::vertical([
+        Constraint::Length(header.height() as u16),
+        Constraint::Fill(1),
+    ]);
+    let [text_area, area] = vertical.areas(frame.area());
+    frame.render_widget(header.centered(), text_area);
+    calendar_style
+        .render_year(frame, area, selected_date)
+        .unwrap();
+}
+
+#[derive(Debug, Clone, Copy)]
+enum StyledCalendar {
+    Default,
+    Surrounding,
+    WeekdaysHeader,
+    SurroundingAndWeekdaysHeader,
+    MonthHeader,
+    MonthAndWeekdaysHeader,
+}
+
+impl StyledCalendar {
+    // Cycle through the different styles.
+    const fn next(self) -> Self {
+        match self {
+            Self::Default => Self::Surrounding,
+            Self::Surrounding => Self::WeekdaysHeader,
+            Self::WeekdaysHeader => Self::SurroundingAndWeekdaysHeader,
+            Self::SurroundingAndWeekdaysHeader => Self::MonthHeader,
+            Self::MonthHeader => Self::MonthAndWeekdaysHeader,
+            Self::MonthAndWeekdaysHeader => Self::Default,
+        }
+    }
+}
+
+impl fmt::Display for StyledCalendar {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::Default => write!(f, "Default"),
+            Self::Surrounding => write!(f, "Show Surrounding"),
+            Self::WeekdaysHeader => write!(f, "Show Weekdays Header"),
+            Self::SurroundingAndWeekdaysHeader => write!(f, "Show Surrounding and Weekdays Header"),
+            Self::MonthHeader => write!(f, "Show Month Header"),
+            Self::MonthAndWeekdaysHeader => write!(f, "Show Month Header and Weekdays Header"),
+        }
+    }
+}
+
+impl StyledCalendar {
+    fn render_year(self, frame: &mut Frame, area: Rect, date: Date) -> Result<()> {
+        let events = events(date)?;
+
+        let area = area.inner(Margin {
+            vertical: 1,
+            horizontal: 1,
+        });
+        let rows = Layout::vertical([Constraint::Ratio(1, 3); 3]).split(area);
+        let areas = rows.iter().flat_map(|row| {
+            Layout::horizontal([Constraint::Ratio(1, 4); 4])
+                .split(*row)
+                .to_vec()
+        });
+        for (i, area) in areas.enumerate() {
+            let month = date
+                .replace_day(1)
+                .unwrap()
+                .replace_month(Month::try_from(i as u8 + 1).unwrap())
+                .unwrap();
+            self.render_month(frame, area, month, &events);
+        }
+        Ok(())
+    }
+
+    fn render_month(self, frame: &mut Frame, area: Rect, date: Date, events: &CalendarEventStore) {
+        let calendar = match self {
+            Self::Default => Monthly::new(date, events)
+                .default_style(Style::new().bold().bg(Color::Rgb(50, 50, 50)))
+                .show_month_header(Style::default()),
+            Self::Surrounding => Monthly::new(date, events)
+                .default_style(Style::new().bold().bg(Color::Rgb(50, 50, 50)))
+                .show_month_header(Style::default())
+                .show_surrounding(Style::new().dim()),
+            Self::WeekdaysHeader => Monthly::new(date, events)
+                .default_style(Style::new().bold().bg(Color::Rgb(50, 50, 50)))
+                .show_month_header(Style::default())
+                .show_weekdays_header(Style::new().bold().green()),
+            Self::SurroundingAndWeekdaysHeader => Monthly::new(date, events)
+                .default_style(Style::new().bold().bg(Color::Rgb(50, 50, 50)))
+                .show_month_header(Style::default())
+                .show_surrounding(Style::new().dim())
+                .show_weekdays_header(Style::new().bold().green()),
+            Self::MonthHeader => Monthly::new(date, events)
+                .default_style(Style::new().bold().bg(Color::Rgb(50, 50, 50)))
+                .show_month_header(Style::default())
+                .show_month_header(Style::new().bold().green()),
+            Self::MonthAndWeekdaysHeader => Monthly::new(date, events)
+                .default_style(Style::new().bold().bg(Color::Rgb(50, 50, 50)))
+                .show_month_header(Style::default())
+                .show_weekdays_header(Style::new().bold().dim().light_yellow()),
+        };
+        frame.render_widget(calendar, area);
+    }
+}
+
+/// Makes a list of dates for the current year.
+fn events(selected_date: Date) -> Result<CalendarEventStore> {
+    const SELECTED: Style = Style::new()
+        .fg(Color::White)
+        .bg(Color::Red)
+        .add_modifier(Modifier::BOLD);
+    const HOLIDAY: Style = Style::new()
+        .fg(Color::Red)
+        .add_modifier(Modifier::UNDERLINED);
+    const SEASON: Style = Style::new()
+        .fg(Color::Green)
+        .bg(Color::Black)
+        .add_modifier(Modifier::UNDERLINED);
+
+    let mut list = CalendarEventStore::today(
+        Style::default()
+            .add_modifier(Modifier::BOLD)
+            .bg(Color::Blue),
+    );
+    let y = selected_date.year();
+
+    // new year's
+    list.add(Date::from_calendar_date(y, Month::January, 1)?, HOLIDAY);
+    // next new_year's for December "show surrounding"
+    list.add(Date::from_calendar_date(y + 1, Month::January, 1)?, HOLIDAY);
+    // groundhog day
+    list.add(Date::from_calendar_date(y, Month::February, 2)?, HOLIDAY);
+    // april fool's
+    list.add(Date::from_calendar_date(y, Month::April, 1)?, HOLIDAY);
+    // earth day
+    list.add(Date::from_calendar_date(y, Month::April, 22)?, HOLIDAY);
+    // star wars day
+    list.add(Date::from_calendar_date(y, Month::May, 4)?, HOLIDAY);
+    // festivus
+    list.add(Date::from_calendar_date(y, Month::December, 23)?, HOLIDAY);
+    // new year's eve
+    list.add(Date::from_calendar_date(y, Month::December, 31)?, HOLIDAY);
+
+    // seasons
+    // spring equinox
+    list.add(Date::from_calendar_date(y, Month::March, 22)?, SEASON);
+    // summer solstice
+    list.add(Date::from_calendar_date(y, Month::June, 21)?, SEASON);
+    // fall equinox
+    list.add(Date::from_calendar_date(y, Month::September, 22)?, SEASON);
+    // winter solstice
+    list.add(Date::from_calendar_date(y, Month::December, 21)?, SEASON);
+
+    // selected date
+    list.add(selected_date, SELECTED);
+
+    Ok(list)
+}

examples/apps/canvas/Cargo.toml

@@ -0,0 +1,15 @@
+[package]
+name = "canvas"
+publish = false
+license.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+
+[dependencies]
+color-eyre.workspace = true
+crossterm.workspace = true
+itertools.workspace = true
+ratatui.workspace = true
+
+[lints]
+workspace = true

examples/apps/canvas/README.md

@@ -0,0 +1,9 @@
+# Canvas demo
+
+This example shows how to render various shapes and a map on a canvas.
+
+To run this demo:
+
+```shell
+cargo run -p canvas
+```

examples/apps/canvas/src/main.rs

@@ -0,0 +1,265 @@
+/// A Ratatui example that demonstrates how to draw on a canvas.
+///
+/// This example demonstrates how to draw various shapes such as rectangles, circles, and lines
+/// on a canvas. It also demonstrates how to draw a map.
+///
+/// This example runs with the Ratatui library code in the branch that you are currently
+/// reading. See the [`latest`] branch for the code which works with the most recent Ratatui
+/// release.
+///
+/// [`latest`]: https://github.com/ratatui/ratatui/tree/latest
+use std::{
+    io::stdout,
+    time::{Duration, Instant},
+};
+
+use color_eyre::Result;
+use crossterm::{
+    event::{DisableMouseCapture, EnableMouseCapture, KeyEventKind},
+    ExecutableCommand,
+};
+use itertools::Itertools;
+use ratatui::{
+    crossterm::event::{self, Event, KeyCode, MouseEventKind},
+    layout::{Constraint, Layout, Position, Rect},
+    style::{Color, Stylize},
+    symbols::Marker,
+    text::Text,
+    widgets::{
+        canvas::{Canvas, Circle, Map, MapResolution, Points, Rectangle},
+        Block, Widget,
+    },
+    DefaultTerminal, Frame,
+};
+
+fn main() -> Result<()> {
+    color_eyre::install()?;
+    stdout().execute(EnableMouseCapture)?;
+    let terminal = ratatui::init();
+    let app_result = App::new().run(terminal);
+    ratatui::restore();
+    stdout().execute(DisableMouseCapture)?;
+    app_result
+}
+
+struct App {
+    exit: bool,
+    x: f64,
+    y: f64,
+    ball: Circle,
+    playground: Rect,
+    vx: f64,
+    vy: f64,
+    marker: Marker,
+    points: Vec<Position>,
+    is_drawing: bool,
+}
+
+impl App {
+    const fn new() -> Self {
+        Self {
+            exit: false,
+            x: 0.0,
+            y: 0.0,
+            ball: Circle {
+                x: 20.0,
+                y: 40.0,
+                radius: 10.0,
+                color: Color::Yellow,
+            },
+            playground: Rect::new(10, 10, 200, 100),
+            vx: 1.0,
+            vy: 1.0,
+            marker: Marker::Dot,
+            points: vec![],
+            is_drawing: false,
+        }
+    }
+
+    pub fn run(mut self, mut terminal: DefaultTerminal) -> Result<()> {
+        let tick_rate = Duration::from_millis(16);
+        let mut last_tick = Instant::now();
+        while !self.exit {
+            terminal.draw(|frame| self.draw(frame))?;
+            let timeout = tick_rate.saturating_sub(last_tick.elapsed());
+            if event::poll(timeout)? {
+                match event::read()? {
+                    Event::Key(key) => self.handle_key_press(key),
+                    Event::Mouse(event) => self.handle_mouse_event(event),
+                    _ => (),
+                }
+            }
+
+            if last_tick.elapsed() >= tick_rate {
+                self.on_tick();
+                last_tick = Instant::now();
+            }
+        }
+        Ok(())
+    }
+
+    fn handle_key_press(&mut self, key: event::KeyEvent) {
+        if key.kind != KeyEventKind::Press {
+            return;
+        }
+        match key.code {
+            KeyCode::Char('q') => self.exit = true,
+            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,
+            KeyCode::Enter => {
+                self.marker = match self.marker {
+                    Marker::Dot => Marker::Braille,
+                    Marker::Braille => Marker::Block,
+                    Marker::Block => Marker::HalfBlock,
+                    Marker::HalfBlock => Marker::Bar,
+                    Marker::Bar => Marker::Dot,
+                };
+            }
+            _ => {}
+        }
+    }
+
+    fn handle_mouse_event(&mut self, event: event::MouseEvent) {
+        match event.kind {
+            MouseEventKind::Down(_) => self.is_drawing = true,
+            MouseEventKind::Up(_) => self.is_drawing = false,
+            MouseEventKind::Drag(_) => {
+                self.points.push(Position::new(event.column, event.row));
+            }
+            _ => {}
+        }
+    }
+
+    fn on_tick(&mut self) {
+        // bounce the ball by flipping the velocity vector
+        let ball = &self.ball;
+        let playground = self.playground;
+        if ball.x - ball.radius < f64::from(playground.left())
+            || ball.x + ball.radius > f64::from(playground.right())
+        {
+            self.vx = -self.vx;
+        }
+        if ball.y - ball.radius < f64::from(playground.top())
+            || ball.y + ball.radius > f64::from(playground.bottom())
+        {
+            self.vy = -self.vy;
+        }
+        self.ball.x += self.vx;
+        self.ball.y += self.vy;
+    }
+
+    fn draw(&self, frame: &mut Frame) {
+        let header = Text::from_iter([
+            "Canvas Example".bold(),
+            "<q> Quit | <enter> Change Marker | <hjkl> Move".into(),
+        ]);
+
+        let vertical = Layout::vertical([
+            Constraint::Length(header.height() as u16),
+            Constraint::Percentage(50),
+            Constraint::Percentage(50),
+        ]);
+        let [text_area, up, down] = vertical.areas(frame.area());
+        frame.render_widget(header.centered(), text_area);
+
+        let horizontal =
+            Layout::horizontal([Constraint::Percentage(50), Constraint::Percentage(50)]);
+        let [draw, pong] = horizontal.areas(up);
+        let [map, boxes] = horizontal.areas(down);
+
+        frame.render_widget(self.map_canvas(), map);
+        frame.render_widget(self.draw_canvas(draw), draw);
+        frame.render_widget(self.pong_canvas(), pong);
+        frame.render_widget(self.boxes_canvas(boxes), boxes);
+    }
+
+    fn map_canvas(&self) -> impl Widget + '_ {
+        Canvas::default()
+            .block(Block::bordered().title("World"))
+            .marker(self.marker)
+            .paint(|ctx| {
+                ctx.draw(&Map {
+                    color: Color::Green,
+                    resolution: MapResolution::High,
+                });
+                ctx.print(self.x, -self.y, "You are here".yellow());
+            })
+            .x_bounds([-180.0, 180.0])
+            .y_bounds([-90.0, 90.0])
+    }
+
+    fn draw_canvas(&self, area: Rect) -> impl Widget + '_ {
+        Canvas::default()
+            .block(Block::bordered().title("Draw here"))
+            .marker(self.marker)
+            .x_bounds([0.0, f64::from(area.width)])
+            .y_bounds([0.0, f64::from(area.height)])
+            .paint(move |ctx| {
+                let points = self
+                    .points
+                    .iter()
+                    .map(|p| {
+                        (
+                            f64::from(p.x) - f64::from(area.left()),
+                            f64::from(area.bottom()) - f64::from(p.y),
+                        )
+                    })
+                    .collect_vec();
+                ctx.draw(&Points {
+                    coords: &points,
+                    color: Color::White,
+                });
+            })
+    }
+
+    fn pong_canvas(&self) -> impl Widget + '_ {
+        Canvas::default()
+            .block(Block::bordered().title("Pong"))
+            .marker(self.marker)
+            .paint(|ctx| {
+                ctx.draw(&self.ball);
+            })
+            .x_bounds([10.0, 210.0])
+            .y_bounds([10.0, 110.0])
+    }
+
+    fn boxes_canvas(&self, area: Rect) -> impl Widget {
+        let left = 0.0;
+        let right = f64::from(area.width);
+        let bottom = 0.0;
+        let top = f64::from(area.height).mul_add(2.0, -4.0);
+        Canvas::default()
+            .block(Block::bordered().title("Rects"))
+            .marker(self.marker)
+            .x_bounds([left, right])
+            .y_bounds([bottom, top])
+            .paint(|ctx| {
+                for i in 0..=11 {
+                    ctx.draw(&Rectangle {
+                        x: f64::from(i * i + 3 * i) / 2.0 + 2.0,
+                        y: 2.0,
+                        width: f64::from(i),
+                        height: f64::from(i),
+                        color: Color::Red,
+                    });
+                    ctx.draw(&Rectangle {
+                        x: f64::from(i * i + 3 * i) / 2.0 + 2.0,
+                        y: 21.0,
+                        width: f64::from(i),
+                        height: f64::from(i),
+                        color: Color::Blue,
+                    });
+                }
+                for i in 0..100 {
+                    if i % 10 != 0 {
+                        ctx.print(f64::from(i) + 1.0, 0.0, format!("{i}", i = i % 10));
+                    }
+                    if i % 2 == 0 && i % 10 != 0 {
+                        ctx.print(0.0, f64::from(i), format!("{i}", i = i % 10));
+                    }
+                }
+            })
+    }
+}

examples/apps/chart/Cargo.toml

@@ -0,0 +1,14 @@
+[package]
+name = "chart"
+publish = false
+license.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+
+[dependencies]
+color-eyre.workspace = true
+crossterm.workspace = true
+ratatui.workspace = true
+
+[lints]
+workspace = true

examples/apps/chart/README.md

@@ -0,0 +1,9 @@
+# Chart demo
+
+This example shows how to render line, bar, and scatter charts.
+
+To run this demo:
+
+```shell
+cargo run -p chart
+```

examples/apps/chart/src/main.rs

@@ -1,39 +1,42 @@
-//! # [Ratatui] Chart example
-//!
-//! The latest version of this example is available in the [examples] folder in the repository.
-//!
-//! Please note that the examples are designed to be run against the `main` branch of the Github
-//! repository. This means that you may not be able to compile with the latest release version on
-//! crates.io, or the one that you have installed locally.
-//!
-//! See the [examples readme] for more information on finding examples that match the version of the
-//! library you are using.
-//!
-//! [Ratatui]: https://github.com/ratatui-org/ratatui
-//! [examples]: https://github.com/ratatui-org/ratatui/blob/main/examples
-//! [examples readme]: https://github.com/ratatui-org/ratatui/blob/main/examples/README.md
-
-use std::{
-    error::Error,
-    io,
-    time::{Duration, Instant},
-};
+/// A Ratatui example that demonstrates how to handle charts.
+///
+/// This example demonstrates how to draw various types of charts such as line, bar, and
+/// scatter charts.
+///
+/// This example runs with the Ratatui library code in the branch that you are currently
+/// reading. See the [`latest`] branch for the code which works with the most recent Ratatui
+/// release.
+///
+/// [`latest`]: https://github.com/ratatui/ratatui/tree/latest
+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},
-    },
-    layout::{Alignment, Constraint, Layout, Rect},
+    crossterm::event::{self, Event, KeyCode},
+    layout::{Constraint, Layout, Rect},
     style::{Color, Modifier, Style, Stylize},
     symbols::{self, Marker},
-    text::Span,
-    widgets::{block::Title, Axis, Block, Chart, Dataset, GraphType, LegendPosition},
-    Frame, Terminal,
+    text::{Line, Span},
+    widgets::{Axis, Block, Chart, Dataset, GraphType, LegendPosition},
+    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 +65,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 +80,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 +111,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)
@@ -228,13 +191,7 @@ fn render_barchart(frame: &mut Frame, bar_chart: Rect) {
         ]);
 
     let chart = Chart::new(vec![dataset])
-        .block(
-            Block::bordered().title(
-                Title::default()
-                    .content("Bar chart".cyan().bold())
-                    .alignment(Alignment::Center),
-            ),
-        )
+        .block(Block::bordered().title_top(Line::from("Bar chart").cyan().bold().centered()))
         .x_axis(
             Axis::default()
                 .style(Style::default().gray())
@@ -252,7 +209,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)
@@ -261,13 +218,7 @@ fn render_line_chart(f: &mut Frame, area: Rect) {
         .data(&[(1., 1.), (4., 4.)])];
 
     let chart = Chart::new(datasets)
-        .block(
-            Block::bordered().title(
-                Title::default()
-                    .content("Line chart".cyan().bold())
-                    .alignment(Alignment::Center),
-            ),
-        )
+        .block(Block::bordered().title(Line::from("Line chart").cyan().bold().centered()))
         .x_axis(
             Axis::default()
                 .title("X Axis")
@@ -285,10 +236,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")
@@ -311,13 +262,7 @@ fn render_scatter(f: &mut Frame, area: Rect) {
     ];
 
     let chart = Chart::new(datasets)
-        .block(
-            Block::bordered().title(
-                Title::default()
-                    .content("Scatter chart".cyan().bold())
-                    .alignment(Alignment::Center),
-            ),
-        )
+        .block(Block::bordered().title(Line::from("Scatter chart").cyan().bold().centered()))
         .x_axis(
             Axis::default()
                 .title("Year")
@@ -334,7 +279,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/apps/color-explorer/Cargo.toml

@@ -0,0 +1,15 @@
+[package]
+name = "color-explorer"
+publish = false
+license.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+
+[dependencies]
+color-eyre.workspace = true
+crossterm.workspace = true
+itertools.workspace = true
+ratatui.workspace = true
+
+[lints]
+workspace = true

examples/apps/color-explorer/README.md

@@ -0,0 +1,9 @@
+# Color explorer demo
+
+This example shows how to handle the supported colors.
+
+To run this demo:
+
+```shell
+cargo run -p color-explorer
+```

examples/apps/color-explorer/src/main.rs

@@ -1,70 +1,44 @@
-//! # [Ratatui] Colors example
+//! A Ratatui example that demonstrates how to handle colors.
 //!
-//! The latest version of this example is available in the [examples] folder in the repository.
+//! This example shows all the colors supported by Ratatui. It will render a grid of foreground
+//! and background colors with their names and indexes.
 //!
-//! 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.
+//! This example runs with the Ratatui library code in the branch that you are currently reading.
+//! See the [`latest`] branch for the code which works with the most recent Ratatui release.
 //!
-//! See the [examples readme] for more information on finding examples that match the version of the
-//! library you are using.
-//!
-//! [Ratatui]: https://github.com/ratatui-org/ratatui
-//! [examples]: https://github.com/ratatui-org/ratatui/blob/main/examples
-//! [examples readme]: https://github.com/ratatui-org/ratatui/blob/main/examples/README.md
-
-// This example shows all the colors supported by ratatui. It will render a grid of foreground
-// and background colors with their names and indexes.
-
-use std::{
-    error::Error,
-    io::{self, Stdout},
-    result,
-    time::Duration,
-};
+//! [`latest`]: https://github.com/ratatui/ratatui/tree/latest
 
+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 +91,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 +109,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 +239,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/apps/demo/Cargo.toml

@@ -0,0 +1,17 @@
+[package]
+name = "demo"
+publish = false
+license.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+
+[features]
+default = ["crossterm"]
+crossterm = ["ratatui/crossterm"]
+termion = ["ratatui/termion"]
+termwiz = ["ratatui/termwiz"]
+
+[dependencies]
+clap = { version = "4.5.23", features = ["derive"] }
+rand = "0.8.5"
+ratatui.workspace = true

examples/apps/demo/README.md

@@ -0,0 +1,25 @@
+# Demo example
+
+This is the original demo that was developed for Tui-rs (the library that Ratatui was forked from).
+
+![demo.gif](https://github.com/ratatui/ratatui/blob/images/examples/demo.gif?raw=true)
+
+This example is available for each backend. To run it:
+
+## crossterm
+
+```shell
+cargo run -p demo
+```
+
+## termion
+
+```shell
+cargo run -p demo --no-default-features --features termion
+```
+
+## termwiz
+
+```shell
+cargo run -p demo --no-default-features --features termwiz
+```

examples/apps/demo/src/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/apps/demo/src/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/apps/demo/src/main.rs

@@ -9,18 +9,18 @@
 //! 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};
 
-use argh::FromArgs;
+use clap::Parser;
 
 mod app;
 #[cfg(feature = "crossterm")]
 mod crossterm;
-#[cfg(feature = "termion")]
+#[cfg(all(not(windows), feature = "termion"))]
 mod termion;
 #[cfg(feature = "termwiz")]
 mod termwiz;
@@ -28,24 +28,29 @@ mod termwiz;
 mod ui;
 
 /// Demo
-#[derive(Debug, FromArgs)]
+#[derive(Debug, Parser)]
 struct Cli {
     /// time in ms between two ticks.
-    #[argh(option, default = "250")]
+    #[arg(short, long, default_value_t = 250)]
     tick_rate: u64,
+
     /// whether unicode symbols are used to improve the overall look of the app
-    #[argh(option, default = "true")]
-    enhanced_graphics: bool,
+    #[arg(short, long, default_value_t = true)]
+    unicode: bool,
 }
 
 fn main() -> Result<(), Box<dyn Error>> {
-    let cli: Cli = argh::from_env();
+    let cli = Cli::parse();
     let tick_rate = Duration::from_millis(cli.tick_rate);
     #[cfg(feature = "crossterm")]
-    crate::crossterm::run(tick_rate, cli.enhanced_graphics)?;
-    #[cfg(feature = "termion")]
-    crate::termion::run(tick_rate, cli.enhanced_graphics)?;
-    #[cfg(feature = "termwiz")]
-    crate::termwiz::run(tick_rate, cli.enhanced_graphics)?;
+    crate::crossterm::run(tick_rate, cli.unicode)?;
+    #[cfg(all(not(windows), feature = "termion", not(feature = "crossterm")))]
+    crate::termion::run(tick_rate, cli.unicode)?;
+    #[cfg(all(
+        feature = "termwiz",
+        not(feature = "crossterm"),
+        not(feature = "termion")
+    ))]
+    crate::termwiz::run(tick_rate, cli.unicode)?;
     Ok(())
 }

examples/apps/demo/src/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/apps/demo/src/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/apps/demo/src/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/apps/demo2/Cargo.toml

@@ -0,0 +1,19 @@
+[package]
+name = "demo2"
+publish = false
+license.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+
+[dependencies]
+color-eyre = "0.6.3"
+crossterm.workspace = true
+indoc.workspace = true
+itertools.workspace = true
+palette = "0.7.6"
+rand = "0.8.5"
+rand_chacha = "0.3.1"
+ratatui = { workspace = true, features = ["all-widgets"] }
+strum.workspace = true
+time = "0.3.37"
+unicode-width = "0.2.0"

examples/apps/demo2/README.md

@@ -0,0 +1,9 @@
+## Demo2
+
+This is the demo example from the main README and crate page. Source: [demo2](./demo2/).
+
+```shell
+cargo run -p demo2
+```
+
+![Demo2](https://github.com/ratatui/ratatui/blob/images/examples/demo2.gif?raw=true)

examples/apps/demo2/src/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/apps/demo2/src/main.rs

@@ -0,0 +1,54 @@
+//! # [Ratatui] Demo2 example
+//!
+//! The latest version of this example is available in the [examples] folder in the repository.
+//!
+//! Please note that the examples are designed to be run against the `main` branch of the Github
+//! repository. This means that you may not be able to compile with the latest release version on
+//! crates.io, or the one that you have installed locally.
+//!
+//! See the [examples readme] for more information on finding examples that match the version of the
+//! library you are using.
+//!
+//! [Ratatui]: https://github.com/ratatui/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,
+    clippy::module_name_repetitions,
+    clippy::must_use_candidate
+)]
+
+mod app;
+mod colors;
+mod destroy;
+mod tabs;
+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},
+    theme::THEME,
+};
+
+fn main() -> Result<()> {
+    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/apps/demo2/src/tabs/about.rs

@@ -0,0 +1,75 @@
+use ratatui::{
+    buffer::Buffer,
+    layout::{Alignment, Constraint, Layout, Margin, Rect},
+    widgets::{
+        Block, Borders, Clear, MascotEyeColor, Padding, Paragraph, RatatuiMascot, Widget, Wrap,
+    },
+};
+
+use crate::{RgbSwatch, THEME};
+
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
+pub struct AboutTab {
+    row_index: usize,
+}
+
+impl AboutTab {
+    pub fn prev_row(&mut self) {
+        self.row_index = self.row_index.saturating_sub(1);
+    }
+
+    pub fn next_row(&mut self) {
+        self.row_index = self.row_index.saturating_add(1);
+    }
+}
+
+impl Widget for AboutTab {
+    fn render(self, area: Rect, buf: &mut Buffer) {
+        RgbSwatch.render(area, buf);
+        let horizontal = Layout::horizontal([Constraint::Length(34), Constraint::Min(0)]);
+        let [logo_area, description] = horizontal.areas(area);
+        render_crate_description(description, buf);
+        let eye_state = if self.row_index % 2 == 0 {
+            MascotEyeColor::Default
+        } else {
+            MascotEyeColor::Red
+        };
+        RatatuiMascot::default().set_eye(eye_state).render(
+            logo_area.inner(Margin {
+                vertical: 0,
+                horizontal: 2,
+            }),
+            buf,
+        );
+    }
+}
+
+fn render_crate_description(area: Rect, buf: &mut Buffer) {
+    let area = area.inner(Margin {
+        vertical: 4,
+        horizontal: 2,
+    });
+    Clear.render(area, buf); // clear out the color swatches
+    Block::new().style(THEME.content).render(area, buf);
+    let area = area.inner(Margin {
+        vertical: 1,
+        horizontal: 2,
+    });
+    let text = "- cooking up terminal user interfaces -
+
+    Ratatui is a Rust crate that provides widgets (e.g. Paragraph, Table) and draws them to the \
+    screen efficiently every frame.";
+    Paragraph::new(text)
+        .style(THEME.description)
+        .block(
+            Block::new()
+                .title(" Ratatui ")
+                .title_alignment(Alignment::Center)
+                .borders(Borders::TOP)
+                .border_style(THEME.description_title)
+                .padding(Padding::new(0, 0, 0, 0)),
+        )
+        .wrap(Wrap { trim: true })
+        .scroll((0, 0))
+        .render(area, buf);
+}

examples/apps/demo2/src/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/apps/demo2/src/tabs/recipe.rs

@@ -25,7 +25,7 @@ impl Ingredient {
     }
 }
 
-impl<'a> From<Ingredient> for Row<'a> {
+impl From<Ingredient> for Row<'_> {
     fn from(i: Ingredient) -> Self {
         Row::new(vec![i.quantity, i.name]).height(i.height())
     }
@@ -164,7 +164,7 @@ fn render_ingredients(selected_row: usize, area: Rect, buf: &mut Buffer) {
         Table::new(rows, [Constraint::Length(7), Constraint::Length(30)])
             .block(Block::new().style(theme.ingredients))
             .header(Row::new(vec!["Qty", "Ingredient"]).style(theme.ingredients_header))
-            .highlight_style(Style::new().light_yellow()),
+            .row_highlight_style(Style::new().light_yellow()),
         area,
         buf,
         &mut state,

examples/apps/demo2/src/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)
@@ -63,7 +60,7 @@ fn render_hops(selected_row: usize, area: Rect, buf: &mut Buffer) {
     StatefulWidget::render(
         Table::new(rows, [Constraint::Max(100), Constraint::Length(15)])
             .header(Row::new(vec!["Host", "Address"]).set_style(THEME.traceroute.header))
-            .highlight_style(THEME.traceroute.selected)
+            .row_highlight_style(THEME.traceroute.selected)
             .block(block),
         area,
         buf,
@@ -102,7 +99,7 @@ pub fn render_ping(progress: usize, area: Rect, buf: &mut Buffer) {
                 .title_alignment(Alignment::Center)
                 .border_type(BorderType::Thick),
         )
-        .data(&data)
+        .data(data)
         .style(THEME.traceroute.ping)
         .render(area, buf);
 }

examples/apps/demo2/src/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 {
@@ -101,7 +101,7 @@ fn render_simple_barchart(area: Rect, buf: &mut Buffer) {
                 } else {
                     Style::new().fg(Color::DarkGray).bg(Color::Yellow).bold()
                 })
-                .label(label.into())
+                .label(label)
         })
         .collect_vec();
     let group = BarGroup::default().bars(&data);
@@ -115,15 +115,15 @@ fn render_simple_barchart(area: Rect, buf: &mut Buffer) {
 fn render_horizontal_barchart(area: Rect, buf: &mut Buffer) {
     let bg = Color::Rgb(32, 48, 96);
     let data = [
-        Bar::default().text_value("Winter 37-51".into()).value(51),
-        Bar::default().text_value("Spring 40-65".into()).value(65),
-        Bar::default().text_value("Summer 54-77".into()).value(77),
+        Bar::default().text_value("Winter 37-51").value(51),
+        Bar::default().text_value("Spring 40-65").value(65),
+        Bar::default().text_value("Summer 54-77").value(77),
         Bar::default()
-            .text_value("Fall 41-71".into())
+            .text_value("Fall 41-71")
             .value(71)
             .value_style(Style::new().bold()), // current season
     ];
-    let group = BarGroup::default().label("GPU".into()).bars(&data);
+    let group = BarGroup::default().label("GPU").bars(&data);
     BarChart::default()
         .block(Block::new().padding(Padding::new(0, 0, 2, 0)))
         .direction(Direction::Horizontal)

examples/apps/demo2/src/theme.rs

@@ -22,10 +22,8 @@ pub struct KeyBinding {
 }
 
 pub struct Logo {
-    pub rat: Color,
     pub rat_eye: Color,
     pub rat_eye_alt: Color,
-    pub term: Color,
 }
 
 pub struct Email {
@@ -77,10 +75,8 @@ pub const THEME: Theme = Theme {
     description: Style::new().fg(LIGHT_GRAY).bg(DARK_BLUE),
     description_title: Style::new().fg(LIGHT_GRAY).add_modifier(Modifier::BOLD),
     logo: Logo {
-        rat: WHITE,
         rat_eye: BLACK,
         rat_eye_alt: RED,
-        term: BLACK,
     },
     key_binding: KeyBinding {
         key: Style::new().fg(BLACK).bg(DARK_GRAY),

examples/apps/input-form/Cargo.toml

@@ -0,0 +1,16 @@
+[package]
+name = "input-form"
+publish = false
+license.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+
+[dependencies]
+color-eyre.workspace = true
+crossterm.workspace = true
+ratatui.workspace = true
+serde.workspace = true
+serde_json.workspace = true
+
+[lints]
+workspace = true

examples/apps/input-form/README.md

@@ -0,0 +1,27 @@
+# Input Form example
+
+This example demonstrates how to handle input across several form fields (2 strings and an number).
+It uses an enum to track the focused field, and sends keyboard events to one which is current.
+
+Run this example with:
+
+```shell
+cargo run -p input-form
+```
+
+This example does not handle things like cursor movement within the line (just keys and backspace).
+Most apps would benefit from using the following crates for text input rather than directly using
+strings:
+
+- [`tui-input`](https://crates.io/crates/tui-input)
+- [`tui-prompts`](https://crates.io/crates/tui-prompts)
+- [`tui-textarea`](https://crates.io/crates/tui-textarea)
+- [`rat-salsa`](https://crates.io/crates/rat-salsa)
+
+Some more ideas for handling focus can be found in:
+
+- [`focusable`](https://crates.io/crates/focusable) (see also [Ratatui forum
+  post](https://forum.ratatui.rs/t/focusable-crate-manage-focus-state-for-your-widgets/73))
+- [`rat-focus`](https://crates.io/crates/rat-focus)
+- A useful [`Bevy` discssion](https://github.com/bevyengine/bevy/discussions/15374) about focus
+  more generally.

examples/apps/input-form/src/main.rs

@@ -0,0 +1,270 @@
+//! A Ratatui example that demonstrates how to handle input form focus
+//!
+//! This example demonstrates how to handle cursor and input focus between multiple fields in a
+//! form. You can navigate between fields using the Tab key.
+//!
+//! This does not handle cursor movement etc. This is just a simple example. In a real application,
+//! consider using [`tui-input`], or [`tui-prompts`], or [`tui-textarea`].
+//!
+//! This example runs with the Ratatui library code in the branch that you are currently reading.
+//! See the [`latest`] branch for the code which works with the most recent Ratatui release.
+//!
+//! [`latest`]: https://github.com/ratatui/ratatui/tree/latest
+//! [`tui-input`]: https://crates.io/crates/tui-input
+//! [`tui-prompts`]: https://crates.io/crates/tui-prompts
+//! [`tui-textarea`]: https://crates.io/crates/tui-textarea
+
+use color_eyre::Result;
+use crossterm::event::{self, Event, KeyCode, KeyEvent, KeyEventKind};
+use ratatui::{
+    buffer::Buffer,
+    layout::{Constraint, Layout, Offset, Rect},
+    style::Stylize,
+    text::Line,
+    widgets::Widget,
+    DefaultTerminal, Frame,
+};
+use serde::Serialize;
+
+fn main() -> Result<()> {
+    color_eyre::install()?;
+    let terminal = ratatui::init();
+    let result = App::default().run(terminal);
+    ratatui::restore();
+
+    // serialize the form to JSON if the user submitted it, otherwise print "Canceled"
+    match result {
+        Ok(Some(form)) => println!("{}", serde_json::to_string_pretty(&form)?),
+        Ok(None) => println!("Canceled"),
+        Err(err) => eprintln!("{err}"),
+    }
+    Ok(())
+}
+
+#[derive(Default)]
+struct App {
+    state: AppState,
+    form: InputForm,
+}
+
+#[derive(Default, PartialEq, Eq)]
+enum AppState {
+    #[default]
+    Running,
+    Cancelled,
+    Submitted,
+}
+
+impl App {
+    fn run(mut self, mut terminal: DefaultTerminal) -> Result<Option<InputForm>> {
+        while self.state == AppState::Running {
+            terminal.draw(|frame| self.render(frame))?;
+            self.handle_events()?;
+        }
+        match self.state {
+            AppState::Cancelled => Ok(None),
+            AppState::Submitted => Ok(Some(self.form)),
+            AppState::Running => unreachable!(),
+        }
+    }
+
+    fn render(&self, frame: &mut Frame) {
+        self.form.render(frame);
+    }
+
+    fn handle_events(&mut self) -> Result<()> {
+        match event::read()? {
+            Event::Key(event) if event.kind == KeyEventKind::Press => match event.code {
+                KeyCode::Esc => self.state = AppState::Cancelled,
+                KeyCode::Enter => self.state = AppState::Submitted,
+                _ => self.form.on_key_press(event),
+            },
+            _ => {}
+        }
+        Ok(())
+    }
+}
+
+#[derive(Serialize)]
+struct InputForm {
+    #[serde(skip)]
+    focus: Focus,
+    first_name: StringField,
+    last_name: StringField,
+    age: AgeField,
+}
+
+impl Default for InputForm {
+    fn default() -> Self {
+        Self {
+            focus: Focus::FirstName,
+            first_name: StringField::new("First Name"),
+            last_name: StringField::new("Last Name"),
+            age: AgeField::new("Age"),
+        }
+    }
+}
+
+impl InputForm {
+    // Handle focus navigation or pass the event to the focused field.
+    fn on_key_press(&mut self, event: KeyEvent) {
+        match event.code {
+            KeyCode::Tab => self.focus = self.focus.next(),
+            _ => match self.focus {
+                Focus::FirstName => self.first_name.on_key_press(event),
+                Focus::LastName => self.last_name.on_key_press(event),
+                Focus::Age => self.age.on_key_press(event),
+            },
+        }
+    }
+
+    /// Render the form with the current focus.
+    ///
+    /// The cursor is placed at the end of the focused field.
+    fn render(&self, frame: &mut Frame) {
+        let [first_name_area, last_name_area, age_area] =
+            Layout::vertical(Constraint::from_lengths([1, 1, 1])).areas(frame.area());
+
+        frame.render_widget(&self.first_name, first_name_area);
+        frame.render_widget(&self.last_name, last_name_area);
+        frame.render_widget(&self.age, age_area);
+
+        let cursor_position = match self.focus {
+            Focus::FirstName => first_name_area.offset(self.first_name.cursor_offset()),
+            Focus::LastName => last_name_area.offset(self.last_name.cursor_offset()),
+            Focus::Age => age_area.offset(self.age.cursor_offset()),
+        };
+        frame.set_cursor_position(cursor_position);
+    }
+}
+
+#[derive(Default, PartialEq, Eq)]
+enum Focus {
+    #[default]
+    FirstName,
+    LastName,
+    Age,
+}
+
+impl Focus {
+    // Round-robin focus order.
+    const fn next(&self) -> Self {
+        match self {
+            Self::FirstName => Self::LastName,
+            Self::LastName => Self::Age,
+            Self::Age => Self::FirstName,
+        }
+    }
+}
+
+/// A new-type representing a string field with a label.
+#[derive(Debug, Serialize)]
+struct StringField {
+    #[serde(skip)]
+    label: &'static str,
+    value: String,
+}
+
+impl StringField {
+    const fn new(label: &'static str) -> Self {
+        Self {
+            label,
+            value: String::new(),
+        }
+    }
+
+    /// Handle input events for the string input.
+    fn on_key_press(&mut self, event: KeyEvent) {
+        match event.code {
+            KeyCode::Char(c) => self.value.push(c),
+            KeyCode::Backspace => {
+                self.value.pop();
+            }
+            _ => {}
+        }
+    }
+
+    fn cursor_offset(&self) -> Offset {
+        let x = (self.label.len() + self.value.len() + 2) as i32;
+        Offset::new(x, 0)
+    }
+}
+
+impl Widget for &StringField {
+    fn render(self, area: Rect, buf: &mut Buffer) {
+        let constraints = [
+            Constraint::Length(self.label.len() as u16 + 2),
+            Constraint::Fill(1),
+        ];
+        let [label_area, value_area] = Layout::horizontal(constraints).areas(area);
+        let label = Line::from_iter([self.label, ": "]).bold();
+        label.render(label_area, buf);
+        self.value.clone().render(value_area, buf);
+    }
+}
+
+/// A new-type representing a person's age in years (0-130).
+#[derive(Default, Clone, Copy, Serialize)]
+struct AgeField {
+    #[serde(skip)]
+    label: &'static str,
+    value: u8,
+}
+
+impl AgeField {
+    const MAX: u8 = 130;
+
+    const fn new(label: &'static str) -> Self {
+        Self { label, value: 0 }
+    }
+
+    /// Handle input events for the age input.
+    ///
+    /// Digits are accepted as input, with any input which would exceed the maximum age being
+    /// ignored. The up/down arrow keys and 'j'/'k' keys can be used to increment/decrement the
+    /// age.
+    fn on_key_press(&mut self, event: KeyEvent) {
+        match event.code {
+            KeyCode::Char(digit @ '0'..='9') => {
+                let value = self
+                    .value
+                    .saturating_mul(10)
+                    .saturating_add(digit as u8 - b'0');
+                if value <= Self::MAX {
+                    self.value = value;
+                }
+            }
+            KeyCode::Backspace => self.value /= 10,
+            KeyCode::Up | KeyCode::Char('k') => self.increment(),
+            KeyCode::Down | KeyCode::Char('j') => self.decrement(),
+            _ => {}
+        };
+    }
+
+    fn increment(&mut self) {
+        self.value = self.value.saturating_add(1).min(Self::MAX);
+    }
+
+    fn decrement(&mut self) {
+        self.value = self.value.saturating_sub(1);
+    }
+
+    fn cursor_offset(&self) -> Offset {
+        let x = (self.label.len() + self.value.to_string().len() + 2) as i32;
+        Offset::new(x, 0)
+    }
+}
+
+impl Widget for &AgeField {
+    fn render(self, area: Rect, buf: &mut Buffer) {
+        let constraints = [
+            Constraint::Length(self.label.len() as u16 + 2),
+            Constraint::Fill(1),
+        ];
+        let [label_area, value_area] = Layout::horizontal(constraints).areas(area);
+        let label = Line::from_iter([self.label, ": "]).bold();
+        let value = self.value.to_string();
+        label.render(label_area, buf);
+        value.render(value_area, buf);
+    }
+}

examples/apps/mouse-drawing/Cargo.toml

@@ -0,0 +1,17 @@
+[package]
+name = "mouse-drawing"
+publish = false
+license.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+
+[dependencies]
+color-eyre.workspace = true
+crossterm.workspace = true
+## a collection of line drawing algorithms (e.g. Bresenham's line algorithm)
+line_drawing = "1.0.0"
+rand = "0.8.5"
+ratatui.workspace = true
+
+[lints]
+workspace = true

examples/apps/mouse-drawing/README.md

@@ -0,0 +1,9 @@
+# Mouse drawing demo
+
+This example shows how to receive mouse and handle mouse events.
+
+To run this demo:
+
+```shell
+cargo run -p mouse-drawing
+```

examples/apps/mouse-drawing/src/main.rs

@@ -0,0 +1,123 @@
+/// A Ratatui example that demonstrates how to handle mouse events.
+///
+/// This example demonstrates how to handle mouse events in Ratatui. You can draw lines by
+/// clicking and dragging the mouse.
+///
+/// This example runs with the Ratatui library code in the branch that you are currently
+/// reading. See the [`latest`] branch for the code which works with the most recent Ratatui
+/// release.
+///
+/// [`latest`]: https://github.com/ratatui/ratatui/tree/latest
+use color_eyre::Result;
+use crossterm::{
+    event::{
+        self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode, KeyEvent, MouseEvent,
+        MouseEventKind,
+    },
+    execute,
+};
+use ratatui::{
+    layout::{Position, Rect, Size},
+    style::{Color, Stylize},
+    symbols,
+    text::Line,
+    DefaultTerminal, Frame,
+};
+
+fn main() -> Result<()> {
+    color_eyre::install()?;
+    let terminal = ratatui::init();
+    let result = MouseDrawingApp::default().run(terminal);
+    ratatui::restore();
+    result
+}
+
+#[derive(Default)]
+struct MouseDrawingApp {
+    // Whether the app should exit
+    pub should_exit: bool,
+    // The last known mouse position
+    pub mouse_position: Option<Position>,
+    // The points that have been clicked / drawn by dragging the mouse
+    pub points: Vec<(Position, Color)>,
+    // The color to draw with
+    pub current_color: Color,
+}
+
+impl MouseDrawingApp {
+    fn run(mut self, mut terminal: DefaultTerminal) -> Result<()> {
+        execute!(std::io::stdout(), EnableMouseCapture)?;
+        while !self.should_exit {
+            terminal.draw(|frame| self.render(frame))?;
+            self.handle_events()?;
+        }
+        execute!(std::io::stdout(), DisableMouseCapture)?;
+        Ok(())
+    }
+
+    fn handle_events(&mut self) -> Result<()> {
+        match event::read()? {
+            Event::Key(event) => self.on_key_event(event),
+            Event::Mouse(event) => self.on_mouse_event(event),
+            _ => {}
+        }
+        Ok(())
+    }
+
+    /// Quit the app if the user presses 'q' or 'Esc'
+    fn on_key_event(&mut self, event: KeyEvent) {
+        match event.code {
+            KeyCode::Char(' ') => {
+                self.current_color = Color::Rgb(rand::random(), rand::random(), rand::random());
+            }
+            KeyCode::Char('q') | KeyCode::Esc => self.should_exit = true,
+            _ => {}
+        }
+    }
+
+    /// Adds any points which were clicked or dragged to the `points` vector.
+    fn on_mouse_event(&mut self, event: MouseEvent) {
+        let position = Position::new(event.column, event.row);
+        match event.kind {
+            MouseEventKind::Down(_) => self.points.push((position, self.current_color)),
+            MouseEventKind::Drag(_) => self.draw_line(position),
+            _ => {}
+        }
+        self.mouse_position = Some(position);
+    }
+
+    /// Draw a line between the last point and the given position
+    fn draw_line(&mut self, position: Position) {
+        if let Some(start) = self.points.last() {
+            let (x0, y0) = (i32::from(start.0.x), i32::from(start.0.y));
+            let (x1, y1) = (i32::from(position.x), i32::from(position.y));
+            for (x, y) in line_drawing::Bresenham::new((x0, y0), (x1, y1)) {
+                let point = (Position::new(x as u16, y as u16), self.current_color);
+                self.points.push(point);
+            }
+        }
+    }
+
+    fn render(&self, frame: &mut Frame) {
+        // call order is important here as later elements are drawn on top of earlier elements
+        self.render_points(frame);
+        self.render_mouse_cursor(frame);
+        let value = "Mouse Example ('Esc' to quit. Click / drag to draw. 'Space' to change color)";
+        let title = Line::from(value).centered();
+        frame.render_widget(title, frame.area());
+    }
+
+    fn render_points(&self, frame: &mut Frame<'_>) {
+        for (position, color) in &self.points {
+            let area = Rect::from((*position, Size::new(1, 1))).clamp(frame.area());
+            frame.render_widget(symbols::block::FULL.fg(*color), area);
+        }
+    }
+
+    fn render_mouse_cursor(&self, frame: &mut Frame<'_>) {
+        if let Some(position) = self.mouse_position {
+            let area = Rect::from((position, Size::new(1, 1))).clamp(frame.area());
+            frame.render_widget("╳".bg(self.current_color), area);
+        }
+    }
+}

examples/apps/weather/Cargo.toml

@@ -0,0 +1,15 @@
+[package]
+name = "weather"
+publish = false
+license.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+
+[dependencies]
+color-eyre.workspace = true
+crossterm.workspace = true
+rand = "0.8.5"
+ratatui.workspace = true
+
+[lints]
+workspace = true

examples/apps/weather/README.md

@@ -0,0 +1,9 @@
+# Weather demo
+
+This example shows how to render weather data using barchart widget.
+
+To run this demo:
+
+```shell
+cargo run -p weather
+```

examples/apps/weather/src/main.rs

@@ -0,0 +1,98 @@
+//! A Ratatui example that demonstrates how to render weather data using [`BarChart`] widget.
+//!
+//! Generates random temperature data for each hour of the day and renders it as a vertical bar.
+//!
+//! This example runs with the Ratatui library code in the branch that you are currently reading.
+//! See the [`latest`] branch for the code which works with the most recent Ratatui release.
+//!
+//! [`latest`]: https://github.com/ratatui/ratatui/tree/latest
+//! [`BarChart`]: https://docs.rs/ratatui/latest/ratatui/widgets/struct.BarChart.html
+
+use color_eyre::Result;
+use rand::{thread_rng, Rng};
+use ratatui::{
+    crossterm::event::{self, Event, KeyCode, KeyEventKind},
+    layout::{Constraint, Layout},
+    style::{Color, Style, Stylize},
+    text::Line,
+    widgets::{Bar, BarChart, BarGroup},
+    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 {
+    should_exit: bool,
+    temperatures: Vec<u8>,
+}
+
+impl App {
+    fn new() -> Self {
+        let mut rng = thread_rng();
+        let temperatures = (0..24).map(|_| rng.gen_range(50..90)).collect();
+        Self {
+            should_exit: false,
+            temperatures,
+        }
+    }
+
+    fn run(mut self, mut terminal: DefaultTerminal) -> Result<()> {
+        while !self.should_exit {
+            terminal.draw(|frame| self.draw(frame))?;
+            self.handle_events()?;
+        }
+        Ok(())
+    }
+
+    fn handle_events(&mut self) -> Result<()> {
+        if let Event::Key(key) = event::read()? {
+            if key.kind == KeyEventKind::Press && key.code == KeyCode::Char('q') {
+                self.should_exit = true;
+            }
+        }
+        Ok(())
+    }
+
+    fn draw(&self, frame: &mut Frame) {
+        let [title, main] = Layout::vertical([Constraint::Length(1), Constraint::Fill(1)])
+            .spacing(1)
+            .areas(frame.area());
+
+        frame.render_widget("Weather demo".bold().into_centered_line(), title);
+        frame.render_widget(vertical_barchart(&self.temperatures), main);
+    }
+}
+
+/// Create a vertical bar chart from the temperatures data.
+fn vertical_barchart(temperatures: &[u8]) -> BarChart {
+    let bars: Vec<Bar> = temperatures
+        .iter()
+        .enumerate()
+        .map(|(hour, value)| vertical_bar(hour, value))
+        .collect();
+    BarChart::default()
+        .data(BarGroup::default().bars(&bars))
+        .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 yellow to red value based on the value (50-90)
+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)
+}

examples/barchart-grouped.rs

@@ -1,278 +0,0 @@
-//! # [Ratatui] `BarChart` example
-//!
-//! The latest version of this example is available in the [examples] folder in the repository.
-//!
-//! Please note that the examples are designed to be run against the `main` branch of the Github
-//! repository. This means that you may not be able to compile with the latest release version on
-//! crates.io, or the one that you have installed locally.
-//!
-//! See the [examples readme] for more information on finding examples that match the version of the
-//! library you are using.
-//!
-//! [Ratatui]: https://github.com/ratatui-org/ratatui
-//! [examples]: https://github.com/ratatui-org/ratatui/blob/main/examples
-//! [examples readme]: https://github.com/ratatui-org/ratatui/blob/main/examples/README.md
-
-use std::iter::zip;
-
-use color_eyre::Result;
-use ratatui::{
-    crossterm::event::{self, Event, KeyCode},
-    prelude::{Color, Constraint, Direction, Frame, Layout, Line, Style},
-    style::Stylize,
-    widgets::{Bar, BarChart, BarGroup, Block},
-};
-
-use self::terminal::Terminal;
-
-const COMPANY_COUNT: usize = 3;
-const PERIOD_COUNT: usize = 4;
-
-struct App {
-    should_exit: bool,
-    companies: [Company; COMPANY_COUNT],
-    revenues: [Revenues; PERIOD_COUNT],
-}
-
-struct Revenues {
-    period: &'static str,
-    revenues: [u32; COMPANY_COUNT],
-}
-
-struct Company {
-    short_name: &'static str,
-    name: &'static str,
-    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 {
-            should_exit: false,
-            companies: fake_companies(),
-            revenues: fake_revenues(),
-        }
-    }
-
-    fn run(mut self, terminal: &mut Terminal) -> Result<()> {
-        while !self.should_exit {
-            self.draw(terminal)?;
-            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') {
-                self.should_exit = true;
-            }
-        }
-        Ok(())
-    }
-
-    fn render(&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());
-
-        frame.render_widget("Grouped Barchart".bold().into_centered_line(), title);
-        frame.render_widget(self.vertical_revenue_barchart(), top);
-        frame.render_widget(self.horizontal_revenue_barchart(), bottom);
-    }
-
-    /// 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))
-            .bar_gap(0)
-            .bar_width(6)
-            .group_gap(2);
-        for group in self
-            .revenues
-            .iter()
-            .map(|revenue| revenue.to_vertical_bar_group(&self.companies))
-        {
-            barchart = barchart.data(group);
-        }
-        barchart
-    }
-
-    /// Create a horizontal revenue bar chart with the data from the `revenues` field.
-    fn horizontal_revenue_barchart(&self) -> BarChart<'_> {
-        let title = Line::from("Company Revenues (Horizontal)").centered();
-        let mut barchart = BarChart::default()
-            .block(Block::new().title(title))
-            .bar_width(1)
-            .group_gap(2)
-            .bar_gap(0)
-            .direction(Direction::Horizontal);
-        for group in self
-            .revenues
-            .iter()
-            .map(|revenue| revenue.to_horizontal_bar_group(&self.companies))
-        {
-            barchart = barchart.data(group);
-        }
-        barchart
-    }
-}
-
-/// Generate fake company data
-const fn fake_companies() -> [Company; COMPANY_COUNT] {
-    [
-        Company::new("BAKE", "Bake my day", Color::LightRed),
-        Company::new("BITE", "Bits and Bites", Color::Blue),
-        Company::new("TART", "Tart of the Table", Color::White),
-    ]
-}
-
-/// Some fake revenue data
-const fn fake_revenues() -> [Revenues; PERIOD_COUNT] {
-    [
-        Revenues::new("Jan", [8500, 6500, 7000]),
-        Revenues::new("Feb", [9000, 7500, 8500]),
-        Revenues::new("Mar", [9500, 4500, 8200]),
-        Revenues::new("Apr", [6300, 4000, 5000]),
-    ]
-}
-
-impl Revenues {
-    /// Create a new instance of `Revenues`
-    const fn new(period: &'static str, revenues: [u32; COMPANY_COUNT]) -> Self {
-        Self { period, revenues }
-    }
-
-    /// Create a `BarGroup` with vertical bars for each company
-    fn to_vertical_bar_group<'a>(&self, companies: &'a [Company]) -> BarGroup<'a> {
-        let bars: Vec<Bar> = zip(companies, self.revenues)
-            .map(|(company, revenue)| company.vertical_revenue_bar(revenue))
-            .collect();
-        BarGroup::default()
-            .label(Line::from(self.period).centered())
-            .bars(&bars)
-    }
-
-    /// Create a `BarGroup` with horizontal bars for each company
-    fn to_horizontal_bar_group<'a>(&'a self, companies: &'a [Company]) -> BarGroup<'a> {
-        let bars: Vec<Bar> = zip(companies, self.revenues)
-            .map(|(company, revenue)| company.horizontal_revenue_bar(revenue))
-            .collect();
-        BarGroup::default()
-            .label(Line::from(self.period).centered())
-            .bars(&bars)
-    }
-}
-
-impl Company {
-    /// Create a new instance of `Company`
-    const fn new(short_name: &'static str, name: &'static str, color: Color) -> Self {
-        Self {
-            short_name,
-            name,
-            color,
-        }
-    }
-
-    /// Create a vertical revenue bar for the company
-    ///
-    /// The label is the short name of the company, and will be displayed under the bar
-    fn vertical_revenue_bar(&self, revenue: u32) -> Bar {
-        let text_value = format!("{:.1}M", f64::from(revenue) / 1000.);
-        Bar::default()
-            .label(self.short_name.into())
-            .value(u64::from(revenue))
-            .text_value(text_value)
-            .style(self.color)
-            .value_style(Style::new().fg(Color::Black).bg(self.color))
-    }
-
-    /// Create a horizontal revenue bar for the company
-    ///
-    /// The label is the long name of the company combined with the revenue and will be displayed
-    /// on the bar
-    fn horizontal_revenue_bar(&self, revenue: u32) -> Bar {
-        let text_value = format!("{} ({:.1} M)", self.name, f64::from(revenue) / 1000.);
-        Bar::default()
-            .value(u64::from(revenue))
-            .text_value(text_value)
-            .style(self.color)
-            .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

@@ -1,199 +0,0 @@
-//! # [Ratatui] `BarChart` example
-//!
-//! The latest version of this example is available in the [examples] folder in the repository.
-//!
-//! Please note that the examples are designed to be run against the `main` branch of the Github
-//! repository. This means that you may not be able to compile with the latest release version on
-//! crates.io, or the one that you have installed locally.
-//!
-//! See the [examples readme] for more information on finding examples that match the version of the
-//! library you are using.
-//!
-//! [Ratatui]: https://github.com/ratatui-org/ratatui
-//! [examples]: https://github.com/ratatui-org/ratatui/blob/main/examples
-//! [examples readme]: https://github.com/ratatui-org/ratatui/blob/main/examples/README.md
-
-use color_eyre::Result;
-use rand::{thread_rng, Rng};
-use ratatui::{
-    crossterm::event::{self, Event, KeyCode},
-    layout::{Constraint, Direction, Layout},
-    prelude::{Color, Line, Style, Stylize},
-    widgets::{Bar, BarChart, BarGroup, Block},
-};
-
-use self::terminal::Terminal;
-
-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();
-        let temperatures = (0..24).map(|_| rng.gen_range(50..90)).collect();
-        Self {
-            should_exit: false,
-            temperatures,
-        }
-    }
-
-    fn run(mut self, terminal: &mut Terminal) -> Result<()> {
-        while !self.should_exit {
-            self.draw(terminal)?;
-            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') {
-                self.should_exit = true;
-            }
-        }
-        Ok(())
-    }
-
-    fn render(&self, frame: &mut ratatui::Frame) {
-        let [title, vertical, horizontal] = Layout::vertical([
-            Constraint::Length(1),
-            Constraint::Fill(1),
-            Constraint::Fill(1),
-        ])
-        .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);
-    }
-}
-
-/// Create a vertical bar chart from the temperatures data.
-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())
-        })
-        .collect();
-    let title = Line::from("Weather (Vertical)").centered();
-    BarChart::default()
-        .data(BarGroup::default().bars(&bars))
-        .block(Block::new().title(title))
-        .bar_width(5)
-}
-
-/// 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())
-        })
-        .collect();
-    let title = Line::from("Weather (Horizontal)").centered();
-    BarChart::default()
-        .block(Block::new().title(title))
-        .data(BarGroup::default().bars(&bars))
-        .bar_width(1)
-        .bar_gap(0)
-        .direction(Direction::Horizontal)
-}
-
-/// 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;
-    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

@@ -1,258 +0,0 @@
-//! # [Ratatui] Block example
-//!
-//! The latest version of this example is available in the [examples] folder in the repository.
-//!
-//! Please note that the examples are designed to be run against the `main` branch of the Github
-//! repository. This means that you may not be able to compile with the latest release version on
-//! crates.io, or the one that you have installed locally.
-//!
-//! See the [examples readme] for more information on finding examples that match the version of the
-//! library you are using.
-//!
-//! [Ratatui]: https://github.com/ratatui-org/ratatui
-//! [examples]: https://github.com/ratatui-org/ratatui/blob/main/examples
-//! [examples readme]: https://github.com/ratatui-org/ratatui/blob/main/examples/README.md
-
-use std::{
-    error::Error,
-    io::{stdout, Stdout},
-    ops::ControlFlow,
-    time::Duration,
-};
-
-use itertools::Itertools;
-use ratatui::{
-    backend::CrosstermBackend,
-    crossterm::{
-        event::{self, Event, KeyCode},
-        execute,
-        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-    },
-    layout::{Alignment, Constraint, Layout, Rect},
-    style::{Style, Stylize},
-    text::Line,
-    widgets::{
-        block::{Position, Title},
-        Block, BorderType, Borders, Padding, Paragraph, Wrap,
-    },
-    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(())
-}
-
-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<()> {
-    loop {
-        terminal.draw(ui)?;
-        if handle_events()?.is_break() {
-            return Ok(());
-        }
-    }
-}
-
-fn handle_events() -> Result<ControlFlow<()>> {
-    if event::poll(Duration::from_millis(100))? {
-        if let Event::Key(key) = event::read()? {
-            if key.code == KeyCode::Char('q') {
-                return Ok(ControlFlow::Break(()));
-            }
-        }
-    }
-    Ok(ControlFlow::Continue(()))
-}
-
-fn ui(frame: &mut Frame) {
-    let (title_area, layout) = calculate_layout(frame.area());
-
-    render_title(frame, title_area);
-
-    let paragraph = placeholder_paragraph();
-
-    render_borders(&paragraph, Borders::ALL, frame, layout[0][0]);
-    render_borders(&paragraph, Borders::NONE, frame, layout[0][1]);
-    render_borders(&paragraph, Borders::LEFT, frame, layout[1][0]);
-    render_borders(&paragraph, Borders::RIGHT, frame, layout[1][1]);
-    render_borders(&paragraph, Borders::TOP, frame, layout[2][0]);
-    render_borders(&paragraph, Borders::BOTTOM, frame, layout[2][1]);
-
-    render_border_type(&paragraph, BorderType::Plain, frame, layout[3][0]);
-    render_border_type(&paragraph, BorderType::Rounded, frame, layout[3][1]);
-    render_border_type(&paragraph, BorderType::Double, frame, layout[4][0]);
-    render_border_type(&paragraph, BorderType::Thick, frame, layout[4][1]);
-
-    render_styled_block(&paragraph, frame, layout[5][0]);
-    render_styled_borders(&paragraph, frame, layout[5][1]);
-    render_styled_title(&paragraph, frame, layout[6][0]);
-    render_styled_title_content(&paragraph, frame, layout[6][1]);
-    render_multiple_titles(&paragraph, frame, layout[7][0]);
-    render_multiple_title_positions(&paragraph, frame, layout[7][1]);
-    render_padding(&paragraph, frame, layout[8][0]);
-    render_nested_blocks(&paragraph, frame, layout[8][1]);
-}
-
-/// Calculate the layout of the UI elements.
-///
-/// Returns a tuple of the title area and the main areas.
-fn calculate_layout(area: Rect) -> (Rect, Vec<Vec<Rect>>) {
-    let main_layout = Layout::vertical([Constraint::Length(1), Constraint::Min(0)]);
-    let block_layout = Layout::vertical([Constraint::Max(4); 9]);
-    let [title_area, main_area] = main_layout.areas(area);
-    let main_areas = block_layout
-        .split(main_area)
-        .iter()
-        .map(|&area| {
-            Layout::horizontal([Constraint::Percentage(50), Constraint::Percentage(50)])
-                .split(area)
-                .to_vec()
-        })
-        .collect_vec();
-    (title_area, main_areas)
-}
-
-fn render_title(frame: &mut Frame, area: Rect) {
-    frame.render_widget(
-        Paragraph::new("Block example. Press q to quit")
-            .dark_gray()
-            .alignment(Alignment::Center),
-        area,
-    );
-}
-
-fn placeholder_paragraph() -> Paragraph<'static> {
-    let text = "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.";
-    Paragraph::new(text.dark_gray()).wrap(Wrap { trim: true })
-}
-
-fn render_borders(paragraph: &Paragraph, border: Borders, frame: &mut Frame, area: Rect) {
-    let block = Block::new()
-        .borders(border)
-        .title(format!("Borders::{border:#?}"));
-    frame.render_widget(paragraph.clone().block(block), area);
-}
-
-fn render_border_type(
-    paragraph: &Paragraph,
-    border_type: BorderType,
-    frame: &mut Frame,
-    area: Rect,
-) {
-    let block = Block::bordered()
-        .border_type(border_type)
-        .title(format!("BorderType::{border_type:#?}"));
-    frame.render_widget(paragraph.clone().block(block), area);
-}
-fn render_styled_borders(paragraph: &Paragraph, frame: &mut Frame, area: Rect) {
-    let block = Block::bordered()
-        .border_style(Style::new().blue().on_white().bold().italic())
-        .title("Styled borders");
-    frame.render_widget(paragraph.clone().block(block), area);
-}
-
-fn render_styled_block(paragraph: &Paragraph, frame: &mut Frame, area: Rect) {
-    let block = Block::bordered()
-        .style(Style::new().blue().on_white().bold().italic())
-        .title("Styled block");
-    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")
-        .title_style(Style::new().blue().on_white().bold().italic());
-    frame.render_widget(paragraph.clone().block(block), area);
-}
-
-fn render_styled_title_content(paragraph: &Paragraph, frame: &mut Frame, area: Rect) {
-    let title = Line::from(vec![
-        "Styled ".blue().on_white().bold().italic(),
-        "title content".red().on_white().bold().italic(),
-    ]);
-    let block = Block::bordered().title(title);
-    frame.render_widget(paragraph.clone().block(block), area);
-}
-
-fn render_multiple_titles(paragraph: &Paragraph, frame: &mut Frame, area: Rect) {
-    let block = Block::bordered()
-        .title("Multiple".blue().on_white().bold().italic())
-        .title("Titles".red().on_white().bold().italic());
-    frame.render_widget(paragraph.clone().block(block), area);
-}
-
-fn render_multiple_title_positions(paragraph: &Paragraph, frame: &mut Frame, area: Rect) {
-    let block = Block::bordered()
-        .title(
-            Title::from("top left")
-                .position(Position::Top)
-                .alignment(Alignment::Left),
-        )
-        .title(
-            Title::from("top center")
-                .position(Position::Top)
-                .alignment(Alignment::Center),
-        )
-        .title(
-            Title::from("top right")
-                .position(Position::Top)
-                .alignment(Alignment::Right),
-        )
-        .title(
-            Title::from("bottom left")
-                .position(Position::Bottom)
-                .alignment(Alignment::Left),
-        )
-        .title(
-            Title::from("bottom center")
-                .position(Position::Bottom)
-                .alignment(Alignment::Center),
-        )
-        .title(
-            Title::from("bottom right")
-                .position(Position::Bottom)
-                .alignment(Alignment::Right),
-        );
-    frame.render_widget(paragraph.clone().block(block), area);
-}
-
-fn render_padding(paragraph: &Paragraph, frame: &mut Frame, area: Rect) {
-    let block = Block::bordered()
-        .padding(Padding::new(5, 10, 1, 2))
-        .title("Padding");
-    frame.render_widget(paragraph.clone().block(block), area);
-}
-
-fn render_nested_blocks(paragraph: &Paragraph, frame: &mut Frame, area: Rect) {
-    let outer_block = Block::bordered().title("Outer block");
-    let inner_block = Block::bordered().title("Inner block");
-    let inner = outer_block.inner(area);
-    frame.render_widget(outer_block, area);
-    frame.render_widget(paragraph.clone().block(inner_block), inner);
-}

examples/calendar.rs

@@ -1,267 +0,0 @@
-//! # [Ratatui] Calendar example
-//!
-//! The latest version of this example is available in the [examples] folder in the repository.
-//!
-//! Please note that the examples are designed to be run against the `main` branch of the Github
-//! repository. This means that you may not be able to compile with the latest release version on
-//! crates.io, or the one that you have installed locally.
-//!
-//! See the [examples readme] for more information on finding examples that match the version of the
-//! library you are using.
-//!
-//! [Ratatui]: https://github.com/ratatui-org/ratatui
-//! [examples]: https://github.com/ratatui-org/ratatui/blob/main/examples
-//! [examples readme]: https://github.com/ratatui-org/ratatui/blob/main/examples/README.md
-
-use std::{error::Error, io};
-
-use ratatui::{
-    backend::CrosstermBackend,
-    crossterm::{
-        event::{self, Event, KeyCode},
-        execute,
-        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-    },
-    layout::{Constraint, Layout, Rect},
-    style::{Color, Modifier, Style},
-    widgets::calendar::{CalendarEventStore, DateStyler, Monthly},
-    Frame, Terminal,
-};
-use 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)?;
-
-    loop {
-        let _ = terminal.draw(draw);
-
-        if let Event::Key(key) = event::read()? {
-            #[allow(clippy::single_match)]
-            match key.code {
-                KeyCode::Char(_) => {
-                    break;
-                }
-                _ => {}
-            };
-        }
-    }
-
-    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 mut start = OffsetDateTime::now_local()
-        .unwrap()
-        .date()
-        .replace_month(Month::January)
-        .unwrap()
-        .replace_day(1)
-        .unwrap();
-
-    let list = make_dates(start.year());
-
-    let rows = Layout::vertical([Constraint::Ratio(1, 3); 3]).split(calarea);
-    let cols = rows.iter().flat_map(|row| {
-        Layout::horizontal([Constraint::Ratio(1, 4); 4])
-            .split(*row)
-            .to_vec()
-    });
-    for col in cols {
-        let cal = cals::get_cal(start.month(), start.year(), &list);
-        frame.render_widget(cal, col);
-        start = start.replace_month(start.month().next()).unwrap();
-    }
-}
-
-fn make_dates(current_year: i32) -> CalendarEventStore {
-    let mut list = CalendarEventStore::today(
-        Style::default()
-            .add_modifier(Modifier::BOLD)
-            .bg(Color::Blue),
-    );
-
-    // Holidays
-    let holiday_style = Style::default()
-        .fg(Color::Red)
-        .add_modifier(Modifier::UNDERLINED);
-
-    // new year's
-    list.add(
-        Date::from_calendar_date(current_year, Month::January, 1).unwrap(),
-        holiday_style,
-    );
-    // next new_year's for December "show surrounding"
-    list.add(
-        Date::from_calendar_date(current_year + 1, Month::January, 1).unwrap(),
-        holiday_style,
-    );
-    // groundhog day
-    list.add(
-        Date::from_calendar_date(current_year, Month::February, 2).unwrap(),
-        holiday_style,
-    );
-    // april fool's
-    list.add(
-        Date::from_calendar_date(current_year, Month::April, 1).unwrap(),
-        holiday_style,
-    );
-    // earth day
-    list.add(
-        Date::from_calendar_date(current_year, Month::April, 22).unwrap(),
-        holiday_style,
-    );
-    // star wars day
-    list.add(
-        Date::from_calendar_date(current_year, Month::May, 4).unwrap(),
-        holiday_style,
-    );
-    // festivus
-    list.add(
-        Date::from_calendar_date(current_year, Month::December, 23).unwrap(),
-        holiday_style,
-    );
-    // new year's eve
-    list.add(
-        Date::from_calendar_date(current_year, Month::December, 31).unwrap(),
-        holiday_style,
-    );
-
-    // seasons
-    let season_style = Style::default()
-        .fg(Color::White)
-        .bg(Color::Yellow)
-        .add_modifier(Modifier::UNDERLINED);
-    // spring equinox
-    list.add(
-        Date::from_calendar_date(current_year, Month::March, 22).unwrap(),
-        season_style,
-    );
-    // summer solstice
-    list.add(
-        Date::from_calendar_date(current_year, Month::June, 21).unwrap(),
-        season_style,
-    );
-    // fall equinox
-    list.add(
-        Date::from_calendar_date(current_year, Month::September, 22).unwrap(),
-        season_style,
-    );
-    list.add(
-        Date::from_calendar_date(current_year, Month::December, 21).unwrap(),
-        season_style,
-    );
-    list
-}
-
-mod cals {
-    #[allow(clippy::wildcard_imports)]
-    use super::*;
-
-    pub fn get_cal<'a, DS: DateStyler>(m: Month, y: i32, es: DS) -> Monthly<'a, DS> {
-        match m {
-            Month::May => example1(m, y, es),
-            Month::June => example2(m, y, es),
-            Month::July | Month::December => example3(m, y, es),
-            Month::February => example4(m, y, es),
-            Month::November => example5(m, y, es),
-            _ => default(m, y, es),
-        }
-    }
-
-    fn default<'a, DS: DateStyler>(m: Month, y: i32, es: DS) -> Monthly<'a, DS> {
-        let default_style = Style::default()
-            .add_modifier(Modifier::BOLD)
-            .bg(Color::Rgb(50, 50, 50));
-
-        Monthly::new(Date::from_calendar_date(y, m, 1).unwrap(), es)
-            .show_month_header(Style::default())
-            .default_style(default_style)
-    }
-
-    fn example1<'a, DS: DateStyler>(m: Month, y: i32, es: DS) -> Monthly<'a, DS> {
-        let default_style = Style::default()
-            .add_modifier(Modifier::BOLD)
-            .bg(Color::Rgb(50, 50, 50));
-
-        Monthly::new(Date::from_calendar_date(y, m, 1).unwrap(), es)
-            .show_surrounding(default_style)
-            .default_style(default_style)
-            .show_month_header(Style::default())
-    }
-
-    fn example2<'a, DS: DateStyler>(m: Month, y: i32, es: DS) -> Monthly<'a, DS> {
-        let header_style = Style::default()
-            .add_modifier(Modifier::BOLD)
-            .add_modifier(Modifier::DIM)
-            .fg(Color::LightYellow);
-
-        let default_style = Style::default()
-            .add_modifier(Modifier::BOLD)
-            .bg(Color::Rgb(50, 50, 50));
-
-        Monthly::new(Date::from_calendar_date(y, m, 1).unwrap(), es)
-            .show_weekdays_header(header_style)
-            .default_style(default_style)
-            .show_month_header(Style::default())
-    }
-
-    fn example3<'a, DS: DateStyler>(m: Month, y: i32, es: DS) -> Monthly<'a, DS> {
-        let header_style = Style::default()
-            .add_modifier(Modifier::BOLD)
-            .fg(Color::Green);
-
-        let default_style = Style::default()
-            .add_modifier(Modifier::BOLD)
-            .bg(Color::Rgb(50, 50, 50));
-
-        Monthly::new(Date::from_calendar_date(y, m, 1).unwrap(), es)
-            .show_surrounding(Style::default().add_modifier(Modifier::DIM))
-            .show_weekdays_header(header_style)
-            .default_style(default_style)
-            .show_month_header(Style::default())
-    }
-
-    fn example4<'a, DS: DateStyler>(m: Month, y: i32, es: DS) -> Monthly<'a, DS> {
-        let header_style = Style::default()
-            .add_modifier(Modifier::BOLD)
-            .fg(Color::Green);
-
-        let default_style = Style::default()
-            .add_modifier(Modifier::BOLD)
-            .bg(Color::Rgb(50, 50, 50));
-
-        Monthly::new(Date::from_calendar_date(y, m, 1).unwrap(), es)
-            .show_weekdays_header(header_style)
-            .default_style(default_style)
-    }
-
-    fn example5<'a, DS: DateStyler>(m: Month, y: i32, es: DS) -> Monthly<'a, DS> {
-        let header_style = Style::default()
-            .add_modifier(Modifier::BOLD)
-            .fg(Color::Green);
-
-        let default_style = Style::default()
-            .add_modifier(Modifier::BOLD)
-            .bg(Color::Rgb(50, 50, 50));
-
-        Monthly::new(Date::from_calendar_date(y, m, 1).unwrap(), es)
-            .show_month_header(header_style)
-            .default_style(default_style)
-    }
-}

examples/canvas.rs

@@ -1,218 +0,0 @@
-//! # [Ratatui] Canvas example
-//!
-//! The latest version of this example is available in the [examples] folder in the repository.
-//!
-//! Please note that the examples are designed to be run against the `main` branch of the Github
-//! repository. This means that you may not be able to compile with the latest release version on
-//! crates.io, or the one that you have installed locally.
-//!
-//! See the [examples readme] for more information on finding examples that match the version of the
-//! library you are using.
-//!
-//! [Ratatui]: https://github.com/ratatui-org/ratatui
-//! [examples]: https://github.com/ratatui-org/ratatui/blob/main/examples
-//! [examples readme]: https://github.com/ratatui-org/ratatui/blob/main/examples/README.md
-
-use std::{
-    io::{self, stdout, Stdout},
-    time::{Duration, Instant},
-};
-
-use ratatui::{
-    backend::CrosstermBackend,
-    crossterm::{
-        event::{self, Event, KeyCode},
-        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-        ExecutableCommand,
-    },
-    layout::{Constraint, Layout, Rect},
-    style::{Color, Stylize},
-    symbols::Marker,
-    widgets::{
-        canvas::{Canvas, Circle, Map, MapResolution, Rectangle},
-        Block, Widget,
-    },
-    Frame, Terminal,
-};
-
-fn main() -> io::Result<()> {
-    App::run()
-}
-
-struct App {
-    x: f64,
-    y: f64,
-    ball: Circle,
-    playground: Rect,
-    vx: f64,
-    vy: f64,
-    tick_count: u64,
-    marker: Marker,
-}
-
-impl App {
-    fn new() -> Self {
-        Self {
-            x: 0.0,
-            y: 0.0,
-            ball: Circle {
-                x: 20.0,
-                y: 40.0,
-                radius: 10.0,
-                color: Color::Yellow,
-            },
-            playground: Rect::new(10, 10, 200, 100),
-            vx: 1.0,
-            vy: 1.0,
-            tick_count: 0,
-            marker: Marker::Dot,
-        }
-    }
-
-    pub fn run() -> io::Result<()> {
-        let mut terminal = init_terminal()?;
-        let mut app = Self::new();
-        let mut last_tick = Instant::now();
-        let tick_rate = Duration::from_millis(16);
-        loop {
-            let _ = terminal.draw(|frame| app.ui(frame));
-            let timeout = tick_rate.saturating_sub(last_tick.elapsed());
-            if event::poll(timeout)? {
-                if let Event::Key(key) = event::read()? {
-                    match key.code {
-                        KeyCode::Char('q') => break,
-                        KeyCode::Down | KeyCode::Char('j') => app.y += 1.0,
-                        KeyCode::Up | KeyCode::Char('k') => app.y -= 1.0,
-                        KeyCode::Right | KeyCode::Char('l') => app.x += 1.0,
-                        KeyCode::Left | KeyCode::Char('h') => app.x -= 1.0,
-                        _ => {}
-                    }
-                }
-            }
-
-            if last_tick.elapsed() >= tick_rate {
-                app.on_tick();
-                last_tick = Instant::now();
-            }
-        }
-        restore_terminal()
-    }
-
-    fn on_tick(&mut self) {
-        self.tick_count += 1;
-        // only change marker every 180 ticks (3s) to avoid stroboscopic effect
-        if (self.tick_count % 180) == 0 {
-            self.marker = match self.marker {
-                Marker::Dot => Marker::Braille,
-                Marker::Braille => Marker::Block,
-                Marker::Block => Marker::HalfBlock,
-                Marker::HalfBlock => Marker::Bar,
-                Marker::Bar => Marker::Dot,
-            };
-        }
-        // bounce the ball by flipping the velocity vector
-        let ball = &self.ball;
-        let playground = self.playground;
-        if ball.x - ball.radius < f64::from(playground.left())
-            || ball.x + ball.radius > f64::from(playground.right())
-        {
-            self.vx = -self.vx;
-        }
-        if ball.y - ball.radius < f64::from(playground.top())
-            || ball.y + ball.radius > f64::from(playground.bottom())
-        {
-            self.vy = -self.vy;
-        }
-
-        self.ball.x += self.vx;
-        self.ball.y += self.vy;
-    }
-
-    fn ui(&self, frame: &mut Frame) {
-        let horizontal =
-            Layout::horizontal([Constraint::Percentage(50), Constraint::Percentage(50)]);
-        let vertical = Layout::vertical([Constraint::Percentage(50), Constraint::Percentage(50)]);
-        let [map, right] = horizontal.areas(frame.area());
-        let [pong, boxes] = vertical.areas(right);
-
-        frame.render_widget(self.map_canvas(), map);
-        frame.render_widget(self.pong_canvas(), pong);
-        frame.render_widget(self.boxes_canvas(boxes), boxes);
-    }
-
-    fn map_canvas(&self) -> impl Widget + '_ {
-        Canvas::default()
-            .block(Block::bordered().title("World"))
-            .marker(self.marker)
-            .paint(|ctx| {
-                ctx.draw(&Map {
-                    color: Color::Green,
-                    resolution: MapResolution::High,
-                });
-                ctx.print(self.x, -self.y, "You are here".yellow());
-            })
-            .x_bounds([-180.0, 180.0])
-            .y_bounds([-90.0, 90.0])
-    }
-
-    fn pong_canvas(&self) -> impl Widget + '_ {
-        Canvas::default()
-            .block(Block::bordered().title("Pong"))
-            .marker(self.marker)
-            .paint(|ctx| {
-                ctx.draw(&self.ball);
-            })
-            .x_bounds([10.0, 210.0])
-            .y_bounds([10.0, 110.0])
-    }
-
-    fn boxes_canvas(&self, area: Rect) -> impl Widget {
-        let left = 0.0;
-        let right = f64::from(area.width);
-        let bottom = 0.0;
-        let top = f64::from(area.height).mul_add(2.0, -4.0);
-        Canvas::default()
-            .block(Block::bordered().title("Rects"))
-            .marker(self.marker)
-            .x_bounds([left, right])
-            .y_bounds([bottom, top])
-            .paint(|ctx| {
-                for i in 0..=11 {
-                    ctx.draw(&Rectangle {
-                        x: f64::from(i * i + 3 * i) / 2.0 + 2.0,
-                        y: 2.0,
-                        width: f64::from(i),
-                        height: f64::from(i),
-                        color: Color::Red,
-                    });
-                    ctx.draw(&Rectangle {
-                        x: f64::from(i * i + 3 * i) / 2.0 + 2.0,
-                        y: 21.0,
-                        width: f64::from(i),
-                        height: f64::from(i),
-                        color: Color::Blue,
-                    });
-                }
-                for i in 0..100 {
-                    if i % 10 != 0 {
-                        ctx.print(f64::from(i) + 1.0, 0.0, format!("{i}", i = i % 10));
-                    }
-                    if i % 2 == 0 && i % 10 != 0 {
-                        ctx.print(0.0, f64::from(i), format!("{i}", i = i % 10));
-                    }
-                }
-            })
-    }
-}
-
-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/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

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

examples/demo2/tabs/about.rs

@@ -1,165 +0,0 @@
-use itertools::Itertools;
-use ratatui::{
-    buffer::Buffer,
-    layout::{Alignment, Constraint, Layout, Margin, Rect},
-    widgets::{Block, Borders, Clear, Padding, Paragraph, Widget, Wrap},
-};
-
-use crate::{RgbSwatch, THEME};
-
-const RATATUI_LOGO: [&str; 32] = [
-    "               ███              ",
-    "             ██████             ",
-    "            ███████             ",
-    "           ████████             ",
-    "          █████████             ",
-    "         ██████████             ",
-    "        ████████████            ",
-    "        █████████████           ",
-    "        █████████████     ██████",
-    "         ███████████    ████████",
-    "              █████ ███████████ ",
-    "               ███ ██ee████████ ",
-    "                █ █████████████ ",
-    "            ████ █████████████  ",
-    "           █████████████████    ",
-    "           ████████████████     ",
-    "           ████████████████     ",
-    "            ███ ██████████      ",
-    "          ██    █████████       ",
-    "         █xx█   █████████       ",
-    "        █xxxx█ ██████████       ",
-    "       █xx█xxx█ █████████       ",
-    "      █xx██xxxx█ ████████       ",
-    "     █xxxxxxxxxx█ ██████████    ",
-    "    █xxxxxxxxxxxx█ ██████████   ",
-    "   █xxxxxxx██xxxxx█ █████████   ",
-    "  █xxxxxxxxx██xxxxx█ ████  ███  ",
-    " █xxxxxxxxxxxxxxxxxx█ ██   ███  ",
-    "█xxxxxxxxxxxxxxxxxxxx█ █   ███  ",
-    "█xxxxxxxxxxxxxxxxxxxxx█   ███   ",
-    " █xxxxxxxxxxxxxxxxxxxxx█ ███    ",
-    "  █xxxxxxxxxxxxxxxxxxxxx█ █     ",
-];
-
-#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
-pub struct AboutTab {
-    row_index: usize,
-}
-
-impl AboutTab {
-    pub fn prev_row(&mut self) {
-        self.row_index = self.row_index.saturating_sub(1);
-    }
-
-    pub fn next_row(&mut self) {
-        self.row_index = self.row_index.saturating_add(1);
-    }
-}
-
-impl Widget for AboutTab {
-    fn render(self, area: Rect, buf: &mut Buffer) {
-        RgbSwatch.render(area, buf);
-        let horizontal = Layout::horizontal([Constraint::Length(34), Constraint::Min(0)]);
-        let [description, logo] = horizontal.areas(area);
-        render_crate_description(description, buf);
-        render_logo(self.row_index, logo, buf);
-    }
-}
-
-fn render_crate_description(area: Rect, buf: &mut Buffer) {
-    let area = area.inner(Margin {
-        vertical: 4,
-        horizontal: 2,
-    });
-    Clear.render(area, buf); // clear out the color swatches
-    Block::new().style(THEME.content).render(area, buf);
-    let area = area.inner(Margin {
-        vertical: 1,
-        horizontal: 2,
-    });
-    let text = "- cooking up terminal user interfaces -
-
-    Ratatui is a Rust crate that provides widgets (e.g. Paragraph, Table) and draws them to the \
-    screen efficiently every frame.";
-    Paragraph::new(text)
-        .style(THEME.description)
-        .block(
-            Block::new()
-                .title(" Ratatui ")
-                .title_alignment(Alignment::Center)
-                .borders(Borders::TOP)
-                .border_style(THEME.description_title)
-                .padding(Padding::new(0, 0, 0, 0)),
-        )
-        .wrap(Wrap { trim: true })
-        .scroll((0, 0))
-        .render(area, buf);
-}
-
-/// Use half block characters to render a logo based on the `RATATUI_LOGO` const.
-///
-/// The logo is rendered in three colors, one for the rat, one for the terminal, and one for the
-/// rat's eye. The eye color alternates between two colors based on the selected row.
-#[allow(clippy::cast_possible_truncation)]
-pub fn render_logo(selected_row: usize, area: Rect, buf: &mut Buffer) {
-    let eye_color = if selected_row % 2 == 0 {
-        THEME.logo.rat_eye
-    } else {
-        THEME.logo.rat_eye_alt
-    };
-    let area = area.inner(Margin {
-        vertical: 0,
-        horizontal: 2,
-    });
-    for (y, (line1, line2)) in RATATUI_LOGO.iter().tuples().enumerate() {
-        for (x, (ch1, ch2)) in line1.chars().zip(line2.chars()).enumerate() {
-            let x = area.left() + x as u16;
-            let y = area.top() + y as u16;
-            let cell = &mut buf[(x, y)];
-            let rat_color = THEME.logo.rat;
-            let term_color = THEME.logo.term;
-            match (ch1, ch2) {
-                ('█', '█') => {
-                    cell.set_char('█');
-                    cell.fg = rat_color;
-                    cell.bg = rat_color;
-                }
-                ('█', ' ') => {
-                    cell.set_char('▀');
-                    cell.fg = rat_color;
-                }
-                (' ', '█') => {
-                    cell.set_char('▄');
-                    cell.fg = rat_color;
-                }
-                ('█', 'x') => {
-                    cell.set_char('▀');
-                    cell.fg = rat_color;
-                    cell.bg = term_color;
-                }
-                ('x', '█') => {
-                    cell.set_char('▄');
-                    cell.fg = rat_color;
-                    cell.bg = term_color;
-                }
-                ('x', 'x') => {
-                    cell.set_char(' ');
-                    cell.fg = term_color;
-                    cell.bg = term_color;
-                }
-                ('█', 'e') => {
-                    cell.set_char('▀');
-                    cell.fg = rat_color;
-                    cell.bg = eye_color;
-                }
-                ('e', '█') => {
-                    cell.set_char('▄');
-                    cell.fg = rat_color;
-                    cell.bg = eye_color;
-                }
-                (_, _) => {}
-            };
-        }
-    }
-}

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

@@ -1,112 +0,0 @@
-//! # [Ratatui] Hello World example
-//!
-//! The latest version of this example is available in the [examples] folder in the repository.
-//!
-//! Please note that the examples are designed to be run against the `main` branch of the Github
-//! repository. This means that you may not be able to compile with the latest release version on
-//! crates.io, or the one that you have installed locally.
-//!
-//! See the [examples readme] for more information on finding examples that match the version of the
-//! library you are using.
-//!
-//! [Ratatui]: https://github.com/ratatui-org/ratatui
-//! [examples]: https://github.com/ratatui-org/ratatui/blob/main/examples
-//! [examples readme]: https://github.com/ratatui-org/ratatui/blob/main/examples/README.md
-
-use std::{
-    io::{self, Stdout},
-    time::Duration,
-};
-
-use color_eyre::{eyre::Context, Result};
-use ratatui::{
-    backend::CrosstermBackend,
-    crossterm::{
-        event::{self, Event, KeyCode},
-        execute,
-        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-    },
-    widgets::Paragraph,
-    Frame, Terminal,
-};
-
-/// This is a bare minimum example. There are many approaches to running an application loop, so
-/// this is not meant to be prescriptive. It is only meant to demonstrate the basic setup and
-/// teardown of a terminal application.
-///
-/// This example does not handle events or update the application state. It just draws a greeting
-/// 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);
-    }));
-}
-
-/// 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<()> {
-    loop {
-        terminal.draw(render_app)?;
-        if should_quit()? {
-            break;
-        }
-    }
-    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) {
-    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.
-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")? {
-            return Ok(KeyCode::Char('q') == key.code);
-        }
-    }
-    Ok(false)
-}

examples/minimal.rs

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

examples/panic.rs

@@ -1,152 +0,0 @@
-//! # [Ratatui] Panic Hook example
-//!
-//! The latest version of this example is available in the [examples] folder in the repository.
-//!
-//! Please note that the examples are designed to be run against the `main` branch of the Github
-//! repository. This means that you may not be able to compile with the latest release version on
-//! crates.io, or the one that you have installed locally.
-//!
-//! See the [examples readme] for more information on finding examples that match the version of the
-//! library you are using.
-//!
-//! [Ratatui]: https://github.com/ratatui-org/ratatui
-//! [examples]: https://github.com/ratatui-org/ratatui/blob/main/examples
-//! [examples readme]: https://github.com/ratatui-org/ratatui/blob/main/examples/README.md
-
-//! How to use a panic hook to reset the terminal before printing the panic to
-//! the terminal.
-//!
-//! 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 chained panic hook, to see the difference.
-
-use std::{error::Error, io};
-
-use ratatui::{
-    backend::{Backend, CrosstermBackend},
-    crossterm::{
-        event::{self, Event, KeyCode},
-        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-    },
-    text::Line,
-    widgets::{Block, Paragraph},
-    Frame, Terminal,
-};
-
-type Result<T> = std::result::Result<T, Box<dyn Error>>;
-
-#[derive(Default)]
-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:?}");
-    }
-
-    Ok(())
-}
-
-/// 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(());
-                }
-            }
-        }
-    }
-}
-
-/// 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());
-}

examples/paragraph.rs

@@ -1,231 +0,0 @@
-//! # [Ratatui] Paragraph example
-//!
-//! The latest version of this example is available in the [examples] folder in the repository.
-//!
-//! Please note that the examples are designed to be run against the `main` branch of the Github
-//! repository. This means that you may not be able to compile with the latest release version on
-//! crates.io, or the one that you have installed locally.
-//!
-//! See the [examples readme] for more information on finding examples that match the version of the
-//! library you are using.
-//!
-//! [Ratatui]: https://github.com/ratatui-org/ratatui
-//! [examples]: https://github.com/ratatui-org/ratatui/blob/main/examples
-//! [examples readme]: https://github.com/ratatui-org/ratatui/blob/main/examples/README.md
-
-use std::{
-    io::{self},
-    time::{Duration, Instant},
-};
-
-use crossterm::event::KeyEventKind;
-use ratatui::{
-    buffer::Buffer,
-    crossterm::event::{self, Event, KeyCode},
-    layout::{Constraint, Layout, Rect},
-    style::{Color, Stylize},
-    text::{Line, Masked, Span},
-    widgets::{Block, Paragraph, Widget, Wrap},
-};
-
-use 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(())
-}
-
-#[derive(Debug)]
-struct App {
-    should_exit: bool,
-    scroll: u16,
-    last_tick: Instant,
-}
-
-impl App {
-    /// The duration between each tick.
-    const TICK_RATE: Duration = Duration::from_millis(250);
-
-    /// Create a new instance of the app.
-    fn new() -> Self {
-        Self {
-            should_exit: false,
-            scroll: 0,
-            last_tick: Instant::now(),
-        }
-    }
-
-    /// Run the app until the user exits.
-    fn run(&mut self, terminal: &mut Tui) -> io::Result<()> {
-        while !self.should_exit {
-            self.draw(terminal)?;
-            self.handle_events()?;
-            if self.last_tick.elapsed() >= Self::TICK_RATE {
-                self.on_tick();
-                self.last_tick = Instant::now();
-            }
-        }
-        Ok(())
-    }
-
-    /// Draw the app to the terminal.
-    fn draw(&mut self, terminal: &mut Tui) -> io::Result<()> {
-        terminal.draw(|frame| frame.render_widget(self, frame.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());
-        while event::poll(timeout)? {
-            if let Event::Key(key) = event::read()? {
-                if key.kind == KeyEventKind::Press && key.code == KeyCode::Char('q') {
-                    self.should_exit = true;
-                }
-            }
-        }
-        Ok(())
-    }
-
-    /// Update the app state on each tick.
-    fn on_tick(&mut self) {
-        self.scroll = (self.scroll + 1) % 10;
-    }
-}
-
-impl Widget for &mut App {
-    fn render(self, area: Rect, buf: &mut Buffer) {
-        let areas = Layout::vertical([Constraint::Max(9); 4]).split(area);
-        Paragraph::new(create_lines(area))
-            .block(title_block("Default alignment (Left), no wrap"))
-            .gray()
-            .render(areas[0], buf);
-        Paragraph::new(create_lines(area))
-            .block(title_block("Default alignment (Left), with wrap"))
-            .gray()
-            .wrap(Wrap { trim: true })
-            .render(areas[1], buf);
-        Paragraph::new(create_lines(area))
-            .block(title_block("Right alignment, with wrap"))
-            .gray()
-            .right_aligned()
-            .wrap(Wrap { trim: true })
-            .render(areas[2], buf);
-        Paragraph::new(create_lines(area))
-            .block(title_block("Center alignment, with wrap, with scroll"))
-            .gray()
-            .centered()
-            .wrap(Wrap { trim: true })
-            .scroll((self.scroll, 0))
-            .render(areas[3], buf);
-    }
-}
-
-/// Create a bordered block with a title.
-fn title_block(title: &str) -> Block {
-    Block::bordered()
-        .gray()
-        .title(title.bold().into_centered_line())
-}
-
-/// Create some lines to display in the paragraph.
-fn create_lines(area: Rect) -> Vec<Line<'static>> {
-    let short_line = "A long line to demonstrate line wrapping. ";
-    let long_line = short_line.repeat(usize::from(area.width) / short_line.len() + 4);
-    let mut styled_spans = vec![];
-    for span in [
-        "Styled".blue(),
-        "Spans".red().on_white(),
-        "Bold".bold(),
-        "Italic".italic(),
-        "Underlined".underlined(),
-        "Strikethrough".crossed_out(),
-    ] {
-        styled_spans.push(span);
-        styled_spans.push(" ".into());
-    }
-    vec![
-        Line::raw("Unstyled Line"),
-        Line::raw("Styled Line").black().on_red().bold().italic(),
-        Line::from(styled_spans),
-        Line::from(long_line.green().italic()),
-        Line::from_iter([
-            "Masked text: ".into(),
-            Span::styled(Masked::new("my secret password", '*'), Color::Red),
-        ]),
-    ]
-}
-
-/// 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

@@ -1,130 +0,0 @@
-//! # [Ratatui] Popup example
-//!
-//! The latest version of this example is available in the [examples] folder in the repository.
-//!
-//! Please note that the examples are designed to be run against the `main` branch of the Github
-//! repository. This means that you may not be able to compile with the latest release version on
-//! crates.io, or the one that you have installed locally.
-//!
-//! See the [examples readme] for more information on finding examples that match the version of the
-//! library you are using.
-//!
-//! [Ratatui]: https://github.com/ratatui-org/ratatui
-//! [examples]: https://github.com/ratatui-org/ratatui/blob/main/examples
-//! [examples readme]: https://github.com/ratatui-org/ratatui/blob/main/examples/README.md
-
-// See also https://github.com/joshka/tui-popup and
-// https://github.com/sephiroth74/tui-confirm-dialog
-
-use std::{error::Error, io};
-
-use ratatui::{
-    backend::{Backend, CrosstermBackend},
-    crossterm::{
-        event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode, KeyEventKind},
-        execute,
-        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-    },
-    layout::{Constraint, Layout, Rect},
-    style::Stylize,
-    widgets::{Block, Clear, Paragraph, Wrap},
-    Frame, Terminal,
-};
-
-struct App {
-    show_popup: bool,
-}
-
-impl App {
-    const fn new() -> Self {
-        Self { show_popup: false }
-    }
-}
-
-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,
-                    _ => {}
-                }
-            }
-        }
-    }
-}
-
-fn ui(f: &mut Frame, app: &App) {
-    let area = f.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 block = Block::bordered().title("Content").on_blue();
-    f.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);
-    }
-}
-
-/// 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]
-}

examples/ratatui-logo.rs

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

@@ -1,238 +0,0 @@
-//! # [Ratatui] Scrollbar example
-//!
-//! The latest version of this example is available in the [examples] folder in the repository.
-//!
-//! Please note that the examples are designed to be run against the `main` branch of the Github
-//! repository. This means that you may not be able to compile with the latest release version on
-//! crates.io, or the one that you have installed locally.
-//!
-//! See the [examples readme] for more information on finding examples that match the version of the
-//! library you are using.
-//!
-//! [Ratatui]: https://github.com/ratatui-org/ratatui
-//! [examples]: https://github.com/ratatui-org/ratatui/blob/main/examples
-//! [examples readme]: https://github.com/ratatui-org/ratatui/blob/main/examples/README.md
-
-#![warn(clippy::pedantic)]
-
-use std::{
-    error::Error,
-    io,
-    time::{Duration, Instant},
-};
-
-use ratatui::{
-    backend::{Backend, CrosstermBackend},
-    crossterm::{
-        event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode},
-        execute,
-        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-    },
-    layout::{Alignment, Constraint, Layout, Margin},
-    style::{Color, Style, Stylize},
-    symbols::scrollbar,
-    text::{Line, Masked, Span},
-    widgets::{Block, Paragraph, Scrollbar, ScrollbarOrientation, ScrollbarState},
-    Frame, Terminal,
-};
-
-#[derive(Default)]
-struct App {
-    pub vertical_scroll_state: ScrollbarState,
-    pub horizontal_scroll_state: ScrollbarState,
-    pub vertical_scroll: usize,
-    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 run_app<B: Backend>(
-    terminal: &mut Terminal<B>,
-    mut app: App,
-    tick_rate: Duration,
-) -> io::Result<()> {
-    let mut last_tick = Instant::now();
-    loop {
-        terminal.draw(|f| ui(f, &mut app))?;
-
-        let timeout = tick_rate.saturating_sub(last_tick.elapsed());
-        if crossterm::event::poll(timeout)? {
-            if let Event::Key(key) = event::read()? {
-                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);
-                    }
-                    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();
-        }
-    }
-}
-
-#[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,
-    );
-}

examples/sparkline.rs

@@ -1,183 +0,0 @@
-//! # [Ratatui] Sparkline example
-//!
-//! The latest version of this example is available in the [examples] folder in the repository.
-//!
-//! Please note that the examples are designed to be run against the `main` branch of the Github
-//! repository. This means that you may not be able to compile with the latest release version on
-//! crates.io, or the one that you have installed locally.
-//!
-//! See the [examples readme] for more information on finding examples that match the version of the
-//! library you are using.
-//!
-//! [Ratatui]: https://github.com/ratatui-org/ratatui
-//! [examples]: https://github.com/ratatui-org/ratatui/blob/main/examples
-//! [examples readme]: https://github.com/ratatui-org/ratatui/blob/main/examples/README.md
-
-use std::{
-    error::Error,
-    io,
-    time::{Duration, Instant},
-};
-
-use 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},
-    },
-    layout::{Constraint, Layout},
-    style::{Color, Style},
-    widgets::{Block, Borders, Sparkline},
-    Frame, Terminal,
-};
-
-#[derive(Clone)]
-struct RandomSignal {
-    distribution: Uniform<u64>,
-    rng: ThreadRng,
-}
-
-impl RandomSignal {
-    fn new(lower: u64, upper: u64) -> Self {
-        Self {
-            distribution: Uniform::new(lower, upper),
-            rng: rand::thread_rng(),
-        }
-    }
-}
-
-impl Iterator for RandomSignal {
-    type Item = u64;
-    fn next(&mut self) -> Option<u64> {
-        Some(self.distribution.sample(&mut self.rng))
-    }
-}
-
-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);
-        let data1 = signal.by_ref().take(200).collect::<Vec<u64>>();
-        let data2 = signal.by_ref().take(200).collect::<Vec<u64>>();
-        let data3 = signal.by_ref().take(200).collect::<Vec<u64>>();
-        Self {
-            signal,
-            data1,
-            data2,
-            data3,
-        }
-    }
-
-    fn on_tick(&mut self) {
-        let value = self.signal.next().unwrap();
-        self.data1.pop();
-        self.data1.insert(0, value);
-        let value = self.signal.next().unwrap();
-        self.data2.pop();
-        self.data2.insert(0, value);
-        let value = self.signal.next().unwrap();
-        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)?;
-
-    // create app and run it
-    let tick_rate = Duration::from_millis(250);
-    let app = App::new();
-    let res = run_app(&mut terminal, app, tick_rate);
-
-    // restore terminal
-    disable_raw_mode()?;
-    execute!(
-        terminal.backend_mut(),
-        LeaveAlternateScreen,
-        DisableMouseCapture
-    )?;
-    terminal.show_cursor()?;
-
-    if let Err(err) = res {
-        println!("{err:?}");
-    }
-
-    Ok(())
-}
-
-fn run_app<B: Backend>(
-    terminal: &mut Terminal<B>,
-    mut app: App,
-    tick_rate: Duration,
-) -> io::Result<()> {
-    let mut last_tick = Instant::now();
-    loop {
-        terminal.draw(|f| ui(f, &app))?;
-
-        let timeout = tick_rate.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();
-        }
-    }
-}
-
-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]);
-}

examples/tabs.rs

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

examples/user_input.rs

@@ -1,274 +0,0 @@
-//! # [Ratatui] User Input example
-//!
-//! The latest version of this example is available in the [examples] folder in the repository.
-//!
-//! Please note that the examples are designed to be run against the `main` branch of the Github
-//! repository. This means that you may not be able to compile with the latest release version on
-//! crates.io, or the one that you have installed locally.
-//!
-//! See the [examples readme] for more information on finding examples that match the version of the
-//! library you are using.
-//!
-//! [Ratatui]: https://github.com/ratatui-org/ratatui
-//! [examples]: https://github.com/ratatui-org/ratatui/blob/main/examples
-//! [examples readme]: https://github.com/ratatui-org/ratatui/blob/main/examples/README.md
-
-// A simple example demonstrating how to handle user input. This is a bit out of the scope of
-// the library as it does not provide any input handling out of the box. However, it may helps
-// some to get started.
-//
-// This is a very simple example:
-//   * An input box always focused. Every character you type is registered here.
-//   * An entered character is inserted at the cursor position.
-//   * Pressing Backspace erases the left character before the cursor position
-//   * Pressing Enter pushes the current input in the history of previous messages. **Note: ** as
-//   this is a relatively simple example unicode characters are unsupported and their use will
-// result in undefined behaviour.
-//
-// See also https://github.com/rhysd/tui-textarea and https://github.com/sayanarijit/tui-input/
-
-use std::{error::Error, io};
-
-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, Position},
-    style::{Color, Modifier, Style, Stylize},
-    text::{Line, Span, Text},
-    widgets::{Block, List, ListItem, Paragraph},
-    Frame, Terminal,
-};
-
-enum InputMode {
-    Normal,
-    Editing,
-}
-
-/// App holds the state of the application
-struct App {
-    /// Current value of the input box
-    input: String,
-    /// Position of cursor in the editor area.
-    character_index: usize,
-    /// Current input mode
-    input_mode: InputMode,
-    /// History of recorded messages
-    messages: Vec<String>,
-}
-
-impl App {
-    const fn new() -> Self {
-        Self {
-            input: String::new(),
-            input_mode: InputMode::Normal,
-            messages: Vec::new(),
-            character_index: 0,
-        }
-    }
-
-    fn move_cursor_left(&mut self) {
-        let cursor_moved_left = self.character_index.saturating_sub(1);
-        self.character_index = self.clamp_cursor(cursor_moved_left);
-    }
-
-    fn move_cursor_right(&mut self) {
-        let cursor_moved_right = self.character_index.saturating_add(1);
-        self.character_index = self.clamp_cursor(cursor_moved_right);
-    }
-
-    fn enter_char(&mut self, new_char: char) {
-        let index = self.byte_index();
-        self.input.insert(index, new_char);
-        self.move_cursor_right();
-    }
-
-    /// Returns the byte index based on the character position.
-    ///
-    /// Since each character in a string can be contain multiple bytes, it's necessary to calculate
-    /// the byte index based on the index of the character.
-    fn byte_index(&self) -> usize {
-        self.input
-            .char_indices()
-            .map(|(i, _)| i)
-            .nth(self.character_index)
-            .unwrap_or(self.input.len())
-    }
-
-    fn delete_char(&mut self) {
-        let is_not_cursor_leftmost = self.character_index != 0;
-        if is_not_cursor_leftmost {
-            // Method "remove" is not used on the saved text for deleting the selected char.
-            // Reason: Using remove on String works on bytes instead of the chars.
-            // Using remove would require special care because of char boundaries.
-
-            let current_index = self.character_index;
-            let from_left_to_current_index = current_index - 1;
-
-            // Getting all characters before the selected character.
-            let before_char_to_delete = self.input.chars().take(from_left_to_current_index);
-            // Getting all characters after selected character.
-            let after_char_to_delete = self.input.chars().skip(current_index);
-
-            // Put all characters together except the selected one.
-            // By leaving the selected one out, it is forgotten and therefore deleted.
-            self.input = before_char_to_delete.chain(after_char_to_delete).collect();
-            self.move_cursor_left();
-        }
-    }
-
-    fn clamp_cursor(&self, new_cursor_pos: usize) -> usize {
-        new_cursor_pos.clamp(0, self.input.chars().count())
-    }
-
-    fn reset_cursor(&mut self) {
-        self.character_index = 0;
-    }
-
-    fn submit_message(&mut self) {
-        self.messages.push(self.input.clone());
-        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)?;
-
-    // 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 => {}
-            }
-        }
-    }
-}
-
-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());
-
-    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 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 => {}
-
-        // 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,
-        )),
-    }
-
-    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);
-}

ratatui-core/Cargo.toml

@@ -0,0 +1,69 @@
+[package]
+name = "ratatui-core"
+description = """
+    Core types and traits for the Ratatui Terminal UI library.
+    Widget libraries should use this crate. Applications should use the main Ratatui crate.
+"""
+version = "0.1.0-alpha.2"
+readme = "README.md"
+authors.workspace = true
+documentation.workspace = true
+repository.workspace = true
+homepage.workspace = true
+keywords.workspace = true
+categories.workspace = true
+license.workspace = true
+exclude.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+
+[package.metadata.docs.rs]
+all-features = true
+rustdoc-args = ["--cfg", "docsrs"]
+
+[features]
+default = []
+
+## enables conversions to / from colors, modifiers, and styles in the ['anstyle'] crate
+anstyle = ["dep:anstyle"]
+
+## enables conversions from colors in the [`palette`] crate to [`Color`](crate::style::Color).
+palette = ["dep:palette"]
+
+## enables the backend code that sets the underline color. Underline color is only supported by
+## the Crossterm backend, and is not supported on Windows 7.
+underline-color = []
+
+## Use terminal scrolling regions to make some operations less prone to
+## flickering. (i.e. Terminal::insert_before).
+scrolling-regions = []
+
+## enables serialization and deserialization of style and color types using the [`serde`] crate.
+## This is useful if you want to save themes to a file.
+serde = ["dep:serde", "bitflags/serde", "compact_str/serde"]
+
+[dependencies]
+anstyle = { version = "1", optional = true }
+bitflags = "2.3"
+cassowary = "0.3"
+compact_str = "0.8.0"
+document-features = { workspace = true, optional = true }
+indoc.workspace = true
+itertools.workspace = true
+lru = "0.12.0"
+palette = { version = "0.7.6", optional = true }
+paste = "1.0.2"
+serde = { workspace = true, optional = true }
+strum.workspace = true
+thiserror = "2"
+unicode-segmentation.workspace = true
+unicode-truncate = "2"
+unicode-width.workspace = true
+
+[dev-dependencies]
+pretty_assertions.workspace = true
+rstest.workspace = true
+serde_json.workspace = true
+
+[lints]
+workspace = true

ratatui-core/README.md

@@ -0,0 +1,41 @@
+# Ratatui Core
+
+[![Crates.io](https://img.shields.io/crates/v/ratatui-core)](https://crates.io/crates/ratatui-core)
+[![Documentation](https://docs.rs/ratatui-core/badge.svg)](https://docs.rs/ratatui-core)
+[![License](https://img.shields.io/crates/l/ratatui-core)](../LICENSE)
+
+<!-- ⚠️ DO NOT EDIT THIS FILE DIRECTLY, EDIT lib.rs AND THEN RUN `cargo rdme` to update this file. -->
+<!-- cargo-rdme start -->
+
+**ratatui-core** is the core library of the [ratatui] project,
+providing the essential building blocks for creating rich terminal user interfaces in Rust.
+
+[ratatui]: https://github.com/ratatui/ratatui
+
+### Why `ratatui-core`?
+
+The `ratatui-core` crate is split from the main [`ratatui`](https://crates.io/crates/ratatui) crate
+to offer better stability for widget library authors. Widget libraries should generally depend
+on `ratatui-core`, benefiting from a stable API and reducing the need for frequent updates.
+
+Applications, on the other hand, should depend on the main `ratatui` crate, which includes
+built-in widgets and additional features.
+
+## Installation
+
+Add `ratatui-core` to your `Cargo.toml`:
+
+```shell
+cargo add ratatui-core
+```
+
+## Contributing
+
+We welcome contributions from the community! Please see our [CONTRIBUTING](../CONTRIBUTING.md)
+guide for more details on how to get involved.
+
+### License
+
+This project is licensed under the MIT License. See the [LICENSE](../LICENSE) file for details.
+
+<!-- cargo-rdme end -->

ratatui-core/src/backend.rs

@@ -24,10 +24,10 @@
 //!
 //! # Example
 //!
-//! ```rust,no_run
+//! ```rust,ignore
 //! use std::io::stdout;
 //!
-//! use ratatui::prelude::*;
+//! use ratatui::{backend::CrosstermBackend, Terminal};
 //!
 //! let backend = CrosstermBackend::new(stdout());
 //! let mut terminal = Terminal::new(backend)?;
@@ -56,7 +56,7 @@
 //! Each backend handles raw mode differently, so the behavior may vary depending on the backend
 //! being used. Be sure to consult the backend's specific documentation for exact details on how it
 //! implements raw mode.
-
+//!
 //! # Alternate Screen
 //!
 //! The alternate screen is a separate buffer that some terminals provide, distinct from the main
@@ -90,16 +90,16 @@
 //! backend being used, and developers should consult the specific backend's documentation to
 //! understand how it implements mouse capture.
 //!
-//! [`TermionBackend`]: termion/struct.TermionBackend.html
-//! [`Terminal`]: crate::terminal::Terminal
-//! [`TermionBackend`]: termion/struct.TermionBackend.html
+//! [`CrosstermBackend`]: https://docs.rs/ratatui/latest/ratatui/backend/struct.CrosstermBackend.html
+//! [`TermionBackend`]: https://docs.rs/ratatui/latest/ratatui/backend/struct.TermionBackend.html
+//! [`TermwizBackend`]: https://docs.rs/ratatui/latest/ratatui/backend/struct.TermwizBackend.html
+//! [`Terminal`]: https://docs.rs/ratatui/latest/ratatui/struct.Terminal.html
 //! [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
-//! [Backend Comparison]:
-//!     https://ratatui.rs/concepts/backends/comparison/
-//! [Ratatui Website]: https://ratatui-org.github.io/ratatui-book
+//! [Examples]: https://github.com/ratatui/ratatui/tree/main/ratatui/examples/README.md
+//! [Backend Comparison]: https://ratatui.rs/concepts/backends/comparison/
+//! [Ratatui Website]: https://ratatui.rs
 use std::io;
 
 use strum::{Display, EnumString};
@@ -109,21 +109,6 @@ use crate::{
     layout::{Position, Size},
 };
 
-#[cfg(feature = "termion")]
-mod termion;
-#[cfg(feature = "termion")]
-pub use self::termion::TermionBackend;
-
-#[cfg(feature = "crossterm")]
-mod crossterm;
-#[cfg(feature = "crossterm")]
-pub use self::crossterm::CrosstermBackend;
-
-#[cfg(feature = "termwiz")]
-mod termwiz;
-#[cfg(feature = "termwiz")]
-pub use self::termwiz::TermwizBackend;
-
 mod test;
 pub use self::test::TestBackend;
 
@@ -162,7 +147,7 @@ pub struct WindowSize {
 /// Most applications should not need to interact with the `Backend` trait directly as the
 /// [`Terminal`] struct provides a higher level interface for interacting with the terminal.
 ///
-/// [`Terminal`]: crate::terminal::Terminal
+/// [`Terminal`]: https://docs.rs/ratatui/latest/ratatui/struct.Terminal.html
 pub trait Backend {
     /// Draw the given content to the terminal screen.
     ///
@@ -186,9 +171,11 @@ pub trait Backend {
     /// See also [`show_cursor`].
     /// # Example
     ///
-    /// ```rust
-    /// # use ratatui::backend::{Backend, TestBackend};
+    /// ```rust,ignore
+    /// # use ratatui::backend::{TestBackend};
     /// # let mut backend = TestBackend::new(80, 25);
+    /// use ratatui::backend::Backend;
+    ///
     /// backend.hide_cursor()?;
     /// // do something with hidden cursor
     /// backend.show_cursor()?;
@@ -221,10 +208,11 @@ pub trait Backend {
     ///
     /// # Example
     ///
-    /// ```rust
-    /// # use ratatui::backend::{Backend, TestBackend};
-    /// # use ratatui::layout::Position;
+    /// ```rust,ignore
+    /// # use ratatui::backend::{TestBackend};
     /// # let mut backend = TestBackend::new(80, 25);
+    /// use ratatui::{backend::Backend, layout::Position};
+    ///
     /// backend.set_cursor_position(Position { x: 10, y: 20 })?;
     /// assert_eq!(backend.get_cursor_position()?, Position { x: 10, y: 20 });
     /// # std::io::Result::Ok(())
@@ -253,9 +241,11 @@ pub trait Backend {
     ///
     /// # Example
     ///
-    /// ```rust,no_run
-    /// # use ratatui::backend::{Backend, TestBackend};
+    /// ```rust,ignore
+    /// # use ratatui::backend::{TestBackend};
     /// # let mut backend = TestBackend::new(80, 25);
+    /// use ratatui::backend::Backend;
+    ///
     /// backend.clear()?;
     /// # std::io::Result::Ok(())
     /// ```
@@ -269,9 +259,11 @@ pub trait Backend {
     ///
     /// # Example
     ///
-    /// ```rust,no_run
-    /// # use ratatui::{prelude::*, backend::{TestBackend, ClearType}};
+    /// ```rust,ignore
+    /// # use ratatui::{backend::{TestBackend}};
     /// # let mut backend = TestBackend::new(80, 25);
+    /// use ratatui::backend::{Backend, ClearType};
+    ///
     /// backend.clear_region(ClearType::All)?;
     /// # std::io::Result::Ok(())
     /// ```
@@ -301,9 +293,11 @@ pub trait Backend {
     ///
     /// # Example
     ///
-    /// ```rust
-    /// # use ratatui::{prelude::*, backend::TestBackend};
-    /// let backend = TestBackend::new(80, 25);
+    /// ```rust,ignore
+    /// # use ratatui::{backend::{TestBackend}};
+    /// # let backend = TestBackend::new(80, 25);
+    /// use ratatui::{backend::Backend, layout::Size};
+    ///
     /// assert_eq!(backend.size()?, Size::new(80, 25));
     /// # std::io::Result::Ok(())
     /// ```
@@ -318,6 +312,64 @@ pub trait Backend {
 
     /// Flush any buffered content to the terminal screen.
     fn flush(&mut self) -> io::Result<()>;
+
+    /// Scroll a region of the screen upwards, where a region is specified by a (half-open) range
+    /// of rows.
+    ///
+    /// Each row in the region is replaced by the row `line_count` rows below it, except the bottom
+    /// `line_count` rows, which are replaced by empty rows. If `line_count` is equal to or larger
+    /// than the number of rows in the region, then all rows are replaced with empty rows.
+    ///
+    /// If the region includes row 0, then `line_count` rows are copied into the bottom of the
+    /// scrollback buffer. These rows are first taken from the old contents of the region, starting
+    /// from the top. If there aren't sufficient rows in the region, then the remainder are empty
+    /// rows.
+    ///
+    /// The position of the cursor afterwards is undefined.
+    ///
+    /// The behavior is designed to match what ANSI terminals do when scrolling regions are
+    /// established. With ANSI terminals, a scrolling region can be established with the "^[[X;Yr"
+    /// sequence, where X and Y define the lines of the region. The scrolling region can be reset
+    /// to be the whole screen with the "^[[r" sequence.
+    ///
+    /// When a scrolling region is established in an ANSI terminal, various operations' behaviors
+    /// are changed in such a way that the scrolling region acts like a "virtual screen". In
+    /// particular, the scrolling sequence "^[[NS", which scrolls lines up by a count of N.
+    ///
+    /// On an ANSI terminal, this method will probably translate to something like:
+    /// "^[[X;Yr^[[NS^[[r". That is, set the scrolling region, scroll up, then reset the scrolling
+    /// region.
+    ///
+    /// For examples of how this function is expected to work, refer to the tests for
+    /// [`TestBackend::scroll_region_up`].
+    #[cfg(feature = "scrolling-regions")]
+    fn scroll_region_up(&mut self, region: std::ops::Range<u16>, line_count: u16)
+        -> io::Result<()>;
+
+    /// Scroll a region of the screen downwards, where a region is specified by a (half-open) range
+    /// of rows.
+    ///
+    /// Each row in the region is replaced by the row `line_count` rows above it, except the top
+    /// `line_count` rows, which are replaced by empty rows. If `line_count` is equal to or larger
+    /// than the number of rows in the region, then all rows are replaced with empty rows.
+    ///
+    /// The position of the cursor afterwards is undefined.
+    ///
+    /// See the documentation for [`Self::scroll_region_down`] for more information about how this
+    /// is expected to be implemented for ANSI terminals. All of that applies, except the ANSI
+    /// sequence to scroll down is "^[[NT".
+    ///
+    /// This function is asymmetrical with regards to the scrollback buffer. The reason is that
+    /// this how terminals seem to implement things.
+    ///
+    /// For examples of how this function is expected to work, refer to the tests for
+    /// [`TestBackend::scroll_region_down`].
+    #[cfg(feature = "scrolling-regions")]
+    fn scroll_region_down(
+        &mut self,
+        region: std::ops::Range<u16>,
+        line_count: u16,
+    ) -> io::Result<()>;
 }
 
 #[cfg(test)]

ratatui-core/src/backend/test.rs

@@ -3,7 +3,7 @@
 
 use std::{
     fmt::{self, Write},
-    io,
+    io, iter,
 };
 
 use unicode_width::UnicodeWidthStr;
@@ -23,8 +23,8 @@ use crate::{
 ///
 /// # Example
 ///
-/// ```rust
-/// use ratatui::{backend::TestBackend, prelude::*};
+/// ```rust,ignore
+/// use ratatui::backend::{Backend, TestBackend};
 ///
 /// let mut backend = TestBackend::new(10, 2);
 /// backend.clear()?;
@@ -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,29 @@ 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),
+        }
+    }
+
+    /// Creates a new `TestBackend` with the specified lines as the initial screen state.
+    ///
+    /// The backend's screen size is determined from the initial lines.
+    #[must_use]
+    pub fn with_lines<'line, Lines>(lines: Lines) -> Self
+    where
+        Lines: IntoIterator,
+        Lines::Item: Into<crate::text::Line<'line>>,
+    {
+        let buffer = Buffer::with_lines(lines);
+        let scrollback = Buffer::empty(Rect {
+            width: buffer.area.width,
+            ..Rect::ZERO
+        });
+        Self {
+            buffer,
+            scrollback,
             cursor: false,
             pos: (0, 0),
         }
@@ -83,9 +107,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 +137,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 +147,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 +194,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]
@@ -175,7 +269,7 @@ impl Backend for TestBackend {
         Ok(())
     }
 
-    fn clear_region(&mut self, clear_type: super::ClearType) -> io::Result<()> {
+    fn clear_region(&mut self, clear_type: ClearType) -> io::Result<()> {
         let region = match clear_type {
             ClearType::All => return self.clear(),
             ClearType::AfterCursor => {
@@ -215,7 +309,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 +318,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(())
@@ -261,10 +365,98 @@ impl Backend for TestBackend {
     fn flush(&mut self) -> io::Result<()> {
         Ok(())
     }
+
+    #[cfg(feature = "scrolling-regions")]
+    fn scroll_region_up(&mut self, region: std::ops::Range<u16>, scroll_by: u16) -> io::Result<()> {
+        let width: usize = self.buffer.area.width.into();
+        let cell_region_start = width * region.start.min(self.buffer.area.height) as usize;
+        let cell_region_end = width * region.end.min(self.buffer.area.height) as usize;
+        let cell_region_len = cell_region_end - cell_region_start;
+        let cells_to_scroll_by = width * scroll_by as usize;
+
+        // Deal with the simple case where nothing needs to be copied into scrollback.
+        if cell_region_start > 0 {
+            if cells_to_scroll_by >= cell_region_len {
+                // The scroll amount is large enough to clear the whole region.
+                self.buffer.content[cell_region_start..cell_region_end].fill_with(Default::default);
+            } else {
+                // Scroll up by rotating, then filling in the bottom with empty cells.
+                self.buffer.content[cell_region_start..cell_region_end]
+                    .rotate_left(cells_to_scroll_by);
+                self.buffer.content[cell_region_end - cells_to_scroll_by..cell_region_end]
+                    .fill_with(Default::default);
+            }
+            return Ok(());
+        }
+
+        // The rows inserted into the scrollback will first come from the buffer, and if that is
+        // insufficient, will then be blank rows.
+        let cells_from_region = cell_region_len.min(cells_to_scroll_by);
+        append_to_scrollback(
+            &mut self.scrollback,
+            self.buffer.content.splice(
+                0..cells_from_region,
+                iter::repeat_with(Default::default).take(cells_from_region),
+            ),
+        );
+        if cells_to_scroll_by < cell_region_len {
+            // Rotate the remaining cells to the front of the region.
+            self.buffer.content[cell_region_start..cell_region_end].rotate_left(cells_from_region);
+        } else {
+            // Splice cleared out the region. Insert empty rows in scrollback.
+            append_to_scrollback(
+                &mut self.scrollback,
+                iter::repeat_with(Default::default).take(cells_to_scroll_by - cell_region_len),
+            );
+        }
+        Ok(())
+    }
+
+    #[cfg(feature = "scrolling-regions")]
+    fn scroll_region_down(
+        &mut self,
+        region: std::ops::Range<u16>,
+        scroll_by: u16,
+    ) -> io::Result<()> {
+        let width: usize = self.buffer.area.width.into();
+        let cell_region_start = width * region.start.min(self.buffer.area.height) as usize;
+        let cell_region_end = width * region.end.min(self.buffer.area.height) as usize;
+        let cell_region_len = cell_region_end - cell_region_start;
+        let cells_to_scroll_by = width * scroll_by as usize;
+
+        if cells_to_scroll_by >= cell_region_len {
+            // The scroll amount is large enough to clear the whole region.
+            self.buffer.content[cell_region_start..cell_region_end].fill_with(Default::default);
+        } else {
+            // Scroll up by rotating, then filling in the top with empty cells.
+            self.buffer.content[cell_region_start..cell_region_end]
+                .rotate_right(cells_to_scroll_by);
+            self.buffer.content[cell_region_start..cell_region_start + cells_to_scroll_by]
+                .fill_with(Default::default);
+        }
+        Ok(())
+    }
+}
+
+/// 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 +465,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),
             }
@@ -286,12 +479,12 @@ mod tests {
 
     #[test]
     fn buffer_view_with_overwrites() {
-        let multi_byte_char = "👨‍👩‍👧‍👦"; // renders 8 wide
+        let multi_byte_char = "👨‍👩‍👧‍👦"; // renders 2 wide
         let buffer = Buffer::with_lines([multi_byte_char]);
         assert_eq!(
             buffer_view(&buffer),
             format!(
-                r#""{multi_byte_char}" Hidden by multi-width symbols: [(1, " "), (2, " "), (3, " "), (4, " "), (5, " "), (6, " "), (7, " ")]
+                r#""{multi_byte_char}" Hidden by multi-width symbols: [(1, " ")]
 "#,
             )
         );
@@ -323,6 +516,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);
@@ -385,8 +585,7 @@ mod tests {
 
     #[test]
     fn clear_region_all() {
-        let mut backend = TestBackend::new(10, 5);
-        backend.buffer = Buffer::with_lines([
+        let mut backend = TestBackend::with_lines([
             "aaaaaaaaaa",
             "aaaaaaaaaa",
             "aaaaaaaaaa",
@@ -406,8 +605,7 @@ mod tests {
 
     #[test]
     fn clear_region_after_cursor() {
-        let mut backend = TestBackend::new(10, 5);
-        backend.buffer = Buffer::with_lines([
+        let mut backend = TestBackend::with_lines([
             "aaaaaaaaaa",
             "aaaaaaaaaa",
             "aaaaaaaaaa",
@@ -430,8 +628,7 @@ mod tests {
 
     #[test]
     fn clear_region_before_cursor() {
-        let mut backend = TestBackend::new(10, 5);
-        backend.buffer = Buffer::with_lines([
+        let mut backend = TestBackend::with_lines([
             "aaaaaaaaaa",
             "aaaaaaaaaa",
             "aaaaaaaaaa",
@@ -454,8 +651,7 @@ mod tests {
 
     #[test]
     fn clear_region_current_line() {
-        let mut backend = TestBackend::new(10, 5);
-        backend.buffer = Buffer::with_lines([
+        let mut backend = TestBackend::with_lines([
             "aaaaaaaaaa",
             "aaaaaaaaaa",
             "aaaaaaaaaa",
@@ -478,8 +674,7 @@ mod tests {
 
     #[test]
     fn clear_region_until_new_line() {
-        let mut backend = TestBackend::new(10, 5);
-        backend.buffer = Buffer::with_lines([
+        let mut backend = TestBackend::with_lines([
             "aaaaaaaaaa",
             "aaaaaaaaaa",
             "aaaaaaaaaa",
@@ -502,8 +697,7 @@ mod tests {
 
     #[test]
     fn append_lines_not_at_last_line() {
-        let mut backend = TestBackend::new(10, 5);
-        backend.buffer = Buffer::with_lines([
+        let mut backend = TestBackend::with_lines([
             "aaaaaaaaaa",
             "bbbbbbbbbb",
             "cccccccccc",
@@ -536,12 +730,12 @@ mod tests {
             "dddddddddd",
             "eeeeeeeeee",
         ]);
+        backend.assert_scrollback_empty();
     }
 
     #[test]
     fn append_lines_at_last_line() {
-        let mut backend = TestBackend::new(10, 5);
-        backend.buffer = Buffer::with_lines([
+        let mut backend = TestBackend::with_lines([
             "aaaaaaaaaa",
             "bbbbbbbbbb",
             "cccccccccc",
@@ -557,13 +751,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
@@ -572,8 +767,7 @@ mod tests {
 
     #[test]
     fn append_multiple_lines_not_at_last_line() {
-        let mut backend = TestBackend::new(10, 5);
-        backend.buffer = Buffer::with_lines([
+        let mut backend = TestBackend::with_lines([
             "aaaaaaaaaa",
             "bbbbbbbbbb",
             "cccccccccc",
@@ -597,12 +791,12 @@ mod tests {
             "dddddddddd",
             "eeeeeeeeee",
         ]);
+        backend.assert_scrollback_empty();
     }
 
     #[test]
     fn append_multiple_lines_past_last_line() {
-        let mut backend = TestBackend::new(10, 5);
-        backend.buffer = Buffer::with_lines([
+        let mut backend = TestBackend::with_lines([
             "aaaaaaaaaa",
             "bbbbbbbbbb",
             "cccccccccc",
@@ -624,12 +818,12 @@ mod tests {
             "          ",
             "          ",
         ]);
+        backend.assert_scrollback_lines(["aaaaaaaaaa", "bbbbbbbbbb"]);
     }
 
     #[test]
     fn append_multiple_lines_where_cursor_at_end_appends_height_lines() {
-        let mut backend = TestBackend::new(10, 5);
-        backend.buffer = Buffer::with_lines([
+        let mut backend = TestBackend::with_lines([
             "aaaaaaaaaa",
             "bbbbbbbbbb",
             "cccccccccc",
@@ -651,12 +845,18 @@ mod tests {
             "          ",
             "          ",
         ]);
+        backend.assert_scrollback_lines([
+            "aaaaaaaaaa",
+            "bbbbbbbbbb",
+            "cccccccccc",
+            "dddddddddd",
+            "eeeeeeeeee",
+        ]);
     }
 
     #[test]
     fn append_multiple_lines_where_cursor_appends_height_lines() {
-        let mut backend = TestBackend::new(10, 5);
-        backend.buffer = Buffer::with_lines([
+        let mut backend = TestBackend::with_lines([
             "aaaaaaaaaa",
             "bbbbbbbbbb",
             "cccccccccc",
@@ -676,6 +876,114 @@ 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::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]
@@ -689,4 +997,81 @@ mod tests {
         let mut backend = TestBackend::new(10, 2);
         backend.flush().unwrap();
     }
+
+    #[cfg(feature = "scrolling-regions")]
+    mod scrolling_regions {
+        use rstest::rstest;
+
+        use super::*;
+
+        const A: &str = "aaaa";
+        const B: &str = "bbbb";
+        const C: &str = "cccc";
+        const D: &str = "dddd";
+        const E: &str = "eeee";
+        const S: &str = "    ";
+
+        #[rstest]
+        #[case([A, B, C, D, E], 0..5, 0, [],                    [A, B, C, D, E])]
+        #[case([A, B, C, D, E], 0..5, 2, [A, B],                [C, D, E, S, S])]
+        #[case([A, B, C, D, E], 0..5, 5, [A, B, C, D, E],       [S, S, S, S, S])]
+        #[case([A, B, C, D, E], 0..5, 7, [A, B, C, D, E, S, S], [S, S, S, S, S])]
+        #[case([A, B, C, D, E], 0..3, 0, [],                    [A, B, C, D, E])]
+        #[case([A, B, C, D, E], 0..3, 2, [A, B],                [C, S, S, D, E])]
+        #[case([A, B, C, D, E], 0..3, 3, [A, B, C],             [S, S, S, D, E])]
+        #[case([A, B, C, D, E], 0..3, 4, [A, B, C, S],          [S, S, S, D, E])]
+        #[case([A, B, C, D, E], 1..4, 0, [],                    [A, B, C, D, E])]
+        #[case([A, B, C, D, E], 1..4, 2, [],                    [A, D, S, S, E])]
+        #[case([A, B, C, D, E], 1..4, 3, [],                    [A, S, S, S, E])]
+        #[case([A, B, C, D, E], 1..4, 4, [],                    [A, S, S, S, E])]
+        #[case([A, B, C, D, E], 0..0, 0, [],                    [A, B, C, D, E])]
+        #[case([A, B, C, D, E], 0..0, 2, [S, S],                [A, B, C, D, E])]
+        #[case([A, B, C, D, E], 2..2, 0, [],                    [A, B, C, D, E])]
+        #[case([A, B, C, D, E], 2..2, 2, [],                    [A, B, C, D, E])]
+        fn scroll_region_up<const L: usize, const M: usize, const N: usize>(
+            #[case] initial_screen: [&'static str; L],
+            #[case] range: std::ops::Range<u16>,
+            #[case] scroll_by: u16,
+            #[case] expected_scrollback: [&'static str; M],
+            #[case] expected_buffer: [&'static str; N],
+        ) {
+            let mut backend = TestBackend::with_lines(initial_screen);
+            backend.scroll_region_up(range, scroll_by).unwrap();
+            if expected_scrollback.is_empty() {
+                backend.assert_scrollback_empty();
+            } else {
+                backend.assert_scrollback_lines(expected_scrollback);
+            }
+            backend.assert_buffer_lines(expected_buffer);
+        }
+
+        #[rstest]
+        #[case([A, B, C, D, E], 0..5, 0, [A, B, C, D, E])]
+        #[case([A, B, C, D, E], 0..5, 2, [S, S, A, B, C])]
+        #[case([A, B, C, D, E], 0..5, 5, [S, S, S, S, S])]
+        #[case([A, B, C, D, E], 0..5, 7, [S, S, S, S, S])]
+        #[case([A, B, C, D, E], 0..3, 0, [A, B, C, D, E])]
+        #[case([A, B, C, D, E], 0..3, 2, [S, S, A, D, E])]
+        #[case([A, B, C, D, E], 0..3, 3, [S, S, S, D, E])]
+        #[case([A, B, C, D, E], 0..3, 4, [S, S, S, D, E])]
+        #[case([A, B, C, D, E], 1..4, 0, [A, B, C, D, E])]
+        #[case([A, B, C, D, E], 1..4, 2, [A, S, S, B, E])]
+        #[case([A, B, C, D, E], 1..4, 3, [A, S, S, S, E])]
+        #[case([A, B, C, D, E], 1..4, 4, [A, S, S, S, E])]
+        #[case([A, B, C, D, E], 0..0, 0, [A, B, C, D, E])]
+        #[case([A, B, C, D, E], 0..0, 2, [A, B, C, D, E])]
+        #[case([A, B, C, D, E], 2..2, 0, [A, B, C, D, E])]
+        #[case([A, B, C, D, E], 2..2, 2, [A, B, C, D, E])]
+        fn scroll_region_down<const M: usize, const N: usize>(
+            #[case] initial_screen: [&'static str; M],
+            #[case] range: std::ops::Range<u16>,
+            #[case] scroll_by: u16,
+            #[case] expected_buffer: [&'static str; N],
+        ) {
+            let mut backend = TestBackend::with_lines(initial_screen);
+            backend.scroll_region_down(range, scroll_by).unwrap();
+            backend.assert_scrollback_empty();
+            backend.assert_buffer_lines(expected_buffer);
+        }
+    }
 }

ratatui-core/src/buffer/assert.rs

@@ -41,7 +41,11 @@ macro_rules! assert_buffer_eq {
 #[allow(deprecated)]
 #[cfg(test)]
 mod tests {
-    use crate::prelude::*;
+    use crate::{
+        buffer::Buffer,
+        layout::Rect,
+        style::{Color, Style},
+    };
 
     #[test]
     fn assert_buffer_eq_does_not_panic_on_equal_buffers() {

ratatui-core/src/buffer/buffer.rs

@@ -6,7 +6,12 @@ use std::{
 use unicode_segmentation::UnicodeSegmentation;
 use unicode_width::UnicodeWidthStr;
 
-use crate::{buffer::Cell, layout::Position, prelude::*};
+use crate::{
+    buffer::Cell,
+    layout::{Position, Rect},
+    style::Style,
+    text::{Line, Span},
+};
 
 /// A buffer that maps to the desired content of the terminal after the draw call
 ///
@@ -18,7 +23,7 @@ use crate::{buffer::Cell, layout::Position, prelude::*};
 /// # Examples:
 ///
 /// ```
-/// use ratatui::{
+/// use ratatui_core::{
 ///     buffer::{Buffer, Cell},
 ///     layout::{Position, Rect},
 ///     style::{Color, Style},
@@ -163,7 +168,11 @@ impl Buffer {
     /// # Examples
     ///
     /// ```rust
-    /// # use ratatui::{prelude::*, buffer::Cell, layout::Position};
+    /// use ratatui_core::{
+    ///     buffer::{Buffer, Cell},
+    ///     layout::{Position, Rect},
+    /// };
+    ///
     /// let mut buffer = Buffer::empty(Rect::new(0, 0, 10, 10));
     ///
     /// assert_eq!(buffer.cell(Position::new(0, 0)), Some(&Cell::default()));
@@ -190,7 +199,11 @@ impl Buffer {
     /// # Examples
     ///
     /// ```rust
-    /// # use ratatui::{prelude::*, buffer::Cell, layout::Position};
+    /// use ratatui_core::{
+    ///     buffer::{Buffer, Cell},
+    ///     layout::{Position, Rect},
+    ///     style::{Color, Style},
+    /// };
     /// let mut buffer = Buffer::empty(Rect::new(0, 0, 10, 10));
     ///
     /// if let Some(cell) = buffer.cell_mut(Position::new(0, 0)) {
@@ -214,7 +227,8 @@ impl Buffer {
     /// # Examples
     ///
     /// ```
-    /// # use ratatui::prelude::*;
+    /// use ratatui_core::{buffer::Buffer, layout::Rect};
+    ///
     /// let buffer = Buffer::empty(Rect::new(200, 100, 10, 10));
     /// // Global coordinates to the top corner of this buffer's area
     /// assert_eq!(buffer.index_of(200, 100), 0);
@@ -225,7 +239,8 @@ impl Buffer {
     /// Panics when given an coordinate that is outside of this Buffer's area.
     ///
     /// ```should_panic
-    /// # use ratatui::prelude::*;
+    /// use ratatui_core::{buffer::Buffer, layout::Rect};
+    ///
     /// let buffer = Buffer::empty(Rect::new(200, 100, 10, 10));
     /// // Top coordinate is outside of the buffer in global coordinate space, as the Buffer's area
     /// // starts at (200, 100).
@@ -246,7 +261,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;
@@ -254,9 +269,10 @@ impl Buffer {
             return None;
         }
         // remove offset
-        let y = position.y - self.area.y;
-        let x = position.x - self.area.x;
-        Some((y * self.area.width + x) as usize)
+        let y = (position.y - self.area.y) as usize;
+        let x = (position.x - self.area.x) as usize;
+        let width = self.area.width as usize;
+        Some(y * width + x)
     }
 
     /// Returns the (global) coordinates of a cell given its index
@@ -266,7 +282,8 @@ impl Buffer {
     /// # Examples
     ///
     /// ```
-    /// # use ratatui::prelude::*;
+    /// use ratatui_core::{buffer::Buffer, layout::Rect};
+    ///
     /// let rect = Rect::new(200, 100, 10, 10);
     /// let buffer = Buffer::empty(rect);
     /// assert_eq!(buffer.pos_of(0), (200, 100));
@@ -278,22 +295,25 @@ impl Buffer {
     /// Panics when given an index that is outside the Buffer's content.
     ///
     /// ```should_panic
-    /// # use ratatui::prelude::*;
+    /// use ratatui_core::{buffer::Buffer, layout::Rect};
+    ///
     /// let rect = Rect::new(0, 0, 10, 10); // 100 cells in total
     /// let buffer = Buffer::empty(rect);
     /// // Index 100 is the 101th cell, which lies outside of the area of this Buffer.
     /// buffer.pos_of(100); // Panics
     /// ```
     #[must_use]
-    pub fn pos_of(&self, i: usize) -> (u16, u16) {
+    pub fn pos_of(&self, index: usize) -> (u16, u16) {
         debug_assert!(
-            i < self.content.len(),
-            "Trying to get the coords of a cell outside the buffer: i={i} len={}",
+            index < self.content.len(),
+            "Trying to get the coords of a cell outside the buffer: i={index} len={}",
             self.content.len()
         );
+        let x = index % self.area.width as usize + self.area.x as usize;
+        let y = index / self.area.width as usize + self.area.y as usize;
         (
-            self.area.x + (i as u16) % self.area.width,
-            self.area.y + (i as u16) / self.area.width,
+            u16::try_from(x).expect("x overflow. This should never happen as area.width is u16"),
+            u16::try_from(y).expect("y overflow. This should never happen as area.height is u16"),
         )
     }
 
@@ -325,7 +345,7 @@ impl Buffer {
         let max_width = max_width.try_into().unwrap_or(u16::MAX);
         let mut remaining_width = self.area.right().saturating_sub(x).min(max_width);
         let graphemes = UnicodeSegmentation::graphemes(string.as_ref(), true)
-            .filter(|symbol| !symbol.contains(|char: char| char.is_control()))
+            .filter(|symbol| !symbol.contains(char::is_control))
             .map(|symbol| (symbol, symbol.width() as u16))
             .filter(|(_symbol, width)| *width > 0)
             .map_while(|(symbol, width)| {
@@ -377,6 +397,8 @@ impl Buffer {
     ///
     /// `style` accepts any type that is convertible to [`Style`] (e.g. [`Style`], [`Color`], or
     /// your own type that implements [`Into<Style>`]).
+    ///
+    /// [`Color`]: crate::style::Color
     pub fn set_style<S: Into<Style>>(&mut self, area: Rect, style: S) {
         let style = style.into();
         let area = self.area.intersection(area);
@@ -504,7 +526,11 @@ impl<P: Into<Position>> Index<P> for Buffer {
     /// # Examples
     ///
     /// ```
-    /// # use ratatui::{prelude::*, buffer::Cell, layout::Position};
+    /// use ratatui_core::{
+    ///     buffer::{Buffer, Cell},
+    ///     layout::{Position, Rect},
+    /// };
+    ///
     /// let buf = Buffer::empty(Rect::new(0, 0, 10, 10));
     /// let cell = &buf[(0, 0)];
     /// let cell = &buf[Position::new(0, 0)];
@@ -530,7 +556,11 @@ impl<P: Into<Position>> IndexMut<P> for Buffer {
     /// # Examples
     ///
     /// ```
-    /// # use ratatui::{prelude::*, buffer::Cell, layout::Position};
+    /// use ratatui_core::{
+    ///     buffer::{Buffer, Cell},
+    ///     layout::{Position, Rect},
+    /// };
+    ///
     /// let mut buf = Buffer::empty(Rect::new(0, 0, 10, 10));
     /// buf[(0, 0)].set_symbol("A");
     /// buf[Position::new(0, 0)].set_symbol("B");
@@ -622,6 +652,7 @@ mod tests {
     use rstest::{fixture, rstest};
 
     use super::*;
+    use crate::style::{Color, Modifier, Stylize};
 
     #[test]
     fn debug_empty_buffer() {
@@ -1214,11 +1245,12 @@ mod tests {
     #[case::shrug("🤷", "🤷xxxxx")]
     // Technically this is a (brown) bear, a zero-width joiner and a snowflake
     // As it is joined its a single emoji and should therefore have a width of 2.
-    // It's correctly detected as a single grapheme but it's width is 4 for some reason
-    #[case::polarbear("🐻‍❄️", "🐻‍❄️xxx")]
+    // Prior to unicode-width 0.2, this was incorrectly detected as width 4 for some reason
+    #[case::polarbear("🐻‍❄️", "🐻‍❄️xxxxx")]
     // Technically this is an eye, a zero-width joiner and a speech bubble
     // Both eye and speech bubble include a 'display as emoji' variation selector
-    #[case::eye_speechbubble("👁️‍🗨️", "👁️‍🗨️xxx")]
+    // Prior to unicode-width 0.2, this was incorrectly detected as width 4 for some reason
+    #[case::eye_speechbubble("👁️‍🗨️", "👁️‍🗨️xxxxx")]
     fn renders_emoji(#[case] input: &str, #[case] expected: &str) {
         use unicode_width::UnicodeWidthChar;
 
@@ -1244,4 +1276,24 @@ mod tests {
         let expected = Buffer::with_lines([expected]);
         assert_eq!(buffer, expected);
     }
+
+    /// Regression test for <https://github.com/ratatui/ratatui/issues/1441>
+    ///
+    /// Previously the `pos_of` function would incorrectly cast the index to a u16 value instead of
+    /// using the index as is. This caused incorrect rendering of any buffer with an length > 65535.
+    #[test]
+    fn index_pos_of_u16_max() {
+        let buffer = Buffer::empty(Rect::new(0, 0, 256, 256 + 1));
+        assert_eq!(buffer.index_of(255, 255), 65535);
+        assert_eq!(buffer.pos_of(65535), (255, 255));
+
+        assert_eq!(buffer.index_of(0, 256), 65536);
+        assert_eq!(buffer.pos_of(65536), (0, 256)); // previously (0, 0)
+
+        assert_eq!(buffer.index_of(1, 256), 65537);
+        assert_eq!(buffer.pos_of(65537), (1, 256)); // previously (1, 0)
+
+        assert_eq!(buffer.index_of(255, 256), 65791);
+        assert_eq!(buffer.pos_of(65791), (255, 256)); // previously (255, 0)
+    }
 }

ratatui-core/src/buffer/cell.rs

@@ -1,6 +1,6 @@
 use compact_str::CompactString;
 
-use crate::prelude::*;
+use crate::style::{Color, Modifier, Style};
 
 /// A buffer cell
 #[derive(Debug, Clone, Eq, PartialEq, Hash)]
@@ -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::*;

ratatui-core/src/layout.rs

@@ -1,4 +1,5 @@
 #![warn(clippy::missing_const_for_fn)]
+//! Provides types and traits for working with layout and positioning in the terminal.
 
 mod alignment;
 mod constraint;
@@ -14,8 +15,8 @@ pub use alignment::Alignment;
 pub use constraint::Constraint;
 pub use direction::Direction;
 pub use flex::Flex;
-pub use layout::Layout;
+pub use layout::{Layout, Spacing};
 pub use margin::Margin;
 pub use position::Position;
-pub use rect::*;
+pub use rect::{Columns, Offset, Positions, Rect, Rows};
 pub use size::Size;