tui-splitflap 0.1.0

A Ratatui widget for rendering retro split-flap display boards
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

# tui-splitflap

[![Built With Ratatui](https://ratatui.rs/built-with-ratatui/badge.svg)](https://ratatui.rs/)
[![Crates.io](https://img.shields.io/crates/v/tui-splitflap.svg)](https://crates.io/crates/tui-splitflap)
[![docs.rs](https://img.shields.io/docsrs/tui-splitflap)](https://docs.rs/tui-splitflap)
[![CI](https://github.com/jharsono/tui-splitflap/actions/workflows/ci.yml/badge.svg)](https://github.com/jharsono/tui-splitflap/actions/workflows/ci.yml)
[![License: MIT OR Apache-2.0](https://img.shields.io/crates/l/tui-splitflap.svg)](LICENSE-MIT)

A [Ratatui](https://ratatui.rs) widget for rendering retro split-flap display boards in the terminal.

Animated character tiles that cycle through an ordered character set, just like the mechanical departure boards at airports and train stations.

![demo](https://raw.githubusercontent.com/jharsono/tui-splitflap/main/assets/demo.gif)

## Features

- **Three animation styles** — Sequential (character roll), Mechanical (split-block), and Combined
- **Staggered flips** — configurable delay between adjacent cells for a wave effect
- **Multi-row boards** — display multiple lines of text
- **Mid-flip interrupts** — new messages resolve cleanly from the current animation state
- **Theming** — customizable colors for text, tile background, borders, and split animation
- **Block integration** — wrap the board in a ratatui `Block` for titled borders

## Installation

```sh
cargo add tui-splitflap
```

## Usage

```rust
use tui_splitflap::{FlapBoard, FlapBoardState, FlapMessage, FlipStyle};

let mut state = FlapBoardState::new(1, 20)
    .with_flip_style(FlipStyle::Combined { frames: 3 })
    .with_flip_speed_ms(60)
    .with_stagger_ms(15);

state.set_message(&FlapMessage::single("HELLO WORLD"));
```

In your event loop, call `state.tick(delta_ms)` (returns `true` while animating) and render with
`frame.render_stateful_widget(FlapBoard::new(), area, &mut state)`.

## Animation Styles

| Style | Description |
|-------|-------------|
| `Sequential` | Cycles through each intermediate character. Duration scales with distance. |
| `Mechanical { frames }` | Fixed split-block animation. Constant duration regardless of distance. |
| `Combined { frames }` | Mechanical phase first, then sequential roll to landing. |

## Examples

### Interactive demo

```sh
cargo run --example demo
```

Keys: `[space]` next message · `[m]` mode · `[s]` speed · `[t]` theme · `[r]` reset · `[q]` quit

### Widget pantry

Browse widget variants in the [tui-pantry](https://crates.io/crates/tui-pantry) isolation viewer:

```sh
cargo pantry
```

Or without `cargo-pantry` installed:

```sh
cargo run --example widget_preview --features pantry
```

## License

Dual licensed under [MIT](LICENSE-MIT) or [Apache 2.0](LICENSE-APACHE).

## Contributing

Contributions are welcome. Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this work by you shall be dual licensed as above, without any additional terms or conditions.