tui-lipan

https://docs.tui-lipan.dev
Admin
Opinionated, component-based TUI framework for Rust - declarative components, reconciliation, layout...
Tokens:129,247
Snippets:1,400
Trust Score:7.5
Update:2 months ago
Show doc for...
Tokens:
Raw
### Run QR-Code Example

Source: https://docs.tui-lipan.dev/examples

Executes the QR code rendering example.

```bash
cargo run --example qr_code --features qr-code
```

--------------------------------

### Run Image Examples

Source: https://docs.tui-lipan.dev/examples

Executes examples for image widgets and chat UI integration.

```bash
cargo run --example image --features image
cargo run --example image_modes --features image
cargo run --example messenger --features image
```

--------------------------------

### Run Diff-View Examples

Source: https://docs.tui-lipan.dev/examples

Executes examples for diff comparison and hunk navigation.

```bash
cargo run --example diff_hub --features diff-view
cargo run --example diff_hunk_navigation --features diff-view
```

--------------------------------

### Run Theme Reload Example

Source: https://docs.tui-lipan.dev/examples

Executes the live theme hot-reloading example.

```bash
cargo run --example theme_hot_reload --features theme-reload
```

--------------------------------

### Run standard examples

Source: https://docs.tui-lipan.dev/examples

Execute a specific example from the examples/ directory using cargo.

```bash
cargo run --example <name>
```

--------------------------------

### Run DevTools Example

Source: https://docs.tui-lipan.dev/examples

Executes the minimal app example for testing DevTools logs.

```bash
cargo run --example devtools --features devtools
```

--------------------------------

### Run Markdown Examples

Source: https://docs.tui-lipan.dev/examples

Executes examples for markdown rendering and Mermaid diagrams.

```bash
cargo run --example markdown_hub --features markdown
cargo run --example document_view_mermaid --features markdown
```

--------------------------------

### Build web examples

Source: https://docs.tui-lipan.dev/web-backend

Use make commands from the repository root to build specific web-based examples.

```bash
make -C examples/web hello
make -C examples/web search-palette
```

--------------------------------

### Run Syntax Highlighting Examples

Source: https://docs.tui-lipan.dev/examples

Executes examples for syntax themes and file browser functionality.

```bash
cargo run --example syntax_theme_compare --features syntax-syntect
cargo run --example yazi --features syntax-extra
```

--------------------------------

### Run Markdown Editor Example

Source: https://docs.tui-lipan.dev/examples

Executes the live markdown editor example with preview sync.

```bash
cargo run --example markdown_editor_sync --features markdown,syntax-syntect
```

--------------------------------

### Run Terminal Examples

Source: https://docs.tui-lipan.dev/examples

Executes examples for terminal devtools, search, copy-mode, and hints.

```bash
cargo run --example terminal_filetree_devtools --features terminal
cargo run --example terminal_search_highlight --features terminal
cargo run --example terminal_copy_mode --features terminal
cargo run --example terminal_hints --features terminal
```

--------------------------------

### Run feature-gated examples

Source: https://docs.tui-lipan.dev/examples

Execute examples that require specific feature flags to be enabled.

```bash
cargo run --example image --features image
cargo run --example markdown_editor_sync --features markdown,syntax-syntect
```

--------------------------------

### Run Big-Text Examples

Source: https://docs.tui-lipan.dev/examples

Executes examples related to FIGlet fonts and text effects.

```bash
cargo run --example big_text --features big-text
cargo run --example figlet_editor --features big-text
cargo run --example burst_effects --features big-text
```

--------------------------------

### Full Component Configuration

Source: https://docs.tui-lipan.dev/widgets/tabs

A comprehensive example demonstrating various properties and event callbacks for the DraggableTabBar.

```rust
rsx! {
    DraggableTabBar {
        tabs: vec![
            DraggableTab::new("main.rs").closeable(true).path("src/main.rs"),
            DraggableTab::new("lib.rs").closeable(true).path("src/lib.rs"),
            DraggableTab::new("README.md").path("README.md"),
        ],
        bar_id: "editor",
        drag_group: "editors",
        active: self.active_tab,
        variant: DraggableTabBarVariant::FrameLine,
        tab_max_width: Some(20),
        overflow: DraggableTabBarOverflow::ShrinkThenScroll { min_tab_width: 8 },
        show_file_icons: true,
        file_icon_style: FileIconStyle::NerdFontColored,
        show_close_buttons: true,
        show_overflow_controls: true,
        active_style: Style::new().fg(Color::Cyan).bold(),
        on_change: ctx.link().callback(|e| Msg::SetActive(e.index)),
        on_close: ctx.link().callback(Msg::CloseTab),
        on_reorder: ctx.link().callback(Msg::ReorderTabs),
    }
}
```

--------------------------------

### Configuring a List Widget

