jspsych 8.2.2 → 8.3.0

package/dist/index.d.ts

@@ -50,6 +50,7 @@ type ParameterInfo = ({
     array?: boolean;
     pretty_name?: string;
     default?: any;
+    options?: any;
 };
 type ParameterInfos = Record<string, ParameterInfo>;
 type InferredParameter<I extends ParameterInfo> = I["array"] extends true ? Array<ParameterTypeMap[I["type"]]> : ParameterTypeMap[I["type"]];
@@ -587,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;
@@ -595,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
@@ -603,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.2";
+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) {
@@ -2064,6 +2117,73 @@ class Trial extends TimelineNode {
             }
           }
         });
+        if (!parameterConfig.array && parameterValue !== null) {
+          switch (parameterConfig.type) {
+            case ParameterType.BOOL:
+              if (typeof parameterValue !== "boolean") {
+                const parameterPathString = parameterPathArrayToString(parameterPath);
+                console.warn(
+                  `A non-boolean value (\`${parameterValue}\`) was provided for the boolean parameter "${parameterPathString}" in the "${this.pluginInfo.name}" plugin.`
+                );
+              }
+              break;
+            // @ts-ignore falls through
+            case ParameterType.KEYS:
+              if (Array.isArray(parameterValue)) break;
+            case ParameterType.STRING:
+            case ParameterType.HTML_STRING:
+            case ParameterType.KEY:
+            case ParameterType.AUDIO:
+            case ParameterType.VIDEO:
+            case ParameterType.IMAGE:
+              if (typeof parameterValue !== "string") {
+                const parameterPathString = parameterPathArrayToString(parameterPath);
+                console.warn(
+                  `A non-string value (\`${parameterValue}\`) was provided for the parameter "${parameterPathString}" in the "${this.pluginInfo.name}" plugin.`
+                );
+              }
+              break;
+            case ParameterType.FLOAT:
+            case ParameterType.INT:
+              if (typeof parameterValue !== "number") {
+                const parameterPathString = parameterPathArrayToString(parameterPath);
+                console.warn(
+                  `A non-numeric value (\`${parameterValue}\`) was provided for the numeric parameter "${parameterPathString}" in the "${this.pluginInfo.name}" plugin.`
+                );
+              }
+              break;
+            case ParameterType.FUNCTION:
+              if (typeof parameterValue !== "function") {
+                const parameterPathString = parameterPathArrayToString(parameterPath);
+                console.warn(
+                  `A non-function value (\`${parameterValue}\`) was provided for the function parameter "${parameterPathString}" in the "${this.pluginInfo.name}" plugin.`
+                );
+              }
+              break;
+            case ParameterType.SELECT:
+              if (!parameterConfig.options) {
+                const parameterPathString = parameterPathArrayToString(parameterPath);
+                console.warn(
+                  `The "options" array is required for the "select" parameter "${parameterPathString}" in the "${this.pluginInfo.name}" plugin.`
+                );
+              }
+          }
+          if (parameterConfig.type === ParameterType.INT && parameterValue % 1 !== 0) {
+            const parameterPathString = parameterPathArrayToString(parameterPath);
+            console.warn(
+              `A float value (\`${parameterValue}\`) was provided for the integer parameter "${parameterPathString}" in the "${this.pluginInfo.name}" plugin. The value will be truncated to an integer.`
+            );
+            parameterValue = Math.trunc(parameterValue);
+          }
+        }
+        if (parameterConfig.type === ParameterType.SELECT) {
+          if (!parameterConfig.options.includes(parameterValue)) {
+            const parameterPathString = parameterPathArrayToString(parameterPath);
+            console.warn(
+              `The value "${parameterValue}" is not a valid option for the parameter "${parameterPathString}" in the "${this.pluginInfo.name}" plugin. Valid options are: ${parameterConfig.options.join(", ")}.`
+            );
+          }
+        }
         if (parameterConfig.array && !Array.isArray(parameterValue)) {
           const parameterPathString = parameterPathArrayToString(parameterPath);
           throw new Error(