jspsych 7.3.4 → 8.0.0

package/src/ProgressBar.spec.ts

@@ -0,0 +1,60 @@
+import { ProgressBar } from "./ProgressBar";
+
+describe("ProgressBar", () => {
+  let containerElement: HTMLDivElement;
+  let progressBar: ProgressBar;
+
+  beforeEach(() => {
+    containerElement = document.createElement("div");
+    progressBar = new ProgressBar(containerElement, "My message");
+  });
+
+  it("sets up proper HTML markup when created", () => {
+    expect(containerElement.innerHTML).toMatchInlineSnapshot(
+      '"<span>My message</span><div id="jspsych-progressbar-outer"><div id="jspsych-progressbar-inner" style="width: 0%;"></div></div>"'
+    );
+  });
+
+  describe("progress", () => {
+    it("updates the bar width accordingly", () => {
+      expect(progressBar.progress).toEqual(0);
+      expect(containerElement.innerHTML).toContain('style="width: 0%;"');
+      progressBar.progress = 0.5;
+      expect(progressBar.progress).toEqual(0.5);
+      expect(containerElement.innerHTML).toContain('style="width: 50%;"');
+
+      progressBar.progress = 1;
+      expect(progressBar.progress).toEqual(1);
+      expect(containerElement.innerHTML).toContain('style="width: 100%;"');
+    });
+
+    it("errors if an invalid progress value is provided", () => {
+      expect(() => {
+        // @ts-expect-error
+        progressBar.progress = "0";
+      }).toThrowErrorMatchingInlineSnapshot(
+        '"jsPsych.progressBar.progress must be a number between 0 and 1"'
+      );
+      expect(() => {
+        progressBar.progress = -0.1;
+      }).toThrowErrorMatchingInlineSnapshot(
+        '"jsPsych.progressBar.progress must be a number between 0 and 1"'
+      );
+      expect(() => (progressBar.progress = 1.1)).toThrowErrorMatchingInlineSnapshot(
+        '"jsPsych.progressBar.progress must be a number between 0 and 1"'
+      );
+    });
+
+    it("should work when message is a function", () => {
+      // Override default container element and progress bar
+      containerElement = document.createElement("div");
+      progressBar = new ProgressBar(containerElement, (progress: number) => String(progress));
+      let messageSpan: HTMLSpanElement = containerElement.querySelector("span");
+
+      expect(messageSpan.innerHTML).toEqual("0");
+
+      progressBar.progress = 0.5;
+      expect(messageSpan.innerHTML).toEqual("0.5");
+    });
+  });
+});

package/src/ProgressBar.ts

@@ -0,0 +1,60 @@
+/**
+ * Maintains a visual progress bar using HTML and CSS
+ */
+export class ProgressBar {
+  constructor(
+    private readonly containerElement: HTMLDivElement,
+    private readonly message: string | ((progress: number) => string)
+  ) {
+    this.setupElements();
+  }
+
+  private _progress = 0;
+
+  private innerDiv: HTMLDivElement;
+  private messageSpan: HTMLSpanElement;
+
+  /** Adds the progress bar HTML code into `this.containerElement` */
+  private setupElements() {
+    this.messageSpan = document.createElement("span");
+
+    this.innerDiv = document.createElement("div");
+    this.innerDiv.id = "jspsych-progressbar-inner";
+    this.update();
+
+    const outerDiv = document.createElement("div");
+    outerDiv.id = "jspsych-progressbar-outer";
+    outerDiv.appendChild(this.innerDiv);
+
+    this.containerElement.appendChild(this.messageSpan);
+    this.containerElement.appendChild(outerDiv);
+  }
+
+  /** Updates the progress bar according to `this.progress` */
+  private update() {
+    this.innerDiv.style.width = this._progress * 100 + "%";
+
+    if (typeof this.message === "function") {
+      this.messageSpan.innerHTML = this.message(this._progress);
+    } else {
+      this.messageSpan.innerHTML = this.message;
+    }
+  }
+
+  /**
+   * The bar's current position as a number in the closed interval [0, 1]. Set this to update the
+   * progress bar accordingly.
+   */
+  set progress(progress: number) {
+    if (typeof progress !== "number" || progress < 0 || progress > 1) {
+      throw new Error("jsPsych.progressBar.progress must be a number between 0 and 1");
+    }
+
+    this._progress = progress;
+    this.update();
+  }
+
+  get progress() {
+    return this._progress;
+  }
+}

package/src/index.scss

