tui-lipandocsv0.1.0
GitHub ↗

Patterns & Anti-Patterns ​

Common Patterns ​

1. View Function Extraction (Mockup → App Workflow) ​

Extract reusable view functions so the same code works in both mockup previews and real components:

rust
// View functions take plain data, return Element
fn sidebar(items: &[&str], selected: usize) -> Element {
    Frame::new()
        .title("Nav").border(true).width(Length::Px(28))
        .child(List::new().items(items.iter().map(|s| ListItem::new(*s))).selected(selected))
        .into()
}

// Step 1: preview with zero boilerplate
fn main() -> tui_lipan::Result<()> {
    let items = vec!["Home", "Settings"];
    mockup!("Preview", { sidebar(&items, 0) })
}

// Step 2: reuse in real component - no changes needed
fn view(&self, ctx: &Context<Self>) -> Element {
    sidebar(&ctx.state.items, ctx.state.selected)
}

2. Reusable Panel Shells (Parameterized UI) ​

When multiple panels share the same chrome but differ in title, status, or body, extract the shared shell into plain Rust helpers. The parameters come from Rust, while rsx! stays focused on composition.

rust
fn app_panel(title: impl Into<Arc<str>>, child: impl Into<Element>) -> Element {
    Frame::new()
        .title(title)
        .border(true)
        .padding(1)
        .child(child)
        .into()
}

fn stats_panel(title: &str, value: &str) -> Element {
    app_panel(
        title,
        rsx! {
            Text {
                content: value,
            }
        },
    )
}

fn view(&self, _ctx: &Context<Self>) -> Element {
    rsx! {
        HStack {
            stats_panel("CPU", "42%"),
            stats_panel("Memory", "1.2 GB"),
        }
    }
}

This is the preferred pattern when:

  • the reusable piece is mostly view/chrome
  • there is no local state or message handling
  • you want to share the same UI between mockups, examples, and real components

If you want a more structured API, wrap the same idea in a small composite widget:

rust
#[derive(Clone)]
struct AppPanel {
    title: Arc<str>,
    child: Element,
}

impl AppPanel {
    fn new(title: impl Into<Arc<str>>, child: impl Into<Element>) -> Self {
        Self {
            title: title.into(),
            child: child.into(),
        }
    }
}

impl From<AppPanel> for Element {
    fn from(panel: AppPanel) -> Element {
        Frame::new()
            .title(panel.title)
            .border(true)
            .padding(1)
            .child(panel.child)
            .into()
    }
}

Use this when the same shell needs a named, reusable API (AppPanel::new(...), .status(...), .footer(...), etc.).

Choose the abstraction level by behavior:

  • Helper function returning Element - best for simple reusable shells
  • Composite widget struct - best for reusable builder-style UI with several options
  • Component with Properties - best when the reusable panel has its own state or events

3. Numbered List Rows ​

Prefer ListItem::numbered(...) or ListItem::bulleted(...) instead of embedding the prefix in the label string yourself. Extra lines automatically indent under the label text.

rust
List::new().items([
    ListItem::new("Alpha")
        .numbered(1)
        .line(ListItemLine::new("first option")),
    ListItem::new("Beta")
        .numbered(2)
        .line(ListItemLine::new("second option")),
])

4. Background Command Pattern ​

Offload blocking I/O to a background thread:

rust
fn update(&mut self, msg: Msg, ctx: &mut Context<Self>) -> Update {
    match msg {
        Msg::LoadUser(id) => {
            ctx.state.loading = true;
            let cmd = ctx.link().command(move |link| {
                let user = db::get_user(id);   // blocking
                link.send(Msg::UserLoaded(user));
            });
            Update::with_command(cmd)
        }
        Msg::UserLoaded(user) => {
            ctx.state.loading = false;
            ctx.state.user = Some(user);
            Update::full()
        }
    }
}

If the blocking work is an interactive subprocess that needs the real TTY ($EDITOR, a pager), do not use link.command / Command::spawn for that phase: use Command::new on the UI thread with terminal_handoff, then request_full_repaint() as needed. See External programs.

