Merge pull request jspsych#3344 from jspsych/v8

Version 8.0

.changeset/afraid-badgers-lie.md

@@ -0,0 +1,5 @@
+---
+"jspsych": minor
+---
+
+Added `jsPsych.abortTimelineByName()`. This allows for aborting a specific active timeline by its `name` property. The `name` can be set in the description of the timline.

.changeset/bright-apples-hope.md

@@ -0,0 +1,5 @@
+---
+"jspsych": patch
+---
+
+`getKeyboardResponse` now returns the `key` in the original case (e.g., "Enter" instead of "enter") for easier matching to standard key event documentation.

.changeset/button-layouts.md

@@ -0,0 +1,8 @@
+---
+"@jspsych/plugin-html-button-response": major
+"jspsych": patch
+---
+
+Button plugins now support either `display: grid` or `display: flex` on the container element that hold the buttons. If the layout is `grid`, the number of rows and/or columns can be specified. The `margin_horizontal` and `margin_vertical` parameters have been removed from the button plugins. If you need control over the button CSS, you can add inline style to the button element using the `button_html` parameter.
+
+jspsych.css has new layout classes to support this feature.

.changeset/button-response-plugins.md

@@ -0,0 +1,31 @@
+---
+"@jspsych/plugin-audio-button-response": major
+"@jspsych/plugin-canvas-button-response": major
+"@jspsych/plugin-html-button-response": major
+"@jspsych/plugin-image-button-response": major
+"@jspsych/plugin-video-button-response": major
+---
+
+- Make `button_html` a function parameter which, given a choice's text and its index, returns the HTML string of the choice's button. If you were previously passing a string to `button_html`, like `<button>%choice%</button>`, you can now pass the function
+  ```js
+  function (choice) {
+    return '<button class="jspsych-btn">' + choice + "</button>";
+  }
+  ```
+  Similarly, if you were using the array syntax, like
+  ```js
+  ['<button class="a">%choice%</button>', '<button class="b">%choice%</button>', '<button class="a">%choice%</button>']
+  ```
+  an easy way to migrate your trial definition is to pass a function which accesses your array and replaces the `%choice%` placeholder:
+  ```js
+  function (choice, choice_index) {
+    return ['<button class="a">%choice%</button>', '<button class="b">%choice%</button>', '<button class="a">%choice%</button>'][choice_index].replace("%choice%", choice);
+  }
+  ```
+  From there on, you can further simplify your function. For instance, if the intention of the above example is to have alternating button classes, the `button_html` function might be rewritten as
+  ```js
+  function (choice, choice_index) {
+    return '<button class="' + (choice_index % 2 === 0 ? "a" : "b") + '">' + choice + "</button>";
+  }
+  ```
+- Simplify the button DOM structure and styling: Buttons are no longer wrapped in individual container `div`s for spacing and `data-choice` attributes. Instead, each button is assigned its `data-choice` attribute and all buttons are direct children of the button group container `div`. The container `div`, in turn, utilizes a flexbox layout to position the buttons.

.changeset/chilled-papayas-admire.md

