ratatui_toolkit/widgets/markdown_widget/
mod.rs

1//! Markdown rendering widget for ratatui applications.
2//!
3//! Provides a feature-rich markdown viewer with optional extensions:
4//! - Table of contents (TOC)
5//! - Syntax highlighting
6//! - Text selection
7//! - Click-to-highlight line selection
8//!
9//! # Mouse Capture Requirement
10//!
11//! For mouse interactions (click, drag, hover) to work, you must enable
12//! mouse capture with crossterm:
13//!
14//! ```rust,ignore
15//! use crossterm::event::{EnableMouseCapture, DisableMouseCapture};
16//!
17//! // On startup:
18//! execute!(stdout, EnterAlternateScreen, EnableMouseCapture)?;
19//!
20//! // On cleanup:
21//! execute!(stdout, LeaveAlternateScreen, DisableMouseCapture)?;
22//! ```
23//!
24//! Without `EnableMouseCapture`, scroll wheel may still work (terminal-dependent),
25//! but click events will not be received.
26//!
27//! # Example (Recommended - Unified State)
28//!
29//! ```rust,ignore
30//! use ratatui_toolkit::{MarkdownWidget, MarkdownState};
31//!
32//! // Create unified state
33//! let mut state = MarkdownState::default();
34//! state.source.set_content("# Hello World\n\nWelcome!");
35//!
36//! // Create widget from state
37//! let content = state.content().to_string();
38//! let widget = MarkdownWidget::from_state(&content, &mut state)
39//!     .show_toc(true)
40//!     .show_statusline(true)
41//!     .show_scrollbar(true);
42//! ```
43//!
44//! # Example (Individual State Modules)
45//!
46//! ```rust,ignore
47//! use ratatui_toolkit::markdown_widget::{MarkdownWidget, state::*};
48//!
49//! // Create state modules
50//! let mut scroll = ScrollState::default();
51//! let mut source = SourceState::default();
52//! let mut cache = CacheState::default();
53//! let display = DisplaySettings::default();
54//! let mut collapse = CollapseState::default();
55//! let mut expandable = ExpandableState::default();
56//! let mut git_stats = GitStatsState::default();
57//! let mut vim = VimState::default();
58//! let mut selection = SelectionState::default();
59//! let mut double_click = DoubleClickState::default();
60//!
61//! // Create widget with individual state modules
62//! let widget = MarkdownWidget::new(
63//!     content,
64//!     &mut scroll,
65//!     &mut source,
66//!     &mut cache,
67//!     &display,
68//!     &mut collapse,
69//!     &mut expandable,
70//!     &mut git_stats,
71//!     &mut vim,
72//!     &mut selection,
73//!     &mut double_click,
74//! )
75//! .show_toc(true)
76//! .show_statusline(true)
77//! .show_scrollbar(true);
78//! ```
79
80// Core modules
81pub mod extensions;
82pub mod foundation;
83pub mod state;
84pub mod widget;
85
86// Internal re-exports for cross-module use
87mod internal;
88
89// ============================================================================
90// Foundation (always available)
91// ============================================================================
92
93// Elements
94pub use foundation::elements::{
95    // Enums
96    CheckboxState,
97    CodeBlockBorderKind,
98    // Constants
99    CodeBlockColors,
100    CodeBlockTheme,
101    ColumnAlignment,
102    ElementKind,
103    // Struct
104    MarkdownElement,
105    TableBorderKind,
106    TextSegment,
107    BLOCKQUOTE_MARKER,
108    BULLET_MARKERS,
109    CHECKBOX_CHECKED,
110    CHECKBOX_TODO,
111    CHECKBOX_UNCHECKED,
112    HEADING_ICONS,
113    HORIZONTAL_RULE_CHAR,
114};
115
116// Element methods
117pub use foundation::elements::methods::{
118    render as render_element, render_with_options as render_element_with_options, RenderOptions,
119};
120
121// Parser
122pub use foundation::parser::render_markdown_to_elements;
123
124// Source
125pub use foundation::source::MarkdownSource;
126
127// Events
128pub use foundation::events::{MarkdownDoubleClickEvent, MarkdownEvent};
129
130// Types
131pub use foundation::types::{GitStats, SelectionPos};
132
133// Functions
134pub use foundation::functions::{render_markdown, render_markdown_with_style};
135
136// ============================================================================
137// Widget
138// ============================================================================
139
140pub use widget::enums::MarkdownWidgetMode;
141pub use widget::MarkdownWidget;
142
143// ============================================================================
144// State (always required)
145// ============================================================================
146
147pub use state::{
148    CacheState, CollapseState, DisplaySettings, DoubleClickState, ExpandableEntry, ExpandableState,
149    GitStatsState, MarkdownState, ParsedCache, RenderCache, ScrollState, SelectionState,
150    SourceState, TocEntry, TocState, VimState,
151};
152
153// ============================================================================
154// Extensions (toggleable)
155// ============================================================================
156
157// TOC
158pub use extensions::toc::{Toc, TocConfig};
159
160// Theme
161pub use extensions::theme::{
162    // Functions
163    get_effective_theme_variant,
164    load_theme_from_json,
165    // Palettes
166    palettes,
167    // Structs
168    ColorMapping,
169    ColorPalette,
170    MarkdownStyle,
171    MarkdownTheme,
172    SyntaxHighlighter,
173    // Enums
174    SyntaxThemeVariant,
175    ThemeVariant,
176};
177
178// Selection handlers
179pub use extensions::selection::{
180    handlers::{handle_mouse_event, handle_mouse_event_with_double_click},
181    helpers::{handle_click, should_render_line},
182};
ratatui_toolkit/widgets/markdown_widget/mod.rs

ratatui_toolkit/widgets/markdown_widget/
mod.rs
