perf: add backend diff comparison benchmark for crossterm

https://crates.io/crates/anstyle makes it possible to define colors in
an interoperable way. This makes it possible for applications to easily
load colors from a variety of formats.

This is gated by the anstyle feature flag which is disabled by default.

---------

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

.cargo/config.toml

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

.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
@@ -21,73 +20,88 @@ concurrency:
 # 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
       - uses: dtolnay/rust-toolchain@nightly
-        with:
-          components: rustfmt
-      - run: cargo +nightly fmt --all --check
+        with: { components: rustfmt }
+      - run: cargo xtask lint-formatting
 
-  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
 
+  # 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
       - uses: Swatinem/rust-cache@v2
       - uses: bnjbvr/cargo-machete@v0.7.0
 
-  clippy:
+  # Run cargo clippy.
+  lint-clippy:
+    name: Check Clippy
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
       - uses: dtolnay/rust-toolchain@stable
-        with:
-          components: clippy
-      - uses: taiki-e/install-action@cargo-make
+        with: { components: clippy }
       - uses: Swatinem/rust-cache@v2
-      - run: cargo make clippy
+      - run: cargo xtask lint-clippy
 
-  markdownlint:
+  # 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@v17
+      - 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
       - uses: dtolnay/rust-toolchain@stable
         with:
           components: llvm-tools
-      - 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
-      - run: cargo make coverage
-      - 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:
@@ -99,13 +113,23 @@ jobs:
       - uses: dtolnay/rust-toolchain@master
         with:
           toolchain: ${{ matrix.toolchain }}
-      - uses: taiki-e/install-action@cargo-make
       - uses: Swatinem/rust-cache@v2
-      - run: cargo make check
-        env:
-          RUST_BACKTRACE: full
+      - run: cargo xtask check
 
+  # 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
+      - uses: Swatinem/rust-cache@v2
+      - uses: taiki-e/install-action@cargo-rdme
+      - run: cargo xtask check-readme
+
+  # 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
@@ -114,47 +138,48 @@ jobs:
       - uses: dtolnay/rust-toolchain@nightly
       - uses: dtolnay/install@cargo-docs-rs
       - uses: Swatinem/rust-cache@v2
-      # Run cargo rustdoc with the same options that would be used by docs.rs, taking into account
-      # the package.metadata.docs.rs configured in Cargo.toml.
-      # https://github.com/dtolnay/cargo-docs-rs
-      - run: cargo +nightly docs-rs
+      - run: cargo xtask lint-docs
 
-  test-doc:
-    strategy:
-      fail-fast: false
-      matrix:
-        os: [ubuntu-latest, windows-latest, macos-latest]
-    runs-on: ${{ matrix.os }}
+  # 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: taiki-e/install-action@cargo-make
       - uses: Swatinem/rust-cache@v2
-      - run: cargo make test-doc
-        env:
-          RUST_BACKTRACE: full
+      - run: cargo xtask test-docs
 
-  test:
+  # 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
-      - uses: dtolnay/rust-toolchain@master
-        with:
-          toolchain: ${{ matrix.toolchain }}
-      - uses: taiki-e/install-action@v2
-        with:
-          tool: cargo-make,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 }}

BREAKING-CHANGES.md

@@ -10,6 +10,9 @@ GitHub with a [breaking change] label.
 
 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
@@ -72,6 +75,109 @@ This is a quick summary of the sections below:
   - MSRV is now 1.63.0
   - `List` no longer ignores empty strings
 
+## 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])

CHANGELOG.md

