@jspsych/plugin-image-keyboard-response 2.1.0 → 2.2.0

package/dist/index.browser.js

@@ -1,7 +1,7 @@
 var jsPsychImageKeyboardResponse = (function (jspsych) {
   'use strict';
 
-  var version = "2.1.0";
+  var version = "2.2.0";
 
   const info = {
     name: "image-keyboard-response",
@@ -72,6 +72,18 @@ var jsPsychImageKeyboardResponse = (function (jspsych) {
       render_on_canvas: {
         type: jspsych.ParameterType.BOOL,
         default: true
+      },
+      /**
+       * If true, the response is not registered until the participant releases the key. The response
+       * time (`rt`) still reflects when the key was pressed, and the additional data field
+       * `rt_key_duration` records how long the key was held down. Note that when this is true, the
+       * trial cannot end until the key is released: with `response_ends_trial: true` the trial ends at
+       * the key release, and if the trial ends for another reason (e.g., `trial_duration`) while the
+       * key is still held, no response is recorded for the trial.
+       */
+      wait_for_key_release: {
+        type: jspsych.ParameterType.BOOL,
+        default: false
       }
     },
     data: {
@@ -87,6 +99,10 @@ var jsPsychImageKeyboardResponse = (function (jspsych) {
        * first appears on the screen until the participant's response. */
       rt: {
         type: jspsych.ParameterType.INT
+      },
+      /** The duration in milliseconds that the response key was held down, measured from key press to key release. Only recorded when `wait_for_key_release` is true; null otherwise or when no response was made. */
+      rt_key_duration: {
+        type: jspsych.ParameterType.INT
       }
     },
     // prettier-ignore
@@ -183,7 +199,8 @@ var jsPsychImageKeyboardResponse = (function (jspsych) {
       }
       var response = {
         rt: null,
-        key: null
+        key: null,
+        rt_key_duration: null
       };
       const end_trial = () => {
         if (typeof keyboardListener !== "undefined") {
@@ -192,14 +209,19 @@ var jsPsychImageKeyboardResponse = (function (jspsych) {
         var trial_data = {
           rt: response.rt,
           stimulus: trial.stimulus,
-          response: response.key
+          response: response.key,
+          rt_key_duration: response.rt_key_duration
         };
         this.jsPsych.finishTrial(trial_data);
       };
       var after_response = (info2) => {
         display_element.querySelector("#jspsych-image-keyboard-response-stimulus").className += " responded";
         if (response.key == null) {
-          response = info2;
+          response = {
+            rt: info2.rt,
+            key: info2.key,
+            rt_key_duration: info2.rt_key_duration ?? null
+          };
         }
         if (trial.response_ends_trial) {
           end_trial();
@@ -211,7 +233,8 @@ var jsPsychImageKeyboardResponse = (function (jspsych) {
           valid_responses: trial.choices,
           rt_method: "performance",
           persist: false,
-          allow_held_key: false
+          allow_held_key: false,
+          wait_for_key_release: trial.wait_for_key_release
         });
       }
       if (trial.stimulus_duration !== null) {
@@ -257,8 +280,10 @@ var jsPsychImageKeyboardResponse = (function (jspsych) {
       const default_data = {
         stimulus: trial.stimulus,
         rt: this.jsPsych.randomization.sampleExGaussian(500, 50, 1 / 150, true),
-        response: this.jsPsych.pluginAPI.getValidKey(trial.choices)
+        response: this.jsPsych.pluginAPI.getValidKey(trial.choices),
+        rt_key_duration: null
       };
+      default_data.rt_key_duration = default_data.rt === null || !trial.wait_for_key_release ? null : this.jsPsych.randomization.sampleExGaussian(150, 30, 1 / 100, true);
       const data = this.jsPsych.pluginAPI.mergeSimulationData(default_data, simulation_options);
       this.jsPsych.pluginAPI.ensureSimulationDataConsistency(trial, data);
       return data;
@@ -268,4 +293,4 @@ var jsPsychImageKeyboardResponse = (function (jspsych) {
   return ImageKeyboardResponsePlugin;
 
 })(jsPsychModule);
-//# sourceMappingURL=https://unpkg.com/@jspsych/plugin-image-keyboard-response@2.1.0/dist/index.browser.js.map
+//# sourceMappingURL=https://unpkg.com/@jspsych/plugin-image-keyboard-response@2.2.0/dist/index.browser.js.map

package/dist/index.browser.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.browser.js","sources":["../package.json","../src/index.ts"],"sourcesContent":["{\n  \"name\": \"@jspsych/plugin-image-keyboard-response\",\n  \"version\": \"2.1.0\",\n  \"description\": \"jsPsych plugin for displaying a stimulus and getting a keyboard response\",\n  \"type\": \"module\",\n  \"main\": \"dist/index.cjs\",\n  \"exports\": {\n    \"import\": \"./dist/index.js\",\n    \"require\": \"./dist/index.cjs\"\n  },\n  \"typings\": \"dist/index.d.ts\",\n  \"unpkg\": \"dist/index.browser.min.js\",\n  \"files\": [\n    \"src\",\n    \"dist\"\n  ],\n  \"source\": \"src/index.ts\",\n  \"scripts\": {\n    \"test\": \"jest\",\n    \"test:watch\": \"npm test -- --watch\",\n    \"tsc\": \"tsc\",\n    \"build\": \"rollup --config\",\n    \"build:watch\": \"npm run build -- --watch\"\n  },\n  \"repository\": {\n    \"type\": \"git\",\n    \"url\": \"git+https://github.com/jspsych/jsPsych.git\",\n    \"directory\": \"packages/plugin-image-keyboard-response\"\n  },\n  \"author\": \"Josh de Leeuw\",\n  \"license\": \"MIT\",\n  \"bugs\": {\n    \"url\": \"https://github.com/jspsych/jsPsych/issues\"\n  },\n  \"homepage\": \"https://www.jspsych.org/latest/plugins/image-keyboard-response\",\n  \"peerDependencies\": {\n    \"jspsych\": \">=7.1.0\"\n  },\n  \"devDependencies\": {\n    \"@jspsych/config\": \"^3.2.0\",\n    \"@jspsych/test-utils\": \"^1.2.0\"\n  }\n}\n","import { JsPsych, JsPsychPlugin, ParameterType, TrialType } from \"jspsych\";\n\nimport { version } from \"../package.json\";\n\nconst info = <const>{\n  name: \"image-keyboard-response\",\n  version: version,\n  parameters: {\n    /** The path of the image file to be displayed. */\n    stimulus: {\n      type: ParameterType.IMAGE,\n      default: undefined,\n    },\n    /** Set the height of the image in pixels. If left null (no value specified), then the image will display at its natural height. */\n    stimulus_height: {\n      type: ParameterType.INT,\n      default: null,\n    },\n    /** Set the width of the image in pixels. If left null (no value specified), then the image will display at its natural width. */\n    stimulus_width: {\n      type: ParameterType.INT,\n      default: null,\n    },\n    /** If setting *only* the width or *only* the height and this parameter is true, then the other dimension will be scaled\n     * to maintain the image's aspect ratio. */\n    maintain_aspect_ratio: {\n      type: ParameterType.BOOL,\n      default: true,\n    },\n    /**his array contains the key(s) that the participant is allowed to press in order to respond to the stimulus. Keys should\n     * be specified as characters (e.g., `'a'`, `'q'`, `' '`, `'Enter'`, `'ArrowDown'`) - see\n     * [this page](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values) and\n     * [this page (event.key column)](https://www.freecodecamp.org/news/javascript-keycode-list-keypress-event-key-codes/)\n     * for more examples. Any key presses that are not listed in the array will be ignored. The default value of `\"ALL_KEYS\"`\n     * means that all keys will be accepted as valid responses. Specifying `\"NO_KEYS\"` will mean that no responses are allowed. */\n    choices: {\n      type: ParameterType.KEYS,\n      default: \"ALL_KEYS\",\n    },\n    /**This string can contain HTML markup. Any content here will be displayed below the stimulus. The intention is that it can\n     * be used to provide a reminder about the action the participant is supposed to take (e.g., which key to press). */\n    prompt: {\n      type: ParameterType.HTML_STRING,\n      default: null,\n    },\n    /** How long to show the stimulus for in milliseconds. If the value is `null`, then the stimulus will be shown until the\n     * participant makes a response. */\n    stimulus_duration: {\n      type: ParameterType.INT,\n      default: null,\n    },\n    /** How long to wait for the participant to make a response before ending the trial in milliseconds. If the participant\n     * fails to make a response before this timer is reached, the participant's response will be recorded as null for the\n     * trial and the trial will end. If the value of this parameter is `null`, then the trial will wait for a response indefinitely. */\n    trial_duration: {\n      type: ParameterType.INT,\n      default: null,\n    },\n    /** If true, then the trial will end whenever the participant makes a response (assuming they make their response before\n     * the cutoff specified by the `trial_duration` parameter). If false, then the trial will continue until the value for\n     * `trial_duration` is reached. You can set this parameter to `false` to force the participant to view a stimulus for a\n     * fixed amount of time, even if they respond before the time is complete.  */\n    response_ends_trial: {\n      type: ParameterType.BOOL,\n      default: true,\n    },\n    /**\n     * If `true`, the image will be drawn onto a canvas element. This prevents a blank screen (white flash) between consecutive image trials in some browsers, like Firefox and Edge.\n     * If `false`, the image will be shown via an img element, as in previous versions of jsPsych. If the stimulus is an **animated gif**, you must set this parameter to false, because the canvas rendering method will only present static images.\n     */\n    render_on_canvas: {\n      type: ParameterType.BOOL,\n      default: true,\n    },\n  },\n  data: {\n    /** The path of the image that was displayed. */\n    stimulus: {\n      type: ParameterType.STRING,\n    },\n    /**  Indicates which key the participant pressed. */\n    response: {\n      type: ParameterType.STRING,\n    },\n    /** The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus\n     * first appears on the screen until the participant's response. */\n    rt: {\n      type: ParameterType.INT,\n    },\n  },\n  // prettier-ignore\n  citations: '__CITATIONS__',\n};\n\ntype Info = typeof info;\n\n/**\n * This plugin displays an image and records responses generated with the keyboard. The stimulus can be displayed until a\n * response is given, or for a pre-determined amount of time. The trial can be ended automatically if the participant has\n * failed to respond within a fixed length of time.\n *\n * Image files can be automatically preloaded by jsPsych using the [`preload` plugin](preload.md). However, if you are using\n * timeline variables or another dynamic method to specify the image stimulus, you will need to\n * [manually preload](../overview/media-preloading.md#manual-preloading) the images.\n *\n * @author Josh de Leeuw\n * @see {@link https://www.jspsych.org/latest/plugins/image-keyboard-response/ image-keyboard-response plugin documentation on jspsych.org}\n */\nclass ImageKeyboardResponsePlugin implements JsPsychPlugin<Info> {\n  static info = info;\n\n  constructor(private jsPsych: JsPsych) {}\n\n  trial(display_element: HTMLElement, trial: TrialType<Info>) {\n    var height, width;\n    if (trial.render_on_canvas) {\n      var image_drawn = false;\n      // first clear the display element (because the render_on_canvas method appends to display_element instead of overwriting it with .innerHTML)\n      if (display_element.hasChildNodes()) {\n        // can't loop through child list because the list will be modified by .removeChild()\n        while (display_element.firstChild) {\n          display_element.removeChild(display_element.firstChild);\n        }\n      }\n      // create canvas element and image\n      var canvas = document.createElement(\"canvas\");\n      canvas.id = \"jspsych-image-keyboard-response-stimulus\";\n      canvas.style.margin = \"0\";\n      canvas.style.padding = \"0\";\n      var ctx = canvas.getContext(\"2d\");\n      var img = new Image();\n      img.onload = () => {\n        // if image wasn't preloaded, then it will need to be drawn whenever it finishes loading\n        if (!image_drawn) {\n          getHeightWidth(); // only possible to get width/height after image loads\n          ctx.drawImage(img, 0, 0, width, height);\n        }\n      };\n      img.src = trial.stimulus;\n      // get/set image height and width - this can only be done after image loads because uses image's naturalWidth/naturalHeight properties\n      const getHeightWidth = () => {\n        if (trial.stimulus_height !== null) {\n          height = trial.stimulus_height;\n          if (trial.stimulus_width == null && trial.maintain_aspect_ratio) {\n            width = img.naturalWidth * (trial.stimulus_height / img.naturalHeight);\n          }\n        } else {\n          height = img.naturalHeight;\n        }\n        if (trial.stimulus_width !== null) {\n          width = trial.stimulus_width;\n          if (trial.stimulus_height == null && trial.maintain_aspect_ratio) {\n            height = img.naturalHeight * (trial.stimulus_width / img.naturalWidth);\n          }\n        } else if (!(trial.stimulus_height !== null && trial.maintain_aspect_ratio)) {\n          // if stimulus width is null, only use the image's natural width if the width value wasn't set\n          // in the if statement above, based on a specified height and maintain_aspect_ratio = true\n          width = img.naturalWidth;\n        }\n        canvas.height = height;\n        canvas.width = width;\n      };\n      getHeightWidth(); // call now, in case image loads immediately (is cached)\n      // add canvas and draw image\n      display_element.insertBefore(canvas, null);\n      if (img.complete && Number.isFinite(width) && Number.isFinite(height)) {\n        // if image has loaded and width/height have been set, then draw it now\n        // (don't rely on img onload function to draw image when image is in the cache, because that causes a delay in the image presentation)\n        ctx.drawImage(img, 0, 0, width, height);\n        image_drawn = true;\n      }\n      // add prompt if there is one\n      if (trial.prompt !== null) {\n        display_element.insertAdjacentHTML(\"beforeend\", trial.prompt);\n      }\n    } else {\n      // display stimulus as an image element\n      var html = '<img src=\"' + trial.stimulus + '\" id=\"jspsych-image-keyboard-response-stimulus\">';\n      // add prompt\n      if (trial.prompt !== null) {\n        html += trial.prompt;\n      }\n      // update the page content\n      display_element.innerHTML = html;\n\n      // set image dimensions after image has loaded (so that we have access to naturalHeight/naturalWidth)\n      var img = display_element.querySelector(\n        \"#jspsych-image-keyboard-response-stimulus\"\n      ) as HTMLImageElement;\n      if (trial.stimulus_height !== null) {\n        height = trial.stimulus_height;\n        if (trial.stimulus_width == null && trial.maintain_aspect_ratio) {\n          width = img.naturalWidth * (trial.stimulus_height / img.naturalHeight);\n        }\n      } else {\n        height = img.naturalHeight;\n      }\n      if (trial.stimulus_width !== null) {\n        width = trial.stimulus_width;\n        if (trial.stimulus_height == null && trial.maintain_aspect_ratio) {\n          height = img.naturalHeight * (trial.stimulus_width / img.naturalWidth);\n        }\n      } else if (!(trial.stimulus_height !== null && trial.maintain_aspect_ratio)) {\n        // if stimulus width is null, only use the image's natural width if the width value wasn't set\n        // in the if statement above, based on a specified height and maintain_aspect_ratio = true\n        width = img.naturalWidth;\n      }\n      img.style.height = height.toString() + \"px\";\n      img.style.width = width.toString() + \"px\";\n    }\n\n    // store response\n    var response = {\n      rt: null,\n      key: null,\n    };\n\n    // function to end trial when it is time\n    const end_trial = () => {\n      // kill keyboard listeners\n      if (typeof keyboardListener !== \"undefined\") {\n        this.jsPsych.pluginAPI.cancelKeyboardResponse(keyboardListener);\n      }\n\n      // gather the data to store for the trial\n      var trial_data = {\n        rt: response.rt,\n        stimulus: trial.stimulus,\n        response: response.key,\n      };\n\n      // move on to the next trial\n      this.jsPsych.finishTrial(trial_data);\n    };\n\n    // function to handle responses by the subject\n    var after_response = (info) => {\n      // after a valid response, the stimulus will have the CSS class 'responded'\n      // which can be used to provide visual feedback that a response was recorded\n      display_element.querySelector(\"#jspsych-image-keyboard-response-stimulus\").className +=\n        \" responded\";\n\n      // only record the first response\n      if (response.key == null) {\n        response = info;\n      }\n\n      if (trial.response_ends_trial) {\n        end_trial();\n      }\n    };\n\n    // start the response listener\n    if (trial.choices != \"NO_KEYS\") {\n      var keyboardListener = this.jsPsych.pluginAPI.getKeyboardResponse({\n        callback_function: after_response,\n        valid_responses: trial.choices,\n        rt_method: \"performance\",\n        persist: false,\n        allow_held_key: false,\n      });\n    }\n\n    // hide stimulus if stimulus_duration is set\n    if (trial.stimulus_duration !== null) {\n      this.jsPsych.pluginAPI.setTimeout(() => {\n        display_element.querySelector<HTMLElement>(\n          \"#jspsych-image-keyboard-response-stimulus\"\n        ).style.visibility = \"hidden\";\n      }, trial.stimulus_duration);\n    }\n\n    // end trial if trial_duration is set\n    if (trial.trial_duration !== null) {\n      this.jsPsych.pluginAPI.setTimeout(() => {\n        end_trial();\n      }, trial.trial_duration);\n    } else if (trial.response_ends_trial === false) {\n      console.warn(\n        \"The experiment may be deadlocked. Try setting a trial duration or set response_ends_trial to true.\"\n      );\n    }\n  }\n\n  simulate(\n    trial: TrialType<Info>,\n    simulation_mode,\n    simulation_options: any,\n    load_callback: () => void\n  ) {\n    if (simulation_mode == \"data-only\") {\n      load_callback();\n      this.simulate_data_only(trial, simulation_options);\n    }\n    if (simulation_mode == \"visual\") {\n      this.simulate_visual(trial, simulation_options, load_callback);\n    }\n  }\n\n  private simulate_data_only(trial: TrialType<Info>, simulation_options) {\n    const data = this.create_simulation_data(trial, simulation_options);\n\n    this.jsPsych.finishTrial(data);\n  }\n\n  private simulate_visual(trial: TrialType<Info>, simulation_options, load_callback: () => void) {\n    const data = this.create_simulation_data(trial, simulation_options);\n\n    const display_element = this.jsPsych.getDisplayElement();\n\n    this.trial(display_element, trial);\n    load_callback();\n\n    if (data.rt !== null) {\n      this.jsPsych.pluginAPI.pressKey(data.response, data.rt);\n    }\n  }\n\n  private create_simulation_data(trial: TrialType<Info>, simulation_options) {\n    const default_data = {\n      stimulus: trial.stimulus,\n      rt: this.jsPsych.randomization.sampleExGaussian(500, 50, 1 / 150, true),\n      response: this.jsPsych.pluginAPI.getValidKey(trial.choices),\n    };\n\n    const data = this.jsPsych.pluginAPI.mergeSimulationData(default_data, simulation_options);\n\n    this.jsPsych.pluginAPI.ensureSimulationDataConsistency(trial, data);\n\n    return data;\n  }\n}\n\nexport default ImageKeyboardResponsePlugin;\n"],"names":[],"mappings":";;;EAEE,IAAW,OAAA,GAAA,OAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ICyFA,SAAA,EAAA;EAAA;;KAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"index.browser.js","sources":["../package.json","../src/index.ts"],"sourcesContent":["{\n  \"name\": \"@jspsych/plugin-image-keyboard-response\",\n  \"version\": \"2.2.0\",\n  \"description\": \"jsPsych plugin for displaying a stimulus and getting a keyboard response\",\n  \"type\": \"module\",\n  \"main\": \"dist/index.cjs\",\n  \"exports\": {\n    \"import\": \"./dist/index.js\",\n    \"require\": \"./dist/index.cjs\"\n  },\n  \"typings\": \"dist/index.d.ts\",\n  \"unpkg\": \"dist/index.browser.min.js\",\n  \"files\": [\n    \"src\",\n    \"dist\"\n  ],\n  \"source\": \"src/index.ts\",\n  \"scripts\": {\n    \"test\": \"jest\",\n    \"test:watch\": \"npm test -- --watch\",\n    \"tsc\": \"tsc\",\n    \"build\": \"rollup --config\",\n    \"build:watch\": \"npm run build -- --watch\"\n  },\n  \"repository\": {\n    \"type\": \"git\",\n    \"url\": \"git+https://github.com/jspsych/jsPsych.git\",\n    \"directory\": \"packages/plugin-image-keyboard-response\"\n  },\n  \"author\": \"Josh de Leeuw\",\n  \"license\": \"MIT\",\n  \"bugs\": {\n    \"url\": \"https://github.com/jspsych/jsPsych/issues\"\n  },\n  \"homepage\": \"https://www.jspsych.org/latest/plugins/image-keyboard-response\",\n  \"peerDependencies\": {\n    \"jspsych\": \">=7.1.0\"\n  },\n  \"devDependencies\": {\n    \"@jspsych/config\": \"^3.3.4\",\n    \"@jspsych/test-utils\": \"^1.3.0\"\n  }\n}\n","import { JsPsych, JsPsychPlugin, ParameterType, TrialType } from \"jspsych\";\n\nimport { version } from \"../package.json\";\n\nconst info = <const>{\n  name: \"image-keyboard-response\",\n  version: version,\n  parameters: {\n    /** The path of the image file to be displayed. */\n    stimulus: {\n      type: ParameterType.IMAGE,\n      default: undefined,\n    },\n    /** Set the height of the image in pixels. If left null (no value specified), then the image will display at its natural height. */\n    stimulus_height: {\n      type: ParameterType.INT,\n      default: null,\n    },\n    /** Set the width of the image in pixels. If left null (no value specified), then the image will display at its natural width. */\n    stimulus_width: {\n      type: ParameterType.INT,\n      default: null,\n    },\n    /** If setting *only* the width or *only* the height and this parameter is true, then the other dimension will be scaled\n     * to maintain the image's aspect ratio. */\n    maintain_aspect_ratio: {\n      type: ParameterType.BOOL,\n      default: true,\n    },\n    /**his array contains the key(s) that the participant is allowed to press in order to respond to the stimulus. Keys should\n     * be specified as characters (e.g., `'a'`, `'q'`, `' '`, `'Enter'`, `'ArrowDown'`) - see\n     * [this page](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values) and\n     * [this page (event.key column)](https://www.freecodecamp.org/news/javascript-keycode-list-keypress-event-key-codes/)\n     * for more examples. Any key presses that are not listed in the array will be ignored. The default value of `\"ALL_KEYS\"`\n     * means that all keys will be accepted as valid responses. Specifying `\"NO_KEYS\"` will mean that no responses are allowed. */\n    choices: {\n      type: ParameterType.KEYS,\n      default: \"ALL_KEYS\",\n    },\n    /**This string can contain HTML markup. Any content here will be displayed below the stimulus. The intention is that it can\n     * be used to provide a reminder about the action the participant is supposed to take (e.g., which key to press). */\n    prompt: {\n      type: ParameterType.HTML_STRING,\n      default: null,\n    },\n    /** How long to show the stimulus for in milliseconds. If the value is `null`, then the stimulus will be shown until the\n     * participant makes a response. */\n    stimulus_duration: {\n      type: ParameterType.INT,\n      default: null,\n    },\n    /** How long to wait for the participant to make a response before ending the trial in milliseconds. If the participant\n     * fails to make a response before this timer is reached, the participant's response will be recorded as null for the\n     * trial and the trial will end. If the value of this parameter is `null`, then the trial will wait for a response indefinitely. */\n    trial_duration: {\n      type: ParameterType.INT,\n      default: null,\n    },\n    /** If true, then the trial will end whenever the participant makes a response (assuming they make their response before\n     * the cutoff specified by the `trial_duration` parameter). If false, then the trial will continue until the value for\n     * `trial_duration` is reached. You can set this parameter to `false` to force the participant to view a stimulus for a\n     * fixed amount of time, even if they respond before the time is complete.  */\n    response_ends_trial: {\n      type: ParameterType.BOOL,\n      default: true,\n    },\n    /**\n     * If `true`, the image will be drawn onto a canvas element. This prevents a blank screen (white flash) between consecutive image trials in some browsers, like Firefox and Edge.\n     * If `false`, the image will be shown via an img element, as in previous versions of jsPsych. If the stimulus is an **animated gif**, you must set this parameter to false, because the canvas rendering method will only present static images.\n     */\n    render_on_canvas: {\n      type: ParameterType.BOOL,\n      default: true,\n    },\n    /**\n     * If true, the response is not registered until the participant releases the key. The response\n     * time (`rt`) still reflects when the key was pressed, and the additional data field\n     * `rt_key_duration` records how long the key was held down. Note that when this is true, the\n     * trial cannot end until the key is released: with `response_ends_trial: true` the trial ends at\n     * the key release, and if the trial ends for another reason (e.g., `trial_duration`) while the\n     * key is still held, no response is recorded for the trial.\n     */\n    wait_for_key_release: {\n      type: ParameterType.BOOL,\n      default: false,\n    },\n  },\n  data: {\n    /** The path of the image that was displayed. */\n    stimulus: {\n      type: ParameterType.STRING,\n    },\n    /**  Indicates which key the participant pressed. */\n    response: {\n      type: ParameterType.STRING,\n    },\n    /** The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus\n     * first appears on the screen until the participant's response. */\n    rt: {\n      type: ParameterType.INT,\n    },\n    /** The duration in milliseconds that the response key was held down, measured from key press to key release. Only recorded when `wait_for_key_release` is true; null otherwise or when no response was made. */\n    rt_key_duration: {\n      type: ParameterType.INT,\n    },\n  },\n  // prettier-ignore\n  citations: '__CITATIONS__',\n};\n\ntype Info = typeof info;\n\n/**\n * This plugin displays an image and records responses generated with the keyboard. The stimulus can be displayed until a\n * response is given, or for a pre-determined amount of time. The trial can be ended automatically if the participant has\n * failed to respond within a fixed length of time.\n *\n * Image files can be automatically preloaded by jsPsych using the [`preload` plugin](preload.md). However, if you are using\n * timeline variables or another dynamic method to specify the image stimulus, you will need to\n * [manually preload](../overview/media-preloading.md#manual-preloading) the images.\n *\n * @author Josh de Leeuw\n * @see {@link https://www.jspsych.org/latest/plugins/image-keyboard-response/ image-keyboard-response plugin documentation on jspsych.org}\n */\nclass ImageKeyboardResponsePlugin implements JsPsychPlugin<Info> {\n  static info = info;\n\n  constructor(private jsPsych: JsPsych) {}\n\n  trial(display_element: HTMLElement, trial: TrialType<Info>) {\n    var height, width;\n    if (trial.render_on_canvas) {\n      var image_drawn = false;\n      // first clear the display element (because the render_on_canvas method appends to display_element instead of overwriting it with .innerHTML)\n      if (display_element.hasChildNodes()) {\n        // can't loop through child list because the list will be modified by .removeChild()\n        while (display_element.firstChild) {\n          display_element.removeChild(display_element.firstChild);\n        }\n      }\n      // create canvas element and image\n      var canvas = document.createElement(\"canvas\");\n      canvas.id = \"jspsych-image-keyboard-response-stimulus\";\n      canvas.style.margin = \"0\";\n      canvas.style.padding = \"0\";\n      var ctx = canvas.getContext(\"2d\");\n      var img = new Image();\n      img.onload = () => {\n        // if image wasn't preloaded, then it will need to be drawn whenever it finishes loading\n        if (!image_drawn) {\n          getHeightWidth(); // only possible to get width/height after image loads\n          ctx.drawImage(img, 0, 0, width, height);\n        }\n      };\n      img.src = trial.stimulus;\n      // get/set image height and width - this can only be done after image loads because uses image's naturalWidth/naturalHeight properties\n      const getHeightWidth = () => {\n        if (trial.stimulus_height !== null) {\n          height = trial.stimulus_height;\n          if (trial.stimulus_width == null && trial.maintain_aspect_ratio) {\n            width = img.naturalWidth * (trial.stimulus_height / img.naturalHeight);\n          }\n        } else {\n          height = img.naturalHeight;\n        }\n        if (trial.stimulus_width !== null) {\n          width = trial.stimulus_width;\n          if (trial.stimulus_height == null && trial.maintain_aspect_ratio) {\n            height = img.naturalHeight * (trial.stimulus_width / img.naturalWidth);\n          }\n        } else if (!(trial.stimulus_height !== null && trial.maintain_aspect_ratio)) {\n          // if stimulus width is null, only use the image's natural width if the width value wasn't set\n          // in the if statement above, based on a specified height and maintain_aspect_ratio = true\n          width = img.naturalWidth;\n        }\n        canvas.height = height;\n        canvas.width = width;\n      };\n      getHeightWidth(); // call now, in case image loads immediately (is cached)\n      // add canvas and draw image\n      display_element.insertBefore(canvas, null);\n      if (img.complete && Number.isFinite(width) && Number.isFinite(height)) {\n        // if image has loaded and width/height have been set, then draw it now\n        // (don't rely on img onload function to draw image when image is in the cache, because that causes a delay in the image presentation)\n        ctx.drawImage(img, 0, 0, width, height);\n        image_drawn = true;\n      }\n      // add prompt if there is one\n      if (trial.prompt !== null) {\n        display_element.insertAdjacentHTML(\"beforeend\", trial.prompt);\n      }\n    } else {\n      // display stimulus as an image element\n      var html = '<img src=\"' + trial.stimulus + '\" id=\"jspsych-image-keyboard-response-stimulus\">';\n      // add prompt\n      if (trial.prompt !== null) {\n        html += trial.prompt;\n      }\n      // update the page content\n      display_element.innerHTML = html;\n\n      // set image dimensions after image has loaded (so that we have access to naturalHeight/naturalWidth)\n      var img = display_element.querySelector(\n        \"#jspsych-image-keyboard-response-stimulus\"\n      ) as HTMLImageElement;\n      if (trial.stimulus_height !== null) {\n        height = trial.stimulus_height;\n        if (trial.stimulus_width == null && trial.maintain_aspect_ratio) {\n          width = img.naturalWidth * (trial.stimulus_height / img.naturalHeight);\n        }\n      } else {\n        height = img.naturalHeight;\n      }\n      if (trial.stimulus_width !== null) {\n        width = trial.stimulus_width;\n        if (trial.stimulus_height == null && trial.maintain_aspect_ratio) {\n          height = img.naturalHeight * (trial.stimulus_width / img.naturalWidth);\n        }\n      } else if (!(trial.stimulus_height !== null && trial.maintain_aspect_ratio)) {\n        // if stimulus width is null, only use the image's natural width if the width value wasn't set\n        // in the if statement above, based on a specified height and maintain_aspect_ratio = true\n        width = img.naturalWidth;\n      }\n      img.style.height = height.toString() + \"px\";\n      img.style.width = width.toString() + \"px\";\n    }\n\n    // store response\n    var response = {\n      rt: null,\n      key: null,\n      rt_key_duration: null,\n    };\n\n    // function to end trial when it is time\n    const end_trial = () => {\n      // kill keyboard listeners\n      if (typeof keyboardListener !== \"undefined\") {\n        this.jsPsych.pluginAPI.cancelKeyboardResponse(keyboardListener);\n      }\n\n      // gather the data to store for the trial\n      var trial_data = {\n        rt: response.rt,\n        stimulus: trial.stimulus,\n        response: response.key,\n        rt_key_duration: response.rt_key_duration,\n      };\n\n      // move on to the next trial\n      this.jsPsych.finishTrial(trial_data);\n    };\n\n    // function to handle responses by the subject\n    var after_response = (info) => {\n      // after a valid response, the stimulus will have the CSS class 'responded'\n      // which can be used to provide visual feedback that a response was recorded\n      display_element.querySelector(\"#jspsych-image-keyboard-response-stimulus\").className +=\n        \" responded\";\n\n      // only record the first response\n      if (response.key == null) {\n        response = {\n          rt: info.rt,\n          key: info.key,\n          rt_key_duration: info.rt_key_duration ?? null,\n        };\n      }\n\n      if (trial.response_ends_trial) {\n        end_trial();\n      }\n    };\n\n    // start the response listener\n    if (trial.choices != \"NO_KEYS\") {\n      var keyboardListener = this.jsPsych.pluginAPI.getKeyboardResponse({\n        callback_function: after_response,\n        valid_responses: trial.choices,\n        rt_method: \"performance\",\n        persist: false,\n        allow_held_key: false,\n        wait_for_key_release: trial.wait_for_key_release,\n      });\n    }\n\n    // hide stimulus if stimulus_duration is set\n    if (trial.stimulus_duration !== null) {\n      this.jsPsych.pluginAPI.setTimeout(() => {\n        display_element.querySelector<HTMLElement>(\n          \"#jspsych-image-keyboard-response-stimulus\"\n        ).style.visibility = \"hidden\";\n      }, trial.stimulus_duration);\n    }\n\n    // end trial if trial_duration is set\n    if (trial.trial_duration !== null) {\n      this.jsPsych.pluginAPI.setTimeout(() => {\n        end_trial();\n      }, trial.trial_duration);\n    } else if (trial.response_ends_trial === false) {\n      console.warn(\n        \"The experiment may be deadlocked. Try setting a trial duration or set response_ends_trial to true.\"\n      );\n    }\n  }\n\n  simulate(\n    trial: TrialType<Info>,\n    simulation_mode,\n    simulation_options: any,\n    load_callback: () => void\n  ) {\n    if (simulation_mode == \"data-only\") {\n      load_callback();\n      this.simulate_data_only(trial, simulation_options);\n    }\n    if (simulation_mode == \"visual\") {\n      this.simulate_visual(trial, simulation_options, load_callback);\n    }\n  }\n\n  private simulate_data_only(trial: TrialType<Info>, simulation_options) {\n    const data = this.create_simulation_data(trial, simulation_options);\n\n    this.jsPsych.finishTrial(data);\n  }\n\n  private simulate_visual(trial: TrialType<Info>, simulation_options, load_callback: () => void) {\n    const data = this.create_simulation_data(trial, simulation_options);\n\n    const display_element = this.jsPsych.getDisplayElement();\n\n    this.trial(display_element, trial);\n    load_callback();\n\n    if (data.rt !== null) {\n      this.jsPsych.pluginAPI.pressKey(data.response, data.rt);\n    }\n  }\n\n  private create_simulation_data(trial: TrialType<Info>, simulation_options) {\n    const default_data = {\n      stimulus: trial.stimulus,\n      rt: this.jsPsych.randomization.sampleExGaussian(500, 50, 1 / 150, true),\n      response: this.jsPsych.pluginAPI.getValidKey(trial.choices),\n      rt_key_duration: null,\n    };\n    default_data.rt_key_duration =\n      default_data.rt === null || !trial.wait_for_key_release\n        ? null\n        : this.jsPsych.randomization.sampleExGaussian(150, 30, 1 / 100, true);\n\n    const data = this.jsPsych.pluginAPI.mergeSimulationData(default_data, simulation_options);\n\n    this.jsPsych.pluginAPI.ensureSimulationDataConsistency(trial, data);\n\n    return data;\n  }\n}\n\nexport default ImageKeyboardResponsePlugin;\n"],"names":[],"mappings":";;;EAEE,IAAA,OAAA,GAAW,OAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ICyGA,SAAA,EAAA;EAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/index.browser.min.js

@@ -1,2 +1,2 @@
-var jsPsychImageKeyboardResponse=function(r){"use strict";var y="2.1.0";const _={name:"image-keyboard-response",version:y,parameters:{stimulus:{type:r.ParameterType.IMAGE,default:void 0},stimulus_height:{type:r.ParameterType.INT,default:null},stimulus_width:{type:r.ParameterType.INT,default:null},maintain_aspect_ratio:{type:r.ParameterType.BOOL,default:!0},choices:{type:r.ParameterType.KEYS,default:"ALL_KEYS"},prompt:{type:r.ParameterType.HTML_STRING,default:null},stimulus_duration:{type:r.ParameterType.INT,default:null},trial_duration:{type:r.ParameterType.INT,default:null},response_ends_trial:{type:r.ParameterType.BOOL,default:!0},render_on_canvas:{type:r.ParameterType.BOOL,default:!0}},data:{stimulus:{type:r.ParameterType.STRING},response:{type:r.ParameterType.STRING},rt:{type:r.ParameterType.INT}},citations:{apa:"de Leeuw, J. R., Gilbert, R. A., & Luchterhandt, B. (2023). jsPsych: Enabling an Open-Source Collaborative Ecosystem of Behavioral Experiments. Journal of Open Source Software, 8(85), 5351. https://doi.org/10.21105/joss.05351 ",bibtex:'@article{Leeuw2023jsPsych, 	author = {de Leeuw, Joshua R. and Gilbert, Rebecca A. and Luchterhandt, Bj{\\" o}rn}, 	journal = {Journal of Open Source Software}, 	doi = {10.21105/joss.05351}, 	issn = {2475-9066}, 	number = {85}, 	year = {2023}, 	month = {may 11}, 	pages = {5351}, 	publisher = {Open Journals}, 	title = {jsPsych: Enabling an {Open}-{Source} {Collaborative} {Ecosystem} of {Behavioral} {Experiments}}, 	url = {https://joss.theoj.org/papers/10.21105/joss.05351}, 	volume = {8}, }  '}};class m{constructor(e){this.jsPsych=e}trial(e,t){var s,i;if(t.render_on_canvas){var u=!1;if(e.hasChildNodes())for(;e.firstChild;)e.removeChild(e.firstChild);var l=document.createElement("canvas");l.id="jspsych-image-keyboard-response-stimulus",l.style.margin="0",l.style.padding="0";var h=l.getContext("2d"),a=new Image;a.onload=()=>{u||(n(),h.drawImage(a,0,0,i,s))},a.src=t.stimulus;const n=()=>{t.stimulus_height!==null?(s=t.stimulus_height,t.stimulus_width==null&&t.maintain_aspect_ratio&&(i=a.naturalWidth*(t.stimulus_height/a.naturalHeight))):s=a.naturalHeight,t.stimulus_width!==null?(i=t.stimulus_width,t.stimulus_height==null&&t.maintain_aspect_ratio&&(s=a.naturalHeight*(t.stimulus_width/a.naturalWidth))):t.stimulus_height!==null&&t.maintain_aspect_ratio||(i=a.naturalWidth),l.height=s,l.width=i};n(),e.insertBefore(l,null),a.complete&&Number.isFinite(i)&&Number.isFinite(s)&&(h.drawImage(a,0,0,i,s),u=!0),t.prompt!==null&&e.insertAdjacentHTML("beforeend",t.prompt)}else{var d='<img src="'+t.stimulus+'" id="jspsych-image-keyboard-response-stimulus">';t.prompt!==null&&(d+=t.prompt),e.innerHTML=d;var a=e.querySelector("#jspsych-image-keyboard-response-stimulus");t.stimulus_height!==null?(s=t.stimulus_height,t.stimulus_width==null&&t.maintain_aspect_ratio&&(i=a.naturalWidth*(t.stimulus_height/a.naturalHeight))):s=a.naturalHeight,t.stimulus_width!==null?(i=t.stimulus_width,t.stimulus_height==null&&t.maintain_aspect_ratio&&(s=a.naturalHeight*(t.stimulus_width/a.naturalWidth))):t.stimulus_height!==null&&t.maintain_aspect_ratio||(i=a.naturalWidth),a.style.height=s.toString()+"px",a.style.width=i.toString()+"px"}var o={rt:null,key:null};const p=()=>{typeof c!="undefined"&&this.jsPsych.pluginAPI.cancelKeyboardResponse(c);var n={rt:o.rt,stimulus:t.stimulus,response:o.key};this.jsPsych.finishTrial(n)};var g=n=>{e.querySelector("#jspsych-image-keyboard-response-stimulus").className+=" responded",o.key==null&&(o=n),t.response_ends_trial&&p()};if(t.choices!="NO_KEYS")var c=this.jsPsych.pluginAPI.getKeyboardResponse({callback_function:g,valid_responses:t.choices,rt_method:"performance",persist:!1,allow_held_key:!1});t.stimulus_duration!==null&&this.jsPsych.pluginAPI.setTimeout(()=>{e.querySelector("#jspsych-image-keyboard-response-stimulus").style.visibility="hidden"},t.stimulus_duration),t.trial_duration!==null?this.jsPsych.pluginAPI.setTimeout(()=>{p()},t.trial_duration):t.response_ends_trial===!1&&console.warn("The experiment may be deadlocked. Try setting a trial duration or set response_ends_trial to true.")}simulate(e,t,s,i){t=="data-only"&&(i(),this.simulate_data_only(e,s)),t=="visual"&&this.simulate_visual(e,s,i)}simulate_data_only(e,t){const s=this.create_simulation_data(e,t);this.jsPsych.finishTrial(s)}simulate_visual(e,t,s){const i=this.create_simulation_data(e,t),u=this.jsPsych.getDisplayElement();this.trial(u,e),s(),i.rt!==null&&this.jsPsych.pluginAPI.pressKey(i.response,i.rt)}create_simulation_data(e,t){const s={stimulus:e.stimulus,rt:this.jsPsych.randomization.sampleExGaussian(500,50,.006666666666666667,!0),response:this.jsPsych.pluginAPI.getValidKey(e.choices)},i=this.jsPsych.pluginAPI.mergeSimulationData(s,t);return this.jsPsych.pluginAPI.ensureSimulationDataConsistency(e,i),i}}return m.info=_,m}(jsPsychModule);
-//# sourceMappingURL=https://unpkg.com/@jspsych/plugin-image-keyboard-response@2.1.0/dist/index.browser.min.js.map
+var jsPsychImageKeyboardResponse=(function(r){"use strict";var c="2.2.0";const g={name:"image-keyboard-response",version:c,parameters:{stimulus:{type:r.ParameterType.IMAGE,default:void 0},stimulus_height:{type:r.ParameterType.INT,default:null},stimulus_width:{type:r.ParameterType.INT,default:null},maintain_aspect_ratio:{type:r.ParameterType.BOOL,default:!0},choices:{type:r.ParameterType.KEYS,default:"ALL_KEYS"},prompt:{type:r.ParameterType.HTML_STRING,default:null},stimulus_duration:{type:r.ParameterType.INT,default:null},trial_duration:{type:r.ParameterType.INT,default:null},response_ends_trial:{type:r.ParameterType.BOOL,default:!0},render_on_canvas:{type:r.ParameterType.BOOL,default:!0},wait_for_key_release:{type:r.ParameterType.BOOL,default:!1}},data:{stimulus:{type:r.ParameterType.STRING},response:{type:r.ParameterType.STRING},rt:{type:r.ParameterType.INT},rt_key_duration:{type:r.ParameterType.INT}},citations:{apa:"de Leeuw, J. R., Gilbert, R. A., & Luchterhandt, B. (2023). jsPsych: Enabling an Open-Source Collaborative Ecosystem of Behavioral Experiments. Journal of Open Source Software, 8(85), 5351. https://doi.org/10.21105/joss.05351 ",bibtex:'@article{Leeuw2023jsPsych, 	author = {de Leeuw, Joshua R. and Gilbert, Rebecca A. and Luchterhandt, Bj{\\" o}rn}, 	journal = {Journal of Open Source Software}, 	doi = {10.21105/joss.05351}, 	issn = {2475-9066}, 	number = {85}, 	year = {2023}, 	month = {may 11}, 	pages = {5351}, 	publisher = {Open Journals}, 	title = {jsPsych: Enabling an {Open}-{Source} {Collaborative} {Ecosystem} of {Behavioral} {Experiments}}, 	url = {https://joss.theoj.org/papers/10.21105/joss.05351}, 	volume = {8}, }  '}};class m{constructor(e){this.jsPsych=e}trial(e,t){var a,s;if(t.render_on_canvas){var o=!1;if(e.hasChildNodes())for(;e.firstChild;)e.removeChild(e.firstChild);var n=document.createElement("canvas");n.id="jspsych-image-keyboard-response-stimulus",n.style.margin="0",n.style.padding="0";var d=n.getContext("2d"),i=new Image;i.onload=()=>{o||(l(),d.drawImage(i,0,0,s,a))},i.src=t.stimulus;const l=()=>{t.stimulus_height!==null?(a=t.stimulus_height,t.stimulus_width==null&&t.maintain_aspect_ratio&&(s=i.naturalWidth*(t.stimulus_height/i.naturalHeight))):a=i.naturalHeight,t.stimulus_width!==null?(s=t.stimulus_width,t.stimulus_height==null&&t.maintain_aspect_ratio&&(a=i.naturalHeight*(t.stimulus_width/i.naturalWidth))):t.stimulus_height!==null&&t.maintain_aspect_ratio||(s=i.naturalWidth),n.height=a,n.width=s};l(),e.insertBefore(n,null),i.complete&&Number.isFinite(s)&&Number.isFinite(a)&&(d.drawImage(i,0,0,s,a),o=!0),t.prompt!==null&&e.insertAdjacentHTML("beforeend",t.prompt)}else{var h='<img src="'+t.stimulus+'" id="jspsych-image-keyboard-response-stimulus">';t.prompt!==null&&(h+=t.prompt),e.innerHTML=h;var i=e.querySelector("#jspsych-image-keyboard-response-stimulus");t.stimulus_height!==null?(a=t.stimulus_height,t.stimulus_width==null&&t.maintain_aspect_ratio&&(s=i.naturalWidth*(t.stimulus_height/i.naturalHeight))):a=i.naturalHeight,t.stimulus_width!==null?(s=t.stimulus_width,t.stimulus_height==null&&t.maintain_aspect_ratio&&(a=i.naturalHeight*(t.stimulus_width/i.naturalWidth))):t.stimulus_height!==null&&t.maintain_aspect_ratio||(s=i.naturalWidth),i.style.height=a.toString()+"px",i.style.width=s.toString()+"px"}var u={rt:null,key:null,rt_key_duration:null};const _=()=>{typeof p!="undefined"&&this.jsPsych.pluginAPI.cancelKeyboardResponse(p);var l={rt:u.rt,stimulus:t.stimulus,response:u.key,rt_key_duration:u.rt_key_duration};this.jsPsych.finishTrial(l)};var f=l=>{var y;e.querySelector("#jspsych-image-keyboard-response-stimulus").className+=" responded",u.key==null&&(u={rt:l.rt,key:l.key,rt_key_duration:(y=l.rt_key_duration)!=null?y:null}),t.response_ends_trial&&_()};if(t.choices!="NO_KEYS")var p=this.jsPsych.pluginAPI.getKeyboardResponse({callback_function:f,valid_responses:t.choices,rt_method:"performance",persist:!1,allow_held_key:!1,wait_for_key_release:t.wait_for_key_release});t.stimulus_duration!==null&&this.jsPsych.pluginAPI.setTimeout(()=>{e.querySelector("#jspsych-image-keyboard-response-stimulus").style.visibility="hidden"},t.stimulus_duration),t.trial_duration!==null?this.jsPsych.pluginAPI.setTimeout(()=>{_()},t.trial_duration):t.response_ends_trial===!1&&console.warn("The experiment may be deadlocked. Try setting a trial duration or set response_ends_trial to true.")}simulate(e,t,a,s){t=="data-only"&&(s(),this.simulate_data_only(e,a)),t=="visual"&&this.simulate_visual(e,a,s)}simulate_data_only(e,t){const a=this.create_simulation_data(e,t);this.jsPsych.finishTrial(a)}simulate_visual(e,t,a){const s=this.create_simulation_data(e,t),o=this.jsPsych.getDisplayElement();this.trial(o,e),a(),s.rt!==null&&this.jsPsych.pluginAPI.pressKey(s.response,s.rt)}create_simulation_data(e,t){const a={stimulus:e.stimulus,rt:this.jsPsych.randomization.sampleExGaussian(500,50,.006666666666666667,!0),response:this.jsPsych.pluginAPI.getValidKey(e.choices),rt_key_duration:null};a.rt_key_duration=a.rt===null||!e.wait_for_key_release?null:this.jsPsych.randomization.sampleExGaussian(150,30,.01,!0);const s=this.jsPsych.pluginAPI.mergeSimulationData(a,t);return this.jsPsych.pluginAPI.ensureSimulationDataConsistency(e,s),s}}return m.info=g,m})(jsPsychModule);
+//# sourceMappingURL=https://unpkg.com/@jspsych/plugin-image-keyboard-response@2.2.0/dist/index.browser.min.js.map

package/dist/index.browser.min.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.browser.min.js","sources":["../package.json","../src/index.ts"],"sourcesContent":["{\n  \"name\": \"@jspsych/plugin-image-keyboard-response\",\n  \"version\": \"2.1.0\",\n  \"description\": \"jsPsych plugin for displaying a stimulus and getting a keyboard response\",\n  \"type\": \"module\",\n  \"main\": \"dist/index.cjs\",\n  \"exports\": {\n    \"import\": \"./dist/index.js\",\n    \"require\": \"./dist/index.cjs\"\n  },\n  \"typings\": \"dist/index.d.ts\",\n  \"unpkg\": \"dist/index.browser.min.js\",\n  \"files\": [\n    \"src\",\n    \"dist\"\n  ],\n  \"source\": \"src/index.ts\",\n  \"scripts\": {\n    \"test\": \"jest\",\n    \"test:watch\": \"npm test -- --watch\",\n    \"tsc\": \"tsc\",\n    \"build\": \"rollup --config\",\n    \"build:watch\": \"npm run build -- --watch\"\n  },\n  \"repository\": {\n    \"type\": \"git\",\n    \"url\": \"git+https://github.com/jspsych/jsPsych.git\",\n    \"directory\": \"packages/plugin-image-keyboard-response\"\n  },\n  \"author\": \"Josh de Leeuw\",\n  \"license\": \"MIT\",\n  \"bugs\": {\n    \"url\": \"https://github.com/jspsych/jsPsych/issues\"\n  },\n  \"homepage\": \"https://www.jspsych.org/latest/plugins/image-keyboard-response\",\n  \"peerDependencies\": {\n    \"jspsych\": \">=7.1.0\"\n  },\n  \"devDependencies\": {\n    \"@jspsych/config\": \"^3.2.0\",\n    \"@jspsych/test-utils\": \"^1.2.0\"\n  }\n}\n","import { JsPsych, JsPsychPlugin, ParameterType, TrialType } from \"jspsych\";\n\nimport { version } from \"../package.json\";\n\nconst info = <const>{\n  name: \"image-keyboard-response\",\n  version: version,\n  parameters: {\n    /** The path of the image file to be displayed. */\n    stimulus: {\n      type: ParameterType.IMAGE,\n      default: undefined,\n    },\n    /** Set the height of the image in pixels. If left null (no value specified), then the image will display at its natural height. */\n    stimulus_height: {\n      type: ParameterType.INT,\n      default: null,\n    },\n    /** Set the width of the image in pixels. If left null (no value specified), then the image will display at its natural width. */\n    stimulus_width: {\n      type: ParameterType.INT,\n      default: null,\n    },\n    /** If setting *only* the width or *only* the height and this parameter is true, then the other dimension will be scaled\n     * to maintain the image's aspect ratio. */\n    maintain_aspect_ratio: {\n      type: ParameterType.BOOL,\n      default: true,\n    },\n    /**his array contains the key(s) that the participant is allowed to press in order to respond to the stimulus. Keys should\n     * be specified as characters (e.g., `'a'`, `'q'`, `' '`, `'Enter'`, `'ArrowDown'`) - see\n     * [this page](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values) and\n     * [this page (event.key column)](https://www.freecodecamp.org/news/javascript-keycode-list-keypress-event-key-codes/)\n     * for more examples. Any key presses that are not listed in the array will be ignored. The default value of `\"ALL_KEYS\"`\n     * means that all keys will be accepted as valid responses. Specifying `\"NO_KEYS\"` will mean that no responses are allowed. */\n    choices: {\n      type: ParameterType.KEYS,\n      default: \"ALL_KEYS\",\n    },\n    /**This string can contain HTML markup. Any content here will be displayed below the stimulus. The intention is that it can\n     * be used to provide a reminder about the action the participant is supposed to take (e.g., which key to press). */\n    prompt: {\n      type: ParameterType.HTML_STRING,\n      default: null,\n    },\n    /** How long to show the stimulus for in milliseconds. If the value is `null`, then the stimulus will be shown until the\n     * participant makes a response. */\n    stimulus_duration: {\n      type: ParameterType.INT,\n      default: null,\n    },\n    /** How long to wait for the participant to make a response before ending the trial in milliseconds. If the participant\n     * fails to make a response before this timer is reached, the participant's response will be recorded as null for the\n     * trial and the trial will end. If the value of this parameter is `null`, then the trial will wait for a response indefinitely. */\n    trial_duration: {\n      type: ParameterType.INT,\n      default: null,\n    },\n    /** If true, then the trial will end whenever the participant makes a response (assuming they make their response before\n     * the cutoff specified by the `trial_duration` parameter). If false, then the trial will continue until the value for\n     * `trial_duration` is reached. You can set this parameter to `false` to force the participant to view a stimulus for a\n     * fixed amount of time, even if they respond before the time is complete.  */\n    response_ends_trial: {\n      type: ParameterType.BOOL,\n      default: true,\n    },\n    /**\n     * If `true`, the image will be drawn onto a canvas element. This prevents a blank screen (white flash) between consecutive image trials in some browsers, like Firefox and Edge.\n     * If `false`, the image will be shown via an img element, as in previous versions of jsPsych. If the stimulus is an **animated gif**, you must set this parameter to false, because the canvas rendering method will only present static images.\n     */\n    render_on_canvas: {\n      type: ParameterType.BOOL,\n      default: true,\n    },\n  },\n  data: {\n    /** The path of the image that was displayed. */\n    stimulus: {\n      type: ParameterType.STRING,\n    },\n    /**  Indicates which key the participant pressed. */\n    response: {\n      type: ParameterType.STRING,\n    },\n    /** The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus\n     * first appears on the screen until the participant's response. */\n    rt: {\n      type: ParameterType.INT,\n    },\n  },\n  // prettier-ignore\n  citations: '__CITATIONS__',\n};\n\ntype Info = typeof info;\n\n/**\n * This plugin displays an image and records responses generated with the keyboard. The stimulus can be displayed until a\n * response is given, or for a pre-determined amount of time. The trial can be ended automatically if the participant has\n * failed to respond within a fixed length of time.\n *\n * Image files can be automatically preloaded by jsPsych using the [`preload` plugin](preload.md). However, if you are using\n * timeline variables or another dynamic method to specify the image stimulus, you will need to\n * [manually preload](../overview/media-preloading.md#manual-preloading) the images.\n *\n * @author Josh de Leeuw\n * @see {@link https://www.jspsych.org/latest/plugins/image-keyboard-response/ image-keyboard-response plugin documentation on jspsych.org}\n */\nclass ImageKeyboardResponsePlugin implements JsPsychPlugin<Info> {\n  static info = info;\n\n  constructor(private jsPsych: JsPsych) {}\n\n  trial(display_element: HTMLElement, trial: TrialType<Info>) {\n    var height, width;\n    if (trial.render_on_canvas) {\n      var image_drawn = false;\n      // first clear the display element (because the render_on_canvas method appends to display_element instead of overwriting it with .innerHTML)\n      if (display_element.hasChildNodes()) {\n        // can't loop through child list because the list will be modified by .removeChild()\n        while (display_element.firstChild) {\n          display_element.removeChild(display_element.firstChild);\n        }\n      }\n      // create canvas element and image\n      var canvas = document.createElement(\"canvas\");\n      canvas.id = \"jspsych-image-keyboard-response-stimulus\";\n      canvas.style.margin = \"0\";\n      canvas.style.padding = \"0\";\n      var ctx = canvas.getContext(\"2d\");\n      var img = new Image();\n      img.onload = () => {\n        // if image wasn't preloaded, then it will need to be drawn whenever it finishes loading\n        if (!image_drawn) {\n          getHeightWidth(); // only possible to get width/height after image loads\n          ctx.drawImage(img, 0, 0, width, height);\n        }\n      };\n      img.src = trial.stimulus;\n      // get/set image height and width - this can only be done after image loads because uses image's naturalWidth/naturalHeight properties\n      const getHeightWidth = () => {\n        if (trial.stimulus_height !== null) {\n          height = trial.stimulus_height;\n          if (trial.stimulus_width == null && trial.maintain_aspect_ratio) {\n            width = img.naturalWidth * (trial.stimulus_height / img.naturalHeight);\n          }\n        } else {\n          height = img.naturalHeight;\n        }\n        if (trial.stimulus_width !== null) {\n          width = trial.stimulus_width;\n          if (trial.stimulus_height == null && trial.maintain_aspect_ratio) {\n            height = img.naturalHeight * (trial.stimulus_width / img.naturalWidth);\n          }\n        } else if (!(trial.stimulus_height !== null && trial.maintain_aspect_ratio)) {\n          // if stimulus width is null, only use the image's natural width if the width value wasn't set\n          // in the if statement above, based on a specified height and maintain_aspect_ratio = true\n          width = img.naturalWidth;\n        }\n        canvas.height = height;\n        canvas.width = width;\n      };\n      getHeightWidth(); // call now, in case image loads immediately (is cached)\n      // add canvas and draw image\n      display_element.insertBefore(canvas, null);\n      if (img.complete && Number.isFinite(width) && Number.isFinite(height)) {\n        // if image has loaded and width/height have been set, then draw it now\n        // (don't rely on img onload function to draw image when image is in the cache, because that causes a delay in the image presentation)\n        ctx.drawImage(img, 0, 0, width, height);\n        image_drawn = true;\n      }\n      // add prompt if there is one\n      if (trial.prompt !== null) {\n        display_element.insertAdjacentHTML(\"beforeend\", trial.prompt);\n      }\n    } else {\n      // display stimulus as an image element\n      var html = '<img src=\"' + trial.stimulus + '\" id=\"jspsych-image-keyboard-response-stimulus\">';\n      // add prompt\n      if (trial.prompt !== null) {\n        html += trial.prompt;\n      }\n      // update the page content\n      display_element.innerHTML = html;\n\n      // set image dimensions after image has loaded (so that we have access to naturalHeight/naturalWidth)\n      var img = display_element.querySelector(\n        \"#jspsych-image-keyboard-response-stimulus\"\n      ) as HTMLImageElement;\n      if (trial.stimulus_height !== null) {\n        height = trial.stimulus_height;\n        if (trial.stimulus_width == null && trial.maintain_aspect_ratio) {\n          width = img.naturalWidth * (trial.stimulus_height / img.naturalHeight);\n        }\n      } else {\n        height = img.naturalHeight;\n      }\n      if (trial.stimulus_width !== null) {\n        width = trial.stimulus_width;\n        if (trial.stimulus_height == null && trial.maintain_aspect_ratio) {\n          height = img.naturalHeight * (trial.stimulus_width / img.naturalWidth);\n        }\n      } else if (!(trial.stimulus_height !== null && trial.maintain_aspect_ratio)) {\n        // if stimulus width is null, only use the image's natural width if the width value wasn't set\n        // in the if statement above, based on a specified height and maintain_aspect_ratio = true\n        width = img.naturalWidth;\n      }\n      img.style.height = height.toString() + \"px\";\n      img.style.width = width.toString() + \"px\";\n    }\n\n    // store response\n    var response = {\n      rt: null,\n      key: null,\n    };\n\n    // function to end trial when it is time\n    const end_trial = () => {\n      // kill keyboard listeners\n      if (typeof keyboardListener !== \"undefined\") {\n        this.jsPsych.pluginAPI.cancelKeyboardResponse(keyboardListener);\n      }\n\n      // gather the data to store for the trial\n      var trial_data = {\n        rt: response.rt,\n        stimulus: trial.stimulus,\n        response: response.key,\n      };\n\n      // move on to the next trial\n      this.jsPsych.finishTrial(trial_data);\n    };\n\n    // function to handle responses by the subject\n    var after_response = (info) => {\n      // after a valid response, the stimulus will have the CSS class 'responded'\n      // which can be used to provide visual feedback that a response was recorded\n      display_element.querySelector(\"#jspsych-image-keyboard-response-stimulus\").className +=\n        \" responded\";\n\n      // only record the first response\n      if (response.key == null) {\n        response = info;\n      }\n\n      if (trial.response_ends_trial) {\n        end_trial();\n      }\n    };\n\n    // start the response listener\n    if (trial.choices != \"NO_KEYS\") {\n      var keyboardListener = this.jsPsych.pluginAPI.getKeyboardResponse({\n        callback_function: after_response,\n        valid_responses: trial.choices,\n        rt_method: \"performance\",\n        persist: false,\n        allow_held_key: false,\n      });\n    }\n\n    // hide stimulus if stimulus_duration is set\n    if (trial.stimulus_duration !== null) {\n      this.jsPsych.pluginAPI.setTimeout(() => {\n        display_element.querySelector<HTMLElement>(\n          \"#jspsych-image-keyboard-response-stimulus\"\n        ).style.visibility = \"hidden\";\n      }, trial.stimulus_duration);\n    }\n\n    // end trial if trial_duration is set\n    if (trial.trial_duration !== null) {\n      this.jsPsych.pluginAPI.setTimeout(() => {\n        end_trial();\n      }, trial.trial_duration);\n    } else if (trial.response_ends_trial === false) {\n      console.warn(\n        \"The experiment may be deadlocked. Try setting a trial duration or set response_ends_trial to true.\"\n      );\n    }\n  }\n\n  simulate(\n    trial: TrialType<Info>,\n    simulation_mode,\n    simulation_options: any,\n    load_callback: () => void\n  ) {\n    if (simulation_mode == \"data-only\") {\n      load_callback();\n      this.simulate_data_only(trial, simulation_options);\n    }\n    if (simulation_mode == \"visual\") {\n      this.simulate_visual(trial, simulation_options, load_callback);\n    }\n  }\n\n  private simulate_data_only(trial: TrialType<Info>, simulation_options) {\n    const data = this.create_simulation_data(trial, simulation_options);\n\n    this.jsPsych.finishTrial(data);\n  }\n\n  private simulate_visual(trial: TrialType<Info>, simulation_options, load_callback: () => void) {\n    const data = this.create_simulation_data(trial, simulation_options);\n\n    const display_element = this.jsPsych.getDisplayElement();\n\n    this.trial(display_element, trial);\n    load_callback();\n\n    if (data.rt !== null) {\n      this.jsPsych.pluginAPI.pressKey(data.response, data.rt);\n    }\n  }\n\n  private create_simulation_data(trial: TrialType<Info>, simulation_options) {\n    const default_data = {\n      stimulus: trial.stimulus,\n      rt: this.jsPsych.randomization.sampleExGaussian(500, 50, 1 / 150, true),\n      response: this.jsPsych.pluginAPI.getValidKey(trial.choices),\n    };\n\n    const data = this.jsPsych.pluginAPI.mergeSimulationData(default_data, simulation_options);\n\n    this.jsPsych.pluginAPI.ensureSimulationDataConsistency(trial, data);\n\n    return data;\n  }\n}\n\nexport default ImageKeyboardResponsePlugin;\n"],"names":["version"],"mappings":"0DAEEA,IAAAA,EAAW,6uBCyFA,UAAA,iuBAAe"}
+{"version":3,"file":"index.browser.min.js","sources":["../package.json","../src/index.ts"],"sourcesContent":["{\n  \"name\": \"@jspsych/plugin-image-keyboard-response\",\n  \"version\": \"2.2.0\",\n  \"description\": \"jsPsych plugin for displaying a stimulus and getting a keyboard response\",\n  \"type\": \"module\",\n  \"main\": \"dist/index.cjs\",\n  \"exports\": {\n    \"import\": \"./dist/index.js\",\n    \"require\": \"./dist/index.cjs\"\n  },\n  \"typings\": \"dist/index.d.ts\",\n  \"unpkg\": \"dist/index.browser.min.js\",\n  \"files\": [\n    \"src\",\n    \"dist\"\n  ],\n  \"source\": \"src/index.ts\",\n  \"scripts\": {\n    \"test\": \"jest\",\n    \"test:watch\": \"npm test -- --watch\",\n    \"tsc\": \"tsc\",\n    \"build\": \"rollup --config\",\n    \"build:watch\": \"npm run build -- --watch\"\n  },\n  \"repository\": {\n    \"type\": \"git\",\n    \"url\": \"git+https://github.com/jspsych/jsPsych.git\",\n    \"directory\": \"packages/plugin-image-keyboard-response\"\n  },\n  \"author\": \"Josh de Leeuw\",\n  \"license\": \"MIT\",\n  \"bugs\": {\n    \"url\": \"https://github.com/jspsych/jsPsych/issues\"\n  },\n  \"homepage\": \"https://www.jspsych.org/latest/plugins/image-keyboard-response\",\n  \"peerDependencies\": {\n    \"jspsych\": \">=7.1.0\"\n  },\n  \"devDependencies\": {\n    \"@jspsych/config\": \"^3.3.4\",\n    \"@jspsych/test-utils\": \"^1.3.0\"\n  }\n}\n","import { JsPsych, JsPsychPlugin, ParameterType, TrialType } from \"jspsych\";\n\nimport { version } from \"../package.json\";\n\nconst info = <const>{\n  name: \"image-keyboard-response\",\n  version: version,\n  parameters: {\n    /** The path of the image file to be displayed. */\n    stimulus: {\n      type: ParameterType.IMAGE,\n      default: undefined,\n    },\n    /** Set the height of the image in pixels. If left null (no value specified), then the image will display at its natural height. */\n    stimulus_height: {\n      type: ParameterType.INT,\n      default: null,\n    },\n    /** Set the width of the image in pixels. If left null (no value specified), then the image will display at its natural width. */\n    stimulus_width: {\n      type: ParameterType.INT,\n      default: null,\n    },\n    /** If setting *only* the width or *only* the height and this parameter is true, then the other dimension will be scaled\n     * to maintain the image's aspect ratio. */\n    maintain_aspect_ratio: {\n      type: ParameterType.BOOL,\n      default: true,\n    },\n    /**his array contains the key(s) that the participant is allowed to press in order to respond to the stimulus. Keys should\n     * be specified as characters (e.g., `'a'`, `'q'`, `' '`, `'Enter'`, `'ArrowDown'`) - see\n     * [this page](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values) and\n     * [this page (event.key column)](https://www.freecodecamp.org/news/javascript-keycode-list-keypress-event-key-codes/)\n     * for more examples. Any key presses that are not listed in the array will be ignored. The default value of `\"ALL_KEYS\"`\n     * means that all keys will be accepted as valid responses. Specifying `\"NO_KEYS\"` will mean that no responses are allowed. */\n    choices: {\n      type: ParameterType.KEYS,\n      default: \"ALL_KEYS\",\n    },\n    /**This string can contain HTML markup. Any content here will be displayed below the stimulus. The intention is that it can\n     * be used to provide a reminder about the action the participant is supposed to take (e.g., which key to press). */\n    prompt: {\n      type: ParameterType.HTML_STRING,\n      default: null,\n    },\n    /** How long to show the stimulus for in milliseconds. If the value is `null`, then the stimulus will be shown until the\n     * participant makes a response. */\n    stimulus_duration: {\n      type: ParameterType.INT,\n      default: null,\n    },\n    /** How long to wait for the participant to make a response before ending the trial in milliseconds. If the participant\n     * fails to make a response before this timer is reached, the participant's response will be recorded as null for the\n     * trial and the trial will end. If the value of this parameter is `null`, then the trial will wait for a response indefinitely. */\n    trial_duration: {\n      type: ParameterType.INT,\n      default: null,\n    },\n    /** If true, then the trial will end whenever the participant makes a response (assuming they make their response before\n     * the cutoff specified by the `trial_duration` parameter). If false, then the trial will continue until the value for\n     * `trial_duration` is reached. You can set this parameter to `false` to force the participant to view a stimulus for a\n     * fixed amount of time, even if they respond before the time is complete.  */\n    response_ends_trial: {\n      type: ParameterType.BOOL,\n      default: true,\n    },\n    /**\n     * If `true`, the image will be drawn onto a canvas element. This prevents a blank screen (white flash) between consecutive image trials in some browsers, like Firefox and Edge.\n     * If `false`, the image will be shown via an img element, as in previous versions of jsPsych. If the stimulus is an **animated gif**, you must set this parameter to false, because the canvas rendering method will only present static images.\n     */\n    render_on_canvas: {\n      type: ParameterType.BOOL,\n      default: true,\n    },\n    /**\n     * If true, the response is not registered until the participant releases the key. The response\n     * time (`rt`) still reflects when the key was pressed, and the additional data field\n     * `rt_key_duration` records how long the key was held down. Note that when this is true, the\n     * trial cannot end until the key is released: with `response_ends_trial: true` the trial ends at\n     * the key release, and if the trial ends for another reason (e.g., `trial_duration`) while the\n     * key is still held, no response is recorded for the trial.\n     */\n    wait_for_key_release: {\n      type: ParameterType.BOOL,\n      default: false,\n    },\n  },\n  data: {\n    /** The path of the image that was displayed. */\n    stimulus: {\n      type: ParameterType.STRING,\n    },\n    /**  Indicates which key the participant pressed. */\n    response: {\n      type: ParameterType.STRING,\n    },\n    /** The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus\n     * first appears on the screen until the participant's response. */\n    rt: {\n      type: ParameterType.INT,\n    },\n    /** The duration in milliseconds that the response key was held down, measured from key press to key release. Only recorded when `wait_for_key_release` is true; null otherwise or when no response was made. */\n    rt_key_duration: {\n      type: ParameterType.INT,\n    },\n  },\n  // prettier-ignore\n  citations: '__CITATIONS__',\n};\n\ntype Info = typeof info;\n\n/**\n * This plugin displays an image and records responses generated with the keyboard. The stimulus can be displayed until a\n * response is given, or for a pre-determined amount of time. The trial can be ended automatically if the participant has\n * failed to respond within a fixed length of time.\n *\n * Image files can be automatically preloaded by jsPsych using the [`preload` plugin](preload.md). However, if you are using\n * timeline variables or another dynamic method to specify the image stimulus, you will need to\n * [manually preload](../overview/media-preloading.md#manual-preloading) the images.\n *\n * @author Josh de Leeuw\n * @see {@link https://www.jspsych.org/latest/plugins/image-keyboard-response/ image-keyboard-response plugin documentation on jspsych.org}\n */\nclass ImageKeyboardResponsePlugin implements JsPsychPlugin<Info> {\n  static info = info;\n\n  constructor(private jsPsych: JsPsych) {}\n\n  trial(display_element: HTMLElement, trial: TrialType<Info>) {\n    var height, width;\n    if (trial.render_on_canvas) {\n      var image_drawn = false;\n      // first clear the display element (because the render_on_canvas method appends to display_element instead of overwriting it with .innerHTML)\n      if (display_element.hasChildNodes()) {\n        // can't loop through child list because the list will be modified by .removeChild()\n        while (display_element.firstChild) {\n          display_element.removeChild(display_element.firstChild);\n        }\n      }\n      // create canvas element and image\n      var canvas = document.createElement(\"canvas\");\n      canvas.id = \"jspsych-image-keyboard-response-stimulus\";\n      canvas.style.margin = \"0\";\n      canvas.style.padding = \"0\";\n      var ctx = canvas.getContext(\"2d\");\n      var img = new Image();\n      img.onload = () => {\n        // if image wasn't preloaded, then it will need to be drawn whenever it finishes loading\n        if (!image_drawn) {\n          getHeightWidth(); // only possible to get width/height after image loads\n          ctx.drawImage(img, 0, 0, width, height);\n        }\n      };\n      img.src = trial.stimulus;\n      // get/set image height and width - this can only be done after image loads because uses image's naturalWidth/naturalHeight properties\n      const getHeightWidth = () => {\n        if (trial.stimulus_height !== null) {\n          height = trial.stimulus_height;\n          if (trial.stimulus_width == null && trial.maintain_aspect_ratio) {\n            width = img.naturalWidth * (trial.stimulus_height / img.naturalHeight);\n          }\n        } else {\n          height = img.naturalHeight;\n        }\n        if (trial.stimulus_width !== null) {\n          width = trial.stimulus_width;\n          if (trial.stimulus_height == null && trial.maintain_aspect_ratio) {\n            height = img.naturalHeight * (trial.stimulus_width / img.naturalWidth);\n          }\n        } else if (!(trial.stimulus_height !== null && trial.maintain_aspect_ratio)) {\n          // if stimulus width is null, only use the image's natural width if the width value wasn't set\n          // in the if statement above, based on a specified height and maintain_aspect_ratio = true\n          width = img.naturalWidth;\n        }\n        canvas.height = height;\n        canvas.width = width;\n      };\n      getHeightWidth(); // call now, in case image loads immediately (is cached)\n      // add canvas and draw image\n      display_element.insertBefore(canvas, null);\n      if (img.complete && Number.isFinite(width) && Number.isFinite(height)) {\n        // if image has loaded and width/height have been set, then draw it now\n        // (don't rely on img onload function to draw image when image is in the cache, because that causes a delay in the image presentation)\n        ctx.drawImage(img, 0, 0, width, height);\n        image_drawn = true;\n      }\n      // add prompt if there is one\n      if (trial.prompt !== null) {\n        display_element.insertAdjacentHTML(\"beforeend\", trial.prompt);\n      }\n    } else {\n      // display stimulus as an image element\n      var html = '<img src=\"' + trial.stimulus + '\" id=\"jspsych-image-keyboard-response-stimulus\">';\n      // add prompt\n      if (trial.prompt !== null) {\n        html += trial.prompt;\n      }\n      // update the page content\n      display_element.innerHTML = html;\n\n      // set image dimensions after image has loaded (so that we have access to naturalHeight/naturalWidth)\n      var img = display_element.querySelector(\n        \"#jspsych-image-keyboard-response-stimulus\"\n      ) as HTMLImageElement;\n      if (trial.stimulus_height !== null) {\n        height = trial.stimulus_height;\n        if (trial.stimulus_width == null && trial.maintain_aspect_ratio) {\n          width = img.naturalWidth * (trial.stimulus_height / img.naturalHeight);\n        }\n      } else {\n        height = img.naturalHeight;\n      }\n      if (trial.stimulus_width !== null) {\n        width = trial.stimulus_width;\n        if (trial.stimulus_height == null && trial.maintain_aspect_ratio) {\n          height = img.naturalHeight * (trial.stimulus_width / img.naturalWidth);\n        }\n      } else if (!(trial.stimulus_height !== null && trial.maintain_aspect_ratio)) {\n        // if stimulus width is null, only use the image's natural width if the width value wasn't set\n        // in the if statement above, based on a specified height and maintain_aspect_ratio = true\n        width = img.naturalWidth;\n      }\n      img.style.height = height.toString() + \"px\";\n      img.style.width = width.toString() + \"px\";\n    }\n\n    // store response\n    var response = {\n      rt: null,\n      key: null,\n      rt_key_duration: null,\n    };\n\n    // function to end trial when it is time\n    const end_trial = () => {\n      // kill keyboard listeners\n      if (typeof keyboardListener !== \"undefined\") {\n        this.jsPsych.pluginAPI.cancelKeyboardResponse(keyboardListener);\n      }\n\n      // gather the data to store for the trial\n      var trial_data = {\n        rt: response.rt,\n        stimulus: trial.stimulus,\n        response: response.key,\n        rt_key_duration: response.rt_key_duration,\n      };\n\n      // move on to the next trial\n      this.jsPsych.finishTrial(trial_data);\n    };\n\n    // function to handle responses by the subject\n    var after_response = (info) => {\n      // after a valid response, the stimulus will have the CSS class 'responded'\n      // which can be used to provide visual feedback that a response was recorded\n      display_element.querySelector(\"#jspsych-image-keyboard-response-stimulus\").className +=\n        \" responded\";\n\n      // only record the first response\n      if (response.key == null) {\n        response = {\n          rt: info.rt,\n          key: info.key,\n          rt_key_duration: info.rt_key_duration ?? null,\n        };\n      }\n\n      if (trial.response_ends_trial) {\n        end_trial();\n      }\n    };\n\n    // start the response listener\n    if (trial.choices != \"NO_KEYS\") {\n      var keyboardListener = this.jsPsych.pluginAPI.getKeyboardResponse({\n        callback_function: after_response,\n        valid_responses: trial.choices,\n        rt_method: \"performance\",\n        persist: false,\n        allow_held_key: false,\n        wait_for_key_release: trial.wait_for_key_release,\n      });\n    }\n\n    // hide stimulus if stimulus_duration is set\n    if (trial.stimulus_duration !== null) {\n      this.jsPsych.pluginAPI.setTimeout(() => {\n        display_element.querySelector<HTMLElement>(\n          \"#jspsych-image-keyboard-response-stimulus\"\n        ).style.visibility = \"hidden\";\n      }, trial.stimulus_duration);\n    }\n\n    // end trial if trial_duration is set\n    if (trial.trial_duration !== null) {\n      this.jsPsych.pluginAPI.setTimeout(() => {\n        end_trial();\n      }, trial.trial_duration);\n    } else if (trial.response_ends_trial === false) {\n      console.warn(\n        \"The experiment may be deadlocked. Try setting a trial duration or set response_ends_trial to true.\"\n      );\n    }\n  }\n\n  simulate(\n    trial: TrialType<Info>,\n    simulation_mode,\n    simulation_options: any,\n    load_callback: () => void\n  ) {\n    if (simulation_mode == \"data-only\") {\n      load_callback();\n      this.simulate_data_only(trial, simulation_options);\n    }\n    if (simulation_mode == \"visual\") {\n      this.simulate_visual(trial, simulation_options, load_callback);\n    }\n  }\n\n  private simulate_data_only(trial: TrialType<Info>, simulation_options) {\n    const data = this.create_simulation_data(trial, simulation_options);\n\n    this.jsPsych.finishTrial(data);\n  }\n\n  private simulate_visual(trial: TrialType<Info>, simulation_options, load_callback: () => void) {\n    const data = this.create_simulation_data(trial, simulation_options);\n\n    const display_element = this.jsPsych.getDisplayElement();\n\n    this.trial(display_element, trial);\n    load_callback();\n\n    if (data.rt !== null) {\n      this.jsPsych.pluginAPI.pressKey(data.response, data.rt);\n    }\n  }\n\n  private create_simulation_data(trial: TrialType<Info>, simulation_options) {\n    const default_data = {\n      stimulus: trial.stimulus,\n      rt: this.jsPsych.randomization.sampleExGaussian(500, 50, 1 / 150, true),\n      response: this.jsPsych.pluginAPI.getValidKey(trial.choices),\n      rt_key_duration: null,\n    };\n    default_data.rt_key_duration =\n      default_data.rt === null || !trial.wait_for_key_release\n        ? null\n        : this.jsPsych.randomization.sampleExGaussian(150, 30, 1 / 100, true);\n\n    const data = this.jsPsych.pluginAPI.mergeSimulationData(default_data, simulation_options);\n\n    this.jsPsych.pluginAPI.ensureSimulationDataConsistency(trial, data);\n\n    return data;\n  }\n}\n\nexport default ImageKeyboardResponsePlugin;\n"],"names":["version","_a"],"mappings":"2DACE,IACAA,EAAW,o1BCyGA,UAAA,iuBAAe,61DA3G5B,IAAAC"}

package/dist/index.cjs

@@ -2,7 +2,7 @@
 
 var jspsych = require('jspsych');
 
-var version = "2.1.0";
+var version = "2.2.0";
 
 const info = {
   name: "image-keyboard-response",
@@ -73,6 +73,18 @@ const info = {
     render_on_canvas: {
       type: jspsych.ParameterType.BOOL,
       default: true
+    },
+    /**
+     * If true, the response is not registered until the participant releases the key. The response
+     * time (`rt`) still reflects when the key was pressed, and the additional data field
+     * `rt_key_duration` records how long the key was held down. Note that when this is true, the
+     * trial cannot end until the key is released: with `response_ends_trial: true` the trial ends at
+     * the key release, and if the trial ends for another reason (e.g., `trial_duration`) while the
+     * key is still held, no response is recorded for the trial.
+     */
+    wait_for_key_release: {
+      type: jspsych.ParameterType.BOOL,
+      default: false
     }
   },
   data: {
@@ -88,6 +100,10 @@ const info = {
      * first appears on the screen until the participant's response. */
     rt: {
       type: jspsych.ParameterType.INT
+    },
+    /** The duration in milliseconds that the response key was held down, measured from key press to key release. Only recorded when `wait_for_key_release` is true; null otherwise or when no response was made. */
+    rt_key_duration: {
+      type: jspsych.ParameterType.INT
     }
   },
   // prettier-ignore
@@ -184,7 +200,8 @@ class ImageKeyboardResponsePlugin {
     }
     var response = {
       rt: null,
-      key: null
+      key: null,
+      rt_key_duration: null
     };
     const end_trial = () => {
       if (typeof keyboardListener !== "undefined") {
@@ -193,14 +210,19 @@ class ImageKeyboardResponsePlugin {
       var trial_data = {
         rt: response.rt,
         stimulus: trial.stimulus,
-        response: response.key
+        response: response.key,
+        rt_key_duration: response.rt_key_duration
       };
       this.jsPsych.finishTrial(trial_data);
     };
     var after_response = (info2) => {
       display_element.querySelector("#jspsych-image-keyboard-response-stimulus").className += " responded";
       if (response.key == null) {
-        response = info2;
+        response = {
+          rt: info2.rt,
+          key: info2.key,
+          rt_key_duration: info2.rt_key_duration ?? null
+        };
       }
       if (trial.response_ends_trial) {
         end_trial();
@@ -212,7 +234,8 @@ class ImageKeyboardResponsePlugin {
         valid_responses: trial.choices,
         rt_method: "performance",
         persist: false,
-        allow_held_key: false
+        allow_held_key: false,
+        wait_for_key_release: trial.wait_for_key_release
       });
     }
     if (trial.stimulus_duration !== null) {
@@ -258,8 +281,10 @@ class ImageKeyboardResponsePlugin {
     const default_data = {
       stimulus: trial.stimulus,
       rt: this.jsPsych.randomization.sampleExGaussian(500, 50, 1 / 150, true),
-      response: this.jsPsych.pluginAPI.getValidKey(trial.choices)
+      response: this.jsPsych.pluginAPI.getValidKey(trial.choices),
+      rt_key_duration: null
     };
+    default_data.rt_key_duration = default_data.rt === null || !trial.wait_for_key_release ? null : this.jsPsych.randomization.sampleExGaussian(150, 30, 1 / 100, true);
     const data = this.jsPsych.pluginAPI.mergeSimulationData(default_data, simulation_options);
     this.jsPsych.pluginAPI.ensureSimulationDataConsistency(trial, data);
     return data;

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","sources":["../package.json","../src/index.ts"],"sourcesContent":["{\n  \"name\": \"@jspsych/plugin-image-keyboard-response\",\n  \"version\": \"2.1.0\",\n  \"description\": \"jsPsych plugin for displaying a stimulus and getting a keyboard response\",\n  \"type\": \"module\",\n  \"main\": \"dist/index.cjs\",\n  \"exports\": {\n    \"import\": \"./dist/index.js\",\n    \"require\": \"./dist/index.cjs\"\n  },\n  \"typings\": \"dist/index.d.ts\",\n  \"unpkg\": \"dist/index.browser.min.js\",\n  \"files\": [\n    \"src\",\n    \"dist\"\n  ],\n  \"source\": \"src/index.ts\",\n  \"scripts\": {\n    \"test\": \"jest\",\n    \"test:watch\": \"npm test -- --watch\",\n    \"tsc\": \"tsc\",\n    \"build\": \"rollup --config\",\n    \"build:watch\": \"npm run build -- --watch\"\n  },\n  \"repository\": {\n    \"type\": \"git\",\n    \"url\": \"git+https://github.com/jspsych/jsPsych.git\",\n    \"directory\": \"packages/plugin-image-keyboard-response\"\n  },\n  \"author\": \"Josh de Leeuw\",\n  \"license\": \"MIT\",\n  \"bugs\": {\n    \"url\": \"https://github.com/jspsych/jsPsych/issues\"\n  },\n  \"homepage\": \"https://www.jspsych.org/latest/plugins/image-keyboard-response\",\n  \"peerDependencies\": {\n    \"jspsych\": \">=7.1.0\"\n  },\n  \"devDependencies\": {\n    \"@jspsych/config\": \"^3.2.0\",\n    \"@jspsych/test-utils\": \"^1.2.0\"\n  }\n}\n","import { JsPsych, JsPsychPlugin, ParameterType, TrialType } from \"jspsych\";\n\nimport { version } from \"../package.json\";\n\nconst info = <const>{\n  name: \"image-keyboard-response\",\n  version: version,\n  parameters: {\n    /** The path of the image file to be displayed. */\n    stimulus: {\n      type: ParameterType.IMAGE,\n      default: undefined,\n    },\n    /** Set the height of the image in pixels. If left null (no value specified), then the image will display at its natural height. */\n    stimulus_height: {\n      type: ParameterType.INT,\n      default: null,\n    },\n    /** Set the width of the image in pixels. If left null (no value specified), then the image will display at its natural width. */\n    stimulus_width: {\n      type: ParameterType.INT,\n      default: null,\n    },\n    /** If setting *only* the width or *only* the height and this parameter is true, then the other dimension will be scaled\n     * to maintain the image's aspect ratio. */\n    maintain_aspect_ratio: {\n      type: ParameterType.BOOL,\n      default: true,\n    },\n    /**his array contains the key(s) that the participant is allowed to press in order to respond to the stimulus. Keys should\n     * be specified as characters (e.g., `'a'`, `'q'`, `' '`, `'Enter'`, `'ArrowDown'`) - see\n     * [this page](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values) and\n     * [this page (event.key column)](https://www.freecodecamp.org/news/javascript-keycode-list-keypress-event-key-codes/)\n     * for more examples. Any key presses that are not listed in the array will be ignored. The default value of `\"ALL_KEYS\"`\n     * means that all keys will be accepted as valid responses. Specifying `\"NO_KEYS\"` will mean that no responses are allowed. */\n    choices: {\n      type: ParameterType.KEYS,\n      default: \"ALL_KEYS\",\n    },\n    /**This string can contain HTML markup. Any content here will be displayed below the stimulus. The intention is that it can\n     * be used to provide a reminder about the action the participant is supposed to take (e.g., which key to press). */\n    prompt: {\n      type: ParameterType.HTML_STRING,\n      default: null,\n    },\n    /** How long to show the stimulus for in milliseconds. If the value is `null`, then the stimulus will be shown until the\n     * participant makes a response. */\n    stimulus_duration: {\n      type: ParameterType.INT,\n      default: null,\n    },\n    /** How long to wait for the participant to make a response before ending the trial in milliseconds. If the participant\n     * fails to make a response before this timer is reached, the participant's response will be recorded as null for the\n     * trial and the trial will end. If the value of this parameter is `null`, then the trial will wait for a response indefinitely. */\n    trial_duration: {\n      type: ParameterType.INT,\n      default: null,\n    },\n    /** If true, then the trial will end whenever the participant makes a response (assuming they make their response before\n     * the cutoff specified by the `trial_duration` parameter). If false, then the trial will continue until the value for\n     * `trial_duration` is reached. You can set this parameter to `false` to force the participant to view a stimulus for a\n     * fixed amount of time, even if they respond before the time is complete.  */\n    response_ends_trial: {\n      type: ParameterType.BOOL,\n      default: true,\n    },\n    /**\n     * If `true`, the image will be drawn onto a canvas element. This prevents a blank screen (white flash) between consecutive image trials in some browsers, like Firefox and Edge.\n     * If `false`, the image will be shown via an img element, as in previous versions of jsPsych. If the stimulus is an **animated gif**, you must set this parameter to false, because the canvas rendering method will only present static images.\n     */\n    render_on_canvas: {\n      type: ParameterType.BOOL,\n      default: true,\n    },\n  },\n  data: {\n    /** The path of the image that was displayed. */\n    stimulus: {\n      type: ParameterType.STRING,\n    },\n    /**  Indicates which key the participant pressed. */\n    response: {\n      type: ParameterType.STRING,\n    },\n    /** The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus\n     * first appears on the screen until the participant's response. */\n    rt: {\n      type: ParameterType.INT,\n    },\n  },\n  // prettier-ignore\n  citations: '__CITATIONS__',\n};\n\ntype Info = typeof info;\n\n/**\n * This plugin displays an image and records responses generated with the keyboard. The stimulus can be displayed until a\n * response is given, or for a pre-determined amount of time. The trial can be ended automatically if the participant has\n * failed to respond within a fixed length of time.\n *\n * Image files can be automatically preloaded by jsPsych using the [`preload` plugin](preload.md). However, if you are using\n * timeline variables or another dynamic method to specify the image stimulus, you will need to\n * [manually preload](../overview/media-preloading.md#manual-preloading) the images.\n *\n * @author Josh de Leeuw\n * @see {@link https://www.jspsych.org/latest/plugins/image-keyboard-response/ image-keyboard-response plugin documentation on jspsych.org}\n */\nclass ImageKeyboardResponsePlugin implements JsPsychPlugin<Info> {\n  static info = info;\n\n  constructor(private jsPsych: JsPsych) {}\n\n  trial(display_element: HTMLElement, trial: TrialType<Info>) {\n    var height, width;\n    if (trial.render_on_canvas) {\n      var image_drawn = false;\n      // first clear the display element (because the render_on_canvas method appends to display_element instead of overwriting it with .innerHTML)\n      if (display_element.hasChildNodes()) {\n        // can't loop through child list because the list will be modified by .removeChild()\n        while (display_element.firstChild) {\n          display_element.removeChild(display_element.firstChild);\n        }\n      }\n      // create canvas element and image\n      var canvas = document.createElement(\"canvas\");\n      canvas.id = \"jspsych-image-keyboard-response-stimulus\";\n      canvas.style.margin = \"0\";\n      canvas.style.padding = \"0\";\n      var ctx = canvas.getContext(\"2d\");\n      var img = new Image();\n      img.onload = () => {\n        // if image wasn't preloaded, then it will need to be drawn whenever it finishes loading\n        if (!image_drawn) {\n          getHeightWidth(); // only possible to get width/height after image loads\n          ctx.drawImage(img, 0, 0, width, height);\n        }\n      };\n      img.src = trial.stimulus;\n      // get/set image height and width - this can only be done after image loads because uses image's naturalWidth/naturalHeight properties\n      const getHeightWidth = () => {\n        if (trial.stimulus_height !== null) {\n          height = trial.stimulus_height;\n          if (trial.stimulus_width == null && trial.maintain_aspect_ratio) {\n            width = img.naturalWidth * (trial.stimulus_height / img.naturalHeight);\n          }\n        } else {\n          height = img.naturalHeight;\n        }\n        if (trial.stimulus_width !== null) {\n          width = trial.stimulus_width;\n          if (trial.stimulus_height == null && trial.maintain_aspect_ratio) {\n            height = img.naturalHeight * (trial.stimulus_width / img.naturalWidth);\n          }\n        } else if (!(trial.stimulus_height !== null && trial.maintain_aspect_ratio)) {\n          // if stimulus width is null, only use the image's natural width if the width value wasn't set\n          // in the if statement above, based on a specified height and maintain_aspect_ratio = true\n          width = img.naturalWidth;\n        }\n        canvas.height = height;\n        canvas.width = width;\n      };\n      getHeightWidth(); // call now, in case image loads immediately (is cached)\n      // add canvas and draw image\n      display_element.insertBefore(canvas, null);\n      if (img.complete && Number.isFinite(width) && Number.isFinite(height)) {\n        // if image has loaded and width/height have been set, then draw it now\n        // (don't rely on img onload function to draw image when image is in the cache, because that causes a delay in the image presentation)\n        ctx.drawImage(img, 0, 0, width, height);\n        image_drawn = true;\n      }\n      // add prompt if there is one\n      if (trial.prompt !== null) {\n        display_element.insertAdjacentHTML(\"beforeend\", trial.prompt);\n      }\n    } else {\n      // display stimulus as an image element\n      var html = '<img src=\"' + trial.stimulus + '\" id=\"jspsych-image-keyboard-response-stimulus\">';\n      // add prompt\n      if (trial.prompt !== null) {\n        html += trial.prompt;\n      }\n      // update the page content\n      display_element.innerHTML = html;\n\n      // set image dimensions after image has loaded (so that we have access to naturalHeight/naturalWidth)\n      var img = display_element.querySelector(\n        \"#jspsych-image-keyboard-response-stimulus\"\n      ) as HTMLImageElement;\n      if (trial.stimulus_height !== null) {\n        height = trial.stimulus_height;\n        if (trial.stimulus_width == null && trial.maintain_aspect_ratio) {\n          width = img.naturalWidth * (trial.stimulus_height / img.naturalHeight);\n        }\n      } else {\n        height = img.naturalHeight;\n      }\n      if (trial.stimulus_width !== null) {\n        width = trial.stimulus_width;\n        if (trial.stimulus_height == null && trial.maintain_aspect_ratio) {\n          height = img.naturalHeight * (trial.stimulus_width / img.naturalWidth);\n        }\n      } else if (!(trial.stimulus_height !== null && trial.maintain_aspect_ratio)) {\n        // if stimulus width is null, only use the image's natural width if the width value wasn't set\n        // in the if statement above, based on a specified height and maintain_aspect_ratio = true\n        width = img.naturalWidth;\n      }\n      img.style.height = height.toString() + \"px\";\n      img.style.width = width.toString() + \"px\";\n    }\n\n    // store response\n    var response = {\n      rt: null,\n      key: null,\n    };\n\n    // function to end trial when it is time\n    const end_trial = () => {\n      // kill keyboard listeners\n      if (typeof keyboardListener !== \"undefined\") {\n        this.jsPsych.pluginAPI.cancelKeyboardResponse(keyboardListener);\n      }\n\n      // gather the data to store for the trial\n      var trial_data = {\n        rt: response.rt,\n        stimulus: trial.stimulus,\n        response: response.key,\n      };\n\n      // move on to the next trial\n      this.jsPsych.finishTrial(trial_data);\n    };\n\n    // function to handle responses by the subject\n    var after_response = (info) => {\n      // after a valid response, the stimulus will have the CSS class 'responded'\n      // which can be used to provide visual feedback that a response was recorded\n      display_element.querySelector(\"#jspsych-image-keyboard-response-stimulus\").className +=\n        \" responded\";\n\n      // only record the first response\n      if (response.key == null) {\n        response = info;\n      }\n\n      if (trial.response_ends_trial) {\n        end_trial();\n      }\n    };\n\n    // start the response listener\n    if (trial.choices != \"NO_KEYS\") {\n      var keyboardListener = this.jsPsych.pluginAPI.getKeyboardResponse({\n        callback_function: after_response,\n        valid_responses: trial.choices,\n        rt_method: \"performance\",\n        persist: false,\n        allow_held_key: false,\n      });\n    }\n\n    // hide stimulus if stimulus_duration is set\n    if (trial.stimulus_duration !== null) {\n      this.jsPsych.pluginAPI.setTimeout(() => {\n        display_element.querySelector<HTMLElement>(\n          \"#jspsych-image-keyboard-response-stimulus\"\n        ).style.visibility = \"hidden\";\n      }, trial.stimulus_duration);\n    }\n\n    // end trial if trial_duration is set\n    if (trial.trial_duration !== null) {\n      this.jsPsych.pluginAPI.setTimeout(() => {\n        end_trial();\n      }, trial.trial_duration);\n    } else if (trial.response_ends_trial === false) {\n      console.warn(\n        \"The experiment may be deadlocked. Try setting a trial duration or set response_ends_trial to true.\"\n      );\n    }\n  }\n\n  simulate(\n    trial: TrialType<Info>,\n    simulation_mode,\n    simulation_options: any,\n    load_callback: () => void\n  ) {\n    if (simulation_mode == \"data-only\") {\n      load_callback();\n      this.simulate_data_only(trial, simulation_options);\n    }\n    if (simulation_mode == \"visual\") {\n      this.simulate_visual(trial, simulation_options, load_callback);\n    }\n  }\n\n  private simulate_data_only(trial: TrialType<Info>, simulation_options) {\n    const data = this.create_simulation_data(trial, simulation_options);\n\n    this.jsPsych.finishTrial(data);\n  }\n\n  private simulate_visual(trial: TrialType<Info>, simulation_options, load_callback: () => void) {\n    const data = this.create_simulation_data(trial, simulation_options);\n\n    const display_element = this.jsPsych.getDisplayElement();\n\n    this.trial(display_element, trial);\n    load_callback();\n\n    if (data.rt !== null) {\n      this.jsPsych.pluginAPI.pressKey(data.response, data.rt);\n    }\n  }\n\n  private create_simulation_data(trial: TrialType<Info>, simulation_options) {\n    const default_data = {\n      stimulus: trial.stimulus,\n      rt: this.jsPsych.randomization.sampleExGaussian(500, 50, 1 / 150, true),\n      response: this.jsPsych.pluginAPI.getValidKey(trial.choices),\n    };\n\n    const data = this.jsPsych.pluginAPI.mergeSimulationData(default_data, simulation_options);\n\n    this.jsPsych.pluginAPI.ensureSimulationDataConsistency(trial, data);\n\n    return data;\n  }\n}\n\nexport default ImageKeyboardResponsePlugin;\n"],"names":[],"mappings":";;;;AAEE,IAAW,OAAA,GAAA,OAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ECyFA,SAAA,EAAA;AAAA;;GAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"index.cjs","sources":["../package.json","../src/index.ts"],"sourcesContent":["{\n  \"name\": \"@jspsych/plugin-image-keyboard-response\",\n  \"version\": \"2.2.0\",\n  \"description\": \"jsPsych plugin for displaying a stimulus and getting a keyboard response\",\n  \"type\": \"module\",\n  \"main\": \"dist/index.cjs\",\n  \"exports\": {\n    \"import\": \"./dist/index.js\",\n    \"require\": \"./dist/index.cjs\"\n  },\n  \"typings\": \"dist/index.d.ts\",\n  \"unpkg\": \"dist/index.browser.min.js\",\n  \"files\": [\n    \"src\",\n    \"dist\"\n  ],\n  \"source\": \"src/index.ts\",\n  \"scripts\": {\n    \"test\": \"jest\",\n    \"test:watch\": \"npm test -- --watch\",\n    \"tsc\": \"tsc\",\n    \"build\": \"rollup --config\",\n    \"build:watch\": \"npm run build -- --watch\"\n  },\n  \"repository\": {\n    \"type\": \"git\",\n    \"url\": \"git+https://github.com/jspsych/jsPsych.git\",\n    \"directory\": \"packages/plugin-image-keyboard-response\"\n  },\n  \"author\": \"Josh de Leeuw\",\n  \"license\": \"MIT\",\n  \"bugs\": {\n    \"url\": \"https://github.com/jspsych/jsPsych/issues\"\n  },\n  \"homepage\": \"https://www.jspsych.org/latest/plugins/image-keyboard-response\",\n  \"peerDependencies\": {\n    \"jspsych\": \">=7.1.0\"\n  },\n  \"devDependencies\": {\n    \"@jspsych/config\": \"^3.3.4\",\n    \"@jspsych/test-utils\": \"^1.3.0\"\n  }\n}\n","import { JsPsych, JsPsychPlugin, ParameterType, TrialType } from \"jspsych\";\n\nimport { version } from \"../package.json\";\n\nconst info = <const>{\n  name: \"image-keyboard-response\",\n  version: version,\n  parameters: {\n    /** The path of the image file to be displayed. */\n    stimulus: {\n      type: ParameterType.IMAGE,\n      default: undefined,\n    },\n    /** Set the height of the image in pixels. If left null (no value specified), then the image will display at its natural height. */\n    stimulus_height: {\n      type: ParameterType.INT,\n      default: null,\n    },\n    /** Set the width of the image in pixels. If left null (no value specified), then the image will display at its natural width. */\n    stimulus_width: {\n      type: ParameterType.INT,\n      default: null,\n    },\n    /** If setting *only* the width or *only* the height and this parameter is true, then the other dimension will be scaled\n     * to maintain the image's aspect ratio. */\n    maintain_aspect_ratio: {\n      type: ParameterType.BOOL,\n      default: true,\n    },\n    /**his array contains the key(s) that the participant is allowed to press in order to respond to the stimulus. Keys should\n     * be specified as characters (e.g., `'a'`, `'q'`, `' '`, `'Enter'`, `'ArrowDown'`) - see\n     * [this page](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values) and\n     * [this page (event.key column)](https://www.freecodecamp.org/news/javascript-keycode-list-keypress-event-key-codes/)\n     * for more examples. Any key presses that are not listed in the array will be ignored. The default value of `\"ALL_KEYS\"`\n     * means that all keys will be accepted as valid responses. Specifying `\"NO_KEYS\"` will mean that no responses are allowed. */\n    choices: {\n      type: ParameterType.KEYS,\n      default: \"ALL_KEYS\",\n    },\n    /**This string can contain HTML markup. Any content here will be displayed below the stimulus. The intention is that it can\n     * be used to provide a reminder about the action the participant is supposed to take (e.g., which key to press). */\n    prompt: {\n      type: ParameterType.HTML_STRING,\n      default: null,\n    },\n    /** How long to show the stimulus for in milliseconds. If the value is `null`, then the stimulus will be shown until the\n     * participant makes a response. */\n    stimulus_duration: {\n      type: ParameterType.INT,\n      default: null,\n    },\n    /** How long to wait for the participant to make a response before ending the trial in milliseconds. If the participant\n     * fails to make a response before this timer is reached, the participant's response will be recorded as null for the\n     * trial and the trial will end. If the value of this parameter is `null`, then the trial will wait for a response indefinitely. */\n    trial_duration: {\n      type: ParameterType.INT,\n      default: null,\n    },\n    /** If true, then the trial will end whenever the participant makes a response (assuming they make their response before\n     * the cutoff specified by the `trial_duration` parameter). If false, then the trial will continue until the value for\n     * `trial_duration` is reached. You can set this parameter to `false` to force the participant to view a stimulus for a\n     * fixed amount of time, even if they respond before the time is complete.  */\n    response_ends_trial: {\n      type: ParameterType.BOOL,\n      default: true,\n    },\n    /**\n     * If `true`, the image will be drawn onto a canvas element. This prevents a blank screen (white flash) between consecutive image trials in some browsers, like Firefox and Edge.\n     * If `false`, the image will be shown via an img element, as in previous versions of jsPsych. If the stimulus is an **animated gif**, you must set this parameter to false, because the canvas rendering method will only present static images.\n     */\n    render_on_canvas: {\n      type: ParameterType.BOOL,\n      default: true,\n    },\n    /**\n     * If true, the response is not registered until the participant releases the key. The response\n     * time (`rt`) still reflects when the key was pressed, and the additional data field\n     * `rt_key_duration` records how long the key was held down. Note that when this is true, the\n     * trial cannot end until the key is released: with `response_ends_trial: true` the trial ends at\n     * the key release, and if the trial ends for another reason (e.g., `trial_duration`) while the\n     * key is still held, no response is recorded for the trial.\n     */\n    wait_for_key_release: {\n      type: ParameterType.BOOL,\n      default: false,\n    },\n  },\n  data: {\n    /** The path of the image that was displayed. */\n    stimulus: {\n      type: ParameterType.STRING,\n    },\n    /**  Indicates which key the participant pressed. */\n    response: {\n      type: ParameterType.STRING,\n    },\n    /** The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus\n     * first appears on the screen until the participant's response. */\n    rt: {\n      type: ParameterType.INT,\n    },\n    /** The duration in milliseconds that the response key was held down, measured from key press to key release. Only recorded when `wait_for_key_release` is true; null otherwise or when no response was made. */\n    rt_key_duration: {\n      type: ParameterType.INT,\n    },\n  },\n  // prettier-ignore\n  citations: '__CITATIONS__',\n};\n\ntype Info = typeof info;\n\n/**\n * This plugin displays an image and records responses generated with the keyboard. The stimulus can be displayed until a\n * response is given, or for a pre-determined amount of time. The trial can be ended automatically if the participant has\n * failed to respond within a fixed length of time.\n *\n * Image files can be automatically preloaded by jsPsych using the [`preload` plugin](preload.md). However, if you are using\n * timeline variables or another dynamic method to specify the image stimulus, you will need to\n * [manually preload](../overview/media-preloading.md#manual-preloading) the images.\n *\n * @author Josh de Leeuw\n * @see {@link https://www.jspsych.org/latest/plugins/image-keyboard-response/ image-keyboard-response plugin documentation on jspsych.org}\n */\nclass ImageKeyboardResponsePlugin implements JsPsychPlugin<Info> {\n  static info = info;\n\n  constructor(private jsPsych: JsPsych) {}\n\n  trial(display_element: HTMLElement, trial: TrialType<Info>) {\n    var height, width;\n    if (trial.render_on_canvas) {\n      var image_drawn = false;\n      // first clear the display element (because the render_on_canvas method appends to display_element instead of overwriting it with .innerHTML)\n      if (display_element.hasChildNodes()) {\n        // can't loop through child list because the list will be modified by .removeChild()\n        while (display_element.firstChild) {\n          display_element.removeChild(display_element.firstChild);\n        }\n      }\n      // create canvas element and image\n      var canvas = document.createElement(\"canvas\");\n      canvas.id = \"jspsych-image-keyboard-response-stimulus\";\n      canvas.style.margin = \"0\";\n      canvas.style.padding = \"0\";\n      var ctx = canvas.getContext(\"2d\");\n      var img = new Image();\n      img.onload = () => {\n        // if image wasn't preloaded, then it will need to be drawn whenever it finishes loading\n        if (!image_drawn) {\n          getHeightWidth(); // only possible to get width/height after image loads\n          ctx.drawImage(img, 0, 0, width, height);\n        }\n      };\n      img.src = trial.stimulus;\n      // get/set image height and width - this can only be done after image loads because uses image's naturalWidth/naturalHeight properties\n      const getHeightWidth = () => {\n        if (trial.stimulus_height !== null) {\n          height = trial.stimulus_height;\n          if (trial.stimulus_width == null && trial.maintain_aspect_ratio) {\n            width = img.naturalWidth * (trial.stimulus_height / img.naturalHeight);\n          }\n        } else {\n          height = img.naturalHeight;\n        }\n        if (trial.stimulus_width !== null) {\n          width = trial.stimulus_width;\n          if (trial.stimulus_height == null && trial.maintain_aspect_ratio) {\n            height = img.naturalHeight * (trial.stimulus_width / img.naturalWidth);\n          }\n        } else if (!(trial.stimulus_height !== null && trial.maintain_aspect_ratio)) {\n          // if stimulus width is null, only use the image's natural width if the width value wasn't set\n          // in the if statement above, based on a specified height and maintain_aspect_ratio = true\n          width = img.naturalWidth;\n        }\n        canvas.height = height;\n        canvas.width = width;\n      };\n      getHeightWidth(); // call now, in case image loads immediately (is cached)\n      // add canvas and draw image\n      display_element.insertBefore(canvas, null);\n      if (img.complete && Number.isFinite(width) && Number.isFinite(height)) {\n        // if image has loaded and width/height have been set, then draw it now\n        // (don't rely on img onload function to draw image when image is in the cache, because that causes a delay in the image presentation)\n        ctx.drawImage(img, 0, 0, width, height);\n        image_drawn = true;\n      }\n      // add prompt if there is one\n      if (trial.prompt !== null) {\n        display_element.insertAdjacentHTML(\"beforeend\", trial.prompt);\n      }\n    } else {\n      // display stimulus as an image element\n      var html = '<img src=\"' + trial.stimulus + '\" id=\"jspsych-image-keyboard-response-stimulus\">';\n      // add prompt\n      if (trial.prompt !== null) {\n        html += trial.prompt;\n      }\n      // update the page content\n      display_element.innerHTML = html;\n\n      // set image dimensions after image has loaded (so that we have access to naturalHeight/naturalWidth)\n      var img = display_element.querySelector(\n        \"#jspsych-image-keyboard-response-stimulus\"\n      ) as HTMLImageElement;\n      if (trial.stimulus_height !== null) {\n        height = trial.stimulus_height;\n        if (trial.stimulus_width == null && trial.maintain_aspect_ratio) {\n          width = img.naturalWidth * (trial.stimulus_height / img.naturalHeight);\n        }\n      } else {\n        height = img.naturalHeight;\n      }\n      if (trial.stimulus_width !== null) {\n        width = trial.stimulus_width;\n        if (trial.stimulus_height == null && trial.maintain_aspect_ratio) {\n          height = img.naturalHeight * (trial.stimulus_width / img.naturalWidth);\n        }\n      } else if (!(trial.stimulus_height !== null && trial.maintain_aspect_ratio)) {\n        // if stimulus width is null, only use the image's natural width if the width value wasn't set\n        // in the if statement above, based on a specified height and maintain_aspect_ratio = true\n        width = img.naturalWidth;\n      }\n      img.style.height = height.toString() + \"px\";\n      img.style.width = width.toString() + \"px\";\n    }\n\n    // store response\n    var response = {\n      rt: null,\n      key: null,\n      rt_key_duration: null,\n    };\n\n    // function to end trial when it is time\n    const end_trial = () => {\n      // kill keyboard listeners\n      if (typeof keyboardListener !== \"undefined\") {\n        this.jsPsych.pluginAPI.cancelKeyboardResponse(keyboardListener);\n      }\n\n      // gather the data to store for the trial\n      var trial_data = {\n        rt: response.rt,\n        stimulus: trial.stimulus,\n        response: response.key,\n        rt_key_duration: response.rt_key_duration,\n      };\n\n      // move on to the next trial\n      this.jsPsych.finishTrial(trial_data);\n    };\n\n    // function to handle responses by the subject\n    var after_response = (info) => {\n      // after a valid response, the stimulus will have the CSS class 'responded'\n      // which can be used to provide visual feedback that a response was recorded\n      display_element.querySelector(\"#jspsych-image-keyboard-response-stimulus\").className +=\n        \" responded\";\n\n      // only record the first response\n      if (response.key == null) {\n        response = {\n          rt: info.rt,\n          key: info.key,\n          rt_key_duration: info.rt_key_duration ?? null,\n        };\n      }\n\n      if (trial.response_ends_trial) {\n        end_trial();\n      }\n    };\n\n    // start the response listener\n    if (trial.choices != \"NO_KEYS\") {\n      var keyboardListener = this.jsPsych.pluginAPI.getKeyboardResponse({\n        callback_function: after_response,\n        valid_responses: trial.choices,\n        rt_method: \"performance\",\n        persist: false,\n        allow_held_key: false,\n        wait_for_key_release: trial.wait_for_key_release,\n      });\n    }\n\n    // hide stimulus if stimulus_duration is set\n    if (trial.stimulus_duration !== null) {\n      this.jsPsych.pluginAPI.setTimeout(() => {\n        display_element.querySelector<HTMLElement>(\n          \"#jspsych-image-keyboard-response-stimulus\"\n        ).style.visibility = \"hidden\";\n      }, trial.stimulus_duration);\n    }\n\n    // end trial if trial_duration is set\n    if (trial.trial_duration !== null) {\n      this.jsPsych.pluginAPI.setTimeout(() => {\n        end_trial();\n      }, trial.trial_duration);\n    } else if (trial.response_ends_trial === false) {\n      console.warn(\n        \"The experiment may be deadlocked. Try setting a trial duration or set response_ends_trial to true.\"\n      );\n    }\n  }\n\n  simulate(\n    trial: TrialType<Info>,\n    simulation_mode,\n    simulation_options: any,\n    load_callback: () => void\n  ) {\n    if (simulation_mode == \"data-only\") {\n      load_callback();\n      this.simulate_data_only(trial, simulation_options);\n    }\n    if (simulation_mode == \"visual\") {\n      this.simulate_visual(trial, simulation_options, load_callback);\n    }\n  }\n\n  private simulate_data_only(trial: TrialType<Info>, simulation_options) {\n    const data = this.create_simulation_data(trial, simulation_options);\n\n    this.jsPsych.finishTrial(data);\n  }\n\n  private simulate_visual(trial: TrialType<Info>, simulation_options, load_callback: () => void) {\n    const data = this.create_simulation_data(trial, simulation_options);\n\n    const display_element = this.jsPsych.getDisplayElement();\n\n    this.trial(display_element, trial);\n    load_callback();\n\n    if (data.rt !== null) {\n      this.jsPsych.pluginAPI.pressKey(data.response, data.rt);\n    }\n  }\n\n  private create_simulation_data(trial: TrialType<Info>, simulation_options) {\n    const default_data = {\n      stimulus: trial.stimulus,\n      rt: this.jsPsych.randomization.sampleExGaussian(500, 50, 1 / 150, true),\n      response: this.jsPsych.pluginAPI.getValidKey(trial.choices),\n      rt_key_duration: null,\n    };\n    default_data.rt_key_duration =\n      default_data.rt === null || !trial.wait_for_key_release\n        ? null\n        : this.jsPsych.randomization.sampleExGaussian(150, 30, 1 / 100, true);\n\n    const data = this.jsPsych.pluginAPI.mergeSimulationData(default_data, simulation_options);\n\n    this.jsPsych.pluginAPI.ensureSimulationDataConsistency(trial, data);\n\n    return data;\n  }\n}\n\nexport default ImageKeyboardResponsePlugin;\n"],"names":[],"mappings":";;;;AAEE,IAAA,OAAA,GAAW,OAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ECyGA,SAAA,EAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/index.d.ts

@@ -70,6 +70,18 @@ declare const info: {
             readonly type: ParameterType.BOOL;
             readonly default: true;
         };
+        /**
+         * If true, the response is not registered until the participant releases the key. The response
+         * time (`rt`) still reflects when the key was pressed, and the additional data field
+         * `rt_key_duration` records how long the key was held down. Note that when this is true, the
+         * trial cannot end until the key is released: with `response_ends_trial: true` the trial ends at
+         * the key release, and if the trial ends for another reason (e.g., `trial_duration`) while the
+         * key is still held, no response is recorded for the trial.
+         */
+        readonly wait_for_key_release: {
+            readonly type: ParameterType.BOOL;
+            readonly default: false;
+        };
     };
     readonly data: {
         /** The path of the image that was displayed. */
@@ -85,6 +97,10 @@ declare const info: {
         readonly rt: {
             readonly type: ParameterType.INT;
         };
+        /** The duration in milliseconds that the response key was held down, measured from key press to key release. Only recorded when `wait_for_key_release` is true; null otherwise or when no response was made. */
+        readonly rt_key_duration: {
+            readonly type: ParameterType.INT;
+        };
     };
     readonly citations: "__CITATIONS__";
 };
@@ -173,6 +189,18 @@ declare class ImageKeyboardResponsePlugin implements JsPsychPlugin<Info> {
                 readonly type: ParameterType.BOOL;
                 readonly default: true;
             };
+            /**
+             * If true, the response is not registered until the participant releases the key. The response
+             * time (`rt`) still reflects when the key was pressed, and the additional data field
+             * `rt_key_duration` records how long the key was held down. Note that when this is true, the
+             * trial cannot end until the key is released: with `response_ends_trial: true` the trial ends at
+             * the key release, and if the trial ends for another reason (e.g., `trial_duration`) while the
+             * key is still held, no response is recorded for the trial.
+             */
+            readonly wait_for_key_release: {
+                readonly type: ParameterType.BOOL;
+                readonly default: false;
+            };
         };
         readonly data: {
             /** The path of the image that was displayed. */
@@ -188,6 +216,10 @@ declare class ImageKeyboardResponsePlugin implements JsPsychPlugin<Info> {
             readonly rt: {
                 readonly type: ParameterType.INT;
             };
+            /** The duration in milliseconds that the response key was held down, measured from key press to key release. Only recorded when `wait_for_key_release` is true; null otherwise or when no response was made. */
+            readonly rt_key_duration: {
+                readonly type: ParameterType.INT;
+            };
         };
         readonly citations: "__CITATIONS__";
     };

package/dist/index.js

@@ -1,6 +1,6 @@
 import { ParameterType } from 'jspsych';
 
-var version = "2.1.0";
+var version = "2.2.0";
 
 const info = {
   name: "image-keyboard-response",
@@ -71,6 +71,18 @@ const info = {
     render_on_canvas: {
       type: ParameterType.BOOL,
       default: true
+    },
+    /**
+     * If true, the response is not registered until the participant releases the key. The response
+     * time (`rt`) still reflects when the key was pressed, and the additional data field
+     * `rt_key_duration` records how long the key was held down. Note that when this is true, the
+     * trial cannot end until the key is released: with `response_ends_trial: true` the trial ends at
+     * the key release, and if the trial ends for another reason (e.g., `trial_duration`) while the
+     * key is still held, no response is recorded for the trial.
+     */
+    wait_for_key_release: {
+      type: ParameterType.BOOL,
+      default: false
     }
   },
   data: {
@@ -86,6 +98,10 @@ const info = {
      * first appears on the screen until the participant's response. */
     rt: {
       type: ParameterType.INT
+    },
+    /** The duration in milliseconds that the response key was held down, measured from key press to key release. Only recorded when `wait_for_key_release` is true; null otherwise or when no response was made. */
+    rt_key_duration: {
+      type: ParameterType.INT
     }
   },
   // prettier-ignore
@@ -182,7 +198,8 @@ class ImageKeyboardResponsePlugin {
     }
     var response = {
       rt: null,
-      key: null
+      key: null,
+      rt_key_duration: null
     };
     const end_trial = () => {
       if (typeof keyboardListener !== "undefined") {
@@ -191,14 +208,19 @@ class ImageKeyboardResponsePlugin {
       var trial_data = {
         rt: response.rt,
         stimulus: trial.stimulus,
-        response: response.key
+        response: response.key,
+        rt_key_duration: response.rt_key_duration
       };
       this.jsPsych.finishTrial(trial_data);
     };
     var after_response = (info2) => {
       display_element.querySelector("#jspsych-image-keyboard-response-stimulus").className += " responded";
       if (response.key == null) {
-        response = info2;
+        response = {
+          rt: info2.rt,
+          key: info2.key,
+          rt_key_duration: info2.rt_key_duration ?? null
+        };
       }
       if (trial.response_ends_trial) {
         end_trial();
@@ -210,7 +232,8 @@ class ImageKeyboardResponsePlugin {
         valid_responses: trial.choices,
         rt_method: "performance",
         persist: false,
-        allow_held_key: false
+        allow_held_key: false,
+        wait_for_key_release: trial.wait_for_key_release
       });
     }
     if (trial.stimulus_duration !== null) {
@@ -256,8 +279,10 @@ class ImageKeyboardResponsePlugin {
     const default_data = {
       stimulus: trial.stimulus,
       rt: this.jsPsych.randomization.sampleExGaussian(500, 50, 1 / 150, true),
-      response: this.jsPsych.pluginAPI.getValidKey(trial.choices)
+      response: this.jsPsych.pluginAPI.getValidKey(trial.choices),
+      rt_key_duration: null
     };
+    default_data.rt_key_duration = default_data.rt === null || !trial.wait_for_key_release ? null : this.jsPsych.randomization.sampleExGaussian(150, 30, 1 / 100, true);
     const data = this.jsPsych.pluginAPI.mergeSimulationData(default_data, simulation_options);
     this.jsPsych.pluginAPI.ensureSimulationDataConsistency(trial, data);
     return data;

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":["../package.json","../src/index.ts"],"sourcesContent":["{\n  \"name\": \"@jspsych/plugin-image-keyboard-response\",\n  \"version\": \"2.1.0\",\n  \"description\": \"jsPsych plugin for displaying a stimulus and getting a keyboard response\",\n  \"type\": \"module\",\n  \"main\": \"dist/index.cjs\",\n  \"exports\": {\n    \"import\": \"./dist/index.js\",\n    \"require\": \"./dist/index.cjs\"\n  },\n  \"typings\": \"dist/index.d.ts\",\n  \"unpkg\": \"dist/index.browser.min.js\",\n  \"files\": [\n    \"src\",\n    \"dist\"\n  ],\n  \"source\": \"src/index.ts\",\n  \"scripts\": {\n    \"test\": \"jest\",\n    \"test:watch\": \"npm test -- --watch\",\n    \"tsc\": \"tsc\",\n    \"build\": \"rollup --config\",\n    \"build:watch\": \"npm run build -- --watch\"\n  },\n  \"repository\": {\n    \"type\": \"git\",\n    \"url\": \"git+https://github.com/jspsych/jsPsych.git\",\n    \"directory\": \"packages/plugin-image-keyboard-response\"\n  },\n  \"author\": \"Josh de Leeuw\",\n  \"license\": \"MIT\",\n  \"bugs\": {\n    \"url\": \"https://github.com/jspsych/jsPsych/issues\"\n  },\n  \"homepage\": \"https://www.jspsych.org/latest/plugins/image-keyboard-response\",\n  \"peerDependencies\": {\n    \"jspsych\": \">=7.1.0\"\n  },\n  \"devDependencies\": {\n    \"@jspsych/config\": \"^3.2.0\",\n    \"@jspsych/test-utils\": \"^1.2.0\"\n  }\n}\n","import { JsPsych, JsPsychPlugin, ParameterType, TrialType } from \"jspsych\";\n\nimport { version } from \"../package.json\";\n\nconst info = <const>{\n  name: \"image-keyboard-response\",\n  version: version,\n  parameters: {\n    /** The path of the image file to be displayed. */\n    stimulus: {\n      type: ParameterType.IMAGE,\n      default: undefined,\n    },\n    /** Set the height of the image in pixels. If left null (no value specified), then the image will display at its natural height. */\n    stimulus_height: {\n      type: ParameterType.INT,\n      default: null,\n    },\n    /** Set the width of the image in pixels. If left null (no value specified), then the image will display at its natural width. */\n    stimulus_width: {\n      type: ParameterType.INT,\n      default: null,\n    },\n    /** If setting *only* the width or *only* the height and this parameter is true, then the other dimension will be scaled\n     * to maintain the image's aspect ratio. */\n    maintain_aspect_ratio: {\n      type: ParameterType.BOOL,\n      default: true,\n    },\n    /**his array contains the key(s) that the participant is allowed to press in order to respond to the stimulus. Keys should\n     * be specified as characters (e.g., `'a'`, `'q'`, `' '`, `'Enter'`, `'ArrowDown'`) - see\n     * [this page](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values) and\n     * [this page (event.key column)](https://www.freecodecamp.org/news/javascript-keycode-list-keypress-event-key-codes/)\n     * for more examples. Any key presses that are not listed in the array will be ignored. The default value of `\"ALL_KEYS\"`\n     * means that all keys will be accepted as valid responses. Specifying `\"NO_KEYS\"` will mean that no responses are allowed. */\n    choices: {\n      type: ParameterType.KEYS,\n      default: \"ALL_KEYS\",\n    },\n    /**This string can contain HTML markup. Any content here will be displayed below the stimulus. The intention is that it can\n     * be used to provide a reminder about the action the participant is supposed to take (e.g., which key to press). */\n    prompt: {\n      type: ParameterType.HTML_STRING,\n      default: null,\n    },\n    /** How long to show the stimulus for in milliseconds. If the value is `null`, then the stimulus will be shown until the\n     * participant makes a response. */\n    stimulus_duration: {\n      type: ParameterType.INT,\n      default: null,\n    },\n    /** How long to wait for the participant to make a response before ending the trial in milliseconds. If the participant\n     * fails to make a response before this timer is reached, the participant's response will be recorded as null for the\n     * trial and the trial will end. If the value of this parameter is `null`, then the trial will wait for a response indefinitely. */\n    trial_duration: {\n      type: ParameterType.INT,\n      default: null,\n    },\n    /** If true, then the trial will end whenever the participant makes a response (assuming they make their response before\n     * the cutoff specified by the `trial_duration` parameter). If false, then the trial will continue until the value for\n     * `trial_duration` is reached. You can set this parameter to `false` to force the participant to view a stimulus for a\n     * fixed amount of time, even if they respond before the time is complete.  */\n    response_ends_trial: {\n      type: ParameterType.BOOL,\n      default: true,\n    },\n    /**\n     * If `true`, the image will be drawn onto a canvas element. This prevents a blank screen (white flash) between consecutive image trials in some browsers, like Firefox and Edge.\n     * If `false`, the image will be shown via an img element, as in previous versions of jsPsych. If the stimulus is an **animated gif**, you must set this parameter to false, because the canvas rendering method will only present static images.\n     */\n    render_on_canvas: {\n      type: ParameterType.BOOL,\n      default: true,\n    },\n  },\n  data: {\n    /** The path of the image that was displayed. */\n    stimulus: {\n      type: ParameterType.STRING,\n    },\n    /**  Indicates which key the participant pressed. */\n    response: {\n      type: ParameterType.STRING,\n    },\n    /** The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus\n     * first appears on the screen until the participant's response. */\n    rt: {\n      type: ParameterType.INT,\n    },\n  },\n  // prettier-ignore\n  citations: '__CITATIONS__',\n};\n\ntype Info = typeof info;\n\n/**\n * This plugin displays an image and records responses generated with the keyboard. The stimulus can be displayed until a\n * response is given, or for a pre-determined amount of time. The trial can be ended automatically if the participant has\n * failed to respond within a fixed length of time.\n *\n * Image files can be automatically preloaded by jsPsych using the [`preload` plugin](preload.md). However, if you are using\n * timeline variables or another dynamic method to specify the image stimulus, you will need to\n * [manually preload](../overview/media-preloading.md#manual-preloading) the images.\n *\n * @author Josh de Leeuw\n * @see {@link https://www.jspsych.org/latest/plugins/image-keyboard-response/ image-keyboard-response plugin documentation on jspsych.org}\n */\nclass ImageKeyboardResponsePlugin implements JsPsychPlugin<Info> {\n  static info = info;\n\n  constructor(private jsPsych: JsPsych) {}\n\n  trial(display_element: HTMLElement, trial: TrialType<Info>) {\n    var height, width;\n    if (trial.render_on_canvas) {\n      var image_drawn = false;\n      // first clear the display element (because the render_on_canvas method appends to display_element instead of overwriting it with .innerHTML)\n      if (display_element.hasChildNodes()) {\n        // can't loop through child list because the list will be modified by .removeChild()\n        while (display_element.firstChild) {\n          display_element.removeChild(display_element.firstChild);\n        }\n      }\n      // create canvas element and image\n      var canvas = document.createElement(\"canvas\");\n      canvas.id = \"jspsych-image-keyboard-response-stimulus\";\n      canvas.style.margin = \"0\";\n      canvas.style.padding = \"0\";\n      var ctx = canvas.getContext(\"2d\");\n      var img = new Image();\n      img.onload = () => {\n        // if image wasn't preloaded, then it will need to be drawn whenever it finishes loading\n        if (!image_drawn) {\n          getHeightWidth(); // only possible to get width/height after image loads\n          ctx.drawImage(img, 0, 0, width, height);\n        }\n      };\n      img.src = trial.stimulus;\n      // get/set image height and width - this can only be done after image loads because uses image's naturalWidth/naturalHeight properties\n      const getHeightWidth = () => {\n        if (trial.stimulus_height !== null) {\n          height = trial.stimulus_height;\n          if (trial.stimulus_width == null && trial.maintain_aspect_ratio) {\n            width = img.naturalWidth * (trial.stimulus_height / img.naturalHeight);\n          }\n        } else {\n          height = img.naturalHeight;\n        }\n        if (trial.stimulus_width !== null) {\n          width = trial.stimulus_width;\n          if (trial.stimulus_height == null && trial.maintain_aspect_ratio) {\n            height = img.naturalHeight * (trial.stimulus_width / img.naturalWidth);\n          }\n        } else if (!(trial.stimulus_height !== null && trial.maintain_aspect_ratio)) {\n          // if stimulus width is null, only use the image's natural width if the width value wasn't set\n          // in the if statement above, based on a specified height and maintain_aspect_ratio = true\n          width = img.naturalWidth;\n        }\n        canvas.height = height;\n        canvas.width = width;\n      };\n      getHeightWidth(); // call now, in case image loads immediately (is cached)\n      // add canvas and draw image\n      display_element.insertBefore(canvas, null);\n      if (img.complete && Number.isFinite(width) && Number.isFinite(height)) {\n        // if image has loaded and width/height have been set, then draw it now\n        // (don't rely on img onload function to draw image when image is in the cache, because that causes a delay in the image presentation)\n        ctx.drawImage(img, 0, 0, width, height);\n        image_drawn = true;\n      }\n      // add prompt if there is one\n      if (trial.prompt !== null) {\n        display_element.insertAdjacentHTML(\"beforeend\", trial.prompt);\n      }\n    } else {\n      // display stimulus as an image element\n      var html = '<img src=\"' + trial.stimulus + '\" id=\"jspsych-image-keyboard-response-stimulus\">';\n      // add prompt\n      if (trial.prompt !== null) {\n        html += trial.prompt;\n      }\n      // update the page content\n      display_element.innerHTML = html;\n\n      // set image dimensions after image has loaded (so that we have access to naturalHeight/naturalWidth)\n      var img = display_element.querySelector(\n        \"#jspsych-image-keyboard-response-stimulus\"\n      ) as HTMLImageElement;\n      if (trial.stimulus_height !== null) {\n        height = trial.stimulus_height;\n        if (trial.stimulus_width == null && trial.maintain_aspect_ratio) {\n          width = img.naturalWidth * (trial.stimulus_height / img.naturalHeight);\n        }\n      } else {\n        height = img.naturalHeight;\n      }\n      if (trial.stimulus_width !== null) {\n        width = trial.stimulus_width;\n        if (trial.stimulus_height == null && trial.maintain_aspect_ratio) {\n          height = img.naturalHeight * (trial.stimulus_width / img.naturalWidth);\n        }\n      } else if (!(trial.stimulus_height !== null && trial.maintain_aspect_ratio)) {\n        // if stimulus width is null, only use the image's natural width if the width value wasn't set\n        // in the if statement above, based on a specified height and maintain_aspect_ratio = true\n        width = img.naturalWidth;\n      }\n      img.style.height = height.toString() + \"px\";\n      img.style.width = width.toString() + \"px\";\n    }\n\n    // store response\n    var response = {\n      rt: null,\n      key: null,\n    };\n\n    // function to end trial when it is time\n    const end_trial = () => {\n      // kill keyboard listeners\n      if (typeof keyboardListener !== \"undefined\") {\n        this.jsPsych.pluginAPI.cancelKeyboardResponse(keyboardListener);\n      }\n\n      // gather the data to store for the trial\n      var trial_data = {\n        rt: response.rt,\n        stimulus: trial.stimulus,\n        response: response.key,\n      };\n\n      // move on to the next trial\n      this.jsPsych.finishTrial(trial_data);\n    };\n\n    // function to handle responses by the subject\n    var after_response = (info) => {\n      // after a valid response, the stimulus will have the CSS class 'responded'\n      // which can be used to provide visual feedback that a response was recorded\n      display_element.querySelector(\"#jspsych-image-keyboard-response-stimulus\").className +=\n        \" responded\";\n\n      // only record the first response\n      if (response.key == null) {\n        response = info;\n      }\n\n      if (trial.response_ends_trial) {\n        end_trial();\n      }\n    };\n\n    // start the response listener\n    if (trial.choices != \"NO_KEYS\") {\n      var keyboardListener = this.jsPsych.pluginAPI.getKeyboardResponse({\n        callback_function: after_response,\n        valid_responses: trial.choices,\n        rt_method: \"performance\",\n        persist: false,\n        allow_held_key: false,\n      });\n    }\n\n    // hide stimulus if stimulus_duration is set\n    if (trial.stimulus_duration !== null) {\n      this.jsPsych.pluginAPI.setTimeout(() => {\n        display_element.querySelector<HTMLElement>(\n          \"#jspsych-image-keyboard-response-stimulus\"\n        ).style.visibility = \"hidden\";\n      }, trial.stimulus_duration);\n    }\n\n    // end trial if trial_duration is set\n    if (trial.trial_duration !== null) {\n      this.jsPsych.pluginAPI.setTimeout(() => {\n        end_trial();\n      }, trial.trial_duration);\n    } else if (trial.response_ends_trial === false) {\n      console.warn(\n        \"The experiment may be deadlocked. Try setting a trial duration or set response_ends_trial to true.\"\n      );\n    }\n  }\n\n  simulate(\n    trial: TrialType<Info>,\n    simulation_mode,\n    simulation_options: any,\n    load_callback: () => void\n  ) {\n    if (simulation_mode == \"data-only\") {\n      load_callback();\n      this.simulate_data_only(trial, simulation_options);\n    }\n    if (simulation_mode == \"visual\") {\n      this.simulate_visual(trial, simulation_options, load_callback);\n    }\n  }\n\n  private simulate_data_only(trial: TrialType<Info>, simulation_options) {\n    const data = this.create_simulation_data(trial, simulation_options);\n\n    this.jsPsych.finishTrial(data);\n  }\n\n  private simulate_visual(trial: TrialType<Info>, simulation_options, load_callback: () => void) {\n    const data = this.create_simulation_data(trial, simulation_options);\n\n    const display_element = this.jsPsych.getDisplayElement();\n\n    this.trial(display_element, trial);\n    load_callback();\n\n    if (data.rt !== null) {\n      this.jsPsych.pluginAPI.pressKey(data.response, data.rt);\n    }\n  }\n\n  private create_simulation_data(trial: TrialType<Info>, simulation_options) {\n    const default_data = {\n      stimulus: trial.stimulus,\n      rt: this.jsPsych.randomization.sampleExGaussian(500, 50, 1 / 150, true),\n      response: this.jsPsych.pluginAPI.getValidKey(trial.choices),\n    };\n\n    const data = this.jsPsych.pluginAPI.mergeSimulationData(default_data, simulation_options);\n\n    this.jsPsych.pluginAPI.ensureSimulationDataConsistency(trial, data);\n\n    return data;\n  }\n}\n\nexport default ImageKeyboardResponsePlugin;\n"],"names":[],"mappings":";;AAEE,IAAW,OAAA,GAAA,OAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ECyFA,SAAA,EAAA;AAAA;;GAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"index.js","sources":["../package.json","../src/index.ts"],"sourcesContent":["{\n  \"name\": \"@jspsych/plugin-image-keyboard-response\",\n  \"version\": \"2.2.0\",\n  \"description\": \"jsPsych plugin for displaying a stimulus and getting a keyboard response\",\n  \"type\": \"module\",\n  \"main\": \"dist/index.cjs\",\n  \"exports\": {\n    \"import\": \"./dist/index.js\",\n    \"require\": \"./dist/index.cjs\"\n  },\n  \"typings\": \"dist/index.d.ts\",\n  \"unpkg\": \"dist/index.browser.min.js\",\n  \"files\": [\n    \"src\",\n    \"dist\"\n  ],\n  \"source\": \"src/index.ts\",\n  \"scripts\": {\n    \"test\": \"jest\",\n    \"test:watch\": \"npm test -- --watch\",\n    \"tsc\": \"tsc\",\n    \"build\": \"rollup --config\",\n    \"build:watch\": \"npm run build -- --watch\"\n  },\n  \"repository\": {\n    \"type\": \"git\",\n    \"url\": \"git+https://github.com/jspsych/jsPsych.git\",\n    \"directory\": \"packages/plugin-image-keyboard-response\"\n  },\n  \"author\": \"Josh de Leeuw\",\n  \"license\": \"MIT\",\n  \"bugs\": {\n    \"url\": \"https://github.com/jspsych/jsPsych/issues\"\n  },\n  \"homepage\": \"https://www.jspsych.org/latest/plugins/image-keyboard-response\",\n  \"peerDependencies\": {\n    \"jspsych\": \">=7.1.0\"\n  },\n  \"devDependencies\": {\n    \"@jspsych/config\": \"^3.3.4\",\n    \"@jspsych/test-utils\": \"^1.3.0\"\n  }\n}\n","import { JsPsych, JsPsychPlugin, ParameterType, TrialType } from \"jspsych\";\n\nimport { version } from \"../package.json\";\n\nconst info = <const>{\n  name: \"image-keyboard-response\",\n  version: version,\n  parameters: {\n    /** The path of the image file to be displayed. */\n    stimulus: {\n      type: ParameterType.IMAGE,\n      default: undefined,\n    },\n    /** Set the height of the image in pixels. If left null (no value specified), then the image will display at its natural height. */\n    stimulus_height: {\n      type: ParameterType.INT,\n      default: null,\n    },\n    /** Set the width of the image in pixels. If left null (no value specified), then the image will display at its natural width. */\n    stimulus_width: {\n      type: ParameterType.INT,\n      default: null,\n    },\n    /** If setting *only* the width or *only* the height and this parameter is true, then the other dimension will be scaled\n     * to maintain the image's aspect ratio. */\n    maintain_aspect_ratio: {\n      type: ParameterType.BOOL,\n      default: true,\n    },\n    /**his array contains the key(s) that the participant is allowed to press in order to respond to the stimulus. Keys should\n     * be specified as characters (e.g., `'a'`, `'q'`, `' '`, `'Enter'`, `'ArrowDown'`) - see\n     * [this page](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values) and\n     * [this page (event.key column)](https://www.freecodecamp.org/news/javascript-keycode-list-keypress-event-key-codes/)\n     * for more examples. Any key presses that are not listed in the array will be ignored. The default value of `\"ALL_KEYS\"`\n     * means that all keys will be accepted as valid responses. Specifying `\"NO_KEYS\"` will mean that no responses are allowed. */\n    choices: {\n      type: ParameterType.KEYS,\n      default: \"ALL_KEYS\",\n    },\n    /**This string can contain HTML markup. Any content here will be displayed below the stimulus. The intention is that it can\n     * be used to provide a reminder about the action the participant is supposed to take (e.g., which key to press). */\n    prompt: {\n      type: ParameterType.HTML_STRING,\n      default: null,\n    },\n    /** How long to show the stimulus for in milliseconds. If the value is `null`, then the stimulus will be shown until the\n     * participant makes a response. */\n    stimulus_duration: {\n      type: ParameterType.INT,\n      default: null,\n    },\n    /** How long to wait for the participant to make a response before ending the trial in milliseconds. If the participant\n     * fails to make a response before this timer is reached, the participant's response will be recorded as null for the\n     * trial and the trial will end. If the value of this parameter is `null`, then the trial will wait for a response indefinitely. */\n    trial_duration: {\n      type: ParameterType.INT,\n      default: null,\n    },\n    /** If true, then the trial will end whenever the participant makes a response (assuming they make their response before\n     * the cutoff specified by the `trial_duration` parameter). If false, then the trial will continue until the value for\n     * `trial_duration` is reached. You can set this parameter to `false` to force the participant to view a stimulus for a\n     * fixed amount of time, even if they respond before the time is complete.  */\n    response_ends_trial: {\n      type: ParameterType.BOOL,\n      default: true,\n    },\n    /**\n     * If `true`, the image will be drawn onto a canvas element. This prevents a blank screen (white flash) between consecutive image trials in some browsers, like Firefox and Edge.\n     * If `false`, the image will be shown via an img element, as in previous versions of jsPsych. If the stimulus is an **animated gif**, you must set this parameter to false, because the canvas rendering method will only present static images.\n     */\n    render_on_canvas: {\n      type: ParameterType.BOOL,\n      default: true,\n    },\n    /**\n     * If true, the response is not registered until the participant releases the key. The response\n     * time (`rt`) still reflects when the key was pressed, and the additional data field\n     * `rt_key_duration` records how long the key was held down. Note that when this is true, the\n     * trial cannot end until the key is released: with `response_ends_trial: true` the trial ends at\n     * the key release, and if the trial ends for another reason (e.g., `trial_duration`) while the\n     * key is still held, no response is recorded for the trial.\n     */\n    wait_for_key_release: {\n      type: ParameterType.BOOL,\n      default: false,\n    },\n  },\n  data: {\n    /** The path of the image that was displayed. */\n    stimulus: {\n      type: ParameterType.STRING,\n    },\n    /**  Indicates which key the participant pressed. */\n    response: {\n      type: ParameterType.STRING,\n    },\n    /** The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus\n     * first appears on the screen until the participant's response. */\n    rt: {\n      type: ParameterType.INT,\n    },\n    /** The duration in milliseconds that the response key was held down, measured from key press to key release. Only recorded when `wait_for_key_release` is true; null otherwise or when no response was made. */\n    rt_key_duration: {\n      type: ParameterType.INT,\n    },\n  },\n  // prettier-ignore\n  citations: '__CITATIONS__',\n};\n\ntype Info = typeof info;\n\n/**\n * This plugin displays an image and records responses generated with the keyboard. The stimulus can be displayed until a\n * response is given, or for a pre-determined amount of time. The trial can be ended automatically if the participant has\n * failed to respond within a fixed length of time.\n *\n * Image files can be automatically preloaded by jsPsych using the [`preload` plugin](preload.md). However, if you are using\n * timeline variables or another dynamic method to specify the image stimulus, you will need to\n * [manually preload](../overview/media-preloading.md#manual-preloading) the images.\n *\n * @author Josh de Leeuw\n * @see {@link https://www.jspsych.org/latest/plugins/image-keyboard-response/ image-keyboard-response plugin documentation on jspsych.org}\n */\nclass ImageKeyboardResponsePlugin implements JsPsychPlugin<Info> {\n  static info = info;\n\n  constructor(private jsPsych: JsPsych) {}\n\n  trial(display_element: HTMLElement, trial: TrialType<Info>) {\n    var height, width;\n    if (trial.render_on_canvas) {\n      var image_drawn = false;\n      // first clear the display element (because the render_on_canvas method appends to display_element instead of overwriting it with .innerHTML)\n      if (display_element.hasChildNodes()) {\n        // can't loop through child list because the list will be modified by .removeChild()\n        while (display_element.firstChild) {\n          display_element.removeChild(display_element.firstChild);\n        }\n      }\n      // create canvas element and image\n      var canvas = document.createElement(\"canvas\");\n      canvas.id = \"jspsych-image-keyboard-response-stimulus\";\n      canvas.style.margin = \"0\";\n      canvas.style.padding = \"0\";\n      var ctx = canvas.getContext(\"2d\");\n      var img = new Image();\n      img.onload = () => {\n        // if image wasn't preloaded, then it will need to be drawn whenever it finishes loading\n        if (!image_drawn) {\n          getHeightWidth(); // only possible to get width/height after image loads\n          ctx.drawImage(img, 0, 0, width, height);\n        }\n      };\n      img.src = trial.stimulus;\n      // get/set image height and width - this can only be done after image loads because uses image's naturalWidth/naturalHeight properties\n      const getHeightWidth = () => {\n        if (trial.stimulus_height !== null) {\n          height = trial.stimulus_height;\n          if (trial.stimulus_width == null && trial.maintain_aspect_ratio) {\n            width = img.naturalWidth * (trial.stimulus_height / img.naturalHeight);\n          }\n        } else {\n          height = img.naturalHeight;\n        }\n        if (trial.stimulus_width !== null) {\n          width = trial.stimulus_width;\n          if (trial.stimulus_height == null && trial.maintain_aspect_ratio) {\n            height = img.naturalHeight * (trial.stimulus_width / img.naturalWidth);\n          }\n        } else if (!(trial.stimulus_height !== null && trial.maintain_aspect_ratio)) {\n          // if stimulus width is null, only use the image's natural width if the width value wasn't set\n          // in the if statement above, based on a specified height and maintain_aspect_ratio = true\n          width = img.naturalWidth;\n        }\n        canvas.height = height;\n        canvas.width = width;\n      };\n      getHeightWidth(); // call now, in case image loads immediately (is cached)\n      // add canvas and draw image\n      display_element.insertBefore(canvas, null);\n      if (img.complete && Number.isFinite(width) && Number.isFinite(height)) {\n        // if image has loaded and width/height have been set, then draw it now\n        // (don't rely on img onload function to draw image when image is in the cache, because that causes a delay in the image presentation)\n        ctx.drawImage(img, 0, 0, width, height);\n        image_drawn = true;\n      }\n      // add prompt if there is one\n      if (trial.prompt !== null) {\n        display_element.insertAdjacentHTML(\"beforeend\", trial.prompt);\n      }\n    } else {\n      // display stimulus as an image element\n      var html = '<img src=\"' + trial.stimulus + '\" id=\"jspsych-image-keyboard-response-stimulus\">';\n      // add prompt\n      if (trial.prompt !== null) {\n        html += trial.prompt;\n      }\n      // update the page content\n      display_element.innerHTML = html;\n\n      // set image dimensions after image has loaded (so that we have access to naturalHeight/naturalWidth)\n      var img = display_element.querySelector(\n        \"#jspsych-image-keyboard-response-stimulus\"\n      ) as HTMLImageElement;\n      if (trial.stimulus_height !== null) {\n        height = trial.stimulus_height;\n        if (trial.stimulus_width == null && trial.maintain_aspect_ratio) {\n          width = img.naturalWidth * (trial.stimulus_height / img.naturalHeight);\n        }\n      } else {\n        height = img.naturalHeight;\n      }\n      if (trial.stimulus_width !== null) {\n        width = trial.stimulus_width;\n        if (trial.stimulus_height == null && trial.maintain_aspect_ratio) {\n          height = img.naturalHeight * (trial.stimulus_width / img.naturalWidth);\n        }\n      } else if (!(trial.stimulus_height !== null && trial.maintain_aspect_ratio)) {\n        // if stimulus width is null, only use the image's natural width if the width value wasn't set\n        // in the if statement above, based on a specified height and maintain_aspect_ratio = true\n        width = img.naturalWidth;\n      }\n      img.style.height = height.toString() + \"px\";\n      img.style.width = width.toString() + \"px\";\n    }\n\n    // store response\n    var response = {\n      rt: null,\n      key: null,\n      rt_key_duration: null,\n    };\n\n    // function to end trial when it is time\n    const end_trial = () => {\n      // kill keyboard listeners\n      if (typeof keyboardListener !== \"undefined\") {\n        this.jsPsych.pluginAPI.cancelKeyboardResponse(keyboardListener);\n      }\n\n      // gather the data to store for the trial\n      var trial_data = {\n        rt: response.rt,\n        stimulus: trial.stimulus,\n        response: response.key,\n        rt_key_duration: response.rt_key_duration,\n      };\n\n      // move on to the next trial\n      this.jsPsych.finishTrial(trial_data);\n    };\n\n    // function to handle responses by the subject\n    var after_response = (info) => {\n      // after a valid response, the stimulus will have the CSS class 'responded'\n      // which can be used to provide visual feedback that a response was recorded\n      display_element.querySelector(\"#jspsych-image-keyboard-response-stimulus\").className +=\n        \" responded\";\n\n      // only record the first response\n      if (response.key == null) {\n        response = {\n          rt: info.rt,\n          key: info.key,\n          rt_key_duration: info.rt_key_duration ?? null,\n        };\n      }\n\n      if (trial.response_ends_trial) {\n        end_trial();\n      }\n    };\n\n    // start the response listener\n    if (trial.choices != \"NO_KEYS\") {\n      var keyboardListener = this.jsPsych.pluginAPI.getKeyboardResponse({\n        callback_function: after_response,\n        valid_responses: trial.choices,\n        rt_method: \"performance\",\n        persist: false,\n        allow_held_key: false,\n        wait_for_key_release: trial.wait_for_key_release,\n      });\n    }\n\n    // hide stimulus if stimulus_duration is set\n    if (trial.stimulus_duration !== null) {\n      this.jsPsych.pluginAPI.setTimeout(() => {\n        display_element.querySelector<HTMLElement>(\n          \"#jspsych-image-keyboard-response-stimulus\"\n        ).style.visibility = \"hidden\";\n      }, trial.stimulus_duration);\n    }\n\n    // end trial if trial_duration is set\n    if (trial.trial_duration !== null) {\n      this.jsPsych.pluginAPI.setTimeout(() => {\n        end_trial();\n      }, trial.trial_duration);\n    } else if (trial.response_ends_trial === false) {\n      console.warn(\n        \"The experiment may be deadlocked. Try setting a trial duration or set response_ends_trial to true.\"\n      );\n    }\n  }\n\n  simulate(\n    trial: TrialType<Info>,\n    simulation_mode,\n    simulation_options: any,\n    load_callback: () => void\n  ) {\n    if (simulation_mode == \"data-only\") {\n      load_callback();\n      this.simulate_data_only(trial, simulation_options);\n    }\n    if (simulation_mode == \"visual\") {\n      this.simulate_visual(trial, simulation_options, load_callback);\n    }\n  }\n\n  private simulate_data_only(trial: TrialType<Info>, simulation_options) {\n    const data = this.create_simulation_data(trial, simulation_options);\n\n    this.jsPsych.finishTrial(data);\n  }\n\n  private simulate_visual(trial: TrialType<Info>, simulation_options, load_callback: () => void) {\n    const data = this.create_simulation_data(trial, simulation_options);\n\n    const display_element = this.jsPsych.getDisplayElement();\n\n    this.trial(display_element, trial);\n    load_callback();\n\n    if (data.rt !== null) {\n      this.jsPsych.pluginAPI.pressKey(data.response, data.rt);\n    }\n  }\n\n  private create_simulation_data(trial: TrialType<Info>, simulation_options) {\n    const default_data = {\n      stimulus: trial.stimulus,\n      rt: this.jsPsych.randomization.sampleExGaussian(500, 50, 1 / 150, true),\n      response: this.jsPsych.pluginAPI.getValidKey(trial.choices),\n      rt_key_duration: null,\n    };\n    default_data.rt_key_duration =\n      default_data.rt === null || !trial.wait_for_key_release\n        ? null\n        : this.jsPsych.randomization.sampleExGaussian(150, 30, 1 / 100, true);\n\n    const data = this.jsPsych.pluginAPI.mergeSimulationData(default_data, simulation_options);\n\n    this.jsPsych.pluginAPI.ensureSimulationDataConsistency(trial, data);\n\n    return data;\n  }\n}\n\nexport default ImageKeyboardResponsePlugin;\n"],"names":[],"mappings":";;AAEE,IAAA,OAAA,GAAW,OAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ECyGA,SAAA,EAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jspsych/plugin-image-keyboard-response",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "jsPsych plugin for displaying a stimulus and getting a keyboard response",
   "type": "module",
   "main": "dist/index.cjs",
@@ -37,7 +37,7 @@
     "jspsych": ">=7.1.0"
   },
   "devDependencies": {
-    "@jspsych/config": "^3.2.0",
-    "@jspsych/test-utils": "^1.2.0"
+    "@jspsych/config": "^3.3.4",
+    "@jspsych/test-utils": "^1.3.0"
   }
 }

package/src/index.spec.ts

@@ -1,4 +1,4 @@
-import { pressKey, startTimeline } from "@jspsych/test-utils";
+import { flushPromises, keyDown, keyUp, pressKey, startTimeline } from "@jspsych/test-utils";
 
 import imageKeyboardResponse from ".";
 
@@ -135,3 +135,143 @@ describe("image-keyboard-response", () => {
     spy.mockRestore();
   });
 });
+
+describe("image-keyboard-response wait_for_key_release", () => {
+  test("does not end the trial until the key is released and records the hold duration", async () => {
+    const { getData, expectRunning, expectFinished } = await startTimeline([
+      {
+        type: imageKeyboardResponse,
+        stimulus: "../media/blue.png",
+        choices: ["a"],
+        render_on_canvas: false,
+        wait_for_key_release: true,
+      },
+    ]);
+
+    jest.advanceTimersByTime(100);
+    await keyDown("a");
+
+    await expectRunning();
+
+    jest.advanceTimersByTime(250);
+    await keyUp("a");
+
+    await expectFinished();
+
+    expect(getData().values()[0].rt).toBe(100);
+    expect(getData().values()[0].rt_key_duration).toBe(250);
+  });
+
+  test("records the hold duration when the trial ends by duration", async () => {
+    const { getData, expectFinished } = await startTimeline([
+      {
+        type: imageKeyboardResponse,
+        stimulus: "../media/blue.png",
+        choices: ["a"],
+        render_on_canvas: false,
+        wait_for_key_release: true,
+        response_ends_trial: false,
+        trial_duration: 1000,
+      },
+    ]);
+
+    await keyDown("a");
+    jest.advanceTimersByTime(250);
+    await keyUp("a");
+
+    jest.advanceTimersByTime(750);
+    await expectFinished();
+
+    expect(getData().values()[0].rt_key_duration).toBe(250);
+  });
+
+  test("records a null response when the trial ends while the key is still held", async () => {
+    const { getData, expectFinished } = await startTimeline([
+      {
+        type: imageKeyboardResponse,
+        stimulus: "../media/blue.png",
+        choices: ["a"],
+        render_on_canvas: false,
+        wait_for_key_release: true,
+        response_ends_trial: false,
+        trial_duration: 1000,
+      },
+    ]);
+
+    await keyDown("a");
+    jest.advanceTimersByTime(1000);
+    await expectFinished();
+
+    expect(getData().values()[0].response).toBe(null);
+    expect(getData().values()[0].rt).toBe(null);
+    expect(getData().values()[0].rt_key_duration).toBe(null);
+
+    await keyUp("a");
+  });
+
+  test("rt_key_duration is null on default trials (wait_for_key_release false)", async () => {
+    const { getData, expectFinished } = await startTimeline([
+      {
+        type: imageKeyboardResponse,
+        stimulus: "../media/blue.png",
+        choices: ["a"],
+        render_on_canvas: false,
+      },
+    ]);
+
+    await keyDown("a");
+    await expectFinished();
+
+    expect(getData().values()[0].rt_key_duration).toBe(null);
+  });
+
+  test("a key held past trial_duration does not contaminate the next trial", async () => {
+    const { getData, expectRunning, expectFinished } = await startTimeline([
+      {
+        type: imageKeyboardResponse,
+        stimulus: "../media/blue.png",
+        choices: ["a"],
+        render_on_canvas: false,
+        wait_for_key_release: true,
+        trial_duration: 1000,
+      },
+      {
+        type: imageKeyboardResponse,
+        stimulus: "../media/blue.png",
+        choices: ["a"],
+        render_on_canvas: false,
+        wait_for_key_release: true,
+      },
+    ]);
+
+    // trial 1: press and hold the key, then let the trial time out
+    await keyDown("a");
+    jest.advanceTimersByTime(1000);
+    await flushPromises();
+
+    // trial 1 ended by duration with no response because the key was never released
+    expect(getData().values()[0].response).toBe(null);
+    expect(getData().values()[0].rt).toBe(null);
+    expect(getData().values()[0].rt_key_duration).toBe(null);
+
+    // trial 2 is now running with the key still held; a key-repeat must not register
+    await keyDown("a");
+    await expectRunning();
+
+    // releasing the held-over key must not register a response in trial 2
+    await keyUp("a");
+    await expectRunning();
+
+    // a fresh press/release cycle in trial 2 works normally
+    jest.advanceTimersByTime(200);
+    await keyDown("a");
+    jest.advanceTimersByTime(125);
+    await keyUp("a");
+
+    await expectFinished();
+
+    expect(getData().values()[1].response).toBe("a");
+    expect(getData().values()[1].rt).toBe(200);
+    expect(getData().values()[1].rt_key_duration).toBe(125);
+  });
+});

package/src/index.ts

@@ -72,6 +72,18 @@ const info = <const>{
       type: ParameterType.BOOL,
       default: true,
     },
+    /**
+     * If true, the response is not registered until the participant releases the key. The response
+     * time (`rt`) still reflects when the key was pressed, and the additional data field
+     * `rt_key_duration` records how long the key was held down. Note that when this is true, the
+     * trial cannot end until the key is released: with `response_ends_trial: true` the trial ends at
+     * the key release, and if the trial ends for another reason (e.g., `trial_duration`) while the
+     * key is still held, no response is recorded for the trial.
+     */
+    wait_for_key_release: {
+      type: ParameterType.BOOL,
+      default: false,
+    },
   },
   data: {
     /** The path of the image that was displayed. */
@@ -87,6 +99,10 @@ const info = <const>{
     rt: {
       type: ParameterType.INT,
     },
+    /** The duration in milliseconds that the response key was held down, measured from key press to key release. Only recorded when `wait_for_key_release` is true; null otherwise or when no response was made. */
+    rt_key_duration: {
+      type: ParameterType.INT,
+    },
   },
   // prettier-ignore
   citations: '__CITATIONS__',
@@ -213,6 +229,7 @@ class ImageKeyboardResponsePlugin implements JsPsychPlugin<Info> {
     var response = {
       rt: null,
       key: null,
+      rt_key_duration: null,
     };
 
     // function to end trial when it is time
@@ -227,6 +244,7 @@ class ImageKeyboardResponsePlugin implements JsPsychPlugin<Info> {
         rt: response.rt,
         stimulus: trial.stimulus,
         response: response.key,
+        rt_key_duration: response.rt_key_duration,
       };
 
       // move on to the next trial
@@ -242,7 +260,11 @@ class ImageKeyboardResponsePlugin implements JsPsychPlugin<Info> {
 
       // only record the first response
       if (response.key == null) {
-        response = info;
+        response = {
+          rt: info.rt,
+          key: info.key,
+          rt_key_duration: info.rt_key_duration ?? null,
+        };
       }
 
       if (trial.response_ends_trial) {
@@ -258,6 +280,7 @@ class ImageKeyboardResponsePlugin implements JsPsychPlugin<Info> {
         rt_method: "performance",
         persist: false,
         allow_held_key: false,
+        wait_for_key_release: trial.wait_for_key_release,
       });
     }
 
@@ -321,7 +344,12 @@ class ImageKeyboardResponsePlugin implements JsPsychPlugin<Info> {
       stimulus: trial.stimulus,
       rt: this.jsPsych.randomization.sampleExGaussian(500, 50, 1 / 150, true),
       response: this.jsPsych.pluginAPI.getValidKey(trial.choices),
+      rt_key_duration: null,
     };
+    default_data.rt_key_duration =
+      default_data.rt === null || !trial.wait_for_key_release
+        ? null
+        : this.jsPsych.randomization.sampleExGaussian(150, 30, 1 / 100, true);
 
     const data = this.jsPsych.pluginAPI.mergeSimulationData(default_data, simulation_options);