react-native-chess-kit 0.1.0

package/src/types.ts

@@ -0,0 +1,114 @@
+import type { SharedValue } from 'react-native-reanimated';
+
+// ---------------------------------------------------------------------------
+// Core chess types
+// ---------------------------------------------------------------------------
+
+/** Board orientation / side color */
+export type ChessColor = 'white' | 'black';
+
+/** How the user interacts with pieces */
+export type MoveMethod = 'drag' | 'click' | 'both';
+
+// ---------------------------------------------------------------------------
+// Piece data
+// ---------------------------------------------------------------------------
+
+/** A single piece on the board with its position and identity */
+export type BoardPiece = {
+  /** Unique stable identifier (survives position changes): e.g. "wp-0", "bk-0" */
+  id: string;
+  /** Piece code matching standard notation: 'wp', 'wn', 'wb', 'wr', 'wq', 'wk', 'bp', etc. */
+  code: string;
+  /** Current square in algebraic notation: 'a1'..'h8' */
+  square: string;
+  /** 'w' or 'b' */
+  color: 'w' | 'b';
+};
+
+/** Intermediate representation from FEN parsing (before ID assignment) */
+export type ParsedPiece = {
+  code: string;
+  square: string;
+  color: 'w' | 'b';
+};
+
+// ---------------------------------------------------------------------------
+// Board ref (exposed to consumers via forwardRef)
+// ---------------------------------------------------------------------------
+
+export type BoardRef = {
+  /** Pre-apply a move to internal state. Visual animation happens when parent updates the FEN prop. */
+  move: (move: { from: string; to: string }) => void;
+  /** Highlight a square with a color */
+  highlight: (square: string, color: string) => void;
+  /** Clear all imperative highlights */
+  clearHighlights: () => void;
+  /** Reset board to a new FEN position */
+  resetBoard: (fen: string) => void;
+  /** Undo the last visually applied move (snap back to previous position) */
+  undo: () => void;
+};
+
+// ---------------------------------------------------------------------------
+// Board props
+// ---------------------------------------------------------------------------
+
+export type BoardColors = {
+  light: string;
+  dark: string;
+};
+
+export type BoardProps = {
+  /** Current board position in FEN notation */
+  fen: string;
+  /** Which color is at the bottom of the board */
+  orientation: ChessColor;
+  /** Board width/height in pixels */
+  boardSize: number;
+  /** Whether gesture interaction is enabled */
+  gestureEnabled: boolean;
+  /** Which side can interact: 'white', 'black', or 'both' */
+  player: ChessColor | 'both';
+  /** Called after a visual move is applied */
+  onMove?: (info: { from: string; to: string }) => void;
+  /** Board square colors */
+  colors: BoardColors;
+  /** Move animation duration in ms (0 = instant) */
+  moveDuration: number;
+  /** Whether to show file labels (a-h) */
+  withLetters: boolean;
+  /** Whether to show rank numbers (1-8) */
+  withNumbers: boolean;
+  /** Custom piece renderer. Receives piece code ('wp', 'bk', etc.) and pixel size. */
+  renderPiece?: (pieceCode: string, size: number) => React.ReactElement;
+  /** Whether to show legal move dots when a piece is selected */
+  showLegalMoves: boolean;
+  /** How the user moves pieces */
+  moveMethod: MoveMethod;
+};
+
+// ---------------------------------------------------------------------------
+// Gesture shared values (internal, but exported for advanced overlay use)
+// ---------------------------------------------------------------------------
+
+export type GestureState = {
+  /** Square the active piece started from (null if no drag/selection) */
+  activeSquare: SharedValue<string | null>;
+  /** Current drag position in board-local pixels */
+  dragX: SharedValue<number>;
+  dragY: SharedValue<number>;
+  /** Whether a drag gesture is currently active */
+  isDragging: SharedValue<boolean>;
+  /** The piece code being dragged (for rendering the ghost) */
+  dragPieceCode: SharedValue<string | null>;
+};
+
+// ---------------------------------------------------------------------------
+// Legal move dots
+// ---------------------------------------------------------------------------
+
+export type LegalMoveTarget = {
+  square: string;
+  isCapture: boolean;
+};

package/src/use-board-gesture.ts