@@ -0,0 +1,58 @@
+---
+"jspsych": minor
+"@jspsych/plugin-animation": minor
+"@jspsych/plugin-audio-button-response": minor
+"@jspsych/plugin-audio-keyboard-response": minor
+"@jspsych/plugin-audio-slider-response": minor
+"@jspsych/plugin-browser-check": minor
+"@jspsych/plugin-call-function": minor
+"@jspsych/plugin-canvas-button-response": minor
+"@jspsych/plugin-canvas-keyboard-response": minor
+"@jspsych/plugin-canvas-slider-response": minor
+"@jspsych/plugin-categorize-animation": minor
+"@jspsych/plugin-categorize-html": minor
+"@jspsych/plugin-categorize-image": minor
+"@jspsych/plugin-cloze": minor
+"@jspsych/plugin-external-html": minor
+"@jspsych/plugin-free-sort": minor
+"@jspsych/plugin-fullscreen": minor
+"@jspsych/plugin-html-audio-response": minor
+"@jspsych/plugin-html-button-response": minor
+"@jspsych/plugin-html-keyboard-response": minor
+"@jspsych/plugin-html-slider-response": minor
+"@jspsych/plugin-html-video-response": minor
+"@jspsych/plugin-iat-html": minor
+"@jspsych/plugin-iat-image": minor
+"@jspsych/plugin-image-button-response": minor
+"@jspsych/plugin-image-keyboard-response": minor
+"@jspsych/plugin-image-slider-response": minor
+"@jspsych/plugin-initialize-camera": minor
+"@jspsych/plugin-initialize-microphone": minor
+"@jspsych/plugin-instructions": minor
+"@jspsych/plugin-maxdiff": minor
+"@jspsych/plugin-mirror-camera": minor
+"@jspsych/plugin-preload": minor
+"@jspsych/plugin-reconstruction": minor
+"@jspsych/plugin-resize": minor
+"@jspsych/plugin-same-different-html": minor
+"@jspsych/plugin-same-different-image": minor
+"@jspsych/plugin-serial-reaction-time": minor
+"@jspsych/plugin-serial-reaction-time-mouse": minor
+"@jspsych/plugin-sketchpad": minor
+"@jspsych/plugin-survey": minor
+"@jspsych/plugin-survey-html-form": minor
+"@jspsych/plugin-survey-likert": minor
+"@jspsych/plugin-survey-multi-choice": minor
+"@jspsych/plugin-survey-multi-select": minor
+"@jspsych/plugin-survey-text": minor
+"@jspsych/plugin-video-button-response": minor
+"@jspsych/plugin-video-keyboard-response": minor
+"@jspsych/plugin-video-slider-response": minor
+"@jspsych/plugin-virtual-chinrest": minor
+"@jspsych/plugin-visual-search-circle": minor
+"@jspsych/plugin-webgazer-calibrate": minor
+"@jspsych/plugin-webgazer-init-camera": minor
+"@jspsych/plugin-webgazer-validate": minor
+---
+
+Updated all plugins to implement new pluginInfo standard that contains version, data generated and new documentation style to match migration of docs to be integrated with the code and packages themselves"

.changeset/chilly-pans-sin.md

@@ -0,0 +1,5 @@
+---
+"@jspsych/config": major
+---
+
+Activate TypeScript's `isolatedModules` flag in the root `tsconfig.json` file. If you are facing any TypeScript errors due to `isolatedModules`, please update your code according to the error messages.

.changeset/core-rewrite.md

