jspsych-tangram 0.0.11 → 0.0.13

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

@@ -1,30 +1,30 @@
 /**
  * GameBoard - Core reusable tangram game board component
- * 
+ *
  * This component provides the complete tangram game functionality that can be
  * shared between jsPsych plugins. It handles both construction and preparation
  * game modes with full interaction support.
- * 
+ *
  * ## Key Features
  * - **Dependency Injection**: All game content provided via props (no hardcoded data)
  * - **Multiple Input Modes**: Supports both click and drag interactions
  * - **Layout Flexibility**: Circle and semicircle layout modes
  * - **Event Tracking**: Comprehensive data collection for research
  * - **State Management**: Uses BaseGameController for robust state handling
- * 
+ *
  * ## Architecture
  * - Uses modern React patterns with hooks
  * - Integrates with BaseGameController for state management
  * - Renders via Board component with computed layout
  * - Handles completion events and data collection
- * 
+ *
  * ## Usage in Plugins
  * ```typescript
  * // In jsPsych plugin trial method:
  * const root = createRoot(display_element);
  * root.render(React.createElement(GameBoard, {
  *   sectors: convertedSectors,
- *   quickstash: convertedMacros, 
+ *   quickstash: convertedMacros,
  *   primitives: PRIMITIVE_BLUEPRINTS,
  *   layout: "semicircle",
  *   target: "silhouette",
@@ -32,7 +32,7 @@
  *   onComplete: handleTrialComplete
  * }));
  * ```
- * 
+ *
  * @see {@link BaseGameController} For state management details
  * @see {@link Board} For rendering implementation
  * @since Phase 3.3 - Extracted from monolithic Board component
@@ -41,9 +41,9 @@
 
 import React from "react";
 import { BaseGameController } from "@/core/engine/state/BaseGameController";
-import type { 
-  Sector, 
-  Blueprint, 
+import type {
+  Sector,
+  Blueprint,
   PrimitiveBlueprint,
   LayoutMode,
   PlacementTarget,
@@ -54,8 +54,8 @@ import { solveLogicalBox } from "@/core/domain/solve";
 import type { Poly } from "@/core/domain/types";
 import { CONFIG } from "@/core/config/config";
 import BoardView, { type AnchorDots as DotsType } from "./BoardView";
-import { 
-  inferUnitFromPolys, 
+import {
+  inferUnitFromPolys,
   placeSilhouetteGridAlignedAsPolys } from "@/core/engine/geometry";
 import { anchorsSilhouetteComplete, anchorsWorkspaceComplete } from "@/core/engine/validation/complete";
 import { scalePolys } from "@/core/components/board/utils";
@@ -67,109 +67,109 @@ import { InteractionTracker } from "@/core/io/InteractionTracker";
 
 /**
  * Configuration interface for GameBoard component
- * 
+ *
  * This interface defines all the required game content and behavior settings
- * that must be provided to the GameBoard component. All properties use 
+ * that must be provided to the GameBoard component. All properties use
  * dependency injection - no defaults are provided.
  */
 export interface GameBoardConfig {
-  /** 
+  /**
    * Array of sector definitions containing target silhouettes to construct
    * Each sector represents one puzzle to solve
    */
   sectors: Sector[];
-  
-  /** 
+
+  /**
    * Array of pre-made composite piece blueprints (macros)
    * Usually created in prep trials and passed to construction trials
    */
   quickstash: Blueprint[];
-  
-  /** 
+
+  /**
    * Array of primitive tangram piece definitions
    * These are the basic 7 tangram shapes that never change
    */
   primitives: PrimitiveBlueprint[];
-  
-  /** 
+
+  /**
    * Layout mode for the game board
    * - "circle": Full circular layout with pieces arranged in complete circle
    * - "semicircle": Half-circle layout with pieces in arc above workspace
    */
   layout: LayoutMode;
-  
-  /** 
+
+  /**
    * Target placement mode for piece validation
    * - "workspace": Pieces can be placed freely in workspace area
    * - "silhouette": Pieces must be placed within target silhouette bounds
    */
   target: PlacementTarget;
-  
-  /** 
+
+  /**
    * Input interaction mode
    * - "click": Click to select pieces, click to place (better for touch)
    * - "drag": Drag pieces directly with mouse/touch
    */
   input: InputMode;
-  
-  /** 
+
+  /**
    * Time limit for the trial in milliseconds
    * Set to 0 for no time limit
    */
   timeLimitMs: number;
-  
-  /** 
+
+  /**
    * Maximum number of quickstash/macro slots to display
    * Controls size of the macro selection ring
    */
   maxQuickstashSlots: number;
-  
-  /** 
+
+  /**
    * Maximum number of primitive pieces allowed in a composite
    * Used for validation when creating macros (prep mode only)
    */
   maxCompositeSize?: number;
-  
+
   /**
    * Game mode to determine behavior differences
    * - "construction": Standard puzzle-solving mode with toggle
    * - "prep": Macro creation mode with primitives-only center
    */
   mode?: "construction" | "prep";
-  
+
   /**
    * Minimum pieces required per macro (prep mode only)
    * Used for submit button validation
    */
   minPiecesPerMacro?: number;
-  
+
   /**
    * Whether all slots must be filled to complete trial (prep mode only)
    * Used for submit button validation
    */
   requireAllSlots?: boolean;
-  
+
   /**
    * Whether to show tangram target shapes decomposed into individual primitives with borders
    * Independent from showBorders/hideTouchingBorders (which control spawned pieces)
    */
   showTangramDecomposition?: boolean;
-  
+
   /**
    * HTML content to display above the gameboard as instructions
    * Allows rich formatting via HTML
    */
   instructions?: string;
-  
+
   /**
    * Cleaned jsPsych plugin parameters (excluding callbacks)
    * Saved to trial data for analysis
    */
   trialParams?: any;
-  
+
   /** Optional CSS width for the game board SVG */
   width?: number;
-  
+
   /** Optional CSS height for the game board SVG */
   height?: number;
 }
