[Bug] Mod-tap doesn't work with KC_TRANSPARENT about qmk_firmware

[sigprof]

Unfortunately, the behavior that you expected here is not actually implemented — KC_TRANSPARENT is handled only by layer_switch_get_layer() during the keymap lookup, and does not work when embedded inside MT() or LT(). So KC_TRANSPARENT is not really a basic keycode for this kind of usage (i.e., something that could be sent directly to the host by register_code()), even though it fits into a single byte.

And internally QMK has some other definitions of what a “basic” keycode is — e.g., IS_BASIC_KEYCODE() and BASIC_KEYCODE_RANGE accept only the KC_A…KC_EXSEL range, which does not even include the modifiers, even though they are also a part of the Keyboard usage page; but IS_QK_BASIC() accepts the whole 0x00…0xFF range — i.e., anything which fits into a byte. So the issue of what is actually a basic keycode is somewhat complicated.

You may try to implement the behavior that you want in custom code — see the Intercepting Mod-Taps section for a way to change the tap function. Although you may need to be careful here — if the layer state changes between the press and release (which may happen for a tap if quick tap is enabled, which is the default), just using the current layer state to determine which keycode to register or unregister for a tap may result in stuck keys (although if you don't care about reporting holds with the quick tap feature properly, you may just call tap_code() on press and do nothing on release, which would avoid the problem).

Implementing that behavior in core (where it would need to work in the most generic way possible) may be difficult though — the problem is that it would require two instances of the source layers cache (one which would remember the layer where the MT() or LT() keycode came from, and another which would remember the layer where the underlying tap keycode had been found). And there is an even worse problem — what to do if the keycode under MT(mods, KC_TRANSPARENT) is not a basic keycode? (The existing code for mod-taps just does register_code(action.key.code) for a tap; this won't work if the second keymap lookup replaces KC_TRANSPARENT with a non-basic keycode.)

[VitalyArtemiev]

That's what I suspected. Can I submit a pull request for docs to communicate this caveat more clearly?
Thank you for your time.