feat: add tap-hold-keys action with named key list options

Adds a new tap-hold variant `tap-hold-keys` that uses named optional
list parameters instead of positional key lists. This addresses the
usability concern of `tap-hold-release-tap-keys-release` having too
many positional parameters, and adds the ability to trigger hold early
on press for specific keys (closes jtroo#1985).

Syntax:
  (tap-hold-keys <repress-timeout> <hold-timeout> <tap> <hold>
    (tap-on-press <keys...>)
    (tap-on-press-release <keys...>)
    (hold-on-press <keys...>))

All list options are optional. Unlisted keys use PermissiveHold behavior.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: malpern

cfg_samples/kanata.kbd

@@ -570,6 +570,17 @@ If you need help, please feel welcome to ask in the GitHub discussions.
   ;; This is useful for home row mods where fast typing should not trigger modifiers.
   utk (tap-hold-tap-keys 200 200 u @msc (a o e))
 
+  ;; tap-hold-keys is a flexible tap-hold with named key list options.
+  ;; tap: u    hold: misc layer
+  ;; (tap-on-press a o e)         — tap immediately if a, o, or e are pressed
+  ;; (tap-on-press-release ' , .) — tap if ', ,, or . are pressed then released
+  ;; (hold-on-press 1 2 3)        — hold immediately if 1, 2, or 3 are pressed
+  ;; All list options are optional. Unlisted keys use PermissiveHold behavior.
+  uthk (tap-hold-keys 200 200 u @msc
+    (tap-on-press a o e)
+    (tap-on-press-release ' , .)
+    (hold-on-press 1 2 3))
+
   ;; tap-hold-order resolves by release order instead of timeout.
   ;; tap: a    hold: lctl    buffer: 50ms (fast typing grace period)
   aor (tap-hold-order 200 50 a lctl)

docs/config.adoc

@@ -2017,6 +2017,7 @@ results in `$tap-action` activating.
 (tap-hold-release-tap-keys-release $tap-repress-timeout $hold-timeout $tap-action $hold-action $tap-trigger-keys-on-press $tap-trigger-keys-on-press-then-release)
 (tap-hold-except-keys $tap-repress-timeout $hold-timeout $tap-action $hold-action $tap-keys)
 (tap-hold-tap-keys $tap-repress-timeout $hold-timeout $tap-action $hold-action $tap-keys)
+(tap-hold-keys $tap-repress-timeout $hold-timeout $tap-action $hold-action [options...])
 (tap-hold-opposite-hand $timeout $tap-action $hold-action [options...])
 (tap-hold-order $tap-repress-timeout $buffer-ms $tap-action $hold-action [options...])
 ----
@@ -2070,6 +2071,14 @@ when other keys are pressed and released.
 Waits for full `$hold-timeout` before activating `$hold-action`.
 This is useful for home row mods where fast typing should not trigger modifiers.
 
+| `tap-hold-keys`
+| A flexible tap-hold variant with named key list options.
+Options are: `(tap-on-press <keys...>)` activates `$tap-action` early if a listed key is pressed;
+`(tap-on-press-release <keys...>)` activates `$tap-action` early if a listed key is pressed then released;
+`(hold-on-press <keys...>)` activates `$hold-action` early if a listed key is pressed.
+For any other key, activates `$hold-action` when the key is pressed and released (PermissiveHold behavior).
+All list options are optional.
+
 | `tap-hold-opposite-hand`
 | Resolves to `$hold-action` when a key from the opposite hand (per `defhands`) is pressed.
 Requires a `defhands` directive. Supports list-form options for fine-grained control.

parser/src/cfg/custom_tap_hold.rs

@@ -125,6 +125,64 @@ pub(crate) fn custom_tap_hold_release_trigger_tap_release(
     )
 }
 
+/// Returns a closure for `tap-hold-keys` with three optional key lists:
+/// - `keys_tap_on_press`: trigger tap immediately on press
+/// - `keys_tap_on_press_release`: trigger tap when pressed then released
+/// - `keys_hold_on_press`: trigger hold immediately on press
+/// For any other key, falls back to PermissiveHold behavior.
+///
+/// Priority when a key appears in multiple lists (checked in order):
+/// tap-on-press > hold-on-press > tap-on-press-release > PermissiveHold
+pub(crate) fn custom_tap_hold_keys(
+    keys_tap_on_press: &[OsCode],
+    keys_tap_on_press_release: &[OsCode],
+    keys_hold_on_press: &[OsCode],
+    a: &Allocations,
+) -> &'static CustomTapHoldFn {
+    let keys_tap_on_press =
+        a.sref_vec(Vec::from_iter(keys_tap_on_press.iter().copied().map(u16::from)));
+    let keys_tap_on_press_release = a.sref_vec(Vec::from_iter(
+        keys_tap_on_press_release.iter().copied().map(u16::from),
+    ));
+    let keys_hold_on_press =
+        a.sref_vec(Vec::from_iter(keys_hold_on_press.iter().copied().map(u16::from)));
+    a.sref(
+        move |mut queued: QueuedIter, _coord: KCoord| -> (Option<WaitingAction>, bool) {
+            while let Some(q) = queued.next() {
+                if q.event().is_press() {
+                    let (i, j) = q.event().coord();
+                    if i != REAL_KEY_ROW {
+                        continue;
+                    }
+                    // If key is in tap-on-press list, trigger tap immediately.
+                    if keys_tap_on_press.iter().copied().any(|j2| j2 == j) {
+                        return (Some(WaitingAction::Tap), false);
+                    }
+                    // If key is in hold-on-press list, trigger hold immediately.
+                    if keys_hold_on_press.iter().copied().any(|j2| j2 == j) {
+                        return (Some(WaitingAction::Hold), false);
+                    }
+                    // If key is in tap-on-press-release list and has been released,
+                    // trigger tap.
+                    if keys_tap_on_press_release.iter().copied().any(|j2| j2 == j) {
+                        let target = Event::Release(i, j);
+                        if queued.clone().copied().any(|q| q.event() == target) {
+                            return (Some(WaitingAction::Tap), false);
+                        }
+                    }
+                    // Otherwise do the PermissiveHold algorithm:
+                    // if another key was pressed and released, trigger hold.
+                    let target = Event::Release(i, j);
+                    if queued.clone().copied().any(|q| q.event() == target) {
+                        return (Some(WaitingAction::Hold), false);
+                    }
+                }
+            }
+            (None, false)
+        },
+    )
+}
+
 pub(crate) fn custom_tap_hold_except(keys: &[OsCode], a: &Allocations) -> &'static CustomTapHoldFn {
     let keys = a.sref_vec(Vec::from_iter(keys.iter().copied()));
     a.sref(

parser/src/cfg/list_actions.rs

@@ -21,6 +21,7 @@ pub const TAP_HOLD_EXCEPT_KEYS: &str = "tap-hold-except-keys";
 pub const TAP_HOLD_EXCEPT_KEYS_A: &str = "tap⬓⤫keys";
 pub const TAP_HOLD_TAP_KEYS: &str = "tap-hold-tap-keys";
 pub const TAP_HOLD_TAP_KEYS_A: &str = "tap⬓tapkeys";
+pub const TAP_HOLD_KEYS: &str = "tap-hold-keys";
 pub const MULTI: &str = "multi";
 pub const MACRO: &str = "macro";
 pub const MACRO_REPEAT: &str = "macro-repeat";
@@ -160,6 +161,7 @@ pub fn is_list_action(ac: &str) -> bool {
         TAP_HOLD_EXCEPT_KEYS_A,
         TAP_HOLD_TAP_KEYS,
         TAP_HOLD_TAP_KEYS_A,
+        TAP_HOLD_KEYS,
         MULTI,
         MACRO,
         MACRO_REPEAT,

parser/src/cfg/mod.rs

@@ -1519,6 +1519,7 @@ fn parse_action_list(ac: &[SExpr], s: &ParserState) -> Result<&'static KanataAct
             parse_tap_hold_timeout(&ac[1..], s, HoldTapConfig::PermissiveHold)
         }
         TAP_HOLD_RELEASE_KEYS_TAP_RELEASE => parse_tap_hold_keys_trigger_tap_release(&ac[1..], s),
+        TAP_HOLD_KEYS => parse_tap_hold_keys_named_lists(&ac[1..], s),
         TAP_HOLD_RELEASE_KEYS | TAP_HOLD_RELEASE_KEYS_A => {
             parse_tap_hold_keys(&ac[1..], s, TAP_HOLD_RELEASE_KEYS, custom_tap_hold_release)
         }

parser/src/cfg/tap_hold.rs

@@ -69,6 +69,12 @@ pub(crate) fn parse_tap_hold_options(
 }
 
 const TAP_HOLD_OPTION_KEYWORDS: &[&str] = &["require-prior-idle"];
+const TAP_HOLD_KEYS_OPTION_KEYWORDS: &[&str] = &[
+    "require-prior-idle",
+    "tap-on-press",
+    "tap-on-press-release",
+    "hold-on-press",
+];
 
 /// Count how many trailing expressions are tap-hold option lists.
 /// An option list is a list whose first element is a known option keyword.
@@ -302,3 +308,137 @@ Params in order:
         require_prior_idle: opts.require_prior_idle,
     }))))
 }
