jspsych-tangram 0.0.16 → 0.0.18

package/dist/grid/index.d.ts

@@ -0,0 +1,174 @@
+import { JsPsychPlugin, ParameterType, JsPsych, TrialType } from 'jspsych';
+
+declare const info: {
+    name: string;
+    version: string;
+    parameters: {
+        /** Array of tangram specifications to display in the grid */
+        tangrams: {
+            type: ParameterType;
+            default: undefined;
+            description: string;
+        };
+        /** Number of rows in the grid */
+        n_rows: {
+            type: ParameterType;
+            default: number;
+            description: string;
+        };
+        /** Number of columns in the grid */
+        n_cols: {
+            type: ParameterType;
+            default: number;
+            description: string;
+        };
+        /** Prompt text displayed above the text input */
+        prompt_text: {
+            type: ParameterType;
+            default: string;
+            description: string;
+        };
+        /** Label for the submit button */
+        button_text: {
+            type: ParameterType;
+            default: string;
+            description: string;
+        };
+        /** Whether to show tangrams decomposed into primitives */
+        show_tangram_decomposition: {
+            type: ParameterType;
+            default: boolean;
+            description: string;
+        };
+        /** Whether to use distinct colors for each primitive type */
+        use_primitive_colors: {
+            type: ParameterType;
+            default: boolean;
+            description: string;
+        };
+        /** Indices mapping primitives to colors */
+        primitive_color_indices: {
+            type: ParameterType;
+            default: number[];
+            description: string;
+        };
+        /** Callback fired when trial ends */
+        onTrialEnd: {
+            type: ParameterType;
+            default: undefined;
+            description: string;
+        };
+    };
+    data: {
+        /** The text response entered by the participant */
+        response: {
+            type: ParameterType;
+            description: string;
+        };
+        /** Reaction time from trial start to submit button click */
+        rt: {
+            type: ParameterType;
+            description: string;
+        };
+    };
+    citations: string;
+};
+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}
+ */
+declare class TangramGridPlugin implements JsPsychPlugin<Info> {
+    private jsPsych;
+    static info: {
+        name: string;
+        version: string;
+        parameters: {
+            /** Array of tangram specifications to display in the grid */
+            tangrams: {
+                type: ParameterType;
+                default: undefined;
+                description: string;
+            };
+            /** Number of rows in the grid */
+            n_rows: {
+                type: ParameterType;
+                default: number;
+                description: string;
+            };
+            /** Number of columns in the grid */
+            n_cols: {
+                type: ParameterType;
+                default: number;
+                description: string;
+            };
+            /** Prompt text displayed above the text input */
+            prompt_text: {
+                type: ParameterType;
+                default: string;
+                description: string;
+            };
+            /** Label for the submit button */
+            button_text: {
+                type: ParameterType;
+                default: string;
+                description: string;
+            };
+            /** Whether to show tangrams decomposed into primitives */
+            show_tangram_decomposition: {
+                type: ParameterType;
+                default: boolean;
+                description: string;
+            };
+            /** Whether to use distinct colors for each primitive type */
+            use_primitive_colors: {
+                type: ParameterType;
+                default: boolean;
+                description: string;
+            };
+            /** Indices mapping primitives to colors */
+            primitive_color_indices: {
+                type: ParameterType;
+                default: number[];
+                description: string;
+            };
+            /** Callback fired when trial ends */
+            onTrialEnd: {
+                type: ParameterType;
+                default: undefined;
+                description: string;
+            };
+        };
+        data: {
+            /** The text response entered by the participant */
+            response: {
+                type: ParameterType;
+                description: string;
+            };
+            /** Reaction time from trial start to submit button click */
+            rt: {
+                type: ParameterType;
+                description: string;
+            };
+        };
+        citations: string;
+    };
+    constructor(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>): void;
+}
+
+export { TangramGridPlugin as default };

package/dist/grid/index.js

