One crate for the shell
One line in Cargo.toml brings the loop, the chrome and four widget crates.
What it does
pito-tui is the app shell for PITO MD terminal apps, as one ratatui 0.30 crate. An app gives it a name, a version and an accent colour, and plugs in its screens; the shell does everything around them: the terminal, a 120 fps loop, the keys, the header, the footer, the hourglass while a screen loads, modals, toasts, a live activity band and a log viewer.
That one line brings ratatui 0.30, crossterm 0.29, pito-header v1.0.1, pito-footer v1.0.1, pito-hourglass v1.0.1 and pito-list v1.0.2, reachable as pito_tui::ratatui, pito_tui::crossterm, pito_tui::header and the rest, so an app pins one crate.
It has no words of its own: every label, hint and message on screen comes from the app, in any language.
-
Screens in a header and a footer
Each screen is a type that implements
Screen: it draws its area, takes its keys, and says what it shows in the header and the footer. The shell lays the screens out as numbered tabs in groups, keeps a breadcrumb when a screen drills in, and fits the footer's hints to the width. -
Keys in a fixed order
One Ctrl+C arms the quit guard until it lapses, a second quits, and while work runs it asks first, in the app's words. Every key goes through one fixed order (the guard, a takeover, a modal, a confirm, a pick, the app, the header, the nav, the screen), so layers never fight over a key.
-
Real commands, followed live
Cx::runstarts a real child command and follows its--progress jsonlines live on the activity band; x stops it with a polite signal, then a kill, and no command outlives the app. -
A terminal always given back
Termturns on raw mode, the alternate screen and bracketed paste, remembers each one, and turns exactly those off again on quit, on an error, on a hangup or termination signal, and on a panic, before the panic message prints.
Measured
- to draw a whole frame, measured on pito-tui 0.4.1, which draws with the same code as 1.0.0; a frame at 120 fps gets 8.3 ms
- 0.07–0.31 ms
- How it was measured
How to use it
-
Start an app and add the shell.
cargo new hello cd hello cargo add pito-tui --git https://github.com/gmrdad82/pito-tui --tag v1.3.0 -
Or by hand in
Cargo.toml.pito-tui = { git = "https://github.com/gmrdad82/pito-tui", tag = "v1.3.0" } -
See everything live in the demo, from a checkout. Ctrl+K opens a Go to list that reaches every screen, and Ctrl+C twice quits.
git clone https://github.com/gmrdad82/pito-tui cd pito-tui cargo run --release --example demo
The four crates it brings
-
pito-header
The groups, tabs, breadcrumb and facts rule at the top.
-
pito-footer
The key hints, notice line, confirm, input and quit guard at the bottom.
-
pito-hourglass
The Braille hourglass shown while a screen loads.
-
pito-list
The selectable rows, scrollbar and range count of every list.