jspsych-tangram 0.0.14 → 0.0.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jspsych-tangram",
-  "version": "0.0.14",
+  "version": "0.0.16",
   "description": "Tangram tasks for jsPsych: prep and construct.",
   "type": "module",
   "main": "dist/index.cjs",
@@ -27,6 +27,11 @@
       "types": "./dist/nback/index.d.ts",
       "import": "./dist/nback/index.js",
       "require": "./dist/nback/index.cjs"
+    },
+    "./afc": {
+      "types": "./dist/afc/index.d.ts",
+      "import": "./dist/afc/index.js",
+      "require": "./dist/afc/index.cjs"
     }
   },
   "files": [
@@ -34,12 +39,13 @@
     "dist",
     "tangram-prep.min.js",
     "tangram-construct.min.js",
-    "tangram-nback.min.js"
+    "tangram-nback.min.js",
+    "tangram-afc.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 && cp dist/nback/index.browser.min.js tangram-nback.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 && cp dist/afc/index.browser.min.js tangram-afc.min.js",
     "build:watch": "npm run build -- --watch",
     "dev": "vite",
     "test": "jest",

package/src/index.ts

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

package/src/plugins/tangram-afc/AFCApp.tsx

@@ -0,0 +1,341 @@
+/**
+ * AFCApp.tsx - React wrapper for tangram alternative forced choice (AFC) trials
+ *
+ * This component handles the React rendering logic for AFC trials,
+ * displaying two tangram silhouettes side-by-side with response buttons.
+ */
+
+import React, { useRef, 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 StartAFCTrialParams {
+  tangramLeft: any;
+  tangramRight: any;
+  instructions?: string;
+  buttonTextLeft?: string;
+  buttonTextRight?: string;
+  showTangramDecomposition?: boolean;
+  usePrimitiveColors?: boolean;
+  primitiveColorIndices?: number[];
+  onTrialEnd?: (data: any) => void;
+}
+
+/**
+ * Start an AFC trial by rendering the AFCView component
+ */
+export function startAFCTrial(
+  display_element: HTMLElement,
+  params: StartAFCTrialParams,
+  _jsPsych: JsPsych
+) {
+  // Create React root and render AFCView
+  const root = createRoot(display_element);
+  root.render(React.createElement(AFCView, { params }));
+
+  return { root, display_element, jsPsych: _jsPsych };
+}
+
+interface AFCViewProps {
+  params: StartAFCTrialParams;
+}
+
+function AFCView({ params }: AFCViewProps) {
+  const {
+    tangramLeft,
+    tangramRight,
+    instructions,
+    buttonTextLeft,
+    buttonTextRight,
+    showTangramDecomposition,
+    usePrimitiveColors,
+    primitiveColorIndices,
+    onTrialEnd
+  } = params;
+
+  // Timing and response tracking
+  const trialStartTime = useRef<number>(Date.now());
+  const [hasResponded, setHasResponded] = useState(false);
+
+  const handleResponse = (choice: "left" | "right") => {
+    if (hasResponded) return;
+
+    setHasResponded(true);
+    const rt = Date.now() - trialStartTime.current;
+
+    if (onTrialEnd) {
+      onTrialEnd({
+        rt,
+        response: choice,
+        show_tangram_decomposition: showTangramDecomposition,
+        use_primitive_colors: usePrimitiveColors,
+        primitive_color_indices: primitiveColorIndices,
+        button_text_left: buttonTextLeft,
+        button_text_right: buttonTextRight
+      });
+    }
+  };
+
+  return (
+    <div style={{
+      display: "flex",
+      flexDirection: "column",
+      alignItems: "center",
+      justifyContent: "center",
+      padding: "20px",
+      background: "#fff7e0ff",
+      minHeight: "100vh"
+    }}>
+      {/* Instructions */}
+      {instructions && (
+        <div
+          style={{
+            maxWidth: "800px",
+            width: "100%",
+            marginBottom: "30px",
+            textAlign: "center",
+            fontSize: "18px",
+            lineHeight: "1.5"
+          }}
+          dangerouslySetInnerHTML={{ __html: instructions }}
+        />
+      )}
+
+      {/* Container for Tangrams */}
+      <div style={{
+        display: "flex",
+        flexDirection: "row",
+        gap: "50px",
+        justifyContent: "center",
+        alignItems: "flex-start",
+        flexWrap: "wrap"
+      }}>
+        {/* Left Option */}
+        <TangramOption
+          tangram={tangramLeft}
+          buttonText={buttonTextLeft}
+          onClick={() => handleResponse("left")}
+          disabled={hasResponded}
+          showDecomposition={showTangramDecomposition}
+          usePrimitiveColors={usePrimitiveColors}
+          primitiveColorIndices={primitiveColorIndices}
+        />
+
+        {/* Right Option */}
+        <TangramOption
+          tangram={tangramRight}
+          buttonText={buttonTextRight}
+          onClick={() => handleResponse("right")}
+          disabled={hasResponded}
+          showDecomposition={showTangramDecomposition}
+          usePrimitiveColors={usePrimitiveColors}
+          primitiveColorIndices={primitiveColorIndices}
+        />
+      </div>
+    </div>
+  );
+}
+
+interface TangramOptionProps {
+  tangram: any;
+  buttonText: string;
+  onClick: () => void;
+  disabled: boolean;
+  showDecomposition?: boolean;
+  usePrimitiveColors?: boolean;
+  primitiveColorIndices?: number[];
+}
+
+function TangramOption({
+  tangram,
+  buttonText,
+  onClick,
+  disabled,
+  showDecomposition,
+  usePrimitiveColors,
+  primitiveColorIndices
+}: TangramOptionProps) {
+
+  if (!tangram) {
+    return <div style={{ width: 300, height: 300, background: "#eee" }}>No Tangram Data</div>;
+  }
+
+  // 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
+  const DISPLAY_SIZE = 300;
+  const viewport = {
+    w: DISPLAY_SIZE,
+    h: DISPLAY_SIZE
+  };
+
+  // Compute scale factor
+  const scaleS = React.useMemo(() => {
+    const u = inferUnitFromPolys(mask);
+    return u ? (CONFIG.layout.grid.unitPx / u) : 1;
+  }, [mask]);
+
+  const centerPos = {
+    cx: viewport.w / 2,
+    cy: viewport.h / 2
+  };
+
+  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";
+  };
+
+  const renderSilhouette = () => {
+    if (showDecomposition) {
+      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) => {
+            const primInfo = primitiveDecomposition[i];
+            let fillColor = CONFIG.color.silhouetteMask;
+
+            if (usePrimitiveColors && primInfo?.kind && primitiveColorIndices) {
+              const kindToIndex: Record<TanKind, number> = {
+                'square': 0,
+                'smalltriangle': 1,
+                'parallelogram': 2,
+                'medtriangle': 3,
+                'largetriangle': 4
+              };
+              const primitiveIndex = kindToIndex[primInfo.kind as TanKind];
+              if (primitiveIndex !== undefined && primitiveColorIndices[primitiveIndex] !== undefined) {
+                const colorIndex = primitiveColorIndices[primitiveIndex];
+                const color = CONFIG.color.primitiveColors[colorIndex];
+                if (color) {
+                  fillColor = color;
+                }
+              }
+            }
+
+            return (
+              <React.Fragment key={`prim-${i}`}>
+                <path
+                  d={pathD(scaledPoly)}
+                  fill={fillColor}
+                  opacity={usePrimitiveColors ? CONFIG.opacity.piece.normal : CONFIG.opacity.silhouetteMask}
+                  stroke="none"
+                />
+                <path
+                  d={pathD(scaledPoly)}
+                  fill="none"
+                  stroke={CONFIG.color.tangramDecomposition.stroke}
+                  strokeWidth={CONFIG.size.stroke.tangramDecompositionPx}
+                />
+              </React.Fragment>
+            );
+          })}
+        </g>
+      );
+    } else {
+      const placedPolys = placeSilhouetteGridAlignedAsPolys(mask, scaleS, centerPos);
+
+      return (
+        <g key="sil-unified" pointerEvents="none">
+          {placedPolys.map((scaledPoly, i) => {
+            const primInfo = primitiveDecomposition[i];
+            let fillColor = CONFIG.color.silhouetteMask;
+
+            if (usePrimitiveColors && primInfo?.kind && primitiveColorIndices) {
+              const kindToIndex: Record<TanKind, number> = {
+                'square': 0,
+                'smalltriangle': 1,
+                'parallelogram': 2,
+                'medtriangle': 3,
+                'largetriangle': 4
+              };
+              const primitiveIndex = kindToIndex[primInfo.kind as TanKind];
+              if (primitiveIndex !== undefined && primitiveColorIndices[primitiveIndex] !== undefined) {
+                const colorIndex = primitiveColorIndices[primitiveIndex];
+                const color = CONFIG.color.primitiveColors[colorIndex];
+                if (color) {
+                  fillColor = color;
+                }
+              }
+            }
+
+            return (
+              <path
+                key={`sil-${i}`}
+                d={pathD(scaledPoly)}
+                fill={fillColor}
+                opacity={usePrimitiveColors ? CONFIG.opacity.piece.normal : CONFIG.opacity.silhouetteMask}
+                stroke="none"
+              />
+            );
+          })}
+        </g>
+      );
+    }
+  };
+
+  return (
+    <div style={{
+      display: "flex",
+      flexDirection: "column",
+      alignItems: "center",
+      gap: "20px"
+    }}>
+      <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>
+
+      <button
+        className="jspsych-btn"
+        onClick={onClick}
+        disabled={disabled}
+        style={{
+          padding: "12px 30px",
+          fontSize: "16px",
+          cursor: disabled ? "not-allowed" : "pointer",
+          opacity: disabled ? 0.5 : 1
+        }}
+      >
+        {buttonText}
+      </button>
+    </div>
+  );
+}

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

