ratatui-toolkit 0.2.6

//! A scrollable, interactive markdown widget.

mod constructors;
pub mod enums;
mod helpers;
mod methods;
mod traits;

pub use enums::MarkdownWidgetMode;
pub use methods::WidgetStateSync;

use crate::primitives::pane::Pane;
use crate::services::theme::AppTheme;
use crate::widgets::markdown_widget::extensions::scrollbar::ScrollbarConfig;
use crate::widgets::markdown_widget::extensions::toc::TocConfig;
use crate::widgets::markdown_widget::foundation::types::GitStats;
use crate::widgets::markdown_widget::state::{
    CacheState, CollapseState, DisplaySettings, DoubleClickState, ExpandableState, GitStatsState,
    ScrollState, SelectionState, SourceState, TocState, VimState,
};

/// A scrollable, interactive markdown widget.
///
/// This widget renders markdown content with:
/// - Scroll support (keyboard and mouse)
/// - Click-to-highlight line selection
/// - Clickable headings to collapse/expand sections
/// - Clickable frontmatter to collapse/expand
/// - Expandable content blocks ("Show more"/"Show less")
/// - Text selection and copy support (drag to select)
/// - Double-click detection
/// - Statusline showing mode and scroll position
///
/// The widget handles ALL event processing internally and returns `MarkdownEvent`
/// variants so the parent application can react appropriately.
///
/// # Mouse Capture Requirement
///
/// For click events to work (line highlighting, TOC navigation, text selection),
/// you must enable mouse capture in your terminal setup:
///
/// ```rust,ignore
/// use crossterm::{
///     event::{EnableMouseCapture, DisableMouseCapture},
///     execute,
///     terminal::{EnterAlternateScreen, LeaveAlternateScreen},
/// };
///
/// // On startup:
/// execute!(stdout, EnterAlternateScreen, EnableMouseCapture)?;
///
/// // On cleanup:
/// execute!(stdout, LeaveAlternateScreen, DisableMouseCapture)?;
/// ```
///
/// Without `EnableMouseCapture`, scroll wheel events may still work (terminal-dependent),
/// but click events will not be received by the application.
pub struct MarkdownWidget<'a> {
    /// The markdown content to render.
    pub(crate) content: String,
    /// Scroll state (position, viewport, current line).
    pub(crate) scroll: ScrollState,
    /// Content source state.
    pub(crate) source: SourceState,
    /// Render cache state.
    pub(crate) cache: CacheState,
    /// Display settings (line numbers, themes).
    pub(crate) display: DisplaySettings,
    /// Section collapse state.
    pub(crate) collapse: CollapseState,
    /// Expandable content state.
    pub(crate) expandable: ExpandableState,
    /// Git stats state.
    pub(crate) git_stats_state: GitStatsState,
    /// Vim keybinding state.
    pub(crate) vim: VimState,
    /// Selection state for text selection/copy.
    pub(crate) selection: SelectionState,
    /// Double-click state for double-click detection.
    pub(crate) double_click: DoubleClickState,
    /// Optional TOC state for table of contents.
    pub(crate) toc_state: Option<TocState>,
    /// When true, use stale cache for smoother resize during drag operations.
    pub(crate) is_resizing: bool,
    /// Current mode for the statusline.
    pub(crate) mode: MarkdownWidgetMode,
    /// Whether to show the statusline.
    pub(crate) show_statusline: bool,
    /// Whether to show the scrollbar.
    pub(crate) show_scrollbar: bool,
    /// Configuration for the scrollbar.
    pub(crate) scrollbar_config: ScrollbarConfig,
    /// Whether selection mode is active (affects statusline mode display).
    pub(crate) selection_active: bool,
    /// Git statistics for the file (optional, from git_stats_state).
    pub(crate) git_stats: Option<GitStats>,
    /// Whether to show the TOC.
    pub(crate) show_toc: bool,
    /// Configuration for the TOC.
    pub(crate) toc_config: TocConfig,
    /// Whether the TOC is currently hovered (expands to show text).
    pub(crate) toc_hovered: bool,
    /// Index of the hovered TOC entry.
    pub(crate) toc_hovered_entry: Option<usize>,
    /// Scroll offset for the TOC list.
    pub(crate) toc_scroll_offset: usize,
    /// Cached rendered lines for selection text extraction.
    pub(crate) rendered_lines: Vec<ratatui::text::Line<'static>>,
    /// Optional application theme for styling.
    pub(crate) app_theme: Option<AppTheme>,
    /// Last double-click info (line number, kind, content) for app to retrieve.
    pub(crate) last_double_click: Option<(usize, String, String)>,
    /// Current filter text (when in filter mode).
    pub(crate) filter: Option<String>,
    /// Whether filter mode is currently active.
    pub(crate) filter_mode: bool,
    /// Whether to render a border around the widget.
    pub(crate) bordered: bool,
    /// Whether to wrap the widget in a Pane.
    pub(crate) has_pane: bool,
    /// Optional Pane configuration for wrapping the widget.
    pub(crate) pane: Option<Pane<'a>>,
    /// Title to use for the default Pane (e.g., filename).
    pub(crate) pane_title: Option<String>,
    /// Color for the Pane border.
    pub(crate) pane_color: Option<ratatui::style::Color>,
    /// Inner area calculated during render (for mouse event handling).
    pub inner_area: Option<ratatui::layout::Rect>,
}