jspsych-tangram 0.0.9 → 0.0.11

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { JsPsychPlugin, ParameterType, JsPsych, TrialType } from 'jspsych';
 
-declare const info$1: {
+declare const info$2: {
     name: string;
     version: string;
     parameters: {
@@ -109,7 +109,7 @@ declare const info$1: {
     };
     citations: string;
 };
-type Info$1 = typeof info$1;
+type Info$2 = typeof info$2;
 /**
  * **tangram-construct**
  *
@@ -118,7 +118,7 @@ type Info$1 = typeof info$1;
  * @author Justin Yang & Sean Paul Anderson
  * @see {@link https://github.com/cogtoolslab/tangram_construction.git/tree/main/experiments/jspsych-tangram-prep}
  */
-declare class TangramConstructPlugin implements JsPsychPlugin<Info$1> {
+declare class TangramConstructPlugin implements JsPsychPlugin<Info$2> {
     private jsPsych;
     static info: {
         name: string;
@@ -234,10 +234,10 @@ declare class TangramConstructPlugin implements JsPsychPlugin<Info$1> {
      * Launches the trial by invoking startConstructionTrial
      * with the display element, parameters, and jsPsych instance.
      */
-    trial(display_element: HTMLElement, trial: TrialType<Info$1>): void;
+    trial(display_element: HTMLElement, trial: TrialType<Info$2>): void;
 }
 
-declare const info: {
+declare const info$1: {
     name: string;
     version: string;
     parameters: {
@@ -308,7 +308,7 @@ declare const info: {
     };
     citations: string;
 };
-type Info = typeof info;
+type Info$1 = typeof info$1;
 /**
  * **tangram-prep**
  *
@@ -316,7 +316,7 @@ type Info = typeof info;
  *
  * @author Justin Yang & Sean Paul Anderson
  */
-declare class TangramPrepPlugin implements JsPsychPlugin<Info> {
+declare class TangramPrepPlugin implements JsPsychPlugin<Info$1> {
     private jsPsych;
     static info: {
         name: string;
@@ -394,7 +394,179 @@ declare class TangramPrepPlugin implements JsPsychPlugin<Info> {
      * Launches the trial by invoking startPrepTrial
      * with the display element, parameters, and jsPsych instance.
      */
+    trial(display_element: HTMLElement, trial: TrialType<Info$1>): void;
+}
+
+declare const info: {
+    name: string;
+    version: string;
+    parameters: {
+        /** Single tangram specification to display */
+        tangram: {
+            type: ParameterType;
+            default: undefined;
+            description: string;
+        };
+        /** Whether this trial is a match (for computing accuracy) */
+        isMatch: {
+            type: ParameterType;
+            default: undefined;
+            description: string;
+        };
+        /** Whether to show tangram decomposed into individual primitives with borders */
+        show_tangram_decomposition: {
+            type: ParameterType;
+            default: boolean;
+            description: string;
+        };
+        /** HTML content to display above the tangram as instructions */
+        instructions: {
+            type: ParameterType;
+            default: string;
+            description: string;
+        };
+        /** Text to display on response button */
+        button_text: {
+            type: ParameterType;
+            default: string;
+            description: string;
+        };
+        /** Duration to display tangram and accept responses (milliseconds) */
+        duration: {
+            type: ParameterType;
+            default: number;
+            description: string;
+        };
+        /** Callback fired when trial ends */
+        onTrialEnd: {
+            type: ParameterType;
+            default: undefined;
+            description: string;
+        };
+    };
+    data: {
+        /** Whether participant clicked the response button before duration expired */
+        responded_match: {
+            type: ParameterType;
+            description: string;
+        };
+        /** Reaction time in milliseconds (NaN if no response or response after duration) */
+        rt: {
+            type: ParameterType;
+            description: string;
+        };
+        /** Accuracy: 1 if correct, 0 if incorrect, NaN if isMatch not provided */
+        accuracy: {
+            type: ParameterType;
+            description: string;
+        };
+        /** Whether response occurred after duration expired */
+        responded_after_duration: {
+            type: ParameterType;
+            description: string;
+        };
+        /** Time of late response (NaN if no late response) */
+        rt_after_duration: {
+            type: ParameterType;
+            description: string;
+        };
+    };
+    citations: string;
+};
+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}
+ */
+declare class TangramNBackPlugin implements JsPsychPlugin<Info> {
+    private jsPsych;
+    static info: {
+        name: string;
+        version: string;
+        parameters: {
+            /** Single tangram specification to display */
+            tangram: {
+                type: ParameterType;
+                default: undefined;
+                description: string;
+            };
+            /** Whether this trial is a match (for computing accuracy) */
+            isMatch: {
+                type: ParameterType;
+                default: undefined;
+                description: string;
+            };
+            /** Whether to show tangram decomposed into individual primitives with borders */
+            show_tangram_decomposition: {
+                type: ParameterType;
+                default: boolean;
+                description: string;
+            };
+            /** HTML content to display above the tangram as instructions */
+            instructions: {
+                type: ParameterType;
+                default: string;
+                description: string;
+            };
+            /** Text to display on response button */
+            button_text: {
+                type: ParameterType;
+                default: string;
+                description: string;
+            };
+            /** Duration to display tangram and accept responses (milliseconds) */
+            duration: {
+                type: ParameterType;
+                default: number;
+                description: string;
+            };
+            /** Callback fired when trial ends */
+            onTrialEnd: {
+                type: ParameterType;
+                default: undefined;
+                description: string;
+            };
+        };
+        data: {
+            /** Whether participant clicked the response button before duration expired */
+            responded_match: {
+                type: ParameterType;
+                description: string;
+            };
+            /** Reaction time in milliseconds (NaN if no response or response after duration) */
+            rt: {
+                type: ParameterType;
+                description: string;
+            };
+            /** Accuracy: 1 if correct, 0 if incorrect, NaN if isMatch not provided */
+            accuracy: {
+                type: ParameterType;
+                description: string;
+            };
+            /** Whether response occurred after duration expired */
+            responded_after_duration: {
+                type: ParameterType;
+                description: string;
+            };
+            /** Time of late response (NaN if no late response) */
+            rt_after_duration: {
+                type: ParameterType;
+                description: string;
+            };
+        };
+        citations: string;
+    };
+    constructor(jsPsych: JsPsych);
+    /**
+     * Launches the trial by invoking startNBackTrial
+     * with the display element, parameters, and jsPsych instance.
+     */
     trial(display_element: HTMLElement, trial: TrialType<Info>): void;
 }
 
-export { TangramConstructPlugin, TangramPrepPlugin };
+export { TangramConstructPlugin, TangramNBackPlugin, TangramPrepPlugin };

package/dist/index.js

@@ -1,5 +1,5 @@
 import { ParameterType } from 'jspsych';
-import React from 'react';
+import React, { useRef, useState, useEffect } from 'react';
 import { createRoot } from 'react-dom/client';
 import { v4 } from 'uuid';
 
@@ -3561,7 +3561,7 @@ function startConstructionTrial(display_element, params, _jsPsych) {
   return { root, display_element, jsPsych: _jsPsych };
 }
 
-const info$1 = {
+const info$2 = {
   name: "tangram-construct",
   version: "1.0.0",
   parameters: {
@@ -3675,7 +3675,7 @@ class TangramConstructPlugin {
     this.jsPsych = jsPsych;
   }
   static {
-    this.info = info$1;
+    this.info = info$2;
   }
   /**
    * Launches the trial by invoking startConstructionTrial
@@ -3819,7 +3819,7 @@ function startPrepTrial(display_element, params, jsPsych) {
   return { root, display_element, jsPsych };
 }
 
-const info = {
+const info$1 = {
   name: "tangram-prep",
   version: "1.0.0",
   parameters: {
@@ -3895,7 +3895,7 @@ class TangramPrepPlugin {
     this.jsPsych = jsPsych;
   }
   static {
-    this.info = info;
+    this.info = info$1;
   }
   /**
    * Launches the trial by invoking startPrepTrial
@@ -3931,5 +3931,327 @@ class TangramPrepPlugin {
   }
 }
 
-export { TangramConstructPlugin, TangramPrepPlugin };
+function startNBackTrial(display_element, params, _jsPsych) {
+  const root = createRoot(display_element);
+  root.render(React.createElement(NBackView, { params }));
+  return { root, display_element, jsPsych: _jsPsych };
+}
+function NBackView({ params }) {
+  const {
+    tangram,
+    isMatch,
+    show_tangram_decomposition,
+    instructions,
+    button_text,
+    duration,
+    onTrialEnd
+  } = params;
+  const trialStartTime = useRef(Date.now());
+  const buttonEnabledRef = useRef(true);
+  const timeoutIdRef = useRef(null);
+  const hasRespondedRef = useRef(false);
+  const responseDataRef = useRef(null);
+  const [buttonDisabled, setButtonDisabled] = useState(false);
+  const CANON = /* @__PURE__ */ new Set([
+    "square",
+    "smalltriangle",
+    "parallelogram",
+    "medtriangle",
+    "largetriangle"
+  ]);
+  const filteredTans = tangram.solutionTans.filter((tan) => {
+    const tanName = tan.name ?? tan.kind;
+    return CANON.has(tanName);
+  });
+  const mask = filteredTans.map((tan) => {
+    const polygon = tan.vertices.map(([x, y]) => ({ x: x ?? 0, y: -(y ?? 0) }));
+    return polygon;
+  });
+  const primitiveDecomposition = filteredTans.map((tan) => ({
+    kind: tan.name ?? tan.kind,
+    polygon: tan.vertices.map(([x, y]) => ({ x: x ?? 0, y: -(y ?? 0) }))
+  }));
+  const DISPLAY_SIZE = 400;
+  const viewport = {
+    w: DISPLAY_SIZE,
+    h: DISPLAY_SIZE
+  };
+  const scaleS = React.useMemo(() => {
+    const u = inferUnitFromPolys$1(mask);
+    return u ? CONFIG.layout.grid.unitPx / u : 1;
+  }, [mask]);
+  const centerPos = {
+    cx: viewport.w / 2,
+    cy: viewport.h / 2
+  };
+  const pathD = (poly) => {
+    if (!poly || poly.length === 0) return "";
+    const moves = poly.map((p, i) => `${i === 0 ? "M" : "L"} ${p.x} ${p.y}`);
+    return moves.join(" ") + " Z";
+  };
+  const endTrial = (data) => {
+    if (timeoutIdRef.current) {
+      clearTimeout(timeoutIdRef.current);
+      timeoutIdRef.current = null;
+    }
+    const accuracy = isMatch !== void 0 ? isMatch === data.responded_match ? 1 : 0 : NaN;
+    const trialData = {
+      ...data,
+      accuracy,
+      tangram_id: tangram.tangramID,
+      is_match: isMatch
+    };
+    if (onTrialEnd) {
+      onTrialEnd(trialData);
+    }
+  };
+  const handleButtonClick = () => {
+    if (!buttonEnabledRef.current) {
+      const rt_late = Date.now() - trialStartTime.current;
+      hasRespondedRef.current = true;
+      responseDataRef.current = {
+        responded_match: true,
+        rt: NaN,
+        responded_after_duration: true,
+        rt_after_duration: rt_late
+      };
+      endTrial(responseDataRef.current);
+    } else {
+      const rt = Date.now() - trialStartTime.current;
+      buttonEnabledRef.current = false;
+      setButtonDisabled(true);
+      hasRespondedRef.current = true;
+      responseDataRef.current = {
+        responded_match: true,
+        rt,
+        responded_after_duration: false,
+        rt_after_duration: NaN
+      };
+    }
+  };
+  useEffect(() => {
+    timeoutIdRef.current = setTimeout(() => {
+      buttonEnabledRef.current = false;
+      if (hasRespondedRef.current && responseDataRef.current) {
+        endTrial(responseDataRef.current);
+      } else {
+        endTrial({
+          responded_match: false,
+          rt: NaN,
+          responded_after_duration: false,
+          rt_after_duration: NaN
+        });
+      }
+    }, duration);
+    return () => {
+      if (timeoutIdRef.current) {
+        clearTimeout(timeoutIdRef.current);
+      }
+    };
+  }, []);
+  const renderSilhouette = () => {
+    if (show_tangram_decomposition) {
+      const rawPolys = primitiveDecomposition.map((primInfo) => primInfo.polygon);
+      const placedPolys = placeSilhouetteGridAlignedAsPolys(rawPolys, scaleS, centerPos);
+      return /* @__PURE__ */ React.createElement("g", { key: "sil-decomposed", pointerEvents: "none" }, placedPolys.map((scaledPoly, i) => /* @__PURE__ */ React.createElement(React.Fragment, { key: `prim-${i}` }, /* @__PURE__ */ React.createElement(
+        "path",
+        {
+          d: pathD(scaledPoly),
+          fill: CONFIG.color.silhouetteMask,
+          opacity: CONFIG.opacity.silhouetteMask,
+          stroke: "none"
+        }
+      ), /* @__PURE__ */ React.createElement(
+        "path",
+        {
+          d: pathD(scaledPoly),
+          fill: "none",
+          stroke: CONFIG.color.tangramDecomposition.stroke,
+          strokeWidth: CONFIG.size.stroke.tangramDecompositionPx
+        }
+      ))));
+    } else {
+      const placedPolys = placeSilhouetteGridAlignedAsPolys(mask, scaleS, centerPos);
+      return /* @__PURE__ */ React.createElement("g", { key: "sil-unified", pointerEvents: "none" }, placedPolys.map((scaledPoly, i) => /* @__PURE__ */ React.createElement(
+        "path",
+        {
+          key: `sil-${i}`,
+          d: pathD(scaledPoly),
+          fill: CONFIG.color.silhouetteMask,
+          opacity: CONFIG.opacity.silhouetteMask,
+          stroke: "none"
+        }
+      )));
+    }
+  };
+  return /* @__PURE__ */ React.createElement("div", { style: {
+    display: "flex",
+    flexDirection: "column",
+    alignItems: "center",
+    justifyContent: "center",
+    padding: "20px",
+    background: "#f5f5f5"
+  } }, instructions && /* @__PURE__ */ React.createElement(
+    "div",
+    {
+      style: {
+        maxWidth: "800px",
+        width: "100%",
+        marginBottom: "30px",
+        textAlign: "center",
+        fontSize: "18px",
+        lineHeight: "1.5"
+      },
+      dangerouslySetInnerHTML: { __html: instructions }
+    }
+  ), /* @__PURE__ */ React.createElement("div", { style: {
+    display: "flex",
+    flexDirection: "column",
+    alignItems: "center",
+    gap: "30px"
+  } }, /* @__PURE__ */ React.createElement(
+    "svg",
+    {
+      width: viewport.w,
+      height: viewport.h,
+      viewBox: `0 0 ${viewport.w} ${viewport.h}`,
+      style: {
+        display: "block",
+        background: CONFIG.color.bands.silhouette.fillEven,
+        border: `${CONFIG.size.stroke.bandPx}px solid ${CONFIG.color.bands.silhouette.stroke}`,
+        borderRadius: "8px"
+      }
+    },
+    renderSilhouette()
+  ), /* @__PURE__ */ React.createElement(
+    "button",
+    {
+      className: "jspsych-btn",
+      onClick: handleButtonClick,
+      disabled: buttonDisabled,
+      style: {
+        padding: "12px 30px",
+        fontSize: "16px",
+        cursor: buttonDisabled ? "not-allowed" : "pointer",
+        opacity: buttonDisabled ? 0.5 : 1
+      }
+    },
+    button_text
+  )));
+}
+
+const info = {
+  name: "tangram-nback",
+  version: "1.0.0",
+  parameters: {
+    /** Single tangram specification to display */
+    tangram: {
+      type: ParameterType.COMPLEX,
+      default: void 0,
+      description: "TangramSpec object defining target shape to display"
+    },
+    /** Whether this trial is a match (for computing accuracy) */
+    isMatch: {
+      type: ParameterType.BOOL,
+      default: void 0,
+      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: 3e3,
+      description: "Duration in milliseconds to display tangram and accept responses"
+    },
+    /** Callback fired when trial ends */
+    onTrialEnd: {
+      type: ParameterType.FUNCTION,
+      default: void 0,
+      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: ""
+};
+class TangramNBackPlugin {
+  constructor(jsPsych) {
+    this.jsPsych = jsPsych;
+  }
+  static {
+    this.info = info;
+  }
+  /**
+   * Launches the trial by invoking startNBackTrial
+   * with the display element, parameters, and jsPsych instance.
+   */
+  trial(display_element, trial) {
+    const wrappedOnTrialEnd = (data) => {
+      if (trial.onTrialEnd) {
+        trial.onTrialEnd(data);
+      }
+      const reactContext = display_element.__reactContext;
+      if (reactContext?.root) {
+        reactContext.root.unmount();
+      }
+      display_element.innerHTML = "";
+      this.jsPsych.finishTrial(data);
+    };
+    const params = {
+      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
+    };
+    const { root, display_element: element, jsPsych } = startNBackTrial(display_element, params, this.jsPsych);
+    element.__reactContext = { root, jsPsych };
+  }
+}
+
+export { TangramConstructPlugin, TangramNBackPlugin, TangramPrepPlugin };
 //# sourceMappingURL=index.js.map