rename to tap-hold-order, add require-prior-idle support, add multi-key test, add comments

Author: tompassarelli

cfg_samples/kanata.kbd

@@ -570,6 +570,12 @@ 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-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)
+  ;; With require-prior-idle: short-circuit to tap during typing streaks
+  ;; aor2 (tap-hold-order 200 50 a lctl 150)
+
   ;; tap for capslk, hold for lctl
   cap (tap-hold 200 200 caps lctl)
 

docs/config.adoc

@@ -2018,6 +2018,7 @@ results in `$tap-action` activating.
 (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-opposite-hand $timeout $tap-action $hold-action [options...])
+(tap-hold-order $tap-repress-timeout $buffer-ms $tap-action $hold-action [$require-prior-idle-ms])
 ----
 
 [cols="1,2"]
@@ -2073,6 +2074,17 @@ This is useful for home row mods where fast typing should not trigger modifiers.
 | 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.
 See <<defhands and tap-hold-opposite-hand>> below.
+
+| `tap-hold-order`
+| Resolves purely by key release order, with no timeout.
+If the tap-hold key is released before the other key, activates `$tap-action`;
+if the other key is released first (while the tap-hold key is still held), activates `$hold-action`.
+`$buffer-ms` is a grace period after the tap-hold key is pressed during which
+release-order logic is ignored so that fast typing resolves as tap.
+Optionally, `$require-prior-idle-ms` can short-circuit to tap when a different key
+was pressed within that many milliseconds before the tap-hold key;
+`require-prior-idle` checks prior typing activity before release-order logic begins,
+whereas `buffer-ms` creates an unconditional tap-only window after the key is pressed.
 |===
 **Description**
 

keyberon/src/action.rs

@@ -67,7 +67,10 @@ pub enum HoldTapConfig<'a> {
     /// The buffer field specifies a grace period in ticks (ms) after the
     /// initial press during which release-order logic is ignored and fast
     /// typing will resolve as Tap.
-    ReleaseOrder { buffer: u16 },
+    Order {
+        buffer: u16,
+        require_prior_idle_ms: u16,
+    },
     /// If there is a press and release of another key, the hold
     /// action is activated.
     ///
@@ -107,7 +110,7 @@ impl Debug for HoldTapConfig<'_> {
         match self {
             HoldTapConfig::Default => f.write_str("Default"),
             HoldTapConfig::HoldOnOtherKeyPress => f.write_str("HoldOnOtherKeyPress"),
-            HoldTapConfig::ReleaseOrder { .. } => f.write_str("ReleaseOrder"),
+            HoldTapConfig::Order { .. } => f.write_str("Order"),
             HoldTapConfig::PermissiveHold => f.write_str("PermissiveHold"),
             HoldTapConfig::Custom(_) => f.write_str("Custom"),
         }
@@ -121,7 +124,7 @@ impl PartialEq for HoldTapConfig<'_> {
             (HoldTapConfig::Default, HoldTapConfig::Default)
             | (HoldTapConfig::HoldOnOtherKeyPress, HoldTapConfig::HoldOnOtherKeyPress)
             | (HoldTapConfig::PermissiveHold, HoldTapConfig::PermissiveHold) => true,
-            (HoldTapConfig::ReleaseOrder { .. }, HoldTapConfig::ReleaseOrder { .. }) => true,
+            (HoldTapConfig::Order { .. }, HoldTapConfig::Order { .. }) => true,
             _ => false,
         }
     }

keyberon/src/layout.rs

@@ -544,7 +544,7 @@ impl<'a, T: std::fmt::Debug> WaitingState<'a, T> {
                     return Some(WaitingAction::Hold);
                 }
             }
