Feature request: layer-toggle should probably toggle a layer

[ToyKeeper]

Is your feature request related to a problem? Please describe.

In the current version (2025-11), layer-toggle is an alias for layer-while-held. If I understand correctly, it was renamed to make the name better represent what it does, and the old name was kept for backward compatibility, so it may not be feasible to change the behavior of layer-toggle directly. But there should still be a clearly-named function to actually toggle a non-base layer on and off.

My suggestion would be sticky-layer-toggle or layer-lock-toggle or something like that. It would make the functionality much more discoverable for new users. Something with "layer" and "toggle" in the name, and an extra word to differentiate it from the existing layer-toggle function.

For use cases, it's pretty common for people to have a lockable numpad layer, or other layers which "stick" until deactivated. On my QMK boards, I have MouseLock, NumpadLock, FnRowLock, and MoonLock... but these are tricky to implement in Kanata because layer-toggle doesn't toggle a layer in the same way it works in QMK. In Kanata it lasts only as long as the key is held.

In old bug reports I found a workaround. Here's an example config...

(deffakekeys
  numpadlock (layer-while-held lnumpad)
)
(defalias
  ;; toggle the lnumpad layer on or off
  lnum (on-press-fakekey numpadlock toggle)
  ;; tap to toggle lnumpad layer, hold for right ctrl
  rctl (tap-hold-press $tt $ht @lnum rctl)
  ;; or in Linux, with workaround for unintended key-repeat: (bug #422)
  ;;norepeat kana
  ;;rctl (multi @norepeat (tap-hold-press $tt $ht @lnum rctl))
)

... but it would be more straightforward and easier for new users with an official function. For example:

(defalias
  ;; toggle the lnumpad layer on or off
  lnum (sticky-layer-toggle lnumpad)
  ;; tap to toggle lnumpad layer, hold for right ctrl
  rctl (tap-hold-press $tt $ht @lnum rctl)
)

Describe the solution you'd like.

For this feature request, ideally there would be a new sticky-layer-toggle function, but it may also suffice to document the workaround somewhere visible and easily-searched.

Describe alternatives you've considered.

Fakekeys workaround in #360.

Additional context

In case it's helpful as a reference, here is my full config. It's for a Logitech K400+ in Linux. It has 4 switchable base layers, 2 momentary Fn layers, and 1 lockable overlay layer. The default layer is dvorak, but qwerty can be accessed by holding the upper-right key ("del") and tapping the lower-left key ("ctrl").

https://toykeeper.net/tmp/k400+.lisp