jspsych 6.3.0 → 7.1.1

package/README.md

@@ -1,63 +1,62 @@
-![logo](http://www.jspsych.org/img/jspsych-logo.jpg)
+![jspsych logo](http://www.jspsych.org/7.0/img/jspsych-logo.jpg)
 
-jsPsych is a JavaScript library for creating behavioral experiments that run in a web browser. It provides a framework for defining experiments using a set of flexible plugins that create different kinds of events, and collect different kinds of data. By assembling these plugins together, it is possible to create a wide range of online experiments.
+jsPsych is a JavaScript framework for creating behavioral experiments that run in a web browser. 
 
-jsPsych experiments are created using the languages of the Web: HTML, CSS, and JavaScript. JavaScript is the programming language used by web browsers. It provides the most control and flexibility for creating web-based experiments, and allows for easy integration with other JavaScript libraries and server-side tools. Don't have JavaScript experience? Don't worry! jsPsych was designed to make creating online experiments as easy as possible for people without web development experience.
+Experiments in jsPsych are created using [plugins](https://www.jspsych.org/latest/overview/plugins). 
+Each plugin defines different kinds of events, like showing an image on the screen, and collects different kinds of data, like recording which key was pressed at which time. 
+By assembling different plugins together into [a timeline](https://www.jspsych.org/latest/overview/timeline), it is possible to create a wide range of online experiments. 
 
 ## What can I do with jsPsych?
 
-jsPsych comes with a number of plugins that you can use create tasks and collect data. Some plugins do general things, like present a stimulus (text, image, audio, video) and record a key press or button response along with a response time. Other plugins do more specific things, like show a set of instructions pages, run a drag-and-drop image sorting task, present a Random-Dot Kinematogram, or calibrate the WebGazer eye-tracking extension. See the documentation website for a [list of all plugins](https://www.jspsych.org/plugins/list-of-plugins/), and to see what each plugin can do.
+jsPsych comes with a number of plugins that you can use create tasks and collect data. 
+Some plugins do general things, like present a stimulus (text, image, audio, video) and record a key press or button response along with a response time. 
+Other plugins do more specific things, like show a set of instructions pages, run a drag-and-drop image sorting task, or calibrate the WebGazer eye-tracking extension. 
+See the [list of all plugins](https://www.jspsych.org/latest/plugins/list-of-plugins/) to see what each plugin can do.
 
-Often people can create their experiment by combining these plugins together. But if that's not possible for your experiment, you can also modify a plugin file or [create your own plugin](https://www.jspsych.org/overview/plugins/#creating-a-new-plugin). This gives you the flexibility to do exactly what you want, while still taking advantage of jsPsych's general experiment-building framework.
+Often people can create their experiment by combining these plugins together. 
+But if that's not possible for your experiment, you can also modify a plugin file or [create your own plugin](https://www.jspsych.org/latest/developers/plugin-development). 
+This gives you the flexibility to do exactly what you want, while still taking advantage of jsPsych's general experiment-building framework. 
+The plugin template is *extremely* flexible. If a task is possible to do in a web browser, you can almost certainly implement it as a plugin.
 
-Getting started
----------------
+## Getting started
 
-New to jsPsych? A good place to start is the basic [Hello World tutorial](https://www.jspsych.org/tutorials/hello-world/) on the jsPsych website. The [Reaction Time Task tutorial](https://www.jspsych.org/tutorials/rt-task/) is a great next step, since it covers many core topics and features. 
+jsPsych can be loaded into a project in a variety of ways, including via CDNs and through NPM. 
+You can learn more about setting up a project by following the [hello world tutorial](https://www.jspsych.org/latest/tutorials/hello-world/) on the jsPsych website. 
 
-There are also a number of [video tutorials](https://www.jspsych.org/tutorials/video-tutorials), including [Session 1 of the Moving Online Workshop](https://www.youtube.com/watch?v=BuhfsIFRFe8), which provides an overview of jsPsych suitable for brand new users. 
+Once you've got a project set up, the [reaction time task tutorial](https://www.jspsych.org/latest/tutorials/rt-task/) is a great next step, since it covers many core topics and features. 
 
-Examples
-----------
+There are also a number of [video tutorials](https://www.jspsych.org/latest/tutorials/video-tutorials) available on the website.
 
-Several example experiments and plugin demonstrations are available in the `/examples` folder. After you've downloaded the [latest release](https://github.com/jspsych/jsPsych/releases), double-click on an example HTML file to run it in your web browser, and open it with a programming-friendly text editor to see how it works.
+## Examples
 
-Documentation
--------------
+Several example experiments and plugin demonstrations are available in the `/examples` folder. 
+After you've downloaded the [latest release](https://github.com/jspsych/jsPsych/releases), double-click on an example HTML file to run it in your web browser, and open it with a programming-friendly text editor to see how it works.
 
-Documentation is available at [jspsych.org](https://www.jspsych.org/).
+## Documentation
 
-Need help?
-----------
+Documentation is available at [https://www.jspsych.org](https://www.jspsych.org/).
 
-For questions about using the library, please use the GitHub [Discussions forum](https://github.com/jspsych/jsPsych/discussions).
+## Getting help
 
-Contributing
-------------
+For questions about using the library, please use the GitHub [discussions forum](https://github.com/jspsych/jsPsych/discussions). 
+You can also browse through the history of Q&A on the forum to find related questions.
 
-Contributions to the code are welcome. Please use the [Issue tracker system](https://github.com/jspsych/jsPsych/issues) to report bugs or discuss suggestions for new features and improvements. If you would like to contribute code, [submit a Pull request](https://help.github.com/articles/using-pull-requests). See the [Contributing to jsPsych](https://www.jspsych.org/about/contributing/) documentation page for more information.
+## Contributing
 
-Citation
---------
+We :heart: contributions! 
+See the [contributing to jsPsych](https://www.jspsych.org/latest/developers/contributing/) documentation page for more information about how you can help.
+
+## 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):
 
 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
 
-Response times
---------------
-
-Wondering if jsPsych can be used for research that depends on accurate response time measurement? For most purposes, the answer is yes. Response time measurements in jsPsych (and JavaScript in general) are comparable to those taken in standard lab software like Psychophysics Toolbox and E-Prime. Response times measured in JavaScript tend to be a little bit longer (10-40ms), but have similar variance. See the following references for extensive work on this topic.
-
-* [de Leeuw, J. R., & Motz, B. A. (2016). Psychophysics in a Web browser? Comparing response times collected with JavaScript and Psychophysics Toolbox in a visual search task. *Behavior Research Methods*, *48*(1), 1-12.](http://link.springer.com/article/10.3758%2Fs13428-015-0567-2)
-* [Hilbig, B. E. (2016). Reaction time effects in lab- versus web-based research: Experimental evidence. *Behavior Research Methods*, *48*(4), 1718-1724.](http://dx.doi.org/10.3758/s13428-015-0678-9)
-* [Pinet, S., Zielinski, C., Mathôt, S. et al. (2017). Measuring sequences of keystrokes with jsPsych: Reliability of response times and interkeystroke intervals.  *Behavior Research Methods*, *49*(3), 1163-1176.](http://link.springer.com/article/10.3758/s13428-016-0776-3)
-* [Reimers, S., & Stewart, N. (2015). Presentation and response time accuracy in Adobe Flash and HTML5/JavaScript Web experiments. *Behavior Research Methods*, *47*(2), 309-327.](http://link.springer.com/article/10.3758%2Fs13428-014-0471-1)
-
+## Contributors
 
-Credits
--------
+jsPsych is open source project with [numerous contributors](https://github.com/jspsych/jsPsych/graphs/contributors). 
+The project is currently managed by the core team of Josh de Leeuw ([@jodeleeuw](https://github.com/jodeleeuw)), Becky Gilbert ([@becky-gilbert](https://github.com/becky-gilbert)), and Björn Luchterhandt ([@bjoluc](https://github.com/bjoluc)).
 
-jsPsych was created by Josh de Leeuw ([@jodeleeuw](https://github.com/jodeleeuw)).
+jsPsych was created by [Josh de Leeuw](http://www.twitter.com/joshdeleeuw).
 
-We're grateful for the many [contributors](https://github.com/jspsych/jsPsych/blob/master/contributors.md) to the library, and for the generous support from a [Mozilla Open Source Support (MOSS)](https://www.mozilla.org/en-US/moss/) award. Thank you!
+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.

package/css/jspsych.css

@@ -5,45 +5,45 @@
  * experiments look polished without any additional styles.
  */
 
- @import url(https://fonts.googleapis.com/css?family=Open+Sans:400italic,700italic,400,700);
+@import url(https://fonts.googleapis.com/css?family=Open+Sans:400italic,700italic,400,700);
 
 /* Container holding jsPsych content */
 
- .jspsych-display-element {
-   display: flex;
-   flex-direction: column;
-   overflow-y: auto;
- }
-
- .jspsych-display-element:focus {
-   outline: none;
- }
-
- .jspsych-content-wrapper {
-   display: flex;
-   margin: auto;
-   flex: 1 1 100%;
-   width: 100%;
- }
-
- .jspsych-content {
-   max-width: 95%; /* this is mainly an IE 10-11 fix */
-   text-align: center;
-   margin: auto; /* this is for overflowing content */
- }
-
- .jspsych-top {
-   align-items: flex-start;
- }
-
- .jspsych-middle {
-   align-items: center;
- }
+.jspsych-display-element {
+  display: flex;
+  flex-direction: column;
+  overflow-y: auto;
+}
+
+.jspsych-display-element:focus {
+  outline: none;
+}
+
+.jspsych-content-wrapper {
+  display: flex;
+  margin: auto;
+  flex: 1 1 100%;
+  width: 100%;
+}
+
+.jspsych-content {
+  max-width: 95%; /* this is mainly an IE 10-11 fix */
+  text-align: center;
+  margin: auto; /* this is for overflowing content */
+}
+
+.jspsych-top {
+  align-items: flex-start;
+}
+
+.jspsych-middle {
+  align-items: center;
+}
 
 /* fonts and type */
 
 .jspsych-display-element {
-  font-family: 'Open Sans', 'Arial', sans-serif;
+  font-family: "Open Sans", "Arial", sans-serif;
   font-size: 18px;
   line-height: 1.6em;
 }
@@ -51,7 +51,7 @@
 /* Form elements like input fields and buttons */
 
 .jspsych-display-element input[type="text"] {
-  font-family: 'Open Sans', 'Arial', sans-serif;
+  font-family: "Open Sans", "Arial", sans-serif;
   font-size: 14px;
 }
 
@@ -62,7 +62,7 @@
   margin: 0px;
   font-size: 14px;
   font-weight: 400;
-  font-family: 'Open Sans', 'Arial', sans-serif;
+  font-family: "Open Sans", "Arial", sans-serif;
   cursor: pointer;
   line-height: 1.4;
   text-align: center;
@@ -86,7 +86,7 @@
 
 .jspsych-btn:active {
   background-color: #ddd;
-  border-color:#000000;
+  border-color: #000000;
 }
 
 .jspsych-btn:disabled {
@@ -100,10 +100,10 @@
 
 .jspsych-slider {
   appearance: none;
-  -webkit-appearance: none; 
+  -webkit-appearance: none;
   -moz-appearance: none;
-  width: 100%; 
-  background: transparent; 
+  width: 100%;
+  background: transparent;
 }
 .jspsych-slider:focus {
   outline: none;
@@ -192,7 +192,7 @@
   height: 14px;
   display: inline-block;
   vertical-align: middle;
-  box-shadow: inset 0 1px 2px rgba(0,0,0,0.1);
+  box-shadow: inset 0 1px 2px rgba(0, 0, 0, 0.1);
 }
 #jspsych-progressbar-inner {
   background-color: #aaa;

package/dist/JsPsych.d.ts

@@ -0,0 +1,112 @@
+import { JsPsychData } from "./modules/data";
+import { PluginAPI } from "./modules/plugin-api";
+import * as randomization from "./modules/randomization";
+import * as turk from "./modules/turk";
+import * as utils from "./modules/utils";
+export declare class JsPsych {
+    extensions: any;
+    turk: typeof turk;
+    randomization: typeof randomization;
+    utils: typeof utils;
+    data: JsPsychData;
+    pluginAPI: PluginAPI;
+    version(): any;
+    /**
+     * options
+     */
+    private opts;
+    /**
+     * experiment timeline
+     */
+    private timeline;
+    private timelineDescription;
+    private global_trial_index;
+    private current_trial;
+    private current_trial_finished;
+    private DOM_container;
+    private DOM_target;
+    /**
+     * time that the experiment began
+     */
+    private exp_start_time;
+    /**
+     * is the experiment paused?
+     */
+    private paused;
+    private waiting;
+    /**
+     * is the page retrieved directly via file:// protocol (true) or hosted on a server (false)?
+     */
+    private file_protocol;
+    /**
+     * Promise that is resolved when `finishExperiment()` is called
+     */
+    private finished;
+    private resolveFinishedPromise;
+    /**
+     * is the experiment running in `simulate()` mode
+     */
+    private simulation_mode;
+    /**
+     * simulation options passed in via `simulate()`
+     */
+    private simulation_options;
+    webaudio_context: AudioContext;
+    internal: {
+        /**
+         * this flag is used to determine whether we are in a scope where
+         * jsPsych.timelineVariable() should be executed immediately or
+         * whether it should return a function to access the variable later.
+         *
+         **/
+        call_immediate: boolean;
+    };
+    constructor(options?: any);
+    /**
+     * Starts an experiment using the provided timeline and returns a promise that is resolved when
+     * the experiment is finished.
+     *
+     * @param timeline The timeline to be run
+     */
+    run(timeline: any[]): Promise<void>;
+    simulate(timeline: any[], simulation_mode?: "data-only" | "visual", simulation_options?: {}): Promise<void>;
+    getProgress(): {
+        total_trials: number;
+        current_trial_global: number;
+        percent_complete: number;
+    };
+    getStartTime(): any;
+    getTotalTime(): number;
+    getDisplayElement(): HTMLElement;
+    getDisplayContainerElement(): HTMLElement;
+    finishTrial(data?: {}): void;
+    endExperiment(end_message?: string, data?: {}): void;
+    endCurrentTimeline(): void;
+    getCurrentTrial(): any;
+    getInitSettings(): any;
+    getCurrentTimelineNodeID(): any;
+    timelineVariable(varname: string, immediate?: boolean): any;
+    getAllTimelineVariables(): any;
+    addNodeToEndOfTimeline(new_timeline: any, preload_callback?: any): void;
+    pauseExperiment(): void;
+    resumeExperiment(): void;
+    loadFail(message: any): void;
+    getSafeModeStatus(): boolean;
+    getTimeline(): any[];
+    private prepareDom;
+    private loadExtensions;
+    private startExperiment;
+    private finishExperiment;
+    private nextTrial;
+    private doTrial;
+    private evaluateTimelineVariables;
+    private evaluateFunctionParameters;
+    private replaceFunctionsWithValues;
+    private setDefaultValues;
+    private checkExclusions;
+    private drawProgressBar;
+    private updateProgressBar;
+    private progress_bar_amount;
+    setProgressBar(proportion_complete: any): void;
+    getProgressBarCompleted(): number;
+}

package/dist/TimelineNode.d.ts

@@ -0,0 +1,34 @@
+import { JsPsych } from "./JsPsych";
+export declare class TimelineNode {
+    private jsPsych;
+    relative_id: any;
+    parent_node: any;
+    trial_parameters: any;
+    timeline_parameters: any;
+    node_trial_data: any;
+    progress: any;
+    end_message?: string;
+    constructor(jsPsych: JsPsych, parameters: any, parent?: any, relativeID?: any);
+    trial(): any;
+    markCurrentTrialComplete(): void;
+    nextRepetiton(): void;
+    setTimelineVariablesOrder(): void;
+    nextSet(): void;
+    advance(): any;
+    isComplete(): any;
+    getTimelineVariableValue(variable_name: string): any;
+    findTimelineVariable(variable_name: any): any;
+    timelineVariable(variable_name: string): any;
+    allTimelineVariables(): any;
+    allTimelineVariablesNames(so_far?: any[]): any;
+    length(): number;
+    percentComplete(): number;
+    reset(): void;
+    end(): void;
+    endActiveNode(): void;
+    ID(): string;
+    activeID(): any;
+    generatedData(): import("./modules/data/DataCollection").DataCollection;
+    trialsOfType(type: any): any;
+    insert(parameters: any): void;
+}