+
+pub(crate) fn parse_tap_hold_keys_named_lists(
+    ac_params: &[SExpr],
+    s: &ParserState,
+) -> Result<&'static KanataAction> {
+    // Count trailing options using the extended keyword set.
+    let n_opts = {
+        let mut count = 0;
+        for expr in ac_params.iter().rev() {
+            if let Some(list) = expr.list(s.vars()) {
+                if let Some(kw) = list.first().and_then(|e| e.atom(s.vars())) {
+                    if TAP_HOLD_KEYS_OPTION_KEYWORDS.contains(&kw) {
+                        count += 1;
+                        continue;
+                    }
+                }
+            }
+            break;
+        }
+        count
+    };
+    let n_positional = ac_params.len() - n_opts;
+    if n_positional != 4 {
+        bail!(
+            r"{} expects 4 items after it, got {}.
+Params in order:
+<tap-repress-timeout> <hold-timeout> <tap-action> <hold-action>
+Followed by optional lists:
+(tap-on-press <keys...>) (tap-on-press-release <keys...>) (hold-on-press <keys...>)
+(require-prior-idle <ms>)",
+            TAP_HOLD_KEYS,
+            n_positional,
+        )
+    }
+    let tap_repress_timeout = parse_u16(&ac_params[0], s, "tap repress timeout")?;
+    let hold_timeout = parse_non_zero_u16(&ac_params[1], s, "hold timeout")?;
+    let tap_action = parse_action(&ac_params[2], s)?;
+    let hold_action = parse_action(&ac_params[3], s)?;
+    if matches!(tap_action, Action::HoldTap { .. }) {
+        bail!("tap-hold does not work in the tap-action of tap-hold")
+    }
+
+    let mut require_prior_idle = None;
+    let mut tap_on_press: Vec<OsCode> = vec![];
+    let mut tap_on_press_release: Vec<OsCode> = vec![];
+    let mut hold_on_press: Vec<OsCode> = vec![];
+    let mut seen_options: HashSet<&str> = HashSet::default();
+
+    for option_expr in &ac_params[n_positional..] {
+        let Some(option) = option_expr.list(s.vars()) else {
+            bail_expr!(
+                option_expr,
+                "expected option list, e.g. `(tap-on-press a b c)`"
+            );
+        };
+        if option.is_empty() {
+            bail_expr!(option_expr, "option list cannot be empty");
+        }
+        let kw = option[0]
+            .atom(s.vars())
+            .ok_or_else(|| anyhow_expr!(&option[0], "option name must be a string"))?;
+        if !seen_options.insert(kw) {
+            bail_expr!(&option[0], "duplicate option '{}'", kw);
+        }
+        match kw {
+            "require-prior-idle" => {
+                require_prior_idle =
+                    Some(parse_require_prior_idle_option(option, option_expr, s)?);
+            }
+            "tap-on-press" => {
+                tap_on_press = parse_key_list_from_option(option, option_expr, s, kw)?;
+            }
+            "tap-on-press-release" => {
+                tap_on_press_release = parse_key_list_from_option(option, option_expr, s, kw)?;
+            }
+            "hold-on-press" => {
+                hold_on_press = parse_key_list_from_option(option, option_expr, s, kw)?;
+            }
+            _ => bail_expr!(
+                &option[0],
+                "unknown tap-hold-keys option '{}'. \
+                Valid options: tap-on-press, tap-on-press-release, hold-on-press, require-prior-idle",
+                kw
+            ),
+        }
+    }
+
+    Ok(s.a.sref(Action::HoldTap(s.a.sref(HoldTapAction {
+        config: HoldTapConfig::Custom(custom_tap_hold_keys(
+            &tap_on_press,
+            &tap_on_press_release,
+            &hold_on_press,
+            &s.a,
+        )),
+        tap_hold_interval: tap_repress_timeout,
+        timeout: hold_timeout,
+        tap: *tap_action,
+        hold: *hold_action,
+        timeout_action: *hold_action,
+        on_press_reset_timeout_to: None,
+        require_prior_idle,
+    }))))
+}
+
+/// Parse keys from a named option list like `(tap-on-press a b c)`.
+/// The first element is the keyword, remaining elements are key names.
+fn parse_key_list_from_option(
+    option: &[SExpr],
+    option_expr: &SExpr,
+    s: &ParserState,
+    kw: &str,
+) -> Result<Vec<OsCode>> {
+    if option.len() < 2 {
+        bail_expr!(
+            option_expr,
+            "{} expects at least one key, e.g. `({} a b c)`",
+            kw,
+            kw
+        );
+    }
+    option[1..].iter().try_fold(vec![], |mut keys, key| {
+        key.atom(s.vars())
+            .map(|a| -> Result<()> {
+                keys.push(str_to_oscode(a).ok_or_else(|| {
+                    anyhow_expr!(key, "string of a known key is expected")
+                })?);
+                Ok(())
+            })
+            .ok_or_else(|| {
+                anyhow_expr!(key, "string of a known key is expected, found list instead")
+            })??;
+        Ok(keys)
+    })
+}