This PR adds "Chordal Hold," a tap-hold option implementing the "opposite hands" rule similar to Achordion and Bilateral Combinations. Chordal Hold may be used out of the box without any configuration, or if desired, Achordion-like per-chord configuration is supported.

Description

Suppose tap-hold key is pressed and then, before the tapping term, another key is pressed. With Chordal Hold, the tap-hold key is settled as tapped if the two keys are on the same hand. This behavior may be useful to avoid accidental modifier activation with mod-taps, particularly in rolled keypresses when using home row mods.

In the case that the keys are on opposite hands, Chordal Hold alone does not yet settle the tap-hold key. Chordal Hold may be used in combination with Hold On Other Key Press or Permissive Hold to determine the behavior. With Hold On Other Key Press, an opposite hands chord is settled immediately as held. Or with Permissive Hold, an opposite hands chord is settled as held provided the other key is pressed and released (nested press) before releasing the tap-hold key.

Further notes:

• Chordal Hold has no effect after the tapping term.

• Chordal Hold has no effect when combos are involved.

History

Previously, "opposite hands" rule behavior like this has been implemented in

• manna-harbour's Bilateral Combinations, as an unmerged patch to core
• my Achordion, in userspace
• stasmarkin's sm_td, in userspace
• filterpaper's Contextual Mod-Taps, in userspace
• (and others?)

This is a highly desired feature. Judging from Reddit, Achordion is my most popular QMK library. Still so far, "opposite hands" behavior like this is not yet in QMK core. I've been reluctant to touch action_tapping.c, it is an intimidating piece of code, but I think it's important to figure this out and make it happen!

Comparison to Achordion and Bilateral Combinations

• Achordion and Bilateral Combinations operate after action_tapping, by manipulating hold events after QMK core has settled them. This means there are two stages of event buffering, first in core, then second in Achordion/Bilateral Combinations.

• Chordal Hold operates within action_tapping itself. This is advantageous since one stage of event buffering rather than two can in some cases complete more quickly for reduced input lag, and it is (arguably) conceptually simpler.

How to use Chordal Hold

Chordal Hold is intended to be used together with either Permissive Hold or Hold On Other Keypress. Enable one of them, and enable Chordal Hold by adding in config.h:

#define CHORDAL_HOLD

For an Achordion-like experience, I suggest enabling Permissive Hold and setting the tapping term rather high, say, 250 ms. With Chordal Hold + Permissive Hold, keys usually settle before the tapping term.

"Handedness"

Determining whether keys are on the same or opposite hands involves defining the "handedness" of each key position. By default if nothing is specified, handedness is guessed based on keyboard geometry information from keyboard.json. If this is inaccurate, handedness may be specified by defining chordal_hold_layout. In keymap.c, define chordal_hold_layout in the following form:

const char chordal_hold_layout[MATRIX_ROWS][MATRIX_COLS] PROGMEM =
    LAYOUT(
        'L', 'L', 'L', 'L', 'L', 'L',  'R', 'R', 'R', 'R', 'R', 'R', 
        'L', 'L', 'L', 'L', 'L', 'L',  'R', 'R', 'R', 'R', 'R', 'R', 
        'L', 'L', 'L', 'L', 'L', 'L',  'R', 'R', 'R', 'R', 'R', 'R', 
                       'L', 'L', 'L',  'R', 'R', 'R'
    );

Use the same LAYOUT macro as used to define your keymap layers. Each entry is a character, either 'L' for left, 'R' for right, or '*' to exempt keys from the "opposite hands rule." When a key has '*' handedness, pressing it with either hand results in a hold. This could be used perhaps on thumb keys or other places where you want to allow same-hand chords.

chordal_hold_layout is inspired by the convenient "BILATERAL_COMBINATIONS_HANDS_LAYER" in Bilateral Combinations. But with the differences that chordal_hold_layout is defined as a separate array outside the keymap and in char datatype to halve the flash space cost.

Advanced configuration

Per-chord tuning of the behavior is possible with the get_chordal_hold() callback. This parallels Achordion's achordion_chord() callback. Returning true from this callback indicates that the chord may be settled as held, while returning false immediately settles the chord as tapped. Example:

bool get_chordal_hold(uint16_t tap_hold_keycode, keyrecord_t* tap_hold_record,
                      uint16_t other_keycode, keyrecord_t* other_record) {
    // Exceptionally allow some one-handed chords for hotkeys.
    switch (tap_hold_keycode) {
        case LCTL_T(KC_A):
           if (other_keycode == KC_C || other_keycode == KC_V) {
               return true;
           }
           break;
        case RCTL_T(KC_SCLN):
           if (other_keycode == KC_N) {
               return true;
           }
           break;
    }
    // Otherwise defer to the opposite hands rule.
    return get_chordal_hold_default(tap_hold_record, other_record);
}

Please see the addition to docs/tap_hold.md for further documentation.

Implementation

• The meat of Chordal Hold's implementation is in action_tapping.c. Please review this first.
• I include unit tests that check that Chordal Hold operates as intended when used together with either Permissive Hold or Hold On Other Key Press.

Inferring default handedness

By default if nothing is specified, handedness is guessed based on keyboard geometry information from keyboard.json. Under "layout", the JSON has x-y coordinates for each key. Handedness is then inferred by the following heuristics (implemented in lib/python/qmk/cli/generate/keyboard_c.py):

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. Here are a few examples (legend: blue = 'L', red = 'R', black = '*'):

Types of Changes

• Core
• Bugfix
• New feature
• Enhancement/optimization
• Keyboard (addition or update)
• Keymap/layout (addition or update)
• Documentation

Checklist

• My code follows the code style of this project: C, Python
• I have read the PR Checklist document and have made the appropriate changes.
• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• I have read the CONTRIBUTING document.
• I have added tests to cover my changes.
• I have tested the changes and verified that they work and don't break anything (as well as I can manage).