@@ -5175,7 +5175,7 @@ Also, we created various tutorials and walkthroughs in [Ratatui Book](https://gi
 
   ```text
   The `Spans` type (plural, not singular) was replaced with a more ergonomic `Line` type
-  in Ratatui v0.21.0 and marked deprecated byt left for backwards compatibility. This is now
+  in Ratatui v0.21.0 and marked deprecated but left for backwards compatibility. This is now
   removed.
 
   - `Line` replaces `Spans`

CONTRIBUTING.md

@@ -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,17 +71,17 @@ 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/ratatui.git
 cd ratatui
-cargo make build
+cargo xtask build
 ```
 
 ### Tests
@@ -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`

Cargo.toml

@@ -1,8 +1,19 @@
-[package]
-name = "ratatui"
-version = "0.29.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/ratatui"
 homepage = "https://ratatui.rs"
@@ -10,72 +21,44 @@ 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"
 
-[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 }
-indoc = "2"
-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"] }
+[workspace.dependencies]
+bitflags = "2.6.0"
+color-eyre = "0.6.3"
+crossterm = "0.28.1"
+document-features = "0.2.7"
+indoc = "2.0.5"
+instability = "0.3.5"
+itertools = "0.13.0"
+pretty_assertions = "1.4.1"
+ratatui = { path = "ratatui", version = "0.30.0-alpha.0" }
+ratatui-core = { path = "ratatui-core", version = "0.1.0-alpha.0" }
+ratatui-crossterm = { path = "ratatui-crossterm", version = "0.1.0-alpha.0" }
+ratatui-termion = { path = "ratatui-termion", version = "0.1.0-alpha.0" }
+ratatui-termwiz = { path = "ratatui-termwiz", version = "0.1.0-alpha.0" }
+ratatui-widgets = { path = "ratatui-widgets", version = "0.3.0-alpha.0" }
+rstest = "0.23.0"
+serde = { version = "1.0.216", features = ["derive"] }
+serde_json = "1.0.134"
 strum = { version = "0.26.3", features = ["derive"] }
-termwiz = { version = "0.22.0", optional = true }
-time = { version = "0.3.11", optional = true, features = ["local-offset"] }
-unicode-segmentation = "1.10"
-unicode-truncate = "1"
+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
 unicode-width = "=0.2.0"
+termion = "4.0.0"
 
-[target.'cfg(not(windows))'.dependencies]
-# termion is not supported on Windows
-termion = { version = "4.0.0", optional = true }
+# 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"] }
-fakeit = "1.1"
-font8x8 = "0.3.1"
-futures = "0.3.30"
-indoc = "2"
-octocrab = "0.41.0"
-pretty_assertions = "1.4.0"
-rand = "0.8.5"
-rand_chacha = "0.3.1"
-rstest = "0.23.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"
@@ -112,275 +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"]
-
-## Use terminal scrolling regions to make some operations less prone to
-## flickering. (i.e. Terminal::insert_before).
-scrolling-regions = []
-
-## 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",
-  "unstable-backend-writer",
-]
-
-## Enables the [`Paragraph::line_count`](widgets::Paragraph::line_count)
-## [`Paragraph::line_width`](widgets::Paragraph::line_width) methods
-## which are experimental and may change in the future.
-## See [Issue 293](https://github.com/ratatui/ratatui/issues/293) for more details.
-unstable-rendered-line-info = []
-
-## Enables the [`WidgetRef`](widgets::WidgetRef) and [`StatefulWidgetRef`](widgets::StatefulWidgetRef) traits which are experimental and may change in
-## the future.
-unstable-widget-ref = []
-
-## Enables getting access to backends' writers.
-unstable-backend-writer = []
-
-[package.metadata.docs.rs]
-all-features = true
-# see https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html
-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"]
-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
-
-[[example]]
-name = "widget_impl"
-required-features = ["crossterm", "unstable-widget-ref"]
-doc-scrape-examples = true
-
-[[test]]
-name = "state_serde"
-required-features = ["serde"]

Makefile.toml

@@ -1,154 +0,0 @@
-# configuration for https://github.com/sagiegurari/cargo-make
-
-[config]
-skip_core_tasks = true
-
-[env]
-# all features except the backend ones
-NON_BACKEND_FEATURES = "all-widgets,macros,serde"
-
-[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"]
-
-[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",
-  "--all-features",
-  "--",
-  "-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", "--all-features"]
-
-[tasks.build]
-description = "Compile the project"
-command = "cargo"
-args = ["build", "--all-targets", "--all-features"]
-
-[tasks.clippy]
-description = "Run Clippy for linting"
-command = "cargo"
-args = [
-  "clippy",
-  "--all-targets",
-  "--all-features",
-  "--tests",
-  "--benches",
-  "--",
-  "-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", "--all-features"]
-
-[tasks.test-doc]
-description = "Run documentation tests"
-command = "cargo"
-args = ["test", "--doc", "--all-features"]
-
-[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",
-  "${NON_BACKEND_FEATURES},${@}",
-]
-
-[tasks.coverage]
-description = "Generate code coverage report"
-command = "cargo"
-args = [
-  "llvm-cov",
-  "--lcov",
-  "--output-path",
-  "target/lcov.info",
-  "--all-features",
-]
-
-[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,326 +1,151 @@
 <details>
 <summary>Table of Contents</summary>
 
-- [Ratatui](#ratatui)
-  - [Quick Start](#quickstart)
-  - [Other documentation](#other-documentation)
-  - [Introduction](#introduction)
-  - [Quickstart](#quickstart)
-    - [Initialize and restore the terminal](#initialize-and-restore-the-terminal)
-    - [Drawing the UI](#drawing-the-ui)
-    - [Handling events](#handling-events)
-  - [Layout](#layout)
-  - [Text and styling](#text-and-styling)
-  - [Status of this fork](#status-of-this-fork)
-  - [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/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]
+Badge]][GitHub Sponsors]<br>
+[Ratatui Website] · [API Docs] · [Widget Examples] · [App Examples] · [Changelog]<br>
+[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.
+[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
 
-Add `ratatui` and `crossterm` as dependencies to your cargo.toml:
+Ratatui has [templates] available to help you get started quickly. You can use the
+[`cargo-generate`] command to create a new project with Ratatui:
 
 ```shell
-cargo add ratatui crossterm
+cargo install --locked cargo-generate
+cargo generate ratatui/templates
 ```
 
-Then you can create a simple "Hello World" application:
+Selecting the Hello World template produces the following application:
 
 ```rust
+use color_eyre::Result;
 use crossterm::event::{self, Event};
-use ratatui::{text::Text, Frame};
+use ratatui::{DefaultTerminal, Frame};
 
-fn main() {
-    let mut terminal = ratatui::init();
-    loop {
-        terminal.draw(draw).expect("failed to draw frame");
-        if matches!(event::read().expect("failed to read event"), Event::Key(_)) {
-            break;
-        }
-    }
-    ratatui::restore();
-}
-
-fn draw(frame: &mut Frame) {
-    let text = Text::raw("Hello World!");
-    frame.render_widget(text, frame.area());
-}
-```
-
-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.
-
-## 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.
-
-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.
-
-## 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.
-
-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]).
-
-Every application built with `ratatui` needs to implement the following steps:
-
-- Initialize the terminal
-- A main loop that:
-  - Draws the UI
-  - Handles input events
-- Restore the terminal state
-
-### Initialize and restore the terminal
-
-The [`Terminal`] type is the main entry point for any Ratatui application. It is generic over a
-a choice of [`Backend`] implementations that each provide functionality to draw frames, clear
-the screen, hide the cursor, etc. There are backend implementations for [Crossterm], [Termion]
-and [Termwiz].
-
-The simplest way to initialize the terminal is to use the [`init`] function which returns a
-[`DefaultTerminal`] instance with the default options, enters the Alternate Screen and Raw mode
-and sets up a panic hook that restores the terminal in case of panic. This instance can then be
-used to draw frames and interact with the terminal state. (The [`DefaultTerminal`] instance is a
-type alias for a terminal with the [`crossterm`] backend.) The [`restore`] function restores the
-terminal to its original state.
-
-```rust
-fn main() -> std::io::Result<()> {
-    let mut terminal = ratatui::init();
-    let result = run(&mut terminal);
+fn main() -> Result<()> {
+    color_eyre::install()?;
+    let terminal = ratatui::init();
+    let result = run(terminal);
     ratatui::restore();
     result
 }
-```
 
-See the [`backend` module] and the [Backends] section of the [Ratatui Website] for more info on
-the alternate screen and raw mode.
-
-### Drawing the UI
-
-Drawing the UI is done by calling the [`Terminal::draw`] method on the terminal instance. This
-method takes a closure that is called with a [`Frame`] instance. 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.
-
-The closure passed to the [`Terminal::draw`] method should handle the rendering of a full frame.
-
-```rust
-use ratatui::{Frame, widgets::Paragraph};
-
-fn run(terminal: &mut ratatui::DefaultTerminal) -> std::io::Result<()> {
+fn run(mut terminal: DefaultTerminal) -> Result<()> {
     loop {
-        terminal.draw(|frame| draw(frame))?;
-        if handle_events()? {
+        terminal.draw(render)?;
+        if matches!(event::read()?, Event::Key(_)) {
             break Ok(());
         }
     }
 }
 
-fn draw(frame: &mut Frame) {
-    let text = Paragraph::new("Hello World!");
-    frame.render_widget(text, frame.area());
+fn render(frame: &mut Frame) {
+    frame.render_widget("hello world", frame.area());
 }
 ```
 
-### Handling events
+See the [documentation](#documentation) for more examples and tutorials.
 
-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.
+## Documentation
 
-```rust
-use crossterm::event::{self, Event, KeyCode, KeyEvent, KeyEventKind};
+- [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.
+- [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.
 
-fn handle_events() -> std::io::Result<bool> {
-    match event::read()? {
-        Event::Key(key) if key.kind == KeyEventKind::Press => match key.code {
-            KeyCode::Char('q') => return Ok(true),
-            // handle other key events
-            _ => {}
-        },
-        // handle other events
-        _ => {}
-    }
-    Ok(false)
-}
+You can also watch the [EuroRust 2024 talk] to learn about common concepts in Ratatui and what's
+possible to build with it.
+
+## Templates
+
+If you're looking to get started quickly, you can use one of the available templates from the
+[templates] repository using [`cargo-generate`]:
+
+```shell
+cargo generate ratatui/templates
 ```
 
-## Layout
+## Built with Ratatui
 
-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.
+[![Awesome](https://awesome.re/badge-flat2.svg)][awesome-ratatui]
 
-```rust
-use ratatui::{
-    layout::{Constraint, Layout},
-    widgets::Block,
-    Frame,
-};
+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!
 
-fn draw(frame: &mut Frame) {
-    use Constraint::{Fill, Length, Min};
+## Alternatives
 
-    let vertical = Layout::vertical([Length(1), Min(0),Length(1)]);
-    let [title_area, main_area, status_area] = vertical.areas(frame.area());
-    let horizontal = Layout::horizontal([Fill(1); 2]);
-    let [left_area, right_area] = horizontal.areas(main_area);
+- [Cursive](https://crates.io/crates/cursive) - a ncurses-based TUI library.
+- [iocraft](https://crates.io/crates/iocraft) - a declarative TUI library.
 
-    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);
-}
-```
+## Contributing
 
-Running this example produces the following output:
+[![Discord Badge]][Discord Server] [![Matrix Badge]][Matrix]
+[![Forum Badge]][Forum]<br>
 
-```text
-Title Bar───────────────────────────────────
-┌Left────────────────┐┌Right───────────────┐
-│                    ││                    │
-└────────────────────┘└────────────────────┘
-Status Bar──────────────────────────────────
-```
+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][Forum].
 
-## Text and styling
+We rely on GitHub for [bugs][Report a bug] and [feature requests][Request a Feature].
 
-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.
+Please make sure you read the [contributing](./CONTRIBUTING.md) guidelines before [creating a pull
+request][Create a Pull Request].
 
-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.
+## Acknowledgements
 
-```rust
-use ratatui::{
-    layout::{Constraint, Layout},
-    style::{Color, Modifier, Style, Stylize},
-    text::{Line, Span},
-    widgets::{Block, Paragraph},
-    Frame,
-};
+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.
 
-fn draw(frame: &mut Frame) {
-    let areas = Layout::vertical([Constraint::Length(1); 4]).split(frame.area());
+Special thanks to [Pavel Fomchenkov] for his work in designing an awesome logo for the Ratatui
+project and organization.
 
-    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]);
+## License
 
-    // 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]);
-}
-```
+[MIT](./LICENSE)
 
 [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/templates/
-[Examples]: https://github.com/ratatui/ratatui/tree/main/examples/README.md
+[Forum]: https://forum.ratatui.rs
+[API 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
-[git-cliff]: https://git-cliff.org
-[Conventional Commits]: https://www.conventionalcommits.org
-[API Docs]: https://docs.rs/ratatui
-[Changelog]: https://github.com/ratatui/ratatui/blob/main/CHANGELOG.md
 [Contributing]: https://github.com/ratatui/ratatui/blob/main/CONTRIBUTING.md
-[Breaking Changes]: https://github.com/ratatui/ratatui/blob/main/BREAKING-CHANGES.md
-[FOSDEM 2024 talk]: https://www.youtube.com/watch?v=NU0q6NOLJ20
-[`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
 [Crate Badge]: https://img.shields.io/crates/v/ratatui?logo=rust&style=flat-square&logoColor=E05D44&color=E05D44
@@ -329,51 +154,18 @@ fn draw(frame: &mut Frame) {
 [CI Workflow]: https://github.com/ratatui/ratatui/actions/workflows/ci.yml
 [Codecov Badge]: https://img.shields.io/codecov/c/github/ratatui/ratatui?logo=codecov&style=flat-square&token=BAQ8SOKEST&color=C43AC3&logoColor=C43AC3
 [Codecov]: https://app.codecov.io/gh/ratatui/ratatui
-[Deps.rs Badge]: https://deps.rs/repo/github/ratatui/ratatui/status.svg?style=flat-square
-[Deps.rs]: https://deps.rs/repo/github/ratatui/ratatui
+[Deps.rs Badge]: https://deps.rs/repo/github/ratatui/ratatui/status.svg?path=ratatui&style=flat-square
+[Deps.rs]: 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/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?logo=github&style=flat-square&color=1370D3
-
-<!-- cargo-rdme end -->
-
-## Contributing
-
-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).
-
-We have also recently launched the [Ratatui Forum][Forum], 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 [contributing](./CONTRIBUTING.md) guidelines, especially if you are
-interested in working on a PR or issue opened in the previous repository.
-
-## Built with Ratatui
-
-Ratatui has a number of built-in [widgets](https://docs.rs/ratatui/latest/ratatui/widgets/), as well
-as many contributed by external contributors. Check out the [Showcase](https://ratatui.rs/showcase/)
-section of the website, or the [awesome-ratatui](https://github.com/ratatui/awesome-ratatui) repo
-for a curated list of awesome apps/libraries built with `ratatui`!
-
-## Alternatives
-
-You might want to checkout [Cursive](https://github.com/gyscos/Cursive) for an alternative solution
-to build text user interfaces in Rust.
-
-## Acknowledgments
-
-None of this could be possible without [**Florian Dehau**](https://github.com/fdehau) who originally
-created [tui-rs] which inspired many Rust TUIs.
-
-Special thanks to [**Pavel Fomchenkov**](https://github.com/nawok) for his work in designing **an
-awesome logo** for the ratatui project and ratatui organization.
-
-## License
-
-[MIT](./LICENSE)
+[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

bacon.toml

@@ -8,58 +8,66 @@
 default_job = "check"
 
 [jobs.check]
-command = ["cargo", "check", "--all-features", "--color", "always"]
+command = ["cargo", "check", "--all-features"]
 need_stdout = false
 
 [jobs.check-all]
-command = ["cargo", "check", "--all-targets", "--all-features", "--color", "always"]
+command = ["cargo", "check", "--all-targets", "--all-features"]
 need_stdout = false
 
 [jobs.check-crossterm]
-command = ["cargo", "check", "--color", "always", "--all-targets", "--no-default-features", "--features", "crossterm"]
+command = [
+    "cargo",
+    "check",
+    "--all-targets",
+    "--no-default-features",
+    "--features",
+    "crossterm",
+]
 need_stdout = false
 
 [jobs.check-termion]
-command = ["cargo", "check", "--color", "always", "--all-targets", "--no-default-features", "--features", "termion"]
+command = [
+    "cargo",
+    "check",
+    "--all-targets",
+    "--no-default-features",
+    "--features",
+    "termion",
+]
 need_stdout = false
 
 [jobs.check-termwiz]
-command = ["cargo", "check", "--color", "always", "--all-targets", "--no-default-features", "--features", "termwiz"]
+command = [
+    "cargo",
+    "check",
+    "--all-targets",
+    "--no-default-features",
+    "--features",
+    "termwiz",
+]
 need_stdout = false
 
 [jobs.clippy]
-command = [
-    "cargo", "clippy",
-    "--all-targets",
-    "--color", "always",
-]
+command = ["cargo", "clippy", "--all-targets"]
 need_stdout = false
 
 [jobs.test]
-command = [
-    "cargo", "test",
-    "--all-features",
-    "--color", "always",
-    "--", "--color", "always", # see https://github.com/Canop/bacon/issues/124
-]
+command = ["cargo", "test", "--all-features"]
 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", "test", "--lib", "--all-features"]
 need_stdout = true
 
 [jobs.doc]
 command = [
-    "cargo", "+nightly", "doc",
-    "-Zunstable-options", "-Zrustdoc-scrape-examples",
+    "cargo",
+    "+nightly",
+    "doc",
+    "-Zunstable-options",
+    "-Zrustdoc-scrape-examples",
     "--all-features",
-    "--color", "always",
     "--no-deps",
 ]
 env.RUSTDOCFLAGS = "--cfg docsrs"
@@ -69,10 +77,12 @@ need_stdout = false
 # to the previous job
 [jobs.doc-open]
 command = [
-    "cargo", "+nightly", "doc",
-    "-Zunstable-options", "-Zrustdoc-scrape-examples",
+    "cargo",
+    "+nightly",
+    "doc",
+    "-Zunstable-options",
+    "-Zrustdoc-scrape-examples",
     "--all-features",
-    "--color", "always",
     "--no-deps",
     "--open",
 ]
@@ -82,19 +92,34 @@ 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",
+    "cargo",
+    "llvm-cov",
+    "--lcov",
+    "--output-path",
+    "target/lcov.info",
     "--all-features",
-    "--color", "always",
 ]
 
 [jobs.coverage-unit-tests-only]
 command = [
-    "cargo", "llvm-cov",
-    "--lcov", "--output-path", "target/lcov.info",
+    "cargo",
+    "llvm-cov",
+    "--lcov",
+    "--output-path",
+    "target/lcov.info",
     "--lib",
     "--all-features",
-    "--color", "always",
+]
+
+[jobs.hack]
+command = [
+    "cargo",
+    "hack",
+    "test",
+    "--lib",
+    "--each-feature",
+    # "--all-targets",
+    "--workspace",
 ]
 
 # You may define here keybindings that would be specific to
@@ -102,7 +127,7 @@ command = [
 # 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"

clippy.toml

@@ -1,18 +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/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",
-    "unicode-width",
-]

deny.toml

@@ -9,6 +9,8 @@ allow = [
     "BSD-3-Clause",
     "ISC",
     "MIT",
+    "OpenSSL",
+    "Unicode-3.0",
     "Unicode-DFS-2016",
     "WTFPL",
     "Zlib",
@@ -24,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]
 >
@@ -11,7 +24,7 @@ This folder might use unreleased code. View the examples for the latest release
 >
 > - 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/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
+> - 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.
@@ -23,456 +36,31 @@ This folder might use unreleased code. View the examples for the latest release
 > 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/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/ratatui/blob/images/examples/barchart.gif?raw=true
-[barchart-grouped.gif]: https://github.com/ratatui/ratatui/blob/images/examples/barchart-grouped.gif?raw=true
-[block.gif]: https://github.com/ratatui/ratatui/blob/images/examples/block.gif?raw=true
-[calendar.gif]: https://github.com/ratatui/ratatui/blob/images/examples/calendar.gif?raw=true
-[canvas.gif]: https://github.com/ratatui/ratatui/blob/images/examples/canvas.gif?raw=true
-[chart.gif]: https://github.com/ratatui/ratatui/blob/images/examples/chart.gif?raw=true
-[colors.gif]: https://github.com/ratatui/ratatui/blob/images/examples/colors.gif?raw=true
-[constraint-explorer.gif]: https://github.com/ratatui/ratatui/blob/images/examples/constraint-explorer.gif?raw=true
-[constraints.gif]: https://github.com/ratatui/ratatui/blob/images/examples/constraints.gif?raw=true
-[custom_widget.gif]: https://github.com/ratatui/ratatui/blob/images/examples/custom_widget.gif?raw=true
-[demo.gif]: https://github.com/ratatui/ratatui/blob/images/examples/demo.gif?raw=true
-[demo2.gif]: https://github.com/ratatui/ratatui/blob/images/examples/demo2.gif?raw=true
-[flex.gif]: https://github.com/ratatui/ratatui/blob/images/examples/flex.gif?raw=true
-[gauge.gif]: https://github.com/ratatui/ratatui/blob/images/examples/gauge.gif?raw=true
-[hello_world.gif]: https://github.com/ratatui/ratatui/blob/images/examples/hello_world.gif?raw=true
-[hyperlink.gif]: https://github.com/ratatui/ratatui/blob/images/examples/hyperlink.gif?raw=true
-[inline.gif]: https://github.com/ratatui/ratatui/blob/images/examples/inline.gif?raw=true
-[layout.gif]: https://github.com/ratatui/ratatui/blob/images/examples/layout.gif?raw=true
-[list.gif]: https://github.com/ratatui/ratatui/blob/images/examples/list.gif?raw=true
-[line_gauge.gif]: https://github.com/ratatui/ratatui/blob/images/examples/line_gauge.gif?raw=true
-[minimal.gif]: https://github.com/ratatui/ratatui/blob/images/examples/minimal.gif?raw=true
-[modifiers.gif]: https://github.com/ratatui/ratatui/blob/images/examples/modifiers.gif?raw=true
-[panic.gif]: https://github.com/ratatui/ratatui/blob/images/examples/panic.gif?raw=true
-[paragraph.gif]: https://github.com/ratatui/ratatui/blob/images/examples/paragraph.gif?raw=true
-[popup.gif]: https://github.com/ratatui/ratatui/blob/images/examples/popup.gif?raw=true
-[ratatui-logo.gif]: https://github.com/ratatui/ratatui/blob/images/examples/ratatui-logo.gif?raw=true
-[scrollbar.gif]: https://github.com/ratatui/ratatui/blob/images/examples/scrollbar.gif?raw=true
-[sparkline.gif]: https://github.com/ratatui/ratatui/blob/images/examples/sparkline.gif?raw=true
-[table.gif]:  https://vhs.charm.sh/vhs-6njXBytDf0rwPufUtmSSpI.gif
-[tabs.gif]: https://github.com/ratatui/ratatui/blob/images/examples/tabs.gif?raw=true
-[tracing.gif]: https://github.com/ratatui/ratatui/blob/images/examples/tracing.gif?raw=true
-[user_input.gif]: https://github.com/ratatui/ratatui/blob/images/examples/user_input.gif?raw=true
-
-[alpha version of Ratatui]: https://crates.io/crates/ratatui/versions
-[BREAKING-CHANGES.md]: https://github.com/ratatui/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.42.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)
@@ -34,11 +32,10 @@ use std::{
     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::{
     buffer::Buffer,
@@ -49,29 +46,17 @@ use ratatui::{
     widgets::{Block, HighlightSpacing, Row, StatefulWidget, Table, TableState, Widget},
     DefaultTerminal, Frame,
 };
+use tokio_stream::StreamExt;
 
 #[tokio::main]
 async fn main() -> Result<()> {
     color_eyre::install()?;
-    init_octocrab()?;
     let terminal = ratatui::init();
     let app_result = App::default().run(terminal).await;
     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,

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

@@ -1,18 +1,13 @@
-//! # [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/ratatui
-//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
-//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md
-
+/// 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},
@@ -29,6 +24,7 @@ use ratatui::{
     layout::{Constraint, Layout, Position, Rect},
     style::{Color, Stylize},
     symbols::Marker,
+    text::Text,
     widgets::{
         canvas::{Canvas, Circle, Map, MapResolution, Points, Rectangle},
         Block, Widget,
@@ -54,7 +50,6 @@ struct App {
     playground: Rect,
     vx: f64,
     vy: f64,
-    tick_count: u64,
     marker: Marker,
     points: Vec<Position>,
     is_drawing: bool,
@@ -75,7 +70,6 @@ impl App {
             playground: Rect::new(10, 10, 200, 100),
             vx: 1.0,
             vy: 1.0,
-            tick_count: 0,
             marker: Marker::Dot,
             points: vec![],
             is_drawing: false,
@@ -114,6 +108,15 @@ impl App {
             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,
+                };
+            }
             _ => {}
         }
     }
@@ -130,17 +133,6 @@ impl App {
     }
 
     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;
@@ -154,18 +146,28 @@ impl App {
         {
             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 vertical = Layout::vertical([Constraint::Percentage(50), Constraint::Percentage(50)]);
-        let [left, right] = horizontal.areas(frame.area());
-        let [draw, map] = vertical.areas(left);
-        let [pong, boxes] = vertical.areas(right);
+        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);

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,18 +1,13 @@
-//! # [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/ratatui
-//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
-//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md
-
+/// 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;

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,20 +1,12 @@
-//! # [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/ratatui
-//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
-//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md
-
-// This example shows all the colors supported by ratatui. It will render a grid of foreground
-// and background colors with their names and indexes.
+//! [`latest`]: https://github.com/ratatui/ratatui/tree/latest
 
 use color_eyre::Result;
 use itertools::Itertools;

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

@@ -15,7 +15,7 @@
 
 use std::{error::Error, time::Duration};
 
-use argh::FromArgs;
+use clap::Parser;
 
 mod app;
 #[cfg(feature = "crossterm")]
@@ -28,28 +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)?;
+    crate::crossterm::run(tick_rate, cli.unicode)?;
     #[cfg(all(not(windows), feature = "termion", not(feature = "crossterm")))]
-    crate::termion::run(tick_rate, cli.enhanced_graphics)?;
+    crate::termion::run(tick_rate, cli.unicode)?;
     #[cfg(all(
         feature = "termwiz",
         not(feature = "crossterm"),
         not(feature = "termion")
     ))]
-    crate::termwiz::run(tick_rate, cli.enhanced_graphics)?;
+    crate::termwiz::run(tick_rate, cli.unicode)?;
     Ok(())
 }

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/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())
     }

examples/apps/demo2/src/tabs/weather.rs

@@ -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/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

@@ -1,26 +1,21 @@
-//! # [Ratatui] `BarChart` example
+//! A Ratatui example that demonstrates how to render weather data using [`BarChart`] widget.
 //!
-//! The latest version of this example is available in the [examples] folder in the repository.
+//! Generates random temperature data for each hour of the day and renders it as a vertical bar.
 //!
-//! 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/ratatui
-//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
-//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md
+//! [`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, Direction, Layout},
+    layout::{Constraint, Layout},
     style::{Color, Style, Stylize},
     text::Line,
-    widgets::{Bar, BarChart, BarGroup, Block},
+    widgets::{Bar, BarChart, BarGroup},
     DefaultTerminal, Frame,
 };
 
@@ -65,17 +60,12 @@ impl App {
     }
 
     fn draw(&self, frame: &mut Frame) {
-        let [title, vertical, horizontal] = Layout::vertical([
-            Constraint::Length(1),
-            Constraint::Fill(1),
-            Constraint::Fill(1),
-        ])
-        .spacing(1)
-        .areas(frame.area());
+        let [title, main] = Layout::vertical([Constraint::Length(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);
+        frame.render_widget("Weather demo".bold().into_centered_line(), title);
+        frame.render_widget(vertical_barchart(&self.temperatures), main);
     }
 }
 
@@ -86,10 +76,8 @@ fn vertical_barchart(temperatures: &[u8]) -> BarChart {
         .enumerate()
         .map(|(hour, value)| vertical_bar(hour, value))
         .collect();
-    let title = Line::from("Weather (Vertical)").centered();
     BarChart::default()
         .data(BarGroup::default().bars(&bars))
-        .block(Block::new().title(title))
         .bar_width(5)
 }
 
@@ -102,32 +90,6 @@ fn vertical_bar(hour: usize, temperature: &u8) -> Bar {
         .value_style(temperature_style(*temperature).reversed())
 }
 
-/// Create a horizontal bar chart from the temperatures data.
-fn horizontal_barchart(temperatures: &[u8]) -> BarChart {
-    let bars: Vec<Bar> = temperatures
-        .iter()
-        .enumerate()
-        .map(|(hour, value)| horizontal_bar(hour, value))
-        .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)
-}
-
-fn horizontal_bar(hour: usize, temperature: &u8) -> Bar {
-    let style = temperature_style(*temperature);
-    Bar::default()
-        .value(u64::from(*temperature))
-        .label(Line::from(format!("{hour:>02}:00")))
-        .text_value(format!("{temperature:>3}°"))
-        .style(style)
-        .value_style(style.reversed())
-}
-
 /// create a yellow to red value based on the value (50-90)
 fn temperature_style(value: u8) -> Style {
     let green = (255.0 * (1.0 - f64::from(value - 50) / 40.0)) as u8;

examples/barchart-grouped.rs

@@ -1,211 +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/ratatui
-//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
-//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md
-
-use std::iter::zip;
-
-use color_eyre::Result;
-use ratatui::{
-    crossterm::event::{self, Event, KeyCode, KeyEventKind},
-    layout::{Constraint, Direction, Layout},
-    style::{Color, Style, Stylize},
-    text::Line,
-    widgets::{Bar, BarChart, BarGroup, Block},
-    DefaultTerminal, Frame,
-};
-
-fn main() -> Result<()> {
-    color_eyre::install()?;
-    let terminal = ratatui::init();
-    let app_result = App::new().run(terminal);
-    ratatui::restore();
-    app_result
-}
-
-const COMPANY_COUNT: usize = 3;
-const PERIOD_COUNT: usize = 4;
-
-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,
-}
-
-impl App {
-    const fn new() -> Self {
-        Self {
-            should_exit: false,
-            companies: fake_companies(),
-            revenues: fake_revenues(),
-        }
-    }
-
-    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) {
-        use Constraint::{Fill, Length, Min};
-        let vertical = Layout::vertical([Length(1), Fill(1), Min(20)]).spacing(1);
-        let [title, top, bottom] = vertical.areas(frame.area());
-
-        frame.render_widget("Grouped Barchart".bold().into_centered_line(), title);
-        frame.render_widget(self.vertical_revenue_barchart(), top);
-        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 mut barchart = BarChart::default()
-            .block(Block::new().title(Line::from("Company revenues (Vertical)").centered()))
-            .bar_gap(0)
-            .bar_width(6)
-            .group_gap(2);
-
-        for group in self
-            .revenues
-            .iter()
-            .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))
-    }
-}

examples/block.rs

@@ -1,186 +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/ratatui
-//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
-//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md
-
-use color_eyre::Result;
-use ratatui::{
-    crossterm::event::{self, Event, KeyCode, KeyEventKind},
-    layout::{Alignment, Constraint, Layout, Rect},
-    style::{Style, Stylize},
-    text::Line,
-    widgets::{Block, BorderType, Borders, Padding, Paragraph, Wrap},
-    DefaultTerminal, Frame,
-};
-
-fn main() -> Result<()> {
-    color_eyre::install()?;
-    let terminal = ratatui::init();
-    let result = run(terminal);
-    ratatui::restore();
-    result
-}
-
-fn run(mut terminal: DefaultTerminal) -> Result<()> {
-    loop {
-        terminal.draw(draw)?;
-        if let Event::Key(key) = event::read()? {
-            if key.kind == KeyEventKind::Press && key.code == KeyCode::Char('q') {
-                break Ok(());
-            }
-        }
-    }
-}
-
-fn draw(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();
-    (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);
-}
-
-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(Line::from("top left").left_aligned())
-        .title(Line::from("top center").centered())
-        .title(Line::from("top right").right_aligned())
-        .title_bottom(Line::from("bottom left").left_aligned())
-        .title_bottom(Line::from("bottom center").centered())
-        .title_bottom(Line::from("bottom right").right_aligned());
-    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,249 +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/ratatui
-//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
-//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md
-
-use color_eyre::Result;
-use ratatui::{
-    crossterm::event::{self, Event, KeyCode, KeyEventKind},
-    layout::{Constraint, Layout, Margin},
-    style::{Color, Modifier, Style},
-    widgets::calendar::{CalendarEventStore, DateStyler, Monthly},
-    DefaultTerminal, Frame,
-};
-use time::{Date, Month, OffsetDateTime};
-
-fn main() -> Result<()> {
-    color_eyre::install()?;
-    let terminal = ratatui::init();
-    let result = run(terminal);
-    ratatui::restore();
-    result
-}
-
-fn run(mut terminal: DefaultTerminal) -> Result<()> {
-    loop {
-        terminal.draw(draw)?;
-        if let Event::Key(key) = event::read()? {
-            if key.kind == KeyEventKind::Press && key.code == KeyCode::Char('q') {
-                break Ok(());
-            }
-        }
-    }
-}
-
-fn draw(frame: &mut Frame) {
-    let area = frame.area().inner(Margin {
-        vertical: 1,
-        horizontal: 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(area);
-    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/paragraph.rs

@@ -1,153 +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/ratatui
-//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
-//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md
-
-use std::{
-    io::{self},
-    time::{Duration, Instant},
-};
-
-use color_eyre::Result;
-use ratatui::{
-    buffer::Buffer,
-    crossterm::event::{self, Event, KeyCode, KeyEventKind},
-    layout::{Constraint, Layout, Rect},
-    style::{Color, Stylize},
-    text::{Line, Masked, Span},
-    widgets::{Block, Paragraph, Widget, Wrap},
-    DefaultTerminal,
-};
-
-fn main() -> Result<()> {
-    color_eyre::install()?;
-    let terminal = ratatui::init();
-    let app_result = App::new().run(terminal);
-    ratatui::restore();
-    app_result
-}
-
-#[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, mut terminal: DefaultTerminal) -> Result<()> {
-        while !self.should_exit {
-            terminal.draw(|frame| frame.render_widget(&self, frame.area()))?;
-            self.handle_events()?;
-            if self.last_tick.elapsed() >= Self::TICK_RATE {
-                self.on_tick();
-                self.last_tick = Instant::now();
-            }
-        }
-        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 &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),
-        ]),
-    ]
-}

examples/sparkline.rs

@@ -1,152 +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/ratatui
-//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
-//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md
-
-use std::time::{Duration, Instant};
-
-use color_eyre::Result;
-use rand::{
-    distributions::{Distribution, Uniform},
-    rngs::ThreadRng,
-};
-use ratatui::{
-    crossterm::event::{self, Event, KeyCode},
-    layout::{Constraint, Layout},
-    style::{Color, Style},
-    widgets::{Block, Borders, Sparkline},
-    DefaultTerminal, Frame,
-};
-
-fn main() -> Result<()> {
-    color_eyre::install()?;
-    let terminal = ratatui::init();
-    let app_result = App::new().run(terminal);
-    ratatui::restore();
-    app_result
-}
-
-struct App {
-    signal: RandomSignal,
-    data1: Vec<u64>,
-    data2: Vec<u64>,
-    data3: Vec<u64>,
-}
-
-#[derive(Clone)]
-struct RandomSignal {
-    distribution: Uniform<u64>,
-    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))
-    }
-}
-
-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 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 draw(&self, frame: &mut Frame) {
-        let chunks = Layout::vertical([
-            Constraint::Length(3),
-            Constraint::Length(3),
-            Constraint::Min(0),
-        ])
-        .split(frame.area());
-        let sparkline = Sparkline::default()
-            .block(
-                Block::new()
-                    .borders(Borders::LEFT | Borders::RIGHT)
-                    .title("Data1"),
-            )
-            .data(&self.data1)
-            .style(Style::default().fg(Color::Yellow));
-        frame.render_widget(sparkline, chunks[0]);
-        let sparkline = Sparkline::default()
-            .block(
-                Block::new()
-                    .borders(Borders::LEFT | Borders::RIGHT)
-                    .title("Data2"),
-            )
-            .data(&self.data2)
-            .style(Style::default().bg(Color::Green));
-        frame.render_widget(sparkline, chunks[1]);
-        // Multiline
-        let sparkline = Sparkline::default()
-            .block(
-                Block::new()
-                    .borders(Borders::LEFT | Borders::RIGHT)
-                    .title("Data3"),
-            )
-            .data(&self.data3)
-            .style(Style::default().fg(Color::Red));
-        frame.render_widget(sparkline, chunks[2]);
-    }
-}

