Merge pull request #2858 from jspsych/core-rewrite

Core rewrite

.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/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/modern-experts-work.md

@@ -0,0 +1,5 @@
+---
+"@jspsych/config": major
+---
+
+Upgrade Jest to v29 and replace ts-jest with the more performant Sucrase Jest plugin. As a consequence, Jest does no longer type-check code. Please check Jest's [upgrade guide](https://jestjs.io/docs/upgrading-to-jest29) for instructions on updating your tests.

.changeset/node.md

@@ -0,0 +1,5 @@
+---
+"@jspsych/config": major
+---
+
+Require at least Node.js v18 and npm v8

.changeset/silly-cycles-sneeze.md

@@ -0,0 +1,5 @@
+---
+"@jspsych/test-utils": minor
+---
+
+Call `flushPromises()` in event-dispatching utility functions to simplify tests involving jsPsych 8

.github/workflows/build.yml

@@ -9,32 +9,32 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        node: [14, 16]
+        node: [18]
 
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
 
       - name: Setup Node.js ${{ matrix.node }}
-        uses: actions/setup-node@v2
+        uses: actions/setup-node@v3
         with:
           node-version: ${{ matrix.node }}
           cache: npm
 
-      - name: Install npm@v7
-        run: npm install -g npm@7
-
       - name: Install dependencies
         run: npm ci
 
-      # Running this after `npm ci` because `npm ci` removes `node_modules`: 
+      # Running this after `npm ci` because `npm ci` removes `node_modules`:
       - name: Download Turborepo cache
-        uses: actions/cache@v2
+        uses: actions/cache@v3
         with:
           path: node_modules/.cache/turbo
           key: ${{ runner.os }}-node-${{ matrix.node }}-turbo-${{ hashFiles('node_modules/.cache/turbo') }}
           restore-keys: |
             ${{ runner.os }}-node-${{ matrix.node }}-turbo-
 
+      - name: Check types
+        run: npm run tsc
+
       - name: Build packages
         run: npm run build
 
@@ -43,9 +43,8 @@ jobs:
       #   run: npm run lint
 
       - 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
+
       # TODO setup codecov or coveralls
       # - name: Upload coverage to Codecov
       #   uses: codecov/codecov-action@v1

.github/workflows/release.yml

@@ -16,29 +16,30 @@ jobs:
     name: Release
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
 
-      - name: Setup Node.js 16
-        uses: actions/setup-node@v2
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
         with:
-          node-version: 16
+          node-version: 18
           cache: npm
 
       - name: Install dependencies
         run: npm ci
 
       - name: Download Turborepo cache
-        uses: actions/cache@v2
+        uses: actions/cache@v3
         with:
           path: node_modules/.cache/turbo
-          key: ${{ runner.os }}-node-16-turbo-${{ hashFiles('node_modules/.cache/turbo') }}
+          key: ${{ runner.os }}-node-18-turbo-${{ hashFiles('node_modules/.cache/turbo') }}
           restore-keys: |
-            ${{ runner.os }}-node-16-turbo-
+            ${{ runner.os }}-node-18-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

CITATION.cff

@@ -0,0 +1,47 @@
+cff-version: "1.2.0"
+authors:
+- family-names: Leeuw
+  given-names: Joshua R.
+  name-particle: de
+  orcid: "https://orcid.org/0000-0003-4815-2364"
+- family-names: Gilbert
+  given-names: Rebecca A.
+  orcid: "https://orcid.org/0000-0003-4574-7792"
+- family-names: Luchterhandt
+  given-names: Björn
+  orcid: "https://orcid.org/0000-0002-9225-2787"
+contact:
+- family-names: Leeuw
+  given-names: Joshua R.
+  name-particle: de
+  orcid: "https://orcid.org/0000-0003-4815-2364"
+doi: 10.5281/zenodo.7702307
+message: If you use this software, please cite our article in the
+  Journal of Open Source Software.
+preferred-citation:
+  authors:
+  - family-names: Leeuw
+    given-names: Joshua R.
+    name-particle: de
+    orcid: "https://orcid.org/0000-0003-4815-2364"
+  - family-names: Gilbert
+    given-names: Rebecca A.
+    orcid: "https://orcid.org/0000-0003-4574-7792"
+  - family-names: Luchterhandt
+    given-names: Björn
+    orcid: "https://orcid.org/0000-0002-9225-2787"
+  date-published: 2023-05-11
+  doi: 10.21105/joss.05351
+  issn: 2475-9066
+  issue: 85
+  journal: Journal of Open Source Software
+  publisher:
+    name: Open Journals
+  start: 5351
+  title: "jsPsych: Enabling an Open-Source Collaborative Ecosystem of
+    Behavioral Experiments"
+  type: article
+  url: "https://joss.theoj.org/papers/10.21105/joss.05351"
+  volume: 8
+title: "jsPsych: Enabling an Open-Source Collaborative Ecosystem of
+  Behavioral Experiments"

README.md

