jspsych-tangram 0.0.16 → 0.0.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jspsych-tangram",
-  "version": "0.0.16",
+  "version": "0.0.18",
   "description": "Tangram tasks for jsPsych: prep and construct.",
   "type": "module",
   "main": "dist/index.cjs",

package/src/core/components/board/GameBoard.tsx

@@ -378,6 +378,18 @@ export default function GameBoard(props: GameBoardProps) {
     };
   }, [sectors, layoutMode, target, maxQuickstashSlots, primitives.length]);
 
+  // Update tracker with sector centers whenever layout changes
+  React.useEffect(() => {
+    if (tracker && layout) {
+      const centers: { [sectorId: string]: { x: number; y: number } } = {};
+      layout.sectors.forEach(s => {
+        const rect = rectForBand(layout, s, "silhouette", 1.0);
+        centers[s.id] = { x: rect.cx, y: rect.cy };
+      });
+      tracker.setSectorCenters(centers);
+    }
+  }, [tracker, layout]);
+
   // Force re-render utility
   const [, force] = React.useReducer((x) => x + 1, 0);
 

package/src/core/io/InteractionTracker.ts

@@ -99,7 +99,10 @@ export class InteractionTracker {
 
   // Trial timing
   private trialStartTime: number;
-  private readonly gridStep: number = CONFIG.layout.grid.stepPx;
+  private completionTimes: Array<{ sectorId: string; completedAt: number }> = [];
+
+  // Sector centers (set by GameBoard after layout computation)
+  private sectorCenters: { [sectorId: string]: { x: number; y: number } } = {};
 
   // Interaction state
   private interactionIndex: number = 0;
@@ -113,21 +116,22 @@ export class InteractionTracker {
   // Interaction history (for TrialEndData)
   private interactions: InteractionEvent[] = [];
 
-  // Construction-specific tracking
-  private completionTimes: Array<{ sectorId: string; completedAt: number }> = [];
-
   // Prep-specific tracking
   private createdMacros: MacroSnapshot[] = [];
 
+  // Grid step for coordinate conversion
+  private gridStep: number;
+
   constructor(
     controller: BaseGameController,
     callbacks: DataTrackingCallbacks,
-    trialParams?: any
+    trialParams: any
   ) {
     this.controller = controller;
     this.callbacks = callbacks;
     this.trialParams = trialParams;
     this.trialStartTime = Date.now();
+    this.gridStep = CONFIG.layout.grid.stepPx;
 
     // Register tracking callbacks with controller
     this.controller.setTrackingCallbacks({
@@ -325,7 +329,14 @@ export class InteractionTracker {
   }
 
   /**
-   * Record sector completion
+   * Set sector centers (for anchor alignment)
+   */
+  setSectorCenters(centers: { [sectorId: string]: { x: number; y: number } }): void {
+    this.sectorCenters = centers;
+  }
+
+  /**
+   * Record a sector completion event
    */
   recordSectorCompletion(sectorId: string): void {
     this.completionTimes.push({
@@ -557,7 +568,8 @@ export class InteractionTracker {
         sectorId: sector.id,
         completed,
         pieceCount: pieces.length,
-        pieces
+        pieces,
+        center: this.sectorCenters[sector.id] ? this.toAnchorPoint(this.sectorCenters[sector.id]) : undefined
       };
 
       if (sectorState?.completedAt !== undefined) {

package/src/core/io/data-tracking.ts

@@ -146,6 +146,10 @@ export interface ConstructionTrialData extends BaseTrialData {
     completedAt: number;          // timestamp in ms (Date.now())
   }>;
 
+  // Sector centers (computed layout positions)
+  // Removed in favor of SectorSnapshot.center
+  // sectorCenters?: { [sectorId: string]: { x: number; y: number } };
+
   // Final blueprint state (usage counts + definitions)
   finalBlueprintState: Array<{
     blueprintId: string;
@@ -212,6 +216,7 @@ export interface SectorSnapshot {
   completedAt?: number;           // timestamp in ms (Date.now()) (undefined if not completed)
   pieceCount: number;
   pieces: PieceSnapshot[];
+  center?: { x: number; y: number }; // Center of sector in anchor coordinates
 }
 
 /**

package/src/index.ts

@@ -1,4 +1,5 @@
 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 TangramAFCPlugin } from "./plugins/tangram-afc";
+export { default as TangramAFCPlugin } from "./plugins/tangram-afc";
+export { default as TangramGridPlugin } from "./plugins/tangram-grid";

package/src/plugins/tangram-grid/GridApp.tsx

@@ -0,0 +1,522 @@
+/**
+ * GridApp.tsx - React wrapper for tangram grid display with text input
+ *
+ * This component displays a grid of tangrams with a text input field
+ * and submit button for collecting free-text responses.
+ */
+
+import React, { useRef, useState, useMemo, useEffect } from "react";
+import { createRoot } from "react-dom/client";
+import { JsPsych } from "jspsych";
+import type { Poly, TanKind } from "../../core/domain/types";
+import { CONFIG } from "../../core/config/config";
+
+export interface StartGridTrialParams {
+  tangrams: any[];
+  n_rows: number;
+  n_cols: number;
+  prompt_text: string;
+  button_text: string;
+  show_tangram_decomposition?: boolean;
+  usePrimitiveColors?: boolean;
+  primitiveColorIndices?: number[];
+  onTrialEnd?: (data: any) => void;
+}
+
+/**
+ * Start a grid trial by rendering the GridView component
+ *
+ * REQUIRES: display_element is a valid HTMLElement
+ * MODIFIES: display_element (renders React into it)
+ * EFFECTS: Creates a React root and renders GridView with the given params
+ */
+export function startGridTrial(
+  display_element: HTMLElement,
+  params: StartGridTrialParams,
+  _jsPsych: JsPsych
+) {
+  const root = createRoot(display_element);
+  root.render(React.createElement(GridView, { params }));
+  return { root, display_element, jsPsych: _jsPsych };
+}
+
+interface GridViewProps {
+  params: StartGridTrialParams;
+}
+
+/**
+ * Compute bounding box for an array of polygons
+ *
+ * REQUIRES: polys is an array of polygons with {x, y} points
+ * MODIFIES: nothing
+ * EFFECTS: Returns {minX, minY, maxX, maxY, width, height} of bounding box
+ */
+function computeBounds(polys: Poly[]) {
+  let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
+  for (const poly of polys) {
+    for (const p of poly) {
+      minX = Math.min(minX, p.x);
+      minY = Math.min(minY, p.y);
+      maxX = Math.max(maxX, p.x);
+      maxY = Math.max(maxY, p.y);
+    }
+  }
+  return { minX, minY, maxX, maxY, width: maxX - minX, height: maxY - minY };
+}
+
+/**
+ * GridView - Main React component for the grid trial
+ *
+ * REQUIRES: params contains valid tangram specs and grid dimensions
+ * MODIFIES: nothing
+ * EFFECTS: Renders a grid of tangrams, text input, and submit button;
+ *          calls onTrialEnd with response data when submitted
+ */
+function GridView({ params }: GridViewProps) {
+  const {
+    tangrams,
+    n_rows,
+    n_cols,
+    prompt_text,
+    button_text,
+    show_tangram_decomposition = false,
+    usePrimitiveColors = false,
+    primitiveColorIndices = [0, 1, 2, 3, 4],
+    onTrialEnd
+  } = params;
+
+  const trialStartTime = useRef<number>(Date.now());
+  const [response, setResponse] = useState<string>("");
+  const [cellSize, setCellSize] = useState<number>(100);
+  const controlsRef = useRef<HTMLDivElement>(null);
+
+  // Layout constants
+  const GRID_GAP = 6;
+  const CONTAINER_PADDING = 8;
+  const CELL_MARGIN = 0.05; // 5% margin inside cell for tangram
+  // jsPsych progress bar: 20px height + 8px top/bottom padding + 18px margin
+  const PROGRESS_BAR_HEIGHT = 58;
+  // Border width on each cell (from CONFIG.size.stroke.bandPx)
+  const CELL_BORDER = CONFIG.size.stroke.bandPx ?? 1;
+  // Extra buffer to prevent scrollbars from appearing
+  const SAFETY_BUFFER = 8;
+
+  // Inject style to override jspsych-content max-width constraint
+  useEffect(() => {
+    const styleId = "tangram-grid-jspsych-override";
+    if (!document.getElementById(styleId)) {
+      const style = document.createElement("style");
+      style.id = styleId;
+      style.textContent = `
+        .jspsych-content {
+          max-width: 100% !important;
+          width: 100% !important;
+        }
+      `;
+      document.head.appendChild(style);
+    }
+    return () => {
+      const style = document.getElementById(styleId);
+      if (style) style.remove();
+    };
+  }, []);
+
+  // Canonical piece names
+  const CANON = new Set([
+    "square",
+    "smalltriangle",
+    "parallelogram",
+    "medtriangle",
+    "largetriangle"
+  ]);
+
+  // Convert TangramSpec to internal format with mask and decomposition
+  const processedTangrams = useMemo(() => {
+    return tangrams.map((tangramSpec) => {
+      const filteredTans = tangramSpec.solutionTans.filter((tan: any) => {
+        const tanName = tan.name ?? tan.kind;
+        return CANON.has(tanName);
+      });
+
+      const mask: Poly[] = filteredTans.map((tan: any) => {
+        return tan.vertices.map(([x, y]: number[]) => ({
+          x: x ?? 0,
+          y: -(y ?? 0)
+        }));
+      });
+
+      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)
+        }))
+      }));
+
+      return {
+        tangramId: tangramSpec.tangramID,
+        mask,
+        primitiveDecomposition
+      };
+    });
+  }, [tangrams]);
+
+  // Find the largest tangram dimensions to determine scaling
+  const maxTangramExtent = useMemo(() => {
+    let maxExtent = 0;
+    for (const t of processedTangrams) {
+      const bounds = computeBounds(t.mask);
+      maxExtent = Math.max(maxExtent, bounds.width, bounds.height);
+    }
+    return maxExtent || 1;
+  }, [processedTangrams]);
+
+  // Calculate cell size based on available space
+  useEffect(() => {
+    const calculateCellSize = () => {
+      // Use document.documentElement for more accurate viewport size
+      const viewportWidth = document.documentElement.clientWidth;
+      const viewportHeight = document.documentElement.clientHeight;
+
+      // Reserve space for controls (prompt + input row) and progress bar
+      const controlsHeight = controlsRef.current?.offsetHeight ?? 70;
+
+      // Available space for the grid (subtract progress bar, controls, padding, buffer)
+      const availableWidth =
+        viewportWidth - CONTAINER_PADDING * 2 - SAFETY_BUFFER;
+      const availableHeight =
+        viewportHeight - PROGRESS_BAR_HEIGHT - controlsHeight -
+        CONTAINER_PADDING * 2 - SAFETY_BUFFER;
+
+      // Account for gaps between cells AND borders on each cell
+      // Each cell has border on all sides, so total border per cell = 2 * CELL_BORDER
+      const totalHorizontalGaps = GRID_GAP * (n_cols - 1);
+      const totalVerticalGaps = GRID_GAP * (n_rows - 1);
+      const totalHorizontalBorders = CELL_BORDER * 2 * n_cols;
+      const totalVerticalBorders = CELL_BORDER * 2 * n_rows;
+
+      // Calculate max cell size that fits in available space
+      const maxCellWidth =
+        (availableWidth - totalHorizontalGaps - totalHorizontalBorders) / n_cols;
+      const maxCellHeight =
+        (availableHeight - totalVerticalGaps - totalVerticalBorders) / n_rows;
+
+      // Use the smaller dimension to keep cells square
+      const newCellSize = Math.floor(Math.min(maxCellWidth, maxCellHeight));
+      setCellSize(Math.max(newCellSize, 50)); // Minimum 50px
+    };
+
+    calculateCellSize();
+    window.addEventListener("resize", calculateCellSize);
+    return () => window.removeEventListener("resize", calculateCellSize);
+  }, [n_rows, n_cols]);
+
+  // Scale factor to fit largest tangram in cell with margin
+  const tangramScale = useMemo(() => {
+    const usableSize = cellSize * (1 - CELL_MARGIN * 2);
+    return usableSize / maxTangramExtent;
+  }, [cellSize, maxTangramExtent]);
+
+  // Mapping from TanKind to color index
+  const kindToIndex: Record<TanKind, number> = {
+    square: 0,
+    smalltriangle: 1,
+    parallelogram: 2,
+    medtriangle: 3,
+    largetriangle: 4
+  };
+
+  // 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";
+  };
+
+  // Handle submit
+  const handleSubmit = () => {
+    const rt = Date.now() - trialStartTime.current;
+    const trialData = {
+      response,
+      rt,
+      n_rows,
+      n_cols,
+      tangram_ids: processedTangrams.map((t) => t.tangramId),
+      show_tangram_decomposition,
+      use_primitive_colors: usePrimitiveColors,
+      primitive_color_indices: primitiveColorIndices
+    };
+    if (onTrialEnd) {
+      onTrialEnd(trialData);
+    }
+  };
+
+  // Render a single tangram SVG
+  const renderTangram = (
+    tangramData: (typeof processedTangrams)[0],
+    index: number
+  ) => {
+    const { mask, primitiveDecomposition } = tangramData;
+
+    if (show_tangram_decomposition) {
+      // Show individual primitives with optional coloring
+      // Scale each primitive and fit to viewport while preserving relative positions
+      const scaledPrimitives = primitiveDecomposition.map(
+        (prim: { kind: TanKind; polygon: Poly }) => {
+          const scaledPoly = prim.polygon.map((p: { x: number; y: number }) => ({
+            x: p.x * tangramScale,
+            y: p.y * tangramScale
+          }));
+          return { kind: prim.kind, polygon: scaledPoly };
+        }
+      );
+
+      // Find bounds of all primitives together
+      let minX = Infinity,
+        minY = Infinity,
+        maxX = -Infinity,
+        maxY = -Infinity;
+      for (const prim of scaledPrimitives) {
+        for (const p of prim.polygon) {
+          minX = Math.min(minX, p.x);
+          minY = Math.min(minY, p.y);
+          maxX = Math.max(maxX, p.x);
+          maxY = Math.max(maxY, p.y);
+        }
+      }
+
+      // Compute translation to center all primitives together in viewport
+      const width = maxX - minX;
+      const height = maxY - minY;
+      const tx = cellSize / 2 - (minX + width / 2);
+      const ty = cellSize / 2 - (minY + height / 2);
+
+      const translatedPrimitives = scaledPrimitives.map(
+        (prim: { kind: TanKind; polygon: Poly }) => ({
+          kind: prim.kind,
+          polygon: prim.polygon.map((p: { x: number; y: number }) => ({
+            x: p.x + tx,
+            y: p.y + ty
+          }))
+        })
+      );
+
+      return (
+        <svg
+          key={index}
+          width={cellSize}
+          height={cellSize}
+          viewBox={`0 0 ${cellSize} ${cellSize}`}
+          style={{
+            display: "block",
+            background: CONFIG.color.bands.silhouette.fillEven,
+            border: `${CONFIG.size.stroke.bandPx}px solid ${CONFIG.color.bands.silhouette.stroke}`,
+            borderRadius: "8px"
+          }}
+        >
+          {translatedPrimitives.map(
+            (prim: { kind: TanKind; polygon: Poly }, i: number) => {
+              let fillColor: string;
+
+              if (usePrimitiveColors) {
+                // Use primitive colors: map piece type to color via primitiveColorIndices
+                const primitiveIndex = kindToIndex[prim.kind];
+                if (
+                  primitiveIndex !== undefined &&
+                  primitiveColorIndices[primitiveIndex] !== undefined
+                ) {
+                  const colorIndex = primitiveColorIndices[primitiveIndex];
+                  const color = CONFIG.color.primitiveColors[colorIndex];
+                  fillColor = color || CONFIG.color.piece.validFill;
+                } else {
+                  fillColor = CONFIG.color.piece.validFill;
+                }
+              } else {
+                // Use default piece color when not using primitive colors
+                fillColor = CONFIG.color.piece.validFill;
+              }
+
+              return (
+                <path
+                  key={`prim-${i}`}
+                  d={pathD(prim.polygon)}
+                  fill={fillColor}
+                  opacity={CONFIG.opacity.piece.normal}
+                  stroke={CONFIG.color.tangramDecomposition.stroke}
+                  strokeWidth={CONFIG.size.stroke.tangramDecompositionPx}
+                />
+              );
+            }
+          )}
+        </svg>
+      );
+    } else {
+      // Show as silhouette (merged shape) - scale and center
+      const scaledMask = mask.map((poly) =>
+        poly.map((p) => ({
+          x: p.x * tangramScale,
+          y: p.y * tangramScale
+        }))
+      );
+
+      // Find bounds
+      let minX = Infinity,
+        minY = Infinity,
+        maxX = -Infinity,
+        maxY = -Infinity;
+      for (const poly of scaledMask) {
+        for (const p of poly) {
+          minX = Math.min(minX, p.x);
+          minY = Math.min(minY, p.y);
+          maxX = Math.max(maxX, p.x);
+          maxY = Math.max(maxY, p.y);
+        }
+      }
+
+      // Center in viewport
+      const width = maxX - minX;
+      const height = maxY - minY;
+      const tx = cellSize / 2 - (minX + width / 2);
+      const ty = cellSize / 2 - (minY + height / 2);
+
+      const placedMask = scaledMask.map((poly) =>
+        poly.map((p) => ({ x: p.x + tx, y: p.y + ty }))
+      );
+
+      return (
+        <svg
+          key={index}
+          width={cellSize}
+          height={cellSize}
+          viewBox={`0 0 ${cellSize} ${cellSize}`}
+          style={{
+            display: "block",
+            background: CONFIG.color.bands.silhouette.fillEven,
+            border: `${CONFIG.size.stroke.bandPx}px solid ${CONFIG.color.bands.silhouette.stroke}`,
+            borderRadius: "8px"
+          }}
+        >
+          {placedMask.map((poly, i) => (
+            <path
+              key={`sil-${i}`}
+              d={pathD(poly)}
+              fill={CONFIG.color.piece.validFill}
+              opacity={CONFIG.opacity.piece.normal}
+              stroke="none"
+            />
+          ))}
+        </svg>
+      );
+    }
+  };
+
+  const isSubmitDisabled = response.trim().length === 0;
+
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        alignItems: "center",
+        justifyContent: "space-between",
+        background: CONFIG.color.background,
+        width: "100%",
+        height: `calc(100vh - ${PROGRESS_BAR_HEIGHT}px)`,
+        overflow: "hidden",
+        fontFamily: "Roboto, sans-serif",
+        boxSizing: "border-box",
+        padding: `${CONTAINER_PADDING}px`
+      }}
+    >
+      {/* Grid of tangrams - takes up available space */}
+      <div
+        style={{
+          flex: "1 1 auto",
+          display: "flex",
+          alignItems: "center",
+          justifyContent: "center",
+          minHeight: 0
+        }}
+      >
+        <div
+          style={{
+            display: "grid",
+            gridTemplateColumns: `repeat(${n_cols}, ${cellSize}px)`,
+            gridTemplateRows: `repeat(${n_rows}, ${cellSize}px)`,
+            gap: `${GRID_GAP}px`
+          }}
+        >
+          {processedTangrams.slice(0, n_rows * n_cols).map((t, i) =>
+            renderTangram(t, i)
+          )}
+        </div>
+      </div>
+
+      {/* Controls section - fixed height at bottom */}
+      <div
+        ref={controlsRef}
+        style={{
+          flex: "0 0 auto",
+          display: "flex",
+          flexDirection: "column",
+          alignItems: "center",
+          gap: "4px",
+          paddingTop: "4px"
+        }}
+      >
+        {/* Prompt text */}
+        <div
+          style={{
+            fontSize: "14px",
+            textAlign: "center",
+            maxWidth: "90vw"
+          }}
+        >
+          {prompt_text}
+        </div>
+
+        {/* Text input and submit button side by side */}
+        <div
+          style={{
+            display: "flex",
+            alignItems: "center",
+            gap: "12px"
+          }}
+        >
+          <input
+            type="text"
+            value={response}
+            onChange={(e) => setResponse(e.target.value)}
+            style={{
+              width: "min(400px, 50vw)",
+              padding: "6px 10px",
+              fontSize: "14px",
+              borderRadius: "6px",
+              border: "2px solid #ccc",
+              fontFamily: "inherit",
+              boxSizing: "border-box"
+            }}
+            placeholder="Type your response here..."
+          />
+
+          <button
+            className="jspsych-btn"
+            onClick={handleSubmit}
+            disabled={isSubmitDisabled}
+            style={{
+              padding: "6px 16px",
+              fontSize: "13px",
+              cursor: isSubmitDisabled ? "not-allowed" : "pointer",
+              opacity: isSubmitDisabled ? 0.5 : 1,
+              flexShrink: 0
+            }}
+          >
+            {button_text}
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}