feat: hold/tap flavor tap-unless-interrupted

Implements new hold/tap flavor, tap-unless-interrupted Adds tests Adds docs
2021-11-06 21:31:23 +00:00 · 2021-11-06 21:31:23 +00:00 · 4e62319982
commit 4e62319982
parent f2e0642291
40 changed files with 415 additions and 3 deletions
--- a/app/dts/bindings/behaviors/zmk,behavior-hold-tap.yaml
+++ b/app/dts/bindings/behaviors/zmk,behavior-hold-tap.yaml
@ -28,6 +28,7 @@ properties:
      - "hold-preferred"
      - "balanced"
      - "tap-preferred"
+      - "tap-unless-interrupted"
  retro-tap:
    type: boolean
  hold-trigger-key-positions:
--- a/app/src/behaviors/behavior_hold_tap.c
+++ b/app/src/behaviors/behavior_hold_tap.c
@ -34,6 +34,7 @@ enum flavor {
    FLAVOR_HOLD_PREFERRED,
    FLAVOR_BALANCED,
    FLAVOR_TAP_PREFERRED,
+    FLAVOR_TAP_UNLESS_INTERRUPTED,
 };

 enum status {
@ -258,6 +259,26 @@ static void decide_tap_preferred(struct active_hold_tap *hold_tap, enum decision
    }
 }