@@ -0,0 +1,39 @@
+---
+"jspsych": major
+---
+
+Rewrite jsPsych's core logic. The following breaking changes have been made:
+
+**Timeline Events**
+
+- `conditional_function` is no longer executed on every iteration of a looping timeline, but only once before running the first trial of the timeline. If you rely on the old behavior, move your `conditional_function` into a nested timeline instead.
+- `on_timeline_start` and `on_timeline_finish` are no longer invoked in every repetition of a timeline, but only at the beginning or at the end of the timeline, respectively. If you rely on the old behavior, move the `on_timeline_start` and `on_timeline_finish` callbacks into a nested timeline.
+
+**Timeline Variables**
+
+- The functionality of `jsPsych.timelineVariable()` has been explicitly split into two functions, `jsPsych.timelineVariable()` and `jsPsych.evaluateTimelineVariable()`. Use `jsPsych.timelineVariable()` to create a timeline variable placeholder and `jsPsych.evaluateTimelineVariable()` to retrieve a given timeline variable's current value.
+- `jsPsych.evaluateTimelineVariable()` now throws an error if a variable is not found.
+- `jsPsych.getAllTimelineVariables()` has been replaced by a trial-level `save_timeline_variables` parameter that can be used to include all or some timeline variables in a trial's result data.
+
+**Parameter Handling**
+
+- JsPsych will now throw an error when a non-array value is used for a trial parameter marked as `array: true` in the plugin's info object.
+- Parameter functions and timeline variables are no longer automatically evaluated recursively throughout the whole trial object, but only for the parameters that a plugin specifies in its `info` object. Parameter functions and timeline variables in nested objects are only evaluated if the nested object's parameters are explicitly specified using the `nested` property in the parameter description.
+
+**Progress Bar**
+
+- `jsPsych.setProgressBar(x)` has been replaced by `jsPsych.progressBar.progress = x`
+- `jsPsych.getProgressBarCompleted()` has been replaced by `jsPsych.progressBar.progress`
+- The automatic progress bar updates after every trial now, including trials in nested timelines.
+
+**Data Handling**
+
+- Timeline nodes no longer have IDs. As a consequence, the `internal_node_id` trial result property and `jsPsych.data.getDataByTimelineNode()` have been removed.
+- Unlike previously, the `save_trial_parameters` parameter can only be used to remove parameters that are specified in the plugin's info object. Other result properties will be left untouched.
+
+**Miscellaneous Changes**
+
+- `jsPsych.endExperiment()` and `jsPsych.endCurrentTimeline()` have been renamed to `jsPsych.abortExperiment()` and `jsPsych.abortCurrentTimeline()`, respectively.
+- JsPsych now internally relies on the JavaScript event loop. This means automated tests have to `await` utility functions like `pressKey()` to process the event loop.
+- The `jspsych` package no longer exports `universalPluginParameters` and the `UniversalPluginParameters` type.
+- Interaction listeners are now removed when the experiment ends.

.changeset/esbuild.md

