feat(behaviors) Required keys for tap-hold behaviors

* Add optional `hold-trigger-key-positions` hold-tap configuration * Leverage configuration for decision making around when to trigger hold decision in hold-taps. * Add docs for new configuration. * Tests for the new config/decision logic.
2021-11-01 09:37:20 -07:00 · 2021-11-01 09:37:20 -07:00 · 19ee7849f8
commit 19ee7849f8
parent f946dc6893
43 changed files with 488 additions and 4 deletions
--- a/app/dts/bindings/behaviors/zmk,behavior-hold-tap.yaml
+++ b/app/dts/bindings/behaviors/zmk,behavior-hold-tap.yaml
@ -30,3 +30,7 @@ properties:
      - "tap-preferred"
  retro-tap:
    type: boolean
+  hold-trigger-key-positions:
+    type: array
+    required: false
+    default: []
--- a/app/src/behaviors/behavior_hold_tap.c
+++ b/app/src/behaviors/behavior_hold_tap.c
@ -58,6 +58,8 @@ struct behavior_hold_tap_config {
    int quick_tap_ms;
    enum flavor flavor;
    bool retro_tap;
+    int32_t hold_trigger_key_positions_len;
+    int32_t hold_trigger_key_positions[];
 };

 // this data is specific for each hold-tap
@ -70,6 +72,9 @@ struct active_hold_tap {
    const struct behavior_hold_tap_config *config;
    struct k_delayed_work work;
    bool work_is_cancelled;
+
+    // initialized to -1, which is to be interpreted as "no other key has been pressed yet"
+    int32_t position_of_first_other_key_pressed;
 };

 // The undecided hold tap is the hold tap that needs to be decided before
@ -206,6 +211,7 @@ static struct active_hold_tap *store_hold_tap(uint32_t position, uint32_t param_
        active_hold_taps[i].param_hold = param_hold;
        active_hold_taps[i].param_tap = param_tap;
        active_hold_taps[i].timestamp = timestamp;
+        active_hold_taps[i].position_of_first_other_key_pressed = -1;
        return &active_hold_taps[i];
    }
    return NULL;
@ -359,6 +365,39 @@ static int release_binding(struct active_hold_tap *hold_tap) {
    return behavior_keymap_binding_released(&binding, event);
 }

