directional-ui

Backend-agnostic layout, display-list, and focus/dispatch model for UIs driven by directional input.

Workspace

This repository has three crates:

• directional-ui: core scene builder, stable keys, layout, display list, hit testing, persistent interaction state, command hints, widgets, and event dispatch.
• directional-ui-ratatui: terminal measurement, display-list rendering into a ratatui::Buffer, crossterm event mapping, and a terminal Theme.
• directional-ui-bevy: Bevy plugin, display-list-to-entity rebuild systems, stable custom mount entities, input mapping, font measurement, and a Bevy Theme.

The terminal backend's public API exposes ratatui and crossterm types. Its dependency floor is ratatui 0.30 and crossterm 0.29; consumers must use compatible versions of those crates.

The normal frame loop is:

build -> layout -> sync -> paint -> dispatch -> paint -> draw

Build creates a retained Scene from app data. Layout solves rectangles. Sync clamps persistent State to the current scene. Paint fills the keyed display list and hints. Dispatch applies one input event to state and returns a Response. Paint runs again to reflect focus, hover, press, scroll, or popup changes before the backend draws.

Examples

Backend smoke examples live in:

• crates/directional-ui-ratatui/examples/terminal_smoke.rs
• crates/directional-ui-ratatui/examples/custom_mount.rs
• crates/directional-ui-bevy/examples/bevy_smoke.rs

Run them with cargo run -p directional-ui-ratatui --example terminal_smoke or cargo run -p directional-ui-bevy --example bevy_smoke.

Contributing

See docs/contributing/.

License

LGPL-3.0-or-later © 2026 kp2pml30

The LGPL (LICENSE) applies as an additional permission on top of the GPL (LICENSE.GPL).