@@ -218,29 +218,47 @@ export interface GameBoardProps extends GameBoardConfig {
    * Useful for spawning initial pieces or setting up state
    */
   onControllerReady?: (controller: BaseGameController, layout?: any, force?: () => void) => void;
+
+  /**
+   * Whether to use distinct colors for each primitive shape type in blueprints
+   * When true, each primitive type (square, triangle, etc.) gets its own color in dock area
+   */
+  usePrimitiveColorsBlueprints?: boolean;
+
+  /**
+   * Whether to use distinct colors for each primitive shape type in target tangrams
+   * When true, each primitive type gets its own color in target silhouettes
+   */
+  usePrimitiveColorsTargets?: boolean;
+
+  /**
+   * Array of 5 integers mapping primitives to colors from CONFIG.color.primitiveColors
+   * Maps [square, smalltriangle, parallelogram, medtriangle, largetriangle] to color indices
+   */
+  primitiveColorIndices?: number[];
 }
 
 /**
  * Core GameBoard component that encapsulates all tangram game functionality
- * 
+ *
  * This is the main reusable component that provides complete tangram game
  * functionality for jsPsych plugins. It handles all aspects of the game
  * including piece interaction, collision detection, completion validation,
  * and data collection.
- * 
+ *
  * ## Key Responsibilities
  * - Creates and manages BaseGameController for state management
- * - Computes layout geometry for board rendering  
+ * - Computes layout geometry for board rendering
  * - Handles event callbacks for plugin integration
  * - Manages CSS sizing for responsive display
- * 
+ *
  * ## State Management
  * Uses BaseGameController internally which provides:
  * - Piece placement and validation
  * - Sector completion tracking
  * - Event logging for data collection
  * - Collision detection and snapping
- * 
+ *
  * @param props - Configuration and event callbacks for the game
  * @returns React component rendering the complete tangram game interface
  */
@@ -266,12 +284,15 @@ export default function GameBoard(props: GameBoardProps) {
     onPieceRemove,
     onInteraction,
     onTrialEnd,
-    onControllerReady
+    onControllerReady,
+    usePrimitiveColorsBlueprints,
+    usePrimitiveColorsTargets,
+    primitiveColorIndices,
   } = props;
-  
+
   // Timer state for countdown
   const [timeRemaining, setTimeRemaining] = React.useState(timeLimitMs > 0 ? Math.floor(timeLimitMs / 1000) : 0);