Source: https://docs.tui-lipan.dev/widgets/data

Example of initializing a List widget with selection symbols, styles, and event callbacks.

```rust
List::new()
    .items(self.files.iter().map(|f| ListItem::new(f.name.clone())))
    .selected(self.selected)
    .scrollbar(true)
    .selection_symbol(Some("> ".to_string()))
    .selection_style(Style::new().fg(Color::Cyan).bold())
    .on_select(ctx.link().callback(|e| Msg::FileSelected(e.index)))
    .on_activate(ctx.link().callback(|e| Msg::FileOpened(e.index)))
```

--------------------------------

### Run Terminal Images Example

Source: https://docs.tui-lipan.dev/examples

Executes the example for Kitty graphics escapes in terminal panes.

```bash
cargo run --example terminal_images --features terminal-images
```

--------------------------------

### Define keymap.conf actions

Source: https://docs.tui-lipan.dev/keybindings

Example format for mapping actions to specific key combinations in the keymap.conf file.

```text
# Comments with #
copy = ctrl-c, super-c, ctrl-insert
paste = super-v, ctrl-shift-v
paste_selection = shift-insert
cut = ctrl-x, super-x, shift-delete
undo = ctrl-z, super-z
redo = ctrl-shift-z, ctrl-y
clear = ctrl-u
select_all = ctrl-a, super-a
move_left = left
select_word_right = shift-ctrl-right
delete_word_left = ctrl-backspace
insert_newline = enter
dismiss_overlay = esc
focus_next = tab
focus_prev = shift-tab
quit = ctrl-q
toggle_devtools = f12
```

--------------------------------

### Import the tui-lipan prelude

Source: https://docs.tui-lipan.dev/quick-start

Use the prelude to access common component types, styling primitives, and widgets. This is the recommended starting point for most applications.

```rust
// Recommended: start here for typical app-author code
use tui_lipan::prelude::*;
```

--------------------------------

### Build and Run Commands

Source: https://docs.tui-lipan.dev/web-backend

Commands to install dependencies, compile the Rust code to WebAssembly, and serve the application.

```bash
npm install           # installs @xterm/xterm and @xterm/addon-fit
wasm-pack build --target web
python3 serve.py      # serves with correct .mjs / .wasm MIME types
```

--------------------------------

### Neovim Conform Configuration

Source: https://docs.tui-lipan.dev/macros

Conform.nvim setup to integrate macro formatters into the Neovim formatting pipeline.

```lua
require("conform").setup({
  formatters = {
    ui_fmt = {
      command = "cargo",
      args = { "ui-fmt", "--stdin" },
      stdin = true,
    },
    rsx_fmt = {
      command = "cargo",
      args = { "rsx-fmt", "--stdin" },
      stdin = true,
    },
  },
  formatters_by_ft = {
    rust = { "ui_fmt", "rsx_fmt", "rustfmt" },
  },
})
```

--------------------------------

### Initialize ManagedTerminal

Source: https://docs.tui-lipan.dev/widgets/terminal

Examples for creating a ManagedTerminal with default settings or custom shell and environment configurations.

```rust
use tui_lipan::prelude::*; 

// Simple usage - starts shell in current directory
ManagedTerminal::new()
    .on_status(ctx.link().callback(Msg::TerminalStatus))

// Custom shell and working directory
ManagedTerminal::new()
    .config(
        TerminalPtyConfig::new("/bin/bash")
            .cwd("/home/user/projects")
            .env("MY_VAR", "value")
    )
    .scrollback(5000)
    .initial_size(120, 40)
    .resize_debounce(std::time::Duration::from_millis(16))
    .on_status(ctx.link().callback(Msg::TerminalStatus))
```

--------------------------------

### Initialize and Configure ContextMenu

Source: https://docs.tui-lipan.dev/widgets/overlays

Demonstrates creating a ContextMenu instance with a trigger button, menu items, state management, and custom selection styling.

```rust
ContextMenu::new(
    Button::new("Options").on_click(ctx.link().callback(|_| Msg::ToggleMenu))
)
    .items(vec!["Cut", "Copy", "Paste", "Delete"])
    .open(ctx.state.menu_open)
    .on_select(ctx.link().callback(Msg::MenuAction))
    .on_close(ctx.link().callback(|_| Msg::CloseMenu))
    .selection_style(Style::new().bg(Color::DarkGray))
```

--------------------------------

### Apply Alpha-Channel Styles

Source: https://docs.tui-lipan.dev/styling

Examples of using Paint for alpha-channel support and applying styles with transparency.

```rust
Paint::solid(Color::Blue)
Paint::rgb(30, 40, 50)
Paint::rgba(30, 40, 50, 192)
Paint::hex("#1E2832CC")

Style::new().bg(Paint::hex("#101015CC"))
Style::new().fg_alpha(Color::White, 0.75)
Style::new().bg_alpha(Color::rgb(16, 16, 21), 0.8)
```

