jspsych 6.2.0 → 7.1.0

package/README.md

@@ -1,48 +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. jsPsych provides a framework for defining experiments using a set of flexible plugins that create different kinds of tasks a subject could complete during an experiment. By assembling these different plugins together it is possible to create many different types of experiments.
+jsPsych is a JavaScript framework for creating behavioral experiments that run in a web browser. 
 
-Examples
-----------
+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. 
 
-Several example experiments and plugin demonstrations are available in the `/examples` folder.
+## What can I do with jsPsych?
 
-Documentation
--------------
+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.
 
-Documentation is available at [docs.jspsych.org](http://docs.jspsych.org).
+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.
 
-Need help?
-----------
+## Getting started
 
-For questions about using the library, please use the [Discussions forum](https://github.com/jspsych/jsPsych/discussions).
+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. 
 
-Contributing
-------------
+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. 
 
-Contributions to the code are welcome. Please use the [Issue tracker system](https://github.com/jodeleeuw/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).
+There are also a number of [video tutorials](https://www.jspsych.org/latest/tutorials/video-tutorials) available on the website.
 
-Citation
---------
+## Examples
 
-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):
+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.
 
-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
+## Documentation
+
+Documentation is available at [https://www.jspsych.org](https://www.jspsych.org/).
+
+## Getting help
+
+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.
 
-Response times
---------------
+## Contributing
 
-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.
+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.
 
-* [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)
+## 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
 
+## 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).
 
-There have been many [contributors](https://github.com/jodeleeuw/jsPsych/blob/master/contributors.md) to the library. 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;
+}