setup

.config/config.json5

@@ -0,0 +1,10 @@
+{
+  "keybindings": {
+    "Home": {
+      "<q>": "Quit", // Quit the application
+      "<Ctrl-d>": "Quit", // Another way to quit
+      "<Ctrl-c>": "Quit", // Yet another way to quit
+      "<Ctrl-z>": "Suspend" // Suspend the application
+    },
+  }
+}

.envrc

@@ -0,0 +1,3 @@
+export TELEVISION_RS_CONFIG=`pwd`/.config
+export TELEVISION_RS_DATA=`pwd`/.data
+export TELEVISION_RS_LOG_LEVEL=debug

.github/workflows/cd.yml

@@ -0,0 +1,152 @@
+name: CD # Continuous Deployment
+
+on:
+  push:
+    tags:
+      - '[v]?[0-9]+.[0-9]+.[0-9]+'
+
+jobs:
+  publish:
+
+    name: Publishing for ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+
+    strategy:
+      matrix:
+        include:
+          - os: macos-latest
+            os-name: macos
+            target: x86_64-apple-darwin
+            architecture: x86_64
+            binary-postfix: ""
+            binary-name: television-rs
+            use-cross: false
+          - os: macos-latest
+            os-name: macos
+            target: aarch64-apple-darwin
+            architecture: arm64
+            binary-postfix: ""
+            use-cross: false
+            binary-name: television-rs
+          - os: ubuntu-latest
+            os-name: linux
+            target: x86_64-unknown-linux-gnu
+            architecture: x86_64
+            binary-postfix: ""
+            use-cross: false
+            binary-name: television-rs
+          - os: windows-latest
+            os-name: windows
+            target: x86_64-pc-windows-msvc
+            architecture: x86_64
+            binary-postfix: ".exe"
+            use-cross: false
+            binary-name: television-rs
+          - os: ubuntu-latest
+            os-name: linux
+            target: aarch64-unknown-linux-gnu
+            architecture: arm64
+            binary-postfix: ""
+            use-cross: true
+            binary-name: television-rs
+          - os: ubuntu-latest
+            os-name: linux
+            target: i686-unknown-linux-gnu
+            architecture: i686
+            binary-postfix: ""
+            use-cross: true
+            binary-name: television-rs
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+      - name: Install Rust toolchain
+        uses: actions-rs/toolchain@v1
+        with:
+          toolchain: stable
+
+          target: ${{ matrix.target }}
+
+          profile: minimal
+          override: true
+      - uses: Swatinem/rust-cache@v2
+      - name: Cargo build
+        uses: actions-rs/cargo@v1
+        with:
+          command: build
+
+          use-cross: ${{ matrix.use-cross }}
+
+          toolchain: stable
+
+          args: --release --target ${{ matrix.target }}
+
+
+      - name: install strip command
+        shell: bash
+        run: |
+
+          if [[ ${{ matrix.target }} == aarch64-unknown-linux-gnu ]]; then
+
+              sudo apt update
+              sudo apt-get install -y binutils-aarch64-linux-gnu
+          fi
+      - name: Packaging final binary
+        shell: bash
+        run: |
+
+          cd target/${{ matrix.target }}/release
+
+
+          ####### reduce binary size by removing debug symbols #######
+
+          BINARY_NAME=${{ matrix.binary-name }}${{ matrix.binary-postfix }}
+          if [[ ${{ matrix.target }} == aarch64-unknown-linux-gnu ]]; then
+
+            GCC_PREFIX="aarch64-linux-gnu-"
+          else
+            GCC_PREFIX=""
+          fi
+          "$GCC_PREFIX"strip $BINARY_NAME
+
+          ########## create tar.gz ##########
+
+          RELEASE_NAME=${{ matrix.binary-name }}-${GITHUB_REF/refs\/tags\//}-${{ matrix.os-name }}-${{ matrix.architecture }}
+
+          tar czvf $RELEASE_NAME.tar.gz $BINARY_NAME
+
+          ########## create sha256 ##########
+
+          if [[ ${{ runner.os }} == 'Windows' ]]; then
+
+            certutil -hashfile $RELEASE_NAME.tar.gz sha256 | grep -E [A-Fa-f0-9]{64} > $RELEASE_NAME.sha256
+          else
+            shasum -a 256 $RELEASE_NAME.tar.gz > $RELEASE_NAME.sha256
+          fi
+      - name: Releasing assets
+        uses: softprops/action-gh-release@v1
+        with:
+          files: |
+
+            target/${{ matrix.target }}/release/${{ matrix.binary-name }}-*.tar.gz
+            target/${{ matrix.target }}/release/${{ matrix.binary-name }}-*.sha256
+
+        env:
+
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+
+  publish-cargo:
+    name: Publishing to Cargo
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - run: cargo publish
+        env:
+
+          CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
+

.github/workflows/ci.yml

@@ -0,0 +1,63 @@
+name: CI # Continuous Integration
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+
+  test:
+    name: Test Suite
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@nightly
+      - uses: Swatinem/rust-cache@v2
+      - name: Run tests
+        run: cargo test --locked --all-features --workspace
+
+  rustfmt:
+    name: Rustfmt
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@nightly
+        with:
+          components: rustfmt
+      - uses: Swatinem/rust-cache@v2
+      - name: Check formatting
+        run: cargo fmt --all --check
+
+  clippy:
+    name: Clippy
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@nightly
+        with:
+          components: clippy
+      - uses: Swatinem/rust-cache@v2
+      - name: Clippy check
+        run: cargo clippy --all-targets --all-features --workspace -- -D warnings
+
+  docs:
+    name: Docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@nightly
+      - uses: Swatinem/rust-cache@v2
+      - name: Check documentation
+        env:
+          RUSTDOCFLAGS: -D warnings
+        run: cargo doc --no-deps --document-private-items --all-features --workspace --examples

.gitignore

@@ -0,0 +1,2 @@
+/target
+.data/*.log

Cargo.toml

@@ -0,0 +1,47 @@
+[package]
+name = "television-rs"
+version = "0.1.0"
+edition = "2021"
+description = "The revolution will be televised"
+authors = ["Alexandre Pasmantier <alex.pasmant@gmail.com>"]
+build = "build.rs"
+repository = "https://github.com/alexpasmantier/television"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+better-panic = "0.3.0"
+clap = { version = "4.4.5", features = [
+    "derive",
+    "cargo",
+    "wrap_help",
+    "unicode",
+    "string",
+    "unstable-styles",
+] }
+color-eyre = "0.6.3"
+config = "0.14.0"
+crossterm = { version = "0.28.1", features = ["serde", "event-stream"] }
+derive_deref = "1.1.1"
+directories = "5.0.1"
+futures = "0.3.30"
+human-panic = "2.0.1"
+json5 = "0.4.1"
+lazy_static = "1.5.0"
+libc = "0.2.158"
+pretty_assertions = "1.4.0"
+ratatui = { version = "0.28.1", features = ["serde", "macros"] }
+serde = { version = "1.0.208", features = ["derive"] }
+serde_json = "1.0.125"
+signal-hook = "0.3.17"
+strip-ansi-escapes = "0.2.0"
+strum = { version = "0.26.3", features = ["derive"] }
+tokio = { version = "1.39.3", features = ["full"] }
+tokio-util = "0.7.11"
+tracing = "0.1.40"
+tracing-error = "0.2.0"
+tracing-subscriber = { version = "0.3.18", features = ["env-filter", "serde"] }
+
+[build-dependencies]
+anyhow = "1.0.86"
+vergen-gix = { version = "1.0.0", features = ["build", "cargo"] }

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Alexandre Pasmantier <alex.pasmant@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,5 @@
+# television-rs
+
+[![CI](https://github.com//television-rs/workflows/CI/badge.svg)](https://github.com/alexpasmantier/television-rs/actions)
+
+The revolution will be televised

build.rs

@@ -0,0 +1,13 @@
+use anyhow::Result;
+use vergen_gix::{BuildBuilder, CargoBuilder, Emitter, GixBuilder};
+
+fn main() -> Result<()> {
+    let build = BuildBuilder::all_build()?;
+    let gix = GixBuilder::all_git()?;
+    let cargo = CargoBuilder::all_cargo()?;
+    Emitter::default()
+        .add_instructions(&build)?
+        .add_instructions(&gix)?
+        .add_instructions(&cargo)?
+        .emit()
+}

src/action.rs

@@ -0,0 +1,15 @@
+use serde::{Deserialize, Serialize};
+use strum::Display;
+
+#[derive(Debug, Clone, PartialEq, Eq, Display, Serialize, Deserialize)]
+pub enum Action {
+    Tick,
+    Render,
+    Resize(u16, u16),
+    Suspend,
+    Resume,
+    Quit,
+    ClearScreen,
+    Error(String),
+    Help,
+}

src/app.rs

@@ -0,0 +1,177 @@
+use color_eyre::Result;
+use crossterm::event::KeyEvent;
+use ratatui::prelude::Rect;
+use serde::{Deserialize, Serialize};
+use tokio::sync::mpsc;
+use tracing::{debug, info};
+
+use crate::{
+    action::Action,
+    components::{fps::FpsCounter, home::Home, Component},
+    config::Config,
+    tui::{Event, Tui},
+};
+
+pub struct App {
+    config: Config,
+    tick_rate: f64,
+    frame_rate: f64,
+    components: Vec<Box<dyn Component>>,
+    should_quit: bool,
+    should_suspend: bool,
+    mode: Mode,
+    last_tick_key_events: Vec<KeyEvent>,
+    action_tx: mpsc::UnboundedSender<Action>,
+    action_rx: mpsc::UnboundedReceiver<Action>,
+}
+
+#[derive(Default, Debug, Copy, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
+pub enum Mode {
+    #[default]
+    Home,
+}
+
+impl App {
+    pub fn new(tick_rate: f64, frame_rate: f64) -> Result<Self> {
+        let (action_tx, action_rx) = mpsc::unbounded_channel();
+        Ok(Self {
+            tick_rate,
+            frame_rate,
+            components: vec![Box::new(Home::new()), Box::new(FpsCounter::default())],
+            should_quit: false,
+            should_suspend: false,
+            config: Config::new()?,
+            mode: Mode::Home,
+            last_tick_key_events: Vec::new(),
+            action_tx,
+            action_rx,
+        })
+    }
+
+    pub async fn run(&mut self) -> Result<()> {
+        let mut tui = Tui::new()?
+            // .mouse(true) // uncomment this line to enable mouse support
+            .tick_rate(self.tick_rate)
+            .frame_rate(self.frame_rate);
+        tui.enter()?;
+
+        for component in self.components.iter_mut() {
+            component.register_action_handler(self.action_tx.clone())?;
+        }
+        for component in self.components.iter_mut() {
+            component.register_config_handler(self.config.clone())?;
+        }
+        for component in self.components.iter_mut() {
+            component.init(tui.size()?)?;
+        }
+
+        let action_tx = self.action_tx.clone();
+        loop {
+            self.handle_events(&mut tui).await?;
+            self.handle_actions(&mut tui)?;
+            if self.should_suspend {
+                tui.suspend()?;
+                action_tx.send(Action::Resume)?;
+                action_tx.send(Action::ClearScreen)?;
+                // tui.mouse(true);
+                tui.enter()?;
+            } else if self.should_quit {
+                tui.stop()?;
+                break;
+            }
+        }
+        tui.exit()?;
+        Ok(())
+    }
+
+    async fn handle_events(&mut self, tui: &mut Tui) -> Result<()> {
+        let Some(event) = tui.next_event().await else {
+            return Ok(());
+        };
+        let action_tx = self.action_tx.clone();
+        match event {
+            Event::Quit => action_tx.send(Action::Quit)?,
+            Event::Tick => action_tx.send(Action::Tick)?,
+            Event::Render => action_tx.send(Action::Render)?,
+            Event::Resize(x, y) => action_tx.send(Action::Resize(x, y))?,
+            Event::Key(key) => self.handle_key_event(key)?,
+            _ => {}
+        }
+        for component in self.components.iter_mut() {
+            if let Some(action) = component.handle_events(Some(event.clone()))? {
+                action_tx.send(action)?;
+            }
+        }
+        Ok(())
+    }
+
+    fn handle_key_event(&mut self, key: KeyEvent) -> Result<()> {
+        let action_tx = self.action_tx.clone();
+        let Some(keymap) = self.config.keybindings.get(&self.mode) else {
+            return Ok(());
+        };
+        match keymap.get(&vec![key]) {
+            Some(action) => {
+                info!("Got action: {action:?}");
+                action_tx.send(action.clone())?;
+            }
+            _ => {
+                // If the key was not handled as a single key action,
+                // then consider it for multi-key combinations.
+                self.last_tick_key_events.push(key);
+
+                // Check for multi-key combinations
+                if let Some(action) = keymap.get(&self.last_tick_key_events) {
+                    info!("Got action: {action:?}");
+                    action_tx.send(action.clone())?;
+                }
+            }
+        }
+        Ok(())
+    }
+
+    fn handle_actions(&mut self, tui: &mut Tui) -> Result<()> {
+        while let Ok(action) = self.action_rx.try_recv() {
+            if action != Action::Tick && action != Action::Render {
+                debug!("{action:?}");
+            }
+            match action {
+                Action::Tick => {
+                    self.last_tick_key_events.drain(..);
+                }
+                Action::Quit => self.should_quit = true,
+                Action::Suspend => self.should_suspend = true,
+                Action::Resume => self.should_suspend = false,
+                Action::ClearScreen => tui.terminal.clear()?,
+                Action::Resize(w, h) => self.handle_resize(tui, w, h)?,
+                Action::Render => self.render(tui)?,
+                _ => {}
+            }
+            for component in self.components.iter_mut() {
+                if let Some(action) = component.update(action.clone())? {
+                    self.action_tx.send(action)?
+                };
+            }
+        }
+        Ok(())
+    }
+
+    fn handle_resize(&mut self, tui: &mut Tui, w: u16, h: u16) -> Result<()> {
+        tui.resize(Rect::new(0, 0, w, h))?;
+        self.render(tui)?;
+        Ok(())
+    }
+
+    fn render(&mut self, tui: &mut Tui) -> Result<()> {
+        tui.draw(|frame| {
+            for component in self.components.iter_mut() {
+                if let Err(err) = component.draw(frame, frame.area()) {
+                    let _ = self
+                        .action_tx
+                        .send(Action::Error(format!("Failed to draw: {:?}", err)));
+                }
+            }
+        })?;
+        Ok(())
+    }
+}

src/cli.rs

@@ -0,0 +1,42 @@
+use clap::Parser;
+
+use crate::config::{get_config_dir, get_data_dir};
+
+#[derive(Parser, Debug)]
+#[command(author, version = version(), about)]
+pub struct Cli {
+    /// Tick rate, i.e. number of ticks per second
+    #[arg(short, long, value_name = "FLOAT", default_value_t = 4.0)]
+    pub tick_rate: f64,
+
+    /// Frame rate, i.e. number of frames per second
+    #[arg(short, long, value_name = "FLOAT", default_value_t = 60.0)]
+    pub frame_rate: f64,
+}
+
+const VERSION_MESSAGE: &str = concat!(
+    env!("CARGO_PKG_VERSION"),
+    "-",
+    env!("VERGEN_GIT_DESCRIBE"),
+    " (",
+    env!("VERGEN_BUILD_DATE"),
+    ")"
+);
+
+pub fn version() -> String {
+    let author = clap::crate_authors!();
+
+    // let current_exe_path = PathBuf::from(clap::crate_name!()).display().to_string();
+    let config_dir_path = get_config_dir().display().to_string();
+    let data_dir_path = get_data_dir().display().to_string();
+
+    format!(
+        "\
+{VERSION_MESSAGE}
+
+Authors: {author}
+
+Config directory: {config_dir_path}
+Data directory: {data_dir_path}"
+    )
+}

src/components.rs

@@ -0,0 +1,125 @@
+use color_eyre::Result;
+use crossterm::event::{KeyEvent, MouseEvent};
+use ratatui::{
+    layout::{Rect, Size},
+    Frame,
+};
+use tokio::sync::mpsc::UnboundedSender;
+
+use crate::{action::Action, config::Config, tui::Event};
+
+pub mod fps;
+pub mod home;
+
+/// `Component` is a trait that represents a visual and interactive element of the user interface.
+///
+/// Implementors of this trait can be registered with the main application loop and will be able to
+/// receive events, update state, and be rendered on the screen.
+pub trait Component {
+    /// Register an action handler that can send actions for processing if necessary.
+    ///
+    /// # Arguments
+    ///
+    /// * `tx` - An unbounded sender that can send actions.
+    ///
+    /// # Returns
+    ///
+    /// * `Result<()>` - An Ok result or an error.
+    fn register_action_handler(&mut self, tx: UnboundedSender<Action>) -> Result<()> {
+        let _ = tx; // to appease clippy
+        Ok(())
+    }
+    /// Register a configuration handler that provides configuration settings if necessary.
+    ///
+    /// # Arguments
+    ///
+    /// * `config` - Configuration settings.
+    ///
+    /// # Returns
+    ///
+    /// * `Result<()>` - An Ok result or an error.
+    fn register_config_handler(&mut self, config: Config) -> Result<()> {
+        let _ = config; // to appease clippy
+        Ok(())
+    }
+    /// Initialize the component with a specified area if necessary.
+    ///
+    /// # Arguments
+    ///
+    /// * `area` - Rectangular area to initialize the component within.
+    ///
+    /// # Returns
+    ///
+    /// * `Result<()>` - An Ok result or an error.
+    fn init(&mut self, area: Size) -> Result<()> {
+        let _ = area; // to appease clippy
+        Ok(())
+    }
+    /// Handle incoming events and produce actions if necessary.
+    ///
+    /// # Arguments
+    ///
+    /// * `event` - An optional event to be processed.
+    ///
+    /// # Returns
+    ///
+    /// * `Result<Option<Action>>` - An action to be processed or none.
+    fn handle_events(&mut self, event: Option<Event>) -> Result<Option<Action>> {
+        let action = match event {
+            Some(Event::Key(key_event)) => self.handle_key_event(key_event)?,
+            Some(Event::Mouse(mouse_event)) => self.handle_mouse_event(mouse_event)?,
+            _ => None,
+        };
+        Ok(action)
+    }
+    /// Handle key events and produce actions if necessary.
+    ///
+    /// # Arguments
+    ///
+    /// * `key` - A key event to be processed.
+    ///
+    /// # Returns
+    ///
+    /// * `Result<Option<Action>>` - An action to be processed or none.
+    fn handle_key_event(&mut self, key: KeyEvent) -> Result<Option<Action>> {
+        let _ = key; // to appease clippy
+        Ok(None)
+    }
+    /// Handle mouse events and produce actions if necessary.
+    ///
+    /// # Arguments
+    ///
+    /// * `mouse` - A mouse event to be processed.
+    ///
+    /// # Returns
+    ///
+    /// * `Result<Option<Action>>` - An action to be processed or none.
+    fn handle_mouse_event(&mut self, mouse: MouseEvent) -> Result<Option<Action>> {
+        let _ = mouse; // to appease clippy
+        Ok(None)
+    }
+    /// Update the state of the component based on a received action. (REQUIRED)
+    ///
+    /// # Arguments
+    ///
+    /// * `action` - An action that may modify the state of the component.
+    ///
+    /// # Returns
+    ///
+    /// * `Result<Option<Action>>` - An action to be processed or none.
+    fn update(&mut self, action: Action) -> Result<Option<Action>> {
+        let _ = action; // to appease clippy
+        Ok(None)
+    }
+    /// Render the component on the screen. (REQUIRED)
+    ///
+    /// # Arguments
+    ///
+    /// * `f` - A frame used for rendering.
+    /// * `area` - The area in which the component should be drawn.
+    ///
+    /// # Returns
+    ///
+    /// * `Result<()>` - An Ok result or an error.
+    fn draw(&mut self, frame: &mut Frame, area: Rect) -> Result<()>;
+}

src/components/fps.rs

@@ -0,0 +1,91 @@
+use std::time::Instant;
+
+use color_eyre::Result;
+use ratatui::{
+    layout::{Constraint, Layout, Rect},
+    style::{Style, Stylize},
+    text::Span,
+    widgets::Paragraph,
+    Frame,
+};
+
+use super::Component;
+
+use crate::action::Action;
+
+#[derive(Debug, Clone, PartialEq)]
+pub struct FpsCounter {
+    last_tick_update: Instant,
+    tick_count: u32,
+    ticks_per_second: f64,
+
+    last_frame_update: Instant,
+    frame_count: u32,
+    frames_per_second: f64,
+}
+
+impl Default for FpsCounter {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl FpsCounter {
+    pub fn new() -> Self {
+        Self {
+            last_tick_update: Instant::now(),
+            tick_count: 0,
+            ticks_per_second: 0.0,
+            last_frame_update: Instant::now(),
+            frame_count: 0,
+            frames_per_second: 0.0,
+        }
+    }
+
+    fn app_tick(&mut self) -> Result<()> {
+        self.tick_count += 1;
+        let now = Instant::now();
+        let elapsed = (now - self.last_tick_update).as_secs_f64();
+        if elapsed >= 1.0 {
+            self.ticks_per_second = self.tick_count as f64 / elapsed;
+            self.last_tick_update = now;
+            self.tick_count = 0;
+        }
+        Ok(())
+    }
+
+    fn render_tick(&mut self) -> Result<()> {
+        self.frame_count += 1;
+        let now = Instant::now();
+        let elapsed = (now - self.last_frame_update).as_secs_f64();
+        if elapsed >= 1.0 {
+            self.frames_per_second = self.frame_count as f64 / elapsed;
+            self.last_frame_update = now;
+            self.frame_count = 0;
+        }
+        Ok(())
+    }
+}
+
+impl Component for FpsCounter {
+    fn update(&mut self, action: Action) -> Result<Option<Action>> {
+        match action {
+            Action::Tick => self.app_tick()?,
+            Action::Render => self.render_tick()?,
+            _ => {}
+        };
+        Ok(None)
+    }
+
+    fn draw(&mut self, frame: &mut Frame, area: Rect) -> Result<()> {
+        let [top, _] = Layout::vertical([Constraint::Length(1), Constraint::Min(0)]).areas(area);
+        let message = format!(
+            "{:.2} ticks/sec, {:.2} FPS",
+            self.ticks_per_second, self.frames_per_second
+        );
+        let span = Span::styled(message, Style::new().dim());
+        let paragraph = Paragraph::new(span).right_aligned();
+        frame.render_widget(paragraph, top);
+        Ok(())
+    }
+}

src/components/home.rs

@@ -0,0 +1,48 @@
+use color_eyre::Result;
+use ratatui::{prelude::*, widgets::*};
+use tokio::sync::mpsc::UnboundedSender;
+
+use super::Component;
+use crate::{action::Action, config::Config};
+
+#[derive(Default)]
+pub struct Home {
+    command_tx: Option<UnboundedSender<Action>>,
+    config: Config,
+}
+
+impl Home {
+    pub fn new() -> Self {
+        Self::default()
+    }
+}
+
+impl Component for Home {
+    fn register_action_handler(&mut self, tx: UnboundedSender<Action>) -> Result<()> {
+        self.command_tx = Some(tx);
+        Ok(())
+    }
+
+    fn register_config_handler(&mut self, config: Config) -> Result<()> {
+        self.config = config;
+        Ok(())
+    }
+
+    fn update(&mut self, action: Action) -> Result<Option<Action>> {
+        match action {
+            Action::Tick => {
+                // add any logic here that should run on every tick
+            }
+            Action::Render => {
+                // add any logic here that should run on every render
+            }
+            _ => {}
+        }
+        Ok(None)
+    }
+
+    fn draw(&mut self, frame: &mut Frame, area: Rect) -> Result<()> {
+        frame.render_widget(Paragraph::new("hello world"), area);
+        Ok(())
+    }
+}

src/config.rs

@@ -0,0 +1,598 @@
+#![allow(dead_code)] // Remove this once you start using the code
+
+use std::{collections::HashMap, env, path::PathBuf};
+
+use color_eyre::Result;
+use crossterm::event::{KeyCode, KeyEvent, KeyModifiers};
+use derive_deref::{Deref, DerefMut};
+use directories::ProjectDirs;
+use lazy_static::lazy_static;
+use ratatui::style::{Color, Modifier, Style};
+use serde::{de::Deserializer, Deserialize};
+use tracing::error;
+
+use crate::{action::Action, app::Mode};
+
+const CONFIG: &str = include_str!("../.config/config.json5");
+
+#[derive(Clone, Debug, Deserialize, Default)]
+pub struct AppConfig {
+    #[serde(default)]
+    pub data_dir: PathBuf,
+    #[serde(default)]
+    pub config_dir: PathBuf,
+}
+
+#[derive(Clone, Debug, Default, Deserialize)]
+pub struct Config {
+    #[serde(default, flatten)]
+    pub config: AppConfig,
+    #[serde(default)]
+    pub keybindings: KeyBindings,
+    #[serde(default)]
+    pub styles: Styles,
+}
+
+lazy_static! {
+    pub static ref PROJECT_NAME: String = env!("CARGO_CRATE_NAME").to_uppercase().to_string();
+    pub static ref DATA_FOLDER: Option<PathBuf> =
+        env::var(format!("{}_DATA", PROJECT_NAME.clone()))
+            .ok()
+            .map(PathBuf::from);
+    pub static ref CONFIG_FOLDER: Option<PathBuf> =
+        env::var(format!("{}_CONFIG", PROJECT_NAME.clone()))
+            .ok()
+            .map(PathBuf::from);
+}
+
+impl Config {
+    pub fn new() -> Result<Self, config::ConfigError> {
+        let default_config: Config = json5::from_str(CONFIG).unwrap();
+        let data_dir = get_data_dir();
+        let config_dir = get_config_dir();
+        let mut builder = config::Config::builder()
+            .set_default("data_dir", data_dir.to_str().unwrap())?
+            .set_default("config_dir", config_dir.to_str().unwrap())?;
+
+        let config_files = [
+            ("config.json5", config::FileFormat::Json5),
+            ("config.json", config::FileFormat::Json),
+            ("config.yaml", config::FileFormat::Yaml),
+            ("config.toml", config::FileFormat::Toml),
+            ("config.ini", config::FileFormat::Ini),
+        ];
+        let mut found_config = false;
+        for (file, format) in &config_files {
+            let source = config::File::from(config_dir.join(file))
+                .format(*format)
+                .required(false);
+            builder = builder.add_source(source);
+            if config_dir.join(file).exists() {
+                found_config = true
+            }
+        }
+        if !found_config {
+            error!("No configuration file found. Application may not behave as expected");
+        }
+
+        let mut cfg: Self = builder.build()?.try_deserialize()?;
+
+        for (mode, default_bindings) in default_config.keybindings.iter() {
+            let user_bindings = cfg.keybindings.entry(*mode).or_default();
+            for (key, cmd) in default_bindings.iter() {
+                user_bindings
+                    .entry(key.clone())
+                    .or_insert_with(|| cmd.clone());
+            }
+        }
+        for (mode, default_styles) in default_config.styles.iter() {
+            let user_styles = cfg.styles.entry(*mode).or_default();
+            for (style_key, style) in default_styles.iter() {
+                user_styles.entry(style_key.clone()).or_insert(*style);
+            }
+        }
+
+        Ok(cfg)
+    }
+}
+
+pub fn get_data_dir() -> PathBuf {
+    let directory = if let Some(s) = DATA_FOLDER.clone() {
+        s
+    } else if let Some(proj_dirs) = project_directory() {
+        proj_dirs.data_local_dir().to_path_buf()
+    } else {
+        PathBuf::from(".").join(".data")
+    };
+    directory
+}
+
+pub fn get_config_dir() -> PathBuf {
+    let directory = if let Some(s) = CONFIG_FOLDER.clone() {
+        s
+    } else if let Some(proj_dirs) = project_directory() {
+        proj_dirs.config_local_dir().to_path_buf()
+    } else {
+        PathBuf::from(".").join(".config")
+    };
+    directory
+}
+
+fn project_directory() -> Option<ProjectDirs> {
+    ProjectDirs::from("com", "kdheepak", env!("CARGO_PKG_NAME"))
+}
+
+#[derive(Clone, Debug, Default, Deref, DerefMut)]
+pub struct KeyBindings(pub HashMap<Mode, HashMap<Vec<KeyEvent>, Action>>);
+
+impl<'de> Deserialize<'de> for KeyBindings {
+    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+    where
+        D: Deserializer<'de>,
+    {
+        let parsed_map = HashMap::<Mode, HashMap<String, Action>>::deserialize(deserializer)?;
+
+        let keybindings = parsed_map
+            .into_iter()
+            .map(|(mode, inner_map)| {
+                let converted_inner_map = inner_map
+                    .into_iter()
+                    .map(|(key_str, cmd)| (parse_key_sequence(&key_str).unwrap(), cmd))
+                    .collect();
+                (mode, converted_inner_map)
+            })
+            .collect();
+
+        Ok(KeyBindings(keybindings))
+    }
+}
+
+fn parse_key_event(raw: &str) -> Result<KeyEvent, String> {
+    let raw_lower = raw.to_ascii_lowercase();
+    let (remaining, modifiers) = extract_modifiers(&raw_lower);
+    parse_key_code_with_modifiers(remaining, modifiers)
+}
+
+fn extract_modifiers(raw: &str) -> (&str, KeyModifiers) {
+    let mut modifiers = KeyModifiers::empty();
+    let mut current = raw;
+
+    loop {
+        match current {
+            rest if rest.starts_with("ctrl-") => {
+                modifiers.insert(KeyModifiers::CONTROL);
+                current = &rest[5..];
+            }
+            rest if rest.starts_with("alt-") => {
+                modifiers.insert(KeyModifiers::ALT);
+                current = &rest[4..];
+            }
+            rest if rest.starts_with("shift-") => {
+                modifiers.insert(KeyModifiers::SHIFT);
+                current = &rest[6..];
+            }
+            _ => break, // break out of the loop if no known prefix is detected
+        };
+    }
+
+    (current, modifiers)
+}
+
+fn parse_key_code_with_modifiers(
+    raw: &str,
+    mut modifiers: KeyModifiers,
+) -> Result<KeyEvent, String> {
+    let c = match raw {
+        "esc" => KeyCode::Esc,
+        "enter" => KeyCode::Enter,
+        "left" => KeyCode::Left,
+        "right" => KeyCode::Right,
+        "up" => KeyCode::Up,
+        "down" => KeyCode::Down,
+        "home" => KeyCode::Home,
+        "end" => KeyCode::End,
+        "pageup" => KeyCode::PageUp,
+        "pagedown" => KeyCode::PageDown,
+        "backtab" => {
+            modifiers.insert(KeyModifiers::SHIFT);
+            KeyCode::BackTab
+        }
+        "backspace" => KeyCode::Backspace,
+        "delete" => KeyCode::Delete,
+        "insert" => KeyCode::Insert,
+        "f1" => KeyCode::F(1),
+        "f2" => KeyCode::F(2),
+        "f3" => KeyCode::F(3),
+        "f4" => KeyCode::F(4),
+        "f5" => KeyCode::F(5),
+        "f6" => KeyCode::F(6),
+        "f7" => KeyCode::F(7),
+        "f8" => KeyCode::F(8),
+        "f9" => KeyCode::F(9),
+        "f10" => KeyCode::F(10),
+        "f11" => KeyCode::F(11),
+        "f12" => KeyCode::F(12),
+        "space" => KeyCode::Char(' '),
+        "hyphen" => KeyCode::Char('-'),
+        "minus" => KeyCode::Char('-'),
+        "tab" => KeyCode::Tab,
+        c if c.len() == 1 => {
+            let mut c = c.chars().next().unwrap();
+            if modifiers.contains(KeyModifiers::SHIFT) {
+                c = c.to_ascii_uppercase();
+            }
+            KeyCode::Char(c)
+        }
+        _ => return Err(format!("Unable to parse {raw}")),
+    };
+    Ok(KeyEvent::new(c, modifiers))
+}
+
+pub fn key_event_to_string(key_event: &KeyEvent) -> String {
+    let char;
+    let key_code = match key_event.code {
+        KeyCode::Backspace => "backspace",
+        KeyCode::Enter => "enter",
+        KeyCode::Left => "left",
+        KeyCode::Right => "right",
+        KeyCode::Up => "up",
+        KeyCode::Down => "down",
+        KeyCode::Home => "home",
+        KeyCode::End => "end",
+        KeyCode::PageUp => "pageup",
+        KeyCode::PageDown => "pagedown",
+        KeyCode::Tab => "tab",
+        KeyCode::BackTab => "backtab",
+        KeyCode::Delete => "delete",
+        KeyCode::Insert => "insert",
+        KeyCode::F(c) => {
+            char = format!("f({c})");
+            &char
+        }
+        KeyCode::Char(' ') => "space",
+        KeyCode::Char(c) => {
+            char = c.to_string();
+            &char
+        }
+        KeyCode::Esc => "esc",
+        KeyCode::Null => "",
+        KeyCode::CapsLock => "",
+        KeyCode::Menu => "",
+        KeyCode::ScrollLock => "",
+        KeyCode::Media(_) => "",
+        KeyCode::NumLock => "",
+        KeyCode::PrintScreen => "",
+        KeyCode::Pause => "",
+        KeyCode::KeypadBegin => "",
+        KeyCode::Modifier(_) => "",
+    };
+
+    let mut modifiers = Vec::with_capacity(3);
+
+    if key_event.modifiers.intersects(KeyModifiers::CONTROL) {
+        modifiers.push("ctrl");
+    }
+
+    if key_event.modifiers.intersects(KeyModifiers::SHIFT) {
+        modifiers.push("shift");
+    }
+
+    if key_event.modifiers.intersects(KeyModifiers::ALT) {
+        modifiers.push("alt");
+    }
+
+    let mut key = modifiers.join("-");
+
+    if !key.is_empty() {
+        key.push('-');
+    }
+    key.push_str(key_code);
+
+    key
+}
+
+pub fn parse_key_sequence(raw: &str) -> Result<Vec<KeyEvent>, String> {
+    if raw.chars().filter(|c| *c == '>').count() != raw.chars().filter(|c| *c == '<').count() {
+        return Err(format!("Unable to parse `{}`", raw));
+    }
+    let raw = if !raw.contains("><") {
+        let raw = raw.strip_prefix('<').unwrap_or(raw);
+        let raw = raw.strip_prefix('>').unwrap_or(raw);
+        raw
+    } else {
+        raw
+    };
+    let sequences = raw
+        .split("><")
+        .map(|seq| {
+            if let Some(s) = seq.strip_prefix('<') {
+                s
+            } else if let Some(s) = seq.strip_suffix('>') {
+                s
+            } else {
+                seq
+            }
+        })
+        .collect::<Vec<_>>();
+
+    sequences.into_iter().map(parse_key_event).collect()
+}
+
+#[derive(Clone, Debug, Default, Deref, DerefMut)]
+pub struct Styles(pub HashMap<Mode, HashMap<String, Style>>);
+
+impl<'de> Deserialize<'de> for Styles {
+    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+    where
+        D: Deserializer<'de>,
+    {
+        let parsed_map = HashMap::<Mode, HashMap<String, String>>::deserialize(deserializer)?;
+
+        let styles = parsed_map
+            .into_iter()
+            .map(|(mode, inner_map)| {
+                let converted_inner_map = inner_map
+                    .into_iter()
+                    .map(|(str, style)| (str, parse_style(&style)))
+                    .collect();
+                (mode, converted_inner_map)
+            })
+            .collect();
+
+        Ok(Styles(styles))
+    }
+}
+
+pub fn parse_style(line: &str) -> Style {
+    let (foreground, background) =
+        line.split_at(line.to_lowercase().find("on ").unwrap_or(line.len()));
+    let foreground = process_color_string(foreground);
+    let background = process_color_string(&background.replace("on ", ""));
+
+    let mut style = Style::default();
+    if let Some(fg) = parse_color(&foreground.0) {
+        style = style.fg(fg);
+    }
+    if let Some(bg) = parse_color(&background.0) {
+        style = style.bg(bg);
+    }
+    style = style.add_modifier(foreground.1 | background.1);
+    style
+}
+
+fn process_color_string(color_str: &str) -> (String, Modifier) {
+    let color = color_str
+        .replace("grey", "gray")
+        .replace("bright ", "")
+        .replace("bold ", "")
+        .replace("underline ", "")
+        .replace("inverse ", "");
+
+    let mut modifiers = Modifier::empty();
+    if color_str.contains("underline") {
+        modifiers |= Modifier::UNDERLINED;
+    }
+    if color_str.contains("bold") {
+        modifiers |= Modifier::BOLD;
+    }
+    if color_str.contains("inverse") {
+        modifiers |= Modifier::REVERSED;
+    }
+
+    (color, modifiers)
+}
+
+fn parse_color(s: &str) -> Option<Color> {
+    let s = s.trim_start();
+    let s = s.trim_end();
+    if s.contains("bright color") {
+        let s = s.trim_start_matches("bright ");
+        let c = s
+            .trim_start_matches("color")
+            .parse::<u8>()
+            .unwrap_or_default();
+        Some(Color::Indexed(c.wrapping_shl(8)))
+    } else if s.contains("color") {
+        let c = s
+            .trim_start_matches("color")
+            .parse::<u8>()
+            .unwrap_or_default();
+        Some(Color::Indexed(c))
+    } else if s.contains("gray") {
+        let c = 232
+            + s.trim_start_matches("gray")
+                .parse::<u8>()
+                .unwrap_or_default();
+        Some(Color::Indexed(c))
+    } else if s.contains("rgb") {
+        let red = (s.as_bytes()[3] as char).to_digit(10).unwrap_or_default() as u8;
+        let green = (s.as_bytes()[4] as char).to_digit(10).unwrap_or_default() as u8;
+        let blue = (s.as_bytes()[5] as char).to_digit(10).unwrap_or_default() as u8;
+        let c = 16 + red * 36 + green * 6 + blue;
+        Some(Color::Indexed(c))
+    } else if s == "bold black" {
+        Some(Color::Indexed(8))
+    } else if s == "bold red" {
+        Some(Color::Indexed(9))
+    } else if s == "bold green" {
+        Some(Color::Indexed(10))
+    } else if s == "bold yellow" {
+        Some(Color::Indexed(11))
+    } else if s == "bold blue" {
+        Some(Color::Indexed(12))
+    } else if s == "bold magenta" {
+        Some(Color::Indexed(13))
+    } else if s == "bold cyan" {
+        Some(Color::Indexed(14))
+    } else if s == "bold white" {
+        Some(Color::Indexed(15))
+    } else if s == "black" {
+        Some(Color::Indexed(0))
+    } else if s == "red" {
+        Some(Color::Indexed(1))
+    } else if s == "green" {
+        Some(Color::Indexed(2))
+    } else if s == "yellow" {
+        Some(Color::Indexed(3))
+    } else if s == "blue" {
+        Some(Color::Indexed(4))
+    } else if s == "magenta" {
+        Some(Color::Indexed(5))
+    } else if s == "cyan" {
+        Some(Color::Indexed(6))
+    } else if s == "white" {
+        Some(Color::Indexed(7))
+    } else {
+        None
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use pretty_assertions::assert_eq;
+
+    use super::*;
+
+    #[test]
+    fn test_parse_style_default() {
+        let style = parse_style("");
+        assert_eq!(style, Style::default());
+    }
+
+    #[test]
+    fn test_parse_style_foreground() {
+        let style = parse_style("red");
+        assert_eq!(style.fg, Some(Color::Indexed(1)));
+    }
+
+    #[test]
+    fn test_parse_style_background() {
+        let style = parse_style("on blue");
+        assert_eq!(style.bg, Some(Color::Indexed(4)));
+    }
+
+    #[test]
+    fn test_parse_style_modifiers() {
+        let style = parse_style("underline red on blue");
+        assert_eq!(style.fg, Some(Color::Indexed(1)));
+        assert_eq!(style.bg, Some(Color::Indexed(4)));
+    }
+
+    #[test]
+    fn test_process_color_string() {
+        let (color, modifiers) = process_color_string("underline bold inverse gray");
+        assert_eq!(color, "gray");
+        assert!(modifiers.contains(Modifier::UNDERLINED));
+        assert!(modifiers.contains(Modifier::BOLD));
+        assert!(modifiers.contains(Modifier::REVERSED));
+    }
+
+    #[test]
+    fn test_parse_color_rgb() {
+        let color = parse_color("rgb123");
+        let expected = 16 + 36 + 2 * 6 + 3;
+        assert_eq!(color, Some(Color::Indexed(expected)));
+    }
+
+    #[test]
+    fn test_parse_color_unknown() {
+        let color = parse_color("unknown");
+        assert_eq!(color, None);
+    }
+
+    #[test]
+    fn test_config() -> Result<()> {
+        let c = Config::new()?;
+        assert_eq!(
+            c.keybindings
+                .get(&Mode::Home)
+                .unwrap()
+                .get(&parse_key_sequence("<q>").unwrap_or_default())
+                .unwrap(),
+            &Action::Quit
+        );
+        Ok(())
+    }
+
+    #[test]
+    fn test_simple_keys() {
+        assert_eq!(
+            parse_key_event("a").unwrap(),
+            KeyEvent::new(KeyCode::Char('a'), KeyModifiers::empty())
+        );
+
+        assert_eq!(
+            parse_key_event("enter").unwrap(),
+            KeyEvent::new(KeyCode::Enter, KeyModifiers::empty())
+        );
+
+        assert_eq!(
+            parse_key_event("esc").unwrap(),
+            KeyEvent::new(KeyCode::Esc, KeyModifiers::empty())
+        );
+    }
+
+    #[test]
+    fn test_with_modifiers() {
+        assert_eq!(
+            parse_key_event("ctrl-a").unwrap(),
+            KeyEvent::new(KeyCode::Char('a'), KeyModifiers::CONTROL)
+        );
+
+        assert_eq!(
+            parse_key_event("alt-enter").unwrap(),
+            KeyEvent::new(KeyCode::Enter, KeyModifiers::ALT)
+        );
+
+        assert_eq!(
+            parse_key_event("shift-esc").unwrap(),
+            KeyEvent::new(KeyCode::Esc, KeyModifiers::SHIFT)
+        );
+    }
+
+    #[test]
+    fn test_multiple_modifiers() {
+        assert_eq!(
+            parse_key_event("ctrl-alt-a").unwrap(),
+            KeyEvent::new(
+                KeyCode::Char('a'),
+                KeyModifiers::CONTROL | KeyModifiers::ALT
+            )
+        );
+
+        assert_eq!(
+            parse_key_event("ctrl-shift-enter").unwrap(),
+            KeyEvent::new(KeyCode::Enter, KeyModifiers::CONTROL | KeyModifiers::SHIFT)
+        );
+    }
+
+    #[test]
+    fn test_reverse_multiple_modifiers() {
+        assert_eq!(
+            key_event_to_string(&KeyEvent::new(
+                KeyCode::Char('a'),
+                KeyModifiers::CONTROL | KeyModifiers::ALT
+            )),
+            "ctrl-alt-a".to_string()
+        );
+    }
+
+    #[test]
+    fn test_invalid_keys() {
+        assert!(parse_key_event("invalid-key").is_err());
+        assert!(parse_key_event("ctrl-invalid-key").is_err());
+    }
+
+    #[test]
+    fn test_case_insensitivity() {
+        assert_eq!(
+            parse_key_event("CTRL-a").unwrap(),
+            KeyEvent::new(KeyCode::Char('a'), KeyModifiers::CONTROL)
+        );
+
+        assert_eq!(
+            parse_key_event("AlT-eNtEr").unwrap(),
+            KeyEvent::new(KeyCode::Enter, KeyModifiers::ALT)
+        );
+    }
+}

src/errors.rs

@@ -0,0 +1,76 @@
+use std::env;
+
+use color_eyre::Result;
+use tracing::error;
+
+pub fn init() -> Result<()> {
+    let (panic_hook, eyre_hook) = color_eyre::config::HookBuilder::default()
+        .panic_section(format!(
+            "This is a bug. Consider reporting it at {}",
+            env!("CARGO_PKG_REPOSITORY")
+        ))
+        .capture_span_trace_by_default(false)
+        .display_location_section(false)
+        .display_env_section(false)
+        .into_hooks();
+    eyre_hook.install()?;
+    std::panic::set_hook(Box::new(move |panic_info| {
+        if let Ok(mut t) = crate::tui::Tui::new() {
+            if let Err(r) = t.exit() {
+                error!("Unable to exit Terminal: {:?}", r);
+            }
+        }
+
+        #[cfg(not(debug_assertions))]
+        {
+            use human_panic::{handle_dump, metadata, print_msg};
+            let metadata = metadata!();
+            let file_path = handle_dump(&metadata, panic_info);
+            // prints human-panic message
+            print_msg(file_path, &metadata)
+                .expect("human-panic: printing error message to console failed");
+            eprintln!("{}", panic_hook.panic_report(panic_info)); // prints color-eyre stack trace to stderr
+        }
+        let msg = format!("{}", panic_hook.panic_report(panic_info));
+        error!("Error: {}", strip_ansi_escapes::strip_str(msg));
+
+        #[cfg(debug_assertions)]
+        {
+            // Better Panic stacktrace that is only enabled when debugging.
+            better_panic::Settings::auto()
+                .most_recent_first(false)
+                .lineno_suffix(true)
+                .verbosity(better_panic::Verbosity::Full)
+                .create_panic_handler()(panic_info);
+        }
+
+        std::process::exit(libc::EXIT_FAILURE);
+    }));
+    Ok(())
+}
+
+/// Similar to the `std::dbg!` macro, but generates `tracing` events rather
+/// than printing to stdout.
+///
+/// By default, the verbosity level for the generated events is `DEBUG`, but
+/// this can be customized.
+#[macro_export]
+macro_rules! trace_dbg {
+        (target: $target:expr, level: $level:expr, $ex:expr) => {{
+                match $ex {
+                        value => {
+                                tracing::event!(target: $target, $level, ?value, stringify!($ex));
+                                value
+                        }
+                }
+        }};
+        (level: $level:expr, $ex:expr) => {
+                trace_dbg!(target: module_path!(), level: $level, $ex)
+        };
+        (target: $target:expr, $ex:expr) => {
+                trace_dbg!(target: $target, level: tracing::Level::DEBUG, $ex)
+        };
+        ($ex:expr) => {
+                trace_dbg!(level: tracing::Level::DEBUG, $ex)
+        };
+}

src/logging.rs

@@ -0,0 +1,36 @@
+use color_eyre::Result;
+use tracing_error::ErrorLayer;
+use tracing_subscriber::{fmt, prelude::*, EnvFilter};
+
+use crate::config;
+
+lazy_static::lazy_static! {
+    pub static ref LOG_ENV: String = format!("{}_LOGLEVEL", config::PROJECT_NAME.clone());
+    pub static ref LOG_FILE: String = format!("{}.log", env!("CARGO_PKG_NAME"));
+}
+
+pub fn init() -> Result<()> {
+    let directory = config::get_data_dir();
+    std::fs::create_dir_all(directory.clone())?;
+    let log_path = directory.join(LOG_FILE.clone());
+    let log_file = std::fs::File::create(log_path)?;
+    let env_filter = EnvFilter::builder().with_default_directive(tracing::Level::INFO.into());
+    // If the `RUST_LOG` environment variable is set, use that as the default, otherwise use the
+    // value of the `LOG_ENV` environment variable. If the `LOG_ENV` environment variable contains
+    // errors, then this will return an error.
+    let env_filter = env_filter
+        .try_from_env()
+        .or_else(|_| env_filter.with_env_var(LOG_ENV.clone()).from_env())?;
+    let file_subscriber = fmt::layer()
+        .with_file(true)
+        .with_line_number(true)
+        .with_writer(log_file)
+        .with_target(false)
+        .with_ansi(false)
+        .with_filter(env_filter);
+    tracing_subscriber::registry()
+        .with(file_subscriber)
+        .with(ErrorLayer::default())
+        .try_init()?;
+    Ok(())
+}

src/main.rs

@@ -0,0 +1,25 @@
+use clap::Parser;
+use cli::Cli;
+use color_eyre::Result;
+
+use crate::app::App;
+
+mod action;
+mod app;
+mod cli;
+mod components;
+mod config;
+mod errors;
+mod logging;
+mod tui;
+
+#[tokio::main]
+async fn main() -> Result<()> {
+    crate::errors::init()?;
+    crate::logging::init()?;
+
+    let args = Cli::parse();
+    let mut app = App::new(args.tick_rate, args.frame_rate)?;
+    app.run().await?;
+    Ok(())
+}

src/tui.rs

@@ -0,0 +1,235 @@
+#![allow(dead_code)] // Remove this once you start using the code
+
+use std::{
+    io::{stdout, Stdout},
+    ops::{Deref, DerefMut},
+    time::Duration,
+};
+
+use color_eyre::Result;
+use crossterm::{
+    cursor,
+    event::{
+        DisableBracketedPaste, DisableMouseCapture, EnableBracketedPaste, EnableMouseCapture,
+        Event as CrosstermEvent, EventStream, KeyEvent, KeyEventKind, MouseEvent,
+    },
+    terminal::{EnterAlternateScreen, LeaveAlternateScreen},
+};
+use futures::{FutureExt, StreamExt};
+use ratatui::backend::CrosstermBackend as Backend;
+use serde::{Deserialize, Serialize};
+use tokio::{
+    sync::mpsc::{self, UnboundedReceiver, UnboundedSender},
+    task::JoinHandle,
+    time::interval,
+};
+use tokio_util::sync::CancellationToken;
+use tracing::error;
+
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub enum Event {
+    Init,
+    Quit,
+    Error,
+    Closed,
+    Tick,
+    Render,
+    FocusGained,
+    FocusLost,
+    Paste(String),
+    Key(KeyEvent),
+    Mouse(MouseEvent),
+    Resize(u16, u16),
+}
+
+pub struct Tui {
+    pub terminal: ratatui::Terminal<Backend<Stdout>>,
+    pub task: JoinHandle<()>,
+    pub cancellation_token: CancellationToken,
+    pub event_rx: UnboundedReceiver<Event>,
+    pub event_tx: UnboundedSender<Event>,
+    pub frame_rate: f64,
+    pub tick_rate: f64,
+    pub mouse: bool,
+    pub paste: bool,
+}
+
+impl Tui {
+    pub fn new() -> Result<Self> {
+        let (event_tx, event_rx) = mpsc::unbounded_channel();
+        Ok(Self {
+            terminal: ratatui::Terminal::new(Backend::new(stdout()))?,
+            task: tokio::spawn(async {}),
+            cancellation_token: CancellationToken::new(),
+            event_rx,
+            event_tx,
+            frame_rate: 60.0,
+            tick_rate: 4.0,
+            mouse: false,
+            paste: false,
+        })
+    }
+
+    pub fn tick_rate(mut self, tick_rate: f64) -> Self {
+        self.tick_rate = tick_rate;
+        self
+    }
+
+    pub fn frame_rate(mut self, frame_rate: f64) -> Self {
+        self.frame_rate = frame_rate;
+        self
+    }
+
+    pub fn mouse(mut self, mouse: bool) -> Self {
+        self.mouse = mouse;
+        self
+    }
+
+    pub fn paste(mut self, paste: bool) -> Self {
+        self.paste = paste;
+        self
+    }
+
+    pub fn start(&mut self) {
+        self.cancel(); // Cancel any existing task
+        self.cancellation_token = CancellationToken::new();
+        let event_loop = Self::event_loop(
+            self.event_tx.clone(),
+            self.cancellation_token.clone(),
+            self.tick_rate,
+            self.frame_rate,
+        );
+        self.task = tokio::spawn(async {
+            event_loop.await;
+        });
+    }
+
+    async fn event_loop(
+        event_tx: UnboundedSender<Event>,
+        cancellation_token: CancellationToken,
+        tick_rate: f64,
+        frame_rate: f64,
+    ) {
+        let mut event_stream = EventStream::new();
+        let mut tick_interval = interval(Duration::from_secs_f64(1.0 / tick_rate));
+        let mut render_interval = interval(Duration::from_secs_f64(1.0 / frame_rate));
+
+        // if this fails, then it's likely a bug in the calling code
+        event_tx
+            .send(Event::Init)
+            .expect("failed to send init event");
+        loop {
+            let event = tokio::select! {
+                _ = cancellation_token.cancelled() => {
+                    break;
+                }
+                _ = tick_interval.tick() => Event::Tick,
+                _ = render_interval.tick() => Event::Render,
+                crossterm_event = event_stream.next().fuse() => match crossterm_event {
+                    Some(Ok(event)) => match event {
+                        CrosstermEvent::Key(key) if key.kind == KeyEventKind::Press => Event::Key(key),
+                        CrosstermEvent::Mouse(mouse) => Event::Mouse(mouse),
+                        CrosstermEvent::Resize(x, y) => Event::Resize(x, y),
+                        CrosstermEvent::FocusLost => Event::FocusLost,
+                        CrosstermEvent::FocusGained => Event::FocusGained,
+                        CrosstermEvent::Paste(s) => Event::Paste(s),
+                        _ => continue, // ignore other events
+                    }
+                    Some(Err(_)) => Event::Error,
+                    None => break, // the event stream has stopped and will not produce any more events
+                },
+            };
+            if event_tx.send(event).is_err() {
+                // the receiver has been dropped, so there's no point in continuing the loop
+                break;
+            }
+        }
+        cancellation_token.cancel();
+    }
+
+    pub fn stop(&self) -> Result<()> {
+        self.cancel();
+        let mut counter = 0;
+        while !self.task.is_finished() {
+            std::thread::sleep(Duration::from_millis(1));
+            counter += 1;
+            if counter > 50 {
+                self.task.abort();
+            }
+            if counter > 100 {
+                error!("Failed to abort task in 100 milliseconds for unknown reason");
+                break;
+            }
+        }
+        Ok(())
+    }
+
+    pub fn enter(&mut self) -> Result<()> {
+        crossterm::terminal::enable_raw_mode()?;
+        crossterm::execute!(stdout(), EnterAlternateScreen, cursor::Hide)?;
+        if self.mouse {
+            crossterm::execute!(stdout(), EnableMouseCapture)?;
+        }
+        if self.paste {
+            crossterm::execute!(stdout(), EnableBracketedPaste)?;
+        }
+        self.start();
+        Ok(())
+    }
+
+    pub fn exit(&mut self) -> Result<()> {
+        self.stop()?;
+        if crossterm::terminal::is_raw_mode_enabled()? {
+            self.flush()?;
+            if self.paste {
+                crossterm::execute!(stdout(), DisableBracketedPaste)?;
+            }
+            if self.mouse {
+                crossterm::execute!(stdout(), DisableMouseCapture)?;
+            }
+            crossterm::execute!(stdout(), LeaveAlternateScreen, cursor::Show)?;
+            crossterm::terminal::disable_raw_mode()?;
+        }
+        Ok(())
+    }
+
+    pub fn cancel(&self) {
+        self.cancellation_token.cancel();
+    }
+
+    pub fn suspend(&mut self) -> Result<()> {
+        self.exit()?;
+        #[cfg(not(windows))]
+        signal_hook::low_level::raise(signal_hook::consts::signal::SIGTSTP)?;
+        Ok(())
+    }
+
+    pub fn resume(&mut self) -> Result<()> {
+        self.enter()?;
+        Ok(())
+    }
+
+    pub async fn next_event(&mut self) -> Option<Event> {
+        self.event_rx.recv().await
+    }
+}
+
+impl Deref for Tui {
+    type Target = ratatui::Terminal<Backend<Stdout>>;
+
+    fn deref(&self) -> &Self::Target {
+        &self.terminal
+    }
+}
+
+impl DerefMut for Tui {
+    fn deref_mut(&mut self) -> &mut Self::Target {
+        &mut self.terminal
+    }
+}
+
+impl Drop for Tui {
+    fn drop(&mut self) {
+        self.exit().unwrap();
+    }
+}