eddacraft-tui 0.2.3

Shared Ratatui component library for the eddacraft product family
Documentation

eddacraft-tui

Shared Ratatui component library for open-source TUIs that follow the eddacraft design system.

Modules

  • theme/ — eddacraft Terminal Standard colour palette, Theme trait, semantic Role tokens, and brand theming
  • keyboard/ — key binding definitions, action mapping, and introspectable Binding table
  • widgets/ — reusable TUI widgets (see Widgets below)
  • pretext/ — two-phase prepare/layout text engine for streaming AI output and dynamic reflow
  • surface.rs — base Surface trait for TUI screens
  • shell.rs — shared shell chrome renderer

Design System

Implements the eddacraft Terminal Standard:

Token Colour
Void rgb(13, 13, 15)
Structure rgb(42, 42, 46)
Off-White rgb(235, 235, 235)
Ghost Grey rgb(133, 133, 138)
anvil Ember rgb(204, 85, 0)
edda Growth rgb(46, 139, 87)
Brick Red rgb(201, 74, 74)
Dull Amber rgb(208, 140, 56)

Usage

[dependencies]
eddacraft-tui = "0.2"

use eddacraft_tui::prelude::*;

let theme = EddaCraftTheme;
let spinner = Spinner::new(&theme).eddacraft().label("Loading...");
let forge_spinner = Spinner::new(&theme).anvil().label("Forging...");

// Pass the consuming crate's version explicitly.
// render_shell(frame, area, ShellBranding::Anvil, "anvil", "Watch", "[q] quit", &theme, env!("CARGO_PKG_VERSION"));

ParallelProgress also uses the branded anvil spinner automatically for running checks.

render_shell supports reusable shell marks for open-source apps:

  • ShellBranding::Plain
  • ShellBranding::EddaCraft -> [■]
  • ShellBranding::Edda -> [=]
  • ShellBranding::Anvil -> [‡]

ProgressBar and ParallelProgress animate toward their target value. Your event loop must call animate_tick each frame for the transition to play — see docs/animations.md.

Widgets

The widgets/ module ships a curated component set. Highlights:

  • Inputs — TextInput, Editor, Select, Confirm
  • Status — Spinner, ProgressBar, ParallelProgress, StatusBadge, StatusBar
  • Layout — Container, Divider, Header
  • Data — DataTable (sortable, themed ▲/▼ indicators), Tree (expand/collapse via TreeState), LogPanel
  • Overlays — OverlayStack + Layer + Placement for layered modals; Modal and Toast/ToastStack as ready-made consumers
  • Chrome — HelpBar auto-renders key hints from KeyHandler::default_bindings(), so help text stays in sync with the keymap
  • Text reflow — PretextWidget + PretextState for cached two-phase layout (see Pretext layout below)
  • Wrappers — Hideable, Disableable, Padded decorate any Widget/StatefulWidget without bloating each widget's API

Optional features

Feature Adds
image ImagePane — themed wrapper around ratatui-image (Kitty / Sixel / iTerm2 / halfblocks)
big-text BigBanner — themed wrapper around tui-big-text for branded splashes
test-utils Snapshot testing helpers re-exported for downstream crates 
[dependencies]
eddacraft-tui = { version = "0.2", features = ["image", "big-text"] }

Pretext layout

pretext is a two-phase text layout engine inspired by Cheng Lou's Pretext library for the browser. Measure word widths once with unicode-width, cache the layout per container width, and re-run only on resize — eliminating reflow stutter for streaming AI output and animated layouts.

use eddacraft_tui::prelude::*;
use ratatui::widgets::StatefulWidget;

let theme = EddaCraftTheme;
let mut state = PretextState::new("streaming tokens flow here…");
let widget = PretextWidget::themed(&theme);

// Each frame:
// widget.render(area, frame.buffer_mut(), &mut state);

// On new tokens:
state.append(" more text from the model");

// Flow text around moving shapes:
state.set_exclusions(vec![ExclusionZone::circle(40, 8, 5)]);

The widget itself is zero-sized — all caching lives on PretextState. At unchanged container width subsequent renders skip layout entirely; the cache is invalidated by a width change, by any text mutation (set_text, set_styled_text, append, append_styled), by set_exclusions, or by an explicit invalidate_layout() call.

Documentation

Extended guides live in docs/. Contributor docs remain at the repo root (CONTRIBUTING.md, RELEASE.md, SECURITY.md).

Links

Acknowledgements

Smooth progress and spinner animations are powered by vyfor/animate, a minimal animation engine for Ratatui.

The pretext module ports the layout engine and widget originally prototyped in joshuaboys/pretext-tui, itself inspired by Cheng Lou's Pretext for the browser.

Licence

Apache-2.0