-  
+
   // Initialize game controller with injected data
   const controller = React.useMemo(() => {
     const gameConfig = {
@@ -286,11 +307,11 @@ export default function GameBoard(props: GameBoardProps) {
       ...(props.minPiecesPerMacro !== undefined && { minPiecesPerMacro: props.minPiecesPerMacro }),
       ...(props.requireAllSlots !== undefined && { requireAllSlots: props.requireAllSlots })
     };
-    
+
     return new BaseGameController(
       sectors,
       quickstash,
-      primitives, 
+      primitives,
       gameConfig
     );
   }, [sectors, quickstash, primitives, layoutMode, target, input, timeLimitMs, maxQuickstashSlots, maxCompositeSize, mode, props.minPiecesPerMacro, props.requireAllSlots]);
@@ -322,12 +343,12 @@ export default function GameBoard(props: GameBoardProps) {
     };
   }, [tracker]);
 
-  // Compute layout geometry  
+  // Compute layout geometry
   const { layout, viewBox } = React.useMemo(() => {
     const nSectors = sectors.length;
     const sectorIds = sectors.map(s => s.id);
     const masksPerSector: Poly[][] = sectors.map(s => s.silhouette.mask ?? []);
-    
+
     const logicalBox = solveLogicalBox({
       n: nSectors,
       layoutMode,
@@ -337,7 +358,7 @@ export default function GameBoard(props: GameBoardProps) {
       layoutPadPx: CONFIG.layout.paddingPx,
       masks: masksPerSector,
     });
-    
+
     const layout = computeCircleLayout(
       { w: logicalBox.LOGICAL_W, h: logicalBox.LOGICAL_H },
       nSectors,
@@ -350,7 +371,7 @@ export default function GameBoard(props: GameBoardProps) {
         masks: masksPerSector,
       }
     );
-    
+
     return {
       layout,
       viewBox: { w: logicalBox.LOGICAL_W, h: logicalBox.LOGICAL_H }
@@ -366,10 +387,10 @@ export default function GameBoard(props: GameBoardProps) {
       onControllerReady(controller, layout, force);
     }
   }, [controller, layout, onControllerReady, force]);
-  
+
   // Game completion tracking
   const [gameCompleted, setGameCompleted] = React.useState(false);
-  
+
   // Watch for game completion
   React.useEffect(() => {
     const checkGameCompletion = () => {
@@ -393,21 +414,21 @@ export default function GameBoard(props: GameBoardProps) {
     // Check completion whenever controller state updates
     checkGameCompletion();
   }, [controller.updateCount, sectors, gameCompleted, controller, tracker]);
-  
+
   // Sector completion callback
   const handleSectorComplete = React.useCallback((sectorId: string) => {
     if (onSectorComplete) {
       onSectorComplete(sectorId, controller.snapshot());
     }
   }, [onSectorComplete, controller]);
-  
+
   // Event callbacks for plugin integration
   const eventCallbacks = React.useMemo(() => ({
     onSectorComplete: handleSectorComplete,
     onPiecePlace: onPiecePlace || (() => {}),
     onPieceRemove: onPieceRemove || (() => {})
   }), [handleSectorComplete, onPiecePlace, onPieceRemove]);
-  
+
   // Calculate sizing based on layout mode
   const getGameboardStyle = () => {
     const baseStyle = {
@@ -560,14 +581,14 @@ export default function GameBoard(props: GameBoardProps) {
     tracker // Pass tracker for data collection
   );
 
-  const { 
-    draggingId, 
-    dragInvalid, 
-    svgRef, 
-    onPiecePointerDown, 
-    onBlueprintPointerDown, 
-    onPointerMove, 
-    onPointerUp, 
+  const {
+    draggingId,
+    dragInvalid,
+    svgRef,
+    onPiecePointerDown,
+    onBlueprintPointerDown,
+    onPointerMove,
+    onPointerUp,
     setPieceRef,
     setDraggingId,
     lockedPieceId,
@@ -640,7 +661,7 @@ export default function GameBoard(props: GameBoardProps) {
   // Timer effect
   React.useEffect(() => {
     if (timeLimitMs === 0) return;
-    
+
     const interval = setInterval(() => {
       setTimeRemaining(prev => {
         if (prev <= 1) {
@@ -650,7 +671,7 @@ export default function GameBoard(props: GameBoardProps) {
         return prev - 1;
       });
     }, 1000);
-    
+
     return () => clearInterval(interval);
   }, [timeLimitMs]);
 
@@ -669,27 +690,38 @@ export default function GameBoard(props: GameBoardProps) {
     // minHeight: '100vh'
   };
 
-  // Header style
+  // Header style (constrained to gameboard width)
   const headerStyle: React.CSSProperties = {
     display: 'flex',
     flexDirection: 'row',
-    justifyContent: 'space-between',
+    justifyContent: 'center',
     alignItems: 'center',
     padding: '20px',
-    background: '#f5f5f5',
+    background: CONFIG.color.background,
     flex: '0 0 auto'
   };
 
-  // Instructions style
+  // Header content wrapper (matches gameboard width)
+  const headerContentStyle: React.CSSProperties = {
+    position: 'relative',
+    width: `${svgDimensions.width}px`,
+    maxWidth: '100%',
+    display: 'flex',
+    justifyContent: 'center',
+    alignItems: 'center'
+  };
+
+  // Instructions style (always centered)
   const instructionsStyle: React.CSSProperties = {
-    flexGrow: 1,
     fontSize: '20px',
     lineHeight: 1.5,
-    marginRight: '20px'
+    textAlign: 'center'
   };
 
-  // Timer style
+  // Timer style (positioned absolutely to not affect centering)
   const timerStyle: React.CSSProperties = {
+    position: 'absolute',
+    right: 0,
     fontSize: '24px',
     fontWeight: 'bold',
     fontFamily: 'monospace',
@@ -711,18 +743,20 @@ export default function GameBoard(props: GameBoardProps) {
     <div className="tangram-trial-container" style={containerStyle}>
       {(instructions || timeLimitMs > 0) && (
         <div className="tangram-header" style={headerStyle}>
-          {instructions && (
-            <div 
-              className="tangram-instructions" 
-              style={instructionsStyle}
-              dangerouslySetInnerHTML={{ __html: instructions }} 
-            />
-          )}
-          {timeLimitMs > 0 && (
-            <div className="tangram-timer" style={timerStyle}>
-              {formatTime(timeRemaining)}
-            </div>
-          )}
+          <div className="tangram-header-content" style={headerContentStyle}>
+            {instructions && (
+              <div
+                className="tangram-instructions"
+                style={instructionsStyle}
+                dangerouslySetInnerHTML={{ __html: instructions }}
+              />
+            )}
+            {timeLimitMs > 0 && (
+              <div className="tangram-timer" style={timerStyle}>
+                {formatTime(timeRemaining)}
+              </div>
+            )}
+          </div>
         </div>
       )}
       <div className="tangram-gameboard-wrapper" style={gameboardWrapperStyle}>
@@ -753,6 +787,9 @@ export default function GameBoard(props: GameBoardProps) {
         onCenterBadgePointerDown={onCenterBadgePointerDown}
         showTangramDecomposition={showTangramDecomposition ?? false}
         scaleS={scaleS}
+        usePrimitiveColorsBlueprints={usePrimitiveColorsBlueprints ?? false}
+        usePrimitiveColorsTargets={usePrimitiveColorsTargets ?? false}
+        primitiveColorIndices={primitiveColorIndices ?? [0, 1, 2, 3, 4]}
         {...eventCallbacks}
       />
         </div>
@@ -779,7 +816,7 @@ export function useGameBoard(config: GameBoardConfig) {
       ...(config.minPiecesPerMacro !== undefined && { minPiecesPerMacro: config.minPiecesPerMacro }),
       ...(config.requireAllSlots !== undefined && { requireAllSlots: config.requireAllSlots })
     };
-    
+
     return new BaseGameController(
       config.sectors,
       config.quickstash,
@@ -787,12 +824,12 @@ export function useGameBoard(config: GameBoardConfig) {
       gameConfig
     );
   }, [config]);
-  
-  const snapshot = React.useMemo(() => 
-    controller.snapshot(), 
+
+  const snapshot = React.useMemo(() =>
+    controller.snapshot(),
     [controller.updateCount]
   );
-  
+
   return {
     controller,
     snapshot,