feat(behaviors): Add Tap-Dance behavior

app/CMakeLists.txt

@@ -54,6 +54,7 @@ if ((NOT CONFIG_ZMK_SPLIT) OR CONFIG_ZMK_SPLIT_BLE_ROLE_CENTRAL)
   target_sources(app PRIVATE src/behaviors/behavior_momentary_layer.c)
   target_sources(app PRIVATE src/behaviors/behavior_mod_morph.c)
   target_sources(app PRIVATE src/behaviors/behavior_outputs.c)
+  target_sources(app PRIVATE src/behaviors/behavior_tap_dance.c)
   target_sources(app PRIVATE src/behaviors/behavior_toggle_layer.c)
   target_sources(app PRIVATE src/behaviors/behavior_to_layer.c)
   target_sources(app PRIVATE src/behaviors/behavior_transparent.c)

app/dts/bindings/behaviors/zmk,behavior-tap-dance.yaml

@@ -0,0 +1,16 @@
+# Copyright (c) 2022 The ZMK Contributors
+# SPDX-License-Identifier: MIT
+
+description: Tap Dance Behavior
+
+compatible: "zmk,behavior-tap-dance"
+
+include: zero_param.yaml
+
+properties:
+  bindings:
+    type: phandle-array
+    required: true
+  tapping-term-ms:
+    type: int
+    default: 200

app/src/behaviors/behavior_tap_dance.c