@@ -0,0 +1,5 @@
+---
+"@jspsych/config": major
+---
+
+Migrate the build chain from TypeScript, Babel, and Terser to [esbuild](https://esbuild.github.io/). Babel and Terser are no longer included as dependencies and the Babel configuration at `@jspsych/config/babel` has been removed. The minified browser builds are only transpiled down to [ES2015](https://caniuse.com/es6) now.

.changeset/flat-tables-repair.md

@@ -0,0 +1,7 @@
+---
+"jspsych": major
+---
+
+Removed the `exclusions` option from `initJsPsych()`. The recommended replacement for this functionality is the browser-check plugin.
+
+Removed the `hardwareAPI` module from the pluginAPI. This was no longer being updated and the features were out of date.

.changeset/forty-weeks-walk.md

@@ -0,0 +1,5 @@
+---
+"jspsych": major
+---
+
+Changed the behavior of `DataColumn.mean()` to exclude `null` and `undefined` values from the calculation, as suggested in #2905

.changeset/fresh-doors-watch.md

@@ -0,0 +1,8 @@
+---
+"jspsych": major
+"@jspsych/plugin-audio-button-response": minor
+"@jspsych/plugin-audio-keyboard-response": minor
+"@jspsych/plugin-audio-slider-response": minor
+---
+
+Changed plugins to use AudioPlayer class; added tests using AudioPlayer mock; plugins now use AudioPlayerInterface.

.changeset/lucky-glasses-crash.md

@@ -0,0 +1,6 @@
+---
+"jspsych": minor
+---
+
+Added `record_data` as a parameter available for any trial. Setting `record_data: false` will prevent data from being stored in the jsPsych data object for that trial.  
+

.changeset/old-moons-lay.md

@@ -0,0 +1,5 @@
+---
+"jspsych": minor
+---
+
+Allow trial `on_finish` methods to be asynchronous, i.e. return a `Promise`. Prior to this, promises returned by `on_finish` were not awaited before proceeding with the next trial.

.changeset/pretty-lions-float.md

@@ -0,0 +1,5 @@
+---
+"jspsych": patch
+---
+
+Fix typo in randomInt error message

.changeset/proud-stingrays-wonder.md

@@ -0,0 +1,5 @@
+---
+"jspsych": major
+---
+
+Removed `max-width: 95%` CSS rule on the `.jspsych-content` `<div>`. This rule existed to address an old IE bug with flex layouts.

.changeset/rich-cups-roll.md

@@ -0,0 +1,7 @@
+---
+"@jspsych/plugin-canvas-button-response": patch
+"@jspsych/plugin-canvas-keyboard-response": patch
+"@jspsych/plugin-canvas-slider-response": patch
+---
+
+Change canvas display to `block` to fix issues when canvas is full screen.

.changeset/rotten-mails-collect.md

@@ -0,0 +1,58 @@
+---
+"jspsych": major
+"@jspsych/plugin-animation": major
+"@jspsych/plugin-audio-button-response": major
+"@jspsych/plugin-audio-keyboard-response": major
+"@jspsych/plugin-audio-slider-response": major
+"@jspsych/plugin-browser-check": major
+"@jspsych/plugin-call-function": major
+"@jspsych/plugin-canvas-button-response": major
+"@jspsych/plugin-canvas-keyboard-response": major
+"@jspsych/plugin-canvas-slider-response": major
+"@jspsych/plugin-categorize-animation": major
+"@jspsych/plugin-categorize-html": major
+"@jspsych/plugin-categorize-image": major
+"@jspsych/plugin-cloze": major
+"@jspsych/plugin-external-html": major
+"@jspsych/plugin-free-sort": major
+"@jspsych/plugin-fullscreen": major
+"@jspsych/plugin-html-audio-response": major
+"@jspsych/plugin-html-button-response": major
+"@jspsych/plugin-html-keyboard-response": major
+"@jspsych/plugin-html-slider-response": major
+"@jspsych/plugin-html-video-response": major
+"@jspsych/plugin-iat-html": major
+"@jspsych/plugin-iat-image": major
+"@jspsych/plugin-image-button-response": major
+"@jspsych/plugin-image-keyboard-response": major
+"@jspsych/plugin-image-slider-response": major
+"@jspsych/plugin-initialize-camera": major
+"@jspsych/plugin-initialize-microphone": major
+"@jspsych/plugin-instructions": major
+"@jspsych/plugin-maxdiff": major
+"@jspsych/plugin-mirror-camera": major
+"@jspsych/plugin-preload": major
+"@jspsych/plugin-reconstruction": major
+"@jspsych/plugin-resize": major
+"@jspsych/plugin-same-different-html": major
+"@jspsych/plugin-same-different-image": major
+"@jspsych/plugin-serial-reaction-time": major
+"@jspsych/plugin-serial-reaction-time-mouse": major
+"@jspsych/plugin-sketchpad": major
+"@jspsych/plugin-survey": major
+"@jspsych/plugin-survey-html-form": major
+"@jspsych/plugin-survey-likert": major
+"@jspsych/plugin-survey-multi-choice": major
+"@jspsych/plugin-survey-multi-select": major
+"@jspsych/plugin-survey-text": major
+"@jspsych/plugin-video-button-response": major
+"@jspsych/plugin-video-keyboard-response": major
+"@jspsych/plugin-video-slider-response": major
+"@jspsych/plugin-virtual-chinrest": major
+"@jspsych/plugin-visual-search-circle": major
+"@jspsych/plugin-webgazer-calibrate": major
+"@jspsych/plugin-webgazer-init-camera": major
+"@jspsych/plugin-webgazer-validate": major
+---
+
+`finishTrial()` now clears the display and any timeouts set with `pluginApi.setTimeout()`

.changeset/sour-ants-push.md

@@ -0,0 +1,5 @@
+---
+"@jspsych/plugin-instructions": minor
+---
+
+Add callback function when navigating through pages

.changeset/stupid-baboons-wait.md

@@ -0,0 +1,5 @@
+---
+"jspsych": minor
+---
+
+Allow message_progress_bar to be a function

.changeset/thick-berries-arrive.md

@@ -0,0 +1,5 @@
+---
+"@jspsych/test-utils": minor
+---
+
+clickTarget method now respects disabled tag on form elements.

.github/workflows/build.yml

@@ -32,10 +32,11 @@ jobs:
           restore-keys: |
             ${{ runner.os }}-node-${{ matrix.node }}-turbo-
 
+      - name: Check types
+        run: npm run tsc
+
       - name: Build packages
         run: npm run build
 
       - name: Run tests
-        run: npm run test -- --ci --coverage --maxWorkers=2
-        env:
-          NODE_OPTIONS: "--max-old-space-size=4096" # Increase heap size for jest
+        run: npm run test -- --ci --coverage --maxWorkers=2 --reporters=default --reporters=github-actions

.github/workflows/release.yml

@@ -35,10 +35,11 @@ jobs:
           restore-keys: |
             ${{ runner.os }}-node-20-turbo-
 
+      - name: Check types
+        run: npm run tsc
+
       - name: Run tests
         run: npm run test -- --ci --maxWorkers=2
-        env:
-          NODE_OPTIONS: "--max-old-space-size=4096" # Increase heap size for jest
 
       - name: Create Release Pull Request or Publish Packages
         id: changesets

contributors.md

@@ -61,4 +61,6 @@ The following people have contributed to the development of jsPsych by writing c
 * Rob Wilkinson - https://github.com/RobAWilkinson
 * Andy Woods - https://github.com/andytwoods
 * Reto Wyss - https://github.com/retowyss
-* Haotian Tu - https://github.com/thtTNT
+* Shaobin Jiang - https://github.com/Shaobin-Jiang
+* Haotian Tu - https://github.com/thtTNT
+

docs/demos/jspsych-audio-button-response-demo-2.html

@@ -30,7 +30,7 @@
     	stimulus: 'sound/roar.mp3',
     	choices: images,
     	prompt: "<p>Which animal made the sound?</p>",
-    	button_html: '<img src="%choice%" />'
+    	button_html: (choice)=>`<img style="cursor: pointer; margin: 10px;" src="${choice}" />`
     };
 
     timeline.push(trial);

