Normalise Swap Hands keycodes (#19720)

16 files changed, 109 insertions, 47 deletions

diff --git a/data/constants/keycodes/keycodes_0.0.2.hjson b/data/constants/keycodes/keycodes_0.0.2.hjson
new file mode 100644
index 0000000000..0967ef424b
--- /dev/null
+++ b/data/constants/keycodes/keycodes_0.0.2.hjson
@@ -0,0 +1 @@
+{}
diff --git a/data/constants/keycodes/keycodes_0.0.2_swap_hands.hjson b/data/constants/keycodes/keycodes_0.0.2_swap_hands.hjson
new file mode 100644
index 0000000000..ddaa2c76b9
--- /dev/null
+++ b/data/constants/keycodes/keycodes_0.0.2_swap_hands.hjson
@@ -0,0 +1,53 @@
+{
+    "keycodes": {
+        "0x56F0": {
+            "group": "swap_hands",
+            "key": "QK_SWAP_HANDS_TOGGLE",
+            "aliases": [
+                "SH_TOGG"
+            ]
+        },
+        "0x56F1": {
+            "group": "swap_hands",
+            "key": "QK_SWAP_HANDS_TAP_TOGGLE",
+            "aliases": [
+                "SH_TT"
+            ]
+        },
+        "0x56F2": {
+            "group": "swap_hands",
+            "key": "QK_SWAP_HANDS_MOMENTARY_ON",
+            "aliases": [
+                "SH_MON"
+            ]
+        },
+        "0x56F3": {
+            "group": "swap_hands",
+            "key": "QK_SWAP_HANDS_MOMENTARY_OFF",
+            "aliases": [
+                "SH_MOFF"
+            ]
+        },
+        "0x56F4": {
+            "group": "swap_hands",
+            "key": "QK_SWAP_HANDS_OFF",
+            "aliases": [
+                "SH_OFF"
+            ]
+        },
+        "0x56F5": {
+            "group": "swap_hands",
+            "key": "QK_SWAP_HANDS_ON",
+            "aliases": [
+                "SH_ON"
+            ]
+        },
+        "0x56F6": {
+            "group": "swap_hands",
+            "key": "QK_SWAP_HANDS_ONE_SHOT",
+            "aliases": [
+                "SH_OS"
+            ]
+        }
+    }
+}
diff --git a/docs/feature_swap_hands.md b/docs/feature_swap_hands.md
index 6768020f12..35131884e1 100644
--- a/docs/feature_swap_hands.md
+++ b/docs/feature_swap_hands.md
@@ -19,18 +19,18 @@ Note that the array indices are reversed same as the matrix and the values are o
 
 ## Swap Keycodes
 
-|Key        |Description                                                              |
-|-----------|-------------------------------------------------------------------------|
-|`SH_T(key)`|Sends `key` with a tap; momentary swap when held.                        |
-|`SH_ON`    |Turns on swapping and leaves it on.                                      |
-|`SH_OFF`   |Turn off swapping and leaves it off. Good for returning to a known state.|
-|`SH_MON`   |Swaps hands when pressed, returns to normal when released (momentary).   |
-|`SH_MOFF`  |Momentarily turns off swap.                                              |
-|`SH_TG`    |Toggles swap on and off with every key press.                            |
-|`SH_TT`    |Momentary swap when held, toggles with repeated taps (see below).        |
-|`SH_OS`    |One shot swap hands: toggles while pressed or until next key press.      |
-
-`SH_TT` swap-hands tap-toggle key is similar to [layer tap-toggle](feature_layers.md?id=switching-and-toggling-layers). Tapping repeatedly (5 taps by default) will toggle swap-hands on or off, like `SH_TG`. Tap-toggle count can be changed by defining a value for `TAPPING_TOGGLE`.
+|Key                          |Aliases  |Description                                         |
+|-----------------------------|---------|----------------------------------------------------|
+|`SH_T(kc)`                   |         |Momentary swap when held, `kc` when tapped          |
+|`QK_SWAP_HANDS_ON`           |`SH_ON`  |Turn on hand swap                                   |
+|`QK_SWAP_HANDS_OFF`          |`SH_OFF` |Turn off hand swap                                  |
+|`QK_SWAP_HANDS_MOMENTARY_ON` |`SH_MON` |Turn on hand swap while held                        |
+|`QK_SWAP_HANDS_MOMENTARY_OFF`|`SH_MOFF`|Turn off hand swap while held                       |
+|`QK_SWAP_HANDS_TOGGLE`       |`SH_TOGG`|Toggle hand swap                                    |
+|`QK_SWAP_HANDS_TAP_TOGGLE`   |`SH_TT`  |Momentary swap when held, toggle when tapped        |
+|`QK_SWAP_HANDS_ONE_SHOT`     |`SH_OS`  |Turn on hand swap while held or until next key press|
+
+`SH_TT` swap-hands tap-toggle key is similar to [layer tap-toggle](feature_layers.md?id=switching-and-toggling-layers). Tapping repeatedly (5 taps by default) will toggle swap-hands on or off, like `SH_TOGG`. Tap-toggle count can be changed by defining a value for `TAPPING_TOGGLE`.
 
 ## Encoder Mapping
 
diff --git a/docs/keycodes.md b/docs/keycodes.md
index f660c7f526..b3be0847e8 100644
--- a/docs/keycodes.md
+++ b/docs/keycodes.md
@@ -819,16 +819,16 @@ See also: [Space Cadet](feature_space_cadet.md)
 
 See also: [Swap Hands](feature_swap_hands.md)
 
-|Key        |Description                                                              |
-|-----------|-------------------------------------------------------------------------|
-|`SH_T(key)`|Sends `key` with a tap; momentary swap when held.                        |
-|`SH_ON`    |Turns on swapping and leaves it on.                                      |
-|`SH_OFF`   |Turn off swapping and leaves it off. Good for returning to a known state.|
-|`SH_MON`   |Swaps hands when pressed, returns to normal when released (momentary).   |
-|`SH_MOFF`  |Momentarily turns off swap.                                              |
-|`SH_TG`    |Toggles swap on and off with every key press.                            |
-|`SH_TT`    |Toggles with a tap; momentary when held.                                 |
-|`SH_OS`    |One shot swap hands: toggle while pressed or until next key press.       |
+|Key                          |Aliases  |Description                                         |
+|-----------------------------|---------|----------------------------------------------------|
+|`SH_T(kc)`                   |         |Momentary swap when held, `kc` when tapped          |
+|`QK_SWAP_HANDS_ON`           |`SH_ON`  |Turn on hand swap                                   |
+|`QK_SWAP_HANDS_OFF`          |`SH_OFF` |Turn off hand swap                                  |
+|`QK_SWAP_HANDS_MOMENTARY_ON` |`SH_MON` |Turn on hand swap while held                        |
+|`QK_SWAP_HANDS_MOMENTARY_OFF`|`SH_MOFF`|Turn off hand swap while held                       |
+|`QK_SWAP_HANDS_TOGGLE`       |`SH_TOGG`|Toggle hand swap                                    |
+|`QK_SWAP_HANDS_TAP_TOGGLE`   |`SH_TT`  |Momentary swap when held, toggle when tapped        |
+|`QK_SWAP_HANDS_ONE_SHOT`     |`SH_OS`  |Turn on hand swap while held or until next key press|
 
 ## Unicode Support :id=unicode-support
 
diff --git a/keyboards/jian/keymaps/advanced/keymap.c b/keyboards/jian/keymaps/advanced/keymap.c
index f06be1f2ed..6b308a4820 100644
--- a/keyboards/jian/keymaps/advanced/keymap.c
+++ b/keyboards/jian/keymaps/advanced/keymap.c
@@ -181,7 +181,7 @@ static uint8_t layout_conversion_dip_state = 0;
 #define LAYOUT_base_wrapper(...) LAYOUT_base(__VA_ARGS__)
 
 #ifdef SWAP_HANDS_ENABLE
-#define SW_TG SH_TG
+#define SW_TG SH_TOGG
 #else
 #define SW_TG _______
 #endif
diff --git a/keyboards/jian/keymaps/default/keymap.c b/keyboards/jian/keymaps/default/keymap.c
index 8a1234e1aa..3948dd119f 100644
--- a/keyboards/jian/keymaps/default/keymap.c
+++ b/keyboards/jian/keymaps/default/keymap.c
@@ -22,7 +22,7 @@ enum jian_keycodes {
 #define LOWER_T(kc) LT(_LOWER, kc)
 
 #ifdef SWAP_HANDS_ENABLE
-#define SW_TG SH_TG
+#define SW_TG SH_TOGG
 #else
 #define SW_TG _______
 #endif
diff --git a/keyboards/jian/keymaps/via/keymap.c b/keyboards/jian/keymaps/via/keymap.c
index 5844ef16e8..3d6c7507ba 100644
--- a/keyboards/jian/keymaps/via/keymap.c
+++ b/keyboards/jian/keymaps/via/keymap.c
@@ -23,6 +23,6 @@ const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
   QK_BOOT, DB_TOGG, XXXXXXX, BL_UP,   RGB_VAI, RGB_HUD, RGB_HUI,
            XXXXXXX, XXXXXXX, BL_DOWN, RGB_VAD, RGB_SAD, RGB_SAI,
            XXXXXXX, BL_BRTG, BL_TOGG, RGB_TOG, RGB_RMOD,RGB_MOD,
-                                      _______, SH_TG,   _______
+                                      _______, SH_TOGG, _______
 )
 };