--------------------------------

### Configure App Keybinding Policies

Source: https://docs.tui-lipan.dev/keybindings

Demonstrates how to customize framework keymaps, quit behavior, and dispatch policies using the App builder pattern.

```rust
App::new()
    .framework_keymap(FrameworkKeymap::default().unbind(FrameworkAction::Quit))
    .global_quit(None) // sugar for unbinding quit
    .user_keymap_policy(UserKeymapPolicy::Disabled)
    .key_dispatch_policy(KeyDispatchPolicy::AppCommandsFirst)
    .terminal_key_policy(TerminalKeyPolicy::AppCommandsThenTerminal)
    .command_conflict_policy(CommandConflictPolicy::HighestPriority)
    .chord_mismatch_policy(ChordMismatchPolicy::ForwardPrefixAndCurrent)
```

--------------------------------

### Initialize FileTree with Provided Listings

Source: https://docs.tui-lipan.dev/widgets/data

Configures a FileTree using a provided list of directory entries and handles directory listing requests via a callback.

```rust
let listings = vec![FileTreeDirectoryListing::new(
    project_root.clone(),
    [
        FileTreeEntry::directory("src"),
        FileTreeEntry::file("README.md").git_status(GitFileStatus::new(
            None,
            Some(GitChangeState::Modified),
        )),
    ],
)];

FileTree::new(project_root)
    .entry_source(FileTreeEntrySource::Provided(listings))
    .on_entry_request(
        ctx.link()
            .callback(|request: FileTreeEntryRequest| Msg::ListDirectory(request.path)),
    )
```

--------------------------------

### Configure a Button

Source: https://docs.tui-lipan.dev/widgets/input

Demonstrates creating a button with custom styling, keyboard shortcuts, and a click callback.

```rust
Button::new("Save")
    .style(Style::new().fg(Color::White).bg(Color::Blue))
    .shortcut_bindings("ctrl+s, super+s".parse().unwrap())
    .focus_style(Style::new().fg(Color::White).bg(Color::DarkBlue).bold())
    .on_click(ctx.link().callback(|_| Msg::Save))
```

--------------------------------

### Configure TextArea on_edit callback

Source: https://docs.tui-lipan.dev/text-editing

Example of wiring the on_edit callback to handle TextEditEvent messages.

```rust
TextArea {
    editor: ctx.state.editor.clone(),
    on_edit: ctx.link().callback(|ev: TextEditEvent| Msg::OnEdit(ev)),
}
```

--------------------------------

### Handle Keyboard Input

Source: https://docs.tui-lipan.dev/events

Example of using a key handler to check for specific keys and modifiers.

```rust
ctx.link().key_handler(|key: KeyEvent| {
    if key.is(KeyCode::Enter) {
        Some(Msg::Submit)
    } else if key.is_with(KeyCode::Char('s'), KeyMods::CTRL) {
        Some(Msg::Save)
    } else {
        None
    }
})
```

--------------------------------

### Initialize a Style

Source: https://docs.tui-lipan.dev/styling

Create and configure a new Style instance with various visual properties.

```rust
Style::new()
    .fg(Color::Blue)
    .bg(Color::indexed(235))
    .bold()
    .italic()
    .underline()
    .dim()
    .reverse()
```

--------------------------------

### delete_to_start()

Source: https://docs.tui-lipan.dev/text-editing

Deletes text from the current cursor position to the start of the text or deletes the current selection.

```APIDOC
## delete_to_start()

### Description
Deletes from cursor to start of text or deletes the current selection.
```

--------------------------------

### Initialize Image Widget

Source: https://docs.tui-lipan.dev/widgets/display

Demonstrates creating an Image widget from a file path or raw bytes.

```rust
Image::new("logo.png")
    .fit(ImageFit::Contain)
    .alt("Company Logo")

// From memory
let bytes: Arc<[u8]> = load_image_bytes();
Image::from_bytes(bytes)
    .protocol(ImageProtocol::Auto)
```

--------------------------------

### Missing Widget Error

Source: https://docs.tui-lipan.dev/testing

Example of the error message displayed when a script references a non-existent widget key.

```text
Error: no widget with key `does-not-exist` is currently rendered
```

--------------------------------

### Initialize and configure a tui-lipan application

Source: https://docs.tui-lipan.dev/tutorial

Use this configuration block to set up the application's appearance and behavior before mounting and running it.

```rust
fn main() -> tui_lipan::Result<()> {
    tui_lipan::App::new()
        .title("My App")                        // Chrome frame title
        .theme(Theme::one_dark())               // Theme preset
        .mouse(true)                            // Mouse capture (default: true)
        .toast_placement(ToastPlacement::BottomEnd)
        .contrast_policy(ContrastPolicy::Wcag)  // WCAG-fix low-contrast text
        .mount(App)
        .run()
}
```

