jspsych 8.2.3 → 8.3.0

package/dist/index.cjs

@@ -4,7 +4,7 @@ var autoBind = require('auto-bind');
 var rw = require('random-words');
 var seedrandom = require('seedrandom/lib/alea.js');
 
-var version = "8.2.3";
+var version = "8.3.0";
 
 class ExtensionManager {
   constructor(dependencies, extensionsConfiguration) {
@@ -557,6 +557,8 @@ class KeyboardListenerAPI {
     this.minimumValidRt = minimumValidRt;
     this.listeners = /* @__PURE__ */ new Set();
     this.heldKeys = /* @__PURE__ */ new Set();
+    this.keyDownTimestamps = /* @__PURE__ */ new Map();
+    this.pendingReleases = /* @__PURE__ */ new Map();
     this.areRootListenersRegistered = false;
     autoBind(this);
     this.registerRootListeners();
@@ -571,11 +573,16 @@ class KeyboardListenerAPI {
       if (rootElement) {
         rootElement.addEventListener("keydown", this.rootKeydownListener);
         rootElement.addEventListener("keyup", this.rootKeyupListener);
+        window.addEventListener("blur", this.rootBlurListener);
         this.areRootListenersRegistered = true;
       }
     }
   }
   rootKeydownListener(e) {
+    const physicalKey = this.getPhysicalKey(e);
+    if (!this.keyDownTimestamps.has(physicalKey)) {
+      this.keyDownTimestamps.set(physicalKey, performance.now());
+    }
     for (const listener of [...this.listeners]) {
       listener(e);
     }
@@ -584,9 +591,43 @@ class KeyboardListenerAPI {
   toLowerCaseIfInsensitive(string) {
     return this.areResponsesCaseSensitive ? string : string.toLowerCase();
   }
+  /**
+   * identifies physical key of a keyboard event, for matching a keydown event with
+   * its corresponding keyup event, in the case of a change of shift state while
+   * the key is being held.
+   */
+  getPhysicalKey(e) {
+    return e.code || this.toLowerCaseIfInsensitive(e.key);
+  }
   rootKeyupListener(e) {
+    const physicalKey = this.getPhysicalKey(e);
+    for (const [listener, pending] of this.pendingReleases) {
+      if (pending.code === physicalKey) {
+        const pressTimestamp = this.keyDownTimestamps.get(physicalKey);
+        const rt_key_duration = pressTimestamp === void 0 ? null : Math.round(performance.now() - pressTimestamp);
+        this.pendingReleases.delete(listener);
+        pending.callback_function({ key: pending.key, rt: pending.rt, rt_key_duration });
+      }
+    }
+    this.keyDownTimestamps.delete(physicalKey);
     this.heldKeys.delete(this.toLowerCaseIfInsensitive(e.key));
   }
+  /**
+   * When the window loses focus (`blur`), the browser will not deliver the `keyup` events for keys
+   * that are currently held, which would otherwise leave stale entries in `heldKeys` and
+   * `keyDownTimestamps` (making a key look permanently held) and orphan any pending releases. Treat
+   * the blur as a release of every held key: resolve each pending release with
+   * `rt_key_duration: null`, since the true hold duration cannot be measured once the release is
+   * never observed, then clear the tracked key state.
+   */
+  rootBlurListener() {
+    for (const [listener, pending] of this.pendingReleases) {
+      this.pendingReleases.delete(listener);
+      pending.callback_function({ key: pending.key, rt: pending.rt, rt_key_duration: null });
+    }
+    this.heldKeys.clear();
+    this.keyDownTimestamps.clear();
+  }
   isResponseValid(validResponses, allowHeldKey, key) {
     if (!allowHeldKey && this.heldKeys.has(key)) {
       return false;
@@ -607,7 +648,8 @@ class KeyboardListenerAPI {
     audio_context,
     audio_context_start_time,
     allow_held_key = false,
-    minimum_valid_rt = this.minimumValidRt
+    minimum_valid_rt = this.minimumValidRt,
+    wait_for_key_release = false
   }) {
     if (rt_method !== "performance" && rt_method !== "audio") {
       console.log(
@@ -634,7 +676,16 @@ class KeyboardListenerAPI {
         if (!persist) {
           this.cancelKeyboardResponse(listener);
         }
-        callback_function({ key: e.key, rt });
+        if (wait_for_key_release) {
+          this.pendingReleases.set(listener, {
+            code: this.getPhysicalKey(e),
+            key: e.key,
+            rt,
+            callback_function
+          });
+        } else {
+          callback_function({ key: e.key, rt });
+        }
       }
     };
     this.listeners.add(listener);
@@ -642,9 +693,11 @@ class KeyboardListenerAPI {
   }
   cancelKeyboardResponse(listener) {
     this.listeners.delete(listener);
+    this.pendingReleases.delete(listener);
   }
   cancelAllKeyboardResponses() {
     this.listeners.clear();
+    this.pendingReleases.clear();
   }
   compareKeys(key1, key2) {
     if (typeof key1 !== "string" && key1 !== null || typeof key2 !== "string" && key2 !== null) {