jspsych-tangram 0.0.1

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

@@ -0,0 +1,682 @@
+/**
+ * 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, 
+ *   primitives: PRIMITIVE_BLUEPRINTS,
+ *   layout: "semicircle",
+ *   target: "silhouette",
+ *   input: "drag",
+ *   onComplete: handleTrialComplete
+ * }));
+ * ```
+ * 
+ * @see {@link BaseGameController} For state management details
+ * @see {@link Board} For rendering implementation
+ * @since Phase 3.3 - Extracted from monolithic Board component
+ * @author Claude Code Assistant
+ */
+
+import React from "react";
+import { BaseGameController } from "@/core/engine/state/BaseGameController";
+import type { 
+  Sector, 
+  Blueprint, 
+  PrimitiveBlueprint,
+  LayoutMode,
+  PlacementTarget,
+  InputMode
+} from "@/core/domain/types";
+import { computeCircleLayout, rectForBand } from "@/core/domain/layout";
+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, 
+  placeSilhouetteGridAlignedAsPolys } from "@/core/engine/geometry";
+import { anchorsSilhouetteComplete, anchorsWorkspaceComplete } from "@/core/engine/validation/complete";
+import { scalePolys } from "@/core/components/board/utils";
+import { usePieceState } from "@/core/components/board/usePieceState";
+import { useAnchorGrid } from "@/core/components/board/useAnchorGrid";
+import { useDragController } from "@/core/components/board/useDragController";
+import { useClickController } from "@/core/components/board/useClickController";
+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 
+ * 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;
+  
+  /** Optional CSS width for the game board SVG */
+  width?: number;
+  
+  /** Optional CSS height for the game board SVG */
+  height?: number;
+}
+
+/**
+ * Props interface for GameBoard component, extending configuration with event callbacks
+ *
+ * This interface includes all configuration options plus optional event handlers
+ * that plugins can use to respond to game events and collect data.
+ */
+export interface GameBoardProps extends GameBoardConfig {
+  /**
+   * Called when an individual sector is completed
+   * Useful for tracking progress through multi-sector trials
+   */
+  onSectorComplete?: (sectorId: string, snapshot: any) => void;
+
+  /**
+   * Called when a piece is successfully placed in a sector
+   * Useful for real-time interaction tracking
+   */
+  onPiecePlace?: (pieceId: string, sectorId: string) => void;
+
+  /**
+   * Called when a piece is removed from a sector
+   * Useful for tracking piece manipulation patterns
+   */
+  onPieceRemove?: (pieceId: string) => void;
+
+  /**
+   * Called immediately after each complete interaction (piece pickup + placedown)
+   * Use for incremental data saving (e.g., socket.emit())
+   */
+  onInteraction?: (event: any) => void;
+
+  /**
+   * Called once when trial ends
+   * Contains complete interaction history + final state
+   * This is the primary mechanism for trial completion - plugins should handle
+   * React cleanup and jsPsych.finishTrial() in their wrapper for this callback
+   */
+  onTrialEnd?: (data: any) => void;
+
+  /**
+   * Called when the game controller is ready
+   * Useful for spawning initial pieces or setting up state
+   */
+  onControllerReady?: (controller: BaseGameController, layout?: any, force?: () => void) => void;
+}
+
+/**
+ * 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  
+ * - 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
+ */
+export default function GameBoard(props: GameBoardProps) {
+  const {
+    sectors,
+    quickstash,
+    primitives,
+    layout: layoutMode,
+    target,
+    input,
+    timeLimitMs,
+    maxQuickstashSlots,
+    maxCompositeSize,
+    mode,
+    width: _width,
+    height: _height,
+    onSectorComplete,
+    onPiecePlace,
+    onPieceRemove,
+    onInteraction,
+    onTrialEnd,
+    onControllerReady
+  } = props;
+  
+  // Initialize game controller with injected data
+  const controller = React.useMemo(() => {
+    const gameConfig = {
+      n: sectors.length,
+      layout: layoutMode,
+      target,
+      input,
+      timeLimitMs,
+      maxQuickstashSlots,
+      ...(maxCompositeSize !== undefined && { maxCompositeSize }),
+      mode: mode || "construction", // Default to construction mode for backwards compatibility
+      ...(props.minPiecesPerMacro !== undefined && { minPiecesPerMacro: props.minPiecesPerMacro }),
+      ...(props.requireAllSlots !== undefined && { requireAllSlots: props.requireAllSlots })
+    };
+    
+    return new BaseGameController(
+      sectors,
+      quickstash,
+      primitives, 
+      gameConfig
+    );
+  }, [sectors, quickstash, primitives, layoutMode, target, input, timeLimitMs, maxQuickstashSlots, maxCompositeSize, mode, props.minPiecesPerMacro, props.requireAllSlots]);
+
+  // Initialize interaction tracker for data collection (if callbacks provided)
+  const tracker = React.useMemo(() => {
+    if (!onInteraction && !onTrialEnd) return null;
+
+    const callbacks: { onInteraction?: (event: any) => void; onTrialEnd?: (data: any) => void } = {};
+    if (onInteraction) callbacks.onInteraction = onInteraction;
+    if (onTrialEnd) callbacks.onTrialEnd = onTrialEnd;
+
+    return new InteractionTracker(controller, callbacks);
+  }, [controller, onInteraction, onTrialEnd]);
+
+  // Call onControllerReady when controller is ready
+  React.useEffect(() => {
+    if (onControllerReady) {
+      onControllerReady(controller);
+    }
+  }, [controller, onControllerReady]);
+
+  // Cleanup tracker on unmount
+  React.useEffect(() => {
+    return () => {
+      if (tracker) {
+        tracker.dispose();
+      }
+    };
+  }, [tracker]);
+
+  // 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,
+      target,
+      qsMaxSlots: maxQuickstashSlots,
+      primitivesSlots: primitives.length,
+      layoutPadPx: CONFIG.layout.paddingPx,
+      masks: masksPerSector,
+    });
+    
+    const layout = computeCircleLayout(
+      { w: logicalBox.LOGICAL_W, h: logicalBox.LOGICAL_H },
+      nSectors,
+      sectorIds,
+      layoutMode,
+      target,
+      {
+        qsMaxSlots: maxQuickstashSlots,
+        primitivesSlots: primitives.length,
+        masks: masksPerSector,
+      }
+    );
+    
+    return {
+      layout,
+      viewBox: { w: logicalBox.LOGICAL_W, h: logicalBox.LOGICAL_H }
+    };
+  }, [sectors, layoutMode, target, maxQuickstashSlots, primitives.length]);
+
+  // Force re-render utility
+  const [, force] = React.useReducer((x) => x + 1, 0);
+
+  // Call onControllerReady when controller and layout are ready
+  React.useEffect(() => {
+    if (onControllerReady) {
+      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 = () => {
+      const allSectorsComplete = sectors.every(s =>
+        controller.isSectorCompleted(s.id)
+      );
+
+      if (allSectorsComplete && !gameCompleted) {
+        setGameCompleted(true);
+
+        // Finalize trial data tracking (which calls onTrialEnd)
+        if (tracker) {
+          tracker.finalizeTrial('auto_complete');
+        }
+      }
+    };
+
+    // 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 = {
+      margin: '0 auto',
+      display: 'flex',
+      alignItems: 'center',
+      justifyContent: 'center',
+      position: 'relative' as const,
+    };
+
+    if (layoutMode === 'circle') {
+      // Circle mode: square aspect ratio (height == width)
+      const size = Math.min(window.innerWidth * 0.96, window.innerHeight * 0.96);
+      return {
+        ...baseStyle,
+        width: `${size}px`,
+        height: `${size}px`,
+      };
+    } else {
+      // Semicircle mode: width is 2x height
+      const maxWidth = Math.min(window.innerWidth * 0.96, window.innerHeight * 0.96 * 2);
+      const maxHeight = Math.min(window.innerWidth * 0.96 / 2, window.innerHeight * 0.96);
+      return {
+        ...baseStyle,
+        width: `${maxWidth}px`,
+        height: `${maxHeight}px`,
+      };
+    }
+  };
+
+  // Calculate SVG dimensions to pass to Board component
+  const getSvgDimensions = () => {
+    if (layoutMode === 'circle') {
+      // Circle mode: square aspect ratio (height == width)
+      const size = Math.min(window.innerWidth * 0.96, window.innerHeight * 0.96);
+      return { width: size, height: size };
+    } else {
+      // Semicircle mode: width is 2x height
+      const maxWidth = Math.min(window.innerWidth * 0.96, window.innerHeight * 0.96 * 2);
+      const maxHeight = Math.min(window.innerWidth * 0.96 / 2, window.innerHeight * 0.96);
+      return { width: maxWidth, height: maxHeight };
+    }
+  };
+
+  const svgDimensions = getSvgDimensions();
+
+  React.useEffect(() => {
+    if (controller.state.cfg.mode !== "construction") return;
+    if (!timeLimitMs || timeLimitMs <= 0) return;
+    if (gameCompleted) return;
+
+    const timeoutId = window.setTimeout(() => {
+      if (gameCompleted) return;
+
+      if (!controller.state.endedAt) {
+        controller.state.endedAt = performance.now();
+        force();
+      }
+
+      tracker?.finalizeTrial('timeout');
+      setGameCompleted(true);
+    }, timeLimitMs);
+
+    return () => {
+      window.clearTimeout(timeoutId);
+    };
+  }, [controller, timeLimitMs, gameCompleted, tracker, force]);
+
+  const isSectorLocked = (id: string) => controller.isSectorCompleted(id);
+
+  // Extract piece management to custom hook
+  const { pieces, pieceById, getSectorPiecePolysCached } = usePieceState(controller);
+
+  const clickMode = controller.state.cfg.input === "click";
+
+  // Center badge geometry (visual + click target are identical)
+  const badgeR = Math.max(CONFIG.size.centerBadge.minPx, layout.innerR * CONFIG.size.centerBadge.fractionOfOuterR);
+  const badgeCenter = (controller.state.cfg.layout === "semicircle")
+    ? { x: layout.cx, y: layout.cy - badgeR - CONFIG.size.centerBadge.marginPx }
+    : { x: layout.cx, y: layout.cy };
+  const isInsideBadge = (px: number, py: number) =>
+    Math.hypot(px - badgeCenter.x, py - badgeCenter.y) <= badgeR;
+
+  // All sector masks (raw)
+  const allMasks: Poly[][] = React.useMemo(() => {
+    return controller.state.cfg.sectors.map(sec => (sec.silhouette.mask ?? []));
+  }, [controller.state.cfg.sectors]);
+
+  // Canonical lattice scale: 1 raw UNIT → CONFIG.layout.grid.unitPx (so a unit edge = 2 grid nodes)
+  // Keep a single scale so lattice density stays invariant across devices/zoom levels.
+  const scaleS = React.useMemo(() => {
+    const u = inferUnitFromPolys(allMasks.flat());
+    return u ? (CONFIG.layout.grid.unitPx / u) : 1;
+  }, [allMasks]);
+
+  // Extract anchor grid logic to custom hook
+  const { anchorDots } = useAnchorGrid(controller, layout, scaleS);
+
+  // Placed silhouettes per sector (grid-aligned polys used for inclusion tests)
+  const placedSilBySector = React.useMemo(() => {
+    const m = new Map<string, Poly[]>();
+    for (const s of layout.sectors) {
+      const mask = controller.state.cfg.sectors.find(ss => ss.id === s.id)?.silhouette.mask ?? [];
+      if (!mask?.length) continue;
+      const rect = rectForBand(layout, s, "silhouette", 1.0);
+      const placed = placeSilhouetteGridAlignedAsPolys(mask, scaleS, { cx: rect.cx, cy: rect.cy });
+      m.set(s.id, placed);
+    }
+    return m;
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [layout, scaleS, controller.state.cfg.sectors]);
+
+  const maybeCompleteSector = (secId: string): boolean => {
+    if (!secId) return false;
+    if (isSectorLocked(secId)) return false;
+
+    if (controller.state.cfg.target === "silhouette") {
+      const sil = placedSilBySector.get(secId) ?? [];
+      if (!sil.length) return false;
+      const piecePolys = getSectorPiecePolysCached(secId);
+      if (anchorsSilhouetteComplete(sil, piecePolys)) {
+        controller.markSectorCompleted(secId);
+        return true;
+      }
+    } else {
+      const raw = controller.state.cfg.sectors.find(ss => ss.id === secId)?.silhouette.mask ?? [];
+      if (!raw.length) return false;
+      const scaledSil = scalePolys(raw, scaleS);
+      const piecePolys = getSectorPiecePolysCached(secId);
+      if (anchorsWorkspaceComplete(scaledSil, piecePolys)) {
+        controller.markSectorCompleted(secId);
+        return true;
+      }
+    }
+    return false;
+  };
+
+  // ---- drag (RAF) - Extracted to useDragController hook ---
+  const dragController = useDragController(
+    controller,
+    layout,
+    pieces,
+    pieceById,
+    anchorDots,
+    placedSilBySector,
+    isSectorLocked,
+    maybeCompleteSector,
+    force,
+    undefined, // clickController - will be set later
+    tracker // Pass tracker for data collection
+  );
+
+  const { 
+    draggingId, 
+    dragInvalid, 
+    svgRef, 
+    onPiecePointerDown, 
+    onBlueprintPointerDown, 
+    onPointerMove, 
+    onPointerUp, 
+    setPieceRef,
+    setDraggingId,
+    lockedPieceId,
+    dragRef  // TODO: Remove once click mode is extracted
+  } = dragController;
+
+  // ---- CLICK controller - Extracted click mode logic ---
+  const svgPoint = (clientX: number, clientY: number) => {
+    const svg = svgRef.current!;
+    const pt = svg.createSVGPoint();
+    pt.x = clientX; pt.y = clientY;
+    const ctm = svg.getScreenCTM();
+    if (!ctm) return { x: 0, y: 0 };
+    const sp = pt.matrixTransform(ctm.inverse());
+    return { x: sp.x, y: sp.y };
+  };
+
+  const clickController = useClickController(
+    controller,
+    layout,
+    pieces,
+    clickMode,
+    draggingId,
+    setDraggingId,
+    dragRef,
+    isInsideBadge,
+    isSectorLocked,
+    maybeCompleteSector,
+    svgPoint,
+    force,
+    tracker // Pass tracker for data collection
+  );
+
+  const {
+    selectedPieceId,
+    onRootPointerDown
+  } = clickController;
+
+  const onCenterBadgePointerDown = (e: React.PointerEvent) => {
+    if (draggingId) return;
+    const { x, y } = svgPoint(e.clientX, e.clientY);
+
+    if (controller.state.cfg.mode === "prep") {
+      if (!controller.isSubmitEnabled() || gameCompleted) {
+        e.stopPropagation();
+        return;
+      }
+
+      setGameCompleted(true);
+      if (tracker) {
+        tracker.finalizeTrial('submit');
+      }
+      e.stopPropagation();
+      return;
+    }
+
+    // Construction mode: toggle blueprint view
+    if (tracker?.recordClickEvent) {
+      const from = controller.state.blueprintView;
+      const to = from === "primitives" ? "quickstash" : "primitives";
+      tracker.recordClickEvent({ x, y }, 'blueprint_view_switch', {
+        blueprintViewSwitch: { from, to }
+      });
+    }
+    controller.switchBlueprintView();
+    force();
+    e.stopPropagation();
+  };
+
+  return (
+    <div className="tangram-gameboard" style={getGameboardStyle()}>
+      <BoardView
+        controller={controller}
+        layout={layout}
+        viewBox={viewBox}
+        width={svgDimensions.width}
+        height={svgDimensions.height}
+        badgeR={badgeR}
+        badgeCenter={badgeCenter}
+        placedSilBySector={placedSilBySector}
+        anchorDots={anchorDots as DotsType[]}
+        pieces={pieces}
+        clickMode={clickMode}
+        draggingId={draggingId}
+        selectedPieceId={selectedPieceId}
+        dragInvalid={dragInvalid}
+        lockedPieceId={lockedPieceId}
+        svgRef={svgRef}
+        setPieceRef={setPieceRef}
+        onPiecePointerDown={onPiecePointerDown}
+        onBlueprintPointerDown={onBlueprintPointerDown}
+        onRootPointerDown={onRootPointerDown}
+        onPointerMove={onPointerMove}
+        onPointerUp={onPointerUp}
+        onCenterBadgePointerDown={onCenterBadgePointerDown}
+        {...eventCallbacks}
+      />
+    </div>
+  );
+}
+
+/**
+ * Hook for managing GameBoard state externally
+ * Useful for plugins that need direct access to game state
+ */
+export function useGameBoard(config: GameBoardConfig) {
+  const controller = React.useMemo(() => {
+    const gameConfig = {
+      n: config.sectors.length,
+      layout: config.layout,
+      target: config.target,
+      input: config.input,
+      timeLimitMs: config.timeLimitMs,
+      maxQuickstashSlots: config.maxQuickstashSlots,
+      ...(config.maxCompositeSize !== undefined && { maxCompositeSize: config.maxCompositeSize }),
+      mode: config.mode || "construction",
+      ...(config.minPiecesPerMacro !== undefined && { minPiecesPerMacro: config.minPiecesPerMacro }),
+      ...(config.requireAllSlots !== undefined && { requireAllSlots: config.requireAllSlots })
+    };
+    
+    return new BaseGameController(
+      config.sectors,
+      config.quickstash,
+      config.primitives,
+      gameConfig
+    );
+  }, [config]);
+  
+  const snapshot = React.useMemo(() => 
+    controller.snapshot(), 
+    [controller.updateCount]
+  );
+  
+  return {
+    controller,
+    snapshot,
+    isComplete: !!controller.state.endedAt
+  };
+}