--------------------------------

### State Style Slot Configuration

Source: https://docs.tui-lipan.dev/styling

Examples of using Replace, Extend, and Inherit semantics for state-based style overlays.

```rust
// Replace: exact selected-row overlay, independent of theme.selection.
List::new().selection_style(Style::new().fg(Color::Black).bg(Color::Cyan))

// Extend: keep theme.selection and add bold text.
List::new().extend_selection_style(Style::new().bold())

// Inherit: selected rows follow the scoped ThemeProvider/App theme.
List::new().inherit_selection_style()
```

--------------------------------

### Filter-as-you-type Pattern

Source: https://docs.tui-lipan.dev/components

Example of using TaskPolicy::LatestOnly to handle rapid input updates by cancelling stale filter tasks.

```rust
use tui_lipan::TaskPolicy;

// Example: filter-as-you-type pattern
match msg {
    Msg::QueryChanged(q) => {
        let cmd = ctx.link().command_keyed("filter", TaskPolicy::LatestOnly, move |link| {
            let results = filter_items(&q);
            let _ = link.send_if_not_cancelled(Msg::FilterDone(results));
        });
        Update::command_only(cmd)
    }
}
```

--------------------------------

### Initialize and Configure a Heatmap

Source: https://docs.tui-lipan.dev/widgets/display

Demonstrates how to construct a Heatmap with custom labels, a color gradient, and specific cell rendering modes.

```rust
let data = vec![
    vec![10.0, 25.0, 40.0, 55.0],
    vec![20.0, 35.0, 50.0, 65.0],
    vec![30.0, 45.0, 60.0, 75.0],
];

Heatmap::new(data)
    .row_labels(["Low", "Med", "High"])
    .column_labels(["Q1", "Q2", "Q3", "Q4"])
    .gradient(ColorGradient::new(Color::Rgb(60, 179, 113), Color::Rgb(226, 82, 87)))
    .range(0.0, 100.0)
    .cell_mode(HeatmapCellMode::GlyphForeground(" ".into()))
    .gap_x(1)
    .gap_y(1)
    .legend_gap(1)
    .legend_spacing(1)
    .legend_width(HeatmapLegendWidth::Full)
    .show_legend(true)
    .border(true)
```

--------------------------------

### Configure Syntax Highlighting

Source: https://docs.tui-lipan.dev/widgets/input

Demonstrates various ways to apply syntax highlighting, including theme selection, auto-detection from file paths, and custom theme loading.

```rust
TextArea::new(code.clone())
    .with_syntax("rust", "base16-ocean.dark")

// With background colors
    .with_syntax_bg("rust", "one-dark")

// Auto-detect language from file path (extension/filename matching, no I/O)
TextArea::new(code.clone())
    .language_from_path("src/main.rs")   // resolves to "Rust"
    .with_syntax_strategy(SyntectStrategy::default(), "Rust", "base16-ocean.dark")

// Or use the free function to get the language string yourself
if let Some(lang) = tui_lipan::language_from_path(&file_path) {
    area = area.language(lang);
}

// Custom theme from file
    .with_syntax_custom_theme_from_file("rust", "MyTheme", "/path/to/theme.tmTheme")
```

--------------------------------

### Start TUI application with control channel

Source: https://docs.tui-lipan.dev/testing

Run the application with the TUI_LIPAN_CONTROL environment variable set to a Unix socket path.

```sh
TUI_LIPAN_CONTROL=/tmp/app.sock cargo run --example todo
```

--------------------------------

### Define Terminal Colors

Source: https://docs.tui-lipan.dev/styling

Examples of creating various terminal color types including named, indexed, RGB, and hex values.

```rust
Color::Red           // Named ANSI color
Color::indexed(235)  // 256-color palette (u8)
Color::rgb(30, 40, 50)  // True color
Color::hex("#1E2832")   // Opaque hex string; invalid input falls back to Color::Reset
Color::Backdrop         // Clear fg but preserve the background already underneath
Color::Transparent      // Skip painting fg/bg - show whatever is already in the buffer / parent
```

--------------------------------

### Load Async Data on Startup

Source: https://docs.tui-lipan.dev/tutorial

Uses the init method and commands to perform background tasks during component mounting.

```rust
fn init(&mut self, ctx: &mut Context<Self>) -> Option<Command> {
    Some(ctx.link().command(move |link| {
        // Runs on a background thread - safe to block here
        let items: Vec<String> = (1..=50)
            .map(|i| format!("Item {i}"))
            .collect();
        std::thread::sleep(std::time::Duration::from_millis(500));
        link.send(Msg::ItemsLoaded(items));
    }))
}
```

--------------------------------

### Initializing TextEditor

Source: https://docs.tui-lipan.dev/text-editing