+static bool is_first_other_key_pressed_trigger_key(struct active_hold_tap *hold_tap) {
+    for (int i = 0; i < hold_tap->config->hold_trigger_key_positions_len; i++) {
+        if (hold_tap->config->hold_trigger_key_positions[i] ==
+            hold_tap->position_of_first_other_key_pressed) {
+            return true;
+        }
+    }
+    return false;
+}
+
+// Force a tap decision if the positional conditions for a hold decision are not met.
+static void decide_positional_hold(struct active_hold_tap *hold_tap) {
+    // Only force a tap decision if the positional hold/tap feature is enabled.
+    if (!(hold_tap->config->hold_trigger_key_positions_len > 0)) {
+        return;
+    }
+
+    // Only force a tap decision if another key was pressed after
+    // the hold/tap key.
+    if (hold_tap->position_of_first_other_key_pressed == -1) {
+        return;
+    }
+
+    // Only force a tap decision if the first other key to be pressed
+    // (after the hold/tap key) is not one of the trigger keys.
+    if (is_first_other_key_pressed_trigger_key(hold_tap)) {
+        return;
+    }
+
+    // Since the positional key conditions have failed, force a TAP decision.
+    hold_tap->status = STATUS_TAP;
+}
+
 static void decide_hold_tap(struct active_hold_tap *hold_tap,
                            enum decision_moment decision_moment) {
    if (hold_tap->status != STATUS_UNDECIDED) {
@ -370,6 +409,7 @@ static void decide_hold_tap(struct active_hold_tap *hold_tap,
        return;
    }

+    // If the hold-tap behavior is still undecided, attempt to decide it.
    switch (hold_tap->config->flavor) {
    case FLAVOR_HOLD_PREFERRED:
        decide_hold_preferred(hold_tap, decision_moment);
@ -383,6 +423,10 @@ static void decide_hold_tap(struct active_hold_tap *hold_tap,
        return;
    }

+    decide_positional_hold(hold_tap);
+
+    // Since the hold-tap has been decided, clean up undecided_hold_tap and
+    // execute the decided behavior.
    LOG_DBG("%d decided %s (%s decision moment %s)", hold_tap->position,
            status_str(hold_tap->status), flavor_str(hold_tap->config->flavor),
            decision_moment_str(decision_moment));
@ -501,6 +545,14 @@ static int position_state_changed_listener(const zmk_event_t *eh) {
        return ZMK_EV_EVENT_BUBBLE;
    }

+    // Store the position of pressed key for positional hold-tap purposes.
+    if ((ev->state) // i.e. key pressed (not released)
+        && (undecided_hold_tap->position_of_first_other_key_pressed ==
+            -1) // i.e. no other key has been pressed yet
+    ) {
+        undecided_hold_tap->position_of_first_other_key_pressed = ev->position;
+    }
+
    if (undecided_hold_tap->position == ev->position) {
        if (ev->state) { // keydown
            LOG_ERR("hold-tap listener should be called before before most other listeners!");
@ -604,6 +656,8 @@ static struct behavior_hold_tap_data behavior_hold_tap_data;
        .quick_tap_ms = DT_INST_PROP(n, quick_tap_ms),                                             \
        .flavor = DT_ENUM_IDX(DT_DRV_INST(n), flavor),                                             \
        .retro_tap = DT_INST_PROP(n, retro_tap),                                                   \
+        .hold_trigger_key_positions = DT_INST_PROP(n, hold_trigger_key_positions),                 \
+        .hold_trigger_key_positions_len = DT_INST_PROP_LEN(n, hold_trigger_key_positions),         \
    };                                                                                             \
    DEVICE_DT_INST_DEFINE(n, behavior_hold_tap_init, device_pm_control_nop,                        \
                          &behavior_hold_tap_data, &behavior_hold_tap_config_##n, APPLICATION,     \
--- a/app/tests/hold-tap/balanced/7-positional/2-dn-timer-up/events.patterns
+++ b/app/tests/hold-tap/balanced/7-positional/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/balanced/7-positional/2-dn-timer-up/keycode_events.snapshot
+++ b/app/tests/hold-tap/balanced/7-positional/2-dn-timer-up/keycode_events.snapshot
@ -0,0 +1,5 @@
+ht_binding_pressed: 0 new undecided hold_tap
+ht_decide: 0 decided hold-timer (balanced decision moment timer)
+kp_pressed: usage_page 0x07 keycode 0xe1 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/balanced/7-positional/2-dn-timer-up/native_posix.keymap
+++ b/app/tests/hold-tap/balanced/7-positional/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/balanced/7-positional/4a-dn-ntgdn-timer-ntgup-up/events.patterns
+++ b/app/tests/hold-tap/balanced/7-positional/4a-dn-ntgdn-timer-ntgup-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/balanced/7-positional/4a-dn-ntgdn-timer-ntgup-up/keycode_events.snapshot
+++ b/app/tests/hold-tap/balanced/7-positional/4a-dn-ntgdn-timer-ntgup-up/keycode_events.snapshot
@ -0,0 +1,7 @@
+ht_binding_pressed: 0 new undecided hold_tap
+ht_decide: 0 decided tap (balanced decision moment timer)
+kp_pressed: usage_page 0x07 keycode 0x09 implicit_mods 0x00 explicit_mods 0x00
+kp_pressed: usage_page 0x07 keycode 0x08 implicit_mods 0x00 explicit_mods 0x00
+kp_released: usage_page 0x07 keycode 0x08 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/balanced/7-positional/4a-dn-ntgdn-timer-ntgup-up/native_posix.keymap
+++ b/app/tests/hold-tap/balanced/7-positional/4a-dn-ntgdn-timer-ntgup-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,1,200) // non trigger key
+		/* timer fires */ 
+		ZMK_MOCK_RELEASE(1,1,10)
+		ZMK_MOCK_RELEASE(0,0,10)
+	>;
+};
--- a/app/tests/hold-tap/balanced/7-positional/4a-dn-tgdn-timer-tgup-up/events.patterns
+++ b/app/tests/hold-tap/balanced/7-positional/4a-dn-tgdn-timer-tgup-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/balanced/7-positional/4a-dn-tgdn-timer-tgup-up/keycode_events.snapshot
+++ b/app/tests/hold-tap/balanced/7-positional/4a-dn-tgdn-timer-tgup-up/keycode_events.snapshot
@ -0,0 +1,7 @@
+ht_binding_pressed: 0 new undecided hold_tap
+ht_decide: 0 decided hold-timer (balanced decision moment timer)
+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/balanced/7-positional/4a-dn-tgdn-timer-tgup-up/native_posix.keymap
+++ b/app/tests/hold-tap/balanced/7-positional/4a-dn-tgdn-timer-tgup-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) // trigger key
+		/* timer fires */ 
+		ZMK_MOCK_RELEASE(1,0,10)
+		ZMK_MOCK_RELEASE(0,0,10)
+	>;
+};
--- a/app/tests/hold-tap/balanced/7-positional/behavior_keymap.dtsi
+++ b/app/tests/hold-tap/balanced/7-positional/behavior_keymap.dtsi
@ -0,0 +1,29 @@
+#include <dt-bindings/zmk/keys.h>
+#include <behaviors.dtsi>
+#include <dt-bindings/zmk/kscan_mock.h>
+
+/ {
+	behaviors {
+		ht_bal: behavior_hold_tap_balanced {
+			compatible = "zmk,behavior-hold-tap";
+			label = "HOLD_TAP_BALANCED";
+			#binding-cells = <2>;
+			flavor = "balanced";
+			tapping-term-ms = <300>;
+			quick-tap-ms = <200>;
+			bindings = <&kp>, <&kp>;
+            hold-trigger-key-positions = <2>;
+		};
+	};
+
+	keymap {
+		compatible = "zmk,keymap";
+		label ="Default keymap";
+
+		default_layer {
+			bindings = <
+				&ht_bal LEFT_SHIFT F      &ht_bal LEFT_CONTROL J
+				&kp D      &kp E>;
+		};
+	};
+};
--- a/app/tests/hold-tap/balanced/7-positional/tgdn-dn-ntgdn-timer-ntgup-tgup-up/events.patterns
+++ b/app/tests/hold-tap/balanced/7-positional/tgdn-dn-ntgdn-timer-ntgup-tgup-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/balanced/7-positional/tgdn-dn-ntgdn-timer-ntgup-tgup-up/keycode_events.snapshot
+++ b/app/tests/hold-tap/balanced/7-positional/tgdn-dn-ntgdn-timer-ntgup-tgup-up/keycode_events.snapshot
@ -0,0 +1,9 @@
+kp_pressed: usage_page 0x07 keycode 0x07 implicit_mods 0x00 explicit_mods 0x00
+ht_binding_pressed: 0 new undecided hold_tap
+ht_decide: 0 decided tap (balanced decision moment timer)
+kp_pressed: usage_page 0x07 keycode 0x09 implicit_mods 0x00 explicit_mods 0x00
+kp_pressed: usage_page 0x07 keycode 0x08 implicit_mods 0x00 explicit_mods 0x00
+kp_released: usage_page 0x07 keycode 0x08 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 0x09 implicit_mods 0x00 explicit_mods 0x00
+ht_binding_released: 0 cleaning up hold-tap
--- a/app/tests/hold-tap/balanced/7-positional/tgdn-dn-ntgdn-timer-ntgup-tgup-up/native_posix.keymap
+++ b/app/tests/hold-tap/balanced/7-positional/tgdn-dn-ntgdn-timer-ntgup-tgup-up/native_posix.keymap
@ -0,0 +1,16 @@
+#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) // trigger key
+		ZMK_MOCK_PRESS(0,0,10)
+		ZMK_MOCK_PRESS(1,1,400) // not trigger key
+		/* timer fires */ 
+		ZMK_MOCK_RELEASE(1,1,10)
+		ZMK_MOCK_RELEASE(1,0,10)
+		ZMK_MOCK_RELEASE(0,0,10)
+	>;
+};
--- a/app/tests/hold-tap/hold-preferred/7-positional/2-dn-timer-up/events.patterns
+++ b/app/tests/hold-tap/hold-preferred/7-positional/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/hold-preferred/7-positional/2-dn-timer-up/keycode_events.snapshot
+++ b/app/tests/hold-tap/hold-preferred/7-positional/2-dn-timer-up/keycode_events.snapshot
@ -0,0 +1,5 @@
+ht_binding_pressed: 0 new undecided hold_tap
+ht_decide: 0 decided hold-timer (hold-preferred decision moment timer)
+kp_pressed: usage_page 0x07 keycode 0xe1 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/hold-preferred/7-positional/2-dn-timer-up/native_posix.keymap
+++ b/app/tests/hold-tap/hold-preferred/7-positional/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/hold-preferred/7-positional/4a-dn-ntgdn-timer-ntgup-up/events.patterns
+++ b/app/tests/hold-tap/hold-preferred/7-positional/4a-dn-ntgdn-timer-ntgup-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/hold-preferred/7-positional/4a-dn-ntgdn-timer-ntgup-up/keycode_events.snapshot
+++ b/app/tests/hold-tap/hold-preferred/7-positional/4a-dn-ntgdn-timer-ntgup-up/keycode_events.snapshot
@ -0,0 +1,7 @@
+ht_binding_pressed: 0 new undecided hold_tap
+ht_decide: 0 decided tap (hold-preferred decision moment other-key-down)
+kp_pressed: usage_page 0x07 keycode 0x09 implicit_mods 0x00 explicit_mods 0x00
+kp_pressed: usage_page 0x07 keycode 0x08 implicit_mods 0x00 explicit_mods 0x00
+kp_released: usage_page 0x07 keycode 0x08 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/hold-preferred/7-positional/4a-dn-ntgdn-timer-ntgup-up/native_posix.keymap
+++ b/app/tests/hold-tap/hold-preferred/7-positional/4a-dn-ntgdn-timer-ntgup-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,1,200) // non trigger key
+		/* timer fires */ 
+		ZMK_MOCK_RELEASE(1,1,10)
+		ZMK_MOCK_RELEASE(0,0,10)
+	>;
+};
--- a/app/tests/hold-tap/hold-preferred/7-positional/4a-dn-tgdn-timer-tgup-up/events.patterns
+++ b/app/tests/hold-tap/hold-preferred/7-positional/4a-dn-tgdn-timer-tgup-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/hold-preferred/7-positional/4a-dn-tgdn-timer-tgup-up/keycode_events.snapshot
+++ b/app/tests/hold-tap/hold-preferred/7-positional/4a-dn-tgdn-timer-tgup-up/keycode_events.snapshot
@ -0,0 +1,7 @@
+ht_binding_pressed: 0 new undecided hold_tap
+ht_decide: 0 decided hold-interrupt (hold-preferred 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/hold-preferred/7-positional/4a-dn-tgdn-timer-tgup-up/native_posix.keymap
+++ b/app/tests/hold-tap/hold-preferred/7-positional/4a-dn-tgdn-timer-tgup-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) // trigger key
+		/* timer fires */ 
+		ZMK_MOCK_RELEASE(1,0,10)
+		ZMK_MOCK_RELEASE(0,0,10)
+	>;
+};
--- a/app/tests/hold-tap/hold-preferred/7-positional/behavior_keymap.dtsi
+++ b/app/tests/hold-tap/hold-preferred/7-positional/behavior_keymap.dtsi
@ -0,0 +1,29 @@
+#include <dt-bindings/zmk/keys.h>
+#include <behaviors.dtsi>
+#include <dt-bindings/zmk/kscan_mock.h>
+
+/ {
+	behaviors {
+		ht_hold: behavior_hold_hold_tap {
+			compatible = "zmk,behavior-hold-tap";
+			label = "hold_hold_tap";
+			#binding-cells = <2>;
+			flavor = "hold-preferred";
+			tapping-term-ms = <300>;
+			quick-tap-ms = <200>;
+			bindings = <&kp>, <&kp>;
+            hold-trigger-key-positions = <2>;
+		};
+	};
+
+	keymap {
+		compatible = "zmk,keymap";
+		label ="Default keymap";
+
+		default_layer {
+			bindings = <
+				&ht_hold LEFT_SHIFT F      &ht_hold LEFT_CONTROL J
+				&kp D      &kp E>;
+		};
+	};
+};
--- a/app/tests/hold-tap/hold-preferred/7-positional/tgdn-dn-ntgdn-timer-ntgup-tgup-up/events.patterns
+++ b/app/tests/hold-tap/hold-preferred/7-positional/tgdn-dn-ntgdn-timer-ntgup-tgup-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/hold-preferred/7-positional/tgdn-dn-ntgdn-timer-ntgup-tgup-up/keycode_events.snapshot
+++ b/app/tests/hold-tap/hold-preferred/7-positional/tgdn-dn-ntgdn-timer-ntgup-tgup-up/keycode_events.snapshot
@ -0,0 +1,9 @@
+kp_pressed: usage_page 0x07 keycode 0x07 implicit_mods 0x00 explicit_mods 0x00
+ht_binding_pressed: 0 new undecided hold_tap
+ht_decide: 0 decided tap (hold-preferred decision moment other-key-down)
+kp_pressed: usage_page 0x07 keycode 0x09 implicit_mods 0x00 explicit_mods 0x00
+kp_pressed: usage_page 0x07 keycode 0x08 implicit_mods 0x00 explicit_mods 0x00
+kp_released: usage_page 0x07 keycode 0x08 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 0x09 implicit_mods 0x00 explicit_mods 0x00
+ht_binding_released: 0 cleaning up hold-tap
--- a/app/tests/hold-tap/hold-preferred/7-positional/tgdn-dn-ntgdn-timer-ntgup-tgup-up/native_posix.keymap
+++ b/app/tests/hold-tap/hold-preferred/7-positional/tgdn-dn-ntgdn-timer-ntgup-tgup-up/native_posix.keymap
@ -0,0 +1,16 @@
+#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) // trigger key
+		ZMK_MOCK_PRESS(0,0,10)
+		ZMK_MOCK_PRESS(1,1,400) // not trigger key
+		/* timer fires */ 
+		ZMK_MOCK_RELEASE(1,1,10)
+		ZMK_MOCK_RELEASE(1,0,10)
+		ZMK_MOCK_RELEASE(0,0,10)
+	>;
+};
--- a/app/tests/hold-tap/tap-preferred/7-positional/2-dn-timer-up/events.patterns
+++ b/app/tests/hold-tap/tap-preferred/7-positional/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-preferred/7-positional/2-dn-timer-up/keycode_events.snapshot
+++ b/app/tests/hold-tap/tap-preferred/7-positional/2-dn-timer-up/keycode_events.snapshot
@ -0,0 +1,5 @@
+ht_binding_pressed: 0 new undecided hold_tap
+ht_decide: 0 decided hold-timer (tap-preferred decision moment timer)
+kp_pressed: usage_page 0x07 keycode 0xe1 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-preferred/7-positional/2-dn-timer-up/native_posix.keymap
+++ b/app/tests/hold-tap/tap-preferred/7-positional/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-preferred/7-positional/4a-dn-ntgdn-timer-ntgup-up/events.patterns
+++ b/app/tests/hold-tap/tap-preferred/7-positional/4a-dn-ntgdn-timer-ntgup-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-preferred/7-positional/4a-dn-ntgdn-timer-ntgup-up/keycode_events.snapshot
+++ b/app/tests/hold-tap/tap-preferred/7-positional/4a-dn-ntgdn-timer-ntgup-up/keycode_events.snapshot
@ -0,0 +1,7 @@
+ht_binding_pressed: 0 new undecided hold_tap
+ht_decide: 0 decided tap (tap-preferred decision moment timer)
+kp_pressed: usage_page 0x07 keycode 0x09 implicit_mods 0x00 explicit_mods 0x00
+kp_pressed: usage_page 0x07 keycode 0x08 implicit_mods 0x00 explicit_mods 0x00
+kp_released: usage_page 0x07 keycode 0x08 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-preferred/7-positional/4a-dn-ntgdn-timer-ntgup-up/native_posix.keymap
+++ b/app/tests/hold-tap/tap-preferred/7-positional/4a-dn-ntgdn-timer-ntgup-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,1,200) // non trigger key
+		/* timer fires */ 
+		ZMK_MOCK_RELEASE(1,1,10)
+		ZMK_MOCK_RELEASE(0,0,10)
+	>;
+};
--- a/app/tests/hold-tap/tap-preferred/7-positional/4a-dn-tgdn-timer-tgup-up/events.patterns
+++ b/app/tests/hold-tap/tap-preferred/7-positional/4a-dn-tgdn-timer-tgup-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-preferred/7-positional/4a-dn-tgdn-timer-tgup-up/keycode_events.snapshot
+++ b/app/tests/hold-tap/tap-preferred/7-positional/4a-dn-tgdn-timer-tgup-up/keycode_events.snapshot
@ -0,0 +1,7 @@
+ht_binding_pressed: 0 new undecided hold_tap
+ht_decide: 0 decided hold-timer (tap-preferred decision moment timer)
+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-preferred/7-positional/4a-dn-tgdn-timer-tgup-up/native_posix.keymap
+++ b/app/tests/hold-tap/tap-preferred/7-positional/4a-dn-tgdn-timer-tgup-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) // trigger key
+		/* timer fires */ 
+		ZMK_MOCK_RELEASE(1,0,10)
+		ZMK_MOCK_RELEASE(0,0,10)
+	>;
+};
--- a/app/tests/hold-tap/tap-preferred/7-positional/behavior_keymap.dtsi
+++ b/app/tests/hold-tap/tap-preferred/7-positional/behavior_keymap.dtsi
@ -0,0 +1,29 @@
+#include <dt-bindings/zmk/keys.h>
+#include <behaviors.dtsi>
+#include <dt-bindings/zmk/kscan_mock.h>
+
+/ {
+	behaviors {
+		tp: behavior_tap_preferred {
+			compatible = "zmk,behavior-hold-tap";
+			label = "MOD_TAP";
+			#binding-cells = <2>;
+			flavor = "tap-preferred";
+			tapping-term-ms = <300>;
+			quick-tap-ms = <200>;
+			bindings = <&kp>, <&kp>;
+            hold-trigger-key-positions = <2>;
+		};
+	};
+
+	keymap {
+		compatible = "zmk,keymap";
+		label ="Default keymap";
+
+		default_layer {
+			bindings = <
+				&tp LEFT_SHIFT F      &tp LEFT_CONTROL J
+				&kp D      &kp E>;
+		};
+	};
+};
--- a/app/tests/hold-tap/tap-preferred/7-positional/tgdn-dn-ntgdn-timer-ntgup-tgup-up/events.patterns
+++ b/app/tests/hold-tap/tap-preferred/7-positional/tgdn-dn-ntgdn-timer-ntgup-tgup-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-preferred/7-positional/tgdn-dn-ntgdn-timer-ntgup-tgup-up/keycode_events.snapshot
+++ b/app/tests/hold-tap/tap-preferred/7-positional/tgdn-dn-ntgdn-timer-ntgup-tgup-up/keycode_events.snapshot
@ -0,0 +1,9 @@
+kp_pressed: usage_page 0x07 keycode 0x07 implicit_mods 0x00 explicit_mods 0x00
+ht_binding_pressed: 0 new undecided hold_tap
+ht_decide: 0 decided tap (tap-preferred decision moment timer)
+kp_pressed: usage_page 0x07 keycode 0x09 implicit_mods 0x00 explicit_mods 0x00
+kp_pressed: usage_page 0x07 keycode 0x08 implicit_mods 0x00 explicit_mods 0x00
+kp_released: usage_page 0x07 keycode 0x08 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 0x09 implicit_mods 0x00 explicit_mods 0x00
+ht_binding_released: 0 cleaning up hold-tap
--- a/app/tests/hold-tap/tap-preferred/7-positional/tgdn-dn-ntgdn-timer-ntgup-tgup-up/native_posix.keymap
+++ b/app/tests/hold-tap/tap-preferred/7-positional/tgdn-dn-ntgdn-timer-ntgup-tgup-up/native_posix.keymap
@ -0,0 +1,16 @@
+#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) // trigger key
+		ZMK_MOCK_PRESS(0,0,10)
+		ZMK_MOCK_PRESS(1,1,400) // not trigger key
+		/* timer fires */ 
+		ZMK_MOCK_RELEASE(1,1,10)
+		ZMK_MOCK_RELEASE(1,0,10)
+		ZMK_MOCK_RELEASE(0,0,10)
+	>;
+};
--- a/docs/docs/behaviors/hold-tap.md
+++ b/docs/docs/behaviors/hold-tap.md
@ -59,6 +59,48 @@ For example, if you press `&mt LEFT_SHIFT A` and then release it without pressin
 };
 ```

+#### Positional hold-tap and `hold-trigger-key-positions`
+
+- Including `hold-trigger-key-postions` in your hold-tap definition turns on the positional hold-tap feature.
+- With positional hold-tap enabled, if you press any key **NOT** listed in `hold-trigger-key-positions` before `tapping-term-ms` expires, it will produce a tap.
+- In all other situations, positional hold-tap will not modify the behavior of your hold-tap.
+- Positional hold-tap is useful with home-row modifiers. If you have a home-row modifier key in the left hand for example, by including only keys positions from the right hand in `hold-trigger-key-positions`, you will only get hold behaviors during cross-hand key combinations.
+- Note that `hold-trigger-key-postions` is an array of key position indexes. Key positions are numbered according to your keymap, starting with 0. So if the first key in your keymap is Q, this key is in position 0. The next key (probably W) will be in position 1, et cetera.
+- See the following example, which uses a hold-tap behavior definition, configured with the `hold-preferrred` flavor, and with positional hold-tap enabled:
+
+```
+#include <dt-bindings/zmk/keys.h>
+#include <behaviors.dtsi>
+/ {
+	behaviors {
+		pht: positional_hold_tap {
+			compatible = "zmk,behavior-hold-tap";
+			label = "POSITIONAL_HOLD_TAP";
+			#binding-cells = <2>;
+			flavor = "hold-preferred";
+			tapping-term-ms = <400>;
+			quick-tap-ms = <200>;
+			bindings = <&kp>, <&kp>;
+			hold-trigger-key-positions = <1>;    // <---[[the W key]]
+		};
+	};
+	keymap {
+		compatible = "zmk,keymap";
+		label ="Default keymap";
+		default_layer {
+			bindings = <
+				//  position 0         position 1       position 2
+				&pht LEFT_SHIFT Q        &kp W            &kp E
+			>;
+		};
+	};
+};
+```
+
+- The sequence `(pht_down, E_down, E_up, pht_up)` produces `qe`. The normal hold behavior (LEFT_SHIFT) **IS** modified into a tap behavior (Q) by positional hold-tap because the first key pressed after the hold-tap key is the `E key`, which is in position 2, which **is NOT** included in `hold-trigger-key-positions`.
+- The sequence `(pht_down, W_down, W_up, pht_up)` produces `W`. The normal hold behavior (LEFT_SHIFT) **is NOT** modified into a tap behavior (Q) by positional hold-tap because the first key pressed after the hold-tap key is the `W key`, which is in position 1, which **IS** included in `hold-trigger-key-positions`.
+- If the `LEFT_SHIFT / Q key` is held by itself for longer than `tapping-term-ms`, a hold behavior is produced. This is because positional hold-tap only modifies the behavior of a hold-tap if another key is pressed before the `tapping-term-ms` period expires.
+
 #### Home row mods

 This example configures a hold-tap that works well for homerow mods:
--- a/docs/docs/development/tests.md
+++ b/docs/docs/development/tests.md
@ -3,10 +3,10 @@ title: Tests
 sidebar_label: Tests
 ---

-Running tests requires [native posix support](posix-board.md). Any folder under `/app/tests`
-containing `native_posix.keymap` will be selected when running `west test`.
-
-Run a single test with `west test <testname>`, like `west test tests/toggle-layer/normal`.
+- Running tests requires [native posix support](posix-board.md).
+- Any folder under `/app/tests` containing `native_posix.keymap` will be selected when running `west test`.
+- Run tests from within the `/zmk/app` directory.
+- Run a single test with `west test <testname>`, like `west test tests/toggle-layer/normal`.

 ## Creating a New Test Set