feat: support Key Group Capturing for dynamic variant data (#35)

- Added `KeyMapConfig::bind()` for mapping matched key groups to enum payloads.
- Implemented `get_bound_*` lookup methods to return owned, captured variants.
- Modified macro to identify key group indices for all macros (@any, @Digit, etc.).
- Automated `Serialize` and `Deserialize` generation to prevent map-key collisions.
- Refreshed project documentation and examples with the new terminology.

Author: rezigned

README.md

@@ -27,6 +27,7 @@
 * ✅ **Declarative Key Mappings**: Define keymaps via simple configuration files (e.g., TOML, YAML) or directly in your code using derive macros.
 * ⌨️ **Key Patterns**: Supports single keys (`a`), combinations (`ctrl-b`), and multi-key sequences (`ctrl-b n`).
 * 🧠 **Key Groups**: Use built-in pattern matching for common key groups (`@upper`, `@lower`, `@alpha`, `@alnum`, and `@any`).
+* 📸 **Key Group Capturing**: Capture specific keypress data (like the actual `char` from `@any` or `@digit`) directly into your action enum variants at runtime.
 * 🧬 **Compile-Time Safety**: The `keymap_derive` macro validates key syntax at compile time, preventing runtime errors.
 * 🌐 **Backend-Agnostic**: Works with multiple backends, including `crossterm`, `termion`, and `wasm`.
 * 🪶 **Lightweight & Extensible**: Designed to be minimal and easy to extend with new backends or features.
@@ -97,6 +98,11 @@ pub enum Action {
     /// Jump.
     #[key("space")]
     Jump,
+
+    /// Key Group Capturing action (e.g. tracking which character was pressed).
+    /// `char` will be captured from any matched key group macro (like `@any` or `@digit`) at runtime.
+    #[key("@any")]
+    Shoot(char),
 }
 ```
 
@@ -109,6 +115,7 @@ The `KeyMap` derive macro generates an associated `keymap_config()` method, whic
 let config = Action::keymap_config();
 
 // `key` is a key code from the input backend, e.g., `crossterm::event::KeyCode`
+// You can lookup the default pre-instantiated action reference:
 match config.get(&key) {
     Some(action) => match action {
         Action::Quit => break,
@@ -117,8 +124,15 @@ match config.get(&key) {
     }
     _ => {}
 }
+
+// Or use Key Group Capturing to extract the actual `char` from `@any` or `@digit`!
+if let Some(Action::Shoot(c)) = config.get_bound(&key) {
+    println!("Captured key: {c}");
+}
 ```
 
+> **Note**: `keymap_derive` automatically generates custom `Serialize` and `Deserialize` implementations for the derived `enum`, making your variants with captured data serialize as simple tags (e.g. `"Shoot"`) out of the box so that Map deserialization continues to work flawlessly.
+
 ### 2. Using External Configuration
 
 `keymap-rs` also supports loading keymaps from external files (e.g., `config.toml`). This is useful for user-configurable keybindings.

examples/action.rs

@@ -1,7 +1,5 @@
-use serde::Deserialize;
-
 #[cfg(feature = "derive")]
-#[derive(Debug, keymap::KeyMap, Deserialize, Hash, PartialEq, Eq)]
+#[derive(Debug, keymap::KeyMap, Hash, PartialEq, Eq, Clone)]
 pub(crate) enum Action {
     /// Jump over obstacles
     #[key("space", "@digit")]
@@ -26,6 +24,11 @@ pub(crate) enum Action {
     /// Exit or pause game
     #[key("q", "esc")]
     Quit,
+
+    /// Key Group Capturing action (e.g. tracking which character was pressed).
+    /// `char` will be captured from any matched key group macro (like `@any` or `@digit`) at runtime.
+    #[key("@any")]
+    Shoot(char),
 }
 
 #[allow(dead_code)]

examples/backend/mock.rs

@@ -13,7 +13,7 @@ impl ToKeyMap for Key {
 }
 
 #[allow(dead_code)]
-pub(crate) fn run<F>(mut f: F) -> io::Result<()>
+pub(crate) fn run<F>(_f: F) -> io::Result<()>
 where
     F: FnMut(Key) -> bool,
 {

examples/capturing.rs

@@ -0,0 +1,40 @@
+#[path = "./backend/mod.rs"]
+mod backend;
+
+#[path = "./action.rs"]
+mod action;
+
+use crate::backend::{print, quit, run};
+use action::Action;
+use keymap::{DerivedConfig, KeyMapConfig};
+
+// In this example, we showcase Key Group Capturing using .get_bound()
+// The Action::Shoot(char) variant is mapped to @any in action.rs.
+pub(crate) const CONFIG: &str = r#"
+Jump = { keys = ["j"], description = "Jump!" }
+"#;
+
+fn main() -> std::io::Result<()> {
+    println!("# Example: Key Group Capturing using .get_bound()");
+    println!("- Press any key to see it captured by Action::Shoot(char)");
+    println!("- Press 'j' to see Action::Jump (unit variant)");
+    println!("- Press 'q' or 'esc' to quit");
+
+    let config: DerivedConfig<Action> = toml::from_str(CONFIG).unwrap();
+
+    run(|key| match config.get_bound(&key) {
+        Some(action) => match action {
+            Action::Quit => quit("quit!"),
+            // This is matched via @any and the char is dynamically bound
+            Action::Shoot(c) => print(&format!("Matched @any! Captured character: '{c}'")),
+            // Standard unit variants work as before
+            Action::Jump | Action::Up | Action::Down | Action::Left | Action::Right => {
+                print(&format!(
+                    "Action: {action:?} (Description: {})",
+                    action.keymap_item().description
+                ))
+            }
+        },
+        None => print(&format!("Unknown key {key:?}")),
+    })
+}

examples/config.rs

@@ -19,12 +19,17 @@ fn main() -> std::io::Result<()> {
 
     let config: Config<Action> = toml::from_str(CONFIG).unwrap();
 
+    // Use .get() for high-performance reference lookup of the "default" variant.
+    // To capture the actual key pressed (e.g. the 'a' in @any), use .get_bound()
+    // or see the `capturing` example.
     run(|key| match config.get(&key) {
         Some(action) => match action {
             Action::Quit => quit("quit!"),
+            // Standard unit variants work as before
             Action::Up | Action::Down | Action::Left | Action::Right | Action::Jump => print(
                 &format!("{action:?} = {}", action.keymap_item().description),
             ),
+            Action::Shoot(_) => print("Shoot! (Use .get_bound() to capture the character)"),
         },
         None => print(&format!("Unknown key {key:?}")),
     })

examples/derive.rs

@@ -5,19 +5,24 @@ mod backend;
 mod action;
 
 use crate::backend::{print, quit, run};
-use keymap::KeyMapConfig;
 use action::Action;
+use keymap::KeyMapConfig;
 
 fn main() -> std::io::Result<()> {
     println!("# Example: Using the KeyMap derive macro");
     let config = Action::keymap_config();
 
+    // Use .get() for high-performance reference lookup of the "default" variant.
+    // To capture the actual key pressed (e.g. the 'a' in @any), use .get_bound()
+    // or see the `capturing` example.
     run(|key| match config.get(&key) {
         Some(action) => match action {
             Action::Quit => quit("quit!"),
-            Action::Up | Action::Down | Action::Left | Action::Right | Action::Jump => {
-                print(&format!("{action:?}"))
-            }
+            Action::Shoot(_) => print("Shoot! (Use .get_bound() to capture the character)"),
+            // Standard unit variants work as before
+            Action::Jump | Action::Up | Action::Down | Action::Left | Action::Right => print(
+                &format!("{action:?} = {}", action.keymap_item().description),
+            ),
         },
         None => print(&format!("Unknown key {key:?}")),
     })

examples/derived_config.rs

@@ -20,12 +20,16 @@ fn main() -> std::io::Result<()> {
 
     let config: DerivedConfig<Action> = toml::from_str(CONFIG).unwrap();
 
+    // Use .get() for high-performance reference lookup of the "default" variant.
+    // To capture the actual key pressed (e.g. the 'a' in @any), use .get_bound()
+    // or see the `capturing` example.
     run(|key| match config.get(&key) {
         Some(action) => match action {
             Action::Quit => quit("quit!"),
-            Action::Up | Action::Down | Action::Left | Action::Right | Action::Jump => {
-                print(&format!("{action:?} = {}", action.keymap_item().description))
-            }
+            Action::Shoot(_) => print("Shoot! (Use .get_bound() to capture the character)"),
+            Action::Up | Action::Down | Action::Left | Action::Right | Action::Jump => print(
+                &format!("{action:?} = {}", action.keymap_item().description),
+            ),
         },
         None => print(&format!("Unknown key {key:?}")),
     })

examples/modes.rs

@@ -7,15 +7,15 @@ use crate::backend::{print, quit, run};
 use keymap::DerivedConfig;
 use serde::Deserialize;
 
-#[derive(keymap::KeyMap, Deserialize, Debug, Hash, Eq, PartialEq)]
+#[derive(keymap::KeyMap, Debug, Hash, Eq, PartialEq, Clone)]
 enum HomeAction {
     #[key("esc")]
     Quit,
     #[key("e")]
     Edit,
 }
 
-#[derive(keymap::KeyMap, Deserialize, Debug, Hash, Eq, PartialEq)]
+#[derive(keymap::KeyMap, Debug, Hash, Eq, PartialEq, Clone)]
 enum EditAction {
     #[key("esc")]
     Exit,

examples/sequences.rs

@@ -8,7 +8,7 @@ use std::time::{Duration, Instant};
 
 use crate::backend::{print, quit, run, Key};
 use action::Action;
-use keymap::DerivedConfig;
+use keymap::{DerivedConfig, KeyMapConfig};
 
 // Override default key mapping defined via #[derive(KeyMap)] in Action.
 pub(crate) const CONFIG: &str = r#"
@@ -26,9 +26,10 @@ fn main() -> std::io::Result<()> {
         let ret = match config.get(&key) {
             Some(action) => match action {
                 Action::Quit => quit("quit!"),
-                Action::Up | Action::Down | Action::Left | Action::Right | Action::Jump => {
-                    print(&format!("{action:?}"))
-                }
+                Action::Shoot(_) => print("Shoot!"),
+                Action::Up | Action::Down | Action::Left | Action::Right | Action::Jump => print(
+                    &format!("{action:?} = {}", action.keymap_item().description),
+                ),
             },
             None => {
                 // Handle key sequence

examples/wasm/game.js

@@ -279,9 +279,9 @@ class ObstacleManager {
 
       const spawnX = lastObstacle
         ? Math.max(
-            canvas.width,
-            lastObstacle.x + CONFIG.OBSTACLE.MIN_GAP + randomOffset,
-          )
+          canvas.width,
+          lastObstacle.x + CONFIG.OBSTACLE.MIN_GAP + randomOffset,
+        )
         : canvas.width + randomOffset;
 
       const type =
@@ -412,8 +412,11 @@ class RainbowTrail {
 
   draw() {
     this.particles.forEach((particle) => {
-      ctx.fillStyle = Utils.hexToRgba(particle.color, particle.alpha);
+      ctx.save();
+      ctx.globalAlpha = particle.alpha;
+      ctx.fillStyle = particle.color;
       ctx.fillRect(particle.x, particle.y, particle.width, particle.height);
+      ctx.restore();
     });
   }
 }
@@ -693,3 +696,16 @@ export function pauseGame() {
 export function setKey(key, description) {
   game.setKey(key, description);
 }
+
+export function setSkin(c) {
+  // Handle char code or string character
+  const char = typeof c === 'number' ? String.fromCharCode(c) : c;
+  const digit = parseInt(char);
+  if (isNaN(digit)) return;
+
+  // Change rainbow trail colors based on digit
+  const baseHue = (digit * 36) % 360;
+  game.rainbowTrail.colors = Array.from({ length: 6 }, (_, i) => {
+    return `hsl(${(baseHue + i * 20) % 360}, 100%, 50%)`;
+  });
+}