Create a new multi-line text editor instance with initial content or default settings.

```rust
let mut editor = TextEditor::new("Hello\nWorld");
// Cursor starts at position 0 (beginning of text)

// Also available via Default
let editor = TextEditor::default(); // empty text, cursor at 0
```

--------------------------------

### Duplicate component state key warning

Source: https://docs.tui-lipan.dev/components

Example of the warning message logged in debug builds when duplicate sibling keys are detected.

```text
Duplicate component_state_key "modal" detected; last-writer-wins
```

--------------------------------

### Initialize DocumentView with Markdown

Source: https://docs.tui-lipan.dev/widgets/display

Create a DocumentView instance with markdown content, enabling line numbers and text wrapping.

```rust
DocumentView::new("# Hello\n\n| A | B |\n|---|---|\n| 1 | 2 |")
    .markdown()
    .line_numbers(true)
    .wrap(true)
```

--------------------------------

### ManagedTerminal

Source: https://docs.tui-lipan.dev/widgets/terminal

The ManagedTerminal widget provides a complete PTY terminal with automatic lifecycle management. It is the recommended starting point for terminal integration.

```APIDOC
## ManagedTerminal

### Description
A complete PTY terminal widget with automatic lifecycle management. No manual wiring is required for basic operation.

### Properties
- **config** (TerminalPtyConfig) - Shell, working directory, and environment configuration.
- **scrollback** (usize) - Scrollback buffer size in lines (default: 2000).
- **initial_cols** (u16) - Initial columns (default: 120).
- **initial_rows** (u16) - Initial rows (default: 24).
- **auto_start** (bool) - Start PTY on init (default: true).
- **placeholder** (Option<Arc<str>>) - Text shown before PTY is ready.
- **forward_mouse** (bool) - Forward mouse events to PTY (default: true).
- **scroll_wheel** (bool) - Mouse wheel for scrollback (default: true).
- **resize_debounce** (Duration) - Trailing-edge PTY/screen resize delay (default: 16ms).
- **style** (Style) - Terminal content style.
- **focusable** (bool) - Accept focus (default: true).
- **tab_stop** (bool) - Include in sequential Tab traversal (default: true).
- **on_focus** / **on_blur** (Callback<()>) - Focus gained / lost callbacks.
- **width** (Length) - Width (default: Flex(1)).
- **height** (Length) - Height (default: Flex(1)).
- **on_status** (Callback<ManagedTerminalStatus>) - Status change callback.
```

--------------------------------

### Basic ui! Macro Syntax

Source: https://docs.tui-lipan.dev/macros

Demonstrates the standard builder chain syntax using the ui! macro.

```rust
ui! {
    VStack::new().gap(1).padding(1) => {
        Text::new("Hello World"),
        Button::new("Click Me")
            .style(Style::new().fg(Color::Blue))
            .on_click(ctx.link().callback(|_| Msg::Clicked)),
    }
}
```

--------------------------------

### Implement live markdown preview

Source: https://docs.tui-lipan.dev/patterns

Uses TextArea and DocumentView to synchronize markdown editing and rendering.

```rust
HStack::new()
    .gap(1)
    .child(
        TextArea::new(ctx.state.markdown.clone())
            .language("markdown")
            .on_change(ctx.link().callback(|ev| Msg::SetMarkdown(ev.value))),
    )
    .child(
        DocumentView::new(ctx.state.markdown.clone())
            .markdown()          // requires feature "markdown"
            .line_numbers(true)
            .wrap(true),
    )
```

--------------------------------

### Define ListItem Types

Source: https://docs.tui-lipan.dev/widgets/data

Examples of creating different types of list items, including headers, spacers, active rows, and items with prefixes or gutters.

```rust
ListItem::new("Normal item")          // Selectable row
ListItem::header("Section Title")      // Non-selectable header row
ListItem::spacer()                     // Non-selectable blank row
ListItem::new("Service").active(true)  // Marks row as active
ListItem::role(ListItemRole::Header)   // Explicit role

// Multi-line rows
ListItem::new("build")
    .line(ListItemLine::new("target/debug/build.log").selection_left(false))

// Prefix helpers
ListItem::new("Item").numbered(1)
ListItem::new("Bullet").bulleted('•')
ListItem::new("Label")
    .prefix("> ")
    .prefix_style(Style::new().fg(Color::Cyan))

// Left gutter helpers. Spinner gutters animate with the app's spinner ticker.
// Set List::gutter_gap(1) when the framework should provide label spacing.
// Use `.leading(1)` so a lone spinner lines up with text markers like `" ●"`.
ListItem::new("Building").gutter(ListItemGutter::spinner(Spinner::new()).leading(1))
ListItem::new("Changed").gutter(ListItemGutter::text("~ "))

// Status helpers render inside the existing selection/unselected symbol column.
ListItem::new("Working").status_spinner(Spinner::new())
ListItem::new("Dirty").status_symbol(" ~ ")
```