@@ -48,9 +48,15 @@ See the [contributing to jsPsych](https://www.jspsych.org/latest/developers/cont
 
 ## Citation
 
-If you use this library in academic work, please cite the [paper that describes jsPsych](http://link.springer.com/article/10.3758%2Fs13428-014-0458-y):
+If you use this library in academic work, the preferred citation is:
 
-de Leeuw, J.R. (2015). jsPsych: A JavaScript library for creating behavioral experiments in a Web browser. *Behavior Research Methods*, _47_(1), 1-12. doi:10.3758/s13428-014-0458-y
+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://joss.theoj.org/papers/10.21105/joss.05351](https://joss.theoj.org/papers/10.21105/joss.05351).
+
+This paper is an updated description of jsPsych and includes all current core team members. It replaces the earlier paper that described jsPsych:
+
+de Leeuw, J.R. (2015). jsPsych: A JavaScript library for creating behavioral experiments in a Web browser. *Behavior Research Methods*, _47_(1), 1-12. doi:[10.3758/s13428-014-0458-y](http://link.springer.com/article/10.3758%2Fs13428-014-0458-y)
+
+Citations help us demonstrate that this library is used and valued, which allows us to continue working on it.
 
 ## Contributors
 
@@ -59,4 +65,4 @@ The project is currently managed by the core team of Josh de Leeuw ([@jodeleeuw]
 
 jsPsych was created by [Josh de Leeuw](http://www.twitter.com/joshdeleeuw).
 
-We're also grateful for the generous support from a [Mozilla Open Source Support award](https://www.mozilla.org/en-US/moss/), which funded development of the library from 2020-2021.
+We're also grateful for the generous support from a [Mozilla Open Source Support award](https://www.mozilla.org/en-US/moss/), which funded development of the library from 2020-2022.

docs/about/about.md

@@ -6,6 +6,12 @@ jsPsych was created by [Josh de Leeuw :fontawesome-brands-twitter:](http://www.t
 
 ### Citation
 
-If you use jsPsych please cite the following paper.
+If you use this library in academic work, the preferred citation is:
 
-de Leeuw, J. R. (2015). jsPsych: A JavaScript library for creating behavioral experiments in a web browser. _Behavior Research Methods_, _47_(1), 1-12. [doi:10.3758/s13428-014-0458-y](https://doi.org/10.3758/s13428-014-0458-y).
+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://joss.theoj.org/papers/10.21105/joss.05351](https://joss.theoj.org/papers/10.21105/joss.05351).
+
+This paper is an updated description of jsPsych and includes all current core team members. It replaces the earlier paper that described jsPsych:
+
+de Leeuw, J.R. (2015). jsPsych: A JavaScript library for creating behavioral experiments in a Web browser. *Behavior Research Methods*, _47_(1), 1-12. doi:[10.3758/s13428-014-0458-y](http://link.springer.com/article/10.3758%2Fs13428-014-0458-y)
+
+Citations help us demonstrate that this library is used and valued, which allows us to continue working on it.

docs/demos/eye-tracking-with-webgazer.html

@@ -1,7 +1,7 @@
 <!DOCTYPE html>
 <html>
   <head>
-    <script src="https://unpkg.com/[email protected].1"></script>
+    <script src="https://unpkg.com/[email protected].3"></script>
     <script src="https://unpkg.com/@jspsych/[email protected]"></script>
     <script src="https://unpkg.com/@jspsych/[email protected]"></script>
     <script src="https://unpkg.com/@jspsych/[email protected]"></script>
@@ -13,7 +13,7 @@
     <script src="https://unpkg.com/@jspsych/[email protected]"></script>
     <link
       rel="stylesheet"
-      href="https://unpkg.com/[email protected].1/css/jspsych.css"
+      href="https://unpkg.com/[email protected].3/css/jspsych.css"
     />
     <link rel="stylesheet" href="docs-demo.css" type="text/css">
   </head>

docs/demos/jspsych-animation-demo.html

@@ -2,11 +2,11 @@
 <html>
   <head>
     <script src="docs-demo-timeline.js"></script>
-    <script src="https://unpkg.com/[email protected].1"></script>
+    <script src="https://unpkg.com/[email protected].3"></script>
     <script src="https://unpkg.com/@jspsych/[email protected]"></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].1/css/jspsych.css" />
+    <link rel="stylesheet" href="https://unpkg.com/[email protected].3/css/jspsych.css" />
     <style>
       #jspsych-animation-image {
         height: 80% !important;

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

@@ -2,11 +2,11 @@
 <html>
   <head>
     <script src="docs-demo-timeline.js"></script>
-    <script src="https://unpkg.com/[email protected].1"></script>
+    <script src="https://unpkg.com/[email protected].3"></script>
     <script src="https://unpkg.com/@jspsych/[email protected]"></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].1/css/jspsych.css" />
+    <link rel="stylesheet" href="https://unpkg.com/[email protected].3/css/jspsych.css" />
   </head>
   <body></body>
   <script>

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

@@ -2,11 +2,12 @@
 <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="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].1/css/jspsych.css" />
+    <link rel="stylesheet" href="https://unpkg.com/[email protected].3/css/jspsych.css" />
   </head>
   <body></body>
   <script>
@@ -30,7 +31,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);