feat: implement the mouse hover in and out events

Author: aradzie

packages/keybr-keyboard-ui/lib/KeyLayer.test.tsx

@@ -1,6 +1,7 @@
 import { test } from "node:test";
 import { KeyboardContext, Layout, loadKeyboard } from "@keybr/keyboard";
 import { render } from "@testing-library/react";
+import { userEvent } from "@testing-library/user-event";
 import { assert } from "chai";
 import { KeyLayer } from "./KeyLayer.tsx";
 
@@ -38,3 +39,39 @@ test("update", () => {
 
   r.unmount();
 });
+
+test("events", async () => {
+  const keyboard = loadKeyboard(Layout.EN_US);
+
+  const events: string[] = [];
+
+  const r = render(
+    <KeyboardContext.Provider value={keyboard}>
+      <KeyLayer
+        onKeyHoverIn={(key) => {
+          events.push(`hover in ${key}`);
+        }}
+        onKeyHoverOut={(key) => {
+          events.push(`hover out ${key}`);
+        }}
+        onKeyClick={(key) => {
+          events.push(`click ${key}`);
+        }}
+      />
+    </KeyboardContext.Provider>,
+  );
+
+  events.length = 0;
+  await userEvent.hover(r.getByText("A"));
+  assert.deepStrictEqual(events, ["hover in KeyA"]);
+
+  events.length = 0;
+  await userEvent.unhover(r.getByText("A"));
+  assert.deepStrictEqual(events, ["hover out KeyA"]);
+
+  events.length = 0;
+  await userEvent.click(r.getByText("A"));
+  assert.deepStrictEqual(events, ["hover in KeyA", "click KeyA"]);
+
+  r.unmount();
+});

packages/keybr-keyboard-ui/lib/KeyLayer.tsx

@@ -8,8 +8,8 @@ import {
   type ComponentType,
   memo,
   type ReactElement,
-  type ReactNode,
   useMemo,
+  useRef,
 } from "react";
 import { type KeyProps, makeKeyComponent } from "./Key.tsx";
 import { Surface } from "./shapes.tsx";
@@ -18,22 +18,59 @@ export const KeyLayer = memo(function KeyLayer({
   depressedKeys = [],
   toggledKeys = [],
   showColors = false,
+  onKeyHoverIn,
+  onKeyHoverOut,
+  onKeyClick,
 }: {
   readonly depressedKeys?: readonly KeyId[];
   readonly toggledKeys?: readonly KeyId[];
   readonly showColors?: boolean;
-}): ReactNode {
+  readonly onKeyHoverIn?: (key: KeyId, elem: Element) => void;
+  readonly onKeyHoverOut?: (key: KeyId, elem: Element) => void;
+  readonly onKeyClick?: (key: KeyId, elem: Element) => void;
+}) {
   const keyboard = useKeyboard();
+  const svgRef = useRef<SVGSVGElement>(null);
   const children = useMemo(() => getKeyElements(keyboard), [keyboard]);
   return (
-    <Surface>
+    <Surface
+      ref={svgRef}
+      onMouseOver={(event) => {
+        relayEvent(svgRef.current!, event, onKeyHoverIn);
+      }}
+      onMouseOut={(event) => {
+        relayEvent(svgRef.current!, event, onKeyHoverOut);
+      }}
+      onClick={(event) => {
+        relayEvent(svgRef.current!, event, onKeyClick);
+      }}
+    >
       {children.map((child) =>
         child.select(depressedKeys, toggledKeys, showColors),
       )}
     </Surface>
   );
 });
 
