feat(docs/hold-tap): Implement 'balanced' flavor animations

docs/docs/behaviors/hold-tap.md

@@ -34,8 +34,47 @@ We call this the 'hold-preferred' flavor of hold-taps. While this flavor may wor
 
 When the hold-tap key is released and the hold behavior has not been triggered, the tap behavior will trigger.
 
+<Tabs
+defaultValue="hold-preferred"
+values={[
+{label: 'Hold-Preferred', value: 'hold-preferred'},
+{label: 'Balanced', value: 'balanced'},
+{label: 'Tap-Preferred', value: 'tap-preferred'},
+]}>
+
+<TabItem value="hold-preferred">
+
+As shown previously, the hold-tap decision is generally made after the [`tapping-term-ms`](#tapping-term-ms) has expired.
+
+<AnimationPlayer auto small name="hold_tap_comparison" />
+
+Alternatively, the 'hold-preferred' flavor triggers the hold behavior when another key is pressed.
+
+<AnimationPlayer auto small name="hold_tap_interrupted" />
+
+</TabItem>
+
+<TabItem value="balanced">
+
+The following section describes the behavior of the 'balanced' hold-tap when another key is pressed while the hold-tap is held.
+
+If another key is pressed while the 'balanced' hold-tap pressed, releasing the hold-tap before the interrupting keypress will invoke the tap behavior.
+
+<AnimationPlayer auto small name="balanced_hold_tap_up" />
+
+On the other hand, if the interrupting key is released before the hold-tap, the hold behavior will be invoked.
+
+<AnimationPlayer auto small name="balanced_other_key_up" />
+
+</TabItem>
+
+<TabItem value="tap-preferred">
+
 ![Hold-tap comparison](../assets/hold-tap/comparison.svg)
 
+</TabItem>
+</Tabs>
+
 ### Basic usage
 
 For basic usage, please see the [mod-tap](mod-tap.md) and [layer-tap](layers.md#layer-tap) pages.

docs/src/animationhelpers/src/hold_tap/balanced_hold_tap_up.meta

@@ -0,0 +1,3 @@
+{
+  "version": 0
+}

docs/src/animationhelpers/src/hold_tap/balanced_hold_tap_up.ts

@@ -0,0 +1,8 @@
+import { makeProject } from "@motion-canvas/core/lib";
+
+import balanced_hold_tap_up from "../scenes/hold_tap/balanced_hold_tap_up?scene";
+
+export default makeProject({
+  scenes: [balanced_hold_tap_up],
+  background: "#FFFFFF",
+});

docs/src/animationhelpers/src/hold_tap/balanced_other_key_up.meta

@@ -0,0 +1,3 @@
+{
+  "version": 0
+}

docs/src/animationhelpers/src/hold_tap/balanced_other_key_up.ts

@@ -0,0 +1,8 @@
+import { makeProject } from "@motion-canvas/core/lib";
+
+import balanced_other_key_up from "../scenes/hold_tap/balanced_other_key_up?scene";
+
+export default makeProject({
+  scenes: [balanced_other_key_up],
+  background: "#FFFFFF",
+});

docs/src/animationhelpers/src/scenes/hold_tap/balanced_hold_tap_up.meta

@@ -0,0 +1,3 @@
+{
+  "version": 0
+}

docs/src/animationhelpers/src/scenes/hold_tap/balanced_hold_tap_up.tsx

@@ -0,0 +1,52 @@
+import { makeScene2D } from "@motion-canvas/2d/lib/scenes";
+import { makeRefs } from "@motion-canvas/core/lib/utils";
+import { any, all, chain, delay, waitFor } from "@motion-canvas/core/lib/flow";
+import Key, { KeyTravel } from "../../components/Key";
+import Output from "../../components/Output";
+import { linear } from "@motion-canvas/core/lib/tweening";
+
+export default makeScene2D(function* (view) {
+  const interrupt = makeRefs<typeof Key>();
+  view.add(<Key refs={interrupt} binding={"&kp"} params={"J"} />);
+  interrupt.group.position.x(125);
+  interrupt.group.position.y(-150);
+  interrupt.duration.fill("#D9D9D9");
+
+  const hold = makeRefs<typeof Key>();
+  view.add(<Key refs={hold} binding={"&ht_bl"} params={"\u21e7 F"} />);
+  hold.group.position.x(-125);
+  hold.group.position.y(-150);
+  hold.duration.fill("#D9D9D9");
+
+  const hold_output = makeRefs<typeof Output>();
+  view.add(<Output refs={hold_output} />);
+  hold_output.group.position(hold.group.position().addX(125));
+  hold_output.group.position.y(hold_output.group.position.y() + 300);
+
+  yield* waitFor(0.5);
+  yield* any(
+    hold.body.position.y(KeyTravel, 0.15),
+    hold.duration.grow(1, 2, linear)
+  );
+  yield* delay(
+    1.2,
+    all(
+      interrupt.body.position.y(KeyTravel, 0.15),
+      hold.duration.fill("F21D00", 0.15)
+    )
+  );
+  yield* delay(
+    1.5,
+    chain(
+      hold.body.position.y(0, 0.15),
+      hold.group.rotation(3, 0.03),
+      hold.group.rotation(-3, 0.06),
+      hold.group.rotation(0, 0.03),
+      hold.duration.grow(0, 0.15),
+      delay(0.05, hold_output.output.text("f", 0)),
+      delay(0.05, hold_output.output.text("fj", 0))
+    )
+  );
+  yield* waitFor(0.25);
+  yield* interrupt.body.position.y(0, 0.15);
+});

docs/src/animationhelpers/src/scenes/hold_tap/balanced_other_key_up.meta

@@ -0,0 +1,3 @@
+{
+  "version": 0
+}

docs/src/animationhelpers/src/scenes/hold_tap/balanced_other_key_up.tsx

@@ -0,0 +1,54 @@
+import { makeScene2D } from "@motion-canvas/2d/lib/scenes";
+import { makeRefs } from "@motion-canvas/core/lib/utils";
+import { any, all, chain, delay, waitFor } from "@motion-canvas/core/lib/flow";
+import Key, { KeyTravel } from "../../components/Key";
+import Output from "../../components/Output";
+import { linear } from "@motion-canvas/core/lib/tweening";
+
+export default makeScene2D(function* (view) {
+  const interrupt = makeRefs<typeof Key>();
+  view.add(<Key refs={interrupt} binding={"&kp"} params={"J"} />);
+  interrupt.group.position.x(125);
+  interrupt.group.position.y(-150);
+  interrupt.duration.fill("#D9D9D9");
+
+  const hold = makeRefs<typeof Key>();
+  view.add(<Key refs={hold} binding={"&ht_bl"} params={"\u21e7 F"} />);
+  hold.group.position.x(-125);
+  hold.group.position.y(-150);
+  hold.duration.fill("#D9D9D9");
+
+  const hold_output = makeRefs<typeof Output>();
+  view.add(<Output refs={hold_output} />);
+  hold_output.group.position(hold.group.position().addX(125));
+  hold_output.group.position.y(hold_output.group.position.y() + 300);
+
+  yield* waitFor(0.5);
+  yield* any(
+    hold.body.position.y(KeyTravel, 0.15),
+    hold.duration.grow(1, 2, linear)
+  );
+  yield* delay(
+    1.2,
+    all(
+      interrupt.body.position.y(KeyTravel, 0.15),
+      hold.duration.fill("F21D00", 0.15)
+    )
+  );
+  yield* delay(
+    1.5,
+    chain(
+      interrupt.body.position.y(0, 0.15),
+      hold.group.rotation(3, 0.03),
+      hold.group.rotation(-3, 0.06),
+      hold.group.rotation(0, 0.03),
+      all(
+        delay(0.15, hold_output.output.text("J", 0)),
+        hold_output.shift.fill("#969696", 0.15)
+      )
+    )
+  );
+  yield* waitFor(0.25);
+  yield* hold.body.position.y(0, 0.15);
+  yield* delay(0.5, hold.duration.grow(0, 0.15));
+});

docs/src/animationhelpers/vite.config.ts

@@ -7,6 +7,8 @@ export default defineConfig({
       project: [
         "./src/hold_tap/hold_tap_comparison.ts",
         "./src/hold_tap/hold_tap_interrupted.ts",
+        "./src/hold_tap/balanced_other_key_up.ts",
+        "./src/hold_tap/balanced_hold_tap_up.ts",
       ],
     }),
   ],