@@ -0,0 +1,545 @@
+import { ParameterType } from 'jspsych';
+import React, { useRef, useState, useEffect, useMemo } from 'react';
+import { createRoot } from 'react-dom/client';
+
+const CONFIG = {
+  color: {
+    background: "#fff7e0ff",
+    bands: {
+      silhouette: { fillEven: "#ffffff", stroke: "#b1b1b1" }},
+    // validFill used here for placed composites
+    piece: { validFill: "#8e7cc3"},
+    tangramDecomposition: { stroke: "#fef2cc" },
+    primitiveColors: [
+      // from seaborn "colorblind" palette, 6 colors, with red omitted
+      "#0173b2",
+      "#de8f05",
+      "#029e73",
+      "#cc78bc",
+      "#ca9161"
+    ]
+  },
+  opacity: {
+    piece: { normal: 1 }
+  },
+  size: {
+    stroke: { bandPx: 5, tangramDecompositionPx: 1 }}};
+
+function startGridTrial(display_element, params, _jsPsych) {
+  const root = createRoot(display_element);
+  root.render(React.createElement(GridView, { params }));
+  return { root, display_element, jsPsych: _jsPsych };
+}
+function computeBounds(polys) {
+  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 };
+}
+function GridView({ params }) {
+  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(Date.now());
+  const [response, setResponse] = useState("");
+  const [cellSize, setCellSize] = useState(100);
+  const controlsRef = useRef(null);
+  const GRID_GAP = 6;
+  const CONTAINER_PADDING = 8;
+  const CELL_MARGIN = 0.05;
+  const PROGRESS_BAR_HEIGHT = 58;
+  const CELL_BORDER = CONFIG.size.stroke.bandPx;
+  const SAFETY_BUFFER = 8;
+  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();
+    };
+  }, []);
+  const CANON = /* @__PURE__ */ new Set([
+    "square",
+    "smalltriangle",
+    "parallelogram",
+    "medtriangle",
+    "largetriangle"
+  ]);
+  const processedTangrams = useMemo(() => {
+    return tangrams.map((tangramSpec) => {
+      const filteredTans = tangramSpec.solutionTans.filter((tan) => {
+        const tanName = tan.name ?? tan.kind;
+        return CANON.has(tanName);
+      });
+      const mask = filteredTans.map((tan) => {
+        return tan.vertices.map(([x, y]) => ({
+          x: x ?? 0,
+          y: -(y ?? 0)
+        }));
+      });
+      const primitiveDecomposition = filteredTans.map((tan) => ({
+        kind: tan.name ?? tan.kind,
+        polygon: tan.vertices.map(([x, y]) => ({
+          x: x ?? 0,
+          y: -(y ?? 0)
+        }))
+      }));
+      return {
+        tangramId: tangramSpec.tangramID,
+        mask,
+        primitiveDecomposition
+      };
+    });
+  }, [tangrams]);
+  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]);
+  useEffect(() => {
+    const calculateCellSize = () => {
+      const viewportWidth = document.documentElement.clientWidth;
+      const viewportHeight = document.documentElement.clientHeight;
+      const controlsHeight = controlsRef.current?.offsetHeight ?? 70;
+      const availableWidth = viewportWidth - CONTAINER_PADDING * 2 - SAFETY_BUFFER;
+      const availableHeight = viewportHeight - PROGRESS_BAR_HEIGHT - controlsHeight - CONTAINER_PADDING * 2 - SAFETY_BUFFER;
+      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;
+      const maxCellWidth = (availableWidth - totalHorizontalGaps - totalHorizontalBorders) / n_cols;
+      const maxCellHeight = (availableHeight - totalVerticalGaps - totalVerticalBorders) / n_rows;
+      const newCellSize = Math.floor(Math.min(maxCellWidth, maxCellHeight));
+      setCellSize(Math.max(newCellSize, 50));
+    };
+    calculateCellSize();
+    window.addEventListener("resize", calculateCellSize);
+    return () => window.removeEventListener("resize", calculateCellSize);
+  }, [n_rows, n_cols]);
+  const tangramScale = useMemo(() => {
+    const usableSize = cellSize * (1 - CELL_MARGIN * 2);
+    return usableSize / maxTangramExtent;
+  }, [cellSize, maxTangramExtent]);
+  const kindToIndex = {
+    square: 0,
+    smalltriangle: 1,
+    parallelogram: 2,
+    medtriangle: 3,
+    largetriangle: 4
+  };
+  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 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);
+    }
+  };
+  const renderTangram = (tangramData, index) => {
+    const { mask, primitiveDecomposition } = tangramData;
+    if (show_tangram_decomposition) {
+      const scaledPrimitives = primitiveDecomposition.map(
+        (prim) => {
+          const scaledPoly = prim.polygon.map((p) => ({
+            x: p.x * tangramScale,
+            y: p.y * tangramScale
+          }));
+          return { kind: prim.kind, polygon: scaledPoly };
+        }
+      );
+      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);
+        }
+      }
+      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: prim.kind,
+          polygon: prim.polygon.map((p) => ({
+            x: p.x + tx,
+            y: p.y + ty
+          }))
+        })
+      );
+      return /* @__PURE__ */ React.createElement(
+        "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, i) => {
+            let fillColor;
+            if (usePrimitiveColors) {
+              const primitiveIndex = kindToIndex[prim.kind];
+              if (primitiveIndex !== void 0 && primitiveColorIndices[primitiveIndex] !== void 0) {
+                const colorIndex = primitiveColorIndices[primitiveIndex];
+                const color = CONFIG.color.primitiveColors[colorIndex];
+                fillColor = color || CONFIG.color.piece.validFill;
+              } else {
+                fillColor = CONFIG.color.piece.validFill;
+              }
+            } else {
+              fillColor = CONFIG.color.piece.validFill;
+            }
+            return /* @__PURE__ */ React.createElement(
+              "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
+              }
+            );
+          }
+        )
+      );
+    } else {
+      const scaledMask = mask.map(
+        (poly) => poly.map((p) => ({
+          x: p.x * tangramScale,
+          y: p.y * tangramScale
+        }))
+      );
+      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);
+        }
+      }
+      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 /* @__PURE__ */ React.createElement(
+        "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) => /* @__PURE__ */ React.createElement(
+          "path",
+          {
+            key: `sil-${i}`,
+            d: pathD(poly),
+            fill: CONFIG.color.piece.validFill,
+            opacity: CONFIG.opacity.piece.normal,
+            stroke: "none"
+          }
+        ))
+      );
+    }
+  };
+  const isSubmitDisabled = response.trim().length === 0;
+  return /* @__PURE__ */ React.createElement(
+    "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`
+      }
+    },
+    /* @__PURE__ */ React.createElement(
+      "div",
+      {
+        style: {
+          flex: "1 1 auto",
+          display: "flex",
+          alignItems: "center",
+          justifyContent: "center",
+          minHeight: 0
+        }
+      },
+      /* @__PURE__ */ React.createElement(
+        "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)
+        )
+      )
+    ),
+    /* @__PURE__ */ React.createElement(
+      "div",
+      {
+        ref: controlsRef,
+        style: {
+          flex: "0 0 auto",
+          display: "flex",
+          flexDirection: "column",
+          alignItems: "center",
+          gap: "4px",
+          paddingTop: "4px"
+        }
+      },
+      /* @__PURE__ */ React.createElement(
+        "div",
+        {
+          style: {
+            fontSize: "14px",
+            textAlign: "center",
+            maxWidth: "90vw"
+          }
+        },
+        prompt_text
+      ),
+      /* @__PURE__ */ React.createElement(
+        "div",
+        {
+          style: {
+            display: "flex",
+            alignItems: "center",
+            gap: "12px"
+          }
+        },
+        /* @__PURE__ */ React.createElement(
+          "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..."
+          }
+        ),
+        /* @__PURE__ */ React.createElement(
+          "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
+        )
+      )
+    )
+  );
+}
+
+const info = {
+  name: "tangram-grid",
+  version: "1.0.0",
+  parameters: {
+    /** Array of tangram specifications to display in the grid */
+    tangrams: {
+      type: ParameterType.COMPLEX,
+      default: void 0,
+      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: void 0,
+      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: ""
+};
+class TangramGridPlugin {
+  constructor(jsPsych) {
+    this.jsPsych = jsPsych;
+  }
+  static {
+    this.info = info;
+  }
+  /**
+   * 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, 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 = {
+      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
+    };
+    const { root, display_element: element, jsPsych } = startGridTrial(
+      display_element,
+      params,
+      this.jsPsych
+    );
+    element.__reactContext = { root, jsPsych };
+  }
+}
+
+export { TangramGridPlugin as default };
+//# sourceMappingURL=index.js.map