-            HoldTapConfig::ReleaseOrder { buffer } => {
+            HoldTapConfig::Order { buffer, .. } => {
                 // Like PermissiveHold: if another key was pressed AND released
                 // (while modifier is still held), resolve as Hold.
                 // If modifier is released first, the fallthrough below handles Tap.
@@ -555,6 +555,7 @@ impl<'a, T: std::fmt::Debug> WaitingState<'a, T> {
                 let mut queued = queued.iter();
                 while let Some(q) = queued.next() {
                     if q.event.is_press() {
+                        // Elapsed ticks since this key entered the queue, compared against buffer window.
                         let press_tick = self.ticks.saturating_sub(q.since);
                         if press_tick < buffer {
                             continue;
@@ -1869,6 +1870,30 @@ impl<'a, const C: usize, const R: usize, T: 'a + Copy + std::fmt::Debug> Layout<
                         return custom;
                     }
                 }
+                // Per-action require-prior-idle for tap-hold-order.
+                if let HoldTapConfig::Order {
+                    require_prior_idle_ms,
+                    ..
+                } = config
+                {
+                    if *require_prior_idle_ms > 0 {
+                        let prior_idle_tap = self
+                            .historical_inputs
+                            .iter_hevents()
+                            .find(|prior| {
+                                prior.event.0 == REAL_KEY_ROW && prior.event != coord
+                            })
+                            .is_some_and(|prior| {
+                                prior.ticks_since_occurrence <= *require_prior_idle_ms
+                            });
+                        if prior_idle_tap {
+                            let custom =
+                                self.do_action(tap, coord, delay, is_oneshot, layer_stack);
+                            self.last_press_tracker.update_coord(coord);
+                            return custom;
+                        }
+                    }
+                }
                 let mut custom = CustomEvent::NoEvent;
                 if *tap_hold_interval == 0
                     || coord != self.last_press_tracker.coord
@@ -2534,7 +2559,7 @@ mod test {
     }
 
     #[test]
-    fn release_order_clean_tap() {
+    fn order_clean_tap() {
         // Press and release modifier with no other keys → Tap.
         static LAYERS: Layers<2, 1> = &[[[
             HoldTap(&HoldTapAction {
@@ -2543,7 +2568,7 @@ mod test {
                 hold: k(LAlt),
                 timeout_action: k(Space),
                 tap: k(Space),
-                config: HoldTapConfig::ReleaseOrder { buffer: 0 },
+                config: HoldTapConfig::Order { buffer: 0, require_prior_idle_ms: 0 },
                 tap_hold_interval: 0,
             }),
             k(Enter),
@@ -2565,7 +2590,7 @@ mod test {
     }
 
     #[test]
-    fn release_order_hold() {
+    fn order_hold() {
         // Modifier down → other down → other up first → Hold.
         static LAYERS: Layers<2, 1> = &[[[
             HoldTap(&HoldTapAction {
@@ -2574,7 +2599,7 @@ mod test {
                 hold: k(LAlt),
                 timeout_action: k(Space),
                 tap: k(Space),
-                config: HoldTapConfig::ReleaseOrder { buffer: 0 },
+                config: HoldTapConfig::Order { buffer: 0, require_prior_idle_ms: 0 },
                 tap_hold_interval: 0,
             }),
             k(Enter),
@@ -2602,7 +2627,7 @@ mod test {
     }
 
     #[test]
-    fn release_order_tap() {
+    fn order_tap() {
         // Modifier down → other down → modifier up first → Tap.
         static LAYERS: Layers<2, 1> = &[[[
             HoldTap(&HoldTapAction {
@@ -2611,7 +2636,7 @@ mod test {
                 hold: k(LAlt),
                 timeout_action: k(Space),
                 tap: k(Space),
-                config: HoldTapConfig::ReleaseOrder { buffer: 0 },
+                config: HoldTapConfig::Order { buffer: 0, require_prior_idle_ms: 0 },
                 tap_hold_interval: 0,
             }),
             k(Enter),
@@ -2632,6 +2657,58 @@ mod test {
         assert_keys(&[Space, Enter], layout.keycodes());
     }
 
+    #[test]
+    fn order_multi_key_hold() {
+        // TH down → A down → B down → A up (while B still held) → TH up.
+        // A's press+release cycle completes while TH is held → Hold.
+        static LAYERS: Layers<3, 1> = &[[[
+            HoldTap(&HoldTapAction {
+                on_press_reset_timeout_to: None,
+                timeout: u16::MAX,
+                hold: k(LAlt),
+                timeout_action: k(Space),
+                tap: k(Space),
+                config: HoldTapConfig::Order { buffer: 0, require_prior_idle_ms: 0 },
+                tap_hold_interval: 0,
+            }),
+            k(Enter),
+            k(Tab),
+        ]]];
+        let mut layout = Layout::new(LAYERS);
+
+        // TH down
+        layout.event(Press(0, 0));
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[], layout.keycodes());
+        // A down
+        layout.event(Press(0, 1));
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[], layout.keycodes());
+        // B down
+        layout.event(Press(0, 2));
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[], layout.keycodes());
+        // A up — A's press+release cycle is complete → Hold resolves
+        layout.event(Release(0, 1));
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[LAlt], layout.keycodes());
+        // Queued keys replay: Enter press, Tab press, Enter release
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[LAlt, Enter], layout.keycodes());
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[LAlt, Enter, Tab], layout.keycodes());
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[LAlt, Tab], layout.keycodes());
+        // Release B
+        layout.event(Release(0, 2));
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[LAlt], layout.keycodes());
+        // Release TH
+        layout.event(Release(0, 0));
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[], layout.keycodes());
+    }
+
     #[test]
     fn permissive_hold() {
         static LAYERS: Layers<2, 1> = &[[[

parser/src/cfg/list_actions.rs

@@ -136,7 +136,7 @@ pub const CLIPBOARD_RESTORE: &str = "clipboard-restore";
 pub const CLIPBOARD_SAVE_SET: &str = "clipboard-save-set";
 pub const CLIPBOARD_SAVE_CMD_SET: &str = "clipboard-save-cmd-set";
 pub const CLIPBOARD_SAVE_SWAP: &str = "clipboard-save-swap";
-pub const TAP_HOLD_RELEASE_ORDER: &str = "tap-hold-release-order";
+pub const TAP_HOLD_ORDER: &str = "tap-hold-order";
 pub const TAP_HOLD_OPPOSITE_HAND: &str = "tap-hold-opposite-hand";
 
 pub fn is_list_action(ac: &str) -> bool {
@@ -273,7 +273,7 @@ pub fn is_list_action(ac: &str) -> bool {
         CLIPBOARD_SAVE_SET,
         CLIPBOARD_SAVE_CMD_SET,
         CLIPBOARD_SAVE_SWAP,
-        TAP_HOLD_RELEASE_ORDER,
+        TAP_HOLD_ORDER,
         TAP_HOLD_OPPOSITE_HAND,
     ];
     LIST_ACTIONS.contains(&ac)

parser/src/cfg/mod.rs

@@ -1508,7 +1508,7 @@ fn parse_action_list(ac: &[SExpr], s: &ParserState) -> Result<&'static KanataAct
         TAP_HOLD_PRESS | TAP_HOLD_PRESS_A => {
             parse_tap_hold(&ac[1..], s, HoldTapConfig::HoldOnOtherKeyPress)
         }
-        TAP_HOLD_RELEASE_ORDER => parse_tap_hold_release_order(&ac[1..], s),
+        TAP_HOLD_ORDER => parse_tap_hold_order(&ac[1..], s),
         TAP_HOLD_RELEASE | TAP_HOLD_RELEASE_A => {
             parse_tap_hold(&ac[1..], s, HoldTapConfig::PermissiveHold)
         }

parser/src/cfg/tap_hold.rs

@@ -94,29 +94,37 @@ pub(crate) fn parse_tap_hold_timeout(
     }))))
 }
 
-pub(crate) fn parse_tap_hold_release_order(
+pub(crate) fn parse_tap_hold_order(
     ac_params: &[SExpr],
     s: &ParserState,
 ) -> Result<&'static KanataAction> {
-    if ac_params.len() != 4 {
+    if ac_params.len() != 4 && ac_params.len() != 5 {
         bail!(
-            r"tap-hold-release-order expects 4 items after it, got {}.
+            r"tap-hold-order expects 4-5 items after it, got {}.
 Params in order:
-<tap-repress-timeout> <buffer-ms> <tap-action> <hold-action>",
+<tap-repress-timeout> <buffer-ms> <tap-action> <hold-action> [require-prior-idle-ms]",
             ac_params.len(),
         )
     }
     let tap_repress_timeout = parse_u16(&ac_params[0], s, "tap repress timeout")?;
     let buffer = parse_u16(&ac_params[1], s, "buffer")?;
     let tap_action = parse_action(&ac_params[2], s)?;
     let hold_action = parse_action(&ac_params[3], s)?;
+    let require_prior_idle_ms = if ac_params.len() == 5 {
+        parse_u16(&ac_params[4], s, "require-prior-idle-ms")?
+    } else {
+        0
+    };
     if matches!(tap_action, Action::HoldTap { .. }) {
         bail!("tap-hold does not work in the tap-action of tap-hold")
     }
     Ok(s.a.sref(Action::HoldTap(s.a.sref(HoldTapAction {
-        config: HoldTapConfig::ReleaseOrder { buffer },
+        config: HoldTapConfig::Order {
+            buffer,
+            require_prior_idle_ms,
+        },
         tap_hold_interval: tap_repress_timeout,
-        timeout: u16::MAX,
+        timeout: u16::MAX, // Resolution is purely event-driven, not timeout-based.
         tap: *tap_action,
         hold: *hold_action,
         timeout_action: *tap_action,