diff --git a/keyboards/jorne/keymaps/default/keymap.c b/keyboards/jorne/keymaps/default/keymap.c
index 7484fc3e94..f37dc1c445 100644
--- a/keyboards/jorne/keymaps/default/keymap.c
+++ b/keyboards/jorne/keymaps/default/keymap.c
@@ -59,7 +59,7 @@ const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
   QK_BOOT, RGBRST,  AS_UP,   AS_TOGG, AS_DOWN, _______, _______,      _______, _______, AS_DOWN, AS_TOGG, AS_UP,   RGBRST,  QK_BOOT,
            RGB_TOG, RGB_HUI, RGB_SAI, RGB_VAI, _______, _______,      _______, _______, RGB_VAI, RGB_SAI, RGB_HUI, RGB_TOG,
            RGB_MOD, RGB_HUD, RGB_SAD, RGB_VAD, _______, _______,      _______, _______, RGB_VAD, RGB_SAD, RGB_HUD, RGB_MOD,
-                                      _______, SH_TG,   _______,      _______, SH_TG,   _______
+                                      _______, SH_TOGG, _______,      _______, SH_TOGG, _______
 ),
 
 };
diff --git a/keyboards/jorne/keymaps/via/keymap.c b/keyboards/jorne/keymaps/via/keymap.c
index 7484fc3e94..f37dc1c445 100644
--- a/keyboards/jorne/keymaps/via/keymap.c
+++ b/keyboards/jorne/keymaps/via/keymap.c
@@ -59,7 +59,7 @@ const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
   QK_BOOT, RGBRST,  AS_UP,   AS_TOGG, AS_DOWN, _______, _______,      _______, _______, AS_DOWN, AS_TOGG, AS_UP,   RGBRST,  QK_BOOT,
            RGB_TOG, RGB_HUI, RGB_SAI, RGB_VAI, _______, _______,      _______, _______, RGB_VAI, RGB_SAI, RGB_HUI, RGB_TOG,
            RGB_MOD, RGB_HUD, RGB_SAD, RGB_VAD, _______, _______,      _______, _______, RGB_VAD, RGB_SAD, RGB_HUD, RGB_MOD,
