feat: Added `toggle-mode`, allowing toggle-on and toggle-off (#2555)

feat: added toggle mode to key and layer toggles

docs: documented toggle mode changes

3 files changed, 98 insertions, 0 deletions

diff --git a/docs/docs/config/behaviors.md b/docs/docs/config/behaviors.md
index e528325aeb..7df6d17660 100644
--- a/docs/docs/config/behaviors.md
+++ b/docs/docs/config/behaviors.md
@@ -17,6 +17,14 @@ See the [zmk/app/dts/behaviors/](https://github.com/zmkfirmware/zmk/tree/main/ap
 | --------------------------------- | ---- | ------------------------------------------------------------------------------------ | ------- |
 | `CONFIG_ZMK_BEHAVIORS_QUEUE_SIZE` | int  | Maximum number of behaviors to allow queueing from a macro or other complex behavior | 64      |
 
+### Devicetree
+
+Definition file: [zmk/app/dts/bindings/behaviors/behavior-metadata.yaml](https://github.com/zmkfirmware/zmk/blob/main/app/dts/bindings/behaviors/behavior-metadata.yaml)
+
+| Property       | Type   | Description                                                                      | Default |
+| -------------- | ------ | -------------------------------------------------------------------------------- | ------- |
+| `display-name` | string | Name of the layer, for use with a display or [ZMK Studio](../features/studio.md) |         |
+
 ## Caps Word
 
 Creates a custom behavior that behaves similar to a caps lock but deactivates when any key not in a continue list is pressed.
@@ -123,6 +131,52 @@ You can use the following nodes to tweak the default behaviors:
 | ------------- | ------------------------------------------------ |
 | `&key_repeat` | [Key repeat](../keymaps/behaviors/key-repeat.md) |
 
+## Key Toggle
+
+Creates a custom behavior that toggles a key code on, off, or switches between the two states.
+
+See the [key toggle behavior](../keymaps/behaviors/key-toggle.md) documentation for more details and examples.
+
+### Devicetree
+
+Definition file: [zmk/app/dts/bindings/behaviors/zmk,behavior-key-toggle.yaml](https://github.com/zmkfirmware/zmk/blob/main/app/dts/bindings/behaviors/zmk%2Cbehavior-key-toggle.yaml)
+
+Applies to: `compatible = "zmk,behavior-key-toggle"`
+
+| Property         | Type | Description                    | Default |
+| ---------------- | ---- | ------------------------------ | ------- |
+| `#binding-cells` | int  | Must be `<1>`                  |         |
+| `toggle-mode`    |      | One of `on`, `off`, and `flip` | `flip`  |
+
+You can use the following node to tweak the default behavior:
+
+| Node  | Behavior                                         |
+| ----- | ------------------------------------------------ |
+| `&kt` | [Key toggle](../keymaps/behaviors/key-toggle.md) |
+
+## Layer Toggle
+
+Creates a custom behavior that toggles a layer on, off, or switches between the two states.
+
+See the [layer toggle behavior](../keymaps/behaviors/layers.md#toggle-layer) documentation for more details and examples.
+
+### Devicetree
+
+Definition file: [zmk/app/dts/bindings/behaviors/zmk,behavior-layer-toggle.yaml](https://github.com/zmkfirmware/zmk/blob/main/app/dts/bindings/behaviors/zmk%2Cbehavior-layer-toggle.yaml)
+
+Applies to: `compatible = "zmk,behavior-layer-toggle"`
+
+| Property         | Type | Description                    | Default |
+| ---------------- | ---- | ------------------------------ | ------- |
+| `#binding-cells` | int  | Must be `<1>`                  |         |
+| `toggle-mode`    |      | One of `on`, `off`, and `flip` | `flip`  |
+
+You can use the following node to tweak the default behavior:
+
+| Node   | Behavior                                                    |
+| ------ | ----------------------------------------------------------- |
+| `&tog` | [Layer toggle](../keymaps/behaviors/layers.md#toggle-layer) |
+
 ## Macro
 
 Creates a custom behavior which triggers a sequence of other behaviors.
diff --git a/docs/docs/keymaps/behaviors/key-toggle.md b/docs/docs/keymaps/behaviors/key-toggle.md
index 8200b455da..173087cad4 100644
--- a/docs/docs/keymaps/behaviors/key-toggle.md
+++ b/docs/docs/keymaps/behaviors/key-toggle.md
@@ -24,3 +24,25 @@ Example:
 
 You can use any keycode that works for `&kp` as parameter to `&kt`, however, [modified keys](../modifiers.mdx#modifier-functions) such as `LA(A)` will be toggled based on the status of the base keycode (in this case `A`).
 In other words, modifiers are ignored when determining whether or not the key is currently pressed.
+
+### Configuration
+
+#### Toggle mode
+
+If you wish to ensure that a key is pressed or released, rather than merely toggling, then you can do so with the `toggle-mode` property.
+Define a new behavior and assign `"on"` or `"off"` to `toggle-mode`:
+
+```dts
+/ {
+    behaviors {
+        kt_on: key_toggle_on_only {
+            compatible = "zmk,behavior-key-toggle";
+            #binding-cells = <1>;
+            display-name = "Key Toggle On";
+            toggle-mode = "on";
+        };
+    };
+};
+```
+
+You can then use `&kt_on` in place of `&kt` whenever you wish to only toggle a key on, and not toggle it off. An `"off"` version of the behavior can be defined similarly.
diff --git a/docs/docs/keymaps/behaviors/layers.md b/docs/docs/keymaps/behaviors/layers.md
index 4a944dfbe4..162a433755 100644
--- a/docs/docs/keymaps/behaviors/layers.md
+++ b/docs/docs/keymaps/behaviors/layers.md
@@ -103,6 +103,28 @@ Example:
 &tog 3
 ```
 
+### Configuration
+
+#### Toggle mode
+
+If you wish to ensure that a layer is toggled on or off specifically, rather than switching between the two states, then you can do so with the `toggle-mode` property.
+Define a new behavior and assign `"on"` or `"off"` to `toggle-mode`:
+
+```dts
+/ {
+    behaviors {
+        tog_on: toggle_layer_on_only {
+            compatible = "zmk,behavior-toggle-layer";
+            #binding-cells = <1>;
+            display-name = "Toggle Layer On";
+            toggle-mode = "on";
+        };
+    };
+};
+```
+
+You can then use `&tog_on` in place of `&tog` whenever you wish to only toggle a layer on, and not toggle it off. An `"off"` version of the behavior can be defined similarly.
+
 ## Conditional Layers
 
 The "conditional layers" feature enables a particular layer when all layers in a specified set are active.