@@ -0,0 +1,201 @@
+import { useMemo, useCallback, useRef } from 'react';
+import { Gesture } from 'react-native-gesture-handler';
+import {
+  useSharedValue,
+  runOnJS,
+} from 'react-native-reanimated';
+
+import type { ChessColor, MoveMethod, BoardPiece, LegalMoveTarget, GestureState } from './types';
+import { xyToSquare } from './use-board-pieces';
+
+type GestureCallbacks = {
+  onPieceSelected: (square: string) => void;
+  onPieceMoved: (from: string, to: string) => void;
+  onSelectionCleared: () => void;
+};
+
+type UseBoardGestureParams = {
+  squareSize: number;
+  orientation: ChessColor;
+  gestureEnabled: boolean;
+  player: ChessColor | 'both';
+  moveMethod: MoveMethod;
+  pieces: BoardPiece[];
+  callbacks: GestureCallbacks;
+  /** Currently selected square (for tap-to-move second tap) */
+  selectedSquare: string | null;
+  /** Legal move targets from the currently selected piece */
+  legalMoves: LegalMoveTarget[];
+};
+
+type UseBoardGestureReturn = {
+  gesture: ReturnType<typeof Gesture.Pan>;
+  gestureState: GestureState;
+};
+
+/**
+ * Single centralized gesture handler for the entire board.
+ *
+ * Instead of 32 separate Gesture.Pan() handlers (one per piece), we use ONE
+ * handler on the board container. Touch -> coordinate math -> which piece.
+ *
+ * Supports three modes:
+ * - 'drag': drag piece to target square
+ * - 'click': tap source piece, then tap target square
+ * - 'both': drag or click (default)
+ *
+ * All drag position tracking uses shared values — zero JS bridge calls,
+ * zero re-renders during drag. Only the final move triggers JS via runOnJS.
+ *
+ * The gesture object is STABLE (only recreated when squareSize, orientation,
+ * gestureEnabled, player, or moveMethod change). Frequently-changing data
+ * (pieces, selectedSquare, legalMoves) is read from refs via runOnJS bridge
+ * functions, avoiding costly gesture teardown/rebuild on every move.
+ */
+export function useBoardGesture({
+  squareSize,
+  orientation,
+  gestureEnabled,
+  player,
+  moveMethod,
+  pieces,
+  callbacks,
+  selectedSquare,
+  legalMoves,
+}: UseBoardGestureParams): UseBoardGestureReturn {
+  // Shared values for drag tracking — updated on UI thread only
+  const activeSquare = useSharedValue<string | null>(null);
+  const dragX = useSharedValue(0);
+  const dragY = useSharedValue(0);
+  const isDragging = useSharedValue(false);
+  const dragPieceCode = useSharedValue<string | null>(null);
+
+  const gestureState: GestureState = {
+    activeSquare,
+    dragX,
+    dragY,
+    isDragging,
+    dragPieceCode,
+  };
+
+  // --- Refs for frequently-changing data (read from JS thread via runOnJS) ---
+  // These update every move but do NOT cause gesture object recreation.
+  const piecesRef = useRef(pieces);
+  piecesRef.current = pieces;
+
+  const selectedSquareRef = useRef(selectedSquare);
+  selectedSquareRef.current = selectedSquare;
+
+  const legalMovesRef = useRef(legalMoves);
+  legalMovesRef.current = legalMoves;
+
+  const callbacksRef = useRef(callbacks);
+  callbacksRef.current = callbacks;
+
+  // --- JS-thread bridge functions called from worklets via runOnJS ---
+  // These read current values from refs, so they always have fresh data.
+
+  const handleBegin = useCallback((touchX: number, touchY: number) => {
+    const square = xyToSquare(touchX, touchY, squareSize, orientation);
+    const currentPieces = piecesRef.current;
+    const currentSelected = selectedSquareRef.current;
+    const currentLegalMoves = legalMovesRef.current;
+    const cbs = callbacksRef.current;
+    const canClick = moveMethod !== 'drag';
+
+    // Build lookup for the current touch
+    const piece = currentPieces.find((p) => p.square === square);
+    const isPlayerPiece = piece
+      ? player === 'both' || (piece.color === 'w' ? 'white' : 'black') === player
+      : false;
+
+    // Click-to-move: second tap on a legal target square
+    const legalSquares = new Set(currentLegalMoves.map((m) => m.square));
+    if (canClick && currentSelected && legalSquares.has(square)) {
+      cbs.onPieceMoved(currentSelected, square);
+      activeSquare.value = null;
+      isDragging.value = false;
+      dragPieceCode.value = null;
+      return;
+    }
+
+    if (isPlayerPiece && piece) {
+      // Tapped/started dragging a player piece
+      activeSquare.value = square;
+      dragX.value = touchX;
+      dragY.value = touchY;
+      dragPieceCode.value = piece.code;
+      cbs.onPieceSelected(square);
+    } else {
+      // Tapped empty square or opponent piece — clear selection
+      activeSquare.value = null;
+      dragPieceCode.value = null;
+      if (currentSelected) {
+        cbs.onSelectionCleared();
+      }
+    }
+  }, [squareSize, orientation, player, moveMethod, activeSquare, dragX, dragY, isDragging, dragPieceCode]);
+
+  const handleEnd = useCallback((touchX: number, touchY: number) => {
+    const fromSquare = activeSquare.value;
+    if (!fromSquare) return;
+
+    const toSquare = xyToSquare(touchX, touchY, squareSize, orientation);
+    isDragging.value = false;
+
+    if (fromSquare !== toSquare) {
+      callbacksRef.current.onPieceMoved(fromSquare, toSquare);
+    }
+
+    activeSquare.value = null;
+    dragPieceCode.value = null;
+  }, [squareSize, orientation, activeSquare, isDragging, dragPieceCode]);
+
+  // --- Build the gesture (STABLE — only changes on layout/config changes) ---
+  const canDrag = moveMethod !== 'click';
+
+  const gesture = useMemo(() => {
+    return Gesture.Pan()
+      .enabled(gestureEnabled)
+      .minDistance(0) // Also detect taps (zero-distance pans)
+      .onBegin((e) => {
+        'worklet';
+        // Bridge to JS for piece lookup + selection logic
+        runOnJS(handleBegin)(e.x, e.y);
+      })
+      .onStart(() => {
+        'worklet';
+        if (!canDrag || !activeSquare.value) return;
+        isDragging.value = true;
+      })
+      .onUpdate((e) => {
+        'worklet';
+        if (!canDrag || !isDragging.value) return;
+        // Only 2 shared value writes — no JS bridge, no re-renders
+        dragX.value = e.x;
+        dragY.value = e.y;
+      })
+      .onEnd((e) => {
+        'worklet';
+        if (!isDragging.value || !activeSquare.value) return;
+        runOnJS(handleEnd)(e.x, e.y);
+      })
+      .onFinalize(() => {
+        'worklet';
+        // Safety reset if gesture was interrupted
+        isDragging.value = false;
+      });
+  }, [
+    gestureEnabled,
+    canDrag,
+    handleBegin,
+    handleEnd,
+    // Shared values are stable refs — listed for exhaustive-deps but don't cause recreations
+    activeSquare,
+    dragX,
+    dragY,
+    isDragging,
+  ]);
+
+  return { gesture, gestureState };
+}