examples/tabs.rs

@@ -1,216 +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/ratatui
-//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
-//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md
-
-use color_eyre::Result;
-use ratatui::{
-    buffer::Buffer,
-    crossterm::event::{self, Event, KeyCode, KeyEventKind},
-    layout::{Constraint, Layout, Rect},
-    style::{palette::tailwind, Color, Stylize},
-    symbols,
-    text::Line,
-    widgets::{Block, Padding, Paragraph, Tabs, Widget},
-    DefaultTerminal,
-};
-use strum::{Display, EnumIter, FromRepr, IntoEnumIterator};
-
-fn main() -> Result<()> {
-    color_eyre::install()?;
-    let terminal = ratatui::init();
-    let app_result = App::default().run(terminal);
-    ratatui::restore();
-    app_result
-}
-
-#[derive(Default)]
-struct App {
-    state: AppState,
-    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,
-}
-
-impl App {
-    fn run(mut self, mut terminal: DefaultTerminal) -> Result<()> {
-        while self.state == AppState::Running {
-            terminal.draw(|frame| frame.render_widget(&self, frame.area()))?;
-            self.handle_events()?;
-        }
-        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,
-        }
-    }
-}

ratatui-core/Cargo.toml

@@ -0,0 +1,73 @@
+[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.0"
+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
+ratatui = { workspace = true, features = ["crossterm", "termwiz"] }
+rstest.workspace = true
+serde_json.workspace = true
+
+[target.'cfg(not(windows))'.dev-dependencies]
+ratatui = { workspace = true, features = ["termion"] }
+
+[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

@@ -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,15 +90,15 @@
 //! 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/ratatui/tree/main/examples/README.md
-//! [Backend Comparison]:
-//!     https://ratatui.rs/concepts/backends/comparison/
+//! [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;
 
@@ -109,21 +109,6 @@ use crate::{
     layout::{Position, Size},
 };
 
-#[cfg(all(not(windows), feature = "termion"))]
-mod termion;
-#[cfg(all(not(windows), 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.
     ///

ratatui-core/src/buffer/buffer.rs

@@ -23,7 +23,7 @@ use crate::{
 /// # Examples:
 ///
 /// ```
-/// use ratatui::{
+/// use ratatui_core::{
 ///     buffer::{Buffer, Cell},
 ///     layout::{Position, Rect},
 ///     style::{Color, Style},
@@ -168,7 +168,7 @@ impl Buffer {
     /// # Examples
     ///
     /// ```rust
-    /// use ratatui::{
+    /// use ratatui_core::{
     ///     buffer::{Buffer, Cell},
     ///     layout::{Position, Rect},
     /// };
@@ -199,7 +199,7 @@ impl Buffer {
     /// # Examples
     ///
     /// ```rust
-    /// use ratatui::{
+    /// use ratatui_core::{
     ///     buffer::{Buffer, Cell},
     ///     layout::{Position, Rect},
     ///     style::{Color, Style},
@@ -227,7 +227,7 @@ impl Buffer {
     /// # Examples
     ///
     /// ```
-    /// use ratatui::{buffer::Buffer, layout::Rect};
+    /// 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
@@ -239,7 +239,7 @@ impl Buffer {
     /// Panics when given an coordinate that is outside of this Buffer's area.
     ///
     /// ```should_panic
-    /// use ratatui::{buffer::Buffer, layout::Rect};
+    /// 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
@@ -282,7 +282,7 @@ impl Buffer {
     /// # Examples
     ///
     /// ```
-    /// use ratatui::{buffer::Buffer, layout::Rect};
+    /// use ratatui_core::{buffer::Buffer, layout::Rect};
     ///
     /// let rect = Rect::new(200, 100, 10, 10);
     /// let buffer = Buffer::empty(rect);
@@ -295,7 +295,7 @@ impl Buffer {
     /// Panics when given an index that is outside the Buffer's content.
     ///
     /// ```should_panic
-    /// use ratatui::{buffer::Buffer, layout::Rect};
+    /// use ratatui_core::{buffer::Buffer, layout::Rect};
     ///
     /// let rect = Rect::new(0, 0, 10, 10); // 100 cells in total
     /// let buffer = Buffer::empty(rect);
@@ -303,15 +303,17 @@ impl 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"),
         )
     }
 
@@ -343,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)| {
@@ -524,7 +526,7 @@ impl<P: Into<Position>> Index<P> for Buffer {
     /// # Examples
     ///
     /// ```
-    /// use ratatui::{
+    /// use ratatui_core::{
     ///     buffer::{Buffer, Cell},
     ///     layout::{Position, Rect},
     /// };
@@ -554,7 +556,7 @@ impl<P: Into<Position>> IndexMut<P> for Buffer {
     /// # Examples
     ///
     /// ```
-    /// use ratatui::{
+    /// use ratatui_core::{
     ///     buffer::{Buffer, Cell},
     ///     layout::{Position, Rect},
     /// };
@@ -1274,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/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;

ratatui-core/src/layout/constraint.rs

@@ -26,7 +26,7 @@ use strum::EnumIs;
 /// `Constraint` provides helper methods to create lists of constraints from various input formats.
 ///
 /// ```rust
-/// use ratatui::layout::Constraint;
+/// use ratatui_core::layout::Constraint;
 ///
 /// // Create a layout with specified lengths for each element
 /// let constraints = Constraint::from_lengths([10, 20, 10]);
@@ -224,7 +224,7 @@ impl Constraint {
     /// # Examples
     ///
     /// ```rust
-    /// use ratatui::layout::{Constraint, Layout, Rect};
+    /// use ratatui_core::layout::{Constraint, Layout, Rect};
     ///
     /// # let area = Rect::default();
     /// let constraints = Constraint::from_lengths([1, 2, 3]);
@@ -242,7 +242,7 @@ impl Constraint {
     /// # Examples
     ///
     /// ```rust
-    /// use ratatui::layout::{Constraint, Layout, Rect};
+    /// use ratatui_core::layout::{Constraint, Layout, Rect};
     ///
     /// # let area = Rect::default();
     /// let constraints = Constraint::from_ratios([(1, 4), (1, 2), (1, 4)]);
@@ -260,7 +260,7 @@ impl Constraint {
     /// # Examples
     ///
     /// ```rust
-    /// use ratatui::layout::{Constraint, Layout, Rect};
+    /// use ratatui_core::layout::{Constraint, Layout, Rect};
     ///
     /// # let area = Rect::default();
     /// let constraints = Constraint::from_percentages([25, 50, 25]);
@@ -278,7 +278,7 @@ impl Constraint {
     /// # Examples
     ///
     /// ```rust
-    /// use ratatui::layout::{Constraint, Layout, Rect};
+    /// use ratatui_core::layout::{Constraint, Layout, Rect};
     ///
     /// # let area = Rect::default();
     /// let constraints = Constraint::from_maxes([1, 2, 3]);
@@ -296,7 +296,7 @@ impl Constraint {
     /// # Examples
     ///
     /// ```rust
-    /// use ratatui::layout::{Constraint, Layout, Rect};
+    /// use ratatui_core::layout::{Constraint, Layout, Rect};
     ///
     /// # let area = Rect::default();
     /// let constraints = Constraint::from_mins([1, 2, 3]);
@@ -314,7 +314,7 @@ impl Constraint {
     /// # Examples
     ///
     /// ```rust
-    /// use ratatui::layout::{Constraint, Layout, Rect};
+    /// use ratatui_core::layout::{Constraint, Layout, Rect};
     ///
     /// # let area = Rect::default();
     /// let constraints = Constraint::from_fills([1, 2, 3]);
@@ -337,7 +337,7 @@ impl From<u16> for Constraint {
     /// # Examples
     ///
     /// ```rust
-    /// use ratatui::layout::{Constraint, Direction, Layout, Rect};
+    /// use ratatui_core::layout::{Constraint, Direction, Layout, Rect};
     ///
     /// # let area = Rect::default();
     /// let layout = Layout::new(Direction::Vertical, [1, 2, 3]).split(area);

ratatui-core/src/layout/layout.rs

@@ -114,7 +114,7 @@ impl From<i16> for Spacing {
 /// - a flex option
 /// - a spacing option
 ///
-/// The algorithm used to compute the layout is based on the [`cassowary-rs`] solver. It is a simple
+/// The algorithm used to compute the layout is based on the [`cassowary`] solver. It is a simple
 /// linear solver that can be used to solve linear equations and inequalities. In our case, we
 /// define a set of constraints that are applied to split the provided area into Rects aligned in a
 /// single direction, and the solver computes the values of the position and sizes that satisfy as
@@ -148,20 +148,18 @@ impl From<i16> for Spacing {
 /// # Example
 ///
 /// ```rust
-/// use ratatui::{
+/// use ratatui_core::{
+///     buffer::Buffer,
 ///     layout::{Constraint, Direction, Layout, Rect},
-///     widgets::Paragraph,
-///     Frame,
+///     text::Text,
+///     widgets::Widget,
 /// };
 ///
-/// fn render(frame: &mut Frame, area: Rect) {
-///     let layout = Layout::new(
-///         Direction::Vertical,
-///         [Constraint::Length(5), Constraint::Min(0)],
-///     )
-///     .split(Rect::new(0, 0, 10, 10));
-///     frame.render_widget(Paragraph::new("foo"), layout[0]);
-///     frame.render_widget(Paragraph::new("bar"), layout[1]);
+/// fn render(area: Rect, buf: &mut ratatui_core::buffer::Buffer) {
+///     let layout = Layout::vertical([Constraint::Length(5), Constraint::Min(0)]);
+///     let [left, right] = layout.areas(area);
+///     Text::from("foo").render(left, buf);
+///     Text::from("bar").render(right, buf);
 /// }
 /// ```
 ///
@@ -171,7 +169,7 @@ impl From<i16> for Spacing {
 /// ![layout
 /// example](https://camo.githubusercontent.com/77d22f3313b782a81e5e033ef82814bb48d786d2598699c27f8e757ccee62021/68747470733a2f2f7668732e636861726d2e73682f7668732d315a4e6f4e4c4e6c4c746b4a58706767396e435635652e676966)
 ///
-/// [`cassowary-rs`]: https://crates.io/crates/cassowary
+/// [`cassowary`]: https://crates.io/crates/cassowary
 /// [Examples]: https://github.com/ratatui/ratatui/blob/main/examples/README.md
 #[derive(Debug, Default, Clone, Eq, PartialEq, Hash)]
 pub struct Layout {
@@ -206,7 +204,7 @@ impl Layout {
     /// # Examples
     ///
     /// ```rust
-    /// use ratatui::layout::{Constraint, Direction, Layout};
+    /// use ratatui_core::layout::{Constraint, Direction, Layout};
     ///
     /// Layout::new(
     ///     Direction::Horizontal,
@@ -240,7 +238,7 @@ impl Layout {
     /// # Examples
     ///
     /// ```rust
-    /// use ratatui::layout::{Constraint, Layout};
+    /// use ratatui_core::layout::{Constraint, Layout};
     ///
     /// let layout = Layout::vertical([Constraint::Length(5), Constraint::Min(0)]);
     /// ```
@@ -260,7 +258,7 @@ impl Layout {
     /// # Examples
     ///
     /// ```rust
-    /// use ratatui::layout::{Constraint, Layout};
+    /// use ratatui_core::layout::{Constraint, Layout};
     ///
     /// let layout = Layout::horizontal([Constraint::Length(5), Constraint::Min(0)]);
     /// ```
@@ -289,7 +287,7 @@ impl Layout {
     /// # Examples
     ///
     /// ```rust
-    /// use ratatui::layout::{Constraint, Direction, Layout, Rect};
+    /// use ratatui_core::layout::{Constraint, Direction, Layout, Rect};
     ///
     /// let layout = Layout::default()
     ///     .direction(Direction::Horizontal)
@@ -324,7 +322,7 @@ impl Layout {
     /// # Examples
     ///
     /// ```rust
-    /// use ratatui::layout::{Constraint, Layout, Rect};
+    /// use ratatui_core::layout::{Constraint, Layout, Rect};
     ///
     /// let layout = Layout::default()
     ///     .constraints([
@@ -369,7 +367,7 @@ impl Layout {
     /// # Examples
     ///
     /// ```rust
-    /// use ratatui::layout::{Constraint, Layout, Rect};
+    /// use ratatui_core::layout::{Constraint, Layout, Rect};
     ///
     /// let layout = Layout::default()
     ///     .constraints([Constraint::Min(0)])
@@ -391,7 +389,7 @@ impl Layout {
     /// # Examples
     ///
     /// ```rust
-    /// use ratatui::layout::{Constraint, Layout, Rect};
+    /// use ratatui_core::layout::{Constraint, Layout, Rect};
     ///
     /// let layout = Layout::default()
     ///     .constraints([Constraint::Min(0)])
@@ -410,7 +408,7 @@ impl Layout {
     /// # Examples
     ///
     /// ```rust
-    /// use ratatui::layout::{Constraint, Layout, Rect};
+    /// use ratatui_core::layout::{Constraint, Layout, Rect};
     ///
     /// let layout = Layout::default()
     ///     .constraints([Constraint::Min(0)])
@@ -442,7 +440,7 @@ impl Layout {
     /// In this example, the items in the layout will be aligned to the start.
     ///
     /// ```rust
-    /// use ratatui::layout::{Constraint::*, Flex, Layout};
+    /// use ratatui_core::layout::{Constraint::*, Flex, Layout};
     ///
     /// let layout = Layout::horizontal([Length(20), Length(20), Length(20)]).flex(Flex::Start);
     /// ```
@@ -451,7 +449,7 @@ impl Layout {
     /// space.
     ///
     /// ```rust
-    /// use ratatui::layout::{Constraint::*, Flex, Layout};
+    /// use ratatui_core::layout::{Constraint::*, Flex, Layout};
     ///
     /// let layout = Layout::horizontal([Length(20), Length(20), Length(20)]).flex(Flex::Legacy);
     /// ```
@@ -479,7 +477,7 @@ impl Layout {
     /// In this example, the spacing between each item in the layout is set to 2 cells.
     ///
     /// ```rust
-    /// use ratatui::layout::{Constraint::*, Layout};
+    /// use ratatui_core::layout::{Constraint::*, Layout};
     ///
     /// let layout = Layout::horizontal([Length(20), Length(20), Length(20)]).spacing(2);
     /// ```
@@ -488,7 +486,7 @@ impl Layout {
     /// three segments will have an overlapping border.
     ///
     /// ```rust
-    /// use ratatui::layout::{Constraint::*, Layout};
+    /// use ratatui_core::layout::{Constraint::*, Layout};
     /// let layout = Layout::horizontal([Length(20), Length(20), Length(20)]).spacing(-1);
     /// ```
     #[must_use = "method moves the value of self and returns the modified value"]
@@ -515,16 +513,14 @@ impl Layout {
     /// # Examples
     ///
     /// ```rust
-    /// use ratatui::{layout::{Layout, Constraint}, Frame};
+    /// use ratatui_core::layout::{Layout, Constraint, Rect};
     ///
-    /// # fn render(frame: &mut Frame) {
-    /// let area = frame.area();
+    /// let area = Rect::new(0, 0, 10, 10);
     /// let layout = Layout::vertical([Constraint::Length(1), Constraint::Min(0)]);
     /// let [top, main] = layout.areas(area);
     ///
     /// // or explicitly specify the number of constraints:
     /// let areas = layout.areas::<2>(area);
-    /// # }
     pub fn areas<const N: usize>(&self, area: Rect) -> [Rect; N] {
         let (areas, _) = self.split_with_spacers(area);
         areas.as_ref().try_into().expect("invalid number of rects")
@@ -548,17 +544,16 @@ impl Layout {
     /// # Examples
     ///
     /// ```rust
-    /// use ratatui::{layout::{Layout, Constraint}, Frame};
+    /// use ratatui_core::layout::{Constraint, Layout, Rect};
     ///
-    /// # fn render(frame: &mut Frame) {
-    /// let area = frame.area();
+    /// let area = Rect::new(0, 0, 10, 10);
     /// let layout = Layout::vertical([Constraint::Length(1), Constraint::Min(0)]);
     /// let [top, main] = layout.areas(area);
     /// let [before, inbetween, after] = layout.spacers(area);
     ///
     /// // or explicitly specify the number of constraints:
-    /// let spacers = layout.spacers::<2>(area);
-    /// # }
+    /// let spacers = layout.spacers::<3>(area);
+    /// ```
     pub fn spacers<const N: usize>(&self, area: Rect) -> [Rect; N] {
         let (_, spacers) = self.split_with_spacers(area);
         spacers
@@ -567,7 +562,7 @@ impl Layout {
             .expect("invalid number of rects")
     }
 
-    /// Wrapper function around the cassowary-rs solver to be able to split a given area into
+    /// Wrapper function around the cassowary solver to be able to split a given area into
     /// smaller ones based on the preferred widths or heights and the direction.
     ///
     /// Note that the constraints are applied to the whole area that is to be split, so using
@@ -588,7 +583,7 @@ impl Layout {
     /// # Examples
     ///
     /// ```
-    /// use ratatui::layout::{Constraint, Direction, Layout, Rect};
+    /// use ratatui_core::layout::{Constraint, Direction, Layout, Rect};
     /// let layout = Layout::default()
     ///     .direction(Direction::Vertical)
     ///     .constraints([Constraint::Length(5), Constraint::Min(0)])
@@ -605,7 +600,7 @@ impl Layout {
         self.split_with_spacers(area).0
     }
 
-    /// Wrapper function around the cassowary-rs solver that splits the given area into smaller ones
+    /// Wrapper function around the cassowary solver that splits the given area into smaller ones
     /// based on the preferred widths or heights and the direction, with the ability to include
     /// spacers between the areas.
     ///
@@ -620,7 +615,7 @@ impl Layout {
     /// # Examples
     ///
     /// ```
-    /// use ratatui::layout::{Constraint, Direction, Layout, Rect};
+    /// use ratatui_core::layout::{Constraint, Direction, Layout, Rect};
     ///
     /// let (areas, spacers) = Layout::default()
     ///     .direction(Direction::Vertical)
@@ -1413,8 +1408,12 @@ mod tests {
 
         use crate::{
             buffer::Buffer,
-            layout::{Constraint, Constraint::*, Direction, Flex, Layout, Rect},
-            widgets::{Paragraph, Widget},
+            layout::{
+                Constraint::{self, *},
+                Direction, Flex, Layout, Rect,
+            },
+            text::Text,
+            widgets::Widget,
         };
 
         /// Test that the given constraints applied to the given area result in the expected layout.
@@ -1436,7 +1435,7 @@ mod tests {
             let mut buffer = Buffer::empty(area);
             for (c, &area) in ('a'..='z').take(constraints.len()).zip(layout.iter()) {
                 let s = c.to_string().repeat(area.width as usize);
-                Paragraph::new(s).render(area, &mut buffer);
+                Text::from(s).render(area, &mut buffer);
             }
             assert_eq!(buffer, Buffer::with_lines([expected]));
         }

ratatui-core/src/layout/position.rs

@@ -12,7 +12,7 @@ use crate::layout::Rect;
 /// # Examples
 ///
 /// ```
-/// use ratatui::layout::{Position, Rect};
+/// use ratatui_core::layout::{Position, Rect};
 ///
 /// // the following are all equivalent
 /// let position = Position { x: 1, y: 2 };

ratatui-core/src/layout/rect.rs

@@ -40,6 +40,16 @@ pub struct Offset {
     pub y: i32,
 }
 
+impl Offset {
+    /// A zero offset
+    pub const ZERO: Self = Self { x: 0, y: 0 };
+
+    /// Creates a new `Offset` with the given values.
+    pub const fn new(x: i32, y: i32) -> Self {
+        Self { x, y }
+    }
+}
+
 impl fmt::Display for Rect {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         write!(f, "{}x{}+{}+{}", self.width, self.height, self.x, self.y)
@@ -64,7 +74,7 @@ impl Rect {
     /// # Examples
     ///
     /// ```
-    /// use ratatui::layout::Rect;
+    /// use ratatui_core::layout::Rect;
     ///
     /// let rect = Rect::new(1, 2, 3, 4);
     /// ```
@@ -213,7 +223,7 @@ impl Rect {
     /// # Examples
     ///
     /// ```rust
-    /// use ratatui::layout::{Position, Rect};
+    /// use ratatui_core::layout::{Position, Rect};
     ///
     /// let rect = Rect::new(1, 2, 3, 4);
     /// assert!(rect.contains(Position { x: 1, y: 2 }));
@@ -243,12 +253,11 @@ impl Rect {
     /// # Examples
     ///
     /// ```rust
-    /// use ratatui::{layout::Rect, Frame};
+    /// use ratatui_core::layout::Rect;
     ///
-    /// # fn render(frame: &mut Frame) {
-    /// let area = frame.area();
-    /// let rect = Rect::new(0, 0, 100, 100).clamp(area);
-    /// # }
+    /// let area = Rect::new(0, 0, 100, 100);
+    /// let rect = Rect::new(80, 80, 30, 30).clamp(area);
+    /// assert_eq!(rect, Rect::new(70, 70, 30, 30));
     /// ```
     #[must_use = "method returns the modified value"]
     pub fn clamp(self, other: Self) -> Self {
@@ -264,7 +273,7 @@ impl Rect {
     /// # Example
     ///
     /// ```
-    /// use ratatui::{buffer::Buffer, layout::Rect, text::Line, widgets::Widget};
+    /// use ratatui_core::{buffer::Buffer, layout::Rect, text::Line, widgets::Widget};
     ///
     /// fn render(area: Rect, buf: &mut Buffer) {
     ///     for row in area.rows() {
@@ -281,14 +290,11 @@ impl Rect {
     /// # Example
     ///
     /// ```
-    /// use ratatui::{
-    ///     buffer::Buffer,
-    ///     layout::Rect,
-    ///     widgets::{Block, Borders, Widget},
-    /// };
+    /// use ratatui_core::{buffer::Buffer, layout::Rect, text::Text, widgets::Widget};
+    ///
     /// fn render(area: Rect, buf: &mut Buffer) {
-    ///     if let Some(left) = area.columns().next() {
-    ///         Block::new().borders(Borders::LEFT).render(left, buf);
+    ///     for (i, column) in area.columns().enumerate() {
+    ///         Text::from(format!("{}", i)).render(column, buf);
     ///     }
     /// }
     /// ```
@@ -303,7 +309,7 @@ impl Rect {
     /// # Example
     ///
     /// ```
-    /// use ratatui::{buffer::Buffer, layout::Rect};
+    /// use ratatui_core::{buffer::Buffer, layout::Rect};
     ///
     /// fn render(area: Rect, buf: &mut Buffer) {
     ///     for position in area.positions() {
@@ -320,7 +326,7 @@ impl Rect {
     /// # Examples
     ///
     /// ```
-    /// use ratatui::layout::Rect;
+    /// use ratatui_core::layout::Rect;
     ///
     /// let rect = Rect::new(1, 2, 3, 4);
     /// let position = rect.as_position();

ratatui-core/src/lib.rs

@@ -0,0 +1,48 @@
+// show the feature flags in the generated documentation
+#![cfg_attr(docsrs, feature(doc_cfg))]
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
+#![doc(
+    html_logo_url = "https://raw.githubusercontent.com/ratatui/ratatui/main/assets/logo.png",
+    html_favicon_url = "https://raw.githubusercontent.com/ratatui/ratatui/main/assets/favicon.ico"
+)]
+//! **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
+//! ```
+#![cfg_attr(feature = "document-features", doc = "\n## Features")]
+#![cfg_attr(feature = "document-features", doc = document_features::document_features!())]
+//!
+//! # 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.
+
+pub mod backend;
+pub mod buffer;
+pub mod layout;
+pub mod style;
+pub mod symbols;
+pub mod terminal;
+pub mod text;
+pub mod widgets;

ratatui-core/src/style.rs

@@ -13,7 +13,7 @@
 //! ## Example
 //!
 //! ```
-//! use ratatui::{
+//! use ratatui_core::{
 //!     style::{Color, Modifier, Style},
 //!     text::Span,
 //! };
@@ -43,10 +43,9 @@
 //! ## Example
 //!
 //! ```
-//! use ratatui::{
+//! use ratatui_core::{
 //!     style::{Color, Modifier, Style, Stylize},
-//!     text::Span,
-//!     widgets::Paragraph,
+//!     text::{Span, Text},
 //! };
 //!
 //! assert_eq!(
@@ -61,8 +60,8 @@
 //! );
 //!
 //! assert_eq!(
-//!     Paragraph::new("hello").red().on_blue().bold(),
-//!     Paragraph::new("hello").style(
+//!     Text::from("hello").red().on_blue().bold(),
+//!     Text::from("hello").style(
 //!         Style::default()
 //!             .fg(Color::Red)
 //!             .bg(Color::Blue)
@@ -80,6 +79,8 @@ pub use color::{Color, ParseColorError};
 use stylize::ColorDebugKind;
 pub use stylize::{Styled, Stylize};
 
+#[cfg(feature = "anstyle")]
+mod anstyle;
 mod color;
 pub mod palette;
 #[cfg(feature = "palette")]
@@ -97,7 +98,7 @@ bitflags! {
     /// ## Examples
     ///
     /// ```rust
-    /// use ratatui::style::Modifier;
+    /// use ratatui_core::style::Modifier;
     ///
     /// let m = Modifier::BOLD | Modifier::ITALIC;
     /// ```
@@ -133,7 +134,7 @@ impl fmt::Debug for Modifier {
 /// Style lets you control the main characteristics of the displayed elements.
 ///
 /// ```rust
-/// use ratatui::style::{Color, Modifier, Style};
+/// use ratatui_core::style::{Color, Modifier, Style};
 ///
 /// Style::default()
 ///     .fg(Color::Black)
@@ -144,7 +145,7 @@ impl fmt::Debug for Modifier {
 /// Styles can also be created with a [shorthand notation](crate::style#using-style-shorthands).
 ///
 /// ```rust
-/// use ratatui::style::{Style, Stylize};
+/// use ratatui_core::style::{Style, Stylize};
 ///
 /// Style::new().black().on_green().italic().bold();
 /// ```
@@ -155,7 +156,7 @@ impl fmt::Debug for Modifier {
 /// anywhere that accepts `Into<Style>`.
 ///
 /// ```rust
-/// use ratatui::{
+/// use ratatui_core::{
 ///     style::{Color, Modifier, Style},
 ///     text::Line,
 /// };
@@ -174,7 +175,7 @@ impl fmt::Debug for Modifier {
 /// just S3.
 ///
 /// ```rust
-/// use ratatui::{
+/// use ratatui_core::{
 ///     buffer::Buffer,
 ///     layout::Rect,
 ///     style::{Color, Modifier, Style},
@@ -214,7 +215,7 @@ impl fmt::Debug for Modifier {
 /// reset all properties until that point use [`Style::reset`].
 ///
 /// ```
-/// use ratatui::{
+/// use ratatui_core::{
 ///     buffer::Buffer,
 ///     layout::Rect,
 ///     style::{Color, Modifier, Style},
@@ -245,11 +246,16 @@ impl fmt::Debug for Modifier {
 #[derive(Default, Clone, Copy, Eq, PartialEq, Hash)]
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 pub struct Style {
+    /// The foreground color.
     pub fg: Option<Color>,
+    /// The background color.
     pub bg: Option<Color>,
+    /// The underline color.
     #[cfg(feature = "underline-color")]
     pub underline_color: Option<Color>,
+    /// The modifiers to add.
     pub add_modifier: Modifier,
+    /// The modifiers to remove.
     pub sub_modifier: Modifier,
 }
 
@@ -276,6 +282,7 @@ impl Styled for Style {
 }
 
 impl Style {
+    /// Returns a `Style` with default properties.
     pub const fn new() -> Self {
         Self {
             fg: None,
@@ -304,7 +311,7 @@ impl Style {
     /// ## Examples
     ///
     /// ```rust
-    /// use ratatui::style::{Color, Style};
+    /// use ratatui_core::style::{Color, Style};
     ///
     /// let style = Style::default().fg(Color::Blue);
     /// let diff = Style::default().fg(Color::Red);
@@ -321,7 +328,7 @@ impl Style {
     /// ## Examples
     ///
     /// ```rust
-    /// use ratatui::style::{Color, Style};
+    /// use ratatui_core::style::{Color, Style};
     ///
     /// let style = Style::default().bg(Color::Blue);
     /// let diff = Style::default().bg(Color::Red);
@@ -346,7 +353,7 @@ impl Style {
     /// ## Examples
     ///
     /// ```rust
-    /// use ratatui::style::{Color, Modifier, Style};
+    /// use ratatui_core::style::{Color, Modifier, Style};
     ///
     /// let style = Style::default()
     ///     .underline_color(Color::Blue)
@@ -375,7 +382,7 @@ impl Style {
     /// ## Examples
     ///
     /// ```rust
-    /// use ratatui::style::{Modifier, Style};
+    /// use ratatui_core::style::{Modifier, Style};
     ///
     /// let style = Style::default().add_modifier(Modifier::BOLD);
     /// let diff = Style::default().add_modifier(Modifier::ITALIC);
@@ -397,7 +404,7 @@ impl Style {
     /// ## Examples
     ///
     /// ```rust
-    /// use ratatui::style::{Modifier, Style};
+    /// use ratatui_core::style::{Modifier, Style};
     ///
     /// let style = Style::default().add_modifier(Modifier::BOLD | Modifier::ITALIC);
     /// let diff = Style::default().remove_modifier(Modifier::ITALIC);
@@ -420,7 +427,7 @@ impl Style {
     ///
     /// ## Examples
     /// ```
-    /// use ratatui::style::{Color, Modifier, Style};
+    /// use ratatui_core::style::{Color, Modifier, Style};
     ///
     /// let style_1 = Style::default().fg(Color::Yellow);
     /// let style_2 = Style::default().bg(Color::Red);
@@ -506,7 +513,7 @@ impl From<Color> for Style {
     /// # Example
     ///
     /// ```rust
-    /// use ratatui::style::{Color, Style};
+    /// use ratatui_core::style::{Color, Style};
     ///
     /// let style = Style::from(Color::Red);
     /// ```
@@ -521,7 +528,7 @@ impl From<(Color, Color)> for Style {
     /// # Example
     ///
     /// ```rust
-    /// use ratatui::style::{Color, Style};
+    /// use ratatui_core::style::{Color, Style};
     ///
     /// // red foreground, blue background
     /// let style = Style::from((Color::Red, Color::Blue));
@@ -544,7 +551,7 @@ impl From<Modifier> for Style {
     /// # Example
     ///
     /// ```rust
-    /// use ratatui::style::{Style, Modifier};
+    /// use ratatui_core::style::{Style, Modifier};
     ///
     /// // add bold and italic
     /// let style = Style::from(Modifier::BOLD|Modifier::ITALIC);
@@ -559,7 +566,7 @@ impl From<(Modifier, Modifier)> for Style {
     /// # Example
     ///
     /// ```rust
-    /// use ratatui::style::{Modifier, Style};
+    /// use ratatui_core::style::{Modifier, Style};
     ///
     /// // add bold and italic, remove dim
     /// let style = Style::from((Modifier::BOLD | Modifier::ITALIC, Modifier::DIM));
@@ -579,7 +586,7 @@ impl From<(Color, Modifier)> for Style {
     /// # Example
     ///
     /// ```rust
-    /// use ratatui::style::{Color, Modifier, Style};
+    /// use ratatui_core::style::{Color, Modifier, Style};
     ///
     /// // red foreground, add bold and italic
     /// let style = Style::from((Color::Red, Modifier::BOLD | Modifier::ITALIC));
@@ -597,7 +604,7 @@ impl From<(Color, Color, Modifier)> for Style {
     /// # Example
     ///
     /// ```rust
-    /// use ratatui::style::{Color, Modifier, Style};
+    /// use ratatui_core::style::{Color, Modifier, Style};
     ///
     /// // red foreground, blue background, add bold and italic
     /// let style = Style::from((Color::Red, Color::Blue, Modifier::BOLD | Modifier::ITALIC));
@@ -614,7 +621,7 @@ impl From<(Color, Color, Modifier, Modifier)> for Style {
     /// # Example
     ///
     /// ```rust
-    /// use ratatui::style::{Color, Modifier, Style};
+    /// use ratatui_core::style::{Color, Modifier, Style};
     ///
     /// // red foreground, blue background, add bold and italic, remove dim
     /// let style = Style::from((

ratatui-core/src/style/anstyle.rs

@@ -0,0 +1,331 @@
+//! This module contains conversion functions for styles from the `anstyle` crate.
+use anstyle::{Ansi256Color, AnsiColor, Effects, RgbColor};
+use thiserror::Error;
+
+use super::{Color, Modifier, Style};
+
+/// Error type for converting between `anstyle` colors and `Color`
+#[derive(Debug, Error, PartialEq, Eq)]
+pub enum TryFromColorError {
+    #[error("cannot convert Ratatui Color to an Ansi256Color as it is not an indexed color")]
+    Ansi256,
+    #[error("cannot convert Ratatui Color to AnsiColor as it is not a 4-bit color")]
+    Ansi,
+    #[error("cannot convert Ratatui Color to RgbColor as it is not an RGB color")]
+    RgbColor,
+}
+
+impl From<Ansi256Color> for Color {
+    fn from(color: Ansi256Color) -> Self {
+        Self::Indexed(color.index())
+    }
+}
+
+impl TryFrom<Color> for Ansi256Color {
+    type Error = TryFromColorError;
+
+    fn try_from(color: Color) -> Result<Self, Self::Error> {
+        match color {
+            Color::Indexed(index) => Ok(Self(index)),
+            _ => Err(TryFromColorError::Ansi256),
+        }
+    }
+}
+
+impl From<AnsiColor> for Color {
+    fn from(value: AnsiColor) -> Self {
+        match value {
+            AnsiColor::Black => Self::Black,
+            AnsiColor::Red => Self::Red,
+            AnsiColor::Green => Self::Green,
+            AnsiColor::Yellow => Self::Yellow,
+            AnsiColor::Blue => Self::Blue,
+            AnsiColor::Magenta => Self::Magenta,
+            AnsiColor::Cyan => Self::Cyan,
+            AnsiColor::White => Self::Gray,
+            AnsiColor::BrightBlack => Self::DarkGray,
+            AnsiColor::BrightRed => Self::LightRed,
+            AnsiColor::BrightGreen => Self::LightGreen,
+            AnsiColor::BrightYellow => Self::LightYellow,
+            AnsiColor::BrightBlue => Self::LightBlue,
+            AnsiColor::BrightMagenta => Self::LightMagenta,
+            AnsiColor::BrightCyan => Self::LightCyan,
+            AnsiColor::BrightWhite => Self::White,
+        }
+    }
+}
+
+impl TryFrom<Color> for AnsiColor {
+    type Error = TryFromColorError;
+
+    fn try_from(color: Color) -> Result<Self, Self::Error> {
+        match color {
+            Color::Black => Ok(Self::Black),
+            Color::Red => Ok(Self::Red),
+            Color::Green => Ok(Self::Green),
+            Color::Yellow => Ok(Self::Yellow),
+            Color::Blue => Ok(Self::Blue),
+            Color::Magenta => Ok(Self::Magenta),
+            Color::Cyan => Ok(Self::Cyan),
+            Color::Gray => Ok(Self::White),
+            Color::DarkGray => Ok(Self::BrightBlack),
+            Color::LightRed => Ok(Self::BrightRed),
+            Color::LightGreen => Ok(Self::BrightGreen),
+            Color::LightYellow => Ok(Self::BrightYellow),
+            Color::LightBlue => Ok(Self::BrightBlue),
+            Color::LightMagenta => Ok(Self::BrightMagenta),
+            Color::LightCyan => Ok(Self::BrightCyan),
+            Color::White => Ok(Self::BrightWhite),
+            _ => Err(TryFromColorError::Ansi),
+        }
+    }
+}
+
+impl From<RgbColor> for Color {
+    fn from(color: RgbColor) -> Self {
+        Self::Rgb(color.r(), color.g(), color.b())
+    }
+}
+
+impl TryFrom<Color> for RgbColor {
+    type Error = TryFromColorError;
+
+    fn try_from(color: Color) -> Result<Self, Self::Error> {
+        match color {
+            Color::Rgb(red, green, blue) => Ok(Self(red, green, blue)),
+            _ => Err(TryFromColorError::RgbColor),
+        }
+    }
+}
+
+impl From<anstyle::Color> for Color {
+    fn from(color: anstyle::Color) -> Self {
+        match color {
+            anstyle::Color::Ansi(ansi_color) => Self::from(ansi_color),
+            anstyle::Color::Ansi256(ansi256_color) => Self::from(ansi256_color),
+            anstyle::Color::Rgb(rgb_color) => Self::from(rgb_color),
+        }
+    }
+}
+
+impl From<Color> for anstyle::Color {
+    fn from(color: Color) -> Self {
+        match color {
+            Color::Rgb(_, _, _) => Self::Rgb(RgbColor::try_from(color).unwrap()),
+            Color::Indexed(_) => Self::Ansi256(Ansi256Color::try_from(color).unwrap()),
+            _ => Self::Ansi(AnsiColor::try_from(color).unwrap()),
+        }
+    }
+}
+
+impl From<Effects> for Modifier {
+    fn from(effect: Effects) -> Self {
+        let mut modifier = Self::empty();
+        if effect.contains(Effects::BOLD) {
+            modifier |= Self::BOLD;
+        }
+        if effect.contains(Effects::DIMMED) {
+            modifier |= Self::DIM;
+        }
+        if effect.contains(Effects::ITALIC) {
+            modifier |= Self::ITALIC;
+        }
+        if effect.contains(Effects::UNDERLINE)
+            || effect.contains(Effects::DOUBLE_UNDERLINE)
+            || effect.contains(Effects::CURLY_UNDERLINE)
+            || effect.contains(Effects::DOTTED_UNDERLINE)
+            || effect.contains(Effects::DASHED_UNDERLINE)
+        {
+            modifier |= Self::UNDERLINED;
+        }
+        if effect.contains(Effects::BLINK) {
+            modifier |= Self::SLOW_BLINK;
+        }
+        if effect.contains(Effects::INVERT) {
+            modifier |= Self::REVERSED;
+        }
+        if effect.contains(Effects::HIDDEN) {
+            modifier |= Self::HIDDEN;
+        }
+        if effect.contains(Effects::STRIKETHROUGH) {
+            modifier |= Self::CROSSED_OUT;
+        }
+        modifier
+    }
+}
+
+impl From<Modifier> for Effects {
+    fn from(modifier: Modifier) -> Self {
+        let mut effects = Self::new();
+        if modifier.contains(Modifier::BOLD) {
+            effects |= Self::BOLD;
+        }
+        if modifier.contains(Modifier::DIM) {
+            effects |= Self::DIMMED;
+        }
+        if modifier.contains(Modifier::ITALIC) {
+            effects |= Self::ITALIC;
+        }
+        if modifier.contains(Modifier::UNDERLINED) {
+            effects |= Self::UNDERLINE;
+        }
+        if modifier.contains(Modifier::SLOW_BLINK) || modifier.contains(Modifier::RAPID_BLINK) {
+            effects |= Self::BLINK;
+        }
+        if modifier.contains(Modifier::REVERSED) {
+            effects |= Self::INVERT;
+        }
+        if modifier.contains(Modifier::HIDDEN) {
+            effects |= Self::HIDDEN;
+        }
+        if modifier.contains(Modifier::CROSSED_OUT) {
+            effects |= Self::STRIKETHROUGH;
+        }
+        effects
+    }
+}
+
+impl From<anstyle::Style> for Style {
+    fn from(style: anstyle::Style) -> Self {
+        Self {
+            fg: style.get_fg_color().map(Color::from),
+            bg: style.get_bg_color().map(Color::from),
+            add_modifier: style.get_effects().into(),
+            ..Default::default()
+        }
+    }
+}
+
+impl From<Style> for anstyle::Style {
+    fn from(style: Style) -> Self {
+        let mut anstyle_style = Self::new();
+        if let Some(fg) = style.fg {
+            let fg = anstyle::Color::from(fg);
+            anstyle_style = anstyle_style.fg_color(Some(fg));
+        }
+        if let Some(bg) = style.bg {
+            let bg = anstyle::Color::from(bg);
+            anstyle_style = anstyle_style.bg_color(Some(bg));
+        }
+        anstyle_style = anstyle_style.effects(style.add_modifier.into());
+        anstyle_style
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn anstyle_to_color() {
+        let anstyle_color = Ansi256Color(42);
+        let color = Color::from(anstyle_color);
+        assert_eq!(color, Color::Indexed(42));
+    }
+
+    #[test]
+    fn color_to_ansi256color() {
+        let color = Color::Indexed(42);
+        let anstyle_color = Ansi256Color::try_from(color);
+        assert_eq!(anstyle_color, Ok(Ansi256Color(42)));
+    }
+
+    #[test]
+    fn color_to_ansi256color_error() {
+        let color = Color::Rgb(0, 0, 0);
+        let anstyle_color = Ansi256Color::try_from(color);
+        assert_eq!(anstyle_color, Err(TryFromColorError::Ansi256));
+    }
+
+    #[test]
+    fn ansi_color_to_color() {
+        let ansi_color = AnsiColor::Red;
+        let color = Color::from(ansi_color);
+        assert_eq!(color, Color::Red);
+    }
+
+    #[test]
+    fn color_to_ansicolor() {
+        let color = Color::Red;
+        let ansi_color = AnsiColor::try_from(color);
+        assert_eq!(ansi_color, Ok(AnsiColor::Red));
+    }
+
+    #[test]
+    fn color_to_ansicolor_error() {
+        let color = Color::Rgb(0, 0, 0);
+        let ansi_color = AnsiColor::try_from(color);
+        assert_eq!(ansi_color, Err(TryFromColorError::Ansi));
+    }
+
+    #[test]
+    fn rgb_color_to_color() {
+        let rgb_color = RgbColor(255, 0, 0);
+        let color = Color::from(rgb_color);
+        assert_eq!(color, Color::Rgb(255, 0, 0));
+    }
+
+    #[test]
+    fn color_to_rgbcolor() {
+        let color = Color::Rgb(255, 0, 0);
+        let rgb_color = RgbColor::try_from(color);
+        assert_eq!(rgb_color, Ok(RgbColor(255, 0, 0)));
+    }
+
+    #[test]
+    fn color_to_rgbcolor_error() {
+        let color = Color::Indexed(42);
+        let rgb_color = RgbColor::try_from(color);
+        assert_eq!(rgb_color, Err(TryFromColorError::RgbColor));
+    }
+
+    #[test]
+    fn effects_to_modifier() {
+        let effects = Effects::BOLD | Effects::ITALIC;
+        let modifier = Modifier::from(effects);
+        assert!(modifier.contains(Modifier::BOLD));
+        assert!(modifier.contains(Modifier::ITALIC));
+    }
+
+    #[test]
+    fn modifier_to_effects() {
+        let modifier = Modifier::BOLD | Modifier::ITALIC;
+        let effects = Effects::from(modifier);
+        assert!(effects.contains(Effects::BOLD));
+        assert!(effects.contains(Effects::ITALIC));
+    }
+
+    #[test]
+    fn anstyle_style_to_style() {
+        let anstyle_style = anstyle::Style::new()
+            .fg_color(Some(anstyle::Color::Ansi(AnsiColor::Red)))
+            .bg_color(Some(anstyle::Color::Ansi(AnsiColor::Blue)))
+            .effects(Effects::BOLD | Effects::ITALIC);
+        let style = Style::from(anstyle_style);
+        assert_eq!(style.fg, Some(Color::Red));
+        assert_eq!(style.bg, Some(Color::Blue));
+        assert!(style.add_modifier.contains(Modifier::BOLD));
+        assert!(style.add_modifier.contains(Modifier::ITALIC));
+    }
+
+    #[test]
+    fn style_to_anstyle_style() {
+        let style = Style {
+            fg: Some(Color::Red),
+            bg: Some(Color::Blue),
+            add_modifier: Modifier::BOLD | Modifier::ITALIC,
+            ..Default::default()
+        };
+        let anstyle_style = anstyle::Style::from(style);
+        assert_eq!(
+            anstyle_style.get_fg_color(),
+            Some(anstyle::Color::Ansi(AnsiColor::Red))
+        );
+        assert_eq!(
+            anstyle_style.get_bg_color(),
+            Some(anstyle::Color::Ansi(AnsiColor::Blue))
+        );
+        assert!(anstyle_style.get_effects().contains(Effects::BOLD));
+        assert!(anstyle_style.get_effects().contains(Effects::ITALIC));
+    }
+}

ratatui-core/src/style/color.rs

@@ -44,7 +44,7 @@ use crate::style::stylize::{ColorDebug, ColorDebugKind};
 /// ```
 /// use std::str::FromStr;
 ///
-/// use ratatui::style::Color;
+/// use ratatui_core::style::Color;
 ///
 /// assert_eq!(Color::from_str("red"), Ok(Color::Red));
 /// assert_eq!("red".parse(), Ok(Color::Red));
@@ -112,14 +112,12 @@ pub enum Color {
     /// Notably versions of Windows Terminal prior to Windows 10 and macOS Terminal.app do not
     /// support this.
     ///
-    /// If the terminal does not support true color, code using the  [`TermwizBackend`] will
+    /// If the terminal does not support true color, code using the  `TermwizBackend` will
     /// fallback to the default text color. Crossterm and Termion do not have this capability and
     /// the display will be unpredictable (e.g. Terminal.app may display glitched blinking text).
     /// See <https://github.com/ratatui/ratatui/issues/475> for an example of this problem.
     ///
     /// See also: <https://en.wikipedia.org/wiki/ANSI_escape_code#24-bit>
-    ///
-    /// [`TermwizBackend`]: crate::backend::TermwizBackend
     Rgb(u8, u8, u8),
     /// An 8-bit 256 color.
     ///
@@ -170,7 +168,7 @@ impl<'de> serde::Deserialize<'de> for Color {
     /// ```
     /// use std::str::FromStr;
     ///
-    /// use ratatui::style::Color;
+    /// use ratatui_core::style::Color;
     ///
     /// #[derive(Debug, serde::Deserialize)]
     /// struct Theme {
@@ -265,7 +263,7 @@ impl std::error::Error for ParseColorError {}
 /// ```
 /// use std::str::FromStr;
 ///
-/// use ratatui::style::Color;
+/// use ratatui_core::style::Color;
 ///
 /// let color: Color = Color::from_str("blue").unwrap();
 /// assert_eq!(color, Color::Blue);
@@ -385,7 +383,8 @@ impl Color {
     /// # Examples
     ///
     /// ```
-    /// use ratatui::{palette::Hsl, style::Color};
+    /// use palette::Hsl;
+    /// use ratatui_core::style::Color;
     ///
     /// // Minimum Lightness is black
     /// let color: Color = Color::from_hsl(Hsl::new(0.0, 0.0, 0.0));
@@ -437,7 +436,8 @@ impl Color {
     /// # Examples
     ///
     /// ```
-    /// use ratatui::{palette::Hsluv, style::Color};
+    /// use palette::Hsluv;
+    /// use ratatui_core::style::Color;
     ///
     /// // Minimum Lightness is black
     /// let color: Color = Color::from_hsluv(Hsluv::new(0.0, 100.0, 0.0));
@@ -480,6 +480,7 @@ mod tests {
 
     #[cfg(feature = "palette")]
     use palette::{Hsl, Hsluv};
+    #[cfg(feature = "palette")]
     use rstest::rstest;
     #[cfg(feature = "serde")]
     use serde::de::{Deserialize, IntoDeserializer};

ratatui-core/src/style/palette/material.rs

@@ -403,7 +403,7 @@
 //! # Example
 //!
 //! ```rust
-//! use ratatui::style::{
+//! use ratatui_core::style::{
 //!     palette::material::{BLUE, RED},
 //!     Color,
 //! };

ratatui-core/src/style/palette/tailwind.rs

@@ -268,7 +268,7 @@
 //! # Example
 //!
 //! ```rust
-//! use ratatui::style::{
+//! use ratatui_core::style::{
 //!     palette::tailwind::{BLUE, RED},
 //!     Color,
 //! };

ratatui-core/src/style/palette_conversion.rs

@@ -15,7 +15,7 @@ use crate::style::Color;
 ///
 /// ```
 /// use palette::Srgb;
-/// use ratatui::style::Color;
+/// use ratatui_core::style::Color;
 ///
 /// let color = Color::from(Srgb::new(1.0f32, 0.0, 0.0));
 /// assert_eq!(color, Color::Rgb(255, 0, 0));
@@ -36,7 +36,7 @@ impl<T: IntoStimulus<u8>> From<Srgb<T>> for Color {
 ///
 /// ```
 /// use palette::LinSrgb;
-/// use ratatui::style::Color;
+/// use ratatui_core::style::Color;
 ///
 /// let color = Color::from(LinSrgb::new(1.0f32, 0.0, 0.0));
 /// assert_eq!(color, Color::Rgb(255, 0, 0));

ratatui-core/src/style/stylize.rs

@@ -195,8 +195,8 @@ macro_rules! modifier {
 /// by `not_`). The `reset()` method is also provided to reset the style.
 ///
 /// # Examples
-/// ```
-/// use ratatui::{
+/// ```ignore
+/// use ratatui_core::{
 ///     style::{Color, Modifier, Style, Stylize},
 ///     text::Line,
 ///     widgets::{Block, Paragraph},
@@ -250,7 +250,7 @@ pub trait Stylize<'a, T>: Sized {
     modifier!(crossed_out);
 }
 
-impl<'a, T, U> Stylize<'a, T> for U
+impl<T, U> Stylize<'_, T> for U
 where
     U: Styled<Item = T>,
 {
@@ -501,80 +501,75 @@ mod tests {
     }
 
     #[rstest]
-    #[case(ColorDebugKind::Foreground, Color::Black, ".black()")]
-    #[case(ColorDebugKind::Foreground, Color::Red, ".red()")]
-    #[case(ColorDebugKind::Foreground, Color::Green, ".green()")]
-    #[case(ColorDebugKind::Foreground, Color::Yellow, ".yellow()")]
-    #[case(ColorDebugKind::Foreground, Color::Blue, ".blue()")]
-    #[case(ColorDebugKind::Foreground, Color::Magenta, ".magenta()")]
-    #[case(ColorDebugKind::Foreground, Color::Cyan, ".cyan()")]
-    #[case(ColorDebugKind::Foreground, Color::Gray, ".gray()")]
-    #[case(ColorDebugKind::Foreground, Color::DarkGray, ".dark_gray()")]
-    #[case(ColorDebugKind::Foreground, Color::LightRed, ".light_red()")]
-    #[case(ColorDebugKind::Foreground, Color::LightGreen, ".light_green()")]
-    #[case(ColorDebugKind::Foreground, Color::LightYellow, ".light_yellow()")]
-    #[case(ColorDebugKind::Foreground, Color::LightBlue, ".light_blue()")]
-    #[case(ColorDebugKind::Foreground, Color::LightMagenta, ".light_magenta()")]
-    #[case(ColorDebugKind::Foreground, Color::LightCyan, ".light_cyan()")]
-    #[case(ColorDebugKind::Foreground, Color::White, ".white()")]
-    #[case(
-        ColorDebugKind::Foreground,
-        Color::Indexed(10),
-        ".fg(Color::Indexed(10))"
-    )]
-    #[case(
-        ColorDebugKind::Foreground,
-        Color::Rgb(255, 0, 0),
-        ".fg(Color::Rgb(255, 0, 0))"
-    )]
-    #[case(ColorDebugKind::Background, Color::Black, ".on_black()")]
-    #[case(ColorDebugKind::Background, Color::Red, ".on_red()")]
-    #[case(ColorDebugKind::Background, Color::Green, ".on_green()")]
-    #[case(ColorDebugKind::Background, Color::Yellow, ".on_yellow()")]
-    #[case(ColorDebugKind::Background, Color::Blue, ".on_blue()")]
-    #[case(ColorDebugKind::Background, Color::Magenta, ".on_magenta()")]
-    #[case(ColorDebugKind::Background, Color::Cyan, ".on_cyan()")]
-    #[case(ColorDebugKind::Background, Color::Gray, ".on_gray()")]
-    #[case(ColorDebugKind::Background, Color::DarkGray, ".on_dark_gray()")]
-    #[case(ColorDebugKind::Background, Color::LightRed, ".on_light_red()")]
-    #[case(ColorDebugKind::Background, Color::LightGreen, ".on_light_green()")]
-    #[case(ColorDebugKind::Background, Color::LightYellow, ".on_light_yellow()")]
-    #[case(ColorDebugKind::Background, Color::LightBlue, ".on_light_blue()")]
-    #[case(ColorDebugKind::Background, Color::LightMagenta, ".on_light_magenta()")]
-    #[case(ColorDebugKind::Background, Color::LightCyan, ".on_light_cyan()")]
-    #[case(ColorDebugKind::Background, Color::White, ".on_white()")]
-    #[case(
-        ColorDebugKind::Background,
-        Color::Indexed(10),
-        ".bg(Color::Indexed(10))"
-    )]
-    #[case(
-        ColorDebugKind::Background,
-        Color::Rgb(255, 0, 0),
-        ".bg(Color::Rgb(255, 0, 0))"
-    )]
+    #[case(Color::Black, ".black()")]
+    #[case(Color::Red, ".red()")]
+    #[case(Color::Green, ".green()")]
+    #[case(Color::Yellow, ".yellow()")]
+    #[case(Color::Blue, ".blue()")]
+    #[case(Color::Magenta, ".magenta()")]
+    #[case(Color::Cyan, ".cyan()")]
+    #[case(Color::Gray, ".gray()")]
+    #[case(Color::DarkGray, ".dark_gray()")]
+    #[case(Color::LightRed, ".light_red()")]
+    #[case(Color::LightGreen, ".light_green()")]
+    #[case(Color::LightYellow, ".light_yellow()")]
+    #[case(Color::LightBlue, ".light_blue()")]
+    #[case(Color::LightMagenta, ".light_magenta()")]
+    #[case(Color::LightCyan, ".light_cyan()")]
+    #[case(Color::White, ".white()")]
+    #[case(Color::Indexed(10), ".fg(Color::Indexed(10))")]
+    #[case(Color::Rgb(255, 0, 0), ".fg(Color::Rgb(255, 0, 0))")]
+    fn stylize_debug_foreground(#[case] color: Color, #[case] expected: &str) {
+        let debug = color.stylize_debug(ColorDebugKind::Foreground);
+        assert_eq!(format!("{debug:?}"), expected);
+    }
+
+    #[rstest]
+    #[case(Color::Black, ".on_black()")]
+    #[case(Color::Red, ".on_red()")]
+    #[case(Color::Green, ".on_green()")]
+    #[case(Color::Yellow, ".on_yellow()")]
+    #[case(Color::Blue, ".on_blue()")]
+    #[case(Color::Magenta, ".on_magenta()")]
+    #[case(Color::Cyan, ".on_cyan()")]
+    #[case(Color::Gray, ".on_gray()")]
+    #[case(Color::DarkGray, ".on_dark_gray()")]
+    #[case(Color::LightRed, ".on_light_red()")]
+    #[case(Color::LightGreen, ".on_light_green()")]
+    #[case(Color::LightYellow, ".on_light_yellow()")]
+    #[case(Color::LightBlue, ".on_light_blue()")]
+    #[case(Color::LightMagenta, ".on_light_magenta()")]
+    #[case(Color::LightCyan, ".on_light_cyan()")]
+    #[case(Color::White, ".on_white()")]
+    #[case(Color::Indexed(10), ".bg(Color::Indexed(10))")]
+    #[case(Color::Rgb(255, 0, 0), ".bg(Color::Rgb(255, 0, 0))")]
+    fn stylize_debug_background(#[case] color: Color, #[case] expected: &str) {
+        let debug = color.stylize_debug(ColorDebugKind::Background);
+        assert_eq!(format!("{debug:?}"), expected);
+    }
+
     #[cfg(feature = "underline-color")]
-    #[case(
-        ColorDebugKind::Underline,
-        Color::Black,
-        ".underline_color(Color::Black)"
-    )]
-    #[cfg(feature = "underline-color")]
-    #[case(ColorDebugKind::Underline, Color::Red, ".underline_color(Color::Red)")]
-    #[cfg(feature = "underline-color")]
-    #[case(
-        ColorDebugKind::Underline,
-        Color::Green,
-        ".underline_color(Color::Green)"
-    )]
-    #[cfg(feature = "underline-color")]
-    #[case(
-        ColorDebugKind::Underline,
-        Color::Yellow,
-        ".underline_color(Color::Yellow)"
-    )]
-    fn stylize_debug(#[case] kind: ColorDebugKind, #[case] color: Color, #[case] expected: &str) {
-        let debug = color.stylize_debug(kind);
+    #[rstest]
+    #[case(Color::Black, ".underline_color(Color::Black)")]
+    #[case(Color::Red, ".underline_color(Color::Red)")]
+    #[case(Color::Green, ".underline_color(Color::Green)")]
+    #[case(Color::Yellow, ".underline_color(Color::Yellow)")]
+    #[case(Color::Blue, ".underline_color(Color::Blue)")]
+    #[case(Color::Magenta, ".underline_color(Color::Magenta)")]
+    #[case(Color::Cyan, ".underline_color(Color::Cyan)")]
+    #[case(Color::Gray, ".underline_color(Color::Gray)")]
+    #[case(Color::DarkGray, ".underline_color(Color::DarkGray)")]
+    #[case(Color::LightRed, ".underline_color(Color::LightRed)")]
+    #[case(Color::LightGreen, ".underline_color(Color::LightGreen)")]
+    #[case(Color::LightYellow, ".underline_color(Color::LightYellow)")]
+    #[case(Color::LightBlue, ".underline_color(Color::LightBlue)")]
+    #[case(Color::LightMagenta, ".underline_color(Color::LightMagenta)")]
+    #[case(Color::LightCyan, ".underline_color(Color::LightCyan)")]
+    #[case(Color::White, ".underline_color(Color::White)")]
+    #[case(Color::Indexed(10), ".underline_color(Color::Indexed(10))")]
+    #[case(Color::Rgb(255, 0, 0), ".underline_color(Color::Rgb(255, 0, 0))")]
+    fn stylize_debug_underline(#[case] color: Color, #[case] expected: &str) {
+        let debug = color.stylize_debug(ColorDebugKind::Underline);
         assert_eq!(format!("{debug:?}"), expected);
     }
 }

ratatui-core/src/symbols.rs

@@ -1,3 +1,5 @@
+//! Symbols and markers for drawing various widgets.
+
 use strum::{Display, EnumString};
 
 pub mod border;

ratatui-core/src/terminal.rs

@@ -32,15 +32,9 @@
 //! [`Buffer`]: crate::buffer::Buffer
 
 mod frame;
-#[cfg(feature = "crossterm")]
-mod init;
 mod terminal;
 mod viewport;
 
 pub use frame::{CompletedFrame, Frame};
-#[cfg(feature = "crossterm")]
-pub use init::{
-    init, init_with_options, restore, try_init, try_init_with_options, try_restore, DefaultTerminal,
-};
 pub use terminal::{Options as TerminalOptions, Terminal};
 pub use viewport::Viewport;

ratatui-core/src/terminal/frame.rs

@@ -1,7 +1,7 @@
 use crate::{
     buffer::Buffer,
     layout::{Position, Rect},
-    widgets::{StatefulWidget, StatefulWidgetRef, Widget, WidgetRef},
+    widgets::{StatefulWidget, Widget},
 };
 
 /// A consistent view into the terminal state for rendering a single frame.
@@ -14,7 +14,7 @@ use crate::{
 /// to the terminal. This avoids drawing redundant cells.
 ///
 /// [`Buffer`]: crate::buffer::Buffer
-/// [`Terminal::draw`]: crate::Terminal::draw
+/// [`Terminal::draw`]: crate::terminal::Terminal::draw
 #[derive(Debug, Hash)]
 pub struct Frame<'a> {
     /// Where should the cursor be after drawing this frame?
@@ -37,7 +37,7 @@ pub struct Frame<'a> {
 /// [`Terminal::draw`] call have been applied. Therefore, it is only valid until the next call to
 /// [`Terminal::draw`].
 ///
-/// [`Terminal::draw`]: crate::Terminal::draw
+/// [`Terminal::draw`]: crate::terminal::Terminal::draw
 #[derive(Debug, Clone, Eq, PartialEq, Hash)]
 pub struct CompletedFrame<'a> {
     /// The buffer that was used to draw the last frame.
@@ -96,32 +96,6 @@ impl Frame<'_> {
         widget.render(area, self.buffer);
     }
 
-    /// Render a [`WidgetRef`] to the current buffer using [`WidgetRef::render_ref`].
-    ///
-    /// Usually the area argument is the size of the current frame or a sub-area of the current
-    /// frame (which can be obtained using [`Layout`] to split the total area).
-    ///
-    /// # Example
-    ///
-    /// ```rust
-    /// # #[cfg(feature = "unstable-widget-ref")] {
-    /// # use ratatui::{backend::TestBackend, Terminal};
-    /// # let backend = TestBackend::new(5, 5);
-    /// # let mut terminal = Terminal::new(backend).unwrap();
-    /// # let mut frame = terminal.get_frame();
-    /// use ratatui::{layout::Rect, widgets::Block};
-    ///
-    /// let block = Block::new();
-    /// let area = Rect::new(0, 0, 5, 5);
-    /// frame.render_widget_ref(block, area);
-    /// # }
-    /// ```
-    #[allow(clippy::needless_pass_by_value)]
-    #[instability::unstable(feature = "widget-ref")]
-    pub fn render_widget_ref<W: WidgetRef>(&mut self, widget: W, area: Rect) {
-        widget.render_ref(area, self.buffer);
-    }
-
     /// Render a [`StatefulWidget`] to the current buffer using [`StatefulWidget::render`].
     ///
     /// Usually the area argument is the size of the current frame or a sub-area of the current
@@ -156,43 +130,6 @@ impl Frame<'_> {
         widget.render(area, self.buffer, state);
     }
 
-    /// Render a [`StatefulWidgetRef`] to the current buffer using
-    /// [`StatefulWidgetRef::render_ref`].
-    ///
-    /// Usually the area argument is the size of the current frame or a sub-area of the current
-    /// frame (which can be obtained using [`Layout`] to split the total area).
-    ///
-    /// The last argument should be an instance of the [`StatefulWidgetRef::State`] associated to
-    /// the given [`StatefulWidgetRef`].
-    ///
-    /// # Example
-    ///
-    /// ```rust
-    /// # #[cfg(feature = "unstable-widget-ref")] {
-    /// # use ratatui::{backend::TestBackend, Terminal};
-    /// # let backend = TestBackend::new(5, 5);
-    /// # let mut terminal = Terminal::new(backend).unwrap();
-    /// # let mut frame = terminal.get_frame();
-    /// use ratatui::{
-    ///     layout::Rect,
-    ///     widgets::{List, ListItem, ListState},
-    /// };
-    ///
-    /// let mut state = ListState::default().with_selected(Some(1));
-    /// let list = List::new(vec![ListItem::new("Item 1"), ListItem::new("Item 2")]);
-    /// let area = Rect::new(0, 0, 5, 5);
-    /// frame.render_stateful_widget_ref(list, area, &mut state);
-    /// # }
-    /// ```
-    #[allow(clippy::needless_pass_by_value)]
-    #[instability::unstable(feature = "widget-ref")]
-    pub fn render_stateful_widget_ref<W>(&mut self, widget: W, area: Rect, state: &mut W::State)
-    where
-        W: StatefulWidgetRef,
-    {
-        widget.render_ref(area, self.buffer, state);
-    }
-
     /// After drawing this frame, make the cursor visible and put it at the specified (x, y)
     /// coordinates. If this method is not called, the cursor will be hidden.
     ///
@@ -200,9 +137,9 @@ impl Frame<'_> {
     /// [`Terminal::show_cursor`], and [`Terminal::set_cursor_position`]. Pick one of the APIs and
     /// stick with it.
     ///
-    /// [`Terminal::hide_cursor`]: crate::Terminal::hide_cursor
-    /// [`Terminal::show_cursor`]: crate::Terminal::show_cursor
-    /// [`Terminal::set_cursor_position`]: crate::Terminal::set_cursor_position
+    /// [`Terminal::hide_cursor`]: crate::terminal::Terminal::hide_cursor
+    /// [`Terminal::show_cursor`]: crate::terminal::Terminal::show_cursor
+    /// [`Terminal::set_cursor_position`]: crate::terminal::Terminal::set_cursor_position
     pub fn set_cursor_position<P: Into<Position>>(&mut self, position: P) {
         self.cursor_position = Some(position.into());
     }
@@ -214,9 +151,9 @@ impl Frame<'_> {
     /// [`Terminal::show_cursor`], and [`Terminal::set_cursor_position`]. Pick one of the APIs and
     /// stick with it.
     ///
-    /// [`Terminal::hide_cursor`]: crate::Terminal::hide_cursor
-    /// [`Terminal::show_cursor`]: crate::Terminal::show_cursor
-    /// [`Terminal::set_cursor_position`]: crate::Terminal::set_cursor_position
+    /// [`Terminal::hide_cursor`]: crate::terminal::Terminal::hide_cursor
+    /// [`Terminal::show_cursor`]: crate::terminal::Terminal::show_cursor
+    /// [`Terminal::set_cursor_position`]: crate::terminal::Terminal::set_cursor_position
     #[deprecated = "the method set_cursor_position indicates more clearly what about the cursor to set"]
     pub fn set_cursor(&mut self, x: u16, y: u16) {
         self.set_cursor_position(Position { x, y });

ratatui-core/src/terminal/terminal.rs

@@ -4,7 +4,7 @@ use crate::{
     backend::{Backend, ClearType},
     buffer::{Buffer, Cell},
     layout::{Position, Rect, Size},
-    CompletedFrame, Frame, TerminalOptions, Viewport,
+    terminal::{CompletedFrame, Frame, TerminalOptions, Viewport},
 };
 
 /// An interface to interact and draw [`Frame`]s on the user's terminal.
@@ -271,7 +271,7 @@ where
     /// - return a [`CompletedFrame`] with the current buffer and the area of the terminal
     ///
     /// The [`CompletedFrame`] returned by this method can be useful for debugging or testing
-    /// purposes, but it is often not used in regular applicationss.
+    /// purposes, but it is often not used in regular applications.
     ///
     /// The render callback should fully render the entire frame when called, including areas that
     /// are unchanged from the previous frame. This is because each frame is compared to the
@@ -339,7 +339,7 @@ where
     /// [`std::io::Error`] and the terminal will not be updated.
     ///
     /// The [`CompletedFrame`] returned by this method can be useful for debugging or testing
-    /// purposes, but it is often not used in regular applicationss.
+    /// purposes, but it is often not used in regular applications.
     ///
     /// The render callback should fully render the entire frame when called, including areas that
     /// are unchanged from the previous frame. This is because each frame is compared to the