tui-treelistview 0.2.2

Interactive tree list widget for Ratatui
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90

# tui-treelistview

[![CI](https://github.com/hexqnt/tui-treelistview/actions/workflows/ci.yml/badge.svg)](https://github.com/hexqnt/tui-treelistview/actions/workflows/ci.yml)
[![crates.io](https://img.shields.io/crates/v/tui-treelistview.svg)](https://crates.io/crates/tui-treelistview)
[![docs.rs](https://docs.rs/tui-treelistview/badge.svg)](https://docs.rs/tui-treelistview)

A tree-list widget for [Ratatui](https://ratatui.rs/).

The widget focuses on interaction with tree data: browsing, navigation, filtering, sorting, marks,
and editing workflows rather than passive rendering alone.

![demo](assets/demo.gif)

> This widget is the open part of a closed-source project, so some features may be highly
> specialized.

## How it works

The widget is split into four layers:

- `TreeModel` provides roots, child states, and a data revision. Your application owns the data.
- `TreeQuery` describes filtering, sorting, root visibility, and selection fallback.
- `TreeListViewState` stores selection, expanded nodes, marks, scroll positions, and caches.
- `TreeListView` renders the current projection as a Ratatui table.

Typical usage:

1. Implement `TreeModel` for your data.
2. Provide a label renderer and a `TreeColumnSet`.
3. Keep `TreeListViewState` in the application state.
4. Handle actions or keys and render `TreeListView` each frame.

`TreeModel` accepts rooted trees, forests, and acyclic graphs: IDs are stable, shared children are
shown as distinct row occurrences, roots and sibling lists contain no duplicate IDs, cycles are not
allowed, and `revision()` changes after relevant model updates.

## Features

- Generic stable node IDs, multiple roots, and occurrence-aware DAG navigation.
- Lazy `Unloaded` and `Loading` child states.
- Filtering, sibling sorting, and stable-ID selection.
- Dynamic columns, horizontal scrolling, and viewport row virtualization.
- Typed view/edit actions, marks, snapshots, and hit testing.
- Iterative traversal for very deep trees.

## Usage

Add the crate from crates.io:

```toml
[dependencies]
tui-treelistview = "0.2"
```

Optional features:

- `keymap` — Crossterm key bindings.
- `serde` — serialization of `TreeListViewSnapshot`.

The crate does not select a Ratatui backend. Editing types are always available.

## Examples

Most examples render into an in-memory buffer and exit immediately. The demo is interactive and
keeps edits in memory.

```bash
cargo run --example minimal
cargo run --example edit_actions
cargo run --example custom_keymap --features keymap
cargo run --example demo --features keymap -- ./ 3
```

Demo keys: arrows or `hjkl` navigate, Enter toggles, `E`/`C` expand or collapse all,
Shift+Up/Down reorder, `a` adds, `e` renames, `d` detaches, `D` deletes, `y`/`p` yank and paste,
Tab changes columns, Ctrl+Left/Right scrolls horizontally, and `q`/Esc exits.

## Benchmarks

The Criterion suite covers balanced, deep, wide, and multi-root trees; projection cache hits and
rebuilds; filtering and sorting; marks and deep selection; indexed-tree validation; and full,
virtualized, and horizontally scrolled rendering.

```bash
cargo bench --bench perf
cargo bench --bench perf -- --test
cargo bench --bench perf -- projection/rebuild
```

The `--test` mode executes every scenario once and is useful as a fast benchmark smoke test.