Add simple-keybind template

[yanganto]

Why we need this?

This template add an abstraction layer for keybindings. Once the application becomes popular, people will easy to ask different keybindings(ex: vim-style), and then a lot of trivial works and a lot of code change will happen, so it will be nice to guild developer solve this problem ahead.

Background

I have introduced vim-style keybinding to gitui project before(gitui-org/gitui#234). Besides, the configure easy to partially patch if user only want to change part of the key binds (gitui-org/gitui#1511), it will be crucial when application grows, and new keybinds added, the user can upgrade the program and still use the previous key bind as a patch. I feel these are common issues to build a tui application, so add a template here.

[yanganto]

As a template, I am not sure it is good to keep everything in a file(main.rs). If keep everything in a file is better to let people try it. We can drop the refact coommit 1cc2037.

[orhun]

Hey, thanks for the PR!

Before making this concrete as a template, I would've preferred discussing this in an issue :)

Some questions:

• How common is it to depend on crossterm-keybind these days? I don't see any reverse dependencies on crates.io
• What benefits does this bring over the simple template? Couldn't we add the keybindings support to the simple template instead?
• What if we update the website about the existence of this crate instead (along with some examples)? I think that would be better instead of offering different versions of the simple-* template.
• Additionally, we can link to that docs from the simple template's code comments. So people could easily see how to add new key bindings and such.

[yanganto]

Hi @orhun

Thanks for the review. A NOTE is added ahead in the AppKeyEventenum, and a previous NOTE for developer is here. Besides, the configure example is shown in main.rs. If these still not enough, please let me know.

This is a new crate released in just one week, when I starting my new side project lanternshark and I feel the similar issues comes out again and again. I did not use main as a major branch, so there is no reverse dependency. As you can check, one of major feature of crossterm-keybind is struct-patch, There are reverse dependencies. Furthermore, the most important things, struct-patch always keep update in years. You can trust the new simple-keybind template and crossterm-keybind will be maintained. If I am not, you can pull the template down anytime.

The keybinding will parsing Control+c, Control + c, Control + c ...,etc. from user inputs to a crossterm key event. These are trivial and redundant works for developers, so it is good to keep in a crate in a reusable way. Besides, if there is another gui project using crossterm with configure deserializing/patching feature, they can easy to reuse the crate without dependent on ratatui.

If it is nice I will like to keep this in the template, because it will be easy to know how to use with correct dependencies in a code not web content. My personal favorite for the web content is to fetch code snippets from template, so it always clearly dependency for developer. However, if additional website content should be added, I am happy to do so. But if there is any strong opinion against, that we should keep this in website not template, we can follow it.

For the last one, I don't think a developer should read a lot of document before adding a keybinding. It should be straight forward and taught by compiler/program, there already are examples for combine key Control+c, single key q, and special key Esc, so the hints are enough.
Besides, when you put any unsupported keys, the compiler will show something like these.
Currently only support following KeyModifiers: Shift, Control, Alt, Super, Hyper, Meta or
Can not load a KeyCode, please use a char or one of following KeyCodes: "Backspace", "Enter", "Left", "Right", "Up", "Down", "Home", "End", "PageUp", "PageDown", "Tab", "BackTab", "Delete",... "RaiseVolume", "MuteVolume"

Thanks for your suggestions again, if there is anything I can do, please let me know.

[joshka]

I think the main concern I have is that turning every feature into its own template doesn’t scale very well. Users only get to pick one starting template, so adding more and more feature-specific templates can actually make that choice harder rather than easier. For that reason, I don’t think this is a great fit for a standalone template in this repo.

I also took a look at the crossterm-keybind crate, and while the idea is interesting, I noticed that parts of the README are a bit hard to follow. It might be worth running it through an LLM or similar tool to help rephrase and clarify some sections (purely for language and structure, not content), as clearer docs would make it much easier for people to evaluate and adopt the crate.

If the goal is to provide a concrete starting point for users of your crate, one option would be to maintain a dedicated template alongside it — either as a separate repository (e.g. yanganto/crossterm-keybind-template) or within the main crate repo itself. That keeps the ownership and evolution of the template closely tied to the crate, without expanding the core templates surface area here.

As an alternative, this might also work well as a blog post or a “recipe” on the website: explaining the motivation, the design trade-offs, and how to add configurable keybindings to an existing app or to the simple template. That way people can opt into the approach without committing to a separate template up front.

[yanganto]

Move this issue to ratatui/ratatui-website#1008