9ed6a95 Improve README — radicle-tui

Radicle terminal user interface

Improve README

Erik Kundt committed 1 year ago

commit 9ed6a954bb40a0eba2e32270ac1b525c6d06ad53
parent dcf59664df5d9f5fe058fc3f4145bfd65d373960

1 file changed +57 -10

modified README.md

@@ -4,7 +4,17 @@

 `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.
 ## Binaries
 # Table of Contents
 . [Getting Started](#getting-started)
     - [Installation](#installation)
     - [Usage](#usage)
 . [Application framework](#framework)
     - [Example](#example)
 . [Roadmap](#roadmap)
 . [Acknowledgments](#acknowledgments)
 . [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.

@@ -20,7 +30,7 @@ The interfaces are designed to be modular and to integrate well with the existin

 #### From source
 > Requires the Rust toolchain.
 > **Note**: Requires the Rust toolchain.
 You can install the binary from source, by running the following
 commands from inside this repository:

@@ -35,7 +45,7 @@ Or directly from our seed node:

 cargo install --force --locked --git https://seed.radicle.xyz/z39mP9rQAaGmERfUMPULfPUi473tY.git
 ```
 This will install `rad-tui`. You can execute it by running `rad-tui`. All available commands can be shown by running `rad-tui --help`.
 This will install `rad-tui`. All available commands can be shown by running `rad-tui --help`.
 ### Usage

@@ -56,7 +66,7 @@ Select a patch, an issue or a notification only and return its id:

 $ rad-tui <patch | issue | inbox> select --mode id
 ```
 ### Output
 #### Output
 All interfaces return a JSON object that reflects the choices made by the user, e.g.:

@@ -64,9 +74,15 @@ All interfaces return a JSON object that reflects the choices made by the user,

 { "operation": "show", "ids": ["546443226b300484a97a2b2d7c7000af6e8169ba"], args:[] }
 ```
 ## Framework
 ## Application framework
 The library portion of this crate is a framework that is the foundation for the interfaces mentioned above. The framework is built on top of [ratatui](https://ratatui.rs) and was inspired by the Flux application pattern. It took some ideas from [cursive](https://github.com/gyscos/cursive) and [rust-chat-server](https://github.com/Yengas/rust-chat-server).
 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.
 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.
 > **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.
 ### Example

@@ -84,15 +100,18 @@ use tui::ui::widget::text::{TextArea, TextAreaProps};

 use tui::ui::widget::ToWidget;
 use tui::{BoxedAny, Channel, Exit};
 /// Centralized application state
 #[derive(Clone, Debug)]
 struct State {
     hello: String,
 }
 /// All messages known by the application
 enum Message {
     Quit,
 }
 /// Implementation of the app-state trait. It's updated whenever a message was received.
 impl store::State<()> for State {
     type Message = Message;

@@ -101,10 +120,13 @@ impl store::State<()> for State {

             Message::Quit => Some(Exit { value: None }),
         }
     }
     fn tick(&mut self) {}
 }
 /// 1. Initializes the communication channel between frontend and state store
 /// 2. Initializes the application state
 /// 3. Builds a textarea widget which renders a welcome message and quits the
 ///    application when (q) is pressed
 /// 4. Runs the TUI application
 #[tokio::main]
 pub async fn main() -> Result<()> {
     let channel = Channel::default();

@@ -113,7 +135,7 @@ pub async fn main() -> Result<()> {

         hello: "Hey there, press (q) to quit...".to_string(),
     };
     let scene = TextArea::default()
     let textarea = TextArea::default()
         .to_widget(sender.clone())
         .on_event(|key, _, _| match key {
             Key::Char('q') => Some(Message::Quit),

@@ -126,12 +148,37 @@ pub async fn main() -> Result<()> {

                 .into()
         });
     tui::run(channel, state, scene).await?;
     tui::run(channel, state, textarea).await?;
     Ok(())
 }
 ```
 ## ROADMAP
 ### Now
 - [ ] Patch and issue preview in selection interfaces
 - [ ] Basic `radicle-cli` integration
 ### Next
 - [ ] Support for multiple selected list and tree items
 - [ ] Read configuration from file
 - [ ] Support user-defined keybindings
 - [ ] Patch review
 ### Later
 - [ ] Streamline CLI integration w/ config and flags for `rad` commands (e.g. `rad patch edit --tui`)`
 - [ ] Read COBs from JSON input
 - [ ] Add support for custom themes
 ## Contributing
 Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.
 If you have any suggestions that would make this better, please clone the repo and open a patch. You can also simply open an issue with the label "enhancement".
 ## License