[Core] Add Chordal Hold, an "opposite hands rule" tap-hold option similar to Achordion, Bilateral Combinations. (#24560)

* Chordal Hold: restrict what chords settle as hold

* Chordal Hold: docs and further improvements

* Fix formatting.

* Doc rewording and minor edit.

* Support Chordal Hold of multiple tap-hold keys.

* Fix formatting.

* Simplification and additional test.

* Fix formatting.

* Tighten tests.

* Add test two_mod_taps_same_hand_hold_til_timeout.

* Revise handing of pairs of tap-hold keys.

* Generate a default chordal_hold_layout.

* Document chordal_hold_handedness().

* Add license notice to new and branched files in PR.

* Add `tapping.chordal_hold` property for info.json.

* Update docs/reference_info_json.md

* Revise "hand" jsonschema.

* Chordal Hold: Improved layout handedness heuristic.

This commit improves the heuristic used in generate-keyboard-c for
inferring key handedness from keyboard.json geometry data.

Heuristic summary:

1. If the layout is symmetric (e.g. most split keyboards), guess the
   handedness based on the sign of (x - layout_x_midpoint).

2. Otherwise, if the layout has a key of >=6u width, it is probably the
   spacebar. Form a dividing line through the spacebar, nearly vertical
   but with a slight angle to follow typical row stagger.

3. Otherwise, assume handedness based on the widest horizontal
   separation.

I have tested this strategy on a couple dozen keyboards and found it to
work reliably.

* Use Optional instead of `| None`.

* Refactor to avoid lambdas.

* Remove trailing comma in chordal_hold_layout.

* Minor docs edits.

* Revise to allow combining multiple same-hand mods.

This commit revises Chordal Hold as described in discussion in
https://github.com/qmk/qmk_firmware/pull/24560#discussion_r1894655238

1. In "RCTL_T(KC_A)↓, RSFT_T(KC_C)↓, RCTL_T(KC_A)↑" before the tapping
   term, RCTL_T(KC_A) is settled as tapped.
2. In "RCTL_T(KC_A)↓, RSFT_T(KC_C)↓, RSFT_T(KC_C)↑", both RCTL_T(KC_A)
   and RSFT_T(KC_C) are settled as tapped.
3. In "RCTL_T(KC_A)↓, RSFT_T(KC_C)↓, KC_U↓" (all keys on the same side),
   both RCTL_T(KC_A) and RSFT_T(KC_C) are settled as tapped.
4. In "RCTL_T(KC_A)↓, RSFT_T(KC_C)↓, LSFT_T(KC_T)↓", with the third key
   on the other side, we allow Permissive Hold or Hold On Other Keypress
   to decide how/when to settle the keys.
5. In "RCTL_T(KC_A)↓, RSFT_T(KC_C)↓" held until the tapping term, the
   keys are settled as held.

1–3 provide same-hand roll protection. 4–5 are for combining multiple
same-hand modifiers.

I've updated the unit tests and have been running it on my keyboard, for
a few hours so far, and all seems good. I really like this scheme. It
allows combining same-side mods, yet it also has roll protection on
streaks. For me, this feels like Achordion, but clearly better streak
handling and improved responsiveness.

* Fix formatting.

* Add a couple tests with LT keys.

* Remove stale use of CHORDAL_HOLD_LAYOUT.

* Fix misspelling lastest -> latest

* Handling tweak for LTs and tests.

* Fix formatting.

* More tests with LT keys.

* Fix formatting.

1 files changed, 65 insertions, 0 deletions

diff --git a/quantum/action_tapping.h b/quantum/action_tapping.h
index 6b518b8298..c3c7b999ec 100644
--- a/quantum/action_tapping.h
+++ b/quantum/action_tapping.h
@@ -46,6 +46,71 @@ bool     get_permissive_hold(uint16_t keycode, keyrecord_t *record);
 bool     get_retro_tapping(uint16_t keycode, keyrecord_t *record);
 bool     get_hold_on_other_key_press(uint16_t keycode, keyrecord_t *record);
 
+#ifdef CHORDAL_HOLD
+/**
+ * Callback to say when a key chord before the tapping term may be held.
+ *
+ * In keymap.c, define the callback
+ *
+ *     bool get_chordal_hold(uint16_t tap_hold_keycode,
+ *                           keyrecord_t* tap_hold_record,
+ *                           uint16_t other_keycode,
+ *                           keyrecord_t* other_record) {
+ *        // Conditions...
+ *     }
+ *
+ * This callback is called when:
+ *
+ * 1. `tap_hold_keycode` is pressed.
+ * 2. `other_keycode` is pressed while `tap_hold_keycode` is still held,
+ *     provided `other_keycode` is *not* also a tap-hold key and it is pressed
+ *     before the tapping term.
+ *
+ * If false is returned, this has the effect of immediately settling the
+ * tap-hold key as tapped. If true is returned, the tap-hold key is still
+ * unsettled, and may be settled as held depending on configuration and
+ * subsequent events.
+ *
+ * @param tap_hold_keycode   Keycode of the tap-hold key.
+ * @param tap_hold_record    Record from the tap-hold press event.
+ * @param other_keycode      Keycode of the other key.
+ * @param other_record       Record from the other key's press event.
+ * @return True if the tap-hold key may be considered held; false if tapped.
+ */
+bool get_chordal_hold(uint16_t tap_hold_keycode, keyrecord_t *tap_hold_record, uint16_t other_keycode, keyrecord_t *other_record);
+
+/**
+ * Default "opposite hands rule" for whether a key chord may settle as held.
+ *
+ * This function returns true when the tap-hold key and other key are on
+ * "opposite hands." In detail, handedness of the two keys are compared. If
+ * handedness values differ, or if either handedness is '*', the function
+ * returns true, indicating that it may be held. Otherwise, it returns false,
+ * in which case the tap-hold key is immediately settled at tapped.
+ *
+ * @param tap_hold_record  Record of the active tap-hold key press.
+ * @param other_record     Record of the other, interrupting key press.
+ * @return True if the tap-hold key may be considered held; false if tapped.
+ */
+bool get_chordal_hold_default(keyrecord_t *tap_hold_record, keyrecord_t *other_record);
+
+/**
+ * Gets the handedness of a key.
+ *
+ * This function returns:
+ *   'L' for keys pressed by the left hand,
+ *   'R' for keys on the right hand,
+ *   '*' for keys exempt from the "opposite hands rule." This could be used
+ *       perhaps on thumb keys or keys that might be pressed by either hand.
+ *
+ * @param key   A key matrix position.
+ * @return Handedness value.
+ */
+char chordal_hold_handedness(keypos_t key);
+
+extern const char chordal_hold_layout[MATRIX_ROWS][MATRIX_COLS] PROGMEM;
+#endif
+
 #ifdef DYNAMIC_TAPPING_TERM_ENABLE
 extern uint16_t g_tapping_term;
 #endif