| |
|
| |
|
| |
|
| - |
`radicle-tui` provides various terminal user interfaces for interacting with the [Radicle](https://radicle.xyz) code forge and exposes the application framework they were built with.
|
| + |
`radicle-tui` provides various terminal user interfaces for interacting with the [Radicle](https://radicle.xyz) code forge. It also exposes the application framework they were built with.
|
| |
|
| |
# Table of Contents
|
| |
1. [Getting Started](#getting-started)
|
| |
- [Installation](#installation)
|
| |
- [Usage](#usage)
|
| - |
2. [Application framework](#framework)
|
| + |
2. [Application framework](#application-framework)
|
| + |
- [Design](#design)
|
| |
- [Example](#example)
|
| |
3. [Roadmap](#roadmap)
|
| - |
4. [Acknowledgments](#acknowledgments)
|
| - |
5. [License](#license)
|
| + |
4. [Contributing](#contributing)
|
| + |
5. [Contact](#contact)
|
| + |
6. [License](#license)
|
| |
|
| |
## Getting started
|
| |
|
| - |
This crate provides a single binary called `rad-tui` which contains all user interfaces. Specific interfaces can be run by the appropriate command, e.g. `rad-tui patch select` shows a patch selector.
|
| + |
This crate provides a binary called `rad-tui` which contains all user interfaces. Specific interfaces can be run by the appropriate command, e.g. `rad-tui patch select` shows a patch selector.
|
| |
|
| - |
The interfaces are designed to be modular and to integrate well with the existing Radicle CLI. Right now, they are meant to be called from other programs that will collect and process their output.
|
| + |
The interfaces are designed to be modular and to integrate well with the existing Radicle CLI. Right now, the binary is meant to be called from `rad`, which will collect and process its output, e.g.
|
| + |
|
| + |
```
|
| + |
rad patch show
|
| + |
```
|
| + |
|
| + |
will show a patch selector and pass on the id of the selected patch.
|
| + |
|
| + |
> **Note:** The integration into the Radicle CLI is not fully done, yet. Please refer to the [Usage](#usage) section for information on how to use `rad-tui` already.
|
| |
|
| |
### Installation
|
| |
|
| |
|
| |
### Usage
|
| |
|
| + |
Soon, `rad-tui` will be integrated into [`heartwood`](https://app.radicle.xyz/nodes/seed.radicle.xyz/rad:z3gqcJUoA1n9HaHKufZs5FCSGazv5). Until then, you can use the `rad` proxy script that is provided. It's considered to be a drop-in replacement for `rad` and can be used for testing and prototyping purposes. It should reflect the current behavior, as if `rad-tui` would have been integrated, e.g.
|
| + |
|
| + |
```sh
|
| + |
# show an interface that let's you select a patch
|
| + |
./scripts/rad.sh patch show
|
| + |
```
|
| + |
```sh
|
| + |
# show an interface that let's you select a patch and an operation
|
| + |
./scripts/rad.sh patch --tui
|
| + |
```
|
| + |
|
| + |
Both commands will call into `rad-tui`, process its output and call `rad` accordingly.
|
| + |
|
| + |
#### Interfaces
|
| + |
|
| |
Select a patch, an issue or a notification and an operation:
|
| |
|
| |
```
|
| |
|
| |
The library portion of this crate is a framework that is the foundation for all `radicle-tui` binaries. The framework is built on top of [ratatui](https://ratatui.rs) and mostly follows the Flux application pattern. It took some ideas from [tui-realm](https://github.com/veeso/tui-realm) and [cursive](https://github.com/gyscos/cursive). The concurrency model was mostly inspired by [rust-chat-server](https://github.com/Yengas/rust-chat-server).
|
| |
|
| - |
> **Note**: Core functionalities are considered to be stable, but the API may still change at any point. New features like configurations, used-defined keybindings, themes etc. will be added soon though.
|
| + |
> **Note**: Existing core functionalities are considered to be stable, but the API may still change at any point. New features like configurations, used-defined keybindings, themes etc. will be added soon though.
|
| + |
|
| + |
The framework comes with a widget library that provides low-level widgets such as lists, text fields etc. as well as higher-level application widgets such as windows, pages and various other containers.
|
| + |
|
| + |
> **Note:** The widget library is under heavy development and still missing most low-level widgets. These will be added where needed by the `radicle-tui` binaries.
|
| + |
|
| + |
### Design
|
| + |
|
| + |
The framework was built with a few design goals in mind:
|
| |
|
| - |
The framework comes with widget library that provides low-level widgets such as lists, text fields etc. as well as higher-level application widgets such as windows, pages and shortcuts.
|
| + |
- **async**: state updates and IO should be asynchronous and not block the UI
|
| + |
- **declarative**: developers should rather think about the *What* then the *How*
|
| + |
- **widget library**: custom widgets should be easy to build; ready-made widgets should come with defaults for user interactions and rendering
|
| |
|
| - |
> **Note:** The widget library is under heavy development and still missing most low-level widgets. These will be added as they are needed by the `radicle-tui` binaries.
|
| + |
The central pieces of the framework are the `Store`, the `Frontend` and a message passing system that let both communicate with each other. The `Store` handles the centralized application state and sends updates to the `Frontend`, whereas the `Frontend` handles user-interactions and sends messages to the `Store`, which updates the state accordingly.
|
| + |
|
| + |
On top of this, an extensible widget library was built. A widget is defined by an implementation of the `View` trait and a `Widget` it is wrapped in. A `View` handles user-interactions, updates itself whenever the application state changed and renders itself frequently. A `Widget` adds additional support for properties and event, update and render callbacks. Properties define the data, configuration etc. of a widget. They are updated by the framework taking the properties built by the `on_update` callback. The `on_event` callback is used to emit application messages whenever a widget receives an event.
|
| + |
|
| + |
The main idea is to build widgets that handle their specific events already, and that are updated with the properties built by the `on_update` callback. Custom logic is added by setting the `on_event` callback. E.g. the `Table` widget handles item selection already; items are set via the `on_update` callback and application messages are emitted via the `on_event` callback.
|
| |
|
| |
### Example
|
| |
|
| |
use tui::ui::widget::ToWidget;
|
| |
use tui::{BoxedAny, Channel, Exit};
|
| |
|
| - |
/// Centralized application state
|
| + |
/// Centralized application state.
|
| |
#[derive(Clone, Debug)]
|
| |
struct State {
|
| |
hello: String,
|
| |
}
|
| |
|
| - |
/// All messages known by the application
|
| + |
/// All messages known by the application.
|
| |
enum Message {
|
| |
Quit,
|
| |
}
|
| |
|
| |
/// Implementation of the app-state trait. It's updated whenever a message was received.
|
| + |
/// Applications quit whenever an `Exit` is returned by the `update` function. The `Exit`
|
| + |
/// type also provides and optional return value.
|
| |
impl store::State<()> for State {
|
| |
type Message = Message;
|
| |
|