+static void decide_tap_unless_interrupted(struct active_hold_tap *hold_tap,
+                                          enum decision_moment event) {
+    switch (event) {
+    case HT_KEY_UP:
+        hold_tap->status = STATUS_TAP;
+        return;
+    case HT_OTHER_KEY_DOWN:
+        hold_tap->status = STATUS_HOLD_INTERRUPT;
+        return;
+    case HT_TIMER_EVENT:
+        hold_tap->status = STATUS_TAP;
+        return;
+    case HT_QUICK_TAP:
+        hold_tap->status = STATUS_TAP;
+        return;
+    default:
+        return;
+    }
+}
+
 static void decide_hold_preferred(struct active_hold_tap *hold_tap, enum decision_moment event) {
    switch (event) {
    case HT_KEY_UP:
@ -285,6 +306,8 @@ static inline const char *flavor_str(enum flavor flavor) {
        return "balanced";
    case FLAVOR_TAP_PREFERRED:
        return "tap-preferred";
+    case FLAVOR_TAP_UNLESS_INTERRUPTED:
+        return "tap-unless-interrupted";
    default:
        return "UNKNOWN FLAVOR";
    }
@ -420,6 +443,9 @@ static void decide_hold_tap(struct active_hold_tap *hold_tap,
    case FLAVOR_TAP_PREFERRED:
        decide_tap_preferred(hold_tap, decision_moment);
        break;
+    case FLAVOR_TAP_UNLESS_INTERRUPTED:
+        decide_tap_unless_interrupted(hold_tap, decision_moment);
+        break;
    }

    if (hold_tap->status == STATUS_UNDECIDED) {
--- a/app/tests/hold-tap/tap-unless-interrupted/1-dn-up/events.patterns
+++ b/app/tests/hold-tap/tap-unless-interrupted/1-dn-up/events.patterns
@ -0,0 +1,4 @@
+s/.*hid_listener_keycode/kp/p
+s/.*mo_keymap_binding/mo/p
+s/.*on_hold_tap_binding/ht_binding/p
+s/.*decide_hold_tap/ht_decide/p
--- a/app/tests/hold-tap/tap-unless-interrupted/1-dn-up/keycode_events.snapshot
+++ b/app/tests/hold-tap/tap-unless-interrupted/1-dn-up/keycode_events.snapshot
@ -0,0 +1,5 @@
+ht_binding_pressed: 0 new undecided hold_tap
+ht_decide: 0 decided tap (tap-unless-interrupted decision moment key-up)
+kp_pressed: usage_page 0x07 keycode 0x09 implicit_mods 0x00 explicit_mods 0x00
+kp_released: usage_page 0x07 keycode 0x09 implicit_mods 0x00 explicit_mods 0x00
+ht_binding_released: 0 cleaning up hold-tap
--- a/app/tests/hold-tap/tap-unless-interrupted/1-dn-up/native_posix.keymap
+++ b/app/tests/hold-tap/tap-unless-interrupted/1-dn-up/native_posix.keymap
@ -0,0 +1,11 @@
+#include <dt-bindings/zmk/keys.h>
+#include <behaviors.dtsi>
+#include <dt-bindings/zmk/kscan_mock.h>
+#include "../behavior_keymap.dtsi"
+
+&kscan {
+	events = <
+		ZMK_MOCK_PRESS(0,0,10) 
+		ZMK_MOCK_RELEASE(0,0,10) 
+	>;
+};
--- a/app/tests/hold-tap/tap-unless-interrupted/2-dn-timer-up/events.patterns
+++ b/app/tests/hold-tap/tap-unless-interrupted/2-dn-timer-up/events.patterns
@ -0,0 +1,4 @@
+s/.*hid_listener_keycode/kp/p
+s/.*mo_keymap_binding/mo/p
+s/.*on_hold_tap_binding/ht_binding/p
+s/.*decide_hold_tap/ht_decide/p
--- a/app/tests/hold-tap/tap-unless-interrupted/2-dn-timer-up/keycode_events.snapshot
+++ b/app/tests/hold-tap/tap-unless-interrupted/2-dn-timer-up/keycode_events.snapshot
@ -0,0 +1,5 @@
+ht_binding_pressed: 0 new undecided hold_tap
+ht_decide: 0 decided tap (tap-unless-interrupted decision moment timer)
+kp_pressed: usage_page 0x07 keycode 0x09 implicit_mods 0x00 explicit_mods 0x00
+kp_released: usage_page 0x07 keycode 0x09 implicit_mods 0x00 explicit_mods 0x00
+ht_binding_released: 0 cleaning up hold-tap
--- a/app/tests/hold-tap/tap-unless-interrupted/2-dn-timer-up/native_posix.keymap
+++ b/app/tests/hold-tap/tap-unless-interrupted/2-dn-timer-up/native_posix.keymap
@ -0,0 +1,11 @@
+#include <dt-bindings/zmk/keys.h>
+#include <behaviors.dtsi>
+#include <dt-bindings/zmk/kscan_mock.h>
+#include "../behavior_keymap.dtsi"
+
+&kscan {
+	events = <
+		ZMK_MOCK_PRESS(0,0,500) 
+		ZMK_MOCK_RELEASE(0,0,10) 
+	>;
+};
--- a/app/tests/hold-tap/tap-unless-interrupted/3a-moddn-dn-modup-up/events.patterns
+++ b/app/tests/hold-tap/tap-unless-interrupted/3a-moddn-dn-modup-up/events.patterns
@ -0,0 +1,4 @@
+s/.*hid_listener_keycode/kp/p
+s/.*mo_keymap_binding/mo/p
+s/.*on_hold_tap_binding/ht_binding/p
+s/.*decide_hold_tap/ht_decide/p
--- a/app/tests/hold-tap/tap-unless-interrupted/3a-moddn-dn-modup-up/keycode_events.snapshot
+++ b/app/tests/hold-tap/tap-unless-interrupted/3a-moddn-dn-modup-up/keycode_events.snapshot
@ -0,0 +1,7 @@
+kp_pressed: usage_page 0x07 keycode 0xe4 implicit_mods 0x00 explicit_mods 0x00
+ht_binding_pressed: 0 new undecided hold_tap
+ht_decide: 0 decided tap (tap-unless-interrupted decision moment key-up)
+kp_pressed: usage_page 0x07 keycode 0x09 implicit_mods 0x00 explicit_mods 0x00
+kp_released: usage_page 0x07 keycode 0xe4 implicit_mods 0x00 explicit_mods 0x00
+kp_released: usage_page 0x07 keycode 0x09 implicit_mods 0x00 explicit_mods 0x00
+ht_binding_released: 0 cleaning up hold-tap
--- a/app/tests/hold-tap/tap-unless-interrupted/3a-moddn-dn-modup-up/native_posix.keymap
+++ b/app/tests/hold-tap/tap-unless-interrupted/3a-moddn-dn-modup-up/native_posix.keymap
@ -0,0 +1,13 @@
+#include <dt-bindings/zmk/keys.h>
+#include <behaviors.dtsi>
+#include <dt-bindings/zmk/kscan_mock.h>
+#include "../behavior_keymap.dtsi"
+
+&kscan {
+	events = <
+		ZMK_MOCK_PRESS(1,1,10) /*ctrl*/
+		ZMK_MOCK_PRESS(0,0,100)  /*mt f-shift */
+		ZMK_MOCK_RELEASE(1,1,10)
+		ZMK_MOCK_RELEASE(0,0,10) 
+	>;
+};
--- a/app/tests/hold-tap/tap-unless-interrupted/3b-moddn-dn-modup-timer-up/events.patterns
+++ b/app/tests/hold-tap/tap-unless-interrupted/3b-moddn-dn-modup-timer-up/events.patterns
@ -0,0 +1,4 @@
+s/.*hid_listener_keycode/kp/p
+s/.*mo_keymap_binding/mo/p
+s/.*on_hold_tap_binding/ht_binding/p
+s/.*decide_hold_tap/ht_decide/p
--- a/app/tests/hold-tap/tap-unless-interrupted/3b-moddn-dn-modup-timer-up/keycode_events.snapshot
+++ b/app/tests/hold-tap/tap-unless-interrupted/3b-moddn-dn-modup-timer-up/keycode_events.snapshot
@ -0,0 +1,7 @@
+kp_pressed: usage_page 0x07 keycode 0xe4 implicit_mods 0x00 explicit_mods 0x00
+ht_binding_pressed: 0 new undecided hold_tap
+ht_decide: 0 decided tap (tap-unless-interrupted decision moment timer)
+kp_pressed: usage_page 0x07 keycode 0x09 implicit_mods 0x00 explicit_mods 0x00
+kp_released: usage_page 0x07 keycode 0xe4 implicit_mods 0x00 explicit_mods 0x00
+kp_released: usage_page 0x07 keycode 0x09 implicit_mods 0x00 explicit_mods 0x00
+ht_binding_released: 0 cleaning up hold-tap
--- a/app/tests/hold-tap/tap-unless-interrupted/3b-moddn-dn-modup-timer-up/native_posix.keymap
+++ b/app/tests/hold-tap/tap-unless-interrupted/3b-moddn-dn-modup-timer-up/native_posix.keymap
@ -0,0 +1,14 @@
+#include <dt-bindings/zmk/keys.h>
+#include <behaviors.dtsi>
+#include <dt-bindings/zmk/kscan_mock.h>
+#include "../behavior_keymap.dtsi"
+
+&kscan {
+	events = <
+		ZMK_MOCK_PRESS(1,1,10) /*ctrl*/
+		ZMK_MOCK_PRESS(0,0,50)  /*mt f-shift */
+		ZMK_MOCK_RELEASE(1,1,300)
+		/*timer*/
+		ZMK_MOCK_RELEASE(0,0,10) 
+	>;
+};
--- a/app/tests/hold-tap/tap-unless-interrupted/3c-kcdn-dn-kcup-up/events.patterns
+++ b/app/tests/hold-tap/tap-unless-interrupted/3c-kcdn-dn-kcup-up/events.patterns
@ -0,0 +1,4 @@
+s/.*hid_listener_keycode/kp/p
+s/.*mo_keymap_binding/mo/p
+s/.*on_hold_tap_binding/ht_binding/p
+s/.*decide_hold_tap/ht_decide/p
--- a/app/tests/hold-tap/tap-unless-interrupted/3c-kcdn-dn-kcup-up/keycode_events.snapshot
+++ b/app/tests/hold-tap/tap-unless-interrupted/3c-kcdn-dn-kcup-up/keycode_events.snapshot
@ -0,0 +1,7 @@
+kp_pressed: usage_page 0x07 keycode 0x07 implicit_mods 0x00 explicit_mods 0x00
+ht_binding_pressed: 0 new undecided hold_tap
+kp_released: usage_page 0x07 keycode 0x07 implicit_mods 0x00 explicit_mods 0x00
+ht_decide: 0 decided tap (tap-unless-interrupted decision moment key-up)
+kp_pressed: usage_page 0x07 keycode 0x09 implicit_mods 0x00 explicit_mods 0x00
+kp_released: usage_page 0x07 keycode 0x09 implicit_mods 0x00 explicit_mods 0x00
+ht_binding_released: 0 cleaning up hold-tap
--- a/app/tests/hold-tap/tap-unless-interrupted/3c-kcdn-dn-kcup-up/native_posix.keymap
+++ b/app/tests/hold-tap/tap-unless-interrupted/3c-kcdn-dn-kcup-up/native_posix.keymap
@ -0,0 +1,13 @@
+#include <dt-bindings/zmk/keys.h>
+#include <behaviors.dtsi>
+#include <dt-bindings/zmk/kscan_mock.h>
+#include "../behavior_keymap.dtsi"
+
+&kscan {
+	events = <
+		ZMK_MOCK_PRESS(1,0,10) /*d*/
+		ZMK_MOCK_PRESS(0,0,100)  /*mt f-shift */
+		ZMK_MOCK_RELEASE(1,0,10)
+		ZMK_MOCK_RELEASE(0,0,10) 
+	>;
+};
--- a/app/tests/hold-tap/tap-unless-interrupted/3d-kcdn-dn-kcup-timer-up/events.patterns
+++ b/app/tests/hold-tap/tap-unless-interrupted/3d-kcdn-dn-kcup-timer-up/events.patterns
@ -0,0 +1,4 @@
+s/.*hid_listener_keycode/kp/p
+s/.*mo_keymap_binding/mo/p
+s/.*on_hold_tap_binding/ht_binding/p
+s/.*decide_hold_tap/ht_decide/p
--- a/app/tests/hold-tap/tap-unless-interrupted/3d-kcdn-dn-kcup-timer-up/keycode_events.snapshot
+++ b/app/tests/hold-tap/tap-unless-interrupted/3d-kcdn-dn-kcup-timer-up/keycode_events.snapshot
@ -0,0 +1,7 @@
+kp_pressed: usage_page 0x07 keycode 0x07 implicit_mods 0x00 explicit_mods 0x00
+ht_binding_pressed: 0 new undecided hold_tap
+kp_released: usage_page 0x07 keycode 0x07 implicit_mods 0x00 explicit_mods 0x00
+ht_decide: 0 decided tap (tap-unless-interrupted decision moment timer)
+kp_pressed: usage_page 0x07 keycode 0x09 implicit_mods 0x00 explicit_mods 0x00
+kp_released: usage_page 0x07 keycode 0x09 implicit_mods 0x00 explicit_mods 0x00
+ht_binding_released: 0 cleaning up hold-tap
--- a/app/tests/hold-tap/tap-unless-interrupted/3d-kcdn-dn-kcup-timer-up/native_posix.keymap
+++ b/app/tests/hold-tap/tap-unless-interrupted/3d-kcdn-dn-kcup-timer-up/native_posix.keymap
@ -0,0 +1,13 @@
+#include <dt-bindings/zmk/keys.h>
+#include <behaviors.dtsi>
+#include <dt-bindings/zmk/kscan_mock.h>
+#include "../behavior_keymap.dtsi"
+
+&kscan {
+	events = <
+		ZMK_MOCK_PRESS(1,0,10) /* d */
+		ZMK_MOCK_PRESS(0,0,100) /* mt f-shift */
+		ZMK_MOCK_RELEASE(1,0,400)
+		ZMK_MOCK_RELEASE(0,0,10) 
+	>;
+};
--- a/app/tests/hold-tap/tap-unless-interrupted/4a-dn-htdn-timer-htup-up/events.patterns
+++ b/app/tests/hold-tap/tap-unless-interrupted/4a-dn-htdn-timer-htup-up/events.patterns
@ -0,0 +1,4 @@
+s/.*hid_listener_keycode/kp/p
+s/.*mo_keymap_binding/mo/p
+s/.*on_hold_tap_binding/ht_binding/p
+s/.*decide_hold_tap/ht_decide/p
--- a/app/tests/hold-tap/tap-unless-interrupted/4a-dn-htdn-timer-htup-up/keycode_events.snapshot
+++ b/app/tests/hold-tap/tap-unless-interrupted/4a-dn-htdn-timer-htup-up/keycode_events.snapshot
@ -0,0 +1,10 @@
+ht_binding_pressed: 0 new undecided hold_tap
+ht_decide: 0 decided hold-interrupt (tap-unless-interrupted decision moment other-key-down)
+kp_pressed: usage_page 0x07 keycode 0xe1 implicit_mods 0x00 explicit_mods 0x00
+ht_binding_pressed: 1 new undecided hold_tap
+ht_decide: 1 decided tap (tap-unless-interrupted decision moment key-up)
+kp_pressed: usage_page 0x07 keycode 0x0d implicit_mods 0x00 explicit_mods 0x00
+kp_released: usage_page 0x07 keycode 0x0d implicit_mods 0x00 explicit_mods 0x00
+ht_binding_released: 1 cleaning up hold-tap
+kp_released: usage_page 0x07 keycode 0xe1 implicit_mods 0x00 explicit_mods 0x00
+ht_binding_released: 0 cleaning up hold-tap
--- a/app/tests/hold-tap/tap-unless-interrupted/4a-dn-htdn-timer-htup-up/native_posix.keymap
+++ b/app/tests/hold-tap/tap-unless-interrupted/4a-dn-htdn-timer-htup-up/native_posix.keymap
@ -0,0 +1,14 @@
+#include <dt-bindings/zmk/keys.h>
+#include <behaviors.dtsi>
+#include <dt-bindings/zmk/kscan_mock.h>
+#include "../behavior_keymap.dtsi"
+
+&kscan {
+	events = <
+		ZMK_MOCK_PRESS(0,0,200)
+		ZMK_MOCK_PRESS(0,1,200)
+		/* timer fires */ 
+		ZMK_MOCK_RELEASE(0,1,10)
+		ZMK_MOCK_RELEASE(0,0,10)
+	>;
+};
--- a/app/tests/hold-tap/tap-unless-interrupted/4a-dn-kcdn-timer-kcup-up/events.patterns
+++ b/app/tests/hold-tap/tap-unless-interrupted/4a-dn-kcdn-timer-kcup-up/events.patterns
@ -0,0 +1,4 @@
+s/.*hid_listener_keycode/kp/p
+s/.*mo_keymap_binding/mo/p
+s/.*on_hold_tap_binding/ht_binding/p
+s/.*decide_hold_tap/ht_decide/p
--- a/app/tests/hold-tap/tap-unless-interrupted/4a-dn-kcdn-timer-kcup-up/keycode_events.snapshot
+++ b/app/tests/hold-tap/tap-unless-interrupted/4a-dn-kcdn-timer-kcup-up/keycode_events.snapshot
@ -0,0 +1,7 @@
+ht_binding_pressed: 0 new undecided hold_tap
+ht_decide: 0 decided hold-interrupt (tap-unless-interrupted decision moment other-key-down)
+kp_pressed: usage_page 0x07 keycode 0xe1 implicit_mods 0x00 explicit_mods 0x00
+kp_pressed: usage_page 0x07 keycode 0x07 implicit_mods 0x00 explicit_mods 0x00
+kp_released: usage_page 0x07 keycode 0x07 implicit_mods 0x00 explicit_mods 0x00
+kp_released: usage_page 0x07 keycode 0xe1 implicit_mods 0x00 explicit_mods 0x00
+ht_binding_released: 0 cleaning up hold-tap
--- a/app/tests/hold-tap/tap-unless-interrupted/4a-dn-kcdn-timer-kcup-up/native_posix.keymap
+++ b/app/tests/hold-tap/tap-unless-interrupted/4a-dn-kcdn-timer-kcup-up/native_posix.keymap
@ -0,0 +1,14 @@
+#include <dt-bindings/zmk/keys.h>
+#include <behaviors.dtsi>
+#include <dt-bindings/zmk/kscan_mock.h>
+#include "../behavior_keymap.dtsi"
+
+&kscan {
+	events = <
+		ZMK_MOCK_PRESS(0,0,200)
+		ZMK_MOCK_PRESS(1,0,200)
+		/* timer fires */ 
+		ZMK_MOCK_RELEASE(1,0,10)
+		ZMK_MOCK_RELEASE(0,0,10)
+	>;
+};
--- a/app/tests/hold-tap/tap-unless-interrupted/4b-dn-kcdn-kcup-timer-up/events.patterns
+++ b/app/tests/hold-tap/tap-unless-interrupted/4b-dn-kcdn-kcup-timer-up/events.patterns
@ -0,0 +1,4 @@
+s/.*hid_listener_keycode/kp/p
+s/.*mo_keymap_binding/mo/p
+s/.*on_hold_tap_binding/ht_binding/p
+s/.*decide_hold_tap/ht_decide/p
--- a/app/tests/hold-tap/tap-unless-interrupted/4b-dn-kcdn-kcup-timer-up/keycode_events.snapshot
+++ b/app/tests/hold-tap/tap-unless-interrupted/4b-dn-kcdn-kcup-timer-up/keycode_events.snapshot
@ -0,0 +1,7 @@
+ht_binding_pressed: 0 new undecided hold_tap
+ht_decide: 0 decided hold-interrupt (tap-unless-interrupted decision moment other-key-down)
+kp_pressed: usage_page 0x07 keycode 0xe1 implicit_mods 0x00 explicit_mods 0x00
+kp_pressed: usage_page 0x07 keycode 0x07 implicit_mods 0x00 explicit_mods 0x00
+kp_released: usage_page 0x07 keycode 0x07 implicit_mods 0x00 explicit_mods 0x00
+kp_released: usage_page 0x07 keycode 0xe1 implicit_mods 0x00 explicit_mods 0x00
+ht_binding_released: 0 cleaning up hold-tap
--- a/app/tests/hold-tap/tap-unless-interrupted/4b-dn-kcdn-kcup-timer-up/native_posix.keymap
+++ b/app/tests/hold-tap/tap-unless-interrupted/4b-dn-kcdn-kcup-timer-up/native_posix.keymap
@ -0,0 +1,14 @@
+#include <dt-bindings/zmk/keys.h>
+#include <behaviors.dtsi>
+#include <dt-bindings/zmk/kscan_mock.h>
+#include "../behavior_keymap.dtsi"
+
+&kscan {
+	events = <
+		ZMK_MOCK_PRESS(0,0,100)
+		ZMK_MOCK_PRESS(1,0,100)
+		ZMK_MOCK_RELEASE(1,0,200)
+		/* timer fires */ 
+		ZMK_MOCK_RELEASE(0,0,10)
+	>;
+};
--- a/app/tests/hold-tap/tap-unless-interrupted/4c-dn-kcdn-kcup-up/events.patterns
+++ b/app/tests/hold-tap/tap-unless-interrupted/4c-dn-kcdn-kcup-up/events.patterns
@ -0,0 +1,4 @@
+s/.*hid_listener_keycode/kp/p
+s/.*mo_keymap_binding/mo/p
+s/.*on_hold_tap_binding/ht_binding/p
+s/.*decide_hold_tap/ht_decide/p
--- a/app/tests/hold-tap/tap-unless-interrupted/4c-dn-kcdn-kcup-up/keycode_events.snapshot
+++ b/app/tests/hold-tap/tap-unless-interrupted/4c-dn-kcdn-kcup-up/keycode_events.snapshot
@ -0,0 +1,7 @@
+ht_binding_pressed: 0 new undecided hold_tap
+ht_decide: 0 decided hold-interrupt (tap-unless-interrupted decision moment other-key-down)
+kp_pressed: usage_page 0x07 keycode 0xe1 implicit_mods 0x00 explicit_mods 0x00
+kp_pressed: usage_page 0x07 keycode 0x07 implicit_mods 0x00 explicit_mods 0x00
+kp_released: usage_page 0x07 keycode 0x07 implicit_mods 0x00 explicit_mods 0x00
+kp_released: usage_page 0x07 keycode 0xe1 implicit_mods 0x00 explicit_mods 0x00
+ht_binding_released: 0 cleaning up hold-tap
--- a/app/tests/hold-tap/tap-unless-interrupted/4c-dn-kcdn-kcup-up/native_posix.keymap
+++ b/app/tests/hold-tap/tap-unless-interrupted/4c-dn-kcdn-kcup-up/native_posix.keymap
@ -0,0 +1,14 @@
+#include <dt-bindings/zmk/keys.h>
+#include <behaviors.dtsi>
+#include <dt-bindings/zmk/kscan_mock.h>
+#include "../behavior_keymap.dtsi"
+
+&kscan {
+	events = <
+		ZMK_MOCK_PRESS(0,0,10)
+		ZMK_MOCK_PRESS(1,0,10)
+		ZMK_MOCK_RELEASE(1,0,10)
+		ZMK_MOCK_RELEASE(0,0,10)
+		/* timer */ 
+	>;
+};
--- a/app/tests/hold-tap/tap-unless-interrupted/4d-dn-kcdn-timer-up-kcup/events.patterns
+++ b/app/tests/hold-tap/tap-unless-interrupted/4d-dn-kcdn-timer-up-kcup/events.patterns
@ -0,0 +1,4 @@
+s/.*hid_listener_keycode/kp/p
+s/.*mo_keymap_binding/mo/p
+s/.*on_hold_tap_binding/ht_binding/p
+s/.*decide_hold_tap/ht_decide/p
--- a/app/tests/hold-tap/tap-unless-interrupted/4d-dn-kcdn-timer-up-kcup/keycode_events.snapshot
+++ b/app/tests/hold-tap/tap-unless-interrupted/4d-dn-kcdn-timer-up-kcup/keycode_events.snapshot
@ -0,0 +1,7 @@
+ht_binding_pressed: 0 new undecided hold_tap
+ht_decide: 0 decided hold-interrupt (tap-unless-interrupted decision moment other-key-down)
+kp_pressed: usage_page 0x07 keycode 0xe1 implicit_mods 0x00 explicit_mods 0x00
+kp_pressed: usage_page 0x07 keycode 0x07 implicit_mods 0x00 explicit_mods 0x00
+kp_released: usage_page 0x07 keycode 0xe1 implicit_mods 0x00 explicit_mods 0x00
+ht_binding_released: 0 cleaning up hold-tap
+kp_released: usage_page 0x07 keycode 0x07 implicit_mods 0x00 explicit_mods 0x00
--- a/app/tests/hold-tap/tap-unless-interrupted/4d-dn-kcdn-timer-up-kcup/native_posix.keymap
+++ b/app/tests/hold-tap/tap-unless-interrupted/4d-dn-kcdn-timer-up-kcup/native_posix.keymap
@ -0,0 +1,14 @@
+#include <dt-bindings/zmk/keys.h>
+#include <behaviors.dtsi>
+#include <dt-bindings/zmk/kscan_mock.h>
+#include "../behavior_keymap.dtsi"
+
+&kscan {
+	events = <
+		ZMK_MOCK_PRESS(0,0,100)
+		ZMK_MOCK_PRESS(1,0,100)
+		ZMK_MOCK_RELEASE(0,0,200)
+		/* timer fires */
+		ZMK_MOCK_RELEASE(1,0,10)
+	>;
+};
--- a/app/tests/hold-tap/tap-unless-interrupted/5-quick-tap/events.patterns
+++ b/app/tests/hold-tap/tap-unless-interrupted/5-quick-tap/events.patterns
@ -0,0 +1,4 @@
+s/.*hid_listener_keycode/kp/p
+s/.*mo_keymap_binding/mo/p
+s/.*on_hold_tap_binding/ht_binding/p
+s/.*decide_hold_tap/ht_decide/p
--- a/app/tests/hold-tap/tap-unless-interrupted/5-quick-tap/keycode_events.snapshot
+++ b/app/tests/hold-tap/tap-unless-interrupted/5-quick-tap/keycode_events.snapshot
@ -0,0 +1,10 @@
+ht_binding_pressed: 0 new undecided hold_tap
+ht_decide: 0 decided tap (tap-unless-interrupted decision moment key-up)
+kp_pressed: usage_page 0x07 keycode 0x09 implicit_mods 0x00 explicit_mods 0x00
+kp_released: usage_page 0x07 keycode 0x09 implicit_mods 0x00 explicit_mods 0x00
+ht_binding_released: 0 cleaning up hold-tap
+ht_binding_pressed: 0 new undecided hold_tap
+ht_decide: 0 decided tap (tap-unless-interrupted decision moment quick-tap)
+kp_pressed: usage_page 0x07 keycode 0x09 implicit_mods 0x00 explicit_mods 0x00
+kp_released: usage_page 0x07 keycode 0x09 implicit_mods 0x00 explicit_mods 0x00
+ht_binding_released: 0 cleaning up hold-tap
--- a/app/tests/hold-tap/tap-unless-interrupted/5-quick-tap/native_posix.keymap
+++ b/app/tests/hold-tap/tap-unless-interrupted/5-quick-tap/native_posix.keymap
@ -0,0 +1,14 @@
+#include <dt-bindings/zmk/keys.h>
+#include <behaviors.dtsi>
+#include <dt-bindings/zmk/kscan_mock.h>
+#include "../behavior_keymap.dtsi"
+
+
+&kscan {
+	events = <
+		ZMK_MOCK_PRESS(0,0,10) 
+		ZMK_MOCK_RELEASE(0,0,10) 
+		ZMK_MOCK_PRESS(0,0,400)
+		ZMK_MOCK_RELEASE(0,0,10) 
+	>;
+};
--- a/app/tests/hold-tap/tap-unless-interrupted/behavior_keymap.dtsi
+++ b/app/tests/hold-tap/tap-unless-interrupted/behavior_keymap.dtsi
@ -0,0 +1,30 @@
+#include <dt-bindings/zmk/keys.h>
+#include <behaviors.dtsi>
+#include <dt-bindings/zmk/kscan_mock.h>
+
+
+
+/ {
+	behaviors {
+		ht_tui: behavior_hold_tap_tap_unless_interrupted {
+			compatible = "zmk,behavior-hold-tap";
+			label = "hold_tap_tap_unless_interrupted";
+			#binding-cells = <2>;
+			flavor = "tap-unless-interrupted";
+			tapping-term-ms = <300>;
+			quick-tap-ms = <200>;
+			bindings = <&kp>, <&kp>;
+		};
+	};
+
+	keymap {
+		compatible = "zmk,keymap";
+		label ="Default keymap";
+
+		default_layer {
+			bindings = <
+				&ht_tui LEFT_SHIFT F      &ht_tui LEFT_CONTROL J
+				&kp D      &kp RIGHT_CONTROL>;
+		};
+	};
+};
--- a/docs/docs/behaviors/hold-tap.md
+++ b/docs/docs/behaviors/hold-tap.md
@ -26,6 +26,7 @@ We call this the 'hold-preferred' flavor of hold-taps. While this flavor may wor
 - The 'hold-preferred' flavor triggers the hold behavior when the `tapping-term-ms` has expired or another key is pressed.
 - The 'balanced' flavor will trigger the hold behavior when the `tapping-term-ms` has expired or another key is pressed and released.
 - The 'tap-preferred' flavor triggers the hold behavior when the `tapping-term-ms` has expired. It triggers the tap behavior when another key is pressed.
+- The 'tap-unless-interrupted' flavor triggers a hold behavior only when another key is pressed before `tapping-term-ms` has expired. It triggers the tap behavior in all other situations.

 When the hold-tap key is released and the hold behavior has not been triggered, the tap behavior will trigger.

@ -103,7 +104,40 @@ For example, if you press `&mt LEFT_SHIFT A` and then release it without pressin

 #### Home row mods

-This example configures a hold-tap that works well for homerow mods:
+The following are suggested hold-tap configurations that work well with home row mods:
+
+##### Option 1: cross-hand only modifiers, using `tap-unless-interrupted` and positional hold-tap (`hold-trigger-key-positions`)
+
+```
+#include <dt-bindings/zmk/keys.h>
+#include <behaviors.dtsi>
+/ {
+	behaviors {
+		lh_pht: left_hand_positional_hold_tap {
+			compatible = "zmk,behavior-hold-tap";
+			label = "POSITIONAL_HOLD_TAP";
+			#binding-cells = <2>;
+			flavor = "tap-unless-interrupted";
+			tapping-term-ms = <100>;                        // <---[[produces tap if held longer than tapping-term-ms]]
+			quick-tap-ms = <200>;
+			bindings = <&kp>, <&kp>;
+			hold-trigger-key-positions = <5 6 7 8 9 10>;    // <---[[right-hand keys]]
+		};
+	};
+
+	keymap {
+		compatible = "zmk,keymap";
+		default_layer {
+			bindings = <
+				// position 0           pos 1             pos 2             pos 3       pos 4    pos 5    pos 6    pos 7    pos 8    pos 9     pos 10
+				&lh_pht LSFT A    &lh_pht LGUI S    &lh_pht LALT D    &lh_pht LCTL F    &kp G    &kp H    &kp I    &kp J    &kp K    &kp L    &kp SCLN
+			>;
+		};
+	};
+};
+```
+
+##### Option 2: `tap-preferred`

 ```
 #include <behaviors.dtsi>
@ -124,7 +158,6 @@ This example configures a hold-tap that works well for homerow mods:

 	keymap {
 		compatible = "zmk,keymap";
-
 		default_layer {
 			bindings = <
 	            &hm LCTRL A &hm LGUI S &hm LALT D &hm LSHIFT F
@ -135,7 +168,36 @@ This example configures a hold-tap that works well for homerow mods:

 ```

-If this config does not work for you, try the flavor "balanced" with a medium `tapping-term-ms` such as 200ms.
+##### Option 3: `balanced`
+
+```
+#include <behaviors.dtsi>
+#include <dt-bindings/zmk/keys.h>
+
+/ {
+	behaviors {
+		bhm: balanced_homerow_mods {
+			compatible = "zmk,behavior-hold-tap";
+			label = "HOMEROW_MODS";
+			#binding-cells = <2>;
+			tapping-term-ms = <200>;    // <---[[moderate duration]]
+			quick_tap_ms = <0>;
+			flavor = "balanced";
+			bindings = <&kp>, <&kp>;
+		};
+	};
+
+	keymap {
+		compatible = "zmk,keymap";
+		default_layer {
+			bindings = <
+	            &bhm LCTRL A &bhm LGUI S &bhm LALT D &bhm LSHIFT F
+			>;
+		};
+	};
+};
+
+```

 #### Comparison to QMK