--------------------------------

### Apply VisualEffect to an EffectScope

Source: https://docs.tui-lipan.dev/styling

Use VisualEffect to mutate rendered cells within an EffectScope. This example applies palette quantization and scanline effects to content.

```rust
EffectScope::new()
    .effect(VisualEffect::PaletteQuantize {
        palette: EffectPalette::Gameboy,
    })
    .effect(VisualEffect::Scanlines {
        strength: 0.18,
        spacing: 2,
    })
    .child(content)
```

--------------------------------

### Initialize LogView with Buffer

Source: https://docs.tui-lipan.dev/widgets/data

Sets up a LogView with a bounded ring buffer and custom styling for log levels.

```rust
let buffer = Arc::new(LogBuffer::new(10_000)); // 10k entry ring buffer

// In a background thread: buffer.push(LogEntry { level, message });

LogView::new(buffer.clone())
    .filter_mode(MatchMode::Fuzzy)
    .auto_follow(true)
    .info_style(Style::new().fg(Color::Green))
    .error_style(Style::new().fg(Color::Red).bold())
```

--------------------------------

### Configure Application Runner

Source: https://docs.tui-lipan.dev/quick-start

Set up the application environment, including themes, keymaps, and terminal behavior, before mounting the root component.

```rust
App::new()
    .title("My App")           // Optional outer chrome frame
    .theme(Theme::one_dark())  // Optional theme override
    .system_theme()            // Optional: derive theme from host terminal colors
    .inline_ephemeral(8)       // Optional: inline mode (8 terminal rows)
    .mouse(true)               // Mouse capture (default: true in fullscreen, false in inline)
    .scroll_wheel_multiplier(3) // Optional: lines per wheel tick (default: 1)
    .toast_placement(ToastPlacement::BottomEnd)
    .keymap_path("/path/to/keymap.conf")  // see docs/keybindings.md
    .global_quit(None)                   // disable Ctrl-Q quit without a keymap file
    .framework_keymap(
        FrameworkKeymap::default().unbind(FrameworkAction::Quit),
    )
    .user_keymap_policy(UserKeymapPolicy::Disabled) // ignore env/default user keymaps
    .key_dispatch_policy(KeyDispatchPolicy::AppCommandsFirst)
    .terminal_key_policy(TerminalKeyPolicy::AppCommandsThenTerminal)
    .command_conflict_policy(CommandConflictPolicy::HighestPriority)
    .chord_mismatch_policy(ChordMismatchPolicy::ForwardPrefixAndCurrent)
    .clipboard_config(ClipboardConfig { .. })
    .contrast_policy(ContrastPolicy::Wcag)
    .terminal_bg(query_host_colors().map(|c| c.bg))  // enables Opacity through Color::Reset
    .live_host_terminal_colors(true)  // opt-in runner-managed live host palette refresh
    .mount(Root)
    .exit_view(|_component, ctx| {
        Text::new(format!("Final count: {}", ctx.state.count)).into()
    })
    .run()
```

--------------------------------

### Configure VisualEffect::Ripple

Source: https://docs.tui-lipan.dev/widgets/effects

Examples of defining Ripple effects using explicit struct initialization or helper methods for centered, looping, and burst animations.

```rust
VisualEffect::Ripple {
    origin: EffectOrigin::cell(12.0, 3.0),
    radius: RippleRadius::Fixed(4.0),
    ring_width: 1.5,
    tint: Color::Cyan,
    strength: 0.6,
}
```

```rust
VisualEffect::centered_ripple(4.0, 1.5, Color::Cyan, 0.6)
```

```rust
VisualEffect::centered_looping_ripple(18.0, 90, 1.5, Color::Cyan, 0.6)
```

```rust
let start_tick = ctx.effect_phase();
VisualEffect::centered_burst_ripple(18.0, 45, start_tick, 1.5, Color::Cyan, 0.6)
```

```rust
VisualEffect::Ripple {
    origin: EffectOrigin::aligned(EffectAlignment::TOP_RIGHT),
    radius: RippleRadius::Once {
        max_radius: 18.0,
        duration_ticks: 45,
        start_tick,
    },
    ring_width: 1.5,
    tint: Color::Cyan,
    strength: 0.6,
}
```

--------------------------------

### Implement RAII guard for terminal handoff

Source: https://docs.tui-lipan.dev/external-programs

Example of using an RAII guard to ensure terminal state is resumed even if the process panics or returns early.

```rust
struct Handoff {
    surface_mode: SurfaceMode,
    mouse_enabled: bool,
}

impl Drop for Handoff {
    fn drop(&mut self) {
        let _ = resume_after_external_process(
            self.surface_mode,
            self.mouse_enabled,
        );
    }
}

fn run_editor(
    surface_mode: SurfaceMode,
    mouse_enabled: bool,
) -> io::Result<()> {
    suspend_for_external_process(surface_mode)?;
    let _guard = Handoff {
        surface_mode,
        mouse_enabled,
    };
    // spawn / wait on editor...
    Ok(())
}
```