package/src/use-board-pieces.ts

@@ -0,0 +1,158 @@
+import { useMemo, useRef } from 'react';
+
+import type { ChessColor, BoardPiece, ParsedPiece } from './types';
+
+const FEN_PIECE_MAP: Record<string, { code: string; color: 'w' | 'b' }> = {
+  p: { code: 'bp', color: 'b' },
+  r: { code: 'br', color: 'b' },
+  n: { code: 'bn', color: 'b' },
+  b: { code: 'bb', color: 'b' },
+  q: { code: 'bq', color: 'b' },
+  k: { code: 'bk', color: 'b' },
+  P: { code: 'wp', color: 'w' },
+  R: { code: 'wr', color: 'w' },
+  N: { code: 'wn', color: 'w' },
+  B: { code: 'wb', color: 'w' },
+  Q: { code: 'wq', color: 'w' },
+  K: { code: 'wk', color: 'w' },
+};
+
+const FILES = 'abcdefgh';
+
+/**
+ * Parse the piece-placement part of a FEN string into an array of pieces.
+ * Pure function — no React dependencies, suitable for worklets if needed.
+ */
+function parseFenPieces(fen: string): ParsedPiece[] {
+  const placement = fen.split(' ')[0];
+  const ranks = placement.split('/');
+  const pieces: ParsedPiece[] = [];
+
+  for (let rankIdx = 0; rankIdx < ranks.length; rankIdx++) {
+    const rank = ranks[rankIdx];
+    let fileIdx = 0;
+
+    for (const char of rank) {
+      if (char >= '1' && char <= '8') {
+        fileIdx += parseInt(char, 10);
+        continue;
+      }
+
+      const mapping = FEN_PIECE_MAP[char];
+      if (mapping) {
+        // FEN ranks are from rank 8 (index 0) down to rank 1 (index 7)
+        const square = `${FILES[fileIdx]}${8 - rankIdx}`;
+        pieces.push({ code: mapping.code, square, color: mapping.color });
+      }
+      fileIdx++;
+    }
+  }
+
+  return pieces;
+}
+
+/**
+ * Convert square notation to pixel coordinates (top-left corner).
+ * Orientation-aware: flips the board when playing as black.
+ */
+export function squareToXY(
+  square: string,
+  squareSize: number,
+  orientation: ChessColor,
+): { x: number; y: number } {
+  'worklet';
+  const fileIdx = square.charCodeAt(0) - 97; // 'a'=0 .. 'h'=7
+  const rankIdx = parseInt(square[1], 10) - 1; // '1'=0 .. '8'=7
+
+  const col = orientation === 'white' ? fileIdx : 7 - fileIdx;
+  const row = orientation === 'white' ? 7 - rankIdx : rankIdx;
+
+  return { x: col * squareSize, y: row * squareSize };
+}
+
+/**
+ * Convert pixel coordinates to a square notation string.
+ * Clamps to board bounds. Orientation-aware.
+ */
+export function xyToSquare(
+  x: number,
+  y: number,
+  squareSize: number,
+  orientation: ChessColor,
+): string {
+  'worklet';
+  const col = Math.max(0, Math.min(7, Math.floor(x / squareSize)));
+  const row = Math.max(0, Math.min(7, Math.floor(y / squareSize)));
+
+  const fileIdx = orientation === 'white' ? col : 7 - col;
+  const rankIdx = orientation === 'white' ? 7 - row : row;
+
+  // String.fromCharCode not available in worklets — use lookup
+  const files = 'abcdefgh';
+  return `${files[fileIdx]}${rankIdx + 1}`;
+}
+
+/**
+ * Manages the piece list derived from FEN, with stable IDs for React keys.
+ *
+ * Stable IDs prevent unmount/remount cycles when pieces change position.
+ * A piece keeps its ID as long as it exists on the board — only capture
+ * (removal) or promotion (code change) creates a new ID.
+ */
+export function useBoardPieces(fen: string): BoardPiece[] {
+  // Track piece-code counters across renders for stable ID assignment
+  const idCounterRef = useRef<Record<string, number>>({});
+  const prevPiecesRef = useRef<BoardPiece[]>([]);
+
+  return useMemo(() => {
+    const parsed = parseFenPieces(fen);
+    const prev = prevPiecesRef.current;
+    const prevBySquare = new Map(prev.map((p) => [p.square, p]));
+
+    // Try to reuse IDs from previous render:
+    // 1. Same code on same square -> keep ID (piece didn't move)
+    // 2. Same code moved to a new square -> find unmatched previous piece of same code
+    const usedPrevIds = new Set<string>();
+    const result: BoardPiece[] = [];
+
+    // First pass: exact square matches (piece stayed or appeared on same square)
+    const unmatched: ParsedPiece[] = [];
+    for (const p of parsed) {
+      const existing = prevBySquare.get(p.square);
+      if (existing && existing.code === p.code && !usedPrevIds.has(existing.id)) {
+        usedPrevIds.add(existing.id);
+        result.push({ ...p, id: existing.id });
+      } else {
+        unmatched.push(p);
+      }
+    }
+
+    // Second pass: match unmatched pieces by code to previous pieces that moved
+    for (const p of unmatched) {
+      let matchedId: string | null = null;
+
+      for (const prevPiece of prev) {
+        if (
+          prevPiece.code === p.code &&
+          !usedPrevIds.has(prevPiece.id)
+        ) {
+          matchedId = prevPiece.id;
+          usedPrevIds.add(prevPiece.id);
+          break;
+        }
+      }
+
+      if (matchedId) {
+        result.push({ ...p, id: matchedId });
+      } else {
+        // New piece (promotion, or first render) — assign fresh ID
+        const counter = idCounterRef.current;
+        counter[p.code] = (counter[p.code] ?? 0) + 1;
+        result.push({ ...p, id: `${p.code}-${counter[p.code]}` });
+      }
+    }
+
+    prevPiecesRef.current = result;
+    return result;
+  }, [fen]);
+}

