update modules

modules/getreuer/tap_flow/README.md

@@ -2,7 +2,7 @@
 
 <table>
 <tr><td><b>Module</b></td><td><tt>getreuer/tap_flow</tt></td></tr>
-<tr><td><b>Version</b></td><td>2025-03-19</td></tr>
+<tr><td><b>Version</b></td><td>2025-04-08</td></tr>
 <tr><td><b>Maintainer</b></td><td>Pascal Getreuer (@getreuer)</td></tr>
 <tr><td><b>License</b></td><td><a href="../LICENSE.txt">Apache 2.0</a></td></tr>
 <tr><td><b>Documentation</b></td><td>
@@ -39,8 +39,9 @@ Tap Flow's default behavior is:
 
 * Filtering is done only when both the tap-hold key and the previous key are
   among <kbd>Space</kbd>, letters <kbd>A</kbd>&ndash;<kbd>Z</kbd>, and
-  punctuations <kbd>,</kbd> <kbd>.</kbd> <kbd>;</kbd> <kbd>/</kbd>. Define the
+  punctuations <kbd>,</kbd> <kbd>.</kbd> <kbd>;</kbd> <kbd>/</kbd>.
-  `get_tap_flow()` callback to customize this logic.
+
+Define the `is_tap_flow_key()` or `get_tap_flow_term()` callbacks to customize.
 
 Tap Flow modifies the tap-hold decision such that when a tap-hold key is pressed
 within a short timeout of the preceding key, the tapping function is used. The
@@ -49,9 +50,10 @@ desired (though perhaps with an exception for Shift or AltGr, noted below),
 whereas the hold functions (mods and layers) are used in isolation, or at least
 with a brief pause preceding the tap-hold key press.
 
-Optionally, the feature can be customized with the `get_tap_flow()` callback. In
+Optionally, the feature can be customized with the `is_tap_flow_key()` and
-this way, exceptions may be made for Shift and AltGr (or whatever you wish) to
+`get_tap_flow_term()` callbacks. In this way, exceptions may be made for Shift
-use a shorter time or to disable filtering for those keys entirely.
+and AltGr (or whatever you wish) to use a shorter time or to disable filtering
+for those keys entirely.
 
 For full documentation, see
 <https://getreuer.info/posts/keyboards/tap-flow>

modules/getreuer/tap_flow/tap_flow.c

@@ -183,8 +183,8 @@ bool process_record_tap_flow(uint16_t keycode, keyrecord_t* record) {
   return true;
 }
 
-// Keycode is a "typing" key: Space, A-Z, or main alphas area punctuation.
+// By default, enable Tap Flow for Space, A-Z, or main alphas area punctuation.
-static bool is_typing(uint16_t keycode) {
+__attribute__((weak)) bool is_tap_flow_key(uint16_t keycode) {
   switch (get_tap_keycode(keycode)) {
     case KC_SPC:
     case KC_A ... KC_Z:
@@ -197,16 +197,20 @@ static bool is_typing(uint16_t keycode) {
   return false;
 }
 
-// By default, enable filtering when both the tap-hold key and previous key are
+__attribute__((weak)) uint16_t get_tap_flow_term(
-// typing keys, and use the quick tap term.
-__attribute__((weak)) uint16_t get_tap_flow(
     uint16_t keycode, keyrecord_t* record, uint16_t prev_keycode) {
-  if (!is_typing(keycode) || !is_typing(prev_keycode)) {
+  return get_tap_flow(keycode, record, prev_keycode);
-    return 0;
 }
 
+// By default, enable filtering when both the tap-hold key and previous key
+// return true for `is_tap_flow_key()`.
+__attribute__((weak)) uint16_t get_tap_flow(
+    uint16_t keycode, keyrecord_t* record, uint16_t prev_keycode) {
+  if (is_tap_flow_key(keycode) && is_tap_flow_key(prev_keycode)) {
     return g_tap_flow_term;
   }
+  return 0;  // Disable Tap Flow.
+}
 
 #endif  // !defined(COMBO_ENABLE) && !defined(REPEAT_KEY_ENABLE)
 

modules/getreuer/tap_flow/tap_flow.h

@@ -48,6 +48,41 @@ extern "C" {
 #  define TAP_FLOW_TERM  150
 #endif  // TAP_FLOW_TERM
 
+/**
+ * Optional callback to customize where Tap Flow is enabled.
+ *
+ * Tap Flow is constrained to certain keys by the following rule: this callback
+ * is called for both the tap-hold key *and* the key press immediately preceding
+ * it. If the callback returns true for both keycodes, Tap Flow may apply.
+ *
+ * The default implementation of this callback corresponds to
+ *
+ *     bool is_tap_flow_key(uint16_t keycode) {
+ *       switch (keycode) {
+ *         case QK_MOD_TAP ... QK_MOD_TAP_MAX:
+ *           keycode = QK_MOD_TAP_GET_TAP_KEYCODE(keycode);
+ *           break;
+ *         case QK_LAYER_TAP ... QK_LAYER_TAP_MAX:
+ *           keycode = QK_LAYER_TAP_GET_TAP_KEYCODE(keycode);
+ *           break;
+ *       }
+ *       switch (keycode) {
+ *         case KC_SPC:
+ *         case KC_A ... KC_Z:
+ *         case KC_DOT:
+ *         case KC_COMM:
+ *         case KC_SCLN:
+ *         case KC_SLSH:
+ *           return true;
+ *       }
+ *       return false;
+ *     }
+ *
+ * @param keycode Keycode of the key.
+ * @return Whether to enable Tap Flow for this key.
+ */
+bool is_tap_flow_key(uint16_t keycode);
+
 /**
  * Optional callback to customize filtering.
  *
@@ -56,11 +91,28 @@ extern "C" {
  * Return a time of 0 to disable filtering. In this way, Tap Flow may be
  * disabled for certain tap-hold keys, or when following certain previous keys.
  *
+ * The default implementation of this callback is
+ *
+ *     uint16_t get_tap_flow_term(uint16_t keycode, keyrecord_t* record,
+ *                                uint16_t prev_keycode) {
+ *       if (is_tap_flow_key(keycode) && is_tap_flow_key(prev_keycode)) {
+ *         return g_tap_flow_term;
+ *       }
+ *       return 0;
+ *     }
+ *
+ * NOTE: If both `is_tap_flow_key()` and `get_tap_flow_term()` are defined, then
+ * `get_tap_flow_term()` takes precedence.
+ *
  * @param keycode Keycode of the tap-hold key.
  * @param record keyrecord_t of the tap-hold event.
  * @param prev_keycode Keycode of the previously pressed key.
- * @return Time in milliseconds.
+ * @return Timeout in milliseconds.
  */
+uint16_t get_tap_flow_term(uint16_t keycode, keyrecord_t* record,
+                           uint16_t prev_keycode);
+
+/** @deprecated Use `get_tap_flow_term()` instead. */
 uint16_t get_tap_flow(uint16_t keycode, keyrecord_t* record,
                       uint16_t prev_keycode);