--------------------------------

### Schedule delayed commands with Command::after

Source: https://docs.tui-lipan.dev/components

Use Command::after to avoid blocking the worker pool with thread::sleep. This example demonstrates debouncing a resize event.

```rust
use std::time::Duration;

// Debounce: coalesce a resize storm into one flush.
Command::after(Duration::from_millis(16), |link: CommandLink<Msg>| {
    link.send(Msg::FlushResizes);
})
```

--------------------------------

### QrCode Constructor and Configuration

Source: https://docs.tui-lipan.dev/widgets/display

Initializes a new QrCode instance and configures its properties such as error correction level, rendering mode, and colors.

```APIDOC
## QrCode Constructor

### Description
Creates a new QrCode instance with the specified payload and allows chaining configuration methods.

### Parameters
- **data** (impl Into<Arc<str>>) - Required - The payload to encode.

### Configuration Methods
- **ecc(QrEcc)** - Sets the error correction level (default: Medium).
- **render(QrRender)** - Sets the module-to-cell mapping (default: HalfBlock).
- **quiet_zone(u16)** - Sets the light margin in modules (default: 4, capped at 32).
- **dark(Color)** - Sets the dark module color (default: Color::Black).
- **light(Color)** - Sets the light module color (default: Color::White).
- **invert()** - Swaps dark and light colors.
- **fallback(impl IntoElement)** - Sets the element to render if the payload exceeds QR capacity.
```

--------------------------------

### List Light Theme Presets

Source: https://docs.tui-lipan.dev/styling

Available light theme constructors.

```rust
Theme::solarized_light()
Theme::gruvbox_light()
Theme::tokyo_night_day()
Theme::catppuccin_latte()
Theme::rose_pine_dawn()
Theme::ayu_light()
```

--------------------------------

### Initialize FileTree Explorer

Source: https://docs.tui-lipan.dev/widgets/data

Configures a FileTree as an explorer with Git status integration and selection event handling.

```rust
FileTree::new("/home/user/projects")
    .git_status(true)
    .change_view(FileTreeChangeView::ChangedOnly)
    .show_diff_stats(true)
    .show_hidden(false)
    .explorer(true)
    .explorer_placeholder("Filter files...")
    .on_select(ctx.link().callback(|e: FileTreeEvent| Msg::FileSelected(e.path)))
```

--------------------------------

### Initialize TextArea with Vim support

Source: https://docs.tui-lipan.dev/widgets/input

Configures a TextArea instance with bound state and enabled Vim motions.

```rust
TextArea::bound(&ctx.state.editor)
    .vim_motions(true)
    .vim_keymap(vim_keymap)
```

--------------------------------

### Recording::view

Source: https://docs.tui-lipan.dev/testing

Initializes a recording session for a plain function that returns an Element.

```APIDOC
## Recording::view(title, fn)

### Description
Starts a new recording session for a given title and rendering function.

### Parameters
- **title** (string) - Required - The title of the recording.
- **fn** (Fn() -> Element) - Required - The function that renders the UI element to be recorded.
```

--------------------------------

### Initialize a Hyperlink

Source: https://docs.tui-lipan.dev/widgets/input

Create a new Hyperlink instance with a label, URL, and custom styling for visited states.

```rust
Hyperlink::new("Open docs")
    .href("https://example.com/docs")
    .visited(self.docs_opened)
    .visited_style(Style::new().fg(Color::Magenta).underline())
    .on_activate(ctx.link().callback(Msg::OpenLink))
```

--------------------------------

### Mounting a Component

Source: https://docs.tui-lipan.dev/components

Demonstrates mounting a component instance to the application and using dependency injection via the constructor.

```rust
fn main() -> tui_lipan::Result<()> {
    App::new()
        .mount(MyApp)        // Takes an instance, not a type
        .run()
}

// Dependency injection: pass data into the constructor
let app = MyApp::new(db_connection, config);
App::new().mount(app).run();
```

--------------------------------

### Configure Padding

Source: https://docs.tui-lipan.dev/enums

Demonstrates how to create Padding objects via conversion or the builder pattern.

```rust
Padding::from(1u16)               // uniform: all sides = 1
Padding::from((2u16, 1u16))       // (vertical, horizontal)
Padding::from((1u16, 2u16, 1u16, 2u16))  // (top, right, bottom, left)
```

```rust
.padding(1)           // uniform
.padding((2, 1))      // (vertical, horizontal)
.padding((1, 2, 1, 2))  // (top, right, bottom, left)
```

--------------------------------

### Mount layouts with Mockup adapter

