jspsych-tangram 0.0.16 → 0.0.18

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

@@ -0,0 +1,154 @@
+import { JsPsych, JsPsychPlugin, ParameterType, TrialType } from "jspsych";
+import { startGridTrial, StartGridTrialParams } from "./GridApp";
+
+const info = {
+  name: "tangram-grid",
+  version: "1.0.0",
+  parameters: {
+    /** Array of tangram specifications to display in the grid */
+    tangrams: {
+      type: ParameterType.COMPLEX,
+      default: undefined,
+      description: "Array of TangramSpec objects to display in the grid"
+    },
+    /** Number of rows in the grid */
+    n_rows: {
+      type: ParameterType.INT,
+      default: 1,
+      description: "Number of rows in the tangram grid"
+    },
+    /** Number of columns in the grid */
+    n_cols: {
+      type: ParameterType.INT,
+      default: 1,
+      description: "Number of columns in the tangram grid"
+    },
+    /** Prompt text displayed above the text input */
+    prompt_text: {
+      type: ParameterType.STRING,
+      default: "",
+      description: "Text displayed above the text input field"
+    },
+    /** Label for the submit button */
+    button_text: {
+      type: ParameterType.STRING,
+      default: "Submit",
+      description: "Text displayed on the submit button"
+    },
+    /** Whether to show tangrams decomposed into primitives */
+    show_tangram_decomposition: {
+      type: ParameterType.BOOL,
+      default: false,
+      description:
+        "Whether to show tangrams decomposed into individual primitives"
+    },
+    /** Whether to use distinct colors for each primitive type */
+    use_primitive_colors: {
+      type: ParameterType.BOOL,
+      default: false,
+      description:
+        "Whether each primitive shape type should have its own distinct color"
+    },
+    /** Indices mapping primitives to colors */
+    primitive_color_indices: {
+      type: ParameterType.OBJECT,
+      default: [0, 1, 2, 3, 4],
+      description:
+        "Array of 5 integers indexing into primitiveColors array, mapping " +
+        "[square, smalltriangle, parallelogram, medtriangle, largetriangle] " +
+        "to colors"
+    },
+    /** Callback fired when trial ends */
+    onTrialEnd: {
+      type: ParameterType.FUNCTION,
+      default: undefined,
+      description: "Callback when trial completes with full data"
+    }
+  },
+  data: {
+    /** The text response entered by the participant */
+    response: {
+      type: ParameterType.STRING,
+      description: "The text response entered by the participant"
+    },
+    /** Reaction time from trial start to submit button click */
+    rt: {
+      type: ParameterType.INT,
+      description: "Time in milliseconds from trial start to submit"
+    }
+  },
+  citations: ""
+};
+
+type Info = typeof info;
+
+/**
+ * **tangram-grid**
+ *
+ * A jsPsych plugin that displays a grid of tangrams with a text input field
+ * and submit button for collecting free-text responses.
+ *
+ * @author Sean Paul Anderson & Justin Yang
+ * @see {@link https://github.com/cogtoolslab/tangram_construction.git}
+ */
+class TangramGridPlugin implements JsPsychPlugin<Info> {
+  static info = info;
+
+  constructor(private jsPsych: JsPsych) {}
+
+  /**
+   * Launches the trial by invoking startGridTrial with the display element,
+   * parameters, and jsPsych instance.
+   *
+   * REQUIRES: display_element is a valid HTMLElement, trial contains valid
+   *           parameters
+   * MODIFIES: display_element (renders React component)
+   * EFFECTS: Starts the grid trial and handles cleanup on completion
+   */
+  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: StartGridTrialParams = {
+      tangrams: trial.tangrams,
+      n_rows: trial.n_rows,
+      n_cols: trial.n_cols,
+      prompt_text: trial.prompt_text,
+      button_text: trial.button_text,
+      show_tangram_decomposition: trial.show_tangram_decomposition,
+      usePrimitiveColors: trial.use_primitive_colors,
+      primitiveColorIndices: trial.primitive_color_indices,
+      onTrialEnd: wrappedOnTrialEnd
+    };
+
+    // Use React wrapper to start the trial
+    const { root, display_element: element, jsPsych } = startGridTrial(
+      display_element,
+      params,
+      this.jsPsych
+    );
+
+    // Store React context for cleanup
+    (element as any).__reactContext = { root, jsPsych };
+  }
+}
+
+export default TangramGridPlugin;