jspsych 8.2.3 → 8.3.0

package/dist/index.d.ts

@@ -588,6 +588,7 @@ interface GetKeyboardResponseOptions {
     audio_context_start_time?: number;
     allow_held_key?: boolean;
     minimum_valid_rt?: number;
+    wait_for_key_release?: boolean;
 }
 declare class KeyboardListenerAPI {
     private getRootElement;
@@ -596,6 +597,8 @@ declare class KeyboardListenerAPI {
     constructor(getRootElement: () => Element | undefined, areResponsesCaseSensitive?: boolean, minimumValidRt?: number);
     private listeners;
     private heldKeys;
+    private keyDownTimestamps;
+    private pendingReleases;
     private areRootListenersRegistered;
     /**
      * If not previously done and `this.getRootElement()` returns an element, adds the root key
@@ -604,9 +607,24 @@ declare class KeyboardListenerAPI {
     private registerRootListeners;
     private rootKeydownListener;
     private toLowerCaseIfInsensitive;
+    /**
+     * 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.
+     */
+    private getPhysicalKey;
     private rootKeyupListener;
+    /**
+     * 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.
+     */
+    private rootBlurListener;
     private isResponseValid;
-    getKeyboardResponse({ callback_function, valid_responses, rt_method, persist, audio_context, audio_context_start_time, allow_held_key, minimum_valid_rt, }: GetKeyboardResponseOptions): KeyboardListener;
+    getKeyboardResponse({ callback_function, valid_responses, rt_method, persist, audio_context, audio_context_start_time, allow_held_key, minimum_valid_rt, wait_for_key_release, }: GetKeyboardResponseOptions): KeyboardListener;
     cancelKeyboardResponse(listener: KeyboardListener): void;
     cancelAllKeyboardResponses(): void;
     compareKeys(key1: string | null, key2: string | null): boolean;

package/dist/index.js

@@ -2,7 +2,7 @@ import autoBind from 'auto-bind';
 import rw from 'random-words';
 import seedrandom from 'seedrandom/lib/alea.js';
 
-var version = "8.2.3";
+var version = "8.3.0";
 
 class ExtensionManager {
   constructor(dependencies, extensionsConfiguration) {
@@ -555,6 +555,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();
@@ -569,11 +571,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);
     }
@@ -582,9 +589,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;
@@ -605,7 +646,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(
@@ -632,7 +674,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);
@@ -640,9 +691,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) {