feat(behaviors): hold while undecided

2 files changed, 24 insertions, 10 deletions

diff --git a/docs/docs/behaviors/hold-tap.mdx b/docs/docs/behaviors/hold-tap.mdx
index 26af9f1d83..191e820dd4 100644
--- a/docs/docs/behaviors/hold-tap.mdx
+++ b/docs/docs/behaviors/hold-tap.mdx
@@ -83,6 +83,18 @@ For example, if you press `&mt LEFT_SHIFT A` and then release it without pressin
 };
 ```
 
+#### `hold-while-undecided`
+
+If enabled, the hold behavior will immediately be held on hold-tap press, and will release before the behavior is sent in the event the hold-tap resolves into a tap. With most modifiers this will not affect typing, and is useful for using modifiers with the mouse.
+
+:::note Alt/Win/Cmd behavior
+In some applications/desktop environments, pressing Alt keycodes by itself will have its own behavior like activate a menu and Gui keycodes will bring up the start menu or an application launcher.
+:::
+
+#### `hold-while-undecided-linger`
+
+If your tap behavior activates the same modifier as the hold behavior, and you want to avoid a double tap when transitioning from the hold to the tap, you can use `hold-while-undecided-linger`. When enabled, the hold behavior will continue to be held until _after_ the tap behavior is released. For example, if the hold is `&kp LGUI` and the tap is `&sk LGUI`, then with `hold-while-undecided-linger` enabled, the host will see `LGUI` held down continuously until the sticky key is finished, instead of seeing a release and press when transitioning from hold to sticky key.
+
 #### Positional hold-tap and `hold-trigger-key-positions`
 
 Including `hold-trigger-key-positions` 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.
diff --git a/docs/docs/config/behaviors.md b/docs/docs/config/behaviors.md
index c31de5dd0a..f8d2fe39eb 100644
--- a/docs/docs/config/behaviors.md
+++ b/docs/docs/config/behaviors.md
@@ -57,16 +57,18 @@ Definition file: [zmk/app/dts/bindings/behaviors/zmk,behavior-hold-tap.yaml](htt
 
 Applies to: `compatible = "zmk,behavior-hold-tap"`
 
-| Property                     | Type          | Description                                                                                                    | Default            |
-| ---------------------------- | ------------- | -------------------------------------------------------------------------------------------------------------- | ------------------ |
-| `#binding-cells`             | int           | Must be `<2>`                                                                                                  |                    |
-| `bindings`                   | phandle array | A list of two behaviors (without parameters): one for hold and one for tap                                     |                    |
-| `flavor`                     | string        | Adjusts how the behavior chooses between hold and tap                                                          | `"hold-preferred"` |
-| `tapping-term-ms`            | int           | How long in milliseconds the key must be held to trigger a hold                                                |                    |
-| `quick-tap-ms`               | int           | Tap twice within this period (in milliseconds) to trigger a tap, even when held                                | -1 (disabled)      |
-| `require-prior-idle-ms`      | int           | Triggers a tap immediately if any non-modifier key was pressed within `require-prior-idle-ms` of the hold-tap. | -1 (disabled)      |
-| `retro-tap`                  | bool          | Triggers the tap behavior on release if no other key was pressed during a hold                                 | false              |
-| `hold-trigger-key-positions` | array         | If set, pressing the hold-tap and then any key position _not_ in the list triggers a tap.                      |                    |
+| Property                      | Type          | Description                                                                                                    | Default            |
+| ----------------------------- | ------------- | -------------------------------------------------------------------------------------------------------------- | ------------------ |
+| `#binding-cells`              | int           | Must be `<2>`                                                                                                  |                    |
+| `bindings`                    | phandle array | A list of two behaviors (without parameters): one for hold and one for tap                                     |                    |
+| `flavor`                      | string        | Adjusts how the behavior chooses between hold and tap                                                          | `"hold-preferred"` |
+| `tapping-term-ms`             | int           | How long in milliseconds the key must be held to trigger a hold                                                |                    |
+| `quick-tap-ms`                | int           | Tap twice within this period (in milliseconds) to trigger a tap, even when held                                | -1 (disabled)      |
+| `require-prior-idle-ms`       | int           | Triggers a tap immediately if any non-modifier key was pressed within `require-prior-idle-ms` of the hold-tap. | -1 (disabled)      |
+| `retro-tap`                   | bool          | Triggers the tap behavior on release if no other key was pressed during a hold                                 | false              |
+| `hold-while-undecided`        | bool          | Triggers the hold behavior immediately on press and releases before a tap                                      | false              |
+| `hold-while-undecided-linger` | bool          | Continues to hold the hold behavior until after the tap is released                                            | false              |
+| `hold-trigger-key-positions`  | array         | If set, pressing the hold-tap and then any key position _not_ in the list triggers a tap.                      |                    |
 
 This behavior forwards the first parameter it receives to the parameter of the first behavior specified in `bindings`, and second parameter to the parameter of the second behavior.