-                                      _______, SH_TG,   _______,      _______, SH_TG,   _______
+                                      _______, SH_TOGG, _______,      _______, SH_TOGG, _______
 ),
 
 };
diff --git a/keyboards/planck/keymaps/rootiest/keymap.c b/keyboards/planck/keymaps/rootiest/keymap.c
index 616a337daf..5aec280af3 100644
--- a/keyboards/planck/keymaps/rootiest/keymap.c
+++ b/keyboards/planck/keymaps/rootiest/keymap.c
@@ -414,7 +414,7 @@ const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
     */
     [_TABULA] = LAYOUT_planck_mit(                                                                                                   //
         KC_ESC, KC_ALTF4, VK_TOGG, PRINT_WPM_KEY, WAKE_ANI_TOG, WAKE_AUD_TOG, KC_REDO, UC_NEXT, UC_WINC, CG_TOGG, AG_TOGG, KC_DLINE,  //
-        KC_NXTAB, KC_SLCTALL, KC_SAVE, KC_TRNS, KC_FIND, SH_TG, SH_TG, IRONY, KC_LCUT, KC_LCOPY, KC_TRNS, KC_KILL,                   //
+        KC_NXTAB, KC_SLCTALL, KC_SAVE, KC_TRNS, KC_FIND, SH_TOGG, SH_TOGG, IRONY, KC_LCUT, KC_LCOPY, KC_TRNS, KC_KILL,                   //
         KC_LSFT, KC_UNDO, KC_CUT, KC_COPY, KC_PASTE, KC_PRVWD, KC_NXTWD, TG(_MOUSY), KC_TRNS, KC_HOME, KC_END, SC_SENT,              //
         TO(_BASE), KC_LCTL, KC_LGUI, KC_LALT, SC_LSPO, ALT_TAB, SC_RSPC, KC_PRVWD, KC_BRID, KC_BRIU, KC_NXTWD),
     /* Tabular Layer [8]
diff --git a/keyboards/signum/3_0/keymaps/default/layout.py b/keyboards/signum/3_0/keymaps/default/layout.py
index 68f08ef212..90fb1d9c94 100644
--- a/keyboards/signum/3_0/keymaps/default/layout.py
+++ b/keyboards/signum/3_0/keymaps/default/layout.py
@@ -388,7 +388,7 @@ qmk_dict = {
     "acc2": "KC_ACL2",
     # Modifiers missinng, add entry for each specific application
     # Mod-Tap Keys missing, add entry for each specific application
-    "_Sh_swp": "LSFT_T(SH_TG)",
+    "_Sh_swp": "LSFT_T(SH_TOGG)",
     # RGB Lighting missing
     # RGB Matrix Lighting missing
     # Thermal Printer missing
diff --git a/quantum/keycodes.h b/quantum/keycodes.h
index b5f0a32500..eafa9eb1b6 100644
--- a/quantum/keycodes.h
+++ b/quantum/keycodes.h
@@ -304,13 +304,13 @@ enum qk_keycode_defines {
     KC_RIGHT_SHIFT = 0x00E5,
     KC_RIGHT_ALT = 0x00E6,
     KC_RIGHT_GUI = 0x00E7,
-    SH_TG = 0x56F0,
-    SH_TT = 0x56F1,
-    SH_MON = 0x56F2,
-    SH_MOFF = 0x56F3,
-    SH_OFF = 0x56F4,
-    SH_ON = 0x56F5,
-    SH_OS = 0x56F6,
+    QK_SWAP_HANDS_TOGGLE = 0x56F0,
+    QK_SWAP_HANDS_TAP_TOGGLE = 0x56F1,
+    QK_SWAP_HANDS_MOMENTARY_ON = 0x56F2,
+    QK_SWAP_HANDS_MOMENTARY_OFF = 0x56F3,
+    QK_SWAP_HANDS_OFF = 0x56F4,
+    QK_SWAP_HANDS_ON = 0x56F5,
+    QK_SWAP_HANDS_ONE_SHOT = 0x56F6,
     MAGIC_SWAP_CONTROL_CAPSLOCK = 0x7000,
     MAGIC_UNSWAP_CONTROL_CAPSLOCK = 0x7001,
     MAGIC_TOGGLE_CONTROL_CAPSLOCK = 0x7002,
@@ -863,6 +863,13 @@ enum qk_keycode_defines {
     KC_RGUI    = KC_RIGHT_GUI,
     KC_RCMD    = KC_RIGHT_GUI,
     KC_RWIN    = KC_RIGHT_GUI,
+    SH_TOGG    = QK_SWAP_HANDS_TOGGLE,
+    SH_TT      = QK_SWAP_HANDS_TAP_TOGGLE,
+    SH_MON     = QK_SWAP_HANDS_MOMENTARY_ON,
+    SH_MOFF    = QK_SWAP_HANDS_MOMENTARY_OFF,
+    SH_OFF     = QK_SWAP_HANDS_OFF,
+    SH_ON      = QK_SWAP_HANDS_ON,
+    SH_OS      = QK_SWAP_HANDS_ONE_SHOT,
     CL_SWAP    = MAGIC_SWAP_CONTROL_CAPSLOCK,
     CL_NORM    = MAGIC_UNSWAP_CONTROL_CAPSLOCK,
     CL_TOGG    = MAGIC_TOGGLE_CONTROL_CAPSLOCK,
@@ -1309,7 +1316,7 @@ enum qk_keycode_defines {
 #define IS_MEDIA_KEYCODE(code) ((code) >= KC_AUDIO_MUTE && (code) <= KC_ASSISTANT)
 #define IS_MOUSE_KEYCODE(code) ((code) >= KC_MS_UP && (code) <= KC_MS_ACCEL2)
 #define IS_MODIFIERS_KEYCODE(code) ((code) >= KC_LEFT_CTRL && (code) <= KC_RIGHT_GUI)
-#define IS_SWAP_HANDS_KEYCODE(code) ((code) >= SH_TG && (code) <= SH_OS)
+#define IS_SWAP_HANDS_KEYCODE(code) ((code) >= QK_SWAP_HANDS_TOGGLE && (code) <= QK_SWAP_HANDS_ONE_SHOT)
 #define IS_MAGIC_KEYCODE(code) ((code) >= MAGIC_SWAP_CONTROL_CAPSLOCK && (code) <= MAGIC_TOGGLE_ESCAPE_CAPSLOCK)
 #define IS_MIDI_KEYCODE(code) ((code) >= QK_MIDI_ON && (code) <= QK_MIDI_PITCH_BEND_UP)
 #define IS_SEQUENCER_KEYCODE(code) ((code) >= SQ_ON && (code) <= SQ_SCLR)
diff --git a/quantum/process_keycode/process_autocorrect.c b/quantum/process_keycode/process_autocorrect.c
index 8aeebf0e06..c89dffeaad 100644
--- a/quantum/process_keycode/process_autocorrect.c
+++ b/quantum/process_keycode/process_autocorrect.c
@@ -126,7 +126,7 @@ __attribute__((weak)) bool process_autocorrect_user(uint16_t *keycode, keyrecord
         // and mask for base keycode when they are tapped.
         case QK_SWAP_HANDS ... QK_SWAP_HANDS_MAX:
 #ifdef SWAP_HANDS_ENABLE
-            // Note: IS_SWAP_HANDS_KEYCODE() actually tests for the special action keycodes like SH_TG, SH_TT, ...,
+            // Note: IS_SWAP_HANDS_KEYCODE() actually tests for the special action keycodes like SH_TOGG, SH_TT, ...,
             // which currently overlap the SH_T(kc) range.
             if (IS_SWAP_HANDS_KEYCODE(*keycode) || !record->tap.count) {
                 return false;
diff --git a/quantum/process_keycode/process_caps_word.c b/quantum/process_keycode/process_caps_word.c
index 4c0217eba7..933abe629e 100644
--- a/quantum/process_keycode/process_caps_word.c
+++ b/quantum/process_keycode/process_caps_word.c
@@ -143,7 +143,7 @@ bool process_caps_word(uint16_t keycode, keyrecord_t* record) {
 
 #ifdef SWAP_HANDS_ENABLE
             case QK_SWAP_HANDS ... QK_SWAP_HANDS_MAX:
-                // Note: IS_SWAP_HANDS_KEYCODE() actually tests for the special action keycodes like SH_TG, SH_TT, ...,
+                // Note: IS_SWAP_HANDS_KEYCODE() actually tests for the special action keycodes like SH_TOGG, SH_TT, ...,
                 // which currently overlap the SH_T(kc) range.
                 if (IS_SWAP_HANDS_KEYCODE(keycode) || record->tap.count == 0) {
                     return true;
diff --git a/quantum/quantum_keycodes_legacy.h b/quantum/quantum_keycodes_legacy.h
index 51ec77bae0..28634d00f7 100644
--- a/quantum/quantum_keycodes_legacy.h
+++ b/quantum/quantum_keycodes_legacy.h
@@ -3,3 +3,4 @@
 // clang-format off
 
 // Deprecated Quantum keycodes
+#define SH_TG QK_SWAP_HANDS_TOGGLE
diff --git a/tests/test_common/keycode_table.cpp b/tests/test_common/keycode_table.cpp
index 63350c272d..ab9c292e95 100644
--- a/tests/test_common/keycode_table.cpp
+++ b/tests/test_common/keycode_table.cpp
@@ -1,4 +1,4 @@
-// Copyright 2022 QMK
+// Copyright 2023 QMK
 // SPDX-License-Identifier: GPL-2.0-or-later
 
 /*******************************************************************************
@@ -250,13 +250,13 @@ std::map<uint16_t, std::string> KEYCODE_ID_TABLE = {
     {KC_RIGHT_SHIFT, "KC_RIGHT_SHIFT"},
     {KC_RIGHT_ALT, "KC_RIGHT_ALT"},
     {KC_RIGHT_GUI, "KC_RIGHT_GUI"},
-    {SH_TG, "SH_TG"},
-    {SH_TT, "SH_TT"},
-    {SH_MON, "SH_MON"},
-    {SH_MOFF, "SH_MOFF"},
-    {SH_OFF, "SH_OFF"},
-    {SH_ON, "SH_ON"},
-    {SH_OS, "SH_OS"},
+    {QK_SWAP_HANDS_TOGGLE, "QK_SWAP_HANDS_TOGGLE"},
+    {QK_SWAP_HANDS_TAP_TOGGLE, "QK_SWAP_HANDS_TAP_TOGGLE"},
+    {QK_SWAP_HANDS_MOMENTARY_ON, "QK_SWAP_HANDS_MOMENTARY_ON"},
+    {QK_SWAP_HANDS_MOMENTARY_OFF, "QK_SWAP_HANDS_MOMENTARY_OFF"},
+    {QK_SWAP_HANDS_OFF, "QK_SWAP_HANDS_OFF"},
+    {QK_SWAP_HANDS_ON, "QK_SWAP_HANDS_ON"},
+    {QK_SWAP_HANDS_ONE_SHOT, "QK_SWAP_HANDS_ONE_SHOT"},
     {MAGIC_SWAP_CONTROL_CAPSLOCK, "MAGIC_SWAP_CONTROL_CAPSLOCK"},
     {MAGIC_UNSWAP_CONTROL_CAPSLOCK, "MAGIC_UNSWAP_CONTROL_CAPSLOCK"},
     {MAGIC_TOGGLE_CONTROL_CAPSLOCK, "MAGIC_TOGGLE_CONTROL_CAPSLOCK"},