jspsych-tangram 0.0.9 → 0.0.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jspsych-tangram",
-  "version": "0.0.9",
+  "version": "0.0.10",
   "description": "Tangram tasks for jsPsych: prep and construct.",
   "type": "module",
   "main": "dist/index.cjs",
@@ -22,18 +22,24 @@
       "types": "./dist/construct/index.d.ts",
       "import": "./dist/construct/index.js",
       "require": "./dist/construct/index.cjs"
+    },
+    "./nback": {
+      "types": "./dist/nback/index.d.ts",
+      "import": "./dist/nback/index.js",
+      "require": "./dist/nback/index.cjs"
     }
   },
   "files": [
     "src",
     "dist",
     "tangram-prep.min.js",
-    "tangram-construct.min.js"
+    "tangram-construct.min.js",
+    "tangram-nback.min.js"
   ],
   "source": "src/index.ts",
   "scripts": {
     "build": "rollup --config",
-    "postbuild": "cp dist/prep/index.browser.min.js tangram-prep.min.js && cp dist/construct/index.browser.min.js tangram-construct.min.js",
+    "postbuild": "cp dist/prep/index.browser.min.js tangram-prep.min.js && cp dist/construct/index.browser.min.js tangram-construct.min.js && cp dist/nback/index.browser.min.js tangram-nback.min.js",
     "build:watch": "npm run build -- --watch",
     "dev": "vite",
     "test": "jest",

package/src/index.ts

@@ -1,2 +1,3 @@
 export { default as TangramConstructPlugin } from "./plugins/tangram-construct";
-export { default as TangramPrepPlugin } from "./plugins/tangram-prep";
+export { default as TangramPrepPlugin } from "./plugins/tangram-prep";
+export { default as TangramNBackPlugin } from "./plugins/tangram-nback";

package/src/plugins/tangram-nback/NBackApp.tsx

@@ -0,0 +1,316 @@
+/**
+ * NBackApp.tsx - React wrapper for tangram n-back matching trials
+ *
+ * This component handles the React rendering logic for n-back trials,
+ * displaying a single tangram silhouette with a response button.
+ */
+
+import React, { useRef, useEffect, useState } from "react";
+import { createRoot } from "react-dom/client";
+import { JsPsych } from "jspsych";
+import type { Poly, TanKind } from "../../core/domain/types";
+import { placeSilhouetteGridAlignedAsPolys, inferUnitFromPolys } from "../../core/engine/geometry";
+import { CONFIG } from "../../core/config/config";
+
+export interface StartNBackTrialParams {
+  tangram: any;
+  isMatch?: boolean;
+  show_tangram_decomposition?: boolean;
+  instructions?: string;
+  button_text?: string;
+  duration: number;
+  onTrialEnd?: (data: any) => void;
+}
+
+/**
+ * Start an n-back trial by rendering the NBackView component
+ */
+export function startNBackTrial(
+  display_element: HTMLElement,
+  params: StartNBackTrialParams,
+  _jsPsych: JsPsych
+) {
+  // Create React root and render NBackView
+  const root = createRoot(display_element);
+  root.render(React.createElement(NBackView, { params }));
+
+  return { root, display_element, jsPsych: _jsPsych };
+}
+
+interface NBackViewProps {
+  params: StartNBackTrialParams;
+}
+
+function NBackView({ params }: NBackViewProps) {
+  const {
+    tangram,
+    isMatch,
+    show_tangram_decomposition,
+    instructions,
+    button_text,
+    duration,
+    onTrialEnd
+  } = params;
+
+  // Timing and response tracking
+  const trialStartTime = useRef<number>(Date.now());
+  const buttonEnabledRef = useRef<boolean>(true);
+  const timeoutIdRef = useRef<NodeJS.Timeout | null>(null);
+  const hasRespondedRef = useRef<boolean>(false);
+  const responseDataRef = useRef<any>(null);
+  const [buttonDisabled, setButtonDisabled] = useState(false);
+
+  // Canonical piece names
+  const CANON = new Set([
+    "square",
+    "smalltriangle",
+    "parallelogram",
+    "medtriangle",
+    "largetriangle",
+  ]);
+
+  // Convert TangramSpec to internal format
+  const filteredTans = tangram.solutionTans.filter((tan: any) => {
+    const tanName = tan.name ?? tan.kind;
+    return CANON.has(tanName);
+  });
+
+  const mask = filteredTans.map((tan: any) => {
+    const polygon = tan.vertices.map(([x, y]: number[]) => ({ x: x ?? 0, y: -(y ?? 0) }));
+    return polygon;
+  });
+
+  const primitiveDecomposition = filteredTans.map((tan: any) => ({
+    kind: (tan.name ?? tan.kind) as TanKind,
+    polygon: tan.vertices.map(([x, y]: number[]) => ({ x: x ?? 0, y: -(y ?? 0) }))
+  }));
+
+  // Use FIXED viewport size for n-back display (constant across all tangrams)
+  const DISPLAY_SIZE = 400;
+  const viewport = {
+    w: DISPLAY_SIZE,
+    h: DISPLAY_SIZE
+  };
+
+  // Compute scale factor to keep tangram pieces at constant physical size
+  // This matches the approach in TangramConstructPlugin/GameBoard
+  const scaleS = React.useMemo(() => {
+    const u = inferUnitFromPolys(mask);
+    return u ? (CONFIG.layout.grid.unitPx / u) : 1;
+  }, [mask]);
+
+  // For n-back display, we want tangrams centered in viewport
+  // Don't use computeCircleLayout's positioning - just center manually
+  const centerPos = {
+    cx: viewport.w / 2,
+    cy: viewport.h / 2
+  };
+
+  // Helper to convert polygon to SVG path
+  const pathD = (poly: Poly): string => {
+    if (!poly || poly.length === 0) return "";
+    const moves = poly.map((p, i) => `${i === 0 ? "M" : "L"} ${p.x} ${p.y}`);
+    return moves.join(" ") + " Z";
+  };
+
+  // End trial with data
+  const endTrial = (data: {
+    responded_match: boolean;
+    rt: number;
+    responded_after_duration: boolean;
+    rt_after_duration: number;
+  }) => {
+    // Clear timeout if it exists
+    if (timeoutIdRef.current) {
+      clearTimeout(timeoutIdRef.current);
+      timeoutIdRef.current = null;
+    }
+
+    // Compute accuracy
+    const accuracy = isMatch !== undefined
+      ? (isMatch === data.responded_match ? 1 : 0)
+      : NaN;
+
+    const trialData = {
+      ...data,
+      accuracy,
+      tangram_id: tangram.tangramID,
+      is_match: isMatch
+    };
+
+    if (onTrialEnd) {
+      onTrialEnd(trialData);
+    }
+  };
+
+  // Handle button click
+  const handleButtonClick = () => {
+    if (!buttonEnabledRef.current) {
+      // Late response after duration expired
+      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 {
+      // Response before duration expired - disable button but continue showing trial
+      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
+      };
+      // Don't end trial yet - wait for duration timeout
+    }
+  };
+
+  // Set up duration timeout
+  useEffect(() => {
+    timeoutIdRef.current = setTimeout(() => {
+      buttonEnabledRef.current = false;
+
+      // End trial with appropriate data
+      if (hasRespondedRef.current && responseDataRef.current) {
+        // User already responded - use saved response data
+        endTrial(responseDataRef.current);
+      } else {
+        // No response - end with no-response data
+        endTrial({
+          responded_match: false,
+          rt: NaN,
+          responded_after_duration: false,
+          rt_after_duration: NaN
+        });
+      }
+    }, duration);
+
+    return () => {
+      if (timeoutIdRef.current) {
+        clearTimeout(timeoutIdRef.current);
+      }
+    };
+  }, []);
+
+  // Render silhouette
+  const renderSilhouette = () => {
+    if (show_tangram_decomposition) {
+      // Render decomposed primitives with borders
+      const rawPolys = primitiveDecomposition.map((primInfo: any) => primInfo.polygon);
+      const placedPolys = placeSilhouetteGridAlignedAsPolys(rawPolys, scaleS, centerPos);
+
+      return (
+        <g key="sil-decomposed" pointerEvents="none">
+          {placedPolys.map((scaledPoly, i) => (
+            <React.Fragment key={`prim-${i}`}>
+              {/* Fill path */}
+              <path
+                d={pathD(scaledPoly)}
+                fill={CONFIG.color.silhouetteMask}
+                opacity={CONFIG.opacity.silhouetteMask}
+                stroke="none"
+              />
+
+              {/* Full perimeter border */}
+              <path
+                d={pathD(scaledPoly)}
+                fill="none"
+                stroke={CONFIG.color.tangramDecomposition.stroke}
+                strokeWidth={CONFIG.size.stroke.tangramDecompositionPx}
+              />
+            </React.Fragment>
+          ))}
+        </g>
+      );
+    } else {
+      // Render unified silhouette
+      const placedPolys = placeSilhouetteGridAlignedAsPolys(mask, scaleS, centerPos);
+
+      return (
+        <g key="sil-unified" pointerEvents="none">
+          {placedPolys.map((scaledPoly, i) => (
+            <path
+              key={`sil-${i}`}
+              d={pathD(scaledPoly)}
+              fill={CONFIG.color.silhouetteMask}
+              opacity={CONFIG.opacity.silhouetteMask}
+              stroke="none"
+            />
+          ))}
+        </g>
+      );
+    }
+  };
+
+  return (
+    <div style={{
+      display: "flex",
+      flexDirection: "column",
+      alignItems: "center",
+      justifyContent: "flex-start",
+      minHeight: "100vh",
+      padding: "40px 20px",
+      background: "#f5f5f5"
+    }}>
+      {/* Instructions */}
+      {instructions && (
+        <div
+          style={{
+            maxWidth: "800px",
+            width: "100%",
+            marginBottom: "30px",
+            textAlign: "center",
+            fontSize: "18px",
+            lineHeight: "1.5"
+          }}
+          dangerouslySetInnerHTML={{ __html: instructions }}
+        />
+      )}
+
+      {/* Container for SVG and button */}
+      <div style={{
+        display: "flex",
+        flexDirection: "column",
+        alignItems: "center",
+        gap: "30px"
+      }}>
+        {/* SVG with tangram silhouette */}
+        <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()}
+        </svg>
+
+        {/* Response button */}
+        <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}
+        </button>
+      </div>
+    </div>
+  );
+}

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;