4. Keyed Coalescing (Filter-as-You-Type) ​

Avoid stale search results by using TaskPolicy::LatestOnly:

rust
Msg::QueryChanged(q) => {
    ctx.state.query = q.clone();
    let cmd = ctx.link().command_keyed(
        "search",
        TaskPolicy::LatestOnly,
        move |link| {
            let results = search_items(&q);
            link.send(Msg::SearchDone(results));
        },
    );
    Update::with_command(cmd)  // Redraw to show query immediately
}

5. Controlled Scroll with Synced State ​

rust
// Controlled list with parent-managed offset
List::new()
    .items(self.items.clone())
    .selected(self.selected)
    .on_scroll_to(ctx.link().callback(Msg::Scrolled))

// In update:
Msg::Scrolled(offset) => {
    ctx.state.scroll_offset = offset;
    Update::none()
}

6. Memoized Heavy Child Components ​

When a parent rerenders often but some child panels/rows are expensive to rebuild, move those children into their own Component and give them a stable memo_key():

rust
impl Component for MessageRow {
    type Message = RowMsg;
    type Properties = MessageRowProps;
    type State = ();

    fn create_state(&self, _props: &Self::Properties) -> Self::State {}

    fn memo_key(&self, props: &Self::Properties, _ctx: &Context<Self>) -> Option<u64> {
        Some(props.revision)
    }

    fn view(&self, ctx: &Context<Self>) -> Element {
        render_message_row(ctx.props)
    }

    fn update(&mut self, _msg: RowMsg, _ctx: &mut Context<Self>) -> Update {
        Update::none()
    }
}

Use this when:

  • the subtree is expensive to build
  • parent updates are frequent but mostly unrelated to the child
  • the child's visual output is driven by a clear semantic revision key

Avoid using memo_key() as a manual diff cache for everything. If the subtree is cheap, a plain view helper is simpler.

7. Focus Routing ​

Navigate between panels with ctx.request_focus:

rust
fn update(&mut self, msg: Msg, ctx: &mut Context<Self>) -> Update {
    match msg {
        Msg::FocusSidebar => { ctx.request_focus("sidebar"); Update::none() }
        Msg::FocusEditor  => { ctx.request_focus("editor");  Update::none() }
    }
}

fn on_key(&mut self, key: KeyEvent, ctx: &mut Context<Self>) -> KeyUpdate {
    match key.code {
        KeyCode::Char('1') if key.mods.ctrl => {
            ctx.request_focus("sidebar");
            KeyUpdate::handled(Update::none())
        }
        KeyCode::Char('2') if key.mods.ctrl => {
            ctx.request_focus("editor");
            KeyUpdate::handled(Update::none())
        }
        _ => KeyUpdate::unhandled(Update::none())
    }
}

8. Conditional Overlay Pattern ​

Show modals/overlays via state flags (not routing):

rust
// State
struct State {
    show_delete_confirm: bool,
    selected_item: usize,
}

// View
fn view(&self, ctx: &Context<Self>) -> Element {
    rsx! {
        VStack {
            List { items: ..., selected: ctx.state.selected_item }

            if ctx.state.show_delete_confirm {
                Modal {
                    title: "Confirm Delete",
                    VStack {
                        gap: 1,
                        Text { content: "This cannot be undone." }
                        HStack {
                            gap: 1,
                            Button {
                                label: "Cancel",
                                on_click: ctx.link().callback(|_| Msg::CancelDelete),
                            }
                            Button {
                                label: "Delete",
                                on_click: ctx.link().callback(|_| Msg::ConfirmDelete),
                            }
                        }
                    }
                }
            }
        }
    }
}

9. Toast from Update ​

rust
Msg::SaveSuccess => {
    ctx.toast().push(Toast::new("File saved!"));
    Update::none()
}
Msg::SaveError(e) => {
    ctx.toast().push(Toast::new(format!("Error: {e}")).title("Error"));
    Update::none()
}

10. Dynamic Tab Management ​

rust
struct State {
    tabs: Vec<String>,
    active: usize,
}

