egaku_term/lib.rs
1//! Egaku-Term — terminal renderer + runtime for [`egaku`] widget state machines.
2//!
3//! `egaku` is a pure-logic widget toolkit: state only, no rendering, no event
4//! loop. Every consumer that wants a terminal UI today re-implements the
5//! same boilerplate:
6//!
7//! 1. Enable raw mode + alternate screen + hide cursor on entry.
8//! 2. Restore those on exit (and on panic, ideally).
9//! 3. Pump `crossterm::event::read()` in a loop.
10//! 4. Translate `KeyEvent` into something the app's state machine understands.
11//! 5. Hand-style each widget render — selected line reverse video, padding,
12//! column wrapping, etc.
13//!
14//! `egaku-term` lifts those five steps into one library:
15//!
16//! - [`Terminal`] — Drop-safe lifecycle wrapper. Constructing one enables raw
17//! mode + alt screen; dropping (or panicking with one alive) restores the
18//! terminal.
19//! - [`Buffer`] — the typed back buffer of [`Cell`]s. Drawers write cells into
20//! it; the runtime [`diff`](Buffer::diff)s it against the previous frame and
21//! flushes only the changed cells via [`render::render_diff`] — no
22//! full-repaint, no `format!()` (★★ TYPED EMISSION).
23//! - [`event::from_crossterm`] — convert any `crossterm::event::Event` into an
24//! [`egaku::KeyCombo`]. Pairs with [`egaku::KeyMap`] for action dispatch.
25//! - [`draw`] — drawers for every widget egaku ships (`ListView`, `TableView`,
26//! `TextInput`, `TabBar`, `Modal`, `SplitPane`, `ScrollView`). Each one takes
27//! a [`Buffer`], a [`Rect`](egaku::Rect), the widget, the theme, and a focus
28//! flag.
29//! - [`Draw`] — the uniform surface over those drawers:
30//! `widget.draw(buf, rect, palette)`, object-safe, sourcing focus from the
31//! widget's own `is_focused()`. It lives here rather than in egaku because a
32//! drawer needs a `Buffer` and a `Palette` and egaku depends on no renderer.
33//! `Modal` is a documented non-implementor — see the trait docs.
34//! - [`TestBackend`] — headless [`Buffer`] capture for golden-frame tests.
35//! - [`App`] / [`run`] — a generic event-loop runtime. Implement `App::handle`
36//! + `App::draw` and `run(&mut app)` does the rest.
37//! - [`keymap!`] / [`key!`] — declarative macros that make hand-authoring
38//! keybindings ergonomic.
39//!
40//! ## Minimal example
41//!
42//! ```no_run
43//! use egaku::ListView;
44//! use egaku_term::{App, Buffer, Result, draw};
45//!
46//! #[derive(Clone, Copy, PartialEq, Eq)]
47//! enum Action { Next, Prev, Quit }
48//!
49//! struct Wizard {
50//! list: ListView,
51//! keys: egaku::KeyMap<Action>,
52//! done: bool,
53//! }
54//!
55//! impl App for Wizard {
56//! type Action = Action;
57//! fn keymap(&self) -> &egaku::KeyMap<Action> { &self.keys }
58//! fn handle(&mut self, action: &Action) {
59//! match action {
60//! Action::Next => self.list.select_next(),
61//! Action::Prev => self.list.select_prev(),
62//! Action::Quit => self.done = true,
63//! }
64//! }
65//! fn draw(&self, frame: &mut Buffer) -> Result<()> {
66//! draw::list(frame, egaku::Rect::new(0.0, 0.0, 40.0, 10.0), &self.list, true);
67//! Ok(())
68//! }
69//! fn should_quit(&self) -> bool { self.done }
70//! }
71//! ```
72
73mod backend;
74mod buffer;
75mod cell;
76
77pub mod anim;
78pub mod app;
79pub mod draw;
80pub mod error;
81pub mod event;
82pub mod keymap;
83pub mod render;
84pub mod terminal;
85pub mod theme;
86
87#[cfg(feature = "tokio")]
88pub mod app_async;
89
90#[cfg(feature = "markdown")]
91pub mod markdown;
92
93pub use app::{App, EventPump, run};
94pub use backend::TestBackend;
95pub use buffer::Buffer;
96pub use cell::{Cell, Modifiers, Style};
97pub use draw::Draw;
98pub use error::{Error, Result};
99pub use event::from_crossterm;
100pub use render::render_diff;
101pub use terminal::Terminal;
102
103/// The back buffer a frame is drawn into. Alias of [`Buffer`] — a drawer's
104/// canvas for one frame, diffed against the previous frame by the runtime.
105pub type Frame = Buffer;
106
107#[cfg(feature = "tokio")]
108pub use app_async::{AsyncApp, run_async};
109
110// Re-export crossterm so downstream crates don't have to track its version
111// independently. They get the exact crossterm we render against.
112pub use crossterm;
113
114/// Re-exports used by the `key!` and `keymap!` macros so callers don't need
115/// to import egaku types directly.
116#[doc(hidden)]
117pub mod __re {
118 pub use egaku::{KeyCombo, KeyMap};
119}