+function relayEvent(
+  root: Element,
+  { target }: { readonly target: any },
+  handler?: (key: KeyId, elem: Element) => void,
+) {
+  while (
+    handler != null &&
+    target instanceof Element &&
+    root.contains(target)
+  ) {
+    const key = (target as SVGElement).dataset["key"];
+    if (key) {
+      handler(key, target);
+      return;
+    }
+    target = target.parentElement;
+  }
+}
+
 function getKeyElements(keyboard: Keyboard): MemoizedKeyElements[] {
   return [...keyboard.shapes.values()].map(
     (shape) => new MemoizedKeyElements(keyboard, shape),

packages/keybr-lesson-ui/lib/Key.test.tsx

@@ -8,70 +8,76 @@ import { assert } from "chai";
 import { Key } from "./Key.tsx";
 
 test("render excluded", () => {
+  const key = new LessonKey({
+    letter: FakePhoneticModel.letter1,
+    samples: [],
+    timeToType: null,
+    bestTimeToType: null,
+    confidence: null,
+    bestConfidence: null,
+  }).asExcluded();
+
   const r = render(
     <FakeIntlProvider>
       <FakeSettingsContext>
-        <Key
-          lessonKey={new LessonKey({
-            letter: FakePhoneticModel.letter1,
-            samples: [],
-            timeToType: null,
-            bestTimeToType: null,
-            confidence: null,
-            bestConfidence: null,
-          }).asExcluded()}
-        />
+        <Key lessonKey={key} />
       </FakeSettingsContext>
     </FakeIntlProvider>,
   );
 
-  assert.isNotNull(r.container.querySelector(".lessonKey_excluded"));
+  const elem = r.container.querySelector(".lessonKey_excluded");
+  assert.isNotNull(elem);
+  assert.strictEqual(Key.attached(elem), key);
 
   r.unmount();
 });
 
 test("render included", () => {
+  const key = new LessonKey({
+    letter: FakePhoneticModel.letter1,
+    samples: [],
+    timeToType: null,
+    bestTimeToType: null,
+    confidence: null,
+    bestConfidence: null,
+  }).asIncluded();
+
   const r = render(
     <FakeIntlProvider>
       <FakeSettingsContext>
-        <Key
-          lessonKey={new LessonKey({
-            letter: FakePhoneticModel.letter1,
-            samples: [],
-            timeToType: null,
-            bestTimeToType: null,
-            confidence: null,
-            bestConfidence: null,
-          }).asIncluded()}
-        />
+        <Key lessonKey={key} />
       </FakeSettingsContext>
     </FakeIntlProvider>,
   );
 
-  assert.isNotNull(r.container.querySelector(".lessonKey_included"));
+  const elem = r.container.querySelector(".lessonKey_included");
+  assert.isNotNull(elem);
+  assert.strictEqual(Key.attached(elem), key);
 
   r.unmount();
 });
 
 test("render focused", () => {
+  const key = new LessonKey({
+    letter: FakePhoneticModel.letter1,
+    samples: [],
+    timeToType: null,
+    bestTimeToType: null,
+    confidence: null,
+    bestConfidence: null,
+  }).asFocused();
+
   const r = render(
     <FakeIntlProvider>
       <FakeSettingsContext>
-        <Key
-          lessonKey={new LessonKey({
-            letter: FakePhoneticModel.letter1,
-            samples: [],
-            timeToType: null,
-            bestTimeToType: null,
-            confidence: null,
-            bestConfidence: null,
-          }).asFocused()}
-        />
+        <Key lessonKey={key} />
       </FakeSettingsContext>
     </FakeIntlProvider>,
   );
 
-  assert.isNotNull(r.container.querySelector(".lessonKey_focused"));
+  const elem = r.container.querySelector(".lessonKey_focused");
+  assert.isNotNull(elem);
+  assert.strictEqual(Key.attached(elem), key);
 
   r.unmount();
 });

packages/keybr-lesson-ui/lib/Key.tsx

@@ -1,5 +1,4 @@
 import { type LessonKey } from "@keybr/lesson";
-import { type Letter } from "@keybr/phonetic-model";
 import { type MouseProps } from "@keybr/widget";
 import { clsx } from "clsx";
 import { type ReactNode } from "react";
@@ -31,6 +30,7 @@ export const Key = ({
   return (
     <span
       {...props}
+      ref={Key.attach(lessonKey)}
       key={codePoint}
       className={clsx(
         styles.lessonKey,
@@ -58,16 +58,16 @@ export const Key = ({
   );
 };
 
-export function getKeyElementSelector({ codePoint }: Letter): string {
-  return `.${styles.lessonKey}[data-code-point="${codePoint}"]`;
-}
+const attachment = Symbol();
 
-export function isKeyElement(el: Element): number | null {
-  if (el instanceof HTMLElement && el.className.includes(styles.lessonKey)) {
-    const value = el.dataset["codePoint"] ?? null;
-    if (value != null) {
-      return Number(value);
+Key.attach = (key: LessonKey) => {
+  return (target: Element | null): void => {
+    if (target != null) {
+      (target as any)[attachment] = key;
     }
-  }
-  return null;
-}
+  };
+};
+
+Key.attached = (target: Element | null): LessonKey | null => {
+  return (target as any)?.[attachment] ?? null;
+};

packages/keybr-lesson-ui/lib/KeySet.test.tsx

@@ -4,10 +4,11 @@ import { LessonKey, LessonKeys } from "@keybr/lesson";
 import { FakePhoneticModel } from "@keybr/phonetic-model";
 import { FakeSettingsContext } from "@keybr/settings";
 import { render } from "@testing-library/react";
+import { userEvent } from "@testing-library/user-event";
 import { assert } from "chai";
 import { KeySet } from "./KeySet.tsx";
 
-test("render", () => {
+test("render", async () => {
   const { letters } = FakePhoneticModel;
 
   const lessonKeys = new LessonKeys([
@@ -45,10 +46,23 @@ test("render", () => {
     }),
   ]);
 
+  const events: string[] = [];
+
   const r = render(
     <FakeIntlProvider>
       <FakeSettingsContext>
-        <KeySet lessonKeys={lessonKeys} />
+        <KeySet
+          lessonKeys={lessonKeys}
+          onKeyHoverIn={(key) => {
+            events.push(`hover in ${key.letter}`);
+          }}
+          onKeyHoverOut={(key) => {
+            events.push(`hover out ${key.letter}`);
+          }}
+          onKeyClick={(key) => {
+            events.push(`click ${key.letter}`);
+          }}
+        />
       </FakeSettingsContext>
     </FakeIntlProvider>,
   );
@@ -57,5 +71,17 @@ test("render", () => {
   assert.isNotNull(r.queryByText("B"));
   assert.isNotNull(r.queryByText("C"));
 
+  events.length = 0;
+  await userEvent.hover(r.getByText("A"));
+  assert.deepStrictEqual(events, ["hover in A"]);
+
+  events.length = 0;
+  await userEvent.unhover(r.getByText("A"));
+  assert.deepStrictEqual(events, ["hover out A"]);
+
+  events.length = 0;
+  await userEvent.click(r.getByText("A"));
+  assert.deepStrictEqual(events, ["hover in A", "click A"]);
+
   r.unmount();
 });

packages/keybr-lesson-ui/lib/KeySet.tsx

@@ -1,22 +1,61 @@
-import { type LessonKeys } from "@keybr/lesson";
+import { type LessonKey, type LessonKeys } from "@keybr/lesson";
 import { type ClassName } from "@keybr/widget";
-import { type ReactNode } from "react";
+import { type ReactNode, useRef } from "react";
 import { Key } from "./Key.tsx";
 
 export const KeySet = ({
   id,
   className,
   lessonKeys,
+  onKeyHoverIn,
+  onKeyHoverOut,
+  onKeyClick,
 }: {
   readonly id?: string;
   readonly className?: ClassName;
   readonly lessonKeys: LessonKeys;
+  readonly onKeyHoverIn?: (key: LessonKey, elem: Element) => void;
+  readonly onKeyHoverOut?: (key: LessonKey, elem: Element) => void;
+  readonly onKeyClick?: (key: LessonKey, elem: Element) => void;
 }): ReactNode => {
+  const ref = useRef<HTMLElement>(null);
   return (
-    <span id={id} className={className}>
+    <span
+      ref={ref}
+      id={id}
+      className={className}
+      onMouseOver={(event) => {
+        relayEvent(ref.current!, event, onKeyHoverIn);
+      }}
+      onMouseOut={(event) => {
+        relayEvent(ref.current!, event, onKeyHoverOut);
+      }}
+      onClick={(event) => {
+        relayEvent(ref.current!, event, onKeyClick);
+      }}
+    >
       {[...lessonKeys].map((lessonKey) => (
         <Key key={lessonKey.letter.codePoint} lessonKey={lessonKey} />
       ))}
     </span>
   );
 };
+
+function relayEvent(
+  root: Element,
+  { target }: { readonly target: any },
+  handler?: (key: LessonKey, elem: Element) => void,
+) {
+  while (
+    handler != null &&
+    target instanceof Element &&
+    root.contains(target)
+  ) {
+    const key = Key.attached(target);
+    if (key) {
+      handler(key, target);
+      return;
+    }
+    target = target.parentElement;
+  }
+}