docs/demos/jspsych-audio-button-response-demo-3.html

@@ -0,0 +1,48 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <script src="docs-demo-timeline.js"></script>
+    <script src="https://unpkg.com/[email protected]"></script>
+    <!--<script src="https://unpkg.com/@jspsych/[email protected]"></script>-->
+    <script src="../../packages/plugin-audio-button-response/dist/index.browser.js"></script>
+    <script src="https://unpkg.com/@jspsych/[email protected]"></script>
+    <script src="https://unpkg.com/@jspsych/[email protected]"></script>
+    <!--<link rel="stylesheet" href="https://unpkg.com/[email protected]/css/jspsych.css" />-->
+    <link rel="stylesheet" href="../../packages/jspsych/css/jspsych.css" />
+  </head>
+  <body></body>
+  <script>
+
+    const jsPsych = initJsPsych();
+
+    const timeline = [];
+
+    // sound source: https://www.videvo.net/sound-effect/lion-growl-angry-gene-pe931902/249942/
+    // images source: http://clipart-library.com/cartoon-animal-clipart.html
+    const images = ['img/lion.png', 'img/elephant.png', 'img/monkey.png']
+
+    const preload = {
+      type: jsPsychPreload,
+      auto_preload: true,
+      images: images
+    }
+
+    const trial = {
+    	type: jsPsychAudioButtonResponse,
+      stimulus: 'sound/telephone.mp3',
+      prompt: '<p>Which key was pressed first?</p>',
+      choices: ['1', '2', '3', '4', '5', '6', '7', '8', '9', '*', '0', '#'],
+      button_layout: 'grid',
+      grid_rows: 4,
+      grid_columns: 3
+    }
+
+    timeline.push(trial);
+
+    if (typeof jsPsych !== "undefined") {
+      jsPsych.run(generateDocsDemoTimeline(timeline, [preload]));
+    } else {
+      document.body.innerHTML = '<div style="text-align:center; margin-top:50%; transform:translate(0,-50%);">You must be online to view the plugin demo.</div>';
+    }
+  </script>
+</html>