Struct Toc 

pub struct Toc<'a> { /* private fields */ }

Table of Contents widget for markdown navigation.

Shows document headings in either compact (lines) or expanded (text) mode. Supports hover interactions and click-to-scroll navigation.

This is a UI-only widget that receives &TocState for state access. State mutations happen through TocState methods, not here.

Example

use ratatui_toolkit::markdown_widget::extensions::toc::{Toc, TocConfig};
use ratatui_toolkit::markdown_widget::state::toc_state::TocState;

let mut toc_state = TocState::new();
let toc = Toc::new(&toc_state)
    .config(TocConfig::default())
    .expanded(true);

Implementations

impl<'a> Toc<'a>

pub fn hovered(self, _index: Option<usize>) -> Self

Set the hovered item index.

Arguments

• index - The index of the hovered heading, or None.

Returns

Self for method chaining.

impl<'a> Toc<'a>

pub fn new(toc_state: &'a TocState) -> Self

Create a new TOC widget from TocState.

The Toc widget is a UI-only component that receives state via reference. State mutations happen through TocState methods, not the Toc widget.

Arguments

• toc_state - Reference to the TocState containing entries, scroll, and hover state.

Returns

A new Toc instance ready for rendering.

Example

use ratatui_toolkit::markdown_widget::extensions::toc::Toc;
use ratatui_toolkit::markdown_widget::state::toc_state::TocState;

let toc_state = TocState::new();
let toc = Toc::new(&toc_state);

pub fn expanded(self, expanded: bool) -> Self

Set whether the TOC is expanded.

Arguments

• expanded - True for expanded mode (full text), false for compact mode (lines).

Returns

Self for method chaining.

pub fn config(self, config: TocConfig) -> Self

Set the TOC configuration.

Arguments

• config - The TOC configuration.

Returns

Self for method chaining.

impl<'a> Toc<'a>

pub fn viewport( self, _scroll_offset: usize, _viewport_height: usize, _total_lines: usize, ) -> Self

Set the current viewport information.

Arguments

• scroll_offset - Current scroll offset.
• viewport_height - Height of the visible viewport.
• total_lines - Total number of lines in the document.

Returns

Self for method chaining.

pub fn toc_scroll(self, _offset: usize) -> Self

Set the TOC scroll offset (for scrolling within the TOC list).

Arguments

• offset - The scroll offset for the TOC list.

Returns

Self for method chaining.

impl<'a> Toc<'a>

pub fn count_headings(content: &str) -> usize

Count the number of headings in markdown content.

This is a static method useful for calculating dynamic TOC height without constructing a full Toc widget.

Arguments

• content - The markdown content to scan.

Returns

The number of headings found.

impl<'a> Toc<'a>

pub fn entry_count(&self) -> usize

Get the number of entries in the TOC.

Delegates to the underlying TocState.

pub fn entries(&self) -> &[TocEntry]

Get all entries.

Delegates to the underlying TocState.

pub fn click_to_line(&self, entry_index: usize) -> Option<usize>

Get the target line number for a clicked entry.

Arguments

• entry_index - The index of the clicked entry.

Returns

The line number to scroll to, or None if the index is invalid.

pub fn get_entry(&self, index: usize) -> Option<&TocEntry>

Get the entry at a given index.

Arguments

• index - The entry index.

Returns

The entry, or None if the index is invalid.

impl<'a> Toc<'a>

pub fn entry_at_position(&self, x: u16, y: u16, area: Rect) -> Option<usize>

Find the entry index at a given screen position.

Arguments

• x - Screen X coordinate.
• y - Screen Y coordinate.
• area - The area the TOC is rendered in.

Returns

The entry index at that position, or None if no entry is there.

impl<'a> Toc<'a>

pub fn required_compact_height( content: &str, line_spacing: u8, show_border: bool, ) -> u16

Calculate the required height for compact mode.

With Braille markers, we have 4 vertical dots per cell. Height = ceil(entries * spacing / 4) + border_height.

Arguments

• content - The markdown content to scan.
• line_spacing - Spacing between lines in dot units.
• show_border - Whether the border is shown.

Returns

The required height in rows.

impl<'a> Toc<'a>

pub fn required_expanded_width(content: &str, show_border: bool) -> u16

Calculate the required width to display all headings without truncation.

Takes into account:

• Indentation based on heading level (2 chars per level)
• Actual text width using Unicode width
• Padding (left and right)
• Border if enabled

Arguments

• content - The markdown content to scan.
• show_border - Whether the border is shown.

Returns

The required width in columns.

impl<'a> Toc<'a>

pub fn required_height(content: &str, show_border: bool) -> u16

Calculate the required height for expanded mode.

Accounts for border (2 rows) and one row per entry.

Arguments

• content - The markdown content to scan.
• show_border - Whether the border is shown.

Returns

The required height in rows.

Trait Implementations

impl<'a> Debug for Toc<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'a> Widget for Toc<'a>

fn render(self, area: Rect, buf: &mut Buffer)

Draws the current state of the widget in the given buffer. That is the only method required to implement a custom widget.