Explanation¶

The reasoning behind the design. Nothing here is needed to use the crate — How-to and Reference cover that — but it is what tells you whether a surprising behaviour is a bug or a decision.

• Why escape means back — the one navigation rule that catches people out, and what it buys.
• Why the spinner does not animate — no background task, no frame loop, and the transports that made that the right call.
• Why the output helpers are a pair — and why the table style is not configurable.
• What rtb-tui does not do — the limitations, stated as limitations.

Where this crate sits¶

rtb-tui is one of the small crates the phpboyscout Rust toolkit was broken into. It was extracted from rust-tool-base, the framework that originally carried it as an internal module, and it is published on its own so a tool can take the widgets without taking the framework.

That split is enforced rather than described: deny.toml bans rust-tool-base and rtb-cli-bin from this crate's dependency graph outright, so a change that reintroduces the dependency fails the audit job. The crate can be used by the framework and never the other way round.

The practical consequence for you is that rtb-tui knows nothing about commands, configuration, logging or dependency injection. It takes a state type you own and a slice of rows you own, and hands back a string, a state value or an error. Anything that looks like framework integration has to happen in your code.

Why the reasoning is here and not in a spec¶

Earlier versions of this crate's comments pointed at a design spec — "see W2 in the spec", "the authoritative contract" — for the why behind several decisions. Those references survive in the source and point at a document that is not in this repository.

A spec is a point-in-time design record: it says what somebody intended to build on the day they wrote it, and it stops being updated the moment the code lands. Documentation has to say what the code does now. So the reasoning is written out here, in its own words, and it is checked against the code rather than against the spec that preceded it.