// In update:
Msg::OpenFile(path) => {
    ctx.state.tabs.push(path);
    ctx.state.active = ctx.state.tabs.len() - 1;
    Update::full()
}
Msg::CloseTab(idx) => {
    ctx.state.tabs.remove(idx);
    ctx.state.active = ctx.state.active.min(ctx.state.tabs.len().saturating_sub(1));
    Update::full()
}
Msg::ReorderTabs(e) => {
    ctx.state.tabs.swap(e.from, e.to);
    ctx.state.active = if ctx.state.active == e.from { e.to } else { ctx.state.active };
    Update::full()
}

11. Markdown Editor + Live Preview ​

Use TextArea for editing and DocumentView for display transforms. Keep the source in one state field and feed both widgets from the same value.

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),
    )

For scroll-sync, emit source-line metrics from editor/preview and set DocumentView::scroll_to_source_line(...).

11a. TextArea inline sentinels (@mentions, file tokens) ​

Store app data on TextAreaSentinel::payload(your_type) and rely on SentinelId + on_sentinel_event for deletes instead of mirroring index → metadata maps. Use TextAreaSnapshot::capture / apply for stash–restore. See widgets/input.md.

12. Choosing the Right Container ​

NeedUseDon't use
Stack children verticallyVStackFrame (unless you need border/title)
Stack children horizontallyHStackFrame (unless you need border/title)
Border + title + status lineFramebare VStack with manual border
Overlay children on top of each otherZStack-
Center a single childCenterVStack with align + justify hacks
Scrollable contentScrollView-
Resizable split panesSplitter-

Frame is for visual chrome, not layout. Use Frame only when you need one or more of: border, title, status text, tab titles, join_frame, clipping, or FrameDecoration. If you just need to group children, use VStack or HStack directly.

Anti-Patterns (Common Mistakes) ​

❌ Returning Update::full() when nothing changed ​

rust
// BAD: triggers unnecessary re-render
Msg::SomeEvent => Update::full()

// GOOD: only redraw if state actually changed
Msg::SomeEvent => {
    if self.process(msg) {
        Update::full()
    } else {
        Update::none()
    }
}

❌ Missing .key(...) on list items or dynamic children ​

rust
// BAD: reconciliation uses position - breaks on insert/remove
rsx! {
    VStack {
        for item in &items {
            ItemWidget { data: item.clone() }
        }
    }
}

// GOOD: stable key for each child
rsx! {
    VStack {
        for item in &items {
            ItemWidget { key: item.id.to_string(), data: item.clone() }
        }
    }
}

❌ Blocking the main thread in update() or view() ​

rust
// BAD: blocks the render loop
Msg::LoadData => {
    let data = std::fs::read_to_string("data.json").unwrap();  // BLOCKS
    ctx.state.data = data;
    Update::full()
}

// GOOD: use a command
Msg::LoadData => {
    Update::with_command(ctx.link().command(|link| {
        let data = std::fs::read_to_string("data.json").unwrap();
        link.send(Msg::DataLoaded(data));
    }))
}

❌ Using TaskPolicy::QueueAll for search/filter ​

rust
// BAD: stale results pile up; each keystroke queues a new search
ctx.link().command_keyed("search", TaskPolicy::QueueAll, ...)

// GOOD: drop old pending searches
ctx.link().command_keyed("search", TaskPolicy::LatestOnly, ...)

❌ Forgetting to drain screen.drain_responses() ​

TUI apps like fzf, vim, and lazygit query terminal capabilities. Not forwarding responses causes them to hang or malfunction.

rust
// BAD: missing response forwarding
screen.process_bytes(&bytes);
let snapshot = screen.render_snapshot();

// GOOD: always drain and forward
screen.process_bytes(&bytes);
if let Some(pty) = &self.pty {
    for response in screen.drain_responses() {
        let _ = pty.write(&response);
    }
}
let snapshot = screen.render_snapshot();

❌ Setting scroll offset before resize in inline mode ​

rust
// BAD: corrupts ratatui's internal cursor offset calculation
terminal.set_cursor_position((0, 0));  // before draw on resize
terminal.draw(...);