@@ -30,7 +30,6 @@
 }
 
 .jspsych-content {
-  max-width: 95%; /* this is mainly an IE 10-11 fix */
   text-align: center;
   margin: auto; /* this is for overflowing content */
 }
@@ -58,11 +57,25 @@
   font-size: 14px;
 }
 
-/* borrowing Bootstrap style for btn elements, but combining styles a bit */
+/* Buttons and Button Groups */
+
+.jspsych-btn-group-flex {
+  display: flex;
+  justify-content: center;
+}
+
+.jspsych-btn-group-grid {
+  display: grid;
+  grid-auto-columns: max-content;
+  max-width: fit-content;
+  margin-right: auto;
+  margin-left: auto;
+}
+
 .jspsych-btn {
   display: inline-block;
-  padding: 6px 12px;
-  margin: 0px;
+  padding: 8px 12px;
+  margin: 0.75em;
   font-size: 14px;
   font-weight: 400;
   font-family: "Open Sans", "Arial", sans-serif;
@@ -108,10 +121,11 @@
   width: 100%;
   background: transparent;
 }
+
 .jspsych-slider:focus {
   outline: none;
 }
-/* track */
+
 .jspsych-slider::-webkit-slider-runnable-track {
   appearance: none;
   -webkit-appearance: none;
@@ -123,6 +137,7 @@
   border-radius: 2px;
   border: 1px solid #aaa;
 }
+
 .jspsych-slider::-moz-range-track {
   appearance: none;
   width: 100%;
@@ -133,6 +148,7 @@
   border-radius: 2px;
   border: 1px solid #aaa;
 }
+
 .jspsych-slider::-ms-track {
   appearance: none;
   width: 99%;
@@ -143,7 +159,7 @@
   border-radius: 2px;
   border: 1px solid #aaa;
 }
-/* thumb */
+
 .jspsych-slider::-webkit-slider-thumb {
   border: 1px solid #666;
   height: 24px;
@@ -154,6 +170,7 @@
   -webkit-appearance: none;
   margin-top: -9px;
 }
+
 .jspsych-slider::-moz-range-thumb {
   border: 1px solid #666;
   height: 24px;
@@ -162,6 +179,7 @@
   background: #ffffff;
   cursor: pointer;
 }
+
 .jspsych-slider::-ms-thumb {
   border: 1px solid #666;
   height: 20px;
@@ -172,7 +190,7 @@
   margin-top: -2px;
 }
 
-/* jsPsych progress bar */
+/* progress bar */
 
 #jspsych-progressbar-container {
   color: #555;
@@ -184,10 +202,12 @@
   width: 100%;
   line-height: 1em;
 }
+
 #jspsych-progressbar-container span {
   font-size: 14px;
   padding-right: 14px;
 }
+
 #jspsych-progressbar-outer {
   background-color: #eee;
   width: 50%;
@@ -197,13 +217,14 @@
   vertical-align: middle;
   box-shadow: inset 0 1px 2px rgba(0, 0, 0, 0.1);
 }
+
 #jspsych-progressbar-inner {
   background-color: #aaa;
   width: 0%;
   height: 100%;
 }
 
-/* Control appearance of jsPsych.data.displayData() */
+/* Appearance of jsPsych.data.displayData() */
 #jspsych-data-display {
   text-align: left;
 }

package/src/index.ts

@@ -62,12 +62,7 @@ export function initJsPsych(options?) {
 }
 
 export { JsPsych } from "./JsPsych";
-export {
-  JsPsychPlugin,
-  PluginInfo,
-  TrialType,
-  ParameterType,
-  universalPluginParameters,
-  UniversalPluginParameters,
-} from "./modules/plugins";
-export { JsPsychExtension, JsPsychExtensionInfo } from "./modules/extensions";
+export type { JsPsychPlugin, PluginInfo, TrialType } from "./modules/plugins";
+export { ParameterType } from "./modules/plugins";
+export type { JsPsychExtension, JsPsychExtensionInfo } from "./modules/extensions";
+export { DataCollection } from "./modules/data/DataCollection";

package/src/modules/data/DataCollection.ts