@@ -0,0 +1,259 @@
+/*
+ * Copyright (c) 2022 The ZMK Contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+
+#define DT_DRV_COMPAT zmk_behavior_tap_dance
+
+#include <device.h>
+#include <drivers/behavior.h>
+#include <logging/log.h>
+#include <zmk/behavior.h>
+#include <zmk/keymap.h>
+#include <zmk/matrix.h>
+#include <zmk/event_manager.h>
+#include <zmk/events/position_state_changed.h>
+#include <zmk/events/keycode_state_changed.h>
+#include <zmk/hid.h>
+
+LOG_MODULE_DECLARE(zmk, CONFIG_ZMK_LOG_LEVEL);
+
+#if DT_HAS_COMPAT_STATUS_OKAY(DT_DRV_COMPAT)
+
+#define ZMK_BHV_TAP_DANCE_MAX_HELD 10
+
+#define ZMK_BHV_TAP_DANCE_POSITION_FREE ULONG_MAX
+
+struct behavior_tap_dance_config {
+    uint32_t tapping_term_ms;
+    size_t behavior_count;
+    struct zmk_behavior_binding *behaviors;
+};
+
+struct active_tap_dance {
+    // Tap Dance Data
+    int counter;
+    uint32_t position;
+    uint32_t param1;
+    uint32_t param2;
+    bool is_pressed;
+    const struct behavior_tap_dance_config *config;
+
+    // Timer Data
+    bool timer_started;
+    bool timer_cancelled;
+    bool tap_dance_decided;
+    int64_t release_at;
+    struct k_delayed_work release_timer;
+};
+
+struct active_tap_dance active_tap_dances[ZMK_BHV_TAP_DANCE_MAX_HELD] = {};
+
+static struct active_tap_dance *find_tap_dance(uint32_t position) {
+    for (int i = 0; i < ZMK_BHV_TAP_DANCE_MAX_HELD; i++) {
+        if (active_tap_dances[i].position == position && !active_tap_dances[i].timer_cancelled) {
+            return &active_tap_dances[i];
+        }
+    }
+    return NULL;
+}
+
+static int new_tap_dance(uint32_t position, const struct behavior_tap_dance_config *config,
+                         struct active_tap_dance **tap_dance) {
+    for (int i = 0; i < ZMK_BHV_TAP_DANCE_MAX_HELD; i++) {
+        struct active_tap_dance *const ref_dance = &active_tap_dances[i];
+        if (ref_dance->position == ZMK_BHV_TAP_DANCE_POSITION_FREE) {
+            ref_dance->counter = 0;
+            ref_dance->position = position;
+            ref_dance->config = config;
+            ref_dance->release_at = 0;
+            ref_dance->is_pressed = true;
+            ref_dance->timer_started = true;
+            ref_dance->timer_cancelled = false;
+            ref_dance->tap_dance_decided = false;
+            *tap_dance = ref_dance;
+            return 0;
+        }
+    }
+    return -ENOMEM;
+}
+
+static void clear_tap_dance(struct active_tap_dance *tap_dance) {
+    tap_dance->position = ZMK_BHV_TAP_DANCE_POSITION_FREE;
+}
+
+static int stop_timer(struct active_tap_dance *tap_dance) {
+    int timer_cancel_result = k_delayed_work_cancel(&tap_dance->release_timer);
+    if (timer_cancel_result == -EINPROGRESS) {
+        // too late to cancel, we'll let the timer handler clear up.
+        tap_dance->timer_cancelled = true;
+    }
+    return timer_cancel_result;
+}
+
+static void reset_timer(struct active_tap_dance *tap_dance,
+                        struct zmk_behavior_binding_event event) {
+    tap_dance->release_at = event.timestamp + tap_dance->config->tapping_term_ms;
+    int32_t ms_left = tap_dance->release_at - k_uptime_get();
+    if (ms_left > 0) {
+        k_delayed_work_submit(&tap_dance->release_timer, K_MSEC(ms_left));
+        LOG_DBG("Successfully reset timer at position %d", tap_dance->position);
+    }
+}
+
+static inline int press_tap_dance_behavior(struct active_tap_dance *tap_dance, int64_t timestamp) {
+    tap_dance->tap_dance_decided = true;
+    struct zmk_behavior_binding binding = tap_dance->config->behaviors[tap_dance->counter - 1];
+    struct zmk_behavior_binding_event event = {
+        .position = tap_dance->position,
+        .timestamp = timestamp,
+    };
+    return behavior_keymap_binding_pressed(&binding, event);
+}
+
+static inline int release_tap_dance_behavior(struct active_tap_dance *tap_dance,
+                                             int64_t timestamp) {
+    struct zmk_behavior_binding binding = tap_dance->config->behaviors[tap_dance->counter - 1];
+    struct zmk_behavior_binding_event event = {
+        .position = tap_dance->position,
+        .timestamp = timestamp,
+    };
+    clear_tap_dance(tap_dance);
+    return behavior_keymap_binding_released(&binding, event);
+}
+
+static int on_tap_dance_binding_pressed(struct zmk_behavior_binding *binding,
+                                        struct zmk_behavior_binding_event event) {
+    const struct device *dev = device_get_binding(binding->behavior_dev);
+    const struct behavior_tap_dance_config *cfg = dev->config;
+    struct active_tap_dance *tap_dance;
+    tap_dance = find_tap_dance(event.position);
+    if (tap_dance == NULL) {
+        if (new_tap_dance(event.position, cfg, &tap_dance) == -ENOMEM) {
+            LOG_ERR("Unable to create new tap dance. Insufficient space in active_tap_dances[].");
+            return ZMK_BEHAVIOR_OPAQUE;
+        }
+        LOG_DBG("%d created new tap dance", event.position);
+    }
+    tap_dance->is_pressed = true;
+    LOG_DBG("%d tap dance pressed", event.position);
+    stop_timer(tap_dance);
+    // Increment the counter on keypress. If the counter has reached its maximum
+    // value, invoke the last binding available.
+    if (tap_dance->counter < cfg->behavior_count) {
+        tap_dance->counter++;
+    }
+    if (tap_dance->counter == cfg->behavior_count) {
+        // LOG_DBG("Tap dance has been decided via maximum counter value");
+        press_tap_dance_behavior(tap_dance, event.timestamp);
+        return ZMK_EV_EVENT_BUBBLE;
+    }
+    reset_timer(tap_dance, event);
+    return ZMK_BEHAVIOR_OPAQUE;
+}
+
+static int on_tap_dance_binding_released(struct zmk_behavior_binding *binding,
+                                         struct zmk_behavior_binding_event event) {
+    LOG_DBG("%d tap dance keybind released", event.position);
+    struct active_tap_dance *tap_dance = find_tap_dance(event.position);
+    if (tap_dance == NULL) {
+        LOG_ERR("ACTIVE TAP DANCE CLEARED TOO EARLY");
+        return ZMK_BEHAVIOR_OPAQUE;
+    }
+    tap_dance->is_pressed = false;
+    if (tap_dance->tap_dance_decided) {
+        release_tap_dance_behavior(tap_dance, event.timestamp);
+    }
+    return ZMK_BEHAVIOR_OPAQUE;
+}
+
+void behavior_tap_dance_timer_handler(struct k_work *item) {
+    struct active_tap_dance *tap_dance = CONTAINER_OF(item, struct active_tap_dance, release_timer);
+    if (tap_dance->position == ZMK_BHV_TAP_DANCE_POSITION_FREE) {
+        return;
+    }
+    if (tap_dance->timer_cancelled) {
+        return;
+    }
+    LOG_DBG("Tap dance has been decided via timer. Counter reached: %d", tap_dance->counter);
+    press_tap_dance_behavior(tap_dance, tap_dance->release_at);
+    if (tap_dance->is_pressed) {
+        return;
+    }
+    release_tap_dance_behavior(tap_dance, tap_dance->release_at);
+}
+
+static const struct behavior_driver_api behavior_tap_dance_driver_api = {
+    .binding_pressed = on_tap_dance_binding_pressed,
+    .binding_released = on_tap_dance_binding_released,
+};
+
+static int tap_dance_position_state_changed_listener(const zmk_event_t *eh);
+
+ZMK_LISTENER(behavior_tap_dance, tap_dance_position_state_changed_listener);
+ZMK_SUBSCRIPTION(behavior_tap_dance, zmk_position_state_changed);
+
+static int tap_dance_position_state_changed_listener(const zmk_event_t *eh) {
+    struct zmk_position_state_changed *ev = as_zmk_position_state_changed(eh);
+    if (ev == NULL) {
+        return ZMK_EV_EVENT_BUBBLE;
+    }
+    if (!ev->state) {
+        LOG_DBG("Ignore upstroke at position %d.", ev->position);
+        return ZMK_EV_EVENT_BUBBLE;
+    }
+    for (int i = 0; i < ZMK_BHV_TAP_DANCE_MAX_HELD; i++) {
+        struct active_tap_dance *tap_dance = &active_tap_dances[i];
+        if (tap_dance->position == ZMK_BHV_TAP_DANCE_POSITION_FREE) {
+            continue;
+        }
+        if (tap_dance->position == ev->position) {
+            continue;
+        }
+        stop_timer(tap_dance);
+        LOG_DBG("Tap dance interrupted, activating tap-dance at %d", tap_dance->position);
+        if (!tap_dance->tap_dance_decided) {
+            press_tap_dance_behavior(tap_dance, ev->timestamp);
+            if (!tap_dance->is_pressed) {
+                release_tap_dance_behavior(tap_dance, ev->timestamp);
+            }
+            return ZMK_EV_EVENT_BUBBLE;
+        }
+    }
+    return ZMK_EV_EVENT_BUBBLE;
+}
+
+static int behavior_tap_dance_init(const struct device *dev) {
+    static bool init_first_run = true;
+    if (init_first_run) {
+        for (int i = 0; i < ZMK_BHV_TAP_DANCE_MAX_HELD; i++) {
+            k_delayed_work_init(&active_tap_dances[i].release_timer,
+                                behavior_tap_dance_timer_handler);
+            clear_tap_dance(&active_tap_dances[i]);
+        }
+    }
+    init_first_run = false;
+    return 0;
+}
+
+#define _TRANSFORM_ENTRY(idx, node) ZMK_KEYMAP_EXTRACT_BINDING(idx, node),
+
+#define TRANSFORMED_BINDINGS(node)                                                                 \
+    { UTIL_LISTIFY(DT_INST_PROP_LEN(node, bindings), _TRANSFORM_ENTRY, DT_DRV_INST(node)) }
+
+#define KP_INST(n)                                                                                 \
+    static struct zmk_behavior_binding                                                             \
+        behavior_tap_dance_config_##n##_bindings[DT_INST_PROP_LEN(n, bindings)] =                  \
+            TRANSFORMED_BINDINGS(n);                                                               \
+    static struct behavior_tap_dance_config behavior_tap_dance_config_##n = {                      \
+        .tapping_term_ms = DT_INST_PROP(n, tapping_term_ms),                                       \
+        .behaviors = behavior_tap_dance_config_##n##_bindings,                                     \
+        .behavior_count = DT_INST_PROP_LEN(n, bindings)};                                          \
+    DEVICE_AND_API_INIT(behavior_tap_dance_##n, DT_INST_LABEL(n), behavior_tap_dance_init, NULL,   \
+                        &behavior_tap_dance_config_##n, APPLICATION,                               \
+                        CONFIG_KERNEL_INIT_PRIORITY_DEFAULT, &behavior_tap_dance_driver_api);
+
+DT_INST_FOREACH_STATUS_OKAY(KP_INST)
+
+#endif

app/tests/tap-dance/1a-tap1/events.patterns

@@ -0,0 +1,2 @@
+s/.*hid_listener_keycode/kp/p
+s/.*on_tap_dance_binding/td_binding/p

app/tests/tap-dance/1a-tap1/keycode_events.snapshot

@@ -0,0 +1,5 @@
+td_binding_pressed: 0 created new tap dance
+td_binding_pressed: 0 tap dance pressed
+td_binding_released: 0 tap dance keybind released
+kp_pressed: usage_page 0x07 keycode 0x04 implicit_mods 0x00 explicit_mods 0x00
+kp_released: usage_page 0x07 keycode 0x04 implicit_mods 0x00 explicit_mods 0x00

app/tests/tap-dance/1a-tap1/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,200)
+	>;
+};

app/tests/tap-dance/1b-tap2/events.patterns

@@ -0,0 +1,2 @@
+s/.*hid_listener_keycode/kp/p
+s/.*on_tap_dance_binding/td_binding/p

app/tests/tap-dance/1b-tap2/keycode_events.snapshot

@@ -0,0 +1,7 @@
+td_binding_pressed: 0 created new tap dance
+td_binding_pressed: 0 tap dance pressed
+td_binding_released: 0 tap dance keybind released
+td_binding_pressed: 0 tap dance pressed
+td_binding_released: 0 tap dance keybind released
+kp_pressed: usage_page 0x07 keycode 0x05 implicit_mods 0x00 explicit_mods 0x00
+kp_released: usage_page 0x07 keycode 0x05 implicit_mods 0x00 explicit_mods 0x00

app/tests/tap-dance/1b-tap2/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(0,0,10)
+		ZMK_MOCK_RELEASE(0,0,10)  
+        ZMK_MOCK_PRESS(0,0,10)
+		ZMK_MOCK_RELEASE(0,0,200)  
+	>;
+};

app/tests/tap-dance/1c-tap3/events.patterns

@@ -0,0 +1,2 @@
+s/.*hid_listener_keycode/kp/p
+s/.*on_tap_dance_binding/td_binding/p

app/tests/tap-dance/1c-tap3/keycode_events.snapshot

@@ -0,0 +1,9 @@
+td_binding_pressed: 0 created new tap dance
+td_binding_pressed: 0 tap dance pressed
+td_binding_released: 0 tap dance keybind released
+td_binding_pressed: 0 tap dance pressed
+td_binding_released: 0 tap dance keybind released
+td_binding_pressed: 0 tap dance pressed
+td_binding_released: 0 tap dance keybind released
+kp_pressed: usage_page 0x07 keycode 0x06 implicit_mods 0x00 explicit_mods 0x00
+kp_released: usage_page 0x07 keycode 0x06 implicit_mods 0x00 explicit_mods 0x00

app/tests/tap-dance/1c-tap3/native_posix.keymap

@@ -0,0 +1,15 @@
+#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,10)
+		ZMK_MOCK_RELEASE(0,0,10)
+        ZMK_MOCK_PRESS(0,0,10)
+		ZMK_MOCK_RELEASE(0,0,200)  
+	>;
+};

app/tests/tap-dance/2a-hold1/events.patterns

@@ -0,0 +1,2 @@
+s/.*hid_listener_keycode/kp/p
+s/.*on_tap_dance_binding/td_binding/p

app/tests/tap-dance/2a-hold1/keycode_events.snapshot

@@ -0,0 +1,5 @@
+td_binding_pressed: 0 created new tap dance
+td_binding_pressed: 0 tap dance pressed
+kp_pressed: usage_page 0x07 keycode 0xe1 implicit_mods 0x00 explicit_mods 0x00
+td_binding_released: 0 tap dance keybind released
+kp_released: usage_page 0x07 keycode 0xe1 implicit_mods 0x00 explicit_mods 0x00

app/tests/tap-dance/2a-hold1/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,400)
+		ZMK_MOCK_RELEASE(0,0,10)  
+	>;
+};

app/tests/tap-dance/2b-hold2/events.patterns

@@ -0,0 +1,2 @@
+s/.*hid_listener_keycode/kp/p
+s/.*on_tap_dance_binding/td_binding/p

app/tests/tap-dance/2b-hold2/keycode_events.snapshot

@@ -0,0 +1,7 @@
+td_binding_pressed: 0 created new tap dance
+td_binding_pressed: 0 tap dance pressed
+td_binding_released: 0 tap dance keybind released
+td_binding_pressed: 0 tap dance pressed
+kp_pressed: usage_page 0x07 keycode 0xe2 implicit_mods 0x00 explicit_mods 0x00
+td_binding_released: 0 tap dance keybind released
+kp_released: usage_page 0x07 keycode 0xe2 implicit_mods 0x00 explicit_mods 0x00

app/tests/tap-dance/2b-hold2/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(0,0,10)
+		ZMK_MOCK_RELEASE(0,0,10)  
+        ZMK_MOCK_PRESS(0,0,400)
+		ZMK_MOCK_RELEASE(0,0,10)  
+	>;
+};

app/tests/tap-dance/2c-hold3/events.patterns

@@ -0,0 +1,2 @@
+s/.*hid_listener_keycode/kp/p
+s/.*on_tap_dance_binding/td_binding/p

app/tests/tap-dance/2c-hold3/keycode_events.snapshot

@@ -0,0 +1,9 @@
+td_binding_pressed: 0 created new tap dance
+td_binding_pressed: 0 tap dance pressed
+td_binding_released: 0 tap dance keybind released
+td_binding_pressed: 0 tap dance pressed
+td_binding_released: 0 tap dance keybind released
+td_binding_pressed: 0 tap dance pressed
+kp_pressed: usage_page 0x07 keycode 0xe3 implicit_mods 0x00 explicit_mods 0x00
+td_binding_released: 0 tap dance keybind released
+kp_released: usage_page 0x07 keycode 0xe3 implicit_mods 0x00 explicit_mods 0x00

app/tests/tap-dance/2c-hold3/native_posix.keymap

@@ -0,0 +1,15 @@
+#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,10)
+		ZMK_MOCK_RELEASE(0,0,10)
+        ZMK_MOCK_PRESS(0,0,400)
+		ZMK_MOCK_RELEASE(0,0,10)  
+	>;
+};

app/tests/tap-dance/3a-tap-int-mid/events.patterns

@@ -0,0 +1,2 @@
+s/.*hid_listener_keycode/kp/p
+s/.*on_tap_dance_binding/td_binding/p

app/tests/tap-dance/3a-tap-int-mid/keycode_events.snapshot

@@ -0,0 +1,10 @@
+td_binding_pressed: 2 created new tap dance
+td_binding_pressed: 2 tap dance pressed
+kp_pressed: usage_page 0x07 keycode 0x1e implicit_mods 0x00 explicit_mods 0x00
+td_binding_pressed: 1 created new tap dance
+td_binding_pressed: 1 tap dance pressed
+kp_pressed: usage_page 0x07 keycode 0x16 implicit_mods 0x00 explicit_mods 0x00
+td_binding_released: 1 tap dance keybind released
+kp_released: usage_page 0x07 keycode 0x16 implicit_mods 0x00 explicit_mods 0x00
+td_binding_released: 2 tap dance keybind released
+kp_released: usage_page 0x07 keycode 0x1e implicit_mods 0x00 explicit_mods 0x00

app/tests/tap-dance/3a-tap-int-mid/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)
+        ZMK_MOCK_PRESS(0,1,10)
+        ZMK_MOCK_RELEASE(0,1,10)
+        ZMK_MOCK_RELEASE(1,0,10)
+	>;
+};

app/tests/tap-dance/3b-tap-int-seq/events.patterns

@@ -0,0 +1,2 @@
+s/.*hid_listener_keycode/kp/p
+s/.*on_tap_dance_binding/td_binding/p

app/tests/tap-dance/3b-tap-int-seq/keycode_events.snapshot

@@ -0,0 +1,10 @@
+td_binding_pressed: 2 created new tap dance
+td_binding_pressed: 2 tap dance pressed
+kp_pressed: usage_page 0x07 keycode 0x1e implicit_mods 0x00 explicit_mods 0x00
+td_binding_pressed: 1 created new tap dance
+td_binding_pressed: 1 tap dance pressed
+kp_pressed: usage_page 0x07 keycode 0x16 implicit_mods 0x00 explicit_mods 0x00
+td_binding_released: 2 tap dance keybind released
+kp_released: usage_page 0x07 keycode 0x1e implicit_mods 0x00 explicit_mods 0x00
+td_binding_released: 1 tap dance keybind released
+kp_released: usage_page 0x07 keycode 0x16 implicit_mods 0x00 explicit_mods 0x00

app/tests/tap-dance/3b-tap-int-seq/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)
+        ZMK_MOCK_PRESS(0,1,10)
+        ZMK_MOCK_RELEASE(1,0,10)
+        ZMK_MOCK_RELEASE(0,1,10)
+	>;
+};

app/tests/tap-dance/3c-tap-int-after/events.patterns

@@ -0,0 +1,2 @@
+s/.*hid_listener_keycode/kp/p
+s/.*on_tap_dance_binding/td_binding/p

app/tests/tap-dance/3c-tap-int-after/keycode_events.snapshot

@@ -0,0 +1,10 @@
+td_binding_pressed: 2 created new tap dance
+td_binding_pressed: 2 tap dance pressed
+td_binding_released: 2 tap dance keybind released
+kp_pressed: usage_page 0x07 keycode 0x1e implicit_mods 0x00 explicit_mods 0x00
+kp_released: usage_page 0x07 keycode 0x1e implicit_mods 0x00 explicit_mods 0x00
+td_binding_pressed: 1 created new tap dance
+td_binding_pressed: 1 tap dance pressed
+kp_pressed: usage_page 0x07 keycode 0x16 implicit_mods 0x00 explicit_mods 0x00
+td_binding_released: 1 tap dance keybind released
+kp_released: usage_page 0x07 keycode 0x16 implicit_mods 0x00 explicit_mods 0x00

app/tests/tap-dance/3c-tap-int-after/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)
+        ZMK_MOCK_RELEASE(1,0,10)
+        ZMK_MOCK_PRESS(0,1,10)
+        ZMK_MOCK_RELEASE(0,1,10)
+	>;
+};

app/tests/tap-dance/3d-hold-int-mid/events.patterns

@@ -0,0 +1,2 @@
+s/.*hid_listener_keycode/kp/p
+s/.*on_tap_dance_binding/td_binding/p

app/tests/tap-dance/3d-hold-int-mid/keycode_events.snapshot

@@ -0,0 +1,10 @@
+td_binding_pressed: 0 created new tap dance
+td_binding_pressed: 0 tap dance pressed
+kp_pressed: usage_page 0x07 keycode 0xe1 implicit_mods 0x00 explicit_mods 0x00
+td_binding_pressed: 1 created new tap dance
+td_binding_pressed: 1 tap dance pressed
+kp_pressed: usage_page 0x07 keycode 0x16 implicit_mods 0x00 explicit_mods 0x00
+td_binding_released: 1 tap dance keybind released
+kp_released: usage_page 0x07 keycode 0x16 implicit_mods 0x00 explicit_mods 0x00
+td_binding_released: 0 tap dance keybind released
+kp_released: usage_page 0x07 keycode 0xe1 implicit_mods 0x00 explicit_mods 0x00

app/tests/tap-dance/3d-hold-int-mid/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(0,0,400)
+        ZMK_MOCK_PRESS(0,1,10)
+        ZMK_MOCK_RELEASE(0,1,10)
+        ZMK_MOCK_RELEASE(0,0,10)
+	>;
+};

app/tests/tap-dance/3e-hold-int-seq/events.patterns

@@ -0,0 +1,2 @@
+s/.*hid_listener_keycode/kp/p
+s/.*on_tap_dance_binding/td_binding/p

app/tests/tap-dance/3e-hold-int-seq/keycode_events.snapshot

@@ -0,0 +1,10 @@
+td_binding_pressed: 0 created new tap dance
+td_binding_pressed: 0 tap dance pressed
+kp_pressed: usage_page 0x07 keycode 0xe1 implicit_mods 0x00 explicit_mods 0x00
+td_binding_pressed: 1 created new tap dance
+td_binding_pressed: 1 tap dance pressed
+kp_pressed: usage_page 0x07 keycode 0x16 implicit_mods 0x00 explicit_mods 0x00
+td_binding_released: 0 tap dance keybind released
+kp_released: usage_page 0x07 keycode 0xe1 implicit_mods 0x00 explicit_mods 0x00
+td_binding_released: 1 tap dance keybind released
+kp_released: usage_page 0x07 keycode 0x16 implicit_mods 0x00 explicit_mods 0x00

app/tests/tap-dance/3e-hold-int-seq/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(0,0,400)
+        ZMK_MOCK_PRESS(0,1,10)
+        ZMK_MOCK_RELEASE(0,0,10)
+        ZMK_MOCK_RELEASE(0,1,10)
+	>;
+};

app/tests/tap-dance/3f-hold-int-after/events.patterns

@@ -0,0 +1,2 @@
+s/.*hid_listener_keycode/kp/p
+s/.*on_tap_dance_binding/td_binding/p

app/tests/tap-dance/3f-hold-int-after/keycode_events.snapshot

@@ -0,0 +1,10 @@
+td_binding_pressed: 0 created new tap dance
+td_binding_pressed: 0 tap dance pressed
+kp_pressed: usage_page 0x07 keycode 0xe1 implicit_mods 0x00 explicit_mods 0x00
+td_binding_released: 0 tap dance keybind released
+kp_released: usage_page 0x07 keycode 0xe1 implicit_mods 0x00 explicit_mods 0x00
+td_binding_pressed: 1 created new tap dance
+td_binding_pressed: 1 tap dance pressed
+kp_pressed: usage_page 0x07 keycode 0x16 implicit_mods 0x00 explicit_mods 0x00
+td_binding_released: 1 tap dance keybind released
+kp_released: usage_page 0x07 keycode 0x16 implicit_mods 0x00 explicit_mods 0x00

app/tests/tap-dance/3f-hold-int-after/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(0,0,400)
+        ZMK_MOCK_RELEASE(0,0,10)
+        ZMK_MOCK_PRESS(0,1,10)
+        ZMK_MOCK_RELEASE(0,1,10)
+	>;
+};

app/tests/tap-dance/4a-single/events.patterns

@@ -0,0 +1,2 @@
+s/.*hid_listener_keycode/kp/p
+s/.*on_tap_dance_binding/td_binding/p

app/tests/tap-dance/4a-single/keycode_events.snapshot

@@ -0,0 +1,5 @@
+td_binding_pressed: 1 created new tap dance
+td_binding_pressed: 1 tap dance pressed
+kp_pressed: usage_page 0x07 keycode 0x16 implicit_mods 0x00 explicit_mods 0x00
+td_binding_released: 1 tap dance keybind released
+kp_released: usage_page 0x07 keycode 0x16 implicit_mods 0x00 explicit_mods 0x00

app/tests/tap-dance/4a-single/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,1,10)
+		ZMK_MOCK_RELEASE(0,1,10)
+	>;
+};

app/tests/tap-dance/5a-tdint-mid/events.patterns

@@ -0,0 +1,2 @@
+s/.*hid_listener_keycode/kp/p
+s/.*on_tap_dance_binding/td_binding/p

app/tests/tap-dance/5a-tdint-mid/keycode_events.snapshot

@@ -0,0 +1,10 @@
+td_binding_pressed: 2 created new tap dance
+td_binding_pressed: 2 tap dance pressed
+kp_pressed: usage_page 0x07 keycode 0x1e implicit_mods 0x00 explicit_mods 0x00
+td_binding_pressed: 3 created new tap dance
+td_binding_pressed: 3 tap dance pressed
+td_binding_released: 3 tap dance keybind released
+td_binding_released: 2 tap dance keybind released
+kp_released: usage_page 0x07 keycode 0x1e implicit_mods 0x00 explicit_mods 0x00
+kp_pressed: usage_page 0x07 keycode 0x04 implicit_mods 0x00 explicit_mods 0x00
+kp_released: usage_page 0x07 keycode 0x04 implicit_mods 0x00 explicit_mods 0x00

app/tests/tap-dance/5a-tdint-mid/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)
+        ZMK_MOCK_PRESS(1,1,10)
+        ZMK_MOCK_RELEASE(1,1,10)
+        ZMK_MOCK_RELEASE(1,0,200)
+	>;
+};

app/tests/tap-dance/5b-tdint-seq/events.patterns

@@ -0,0 +1,2 @@
+s/.*hid_listener_keycode/kp/p
+s/.*on_tap_dance_binding/td_binding/p

app/tests/tap-dance/5b-tdint-seq/keycode_events.snapshot

@@ -0,0 +1,10 @@
+td_binding_pressed: 2 created new tap dance
+td_binding_pressed: 2 tap dance pressed
+kp_pressed: usage_page 0x07 keycode 0x1e implicit_mods 0x00 explicit_mods 0x00
+td_binding_pressed: 3 created new tap dance
+td_binding_pressed: 3 tap dance pressed
+td_binding_released: 2 tap dance keybind released
+kp_released: usage_page 0x07 keycode 0x1e implicit_mods 0x00 explicit_mods 0x00
+td_binding_released: 3 tap dance keybind released
+kp_pressed: usage_page 0x07 keycode 0x04 implicit_mods 0x00 explicit_mods 0x00
+kp_released: usage_page 0x07 keycode 0x04 implicit_mods 0x00 explicit_mods 0x00

app/tests/tap-dance/5b-tdint-seq/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)
+        ZMK_MOCK_PRESS(1,1,10)
+        ZMK_MOCK_RELEASE(1,0,10)
+        ZMK_MOCK_RELEASE(1,1,200)
+	>;
+};

app/tests/tap-dance/5c-tdint-after/events.patterns

@@ -0,0 +1,2 @@
+s/.*hid_listener_keycode/kp/p
+s/.*on_tap_dance_binding/td_binding/p

app/tests/tap-dance/5c-tdint-after/keycode_events.snapshot

@@ -0,0 +1,10 @@
+td_binding_pressed: 2 created new tap dance
+td_binding_pressed: 2 tap dance pressed
+td_binding_released: 2 tap dance keybind released
+kp_pressed: usage_page 0x07 keycode 0x1e implicit_mods 0x00 explicit_mods 0x00
+kp_released: usage_page 0x07 keycode 0x1e implicit_mods 0x00 explicit_mods 0x00
+td_binding_pressed: 3 created new tap dance
+td_binding_pressed: 3 tap dance pressed
+td_binding_released: 3 tap dance keybind released
+kp_pressed: usage_page 0x07 keycode 0x04 implicit_mods 0x00 explicit_mods 0x00
+kp_released: usage_page 0x07 keycode 0x04 implicit_mods 0x00 explicit_mods 0x00

app/tests/tap-dance/5c-tdint-after/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)
+        ZMK_MOCK_RELEASE(1,0,10)
+        ZMK_MOCK_PRESS(1,1,10)
+        ZMK_MOCK_RELEASE(1,1,200)
+	>;
+};

app/tests/tap-dance/5d-tdint-multiple/events.patterns

@@ -0,0 +1,2 @@
+s/.*hid_listener_keycode/kp/p
+s/.*on_tap_dance_binding/td_binding/p

app/tests/tap-dance/5d-tdint-multiple/keycode_events.snapshot

@@ -0,0 +1,15 @@
+td_binding_pressed: 2 created new tap dance
+td_binding_pressed: 2 tap dance pressed
+td_binding_released: 2 tap dance keybind released
+kp_pressed: usage_page 0x07 keycode 0x1e implicit_mods 0x00 explicit_mods 0x00
+kp_released: usage_page 0x07 keycode 0x1e implicit_mods 0x00 explicit_mods 0x00
+td_binding_pressed: 3 created new tap dance
+td_binding_pressed: 3 tap dance pressed
+td_binding_released: 3 tap dance keybind released
+kp_pressed: usage_page 0x07 keycode 0x04 implicit_mods 0x00 explicit_mods 0x00
+kp_released: usage_page 0x07 keycode 0x04 implicit_mods 0x00 explicit_mods 0x00
+td_binding_pressed: 2 created new tap dance
+td_binding_pressed: 2 tap dance pressed
+td_binding_released: 2 tap dance keybind released
+kp_pressed: usage_page 0x07 keycode 0x1e implicit_mods 0x00 explicit_mods 0x00
+kp_released: usage_page 0x07 keycode 0x1e implicit_mods 0x00 explicit_mods 0x00

app/tests/tap-dance/5d-tdint-multiple/native_posix.keymap

@@ -0,0 +1,15 @@
+#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)
+        ZMK_MOCK_RELEASE(1,0,10)
+        ZMK_MOCK_PRESS(1,1,10)
+        ZMK_MOCK_RELEASE(1,1,10)
+        ZMK_MOCK_PRESS(1,0,10)
+        ZMK_MOCK_RELEASE(1,0,200)
+	>;
+};

app/tests/tap-dance/behavior_keymap.dtsi

@@ -0,0 +1,60 @@
+#include <dt-bindings/zmk/keys.h>
+#include <behaviors.dtsi>
+#include <dt-bindings/zmk/kscan_mock.h>
+
+/ {
+	behaviors {
+        ht: hold_tap {
+            compatible = "zmk,behavior-hold-tap";
+            label = "HOLD_TAP";
+            #binding-cells = <2>;
+            tapping-term-ms = <200>;
+            quick_tap_ms = <0>;
+            flavor = "tap-preferred";
+            bindings = <&kp>, <&kp>;
+        };
+
+        tdm: tap_dance_mixed {
+            compatible = "zmk,behavior-tap-dance";
+            label = "TAP_DANCE_MOD";
+            #binding-cells = <0>;
+            tapping-term-ms = <200>;
+            bindings = <&ht LSHIFT A>, <&ht LALT B>, <&ht LGUI C>;
+        };
+
+        tdb: tap_dance_basic {
+            compatible = "zmk,behavior-tap-dance";
+            label = "TAP_DANCE_BASIC";
+            #binding-cells = <0>;
+            tapping-term-ms = <200>;
+            bindings = <&kp N1>, <&kp N2>, <&kp N3>;
+        };
+
+        td2: tap_dance_basic_2 {
+            compatible = "zmk,behavior-tap-dance";
+            label = "TAP_DANCE_BASIC_2";
+            #binding-cells = <0>;
+            tapping-term-ms = <200>;
+            bindings = <&kp A>, <&kp B>, <&kp C>;
+        };
+
+        tds: tap_dance_single {
+            compatible = "zmk,behavior-tap-dance";
+            label = "TAP_DANCE_SINGlE";
+            #binding-cells = <0>;
+            tapping-term-ms = <200>;
+            bindings = <&kp S>;
+        };
+    };
+
+	keymap {
+		compatible = "zmk,keymap";
+		label ="Default keymap";
+
+		default_layer {
+			bindings = <
+				&tdm    &tds
+				&tdb    &td2>;
+		};
+	};
+};

docs/docs/behaviors/tap-dance.md

@@ -0,0 +1,76 @@
+---
+title: Tap-Dance Behavior
+sidebar_label: Tap-Dance
+---
+
+## Summary
+
+A tap-dance key invokes a different behavior (e.g. `kp`) corresponding
+to how many times it is pressed. For example, you could configure a
+tap-dance key that acts as `LSHIFT` if tapped once, or Caps _Lock_ if tapped twice.
+The expandability of the number of [`bindings`](#bindings) attached to a
+particular tap-dance is a great way to add more functionality to a single key,
+especially for keyboards with a limited number of keys.
+Tap-dances are completely custom, so for every unique tap-dance key,
+a new tap-dance must be defined in your keymap's `behaviors`.
+
+Tap-dances are designed to resolve immediately when interrupted by another keypress.
+Meaning, when a keybind is pressed other than any active tap-dances,
+the tap-dance will activate according to the current value of its
+counter before the interrupting keybind is registered.
+
+### Configuration
+
+#### `tapping-term-ms`
+
+Defines the maximum elapsed time after the last tap-dance keybind press
+before a binding is selected from [`bindings`](#bindings).
+Default value is `200`ms.
+
+#### `bindings`
+
+An array of one or more keybinds. This list can include [any ZMK keycode](../codes/) and bindings for ZMK behaviors.
+
+#### Example Usage
+
+This example configures a tap-dance named `td0` that outputs the number of times it is pressed from 1-3.
+
+```
+#include <behaviors.dtsi>
+#include <dt-bindings/zmk/keys.h>
+
+/ {
+	behaviors {
+		td0: tap_dance_0 {
+            compatible = "zmk,behavior-tap-dance";
+            label = "TAP_DANCE_0";
+            #binding-cells = <0>;
+            tapping-term-ms = <200>;
+            bindings = <&kp N1>, <&kp N2>, <&kp N3>;
+        };
+	};
+
+	keymap {
+		compatible = "zmk,keymap";
+
+		default_layer {
+			bindings = <
+	            &td0
+			>;
+		};
+	};
+};
+```
+
+The following image describes the behavior of this particular tap-dance.
+
+![Timing Diagram](../assets/tap-dance/timing_diagram.svg)
+
+:::note
+Alphanumeric [`key press`](key-press.md) bindings, like those used for `td0`,
+will release as soon as an interrupting key press occurs.
+For instance, if a modifier key like `LSHIFT` were to replace the `N1`
+binding in the last example above, it would remain pressed until `td0`'s
+binding is released and the output would instead be `J`. Any following
+alphanumeric key presses would be capitalized as long as `td0` is held down.
+:::

docs/sidebars.js

@@ -28,6 +28,7 @@ module.exports = {
       "behaviors/mod-morph",
       "behaviors/sticky-key",
       "behaviors/sticky-layer",
+      "behaviors/tap-dance",
       "behaviors/caps-word",
       "behaviors/key-repeat",
       "behaviors/reset",