// GOOD: use backend_mut() for operations that must NOT touch ratatui state
terminal.backend_mut().execute(cursor_op)?;

❌ Missing PartialEq on Properties ​

Properties must implement Clone + PartialEq for reconciliation to work. Without PartialEq, props changes may not trigger on_props_changed.

rust
// BAD
#[derive(Clone)]
struct Props { value: String }

// GOOD
#[derive(Clone, PartialEq)]
struct Props { value: String }

❌ Accessing image clipboard without image feature ​

rust
// BAD: will not compile without feature "image"
use tui_lipan::ImageContent;  // Only available with feature "image"

// Check Cargo.toml: features = ["image"]

❌ Using Color::named() for precise contrast ​

rust
// BAD: Color::Gray varies between terminal palettes
Button::new("Click").focus_style(Style::new().bg(Color::Gray))

// GOOD: use explicit RGB for predictable contrast behavior
Button::new("Click").focus_style(Style::new().bg(Color::rgb(80, 80, 80)))

❌ Setting default values explicitly ​

Don't set properties that are already the default - it adds noise and signals misunderstanding of the framework. Common offenders:

rust
// BAD: All of these are no-ops (they set the default value)
Input::new(query.clone())
    .caret_shape(CaretShape::Block)    // Block is the default
    .focusable(true)                   // interactive widgets are focusable by default

VStack::new()
    .width(Length::Flex(1))            // containers default to Flex(1)
    .height(Length::Flex(1))           // containers default to Flex(1)
    .align(Align::Start)              // Start is the default
    .justify(Justify::Start)          // Start is the default

App::new()
    .mouse(true)                      // true in fullscreen mode by default
    .contrast_policy(ContrastPolicy::Wcag)  // Wcag is the default

// GOOD: Only set properties when you want non-default values
Input::new(query.clone())
    .caret_shape(CaretShape::Bar)     // Bar is NOT the default - this IS meaningful

VStack::new()
    .align(Align::Center)             // Center is NOT the default - this IS meaningful

❌ Setting background color on every widget and style variant ​

Background color inherits from the nearest ancestor. Don't repeat it on every child or sub-style:

rust
// BAD: Repeating bg on every widget and sub-style
Frame::new()
    .style(Style::new().bg(Color::indexed(235)))
    .child(
        Input::new(query.clone())
            .style(Style::new().fg(Color::White).bg(Color::indexed(235)))
            .focus_style(Style::new().fg(Color::White).bg(Color::indexed(235)).bold())
    )
    .child(
        List::new()
            .items(items)
            .selection_style(Style::new().fg(Color::Cyan).bg(Color::indexed(235)))
    )

// GOOD: Set bg once on the parent; children inherit it.
// Only set bg when you want a DIFFERENT background.
Frame::new()
    .style(Style::new().bg(Color::indexed(235)))
    .child(
        Input::new(query.clone())
            .style(Style::new().fg(Color::White))
            .focus_style(Style::new().fg(Color::White).bold())
    )
    .child(
        List::new()
            .items(items)
            .selection_style(Style::new().fg(Color::Cyan).bold())
    )

See styling.md for the full style inheritance rules.

Note: Only bg inherits this way. fg does not inherit - each widget resolves its own foreground color independently.

❌ Wrapping containers in Frame unnecessarily ​

Frame is for visual chrome (border, title, status text, clipping). If you just need layout, use VStack/HStack directly:

rust
// BAD: Frame adds no value here - no border, title, or status used
Frame::new()
    .child(
        VStack::new()
            .child(Text::new("Hello"))
            .child(Button::new("Click"))
    )

// GOOD: VStack alone provides the same layout
VStack::new()
    .child(Text::new("Hello"))
    .child(Button::new("Click"))

// GOOD: Frame is justified when you use its features
Frame::new()
    .title("Settings")
    .border(true)
    .status("v1.2")
    .child(
        VStack::new()
            .gap(1)
            .child(Text::new("Hello"))
            .child(Button::new("Click"))
    )

MIT OR Apache-2.0

© Adam Mikołajczyk