implement combo/chord/sequence module

docs/README.md

@@ -22,6 +22,7 @@
 
 ## [Modules](modules.md)
 
+- [Combos](combos.md): Adds chords and sequences
 - [Layers](layers.md): Adds layer support (Fn key) to allow many more keys to be put on your keyboard
 - [ModTap](modtap.md): Adds support for augmented modifier keys to act as one key when tapped, and modifier when held.
 - [Mouse keys](mouse_keys.md): Adds mouse keycodes

docs/combos.md

@@ -0,0 +1,45 @@
+# Combos
+Combos allow you to assign special functionality to combinations of key presses.
+The two default behaviors are:
+* Chords: match keys in random order, all pressed within 50ms.
+* Sequences: match keys in order, pressed within 1s of one another.
+
+You can define combos to listen to any valid KMK key, even internal or
+functional keys, like HoldTap. When using internal KMK keys, be aware that the
+order of modules matters.
+
+The result of a combo is another key being pressed/released; if the desired
+action isn't covered by KMK keys: create your own with `make_key` and attach
+corresponding handlers.
+
+Combos may overlap, i.e. share match keys amongst each other.
+
+The optional arguments `timeout` and `per_key_timeout` define the time window
+within which the match has to happen and wether the timeout is renewed after
+each key press, respectively. These can be customized for every combo
+individually.
+
+## Keycodes
+|New Keycode |Description                                         |
+|------------|----------------------------------------------------|
+|`KC.LEADER` | a dummy / convenience key for leader key sequences |
+
+## Example Code
+```python
+from kmk.keys import KC, make_key
+from kmk.modules.combos import Combos, Chord, Sequence
+combos = Combos()
+keyboard.modules.append(combos)
+
+make_key(
+    names=('MYKEY',),
+    on_press=lambda: print('I pressed MYKEY'),
+)
+
+combos.combos = [
+    Chord((KC.A, KC.B), KC.LSFT)
+    Chord((KC.A, KC.B, KC.C), KC.LALT)
+    Sequence((KC.LEADER, KC.A, KC.B), KC.C)
+    Sequence((KC.E, KC.F) KC.MYKEY, timeout=500, per_key_timeout=False)
+]
+```

docs/modules.md

@@ -7,6 +7,7 @@ sandbox, and can make massive changes to normal operation.
 These modules are provided in all builds and can be enabled. Currently offered
 modules are
 
+- [Combos](combos.md): Adds chords and sequences
 - [Layers](layers.md): Adds layer support (Fn key) to allow many more keys to be
 put on your keyboard.
 - [ModTap](modtap.md): Adds support for augmented modifier keys to act as one key