ui.rs

//! # User Interface Module
//!
//! The UI module provides the complete terminal user interface (TUI) for the diff viewer.
//! It handles rendering, event handling, and application state management for an interactive
//! diff viewing experience.
//!
//! ## Overview
//!
//! The UI module is built on top of the [`ratatui`](https://docs.rs/ratatui/) library for
//! terminal rendering and [`crossterm`](https://docs.rs/crossterm/) for event handling.
//! It provides a responsive, vim-like interface for navigating and viewing diffs.
//!
//! ## Components
//!
//! The module is organized into several submodules:
//!
//! - **[`app`]**: Application state management, scroll control, and hunk navigation
//! - **[`events`]**: Keyboard event handling and input processing
//! - **[`renderers`]**: Terminal rendering logic for all UI elements
//!
//! ## Architecture
//!
//! ```text
//! User Input (Keyboard)
//!        ↓
//!   [events] Module ← Handles key presses, modifiers
//!        ↓
//!   [app] Module   ← Updates scroll position, navigation state
//!        ↓
//!   [renderers]    ← Renders the updated state
//!        ↓
//!   Terminal Output (Display)
//! ```
//!
//! ## Key Features
//!
//! ### Navigation
//! - Line-by-line scrolling (vim-style `j`/`k` or arrow keys)
//! - Half-page scrolling (Ctrl+D/U)
//! - Full-page scrolling (Ctrl+F/B or Page Up/Down)
//! - Jump to next/previous hunk (n/p keys)
//!
//! ### Display
//! - Syntax-highlighted code using the Syntect library
//! - Color-coded diff lines (red for deletions, green for additions)
//! - Header showing compared file names
//! - Footer showing available keybindings
//! - Line number tracking for both old and new files
//!
//! ### Rendering
//! - Three-panel layout: header, content, footer
//! - Scrollable content area with viewport management
//! - Syntax highlighting with theme support
//! - Proper hunk position tracking for navigation
//!
//! ## Usage Example
//!
//! ```ignore
//! use rustydiff::ui;
//! use rustydiff::diff::parser;
//! use rustydiff::ui::app::App;
//! use ratatui::Terminal;
//! use crossterm::terminal::EnterAlternateScreen;
//!
//! // Parse the diff output
//! let diff_result = parser::parse_unified_diff(diff_output)?;
//!
//! // Create the app with the parsed diff
//! let mut app = App::new(diff_result);
//!
//! // Initialize terminal
//! let mut terminal = Terminal::new(CrosstermBackend::new(std::io::stdout()))?;
//! terminal.enable_raw_mode()?;
//!
//! // Main event loop
//! while !app.should_quit {
//!     // Render the UI
//!     terminal.draw(|frame| {
//!         renderers::render(frame, &mut app).ok();
//!     })?;
//!
//!     // Handle user input
//!     events::handle_events(&mut app)?;
//! }
//! ```
//!
//! ## Application State
//!
//! The [`app::App`] struct maintains:
//! - The parsed diff result
//! - Current scroll position
//! - Viewport dimensions
//! - Hunk navigation positions
//! - Syntax highlighting definitions and theme
//! - Quit flag for application lifecycle
//!
//! ## Event Handling
//!
//! The [`events`] module provides non-blocking event polling with a 100ms timeout.
//! It translates keyboard events into app state changes through the [`app::App`] methods.
//!
//! ## Rendering Strategy
//!
//! The [`renderers`] module implements:
//! - Layout management using Ratatui's constraint system
//! - Dynamic syntax highlighting based on file extension
//! - Viewport-aware rendering of diff content
//! - Hunk position tracking for accurate navigation
//!
//! ## Keyboard Controls
//!
//! | Key | Action |
//! |-----|--------|
//! | `q` / `Esc` | Quit the application |
//! | `j` / `↓` | Scroll down one line |
//! | `k` / `↑` | Scroll up one line |
//! | `Ctrl+D` | Scroll down half page |
//! | `Ctrl+U` | Scroll up half page |
//! | `Ctrl+F` / `PageDown` | Scroll down full page |
//! | `Ctrl+B` / `PageUp` | Scroll up full page |
//! | `n` | Jump to next hunk |
//! | `p` | Jump to previous hunk |
//! | `Ctrl+C` | Quit (alternative) |
//!
//! ## Color Scheme
//!
//! - **Blue**: Header section (file names)
//! - **Red**: Deleted lines (with dark red background)
//! - **Green**: Added lines (with dark green background)
//! - **White**: Context lines
//! - **Cyan**: Hunk headers
//! - **Yellow**: Footer keybindings
//! - **Dark Gray**: Line numbers
//! - **Theme-dependent**: Syntax highlighting colors

pub mod app;
pub mod events;
pub mod renderers;
pub(super) mod utils;

pub use self::app::App;