Make ratatui dev-dependecy in ratatui-termwiz just a path ref

We now expect that you disable the default features if you want less
dependencies

.cargo-husky/hooks/pre-push

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

.cargo/config.toml

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

.editorconfig

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

.github/CODEOWNERS

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

.github/FUNDING.yml

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

.github/ISSUE_TEMPLATE/bug_report.md

@@ -2,7 +2,7 @@
 name: Bug report
 about: Create an issue about a bug you encountered
 title: ''
-labels: bug
+labels: 'Type: Bug'
 assignees: ''
 ---
 
@@ -17,26 +17,22 @@ A detailed and complete issue is more likely to be processed quickly.
 A clear and concise description of what the bug is.
 -->
 
-
 ## To Reproduce
 <!--
 Try to reduce the issue to a simple code sample exhibiting the problem.
 Ideally, fork the project and add a test or an example.
 -->
 
-
 ## Expected behavior
 <!--
 A clear and concise description of what you expected to happen.
 -->
 
-
 ## Screenshots
 <!--
 If applicable, add screenshots, gifs or videos to help explain your problem.
 -->
 
-
 ## Environment
 <!--
 Add a description of the systems where you are observing the issue. For example:

.github/ISSUE_TEMPLATE/config.yml

@@ -1 +1,14 @@
 blank_issues_enabled: false
+contact_links:
+  - name: Frequently Asked Questions
+    url: https://ratatui.rs/faq/
+    about: Check the website FAQ section to see if your question has already been answered
+  - name: Ratatui Forum
+    url: https://forum.ratatui.rs
+    about: Ask questions about ratatui on our Forum
+  - name: Discord Chat
+    url: https://discord.gg/pMCEU9hNEj
+    about: Ask questions about ratatui on Discord
+  - name: Matrix Chat
+    url: https://matrix.to/#/#ratatui:matrix.org
+    about: Ask questions about ratatui on Matrix

.github/ISSUE_TEMPLATE/feature_request.md

@@ -2,7 +2,7 @@
 name: Feature request
 about: Suggest an idea for this project
 title: ''
-labels: enhancement
+labels: 'Type: Enhancement'
 assignees: ''
 
 ---

.github/dependabot.yml

@@ -0,0 +1,18 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+
+version: 2
+updates:
+  # Maintain dependencies for Cargo
+  - package-ecosystem: "cargo"
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "weekly"
+  # Maintain dependencies for GitHub Actions
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 10

.github/workflows/bench_base.yml

@@ -0,0 +1,25 @@
+name: Run Benchmarks
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  benchmark_base_branch:
+    name: Continuous Benchmarking with Bencher
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - uses: bencherdev/bencher@main
+      - name: Track base branch benchmarks with Bencher
+        run: |
+          bencher run \
+          --project ratatui-org \
+          --token '${{ secrets.BENCHER_API_TOKEN }}' \
+          --branch main \
+          --testbed ubuntu-latest \
+          --adapter rust_criterion \
+          --err \
+          cargo bench

.github/workflows/bench_run_fork_pr.yml

@@ -0,0 +1,25 @@
+name: Run and Cache Benchmarks
+
+on:
+  pull_request:
+    types: [opened, reopened, edited, synchronize]
+
+jobs:
+  benchmark_fork_pr_branch:
+    name: Run Fork PR Benchmarks
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Run Benchmarks
+        run: cargo bench > benchmark_results.txt
+      - name: Upload Benchmark Results
+        uses: actions/upload-artifact@v4
+        with:
+          name: benchmark_results.txt
+          path: ./benchmark_results.txt
+      - name: Upload GitHub Pull Request Event
+        uses: actions/upload-artifact@v4
+        with:
+          name: event.json
+          path: ${{ github.event_path }}

.github/workflows/bench_track_fork_pr.yml

@@ -0,0 +1,56 @@
+name: Track Benchmarks with Bencher
+
+on:
+  workflow_run:
+    workflows: [Run and Cache Benchmarks]
+    types: [completed]
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  track_fork_pr_branch:
+    if: github.event.workflow_run.conclusion == 'success'
+    runs-on: ubuntu-latest
+    env:
+      BENCHMARK_RESULTS: benchmark_results.txt
+      PR_EVENT: event.json
+    steps:
+      - name: Download Benchmark Results
+        uses: dawidd6/action-download-artifact@v6
+        with:
+          name: ${{ env.BENCHMARK_RESULTS }}
+          run_id: ${{ github.event.workflow_run.id }}
+      - name: Download PR Event
+        uses: dawidd6/action-download-artifact@v6
+        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.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);
+      - uses: bencherdev/bencher@main
+      - name: Track Benchmarks with Bencher
+        run: |
+          bencher run \
+          --project ratatui-org \
+          --token '${{ secrets.BENCHER_API_TOKEN }}' \
+          --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 "$PR_NUMBER" \
+          --file "$BENCHMARK_RESULTS"

.github/workflows/calculate-alpha-release.bash

@@ -0,0 +1,52 @@
+#!/bin/bash
+
+# Exit on error. Append "|| true" if you expect an error.
+set -o errexit
+# Exit on error inside any functions or subshells.
+set -o errtrace
+# Do not allow use of undefined vars. Use ${VAR:-} to use an undefined VAR
+set -o nounset
+# Catch the error in case mysqldump fails (but gzip succeeds) in `mysqldump |gzip`
+set -o pipefail
+# Turn on traces, useful while debugging but commented out by default
+# set -o xtrace
+
+last_release="$(git tag --sort=committerdate | grep -P "v0+\.\d+\.\d+$" | tail -1)"
+echo "🐭 Last release: ${last_release}"
+
+# detect breaking changes
+if [ -n "$(git log --oneline ${last_release}..HEAD | grep '!:')" ]; then
+    echo "🐭 Breaking changes detected since ${last_release}"
+    git log --oneline ${last_release}..HEAD | grep '!:'
+    # increment the minor version
+    minor="${last_release##v0.}"
+    minor="${minor%.*}"
+    next_minor="$((minor + 1))"
+    next_release="v0.${next_minor}.0"
+else
+    # increment the patch version
+    patch="${last_release##*.}"
+    next_patch="$((patch + 1))"
+    next_release="${last_release/%${patch}/${next_patch}}"
+fi
+echo "🐭 Next release: ${next_release}"
+
+suffix="alpha"
+last_tag="$(git tag --sort=committerdate | tail -1)"
+if [[ "${last_tag}" = "${next_release}-${suffix}"* ]]; then
+    echo "🐭 Last alpha release: ${last_tag}"
+    # increment the alpha version
+    # e.g. v0.22.1-alpha.12 -> v0.22.1-alpha.13
+    alpha="${last_tag##*-${suffix}.}"
+    next_alpha="$((alpha + 1))"
+    next_tag="${last_tag/%${alpha}/${next_alpha}}"
+else
+    # increment the patch and start the alpha version from 0
+    # e.g. v0.22.0 -> v0.22.1-alpha.0
+    next_tag="${next_release}-${suffix}.0"
+fi
+# update the crate version
+msg="# crate version"
+sed -E -i "s/^version = .* ${msg}$/version = \"${next_tag#v}\" ${msg}/" Cargo.toml
+echo "NEXT_TAG=${next_tag}" >> $GITHUB_ENV
+echo "🐭 Next alpha release: ${next_tag}"

.github/workflows/cd.yml

@@ -1,86 +0,0 @@
-name: Continuous Deployment
-
-on:
-  workflow_dispatch:
-  schedule:
-    # At 00:00 on Saturday
-    # https://crontab.guru/#0_0_*_*_6
-    - cron: "0 0 * * 6"
-  push:
-    tags:
-      - "v*.*.*"
-
-defaults:
-  run:
-    shell: bash
-
-jobs:
-  publish-alpha:
-    name: Create an alpha release
-    runs-on: ubuntu-latest
-    permissions:
-      contents: write
-    if: ${{ !startsWith(github.event.ref, 'refs/tags/v') }}
-    steps:
-      - name: Checkout the repository
-        uses: actions/checkout@v3
-        with:
-          fetch-depth: 0
-
-      - name: Calculate the next release
-        run: |
-          suffix="alpha"
-          last_tag="$(git tag --sort=committerdate | tail -1)"
-          if [[ "${last_tag}" = *"-${suffix}"* ]]; then
-            # increment the alpha version
-            # e.g. v0.22.1-alpha.12 -> v0.22.1-alpha.13
-            alpha="${last_tag##*-${suffix}.}"
-            next_alpha="$((alpha + 1))"
-            next_tag="${last_tag/%${alpha}/${next_alpha}}"
-          else
-            # increment the patch and start the alpha version from 0
-            # e.g. v0.22.0 -> v0.22.1-alpha.0
-            patch="${last_tag##*.}"
-            next_patch="$((patch + 1))"
-            next_tag="${last_tag/%${patch}/${next_patch}}-${suffix}.0"
-          fi
-          # update the crate version
-          msg="# crate version"
-          sed -E -i "s/^version = .* ${msg}$/version = \"${next_tag#v}\" ${msg}/" Cargo.toml
-          echo "NEXT_TAG=${next_tag}" >> $GITHUB_ENV
-          echo "Next alpha release: ${next_tag} 🐭"
-
-      - name: Publish on crates.io
-        uses: actions-rs/cargo@v1
-        with:
-          command: publish
-          args: --allow-dirty --token ${{ secrets.CARGO_TOKEN }}
-
-      - name: Generate a changelog
-        uses: orhun/git-cliff-action@v2
-        with:
-          config: cliff.toml
-          args: --unreleased --tag ${{ env.NEXT_TAG }} --strip header
-        env:
-          OUTPUT: BODY.md
-
-      - name: Publish on GitHub
-        uses: ncipollo/release-action@v1
-        with:
-          tag: ${{ env.NEXT_TAG }}
-          prerelease: true
-          bodyFile: BODY.md
-
-  publish-stable:
-    name: Create a stable release
-    runs-on: ubuntu-latest
-    if: ${{ startsWith(github.event.ref, 'refs/tags/v') }}
-    steps:
-      - name: Checkout the repository
-        uses: actions/checkout@v3
-
-      - name: Publish on crates.io
-        uses: actions-rs/cargo@v1
-        with:
-          command: publish
-          args: --token ${{ secrets.CARGO_TOKEN }}

.github/workflows/check-pr.yml

@@ -46,20 +46,24 @@ jobs:
 
   check-breaking-change-label:
     runs-on: ubuntu-latest
+    env:
+      # use an environment variable to pass untrusted input to the script
+      # see https://securitylab.github.com/research/github-actions-untrusted-input/
+      PR_TITLE: ${{ github.event.pull_request.title }}
     steps:
     - name: Check breaking change label
       id: check_breaking_change
       run: |
         pattern='^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(\(\w+\))?!:'
         # Check if pattern matches
-        if echo "${{ github.event.pull_request.title }}" | grep -qE "$pattern"; then
+        if echo "${PR_TITLE}" | grep -qE "$pattern"; then
           echo "breaking_change=true" >> $GITHUB_OUTPUT
         else
           echo "breaking_change=false" >> $GITHUB_OUTPUT
         fi
     - name: Add label
       if: steps.check_breaking_change.outputs.breaking_change == 'true'
-      uses: actions/github-script@v6
+      uses: actions/github-script@v7
       with:
         github-token: ${{ secrets.GITHUB_TOKEN }}
         script: |
@@ -67,7 +71,7 @@ jobs:
             issue_number: context.issue.number,
             owner: context.repo.owner,
             repo: context.repo.repo,
-            labels: ['breaking change']
+            labels: ['Type: Breaking Change']
           })
 
   do-not-merge:
@@ -80,4 +84,3 @@ jobs:
           echo "Pull request is labeled as 'do not merge'"
           echo "This workflow fails so that the pull request cannot be merged"
           exit 1
-

.github/workflows/check-semver.yml

@@ -0,0 +1,16 @@
+name: Check Semver
+
+on:
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  check-semver:
+    name: Check semver
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout the repository
+        uses: actions/checkout@v4
+      - name: Check semver
+        uses: obi1kenobi/cargo-semver-checks-action@v2

.github/workflows/ci.yml

@@ -9,7 +9,6 @@ on:
   pull_request:
     branches:
       - main
-  merge_group:
 
 # ensure that the workflow is only triggered once per PR,  subsequent pushes to the PR will cancel
 # and restart the workflow. See https://docs.github.com/en/actions/using-jobs/using-concurrency
@@ -17,141 +16,170 @@ concurrency:
   group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
   cancel-in-progress: true
 
-env:
-  # don't install husky hooks during CI as they are only needed for for pre-push
-  CARGO_HUSKY_DONT_INSTALL_HOOKS: true
-
-# lint, clippy and coveraget jobs are intentionally early in the workflow to catch simple
-# formatting, typos, and missing tests as early as possible. This allows us to fix these and
-# resubmit the PR without having to wait for the comprehensive matrix of tests to complete.
+# lint, clippy and coverage jobs are intentionally early in the workflow to catch simple formatting,
+# typos, and missing tests as early as possible. This allows us to fix these and resubmit the PR
+# without having to wait for the comprehensive matrix of tests to complete.
 jobs:
-  lint:
+  # Lint the formatting of the codebase.
+  lint-formatting:
+    name: Check Formatting
     runs-on: ubuntu-latest
     steps:
-      - name: Checkout
-        if: github.event_name != 'pull_request'
-        uses: actions/checkout@v3
-      - name: Checkout
-        if: github.event_name == 'pull_request'
-        uses: actions/checkout@v3
-        with:
-          ref: ${{ github.event.pull_request.head.sha }}
-      - name: Install Rust nightly
-        uses: dtolnay/rust-toolchain@nightly
-        with:
-          components: rustfmt
-      - name: Install cargo-make
-        uses: taiki-e/install-action@cargo-make
-      - name: Check formatting
-        run: cargo make lint-format
-      - name: Check documentation
-        run: cargo make lint-docs
-      - name: Check conventional commits
-        uses: crate-ci/committed@master
-        with:
-          args: "-vv"
-          commits: HEAD
-      - name: Check typos
-        uses: crate-ci/typos@master
-      - name: Lint dependencies
-        uses: EmbarkStudios/cargo-deny-action@v1
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@nightly
+        with: { components: rustfmt }
+      - run: cargo xtask lint-formatting
 
-  clippy:
+  # Check for typos in the codebase.
+  # See <https://github.com/crate-ci/typos/>
+  lint-typos:
+    name: Check Typos
     runs-on: ubuntu-latest
     steps:
-      - name: Checkout
-        uses: actions/checkout@v3
-      - name: Install Rust stable
-        uses: dtolnay/rust-toolchain@stable
-        with:
-          components: clippy
-      - name: Install cargo-make
-        uses: taiki-e/install-action@cargo-make
-      - name: Run cargo make clippy-all
-        run: cargo make clippy
+      - 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
+
+  # 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: Swatinem/rust-cache@v2
+      - run: cargo xtask lint-clippy
+
+  # Run markdownlint on all markdown files in the repository.
+  lint-markdown:
+    name: Check Markdown
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: DavidAnson/markdownlint-cli2-action@v18
+        with:
+          globs: |
+            '**/*.md'
+            '!target'
+
+  # Run cargo coverage. This will generate a coverage report and upload it to codecov.
+  # <https://app.codecov.io/gh/ratatui/ratatui>
   coverage:
+    name: Coverage Report
     runs-on: ubuntu-latest
     steps:
-      - name: Checkout
-        uses: actions/checkout@v3
-      - name: Install Rust stable
-        uses: dtolnay/rust-toolchain@stable
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
         with:
           components: llvm-tools
-      - name: Install cargo-llvm-cov and cargo-make
-        uses: taiki-e/install-action@v2
-        with:
-          tool: cargo-llvm-cov,cargo-make
-      - name: Generate coverage
-        run: cargo make coverage
-      - name: Upload to codecov.io
-        uses: codecov/codecov-action@v3
+      - uses: taiki-e/install-action@cargo-llvm-cov
+      - uses: Swatinem/rust-cache@v2
+      - 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:
-        os: [ ubuntu-latest, windows-latest, macos-latest ]
-        toolchain: [ "1.67.0", "stable" ]
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        toolchain: ["1.74.0", "stable"]
     runs-on: ${{ matrix.os }}
     steps:
-      - name: Checkout
-        uses: actions/checkout@v3
-      - name: Install Rust {{ matrix.toolchain }}
-        uses: dtolnay/rust-toolchain@master
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@master
         with:
           toolchain: ${{ matrix.toolchain }}
-      - name: Install cargo-make
-        uses: taiki-e/install-action@cargo-make
-      - name: Run cargo make check
-        run: cargo make check
-        env:
-          RUST_BACKTRACE: full
+      - uses: Swatinem/rust-cache@v2
+      - run: cargo xtask check
 
-  test-doc:
-    strategy:
-      fail-fast: false
-      matrix:
-        os: [ ubuntu-latest, windows-latest, macos-latest ]
-    runs-on: ${{ matrix.os }}
+  # Check if README.md is up-to-date with the crate's documentation.
+  check-readme:
+    name: Check README
+    runs-on: ubuntu-latest
     steps:
-      - name: Checkout
-        uses: actions/checkout@v3
-      - name: Install Rust stable
-        uses: dtolnay/rust-toolchain@stable
-      - name: Install cargo-make
-        uses: taiki-e/install-action@cargo-make
-      - name: Test docs
-        run: cargo make test-doc
-        env:
-          RUST_BACKTRACE: full
+      - uses: actions/checkout@v4
+      - uses: Swatinem/rust-cache@v2
+      - uses: taiki-e/install-action@cargo-rdme
+      - run: cargo xtask check-readme
 
-  test:
+  # Run cargo rustdoc with the same options that would be used by docs.rs, taking into account the
+  # package.metadata.docs.rs configured in Cargo.toml. https://github.com/dtolnay/cargo-docs-rs
+  lint-docs:
+    name: Check Docs
+    runs-on: ubuntu-latest
+    env:
+      RUSTDOCFLAGS: -Dwarnings
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@nightly
+      - uses: dtolnay/install@cargo-docs-rs
+      - uses: Swatinem/rust-cache@v2
+      - run: cargo xtask lint-docs
+
+  # Run cargo test on the documentation of the crate. This will catch any code examples that don't
+  # compile, or any other issues in the documentation.
+  test-docs:
+    name: Test Docs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - run: cargo xtask test-docs
+
+  # Run cargo test on the libraries of the crate.
+  test-libs:
+    name: Test Libs ${{ matrix.toolchain }}
+    runs-on: ubuntu-latest
     strategy:
       fail-fast: false
       matrix:
-        os: [ ubuntu-latest, windows-latest, macos-latest ]
-        toolchain: [ "1.67.0", "stable" ]
-        backend: [ crossterm, termion, termwiz ]
+        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]
+        backend: [crossterm, termion, termwiz]
         exclude:
           # termion is not supported on windows
           - os: windows-latest
             backend: termion
-    runs-on: ${{ matrix.os }}
     steps:
-      - name: Checkout
-        uses: actions/checkout@v3
-      - name: Install Rust ${{ matrix.toolchain }}}
-        uses: dtolnay/rust-toolchain@master
-        with:
-          toolchain: ${{ matrix.toolchain }}
-      - name: Install cargo-make
-        uses: taiki-e/install-action@cargo-make
-      - name: Test ${{ matrix.backend }}
-        run: cargo make test-backend ${{ matrix.backend }}
-        env:
-          RUST_BACKTRACE: full
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - run: cargo xtask test-backend ${{ matrix.backend }}

.github/workflows/release-alpha.yml

@@ -0,0 +1,48 @@
+name: Release alpha version
+
+on:
+  workflow_dispatch:
+  schedule:
+    # At 00:00 on Saturday
+    # https://crontab.guru/#0_0_*_*_6
+    - cron: "0 0 * * 6"
+
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  publish-alpha:
+    name: Create an alpha release
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout the repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Calculate the next release
+        run: .github/workflows/calculate-alpha-release.bash
+
+      - name: Install Rust stable
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Publish
+        run: cargo publish --allow-dirty --token ${{ secrets.CARGO_TOKEN }}
+
+      - name: Generate a changelog
+        uses: orhun/git-cliff-action@v4
+        with:
+          config: cliff.toml
+          args: --unreleased --tag ${{ env.NEXT_TAG }} --strip header
+        env:
+          OUTPUT: BODY.md
+
+      - name: Publish on GitHub
+        uses: ncipollo/release-action@v1
+        with:
+          tag: ${{ env.NEXT_TAG }}
+          prerelease: true
+          bodyFile: BODY.md

.github/workflows/release-stable.yml

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

.gitignore

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

BREAKING-CHANGES.md

@@ -0,0 +1,890 @@
+# Breaking Changes
+
+This document contains a list of breaking changes in each version and some notes to help migrate
+between versions. It is compiled manually from the commit history and changelog. We also tag PRs on
+GitHub with a [breaking change] label.
+
+[breaking change]: (https://github.com/ratatui/ratatui/issues?q=label%3A%22breaking+change%22)
+
+## Summary
+
+This is a quick summary of the sections below:
+
+- [Unreleased](#unreleased)
+  - The `From` impls for backend types are now replaced with more specific traits
+- [v0.29.0](#v0290)
+  - `Sparkline::data` takes `IntoIterator<Item = SparklineBar>` instead of `&[u64]` and is no longer const
+  - Removed public fields from `Rect` iterators
+  - `Line` now implements `From<Cow<str>`
+  - `Table::highlight_style` is now `Table::row_highlight_style`
+  - `Tabs::select` now accepts `Into<Option<usize>>`
+  - `Color::from_hsl` is now behind the `palette` feature
+- [v0.28.0](#v0280)
+  - `Backend::size` returns `Size` instead of `Rect`
+  - `Backend` trait migrates to `get/set_cursor_position`
+  - Ratatui now requires Crossterm 0.28.0
+  - `Axis::labels` now accepts `IntoIterator<Into<Line>>`
+  - `Layout::init_cache` no longer returns bool and takes a `NonZeroUsize` instead of `usize`
+  - `ratatui::terminal` module is now private
+  - `ToText` no longer has a lifetime
+  - `Frame::size` is deprecated and renamed to `Frame::area`
+- [v0.27.0](#v0270)
+  - List no clamps the selected index to list
+  - Prelude items added / removed
+  - 'termion' updated to 4.0
+  - `Rect::inner` takes `Margin` directly instead of reference
+  - `Buffer::filled` takes `Cell` directly instead of reference
+  - `Stylize::bg()` now accepts `Into<Color>`
+  - Removed deprecated `List::start_corner`
+  - `LineGauge::gauge_style` is deprecated
+- [v0.26.0](#v0260)
+  - `Flex::Start` is the new default flex mode for `Layout`
+  - `patch_style` & `reset_style` now consume and return `Self`
+  - Removed deprecated `Block::title_on_bottom`
+  - `Line` now has an extra `style` field which applies the style to the entire line
+  - `Block` style methods cannot be created in a const context
+  - `Tabs::new()` now accepts `IntoIterator<Item: Into<Line<'a>>>`
+  - `Table::new` now accepts `IntoIterator<Item: Into<Row<'a>>>`.
+- [v0.25.0](#v0250)
+  - Removed `Axis::title_style` and `Buffer::set_background`
+  - `List::new()` now accepts `IntoIterator<Item = Into<ListItem<'a>>>`
+  - `Table::new()` now requires specifying the widths
+  - `Table::widths()` now accepts `IntoIterator<Item = AsRef<Constraint>>`
+  - Layout::new() now accepts direction and constraint parameters
+  - The default `Tabs::highlight_style` is now `Style::new().reversed()`
+- [v0.24.0](#v0240)
+  - MSRV is now 1.70.0
+  - `ScrollbarState`: `position`, `content_length`, and `viewport_content_length` are now `usize`
+  - `BorderType`: `line_symbols` is now `border_symbols` and returns `symbols::border::set`
+  - `Frame<'a, B: Backend>` is now `Frame<'a>`
+  - `Stylize` shorthands for `String` now consume the value and return `Span<'static>`
+  - `Spans` is removed
+- [v0.23.0](#v0230)
+  - `Scrollbar`: `track_symbol` now takes `Option<&str>`
+  - `Scrollbar`: symbols moved to `symbols` module
+  - MSRV is now 1.67.0
+- [v0.22.0](#v0220)
+  - `serde` representation of `Borders` and `Modifiers` has changed
+- [v0.21.0](#v0210)
+  - MSRV is now 1.65.0
+  - `terminal::ViewPort` is now an enum
+  - `"".as_ref()` must be annotated to implement `Into<Text<'a>>`
+  - `Marker::Block` renders as a block char instead of a bar char
+- [v0.20.0](#v0200)
+  - MSRV is now 1.63.0
+  - `List` no longer ignores empty strings
+
+## Unreleased (0.30.0)
+
+### `WidgetRef` no longer has a blanket implementation of Widget
+
+Previously there was a blanket implementation of Widget for WidgetRef. This has been reversed to
+instead be a blanket implementation of WidgetRef for all &W where W: Widget. Any widgets that
+previously implemented WidgetRef directly should now instead implement Widget for a reference to the
+type.
+
+```diff
+-impl WidgetRef for Foo {
+-    fn render_ref(&self, area: Rect, buf: &mut Buffer)
++impl Widget for &Foo {
++    fn render(self, area: Rect, buf: &mut Buffer)
+}
+```
+
+### The `From` impls for backend types are now replaced with more specific traits [#1464]
+
+[#1464]: https://github.com/ratatui/ratatui/pull/1464
+
+Crossterm gains `ratatui::backend::crossterm::{FromCrossterm, IntoCrossterm}`
+Termwiz gains `ratatui::backend::termwiz::{FromTermwiz, IntoTermwiz}`
+
+This is necessary in order to avoid the orphan rule when implementing `From` for crossterm types
+once the crossterm types are moved to a separate crate.
+
+```diff
++ use ratatui::backend::crossterm::{FromCrossterm, IntoCrossterm};
+
+let crossterm_color = crossterm::style::Color::Black;
+- let ratatui_color = crossterm_color.into();
+- let ratatui_color = ratatui::style::Color::from(crossterm_color);
++ let ratatui_color = ratatui::style::Color::from_crossterm(crossterm_color);
+- let crossterm_color = ratatui_color.into();
+- let crossterm_color = crossterm::style::Color::from(ratatui_color);
++ let crossterm_color = ratatui_color.into_crossterm();
+
+let crossterm_attribute = crossterm::style::types::Attribute::Bold;
+- let ratatui_modifier = crossterm_attribute.into();
+- let ratatui_modifier = ratatui::style::Modifier::from(crossterm_attribute);
++ let ratatui_modifier = ratatui::style::Modifier::from_crossterm(crossterm_attribute);
+- let crossterm_attribute = ratatui_modifier.into();
+- let crossterm_attribute = crossterm::style::types::Attribute::from(ratatui_modifier);
++ let crossterm_attribute = ratatui_modifier.into_crossterm();
+```
+
+Similar conversions for `ContentStyle` -> `Style` and `Attributes` -> `Modifier` exist for
+Crossterm and the various Termion and Termwiz types as well.
+
+### `Bar::label()` and `BarGroup::label()` now accepts `Into<Line<'a>>`. ([#1471])
+
+[#1471]: https://github.com/ratatui/ratatui/pull/1471
+
+Previously `Bar::label()` and `BarGroup::label()` accepted `Line<'a>`, but they now accepts `Into<Line<'a>>`.
+
+for `Bar::label()`:
+
+```diff
+- Bar::default().label("foo".into());
++ Bar::default().label("foo");
+```
+
+for `BarGroup::label()`:
+
+```diff
+- BarGroup::default().label("bar".into());
++ BarGroup::default().label("bar");
+```
+
+### `Bar::text_value` now accepts `Into<String>` ([#1471])
+
+Previously `Bar::text_value` accepted `String`, but now it accepts `Into<String>`.
+
+for `Bar::text_value()`:
+
+```diff
+- Bar::default().text_value("foobar".into());
++ Bar::default().text_value("foobar");
+```
+
+## [v0.29.0](https://github.com/ratatui/ratatui/releases/tag/v0.29.0)
+
+### `Sparkline::data` takes `IntoIterator<Item = SparklineBar>` instead of `&[u64]` and is no longer const ([#1326])
+
+[#1326]: https://github.com/ratatui/ratatui/pull/1326
+
+The `Sparkline::data` method has been modified to accept `IntoIterator<Item = SparklineBar>`
+instead of `&[u64]`.
+
+`SparklineBar` is a struct that contains an `Option<u64>` value, which represents an possible
+_absent_ value, as distinct from a `0` value. This change allows the `Sparkline` to style
+data points differently, depending on whether they are present or absent.
+
+`SparklineBar` also contains an `Option<Style>` that will be used to apply a style the bar in
+addition to any other styling applied to the `Sparkline`.
+
+Several `From` implementations have been added to `SparklineBar` to support existing callers who
+provide `&[u64]` and other types that can be converted to `SparklineBar`, such as `Option<u64>`.
+
+If you encounter any type inference issues, you may need to provide an explicit type for the data
+passed to `Sparkline::data`. For example, if you are passing a single value, you may need to use
+`into()` to convert it to form that can be used as a `SparklineBar`:
+
+```diff
+let value = 1u8;
+- Sparkline::default().data(&[value.into()]);
++ Sparkline::default().data(&[u64::from(value)]);
+```
+
+As a consequence of this change, the `data` method is no longer a `const fn`.
+
+### `Color::from_hsl` is now behind the `palette` feature and accepts `palette::Hsl` ([#1418])
+
+[#1418]: https://github.com/ratatui/ratatui/pull/1418
+
+Previously `Color::from_hsl` accepted components as individual f64 parameters. It now accepts a
+single `palette::Hsl` value and is gated behind a `palette` feature flag.
+
+```diff
+- Color::from_hsl(360.0, 100.0, 100.0)
++ Color::from_hsl(Hsl::new(360.0, 100.0, 100.0))
+```
+
+### Removed public fields from `Rect` iterators ([#1358], [#1424])
+
+[#1358]: https://github.com/ratatui/ratatui/pull/1358
+[#1424]: https://github.com/ratatui/ratatui/pull/1424
+
+The `pub` modifier has been removed from fields on the `Columns`,`Rows`, and `Positions` iterators.
+These fields were not intended to be public and should not have been accessed directly.
+
+### `Rect::area()` now returns u32 instead of u16 ([#1378])
+
+[#1378]: https://github.com/ratatui/ratatui/pull/1378
+
+This is likely to impact anything which relies on `Rect::area` maxing out at u16::MAX. It can now
+return up to u16::MAX * u16::MAX (2^32 - 2^17 + 1).
+
+### `Line` now implements `From<Cow<str>` ([#1373])
+
+[#1373]: https://github.com/ratatui/ratatui/pull/1373
+
+As this adds an extra conversion, ambiguous inferred expressions may no longer compile.
+
+```rust
+// given:
+struct Foo { ... }
+impl From<Foo> for String { ... }
+impl From<Foo> for Cow<str> { ... }
+
+let foo = Foo { ... };
+let line = Line::from(foo); // now fails due to now ambiguous inferred type
+// replace with e.g.
+let line = Line::from(String::from(foo));
+```
+
+### `Tabs::select()` now accepts `Into<Option<usize>>` ([#1413])
+
+[#1413]: https://github.com/ratatui/ratatui/pull/1413
+
+Previously `Tabs::select()` accepted `usize`, but it now accepts `Into<Option<usize>>`. This breaks
+any code already using parameter type inference:
+
+```diff
+let selected = 1u8;
+- let tabs = Tabs::new(["A", "B"]).select(selected.into())
++ let tabs = Tabs::new(["A", "B"]).select(selected as usize)
+```
+
+### `Table::highlight_style` is now `Table::row_highlight_style` ([#1331])
+
+[#1331]: https://github.com/ratatui/ratatui/pull/1331
+
+The `Table::highlight_style` is now deprecated in favor of `Table::row_highlight_style`.
+
+Also, the serialized output of the `TableState` will now include the "selected_column" field.
+Software that manually parse the serialized the output (with anything other than the `Serialize`
+implementation on `TableState`) may have to be refactored if the "selected_column" field is not
+accounted for. This does not affect users who rely on the `Deserialize`, or `Serialize`
+implementation on the state.
+
+## [v0.28.0](https://github.com/ratatui/ratatui/releases/tag/v0.28.0)
+
+### `Backend::size` returns `Size` instead of `Rect` ([#1254])
+
+[#1254]: https://github.com/ratatui/ratatui/pull/1254
+
+The `Backend::size` method returns a `Size` instead of a `Rect`.
+There is no need for the position here as it was always 0,0.
+
+### `Backend` trait migrates to `get/set_cursor_position` ([#1284])
+
+[#1284]: https://github.com/ratatui/ratatui/pull/1284
+
+If you just use the types implementing the `Backend` trait, you will see deprecation hints but
+nothing is a breaking change for you.
+
+If you implement the Backend trait yourself, you need to update the implementation and add the
+`get/set_cursor_position` method. You can remove the `get/set_cursor` methods as they are deprecated
+and a default implementation for them exists.
+
+### Ratatui now requires Crossterm 0.28.0 ([#1278])
+
+[#1278]: https://github.com/ratatui/ratatui/pull/1278
+
+Crossterm is updated to version 0.28.0, which is a semver incompatible version with the previous
+version (0.27.0). Ratatui re-exports the version of crossterm that it is compatible with under
+`ratatui::crossterm`, which can be used to avoid incompatible versions in your dependency list.
+
+### `Axis::labels()` now accepts `IntoIterator<Into<Line>>` ([#1273] and [#1283])
+
+[#1273]: https://github.com/ratatui/ratatui/pull/1173
+[#1283]: https://github.com/ratatui/ratatui/pull/1283
+
+Previously Axis::labels accepted `Vec<Span>`. Any code that uses conversion methods that infer the
+type will need to be rewritten as the compiler cannot infer the correct type.
+
+```diff
+- Axis::default().labels(vec!["a".into(), "b".into()])
++ Axis::default().labels(["a", "b"])
+```
+
+### `Layout::init_cache` no longer returns bool and takes a `NonZeroUsize` instead of `usize` ([#1245])
+
+[#1245]: https://github.com/ratatui/ratatui/pull/1245
+
+```diff
+- let is_initialized = Layout::init_cache(100);
++ Layout::init_cache(NonZeroUsize::new(100).unwrap());
+```
+
+### `ratatui::terminal` module is now private ([#1160])
+
+[#1160]: https://github.com/ratatui/ratatui/pull/1160
+
+The `terminal` module is now private and can not be used directly. The types under this module are
+exported from the root of the crate. This reduces clashes with other modules in the backends that
+are also named terminal, and confusion about module exports for newer Rust users.
+
+```diff
+- use ratatui::terminal::{CompletedFrame, Frame, Terminal, TerminalOptions, ViewPort};
++ use ratatui::{CompletedFrame, Frame, Terminal, TerminalOptions, ViewPort};
+```
+
+### `ToText` no longer has a lifetime ([#1234])
+
+[#1234]: https://github.com/ratatui/ratatui/pull/1234
+
+This change simplifies the trait and makes it easier to implement.
+
+### `Frame::size` is deprecated and renamed to `Frame::area` ([#1293])
+
+[#1293]: https://github.com/ratatui/ratatui/pull/1293
+
+`Frame::size` is renamed to `Frame::area` as it's the more correct name.
+
+## [v0.27.0](https://github.com/ratatui/ratatui/releases/tag/v0.27.0)
+
+### List no clamps the selected index to list ([#1159])
+
+[#1149]: https://github.com/ratatui/ratatui/pull/1149
+
+The `List` widget now clamps the selected index to the bounds of the list when navigating with
+`first`, `last`, `previous`, and `next`, as well as when setting the index directly with `select`.
+
+Previously selecting an index past the end of the list would show treat the list as having a
+selection which was not visible. Now the last item in the list will be selected instead.
+
+### Prelude items added / removed ([#1149])
+
+The following items have been removed from the prelude:
+
+- `style::Styled` - this trait is useful for widgets that want to
+  support the Stylize trait, but it adds complexity as widgets have two
+  `style` methods and a `set_style` method.
+- `symbols::Marker` - this item is used by code that needs to draw to
+  the `Canvas` widget, but it's not a common item that would be used by
+  most users of the library.
+- `terminal::{CompletedFrame, TerminalOptions, Viewport}` - these items
+  are rarely used by code that needs to interact with the terminal, and
+  they're generally only ever used once in any app.
+
+The following items have been added to the prelude:
+
+- `layout::{Position, Size}` - these items are used by code that needs
+  to interact with the layout system. These are newer items that were
+  added in the last few releases, which should be used more liberally.
+  This may cause conflicts for types defined elsewhere with a similar
+  name.
+
+To update your app:
+
+```diff
+// if your app uses Styled::style() or Styled::set_style():
+-use ratatui::prelude::*;
++use ratatui::{prelude::*, style::Styled};
+
+// if your app uses symbols::Marker:
+-use ratatui::prelude::*;
++use ratatui::{prelude::*, symbols::Marker}
+
+// if your app uses terminal::{CompletedFrame, TerminalOptions, Viewport}
+-use ratatui::prelude::*;
++use ratatui::{prelude::*, terminal::{CompletedFrame, TerminalOptions, Viewport}};
+
+// to disambiguate existing types named Position or Size:
+- use some_crate::{Position, Size};
+- let size: Size = ...;
+- let position: Position = ...;
++ let size: some_crate::Size = ...;
++ let position: some_crate::Position = ...;
+```
+
+### Termion is updated to 4.0 [#1106]
+
+Changelog: <https://gitlab.redox-os.org/redox-os/termion/-/blob/master/CHANGELOG.md>
+
+A change is only necessary if you were matching on all variants of the `MouseEvent` enum without a
+wildcard. In this case, you need to either handle the two new variants, `MouseLeft` and
+`MouseRight`, or add a wildcard.
+
+[#1106]: https://github.com/ratatui/ratatui/pull/1106
+
+### `Rect::inner` takes `Margin` directly instead of reference ([#1008])
+
+[#1008]: https://github.com/ratatui/ratatui/pull/1008
+
+`Margin` needs to be passed without reference now.
+
+```diff
+-let area = area.inner(&Margin {
++let area = area.inner(Margin {
+     vertical: 0,
+     horizontal: 2,
+ });
+```
+
+### `Buffer::filled` takes `Cell` directly instead of reference ([#1148])
+
+[#1148]: https://github.com/ratatui/ratatui/pull/1148
+
+`Buffer::filled` moves the `Cell` instead of taking a reference.
+
+```diff
+-Buffer::filled(area, &Cell::new("X"));
++Buffer::filled(area, Cell::new("X"));
+```
+
+### `Stylize::bg()` now accepts `Into<Color>` ([#1103])
+
+[#1103]: https://github.com/ratatui/ratatui/pull/1103
+
+Previously, `Stylize::bg()` accepted `Color` but now accepts `Into<Color>`. This allows more
+flexible types from calling scopes, though it can break some type inference in the calling scope.
+
+### Remove deprecated `List::start_corner` and `layout::Corner` ([#759])
+
+[#759]: https://github.com/ratatui/ratatui/pull/759
+
+`List::start_corner` was deprecated in v0.25. Use `List::direction` and `ListDirection` instead.
+
+```diff
+- list.start_corner(Corner::TopLeft);
+- list.start_corner(Corner::TopRight);
+// This is not an error, BottomRight rendered top to bottom previously
+- list.start_corner(Corner::BottomRight);
+// all becomes
++ list.direction(ListDirection::TopToBottom);
+```
+
+```diff
+- list.start_corner(Corner::BottomLeft);
+// becomes
++ list.direction(ListDirection::BottomToTop);
+```
+
+`layout::Corner` was removed entirely.
+
+### `LineGauge::gauge_style` is deprecated ([#565])
+
+[#565]: https://github.com/ratatui/ratatui/pull/1148
+
+`LineGauge::gauge_style` is deprecated and replaced with `LineGauge::filled_style` and `LineGauge::unfilled_style`:
+
+```diff
+let gauge = LineGauge::default()
+- .gauge_style(Style::default().fg(Color::Red).bg(Color::Blue)
++ .filled_style(Style::default().fg(Color::Green))
++ .unfilled_style(Style::default().fg(Color::White));
+```
+
+## [v0.26.0](https://github.com/ratatui/ratatui/releases/tag/v0.26.0)
+
+### `Flex::Start` is the new default flex mode for `Layout` ([#881])
+
+[#881]: https://github.com/ratatui/ratatui/pull/881
+
+Previously, constraints would stretch to fill all available space, violating constraints if
+necessary.
+
+With v0.26.0, `Flex` modes are introduced, and the default is `Flex::Start`, which will align
+areas associated with constraints to be beginning of the area. With v0.26.0, additionally,
+`Min` constraints grow to fill excess space. These changes will allow users to build layouts
+more easily.
+
+With v0.26.0, users will most likely not need to change what constraints they use to create
+existing layouts with `Flex::Start`. However, to get old behavior, use `Flex::Legacy`.
+
+```diff
+- let rects = Layout::horizontal([Length(1), Length(2)]).split(area);
+// becomes
++ let rects = Layout::horizontal([Length(1), Length(2)]).flex(Flex::Legacy).split(area);
+```
+
+### `Table::new()` now accepts `IntoIterator<Item: Into<Row<'a>>>` ([#774])
+
+[#774]: https://github.com/ratatui/ratatui/pull/774
+
+Previously, `Table::new()` accepted `IntoIterator<Item=Row<'a>>`. The argument change to
+`IntoIterator<Item: Into<Row<'a>>>`, This allows more flexible types from calling scopes, though it
+can some break type inference in the calling scope for empty containers.
+
+This can be resolved either by providing an explicit type (e.g. `Vec::<Row>::new()`), or by using
+`Table::default()`.
+
+```diff
+- let table = Table::new(vec![], widths);
+// becomes
++ let table = Table::default().widths(widths);
+```
+
+### `Tabs::new()` now accepts `IntoIterator<Item: Into<Line<'a>>>` ([#776])
+
+[#776]: https://github.com/ratatui/ratatui/pull/776
+
+Previously, `Tabs::new()` accepted `Vec<T>` where `T: Into<Line<'a>>`. This allows more flexible
+types from calling scopes, though it can break some type inference in the calling scope.
+
+This typically occurs when collecting an iterator prior to calling `Tabs::new`, and can be resolved
+by removing the call to `.collect()`.
+
+```diff
+- let tabs = Tabs::new((0.3).map(|i| format!("{i}")).collect());
+// becomes
++ let tabs = Tabs::new((0.3).map(|i| format!("{i}")));
+```
+
+### Table::default() now sets segment_size to None and column_spacing to ([#751])
+
+[#751]: https://github.com/ratatui/ratatui/pull/751
+
+The default() implementation of Table now sets the column_spacing field to 1 and the segment_size
+field to `SegmentSize::None`. This will affect the rendering of a small amount of apps.
+
+To use the previous default values, call `table.segment_size(Default::default())` and
+`table.column_spacing(0)`.
+
+### `patch_style` & `reset_style` now consumes and returns `Self` ([#754])
+
+[#754]: https://github.com/ratatui/ratatui/pull/754
+
+Previously, `patch_style` and `reset_style` in `Text`, `Line` and `Span` were using a mutable
+reference to `Self`. To be more consistent with the rest of `ratatui`, which is using fluent
+setters, these now take ownership of `Self` and return it.
+
+The following example shows how to migrate for `Line`, but the same applies for `Text` and `Span`.
+
+```diff
+- let mut line = Line::from("foobar");
+- line.patch_style(style);
+// becomes
++ let line = Line::new("foobar").patch_style(style);
+```
+
+### Remove deprecated `Block::title_on_bottom` ([#757])
+
+`Block::title_on_bottom` was deprecated in v0.22. Use `Block::title` and `Title::position` instead.
+
+```diff
+- block.title("foobar").title_on_bottom();
++ block.title(Title::from("foobar").position(Position::Bottom));
+```
+
+### `Block` style methods cannot be used in a const context ([#720])
+
+[#720]: https://github.com/ratatui/ratatui/pull/720
+
+Previously the `style()`, `border_style()` and `title_style()` methods could be used to create a
+`Block` in a constant context. These now accept `Into<Style>` instead of `Style`. These methods no
+longer can be called from a constant context.
+
+### `Line` now has a `style` field that applies to the entire line ([#708])
+
+[#708]: https://github.com/ratatui/ratatui/pull/708
+
+Previously the style of a `Line` was stored in the `Span`s that make up the line. Now the `Line`
+itself has a `style` field, which can be set with the `Line::styled` method. Any code that creates
+`Line`s using the struct initializer instead of constructors will fail to compile due to the added
+field. This can be easily fixed by adding `..Default::default()` to the field list or by using a
+constructor method (`Line::styled()`, `Line::raw()`) or conversion method (`Line::from()`).
+
+Each `Span` contained within the line will no longer have the style that is applied to the line in
+the `Span::style` field.
+
+```diff
+  let line = Line {
+      spans: vec!["".into()],
+      alignment: Alignment::Left,
++     ..Default::default()
+  };
+
+  // or
+
+  let line = Line::raw(vec!["".into()])
+      .alignment(Alignment::Left);
+```
+
+## [v0.25.0](https://github.com/ratatui/ratatui/releases/tag/v0.25.0)
+
+### Removed `Axis::title_style` and `Buffer::set_background` ([#691])
+
+[#691]: https://github.com/ratatui/ratatui/pull/691
+
+These items were deprecated since 0.10.
+
+- You should use styling capabilities of [`text::Line`] given as argument of [`Axis::title`]
+  instead of `Axis::title_style`
+- You should use styling capabilities of [`Buffer::set_style`] instead of `Buffer::set_background`
+
+[`text::Line`]: https://docs.rs/ratatui/latest/ratatui/text/struct.Line.html
+[`Axis::title`]: https://docs.rs/ratatui/latest/ratatui/widgets/struct.Axis.html#method.title
+[`Buffer::set_style`]: https://docs.rs/ratatui/latest/ratatui/buffer/struct.Buffer.html#method.set_style
+
+### `List::new()` now accepts `IntoIterator<Item = Into<ListItem<'a>>>` ([#672])
+
+[#672]: https://github.com/ratatui/ratatui/pull/672
+
+Previously `List::new()` took `Into<Vec<ListItem<'a>>>`. This change will throw a compilation
+error for `IntoIterator`s with an indeterminate item (e.g. empty vecs).
+
+E.g.
+
+```diff
+- let list = List::new(vec![]);
+// becomes
++ let list = List::default();
+```
+
+### The default `Tabs::highlight_style` is now `Style::new().reversed()` ([#635])
+
+[#635]: https://github.com/ratatui/ratatui/pull/635
+
+Previously the default highlight style for tabs was `Style::default()`, which meant that a `Tabs`
+widget in the default configuration would not show any indication of the selected tab.
+
+### The default `Tabs::highlight_style` is now `Style::new().reversed()` ([#635])
+
+Previously the default highlight style for tabs was `Style::default()`, which meant that a `Tabs`
+widget in the default configuration would not show any indication of the selected tab.
+
+### `Table::new()` now requires specifying the widths of the columns ([#664])
+
+[#664]: https://github.com/ratatui/ratatui/pull/664
+
+Previously `Table`s could be constructed without `widths`. In almost all cases this is an error.
+A new `widths` parameter is now mandatory on `Table::new()`. Existing code of the form:
+
+```diff
+- Table::new(rows).widths(widths)
+```
+
+Should be updated to:
+
+```diff
++ Table::new(rows, widths)
+```
+
+For ease of automated replacement in cases where the amount of code broken by this change is large
+or complex, it may be convenient to replace `Table::new` with `Table::default().rows`.
+
+```diff
+- Table::new(rows).block(block).widths(widths);
+// becomes
++ Table::default().rows(rows).widths(widths)
+```
+
+### `Table::widths()` now accepts `IntoIterator<Item = AsRef<Constraint>>` ([#663])
+
+[#663]: https://github.com/ratatui/ratatui/pull/663
+
+Previously `Table::widths()` took a slice (`&'a [Constraint]`). This change will introduce clippy
+`needless_borrow` warnings for places where slices are passed to this method. To fix these, remove
+the `&`.
+
+E.g.
+
+```diff
+- let table = Table::new(rows).widths(&[Constraint::Length(1)]);
+// becomes
++ let table = Table::new(rows, [Constraint::Length(1)]);
+```
+
+### Layout::new() now accepts direction and constraint parameters ([#557])
+
+[#557]: https://github.com/ratatui/ratatui/pull/557
+
+Previously layout new took no parameters. Existing code should either use `Layout::default()` or
+the new constructor.
+
+```rust
+let layout = layout::new()
+  .direction(Direction::Vertical)
+  .constraints([Constraint::Min(1), Constraint::Max(2)]);
+// becomes either
+let layout = layout::default()
+  .direction(Direction::Vertical)
+  .constraints([Constraint::Min(1), Constraint::Max(2)]);
+// or
+let layout = layout::new(Direction::Vertical, [Constraint::Min(1), Constraint::Max(2)]);
+```
+
+## [v0.24.0](https://github.com/ratatui/ratatui/releases/tag/v0.24.0)
+
+### `ScrollbarState` field type changed from `u16` to `usize` ([#456])
+
+[#456]: https://github.com/ratatui/ratatui/pull/456
+
+In order to support larger content lengths, the `position`, `content_length` and
+`viewport_content_length` methods on `ScrollbarState` now take `usize` instead of `u16`
+
+### `BorderType::line_symbols` renamed to `border_symbols` ([#529])
+
+[#529]: https://github.com/ratatui/ratatui/issues/529
+
+Applications can now set custom borders on a `Block` by calling `border_set()`. The
+`BorderType::line_symbols()` is renamed to `border_symbols()` and now returns a new struct
+`symbols::border::Set`. E.g.:
+
+```diff
+- let line_set: symbols::line::Set = BorderType::line_symbols(BorderType::Plain);
+// becomes
++ let border_set: symbols::border::Set = BorderType::border_symbols(BorderType::Plain);
+```
+
+### Generic `Backend` parameter removed from `Frame` ([#530])
+
+[#530]: https://github.com/ratatui/ratatui/issues/530
+
+`Frame` is no longer generic over Backend. Code that accepted `Frame<Backend>` will now need to
+accept `Frame`. To migrate existing code, remove any generic parameters from code that uses an
+instance of a Frame. E.g.:
+
+```diff
+- fn ui<B: Backend>(frame: &mut Frame<B>) { ... }
+// becomes
++ fn ui(frame: Frame) { ... }
+```
+
+### `Stylize` shorthands now consume rather than borrow `String` ([#466])
+
+[#466]: https://github.com/ratatui/ratatui/issues/466
+
+In order to support using `Stylize` shorthands (e.g. `"foo".red()`) on temporary `String` values, a
+new implementation of `Stylize` was added that returns a `Span<'static>`. This causes the value to
+be consumed rather than borrowed. Existing code that expects to use the string after a call will no
+longer compile. E.g.
+
+```diff
+- let s = String::new("foo");
+- let span1 = s.red();
+- let span2 = s.blue(); // will no longer compile as s is consumed by the previous line
+// becomes
++ let span1 = s.clone().red();
++ let span2 = s.blue();
+```
+
+### Deprecated `Spans` type removed (replaced with `Line`) ([#426])
+
+[#426]: https://github.com/ratatui/ratatui/issues/426
+
+`Spans` was replaced with `Line` in 0.21.0. `Buffer::set_spans` was replaced with
+`Buffer::set_line`.
+
+```diff
+- let spans = Spans::from(some_string_str_span_or_vec_span);
+- buffer.set_spans(0, 0, spans, 10);
+// becomes
++ let line - Line::from(some_string_str_span_or_vec_span);
++ buffer.set_line(0, 0, line, 10);
+```
+
+## [v0.23.0](https://github.com/ratatui/ratatui/releases/tag/v0.23.0)
+
+### `Scrollbar::track_symbol()` now takes an `Option<&str>` instead of `&str` ([#360])
+
+[#360]: https://github.com/ratatui/ratatui/issues/360
+
+The track symbol of `Scrollbar` is now optional, this method now takes an optional value.
+
+```diff
+- let scrollbar = Scrollbar::default().track_symbol("|");
+// becomes
++ let scrollbar = Scrollbar::default().track_symbol(Some("|"));
+```
+
+### `Scrollbar` symbols moved to `symbols::scrollbar` and `widgets::scrollbar` module is private ([#330])
+
+[#330]: https://github.com/ratatui/ratatui/issues/330
+
+The symbols for defining scrollbars have been moved to the `symbols` module from the
+`widgets::scrollbar` module which is no longer public. To update your code update any imports to the
+new module locations. E.g.:
+
+```diff
+- use ratatui::{widgets::scrollbar::{Scrollbar, Set}};
+// becomes
++ use ratatui::{widgets::Scrollbar, symbols::scrollbar::Set}
+```
+
+### MSRV updated to 1.67 ([#361])
+
+[#361]: https://github.com/ratatui/ratatui/issues/361
+
+The MSRV of ratatui is now 1.67 due to an MSRV update in a dependency (`time`).
+
+## [v0.22.0](https://github.com/ratatui/ratatui/releases/tag/v0.22.0)
+
+### `bitflags` updated to 2.3 ([#205])
+
+[#205]: https://github.com/ratatui/ratatui/issues/205
+
+The `serde` representation of `bitflags` has changed. Any existing serialized types that have
+Borders or Modifiers will need to be re-serialized. This is documented in the [`bitflags`
+changelog](https://github.com/bitflags/bitflags/blob/main/CHANGELOG.md#200-rc2)..
+
+## [v0.21.0](https://github.com/ratatui/ratatui/releases/tag/v0.21.0)
+
+### MSRV is 1.65.0 ([#171])
+
+[#171]: https://github.com/ratatui/ratatui/issues/171
+
+The minimum supported rust version is now 1.65.0.
+
+### `Terminal::with_options()` stabilized to allow configuring the viewport ([#114])
+
+[#114]: https://github.com/ratatui/ratatui/issues/114
+
+In order to support inline viewports, the unstable method `Terminal::with_options()` was stabilized
+and `ViewPort` was changed from a struct to an enum.
+
+```diff
+let terminal = Terminal::with_options(backend, TerminalOptions {
+-    viewport: Viewport::fixed(area),
+});
+// becomes
+let terminal = Terminal::with_options(backend, TerminalOptions {
++    viewport: Viewport::Fixed(area),
+});
+```
+
+### Code that binds `Into<Text<'a>>` now requires type annotations ([#168])
+
+[#168]: https://github.com/ratatui/ratatui/issues/168
+
+A new type `Masked` was introduced that implements `From<Text<'a>>`. This causes any code that
+previously did not need to use type annotations to fail to compile. To fix this, annotate or call
+`to_string()` / `to_owned()` / `as_str()` on the value. E.g.:
+
+```diff
+- let paragraph = Paragraph::new("".as_ref());
+// becomes
++ let paragraph = Paragraph::new("".as_str());
+```
+
+### `Marker::Block` now renders as a block rather than a bar character ([#133])
+
+[#133]: https://github.com/ratatui/ratatui/issues/133
+
+Code using the `Block` marker that previously rendered using a half block character (`'▀'``) now
+renders using the full block character (`'█'`). A new marker variant`Bar` is introduced to replace
+the existing code.
+
+```diff
+- let canvas = Canvas::default().marker(Marker::Block);
+// becomes
++ let canvas = Canvas::default().marker(Marker::Bar);
+```
+
+## [v0.20.0](https://github.com/ratatui/ratatui/releases/tag/v0.20.0)
+
+v0.20.0 was the first release of Ratatui - versions prior to this were release as tui-rs. See the
+[Changelog](./CHANGELOG.md) for more details.
+
+### MSRV is update to 1.63.0 ([#80])
+
+[#80]: https://github.com/ratatui/ratatui/issues/80
+
+The minimum supported rust version is 1.63.0
+
+### List no longer ignores empty string in items ([#42])
+
+[#42]: https://github.com/ratatui/ratatui/issues/42
+
+The following code now renders 3 items instead of 2. Code which relies on the previous behavior will
+need to manually filter empty items prior to display.
+
+```rust
+let items = vec![
+    ListItem::new("line one"),
+    ListItem::new(""),
+    ListItem::new("line four"),
+];
+```

CODE_OF_CONDUCT.md

@@ -0,0 +1,128 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+https://forum.ratatui.rs/ or https://discord.gg/pMCEU9hNEj.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior,  harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.

CONTRIBUTING.md

@@ -8,7 +8,7 @@ creating a new issue before making the change, or starting a discussion on
 
 ## Reporting issues
 
-Before reporting an issue on the [issue tracker](https://github.com/ratatui-org/ratatui/issues),
+Before reporting an issue on the [issue tracker](https://github.com/ratatui/ratatui/issues),
 please check that it has not already been reported by searching for some related keywords. Please
 also check [`tui-rs` issues](https://github.com/fdehau/tui-rs/issues/) and link any related issues
 found.
@@ -17,10 +17,10 @@ found.
 
 All contributions are obviously welcome. Please include as many details as possible in your PR
 description to help the reviewer (follow the provided template). Make sure to highlight changes
-which may need additional attention or you are uncertain about. Any idea with a large scale impact
+which may need additional attention, or you are uncertain about. Any idea with a large scale impact
 on the crate or its users should ideally be discussed in a "Feature Request" issue beforehand.
 
-### Keep PRs small, intentional and focused
+### Keep PRs small, intentional, and focused
 
 Try to do one pull request per change. The time taken to review a PR grows exponential with the size
 of the change. Small focused PRs will generally be much more faster to review. PRs that include both
@@ -31,8 +31,8 @@ guarantee that the behavior is unchanged.
 
 ### Code formatting
 
-Run `cargo make format` before committing to ensure that code is consistently formatted with
-rustfmt. Configuration is in [rustfmt.toml](./rustfmt.toml).
+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
 
@@ -54,21 +54,11 @@ describes the nature of the problem that the commit is solving and any unintuiti
 change. It's rare that code changes can easily communicate intent, so make sure this is clearly
 documented.
 
-### Clean up your commits
-
-The final version of your PR that will be committed to the repository should be rebased and tested
-against main. Every commit will end up as a line in the changelog, so please squash commits that are
-only formatting or incremental fixes to things brought up as part of the PR review. Aim for a single
-commit (unless there is a strong reason to stack the commits). See [Git Best Practices - On Sausage
-Making](https://sethrobertson.github.io/GitBestPractices/#sausage) for more on this.
-
 ### Run CI tests before pushing a PR
 
-We're using [cargo-husky](https://github.com/rhysd/cargo-husky) to automatically run git hooks,
-which will run `cargo make ci` before each push. To initialize the hook  run `cargo test`. If
-`cargo-make` is not installed, it will provide instructions to install it for you. This will ensure
-that your code is formatted, compiles and passes all tests before you push. If you need to skip this
-check, you can use `git push --no-verify`.
+Running `cargo 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.
 
 ### Sign your commits
 
@@ -81,22 +71,22 @@ in GitHub docs.
 
 ### Setup
 
-Clone the repo and build it using [cargo-make](https://sagiegurari.github.io/cargo-make/)
+TL;DR: Clone the repo and build it using `cargo xtask`.
 
 Ratatui is an ordinary Rust project where common tasks are managed with
-[cargo-make](https://github.com/sagiegurari/cargo-make/). It wraps common `cargo` commands with sane
+[cargo-xtask](https://github.com/matklad/cargo-xtask). It wraps common `cargo` commands with sane
 defaults depending on your platform of choice. Building the project should be as easy as running
-`cargo make build`.
+`cargo xtask build`.
 
 ```shell
-git clone https://github.com/ratatui-org/ratatui.git
+git clone https://github.com/ratatui/ratatui.git
 cd ratatui
-cargo make build
+cargo xtask build
 ```
 
 ### Tests
 
-The [test coverage](https://app.codecov.io/gh/ratatui-org/ratatui) of the crate is reasonably
+The [test coverage](https://app.codecov.io/gh/ratatui/ratatui) of the crate is reasonably
 good, but this can always be improved. Focus on keeping the tests simple and obvious and write unit
 tests for all new or modified code. Beside the usual doc and unit tests, one of the most valuable
 test you can write for Ratatui is a test against the `TestBackend`. It allows you to assert the
@@ -120,7 +110,8 @@ exist to show coverage directly in your editor. E.g.:
 
 ### Documentation
 
-Here are some guidelines for writing documentation in Ratatui.  
+Here are some guidelines for writing documentation in Ratatui.
+
 Every public API **must** be documented.
 
 Keep in mind that Ratatui tends to attract beginner Rust users that may not be familiar with Rust
@@ -133,10 +124,9 @@ the concepts pointing to the various methods. Focus on interaction with various
 enough information that helps understand why you might want something.
 
 Examples should help users understand a particular usage, not test a feature. They should be as
-simple as possible.  
-Prefer hiding imports and using wildcards to keep things concise. Some imports may still be shown
-to demonstrate a particular non-obvious import (e.g. `Stylize` trait to use style methods).  
-Speaking of `Stylize`, you should use it over the more verbose style setters:
+simple as possible. Prefer hiding imports and using wildcards to keep things concise. Some imports
+may still be shown to demonstrate a particular non-obvious import (e.g. `Stylize` trait to use style
+methods). Speaking of `Stylize`, you should use it over the more verbose style setters:
 
 ```rust
 let style = Style::new().red().bold();
@@ -146,7 +136,7 @@ let style = Style::default().fg(Color::Red).add_modifier(Modifiers::BOLD);
 
 #### Format
 
-- First line is summary, second is blank, third onward is more detail  
+- First line is summary, second is blank, third onward is more detail
 
 ```rust
 /// Summary
@@ -156,10 +146,10 @@ let style = Style::default().fg(Color::Red).add_modifier(Modifiers::BOLD);
 fn foo() {}
 ```
 
-- Max line length is 100 characters  
-See [vscode rewrap extension](https://marketplace.visualstudio.com/items?itemName=stkb.rewrap)
+- Max line length is 100 characters
+See [VS Code rewrap extension](https://marketplace.visualstudio.com/items?itemName=stkb.rewrap)
 
-- Doc comments are above macros  
+- Doc comments are above macros
 i.e.
 
 ```rust
@@ -168,25 +158,31 @@ i.e.
 struct Foo {}
 ```
 
-- Code items should be between backticks  
+- Code items should be between backticks
 i.e. ``[`Block`]``, **NOT** ``[Block]``
 
+### Deprecation notice
+
+We generally want to wait at least two versions before removing deprecated items, so users have
+time to update. However, if a deprecation is blocking for us to implement a new feature we may
+*consider* removing it in a one version notice.
+
 ### Use of unsafe for optimization purposes
 
-We don't currently use any unsafe code in Ratatui, and would like to keep it that way. However there
+We don't currently use any unsafe code in Ratatui, and would like to keep it that way. However, there
 may be specific cases that this becomes necessary in order to avoid slowness. Please see [this
-discussion](https://github.com/ratatui-org/ratatui/discussions/66) for more about the decision.
+discussion](https://github.com/ratatui/ratatui/discussions/66) for more about the decision.
 
 ## Continuous Integration
 
-We use Github Actions for the CI where we perform the following checks:
+We use GitHub Actions for the CI where we perform the following checks:
 
 - The code should compile on `stable` and the Minimum Supported Rust Version (MSRV).
 - The tests (docs, lib, tests and examples) should pass.
 - 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`
@@ -195,12 +191,12 @@ This project was forked from [`tui-rs`](https://github.com/fdehau/tui-rs/) in Fe
 [blessing of the original author](https://github.com/fdehau/tui-rs/issues/654), Florian Dehau
 ([@fdehau](https://github.com/fdehau)).
 
-The original repository contains all the issues, PRs and discussion that were raised originally, and
+The original repository contains all the issues, PRs, and discussion that were raised originally, and
 it is useful to refer to when contributing code, documentation, or issues with Ratatui.
 
-We imported all the PRs from the original repository and implemented many of the smaller ones and
+We imported all the PRs from the original repository, implemented many of the smaller ones, and
 made notes on the leftovers. These are marked as draft PRs and labelled as [imported from
-tui](https://github.com/ratatui-org/ratatui/pulls?q=is%3Apr+is%3Aopen+label%3A%22imported+from+tui%22).
+tui](https://github.com/ratatui/ratatui/pulls?q=is%3Apr+is%3Aopen+label%3A%22imported+from+tui%22).
 We have documented the current state of those PRs, and anyone is welcome to pick them up and
 continue the work on them.
 

Cargo.toml

@@ -1,227 +1,55 @@
-[package]
-name = "ratatui"
-version = "0.23.0" # crate version
+[workspace]
+resolver = "2"
+members = ["ratatui", "ratatui-*", "xtask"]
+default-members = [
+    "ratatui",
+    "ratatui-core",
+    "ratatui-crossterm",
+    # this is not included as it doesn't compile on windows
+    # "ratatui-termion",
+    "ratatui-termwiz",
+    "ratatui-widgets",
+]
+
+[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"
 keywords = ["tui", "terminal", "dashboard"]
-repository = "https://github.com/ratatui-org/ratatui"
+categories = ["command-line-interface"]
 readme = "README.md"
 license = "MIT"
-exclude = [
-  "assets/*",
-  ".github",
-  "Makefile.toml",
-  "CONTRIBUTING.md",
-  "*.log",
-  "tags",
-]
-autoexamples = true
+exclude = ["assets/*", ".github", "Makefile.toml", "CONTRIBUTING.md", "*.log", "tags"]
 edition = "2021"
-rust-version = "1.67.0"
+rust-version = "1.74.0"
 
-[badges]
+[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.3"
+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.215", features = ["derive"] }
+serde_json = "1.0.133"
+strum = { version = "0.26.3", features = ["derive"] }
+termwiz = { version = "0.22.0" }
+unicode-segmentation = "1.12.0"
+# See <https://github.com/ratatui/ratatui/issues/1271> for information about why we pin unicode-width
+unicode-width = "=0.2.0"
+termion = "4.0.0"
 
-[dependencies]
-#! The crate provides a set of optional features that can be enabled in your `cargo.toml` file.
-#!
-#! Generally an application will only use one backend, so you should only enable one of the following features:
-## enables the [`CrosstermBackend`] backend and adds a dependency on the [Crossterm crate].
-crossterm = { version = "0.27", optional = true }
-## enables the [`TermionBackend`] backend and adds a dependency on the [Termion crate].
-termion = { version = "2.0", optional = true }
-## enables the [`TermwizBackend`] backend and adds a dependency on the [Termwiz crate].
-termwiz = { version = "0.20.0", optional = true }
-
-serde = { version = "1", optional = true, features = ["derive"] }
-bitflags = "2.3"
-cassowary = "0.3"
-indoc = "2.0"
-itertools = "0.11"
-paste = "1.0.2"
-strum = { version = "0.25", features = ["derive"] }
-time = { version = "0.3.11", optional = true, features = ["local-offset"] }
-unicode-segmentation = "1.10"
-unicode-width = "0.1"
-document-features = { version = "0.2.7", optional = true }
-lru = "0.11.1"
-
-[dev-dependencies]
-anyhow = "1.0.71"
-argh = "0.1.12"
-better-panic = "0.3.0"
-cargo-husky = { version = "1.5.0", default-features = false, features = [
-  "user-hooks",
-] }
-criterion = { version = "0.5.1", features = ["html_reports"] }
-fakeit = "1.1"
-rand = "0.8.5"
-palette = "0.7.3"
-pretty_assertions = "1.4.0"
-
-[features]
-default = ["crossterm"]
-#! 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"]
-
-## enables the [`border!`] macro.
-macros = []
-
-## enables all widgets.
-all-widgets = ["widget-calendar"]
-
-#! Widgets that add dependencies are gated behind feature flags to prevent unused transitive
-#! dependencies. The available features are:
-## enables the [`calendar`] widget module and adds a dependency on the [Time crate].
-widget-calendar = ["dep:time"]
-
-[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"]
-
-[[bench]]
-name = "barchart"
-harness = false
-
-[[bench]]
-name = "block"
-harness = false
-
-[[bench]]
-name = "list"
-harness = false
-
-[[bench]]
-name = "paragraph"
-harness = false
-
-[[bench]]
-name = "sparkline"
-harness = false
-
-
-[[example]]
-name = "barchart"
-required-features = ["crossterm"]
-doc-scrape-examples = true
-
-[[example]]
-name = "block"
-required-features = ["crossterm"]
-doc-scrape-examples = true
-
-[[example]]
-name = "canvas"
-required-features = ["crossterm"]
-doc-scrape-examples = true
-
-[[example]]
-name = "calendar"
-required-features = ["crossterm", "widget-calendar"]
-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"]
-doc-scrape-examples = true
-
-[[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", "widget-calendar"]
-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 = "layout"
-required-features = ["crossterm"]
-doc-scrape-examples = true
-
-[[example]]
-name = "list"
-required-features = ["crossterm"]
-doc-scrape-examples = true
-
-[[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 = "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 = "user_input"
-required-features = ["crossterm"]
-doc-scrape-examples = true
-
-[[example]]
-name = "inline"
-required-features = ["crossterm"]
-doc-scrape-examples = true
+# Improve benchmark consistency
+[profile.bench]
+codegen-units = 1
+lto = true

FUNDING.json

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

LICENSE

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

MAINTAINERS.md

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

Makefile.toml

@@ -1,163 +0,0 @@
-# configuration for https://github.com/sagiegurari/cargo-make
-
-[config]
-skip_core_tasks = true
-
-[env]
-# all features except the backend ones
-ALL_FEATURES = "all-widgets,macros,serde"
-
-# Windows does not support building termion, so this avoids the build failure by providing two
-# sets of flags, one for Windows and one for other platforms.
-# Windows: --features=all-widgets,macros,serde,crossterm,termwiz
-# Other: --all-features
-ALL_FEATURES_FLAG = { source = "${CARGO_MAKE_RUST_TARGET_OS}", default_value = "--all-features", mapping = { "windows" = "--features=all-widgets,macros,serde,crossterm,termwiz" } }
-
-[tasks.default]
-alias = "ci"
-
-[tasks.ci]
-description = "Run continuous integration tasks"
-dependencies = ["lint-style", "clippy", "check", "test"]
-
-[tasks.lint-style]
-description = "Lint code style (formatting, typos, docs)"
-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",
-  "--no-default-features",
-  "${ALL_FEATURES_FLAG}",
-  "--",
-  "-Zunstable-options",
-  "--check",
-  "-Dwarnings",
-]
-
-[tasks.check]
-description = "Check code for errors and warnings"
-command = "cargo"
-args = [
-  "check",
-  "--all-targets",
-  "--no-default-features",
-  "${ALL_FEATURES_FLAG}",
-]
-
-[tasks.build]
-description = "Compile the project"
-command = "cargo"
-args = [
-  "build",
-  "--all-targets",
-  "--no-default-features",
-  "${ALL_FEATURES_FLAG}",
-]
-
-[tasks.clippy]
-description = "Run Clippy for linting"
-command = "cargo"
-args = [
-  "clippy",
-  "--all-targets",
-  "--tests",
-  "--benches",
-  "--no-default-features",
-  "${ALL_FEATURES_FLAG}",
-  "--",
-  "-D",
-  "warnings",
-]
-
-[tasks.test]
-description = "Run tests"
-dependencies = ["test-doc"]
-command = "cargo"
-args = [
-  "test",
-  "--all-targets",
-  "--no-default-features",
-  "${ALL_FEATURES_FLAG}",
-]
-
-[tasks.test-doc]
-description = "Run documentation tests"
-command = "cargo"
-args = ["test", "--doc", "--no-default-features", "${ALL_FEATURES_FLAG}"]
-
-[tasks.test-backend]
-# takes a command line parameter to specify the backend to test (e.g. "crossterm")
-description = "Run backend-specific tests"
-command = "cargo"
-args = [
-  "test",
-  "--all-targets",
-  "--no-default-features",
-  "--features",
-  "${ALL_FEATURES},${@}",
-]
-
-[tasks.coverage]
-description = "Generate code coverage report"
-command = "cargo"
-args = [
-  "llvm-cov",
-  "--lcov",
-  "--output-path",
-  "target/lcov.info",
-  "--no-default-features",
-  "${ALL_FEATURES_FLAG}",
-]
-
-[tasks.run-example]
-private = true
-condition = { env_set = ["TUI_EXAMPLE_NAME"] }
-command = "cargo"
-args = [
-  "run",
-  "--release",
-  "--example",
-  "${TUI_EXAMPLE_NAME}",
-  "--features",
-  "all-widgets",
-]
-
-[tasks.build-examples]
-description = "Compile project examples"
-command = "cargo"
-args = ["build", "--examples", "--release", "--features", "all-widgets"]
-
-[tasks.run-examples]
-description = "Run project examples"
-dependencies = ["build-examples"]
-script = '''
-#!@duckscript
-files = glob_array ./examples/*.rs
-for file in ${files}
-  name = basename ${file}
-  name = substring ${name} -3
-  set_env TUI_EXAMPLE_NAME ${name}
-  cm_run_task run-example
-end
-'''

README.md

@@ -1,271 +1,379 @@
-![Demo of
-Ratatui](https://raw.githubusercontent.com/ratatui-org/ratatui/aa09e59dc0058347f68d7c1e0c91f863c6f2b8c9/examples/demo2.gif)
-<!--
-Permalink to https://github.com/ratatui-org/ratatui/blob/images/examples/demo2.gif
-See RELEASE.md for instructions on creating the demo gif
---->
-
-<div align="center">
-
-[![Crates.io](https://img.shields.io/crates/v/ratatui?logo=rust&style=flat-square)](https://crates.io/crates/ratatui)
-[![License](https://img.shields.io/crates/l/ratatui?style=flat-square)](./LICENSE) [![GitHub CI
-Status](https://img.shields.io/github/actions/workflow/status/ratatui-org/ratatui/ci.yml?style=flat-square&logo=github)](https://github.com/ratatui-org/ratatui/actions?query=workflow%3ACI+)
-[![Docs.rs](https://img.shields.io/docsrs/ratatui?logo=rust&style=flat-square)](https://docs.rs/crate/ratatui/)<br>
-[![Dependency
-Status](https://deps.rs/repo/github/ratatui-org/ratatui/status.svg?style=flat-square)](https://deps.rs/repo/github/ratatui-org/ratatui)
-[![Codecov](https://img.shields.io/codecov/c/github/ratatui-org/ratatui?logo=codecov&style=flat-square&token=BAQ8SOKEST)](https://app.codecov.io/gh/ratatui-org/ratatui)
-[![Discord](https://img.shields.io/discord/1070692720437383208?label=discord&logo=discord&style=flat-square)](https://discord.gg/pMCEU9hNEj)
-[![Matrix](https://img.shields.io/matrix/ratatui-general%3Amatrix.org?style=flat-square&logo=matrix&label=Matrix)](https://matrix.to/#/#ratatui:matrix.org)<br>
-[Documentation](https://docs.rs/ratatui)
-· [Examples](https://github.com/ratatui-org/ratatui/tree/main/examples)
-· [Report a bug](https://github.com/ratatui-org/ratatui/issues/new?labels=bug&projects=&template=bug_report.md)
-· [Request a Feature](https://github.com/ratatui-org/ratatui/issues/new?labels=enhancement&projects=&template=feature_request.md)
-· [Send a Pull Request](https://github.com/ratatui-org/ratatui/compare)
-
-</div>
-
-<img align="left" src="https://avatars.githubusercontent.com/u/125200832?s=128&v=4">
-
-# Ratatui
-
-`ratatui` is a [Rust](https://www.rust-lang.org) library that is all about cooking up terminal user
-interfaces. It is a community fork of the original [tui-rs](https://github.com/fdehau/tui-rs)
-project.
-
 <details>
 <summary>Table of Contents</summary>
 
-* [Ratatui](#ratatui)
-  * [Installation](#installation)
-  * [Introduction](#introduction)
-  * [Quickstart](#quickstart)
-  * [Status of this fork](#status-of-this-fork)
-  * [Rust version requirements](#rust-version-requirements)
-  * [Documentation](#documentation)
-  * [Examples](#examples)
-  * [Widgets](#widgets)
-    * [Built in](#built-in)
-    * [Third\-party libraries, bootstrapping templates and
-      widgets](#third-party-libraries-bootstrapping-templates-and-widgets)
-  * [Apps](#apps)
-  * [Alternatives](#alternatives)
-  * [Contributors](#contributors)
-  * [Acknowledgments](#acknowledgments)
-  * [License](#license)
+- [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)
 
 </details>
 
-## Installation
+<!-- cargo-rdme start -->
 
-```shell
-cargo add ratatui --features all-widgets
-```
+![Demo](https://github.com/ratatui/ratatui/blob/87ae72dbc756067c97f6400d3e2a58eeb383776e/examples/demo2-destroy.gif?raw=true)
 
-Or modify your `Cargo.toml`
+<div align="center">
 
-```toml
-[dependencies]
-ratatui = { version = "0.23.0", features = ["all-widgets"]}
-```
+[![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>
 
-## Introduction
+[Ratatui Website] · [API Docs] · [Examples] · [Changelog] · [Breaking Changes]<br>
+[Contributing] · [Report a bug] · [Request a Feature] · [Create a Pull Request]
 
-`ratatui` is a terminal UI library that supports multiple backends:
+</div>
 
-* [crossterm](https://github.com/crossterm-rs/crossterm) [default]
-* [termion](https://github.com/ticki/termion)
-* [termwiz](https://github.com/wez/wezterm/tree/master/termwiz)
+# Ratatui
 
-The library is based on the principle of immediate rendering with intermediate buffers. This means
-that at each new frame you should build all widgets that are supposed to be part of the UI. While
-providing a great flexibility for rich and interactive UI, this may introduce overhead for highly
-dynamic content. So, the implementation try to minimize the number of ansi escapes sequences
-generated to draw the updated UI. In practice, given the speed of `Rust` the overhead rather comes
-from the terminal emulator than the library itself.
-
-Moreover, the library does not provide any input handling nor any event system and you may rely on
-the previously cited libraries to achieve such features.
-
-We keep a [CHANGELOG](./CHANGELOG.md) generated by [git-cliff](https://github.com/orhun/git-cliff)
-utilizing [Conventional Commits](https://www.conventionalcommits.org/).
+[Ratatui][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.
 
 ## Quickstart
 
-The following example demonstrates the minimal amount of code necessary to setup a terminal and
-render "Hello World!". The full code for this example which contains a little more detail is in
-[hello_world.rs](./examples/hello_world.rs). For more guidance on how to create Ratatui apps, see
-the [Docs](https://docs.rs/ratatui) and [Examples](#examples). There is also a starter template
-available at [rust-tui-template](https://github.com/ratatui-org/rust-tui-template).
+Add `ratatui` and `crossterm` as dependencies to your cargo.toml:
+
+```shell
+cargo add ratatui crossterm
+```
+
+Then you can create a simple "Hello World" application:
 
 ```rust
-fn main() -> Result<(), Box<dyn Error>> {
-    let mut terminal = setup_terminal()?;
-    run(&mut terminal)?;
-    restore_terminal(&mut terminal)?;
-    Ok(())
-}
+use crossterm::event::{self, Event};
+use ratatui::{text::Text, Frame};
 
-fn setup_terminal() -> Result<Terminal<CrosstermBackend<Stdout>>, Box<dyn Error>> {
-    let mut stdout = io::stdout();
-    enable_raw_mode()?;
-    execute!(stdout, EnterAlternateScreen)?;
-    Ok(Terminal::new(CrosstermBackend::new(stdout))?)
-}
-
-fn restore_terminal(
-    terminal: &mut Terminal<CrosstermBackend<Stdout>>,
-) -> Result<(), Box<dyn Error>> {
-    disable_raw_mode()?;
-    execute!(terminal.backend_mut(), LeaveAlternateScreen,)?;
-    Ok(terminal.show_cursor()?)
-}
-
-fn run(terminal: &mut Terminal<CrosstermBackend<Stdout>>) -> Result<(), Box<dyn Error>> {
-    Ok(loop {
-        terminal.draw(|frame| {
-            let greeting = Paragraph::new("Hello World!");
-            frame.render_widget(greeting, frame.size());
-        })?;
-        if event::poll(Duration::from_millis(250))? {
-            if let Event::Key(key) = event::read()? {
-                if KeyCode::Char('q') == key.code {
-                    break;
-                }
-            }
+fn 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());
 }
 ```
 
-## Status of this fork
+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.
 
-In response to the original maintainer [**Florian Dehau**](https://github.com/fdehau)'s issue
-regarding the [future of `tui-rs`](https://github.com/fdehau/tui-rs/issues/654), several members of
-the community forked the project and created this crate. We look forward to continuing the work
-started by Florian 🚀
+## 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);
+    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::{widgets::Paragraph, Frame};
+
+fn run(terminal: &mut ratatui::DefaultTerminal) -> std::io::Result<()> {
+    loop {
+        terminal.draw(|frame| draw(frame))?;
+        if handle_events()? {
+            break Ok(());
+        }
+    }
+}
+
+fn draw(frame: &mut Frame) {
+    let text = Paragraph::new("Hello World!");
+    frame.render_widget(text, frame.area());
+}
+```
+
+### Handling events
+
+Ratatui does not include any input handling. Instead event handling can be implemented by
+calling backend library methods directly. See the [Handling Events] section of the [Ratatui
+Website] for more info. For example, if you are using [Crossterm], you can use the
+[`crossterm::event`] module to handle events.
+
+```rust
+use crossterm::event::{self, Event, KeyCode, KeyEvent, KeyEventKind};
+
+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)
+}
+```
+
+## Layout
+
+The library comes with a basic yet useful layout management object called [`Layout`] which
+allows you to split the available space into multiple areas and then render widgets in each
+area. This lets you describe a responsive terminal UI by nesting layouts. See the [Layout]
+section of the [Ratatui Website] for more info.
+
+```rust
+use ratatui::{
+    layout::{Constraint, Layout},
+    widgets::Block,
+    Frame,
+};
+
+fn draw(frame: &mut Frame) {
+    use Constraint::{Fill, Length, Min};
+
+    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);
+
+    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);
+}
+```
+
+Running this example produces the following output:
+
+```text
+Title Bar───────────────────────────────────
+┌Left────────────────┐┌Right───────────────┐
+│                    ││                    │
+└────────────────────┘└────────────────────┘
+Status Bar──────────────────────────────────
+```
+
+## Text and styling
+
+The [`Text`], [`Line`] and [`Span`] types are the building blocks of the library and are used in
+many places. [`Text`] is a list of [`Line`]s and a [`Line`] is a list of [`Span`]s. A [`Span`]
+is a string with a specific style.
+
+The [`style` module] provides types that represent the various styling options. The most
+important one is [`Style`] which represents the foreground and background colors and the text
+attributes of a [`Span`]. The [`style` module] also provides a [`Stylize`] trait that allows
+short-hand syntax to apply a style to widgets and text. See the [Styling Text] section of the
+[Ratatui Website] for more info.
+
+```rust
+use ratatui::{
+    layout::{Constraint, Layout},
+    style::{Color, Modifier, Style, Stylize},
+    text::{Line, Span},
+    widgets::{Block, Paragraph},
+    Frame,
+};
+
+fn draw(frame: &mut Frame) {
+    let areas = Layout::vertical([Constraint::Length(1); 4]).split(frame.area());
+
+    let line = Line::from(vec![
+        Span::raw("Hello "),
+        Span::styled(
+            "World",
+            Style::new()
+                .fg(Color::Green)
+                .bg(Color::White)
+                .add_modifier(Modifier::BOLD),
+        ),
+        "!".red().on_light_yellow().italic(),
+    ]);
+    frame.render_widget(line, areas[0]);
+
+    // using the short-hand syntax and implicit conversions
+    let paragraph = Paragraph::new("Hello World!".red().on_white().bold());
+    frame.render_widget(paragraph, areas[1]);
+
+    // style the whole widget instead of just the text
+    let paragraph = Paragraph::new("Hello World!").style(Style::new().red().on_white());
+    frame.render_widget(paragraph, areas[2]);
+
+    // use the simpler short-hand syntax
+    let paragraph = Paragraph::new("Hello World!").blue().on_yellow();
+    frame.render_widget(paragraph, areas[3]);
+}
+```
+
+[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/ratatui/examples/README.md
+[Report a bug]: https://github.com/ratatui/ratatui/issues/new?labels=bug&projects=&template=bug_report.md
+[Request a Feature]: https://github.com/ratatui/ratatui/issues/new?labels=enhancement&projects=&template=feature_request.md
+[Create a Pull Request]: https://github.com/ratatui/ratatui/compare
+[git-cliff]: https://git-cliff.org
+[Conventional Commits]: https://www.conventionalcommits.org
+[API Docs]: https://docs.rs/ratatui
+[Changelog]: https://github.com/ratatui/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
+[License Badge]: https://img.shields.io/crates/l/ratatui?style=flat-square&color=1370D3
+[CI Badge]: https://img.shields.io/github/actions/workflow/status/ratatui/ratatui/ci.yml?style=flat-square&logo=github
+[CI Workflow]: https://github.com/ratatui/ratatui/actions/workflows/ci.yml
+[Codecov Badge]: https://img.shields.io/codecov/c/github/ratatui/ratatui?logo=codecov&style=flat-square&token=BAQ8SOKEST&color=C43AC3&logoColor=C43AC3
+[Codecov]: https://app.codecov.io/gh/ratatui/ratatui
+[Deps.rs Badge]: https://deps.rs/repo/github/ratatui/ratatui/status.svg?style=flat-square
+[Deps.rs]: https://deps.rs/repo/github/ratatui/ratatui
+[Discord Badge]: https://img.shields.io/discord/1070692720437383208?label=discord&logo=discord&style=flat-square&color=1370D3&logoColor=1370D3
+[Discord Server]: https://discord.gg/pMCEU9hNEj
+[Docs Badge]: https://img.shields.io/docsrs/ratatui?logo=rust&style=flat-square&logoColor=E05D44
+[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).
 
-While we do utilize Discord for coordinating, it's not essential for contributing.
-Our primary open-source workflow is centered around GitHub.
-For significant discussions, we rely on GitHub — please open an issue, a discussion or a PR.
+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 updated [contributing](./CONTRIBUTING.md) guidelines, especially if
-you are interested in working on a PR or issue opened in the previous repository.
+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.
 
-## Rust version requirements
+## Built with Ratatui
 
-Since version 0.23.0, The Minimum Supported Rust Version (MSRV) of `ratatui` is 1.67.0.
-
-## Documentation
-
-The documentation can be found on [docs.rs.](https://docs.rs/ratatui)
-
-## Examples
-
-The demo shown in the gif above is available on all available backends.
-
-```shell
-# crossterm
-cargo run --example demo
-# termion
-cargo run --example demo --no-default-features --features=termion
-# termwiz
-cargo run --example demo --no-default-features --features=termwiz
-```
-
-The UI code for this is in [examples/demo/ui.rs](./examples/demo/ui.rs) while the application state
-is in [examples/demo/app.rs](./examples/demo/app.rs).
-
-If the user interface contains glyphs that are not displayed correctly by your terminal, you may
-want to run the demo without those symbols:
-
-```shell
-cargo run --example demo --release -- --tick-rate 200 --enhanced-graphics false
-```
-
-More examples are available in the [examples](./examples/) folder.
-
-## Widgets
-
-### Built in
-
-The library comes with the following
-[widgets](https://docs.rs/ratatui/latest/ratatui/widgets/index.html):
-
-* [BarChart](https://docs.rs/ratatui/latest/ratatui/widgets/struct.BarChart.html)
-* [Block](https://docs.rs/ratatui/latest/ratatui/widgets/block/struct.Block.html)
-* [Calendar](https://docs.rs/ratatui/latest/ratatui/widgets/calendar/index.html)
-* [Canvas](https://docs.rs/ratatui/latest/ratatui/widgets/canvas/struct.Canvas.html) which allows
-  rendering [points, lines, shapes and a world
-  map](https://docs.rs/ratatui/latest/ratatui/widgets/canvas/index.html)
-* [Chart](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Chart.html)
-* [Clear](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Clear.html)
-* [Gauge](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Gauge.html)
-* [List](https://docs.rs/ratatui/latest/ratatui/widgets/struct.List.html)
-* [Paragraph](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Paragraph.html)
-* [Scrollbar](https://docs.rs/ratatui/latest/ratatui/widgets/scrollbar/struct.Scrollbar.html)
-* [Sparkline](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Sparkline.html)
-* [Table](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Table.html)
-* [Tabs](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Tabs.html)
-
-Each widget has an associated example which can be found in the [examples](./examples/) folder. Run
-each examples with cargo (e.g. to run the gauge example `cargo run --example gauge`), and quit by
-pressing `q`.
-
-You can also run all examples by running `cargo make run-examples` (requires `cargo-make` that can
-be installed with `cargo install cargo-make`).
-
-### Third-party libraries, bootstrapping templates and widgets
-
-* [ansi-to-tui](https://github.com/uttarayan21/ansi-to-tui) — Convert ansi colored text to
-  `ratatui::text::Text`
-* [color-to-tui](https://github.com/uttarayan21/color-to-tui) — Parse hex colors to
-  `ratatui::style::Color`
-* [rust-tui-template](https://github.com/ratatui-org/rust-tui-template) — A template for bootstrapping a
-  Rust TUI application with Tui-rs & crossterm
-* [simple-tui-rs](https://github.com/pmsanford/simple-tui-rs) — A simple example tui-rs app
-* [tui-builder](https://github.com/jkelleyrtp/tui-builder) — Batteries-included MVC framework for
-  Tui-rs + Crossterm apps
-* [tui-clap](https://github.com/kegesch/tui-clap-rs) — Use clap-rs together with Tui-rs
-* [tui-log](https://github.com/kegesch/tui-log-rs) — Example of how to use logging with Tui-rs
-* [tui-logger](https://github.com/gin66/tui-logger) — Logger and Widget for Tui-rs
-* [tui-realm](https://github.com/veeso/tui-realm) — Tui-rs framework to build stateful applications
-  with a React/Elm inspired approach
-* [tui-realm-treeview](https://github.com/veeso/tui-realm-treeview) — Treeview component for
-  Tui-realm
-* [tui-rs-tree-widgets](https://github.com/EdJoPaTo/tui-rs-tree-widget): Widget for tree data
-  structures.
-* [tui-windows](https://github.com/markatk/tui-windows-rs) — Tui-rs abstraction to handle multiple
-  windows and their rendering
-* [tui-textarea](https://github.com/rhysd/tui-textarea): Simple yet powerful multi-line text editor
-  widget supporting several key shortcuts, undo/redo, text search, etc.
-* [tui-input](https://github.com/sayanarijit/tui-input): TUI input library supporting multiple
-  backends and tui-rs.
-* [tui-term](https://github.com/a-kenji/tui-term): A pseudoterminal widget library
-  that enables the rendering of terminal applications as ratatui widgets.
-
-## Apps
-
-Check out the list of more than 50 [Apps using
-`Ratatui`](https://github.com/ratatui-org/ratatui/wiki/Apps-using-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
+You might want to checkout [Cursive](https://github.com/gyscos/Cursive) or 
+[iocraft](https://github.com/ccbrown/iocraft/) for an alternative solutions
 to build text user interfaces in Rust.
 
-## Contributors
-
-[![GitHub
-Contributors](https://contrib.rocks/image?repo=ratatui-org/ratatui)](https://github.com/ratatui-org/ratatui/graphs/contributors)
-
 ## Acknowledgments
 
+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-org organization.
+awesome logo** for the ratatui project and ratatui organization.
 
 ## License
 

RELEASE.md

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

SECURITY.md

@@ -0,0 +1,9 @@
+# Security Policy
+
+## Supported Versions
+
+We only support the latest version of this crate.
+
+## Reporting a Vulnerability
+
+To report secuirity vulnerability, please use the form at <https://github.com/ratatui/ratatui/security/advisories/new>

bacon.toml

@@ -8,48 +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"]
 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"
@@ -59,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",
 ]
@@ -72,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",
-    "--all-features", 
-    "--color", "always",
+    "cargo",
+    "llvm-cov",
+    "--lcov",
+    "--output-path",
+    "target/lcov.info",
+    "--all-features",
 ]
 
 [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
@@ -92,9 +127,11 @@ 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"
 v = "job:coverage"
-u = "job:coverage-unit-tests-only"
+ctrl-v = "job:coverage-unit-tests-only"
+u = "job:test-unit"
+n = "job:nextest"

benches/block.rs

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

cliff.toml

@@ -1,4 +1,9 @@
-# configuration for https://github.com/orhun/git-cliff
+# git-cliff ~ configuration file
+# https://git-cliff.org/docs/configuration
+
+[remote.github]
+owner = "ratatui"
+repo = "ratatui"
 
 [changelog]
 # changelog header
@@ -6,6 +11,8 @@ header = """
 # Changelog
 
 All notable changes to this project will be documented in this file.
+<!-- ignore lint rules that are often triggered by content generated from commits / git-cliff -->
+<!-- markdownlint-disable line-length no-bare-urls ul-style emphasis-style -->
 """
 # template for the changelog body
 # https://keats.github.io/tera/docs/#introduction
@@ -17,19 +24,15 @@ body = """
 {%- if not version %}
 ## [unreleased]
 {% else -%}
-## [{{ version }}](https://github.com/ratatui-org/ratatui/releases/tag/{{ version }}) - {{ timestamp | date(format="%Y-%m-%d") }}
+## [{{ version }}](https://github.com/ratatui/ratatui/releases/tag/{{ version }}) - {{ timestamp | date(format="%Y-%m-%d") }}
 {% endif -%}
 
 {% macro commit(commit) -%}
-- [{{ commit.id | truncate(length=7, end="") }}]({{ "https://github.com/ratatui-org/ratatui/commit/" ~ commit.id }})
-  *({{commit.scope | default(value = "uncategorized") | lower }})* {{ commit.message | upper_first }}
+- [{{ commit.id | truncate(length=7, end="") }}]({{ "https://github.com/ratatui/ratatui/commit/" ~ commit.id }}) \
+  *({{commit.scope | default(value = "uncategorized") | lower }})* {{ commit.message | upper_first | trim }}\
+  {% if commit.remote.username %} by @{{ commit.remote.username }}{%- endif -%}\
+  {% if commit.remote.pr_number %} in [#{{ commit.remote.pr_number }}]({{ self::remote_url() }}/pull/{{ commit.remote.pr_number }}){%- endif %}\
 {%- if commit.breaking %} [**breaking**]{% endif %}
-{%- if commit.body %}
-
-  ````text {#- 4 backticks escape any backticks in body #}
-  {{commit.body | indent(prefix="  ") }}
-  ````
-{%- endif %}
 {% endmacro -%}
 
 {% for group, commits in commits | group_by(attribute="group") %}
@@ -43,6 +46,28 @@ body = """
 {%- endif -%}
 {%- endfor -%}
 {%- endfor %}
+
+{% if github.contributors | filter(attribute="is_first_time", value=true) | length != 0 %}
+### New Contributors
+{%- endif %}\
+{% for contributor in github.contributors | filter(attribute="is_first_time", value=true) %}
+* @{{ contributor.username }} made their first contribution
+{%- if contributor.pr_number %} in \
+[#{{ contributor.pr_number }}]({{ self::remote_url() }}/pull/{{ contributor.pr_number }}) \
+{%- endif %}
+{%- endfor -%}
+
+{% if version %}
+{% if previous.version %}
+**Full Changelog**: {{ self::remote_url() }}/compare/{{ previous.version }}...{{ version }}
+{% endif %}
+{% else -%}
+  {% raw %}\n{% endraw %}
+{% endif %}
+
+{%- macro remote_url() -%}
+https://github.com/{{ remote.github.owner }}/{{ remote.github.repo }}\
+{% endmacro %}
 """
 
 
@@ -52,6 +77,11 @@ trim = false
 footer = """
 <!-- generated by git-cliff -->
 """
+postprocessors = [
+  { pattern = '<!-- Please read CONTRIBUTING.md before submitting any pull request. -->', replace = "" },
+  { pattern = '>---+\n', replace = '' },
+  { pattern = ' +\n', replace = "\n" },
+]
 
 [git]
 # parse the commits based on https://www.conventionalcommits.org
@@ -62,7 +92,7 @@ filter_unconventional = true
 split_commits = false
 # regex for preprocessing the commit messages
 commit_preprocessors = [
-  { pattern = '\((\w+\s)?#([0-9]+)\)', replace = "([#${2}](https://github.com/ratatui-org/ratatui/issues/${2}))" },
+  { pattern = '\((\w+\s)?#([0-9]+)\)', replace = "" },
   { pattern = '(better safe shared layout cache)', replace = "perf(layout): ${1}" },
   { pattern = '(Clarify README.md)', replace = "docs(readme): ${1}" },
   { pattern = '(Update README.md)', replace = "docs(readme): ${1}" },
@@ -80,6 +110,8 @@ commit_parsers = [
   { message = "^chore\\(release\\): prepare for", skip = true },
   { message = "^chore\\(pr\\)", skip = true },
   { message = "^chore\\(pull\\)", skip = true },
+  { message = "^chore\\(deps\\)", skip = true },
+  { message = "^chore\\(changelog\\)", skip = true },
   { message = "^[cC]hore", group = "<!-- 07 -->Miscellaneous Tasks" },
   { body = ".*security", group = "<!-- 08 -->Security" },
   { message = "^build", group = "<!-- 09 -->Build" },
@@ -89,6 +121,7 @@ commit_parsers = [
   { message = "^(Buffer|buffer|Frame|frame|Gauge|gauge|Paragraph|paragraph):", group = "<!-- 07 -->Miscellaneous Tasks" },
   { message = "^\\[", group = "<!-- 07 -->Miscellaneous Tasks" },
 ]
+
 # protect breaking changes from being skipped due to matching a skipping commit_parser
 protect_breaking_commits = false
 # filter out the commits that are not matched by commit parsers

clippy.toml

@@ -0,0 +1,24 @@
+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
+# (also, memoffset, syn, nix, strsim, windows-sys
+# crossterm -> all the windows- deps https://github.com/ratatui/ratatui/pull/1064#issuecomment-2078848980
+allowed-duplicate-crates = [
+    "bitflags",
+    "memoffset",
+    "nix",
+    "strsim",
+    "syn",
+    "windows-sys",
+    "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",
+]

codecov.yml

@@ -1,3 +1,14 @@
+coverage: # https://docs.codecov.com/docs/codecovyml-reference#coverage
+  precision: 1 # e.g. 89.1%
+  round: down
+  range: 85..100 # https://docs.codecov.com/docs/coverage-configuration#section-range
+  status: # https://docs.codecov.com/docs/commit-status
+    project:
+      default:
+        threshold: 1% # Avoid false negatives
 ignore:
   - "examples"
   - "benches"
+comment: # https://docs.codecov.com/docs/pull-request-comments
+  # make the comments less noisy
+  require_changes: true

deny.toml

@@ -1,9 +1,7 @@
 # configuration for https://github.com/EmbarkStudios/cargo-deny
 
 [licenses]
-default = "deny"
-unlicensed = "deny"
-copyleft = "deny"
+version = 2
 confidence-threshold = 0.8
 allow = [
     "Apache-2.0",
@@ -13,11 +11,11 @@ allow = [
     "MIT",
     "Unicode-DFS-2016",
     "WTFPL",
+    "Zlib",
 ]
 
 [advisories]
-unmaintained = "deny"
-yanked = "deny"
+version = 2
 
 [bans]
 multiple-versions = "allow"

examples/README.md

@@ -1,317 +0,0 @@
-# Examples
-
-These gifs were created using [Charm VHS](https://github.com/charmbracelet/vhs).
-
-VHS has a problem rendering some background color transitions, which shows up in several examples
-below. See <https://github.com/charmbracelet/vhs/issues/344> for more info. These problems don't
-occur in a terminal.
-
-## Demo
-
-This is the previous demo example from the main README. It is available for each of the backends. Source:
-[demo.rs](./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
-```
-
-![Demo][demo.gif]
-
-## Hello World
-
-This is a pretty boring example, but it contains some good documentation
-on writing tui apps. Source: [hello_world.rs](./hello_world.rs).
-
-```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]
-
-## 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).
-
-```shell
-cargo run --example=colors_rgb --features=crossterm
-```
-
-![Colors RGB][colors_rgb.gif]
-
-## Custom Widget
-
-Demonstrates how to implement the
-[`Widget`](https://docs.rs/ratatui/latest/ratatui/widgets/trait.Widget.html) trait. Source:
-[custom_widget.rs](./custom_widget.rs).
-
-```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).
-
-> [!NOTE] The backgrounds render poorly when we generate this example using VHS. This problem
-> doesn't generally happen during normal rendering in a terminal. See
-> [vhs#344](https://github.com/charmbracelet/vhs/issues/344) for more details.
-
-```shell
-cargo run --example=gauge --features=crossterm
-```
-
-![Gauge][gauge.gif]
-
-## Inline
-
-Demonstrates 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]
-
-## 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
-```
-
-> [!NOTE] The background renders poorly after the popup when we generate this example using VHS.
-> This problem doesn't generally happen during normal rendering in a terminal. See
-> [vhs#344](https://github.com/charmbracelet/vhs/issues/344) for more details.
-
-![Popup][popup.gif]
-
-## 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).
-
-> [!NOTE] The background renders poorly in the second sparkline when we generate this example using
-> VHS. This problem doesn't generally happen during normal rendering in a terminal. See
-> [vhs#344](https://github.com/charmbracelet/vhs/issues/344) for more details.
-
-```shell
-cargo run --example=sparkline --features=crossterm
-```
-
-![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]
-
-## 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]
-
-<!--
-links to images to make it easier to update in bulk
-These are generated with `vhs publish examples/xxx.gif`
-
-To update these examples in bulk:
-```shell
-examples/generate.bash
-```
--->
-[barchart.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/barchart.gif?raw=true
-[block.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/block.gif?raw=true
-[calendar.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/calendar.gif?raw=true
-[canvas.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/canvas.gif?raw=true
-[chart.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/chart.gif?raw=true
-[colors.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/colors.gif?raw=true
-[colors_rgb.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/colors_rgb.gif?raw=true
-[custom_widget.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/custom_widget.gif?raw=true
-[demo.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/demo.gif?raw=true
-[gauge.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/gauge.gif?raw=true
-[hello_world.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/hello_world.gif?raw=true
-[inline.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/inline.gif?raw=true
-[layout.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/layout.gif?raw=true
-[list.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/list.gif?raw=true
-[modifiers.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/modifiers.gif?raw=true
-[panic.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/panic.gif?raw=true
-[paragraph.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/paragraph.gif?raw=true
-[popup.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/popup.gif?raw=true
-[scrollbar.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/scrollbar.gif?raw=true
-[sparkline.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/sparkline.gif?raw=true
-[table.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/table.gif?raw=true
-[tabs.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/tabs.gif?raw=true
-[user_input.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/user_input.gif?raw=true

examples/barchart.rs

@@ -1,293 +0,0 @@
-use std::{
-    error::Error,
-    io,
-    time::{Duration, Instant},
-};
-
-use crossterm::{
-    event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode},
-    execute,
-    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-};
-use ratatui::{prelude::*, widgets::*};
-
-struct Company<'a> {
-    revenue: [u64; 4],
-    label: &'a str,
-    bar_style: Style,
-}
-
-struct App<'a> {
-    data: Vec<(&'a str, u64)>,
-    months: [&'a str; 4],
-    companies: [Company<'a>; 3],
-}
-
-const TOTAL_REVENUE: &str = "Total Revenue";
-
-impl<'a> App<'a> {
-    fn new() -> App<'a> {
-        App {
-            data: vec![
-                ("B1", 9),
-                ("B2", 12),
-                ("B3", 5),
-                ("B4", 8),
-                ("B5", 2),
-                ("B6", 4),
-                ("B7", 5),
-                ("B8", 9),
-                ("B9", 14),
-                ("B10", 15),
-                ("B11", 1),
-                ("B12", 0),
-                ("B13", 4),
-                ("B14", 6),
-                ("B15", 4),
-                ("B16", 6),
-                ("B17", 4),
-                ("B18", 7),
-                ("B19", 13),
-                ("B20", 8),
-                ("B21", 11),
-                ("B22", 9),
-                ("B23", 3),
-                ("B24", 5),
-            ],
-            companies: [
-                Company {
-                    label: "Comp.A",
-                    revenue: [9500, 12500, 5300, 8500],
-                    bar_style: Style::default().fg(Color::Green),
-                },
-                Company {
-                    label: "Comp.B",
-                    revenue: [1500, 2500, 3000, 500],
-                    bar_style: Style::default().fg(Color::Yellow),
-                },
-                Company {
-                    label: "Comp.C",
-                    revenue: [10500, 10600, 9000, 4200],
-                    bar_style: Style::default().fg(Color::White),
-                },
-            ],
-            months: ["Mars", "Apr", "May", "Jun"],
-        }
-    }
-
-    fn on_tick(&mut self) {
-        let value = self.data.pop().unwrap();
-        self.data.insert(0, value);
-    }
-}
-
-fn main() -> Result<(), Box<dyn Error>> {
-    // setup terminal
-    enable_raw_mode()?;
-    let mut stdout = io::stdout();
-    execute!(stdout, EnterAlternateScreen, EnableMouseCapture)?;
-    let backend = CrosstermBackend::new(stdout);
-    let mut terminal = Terminal::new(backend)?;
-
-    // create app and run it
-    let tick_rate = Duration::from_millis(250);
-    let app = App::new();
-    let res = run_app(&mut terminal, app, tick_rate);
-
-    // restore terminal
-    disable_raw_mode()?;
-    execute!(
-        terminal.backend_mut(),
-        LeaveAlternateScreen,
-        DisableMouseCapture
-    )?;
-    terminal.show_cursor()?;
-
-    if let Err(err) = res {
-        println!("{err:?}");
-    }
-
-    Ok(())
-}
-
-fn run_app<B: Backend>(
-    terminal: &mut Terminal<B>,
-    mut app: App,
-    tick_rate: Duration,
-) -> io::Result<()> {
-    let mut last_tick = Instant::now();
-    loop {
-        terminal.draw(|f| ui(f, &app))?;
-
-        let timeout = tick_rate
-            .checked_sub(last_tick.elapsed())
-            .unwrap_or_else(|| Duration::from_secs(0));
-        if crossterm::event::poll(timeout)? {
-            if let Event::Key(key) = event::read()? {
-                if let KeyCode::Char('q') = key.code {
-                    return Ok(());
-                }
-            }
-        }
-        if last_tick.elapsed() >= tick_rate {
-            app.on_tick();
-            last_tick = Instant::now();
-        }
-    }
-}
-
-fn ui<B: Backend>(f: &mut Frame<B>, app: &App) {
-    let chunks = Layout::default()
-        .direction(Direction::Vertical)
-        .constraints([Constraint::Ratio(1, 3), Constraint::Ratio(2, 3)].as_ref())
-        .split(f.size());
-
-    let barchart = BarChart::default()
-        .block(Block::default().title("Data1").borders(Borders::ALL))
-        .data(&app.data)
-        .bar_width(9)
-        .bar_style(Style::default().fg(Color::Yellow))
-        .value_style(Style::default().fg(Color::Black).bg(Color::Yellow));
-    f.render_widget(barchart, chunks[0]);
-
-    let chunks = Layout::default()
-        .direction(Direction::Horizontal)
-        .constraints([Constraint::Percentage(50), Constraint::Percentage(50)].as_ref())
-        .split(chunks[1]);
-
-    draw_bar_with_group_labels(f, app, chunks[0]);
-    draw_horizontal_bars(f, app, chunks[1]);
-}
-
-fn create_groups<'a>(app: &'a App, combine_values_and_labels: bool) -> Vec<BarGroup<'a>> {
-    app.months
-        .iter()
-        .enumerate()
-        .map(|(i, &month)| {
-            let bars: Vec<Bar> = app
-                .companies
-                .iter()
-                .map(|c| {
-                    let mut bar = Bar::default()
-                        .value(c.revenue[i])
-                        .style(c.bar_style)
-                        .value_style(
-                            Style::default()
-                                .bg(c.bar_style.fg.unwrap())
-                                .fg(Color::Black),
-                        );
-
-                    if combine_values_and_labels {
-                        bar = bar.text_value(format!(
-                            "{} ({:.1} M)",
-                            c.label,
-                            (c.revenue[i] as f64) / 1000.
-                        ));
-                    } else {
-                        bar = bar
-                            .text_value(format!("{:.1}", (c.revenue[i] as f64) / 1000.))
-                            .label(c.label.into());
-                    }
-                    bar
-                })
-                .collect();
-            BarGroup::default()
-                .label(Line::from(month).alignment(Alignment::Center))
-                .bars(&bars)
-        })
-        .collect()
-}
-
-fn draw_bar_with_group_labels<B>(f: &mut Frame<B>, app: &App, area: Rect)
-where
-    B: Backend,
-{
-    let groups = create_groups(app, false);
-
-    let mut barchart = BarChart::default()
-        .block(Block::default().title("Data1").borders(Borders::ALL))
-        .bar_width(7)
-        .group_gap(3);
-
-    for group in groups {
-        barchart = barchart.data(group)
-    }
-
-    f.render_widget(barchart, area);
-
-    const LEGEND_HEIGHT: u16 = 6;
-    if area.height >= LEGEND_HEIGHT && area.width >= TOTAL_REVENUE.len() as u16 + 2 {
-        let legend_width = TOTAL_REVENUE.len() as u16 + 2;
-        let legend_area = Rect {
-            height: LEGEND_HEIGHT,
-            width: legend_width,
-            y: area.y,
-            x: area.right() - legend_width,
-        };
-        draw_legend(f, legend_area);
-    }
-}
-
-fn draw_horizontal_bars<B>(f: &mut Frame<B>, app: &App, area: Rect)
-where
-    B: Backend,
-{
-    let groups = create_groups(app, true);
-
-    let mut barchart = BarChart::default()
-        .block(Block::default().title("Data1").borders(Borders::ALL))
-        .bar_width(1)
-        .group_gap(1)
-        .bar_gap(0)
-        .direction(Direction::Horizontal);
-
-    for group in groups {
-        barchart = barchart.data(group)
-    }
-
-    f.render_widget(barchart, area);
-
-    const LEGEND_HEIGHT: u16 = 6;
-    if area.height >= LEGEND_HEIGHT && area.width >= TOTAL_REVENUE.len() as u16 + 2 {
-        let legend_width = TOTAL_REVENUE.len() as u16 + 2;
-        let legend_area = Rect {
-            height: LEGEND_HEIGHT,
-            width: legend_width,
-            y: area.y,
-            x: area.right() - legend_width,
-        };
-        draw_legend(f, legend_area);
-    }
-}
-
-fn draw_legend<B>(f: &mut Frame<B>, area: Rect)
-where
-    B: Backend,
-{
-    let text = vec![
-        Line::from(Span::styled(
-            TOTAL_REVENUE,
-            Style::default()
-                .add_modifier(Modifier::BOLD)
-                .fg(Color::White),
-        )),
-        Line::from(Span::styled(
-            "- Company A",
-            Style::default().fg(Color::Green),
-        )),
-        Line::from(Span::styled(
-            "- Company B",
-            Style::default().fg(Color::Yellow),
-        )),
-        Line::from(vec![Span::styled(
-            "- Company C",
-            Style::default().fg(Color::White),
-        )]),
-    ];
-
-    let block = Block::default()
-        .borders(Borders::ALL)
-        .style(Style::default().fg(Color::White));
-    let paragraph = Paragraph::new(text).block(block);
-    f.render_widget(paragraph, area);
-}

examples/block.rs

@@ -1,253 +0,0 @@
-use std::{
-    error::Error,
-    io::{stdout, Stdout},
-    ops::ControlFlow,
-    time::Duration,
-};
-
-use crossterm::{
-    event::{self, Event, KeyCode},
-    execute,
-    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-};
-use itertools::Itertools;
-use ratatui::{
-    prelude::*,
-    widgets::{
-        block::{Position, Title},
-        Block, BorderType, Borders, Padding, Paragraph, Wrap,
-    },
-};
-
-// These type aliases are used to make the code more readable by reducing repetition of the generic
-// types. They are not necessary for the functionality of the code.
-type Frame<'a> = ratatui::Frame<'a, CrosstermBackend<Stdout>>;
-type Terminal = ratatui::Terminal<CrosstermBackend<Stdout>>;
-type Result<T> = std::result::Result<T, Box<dyn Error>>;
-
-fn main() -> Result<()> {
-    let mut terminal = setup_terminal()?;
-    let result = run(&mut terminal);
-    restore_terminal(terminal)?;
-
-    if let Err(err) = result {
-        eprintln!("{err:?}");
-    }
-    Ok(())
-}
-
-fn setup_terminal() -> Result<Terminal> {
-    enable_raw_mode()?;
-    let mut stdout = stdout();
-    execute!(stdout, EnterAlternateScreen)?;
-    let backend = CrosstermBackend::new(stdout);
-    let terminal = Terminal::new(backend)?;
-    Ok(terminal)
-}
-
-fn restore_terminal(mut terminal: Terminal) -> Result<()> {
-    disable_raw_mode()?;
-    execute!(terminal.backend_mut(), LeaveAlternateScreen)?;
-    Ok(())
-}
-
-fn run(terminal: &mut Terminal) -> Result<()> {
-    loop {
-        terminal.draw(ui)?;
-        if handle_events()?.is_break() {
-            return Ok(());
-        }
-    }
-}
-
-fn handle_events() -> Result<ControlFlow<()>> {
-    if event::poll(Duration::from_millis(100))? {
-        if let Event::Key(key) = event::read()? {
-            if let KeyCode::Char('q') = key.code {
-                return Ok(ControlFlow::Break(()));
-            }
-        }
-    }
-    Ok(ControlFlow::Continue(()))
-}
-
-fn ui(frame: &mut Frame) {
-    let (title_area, layout) = calculate_layout(frame.size());
-
-    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 layout = Layout::default()
-        .direction(Direction::Vertical)
-        .constraints(vec![Constraint::Length(1), Constraint::Min(0)])
-        .split(area);
-    let title_area = layout[0];
-    let main_areas = Layout::default()
-        .direction(Direction::Vertical)
-        .constraints(vec![Constraint::Max(4); 9])
-        .split(layout[1])
-        .iter()
-        .map(|&area| {
-            Layout::default()
-                .direction(Direction::Horizontal)
-                .constraints(vec![Constraint::Percentage(50), Constraint::Percentage(50)])
-                .split(area)
-                .to_vec()
-        })
-        .collect_vec();
-    (title_area, main_areas)
-}
-
-fn render_title(frame: &mut Frame, area: Rect) {
-    frame.render_widget(
-        Paragraph::new("Block example. Press q to quit")
-            .dark_gray()
-            .alignment(Alignment::Center),
-        area,
-    );
-}
-
-fn placeholder_paragraph() -> Paragraph<'static> {
-    let text = "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.";
-    Paragraph::new(text.dark_gray()).wrap(Wrap { trim: true })
-}
-
-fn render_borders(paragraph: &Paragraph, border: Borders, frame: &mut Frame, area: Rect) {
-    let block = Block::new()
-        .borders(border)
-        .title(format!("Borders::{border:#?}", border = 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::new()
-        .borders(Borders::ALL)
-        .border_type(border_type)
-        .title(format!("BorderType::{border_type:#?}"));
-    frame.render_widget(paragraph.clone().block(block), area);
-}
-fn render_styled_borders(paragraph: &Paragraph, frame: &mut Frame, area: Rect) {
-    let block = Block::new()
-        .borders(Borders::ALL)
-        .border_style(Style::new().blue().on_white().bold().italic())
-        .title("Styled borders");
-    frame.render_widget(paragraph.clone().block(block), area);
-}
-
-fn render_styled_block(paragraph: &Paragraph, frame: &mut Frame, area: Rect) {
-    let block = Block::new()
-        .borders(Borders::ALL)
-        .style(Style::new().blue().on_white().bold().italic())
-        .title("Styled block");
-    frame.render_widget(paragraph.clone().block(block), area);
-}
-
-// Note: this currently renders incorrectly, see https://github.com/ratatui-org/ratatui/issues/349
-fn render_styled_title(paragraph: &Paragraph, frame: &mut Frame, area: Rect) {
-    let block = Block::new()
-        .borders(Borders::ALL)
-        .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::new().borders(Borders::ALL).title(title);
-    frame.render_widget(paragraph.clone().block(block), area);
-}
-
-fn render_multiple_titles(paragraph: &Paragraph, frame: &mut Frame, area: Rect) {
-    let block = Block::new()
-        .borders(Borders::ALL)
-        .title("Multiple".blue().on_white().bold().italic())
-        .title("Titles".red().on_white().bold().italic());
-    frame.render_widget(paragraph.clone().block(block), area);
-}
-
-fn render_multiple_title_positions(paragraph: &Paragraph, frame: &mut Frame, area: Rect) {
-    let block = Block::new()
-        .borders(Borders::ALL)
-        .title(
-            Title::from("top left")
-                .position(Position::Top)
-                .alignment(Alignment::Left),
-        )
-        .title(
-            Title::from("top center")
-                .position(Position::Top)
-                .alignment(Alignment::Center),
-        )
-        .title(
-            Title::from("top right")
-                .position(Position::Top)
-                .alignment(Alignment::Right),
-        )
-        .title(
-            Title::from("bottom left")
-                .position(Position::Bottom)
-                .alignment(Alignment::Left),
-        )
-        .title(
-            Title::from("bottom center")
-                .position(Position::Bottom)
-                .alignment(Alignment::Center),
-        )
-        .title(
-            Title::from("bottom right")
-                .position(Position::Bottom)
-                .alignment(Alignment::Right),
-        );
-    frame.render_widget(paragraph.clone().block(block), area);
-}
-
-fn render_padding(paragraph: &Paragraph, frame: &mut Frame, area: Rect) {
-    let block = Block::new()
-        .borders(Borders::ALL)
-        .title("Padding")
-        .padding(Padding::new(5, 10, 1, 2));
-    frame.render_widget(paragraph.clone().block(block), area);
-}
-
-fn render_nested_blocks(paragraph: &Paragraph, frame: &mut Frame, area: Rect) {
-    let outer_block = Block::new().borders(Borders::ALL).title("Outer block");
-    let inner_block = Block::new().borders(Borders::ALL).title("Inner block");
-    let inner = outer_block.inner(area);
-    frame.render_widget(outer_block, area);
-    frame.render_widget(paragraph.clone().block(inner_block), inner);
-}

examples/canvas.rs

@@ -1,186 +0,0 @@
-use std::{
-    error::Error,
-    io,
-    time::{Duration, Instant},
-};
-
-use crossterm::{
-    event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode},
-    execute,
-    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-};
-use ratatui::{
-    prelude::*,
-    widgets::{canvas::*, *},
-};
-
-struct App {
-    x: f64,
-    y: f64,
-    ball: Rectangle,
-    playground: Rect,
-    vx: f64,
-    vy: f64,
-    dir_x: bool,
-    dir_y: bool,
-    tick_count: u64,
-    marker: Marker,
-}
-
-impl App {
-    fn new() -> App {
-        App {
-            x: 0.0,
-            y: 0.0,
-            ball: Rectangle {
-                x: 10.0,
-                y: 30.0,
-                width: 10.0,
-                height: 10.0,
-                color: Color::Yellow,
-            },
-            playground: Rect::new(10, 10, 100, 100),
-            vx: 1.0,
-            vy: 1.0,
-            dir_x: true,
-            dir_y: true,
-            tick_count: 0,
-            marker: Marker::Dot,
-        }
-    }
-
-    fn on_tick(&mut self) {
-        self.tick_count += 1;
-        // only change marker every 4 ticks (1s) to avoid stroboscopic effect
-        if (self.tick_count % 4) == 0 {
-            self.marker = match self.marker {
-                Marker::Dot => Marker::Block,
-                Marker::Block => Marker::Bar,
-                Marker::Bar => Marker::Braille,
-                Marker::Braille => Marker::Dot,
-            };
-        }
-        if self.ball.x < self.playground.left() as f64
-            || self.ball.x + self.ball.width > self.playground.right() as f64
-        {
-            self.dir_x = !self.dir_x;
-        }
-        if self.ball.y < self.playground.top() as f64
-            || self.ball.y + self.ball.height > self.playground.bottom() as f64
-        {
-            self.dir_y = !self.dir_y;
-        }
-
-        if self.dir_x {
-            self.ball.x += self.vx;
-        } else {
-            self.ball.x -= self.vx;
-        }
-
-        if self.dir_y {
-            self.ball.y += self.vy;
-        } else {
-            self.ball.y -= self.vy
-        }
-    }
-}
-
-fn main() -> Result<(), Box<dyn Error>> {
-    // setup terminal
-    enable_raw_mode()?;
-    let mut stdout = io::stdout();
-    execute!(stdout, EnterAlternateScreen, EnableMouseCapture)?;
-    let backend = CrosstermBackend::new(stdout);
-    let mut terminal = Terminal::new(backend)?;
-
-    // create app and run it
-    let tick_rate = Duration::from_millis(250);
-    let app = App::new();
-    let res = run_app(&mut terminal, app, tick_rate);
-
-    // restore terminal
-    disable_raw_mode()?;
-    execute!(
-        terminal.backend_mut(),
-        LeaveAlternateScreen,
-        DisableMouseCapture
-    )?;
-    terminal.show_cursor()?;
-
-    if let Err(err) = res {
-        println!("{err:?}");
-    }
-
-    Ok(())
-}
-
-fn run_app<B: Backend>(
-    terminal: &mut Terminal<B>,
-    mut app: App,
-    tick_rate: Duration,
-) -> io::Result<()> {
-    let mut last_tick = Instant::now();
-    loop {
-        terminal.draw(|f| ui(f, &app))?;
-
-        let timeout = tick_rate
-            .checked_sub(last_tick.elapsed())
-            .unwrap_or_else(|| Duration::from_secs(0));
-        if event::poll(timeout)? {
-            if let Event::Key(key) = event::read()? {
-                match key.code {
-                    KeyCode::Char('q') => {
-                        return Ok(());
-                    }
-                    KeyCode::Down => {
-                        app.y += 1.0;
-                    }
-                    KeyCode::Up => {
-                        app.y -= 1.0;
-                    }
-                    KeyCode::Right => {
-                        app.x += 1.0;
-                    }
-                    KeyCode::Left => {
-                        app.x -= 1.0;
-                    }
-                    _ => {}
-                }
-            }
-        }
-
-        if last_tick.elapsed() >= tick_rate {
-            app.on_tick();
-            last_tick = Instant::now();
-        }
-    }
-}
-
-fn ui<B: Backend>(f: &mut Frame<B>, app: &App) {
-    let chunks = Layout::default()
-        .direction(Direction::Horizontal)
-        .constraints([Constraint::Percentage(50), Constraint::Percentage(50)].as_ref())
-        .split(f.size());
-    let canvas = Canvas::default()
-        .block(Block::default().borders(Borders::ALL).title("World"))
-        .marker(app.marker)
-        .paint(|ctx| {
-            ctx.draw(&Map {
-                color: Color::White,
-                resolution: MapResolution::High,
-            });
-            ctx.print(app.x, -app.y, "You are here".yellow());
-        })
-        .x_bounds([-180.0, 180.0])
-        .y_bounds([-90.0, 90.0]);
-    f.render_widget(canvas, chunks[0]);
-    let canvas = Canvas::default()
-        .block(Block::default().borders(Borders::ALL).title("Pong"))
-        .marker(app.marker)
-        .paint(|ctx| {
-            ctx.draw(&app.ball);
-        })
-        .x_bounds([10.0, 110.0])
-        .y_bounds([10.0, 110.0]);
-    f.render_widget(canvas, chunks[1]);
-}

examples/chart.rs

@@ -1,259 +0,0 @@
-use std::{
-    error::Error,
-    io,
-    time::{Duration, Instant},
-};
-
-use crossterm::{
-    event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode},
-    execute,
-    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-};
-use ratatui::{prelude::*, widgets::*};
-
-const DATA: [(f64, f64); 5] = [(0.0, 0.0), (1.0, 1.0), (2.0, 2.0), (3.0, 3.0), (4.0, 4.0)];
-const DATA2: [(f64, f64); 7] = [
-    (0.0, 0.0),
-    (10.0, 1.0),
-    (20.0, 0.5),
-    (30.0, 1.5),
-    (40.0, 1.0),
-    (50.0, 2.5),
-    (60.0, 3.0),
-];
-
-#[derive(Clone)]
-pub struct SinSignal {
-    x: f64,
-    interval: f64,
-    period: f64,
-    scale: f64,
-}
-
-impl SinSignal {
-    pub fn new(interval: f64, period: f64, scale: f64) -> SinSignal {
-        SinSignal {
-            x: 0.0,
-            interval,
-            period,
-            scale,
-        }
-    }
-}
-
-impl Iterator for SinSignal {
-    type Item = (f64, f64);
-    fn next(&mut self) -> Option<Self::Item> {
-        let point = (self.x, (self.x * 1.0 / self.period).sin() * self.scale);
-        self.x += self.interval;
-        Some(point)
-    }
-}
-
-struct App {
-    signal1: SinSignal,
-    data1: Vec<(f64, f64)>,
-    signal2: SinSignal,
-    data2: Vec<(f64, f64)>,
-    window: [f64; 2],
-}
-
-impl App {
-    fn new() -> App {
-        let mut signal1 = SinSignal::new(0.2, 3.0, 18.0);
-        let mut signal2 = SinSignal::new(0.1, 2.0, 10.0);
-        let data1 = signal1.by_ref().take(200).collect::<Vec<(f64, f64)>>();
-        let data2 = signal2.by_ref().take(200).collect::<Vec<(f64, f64)>>();
-        App {
-            signal1,
-            data1,
-            signal2,
-            data2,
-            window: [0.0, 20.0],
-        }
-    }
-
-    fn on_tick(&mut self) {
-        for _ in 0..5 {
-            self.data1.remove(0);
-        }
-        self.data1.extend(self.signal1.by_ref().take(5));
-        for _ in 0..10 {
-            self.data2.remove(0);
-        }
-        self.data2.extend(self.signal2.by_ref().take(10));
-        self.window[0] += 1.0;
-        self.window[1] += 1.0;
-    }
-}
-
-fn main() -> Result<(), Box<dyn Error>> {
-    // setup terminal
-    enable_raw_mode()?;
-    let mut stdout = io::stdout();
-    execute!(stdout, EnterAlternateScreen, EnableMouseCapture)?;
-    let backend = CrosstermBackend::new(stdout);
-    let mut terminal = Terminal::new(backend)?;
-
-    // create app and run it
-    let tick_rate = Duration::from_millis(250);
-    let app = App::new();
-    let res = run_app(&mut terminal, app, tick_rate);
-
-    // restore terminal
-    disable_raw_mode()?;
-    execute!(
-        terminal.backend_mut(),
-        LeaveAlternateScreen,
-        DisableMouseCapture
-    )?;
-    terminal.show_cursor()?;
-
-    if let Err(err) = res {
-        println!("{err:?}");
-    }
-
-    Ok(())
-}
-
-fn run_app<B: Backend>(
-    terminal: &mut Terminal<B>,
-    mut app: App,
-    tick_rate: Duration,
-) -> io::Result<()> {
-    let mut last_tick = Instant::now();
-    loop {
-        terminal.draw(|f| ui(f, &app))?;
-
-        let timeout = tick_rate
-            .checked_sub(last_tick.elapsed())
-            .unwrap_or_else(|| Duration::from_secs(0));
-        if crossterm::event::poll(timeout)? {
-            if let Event::Key(key) = event::read()? {
-                if let KeyCode::Char('q') = key.code {
-                    return Ok(());
-                }
-            }
-        }
-        if last_tick.elapsed() >= tick_rate {
-            app.on_tick();
-            last_tick = Instant::now();
-        }
-    }
-}
-
-fn ui<B: Backend>(f: &mut Frame<B>, app: &App) {
-    let size = f.size();
-    let chunks = Layout::default()
-        .direction(Direction::Vertical)
-        .constraints(
-            [
-                Constraint::Ratio(1, 3),
-                Constraint::Ratio(1, 3),
-                Constraint::Ratio(1, 3),
-            ]
-            .as_ref(),
-        )
-        .split(size);
-    let x_labels = vec![
-        Span::styled(
-            format!("{}", app.window[0]),
-            Style::default().add_modifier(Modifier::BOLD),
-        ),
-        Span::raw(format!("{}", (app.window[0] + app.window[1]) / 2.0)),
-        Span::styled(
-            format!("{}", app.window[1]),
-            Style::default().add_modifier(Modifier::BOLD),
-        ),
-    ];
-    let datasets = vec![
-        Dataset::default()
-            .name("data2")
-            .marker(symbols::Marker::Dot)
-            .style(Style::default().fg(Color::Cyan))
-            .data(&app.data1),
-        Dataset::default()
-            .name("data3")
-            .marker(symbols::Marker::Braille)
-            .style(Style::default().fg(Color::Yellow))
-            .data(&app.data2),
-    ];
-
-    let chart = Chart::new(datasets)
-        .block(
-            Block::default()
-                .title("Chart 1".cyan().bold())
-                .borders(Borders::ALL),
-        )
-        .x_axis(
-            Axis::default()
-                .title("X Axis")
-                .style(Style::default().fg(Color::Gray))
-                .labels(x_labels)
-                .bounds(app.window),
-        )
-        .y_axis(
-            Axis::default()
-                .title("Y Axis")
-                .style(Style::default().fg(Color::Gray))
-                .labels(vec!["-20".bold(), "0".into(), "20".bold()])
-                .bounds([-20.0, 20.0]),
-        );
-    f.render_widget(chart, chunks[0]);
-
-    let datasets = vec![Dataset::default()
-        .name("data")
-        .marker(symbols::Marker::Braille)
-        .style(Style::default().fg(Color::Yellow))
-        .graph_type(GraphType::Line)
-        .data(&DATA)];
-    let chart = Chart::new(datasets)
-        .block(
-            Block::default()
-                .title("Chart 2".cyan().bold())
-                .borders(Borders::ALL),
-        )
-        .x_axis(
-            Axis::default()
-                .title("X Axis")
-                .style(Style::default().fg(Color::Gray))
-                .bounds([0.0, 5.0])
-                .labels(vec!["0".bold(), "2.5".into(), "5.0".bold()]),
-        )
-        .y_axis(
-            Axis::default()
-                .title("Y Axis")
-                .style(Style::default().fg(Color::Gray))
-                .bounds([0.0, 5.0])
-                .labels(vec!["0".bold(), "2.5".into(), "5.0".bold()]),
-        );
-    f.render_widget(chart, chunks[1]);
-
-    let datasets = vec![Dataset::default()
-        .name("data")
-        .marker(symbols::Marker::Braille)
-        .style(Style::default().fg(Color::Yellow))
-        .graph_type(GraphType::Line)
-        .data(&DATA2)];
-    let chart = Chart::new(datasets)
-        .block(
-            Block::default()
-                .title("Chart 3".cyan().bold())
-                .borders(Borders::ALL),
-        )
-        .x_axis(
-            Axis::default()
-                .title("X Axis")
-                .style(Style::default().fg(Color::Gray))
-                .bounds([0.0, 50.0])
-                .labels(vec!["0".bold(), "25".into(), "50".bold()]),
-        )
-        .y_axis(
-            Axis::default()
-                .title("Y Axis")
-                .style(Style::default().fg(Color::Gray))
-                .bounds([0.0, 5.0])
-                .labels(vec!["0".bold(), "2.5".into(), "5".bold()]),
-        );
-    f.render_widget(chart, chunks[2]);
-}

examples/colors.tape

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

examples/colors_rgb.rs

@@ -1,147 +0,0 @@
-/// This example shows the full range of RGB colors that can be displayed in the terminal.
-///
-/// Requires a terminal that supports 24-bit color (true color) and unicode.
-use std::{
-    error::Error,
-    io::{stdout, Stdout},
-    rc::Rc,
-    time::Duration,
-};
-
-use crossterm::{
-    event::{self, Event, KeyCode, KeyEventKind},
-    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-    ExecutableCommand,
-};
-use palette::{
-    convert::{FromColorUnclamped, IntoColorUnclamped},
-    Okhsv, Srgb,
-};
-use ratatui::{prelude::*, widgets::*};
-
-type Result<T> = std::result::Result<T, Box<dyn Error>>;
-
-fn main() -> Result<()> {
-    install_panic_hook();
-    App::new()?.run()
-}
-
-struct App {
-    terminal: Terminal<CrosstermBackend<Stdout>>,
-    should_quit: bool,
-}
-
-impl App {
-    pub fn new() -> Result<Self> {
-        Ok(Self {
-            terminal: Terminal::new(CrosstermBackend::new(stdout()))?,
-            should_quit: false,
-        })
-    }
-
-    pub fn run(mut self) -> Result<()> {
-        init_terminal()?;
-        self.terminal.clear()?;
-        while !self.should_quit {
-            self.draw()?;
-            self.handle_events()?;
-        }
-        restore_terminal()?;
-        Ok(())
-    }
-
-    fn draw(&mut self) -> Result<()> {
-        self.terminal.draw(|frame| {
-            frame.render_widget(RgbColors, frame.size());
-        })?;
-        Ok(())
-    }
-
-    fn handle_events(&mut self) -> Result<()> {
-        if event::poll(Duration::from_millis(100))? {
-            if let Event::Key(key) = event::read()? {
-                if key.kind == KeyEventKind::Press && key.code == KeyCode::Char('q') {
-                    self.should_quit = true;
-                };
-            }
-        }
-        Ok(())
-    }
-}
-
-impl Drop for App {
-    fn drop(&mut self) {
-        let _ = restore_terminal();
-    }
-}
-
-struct RgbColors;
-
-impl Widget for RgbColors {
-    fn render(self, area: Rect, buf: &mut Buffer) {
-        let layout = Self::layout(area);
-        Self::render_title(layout[0], buf);
-        Self::render_colors(layout[1], buf);
-    }
-}
-
-impl RgbColors {
-    fn layout(area: Rect) -> Rc<[Rect]> {
-        Layout::default()
-            .direction(Direction::Vertical)
-            .constraints(vec![Constraint::Length(1), Constraint::Min(0)])
-            .split(area)
-    }
-
-    fn render_title(area: Rect, buf: &mut Buffer) {
-        Paragraph::new("colors_rgb example. Press q to quit")
-            .dark_gray()
-            .alignment(Alignment::Center)
-            .render(area, buf);
-    }
-
-    /// Render a colored grid of half block characters (`"▀"`) each with a different RGB color.
-    fn render_colors(area: Rect, buf: &mut Buffer) {
-        for (xi, x) in (area.left()..area.right()).enumerate() {
-            for (yi, y) in (area.top()..area.bottom()).enumerate() {
-                let hue = xi as f32 * 360.0 / area.width as f32;
-
-                let value_fg = (yi as f32) / (area.height as f32 - 0.5);
-                let fg = Okhsv::<f32>::new(hue, Okhsv::max_saturation(), value_fg);
-                let fg: Srgb = fg.into_color_unclamped();
-                let fg: Srgb<u8> = fg.into_format();
-                let fg = Color::Rgb(fg.red, fg.green, fg.blue);
-
-                let value_bg = (yi as f32 + 0.5) / (area.height as f32 - 0.5);
-                let bg = Okhsv::new(hue, Okhsv::max_saturation(), value_bg);
-                let bg = Srgb::<f32>::from_color_unclamped(bg);
-                let bg: Srgb<u8> = bg.into_format();
-                let bg = Color::Rgb(bg.red, bg.green, bg.blue);
-
-                buf.get_mut(x, y).set_char('▀').set_fg(fg).set_bg(bg);
-            }
-        }
-    }
-}
-
-/// Install a panic hook that restores the terminal before panicking.
-fn install_panic_hook() {
-    better_panic::install();
-    let prev_hook = std::panic::take_hook();
-    std::panic::set_hook(Box::new(move |info| {
-        let _ = restore_terminal();
-        prev_hook(info);
-    }));
-}
-
-fn init_terminal() -> Result<()> {
-    enable_raw_mode()?;
-    stdout().execute(EnterAlternateScreen)?;
-    Ok(())
-}
-
-fn restore_terminal() -> Result<()> {
-    disable_raw_mode()?;
-    stdout().execute(LeaveAlternateScreen)?;
-    Ok(())
-}

examples/colors_rgb.tape

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

examples/custom_widget.rs

@@ -1,71 +0,0 @@
-use std::{error::Error, io};
-
-use crossterm::{
-    event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode},
-    execute,
-    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-};
-use ratatui::{prelude::*, widgets::*};
-
-#[derive(Default)]
-struct Label<'a> {
-    text: &'a str,
-}
-
-impl<'a> Widget for Label<'a> {
-    fn render(self, area: Rect, buf: &mut Buffer) {
-        buf.set_string(area.left(), area.top(), self.text, Style::default());
-    }
-}
-
-impl<'a> Label<'a> {
-    fn text(mut self, text: &'a str) -> Label<'a> {
-        self.text = text;
-        self
-    }
-}
-
-fn main() -> Result<(), Box<dyn Error>> {
-    // setup terminal
-    enable_raw_mode()?;
-    let mut stdout = io::stdout();
-    execute!(stdout, EnterAlternateScreen, EnableMouseCapture)?;
-    let backend = CrosstermBackend::new(stdout);
-    let mut terminal = Terminal::new(backend)?;
-
-    // create app and run it
-    let res = run_app(&mut terminal);
-
-    // restore terminal
-    disable_raw_mode()?;
-    execute!(
-        terminal.backend_mut(),
-        LeaveAlternateScreen,
-        DisableMouseCapture
-    )?;
-    terminal.show_cursor()?;
-
-    if let Err(err) = res {
-        println!("{err:?}");
-    }
-
-    Ok(())
-}
-
-fn run_app<B: Backend>(terminal: &mut Terminal<B>) -> io::Result<()> {
-    loop {
-        terminal.draw(ui)?;
-
-        if let Event::Key(key) = event::read()? {
-            if let KeyCode::Char('q') = key.code {
-                return Ok(());
-            }
-        }
-    }
-}
-
-fn ui<B: Backend>(f: &mut Frame<B>) {
-    let size = f.size();
-    let label = Label::default().text("Test");
-    f.render_widget(label, size);
-}

examples/demo/main.rs

@@ -1,36 +0,0 @@
-use std::{error::Error, time::Duration};
-
-use argh::FromArgs;
-
-mod app;
-#[cfg(feature = "crossterm")]
-mod crossterm;
-#[cfg(feature = "termion")]
-mod termion;
-#[cfg(feature = "termwiz")]
-mod termwiz;
-
-mod ui;
-
-/// Demo
-#[derive(Debug, FromArgs)]
-struct Cli {
-    /// time in ms between two ticks.
-    #[argh(option, default = "250")]
-    tick_rate: u64,
-    /// whether unicode symbols are used to improve the overall look of the app
-    #[argh(option, default = "true")]
-    enhanced_graphics: bool,
-}
-
-fn main() -> Result<(), Box<dyn Error>> {
-    let cli: Cli = argh::from_env();
-    let tick_rate = Duration::from_millis(cli.tick_rate);
-    #[cfg(feature = "crossterm")]
-    crate::crossterm::run(tick_rate, cli.enhanced_graphics)?;
-    #[cfg(feature = "termion")]
-    crate::termion::run(tick_rate, cli.enhanced_graphics)?;
-    #[cfg(feature = "termwiz")]
-    crate::termwiz::run(tick_rate, cli.enhanced_graphics)?;
-    Ok(())
-}

examples/demo2/app.rs

@@ -1,99 +0,0 @@
-use std::time::Duration;
-
-use anyhow::{Context, Result};
-use crossterm::event::{Event, KeyCode, KeyEvent, KeyEventKind, KeyModifiers};
-use ratatui::prelude::Rect;
-
-use crate::{Root, Term};
-
-#[derive(Debug)]
-pub struct App {
-    term: Term,
-    should_quit: bool,
-    context: AppContext,
-}
-
-#[derive(Debug, Default, Clone, Copy)]
-pub struct AppContext {
-    pub tab_index: usize,
-    pub row_index: usize,
-}
-
-impl App {
-    fn new() -> Result<Self> {
-        Ok(Self {
-            term: Term::start()?,
-            should_quit: false,
-            context: AppContext::default(),
-        })
-    }
-
-    pub fn run() -> Result<()> {
-        install_panic_hook();
-        let mut app = Self::new()?;
-        while !app.should_quit {
-            app.draw()?;
-            app.handle_events()?;
-        }
-        Term::stop()?;
-        Ok(())
-    }
-
-    fn draw(&mut self) -> Result<()> {
-        self.term
-            .draw(|frame| frame.render_widget(Root::new(&self.context), frame.size()))
-            .context("terminal.draw")?;
-        Ok(())
-    }
-
-    fn handle_events(&mut self) -> Result<()> {
-        match Term::next_event(Duration::from_millis(16))? {
-            Some(Event::Key(key)) => self.handle_key_event(key),
-            Some(Event::Resize(width, height)) => {
-                Ok(self.term.resize(Rect::new(0, 0, width, height))?)
-            }
-            _ => Ok(()),
-        }
-    }
-
-    fn handle_key_event(&mut self, key: KeyEvent) -> Result<()> {
-        if key.kind != KeyEventKind::Press {
-            return Ok(());
-        }
-
-        let context = &mut self.context;
-        const TAB_COUNT: usize = 5;
-        match key.code {
-            KeyCode::Char('q') | KeyCode::Esc => {
-                self.should_quit = true;
-            }
-            KeyCode::Tab | KeyCode::BackTab if key.modifiers.contains(KeyModifiers::SHIFT) => {
-                let tab_index = context.tab_index + TAB_COUNT; // to wrap around properly
-                context.tab_index = tab_index.saturating_sub(1) % TAB_COUNT;
-                context.row_index = 0;
-            }
-            KeyCode::Tab | KeyCode::BackTab => {
-                context.tab_index = context.tab_index.saturating_add(1) % TAB_COUNT;
-                context.row_index = 0;
-            }
-            KeyCode::Up | KeyCode::Char('k') => {
-                context.row_index = context.row_index.saturating_sub(1);
-            }
-            KeyCode::Down | KeyCode::Char('j') => {
-                context.row_index = context.row_index.saturating_add(1);
-            }
-            _ => {}
-        };
-        Ok(())
-    }
-}
-
-pub fn install_panic_hook() {
-    better_panic::install();
-    let hook = std::panic::take_hook();
-    std::panic::set_hook(Box::new(move |info| {
-        let _ = Term::stop();
-        hook(info);
-        std::process::exit(1);
-    }));
-}

examples/demo2/main.rs

@@ -1,17 +0,0 @@
-use anyhow::Result;
-pub use app::*;
-pub use colors::*;
-pub use root::*;
-pub use term::*;
-pub use theme::*;
-
-mod app;
-mod colors;
-mod root;
-mod tabs;
-mod term;
-mod theme;
-
-fn main() -> Result<()> {
-    App::run()
-}

examples/demo2/root.rs

@@ -1,93 +0,0 @@
-use std::rc::Rc;
-
-use itertools::Itertools;
-use ratatui::{prelude::*, widgets::*};
-
-use crate::{tabs::*, AppContext, THEME};
-
-pub struct Root<'a> {
-    context: &'a AppContext,
-}
-
-impl<'a> Root<'a> {
-    pub fn new(context: &'a AppContext) -> Self {
-        Root { context }
-    }
-}
-
-impl Widget for Root<'_> {
-    fn render(self, area: Rect, buf: &mut Buffer) {
-        Block::new().style(THEME.root).render(area, buf);
-        let area = layout(area, Direction::Vertical, vec![1, 0, 1]);
-        self.render_title_bar(area[0], buf);
-        self.render_selected_tab(area[1], buf);
-        self.render_bottom_bar(area[2], buf);
-    }
-}
-
-impl Root<'_> {
-    fn render_title_bar(&self, area: Rect, buf: &mut Buffer) {
-        let area = layout(area, Direction::Horizontal, vec![0, 45]);
-
-        Paragraph::new(Span::styled("Ratatui", THEME.app_title)).render(area[0], buf);
-        let titles = vec!["", " Recipe ", " Email ", " Traceroute ", " Weather "];
-        Tabs::new(titles)
-            .style(THEME.tabs)
-            .highlight_style(THEME.tabs_selected)
-            .select(self.context.tab_index)
-            .divider("")
-            .render(area[1], buf);
-    }
-
-    fn render_selected_tab(&self, area: Rect, buf: &mut Buffer) {
-        let row_index = self.context.row_index;
-        match self.context.tab_index {
-            0 => AboutTab::new(row_index).render(area, buf),
-            1 => RecipeTab::new(row_index).render(area, buf),
-            2 => EmailTab::new(row_index).render(area, buf),
-            3 => TracerouteTab::new(row_index).render(area, buf),
-            4 => WeatherTab::new(row_index).render(area, buf),
-            _ => unreachable!(),
-        };
-    }
-
-    fn render_bottom_bar(&self, area: Rect, buf: &mut Buffer) {
-        let keys = [
-            ("Q/Esc", "Quit"),
-            ("Tab", "Next Tab"),
-            ("↑/k", "Up"),
-            ("↓/j", "Down"),
-        ];
-        let spans = keys
-            .iter()
-            .flat_map(|(key, desc)| {
-                let key = Span::styled(format!(" {} ", key), THEME.key_binding.key);
-                let desc = Span::styled(format!(" {} ", desc), THEME.key_binding.description);
-                [key, desc]
-            })
-            .collect_vec();
-        Paragraph::new(Line::from(spans))
-            .alignment(Alignment::Center)
-            .fg(Color::Indexed(236))
-            .bg(Color::Indexed(232))
-            .render(area, buf);
-    }
-}
-
-/// simple helper method to split an area into multiple sub-areas
-pub fn layout(area: Rect, direction: Direction, heights: Vec<u16>) -> Rc<[Rect]> {
-    let constraints = heights
-        .iter()
-        .map(|&h| {
-            if h > 0 {
-                Constraint::Length(h)
-            } else {
-                Constraint::Min(0)
-            }
-        })
-        .collect_vec();
-    Layout::default()
-        .direction(direction)
-        .constraints(constraints)
-        .split(area)
-}

examples/demo2/term.rs

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

examples/gauge.rs

@@ -1,159 +0,0 @@
-use std::{
-    error::Error,
-    io,
-    time::{Duration, Instant},
-};
-
-use crossterm::{
-    event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode},
-    execute,
-    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-};
-use ratatui::{prelude::*, widgets::*};
-
-struct App {
-    progress1: u16,
-    progress2: u16,
-    progress3: f64,
-    progress4: u16,
-}
-
-impl App {
-    fn new() -> App {
-        App {
-            progress1: 0,
-            progress2: 0,
-            progress3: 0.45,
-            progress4: 0,
-        }
-    }
-
-    fn on_tick(&mut self) {
-        self.progress1 += 1;
-        if self.progress1 > 100 {
-            self.progress1 = 0;
-        }
-        self.progress2 += 2;
-        if self.progress2 > 100 {
-            self.progress2 = 0;
-        }
-        self.progress3 += 0.001;
-        if self.progress3 > 1.0 {
-            self.progress3 = 0.0;
-        }
-        self.progress4 += 1;
-        if self.progress4 > 100 {
-            self.progress4 = 0;
-        }
-    }
-}
-
-fn main() -> Result<(), Box<dyn Error>> {
-    // setup terminal
-    enable_raw_mode()?;
-    let mut stdout = io::stdout();
-    execute!(stdout, EnterAlternateScreen, EnableMouseCapture)?;
-    let backend = CrosstermBackend::new(stdout);
-    let mut terminal = Terminal::new(backend)?;
-
-    // create app and run it
-    let tick_rate = Duration::from_millis(250);
-    let app = App::new();
-    let res = run_app(&mut terminal, app, tick_rate);
-
-    // restore terminal
-    disable_raw_mode()?;
-    execute!(
-        terminal.backend_mut(),
-        LeaveAlternateScreen,
-        DisableMouseCapture
-    )?;
-    terminal.show_cursor()?;
-
-    if let Err(err) = res {
-        println!("{err:?}");
-    }
-
-    Ok(())
-}
-
-fn run_app<B: Backend>(
-    terminal: &mut Terminal<B>,
-    mut app: App,
-    tick_rate: Duration,
-) -> io::Result<()> {
-    let mut last_tick = Instant::now();
-    loop {
-        terminal.draw(|f| ui(f, &app))?;
-
-        let timeout = tick_rate
-            .checked_sub(last_tick.elapsed())
-            .unwrap_or_else(|| Duration::from_secs(0));
-        if crossterm::event::poll(timeout)? {
-            if let Event::Key(key) = event::read()? {
-                if let KeyCode::Char('q') = key.code {
-                    return Ok(());
-                }
-            }
-        }
-        if last_tick.elapsed() >= tick_rate {
-            app.on_tick();
-            last_tick = Instant::now();
-        }
-    }
-}
-
-fn ui<B: Backend>(f: &mut Frame<B>, app: &App) {
-    let chunks = Layout::default()
-        .direction(Direction::Vertical)
-        .constraints(
-            [
-                Constraint::Percentage(25),
-                Constraint::Percentage(25),
-                Constraint::Percentage(25),
-                Constraint::Percentage(25),
-            ]
-            .as_ref(),
-        )
-        .split(f.size());
-
-    let gauge = Gauge::default()
-        .block(Block::default().title("Gauge1").borders(Borders::ALL))
-        .gauge_style(Style::default().fg(Color::Yellow))
-        .percent(app.progress1);
-    f.render_widget(gauge, chunks[0]);
-
-    let label = format!("{}/100", app.progress2);
-    let gauge = Gauge::default()
-        .block(Block::default().title("Gauge2").borders(Borders::ALL))
-        .gauge_style(Style::default().fg(Color::Magenta).bg(Color::Green))
-        .percent(app.progress2)
-        .label(label);
-    f.render_widget(gauge, chunks[1]);
-
-    let label = Span::styled(
-        format!("{:.2}%", app.progress3 * 100.0),
-        Style::default()
-            .fg(Color::Red)
-            .add_modifier(Modifier::ITALIC | Modifier::BOLD),
-    );
-    let gauge = Gauge::default()
-        .block(Block::default().title("Gauge3").borders(Borders::ALL))
-        .gauge_style(Style::default().fg(Color::Yellow))
-        .ratio(app.progress3)
-        .label(label)
-        .use_unicode(true);
-    f.render_widget(gauge, chunks[2]);
-
-    let label = format!("{}/100", app.progress4);
-    let gauge = Gauge::default()
-        .block(Block::default().title("Gauge4").borders(Borders::ALL))
-        .gauge_style(
-            Style::default()
-                .fg(Color::Cyan)
-                .add_modifier(Modifier::ITALIC),
-        )
-        .percent(app.progress4)
-        .label(label);
-    f.render_widget(gauge, chunks[3]);
-}

examples/hello_world.rs

@@ -1,80 +0,0 @@
-use std::{
-    io::{self, Stdout},
-    time::Duration,
-};
-
-use anyhow::{Context, Result};
-use crossterm::{
-    event::{self, Event, KeyCode},
-    execute,
-    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-};
-use ratatui::{prelude::*, widgets::*};
-
-/// This is a bare minimum example. There are many approaches to running an application loop, so
-/// this is not meant to be prescriptive. It is only meant to demonstrate the basic setup and
-/// teardown of a terminal application.
-///
-/// A more robust application would probably want to handle errors and ensure that the terminal is
-/// restored to a sane state before exiting. This example does not do that. It also does not handle
-/// events or update the application state. It just draws a greeting and exits when the user
-/// presses 'q'.
-fn main() -> Result<()> {
-    let mut terminal = setup_terminal().context("setup failed")?;
-    run(&mut terminal).context("app loop failed")?;
-    restore_terminal(&mut terminal).context("restore terminal failed")?;
-    Ok(())
-}
-
-/// Setup the terminal. This is where you would enable raw mode, enter the alternate screen, and
-/// hide the cursor. This example does not handle errors. A more robust application would probably
-/// want to handle errors and ensure that the terminal is restored to a sane state before exiting.
-fn setup_terminal() -> Result<Terminal<CrosstermBackend<Stdout>>> {
-    let mut stdout = io::stdout();
-    enable_raw_mode().context("failed to enable raw mode")?;
-    execute!(stdout, EnterAlternateScreen).context("unable to enter alternate screen")?;
-    Terminal::new(CrosstermBackend::new(stdout)).context("creating terminal failed")
-}
-
-/// Restore the terminal. This is where you disable raw mode, leave the alternate screen, and show
-/// the cursor.
-fn restore_terminal(terminal: &mut Terminal<CrosstermBackend<Stdout>>) -> Result<()> {
-    disable_raw_mode().context("failed to disable raw mode")?;
-    execute!(terminal.backend_mut(), LeaveAlternateScreen)
-        .context("unable to switch to main screen")?;
-    terminal.show_cursor().context("unable to show cursor")
-}
-
-/// Run the application loop. This is where you would handle events and update the application
-/// state. This example exits when the user presses 'q'. Other styles of application loops are
-/// possible, for example, you could have multiple application states and switch between them based
-/// on events, or you could have a single application state and update it based on events.
-fn run(terminal: &mut Terminal<CrosstermBackend<Stdout>>) -> Result<()> {
-    loop {
-        terminal.draw(crate::render_app)?;
-        if should_quit()? {
-            break;
-        }
-    }
-    Ok(())
-}
-
-/// Render the application. This is where you would draw the application UI. This example just
-/// draws a greeting.
-fn render_app(frame: &mut ratatui::Frame<CrosstermBackend<Stdout>>) {
-    let greeting = Paragraph::new("Hello World! (press 'q' to quit)");
-    frame.render_widget(greeting, frame.size());
-}
-
-/// Check if the user has pressed 'q'. This is where you would handle events. This example just
-/// checks if the user has pressed 'q' and returns true if they have. It does not handle any other
-/// events. There is a 250ms timeout on the event poll so that the application can exit in a timely
-/// manner, and to ensure that the terminal is rendered at least once every 250ms.
-fn should_quit() -> Result<bool> {
-    if event::poll(Duration::from_millis(250)).context("event poll failed")? {
-        if let Event::Key(key) = event::read().context("event read failed")? {
-            return Ok(KeyCode::Char('q') == key.code);
-        }
-    }
-    Ok(false)
-}

examples/layout.rs

@@ -1,223 +0,0 @@
-use std::{error::Error, io};
-
-use crossterm::{
-    event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode},
-    execute,
-    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-};
-use itertools::Itertools;
-use ratatui::{layout::Constraint::*, prelude::*, widgets::*};
-
-fn main() -> Result<(), Box<dyn Error>> {
-    // setup terminal
-    enable_raw_mode()?;
-    let mut stdout = io::stdout();
-    execute!(stdout, EnterAlternateScreen, EnableMouseCapture)?;
-    let backend = CrosstermBackend::new(stdout);
-    let mut terminal = Terminal::new(backend)?;
-
-    // create app and run it
-    let res = run_app(&mut terminal);
-
-    // restore terminal
-    disable_raw_mode()?;
-    execute!(
-        terminal.backend_mut(),
-        LeaveAlternateScreen,
-        DisableMouseCapture
-    )?;
-    terminal.show_cursor()?;
-
-    if let Err(err) = res {
-        println!("{err:?}");
-    }
-
-    Ok(())
-}
-
-fn run_app<B: Backend>(terminal: &mut Terminal<B>) -> io::Result<()> {
-    loop {
-        terminal.draw(|f| ui(f))?;
-
-        if let Event::Key(key) = event::read()? {
-            if let KeyCode::Char('q') = key.code {
-                return Ok(());
-            }
-        }
-    }
-}
-
-fn ui<B: Backend>(frame: &mut Frame<B>) {
-    let main_layout = Layout::default()
-        .direction(Direction::Vertical)
-        .constraints(vec![
-            Length(4),  // text
-            Length(50), // examples
-            Min(0),     // fills remaining space
-        ])
-        .split(frame.size());
-
-    // title
-    frame.render_widget(
-        Paragraph::new(vec![
-            Line::from("Horizontal Layout Example. Press q to quit".dark_gray())
-                .alignment(Alignment::Center),
-            Line::from("Each line has 2 constraints, plus Min(0) to fill the remaining space."),
-            Line::from("E.g. the second line of the Len/Min box is [Length(2), Min(2), Min(0)]"),
-            Line::from("Note: constraint labels that don't fit are truncated"),
-        ]),
-        main_layout[0],
-    );
-
-    let example_rows = Layout::default()
-        .direction(Direction::Vertical)
-        .constraints(vec![
-            Length(9),
-            Length(9),
-            Length(9),
-            Length(9),
-            Length(9),
-            Min(0), // fills remaining space
-        ])
-        .split(main_layout[1]);
-    let example_areas = example_rows
-        .iter()
-        .flat_map(|area| {
-            Layout::default()
-                .direction(Direction::Horizontal)
-                .constraints(vec![
-                    Length(14),
-                    Length(14),
-                    Length(14),
-                    Length(14),
-                    Length(14),
-                    Min(0), // fills remaining space
-                ])
-                .split(*area)
-                .iter()
-                .copied()
-                .take(5) // ignore Min(0)
-                .collect_vec()
-        })
-        .collect_vec();
-
-    // the examples are a cartesian product of the following constraints
-    // e.g. Len/Len, Len/Min, Len/Max, Len/Perc, Len/Ratio, Min/Len, Min/Min, ...
-    let examples = [
-        (
-            "Len",
-            vec![
-                Length(0),
-                Length(2),
-                Length(3),
-                Length(6),
-                Length(10),
-                Length(15),
-            ],
-        ),
-        (
-            "Min",
-            vec![Min(0), Min(2), Min(3), Min(6), Min(10), Min(15)],
-        ),
-        (
-            "Max",
-            vec![Max(0), Max(2), Max(3), Max(6), Max(10), Max(15)],
-        ),
-        (
-            "Perc",
-            vec![
-                Percentage(0),
-                Percentage(25),
-                Percentage(50),
-                Percentage(75),
-                Percentage(100),
-                Percentage(150),
-            ],
-        ),
-        (
-            "Ratio",
-            vec![
-                Ratio(0, 4),
-                Ratio(1, 4),
-                Ratio(2, 4),
-                Ratio(3, 4),
-                Ratio(4, 4),
-                Ratio(6, 4),
-            ],
-        ),
-    ];
-
-    for (i, (a, b)) in examples
-        .iter()
-        .cartesian_product(examples.iter())
-        .enumerate()
-    {
-        let (name_a, examples_a) = a;
-        let (name_b, examples_b) = b;
-        let constraints = examples_a
-            .iter()
-            .copied()
-            .zip(examples_b.iter().copied())
-            .collect_vec();
-        render_example_combination(
-            frame,
-            example_areas[i],
-            &format!("{name_a}/{name_b}"),
-            constraints,
-        );
-    }
-}
-
-/// Renders a single example box
-fn render_example_combination<B: Backend>(
-    frame: &mut Frame<B>,
-    area: Rect,
-    title: &str,
-    constraints: Vec<(Constraint, Constraint)>,
-) {
-    let block = Block::default()
-        .title(title.gray())
-        .style(Style::reset())
-        .borders(Borders::ALL)
-        .border_style(Style::default().fg(Color::DarkGray));
-    let inner = block.inner(area);
-    frame.render_widget(block, area);
-    let layout = Layout::default()
-        .direction(Direction::Vertical)
-        .constraints(vec![Length(1); constraints.len() + 1])
-        .split(inner);
-    for (i, (a, b)) in constraints.iter().enumerate() {
-        render_single_example(frame, layout[i], vec![*a, *b, Min(0)]);
-    }
-    // This is to make it easy to visually see the alignment of the examples
-    // with the constraints.
-    frame.render_widget(Paragraph::new("123456789012"), layout[6]);
-}
-
-/// Renders a single example line
-fn render_single_example<B: Backend>(
-    frame: &mut Frame<B>,
-    area: Rect,
-    constraints: Vec<Constraint>,
-) {
-    let red = Paragraph::new(constraint_label(constraints[0])).on_red();
-    let blue = Paragraph::new(constraint_label(constraints[1])).on_blue();
-    let green = Paragraph::new("·".repeat(12)).on_green();
-    let layout = Layout::default()
-        .direction(Direction::Horizontal)
-        .constraints(constraints)
-        .split(area);
-    frame.render_widget(red, layout[0]);
-    frame.render_widget(blue, layout[1]);
-    frame.render_widget(green, layout[2]);
-}
-
-fn constraint_label(constraint: Constraint) -> String {
-    match constraint {
-        Length(n) => format!("{n}"),
-        Min(n) => format!("{n}"),
-        Max(n) => format!("{n}"),
-        Percentage(n) => format!("{n}"),
-        Ratio(a, b) => format!("{a}:{b}"),
-    }
-}

examples/list.rs

@@ -1,280 +0,0 @@
-use std::{
-    error::Error,
-    io,
-    time::{Duration, Instant},
-};
-
-use crossterm::{
-    event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode, KeyEventKind},
-    execute,
-    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-};
-use ratatui::{prelude::*, widgets::*};
-
-struct StatefulList<T> {
-    state: ListState,
-    items: Vec<T>,
-}
-
-impl<T> StatefulList<T> {
-    fn with_items(items: Vec<T>) -> StatefulList<T> {
-        StatefulList {
-            state: ListState::default(),
-            items,
-        }
-    }
-
-    fn next(&mut self) {
-        let i = match self.state.selected() {
-            Some(i) => {
-                if i >= self.items.len() - 1 {
-                    0
-                } else {
-                    i + 1
-                }
-            }
-            None => 0,
-        };
-        self.state.select(Some(i));
-    }
-
-    fn previous(&mut self) {
-        let i = match self.state.selected() {
-            Some(i) => {
-                if i == 0 {
-                    self.items.len() - 1
-                } else {
-                    i - 1
-                }
-            }
-            None => 0,
-        };
-        self.state.select(Some(i));
-    }
-
-    fn unselect(&mut self) {
-        self.state.select(None);
-    }
-}
-
-/// This struct holds the current state of the app. In particular, it has the `items` field which is
-/// a wrapper around `ListState`. Keeping track of the items state let us render the associated
-/// widget with its state and have access to features such as natural scrolling.
-///
-/// Check the event handling at the bottom to see how to change the state on incoming events.
-/// Check the drawing logic for items on how to specify the highlighting style for selected items.
-struct App<'a> {
-    items: StatefulList<(&'a str, usize)>,
-    events: Vec<(&'a str, &'a str)>,
-}
-
-impl<'a> App<'a> {
-    fn new() -> App<'a> {
-        App {
-            items: StatefulList::with_items(vec![
-                ("Item0", 1),
-                ("Item1", 2),
-                ("Item2", 1),
-                ("Item3", 3),
-                ("Item4", 1),
-                ("Item5", 4),
-                ("Item6", 1),
-                ("Item7", 3),
-                ("Item8", 1),
-                ("Item9", 6),
-                ("Item10", 1),
-                ("Item11", 3),
-                ("Item12", 1),
-                ("Item13", 2),
-                ("Item14", 1),
-                ("Item15", 1),
-                ("Item16", 4),
-                ("Item17", 1),
-                ("Item18", 5),
-                ("Item19", 4),
-                ("Item20", 1),
-                ("Item21", 2),
-                ("Item22", 1),
-                ("Item23", 3),
-                ("Item24", 1),
-            ]),
-            events: vec![
-                ("Event1", "INFO"),
-                ("Event2", "INFO"),
-                ("Event3", "CRITICAL"),
-                ("Event4", "ERROR"),
-                ("Event5", "INFO"),
-                ("Event6", "INFO"),
-                ("Event7", "WARNING"),
-                ("Event8", "INFO"),
-                ("Event9", "INFO"),
-                ("Event10", "INFO"),
-                ("Event11", "CRITICAL"),
-                ("Event12", "INFO"),
-                ("Event13", "INFO"),
-                ("Event14", "INFO"),
-                ("Event15", "INFO"),
-                ("Event16", "INFO"),
-                ("Event17", "ERROR"),
-                ("Event18", "ERROR"),
-                ("Event19", "INFO"),
-                ("Event20", "INFO"),
-                ("Event21", "WARNING"),
-                ("Event22", "INFO"),
-                ("Event23", "INFO"),
-                ("Event24", "WARNING"),
-                ("Event25", "INFO"),
-                ("Event26", "INFO"),
-            ],
-        }
-    }
-
-    /// Rotate through the event list.
-    /// This only exists to simulate some kind of "progress"
-    fn on_tick(&mut self) {
-        let event = self.events.remove(0);
-        self.events.push(event);
-    }
-}
-
-fn main() -> Result<(), Box<dyn Error>> {
-    // setup terminal
-    enable_raw_mode()?;
-    let mut stdout = io::stdout();
-    execute!(stdout, EnterAlternateScreen, EnableMouseCapture)?;
-    let backend = CrosstermBackend::new(stdout);
-    let mut terminal = Terminal::new(backend)?;
-
-    // create app and run it
-    let tick_rate = Duration::from_millis(250);
-    let app = App::new();
-    let res = run_app(&mut terminal, app, tick_rate);
-
-    // restore terminal
-    disable_raw_mode()?;
-    execute!(
-        terminal.backend_mut(),
-        LeaveAlternateScreen,
-        DisableMouseCapture
-    )?;
-    terminal.show_cursor()?;
-
-    if let Err(err) = res {
-        println!("{err:?}");
-    }
-
-    Ok(())
-}
-
-fn run_app<B: Backend>(
-    terminal: &mut Terminal<B>,
-    mut app: App,
-    tick_rate: Duration,
-) -> io::Result<()> {
-    let mut last_tick = Instant::now();
-    loop {
-        terminal.draw(|f| ui(f, &mut app))?;
-
-        let timeout = tick_rate
-            .checked_sub(last_tick.elapsed())
-            .unwrap_or_else(|| Duration::from_secs(0));
-        if crossterm::event::poll(timeout)? {
-            if let Event::Key(key) = event::read()? {
-                if key.kind == KeyEventKind::Press {
-                    match key.code {
-                        KeyCode::Char('q') => return Ok(()),
-                        KeyCode::Left => app.items.unselect(),
-                        KeyCode::Down => app.items.next(),
-                        KeyCode::Up => app.items.previous(),
-                        _ => {}
-                    }
-                }
-            }
-        }
-        if last_tick.elapsed() >= tick_rate {
-            app.on_tick();
-            last_tick = Instant::now();
-        }
-    }
-}
-
-fn ui<B: Backend>(f: &mut Frame<B>, app: &mut App) {
-    // Create two chunks with equal horizontal screen space
-    let chunks = Layout::default()
-        .direction(Direction::Horizontal)
-        .constraints([Constraint::Percentage(50), Constraint::Percentage(50)].as_ref())
-        .split(f.size());
-
-    // Iterate through all elements in the `items` app and append some debug text to it.
-    let items: Vec<ListItem> = app
-        .items
-        .items
-        .iter()
-        .map(|i| {
-            let mut lines = vec![Line::from(i.0)];
-            for _ in 0..i.1 {
-                lines.push(
-                    "Lorem ipsum dolor sit amet, consectetur adipiscing elit."
-                        .italic()
-                        .into(),
-                );
-            }
-            ListItem::new(lines).style(Style::default().fg(Color::Black).bg(Color::White))
-        })
-        .collect();
-
-    // Create a List from all list items and highlight the currently selected one
-    let items = List::new(items)
-        .block(Block::default().borders(Borders::ALL).title("List"))
-        .highlight_style(
-            Style::default()
-                .bg(Color::LightGreen)
-                .add_modifier(Modifier::BOLD),
-        )
-        .highlight_symbol(">> ");
-
-    // We can now render the item list
-    f.render_stateful_widget(items, chunks[0], &mut app.items.state);
-
-    // Let's do the same for the events.
-    // The event list doesn't have any state and only displays the current state of the list.
-    let events: Vec<ListItem> = app
-        .events
-        .iter()
-        .rev()
-        .map(|&(event, level)| {
-            // Colorcode the level depending on its type
-            let s = match level {
-                "CRITICAL" => Style::default().fg(Color::Red),
-                "ERROR" => Style::default().fg(Color::Magenta),
-                "WARNING" => Style::default().fg(Color::Yellow),
-                "INFO" => Style::default().fg(Color::Blue),
-                _ => Style::default(),
-            };
-            // Add a example datetime and apply proper spacing between them
-            let header = Line::from(vec![
-                Span::styled(format!("{level:<9}"), s),
-                " ".into(),
-                "2020-01-01 10:00:00".italic(),
-            ]);
-            // The event gets its own line
-            let log = Line::from(vec![event.into()]);
-
-            // Here several things happen:
-            // 1. Add a `---` spacing line above the final list entry
-            // 2. Add the Level + datetime
-            // 3. Add a spacer line
-            // 4. Add the actual event
-            ListItem::new(vec![
-                Line::from("-".repeat(chunks[1].width as usize)),
-                header,
-                Line::from(""),
-                log,
-            ])
-        })
-        .collect();
-    let events_list = List::new(events)
-        .block(Block::default().borders(Borders::ALL).title("List"))
-        .start_corner(Corner::BottomLeft);
-    f.render_widget(events_list, chunks[1]);
-}

examples/modifiers.rs

@@ -1,116 +0,0 @@
-/// This example is useful for testing how your terminal emulator handles different modifiers.
-/// It will render a grid of combinations of foreground and background colors with all
-/// modifiers applied to them.
-use std::{
-    error::Error,
-    io::{self, Stdout},
-    iter::once,
-    result,
-    time::Duration,
-};
-
-use crossterm::{
-    event::{self, Event, KeyCode},
-    execute,
-    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-};
-use itertools::Itertools;
-use ratatui::{prelude::*, widgets::*};
-
-type Result<T> = result::Result<T, Box<dyn Error>>;
-
-fn main() -> Result<()> {
-    let mut terminal = setup_terminal()?;
-    let res = run_app(&mut terminal);
-    restore_terminal(terminal)?;
-    if let Err(err) = res {
-        eprintln!("{err:?}");
-    }
-    Ok(())
-}
-
-fn run_app<B: Backend>(terminal: &mut Terminal<B>) -> io::Result<()> {
-    loop {
-        terminal.draw(ui)?;
-
-        if event::poll(Duration::from_millis(250))? {
-            if let Event::Key(key) = event::read()? {
-                if let KeyCode::Char('q') = key.code {
-                    return Ok(());
-                }
-            }
-        }
-    }
-}
-
-fn ui<B: Backend>(frame: &mut Frame<B>) {
-    let layout = Layout::default()
-        .direction(Direction::Vertical)
-        .constraints(vec![Constraint::Length(1), Constraint::Min(0)])
-        .split(frame.size());
-    frame.render_widget(
-        Paragraph::new("Note: not all terminals support all modifiers")
-            .style(Style::default().fg(Color::Red).add_modifier(Modifier::BOLD)),
-        layout[0],
-    );
-    let layout = Layout::default()
-        .direction(Direction::Vertical)
-        .constraints(vec![Constraint::Length(1); 50])
-        .split(layout[1])
-        .iter()
-        .flat_map(|area| {
-            Layout::default()
-                .direction(Direction::Horizontal)
-                .constraints(vec![Constraint::Percentage(20); 5])
-                .split(*area)
-                .to_vec()
-        })
-        .collect_vec();
-
-    let colors = [
-        Color::Black,
-        Color::DarkGray,
-        Color::Gray,
-        Color::White,
-        Color::Red,
-    ];
-    let all_modifiers = once(Modifier::empty())
-        .chain(Modifier::all().iter())
-        .collect_vec();
-    let mut index = 0;
-    for bg in colors.iter() {
-        for fg in colors.iter() {
-            for modifier in &all_modifiers {
-                let modifier_name = format!("{modifier:11?}");
-                let padding = (" ").repeat(12 - modifier_name.len());
-                let paragraph = Paragraph::new(Line::from(vec![
-                    modifier_name.fg(*fg).bg(*bg).add_modifier(*modifier),
-                    padding.fg(*fg).bg(*bg).add_modifier(*modifier),
-                    // This is a hack to work around a bug in VHS which is used for rendering the
-                    // examples to gifs. The bug is that the background color of a paragraph seems
-                    // to bleed into the next character.
-                    ".".black().on_black(),
-                ]));
-                frame.render_widget(paragraph, layout[index]);
-                index += 1;
-            }
-        }
-    }
-}
-
-fn setup_terminal() -> Result<Terminal<CrosstermBackend<Stdout>>> {
-    enable_raw_mode()?;
-    let mut stdout = io::stdout();
-    execute!(stdout, EnterAlternateScreen)?;
-    let backend = CrosstermBackend::new(stdout);
-    let mut terminal = Terminal::new(backend)?;
-    terminal.hide_cursor()?;
-    Ok(terminal)
-}
-
-fn restore_terminal(mut terminal: Terminal<CrosstermBackend<Stdout>>) -> Result<()> {
-    disable_raw_mode()?;
-    execute!(terminal.backend_mut(), LeaveAlternateScreen)?;
-    terminal.show_cursor()?;
-    Ok(())
-}

examples/panic.rs

@@ -1,134 +0,0 @@
-//! How to use a panic hook to reset the terminal before printing the panic to
-//! the terminal.
-//!
-//! When exiting normally or when handling `Result::Err`, we can reset the
-//! terminal manually at the end of `main` just before we print the error.
-//!
-//! Because a panic interrupts the normal control flow, manually resetting the
-//! terminal at the end of `main` won't do us any good. Instead, we need to
-//! make sure to set up a panic hook that first resets the terminal before
-//! handling the panic. This both reuses the standard panic hook to ensure a
-//! consistent panic handling UX and properly resets the terminal to not
-//! distort the output.
-//!
-//! That's why this example is set up to show both situations, with and without
-//! the chained panic hook, to see the difference.
-
-use std::{error::Error, io};
-
-use crossterm::{
-    event::{self, Event, KeyCode},
-    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-};
-use ratatui::{prelude::*, widgets::*};
-
-type Result<T> = std::result::Result<T, Box<dyn Error>>;
-
-#[derive(Default)]
-struct App {
-    hook_enabled: bool,
-}
-
-impl App {
-    fn chain_hook(&mut self) {
-        let original_hook = std::panic::take_hook();
-
-        std::panic::set_hook(Box::new(move |panic| {
-            reset_terminal().unwrap();
-            original_hook(panic);
-        }));
-
-        self.hook_enabled = true;
-    }
-}
-
-fn main() -> Result<()> {
-    let mut terminal = init_terminal()?;
-
-    let mut app = App::default();
-    let res = run_tui(&mut terminal, &mut app);
-
-    reset_terminal()?;
-
-    if let Err(err) = res {
-        println!("{err:?}");
-    }
-
-    Ok(())
-}
-
-/// Initializes the terminal.
-fn init_terminal() -> Result<Terminal<CrosstermBackend<io::Stdout>>> {
-    crossterm::execute!(io::stdout(), EnterAlternateScreen)?;
-    enable_raw_mode()?;
-
-    let backend = CrosstermBackend::new(io::stdout());
-
-    let mut terminal = Terminal::new(backend)?;
-    terminal.hide_cursor()?;
-
-    Ok(terminal)
-}
-
-/// Resets the terminal.
-fn reset_terminal() -> Result<()> {
-    disable_raw_mode()?;
-    crossterm::execute!(io::stdout(), LeaveAlternateScreen)?;
-
-    Ok(())
-}
-
-/// Runs the TUI loop.
-fn run_tui<B: Backend>(terminal: &mut Terminal<B>, app: &mut App) -> io::Result<()> {
-    loop {
-        terminal.draw(|f| ui(f, app))?;
-
-        if let Event::Key(key) = event::read()? {
-            match key.code {
-                KeyCode::Char('p') => {
-                    panic!("intentional demo panic");
-                }
-
-                KeyCode::Char('e') => {
-                    app.chain_hook();
-                }
-
-                _ => {
-                    return Ok(());
-                }
-            }
-        }
-    }
-}
-
-/// Render the TUI.
-fn ui<B: Backend>(f: &mut Frame<B>, app: &App) {
-    let text = vec![
-        if app.hook_enabled {
-            Line::from("HOOK IS CURRENTLY **ENABLED**")
-        } else {
-            Line::from("HOOK IS CURRENTLY **DISABLED**")
-        },
-        Line::from(""),
-        Line::from("press `p` to panic"),
-        Line::from("press `e` to enable the terminal-resetting panic hook"),
-        Line::from("press any other key to quit without panic"),
-        Line::from(""),
-        Line::from("when you panic without the chained hook,"),
-        Line::from("you will likely have to reset your terminal afterwards"),
-        Line::from("with the `reset` command"),
-        Line::from(""),
-        Line::from("with the chained panic hook enabled,"),
-        Line::from("you should see the panic report as you would without ratatui"),
-        Line::from(""),
-        Line::from("try first without the panic handler to see the difference"),
-    ];
-
-    let b = Block::default()
-        .title("Panic Handler Demo")
-        .borders(Borders::ALL);
-
-    let p = Paragraph::new(text).block(b).alignment(Alignment::Center);
-
-    f.render_widget(p, f.size());
-}

examples/paragraph.rs

@@ -1,159 +0,0 @@
-use std::{
-    error::Error,
-    io,
-    time::{Duration, Instant},
-};
-
-use crossterm::{
-    event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode},
-    execute,
-    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-};
-use ratatui::{prelude::*, widgets::*};
-
-struct App {
-    scroll: u16,
-}
-
-impl App {
-    fn new() -> App {
-        App { scroll: 0 }
-    }
-
-    fn on_tick(&mut self) {
-        self.scroll += 1;
-        self.scroll %= 10;
-    }
-}
-
-fn main() -> Result<(), Box<dyn Error>> {
-    // setup terminal
-    enable_raw_mode()?;
-    let mut stdout = io::stdout();
-    execute!(stdout, EnterAlternateScreen, EnableMouseCapture)?;
-    let backend = CrosstermBackend::new(stdout);
-    let mut terminal = Terminal::new(backend)?;
-
-    // create app and run it
-    let tick_rate = Duration::from_millis(250);
-    let app = App::new();
-    let res = run_app(&mut terminal, app, tick_rate);
-
-    // restore terminal
-    disable_raw_mode()?;
-    execute!(
-        terminal.backend_mut(),
-        LeaveAlternateScreen,
-        DisableMouseCapture
-    )?;
-    terminal.show_cursor()?;
-
-    if let Err(err) = res {
-        println!("{err:?}");
-    }
-
-    Ok(())
-}
-
-fn run_app<B: Backend>(
-    terminal: &mut Terminal<B>,
-    mut app: App,
-    tick_rate: Duration,
-) -> io::Result<()> {
-    let mut last_tick = Instant::now();
-    loop {
-        terminal.draw(|f| ui(f, &app))?;
-
-        let timeout = tick_rate
-            .checked_sub(last_tick.elapsed())
-            .unwrap_or_else(|| Duration::from_secs(0));
-        if crossterm::event::poll(timeout)? {
-            if let Event::Key(key) = event::read()? {
-                if let KeyCode::Char('q') = key.code {
-                    return Ok(());
-                }
-            }
-        }
-        if last_tick.elapsed() >= tick_rate {
-            app.on_tick();
-            last_tick = Instant::now();
-        }
-    }
-}
-
-fn ui<B: Backend>(f: &mut Frame<B>, app: &App) {
-    let size = f.size();
-
-    // Words made "loooong" to demonstrate line breaking.
-    let s = "Veeeeeeeeeeeeeeeery    loooooooooooooooooong   striiiiiiiiiiiiiiiiiiiiiiiiiing.   ";
-    let mut long_line = s.repeat(usize::from(size.width) / s.len() + 4);
-    long_line.push('\n');
-
-    let block = Block::default().black();
-    f.render_widget(block, size);
-
-    let chunks = Layout::default()
-        .direction(Direction::Vertical)
-        .constraints(
-            [
-                Constraint::Percentage(25),
-                Constraint::Percentage(25),
-                Constraint::Percentage(25),
-                Constraint::Percentage(25),
-            ]
-            .as_ref(),
-        )
-        .split(size);
-
-    let text = vec![
-        Line::from("This is a line "),
-        Line::from("This is a line   ".red()),
-        Line::from("This is a line".on_blue()),
-        Line::from("This is a longer line".crossed_out()),
-        Line::from(long_line.on_green()),
-        Line::from("This is a line".green().italic()),
-        Line::from(vec![
-            "Masked text: ".into(),
-            Span::styled(
-                Masked::new("password", '*'),
-                Style::default().fg(Color::Red),
-            ),
-        ]),
-    ];
-
-    let create_block = |title| {
-        Block::default()
-            .borders(Borders::ALL)
-            .style(Style::default().fg(Color::Gray))
-            .title(Span::styled(
-                title,
-                Style::default().add_modifier(Modifier::BOLD),
-            ))
-    };
-
-    let paragraph = Paragraph::new(text.clone())
-        .style(Style::default().fg(Color::Gray))
-        .block(create_block("Default alignment (Left), no wrap"));
-    f.render_widget(paragraph, chunks[0]);
-
-    let paragraph = Paragraph::new(text.clone())
-        .style(Style::default().fg(Color::Gray))
-        .block(create_block("Default alignment (Left), with wrap"))
-        .wrap(Wrap { trim: true });
-    f.render_widget(paragraph, chunks[1]);
-
-    let paragraph = Paragraph::new(text.clone())
-        .style(Style::default().fg(Color::Gray))
-        .block(create_block("Right alignment, with wrap"))
-        .alignment(Alignment::Right)
-        .wrap(Wrap { trim: true });
-    f.render_widget(paragraph, chunks[2]);
-
-    let paragraph = Paragraph::new(text)
-        .style(Style::default().fg(Color::Gray))
-        .block(create_block("Center alignment, with wrap, with scroll"))
-        .alignment(Alignment::Center)
-        .wrap(Wrap { trim: true })
-        .scroll((app.scroll, 0));
-    f.render_widget(paragraph, chunks[3]);
-}

examples/popup.rs

@@ -1,120 +0,0 @@
-use std::{error::Error, io};
-
-use crossterm::{
-    event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode, KeyEventKind},
-    execute,
-    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-};
-use ratatui::{prelude::*, widgets::*};
-
-struct App {
-    show_popup: bool,
-}
-
-impl App {
-    fn new() -> App {
-        App { show_popup: false }
-    }
-}
-
-fn main() -> Result<(), Box<dyn Error>> {
-    // setup terminal
-    enable_raw_mode()?;
-    let mut stdout = io::stdout();
-    execute!(stdout, EnterAlternateScreen, EnableMouseCapture)?;
-    let backend = CrosstermBackend::new(stdout);
-    let mut terminal = Terminal::new(backend)?;
-
-    // create app and run it
-    let app = App::new();
-    let res = run_app(&mut terminal, app);
-
-    // restore terminal
-    disable_raw_mode()?;
-    execute!(
-        terminal.backend_mut(),
-        LeaveAlternateScreen,
-        DisableMouseCapture
-    )?;
-    terminal.show_cursor()?;
-
-    if let Err(err) = res {
-        println!("{err:?}");
-    }
-
-    Ok(())
-}
-
-fn run_app<B: Backend>(terminal: &mut Terminal<B>, mut app: App) -> io::Result<()> {
-    loop {
-        terminal.draw(|f| ui(f, &app))?;
-
-        if let Event::Key(key) = event::read()? {
-            if key.kind == KeyEventKind::Press {
-                match key.code {
-                    KeyCode::Char('q') => return Ok(()),
-                    KeyCode::Char('p') => app.show_popup = !app.show_popup,
-                    _ => {}
-                }
-            }
-        }
-    }
-}
-
-fn ui<B: Backend>(f: &mut Frame<B>, app: &App) {
-    let size = f.size();
-
-    let chunks = Layout::default()
-        .constraints([Constraint::Percentage(20), Constraint::Percentage(80)].as_ref())
-        .split(size);
-
-    let text = if app.show_popup {
-        "Press p to close the popup"
-    } else {
-        "Press p to show the popup"
-    };
-    let paragraph = Paragraph::new(text.slow_blink())
-        .alignment(Alignment::Center)
-        .wrap(Wrap { trim: true });
-    f.render_widget(paragraph, chunks[0]);
-
-    let block = Block::default()
-        .title("Content")
-        .borders(Borders::ALL)
-        .on_blue();
-    f.render_widget(block, chunks[1]);
-
-    if app.show_popup {
-        let block = Block::default().title("Popup").borders(Borders::ALL);
-        let area = centered_rect(60, 20, size);
-        f.render_widget(Clear, area); //this clears out the background
-        f.render_widget(block, area);
-    }
-}
-
-/// helper function to create a centered rect using up certain percentage of the available rect `r`
-fn centered_rect(percent_x: u16, percent_y: u16, r: Rect) -> Rect {
-    let popup_layout = Layout::default()
-        .direction(Direction::Vertical)
-        .constraints(
-            [
-                Constraint::Percentage((100 - percent_y) / 2),
-                Constraint::Percentage(percent_y),
-                Constraint::Percentage((100 - percent_y) / 2),
-            ]
-            .as_ref(),
-        )
-        .split(r);
-
-    Layout::default()
-        .direction(Direction::Horizontal)
-        .constraints(
-            [
-                Constraint::Percentage((100 - percent_x) / 2),
-                Constraint::Percentage(percent_x),
-                Constraint::Percentage((100 - percent_x) / 2),
-            ]
-            .as_ref(),
-        )
-        .split(popup_layout[1])[1]
-}

examples/scrollbar.rs

@@ -1,240 +0,0 @@
-use std::{
-    error::Error,
-    io,
-    time::{Duration, Instant},
-};
-
-use crossterm::{
-    event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode},
-    execute,
-    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-};
-use ratatui::{prelude::*, symbols::scrollbar, widgets::*};
-
-#[derive(Default)]
-struct App {
-    pub vertical_scroll_state: ScrollbarState,
-    pub horizontal_scroll_state: ScrollbarState,
-    pub vertical_scroll: usize,
-    pub horizontal_scroll: usize,
-}
-
-fn main() -> Result<(), Box<dyn Error>> {
-    // setup terminal
-    enable_raw_mode()?;
-    let mut stdout = io::stdout();
-    execute!(stdout, EnterAlternateScreen, EnableMouseCapture)?;
-    let backend = CrosstermBackend::new(stdout);
-    let mut terminal = Terminal::new(backend)?;
-
-    // create app and run it
-    let tick_rate = Duration::from_millis(250);
-    let app = App::default();
-    let res = run_app(&mut terminal, app, tick_rate);
-
-    // restore terminal
-    disable_raw_mode()?;
-    execute!(
-        terminal.backend_mut(),
-        LeaveAlternateScreen,
-        DisableMouseCapture
-    )?;
-    terminal.show_cursor()?;
-
-    if let Err(err) = res {
-        println!("{err:?}");
-    }
-
-    Ok(())
-}
-
-fn run_app<B: Backend>(
-    terminal: &mut Terminal<B>,
-    mut app: App,
-    tick_rate: Duration,
-) -> io::Result<()> {
-    let mut last_tick = Instant::now();
-    loop {
-        terminal.draw(|f| ui(f, &mut app))?;
-
-        let timeout = tick_rate
-            .checked_sub(last_tick.elapsed())
-            .unwrap_or_else(|| Duration::from_secs(0));
-        if crossterm::event::poll(timeout)? {
-            if let Event::Key(key) = event::read()? {
-                match key.code {
-                    KeyCode::Char('q') => return Ok(()),
-                    KeyCode::Char('j') => {
-                        app.vertical_scroll = app.vertical_scroll.saturating_add(1);
-                        app.vertical_scroll_state =
-                            app.vertical_scroll_state.position(app.vertical_scroll);
-                    }
-                    KeyCode::Char('k') => {
-                        app.vertical_scroll = app.vertical_scroll.saturating_sub(1);
-                        app.vertical_scroll_state =
-                            app.vertical_scroll_state.position(app.vertical_scroll);
-                    }
-                    KeyCode::Char('h') => {
-                        app.horizontal_scroll = app.horizontal_scroll.saturating_sub(1);
-                        app.horizontal_scroll_state =
-                            app.horizontal_scroll_state.position(app.horizontal_scroll);
-                    }
-                    KeyCode::Char('l') => {
-                        app.horizontal_scroll = app.horizontal_scroll.saturating_add(1);
-                        app.horizontal_scroll_state =
-                            app.horizontal_scroll_state.position(app.horizontal_scroll);
-                    }
-                    _ => {}
-                }
-            }
-        }
-        if last_tick.elapsed() >= tick_rate {
-            last_tick = Instant::now();
-        }
-    }
-}
-
-fn ui<B: Backend>(f: &mut Frame<B>, app: &mut App) {
-    let size = f.size();
-
-    // Words made "loooong" to demonstrate line breaking.
-    let s = "Veeeeeeeeeeeeeeeery    loooooooooooooooooong   striiiiiiiiiiiiiiiiiiiiiiiiiing.   ";
-    let mut long_line = s.repeat(usize::from(size.width) / s.len() + 4);
-    long_line.push('\n');
-
-    let block = Block::default().black();
-    f.render_widget(block, size);
-
-    let chunks = Layout::default()
-        .direction(Direction::Vertical)
-        .constraints(
-            [
-                Constraint::Min(1),
-                Constraint::Percentage(25),
-                Constraint::Percentage(25),
-                Constraint::Percentage(25),
-                Constraint::Percentage(25),
-            ]
-            .as_ref(),
-        )
-        .split(size);
-
-    let text = vec![
-        Line::from("This is a line "),
-        Line::from("This is a line   ".red()),
-        Line::from("This is a line".on_dark_gray()),
-        Line::from("This is a longer line".crossed_out()),
-        Line::from(long_line.clone()),
-        Line::from("This is a line".reset()),
-        Line::from(vec![
-            Span::raw("Masked text: "),
-            Span::styled(
-                Masked::new("password", '*'),
-                Style::default().fg(Color::Red),
-            ),
-        ]),
-        Line::from("This is a line "),
-        Line::from("This is a line   ".red()),
-        Line::from("This is a line".on_dark_gray()),
-        Line::from("This is a longer line".crossed_out()),
-        Line::from(long_line.clone()),
-        Line::from("This is a line".reset()),
-        Line::from(vec![
-            Span::raw("Masked text: "),
-            Span::styled(
-                Masked::new("password", '*'),
-                Style::default().fg(Color::Red),
-            ),
-        ]),
-    ];
-    app.vertical_scroll_state = app.vertical_scroll_state.content_length(text.len());
-    app.horizontal_scroll_state = app.horizontal_scroll_state.content_length(long_line.len());
-
-    let create_block = |title| {
-        Block::default()
-            .borders(Borders::ALL)
-            .gray()
-            .title(Span::styled(
-                title,
-                Style::default().add_modifier(Modifier::BOLD),
-            ))
-    };
-
-    let title = Block::default()
-        .title("Use h j k l to scroll ◄ ▲ ▼ ►")
-        .title_alignment(Alignment::Center);
-    f.render_widget(title, chunks[0]);
-
-    let paragraph = Paragraph::new(text.clone())
-        .gray()
-        .block(create_block("Vertical scrollbar with arrows"))
-        .scroll((app.vertical_scroll as u16, 0));
-    f.render_widget(paragraph, chunks[1]);
-    f.render_stateful_widget(
-        Scrollbar::default()
-            .orientation(ScrollbarOrientation::VerticalRight)
-            .begin_symbol(Some("↑"))
-            .end_symbol(Some("↓")),
-        chunks[1],
-        &mut app.vertical_scroll_state,
-    );
-
-    let paragraph = Paragraph::new(text.clone())
-        .gray()
-        .block(create_block(
-            "Vertical scrollbar without arrows, without track symbol and mirrored",
-        ))
-        .scroll((app.vertical_scroll as u16, 0));
-    f.render_widget(paragraph, chunks[2]);
-    f.render_stateful_widget(
-        Scrollbar::default()
-            .orientation(ScrollbarOrientation::VerticalLeft)
-            .symbols(scrollbar::VERTICAL)
-            .begin_symbol(None)
-            .track_symbol(None)
-            .end_symbol(None),
-        chunks[2].inner(&Margin {
-            vertical: 1,
-            horizontal: 0,
-        }),
-        &mut app.vertical_scroll_state,
-    );
-
-    let paragraph = Paragraph::new(text.clone())
-        .gray()
-        .block(create_block(
-            "Horizontal scrollbar with only begin arrow & custom thumb symbol",
-        ))
-        .scroll((0, app.horizontal_scroll as u16));
-    f.render_widget(paragraph, chunks[3]);
-    f.render_stateful_widget(
-        Scrollbar::default()
-            .orientation(ScrollbarOrientation::HorizontalBottom)
-            .thumb_symbol("🬋")
-            .end_symbol(None),
-        chunks[3].inner(&Margin {
-            vertical: 0,
-            horizontal: 1,
-        }),
-        &mut app.horizontal_scroll_state,
-    );
-
-    let paragraph = Paragraph::new(text.clone())
-        .gray()
-        .block(create_block(
-            "Horizontal scrollbar without arrows & custom thumb and track symbol",
-        ))
-        .scroll((0, app.horizontal_scroll as u16));
-    f.render_widget(paragraph, chunks[4]);
-    f.render_stateful_widget(
-        Scrollbar::default()
-            .orientation(ScrollbarOrientation::HorizontalBottom)
-            .thumb_symbol("░")
-            .track_symbol(Some("─")),
-        chunks[4].inner(&Margin {
-            vertical: 0,
-            horizontal: 1,
-        }),
-        &mut app.horizontal_scroll_state,
-    );
-}

examples/sparkline.rs

@@ -1,169 +0,0 @@
-use std::{
-    error::Error,
-    io,
-    time::{Duration, Instant},
-};
-
-use crossterm::{
-    event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode},
-    execute,
-    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-};
-use rand::{
-    distributions::{Distribution, Uniform},
-    rngs::ThreadRng,
-};
-use ratatui::{prelude::*, widgets::*};
-
-#[derive(Clone)]
-pub struct RandomSignal {
-    distribution: Uniform<u64>,
-    rng: ThreadRng,
-}
-
-impl RandomSignal {
-    pub fn new(lower: u64, upper: u64) -> RandomSignal {
-        RandomSignal {
-            distribution: Uniform::new(lower, upper),
-            rng: rand::thread_rng(),
-        }
-    }
-}
-
-impl Iterator for RandomSignal {
-    type Item = u64;
-    fn next(&mut self) -> Option<u64> {
-        Some(self.distribution.sample(&mut self.rng))
-    }
-}
-
-struct App {
-    signal: RandomSignal,
-    data1: Vec<u64>,
-    data2: Vec<u64>,
-    data3: Vec<u64>,
-}
-
-impl App {
-    fn new() -> App {
-        let mut signal = RandomSignal::new(0, 100);
-        let data1 = signal.by_ref().take(200).collect::<Vec<u64>>();
-        let data2 = signal.by_ref().take(200).collect::<Vec<u64>>();
-        let data3 = signal.by_ref().take(200).collect::<Vec<u64>>();
-        App {
-            signal,
-            data1,
-            data2,
-            data3,
-        }
-    }
-
-    fn on_tick(&mut self) {
-        let value = self.signal.next().unwrap();
-        self.data1.pop();
-        self.data1.insert(0, value);
-        let value = self.signal.next().unwrap();
-        self.data2.pop();
-        self.data2.insert(0, value);
-        let value = self.signal.next().unwrap();
-        self.data3.pop();
-        self.data3.insert(0, value);
-    }
-}
-
-fn main() -> Result<(), Box<dyn Error>> {
-    // setup terminal
-    enable_raw_mode()?;
-    let mut stdout = io::stdout();
-    execute!(stdout, EnterAlternateScreen, EnableMouseCapture)?;
-    let backend = CrosstermBackend::new(stdout);
-    let mut terminal = Terminal::new(backend)?;
-
-    // create app and run it
-    let tick_rate = Duration::from_millis(250);
-    let app = App::new();
-    let res = run_app(&mut terminal, app, tick_rate);
-
-    // restore terminal
-    disable_raw_mode()?;
-    execute!(
-        terminal.backend_mut(),
-        LeaveAlternateScreen,
-        DisableMouseCapture
-    )?;
-    terminal.show_cursor()?;
-
-    if let Err(err) = res {
-        println!("{err:?}");
-    }
-
-    Ok(())
-}
-
-fn run_app<B: Backend>(
-    terminal: &mut Terminal<B>,
-    mut app: App,
-    tick_rate: Duration,
-) -> io::Result<()> {
-    let mut last_tick = Instant::now();
-    loop {
-        terminal.draw(|f| ui(f, &app))?;
-
-        let timeout = tick_rate
-            .checked_sub(last_tick.elapsed())
-            .unwrap_or_else(|| Duration::from_secs(0));
-        if crossterm::event::poll(timeout)? {
-            if let Event::Key(key) = event::read()? {
-                if let KeyCode::Char('q') = key.code {
-                    return Ok(());
-                }
-            }
-        }
-        if last_tick.elapsed() >= tick_rate {
-            app.on_tick();
-            last_tick = Instant::now();
-        }
-    }
-}
-
-fn ui<B: Backend>(f: &mut Frame<B>, app: &App) {
-    let chunks = Layout::default()
-        .direction(Direction::Vertical)
-        .constraints(
-            [
-                Constraint::Length(3),
-                Constraint::Length(3),
-                Constraint::Min(0),
-            ]
-            .as_ref(),
-        )
-        .split(f.size());
-    let sparkline = Sparkline::default()
-        .block(
-            Block::default()
-                .title("Data1")
-                .borders(Borders::LEFT | Borders::RIGHT),
-        )
-        .data(&app.data1)
-        .style(Style::default().fg(Color::Yellow));
-    f.render_widget(sparkline, chunks[0]);
-    let sparkline = Sparkline::default()
-        .block(
-            Block::default()
-                .title("Data2")
-                .borders(Borders::LEFT | Borders::RIGHT),
-        )
-        .data(&app.data2)
-        .style(Style::default().bg(Color::Green));
-    f.render_widget(sparkline, chunks[1]);
-    // Multiline
-    let sparkline = Sparkline::default()
-        .block(
-            Block::default()
-                .title("Data3")
-                .borders(Borders::LEFT | Borders::RIGHT),
-        )
-        .data(&app.data3)
-        .style(Style::default().fg(Color::Red));
-    f.render_widget(sparkline, chunks[2]);
-}

examples/table.rs

@@ -1,151 +0,0 @@
-use std::{error::Error, io};
-
-use crossterm::{
-    event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode, KeyEventKind},
-    execute,
-    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-};
-use ratatui::{prelude::*, widgets::*};
-
-struct App<'a> {
-    state: TableState,
-    items: Vec<Vec<&'a str>>,
-}
-
-impl<'a> App<'a> {
-    fn new() -> App<'a> {
-        App {
-            state: TableState::default(),
-            items: vec![
-                vec!["Row11", "Row12", "Row13"],
-                vec!["Row21", "Row22", "Row23"],
-                vec!["Row31", "Row32", "Row33"],
-                vec!["Row41", "Row42", "Row43"],
-                vec!["Row51", "Row52", "Row53"],
-                vec!["Row61", "Row62\nTest", "Row63"],
-                vec!["Row71", "Row72", "Row73"],
-                vec!["Row81", "Row82", "Row83"],
-                vec!["Row91", "Row92", "Row93"],
-                vec!["Row101", "Row102", "Row103"],
-                vec!["Row111", "Row112", "Row113"],
-                vec!["Row121", "Row122", "Row123"],
-                vec!["Row131", "Row132", "Row133"],
-                vec!["Row141", "Row142", "Row143"],
-                vec!["Row151", "Row152", "Row153"],
-                vec!["Row161", "Row162", "Row163"],
-                vec!["Row171", "Row172", "Row173"],
-                vec!["Row181", "Row182", "Row183"],
-                vec!["Row191", "Row192", "Row193"],
-            ],
-        }
-    }
-    pub fn next(&mut self) {
-        let i = match self.state.selected() {
-            Some(i) => {
-                if i >= self.items.len() - 1 {
-                    0
-                } else {
-                    i + 1
-                }
-            }
-            None => 0,
-        };
-        self.state.select(Some(i));
-    }
-
-    pub fn previous(&mut self) {
-        let i = match self.state.selected() {
-            Some(i) => {
-                if i == 0 {
-                    self.items.len() - 1
-                } else {
-                    i - 1
-                }
-            }
-            None => 0,
-        };
-        self.state.select(Some(i));
-    }
-}
-
-fn main() -> Result<(), Box<dyn Error>> {
-    // setup terminal
-    enable_raw_mode()?;
-    let mut stdout = io::stdout();
-    execute!(stdout, EnterAlternateScreen, EnableMouseCapture)?;
-    let backend = CrosstermBackend::new(stdout);
-    let mut terminal = Terminal::new(backend)?;
-
-    // create app and run it
-    let app = App::new();
-    let res = run_app(&mut terminal, app);
-
-    // restore terminal
-    disable_raw_mode()?;
-    execute!(
-        terminal.backend_mut(),
-        LeaveAlternateScreen,
-        DisableMouseCapture
-    )?;
-    terminal.show_cursor()?;
-
-    if let Err(err) = res {
-        println!("{err:?}");
-    }
-
-    Ok(())
-}
-
-fn run_app<B: Backend>(terminal: &mut Terminal<B>, mut app: App) -> io::Result<()> {
-    loop {
-        terminal.draw(|f| ui(f, &mut app))?;
-
-        if let Event::Key(key) = event::read()? {
-            if key.kind == KeyEventKind::Press {
-                match key.code {
-                    KeyCode::Char('q') => return Ok(()),
-                    KeyCode::Down => app.next(),
-                    KeyCode::Up => app.previous(),
-                    _ => {}
-                }
-            }
-        }
-    }
-}
-
-fn ui<B: Backend>(f: &mut Frame<B>, app: &mut App) {
-    let rects = Layout::default()
-        .constraints([Constraint::Percentage(100)].as_ref())
-        .split(f.size());
-
-    let selected_style = Style::default().add_modifier(Modifier::REVERSED);
-    let normal_style = Style::default().bg(Color::Blue);
-    let header_cells = ["Header1", "Header2", "Header3"]
-        .iter()
-        .map(|h| Cell::from(*h).style(Style::default().fg(Color::Red)));
-    let header = Row::new(header_cells)
-        .style(normal_style)
-        .height(1)
-        .bottom_margin(1);
-    let rows = app.items.iter().map(|item| {
-        let height = item
-            .iter()
-            .map(|content| content.chars().filter(|c| *c == '\n').count())
-            .max()
-            .unwrap_or(0)
-            + 1;
-        let cells = item.iter().map(|c| Cell::from(*c));
-        Row::new(cells).height(height as u16).bottom_margin(1)
-    });
-    let t = Table::new(rows)
-        .header(header)
-        .block(Block::default().borders(Borders::ALL).title("Table"))
-        .highlight_style(selected_style)
-        .highlight_symbol(">> ")
-        .widths(&[
-            Constraint::Percentage(50),
-            Constraint::Max(30),
-            Constraint::Min(10),
-        ]);
-    f.render_stateful_widget(t, rects[0], &mut app.state);
-}

examples/tabs.rs

@@ -1,116 +0,0 @@
-use std::{error::Error, io};
-
-use crossterm::{
-    event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode, KeyEventKind},
-    execute,
-    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-};
-use ratatui::{prelude::*, widgets::*};
-
-struct App<'a> {
-    pub titles: Vec<&'a str>,
-    pub index: usize,
-}
-
-impl<'a> App<'a> {
-    fn new() -> App<'a> {
-        App {
-            titles: vec!["Tab0", "Tab1", "Tab2", "Tab3"],
-            index: 0,
-        }
-    }
-
-    pub fn next(&mut self) {
-        self.index = (self.index + 1) % self.titles.len();
-    }
-
-    pub fn previous(&mut self) {
-        if self.index > 0 {
-            self.index -= 1;
-        } else {
-            self.index = self.titles.len() - 1;
-        }
-    }
-}
-
-fn main() -> Result<(), Box<dyn Error>> {
-    // setup terminal
-    enable_raw_mode()?;
-    let mut stdout = io::stdout();
-    execute!(stdout, EnterAlternateScreen, EnableMouseCapture)?;
-    let backend = CrosstermBackend::new(stdout);
-    let mut terminal = Terminal::new(backend)?;
-
-    // create app and run it
-    let app = App::new();
-    let res = run_app(&mut terminal, app);
-
-    // restore terminal
-    disable_raw_mode()?;
-    execute!(
-        terminal.backend_mut(),
-        LeaveAlternateScreen,
-        DisableMouseCapture
-    )?;
-    terminal.show_cursor()?;
-
-    if let Err(err) = res {
-        println!("{err:?}");
-    }
-
-    Ok(())
-}
-
-fn run_app<B: Backend>(terminal: &mut Terminal<B>, mut app: App) -> io::Result<()> {
-    loop {
-        terminal.draw(|f| ui(f, &app))?;
-
-        if let Event::Key(key) = event::read()? {
-            if key.kind == KeyEventKind::Press {
-                match key.code {
-                    KeyCode::Char('q') => return Ok(()),
-                    KeyCode::Right => app.next(),
-                    KeyCode::Left => app.previous(),
-                    _ => {}
-                }
-            }
-        }
-    }
-}
-
-fn ui<B: Backend>(f: &mut Frame<B>, app: &App) {
-    let size = f.size();
-    let chunks = Layout::default()
-        .direction(Direction::Vertical)
-        .constraints([Constraint::Length(3), Constraint::Min(0)].as_ref())
-        .split(size);
-
-    let block = Block::default().on_white().black();
-    f.render_widget(block, size);
-    let titles = app
-        .titles
-        .iter()
-        .map(|t| {
-            let (first, rest) = t.split_at(1);
-            Line::from(vec![first.yellow(), rest.green()])
-        })
-        .collect();
-    let tabs = Tabs::new(titles)
-        .block(Block::default().borders(Borders::ALL).title("Tabs"))
-        .select(app.index)
-        .style(Style::default().fg(Color::Cyan))
-        .highlight_style(
-            Style::default()
-                .add_modifier(Modifier::BOLD)
-                .bg(Color::Black),
-        );
-    f.render_widget(tabs, chunks[0]);
-    let inner = match app.index {
-        0 => Block::default().title("Inner 0").borders(Borders::ALL),
-        1 => Block::default().title("Inner 1").borders(Borders::ALL),
-        2 => Block::default().title("Inner 2").borders(Borders::ALL),
-        3 => Block::default().title("Inner 3").borders(Borders::ALL),
-        _ => unreachable!(),
-    };
-    f.render_widget(inner, chunks[1]);
-}

examples/user_input.rs

@@ -1,251 +0,0 @@
-use std::{error::Error, io};
-
-/// A simple example demonstrating how to handle user input. This is
-/// a bit out of the scope of the library as it does not provide any
-/// input handling out of the box. However, it may helps some to get
-/// started.
-///
-/// This is a very simple example:
-///   * An input box always focused. Every character you type is registered
-///   here.
-///   * An entered character is inserted at the cursor position.
-///   * Pressing Backspace erases the left character before the cursor position
-///   * Pressing Enter pushes the current input in the history of previous
-///   messages.
-/// **Note: ** as this is a relatively simple example unicode characters are unsupported and
-/// their use will result in undefined behaviour.
-use crossterm::{
-    event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode, KeyEventKind},
-    execute,
-    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-};
-use ratatui::{prelude::*, widgets::*};
-
-enum InputMode {
-    Normal,
-    Editing,
-}
-
-/// App holds the state of the application
-struct App {
-    /// Current value of the input box
-    input: String,
-    /// Position of cursor in the editor area.
-    cursor_position: usize,
-    /// Current input mode
-    input_mode: InputMode,
-    /// History of recorded messages
-    messages: Vec<String>,
-}
-
-impl Default for App {
-    fn default() -> App {
-        App {
-            input: String::new(),
-            input_mode: InputMode::Normal,
-            messages: Vec::new(),
-            cursor_position: 0,
-        }
-    }
-}
-
-impl App {
-    fn move_cursor_left(&mut self) {
-        let cursor_moved_left = self.cursor_position.saturating_sub(1);
-        self.cursor_position = self.clamp_cursor(cursor_moved_left);
-    }
-
-    fn move_cursor_right(&mut self) {
-        let cursor_moved_right = self.cursor_position.saturating_add(1);
-        self.cursor_position = self.clamp_cursor(cursor_moved_right);
-    }
-
-    fn enter_char(&mut self, new_char: char) {
-        self.input.insert(self.cursor_position, new_char);
-
-        self.move_cursor_right();
-    }
-
-    fn delete_char(&mut self) {
-        let is_not_cursor_leftmost = self.cursor_position != 0;
-        if is_not_cursor_leftmost {
-            // Method "remove" is not used on the saved text for deleting the selected char.
-            // Reason: Using remove on String works on bytes instead of the chars.
-            // Using remove would require special care because of char boundaries.
-
-            let current_index = self.cursor_position;
-            let from_left_to_current_index = current_index - 1;
-
-            // Getting all characters before the selected character.
-            let before_char_to_delete = self.input.chars().take(from_left_to_current_index);
-            // Getting all characters after selected character.
-            let after_char_to_delete = self.input.chars().skip(current_index);
-
-            // Put all characters together except the selected one.
-            // By leaving the selected one out, it is forgotten and therefore deleted.
-            self.input = before_char_to_delete.chain(after_char_to_delete).collect();
-            self.move_cursor_left();
-        }
-    }
-
-    fn clamp_cursor(&self, new_cursor_pos: usize) -> usize {
-        new_cursor_pos.clamp(0, self.input.len())
-    }
-
-    fn reset_cursor(&mut self) {
-        self.cursor_position = 0;
-    }
-
-    fn submit_message(&mut self) {
-        self.messages.push(self.input.clone());
-        self.input.clear();
-        self.reset_cursor();
-    }
-}
-
-fn main() -> Result<(), Box<dyn Error>> {
-    // setup terminal
-    enable_raw_mode()?;
-    let mut stdout = io::stdout();
-    execute!(stdout, EnterAlternateScreen, EnableMouseCapture)?;
-    let backend = CrosstermBackend::new(stdout);
-    let mut terminal = Terminal::new(backend)?;
-
-    // create app and run it
-    let app = App::default();
-    let res = run_app(&mut terminal, app);
-
-    // restore terminal
-    disable_raw_mode()?;
-    execute!(
-        terminal.backend_mut(),
-        LeaveAlternateScreen,
-        DisableMouseCapture
-    )?;
-    terminal.show_cursor()?;
-
-    if let Err(err) = res {
-        println!("{err:?}");
-    }
-
-    Ok(())
-}
-
-fn run_app<B: Backend>(terminal: &mut Terminal<B>, mut app: App) -> io::Result<()> {
-    loop {
-        terminal.draw(|f| ui(f, &app))?;
-
-        if let Event::Key(key) = event::read()? {
-            match app.input_mode {
-                InputMode::Normal => match key.code {
-                    KeyCode::Char('e') => {
-                        app.input_mode = InputMode::Editing;
-                    }
-                    KeyCode::Char('q') => {
-                        return Ok(());
-                    }
-                    _ => {}
-                },
-                InputMode::Editing if key.kind == KeyEventKind::Press => match key.code {
-                    KeyCode::Enter => app.submit_message(),
-                    KeyCode::Char(to_insert) => {
-                        app.enter_char(to_insert);
-                    }
-                    KeyCode::Backspace => {
-                        app.delete_char();
-                    }
-                    KeyCode::Left => {
-                        app.move_cursor_left();
-                    }
-                    KeyCode::Right => {
-                        app.move_cursor_right();
-                    }
-                    KeyCode::Esc => {
-                        app.input_mode = InputMode::Normal;
-                    }
-                    _ => {}
-                },
-                _ => {}
-            }
-        }
-    }
-}
-
-fn ui<B: Backend>(f: &mut Frame<B>, app: &App) {
-    let chunks = Layout::default()
-        .direction(Direction::Vertical)
-        .constraints(
-            [
-                Constraint::Length(1),
-                Constraint::Length(3),
-                Constraint::Min(1),
-            ]
-            .as_ref(),
-        )
-        .split(f.size());
-
-    let (msg, style) = match app.input_mode {
-        InputMode::Normal => (
-            vec![
-                "Press ".into(),
-                "q".bold(),
-                " to exit, ".into(),
-                "e".bold(),
-                " to start editing.".bold(),
-            ],
-            Style::default().add_modifier(Modifier::RAPID_BLINK),
-        ),
-        InputMode::Editing => (
-            vec![
-                "Press ".into(),
-                "Esc".bold(),
-                " to stop editing, ".into(),
-                "Enter".bold(),
-                " to record the message".into(),
-            ],
-            Style::default(),
-        ),
-    };
-    let mut text = Text::from(Line::from(msg));
-    text.patch_style(style);
-    let help_message = Paragraph::new(text);
-    f.render_widget(help_message, chunks[0]);
-
-    let input = Paragraph::new(app.input.as_str())
-        .style(match app.input_mode {
-            InputMode::Normal => Style::default(),
-            InputMode::Editing => Style::default().fg(Color::Yellow),
-        })
-        .block(Block::default().borders(Borders::ALL).title("Input"));
-    f.render_widget(input, chunks[1]);
-    match app.input_mode {
-        InputMode::Normal =>
-            // Hide the cursor. `Frame` does this by default, so we don't need to do anything here
-            {}
-
-        InputMode::Editing => {
-            // Make the cursor visible and ask ratatui to put it at the specified coordinates after
-            // rendering
-            f.set_cursor(
-                // Draw the cursor at the current position in the input field.
-                // This position is can be controlled via the left and right arrow key
-                chunks[1].x + app.cursor_position as u16 + 1,
-                // Move one line down, from the border to the input line
-                chunks[1].y + 1,
-            )
-        }
-    }
-
-    let messages: Vec<ListItem> = app
-        .messages
-        .iter()
-        .enumerate()
-        .map(|(i, m)| {
-            let content = Line::from(Span::raw(format!("{i}: {m}")));
-            ListItem::new(content)
-        })
-        .collect();
-    let messages =
-        List::new(messages).block(Block::default().borders(Borders::ALL).title("Messages"));
-    f.render_widget(messages, chunks[2]);
-}

ratatui-core/Cargo.toml

@@ -0,0 +1,70 @@
+[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 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]
+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
+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.clippy]
+# we often split up a module into multiple files with the main type in a file named after the
+# module, so we want to allow this pattern
+module_inception = "allow"

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

@@ -11,7 +11,7 @@
 //!
 //! Additionally, a [`TestBackend`] is provided for testing purposes.
 //!
-//! See the [Backend Comparison] section of the [Ratatui Book] for more details on the different
+//! See the [Backend Comparison] section of the [Ratatui Website] for more details on the different
 //! backends.
 //!
 //! Each backend supports a number of features, such as [raw mode](#raw-mode), [alternate
@@ -26,7 +26,8 @@
 //!
 //! ```rust,no_run
 //! use std::io::stdout;
-//! use ratatui::prelude::*;
+//!
+//! use ratatui::{backend::CrosstermBackend, Terminal};
 //!
 //! let backend = CrosstermBackend::new(stdout());
 //! let mut terminal = Terminal::new(backend)?;
@@ -37,7 +38,7 @@
 //! # std::io::Result::Ok(())
 //! ```
 //!
-//! See the the [examples] directory for more examples.
+//! See the the [Examples] directory for more examples.
 //!
 //! # Raw Mode
 //!
@@ -55,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
@@ -89,36 +90,24 @@
 //! backend being used, and developers should consult the specific backend's documentation to
 //! understand how it implements mouse capture.
 //!
-//! [`TermionBackend`]: termion/struct.TermionBackend.html
-//! [`Terminal`]: crate::terminal::Terminal
-//! [`TermionBackend`]: termion/struct.TermionBackend.html
+//! [`CrosstermBackend`]: https://docs.rs/ratatui/latest/ratatui/backend/struct.CrosstermBackend.html
+//! [`TermionBackend`]: https://docs.rs/ratatui/latest/ratatui/backend/struct.TermionBackend.html
+//! [`TermwizBackend`]: https://docs.rs/ratatui/latest/ratatui/backend/struct.TermwizBackend.html
+//! [`Terminal`]: https://docs.rs/ratatui/latest/ratatui/struct.Terminal.html
 //! [Crossterm]: https://crates.io/crates/crossterm
 //! [Termion]: https://crates.io/crates/termion
 //! [Termwiz]: https://crates.io/crates/termwiz
-//! [examples]: https://github.com/ratatui-org/ratatui/tree/main/examples#readme
-//! [Backend Comparison]:
-//!     https://ratatui-org.github.io/ratatui-book/concepts/backends/comparison.html
-//! [Ratatui Book]: https://ratatui-org.github.io/ratatui-book
+//! [Examples]: https://github.com/ratatui/ratatui/tree/main/ratatui/examples/README.md
+//! [Backend Comparison]: https://ratatui.rs/concepts/backends/comparison/
+//! [Ratatui Website]: https://ratatui.rs
 use std::io;
 
 use strum::{Display, EnumString};
 
-use crate::{buffer::Cell, layout::Size, prelude::Rect};
-
-#[cfg(feature = "termion")]
-mod termion;
-#[cfg(feature = "termion")]
-pub use self::termion::TermionBackend;
-
-#[cfg(feature = "crossterm")]
-mod crossterm;
-#[cfg(feature = "crossterm")]
-pub use self::crossterm::CrosstermBackend;
-
-#[cfg(feature = "termwiz")]
-mod termwiz;
-#[cfg(feature = "termwiz")]
-pub use self::termwiz::TermwizBackend;
+use crate::{
+    buffer::Cell,
+    layout::{Position, Size},
+};
 
 mod test;
 pub use self::test::TestBackend;
@@ -140,6 +129,7 @@ pub enum ClearType {
 }
 
 /// The window size in characters (columns / rows) as well as pixels.
+#[derive(Debug, Clone, Copy, Eq, PartialEq, Hash)]
 pub struct WindowSize {
     /// Size of the window in characters (columns / rows).
     pub columns_rows: Size,
@@ -157,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.
     ///
@@ -182,33 +172,35 @@ pub trait Backend {
     /// # Example
     ///
     /// ```rust
-    /// # use ratatui::backend::{Backend, TestBackend};
+    /// # use ratatui::backend::{TestBackend};
     /// # let mut backend = TestBackend::new(80, 25);
+    /// use ratatui::backend::Backend;
+    ///
     /// backend.hide_cursor()?;
     /// // do something with hidden cursor
     /// backend.show_cursor()?;
     /// # std::io::Result::Ok(())
     /// ```
     ///
-    /// [`show_cursor`]: Backend::show_cursor
+    /// [`show_cursor`]: Self::show_cursor
     fn hide_cursor(&mut self) -> io::Result<()>;
 
     /// Show the cursor on the terminal screen.
     ///
     /// See [`hide_cursor`] for an example.
     ///
-    /// [`hide_cursor`]: Backend::hide_cursor
+    /// [`hide_cursor`]: Self::hide_cursor
     fn show_cursor(&mut self) -> io::Result<()>;
 
     /// Get the current cursor position on the terminal screen.
     ///
-    /// The returned tuple contains the x and y coordinates of the cursor. The origin
-    /// (0, 0) is at the top left corner of the screen.
+    /// The returned tuple contains the x and y coordinates of the cursor.
+    /// The origin (0, 0) is at the top left corner of the screen.
     ///
-    /// See [`set_cursor`] for an example.
+    /// See [`set_cursor_position`] for an example.
     ///
-    /// [`set_cursor`]: Backend::set_cursor
-    fn get_cursor(&mut self) -> io::Result<(u16, u16)>;
+    /// [`set_cursor_position`]: Self::set_cursor_position
+    fn get_cursor_position(&mut self) -> io::Result<Position>;
 
     /// Set the cursor position on the terminal screen to the given x and y coordinates.
     ///
@@ -217,23 +209,43 @@ pub trait Backend {
     /// # Example
     ///
     /// ```rust
-    /// # use ratatui::backend::{Backend, TestBackend};
+    /// # use ratatui::backend::{TestBackend};
     /// # let mut backend = TestBackend::new(80, 25);
-    /// backend.set_cursor(10, 20)?;
-    /// assert_eq!(backend.get_cursor()?, (10, 20));
+    /// use ratatui::{backend::Backend, layout::Position};
+    ///
+    /// backend.set_cursor_position(Position { x: 10, y: 20 })?;
+    /// assert_eq!(backend.get_cursor_position()?, Position { x: 10, y: 20 });
     /// # std::io::Result::Ok(())
     /// ```
-    ///
-    /// [`get_cursor`]: Backend::get_cursor
-    fn set_cursor(&mut self, x: u16, y: u16) -> io::Result<()>;
+    fn set_cursor_position<P: Into<Position>>(&mut self, position: P) -> io::Result<()>;
 
-    /// Clears the whole terminal scree
+    /// Get the current cursor position on the terminal screen.
+    ///
+    /// The returned tuple contains the x and y coordinates of the cursor. The origin
+    /// (0, 0) is at the top left corner of the screen.
+    #[deprecated = "the method get_cursor_position indicates more clearly what about the cursor to get"]
+    fn get_cursor(&mut self) -> io::Result<(u16, u16)> {
+        let Position { x, y } = self.get_cursor_position()?;
+        Ok((x, y))
+    }
+
+    /// Set the cursor position on the terminal screen to the given x and y coordinates.
+    ///
+    /// The origin (0, 0) is at the top left corner of the screen.
+    #[deprecated = "the method set_cursor_position indicates more clearly what about the cursor to set"]
+    fn set_cursor(&mut self, x: u16, y: u16) -> io::Result<()> {
+        self.set_cursor_position(Position { x, y })
+    }
+
+    /// Clears the whole terminal screen
     ///
     /// # Example
     ///
     /// ```rust,no_run
-    /// # use ratatui::backend::{Backend, TestBackend};
+    /// # use ratatui::backend::{TestBackend};
     /// # let mut backend = TestBackend::new(80, 25);
+    /// use ratatui::backend::Backend;
+    ///
     /// backend.clear()?;
     /// # std::io::Result::Ok(())
     /// ```
@@ -248,8 +260,10 @@ pub trait Backend {
     /// # Example
     ///
     /// ```rust,no_run
-    /// # use ratatui::{prelude::*, backend::{TestBackend, ClearType}};
+    /// # use ratatui::{backend::{TestBackend}};
     /// # let mut backend = TestBackend::new(80, 25);
+    /// use ratatui::backend::{Backend, ClearType};
+    ///
     /// backend.clear_region(ClearType::All)?;
     /// # std::io::Result::Ok(())
     /// ```
@@ -259,7 +273,7 @@ pub trait Backend {
     /// This method will return an error if the terminal screen could not be cleared. It will also
     /// return an error if the `clear_type` is not supported by the backend.
     ///
-    /// [`clear`]: Backend::clear
+    /// [`clear`]: Self::clear
     fn clear_region(&mut self, clear_type: ClearType) -> io::Result<()> {
         match clear_type {
             ClearType::All => self.clear(),
@@ -273,19 +287,21 @@ pub trait Backend {
         }
     }
 
-    /// Get the size of the terminal screen in columns/rows as a [`Rect`].
+    /// Get the size of the terminal screen in columns/rows as a [`Size`].
     ///
-    /// The returned [`Rect`] contains the width and height of the terminal screen.
+    /// The returned [`Size`] contains the width and height of the terminal screen.
     ///
     /// # Example
     ///
-    /// ```rust,no_run
-    /// # use ratatui::{prelude::*, backend::TestBackend};
-    /// let backend = TestBackend::new(80, 25);
-    /// assert_eq!(backend.size()?, Rect::new(0, 0, 80, 25));
+    /// ```rust
+    /// # use ratatui::{backend::{TestBackend}};
+    /// # let backend = TestBackend::new(80, 25);
+    /// use ratatui::{backend::Backend, layout::Size};
+    ///
+    /// assert_eq!(backend.size()?, Size::new(80, 25));
     /// # std::io::Result::Ok(())
     /// ```
-    fn size(&self) -> io::Result<Rect>;
+    fn size(&self) -> io::Result<Size>;
 
     /// Get the size of the terminal screen in columns/rows and pixels as a [`WindowSize`].
     ///
@@ -296,6 +312,64 @@ pub trait Backend {
 
     /// Flush any buffered content to the terminal screen.
     fn flush(&mut self) -> io::Result<()>;
+
+    /// Scroll a region of the screen upwards, where a region is specified by a (half-open) range
+    /// of rows.
+    ///
+    /// Each row in the region is replaced by the row `line_count` rows below it, except the bottom
+    /// `line_count` rows, which are replaced by empty rows. If `line_count` is equal to or larger
+    /// than the number of rows in the region, then all rows are replaced with empty rows.
+    ///
+    /// If the region includes row 0, then `line_count` rows are copied into the bottom of the
+    /// scrollback buffer. These rows are first taken from the old contents of the region, starting
+    /// from the top. If there aren't sufficient rows in the region, then the remainder are empty
+    /// rows.
+    ///
+    /// The position of the cursor afterwards is undefined.
+    ///
+    /// The behavior is designed to match what ANSI terminals do when scrolling regions are
+    /// established. With ANSI terminals, a scrolling region can be established with the "^[[X;Yr"
+    /// sequence, where X and Y define the lines of the region. The scrolling region can be reset
+    /// to be the whole screen with the "^[[r" sequence.
+    ///
+    /// When a scrolling region is established in an ANSI terminal, various operations' behaviors
+    /// are changed in such a way that the scrolling region acts like a "virtual screen". In
+    /// particular, the scrolling sequence "^[[NS", which scrolls lines up by a count of N.
+    ///
+    /// On an ANSI terminal, this method will probably translate to something like:
+    /// "^[[X;Yr^[[NS^[[r". That is, set the scrolling region, scroll up, then reset the scrolling
+    /// region.
+    ///
+    /// For examples of how this function is expected to work, refer to the tests for
+    /// [`TestBackend::scroll_region_up`].
+    #[cfg(feature = "scrolling-regions")]
+    fn scroll_region_up(&mut self, region: std::ops::Range<u16>, line_count: u16)
+        -> io::Result<()>;
+
+    /// Scroll a region of the screen downwards, where a region is specified by a (half-open) range
+    /// of rows.
+    ///
+    /// Each row in the region is replaced by the row `line_count` rows above it, except the top
+    /// `line_count` rows, which are replaced by empty rows. If `line_count` is equal to or larger
+    /// than the number of rows in the region, then all rows are replaced with empty rows.
+    ///
+    /// The position of the cursor afterwards is undefined.
+    ///
+    /// See the documentation for [`Self::scroll_region_down`] for more information about how this
+    /// is expected to be implemented for ANSI terminals. All of that applies, except the ANSI
+    /// sequence to scroll down is "^[[NT".
+    ///
+    /// This function is asymmetrical with regards to the scrollback buffer. The reason is that
+    /// this how terminals seem to implement things.
+    ///
+    /// For examples of how this function is expected to work, refer to the tests for
+    /// [`TestBackend::scroll_region_down`].
+    #[cfg(feature = "scrolling-regions")]
+    fn scroll_region_down(
+        &mut self,
+        region: std::ops::Range<u16>,
+        line_count: u16,
+    ) -> io::Result<()>;
 }
 
 #[cfg(test)]

ratatui-core/src/buffer.rs

@@ -0,0 +1,9 @@
+#![warn(missing_docs)]
+//! A module for the [`Buffer`] and [`Cell`] types.
+
+mod assert;
+mod buffer;
+mod cell;
+
+pub use buffer::Buffer;
+pub use cell::Cell;

ratatui-core/src/buffer/assert.rs

@@ -0,0 +1,73 @@
+/// Assert that two buffers are equal by comparing their areas and content.
+///
+/// # Panics
+/// When the buffers differ this method panics and displays the differences similar to
+/// `assert_eq!()`.
+#[deprecated = "use assert_eq!(&actual, &expected)"]
+#[macro_export]
+macro_rules! assert_buffer_eq {
+    ($actual_expr:expr, $expected_expr:expr) => {
+        match (&$actual_expr, &$expected_expr) {
+            (actual, expected) => {
+                assert!(
+                    actual.area == expected.area,
+                    "buffer areas not equal\nexpected: {expected:?}\nactual:   {actual:?}",
+                );
+                let nice_diff = expected
+                    .diff(actual)
+                    .into_iter()
+                    .enumerate()
+                    .map(|(i, (x, y, cell))| {
+                        let expected_cell = &expected[(x, y)];
+                        format!("{i}: at ({x}, {y})\n  expected: {expected_cell:?}\n  actual:   {cell:?}")
+                    })
+                    .collect::<Vec<String>>()
+                    .join("\n");
+                assert!(
+                    nice_diff.is_empty(),
+                    "buffer contents not equal\nexpected: {expected:?}\nactual:   {actual:?}\ndiff:\n{nice_diff}",
+                );
+                // shouldn't get here, but this guards against future behavior
+                // that changes equality but not area or content
+                assert_eq!(
+                    actual, expected,
+                    "buffers are not equal in an unexpected way. Please open an issue about this."
+                );
+            }
+        }
+    };
+}
+
+#[allow(deprecated)]
+#[cfg(test)]
+mod tests {
+    use crate::{
+        buffer::Buffer,
+        layout::Rect,
+        style::{Color, Style},
+    };
+
+    #[test]
+    fn assert_buffer_eq_does_not_panic_on_equal_buffers() {
+        let buffer = Buffer::empty(Rect::new(0, 0, 5, 1));
+        let other_buffer = Buffer::empty(Rect::new(0, 0, 5, 1));
+        assert_buffer_eq!(buffer, other_buffer);
+    }
+
+    #[should_panic = "buffer areas not equal"]
+    #[test]
+    fn assert_buffer_eq_panics_on_unequal_area() {
+        let buffer = Buffer::empty(Rect::new(0, 0, 5, 1));
+        let other_buffer = Buffer::empty(Rect::new(0, 0, 6, 1));
+        assert_buffer_eq!(buffer, other_buffer);
+    }
+
+    #[should_panic = "buffer contents not equal"]
+    #[test]
+    fn assert_buffer_eq_panics_on_unequal_style() {
+        let buffer = Buffer::empty(Rect::new(0, 0, 5, 1));
+        let mut other_buffer = Buffer::empty(Rect::new(0, 0, 5, 1));
+        other_buffer.set_string(0, 0, " ", Style::default().fg(Color::Red));
+        assert_buffer_eq!(buffer, other_buffer);
+    }
+}

ratatui-core/src/buffer/cell.rs

@@ -0,0 +1,297 @@
+use compact_str::CompactString;
+
+use crate::style::{Color, Modifier, Style};
+
+/// A buffer cell
+#[derive(Debug, Clone, Eq, PartialEq, Hash)]
+#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
+pub struct Cell {
+    /// The string to be drawn in the cell.
+    ///
+    /// This accepts unicode grapheme clusters which might take up more than one cell.
+    ///
+    /// This is a [`CompactString`] which is a wrapper around [`String`] that uses a small inline
+    /// buffer for short strings.
+    ///
+    /// See <https://github.com/ratatui/ratatui/pull/601> for more information.
+    symbol: CompactString,
+
+    /// The foreground color of the cell.
+    pub fg: Color,
+
+    /// The background color of the cell.
+    pub bg: Color,
+
+    /// The underline color of the cell.
+    #[cfg(feature = "underline-color")]
+    pub underline_color: Color,
+
+    /// The modifier of the cell.
+    pub modifier: Modifier,
+
+    /// Whether the cell should be skipped when copying (diffing) the buffer to the screen.
+    pub skip: bool,
+}
+
+impl Cell {
+    /// An empty `Cell`
+    pub const EMPTY: Self = Self::new(" ");
+
+    /// Creates a new `Cell` with the given symbol.
+    ///
+    /// This works at compile time and puts the symbol onto the stack. Fails to build when the
+    /// symbol doesnt fit onto the stack and requires to be placed on the heap. Use
+    /// `Self::default().set_symbol()` in that case. See [`CompactString::const_new`] for more
+    /// details on this.
+    pub const fn new(symbol: &'static str) -> Self {
+        Self {
+            symbol: CompactString::const_new(symbol),
+            fg: Color::Reset,
+            bg: Color::Reset,
+            #[cfg(feature = "underline-color")]
+            underline_color: Color::Reset,
+            modifier: Modifier::empty(),
+            skip: false,
+        }
+    }
+
+    /// Gets the symbol of the cell.
+    #[must_use]
+    pub fn symbol(&self) -> &str {
+        self.symbol.as_str()
+    }
+
+    /// Sets the symbol of the cell.
+    pub fn set_symbol(&mut self, symbol: &str) -> &mut Self {
+        self.symbol = CompactString::new(symbol);
+        self
+    }
+
+    /// Appends a symbol to the cell.
+    ///
+    /// This is particularly useful for adding zero-width characters to the cell.
+    pub(crate) fn append_symbol(&mut self, symbol: &str) -> &mut Self {
+        self.symbol.push_str(symbol);
+        self
+    }
+
+    /// Sets the symbol of the cell to a single character.
+    pub fn set_char(&mut self, ch: char) -> &mut Self {
+        let mut buf = [0; 4];
+        self.symbol = CompactString::new(ch.encode_utf8(&mut buf));
+        self
+    }
+
+    /// Sets the foreground color of the cell.
+    pub fn set_fg(&mut self, color: Color) -> &mut Self {
+        self.fg = color;
+        self
+    }
+
+    /// Sets the background color of the cell.
+    pub fn set_bg(&mut self, color: Color) -> &mut Self {
+        self.bg = color;
+        self
+    }
+
+    /// Sets the style of the cell.
+    ///
+    ///  `style` accepts any type that is convertible to [`Style`] (e.g. [`Style`], [`Color`], or
+    /// your own type that implements [`Into<Style>`]).
+    pub fn set_style<S: Into<Style>>(&mut self, style: S) -> &mut Self {
+        let style = style.into();
+        if let Some(c) = style.fg {
+            self.fg = c;
+        }
+        if let Some(c) = style.bg {
+            self.bg = c;
+        }
+        #[cfg(feature = "underline-color")]
+        if let Some(c) = style.underline_color {
+            self.underline_color = c;
+        }
+        self.modifier.insert(style.add_modifier);
+        self.modifier.remove(style.sub_modifier);
+        self
+    }
+
+    /// Returns the style of the cell.
+    #[must_use]
+    pub const fn style(&self) -> Style {
+        Style {
+            fg: Some(self.fg),
+            bg: Some(self.bg),
+            #[cfg(feature = "underline-color")]
+            underline_color: Some(self.underline_color),
+            add_modifier: self.modifier,
+            sub_modifier: Modifier::empty(),
+        }
+    }
+
+    /// Sets the cell to be skipped when copying (diffing) the buffer to the screen.
+    ///
+    /// This is helpful when it is necessary to prevent the buffer from overwriting a cell that is
+    /// covered by an image from some terminal graphics protocol (Sixel / iTerm / Kitty ...).
+    pub fn set_skip(&mut self, skip: bool) -> &mut Self {
+        self.skip = skip;
+        self
+    }
+
+    /// Resets the cell to the empty state.
+    pub fn reset(&mut self) {
+        self.symbol = CompactString::const_new(" ");
+        self.fg = Color::Reset;
+        self.bg = Color::Reset;
+        #[cfg(feature = "underline-color")]
+        {
+            self.underline_color = Color::Reset;
+        }
+        self.modifier = Modifier::empty();
+        self.skip = false;
+    }
+}
+
+impl Default for Cell {
+    fn default() -> Self {
+        Self::EMPTY
+    }
+}
+
+impl From<char> for Cell {
+    fn from(ch: char) -> Self {
+        let mut cell = Self::EMPTY;
+        cell.set_char(ch);
+        cell
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn new() {
+        let cell = Cell::new("あ");
+        assert_eq!(
+            cell,
+            Cell {
+                symbol: CompactString::const_new("あ"),
+                fg: Color::Reset,
+                bg: Color::Reset,
+                #[cfg(feature = "underline-color")]
+                underline_color: Color::Reset,
+                modifier: Modifier::empty(),
+                skip: false,
+            }
+        );
+    }
+
+    #[test]
+    fn empty() {
+        let cell = Cell::EMPTY;
+        assert_eq!(cell.symbol(), " ");
+    }
+
+    #[test]
+    fn set_symbol() {
+        let mut cell = Cell::EMPTY;
+        cell.set_symbol("あ"); // Multi-byte character
+        assert_eq!(cell.symbol(), "あ");
+        cell.set_symbol("👨‍👩‍👧‍👦"); // Multiple code units combined with ZWJ
+        assert_eq!(cell.symbol(), "👨‍👩‍👧‍👦");
+    }
+
+    #[test]
+    fn append_symbol() {
+        let mut cell = Cell::EMPTY;
+        cell.set_symbol("あ"); // Multi-byte character
+        cell.append_symbol("\u{200B}"); // zero-width space
+        assert_eq!(cell.symbol(), "あ\u{200B}");
+    }
+
+    #[test]
+    fn set_char() {
+        let mut cell = Cell::EMPTY;
+        cell.set_char('あ'); // Multi-byte character
+        assert_eq!(cell.symbol(), "あ");
+    }
+
+    #[test]
+    fn set_fg() {
+        let mut cell = Cell::EMPTY;
+        cell.set_fg(Color::Red);
+        assert_eq!(cell.fg, Color::Red);
+    }
+
+    #[test]
+    fn set_bg() {
+        let mut cell = Cell::EMPTY;
+        cell.set_bg(Color::Red);
+        assert_eq!(cell.bg, Color::Red);
+    }
+
+    #[test]
+    fn set_style() {
+        let mut cell = Cell::EMPTY;
+        cell.set_style(Style::new().fg(Color::Red).bg(Color::Blue));
+        assert_eq!(cell.fg, Color::Red);
+        assert_eq!(cell.bg, Color::Blue);
+    }
+
+    #[test]
+    fn set_skip() {
+        let mut cell = Cell::EMPTY;
+        cell.set_skip(true);
+        assert!(cell.skip);
+    }
+
+    #[test]
+    fn reset() {
+        let mut cell = Cell::EMPTY;
+        cell.set_symbol("あ");
+        cell.set_fg(Color::Red);
+        cell.set_bg(Color::Blue);
+        cell.set_skip(true);
+        cell.reset();
+        assert_eq!(cell.symbol(), " ");
+        assert_eq!(cell.fg, Color::Reset);
+        assert_eq!(cell.bg, Color::Reset);
+        assert!(!cell.skip);
+    }
+
+    #[test]
+    fn style() {
+        let cell = Cell::EMPTY;
+        assert_eq!(
+            cell.style(),
+            Style {
+                fg: Some(Color::Reset),
+                bg: Some(Color::Reset),
+                #[cfg(feature = "underline-color")]
+                underline_color: Some(Color::Reset),
+                add_modifier: Modifier::empty(),
+                sub_modifier: Modifier::empty(),
+            }
+        );
+    }
+
+    #[test]
+    fn default() {
+        let cell = Cell::default();
+        assert_eq!(cell.symbol(), " ");
+    }
+
+    #[test]
+    fn cell_eq() {
+        let cell1 = Cell::new("あ");
+        let cell2 = Cell::new("あ");
+        assert_eq!(cell1, cell2);
+    }
+
+    #[test]
+    fn cell_ne() {
+        let cell1 = Cell::new("あ");
+        let cell2 = Cell::new("い");
+        assert_ne!(cell1, cell2);
+    }
+}

ratatui-core/src/layout.rs

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

ratatui-core/src/layout/alignment.rs

@@ -0,0 +1,31 @@
+use strum::{Display, EnumString};
+
+#[derive(Debug, Default, Display, EnumString, Clone, Copy, Eq, PartialEq, Hash)]
+pub enum Alignment {
+    #[default]
+    Left,
+    Center,
+    Right,
+}
+
+#[cfg(test)]
+mod tests {
+    use strum::ParseError;
+
+    use super::*;
+
+    #[test]
+    fn alignment_to_string() {
+        assert_eq!(Alignment::Left.to_string(), "Left");
+        assert_eq!(Alignment::Center.to_string(), "Center");
+        assert_eq!(Alignment::Right.to_string(), "Right");
+    }
+
+    #[test]
+    fn alignment_from_str() {
+        assert_eq!("Left".parse::<Alignment>(), Ok(Alignment::Left));
+        assert_eq!("Center".parse::<Alignment>(), Ok(Alignment::Center));
+        assert_eq!("Right".parse::<Alignment>(), Ok(Alignment::Right));
+        assert_eq!("".parse::<Alignment>(), Err(ParseError::VariantNotFound));
+    }
+}

ratatui-core/src/layout/constraint.rs

@@ -0,0 +1,499 @@
+use std::fmt;
+
+use strum::EnumIs;
+
+/// A constraint that defines the size of a layout element.
+///
+/// Constraints can be used to specify a fixed size, a percentage of the available space, a ratio of
+/// the available space, a minimum or maximum size or a fill proportional value for a layout
+/// element.
+///
+/// Relative constraints (percentage, ratio) are calculated relative to the entire space being
+/// divided, rather than the space available after applying more fixed constraints (min, max,
+/// length).
+///
+/// Constraints are prioritized in the following order:
+///
+/// 1. [`Constraint::Min`]
+/// 2. [`Constraint::Max`]
+/// 3. [`Constraint::Length`]
+/// 4. [`Constraint::Percentage`]
+/// 5. [`Constraint::Ratio`]
+/// 6. [`Constraint::Fill`]
+///
+/// # Examples
+///
+/// `Constraint` provides helper methods to create lists of constraints from various input formats.
+///
+/// ```rust
+/// use ratatui_core::layout::Constraint;
+///
+/// // Create a layout with specified lengths for each element
+/// let constraints = Constraint::from_lengths([10, 20, 10]);
+///
+/// // Create a centered layout using ratio or percentage constraints
+/// let constraints = Constraint::from_ratios([(1, 4), (1, 2), (1, 4)]);
+/// let constraints = Constraint::from_percentages([25, 50, 25]);
+///
+/// // Create a centered layout with a minimum size constraint for specific elements
+/// let constraints = Constraint::from_mins([0, 100, 0]);
+///
+/// // Create a sidebar layout specifying maximum sizes for the columns
+/// let constraints = Constraint::from_maxes([30, 170]);
+///
+/// // Create a layout with fill proportional sizes for each element
+/// let constraints = Constraint::from_fills([1, 2, 1]);
+/// ```
+#[derive(Debug, Clone, Copy, Eq, PartialEq, Hash, EnumIs)]
+pub enum Constraint {
+    /// Applies a minimum size constraint to the element
+    ///
+    /// The element size is set to at least the specified amount.
+    ///
+    /// # Examples
+    ///
+    /// `[Percentage(100), Min(20)]`
+    ///
+    /// ```plain
+    /// ┌────────────────────────────┐┌──────────────────┐
+    /// │            30 px           ││       20 px      │
+    /// └────────────────────────────┘└──────────────────┘
+    /// ```
+    ///
+    /// `[Percentage(100), Min(10)]`
+    ///
+    /// ```plain
+    /// ┌──────────────────────────────────────┐┌────────┐
+    /// │                 40 px                ││  10 px │
+    /// └──────────────────────────────────────┘└────────┘
+    /// ```
+    Min(u16),
+
+    /// Applies a maximum size constraint to the element
+    ///
+    /// The element size is set to at most the specified amount.
+    ///
+    /// # Examples
+    ///
+    /// `[Percentage(0), Max(20)]`
+    ///
+    /// ```plain
+    /// ┌────────────────────────────┐┌──────────────────┐
+    /// │            30 px           ││       20 px      │
+    /// └────────────────────────────┘└──────────────────┘
+    /// ```
+    ///
+    /// `[Percentage(0), Max(10)]`
+    ///
+    /// ```plain
+    /// ┌──────────────────────────────────────┐┌────────┐
+    /// │                 40 px                ││  10 px │
+    /// └──────────────────────────────────────┘└────────┘
+    /// ```
+    Max(u16),
+
+    /// Applies a length constraint to the element
+    ///
+    /// The element size is set to the specified amount.
+    ///
+    /// # Examples
+    ///
+    /// `[Length(20), Length(20)]`
+    ///
+    /// ```plain
+    /// ┌──────────────────┐┌──────────────────┐
+    /// │       20 px      ││       20 px      │
+    /// └──────────────────┘└──────────────────┘
+    /// ```
+    ///
+    /// `[Length(20), Length(30)]`
+    ///
+    /// ```plain
+    /// ┌──────────────────┐┌────────────────────────────┐
+    /// │       20 px      ││            30 px           │
+    /// └──────────────────┘└────────────────────────────┘
+    /// ```
+    Length(u16),
+
+    /// Applies a percentage of the available space to the element
+    ///
+    /// Converts the given percentage to a floating-point value and multiplies that with area. This
+    /// value is rounded back to a integer as part of the layout split calculation.
+    ///
+    /// **Note**: As this value only accepts a `u16`, certain percentages that cannot be
+    /// represented exactly (e.g. 1/3) are not possible. You might want to use
+    /// [`Constraint::Ratio`] or [`Constraint::Fill`] in such cases.
+    ///
+    /// # Examples
+    ///
+    /// `[Percentage(75), Fill(1)]`
+    ///
+    /// ```plain
+    /// ┌────────────────────────────────────┐┌──────────┐
+    /// │                38 px               ││   12 px  │
+    /// └────────────────────────────────────┘└──────────┘
+    /// ```
+    ///
+    /// `[Percentage(50), Fill(1)]`
+    ///
+    /// ```plain
+    /// ┌───────────────────────┐┌───────────────────────┐
+    /// │         25 px         ││         25 px         │
+    /// └───────────────────────┘└───────────────────────┘
+    /// ```
+    Percentage(u16),
+
+    /// Applies a ratio of the available space to the element
+    ///
+    /// Converts the given ratio to a floating-point value and multiplies that with area.
+    /// This value is rounded back to a integer as part of the layout split calculation.
+    ///
+    /// # Examples
+    ///
+    /// `[Ratio(1, 2) ; 2]`
+    ///
+    /// ```plain
+    /// ┌───────────────────────┐┌───────────────────────┐
+    /// │         25 px         ││         25 px         │
+    /// └───────────────────────┘└───────────────────────┘
+    /// ```
+    ///
+    /// `[Ratio(1, 4) ; 4]`
+    ///
+    /// ```plain
+    /// ┌───────────┐┌──────────┐┌───────────┐┌──────────┐
+    /// │   13 px   ││   12 px  ││   13 px   ││   12 px  │
+    /// └───────────┘└──────────┘└───────────┘└──────────┘
+    /// ```
+    Ratio(u32, u32),
+
+    /// Applies the scaling factor proportional to all other [`Constraint::Fill`] elements
+    /// to fill excess space
+    ///
+    /// The element will only expand or fill into excess available space, proportionally matching
+    /// other [`Constraint::Fill`] elements while satisfying all other constraints.
+    ///
+    /// # Examples
+    ///
+    ///
+    /// `[Fill(1), Fill(2), Fill(3)]`
+    ///
+    /// ```plain
+    /// ┌──────┐┌───────────────┐┌───────────────────────┐
+    /// │ 8 px ││     17 px     ││         25 px         │
+    /// └──────┘└───────────────┘└───────────────────────┘
+    /// ```
+    ///
+    /// `[Fill(1), Percentage(50), Fill(1)]`
+    ///
+    /// ```plain
+    /// ┌───────────┐┌───────────────────────┐┌──────────┐
+    /// │   13 px   ││         25 px         ││   12 px  │
+    /// └───────────┘└───────────────────────┘└──────────┘
+    /// ```
+    Fill(u16),
+}
+
+impl Constraint {
+    #[deprecated(
+        since = "0.26.0",
+        note = "This field will be hidden in the next minor version."
+    )]
+    pub fn apply(&self, length: u16) -> u16 {
+        match *self {
+            Self::Percentage(p) => {
+                let p = f32::from(p) / 100.0;
+                let length = f32::from(length);
+                (p * length).min(length) as u16
+            }
+            Self::Ratio(numerator, denominator) => {
+                // avoid division by zero by using 1 when denominator is 0
+                // this results in 0/0 -> 0 and x/0 -> x for x != 0
+                let percentage = numerator as f32 / denominator.max(1) as f32;
+                let length = f32::from(length);
+                (percentage * length).min(length) as u16
+            }
+            Self::Length(l) | Self::Fill(l) => length.min(l),
+            Self::Max(m) => length.min(m),
+            Self::Min(m) => length.max(m),
+        }
+    }
+
+    /// Convert an iterator of lengths into a vector of constraints
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// use ratatui_core::layout::{Constraint, Layout, Rect};
+    ///
+    /// # let area = Rect::default();
+    /// let constraints = Constraint::from_lengths([1, 2, 3]);
+    /// let layout = Layout::default().constraints(constraints).split(area);
+    /// ```
+    pub fn from_lengths<T>(lengths: T) -> Vec<Self>
+    where
+        T: IntoIterator<Item = u16>,
+    {
+        lengths.into_iter().map(Self::Length).collect()
+    }
+
+    /// Convert an iterator of ratios into a vector of constraints
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// use ratatui_core::layout::{Constraint, Layout, Rect};
+    ///
+    /// # let area = Rect::default();
+    /// let constraints = Constraint::from_ratios([(1, 4), (1, 2), (1, 4)]);
+    /// let layout = Layout::default().constraints(constraints).split(area);
+    /// ```
+    pub fn from_ratios<T>(ratios: T) -> Vec<Self>
+    where
+        T: IntoIterator<Item = (u32, u32)>,
+    {
+        ratios.into_iter().map(|(n, d)| Self::Ratio(n, d)).collect()
+    }
+
+    /// Convert an iterator of percentages into a vector of constraints
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// use ratatui_core::layout::{Constraint, Layout, Rect};
+    ///
+    /// # let area = Rect::default();
+    /// let constraints = Constraint::from_percentages([25, 50, 25]);
+    /// let layout = Layout::default().constraints(constraints).split(area);
+    /// ```
+    pub fn from_percentages<T>(percentages: T) -> Vec<Self>
+    where
+        T: IntoIterator<Item = u16>,
+    {
+        percentages.into_iter().map(Self::Percentage).collect()
+    }
+
+    /// Convert an iterator of maxes into a vector of constraints
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// use ratatui_core::layout::{Constraint, Layout, Rect};
+    ///
+    /// # let area = Rect::default();
+    /// let constraints = Constraint::from_maxes([1, 2, 3]);
+    /// let layout = Layout::default().constraints(constraints).split(area);
+    /// ```
+    pub fn from_maxes<T>(maxes: T) -> Vec<Self>
+    where
+        T: IntoIterator<Item = u16>,
+    {
+        maxes.into_iter().map(Self::Max).collect()
+    }
+
+    /// Convert an iterator of mins into a vector of constraints
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// use ratatui_core::layout::{Constraint, Layout, Rect};
+    ///
+    /// # let area = Rect::default();
+    /// let constraints = Constraint::from_mins([1, 2, 3]);
+    /// let layout = Layout::default().constraints(constraints).split(area);
+    /// ```
+    pub fn from_mins<T>(mins: T) -> Vec<Self>
+    where
+        T: IntoIterator<Item = u16>,
+    {
+        mins.into_iter().map(Self::Min).collect()
+    }
+
+    /// Convert an iterator of proportional factors into a vector of constraints
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// use ratatui_core::layout::{Constraint, Layout, Rect};
+    ///
+    /// # let area = Rect::default();
+    /// let constraints = Constraint::from_fills([1, 2, 3]);
+    /// let layout = Layout::default().constraints(constraints).split(area);
+    /// ```
+    pub fn from_fills<T>(proportional_factors: T) -> Vec<Self>
+    where
+        T: IntoIterator<Item = u16>,
+    {
+        proportional_factors.into_iter().map(Self::Fill).collect()
+    }
+}
+
+impl From<u16> for Constraint {
+    /// Convert a `u16` into a [`Constraint::Length`]
+    ///
+    /// This is useful when you want to specify a fixed size for a layout, but don't want to
+    /// explicitly create a [`Constraint::Length`] yourself.
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// use ratatui_core::layout::{Constraint, Direction, Layout, Rect};
+    ///
+    /// # let area = Rect::default();
+    /// let layout = Layout::new(Direction::Vertical, [1, 2, 3]).split(area);
+    /// let layout = Layout::horizontal([1, 2, 3]).split(area);
+    /// let layout = Layout::vertical([1, 2, 3]).split(area);
+    /// ````
+    fn from(length: u16) -> Self {
+        Self::Length(length)
+    }
+}
+
+impl From<&Self> for Constraint {
+    fn from(constraint: &Self) -> Self {
+        *constraint
+    }
+}
+
+impl AsRef<Self> for Constraint {
+    fn as_ref(&self) -> &Self {
+        self
+    }
+}
+
+impl Default for Constraint {
+    fn default() -> Self {
+        Self::Percentage(100)
+    }
+}
+
+impl fmt::Display for Constraint {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::Percentage(p) => write!(f, "Percentage({p})"),
+            Self::Ratio(n, d) => write!(f, "Ratio({n}, {d})"),
+            Self::Length(l) => write!(f, "Length({l})"),
+            Self::Fill(l) => write!(f, "Fill({l})"),
+            Self::Max(m) => write!(f, "Max({m})"),
+            Self::Min(m) => write!(f, "Min({m})"),
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn default() {
+        assert_eq!(Constraint::default(), Constraint::Percentage(100));
+    }
+
+    #[test]
+    fn to_string() {
+        assert_eq!(Constraint::Percentage(50).to_string(), "Percentage(50)");
+        assert_eq!(Constraint::Ratio(1, 2).to_string(), "Ratio(1, 2)");
+        assert_eq!(Constraint::Length(10).to_string(), "Length(10)");
+        assert_eq!(Constraint::Max(10).to_string(), "Max(10)");
+        assert_eq!(Constraint::Min(10).to_string(), "Min(10)");
+    }
+
+    #[test]
+    fn from_lengths() {
+        let expected = [
+            Constraint::Length(1),
+            Constraint::Length(2),
+            Constraint::Length(3),
+        ];
+        assert_eq!(Constraint::from_lengths([1, 2, 3]), expected);
+        assert_eq!(Constraint::from_lengths(vec![1, 2, 3]), expected);
+    }
+
+    #[test]
+    fn from_ratios() {
+        let expected = [
+            Constraint::Ratio(1, 4),
+            Constraint::Ratio(1, 2),
+            Constraint::Ratio(1, 4),
+        ];
+        assert_eq!(Constraint::from_ratios([(1, 4), (1, 2), (1, 4)]), expected);
+        assert_eq!(
+            Constraint::from_ratios(vec![(1, 4), (1, 2), (1, 4)]),
+            expected
+        );
+    }
+
+    #[test]
+    fn from_percentages() {
+        let expected = [
+            Constraint::Percentage(25),
+            Constraint::Percentage(50),
+            Constraint::Percentage(25),
+        ];
+        assert_eq!(Constraint::from_percentages([25, 50, 25]), expected);
+        assert_eq!(Constraint::from_percentages(vec![25, 50, 25]), expected);
+    }
+
+    #[test]
+    fn from_maxes() {
+        let expected = [Constraint::Max(1), Constraint::Max(2), Constraint::Max(3)];
+        assert_eq!(Constraint::from_maxes([1, 2, 3]), expected);
+        assert_eq!(Constraint::from_maxes(vec![1, 2, 3]), expected);
+    }
+
+    #[test]
+    fn from_mins() {
+        let expected = [Constraint::Min(1), Constraint::Min(2), Constraint::Min(3)];
+        assert_eq!(Constraint::from_mins([1, 2, 3]), expected);
+        assert_eq!(Constraint::from_mins(vec![1, 2, 3]), expected);
+    }
+
+    #[test]
+    fn from_fills() {
+        let expected = [
+            Constraint::Fill(1),
+            Constraint::Fill(2),
+            Constraint::Fill(3),
+        ];
+        assert_eq!(Constraint::from_fills([1, 2, 3]), expected);
+        assert_eq!(Constraint::from_fills(vec![1, 2, 3]), expected);
+    }
+
+    #[test]
+    #[allow(deprecated)]
+    fn apply() {
+        assert_eq!(Constraint::Percentage(0).apply(100), 0);
+        assert_eq!(Constraint::Percentage(50).apply(100), 50);
+        assert_eq!(Constraint::Percentage(100).apply(100), 100);
+        assert_eq!(Constraint::Percentage(200).apply(100), 100);
+        assert_eq!(Constraint::Percentage(u16::MAX).apply(100), 100);
+
+        // 0/0 intentionally avoids a panic by returning 0.
+        assert_eq!(Constraint::Ratio(0, 0).apply(100), 0);
+        // 1/0 intentionally avoids a panic by returning 100% of the length.
+        assert_eq!(Constraint::Ratio(1, 0).apply(100), 100);
+        assert_eq!(Constraint::Ratio(0, 1).apply(100), 0);
+        assert_eq!(Constraint::Ratio(1, 2).apply(100), 50);
+        assert_eq!(Constraint::Ratio(2, 2).apply(100), 100);
+        assert_eq!(Constraint::Ratio(3, 2).apply(100), 100);
+        assert_eq!(Constraint::Ratio(u32::MAX, 2).apply(100), 100);
+
+        assert_eq!(Constraint::Length(0).apply(100), 0);
+        assert_eq!(Constraint::Length(50).apply(100), 50);
+        assert_eq!(Constraint::Length(100).apply(100), 100);
+        assert_eq!(Constraint::Length(200).apply(100), 100);
+        assert_eq!(Constraint::Length(u16::MAX).apply(100), 100);
+
+        assert_eq!(Constraint::Max(0).apply(100), 0);
+        assert_eq!(Constraint::Max(50).apply(100), 50);
+        assert_eq!(Constraint::Max(100).apply(100), 100);
+        assert_eq!(Constraint::Max(200).apply(100), 100);
+        assert_eq!(Constraint::Max(u16::MAX).apply(100), 100);
+
+        assert_eq!(Constraint::Min(0).apply(100), 100);
+        assert_eq!(Constraint::Min(50).apply(100), 100);
+        assert_eq!(Constraint::Min(100).apply(100), 100);
+        assert_eq!(Constraint::Min(200).apply(100), 200);
+        assert_eq!(Constraint::Min(u16::MAX).apply(100), u16::MAX);
+    }
+}

ratatui-core/src/layout/direction.rs

@@ -0,0 +1,28 @@
+use strum::{Display, EnumString};
+
+#[derive(Debug, Default, Display, EnumString, Clone, Copy, Eq, PartialEq, Hash)]
+pub enum Direction {
+    Horizontal,
+    #[default]
+    Vertical,
+}
+
+#[cfg(test)]
+mod tests {
+    use strum::ParseError;
+
+    use super::*;
+
+    #[test]
+    fn direction_to_string() {
+        assert_eq!(Direction::Horizontal.to_string(), "Horizontal");
+        assert_eq!(Direction::Vertical.to_string(), "Vertical");
+    }
+
+    #[test]
+    fn direction_from_str() {
+        assert_eq!("Horizontal".parse::<Direction>(), Ok(Direction::Horizontal));
+        assert_eq!("Vertical".parse::<Direction>(), Ok(Direction::Vertical));
+        assert_eq!("".parse::<Direction>(), Err(ParseError::VariantNotFound));
+    }
+}

ratatui-core/src/layout/flex.rs

@@ -0,0 +1,181 @@
+use strum::{Display, EnumIs, EnumString};
+
+#[allow(unused_imports)]
+use crate::layout::Constraint;
+
+/// Defines the options for layout flex justify content in a container.
+///
+/// This enumeration controls the distribution of space when layout constraints are met.
+///
+/// - `Legacy`: Fills the available space within the container, putting excess space into the last
+///   element.
+/// - `Start`: Aligns items to the start of the container.
+/// - `End`: Aligns items to the end of the container.
+/// - `Center`: Centers items within the container.
+/// - `SpaceBetween`: Adds excess space between each element.
+/// - `SpaceAround`: Adds excess space around each element.
+#[derive(Copy, Debug, Default, Display, EnumString, Clone, Eq, PartialEq, Hash, EnumIs)]
+pub enum Flex {
+    /// Fills the available space within the container, putting excess space into the last
+    /// constraint of the lowest priority. This matches the default behavior of ratatui and tui
+    /// applications without [`Flex`]
+    ///
+    /// The following examples illustrate the allocation of excess in various combinations of
+    /// constraints. As a refresher, the priorities of constraints are as follows:
+    ///
+    /// 1. [`Constraint::Min`]
+    /// 2. [`Constraint::Max`]
+    /// 3. [`Constraint::Length`]
+    /// 4. [`Constraint::Percentage`]
+    /// 5. [`Constraint::Ratio`]
+    /// 6. [`Constraint::Fill`]
+    ///
+    /// When every constraint is `Length`, the last element gets the excess.
+    ///
+    /// ```plain
+    /// <----------------------------------- 80 px ------------------------------------>
+    /// ┌──────20 px───────┐┌──────20 px───────┐┌────────────────40 px─────────────────┐
+    /// │    Length(20)    ││    Length(20)    ││              Length(20)              │
+    /// └──────────────────┘└──────────────────┘└──────────────────────────────────────┘
+    ///                                         ^^^^^^^^^^^^^^^^ EXCESS ^^^^^^^^^^^^^^^^
+    /// ```
+    ///
+    /// Fill constraints have the lowest priority amongst all the constraints and hence
+    /// will always take up any excess space available.
+    ///
+    /// ```plain
+    /// <----------------------------------- 80 px ------------------------------------>
+    /// ┌──────20 px───────┐┌──────20 px───────┐┌──────20 px───────┐┌──────20 px───────┐
+    /// │      Fill(0)     ││      Max(20)     ││    Length(20)    ││     Length(20)   │
+    /// └──────────────────┘└──────────────────┘└──────────────────┘└──────────────────┘
+    /// ^^^^^^ EXCESS ^^^^^^
+    /// ```
+    ///
+    /// # Examples
+    ///
+    /// ```plain
+    /// <------------------------------------80 px------------------------------------->
+    /// ┌──────────────────────────60 px───────────────────────────┐┌──────20 px───────┐
+    /// │                          Min(20)                         ││      Max(20)     │
+    /// └──────────────────────────────────────────────────────────┘└──────────────────┘
+    ///
+    /// <------------------------------------80 px------------------------------------->
+    /// ┌────────────────────────────────────80 px─────────────────────────────────────┐
+    /// │                                    Max(20)                                   │
+    /// └──────────────────────────────────────────────────────────────────────────────┘
+    /// ```
+    Legacy,
+
+    /// Aligns items to the start of the container.
+    ///
+    /// # Examples
+    ///
+    /// ```plain
+    /// <------------------------------------80 px------------------------------------->
+    /// ┌────16 px─────┐┌──────20 px───────┐┌──────20 px───────┐
+    /// │Percentage(20)││    Length(20)    ││     Fixed(20)    │
+    /// └──────────────┘└──────────────────┘└──────────────────┘
+    ///
+    /// <------------------------------------80 px------------------------------------->
+    /// ┌──────20 px───────┐┌──────20 px───────┐
+    /// │      Max(20)     ││      Max(20)     │
+    /// └──────────────────┘└──────────────────┘
+    ///
+    /// <------------------------------------80 px------------------------------------->
+    /// ┌──────20 px───────┐
+    /// │      Max(20)     │
+    /// └──────────────────┘
+    /// ```
+    #[default]
+    Start,
+
+    /// Aligns items to the end of the container.
+    ///
+    /// # Examples
+    ///
+    /// ```plain
+    /// <------------------------------------80 px------------------------------------->
+    ///                         ┌────16 px─────┐┌──────20 px───────┐┌──────20 px───────┐
+    ///                         │Percentage(20)││    Length(20)    ││     Length(20)   │
+    ///                         └──────────────┘└──────────────────┘└──────────────────┘
+    ///
+    /// <------------------------------------80 px------------------------------------->
+    ///                                         ┌──────20 px───────┐┌──────20 px───────┐
+    ///                                         │      Max(20)     ││      Max(20)     │
+    ///                                         └──────────────────┘└──────────────────┘
+    ///
+    /// <------------------------------------80 px------------------------------------->
+    ///                                                             ┌──────20 px───────┐
+    ///                                                             │      Max(20)     │
+    ///                                                             └──────────────────┘
+    /// ```
+    End,
+
+    /// Centers items within the container.
+    ///
+    /// # Examples
+    ///
+    /// ```plain
+    /// <------------------------------------80 px------------------------------------->
+    ///             ┌────16 px─────┐┌──────20 px───────┐┌──────20 px───────┐
+    ///             │Percentage(20)││    Length(20)    ││     Length(20)   │
+    ///             └──────────────┘└──────────────────┘└──────────────────┘
+    ///
+    /// <------------------------------------80 px------------------------------------->
+    ///                     ┌──────20 px───────┐┌──────20 px───────┐
+    ///                     │      Max(20)     ││      Max(20)     │
+    ///                     └──────────────────┘└──────────────────┘
+    ///
+    /// <------------------------------------80 px------------------------------------->
+    ///                               ┌──────20 px───────┐
+    ///                               │      Max(20)     │
+    ///                               └──────────────────┘
+    /// ```
+    Center,
+
+    /// Adds excess space between each element.
+    ///
+    /// # Examples
+    ///
+    /// ```plain
+    /// <------------------------------------80 px------------------------------------->
+    /// ┌────16 px─────┐            ┌──────20 px───────┐            ┌──────20 px───────┐
+    /// │Percentage(20)│            │    Length(20)    │            │     Length(20)   │
+    /// └──────────────┘            └──────────────────┘            └──────────────────┘
+    ///
+    /// <------------------------------------80 px------------------------------------->
+    /// ┌──────20 px───────┐                                        ┌──────20 px───────┐
+    /// │      Max(20)     │                                        │      Max(20)     │
+    /// └──────────────────┘                                        └──────────────────┘
+    ///
+    /// <------------------------------------80 px------------------------------------->
+    /// ┌────────────────────────────────────80 px─────────────────────────────────────┐
+    /// │                                    Max(20)                                   │
+    /// └──────────────────────────────────────────────────────────────────────────────┘
+    /// ```
+    SpaceBetween,
+
+    /// Adds excess space around each element.
+    ///
+    /// # Examples
+    ///
+    /// ```plain
+    /// <------------------------------------80 px------------------------------------->
+    ///       ┌────16 px─────┐      ┌──────20 px───────┐      ┌──────20 px───────┐
+    ///       │Percentage(20)│      │    Length(20)    │      │     Length(20)   │
+    ///       └──────────────┘      └──────────────────┘      └──────────────────┘
+    ///
+    /// <------------------------------------80 px------------------------------------->
+    ///              ┌──────20 px───────┐              ┌──────20 px───────┐
+    ///              │      Max(20)     │              │      Max(20)     │
+    ///              └──────────────────┘              └──────────────────┘
+    ///
+    /// <------------------------------------80 px------------------------------------->
+    ///                               ┌──────20 px───────┐
+    ///                               │      Max(20)     │
+    ///                               └──────────────────┘
+    /// ```
+    SpaceAround,
+}
+#[cfg(test)]
+mod tests {}

ratatui-core/src/layout/margin.rs

@@ -0,0 +1,44 @@
+use std::fmt;
+
+#[derive(Debug, Default, Clone, Copy, Eq, PartialEq, Hash)]
+#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
+pub struct Margin {
+    pub horizontal: u16,
+    pub vertical: u16,
+}
+
+impl Margin {
+    pub const fn new(horizontal: u16, vertical: u16) -> Self {
+        Self {
+            horizontal,
+            vertical,
+        }
+    }
+}
+
+impl fmt::Display for Margin {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "{}x{}", self.horizontal, self.vertical)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn margin_to_string() {
+        assert_eq!(Margin::new(1, 2).to_string(), "1x2");
+    }
+
+    #[test]
+    fn margin_new() {
+        assert_eq!(
+            Margin::new(1, 2),
+            Margin {
+                horizontal: 1,
+                vertical: 2
+            }
+        );
+    }
+}

ratatui-core/src/layout/position.rs

@@ -0,0 +1,115 @@
+#![warn(missing_docs)]
+use std::fmt;
+
+use crate::layout::Rect;
+
+/// Position in the terminal
+///
+/// The position is relative to the top left corner of the terminal window, with the top left corner
+/// being (0, 0). The x axis is horizontal increasing to the right, and the y axis is vertical
+/// increasing downwards.
+///
+/// # Examples
+///
+/// ```
+/// use ratatui_core::layout::{Position, Rect};
+///
+/// // the following are all equivalent
+/// let position = Position { x: 1, y: 2 };
+/// let position = Position::new(1, 2);
+/// let position = Position::from((1, 2));
+/// let position = Position::from(Rect::new(1, 2, 3, 4));
+///
+/// // position can be converted back into the components when needed
+/// let (x, y) = position.into();
+/// ```
+#[derive(Debug, Default, Copy, Clone, PartialEq, Eq, Ord, PartialOrd, Hash)]
+#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
+pub struct Position {
+    /// The x coordinate of the position
+    ///
+    /// The x coordinate is relative to the left edge of the terminal window, with the left edge
+    /// being 0.
+    pub x: u16,
+
+    /// The y coordinate of the position
+    ///
+    /// The y coordinate is relative to the top edge of the terminal window, with the top edge
+    /// being 0.
+    pub y: u16,
+}
+
+impl Position {
+    /// Position at the origin, the top left edge at 0,0
+    pub const ORIGIN: Self = Self { x: 0, y: 0 };
+
+    /// Create a new position
+    pub const fn new(x: u16, y: u16) -> Self {
+        Self { x, y }
+    }
+}
+
+impl From<(u16, u16)> for Position {
+    fn from((x, y): (u16, u16)) -> Self {
+        Self { x, y }
+    }
+}
+
+impl From<Position> for (u16, u16) {
+    fn from(position: Position) -> Self {
+        (position.x, position.y)
+    }
+}
+
+impl From<Rect> for Position {
+    fn from(rect: Rect) -> Self {
+        rect.as_position()
+    }
+}
+
+impl fmt::Display for Position {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        write!(f, "({}, {})", self.x, self.y)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn new() {
+        let position = Position::new(1, 2);
+        assert_eq!(position.x, 1);
+        assert_eq!(position.y, 2);
+    }
+
+    #[test]
+    fn from_tuple() {
+        let position = Position::from((1, 2));
+        assert_eq!(position.x, 1);
+        assert_eq!(position.y, 2);
+    }
+
+    #[test]
+    fn into_tuple() {
+        let position = Position::new(1, 2);
+        let (x, y) = position.into();
+        assert_eq!(x, 1);
+        assert_eq!(y, 2);
+    }
+
+    #[test]
+    fn from_rect() {
+        let rect = Rect::new(1, 2, 3, 4);
+        let position = Position::from(rect);
+        assert_eq!(position.x, 1);
+        assert_eq!(position.y, 2);
+    }
+
+    #[test]
+    fn to_string() {
+        let position = Position::new(1, 2);
+        assert_eq!(position.to_string(), "(1, 2)");
+    }
+}

ratatui-core/src/layout/rect.rs

@@ -0,0 +1,646 @@
+#![warn(missing_docs)]
+use std::{
+    cmp::{max, min},
+    fmt,
+};
+
+use crate::layout::{Margin, Position, Size};
+
+mod iter;
+pub use iter::*;
+
+/// A Rectangular area.
+///
+/// A simple rectangle used in the computation of the layout and to give widgets a hint about the
+/// area they are supposed to render to.
+#[derive(Debug, Default, Clone, Copy, Eq, PartialEq, Hash)]
+#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
+pub struct Rect {
+    /// The x coordinate of the top left corner of the `Rect`.
+    pub x: u16,
+    /// The y coordinate of the top left corner of the `Rect`.
+    pub y: u16,
+    /// The width of the `Rect`.
+    pub width: u16,
+    /// The height of the `Rect`.
+    pub height: u16,
+}
+
+/// Amounts by which to move a [`Rect`](crate::layout::Rect).
+///
+/// Positive numbers move to the right/bottom and negative to the left/top.
+///
+/// See [`Rect::offset`]
+#[derive(Debug, Default, Clone, Copy, Eq, PartialEq, Hash)]
+#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
+pub struct Offset {
+    /// How much to move on the X axis
+    pub x: i32,
+    /// How much to move on the Y axis
+    pub y: i32,
+}
+
+impl fmt::Display for Rect {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "{}x{}+{}+{}", self.width, self.height, self.x, self.y)
+    }
+}
+
+impl Rect {
+    /// A zero sized Rect at position 0,0
+    pub const ZERO: Self = Self {
+        x: 0,
+        y: 0,
+        width: 0,
+        height: 0,
+    };
+
+    /// Creates a new `Rect`, with width and height limited to keep both bounds within `u16`.
+    ///
+    /// If the width or height would cause the right or bottom coordinate to be larger than the
+    /// maximum value of `u16`, the width or height will be clamped to keep the right or bottom
+    /// coordinate within `u16`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use ratatui_core::layout::Rect;
+    ///
+    /// let rect = Rect::new(1, 2, 3, 4);
+    /// ```
+    pub const fn new(x: u16, y: u16, width: u16, height: u16) -> Self {
+        // these calculations avoid using min so that this function can be const
+        let max_width = u16::MAX - x;
+        let max_height = u16::MAX - y;
+        let width = if width > max_width { max_width } else { width };
+        let height = if height > max_height {
+            max_height
+        } else {
+            height
+        };
+        Self {
+            x,
+            y,
+            width,
+            height,
+        }
+    }
+
+    /// The area of the `Rect`. If the area is larger than the maximum value of `u16`, it will be
+    /// clamped to `u16::MAX`.
+    pub const fn area(self) -> u32 {
+        (self.width as u32) * (self.height as u32)
+    }
+
+    /// Returns true if the `Rect` has no area.
+    pub const fn is_empty(self) -> bool {
+        self.width == 0 || self.height == 0
+    }
+
+    /// Returns the left coordinate of the `Rect`.
+    pub const fn left(self) -> u16 {
+        self.x
+    }
+
+    /// Returns the right coordinate of the `Rect`. This is the first coordinate outside of the
+    /// `Rect`.
+    ///
+    /// If the right coordinate is larger than the maximum value of u16, it will be clamped to
+    /// `u16::MAX`.
+    pub const fn right(self) -> u16 {
+        self.x.saturating_add(self.width)
+    }
+
+    /// Returns the top coordinate of the `Rect`.
+    pub const fn top(self) -> u16 {
+        self.y
+    }
+
+    /// Returns the bottom coordinate of the `Rect`. This is the first coordinate outside of the
+    /// `Rect`.
+    ///
+    /// If the bottom coordinate is larger than the maximum value of u16, it will be clamped to
+    /// `u16::MAX`.
+    pub const fn bottom(self) -> u16 {
+        self.y.saturating_add(self.height)
+    }
+
+    /// Returns a new `Rect` inside the current one, with the given margin on each side.
+    ///
+    /// If the margin is larger than the `Rect`, the returned `Rect` will have no area.
+    #[must_use = "method returns the modified value"]
+    pub const fn inner(self, margin: Margin) -> Self {
+        let doubled_margin_horizontal = margin.horizontal.saturating_mul(2);
+        let doubled_margin_vertical = margin.vertical.saturating_mul(2);
+
+        if self.width < doubled_margin_horizontal || self.height < doubled_margin_vertical {
+            Self::ZERO
+        } else {
+            Self {
+                x: self.x.saturating_add(margin.horizontal),
+                y: self.y.saturating_add(margin.vertical),
+                width: self.width.saturating_sub(doubled_margin_horizontal),
+                height: self.height.saturating_sub(doubled_margin_vertical),
+            }
+        }
+    }
+
+    /// Moves the `Rect` without modifying its size.
+    ///
+    /// Moves the `Rect` according to the given offset without modifying its [`width`](Rect::width)
+    /// or [`height`](Rect::height).
+    /// - Positive `x` moves the whole `Rect` to the right, negative to the left.
+    /// - Positive `y` moves the whole `Rect` to the bottom, negative to the top.
+    ///
+    /// See [`Offset`] for details.
+    #[must_use = "method returns the modified value"]
+    pub fn offset(self, offset: Offset) -> Self {
+        Self {
+            x: i32::from(self.x)
+                .saturating_add(offset.x)
+                .clamp(0, i32::from(u16::MAX - self.width)) as u16,
+            y: i32::from(self.y)
+                .saturating_add(offset.y)
+                .clamp(0, i32::from(u16::MAX - self.height)) as u16,
+            ..self
+        }
+    }
+
+    /// Returns a new `Rect` that contains both the current one and the given one.
+    #[must_use = "method returns the modified value"]
+    pub fn union(self, other: Self) -> Self {
+        let x1 = min(self.x, other.x);
+        let y1 = min(self.y, other.y);
+        let x2 = max(self.right(), other.right());
+        let y2 = max(self.bottom(), other.bottom());
+        Self {
+            x: x1,
+            y: y1,
+            width: x2.saturating_sub(x1),
+            height: y2.saturating_sub(y1),
+        }
+    }
+
+    /// Returns a new `Rect` that is the intersection of the current one and the given one.
+    ///
+    /// If the two `Rect`s do not intersect, the returned `Rect` will have no area.
+    #[must_use = "method returns the modified value"]
+    pub fn intersection(self, other: Self) -> Self {
+        let x1 = max(self.x, other.x);
+        let y1 = max(self.y, other.y);
+        let x2 = min(self.right(), other.right());
+        let y2 = min(self.bottom(), other.bottom());
+        Self {
+            x: x1,
+            y: y1,
+            width: x2.saturating_sub(x1),
+            height: y2.saturating_sub(y1),
+        }
+    }
+
+    /// Returns true if the two `Rect`s intersect.
+    pub const fn intersects(self, other: Self) -> bool {
+        self.x < other.right()
+            && self.right() > other.x
+            && self.y < other.bottom()
+            && self.bottom() > other.y
+    }
+
+    /// Returns true if the given position is inside the `Rect`.
+    ///
+    /// The position is considered inside the `Rect` if it is on the `Rect`'s border.
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// use ratatui_core::layout::{Position, Rect};
+    ///
+    /// let rect = Rect::new(1, 2, 3, 4);
+    /// assert!(rect.contains(Position { x: 1, y: 2 }));
+    /// ````
+    pub const fn contains(self, position: Position) -> bool {
+        position.x >= self.x
+            && position.x < self.right()
+            && position.y >= self.y
+            && position.y < self.bottom()
+    }
+
+    /// Clamp this `Rect` to fit inside the other `Rect`.
+    ///
+    /// If the width or height of this `Rect` is larger than the other `Rect`, it will be clamped to
+    /// the other `Rect`'s width or height.
+    ///
+    /// If the left or top coordinate of this `Rect` is smaller than the other `Rect`, it will be
+    /// clamped to the other `Rect`'s left or top coordinate.
+    ///
+    /// If the right or bottom coordinate of this `Rect` is larger than the other `Rect`, it will be
+    /// clamped to the other `Rect`'s right or bottom coordinate.
+    ///
+    /// This is different from [`Rect::intersection`] because it will move this `Rect` to fit inside
+    /// the other `Rect`, while [`Rect::intersection`] instead would keep this `Rect`'s position and
+    /// truncate its size to only that which is inside the other `Rect`.
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// use ratatui_core::layout::Rect;
+    ///
+    /// 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 {
+        let width = self.width.min(other.width);
+        let height = self.height.min(other.height);
+        let x = self.x.clamp(other.x, other.right().saturating_sub(width));
+        let y = self.y.clamp(other.y, other.bottom().saturating_sub(height));
+        Self::new(x, y, width, height)
+    }
+
+    /// An iterator over rows within the `Rect`.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use ratatui_core::{buffer::Buffer, layout::Rect, text::Line, widgets::Widget};
+    ///
+    /// fn render(area: Rect, buf: &mut Buffer) {
+    ///     for row in area.rows() {
+    ///         Line::raw("Hello, world!").render(row, buf);
+    ///     }
+    /// }
+    /// ```
+    pub const fn rows(self) -> Rows {
+        Rows::new(self)
+    }
+
+    /// An iterator over columns within the `Rect`.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use ratatui_core::{buffer::Buffer, layout::Rect, text::Text, widgets::Widget};
+    ///
+    /// fn render(area: Rect, buf: &mut Buffer) {
+    ///     for (i, column) in area.columns().enumerate() {
+    ///         Text::from(format!("{}", i)).render(column, buf);
+    ///     }
+    /// }
+    /// ```
+    pub const fn columns(self) -> Columns {
+        Columns::new(self)
+    }
+
+    /// An iterator over the positions within the `Rect`.
+    ///
+    /// The positions are returned in a row-major order (left-to-right, top-to-bottom).
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use ratatui_core::{buffer::Buffer, layout::Rect};
+    ///
+    /// fn render(area: Rect, buf: &mut Buffer) {
+    ///     for position in area.positions() {
+    ///         buf[(position.x, position.y)].set_symbol("x");
+    ///     }
+    /// }
+    /// ```
+    pub const fn positions(self) -> Positions {
+        Positions::new(self)
+    }
+
+    /// Returns a [`Position`] with the same coordinates as this `Rect`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use ratatui_core::layout::Rect;
+    ///
+    /// let rect = Rect::new(1, 2, 3, 4);
+    /// let position = rect.as_position();
+    /// ````
+    pub const fn as_position(self) -> Position {
+        Position {
+            x: self.x,
+            y: self.y,
+        }
+    }
+
+    /// Converts the `Rect` into a size struct.
+    pub const fn as_size(self) -> Size {
+        Size {
+            width: self.width,
+            height: self.height,
+        }
+    }
+
+    /// indents the x value of the `Rect` by a given `offset`
+    ///
+    /// This is pub(crate) for now as we need to stabilize the naming / design of this API.
+    #[must_use]
+    pub(crate) const fn indent_x(self, offset: u16) -> Self {
+        Self {
+            x: self.x.saturating_add(offset),
+            width: self.width.saturating_sub(offset),
+            ..self
+        }
+    }
+}
+
+impl From<(Position, Size)> for Rect {
+    fn from((position, size): (Position, Size)) -> Self {
+        Self {
+            x: position.x,
+            y: position.y,
+            width: size.width,
+            height: size.height,
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use rstest::rstest;
+
+    use super::*;
+    use crate::layout::{Constraint, Layout};
+
+    #[test]
+    fn to_string() {
+        assert_eq!(Rect::new(1, 2, 3, 4).to_string(), "3x4+1+2");
+    }
+
+    #[test]
+    fn new() {
+        assert_eq!(
+            Rect::new(1, 2, 3, 4),
+            Rect {
+                x: 1,
+                y: 2,
+                width: 3,
+                height: 4
+            }
+        );
+    }
+
+    #[test]
+    fn area() {
+        assert_eq!(Rect::new(1, 2, 3, 4).area(), 12);
+    }
+
+    #[test]
+    fn is_empty() {
+        assert!(!Rect::new(1, 2, 3, 4).is_empty());
+        assert!(Rect::new(1, 2, 0, 4).is_empty());
+        assert!(Rect::new(1, 2, 3, 0).is_empty());
+    }
+
+    #[test]
+    fn left() {
+        assert_eq!(Rect::new(1, 2, 3, 4).left(), 1);
+    }
+
+    #[test]
+    fn right() {
+        assert_eq!(Rect::new(1, 2, 3, 4).right(), 4);
+    }
+
+    #[test]
+    fn top() {
+        assert_eq!(Rect::new(1, 2, 3, 4).top(), 2);
+    }
+
+    #[test]
+    fn bottom() {
+        assert_eq!(Rect::new(1, 2, 3, 4).bottom(), 6);
+    }
+
+    #[test]
+    fn inner() {
+        assert_eq!(
+            Rect::new(1, 2, 3, 4).inner(Margin::new(1, 2)),
+            Rect::new(2, 4, 1, 0)
+        );
+    }
+
+    #[test]
+    fn offset() {
+        assert_eq!(
+            Rect::new(1, 2, 3, 4).offset(Offset { x: 5, y: 6 }),
+            Rect::new(6, 8, 3, 4),
+        );
+    }
+
+    #[test]
+    fn negative_offset() {
+        assert_eq!(
+            Rect::new(4, 3, 3, 4).offset(Offset { x: -2, y: -1 }),
+            Rect::new(2, 2, 3, 4),
+        );
+    }
+
+    #[test]
+    fn negative_offset_saturate() {
+        assert_eq!(
+            Rect::new(1, 2, 3, 4).offset(Offset { x: -5, y: -6 }),
+            Rect::new(0, 0, 3, 4),
+        );
+    }
+
+    /// Offsets a [`Rect`] making it go outside [`u16::MAX`], it should keep its size.
+    #[test]
+    fn offset_saturate_max() {
+        assert_eq!(
+            Rect::new(u16::MAX - 500, u16::MAX - 500, 100, 100).offset(Offset { x: 1000, y: 1000 }),
+            Rect::new(u16::MAX - 100, u16::MAX - 100, 100, 100),
+        );
+    }
+
+    #[test]
+    fn union() {
+        assert_eq!(
+            Rect::new(1, 2, 3, 4).union(Rect::new(2, 3, 4, 5)),
+            Rect::new(1, 2, 5, 6)
+        );
+    }
+
+    #[test]
+    fn intersection() {
+        assert_eq!(
+            Rect::new(1, 2, 3, 4).intersection(Rect::new(2, 3, 4, 5)),
+            Rect::new(2, 3, 2, 3)
+        );
+    }
+
+    #[test]
+    fn intersection_underflow() {
+        assert_eq!(
+            Rect::new(1, 1, 2, 2).intersection(Rect::new(4, 4, 2, 2)),
+            Rect::new(4, 4, 0, 0)
+        );
+    }
+
+    #[test]
+    fn intersects() {
+        assert!(Rect::new(1, 2, 3, 4).intersects(Rect::new(2, 3, 4, 5)));
+        assert!(!Rect::new(1, 2, 3, 4).intersects(Rect::new(5, 6, 7, 8)));
+    }
+
+    // the bounds of this rect are x: [1..=3], y: [2..=5]
+    #[rstest]
+    #[case::inside_top_left(Rect::new(1, 2, 3, 4), Position { x: 1, y: 2 }, true)]
+    #[case::inside_top_right(Rect::new(1, 2, 3, 4), Position { x: 3, y: 2 }, true)]
+    #[case::inside_bottom_left(Rect::new(1, 2, 3, 4), Position { x: 1, y: 5 }, true)]
+    #[case::inside_bottom_right(Rect::new(1, 2, 3, 4), Position { x: 3, y: 5 }, true)]
+    #[case::outside_left(Rect::new(1, 2, 3, 4), Position { x: 0, y: 2 }, false)]
+    #[case::outside_right(Rect::new(1, 2, 3, 4), Position { x: 4, y: 2 }, false)]
+    #[case::outside_top(Rect::new(1, 2, 3, 4), Position { x: 1, y: 1 }, false)]
+    #[case::outside_bottom(Rect::new(1, 2, 3, 4), Position { x: 1, y: 6 }, false)]
+    #[case::outside_top_left(Rect::new(1, 2, 3, 4), Position { x: 0, y: 1 }, false)]
+    #[case::outside_bottom_right(Rect::new(1, 2, 3, 4), Position { x: 4, y: 6 }, false)]
+    fn contains(#[case] rect: Rect, #[case] position: Position, #[case] expected: bool) {
+        assert_eq!(
+            rect.contains(position),
+            expected,
+            "rect: {rect:?}, position: {position:?}",
+        );
+    }
+
+    #[test]
+    fn size_truncation() {
+        assert_eq!(
+            Rect::new(u16::MAX - 100, u16::MAX - 1000, 200, 2000),
+            Rect {
+                x: u16::MAX - 100,
+                y: u16::MAX - 1000,
+                width: 100,
+                height: 1000
+            }
+        );
+    }
+
+    #[test]
+    fn size_preservation() {
+        assert_eq!(
+            Rect::new(u16::MAX - 100, u16::MAX - 1000, 100, 1000),
+            Rect {
+                x: u16::MAX - 100,
+                y: u16::MAX - 1000,
+                width: 100,
+                height: 1000
+            }
+        );
+    }
+
+    #[test]
+    fn can_be_const() {
+        const RECT: Rect = Rect {
+            x: 0,
+            y: 0,
+            width: 10,
+            height: 10,
+        };
+        const _AREA: u32 = RECT.area();
+        const _LEFT: u16 = RECT.left();
+        const _RIGHT: u16 = RECT.right();
+        const _TOP: u16 = RECT.top();
+        const _BOTTOM: u16 = RECT.bottom();
+        assert!(RECT.intersects(RECT));
+    }
+
+    #[test]
+    fn split() {
+        let [a, b] = Layout::horizontal([Constraint::Percentage(50), Constraint::Percentage(50)])
+            .areas(Rect::new(0, 0, 2, 1));
+        assert_eq!(a, Rect::new(0, 0, 1, 1));
+        assert_eq!(b, Rect::new(1, 0, 1, 1));
+    }
+
+    #[test]
+    #[should_panic(expected = "invalid number of rects")]
+    fn split_invalid_number_of_recs() {
+        let layout = Layout::horizontal([Constraint::Percentage(50), Constraint::Percentage(50)]);
+        let [_a, _b, _c] = layout.areas(Rect::new(0, 0, 2, 1));
+    }
+
+    #[rstest]
+    #[case::inside(Rect::new(20, 20, 10, 10), Rect::new(20, 20, 10, 10))]
+    #[case::up_left(Rect::new(5, 5, 10, 10), Rect::new(10, 10, 10, 10))]
+    #[case::up(Rect::new(20, 5, 10, 10), Rect::new(20, 10, 10, 10))]
+    #[case::up_right(Rect::new(105, 5, 10, 10), Rect::new(100, 10, 10, 10))]
+    #[case::left(Rect::new(5, 20, 10, 10), Rect::new(10, 20, 10, 10))]
+    #[case::right(Rect::new(105, 20, 10, 10), Rect::new(100, 20, 10, 10))]
+    #[case::down_left(Rect::new(5, 105, 10, 10), Rect::new(10, 100, 10, 10))]
+    #[case::down(Rect::new(20, 105, 10, 10), Rect::new(20, 100, 10, 10))]
+    #[case::down_right(Rect::new(105, 105, 10, 10), Rect::new(100, 100, 10, 10))]
+    #[case::too_wide(Rect::new(5, 20, 200, 10), Rect::new(10, 20, 100, 10))]
+    #[case::too_tall(Rect::new(20, 5, 10, 200), Rect::new(20, 10, 10, 100))]
+    #[case::too_large(Rect::new(0, 0, 200, 200), Rect::new(10, 10, 100, 100))]
+    fn clamp(#[case] rect: Rect, #[case] expected: Rect) {
+        let other = Rect::new(10, 10, 100, 100);
+        assert_eq!(rect.clamp(other), expected);
+    }
+
+    #[test]
+    fn rows() {
+        let area = Rect::new(0, 0, 3, 2);
+        let rows: Vec<Rect> = area.rows().collect();
+
+        let expected_rows: Vec<Rect> = vec![Rect::new(0, 0, 3, 1), Rect::new(0, 1, 3, 1)];
+
+        assert_eq!(rows, expected_rows);
+    }
+
+    #[test]
+    fn columns() {
+        let area = Rect::new(0, 0, 3, 2);
+        let columns: Vec<Rect> = area.columns().collect();
+
+        let expected_columns: Vec<Rect> = vec![
+            Rect::new(0, 0, 1, 2),
+            Rect::new(1, 0, 1, 2),
+            Rect::new(2, 0, 1, 2),
+        ];
+
+        assert_eq!(columns, expected_columns);
+    }
+
+    #[test]
+    fn as_position() {
+        let rect = Rect::new(1, 2, 3, 4);
+        let position = rect.as_position();
+        assert_eq!(position.x, 1);
+        assert_eq!(position.y, 2);
+    }
+
+    #[test]
+    fn as_size() {
+        assert_eq!(
+            Rect::new(1, 2, 3, 4).as_size(),
+            Size {
+                width: 3,
+                height: 4
+            }
+        );
+    }
+
+    #[test]
+    fn from_position_and_size() {
+        let position = Position { x: 1, y: 2 };
+        let size = Size {
+            width: 3,
+            height: 4,
+        };
+        assert_eq!(
+            Rect::from((position, size)),
+            Rect {
+                x: 1,
+                y: 2,
+                width: 3,
+                height: 4
+            }
+        );
+    }
+}

ratatui-core/src/layout/rect/iter.rs

@@ -0,0 +1,329 @@
+use crate::layout::{Position, Rect};
+
+/// An iterator over rows within a `Rect`.
+pub struct Rows {
+    /// The `Rect` associated with the rows.
+    rect: Rect,
+    /// The y coordinate of the row within the `Rect` when iterating forwards.
+    current_row_fwd: u16,
+    /// The y coordinate of the row within the `Rect` when iterating backwards.
+    current_row_back: u16,
+}
+
+impl Rows {
+    /// Creates a new `Rows` iterator.
+    pub const fn new(rect: Rect) -> Self {
+        Self {
+            rect,
+            current_row_fwd: rect.y,
+            current_row_back: rect.bottom(),
+        }
+    }
+}
+
+impl Iterator for Rows {
+    type Item = Rect;
+
+    /// Retrieves the next row within the `Rect`.
+    ///
+    /// Returns `None` when there are no more rows to iterate through.
+    fn next(&mut self) -> Option<Self::Item> {
+        if self.current_row_fwd >= self.current_row_back {
+            return None;
+        }
+        let row = Rect::new(self.rect.x, self.current_row_fwd, self.rect.width, 1);
+        self.current_row_fwd += 1;
+        Some(row)
+    }
+
+    fn size_hint(&self) -> (usize, Option<usize>) {
+        let start_count = self.current_row_fwd.saturating_sub(self.rect.top());
+        let end_count = self.rect.bottom().saturating_sub(self.current_row_back);
+        let count = self
+            .rect
+            .height
+            .saturating_sub(start_count)
+            .saturating_sub(end_count) as usize;
+        (count, Some(count))
+    }
+}
+
+impl DoubleEndedIterator for Rows {
+    /// Retrieves the previous row within the `Rect`.
+    ///
+    /// Returns `None` when there are no more rows to iterate through.
+    fn next_back(&mut self) -> Option<Self::Item> {
+        if self.current_row_back <= self.current_row_fwd {
+            return None;
+        }
+        self.current_row_back -= 1;
+        let row = Rect::new(self.rect.x, self.current_row_back, self.rect.width, 1);
+        Some(row)
+    }
+}
+
+/// An iterator over columns within a `Rect`.
+pub struct Columns {
+    /// The `Rect` associated with the columns.
+    rect: Rect,
+    /// The x coordinate of the column within the `Rect` when iterating forwards.
+    current_column_fwd: u16,
+    /// The x coordinate of the column within the `Rect` when iterating backwards.
+    current_column_back: u16,
+}
+
+impl Columns {
+    /// Creates a new `Columns` iterator.
+    pub const fn new(rect: Rect) -> Self {
+        Self {
+            rect,
+            current_column_fwd: rect.x,
+            current_column_back: rect.right(),
+        }
+    }
+}
+
+impl Iterator for Columns {
+    type Item = Rect;
+
+    /// Retrieves the next column within the `Rect`.
+    ///
+    /// Returns `None` when there are no more columns to iterate through.
+    fn next(&mut self) -> Option<Self::Item> {
+        if self.current_column_fwd >= self.current_column_back {
+            return None;
+        }
+        let column = Rect::new(self.current_column_fwd, self.rect.y, 1, self.rect.height);
+        self.current_column_fwd += 1;
+        Some(column)
+    }
+
+    fn size_hint(&self) -> (usize, Option<usize>) {
+        let start_count = self.current_column_fwd.saturating_sub(self.rect.left());
+        let end_count = self.rect.right().saturating_sub(self.current_column_back);
+        let count = self
+            .rect
+            .width
+            .saturating_sub(start_count)
+            .saturating_sub(end_count) as usize;
+        (count, Some(count))
+    }
+}
+
+impl DoubleEndedIterator for Columns {
+    /// Retrieves the previous column within the `Rect`.
+    ///
+    /// Returns `None` when there are no more columns to iterate through.
+    fn next_back(&mut self) -> Option<Self::Item> {
+        if self.current_column_back <= self.current_column_fwd {
+            return None;
+        }
+        self.current_column_back -= 1;
+        let column = Rect::new(self.current_column_back, self.rect.y, 1, self.rect.height);
+        Some(column)
+    }
+}
+
+/// An iterator over positions within a `Rect`.
+///
+/// The iterator will yield all positions within the `Rect` in a row-major order.
+pub struct Positions {
+    /// The `Rect` associated with the positions.
+    rect: Rect,
+    /// The current position within the `Rect`.
+    current_position: Position,
+}
+
+impl Positions {
+    /// Creates a new `Positions` iterator.
+    pub const fn new(rect: Rect) -> Self {
+        Self {
+            rect,
+            current_position: Position::new(rect.x, rect.y),
+        }
+    }
+}
+
+impl Iterator for Positions {
+    type Item = Position;
+
+    /// Retrieves the next position within the `Rect`.
+    ///
+    /// Returns `None` when there are no more positions to iterate through.
+    fn next(&mut self) -> Option<Self::Item> {
+        if self.current_position.y >= self.rect.bottom() {
+            return None;
+        }
+        let position = self.current_position;
+        self.current_position.x += 1;
+        if self.current_position.x >= self.rect.right() {
+            self.current_position.x = self.rect.x;
+            self.current_position.y += 1;
+        }
+        Some(position)
+    }
+
+    fn size_hint(&self) -> (usize, Option<usize>) {
+        let row_count = self.rect.bottom().saturating_sub(self.current_position.y);
+        if row_count == 0 {
+            return (0, Some(0));
+        }
+        let column_count = self.rect.right().saturating_sub(self.current_position.x);
+        // subtract 1 from the row count to account for the current row
+        let count = (row_count - 1)
+            .saturating_mul(self.rect.width)
+            .saturating_add(column_count) as usize;
+        (count, Some(count))
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn rows() {
+        let rect = Rect::new(0, 0, 2, 3);
+        let mut rows = Rows::new(rect);
+        assert_eq!(rows.size_hint(), (3, Some(3)));
+        assert_eq!(rows.next(), Some(Rect::new(0, 0, 2, 1)));
+        assert_eq!(rows.size_hint(), (2, Some(2)));
+        assert_eq!(rows.next(), Some(Rect::new(0, 1, 2, 1)));
+        assert_eq!(rows.size_hint(), (1, Some(1)));
+        assert_eq!(rows.next(), Some(Rect::new(0, 2, 2, 1)));
+        assert_eq!(rows.size_hint(), (0, Some(0)));
+        assert_eq!(rows.next(), None);
+        assert_eq!(rows.size_hint(), (0, Some(0)));
+        assert_eq!(rows.next_back(), None);
+        assert_eq!(rows.size_hint(), (0, Some(0)));
+    }
+
+    #[test]
+    fn rows_back() {
+        let rect = Rect::new(0, 0, 2, 3);
+        let mut rows = Rows::new(rect);
+        assert_eq!(rows.size_hint(), (3, Some(3)));
+        assert_eq!(rows.next_back(), Some(Rect::new(0, 2, 2, 1)));
+        assert_eq!(rows.size_hint(), (2, Some(2)));
+        assert_eq!(rows.next_back(), Some(Rect::new(0, 1, 2, 1)));
+        assert_eq!(rows.size_hint(), (1, Some(1)));
+        assert_eq!(rows.next_back(), Some(Rect::new(0, 0, 2, 1)));
+        assert_eq!(rows.size_hint(), (0, Some(0)));
+        assert_eq!(rows.next_back(), None);
+        assert_eq!(rows.size_hint(), (0, Some(0)));
+        assert_eq!(rows.next(), None);
+        assert_eq!(rows.size_hint(), (0, Some(0)));
+    }
+
+    #[test]
+    fn rows_meet_in_the_middle() {
+        let rect = Rect::new(0, 0, 2, 4);
+        let mut rows = Rows::new(rect);
+        assert_eq!(rows.size_hint(), (4, Some(4)));
+        assert_eq!(rows.next(), Some(Rect::new(0, 0, 2, 1)));
+        assert_eq!(rows.size_hint(), (3, Some(3)));
+        assert_eq!(rows.next_back(), Some(Rect::new(0, 3, 2, 1)));
+        assert_eq!(rows.size_hint(), (2, Some(2)));
+        assert_eq!(rows.next(), Some(Rect::new(0, 1, 2, 1)));
+        assert_eq!(rows.size_hint(), (1, Some(1)));
+        assert_eq!(rows.next_back(), Some(Rect::new(0, 2, 2, 1)));
+        assert_eq!(rows.size_hint(), (0, Some(0)));
+        assert_eq!(rows.next(), None);
+        assert_eq!(rows.size_hint(), (0, Some(0)));
+        assert_eq!(rows.next_back(), None);
+        assert_eq!(rows.size_hint(), (0, Some(0)));
+    }
+
+    #[test]
+    fn columns() {
+        let rect = Rect::new(0, 0, 3, 2);
+        let mut columns = Columns::new(rect);
+        assert_eq!(columns.size_hint(), (3, Some(3)));
+        assert_eq!(columns.next(), Some(Rect::new(0, 0, 1, 2)));
+        assert_eq!(columns.size_hint(), (2, Some(2)));
+        assert_eq!(columns.next(), Some(Rect::new(1, 0, 1, 2)));
+        assert_eq!(columns.size_hint(), (1, Some(1)));
+        assert_eq!(columns.next(), Some(Rect::new(2, 0, 1, 2)));
+        assert_eq!(columns.size_hint(), (0, Some(0)));
+        assert_eq!(columns.next(), None);
+        assert_eq!(columns.size_hint(), (0, Some(0)));
+        assert_eq!(columns.next_back(), None);
+        assert_eq!(columns.size_hint(), (0, Some(0)));
+    }
+
+    #[test]
+    fn columns_back() {
+        let rect = Rect::new(0, 0, 3, 2);
+        let mut columns = Columns::new(rect);
+        assert_eq!(columns.size_hint(), (3, Some(3)));
+        assert_eq!(columns.next_back(), Some(Rect::new(2, 0, 1, 2)));
+        assert_eq!(columns.size_hint(), (2, Some(2)));
+        assert_eq!(columns.next_back(), Some(Rect::new(1, 0, 1, 2)));
+        assert_eq!(columns.size_hint(), (1, Some(1)));
+        assert_eq!(columns.next_back(), Some(Rect::new(0, 0, 1, 2)));
+        assert_eq!(columns.size_hint(), (0, Some(0)));
+        assert_eq!(columns.next_back(), None);
+        assert_eq!(columns.size_hint(), (0, Some(0)));
+        assert_eq!(columns.next(), None);
+        assert_eq!(columns.size_hint(), (0, Some(0)));
+    }
+
+    #[test]
+    fn columns_meet_in_the_middle() {
+        let rect = Rect::new(0, 0, 4, 2);
+        let mut columns = Columns::new(rect);
+        assert_eq!(columns.size_hint(), (4, Some(4)));
+        assert_eq!(columns.next(), Some(Rect::new(0, 0, 1, 2)));
+        assert_eq!(columns.size_hint(), (3, Some(3)));
+        assert_eq!(columns.next_back(), Some(Rect::new(3, 0, 1, 2)));
+        assert_eq!(columns.size_hint(), (2, Some(2)));
+        assert_eq!(columns.next(), Some(Rect::new(1, 0, 1, 2)));
+        assert_eq!(columns.size_hint(), (1, Some(1)));
+        assert_eq!(columns.next_back(), Some(Rect::new(2, 0, 1, 2)));
+        assert_eq!(columns.size_hint(), (0, Some(0)));
+        assert_eq!(columns.next(), None);
+        assert_eq!(columns.size_hint(), (0, Some(0)));
+        assert_eq!(columns.next_back(), None);
+        assert_eq!(columns.size_hint(), (0, Some(0)));
+    }
+
+    /// We allow a total of `65536` columns in the range `(0..=65535)`.  In this test we iterate
+    /// forward and skip the first `65534` columns, and expect the next column to be `65535` and
+    /// the subsequent columns to be `None`.
+    #[test]
+    fn columns_max() {
+        let rect = Rect::new(0, 0, u16::MAX, 1);
+        let mut columns = Columns::new(rect).skip(usize::from(u16::MAX - 1));
+        assert_eq!(columns.next(), Some(Rect::new(u16::MAX - 1, 0, 1, 1)));
+        assert_eq!(columns.next(), None);
+    }
+
+    /// We allow a total of `65536` columns in the range `(0..=65535)`.  In this test we iterate
+    /// backward and skip the last `65534` columns, and expect the next column to be `0` and the
+    /// subsequent columns to be `None`.
+    #[test]
+    fn columns_min() {
+        let rect = Rect::new(0, 0, u16::MAX, 1);
+        let mut columns = Columns::new(rect).rev().skip(usize::from(u16::MAX - 1));
+        assert_eq!(columns.next(), Some(Rect::new(0, 0, 1, 1)));
+        assert_eq!(columns.next(), None);
+        assert_eq!(columns.next(), None);
+    }
+
+    #[test]
+    fn positions() {
+        let rect = Rect::new(0, 0, 2, 2);
+        let mut positions = Positions::new(rect);
+        assert_eq!(positions.size_hint(), (4, Some(4)));
+        assert_eq!(positions.next(), Some(Position::new(0, 0)));
+        assert_eq!(positions.size_hint(), (3, Some(3)));
+        assert_eq!(positions.next(), Some(Position::new(1, 0)));
+        assert_eq!(positions.size_hint(), (2, Some(2)));
+        assert_eq!(positions.next(), Some(Position::new(0, 1)));
+        assert_eq!(positions.size_hint(), (1, Some(1)));
+        assert_eq!(positions.next(), Some(Position::new(1, 1)));
+        assert_eq!(positions.size_hint(), (0, Some(0)));
+        assert_eq!(positions.next(), None);
+        assert_eq!(positions.size_hint(), (0, Some(0)));
+    }
+}

ratatui-core/src/layout/size.rs

@@ -0,0 +1,76 @@
+#![warn(missing_docs)]
+use std::fmt;
+
+use crate::layout::Rect;
+
+/// A simple size struct
+///
+/// The width and height are stored as `u16` values and represent the number of columns and rows
+/// respectively.
+#[derive(Debug, Default, Clone, Copy, Eq, PartialEq, Hash)]
+#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
+pub struct Size {
+    /// The width in columns
+    pub width: u16,
+    /// The height in rows
+    pub height: u16,
+}
+
+impl Size {
+    /// A zero sized Size
+    pub const ZERO: Self = Self::new(0, 0);
+
+    /// Create a new `Size` struct
+    pub const fn new(width: u16, height: u16) -> Self {
+        Self { width, height }
+    }
+}
+
+impl From<(u16, u16)> for Size {
+    fn from((width, height): (u16, u16)) -> Self {
+        Self { width, height }
+    }
+}
+
+impl From<Rect> for Size {
+    fn from(rect: Rect) -> Self {
+        rect.as_size()
+    }
+}
+
+impl fmt::Display for Size {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        write!(f, "{}x{}", self.width, self.height)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn new() {
+        let size = Size::new(10, 20);
+        assert_eq!(size.width, 10);
+        assert_eq!(size.height, 20);
+    }
+
+    #[test]
+    fn from_tuple() {
+        let size = Size::from((10, 20));
+        assert_eq!(size.width, 10);
+        assert_eq!(size.height, 20);
+    }
+
+    #[test]
+    fn from_rect() {
+        let size = Size::from(Rect::new(0, 0, 10, 20));
+        assert_eq!(size.width, 10);
+        assert_eq!(size.height, 20);
+    }
+
+    #[test]
+    fn display() {
+        assert_eq!(Size::new(10, 20).to_string(), "10x20");
+    }
+}

ratatui-core/src/lib.rs

@@ -0,0 +1,47 @@
+// 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 text;
+pub mod widgets;

ratatui-core/src/style.rs

@@ -0,0 +1,910 @@
+//! `style` contains the primitives used to control how your user interface will look.
+//!
+//! There are two ways to set styles:
+//! - Creating and using the [`Style`] struct. (e.g. `Style::new().fg(Color::Red)`).
+//! - Using style shorthands. (e.g. `"hello".red()`).
+//!
+//! # Using the `Style` struct
+//!
+//! This is the original approach to styling and likely the most common. This is useful when
+//! creating style variables to reuse, however the shorthands are often more convenient and
+//! readable for most use cases.
+//!
+//! ## Example
+//!
+//! ```
+//! use ratatui_core::{
+//!     style::{Color, Modifier, Style},
+//!     text::Span,
+//! };
+//!
+//! let heading_style = Style::new()
+//!     .fg(Color::Black)
+//!     .bg(Color::Green)
+//!     .add_modifier(Modifier::ITALIC | Modifier::BOLD);
+//! let span = Span::styled("hello", heading_style);
+//! ```
+//!
+//! # Using style shorthands
+//!
+//! Originally Ratatui only had the ability to set styles using the `Style` struct. This is still
+//! supported, but there are now shorthands for all the styles that can be set. These save you from
+//! having to create a `Style` struct every time you want to set a style.
+//!
+//! The shorthands are implemented in the [`Stylize`] trait which is automatically implemented for
+//! many types via the [`Styled`] trait. This means that you can use the shorthands on any type
+//! that implements [`Styled`]. E.g.:
+//! - Strings and string slices when styled return a [`Span`]
+//! - [`Span`]s can be styled again, which will merge the styles.
+//! - Many widget types can be styled directly rather than calling their `style()` method.
+//!
+//! See the [`Stylize`] and [`Styled`] traits for more information.
+//!
+//! ## Example
+//!
+//! ```
+//! use ratatui_core::{
+//!     style::{Color, Modifier, Style, Stylize},
+//!     text::{Span, Text},
+//! };
+//!
+//! assert_eq!(
+//!     "hello".red().on_blue().bold(),
+//!     Span::styled(
+//!         "hello",
+//!         Style::default()
+//!             .fg(Color::Red)
+//!             .bg(Color::Blue)
+//!             .add_modifier(Modifier::BOLD)
+//!     )
+//! );
+//!
+//! assert_eq!(
+//!     Text::from("hello").red().on_blue().bold(),
+//!     Text::from("hello").style(
+//!         Style::default()
+//!             .fg(Color::Red)
+//!             .bg(Color::Blue)
+//!             .add_modifier(Modifier::BOLD)
+//!     )
+//! );
+//! ```
+//!
+//! [`Span`]: crate::text::Span
+
+use std::fmt;
+
+use bitflags::bitflags;
+pub use color::{Color, ParseColorError};
+use stylize::ColorDebugKind;
+pub use stylize::{Styled, Stylize};
+
+mod color;
+pub mod palette;
+#[cfg(feature = "palette")]
+mod palette_conversion;
+mod stylize;
+
+bitflags! {
+    /// Modifier changes the way a piece of text is displayed.
+    ///
+    /// They are bitflags so they can easily be composed.
+    ///
+    /// `From<Modifier> for Style` is implemented so you can use `Modifier` anywhere that accepts
+    /// `Into<Style>`.
+    ///
+    /// ## Examples
+    ///
+    /// ```rust
+    /// use ratatui_core::style::Modifier;
+    ///
+    /// let m = Modifier::BOLD | Modifier::ITALIC;
+    /// ```
+    #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
+    #[derive(Default, Clone, Copy, Eq, PartialEq, Hash)]
+    pub struct Modifier: u16 {
+        const BOLD              = 0b0000_0000_0001;
+        const DIM               = 0b0000_0000_0010;
+        const ITALIC            = 0b0000_0000_0100;
+        const UNDERLINED        = 0b0000_0000_1000;
+        const SLOW_BLINK        = 0b0000_0001_0000;
+        const RAPID_BLINK       = 0b0000_0010_0000;
+        const REVERSED          = 0b0000_0100_0000;
+        const HIDDEN            = 0b0000_1000_0000;
+        const CROSSED_OUT       = 0b0001_0000_0000;
+    }
+}
+
+/// Implement the `Debug` trait for `Modifier` manually.
+///
+/// This will avoid printing the empty modifier as 'Borders(0x0)' and instead print it as 'NONE'.
+impl fmt::Debug for Modifier {
+    /// Format the modifier as `NONE` if the modifier is empty or as a list of flags separated by
+    /// `|` otherwise.
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        if self.is_empty() {
+            return write!(f, "NONE");
+        }
+        write!(f, "{}", self.0)
+    }
+}
+
+/// Style lets you control the main characteristics of the displayed elements.
+///
+/// ```rust
+/// use ratatui_core::style::{Color, Modifier, Style};
+///
+/// Style::default()
+///     .fg(Color::Black)
+///     .bg(Color::Green)
+///     .add_modifier(Modifier::ITALIC | Modifier::BOLD);
+/// ```
+///
+/// Styles can also be created with a [shorthand notation](crate::style#using-style-shorthands).
+///
+/// ```rust
+/// use ratatui_core::style::{Style, Stylize};
+///
+/// Style::new().black().on_green().italic().bold();
+/// ```
+///
+/// For more information about the style shorthands, see the [`Stylize`] trait.
+///
+/// We implement conversions from [`Color`] and [`Modifier`] to [`Style`] so you can use them
+/// anywhere that accepts `Into<Style>`.
+///
+/// ```rust
+/// use ratatui_core::{
+///     style::{Color, Modifier, Style},
+///     text::Line,
+/// };
+///
+/// Line::styled("hello", Style::new().fg(Color::Red));
+/// // simplifies to
+/// Line::styled("hello", Color::Red);
+///
+/// Line::styled("hello", Style::new().add_modifier(Modifier::BOLD));
+/// // simplifies to
+/// Line::styled("hello", Modifier::BOLD);
+/// ```
+///
+/// Styles represents an incremental change. If you apply the styles S1, S2, S3 to a cell of the
+/// terminal buffer, the style of this cell will be the result of the merge of S1, S2 and S3, not
+/// just S3.
+///
+/// ```rust
+/// use ratatui_core::{
+///     buffer::Buffer,
+///     layout::Rect,
+///     style::{Color, Modifier, Style},
+/// };
+///
+/// let styles = [
+///     Style::default()
+///         .fg(Color::Blue)
+///         .add_modifier(Modifier::BOLD | Modifier::ITALIC),
+///     Style::default()
+///         .bg(Color::Red)
+///         .add_modifier(Modifier::UNDERLINED),
+///     #[cfg(feature = "underline-color")]
+///     Style::default().underline_color(Color::Green),
+///     Style::default()
+///         .fg(Color::Yellow)
+///         .remove_modifier(Modifier::ITALIC),
+/// ];
+/// let mut buffer = Buffer::empty(Rect::new(0, 0, 1, 1));
+/// for style in &styles {
+///     buffer[(0, 0)].set_style(*style);
+/// }
+/// assert_eq!(
+///     Style {
+///         fg: Some(Color::Yellow),
+///         bg: Some(Color::Red),
+///         #[cfg(feature = "underline-color")]
+///         underline_color: Some(Color::Green),
+///         add_modifier: Modifier::BOLD | Modifier::UNDERLINED,
+///         sub_modifier: Modifier::empty(),
+///     },
+///     buffer[(0, 0)].style(),
+/// );
+/// ```
+///
+/// The default implementation returns a `Style` that does not modify anything. If you wish to
+/// reset all properties until that point use [`Style::reset`].
+///
+/// ```
+/// use ratatui_core::{
+///     buffer::Buffer,
+///     layout::Rect,
+///     style::{Color, Modifier, Style},
+/// };
+///
+/// let styles = [
+///     Style::default()
+///         .fg(Color::Blue)
+///         .add_modifier(Modifier::BOLD | Modifier::ITALIC),
+///     Style::reset().fg(Color::Yellow),
+/// ];
+/// let mut buffer = Buffer::empty(Rect::new(0, 0, 1, 1));
+/// for style in &styles {
+///     buffer[(0, 0)].set_style(*style);
+/// }
+/// assert_eq!(
+///     Style {
+///         fg: Some(Color::Yellow),
+///         bg: Some(Color::Reset),
+///         #[cfg(feature = "underline-color")]
+///         underline_color: Some(Color::Reset),
+///         add_modifier: Modifier::empty(),
+///         sub_modifier: Modifier::empty(),
+///     },
+///     buffer[(0, 0)].style(),
+/// );
+/// ```
+#[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,
+}
+
+/// A custom debug implementation that prints only the fields that are not the default, and unwraps
+/// the `Option`s.
+impl fmt::Debug for Style {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        f.write_str("Style::new()")?;
+        self.fmt_stylize(f)?;
+        Ok(())
+    }
+}
+
+impl Styled for Style {
+    type Item = Self;
+
+    fn style(&self) -> Style {
+        *self
+    }
+
+    fn set_style<S: Into<Self>>(self, style: S) -> Self::Item {
+        self.patch(style)
+    }
+}
+
+impl Style {
+    /// Returns a `Style` with default properties.
+    pub const fn new() -> Self {
+        Self {
+            fg: None,
+            bg: None,
+            #[cfg(feature = "underline-color")]
+            underline_color: None,
+            add_modifier: Modifier::empty(),
+            sub_modifier: Modifier::empty(),
+        }
+    }
+
+    /// Returns a `Style` resetting all properties.
+    pub const fn reset() -> Self {
+        Self {
+            fg: Some(Color::Reset),
+            bg: Some(Color::Reset),
+            #[cfg(feature = "underline-color")]
+            underline_color: Some(Color::Reset),
+            add_modifier: Modifier::empty(),
+            sub_modifier: Modifier::all(),
+        }
+    }
+
+    /// Changes the foreground color.
+    ///
+    /// ## Examples
+    ///
+    /// ```rust
+    /// use ratatui_core::style::{Color, Style};
+    ///
+    /// let style = Style::default().fg(Color::Blue);
+    /// let diff = Style::default().fg(Color::Red);
+    /// assert_eq!(style.patch(diff), Style::default().fg(Color::Red));
+    /// ```
+    #[must_use = "`fg` returns the modified style without modifying the original"]
+    pub const fn fg(mut self, color: Color) -> Self {
+        self.fg = Some(color);
+        self
+    }
+
+    /// Changes the background color.
+    ///
+    /// ## Examples
+    ///
+    /// ```rust
+    /// use ratatui_core::style::{Color, Style};
+    ///
+    /// let style = Style::default().bg(Color::Blue);
+    /// let diff = Style::default().bg(Color::Red);
+    /// assert_eq!(style.patch(diff), Style::default().bg(Color::Red));
+    /// ```
+    #[must_use = "`bg` returns the modified style without modifying the original"]
+    pub const fn bg(mut self, color: Color) -> Self {
+        self.bg = Some(color);
+        self
+    }
+
+    /// Changes the underline color. The text must be underlined with a modifier for this to work.
+    ///
+    /// This uses a non-standard ANSI escape sequence. It is supported by most terminal emulators,
+    /// but is only implemented in the crossterm backend and enabled by the `underline-color`
+    /// feature flag.
+    ///
+    /// See
+    /// [Wikipedia](https://en.wikipedia.org/wiki/ANSI_escape_code#SGR_(Select_Graphic_Rendition)_parameters)
+    /// code `58` and `59` for more information.
+    ///
+    /// ## Examples
+    ///
+    /// ```rust
+    /// use ratatui_core::style::{Color, Modifier, Style};
+    ///
+    /// let style = Style::default()
+    ///     .underline_color(Color::Blue)
+    ///     .add_modifier(Modifier::UNDERLINED);
+    /// let diff = Style::default()
+    ///     .underline_color(Color::Red)
+    ///     .add_modifier(Modifier::UNDERLINED);
+    /// assert_eq!(
+    ///     style.patch(diff),
+    ///     Style::default()
+    ///         .underline_color(Color::Red)
+    ///         .add_modifier(Modifier::UNDERLINED)
+    /// );
+    /// ```
+    #[cfg(feature = "underline-color")]
+    #[must_use = "`underline_color` returns the modified style without modifying the original"]
+    pub const fn underline_color(mut self, color: Color) -> Self {
+        self.underline_color = Some(color);
+        self
+    }
+
+    /// Changes the text emphasis.
+    ///
+    /// When applied, it adds the given modifier to the `Style` modifiers.
+    ///
+    /// ## Examples
+    ///
+    /// ```rust
+    /// use ratatui_core::style::{Modifier, Style};
+    ///
+    /// let style = Style::default().add_modifier(Modifier::BOLD);
+    /// let diff = Style::default().add_modifier(Modifier::ITALIC);
+    /// let patched = style.patch(diff);
+    /// assert_eq!(patched.add_modifier, Modifier::BOLD | Modifier::ITALIC);
+    /// assert_eq!(patched.sub_modifier, Modifier::empty());
+    /// ```
+    #[must_use = "`add_modifier` returns the modified style without modifying the original"]
+    pub const fn add_modifier(mut self, modifier: Modifier) -> Self {
+        self.sub_modifier = self.sub_modifier.difference(modifier);
+        self.add_modifier = self.add_modifier.union(modifier);
+        self
+    }
+
+    /// Changes the text emphasis.
+    ///
+    /// When applied, it removes the given modifier from the `Style` modifiers.
+    ///
+    /// ## Examples
+    ///
+    /// ```rust
+    /// use ratatui_core::style::{Modifier, Style};
+    ///
+    /// let style = Style::default().add_modifier(Modifier::BOLD | Modifier::ITALIC);
+    /// let diff = Style::default().remove_modifier(Modifier::ITALIC);
+    /// let patched = style.patch(diff);
+    /// assert_eq!(patched.add_modifier, Modifier::BOLD);
+    /// assert_eq!(patched.sub_modifier, Modifier::ITALIC);
+    /// ```
+    #[must_use = "`remove_modifier` returns the modified style without modifying the original"]
+    pub const fn remove_modifier(mut self, modifier: Modifier) -> Self {
+        self.add_modifier = self.add_modifier.difference(modifier);
+        self.sub_modifier = self.sub_modifier.union(modifier);
+        self
+    }
+
+    /// Results in a combined style that is equivalent to applying the two individual styles to
+    /// a style one after the other.
+    ///
+    /// `style` accepts any type that is convertible to [`Style`] (e.g. [`Style`], [`Color`], or
+    /// your own type that implements [`Into<Style>`]).
+    ///
+    /// ## Examples
+    /// ```
+    /// use ratatui_core::style::{Color, Modifier, Style};
+    ///
+    /// let style_1 = Style::default().fg(Color::Yellow);
+    /// let style_2 = Style::default().bg(Color::Red);
+    /// let combined = style_1.patch(style_2);
+    /// assert_eq!(
+    ///     Style::default().patch(style_1).patch(style_2),
+    ///     Style::default().patch(combined)
+    /// );
+    /// ```
+    #[must_use = "`patch` returns the modified style without modifying the original"]
+    pub fn patch<S: Into<Self>>(mut self, other: S) -> Self {
+        let other = other.into();
+        self.fg = other.fg.or(self.fg);
+        self.bg = other.bg.or(self.bg);
+
+        #[cfg(feature = "underline-color")]
+        {
+            self.underline_color = other.underline_color.or(self.underline_color);
+        }
+
+        self.add_modifier.remove(other.sub_modifier);
+        self.add_modifier.insert(other.add_modifier);
+        self.sub_modifier.remove(other.add_modifier);
+        self.sub_modifier.insert(other.sub_modifier);
+
+        self
+    }
+
+    /// Formats the style in a way that can be copy-pasted into code using the style shorthands.
+    ///
+    /// This is useful for debugging and for generating code snippets.
+    pub(crate) fn fmt_stylize(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        use fmt::Debug;
+        if let Some(fg) = self.fg {
+            fg.stylize_debug(ColorDebugKind::Foreground).fmt(f)?;
+        }
+        if let Some(bg) = self.bg {
+            bg.stylize_debug(ColorDebugKind::Background).fmt(f)?;
+        }
+        #[cfg(feature = "underline-color")]
+        if let Some(underline_color) = self.underline_color {
+            underline_color
+                .stylize_debug(ColorDebugKind::Underline)
+                .fmt(f)?;
+        }
+        for modifier in self.add_modifier.iter() {
+            match modifier {
+                Modifier::BOLD => f.write_str(".bold()")?,
+                Modifier::DIM => f.write_str(".dim()")?,
+                Modifier::ITALIC => f.write_str(".italic()")?,
+                Modifier::UNDERLINED => f.write_str(".underlined()")?,
+                Modifier::SLOW_BLINK => f.write_str(".slow_blink()")?,
+                Modifier::RAPID_BLINK => f.write_str(".rapid_blink()")?,
+                Modifier::REVERSED => f.write_str(".reversed()")?,
+                Modifier::HIDDEN => f.write_str(".hidden()")?,
+                Modifier::CROSSED_OUT => f.write_str(".crossed_out()")?,
+                _ => f.write_fmt(format_args!(".add_modifier(Modifier::{modifier:?})"))?,
+            }
+        }
+        for modifier in self.sub_modifier.iter() {
+            match modifier {
+                Modifier::BOLD => f.write_str(".not_bold()")?,
+                Modifier::DIM => f.write_str(".not_dim()")?,
+                Modifier::ITALIC => f.write_str(".not_italic()")?,
+                Modifier::UNDERLINED => f.write_str(".not_underlined()")?,
+                Modifier::SLOW_BLINK => f.write_str(".not_slow_blink()")?,
+                Modifier::RAPID_BLINK => f.write_str(".not_rapid_blink()")?,
+                Modifier::REVERSED => f.write_str(".not_reversed()")?,
+                Modifier::HIDDEN => f.write_str(".not_hidden()")?,
+                Modifier::CROSSED_OUT => f.write_str(".not_crossed_out()")?,
+                _ => f.write_fmt(format_args!(".remove_modifier(Modifier::{modifier:?})"))?,
+            }
+        }
+        Ok(())
+    }
+}
+
+impl From<Color> for Style {
+    /// Creates a new `Style` with the given foreground color.
+    ///
+    /// To specify a foreground and background color, use the `from((fg, bg))` constructor.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// use ratatui_core::style::{Color, Style};
+    ///
+    /// let style = Style::from(Color::Red);
+    /// ```
+    fn from(color: Color) -> Self {
+        Self::new().fg(color)
+    }
+}
+
+impl From<(Color, Color)> for Style {
+    /// Creates a new `Style` with the given foreground and background colors.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// use ratatui_core::style::{Color, Style};
+    ///
+    /// // red foreground, blue background
+    /// let style = Style::from((Color::Red, Color::Blue));
+    /// // default foreground, blue background
+    /// let style = Style::from((Color::Reset, Color::Blue));
+    /// ```
+    fn from((fg, bg): (Color, Color)) -> Self {
+        Self::new().fg(fg).bg(bg)
+    }
+}
+
+impl From<Modifier> for Style {
+    /// Creates a new `Style` with the given modifier added.
+    ///
+    /// To specify multiple modifiers, use the `|` operator.
+    ///
+    /// To specify modifiers to add and remove, use the `from((add_modifier, sub_modifier))`
+    /// constructor.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// use ratatui_core::style::{Style, Modifier};
+    ///
+    /// // add bold and italic
+    /// let style = Style::from(Modifier::BOLD|Modifier::ITALIC);
+    fn from(modifier: Modifier) -> Self {
+        Self::new().add_modifier(modifier)
+    }
+}
+
+impl From<(Modifier, Modifier)> for Style {
+    /// Creates a new `Style` with the given modifiers added and removed.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// use ratatui_core::style::{Modifier, Style};
+    ///
+    /// // add bold and italic, remove dim
+    /// let style = Style::from((Modifier::BOLD | Modifier::ITALIC, Modifier::DIM));
+    /// ```
+    fn from((add_modifier, sub_modifier): (Modifier, Modifier)) -> Self {
+        Self::new()
+            .add_modifier(add_modifier)
+            .remove_modifier(sub_modifier)
+    }
+}
+
+impl From<(Color, Modifier)> for Style {
+    /// Creates a new `Style` with the given foreground color and modifier added.
+    ///
+    /// To specify multiple modifiers, use the `|` operator.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// use ratatui_core::style::{Color, Modifier, Style};
+    ///
+    /// // red foreground, add bold and italic
+    /// let style = Style::from((Color::Red, Modifier::BOLD | Modifier::ITALIC));
+    /// ```
+    fn from((fg, modifier): (Color, Modifier)) -> Self {
+        Self::new().fg(fg).add_modifier(modifier)
+    }
+}
+
+impl From<(Color, Color, Modifier)> for Style {
+    /// Creates a new `Style` with the given foreground and background colors and modifier added.
+    ///
+    /// To specify multiple modifiers, use the `|` operator.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// 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));
+    /// ```
+    fn from((fg, bg, modifier): (Color, Color, Modifier)) -> Self {
+        Self::new().fg(fg).bg(bg).add_modifier(modifier)
+    }
+}
+
+impl From<(Color, Color, Modifier, Modifier)> for Style {
+    /// Creates a new `Style` with the given foreground and background colors and modifiers added
+    /// and removed.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// use ratatui_core::style::{Color, Modifier, Style};
+    ///
+    /// // red foreground, blue background, add bold and italic, remove dim
+    /// let style = Style::from((
+    ///     Color::Red,
+    ///     Color::Blue,
+    ///     Modifier::BOLD | Modifier::ITALIC,
+    ///     Modifier::DIM,
+    /// ));
+    /// ```
+    fn from((fg, bg, add_modifier, sub_modifier): (Color, Color, Modifier, Modifier)) -> Self {
+        Self::new()
+            .fg(fg)
+            .bg(bg)
+            .add_modifier(add_modifier)
+            .remove_modifier(sub_modifier)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use rstest::rstest;
+
+    use super::*;
+
+    #[rstest]
+    #[case(Style::new(), "Style::new()")]
+    #[case(Style::new().red(), "Style::new().red()")]
+    #[case(Style::new().on_blue(), "Style::new().on_blue()")]
+    #[case(Style::new().bold(), "Style::new().bold()")]
+    #[case(Style::new().not_italic(), "Style::new().not_italic()")]
+    #[case(
+        Style::new().red().on_blue().bold().italic().not_dim().not_hidden(),
+        "Style::new().red().on_blue().bold().italic().not_dim().not_hidden()"
+    )]
+    fn debug(#[case] style: Style, #[case] expected: &'static str) {
+        assert_eq!(format!("{style:?}"), expected);
+    }
+
+    #[test]
+    fn combined_patch_gives_same_result_as_individual_patch() {
+        let styles = [
+            Style::new(),
+            Style::new().fg(Color::Yellow),
+            Style::new().bg(Color::Yellow),
+            Style::new().add_modifier(Modifier::BOLD),
+            Style::new().remove_modifier(Modifier::BOLD),
+            Style::new().add_modifier(Modifier::ITALIC),
+            Style::new().remove_modifier(Modifier::ITALIC),
+            Style::new().add_modifier(Modifier::ITALIC | Modifier::BOLD),
+            Style::new().remove_modifier(Modifier::ITALIC | Modifier::BOLD),
+        ];
+        for &a in &styles {
+            for &b in &styles {
+                for &c in &styles {
+                    for &d in &styles {
+                        assert_eq!(
+                            Style::new().patch(a).patch(b).patch(c).patch(d),
+                            Style::new().patch(a.patch(b.patch(c.patch(d))))
+                        );
+                    }
+                }
+            }
+        }
+    }
+
+    #[test]
+    fn combine_individual_modifiers() {
+        use crate::{buffer::Buffer, layout::Rect};
+
+        let mods = [
+            Modifier::BOLD,
+            Modifier::DIM,
+            Modifier::ITALIC,
+            Modifier::UNDERLINED,
+            Modifier::SLOW_BLINK,
+            Modifier::RAPID_BLINK,
+            Modifier::REVERSED,
+            Modifier::HIDDEN,
+            Modifier::CROSSED_OUT,
+        ];
+
+        let mut buffer = Buffer::empty(Rect::new(0, 0, 1, 1));
+
+        for m in mods {
+            buffer[(0, 0)].set_style(Style::reset());
+            buffer[(0, 0)].set_style(Style::new().add_modifier(m));
+            let style = buffer[(0, 0)].style();
+            assert!(style.add_modifier.contains(m));
+            assert!(!style.sub_modifier.contains(m));
+        }
+    }
+
+    #[rstest]
+    #[case(Modifier::empty(), "NONE")]
+    #[case(Modifier::BOLD, "BOLD")]
+    #[case(Modifier::DIM, "DIM")]
+    #[case(Modifier::ITALIC, "ITALIC")]
+    #[case(Modifier::UNDERLINED, "UNDERLINED")]
+    #[case(Modifier::SLOW_BLINK, "SLOW_BLINK")]
+    #[case(Modifier::RAPID_BLINK, "RAPID_BLINK")]
+    #[case(Modifier::REVERSED, "REVERSED")]
+    #[case(Modifier::HIDDEN, "HIDDEN")]
+    #[case(Modifier::CROSSED_OUT, "CROSSED_OUT")]
+    #[case(Modifier::BOLD | Modifier::DIM, "BOLD | DIM")]
+    #[case(Modifier::all(), "BOLD | DIM | ITALIC | UNDERLINED | SLOW_BLINK | RAPID_BLINK | REVERSED | HIDDEN | CROSSED_OUT")]
+    fn modifier_debug(#[case] modifier: Modifier, #[case] expected: &str) {
+        assert_eq!(format!("{modifier:?}"), expected);
+    }
+
+    #[test]
+    fn style_can_be_const() {
+        const RED: Color = Color::Red;
+        const BLACK: Color = Color::Black;
+        const BOLD: Modifier = Modifier::BOLD;
+        const ITALIC: Modifier = Modifier::ITALIC;
+
+        const _RESET: Style = Style::reset();
+        const _RED_FG: Style = Style::new().fg(RED);
+        const _BLACK_BG: Style = Style::new().bg(BLACK);
+        const _ADD_BOLD: Style = Style::new().add_modifier(BOLD);
+        const _REMOVE_ITALIC: Style = Style::new().remove_modifier(ITALIC);
+        const ALL: Style = Style::new()
+            .fg(RED)
+            .bg(BLACK)
+            .add_modifier(BOLD)
+            .remove_modifier(ITALIC);
+        assert_eq!(
+            ALL,
+            Style::new()
+                .fg(Color::Red)
+                .bg(Color::Black)
+                .add_modifier(Modifier::BOLD)
+                .remove_modifier(Modifier::ITALIC)
+        );
+    }
+
+    #[rstest]
+    #[case(Style::new().black(), Color::Black)]
+    #[case(Style::new().red(), Color::Red)]
+    #[case(Style::new().green(), Color::Green)]
+    #[case(Style::new().yellow(), Color::Yellow)]
+    #[case(Style::new().blue(), Color::Blue)]
+    #[case(Style::new().magenta(), Color::Magenta)]
+    #[case(Style::new().cyan(), Color::Cyan)]
+    #[case(Style::new().white(), Color::White)]
+    #[case(Style::new().gray(), Color::Gray)]
+    #[case(Style::new().dark_gray(), Color::DarkGray)]
+    #[case(Style::new().light_red(), Color::LightRed)]
+    #[case(Style::new().light_green(), Color::LightGreen)]
+    #[case(Style::new().light_yellow(), Color::LightYellow)]
+    #[case(Style::new().light_blue(), Color::LightBlue)]
+    #[case(Style::new().light_magenta(), Color::LightMagenta)]
+    #[case(Style::new().light_cyan(), Color::LightCyan)]
+    #[case(Style::new().white(), Color::White)]
+    fn fg_can_be_stylized(#[case] stylized: Style, #[case] expected: Color) {
+        assert_eq!(stylized, Style::new().fg(expected));
+    }
+
+    #[rstest]
+    #[case(Style::new().on_black(), Color::Black)]
+    #[case(Style::new().on_red(), Color::Red)]
+    #[case(Style::new().on_green(), Color::Green)]
+    #[case(Style::new().on_yellow(), Color::Yellow)]
+    #[case(Style::new().on_blue(), Color::Blue)]
+    #[case(Style::new().on_magenta(), Color::Magenta)]
+    #[case(Style::new().on_cyan(), Color::Cyan)]
+    #[case(Style::new().on_white(), Color::White)]
+    #[case(Style::new().on_gray(), Color::Gray)]
+    #[case(Style::new().on_dark_gray(), Color::DarkGray)]
+    #[case(Style::new().on_light_red(), Color::LightRed)]
+    #[case(Style::new().on_light_green(), Color::LightGreen)]
+    #[case(Style::new().on_light_yellow(), Color::LightYellow)]
+    #[case(Style::new().on_light_blue(), Color::LightBlue)]
+    #[case(Style::new().on_light_magenta(), Color::LightMagenta)]
+    #[case(Style::new().on_light_cyan(), Color::LightCyan)]
+    #[case(Style::new().on_white(), Color::White)]
+    fn bg_can_be_stylized(#[case] stylized: Style, #[case] expected: Color) {
+        assert_eq!(stylized, Style::new().bg(expected));
+    }
+
+    #[rstest]
+    #[case(Style::new().bold(), Modifier::BOLD)]
+    #[case(Style::new().dim(), Modifier::DIM)]
+    #[case(Style::new().italic(), Modifier::ITALIC)]
+    #[case(Style::new().underlined(), Modifier::UNDERLINED)]
+    #[case(Style::new().slow_blink(), Modifier::SLOW_BLINK)]
+    #[case(Style::new().rapid_blink(), Modifier::RAPID_BLINK)]
+    #[case(Style::new().reversed(), Modifier::REVERSED)]
+    #[case(Style::new().hidden(), Modifier::HIDDEN)]
+    #[case(Style::new().crossed_out(), Modifier::CROSSED_OUT)]
+    fn add_modifier_can_be_stylized(#[case] stylized: Style, #[case] expected: Modifier) {
+        assert_eq!(stylized, Style::new().add_modifier(expected));
+    }
+
+    #[rstest]
+    #[case(Style::new().not_bold(), Modifier::BOLD)]
+    #[case(Style::new().not_dim(), Modifier::DIM)]
+    #[case(Style::new().not_italic(), Modifier::ITALIC)]
+    #[case(Style::new().not_underlined(), Modifier::UNDERLINED)]
+    #[case(Style::new().not_slow_blink(), Modifier::SLOW_BLINK)]
+    #[case(Style::new().not_rapid_blink(), Modifier::RAPID_BLINK)]
+    #[case(Style::new().not_reversed(), Modifier::REVERSED)]
+    #[case(Style::new().not_hidden(), Modifier::HIDDEN)]
+    #[case(Style::new().not_crossed_out(), Modifier::CROSSED_OUT)]
+    fn remove_modifier_can_be_stylized(#[case] stylized: Style, #[case] expected: Modifier) {
+        assert_eq!(stylized, Style::new().remove_modifier(expected));
+    }
+
+    #[test]
+    fn reset_can_be_stylized() {
+        assert_eq!(Style::new().reset(), Style::reset());
+    }
+
+    #[test]
+    fn from_color() {
+        assert_eq!(Style::from(Color::Red), Style::new().fg(Color::Red));
+    }
+
+    #[test]
+    fn from_color_color() {
+        assert_eq!(
+            Style::from((Color::Red, Color::Blue)),
+            Style::new().fg(Color::Red).bg(Color::Blue)
+        );
+    }
+
+    #[test]
+    fn from_modifier() {
+        assert_eq!(
+            Style::from(Modifier::BOLD | Modifier::ITALIC),
+            Style::new()
+                .add_modifier(Modifier::BOLD)
+                .add_modifier(Modifier::ITALIC)
+        );
+    }
+
+    #[test]
+    fn from_modifier_modifier() {
+        assert_eq!(
+            Style::from((Modifier::BOLD | Modifier::ITALIC, Modifier::DIM)),
+            Style::new()
+                .add_modifier(Modifier::BOLD)
+                .add_modifier(Modifier::ITALIC)
+                .remove_modifier(Modifier::DIM)
+        );
+    }
+
+    #[test]
+    fn from_color_modifier() {
+        assert_eq!(
+            Style::from((Color::Red, Modifier::BOLD | Modifier::ITALIC)),
+            Style::new()
+                .fg(Color::Red)
+                .add_modifier(Modifier::BOLD)
+                .add_modifier(Modifier::ITALIC)
+        );
+    }
+
+    #[test]
+    fn from_color_color_modifier() {
+        assert_eq!(
+            Style::from((Color::Red, Color::Blue, Modifier::BOLD | Modifier::ITALIC)),
+            Style::new()
+                .fg(Color::Red)
+                .bg(Color::Blue)
+                .add_modifier(Modifier::BOLD)
+                .add_modifier(Modifier::ITALIC)
+        );
+    }
+
+    #[test]
+    fn from_color_color_modifier_modifier() {
+        assert_eq!(
+            Style::from((
+                Color::Red,
+                Color::Blue,
+                Modifier::BOLD | Modifier::ITALIC,
+                Modifier::DIM
+            )),
+            Style::new()
+                .fg(Color::Red)
+                .bg(Color::Blue)
+                .add_modifier(Modifier::BOLD)
+                .add_modifier(Modifier::ITALIC)
+                .remove_modifier(Modifier::DIM)
+        );
+    }
+}

ratatui-core/src/style/color.rs

@@ -0,0 +1,737 @@
+#![allow(clippy::unreadable_literal)]
+
+use std::{fmt, str::FromStr};
+
+use crate::style::stylize::{ColorDebug, ColorDebugKind};
+
+/// ANSI Color
+///
+/// All colors from the [ANSI color table] are supported (though some names are not exactly the
+/// same).
+///
+/// | Color Name     | Color                   | Foreground | Background |
+/// |----------------|-------------------------|------------|------------|
+/// | `black`        | [`Color::Black`]        | 30         | 40         |
+/// | `red`          | [`Color::Red`]          | 31         | 41         |
+/// | `green`        | [`Color::Green`]        | 32         | 42         |
+/// | `yellow`       | [`Color::Yellow`]       | 33         | 43         |
+/// | `blue`         | [`Color::Blue`]         | 34         | 44         |
+/// | `magenta`      | [`Color::Magenta`]      | 35         | 45         |
+/// | `cyan`         | [`Color::Cyan`]         | 36         | 46         |
+/// | `gray`*        | [`Color::Gray`]         | 37         | 47         |
+/// | `darkgray`*    | [`Color::DarkGray`]     | 90         | 100        |
+/// | `lightred`     | [`Color::LightRed`]     | 91         | 101        |
+/// | `lightgreen`   | [`Color::LightGreen`]   | 92         | 102        |
+/// | `lightyellow`  | [`Color::LightYellow`]  | 93         | 103        |
+/// | `lightblue`    | [`Color::LightBlue`]    | 94         | 104        |
+/// | `lightmagenta` | [`Color::LightMagenta`] | 95         | 105        |
+/// | `lightcyan`    | [`Color::LightCyan`]    | 96         | 106        |
+/// | `white`*       | [`Color::White`]        | 97         | 107        |
+///
+/// - `gray` is sometimes called `white` - this is not supported as we use `white` for bright white
+/// - `gray` is sometimes called `silver` - this is supported
+/// - `darkgray` is sometimes called `light black` or `bright black` (both are supported)
+/// - `white` is sometimes called `light white` or `bright white` (both are supported)
+/// - we support `bright` and `light` prefixes for all colors
+/// - we support `-` and `_` and ` ` as separators for all colors
+/// - we support both `gray` and `grey` spellings
+///
+/// `From<Color> for Style` is implemented by creating a style with the foreground color set to the
+/// given color. This allows you to use colors anywhere that accepts `Into<Style>`.
+///
+/// # Example
+///
+/// ```
+/// use std::str::FromStr;
+///
+/// use ratatui_core::style::Color;
+///
+/// assert_eq!(Color::from_str("red"), Ok(Color::Red));
+/// assert_eq!("red".parse(), Ok(Color::Red));
+/// assert_eq!("lightred".parse(), Ok(Color::LightRed));
+/// assert_eq!("light red".parse(), Ok(Color::LightRed));
+/// assert_eq!("light-red".parse(), Ok(Color::LightRed));
+/// assert_eq!("light_red".parse(), Ok(Color::LightRed));
+/// assert_eq!("lightRed".parse(), Ok(Color::LightRed));
+/// assert_eq!("bright red".parse(), Ok(Color::LightRed));
+/// assert_eq!("bright-red".parse(), Ok(Color::LightRed));
+/// assert_eq!("silver".parse(), Ok(Color::Gray));
+/// assert_eq!("dark-grey".parse(), Ok(Color::DarkGray));
+/// assert_eq!("dark gray".parse(), Ok(Color::DarkGray));
+/// assert_eq!("light-black".parse(), Ok(Color::DarkGray));
+/// assert_eq!("white".parse(), Ok(Color::White));
+/// assert_eq!("bright white".parse(), Ok(Color::White));
+/// ```
+///
+/// [ANSI color table]: https://en.wikipedia.org/wiki/ANSI_escape_code#Colors
+#[derive(Debug, Default, Clone, Copy, Eq, PartialEq, Hash)]
+pub enum Color {
+    /// Resets the foreground or background color
+    #[default]
+    Reset,
+    /// ANSI Color: Black. Foreground: 30, Background: 40
+    Black,
+    /// ANSI Color: Red. Foreground: 31, Background: 41
+    Red,
+    /// ANSI Color: Green. Foreground: 32, Background: 42
+    Green,
+    /// ANSI Color: Yellow. Foreground: 33, Background: 43
+    Yellow,
+    /// ANSI Color: Blue. Foreground: 34, Background: 44
+    Blue,
+    /// ANSI Color: Magenta. Foreground: 35, Background: 45
+    Magenta,
+    /// ANSI Color: Cyan. Foreground: 36, Background: 46
+    Cyan,
+    /// ANSI Color: White. Foreground: 37, Background: 47
+    ///
+    /// Note that this is sometimes called `silver` or `white` but we use `white` for bright white
+    Gray,
+    /// ANSI Color: Bright Black. Foreground: 90, Background: 100
+    ///
+    /// Note that this is sometimes called `light black` or `bright black` but we use `dark gray`
+    DarkGray,
+    /// ANSI Color: Bright Red. Foreground: 91, Background: 101
+    LightRed,
+    /// ANSI Color: Bright Green. Foreground: 92, Background: 102
+    LightGreen,
+    /// ANSI Color: Bright Yellow. Foreground: 93, Background: 103
+    LightYellow,
+    /// ANSI Color: Bright Blue. Foreground: 94, Background: 104
+    LightBlue,
+    /// ANSI Color: Bright Magenta. Foreground: 95, Background: 105
+    LightMagenta,
+    /// ANSI Color: Bright Cyan. Foreground: 96, Background: 106
+    LightCyan,
+    /// ANSI Color: Bright White. Foreground: 97, Background: 107
+    /// Sometimes called `bright white` or `light white` in some terminals
+    White,
+    /// An RGB color.
+    ///
+    /// Note that only terminals that support 24-bit true color will display this correctly.
+    /// 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
+    /// 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>
+    Rgb(u8, u8, u8),
+    /// An 8-bit 256 color.
+    ///
+    /// See also <https://en.wikipedia.org/wiki/ANSI_escape_code#8-bit>
+    Indexed(u8),
+}
+
+impl Color {
+    /// Convert a u32 to a Color
+    ///
+    /// The u32 should be in the format 0x00RRGGBB.
+    pub const fn from_u32(u: u32) -> Self {
+        let r = (u >> 16) as u8;
+        let g = (u >> 8) as u8;
+        let b = u as u8;
+        Self::Rgb(r, g, b)
+    }
+}
+
+#[cfg(feature = "serde")]
+impl serde::Serialize for Color {
+    /// This utilises the [`fmt::Display`] implementation for serialization.
+    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
+    where
+        S: serde::Serializer,
+    {
+        serializer.serialize_str(&self.to_string())
+    }
+}
+
+#[cfg(feature = "serde")]
+impl<'de> serde::Deserialize<'de> for Color {
+    /// This is used to deserialize a value into Color via serde.
+    ///
+    /// This implementation uses the `FromStr` trait to deserialize strings, so named colours, RGB,
+    /// and indexed values are able to be deserialized. In addition, values that were produced by
+    /// the the older serialization implementation of Color are also able to be deserialized.
+    ///
+    /// Prior to v0.26.0, Ratatui would be serialized using a map for indexed and RGB values, for
+    /// examples in json `{"Indexed": 10}` and `{"Rgb": [255, 0, 255]}` respectively. Now they are
+    /// serialized using the string representation of the index and the RGB hex value, for example
+    /// in json it would now be `"10"` and `"#FF00FF"` respectively.
+    ///
+    /// See the [`Color`] documentation for more information on color names.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use std::str::FromStr;
+    ///
+    /// use ratatui_core::style::Color;
+    ///
+    /// #[derive(Debug, serde::Deserialize)]
+    /// struct Theme {
+    ///     color: Color,
+    /// }
+    ///
+    /// # fn get_theme() -> Result<(), serde_json::Error> {
+    /// let theme: Theme = serde_json::from_str(r#"{"color": "bright-white"}"#)?;
+    /// assert_eq!(theme.color, Color::White);
+    ///
+    /// let theme: Theme = serde_json::from_str(r##"{"color": "#00FF00"}"##)?;
+    /// assert_eq!(theme.color, Color::Rgb(0, 255, 0));
+    ///
+    /// let theme: Theme = serde_json::from_str(r#"{"color": "42"}"#)?;
+    /// assert_eq!(theme.color, Color::Indexed(42));
+    ///
+    /// let err = serde_json::from_str::<Theme>(r#"{"color": "invalid"}"#).unwrap_err();
+    /// assert!(err.is_data());
+    /// assert_eq!(
+    ///     err.to_string(),
+    ///     "Failed to parse Colors at line 1 column 20"
+    /// );
+    ///
+    /// // Deserializing from the previous serialization implementation
+    /// let theme: Theme = serde_json::from_str(r#"{"color": {"Rgb":[255,0,255]}}"#)?;
+    /// assert_eq!(theme.color, Color::Rgb(255, 0, 255));
+    ///
+    /// let theme: Theme = serde_json::from_str(r#"{"color": {"Indexed":10}}"#)?;
+    /// assert_eq!(theme.color, Color::Indexed(10));
+    /// # Ok(())
+    /// # }
+    /// ```
+    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+    where
+        D: serde::Deserializer<'de>,
+    {
+        /// Colors are currently serialized with the `Display` implementation, so
+        /// RGB values are serialized via hex, for example "#FFFFFF".
+        ///
+        /// Previously they were serialized using serde derive, which encoded
+        /// RGB values as a map, for example { "rgb": [255, 255, 255] }.
+        ///
+        /// The deserialization implementation utilises a `Helper` struct
+        /// to be able to support both formats for backwards compatibility.
+        #[derive(serde::Deserialize)]
+        enum ColorWrapper {
+            Rgb(u8, u8, u8),
+            Indexed(u8),
+        }
+
+        #[derive(serde::Deserialize)]
+        #[serde(untagged)]
+        enum ColorFormat {
+            V2(String),
+            V1(ColorWrapper),
+        }
+
+        let multi_type = ColorFormat::deserialize(deserializer)
+            .map_err(|err| serde::de::Error::custom(format!("Failed to parse Colors: {err}")))?;
+        match multi_type {
+            ColorFormat::V2(s) => FromStr::from_str(&s).map_err(serde::de::Error::custom),
+            ColorFormat::V1(color_wrapper) => match color_wrapper {
+                ColorWrapper::Rgb(red, green, blue) => Ok(Self::Rgb(red, green, blue)),
+                ColorWrapper::Indexed(index) => Ok(Self::Indexed(index)),
+            },
+        }
+    }
+}
+
+/// Error type indicating a failure to parse a color string.
+#[derive(Debug, Clone, Copy, Eq, PartialEq, Hash)]
+pub struct ParseColorError;
+
+impl fmt::Display for ParseColorError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "Failed to parse Colors")
+    }
+}
+
+impl std::error::Error for ParseColorError {}
+
+/// Converts a string representation to a `Color` instance.
+///
+/// The `from_str` function attempts to parse the given string and convert it to the corresponding
+/// `Color` variant. It supports named colors, RGB values, and indexed colors. If the string cannot
+/// be parsed, a `ParseColorError` is returned.
+///
+/// See the [`Color`] documentation for more information on the supported color names.
+///
+/// # Examples
+///
+/// ```
+/// use std::str::FromStr;
+///
+/// use ratatui_core::style::Color;
+///
+/// let color: Color = Color::from_str("blue").unwrap();
+/// assert_eq!(color, Color::Blue);
+///
+/// let color: Color = Color::from_str("#FF0000").unwrap();
+/// assert_eq!(color, Color::Rgb(255, 0, 0));
+///
+/// let color: Color = Color::from_str("10").unwrap();
+/// assert_eq!(color, Color::Indexed(10));
+///
+/// let color: Result<Color, _> = Color::from_str("invalid_color");
+/// assert!(color.is_err());
+/// ```
+impl FromStr for Color {
+    type Err = ParseColorError;
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        Ok(
+            // There is a mix of different color names and formats in the wild.
+            // This is an attempt to support as many as possible.
+            match s
+                .to_lowercase()
+                .replace([' ', '-', '_'], "")
+                .replace("bright", "light")
+                .replace("grey", "gray")
+                .replace("silver", "gray")
+                .replace("lightblack", "darkgray")
+                .replace("lightwhite", "white")
+                .replace("lightgray", "white")
+                .as_ref()
+            {
+                "reset" => Self::Reset,
+                "black" => Self::Black,
+                "red" => Self::Red,
+                "green" => Self::Green,
+                "yellow" => Self::Yellow,
+                "blue" => Self::Blue,
+                "magenta" => Self::Magenta,
+                "cyan" => Self::Cyan,
+                "gray" => Self::Gray,
+                "darkgray" => Self::DarkGray,
+                "lightred" => Self::LightRed,
+                "lightgreen" => Self::LightGreen,
+                "lightyellow" => Self::LightYellow,
+                "lightblue" => Self::LightBlue,
+                "lightmagenta" => Self::LightMagenta,
+                "lightcyan" => Self::LightCyan,
+                "white" => Self::White,
+                _ => {
+                    if let Ok(index) = s.parse::<u8>() {
+                        Self::Indexed(index)
+                    } else if let Some((r, g, b)) = parse_hex_color(s) {
+                        Self::Rgb(r, g, b)
+                    } else {
+                        return Err(ParseColorError);
+                    }
+                }
+            },
+        )
+    }
+}
+
+fn parse_hex_color(input: &str) -> Option<(u8, u8, u8)> {
+    if !input.starts_with('#') || input.len() != 7 {
+        return None;
+    }
+    let r = u8::from_str_radix(input.get(1..3)?, 16).ok()?;
+    let g = u8::from_str_radix(input.get(3..5)?, 16).ok()?;
+    let b = u8::from_str_radix(input.get(5..7)?, 16).ok()?;
+    Some((r, g, b))
+}
+
+impl fmt::Display for Color {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::Reset => write!(f, "Reset"),
+            Self::Black => write!(f, "Black"),
+            Self::Red => write!(f, "Red"),
+            Self::Green => write!(f, "Green"),
+            Self::Yellow => write!(f, "Yellow"),
+            Self::Blue => write!(f, "Blue"),
+            Self::Magenta => write!(f, "Magenta"),
+            Self::Cyan => write!(f, "Cyan"),
+            Self::Gray => write!(f, "Gray"),
+            Self::DarkGray => write!(f, "DarkGray"),
+            Self::LightRed => write!(f, "LightRed"),
+            Self::LightGreen => write!(f, "LightGreen"),
+            Self::LightYellow => write!(f, "LightYellow"),
+            Self::LightBlue => write!(f, "LightBlue"),
+            Self::LightMagenta => write!(f, "LightMagenta"),
+            Self::LightCyan => write!(f, "LightCyan"),
+            Self::White => write!(f, "White"),
+            Self::Rgb(r, g, b) => write!(f, "#{r:02X}{g:02X}{b:02X}"),
+            Self::Indexed(i) => write!(f, "{i}"),
+        }
+    }
+}
+
+impl Color {
+    pub(crate) const fn stylize_debug(self, kind: ColorDebugKind) -> ColorDebug {
+        ColorDebug { kind, color: self }
+    }
+
+    /// Converts a HSL representation to a `Color::Rgb` instance.
+    ///
+    /// The `from_hsl` function converts the Hue, Saturation and Lightness values to a corresponding
+    /// `Color` RGB equivalent.
+    ///
+    /// Hue values should be in the range [-180..180]. Values outside this range are normalized by
+    /// wrapping.
+    ///
+    /// Saturation and L values should be in the range [0.0..1.0]. Values outside this range are
+    /// clamped.
+    ///
+    /// Clamping to valid ranges happens before conversion to RGB.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// 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));
+    /// assert_eq!(color, Color::Rgb(0, 0, 0));
+    ///
+    /// // Maximum Lightness is white
+    /// let color: Color = Color::from_hsl(Hsl::new(0.0, 0.0, 1.0));
+    /// assert_eq!(color, Color::Rgb(255, 255, 255));
+    ///
+    /// // Minimum Saturation is fully desaturated red = gray
+    /// let color: Color = Color::from_hsl(Hsl::new(0.0, 0.0, 0.5));
+    /// assert_eq!(color, Color::Rgb(128, 128, 128));
+    ///
+    /// // Bright red
+    /// let color: Color = Color::from_hsl(Hsl::new(0.0, 1.0, 0.5));
+    /// assert_eq!(color, Color::Rgb(255, 0, 0));
+    ///
+    /// // Bright blue
+    /// let color: Color = Color::from_hsl(Hsl::new(-120.0, 1.0, 0.5));
+    /// assert_eq!(color, Color::Rgb(0, 0, 255));
+    /// ```
+    #[cfg(feature = "palette")]
+    pub fn from_hsl(hsl: palette::Hsl) -> Self {
+        use palette::{Clamp, FromColor, Srgb};
+        let hsl = hsl.clamp();
+        let Srgb {
+            red,
+            green,
+            blue,
+            standard: _,
+        }: Srgb<u8> = Srgb::from_color(hsl).into();
+
+        Self::Rgb(red, green, blue)
+    }
+
+    /// Converts a `HSLuv` representation to a `Color::Rgb` instance.
+    ///
+    /// The `from_hsluv` function converts the Hue, Saturation and Lightness values to a
+    /// corresponding `Color` RGB equivalent.
+    ///
+    /// Hue values should be in the range [-180.0..180.0]. Values outside this range are normalized
+    /// by wrapping.
+    ///
+    /// Saturation and L values should be in the range [0.0..100.0]. Values outside this range are
+    /// clamped.
+    ///
+    /// Clamping to valid ranges happens before conversion to RGB.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// 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));
+    /// assert_eq!(color, Color::Rgb(0, 0, 0));
+    ///
+    /// // Maximum Lightness is white
+    /// let color: Color = Color::from_hsluv(Hsluv::new(0.0, 0.0, 100.0));
+    /// assert_eq!(color, Color::Rgb(255, 255, 255));
+    ///
+    /// // Minimum Saturation is fully desaturated red = gray
+    /// let color = Color::from_hsluv(Hsluv::new(0.0, 0.0, 50.0));
+    /// assert_eq!(color, Color::Rgb(119, 119, 119));
+    ///
+    /// // Bright Red
+    /// let color = Color::from_hsluv(Hsluv::new(12.18, 100.0, 53.2));
+    /// assert_eq!(color, Color::Rgb(255, 0, 0));
+    ///
+    /// // Bright Blue
+    /// let color = Color::from_hsluv(Hsluv::new(-94.13, 100.0, 32.3));
+    /// assert_eq!(color, Color::Rgb(0, 0, 255));
+    /// ```
+    #[cfg(feature = "palette")]
+    pub fn from_hsluv(hsluv: palette::Hsluv) -> Self {
+        use palette::{Clamp, FromColor, Srgb};
+        let hsluv = hsluv.clamp();
+        let Srgb {
+            red,
+            green,
+            blue,
+            standard: _,
+        }: Srgb<u8> = Srgb::from_color(hsluv).into();
+
+        Self::Rgb(red, green, blue)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use std::error::Error;
+
+    #[cfg(feature = "palette")]
+    use palette::{Hsl, Hsluv};
+    #[cfg(feature = "palette")]
+    use rstest::rstest;
+    #[cfg(feature = "serde")]
+    use serde::de::{Deserialize, IntoDeserializer};
+
+    use super::*;
+
+    #[cfg(feature = "palette")]
+    #[rstest]
+    #[case::black(Hsl::new(0.0, 0.0, 0.0), Color::Rgb(0, 0, 0))]
+    #[case::white(Hsl::new(0.0, 0.0, 1.0), Color::Rgb(255, 255, 255))]
+    #[case::valid(Hsl::new(120.0, 0.5, 0.75), Color::Rgb(159, 223, 159))]
+    #[case::min_hue(Hsl::new(-180.0, 0.5, 0.75), Color::Rgb(159, 223, 223))]
+    #[case::max_hue(Hsl::new(180.0, 0.5, 0.75), Color::Rgb(159, 223, 223))]
+    #[case::min_saturation(Hsl::new(0.0, 0.0, 0.5), Color::Rgb(128, 128, 128))]
+    #[case::max_saturation(Hsl::new(0.0, 1.0, 0.5), Color::Rgb(255, 0, 0))]
+    #[case::min_lightness(Hsl::new(0.0, 0.5, 0.0), Color::Rgb(0, 0, 0))]
+    #[case::max_lightness(Hsl::new(0.0, 0.5, 1.0), Color::Rgb(255, 255, 255))]
+    #[case::under_hue_wraps(Hsl::new(-240.0, 0.5, 0.75), Color::Rgb(159, 223, 159))]
+    #[case::over_hue_wraps(Hsl::new(480.0, 0.5, 0.75), Color::Rgb(159, 223, 159))]
+    #[case::under_saturation_clamps(Hsl::new(0.0, -0.5, 0.75), Color::Rgb(191, 191, 191))]
+    #[case::over_saturation_clamps(Hsl::new(0.0, 1.2, 0.75), Color::Rgb(255, 128, 128))]
+    #[case::under_lightness_clamps(Hsl::new(0.0, 0.5, -0.20), Color::Rgb(0, 0, 0))]
+    #[case::over_lightness_clamps(Hsl::new(0.0, 0.5, 1.5), Color::Rgb(255, 255, 255))]
+    #[case::under_saturation_lightness_clamps(Hsl::new(0.0, -0.5, -0.20), Color::Rgb(0, 0, 0))]
+    #[case::over_saturation_lightness_clamps(Hsl::new(0.0, 1.2, 1.5), Color::Rgb(255, 255, 255))]
+    fn test_hsl_to_rgb(#[case] hsl: palette::Hsl, #[case] expected: Color) {
+        assert_eq!(Color::from_hsl(hsl), expected);
+    }
+
+    #[cfg(feature = "palette")]
+    #[rstest]
+    #[case::black(Hsluv::new(0.0, 0.0, 0.0), Color::Rgb(0, 0, 0))]
+    #[case::white(Hsluv::new(0.0, 0.0, 100.0), Color::Rgb(255, 255, 255))]
+    #[case::valid(Hsluv::new(120.0, 50.0, 75.0), Color::Rgb(147, 198, 129))]
+    #[case::min_hue(Hsluv::new(-180.0, 50.0, 75.0), Color::Rgb(135,196, 188))]
+    #[case::max_hue(Hsluv::new(180.0, 50.0, 75.0), Color::Rgb(135, 196, 188))]
+    #[case::min_saturation(Hsluv::new(0.0, 0.0, 75.0), Color::Rgb(185, 185, 185))]
+    #[case::max_saturation(Hsluv::new(0.0, 100.0, 75.0), Color::Rgb(255, 156, 177))]
+    #[case::min_lightness(Hsluv::new(0.0, 50.0, 0.0), Color::Rgb(0, 0, 0))]
+    #[case::max_lightness(Hsluv::new(0.0, 50.0, 100.0), Color::Rgb(255, 255, 255))]
+    #[case::under_hue_wraps(Hsluv::new(-240.0, 50.0, 75.0), Color::Rgb(147, 198, 129))]
+    #[case::over_hue_wraps(Hsluv::new(480.0, 50.0, 75.0), Color::Rgb(147, 198, 129))]
+    #[case::under_saturation_clamps(Hsluv::new(0.0, -50.0, 75.0), Color::Rgb(185, 185, 185))]
+    #[case::over_saturation_clamps(Hsluv::new(0.0, 150.0, 75.0), Color::Rgb(255, 156, 177))]
+    #[case::under_lightness_clamps(Hsluv::new(0.0, 50.0, -20.0), Color::Rgb(0, 0, 0))]
+    #[case::over_lightness_clamps(Hsluv::new(0.0, 50.0, 150.0), Color::Rgb(255, 255, 255))]
+    #[case::under_saturation_lightness_clamps(Hsluv::new(0.0, -50.0, -20.0), Color::Rgb(0, 0, 0))]
+    #[case::over_saturation_lightness_clamps(
+        Hsluv::new(0.0, 150.0, 150.0),
+        Color::Rgb(255, 255, 255)
+    )]
+    fn test_hsluv_to_rgb(#[case] hsluv: palette::Hsluv, #[case] expected: Color) {
+        assert_eq!(Color::from_hsluv(hsluv), expected);
+    }
+
+    #[test]
+    fn from_u32() {
+        assert_eq!(Color::from_u32(0x000000), Color::Rgb(0, 0, 0));
+        assert_eq!(Color::from_u32(0xFF0000), Color::Rgb(255, 0, 0));
+        assert_eq!(Color::from_u32(0x00FF00), Color::Rgb(0, 255, 0));
+        assert_eq!(Color::from_u32(0x0000FF), Color::Rgb(0, 0, 255));
+        assert_eq!(Color::from_u32(0xFFFFFF), Color::Rgb(255, 255, 255));
+    }
+
+    #[test]
+    fn from_rgb_color() {
+        let color: Color = Color::from_str("#FF0000").unwrap();
+        assert_eq!(color, Color::Rgb(255, 0, 0));
+    }
+
+    #[test]
+    fn from_indexed_color() {
+        let color: Color = Color::from_str("10").unwrap();
+        assert_eq!(color, Color::Indexed(10));
+    }
+
+    #[test]
+    fn from_ansi_color() -> Result<(), Box<dyn Error>> {
+        assert_eq!(Color::from_str("reset")?, Color::Reset);
+        assert_eq!(Color::from_str("black")?, Color::Black);
+        assert_eq!(Color::from_str("red")?, Color::Red);
+        assert_eq!(Color::from_str("green")?, Color::Green);
+        assert_eq!(Color::from_str("yellow")?, Color::Yellow);
+        assert_eq!(Color::from_str("blue")?, Color::Blue);
+        assert_eq!(Color::from_str("magenta")?, Color::Magenta);
+        assert_eq!(Color::from_str("cyan")?, Color::Cyan);
+        assert_eq!(Color::from_str("gray")?, Color::Gray);
+        assert_eq!(Color::from_str("darkgray")?, Color::DarkGray);
+        assert_eq!(Color::from_str("lightred")?, Color::LightRed);
+        assert_eq!(Color::from_str("lightgreen")?, Color::LightGreen);
+        assert_eq!(Color::from_str("lightyellow")?, Color::LightYellow);
+        assert_eq!(Color::from_str("lightblue")?, Color::LightBlue);
+        assert_eq!(Color::from_str("lightmagenta")?, Color::LightMagenta);
+        assert_eq!(Color::from_str("lightcyan")?, Color::LightCyan);
+        assert_eq!(Color::from_str("white")?, Color::White);
+
+        // aliases
+        assert_eq!(Color::from_str("lightblack")?, Color::DarkGray);
+        assert_eq!(Color::from_str("lightwhite")?, Color::White);
+        assert_eq!(Color::from_str("lightgray")?, Color::White);
+
+        // silver = grey = gray
+        assert_eq!(Color::from_str("grey")?, Color::Gray);
+        assert_eq!(Color::from_str("silver")?, Color::Gray);
+
+        // spaces are ignored
+        assert_eq!(Color::from_str("light black")?, Color::DarkGray);
+        assert_eq!(Color::from_str("light white")?, Color::White);
+        assert_eq!(Color::from_str("light gray")?, Color::White);
+
+        // dashes are ignored
+        assert_eq!(Color::from_str("light-black")?, Color::DarkGray);
+        assert_eq!(Color::from_str("light-white")?, Color::White);
+        assert_eq!(Color::from_str("light-gray")?, Color::White);
+
+        // underscores are ignored
+        assert_eq!(Color::from_str("light_black")?, Color::DarkGray);
+        assert_eq!(Color::from_str("light_white")?, Color::White);
+        assert_eq!(Color::from_str("light_gray")?, Color::White);
+
+        // bright = light
+        assert_eq!(Color::from_str("bright-black")?, Color::DarkGray);
+        assert_eq!(Color::from_str("bright-white")?, Color::White);
+
+        // bright = light
+        assert_eq!(Color::from_str("brightblack")?, Color::DarkGray);
+        assert_eq!(Color::from_str("brightwhite")?, Color::White);
+
+        Ok(())
+    }
+
+    #[test]
+    fn from_invalid_colors() {
+        let bad_colors = [
+            "invalid_color", // not a color string
+            "abcdef0",       // 7 chars is not a color
+            " bcdefa",       // doesn't start with a '#'
+            "#abcdef00",     // too many chars
+            "#1🦀2",         // len 7 but on char boundaries shouldnt panic
+            "resett",        // typo
+            "lightblackk",   // typo
+        ];
+
+        for bad_color in bad_colors {
+            assert!(
+                Color::from_str(bad_color).is_err(),
+                "bad color: '{bad_color}'"
+            );
+        }
+    }
+
+    #[test]
+    fn display() {
+        assert_eq!(format!("{}", Color::Black), "Black");
+        assert_eq!(format!("{}", Color::Red), "Red");
+        assert_eq!(format!("{}", Color::Green), "Green");
+        assert_eq!(format!("{}", Color::Yellow), "Yellow");
+        assert_eq!(format!("{}", Color::Blue), "Blue");
+        assert_eq!(format!("{}", Color::Magenta), "Magenta");
+        assert_eq!(format!("{}", Color::Cyan), "Cyan");
+        assert_eq!(format!("{}", Color::Gray), "Gray");
+        assert_eq!(format!("{}", Color::DarkGray), "DarkGray");
+        assert_eq!(format!("{}", Color::LightRed), "LightRed");
+        assert_eq!(format!("{}", Color::LightGreen), "LightGreen");
+        assert_eq!(format!("{}", Color::LightYellow), "LightYellow");
+        assert_eq!(format!("{}", Color::LightBlue), "LightBlue");
+        assert_eq!(format!("{}", Color::LightMagenta), "LightMagenta");
+        assert_eq!(format!("{}", Color::LightCyan), "LightCyan");
+        assert_eq!(format!("{}", Color::White), "White");
+        assert_eq!(format!("{}", Color::Indexed(10)), "10");
+        assert_eq!(format!("{}", Color::Rgb(255, 0, 0)), "#FF0000");
+        assert_eq!(format!("{}", Color::Reset), "Reset");
+    }
+
+    #[cfg(feature = "serde")]
+    #[test]
+    fn deserialize() -> Result<(), serde::de::value::Error> {
+        assert_eq!(
+            Color::Black,
+            Color::deserialize("Black".into_deserializer())?
+        );
+        assert_eq!(
+            Color::Magenta,
+            Color::deserialize("magenta".into_deserializer())?
+        );
+        assert_eq!(
+            Color::LightGreen,
+            Color::deserialize("LightGreen".into_deserializer())?
+        );
+        assert_eq!(
+            Color::White,
+            Color::deserialize("bright-white".into_deserializer())?
+        );
+        assert_eq!(
+            Color::Indexed(42),
+            Color::deserialize("42".into_deserializer())?
+        );
+        assert_eq!(
+            Color::Rgb(0, 255, 0),
+            Color::deserialize("#00ff00".into_deserializer())?
+        );
+        Ok(())
+    }
+
+    #[cfg(feature = "serde")]
+    #[test]
+    fn deserialize_error() {
+        let color: Result<_, serde::de::value::Error> =
+            Color::deserialize("invalid".into_deserializer());
+        assert!(color.is_err());
+
+        let color: Result<_, serde::de::value::Error> =
+            Color::deserialize("#00000000".into_deserializer());
+        assert!(color.is_err());
+    }
+
+    #[cfg(feature = "serde")]
+    #[test]
+    fn serialize_then_deserialize() -> Result<(), serde_json::Error> {
+        let json_rgb = serde_json::to_string(&Color::Rgb(255, 0, 255))?;
+        assert_eq!(json_rgb, r##""#FF00FF""##);
+        assert_eq!(
+            serde_json::from_str::<Color>(&json_rgb)?,
+            Color::Rgb(255, 0, 255)
+        );
+
+        let json_white = serde_json::to_string(&Color::White)?;
+        assert_eq!(json_white, r#""White""#);
+
+        let json_indexed = serde_json::to_string(&Color::Indexed(10))?;
+        assert_eq!(json_indexed, r#""10""#);
+        assert_eq!(
+            serde_json::from_str::<Color>(&json_indexed)?,
+            Color::Indexed(10)
+        );
+
+        Ok(())
+    }
+
+    #[cfg(feature = "serde")]
+    #[test]
+    fn deserialize_with_previous_format() -> Result<(), serde_json::Error> {
+        assert_eq!(Color::White, serde_json::from_str::<Color>("\"White\"")?);
+        assert_eq!(
+            Color::Rgb(255, 0, 255),
+            serde_json::from_str::<Color>(r#"{"Rgb":[255,0,255]}"#)?
+        );
+        assert_eq!(
+            Color::Indexed(10),
+            serde_json::from_str::<Color>(r#"{"Indexed":10}"#)?
+        );
+        Ok(())
+    }
+}

ratatui-core/src/style/palette.rs

@@ -0,0 +1,6 @@
+#![allow(clippy::unreadable_literal)]
+
+//! A module for defining color palettes.
+
+pub mod material;
+pub mod tailwind;

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

@@ -0,0 +1,608 @@
+//! Material design color palettes.
+//!
+//! Represents the colors from the 2014 [Material design color palettes][palettes] by Google.
+//!
+//! [palettes]: https://m2.material.io/design/color/the-color-system.html#tools-for-picking-colors
+//!
+//! There are 16 palettes with accent colors, and 3 palettes without accent colors. Each palette
+//! has 10 colors, with variants from 50 to 900. The accent palettes also have 4 accent colors
+//! with variants from 100 to 700. Black and White are also included for completeness and to avoid
+//! being affected by any terminal theme that might be in use.
+//!
+//! This module exists to provide a convenient way to use the colors from the
+//! [`matdesign-color` crate] in your application.
+//!
+//! <style>
+//! .color { display: flex; align-items: center; }
+//! .color > div { width: 2rem; height: 2rem; }
+//! .color > div.name { width: 150px; !important; }
+//! </style>
+//! <div style="overflow-x: auto">
+//! <div style="display: flex; flex-direction:column; text-align: left">
+//! <div class="color" style="font-size:0.8em">
+//!     <div class="name"></div>
+//!     <div>C50</div>
+//!     <div>C100</div>
+//!     <div>C200</div>
+//!     <div>C300</div>
+//!     <div>C400</div>
+//!     <div>C500</div>
+//!     <div>C600</div>
+//!     <div>C700</div>
+//!     <div>C800</div>
+//!     <div>C900</div>
+//!     <div>A100</div>
+//!     <div>A200</div>
+//!     <div>A400</div>
+//!     <div>A700</div>
+//! </div>
+//! <div class="color">
+//!     <div class="name">
+//!
+//! [`RED`]</div>
+//!     <div style="background-color: #FFEBEE"></div>
+//!     <div style="background-color: #FFCDD2"></div>
+//!     <div style="background-color: #EF9A9A"></div>
+//!     <div style="background-color: #E57373"></div>
+//!     <div style="background-color: #EF5350"></div>
+//!     <div style="background-color: #F44336"></div>
+//!     <div style="background-color: #E53935"></div>
+//!     <div style="background-color: #D32F2F"></div>
+//!     <div style="background-color: #C62828"></div>
+//!     <div style="background-color: #B71C1C"></div>
+//!     <div style="background-color: #FF8A80"></div>
+//!     <div style="background-color: #FF5252"></div>
+//!     <div style="background-color: #FF1744"></div>
+//!     <div style="background-color: #D50000"></div>
+//! </div>
+//! <div class="color">
+//!     <div class="name">
+//!
+//! [`PINK`]</div>
+//!     <div style="background-color: #FCE4EC"></div>
+//!     <div style="background-color: #F8BBD0"></div>
+//!     <div style="background-color: #F48FB1"></div>
+//!     <div style="background-color: #F06292"></div>
+//!     <div style="background-color: #EC407A"></div>
+//!     <div style="background-color: #E91E63"></div>
+//!     <div style="background-color: #D81B60"></div>
+//!     <div style="background-color: #C2185B"></div>
+//!     <div style="background-color: #AD1457"></div>
+//!     <div style="background-color: #880E4F"></div>
+//!     <div style="background-color: #FF80AB"></div>
+//!     <div style="background-color: #FF4081"></div>
+//!     <div style="background-color: #F50057"></div>
+//!     <div style="background-color: #C51162"></div>
+//! </div>
+//! <div class="color">
+//!     <div class="name">
+//!
+//! [`PURPLE`]</div>
+//!     <div style="background-color: #F3E5F5"></div>
+//!     <div style="background-color: #E1BEE7"></div>
+//!     <div style="background-color: #CE93D8"></div>
+//!     <div style="background-color: #BA68C8"></div>
+//!     <div style="background-color: #AB47BC"></div>
+//!     <div style="background-color: #9C27B0"></div>
+//!     <div style="background-color: #8E24AA"></div>
+//!     <div style="background-color: #7B1FA2"></div>
+//!     <div style="background-color: #6A1B9A"></div>
+//!     <div style="background-color: #4A148C"></div>
+//!     <div style="background-color: #EA80FC"></div>
+//!     <div style="background-color: #E040FB"></div>
+//!     <div style="background-color: #D500F9"></div>
+//!     <div style="background-color: #AA00FF"></div>
+//! </div>
+//! <div class="color">
+//!     <div class="name">
+//!
+//! [`DEEP_PURPLE`]</div>
+//!     <div style="background-color: #EDE7F6"></div>
+//!     <div style="background-color: #D1C4E9"></div>
+//!     <div style="background-color: #B39DDB"></div>
+//!     <div style="background-color: #9575CD"></div>
+//!     <div style="background-color: #7E57C2"></div>
+//!     <div style="background-color: #673AB7"></div>
+//!     <div style="background-color: #5E35B1"></div>
+//!     <div style="background-color: #512DA8"></div>
+//!     <div style="background-color: #4527A0"></div>
+//!     <div style="background-color: #311B92"></div>
+//!     <div style="background-color: #B388FF"></div>
+//!     <div style="background-color: #7C4DFF"></div>
+//!     <div style="background-color: #651FFF"></div>
+//!     <div style="background-color: #6200EA"></div>
+//! </div>
+//! <div class="color">
+//!     <div class="name">
+//!
+//! [`INDIGO`]</div>
+//!     <div style="background-color: #E8EAF6"></div>
+//!     <div style="background-color: #C5CAE9"></div>
+//!     <div style="background-color: #9FA8DA"></div>
+//!     <div style="background-color: #7986CB"></div>
+//!     <div style="background-color: #5C6BC0"></div>
+//!     <div style="background-color: #3F51B5"></div>
+//!     <div style="background-color: #3949AB"></div>
+//!     <div style="background-color: #303F9F"></div>
+//!     <div style="background-color: #283593"></div>
+//!     <div style="background-color: #1A237E"></div>
+//!     <div style="background-color: #8C9EFF"></div>
+//!     <div style="background-color: #536DFE"></div>
+//!     <div style="background-color: #3D5AFE"></div>
+//!     <div style="background-color: #304FFE"></div>
+//! </div>
+//! <div class="color">
+//!     <div class="name">
+//!
+//! [`BLUE`]</div>
+//!     <div style="background-color: #E3F2FD"></div>
+//!     <div style="background-color: #BBDEFB"></div>
+//!     <div style="background-color: #90CAF9"></div>
+//!     <div style="background-color: #64B5F6"></div>
+//!     <div style="background-color: #42A5F5"></div>
+//!     <div style="background-color: #2196F3"></div>
+//!     <div style="background-color: #1E88E5"></div>
+//!     <div style="background-color: #1976D2"></div>
+//!     <div style="background-color: #1565C0"></div>
+//!     <div style="background-color: #0D47A1"></div>
+//!     <div style="background-color: #82B1FF"></div>
+//!     <div style="background-color: #448AFF"></div>
+//!     <div style="background-color: #2979FF"></div>
+//!     <div style="background-color: #2962FF"></div>
+//! </div>
+//! <div class="color">
+//!     <div class="name">
+//!
+//! [`LIGHT_BLUE`]</div>
+//!     <div style="background-color: #E1F5FE"></div>
+//!     <div style="background-color: #B3E5FC"></div>
+//!     <div style="background-color: #81D4FA"></div>
+//!     <div style="background-color: #4FC3F7"></div>
+//!     <div style="background-color: #29B6F6"></div>
+//!     <div style="background-color: #03A9F4"></div>
+//!     <div style="background-color: #039BE5"></div>
+//!     <div style="background-color: #0288D1"></div>
+//!     <div style="background-color: #0277BD"></div>
+//!     <div style="background-color: #01579B"></div>
+//!     <div style="background-color: #80D8FF"></div>
+//!     <div style="background-color: #40C4FF"></div>
+//!     <div style="background-color: #00B0FF"></div>
+//!     <div style="background-color: #0091EA"></div>
+//! </div>
+//! <div class="color">
+//!     <div class="name">
+//!
+//! [`CYAN`]</div>
+//!     <div style="background-color: #E0F7FA"></div>
+//!     <div style="background-color: #B2EBF2"></div>
+//!     <div style="background-color: #80DEEA"></div>
+//!     <div style="background-color: #4DD0E1"></div>
+//!     <div style="background-color: #26C6DA"></div>
+//!     <div style="background-color: #00BCD4"></div>
+//!     <div style="background-color: #00ACC1"></div>
+//!     <div style="background-color: #0097A7"></div>
+//!     <div style="background-color: #00838F"></div>
+//!     <div style="background-color: #006064"></div>
+//!     <div style="background-color: #84FFFF"></div>
+//!     <div style="background-color: #18FFFF"></div>
+//!     <div style="background-color: #00E5FF"></div>
+//!     <div style="background-color: #00B8D4"></div>
+//! </div>
+//! <div class="color">
+//!     <div class="name">
+//!
+//! [`TEAL`]</div>
+//!     <div style="background-color: #E0F2F1"></div>
+//!     <div style="background-color: #B2DFDB"></div>
+//!     <div style="background-color: #80CBC4"></div>
+//!     <div style="background-color: #4DB6AC"></div>
+//!     <div style="background-color: #26A69A"></div>
+//!     <div style="background-color: #009688"></div>
+//!     <div style="background-color: #00897B"></div>
+//!     <div style="background-color: #00796B"></div>
+//!     <div style="background-color: #00695C"></div>
+//!     <div style="background-color: #004D40"></div>
+//!     <div style="background-color: #A7FFEB"></div>
+//!     <div style="background-color: #64FFDA"></div>
+//!     <div style="background-color: #1DE9B6"></div>
+//!     <div style="background-color: #00BFA5"></div>
+//! </div>
+//! <div class="color">
+//!     <div class="name">
+//!
+//! [`GREEN`]</div>
+//!     <div style="background-color: #E8F5E9"></div>
+//!     <div style="background-color: #C8E6C9"></div>
+//!     <div style="background-color: #A5D6A7"></div>
+//!     <div style="background-color: #81C784"></div>
+//!     <div style="background-color: #66BB6A"></div>
+//!     <div style="background-color: #4CAF50"></div>
+//!     <div style="background-color: #43A047"></div>
+//!     <div style="background-color: #388E3C"></div>
+//!     <div style="background-color: #2E7D32"></div>
+//!     <div style="background-color: #1B5E20"></div>
+//!     <div style="background-color: #B9F6CA"></div>
+//!     <div style="background-color: #69F0AE"></div>
+//!     <div style="background-color: #00E676"></div>
+//!     <div style="background-color: #00C853"></div>
+//! </div>
+//! <div class="color">
+//!     <div class="name">
+//!
+//! [`LIGHT_GREEN`]</div>
+//!     <div style="background-color: #F1F8E9"></div>
+//!     <div style="background-color: #DCEDC8"></div>
+//!     <div style="background-color: #C5E1A5"></div>
+//!     <div style="background-color: #AED581"></div>
+//!     <div style="background-color: #9CCC65"></div>
+//!     <div style="background-color: #8BC34A"></div>
+//!     <div style="background-color: #7CB342"></div>
+//!     <div style="background-color: #689F38"></div>
+//!     <div style="background-color: #558B2F"></div>
+//!     <div style="background-color: #33691E"></div>
+//!     <div style="background-color: #CCFF90"></div>
+//!     <div style="background-color: #B2FF59"></div>
+//!     <div style="background-color: #76FF03"></div>
+//!     <div style="background-color: #64DD17"></div>
+//! </div>
+//! <div class="color">
+//!     <div class="name">
+//!
+//! [`LIME`]</div>
+//!     <div style="background-color: #F9FBE7"></div>
+//!     <div style="background-color: #F0F4C3"></div>
+//!     <div style="background-color: #E6EE9C"></div>
+//!     <div style="background-color: #DCE775"></div>
+//!     <div style="background-color: #D4E157"></div>
+//!     <div style="background-color: #CDDC39"></div>
+//!     <div style="background-color: #C0CA33"></div>
+//!     <div style="background-color: #AFB42B"></div>
+//!     <div style="background-color: #9E9D24"></div>
+//!     <div style="background-color: #827717"></div>
+//!     <div style="background-color: #F4FF81"></div>
+//!     <div style="background-color: #EEFF41"></div>
+//!     <div style="background-color: #C6FF00"></div>
+//!     <div style="background-color: #AEEA00"></div>
+//! </div>
+//! <div class="color">
+//!     <div class="name">
+//!
+//! [`YELLOW`]</div>
+//!     <div style="background-color: #FFFDE7"></div>
+//!     <div style="background-color: #FFF9C4"></div>
+//!     <div style="background-color: #FFF59D"></div>
+//!     <div style="background-color: #FFF176"></div>
+//!     <div style="background-color: #FFEE58"></div>
+//!     <div style="background-color: #FFEB3B"></div>
+//!     <div style="background-color: #FDD835"></div>
+//!     <div style="background-color: #FBC02D"></div>
+//!     <div style="background-color: #F9A825"></div>
+//!     <div style="background-color: #F57F17"></div>
+//!     <div style="background-color: #FFFF8D"></div>
+//!     <div style="background-color: #FFFF00"></div>
+//!     <div style="background-color: #FFEA00"></div>
+//!     <div style="background-color: #FFD600"></div>
+//! </div>
+//! <div class="color">
+//!     <div class="name">
+//!
+//! [`AMBER`]</div>
+//!     <div style="background-color: #FFF8E1"></div>
+//!     <div style="background-color: #FFECB3"></div>
+//!     <div style="background-color: #FFE082"></div>
+//!     <div style="background-color: #FFD54F"></div>
+//!     <div style="background-color: #FFCA28"></div>
+//!     <div style="background-color: #FFC107"></div>
+//!     <div style="background-color: #FFB300"></div>
+//!     <div style="background-color: #FFA000"></div>
+//!     <div style="background-color: #FF8F00"></div>
+//!     <div style="background-color: #FF6F00"></div>
+//!     <div style="background-color: #FFE57F"></div>
+//!     <div style="background-color: #FFD740"></div>
+//!     <div style="background-color: #FFC400"></div>
+//!     <div style="background-color: #FFAB00"></div>
+//! </div>
+//! <div class="color">
+//!     <div class="name">
+//!
+//! [`ORANGE`]</div>
+//!     <div style="background-color: #FFF3E0"></div>
+//!     <div style="background-color: #FFE0B2"></div>
+//!     <div style="background-color: #FFCC80"></div>
+//!     <div style="background-color: #FFB74D"></div>
+//!     <div style="background-color: #FFA726"></div>
+//!     <div style="background-color: #FF9800"></div>
+//!     <div style="background-color: #FB8C00"></div>
+//!     <div style="background-color: #F57C00"></div>
+//!     <div style="background-color: #EF6C00"></div>
+//!     <div style="background-color: #E65100"></div>
+//!     <div style="background-color: #FFD180"></div>
+//!     <div style="background-color: #FFAB40"></div>
+//!     <div style="background-color: #FF9100"></div>
+//!     <div style="background-color: #FF6D00"></div>
+//! </div>
+//! <div class="color">
+//!     <div class="name">
+//!
+//! [`DEEP_ORANGE`]</div>
+//!     <div style="background-color: #FBE9E7"></div>
+//!     <div style="background-color: #FFCCBC"></div>
+//!     <div style="background-color: #FFAB91"></div>
+//!     <div style="background-color: #FF8A65"></div>
+//!     <div style="background-color: #FF7043"></div>
+//!     <div style="background-color: #FF5722"></div>
+//!     <div style="background-color: #F4511E"></div>
+//!     <div style="background-color: #E64A19"></div>
+//!     <div style="background-color: #D84315"></div>
+//!     <div style="background-color: #BF360C"></div>
+//!     <div style="background-color: #FF9E80"></div>
+//!     <div style="background-color: #FF6E40"></div>
+//!     <div style="background-color: #FF3D00"></div>
+//!     <div style="background-color: #DD2C00"></div>
+//! </div>
+//! <div class="color">
+//!     <div class="name">
+//!
+//! [`BROWN`]</div>
+//!     <div style="background-color: #EFEBE9"></div>
+//!     <div style="background-color: #D7CCC8"></div>
+//!     <div style="background-color: #BCAAA4"></div>
+//!     <div style="background-color: #A1887F"></div>
+//!     <div style="background-color: #8D6E63"></div>
+//!     <div style="background-color: #795548"></div>
+//!     <div style="background-color: #6D4C41"></div>
+//!     <div style="background-color: #5D4037"></div>
+//!     <div style="background-color: #4E342E"></div>
+//!     <div style="background-color: #3E2723"></div>
+//! </div>
+//! <div class="color">
+//!     <div class="name">
+//!
+//! [`GRAY`]</div>
+//!     <div style="background-color: #FAFAFA"></div>
+//!     <div style="background-color: #F5F5F5"></div>
+//!     <div style="background-color: #EEEEEE"></div>
+//!     <div style="background-color: #E0E0E0"></div>
+//!     <div style="background-color: #BDBDBD"></div>
+//!     <div style="background-color: #9E9E9E"></div>
+//!     <div style="background-color: #757575"></div>
+//!     <div style="background-color: #616161"></div>
+//!     <div style="background-color: #424242"></div>
+//!     <div style="background-color: #212121"></div>
+//! </div>
+//! <div class="color">
+//!     <div class="name">
+//!
+//! [`BLUE_GRAY`]</div>
+//!     <div style="background-color: #ECEFF1"></div>
+//!     <div style="background-color: #CFD8DC"></div>
+//!     <div style="background-color: #B0BEC5"></div>
+//!     <div style="background-color: #90A4AE"></div>
+//!     <div style="background-color: #78909C"></div>
+//!     <div style="background-color: #607D8B"></div>
+//!     <div style="background-color: #546E7A"></div>
+//!     <div style="background-color: #455A64"></div>
+//!     <div style="background-color: #37474F"></div>
+//!     <div style="background-color: #263238"></div>
+//! </div>
+//! <div class="color">
+//!     <div class="name">
+//!
+//! [`BLACK`]</div>
+//!     <div class="bw" style="width: 350px; background-color: #000000"></div>
+//! </div>
+//! <div class="color">
+//!     <div class="name">
+//!
+//! [`WHITE`]</div>
+//!     <div style="width: 350px; background-color: #FFFFFF"></div>
+//! </div>
+//! </div>
+//! </div>
+//!
+//! # Example
+//!
+//! ```rust
+//! use ratatui_core::style::{
+//!     palette::material::{BLUE, RED},
+//!     Color,
+//! };
+//!
+//! assert_eq!(RED.c500, Color::Rgb(244, 67, 54));
+//! assert_eq!(BLUE.c500, Color::Rgb(33, 150, 243));
+//! ```
+//!
+//! [`matdesign-color` crate]: https://crates.io/crates/matdesign-color
+
+use crate::style::Color;
+
+/// A palette of colors for use in Material design with accent colors
+///
+/// This is a collection of colors that are used in Material design. They consist of a set of
+/// colors from 50 to 900, and a set of accent colors from 100 to 700.
+#[derive(Debug, Clone, Copy, Eq, PartialEq, Hash)]
+pub struct AccentedPalette {
+    pub c50: Color,
+    pub c100: Color,
+    pub c200: Color,
+    pub c300: Color,
+    pub c400: Color,
+    pub c500: Color,
+    pub c600: Color,
+    pub c700: Color,
+    pub c800: Color,
+    pub c900: Color,
+    pub a100: Color,
+    pub a200: Color,
+    pub a400: Color,
+    pub a700: Color,
+}
+
+/// A palette of colors for use in Material design without accent colors
+///
+/// This is a collection of colors that are used in Material design. They consist of a set of
+/// colors from 50 to 900.
+#[derive(Debug, Clone, Copy, Eq, PartialEq, Hash)]
+pub struct NonAccentedPalette {
+    pub c50: Color,
+    pub c100: Color,
+    pub c200: Color,
+    pub c300: Color,
+    pub c400: Color,
+    pub c500: Color,
+    pub c600: Color,
+    pub c700: Color,
+    pub c800: Color,
+    pub c900: Color,
+}
+
+impl AccentedPalette {
+    /// Create a new `AccentedPalette` from the given variants
+    ///
+    /// The variants should be in the format [0x00RRGGBB, ...]
+    pub const fn from_variants(variants: [u32; 14]) -> Self {
+        Self {
+            c50: Color::from_u32(variants[0]),
+            c100: Color::from_u32(variants[1]),
+            c200: Color::from_u32(variants[2]),
+            c300: Color::from_u32(variants[3]),
+            c400: Color::from_u32(variants[4]),
+            c500: Color::from_u32(variants[5]),
+            c600: Color::from_u32(variants[6]),
+            c700: Color::from_u32(variants[7]),
+            c800: Color::from_u32(variants[8]),
+            c900: Color::from_u32(variants[9]),
+            a100: Color::from_u32(variants[10]),
+            a200: Color::from_u32(variants[11]),
+            a400: Color::from_u32(variants[12]),
+            a700: Color::from_u32(variants[13]),
+        }
+    }
+}
+
+impl NonAccentedPalette {
+    /// Create a new `NonAccented` from the given variants
+    ///
+    /// The variants should be in the format [0x00RRGGBB, ...]
+    pub const fn from_variants(variants: [u32; 10]) -> Self {
+        Self {
+            c50: Color::from_u32(variants[0]),
+            c100: Color::from_u32(variants[1]),
+            c200: Color::from_u32(variants[2]),
+            c300: Color::from_u32(variants[3]),
+            c400: Color::from_u32(variants[4]),
+            c500: Color::from_u32(variants[5]),
+            c600: Color::from_u32(variants[6]),
+            c700: Color::from_u32(variants[7]),
+            c800: Color::from_u32(variants[8]),
+            c900: Color::from_u32(variants[9]),
+        }
+    }
+}
+
+// Accented palettes
+
+pub const RED: AccentedPalette = AccentedPalette::from_variants(variants::RED);
+pub const PINK: AccentedPalette = AccentedPalette::from_variants(variants::PINK);
+pub const PURPLE: AccentedPalette = AccentedPalette::from_variants(variants::PURPLE);
+pub const DEEP_PURPLE: AccentedPalette = AccentedPalette::from_variants(variants::DEEP_PURPLE);
+pub const INDIGO: AccentedPalette = AccentedPalette::from_variants(variants::INDIGO);
+pub const BLUE: AccentedPalette = AccentedPalette::from_variants(variants::BLUE);
+pub const LIGHT_BLUE: AccentedPalette = AccentedPalette::from_variants(variants::LIGHT_BLUE);
+pub const CYAN: AccentedPalette = AccentedPalette::from_variants(variants::CYAN);
+pub const TEAL: AccentedPalette = AccentedPalette::from_variants(variants::TEAL);
+pub const GREEN: AccentedPalette = AccentedPalette::from_variants(variants::GREEN);
+pub const LIGHT_GREEN: AccentedPalette = AccentedPalette::from_variants(variants::LIGHT_GREEN);
+pub const LIME: AccentedPalette = AccentedPalette::from_variants(variants::LIME);
+pub const YELLOW: AccentedPalette = AccentedPalette::from_variants(variants::YELLOW);
+pub const AMBER: AccentedPalette = AccentedPalette::from_variants(variants::AMBER);
+pub const ORANGE: AccentedPalette = AccentedPalette::from_variants(variants::ORANGE);
+pub const DEEP_ORANGE: AccentedPalette = AccentedPalette::from_variants(variants::DEEP_ORANGE);
+
+// Unaccented palettes
+pub const BROWN: NonAccentedPalette = NonAccentedPalette::from_variants(variants::BROWN);
+pub const GRAY: NonAccentedPalette = NonAccentedPalette::from_variants(variants::GRAY);
+pub const BLUE_GRAY: NonAccentedPalette = NonAccentedPalette::from_variants(variants::BLUE_GRAY);
+
+// Black and white included for completeness
+pub const BLACK: Color = Color::from_u32(0x000000);
+pub const WHITE: Color = Color::from_u32(0xFFFFFF);
+
+mod variants {
+    pub const RED: [u32; 14] = [
+        0xFFEBEE, 0xFFCDD2, 0xEF9A9A, 0xE57373, 0xEF5350, 0xF44336, 0xE53935, 0xD32F2F, 0xC62828,
+        0xB71C1C, 0xFF8A80, 0xFF5252, 0xFF1744, 0xD50000,
+    ];
+    pub const PINK: [u32; 14] = [
+        0xFCE4EC, 0xF8BBD0, 0xF48FB1, 0xF06292, 0xEC407A, 0xE91E63, 0xD81B60, 0xC2185B, 0xAD1457,
+        0x880E4F, 0xFF80AB, 0xFF4081, 0xF50057, 0xC51162,
+    ];
+    pub const PURPLE: [u32; 14] = [
+        0xF3E5F5, 0xE1BEE7, 0xCE93D8, 0xBA68C8, 0xAB47BC, 0x9C27B0, 0x8E24AA, 0x7B1FA2, 0x6A1B9A,
+        0x4A148C, 0xEA80FC, 0xE040FB, 0xD500F9, 0xAA00FF,
+    ];
+    pub const DEEP_PURPLE: [u32; 14] = [
+        0xEDE7F6, 0xD1C4E9, 0xB39DDB, 0x9575CD, 0x7E57C2, 0x673AB7, 0x5E35B1, 0x512DA8, 0x4527A0,
+        0x311B92, 0xB388FF, 0x7C4DFF, 0x651FFF, 0x6200EA,
+    ];
+    pub const INDIGO: [u32; 14] = [
+        0xE8EAF6, 0xC5CAE9, 0x9FA8DA, 0x7986CB, 0x5C6BC0, 0x3F51B5, 0x3949AB, 0x303F9F, 0x283593,
+        0x1A237E, 0x8C9EFF, 0x536DFE, 0x3D5AFE, 0x304FFE,
+    ];
+    pub const BLUE: [u32; 14] = [
+        0xE3F2FD, 0xBBDEFB, 0x90CAF9, 0x64B5F6, 0x42A5F5, 0x2196F3, 0x1E88E5, 0x1976D2, 0x1565C0,
+        0x0D47A1, 0x82B1FF, 0x448AFF, 0x2979FF, 0x2962FF,
+    ];
+    pub const LIGHT_BLUE: [u32; 14] = [
+        0xE1F5FE, 0xB3E5FC, 0x81D4FA, 0x4FC3F7, 0x29B6F6, 0x03A9F4, 0x039BE5, 0x0288D1, 0x0277BD,
+        0x01579B, 0x80D8FF, 0x40C4FF, 0x00B0FF, 0x0091EA,
+    ];
+    pub const CYAN: [u32; 14] = [
+        0xE0F7FA, 0xB2EBF2, 0x80DEEA, 0x4DD0E1, 0x26C6DA, 0x00BCD4, 0x00ACC1, 0x0097A7, 0x00838F,
+        0x006064, 0x84FFFF, 0x18FFFF, 0x00E5FF, 0x00B8D4,
+    ];
+    pub const TEAL: [u32; 14] = [
+        0xE0F2F1, 0xB2DFDB, 0x80CBC4, 0x4DB6AC, 0x26A69A, 0x009688, 0x00897B, 0x00796B, 0x00695C,
+        0x004D40, 0xA7FFEB, 0x64FFDA, 0x1DE9B6, 0x00BFA5,
+    ];
+    pub const GREEN: [u32; 14] = [
+        0xE8F5E9, 0xC8E6C9, 0xA5D6A7, 0x81C784, 0x66BB6A, 0x4CAF50, 0x43A047, 0x388E3C, 0x2E7D32,
+        0x1B5E20, 0xB9F6CA, 0x69F0AE, 0x00E676, 0x00C853,
+    ];
+    pub const LIGHT_GREEN: [u32; 14] = [
+        0xF1F8E9, 0xDCEDC8, 0xC5E1A5, 0xAED581, 0x9CCC65, 0x8BC34A, 0x7CB342, 0x689F38, 0x558B2F,
+        0x33691E, 0xCCFF90, 0xB2FF59, 0x76FF03, 0x64DD17,
+    ];
+    pub const LIME: [u32; 14] = [
+        0xF9FBE7, 0xF0F4C3, 0xE6EE9C, 0xDCE775, 0xD4E157, 0xCDDC39, 0xC0CA33, 0xAFB42B, 0x9E9D24,
+        0x827717, 0xF4FF81, 0xEEFF41, 0xC6FF00, 0xAEEA00,
+    ];
+    pub const YELLOW: [u32; 14] = [
+        0xFFFDE7, 0xFFF9C4, 0xFFF59D, 0xFFF176, 0xFFEE58, 0xFFEB3B, 0xFDD835, 0xFBC02D, 0xF9A825,
+        0xF57F17, 0xFFFF8D, 0xFFFF00, 0xFFEA00, 0xFFD600,
+    ];
+    pub const AMBER: [u32; 14] = [
+        0xFFF8E1, 0xFFECB3, 0xFFE082, 0xFFD54F, 0xFFCA28, 0xFFC107, 0xFFB300, 0xFFA000, 0xFF8F00,
+        0xFF6F00, 0xFFE57F, 0xFFD740, 0xFFC400, 0xFFAB00,
+    ];
+    pub const ORANGE: [u32; 14] = [
+        0xFFF3E0, 0xFFE0B2, 0xFFCC80, 0xFFB74D, 0xFFA726, 0xFF9800, 0xFB8C00, 0xF57C00, 0xEF6C00,
+        0xE65100, 0xFFD180, 0xFFAB40, 0xFF9100, 0xFF6D00,
+    ];
+    pub const DEEP_ORANGE: [u32; 14] = [
+        0xFBE9E7, 0xFFCCBC, 0xFFAB91, 0xFF8A65, 0xFF7043, 0xFF5722, 0xF4511E, 0xE64A19, 0xD84315,
+        0xBF360C, 0xFF9E80, 0xFF6E40, 0xFF3D00, 0xDD2C00,
+    ];
+    pub const BROWN: [u32; 10] = [
+        0xEFEBE9, 0xD7CCC8, 0xBCAAA4, 0xA1887F, 0x8D6E63, 0x795548, 0x6D4C41, 0x5D4037, 0x4E342E,
+        0x3E2723,
+    ];
+    pub const GRAY: [u32; 10] = [
+        0xFAFAFA, 0xF5F5F5, 0xEEEEEE, 0xE0E0E0, 0xBDBDBD, 0x9E9E9E, 0x757575, 0x616161, 0x424242,
+        0x212121,
+    ];
+    pub const BLUE_GRAY: [u32; 10] = [
+        0xECEFF1, 0xCFD8DC, 0xB0BEC5, 0x90A4AE, 0x78909C, 0x607D8B, 0x546E7A, 0x455A64, 0x37474F,
+        0x263238,
+    ];
+}

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

@@ -0,0 +1,654 @@
+//! Represents the Tailwind CSS [default color palette][palette].
+//!
+//! [palette]: https://tailwindcss.com/docs/customizing-colors#default-color-palette
+//!
+//! There are 22 palettes. Each palette has 11 colors, with variants from 50 to 950. Black and White
+//! are also included for completeness and to avoid being affected by any terminal theme that might
+//! be in use.
+//!
+//! <style>
+//! .color { display: flex; align-items: center; }
+//! .color > div { width: 2rem; height: 2rem; }
+//! .color > div.name { width: 150px; !important; }
+//! </style>
+//! <div style="overflow-x: auto">
+//! <div style="display: flex; flex-direction:column; text-align: left">
+//! <div class="color" style="font-size:0.8em">
+//!     <div class="name"></div>
+//!     <div>C50</div> <div>C100</div> <div>C200</div> <div>C300</div> <div>C400</div>
+//!     <div>C500</div> <div>C600</div> <div>C700</div> <div>C800</div> <div>C900</div>
+//!     <div>C950</div>
+//! </div>
+//! <div class="color">
+//!     <div class="name">
+//!
+//! [`SLATE`]</div>
+//!     <div style="background-color: #f8fafc"></div> <div style="background-color: #f1f5f9"></div>
+//!     <div style="background-color: #e2e8f0"></div> <div style="background-color: #cbd5e1"></div>
+//!     <div style="background-color: #94a3b8"></div> <div style="background-color: #64748b"></div>
+//!     <div style="background-color: #475569"></div> <div style="background-color: #334155"></div>
+//!     <div style="background-color: #1e293b"></div> <div style="background-color: #0f172a"></div>
+//!     <div style="background-color: #020617"></div>
+//! </div>
+//! <div class="color">
+//!     <div class="name">
+//!
+//! [`GRAY`]</div>
+//!     <div style="background-color: #f9fafb"></div> <div style="background-color: #f3f4f6"></div>
+//!     <div style="background-color: #e5e7eb"></div> <div style="background-color: #d1d5db"></div>
+//!     <div style="background-color: #9ca3af"></div> <div style="background-color: #6b7280"></div>
+//!     <div style="background-color: #4b5563"></div> <div style="background-color: #374151"></div>
+//!     <div style="background-color: #1f2937"></div> <div style="background-color: #111827"></div>
+//!     <div style="background-color: #0a0a0a"></div>
+//! </div>
+//! <div class="color">
+//!     <div class="name">
+//!
+//! [`ZINC`]</div>
+//!     <div style="background-color: #fafafa"></div> <div style="background-color: #f5f5f5"></div>
+//!     <div style="background-color: #e5e5e5"></div> <div style="background-color: #d4d4d4"></div>
+//!     <div style="background-color: #a1a1aa"></div> <div style="background-color: #71717a"></div>
+//!     <div style="background-color: #52525b"></div> <div style="background-color: #404040"></div>
+//!     <div style="background-color: #262626"></div> <div style="background-color: #171717"></div>
+//!     <div style="background-color: #0a0a0a"></div>
+//! </div>
+//! <div class="color">
+//!     <div class="name">
+//!
+//! [`NEUTRAL`]</div>
+//!     <div style="background-color: #fafafa"></div> <div style="background-color: #f5f5f5"></div>
+//!     <div style="background-color: #e5e5e5"></div> <div style="background-color: #d4d4d4"></div>
+//!     <div style="background-color: #a3a3a3"></div> <div style="background-color: #737373"></div>
+//!     <div style="background-color: #525252"></div> <div style="background-color: #404040"></div>
+//!     <div style="background-color: #262626"></div> <div style="background-color: #171717"></div>
+//!     <div style="background-color: #0a0a0a"></div>
+//! </div>
+//! <div class="color">
+//!     <div class="name">
+//!
+//! [`STONE`]</div>
+//!     <div style="background-color: #fafaf9"></div> <div style="background-color: #f5f5f4"></div>
+//!     <div style="background-color: #e7e5e4"></div> <div style="background-color: #d6d3d1"></div>
+//!     <div style="background-color: #a8a29e"></div> <div style="background-color: #78716c"></div>
+//!     <div style="background-color: #57534e"></div> <div style="background-color: #44403c"></div>
+//!     <div style="background-color: #292524"></div> <div style="background-color: #1c1917"></div>
+//!     <div style="background-color: #0c0a09"></div>
+//! </div>
+//! <div class="color">
+//!     <div class="name">
+//!
+//! [`RED`]</div>
+//!     <div style="background-color: #fef2f2"></div> <div style="background-color: #fee2e2"></div>
+//!     <div style="background-color: #fecaca"></div> <div style="background-color: #fca5a5"></div>
+//!     <div style="background-color: #f87171"></div> <div style="background-color: #ef4444"></div>
+//!     <div style="background-color: #dc2626"></div> <div style="background-color: #b91c1c"></div>
+//!     <div style="background-color: #991b1b"></div> <div style="background-color: #7f1d1d"></div>
+//!     <div style="background-color: #450a0a"></div>
+//! </div>
+//! <div class="color">
+//!     <div class="name">
+//!
+//! [`ORANGE`]</div>
+//!     <div style="background-color: #fff7ed"></div> <div style="background-color: #ffedd5"></div>
+//!     <div style="background-color: #fed7aa"></div> <div style="background-color: #fdba74"></div>
+//!     <div style="background-color: #fb923c"></div> <div style="background-color: #f97316"></div>
+//!     <div style="background-color: #ea580c"></div> <div style="background-color: #c2410c"></div>
+//!     <div style="background-color: #9a3412"></div> <div style="background-color: #7c2d12"></div>
+//!     <div style="background-color: #431407"></div>
+//! </div>
+//! <div class="color">
+//!     <div class="name">
+//!
+//! [`AMBER`]</div>
+//!     <div style="background-color: #fffbeb"></div> <div style="background-color: #fef3c7"></div>
+//!     <div style="background-color: #fde68a"></div> <div style="background-color: #fcd34d"></div>
+//!     <div style="background-color: #fbbf24"></div> <div style="background-color: #f59e0b"></div>
+//!     <div style="background-color: #d97706"></div> <div style="background-color: #b45309"></div>
+//!     <div style="background-color: #92400e"></div> <div style="background-color: #78350f"></div>
+//!     <div style="background-color: #451a03"></div>
+//! </div>
+//! <div class="color">
+//!     <div class="name">
+//!
+//! [`YELLOW`]</div>
+//!     <div style="background-color: #fefce8"></div> <div style="background-color: #fef9c3"></div>
+//!     <div style="background-color: #fef08a"></div> <div style="background-color: #fde047"></div>
+//!     <div style="background-color: #facc15"></div> <div style="background-color: #eab308"></div>
+//!     <div style="background-color: #ca8a04"></div> <div style="background-color: #a16207"></div>
+//!     <div style="background-color: #854d0e"></div> <div style="background-color: #713f12"></div>
+//!     <div style="background-color: #422006"></div>
+//! </div>
+//! <div class="color">
+//!     <div class="name">
+//!
+//! [`LIME`]</div>
+//!     <div style="background-color: #f7fee7"></div> <div style="background-color: #ecfccb"></div>
+//!     <div style="background-color: #d9f99d"></div> <div style="background-color: #bef264"></div>
+//!     <div style="background-color: #a3e635"></div> <div style="background-color: #84cc16"></div>
+//!     <div style="background-color: #65a30d"></div> <div style="background-color: #4d7c0f"></div>
+//!     <div style="background-color: #3f6212"></div> <div style="background-color: #365314"></div>
+//!     <div style="background-color: #1a2e05"></div>
+//! </div>
+//! <div class="color">
+//!     <div class="name">
+//!
+//! [`GREEN`]</div>
+//!     <div style="background-color: #f0fdf4"></div> <div style="background-color: #dcfce7"></div>
+//!     <div style="background-color: #bbf7d0"></div> <div style="background-color: #86efac"></div>
+//!     <div style="background-color: #4ade80"></div> <div style="background-color: #22c55e"></div>
+//!     <div style="background-color: #16a34a"></div> <div style="background-color: #15803d"></div>
+//!     <div style="background-color: #166534"></div> <div style="background-color: #14532d"></div>
+//!     <div style="background-color: #052e16"></div>
+//! </div>
+//! <div class="color">
+//!     <div class="name">
+//!
+//! [`EMERALD`]</div>
+//!     <div style="background-color: #ecfdf5"></div> <div style="background-color: #d1fae5"></div>
+//!     <div style="background-color: #a7f3d0"></div> <div style="background-color: #6ee7b7"></div>
+//!     <div style="background-color: #34d399"></div> <div style="background-color: #10b981"></div>
+//!     <div style="background-color: #059669"></div> <div style="background-color: #047857"></div>
+//!     <div style="background-color: #065f46"></div> <div style="background-color: #064e3b"></div>
+//!     <div style="background-color: #022c22"></div>
+//! </div>
+//! <div class="color">
+//!     <div class="name">
+//!
+//! [`TEAL`]</div>
+//!     <div style="background-color: #f0fdfa"></div> <div style="background-color: #ccfbf1"></div>
+//!     <div style="background-color: #99f6e4"></div> <div style="background-color: #5eead4"></div>
+//!     <div style="background-color: #2dd4bf"></div> <div style="background-color: #14b8a6"></div>
+//!     <div style="background-color: #0d9488"></div> <div style="background-color: #0f766e"></div>
+//!     <div style="background-color: #115e59"></div> <div style="background-color: #134e4a"></div>
+//!     <div style="background-color: #042f2e"></div>
+//! </div>
+//! <div class="color">
+//!     <div class="name">
+//!
+//! [`CYAN`]</div>
+//!     <div style="background-color: #ecfeff"></div> <div style="background-color: #cffafe"></div>
+//!     <div style="background-color: #a5f3fc"></div> <div style="background-color: #67e8f9"></div>
+//!     <div style="background-color: #22d3ee"></div> <div style="background-color: #06b6d4"></div>
+//!     <div style="background-color: #0891b2"></div> <div style="background-color: #0e7490"></div>
+//!     <div style="background-color: #155e75"></div> <div style="background-color: #164e63"></div>
+//!     <div style="background-color: #083344"></div>
+//! </div>
+//! <div class="color">
+//!     <div class="name">
+//!
+//! [`SKY`]</div>
+//!     <div style="background-color: #f0f9ff"></div> <div style="background-color: #e0f2fe"></div>
+//!     <div style="background-color: #bae6fd"></div> <div style="background-color: #7dd3fc"></div>
+//!     <div style="background-color: #38bdf8"></div> <div style="background-color: #0ea5e9"></div>
+//!     <div style="background-color: #0284c7"></div> <div style="background-color: #0369a1"></div>
+//!     <div style="background-color: #075985"></div> <div style="background-color: #0c4a6e"></div>
+//!     <div style="background-color: #082f49"></div>
+//! </div>
+//! <div class="color">
+//!     <div class="name">
+//!
+//! [`BLUE`]</div>
+//!     <div style="background-color: #eff6ff"></div> <div style="background-color: #dbeafe"></div>
+//!     <div style="background-color: #bfdbfe"></div> <div style="background-color: #93c5fd"></div>
+//!     <div style="background-color: #60a5fa"></div> <div style="background-color: #3b82f6"></div>
+//!     <div style="background-color: #2563eb"></div> <div style="background-color: #1d4ed8"></div>
+//!     <div style="background-color: #1e40af"></div> <div style="background-color: #1e3a8a"></div>
+//!     <div style="background-color: #172554"></div>
+//! </div>
+//! <div class="color">
+//!     <div class="name">
+//!
+//! [`INDIGO`]</div>
+//!     <div style="background-color: #eef2ff"></div> <div style="background-color: #e0e7ff"></div>
+//!     <div style="background-color: #c7d2fe"></div> <div style="background-color: #a5b4fc"></div>
+//!     <div style="background-color: #818cf8"></div> <div style="background-color: #6366f1"></div>
+//!     <div style="background-color: #4f46e5"></div> <div style="background-color: #4338ca"></div>
+//!     <div style="background-color: #3730a3"></div> <div style="background-color: #312e81"></div>
+//!     <div style="background-color: #1e1b4b"></div>
+//! </div>
+//! <div class="color">
+//!     <div class="name">
+//!
+//! [`VIOLET`]</div>
+//!     <div style="background-color: #f5f3ff"></div> <div style="background-color: #ede9fe"></div>
+//!     <div style="background-color: #ddd6fe"></div> <div style="background-color: #c4b5fd"></div>
+//!     <div style="background-color: #a78bfa"></div> <div style="background-color: #8b5cf6"></div>
+//!     <div style="background-color: #7c3aed"></div> <div style="background-color: #6d28d9"></div>
+//!     <div style="background-color: #5b21b6"></div> <div style="background-color: #4c1d95"></div>
+//!     <div style="background-color: #2e1065"></div>
+//! </div>
+//! <div class="color">
+//!     <div class="name">
+//!
+//! [`PURPLE`]</div>
+//!     <div style="background-color: #faf5ff"></div> <div style="background-color: #f3e8ff"></div>
+//!     <div style="background-color: #e9d5ff"></div> <div style="background-color: #d8b4fe"></div>
+//!     <div style="background-color: #c084fc"></div> <div style="background-color: #a855f7"></div>
+//!     <div style="background-color: #9333ea"></div> <div style="background-color: #7e22ce"></div>
+//!     <div style="background-color: #6b21a8"></div> <div style="background-color: #581c87"></div>
+//!     <div style="background-color: #4c136e"></div>
+//! </div>
+//! <div class="color">
+//!     <div class="name">
+//!
+//! [`FUCHSIA`]</div>
+//!     <div style="background-color: #fdf4ff"></div> <div style="background-color: #fae8ff"></div>
+//!     <div style="background-color: #f5d0fe"></div> <div style="background-color: #f0abfc"></div>
+//!     <div style="background-color: #e879f9"></div> <div style="background-color: #d946ef"></div>
+//!     <div style="background-color: #c026d3"></div> <div style="background-color: #a21caf"></div>
+//!     <div style="background-color: #86198f"></div> <div style="background-color: #701a75"></div>
+//!     <div style="background-color: #4e145b"></div>
+//! </div>
+//! <div class="color">
+//!     <div class="name">
+//!
+//! [`PINK`]</div>
+//!     <div style="background-color: #fdf2f8"></div> <div style="background-color: #fce7f3"></div>
+//!     <div style="background-color: #fbcfe8"></div> <div style="background-color: #f9a8d4"></div>
+//!     <div style="background-color: #f472b6"></div> <div style="background-color: #ec4899"></div>
+//!     <div style="background-color: #db2777"></div> <div style="background-color: #be185d"></div>
+//!     <div style="background-color: #9d174d"></div> <div style="background-color: #831843"></div>
+//!     <div style="background-color: #5f0b37"></div>
+//! </div>
+//! <div class="color">
+//!    <div class="name">
+//!
+//! [`BLACK`]</div>
+//!     <div style="background-color: #000000; width:22rem"></div>
+//! </div>
+//! <div class="color">
+//!     <div class="name">
+//!
+//! [`WHITE`]</div>
+//!     <div style="background-color: #ffffff; width:22rem"></div>
+//! </div>
+//! </div>
+//! </div>
+//!
+//! # Example
+//!
+//! ```rust
+//! use ratatui_core::style::{
+//!     palette::tailwind::{BLUE, RED},
+//!     Color,
+//! };
+//!
+//! assert_eq!(RED.c500, Color::Rgb(239, 68, 68));
+//! assert_eq!(BLUE.c500, Color::Rgb(59, 130, 246));
+//! ```
+
+use crate::style::Color;
+
+pub struct Palette {
+    pub c50: Color,
+    pub c100: Color,
+    pub c200: Color,
+    pub c300: Color,
+    pub c400: Color,
+    pub c500: Color,
+    pub c600: Color,
+    pub c700: Color,
+    pub c800: Color,
+    pub c900: Color,
+    pub c950: Color,
+}
+
+#[rustfmt::skip]
+/// <style>.palette div{width:22rem;height:2rem}</style><div class="palette" style="display:flex;flex-direction:row"><div style="background-color: #000000"></div></div>
+pub const BLACK: Color = Color::from_u32(0x000000);
+
+#[rustfmt::skip]
+/// <style>.palette div{width:22rem;height:2rem}</style><div class="palette" style="display:flex;flex-direction:row"><div style="background-color: #ffffff"></div></div>
+pub const WHITE: Color = Color::from_u32(0xffffff);
+
+#[rustfmt::skip]
+/// <style>.palette div{width:2rem;height:2rem}</style><div class="palette" style="display:flex;flex-direction:row"><div style="background-color: #f8fafc"></div><div style="background-color: #f1f5f9"></div><div style="background-color: #e2e8f0"></div><div style="background-color: #cbd5e1"></div><div style="background-color: #94a3b8"></div><div style="background-color: #64748b"></div><div style="background-color: #475569"></div><div style="background-color: #334155"></div><div style="background-color: #1e293b"></div><div style="background-color: #0f172a"></div><div style="background-color: #020617"></div></div>
+pub const SLATE: Palette = Palette {
+    c50: Color::from_u32(0xf8fafc),
+    c100: Color::from_u32(0xf1f5f9),
+    c200: Color::from_u32(0xe2e8f0),
+    c300: Color::from_u32(0xcbd5e1),
+    c400: Color::from_u32(0x94a3b8),
+    c500: Color::from_u32(0x64748b),
+    c600: Color::from_u32(0x475569),
+    c700: Color::from_u32(0x334155),
+    c800: Color::from_u32(0x1e293b),
+    c900: Color::from_u32(0x0f172a),
+    c950: Color::from_u32(0x020617),
+};
+
+#[rustfmt::skip]
+/// <style>.palette div{width:2rem;height:2rem}</style><div class="palette" style="display:flex;flex-direction:row"><div style="background-color: #f9fafb"></div><div style="background-color: #f3f4f6"></div><div style="background-color: #e5e7eb"></div><div style="background-color: #d1d5db"></div><div style="background-color: #9ca3af"></div><div style="background-color: #6b7280"></div><div style="background-color: #4b5563"></div><div style="background-color: #374151"></div><div style="background-color: #1f2937"></div><div style="background-color: #111827"></div><div style="background-color: #030712"></div></div>
+pub const GRAY: Palette = Palette {
+    c50: Color::from_u32(0xf9fafb),
+    c100: Color::from_u32(0xf3f4f6),
+    c200: Color::from_u32(0xe5e7eb),
+    c300: Color::from_u32(0xd1d5db),
+    c400: Color::from_u32(0x9ca3af),
+    c500: Color::from_u32(0x6b7280),
+    c600: Color::from_u32(0x4b5563),
+    c700: Color::from_u32(0x374151),
+    c800: Color::from_u32(0x1f2937),
+    c900: Color::from_u32(0x111827),
+    c950: Color::from_u32(0x030712),
+};
+
+#[rustfmt::skip]
+/// <style>.palette div{width:2rem;height:2rem}</style><div class="palette" style="display:flex;flex-direction:row"><div style="background-color: #fafafa"></div><div style="background-color: #f5f5f5"></div><div style="background-color: #e5e5e5"></div><div style="background-color: #d4d4d4"></div><div style="background-color: #a1a1aa"></div><div style="background-color: #71717a"></div><div style="background-color: #52525b"></div><div style="background-color: #404040"></div><div style="background-color: #262626"></div><div style="background-color: #171717"></div><div style="background-color: #09090b"></div></div>
+pub const ZINC: Palette = Palette {
+    c50: Color::from_u32(0xfafafa),
+    c100: Color::from_u32(0xf4f4f5),
+    c200: Color::from_u32(0xe4e4e7),
+    c300: Color::from_u32(0xd4d4d8),
+    c400: Color::from_u32(0xa1a1aa),
+    c500: Color::from_u32(0x71717a),
+    c600: Color::from_u32(0x52525b),
+    c700: Color::from_u32(0x3f3f46),
+    c800: Color::from_u32(0x27272a),
+    c900: Color::from_u32(0x18181b),
+    c950: Color::from_u32(0x09090b),
+};
+
+#[rustfmt::skip]
+/// <style>.palette div{width:2rem;height:2rem}</style><div class="palette" style="display:flex;flex-direction:row"><div style="background-color: #fafafa"></div><div style="background-color: #f5f5f5"></div><div style="background-color: #e5e5e5"></div><div style="background-color: #d4d4d4"></div><div style="background-color: #a3a3a3"></div><div style="background-color: #737373"></div><div style="background-color: #525252"></div><div style="background-color: #404040"></div><div style="background-color: #262626"></div><div style="background-color: #171717"></div><div style="background-color: #0a0a0a"></div></div>
+pub const NEUTRAL: Palette = Palette {
+    c50: Color::from_u32(0xfafafa),
+    c100: Color::from_u32(0xf5f5f5),
+    c200: Color::from_u32(0xe5e5e5),
+    c300: Color::from_u32(0xd4d4d4),
+    c400: Color::from_u32(0xa3a3a3),
+    c500: Color::from_u32(0x737373),
+    c600: Color::from_u32(0x525252),
+    c700: Color::from_u32(0x404040),
+    c800: Color::from_u32(0x262626),
+    c900: Color::from_u32(0x171717),
+    c950: Color::from_u32(0x0a0a0a),
+};
+
+#[rustfmt::skip]
+/// <style>.palette div{width:2rem;height:2rem}</style><div class="palette" style="display:flex;flex-direction:row"><div style="background-color: #fafaf9"></div><div style="background-color: #f5f5f4"></div><div style="background-color: #e7e5e4"></div><div style="background-color: #d6d3d1"></div><div style="background-color: #a8a29e"></div><div style="background-color: #78716c"></div><div style="background-color: #57534e"></div><div style="background-color: #44403c"></div><div style="background-color: #292524"></div><div style="background-color: #1c1917"></div><div style="background-color: #0c0a09"></div></div>
+pub const STONE: Palette = Palette {
+    c50: Color::from_u32(0xfafaf9),
+    c100: Color::from_u32(0xf5f5f4),
+    c200: Color::from_u32(0xe7e5e4),
+    c300: Color::from_u32(0xd6d3d1),
+    c400: Color::from_u32(0xa8a29e),
+    c500: Color::from_u32(0x78716c),
+    c600: Color::from_u32(0x57534e),
+    c700: Color::from_u32(0x44403c),
+    c800: Color::from_u32(0x292524),
+    c900: Color::from_u32(0x1c1917),
+    c950: Color::from_u32(0x0c0a09),
+};
+
+#[rustfmt::skip]
+/// <style>.palette div{width:2rem;height:2rem}</style><div class="palette" style="display:flex;flex-direction:row"><div style="background-color: #fef2f2"></div><div style="background-color: #fee2e2"></div><div style="background-color: #fecaca"></div><div style="background-color: #fca5a5"></div><div style="background-color: #f87171"></div><div style="background-color: #ef4444"></div><div style="background-color: #dc2626"></div><div style="background-color: #b91c1c"></div><div style="background-color: #991b1b"></div><div style="background-color: #7f1d1d"></div><div style="background-color: #450a0a"></div></div>
+pub const RED: Palette = Palette {
+    c50: Color::from_u32(0xfef2f2),
+    c100: Color::from_u32(0xfee2e2),
+    c200: Color::from_u32(0xfecaca),
+    c300: Color::from_u32(0xfca5a5),
+    c400: Color::from_u32(0xf87171),
+    c500: Color::from_u32(0xef4444),
+    c600: Color::from_u32(0xdc2626),
+    c700: Color::from_u32(0xb91c1c),
+    c800: Color::from_u32(0x991b1b),
+    c900: Color::from_u32(0x7f1d1d),
+    c950: Color::from_u32(0x450a0a),
+};
+
+#[rustfmt::skip]
+/// <style>.palette div{width:2rem;height:2rem}</style><div class="palette" style="display:flex;flex-direction:row"><div style="background-color: #fff7ed"></div><div style="background-color: #ffedd5"></div><div style="background-color: #fed7aa"></div><div style="background-color: #fdba74"></div><div style="background-color: #fb923c"></div><div style="background-color: #f97316"></div><div style="background-color: #ea580c"></div><div style="background-color: #c2410c"></div><div style="background-color: #9a3412"></div><div style="background-color: #7c2d12"></div><div style="background-color: #431407"></div></div>
+pub const ORANGE: Palette = Palette {
+    c50: Color::from_u32(0xfff7ed),
+    c100: Color::from_u32(0xffedd5),
+    c200: Color::from_u32(0xfed7aa),
+    c300: Color::from_u32(0xfdba74),
+    c400: Color::from_u32(0xfb923c),
+    c500: Color::from_u32(0xf97316),
+    c600: Color::from_u32(0xea580c),
+    c700: Color::from_u32(0xc2410c),
+    c800: Color::from_u32(0x9a3412),
+    c900: Color::from_u32(0x7c2d12),
+    c950: Color::from_u32(0x431407),
+};
+
+#[rustfmt::skip]
+/// <style>.palette div{width:2rem;height:2rem}</style><div class="palette" style="display:flex;flex-direction:row"><div style="background-color: #fffbeb"></div><div style="background-color: #fef3c7"></div><div style="background-color: #fde68a"></div><div style="background-color: #fcd34d"></div><div style="background-color: #fbbf24"></div><div style="background-color: #f59e0b"></div><div style="background-color: #d97706"></div><div style="background-color: #b45309"></div><div style="background-color: #92400e"></div><div style="background-color: #78350f"></div><div style="background-color: #451a03"></div></div>
+pub const AMBER: Palette = Palette {
+    c50: Color::from_u32(0xfffbeb),
+    c100: Color::from_u32(0xfef3c7),
+    c200: Color::from_u32(0xfde68a),
+    c300: Color::from_u32(0xfcd34d),
+    c400: Color::from_u32(0xfbbf24),
+    c500: Color::from_u32(0xf59e0b),
+    c600: Color::from_u32(0xd97706),
+    c700: Color::from_u32(0xb45309),
+    c800: Color::from_u32(0x92400e),
+    c900: Color::from_u32(0x78350f),
+    c950: Color::from_u32(0x451a03),
+};
+
+#[rustfmt::skip]
+/// <style>.palette div{width:2rem;height:2rem}</style><div class="palette" style="display:flex;flex-direction:row"><div style="background-color: #fefce8"></div><div style="background-color: #fef9c3"></div><div style="background-color: #fef08a"></div><div style="background-color: #fde047"></div><div style="background-color: #facc15"></div><div style="background-color: #eab308"></div><div style="background-color: #ca8a04"></div><div style="background-color: #a16207"></div><div style="background-color: #854d0e"></div><div style="background-color: #713f12"></div><div style="background-color: #422006"></div></div>
+pub const YELLOW: Palette = Palette {
+    c50: Color::from_u32(0xfefce8),
+    c100: Color::from_u32(0xfef9c3),
+    c200: Color::from_u32(0xfef08a),
+    c300: Color::from_u32(0xfde047),
+    c400: Color::from_u32(0xfacc15),
+    c500: Color::from_u32(0xeab308),
+    c600: Color::from_u32(0xca8a04),
+    c700: Color::from_u32(0xa16207),
+    c800: Color::from_u32(0x854d0e),
+    c900: Color::from_u32(0x713f12),
+    c950: Color::from_u32(0x422006),
+};
+
+#[rustfmt::skip]
+/// <style>.palette div{width:2rem;height:2rem}</style><div class="palette" style="display:flex;flex-direction:row"><div style="background-color: #f7fee7"></div><div style="background-color: #ecfccb"></div><div style="background-color: #d9f99d"></div><div style="background-color: #bef264"></div><div style="background-color: #a3e635"></div><div style="background-color: #84cc16"></div><div style="background-color: #65a30d"></div><div style="background-color: #4d7c0f"></div><div style="background-color: #3f6212"></div><div style="background-color: #365314"></div><div style="background-color: #1a2e05"></div></div>
+pub const LIME: Palette = Palette {
+    c50: Color::from_u32(0xf7fee7),
+    c100: Color::from_u32(0xecfccb),
+    c200: Color::from_u32(0xd9f99d),
+    c300: Color::from_u32(0xbef264),
+    c400: Color::from_u32(0xa3e635),
+    c500: Color::from_u32(0x84cc16),
+    c600: Color::from_u32(0x65a30d),
+    c700: Color::from_u32(0x4d7c0f),
+    c800: Color::from_u32(0x3f6212),
+    c900: Color::from_u32(0x365314),
+    c950: Color::from_u32(0x1a2e05),
+};
+
+#[rustfmt::skip]
+/// <style>.palette div{width:2rem;height:2rem}</style><div class="palette" style="display:flex;flex-direction:row"><div style="background-color: #f0fdf4"></div><div style="background-color: #dcfce7"></div><div style="background-color: #bbf7d0"></div><div style="background-color: #86efac"></div><div style="background-color: #4ade80"></div><div style="background-color: #22c55e"></div><div style="background-color: #16a34a"></div><div style="background-color: #15803d"></div><div style="background-color: #166534"></div><div style="background-color: #14532d"></div><div style="background-color: #052e16"></div></div>
+pub const GREEN: Palette = Palette {
+    c50: Color::from_u32(0xf0fdf4),
+    c100: Color::from_u32(0xdcfce7),
+    c200: Color::from_u32(0xbbf7d0),
+    c300: Color::from_u32(0x86efac),
+    c400: Color::from_u32(0x4ade80),
+    c500: Color::from_u32(0x22c55e),
+    c600: Color::from_u32(0x16a34a),
+    c700: Color::from_u32(0x15803d),
+    c800: Color::from_u32(0x166534),
+    c900: Color::from_u32(0x14532d),
+    c950: Color::from_u32(0x052e16),
+};
+
+#[rustfmt::skip]
+/// <style>.palette div{width:2rem;height:2rem}</style><div class="palette" style="display:flex;flex-direction:row"><div style="background-color: #f0fdfa"></div><div style="background-color: #ccfbf1"></div><div style="background-color: #99f6e4"></div><div style="background-color: #5eead4"></div><div style="background-color: #2dd4bf"></div><div style="background-color: #14b8a6"></div><div style="background-color: #0d9488"></div><div style="background-color: #0f766e"></div><div style="background-color: #115e59"></div><div style="background-color: #134e4a"></div><div style="background-color: #042f2e"></div></div>
+pub const EMERALD: Palette = Palette {
+    c50: Color::from_u32(0xecfdf5),
+    c100: Color::from_u32(0xd1fae5),
+    c200: Color::from_u32(0xa7f3d0),
+    c300: Color::from_u32(0x6ee7b7),
+    c400: Color::from_u32(0x34d399),
+    c500: Color::from_u32(0x10b981),
+    c600: Color::from_u32(0x059669),
+    c700: Color::from_u32(0x047857),
+    c800: Color::from_u32(0x065f46),
+    c900: Color::from_u32(0x064e3b),
+    c950: Color::from_u32(0x022c22),
+};
+
+#[rustfmt::skip]
+/// <style>.palette div{width:2rem;height:2rem}</style><div class="palette" style="display:flex;flex-direction:row"><div style="background-color: #f5fdf4"></div><div style="background-color: #e7f9e7"></div><div style="background-color: #c6f6d5"></div><div style="background-color: #9ae6b4"></div><div style="background-color: #68d391"></div><div style="background-color: #48bb78"></div><div style="background-color: #38a169"></div><div style="background-color: #2f855a"></div><div style="background-color: #276749"></div><div style="background-color: #22543d"></div><div style="background-color: #0d3321"></div></div>
+pub const TEAL: Palette = Palette {
+    c50: Color::from_u32(0xf0fdfa),
+    c100: Color::from_u32(0xccfbf1),
+    c200: Color::from_u32(0x99f6e4),
+    c300: Color::from_u32(0x5eead4),
+    c400: Color::from_u32(0x2dd4bf),
+    c500: Color::from_u32(0x14b8a6),
+    c600: Color::from_u32(0x0d9488),
+    c700: Color::from_u32(0x0f766e),
+    c800: Color::from_u32(0x115e59),
+    c900: Color::from_u32(0x134e4a),
+    c950: Color::from_u32(0x042f2e),
+};
+
+#[rustfmt::skip]
+/// <style>.palette div{width:2rem;height:2rem}</style><div class="palette" style="display:flex;flex-direction:row"><div style="background-color: #ecfeff"></div><div style="background-color: #cffafe"></div><div style="background-color: #a5f3fc"></div><div style="background-color: #67e8f9"></div><div style="background-color: #22d3ee"></div><div style="background-color: #06b6d4"></div><div style="background-color: #0891b2"></div><div style="background-color: #0e7490"></div><div style="background-color: #155e75"></div><div style="background-color: #164e63"></div><div style="background-color: #083344"></div></div>
+pub const CYAN: Palette = Palette {
+    c50: Color::from_u32(0xecfeff),
+    c100: Color::from_u32(0xcffafe),
+    c200: Color::from_u32(0xa5f3fc),
+    c300: Color::from_u32(0x67e8f9),
+    c400: Color::from_u32(0x22d3ee),
+    c500: Color::from_u32(0x06b6d4),
+    c600: Color::from_u32(0x0891b2),
+    c700: Color::from_u32(0x0e7490),
+    c800: Color::from_u32(0x155e75),
+    c900: Color::from_u32(0x164e63),
+    c950: Color::from_u32(0x083344),
+};
+
+#[rustfmt::skip]
+/// <style>.palette div{width:22rem;height:2rem}</style><div class="palette" style="display:flex;flex-direction:row"><div style="background-color: #f0f9ff"></div><div style="background-color: #e0f2fe"></div><div style="background-color: #bae6fd"></div><div style="background-color: #7dd3fc"></div><div style="background-color: #38bdf8"></div><div style="background-color: #0ea5e9"></div><div style="background-color: #0284c7"></div><div style="background-color: #0369a1"></div><div style="background-color: #075985"></div><div style="background-color: #0c4a6e"></div><div style="background-color: #082f49"></div></div>
+pub const SKY: Palette = Palette {
+    c50: Color::from_u32(0xf0f9ff),
+    c100: Color::from_u32(0xe0f2fe),
+    c200: Color::from_u32(0xbae6fd),
+    c300: Color::from_u32(0x7dd3fc),
+    c400: Color::from_u32(0x38bdf8),
+    c500: Color::from_u32(0x0ea5e9),
+    c600: Color::from_u32(0x0284c7),
+    c700: Color::from_u32(0x0369a1),
+    c800: Color::from_u32(0x075985),
+    c900: Color::from_u32(0x0c4a6e),
+    c950: Color::from_u32(0x082f49),
+};
+
+#[rustfmt::skip]
+/// <style>.palette div{width:22rem;height:2rem}</style><div class="palette" style="display:flex;flex-direction:row"><div style="background-color: #eff6ff"></div><div style="background-color: #dbeafe"></div><div style="background-color: #bfdbfe"></div><div style="background-color: #93c5fd"></div><div style="background-color: #60a5fa"></div><div style="background-color: #3b82f6"></div><div style="background-color: #2563eb"></div><div style="background-color: #1d4ed8"></div><div style="background-color: #1e40af"></div><div style="background-color: #1e3a8a"></div><div style="background-color: #172554"></div></div>
+pub const BLUE: Palette = Palette {
+    c50: Color::from_u32(0xeff6ff),
+    c100: Color::from_u32(0xdbeafe),
+    c200: Color::from_u32(0xbfdbfe),
+    c300: Color::from_u32(0x93c5fd),
+    c400: Color::from_u32(0x60a5fa),
+    c500: Color::from_u32(0x3b82f6),
+    c600: Color::from_u32(0x2563eb),
+    c700: Color::from_u32(0x1d4ed8),
+    c800: Color::from_u32(0x1e40af),
+    c900: Color::from_u32(0x1e3a8a),
+    c950: Color::from_u32(0x172554),
+};
+
+#[rustfmt::skip]
+/// <style>.palette div{width:22rem;height:2rem}</style><div class="palette" style="display:flex;flex-direction:row"><div style="background-color: #eef2ff"></div><div style="background-color: #e0e7ff"></div><div style="background-color: #c7d2fe"></div><div style="background-color: #a5b4fc"></div><div style="background-color: #818cf8"></div><div style="background-color: #6366f1"></div><div style="background-color: #4f46e5"></div><div style="background-color: #4338ca"></div><div style="background-color: #3730a3"></div><div style="background-color: #312e81"></div><div style="background-color: #1e1b4b"></div></div>
+pub const INDIGO: Palette = Palette {
+    c50: Color::from_u32(0xeef2ff),
+    c100: Color::from_u32(0xe0e7ff),
+    c200: Color::from_u32(0xc7d2fe),
+    c300: Color::from_u32(0xa5b4fc),
+    c400: Color::from_u32(0x818cf8),
+    c500: Color::from_u32(0x6366f1),
+    c600: Color::from_u32(0x4f46e5),
+    c700: Color::from_u32(0x4338ca),
+    c800: Color::from_u32(0x3730a3),
+    c900: Color::from_u32(0x312e81),
+    c950: Color::from_u32(0x1e1b4b),
+};
+
+#[rustfmt::skip]
+/// <style>.palette div{width:22rem;height:2rem}</style><div class="palette" style="display:flex;flex-direction:row"><div style="background-color: #f5f3ff"></div><div style="background-color: #ede9fe"></div><div style="background-color: #ddd6fe"></div><div style="background-color: #c4b5fd"></div><div style="background-color: #a78bfa"></div><div style="background-color: #8b5cf6"></div><div style="background-color: #7c3aed"></div><div style="background-color: #6d28d9"></div><div style="background-color: #5b21b6"></div><div style="background-color: #4c1d95"></div><div style="background-color: #2e1065"></div></div>
+pub const VIOLET: Palette = Palette {
+    c50: Color::from_u32(0xf5f3ff),
+    c100: Color::from_u32(0xede9fe),
+    c200: Color::from_u32(0xddd6fe),
+    c300: Color::from_u32(0xc4b5fd),
+    c400: Color::from_u32(0xa78bfa),
+    c500: Color::from_u32(0x8b5cf6),
+    c600: Color::from_u32(0x7c3aed),
+    c700: Color::from_u32(0x6d28d9),
+    c800: Color::from_u32(0x5b21b6),
+    c900: Color::from_u32(0x4c1d95),
+    c950: Color::from_u32(0x2e1065),
+};
+
+#[rustfmt::skip]
+/// <style>.palette div{width:22rem;height:2rem}</style><div class="palette" style="display:flex;flex-direction:row"><div style="background-color: #faf5ff"></div><div style="background-color: #f3e8ff"></div><div style="background-color: #e9d5ff"></div><div style="background-color: #d8b4fe"></div><div style="background-color: #c084fc"></div><div style="background-color: #a855f7"></div><div style="background-color: #9333ea"></div><div style="background-color: #7e22ce"></div><div style="background-color: #6b21a8"></div><div style="background-color: #581c87"></div><div style="background-color: #3b0764"></div></div>
+pub const PURPLE: Palette = Palette {
+    c50: Color::from_u32(0xfaf5ff),
+    c100: Color::from_u32(0xf3e8ff),
+    c200: Color::from_u32(0xe9d5ff),
+    c300: Color::from_u32(0xd8b4fe),
+    c400: Color::from_u32(0xc084fc),
+    c500: Color::from_u32(0xa855f7),
+    c600: Color::from_u32(0x9333ea),
+    c700: Color::from_u32(0x7e22ce),
+    c800: Color::from_u32(0x6b21a8),
+    c900: Color::from_u32(0x581c87),
+    c950: Color::from_u32(0x3b0764),
+};
+
+#[rustfmt::skip]
+/// <style>.palette div{width:22rem;height:2rem}</style><div class="palette" style="display:flex;flex-direction:row"><div style="background-color: #fdf4ff"></div><div style="background-color: #fae8ff"></div><div style="background-color: #f5d0fe"></div><div style="background-color: #f0abfc"></div><div style="background-color: #e879f9"></div><div style="background-color: #d946ef"></div><div style="background-color: #c026d3"></div><div style="background-color: #a21caf"></div><div style="background-color: #86198f"></div><div style="background-color: #701a75"></div><div style="background-color: #4a044e"></div></div>
+pub const FUCHSIA: Palette = Palette {
+    c50: Color::from_u32(0xfdf4ff),
+    c100: Color::from_u32(0xfae8ff),
+    c200: Color::from_u32(0xf5d0fe),
+    c300: Color::from_u32(0xf0abfc),
+    c400: Color::from_u32(0xe879f9),
+    c500: Color::from_u32(0xd946ef),
+    c600: Color::from_u32(0xc026d3),
+    c700: Color::from_u32(0xa21caf),
+    c800: Color::from_u32(0x86198f),
+    c900: Color::from_u32(0x701a75),
+    c950: Color::from_u32(0x4a044e),
+};
+
+#[rustfmt::skip]
+/// <style>.palette div{width:22rem;height:2rem}</style><div class="palette" style="display:flex;flex-direction:row"><div style="background-color: #fdf2f8"></div><div style="background-color: #fce7f3"></div><div style="background-color: #fbcfe8"></div><div style="background-color: #f9a8d4"></div><div style="background-color: #f472b6"></div><div style="background-color: #ec4899"></div><div style="background-color: #db2777"></div><div style="background-color: #be185d"></div><div style="background-color: #9d174d"></div><div style="background-color: #831843"></div><div style="background-color: #500724"></div></div>
+pub const PINK: Palette = Palette {
+    c50: Color::from_u32(0xfdf2f8),
+    c100: Color::from_u32(0xfce7f3),
+    c200: Color::from_u32(0xfbcfe8),
+    c300: Color::from_u32(0xf9a8d4),
+    c400: Color::from_u32(0xf472b6),
+    c500: Color::from_u32(0xec4899),
+    c600: Color::from_u32(0xdb2777),
+    c700: Color::from_u32(0xbe185d),
+    c800: Color::from_u32(0x9d174d),
+    c900: Color::from_u32(0x831843),
+    c950: Color::from_u32(0x500724),
+};
+
+#[rustfmt::skip]
+/// <style>.palette div{width:22rem;height:2rem}</style><div class="palette" style="display:flex;flex-direction:row"><div style="background-color: #fff1f2"></div><div style="background-color: #ffe4e6"></div><div style="background-color: #fecdd3"></div><div style="background-color: #fda4af"></div><div style="background-color: #fb7185"></div><div style="background-color: #f43f5e"></div><div style="background-color: #e11d48"></div><div style="background-color: #be123c"></div><div style="background-color: #9f1239"></div><div style="background-color: #881337"></div><div style="background-color: #4c0519"></div></div>
+pub const ROSE: Palette = Palette {
+    c50: Color::from_u32(0xfff1f2),
+    c100: Color::from_u32(0xffe4e6),
+    c200: Color::from_u32(0xfecdd3),
+    c300: Color::from_u32(0xfda4af),
+    c400: Color::from_u32(0xfb7185),
+    c500: Color::from_u32(0xf43f5e),
+    c600: Color::from_u32(0xe11d48),
+    c700: Color::from_u32(0xbe123c),
+    c800: Color::from_u32(0x9f1239),
+    c900: Color::from_u32(0x881337),
+    c950: Color::from_u32(0x4c0519),
+};

ratatui-core/src/style/palette_conversion.rs

@@ -0,0 +1,83 @@
+//! Conversions from colors in the `palette` crate to [`Color`].
+
+use ::palette::{
+    bool_mask::LazySelect,
+    num::{Arithmetics, MulSub, PartialCmp, Powf, Real},
+    LinSrgb,
+};
+use palette::{stimulus::IntoStimulus, Srgb};
+
+use crate::style::Color;
+
+/// Convert an [`palette::Srgb`] color to a [`Color`].
+///
+/// # Examples
+///
+/// ```
+/// use palette::Srgb;
+/// 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));
+/// ```
+impl<T: IntoStimulus<u8>> From<Srgb<T>> for Color {
+    fn from(color: Srgb<T>) -> Self {
+        let (red, green, blue) = color.into_format().into_components();
+        Self::Rgb(red, green, blue)
+    }
+}
+
+/// Convert a [`palette::LinSrgb`] color to a [`Color`].
+///
+/// Note: this conversion only works for floating point linear sRGB colors. If you have a linear
+/// sRGB color in another format, you need to convert it to floating point first.
+///
+/// # Examples
+///
+/// ```
+/// use palette::LinSrgb;
+/// 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));
+/// ```
+impl<T: IntoStimulus<u8>> From<LinSrgb<T>> for Color
+where
+    T: Real + Powf + MulSub + Arithmetics + PartialCmp + Clone,
+    T::Mask: LazySelect<T>,
+{
+    fn from(color: LinSrgb<T>) -> Self {
+        let srgb_color = Srgb::<T>::from_linear(color);
+        Self::from(srgb_color)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn from_srgb() {
+        const RED: Color = Color::Rgb(255, 0, 0);
+        assert_eq!(Color::from(Srgb::new(255u8, 0, 0)), RED);
+        assert_eq!(Color::from(Srgb::new(65535u16, 0, 0)), RED);
+        assert_eq!(Color::from(Srgb::new(1.0f32, 0.0, 0.0)), RED);
+
+        assert_eq!(
+            Color::from(Srgb::new(0.5f32, 0.5, 0.5)),
+            Color::Rgb(128, 128, 128)
+        );
+    }
+
+    #[test]
+    fn from_lin_srgb() {
+        const RED: Color = Color::Rgb(255, 0, 0);
+        assert_eq!(Color::from(LinSrgb::new(1.0f32, 0.0, 0.0)), RED);
+        assert_eq!(Color::from(LinSrgb::new(1.0f64, 0.0, 0.0)), RED);
+
+        assert_eq!(
+            Color::from(LinSrgb::new(0.5f32, 0.5, 0.5)),
+            Color::Rgb(188, 188, 188)
+        );
+    }
+}

ratatui-core/src/style/stylize.rs

@@ -1,3 +1,5 @@
+use std::fmt;
+
 use paste::paste;
 
 use crate::{
@@ -13,8 +15,83 @@ use crate::{
 pub trait Styled {
     type Item;
 
+    /// Returns the style of the object.
     fn style(&self) -> Style;
-    fn set_style(self, style: Style) -> Self::Item;
+
+    /// Sets the style of the object.
+    ///
+    /// `style` accepts any type that is convertible to [`Style`] (e.g. [`Style`], [`Color`], or
+    /// your own type that implements [`Into<Style>`]).
+    fn set_style<S: Into<Style>>(self, style: S) -> Self::Item;
+}
+
+/// A helper struct to make it easy to debug using the `Stylize` method names
+pub(crate) struct ColorDebug {
+    pub kind: ColorDebugKind,
+    pub color: Color,
+}
+
+#[derive(Debug, Clone, Copy, Eq, PartialEq, Hash)]
+pub(crate) enum ColorDebugKind {
+    Foreground,
+    Background,
+    #[cfg(feature = "underline-color")]
+    Underline,
+}
+
+impl fmt::Debug for ColorDebug {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        #[cfg(feature = "underline-color")]
+        let is_underline = self.kind == ColorDebugKind::Underline;
+        #[cfg(not(feature = "underline-color"))]
+        let is_underline = false;
+        if is_underline
+            || matches!(
+                self.color,
+                Color::Reset | Color::Indexed(_) | Color::Rgb(_, _, _)
+            )
+        {
+            match self.kind {
+                ColorDebugKind::Foreground => write!(f, ".fg(")?,
+                ColorDebugKind::Background => write!(f, ".bg(")?,
+                #[cfg(feature = "underline-color")]
+                ColorDebugKind::Underline => write!(f, ".underline_color(")?,
+            }
+            write!(f, "Color::{:?}", self.color)?;
+            write!(f, ")")?;
+            return Ok(());
+        }
+
+        match self.kind {
+            ColorDebugKind::Foreground => write!(f, ".")?,
+            ColorDebugKind::Background => write!(f, ".on_")?,
+            // TODO: .underline_color_xxx is not implemented on Stylize yet, but it should be
+            #[cfg(feature = "underline-color")]
+            ColorDebugKind::Underline => {
+                unreachable!("covered by the first part of the if statement")
+            }
+        }
+        match self.color {
+            Color::Black => write!(f, "black")?,
+            Color::Red => write!(f, "red")?,
+            Color::Green => write!(f, "green")?,
+            Color::Yellow => write!(f, "yellow")?,
+            Color::Blue => write!(f, "blue")?,
+            Color::Magenta => write!(f, "magenta")?,
+            Color::Cyan => write!(f, "cyan")?,
+            Color::Gray => write!(f, "gray")?,
+            Color::DarkGray => write!(f, "dark_gray")?,
+            Color::LightRed => write!(f, "light_red")?,
+            Color::LightGreen => write!(f, "light_green")?,
+            Color::LightYellow => write!(f, "light_yellow")?,
+            Color::LightBlue => write!(f, "light_blue")?,
+            Color::LightMagenta => write!(f, "light_magenta")?,
+            Color::LightCyan => write!(f, "light_cyan")?,
+            Color::White => write!(f, "white")?,
+            _ => unreachable!("covered by the first part of the if statement"),
+        }
+        write!(f, "()")
+    }
 }
 
 /// Generates two methods for each color, one for setting the foreground color (`red()`, `blue()`,
@@ -40,11 +117,13 @@ macro_rules! color {
     ( $color:ident ) => {
         paste! {
             #[doc = "Sets the foreground color to [`" $color "`](Color::" $color:camel ")."]
+            #[must_use = concat!("`", stringify!($color), "` returns the modified style without modifying the original")]
             fn $color(self) -> T {
                 self.fg(Color::[<$color:camel>])
             }
 
             #[doc = "Sets the background color to [`" $color "`](Color::" $color:camel ")."]
+            #[must_use = concat!("`on_", stringify!($color), "` returns the modified style without modifying the original")]
             fn [<on_ $color>](self) -> T {
                 self.bg(Color::[<$color:camel>])
             }
@@ -76,6 +155,7 @@ macro_rules! modifier {
     ( $modifier:ident ) => {
         paste! {
             #[doc = "Adds the [`" $modifier:upper "`](Modifier::" $modifier:upper ") modifier."]
+            #[must_use = concat!("`", stringify!($modifier), "` returns the modified style without modifying the original")]
             fn [<$modifier>](self) -> T {
                 self.add_modifier(Modifier::[<$modifier:upper>])
             }
@@ -83,6 +163,7 @@ macro_rules! modifier {
 
         paste! {
             #[doc = "Removes the [`" $modifier:upper "`](Modifier::" $modifier:upper ") modifier."]
+            #[must_use = concat!("`not_", stringify!($modifier), "` returns the modified style without modifying the original")]
             fn [<not_ $modifier>](self) -> T {
                 self.remove_modifier(Modifier::[<$modifier:upper>])
             }
@@ -114,8 +195,12 @@ macro_rules! modifier {
 /// by `not_`). The `reset()` method is also provided to reset the style.
 ///
 /// # Examples
-/// ```
-/// use ratatui::{prelude::*, widgets::*};
+/// ```ignore
+/// use ratatui_core::{
+///     style::{Color, Modifier, Style, Stylize},
+///     text::Line,
+///     widgets::{Block, Paragraph},
+/// };
 ///
 /// let span = "hello".red().on_blue().bold();
 /// let line = Line::from(vec![
@@ -123,13 +208,18 @@ macro_rules! modifier {
 ///     "world".green().on_yellow().not_bold(),
 /// ]);
 /// let paragraph = Paragraph::new(line).italic().underlined();
-/// let block = Block::default().title("Title").borders(Borders::ALL).on_white().bold();
+/// let block = Block::bordered().title("Title").on_white().bold();
 /// ```
 pub trait Stylize<'a, T>: Sized {
-    fn bg(self, color: Color) -> T;
-    fn fg<S: Into<Color>>(self, color: S) -> T;
+    #[must_use = "`bg` returns the modified style without modifying the original"]
+    fn bg<C: Into<Color>>(self, color: C) -> T;
+    #[must_use = "`fg` returns the modified style without modifying the original"]
+    fn fg<C: Into<Color>>(self, color: C) -> T;
+    #[must_use = "`reset` returns the modified style without modifying the original"]
     fn reset(self) -> T;
+    #[must_use = "`add_modifier` returns the modified style without modifying the original"]
     fn add_modifier(self, modifier: Modifier) -> T;
+    #[must_use = "`remove_modifier` returns the modified style without modifying the original"]
     fn remove_modifier(self, modifier: Modifier) -> T;
 
     color!(black);
@@ -164,12 +254,12 @@ impl<'a, T, U> Stylize<'a, T> for U
 where
     U: Styled<Item = T>,
 {
-    fn bg(self, color: Color) -> T {
-        let style = self.style().bg(color);
+    fn bg<C: Into<Color>>(self, color: C) -> T {
+        let style = self.style().bg(color.into());
         self.set_style(style)
     }
 
-    fn fg<S: Into<Color>>(self, color: S) -> T {
+    fn fg<C: Into<Color>>(self, color: C) -> T {
         let style = self.style().fg(color.into());
         self.set_style(style)
     }
@@ -196,7 +286,7 @@ impl<'a> Styled for &'a str {
         Style::default()
     }
 
-    fn set_style(self, style: Style) -> Self::Item {
+    fn set_style<S: Into<Style>>(self, style: S) -> Self::Item {
         Span::styled(self, style)
     }
 }
@@ -208,7 +298,7 @@ impl Styled for String {
         Style::default()
     }
 
-    fn set_style(self, style: Style) -> Self::Item {
+    fn set_style<S: Into<Style>>(self, style: S) -> Self::Item {
         Span::styled(self, style)
     }
 }
@@ -216,6 +306,7 @@ impl Styled for String {
 #[cfg(test)]
 mod tests {
     use itertools::Itertools;
+    use rstest::rstest;
 
     use super::*;
 
@@ -329,9 +420,9 @@ mod tests {
 
         // format!() is used to create a temporary String inside a closure, which suffers the same
         // issue as above without the `Styled` trait impl for `String`
-        let items = vec![String::from("a"), String::from("b")];
+        let items = [String::from("a"), String::from("b")];
         let sss = items.iter().map(|s| format!("{s}{s}").red()).collect_vec();
-        assert_eq!(sss, vec![Span::from("aa").red(), Span::from("bb").red()]);
+        assert_eq!(sss, [Span::from("aa").red(), Span::from("bb").red()]);
     }
 
     #[test]
@@ -374,12 +465,12 @@ mod tests {
 
     #[test]
     fn repeated_attributes() {
-        let cyan_bg = Style::default().bg(Color::Cyan);
-        let cyan_fg = Style::default().fg(Color::Cyan);
+        let bg = Style::default().bg(Color::Cyan);
+        let fg = Style::default().fg(Color::Cyan);
 
         // Behavior: the last one set is the definitive one
-        assert_eq!("hello".on_red().on_cyan(), Span::styled("hello", cyan_bg));
-        assert_eq!("hello".red().cyan(), Span::styled("hello", cyan_fg));
+        assert_eq!("hello".on_red().on_cyan(), Span::styled("hello", bg));
+        assert_eq!("hello".red().cyan(), Span::styled("hello", fg));
     }
 
     #[test]
@@ -408,4 +499,77 @@ mod tests {
             Span::styled("hello", all_modifier_black)
         );
     }
+
+    #[rstest]
+    #[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")]
+    #[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,5 +1,10 @@
+//! Symbols and markers for drawing various widgets.
+
 use strum::{Display, EnumString};
 
+pub mod border;
+pub mod line;
+
 pub mod block {
     pub const FULL: &str = "█";
     pub const SEVEN_EIGHTHS: &str = "▉";
@@ -54,6 +59,12 @@ pub mod block {
     };
 }
 
+pub mod half_block {
+    pub const UPPER: char = '▀';
+    pub const LOWER: char = '▄';
+    pub const FULL: char = '█';
+}
+
 pub mod bar {
     pub const FULL: &str = "█";
     pub const SEVEN_EIGHTHS: &str = "▇";
@@ -108,127 +119,6 @@ pub mod bar {
     };
 }
 
-pub mod line {
-    pub const VERTICAL: &str = "│";
-    pub const DOUBLE_VERTICAL: &str = "║";
-    pub const THICK_VERTICAL: &str = "┃";
-
-    pub const HORIZONTAL: &str = "─";
-    pub const DOUBLE_HORIZONTAL: &str = "═";
-    pub const THICK_HORIZONTAL: &str = "━";
-
-    pub const TOP_RIGHT: &str = "┐";
-    pub const ROUNDED_TOP_RIGHT: &str = "╮";
-    pub const DOUBLE_TOP_RIGHT: &str = "╗";
-    pub const THICK_TOP_RIGHT: &str = "┓";
-
-    pub const TOP_LEFT: &str = "┌";
-    pub const ROUNDED_TOP_LEFT: &str = "╭";
-    pub const DOUBLE_TOP_LEFT: &str = "╔";
-    pub const THICK_TOP_LEFT: &str = "┏";
-
-    pub const BOTTOM_RIGHT: &str = "┘";
-    pub const ROUNDED_BOTTOM_RIGHT: &str = "╯";
-    pub const DOUBLE_BOTTOM_RIGHT: &str = "╝";
-    pub const THICK_BOTTOM_RIGHT: &str = "┛";
-
-    pub const BOTTOM_LEFT: &str = "└";
-    pub const ROUNDED_BOTTOM_LEFT: &str = "╰";
-    pub const DOUBLE_BOTTOM_LEFT: &str = "╚";
-    pub const THICK_BOTTOM_LEFT: &str = "┗";
-
-    pub const VERTICAL_LEFT: &str = "┤";
-    pub const DOUBLE_VERTICAL_LEFT: &str = "╣";
-    pub const THICK_VERTICAL_LEFT: &str = "┫";
-
-    pub const VERTICAL_RIGHT: &str = "├";
-    pub const DOUBLE_VERTICAL_RIGHT: &str = "╠";
-    pub const THICK_VERTICAL_RIGHT: &str = "┣";
-
-    pub const HORIZONTAL_DOWN: &str = "┬";
-    pub const DOUBLE_HORIZONTAL_DOWN: &str = "╦";
-    pub const THICK_HORIZONTAL_DOWN: &str = "┳";
-
-    pub const HORIZONTAL_UP: &str = "┴";
-    pub const DOUBLE_HORIZONTAL_UP: &str = "╩";
-    pub const THICK_HORIZONTAL_UP: &str = "┻";
-
-    pub const CROSS: &str = "┼";
-    pub const DOUBLE_CROSS: &str = "╬";
-    pub const THICK_CROSS: &str = "╋";
-
-    #[derive(Debug, Clone, Eq, PartialEq, Hash)]
-    pub struct Set {
-        pub vertical: &'static str,
-        pub horizontal: &'static str,
-        pub top_right: &'static str,
-        pub top_left: &'static str,
-        pub bottom_right: &'static str,
-        pub bottom_left: &'static str,
-        pub vertical_left: &'static str,
-        pub vertical_right: &'static str,
-        pub horizontal_down: &'static str,
-        pub horizontal_up: &'static str,
-        pub cross: &'static str,
-    }
-
-    impl Default for Set {
-        fn default() -> Self {
-            NORMAL
-        }
-    }
-
-    pub const NORMAL: Set = Set {
-        vertical: VERTICAL,
-        horizontal: HORIZONTAL,
-        top_right: TOP_RIGHT,
-        top_left: TOP_LEFT,
-        bottom_right: BOTTOM_RIGHT,
-        bottom_left: BOTTOM_LEFT,
-        vertical_left: VERTICAL_LEFT,
-        vertical_right: VERTICAL_RIGHT,
-        horizontal_down: HORIZONTAL_DOWN,
-        horizontal_up: HORIZONTAL_UP,
-        cross: CROSS,
-    };
-
-    pub const ROUNDED: Set = Set {
-        top_right: ROUNDED_TOP_RIGHT,
-        top_left: ROUNDED_TOP_LEFT,
-        bottom_right: ROUNDED_BOTTOM_RIGHT,
-        bottom_left: ROUNDED_BOTTOM_LEFT,
-        ..NORMAL
-    };
-
-    pub const DOUBLE: Set = Set {
-        vertical: DOUBLE_VERTICAL,
-        horizontal: DOUBLE_HORIZONTAL,
-        top_right: DOUBLE_TOP_RIGHT,
-        top_left: DOUBLE_TOP_LEFT,
-        bottom_right: DOUBLE_BOTTOM_RIGHT,
-        bottom_left: DOUBLE_BOTTOM_LEFT,
-        vertical_left: DOUBLE_VERTICAL_LEFT,
-        vertical_right: DOUBLE_VERTICAL_RIGHT,
-        horizontal_down: DOUBLE_HORIZONTAL_DOWN,
-        horizontal_up: DOUBLE_HORIZONTAL_UP,
-        cross: DOUBLE_CROSS,
-    };
-
-    pub const THICK: Set = Set {
-        vertical: THICK_VERTICAL,
-        horizontal: THICK_HORIZONTAL,
-        top_right: THICK_TOP_RIGHT,
-        top_left: THICK_TOP_LEFT,
-        bottom_right: THICK_BOTTOM_RIGHT,
-        bottom_left: THICK_BOTTOM_LEFT,
-        vertical_left: THICK_VERTICAL_LEFT,
-        vertical_right: THICK_VERTICAL_RIGHT,
-        horizontal_down: THICK_HORIZONTAL_DOWN,
-        horizontal_up: THICK_HORIZONTAL_UP,
-        cross: THICK_CROSS,
-    };
-}
-
 pub const DOT: &str = "•";
 
 pub mod braille {
@@ -244,12 +134,12 @@ pub mod braille {
 /// Marker to use when plotting data points
 #[derive(Debug, Default, Display, EnumString, Clone, Copy, Eq, PartialEq, Hash)]
 pub enum Marker {
-    /// One point per cell in shape of dot ("•")
+    /// One point per cell in shape of dot (`•`)
     #[default]
     Dot,
-    /// One point per cell in shape of a block ("█")
+    /// One point per cell in shape of a block (`█`)
     Block,
-    /// One point per cell in the shape of a bar ("▄")
+    /// One point per cell in the shape of a bar (`▄`)
     Bar,
     /// Use the [Unicode Braille Patterns](https://en.wikipedia.org/wiki/Braille_Patterns) block to
     /// represent data points.
@@ -258,12 +148,16 @@ pub enum Marker {
     ///
     /// Note: Support for this marker is limited to terminals and fonts that support Unicode
     /// Braille Patterns. If your terminal does not support this, you will see unicode replacement
-    /// characters (<EFBFBD>) instead of Braille dots.
+    /// characters (`<60>`) instead of Braille dots (`⠓`, `⣇`, `⣿`).
     Braille,
+    /// Use the unicode block and half block characters (`█`, `▄`, and `▀`) to represent points in
+    /// a grid that is double the resolution of the terminal. Because each terminal cell is
+    /// generally about twice as tall as it is wide, this allows for a square grid of pixels.
+    HalfBlock,
 }
 
 pub mod scrollbar {
-    use super::{block, line};
+    use crate::symbols::{block, line};
 
     /// Scrollbar Set
     /// ```text
@@ -311,6 +205,14 @@ pub mod scrollbar {
     };
 }
 
+pub mod shade {
+    pub const EMPTY: &str = " ";
+    pub const LIGHT: &str = "░";
+    pub const MEDIUM: &str = "▒";
+    pub const DARK: &str = "▓";
+    pub const FULL: &str = "█";
+}
+
 #[cfg(test)]
 mod tests {
     use strum::ParseError;

ratatui-core/src/symbols/border.rs

@@ -0,0 +1,509 @@
+use crate::symbols::{block, line};
+
+#[derive(Debug, Clone, Copy, Eq, PartialEq, Hash)]
+pub struct Set {
+    pub top_left: &'static str,
+    pub top_right: &'static str,
+    pub bottom_left: &'static str,
+    pub bottom_right: &'static str,
+    pub vertical_left: &'static str,
+    pub vertical_right: &'static str,
+    pub horizontal_top: &'static str,
+    pub horizontal_bottom: &'static str,
+}
+
+impl Default for Set {
+    fn default() -> Self {
+        PLAIN
+    }
+}
+
+/// Border Set with a single line width
+///
+/// ```text
+/// ┌─────┐
+/// │xxxxx│
+/// │xxxxx│
+/// └─────┘
+/// ```
+pub const PLAIN: Set = Set {
+    top_left: line::NORMAL.top_left,
+    top_right: line::NORMAL.top_right,
+    bottom_left: line::NORMAL.bottom_left,
+    bottom_right: line::NORMAL.bottom_right,
+    vertical_left: line::NORMAL.vertical,
+    vertical_right: line::NORMAL.vertical,
+    horizontal_top: line::NORMAL.horizontal,
+    horizontal_bottom: line::NORMAL.horizontal,
+};
+
+/// Border Set with a single line width and rounded corners
+///
+/// ```text
+/// ╭─────╮
+/// │xxxxx│
+/// │xxxxx│
+/// ╰─────╯
+/// ```
+pub const ROUNDED: Set = Set {
+    top_left: line::ROUNDED.top_left,
+    top_right: line::ROUNDED.top_right,
+    bottom_left: line::ROUNDED.bottom_left,
+    bottom_right: line::ROUNDED.bottom_right,
+    vertical_left: line::ROUNDED.vertical,
+    vertical_right: line::ROUNDED.vertical,
+    horizontal_top: line::ROUNDED.horizontal,
+    horizontal_bottom: line::ROUNDED.horizontal,
+};
+
+/// Border Set with a double line width
+///
+/// ```text
+/// ╔═════╗
+/// ║xxxxx║
+/// ║xxxxx║
+/// ╚═════╝
+/// ```
+pub const DOUBLE: Set = Set {
+    top_left: line::DOUBLE.top_left,
+    top_right: line::DOUBLE.top_right,
+    bottom_left: line::DOUBLE.bottom_left,
+    bottom_right: line::DOUBLE.bottom_right,
+    vertical_left: line::DOUBLE.vertical,
+    vertical_right: line::DOUBLE.vertical,
+    horizontal_top: line::DOUBLE.horizontal,
+    horizontal_bottom: line::DOUBLE.horizontal,
+};
+
+/// Border Set with a thick line width
+///
+/// ```text
+/// ┏━━━━━┓
+/// ┃xxxxx┃
+/// ┃xxxxx┃
+/// ┗━━━━━┛
+/// ```
+pub const THICK: Set = Set {
+    top_left: line::THICK.top_left,
+    top_right: line::THICK.top_right,
+    bottom_left: line::THICK.bottom_left,
+    bottom_right: line::THICK.bottom_right,
+    vertical_left: line::THICK.vertical,
+    vertical_right: line::THICK.vertical,
+    horizontal_top: line::THICK.horizontal,
+    horizontal_bottom: line::THICK.horizontal,
+};
+
+pub const QUADRANT_TOP_LEFT: &str = "▘";
+pub const QUADRANT_TOP_RIGHT: &str = "▝";
+pub const QUADRANT_BOTTOM_LEFT: &str = "▖";
+pub const QUADRANT_BOTTOM_RIGHT: &str = "▗";
+pub const QUADRANT_TOP_HALF: &str = "▀";
+pub const QUADRANT_BOTTOM_HALF: &str = "▄";
+pub const QUADRANT_LEFT_HALF: &str = "▌";
+pub const QUADRANT_RIGHT_HALF: &str = "▐";
+pub const QUADRANT_TOP_LEFT_BOTTOM_LEFT_BOTTOM_RIGHT: &str = "▙";
+pub const QUADRANT_TOP_LEFT_TOP_RIGHT_BOTTOM_LEFT: &str = "▛";
+pub const QUADRANT_TOP_LEFT_TOP_RIGHT_BOTTOM_RIGHT: &str = "▜";
+pub const QUADRANT_TOP_RIGHT_BOTTOM_LEFT_BOTTOM_RIGHT: &str = "▟";
+pub const QUADRANT_TOP_LEFT_BOTTOM_RIGHT: &str = "▚";
+pub const QUADRANT_TOP_RIGHT_BOTTOM_LEFT: &str = "▞";
+pub const QUADRANT_BLOCK: &str = "█";
+
+/// Quadrant used for setting a border outside a block by one half cell "pixel".
+///
+/// ```text
+/// ▛▀▀▀▀▀▜
+/// ▌xxxxx▐
+/// ▌xxxxx▐
+/// ▙▄▄▄▄▄▟
+/// ```
+pub const QUADRANT_OUTSIDE: Set = Set {
+    top_left: QUADRANT_TOP_LEFT_TOP_RIGHT_BOTTOM_LEFT,
+    top_right: QUADRANT_TOP_LEFT_TOP_RIGHT_BOTTOM_RIGHT,
+    bottom_left: QUADRANT_TOP_LEFT_BOTTOM_LEFT_BOTTOM_RIGHT,
+    bottom_right: QUADRANT_TOP_RIGHT_BOTTOM_LEFT_BOTTOM_RIGHT,
+    vertical_left: QUADRANT_LEFT_HALF,
+    vertical_right: QUADRANT_RIGHT_HALF,
+    horizontal_top: QUADRANT_TOP_HALF,
+    horizontal_bottom: QUADRANT_BOTTOM_HALF,
+};
+
+/// Quadrant used for setting a border inside a block by one half cell "pixel".
+///
+/// ```text
+/// ▗▄▄▄▄▄▖
+/// ▐xxxxx▌
+/// ▐xxxxx▌
+/// ▝▀▀▀▀▀▘
+/// ```
+pub const QUADRANT_INSIDE: Set = Set {
+    top_right: QUADRANT_BOTTOM_LEFT,
+    top_left: QUADRANT_BOTTOM_RIGHT,
+    bottom_right: QUADRANT_TOP_LEFT,
+    bottom_left: QUADRANT_TOP_RIGHT,
+    vertical_left: QUADRANT_RIGHT_HALF,
+    vertical_right: QUADRANT_LEFT_HALF,
+    horizontal_top: QUADRANT_BOTTOM_HALF,
+    horizontal_bottom: QUADRANT_TOP_HALF,
+};
+
+pub const ONE_EIGHTH_TOP_EIGHT: &str = "▔";
+pub const ONE_EIGHTH_BOTTOM_EIGHT: &str = "▁";
+pub const ONE_EIGHTH_LEFT_EIGHT: &str = "▏";
+pub const ONE_EIGHTH_RIGHT_EIGHT: &str = "▕";
+
+/// Wide border set based on McGugan box technique
+///
+/// ```text
+/// ▁▁▁▁▁▁▁
+/// ▏xxxxx▕
+/// ▏xxxxx▕
+/// ▔▔▔▔▔▔▔
+/// ```
+#[allow(clippy::doc_markdown)]
+pub const ONE_EIGHTH_WIDE: Set = Set {
+    top_right: ONE_EIGHTH_BOTTOM_EIGHT,
+    top_left: ONE_EIGHTH_BOTTOM_EIGHT,
+    bottom_right: ONE_EIGHTH_TOP_EIGHT,
+    bottom_left: ONE_EIGHTH_TOP_EIGHT,
+    vertical_left: ONE_EIGHTH_LEFT_EIGHT,
+    vertical_right: ONE_EIGHTH_RIGHT_EIGHT,
+    horizontal_top: ONE_EIGHTH_BOTTOM_EIGHT,
+    horizontal_bottom: ONE_EIGHTH_TOP_EIGHT,
+};
+
+/// Tall border set based on McGugan box technique
+///
+/// ```text
+/// ▕▔▔▏
+/// ▕xx▏
+/// ▕xx▏
+/// ▕▁▁▏
+/// ```
+#[allow(clippy::doc_markdown)]
+pub const ONE_EIGHTH_TALL: Set = Set {
+    top_right: ONE_EIGHTH_LEFT_EIGHT,
+    top_left: ONE_EIGHTH_RIGHT_EIGHT,
+    bottom_right: ONE_EIGHTH_LEFT_EIGHT,
+    bottom_left: ONE_EIGHTH_RIGHT_EIGHT,
+    vertical_left: ONE_EIGHTH_RIGHT_EIGHT,
+    vertical_right: ONE_EIGHTH_LEFT_EIGHT,
+    horizontal_top: ONE_EIGHTH_TOP_EIGHT,
+    horizontal_bottom: ONE_EIGHTH_BOTTOM_EIGHT,
+};
+
+/// Wide proportional (visually equal width and height) border with using set of quadrants.
+///
+/// The border is created by using half blocks for top and bottom, and full
+/// blocks for right and left sides to make horizontal and vertical borders seem equal.
+///
+/// ```text
+/// ▄▄▄▄
+/// █xx█
+/// █xx█
+/// ▀▀▀▀
+/// ```
+pub const PROPORTIONAL_WIDE: Set = Set {
+    top_right: QUADRANT_BOTTOM_HALF,
+    top_left: QUADRANT_BOTTOM_HALF,
+    bottom_right: QUADRANT_TOP_HALF,
+    bottom_left: QUADRANT_TOP_HALF,
+    vertical_left: QUADRANT_BLOCK,
+    vertical_right: QUADRANT_BLOCK,
+    horizontal_top: QUADRANT_BOTTOM_HALF,
+    horizontal_bottom: QUADRANT_TOP_HALF,
+};
+
+/// Tall proportional (visually equal width and height) border with using set of quadrants.
+///
+/// The border is created by using full blocks for all sides, except for the top and bottom,
+/// which use half blocks to make horizontal and vertical borders seem equal.
+///
+/// ```text
+/// ▕█▀▀█
+/// ▕█xx█
+/// ▕█xx█
+/// ▕█▄▄█
+/// ```
+pub const PROPORTIONAL_TALL: Set = Set {
+    top_right: QUADRANT_BLOCK,
+    top_left: QUADRANT_BLOCK,
+    bottom_right: QUADRANT_BLOCK,
+    bottom_left: QUADRANT_BLOCK,
+    vertical_left: QUADRANT_BLOCK,
+    vertical_right: QUADRANT_BLOCK,
+    horizontal_top: QUADRANT_TOP_HALF,
+    horizontal_bottom: QUADRANT_BOTTOM_HALF,
+};
+
+/// Solid border set
+///
+/// The border is created by using full blocks for all sides.
+///
+/// ```text
+/// ████
+/// █xx█
+/// █xx█
+/// ████
+/// ```
+pub const FULL: Set = Set {
+    top_left: block::FULL,
+    top_right: block::FULL,
+    bottom_left: block::FULL,
+    bottom_right: block::FULL,
+    vertical_left: block::FULL,
+    vertical_right: block::FULL,
+    horizontal_top: block::FULL,
+    horizontal_bottom: block::FULL,
+};
+
+/// Empty border set
+///
+/// The border is created by using empty strings for all sides.
+///
+/// This is useful for ensuring that the border style is applied to a border on a block with a title
+/// without actually drawing a border.
+///
+/// ░ Example
+///
+/// `░` represents the content in the area not covered by the border to make it easier to see the
+/// blank symbols.
+///
+/// ```text
+/// ░░░░░░░░
+/// ░░    ░░
+/// ░░ ░░ ░░
+/// ░░ ░░ ░░
+/// ░░    ░░
+/// ░░░░░░░░
+/// ```
+pub const EMPTY: Set = Set {
+    top_left: " ",
+    top_right: " ",
+    bottom_left: " ",
+    bottom_right: " ",
+    vertical_left: " ",
+    vertical_right: " ",
+    horizontal_top: " ",
+    horizontal_bottom: " ",
+};
+
+#[cfg(test)]
+mod tests {
+    use indoc::{formatdoc, indoc};
+
+    use super::*;
+
+    #[test]
+    fn default() {
+        assert_eq!(Set::default(), PLAIN);
+    }
+
+    /// A helper function to render a border set to a string.
+    ///
+    /// '░' (U+2591 Light Shade) is used as a placeholder for empty space to make it easier to see
+    /// the size of the border symbols.
+    fn render(set: Set) -> String {
+        formatdoc!(
+            "░░░░░░
+             ░{}{}{}{}░
+             ░{}░░{}░
+             ░{}░░{}░
+             ░{}{}{}{}░
+             ░░░░░░",
+            set.top_left,
+            set.horizontal_top,
+            set.horizontal_top,
+            set.top_right,
+            set.vertical_left,
+            set.vertical_right,
+            set.vertical_left,
+            set.vertical_right,
+            set.bottom_left,
+            set.horizontal_bottom,
+            set.horizontal_bottom,
+            set.bottom_right
+        )
+    }
+
+    #[test]
+    fn plain() {
+        assert_eq!(
+            render(PLAIN),
+            indoc!(
+                "░░░░░░
+                 ░┌──┐░
+                 ░│░░│░
+                 ░│░░│░
+                 ░└──┘░
+                 ░░░░░░"
+            )
+        );
+    }
+
+    #[test]
+    fn rounded() {
+        assert_eq!(
+            render(ROUNDED),
+            indoc!(
+                "░░░░░░
+                 ░╭──╮░
+                 ░│░░│░
+                 ░│░░│░
+                 ░╰──╯░
+                 ░░░░░░"
+            )
+        );
+    }
+
+    #[test]
+    fn double() {
+        assert_eq!(
+            render(DOUBLE),
+            indoc!(
+                "░░░░░░
+                 ░╔══╗░
+                 ░║░░║░
+                 ░║░░║░
+                 ░╚══╝░
+                 ░░░░░░"
+            )
+        );
+    }
+
+    #[test]
+    fn thick() {
+        assert_eq!(
+            render(THICK),
+            indoc!(
+                "░░░░░░
+                 ░┏━━┓░
+                 ░┃░░┃░
+                 ░┃░░┃░
+                 ░┗━━┛░
+                 ░░░░░░"
+            )
+        );
+    }
+
+    #[test]
+    fn quadrant_outside() {
+        assert_eq!(
+            render(QUADRANT_OUTSIDE),
+            indoc!(
+                "░░░░░░
+                 ░▛▀▀▜░
+                 ░▌░░▐░
+                 ░▌░░▐░
+                 ░▙▄▄▟░
+                 ░░░░░░"
+            )
+        );
+    }
+
+    #[test]
+    fn quadrant_inside() {
+        assert_eq!(
+            render(QUADRANT_INSIDE),
+            indoc!(
+                "░░░░░░
+                 ░▗▄▄▖░
+                 ░▐░░▌░
+                 ░▐░░▌░
+                 ░▝▀▀▘░
+                 ░░░░░░"
+            )
+        );
+    }
+
+    #[test]
+    fn one_eighth_wide() {
+        assert_eq!(
+            render(ONE_EIGHTH_WIDE),
+            indoc!(
+                "░░░░░░
+                 ░▁▁▁▁░
+                 ░▏░░▕░
+                 ░▏░░▕░
+                 ░▔▔▔▔░
+                 ░░░░░░"
+            )
+        );
+    }
+
+    #[test]
+    fn one_eighth_tall() {
+        assert_eq!(
+            render(ONE_EIGHTH_TALL),
+            indoc!(
+                "░░░░░░
+                 ░▕▔▔▏░
+                 ░▕░░▏░
+                 ░▕░░▏░
+                 ░▕▁▁▏░
+                 ░░░░░░"
+            )
+        );
+    }
+
+    #[test]
+    fn proportional_wide() {
+        assert_eq!(
+            render(PROPORTIONAL_WIDE),
+            indoc!(
+                "░░░░░░
+                 ░▄▄▄▄░
+                 ░█░░█░
+                 ░█░░█░
+                 ░▀▀▀▀░
+                 ░░░░░░"
+            )
+        );
+    }
+
+    #[test]
+    fn proportional_tall() {
+        assert_eq!(
+            render(PROPORTIONAL_TALL),
+            indoc!(
+                "░░░░░░
+                 ░█▀▀█░
+                 ░█░░█░
+                 ░█░░█░
+                 ░█▄▄█░
+                 ░░░░░░"
+            )
+        );
+    }
+
+    #[test]
+    fn full() {
+        assert_eq!(
+            render(FULL),
+            indoc!(
+                "░░░░░░
+                 ░████░
+                 ░█░░█░
+                 ░█░░█░
+                 ░████░
+                 ░░░░░░"
+            )
+        );
+    }
+
+    #[test]
+    fn empty() {
+        assert_eq!(
+            render(EMPTY),
+            indoc!(
+                "░░░░░░
+                 ░    ░
+                 ░ ░░ ░
+                 ░ ░░ ░
+                 ░    ░
+                 ░░░░░░"
+            )
+        );
+    }
+}

ratatui-core/src/symbols/line.rs

@@ -0,0 +1,208 @@
+pub const VERTICAL: &str = "│";
+pub const DOUBLE_VERTICAL: &str = "║";
+pub const THICK_VERTICAL: &str = "┃";
+
+pub const HORIZONTAL: &str = "─";
+pub const DOUBLE_HORIZONTAL: &str = "═";
+pub const THICK_HORIZONTAL: &str = "━";
+
+pub const TOP_RIGHT: &str = "┐";
+pub const ROUNDED_TOP_RIGHT: &str = "╮";
+pub const DOUBLE_TOP_RIGHT: &str = "╗";
+pub const THICK_TOP_RIGHT: &str = "┓";
+
+pub const TOP_LEFT: &str = "┌";
+pub const ROUNDED_TOP_LEFT: &str = "╭";
+pub const DOUBLE_TOP_LEFT: &str = "╔";
+pub const THICK_TOP_LEFT: &str = "┏";
+
+pub const BOTTOM_RIGHT: &str = "┘";
+pub const ROUNDED_BOTTOM_RIGHT: &str = "╯";
+pub const DOUBLE_BOTTOM_RIGHT: &str = "╝";
+pub const THICK_BOTTOM_RIGHT: &str = "┛";
+
+pub const BOTTOM_LEFT: &str = "└";
+pub const ROUNDED_BOTTOM_LEFT: &str = "╰";
+pub const DOUBLE_BOTTOM_LEFT: &str = "╚";
+pub const THICK_BOTTOM_LEFT: &str = "┗";
+
+pub const VERTICAL_LEFT: &str = "┤";
+pub const DOUBLE_VERTICAL_LEFT: &str = "╣";
+pub const THICK_VERTICAL_LEFT: &str = "┫";
+
+pub const VERTICAL_RIGHT: &str = "├";
+pub const DOUBLE_VERTICAL_RIGHT: &str = "╠";
+pub const THICK_VERTICAL_RIGHT: &str = "┣";
+
+pub const HORIZONTAL_DOWN: &str = "┬";
+pub const DOUBLE_HORIZONTAL_DOWN: &str = "╦";
+pub const THICK_HORIZONTAL_DOWN: &str = "┳";
+
+pub const HORIZONTAL_UP: &str = "┴";
+pub const DOUBLE_HORIZONTAL_UP: &str = "╩";
+pub const THICK_HORIZONTAL_UP: &str = "┻";
+
+pub const CROSS: &str = "┼";
+pub const DOUBLE_CROSS: &str = "╬";
+pub const THICK_CROSS: &str = "╋";
+
+#[derive(Debug, Clone, Copy, Eq, PartialEq, Hash)]
+pub struct Set {
+    pub vertical: &'static str,
+    pub horizontal: &'static str,
+    pub top_right: &'static str,
+    pub top_left: &'static str,
+    pub bottom_right: &'static str,
+    pub bottom_left: &'static str,
+    pub vertical_left: &'static str,
+    pub vertical_right: &'static str,
+    pub horizontal_down: &'static str,
+    pub horizontal_up: &'static str,
+    pub cross: &'static str,
+}
+
+impl Default for Set {
+    fn default() -> Self {
+        NORMAL
+    }
+}
+
+pub const NORMAL: Set = Set {
+    vertical: VERTICAL,
+    horizontal: HORIZONTAL,
+    top_right: TOP_RIGHT,
+    top_left: TOP_LEFT,
+    bottom_right: BOTTOM_RIGHT,
+    bottom_left: BOTTOM_LEFT,
+    vertical_left: VERTICAL_LEFT,
+    vertical_right: VERTICAL_RIGHT,
+    horizontal_down: HORIZONTAL_DOWN,
+    horizontal_up: HORIZONTAL_UP,
+    cross: CROSS,
+};
+
+pub const ROUNDED: Set = Set {
+    top_right: ROUNDED_TOP_RIGHT,
+    top_left: ROUNDED_TOP_LEFT,
+    bottom_right: ROUNDED_BOTTOM_RIGHT,
+    bottom_left: ROUNDED_BOTTOM_LEFT,
+    ..NORMAL
+};
+
+pub const DOUBLE: Set = Set {
+    vertical: DOUBLE_VERTICAL,
+    horizontal: DOUBLE_HORIZONTAL,
+    top_right: DOUBLE_TOP_RIGHT,
+    top_left: DOUBLE_TOP_LEFT,
+    bottom_right: DOUBLE_BOTTOM_RIGHT,
+    bottom_left: DOUBLE_BOTTOM_LEFT,
+    vertical_left: DOUBLE_VERTICAL_LEFT,
+    vertical_right: DOUBLE_VERTICAL_RIGHT,
+    horizontal_down: DOUBLE_HORIZONTAL_DOWN,
+    horizontal_up: DOUBLE_HORIZONTAL_UP,
+    cross: DOUBLE_CROSS,
+};
+
+pub const THICK: Set = Set {
+    vertical: THICK_VERTICAL,
+    horizontal: THICK_HORIZONTAL,
+    top_right: THICK_TOP_RIGHT,
+    top_left: THICK_TOP_LEFT,
+    bottom_right: THICK_BOTTOM_RIGHT,
+    bottom_left: THICK_BOTTOM_LEFT,
+    vertical_left: THICK_VERTICAL_LEFT,
+    vertical_right: THICK_VERTICAL_RIGHT,
+    horizontal_down: THICK_HORIZONTAL_DOWN,
+    horizontal_up: THICK_HORIZONTAL_UP,
+    cross: THICK_CROSS,
+};
+
+#[cfg(test)]
+mod tests {
+    use indoc::{formatdoc, indoc};
+
+    use super::*;
+
+    #[test]
+    fn default() {
+        assert_eq!(Set::default(), NORMAL);
+    }
+
+    /// A helper function to render a set of symbols.
+    fn render(set: Set) -> String {
+        formatdoc!(
+            "{}{}{}{}
+             {}{}{}{}
+             {}{}{}{}
+             {}{}{}{}",
+            set.top_left,
+            set.horizontal,
+            set.horizontal_down,
+            set.top_right,
+            set.vertical,
+            " ",
+            set.vertical,
+            set.vertical,
+            set.vertical_right,
+            set.horizontal,
+            set.cross,
+            set.vertical_left,
+            set.bottom_left,
+            set.horizontal,
+            set.horizontal_up,
+            set.bottom_right
+        )
+    }
+
+    #[test]
+    fn normal() {
+        assert_eq!(
+            render(NORMAL),
+            indoc!(
+                "┌─┬┐
+                 │ ││
+                 ├─┼┤
+                 └─┴┘"
+            )
+        );
+    }
+
+    #[test]
+    fn rounded() {
+        assert_eq!(
+            render(ROUNDED),
+            indoc!(
+                "╭─┬╮
+                 │ ││
+                 ├─┼┤
+                 ╰─┴╯"
+            )
+        );
+    }
+
+    #[test]
+    fn double() {
+        assert_eq!(
+            render(DOUBLE),
+            indoc!(
+                "╔═╦╗
+                 ║ ║║
+                 ╠═╬╣
+                 ╚═╩╝"
+            )
+        );
+    }
+
+    #[test]
+    fn thick() {
+        assert_eq!(
+            render(THICK),
+            indoc!(
+                "┏━┳┓
+                 ┃ ┃┃
+                 ┣━╋┫
+                 ┗━┻┛"
+            )
+        );
+    }
+}

ratatui-core/src/text.rs

@@ -1,65 +1,64 @@
 //! Primitives for styled text.
 //!
-//! A terminal UI is at its root a lot of strings. In order to make it accessible and stylish,
-//! those strings may be associated to a set of styles. `ratatui` has three ways to represent them:
+//! A terminal UI is at its root a lot of strings. In order to make it accessible and stylish, those
+//! strings may be associated to a set of styles. `ratatui` has three ways to represent them:
 //! - A single line string where all graphemes have the same style is represented by a [`Span`].
 //! - A single line string where each grapheme may have its own style is represented by [`Line`].
 //! - A multiple line string where each grapheme may have its own style is represented by a
-//! [`Text`].
+//!   [`Text`].
 //!
-//! These types form a hierarchy: [`Line`] is a collection of [`Span`] and each line of [`Text`]
-//! is a [`Line`].
+//! These types form a hierarchy: [`Line`] is a collection of [`Span`] and each line of [`Text`] is
+//! a [`Line`].
 //!
 //! Keep it mind that a lot of widgets will use those types to advertise what kind of string is
 //! supported for their properties. Moreover, `ratatui` provides convenient `From` implementations
 //! so that you can start by using simple `String` or `&str` and then promote them to the previous
 //! primitives when you need additional styling capabilities.
 //!
-//! For example, for the [`crate::widgets::Block`] widget, all the following calls are valid to set
-//! its `title` property (which is a [`Line`] under the hood):
+//! For example, for the `Block` widget, all the following calls are valid to set its `title`
+//! property (which is a [`Line`] under the hood):
 //!
-//! ```rust
-//! use ratatui::{prelude::*, widgets::*};
+//! ```rust,ignore
+//! use ratatui_core::{
+//!     style::{Color, Style},
+//!     text::{Line, Span},
+//!     widgets::Block,
+//! };
 //!
 //! // A simple string with no styling.
 //! // Converted to Line(vec![
 //! //   Span { content: Cow::Borrowed("My title"), style: Style { .. } }
 //! // ])
-//! let block = Block::default().title("My title");
+//! let block = Block::new().title("My title");
 //!
 //! // A simple string with a unique style.
 //! // Converted to Line(vec![
 //! //   Span { content: Cow::Borrowed("My title"), style: Style { fg: Some(Color::Yellow), .. }
 //! // ])
-//! let block = Block::default().title(
-//!     Span::styled("My title", Style::default().fg(Color::Yellow))
-//! );
+//! let block = Block::new().title(Span::styled("My title", Style::default().fg(Color::Yellow)));
 //!
 //! // A string with multiple styles.
 //! // Converted to Line(vec![
 //! //   Span { content: Cow::Borrowed("My"), style: Style { fg: Some(Color::Yellow), .. } },
 //! //   Span { content: Cow::Borrowed(" title"), .. }
 //! // ])
-//! let block = Block::default().title(vec![
+//! let block = Block::new().title(vec![
 //!     Span::styled("My", Style::default().fg(Color::Yellow)),
 //!     Span::raw(" title"),
 //! ]);
 //! ```
 
-use crate::style::Style;
-
 mod grapheme;
 pub use grapheme::StyledGrapheme;
 
 mod line;
-pub use line::Line;
+pub use line::{Line, ToLine};
 
 mod masked;
 pub use masked::Masked;
 
 mod span;
-pub use span::Span;
+pub use span::{Span, ToSpan};
 
-#[allow(clippy::module_inception)]
 mod text;
-pub use text::Text;
+pub use text::{Text, ToText};

ratatui-core/src/text/grapheme.rs

@@ -1,5 +1,8 @@
 use crate::style::{Style, Styled};
 
+const NBSP: &str = "\u{00a0}";
+const ZWSP: &str = "\u{200b}";
+
 /// A grapheme associated to a style.
 /// Note that, although `StyledGrapheme` is the smallest divisible unit of text,
 /// it actually is not a member of the text type hierarchy (`Text` -> `Line` -> `Span`).
@@ -12,20 +15,34 @@ pub struct StyledGrapheme<'a> {
 }
 
 impl<'a> StyledGrapheme<'a> {
-    pub fn new(symbol: &'a str, style: Style) -> StyledGrapheme<'a> {
-        StyledGrapheme { symbol, style }
+    /// Creates a new `StyledGrapheme` with the given symbol and style.
+    ///
+    /// `style` accepts any type that is convertible to [`Style`] (e.g. [`Style`], [`Color`], or
+    /// your own type that implements [`Into<Style>`]).
+    ///
+    /// [`Color`]: crate::style::Color
+    pub fn new<S: Into<Style>>(symbol: &'a str, style: S) -> Self {
+        Self {
+            symbol,
+            style: style.into(),
+        }
+    }
+
+    pub fn is_whitespace(&self) -> bool {
+        let symbol = self.symbol;
+        symbol == ZWSP || symbol.chars().all(char::is_whitespace) && symbol != NBSP
     }
 }
 
 impl<'a> Styled for StyledGrapheme<'a> {
-    type Item = StyledGrapheme<'a>;
+    type Item = Self;
 
     fn style(&self) -> Style {
         self.style
     }
 
-    fn set_style(mut self, style: Style) -> Self::Item {
-        self.style = style;
+    fn set_style<S: Into<Style>>(mut self, style: S) -> Self::Item {
+        self.style = style.into();
         self
     }
 }
@@ -33,7 +50,7 @@ impl<'a> Styled for StyledGrapheme<'a> {
 #[cfg(test)]
 mod tests {
     use super::*;
-    use crate::prelude::*;
+    use crate::style::Stylize;
 
     #[test]
     fn new() {

ratatui-core/src/text/masked.rs

@@ -1,25 +1,27 @@
-use std::{
-    borrow::Cow,
-    fmt::{self, Debug, Display},
-};
+use std::{borrow::Cow, fmt};
 
-use super::Text;
+use crate::text::Text;
 
 /// A wrapper around a string that is masked when displayed.
 ///
-/// The masked string is displayed as a series of the same character.
-/// This might be used to display a password field or similar secure data.
+/// The masked string is displayed as a series of the same character. This might be used to display
+/// a password field or similar secure data.
 ///
 /// # Examples
 ///
 /// ```rust
-/// use ratatui::{prelude::*, widgets::*};
+/// use ratatui_core::{
+///     buffer::Buffer,
+///     layout::Rect,
+///     text::{Masked, Text},
+///     widgets::Widget,
+/// };
 ///
 /// let mut buffer = Buffer::empty(Rect::new(0, 0, 5, 1));
 /// let password = Masked::new("12345", 'x');
 ///
-/// Paragraph::new(password).render(buffer.area, &mut buffer);
-/// assert_eq!(buffer, Buffer::with_lines(vec!["xxxxx"]));
+/// Text::from(password).render(buffer.area, &mut buffer);
+/// assert_eq!(buffer, Buffer::with_lines(["xxxxx"]));
 /// ```
 #[derive(Default, Clone, Eq, PartialEq, Hash)]
 pub struct Masked<'a> {
@@ -36,7 +38,7 @@ impl<'a> Masked<'a> {
     }
 
     /// The character to use for masking.
-    pub fn mask_char(&self) -> char {
+    pub const fn mask_char(&self) -> char {
         self.mask_char
     }
 
@@ -46,40 +48,41 @@ impl<'a> Masked<'a> {
     }
 }
 
-impl Debug for Masked<'_> {
+impl fmt::Debug for Masked<'_> {
     /// Debug representation of a masked string is the underlying string
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        f.write_str(&self.inner).map_err(|_| fmt::Error)
+        // note that calling display instead of Debug here is intentional
+        fmt::Display::fmt(&self.inner, f)
     }
 }
 
-impl Display for Masked<'_> {
+impl fmt::Display for Masked<'_> {
     /// Display representation of a masked string is the masked string
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        f.write_str(&self.value()).map_err(|_| fmt::Error)
+        fmt::Display::fmt(&self.value(), f)
     }
 }
 
 impl<'a> From<&'a Masked<'a>> for Cow<'a, str> {
-    fn from(masked: &'a Masked) -> Cow<'a, str> {
+    fn from(masked: &'a Masked) -> Self {
         masked.value()
     }
 }
 
 impl<'a> From<Masked<'a>> for Cow<'a, str> {
-    fn from(masked: Masked<'a>) -> Cow<'a, str> {
+    fn from(masked: Masked<'a>) -> Self {
         masked.value()
     }
 }
 
 impl<'a> From<&'a Masked<'_>> for Text<'a> {
-    fn from(masked: &'a Masked) -> Text<'a> {
+    fn from(masked: &'a Masked) -> Self {
         Text::raw(masked.value())
     }
 }
 
 impl<'a> From<Masked<'a>> for Text<'a> {
-    fn from(masked: Masked<'a>) -> Text<'a> {
+    fn from(masked: Masked<'a>) -> Self {
         Text::raw(masked.value())
     }
 }
@@ -112,12 +115,14 @@ mod tests {
     fn debug() {
         let masked = Masked::new("12345", 'x');
         assert_eq!(format!("{masked:?}"), "12345");
+        assert_eq!(format!("{masked:.3?}"), "123", "Debug truncates");
     }
 
     #[test]
     fn display() {
         let masked = Masked::new("12345", 'x');
         assert_eq!(format!("{masked}"), "xxxxx");
+        assert_eq!(format!("{masked:.3}"), "xxx", "Display truncates");
     }
 
     #[test]
@@ -125,10 +130,10 @@ mod tests {
         let masked = Masked::new("12345", 'x');
 
         let text: Text = (&masked).into();
-        assert_eq!(text.lines, vec![Line::from("xxxxx")]);
+        assert_eq!(text.lines, [Line::from("xxxxx")]);
 
         let text: Text = masked.into();
-        assert_eq!(text.lines, vec![Line::from("xxxxx")]);
+        assert_eq!(text.lines, [Line::from("xxxxx")]);
     }
 
     #[test]