package/src/use-board-state.ts

@@ -0,0 +1,104 @@
+import { useRef, useCallback } from 'react';
+import { Chess } from 'chess.js';
+import type { Square } from 'chess.js';
+
+import type { ChessColor, BoardPiece, LegalMoveTarget } from './types';
+
+type MoveResult = {
+  /** Whether the move was applied to the internal chess.js instance */
+  applied: boolean;
+  /** The new FEN after the move (if applied) */
+  fen?: string;
+};
+
+type BoardStateReturn = {
+  /** Get legal moves for a piece on the given square */
+  getLegalMoves: (square: string) => LegalMoveTarget[];
+  /** Check if a given square has a piece belonging to the active player */
+  isPlayerPiece: (square: string, pieces: BoardPiece[], player: ChessColor | 'both') => boolean;
+  /** Apply a move to the internal chess state. Returns the new FEN if valid. */
+  applyMove: (from: string, to: string, promotion?: string) => MoveResult;
+  /** Undo the last move on the internal chess state */
+  undoMove: () => string | null;
+  /** Load a new FEN into the internal chess state */
+  loadFen: (fen: string) => void;
+  /** Get the current FEN from internal state */
+  getFen: () => string;
+  /** Get the current turn from internal state */
+  getTurn: () => 'w' | 'b';
+};
+
+/**
+ * Manages the internal chess.js instance for legal move validation.
+ *
+ * This mirrors the visual board state. When the parent passes a new FEN,
+ * the internal chess.js is synced. Legal move queries and move application
+ * happen against this instance.
+ *
+ * The chess.js instance lives in a ref — no React state, no re-renders.
+ */
+export function useBoardState(initialFen: string): BoardStateReturn {
+  const chessRef = useRef<Chess>(null!);
+  if (!chessRef.current) chessRef.current = new Chess(initialFen);
+
+  const getLegalMoves = useCallback((square: string): LegalMoveTarget[] => {
+    try {
+      const moves = chessRef.current.moves({ square: square as Square, verbose: true });
+      return moves.map((m) => ({
+        square: m.to,
+        isCapture: m.captured !== undefined,
+      }));
+    } catch {
+      return [];
+    }
+  }, []);
+
+  const isPlayerPiece = useCallback(
+    (square: string, pieces: BoardPiece[], player: ChessColor | 'both'): boolean => {
+      const piece = pieces.find((p) => p.square === square);
+      if (!piece) return false;
+
+      if (player === 'both') return true;
+
+      const pieceColor: ChessColor = piece.color === 'w' ? 'white' : 'black';
+      return pieceColor === player;
+    },
+    [],
+  );
+
+  const applyMove = useCallback((from: string, to: string, promotion?: string): MoveResult => {
+    try {
+      chessRef.current.move({
+        from: from as Square,
+        to: to as Square,
+        promotion: promotion as 'q' | 'r' | 'b' | 'n' | undefined,
+      });
+      return { applied: true, fen: chessRef.current.fen() };
+    } catch {
+      return { applied: false };
+    }
+  }, []);
+
+  const undoMove = useCallback((): string | null => {
+    const result = chessRef.current.undo();
+    return result ? chessRef.current.fen() : null;
+  }, []);
+
+  const loadFen = useCallback((fen: string) => {
+    chessRef.current.load(fen);
+  }, []);
+
+  const getFen = useCallback(() => chessRef.current.fen(), []);
+
+  const getTurn = useCallback(() => chessRef.current.turn(), []);
+
+  return {
+    getLegalMoves,
+    isPlayerPiece,
+    applyMove,
+    undoMove,
+    loadFen,
+    getFen,
+    getTurn,
+  };
+}