jspsych 8.2.2 → 8.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jspsych",
-  "version": "8.2.2",
+  "version": "8.3.0",
   "description": "Behavioral experiments in a browser",
   "type": "module",
   "main": "dist/index.cjs",
@@ -48,7 +48,7 @@
   },
   "devDependencies": {
     "@fontsource/open-sans": "4.5.3",
-    "@jspsych/config": "^3.3.0",
+    "@jspsych/config": "^3.3.4",
     "@types/dom-mediacapture-record": "^1.0.11",
     "base64-inline-loader": "^2.0.1",
     "css-loader": "^6.6.0",

package/src/index.scss

@@ -112,6 +112,27 @@
   cursor: not-allowed;
 }
 
+/* Keyboard keys, e.g., press <kbd>space</kbd> in instructions */
+
+.jspsych-display-element kbd,
+.jspsych-display-element .jspsych-key {
+  display: inline-block;
+  min-width: 1em;
+  padding: 0.15em 0.5em;
+  margin: 0 0.1em 2px;
+  font-family: "Open Sans", "Arial", sans-serif;
+  font-size: 0.8em;
+  line-height: 1.4;
+  text-align: center;
+  white-space: nowrap;
+  vertical-align: middle;
+  color: #333;
+  background-color: #f7f7f7;
+  border: 1px solid #ccc;
+  border-radius: 4px;
+  box-shadow: 0 2px 0 #ccc;
+}
+
 /* custom style for input[type="range] (slider) to improve alignment between positions and labels */
 
 .jspsych-slider {

package/src/modules/plugin-api/KeyboardListenerAPI.ts

@@ -13,6 +13,18 @@ export interface GetKeyboardResponseOptions {
   audio_context_start_time?: number;
   allow_held_key?: boolean;
   minimum_valid_rt?: number;
+  wait_for_key_release?: boolean;
+}
+
+interface PendingRelease {
+  /**
+   * physical key (`KeyboardEvent.code`) whose release is being awaited; falls back to the
+   * case-normalized key value for synthetic events that do not set `code`.
+   */
+  code: string;
+  key: string;
+  rt: number;
+  callback_function: any;
 }
 
 export class KeyboardListenerAPI {
@@ -27,6 +39,8 @@ export class KeyboardListenerAPI {
 
   private listeners = new Set<KeyboardListener>();
   private heldKeys = new Set<string>();
+  private keyDownTimestamps = new Map<string, number>();
+  private pendingReleases = new Map<KeyboardListener, PendingRelease>();
 
   private areRootListenersRegistered = false;
 
@@ -40,12 +54,21 @@ export class KeyboardListenerAPI {
       if (rootElement) {
         rootElement.addEventListener("keydown", this.rootKeydownListener);
         rootElement.addEventListener("keyup", this.rootKeyupListener);
+        // When the window loses focus the browser stops delivering keyup events, so a key held at
+        // that moment would otherwise never be seen as released. Treat a blur as releasing all keys.
+        window.addEventListener("blur", this.rootBlurListener);
         this.areRootListenersRegistered = true;
       }
     }
   }
 
   private rootKeydownListener(e: KeyboardEvent) {
+    const physicalKey = this.getPhysicalKey(e);
+    // Record the press timestamp only for the initial keydown, not for key-repeat events of a key
+    // that is already held down (the timestamp is only removed again by the key's keyup).
+    if (!this.keyDownTimestamps.has(physicalKey)) {
+      this.keyDownTimestamps.set(physicalKey, performance.now());
+    }
     // Iterate over a static copy of the listeners set because listeners might add other listeners
     // that we do not want to be included in the loop
     for (const listener of [...this.listeners]) {
@@ -58,10 +81,53 @@ export class KeyboardListenerAPI {
     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.
+   */
+  private getPhysicalKey(e: KeyboardEvent) {
+    return e.code || this.toLowerCaseIfInsensitive(e.key);
+  }
+
   private rootKeyupListener(e: KeyboardEvent) {
+    const physicalKey = this.getPhysicalKey(e);
+
+    // match pending releases by physical key so that a change in shift state while the key is held
+    // (which changes `e.key`, but not `e.code`) cannot orphan a pending release.
+    for (const [listener, pending] of this.pendingReleases) {
+      if (pending.code === physicalKey) {
+        const pressTimestamp = this.keyDownTimestamps.get(physicalKey);
+        const rt_key_duration =
+          pressTimestamp === undefined ? null : Math.round(performance.now() - pressTimestamp);
+        this.pendingReleases.delete(listener);
+        // report the key as it was at keydown, so that the deferred and immediate paths record
+        // the same response for the same key press
+        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.
+   */
+  private 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();
+  }
+
   private isResponseValid(validResponses: ValidResponses, allowHeldKey: boolean, key: string) {
     // check if key was already held down
     if (!allowHeldKey && this.heldKeys.has(key)) {
@@ -87,6 +153,7 @@ export class KeyboardListenerAPI {
     audio_context_start_time,
     allow_held_key = false,
     minimum_valid_rt = this.minimumValidRt,
+    wait_for_key_release = false,
   }: GetKeyboardResponseOptions) {
     if (rt_method !== "performance" && rt_method !== "audio") {
       console.log(
@@ -125,7 +192,26 @@ export class KeyboardListenerAPI {
           this.cancelKeyboardResponse(listener);
         }
 
-        callback_function({ key: e.key, rt });
+        if (wait_for_key_release) {
+          // defer the callback until this key is released, keyed by the listener handle so that
+          // the pending release is cancelled together with the listener (see cancelKeyboardResponse
+          // and cancelAllKeyboardResponses).
+          //
+          // Because the pending release is keyed by listener, each listener tracks only one pending
+          // release at a time. With persist: true, if a second valid key is pressed before the first
+          // is released, this overwrites the earlier pending release: the superseded press is
+          // dropped and only the most recent press's release fires the callback. This is a
+          // deliberate trade-off of the single-slot design — note that it differs from the
+          // non-deferred persist path, which fires the callback for every valid press.
+          this.pendingReleases.set(listener, {
+            code: this.getPhysicalKey(e),
+            key: e.key,
+            rt,
+            callback_function,
+          });
+        } else {
+          callback_function({ key: e.key, rt });
+        }
       }
     };
 
@@ -136,10 +222,13 @@ export class KeyboardListenerAPI {
   cancelKeyboardResponse(listener: KeyboardListener) {
     // remove the listener from the set of listeners if it is contained
     this.listeners.delete(listener);
+    // also drop any pending release so a deferred callback never fires after cancellation
+    this.pendingReleases.delete(listener);
   }
 
   cancelAllKeyboardResponses() {
     this.listeners.clear();
+    this.pendingReleases.clear();
   }
 
   compareKeys(key1: string | null, key2: string | null) {

package/src/modules/plugins.ts

@@ -51,6 +51,7 @@ export type ParameterInfo = (
   array?: boolean;
   pretty_name?: string;
   default?: any;
+  options?: any;
 };
 
 export type ParameterInfos = Record<string, ParameterInfo>;

package/src/timeline/Trial.spec.ts

@@ -235,7 +235,7 @@ describe("Trial", () => {
     });
 
     it("respects the `save_trial_parameters` parameter", async () => {
-      const consoleSpy = jest.spyOn(console, "warn").mockImplementation();
+      const consoleSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
 
       TestPlugin.setParameterInfos({
         stringParameter1: { type: ParameterType.STRING },
@@ -560,6 +560,110 @@ describe("Trial", () => {
       });
     });
 
+    describe("with parameter type mismatches", () => {
+      //TODO: redo these to expect errors on v9!
+      let consoleSpy: jest.SpyInstance;
+
+      beforeEach(() => {
+        consoleSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+      });
+
+      afterEach(() => {
+        consoleSpy.mockRestore();
+      });
+
+      it("errors on non-boolean values for boolean parameters", async () => {
+        TestPlugin.setParameterInfos({
+          boolParameter: { type: ParameterType.BOOL },
+        });
+
+        // this should work:
+        await createTrial({ type: TestPlugin, boolParameter: true }).run();
+
+        // this shouldn't:
+        await createTrial({ type: TestPlugin, boolParameter: "foo" }).run();
+        expect(consoleSpy).toHaveBeenCalledWith(
+          'A non-boolean value (`foo`) was provided for the boolean parameter "boolParameter" in the "test" plugin.'
+        );
+      });
+
+      it("errors on non-string values for string parameters", async () => {
+        TestPlugin.setParameterInfos({
+          stringParameter: { type: ParameterType.STRING },
+        });
+
+        // this should work:
+        await createTrial({ type: TestPlugin, stringParameter: "foo" }).run();
+
+        // this shouldn't:
+        await createTrial({ type: TestPlugin, stringParameter: 1 }).run();
+        expect(consoleSpy).toHaveBeenCalledWith(
+          'A non-string value (`1`) was provided for the parameter "stringParameter" in the "test" plugin.'
+        );
+      });
+
+      it("errors on non-numeric values for numeric parameters", async () => {
+        TestPlugin.setParameterInfos({
+          intParameter: { type: ParameterType.INT },
+          floatParameter: { type: ParameterType.FLOAT },
+        });
+
+        // this should work:
+        await createTrial({ type: TestPlugin, intParameter: 1, floatParameter: 1.5 }).run();
+
+        // this shouldn't:
+        await createTrial({ type: TestPlugin, intParameter: "foo", floatParameter: 1.5 }).run();
+        expect(consoleSpy).toHaveBeenCalledWith(
+          'A non-numeric value (`foo`) was provided for the numeric parameter "intParameter" in the "test" plugin.'
+        );
+
+        await createTrial({ type: TestPlugin, intParameter: 1, floatParameter: "foo" }).run();
+        expect(consoleSpy).toHaveBeenCalledWith(
+          'A non-numeric value (`foo`) was provided for the numeric parameter "floatParameter" in the "test" plugin.'
+        );
+
+        // this should warn but not error (behavior in v9):
+        await createTrial({ type: TestPlugin, intParameter: 1.5, floatParameter: 1.5 }).run();
+        expect(consoleSpy).toHaveBeenCalledWith(
+          `A float value (\`1.5\`) was provided for the integer parameter "intParameter" in the "test" plugin. The value will be truncated to an integer.`
+        );
+      });
+
+      it("errors on non-function values for function parameters", async () => {
+        TestPlugin.setParameterInfos({
+          functionParameter: { type: ParameterType.FUNCTION },
+        });
+
+        // this should work:
+        await createTrial({ type: TestPlugin, functionParameter: () => {} }).run();
+
+        // this shouldn't:
+        await createTrial({ type: TestPlugin, functionParameter: "foo" }).run();
+        expect(consoleSpy).toHaveBeenCalledWith(
+          'A non-function value (`foo`) was provided for the function parameter "functionParameter" in the "test" plugin.'
+        );
+      });
+
+      it("errors on select parameters with values not in the options array", async () => {
+        TestPlugin.setParameterInfos({
+          selectParameter: {
+            type: ParameterType.SELECT,
+            options: ["foo", "bar"],
+          },
+        });
+
+        // this should work:
+        await createTrial({ type: TestPlugin, selectParameter: "foo" }).run();
+
+        // this shouldn't:
+
+        await createTrial({ type: TestPlugin, selectParameter: "baz" }).run();
+        expect(consoleSpy).toHaveBeenCalledWith(
+          'The value "baz" is not a valid option for the parameter "selectParameter" in the "test" plugin. Valid options are: foo, bar.'
+        );
+      });
+    });
+
     it("respects `default_iti` and `post_trial_gap``", async () => {
       dependencies.getDefaultIti.mockReturnValue(100);
       TestPlugin.setManualFinishTrialMode();

package/src/timeline/Trial.ts

@@ -360,6 +360,7 @@ export class Trial extends TimelineNode {
       for (const [parameterName, parameterConfig] of Object.entries(parameterInfos)) {
         const parameterPath = [...parentParameterPath, parameterName];
 
+        // evaluate parameter and validate required parameter
         let parameterValue = this.getParameterValue(parameterPath, {
           evaluateFunctions: parameterConfig.type !== ParameterType.FUNCTION,
           replaceResult: (originalResult) => {
@@ -379,6 +380,83 @@ export class Trial extends TimelineNode {
           },
         });
 
+        // TODO: ensure that this throws an error in v9!
+        // major parameter type validation
+        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: // "ALL_KEYS", "NO_KEYS", and single key strings are checked here
+              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.`
+                );
+              }
+          }
+
+          // truncate floats to integers if the parameter type is INT
+          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(", ")}.`
+            );
+          }
+        }
+
+        // array validation
         if (parameterConfig.array && !Array.isArray(parameterValue)) {
           const parameterPathString = parameterPathArrayToString(parameterPath);
           throw new Error(