Source: https://docs.tui-lipan.dev/quick-start

Integrate a layout directly into an application using the Mockup adapter. The closure must return an Element.

```rust
App::new()
    .title("My Layout")
    .mount(Mockup::new(|| {
        Frame::new().header_left("Panel").border(true)
            .child(Text::new("World")).into()  // closure must return Element
    }))
    .run()
```

--------------------------------

### Build Size-Optimized Binary

Source: https://docs.tui-lipan.dev/quick-start

Use a custom release profile to reduce the size of the final application binary.

```bash
cargo build --profile release-size --no-default-features
```

--------------------------------

### mount_web

Source: https://docs.tui-lipan.dev/web-backend

Initializes a tui-lipan component within an xterm.js terminal instance.

```APIDOC
## mount_web

### Description
Initializes and mounts a tui-lipan component to an xterm.js terminal object. This function is available only when targeting wasm32 with the 'web' feature enabled.

### Signature
`pub fn mount_web<C: Component>(component: C, props: C::Properties, term: JsValue, cols: u16, rows: u16) -> Result<WebTerminal<C>>`

### Parameters
- **component** (C) - The component instance to mount.
- **props** (C::Properties) - The properties for the component.
- **term** (JsValue) - The xterm.js Terminal object instance.
- **cols** (u16) - Initial number of columns.
- **rows** (u16) - Initial number of rows.
```

--------------------------------

### Initialize PanView

Source: https://docs.tui-lipan.dev/widgets/layout

Configures a PanView with custom dimensions, clamping, and state persistence.

```rust
PanView::new()
    .child(diagram)
    .width(Length::Flex(1))
    .height(Length::Px(20))
    .clamp(false)
    .center_content(true)
    .free_pan_margin(2)
    .key_step((4, 2))
    .pan_state_key("diagram-preview")
```

--------------------------------

### Recording::component

Source: https://docs.tui-lipan.dev/testing

Initializes a recording session for a Component with default properties.

```APIDOC
## Recording::component(title, c)

### Description
Starts a new recording session for a given title and Component.

### Parameters
- **title** (string) - Required - The title of the recording.
- **c** (Component) - Required - The component to be recorded.
```

--------------------------------

### Initialize and Configure DiffView

Source: https://docs.tui-lipan.dev/widgets/input

Demonstrates the builder pattern for configuring a DiffView instance with split mode, borders, line numbers, and custom styling.

```rust
let diff = DiffView::new(before, after)
    .mode(DiffViewMode::Split)
    .document_view(DocumentView::new("")) // backend inferred
    .height(Length::Auto) // useful for inline/message-style diff blocks
    .border(true)
    .panels_border(true)
    .wrap(true)
    .line_numbers(true)
    .min_line_number_width(4)
    .single_scrollbar(true)
    .join_frame(true)
    .vertical_separator(true)
    .vertical_separator_style(Style::new().dim())
    .highlight_full_width(true)
    .neutral_bg(Color::rgb(24, 24, 24))
    .word_diff(true)
    .show_prefixes(true);
```

--------------------------------

### Configure StatusBar in Rust and RSX

Source: https://docs.tui-lipan.dev/widgets/feedback

Demonstrates initializing a status bar with custom styles and content slots using both standard Rust methods and RSX syntax.

```rust
StatusBar::new()
    .style(Style::new().bg(Color::DarkGray))
    .left_style(Style::new().fg(Color::Green))
    .left(Text::new("MODE: NORMAL").into())
    .right(Text::new("ln 42, col 8").into())
```

```rust
rsx! {
    StatusBar {
        style: Style::new().bg(Color::DarkGray),
        left: Text { content: "Mode: Normal" }
        right: Badge { content: "v1.0" }
    }
}
```

--------------------------------

### Configure ProgressBar with zones and targets

Source: https://docs.tui-lipan.dev/widgets/feedback

Initializes a progress bar with custom styles, percentage display, and threshold zones.

```rust
ProgressBar::new(0.67)
    .progress_style(ProgressStyle::Block)
    .show_percentage(true)
    .filled_style(Style::new().fg(Color::Green))
    .target(0.8)
    .target_style(Style::new().fg(Color::Yellow))
    .zones(vec![
        ProgressZone::new(0.75).style(Style::new().fg(Color::Yellow)),
        ProgressZone::new(0.90).style(Style::new().fg(Color::Red)),
    ])
```

--------------------------------

### Enable DevTools Feature and Configuration

Source: https://docs.tui-lipan.dev/perf

Configure the devtools feature in your dependencies and initialize the DevToolsConfig to monitor metrics.

```toml
tui-lipan = { version = "*", features = ["devtools"] }
```

```rust
App::new().devtools_config(DevToolsConfig {
    logs: false,
    metrics: true,
    show_framework_logs: false,
})
```
Tokens:
Raw