refactor: add ToKeyMap, IntoKeyMap and FromKeyMap traits to allow conversion between keymap's node and backend's key (#28)

Author: rezigned

.github/workflows/ci.yml

@@ -2,20 +2,53 @@ name: CI
 
 on:
   push:
-    branches: [ "main" ]
+    branches: ["main"]
   pull_request:
-    branches: [ "main" ]
+    branches: ["main"]
 
 env:
   CARGO_TERM_COLOR: always
 
 jobs:
-  build:
+  test-backends:
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        backend:
+          - crossterm
+          - termion
 
     steps:
-    - uses: actions/checkout@v3
-    - name: Build
-      run: cargo build --verbose
-    - name: Run tests
-      run: cargo test --workspace --verbose
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+
+      - name: Run tests
+        run: cargo test --no-default-features --features "derive ${{ matrix.backend }}" --verbose
+
+  test-wasm-backend:
+    # TODO: This takes too long to run. Might enable it again later.
+    if: false
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+
+      - name: Install wasm-pack
+        run: cargo install wasm-pack
+
+      - name: Run wasm tests
+        run: wasm-pack test --headless --chrome --features wasm --no-default-features
+
+  test-workspace:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+
+      - name: Run tests
+        run: cargo test --workspace --verbose

.github/workflows/github-pages.yml

@@ -0,0 +1,72 @@
+# See https://book.leptos.dev/deployment/csr.html#github-pages
+name: Release to Github Pages
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'examples/wasm/**'
+  workflow_dispatch:
+
+permissions:
+  contents: write # for committing to gh-pages branch.
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+env:
+  WASM_PATH: ./examples/wasm
+
+jobs:
+  Github-Pages-Release:
+    defaults:
+      run:
+        working-directory: ${{ env.WASM_PATH }}
+
+    timeout-minutes: 10
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4 # repo checkout
+
+      # Install Rust Nightly Toolchain, with Clippy & Rustfmt
+      - name: Install nightly Rust
+        uses: dtolnay/rust-toolchain@nightly
+
+      - name: Add WASM target
+        run: rustup target add wasm32-unknown-unknown
+
+      - name: Download and install Trunk binary
+        run: wget -qO- https://github.com/trunk-rs/trunk/releases/download/v0.21.14/trunk-x86_64-unknown-linux-gnu.tar.gz | tar -xzf-
+
+      - name: Build with Trunk
+        # The behavior of the --public-url argument has changed: it no longer includes a leading '/'.
+        # We now need to specify it explicitly. See https://github.com/trunk-rs/trunk/issues/668
+        run: ./trunk build --release --public-url "/${GITHUB_REPOSITORY#*/}"
+
+      # Deploy with Github Static Pages
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+        with:
+          enablement: true
+          # token:
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          # Upload dist dir
+          path: "${{ env.WASM_PATH }}/dist"
+
+      - name: Deploy to GitHub Pages 🚀
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -1,4 +1,6 @@
-/target
+**/target
+**/pkg
+**/dist
 Cargo.lock
 .DS_Store
 .vscode

Cargo.toml

@@ -23,22 +23,28 @@ homepage = "https://github.com/rezigned/keymap-rs"
 repository = "https://github.com/rezigned/keymap-rs"
 documentation = "https://docs.rs/keymap"
 edition = "2021"
-keywords = ["terminal", "input", "event", "config", "keymap", "keybinding"]
+keywords = ["terminal", "input", "event", "config", "keymap", "keybinding", "wasm"]
 license = "MIT"
 
 [dependencies]
 keymap_parser = { path = "./keymap_parser", version = "1.0.0-rc.2" }
 keymap_derive = { path = "./keymap_derive", version = "1.0.0-rc.2", optional = true }
 crossterm = { version = "0.29", optional = true }
 termion = { version = "4.0", optional = true }
+web-sys = { version = "0.3", features = ["KeyboardEvent", "KeyboardEventInit"], optional = true }
+wasm-bindgen = { version = "0.2", optional = true }
 serde = { version = "1.0", features = ["derive"] }
 
 [features]
-default = ["crossterm", "derive"]
+default = ["derive"]
 derive = ["dep:keymap_derive"]
+crossterm = ["dep:crossterm"]
+termion = ["dep:termion"]
+wasm = ["dep:web-sys", "dep:wasm-bindgen"]
 
 [dev-dependencies]
 toml = "0.8"
+wasm-bindgen-test = "0.3"
 
 [[example]]
 name = "crossterm"
@@ -54,6 +60,11 @@ name = "crossterm_derived_config"
 path = "examples/crossterm/derived_config.rs"
 required-features = ["crossterm", "derive"]
 
+[[example]]
+name = "crossterm_modes"
+path = "examples/crossterm/modes.rs"
+required-features = ["crossterm", "derive"]
+
 [[example]]
 name = "termion"
 required-features = ["termion"]

README.md

@@ -1,6 +1,6 @@
 # keymap-rs
 
-**keymap-rs** is a lightweight and extensible key mapping library for Rust applications. It supports parsing key mappings from configuration files and mapping them to actions based on input events from backends like [`crossterm`](https://crates.io/crates/crossterm), [`termion`](https://docs.rs/termion/latest/termion/), `wasm` (via `web_sys`), and others.
+**keymap-rs** is a lightweight and extensible key mapping library for Rust applications. It supports parsing key mappings from configuration files and mapping them to actions based on input events from backends like [`crossterm`](https://crates.io/crates/crossterm), [`termion`](https://docs.rs/termion/latest/termion/), `wasm`, and others.
 
 ---
 
@@ -15,7 +15,7 @@
   * `@alnum` – alphanumeric
   * `@any` – match any key
 * 🧬 **Derive-based config parser** via `keymap_derive`
-* 🌐 Backend-agnostic (works with `crossterm`, `termion`, `web_sys`, etc.)
+* 🌐 Backend-agnostic (works with `crossterm`, `termion`, `wasm`, etc.)
 * 🪶 Lightweight and extensible
 
 ---
@@ -24,21 +24,31 @@
 
 Run the following command:
 
-> \[!NOTE]
-> By default, this installs with `crossterm` as the default backend. You can enable a different backend by specifying the feature flag:
->
-> ```sh
-> cargo add keymap --features termion  # or web_sys, etc.
-> ```
-
 ```sh
-cargo add keymap
+cargo add keymap --feature {crossterm | termion | wasm}
 ```
 
 ---
 
 ## 🚀 Example
 
+### Parsing keys
+
+Parse an input key string into a `KeyMap`
+```rust
+assert_eq("ctrl-l".parse::<KeyMap>(), KeyMap::new(Modifier::Ctrl, Key::Char('l'))
+
+// Same as above
+assert_eq(parser::parse("ctrl-l"), KeyMap::new(Modifier::Ctrl, Key::Char('l'))
+```
+
+Parse an input key string into the backend's key event.
+```rust
+assert_eq!(
+    keymap::backend::crossterm::parse("ctrl-l"),
+    crossterm::event::KeyEvent::new(KeyCode::Char('l'), KeyModifiers::CONTROL)
+)
+```
 ### Using `keymap_derive`
 
 Define your actions and key mappings:

examples/config_derive.rs

@@ -1,4 +1,7 @@
+#[cfg(feature = "derive")]
 use keymap::{DerivedConfig, Item};
+
+#[cfg(feature = "derive")]
 use serde::Deserialize;
 
 #[cfg(feature = "derive")]
@@ -37,11 +40,13 @@ Up = { keys = ["u", "g g"], description = "Fly!" }
 Quit = { keys = ["@digit"], description = "Quit!" }
 "#;
 
+#[cfg(feature = "derive")]
 #[allow(unused)]
 pub(crate) fn derived_config() -> DerivedConfig<Action> {
     toml::from_str(DERIVED_CONFIG).unwrap()
 }
 
+#[cfg(feature = "derive")]
 #[allow(unused)]
 pub(crate) fn print_config(items: &[(Action, Item)]) {
     println!("--- keymap ---");

examples/crossterm/derive.rs

@@ -10,7 +10,7 @@ use crossterm::{
     terminal::{disable_raw_mode, enable_raw_mode},
 };
 use crossterm_utils::output;
-use keymap::{KeyMapConfig};
+use keymap::KeyMapConfig;
 use std::io;
 
 fn main() -> io::Result<()> {

examples/crossterm/main.rs

@@ -12,7 +12,7 @@ use crossterm::{
     terminal::{disable_raw_mode, enable_raw_mode},
 };
 use crossterm_utils::output;
-use keymap::KeyMap;
+use keymap::ToKeyMap;
 
 fn main() -> io::Result<()> {
     enable_raw_mode()?;
@@ -24,7 +24,7 @@ fn main() -> io::Result<()> {
         let event = read()?;
 
         if let Event::Key(key) = event {
-            if let Some((_, action)) = config.0.get_key_value(&KeyMap::try_from(&key).unwrap()) {
+            if let Some((_, action)) = config.0.get_key_value(&key.to_keymap().unwrap()) {
                 match action {
                     Action::Up => send("Up!")?,
                     Action::Down => send("Down!")?,

examples/crossterm/modes.rs

@@ -0,0 +1,56 @@
+use std::collections::HashMap;
+
+use keymap::{DerivedConfig, ToKeyMap};
+use serde::Deserialize;
+
+#[derive(keymap::KeyMap, Deserialize, Debug, Hash, Eq, PartialEq)]
+enum HomeAction {
+    #[key("esc")]
+    Quit,
+    #[key("e")]
+    Edit,
+}
+
+#[derive(keymap::KeyMap, Deserialize, Debug, Hash, Eq, PartialEq)]
+enum EditAction {
+    #[key("esc")]
+    ExitMode,
+}
+
+#[derive(Deserialize, Debug)]
+#[serde(untagged)]
+enum Actions {
+    Home(DerivedConfig<HomeAction>),
+    Edit(DerivedConfig<EditAction>),
+}
+
+#[allow(unused)]
+pub(crate) const DERIVED_CONFIG: &str = r#"
+[home]
+Quit = { keys = ["esc", "q"], description = "Quit the app" }
+Edit = { keys = ["e"], description = "Enter edit mode" }
+
+[edit]
+ExitMode = { keys = ["esc", "q"], description = "Exit edit mode" }
+"#;
+
+type Modes = HashMap<String, Actions>;
+
+fn main() {
+    let modes: Modes = toml::from_str(DERIVED_CONFIG).unwrap();
+    let mode = "home";
+
+    match mode {
+        "home" => {
+            if let Some(Actions::Home(config)) = modes.get(mode) {
+                // config.get(key)
+            }
+        }
+        "edit" => {
+            if let Some(Actions::Edit(config)) = modes.get(mode) {
+                // config.get(key)
+            }
+        }
+        _ => {}
+    }
+}

examples/termion/main.rs

@@ -6,7 +6,7 @@ mod termion_utils;
 use std::io::{stdin, Write};
 
 use config::{parse_config, Action};
-use keymap::KeyMap;
+use keymap::ToKeyMap;
 use termion::event::Event;
 use termion::input::TermRead;
 use termion_utils::{output, print, Result};
@@ -20,7 +20,7 @@ fn main() -> Result {
         if let Event::Key(key) = event? {
             let mut send = |s: &str| print(&mut stdout, s);
 
-            match bindings.0.get_key_value(&KeyMap::try_from(&key).unwrap()) {
+            match bindings.0.get_key_value(&key.to_keymap().unwrap()) {
                 Some((key, action)) => {
                     if *action == Action::Quit {
                         break;