jspsych-tangram 0.0.8 → 0.0.10

package/src/plugins/tangram-nback/index.ts

@@ -0,0 +1,141 @@
+import { JsPsych, JsPsychPlugin, ParameterType, TrialType } from "jspsych";
+import { startNBackTrial, StartNBackTrialParams } from "./NBackApp";
+
+const info = {
+  name: "tangram-nback",
+  version: "1.0.0",
+  parameters: {
+    /** Single tangram specification to display */
+    tangram: {
+      type: ParameterType.COMPLEX,
+      default: undefined,
+      description: "TangramSpec object defining target shape to display"
+    },
+    /** Whether this trial is a match (for computing accuracy) */
+    isMatch: {
+      type: ParameterType.BOOL,
+      default: undefined,
+      description: "Whether this tangram matches the previous one (optional)"
+    },
+    /** Whether to show tangram decomposed into individual primitives with borders */
+    show_tangram_decomposition: {
+      type: ParameterType.BOOL,
+      default: false,
+      description: "Whether to show tangram decomposed into individual primitives with borders"
+    },
+    /** HTML content to display above the tangram as instructions */
+    instructions: {
+      type: ParameterType.STRING,
+      default: "",
+      description: "HTML content to display above the tangram as instructions"
+    },
+    /** Text to display on response button */
+    button_text: {
+      type: ParameterType.STRING,
+      default: "Same as previous!",
+      description: "Text to display on response button"
+    },
+    /** Duration to display tangram and accept responses (milliseconds) */
+    duration: {
+      type: ParameterType.INT,
+      default: 3000,
+      description: "Duration in milliseconds to display tangram and accept responses"
+    },
+    /** Callback fired when trial ends */
+    onTrialEnd: {
+      type: ParameterType.FUNCTION,
+      default: undefined,
+      description: "Callback when trial completes with full data"
+    }
+  },
+  data: {
+    /** Whether participant clicked the response button before duration expired */
+    responded_match: {
+      type: ParameterType.BOOL,
+      description: "True if participant clicked response button, false otherwise"
+    },
+    /** Reaction time in milliseconds (NaN if no response or response after duration) */
+    rt: {
+      type: ParameterType.INT,
+      description: "Milliseconds between trial start and button click (NaN if no response or late response)"
+    },
+    /** Accuracy: 1 if correct, 0 if incorrect, NaN if isMatch not provided */
+    accuracy: {
+      type: ParameterType.FLOAT,
+      description: "1 if response matches isMatch parameter, 0 otherwise (NaN if isMatch not provided)"
+    },
+    /** Whether response occurred after duration expired */
+    responded_after_duration: {
+      type: ParameterType.BOOL,
+      description: "True if button clicked after duration expired, false otherwise"
+    },
+    /** Time of late response (NaN if no late response) */
+    rt_after_duration: {
+      type: ParameterType.INT,
+      description: "Milliseconds between trial start and late button click (NaN if no late response)"
+    }
+  },
+  citations: ""
+};
+
+type Info = typeof info;
+
+/**
+ * **tangram-nback**
+ *
+ * A jsPsych plugin for n-back matching trials displaying a single tangram
+ * with a response button.
+ *
+ * @author Justin Yang & Sean Paul Anderson
+ * @see {@link https://github.com/cogtoolslab/tangram_construction.git/tree/main/experiments/jspsych-tangram-prep}
+ */
+class TangramNBackPlugin implements JsPsychPlugin<Info> {
+  static info = info;
+
+  constructor(private jsPsych: JsPsych) {}
+
+  /**
+   * Launches the trial by invoking startNBackTrial
+   * with the display element, parameters, and jsPsych instance.
+   */
+  trial(display_element: HTMLElement, trial: TrialType<Info>) {
+    // Wrap onTrialEnd to handle React cleanup and jsPsych trial completion
+    const wrappedOnTrialEnd = (data: any) => {
+      // Call user-provided callback if exists
+      if (trial.onTrialEnd) {
+        trial.onTrialEnd(data);
+      }
+
+      // Clean up React first (before clearing DOM)
+      const reactContext = (display_element as any).__reactContext;
+      if (reactContext?.root) {
+        reactContext.root.unmount();
+      }
+
+      // Clear display after React cleanup
+      display_element.innerHTML = '';
+
+      // Finish jsPsych trial with data
+      this.jsPsych.finishTrial(data);
+    };
+
+    // Create parameter object for wrapper
+    const params: StartNBackTrialParams = {
+      tangram: trial.tangram,
+      isMatch: trial.isMatch,
+      show_tangram_decomposition: trial.show_tangram_decomposition,
+      instructions: trial.instructions,
+      button_text: trial.button_text,
+      duration: trial.duration,
+      onTrialEnd: wrappedOnTrialEnd
+    };
+
+    // Use React wrapper to start the trial
+    const { root, display_element: element, jsPsych } = startNBackTrial(display_element, params, this.jsPsych);
+
+    // Store React context for cleanup
+    (element as any).__reactContext = { root, jsPsych };
+  }
+}
+
+export default TangramNBackPlugin;