@@ -89,7 +89,7 @@ export class DataCollection {
   }
 
   addToLast(properties) {
-    if (this.trials.length != 0) {
+    if (this.trials.length > 0) {
       Object.assign(this.trials[this.trials.length - 1], properties);
     }
     return this;

package/src/modules/data/DataColumn.ts

@@ -10,7 +10,18 @@ export class DataColumn {
   }
 
   mean() {
-    return this.sum() / this.count();
+    let sum = 0;
+    let count = 0;
+    for (const value of this.values) {
+      if (typeof value !== "undefined" && value !== null) {
+        sum += value;
+        count++;
+      }
+    }
+    if (count === 0) {
+      return undefined;
+    }
+    return sum / count;
   }
 
   median() {

package/src/modules/data/index.ts

@@ -1,106 +1,104 @@
-import { JsPsych } from "../../JsPsych";
+import { TrialResult } from "../../timeline";
+import { Trial } from "../../timeline/Trial";
 import { DataCollection } from "./DataCollection";
 import { getQueryString } from "./utils";
 
+export type InteractionEvent = "blur" | "focus" | "fullscreenenter" | "fullscreenexit";
+
+export interface InteractionRecord {
+  event: InteractionEvent;
+  trial: number;
+  time: number;
+}
+
+/**
+ * Functions and options needed by the `JsPsychData` module
+ */
+export interface JsPsychDataDependencies {
+  /**
+   * Returns progress information for interaction records.
+   */
+  getProgress: () => { trial: number; time: number };
+
+  onInteractionRecordAdded: (record: InteractionRecord) => void;
+
+  getDisplayElement: () => HTMLElement;
+}
+
 export class JsPsychData {
-  // data storage object
-  private allData: DataCollection;
+  private results: DataCollection;
+  private resultToTrialMap: WeakMap<TrialResult, Trial>;
 
-  // browser interaction event data
-  private interactionData: DataCollection;
+  /** Browser interaction event data */
+  private interactionRecords: DataCollection;
 
-  // data properties for all trials
+  /** Data properties for all trials */
   private dataProperties = {};
 
   // cache the query_string
   private query_string;
 
-  constructor(private jsPsych: JsPsych) {
+  constructor(private dependencies: JsPsychDataDependencies) {
     this.reset();
   }
 
   reset() {
-    this.allData = new DataCollection();
-    this.interactionData = new DataCollection();
+    this.results = new DataCollection();
+    this.resultToTrialMap = new WeakMap<TrialResult, Trial>();
+    this.interactionRecords = new DataCollection();
   }
 
   get() {
-    return this.allData;
+    return this.results;
   }
 
   getInteractionData() {
-    return this.interactionData;
+    return this.interactionRecords;
   }
 
-  write(data_object) {
-    const progress = this.jsPsych.getProgress();
-    const trial = this.jsPsych.getCurrentTrial();
-
-    //var trial_opt_data = typeof trial.data == 'function' ? trial.data() : trial.data;
-
-    const default_data = {
-      trial_type: trial.type.info.name,
-      trial_index: progress.current_trial_global,
-      time_elapsed: this.jsPsych.getTotalTime(),
-      internal_node_id: this.jsPsych.getCurrentTimelineNodeID(),
-    };
-
-    this.allData.push({
-      ...data_object,
-      ...trial.data,
-      ...default_data,
-      ...this.dataProperties,
-    });
+  write(trial: Trial) {
+    const result = trial.getResult();
+    Object.assign(result, this.dataProperties);
+    this.results.push(result);
+    this.resultToTrialMap.set(result, trial);
   }
 
   addProperties(properties) {
     // first, add the properties to all data that's already stored
-    this.allData.addToAll(properties);
+    this.results.addToAll(properties);
 
     // now add to list so that it gets appended to all future data
     this.dataProperties = Object.assign({}, this.dataProperties, properties);
   }
 
   addDataToLastTrial(data) {
-    this.allData.addToLast(data);
-  }
-
-  getDataByTimelineNode(node_id) {
-    return this.allData.filterCustom(
-      (x) => x.internal_node_id.slice(0, node_id.length) === node_id
-    );
+    this.results.addToLast(data);
   }
 
   getLastTrialData() {
-    return this.allData.top();
+    return this.results.top();
   }
 
   getLastTimelineData() {
-    const lasttrial = this.getLastTrialData();
-    const node_id = lasttrial.select("internal_node_id").values[0];
-    if (typeof node_id === "undefined") {
-      return new DataCollection();
-    } else {
-      const parent_node_id = node_id.substr(0, node_id.lastIndexOf("-"));
-      const lastnodedata = this.getDataByTimelineNode(parent_node_id);
-      return lastnodedata;
-    }
+    const lastResult = this.getLastTrialData().values()[0];
+
+    return new DataCollection(
+      lastResult ? this.resultToTrialMap.get(lastResult).parent.getResults() : []
+    );
   }
 
   displayData(format = "json") {
     format = format.toLowerCase();
-    if (format != "json" && format != "csv") {
+    if (format !== "json" && format !== "csv") {
       console.log("Invalid format declared for displayData function. Using json as default.");
       format = "json";
     }
 
-    const data_string = format === "json" ? this.allData.json(true) : this.allData.csv();
+    const dataContainer = document.createElement("pre");
+    dataContainer.id = "jspsych-data-display";
+    dataContainer.textContent = format === "json" ? this.results.json(true) : this.results.csv();
 
-    const display_element = this.jsPsych.getDisplayElement();
-
-    display_element.innerHTML = '<pre id="jspsych-data-display"></pre>';
-
-    document.getElementById("jspsych-data-display").textContent = data_string;
+    this.dependencies.getDisplayElement().replaceChildren(dataContainer);
   }
 
   urlVariables() {
@@ -114,61 +112,52 @@ export class JsPsychData {
     return this.urlVariables()[whichvar];
   }
 
-  createInteractionListeners() {
-    // blur event capture
-    window.addEventListener("blur", () => {
-      const data = {
-        event: "blur",
-        trial: this.jsPsych.getProgress().current_trial_global,
-        time: this.jsPsych.getTotalTime(),
-      };
-      this.interactionData.push(data);
-      this.jsPsych.getInitSettings().on_interaction_data_update(data);
-    });
-
-    // focus event capture
-    window.addEventListener("focus", () => {
-      const data = {
-        event: "focus",
-        trial: this.jsPsych.getProgress().current_trial_global,
-        time: this.jsPsych.getTotalTime(),
-      };
-      this.interactionData.push(data);
-      this.jsPsych.getInitSettings().on_interaction_data_update(data);
-    });
-
-    // fullscreen change capture
-    const fullscreenchange = () => {
-      const data = {
-        event:
-          // @ts-expect-error
-          document.isFullScreen ||
+  private addInteractionRecord(event: InteractionEvent) {
+    const record: InteractionRecord = { event, ...this.dependencies.getProgress() };
+    this.interactionRecords.push(record);
+    this.dependencies.onInteractionRecordAdded(record);
+  }
+
+  private interactionListeners = {
+    blur: () => {
+      this.addInteractionRecord("blur");
+    },
+    focus: () => {
+      this.addInteractionRecord("focus");
+    },
+    fullscreenchange: () => {
+      this.addInteractionRecord(
+        // @ts-expect-error
+        document.isFullScreen ||
           // @ts-expect-error
           document.webkitIsFullScreen ||
           // @ts-expect-error
           document.mozIsFullScreen ||
           document.fullscreenElement
-            ? "fullscreenenter"
-            : "fullscreenexit",
-        trial: this.jsPsych.getProgress().current_trial_global,
-        time: this.jsPsych.getTotalTime(),
-      };
-      this.interactionData.push(data);
-      this.jsPsych.getInitSettings().on_interaction_data_update(data);
-    };
-
-    document.addEventListener("fullscreenchange", fullscreenchange);
-    document.addEventListener("mozfullscreenchange", fullscreenchange);
-    document.addEventListener("webkitfullscreenchange", fullscreenchange);
-  }
+          ? "fullscreenenter"
+          : "fullscreenexit"
+      );
+    },
+  };
+
+  createInteractionListeners() {
+    window.addEventListener("blur", this.interactionListeners.blur);
+    window.addEventListener("focus", this.interactionListeners.focus);
 
-  // public methods for testing purposes. not recommended for use.
-  _customInsert(data) {
-    this.allData = new DataCollection(data);
+    document.addEventListener("fullscreenchange", this.interactionListeners.fullscreenchange);
+    document.addEventListener("mozfullscreenchange", this.interactionListeners.fullscreenchange);
+    document.addEventListener("webkitfullscreenchange", this.interactionListeners.fullscreenchange);
   }
 
-  _fullreset() {
-    this.reset();
-    this.dataProperties = {};
+  removeInteractionListeners() {
+    window.removeEventListener("blur", this.interactionListeners.blur);
+    window.removeEventListener("focus", this.interactionListeners.focus);
+
+    document.removeEventListener("fullscreenchange", this.interactionListeners.fullscreenchange);
+    document.removeEventListener("mozfullscreenchange", this.interactionListeners.fullscreenchange);
+    document.removeEventListener(
+      "webkitfullscreenchange",
+      this.interactionListeners.fullscreenchange
+    );
   }
 }

package/src/modules/extensions.ts

@@ -1,5 +1,9 @@
+import { ParameterInfos } from "./plugins";
+
 export interface JsPsychExtensionInfo {
   name: string;
+  version?: string;
+  data?: ParameterInfos;
 }
 
 export interface JsPsychExtension {

package/src/modules/plugin-api/AudioPlayer.ts

@@ -0,0 +1,101 @@
+export interface AudioPlayerOptions {
+  useWebAudio: boolean;
+  audioContext?: AudioContext;
+}
+
+export interface AudioPlayerInterface {
+  load(): Promise<void>;
+  play(): void;
+  stop(): void;
+  addEventListener(eventName: string, callback: EventListenerOrEventListenerObject): void;
+  removeEventListener(eventName: string, callback: EventListenerOrEventListenerObject): void;
+}
+
+export class AudioPlayer implements AudioPlayerInterface {
+  private audio: HTMLAudioElement | AudioBufferSourceNode;
+  private webAudioBuffer: AudioBuffer;
+  private audioContext: AudioContext | null;
+  private useWebAudio: boolean;
+  private src: string;
+
+  constructor(src: string, options: AudioPlayerOptions = { useWebAudio: false }) {
+    this.src = src;
+    this.useWebAudio = options.useWebAudio;
+    this.audioContext = options.audioContext || null;
+  }
+
+  async load() {
+    if (this.useWebAudio) {
+      this.webAudioBuffer = await this.preloadWebAudio(this.src);
+    } else {
+      this.audio = await this.preloadHTMLAudio(this.src);
+    }
+  }
+
+  play() {
+    if (this.audio instanceof HTMLAudioElement) {
+      this.audio.play();
+    } else {
+      // If audio is not HTMLAudioElement, it must be a WebAudio API object, so create a source node.
+      if (!this.audio) this.audio = this.getAudioSourceNode(this.webAudioBuffer);
+      this.audio.start();
+    }
+  }
+
+  stop() {
+    if (this.audio instanceof HTMLAudioElement) {
+      this.audio.pause();
+      this.audio.currentTime = 0;
+    } else {
+      this.audio!.stop();
+      // Regenerate source node for audio since the previous one is stopped and unusable.
+      this.audio = this.getAudioSourceNode(this.webAudioBuffer);
+    }
+  }
+
+  addEventListener(eventName: string, callback: EventListenerOrEventListenerObject) {
+    // If WebAudio buffer exists but source node doesn't, create it.
+    if (!this.audio && this.webAudioBuffer)
+      this.audio = this.getAudioSourceNode(this.webAudioBuffer);
+    this.audio.addEventListener(eventName, callback);
+  }
+
+  removeEventListener(eventName: string, callback: EventListenerOrEventListenerObject) {
+    // If WebAudio buffer exists but source node doesn't, create it.
+    if (!this.audio && this.webAudioBuffer)
+      this.audio = this.getAudioSourceNode(this.webAudioBuffer);
+    this.audio.removeEventListener(eventName, callback);
+  }
+
+  private getAudioSourceNode(audioBuffer: AudioBuffer): AudioBufferSourceNode {
+    const source = this.audioContext!.createBufferSource();
+    source.buffer = audioBuffer;
+    source.connect(this.audioContext!.destination);
+    return source;
+  }
+
+  private async preloadWebAudio(src: string): Promise<AudioBuffer> {
+    const buffer = await fetch(src);
+    const arrayBuffer = await buffer.arrayBuffer();
+    const audioBuffer = await this.audioContext!.decodeAudioData(arrayBuffer);
+    const source = this.audioContext!.createBufferSource();
+    source.buffer = audioBuffer;
+    source.connect(this.audioContext!.destination);
+    return audioBuffer;
+  }
+
+  private async preloadHTMLAudio(src: string): Promise<HTMLAudioElement> {
+    return new Promise<HTMLAudioElement>((resolve, reject) => {
+      const audio = new Audio(src);
+      audio.addEventListener("canplaythrough", () => {
+        resolve(audio);
+      });
+      audio.addEventListener("error", (err) => {
+        reject(err);
+      });
+      audio.addEventListener("abort", (err) => {
+        reject(err);
+      });
+    });
+  }
+}

package/src/modules/plugin-api/KeyboardListenerAPI.ts

@@ -125,7 +125,7 @@ export class KeyboardListenerAPI {
           this.cancelKeyboardResponse(listener);
         }
 
-        callback_function({ key, rt });
+        callback_function({ key: e.key, rt });
       }
     };