@@ -0,0 +1,140 @@
+import { JsPsych, JsPsychPlugin, ParameterType, TrialType } from "jspsych";
+import { startAFCTrial, StartAFCTrialParams } from "./AFCApp";
+
+const info = {
+  name: "tangram-afc",
+  version: "1.0.0",
+  parameters: {
+    /** Left tangram specification to display */
+    tangram_left: {
+      type: ParameterType.COMPLEX,
+      default: undefined,
+      description: "TangramSpec object defining left target shape to display"
+    },
+    /** Right tangram specification to display */
+    tangram_right: {
+      type: ParameterType.COMPLEX,
+      default: undefined,
+      description: "TangramSpec object defining right target shape to display"
+    },
+    /** HTML content to display above the tangrams as instructions */
+    instructions: {
+      type: ParameterType.STRING,
+      default: "",
+      description: "HTML content to display above the tangrams as instructions"
+    },
+    /** Text to display on left response button */
+    button_text_left: {
+      type: ParameterType.STRING,
+      default: "Select Left",
+      description: "Text to display on left response button"
+    },
+    /** Text to display on right response button */
+    button_text_right: {
+      type: ParameterType.STRING,
+      default: "Select Right",
+      description: "Text to display on right response button"
+    },
+    /** 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"
+    },
+    /** Whether to use distinct colors for each primitive shape type */
+    use_primitive_colors: {
+      type: ParameterType.BOOL,
+      default: false,
+      description: "Whether each primitive shape type should have its own distinct color in the displayed tangram"
+    },
+    /** Indices mapping primitives to colors from the color palette */
+    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: {
+    /** Reaction time in milliseconds */
+    rt: {
+      type: ParameterType.INT,
+      description: "Milliseconds between trial start and button click"
+    },
+    /** Response choice */
+    response: {
+      type: ParameterType.STRING,
+      description: "Which button was clicked: 'left' or 'right'"
+    }
+  },
+  citations: ""
+};
+
+type Info = typeof info;
+
+/**
+ * **tangram-afc**
+ *
+ * A jsPsych plugin for alternative forced choice (AFC) trials displaying two tangrams
+ * side-by-side with response buttons.
+ *
+ * @author Justin Yang & Sean Paul Anderson
+ * @see {@link https://github.com/cogtoolslab/tangram_construction.git/tree/main/experiments/jspsych-tangram-prep}
+ */
+class TangramAFCPlugin implements JsPsychPlugin<Info> {
+  static info = info;
+
+  constructor(private jsPsych: JsPsych) {}
+
+  /**
+   * Launches the trial by invoking startAFCTrial
+   * 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: StartAFCTrialParams = {
+      tangramLeft: trial.tangram_left,
+      tangramRight: trial.tangram_right,
+      instructions: trial.instructions,
+      buttonTextLeft: trial.button_text_left,
+      buttonTextRight: trial.button_text_right,
+      showTangramDecomposition: 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 } = startAFCTrial(display_element, params, this.jsPsych);
+
+    // Store React context for cleanup
+    (element as any).__reactContext = { root, jsPsych };
+  }
+}
+
+export default TangramAFCPlugin;

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

@@ -247,7 +247,7 @@ function NBackView({ params }: NBackViewProps) {
                 <path
                   d={pathD(scaledPoly)}
                   fill={fillColor}
-                  opacity={CONFIG.opacity.silhouetteMask}
+                  opacity={usePrimitiveColors ? CONFIG.opacity.piece.normal : CONFIG.opacity.silhouetteMask}
                   stroke="none"
                 />
 
@@ -298,7 +298,7 @@ function NBackView({ params }: NBackViewProps) {
                 key={`sil-${i}`}
                 d={pathD(scaledPoly)}
                 fill={fillColor}
-                opacity={CONFIG.opacity.silhouetteMask}
+                opacity={usePrimitiveColors ? CONFIG.opacity.piece.normal : CONFIG.opacity.silhouetteMask}
                 stroke="none"
               />
             );